Merge pull request #328 from nyx-space/325-examples-howtos

Add examples / how-to

.github/ISSUE_TEMPLATE/documentation.md

@@ -7,37 +7,21 @@ assignees: ''
 
 ---
 
-## Description 
+## Description
 
 Please describe the issue or enhancement you want to report. Provide as much detail as possible to help us understand and address it.
 
-## Documentation type 
+## Documentation type
 
 Tell us which of the four Diátaxis documentation types this issue or enhancement relates to:
 
-- Tutorial
-- How-to guide  
-- Technical reference / Math Spec
-- Explanation
-
-## Affected area(s)
-
-For the selected documentation type, tell us what specific area(s) this issue relates to. Provide titles, page numbers, URLs or other locators. 
+- [ ] Tutorial
+- [ ] How-to guide
+- [ ] Technical reference / Math Spec
+- [ ] Explanation
 
 ## Expected or desired behavior
 
-Tell us what you expected to see in the documentation, or how you think it could be improved. For enhancements, describe the improvement you think could be made.
-
-## Additional context
-
-Provide any other context or screenshots that would help us understand the issue or enhancement.
-
-## Possible solutions (optional)
-
-If you have any suggestions for how to address the issue or implement the enhancement, provide them here. We appreciate any insights you have!
-
-## Who should review this?  
-
-Tag any individuals, teams, or roles that would likely need to review or address this issue for the specified documentation type.
+Tell us what you expected to see in the documentation, or how you think it could be improved. For enhancements, describe the improvement you think could be made, including URLs to the documentation if available.
 
-We will do our best to direct this to the appropriate people. Thank you for your feedback!
+<!-- Thank you for your feedback! -->

.github/workflows/rust.yaml

@@ -81,6 +81,11 @@ jobs:
       - name: Doc Test
         run: cargo test --doc
 
+      - name: Run examples
+        run: |
+          cargo run --example 01_orbit_prop --release
+          cargo run --example 02_jwst --release
+
   lints:
     name: Lints
     runs-on: ubuntu-latest

.gitignore

@@ -12,6 +12,7 @@ node_modules/
 *.venv*
 dist/
 *.parquet
+*.oem
 *.profraw
 lcov.txt
 .DS_Store

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "nyx-space"
 build = "build.rs"
-version = "2.0.0-beta.1"
+version = "2.0.0-rc"
 edition = "2021"
 authors = ["Christopher Rabotin <[email protected]>"]
 description = "A high-fidelity space mission toolkit, with orbit propagation, estimation and some systems engineering"
@@ -26,6 +26,7 @@ exclude = [
     "Dockerfile*",
     "rustfmt.toml",
     "tests/GMAT_scripts/*",
+    "*.png",
 ]
 
 [badges]
@@ -96,3 +97,11 @@ name = "nyx_space"
 # For flamegraph -- https://github.com/flamegraph-rs/flamegraph
 linker = "/usr/bin/clang"
 rustflags = ["-Clink-arg=-fuse-ld=lld", "-Clink-arg=-Wl,--no-rosegment"]
+
+[[example]]
+name = "01_orbit_prop"
+path = "examples/01_orbit_prop/main.rs"
+
+[[example]]
+name = "02_jwst"
+path = "examples/02_jwst_covar_monte_carlo/main.rs"

README.md

@@ -1,18 +1,48 @@
-# Nyx: Revolutionizing Flight Dynamics
+# Nyx: Comprehensive Spaceflight Dynamics
 
