Design

This document is for contributors and for readers who want to see how the library fits together: how the source directories depend on each other, where a namespace differs from its file, how time scales are handled, and which failure gets which mechanism. Day-to-day conventions are in AGENTS.md.

Layers

A header includes only from its own level or a lower one. From the bottom:

calendar/lunar/{common,converter,algo1,algo3}.hpp include only ymd.hpp and lunar/common.hpp. They live under calendar/ but sit just above util/ by dependency and never reach astro/.

Time-bearing astro/ headers use calendar/datetime.hpp. That is not an inversion. calendar::Datetime is a date and a time of day with no time scale or time zone attached, a util-level type that happens to live under calendar/, and datetime.hpp itself includes only ymd.hpp. No astro/ header includes anything else from calendar/, directly or transitively, so the order util → datetime.hpp → astro → jieqi.hpp / algo2.hpp has no backward edge.

src/CMakeLists.txt puts astro/, calendar/ and util/ on one include path, so an include names a file, not a level. No check enforces this order; read the includes when you add one.

Within astro/, ephemeris::TARGET_FACTS owns target membership, sources and provider domains. Position dispatch and equatorial_position live with those facts; chart composes them with rates and house geometry. The typed capability.hpp facade combines domain facts with the lightweight ephemeris_event_facts.hpp, without pulling the event search kernel/bounds tables into chart or independent position queries. julian_day owns physical time conversion; chart::resolve_civil_times adds the shared civil admission policy. Raw C selectors, sentinel encoding, record shaping and runtime model/text registries belong to shared_lib; adapters use public core operations, not core detail symbols.

Files and namespaces

Most headers open the namespace their path suggests: astro/earth/precession.hpp is astro::earth::precession, calendar/lunar/algo2.hpp is calendar::lunar::algo2. These do not:

astro/astro.hpp and astro/vsop87d/vsop87d.hpp only include other headers and open no namespace. Outside the library headers, src/test/random.hpp keeps util and util::detail, src/test/test_helper.hpp uses util::test, and src/shared_lib/ keeps its C++ helpers in lib and lib::chart, with the exported functions extern "C" at global scope.

The names stay. The design ledger in AGENTS.md rules out a one-off namespace rename: new code lands in the intended shape, and old names change incidentally or not at all.

Time scales

Ephemerides run on TT. UT1 enters where Earth's rotation matters (sidereal time, houses, rise and set), and UTC only at civil inputs and outputs. Other documents state the conclusion and link here.

• UT1 follows Earth's rotation; no clock keeps it.
• TT is TAI + 32.184 s exactly, where TAI is atomic time (TT_MINUS_TAI_SEC in leap_second.hpp).
• UTC is TAI − ΔAT, where ΔAT is the leap-second count that IERS steps to keep |UT1 − UTC| < 0.9 s. Together with the line above, TT − UTC = ΔAT + 32.184 s exactly, with no model involved (leap_second.hpp).
• ΔT is TT − UT1. It is observed, not defined, so the library takes it from a model (delta_t.hpp).
• DUT1 is UT1 − UTC. This document uses that sign throughout.

A JD counts days on UT1 and a JDE on TT (julian_day.hpp). A calendar::Datetime carries no scale of its own; the parameter name says which one it holds (jd_ut1, jde_tt, ymd_ut1, utc_dt).

The library's UTC begins on 1972-01-01 (MODERN_UTC_START); it does not model the rubber-second UTC of 1960–1971. The explicitly scaled julian_day::civil_to_tt / resolve_times and chart/civil-house inputs reject UTC before that date. Legacy leap_second::utc_to_tt / tt_to_utc and their Julian-day convenience wrappers instead read pre-1972 UTC-labelled values as UT1, with fixed Algo5. Their seam at 1972-01-01 is ΔT(1972.0) − 42.184 s, under a second. From 1972 the conversion uses the ΔAT table (LEAP_SECOND_TABLE), whose last step is 2017-01-01. After the last step ΔAT is held at 37 s. Whether real UTC keeps that value depends on future leap seconds or their successor under CGPM 2022 Resolution 4, which the library cannot know (calendar/lunar/algo2.hpp, the comment on its year ceiling).

DUT1 is not modelled: the library never reads an observed UT1 − UTC. Its UT1 is TT − ΔT from the selected model and its UTC is TT − (ΔAT + 32.184 s), so for one instant UT1 − UTC = (ΔAT + 32.184 s) − ΔT. By era:

So a UT1 result is not UTC, and reading one as UTC carries the gap in the table above. The leap-second-aware leap_second::utc_to_tt / tt_to_utc, added in v0.4.0 (#84), convert between UTC and TT through the ΔAT table; they supply no UT1 − UTC, so they do not make a UT1 output usable as UTC.

Where the library derives UT1 from a UTC input, UTC goes to TT through the ΔAT table, then TT − ΔT with one ΔT evaluation at TT. julian_day::Scale, Times { jd_ut1, jde_tt }, civil_to_tt and resolve_times own this conversion. The general resolver has no chart/house civil-year or derived-TT admission policy. Model guards apply at the evaluation instant: UT1 for the forward shift, TT for the reverse. Algo4 UT1 input may derive TT beyond its TT-evaluation end; reversing that TT through Algo4 may fail. UTC-to-TT alone does not evaluate ΔT and must not be routed through the both-scales resolver.

chart::resolve_civil_times adds the shared chart/civil-house policy: civil years [1885, 2100), strict modern UTC, and Algo4 derived JDE(TT) < 2464328.5, checked before reverse conversion. UT1 input passes through unchanged. Chart then checks its joint target/rate window; the civil house query does not. Numeric house::axes and house::calculate take same-instant UT1/TT values without this civil policy. Future UTC holds the last known leap offset, and derived UT1 is modelled, not observed DUT1.

The C, Python and JavaScript UTC/JDE convenience conversions follow the same historical substitute, 1972 seam and leap-table policy as C++. Their separate input domains and noninvertible boundaries, with a UTC-input Jieqi example, are in UTC conversions.

ΔT defaults to Algo5. Each model's source, status, hard year domain and role are in Delta T models; the definitions are in src/astro/delta_t.hpp.

Selectable ΔT operations follow delta_t::DEFAULT_MODEL; fixed-Algo5 convenience conversions stay fixed. House nutation follows house::DEFAULT_NUTATION_MODEL. Nutation/true-obliquity primitives and omitted sidereal model arguments retain fixed IAU 1980; positions, equatorial projection, solar time and rise/set also retain that fixed convention. A chart's returned house-nutation key does not claim its body corrections follow the house default.

Failures

Each failure is sorted by what happened to the answer (#97):

A declared model window is the contract's domain, so leaving it is a bad argument like any other. An input guard is never an assert.

The runtime_error check and the assert differ in when they run. An assert states an invariant the code guarantees by construction and is checked only without NDEBUG: in debug builds and the test binaries, never in the Release library. A runtime_error check guards a result that depends on numerics or data, runs in every build, and stops a wrong answer from reaching the caller.

optional never carries an error; it carries a legitimate "none". std::expected was evaluated for the core and declined (#97). The C ABI catches failures without throwing across the boundary: records return valid = false, and count/sized-string calls return zero. Every export except celestial_last_error and celestial_last_error_kind clears or records the calling thread's error kind/message. Both readers preserve state. The kind is authoritative even when the message is empty because message allocation failed.

Binding type/shape errors use TypeError; malformed native success payloads use the library error class. Coordinate checks after finite input can fail computation without declaring a new input interval. No coordinate validity check establishes physical plausibility or accuracy. Deliberate invalid-input error-class/message changes are listed in Migrating to 1.0.