MesoTimes Ecosystem (Chronology and Astronomy)

MesoTimes Ecosystem (Chronology and Astronomy)#

Integrated astronomical module as an alpha preview for time management and horizons.

The Facade of Times#

Date (ChronDate)#

class ChronDate(jd: float)#

Main user-facing chronological anchor.

Acts as a Facade unifying historical calendars, lunar intervals, and planetary phenomena based on a continuous timeline.

Initializes a ChronDate instance via a Julian Day.

Parameters:: jd (float) – Julian Day number (UT).

classmethod from_babylonian(king_code: str, year: int, month: float, day: int, hour: int = 0, minute: int = 0, second: int = 0) → ChronDate#

Creates a ChronDate instance from a Babylonian historical date.

Parameters:

king_code (str) – Regnal abbreviations matching canonical cuneiform records.
year (int) – Regnal year of the designated king.
month (float) – Month number (intercalary months represented as floats).
day (int) – Day of the Babylonian lunar month (1 to 30).
hour (int, optional) – Hour of the day. Defaults to 0.
minute (int, optional) – Minute of the hour. Defaults to 0.
second (int, optional) – Second of the minute. Defaults to 0.

Returns:

An initialized instance anchored to the calculated Julian Day.

Return type:

ChronDate

classmethod from_gregorian(year: int, month: int, day: int, hour: int = 0, minute: int = 0, second: int = 0) → ChronDate#

Creates a ChronDate instance from a Proleptic Gregorian calendar date.

Parameters:

year (int) – Astronomical year (negative for BCE dates).
month (int) – Month index (1 to 12).
day (int) – Civil day number.
hour (int, optional) – Hour of the day. Defaults to 0.
minute (int, optional) – Minute of the hour. Defaults to 0.
second (int, optional) – Second of the minute. Defaults to 0.

Returns:

An initialized instance anchored to the calculated Julian Day.

Return type:

ChronDate

classmethod from_julian(year: int, month: int, day: int, hour: int = 0, minute: int = 0, second: int = 0) → ChronDate#

Creates a ChronDate instance from a Proleptic Julian calendar date.

Parameters:

year (int) – Astronomical year (negative for BCE dates).
month (int) – Month index (1 to 12).
day (int) – Civil day number.
hour (int, optional) – Hour of the day. Defaults to 0.
minute (int, optional) – Minute of the hour. Defaults to 0.
second (int, optional) – Second of the minute. Defaults to 0.

Returns:

An initialized instance anchored to the calculated Julian Day.

Return type:

ChronDate

classmethod kings() → list[str]#: Lists King codes, names and peripd start.

static _dt2lon(seconds: float) → tuple[float, float, float]#

Helper to map clock seconds into angular degrees, minutes, and seconds of arc.

1 temporal second equals 15 seconds of arc (360° / 24h = 15°/h = 15’/min = 15”/s).

static _format_hours(decimal_hours: float) → str#

Internal helper to format decimal raw hours into standard sexagesimal terminal clocks.

Parameters:: decimal_hours (float) – Time representation in decimal format.
Returns:: Normalized time string in “HH:MM” format, or “N/A” if input is NaN.
Return type:: str

static sites(cities_dict: dict = {'Assur': {'altitude': 165, 'description': 'Assyrian religious capital with early observations.', 'latitude': 35.4567, 'longitude': 43.2625, 'modern_name': "Qal'at Sherqat, Iraq"}, 'Babylon': {'altitude': 26, 'description': 'Main center of the astronomical diaries (Esagila).', 'latitude': 32.543, 'longitude': 44.4244, 'modern_name': 'Al Hillah, Iraq'}, 'Borsippa': {'altitude': 30, 'description': 'Sister city of Babylon with an important ziggurat (associated with Nabu).', 'latitude': 32.3917, 'longitude': 44.3417, 'modern_name': 'Birs Nimrud, Iraq'}, 'Eridu': {'altitude': 6, 'description': 'Considered the oldest city; relevant to the cosmogony associated with the sea horizon.', 'latitude': 30.8158, 'longitude': 45.9961, 'modern_name': 'Tell Abu Shahrein, Iraq'}, 'Harran': {'altitude': 377, 'description': 'Main center of worship of the god Sin (the Moon). Fundamental for lunar observations in the north.', 'latitude': 36.8625, 'longitude': 39.025, 'modern_name': 'Harran, Turkey'}, 'Kish': {'altitude': 29, 'description': 'A site of great antiquity, mentioned in royal lists and eclipse records.', 'latitude': 32.5453, 'longitude': 44.6033, 'modern_name': 'Tell al-Uhaymir, Iraq'}, 'Larsa': {'altitude': 20, 'description': 'Ancient solar center relevant for astronomical observations.', 'latitude': 31.2858, 'longitude': 45.8533, 'modern_name': 'Tell as-Senkereh, Iraq'}, 'Nineveh': {'altitude': 223, 'description': 'Seat of the library of Ashurbanipal, rich in texts of celestial omens (Enuma Anu Enlil).', 'latitude': 36.3583, 'longitude': 43.1517, 'modern_name': 'Mosul, Iraq'}, 'Nippur': {'altitude': 25, 'description': 'Religious center and lunar calendar calibration center.', 'latitude': 32.1264, 'longitude': 45.2319, 'modern_name': 'Afak, Iraq'}, 'Sevilla': {'altitude': 20, 'description': 'Non-Mesopotamian test node (internal verification).', 'latitude': 37.40855, 'longitude': -5.92328, 'modern_name': 'Seville, Spain'}, 'Sippar': {'altitude': 32, 'description': 'City of the sun god (Utu/Shamash), relevant for solstice calculations.', 'latitude': 33.0594, 'longitude': 44.2525, 'modern_name': 'Tell Abu Habbah, Iraq'}, 'Susa': {'altitude': 78, 'description': 'Capital of Elam; seat of administrative and astronomical archives shared with Mesopotamia.', 'latitude': 32.1892, 'longitude': 48.2436, 'modern_name': 'Shush, Iran'}, 'Ur': {'altitude': 5, 'description': 'Key Sumerian city with an astronomically aligned ziggurat.', 'latitude': 30.9625, 'longitude': 46.1031, 'modern_name': 'Tell el-Muqayyar, Iraq'}, 'Uruk': {'altitude': 21, 'description': 'Important center of observation and late mathematical/astronomical texts.', 'latitude': 31.3222, 'longitude': 45.6361, 'modern_name': 'Warka, Iraq'}}) → None#

