# Moira 5.2.0 - Global Eclipse Circumstances and Adaptive Cartography **Release date:** 2026-07-23 **Public upgrade path:** 5.1.2 to 5.2.0 Moira 5.2.0 promotes global solar and lunar eclipse circumstances into first-class, immutable engine products and admits a NumPy-free spherical cartography surface for maximum-visible magnitude and obscuration. The release is additive at the public API boundary and keeps astronomical policy, timescales, ephemeris identity, surface model, and known exclusions explicit. ## Solar global circumstances `EclipseCalculator.solar_global_circumstances(...)` and the corresponding `Moira` facade method assemble: - P1-P4 footprint contacts and event-swept penumbral limits; - independently solved U1-U4 cone tangencies; - first and last central-line limits; - greatest eclipse and greatest duration as distinct optimizations; - equatorial and ecliptic conjunctions; - signed gamma and Besselian elements; - geocentric apparent Sun and Moon states; - WGS-84 zero-elevation greatest-site position, path width, local duration, magnitude, obscuration, altitude, and azimuth; and - the existing event-swept visibility footprint by reference. Authoritative horizon junctions, including the 2032 annular and 2049 near-singular hybrid cases exercised by the release corpus, are retained as exact incidences. Only sub-0.5-second numerical micro-branches wholly confined to the declared half-kilometre junction neighborhood are normalized. Connected-component and sunrise/sunset incidence invariants remain strict. ## Lunar global circumstances `EclipseCalculator.lunar_global_circumstances(...)` and the facade expose one geocentric result with explicit `native` and `nasa_compat` modes. The result carries: - greatest eclipse in TT and UT1 with Delta T and time-policy identity; - apparent geocentric Sun and Moon right ascension, declination, distance, semidiameter, and equatorial horizontal parallax; - signed gamma, axis distance, lunar radius, umbral and penumbral shadow radii, and both eclipse magnitudes; and - penumbral, partial, and total phase durations where those phases exist. Mode purity is enforced: native physical geometry and NASA-compatibility canon geometry cannot be mixed inside one result. ## Adaptive spherical cartography `solar_eclipse_cartography(...)` evaluates the lawful observer-visible eclipse interval at adaptive icosphere vertices and produces separate magnitude and obscuration contours. Refinement is conforming across shared edges and is driven by: - midpoint field interpolation error; - requested contour-level crossings; - visibility and local-class transitions; - polar topology; and - antimeridian seam topology. The result reports its requested and achieved depth, mesh triangle count, maximum angular edge, field and angular tolerances, unresolved-edge count, and convergence state. A flat renderer receives antimeridian-split segments; a 3D globe retains spherical connectivity. Duration contours, terrain and elevation, atmospheric refraction, weather, lunar-limb topography, and projection-specific screen coordinates are not part of this admitted product. ## REST admission The optional FastAPI surface adds: - `POST /v1/eclipses/solar/global-circumstances`; - `POST /v1/eclipses/solar/cartography`; and - `POST /v1/eclipses/lunar/global-circumstances`. Request bounds and response convergence metadata are typed in the OpenAPI contract. The server remains a transport layer; solver and cartography doctrine stay in the engine. ## Validation evidence The release exercises total, annular, hybrid, partial, polar-central, and near-singular solar geometry; penumbral, partial, total, and limiting lunar geometry; adaptive-mesh closure; antimeridian splitting; public exports; native boundary behavior; and REST serialization. The new global vessels are bound to the repository's existing NASA/GSFC Besselian and hashed lunar-figure corpora. Detailed 2027-08-02 solar and 2026-08-28 lunar fields are additionally compared with declared EclipseWise DE405/DE430 rows. These are named cross-model comparisons. Moira's runtime continues to use content-identified DE441/LE441, its declared mean-limb and WGS-84 policies, and its selected Delta-T model. No NumPy, SciPy, Swiss Ephemeris, or jplephem runtime dependency is introduced. A native dense-field cartography accelerator remains deferred until measured production evidence justifies its boundary and parity cost. ## Performance smoke One warm-reader Windows/Python 3.14 smoke using DE441/LE441 and the 2027-08-02 total eclipse measured: - `solar_global_circumstances(...)`: 18.92 seconds wall time; and - default `solar_eclipse_cartography(...)`: 39.74 seconds wall time. The cartography result contained 21 evaluated mesh vertices and 38 triangles at achieved depth 1. It correctly reported `converged=False` with 31 unresolved edges under the requested default tolerances. These single-process timings are performance evidence only. They establish the need for background execution, request deduplication, caching, and explicit convergence handling in an interactive website; they are not a throughput guarantee or scientific validation result.