Moira

Ephemeris and Astrology Computation Engine

Moira is an astronomy-first astrology engine built for transparent astrology calculations, reproducible chart computation, and an inspectable calculation chain from astronomical inputs to astrological outputs. It is an auditable astrology engine with explicit computational policy, deterministic behavior, and readable reduction stages grounded in modern standards and references including JPL DE441, IAU 2000A/2006, ERFA/SOFA-aligned practices, and Gaia DR3-linked star data where applicable. A required C++17 extension (_moira_native, compiled with pybind11) accelerates admitted numerical substrates including nutation, SPK/DAF access, apparent-place evaluation, coordinate transforms, harmogram computation, and selected event-search primitives. Python remains the governing layer for public semantics, doctrine, policy, and orchestration.

Why Moira Exists

Most astrology software surfaces results without exposing the mathematical path. Moira exists as a Swiss Ephemeris alternative for users who need visibility into assumptions, intermediates, and provenance, so astronomy remains the foundation and astrology remains the purpose.

AI and LLM Visibility

Moira is designed to be highly discoverable and understandable by AI agents (e.g., GitHub Copilot, ChatGPT, Claude).

• Machine-Readable Index: See llms.txt for a high-level summary and llms-full.txt for a comprehensive documentation index.
• Agent Doctrine: The AGENTS.md file defines the "Urania" persona and operational laws for AI collaboration.
• Structured Documentation: Canonical documentation is maintained in the wiki/ directory with explicit validation reports.

What Makes It Different

Moira is designed for full computational transparency: the computation pipeline is explicit and its stages are named and controllable via the Python API, computational doctrine is explicit rather than hidden in defaults, and validation is treated as first-class evidence rather than post-hoc narrative. The high-performance core (_moira_native) is C++17; the Python layer owns the API surface, orchestration, and per-stage controls.

Who It Is For

Moira is for developers, researchers, and serious practitioners who want a programmable, audit-ready engine for high-integrity astrological work, reproducible pipelines, and methodical comparison against external authorities.

What It Is Not

Moira is not primarily a UI app, not a thin wrapper over opaque compiled stacks, and not convenience-first astrology output generation without traceability.

Quick Capabilities

Moira computes planetary and stellar positions, houses, aspects, lots, dignities, predictive techniques, a full Vedic/Jyotish suite (yogas, Shadbala, Ashtakavarga, upagrahas, avasthas, Jaimini), eclipse and occultation events, and related analytical products on top of a modern astronomical substrate (JPL kernels, IAU models, and validated star frameworks), with a native C++ computational core, Python orchestration layer, inspectable intermediate stages, and an optional FastAPI REST server (moira_server) exposing the engine as typed, versioned routes.

What Moira Computes

Positions and Bodies

