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}