mesomath 2.1.1__tar.gz → 2.2.0__tar.gz

mesomath-2.2.0/.webui_secret_key

@@ -0,0 +1 @@
+8jwRclFzu7ELjH+s

{mesomath-2.1.1 → mesomath-2.2.0}/CHANGELOG.md

@@ -1,3 +1,28 @@
+## [2.2.0] - 2026-06-29
+
+### Added
+* **User-defined locations**: Added support for custom archaeological sites and observation platforms by allowing user-defined coordinate overrides (latitude, longitude, and altitude) in core astronomical functions.
+* **`mesotimes.astronomy.stars` module**: Introduced the `BabStar` class, enabling high-precision tracking of ancient stars. Includes native catalog parsing (`from_catalog`), automatic extraction of photometric magnitudes ($V$, $B-V$), and geometric event finders (`search_phenomena`).
+* **`mesotimes.astronomy.visibility` module**: Implemented a comprehensive twilight visibility simulation framework. Features 3D scattering models for crepuscular sky brightness, customizable air-mass functions (Pickering, Kasten-Young), and atmospheric extinction profiling (`scan_twilight_visibility`).
+* **Object-Oriented Analysis Interface**: Integrated `twilight_tomography` directly into `BabStar`, allowing researchers to generate multi-day visual contrast time-series reports with a single method call.
+
+---
+
+## [2.1.2] - 2026-06-07
+
+### Fixed
+* **Bug in date.py**: Chrondate.day_ephemeris() returned the day of the season based only on the Julian calendar. Fixed.
+
+---
+
+
+## [2.1.1] - 2026-06-06
+
+### Fixed
+* **README.md**: Incorrect badges. Fixed.
+
+---
+
 
 ## [2.1.0] - 2026-06-06
 

