Skip to main content

hpr_motor/
lib.rs

1//! Solid rocket motor model (thrust, propellant mass, CG and inertia over time), `.eng`/`.rse`
2//! reading and writing, and catalog types.
3//!
4//! Three pages of the guide cover this crate: [Solid motors][guide-motor], [`.eng`
5//! files][guide-eng] and [`.rse` files][guide-rse]. They give the models, their sources, how well
6//! they are validated and what they leave out.
7//!
8//! [guide-motor]: https://hpr.fusionspace.co/physics/motor.html
9//! [guide-eng]: https://hpr.fusionspace.co/format/eng.html
10//! [guide-rse]: https://hpr.fusionspace.co/format/rse.html
11//!
12//! - [`curve`]: thrust curves, total impulse, NFPA 1125 burn time and average thrust.
13//! - [`class`]: impulse classes (`1/8A` to `O` and beyond).
14//! - [`motor`]: the solid motor: consumption, mass properties and ambient-pressure thrust, with
15//!   [`grains`] (BATES grains) and [`mass`] (axisymmetric mass elements).
16//! - [`eng`] and [`rse`]: RASP and RockSim motor files, with [`delay`] strings.
17//! - [`catalog`]: the offline catalog and its bundled ThrustCurve.org curves.
18
19// Outside bytes reach casts here. An `as` cast of a length or count truncates silently where
20// `usize` is 32 bits (wasm32), and one from a float saturates: each cast is checked with
21// `try_from`, or its `allow` says why it is exact or meant.
22#![warn(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
23#![cfg_attr(
24    test,
25    allow(
26        clippy::cast_possible_truncation,
27        clippy::cast_sign_loss,
28        reason = "a test builds its own inputs, so it sets its casts' ranges"
29    )
30)]
31mod bundled;
32pub mod catalog;
33pub mod class;
34pub mod convert;
35pub mod curve;
36pub mod delay;
37pub mod eng;
38pub mod error;
39pub mod grains;
40pub mod mass;
41pub mod motor;
42pub mod openrocket_curves;
43pub mod rse;
44pub mod text;
45
46pub use catalog::{Catalog, CatalogCurve, CatalogMotor};
47pub use class::ImpulseClass;
48pub use curve::ThrustCurve;
49pub use delay::{Delay, DelayList, DelayWarning};
50pub use error::MotorError;
51pub use grains::{BatesGrains, GrainShape};
52pub use mass::MassElement;
53pub use motor::{
54    EXHAUST_VELOCITY_RANGE_M_S, MotorState, Nozzle, Propellant, PropellantColumn, SolidMotor,
55};
56pub use text::{ParseWarning, Parsed, WarningKind};
57
58#[cfg(test)]
59mod tests {
60    use super::*;
61
62    /// Loft lesson L38: Loft's class letter was off by one at band tops (2.5 N·s gave `B`) and
63    /// had no `1/8A`.
64    #[test]
65    fn impulse_class_upper_bound_inclusive() {
66        let class = |ns: f64| ImpulseClass::from_total_impulse(ns).unwrap().label();
67        assert_eq!(class(2.5), "A");
68        assert_eq!(class(2.500_000_000_000_001), "B");
69        assert_eq!(class(5.0), "B");
70        assert_eq!(class(10.0), "C");
71        assert_eq!(class(160.0), "G");
72        assert_eq!(class(160.000_1), "H");
73        assert_eq!(class(40960.0), "O");
74        assert_eq!(class(0.3125), "1/8A");
75        assert_eq!(class(0.1), "1/8A");
76        assert_eq!(class(0.3126), "1/4A");
77        assert_eq!(class(1.25), "1/2A");
78        assert_eq!(class(1.2501), "A");
79    }
80
81    /// Loft lesson L40: Loft fixed the motor CG at the casing midpoint with no inertia of its own,
82    /// and its impulse-fraction model was uncited.
83    #[test]
84    fn cg_and_inertia_move_from_loaded_to_burnout() {
85        let curve =
86            ThrustCurve::new(vec![0.05, 0.2, 1.8, 2.0], vec![900.0, 800.0, 700.0, 0.0]).unwrap();
87        // A 38 mm reload: a heavy nozzle and aft closure put the dry center at 0.10 m, and three
88        // grains are centered further forward, at 0.20 m.
89        let grains = BatesGrains {
90            count: 3,
91            density_kg_m3: 1815.0,
92            outer_radius_m: 0.0165,
93            initial_inner_radius_m: 0.006,
94            initial_height_m: 0.09,
95            separation_m: 0.005,
96            center_m: 0.2,
97            inhibited_ends: false,
98        };
99        let dry = MassElement {
100            mass_kg: 0.45,
101            cg_m: 0.10,
102            axial_inertia_kg_m2: 1.6e-4,
103            transverse_inertia_kg_m2: 7.6e-3,
104        };
105        let motor = SolidMotor::new(curve, Propellant::Grains(grains), dry, None).unwrap();
106        let loaded = motor.state(0.0);
107        let burnout = motor.state(motor.burnout_time_s());
108
109        // Loaded: the parallel-axis combination of the dry mass and the full grains.
110        let m_p = grains.initial_mass_kg();
111        assert_eq!(loaded.propellant.mass_kg, m_p);
112        let cg = (0.45 * 0.10 + m_p * 0.2) / (0.45 + m_p);
113        assert!((loaded.total.cg_m - cg).abs() < 1e-15);
114        let full = grains.mass_element(m_p);
115        let transverse = dry.transverse_inertia_kg_m2
116            + 0.45 * (0.10 - cg).powi(2)
117            + full.transverse_inertia_kg_m2
118            + m_p * (0.2 - cg).powi(2);
119        assert!((loaded.total.transverse_inertia_kg_m2 - transverse).abs() < 1e-15);
120
121        // Burnout: only the dry mass is left, with its own inertia.
122        assert_eq!(burnout.propellant.mass_kg, 0.0);
123        assert_eq!(burnout.total.mass_kg, 0.45);
124        assert!((burnout.total.cg_m - 0.10).abs() < 1e-15);
125        assert!((burnout.total.axial_inertia_kg_m2 - 1.6e-4).abs() < 1e-18);
126        assert!((burnout.total.transverse_inertia_kg_m2 - 7.6e-3).abs() < 1e-15);
127
128        // In between, the center moves aft and both inertias fall, monotonically.
129        let states: Vec<MotorState> = (0..=200)
130            .map(|i| motor.state(f64::from(i) * 0.01))
131            .collect();
132        for pair in states.windows(2) {
133            assert!(pair[1].total.cg_m <= pair[0].total.cg_m + 1e-15);
134            assert!(pair[1].total.mass_kg <= pair[0].total.mass_kg);
135            assert!(pair[1].total.axial_inertia_kg_m2 <= pair[0].total.axial_inertia_kg_m2 + 1e-18);
136        }
137        assert!(loaded.total.cg_m - burnout.total.cg_m > 0.03);
138        assert!(
139            loaded.total.transverse_inertia_kg_m2 > 1.3 * burnout.total.transverse_inertia_kg_m2
140        );
141    }
142
143    /// Loft lesson L39: Loft took the last sample as the burn time. ThrustCurve's glossary uses
144    /// NFPA 1125: from 5% of peak thrust on the way up to 5% of peak on the way down.
145    #[test]
146    fn burn_time_uses_the_nfpa_1125_definition() {
147        // A 1 s ramp to a 200 N peak, a 1 s plateau at 100 N, and a 1 s tail-off to zero; then a
148        // long trickle at 2 N (1% of peak) that NFPA 1125 leaves out.
149        let curve = ThrustCurve::new(
150            vec![0.0, 1.0, 1.001, 2.0, 3.0, 3.001, 6.0, 6.001],
151            vec![0.0, 200.0, 100.0, 100.0, 0.0, 2.0, 2.0, 0.0],
152        )
153        .unwrap();
154        assert_eq!(curve.end_time_s(), 6.001);
155        // Up through 10 N at 0.05 s; down through 10 N at 2.9 s.
156        let (start, end) = curve.burn_window_s();
157        assert!((start - 0.05).abs() < 1e-12, "{start}");
158        assert!((end - 2.9).abs() < 1e-12, "{end}");
159        assert!((curve.burn_time_s() - 2.85).abs() < 1e-12);
160        assert!(
161            (curve.average_thrust_n() - curve.total_impulse_ns() / 2.85).abs() < 1e-9,
162            "average thrust is the total impulse over the NFPA burn time"
163        );
164    }
165}