Prints a formatted, scannable table of Mesopotamian observatories and their geographical coordinates.

Parameters:: cities_dict (dict) – Dictionary containing city metadata and coordinates.

__init__(jd: float) → None#

Initializes a ChronDate instance via a Julian Day.

Parameters:: jd (float) – Julian Day number (UT).

_get_context()#

Get historical context for this date from database

Returns:: Database matches.
Return type:: iterable

_run_planet_almanac(planet_instance: Any, title: str) → None#

Private generic template dispatcher that dynamic loops through standard planet phenomena lists.

Recalculates Delta T independently for each node collision to safely isolate civil UT frames.

bab_day_info(city: str = 'Babylon', ziggurat: float = 0.0) → None#

Prints a comprehensive dashboard for the localized sunset-to-sunset Babylonian day.

Parameters:

city (str, optional) – Target ancient observation city. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height above terrain in meters. Defaults to 0.0.

bab_day_instance(city: str = 'Babylon', ziggurat: float = 0.0) → BabylonianDay#

Instantiates a localized BabylonianDay framework matching this instance’s Julian Day.

Parameters:

city (str, optional) – Ancient observation site registry name. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height above terrain in meters. Defaults to 0.0.

Returns:

A localized day metrics framework mapping sunset-to-sunset boundaries.

Return type:

BabylonianDay

bab_year_calendar(city: str = 'Babylon', ziggurat: float = 0.0)#

Prints a human-readable table of the Babylonian year structure.

Parameters:

city (str, optional) – Observatory location, defaults to “Babylon”
ziggurat (float, optional) – Altitude above the ground level in meters, defaults to 0.0

day_ephemeris(city: str = 'Babylon', ziggurat: float = 0.0) → None#

Prints a comprehensive astronomical profile for the local Mesopotamian sky.

Outputs solar context, lunar intervals, and twilight planetary visibilities for this specific Julian Day to the standard output.

Parameters:

city (str, optional) – Target Mesopotamian city registry. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height above ground level in meters. Defaults to 0.0.

get_bab_day_data(city: str = 'Babylon', ziggurat: float = 0.0) → dict[str, float]#

Computes exact durations and boundaries of the Babylonian civil day (sunset-to-sunset).

Parameters:

city (str, optional) – Target Mesopotamian city registry. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height above ground level in meters. Defaults to 0.0.

Returns:

Dictionary containing complete diurnal/nocturnal breakdowns:

’duration’: Total length of the local civil day.
’diurnal’: Length of daylight interval.
’nocturnal’: Length of nighttime interval.
’start_previous_sunset_ut’: UT epoch marking the true start of the Babylonian day.
’sunrise_ut’: Middle daylight transition.
’transit_ut’: Solar culmination.
’end_sunset_ut’: UT epoch closing the current Babylonian day.

Return type:

dict[str, float]

get_babylonian_month_data(city: str = 'Babylon', ziggurat: float = 0.0, db_filename: str = 'mesotimes.sqlite', AoV: float = 12.0, uncertainty: float = 0.833) → LunarAlmanac#

Initializes and synchronizes a LunarAlmanac instance for the current civil month.

Applies an automated algorithmic epoch advancement check if the localized first crescent visibility (neomenia) has drifted into adjacent lunations.

Parameters:

city (str, optional) – Target Mesopotamian city registry. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height above ground level in meters. Defaults to 0.0.
db_filename (str, optional) – SQLite database filename path. Defaults to “mesotimes.sqlite”.
AoV (float, optional) – Empirical Arc of Vision in degrees for neomenia. Defaults to 12.0.
uncertainty (float, optional) – Marginal visibility filtering factor. Defaults to 0.833.

Returns:

A fully scanned and synchronized lunar almanac instance.

Return type:

LunarAlmanac

get_day_planetary_visibility(city: str = 'Babylon', ziggurat: float = 0.0) → dict[str, dict[str, Any]]#

Evaluates true heliacal visibility statuses for the 5 classical planets.

Checks geometric altitude against empirical Babylonian Arcs of Vision both at local astronomical dawn (Morning Star) and dusk (Evening Star).

Parameters:

city (str, optional) – Target Mesopotamian city registry. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height above ground level in meters. Defaults to 0.0.

Returns:

Nested map of planetary visibility flags and vision constraints.

Return type:

dict[str, dict[str, Any]]