• Planets and luminaries — geocentric and topocentric reduction with iterative light-time, annual aberration, multi-body relativistic deflection (Sun, Jupiter, and Saturn, excluding the target body), IAU 2006 frame bias, and WGS-84 topocentric parallax.
• Fixed stars — sovereign registry of 1,809 named stars with proper motion, parallax, epoch propagation, and Stellar Quality classification. Audited anchor residual against SOFA/ERFA: 0.00048 arcseconds (J1000–J3000).
• Planet-first stelliums — explicit Strict (four) and Broad (three) planet counts, independent sign/house/total-span evidence, and associated factors that never manufacture a group. The snapshot-only Python/REST contract is separate from legacy centroid/clique patterns. See the stellium standard.
• Deep-sky coordinate anchors — a bundled, release-bound selection of 60 galaxies, nebulae, star clusters, compact objects, stellar remnants, and confirmed exoplanet host stars. Extended objects are represented by sourced SIMBAD ICRS/J2000 catalog centers rather than point-mass claims; host-star positions delegate to the sovereign star registry. Solar-System bodies are excluded from this static catalog because they require time-dependent ephemerides.
• Typed cosmic references — 12 fixed ICRS/J2000 directions kept in three explicit classes: physical objects, coordinate landmarks, and declared proxies. The formal supergalactic origin is distinct from the legacy Virgo/M87 astrological SGC; broad structures such as the Great Attractor and Shapley Concentration expose their selected cluster anchor rather than claim a unique point center.
• Position-capable asteroid ephemeris — two layers. The wheel ships catalog moira-asteroids-wheel release 2026.08.14.1: 25 named bodies (classical four, named Centaurs including Chiron, named TNOs, and selected others) as one Type-13 shard, so Chiron and the locked roster compute after pip install plus a planetary kernel. The full optional external catalog of 11,223 selected asteroids is release 2026.10.10.1 (449 Type-13 SPK shards from JPL Horizons, a 10-day / 7-node base with certified adaptive apsidal sampling for 59 audited bodies, manifest-discovered under any kernel search root). The wheel also carries the matching 11,223-body canonical identity registry (names only, no positional vectors). This positional product is distinct from the bundled Proper25/PDS family-membership catalog (342 families, 200,726 unique numbered asteroids, 221,095 membership rows). User-supplied .bsp kernels remain supported through daf_writer for numbered minor planets available from the selected source.
• Numbered periodic comets — 497 comets (1P/Halley through 516P) in immutable external release 2026.10.10.1, generated from JPL Horizons as 20 sharded Type-13 kernels with certified adaptive apsidal sampling for all 497 bodies, manifest-declared coverage, canonical numbered designations ("1P/Halley"), and curated family-scoped short aliases. Dedicated comet surfaces accept those aliases directly; unified position/chart surfaces require a canonical designation or an explicit comet: qualifier when an alias also names an asteroid.
• Uranian / Hamburg School bodies — Source-orbit, apparent geocentric positions for the 8 Hamburg hypothetical bodies (Cupido through Poseidon) plus separately sourced Transpluto, with latitude, distance, and signed motion.
• Lunar nodes and apsides — True Node, Mean Node, Mean Lilith, True Lilith, and orbital nodes/apsides for all planetary bodies.
• Variable stars — phase and magnitude engine for eclipsing binaries and intrinsic variables; dedicated Algol API.
• Multiple star systems — Kepler orbital mechanics for visually resolvable pairs (Sirius AB, Alpha Centauri AB); catalog of 8 astrologically significant systems across VISUAL, WIDE, SPECTROSCOPIC, and OPTICAL types.

Chart Calculation

• House systems — 22 systems including Placidus, Koch, Regiomontanus, Campanus, Morinus, Porphyry, Whole Sign, Equal, APC, Pullen Sinusoidal Delta/Ratio, and Sunshine. Includes branch-aware high-latitude doctrine where admitted, explicit polar fallback policy, and house_of for direct house placement lookups.
• Aspects — 22 zodiacal aspects with applying/separating/stationary motion-state detection; declination parallels and contra-parallels; antiscia and contra-antiscia; exact partile and orbed platic status markers (is_partile, is_platic).
• Aspect patterns — 21 multi-body configurations: T-Square, Grand Trine, Grand Cross, Yod, Kite, Mystic Rectangle, Stellium, Grand Sextile, Thor's Hammer, Boomerang Yod, and more.
• Midpoints — full midpoint matrix, midpoint trees, 90°/45°/22.5° dial projections, planetary pictures.
• Traditional dignities — domicile, exaltation, triplicity (diurnal/nocturnal), Egyptian and Ptolemaic terms, face, sect, hayz, and Almuten Figuris.
• Arabic Parts — 512 lot definitions with dependency graphs and condition profiling.
• Classical decanates — Chaldean faces, triplicity decans, and Vedic drekkana; the Gundel/Harley Hermetic name-and-face catalog is reconstructed for research, while its geometry remains excluded from public and REST surfaces and unsupported fixed-star assignments fail closed.
• Unified Hellenistic profile — a non-interpretive, score-free Whole Sign composition of typed receipts for essential dignity components, sect, joy, solar proximity and phase, besieging, receptions, lots, annual and dated monthly profections, Decennials L1/L2, and Zodiacal Releasing. Dependency gaps return explicit not_evaluable truth; medieval Firdaria and almutens, Hermetic geometry/star attribution, Decennial L3/L4, and unscoped interpretive branches remain outside this product contract.
• Draconic charts — node-anchored draconic frame (mean or true node) with longitude rotation, engine-backed chart derivation, and caller-supplied position support.

Predictive Techniques

