Merge pull request #36 from nyx-space/gemini-docs

Gemini docs

Author: ChristopherRabotin

docs/anise/explanation/almanac-and-context.md

@@ -0,0 +1,42 @@
+# The Almanac and the Context Pattern
+
+In most legacy astrodynamics toolkits, loading "kernels" (data files) is a global operation. When you load a file, it enters a global memory pool accessible by any function in your program. This "Global State" pattern makes it extremely difficult to write concurrent code or to manage different scenarios in a single application.
+
+## The Almanac as a Container
+
+ANISE replaces the global pool with the `Almanac`. An `Almanac` is a self-contained object that stores:
+- Ephemeris data (SPICE SPK)
+- Orientation data (SPICE BPC, PCK)
+- Planetary data (PCA)
+- Spacecraft data (SCA)
+- Euler Parameter / Unit quaternion data (EPA)
+- Location data (LKA)
+- Instrument data (IKA)
+
+```rust
+// In ANISE, you manage your own context
+let mut almanac = Almanac::default();
+almanac.load("de440.bsp")?;
+```
+
+Because the `Almanac` is an object, you can have as many as you want. One thread can work with a high-fidelity Earth model stored in `almanac_A`, while another thread performs long-term trajectory analysis using a simplified model in `almanac_B`.
+
+## Immutable Sharing and Cheap Clones
+
+A common concern with moving away from global state is the overhead of passing around a large context object. ANISE solves this through its memory management:
+
+1. **In-Memory storing**: When you load a kernel into an `Almanac`, the data is read once in memory (on the heap), reducing the overhead of maintaining a file handler;
+2. **Shared Data**: Internally, the `Almanac` uses reference-counting buffers;
+3. **Cheap Clones**: Cloning an `Almanac` does not copy the gigabytes of ephemeris data; it simply creates a new handle to the same underlying memory.
+
+This allows you to pass the `Almanac` into parallel loops (e.g., using `rayon` in Rust) with near-zero overhead.
+
+## The Search Engine
+
+The `Almanac` acts as a search engine for your data. When you ask for the position of Mars relative to Earth, the `Almanac`:
+1. Looks up the IDs for Earth and Mars.
+2. Traverses the ephemeris tree to find a common ancestor.
+3. Chains together the necessary translations from the loaded SPK segments.
+4. Returns the result as a high-precision state vector.
+
+By centralizing this logic in a thread-safe object, ANISE provides a clean API that hides the complexity of multi-segment, multi-file lookups.

docs/anise/explanation/analysis.md

