Almanac

Struct Almanac 

pub struct Almanac {
    pub spk_data: [Option<GenericDAF<SPKSummaryRecord, Bytes>>; 32],
    pub bpc_data: [Option<GenericDAF<BPCSummaryRecord, Bytes>>; 8],
    pub planetary_data: DataSet<PlanetaryData, anise::::structure::PlanetaryDataSet::{constant#0}>,
    pub spacecraft_data: DataSet<SpacecraftData, anise::::structure::SpacecraftDataSet::{constant#0}>,
    pub euler_param_data: DataSet<EulerParameter, anise::::structure::EulerParameterDataSet::{constant#0}>,
}
Expand description

An Almanac contains all of the loaded SPICE and ANISE data. It is the context for all computations.

:type path: str :rtype: Almanac

Fields§

§spk_data: [Option<GenericDAF<SPKSummaryRecord, Bytes>>; 32]

NAIF SPK is kept unchanged

§bpc_data: [Option<GenericDAF<BPCSummaryRecord, Bytes>>; 8]

NAIF BPC is kept unchanged

§planetary_data: DataSet<PlanetaryData, anise::::structure::PlanetaryDataSet::{constant#0}>

Dataset of planetary data

§spacecraft_data: DataSet<SpacecraftData, anise::::structure::SpacecraftDataSet::{constant#0}>

Dataset of spacecraft data

§euler_param_data: DataSet<EulerParameter, anise::::structure::EulerParameterDataSet::{constant#0}>

Dataset of euler parameters

Implementations§

§

impl Almanac

pub fn azimuth_elevation_range_sez( &self, rx: CartesianState, tx: CartesianState, obstructing_body: Option<Frame>, ab_corr: Option<Aberration>, ) -> Result<AzElRange, AlmanacError>

Computes the azimuth (in degrees), elevation (in degrees), and range (in kilometers) of the receiver state (rx) seen from the transmitter state (tx), once converted into the SEZ frame of the transmitter.

§Warning

The obstructing body should be a tri-axial ellipsoid body, e.g. IAU_MOON_FRAME.

§Algorithm
  1. If any obstructing_bodies are provided, ensure that none of these are obstructing the line of sight between the receiver and transmitter.
  2. Compute the SEZ (South East Zenith) frame of the transmitter.
  3. Rotate the receiver position vector into the transmitter SEZ frame.
  4. Rotate the transmitter position vector into that same SEZ frame.
  5. Compute the range as the norm of the difference between these two position vectors.
  6. Compute the elevation, and ensure it is between +/- 180 degrees.
  7. Compute the azimuth with a quadrant check, and ensure it is between 0 and 360 degrees.
Examples found in repository?
examples/01_orbit_prop/main.rs (lines 240-245)
30fn main() -> Result<(), Box<dyn Error>> {
31    pel::init();
32    // Dynamics models require planetary constants and ephemerides to be defined.
33    // Let's start by grabbing those by using ANISE's latest MetaAlmanac.
34    // This will automatically download the DE440s planetary ephemeris,
35    // the daily-updated Earth Orientation Parameters, the high fidelity Moon orientation
36    // parameters (for the Moon Mean Earth and Moon Principal Axes frames), and the PCK11
37    // planetary constants kernels.
38    // For details, refer to https://github.com/nyx-space/anise/blob/master/data/latest.dhall.
39    // Note that we place the Almanac into an Arc so we can clone it cheaply and provide read-only
40    // references to many functions.
41    let almanac = Arc::new(MetaAlmanac::latest().map_err(Box::new)?);
42    // Define the orbit epoch
43    let epoch = Epoch::from_gregorian_utc_hms(2024, 2, 29, 12, 13, 14);
44
45    // Define the orbit.
46    // First we need to fetch the Earth J2000 from information from the Almanac.
47    // This allows the frame to include the gravitational parameters and the shape of the Earth,
48    // defined as a tri-axial ellipoid. Note that this shape can be changed manually or in the Almanac
49    // by loading a different set of planetary constants.
50    let earth_j2000 = almanac.frame_from_uid(EARTH_J2000)?;
51
52    let orbit =
53        Orbit::try_keplerian_altitude(300.0, 0.015, 68.5, 65.2, 75.0, 0.0, epoch, earth_j2000)?;
54    // Print in in Keplerian form.
55    println!("{orbit:x}");
56
57    // There are two ways to propagate an orbit. We can make a quick approximation assuming only two-body
58    // motion. This is a useful first order approximation but it isn't used in real-world applications.
59
60    // This approach is a feature of ANISE.
61    let future_orbit_tb = orbit.at_epoch(epoch + Unit::Day * 3)?;
62    println!("{future_orbit_tb:x}");
63
64    // Two body propagation relies solely on Kepler's laws, so only the true anomaly will change.
65    println!(
66        "SMA changed by {:.3e} km",
67        orbit.sma_km()? - future_orbit_tb.sma_km()?
68    );
69    println!(
70        "ECC changed by {:.3e}",
71        orbit.ecc()? - future_orbit_tb.ecc()?
72    );
73    println!(
74        "INC changed by {:.3e} deg",
75        orbit.inc_deg()? - future_orbit_tb.inc_deg()?
76    );
77    println!(
78        "RAAN changed by {:.3e} deg",
79        orbit.raan_deg()? - future_orbit_tb.raan_deg()?
80    );
81    println!(
82        "AOP changed by {:.3e} deg",
83        orbit.aop_deg()? - future_orbit_tb.aop_deg()?
84    );
85    println!(
86        "TA changed by {:.3} deg",
87        orbit.ta_deg()? - future_orbit_tb.ta_deg()?
88    );
89
90    // Nyx is used for high fidelity propagation, not Keplerian propagation as above.
91    // Nyx only propagates Spacecraft at the moment, which allows it to account for acceleration
92    // models such as solar radiation pressure.
93
94    // Let's build a cubesat sized spacecraft, with an SRP area of 10 cm^2 and a mass of 9.6 kg.
95    let sc = Spacecraft::builder()
96        .orbit(orbit)
97        .mass(Mass::from_dry_mass(9.60))
98        .srp(SRPData {
99            area_m2: 10e-4,
100            coeff_reflectivity: 1.1,
101        })
102        .build();
103    println!("{sc:x}");
104
105    // Set up the spacecraft dynamics.
106
107    // Specify that the orbital dynamics must account for the graviational pull of the Moon and the Sun.
108    // The gravity of the Earth will also be accounted for since the spaceraft in an Earth orbit.
109    let mut orbital_dyn = OrbitalDynamics::point_masses(vec![MOON, SUN]);
110
111    // We want to include the spherical harmonics, so let's download the gravitational data from the Nyx Cloud.
112    // We're using the JGM3 model here, which is the default in GMAT.
113    let mut jgm3_meta = MetaFile {
114        uri: "http://public-data.nyxspace.com/nyx/models/JGM3.cof.gz".to_string(),
115        crc32: Some(0xF446F027), // Specifying the CRC32 avoids redownloading it if it's cached.
116    };
117    // And let's download it if we don't have it yet.
118    jgm3_meta.process(true)?;
119
120    // Build the spherical harmonics.
121    // The harmonics must be computed in the body fixed frame.
122    // We're using the long term prediction of the Earth centered Earth fixed frame, IAU Earth.
123    let harmonics_21x21 = Harmonics::from_stor(
124        almanac.frame_from_uid(IAU_EARTH_FRAME)?,
125        HarmonicsMem::from_cof(&jgm3_meta.uri, 21, 21, true).unwrap(),
126    );
127
128    // Include the spherical harmonics into the orbital dynamics.
129    orbital_dyn.accel_models.push(harmonics_21x21);
130
131    // We define the solar radiation pressure, using the default solar flux and accounting only
132    // for the eclipsing caused by the Earth.
133    let srp_dyn = SolarPressure::default(EARTH_J2000, almanac.clone())?;
134
135    // Finalize setting up the dynamics, specifying the force models (orbital_dyn) separately from the
136    // acceleration models (SRP in this case). Use `from_models` to specify multiple accel models.
137    let dynamics = SpacecraftDynamics::from_model(orbital_dyn, srp_dyn);
138
139    println!("{dynamics}");
140
141    // Finally, let's propagate this orbit to the same epoch as above.
142    // The first returned value is the spacecraft state at the final epoch.
143    // The second value is the full trajectory where the step size is variable step used by the propagator.
144    let (future_sc, trajectory) = Propagator::default(dynamics)
145        .with(sc, almanac.clone())
146        .until_epoch_with_traj(future_orbit_tb.epoch)?;
147
148    println!("=== High fidelity propagation ===");
149    println!(
150        "SMA changed by {:.3} km",
151        orbit.sma_km()? - future_sc.orbit.sma_km()?
152    );
153    println!(
154        "ECC changed by {:.6}",
155        orbit.ecc()? - future_sc.orbit.ecc()?
156    );
157    println!(
158        "INC changed by {:.3e} deg",
159        orbit.inc_deg()? - future_sc.orbit.inc_deg()?
160    );
161    println!(
162        "RAAN changed by {:.3} deg",
163        orbit.raan_deg()? - future_sc.orbit.raan_deg()?
164    );
165    println!(
166        "AOP changed by {:.3} deg",
167        orbit.aop_deg()? - future_sc.orbit.aop_deg()?
168    );
169    println!(
170        "TA changed by {:.3} deg",
171        orbit.ta_deg()? - future_sc.orbit.ta_deg()?
172    );
173
174    // We also have access to the full trajectory throughout the propagation.
175    println!("{trajectory}");
176
177    // With the trajectory, let's build a few data products.
178
179    // 1. Export the trajectory as a CCSDS OEM version 2.0 file and as a parquet file, which includes the Keplerian orbital elements.
180
181    trajectory.to_oem_file(
182        "./01_cubesat_hf_prop.oem",
183        ExportCfg::builder().step(Unit::Minute * 2).build(),
184    )?;
185
186    trajectory.to_parquet_with_cfg(
187        "./01_cubesat_hf_prop.parquet",
188        ExportCfg::builder().step(Unit::Minute * 2).build(),
189        almanac.clone(),
190    )?;
191
192    // 2. Compare the difference in the radial-intrack-crosstrack frame between the high fidelity
193    // and Keplerian propagation. The RIC frame is commonly used to compute the difference in position
194    // and velocity of different spacecraft.
195    // 3. Compute the azimuth, elevation, range, and range-rate data of that spacecraft as seen from Boulder, CO, USA.
196
197    let boulder_station = GroundStation::from_point(
198        "Boulder, CO, USA".to_string(),
199        40.014984,   // latitude in degrees
200        -105.270546, // longitude in degrees
201        1.6550,      // altitude in kilometers
202        almanac.frame_from_uid(IAU_EARTH_FRAME)?,
203    );
204
205    // We iterate over the trajectory, grabbing a state every two minutes.
206    let mut offset_s = vec![];
207    let mut epoch_str = vec![];
208    let mut ric_x_km = vec![];
209    let mut ric_y_km = vec![];
210    let mut ric_z_km = vec![];
211    let mut ric_vx_km_s = vec![];
212    let mut ric_vy_km_s = vec![];
213    let mut ric_vz_km_s = vec![];
214
215    let mut azimuth_deg = vec![];
216    let mut elevation_deg = vec![];
217    let mut range_km = vec![];
218    let mut range_rate_km_s = vec![];
219    for state in trajectory.every(Unit::Minute * 2) {
220        // Try to compute the Keplerian/two body state just in time.
221        // This method occasionally fails to converge on an appropriate true anomaly
222        // from the mean anomaly. If that happens, we just skip this state.
223        // The high fidelity and Keplerian states diverge continuously, and we're curious
224        // about the divergence in this quick analysis.
225        let this_epoch = state.epoch();
226        match orbit.at_epoch(this_epoch) {
227            Ok(tb_then) => {
228                offset_s.push((this_epoch - orbit.epoch).to_seconds());
229                epoch_str.push(format!("{this_epoch}"));
230                // Compute the two body state just in time.
231                let ric = state.orbit.ric_difference(&tb_then)?;
232                ric_x_km.push(ric.radius_km.x);
233                ric_y_km.push(ric.radius_km.y);
234                ric_z_km.push(ric.radius_km.z);
235                ric_vx_km_s.push(ric.velocity_km_s.x);
236                ric_vy_km_s.push(ric.velocity_km_s.y);
237                ric_vz_km_s.push(ric.velocity_km_s.z);
238
239                // Compute the AER data for each state.
240                let aer = almanac.azimuth_elevation_range_sez(
241                    state.orbit,
242                    boulder_station.to_orbit(this_epoch, &almanac)?,
243                    None,
244                    None,
245                )?;
246                azimuth_deg.push(aer.azimuth_deg);
247                elevation_deg.push(aer.elevation_deg);
248                range_km.push(aer.range_km);
249                range_rate_km_s.push(aer.range_rate_km_s);
250            }
251            Err(e) => warn!("{} {e}", state.epoch()),
252        };
253    }
254
255    // Build the data frames.
256    let ric_df = df!(
257        "Offset (s)" => offset_s.clone(),
258        "Epoch" => epoch_str.clone(),
259        "RIC X (km)" => ric_x_km,
260        "RIC Y (km)" => ric_y_km,
261        "RIC Z (km)" => ric_z_km,
262        "RIC VX (km/s)" => ric_vx_km_s,
263        "RIC VY (km/s)" => ric_vy_km_s,
264        "RIC VZ (km/s)" => ric_vz_km_s,
265    )?;
266
267    println!("RIC difference at start\n{}", ric_df.head(Some(10)));
268    println!("RIC difference at end\n{}", ric_df.tail(Some(10)));
269
270    let aer_df = df!(
271        "Offset (s)" => offset_s.clone(),
272        "Epoch" => epoch_str.clone(),
273        "azimuth (deg)" => azimuth_deg,
274        "elevation (deg)" => elevation_deg,
275        "range (km)" => range_km,
276        "range rate (km/s)" => range_rate_km_s,
277    )?;
278
279    // Finally, let's see when the spacecraft is visible, assuming 15 degrees minimum elevation.
280    let mask = aer_df
281        .column("elevation (deg)")?
282        .gt(&Column::Scalar(ScalarColumn::new(
283            "elevation mask (deg)".into(),
284            Scalar::new(DataType::Float64, AnyValue::Float64(15.0)),
285            offset_s.len(),
286        )))?;
287    let cubesat_visible = aer_df.filter(&mask)?;
288
289    println!("{cubesat_visible}");
290
291    Ok(())
292}
§

impl Almanac

pub fn from_bpc( bpc: GenericDAF<BPCSummaryRecord, Bytes>, ) -> Result<Almanac, OrientationError>

pub fn with_bpc( &self, bpc: GenericDAF<BPCSummaryRecord, Bytes>, ) -> Result<Almanac, OrientationError>

Loads a Binary Planetary Constants kernel.

pub fn num_loaded_bpc(&self) -> usize

pub fn bpc_summary_from_name_at_epoch( &self, name: &str, epoch: Epoch, ) -> Result<(&BPCSummaryRecord, usize, usize), OrientationError>

Returns the summary given the name of the summary record if that summary has data defined at the requested epoch and the BPC where this name was found to be valid at that epoch.

pub fn bpc_summary_at_epoch( &self, id: i32, epoch: Epoch, ) -> Result<(&BPCSummaryRecord, usize, usize), OrientationError>

Returns the summary given the name of the summary record if that summary has data defined at the requested epoch

pub fn bpc_summary_from_name( &self, name: &str, ) -> Result<(&BPCSummaryRecord, usize, usize), OrientationError>

Returns the summary given the name of the summary record.

pub fn bpc_summary( &self, id: i32, ) -> Result<(&BPCSummaryRecord, usize, usize), OrientationError>

Returns the summary given the name of the summary record if that summary has data defined at the requested epoch

§

impl Almanac

pub fn bpc_summaries( &self, id: i32, ) -> Result<Vec<BPCSummaryRecord>, OrientationError>

Returns a vector of the summaries whose ID matches the desired id, in the order in which they will be used, i.e. in reverse loading order.

§Warning

This function performs a memory allocation.

:type id: int :rtype: typing.List

pub fn bpc_domain(&self, id: i32) -> Result<(Epoch, Epoch), OrientationError>

Returns the applicable domain of the request id, i.e. start and end epoch that the provided id has loaded data.

:type id: int :rtype: typing.Tuple

pub fn bpc_domains( &self, ) -> Result<HashMap<i32, (Epoch, Epoch)>, OrientationError>

Returns a map of each loaded BPC ID to its domain validity.

§Warning

This function performs a memory allocation.

:rtype: typing.Dict

§

impl Almanac

pub fn line_of_sight_obstructed( &self, observer: CartesianState, observed: CartesianState, obstructing_body: Frame, ab_corr: Option<Aberration>, ) -> Result<bool, AlmanacError>

Computes whether the line of sight between an observer and an observed Cartesian state is obstructed by the obstructing body. Returns true if the obstructing body is in the way, false otherwise.

For example, if the Moon is in between a Lunar orbiter (observed) and a ground station (observer), then this function returns true because the Moon (obstructing body) is indeed obstructing the line of sight.

Observed
  o  -
   +    -
    +      -
     + ***   -
    * +    *   -
    *  + + * + + o
    *     *     Observer
      ****

Key Elements:

  • o represents the positions of the observer and observed objects.
  • The dashed line connecting the observer and observed is the line of sight.

Algorithm (source: Algorithm 35 of Vallado, 4th edition, page 308.):

  • r1 and r2 are the transformed radii of the observed and observer objects, respectively.
  • r1sq and r2sq are the squared magnitudes of these vectors.
  • r1dotr2 is the dot product of r1 and r2.
  • tau is a parameter that determines the intersection point along the line of sight.
  • The condition (1.0 - tau) * r1sq + r1dotr2 * tau <= ob_mean_eq_radius_km^2 checks if the line of sight is within the obstructing body’s radius, indicating an obstruction.

pub fn occultation( &self, back_frame: Frame, front_frame: Frame, observer: CartesianState, ab_corr: Option<Aberration>, ) -> Result<Occultation, AlmanacError>

Computes the occultation percentage of the back_frame object by the front_frame object as seen from the observer, when according for the provided aberration correction.

A zero percent occultation means that the back object is fully visible from the observer. A 100% percent occultation means that the back object is fully hidden from the observer because of the front frame (i.e. umbra if the back object is the Sun). A value in between means that the back object is partially hidden from the observser (i.e. penumbra if the back object is the Sun). Refer to the MathSpec for modeling details.

pub fn solar_eclipsing( &self, eclipsing_frame: Frame, observer: CartesianState, ab_corr: Option<Aberration>, ) -> Result<Occultation, AlmanacError>

Computes the solar eclipsing of the observer due to the eclipsing_frame.

This function calls occultation where the back object is the Sun in the J2000 frame, and the front object is the provided eclipsing frame.

:type eclipsing_frame: Frame :type observer: Orbit :type ab_corr: Aberration, optional :rtype: Occultation

pub fn beta_angle_deg( &self, state: CartesianState, ab_corr: Option<Aberration>, ) -> Result<f64, AlmanacError>

Computes the Beta angle (β) for a given orbital state, in degrees. A Beta angle of 0° indicates that the orbit plane is edge-on to the Sun, leading to maximum eclipse time. Conversely, a Beta angle of +90° or -90° means the orbit plane is face-on to the Sun, resulting in continuous sunlight exposure and no eclipses.

The Beta angle (β) is defined as the angle between the orbit plane of a spacecraft and the vector from the central body (e.g., Earth) to the Sun. In simpler terms, it measures how much of the time a satellite in orbit is exposed to direct sunlight. The mathematical formula for the Beta angle is: β=arcsin(h⋅usun​) Where:

  • h is the unit vector of the orbital momentum.
  • usun​ is the unit vector pointing from the central body to the Sun.

Original code from GMAT, https://github.com/ChristopherRabotin/GMAT/blob/GMAT-R2022a/src/gmatutil/util/CalculationUtilities.cpp#L209-L219

§

impl Almanac

pub fn frame_from_uid<U>(&self, uid: U) -> Result<Frame, PlanetaryDataError>
where U: Into<FrameUid>,

Given the frame UID (or something that can be transformed into it), attempt to retrieve the full frame information, if that frame is loaded

Examples found in repository?
examples/03_geo_analysis/stationkeeping.rs (line 35)
28fn main() -> Result<(), Box<dyn Error>> {
29    pel::init();
30    // Set up the dynamics like in the orbit raise.
31    let almanac = Arc::new(MetaAlmanac::latest().map_err(Box::new)?);
32    let epoch = Epoch::from_gregorian_utc_hms(2024, 2, 29, 12, 13, 14);
33
34    // Define the GEO orbit, and we're just going to maintain it very tightly.
35    let earth_j2000 = almanac.frame_from_uid(EARTH_J2000)?;
36    let orbit = Orbit::try_keplerian(42164.0, 1e-5, 0., 163.0, 75.0, 0.0, epoch, earth_j2000)?;
37    println!("{orbit:x}");
38
39    let sc = Spacecraft::builder()
40        .orbit(orbit)
41        .mass(Mass::from_dry_and_prop_masses(1000.0, 1000.0)) // 1000 kg of dry mass and prop, totalling 2.0 tons
42        .srp(SRPData::from_area(3.0 * 6.0)) // Assuming 1 kW/m^2 or 18 kW, giving a margin of 4.35 kW for on-propulsion consumption
43        .thruster(Thruster {
44            // "NEXT-STEP" row in Table 2
45            isp_s: 4435.0,
46            thrust_N: 0.472,
47        })
48        .mode(GuidanceMode::Thrust) // Start thrusting immediately.
49        .build();
50
51    // Set up the spacecraft dynamics like in the orbit raise example.
52
53    let prop_time = 30.0 * Unit::Day;
54
55    // Define the guidance law -- we're just using a Ruggiero controller as demonstrated in AAS-2004-5089.
56    let objectives = &[
57        Objective::within_tolerance(StateParameter::SMA, 42_164.0, 5.0), // 5 km
58        Objective::within_tolerance(StateParameter::Eccentricity, 0.001, 5e-5),
59        Objective::within_tolerance(StateParameter::Inclination, 0.05, 1e-2),
60    ];
61
62    let ruggiero_ctrl = Ruggiero::from_max_eclipse(objectives, sc, 0.2)?;
63    println!("{ruggiero_ctrl}");
64
65    let mut orbital_dyn = OrbitalDynamics::point_masses(vec![MOON, SUN]);
66
67    let mut jgm3_meta = MetaFile {
68        uri: "http://public-data.nyxspace.com/nyx/models/JGM3.cof.gz".to_string(),
69        crc32: Some(0xF446F027), // Specifying the CRC32 avoids redownloading it if it's cached.
70    };
71    jgm3_meta.process(true)?;
72
73    let harmonics = Harmonics::from_stor(
74        almanac.frame_from_uid(IAU_EARTH_FRAME)?,
75        HarmonicsMem::from_cof(&jgm3_meta.uri, 8, 8, true)?,
76    );
77    orbital_dyn.accel_models.push(harmonics);
78
79    let srp_dyn = SolarPressure::default(EARTH_J2000, almanac.clone())?;
80    let sc_dynamics = SpacecraftDynamics::from_model(orbital_dyn, srp_dyn)
81        .with_guidance_law(ruggiero_ctrl.clone());
82
83    println!("{sc_dynamics}");
84
85    // Finally, let's use the Monte Carlo framework built into Nyx to propagate spacecraft.
86
87    // Let's start by defining the dispersion.
88    // The MultivariateNormal structure allows us to define the dispersions in any of the orbital parameters, but these are applied directly in the Cartesian state space.
89    // Note that additional validation on the MVN is in progress -- https://github.com/nyx-space/nyx/issues/339.
90    let mc_rv = MvnSpacecraft::new(
91        sc,
92        vec![StateDispersion::zero_mean(StateParameter::SMA, 3.0)],
93    )?;
94
95    let my_mc = MonteCarlo::new(
96        sc, // Nominal state
97        mc_rv,
98        "03_geo_sk".to_string(), // Scenario name
99        None, // No specific seed specified, so one will be drawn from the computer's entropy.
100    );
101
102    // Build the propagator setup.
103    let setup = Propagator::rk89(
104        sc_dynamics.clone(),
105        IntegratorOptions::builder()
106            .min_step(10.0_f64.seconds())
107            .error_ctrl(ErrorControl::RSSCartesianStep)
108            .build(),
109    );
110
111    let num_runs = 25;
112    let rslts = my_mc.run_until_epoch(setup, almanac.clone(), sc.epoch() + prop_time, num_runs);
113
114    assert_eq!(rslts.runs.len(), num_runs);
115
116    // For all of the resulting trajectories, we'll want to compute the percentage of penumbra and umbra.
117
118    rslts.to_parquet(
119        "03_geo_sk.parquet",
120        Some(vec![
121            &EclipseLocator::cislunar(almanac.clone()).to_penumbra_event()
122        ]),
123        ExportCfg::default(),
124        almanac,
125    )?;
126
127    Ok(())
128}
More examples
Hide additional examples
examples/03_geo_analysis/raise.rs (line 41)
27fn main() -> Result<(), Box<dyn Error>> {
28    pel::init();
29
30    // Dynamics models require planetary constants and ephemerides to be defined.
31    // Let's start by grabbing those by using ANISE's latest MetaAlmanac.
32    // This will automatically download the DE440s planetary ephemeris,
33    // the daily-updated Earth Orientation Parameters, the high fidelity Moon orientation
34    // parameters (for the Moon Mean Earth and Moon Principal Axes frames), and the PCK11
35    // planetary constants kernels.
36    // For details, refer to https://github.com/nyx-space/anise/blob/master/data/latest.dhall.
37    // Note that we place the Almanac into an Arc so we can clone it cheaply and provide read-only
38    // references to many functions.
39    let almanac = Arc::new(MetaAlmanac::latest().map_err(Box::new)?);
40    // Fetch the EME2000 frame from the Almabac
41    let eme2k = almanac.frame_from_uid(EARTH_J2000).unwrap();
42    // Define the orbit epoch
43    let epoch = Epoch::from_gregorian_utc_hms(2024, 2, 29, 12, 13, 14);
44
45    // Build the spacecraft itself.
46    // Using slide 6 of https://aerospace.org/sites/default/files/2018-11/Davis-Mayberry_HPSEP_11212018.pdf
47    // for the "next gen" SEP characteristics.
48
49    // GTO start
50    let orbit = Orbit::keplerian(24505.9, 0.725, 7.05, 0.0, 0.0, 0.0, epoch, eme2k);
51
52    let sc = Spacecraft::builder()
53        .orbit(orbit)
54        .mass(Mass::from_dry_and_prop_masses(1000.0, 1000.0)) // 1000 kg of dry mass and prop, totalling 2.0 tons
55        .srp(SRPData::from_area(3.0 * 6.0)) // Assuming 1 kW/m^2 or 18 kW, giving a margin of 4.35 kW for on-propulsion consumption
56        .thruster(Thruster {
57            // "NEXT-STEP" row in Table 2
58            isp_s: 4435.0,
59            thrust_N: 0.472,
60        })
61        .mode(GuidanceMode::Thrust) // Start thrusting immediately.
62        .build();
63
64    let prop_time = 180.0 * Unit::Day;
65
66    // Define the guidance law -- we're just using a Ruggiero controller as demonstrated in AAS-2004-5089.
67    let objectives = &[
68        Objective::within_tolerance(StateParameter::SMA, 42_165.0, 20.0),
69        Objective::within_tolerance(StateParameter::Eccentricity, 0.001, 5e-5),
70        Objective::within_tolerance(StateParameter::Inclination, 0.05, 1e-2),
71    ];
72
73    // Ensure that we only thrust if we have more than 20% illumination.
74    let ruggiero_ctrl = Ruggiero::from_max_eclipse(objectives, sc, 0.2).unwrap();
75    println!("{ruggiero_ctrl}");
76
77    // Define the high fidelity dynamics
78
79    // Set up the spacecraft dynamics.
80
81    // Specify that the orbital dynamics must account for the graviational pull of the Moon and the Sun.
82    // The gravity of the Earth will also be accounted for since the spaceraft in an Earth orbit.
83    let mut orbital_dyn = OrbitalDynamics::point_masses(vec![MOON, SUN]);
84
85    // We want to include the spherical harmonics, so let's download the gravitational data from the Nyx Cloud.
86    // We're using the JGM3 model here, which is the default in GMAT.
87    let mut jgm3_meta = MetaFile {
88        uri: "http://public-data.nyxspace.com/nyx/models/JGM3.cof.gz".to_string(),
89        crc32: Some(0xF446F027), // Specifying the CRC32 avoids redownloading it if it's cached.
90    };
91    // And let's download it if we don't have it yet.
92    jgm3_meta.process(true)?;
93
94    // Build the spherical harmonics.
95    // The harmonics must be computed in the body fixed frame.
96    // We're using the long term prediction of the Earth centered Earth fixed frame, IAU Earth.
97    let harmonics = Harmonics::from_stor(
98        almanac.frame_from_uid(IAU_EARTH_FRAME)?,
99        HarmonicsMem::from_cof(&jgm3_meta.uri, 8, 8, true).unwrap(),
100    );
101
102    // Include the spherical harmonics into the orbital dynamics.
103    orbital_dyn.accel_models.push(harmonics);
104
105    // We define the solar radiation pressure, using the default solar flux and accounting only
106    // for the eclipsing caused by the Earth.
107    let srp_dyn = SolarPressure::default(EARTH_J2000, almanac.clone())?;
108
109    // Finalize setting up the dynamics, specifying the force models (orbital_dyn) separately from the
110    // acceleration models (SRP in this case). Use `from_models` to specify multiple accel models.
111    let sc_dynamics = SpacecraftDynamics::from_model(orbital_dyn, srp_dyn)
112        .with_guidance_law(ruggiero_ctrl.clone());
113
114    println!("{orbit:x}");
115
116    // We specify a minimum step in the propagator because the Ruggiero control would otherwise drive this step very low.
117    let (final_state, traj) = Propagator::rk89(
118        sc_dynamics.clone(),
119        IntegratorOptions::builder()
120            .min_step(10.0_f64.seconds())
121            .error_ctrl(ErrorControl::RSSCartesianStep)
122            .build(),
123    )
124    .with(sc, almanac.clone())
125    .for_duration_with_traj(prop_time)?;
126
127    let prop_usage = sc.mass.prop_mass_kg - final_state.mass.prop_mass_kg;
128    println!("{:x}", final_state.orbit);
129    println!("prop usage: {prop_usage:.3} kg");
130
131    // Finally, export the results for analysis, including the penumbra percentage throughout the orbit raise.
132    traj.to_parquet(
133        "./03_geo_raise.parquet",
134        Some(vec![
135            &EclipseLocator::cislunar(almanac.clone()).to_penumbra_event()
136        ]),
137        ExportCfg::default(),
138        almanac,
139    )?;
140
141    for status_line in ruggiero_ctrl.status(&final_state) {
142        println!("{status_line}");
143    }
144
145    ruggiero_ctrl
146        .achieved(&final_state)
147        .expect("objective not achieved");
148
149    Ok(())
150}
examples/05_cislunar_spacecraft_link_od/main.rs (line 61)
34fn main() -> Result<(), Box<dyn Error>> {
35    pel::init();
36
37    // ====================== //
38    // === ALMANAC SET UP === //
39    // ====================== //
40
41    let manifest_dir =
42        PathBuf::from(std::env::var("CARGO_MANIFEST_DIR").unwrap_or(".".to_string()));
43
44    let out = manifest_dir.join("data/04_output/");
45
46    let almanac = Arc::new(
47        Almanac::new(
48            &manifest_dir
49                .join("data/01_planetary/pck08.pca")
50                .to_string_lossy(),
51        )
52        .unwrap()
53        .load(
54            &manifest_dir
55                .join("data/01_planetary/de440s.bsp")
56                .to_string_lossy(),
57        )
58        .unwrap(),
59    );
60
61    let eme2k = almanac.frame_from_uid(EARTH_J2000).unwrap();
62    let moon_iau = almanac.frame_from_uid(IAU_MOON_FRAME).unwrap();
63
64    let epoch = Epoch::from_gregorian_tai(2021, 5, 29, 19, 51, 16, 852_000);
65    let nrho = Orbit::cartesian(
66        166_473.631_302_239_7,
67        -274_715.487_253_382_7,
68        -211_233.210_176_686_7,
69        0.933_451_604_520_018_4,
70        0.436_775_046_841_900_9,
71        -0.082_211_021_250_348_95,
72        epoch,
73        eme2k,
74    );
75
76    let tx_nrho_sc = Spacecraft::from(nrho);
77
78    let state_luna = almanac.transform_to(nrho, MOON_J2000, None).unwrap();
79    println!("Start state (dynamics: Earth, Moon, Sun gravity):\n{state_luna}");
80
81    let bodies = vec![EARTH, SUN];
82    let dynamics = SpacecraftDynamics::new(OrbitalDynamics::point_masses(bodies));
83
84    let setup = Propagator::rk89(
85        dynamics,
86        IntegratorOptions::builder().max_step(0.5.minutes()).build(),
87    );
88
89    /* == Propagate the NRHO vehicle == */
90    let prop_time = 1.1 * state_luna.period().unwrap();
91
92    let (nrho_final, mut tx_traj) = setup
93        .with(tx_nrho_sc, almanac.clone())
94        .for_duration_with_traj(prop_time)
95        .unwrap();
96
97    tx_traj.name = Some("NRHO Tx SC".to_string());
98
99    println!("{tx_traj}");
100
101    /* == Propagate an LLO vehicle == */
102    let llo_orbit =
103        Orbit::try_keplerian_altitude(110.0, 1e-4, 90.0, 0.0, 0.0, 0.0, epoch, moon_iau).unwrap();
104
105    let llo_sc = Spacecraft::builder().orbit(llo_orbit).build();
106
107    let (_, llo_traj) = setup
108        .with(llo_sc, almanac.clone())
109        .until_epoch_with_traj(nrho_final.epoch())
110        .unwrap();
111
112    // Export the subset of the first two hours.
113    llo_traj
114        .clone()
115        .filter_by_offset(..2.hours())
116        .to_parquet_simple(out.join("05_caps_llo_truth.pq"), almanac.clone())?;
117
118    /* == Setup the interlink == */
119
120    let mut measurement_types = IndexSet::new();
121    measurement_types.insert(MeasurementType::Range);
122    measurement_types.insert(MeasurementType::Doppler);
123
124    let mut stochastics = IndexMap::new();
125
126    let sa45_csac_allan_dev = 1e-11;
127
128    stochastics.insert(
129        MeasurementType::Range,
130        StochasticNoise::from_hardware_range_km(
131            sa45_csac_allan_dev,
132            10.0.seconds(),
133            link_specific::ChipRate::StandardT4B,
134            link_specific::SN0::Average,
135        ),
136    );
137
138    stochastics.insert(
139        MeasurementType::Doppler,
140        StochasticNoise::from_hardware_doppler_km_s(
141            sa45_csac_allan_dev,
142            10.0.seconds(),
143            link_specific::CarrierFreq::SBand,
144            link_specific::CN0::Average,
145        ),
146    );
147
148    let interlink = InterlinkTxSpacecraft {
149        traj: tx_traj,
150        measurement_types,
151        integration_time: None,
152        timestamp_noise_s: None,
153        ab_corr: Aberration::LT,
154        stochastic_noises: Some(stochastics),
155    };
156
157    // Devices are the transmitter, which is our NRHO vehicle.
158    let mut devices = BTreeMap::new();
159    devices.insert("NRHO Tx SC".to_string(), interlink);
160
161    let mut configs = BTreeMap::new();
162    configs.insert(
163        "NRHO Tx SC".to_string(),
164        TrkConfig::builder()
165            .strands(vec![Strand {
166                start: epoch,
167                end: nrho_final.epoch(),
168            }])
169            .build(),
170    );
171
172    let mut trk_sim =
173        TrackingArcSim::with_seed(devices.clone(), llo_traj.clone(), configs, 0).unwrap();
174    println!("{trk_sim}");
175
176    let trk_data = trk_sim.generate_measurements(almanac.clone()).unwrap();
177    println!("{trk_data}");
178
179    trk_data
180        .to_parquet_simple(out.clone().join("nrho_interlink_msr.pq"))
181        .unwrap();
182
183    // Run a truth OD where we estimate the LLO position
184    let llo_uncertainty = SpacecraftUncertainty::builder()
185        .nominal(llo_sc)
186        .x_km(1.0)
187        .y_km(1.0)
188        .z_km(1.0)
189        .vx_km_s(1e-3)
190        .vy_km_s(1e-3)
191        .vz_km_s(1e-3)
192        .build();
193
194    let mut proc_devices = devices.clone();
195
196    // Define the initial estimate, randomized, seed for reproducibility
197    let mut initial_estimate = llo_uncertainty.to_estimate_randomized(Some(0)).unwrap();
198    // Inflate the covariance -- https://github.com/nyx-space/nyx/issues/339
199    initial_estimate.covar *= 2.5;
200
201    // Increase the noise in the devices to accept more measurements.
202
203    for link in proc_devices.values_mut() {
204        for noise in &mut link.stochastic_noises.as_mut().unwrap().values_mut() {
205            *noise.white_noise.as_mut().unwrap() *= 3.0;
206        }
207    }
208
209    let init_err = initial_estimate
210        .orbital_state()
211        .ric_difference(&llo_orbit)
212        .unwrap();
213
214    println!("initial estimate:\n{initial_estimate}");
215    println!("RIC errors = {init_err}",);
216
217    let odp = InterlinkKalmanOD::new(
218        setup.clone(),
219        KalmanVariant::ReferenceUpdate,
220        Some(ResidRejectCrit::default()),
221        proc_devices,
222        almanac.clone(),
223    );
224
225    // Shrink the data to process.
226    let arc = trk_data.filter_by_offset(..2.hours());
227
228    let od_sol = odp.process_arc(initial_estimate, &arc).unwrap();
229
230    println!("{od_sol}");
231
232    od_sol
233        .to_parquet(
234            out.join(format!("05_caps_interlink_od_sol.pq")),
235            ExportCfg::default(),
236        )
237        .unwrap();
238
239    let od_traj = od_sol.to_traj().unwrap();
240
241    od_traj
242        .ric_diff_to_parquet(
243            &llo_traj,
244            out.join(format!("05_caps_interlink_llo_est_error.pq")),
245            ExportCfg::default(),
246        )
247        .unwrap();
248
249    let final_est = od_sol.estimates.last().unwrap();
250    assert!(final_est.within_3sigma(), "should be within 3 sigma");
251
252    println!("ESTIMATE\n{final_est:x}\n");
253    let truth = llo_traj.at(final_est.epoch()).unwrap();
254    println!("TRUTH\n{truth:x}");
255
256    let final_err = truth
257        .orbit
258        .ric_difference(&final_est.orbital_state())
259        .unwrap();
260    println!("ERROR {final_err}");
261
262    // Build the residuals versus reference plot.
263    let rvr_sol = odp
264        .process_arc(initial_estimate, &arc.resid_vs_ref_check())
265        .unwrap();
266
267    rvr_sol
268        .to_parquet(
269            out.join(format!("05_caps_interlink_resid_v_ref.pq")),
270            ExportCfg::default(),
271        )
272        .unwrap();
273
274    let final_rvr = rvr_sol.estimates.last().unwrap();
275
276    println!("RMAG error {:.3} m", final_err.rmag_km() * 1e3);
277    println!(
278        "Pure prop error {:.3} m",
279        final_rvr
280            .orbital_state()
281            .ric_difference(&final_est.orbital_state())
282            .unwrap()
283            .rmag_km()
284            * 1e3
285    );
286
287    Ok(())
288}
examples/03_geo_analysis/drift.rs (line 46)
26fn main() -> Result<(), Box<dyn Error>> {
27    pel::init();
28    // Dynamics models require planetary constants and ephemerides to be defined.
29    // Let's start by grabbing those by using ANISE's latest MetaAlmanac.
30    // This will automatically download the DE440s planetary ephemeris,
31    // the daily-updated Earth Orientation Parameters, the high fidelity Moon orientation
32    // parameters (for the Moon Mean Earth and Moon Principal Axes frames), and the PCK11
33    // planetary constants kernels.
34    // For details, refer to https://github.com/nyx-space/anise/blob/master/data/latest.dhall.
35    // Note that we place the Almanac into an Arc so we can clone it cheaply and provide read-only
36    // references to many functions.
37    let almanac = Arc::new(MetaAlmanac::latest().map_err(Box::new)?);
38    // Define the orbit epoch
39    let epoch = Epoch::from_gregorian_utc_hms(2024, 2, 29, 12, 13, 14);
40
41    // Define the orbit.
42    // First we need to fetch the Earth J2000 from information from the Almanac.
43    // This allows the frame to include the gravitational parameters and the shape of the Earth,
44    // defined as a tri-axial ellipoid. Note that this shape can be changed manually or in the Almanac
45    // by loading a different set of planetary constants.
46    let earth_j2000 = almanac.frame_from_uid(EARTH_J2000)?;
47
48    // Placing this GEO bird just above Colorado.
49    // In theory, the eccentricity is zero, but in practice, it's about 1e-5 to 1e-6 at best.
50    let orbit = Orbit::try_keplerian(42164.0, 1e-5, 0., 163.0, 75.0, 0.0, epoch, earth_j2000)?;
51    // Print in in Keplerian form.
52    println!("{orbit:x}");
53
54    let state_bf = almanac.transform_to(orbit, IAU_EARTH_FRAME, None)?;
55    let (orig_lat_deg, orig_long_deg, orig_alt_km) = state_bf.latlongalt()?;
56
57    // Nyx is used for high fidelity propagation, not Keplerian propagation as above.
58    // Nyx only propagates Spacecraft at the moment, which allows it to account for acceleration
59    // models such as solar radiation pressure.
60
61    // Let's build a cubesat sized spacecraft, with an SRP area of 10 cm^2 and a mass of 9.6 kg.
62    let sc = Spacecraft::builder()
63        .orbit(orbit)
64        .mass(Mass::from_dry_mass(9.60))
65        .srp(SRPData {
66            area_m2: 10e-4,
67            coeff_reflectivity: 1.1,
68        })
69        .build();
70    println!("{sc:x}");
71
72    // Set up the spacecraft dynamics.
73
74    // Specify that the orbital dynamics must account for the graviational pull of the Moon and the Sun.
75    // The gravity of the Earth will also be accounted for since the spaceraft in an Earth orbit.
76    let mut orbital_dyn = OrbitalDynamics::point_masses(vec![MOON, SUN]);
77
78    // We want to include the spherical harmonics, so let's download the gravitational data from the Nyx Cloud.
79    // We're using the JGM3 model here, which is the default in GMAT.
80    let mut jgm3_meta = MetaFile {
81        uri: "http://public-data.nyxspace.com/nyx/models/JGM3.cof.gz".to_string(),
82        crc32: Some(0xF446F027), // Specifying the CRC32 avoids redownloading it if it's cached.
83    };
84    // And let's download it if we don't have it yet.
85    jgm3_meta.process(true)?;
86
87    // Build the spherical harmonics.
88    // The harmonics must be computed in the body fixed frame.
89    // We're using the long term prediction of the Earth centered Earth fixed frame, IAU Earth.
90    let harmonics_21x21 = Harmonics::from_stor(
91        almanac.frame_from_uid(IAU_EARTH_FRAME)?,
92        HarmonicsMem::from_cof(&jgm3_meta.uri, 21, 21, true).unwrap(),
93    );
94
95    // Include the spherical harmonics into the orbital dynamics.
96    orbital_dyn.accel_models.push(harmonics_21x21);
97
98    // We define the solar radiation pressure, using the default solar flux and accounting only
99    // for the eclipsing caused by the Earth and Moon.
100    let srp_dyn = SolarPressure::new(vec![EARTH_J2000, MOON_J2000], almanac.clone())?;
101
102    // Finalize setting up the dynamics, specifying the force models (orbital_dyn) separately from the
103    // acceleration models (SRP in this case). Use `from_models` to specify multiple accel models.
104    let dynamics = SpacecraftDynamics::from_model(orbital_dyn, srp_dyn);
105
106    println!("{dynamics}");
107
108    // Finally, let's propagate this orbit to the same epoch as above.
109    // The first returned value is the spacecraft state at the final epoch.
110    // The second value is the full trajectory where the step size is variable step used by the propagator.
111    let (future_sc, trajectory) = Propagator::default(dynamics)
112        .with(sc, almanac.clone())
113        .until_epoch_with_traj(epoch + Unit::Century * 0.03)?;
114
115    println!("=== High fidelity propagation ===");
116    println!(
117        "SMA changed by {:.3} km",
118        orbit.sma_km()? - future_sc.orbit.sma_km()?
119    );
120    println!(
121        "ECC changed by {:.6}",
122        orbit.ecc()? - future_sc.orbit.ecc()?
123    );
124    println!(
125        "INC changed by {:.3e} deg",
126        orbit.inc_deg()? - future_sc.orbit.inc_deg()?
127    );
128    println!(
129        "RAAN changed by {:.3} deg",
130        orbit.raan_deg()? - future_sc.orbit.raan_deg()?
131    );
132    println!(
133        "AOP changed by {:.3} deg",
134        orbit.aop_deg()? - future_sc.orbit.aop_deg()?
135    );
136    println!(
137        "TA changed by {:.3} deg",
138        orbit.ta_deg()? - future_sc.orbit.ta_deg()?
139    );
140
141    // We also have access to the full trajectory throughout the propagation.
142    println!("{trajectory}");
143
144    println!("Spacecraft params after 3 years without active control:\n{future_sc:x}");
145
146    // With the trajectory, let's build a few data products.
147
148    // 1. Export the trajectory as a parquet file, which includes the Keplerian orbital elements.
149
150    let analysis_step = Unit::Minute * 5;
151
152    trajectory.to_parquet(
153        "./03_geo_hf_prop.parquet",
154        Some(vec![
155            &EclipseLocator::cislunar(almanac.clone()).to_penumbra_event()
156        ]),
157        ExportCfg::builder().step(analysis_step).build(),
158        almanac.clone(),
159    )?;
160
161    // 2. Compute the latitude, longitude, and altitude throughout the trajectory by rotating the spacecraft position into the Earth body fixed frame.
162
163    // We iterate over the trajectory, grabbing a state every two minutes.
164    let mut offset_s = vec![];
165    let mut epoch_str = vec![];
166    let mut longitude_deg = vec![];
167    let mut latitude_deg = vec![];
168    let mut altitude_km = vec![];
169
170    for state in trajectory.every(analysis_step) {
171        // Convert the GEO bird state into the body fixed frame, and keep track of its latitude, longitude, and altitude.
172        // These define the GEO stationkeeping box.
173
174        let this_epoch = state.epoch();
175
176        offset_s.push((this_epoch - orbit.epoch).to_seconds());
177        epoch_str.push(this_epoch.to_isoformat());
178
179        let state_bf = almanac.transform_to(state.orbit, IAU_EARTH_FRAME, None)?;
180        let (lat_deg, long_deg, alt_km) = state_bf.latlongalt()?;
181        longitude_deg.push(long_deg);
182        latitude_deg.push(lat_deg);
183        altitude_km.push(alt_km);
184    }
185
186    println!(
187        "Longitude changed by {:.3} deg -- Box is 0.1 deg E-W",
188        orig_long_deg - longitude_deg.last().unwrap()
189    );
190
191    println!(
192        "Latitude changed by {:.3} deg -- Box is 0.05 deg N-S",
193        orig_lat_deg - latitude_deg.last().unwrap()
194    );
195
196    println!(
197        "Altitude changed by {:.3} km -- Box is 30 km",
198        orig_alt_km - altitude_km.last().unwrap()
199    );
200
201    // Build the station keeping data frame.
202    let mut sk_df = df!(
203        "Offset (s)" => offset_s.clone(),
204        "Epoch (UTC)" => epoch_str.clone(),
205        "Longitude E-W (deg)" => longitude_deg,
206        "Latitude N-S (deg)" => latitude_deg,
207        "Altitude (km)" => altitude_km,
208
209    )?;
210
211    // Create a file to write the Parquet to
212    let file = File::create("./03_geo_lla.parquet").expect("Could not create file");
213
214    // Create a ParquetWriter and write the DataFrame to the file
215    ParquetWriter::new(file).finish(&mut sk_df)?;
216
217    Ok(())
218}
examples/01_orbit_prop/main.rs (line 50)
30fn main() -> Result<(), Box<dyn Error>> {
31    pel::init();
32    // Dynamics models require planetary constants and ephemerides to be defined.
33    // Let's start by grabbing those by using ANISE's latest MetaAlmanac.
34    // This will automatically download the DE440s planetary ephemeris,
35    // the daily-updated Earth Orientation Parameters, the high fidelity Moon orientation
36    // parameters (for the Moon Mean Earth and Moon Principal Axes frames), and the PCK11
37    // planetary constants kernels.
38    // For details, refer to https://github.com/nyx-space/anise/blob/master/data/latest.dhall.
39    // Note that we place the Almanac into an Arc so we can clone it cheaply and provide read-only
40    // references to many functions.
41    let almanac = Arc::new(MetaAlmanac::latest().map_err(Box::new)?);
42    // Define the orbit epoch
43    let epoch = Epoch::from_gregorian_utc_hms(2024, 2, 29, 12, 13, 14);
44
45    // Define the orbit.
46    // First we need to fetch the Earth J2000 from information from the Almanac.
47    // This allows the frame to include the gravitational parameters and the shape of the Earth,
48    // defined as a tri-axial ellipoid. Note that this shape can be changed manually or in the Almanac
49    // by loading a different set of planetary constants.
50    let earth_j2000 = almanac.frame_from_uid(EARTH_J2000)?;
51
52    let orbit =
53        Orbit::try_keplerian_altitude(300.0, 0.015, 68.5, 65.2, 75.0, 0.0, epoch, earth_j2000)?;
54    // Print in in Keplerian form.
55    println!("{orbit:x}");
56
57    // There are two ways to propagate an orbit. We can make a quick approximation assuming only two-body
58    // motion. This is a useful first order approximation but it isn't used in real-world applications.
59
60    // This approach is a feature of ANISE.
61    let future_orbit_tb = orbit.at_epoch(epoch + Unit::Day * 3)?;
62    println!("{future_orbit_tb:x}");
63
64    // Two body propagation relies solely on Kepler's laws, so only the true anomaly will change.
65    println!(
66        "SMA changed by {:.3e} km",
67        orbit.sma_km()? - future_orbit_tb.sma_km()?
68    );
69    println!(
70        "ECC changed by {:.3e}",
71        orbit.ecc()? - future_orbit_tb.ecc()?
72    );
73    println!(
74        "INC changed by {:.3e} deg",
75        orbit.inc_deg()? - future_orbit_tb.inc_deg()?
76    );
77    println!(
78        "RAAN changed by {:.3e} deg",
79        orbit.raan_deg()? - future_orbit_tb.raan_deg()?
80    );
81    println!(
82        "AOP changed by {:.3e} deg",
83        orbit.aop_deg()? - future_orbit_tb.aop_deg()?
84    );
85    println!(
86        "TA changed by {:.3} deg",
87        orbit.ta_deg()? - future_orbit_tb.ta_deg()?
88    );
89
90    // Nyx is used for high fidelity propagation, not Keplerian propagation as above.
91    // Nyx only propagates Spacecraft at the moment, which allows it to account for acceleration
92    // models such as solar radiation pressure.
93
94    // Let's build a cubesat sized spacecraft, with an SRP area of 10 cm^2 and a mass of 9.6 kg.
95    let sc = Spacecraft::builder()
96        .orbit(orbit)
97        .mass(Mass::from_dry_mass(9.60))
98        .srp(SRPData {
99            area_m2: 10e-4,
100            coeff_reflectivity: 1.1,
101        })
102        .build();
103    println!("{sc:x}");
104
105    // Set up the spacecraft dynamics.
106
107    // Specify that the orbital dynamics must account for the graviational pull of the Moon and the Sun.
108    // The gravity of the Earth will also be accounted for since the spaceraft in an Earth orbit.
109    let mut orbital_dyn = OrbitalDynamics::point_masses(vec![MOON, SUN]);
110
111    // We want to include the spherical harmonics, so let's download the gravitational data from the Nyx Cloud.
112    // We're using the JGM3 model here, which is the default in GMAT.
113    let mut jgm3_meta = MetaFile {
114        uri: "http://public-data.nyxspace.com/nyx/models/JGM3.cof.gz".to_string(),
115        crc32: Some(0xF446F027), // Specifying the CRC32 avoids redownloading it if it's cached.
116    };
117    // And let's download it if we don't have it yet.
118    jgm3_meta.process(true)?;
119
120    // Build the spherical harmonics.
121    // The harmonics must be computed in the body fixed frame.
122    // We're using the long term prediction of the Earth centered Earth fixed frame, IAU Earth.
123    let harmonics_21x21 = Harmonics::from_stor(
124        almanac.frame_from_uid(IAU_EARTH_FRAME)?,
125        HarmonicsMem::from_cof(&jgm3_meta.uri, 21, 21, true).unwrap(),
126    );
127
128    // Include the spherical harmonics into the orbital dynamics.
129    orbital_dyn.accel_models.push(harmonics_21x21);
130
131    // We define the solar radiation pressure, using the default solar flux and accounting only
132    // for the eclipsing caused by the Earth.
133    let srp_dyn = SolarPressure::default(EARTH_J2000, almanac.clone())?;
134
135    // Finalize setting up the dynamics, specifying the force models (orbital_dyn) separately from the
136    // acceleration models (SRP in this case). Use `from_models` to specify multiple accel models.
137    let dynamics = SpacecraftDynamics::from_model(orbital_dyn, srp_dyn);
138
139    println!("{dynamics}");
140
141    // Finally, let's propagate this orbit to the same epoch as above.
142    // The first returned value is the spacecraft state at the final epoch.
143    // The second value is the full trajectory where the step size is variable step used by the propagator.
144    let (future_sc, trajectory) = Propagator::default(dynamics)
145        .with(sc, almanac.clone())
146        .until_epoch_with_traj(future_orbit_tb.epoch)?;
147
148    println!("=== High fidelity propagation ===");
149    println!(
150        "SMA changed by {:.3} km",
151        orbit.sma_km()? - future_sc.orbit.sma_km()?
152    );
153    println!(
154        "ECC changed by {:.6}",
155        orbit.ecc()? - future_sc.orbit.ecc()?
156    );
157    println!(
158        "INC changed by {:.3e} deg",
159        orbit.inc_deg()? - future_sc.orbit.inc_deg()?
160    );
161    println!(
162        "RAAN changed by {:.3} deg",
163        orbit.raan_deg()? - future_sc.orbit.raan_deg()?
164    );
165    println!(
166        "AOP changed by {:.3} deg",
167        orbit.aop_deg()? - future_sc.orbit.aop_deg()?
168    );
169    println!(
170        "TA changed by {:.3} deg",
171        orbit.ta_deg()? - future_sc.orbit.ta_deg()?
172    );
173
174    // We also have access to the full trajectory throughout the propagation.
175    println!("{trajectory}");
176
177    // With the trajectory, let's build a few data products.
178
179    // 1. Export the trajectory as a CCSDS OEM version 2.0 file and as a parquet file, which includes the Keplerian orbital elements.
180
181    trajectory.to_oem_file(
182        "./01_cubesat_hf_prop.oem",
183        ExportCfg::builder().step(Unit::Minute * 2).build(),
184    )?;
185
186    trajectory.to_parquet_with_cfg(
187        "./01_cubesat_hf_prop.parquet",
188        ExportCfg::builder().step(Unit::Minute * 2).build(),
189        almanac.clone(),
190    )?;
191
192    // 2. Compare the difference in the radial-intrack-crosstrack frame between the high fidelity
193    // and Keplerian propagation. The RIC frame is commonly used to compute the difference in position
194    // and velocity of different spacecraft.
195    // 3. Compute the azimuth, elevation, range, and range-rate data of that spacecraft as seen from Boulder, CO, USA.
196
197    let boulder_station = GroundStation::from_point(
198        "Boulder, CO, USA".to_string(),
199        40.014984,   // latitude in degrees
200        -105.270546, // longitude in degrees
201        1.6550,      // altitude in kilometers
202        almanac.frame_from_uid(IAU_EARTH_FRAME)?,
203    );
204
205    // We iterate over the trajectory, grabbing a state every two minutes.
206    let mut offset_s = vec![];
207    let mut epoch_str = vec![];
208    let mut ric_x_km = vec![];
209    let mut ric_y_km = vec![];
210    let mut ric_z_km = vec![];
211    let mut ric_vx_km_s = vec![];
212    let mut ric_vy_km_s = vec![];
213    let mut ric_vz_km_s = vec![];
214
215    let mut azimuth_deg = vec![];
216    let mut elevation_deg = vec![];
217    let mut range_km = vec![];
218    let mut range_rate_km_s = vec![];
219    for state in trajectory.every(Unit::Minute * 2) {
220        // Try to compute the Keplerian/two body state just in time.
221        // This method occasionally fails to converge on an appropriate true anomaly
222        // from the mean anomaly. If that happens, we just skip this state.
223        // The high fidelity and Keplerian states diverge continuously, and we're curious
224        // about the divergence in this quick analysis.
225        let this_epoch = state.epoch();
226        match orbit.at_epoch(this_epoch) {
227            Ok(tb_then) => {
228                offset_s.push((this_epoch - orbit.epoch).to_seconds());
229                epoch_str.push(format!("{this_epoch}"));
230                // Compute the two body state just in time.
231                let ric = state.orbit.ric_difference(&tb_then)?;
232                ric_x_km.push(ric.radius_km.x);
233                ric_y_km.push(ric.radius_km.y);
234                ric_z_km.push(ric.radius_km.z);
235                ric_vx_km_s.push(ric.velocity_km_s.x);
236                ric_vy_km_s.push(ric.velocity_km_s.y);
237                ric_vz_km_s.push(ric.velocity_km_s.z);
238
239                // Compute the AER data for each state.
240                let aer = almanac.azimuth_elevation_range_sez(
241                    state.orbit,
242                    boulder_station.to_orbit(this_epoch, &almanac)?,
243                    None,
244                    None,
245                )?;
246                azimuth_deg.push(aer.azimuth_deg);
247                elevation_deg.push(aer.elevation_deg);
248                range_km.push(aer.range_km);
249                range_rate_km_s.push(aer.range_rate_km_s);
250            }
251            Err(e) => warn!("{} {e}", state.epoch()),
252        };
253    }
254
255    // Build the data frames.
256    let ric_df = df!(
257        "Offset (s)" => offset_s.clone(),
258        "Epoch" => epoch_str.clone(),
259        "RIC X (km)" => ric_x_km,
260        "RIC Y (km)" => ric_y_km,
261        "RIC Z (km)" => ric_z_km,
262        "RIC VX (km/s)" => ric_vx_km_s,
263        "RIC VY (km/s)" => ric_vy_km_s,
264        "RIC VZ (km/s)" => ric_vz_km_s,
265    )?;
266
267    println!("RIC difference at start\n{}", ric_df.head(Some(10)));
268    println!("RIC difference at end\n{}", ric_df.tail(Some(10)));
269
270    let aer_df = df!(
271        "Offset (s)" => offset_s.clone(),
272        "Epoch" => epoch_str.clone(),
273        "azimuth (deg)" => azimuth_deg,
274        "elevation (deg)" => elevation_deg,
275        "range (km)" => range_km,
276        "range rate (km/s)" => range_rate_km_s,
277    )?;
278
279    // Finally, let's see when the spacecraft is visible, assuming 15 degrees minimum elevation.
280    let mask = aer_df
281        .column("elevation (deg)")?
282        .gt(&Column::Scalar(ScalarColumn::new(
283            "elevation mask (deg)".into(),
284            Scalar::new(DataType::Float64, AnyValue::Float64(15.0)),
285            offset_s.len(),
286        )))?;
287    let cubesat_visible = aer_df.filter(&mask)?;
288
289    println!("{cubesat_visible}");
290
291    Ok(())
292}
examples/04_lro_od/main.rs (line 129)
34fn main() -> Result<(), Box<dyn Error>> {
35    pel::init();
36
37    // ====================== //
38    // === ALMANAC SET UP === //
39    // ====================== //
40
41    // Dynamics models require planetary constants and ephemerides to be defined.
42    // Let's start by grabbing those by using ANISE's MetaAlmanac.
43
44    let data_folder: PathBuf = [env!("CARGO_MANIFEST_DIR"), "examples", "04_lro_od"]
45        .iter()
46        .collect();
47
48    let meta = data_folder.join("lro-dynamics.dhall");
49
50    // Load this ephem in the general Almanac we're using for this analysis.
51    let mut almanac = MetaAlmanac::new(meta.to_string_lossy().to_string())
52        .map_err(Box::new)?
53        .process(true)
54        .map_err(Box::new)?;
55
56    let mut moon_pc = almanac.planetary_data.get_by_id(MOON)?;
57    moon_pc.mu_km3_s2 = 4902.74987;
58    almanac.planetary_data.set_by_id(MOON, moon_pc)?;
59
60    let mut earth_pc = almanac.planetary_data.get_by_id(EARTH)?;
61    earth_pc.mu_km3_s2 = 398600.436;
62    almanac.planetary_data.set_by_id(EARTH, earth_pc)?;
63
64    // Save this new kernel for reuse.
65    // In an operational context, this would be part of the "Lock" process, and should not change throughout the mission.
66    almanac
67        .planetary_data
68        .save_as(&data_folder.join("lro-specific.pca"), true)?;
69
70    // Lock the almanac (an Arc is a read only structure).
71    let almanac = Arc::new(almanac);
72
73    // Orbit determination requires a Trajectory structure, which can be saved as parquet file.
74    // In our case, the trajectory comes from the BSP file, so we need to build a Trajectory from the almanac directly.
75    // To query the Almanac, we need to build the LRO frame in the J2000 orientation in our case.
76    // Inspecting the LRO BSP in the ANISE GUI shows us that NASA has assigned ID -85 to LRO.
77    let lro_frame = Frame::from_ephem_j2000(-85);
78
79    // To build the trajectory we need to provide a spacecraft template.
80    let sc_template = Spacecraft::builder()
81        .mass(Mass::from_dry_and_prop_masses(1018.0, 900.0)) // Launch masses
82        .srp(SRPData {
83            // SRP configuration is arbitrary, but we will be estimating it anyway.
84            area_m2: 3.9 * 2.7,
85            coeff_reflectivity: 0.96,
86        })
87        .orbit(Orbit::zero(MOON_J2000)) // Setting a zero orbit here because it's just a template
88        .build();
89    // Now we can build the trajectory from the BSP file.
90    // We'll arbitrarily set the tracking arc to 24 hours with a five second time step.
91    let traj_as_flown = Traj::from_bsp(
92        lro_frame,
93        MOON_J2000,
94        almanac.clone(),
95        sc_template,
96        5.seconds(),
97        Some(Epoch::from_str("2024-01-01 00:00:00 UTC")?),
98        Some(Epoch::from_str("2024-01-02 00:00:00 UTC")?),
99        Aberration::LT,
100        Some("LRO".to_string()),
101    )?;
102
103    println!("{traj_as_flown}");
104
105    // ====================== //
106    // === MODEL MATCHING === //
107    // ====================== //
108
109    // Set up the spacecraft dynamics.
110
111    // Specify that the orbital dynamics must account for the graviational pull of the Earth and the Sun.
112    // The gravity of the Moon will also be accounted for since the spaceraft in a lunar orbit.
113    let mut orbital_dyn = OrbitalDynamics::point_masses(vec![EARTH, SUN, JUPITER_BARYCENTER]);
114
115    // We want to include the spherical harmonics, so let's download the gravitational data from the Nyx Cloud.
116    // We're using the GRAIL JGGRX model.
117    let mut jggrx_meta = MetaFile {
118        uri: "http://public-data.nyxspace.com/nyx/models/Luna_jggrx_1500e_sha.tab.gz".to_string(),
119        crc32: Some(0x6bcacda8), // Specifying the CRC32 avoids redownloading it if it's cached.
120    };
121    // And let's download it if we don't have it yet.
122    jggrx_meta.process(true)?;
123
124    // Build the spherical harmonics.
125    // The harmonics must be computed in the body fixed frame.
126    // We're using the long term prediction of the Moon principal axes frame.
127    let moon_pa_frame = MOON_PA_FRAME.with_orient(31008);
128    let sph_harmonics = Harmonics::from_stor(
129        almanac.frame_from_uid(moon_pa_frame)?,
130        HarmonicsMem::from_shadr(&jggrx_meta.uri, 80, 80, true)?,
131    );
132
133    // Include the spherical harmonics into the orbital dynamics.
134    orbital_dyn.accel_models.push(sph_harmonics);
135
136    // We define the solar radiation pressure, using the default solar flux and accounting only
137    // for the eclipsing caused by the Earth and Moon.
138    // Note that by default, enabling the SolarPressure model will also enable the estimation of the coefficient of reflectivity.
139    let srp_dyn = SolarPressure::new(vec![EARTH_J2000, MOON_J2000], almanac.clone())?;
140
141    // Finalize setting up the dynamics, specifying the force models (orbital_dyn) separately from the
142    // acceleration models (SRP in this case). Use `from_models` to specify multiple accel models.
143    let dynamics = SpacecraftDynamics::from_model(orbital_dyn, srp_dyn);
144
145    println!("{dynamics}");
146
147    // Now we can build the propagator.
148    let setup = Propagator::default_dp78(dynamics.clone());
149
150    // For reference, let's build the trajectory with Nyx's models from that LRO state.
151    let (sim_final, traj_as_sim) = setup
152        .with(*traj_as_flown.first(), almanac.clone())
153        .until_epoch_with_traj(traj_as_flown.last().epoch())?;
154
155    println!("SIM INIT:  {:x}", traj_as_flown.first());
156    println!("SIM FINAL: {sim_final:x}");
157    // Compute RIC difference between SIM and LRO ephem
158    let sim_lro_delta = sim_final
159        .orbit
160        .ric_difference(&traj_as_flown.last().orbit)?;
161    println!("{traj_as_sim}");
162    println!(
163        "SIM v LRO - RIC Position (m): {:.3}",
164        sim_lro_delta.radius_km * 1e3
165    );
166    println!(
167        "SIM v LRO - RIC Velocity (m/s): {:.3}",
168        sim_lro_delta.velocity_km_s * 1e3
169    );
170
171    traj_as_sim.ric_diff_to_parquet(
172        &traj_as_flown,
173        "./04_lro_sim_truth_error.parquet",
174        ExportCfg::default(),
175    )?;
176
177    // ==================== //
178    // === OD SIMULATOR === //
179    // ==================== //
180
181    // After quite some time trying to exactly match the model, we still end up with an oscillatory difference on the order of 150 meters between the propagated state
182    // and the truth LRO state.
183
184    // Therefore, we will actually run an estimation from a dispersed LRO state.
185    // The sc_seed is the true LRO state from the BSP.
186    let sc_seed = *traj_as_flown.first();
187
188    // Load the Deep Space Network ground stations.
189    // Nyx allows you to build these at runtime but it's pretty static so we can just load them from YAML.
190    let ground_station_file: PathBuf = [
191        env!("CARGO_MANIFEST_DIR"),
192        "examples",
193        "04_lro_od",
194        "dsn-network.yaml",
195    ]
196    .iter()
197    .collect();
198
199    let devices = GroundStation::load_named(ground_station_file)?;
200
201    let mut proc_devices = devices.clone();
202
203    // Increase the noise in the devices to accept more measurements.
204    for gs in proc_devices.values_mut() {
205        if let Some(noise) = &mut gs
206            .stochastic_noises
207            .as_mut()
208            .unwrap()
209            .get_mut(&MeasurementType::Range)
210        {
211            *noise.white_noise.as_mut().unwrap() *= 3.0;
212        }
213    }
214
215    // Typical OD software requires that you specify your own tracking schedule or you'll have overlapping measurements.
216    // Nyx can build a tracking schedule for you based on the first station with access.
217    let trkconfg_yaml: PathBuf = [
218        env!("CARGO_MANIFEST_DIR"),
219        "examples",
220        "04_lro_od",
221        "tracking-cfg.yaml",
222    ]
223    .iter()
224    .collect();
225
226    let configs: BTreeMap<String, TrkConfig> = TrkConfig::load_named(trkconfg_yaml)?;
227
228    // Build the tracking arc simulation to generate a "standard measurement".
229    let mut trk = TrackingArcSim::<Spacecraft, GroundStation>::with_seed(
230        devices.clone(),
231        traj_as_flown.clone(),
232        configs,
233        123, // Set a seed for reproducibility
234    )?;
235
236    trk.build_schedule(almanac.clone())?;
237    let arc = trk.generate_measurements(almanac.clone())?;
238    // Save the simulated tracking data
239    arc.to_parquet_simple("./04_lro_simulated_tracking.parquet")?;
240
241    // We'll note that in our case, we have continuous coverage of LRO when the vehicle is not behind the Moon.
242    println!("{arc}");
243
244    // Now that we have simulated measurements, we'll run the orbit determination.
245
246    // ===================== //
247    // === OD ESTIMATION === //
248    // ===================== //
249
250    let sc = SpacecraftUncertainty::builder()
251        .nominal(sc_seed)
252        .frame(LocalFrame::RIC)
253        .x_km(0.5)
254        .y_km(0.5)
255        .z_km(0.5)
256        .vx_km_s(5e-3)
257        .vy_km_s(5e-3)
258        .vz_km_s(5e-3)
259        .build();
260
261    // Build the filter initial estimate, which we will reuse in the filter.
262    let mut initial_estimate = sc.to_estimate()?;
263    initial_estimate.covar *= 3.0;
264
265    println!("== FILTER STATE ==\n{sc_seed:x}\n{initial_estimate}");
266
267    // Build the SNC in the Moon J2000 frame, specified as a velocity noise over time.
268    let process_noise = ProcessNoise3D::from_velocity_km_s(
269        &[1e-10, 1e-10, 1e-10],
270        1 * Unit::Hour,
271        10 * Unit::Minute,
272        None,
273    );
274
275    println!("{process_noise}");
276
277    // We'll set up the OD process to reject measurements whose residuals are move than 3 sigmas away from what we expect.
278    let odp = SpacecraftKalmanOD::new(
279        setup,
280        KalmanVariant::ReferenceUpdate,
281        Some(ResidRejectCrit::default()),
282        proc_devices,
283        almanac.clone(),
284    )
285    .with_process_noise(process_noise);
286
287    let od_sol = odp.process_arc(initial_estimate, &arc)?;
288
289    let final_est = od_sol.estimates.last().unwrap();
290
291    println!("{final_est}");
292
293    let ric_err = traj_as_flown
294        .at(final_est.epoch())?
295        .orbit
296        .ric_difference(&final_est.orbital_state())?;
297    println!("== RIC at end ==");
298    println!("RIC Position (m): {:.3}", ric_err.radius_km * 1e3);
299    println!("RIC Velocity (m/s): {:.3}", ric_err.velocity_km_s * 1e3);
300
301    println!(
302        "Num residuals rejected: #{}",
303        od_sol.rejected_residuals().len()
304    );
305    println!(
306        "Percentage within +/-3: {}",
307        od_sol.residual_ratio_within_threshold(3.0).unwrap()
308    );
309    println!("Ratios normal? {}", od_sol.is_normal(None).unwrap());
310
311    od_sol.to_parquet("./04_lro_od_results.parquet", ExportCfg::default())?;
312
313    // In our case, we have the truth trajectory from NASA.
314    // So we can compute the RIC state difference between the real LRO ephem and what we've just estimated.
315    // Export the OD trajectory first.
316    let od_trajectory = od_sol.to_traj()?;
317    // Build the RIC difference.
318    od_trajectory.ric_diff_to_parquet(
319        &traj_as_flown,
320        "./04_lro_od_truth_error.parquet",
321        ExportCfg::default(),
322    )?;
323
324    Ok(())
325}

pub fn with_planetary_data( &self, planetary_data: DataSet<PlanetaryData, anise::::structure::PlanetaryDataSet::{constant#0}>, ) -> Almanac

Loads the provided planetary data into a clone of this original Almanac.

§

impl Almanac

pub fn sun_angle_deg( &self, target_id: i32, observer_id: i32, epoch: Epoch, ) -> Result<f64, EphemerisError>

Returns the angle (between 0 and 180 degrees) between the observer and the Sun, and the observer and the target body ID. This computes the Sun Probe Earth angle (SPE) if the probe is in a loaded SPK, its ID is the “observer_id”, and the target is set to its central body.

§Geometry

If the SPE is greater than 90 degrees, then the celestial object below the probe is in sunlight.

§Sunrise at nadir
Sun
 |  \      
 |   \
 |    \
 Obs. -- Target
§Sun high at nadir
Sun
 \        
  \  __ θ > 90
   \     \
    Obs. ---------- Target
§Sunset at nadir
         Sun
       /  
      /  __ θ < 90
     /    /
 Obs. -- Target
§Algorithm
  1. Compute the position of the Sun as seen from the observer
  2. Compute the position of the target as seen from the observer
  3. Return the arccosine of the dot product of the norms of these vectors.

:type target_id: int :type observer_id: int :type epoch: Epoch :rtype: float

pub fn sun_angle_deg_from_frame( &self, target: Frame, observer: Frame, epoch: Epoch, ) -> Result<f64, EphemerisError>

Convenience function that calls sun_angle_deg with the provided frames instead of the ephemeris ID.

:type target: Frame :type observer: Frame :type epoch: Epoch :rtype: float

§

impl Almanac

pub fn from_spk( spk: GenericDAF<SPKSummaryRecord, Bytes>, ) -> Result<Almanac, EphemerisError>

pub fn with_spk( &self, spk: GenericDAF<SPKSummaryRecord, Bytes>, ) -> Result<Almanac, EphemerisError>

Loads a new SPK file into a new context. This new context is needed to satisfy the unloading of files. In fact, to unload a file, simply let the newly loaded context drop out of scope and Rust will clean it up.

§

impl Almanac

pub fn num_loaded_spk(&self) -> usize

pub fn spk_summary_from_name_at_epoch( &self, name: &str, epoch: Epoch, ) -> Result<(&SPKSummaryRecord, usize, usize), EphemerisError>

Returns the summary given the name of the summary record if that summary has data defined at the requested epoch and the SPK where this name was found to be valid at that epoch.

pub fn spk_summary_at_epoch( &self, id: i32, epoch: Epoch, ) -> Result<(&SPKSummaryRecord, usize, usize), EphemerisError>

Returns the summary given the name of the summary record if that summary has data defined at the requested epoch

pub fn spk_summary_from_name( &self, name: &str, ) -> Result<(&SPKSummaryRecord, usize, usize), EphemerisError>

Returns the most recently loaded summary by its name, if any with that ID are available

pub fn spk_summary( &self, id: i32, ) -> Result<(&SPKSummaryRecord, usize, usize), EphemerisError>

Returns the most recently loaded summary by its ID, if any with that ID are available

§

impl Almanac

pub fn spk_summaries( &self, id: i32, ) -> Result<Vec<SPKSummaryRecord>, EphemerisError>

Returns a vector of the summaries whose ID matches the desired id, in the order in which they will be used, i.e. in reverse loading order.

§Warning

This function performs a memory allocation.

:type id: int :rtype: typing.List

pub fn spk_domain(&self, id: i32) -> Result<(Epoch, Epoch), EphemerisError>

Returns the applicable domain of the request id, i.e. start and end epoch that the provided id has loaded data.

:type id: int :rtype: typing.Tuple

Examples found in repository?
examples/02_jwst_covar_monte_carlo/main.rs (line 54)
26fn main() -> Result<(), Box<dyn Error>> {
27    pel::init();
28    // Dynamics models require planetary constants and ephemerides to be defined.
29    // Let's start by grabbing those by using ANISE's latest MetaAlmanac.
30    // For details, refer to https://github.com/nyx-space/anise/blob/master/data/latest.dhall.
31
32    // Download the regularly update of the James Webb Space Telescope reconstucted (or definitive) ephemeris.
33    // Refer to https://naif.jpl.nasa.gov/pub/naif/JWST/kernels/spk/aareadme.txt for details.
34    let mut latest_jwst_ephem = MetaFile {
35        uri: "https://naif.jpl.nasa.gov/pub/naif/JWST/kernels/spk/jwst_rec.bsp".to_string(),
36        crc32: None,
37    };
38    latest_jwst_ephem.process(true)?;
39
40    // Load this ephem in the general Almanac we're using for this analysis.
41    let almanac = Arc::new(
42        MetaAlmanac::latest()
43            .map_err(Box::new)?
44            .load_from_metafile(latest_jwst_ephem, true)?,
45    );
46
47    // By loading this ephemeris file in the ANISE GUI or ANISE CLI, we can find the NAIF ID of the JWST
48    // in the BSP. We need this ID in order to query the ephemeris.
49    const JWST_NAIF_ID: i32 = -170;
50    // Let's build a frame in the J2000 orientation centered on the JWST.
51    const JWST_J2000: Frame = Frame::from_ephem_j2000(JWST_NAIF_ID);
52
53    // Since the ephemeris file is updated regularly, we'll just grab the latest state in the ephem.
54    let (earliest_epoch, latest_epoch) = almanac.spk_domain(JWST_NAIF_ID)?;
55    println!("JWST defined from {earliest_epoch} to {latest_epoch}");
56    // Fetch the state, printing it in the Earth J2000 frame.
57    let jwst_orbit = almanac.transform(JWST_J2000, EARTH_J2000, latest_epoch, None)?;
58    println!("{jwst_orbit:x}");
59
60    // Build the spacecraft
61    // SRP area assumed to be the full sunshield and mass if 6200.0 kg, c.f. https://webb.nasa.gov/content/about/faqs/facts.html
62    // SRP Coefficient of reflectivity assumed to be that of Kapton, i.e. 2 - 0.44 = 1.56, table 1 from https://amostech.com/TechnicalPapers/2018/Poster/Bengtson.pdf
63    let jwst = Spacecraft::builder()
64        .orbit(jwst_orbit)
65        .srp(SRPData {
66            area_m2: 21.197 * 14.162,
67            coeff_reflectivity: 1.56,
68        })
69        .mass(Mass::from_dry_mass(6200.0))
70        .build();
71
72    // Build up the spacecraft uncertainty builder.
73    // We can use the spacecraft uncertainty structure to build this up.
74    // We start by specifying the nominal state (as defined above), then the uncertainty in position and velocity
75    // in the RIC frame. We could also specify the Cr, Cd, and mass uncertainties, but these aren't accounted for until
76    // Nyx can also estimate the deviation of the spacecraft parameters.
77    let jwst_uncertainty = SpacecraftUncertainty::builder()
78        .nominal(jwst)
79        .frame(LocalFrame::RIC)
80        .x_km(0.5)
81        .y_km(0.3)
82        .z_km(1.5)
83        .vx_km_s(1e-4)
84        .vy_km_s(0.6e-3)
85        .vz_km_s(3e-3)
86        .build();
87
88    println!("{jwst_uncertainty}");
89
90    // Build the Kalman filter estimate.
91    // Note that we could have used the KfEstimate structure directly (as seen throughout the OD integration tests)
92    // but this approach requires quite a bit more boilerplate code.
93    let jwst_estimate = jwst_uncertainty.to_estimate()?;
94
95    // Set up the spacecraft dynamics.
96    // We'll use the point masses of the Earth, Sun, Jupiter (barycenter, because it's in the DE440), and the Moon.
97    // We'll also enable solar radiation pressure since the James Webb has a huge and highly reflective sun shield.
98
99    let orbital_dyn = OrbitalDynamics::point_masses(vec![MOON, SUN, JUPITER_BARYCENTER]);
100    let srp_dyn = SolarPressure::new(vec![EARTH_J2000, MOON_J2000], almanac.clone())?;
101
102    // Finalize setting up the dynamics.
103    let dynamics = SpacecraftDynamics::from_model(orbital_dyn, srp_dyn);
104
105    // Build the propagator set up to use for the whole analysis.
106    let setup = Propagator::default(dynamics);
107
108    // All of the analysis will use this duration.
109    let prediction_duration = 6.5 * Unit::Day;
110
111    // === Covariance mapping ===
112    // For the covariance mapping / prediction, we'll use the common orbit determination approach.
113    // This is done by setting up a spacecraft Kalman filter OD process, and predicting for the analysis duration.
114
115    // Build the propagation instance for the OD process.
116    let odp = SpacecraftKalmanOD::new(
117        setup.clone(),
118        KalmanVariant::DeviationTracking,
119        None,
120        BTreeMap::new(),
121        almanac.clone(),
122    );
123
124    // The prediction step is 1 minute by default, configured in the OD process, i.e. how often we want to know the covariance.
125    assert_eq!(odp.max_step, 1_i64.minutes());
126    // Finally, predict, and export the trajectory with covariance to a parquet file.
127    let od_sol = odp.predict_for(jwst_estimate, prediction_duration)?;
128    od_sol.to_parquet("./02_jwst_covar_map.parquet", ExportCfg::default())?;
129
130    // === Monte Carlo framework ===
131    // Nyx comes with a complete multi-threaded Monte Carlo frame. It's blazing fast.
132
133    let my_mc = MonteCarlo::new(
134        jwst, // Nominal state
135        jwst_estimate.to_random_variable()?,
136        "02_jwst".to_string(), // Scenario name
137        None, // No specific seed specified, so one will be drawn from the computer's entropy.
138    );
139
140    let num_runs = 5_000;
141    let rslts = my_mc.run_until_epoch(
142        setup,
143        almanac.clone(),
144        jwst.epoch() + prediction_duration,
145        num_runs,
146    );
147
148    assert_eq!(rslts.runs.len(), num_runs);
149    // Finally, export these results, computing the eclipse percentage for all of these results.
150
151    // For all of the resulting trajectories, we'll want to compute the percentage of penumbra and umbra.
152    let eclipse_loc = EclipseLocator::cislunar(almanac.clone());
153    let umbra_event = eclipse_loc.to_umbra_event();
154    let penumbra_event = eclipse_loc.to_penumbra_event();
155
156    rslts.to_parquet(
157        "02_jwst_monte_carlo.parquet",
158        Some(vec![&umbra_event, &penumbra_event]),
159        ExportCfg::default(),
160        almanac,
161    )?;
162
163    Ok(())
164}

pub fn spk_domains( &self, ) -> Result<HashMap<i32, (Epoch, Epoch)>, EphemerisError>

Returns a map of each loaded SPK ID to its domain validity.

§Warning

This function performs a memory allocation.

:rtype: typing.Dict

§

impl Almanac

pub fn transform( &self, target_frame: Frame, observer_frame: Frame, epoch: Epoch, ab_corr: Option<Aberration>, ) -> Result<CartesianState, AlmanacError>

Returns the Cartesian state needed to transform the from_frame to the to_frame.

§SPICE Compatibility

This function is the SPICE equivalent of spkezr: spkezr(TARGET_ID, EPOCH_TDB_S, ORIENTATION_ID, ABERRATION, OBSERVER_ID) In ANISE, the TARGET_ID and ORIENTATION are provided in the first argument (TARGET_FRAME), as that frame includes BOTH the target ID and the orientation of that target. The EPOCH_TDB_S is the epoch in the TDB time system, which is computed in ANISE using Hifitime. THe ABERRATION is computed by providing the optional Aberration flag. Finally, the OBSERVER argument is replaced by OBSERVER_FRAME: if the OBSERVER_FRAME argument has the same orientation as the TARGET_FRAME, then this call will return exactly the same data as the spkerz SPICE call.

§Note

The units will be those of the underlying ephemeris data (typically km and km/s)

Examples found in repository?
examples/02_jwst_covar_monte_carlo/main.rs (line 57)
26fn main() -> Result<(), Box<dyn Error>> {
27    pel::init();
28    // Dynamics models require planetary constants and ephemerides to be defined.
29    // Let's start by grabbing those by using ANISE's latest MetaAlmanac.
30    // For details, refer to https://github.com/nyx-space/anise/blob/master/data/latest.dhall.
31
32    // Download the regularly update of the James Webb Space Telescope reconstucted (or definitive) ephemeris.
33    // Refer to https://naif.jpl.nasa.gov/pub/naif/JWST/kernels/spk/aareadme.txt for details.
34    let mut latest_jwst_ephem = MetaFile {
35        uri: "https://naif.jpl.nasa.gov/pub/naif/JWST/kernels/spk/jwst_rec.bsp".to_string(),
36        crc32: None,
37    };
38    latest_jwst_ephem.process(true)?;
39
40    // Load this ephem in the general Almanac we're using for this analysis.
41    let almanac = Arc::new(
42        MetaAlmanac::latest()
43            .map_err(Box::new)?
44            .load_from_metafile(latest_jwst_ephem, true)?,
45    );
46
47    // By loading this ephemeris file in the ANISE GUI or ANISE CLI, we can find the NAIF ID of the JWST
48    // in the BSP. We need this ID in order to query the ephemeris.
49    const JWST_NAIF_ID: i32 = -170;
50    // Let's build a frame in the J2000 orientation centered on the JWST.
51    const JWST_J2000: Frame = Frame::from_ephem_j2000(JWST_NAIF_ID);
52
53    // Since the ephemeris file is updated regularly, we'll just grab the latest state in the ephem.
54    let (earliest_epoch, latest_epoch) = almanac.spk_domain(JWST_NAIF_ID)?;
55    println!("JWST defined from {earliest_epoch} to {latest_epoch}");
56    // Fetch the state, printing it in the Earth J2000 frame.
57    let jwst_orbit = almanac.transform(JWST_J2000, EARTH_J2000, latest_epoch, None)?;
58    println!("{jwst_orbit:x}");
59
60    // Build the spacecraft
61    // SRP area assumed to be the full sunshield and mass if 6200.0 kg, c.f. https://webb.nasa.gov/content/about/faqs/facts.html
62    // SRP Coefficient of reflectivity assumed to be that of Kapton, i.e. 2 - 0.44 = 1.56, table 1 from https://amostech.com/TechnicalPapers/2018/Poster/Bengtson.pdf
63    let jwst = Spacecraft::builder()
64        .orbit(jwst_orbit)
65        .srp(SRPData {
66            area_m2: 21.197 * 14.162,
67            coeff_reflectivity: 1.56,
68        })
69        .mass(Mass::from_dry_mass(6200.0))
70        .build();
71
72    // Build up the spacecraft uncertainty builder.
73    // We can use the spacecraft uncertainty structure to build this up.
74    // We start by specifying the nominal state (as defined above), then the uncertainty in position and velocity
75    // in the RIC frame. We could also specify the Cr, Cd, and mass uncertainties, but these aren't accounted for until
76    // Nyx can also estimate the deviation of the spacecraft parameters.
77    let jwst_uncertainty = SpacecraftUncertainty::builder()
78        .nominal(jwst)
79        .frame(LocalFrame::RIC)
80        .x_km(0.5)
81        .y_km(0.3)
82        .z_km(1.5)
83        .vx_km_s(1e-4)
84        .vy_km_s(0.6e-3)
85        .vz_km_s(3e-3)
86        .build();
87
88    println!("{jwst_uncertainty}");
89
90    // Build the Kalman filter estimate.
91    // Note that we could have used the KfEstimate structure directly (as seen throughout the OD integration tests)
92    // but this approach requires quite a bit more boilerplate code.
93    let jwst_estimate = jwst_uncertainty.to_estimate()?;
94
95    // Set up the spacecraft dynamics.
96    // We'll use the point masses of the Earth, Sun, Jupiter (barycenter, because it's in the DE440), and the Moon.
97    // We'll also enable solar radiation pressure since the James Webb has a huge and highly reflective sun shield.
98
99    let orbital_dyn = OrbitalDynamics::point_masses(vec![MOON, SUN, JUPITER_BARYCENTER]);
100    let srp_dyn = SolarPressure::new(vec![EARTH_J2000, MOON_J2000], almanac.clone())?;
101
102    // Finalize setting up the dynamics.
103    let dynamics = SpacecraftDynamics::from_model(orbital_dyn, srp_dyn);
104
105    // Build the propagator set up to use for the whole analysis.
106    let setup = Propagator::default(dynamics);
107
108    // All of the analysis will use this duration.
109    let prediction_duration = 6.5 * Unit::Day;
110
111    // === Covariance mapping ===
112    // For the covariance mapping / prediction, we'll use the common orbit determination approach.
113    // This is done by setting up a spacecraft Kalman filter OD process, and predicting for the analysis duration.
114
115    // Build the propagation instance for the OD process.
116    let odp = SpacecraftKalmanOD::new(
117        setup.clone(),
118        KalmanVariant::DeviationTracking,
119        None,
120        BTreeMap::new(),
121        almanac.clone(),
122    );
123
124    // The prediction step is 1 minute by default, configured in the OD process, i.e. how often we want to know the covariance.
125    assert_eq!(odp.max_step, 1_i64.minutes());
126    // Finally, predict, and export the trajectory with covariance to a parquet file.
127    let od_sol = odp.predict_for(jwst_estimate, prediction_duration)?;
128    od_sol.to_parquet("./02_jwst_covar_map.parquet", ExportCfg::default())?;
129
130    // === Monte Carlo framework ===
131    // Nyx comes with a complete multi-threaded Monte Carlo frame. It's blazing fast.
132
133    let my_mc = MonteCarlo::new(
134        jwst, // Nominal state
135        jwst_estimate.to_random_variable()?,
136        "02_jwst".to_string(), // Scenario name
137        None, // No specific seed specified, so one will be drawn from the computer's entropy.
138    );
139
140    let num_runs = 5_000;
141    let rslts = my_mc.run_until_epoch(
142        setup,
143        almanac.clone(),
144        jwst.epoch() + prediction_duration,
145        num_runs,
146    );
147
148    assert_eq!(rslts.runs.len(), num_runs);
149    // Finally, export these results, computing the eclipse percentage for all of these results.
150
151    // For all of the resulting trajectories, we'll want to compute the percentage of penumbra and umbra.
152    let eclipse_loc = EclipseLocator::cislunar(almanac.clone());
153    let umbra_event = eclipse_loc.to_umbra_event();
154    let penumbra_event = eclipse_loc.to_penumbra_event();
155
156    rslts.to_parquet(
157        "02_jwst_monte_carlo.parquet",
158        Some(vec![&umbra_event, &penumbra_event]),
159        ExportCfg::default(),
160        almanac,
161    )?;
162
163    Ok(())
164}

pub fn transform_to( &self, state: CartesianState, observer_frame: Frame, ab_corr: Option<Aberration>, ) -> Result<CartesianState, AlmanacError>

Returns the provided state as seen from the observer frame, given the aberration.

Examples found in repository?
examples/05_cislunar_spacecraft_link_od/main.rs (line 78)
34fn main() -> Result<(), Box<dyn Error>> {
35    pel::init();
36
37    // ====================== //
38    // === ALMANAC SET UP === //
39    // ====================== //
40
41    let manifest_dir =
42        PathBuf::from(std::env::var("CARGO_MANIFEST_DIR").unwrap_or(".".to_string()));
43
44    let out = manifest_dir.join("data/04_output/");
45
46    let almanac = Arc::new(
47        Almanac::new(
48            &manifest_dir
49                .join("data/01_planetary/pck08.pca")
50                .to_string_lossy(),
51        )
52        .unwrap()
53        .load(
54            &manifest_dir
55                .join("data/01_planetary/de440s.bsp")
56                .to_string_lossy(),
57        )
58        .unwrap(),
59    );
60
61    let eme2k = almanac.frame_from_uid(EARTH_J2000).unwrap();
62    let moon_iau = almanac.frame_from_uid(IAU_MOON_FRAME).unwrap();
63
64    let epoch = Epoch::from_gregorian_tai(2021, 5, 29, 19, 51, 16, 852_000);
65    let nrho = Orbit::cartesian(
66        166_473.631_302_239_7,
67        -274_715.487_253_382_7,
68        -211_233.210_176_686_7,
69        0.933_451_604_520_018_4,
70        0.436_775_046_841_900_9,
71        -0.082_211_021_250_348_95,
72        epoch,
73        eme2k,
74    );
75
76    let tx_nrho_sc = Spacecraft::from(nrho);
77
78    let state_luna = almanac.transform_to(nrho, MOON_J2000, None).unwrap();
79    println!("Start state (dynamics: Earth, Moon, Sun gravity):\n{state_luna}");
80
81    let bodies = vec![EARTH, SUN];
82    let dynamics = SpacecraftDynamics::new(OrbitalDynamics::point_masses(bodies));
83
84    let setup = Propagator::rk89(
85        dynamics,
86        IntegratorOptions::builder().max_step(0.5.minutes()).build(),
87    );
88
89    /* == Propagate the NRHO vehicle == */
90    let prop_time = 1.1 * state_luna.period().unwrap();
91
92    let (nrho_final, mut tx_traj) = setup
93        .with(tx_nrho_sc, almanac.clone())
94        .for_duration_with_traj(prop_time)
95        .unwrap();
96
97    tx_traj.name = Some("NRHO Tx SC".to_string());
98
99    println!("{tx_traj}");
100
101    /* == Propagate an LLO vehicle == */
102    let llo_orbit =
103        Orbit::try_keplerian_altitude(110.0, 1e-4, 90.0, 0.0, 0.0, 0.0, epoch, moon_iau).unwrap();
104
105    let llo_sc = Spacecraft::builder().orbit(llo_orbit).build();
106
107    let (_, llo_traj) = setup
108        .with(llo_sc, almanac.clone())
109        .until_epoch_with_traj(nrho_final.epoch())
110        .unwrap();
111
112    // Export the subset of the first two hours.
113    llo_traj
114        .clone()
115        .filter_by_offset(..2.hours())
116        .to_parquet_simple(out.join("05_caps_llo_truth.pq"), almanac.clone())?;
117
118    /* == Setup the interlink == */
119
120    let mut measurement_types = IndexSet::new();
121    measurement_types.insert(MeasurementType::Range);
122    measurement_types.insert(MeasurementType::Doppler);
123
124    let mut stochastics = IndexMap::new();
125
126    let sa45_csac_allan_dev = 1e-11;
127
128    stochastics.insert(
129        MeasurementType::Range,
130        StochasticNoise::from_hardware_range_km(
131            sa45_csac_allan_dev,
132            10.0.seconds(),
133            link_specific::ChipRate::StandardT4B,
134            link_specific::SN0::Average,
135        ),
136    );
137
138    stochastics.insert(
139        MeasurementType::Doppler,
140        StochasticNoise::from_hardware_doppler_km_s(
141            sa45_csac_allan_dev,
142            10.0.seconds(),
143            link_specific::CarrierFreq::SBand,
144            link_specific::CN0::Average,
145        ),
146    );
147
148    let interlink = InterlinkTxSpacecraft {
149        traj: tx_traj,
150        measurement_types,
151        integration_time: None,
152        timestamp_noise_s: None,
153        ab_corr: Aberration::LT,
154        stochastic_noises: Some(stochastics),
155    };
156
157    // Devices are the transmitter, which is our NRHO vehicle.
158    let mut devices = BTreeMap::new();
159    devices.insert("NRHO Tx SC".to_string(), interlink);
160
161    let mut configs = BTreeMap::new();
162    configs.insert(
163        "NRHO Tx SC".to_string(),
164        TrkConfig::builder()
165            .strands(vec![Strand {
166                start: epoch,
167                end: nrho_final.epoch(),
168            }])
169            .build(),
170    );
171
172    let mut trk_sim =
173        TrackingArcSim::with_seed(devices.clone(), llo_traj.clone(), configs, 0).unwrap();
174    println!("{trk_sim}");
175
176    let trk_data = trk_sim.generate_measurements(almanac.clone()).unwrap();
177    println!("{trk_data}");
178
179    trk_data
180        .to_parquet_simple(out.clone().join("nrho_interlink_msr.pq"))
181        .unwrap();
182
183    // Run a truth OD where we estimate the LLO position
184    let llo_uncertainty = SpacecraftUncertainty::builder()
185        .nominal(llo_sc)
186        .x_km(1.0)
187        .y_km(1.0)
188        .z_km(1.0)
189        .vx_km_s(1e-3)
190        .vy_km_s(1e-3)
191        .vz_km_s(1e-3)
192        .build();
193
194    let mut proc_devices = devices.clone();
195
196    // Define the initial estimate, randomized, seed for reproducibility
197    let mut initial_estimate = llo_uncertainty.to_estimate_randomized(Some(0)).unwrap();
198    // Inflate the covariance -- https://github.com/nyx-space/nyx/issues/339
199    initial_estimate.covar *= 2.5;
200
201    // Increase the noise in the devices to accept more measurements.
202
203    for link in proc_devices.values_mut() {
204        for noise in &mut link.stochastic_noises.as_mut().unwrap().values_mut() {
205            *noise.white_noise.as_mut().unwrap() *= 3.0;
206        }
207    }
208
209    let init_err = initial_estimate
210        .orbital_state()
211        .ric_difference(&llo_orbit)
212        .unwrap();
213
214    println!("initial estimate:\n{initial_estimate}");
215    println!("RIC errors = {init_err}",);
216
217    let odp = InterlinkKalmanOD::new(
218        setup.clone(),
219        KalmanVariant::ReferenceUpdate,
220        Some(ResidRejectCrit::default()),
221        proc_devices,
222        almanac.clone(),
223    );
224
225    // Shrink the data to process.
226    let arc = trk_data.filter_by_offset(..2.hours());
227
228    let od_sol = odp.process_arc(initial_estimate, &arc).unwrap();
229
230    println!("{od_sol}");
231
232    od_sol
233        .to_parquet(
234            out.join(format!("05_caps_interlink_od_sol.pq")),
235            ExportCfg::default(),
236        )
237        .unwrap();
238
239    let od_traj = od_sol.to_traj().unwrap();
240
241    od_traj
242        .ric_diff_to_parquet(
243            &llo_traj,
244            out.join(format!("05_caps_interlink_llo_est_error.pq")),
245            ExportCfg::default(),
246        )
247        .unwrap();
248
249    let final_est = od_sol.estimates.last().unwrap();
250    assert!(final_est.within_3sigma(), "should be within 3 sigma");
251
252    println!("ESTIMATE\n{final_est:x}\n");
253    let truth = llo_traj.at(final_est.epoch()).unwrap();
254    println!("TRUTH\n{truth:x}");
255
256    let final_err = truth
257        .orbit
258        .ric_difference(&final_est.orbital_state())
259        .unwrap();
260    println!("ERROR {final_err}");
261
262    // Build the residuals versus reference plot.
263    let rvr_sol = odp
264        .process_arc(initial_estimate, &arc.resid_vs_ref_check())
265        .unwrap();
266
267    rvr_sol
268        .to_parquet(
269            out.join(format!("05_caps_interlink_resid_v_ref.pq")),
270            ExportCfg::default(),
271        )
272        .unwrap();
273
274    let final_rvr = rvr_sol.estimates.last().unwrap();
275
276    println!("RMAG error {:.3} m", final_err.rmag_km() * 1e3);
277    println!(
278        "Pure prop error {:.3} m",
279        final_rvr
280            .orbital_state()
281            .ric_difference(&final_est.orbital_state())
282            .unwrap()
283            .rmag_km()
284            * 1e3
285    );
286
287    Ok(())
288}
More examples
Hide additional examples
examples/03_geo_analysis/drift.rs (line 54)
26fn main() -> Result<(), Box<dyn Error>> {
27    pel::init();
28    // Dynamics models require planetary constants and ephemerides to be defined.
29    // Let's start by grabbing those by using ANISE's latest MetaAlmanac.
30    // This will automatically download the DE440s planetary ephemeris,
31    // the daily-updated Earth Orientation Parameters, the high fidelity Moon orientation
32    // parameters (for the Moon Mean Earth and Moon Principal Axes frames), and the PCK11
33    // planetary constants kernels.
34    // For details, refer to https://github.com/nyx-space/anise/blob/master/data/latest.dhall.
35    // Note that we place the Almanac into an Arc so we can clone it cheaply and provide read-only
36    // references to many functions.
37    let almanac = Arc::new(MetaAlmanac::latest().map_err(Box::new)?);
38    // Define the orbit epoch
39    let epoch = Epoch::from_gregorian_utc_hms(2024, 2, 29, 12, 13, 14);
40
41    // Define the orbit.
42    // First we need to fetch the Earth J2000 from information from the Almanac.
43    // This allows the frame to include the gravitational parameters and the shape of the Earth,
44    // defined as a tri-axial ellipoid. Note that this shape can be changed manually or in the Almanac
45    // by loading a different set of planetary constants.
46    let earth_j2000 = almanac.frame_from_uid(EARTH_J2000)?;
47
48    // Placing this GEO bird just above Colorado.
49    // In theory, the eccentricity is zero, but in practice, it's about 1e-5 to 1e-6 at best.
50    let orbit = Orbit::try_keplerian(42164.0, 1e-5, 0., 163.0, 75.0, 0.0, epoch, earth_j2000)?;
51    // Print in in Keplerian form.
52    println!("{orbit:x}");
53
54    let state_bf = almanac.transform_to(orbit, IAU_EARTH_FRAME, None)?;
55    let (orig_lat_deg, orig_long_deg, orig_alt_km) = state_bf.latlongalt()?;
56
57    // Nyx is used for high fidelity propagation, not Keplerian propagation as above.
58    // Nyx only propagates Spacecraft at the moment, which allows it to account for acceleration
59    // models such as solar radiation pressure.
60
61    // Let's build a cubesat sized spacecraft, with an SRP area of 10 cm^2 and a mass of 9.6 kg.
62    let sc = Spacecraft::builder()
63        .orbit(orbit)
64        .mass(Mass::from_dry_mass(9.60))
65        .srp(SRPData {
66            area_m2: 10e-4,
67            coeff_reflectivity: 1.1,
68        })
69        .build();
70    println!("{sc:x}");
71
72    // Set up the spacecraft dynamics.
73
74    // Specify that the orbital dynamics must account for the graviational pull of the Moon and the Sun.
75    // The gravity of the Earth will also be accounted for since the spaceraft in an Earth orbit.
76    let mut orbital_dyn = OrbitalDynamics::point_masses(vec![MOON, SUN]);
77
78    // We want to include the spherical harmonics, so let's download the gravitational data from the Nyx Cloud.
79    // We're using the JGM3 model here, which is the default in GMAT.
80    let mut jgm3_meta = MetaFile {
81        uri: "http://public-data.nyxspace.com/nyx/models/JGM3.cof.gz".to_string(),
82        crc32: Some(0xF446F027), // Specifying the CRC32 avoids redownloading it if it's cached.
83    };
84    // And let's download it if we don't have it yet.
85    jgm3_meta.process(true)?;
86
87    // Build the spherical harmonics.
88    // The harmonics must be computed in the body fixed frame.
89    // We're using the long term prediction of the Earth centered Earth fixed frame, IAU Earth.
90    let harmonics_21x21 = Harmonics::from_stor(
91        almanac.frame_from_uid(IAU_EARTH_FRAME)?,
92        HarmonicsMem::from_cof(&jgm3_meta.uri, 21, 21, true).unwrap(),
93    );
94
95    // Include the spherical harmonics into the orbital dynamics.
96    orbital_dyn.accel_models.push(harmonics_21x21);
97
98    // We define the solar radiation pressure, using the default solar flux and accounting only
99    // for the eclipsing caused by the Earth and Moon.
100    let srp_dyn = SolarPressure::new(vec![EARTH_J2000, MOON_J2000], almanac.clone())?;
101
102    // Finalize setting up the dynamics, specifying the force models (orbital_dyn) separately from the
103    // acceleration models (SRP in this case). Use `from_models` to specify multiple accel models.
104    let dynamics = SpacecraftDynamics::from_model(orbital_dyn, srp_dyn);
105
106    println!("{dynamics}");
107
108    // Finally, let's propagate this orbit to the same epoch as above.
109    // The first returned value is the spacecraft state at the final epoch.
110    // The second value is the full trajectory where the step size is variable step used by the propagator.
111    let (future_sc, trajectory) = Propagator::default(dynamics)
112        .with(sc, almanac.clone())
113        .until_epoch_with_traj(epoch + Unit::Century * 0.03)?;
114
115    println!("=== High fidelity propagation ===");
116    println!(
117        "SMA changed by {:.3} km",
118        orbit.sma_km()? - future_sc.orbit.sma_km()?
119    );
120    println!(
121        "ECC changed by {:.6}",
122        orbit.ecc()? - future_sc.orbit.ecc()?
123    );
124    println!(
125        "INC changed by {:.3e} deg",
126        orbit.inc_deg()? - future_sc.orbit.inc_deg()?
127    );
128    println!(
129        "RAAN changed by {:.3} deg",
130        orbit.raan_deg()? - future_sc.orbit.raan_deg()?
131    );
132    println!(
133        "AOP changed by {:.3} deg",
134        orbit.aop_deg()? - future_sc.orbit.aop_deg()?
135    );
136    println!(
137        "TA changed by {:.3} deg",
138        orbit.ta_deg()? - future_sc.orbit.ta_deg()?
139    );
140
141    // We also have access to the full trajectory throughout the propagation.
142    println!("{trajectory}");
143
144    println!("Spacecraft params after 3 years without active control:\n{future_sc:x}");
145
146    // With the trajectory, let's build a few data products.
147
148    // 1. Export the trajectory as a parquet file, which includes the Keplerian orbital elements.
149
150    let analysis_step = Unit::Minute * 5;
151
152    trajectory.to_parquet(
153        "./03_geo_hf_prop.parquet",
154        Some(vec![
155            &EclipseLocator::cislunar(almanac.clone()).to_penumbra_event()
156        ]),
157        ExportCfg::builder().step(analysis_step).build(),
158        almanac.clone(),
159    )?;
160
161    // 2. Compute the latitude, longitude, and altitude throughout the trajectory by rotating the spacecraft position into the Earth body fixed frame.
162
163    // We iterate over the trajectory, grabbing a state every two minutes.
164    let mut offset_s = vec![];
165    let mut epoch_str = vec![];
166    let mut longitude_deg = vec![];
167    let mut latitude_deg = vec![];
168    let mut altitude_km = vec![];
169
170    for state in trajectory.every(analysis_step) {
171        // Convert the GEO bird state into the body fixed frame, and keep track of its latitude, longitude, and altitude.
172        // These define the GEO stationkeeping box.
173
174        let this_epoch = state.epoch();
175
176        offset_s.push((this_epoch - orbit.epoch).to_seconds());
177        epoch_str.push(this_epoch.to_isoformat());
178
179        let state_bf = almanac.transform_to(state.orbit, IAU_EARTH_FRAME, None)?;
180        let (lat_deg, long_deg, alt_km) = state_bf.latlongalt()?;
181        longitude_deg.push(long_deg);
182        latitude_deg.push(lat_deg);
183        altitude_km.push(alt_km);
184    }
185
186    println!(
187        "Longitude changed by {:.3} deg -- Box is 0.1 deg E-W",
188        orig_long_deg - longitude_deg.last().unwrap()
189    );
190
191    println!(
192        "Latitude changed by {:.3} deg -- Box is 0.05 deg N-S",
193        orig_lat_deg - latitude_deg.last().unwrap()
194    );
195
196    println!(
197        "Altitude changed by {:.3} km -- Box is 30 km",
198        orig_alt_km - altitude_km.last().unwrap()
199    );
200
201    // Build the station keeping data frame.
202    let mut sk_df = df!(
203        "Offset (s)" => offset_s.clone(),
204        "Epoch (UTC)" => epoch_str.clone(),
205        "Longitude E-W (deg)" => longitude_deg,
206        "Latitude N-S (deg)" => latitude_deg,
207        "Altitude (km)" => altitude_km,
208
209    )?;
210
211    // Create a file to write the Parquet to
212    let file = File::create("./03_geo_lla.parquet").expect("Could not create file");
213
214    // Create a ParquetWriter and write the DataFrame to the file
215    ParquetWriter::new(file).finish(&mut sk_df)?;
216
217    Ok(())
218}

pub fn state_of( &self, object: i32, observer: Frame, epoch: Epoch, ab_corr: Option<Aberration>, ) -> Result<CartesianState, AlmanacError>

Returns the Cartesian state of the object as seen from the provided observer frame (essentially spkezr).

§Note

The units will be those of the underlying ephemeris data (typically km and km/s)

pub fn spk_ezr( &self, target: i32, epoch: Epoch, frame: i32, observer: i32, ab_corr: Option<Aberration>, ) -> Result<CartesianState, AlmanacError>

Alias fo SPICE’s spkezr where the inputs must be the NAIF IDs of the objects and frames with the caveat that the aberration is moved to the last positional argument.

pub fn transform_state_to( &self, position: Matrix<f64, Const<3>, Const<1>, ArrayStorage<f64, 3, 1>>, velocity: Matrix<f64, Const<3>, Const<1>, ArrayStorage<f64, 3, 1>>, from_frame: Frame, to_frame: Frame, epoch: Epoch, ab_corr: Option<Aberration>, distance_unit: LengthUnit, time_unit: Unit, ) -> Result<CartesianState, AlmanacError>

Translates a state with its origin (to_frame) and given its units (distance_unit, time_unit), returns that state with respect to the requested frame

WARNING: This function only performs the translation and no rotation whatsoever. Use the transform_state_to function instead to include rotations.

pub fn unit_vector( &self, target_frame: Frame, observer_frame: Frame, epoch: Epoch, ab_corr: Option<Aberration>, ) -> Result<Matrix<f64, Const<3>, Const<1>, ArrayStorage<f64, 3, 1>>, AlmanacError>

Returns the unitary 3D vector between two Frames (solid bodies) at desired Epoch

pub fn sun_unit_vector( &self, epoch: Epoch, observer_frame: Frame, ab_corr: Option<Aberration>, ) -> Result<Matrix<f64, Const<3>, Const<1>, ArrayStorage<f64, 3, 1>>, AlmanacError>

Returns the unitary 3D vector between desired Frame (solid body) and the Sun at desired Epoch

pub fn earth_sun_unit_vector( &self, epoch: Epoch, ab_corr: Option<Aberration>, ) -> Result<Matrix<f64, Const<3>, Const<1>, ArrayStorage<f64, 3, 1>>, AlmanacError>

Returns the unitary 3D vector between Earth and Sun at desired Epoch.

§

impl Almanac

pub fn load_from_metafile( &self, metafile: MetaFile, autodelete: bool, ) -> Result<Almanac, AlmanacError>

Load from the provided MetaFile, downloading it if necessary. Set autodelete to true to automatically delete lock files. Lock files are important in multi-threaded loads.

Examples found in repository?
examples/02_jwst_covar_monte_carlo/main.rs (line 44)
26fn main() -> Result<(), Box<dyn Error>> {
27    pel::init();
28    // Dynamics models require planetary constants and ephemerides to be defined.
29    // Let's start by grabbing those by using ANISE's latest MetaAlmanac.
30    // For details, refer to https://github.com/nyx-space/anise/blob/master/data/latest.dhall.
31
32    // Download the regularly update of the James Webb Space Telescope reconstucted (or definitive) ephemeris.
33    // Refer to https://naif.jpl.nasa.gov/pub/naif/JWST/kernels/spk/aareadme.txt for details.
34    let mut latest_jwst_ephem = MetaFile {
35        uri: "https://naif.jpl.nasa.gov/pub/naif/JWST/kernels/spk/jwst_rec.bsp".to_string(),
36        crc32: None,
37    };
38    latest_jwst_ephem.process(true)?;
39
40    // Load this ephem in the general Almanac we're using for this analysis.
41    let almanac = Arc::new(
42        MetaAlmanac::latest()
43            .map_err(Box::new)?
44            .load_from_metafile(latest_jwst_ephem, true)?,
45    );
46
47    // By loading this ephemeris file in the ANISE GUI or ANISE CLI, we can find the NAIF ID of the JWST
48    // in the BSP. We need this ID in order to query the ephemeris.
49    const JWST_NAIF_ID: i32 = -170;
50    // Let's build a frame in the J2000 orientation centered on the JWST.
51    const JWST_J2000: Frame = Frame::from_ephem_j2000(JWST_NAIF_ID);
52
53    // Since the ephemeris file is updated regularly, we'll just grab the latest state in the ephem.
54    let (earliest_epoch, latest_epoch) = almanac.spk_domain(JWST_NAIF_ID)?;
55    println!("JWST defined from {earliest_epoch} to {latest_epoch}");
56    // Fetch the state, printing it in the Earth J2000 frame.
57    let jwst_orbit = almanac.transform(JWST_J2000, EARTH_J2000, latest_epoch, None)?;
58    println!("{jwst_orbit:x}");
59
60    // Build the spacecraft
61    // SRP area assumed to be the full sunshield and mass if 6200.0 kg, c.f. https://webb.nasa.gov/content/about/faqs/facts.html
62    // SRP Coefficient of reflectivity assumed to be that of Kapton, i.e. 2 - 0.44 = 1.56, table 1 from https://amostech.com/TechnicalPapers/2018/Poster/Bengtson.pdf
63    let jwst = Spacecraft::builder()
64        .orbit(jwst_orbit)
65        .srp(SRPData {
66            area_m2: 21.197 * 14.162,
67            coeff_reflectivity: 1.56,
68        })
69        .mass(Mass::from_dry_mass(6200.0))
70        .build();
71
72    // Build up the spacecraft uncertainty builder.
73    // We can use the spacecraft uncertainty structure to build this up.
74    // We start by specifying the nominal state (as defined above), then the uncertainty in position and velocity
75    // in the RIC frame. We could also specify the Cr, Cd, and mass uncertainties, but these aren't accounted for until
76    // Nyx can also estimate the deviation of the spacecraft parameters.
77    let jwst_uncertainty = SpacecraftUncertainty::builder()
78        .nominal(jwst)
79        .frame(LocalFrame::RIC)
80        .x_km(0.5)
81        .y_km(0.3)
82        .z_km(1.5)
83        .vx_km_s(1e-4)
84        .vy_km_s(0.6e-3)
85        .vz_km_s(3e-3)
86        .build();
87
88    println!("{jwst_uncertainty}");
89
90    // Build the Kalman filter estimate.
91    // Note that we could have used the KfEstimate structure directly (as seen throughout the OD integration tests)
92    // but this approach requires quite a bit more boilerplate code.
93    let jwst_estimate = jwst_uncertainty.to_estimate()?;
94
95    // Set up the spacecraft dynamics.
96    // We'll use the point masses of the Earth, Sun, Jupiter (barycenter, because it's in the DE440), and the Moon.
97    // We'll also enable solar radiation pressure since the James Webb has a huge and highly reflective sun shield.
98
99    let orbital_dyn = OrbitalDynamics::point_masses(vec![MOON, SUN, JUPITER_BARYCENTER]);
100    let srp_dyn = SolarPressure::new(vec![EARTH_J2000, MOON_J2000], almanac.clone())?;
101
102    // Finalize setting up the dynamics.
103    let dynamics = SpacecraftDynamics::from_model(orbital_dyn, srp_dyn);
104
105    // Build the propagator set up to use for the whole analysis.
106    let setup = Propagator::default(dynamics);
107
108    // All of the analysis will use this duration.
109    let prediction_duration = 6.5 * Unit::Day;
110
111    // === Covariance mapping ===
112    // For the covariance mapping / prediction, we'll use the common orbit determination approach.
113    // This is done by setting up a spacecraft Kalman filter OD process, and predicting for the analysis duration.
114
115    // Build the propagation instance for the OD process.
116    let odp = SpacecraftKalmanOD::new(
117        setup.clone(),
118        KalmanVariant::DeviationTracking,
119        None,
120        BTreeMap::new(),
121        almanac.clone(),
122    );
123
124    // The prediction step is 1 minute by default, configured in the OD process, i.e. how often we want to know the covariance.
125    assert_eq!(odp.max_step, 1_i64.minutes());
126    // Finally, predict, and export the trajectory with covariance to a parquet file.
127    let od_sol = odp.predict_for(jwst_estimate, prediction_duration)?;
128    od_sol.to_parquet("./02_jwst_covar_map.parquet", ExportCfg::default())?;
129
130    // === Monte Carlo framework ===
131    // Nyx comes with a complete multi-threaded Monte Carlo frame. It's blazing fast.
132
133    let my_mc = MonteCarlo::new(
134        jwst, // Nominal state
135        jwst_estimate.to_random_variable()?,
136        "02_jwst".to_string(), // Scenario name
137        None, // No specific seed specified, so one will be drawn from the computer's entropy.
138    );
139
140    let num_runs = 5_000;
141    let rslts = my_mc.run_until_epoch(
142        setup,
143        almanac.clone(),
144        jwst.epoch() + prediction_duration,
145        num_runs,
146    );
147
148    assert_eq!(rslts.runs.len(), num_runs);
149    // Finally, export these results, computing the eclipse percentage for all of these results.
150
151    // For all of the resulting trajectories, we'll want to compute the percentage of penumbra and umbra.
152    let eclipse_loc = EclipseLocator::cislunar(almanac.clone());
153    let umbra_event = eclipse_loc.to_umbra_event();
154    let penumbra_event = eclipse_loc.to_penumbra_event();
155
156    rslts.to_parquet(
157        "02_jwst_monte_carlo.parquet",
158        Some(vec![&umbra_event, &penumbra_event]),
159        ExportCfg::default(),
160        almanac,
161    )?;
162
163    Ok(())
164}
§

impl Almanac

pub fn new(path: &str) -> Result<Almanac, AlmanacError>

Initializes a new Almanac from the provided file path, guessing at the file type

Examples found in repository?
examples/05_cislunar_spacecraft_link_od/main.rs (lines 47-51)
34fn main() -> Result<(), Box<dyn Error>> {
35    pel::init();
36
37    // ====================== //
38    // === ALMANAC SET UP === //
39    // ====================== //
40
41    let manifest_dir =
42        PathBuf::from(std::env::var("CARGO_MANIFEST_DIR").unwrap_or(".".to_string()));
43
44    let out = manifest_dir.join("data/04_output/");
45
46    let almanac = Arc::new(
47        Almanac::new(
48            &manifest_dir
49                .join("data/01_planetary/pck08.pca")
50                .to_string_lossy(),
51        )
52        .unwrap()
53        .load(
54            &manifest_dir
55                .join("data/01_planetary/de440s.bsp")
56                .to_string_lossy(),
57        )
58        .unwrap(),
59    );
60
61    let eme2k = almanac.frame_from_uid(EARTH_J2000).unwrap();
62    let moon_iau = almanac.frame_from_uid(IAU_MOON_FRAME).unwrap();
63
64    let epoch = Epoch::from_gregorian_tai(2021, 5, 29, 19, 51, 16, 852_000);
65    let nrho = Orbit::cartesian(
66        166_473.631_302_239_7,
67        -274_715.487_253_382_7,
68        -211_233.210_176_686_7,
69        0.933_451_604_520_018_4,
70        0.436_775_046_841_900_9,
71        -0.082_211_021_250_348_95,
72        epoch,
73        eme2k,
74    );
75
76    let tx_nrho_sc = Spacecraft::from(nrho);
77
78    let state_luna = almanac.transform_to(nrho, MOON_J2000, None).unwrap();
79    println!("Start state (dynamics: Earth, Moon, Sun gravity):\n{state_luna}");
80
81    let bodies = vec![EARTH, SUN];
82    let dynamics = SpacecraftDynamics::new(OrbitalDynamics::point_masses(bodies));
83
84    let setup = Propagator::rk89(
85        dynamics,
86        IntegratorOptions::builder().max_step(0.5.minutes()).build(),
87    );
88
89    /* == Propagate the NRHO vehicle == */
90    let prop_time = 1.1 * state_luna.period().unwrap();
91
92    let (nrho_final, mut tx_traj) = setup
93        .with(tx_nrho_sc, almanac.clone())
94        .for_duration_with_traj(prop_time)
95        .unwrap();
96
97    tx_traj.name = Some("NRHO Tx SC".to_string());
98
99    println!("{tx_traj}");
100
101    /* == Propagate an LLO vehicle == */
102    let llo_orbit =
103        Orbit::try_keplerian_altitude(110.0, 1e-4, 90.0, 0.0, 0.0, 0.0, epoch, moon_iau).unwrap();
104
105    let llo_sc = Spacecraft::builder().orbit(llo_orbit).build();
106
107    let (_, llo_traj) = setup
108        .with(llo_sc, almanac.clone())
109        .until_epoch_with_traj(nrho_final.epoch())
110        .unwrap();
111
112    // Export the subset of the first two hours.
113    llo_traj
114        .clone()
115        .filter_by_offset(..2.hours())
116        .to_parquet_simple(out.join("05_caps_llo_truth.pq"), almanac.clone())?;
117
118    /* == Setup the interlink == */
119
120    let mut measurement_types = IndexSet::new();
121    measurement_types.insert(MeasurementType::Range);
122    measurement_types.insert(MeasurementType::Doppler);
123
124    let mut stochastics = IndexMap::new();
125
126    let sa45_csac_allan_dev = 1e-11;
127
128    stochastics.insert(
129        MeasurementType::Range,
130        StochasticNoise::from_hardware_range_km(
131            sa45_csac_allan_dev,
132            10.0.seconds(),
133            link_specific::ChipRate::StandardT4B,
134            link_specific::SN0::Average,
135        ),
136    );
137
138    stochastics.insert(
139        MeasurementType::Doppler,
140        StochasticNoise::from_hardware_doppler_km_s(
141            sa45_csac_allan_dev,
142            10.0.seconds(),
143            link_specific::CarrierFreq::SBand,
144            link_specific::CN0::Average,
145        ),
146    );
147
148    let interlink = InterlinkTxSpacecraft {
149        traj: tx_traj,
150        measurement_types,
151        integration_time: None,
152        timestamp_noise_s: None,
153        ab_corr: Aberration::LT,
154        stochastic_noises: Some(stochastics),
155    };
156
157    // Devices are the transmitter, which is our NRHO vehicle.
158    let mut devices = BTreeMap::new();
159    devices.insert("NRHO Tx SC".to_string(), interlink);
160
161    let mut configs = BTreeMap::new();
162    configs.insert(
163        "NRHO Tx SC".to_string(),
164        TrkConfig::builder()
165            .strands(vec![Strand {
166                start: epoch,
167                end: nrho_final.epoch(),
168            }])
169            .build(),
170    );
171
172    let mut trk_sim =
173        TrackingArcSim::with_seed(devices.clone(), llo_traj.clone(), configs, 0).unwrap();
174    println!("{trk_sim}");
175
176    let trk_data = trk_sim.generate_measurements(almanac.clone()).unwrap();
177    println!("{trk_data}");
178
179    trk_data
180        .to_parquet_simple(out.clone().join("nrho_interlink_msr.pq"))
181        .unwrap();
182
183    // Run a truth OD where we estimate the LLO position
184    let llo_uncertainty = SpacecraftUncertainty::builder()
185        .nominal(llo_sc)
186        .x_km(1.0)
187        .y_km(1.0)
188        .z_km(1.0)
189        .vx_km_s(1e-3)
190        .vy_km_s(1e-3)
191        .vz_km_s(1e-3)
192        .build();
193
194    let mut proc_devices = devices.clone();
195
196    // Define the initial estimate, randomized, seed for reproducibility
197    let mut initial_estimate = llo_uncertainty.to_estimate_randomized(Some(0)).unwrap();
198    // Inflate the covariance -- https://github.com/nyx-space/nyx/issues/339
199    initial_estimate.covar *= 2.5;
200
201    // Increase the noise in the devices to accept more measurements.
202
203    for link in proc_devices.values_mut() {
204        for noise in &mut link.stochastic_noises.as_mut().unwrap().values_mut() {
205            *noise.white_noise.as_mut().unwrap() *= 3.0;
206        }
207    }
208
209    let init_err = initial_estimate
210        .orbital_state()
211        .ric_difference(&llo_orbit)
212        .unwrap();
213
214    println!("initial estimate:\n{initial_estimate}");
215    println!("RIC errors = {init_err}",);
216
217    let odp = InterlinkKalmanOD::new(
218        setup.clone(),
219        KalmanVariant::ReferenceUpdate,
220        Some(ResidRejectCrit::default()),
221        proc_devices,
222        almanac.clone(),
223    );
224
225    // Shrink the data to process.
226    let arc = trk_data.filter_by_offset(..2.hours());
227
228    let od_sol = odp.process_arc(initial_estimate, &arc).unwrap();
229
230    println!("{od_sol}");
231
232    od_sol
233        .to_parquet(
234            out.join(format!("05_caps_interlink_od_sol.pq")),
235            ExportCfg::default(),
236        )
237        .unwrap();
238
239    let od_traj = od_sol.to_traj().unwrap();
240
241    od_traj
242        .ric_diff_to_parquet(
243            &llo_traj,
244            out.join(format!("05_caps_interlink_llo_est_error.pq")),
245            ExportCfg::default(),
246        )
247        .unwrap();
248
249    let final_est = od_sol.estimates.last().unwrap();
250    assert!(final_est.within_3sigma(), "should be within 3 sigma");
251
252    println!("ESTIMATE\n{final_est:x}\n");
253    let truth = llo_traj.at(final_est.epoch()).unwrap();
254    println!("TRUTH\n{truth:x}");
255
256    let final_err = truth
257        .orbit
258        .ric_difference(&final_est.orbital_state())
259        .unwrap();
260    println!("ERROR {final_err}");
261
262    // Build the residuals versus reference plot.
263    let rvr_sol = odp
264        .process_arc(initial_estimate, &arc.resid_vs_ref_check())
265        .unwrap();
266
267    rvr_sol
268        .to_parquet(
269            out.join(format!("05_caps_interlink_resid_v_ref.pq")),
270            ExportCfg::default(),
271        )
272        .unwrap();
273
274    let final_rvr = rvr_sol.estimates.last().unwrap();
275
276    println!("RMAG error {:.3} m", final_err.rmag_km() * 1e3);
277    println!(
278        "Pure prop error {:.3} m",
279        final_rvr
280            .orbital_state()
281            .ric_difference(&final_est.orbital_state())
282            .unwrap()
283            .rmag_km()
284            * 1e3
285    );
286
287    Ok(())
288}

pub fn with_spacecraft_data( &self, spacecraft_data: DataSet<SpacecraftData, anise::::structure::SpacecraftDataSet::{constant#0}>, ) -> Almanac

Loads the provided spacecraft data into a clone of this original Almanac.

pub fn with_euler_parameters( &self, ep_dataset: DataSet<EulerParameter, anise::::structure::EulerParameterDataSet::{constant#0}>, ) -> Almanac

Loads the provided Euler parameter data into a clone of this original Almanac.

pub fn load_from_bytes(&self, bytes: Bytes) -> Result<Almanac, AlmanacError>

Loads the provides bytes as one of the data types supported in ANISE.

pub fn load(&self, path: &str) -> Result<Almanac, AlmanacError>

Generic function that tries to load the provided path guessing to the file type.

Examples found in repository?
examples/05_cislunar_spacecraft_link_od/main.rs (lines 53-57)
34fn main() -> Result<(), Box<dyn Error>> {
35    pel::init();
36
37    // ====================== //
38    // === ALMANAC SET UP === //
39    // ====================== //
40
41    let manifest_dir =
42        PathBuf::from(std::env::var("CARGO_MANIFEST_DIR").unwrap_or(".".to_string()));
43
44    let out = manifest_dir.join("data/04_output/");
45
46    let almanac = Arc::new(
47        Almanac::new(
48            &manifest_dir
49                .join("data/01_planetary/pck08.pca")
50                .to_string_lossy(),
51        )
52        .unwrap()
53        .load(
54            &manifest_dir
55                .join("data/01_planetary/de440s.bsp")
56                .to_string_lossy(),
57        )
58        .unwrap(),
59    );
60
61    let eme2k = almanac.frame_from_uid(EARTH_J2000).unwrap();
62    let moon_iau = almanac.frame_from_uid(IAU_MOON_FRAME).unwrap();
63
64    let epoch = Epoch::from_gregorian_tai(2021, 5, 29, 19, 51, 16, 852_000);
65    let nrho = Orbit::cartesian(
66        166_473.631_302_239_7,
67        -274_715.487_253_382_7,
68        -211_233.210_176_686_7,
69        0.933_451_604_520_018_4,
70        0.436_775_046_841_900_9,
71        -0.082_211_021_250_348_95,
72        epoch,
73        eme2k,
74    );
75
76    let tx_nrho_sc = Spacecraft::from(nrho);
77
78    let state_luna = almanac.transform_to(nrho, MOON_J2000, None).unwrap();
79    println!("Start state (dynamics: Earth, Moon, Sun gravity):\n{state_luna}");
80
81    let bodies = vec![EARTH, SUN];
82    let dynamics = SpacecraftDynamics::new(OrbitalDynamics::point_masses(bodies));
83
84    let setup = Propagator::rk89(
85        dynamics,
86        IntegratorOptions::builder().max_step(0.5.minutes()).build(),
87    );
88
89    /* == Propagate the NRHO vehicle == */
90    let prop_time = 1.1 * state_luna.period().unwrap();
91
92    let (nrho_final, mut tx_traj) = setup
93        .with(tx_nrho_sc, almanac.clone())
94        .for_duration_with_traj(prop_time)
95        .unwrap();
96
97    tx_traj.name = Some("NRHO Tx SC".to_string());
98
99    println!("{tx_traj}");
100
101    /* == Propagate an LLO vehicle == */
102    let llo_orbit =
103        Orbit::try_keplerian_altitude(110.0, 1e-4, 90.0, 0.0, 0.0, 0.0, epoch, moon_iau).unwrap();
104
105    let llo_sc = Spacecraft::builder().orbit(llo_orbit).build();
106
107    let (_, llo_traj) = setup
108        .with(llo_sc, almanac.clone())
109        .until_epoch_with_traj(nrho_final.epoch())
110        .unwrap();
111
112    // Export the subset of the first two hours.
113    llo_traj
114        .clone()
115        .filter_by_offset(..2.hours())
116        .to_parquet_simple(out.join("05_caps_llo_truth.pq"), almanac.clone())?;
117
118    /* == Setup the interlink == */
119
120    let mut measurement_types = IndexSet::new();
121    measurement_types.insert(MeasurementType::Range);
122    measurement_types.insert(MeasurementType::Doppler);
123
124    let mut stochastics = IndexMap::new();
125
126    let sa45_csac_allan_dev = 1e-11;
127
128    stochastics.insert(
129        MeasurementType::Range,
130        StochasticNoise::from_hardware_range_km(
131            sa45_csac_allan_dev,
132            10.0.seconds(),
133            link_specific::ChipRate::StandardT4B,
134            link_specific::SN0::Average,
135        ),
136    );
137
138    stochastics.insert(
139        MeasurementType::Doppler,
140        StochasticNoise::from_hardware_doppler_km_s(
141            sa45_csac_allan_dev,
142            10.0.seconds(),
143            link_specific::CarrierFreq::SBand,
144            link_specific::CN0::Average,
145        ),
146    );
147
148    let interlink = InterlinkTxSpacecraft {
149        traj: tx_traj,
150        measurement_types,
151        integration_time: None,
152        timestamp_noise_s: None,
153        ab_corr: Aberration::LT,
154        stochastic_noises: Some(stochastics),
155    };
156
157    // Devices are the transmitter, which is our NRHO vehicle.
158    let mut devices = BTreeMap::new();
159    devices.insert("NRHO Tx SC".to_string(), interlink);
160
161    let mut configs = BTreeMap::new();
162    configs.insert(
163        "NRHO Tx SC".to_string(),
164        TrkConfig::builder()
165            .strands(vec![Strand {
166                start: epoch,
167                end: nrho_final.epoch(),
168            }])
169            .build(),
170    );
171
172    let mut trk_sim =
173        TrackingArcSim::with_seed(devices.clone(), llo_traj.clone(), configs, 0).unwrap();
174    println!("{trk_sim}");
175
176    let trk_data = trk_sim.generate_measurements(almanac.clone()).unwrap();
177    println!("{trk_data}");
178
179    trk_data
180        .to_parquet_simple(out.clone().join("nrho_interlink_msr.pq"))
181        .unwrap();
182
183    // Run a truth OD where we estimate the LLO position
184    let llo_uncertainty = SpacecraftUncertainty::builder()
185        .nominal(llo_sc)
186        .x_km(1.0)
187        .y_km(1.0)
188        .z_km(1.0)
189        .vx_km_s(1e-3)
190        .vy_km_s(1e-3)
191        .vz_km_s(1e-3)
192        .build();
193
194    let mut proc_devices = devices.clone();
195
196    // Define the initial estimate, randomized, seed for reproducibility
197    let mut initial_estimate = llo_uncertainty.to_estimate_randomized(Some(0)).unwrap();
198    // Inflate the covariance -- https://github.com/nyx-space/nyx/issues/339
199    initial_estimate.covar *= 2.5;
200
201    // Increase the noise in the devices to accept more measurements.
202
203    for link in proc_devices.values_mut() {
204        for noise in &mut link.stochastic_noises.as_mut().unwrap().values_mut() {
205            *noise.white_noise.as_mut().unwrap() *= 3.0;
206        }
207    }
208
209    let init_err = initial_estimate
210        .orbital_state()
211        .ric_difference(&llo_orbit)
212        .unwrap();
213
214    println!("initial estimate:\n{initial_estimate}");
215    println!("RIC errors = {init_err}",);
216
217    let odp = InterlinkKalmanOD::new(
218        setup.clone(),
219        KalmanVariant::ReferenceUpdate,
220        Some(ResidRejectCrit::default()),
221        proc_devices,
222        almanac.clone(),
223    );
224
225    // Shrink the data to process.
226    let arc = trk_data.filter_by_offset(..2.hours());
227
228    let od_sol = odp.process_arc(initial_estimate, &arc).unwrap();
229
230    println!("{od_sol}");
231
232    od_sol
233        .to_parquet(
234            out.join(format!("05_caps_interlink_od_sol.pq")),
235            ExportCfg::default(),
236        )
237        .unwrap();
238
239    let od_traj = od_sol.to_traj().unwrap();
240
241    od_traj
242        .ric_diff_to_parquet(
243            &llo_traj,
244            out.join(format!("05_caps_interlink_llo_est_error.pq")),
245            ExportCfg::default(),
246        )
247        .unwrap();
248
249    let final_est = od_sol.estimates.last().unwrap();
250    assert!(final_est.within_3sigma(), "should be within 3 sigma");
251
252    println!("ESTIMATE\n{final_est:x}\n");
253    let truth = llo_traj.at(final_est.epoch()).unwrap();
254    println!("TRUTH\n{truth:x}");
255
256    let final_err = truth
257        .orbit
258        .ric_difference(&final_est.orbital_state())
259        .unwrap();
260    println!("ERROR {final_err}");
261
262    // Build the residuals versus reference plot.
263    let rvr_sol = odp
264        .process_arc(initial_estimate, &arc.resid_vs_ref_check())
265        .unwrap();
266
267    rvr_sol
268        .to_parquet(
269            out.join(format!("05_caps_interlink_resid_v_ref.pq")),
270            ExportCfg::default(),
271        )
272        .unwrap();
273
274    let final_rvr = rvr_sol.estimates.last().unwrap();
275
276    println!("RMAG error {:.3} m", final_err.rmag_km() * 1e3);
277    println!(
278        "Pure prop error {:.3} m",
279        final_rvr
280            .orbital_state()
281            .ric_difference(&final_est.orbital_state())
282            .unwrap()
283            .rmag_km()
284            * 1e3
285    );
286
287    Ok(())
288}

pub fn describe( &self, spk: Option<bool>, bpc: Option<bool>, planetary: Option<bool>, eulerparams: Option<bool>, time_scale: Option<TimeScale>, round_time: Option<bool>, )

Pretty prints the description of this Almanac, showing everything by default. Default time scale is TDB. If any parameter is set to true, then nothing other than that will be printed.

§

impl Almanac

pub fn try_find_ephemeris_root(&self) -> Result<i32, EphemerisError>

Returns the root of all of the loaded ephemerides, typically this should be the Solar System Barycenter.

§Algorithm
  1. For each loaded SPK, iterated in reverse order (to mimic SPICE behavior)
  2. For each summary record in each SPK, follow the ephemeris branch all the way up until the end of this SPK or until the SSB.

pub fn ephemeris_path_to_root( &self, source: Frame, epoch: Epoch, ) -> Result<(usize, [Option<i32>; 8]), EphemerisError>

Try to construct the path from the source frame all the way to the root ephemeris of this context.

pub fn common_ephemeris_path( &self, from_frame: Frame, to_frame: Frame, epoch: Epoch, ) -> Result<(usize, [Option<i32>; 8], i32), EphemerisError>

Returns the ephemeris path between two frames and the common node. This may return a DisjointRoots error if the frames do not share a common root, which is considered a file integrity error.

§Example

If the “from” frame is Earth Barycenter whose path to the ANISE root is the following:

Solar System barycenter
╰─> Earth Moon Barycenter
    ╰─> Earth

And the “to” frame is Moon, whose path is:

Solar System barycenter
╰─> Earth Moon Barycenter
    ╰─> Moon
        ╰─> LRO

Then this function will return the path an array of hashes of up to [MAX_TREE_DEPTH] items. In this example, the array with the hashes of the “Earth Moon Barycenter” and “Moon”.

§Note

A proper ANISE file should only have a single root and if two paths are empty, then they should be the same frame. If a DisjointRoots error is reported here, it means that the ANISE file is invalid.

§Time complexity

This can likely be simplified as this as a time complexity of O(n×m) where n, m are the lengths of the paths from the ephemeris up to the root. This can probably be optimized to avoid rewinding the entire frame path up to the root frame

§

impl Almanac

pub fn translate_to_parent( &self, source: Frame, epoch: Epoch, ) -> Result<CartesianState, EphemerisError>

Performs the GEOMETRIC translation to the parent. Use translate_from_to for aberration.

:type source: Frame :type epoch: Epoch :rtype: Orbit

§

impl Almanac

pub fn translate( &self, target_frame: Frame, observer_frame: Frame, epoch: Epoch, ab_corr: Option<Aberration>, ) -> Result<CartesianState, EphemerisError>

Returns the Cartesian state of the target frame as seen from the observer frame at the provided epoch, and optionally given the aberration correction.

§SPICE Compatibility

This function is the SPICE equivalent of spkezr: spkezr(TARGET_ID, EPOCH_TDB_S, ORIENTATION_ID, ABERRATION, OBSERVER_ID) In ANISE, the TARGET_ID and ORIENTATION are provided in the first argument (TARGET_FRAME), as that frame includes BOTH the target ID and the orientation of that target. The EPOCH_TDB_S is the epoch in the TDB time system, which is computed in ANISE using Hifitime. THe ABERRATION is computed by providing the optional Aberration flag. Finally, the OBSERVER argument is replaced by OBSERVER_FRAME: if the OBSERVER_FRAME argument has the same orientation as the TARGET_FRAME, then this call will return exactly the same data as the spkerz SPICE call.

§Warning

This function only performs the translation and no rotation whatsoever. Use the transform function instead to include rotations.

§Note

This function performs a recursion of no more than twice the [MAX_TREE_DEPTH].

pub fn translate_geometric( &self, target_frame: Frame, observer_frame: Frame, epoch: Epoch, ) -> Result<CartesianState, EphemerisError>

Returns the geometric position vector, velocity vector, and acceleration vector needed to translate the from_frame to the to_frame, where the distance is in km, the velocity in km/s, and the acceleration in km/s^2.

pub fn translate_to( &self, state: CartesianState, observer_frame: Frame, ab_corr: Option<Aberration>, ) -> Result<CartesianState, EphemerisError>

Translates the provided Cartesian state into the requested observer frame

WARNING: This function only performs the translation and no rotation whatsoever. Use the transform_to function instead to include rotations.

pub fn translate_state_to( &self, position: Matrix<f64, Const<3>, Const<1>, ArrayStorage<f64, 3, 1>>, velocity: Matrix<f64, Const<3>, Const<1>, ArrayStorage<f64, 3, 1>>, from_frame: Frame, observer_frame: Frame, epoch: Epoch, ab_corr: Option<Aberration>, distance_unit: LengthUnit, time_unit: Unit, ) -> Result<CartesianState, EphemerisError>

Translates a state with its origin (to_frame) and given its units (distance_unit, time_unit), returns that state with respect to the requested frame

WARNING: This function only performs the translation and no rotation whatsoever. Use the transform_state_to function instead to include rotations.

§

impl Almanac

pub fn try_find_orientation_root(&self) -> Result<i32, OrientationError>

Returns the root of all of the loaded orientations (BPC or planetary), typically this should be J2000.

§Algorithm
  1. For each loaded BPC, iterated in reverse order (to mimic SPICE behavior)
  2. For each summary record in each BPC, follow the orientation branch all the way up until the end of this BPC or until the J2000.

pub fn orientation_path_to_root( &self, source: Frame, epoch: Epoch, ) -> Result<(usize, [Option<i32>; 8]), OrientationError>

Try to construct the path from the source frame all the way to the root orientation of this context.

pub fn common_orientation_path( &self, from_frame: Frame, to_frame: Frame, epoch: Epoch, ) -> Result<(usize, [Option<i32>; 8], i32), OrientationError>

Returns the orientation path between two frames and the common node. This may return a DisjointRoots error if the frames do not share a common root, which is considered a file integrity error.

§

impl Almanac

pub fn rotation_to_parent( &self, source: Frame, epoch: Epoch, ) -> Result<DCM, OrientationError>

Returns the direct cosine matrix (DCM) to rotate from the source to its parent in the orientation hierarchy at the provided epoch,

§Example

If the ephemeris stores position interpolation coefficients in kilometer but this function is called with millimeters as a distance unit, the output vectors will be in mm, mm/s, mm/s^2 respectively.

§Errors
  • As of now, some interpolation types are not supported, and if that were to happen, this would return an error.

WARNING: This function only performs the rotation and no translation whatsoever. Use the transform_to_parent_from function instead to include rotations.

§

impl Almanac

pub fn rotate( &self, from_frame: Frame, to_frame: Frame, epoch: Epoch, ) -> Result<DCM, OrientationError>

Returns the 6x6 DCM needed to rotation the from_frame to the to_frame.

§Warning

This function only performs the rotation and no translation whatsoever. Use the transform_from_to function instead to include rotations.

§Note

This function performs a recursion of no more than twice the MAX_TREE_DEPTH.

pub fn rotate_to( &self, state: CartesianState, observer_frame: Frame, ) -> Result<CartesianState, OrientationError>

Rotates the provided Cartesian state into the requested observer frame

WARNING: This function only performs the translation and no rotation whatsoever. Use the transform_to function instead to include rotations.

§

impl Almanac

pub fn rotate_state_to( &self, position: Matrix<f64, Const<3>, Const<1>, ArrayStorage<f64, 3, 1>>, velocity: Matrix<f64, Const<3>, Const<1>, ArrayStorage<f64, 3, 1>>, from_frame: Frame, to_frame: Frame, epoch: Epoch, distance_unit: LengthUnit, time_unit: Unit, ) -> Result<CartesianState, OrientationError>

Rotates a state with its origin (to_frame) and given its units (distance_unit, time_unit), returns that state with respect to the requested frame

WARNING: This function only performs the translation and no rotation whatsoever. Use the transform_state_to function instead to include rotations.

Trait Implementations§

§

impl Clone for Almanac

§

fn clone(&self) -> Almanac

Returns a duplicate of the value. Read more
1.0.0 · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
§

impl Default for Almanac

§

fn default() -> Almanac

Returns the “default value” for a type. Read more
§

impl Display for Almanac

§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<T> Pointable for T

§

const ALIGN: usize

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
§

impl<SS, SP> SupersetOf<SS> for SP
where SS: SubsetOf<SP>,

§

fn to_subset(&self) -> Option<SS>

The inverse inclusion map: attempts to construct self from the equivalent element of its superset. Read more
§

fn is_in_subset(&self) -> bool

Checks if self is actually part of its subset T (and can be converted to it).
§

fn to_subset_unchecked(&self) -> SS

Use with care! Same as self.to_subset but without any property checks. Always succeeds.
§

fn from_subset(element: &SS) -> SP

The inclusion map: converts self to the equivalent element of its superset.
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T> ToString for T
where T: Display + ?Sized,

Source§

fn to_string(&self) -> String

Converts the given value to a String. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

impl<T> Allocation for T
where T: RefUnwindSafe + Send + Sync,

§

impl<T> ErasedDestructor for T
where T: 'static,