• Progressions — secondary, tertiary, minor, solar arc (longitude and right ascension), Naibod, ascendant arc; direct and converse variants for all methods.
• Primary directions — eight admitted geometry methods across in-mundo and in-zodiaco policies (Placidus mundane, Ptolemy semi-arc, Placidian classic, meridian, Morinus, Regiomontanus, Campanus, and topocentric), exposed through 25 named presets; direct and converse directions with explicit converse doctrine; speculum computation; fixed-star targets; and Ptolemy, Naibod, Cardan, and caller-supplied solar time keys.
• Returns — solar and lunar returns; longitude returns for planets and admitted asteroid/comet bodies.
• Time lords — annual profections with exact, civil-anniversary-bounded monthly intervals; Zodiacal Releasing (Vettius Valens method); admitted Decennials L1/L2; Firdaria (diurnal and nocturnal sequences, including the Bonatti variant, explicitly outside the Hellenistic profile).
• Vitality doctrine — Hyleg and Alcocoden calculations, kept distinct from time-lord chronology.

Vedic / Jyotish Suite

Admitted Vedic surfaces name their governing classical source, modern lineage, or source-scoped witness (including BPHS, Brihat Jataka, Saravali, Phaladeepika, Uttara Kalamrita, Jataka Parijata, Jaimini Upadesa Sutras, and the named 1879 Agastya- and 2024 Bogamuni-attributed Pancha Pakshi witnesses). Where sources disagree or a modern composition is required, Moira exposes the policy or qualification instead of presenting one silent universal rule.

