rust-astro-engine 0.1.0__tar.gz

rust_astro_engine-0.1.0/Cargo.lock

@@ -0,0 +1,264 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "astro-models"
+version = "0.1.0"
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "ephemeris-core"
+version = "0.1.0"
+
+[[package]]
+name = "ephemeris-python"
+version = "0.1.0"
+dependencies = [
+ "ephemeris-core",
+ "ephemeris-spk",
+ "ephemeris-time",
+ "numpy",
+ "pyo3",
+]
+
+[[package]]
+name = "ephemeris-spk"
+version = "0.1.0"
+dependencies = [
+ "ephemeris-core",
+ "ephemeris-time",
+ "memmap2",
+]
+
+[[package]]
+name = "ephemeris-time"
+version = "0.1.0"
+dependencies = [
+ "ephemeris-core",
+]
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "libc"
+version = "0.2.189"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
+
+[[package]]
+name = "matrixmultiply"
+version = "0.3.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f607c237553f086e7043417a51df26b2eb899d3caff94e6a67592ff992fedc7"
+dependencies = [
+ "autocfg",
+ "rawpointer",
+]
+
+[[package]]
+name = "memmap2"
+version = "0.9.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d1219ed1b7f229ee7104d281dd01d6802fe28bb6e95d292942c4daacdeb798c0"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "ndarray"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "882ed72dce9365842bf196bdeedf5055305f11fc8c03dee7bb0194a6cad34841"
+dependencies = [
+ "matrixmultiply",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "portable-atomic",
+ "portable-atomic-util",
+ "rawpointer",
+]
+
+[[package]]
+name = "num-complex"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-integer"
+version = "0.1.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7ce2d95d4b3734dc35aa2f45e1aa22cd416814592a4f9d9205e11affd5b8e10b"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "numpy"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a5b15d63a5ff39e378daed0e1340d3a5964703ea9712eb09a0dc66fade996f4"
+dependencies = [
+ "libc",
+ "ndarray",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "pyo3",
+ "pyo3-build-config",
+ "rustc-hash",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "portable-atomic-util"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a106d1259c23fac8e543272398ae0e3c0b8d33c88ed73d0cc71b0f1d902618"
+dependencies = [
+ "portable-atomic",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4688ddedf473e32662b9b067670129a8afb8c18e351482c70d62ba4a88171e8b"
+dependencies = [
+ "libc",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f41027e41b4bd03f6e60f9f417fe24a6341a6bb744edd62b6f709f2a52ea30e9"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e591a95526fead067432c3b3a33fc74770b87b1e04e73671090d9c2055a2b327"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73225868fc1cd84eef2c3c230ddb91273bf1de46aeb8a4248da76d32a0924a1c"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.29.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "571575aa3749fa6216757dd47d2a3e7ef360f329a40f0666a9fbd14889024952"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rawpointer"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60a357793950651c4ed0f3f52338f53b2f809f32d83a07f72909fa13e4c6c1e3"
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"

rust_astro_engine-0.1.0/Cargo.toml

@@ -0,0 +1,18 @@
+[workspace]
+members = ["crates/ephemeris-core", "crates/ephemeris-spk", "crates/ephemeris-time", "crates/ephemeris-python"]
+resolver = "2"
+
+[workspace.package]
+version = "0.1.0"
+edition = "2021"
+license = "MIT OR Apache-2.0"
+rust-version = "1.75"
+
+[workspace.lints.rust]
+# `deny` rather than `forbid` so `ephemeris-spk` can memory-map kernels
+# (`memmap2::Mmap::map` is unsafe). Other crates still `#![forbid(unsafe_code)]`.
+unsafe_code = "deny"
+
+[workspace.lints.clippy]
+all = "warn"
+pedantic = "warn"

rust_astro_engine-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: rust-astro-engine
+Version: 0.1.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: pytest>=7.0 ; extra == 'dev'
+Provides-Extra: dev
+Summary: Python bindings for Rust Astro Engine (thin PyO3 slice)
+License: MIT OR Apache-2.0
+Requires-Python: >=3.9

rust_astro_engine-0.1.0/crates/ephemeris-core/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "ephemeris-core"
+description = "Core types and contracts for Rust Astro Engine"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+rust-version.workspace = true
+
+[lints]
+workspace = true

rust_astro_engine-0.1.0/crates/ephemeris-core/src/events.rs

@@ -0,0 +1,94 @@
+//! Named astronomical events on top of existing spherical positions.
+//!
+//! Horizon kinds label rise, set, and meridian transit. Season and lunation
+//! kinds label ecliptic-longitude targets (Sun at 0°/90°/180°/270°, or
+//! Sun–Moon elongation 0°/180°). Searching those zeros lives with the SPK
+//! backend; this module is the public vocabulary.
+
+/// Rise, set, or apparent meridian transit of the Sun or Moon.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum HorizonEventKind {
+    Rise,
+    Set,
+    Transit,
+}
+
+/// One horizon event, as a UT1 Julian day.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct HorizonEvent {
+    pub kind: HorizonEventKind,
+    pub ut1_julian_day: f64,
+}
+
+/// Equinoxes and solstices: geocentric apparent true ecliptic longitude of
+/// the Sun.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum SeasonEvent {
+    /// Sun longitude 0°.
+    MarchEquinox,
+    /// Sun longitude 90°.
+    JuneSolstice,
+    /// Sun longitude 180°.
+    SeptemberEquinox,
+    /// Sun longitude 270°.
+    DecemberSolstice,
+}
+
+impl SeasonEvent {
+    /// Target apparent ecliptic longitude of the Sun, degrees.
+    #[must_use]
+    pub const fn sun_longitude_deg(self) -> f64 {
+        match self {
+            Self::MarchEquinox => 0.0,
+            Self::JuneSolstice => 90.0,
+            Self::SeptemberEquinox => 180.0,
+            Self::DecemberSolstice => 270.0,
+        }
+    }
+}
+
+/// Lunation phases from apparent geocentric ecliptic elongation.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum LunationEvent {
+    /// Moon − Sun longitude 0°.
+    NewMoon,
+    /// Moon − Sun longitude 180°.
+    FullMoon,
+}
+
+impl LunationEvent {
+    /// Target Moon minus Sun apparent ecliptic elongation, degrees.
+    #[must_use]
+    pub const fn elongation_deg(self) -> f64 {
+        match self {
+            Self::NewMoon => 0.0,
+            Self::FullMoon => 180.0,
+        }
+    }
+}
+
+/// Forward residual in `[0, 360)` from `current_deg` to `target_deg`.
+#[must_use]
+pub fn forward_angle_deg(current_deg: f64, target_deg: f64) -> f64 {
+    (target_deg - current_deg).rem_euclid(360.0)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn season_targets_are_the_four_cardinal_longitudes() {
+        assert!((SeasonEvent::MarchEquinox.sun_longitude_deg() - 0.0).abs() < 1.0e-15);
+        assert!((SeasonEvent::JuneSolstice.sun_longitude_deg() - 90.0).abs() < 1.0e-15);
+        assert!((SeasonEvent::SeptemberEquinox.sun_longitude_deg() - 180.0).abs() < 1.0e-15);
+        assert!((SeasonEvent::DecemberSolstice.sun_longitude_deg() - 270.0).abs() < 1.0e-15);
+    }
+
+    #[test]
+    fn forward_angle_wraps_across_zero() {
+        assert!((forward_angle_deg(350.0, 10.0) - 20.0).abs() < 1.0e-12);
+        assert!((forward_angle_deg(10.0, 10.0)).abs() < 1.0e-12);
+        assert!((forward_angle_deg(0.0, 180.0) - 180.0).abs() < 1.0e-12);
+    }
+}

