Crate astroceleste_engine

Expand description

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 `CrossAspect`s 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)
`calculate_election_chart`	the chart plus `ElectionData`: an electional score with the rules that apply
`search_elections`	the best `ElectionWindow`s over a span of time at a place

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.
CriteriaSummary: The criteria a search ran with, defaults resolved (the natal chart only as a flag).
CrossAspect: A cross-aspect between an overlay body (transit, partner) and a base body (natal).
ElectionChart: A chart for a candidate moment with its electional assessment (serialized flattened).
ElectionCriteria: What to look for. Every field has a default, so {} is a valid criteria object.
ElectionData: The electional assessment of a moment.
ElectionFactor: One electional rule that applies to a moment.
ElectionSearch: The result of a search.
ElectionWindow: A run of consecutive assessed moments scoring at least the minimum.
Exclusions: How many moments each criteria filter left out.
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.
HourRange: Local clock hours, from inclusive to to exclusive; from > to spans midnight.
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.
NatalPoint: A natal point, as in a stored chart’s planets list (other fields are ignored).
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.
UtcOffset: The UTC offset of local time from an instant on (until the next one), so that ElectionCriteria::local_hours follows daylight saving time.

Enums§

EngineError: Why a calculation failed. EngineError::code gives the API error code.
Purpose: What the election is for. Each purpose has a house of the matter, a natural significator and the planetary hours that favour it.

Constants§

MAX_SEARCH_DAYS: Longest span a search covers, in days.

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_election_chart: A chart for a candidate moment with its electional assessment.
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).
search_elections: The best windows from req.instant to end (at most MAX_SEARCH_DAYS) at the request’s place, with its house system and zodiac.