Astrology Engine

A Rust library for calculating astrology charts: planetary positions, chart angles, and house cusps.

Calculate a natal chart

Supply a birth instant, latitude and longitude, and a house system. calculate_chart returns the chart's body positions, angles, and optional house cusps using a reusable ephemeris dataset.

From this repository, use the Rust toolchain pinned in rust-toolchain.toml and supply a compatible HDCHEB01 ephemeris file. Dataset binaries are supplied separately; the repository includes dataset generation guide.

cargo run --locked --example natal_chart -- /path/to/cheb.bin

The example uses a birth instant of 1 January 2000 at 12:00 UTC, a London location, and equal houses. Convert the person's local birth time to an unambiguous instant before calling the library. The dataset must cover that instant and the half-day samples on either side used to calculate speeds.

The complete source is examples/natal_chart.rs:

use astrology_engine::{calculate_chart, ChartInput, Ephemeris, Epoch, HouseSystem, Location};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let dataset = std::env::args_os()
        .nth(1)
        .ok_or("Usage: cargo run --example natal_chart -- /path/to/cheb.bin")?;
    let ephemeris = Ephemeris::parse(std::fs::read(dataset)?)
        .map_err(|error| format!("Cannot load ephemeris: {error}"))?;

    let birth_moment = Epoch::from_gregorian_str("2000-01-01T12:00:00 UTC")?;
    let chart = calculate_chart(
        &ephemeris,
        ChartInput {
            epoch: birth_moment,
            location: Location {
                latitude: 51.5074,
                longitude: -0.1278,
            },
            house_system: HouseSystem::Equal,
        },
    )?;

    println!("Birth moment: {birth_moment}");
    println!("Longitudes in degrees:");
    for body in &chart.bodies {
        println!("{:<20} {:>12.6}", body.name, body.longitude);
    }
    if let Some(cusps) = &chart.cusps {
        println!("House cusps in degrees: {cusps:?}");
    }

    Ok(())
}

The example prints the body and angle longitudes and the twelve equal-house cusps. Each body entry also contains longitudinal speed and declination. The returned ChartValues can be used to display a chart in your application.

Load and parse the ephemeris once, then reuse it for subsequent charts.

Human Design design-date search

The library also supports finding the design instant used in Human Design: when the Sun was 88° before its birth longitude. Starting with a natal chart, subtract 88° from the birth Sun's longitude, wrap into [0°, 360°), and call find_sun_crossing with Direction::Backward.

The offset is an angle; the search determines the corresponding date and time. You can then call calculate_chart at that instant to obtain its planetary positions, using the same ephemeris.

The birth and design example demonstrates the complete workflow:

cargo run --locked --example birth_and_design -- /path/to/cheb.bin

This search requires at least 89 days of dataset coverage before birth. The dataset must also cover the returned design instant and the surrounding half-day samples used by chart calculations.

Architecture and entry points

Read From JPL data to a natal chart for the preparation and runtime pipeline: JPL inputs, chart-coordinate samples, Chebyshev coefficients, and chart calculation.

• Public Rust API: chart calculation, ephemeris evaluation, and solar longitude search.
• Example Cloudflare Worker: an HTTP adapter that loads the dataset from R2 and calls the library.
• Deploy the Worker demo: generate a dataset, test locally, deploy a public demo in your Cloudflare account, and clean up.