xalen-ephemeris

XALEN Ephemeris

A pure-Rust astronomical ephemeris for astrology — JPL-class planet accuracy, zero unsafe core, Apache-2.0.

Publish status: the Rust crates, the PyPI xalen wheel, and the npm xalen (native) / xalen-ephemeris (WASM) packages are not published to their registries yet — the Crates.io / docs.rs registry badges above are placeholders until first release. Build from source per the per-binding READMEs (crates/xalen-python, crates/xalen-node, crates/xalen-wasm).

Validated against the references that matter — JPL Horizons DE440 (NASA's definitive ephemeris), the real DE440 binary kernel, Swiss Ephemeris, and the public calculators (astro.com, AstroSage, Drik Panchang, Prokerala, Jagannatha Hora). Sun + Mercury–Saturn sub-arcsecond vs DE440 (Sun 0.21″, Mercury–Saturn ≤ 0.76″; Uranus/Neptune ~1.8–2.5″, Pluto arcminute-class in-window). Analytical Moon RMS ~2.8″ / max ~12″ vs pyswisseph (AD 1600–2100); the DE440 kernel takes the Moon sub-arcsecond. Pure Rust, zero unsafe in the core, thread-safe, Apache-2.0. Full report → docs/ACCURACY.md.

use xalen_ephem::{Almanac, Body};
use xalen_time::{calendar_to_jd, CalendarSystem, JulianDay};
use xalen_ayanamsa::Ayanamsa;
use xalen_vedic::nakshatra::Nakshatra;

let jd = calendar_to_jd(1990, 3, 15, 12.0 - 5.5, CalendarSystem::default());
let almanac = Almanac::default_vedic();
let pos = almanac.geocentric_ecliptic(Body::Moon, jd).unwrap();
let sid = (pos.longitude.to_degrees() - Ayanamsa::Lahiri.compute_deg(jd.as_f64())).rem_euclid(360.0);
println!("{}", Nakshatra::from_longitude_deg(sid)); // Swati

What You Get

• 50 ayanamsa systems -- Lahiri, KP Krishnamurti, Raman, Fagan-Bradley, True Chitrapaksha, True Revati, Surya Siddhanta, all Galactic Center variants, Babylonian (Kugler), all Swiss Ephemeris IDs (0-46), plus a fully custom variant with user-defined epoch, value, and precession rate

• 23 house systems -- Placidus, Koch, Campanus, Regiomontanus, Whole Sign, Equal, Porphyry, Morinus, Alcabitius, Topocentric (Polich-Page), Meridian, Vehlow, Sripati, Krusinski-Pisa, Sunshine (Makransky & Treindl), Pullen Sinusoidal (Delta & Ratio), Carter Poli-Equatorial, APC, Zariel, Alcabitius Classic -- with automatic Porphyry fallback at polar latitudes. (Gauquelin sectors is an experimental placeholder that currently returns Placidus cusps, not a true Gauquelin division.)

• 12+ astrology traditions -- Vedic/Jyotish (dasha, shadbala, KP, Jaimini, Tajaka, panchang with tithi/nakshatra/yoga/karana transition times, compatibility, 16 divisional charts, yoga, dosha), Western (aspects, dignities, 97 Arabic Lots, Hellenistic, Uranian, Cosmobiology, progressions, exact solar/lunar returns by iterative refinement, declination aspects + antiscia, harmonics, horary), Chinese (BaZi, Zi Wei Dou Shu, Feng Shui Flying Stars, Qi Men Dun Jia [experimental]), Lal Kitab, I Ching (64 hexagrams + all 384 line texts, verbatim public-domain Legge SBE XVI), Numerology, Korean Saju, Japanese Nine Star Ki, Burmese Mahabote (day-sign profile only), Mayan, Aztec, Tibetan, Persian/Zoroastrian, Egyptian, Celtic

• 506 built-in fixed stars (in xalen-western) with proper motion and precession correction (all mag Availability note: crates.io currently serves the 0.3.1 line (leaf

crates). The 0.4.x / 0.5.x releases described in this README are not yet published to crates.io — publishing is in progress. Until it lands, either pin 0.3 or depend on this repository directly with a git/path dependency. The Node.js (xalen, npm) and Python (xalen, PyPI) packages are not yet published; see Language Bindings below for building from source.

# crates.io (currently serves the 0.3.1 line):
cargo add xalen-ephemeris

Or pick individual crates for a smaller footprint (pin to the latest published version):

[dependencies]
xalen-ephem = "0.3"         # planetary engine
xalen-vedic = "0.3"         # Vedic astrology
xalen-houses = "0.3"        # house systems
xalen-ayanamsa = "0.3"      # ayanamsa / sidereal conversion
xalen-time = "0.3"          # Julian Day, delta-T, calendars

Quick Start

Vedic chart: Sun and Moon with nakshatra and rashi

With only xalen-ephemeris added, every sub-crate is reachable through the umbrella re-exports (xalen_ephemeris::ephem, ::vedic, ::time, …):

…

Western chart: aspects and dignities

use xalen_ephemeris::western::aspects::{find_all_aspects, AspectType};
use xalen_ephemeris::western::dignity::essential_dignity_score;

More examples

cargo run --example basic_chart      # Sun/Moon + nakshatra + rashi
cargo run --example vedic_chart      # Full Vedic chart with dasha, shadbala, panchang
cargo run --example western_chart    # Aspects, dignities, Arabic Lots
cargo run --example chinese_bazi     # BaZi Four Pillars with Wu Xing

Accuracy

For most astrological applications, the analytical theories (VSOP87A, ELP2000-82) provide more than enough precision -- they require zero external data files and work entirely from compiled-in polynomial series; the analytical Moon now lands within RMS ~2.8" of Swiss Ephemeris across four centuries. Load DE440 when you need JPL-grade sub-arcsecond precision on the Moon and outer bodies, full-range Pluto, or primary directions to the minute.

Sub-arcsecond Moon with zero manual kernel handling. Enable the optional kernel-autodownload feature and call De440Provider::from_auto_cache(); the public NASA NAIF de440s.bsp kernel (~32 MB) is fetched once into the OS cache directory, verified, and reused thereafter. The feature is off by default so the base crate stays offline and data-file-free:

[dependencies]
xalen-ephem = { version = "0.6", features = ["kernel-autodownload"] }

use xalen_ephem::De440Provider;
// First call fetches + caches de440s.bsp; later calls reuse it (no network).
let provider = De440Provider::from_auto_cache()?;
// Apparent Moon (and all kernel bodies) now sub-arcsecond.

Eclipse output now includes both a global-circumstances classifier (type / Besselian γ / greatest eclipse; the global figure is a diameter-ratio coverage proxy, not a true magnitude) and a Besselian local-circumstances engine that does provide a real per-observer magnitude, obscuration, and C1–C4 contact times.

Crate Map

Language Bindings

The pip install xalen / npm install xalen commands in the migration guides describe the intended published interface and are not live yet. There is an unrelated xalen package on PyPI (a separate XALEN SDK) — it is not these ephemeris bindings. Until the bindings are published, build them from this repository with the commands above.

Core computation crates compile to wasm32-unknown-unknown without modification.

All four bindings expose the full (lon, lat, dist, lon_speed, lat_speed, dist_speed) 6-tuple plus a retrograde flag, matching what swe.calc_ut(..., FLG_SPEED) returns. The Python binding additionally ships an xalen.swe submodule (import xalen.swe as swe) intended as a near-drop-in substitute for import swisseph as swe for the common calc_ut / fixstar2 calls — a search-and-replace migration path, not a 1:1 reimplementation of every pyswisseph entry point.

Architecture

• Pure Rust -- no C FFI dependencies in any core crate
• No unsafe in core crates -- only xalen-ffi uses unsafe (required for extern "C")
• Zero global state -- all computation through owned or Arc references
• Thread-safe -- `A