caltib 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. caltib-0.3.0/.github/workflows/docs.yml +40 -0
  2. caltib-0.3.0/.github/workflows/publish.yml +35 -0
  3. caltib-0.3.0/.gitignore +16 -0
  4. caltib-0.3.0/.vscode/settings.json +3 -0
  5. caltib-0.3.0/ARCHITECTURE.md +72 -0
  6. caltib-0.3.0/LICENSE +21 -0
  7. caltib-0.3.0/PKG-INFO +116 -0
  8. caltib-0.3.0/README.md +67 -0
  9. caltib-0.3.0/TODO.md +32 -0
  10. caltib-0.3.0/docs/api.md +122 -0
  11. caltib-0.3.0/docs/app.html +261 -0
  12. caltib-0.3.0/docs/app_logic.py +1050 -0
  13. caltib-0.3.0/docs/assets/anomaly.png +0 -0
  14. caltib-0.3.0/docs/assets/anomaly_l12.png +0 -0
  15. caltib-0.3.0/docs/assets/drift_quad.png +0 -0
  16. caltib-0.3.0/docs/assets/equinox.png +0 -0
  17. caltib-0.3.0/docs/assets/equinox_l1.png +0 -0
  18. caltib-0.3.0/docs/assets/new_year_l1.png +0 -0
  19. caltib-0.3.0/docs/assets/new_year_scatter.png +0 -0
  20. caltib-0.3.0/docs/assets/offsets_l1.png +0 -0
  21. caltib-0.3.0/docs/assets/offsets_l2.png +0 -0
  22. caltib-0.3.0/docs/assets/offsets_l3.png +0 -0
  23. caltib-0.3.0/docs/assets/offsets_l3_true.png +0 -0
  24. caltib-0.3.0/docs/assets/offsets_mongol.png +0 -0
  25. caltib-0.3.0/docs/assets/offsets_phugpa.png +0 -0
  26. caltib-0.3.0/docs/caltib-0.1.0-py3-none-any.whl +0 -0
  27. caltib-0.3.0/docs/diag.html +812 -0
  28. caltib-0.3.0/docs/index.md +111 -0
  29. caltib-0.3.0/docs/library.md +43 -0
  30. caltib-0.3.0/docs/reforms.md +46 -0
  31. caltib-0.3.0/docs/stylesheets/app.css +132 -0
  32. caltib-0.3.0/docs/stylesheets/diag.css +96 -0
  33. caltib-0.3.0/docs/stylesheets/extra.css +35 -0
  34. caltib-0.3.0/docs/stylesheets/style.css +233 -0
  35. caltib-0.3.0/docs/tools.md +68 -0
  36. caltib-0.3.0/docs/traditions.md +43 -0
  37. caltib-0.3.0/mkdocs.yml +91 -0
  38. caltib-0.3.0/pyproject.toml +44 -0
  39. caltib-0.3.0/src/caltib/__init__.py +57 -0
  40. caltib-0.3.0/src/caltib/api.py +268 -0
  41. caltib-0.3.0/src/caltib/api_init.py +5 -0
  42. caltib-0.3.0/src/caltib/attributes/__init__.py +4 -0
  43. caltib-0.3.0/src/caltib/attributes/registry.py +23 -0
  44. caltib-0.3.0/src/caltib/attributes/standard.py +20 -0
  45. caltib-0.3.0/src/caltib/bootstrap.py +10 -0
  46. caltib-0.3.0/src/caltib/cli.py +360 -0
  47. caltib-0.3.0/src/caltib/core/__init__.py +0 -0
  48. caltib-0.3.0/src/caltib/core/engine.py +23 -0
  49. caltib-0.3.0/src/caltib/core/errors.py +5 -0
  50. caltib-0.3.0/src/caltib/core/time.py +124 -0
  51. caltib-0.3.0/src/caltib/core/types.py +131 -0
  52. caltib-0.3.0/src/caltib/design/__init__.py +0 -0
  53. caltib-0.3.0/src/caltib/design/dyadic_params.py +161 -0
  54. caltib-0.3.0/src/caltib/design/ephem/__init__.py +5 -0
  55. caltib-0.3.0/src/caltib/design/ephem/rational_planets.py +207 -0
  56. caltib-0.3.0/src/caltib/design/float_params.py +146 -0
  57. caltib-0.3.0/src/caltib/design/int_tables.py +140 -0
  58. caltib-0.3.0/src/caltib/design/minimax_polys.py +202 -0
  59. caltib-0.3.0/src/caltib/design/month_constants.py +180 -0
  60. caltib-0.3.0/src/caltib/design/pade_arctan.py +132 -0
  61. caltib-0.3.0/src/caltib/design/rational_params.py +199 -0
  62. caltib-0.3.0/src/caltib/design/rational_params_b.py +175 -0
  63. caltib-0.3.0/src/caltib/design/sine_tables.py +96 -0
  64. caltib-0.3.0/src/caltib/diagnostics/__init__.py +7 -0
  65. caltib-0.3.0/src/caltib/diagnostics/analysis.py +345 -0
  66. caltib-0.3.0/src/caltib/diagnostics/anomaly.py +287 -0
  67. caltib-0.3.0/src/caltib/diagnostics/anomaly_elong.py +232 -0
  68. caltib-0.3.0/src/caltib/diagnostics/anomaly_forward.py +264 -0
  69. caltib-0.3.0/src/caltib/diagnostics/anomaly_sun.py +263 -0
  70. caltib-0.3.0/src/caltib/diagnostics/assign_day.py +262 -0
  71. caltib-0.3.0/src/caltib/diagnostics/assign_month.py +285 -0
  72. caltib-0.3.0/src/caltib/diagnostics/compare_sunrise.py +164 -0
  73. caltib-0.3.0/src/caltib/diagnostics/drift.py +202 -0
  74. caltib-0.3.0/src/caltib/diagnostics/drift_quad.py +350 -0
  75. caltib-0.3.0/src/caltib/diagnostics/ephem/__init__.py +5 -0
  76. caltib-0.3.0/src/caltib/diagnostics/ephem/analysis_trads.py +355 -0
  77. caltib-0.3.0/src/caltib/diagnostics/ephem/anomaly.py +205 -0
  78. caltib-0.3.0/src/caltib/diagnostics/ephem/anomaly_trads.py +202 -0
  79. caltib-0.3.0/src/caltib/diagnostics/ephem/drift_quad_fit.py +311 -0
  80. caltib-0.3.0/src/caltib/diagnostics/ephem/drift_trads.py +224 -0
  81. caltib-0.3.0/src/caltib/diagnostics/ephem/offsets_trads.py +199 -0
  82. caltib-0.3.0/src/caltib/diagnostics/ephem/sky.py +273 -0
  83. caltib-0.3.0/src/caltib/diagnostics/ephem/validate_ref_helio.py +142 -0
  84. caltib-0.3.0/src/caltib/diagnostics/ephem/validate_ref_planets.py +149 -0
  85. caltib-0.3.0/src/caltib/diagnostics/ephem/validate_ref_rahu.py +101 -0
  86. caltib-0.3.0/src/caltib/diagnostics/ephem/validate_ref_sm.py +145 -0
  87. caltib-0.3.0/src/caltib/diagnostics/ephem/validate_ref_stars.py +168 -0
  88. caltib-0.3.0/src/caltib/diagnostics/equinox.py +216 -0
  89. caltib-0.3.0/src/caltib/diagnostics/leap_months.py +223 -0
  90. caltib-0.3.0/src/caltib/diagnostics/losar_scatter.py +192 -0
  91. caltib-0.3.0/src/caltib/diagnostics/new_years_table.py +112 -0
  92. caltib-0.3.0/src/caltib/diagnostics/offsets.py +228 -0
  93. caltib-0.3.0/src/caltib/diagnostics/planets.py +154 -0
  94. caltib-0.3.0/src/caltib/diagnostics/pretty_month.py +164 -0
  95. caltib-0.3.0/src/caltib/diagnostics/round_trip.py +110 -0
  96. caltib-0.3.0/src/caltib/diagnostics/solar_lon.py +221 -0
  97. caltib-0.3.0/src/caltib/engines/__init__.py +0 -0
  98. caltib-0.3.0/src/caltib/engines/arithmetic_day.py +200 -0
  99. caltib-0.3.0/src/caltib/engines/arithmetic_month.py +357 -0
  100. caltib-0.3.0/src/caltib/engines/astro/affine_series.py +243 -0
  101. caltib-0.3.0/src/caltib/engines/astro/deltat.py +126 -0
  102. caltib-0.3.0/src/caltib/engines/astro/float_series.py +185 -0
  103. caltib-0.3.0/src/caltib/engines/astro/fp_math.py +141 -0
  104. caltib-0.3.0/src/caltib/engines/astro/sin_tables.py +115 -0
  105. caltib-0.3.0/src/caltib/engines/astro/sunrise.py +258 -0
  106. caltib-0.3.0/src/caltib/engines/astro/tables.py +228 -0
  107. caltib-0.3.0/src/caltib/engines/calendar.py +439 -0
  108. caltib-0.3.0/src/caltib/engines/factory.py +69 -0
  109. caltib-0.3.0/src/caltib/engines/fp_day.py +214 -0
  110. caltib-0.3.0/src/caltib/engines/interfaces.py +208 -0
  111. caltib-0.3.0/src/caltib/engines/l6/__init__.py +0 -0
  112. caltib-0.3.0/src/caltib/engines/l6/engine.py +8 -0
  113. caltib-0.3.0/src/caltib/engines/rational_day.py +307 -0
  114. caltib-0.3.0/src/caltib/engines/rational_month.py +306 -0
  115. caltib-0.3.0/src/caltib/engines/rational_planets.py +113 -0
  116. caltib-0.3.0/src/caltib/engines/specs.py +1247 -0
  117. caltib-0.3.0/src/caltib/engines/trad_attr.py +63 -0
  118. caltib-0.3.0/src/caltib/engines/trad_day.py +256 -0
  119. caltib-0.3.0/src/caltib/engines/trad_planets.py +141 -0
  120. caltib-0.3.0/src/caltib/ephemeris/__init__.py +14 -0
  121. caltib-0.3.0/src/caltib/ephemeris/de422.py +229 -0
  122. caltib-0.3.0/src/caltib/ephemeris/update_deltat_table.py +363 -0
  123. caltib-0.3.0/src/caltib/i18n.py +1778 -0
  124. caltib-0.3.0/src/caltib/reference/__init__.py +0 -0
  125. caltib-0.3.0/src/caltib/reference/astro_args.py +403 -0
  126. caltib-0.3.0/src/caltib/reference/build_micro_vsop.py +117 -0
  127. caltib-0.3.0/src/caltib/reference/build_stars.py +118 -0
  128. caltib-0.3.0/src/caltib/reference/coords.py +142 -0
  129. caltib-0.3.0/src/caltib/reference/data/__init__.py +0 -0
  130. caltib-0.3.0/src/caltib/reference/data/deltat_iers_monthly.csv +650 -0
  131. caltib-0.3.0/src/caltib/reference/deltat.py +352 -0
  132. caltib-0.3.0/src/caltib/reference/events.py +217 -0
  133. caltib-0.3.0/src/caltib/reference/kepler.py +194 -0
  134. caltib-0.3.0/src/caltib/reference/lunar.py +214 -0
  135. caltib-0.3.0/src/caltib/reference/planets.py +776 -0
  136. caltib-0.3.0/src/caltib/reference/planets_tmpl.py +182 -0
  137. caltib-0.3.0/src/caltib/reference/solar.py +182 -0
  138. caltib-0.3.0/src/caltib/reference/stars.py +282 -0
  139. caltib-0.3.0/src/caltib/reference/stars_tmpl.py +111 -0
  140. caltib-0.3.0/src/caltib/reference/time_scales.py +232 -0
  141. caltib-0.3.0/src/caltib/web_diag/__init__.py +0 -0
  142. caltib-0.3.0/src/caltib/web_diag/api.py +1011 -0