get_julian_month_phases() → list[dict[str, Any]]#

Calculates exact lunar phases falling within the current civil month.

Implements a continuous dynamic grid sweep to eliminate boundary blind spots caused by timezone transitions and delta T shifts.

Returns:

Cronologically sorted dictionaries detailing phase names,: underlying PyMeeus UT Epochs, and formatted date strings.

Return type:

list[dict[str, Any]]

get_kur_data(city: str = 'Babylon', ziggurat: float = 0.0) → dict[str, Any]#

Computes the KUR lunar interval for the last visible wane before conjunction.

Parameters:

city (str, optional) – Target Mesopotamian city registry. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height above ground level in meters. Defaults to 0.0.

Returns:

Calculated parameters including visibility thresholds.

’status’ (str): Evaluated atmospheric visibility (‘VISIBLE’, ‘CRITICAL’, ‘INVISIBLE’).

Return type:

dict[str, Any]

get_lunar_horizon_data(city: str = 'Babylon', ziggurat: float = 0.0) → dict[str, float]#

Computes the exact decimal Universal Time (UT) hours for lunar horizon events.

Parameters:

city (str, optional) – Target Mesopotamian city registry. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height above ground level in meters. Defaults to 0.0.

Returns:

Dictionary containing ‘moonrise_ut’, ‘transit_ut’, and ‘moonset_ut’.

Return type:

dict[str, float]

get_lunar_intervals(city: str = 'Babylon', ziggurat: float = 0.0) → dict[str, float]#

Calculates and returns the classical Neo-Babylonian lunar intervals for the lunation.

Parameters:

city (str, optional) – Target Mesopotamian city registry. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height above ground level in meters. Defaults to 0.0.

Returns:

Dictionary containing:

’na’: Time between sunset and moonset after New Moon (or vice versa at Full Moon).
’mi_mush’: Lunar visibility interval during the night.
’kur’: Time between moonrise and sunrise before conjunction.

Return type:

dict[str, float]

get_mi_mush_data(city: str = 'Babylon', ziggurat: float = 0.0) → dict[str, Any]#

Computes the MI-MUSH lunar interval in both standard minutes and Babylonian UŠ units.

MI-MUSH defines the duration of simultaneous visibility of the Sun and Moon on the night of the full moon.

Parameters:

city (str, optional) – Target Mesopotamian city registry. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height above ground level in meters. Defaults to 0.0.

Returns:

Calculated parameters including intervals, raw UT times, and visibility flags.

’interval_minutes’ (float): Visibility time in minutes.
’interval_ush’ (float): Visibility time in UŠ (1 UŠ = 4 minutes).
’visible_simultaneously’ (bool): True if structural overlapping occurs.

Return type:

dict[str, Any]

get_planetary_events() → dict[str, dict[str, Any]]#

Finds the chronologically closest oppositions, stations, and elongations for the 5 classical planets.

Returns:: Structured dict mapped by planet names containing event description and Julian Day.
Return type:: dict[str, dict[str, Any]]

get_sun_data(city: str = 'Babylon', ziggurat: float = 0.0) → dict[str, float]#

Computes exact solar ephemerides in Universal Time (UT) for the instance date.

Parameters:

city (str, optional) – Target Mesopotamian city registry. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height above ground level in meters. Defaults to 0.0.

Returns:

Dictionary containing ‘sunrise_ut’, ‘transit_ut’, and ‘sunset_ut’ as float days.

Return type:

dict[str, float]

get_year_delta_t_data() → dict[str, Any]#

Computes Delta T (ΔT) and its standard error (sigma) for the current year.

Extrapolates the respective structural shifts in geographical longitude (angular arc drift due to Earth’s rotational deceleration).

Returns:

Ephemeris correction metrics containing:

’delta_t_seconds’ (float): Total temporal discrepancy.
’delta_t_str’ (str): Formatted ISO timedelta string representation.
’delta_t_lon’ (tuple): Resulting spatial shift in (Degrees, Minutes, Seconds) of arc.
’sigma_seconds’ (float | None): Uncertainty bounds if within valid matrices.

Return type:

dict[str, Any]

get_year_eclipses() → list[dict[str, Any]]#

Queries the internal historical database to retrieve all recorded eclipses

visible from the Kish station during the current Julian year.

Returns:

A list of dictionaries containing:

’year’ (int): Historical Julian year.
’month’ (int): Civil month.
’day’ (int): Civil day.
’type’ (str): Eclipse nature (‘SOLAR’, ‘LUNAR’).
’magnitude’ (float): Calculated astronomical magnitude.

Return type:

list[dict[str, Any]]

get_year_planetary_events() → dict[str, dict[str, Any]]#

Calculates major orbital phenomena (Oppositions, Stations, Conjunctions) for the current year.

Uses an intermediate mid-year search anchor to feed underlying numerical solvers.

Returns:: Structural map containing raw PyMeeus Epoch instances (Terrestrial Time, TT).
Return type:: dict[str, dict[str, Any]]

heliacal_phases(planet_name: str, city: str = 'Babylon', ziggurat: float = 0.0) → None#

Scans forward from the current date to resolve and print the next four heliacal phases

of a given planet. Translates raw Epoch results into both Julian and Babylonian calendars.

Parameters:

planet_name (str) – Name of the planet (mercury, venus, mars, jupiter, saturn).
city (str, optional) – Target ancient observation site. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height in meters. Defaults to 0.0.

