Skip to main content

hpr/rocket/
mod.rs

1//! A rocket built part by part, from the nose back.
2//!
3//! [`Rocket::new`] starts an empty rocket of one body diameter. Body parts ([`Nose`], [`Tube`],
4//! [`Transition`]) stack from the nose tip in the order they are added. Attached parts ([`Fins`],
5//! [`MotorTube`], [`Mass`]) go on the last body tube added, where their [`Position`] puts them.
6//! [`Fitting`]s (couplers, centering rings, bulkheads, launch lugs, packed parachutes and
7//! streamers) go there too. [`Rocket::set_motor`] puts a [`Motor`] in the motor tube, and
8//! [`Rocket::add_parachute`] adds a recovery device. What the builder makes is an ordinary
9//! [`hpr_design::Rocket`], the same tree a design file holds ([`Rocket::design`]); a design you
10//! already have flies through [`Rocket::from_design`].
11//!
12//! Every part names its material. [`material`] finds a built-in one by id; the list, with each
13//! density's source, is [`hpr_design::materials`]. The builder has no default materials or wall
14//! thicknesses, because each one would be a guess at your rocket's mass. Every outer surface has
15//! the design's default finish, mass-production paint ([`hpr_design::Finish`]), which sets its
16//! skin friction; the builder can't change it yet.
17//!
18//! Parts can also come from a parts catalog, such as the one OpenRocket ships
19//! ([`hpr_io::orc::bundled`]): [`Nose::from_catalog`], [`Tube::from_catalog`],
20//! [`Transition::from_catalog`], [`MotorTube::from_catalog`] and [`Fitting::from_catalog`] make
21//! each part as the catalog gives it, its material and stated mass included. What a catalog
22//! leaves unsaid is chosen as OpenRocket chooses it, but for a hollow part's shoulder wall
23//! ([`catalog`] lists each choice).
24
25use hpr_aero::AeroModel;
26use hpr_design::checks::{check, has_errors};
27use hpr_design::{
28    Assembly, AutoDimension, BodyTube, Component, Configuration, FinCrossSection, FinPlanform,
29    FinSet, Ignition, InnerTube, MassComponent, MassProperties, Material, MotorMount, MountedMotor,
30    NoseCone, NoseShape, Overrides, Packing, Part, Position, Profile, ReferenceDiameter, Shoulder,
31    Stage, Wall, materials,
32};
33use hpr_sim::Device;
34use hpr_sim::metrics::{self, Margin};
35use serde::{Deserialize, Serialize};
36
37use crate::error::{Error, Order, finite, non_negative, positive};
38use crate::motor::Motor;
39
40pub mod catalog;
41
42pub use catalog::Fitting;
43
44/// The built-in material with id `id`, such as `"abs"`, `"kraft_phenolic"` or
45/// `"birch_plywood"`. [`hpr_design::materials`] lists them all, each with its density's source.
46///
47/// # Errors
48///
49/// [`Error::UnknownMaterial`] if no built-in material has that id.
50pub fn material(id: &str) -> Result<Material, Error> {
51    materials::find(id)
52        .map(|builtin| builtin.material())
53        .ok_or_else(|| Error::UnknownMaterial(id.to_owned()))
54}
55
56/// A nose cone. Its base takes the rocket's diameter, unless it states its own, as a catalog
57/// part does ([`Nose::from_catalog`]).
58#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
59pub struct Nose {
60    shape: NoseShape,
61    length_m: f64,
62    wall: Wall,
63    /// The shoulder; an outer radius of zero takes the inner radius of the tube behind it.
64    shoulder: Option<Shoulder>,
65    material: Material,
66    name: String,
67    /// The base diameter, m, where the nose states its own: a catalog part's.
68    #[serde(default, skip_serializing_if = "Option::is_none")]
69    diameter_m: Option<f64>,
70}
71
72impl Nose {
73    /// A hollow nose cone of `shape` and `length_m`, with a wall `wall_m` thick.
74    #[must_use]
75    pub fn hollow(shape: NoseShape, length_m: f64, wall_m: f64, material: Material) -> Self {
76        Self {
77            shape,
78            length_m,
79            wall: Wall::Shell {
80                thickness_m: wall_m,
81            },
82            shoulder: None,
83            material,
84            name: String::new(),
85            diameter_m: None,
86        }
87    }
88
89    /// A solid nose cone of `shape` and `length_m`.
90    #[must_use]
91    pub fn solid(shape: NoseShape, length_m: f64, material: Material) -> Self {
92        Self {
93            wall: Wall::Filled {},
94            ..Self::hollow(shape, length_m, 0.0, material)
95        }
96    }
97
98    /// The same nose with a shoulder, the sleeve behind its base that fits inside the tube
99    /// behind it: `length_m` long, `wall_m` thick, open at its aft end. Its outer radius is that
100    /// tube's inner radius.
101    #[must_use]
102    pub fn with_shoulder(mut self, length_m: f64, wall_m: f64) -> Self {
103        self.shoulder = Some(Shoulder {
104            length_m,
105            outer_radius_m: 0.0,
106            thickness_m: wall_m,
107            capped: false,
108        });
109        self
110    }
111
112    /// The same nose with a shoulder as [`Nose::with_shoulder`] makes it, closed at its aft end
113    /// by a disc as thick as its wall.
114    #[must_use]
115    pub fn with_capped_shoulder(self, length_m: f64, wall_m: f64) -> Self {
116        let mut nose = self.with_shoulder(length_m, wall_m);
117        if let Some(shoulder) = &mut nose.shoulder {
118            shoulder.capped = true;
119        }
120        nose
121    }
122
123    /// The same nose with `name`, which the design file keeps.
124    #[must_use]
125    pub fn named(mut self, name: &str) -> Self {
126        name.clone_into(&mut self.name);
127        self
128    }
129}
130
131/// A body tube: a length of the airframe.
132#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
133pub struct Tube {
134    length_m: f64,
135    wall_m: f64,
136    diameter_m: Option<f64>,
137    material: Material,
138    name: String,
139}
140
141impl Tube {
142    /// A tube `length_m` long with a wall `wall_m` thick. Its outer diameter is the aft diameter
143    /// of the body part before it, or the rocket's if it is the first.
144    #[must_use]
145    pub fn new(length_m: f64, wall_m: f64, material: Material) -> Self {
146        Self {
147            length_m,
148            wall_m,
149            diameter_m: None,
150            material,
151            name: String::new(),
152        }
153    }
154
155    /// The same tube with outer diameter `diameter_m`. A diameter other than the aft diameter of
156    /// the part before it makes a step in the airframe, which the design's checks warn of; a
157    /// [`Transition`] joins two diameters smoothly.
158    #[must_use]
159    pub fn with_diameter_m(mut self, diameter_m: f64) -> Self {
160        self.diameter_m = Some(diameter_m);
161        self
162    }
163
164    /// The same tube with `name`, which the design file keeps.
165    #[must_use]
166    pub fn named(mut self, name: &str) -> Self {
167        name.clone_into(&mut self.name);
168        self
169    }
170}
171
172/// A transition between two diameters: a boattail narrowing toward the tail, or a cone stepping
173/// the airframe up or down. Its fore end takes the diameter of the body part before it.
174#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
175pub struct Transition {
176    shape: NoseShape,
177    length_m: f64,
178    aft_diameter_m: f64,
179    wall: Wall,
180    material: Material,
181    name: String,
182    /// The fore diameter, m, where the transition states its own: a catalog part's.
183    #[serde(default, skip_serializing_if = "Option::is_none")]
184    fore_diameter_m: Option<f64>,
185    /// Whether its profile is cut from a whole nose cone ([`hpr_design::Transition::clipped`]).
186    #[serde(default)]
187    clipped: bool,
188    /// The shoulder ahead of its fore end, its outer radius stated.
189    #[serde(default, skip_serializing_if = "Option::is_none")]
190    fore_shoulder: Option<Shoulder>,
191    /// The shoulder behind its aft end, its outer radius stated.
192    #[serde(default, skip_serializing_if = "Option::is_none")]
193    aft_shoulder: Option<Shoulder>,
194}
195
196impl Transition {
197    /// A hollow conical transition `length_m` long, to `aft_diameter_m` at its aft end, with a
198    /// wall `wall_m` thick.
199    #[must_use]
200    pub fn conical(length_m: f64, aft_diameter_m: f64, wall_m: f64, material: Material) -> Self {
201        Self {
202            shape: NoseShape::Conical {},
203            length_m,
204            aft_diameter_m,
205            wall: Wall::Shell {
206                thickness_m: wall_m,
207            },
208            material,
209            name: String::new(),
210            fore_diameter_m: None,
211            clipped: false,
212            fore_shoulder: None,
213            aft_shoulder: None,
214        }
215    }
216
217    /// The same transition with the profile `shape` instead of a cone. It stays clipped, or
218    /// not, as it was ([`Transition::with_clipped`]).
219    #[must_use]
220    pub fn with_shape(mut self, shape: NoseShape) -> Self {
221        self.shape = shape;
222        self
223    }
224
225    /// The same transition with its profile cut from a whole nose cone (`true`), or scaled
226    /// between its two radii (`false`, as [`Transition::conical`] makes it):
227    /// [`hpr_design::Transition::clipped`]. A conical or tangent-ogive transition is the same
228    /// either way.
229    #[must_use]
230    pub fn with_clipped(mut self, clipped: bool) -> Self {
231        self.clipped = clipped;
232        self
233    }
234
235    /// The same transition, solid.
236    #[must_use]
237    pub fn solid(mut self) -> Self {
238        self.wall = Wall::Filled {};
239        self
240    }
241
242    /// The same transition with `name`, which the design file keeps.
243    #[must_use]
244    pub fn named(mut self, name: &str) -> Self {
245        name.clone_into(&mut self.name);
246        self
247    }
248}
249
250/// A set of identical fins spaced evenly around the last body tube, flush with its aft end
251/// unless placed elsewhere with [`Fins::at`]. Their edges are square unless
252/// [`Fins::with_cross_section`] says otherwise.
253#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
254pub struct Fins {
255    set: FinSet,
256    position: Position,
257    name: String,
258}
259
260impl Fins {
261    /// `count` fins of the shape `planform`, `thickness_m` thick. The planform names its
262    /// dimensions: a trapezoid's root and tip chords, its span, and how far aft of the root's
263    /// leading edge the tip's is ([`FinPlanform`]).
264    ///
265    /// ```
266    /// use hpr::FinPlanform;
267    /// use hpr::rocket::{Fins, material};
268    ///
269    /// let planform = FinPlanform::Trapezoidal {
270    ///     root_chord_m: 0.1,
271    ///     tip_chord_m: 0.04,
272    ///     span_m: 0.045,
273    ///     sweep_m: 0.05,
274    /// };
275    /// let fins = Fins::new(3, planform, 0.003175, material("birch_plywood")?);
276    /// # Ok::<(), hpr::Error>(())
277    /// ```
278    #[must_use]
279    pub fn new(count: u32, planform: FinPlanform, thickness_m: f64, material: Material) -> Self {
280        Self {
281            set: FinSet {
282                count,
283                planform,
284                thickness_m,
285                cross_section: FinCrossSection::Square,
286                tab: None,
287                fillet: None,
288                cant_rad: 0.0,
289                base_angle_rad: 0.0,
290                material,
291            },
292            position: Position::Bottom { aft_offset_m: 0.0 },
293            name: String::new(),
294        }
295    }
296
297    /// The same fins with edges shaped `cross_section`: square, rounded or an airfoil. It changes
298    /// their drag.
299    #[must_use]
300    pub fn with_cross_section(mut self, cross_section: FinCrossSection) -> Self {
301        self.set.cross_section = cross_section;
302        self
303    }
304
305    /// The same fins canted by `cant_deg`, which spins the rocket (the sign convention is
306    /// [`FinSet::cant_rad`]'s).
307    #[must_use]
308    pub fn with_cant_deg(mut self, cant_deg: f64) -> Self {
309        self.set.cant_rad = cant_deg.to_radians();
310        self
311    }
312
313    /// The same fins at `position` along their tube: [`Position`] places their root's leading
314    /// edge (`Top`, `After`, `Absolute`), its trailing edge (`Bottom`) or its middle (`Middle`).
315    #[must_use]
316    pub fn at(mut self, position: Position) -> Self {
317        self.position = position;
318        self
319    }
320
321    /// The same fins with `name`, which the design file keeps.
322    #[must_use]
323    pub fn named(mut self, name: &str) -> Self {
324        name.clone_into(&mut self.name);
325        self
326    }
327}
328
329/// The tube inside the airframe that holds the motor, flush with the last body tube's aft end
330/// unless placed elsewhere with [`MotorTube::at`].
331#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
332pub struct MotorTube {
333    length_m: f64,
334    inner_diameter_m: f64,
335    wall_m: f64,
336    overhang_m: f64,
337    position: Position,
338    material: Material,
339    name: String,
340}
341
342impl MotorTube {
343    /// A motor tube `length_m` long, with a bore of `inner_diameter_m` and a wall `wall_m` thick.
344    #[must_use]
345    pub fn new(length_m: f64, inner_diameter_m: f64, wall_m: f64, material: Material) -> Self {
346        Self {
347            length_m,
348            inner_diameter_m,
349            wall_m,
350            overhang_m: 0.0,
351            position: Position::Bottom { aft_offset_m: 0.0 },
352            material,
353            name: String::new(),
354        }
355    }
356
357    /// The same tube with the motor's aft end `overhang_m` past the tube's.
358    #[must_use]
359    pub fn with_overhang_m(mut self, overhang_m: f64) -> Self {
360        self.overhang_m = overhang_m;
361        self
362    }
363
364    /// The same tube at `position` along the body tube it is in.
365    #[must_use]
366    pub fn at(mut self, position: Position) -> Self {
367        self.position = position;
368        self
369    }
370
371    /// The same tube with `name`, which the design file keeps.
372    #[must_use]
373    pub fn named(mut self, name: &str) -> Self {
374        name.clone_into(&mut self.name);
375        self
376    }
377}
378
379/// A mass inside the last body tube: a parachute and its cord, an altimeter bay, ballast.
380///
381/// It is a solid cylinder along the axis, as long and as wide as its packing, or a point until
382/// [`Mass::packed`] gives it a size. Its [`Position`] places the packing's fore end (`Top`,
383/// `After`, `Absolute`), its aft end (`Bottom`) or its middle (`Middle`). So packing a mass
384/// moves its center by half the packed length, unless it is placed by its middle.
385#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
386pub struct Mass {
387    mass_kg: f64,
388    position: Position,
389    packed_length_m: f64,
390    packed_diameter_m: f64,
391    name: String,
392}
393
394impl Mass {
395    /// `mass_kg` at `position` along the body tube it is in.
396    #[must_use]
397    pub fn new(mass_kg: f64, position: Position) -> Self {
398        Self {
399            mass_kg,
400            position,
401            packed_length_m: 0.0,
402            packed_diameter_m: 0.0,
403            name: String::new(),
404        }
405    }
406
407    /// The same mass packed in a cylinder `length_m` long and `diameter_m` across.
408    #[must_use]
409    pub fn packed(mut self, length_m: f64, diameter_m: f64) -> Self {
410        self.packed_length_m = length_m;
411        self.packed_diameter_m = diameter_m;
412        self
413    }
414
415    /// The same mass with `name`, which the design file keeps.
416    #[must_use]
417    pub fn named(mut self, name: &str) -> Self {
418        name.clone_into(&mut self.name);
419        self
420    }
421}
422
423/// A rocket: its design, its motor and its recovery devices.
424///
425/// It serializes, for a record of what was flown, but doesn't deserialize: the builder's methods
426/// check what goes in, so a rocket is built with them, or read from a design with
427/// [`Rocket::from_design`].
428///
429/// ```
430/// use hpr::rocket::{Fins, Mass, MotorTube, Nose, Tube, material};
431/// use hpr::{FinPlanform, Motor, NoseShape, Position, Rocket};
432///
433/// let mut rocket = Rocket::new("Small", 0.0563)?;
434/// let ogive = NoseShape::Ogive { radius_ratio: 1.0 };
435/// let planform = FinPlanform::Trapezoidal {
436///     root_chord_m: 0.1,
437///     tip_chord_m: 0.04,
438///     span_m: 0.045,
439///     sweep_m: 0.05,
440/// };
441/// rocket
442///     .add_nose(Nose::hollow(ogive, 0.22, 0.0015, material("abs")?))?
443///     .add_tube(Tube::new(0.9, 0.00115, material("kraft_phenolic")?))?
444///     .add_fins(Fins::new(3, planform, 0.003175, material("birch_plywood")?))?
445///     .add_motor_tube(MotorTube::new(0.2, 0.029, 0.001, material("kraft_phenolic")?))?
446///     .set_motor(Motor::from_catalog("H54")?)?;
447///
448/// // Unstable as it stands: the motor's weight puts the center of gravity behind the center of
449/// // pressure, and the margin, in calibers, is negative.
450/// assert!(rocket.static_margin_cal(0.0, 0.3)?.is_some_and(|margin| margin < 0.0));
451/// // 200 g near the top of the tube, a recovery bay, brings it forward of it.
452/// rocket.add_mass(Mass::new(0.2, Position::Top { aft_offset_m: 0.07 }))?;
453/// assert!(rocket.static_margin_cal(0.0, 0.3)?.is_some_and(|margin| margin > 1.0));
454/// # Ok::<(), hpr::Error>(())
455/// ```
456#[derive(Debug, Clone, PartialEq, Serialize)]
457pub struct Rocket {
458    design: hpr_design::Rocket,
459    configuration_id: Option<String>,
460    recovery: Vec<Device>,
461    /// Where the builder has got to; `None` for a rocket read from a design. Not part of the
462    /// record.
463    #[serde(skip)]
464    build: Option<Build>,
465}
466
467/// The builder's place in the tree.
468#[derive(Debug, Clone, PartialEq)]
469struct Build {
470    /// The rocket's body diameter, m.
471    diameter_m: f64,
472    /// The last body part's aft radius, m; `None` before the first.
473    aft_radius_m: Option<f64>,
474    /// The index of the last body tube among the stage's components.
475    tube: Option<usize>,
476    /// The motor tube's component id, once there is one.
477    motor_tube: Option<String>,
478}
479
480/// The id of the stage the builder makes.
481const STAGE_ID: &str = "sustainer";
482
483impl Rocket {
484    /// An empty rocket called `name`, of outer body diameter `diameter_m`: the nose's base
485    /// diameter, and the first tube's, unless they say otherwise (a catalog part states its
486    /// own). Its reference diameter, the one
487    /// the stability margin is counted in, is its largest body diameter.
488    ///
489    /// # Errors
490    ///
491    /// [`Error::Domain`] for a diameter that isn't finite and positive.
492    pub fn new(name: &str, diameter_m: f64) -> Result<Self, Error> {
493        Ok(Self {
494            design: hpr_design::Rocket {
495                name: name.to_owned(),
496                stages: vec![Stage {
497                    id: STAGE_ID.to_owned(),
498                    name: String::new(),
499                    components: Vec::new(),
500                    overrides: Overrides::default(),
501                    override_rule: Default::default(),
502                    added_mass: None,
503                    drag_override: None,
504                    parallel: None,
505                }],
506                reference_diameter: ReferenceDiameter::Maximum {},
507                configurations: Vec::new(),
508            },
509            configuration_id: None,
510            recovery: Vec::new(),
511            build: Some(Build {
512                diameter_m: positive("rocket diameter, m", diameter_m)?,
513                aft_radius_m: None,
514                tube: None,
515                motor_tube: None,
516            }),
517        })
518    }
519
520    /// A rocket from a design you already have, flown in its configuration `configuration_id`:
521    /// a design file read with `serde_json`, an OpenRocket file read with [`hpr_io::ork`], or a
522    /// built rocket's [`Rocket::design`] changed with [`hpr_design`] to hold what the builder
523    /// can't, such as a cluster or pods. Parts can't be added to it; recovery devices can.
524    ///
525    /// # Errors
526    ///
527    /// [`Error::NoSuchConfiguration`] if the design has no configuration of that id.
528    pub fn from_design(design: hpr_design::Rocket, configuration_id: &str) -> Result<Self, Error> {
529        if design.configuration(configuration_id).is_none() {
530            return Err(Error::NoSuchConfiguration(configuration_id.to_owned()));
531        }
532        Ok(Self {
533            design,
534            configuration_id: Some(configuration_id.to_owned()),
535            recovery: Vec::new(),
536            build: None,
537        })
538    }
539
540    /// Adds the nose cone, which goes first.
541    ///
542    /// # Errors
543    ///
544    /// - [`Error::Order`] if a body part is already in place, or the rocket was read from a
545    ///   design.
546    /// - [`Error::Domain`] for a diameter, length, wall or shoulder dimension that isn't finite
547    ///   and positive, or a shoulder wall thicker than its stated radius; [`Error::Design`] for a
548    ///   shape whose parameter is out of its range.
549    pub fn add_nose(&mut self, nose: Nose) -> Result<&mut Self, Error> {
550        let build = self.build()?;
551        if build.aft_radius_m.is_some() {
552            return Err(Error::Order(Order::NoseNotFirst));
553        }
554        let radius_m = 0.5
555            * positive(
556                "nose diameter, m",
557                nose.diameter_m.unwrap_or(build.diameter_m),
558            )?;
559        positive("nose length, m", nose.length_m)?;
560        check_wall("nose wall, m", nose.wall)?;
561        Profile::nose(nose.shape, nose.length_m, radius_m)?;
562        let mut auto = Vec::new();
563        if let Some(shoulder) = &nose.shoulder {
564            check_shoulder(&NOSE_SHOULDER, shoulder)?;
565            if shoulder.outer_radius_m == 0.0 {
566                auto.push(AutoDimension::ShoulderRadius);
567            }
568        }
569        let part = Part::NoseCone(NoseCone {
570            shape: nose.shape,
571            length_m: nose.length_m,
572            base_radius_m: radius_m,
573            wall: nose.wall,
574            shoulder: nose.shoulder,
575            material: nose.material,
576        });
577        let mut component = self.component("nose", &nose.name, part, None);
578        component.auto = auto;
579        self.push_body(component, radius_m, false)?;
580        Ok(self)
581    }
582
583    /// Adds a body tube behind the last body part.
584    ///
585    /// # Errors
586    ///
587    /// - [`Error::Order`] if the rocket was read from a design.
588    /// - [`Error::Domain`] for a length, wall or diameter that isn't finite and positive.
589    pub fn add_tube(&mut self, tube: Tube) -> Result<&mut Self, Error> {
590        let build = self.build()?;
591        let before_m = build
592            .aft_radius_m
593            .map_or(build.diameter_m, |radius_m| 2.0 * radius_m);
594        let diameter_m = positive("tube diameter, m", tube.diameter_m.unwrap_or(before_m))?;
595        let part = Part::BodyTube(BodyTube {
596            length_m: positive("tube length, m", tube.length_m)?,
597            outer_radius_m: 0.5 * diameter_m,
598            thickness_m: positive("tube wall, m", tube.wall_m)?,
599            material: tube.material,
600        });
601        let component = self.component("tube", &tube.name, part, None);
602        self.push_body(component, 0.5 * diameter_m, true)?;
603        Ok(self)
604    }
605
606    /// Adds a transition behind the last body part, starting at its diameter unless it states its
607    /// own (a catalog part does).
608    ///
609    /// # Errors
610    ///
611    /// - [`Error::Order`] if there is no body part before it, or the rocket was read from a
612    ///   design.
613    /// - [`Error::Domain`] for a length, wall, stated fore diameter or shoulder dimension that
614    ///   isn't finite and positive, an aft diameter that is negative or not finite, or a
615    ///   shoulder wall thicker than its radius; [`Error::Design`] for a shape whose parameter is
616    ///   out of its range.
617    pub fn add_transition(&mut self, transition: Transition) -> Result<&mut Self, Error> {
618        let before_radius_m = self
619            .build()?
620            .aft_radius_m
621            .ok_or(Error::Order(Order::NothingBeforeTransition))?;
622        let fore_radius_m = match transition.fore_diameter_m {
623            Some(diameter_m) => 0.5 * positive("transition fore diameter, m", diameter_m)?,
624            None => before_radius_m,
625        };
626        positive("transition length, m", transition.length_m)?;
627        check_wall("transition wall, m", transition.wall)?;
628        let aft_radius_m =
629            0.5 * non_negative("transition aft diameter, m", transition.aft_diameter_m)?;
630        Profile::transition(
631            transition.shape,
632            transition.length_m,
633            fore_radius_m,
634            aft_radius_m,
635            transition.clipped,
636        )?;
637        for shoulder in [&transition.fore_shoulder, &transition.aft_shoulder]
638            .into_iter()
639            .flatten()
640        {
641            // A transition's shoulders state their radius: the builder finds none for them.
642            positive("transition shoulder radius, m", shoulder.outer_radius_m)?;
643            check_shoulder(&TRANSITION_SHOULDER, shoulder)?;
644        }
645        let part = Part::Transition(hpr_design::Transition {
646            shape: transition.shape,
647            clipped: transition.clipped,
648            length_m: transition.length_m,
649            fore_radius_m,
650            aft_radius_m,
651            wall: transition.wall,
652            fore_shoulder: transition.fore_shoulder,
653            aft_shoulder: transition.aft_shoulder,
654            material: transition.material,
655        });
656        let component = self.component("transition", &transition.name, part, None);
657        self.push_body(component, aft_radius_m, false)?;
658        Ok(self)
659    }
660
661    /// Adds a fin set to the last body tube.
662    ///
663    /// # Errors
664    ///
665    /// - [`Error::Order`] if there is no body tube yet, or the rocket was read from a design.
666    /// - [`Error::Design`] for fins the design refuses ([`FinSet::validate`]): no fins, a chord,
667    ///   span or thickness that isn't finite and positive, and the like.
668    /// - [`Error::Domain`] for a position that isn't finite.
669    pub fn add_fins(&mut self, fins: Fins) -> Result<&mut Self, Error> {
670        fins.set.validate()?;
671        check_position(fins.position)?;
672        let component = self.component(
673            "fins",
674            &fins.name,
675            Part::FinSet(fins.set),
676            Some(fins.position),
677        );
678        self.attach(component)?;
679        Ok(self)
680    }
681
682    /// Adds the motor tube to the last body tube. A rocket has one.
683    ///
684    /// # Errors
685    ///
686    /// - [`Error::Order`] if there is no body tube yet, the rocket has a motor tube already, or
687    ///   it was read from a design.
688    /// - [`Error::Domain`] for a length, bore or wall that isn't finite and positive, an overhang
689    ///   that is negative or not finite, or a position that isn't finite.
690    pub fn add_motor_tube(&mut self, tube: MotorTube) -> Result<&mut Self, Error> {
691        if self.build()?.motor_tube.is_some() {
692            return Err(Error::Order(Order::SecondMotorTube));
693        }
694        let wall_m = positive("motor tube wall, m", tube.wall_m)?;
695        let part = Part::InnerTube(InnerTube {
696            length_m: positive("motor tube length, m", tube.length_m)?,
697            outer_radius_m: 0.5 * positive("motor tube bore, m", tube.inner_diameter_m)? + wall_m,
698            thickness_m: wall_m,
699            radial_offset_m: 0.0,
700            angle_rad: 0.0,
701            material: tube.material,
702            cluster_m: Vec::new(),
703        });
704        check_position(tube.position)?;
705        let mut component = self.component("motor-tube", &tube.name, part, Some(tube.position));
706        component.motor_mount = Some(MotorMount {
707            overhang_m: non_negative("motor overhang, m", tube.overhang_m)?,
708        });
709        let id = component.id.clone();
710        self.attach(component)?;
711        if let Some(build) = &mut self.build {
712            build.motor_tube = Some(id);
713        }
714        Ok(self)
715    }
716
717    /// Adds a mass inside the last body tube.
718    ///
719    /// # Errors
720    ///
721    /// - [`Error::Order`] if there is no body tube yet, or the rocket was read from a design.
722    /// - [`Error::Domain`] for a mass or packing that is negative or not finite, or a position
723    ///   that isn't finite.
724    pub fn add_mass(&mut self, mass: Mass) -> Result<&mut Self, Error> {
725        non_negative("mass, kg", mass.mass_kg)?;
726        non_negative("packed length, m", mass.packed_length_m)?;
727        non_negative("packed diameter, m", mass.packed_diameter_m)?;
728        check_position(mass.position)?;
729        let part = Part::MassComponent(MassComponent {
730            mass_kg: mass.mass_kg,
731            packing: Packing {
732                length_m: mass.packed_length_m,
733                radius_m: 0.5 * mass.packed_diameter_m,
734                radial_offset_m: 0.0,
735                angle_rad: 0.0,
736            },
737        });
738        let component = self.component("mass", &mass.name, part, Some(mass.position));
739        self.attach(component)?;
740        Ok(self)
741    }
742
743    /// Adds a fitting to the last body tube: a coupler, a centering ring, a bulkhead, a launch
744    /// lug, or a packed parachute or streamer.
745    ///
746    /// # Errors
747    ///
748    /// - [`Error::Order`] if there is no body tube yet, the rocket was read from a design, or the
749    ///   fitting holds a part of another kind (one read from a file).
750    /// - [`Error::Design`] for a part the design can't weigh: a size that is negative or not
751    ///   finite, a ring whose bore reaches its rim, a wall thicker than its tube's radius, a
752    ///   material of the wrong kind. A tube with a wall of zero, or a parachute or streamer of
753    ///   no size, weighs nothing and is taken.
754    /// - [`Error::Domain`] for a position that isn't finite.
755    pub fn add_fitting(&mut self, fitting: Fitting) -> Result<&mut Self, Error> {
756        let id = fitting.id().ok_or(Error::Order(Order::NotAFitting))?;
757        let (part, position, name) = fitting.into_parts();
758        check_position(position)?;
759        // Weighed now, on the tube it goes on, so a part the design can't take is refused where
760        // it is added.
761        part.mass_properties(Some(self.tube_radius_m()?))?;
762        let component = self.component(id, &name, part, Some(position));
763        self.attach(component)?;
764        Ok(self)
765    }
766
767    /// Puts `motor` in the motor tube, lit at launch, in place of any motor there before. The
768    /// design's one configuration is named after its designation.
769    ///
770    /// # Errors
771    ///
772    /// [`Error::Order`] if there is no motor tube yet, or the rocket was read from a design.
773    pub fn set_motor(&mut self, motor: Motor) -> Result<&mut Self, Error> {
774        let mount = self
775            .build()?
776            .motor_tube
777            .clone()
778            .ok_or(Error::Order(Order::NoMotorTube))?;
779        let id = motor.designation().to_owned();
780        self.design.configurations = vec![Configuration {
781            id: id.clone(),
782            name: String::new(),
783            motors: vec![MountedMotor {
784                mount,
785                designation: id.clone(),
786                diameter_m: motor.diameter_m(),
787                length_m: motor.length_m(),
788                motor: motor.solid_motor().clone(),
789                delay: motor.delay(),
790                ignition: Ignition::Launch,
791                failed_tubes: Vec::new(),
792            }],
793        }];
794        self.configuration_id = Some(id);
795        Ok(self)
796    }
797
798    /// Adds a recovery device: a parachute, a streamer or a tumble, with what opens it.
799    /// [`Trigger::MotorDelay`](hpr_sim::Trigger::MotorDelay) with motor 0, the first motor, opens
800    /// it at the motor's ejection charge, which needs the motor's delay set
801    /// ([`Motor::with_delay_s`]). The device adds drag, not mass: add its mass with
802    /// [`Rocket::add_mass`], or a catalog parachute's with [`Fitting::from_catalog`].
803    pub fn add_parachute(&mut self, device: Device) -> &mut Self {
804        self.recovery.push(device);
805        self
806    }
807
808    /// The design: the same tree a design file holds.
809    #[must_use]
810    pub fn design(&self) -> &hpr_design::Rocket {
811        &self.design
812    }
813
814    /// The configuration the rocket flies in: the motor's designation for a built rocket, `None`
815    /// before it has a motor.
816    #[must_use]
817    pub fn configuration_id(&self) -> Option<&str> {
818        self.configuration_id.as_deref()
819    }
820
821    /// The recovery devices, in the order they were added.
822    #[must_use]
823    pub fn recovery(&self) -> &[Device] {
824        &self.recovery
825    }
826
827    /// The parts placed and the motor in its tube ([`hpr_design::Rocket::assemble`]), once the
828    /// design's checks ([`hpr_design::checks`]) find no errors: the same checks a flight runs
829    /// with the default settings, so what this weighs is what [`crate::Flight`] would fly. A
830    /// flight told to accept a design's errors
831    /// ([`FlightSettings::accept_design_errors`](hpr_sim::FlightSettings::accept_design_errors))
832    /// flies what this refuses; `design().assemble(id)` weighs it.
833    ///
834    /// # Errors
835    ///
836    /// - [`Error::NoMotor`] before the rocket has a motor.
837    /// - [`Error::DesignChecks`] with every finding if the checks find an error, such as a motor
838    ///   wider than its tube's bore or a motor tube wider than the airframe.
839    /// - [`Error::Design`] for a tree that doesn't hold together.
840    pub fn assemble(&self) -> Result<Assembly, Error> {
841        let id = self.configuration_id.as_deref().ok_or(Error::NoMotor)?;
842        let findings = check(&self.design)?;
843        if has_errors(&findings) {
844            return Err(Error::DesignChecks(findings));
845        }
846        Ok(self.design.assemble(id)?)
847    }
848
849    /// The mass, center of gravity and inertia `time_s` seconds after the motor lights, the
850    /// motor burning as its thrust curve says. The center of gravity is in the body frame: `z`
851    /// points to the nose and is zero at its tip, so a point `s` meters aft of the tip is at
852    /// `z = −s` (`docs/physics/frames.md`).
853    ///
854    /// # Errors
855    ///
856    /// As [`Rocket::assemble`], and [`Error::Domain`] for a time that is negative or not finite.
857    pub fn mass_properties(&self, time_s: f64) -> Result<MassProperties, Error> {
858        let time_s = non_negative("time, s", time_s)?;
859        Ok(self.assemble()?.mass_properties(time_s))
860    }
861
862    /// The static stability margin `time_s` seconds after the motor lights, at Mach `mach` with
863    /// the air along the axis, in the rocket's weakest plane ([`Rocket::margin`]), calibers of the
864    /// reference diameter: how far the center of pressure is behind the center of gravity. `None`
865    /// where [`hpr_sim::metrics::margin`] leaves it
866    /// undefined: a normal force that doesn't restore, or a center of pressure too ill-conditioned
867    /// to place. [`Rocket::margin`] gives the rest of it.
868    ///
869    /// # Errors
870    ///
871    /// As [`Rocket::margin`].
872    pub fn static_margin_cal(&self, time_s: f64, mach: f64) -> Result<Option<f64>, Error> {
873        Ok(self.margin(time_s, mach)?.margin_cal)
874    }
875
876    /// The center of pressure and the static margin `time_s` seconds after the motor lights, at
877    /// Mach `mach` with the air along the axis, in the weakest plane the air can cross the rocket
878    /// in ([`hpr_sim::metrics::weakest_margin`]): a rocket with a fin set of one or two fins has a
879    /// margin in each plane, and the least is the one to trust. Its center of pressure is a
880    /// station: meters aft of the nose tip, positive.
881    ///
882    /// # Errors
883    ///
884    /// As [`Rocket::mass_properties`], [`Error::Aero`] for a rocket the aerodynamic model can't
885    /// take, and [`Error::Sim`] for a Mach number out of its range.
886    pub fn margin(&self, time_s: f64, mach: f64) -> Result<Margin, Error> {
887        let time_s = non_negative("time, s", time_s)?;
888        let assembly = self.assemble()?;
889        let cg_station_m = -assembly.mass_properties(time_s).cg_m.z;
890        let aero = AeroModel::new(&assembly.layout)?;
891        Ok(metrics::weakest_margin(&aero, mach, cg_station_m)?)
892    }
893
894    /// The builder's place, or [`Error::Order`] for a rocket read from a design.
895    fn build(&self) -> Result<&Build, Error> {
896        self.build
897            .as_ref()
898            .ok_or(Error::Order(Order::ReadFromDesign))
899    }
900
901    /// The builder's stage: its one, the first.
902    fn stage(&mut self) -> Result<&mut Stage, Error> {
903        self.design
904            .stages
905            .first_mut()
906            .ok_or(Error::Order(Order::ReadFromDesign))
907    }
908
909    /// A component of the stage, its id `kind` or, if that is taken, `kind-2`, `kind-3` and on.
910    fn component(
911        &self,
912        kind: &str,
913        name: &str,
914        part: Part,
915        position: Option<Position>,
916    ) -> Component {
917        let mut ids = Vec::new();
918        for stage in &self.design.stages {
919            for component in &stage.components {
920                ids.push(component.id.as_str());
921                ids.extend(component.children.iter().map(|child| child.id.as_str()));
922            }
923        }
924        let mut id = kind.to_owned();
925        let mut n = 1;
926        while ids.contains(&id.as_str()) {
927            n += 1;
928            id = format!("{kind}-{n}");
929        }
930        Component {
931            id,
932            name: name.to_owned(),
933            part,
934            position,
935            auto: Vec::new(),
936            motor_mount: None,
937            finish: None,
938            overrides: Overrides::default(),
939            overrides_include_children: false,
940            drag_override: None,
941            children: Vec::new(),
942        }
943    }
944
945    /// Adds a body component with aft radius `aft_radius_m`; a `tube` takes the attached parts
946    /// that follow.
947    fn push_body(
948        &mut self,
949        component: Component,
950        aft_radius_m: f64,
951        tube: bool,
952    ) -> Result<(), Error> {
953        let components = &mut self.stage()?.components;
954        components.push(component);
955        let index = components.len() - 1;
956        if let Some(build) = &mut self.build {
957            build.aft_radius_m = Some(aft_radius_m);
958            if tube {
959                build.tube = Some(index);
960            }
961        }
962        Ok(())
963    }
964
965    /// The last body tube's outer radius, m.
966    fn tube_radius_m(&self) -> Result<f64, Error> {
967        let index = self.build()?.tube.ok_or(Error::Order(Order::NoTube))?;
968        match self
969            .design
970            .stages
971            .first()
972            .and_then(|stage| stage.components.get(index))
973            .map(|component| &component.part)
974        {
975            Some(Part::BodyTube(tube)) => Ok(tube.outer_radius_m),
976            _ => Err(Error::Order(Order::NoTube)),
977        }
978    }
979
980    /// Attaches `component` to the last body tube.
981    fn attach(&mut self, component: Component) -> Result<(), Error> {
982        let index = self.build()?.tube.ok_or(Error::Order(Order::NoTube))?;
983        self.stage()?
984            .components
985            .get_mut(index)
986            .ok_or(Error::Order(Order::NoTube))?
987            .children
988            .push(component);
989        Ok(())
990    }
991}
992
993/// A wall's thickness, if it has one, checked finite and positive.
994fn check_wall(what: &'static str, wall: Wall) -> Result<(), Error> {
995    if let Wall::Shell { thickness_m } = wall {
996        positive(what, thickness_m)?;
997    }
998    Ok(())
999}
1000
1001/// A shoulder's length and wall, checked finite and positive, and, where its outer radius is
1002/// stated (zero is the tube's, found later), that radius too, with the wall no thicker than it.
1003/// `names` names those four numbers in an error: [`NOSE_SHOULDER`], [`TRANSITION_SHOULDER`].
1004fn check_shoulder(names: &[&'static str; 4], shoulder: &Shoulder) -> Result<(), Error> {
1005    let [length, wall, radius, past] = *names;
1006    positive(length, shoulder.length_m)?;
1007    positive(wall, shoulder.thickness_m)?;
1008    if shoulder.outer_radius_m != 0.0 {
1009        positive(radius, shoulder.outer_radius_m)?;
1010        if shoulder.thickness_m > shoulder.outer_radius_m {
1011            return Err(Error::Domain {
1012                what: past,
1013                value: shoulder.thickness_m,
1014                allowed: "no more than the shoulder's radius",
1015            });
1016        }
1017    }
1018    Ok(())
1019}
1020
1021/// A nose shoulder's numbers, as [`check_shoulder`] names them.
1022const NOSE_SHOULDER: [&str; 4] = [
1023    "nose shoulder length, m",
1024    "nose shoulder wall, m",
1025    "nose shoulder radius, m",
1026    "nose shoulder wall past its radius, m",
1027];
1028
1029/// A transition shoulder's numbers, as [`check_shoulder`] names them.
1030const TRANSITION_SHOULDER: [&str; 4] = [
1031    "transition shoulder length, m",
1032    "transition shoulder wall, m",
1033    "transition shoulder radius, m",
1034    "transition shoulder wall past its radius, m",
1035];
1036
1037/// A position's offset or station, checked finite.
1038fn check_position(position: Position) -> Result<(), Error> {
1039    let (Position::Top {
1040        aft_offset_m: value,
1041    }
1042    | Position::Middle {
1043        aft_offset_m: value,
1044    }
1045    | Position::Bottom {
1046        aft_offset_m: value,
1047    }
1048    | Position::After {
1049        aft_offset_m: value,
1050    }
1051    | Position::Absolute { station_m: value }) = position;
1052    finite("position, m", value)?;
1053    Ok(())
1054}