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. Performance-critical computations — nutation, SPK kernel reading, apparent planetary evaluation (via NativePlanetaryEvaluator), coordinate transforms, light-time iteration, harmogram analysis, and event searching — are executed by a native C++17 extension (_moira_native) compiled with pybind11.

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, Saturn, Earth), 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).
• Asteroid catalog — unified catalog of 1,382 asteroids covering all 119 recognized asteroid families, including the classical four (Ceres, Pallas, Juno, Vesta), Centaurs (Chiron, Pholus, Chariklo, Asbolus, Hylonome), and Trans-Neptunians (Ixion, Quaoar, Varuna, Orcus). Built from JPL Horizons as 56 Type-13 SPK shards covering 1600–2500 CE at sub-milliarcsecond interpolation fidelity, discovered via manifest under any kernel search root. User-supplied .bsp kernels remain supported via the integrated daf_writer for any of the 887,000+ numbered minor planets in the JPL catalog.
• Numbered periodic comets — 497 comets (1P/Halley through 516P) from JPL Horizons as sharded Type-13 kernels (1600–2500 CE), with canonical numbered designations ("1P/Halley") and curated short aliases accepted as inputs.
• Uranian / Hamburg School bodies — 8 hypothetical transneptunian planets (Cupido through Poseidon) plus Transpluto.
• 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 — 499 lots with dependency graphs and condition profiling.
• Hermetic decans — 36-decan system with computed positions for all ruling stars.
• 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 — Placidus semi-arc/mundane, Regiomontanus, and Morinus method families with mundane and zodiacal variants; direct and converse directions (converse computed by true role exchange, not arc negation); speculum computation; fixed-star targets; seven conventional time-key presets.
• Returns — solar and lunar returns; planet returns.
• Time lords — annual and monthly profections; Firdaria (diurnal and nocturnal sequences, including Bonatti variant); Zodiacal Releasing (Vettius Valens method); Hyleg and Alcocoden.

Vedic / Jyotish Suite

Every Vedic engine is implemented from primary-source research (BPHS, Brihat Jataka, Saravali, Phaladeepika, Uttara Kalamrita, Jataka Parijata, Jaimini Upadesa Sutras) with per-rule citations; where classical sources disagree, the disagreement is an explicit policy switch or a recorded note — never a silent choice.

• Sidereal foundation — 40+ ayanamsa systems including star-anchored "True" ayanamsas; 27-nakshatra system; Panchanga.
• Dashas — Vimshottari with nakshatra balance; Chara Dasha (K.N. Rao's named lineage); Varshaphal (annual charts).
• 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 — 60 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.
• Heliacal phenomena — heliacal rising and setting; acronychal rising and setting; planetary elongation extremes.
• 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 transform and reference point catalog.
• 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.

• 60+ route families under /v1 — charts, positions, houses, per-stage pipeline visibility, progressions (the full dispatched method menu advertised as OpenAPI enums), primary directions, returns, transits, dashas and time lords, the complete Vedic suite (yogas, shadbala, ashtakavarga, upagrahas, avasthas, Jaimini, muhurta, sade sati), draconic charts, astrocartography, asteroids and comets, fixed stars, harmonics, harmograms, electional scoring, synastry and relationship products, and more.
• Typed transport — every route family has dedicated Pydantic request/response models, serializers, and services; doctrine stays in the engine, the server is transport and orchestration only.
• OpenAPI discovery — tagged schema with installed discovery metadata for machine consumers.

Requirements and Installation

• Python 3.10 or later
• A C++ compiler, cmake >= 3.24, and pybind11 >= 2.12 (required at build time for the native extension)
• A JPL DE-series planetary kernel (de430, de440, or de441 — not bundled; see below)

# Standard install (builds the native C++ extension)
pip install moira-astro

# With the FastAPI REST server (fastapi, uvicorn, pydantic)
pip install moira-astro[server]

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

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.

Supported kernels:

Kernel Manager (GUI)

The easiest way to download and configure a kernel is the built-in Tkinter interface. It requires no extra dependencies — Tkinter ships with CPython on all platforms.

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 kernel for the current session via set_kernel_path().
• Browse… — open any .bsp file already on disk and set it as the active kernel immediately.

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 SSD):

• 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://ssd.jpl.nasa.gov/ftp/eph/planets/bsp/de430.bsp

Small-Body Catalogs (Asteroids and Comets)

The unified asteroid catalog (1,382 bodies as 56 Type-13 shards) and the numbered periodic comet catalog (497 comets as 20 shards) are too large to ship inside the wheel and are distributed as separate downloads. Install a catalog by placing its shard directory — asteroids/ or comets/, each containing its shards and manifest.json — under any kernel search root (kernels/ at the repository root or ~/.moira/kernels/). The engine discovers every manifest under every search root automatically; no configuration call is required.

Note for pre-4.0.0 installs: the single-file supplemental kernels (comets.bsp, centaurs.bsp, minor_bodies.bsp) no longer auto-load. All small bodies now resolve through the sharded manifests.

Data Inventory

Native C++ Performance

Moira's computational core (_moira_native) is implemented in C++17 and compiled as a pybind11 extension at install time. Performance-critical paths — IAU 2000A nutation evaluation, SPK/DAF kernel reading, apparent planetary evaluation (via NativePlanetaryEvaluator), coordinate transforms, light-time iteration, harmogram computation, precession, and event searching — execute natively without Python overhead.

This matters most in phenomenon-searching loops (retrograde periods, eclipse searches, heliacal events, conjunction sweeps) where core transforms are evaluated thousands of times. The native extension is a required component and is built automatically during pip install.

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 — external chart software where stable and meaningful; doctrine-grounded invariants where no universal oracle exists. References: Swiss Ephemeris, Astro.com, canonical doctrine tables, structural invariants.

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 Oracle — outputs are benchmarked against an external reference appropriate to the domain.

When residuals remain, Moira documents them as model-basis differences rather than mislabeling them as engine defects. Two systems may be internally correct while answering different mathematical questions because of differing assumptions — for example, Delta-T branch, retarded-versus-geometric Moon treatment, or event-definition objective.

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 · Earth]
    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\n1365 lunisolar + 687 planetary terms]
    J --> K[True Equinox and Equator of Date]
    K --> L[7 · Topocentric Parallax\nWGS-84 · optional]
    K --> M[8 · Atmospheric Refraction\nSky positions 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 J2000.0

The following traces every pipeline stage for Mars on 2000 January 1, 12:00 TT, using live DE441 kernel data. All numbers are from the running engine.

Time: JD_UT 2451545.000000 → JD_TT 2451545.000739  (ΔT = +63.807 s)

Final position: Aquarius 27° 57′ 48″  ·  distance 1.8497 AU  ·  speed +0.7757°/day (direct)

Total pipeline correction from geometric to apparent: −43.760 arcsec

The largest contributors are nutation (−13.932″), annual aberration (−14.070″), and the combined light-time displacement (−15.761″). Gravitational deflection (0.006″) and frame bias (0.023″) are sub-arcsecond but non-negligible at sub-arcsecond accuracy targets.

Pipeline Controls

Each correction stage can be toggled independently via planet_at(). The table below shows the measurable effect of disabling each stage on the Mars J2000.0 result.

Project Documentation

The canonical documentation tree lives in wiki/. The flat moira.wiki/ Git wiki mirror is generated from it by python scripts/sync_git_wiki.py and should not be edited by hand.

License

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