Rust JPL Ephemeris Reader (rust-jpl)

rust-jpl is a Rust library that enables integration of NASA Jet Propulsion Laboratory (JPL) ephemeris data into Rust applications.
It provides high-precision planetary and lunar positions based on a given Julian date, using official NASA JPL DE ephemerides (DE441).

The library is designed for scientific correctness, API clarity, and performance, making it suitable for research, engineering, simulation, and educational use.

---

✨ Features

| Feature | Description | Status | | ----------------------- | -------------------------------------------- | ------- | | Planetary Positions | High-precision positions of celestial bodies | ✓ | | JPL Ephemeris Support | Official NASA JPL DE441 ephemeris | ✓ | | Time Conversions | Calendar ↔ Julian date conversion | ✓ | | Lunar Ephemerides | Accurate Moon calculations | ✓ | | Solar System Dynamics | Barycentric and heliocentric data | ✓ | | Scientific Applications | Engineering and research-grade accuracy | ✓ | | Multiple Ephemerides | Support for additional DE versions | Planned | | Gravitational Effects | Gravity-based calculations | Planned | | Celestial Phenomena | Event prediction and tracking | Planned |

---

🧭 Use Cases

• Astronomy and astrophysics research
• Orbital mechanics and trajectory planning
• Space mission planning
• Celestial navigation
• Satellite and ground-station tracking
• Educational tools and simulations
• Scientific visualization software

---

🛠 Requirements

| Requirement | Version | | --------------- | --------------------- | | Rust (MSRV) | 1.70.0 or newer | | Cargo | Comes with Rust | | Supported OS | Linux, macOS, Windows | | Architecture | x86_64, aarch64 |

The MSRV is documented and respected. Breaking MSRV changes will require a minor or major release.

---

📦 Installation

From crates.io

[dependencies]
rust-jpl = "0.0.1-alpha"

From source

git clone https://github.com/chinmayvivek/rust-jpl
cd rust-jpl
cargo build --release

---

🚀 Quick Start

Basic Usage

use rust_jpl::{Ephemeris, JulianDate};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut eph = Ephemeris::new("config.toml")?;

    let jd = JulianDate::from_calendar(2024, 1, 15, 12, 0, 0.0)?;
    let position = eph.get_position("Earth", jd)?;

    println!(
        "Earth position: ({}, {}, {}) AU",
        position.x, position.y, position.z
    );

    Ok(())
}

---

⏱ Time Conversion

use rust_jpl::{CalendarDate, JulianDate};

let cal = CalendarDate::new(2024, 1, 15, 12, 0, 0.0);
let jd = cal.to_julian()?;
println!("Julian Date: {}", jd.as_f64());

let cal2 = jd.to_calendar();
println!("Calendar: {}-{:02}-{:02}", cal2.year, cal2.month, cal2.day);

---

🪐 Planetary Positions

use rust_jpl::{Ephemeris, JulianDate};

let mut eph = Ephemeris::new("config.toml")?;
let jd = JulianDate::from_calendar(2024, 1, 15, 12, 0, 0.0)?;

let sun = eph.get_position("Sun", jd)?;
let earth = eph.get_position("Earth", jd)?;
let mars = eph.get_position("Mars", jd)?;

println!("Sun: ({:.6}, {:.6}, {:.6}) AU", sun.x, sun.y, sun.z);
println!("Distance from origin: {:.6} AU", sun.distance());

---

📊 Ephemeris Metadata

use rust_jpl::Ephemeris;

let mut eph = Ephemeris::new("config.toml")?;
let metadata = eph.get_metadata();

println!("Date Range: {} - {}", metadata.start_year, metadata.end_year);
println!("Julian Range: {} - {}", metadata.julian_start, metadata.julian_end);
println!("Interval: {} days", metadata.interval_days);
println!("Earth–Moon Mass Ratio: {}", metadata.earth_moon_ratio);

for body in eph.get_bodies() {
    println!("{}: {}", body.name, if body.active { "active" } else { "inactive" });
}

---

⚙️ Configuration

Copy the example configuration file:

cp config.toml.example config.toml

Example config.toml

[paths]
nasa_jpl_de441 = "assets/linux_m13000p17000.441.bsp"
header_441 = "assets/header.441"
initial_data_dat = "assets/Initial_data.dat"

---

📥 Ephemeris File Setup

1. Download NASA JPL DE441

• Source: NASA JPL Solar System Dynamics
• Required files:
  • linux_m13000p17000.441
  • header.441

Rename:

linux_m13000p17000.441 → linux_m13000p17000.441.bsp

Place files in the assets/ directory.

---

2. Create Initial_data.dat

BODIES:

Mercury                 true
Venus                   true
EarthMoon_barycenter     true
Mars                    true
Jupiter                 true
Saturn                  true
Uranus                  true
Neptune                 true
Pluto                   true
Moon_geocentric          true
Sun                     true

DATE:

Start_year              1940
End_year                2100

---

🧪 Examples

cargo run --example basic_usage
cargo run --example time_conversion
cargo run --example planetary_positions

---

📚 API Overview

Ephemeris

• new(config_path: &str)
• get_position(body: &str, jd: JulianDate)
• get_bodies()
• get_metadata()
• get_date_range()

JulianDate

• from_calendar(...)
• to_calendar()
• as_f64()

Position

• x, y, z
• distance()

---

🌍 Supported Celestial Bodies

• Mercury
• Venus
• Earth–Moon barycenter
• Mars
• Jupiter
• Saturn
• Uranus
• Neptune
• Pluto
• Moon (geocentric)
• Sun

---

❗ Error Handling

All public APIs return Result<T, Error>.

Error categories include:

• Configuration errors
• I/O failures
• Invalid date ranges
• Ephemeris parsing errors

---

🤝 Contributing

Contributions are welcome and appreciated.

Please read:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• GOVERNANCE.md
• MAINTAINERS.md

---

🔐 Security

For security vulnerabilities, see:

• SECURITY.md

Please do not open public issues for security concerns.

---

📦 Releases

• Semantic Versioning is followed
• Release process is documented in:
  • RELEASE.md

---

📜 License

Licensed under either of:

• MIT License (LICENSE-MIT)

You may choose either license.

---

🙏 Acknowledgments

• NASA Jet Propulsion Laboratory (JPL) for providing DE ephemeris data
• The Rust community for outstanding tooling and libraries