jupiter_almanac() → None#: Prints all analytical astronomical phenomena for Jupiter within this temporal frame.

kur(city: str = 'Babylon', ziggurat: float = 0.0) → None#

Prints a mathematical audit of the late-lunation disappearance interval ‘KUR’.

Parameters:

city (str, optional) – Target Mesopotamian city registry. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height above ground level in meters. Defaults to 0.0.

lunar_info(city: str = 'Babylon', ziggurat: float = 0.0, AoV: float = 12.0, uncertainty: float = 0.833) → None#

Generates a monthly analytical report structured as a Babylonian cuneiform tablet.

Parameters:

city (str, optional) – Target ancient observation city. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height above ground level in meters. Defaults to 0.0.
AoV (float, optional) – Empirical Arc of Vision constraint. Defaults to 12.0.
uncertainty (float, optional) – Marginal visibility filtering factor. Defaults to 0.833.

mars_almanac() → None#: Prints all analytical astronomical phenomena for Mars within this temporal frame.

mercury_almanac() → None#: Prints all analytical astronomical phenomena for Mercury within this temporal frame.

mi_mush(city: str = 'Babylon', ziggurat: float = 0.0) → None#

Prints a detailed mathematical audit of the lunar opposition interval ‘MI-MUSH’.

Parameters:

city (str, optional) – Target Mesopotamian city registry. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height above ground level in meters. Defaults to 0.0.

month_almanac(city: str = 'Babylon', ziggurat: float = 0.0, db_filename: str = 'mesotimes.sqlite', AoV: float = 12.0, uncertainty: float = 0.833, full: bool = False) → None#

Prints a structured analytical summary of lunar phases for the current civil month.

Triggers an automated virtual tablet matrix reconstruction on the terminal.

Parameters:

city (str, optional) – Target ancient observation city. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height in meters. Defaults to 0.0.
db_filename (str, optional) – Internal SQLite filename database. Defaults to “mesotimes.sqlite”.
AoV (float, optional) – Empirical Arc of Vision constraint. Defaults to 12.0.
uncertainty (float, optional) – Marginal parsing threshold index. Defaults to 0.833.
full (bool, optional) – If True, dumps raw sequential lunar phase steps. Defaults to False.

moon_rise_transit_set(city: str = 'Babylon', ziggurat: float = 0.0) → None#

Dumps local lunar horizon ephemerides directly to the REPL pipeline.

Parameters:

city (str, optional) – Target Mesopotamian city registry. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height above ground level in meters. Defaults to 0.0.

neomenia(city: str = 'Babylon', ziggurat: float = 0.0, AoV: float = 12.0, uncertainty: float = 0.833) → None#

Executes and renders standard visibility criteria matrices for the primary Neomenia.

Parameters:

city (str, optional) – Target ancient observation city. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height in meters. Defaults to 0.0.
AoV (float, optional) – Empirical Arc of Vision constraint. Defaults to 12.0.
uncertainty (float, optional) – Marginal parsing threshold index. Defaults to 0.833.

night_at_a_glance(city: str = 'Babylon') → None#

Draws a visual ASCII horizontal timeline visibility chart of the Mesopotamian planets.

Optimizes calculation performance across the diurnal/nocturnal transition by caching body equatorial positions (RA/Dec) once per execution frame.

Parameters:: city (str, optional) – Target Mesopotamian observation site. Defaults to “Babylon”.

saturn_almanac() → None#: Prints all analytical astronomical phenomena for Saturn within this temporal frame.

sun_rise_transit_set(city: str = 'Babylon', ziggurat: float = 0.0) → None#

Prints the specific solar transit metrics alongside the three ancient Night Watches.

Calculates the exact temporal division for the maṣṣarātu based on fluid nocturnal arcs.

Parameters:

city (str, optional) – Target Mesopotamian city registry. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height above ground level in meters. Defaults to 0.0.

venus_almanac() → None#: Prints all analytical astronomical phenomena for Venus within this temporal frame.

year_almanac(city: str = 'Babylon', ziggurat: float = 0.0) → None#

Assembles and prints global solstices, equinoxes, planetary nodes, and annual eclipses.

Preceded by a critical diagnosis of Earth’s rotational deceleration parameter Delta T (ΔT).

Parameters:

city (str, optional) – Ancient observation site registry name. Defaults to “Babylon”.
ziggurat (float, optional) – Observer height above terrain in meters. Defaults to 0.0.

GREGORIAN_REFORM: float = 2299161.5#

MAX_JD: float = 1748872.5#

MIN_JD: float = 1492870.5#

_bab_conv = <mesotimes.calendars.BabylonianConverter object>#

_cal_conv = <mesotimes.calendars.CalendarConverter object>#

property _civil_components: tuple[int, int, int, str]#

Calculates, caches, and returns standard civil calendar components.

Differentiates between Proleptic Julian and Gregorian timelines using the canonical Gregorian Reform threshold.

property babylonian: str#: Formats and wraps Babylonian calendar parameters into a readable string for REPL inspection.

property babylonian_data: dict[str, Any]#

Algorithmic property that resolves the current Julian Day into raw Babylonian calendar structures.

Falls back to a structural Proleptic Babylonian Calendar algorithm if the date overflows historical table boundaries.

property context#: Print historical context for this date.

property gregorian: tuple[int, int, int]#: Returns the date in the Proleptic Gregorian Calendar as a (Year, Month, Day) tuple.

