Skip to main content

Crate astrodyn_math

Crate astrodyn_math 

Source
Expand description

astrodyn_math — JEOD-faithful math kernels.

Pure-Rust port of the standalone math utilities under JEOD models/utils/: quaternions, Euler angles, orbital elements, geodetic coordinates, the LVLH frame, the solar beta angle, and the small but load-bearing collection of vector/matrix helpers that mirror JEOD’s Vector3/Matrix3x3 inline functions.

Phase 2 of the type-system refactor (#104) unifies the quaternion type with astrodyn_quantities. JeodQuat is now a re-export of astrodyn_quantities::JeodQuat (the canonical Quat<ScalarFirst, LeftTransform> type alias), and all algebraic/conversion methods live on that unified type so there is only one quaternion in the workspace. Quat, NormalizedQuat, the Layout tags (ScalarFirst, ScalarLast) and the Transform tags (LeftTransform, RightTransform) are re-exported so kernel code can name its inputs at the JEOD convention without reaching into upstream crates directly.

§Public surface

§Vector / matrix helpers

types re-exports glam’s DMat3 / DQuat / DVec3 and adds the mat3_from_rows constructor (JEOD source is row-major while glam is column-major, so this lets ports read top-to-bottom against the C++ source) plus the inline Vector3::* / Matrix3x3::* operators ported from models/utils/math/include/vector3_inline.hh and matrix3x3_inline.hh (e.g., vector3_transform, vector3_transform_transpose, matrix3x3_transform_matrix, matrix3x3_transpose_transform_matrix, matrix3x3_product_transpose_transpose).

Pure Rust, zero Bevy dependency.

§Example

Build a JEOD-convention left-transformation quaternion from an eigen-rotation (angle + axis) and verify the round-trip q.conjugate(q.transform(v)) == v:

use astrodyn_math::JeodQuat;
use glam::DVec3;

// Arbitrary rotation: 0.7 rad about the (1, 1, 1)/√3 axis.
let axis = DVec3::new(1.0, 1.0, 1.0).normalize();
let q = JeodQuat::left_quat_from_eigen_rotation(0.7, axis);

// Transform-then-inverse-transform recovers the original vector
// (i.e. q.conjugate() reverses q).
let v = DVec3::new(3.0, -2.0, 5.0);
let v_rotated = q.left_quat_transform(v);
let v_back = q.conjugate().left_quat_transform(v_rotated);
assert!((v_back - v).length() < 1e-12);

Re-exports§

pub use euler_angles::compute_euler_angles_from_matrix_typed;
pub use euler_angles::compute_matrix_from_euler_angles_typed;
pub use euler_angles::compute_quaternion_from_euler_angles_typed;
pub use euler_angles::quaternion_to_matrix_normalized;
pub use euler_angles::EulerSequence;
pub use euler_angles::ALL_SEQUENCES;
pub use geodetic::cartesian_to_geodetic_typed;
pub use geodetic::compute_body_geodetic;
pub use geodetic::compute_body_geodetic_typed;
pub use geodetic::geodetic_to_cartesian_typed;
pub use geodetic::GeodeticState;
pub use geodetic::GeodeticStateTyped;
pub use lvlh::compute_lvlh_frame_typed;
pub use lvlh::LvlhFrame;
pub use orbital_elements::OrbitalElements;
pub use solar_beta::compute_body_solar_beta;
pub use solar_beta::compute_body_solar_beta_typed;
pub use solar_beta::solar_beta_angle_typed;
pub use error::*;
pub use types::*;

Modules§

error
Error type for the orbital-element kernels in crate::orbital_elements.
euler_angles
Euler angle decomposition and composition.
geodetic
Geodetic coordinate conversions.
lvlh
LVLH (Local Vertical Local Horizontal) frame computation.
orbital_elements
Classical orbital elements and Cartesian ↔ Keplerian conversion.
quaternion
JEOD quaternion glue: re-exports the unified astrodyn_quantities::JeodQuat type and keeps JEOD-specific constants and free helpers that don’t belong in the generic quantities crate.
solar_beta
Solar beta angle computation.
test_utils
Approximate-equality helpers for unit and Tier-2 tests.
types
Vector / matrix helpers ported from models/utils/math/include/vector3_inline.hh and models/utils/math/include/matrix3x3_inline.hh in JEOD v5.4.0.

Structs§

BodyAttitude
RootInertial → body attitude of vehicle V, witnessed unit-norm and scalar-first / left-transformation (JEOD canonical).
BodyFrame
Body (CoM-centered) frame of vehicle V. Rotates with the vehicle.
Earth
Planet marker for Earth.
Ecef
Earth-centered Earth-fixed frame (ITRF-like). Rotates with Earth.
FrameTransform
Proper rotation taking vectors expressed in From to the same vectors expressed in To.
GMST
Greenwich Mean Sidereal Time (angle, but seconds-ized by convention).
GPS
GPS Time (TAI − 19 s).
GravParam
Gravitational parameter μ = GM tagged with the source planet P.
HarmonicDegree
Spherical-harmonic degree or order index. Unitless ordinal.
InertiaTensor
Mass moment of inertia tensor (kg·m²) expressed in frame F.
IntegOrigin
The integration-frame origin: position and velocity of the integration-frame origin expressed in root-inertial coordinates.
IntegrationFrame
A body’s integration frame — a non-rotating quasi-inertial frame whose origin generally differs from the root inertial origin.
LeftTransform
r' = q r q⁻¹ — the JEOD convention.
Lvlh
Local Vertical / Local Horizontal frame relative to chief vehicle Chief. Z axis points planet-ward; Y opposes orbital angular momentum; X completes the right-handed triad (approximately along-track in near-circular orbits).
Mars
Planet marker for Mars.
MassNode
Mass-tree wildcard inertial-flavor frame for kinematic-propagation scratch state.
Moon
Planet marker for Moon.
Ned
North-East-Down topocentric frame relative to chief vehicle Chief.
NormalizedQuat
A quaternion witnessed to have unit norm at construction time.
PlanetFixed
Planet-fixed frame for any planet P. Rotates with that planet.
PlanetInertial
A particular planet’s inertial (non-rotating, J2000-aligned) frame, centered at the planet’s CoM.
Qty3
Componentwise 3-vector: each of x, y, z carries the dimension D, and the whole vector carries the frame tag F.
Quat
Quaternion tagged with its storage layout and transformation convention.
RightTransform
r' = q⁻¹ r q — the opposite of JEOD; common in many textbooks.
RootInertial
The simulation’s root inertial frame — the unique inertial node at the top of the frame tree.
ScalarFirst
Storage layout [q0, q1, q2, q3] where q0 is the scalar part (JEOD).
ScalarLast
Storage layout [x, y, z, w] where w is the scalar part (glam).
SecondsSince
Seconds elapsed in the named time scale, measured from that scale’s epoch.
SelfPlanet
Phantom marker for “this entity’s own planet” — used by ECS adapters whose per-entity components carry PlanetFixed<P> phantoms but whose planet identity is determined at runtime by the entity itself.
SelfRef
Phantom marker for “this entity’s own vehicle frame” — used by ECS adapters whose per-entity components carry frame phantoms but whose vehicle identity is determined at runtime by the entity itself.
StructuralFrame
Structural (geometric-origin) frame of vehicle V. Rotates with vehicle.
Sun
Planet marker for Sun.
TAI
International Atomic Time.
TDB
Barycentric Dynamical Time (relativistic correction to TT).
TT
Terrestrial Time (TAI + 32.184 s).
TimeConverter
Explicit converter between two time scales.
UT1
Universal Time 1 (Earth-rotation based).
UTC
Coordinated Universal Time (leap-second stepped).

Traits§

Array3Ext
Extension trait on [f64; 3] (raw component arrays from CSVs or JEOD initial conditions) producing frame-tagged 3-vectors.
F64Ext
Unit-construction extension on f64.
Frame
Compile-time reference frame tag.
Layout
Compile-time quaternion storage layout marker.
Planet
Compile-time planet tag used to parameterize planet-fixed frames.
TimeScale
Compile-time time-scale tag.
Transform
Compile-time quaternion transformation convention marker.
Vec3Ext
Extension trait on glam::DVec3 producing frame-tagged 3-vectors.
Vehicle
Compile-time vehicle tag used to parameterize vehicle-relative frames.

Type Aliases§

Acceleration
Acceleration in frame F. Base SI unit: m/s².
AngularAcceleration
Angular acceleration in frame F. Base SI unit: rad/s².
AngularMomentum
Angular momentum in frame F. Base SI unit: kg·m²/s.
AngularVelocity
Angular velocity in frame F. Base SI unit: rad/s.
Force
Force in frame F. Base SI unit: newtons.
JeodQuat
The JEOD canonical quaternion type: scalar-first, left-transformation.
Jerk
Jerk (time derivative of acceleration) in frame F. Base SI unit: m/s³.
MassFlowRate
Scalar mass-flow rate.
Position
Position in frame F (default: RootInertial). Base SI unit: meters.
SpecificAngMom
Scalar specific angular momentum.
SpecificEnergy
Scalar specific energy.
Torque
Torque in frame F. Base SI unit: N·m.
Velocity
Velocity in frame F. Base SI unit: m/s.