@@ -0,0 +1,40 @@
1
+ name: Build and Deploy Documentation
2
+
3
+ on:
4
+ push:
5
+ branches:
6
+ - main # Triggers the build whenever you push to the main branch
7
+
8
+ permissions:
9
+ contents: write # Allows the action to push the built HTML to the gh-pages branch
10
+
11
+ jobs:
12
+ deploy:
13
+ runs-on: ubuntu-latest
14
+ steps:
15
+ - name: Checkout repository
16
+ uses: actions/checkout@v4
17
+
18
+ - name: Configure Git Credentials
19
+ run: |
20
+ git config user.name github-actions[bot]
21
+ git config user.email 41898282+github-actions[bot]@users.noreply.github.com
22
+
23
+ - name: Set up Python
24
+ uses: actions/setup-python@v5
25
+ with:
26
+ python-version: '3.9' # Matching your pyproject.toml requirement
27
+
28
+ - name: Install documentation dependencies
29
+ run: |
30
+ python -m pip install --upgrade pip
31
+ pip install mkdocs-material
32
+ pip install "mkdocstrings[python]"
33
+
34
+ - name: Install caltib (Crucial Step)
35
+ # mkdocstrings must be able to import your library to read the docstrings.
36
+ # We install the full bundle so the ephemeris and tools modules don't crash on import.
37
+ run: pip install -e .[full]
38
+
39
+ - name: Deploy to GitHub Pages
40
+ run: mkdocs gh-deploy --force
@@ -0,0 +1,35 @@
1
+ name: Publish to PyPI
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - 'v*' # This workflow ONLY runs with a tag like v0.3.0, v0.3.1, etc.
7
+
8
+ jobs:
9
+ pypi-publish:
10
+ name: Build and publish Python distribution
11
+ runs-on: ubuntu-latest
12
+
13
+ # These permissions are required for PyPI Trusted Publishing
14
+ environment: release
15
+ permissions:
16
+ id-token: write
17
+ contents: read
18
+
19
+ steps:
20
+ - name: Checkout code
21
+ uses: actions/checkout@v4
22
+
23
+ - name: Set up Python
24
+ uses: actions/setup-python@v5
25
+ with:
26
+ python-version: '3.9'
27
+
28
+ - name: Install build tools
29
+ run: python -m pip install --upgrade pip build
30
+
31
+ - name: Build the tarball and wheel
32
+ run: python -m build
33
+
34
+ - name: Publish package to PyPI
35
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,16 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.pyc
4
+ .pytest_cache/
5
+ .mypy_cache/
6
+ .ruff_cache/
7
+ dist/
8
+ build/
9
+ *.egg-info/
10
+ .venv/
11
+ .DS_Store
12
+ # Ignore these file types ONLY in the root directory
13
+ /*.png
14
+ /*.jpg
15
+ /*.pdf
16
+ /*.csv
@@ -0,0 +1,3 @@
1
+ {
2
+ "python.analysis.extraPaths": ["./src"]
3
+ }
@@ -0,0 +1,72 @@
1
+ # Caltib: Architecture & Design Philosophy
2
+
3
+ `caltib` is a high-precision, mathematically rigorous library for Siddhantic and Tibetan calendrical astronomy. It bridges the gap between historical medieval algorithms (piecewise linear integer models) and modern celestial mechanics (continuous trigonometric ephemerides) by unifying them under a single algebraic framework.
4
+
5
+ ## 1. The Principle of Modularity
6
+
7
+ The historical calendar is fundamentally the intersection of two completely orthogonal mathematical domains. `caltib` strictly isolates these domains into independent protocols.
8
+
9
+ 1. **`MonthEngine` (Discrete Arithmetic):** * **Domain:** Labels, years, and leap statuses.
10
+ * **Mechanics:** Maps absolute lunation indices ($n$) to human calendar labels (Year, Month, Intercalary status). It operates purely on modular arithmetic and knows nothing of physical time or Julian Days.
11
+ 2. **`DayEngine` (Continuous Kinematics):**
12
+ * **Domain:** Celestial motion and timekeeping.
13
+ * **Mechanics:** Maps an absolute spatial coordinate ($x$) to an exact physical time (Julian Day) by solving for planetary alignments. It knows nothing of calendar years or human month labels.
14
+ 3. **`CalendarEngine` (The Orchestrator):**
15
+ * **Domain:** The Civil Boundary.
16
+ * **Mechanics:** Acts as the bridge between the civil user and the physical engines. It takes a local integer Julian Day Number (JDN), queries the Day Engine for the spatial coordinate $x$, derives the lunation $n$, and asks the Month Engine for the label.
17
+
18
+ By treating the Month and Day engines as modular plugins, the library supports seamless hybridization (e.g., combining a traditional 15th-century Phugpa month calculator with a 21st-century floating-point day kinematic solver).
19
+
20
+ ## 2. The Absolute Spatial Coordinate ($x$)
21
+
22
+ A core breakthrough of the `caltib` architecture is the flattening of the traditional two-dimensional calendar grid (lunation $n$, tithi $d$) into a single, continuous, one-dimensional spatial coordinate:
23
+
24
+ $$x = 30n + d$$
25
+
26
+ In the kinematic layer (`DayEngine`), $x$ represents the absolute number of tithis (lunar days, or $12^\circ$ increments of elongation) elapsed since the epoch.
27
+ * By removing $n$ and $d$ from the core physics loop, continuous root-finding algorithms (like the Picard solver) can evaluate fractional tithis seamlessly.
28
+ * The traditional engine logic is completely subsumed by this coordinate, evaluating mean elongation linearly via $m_0 + x \cdot m_1$.
29
+
30
+ ## 3. The Temporal Reference Frame (J2000.0 TT)
31
+
32
+ To guarantee numerical stability, all internal physical time variables ($t$) in the `DayEngine` represent **Days since J2000.0 TT** (where J2000.0 = JD 2451545.0).
33
+
34
+ * **Rational Engines (L1-L3):** Shifting the origin to J2000.0 prevents fraction denominators from exploding when evaluating exact affine series over millions of days.
35
+ * **Floating-Point Engines (L4-L5):** Shifting the origin prevents catastrophic cancellation and floating-point precision loss when computing high-frequency astronomical anomalies.
36
+ * **Civil Abstraction:** The continuous $t2000$ values are only converted to absolute Julian Days (JD) or Julian Day Numbers (JDN) at the outermost `CalendarEngine` layer.
37
+
38
+ ## 4. The Kinematic Solver (The Picard Iteration)
39
+
40
+ The continuous `DayEngine` reforms discard historical lookup tables in favor of dynamically solving the fundamental equation of syzygy. The engine builds an affine series for the mean elongation $D(t)$ and the solar/lunar perturbations $C(t)$.
41
+
42
+ To find the exact time $t$ of a tithi boundary $x$, the engine solves:
43
+ $$D(t) + C_{moon}(t) - C_{sun}(t) = \frac{x}{30}$$
44
+
45
+ Because the perturbations $C(t)$ themselves depend on time, `caltib` employs a Picard fixed-point iteration, seeded by the linear mean system $t_0 = D^{-1}(x/30)$, to converge on the exact physical timing of the lunar day.
46
+
47
+ ## 5. Epoch Synchronization
48
+
49
+ Because the Month and Day engines are independent, they may theoretically possess different astronomical epochs. `caltib` defines the epoch natively via the absolute Meeus mean new moon index ($k_0$).
50
+ The `CalendarEngine` automatically aligns the engines by computing $\Delta k = \text{Day.epoch\_k} - \text{Month.epoch\_k}$, dynamically shifting the $x$ coordinate to guarantee perfect phase synchronization across any combination of models.
51
+
52
+
53
+ ## 1. The Strategy Pattern (The Orchestrator)
54
+ The library is built around a pure Strategy Pattern. The `CalendarEngine` acts as a universal orchestrator that knows nothing about astronomical physics or traditional arithmetic. It strictly expects two interchangeable components that satisfy strict protocols (`interfaces.py`):
55
+ * `MonthEngineProtocol`: Solves for the human month label (Year, Month, Leap) given an absolute lunation index `n`.
56
+ * `DayEngineProtocol`: Solves for the physical time (`t2000`) given a continuous absolute tithi coordinate `x`.
57
+
58
+ Because of this decoupled design, any combination of month and day models can be composed into a functional calendar. An ancient `ArithmeticMonthEngine` can be paired with a highly precise `RationalDayEngine` without either component knowing the other exists.
59
+
60
+ ## 2. Epoch Synchronization (`delta_k`)
61
+ Different historical traditions defined their epoch zero points differently (e.g., the Phugpa epoch vs. the Tsurphu epoch). The `CalendarEngine` completely absorbs this complexity via the `delta_k` shift.
62
+ When a Composite calendar is instantiated, the orchestrator calculates `delta_k = month.epoch_k - day.epoch_k`. It dynamically shifts the coordinates between the Month and Day engines on the fly, allowing parameters from entirely different centuries to be perfectly aligned on the J2000.0 timeline.
63
+
64
+ ## 3. Pure Data Specifications & The Factory
65
+ The library enforces a strict boundary between configuration and execution:
66
+ * **Specs as Pure Data:** `src/caltib/engines/specs.py` contains only frozen `dataclasses` (`CalendarSpec`). It imports zero execution logic. This ensures serialization is trivial and avoids circular imports.
67
+ * **The Factory Instantiator:** `src/caltib/engines/factory.py` is the singular chokepoint where pure data specifications are "hydrated" into live, executable engine objects.
68
+
69
+ ## 4. Dynamic Location Overrides (Immutability)
70
+ Because our specifications are built on frozen dataclasses, they are perfectly immutable. If a user wishes to calculate a continuous L1-L3 reform calendar for a custom location (e.g., Montreal instead of Lhasa), they do not need to alter the global specification.
71
+
72
+ The `api.get_calendar(name, location=LOC)` function uses Python's `dataclasses.replace` to safely clone the `CalendarSpec` in memory, inject the new coordinate parameters into the `DayEngine` configuration, and pass the cloned spec to the factory. The base `specs.py` data remains completely uncorrupted.
caltib-0.3.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Tsogtgerel Gantumur
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
caltib-0.3.0/PKG-INFO ADDED
@@ -0,0 +1,116 @@
1
+ Metadata-Version: 2.4
2
+ Name: caltib
3
+ Version: 0.3.0
4
+ Summary: Tibetan calendar toolkit (traditional + reform engines).
5
+ Author: caltib contributors
6
+ License: MIT License
7
+
8
+ Copyright (c) 2026 Tsogtgerel Gantumur
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+ License-File: LICENSE
28
+ Requires-Python: >=3.9
29
+ Provides-Extra: dev
30
+ Requires-Dist: build>=1.2; extra == 'dev'
31
+ Requires-Dist: mypy>=1.8; extra == 'dev'
32
+ Requires-Dist: pytest>=8; extra == 'dev'
33
+ Requires-Dist: ruff>=0.4; extra == 'dev'
34
+ Requires-Dist: twine>=5; extra == 'dev'
35
+ Provides-Extra: ephemeris
36
+ Requires-Dist: jplephem>=2.21; extra == 'ephemeris'
37
+ Requires-Dist: skyfield>=1.45; extra == 'ephemeris'
38
+ Provides-Extra: full
39
+ Requires-Dist: jplephem>=2.21; extra == 'full'
40
+ Requires-Dist: matplotlib>=3.8; extra == 'full'
41
+ Requires-Dist: numpy>=1.24; extra == 'full'
42
+ Requires-Dist: scipy>=1.10; extra == 'full'
43
+ Requires-Dist: skyfield>=1.45; extra == 'full'
44
+ Provides-Extra: tools
45
+ Requires-Dist: matplotlib>=3.8; extra == 'tools'
46
+ Requires-Dist: numpy>=1.24; extra == 'tools'
47
+ Requires-Dist: scipy>=1.10; extra == 'tools'
48
+ Description-Content-Type: text/markdown
49
+
50
+ caltib
51
+ High-Precision Tibetan Calendrical Math
52
+
53
+ caltib is a rigorous Python library designed to unify 15th-century historical algorithms with 21st-century astrophysics. It provides a polymorphic framework for evaluating traditional lunisolar calendars alongside modern mathematical reforms.
54
+
55
+ Live Demonstration
56
+ The library can be evaluated directly in the browser without local installation. The web calendar runs completely client-side via WebAssembly:
57
+ Launch the caltib Web App (Note: Insert your actual link here)
58
+
59
+ Key Features
60
+ Unified API: Evaluate traditional engines (Phugpa, Mongol, Tsurphu, etc.) and modern reforms (L0–L6) using a single, harmonized interface.
61
+
62
+ Progressive Reforms: A tiered sequence of engines advancing from pure-integer mean motion (L0) and fixed-iteration Picard solvers (L1–L3) to strictly reproducible floating-point models (L4–L5) and JPL-powered numerical integration (L6).
63
+
64
+ Strict Reproducibility: L0–L5 engines utilize integer sine-tables or Chebyshev minimax polynomials to ensure bit-for-bit consistency across all CPU architectures.
65
+
66
+ Localized Physics: Support for geographical location injection to accurately handle spherical sunrise boundaries and civil day-numbering conventions.
67
+
68
+ Design & Diagnostics Laboratory: A professional-grade toolkit for designing new calendar parameters via continued fractions and analyzing secular drift over millennia.
69
+
70
+ Installation
71
+ caltib is designed to be lightweight. The core package has zero external dependencies, making it highly suitable for embedded environments or web deployment.
72
+
73
+ Bash
74
+ # Core: Traditional engines & Reform Tiers L0-L5
75
+ pip install caltib
76
+
77
+ # Tools: Diagnostic charting & parameter design (requires NumPy & Matplotlib)
78
+ pip install "caltib[tools]"
79
+
80
+ # Ephemeris: JPL DE422 integration & L6 engine (requires Skyfield & jplephem)
81
+ pip install "caltib[ephemeris]"
82
+ Quickstart
83
+ Basic Day Query
84
+ Python
85
+ from datetime import date
86
+ import caltib
87
+
88
+ # Standard traditional lookup
89
+ info = caltib.day_info(date(2026, 2, 21), engine="mongol")
90
+ print(f"Mongol Tithi: {info.tibetan.tithi}")
91
+ Advanced Localized Reform
92
+ Python
93
+ from caltib.engines.specs import LOC_MONTREAL
94
+ import caltib
95
+
96
+ # Build an L3 engine localized to Montreal coordinates.
97
+ # L3 utilizes fixed-iteration rational Picard solvers and spherical sunrise geometry.
98
+ engine = caltib.get_calendar("l3", location=LOC_MONTREAL)
99
+ info = engine.day_info(date(2026, 2, 21))
100
+ Diagnostics & Design
101
+ The library includes a comprehensive diagnostic suite to rigorously analyze calendar accuracy and historical deviations.
102
+
103
+ Secular Drift: Track how sidereal calendars decouple from the tropical equinox over 1,500-year timescales.
104
+
105
+ Variance Mapping: Visualize the error propagation and variance of traditional anomaly approximations.
106
+
107
+ Rational Design: Derive optimal convergents for constructing new calendar architectures.
108
+
109
+ Example Usage:
110
+
111
+ Bash
112
+ # Analyze secular acceleration against JPL DE422 numerical integration
113
+ caltib diag analysis --engine mongol --ephem de422
114
+
115
+ License
116
+ Distributed under the MIT License. Created by Tsogtgerel Gantumur.
caltib-0.3.0/README.md ADDED
@@ -0,0 +1,67 @@
1
+ caltib
2
+ High-Precision Tibetan Calendrical Math
3
+
4
+ caltib is a rigorous Python library designed to unify 15th-century historical algorithms with 21st-century astrophysics. It provides a polymorphic framework for evaluating traditional lunisolar calendars alongside modern mathematical reforms.
5
+
6
+ Live Demonstration
7
+ The library can be evaluated directly in the browser without local installation. The web calendar runs completely client-side via WebAssembly:
8
+ Launch the caltib Web App (Note: Insert your actual link here)
9
+
10
+ Key Features
11
+ Unified API: Evaluate traditional engines (Phugpa, Mongol, Tsurphu, etc.) and modern reforms (L0–L6) using a single, harmonized interface.
12
+
13
+ Progressive Reforms: A tiered sequence of engines advancing from pure-integer mean motion (L0) and fixed-iteration Picard solvers (L1–L3) to strictly reproducible floating-point models (L4–L5) and JPL-powered numerical integration (L6).
14
+
15
+ Strict Reproducibility: L0–L5 engines utilize integer sine-tables or Chebyshev minimax polynomials to ensure bit-for-bit consistency across all CPU architectures.
16
+
17
+ Localized Physics: Support for geographical location injection to accurately handle spherical sunrise boundaries and civil day-numbering conventions.
18
+
19
+ Design & Diagnostics Laboratory: A professional-grade toolkit for designing new calendar parameters via continued fractions and analyzing secular drift over millennia.
20
+
21
+ Installation
22
+ caltib is designed to be lightweight. The core package has zero external dependencies, making it highly suitable for embedded environments or web deployment.
23
+
24
+ Bash
25
+ # Core: Traditional engines & Reform Tiers L0-L5
26
+ pip install caltib
27
+
28
+ # Tools: Diagnostic charting & parameter design (requires NumPy & Matplotlib)
29
+ pip install "caltib[tools]"
30
+
31
+ # Ephemeris: JPL DE422 integration & L6 engine (requires Skyfield & jplephem)
32
+ pip install "caltib[ephemeris]"
33
+ Quickstart
34
+ Basic Day Query
35
+ Python
36
+ from datetime import date
37
+ import caltib
38
+
39
+ # Standard traditional lookup
40
+ info = caltib.day_info(date(2026, 2, 21), engine="mongol")
41
+ print(f"Mongol Tithi: {info.tibetan.tithi}")
42
+ Advanced Localized Reform
43
+ Python
44
+ from caltib.engines.specs import LOC_MONTREAL
45
+ import caltib
46
+
47
+ # Build an L3 engine localized to Montreal coordinates.
48
+ # L3 utilizes fixed-iteration rational Picard solvers and spherical sunrise geometry.
49
+ engine = caltib.get_calendar("l3", location=LOC_MONTREAL)
50
+ info = engine.day_info(date(2026, 2, 21))
51
+ Diagnostics & Design
52
+ The library includes a comprehensive diagnostic suite to rigorously analyze calendar accuracy and historical deviations.
53
+
54
+ Secular Drift: Track how sidereal calendars decouple from the tropical equinox over 1,500-year timescales.
55
+
56
+ Variance Mapping: Visualize the error propagation and variance of traditional anomaly approximations.
57
+
58
+ Rational Design: Derive optimal convergents for constructing new calendar architectures.
59
+
60
+ Example Usage:
61
+
62
+ Bash
63
+ # Analyze secular acceleration against JPL DE422 numerical integration
64
+ caltib diag analysis --engine mongol --ephem de422
65
+
66
+ License
67
+ Distributed under the MIT License. Created by Tsogtgerel Gantumur.
caltib-0.3.0/TODO.md ADDED
@@ -0,0 +1,32 @@
1
+ # caltib Project Roadmap
2
+
3
+ ## 🎯 Active Development Tracks
4
+
5
+ ### 1. Web Application & Documentation
6
+ - [ ] **Implement Open/Save Configuration:** Add functionality to export and import complete custom calendar specifications (via JSON) directly within the `app.html` web interface.
7
+ - [ ] **Automated Documentation Pipeline:** Implement docstring-driven documentation using MkDocs (with the Material theme) and `mkdocstrings`. Set up a GitHub Action to automatically build and deploy the API reference to GitHub Pages on `main` branch pushes.
8
+
9
+ ### 2. Numerical Ephemeris Integration (L6)
10
+ - [ ] **Develop `EphDayEngine` (L6):** Create the ultimate truth layer by implementing L6, allowing users to toggle between **JPL DE422 `.bsp` files** and the **internal analytical reference library** as optional sources for mapping physical syzygies.
11
+ - [ ] **Develop `EphMonthEngine`:** Allow the month boundaries and intercalation logic to be driven natively by continuous ephemeris data rather than analytical mean motions.
12
+
13
+ ### 3. Phenomenological & Planetary Engines
14
+ - [ ] **Write Rational Planet Engine:** Implement the pure-rational historical Siddhantic planetary mathematical models (fast/slow motions, dal-bar, etc.).
15
+
16
+ ### 4. Advanced Diagnostics Laboratory & Validation
17
+ - [ ] **Near-Tie & Boundary Validation:** Ensure all extreme mathematical boundary cases are correct. Write dedicated, rigorous test scripts targeting near-tie scenarios (e.g., borderline leap months, micro-second skipped/repeated day boundaries).
18
+ - [ ] **Integrate Exotic Epochs:** Extract and implement the "exotic" historical epoch data and parameters from Edward Henning's source code/pages to use as hardened validation baselines.
19
+ - [ ] **Web-Diag Enhancements:** Add the Equinox Solar Longitude drift analysis tool directly into the `diag.html` web dashboard.
20
+
21
+ ---
22
+
23
+ ## ✅ Completed Milestones
24
+ * **Architecture Refactor:** Successfully decoupled discrete arithmetic from continuous kinematics using the `CalendarSpec` polymorphic factory.
25
+ * **Rational Engines (L0-L3):** Implemented zero-FPU continuous rational fractions, Picard solvers, and integer sine-tables.
26
+ * **Floating-Point Engines (L4-L5):** Developed strictly reproducible FP kinematics using Chebyshev minimax polynomials, floating-point spherical sunrise models, and Picard/Steffensen solvers.
27
+ * **Universal Civil Generator:** Built the orchestrator to convert continuous $x$-coordinates into discrete JDN boundaries, accurately handling skipped/duplicated days based on geographical location.
28
+ * **Web Calendar Frontend:** Built `app.html` with full-featured Day/Month/Year views, chronological Losar/Tsagaan Sar generators, and fully integrated client-side PyScript/WebAssembly execution.
29
+ * **Attribute Engine:** Mapped the discrete chronological grids to traditional Tibetan/Mongolian attributes (Elements, Animals, Trigrams/Mewa, Lunar Mansions, Weekdays).
30
+ * **Unified Diagnostics Lab:** Built the comprehensive suite for measuring secular drift, variance, equinox precession, and syzygy offsets against JPL DE422 truth.
31
+ * **Diagnostic Enhancements:** Completed month-level diagnostics (intercalation triggers, drift) and spherical sunrise/latitude geographic phase shift comparisons.
32
+ * **Design Tools:** Implemented continued fraction generators and Chebyshev minimax polynomial calculators for engine design.
@@ -0,0 +1,122 @@
1
+ # The `caltib` Python API
2
+
3
+ The library provides a clean, unified interface to query both discrete traditional engines and continuous astronomical models. Because of the strict mathematical decoupling under the hood, the top-level API remains identical whether you are evaluating a 15th-century integer framework or an L6 JPL numerical ephemeris.
4
+
5
+ ---
6
+
7
+ ## 1. Initialization & The Engine Factory
8
+
9
+ The `get_calendar()` factory is the gateway to the library. It dynamically instantiates the requested `CalendarEngine`, utilizing lazy loading to ensure high-end dependencies (like `jplephem`) are only imported if explicitly requested.
10
+
11
+ ```python
12
+ import caltib
13
+ from caltib.engines.specs import LOC_MONTREAL, LOC_LHASA
14
+
15
+ # Instantiate a traditional engine (defaults to approximate historical coordinates)
16
+ phugpa_engine = caltib.get_calendar("phugpa")
17
+
18
+ # Instantiate a reform engine with localized geographical dependency injection
19
+ # This dynamically overrides the thresholds used for spherical sunrise
20
+ l3_montreal = caltib.get_calendar("l3", location=LOC_MONTREAL)
21
+ ```
22
+
23
+ ---
24
+
25
+ ## 2. Core Day Queries
26
+
27
+ The most common operation is fetching the complete calendrical state for a specific Gregorian date. You can use the top-level `day_info()` function for quick lookups, or call it directly on an instantiated engine.
28
+
29
+ ```python
30
+ from datetime import date
31
+
32
+ # 1. Top-level quick query
33
+ info = caltib.day_info(date(2026, 2, 21), engine="mongol")
34
+
35
+ # 2. Engine-level query (faster for bulk operations)
36
+ info = l3_montreal.day_info(date(2026, 2, 21))
37
+
38
+ print(f"Tibetan Year: {info.tibetan.year}")
39
+ print(f"Tithi (Lunar Day): {info.tibetan.tithi}")
40
+ print(f"Is Leap Month?: {info.tibetan.is_leap_month}")
41
+ ```
42
+
43
+ ### The `DayInfo` & `TibetanDate` Data Models
44
+
45
+ The `day_info` method returns a comprehensive `DayInfo` dataclass containing both the input Gregorian parameters and the resulting Tibetan mapping.
46
+
47
+ * `DayInfo.gregorian`: A standard Python `datetime.date` object.
48
+ * `DayInfo.jdn`: The Julian Day Number (integer) representing local noon.
49
+ * `DayInfo.tibetan`: A `TibetanDate` dataclass containing:
50
+ * `year`: The Tibetan year number.
51
+ * `month`: The Tibetan month number (1–12).
52
+ * `is_leap_month`: Boolean. `True` if this is an intercalary month.
53
+ * `tithi`: The lunar day number (1–30).
54
+ * `is_leap_day`: Boolean. `True` if this specific tithi is duplicated (the second occurrence).
55
+ * `is_skipped`: Boolean. Identifies if the *preceding* mathematical tithi was skipped in the civil calendar.
56
+
57
+ ---
58
+
59
+ ## 3. Calendar Arithmetic & Conversions
60
+
61
+ The API provides robust tools for navigating the calendar chronologically, handling the complex boundaries of leap months and missing days.
62
+
63
+ * `caltib.new_year_day(Y: int, engine: str) -> date`: Resolves the Gregorian start date of the Tibetan New Year (Losar / Tsagaan Sar) for the given Tibetan year $Y$.
64
+ * `caltib.month_bounds(Y: int, M: int, is_leap: bool = False, engine: str) -> MonthBounds`: Returns the exact starting and ending JDN and Gregorian dates of a specific lunar month, mapping the continuous coordinate $x$ to the civil grid.
65
+ * `caltib.to_gregorian(t_date: TibetanDate, engine: str, policy: str = "all") -> list[date]`: Inverts a Tibetan date back into Gregorian. Because Tibetan civil days can be duplicated, this returns a list.
66
+ * `policy="all"`: Returns all Gregorian dates matching the Tibetan date (returns 2 dates if duplicated, 0 if skipped).
67
+ * `policy="first"`: Returns only the first occurrence of a duplicated day.
68
+ * `policy="second"`: Returns only the second occurrence.
69
+
70
+ ---
71
+
72
+ ## 4. High-Performance Bulk Processing
73
+
74
+ When generating millennia-spanning charts in the Diagnostics Lab, repeatedly calling the top-level `caltib.day_info(..., engine="...")` introduces factory overhead. For maximum performance, instantiate the `CalendarEngine` once and use its internal generators.
75
+
76
+ ```python
77
+ # Instantiate engine once
78
+ engine = caltib.get_calendar("l4")
79
+
80
+ # Fetch civil calendar mappings for an entire lunation efficiently
81
+ # lunation_index (n) maps directly to the absolute coordinate x = 30n + d
82
+ month_map = engine.build_civil_month(lunation_index=12345)
83
+
84
+ for civil_jdn, tithi in month_map.items():
85
+ # Process the discrete grid...
86
+ pass
87
+ ```
88
+
89
+ ---
90
+
91
+ ## Exhaustive API Reference
92
+
93
+ Below is the automatically generated technical reference for all public classes and functions in the `caltib` library, extracted directly from the Python source code.
94
+
95
+ ### Top-Level API & Configuration
96
+ ::: caltib.api
97
+ ::: caltib.engines.factory
98
+ ::: caltib.engines.specs
99
+
100
+ ### Core Data Models
101
+ ::: caltib.core.types
102
+ ::: caltib.core.time
103
+
104
+ ### Base Engine Architectures
105
+ ::: caltib.engines.interfaces
106
+ ::: caltib.engines.calendar
107
+
108
+ ### Internal Solvers & Physics Models
109
+ ::: caltib.engines.trad_day
110
+ ::: caltib.engines.rational_day
111
+ ::: caltib.engines.fp_day
112
+
113
+ !!! warning "Experimental: L6 Engine"
114
+ The following `l6.engine` module is under development.
115
+
116
+ ::: caltib.engines.l6.engine
117
+
118
+ ### Analytical Astronomical Reference (Ground Truth)
119
+ ::: caltib.reference.solar
120
+ ::: caltib.reference.lunar
121
+ ::: caltib.reference.time_scales
122
+ ::: caltib.reference.astro_args