Merge pull request #186 from nyx-space/174-moon-frame-simplifications

Moon frame simplifications + add loading from MetaFile into Almanac
nyx-space · Jan 27, 2024 · f413f5f · f413f5f
2 parents 9721abc + 2c2ce28
commit f413f5f
Show file tree

Hide file tree

Showing 40 changed files with 2,101 additions and 1,150 deletions.
diff --git a/.github/workflows/benchmarks.yml b/.github/workflows/benchmarks.yml
@@ -23,7 +23,7 @@ jobs:
           wget -O data/de430.bsp http://public-data.nyxspace.com/anise/de430.bsp
           wget -O data/de440s.bsp http://public-data.nyxspace.com/anise/de440s.bsp
           wget -O data/de440.bsp http://public-data.nyxspace.com/anise/de440.bsp
-          wget -O data/pck08.pca http://public-data.nyxspace.com/anise/pck08.pca
+          wget -O data/pck08.pca http://public-data.nyxspace.com/anise/v0.3/pck08.pca
           wget -O data/gmat-hermite.bsp http://public-data.nyxspace.com/anise/ci/gmat-hermite.bsp
           wget -O data/variable-seg-size-hermite.bsp http://public-data.nyxspace.com/anise/ci/variable-seg-size-hermite.bsp
           wget -O data/earth_latest_high_prec.bpc http://public-data.nyxspace.com/anise/ci/earth_latest_high_prec-2023-09-08.bpc

diff --git a/.github/workflows/python.yml b/.github/workflows/python.yml
@@ -33,8 +33,8 @@ jobs:
           wget -O data/de430.bsp http://public-data.nyxspace.com/anise/de430.bsp
           wget -O data/de440s.bsp http://public-data.nyxspace.com/anise/de440s.bsp
           wget -O data/de440.bsp http://public-data.nyxspace.com/anise/de440.bsp
-          wget -O data/pck08.pca http://public-data.nyxspace.com/anise/pck08.pca
-          wget -O data/pck11.pca http://public-data.nyxspace.com/anise/pck11.pca
+          wget -O data/pck08.pca http://public-data.nyxspace.com/anise/v0.3/pck08.pca
+          wget -O data/pck11.pca http://public-data.nyxspace.com/anise/v0.3/pck11.pca
 
       - uses: actions/setup-python@v4
         with:
@@ -196,8 +196,8 @@ jobs:
           wget -O data/de430.bsp http://public-data.nyxspace.com/anise/de430.bsp
           wget -O data/de440s.bsp http://public-data.nyxspace.com/anise/de440s.bsp
           wget -O data/de440.bsp http://public-data.nyxspace.com/anise/de440.bsp
-          wget -O data/pck08.pca http://public-data.nyxspace.com/anise/pck08.pca
-          wget -O data/pck11.pca http://public-data.nyxspace.com/anise/pck11.pca
+          wget -O data/pck08.pca http://public-data.nyxspace.com/anise/v0.3/pck08.pca
+          wget -O data/pck11.pca http://public-data.nyxspace.com/anise/v0.3/pck11.pca
 
       - name: Build sdist
         uses: PyO3/maturin-action@v1

diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml
@@ -40,8 +40,8 @@ jobs:
           wget -O data/de430.bsp http://public-data.nyxspace.com/anise/de430.bsp
           wget -O data/de440s.bsp http://public-data.nyxspace.com/anise/de440s.bsp
           wget -O data/de440.bsp http://public-data.nyxspace.com/anise/de440.bsp
