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 and calculate_derived_chart. 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(), plus synastry() and derived_chart(), 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

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.