-**Blazing fast from mission concept to operations, and automation.** -- [https://nyxspace.com/](https://nyxspace.com/)
+[**Empowering flight dynamics engineers with open-source software**](https://nyxspace.com/)
 
-Nyx is provided under the AGPLv3 License. By using this software, you assume responsibility for adhering to the license. Refer to [the pricing page](https://nyxspace.com/pricing/) for an FAQ on the AGPLv3 license.
+Nyx is revolutionizing the field of flight dynamics engineering as a powerful, open-source tool for mission design and orbit determination. From trajectory optimization to orbit estimation, Nyx is built for speed, automation, and scalability. It dramatically reduces simulation time compared to commercial products, and integrates seamlessly into automated workflows across various platforms.
+
+**Nyx has proven mission-critical reliability, already contributing to the success of three lunar missions.**
+
+![Static Badge](https://img.shields.io/badge/Nyx_Space-Website-orange?link=https%3A%2F%2Fnyxspace.com%2F)
+![Contact Form](https://img.shields.io/badge/Nyx_Space-Contact-orange?link=https%3A%2F%2F7ug5imdtt8v.typeform.com%2Fto%2FneFvVW3p)
 
 [![nyx-space on crates.io][cratesio-image]][cratesio]
 [![nyx-space on docs.rs][docsrs-image]][docsrs]
-[![LoC](https://tokei.rs/b1/github/nyx-space/nyx?category=lines)](https://github.com/nyx-space/nyx).
 [![codecov](https://codecov.io/gh/nyx-space/nyx/graph/badge.svg?token=gEiAvwzwh5)](https://codecov.io/gh/nyx-space/nyx)
 
+# Documentation
+
+The documentation is currently being updated. If you have specific use cases you would like to see documented, please [open a Github issue](https://github.com/nyx-space/nyx/issues/new?assignees=&labels=Documentation&projects=&template=documentation.md&title=) or [use the contact form](https://7ug5imdtt8v.typeform.com/to/neFvVW3p).
+
+## Quick start
+
+### Rust
+
+To install Nyx, follow these steps:
+1. Clone the repository: `git clone https://github.com/nyx-space/nyx.git`
+2. Navigate to the directory: `cd nyx`
+3. Run any of the [examples](./examples/), e.g. `RUST_LOG=info cargo run --example 01_orbit_prop --release`
+
+### Python
+
+For Python projects, get started by installing the library via `pip`: `pip install nyx_space`.
+
+**Important:** The Python package has been temporarily disabled. Refer to <https://github.com/nyx-space/nyx/issues/311> for details.
+
+# License
+
+Nyx is provided under the [AGPLv3 License](./LICENSE). By using this software, you assume responsibility for adhering to the license. Refer to [the pricing page](https://nyxspace.com/pricing/) for an FAQ on the AGPLv3 license. Notably, any software that incorporates, links to, or depends on Nyx must also be released under the AGPLv3 license, even if you distribute an unmodified version of Nyx.
+
+
 [cratesio-image]: https://img.shields.io/crates/v/nyx-space.svg
 [cratesio]: https://crates.io/crates/nyx-space
 [docsrs-image]: https://docs.rs/nyx-space/badge.svg
-[docsrs]: https://docs.rs/nyx-space/
+[docsrs]: https://rustdoc.nyxspace.com/
+
+# Author information
+> Chris Rabotin is a GNC and flight dynamics engineer with a heavy background in software.
 
-## Who am I?
-An GNC and flight dynamics engineer with a heavy background in software. I currently work for Rocket Lab USA on the Blue Ghost lunar lander. -- Find me on [LinkedIn](https://www.linkedin.com/in/chrisrabotin/).
+I currently work for Rocket Lab USA as the lead flight dynamics engineer on both Blue Ghost lunar lander missions. -- Find me on [LinkedIn](https://www.linkedin.com/in/chrisrabotin/).

examples/01_orbit_prop/README.md

@@ -0,0 +1,37 @@
+# Orbit propagation
+
+Propagating an orbit is the core of any astrodynamics analysis. In this example, you'll learn how to propagate an orbit state using basic two body dynamics or using a high fidelity propagator with the point masses of the Moon and Sun, solar radiation pressure, and a 21x21 gravity field.
+
+Then, you'll learn how to build some data products as dataframes using polars, and how to export the propagated trajectory as a CCSDS OEM file.
+
+To run this example, just execute:
+```sh
+RUST_LOG=info cargo run --example 01_orbit_prop --release
+```
+
+Building in `release` mode will make the computation significantly faster. Specifying `RUST_LOG=info` will allow you to see all of the information messages happening in ANISE and Nyx throughout the execution of the program.
+
+## Data products
+
+1. Export the trajectory as a CCSDS OEM version 2.0 file and as a parquet file, which includes the Keplerian orbital elements. This can be quickly analyzed and plotted in Python.
+2. Compare the difference in the radial, in-track, cross-track frame between the high fidelity and two-body/Keplerian propagation. The RIC frame is commonly used to compute the difference in position and velocity of different spacecraft. Build a Dataframe from this data and print
+3. Build a Dataframe containing the azimuth, elevation, range, and range-rate data of that spacecraft as seen from Boulder, CO, USA. Print out when the spacecraft has an elevation of 15 degrees or above on the horizon.
+
+## Force models
+
+The force models used here are akin to STK's "HPOP" propagator. Specifically, this example runs with the following models:
+- Point masses of the Earth, Moon, and Sun, where the gravitational parameters are sourced from NASA's [pck00011.tpc](https://naif.jpl.nasa.gov/pub/naif/generic_kernels/pck/pck00011.tpc) file (note that these differ slightly from GMAT's values). The planetary ephemeris used is the DE440s.bsp, provided by NASA as well.
+- Solar radiation pressure, with only the Earth as an eclipsing body
+- Spherical Harmonics of the Earth of order and degree 21x21, computed in the IAU Earth frame. The data comes from the JGM3 gravitational model, downloaded automatically using ANISE's `MetaFile` downloading and local caching mechanism. This is the default gravity field model of GMAT.
+
+## Quick analysis
+
+In two body propagation, all orbital elements remain constant apart from the true anomaly. In real life, the oblateness of the Earth causes the right ascension of the ascending node to drift with time (red line below). The other force models also affect the overall orbit.
+
+![RAAN, AOP, INC over time](./cubesat-angles-v-time.png)
+
+![SMA (km) over time](./cubesat-sma-v-time.png)
+
+![ECC over time](./cubesat-ecc-v-time.png)
+
+_Note_: These plots were generated with an SRP area of that was ten times larger than the correct value, hence you may notice slightly different Keplerian orbital elements, notably for the change in the shape of the orbit.