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 (the seven with their `Condition`), houses, aspects, fixed stars, lots, temperament, lunar status, sect, `Reception`s, antiscia, planetary hours
`calculate_horary_chart`	the chart plus `HoraryData`: planetary hours, the Moon’s aspects, strictures and the `Judgment` (significators, perfection, prohibition, translation, collection)
`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
`degree_qualities`	Lilly’s `DegreeQualities` of the degree a longitude falls in (no kernel needed)
`chart_dignities`	a computed chart’s `Condition`s and `Reception`s judged again under the Lilly or Dorothean scheme (no kernel needed)
`time_lords`	the annual `Profection`s and `Firdaria` of a nativity over a span of time (no kernel needed)
`chinese_calendar`	the `ChineseCalendar` around a moment: solar terms, lunar months, equation of time (also on a chart, with `ChartRequest::chinese_calendar`)
`bazi`	the Four Pillars (`Bazi`) of a birth from its Chinese calendar: hidden stems, Ten Gods, NaYin, element balance, luck pillars (no kernel needed)
`zi_wei`	the Zi Wei Dou Shu chart (`ZiWei`) of a birth from its Chinese calendar: palaces, bureau, the 14 major and 14 auxiliary stars with brightness, the Four Transformations, minor stars and cycles of gods, flying transformations, decade and small limits and a year’s horoscope (no kernel needed)
`jyotish`	the Vedic reading (`Jyotish`) of a chart: sidereal placements with their `Nakshatra`s, the divisional charts D1-D60 and the Vimshottari dasha (no kernel needed)
`vedic_calendar`	the panchanga (`VedicCalendar`) of a moment and place: sunrise, vara, tithi, nakshatra, yoga, karana, lunar month, samvatsara (also on a chart, with `ChartRequest::vedic_calendar`)

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§

AgeRange: A range of nominal ages (虛歲), inclusive.
Anga: One of the angas running at the moment.
AntisciaContact: Two points joined by antiscion (mirrored across the solstitial axis, Cancer–Capricorn) or contra-antiscion (across the equinoctial axis, Aries–Libra).
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.
Bazi: The Four Pillars of a birth.
BaziFlow: The pillars of a date read against a chart.
BaziOptions: How to cast the pillars.
Bureau: The five-element bureau.
Chart: A complete chart (calculate_chart_data); serializes to the API’s JSON.
ChartDignities: A chart’s dignities judged again under a scheme: what chart_dignities returns.
ChartRequest: What to compute.
ChineseCalendar: The Chinese calendar around a moment: what the Four Pillars and the Purple Star chart need from the ephemeris.
Collection: A heavier planet that both significators apply to.
Condition: The condition of one of the seven planets.
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).
DashaPeriod: A dasha period and, to the depth asked, its subperiods.
DegreeQualities: The qualities of the degree an ecliptic longitude falls in.
DegreeRun: A run of degrees sharing one quality, from the end of the previous run (or the start of the sign) up to and including end.
DignityLords: The lords of each essential dignity at a longitude.
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.
ElementBalance: Weight of each element among the eight characters (stems count 1, each branch 1 shared among its hidden stems).
EssentialDignity: A planet’s essential dignities and debilities where it stands.
Exclusions: How many moments each criteria filter left out.
Factor: One contribution to the temperament, with its weighted qualities.
Firdaria: A major period of the firdaria, with its seven sub-periods (none for the nodes).
FixedStarPosition: A fixed star conjunct a chart point.
Graha: A body or the Ascendant in the sidereal zodiac.
HiddenStem: A stem hidden in a branch.
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.
Judgment: The judgment of a horary question.
Jyotish: The Vedic reading of a chart: jyotish.
JyotishOptions: What jyotish computes; every field is optional in JSON.
Lot: An Arabic part (lot) placed in the chart.
Luck: The luck pillars (大運).
LuckPillar: A ten-year luck pillar.
LunarDate: A date of the lunisolar calendar.
LunarMansion: One of the 28 lunar mansions (manazil al-qamar).
LunarMonth: A month of the lunisolar calendar.
LunarStatus: Lunar phase, speed, dignity and mansion.
Masa: The lunar month.
MoonStatus: The Moon’s condition in a horary chart.
Nakshatra: The nakshatra of a sidereal longitude.
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.
Perfection: An aspect that becomes exact between two planets, both still in their present signs.
Period: A span of time ruled by a planet.
Pillar: A stem and a branch: one of the four pillars, or a luck pillar.
Placement: A planet, lunar point or angle placed in the chart.
PlanetCondition: The condition of one planet, by name.
PlanetaryHours: Planetary day and hour of a horary chart.
Profection: One year of life and the sign the Ascendant has profected to.
Prohibition: A third planet that perfects an aspect with one of the significators first.
Qualities: The four primary qualities.
Reception: One planet received by another: it stands in a dignity of the receiver.
Refranation: A significator that turns retrograde (or direct) before the aspect perfects.
Scores: The four temperaments.
SeparatingAspect: A Ptolemaic aspect the Moon has perfected since entering its sign.
SignDegrees: Lilly’s qualities of the degrees of one sign. Degrees are ordinal: degree n spans n-1°00’ to n-1°59’ of the sign.
SolarTerm: One of the 24 solar terms (節氣): the moment the Sun reaches a multiple of 15°.
Stricture: A consideration before judgement (stricture against judging the chart).
Synastry: Synastry between two charts.
Temperament: Temperament assessment from the chart’s qualities.
TermMoment: A solar term the pillars refer to.
TimeLords: The time-lords active over a span of a life.
TransitChart: Transits to a natal chart (calculate_transit_chart).
Translation: A lighter planet carrying the light of one significator to the other.
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.
Vara: The weekday of the Vedic day, which begins at sunrise.
Varga: A divisional chart: the Ascendant first, then the grahas.
VargaPlacement: A placement in a divisional chart.
VedicCalendar: The panchanga of a moment and place: vedic_calendar.
Vimshottari: The Vimshottari dasha of a birth, in a Jyotish reading.
ZiWei: The Purple Star chart of a birth.
ZiWeiFlowStar: A moving star of a horoscope period.
ZiWeiGod: A god of a yearly cycle of twelve.
ZiWeiGods: The gods of the four cycles of twelve in a palace.
ZiWeiHoroscope: The horoscope of a year.
ZiWeiOptions: How to cast the chart.
ZiWeiPalace: One of the twelve palaces.
ZiWeiPeriod: One period of a horoscope: a decade, the childhood limit or a year.
ZiWeiStar: A star in a palace.
ZiWeiTransformation: A natal transformation.

Enums§

DignityScheme: The doctrine of triplicities and bounds a chart is judged by.
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_DASHA_DEPTH: Most levels returned in one tree below path.
MAX_DASHA_LEVELS: Levels below the mahadashas: antardasha, pratyantardasha, sookshma, prana.
MAX_SEARCH_DAYS: Longest span a search covers, in days.
MAX_TIME_LORDS_YEARS: Longest span time_lords covers, in years.
MINOR_BODIES: The bodies with a Horizons table, in chart order.
NAKSHATRAS: The 27 nakshatras from Ashwini, 13°20′ each from 0° sidereal Aries.
VARGAS: The vargas computed: the sixteen of Parashara’s shodashavarga plus D5, D6, D8 and D11.

Functions§

bazi: Cast the Four Pillars of a birth at birth (UTC), at longitude (degrees east) where civil time was utc_offset_minutes ahead of UTC, from its calendar (chinese_calendar of the same moment).
calculate_chart: Compute a chart (calculate_chart_data), with its planetary day and hour.
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). quesited_house (1-12) is the house of the matter asked about; its lord is judged against the lord of the Ascendant.
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). req.chinese_calendar and req.vedic_calendar are ignored: a transit chart has no calendar.
chart_dignities: Judge the dignities of an already computed chart (its JSON, as calculate_chart returns it: planets with name, ecliptic_longitude and speed, and aspects) under scheme (“lilly” or “dorothean”). No kernel is needed: a chart stored with one scheme can be shown with the other.
chinese_calendar: The Chinese calendar around instant, or None when the loaded kernels do not cover the year or so of ephemeris it needs (about 14 months before the moment and 2 after).
degree_qualities: The qualities of the degree longitude (ecliptic, in degrees) falls in. The zodiac is whatever the longitude is measured in, as for every sign-based rule.
degree_quality_table: Lilly’s table of the degree qualities, one entry per sign from Aries.
is_minor_body: Whether name is one of MINOR_BODIES.
jyotish: The sidereal placements, nakshatras, vargas and Vimshottari dasha of chart (the chart JSON, tropical or sidereal under any ayanamsa) born at birth, under the ayanamsa of options.
nakshatra: The nakshatra of sidereal longitude longitude (degrees).
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.
time_lords: Annual profections and firdaria from birth (with the natal Sun’s and Ascendant’s longitudes), for the years that overlap start..end (at most MAX_TIME_LORDS_YEARS after the birth or the start, whichever is later).
vedic_calendar: The panchanga at instant for a place, or None when the loaded kernels do not cover the lunar month around it.
zi_wei: Cast the Purple Star chart of a birth at birth (UTC), at longitude (degrees east) where civil time was utc_offset_minutes ahead of UTC, from its calendar.