rust_astro_engine-0.1.0/crates/ephemeris-core/src/horizon.rs

@@ -0,0 +1,227 @@
+//! Rise, set, and meridian transit on the local horizon.
+//!
+//! Hour-angle formulas follow Meeus, *Astronomical Algorithms* (2nd ed.),
+//! Chapter 15. Standard geometric altitudes: mean Sun/Moon upper limb −50′
+//! (refraction 34′ plus mean semi-diameter 16′); stellar/mean-refraction
+//! center −34′.
+
+#![allow(clippy::module_name_repetitions)]
+
+use crate::CoordinateError;
+use std::f64::consts::{PI, TAU};
+
+/// IERS Conventions (2010) Eq. 5.15: one UT1 day plus the ERA linear rate.
+pub const SIDEREAL_TURNS_PER_UT1_DAY: f64 = 1.0 + 0.002_737_811_911_354_48;
+
+/// Mean refraction for a geometric center, degrees (Meeus: −34′).
+pub const MEAN_REFRACTION_ALTITUDE_DEG: f64 = -34.0 / 60.0;
+
+/// Sun upper limb at rise/set, degrees (Meeus: −50′ = −0.8333…).
+pub const SUN_UPPER_LIMB_ALTITUDE_DEG: f64 = -50.0 / 60.0;
+
+/// Mean Moon upper limb at rise/set, degrees (−50′: 34′ refraction plus a
+/// mean 16′ semi-diameter). Precise limb work should use the date-dependent
+/// apparent lunar semi-diameter as the caller-supplied altitude instead.
+pub const MOON_MEAN_UPPER_LIMB_ALTITUDE_DEG: f64 = -50.0 / 60.0;
+
+/// UT1 epochs of meridian transit and, when they exist, rise and set.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct RiseSetTransit {
+    pub transit_ut1_julian_day: f64,
+    pub rise_ut1_julian_day: Option<f64>,
+    pub set_ut1_julian_day: Option<f64>,
+}
+
+/// Whether a body crosses a chosen geometric altitude.
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum RiseSetHourAngle {
+    /// Hour angle at setting, radians in `(0, π)`. Rise is at `−hour_angle_rad`.
+    Crosses { hour_angle_rad: f64 },
+    /// Always above the chosen altitude (circumpolar).
+    AlwaysAbove,
+    /// Always below the chosen altitude.
+    AlwaysBelow,
+}
+
+/// Converts apparent equatorial coordinates to local azimuth (degrees from
+/// north toward east, `[0, 360)`) and altitude (degrees).
+///
+/// `local_sidereal_time_rad` is LAST; `right_ascension_rad` is apparent RA.
+///
+/// # Errors
+///
+/// Returns [`CoordinateError::NonFiniteState`] when an input is not finite.
+pub fn equatorial_to_horizontal(
+    latitude_rad: f64,
+    local_sidereal_time_rad: f64,
+    right_ascension_rad: f64,
+    declination_rad: f64,
+) -> Result<(f64, f64), CoordinateError> {
+    if ![
+        latitude_rad,
+        local_sidereal_time_rad,
+        right_ascension_rad,
+        declination_rad,
+    ]
+    .into_iter()
+    .all(f64::is_finite)
+    {
+        return Err(CoordinateError::NonFiniteState);
+    }
+    let hour_angle = local_sidereal_time_rad - right_ascension_rad;
+    let (sin_phi, cos_phi) = latitude_rad.sin_cos();
+    let (sin_dec, cos_dec) = declination_rad.sin_cos();
+    let (sin_ha, cos_ha) = hour_angle.sin_cos();
+    let sin_alt = sin_phi.mul_add(sin_dec, cos_phi * cos_dec * cos_ha);
+    let altitude_rad = sin_alt.clamp(-1.0, 1.0).asin();
+    let y_east = -cos_dec * sin_ha;
+    let x_north = cos_phi.mul_add(sin_dec, -sin_phi * cos_dec * cos_ha);
+    let azimuth_deg = y_east.atan2(x_north).to_degrees().rem_euclid(360.0);
+    Ok((azimuth_deg, altitude_rad.to_degrees()))
+}
+
+/// Hour angle at which a body at declination `declination_rad` crosses
+/// geometric altitude `altitude_rad` for an observer at `latitude_rad`.
+///
+/// Meeus (15.1): `cos H0 = (sin h0 − sin φ sin δ) / (cos φ cos δ)`.
+///
+/// # Errors
+///
+/// Returns [`CoordinateError::NonFiniteState`] when an input is not finite.
+pub fn rise_set_hour_angle(
+    latitude_rad: f64,
+    declination_rad: f64,
+    altitude_rad: f64,
+) -> Result<RiseSetHourAngle, CoordinateError> {
+    if ![latitude_rad, declination_rad, altitude_rad]
+        .into_iter()
+        .all(f64::is_finite)
+    {
+        return Err(CoordinateError::NonFiniteState);
+    }
+    let (sin_phi, cos_phi) = latitude_rad.sin_cos();
+    let (sin_dec, cos_dec) = declination_rad.sin_cos();
+    let denominator = cos_phi * cos_dec;
+    if denominator.abs() < 1.0e-18 {
+        let sin_alt = sin_phi * sin_dec;
+        return Ok(if sin_alt >= altitude_rad.sin() {
+            RiseSetHourAngle::AlwaysAbove
+        } else {
+            RiseSetHourAngle::AlwaysBelow
+        });
+    }
+    let cos_h0 = (altitude_rad.sin() - sin_phi * sin_dec) / denominator;
+    if cos_h0 > 1.0 {
+        Ok(RiseSetHourAngle::AlwaysBelow)
+    } else if cos_h0 < -1.0 {
+        Ok(RiseSetHourAngle::AlwaysAbove)
+    } else {
+        Ok(RiseSetHourAngle::Crosses {
+            hour_angle_rad: cos_h0.acos(),
+        })
+    }
+}
+
+/// UT1-day offset that advances local sidereal time by `delta_sidereal_rad`.
+#[must_use]
+pub fn ut1_days_from_sidereal_radians(delta_sidereal_rad: f64) -> f64 {
+    delta_sidereal_rad / (TAU * SIDEREAL_TURNS_PER_UT1_DAY)
+}
+
+/// Wraps an angle to `(-π, π]`.
+#[must_use]
+pub fn wrap_pi(radians: f64) -> f64 {
+    let wrapped = (radians + PI).rem_euclid(TAU) - PI;
+    if wrapped <= -PI {
+        PI
+    } else {
+        wrapped
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn assert_close(actual: f64, expected: f64, tolerance: f64) {
+        assert!(
+            (actual - expected).abs() < tolerance,
+            "actual={actual} expected={expected} tolerance={tolerance}"
+        );
+    }
+
+    #[test]
+    fn equator_zero_declination_sets_six_hours_from_transit() {
+        let hour = rise_set_hour_angle(0.0, 0.0, 0.0).expect("finite");
+        match hour {
+            RiseSetHourAngle::Crosses { hour_angle_rad } => {
+                assert_close(hour_angle_rad, PI / 2.0, 1.0e-14);
+            }
+            other => panic!("expected a crossing, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn sun_upper_limb_lengthens_the_day_versus_the_geometric_center() {
+        let latitude = 51.477_8_f64.to_radians();
+        let declination = 0.0;
+        let geometric = rise_set_hour_angle(latitude, declination, 0.0).expect("finite");
+        let limb = rise_set_hour_angle(
+            latitude,
+            declination,
+            SUN_UPPER_LIMB_ALTITUDE_DEG.to_radians(),
+        )
+        .expect("finite");
+        let RiseSetHourAngle::Crosses {
+            hour_angle_rad: h_geo,
+        } = geometric
+        else {
+            panic!("geometric should cross");
+        };
+        let RiseSetHourAngle::Crosses {
+            hour_angle_rad: h_limb,
+        } = limb
+        else {
+            panic!("limb should cross");
+        };
+        assert!(h_limb > h_geo);
+    }
+
+    #[test]
+    fn high_declination_is_circumpolar_or_never_rises() {
+        let latitude = 80.0_f64.to_radians();
+        assert_eq!(
+            rise_set_hour_angle(latitude, 30.0_f64.to_radians(), 0.0).expect("finite"),
+            RiseSetHourAngle::AlwaysAbove
+        );
+        assert_eq!(
+            rise_set_hour_angle(latitude, -30.0_f64.to_radians(), 0.0).expect("finite"),
+            RiseSetHourAngle::AlwaysBelow
+        );
+    }
+
+    #[test]
+    fn equatorial_to_horizontal_puts_ramc_on_the_meridian() {
+        let latitude = 51.477_8_f64.to_radians();
+        let last = 1.2;
+        let (azimuth, altitude) =
+            equatorial_to_horizontal(latitude, last, last, 0.0).expect("finite");
+        assert_close(azimuth, 180.0, 1.0e-8);
+        let expected_alt = (latitude.cos()).asin().to_degrees();
+        assert_close(altitude, expected_alt, 1.0e-10);
+    }
+
+    #[test]
+    fn ut1_offset_inverts_the_iers_era_rate() {
+        let one_turn = ut1_days_from_sidereal_radians(TAU);
+        assert_close(one_turn * SIDEREAL_TURNS_PER_UT1_DAY, 1.0, 1.0e-15);
+    }
+
+    #[test]
+    fn rejects_non_finite_inputs() {
+        assert_eq!(
+            rise_set_hour_angle(f64::NAN, 0.0, 0.0),
+            Err(CoordinateError::NonFiniteState)
+        );
+    }
+}