@@ -0,0 +1,76 @@
+# Analysis Engine
+
+ANISE includes a powerful **Analysis Engine** designed to answer complex astrodynamics questions declaratively. Instead of writing imperative loops to check conditions at every time step, you define *what* you want to compute, and ANISE figures out *how* to compute it efficiently.
+
+## Core Philosophy
+
+The analysis engine is built on three pillars:
+
+1.  **Declarative Queries**: You describe the state of the system (e.g., "The distance between Earth and Mars") as an expression tree, rather than a sequence of math operations.
+2.  **Continuous Resolution**: Unlike simple step-by-step propagation, the engine uses root-finding algorithms (specifically the **Brent solver**) to find exact times of events, such as when a satellite enters an eclipse or crosses a specific altitude.
+3.  **Serialization**: All queries can be serialized to **S-expressions** (symbolic expressions). This allows you to define a query in Python, send it to a remote Rust/Python worker, and execute it safely without allowing arbitrary code execution.
+
+## Expression Trees
+
+Everything in the analysis engine is an **Expression**. These expressions can be nested to form complex queries.
+
+-   **`StateSpec`**: Defines the "Context" of an orbital state. Who is the target? Who is the observer? What frame are we in?
+    -   *Example*: "LRO (Target) as seen from the Moon (Observer) in the Moon Body-Fixed frame."
+-   **`VectorExpr`**: Computes a 3D vector.
+    -   *Examples*: `Radius`, `Velocity`, `SunVector`, `OrbitalMomentum`.
+-   **`ScalarExpr`**: Computes a single floating-point number.
+    -   *Examples*: `Norm` (of a vector), `DotProduct`, `AngleBetween`, `OrbitalElement` (eccentricity, SMA), `ShadowFunction`.
+-   **`DcmExpr`**: Defines how to compute a direct cosine matrix, used to correctly align instruments with respect to the orbit frame
+    -   *Examples*: `Triad` for an align/clock vector setup, `R1` for a rotation about X
+
+### Example
+To compute the **Beta Angle** (angle between the orbit plane and the vector to the Sun), you don't write a function. You build it:
+
+```rust
+// In pseudo-code representation of the internal tree
+Shape: AngleBetween(
+    VectorA: SunVector(Observer),
+    VectorB: OrbitalMomentum(Target, Observer)
+)
+```
+
+## Event Finding (The Superlinear Solver)
+
+One of ANISE's most powerful features is its ability to find **Events**. An Event is defined by a `ScalarExpr` and a `Condition`.
+
+-   **Scalar**: Any continuous values (e.g., "Elevation Angle").
+-   **Condition**: A threshold or extrema (e.g., `= 4.57 deg`, `> 5.0 deg`, `Maximum`, `Minimum`).
+
+### The Problem with Steps
+If you simply loop through time with a 1-minute step, you might miss short events (like a 30-second eclipse) or get inaccurate start/stop times.
+
+### The ANISE Solution: Brent's Method
+ANISE uses an adaptive checking method combined with **Brent's method** for root finding.
+
+1.  **Search**: It scans the time domain using an adapative step scanner inspired from adaptive step Runge Kutta methods
+2.  **Bracket**: When it detects that the condition changed (e.g., elevation went from negative to positive), it knows a root (0 crossings) exists in that interval.
+3.  **Solve**: It deploys the Brent solver to find the *exact* event when determining the value crossed the threshold.
+
+This allows for **superlinear convergence**, meaning it finds high-precision times with very few function evaluations compared to brute-force searching.
+
+## Reporting
+
+The engine provides three main reporting modes:
+
+1.  **`report_scalars`**: Evaluates a list of expressions at fixed time steps. This is parallelized using `rayon` for maximum speed.
+2.  **`report_events`**: Finds discrete instants where a condition happens (e.g., "Apoapsis", "Max Elevation").
+3.  **`report_event_arcs`**: Finds durations where a condition holds true (e.g., "Eclipse Duration", "Comm Window").
+4.  **`report_visibility_arcs`**: Compute the Azimuth, Elevation, Range, and Range-rate ("AER") for each communication pass from a given location on _any_ celestial object.
+
+## Safety and S-Expressions
+
+Because analysis queries are just data structures (enums), they can be serialized into a lisp-like S-expression format.
+
+```lisp
+(Event
+  (scalar (AngleBetween (Radius) (SunVector)))
+  (condition (LessThan 90.0))
+)
+```
+
+This is critical for web services or distributed systems. A client can craft a complex query and send it to a server. The server parses the S-expression and executes it. Because the server *only* executes valid ANISE expressions, there is **no risk of arbitrary code injection**, unlike pickling Python objects or sending raw scripts.

docs/anise/explanation/frame-safety.md