-          wget -O data/pck08.pca http://public-data.nyxspace.com/anise/pck08.pca
-          wget -O data/pck11.pca http://public-data.nyxspace.com/anise/pck11.pca
+          wget -O data/pck08.pca http://public-data.nyxspace.com/anise/v0.3/pck08.pca
+          wget -O data/pck11.pca http://public-data.nyxspace.com/anise/v0.3/pck11.pca
           wget -O data/gmat-hermite.bsp http://public-data.nyxspace.com/anise/ci/gmat-hermite.bsp
           wget -O data/variable-seg-size-hermite.bsp http://public-data.nyxspace.com/anise/ci/variable-seg-size-hermite.bsp
           wget -O data/earth_latest_high_prec.bpc http://public-data.nyxspace.com/anise/ci/earth_latest_high_prec-2023-09-08.bpc
@@ -90,8 +90,8 @@ jobs:
           wget -O data/de430.bsp http://public-data.nyxspace.com/anise/de430.bsp
           wget -O data/de440s.bsp http://public-data.nyxspace.com/anise/de440s.bsp
           wget -O data/de440.bsp http://public-data.nyxspace.com/anise/de440.bsp
-          wget -O data/pck08.pca http://public-data.nyxspace.com/anise/pck08.pca
-          wget -O data/pck11.pca http://public-data.nyxspace.com/anise/pck11.pca
+          wget -O data/pck08.pca http://public-data.nyxspace.com/anise/v0.3/pck08.pca
+          wget -O data/pck11.pca http://public-data.nyxspace.com/anise/v0.3/pck11.pca
           wget -O data/gmat-hermite.bsp http://public-data.nyxspace.com/anise/ci/gmat-hermite.bsp
           wget -O data/variable-seg-size-hermite.bsp http://public-data.nyxspace.com/anise/ci/variable-seg-size-hermite.bsp
           wget -O data/earth_latest_high_prec.bpc http://public-data.nyxspace.com/anise/ci/earth_latest_high_prec-2023-09-08.bpc
@@ -153,8 +153,8 @@ jobs:
           wget -O data/de430.bsp http://public-data.nyxspace.com/anise/de430.bsp
           wget -O data/de440s.bsp http://public-data.nyxspace.com/anise/de440s.bsp
           wget -O data/de440.bsp http://public-data.nyxspace.com/anise/de440.bsp
-          wget -O data/pck08.pca http://public-data.nyxspace.com/anise/pck08.pca
-          wget -O data/pck11.pca http://public-data.nyxspace.com/anise/pck11.pca
+          wget -O data/pck08.pca http://public-data.nyxspace.com/anise/v0.3/pck08.pca
+          wget -O data/pck11.pca http://public-data.nyxspace.com/anise/v0.3/pck11.pca
           wget -O data/gmat-hermite.bsp http://public-data.nyxspace.com/anise/ci/gmat-hermite.bsp
           wget -O data/variable-seg-size-hermite.bsp http://public-data.nyxspace.com/anise/ci/variable-seg-size-hermite.bsp
           wget -O data/earth_latest_high_prec.bpc http://public-data.nyxspace.com/anise/ci/earth_latest_high_prec-2023-09-08.bpc
@@ -181,7 +181,7 @@ jobs:
           cargo llvm-cov test --no-report validate_jplde_de440s_no_aberration --features spkezr_validation -- --nocapture --ignored
           cargo llvm-cov test --no-report validate_jplde_de440s_aberration_lt --features spkezr_validation -- --nocapture --ignored
           cargo llvm-cov test --no-report validate_hermite_type13_from_gmat --features spkezr_validation -- --nocapture --ignored
-          cargo llvm-cov report --lcov > lcov.txt
+          cargo llvm-cov report --lcov > ../lcov.txt
         env:
           RUSTFLAGS: --cfg __ui_tests
 

diff --git a/README.md b/README.md
@@ -23,187 +23,44 @@ ANISE stands validated against the traditional SPICE toolkit, ensuring accuracy
 + **Frame safety**: ANISE checks all frames translations or rotations are physically valid before performing any computation, even internally.
 + **Auto-downloading capability**: ANISE simplifies your workflow by automatically downloading the latest Earth orientation parameters, or any other SPICE or ANISE file from a remote location, seamlessly integrating them into the `Almanac` for immediate use.
 