property is_babylonian: bool#: Checks if the Julian Day falls within the reliable historical constraints of P&D (1971).

property jd: float#: Returns the core astronomical Julian Day (UT).

property julian: tuple[int, int, int]#: Returns the date in the Proleptic Julian Calendar as a (Year, Month, Day) tuple.

property season_day#: Returns a string indicating the current day within the season.

Planetary and Heliacal Calculations#

astronomy/planets/finder.py - Root finder for Mesopotamian planetary phases.

find_first_appearance_morning(planet: Planet, start_epoch: Epoch, city: str = 'Babylon', ziggurat: float = 0.0) → Epoch#: Finds the First Heliacal Appearance in the East before sunrise (Phenomenon Gamma / Xi).

find_heliacal_event(planet: Planet, start_epoch: Epoch, horizon: Literal['sunrise', 'sunset'], search_type: Literal['appearance', 'disappearance'], city: str = 'Babylon', ziggurat: float = 0.0, max_days: int = 60) → Epoch#

Scans forward day-by-day from an astronomical baseline to locate the exact calendar day of a planet’s heliacal event (appearance or disappearance).

Parameters:

planet – The Mesopotamian planet instance.
start_epoch – The starting point for the scan (e.g., date of conjunction).
horizon – Target twilight horizon to evaluate (“sunrise” or “sunset”).
search_type – Whether we look for the first day of visibility (“appearance”) or the first day of total invisibility (“disappearance”).
city – Target city string registry.
ziggurat – Height of the observer structure in meters.
max_days – Safety limit for the iterative loop.

Returns:

The Epoch corresponding to the twilight of the resolved event day.

find_heliacal_event2(planet: Planet, start_epoch: Epoch, horizon: Literal['sunrise', 'sunset'], search_type: Literal['appearance', 'disappearance'], city: str = 'Babylon', ziggurat: float = 0.0, max_days: int = 60) → Epoch#

Scans forward day-by-day from an astronomical baseline to locate the exact calendar day of a planet’s heliacal event (appearance or disappearance).

Parameters:

planet – The Mesopotamian planet instance.
start_epoch – The starting point for the scan (e.g., date of conjunction).
horizon – Target twilight horizon to evaluate (“sunrise” or “sunset”).
search_type – Whether we look for the first day of visibility (“appearance”) or the first day of total invisibility (“disappearance”).
city – Target city string registry.
ziggurat – Height of the observer structure in meters.
max_days – Safety limit for the iterative loop.

Returns:

The Epoch corresponding to the twilight of the resolved event day.

find_last_appearance_evening(planet: Planet, start_epoch: Epoch, city: str = 'Babylon', ziggurat: float = 0.0) → Epoch#: Finds the Last Heliacal Appearance in the West after sunset (Phenomenon Omega / Sigma).

find_setting_heliacal_evening(planet: Planet, start_epoch: Epoch, city: str = 'Babylon', ziggurat: float = 0.0) → Epoch#: Finds the Evening Heliacal Setting/Disappearance in the West (Phenomenon Epsilon).

find_setting_heliacal_morning(planet: Planet, start_epoch: Epoch, city: str = 'Babylon', ziggurat: float = 0.0) → Epoch#: Finds the Morning Heliacal Setting/Disappearance in the East (Phenomenon Delta).

Models of Celestial Bodies#

`astronomy/core.py` - Core astronomical corrections, constants, and geodetic data.

This module provides low-level tools, algorithms (Horner’s method), historical time corrections (Delta T), and geodetic properties for ancient Mesopotamian sites.

_historical_gmst_degrees(epoch: Epoch) → float#

Calculates Greenwich Mean Sidereal Time (GMST) in degrees from an Epoch. Bypasses library limitations for ancient negative years. Reference: Meeus, Astronomical Algorithms, Chapter 12.

Parameters:: epoch (Epoch) – pymeeus.Epoch object
Returns:: GMST in decimal degrees [0.0, 360.0)
Return type:: float

_horner(x: float, a: list[float]) → float#

Evaluates a polynomial using Horner’s method.

Parameters:

x (float) – Independent variable
a (list[float]) – List of coefficients ordered from lowest to highest degree

Returns:

Polynomial evaluation value

Return type:

float

delta_t(year: int, month: int = 7) → float#

Calculates Delta T (ΔT), the difference between Terrestrial Time (TT) and Universal Time (UT) in seconds.

Uses the polynomial fits by Espenak and Meeus (NASA) to account for the deceleration of Earth’s rotation.

Parameters:

year (int) – Astronomical year (-1999 to 3000)
month (int, optional) – Month, defaults to 7 (mid-year pivot)

Raises:

ValueError – If year is outside the [-1999, 3000] range

Returns:

Delta T in seconds

Return type:

float

delta_t_sigma(year: int, month: int = 7) → float#

Calculates Delta T (ΔT) Uncertainty in seconds based on Espenak & Meeus (NASA). Covers the full historical range from ancient eras to future projections.

Parameters:

year (int) – Astronomical year (-1999 to 3000)
month (int, optional) – Month, defaults to 7

Returns:

Delta T (ΔT) Uncertainty estimates in seconds

Return type:

float

epsilon(year: int | float) → float#

Calculates the historical obliquity in decimal degrees. From Laskar (1986), Bibcode:1986A&A…157…59L

Parameters:: year (int|float) – Year
Returns:: Obliquity in decimal degrees
Return type:: float

