Python reimplementation of the original Turbo Pascal Pohualli calendrical utility.
- Maya & Aztec core calculations (Tzolk'in, Haab, Long Count, Year Bearer)
- 819‑day cycle, planetary synodic helpers, zodiac & moon heuristics
- Correlation ("New Era") presets + on-the-fly overrides
- Auto-derivation of correction offsets from partial constraints
- Unified composite API & high-coverage test suite (≥90% per file)
- FastAPI web UI + CLI + JSON output
pip install pohualli
Include web extras (FastAPI UI) if you want the local server:
pip install "pohualli[web]"
PyPI: https://pypi.org/project/pohualli/
Download the pre-built bundle artifacts (App on macOS, MSI or app dir on Windows) from the Desktop Bundles workflow or a Release.
macOS first run (unsigned / ad‑hoc bundle):
- Move
Pohualli.appto/Applications(optional but typical). - Control‑click the app → Open → Open (this whitelists it in Gatekeeper).
- Browser opens automatically; if not, visit the printed
http://127.0.0.1:<port>.
Windows:
- Run the MSI or
Pohualli.exeinside the unpacked directory. - If SmartScreen warns, choose “More info” → “Run anyway”.
- Browser tab should appear automatically.
Updates: replace the old bundle with the new one (no persistent user data yet).
Latest release downloads: https://github.com/muscariello/pohualli-python/releases
git clone https://github.com/muscariello/pohualli-python.git
cd pohualli-python
pip install -e .[dev,web]
Then run CLI (pohualli ...) or web app (uvicorn pohualli.webapp:app --reload).
.
├── CHANGELOG.md # Project changelog / release notes
├── LICENSE # GPL-3.0-only license text
├── README.md # Overview & usage (this file)
├── docker-compose.yml # Convenience orchestration for web app
├── Dockerfile # Multi-arch container build definition
├── mkdocs.yml # MkDocs Material documentation config
├── pyproject.toml # Packaging & dependency metadata
├── docs/ # Documentation markdown sources (MkDocs)
│ ├── index.md # Landing page
│ ├── dev.md # Development & contributing notes
│ ├── license.md # License blurb for docs site
│ ├── concepts/ # Conceptual explanations
│ │ ├── calendars.md # Calendar systems overview
│ │ └── configuration.md # Correlations & correction parameters
│ └── usage/ # How-to guides
│ ├── quickstart.md # Quick installation & first run
│ ├── cli.md # CLI usage details
│ ├── desktop.md # Desktop bundles (Briefcase) guide
│ └── python-api.md # Python API examples
├── pohualli/
│ ├── __init__.py # Public API exports (compute_composite, etc.)
│ ├── __main__.py # Module entry point (python -m pohualli / bundle)
│ ├── autocorr.py # Derive correction offsets from constraints
│ ├── aztec.py # Aztec (Tonalpohualli) name tables & helpers
│ ├── calendar_dates.py # Gregorian/Julian conversions & weekday calc
│ ├── cli.py # Command line interface entry point
│ ├── composite.py # High-level composite computation orchestrator
│ ├── correlations.py # Correlation (New Era) preset definitions
│ ├── cycle819.py # 819‑day cycle station & direction colors
│ ├── desktop_app.py # Desktop launcher for packaged app (Briefcase)
│ ├── maya.py # Core Maya calendar math (Tzolk'in / Haab / LC)
│ ├── moon.py # Moon phase / anomaly heuristics
│ ├── planets.py # Planetary synodic value helpers
│ ├── templates/
│ │ └── index.html # Web UI Jinja2 template
│ ├── types.py # Dataclasses & global correction state types
│ ├── webapp.py # FastAPI application (async range jobs, endpoints)
│ ├── yearbear.py # Year Bearer packing/unpacking utilities
│ └── zodiac.py # Star & earth zodiac angle computations
└── tests/ # Pytest suite (broad branch coverage)
├── test_async_range_job.py # Async range job creation & polling
├── test_async_cancel_partial.py # Cancellation partial-results semantics
├── test_autocorr*.py # Auto-correction derivation & edge cases
├── test_cli_direct.py # Direct main() invocation basic paths
├── test_cli_early_filters_paths.py # Early filter continue branches (range)
├── test_cli_more.py # JSON output & new-era/year bearer refs
├── test_cli_no_subproc.py # CLI coverage without subprocess fork
├── test_cli_range_matrix.py # Combinatorial filter matrix (range)
├── test_cli_search_range*.py # Range search modes (table/json-lines)
├── test_cli_textual_branches.py # Textual from-jdn output branches
├── test_composite.py # Composite object field consistency
├── test_cycle_planets.py # 819-cycle & planetary helpers
├── test_desktop_app.py # Desktop launcher behavior
├── test_extra_cycles_yearbear_moon.py # Mixed composite cycle branches
├── test_maya*.py # Maya calendar arithmetic & validation
├── test_moon_zodiac.py # Moon + zodiac computations
├── test_web.py # Basic web endpoint checks
├── test_web_extra.py # Additional /api/convert / derive cases
├── test_web_range_job_extra.py # Range job edge cases & listing
├── test_webapp_internal.py # Internal helpers (_early_filters etc.)
├── test_webapp_filters_matrix.py # Each filter type in async jobs
├── test_webapp_more.py # Not-found, cancel-after-complete, culture
├── test_webapp_additional.py # Reversed ranges, invalid specs, limits
├── test_yearbear_cli.py # Year bearer & CLI integration
└── test_zodiac_extra.py # Additional zodiac heuristic coverage
Run Pohualli instantly in Google Colab (no local setup) with the interactive FastAPI UI and helper functions:
➡️ Open in Colab: https://colab.research.google.com/github/muscariello/pohualli-python/blob/main/notebooks/pohualli_colab.ipynb
The notebook will:
- Install required dependencies when launched on Colab.
- Start the FastAPI app in a background thread.
- Provide helper functions (
convert,derive) for programmatic use. - Offer instructions to expose the UI via
pyngrok(since Colab can't iframe localhost directly).
from pohualli import compute_composite
result = compute_composite(2451545)
print(result.tzolkin_name, result.long_count, result.star_zodiac_name)# Basic human-readable conversion
pohualli from-jdn 2451545
# Year Bearer reference override
pohualli from-jdn 2451545 --year-bearer-ref 0 0
# JSON output (pretty with jq)
pohualli from-jdn 2451545 --json | jq .long_count
# Override New Era just for this invocation
pohualli from-jdn 2451545 --new-era 584283 --json
# Apply a named correlation preset globally
pohualli apply-correlation gmt-584283
# List available correlations
pohualli list-correlations
# Derive corrections from partial constraint (tzolkin only)
pohualli derive-autocorr 2451545 --tzolkin "4 Ahau"
# Derive with multiple constraints (tzolkin + haab + g)
pohualli derive-autocorr 2451545 --tzolkin "4 Ahau" --haab "3 Pop" --g 5
# Persist and restore configuration
pohualli save-config config.json
pohualli load-config config.json
# Full JSON composite into a file
pohualli from-jdn 2451545 --json > composite.json
# Range search (scan inclusive JDN interval with filters)
# Find first 5 dates in a span whose Tzolkin name is Imix and Haab month is Cumhu
pohualli search-range 584283 584500 --tzolkin-name Imix --haab-month Cumhu --limit 5
# Long Count pattern matching (use * as wildcard for a component)
pohualli search-range 500000 600000 --long-count '9.*.*.*.*.*' --limit 3
# Output JSON lines (machine processing)
pohualli search-range 584283 584400 --tzolkin-value 4 --json-lines --limit 2
# Select custom output fields
pohualli search-range 584283 584400 --fields jdn,tzolkin_name,haab_month_name --limit 3
# Switch to Aztec year-bearer derivation (subtracts 364 days in interval logic)
pohualli from-jdn 2451545 --culture aztec --year-bearer-ref 0 0
# Range search in Aztec mode
pohualli search-range 584283 584400 --culture aztec --tzolkin-value 4 --limit 2
uvicorn pohualli.webapp:app --reload
docker build -t pohualli .
docker run --rm -p 8000:8000 pohualli
Or use the published image:
docker run --rm -p 8000:8000 ghcr.io/muscariello/pohualli-python:latest
pytest -q
GPL-3.0-only
The computation of the Year Bearer differs: in Aztec (tonalpohualli) mode the interval between the target Haab position and the reference is reduced by 364 days before deriving the bearer, shifting the resulting Tzolkin pair relative to Maya convention. Use --culture aztec (CLI) or the Culture dropdown in the web UI to toggle. Default is Maya.
Sołtysiak, A. & Lebeuf, A. (2011). Pohualli 1.01. A computer simulation of Mesoamerican calendar systems. 8(49), 165–168. ResearchGate