siderust 0.7.0

High-precision astronomy and satellite mechanics in Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

// SPDX-License-Identifier: AGPL-3.0-or-later
// Copyright (C) 2026 Vallés Puig, Ramon

//! # Satellites
//!
//! ## Scientific scope
//!
//! Natural satellites (moons) orbit planets or dwarf planets under
//! gravitational attraction. Their orbits are often non-Keplerian due to
//! oblateness of the primary and mutual perturbations, but for many
//! practical purposes a mean Keplerian element set gives adequate
//! first-order positions. The Bond albedo characterises the overall
//! reflectivity of the body's surface integrated over all wavelengths and
//! phase angles.
//!
//! This module does **not** model artificial satellites; TLE-based SGP4
//! propagation is outside scope here.
//!
//! ## Technical scope
//!
//! - [`Satellite`] — data structure for name, mass ([`Kilograms`]),
//!   mean radius ([`Kilometers`]), Keplerian orbit ([`KeplerianOrbit`]),
//!   and optional Bond albedo ([`Albedos`]).
//! - [`Satellite::new_const`] — `const`-safe constructor.
//! - [`Satellite::with_albedo`] — `const`-safe albedo builder.
//! - [`Satellite::new`] — runtime constructor accepting any string-like name.
//!
//! Pre-built satellite constants (Moon, Io, Europa, Ganymede, Callisto,
//! Titan, Triton) are defined in [`crate::bodies::solar_system`].
//!
//! ## References
//!
//! - Seidelmann, P. K. (Ed.) (1992). *Explanatory Supplement to the
//!   Astronomical Almanac*. University Science Books. Chapter 15.
//! - IAU Working Group on Cartographic Coordinates and Rotational Elements
//!   (2015). *Celestial Mechanics and Dynamical Astronomy* 130, 22.
//!   doi:10.1007/s10569-017-9805-5

use crate::astro::orbit::KeplerianOrbit;
use crate::qtty::{Albedos, Kilograms, Kilometers};

use std::borrow::Cow;

/// Represents a **Satellite** characterized by its mass, radius, optional
/// Bond albedo, and Keplerian orbit.
#[derive(Clone, Debug)]
pub struct Satellite<'a> {
    pub name: Cow<'a, str>,
    pub mass: Kilograms,
    pub radius: Kilometers,
    pub orbit: KeplerianOrbit,
    /// Bond albedo (dimensionless, ∈ [0, 1]).  `None` when not catalogued.
    pub albedo: Option<Albedos>,
}

impl<'a> Satellite<'a> {
    /// Compile-time constructor (only works with `'static` string literals).
    ///
    /// `albedo` defaults to `None`; use [`Satellite::with_albedo`] to
    /// attach a known Bond albedo value.
    pub const fn new_const(
        name: &'static str,
        mass: Kilograms,
        radius: Kilometers,
        orbit: KeplerianOrbit,
    ) -> Satellite<'static> {
        Satellite {
            name: Cow::Borrowed(name),
            mass,
            radius,
            orbit,
            albedo: None,
        }
    }

    /// Attach a typed Bond albedo (`const`-safe builder).
    ///
    /// # Arguments
    ///
    /// - `albedo` — Bond albedo as [`Albedos`] (`Quantity<Albedo>`), ∈ [0, 1].
    pub const fn with_albedo(mut self, albedo: Albedos) -> Self {
        self.albedo = Some(albedo);
        self
    }

    /// Runtime constructor: accepts any string-like thing.
    pub fn new<N>(
        name: N,
        mass: Kilograms,
        radius: Kilometers,
        orbit: KeplerianOrbit,
    ) -> Satellite<'a>
    where
        N: Into<Cow<'a, str>>,
    {
        Satellite {
            name: name.into(),
            mass,
            radius,
            orbit,
            albedo: None,
        }
    }
}