astroceleste-engine

Astrological chart calculation on JPL ephemerides, in pure Rust.

It is the calculation core of Astroceleste. The same code runs on the server (Python bindings), in the desktop and mobile apps (native) and in the browser (WASM), so every platform computes the same chart down to the arcsecond.

Website and live demo · API docs · Guides

Experimental (0.0.x): the API may change in any release. Pin an exact version.

Status: the complete chart pipeline is ported and matches the reference implementation on every golden chart: planets, lunar nodes, Chiron, Lilith, houses (Placidus, Whole Sign, Equal, Porphyry; Koch, Regiomontanus, Campanus, Topocentric, Alcabitius, Morinus and Vehlow are checked against Swiss Ephemeris), aspects and orbs, fixed stars, Arabic parts, temperament, lunar status, horary charts (planetary hours from computed sunrise and sunset), transits, synastry and derived charts, with Python and WebAssembly bindings.

Usage

use astroceleste_engine::ephemeris::{Kernel, KernelSet, Spk};
use astroceleste_engine::{calculate_chart, ChartRequest, UtcInstant};

let mut kernels = KernelSet::new();
kernels.push(Kernel::new("de440s.bsp", Spk::open("kernels/de440s.bsp")?)?);

let request = ChartRequest::new(UtcInstant::parse("1987-05-17T14:30:00Z")?, 41.9, 12.5);
let chart = calculate_chart(&kernels, &request)?;
println!("{}", serde_json::to_string_pretty(&chart)?);

Charts serialize to the same JSON as the Astroceleste API. Other entry points: calculate_horary_chart, calculate_transit_chart, calculate_synastry, calculate_derived_chart, and for electional astrology calculate_election_chart and search_elections (the best moments over a span of time), degree_qualities (William Lilly's qualities of the zodiac degrees), chart_dignities (a stored chart judged again under another dignity scheme) and time_lords (profections and firdaria), all three with no kernel needed, and for Chinese astrology chinese_calendar (solar terms, lunar and leap months), bazi (the Four Pillars) and zi_wei (Zi Wei Dou Shu), both with no kernel needed (see Chinese astrology), and for Vedic astrology vedic_calendar (the panchanga) and jyotish (nakshatras, vargas, Vimshottari dasha, no kernel needed; see Vedic astrology). In the browser or on mobile, load the kernel from memory with Spk::from_bytes.

Bindings

• Python (pip install astroceleste-engine, CPython ≥ 3.12): Engine([kernel paths]) with .chart(), .horary(), .transit(), .election(), .elections() and .chinese_calendar() and .vedic_calendar(), plus synastry(), derived_chart(), degree_qualities(), degree_quality_table(), chart_dignities(), time_lords(), bazi(), zi_wei(), jyotish(), julian_day() and excerpt_kernel(), returning plain dicts. See crates/astroceleste-engine-py.
• JavaScript / WebAssembly (npm install astroceleste-engine): the same API over kernels loaded from memory, for browsers and Node. See crates/astroceleste-engine-wasm.

Both are tested against the same golden fixtures as the Rust crate.

Documentation

• API reference on docs.rs
• API guide: request options, the chart JSON, error codes in every language
• Ephemerides: kernels, date coverage, loading from memory, smaller excerpts for the web and mobile
• Accuracy: how every number is verified
• Architecture: crates and calculation pipeline

Layout

Path	Content
crates/astroceleste-engine	the core library
crates/astroceleste-engine-py	Python bindings (PyO3, built with maturin)
crates/astroceleste-engine-wasm	WebAssembly bindings (wasm-bindgen, built with wasm-pack)
tests/fixtures/*.json	golden charts produced by the reference implementation, the acceptance spec
tests/data/de440s_2000.bsp	one-year excerpt of DE440s used by the tests
scripts/fetch-kernels.sh	downloads full JPL kernels into kernels/ (gitignored)
scripts/make_spk_fixtures.py	rebuilds the excerpt and the SPK reference states with jplephem
scripts/make_reduction_fixtures.py	stage-by-stage reference values from Skyfield
scripts/gen_tables.py	regenerates the embedded ΔT, nutation and Chiron tables
scripts/fetch_minor_bodies.py	regenerates the minor-body tables from JPL Horizons
scripts/build-site.sh	builds the landing site and live demo into target/site/
docs/	guides
site/	landing site and live demo, deployed to GitHub Pages

Contributing

Contributions are welcome: see CONTRIBUTING.md for setup, the test suite and the rules that keep every platform identical. Report vulnerabilities privately, as described in SECURITY.md. Maintainers release by pushing a version tag (RELEASING.md).

cargo test --workspace --exclude astroceleste-engine-py   # uses the committed excerpt
scripts/fetch-kernels.sh        # full de440s (1849-2150): enables the golden and full-range tests
cargo clippy --workspace --all-targets -- -D warnings

Ephemerides

The engine reads NASA JPL SPK kernels (DE440s by default, DE441 for dates outside 1849–2150). Dates outside the loaded kernels are reported as errors, never approximated. See docs/ephemerides.md for coverage, sizes and excerpts.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

The astronomical reduction (ΔT, IAU 2000A nutation, IAU 2006 precession, light-time, deflection and aberration) is ported from Skyfield by Brandon Rhodes, used under the MIT license: see NOTICE, which is shipped in every package.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.