astrodyn_dynamics/
lib.rs

1//! Rigid-body dynamics: state, mass properties, forces, and integration.
2//!
3//! This crate is the JEOD-faithful port of the dynamics half of
4//! `models/dynamics/`. It owns the per-vehicle state types
5//! ([`TranslationalState`], [`RotationalState`], [`SixDofState`]), the rigid-
6//! body mass model ([`MassProperties`], [`MassBody`], [`MassPoint`],
7//! [`MassTree`], [`point_mass_inertia`]), the force-collection pipeline
8//! ([`collect_forces`], [`ForceContributions`], [`TotalForce`],
9//! [`GravityAcceleration`], [`compute_translational_acceleration`],
10//! [`compute_translational_derivatives`], [`compute_frame_derivatives`],
11//! [`compute_t_inertial_struct`]), and a battery of integrators
12//! ([`rk4_translational_step`], [`rk4_sixdof_step`], adaptive RKF4(5) in
13//! [`rkf45`], multistep [`abm4`]/Adams–Bashforth–Moulton, and
14//! [`gauss_jackson`]).
15//!
16//! Initial-condition machinery in [`body_init`] mirrors JEOD's
17//! `BodyAction` subclasses: [`init_from_orbital_elements`],
18//! [`init_from_mean_anomaly`], [`init_from_time_periapsis`],
19//! [`init_from_lvlh`], [`init_from_ned`], and [`compute_ned_rotation`].
20//! Frame propagation lives in [`propagation`]: [`propagate_body_frames`],
21//! [`propagate_forward`], [`propagate_reverse`]. Holonomic constraints
22//! ([`HolonomicConstraint`], [`PendulumConstraint`], [`BaumgarteSolver`],
23//! [`apply_constraint`]) port the constraint-stabilization layer used by
24//! tethers and articulated structures. Declaratively driven kinematic
25//! joints — single-axis frame-rotation drivers used by articulated
26//! sub-trees that consume a prescribed angular trajectory rather than
27//! integrating one — live in [`kinematic_joint`]
28//! ([`JointKinematicsSpec`], [`evaluate_joint_kinematics`]).
29//! Root-to-leaf state propagation through kinematic-child chains lives
30//! in [`kinematic_propagation`] ([`compute_kinematic_child_state`],
31//! [`compute_kinematic_child_state_typed`],
32//! [`derive_kinematic_child_from_states`], [`KinematicChildInputs`],
33//! [`KinematicChildOutputs`]).
34//!
35//! JEOD source: `models/dynamics/dyn_body/`, `models/dynamics/mass/`,
36//! `models/dynamics/body_action/`, and `models/utils/integration/`. Pure
37//! Rust, zero Bevy dependency — orchestration lives in `astrodyn` and ECS
38//! wiring lives in the `astrodyn_bevy` root crate.
39//!
40//! ## Example
41//!
42//! Compute the parallel-axis (Steiner) inertia contribution of a 10 kg
43//! point mass offset 2 m along +X from the reference point. The
44//! resulting matrix has `0` on the (0,0) diagonal (no inertia about the
45//! axis through the offset) and `mass * r^2 = 40` on the perpendicular
46//! diagonal entries:
47//!
48//! ```
49//! use astrodyn_dynamics::point_mass_inertia;
50//! use glam::DVec3;
51//!
52//! let i = point_mass_inertia(10.0, DVec3::new(2.0, 0.0, 0.0));
53//! assert!(i.x_axis.x.abs() < 1e-12);
54//! assert!((i.y_axis.y - 40.0).abs() < 1e-12);
55//! assert!((i.z_axis.z - 40.0).abs() < 1e-12);
56//! ```
57
58#![forbid(unsafe_code)]
59#![deny(missing_docs)]
60
61pub mod abm4;
62pub mod attach;
63pub mod body_init;
64pub mod constraints;
65pub mod forces;
66pub mod frame_attach;
67pub mod gauss_jackson;
68pub mod integration;
69pub mod kinematic_joint;
70pub mod kinematic_propagation;
71pub mod mass;
72pub mod mass_body;
73pub mod mass_storage;
74pub mod propagation;
75pub mod rkf45;
76pub mod rotational;
77pub mod state;
78pub mod subtree;
79pub mod wrench;
80
81pub use abm4::{abm4_translational_step, Abm4State};
82pub use attach::{combine_states_at_attach, AttachCombineInputs, AttachCombineOutputs};
83pub use body_init::{
84    compute_ned_rotation, init_from_lvlh, init_from_mean_anomaly, init_from_ned,
85    init_from_orbital_elements, init_from_time_periapsis,
86};
87pub use constraints::{apply_constraint, BaumgarteSolver, HolonomicConstraint, PendulumConstraint};
88pub use forces::{
89    collect_forces, compute_frame_derivatives, compute_t_inertial_struct,
90    compute_translational_acceleration, compute_translational_derivatives, DynamicsConfig,
91    ForceContributions, FrameDerivatives, GravityAcceleration, TotalForce,
92};
93pub use frame_attach::{derive_frame_attached_state, FrameAttachInputs};
94pub use gauss_jackson::config::GaussJacksonConfig;
95pub use gauss_jackson::{GaussJacksonState, IntegratorResult};
96pub use integration::{rk4_sixdof_step, rk4_translational_step, IntegratorType};
97pub use kinematic_joint::{
98    evaluate as evaluate_joint_kinematics, evaluate_closure as evaluate_closure_kinematics,
99    evaluate_model as evaluate_joint_kinematics_model,
100    evaluate_multi_dof as evaluate_multi_dof_kinematics,
101    evaluate_sinusoidal as evaluate_sinusoidal_kinematics, ClosureJointKinematicsSpec,
102    JointKinematicsModel, JointKinematicsSpec, MultiDofJointKinematicsSpec, SingleDofKinematics,
103    SinusoidalJointKinematicsSpec, MAX_MULTI_DOF_AXES,
104};
105pub use kinematic_propagation::{
106    compute_kinematic_child_state, compute_kinematic_child_state_dquat,
107    compute_kinematic_child_state_typed, derive_kinematic_child_from_states, KinematicChildInputs,
108    KinematicChildOutputs,
109};
110pub use mass::{MassProperties, MassPropertiesTyped, INERTIA_CONSISTENCY_TOL};
111pub use mass_body::{
112    point_mass_inertia, MassBody, MassBodyId, MassPoint, MassPointState, MassTree,
113};
114pub use mass_storage::{
115    compute_node_composite, finalize_child_in_parent_frame, recompute_composites_via_storage,
116    MassNodeOutputs, MassNodeView, MassStorage,
117};
118pub use propagation::{propagate_body_frames, propagate_forward, propagate_reverse};
119pub use rkf45::{
120    rkf45_adaptive_sixdof_step, rkf45_adaptive_translational_step, rkf45_sixdof_step,
121    rkf45_translational_step, AdaptiveConfig, AdaptiveResult,
122};
123pub use rotational::{
124    compute_left_quat_deriv, compute_rotational_acceleration, normalize_integ, RotationalState,
125    RotationalStateTyped, SixDofState, SixDofStateTyped,
126};
127pub use state::TranslationalState;
128pub use subtree::DetachedSubtreeState;
129pub use wrench::{shift_wrench_to_parent, shift_wrench_to_parent_typed, Wrench};
astrodyn_dynamics/lib.rs

astrodyn_dynamics/
lib.rs