equatorial_to_horizontal_at_instant(jd_ut: float, ra_hours: float, dec_deg: Angle, city_lon: float, city_lat: float) → tuple[Angle, Angle]#

Calculates geometric horizontal coordinates.

Parameters:

jd_ut (float) – Julian Day (UT)
ra_hours (float) – Right Ascension in decimal hours
dec_deg (Angle) – Declination in degrees
city_lon (float) – Geografic longitude of the city in degrees (East is positive)
city_lat (float) – Geografic latitude of the city in degrees (North is positive)

Returns:

Tuple elevation, azimut

Return type:

tuple[Angle, Angle]

get_body_equatorial_at_midnight(jd_ut: float, body_id: str, city: str = 'Babylon') → tuple[Angle, Angle]#

Computes fixed equatorial positions using the safe math.floor approach.

Parameters:

jd_ut (float) – Julian Day (UT)
body_id (str) – Body name
city (str, optional) – Observatory city name, defaults to “Babylon”

Returns:

Right Ascension and Declination

Return type:

tuple[Angle, Angle]

get_horizon_dip(altitude_m: float) → float#

Calculates the geometric dip of the horizon based on observer elevation.

Parameters:: altitude_m (float) – Height above local terrain in meters
Returns:: Horizon dip in decimal degrees
Return type:: float

jde2date(jd: float) → tuple[int, int, int]#

Converts a Julian Date (JD/JDE) to a calendar date tuple (Year, Month, Day).

Parameters:: jd (float) – Julian Day Number
Returns:: Year, month, day calendar units
Return type:: tuple[int, int, int]

astronomy/sun.py - Solar coordinates, cardinal events, and daytime metrics.

This module provides tools to compute solar ephemerides, equinoxes, solstices, local rotational times for sunrise/sunset, and the historical duration of the Babylonian day (sunset to sunset).

autumnal_equinox(year: int) → float#

Calculates the approximate Julian Date (JD) of the autumnal equinox. Based on J. Meeus’s Astronomical Algorithms, incorporating Delta T (ΔT) corrections for historical accuracy.

Range: -1000 to 3000

Parameters:: year (int) – Astronomical year
Returns:: Julian Date of the autumnal equinox
Return type:: float

bab_day_duration(jd: float, city: str = 'Babylon', ziggurat: float = 0.0) → tuple[float, float, float, float, float, float, float]#

Returns the duration parameters in hours for a specific Babylonian day (between two consecutive sunsets).

Parameters:

jd (float) – Julian Date representing the target day
city (str, optional) – City name, defaults to “Babylon”
ziggurat (float, optional) – Height above terrain in meters, defaults to 0.0

Returns:

Tuple containing (duration, diurnal, nocturnal, start UT, sunrise UT, transit UT, end UT) in decimal hours

Return type:

tuple[float, float, float, float, float, float, float]

get_season_day_str(year: int, month: int, day: int, calendar: Literal['julian', 'gregorian'] = 'julian') → str#

Returns a string indicating the current day count within its astronomical season. Example: ‘Day: 34 of spring’

Parameters:

year (int) – Calendar year
month (int) – Calendar month
day (int) – Calendar day
calendar (str, optional) – Calendar system (“julian” or “gregorian”), defaults to “julian”

Returns:

String indicating the current day within the season

Return type:

str

summer_solstice(year: int) → float#

Calculates the approximate Julian Date (JD) of the summer solstice. Based on J. Meeus’s Astronomical Algorithms, incorporating Delta T (ΔT) corrections for historical accuracy.

Range: -1000 to 3000

Parameters:: year (int) – Astronomical year
Returns:: Julian Date of the summer solstice
Return type:: float

sun_rise_transit_set(year: int, month: int, day: int, city: str = 'Babylon', ziggurat: float = 0.0) → tuple[float, float, float, float, float, float]#

Calculates solar rise, transit, and set times considering atmospheric refraction and observer elevation.

The geometric horizon is adjusted by -0.833° to account for standard refraction and solar semi-diameter. Elevation (ziggurat) adds a dip correction to the horizon.

Parameters:

year (int) – Calendar year
month (int) – Calendar month
day (int) – Calendar day
city (str, optional) – Name of the site in mesopotamian_cities, defaults to “Babylon”
ziggurat (float, optional) – Observer height above terrain in meters, defaults to 0.0

Returns:

(rise_ut, transit_ut, set_ut, rise_local, transit_local, set_local) in decimal hours.

Return type:

tuple[float, float, float, float, float, float]

vernal_equinox(year: int) → float#

Calculates the approximate Julian Date (JD) of the vernal equinox. Based on J. Meeus’s Astronomical Algorithms, incorporating Delta T (ΔT) corrections for historical accuracy.

Range: -1000 to 3000

Parameters:: year (int) – Astronomical year
Returns:: Julian Date of the vernal equinox
Return type:: float

winter_solstice(year: int) → float#

Calculates the approximate Julian Date (JD) of the winter solstice. Based on J. Meeus’s Astronomical Algorithms, incorporating Delta T (ΔT) corrections for historical accuracy.

Range: -1000 to 3000

Parameters:: year (int) – Astronomical year
Returns:: Julian Date of the winter solstice
Return type:: float

astronomy/moon.py - Lunar ephemerides, topocentric event solvers, and Babylonian astronomical diary intervals.

This module provides tools to track lunar age, compute precise topocentric moonrise, transit, and moonset times, and analyze the six classical Babylonian lunar intervals (na, šú, me, kúr, etc.) for historical diary reconstructions.