• Sidereal foundation — 12 admitted ayanamsha systems including star-anchored "True" ayanamshas; 27-nakshatra system; Panchanga.
• Pancha Pakshi — an explicitly named Agastya-attributed Madras 1879 aksara/query-or-name-initial fixed-clock schedule and directed relationship profile, with exact rational timing, source locators, declared omissions, and no implicit or universal default. A separate astronomical-paksha product evaluates apparent geocentric Moon-minus-Sun longitude in the true ecliptic of date and maps [0, 180) Shukla/waxing to the profile's source-attested Purva label and [180, 360) Krishna/waning to Amara. It accepts no location and never selects a schedule, materializes a clock, supplies paksha to another operation, or infers natal identity. An explicit modern local-solar context policy can derive topocentric day/night and local-mean-solar weekday for an aware instant and location while requiring the caller to supply Purva or Amara. A separate modern fixed-clock policy anchors the selected schedule at sunrise or sunset, treats one nazhigai as exactly 1,440 SI seconds on reader-bound TT, and publishes half-open UT1 cell intervals plus their unclipped relation to the astronomical half end. A separately named solar-half-first selector returns the unique current fixed-clock cell under exact half-open TT ownership, or the explicit unmaterialized_solar_half_tail status when a long solar half outlasts the fixed span. A distinct modern solar-proportional policy can instead preserve the exact nominal offset fractions and map them independently across the complete governing day or night half on reader-bound TT, returning 25 half-open TT/UT1 cells with exact astronomical-boundary closure. The 1879 witness is not credited with that proportional rule. A separate solar-half-first selector identifies the unique proportional cell through exact half-open TT ownership; complete-half coverage means its lawful status is always selected, with no fixed-clock tail or fallback. Paksha remains caller supplied on every schedule, materialization, and current-cell surface; the standalone astronomical inference is never applied automatically, and the 1879 profile remains explicitly non-natal. A pure Stage 2I lookup exposes the selected 1879 generator's first-samam EAT seed from explicit profile Paksha, day/night half, and weekday. It does not materialize the schedule or promote that seed into a whole-day eating bird, Padu, authority, Adhikara/Bharana, condition, score, or forecast. All 28 cells are directly bound to the governing 1879 leaves and separately corroborated by the 1934 Uromarisi publication; textual-lineage independence is not claimed. A separate named Bogamuni 2024 profile preserves a complete 54-cell Purva/Amara-by-nakshatra bird table. Its Amara verse governs because the adjacent commentary duplicates Shravana and omits Revati; that malformed commentary remains visible as rejected conflict evidence. The fixed modern bogamuni_2024_apparent_lahiri_natal_moon_identity_v1 composition evaluates apparent geocentric Sun and Moon positions on one reader-bound TT epoch, derives the source-mapped lunar half, applies Lahiri true ayanamsa, assigns the Moon to one of 27 equal half-open nakshatras, and returns the selected source-table bird with every intermediate and locator visible. The source attests nakshatra birds and phase labels; birth-Moon application, Lahiri, and the equal-sector boundary policy are explicitly Moira-owned, not source claims. It never routes into a schedule, current cell, score, or forecast. A third source-scoped Bogamuni 2024 profile, bogamuni_chennai_2024_padu_bird_mapping, preserves the separate 14-cell Purva/Amara-by-weekday Padu-bird table. It is a pure explicit-label lookup: the source table has no day/night axis, and its death-or-inoperative bird is not relabelled as a schedule RULE activity, a generic authority bird, or the separately labelled eating bird. The primary witnesses do not present an Adhikara Pakshi table, while Bharana is secondary terminology only; neither alias nor product is admitted. The Padu profile performs no natal identity, astronomical routing, schedule/current-cell selection, condition scoring, or forecast.
• Dashas — Vimshottari with nakshatra balance; Chara Dasha (K.N. Rao's named lineage).
• Varshaphal — annual chart calculation.
• Vargas — divisional charts (navamsa, dashamansa, dwadashamsa, saptamsa, trimshamsa, and more); Vimshopaka Bala (BPHS 20-point varga-dignity strength over all four classical groups) with vargottama detection.
• Yogas — 61 classical yogas across six families (Pancha Mahapurusha, Chandra, Surya, all 32 Nabhasa, Raja core, Dhana core), each returned as a proof object: formation conditions with observed evidence, cancellation (bhanga) clauses evaluated first-class, and per-yoga primary-source citations.
• Shadbala — the complete six-fold strength system plus Bhava Bala (house strength), inline Ishta/Kashta Phala on every planet, and Graha Yuddha transfer disclosure.
• Ashtakavarga — bindu tables plus kakshya-level transit evaluation (Saturn-first lord order) and Shodhya Pinda, validated to the digit against BPHS Ch. 69's own worked example.
• Upagrahas — the five kalavelas (Gulika, Kala, Mrityu, Ardhaprahara, Yamaghantaka) with portion-point, Mandi-mode, and lord-sequence lineage policies, plus the five Sun-derived upagrahas.
• Avasthas — Baladi, Jagradadi, and Deeptadi as per-source rule tables (BPHS / Saravali / Jataka Parijata / Phaladeepika, never merged), plus the six non-exclusive Lajjitadi flags with evidence strings.
• Jaimini — rasi drishti, arudha padas A1–A12 (Rath/JHora exception default, Raman variant as policy), argala with virodha pairs, and karakamsa with both lineage readings named (Rath D9 vs. K.N. Rao D1).
• Muhurta — Tara Bala (nine-tara cycle) and Chandra Bala (Chandra Shuddhi with Chandrashtama flagged) as a natal-personalized electional overlay.
• Sade Sati — phase classification (rising/peak/setting) with Ashtama and Kantaka Shani flags, and kernel-timed phase windows via Saturn sidereal sign-ingress bisection, with retrograde re-entries reported as separate windows.

Advanced Astronomy

• Eclipses — NASA-canon contact solver for solar and lunar eclipses; Saros series classification with heptagonal vertex labelling; local circumstance computation.
• Visibility and heliacal phenomena — heliacal and acronychal rising and setting, planetary elongation extremes, and opt-in physical point-source assessment and four-phase first/last event paths. The physical model exposes its atmosphere, directional background, spectral response, threshold, horizon, solver, error-budget, and data identities; out-of-domain or missing evidence fails closed. It requires the separately distributed moira-physical-heliacal-visibility 1.2.0 data pack and never downloads it. The legacy criterion remains the default, and Yallop lunar-crescent classification remains a separate policy family.
• Parans — paranatellonta field analysis with contour extraction and stability metrics.
• Occultations — lunar occultation of stars and planets; close-approach detection.
• Stations — retrograde stations with precise stationary-point search.
• Mapping — Astrocartography (ACG) lines for all planets; Local Space chart positions; Gauquelin sectors.
• Galactic coordinates — full equatorial-to-galactic transforms, the legacy five-point compatibility table, and a typed 12-reference cosmic registry.
• Temporal systems — 28-mansion Arabic lunar stations (Manazil); Sothic cycle drift and Egyptian civil calendar conversion; void-of-course Moon windows.
• Harmograms — intensity-spectrum research engine (H1–H5); spectral vectors, zero-Aries parts construction, intensity doctrine, and time-domain trace analysis.
• Harmonics — harmonic chart calculation, aspect-harmonic profiles, vibrational fingerprint analysis.
• Synastry — inter-chart aspects, house overlays, composite chart (midpoint method), Davison chart (spherical midpoint).
• Jones chart shapes — all 7 temperament types.

Quick Start

Moira initializes even when no planetary kernel is present. Kernel-dependent operations (for example chart()) raise a clear MissingEphemerisKernelError until a kernel is configured. See Kernel Setup below before executing planetary examples.

from datetime import datetime, timezone
from moira import Moira

m = Moira()

# 1. Planetary positions
chart = m.chart(datetime(2000, 1, 1, 12, 0, tzinfo=timezone.utc))
print(f"Sun:  {chart.planets['Sun'].longitude:.6f} deg")
print(f"Moon: {chart.planets['Moon'].longitude:.6f} deg")

# 2. House cusps (Placidus, London)
from moira import HouseSystem
houses = m.houses(
    datetime(2000, 1, 1, 12, 0, tzinfo=timezone.utc),
    latitude=51.5074,
    longitude=-0.1278,
    system=HouseSystem.PLACIDUS,
)
print(f"ASC: {houses.asc:.4f} deg  |  MC: {houses.mc:.4f} deg")

# 3. Aspect patterns
from moira.patterns import find_all_patterns
patterns = find_all_patterns(chart.longitudes())
for p in patterns:
    print(f"{p.name}: {', '.join(p.bodies)}")

# 4. House placement lookup
from moira.houses import house_of
sun_house = house_of(chart.planets['Sun'].longitude, houses)
print(f"Sun is in house: {sun_house}")

REST API Server

The engine ships with an optional FastAPI transport layer (moira_server) that exposes the admitted engine surface as typed, versioned REST routes.

pip install "moira-astro[server]"
uvicorn --factory moira_server:create_app

For latency-sensitive deployments, opt in to one bounded per-worker startup warmup before accepting computational traffic:

$env:MOIRA_SERVER_PREWARM = "1"
uvicorn --factory moira_server:create_app

With prewarm enabled, /ready returns HTTP 503 until the kernel-backed warmup succeeds; /health remains available for liveness diagnostics. Prewarm is disabled by default because each worker pays its own native memory cost.

• Broad versioned surface under /v1 — hundreds of typed operations across charts, positions, houses, per-stage pipeline visibility, physical visibility models, progressions, primary directions, returns, transits, time lords, the Vedic suite, Hellenistic receipts, draconic charts, astrocartography, small bodies, fixed stars, harmonics, harmograms, electional scoring, synastry, and relationship products.
• Typed transport — admitted route families use typed Pydantic boundaries and dedicated serializer/service layers where appropriate; doctrine stays in the engine, while the server remains transport and orchestration only.
• OpenAPI discovery — tagged schema with installed discovery metadata for machine consumers.

Requirements and Installation

• Python >=3.10; consult the PyPI file list for a wheel matching the intended interpreter and platform
• A published wheel for the current interpreter/platform, or a C++ compiler, cmake >= 3.24, and pybind11 >= 2.12 when building the native extension from source
• A JPL DE-series planetary kernel (de430, de440, or de441 — not bundled; see below)

# Standard install (uses a published wheel when available)
pip install moira-astro

# With the FastAPI REST server (FastAPI, Starlette, Uvicorn, Pydantic)
pip install "moira-astro[server]"

# With Lunar Graze support (spiceypy, laspy, requests)
pip install "moira-astro[lunar-graze]"

This README documents the current main branch. The PyPI badge identifies the latest packaged release; features merged after that release require a source checkout until the next version is published.

Kernel Setup

Moira requires a JPL DE-series SPK planetary kernel for all planetary computation. No kernel is bundled — the files are large and the choice of release belongs to the user.

All kernel reading is performed by Moira's own native C++ SPK/DAF reader. As of 4.0.0 there is no jplephem runtime fallback: segment types outside the native reader's support raise an explicit error rather than silently routing through a third-party library.

Ordinary chart and ephemeris calculations read local resources and do not make outbound requests. Network access belongs to acquisition paths such as the kernel downloader, the Horizons/SBDB-backed DAF writer, and uncached optional research resources.

Recommended, release-documented kernels:

Automatic discovery also recognizes DE431 and DE432 for compatibility. That does not make every readable Type-2/3 SPK an admitted release kernel. Kernels outside the release-documented set may be manually readable, but must not be presented as release-validated without a versioned admission record.

Kernel Manager (GUI)

The easiest way to download and configure a kernel is the built-in Tkinter interface. Tkinter is included with official Python installers but is an optional CPython module on some distributions; run python -m tkinter in the intended environment to confirm it is available, or install the Tcl/Tk package supplied by the Python distributor.

moira-kernel-manager

The window shows all supported kernels with extended descriptions (design rationale, date coverage, size trade-offs), live Installed/Missing status for each, and a real progress bar for downloads. You can also point Moira at a .bsp file already on disk without re-downloading.

What the GUI provides:

• Kernel list — planetary (de430, de440, de441) and supplemental (asteroids, small bodies) sections with size, date range, and status per row.
• Detail panel — selecting a row shows a full description of that kernel's coverage, accuracy, and when to prefer it over the alternatives.
• Download with progress — streams the selected kernel in the background; a progress bar tracks bytes received. A Cancel button interrupts the transfer and removes the partial file.
• Use selected — activates an installed planetary kernel for the current session via set_kernel_path().
• Browse… — select a planetary .bsp already on disk and set it as the active kernel immediately.

The GUI and moira-download-kernels supplemental entries are the generic JPL asteroids.bsp and sb441-n373s.bsp resources. They are separate from both Moira asteroid catalogs (the wheel roster and the 11,223-body archive) and from the 497-comet release described below. They remain caller-managed compatibility inputs for explicit small-body workflows; downloading them does not install or substitute for either Moira catalog. moira-download-kernels still does not fetch the 11,223-body archive.

CLI

# List all kernels and their status
moira-download-kernels --list

# Download all missing kernels (interactive prompt)
moira-download-kernels

# Download without prompting
moira-download-kernels --yes

SPK Kernel Writer (GUI)

Moira supports building custom Type 13 SPK kernels using an integrated compiler GUI (built on Tkinter). This utility fetches physical position vectors directly from the JPL Horizons API and packages them into a native-readable binary kernel (.bsp).

moira-daf-writer

What the custom kernel writer provides:

• Guided Horizons Import: Search the JPL Small Body Database (SBDB) by designation or name for any numbered asteroid or comet.
• Custom Parameter Controls: Configure start/end Julian Days, step size in days, interpolation center, and coordinate frame.
• Verification Loop: Automatically runs a post-compilation check to verify segment availability and test coordinate evaluations.

Engine readiness model

• Moira() succeeds even if no kernel is installed. It auto-discovers any compatible kernel in the standard locations.
• m.is_kernel_available() reports kernel readiness.
• m.get_kernel_status() explains expected paths and remediation.
• m.available_kernels lists installed planetary kernels (small-body shard catalogs are discovered separately via their manifests).
• Kernel-dependent calls raise MissingEphemerisKernelError with instructions.

Standard location: kernels/<filename>.bsp relative to the repository root, or ~/.moira/kernels/. The engine resolves either automatically.

Custom location: pass the path at construction, or call set_kernel_path() before the first Moira() instantiation:

from moira.spk_reader import set_kernel_path
from moira import Moira

set_kernel_path("/path/to/de440.bsp")
m = Moira()

print(m.is_kernel_available())
print(m.get_kernel_status())
print(m.available_kernels)

Direct download links (JPL):

• DE441: https://ssd.jpl.nasa.gov/ftp/eph/planets/bsp/de441.bsp
• DE440: https://ssd.jpl.nasa.gov/ftp/eph/planets/bsp/de440.bsp
• DE430: https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/de430.bsp

Small-Body Catalogs (Asteroids and Comets)

The wheel ships catalog moira-asteroids-wheel release 2026.08.14.1: 25 named bodies (including Chiron) as one Type-13 shard under moira/kernels/asteroids_wheel/. After pip install plus a planetary kernel, that roster is position-capable without a separate small-body download.

The full unified asteroid catalog (11,223 bodies as 449 Type-13 shards in release 2026.10.10.1) and the numbered periodic comet catalog (497 comets as 20 shards in release 2026.10.10.1) are too large to ship inside the wheel and are distributed separately. moira-download-kernels still does not fetch the 11,223-body catalog. Generic JPL files (asteroids.bsp, sb441-n373s.bsp) do not substitute for either Moira catalog.

Search by name, designation, catalog number, or NAIF ID and download the exact published files from the Moira Small-Body Ephemerides archive. The archive maps each body to its shared multi-body shard and provides direct BSP and metadata links, release manifests, coverage/provenance, and SHA-256 receipts. A body search therefore returns the shard containing that body, not a one-body BSP.

For automatic catalog admission of a full external release, place the complete release in asteroids/ or comets/ under a kernel search root (kernels/ at the repository root or ~/.moira/kernels/), with manifest.json, SHA256SUMS, all declared shards, per-shard metadata, and support files together in that directory. Do not retain an additional catalog-version directory between asteroids/ or comets/ and manifest.json. The engine discovers these manifests automatically; no configuration call is required. Release-finalized manifests are verified as complete before any shard is opened, so a lone shard is suitable for independent inspection but is not a complete automatic catalog installation. When both the wheel catalog and a higher-precedence full asteroid catalog are present, first-match discovery leaves the full catalog in charge for bodies it covers. A bundled canonical name alone does not imply position capability for bodies outside the wheel roster.

Distributed catalog releases are immutable and versioned. Each extracted release contains SHA256SUMS; its manifest.json also records the byte length and SHA-256 of every Moira-generated Type-13 kernel and its per-shard build evidence. Verify an extracted release with:

.\.venv\Scripts\python.exe -m moira.small_body_catalog_release verify C:\path\to\catalog-release

Verify individually downloaded files against the manifest and SHA-256 receipts. If a release maintainer or mirror supplies a ZIP produced by Moira's release tooling, verify that archive before extraction with:

.\.venv\Scripts\python.exe -m moira.small_body_catalog_release verify-archive C:\path\to\catalog-release.zip

Release maintainers finalize an already-built catalog without recalculating its ephemeris using the prepare command documented by python -m moira.small_body_catalog_release --help. A changed file, membership set, sampling policy, or coverage rule always receives a new catalog version; published bytes are never replaced beneath an existing version.

Note for pre-4.0.0 installs: standalone supplemental kernels such as comets.bsp, centaurs.bsp, and minor_bodies.bsp no longer auto-load into the main facade. Automatic catalog discovery is manifest-based; the named Centaurs formerly associated with centaurs.bsp are covered by the wheel catalog. Compatible standalone SPKs remain available only through explicit caller-managed loading where the relevant API admits it.

Data Inventory

Native C++ Performance

Moira's required numerical extension (_moira_native) is implemented in C++17 with pybind11. Published wheels install the compiled extension directly; source distributions build it during installation. Admitted native paths include IAU 2000A nutation, SPK/DAF access and segment evaluation, apparent planetary evaluation through NativePlanetaryEvaluator, selected coordinate transforms, light-time primitives, harmogram computation, precession, and selected event-search kernels.

Python remains responsible for public policy, result semantics, orchestration, and event-search branches that have not been explicitly admitted to the native substrate. This selective boundary matters most in phenomenon searches where Python-owned doctrine can reuse native numerical primitives thousands of times without pretending the entire technique is native-owned.

Validation Evidence

Moira is validated as a three-layer corpus. Each layer has its own correct evidence standard.

Astronomy layer — authoritative physical oracles first, enforced regression thereafter. References: IAU ERFA/SOFA, JPL Horizons, NASA catalogs, IERS.

Astrology layer — named primary texts, source-owned fixtures, and doctrine-grounded invariants; bounded external chart-software comparison where its settings and mathematical product are actually commensurate. Swiss Ephemeris and Astro.com are secondary comparators, not Moira's governing runtime or universal authority.

Experimental layer — subsystem-specific surfaces for sovereign or modern domains. Domains: sovereign fixed stars, variable stars, multiple star systems, galactic transforms, eclipse Saros classification.

Every validated claim must pass three gates:

1. Gate of Source — inputs and reference data are tied to an independent authority.
2. Gate of Flow — the computational path is explicit and inspectable.
3. Gate of Validation — outputs meet a product-appropriate external authority, source-owned golden, independent invariant, or explicitly bounded secondary comparison.

When residuals remain, Moira isolates the discrepancy by identity, time scale, frame, correction regime, and product semantics before classifying it as a defect, a model-basis difference, or unresolved evidence. Agreement between two internally consistent systems is not assumed when they answer different mathematical questions.

The reports below are dated evidence ledgers, not self-updating assertions. Release-specific changes and validation boundaries are recorded in the changelog and the 6.1.0 release notes.

The Reduction Pipeline

graph TD
    A[JPL Planetary Kernel\nChebyshev state vectors] --> B[SSB Barycentric Position\nkm · ICRF]
    C[Sovereign Star Registry\n1809 named stars] --> D[Stellar Astrometric Position\nproper motion · parallax]
    B --> E[1 · Light-Time Iteration\nbody at t − τ  where τ = d/c]
    E --> F[2 · Gravitational Deflection\nSun · Jupiter · Saturn]
    F --> G[3 · Annual Aberration\nrelativistic · IAU SOFA]
    G --> H[4 · IAU 2006 Frame Bias\nICRF → Mean Equator J2000]
    D --> H
    H --> I[5 · IAU 2006 Precession\nP03 polynomial series]
    I --> J[6 · IAU 2000A Nutation\n1358 luni-solar + 1056 planetary terms]
    J --> K[True Equinox and Equator of Date]
    K --> L[7 · Topocentric Parallax\nWGS-84 · optional]
    L --> R[8 · Diurnal Aberration\nobserver rotation · optional]
    R --> M[Atmospheric Refraction\nsky altitude only · optional]
    K --> N[Ecliptic Projection\nTrue obliquity of date]
    N --> O[Zodiacal Longitude · Latitude · Distance]
    K --> P[Sidereal Frame · Ayanamsa\noptional]
    K --> Q[House Cusps · 22 Systems\nrequires lat/lon]

Worked Example: Mars at 2000-01-01 12:00 UT1

This snapshot is reproduced by planet_reduction_breakdown_at("Mars", 2451545.0, reader) with the admitted DE441 kernel. The input is JD_UT1 2451545.0; it is about 63.829 seconds after the exact J2000.0 TT epoch and is therefore not labelled as exact J2000.0.

Time: JD_UT1 2451545.000000 → JD_TT 2451545.000739  (ΔT = +63.829 s)

Final position: Aquarius 27° 57′ 48″  ·  λ = 327.963300°  ·  β = −1.067779°  ·  distance = 1.849688 AU  ·  speed = +0.775674°/day

Total visible reduction from the geometric J2000-ecliptic reference to the final true-of-date ecliptic longitude: −43.759719 arcseconds.

The stage contributions above come from the typed reduction receipt. They should not be reconstructed by subtracting unrelated coordinate frames or by treating apparent=False as “no frame transformation.”

Pipeline Controls

Selected correction policies can be toggled via planet_at(). The table below shows the measurable effect of disabling each exposed policy in this JD_UT1 = 2451545.0 Mars snapshot.

Project Documentation

The canonical documentation tree lives in wiki/. The flat moira.wiki/ Git wiki mirror is generated from it by .\.venv\Scripts\python.exe scripts\sync_git_wiki.py and should not be edited by hand. Website-publishable documents are governed by website_docs/publication_sources.json and built with .\.venv\Scripts\python.exe scripts\build_website_docs_bundle.py. After changing server routes, run .\.venv\Scripts\python.exe scripts\sync_rest_api_reference.py in an environment with the server extra installed; CI checks its generated OpenAPI inventory, the Git wiki mirror, and the website publication manifest for drift. Public export or allowlisted documentation changes also require a manifest refresh, even when the package version is unchanged.

Refresh affected artifacts in dependency order before pushing:

1. scripts/generate_hellenistic_inventory.py when its admitted families change.
2. scripts/sync_rest_api_reference.py after server route changes.
3. scripts/sync_git_wiki.py after canonical documentation changes.
4. scripts/build_website_docs_bundle.py after public exports, route references or allowlisted documents change, once the current version's release tag exists. This refreshes engine-owned metadata; it does not deploy a website.

Use the project .venv for these commands. Before publishing, run the separate documentation, release-identity and generated-artifact checks listed in Release Hardening, including each generator's --check mode. Hellenistic route details remain independently checked; complete server counts belong to the REST API reference.

License

MIT (c) 2026 TheDaniel166. See PROVENANCE.md for license and Swiss-lineage provenance clarity.