@@ -0,0 +1,40 @@
+# Frame Safety and Graph Lookups
+
+In space mission design, one of the most common sources of error is the misuse of reference frames. Forgetting to rotate from a body-fixed frame to an inertial frame, or confusing two different inertial frames (like J2000 and EME2000), can lead to mission-critical failures.
+
+ANISE introduces the concept of **Frame Safety** to eliminate these errors.
+
+## Frames are Not Just IDs
+
+In the SPICE toolkit, frames are often referred to by integer IDs. While ANISE maintains compatibility with NAIF IDs, it treats Frames as rich objects. 
+
+Every Frame in ANISE has an `ephemeris_id` and an `orientation_id`, which store the central object identifier and the reference frame orientation identifier. Each frame may also set properties related to the central object, notably:
+- **`mu_km3_s2`**: the gravitational parameter in km^3/s^2
+- **`shape`**: the tri-axial ellipsoid shape of the central object, defined by its semi major and semi minor axes and its polar axis.
+
+These optional data may be required for specific computations. For example, the calculation of the semi-major axis of the orbit requires that orbit's frame to set the `mu_km3_s2`. You may fetch the available frame information loaded in the almanac using the `frame_info` function, e.g. `my_almanac.frame_info(EARTH_J2000)`.
+
+ANISE also defines a `FrameUid` which is identical to the `Frame` but only stores the ephemeris and orientation IDs. A number of commonly used frames are defined in the ANISE constants, though none of these definitions include the gravitational data or the shape data: these _must_ be loaded at runtime.
+
+## Validation Before Computation
+
+When you request a transformation in ANISE, the toolkit doesn't just blindly multiply matrices or vectors. It performs a **Frame Check**.
+
+Before any computation:
+1. ANISE checks that the target and observer frames are part of the same "graph" (they have a path between them).
+2. It ensures the transformation is physically valid (e.g., you aren't trying to rotate between two frames that don't have a defined orientation relationship).
+3. It identifies the "Common Ancestor"—the point in the frame tree where the paths from the two frames meet.
+
+## Tree Traversal and Path Finding
+
+ANISE represents the relationship between frames as a tree. 
+
+When transforming from Frame A to Frame B:
+- **Translation Path**: Finds the common ephemeris ancestor (e.g., the Solar System Barycenter) and sums the vectors along the branches.
+- **Rotation Path**: Finds the common orientation ancestor and composes the Direction Cosine Matrices (DCMs) or Quaternions.
+
+If a path cannot be found (e.g., you haven't loaded the necessary SPK or PCK files), ANISE returns a clear error at the start of the query (when building the paths), rather than producing junk data or crashing with a segfault.
+
+## The `Frame` Object
+
+In the ANISE API, a `Frame` object carries its metadata with it. When you build an `Orbit`, it is attached to a specific `Frame`. When you transform that `Orbit` to a new frame, ANISE uses the metadata to ensure the transformation is accurate, including handling the necessary time conversions for body-fixed rotations.

docs/anise/explanation/index.md

@@ -1,4 +1,11 @@
 > Explanation is a discusive treatment of a subject, that permits reflection. Explanation is **understanding-oriented**.
 -- [_Diataxis_](https://www.diataxis.fr/tutorials/)
 
-This section delves into the design of ANISE, how it is validated, and how its results may very minutely differ from those of the SPICE toolkit but why you should actually trust ANISE instead.
+This section delves into the design of ANISE, its architecture, and the core concepts that make it a modern alternative to legacy toolkits.
+
+- **[Why ANISE?](why-anise.md)**: The philosophy and architectural decisions behind the toolkit.
+- **[Almanac and Context](almanac-and-context.md)**: Understanding the data-driven design and thread safety.
+- **[Frame Safety](frame-safety.md)**: How ANISE prevents coordinate system errors.
+- **[Analysis Engine](analysis.md)**: Declarative queries and superlinear event finding.
+- **[Time](time.md)**: The importance of high-precision timekeeping.
+- **[Validation](validation.md)**: How we ensure ANISE matches (or exceeds) the accuracy of the SPICE toolkit.

docs/anise/explanation/why-anise.md

@@ -0,0 +1,34 @@
+# Why ANISE?
+
+ANISE (Attitude, Navigation, Instrument, Spacecraft, Ephemeris) was born out of a need for a modern, high-performance, and thread-safe toolkit for space mission design and operations. While the NAIF SPICE toolkit has been the industry standard for decades, its architecture was designed for an era of single-threaded, procedural programming.
+
+## Designed for Modern Hardware
+
+Modern computing environments, from high-performance workstations to cloud-based clusters, rely on multi-core processors. Legacy toolkits often struggle in these environments due to:
+
+- **Global State**: SPICE uses a global kernel pool. This means you cannot easily load different sets of kernels for different threads or perform concurrent queries without complex locking mechanisms (mutexes) that severely bottleneck performance.
+- **Thread Safety**: Because of its global state and internal cache mechanisms, SPICE is inherently NOT thread-safe.
+
+**ANISE is thread-safe by design.** It eliminates global state by using the `Almanac` as a first-class object. You can create multiple `Almanac` instances, each with its own set of loaded kernels, and share them across threads safely.
+
+## Safety through Rust
+
+By building on Rust, ANISE leverages a powerful type system and ownership model to provide guarantees that other toolkits cannot:
+
+- **Memory Safety**: Rust prevents common bugs like null pointer dereferences, buffer overflows, and data races at compile time.
+- **Frame Safety**: ANISE doesn't just treat frames as integer IDs. It understands the relationship between frames. It validates that any transformation (rotation or translation) you request is physically possible before even attempting the math. No more mixing up J2000 and ITRF93 by accident.
+
+## Precision and Performance
+
+ANISE matches SPICE's mathematical precision—and in many cases, exceeds it.
+
+- **Integer-based Time**: By using the `hifitime` library, ANISE avoids the rounding errors inherent in floating-point time representations (used by SPICE). This is particularly critical for high-fidelity planetary rotations where a few microseconds of error can accumulate over years.
+- **Limited file system calls**: ANISE uses copies the content of files on the heap on load, allowing it to query large kernel files (like DE440) with zero file system waits, minimal memory overhead and maximum speed.
+
+## Multi-language from the Core
+
+ANISE is an ecosystem. While the core engine is written in Rust for maximum performance, it is designed to be easily accessible from other languages.
+- **Rust**: Native performance and type safety.
+- **Python**: A pythonic API (`anise-py`) that offers the performance and safety of the Rust core.
+- **CLI/GUI**: Tools for quick inspection and visualization that work cross-platform.
+- **C++**: While planned, this interface is stalled due to limited resources.

docs/anise/reference/almanac.md

@@ -0,0 +1,62 @@
+# Almanac Reference
+
+The `Almanac` is the primary interface for ANISE. It serves as the context for all ephemeris, orientation, and physical constant lookups.
+
+The following is a _small subset_ of all the functions available in the Almanac. Please refer to <https://docs.rs/anise/latest/anise/almanac/struct.Almanac.html> for the exhaustive list: Python functions are (almost) always named identically.
+
+## Key Concepts
+
+- **Thread Safety**: The `Almanac` is `Send + Sync`, meaning it can be safely shared across threads.
+- **Data Encapsulation**: It stores loaded kernel data internally; there is no global pool.
+- **Method Chaining**: Loading methods often use a builder pattern or return a new handle for easy initialization.
+
+## Loading Data
+
+The `Almanac` supports loading various kernel types. You can load files directly or allow ANISE to "guess" the file type.
+
+### `load`
+Loads any supported ANISE or SPICE file.
+- **Rust**: `almanac.load("path/to/file")?`
+- **Python**: `almanac.load("path/to/file")`
+
+### Specialized Loaders
+If you know the file type, you can use specialized loaders for better performance or specific configuration:
+- `with_spk(spk)`: Add SPK (ephemeris) data.
+- `with_bpc(bpc)`: Add BPC (high-precision orientation) data.
+- `with_planetary_data(pca)`: Add an ANISE planetary constant data kernel (gravity and tri-axial ellipsoid constants and low-fidelity orientation).
+- `with_location_data(lka)`: Add an ANISE location data kernel (landmarks defined by their latitude, longitude, and height above the ellipsoid on a given body fixed frame).
+- `with_instrument_data(ika)`: Add an ANISE instrument kernel (an instrument is defined by its rotation quaternion/EP, its offset from the body center, and its field of view).
+
+## Coordinate Transformations
+
+The most common use of the `Almanac` is to transform positions and velocities between frames.
+
+### `transform_to`
+Transforms an `Orbit` (state vector) into a different frame at its own epoch.
+- **Parameters**: `orbit`, `target_frame`, `aberration`.
+- **Returns**: A new `Orbit` in the target frame.
+
+### `translate`
+Calculates the relative position and velocity between two frames.
+- **Parameters**: `target`, `observer`, `epoch`, `aberration`.
+- **Returns**: A `StateVector` (Position + Velocity).
+
+### `rotate`
+Calculates the rotation (DCM) from one orientation frame to another.
+- **Parameters**: `target`, `observer`, `epoch`.
+- **Returns**: A 3x3 Direction Cosine Matrix.
+
+## Physical Constants
+
+The `Almanac` also stores physical data for bodies defined in the kernels.
+
+### `frame_info`
+Retrieves a `Frame` object containing metadata for a given NAIF ID.
+- **Includes**: Gravitational parameter ($\mu$), body radii, and frame type.
+
+### `angular_velocity_deg_s`
+Returns the angular velocity vector in deg/s of the from_frame wrt to the to_frame.
+
+## Built-in Constants
+
+ANISE provides a set of common NAIF IDs and frames in the `constants` module for ease of use (e.g., `EARTH_J2000`, `SUN_J2000`, `MOON_J2000`).