-## Validation
+## Interfaces
 
-[![ANISE Validation](https://github.com/nyx-space/anise/actions/workflows/rust.yml/badge.svg)](https://github.com/nyx-space/anise/actions/workflows/rust.yml)
+### Rust
 
-ANISE is validated by running the same queries in ANISE and in SPICE (single threaded) in the _Validation_ step linked above. This workflow validates 101,000 BSP queries in the DE440.BSP file, and 7305 queries each frame in the PCK08 file (every day for 20 years), along with thousands of rotations from Earth high precision BPC file.
+ANISE is developed in Rust, leveraging Rust's robust features such as memory safety, efficient concurrency handling, a superb test framework, and excellent error management. These capabilities ensure that all ANISE features are highly reliable and secure from the outset. Being native to Rust, these features are available first within the Rust ecosystem, offering cutting-edge functionality to Rust developers. They are then integrated into other interfaces. If there is a feature in Rust that has yet to be ported into the language of your choice, please open a Github issue.
 
-**Note:** The PCK data comes from the IAU Reports, which publishes angle, angle rate, and angle acceleration data, expressed in centuries past the J2000 reference epoch.
-ANISE uses Hifitime for time conversions. Hifitime's reliance solely on integers for all time computations eliminates the risk of rounding errors. In contrast, SPICE utilizes floating-point values, which introduces rounding errors in calculations like centuries past J2000. Consequently, you might observe a discrepancy of up to 1 millidegree in rotation angles between SPICE and ANISE. However, this difference is a testament to ANISE's superior precision.
-
-## Tutorials
+Refer to the [Rust README](./anise/README.md) for further details. The Rust API documentation is available on <https://docs.rs/anise/latest/anise/>.
 
 ### Python
 
-Refer to [Python README](./anise-py/README.md) for Juyter notebook tutorials in Python
-
-## Rust Usage
-
-Start using it by adding to your Rust project:
-
-```sh
-cargo add anise
-```
-
-### Frame Transformation of an Orbit
-
-ANISE provides the ability to create Cartesian states (also simply called `Orbit`s), calculate orbital elements from them in an error free way (computations that may fail return a `Result` type), and transform these states into other frames via the loaded context, called `Almanac`, which stores all of the SPICE and ANISE files you need.
-
-```rust
-use anise::prelude::*;
-// ANISE provides pre-built frames, but examples below show how to build them from their NAIF IDs.
-use anise::constants::frames::{EARTH_ITRF93, EARTH_J2000};
-
-// Initialize an empty Almanac
-let ctx = Almanac::default();
-
-// Load a SPK/BSP file
-let spk = SPK::load("../data/de440.bsp").unwrap();
-// Load the high precision ITRF93 kernel
-let bpc = BPC::load("../data/earth_latest_high_prec.bpc").unwrap();
-// Build the planetary constants file, which includes the gravitational parameters and the IAU low fidelity rotations
-use anise::naif::kpl::parser::convert_tpc;
-// Note that the PCK variable can also be serialized to disk to avoid having to rebuild it next time.
-let pck = convert_tpc("../data/pck00008.tpc", "../data/gm_de431.tpc").unwrap();
-
-// And add all of these to the Almanac context
-let almanac = ctx
-    .with_spk(spk)
-    .unwrap()
-    .with_bpc(bpc)
-    .unwrap()
-    .with_planetary_data(pck);
-
-// Let's build an orbit
-// Start by grabbing a copy of the frame.
-let eme2k = almanac.frame_from_uid(EARTH_J2000).unwrap();
-
-// Define an epoch, in TDB, but you may specify UTC, TT, TAI, GPST, and more.
-let epoch = Epoch::from_str("2021-10-29 12:34:56 TDB").unwrap();
-
-// Define the orbit from its Keplerian orbital elements.
-// Note that we must specify the frame of this orbit: ANISE checks all frames are valid before any translation or rotation, even internally.
-let orig_state = Orbit::keplerian(
-    8_191.93, 1e-6, 12.85, 306.614, 314.19, 99.887_7, epoch, eme2k,
-);
-
-// Transform that orbit into another frame.
-let state_itrf93 = almanac
-    .transform_to(orig_state, EARTH_ITRF93, None)
-    .unwrap();
-
-// The `:x` prints this orbit's Keplerian elements
-println!("{orig_state:x}");
-// The `:X` prints the prints the range, altitude, latitude, and longitude with respect to the planetocentric frame in floating point with units if frame is celestial,
-println!("{state_itrf93:X}");
-
-// Convert back
-let from_state_itrf93_to_eme2k = almanac
-    .transform_to(state_itrf93, EARTH_J2000, Aberration::NONE)
-    .unwrap();
-
-println!("{from_state_itrf93_to_eme2k}");
-
-// Check that our return data matches the original one exactly
-assert_eq!(orig_state, from_state_itrf93_to_eme2k);
-```
-
-### Load and query a PCK/BPC file (high fidelity rotation)
-
-```rust
-use anise::prelude::*;
-use anise::constants::frames::{EARTH_ITRF93, EME2000};
+Although ANISE is primarily developed in Rust, it offers first-class support for Python, recognizing that many users will interact with ANISE through its Python interface. This integration ensures that Python users can leverage most of ANISE's capabilities without compromise. If you encounter any limitations or missing features in the Python support, we encourage you to open a GitHub issue to help us improve the interface.
 
-let pck = "../data/earth_latest_high_prec.bpc";
+For Python-specific tutorials and resources, please refer to the [Python README](./anise-py/README.md), which includes Jupyter notebook tutorials tailored for Python users.
 
-let bpc = BPC::load(pck).unwrap();
-let almanac = Almanac::from_bpc(bpc).unwrap();
+### GUI
 
-// Load the useful frame constants
-use anise::constants::frames::*;
+ANISE provides a graphical interface to inspect SPK, BPC, and PCA (Planetary Constant ANISE) files. Allows you to check the start/end times of the segments (shown in whichever time scale you want, including UNIX UTC seconds).
 
-// Define an Epoch in the dynamical barycentric time scale
-let epoch = Epoch::from_str("2020-11-15 12:34:56.789 TDB").unwrap();
+Refer to the [GUI](./anise-gui/README.md) README for details.
 
-// Query for the DCM
-let dcm = almanac.rotate_from_to(EARTH_ITRF93, EME2000, epoch).unwrap();
-
-println!("{dcm}");
-```
-
-### Load and query a text PCK/KPL file (low fidelity rotation)
-
-```rust
-use anise::prelude::*;
-// Load the TPC converter, which will create the ANISE representation too, in ASN1 format, that you may reuse.
-use anise::naif::kpl::parser::convert_tpc;
-
-// Note that the ASN1 ANISE format for planetary data also stores the gravity parameters, so we must convert both at once into a single ANISE file.
-let planetary_data = convert_tpc("../data/pck00008.tpc", "../data/gm_de431.tpc").unwrap();
-
-let almanac = Almanac {
-    planetary_data,
-    ..Default::default()
-};
-
-// Load the useful frame constants
-use anise::constants::frames::*;
-
-// Define an Epoch in the dynamical barycentric time scale
-let epoch = Epoch::from_str("2020-11-15 12:34:56.789 TDB").unwrap();
-
-// Query for the DCM to the immediate parent
-let dcm = almanac.rotation_to_parent(IAU_VENUS_FRAME, epoch).unwrap();
-
-println!("{dcm}");
-```
-
-### Load and query an SPK/BSP file (ephemeris)
-
-```rust
-use anise::prelude::*;
-use anise::constants::frames::*;
-
-let spk = SPK::load("../data/de440s.bsp").unwrap();
-let ctx = Almanac::from_spk(spk).unwrap();
-
-// Define an Epoch in the dynamical barycentric time scale
-let epoch = Epoch::from_str("2020-11-15 12:34:56.789 TDB").unwrap();
-
-let state = ctx
-    .translate(
-        VENUS_J2000, // Target
-        EARTH_MOON_BARYCENTER_J2000, // Observer
-        epoch,
-        None,
-    )
-    .unwrap();
-
-println!("{state}");
-```
-
-## GUI
-
-ANISE comes with a GUI to inspect files. Allows you to check the start/end times of the segments (shown in whichever time scale you want, including UNIX UTC seconds)
-
-### Demos
-
-Inspect an SPK file ([video link](http://public-data.nyxspace.com/anise/demo/ANISE-SPK.webm)):
+## Validation
 
-![Inspect an SPK file](http://public-data.nyxspace.com/anise/demo/ANISE-SPK.gif)
+[![ANISE Validation](https://github.com/nyx-space/anise/actions/workflows/rust.yml/badge.svg)](https://github.com/nyx-space/anise/actions/workflows/rust.yml)
 
-Inspect an Binary PCK file (BPC) ([video link](http://public-data.nyxspace.com/anise/demo/ANISE-BPC.webm)):
+ANISE is validated by running the same queries in ANISE and in SPICE (single threaded) in the _Validation_ step linked above. This workflow validates 101,000 BSP queries in the DE440.BSP file, and 7305 queries each frame in the PCK08 file (every day for 20 years), along with thousands of rotations from Earth high precision BPC file.
 
-![Inspect an SPK file](http://public-data.nyxspace.com/anise/demo/ANISE-BPC.gif)
+**Note:** The PCK data comes from the IAU Reports, which publishes angle, angle rate, and angle acceleration data, expressed in centuries past the J2000 reference epoch.
+ANISE uses Hifitime for time conversions. Hifitime's reliance solely on integers for all time computations eliminates the risk of rounding errors. In contrast, SPICE utilizes floating-point values, which introduces rounding errors in calculations like centuries past J2000. Consequently, you might observe a discrepancy of up to 1 millidegree in rotation angles between SPICE and ANISE. However, this difference is a testament to ANISE's superior precision.
 
 ## Resources / Assets
 
 For convenience, Nyx Space provides a few important SPICE files on a public bucket:
 
 + [de440s.bsp](http://public-data.nyxspace.com/anise/de440s.bsp): JPL's latest ephemeris dataset from 1900 until 20250
 + [de440.bsp](http://public-data.nyxspace.com/anise/de440.bsp): JPL's latest long-term ephemeris dataset
-+ [pck08.pca](http://public-data.nyxspace.com/anise/pck08.pca): planetary constants ANISE (`pca`) kernel, built from the JPL gravitational data [gm_de431.tpc](http://public-data.nyxspace.com/anise/gm_de431.tpc) and JPL's plantary constants file [pck00008.tpc](http://public-data.nyxspace.com/anise/pck00008.tpc)
++ [pck08.pca](http://public-data.nyxspace.com/anise/v0.3/pck08.pca): planetary constants ANISE (`pca`) kernel, built from the JPL gravitational data [gm_de431.tpc](http://public-data.nyxspace.com/anise/gm_de431.tpc) and JPL's plantary constants file [pck00008.tpc](http://public-data.nyxspace.com/anise/pck00008.tpc)
++ [pck11.pca](http://public-data.nyxspace.com/anise/v0.3/pck11.pca): planetary constants ANISE (`pca`) kernel, built from the JPL gravitational data [gm_de431.tpc](http://public-data.nyxspace.com/anise/gm_de431.tpc) and JPL's plantary constants file [pck00011.tpc](http://public-data.nyxspace.com/anise/pck00011.tpc)
++ [moon_fk.epa](http://public-data.nyxspace.com/anise/v0.3/moon_fk.epa): Euler Parameter ANISE (`epa`) kernel, built from the JPL Moon Frame Kernel `moon_080317.txt`
 
 You may load any of these using the `load()` shortcut that will determine the file type upon loading, e.g. `let almanac = Almanac::new("pck08.pca").unwrap();` or in Python `almanac = Almanac("pck08.pca")`. To automatically download remote assets, from the Nyx Cloud or elsewhere, use the MetaAlmanac: `almanac = MetaAlmanac("ci_config.dhall").process()` in Python.
 

diff --git a/anise-gui/README.md b/anise-gui/README.md
@@ -1,10 +1,20 @@
 # ANISE GUI
 
-ANISE provides a graphical interface to inspect SPK, BPC, and PCA (Planetary Constant ANISE) files.
+ANISE provides a graphical interface to inspect SPK, BPC, and PCA (Planetary Constant ANISE) files. Allows you to check the start/end times of the segments (shown in whichever time scale you want, including UNIX UTC seconds).
 
-## Running
+**Latest binaries:** <https://github.com/nyx-space/anise/discussions/138>
 
-Best bet is to visit the [Discussions](https://github.com/nyx-space/anise/discussions) on ANISE and find the latest release for binaries for Linux, MacOS, and Windows.
+When updates are published, they'll be announced in the [Discussions](https://github.com/nyx-space/anise/discussions).
+
+## Demos
+
+Inspect an SPK file ([video link](http://public-data.nyxspace.com/anise/demo/ANISE-SPK.webm)):
+
+![Inspect an SPK file](http://public-data.nyxspace.com/anise/demo/ANISE-SPK.gif)
+
+Inspect an Binary PCK file (BPC) ([video link](http://public-data.nyxspace.com/anise/demo/ANISE-BPC.webm)):
+
+![Inspect an SPK file](http://public-data.nyxspace.com/anise/demo/ANISE-BPC.gif)
 
 ## Building
 

diff --git a/anise-py/README.md b/anise-py/README.md
@@ -24,12 +24,12 @@ ANISE stands validated against the traditional SPICE toolkit, ensuring accuracy
 
 ## Tutorials
 
-- [01 - Querying SPK files](./notebooks/Tutorial%2001%20-%20Querying%20SPK%20files.ipynb)
-- [02 - Loading remote and local files (MetaAlmanac)](./notebooks/Tutorial%2002%20-%20Loading%20remote%20SPICE%20and%20ANISE%20files%20(meta%20almanac).ipynb)
-- [03 - Defining and working with the orbit structure](./notebooks/Tutorial%2003%20-%20Defining%20and%20working%20with%20the%20Orbit%20structure.ipynb)
-- [04 - Computing azimuth, elevation, and range data (AER)](./notebooks/Tutorial%2004%20-%20Computing%20Azimuth%20Elevation%20and%20Range%20data.ipynb)
+- [01 - Querying SPK files](./tutorials/Tutorial%2001%20-%20Querying%20SPK%20files.ipynb)
+- [02 - Loading remote and local files (MetaAlmanac)](./tutorials/Tutorial%2002%20-%20Loading%20remote%20SPICE%20and%20ANISE%20files%20(meta%20almanac).ipynb)
+- [03 - Defining and working with the orbit structure](./tutorials/Tutorial%2003%20-%20Defining%20and%20working%20with%20the%20Orbit%20structure.ipynb)
+- [04 - Computing azimuth, elevation, and range data (AER)](./tutorials/Tutorial%2004%20-%20Computing%20Azimuth%20Elevation%20and%20Range%20data.ipynb)
 
-Note: The tutorials can be viewed in read-only form on [the Github repo](https://github.com/nyx-space/anise/tree/master/anise-py/notebooks).
+Note: The tutorials can be viewed in read-only form on [the Github repo](https://github.com/nyx-space/anise/tree/master/anise-py/tutorials).
 
 ## Usage