calculate_full_moon_na(year: int, month: int, day: int, city: str = 'Babylon', ziggurat: float = 0.0) → float#

Calculate the NA interval of the full moon: Time from the Lunar Rising to the Solar Setting.

Parameters:

year (int) – Year
month (int) – Month
day (int) – Day
city (str, optional) – City name, defaults to “Babylon”
ziggurat (float, optional) – Height above terrain in meters, defaults to 0.0

Returns:

NA (Full Moon) = Sunset - Moonrise in minutes

Return type:

float

calculate_kur(year: int, month: int, day: int, city: str = 'Babylon', ziggurat: float = 0.0) → tuple[float, float, float]#

Calculates the ‘KUR’ interval: Time between Moonrise and Sunrise on the last days of the lunar month.

Parameters:

year (int) – Year
month (int) – Month
day (int) – Day
city (str, optional) – City name, defaults to “Babylon”
ziggurat (float, optional) – Height above terrain in meters, defaults to 0.0

Returns:

Tuple containing (kur_interval_min, moon_rise_ut, sun_rise_ut)

Return type:

tuple[float, float, float]

calculate_mi_mush(year: int, month: int, day: int, city: str = 'Babylon', ziggurat: float = 0.0) → tuple[float, float, float]#

Calculates the ‘Mi-Mush’ (ME) interval: The time between Moonset and Sunrise around the day of the Full Moon.

Parameters:

year (int) – Year
month (int) – Month
day (int) – Day
city (str, optional) – City name, defaults to “Babylon”
ziggurat (float, optional) – Height above terrain in meters, defaults to 0.0

Returns:

Tuple containing (mi_mush_interval_min, moon_set_ut, sun_rise_ut)

Return type:

tuple[float, float, float]

calculate_moon_event(year: int, month: int, day: int, lat: float, lon: float, dip: float, is_setting: bool = True, seed_ut: float = 12.0) → float#

Iterative solver for lunar rise/set events using topocentric corrections.

Accounts for Horizontal Parallax (pi) and atmospheric refraction. Iterates to find the exact UT where the Moon’s limb touches the local horizon. Bypasses library limits for ancient Sidereal Time.

Parameters:

year (int) – Astronomical year
month (int) – Month
day (int) – Day
lat (float) – Latitude (degrees)
lon (float) – Longitude (degrees)
dip (float) – Horizon depth (refraction + geometric dip)
is_setting (bool, optional) – True for Moonset, False for Moonrise, defaults to True
seed_ut (float, optional) – Initial UT guess, defaults to 12.0

Returns:

Event UT in decimal hours (NaN if no event occurs)

Return type:

float

calculate_moon_transit(year: int, month: int, day: int, lon: float) → float#

Iterative solver for Moon Transit (Meridian Culmination). Target: Local Hour Angle (LHA) == 0.0

Parameters:

year (int) – Year
month (int) – Month
day (int) – Day
lon (float) – Geographical Longitude

Returns:

Moon transit UT in decimal hours

Return type:

float

calculate_shu_interval(year: int, month: int, day: int, city: str = 'Babylon', ziggurat: float = 0.0) → float#

Calculate the SU (Shu) interval: Time from the Solar Sunset to the Lunar Sunset on the days near the full moon.

Parameters:

year (int) – Year
month (int) – Month
day (int) – Day
city (str, optional) – City name, defaults to “Babylon”
ziggurat (float, optional) – Height above terrain in meters, defaults to 0.0

Returns:

SU = Moonset - Sunset in minutes

Return type:

float

check_neomenia(year: int, month: int, day: int, city: str = 'Babylon', ziggurat: float = 0.0, AoV: float = 12.0, uncertainty: float = 0.833, verbose: bool = True) → tuple[float, float]#

Evaluate visibility criteria for the first lunar crescent after New Moon (na interval).

Calculates the ‘na’ interval (Sunset to Moonset) and the lunar altitude at the moment of sunset. The standard Babylonian criterion for visibility is an ‘na’ interval > 12 US (48 minutes).

Parameters:

year (int) – Year
month (int) – Month
day (int) – Day
city (str, optional) – City name, defaults to “Babylon”
ziggurat (float, optional) – Elevation in meters, defaults to 0.0
AoV (float, optional) – Angle of Viewing in degrees, defaults to 12.0
uncertainty (float, optional) – Uncertainty or marginal visibility factor, defaults to 0.833
verbose (bool, optional) – If True, prints analysis to console, defaults to True

Returns:

Tuple (na_interval_min, lunar_altitude_at_sunset)

Return type:

tuple[float, float]

get_lunar_info(epoch_obj: Epoch) → tuple[float, float]#

Returns precise lunar age and illumination percentage.

Parameters:: epoch_obj (Epoch) – pymeeus Epoch object.
Returns:: Tuple with lunar age (days) and illumination fraction (0-100)
Return type:: tuple[float, float]

lunar_info(jd: float) → tuple[float, float]#

Wrapper around get_lunar_info accepting an absolute Julian Date.

Parameters:: jd (float) – Julian Date
Returns:: tuple with lunar age and illumination.
Return type:: tuple[float, float]

moon_age(jd: float, offset: float = 0.0) → int#

Calculates the days elapsed since the last New Moon using a coarse linear model.

This function uses the Mean Synodic Month constant from the ‘Five Millennium Canon of Solar Eclipses’.

Parameters:

