Metadata-Version: 2.4
Name: caelus-engine
Version: 0.11.0
Summary: Clean-room astrological ephemeris engine: planetary and lunar positions, houses, aspects, and events from published sources. The Python reference for the Caelus engine.
Author-email: EphemEngine <info@ephemengine.com>
License: MIT
Project-URL: Homepage, https://ephemengine.com
Project-URL: Repository, https://github.com/heavyblotto/caelus
Project-URL: Issues, https://github.com/heavyblotto/caelus/issues
Project-URL: Changelog, https://github.com/heavyblotto/caelus/blob/main/CHANGELOG.md
Keywords: astronomy,astrology,ephemeris,vsop87,horoscope,chart,houses,aspects
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: fit
Requires-Dist: numpy>=1.24; extra == "fit"
Dynamic: license-file

# caelus-engine

The Python reference implementation of the Caelus astrological ephemeris
engine. Clean-room, MIT-licensed, written from published sources (VSOP87D,
ELP/Meeus, IAU models, JPL Horizons fits). No Swiss Ephemeris code, no
bundled third-party ephemeris files.

The engine reads pre-built Chebyshev and series packs shipped with the
package and runs on the Python standard library alone. It is also the
reference that the TypeScript engine (`caelus` on npm) is pinned to by a
golden conformance suite.

## Install

```bash
pip install caelus-engine
```

The import package is `astroengine`:

```python
from astroengine import Engine, BODIES

eng = Engine("full")
jd = 2451545.0  # 2000-01-01 12:00 UT
for body in BODIES:
    print(f"{body:10s} {eng.longitude(body, jd):10.5f}")
```

## What it computes

- Planetary and lunar apparent geocentric ecliptic longitudes (VSOP87D for
  the planets, Meeus Ch. 47 for the Moon, Meeus Ch. 37 series for Pluto),
  with light-time, annual aberration, FK5 frame correction, and IAU 1980
  nutation.
- 12 house systems; tropical and sidereal (7 ayanamsas).
- Aspects with configurable orbs.
- Events: rise/set/transit, longitude crossings, lunar phases, stations,
  Gauquelin sectors, solar and lunar eclipses.
- Fixed stars and topocentric positions.
- Derived charts: returns, secondary progressions, solar arc, composite and
  Davison, harmonics, antiscia, declination aspects and parallels,
  out-of-bounds, dignities, sect.
- Electional primitives: applying/separating aspects, solar phase
  (cazimi/combust/under-the-beams), planetary hours, void-of-course Moon,
  house placement.
- A declarative `when()` query engine over celestial predicates.
- A turbo tier (`Turbo`): segmented Chebyshev longitude packs fit to the
  engine for bulk scans.
- 3D aspects (`angular_separation_3d`): the great-circle angle between two
  bodies, accounting for ecliptic latitude.
- Astrocartography (`astrocartography`): the planetary angle lines (MC/IC
  meridians, ASC/DSC rising and setting tracks) across the globe.

## Accuracy

Accuracy is calibrated against Swiss Ephemeris and validated against JPL
Horizons, stated per body rather than as a blanket figure. See the
validation tables at https://ephemengine.com.

## Optional: the fitting toolchain

The engine runs without any third-party dependency. The data-fitting tools
that regenerate the coefficient packs need numpy:

```bash
pip install "caelus-engine[fit]"
```

## License

MIT. See `LICENSE`. Project home: https://ephemengine.com. Source:
https://github.com/heavyblotto/caelus.
