Metadata-Version: 2.4
Name: moira-astro
Version: 0.1.2
Summary: Pure Python ephemeris and astrology engine built on JPL DE441 and SPK kernels.
Author: Moira contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/TheDaniel166/moira
Project-URL: Repository, https://github.com/TheDaniel166/moira
Project-URL: Issues, https://github.com/TheDaniel166/moira/issues
Keywords: astronomy,astrology,ephemeris,jpl,spk,sidereal,houses,transits
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jplephem>=2.24
Provides-Extra: fast
Requires-Dist: numpy>=1.24; extra == "fast"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6.0; extra == "dev"
Requires-Dist: pytest>=9.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.5; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Requires-Dist: hypothesis>=6.100; extra == "dev"
Requires-Dist: pyerfa>=2.0; extra == "dev"
Dynamic: license-file

# MOIRA

### The Pure-Python Ephemeris for the 21st Century

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Precision: Sub-Milliarcsecond](https://img.shields.io/badge/Precision-Sub--Milliarcsecond-success.svg)](#validation)
[![Standard: JPL DE441](https://img.shields.io/badge/Standard-JPL%20DE441-blueviolet.svg)](https://naif.jpl.nasa.gov/naif/index.html)

![Moira Header Banner](moira/docs/assets/hero_banner.png)

> *Moira* — In Greek myth, the goddess who assigns each soul its fate. The one who measures the thread.

Moira is a **Pure-Python** astronomical engine designed for the absolute inversion of the "Black Box" ephemeris standard. By combining **JPL DE441** kernels, **IAU 2000A/2006** reduction suites, and **Gaia DR3** distancing, Moira delivers sub-milliarcsecond precision in an auditable, modern architecture.

---

## The Light Box Manifesto

The era of opaque pre-computation is over. Moira performs **Luminous Derivation**—deriving every astronomical coordinate through visible, auditable logic at runtime.

### The Inversion of the Standard

| Attribute | The Black Box (Legacy) | The Light Box (Moira) |
| :--- | :--- | :--- |
| **Logic Substrate** | Compiled C / Opaque Loops | Pure, Auditable Python 3.10+ |
| **Data Standard** | Proprietary `.se1` Binary Files | Raw **JPL DE441** SPK Kernels |
| **Star Database** | 118K Stars (Hipparcos 1997) | **1.8 Billion** Stars (Gaia DR3 2022) |
| **Precision Anchor** | Software-to-Software Mimicry | **External Physics Oracles (SOFA/ERFA)** |
| **Uncertainty** | Silent Fallbacks | Explicit **Uncertainty Envelopes** |

---

## The Three Gates of Evidence

Every calculation in Moira must pass through the **Three Gates of Evidence** to be considered "Luminous." We don't ask for trust; we provide the evidence.

![The Three Gates](moira/docs/assets/three_gates.png)

1.  **Gate of Source**: All raw data can be verified against an independent physical observatory (JPL, NASA, ESA).
2.  **Gate of Flow**: Every transformation (Nutation, Aberration, Light-Time) is readable as code, not hidden in a compiled buffer.
3.  **Gate of Oracle**: Continuous `pytest` suites benchmark every computation against the **IAU SOFA/ERFA** reference routines at sub-milliarcsecond accuracy.

---

## The Case for a New Engine

![Gaia DR3 Background](moira/docs/assets/gaia_dr3.png)

Since the release of the Swiss Ephemeris in 1997, the astronomical world has shifted. The Hipparcos catalog has been superseded by **Gaia DR3**, providing 3D parallax for billions of stars. Asteroid discovery has exploded from 10,000 to over **887,000+**. 

Legacy data files cannot compute a body they were not pre-built for. They cannot access IERS real-time Earth orientation data. They have no pathway to Gaia parallax. **Moira is built to reach all of these things.**

See [`BEYOND_SWISS_EPHEMERIS.md`](wiki/01_doctrines/BEYOND_SWISS_EPHEMERIS.md) and [`01_LIGHT_BOX_DOCTRINE.md`](wiki/01_doctrines/01_LIGHT_BOX_DOCTRINE.md) for more detail.

---

## Architectural Visualization

### The Reduction Pipeline

```mermaid
graph TD
    A[JPL DE441 Kernels] --> B[Relative State Vectors]
    C[Gaia DR3 Catalog] --> B
    B --> D[Astrometric Position]
    D --> E[Correction Suite]
    E --> F[Light-Time Correction]
    E --> G[Stellar Aberration]
    E --> H[Relativistic Deflection]
    F & G & H --> I[Apparent Geocentric Position]
    I --> J[Nutation & Precession Suite]
    J --> K[Apparent Equinox/Equator]
    K --> L[API: Topocentric / Sidereal / Houses]
```

---

## What Moira Computes

### Positions and Bodies
- **Planets, Moon, Sun**: Geocentric and topocentric reduction with light-time, aberration, and relativistic deflection.
- **Deep Asteroid Support**: Direct access to 887,000+ asteroids via JPL Horizons and SPK kernels.
- **Small Bodies**: Dedicated specialists for Centaurs (Chiron, Pholus), TNOs (Eris, Sedna), and uranian Hamburg School bodies.
- **Nodes & Apsides**: True/Mean nodes, Lilith, and orbital nodes/apsides for all planetary bodies.
- **Fixed Stars**: ~1.5K from SE catalog + Gaia DR3 binary catalog (~290K entries) with BP-RP spectral color mapping.
- **Star Groups**: 15 Behenian stars, Royal Stars, Pleiades, and Orion belt clusters.
- **Variable Stars**: Phase and magnitude engine; eclipsing binary models (Algol-specific API).

### Chart Calculations
- **House Systems**: 18 systems including Placidus, Koch, Regiomontanus, APC, and Sunshine.
- **Relational Logic**: 22 zodiacal aspects with applying/separating detection; midpoints and midpoint trees.
- **Traditional Dignities**: Domicile, Exaltation, Triplicity, Term, Face, Mutual Reception, Sect, and Almuten Figuris.
- **Esoterica**: 499 Arabic Parts; Hermetic 36-decan system; 12 major Aspect Patterns (Yod, Kite, Mystic Rectangle).

### Predictive Techniques
- **Progressions**: Secondary, Tertiary, and Minor progressions (direct and converse).
- **Directions**: Primary Directions (Placidus semi-arc and mundane) and Solar Arc progressions.
- **Cycles**: Solar/Lunar returns, Vimshottari Dasha periods, and Zodiacal Releasing.
- **Time Lords**: Profections (Annual/Monthly), Firdaria, and Hyleg/Alcocoden detection.

### Advanced Astronomy
- **Eclipse Search**: NASA-canon contact solver for solar/lunar eclipses; Saros series with heptagonal vertex labeling.
- **Heliacal Dynamics**: Heliacal rising/setting of stars; Parans (paranatellonta) field analysis.
- **Mapping & Occultations**: Astrocartography (ACG) contour mapping; Lunar/Stellar occultations and planetary phenomena.
- **Temporal Systems**: 28-mansion Arabic lunar station system (Manazil); Sothic cycle drift and Egyptian civil calendar conversion.

### Precision Infrastructure
- **Nutation**: IAU 2000A (1,358 luni-solar terms + 1,056 planetary terms).
- **Precession**: IAU 2006 P03 (The current high-precision standard).
- **Time Model**: Hybrid ΔT model integrating IERS data, GRACE satellite LOD series, and historical paleoclimate tables.
- **Sidereal**: 30 validated ayanamsa systems (Lahiri, Fagan-Bradley, Raman).

---

## Quick Start

```python
from datetime import datetime, timezone
from moira import Moira

# Initialize the 'Glass Engine'
m = Moira()

# Cast a chart for the Millennium
chart = m.chart(datetime(2000, 1, 1, 12, 0, tzinfo=timezone.utc))

print(f"Sun Longitude:  {chart.planets['Sun'].longitude:.6f}")
print(f"Moon Longitude: {chart.planets['Moon'].longitude:.6f}")
```

---

## Requirements & Installation

- **Python 3.10+** (`dataclasses(slots=True)` and union type syntax are the minimum requirements)
- **jplephem >= 2.24**
- **Local JPL Kernels** (`de441.bsp`, `asteroids.bsp` - see documentation)

```powershell
# Minimal install — pure Python, zero compiled dependencies
python -m pip install moira-astro

# With numpy acceleration (recommended)
python -m pip install moira-astro[fast]

# Source installation
git clone https://github.com/TheDaniel166/moira.git
cd moira
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
```

### Pure Python vs. numpy — what this means

Moira is a **pure Python engine by design**. Every calculation is auditable,
readable, and runs without any compiled extension. This is a deliberate
architectural choice — the Light Box doctrine requires that the full
computation chain be inspectable without a C compiler.

**numpy is entirely optional.** When present, it accelerates the inner loops of
the IAU 2000A nutation engine (2,414 IERS terms) using vectorised matrix
operations. When absent, the pure Python path runs identically — same IERS
tables, same formulas, same results.

| | Without numpy | With numpy (`pip install moira-astro[fast]`) |
| :--- | :--- | :--- |
| **Nutation per call** | ~2.7 ms | ~0.035 ms |
| **Speedup** | baseline | **~79×** |
| **Numerical difference** | — | < 3×10⁻¹⁶ degrees |
| **Pure Python guarantee** | yes | yes — pure Python path preserved |
| **Auditability** | full | full — numpy path is acceleration only |

The nutation engine is called for every position computation. A 79× reduction
in nutation cost is material for workloads that compute many positions at
different epochs (transits, progressions, solar arc directions, eclipse searches).

If numpy is installed, Moira uses it silently. If it is not, Moira runs
correctly without it. No configuration is required either way.

---

## Internal Documentation

| Document | Contents |
| :--- | :--- |
| [`THE_COVENANT.md`](wiki/00_foundations/THE_COVENANT.md) | The constitutional laws governing the project and its development. |
| [`SCP.md`](wiki/00_foundations/SCP.md) | The Subsystem Constitutionalization Process (SCP) methodology. |
| [`01_LIGHT_BOX_DOCTRINE.md`](wiki/01_doctrines/01_LIGHT_BOX_DOCTRINE.md) | The philosophical and technical inversion of the ephemeris standard. |
| [`BEYOND_SWISS_EPHEMERIS.md`](wiki/01_doctrines/BEYOND_SWISS_EPHEMERIS.md) | Capabilities impossible before Gaia, Horizons, and modern Python. |
| [`MOIRA_ROADMAP.md`](wiki/06_roadmap/MOIRA_ROADMAP.md) | The strategic path toward substrate parity and transcendence. |
| [`VALIDATION_ASTRONOMY.md`](wiki/03_validation/VALIDATION_ASTRONOMY.md) | Sub-milliarcsecond validation reports against JPL Horizons. |

---

## License

MIT © 2026 Burkett