jd (float) – Julian Day (UT)
offset (float, optional) – Adjustment for local events (e.g., sunset), defaults to 0.0

Returns:

Moon age in days

Return type:

int

moon_rise_transit_set(year: int, month: int, day: int, city: str = 'Babylon', ziggurat: float = 0.0) → tuple[float, float, float, float, float, float]#

Calculates the precise Moonrise, transit, and Moonset for a Mesopotamian site.

Parameters:

year (int) – Year
month (int) – Month
day (int) – Day
city (str, optional) – City name, defaults to “Babylon”
ziggurat (float, optional) – Height above terrain in meters, defaults to 0.0

Returns:

ut_rise, ut_transit, ut_set, local_rise, local_transit, local_set

Return type:

tuple[float, float, float, float, float, float]

astronomy/planets/base.py - Abstract base class for planetary ephemerides.

class Planet(name: str, arc_of_vision: float, debug: bool = False)#

Bases: ABC

Abstract Base Class representing a planet in Mesopotamian astronomy.

calculate_apparent_altitude(epoch: Epoch, city: str = 'Babylon', ziggurat: float = 0.0) → float#: SHARED CODE: Converts equatorial geocentric coordinates to horizontal altitude. Calculates the local hour angle using rigorous sidereal time mechanics, incorporating refraction and ziggurat horizon dip corrections.

abstractmethod get_geocentric_position(epoch: Epoch)#: Must be implemented by each specific planet. Should return (ra, dec, elon) from PyMeeus.

is_visible_at_twilight(epoch_sunset_or_sunrise: Epoch, city: str = 'Babylon', ziggurat: float = 0.0) → bool#

Determines if the planet is optically visible during the critical historical twilight.

This checks if the planet’s apparent altitude is above the horizon at the precise instant when the Sun is depressed by the planet’s specific Arc of Vision (Av).

Parameters:

epoch_sunset_or_sunrise – The Epoch of sunset (for evening stars) or sunrise (for morning stars).
city – The Mesopotamian site registry string.
ziggurat – Observer’s elevation in meters.

Returns:

True if the planet breaks through the solar glare, False otherwise.

astronomy/planets/inferiors.py - Inferior planets implementation.

class InferiorPlanet(name: str, arc_of_vision: float, debug: bool = False)#

Bases: Planet

Base class for planets closer to the Sun than the Earth (Venus, Mercury).

get_eastern_elongation(epoch: Epoch)#: Wraps PyMeeus native eastern elongation calculation using the instance.

get_eastern_elongation_time(epoch: Epoch)#: Wraps PyMeeus native eastern elongation calculation using the instance.

get_geocentric_position(epoch: Epoch)#: Wraps PyMeeus native geocentric calculation using the instance.

get_inferior_conjunction(epoch: Epoch)#: Wraps PyMeeus native inferior conjunction calculation using the instance.

get_station_longitude_1(epoch: Epoch)#: Wraps PyMeeus native station longitude 1 calculation using the instance.

get_station_longitude_2(epoch: Epoch)#: Wraps PyMeeus native station longitude 2 calculation using the instance.

get_superior_conjunction(epoch: Epoch)#: Wraps PyMeeus native superior conjunction calculation using the instance.

get_western_elongation(epoch: Epoch)#: Wraps PyMeeus native western elongation calculation using the instance.

get_western_elongation_time(epoch: Epoch)#: Wraps PyMeeus native western elongation calculation using the instance.

class MesopotamianMercury(debug: bool = False)#

Bases: InferiorPlanet

Mercury computations tailored for Babylonian astronomical phenomena.

class MesopotamianVenus(debug: bool = False)#

Bases: InferiorPlanet

Venus computations tailored for Babylonian astronomical phenomena (The Ninsianna diary).

astronomy/planets/superiors.py - Superior planets implementation.

class MesopotamianJupiter(debug: bool = False)#

Bases: SuperiorPlanet

Jupiter computations tailored for Babylonian astronomical phenomena.

class MesopotamianMars(debug: bool = False)#

Bases: SuperiorPlanet

Mars computations tailored for Babylonian astronomical phenomena.

class MesopotamianSaturn(debug: bool = False)#

Bases: SuperiorPlanet

Saturn computations tailored for Babylonian astronomical phenomena.

class SuperiorPlanet(name: str, arc_of_vision: float, debug: bool = False)#

Bases: Planet

Base class for planets further from the Sun than the Earth (Mars, Jupiter, Saturn).

get_conjunction(epoch: Epoch)#: Wraps PyMeeus native conjunction calculation using the instance.

get_geocentric_position(epoch: Epoch)#: Wraps PyMeeus native geocentric calculation using the instance.

get_opposition(epoch: Epoch)#: Wraps PyMeeus native opposition calculation using the instance.

get_station_longitude_1(epoch: Epoch)#: Wraps PyMeeus native station longitude 1 calculation using the instance.

get_station_longitude_2(epoch: Epoch)#: Wraps PyMeeus native station longitude 2 calculation using the instance.

is_in_opposition(epoch: Epoch, tolerance_deg: float = 0.5) → bool#: Checks if the planet is in acronychal opposition (Theta phenomena). Elongation close to 180 degrees.

MesoTimes Ecosystem (Chronology and Astronomy)

Contents

MesoTimes Ecosystem (Chronology and Astronomy)#

The Facade of Times#

Date (ChronDate)#

Planetary and Heliacal Calculations#

Models of Celestial Bodies#