Crate astroceleste_engine 

astroceleste-engine: astrological chart calculation on JPL ephemerides.

One implementation shared by the Astroceleste server (Python bindings), desktop and mobile apps (native) and the web app (WASM), so every platform computes identical charts.

Experimental (0.0.x): the API may change in any release.

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

// Kernels in preference order: the first one covering a date is used.
let mut kernels = KernelSet::new();
kernels.push(Kernel::new("de440s.bsp", Spk::open("kernels/de440s.bsp")?)?);

let mut request = ChartRequest::new(UtcInstant::parse("1987-05-17T14:30:00Z")?, 41.9, 12.5);
request.house_system = "P";
request.zodiac_type = "sidereal";
request.ayanamsa = "lahiri";

let chart = calculate_chart(&kernels, &request)?;
println!("{}", serde_json::to_string_pretty(&chart)?);

Entry points

Function	Result
calculate_chart	a natal or event Chart: planets, houses, aspects, fixed stars, lots, temperament, lunar status
calculate_horary_chart	the chart plus HoraryData: planetary hours, significators, the Moon’s aspects, strictures
calculate_transit_chart	the sky at a moment and place, with its CrossAspects to natal planets
calculate_synastry	cross-aspects between two charts’ planets (no kernel needed)
calculate_derived_chart	a stored chart turned to a new first house (no kernel needed)

Every result implements serde::Serialize and serializes to the JSON of the Astroceleste API, with the same key order and the same integer vs float types. The Python and WebAssembly bindings return exactly that JSON.

Loading kernels

Positions come from NASA JPL SPK kernels (de440s.bsp covers 1849–2150; DE441 covers 13200 BC–17191). A KernelSet holds them in preference order, and each date is computed with the first kernel that covers it. Spk::open reads a file. Where there is no file system (WebAssembly) or the kernel is bundled with an app, load the bytes and use Spk::from_bytes. Spk::excerpt cuts a smaller kernel for a date range, with positions unchanged inside it (1950–2050 of DE440s is about 11 MB).

use astroceleste_engine::ephemeris::{Kernel, KernelSet, Spk};

let bytes: Vec<u8> = download("https://example.com/de440s-1950-2050.bsp");
let mut kernels = KernelSet::new();
kernels.push(Kernel::new("de440s-1950-2050.bsp", Spk::from_bytes(bytes)?)?);
assert!(kernels.coverage().is_some());

Errors

Calculations return EngineError, whose code is the stable error code of the Astroceleste API. A date that no loaded kernel covers is EngineError::OutOfRange: the engine never extrapolates or approximates.

let request = ChartRequest::new(UtcInstant::parse("1700-01-01T00:00:00Z")?, 41.9, 12.5);
match calculate_chart(&kernels, &request) {
    Ok(chart) => println!("{} planets", chart.planets.len()),
    Err(EngineError::OutOfRange { jd, coverage }) => {
        eprintln!("JD {jd} is outside the loaded kernels ({coverage:?})")
    }
    Err(err) => eprintln!("{}: {err}", err.code()),
}

Platforms

The crate is pure Rust with no C code, and depends only on serde and serde_json. It builds for servers and desktops, wasm32-unknown-unknown, Android and iOS. Python (pip install astroceleste-engine) and JavaScript (npm install astroceleste-engine) bindings are published from the same repository.

Further reading

• API guide: request options (house systems, ayanamsas, orb settings) and the chart JSON
• Ephemerides: kernels, coverage and excerpts
• Accuracy: how results are verified against the reference implementation
• Live demo: this crate compiled to WebAssembly, computing charts in your browser

Modules

ephemeris

Ephemeris sources. Everything above this layer (houses, aspects, lots, stars, …) is independent of where planetary positions come from.

Structs

ApplyingAspect

A Ptolemaic aspect the Moon perfects before leaving its sign.

Aspect

An aspect between two chart points. Fixed-star conjunctions carry no is_major.

Chart

A complete chart (calculate_chart_data); serializes to the API’s JSON.

ChartRequest

What to compute.

CrossAspect

A cross-aspect between an overlay body (transit, partner) and a base body (natal).

Factor

One contribution to the temperament, with its weighted qualities.

FixedStarPosition

A fixed star conjunct a chart point.

HoraryChart

A horary chart: a complete chart plus horary_data (serialized flattened).

HoraryData

The horary-specific part of a horary chart.

HouseCusp

The cusp of one house.

Lot

An Arabic part (lot) placed in the chart.

LunarMansion

One of the 28 lunar mansions (manazil al-qamar).

LunarStatus

Lunar phase, speed, dignity and mansion.

MoonStatus

The Moon’s condition in a horary chart.

ParseError

The text given to UtcInstant::parse is not a supported date-time.

Placement

A planet, lunar point or angle placed in the chart.

PlanetaryHours

Planetary day and hour of a horary chart.

Qualities

The four primary qualities.

Scores

The four temperaments.

SeparatingAspect

A Ptolemaic aspect the Moon has perfected since entering its sign.

Stricture

A consideration before judgement (stricture against judging the chart).

Synastry

Synastry between two charts.

Temperament

Temperament assessment from the chart’s qualities.

TransitChart

Transits to a natal chart (calculate_transit_chart).

UtcInstant

A UTC instant, as microseconds since 1970-01-01T00:00:00Z.

Enums

EngineError

Why a calculation failed. EngineError::code gives the API error code.

Functions

calculate_chart

Compute a chart (calculate_chart_data).

calculate_derived_chart

A derived (turned) chart: radix house root (1-12) becomes the first house; cusps, angles and house placements follow, with the meaning of each derived house (calculate_derived_chart_data). Works on a stored chart payload, keeping every field it does not turn.

calculate_horary_chart

A chart for the moment of the question, with its horary analysis (calculate_horary_chart_data).

calculate_synastry

Cross-aspects from chart B (overlay) to chart A (base) (calculate_synastry_chart).

calculate_transit_chart

The sky at req (relocatable), with its cross-aspects to natal_planets (calculate_transit_chart).