{mesomath-2.1.1 → mesomath-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mesomath
-Version: 2.1.1
+Version: 2.2.0
 Summary: A robust sexagesimal, metrological, and astronomical engine for Babylonian mathematics. From the Eduba to the Jupyter Notebook.
 Project-URL: Changelog, https://github.com/jccsvq/mesomath/blob/main/CHANGELOG.md
 Project-URL: Documentation, https://mesomath.readthedocs.io/
@@ -30,14 +30,13 @@ Requires-Python: >=3.11
 Requires-Dist: ipython>=9.0.0
 Requires-Dist: juliandate
 Requires-Dist: parsimonious==0.11.0
-Requires-Dist: pymeeus>=0.5.12
+Requires-Dist: pymeeus==0.5.12
 Requires-Dist: traitlets>=5.0.0
 Requires-Dist: typing-extensions>=4.0.0
 Requires-Dist: wcwidth
 Description-Content-Type: text/markdown
 
-
-# 🏺 MesoMath v2.1.0
+# 🏺 MesoMath v2.2
 **The Mesopotamian Computational Engine for Python.**
 
 [![PyPI - Version](https://img.shields.io/pypi/v/mesomath.svg)](https://pypi.org/project/mesomath/)
@@ -47,19 +46,36 @@ Description-Content-Type: text/markdown
 [![Documentation Status](https://readthedocs.org/projects/mesomath/badge/?version=latest)](https://mesomath.readthedocs.io)
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jccsvq/mesomath-nb/main?labpath=notebooks%2Findex.ipynb)
 
-MesoMath is a high-precision computational framework engineered for the rigorous study of ancient Mesopotamian mathematics, metrology, chronology, timekeeping, and archaeoastronomy. It provides native command-line environments (CLI), Jupyter integration, and authentic epigraphic support (Old Babylonian transliteration and Unicode cuneiform rendering).
+MesoMath is a high-precision computational framework engineered for the rigorous study of ancient Mesopotamian:
+
+* **Mathematics**
+  * Sexagesimal integer arithmetic (absolute and floating)
+  * Fraction arithmetic
+* **Metrology**
+  * Old Babylonian Period metrology (length, surface, volume, weight, capacity, and bricks)
+  * User-extensible framework for other historical periods
+  * NPVS Systems S, G, C, and K
+  * Socio-economic applications
+* **Chronology**
+  * Based on Parker and Dubberstein (1971) for the period 626 B.C. – A.D. 75
+  * *Proleptic* lunar calendar engine for other historical eras
+* **Timekeeping & Archaeoastronomy**
+  * Lunar and Planetary Ephemerides
+  * Heliacal and Acronychal Rising of stars (Atmospheric 3D scattering models)
+  * Built-in catalog of relevant Mesopotamian astronomical sites
+  * Built-in catalog of critical historical stars
+  * Custom user-defined sites and stars support
+
+MesoMath provides:
+* **Native Command-Line Environments (CLI)**: `babcalc` (basic) and `ibabcalc` (full-featured interactive shell).
+* **Jupyter Notebook Integration** for reproducible research.
+* **Authentic Epigraphic Support**: Old Babylonian transliteration standards and Unicode cuneiform rendering.
 
 ---
 
-## ✨ What's New in v2.1.0?
-
-MesoMath has evolved into a unified metapackage, structurally decoupling core arithmetic from chronological anchoring systems:
+## ✨ What's New in v2.2.0?
 
-* **`mesomath` Core**: Introduces the **`BabF`** class for native sexagesimal (base-60) fractional arithmetic without floating-point rounding artifacts.
-* **`mesotimes` Subsystem**: A dedicated historical engine driving:
-    * **Empirical & Proleptic Chronology**: Seamless alignment with historical cuneiform registers.
-    * **Elastic Timekeeping**: Shifting horizon-based day boundaries (Sunset-to-Sunset) and dynamic nocturnal watches (*maṣṣarātu*).
-    * **Archaeoastronomy**: High-fidelity celestial positioning and eclipse matrices.
+MesoMath v2.2.0 introduces the `BabStar` class, enabling high-fidelity search, physical contrast tracking, and multi-day **Twilight Tomography** for Heliacal and Acronychal stellar phenomena.
 
 ---
 
@@ -109,7 +125,7 @@ from mesomath import Bcap
 
 vol = Bcap('3 bariga 2 ban')
 print(vol.translit)   # Output: '3(barig) 2(ban2) še'
-print(vol.cuneiform)  # Output: 𒑗 𒑐 𒊺
+print(vol.cuneiform)  # Output: itri  samot 𒊺
 
 ```
 
@@ -135,7 +151,7 @@ date.day_ephemeris(city='Susa')
 
 ```text
 =================================================================
-               MESOPOTAMIAN DAILY EPHEMERIS: SUSA                
+                MESOPOTAMIAN DAILY EPHEMERIS: SUSA                
 =================================================================
   Julian Day:  1583129.5       | Civil Calendar: Julian (-378/5/17)
   Chronology:  Year 26 of Artaxerxes II, month: 2 (Aiaru), day: 14
@@ -150,14 +166,13 @@ date.day_ephemeris(city='Susa')
     [End-Month] KUR:        -894.34 min (Dawn crescent disappearance)
 -----------------------------------------------------------------
   PLANETARY VISIBILITY ( Twilight vs. Arc of Vision ):
-    * Mercury    -> Invisible / Glare                   (Required Av: 12.0°)
+    * Mercury    -> Invisible / Glare          (Required Av: 12.0°)
     * Venus      -> VISIBLE (Morning Star)     (Required Av: 6.0°)
     * Mars       -> VISIBLE (Morning Star)     (Required Av: 14.0°)
     * Jupiter    -> VISIBLE (Evening Star)     (Required Av: 9.0°)
     * Saturn     -> VISIBLE (Evening Star)     (Required Av: 11.0°)
 =================================================================
 
-
 ```
 
 ```python
@@ -168,24 +183,91 @@ date.night_at_a_glance(city='Susa')
 
 ```text
 ===================================================================
-          NIGHT AT A GLANCE: SUSA (-378-05-17)
+    Night at a Glance: Susa (-378-05-17)
 ===================================================================
 UT Hours:  09  11  13  15  17  19  21  23  01  03  05  07  09  
 Local H.:  12  14  16  18  20  22  00  02  04  06  08  10  12  
 -------------------------------------------------------------------
  Sky/Sun :  #############::.               .::###############
 -------------------------------------------------------------------
- Moon    :              =====================                
+ Moon    :               =====================                 
 -------------------------------------------------------------------
- Mercury :  ----------                      -----------------
- Venus   :  ------------                     ----------------
- Mars    :  -                          --------------------- 
- Jupiter :          -----------------------                  
- Saturn  :  ------------------------                    -----
+ Mercury :  ----------                     -----------------
+ Venus   :  ------------                   ----------------
+ Mars    :  -                           --------------------- 
+ Jupiter :            -----------------------                  
+ Saturn  :  ------------------------                     -----
 ===================================================================
 Legend:  # Day  : Civ/Nav Twilight  . Ast Twilight    Night
          - Planet above horizon     = Moon above horizon
 
+```
+
+```python
+# Search for Sirius' Heliacal Rising in 378 BCE
+from mesomath import BabStar
+
+sirius = BabStar.from_catalog("Sirius")
+sirius.search_phenomena(-378)
+
+```
+
+```text
+Search for Sirius Heliacal Appearance in the East before sunrise:
+======================================================================
+Search starting at Babylon:  -378-01-1.0
+   First sight found at:  -378-07-23.08 (JD= 1583196.582765)
+           Rising angle:  55.912d
+----------------------------------------------------------------------
+
+```
+
+```python
+# Generates a 2-day contrast time-series report at 6-minute intervals
+sirius.twilight_tomography(year=-378, phenomena="heliacal", city="Babylon", k=0.20, day_offset=(0, 1))
+
+```
+
+```text
+Search for Sirius Heliacal Appearance in the East before sunrise:
+======================================================================
+Search starting at Babylon:  -378-01-1.0
+   First sight found at:  -378-07-23.08 (JD= 1583196.582765)
+           Rising angle:  55.912d
+----------------------------------------------------------------------
+Scanning Sirius visibility in Babylon ( -378-07-23.0)
+at 6 sidereal minutes interval (backward)
+Day Offset: 0
+Current Extinction Coefficient value: k = 0.2
+|sun_ele |star_ele |     phi |Vis. |m_real | m_lim | Contrast
+|--------|---------|---------|-----|-------|-------|---------------------
+| -0.041 |  10.885 |  54.736 | No  | -0.43 | -5.78 | 
+| -2.014 |   9.766 |  54.943 | No  | -0.32 | -3.69 | 
+| -3.131 |   8.641 |  54.949 | No  | -0.18 | -2.52 | 
+| -4.239 |   7.510 |  54.956 | No  | -0.00 | -1.35 | 
+| -5.338 |   6.376 |  54.965 | No  |  0.23 | -0.19 | 
+| -6.428 |   5.242 |  54.975 | Yes |  0.54 |  0.96 | ###
+| -7.507 |   4.112 |  54.988 | Yes |  0.99 |  2.08 | ########
+| -8.576 |   2.995 |  55.006 | Yes |  1.65 |  3.15 | ############
+| -9.635 |   1.910 |  55.033 | Yes |  2.68 |  4.14 | ###########
+|-10.681 |   0.897 |  55.081 | Yes |  4.33 |  4.94 | ####
+-------------------------------------------------------------------------
+Scanning Sirius visibility in Babylon ( -378-07-22.0)
+at 6 sidereal minutes interval (backward)
+Day Offset: 1
+Current Extinction Coefficient value: k = 0.2
+|sun_ele |star_ele |     phi |Vis. |m_real | m_lim | Contrast
+|--------|---------|---------|-----|-------|-------|---------------------
+| -1.888 |   9.028 |  54.332 | No  | -0.23 | -3.84 | 
+| -3.004 |   7.899 |  54.339 | No  | -0.07 | -2.66 | 
+| -4.111 |   6.765 |  54.347 | No  |  0.14 | -1.49 | 
+| -5.209 |   5.631 |  54.356 | No  |  0.42 | -0.33 | 
+| -6.298 |   4.498 |  54.367 | No  |  0.81 |  0.81 | 
+| -7.376 |   3.376 |  54.382 | Yes |  1.39 |  1.93 | ####
+| -8.444 |   2.277 |  54.404 | Yes |  2.27 |  3.01 | #####
+| -9.501 |   1.232 |  54.441 | Yes |  3.68 |  4.01 | ##
+|-10.546 |   0.297 |  54.506 | No  |  5.89 |  4.85 | 
+-------------------------------------------------------------------------
 
 ```
 
@@ -202,8 +284,8 @@ The complete user manual, tutorials, and mathematical references are available a
 * **Mathematical Metrology**: Structured upon the breakthrough historical analyses of **Christine Proust** (*Tablettes mathématiques de Nippur*, 2007) and canonical scribal lexical lists.
 * **Archaeoastronomy & Eclipses**: Driven by the raw ephemeris computational methods and historical eclipse logs compiled in NASA's *Five Millennium Canon of Eclipses* by **Fred Espenak and Jean Meeus**.
 * **Chronological Registers**: Grounded on the empirical data frameworks from *Babylonian Chronology: 626 B.C. – A.D. 75*, by **Richard A. Parker and Waldo H. Dubberstein** (2nd edition, Brown University Press, 1971).
+* **Ephemeris Validation**: Elwood C. Downey's **XEphem** has been continuously utilized during development as an independent computational baseline to audit the mathematical accuracy of the underlying engine.
 
 ---
 
-**Developed by [jccsvq](https://github.com/jccsvq?tab=repositories)**
-
+**Developed by [jccsvq**](https://github.com/jccsvq?tab=repositories)

mesomath-2.2.0/README.md

@@ -0,0 +1,253 @@
+# 🏺 MesoMath v2.2
+**The Mesopotamian Computational Engine for Python.**
+
+[![PyPI - Version](https://img.shields.io/pypi/v/mesomath.svg)](https://pypi.org/project/mesomath/)
+[![PyPI - Status](https://img.shields.io/pypi/status/mesomath.svg)](https://pypi.org/project/mesomath/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![Hatch project](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pypa/hatch/master/docs/assets/badge/v0.json)](https://github.com/pypa/hatch)
+[![Documentation Status](https://readthedocs.org/projects/mesomath/badge/?version=latest)](https://mesomath.readthedocs.io)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jccsvq/mesomath-nb/main?labpath=notebooks%2Findex.ipynb)
+
+MesoMath is a high-precision computational framework engineered for the rigorous study of ancient Mesopotamian:
+
+* **Mathematics**
+  * Sexagesimal integer arithmetic (absolute and floating)
+  * Fraction arithmetic
+* **Metrology**
+  * Old Babylonian Period metrology (length, surface, volume, weight, capacity, and bricks)
+  * User-extensible framework for other historical periods
+  * NPVS Systems S, G, C, and K
+  * Socio-economic applications
+* **Chronology**
+  * Based on Parker and Dubberstein (1971) for the period 626 B.C. – A.D. 75
+  * *Proleptic* lunar calendar engine for other historical eras
+* **Timekeeping & Archaeoastronomy**
+  * Lunar and Planetary Ephemerides
+  * Heliacal and Acronychal Rising of stars (Atmospheric 3D scattering models)
+  * Built-in catalog of relevant Mesopotamian astronomical sites
+  * Built-in catalog of critical historical stars
+  * Custom user-defined sites and stars support
+
+MesoMath provides:
+* **Native Command-Line Environments (CLI)**: `babcalc` (basic) and `ibabcalc` (full-featured interactive shell).
+* **Jupyter Notebook Integration** for reproducible research.
+* **Authentic Epigraphic Support**: Old Babylonian transliteration standards and Unicode cuneiform rendering.
+
+---
+
+## ✨ What's New in v2.2.0?
+
+MesoMath v2.2.0 introduces the `BabStar` class, enabling high-fidelity search, physical contrast tracking, and multi-day **Twilight Tomography** for Heliacal and Acronychal stellar phenomena.
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+Install the complete environment globally using `pipx` (recommended for CLI apps):
+
+```bash
+$ pipx install mesomath
+
+```
+
+### The Scribal Console
+
+Launch the pre-configured advanced interactive environment:
+
+```bash
+$ ibabcalc
+
+```
+
+### 1. Dimensional Arithmetic & Fractions
+
+MesoMath manages geometric dimensions and base-60 rational numbers natively:
+
+```python
+from mesomath import Blen, Bsur
+
+# Objects understand localized metrological ratios
+width = Blen('3 ninda')
+area = Bsur('1 sar')
+
+# Dimensional descent via division engine
+length = area / width
+print(length.prtf())  # Output: '1/3 ninda'
+
+```
+
+### 2. Epigraphic Authenticity
+
+Export mathematical computations directly into cuneiform strings or scholarly transliterations:
+
+```python
+from mesomath import Bcap
+
+vol = Bcap('3 bariga 2 ban')
+print(vol.translit)   # Output: '3(barig) 2(ban2) še'
+print(vol.cuneiform)  # Output: itri  samot 𒊺
+
+```
+
+### 3. Chronology & Archaeoastronomy
+
+Translate continuous timeline anchors into historical calendars and calculate complex planetary visibilities:
+
+```python
+from mesomath import ChronDate
+
+# Instantiate a target Julian date
+date = ChronDate.from_julian(-378, 5, 17)
+print(date.babylonian)
+# Output: 'Year 26 of Artaxerxes II, month: 2 (Aiaru), day: 14'
+
+```
+
+```python
+# Generate localized micro-historical data grids
+date.day_ephemeris(city='Susa')
+
+```
+
+```text
+=================================================================
+                MESOPOTAMIAN DAILY EPHEMERIS: SUSA                
+=================================================================
+  Julian Day:  1583129.5       | Civil Calendar: Julian (-378/5/17)
+  Chronology:  Year 26 of Artaxerxes II, month: 2 (Aiaru), day: 14
+-----------------------------------------------------------------
+  SOLAR CONTEXT:
+    Sunrise : 01:46 UT | Sunset : 15:32 UT
+    Transit : 08:39 UT | Season : Day: 52 of spring
+-----------------------------------------------------------------
+  LUNAR INTERVALS (Phenomena in current lunation):
+    [Neomenia] NA Interval: -68.35 min (Time from Sunset to Moonset)
+    [Mid-Month] MI-MUSH:    19.77 min (Simultaneous visibility)
+    [End-Month] KUR:        -894.34 min (Dawn crescent disappearance)
+-----------------------------------------------------------------
+  PLANETARY VISIBILITY ( Twilight vs. Arc of Vision ):
+    * Mercury    -> Invisible / Glare          (Required Av: 12.0°)
+    * Venus      -> VISIBLE (Morning Star)     (Required Av: 6.0°)
+    * Mars       -> VISIBLE (Morning Star)     (Required Av: 14.0°)
+    * Jupiter    -> VISIBLE (Evening Star)     (Required Av: 9.0°)
+    * Saturn     -> VISIBLE (Evening Star)     (Required Av: 11.0°)
+=================================================================
+
+```
+
+```python
+# Visualize the sky timeline across ancient nocturnal watches
+date.night_at_a_glance(city='Susa')
+
+```
+
+```text
+===================================================================
+    Night at a Glance: Susa (-378-05-17)
+===================================================================
+UT Hours:  09  11  13  15  17  19  21  23  01  03  05  07  09  
+Local H.:  12  14  16  18  20  22  00  02  04  06  08  10  12  
+-------------------------------------------------------------------
+ Sky/Sun :  #############::.               .::###############
+-------------------------------------------------------------------
+ Moon    :               =====================                 
+-------------------------------------------------------------------
+ Mercury :  ----------                     -----------------
+ Venus   :  ------------                   ----------------
+ Mars    :  -                           --------------------- 
+ Jupiter :            -----------------------                  
+ Saturn  :  ------------------------                     -----
+===================================================================
+Legend:  # Day  : Civ/Nav Twilight  . Ast Twilight    Night
+         - Planet above horizon     = Moon above horizon
+
+```
+
+```python
+# Search for Sirius' Heliacal Rising in 378 BCE
+from mesomath import BabStar
+
+sirius = BabStar.from_catalog("Sirius")
+sirius.search_phenomena(-378)
+
+```
+
+```text
+Search for Sirius Heliacal Appearance in the East before sunrise:
+======================================================================
+Search starting at Babylon:  -378-01-1.0
+   First sight found at:  -378-07-23.08 (JD= 1583196.582765)
+           Rising angle:  55.912d
+----------------------------------------------------------------------
+
+```
+
+```python
+# Generates a 2-day contrast time-series report at 6-minute intervals
+sirius.twilight_tomography(year=-378, phenomena="heliacal", city="Babylon", k=0.20, day_offset=(0, 1))
+
+```
+
+```text
+Search for Sirius Heliacal Appearance in the East before sunrise:
+======================================================================
+Search starting at Babylon:  -378-01-1.0
+   First sight found at:  -378-07-23.08 (JD= 1583196.582765)
+           Rising angle:  55.912d
+----------------------------------------------------------------------
+Scanning Sirius visibility in Babylon ( -378-07-23.0)
+at 6 sidereal minutes interval (backward)
+Day Offset: 0
+Current Extinction Coefficient value: k = 0.2
+|sun_ele |star_ele |     phi |Vis. |m_real | m_lim | Contrast
+|--------|---------|---------|-----|-------|-------|---------------------
+| -0.041 |  10.885 |  54.736 | No  | -0.43 | -5.78 | 
+| -2.014 |   9.766 |  54.943 | No  | -0.32 | -3.69 | 
+| -3.131 |   8.641 |  54.949 | No  | -0.18 | -2.52 | 
+| -4.239 |   7.510 |  54.956 | No  | -0.00 | -1.35 | 
+| -5.338 |   6.376 |  54.965 | No  |  0.23 | -0.19 | 
+| -6.428 |   5.242 |  54.975 | Yes |  0.54 |  0.96 | ###
+| -7.507 |   4.112 |  54.988 | Yes |  0.99 |  2.08 | ########
+| -8.576 |   2.995 |  55.006 | Yes |  1.65 |  3.15 | ############
+| -9.635 |   1.910 |  55.033 | Yes |  2.68 |  4.14 | ###########
+|-10.681 |   0.897 |  55.081 | Yes |  4.33 |  4.94 | ####
+-------------------------------------------------------------------------
+Scanning Sirius visibility in Babylon ( -378-07-22.0)
+at 6 sidereal minutes interval (backward)
+Day Offset: 1
+Current Extinction Coefficient value: k = 0.2
+|sun_ele |star_ele |     phi |Vis. |m_real | m_lim | Contrast
+|--------|---------|---------|-----|-------|-------|---------------------
+| -1.888 |   9.028 |  54.332 | No  | -0.23 | -3.84 | 
+| -3.004 |   7.899 |  54.339 | No  | -0.07 | -2.66 | 
+| -4.111 |   6.765 |  54.347 | No  |  0.14 | -1.49 | 
+| -5.209 |   5.631 |  54.356 | No  |  0.42 | -0.33 | 
+| -6.298 |   4.498 |  54.367 | No  |  0.81 |  0.81 | 
+| -7.376 |   3.376 |  54.382 | Yes |  1.39 |  1.93 | ####
+| -8.444 |   2.277 |  54.404 | Yes |  2.27 |  3.01 | #####
+| -9.501 |   1.232 |  54.441 | Yes |  3.68 |  4.01 | ##
+|-10.546 |   0.297 |  54.506 | No  |  5.89 |  4.85 | 
+-------------------------------------------------------------------------
+
+```
+
+---
+
+## 📚 Documentation
+
+The complete user manual, tutorials, and mathematical references are available at [mesomath.readthedocs.io](https://mesomath.readthedocs.io).
+
+---
+
+## 🏛️ Acknowledgments & Sources
+
+* **Mathematical Metrology**: Structured upon the breakthrough historical analyses of **Christine Proust** (*Tablettes mathématiques de Nippur*, 2007) and canonical scribal lexical lists.
+* **Archaeoastronomy & Eclipses**: Driven by the raw ephemeris computational methods and historical eclipse logs compiled in NASA's *Five Millennium Canon of Eclipses* by **Fred Espenak and Jean Meeus**.
+* **Chronological Registers**: Grounded on the empirical data frameworks from *Babylonian Chronology: 626 B.C. – A.D. 75*, by **Richard A. Parker and Waldo H. Dubberstein** (2nd edition, Brown University Press, 1971).
+* **Ephemeris Validation**: Elwood C. Downey's **XEphem** has been continuously utilized during development as an independent computational baseline to audit the mathematical accuracy of the underlying engine.
+
+---
+
+**Developed by [jccsvq**](https://github.com/jccsvq?tab=repositories)

{mesomath-2.1.1 → mesomath-2.2.0}/docs/source/api_mesotimes.rst

@@ -54,7 +54,6 @@ Core
 Sun
 ...
 
-
 .. automodule:: mesotimes.astronomy.sun
    :members:
 
@@ -78,3 +77,14 @@ Planets
 .. automodule:: mesotimes.astronomy.planets.superiors
    :members:
    :show-inheritance:
+
+Stars (BabStar)
+...............
+
+.. autoclass:: mesotimes.BabStar
+   :members:
+   :special-members: __init__
+   :undoc-members:
+
+.. automodule:: mesotimes.astronomy.visibility
+   :members:

{mesomath-2.1.1 → mesomath-2.2.0}/docs/source/intro.md

@@ -1,11 +1,11 @@
 
-# Introduction to MesoMath (v2.1.0)
+# Introduction to MesoMath ({{ release }})
 
 **MesoMath** is more than just a calculator; it is a digital bridge to the mathematical and astronomical mind of the ancient Mesopotamian scribe. While modern mathematics relies on abstract decimal notation, the Old Babylonian period (c. 1900–1600 BCE) developed a sophisticated sexagesimal (base-60) system that combined floating-point arithmetic with a complex web of metrological units and elastic, horizon-based timekeeping frameworks.
 
 ## The MesoMath Ecosystem
 
-MesoMath 2.1.0 expands its unified workflow by transitioning into a comprehensive metapackage. It couples core scribal mathematics with advanced historical chronology and archaeoastronomy, tailored to the needs of researchers from quick terminal calculations to reproducible academic analysis:
+Since version 2.1.0 MesoMath expands its unified workflow by transitioning into a comprehensive metapackage. It couples core scribal mathematics with advanced historical chronology and archaeoastronomy, tailored to the needs of researchers from quick terminal calculations to reproducible academic analysis:
 
 ### 1. Command-Line Environments (CLI)
 
@@ -44,7 +44,7 @@ The MesoMath engine does not merely compute; it documents. All results can be ex
 
 * **Precise Event Ephemeris**: Calculated directly with the [`pymeeus` library](https://github.com/architest/pymeeus) (VSOP87, ELP85) up to the current limit of knowledge of the parameter `Delta T`.
 * **Internal Database of Historical Eclipses**: Solar and Lunar eclipses visible at Kish (total and partial) based on the [*Five Millennium Canon of Eclipses* by Fred Espenak and Jean Meeus](https://eclipse.gsfc.nasa.gov/SEpubs/5MCSE.html).
-
+* **Heliacal and Acronychal Rising of Stars**: Precise dating and dissection/tomography of twilight lights to reveal the temporal evolution of the contrast between the star and the twilight background.
 -----
 
 ## Project Architecture
@@ -59,6 +59,7 @@ MesoMath has shifted into a structural metapackage architecture, decoupling core
 
 2. **The `mesotimes` Package Core Engine**:
    * `date.py`: Chronological, calendrical, and astronomical dispatchers (`ChronDate`).
+   * `stars.py` and `visibility.py`: Search and analysis of heliacal/acronychal star phenomena.
 
 3. **Unified API**: Legacy standalone utilities (formerly `mtlookup`, `bmultable`) are integrated directly into the core classes, streamlining the developer experience. Methods like `Blen.lookup()` or `BabN.multable()` are now standard.
 

{mesomath-2.1.1 → mesomath-2.2.0}/docs/source/references.md

@@ -114,4 +114,30 @@ This bibliography provides the academic and historical foundations for the metro
 
 (ref-PyMeeus)=
 * **Arribas, J. L.** (2020). *PyMeeus: Astronomical Algorithms in Python*. Python Software Foundation. Available at: https://github.com/leasw/pymeeus
-> *Note: Python implementation of Meeus' algorithms used as a validation layer for specific internal ephemeris loops.*
+> *Note: Python implementation of Meeus' algorithms used as a validation layer for specific internal ephemeris loops.*
+
+## Stellar Visibility
+
+(ref-Schoch1924)=
+* **Schoch, C.** (1924). *The Arcus Visionis of the Planets in Babylonian Astronomy*. Monthly Notices of the Royal Astronomical Society, 84(9), 731–734.
+> *Note: Traditional geometric baseline for Babylonian stellar and planetary visibility calculations.*
+
+(ref-Schaefer1993)=
+* **Schaefer, B. E.** (1993). *Astronomy and the Limiting Magnitude of the Naked Eye*. Publications of the Astronomical Society of the Pacific, 105(688), 651–661.
+> *Note: Fundamental paper for the 1D ramp model and human visual contrast threshold equations against sky brightness.*
+
+(ref-Schaefer2000)=
+* **Schaefer, B. E.** (2000). *The Heliacal Rise of Sirius and Ancient Chronology*. Journal for the History of Astronomy, 31(2), 149–155.
+> *Note: Direct application of atmospheric extinction and scattering models to the specific historical problem of the rising of Sirius.*
+
+(ref-Garstang1989)=
+* **Garstang, R. H.** (1989). *Night-sky Brightness at Observatories and Sites*. Publications of the Astronomical Society of the Pacific, 101, 306–329.
+> *Note: Mathematical foundation for the 3D visibility framework, containing Rayleigh and aerosol scattering phase functions.*
+
+(ref-Pickering2002)=
+* **Pickering, K. A.** (2002). *The Southern Limits of the Ancient Star Catalog and the Commentary of Hipparchos*. DIO, 12, 3–27.
+> *Note: Reference study for ancient star catalog boundaries and historical stellar visibility constraints.*
+
+(ref-KastenYoung1989)=
+* **Kasten, F. and Young, A. T.** (1989). *Revised optical air mass tables and approximation formula*. Applied Optics, 28(22), 4735–4738.
+> *Note: Reference formulation for atmospheric optical air mass calculations at low horizons and high zenith angles.*