Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Getting started

Install HPR Sim, fly a first rocket from the rail to the ground with a short Rust program, and learn to change it.

This page takes you from nothing to a first simulated flight. You install Rust, build HPR Sim, and run a short program. It flies a rocket from the launch rail to the ground and prints what happened. Then the page walks through that program, so you can change it and fly your own variations. It needs some Rust, but no knowledge of this project.

The drag and the drift in a wind are the least certain numbers it prints (Accuracy of these numbers).

Setting up

Install a release, or gather what you need to build HPR Sim yourself.

Install a release

Release 0.1.0 is out. Each part installs without a copy of the repository. The rest of this page builds HPR Sim from the repository instead, which works too.

Release 0.1 has files for Linux on x86-64, Macs with Apple silicon, and Windows on x86-64. From release 0.2 there are also files for Linux on 64-bit ARM and Windows on ARM. Intel Macs aren’t built yet (issue #438).

  • A package manager installs the command line, hpr, and keeps it up to date, or you can download it yourself. Packages for winget and conda-forge are planned (issue #434). Whichever way you install it, the command is hpr. hpr --version shows the install worked: it prints FusionSpace HPR and the version. The command line documents its commands.
    • Homebrew, on a Mac with Apple silicon or on Linux on x86-64, and on Linux on 64-bit ARM from release 0.2: brew install nrdptel/tap/fusionspace-hpr. Naming the tap in full adds it, so there’s no separate brew tap step. brew upgrade takes each new release.
    • Scoop, on Windows on x86-64, and on Windows on ARM from release 0.2: scoop bucket add fusionspace https://github.com/nrdptel/scoop-bucket once, then scoop install fusionspace/fusionspace-hpr. scoop update fusionspace-hpr takes each new release.
    • cargo binstall, with Rust and cargo-binstall installed: cargo binstall fusionspace-hpr-cli downloads the release’s archive instead of compiling. Where it finds no archive, it compiles the crate, as cargo install does. That happens for releases before 0.2, whose crate on crates.io lacks the lines that point it at the archives. It happens on an Intel Mac too, until issue #438.
    • By hand. Download the archive for your system from the releases page, unpack it, and put hpr on your path. Each is named fusionspace-hpr-<version>-<system>, and the package managers install the same files.
    • From source, anywhere else, or with Rust installed: cargo install fusionspace-hpr-cli --locked builds it.
  • The Python package installs with pip install fusionspace-hpr, and it imports as fusionspace.hpr: from fusionspace import hpr. One wheel serves CPython 3.10 and later on each of those systems (3.11 on Windows on ARM, its oldest). Elsewhere pip builds it from source, which needs Rust (Python).
  • For your own Rust program, cargo add fusionspace-hpr adds the library’s front-door crate. A program uses it as hpr (use hpr::Rocket;), and it re-exports the others (The builder; the API reference).

Each archive and wheel holds the project’s two licenses and the license texts of everything compiled into it. How a release is built lists the files and the checks each passed. The changelog says what 0.1.0 does, how far to trust it, and its known gaps.

Three cautions for the downloaded archives:

  • macOS may say it can’t check hpr for malicious software, since the program isn’t notarized by Apple. To allow it, run xattr -d com.apple.quarantine hpr in the folder you unpacked it into. This applies to an archive downloaded in a web browser. Homebrew doesn’t mark a formula’s download for that check, so an hpr it installs runs as it is.

  • The Linux files are for x86-64 and need the GNU C library (glibc) 2.17 or later. Run ldd --version: its first line ends in your glibc’s version. By their glibc, that means RHEL and CentOS 7, Debian 8, Ubuntu 14.04 and anything newer. The release’s checks run on a CentOS 7 image, and the others aren’t run one by one.

    On an older glibc the program stops with version 'GLIBC_2.xx' not found. There, or on a distribution built on musl such as Alpine, build from source. cargo install fusionspace-hpr-cli --locked builds the command line (What you need), and pip builds the Python package. Homebrew and cargo binstall install the same program on Linux, so the same floor applies to them.

  • On Windows, release 0.2’s hpr.exe runs on a clean Windows, since the C runtime is built into it. Release 0.1.0’s needs Microsoft’s Visual C++ Redistributable, a free package of runtime libraries. If Windows says VCRUNTIME140.dll was not found, install the Redistributable for 0.1.0’s x86-64 build with winget install Microsoft.VCRedist.2015+.x64. With Scoop, scoop bucket add extras then scoop install vcredist2022 does the same. extras is Scoop’s own bucket, separate from the fusionspace one above.

What you need

  • Rust, through rustup, Rust’s installer. The repository pins the version it’s built with (in rust-toolchain.toml), and rustup installs that version the first time you build.
  • Your system’s C build tools, which Rust uses to link programs. You may have them already:
    • On Windows, the Microsoft C++ build tools, from Visual Studio. The rustup installer checks for them and says how to get them.
    • On macOS, Apple’s command-line developer tools. If git or cc is missing, install them with xcode-select --install; they include Git.
    • On Linux, a C compiler such as gcc, which most distributions have. On Debian and Ubuntu it comes with the build-essential package.
  • Git, to fetch the code.
  • A network connection the first time, to download Rust and the libraries the simulator uses. After that, everything here works offline, on macOS, Windows and Linux.

Nothing else: no Python, Java or other simulator.

Your first flight

Build HPR Sim, fly the example rocket, and read what it printed and how accurate those numbers are.

Build it and fly

git clone https://github.com/nrdptel/fusionspace-eridanus.git
cd fusionspace-eridanus
cargo run --example first_flight -p fusionspace-hpr-sim

The first run compiles the simulator and its libraries, which takes a few minutes; later runs start at once. The last command runs the program crates/hpr-sim/examples/first_flight.rs.

In that command, --example first_flight names the program. -p fusionspace-hpr-sim (short for --package) names the crate that holds it, one of the repository’s Rust packages: the crate that flies the rocket. Code calls it hpr_sim (use hpr_sim::…). Every fusionspace-hpr* package keeps its short name in code (the crates). The program prints this:

Valetudo on a K400C: 9.67 kg at liftoff, a 3 m rail, 5 m/s of wind from 270°
Not yet validated: see the Accuracy page before trusting these numbers.

event                time (s)   CG height (m)   speed (m/s)
liftoff                  0.00             0.9           0.0
rail exit                0.37             3.9          16.2
burnout                  3.26           216.0         111.0
apogee                  13.83           778.7           6.4
drogue charge fires     13.83           778.7           6.4
drogue opens            14.33           777.6           7.7
main charge fires       39.23           150.0          27.0
main opens              40.23           123.5          27.0
landing                 58.93             0.0           8.1

Apogee:     778.7 m (2555 ft) above the pad, 88.7 m from it at a bearing of 270°, at 13.83 s
Top speed:  112.3 m/s (Mach 0.34), at 3.0 s
Rail exit:  16.2 m/s
Landing:    90.2 m from the pad at a bearing of 90°, falling at 6.4 m/s, at 58.93 s

The heights are the center of gravity’s, above the launch site. Flight metrics gives the peaks, the stability margin through the climb, the best ejection delay and the landing’s latitude and longitude. Its example flies this rocket with one parachute.

You should see exactly these numbers. The project’s automated checks (CI, for continuous integration) run the program on macOS, Windows and Linux on every change. They fail if it prints anything but what is committed in first_flight.output.txt, the file quoted above.

What it printed

The rocket is Valetudo, which Projeto Jupiter, a student team at the University of São Paulo, flew in 2019. RocketPy, another open-source simulator, uses it as an example, and a copy of it is one of the project’s example rockets.

Its motor isn’t a real K400C. It keeps the size and mass of the motor in RocketPy’s example, and takes the thrust curve of a K400C in place of the original’s. The K400C is a commercial motor (motor designation) whose curve the simulator bundles. Like RocketPy’s example, HPR Sim flies the curve as it was measured. It adds no thrust for the thinner air at the site, 1,400 m (4,593 ft) above sea level.

The rocket launches from a 3 m (9.8 ft) vertical rail. A 5 m/s (11 mph) wind blows from the west at every height. The rocket comes down on a drogue and a main parachute.

The table lists the flight’s events in order:

columnmeaning
timeseconds since the motor ignited
CG heightthe height of the rocket’s center of gravity above the launch pad. It starts at 0.9 m (3.0 ft), not 0: the rocket stands on the rail with its aft end at the rail’s foot, and its center of gravity is 0.9 m (3.0 ft) above that
speedthe center of gravity’s speed over the ground, not through the air

And the events:

eventwhat happens
liftoffthe push up the rail first beats the weight and the rail’s friction (zero here): the rocket starts to move (liftoff)
rail exitthe last rail button, one of the small studs that slide in the rail’s slot, leaves the top of the rail, and the rocket flies free (rail exit)
burnoutthe motor’s thrust curve ends (burnout)
apogeethe highest point, where the rocket stops climbing (apogee)
drogue charge firesthe drogue is set to fire at apogee
drogue openshalf a second later, the drogue’s lines are stretched and it takes effect (deployment)
main charge firesthe rocket falls past 150 m (492 ft) above the pad, the main’s setting
main opensa second later, the main takes effect
landingthe center of gravity reaches the ground

Liftoff comes 1.6 milliseconds after ignition, when the thrust is only 73 N against 95 N of weight. Most of the rest of the push, 21 N, comes from the propellant’s internal momentum. That’s the propellant and gas moving inside the motor as it burns.

  • A thrust curve measured on a test stand already includes that effect. The simulator’s equations of motion add it again, so it’s counted twice.
  • HPR Sim does this on purpose, as RocketPy does, so that the two codes can be compared like for like. It’s a known approximation, listed with the other gaps on Start here.
  • It’s small here: it changes the burnout speed by at most 0.05 m/s (0.2 ft/s) (Rigid-body flight).

The speed is over the ground, so it includes the drift. At apogee the rocket is still moving sideways at 6.4 m/s (21 ft/s). At landing it falls at 6.4 m/s (21 ft/s) while the 5 m/s (11 mph) wind carries it east. That’s 8.1 m/s (27 ft/s) in all (6.42+52≈8.1).

Below the table:

  • Apogee is the highest point, in meters and feet, and where it was: 88.7 m (291 ft) from the pad at a bearing of 270°. A bearing is a direction clockwise from north, so 270° is due west.
  • Top speed is the fastest the rocket went, over the ground, with its Mach number. The Mach number is the rocket’s speed through the air as a fraction of the speed of sound. The top speed comes just before burnout, once the dwindling thrust no longer beats the drag and the weight.
  • Rail exit is the speed as the rocket leaves the rail. The slower it is in a crosswind, the larger the angle of attack just after it. That’s where the simulator’s models are least trustworthy (see what is left out). The simulator sets no minimum rail-exit speed and doesn’t judge whether this one is enough. That call is your range safety officer’s.
  • Landing is where the rocket came down, 90.2 m (296 ft) due east of the pad, and how fast it was falling. The rocket weathercocks: it turns into the wind as it climbs, so its apogee is west of the pad. It then drifts east under its parachutes, past the pad.

Accuracy of these numbers

  • Heights, speeds and times match RocketPy’s, given the same drag. Both codes flew five of RocketPy’s example rockets, this airframe among them, from the pad to the ground with one declared drag coefficient. They agree within 3% on how high, how fast and how long (the whole-flight comparison). That checks the equations of motion, the motor and the air, not the drag.

  • Where it goes in wind is the least certain number. This airframe was compared with RocketPy only in still air, where its drifts agree within 3%.

    Here it leaves the rail at 16.2 m/s (53 ft/s) in a 5 m/s (11 mph) wind, at a steep angle to the airflow. At such angles, HPR Sim’s drifts for two of RocketPy’s rockets are 10 to 38% from RocketPy’s (Accuracy). HPR Sim’s body lift and its later release from the rail put them there. Body lift is a sideways push on the body that RocketPy leaves out. How much body lift a body makes is itself uncertain.

    So this example’s apogee drift, 88.7 m (291 ft) upwind, and its landing point are the least trustworthy numbers it prints. Drift and landing haven’t been compared with any real flight yet (real flights compare heights).

  • The thrust is likely a little low for this site. HPR Sim flies the curve as measured, to match RocketPy’s example. A motor fired on a test stand near sea level gives somewhat more thrust in the thinner air at 1,400 m (4,593 ft). With the simulator’s correction for that, which assumes a sea-level test, this flight reached 874 m (2,867 ft).

    Motor files don’t say where the curve was measured, so neither number is certain. Treat 779 m (2,556 ft) as a little low (Solid motors).

  • The drag is the largest doubt. HPR Sim computes the drag coefficient from the rocket’s shape and surface. For this design it’s 0.5566 at Mach 0.3, coasting with the motor burnt out (power-off drag). That’s with rail buttons and a mirror-smooth surface finish (0 µm of roughness; a rougher surface adds skin-friction drag).

    • That’s 23.5% under the 0.728 in the rocket’s own OpenRocket file.
    • With that file’s rougher finish (60 µm) and its two launch lugs, HPR Sim gives 0.714, 1.9% under it. Launch lugs are short tubes on the outside of the body that ride along the rail, like rail buttons.
    • The drag curve in RocketPy’s example says 1.05, which the comparison leaves unexplained (Aerodynamics). Flown on that curve, RocketPy’s flight peaks 10% lower than HPR Sim’s on its own drag (Accuracy).

    A second program, drag_what_if.rs, flies the same rocket with each of the other two values in place of HPR Sim’s drag. Each value is held at every Mach number. Run it the same way:

    cargo run --example drag_what_if -p fusionspace-hpr-sim
    

    It prints this, and CI checks that on every change, as it does for the first program:

    Valetudo's apogee under three drag models, from a 3 m rail in 5 m/s of wind
    
    drag coefficient                             apogee (m)
    hpr's own, from the design                       778.7
    0.728, from the rocket's OpenRocket file         753.3
    1.05, from RocketPy's example curve              711.5
    

    For this rocket, the three drag values on record move the apogee from 778.7 m (2,555 ft) to 711.5 m (2,334 ft), 8.6% lower. That’s a spread, not a bound:

    • It shows how much this rocket’s apogee depends on its drag. It doesn’t say how far the simulator’s apogee is from the truth.
    • Three values don’t fence in the true drag: it could lie outside them.
    • HPR Sim’s drag has been checked against reference drag curves at Mach 0.3 only. It’s within 10% in two of seven cases, 10.3% and 11.5% low for two boattailed ones, 18% low for another rocket with its motor burning, and 47% to 50% low against this rocket’s own curve, the 1.05 above (Accuracy).
    • Another rocket, or this one on another motor, has its own spread.

    So 779 m (2,556 ft) is this design’s answer, and with more drag the same design would peak lower. The rocket that flew had a different motor, so none of these is a prediction of its flight.

  • The parachutes are simple. Each opens fully the moment its lines stretch. There’s no filling time and no drag overshoot, the canopy’s drag briefly rising above its steady value as it fills. So the opening load the simulator reports is no safe bound either way. Each canopy’s drag coefficient is the middle of the range printed for its type in Knacke’s Parachute Recovery Systems Design Manual, a standard handbook (Recovery).

  • The descent is the best-checked part. Its check gives both codes the same start near apogee, opens the first parachute at once and uses RocketPy’s formula for gravity. On those terms, HPR Sim’s descent agrees with RocketPy’s within 3% for five rockets (Recovery).

    This example opens the drogue after half a second and uses HPR Sim’s own gravity. Its landing point also depends on where the apogee is. On each code’s own drag, the apogee differs from RocketPy’s by 10% for this rocket.

Checking it yourself

You don’t have to take these numbers on trust. Four ways to test them:

  • To see how much the drag matters, run drag_what_if, as above. To try other drag coefficients, change the values in its list of them and run it again.

  • To trace a number to its source, use Checking a claim. It follows any number on this site back to the published source of its model, the test that pins it, and any comparison with another program.

  • To compare with a flight of your own, by hand, build your rocket as Your own rocket does, with the motor you flew. Solid motors shows how to read its thrust-curve file. Set the rail and the wind to match the day, and set HPR Sim’s apogee beside your altimeter’s.

    HPR Sim’s apogee is the height of the rocket’s center of gravity above the pad. Most hobby altimeters measure air pressure and turn it into height with the standard atmosphere. So on a day warmer or colder than standard, they read off by roughly 3 to 4% of the height for every 10 °C of difference. Give the simulator the day’s temperature too: Ussa76::with_offset shifts the standard atmosphere, and Environment::new takes it.

    The analyzer, hpr analyze, reads your altimeter’s log, in any of the layouts it reads. From its barometric altitude or pressure, it takes the flight’s apogee, liftoff, top speed and landing (Reading a flight log). Each comes within a stated bound, or is withheld by name. A GPS track alone gives no readings. hpr compare sets a log against a simulation of it (Comparing a flight with its simulation).

  • To compare with another simulator, by hand, enter the same rocket, motor, rail and wind in OpenRocket or RocketPy, and compare the apogee. Give both the same surface finish and rail guides. For this rocket, the OpenRocket file’s finish and launch lugs take HPR Sim’s drag coefficient from 0.5566 to 0.714, as above. HPR Sim reads OpenRocket’s .ork files too (OpenRocket import; Fly your .ork).

The project compared whole flights against RocketPy with the drag given to both codes, and with each code’s own drag.

Reading the code

Walk through the program line by line, then change it and fly again.

The program, step by step

This is the whole program. It’s also the file CI runs, line for line.

//! A first flight: a rocket with a drogue and a main parachute, flown from the launch rail to the
//! ground, with a summary of what happened.
//!
//! Run it from anywhere in the repository:
//!
//! ```text
//! cargo run --example first_flight -p fusionspace-hpr-sim
//! ```
//!
//! The documentation site's *Getting started* page (`docs/getting-started.md`) walks through it.
//! What it prints is kept next to it in `first_flight.output.txt`, and CI checks that the two
//! still agree (`cargo xtask examples --check`).

#![allow(
    clippy::print_stdout,
    reason = "the project's lints forbid printing in library code, and this program exists to print"
)]

use std::error::Error;

use hpr_atmos::ConstantWind;
use hpr_core::DVec3;
use hpr_core::geodesy::Geodetic;
use hpr_design::Rocket;
use hpr_sim::{
    CanopyType, Device, DeviceDrag, Environment, EventKind, FlightSettings, FlightStep, Observer,
    Rail, SimError, Simulation, Termination, Trigger,
};

fn main() -> Result<(), Box<dyn Error>> {
    // The rocket: Valetudo, which Projeto Jupiter (University of São Paulo) flew in 2019 and
    // RocketPy uses as an example. The design file describes its parts, materials and motor; the
    // motor keeps the example's size and mass, with a bundled K400C thrust curve.
    let rocket: Rocket = serde_json::from_str(include_str!(
        "../../../validation/designs/rocketpy-valetudo.json"
    ))?;

    // Where and in what weather: a site in New Mexico 1,400 m up, the 1976 US Standard
    // Atmosphere, and a steady wind from the west (270°) at every height.
    let site = Geodetic::from_degrees(32.99, -106.97, 1400.0)?;
    let wind_speed_m_s = 5.0;
    let wind_from_deg = 270.0_f64;
    let environment = Environment::standard(site)?.with_wind(ConstantWind::new(
        wind_speed_m_s,
        wind_from_deg.to_radians(),
    )?);

    // A vertical launch rail.
    let rail_length_m = 3.0;
    let rail = Rail::vertical(rail_length_m);

    // The flight: the design's configuration "example" (its K400C), the default settings, and
    // dual deployment. The drogue opens half a second after apogee; the main opens a second after
    // the rocket falls past 150 m above the ground, and the drogue stays attached.
    let simulation = Simulation::new(
        &rocket,
        "example",
        environment,
        rail,
        FlightSettings::default(),
    )?
    .with_recovery(vec![
        Device::new(
            "drogue",
            DeviceDrag::canopy(CanopyType::FlatCircular, 0.6),
            Trigger::Apogee,
        )
        .with_lag_s(0.5),
        Device::new(
            "main",
            DeviceDrag::canopy(CanopyType::FlatCircular, 2.4),
            Trigger::Altitude {
                height_above_ground_m: 150.0,
            },
        )
        .with_lag_s(1.0),
    ])?;

    // Fly it. `TopSpeed` (below) watches every step of the flight for its fastest moment.
    let mut top = TopSpeed::default();
    let flight = simulation.run(&mut top)?;
    if flight.termination != Termination::GroundHit {
        return Err(format!("the flight ended with {:?}", flight.termination).into());
    }

    let liftoff = flight
        .event(EventKind::Liftoff)
        .ok_or("the rocket never lifted off")?
        .sample;
    println!(
        "Valetudo on a K400C: {:.2} kg at liftoff, a {rail_length_m} m rail, {wind_speed_m_s} m/s \
         of wind from {wind_from_deg}°",
        liftoff.mass_kg
    );
    println!("Not yet validated: see the Accuracy page before trusting these numbers.");
    println!();
    println!("event                time (s)   CG height (m)   speed (m/s)");
    for event in &flight.events {
        let name = match event.kind {
            EventKind::Liftoff => "liftoff".to_owned(),
            EventKind::RailExit => "rail exit".to_owned(),
            EventKind::Burnout => "burnout".to_owned(),
            EventKind::Apogee => "apogee".to_owned(),
            EventKind::Trigger(i) => format!("{} charge fires", simulation.recovery()[i].name),
            EventKind::Deployment(i) => format!("{} opens", simulation.recovery()[i].name),
            EventKind::GroundHit => "landing".to_owned(),
            other => format!("{other:?}"),
        };
        let sample = &event.sample;
        // Heights are the center of gravity's above the pad. The flight ends where it reaches the
        // ground, found to within a micrometer just below it: print that as 0 (`+ 0.0` turns a
        // -0 into 0).
        println!(
            "{name:<20} {:>8.2} {:>15.1} {:>13.1}",
            sample.time_s,
            sample.height_above_ground_m.max(0.0) + 0.0,
            sample.cg_velocity_enu_m_s.length(),
        );
    }

    let apogee = flight
        .event(EventKind::Apogee)
        .ok_or("the flight has no apogee")?
        .sample;
    let rail_exit = flight
        .event(EventKind::RailExit)
        .ok_or("the flight never left the rail")?
        .sample;
    let landing = flight.final_sample;
    let (apogee_distance_m, apogee_bearing_deg) = from_pad(apogee.cg_enu_m);
    let (landing_distance_m, landing_bearing_deg) = from_pad(landing.cg_enu_m);

    println!();
    println!(
        "Apogee:     {:.1} m ({:.0} ft) above the pad, {apogee_distance_m:.1} m from it at a \
         bearing of {apogee_bearing_deg:.0}°, at {:.2} s",
        apogee.height_above_ground_m,
        apogee.height_above_ground_m / METERS_PER_FOOT,
        apogee.time_s,
    );
    println!(
        "Top speed:  {:.1} m/s (Mach {:.2}), at {:.1} s",
        top.speed_m_s, top.mach, top.time_s,
    );
    println!(
        "Rail exit:  {:.1} m/s",
        rail_exit.cg_velocity_enu_m_s.length()
    );
    println!(
        "Landing:    {landing_distance_m:.1} m from the pad at a bearing of \
         {landing_bearing_deg:.0}°, falling at {:.1} m/s, at {:.2} s",
        -landing.vertical_speed_m_s, landing.time_s,
    );
    Ok(())
}

/// The international foot.
const METERS_PER_FOOT: f64 = 0.3048;

/// Where `position` is from the pad: its distance over the ground, m, and its bearing, clockwise
/// from north, degrees. The launch frame's axes point east, north and up from the pad
/// (`docs/physics/frames.md`).
fn from_pad(position: DVec3) -> (f64, f64) {
    let (east_m, north_m) = (position.x, position.y);
    let bearing_deg = east_m.atan2(north_m).to_degrees().rem_euclid(360.0);
    (east_m.hypot(north_m), bearing_deg)
}

/// The fastest moment of a flight, relative to the ground.
///
/// An [`Observer`] sees every accepted step of the integration as the flight runs. This one looks
/// at the end of each step. Looking at 200 points inside every step instead raises the top speed
/// by 0.005 m/s, and moves its time by 0.013 s, since the speed is flat near its peak. So the
/// speed can read low by one in its last printed digit, and the time is printed to 0.1 s.
#[derive(Debug, Default)]
struct TopSpeed {
    speed_m_s: f64,
    mach: f64,
    time_s: f64,
}

impl Observer for TopSpeed {
    fn step(&mut self, step: &dyn FlightStep) -> Result<(), SimError> {
        let sample = step.sample(step.end_s())?;
        let speed_m_s = sample.cg_velocity_enu_m_s.length();
        if speed_m_s > self.speed_m_s {
            *self = Self {
                speed_m_s,
                mach: sample.mach,
                time_s: sample.time_s,
            };
        }
        Ok(())
    }
}

It has six steps.

  1. The rocket. The program reads Valetudo’s design from validation/designs/rocketpy-valetudo.json into a Rocket: its parts, their shapes, materials and positions, and its motor.

    The file holds the rocket alone: the rocket key of the open design format, without the rest of a .hpr file. HPR Sim also reads whole .hpr files, and OpenRocket’s .ork files (import from OpenRocket). The designs folder holds the other example rockets, and its README says how each was built.

  2. The surroundings. Geodetic::from_degrees places the launch site by latitude, longitude and height. Environment::standard gives it the Earth’s WGS 84 gravity and rotation, the 1976 US Standard Atmosphere and no wind. with_wind adds a constant wind: wind_speed_m_s, 5 m/s (11 mph), from wind_from_deg, 270°, clockwise from north (see wind direction). Angles in the code are in radians, hence to_radians().

  3. The rail. Rail::vertical(rail_length_m) is a rail 3 m (9.8 ft) long pointing straight up, with no friction. Its fields also set its heading, its angle above the horizon and its friction.

  4. The simulation. Simulation::new takes the rocket and the name of the configuration to fly. A design can hold several, one per motor choice.

    It also takes the surroundings, the rail and the integration settings, which say how finely to step through time. It runs the design’s checks first, and refuses a rocket that can’t exist, such as a motor wider than its mount. FlightSettings::default() steps through time to a tight tolerance (Time integration).

  5. The parachutes. Each Device has a name, a drag, and a trigger that fires its charge. DeviceDrag::canopy is a parachute of the given type and nominal diameter in meters. The drogue’s is 0.6 m (24 in), and the main’s is 2.4 m (94 in).

    • CanopyType::FlatCircular is a flat circular canopy. It’s one of thirteen canopy types, such as conical, hemispherical, cross and ringslot, each with drag data from Knacke’s parachute handbook. The CanopyType page of the API reference lists them all, and Recovery explains the data.
    • Trigger::Apogee fires at apogee; Trigger::Altitude fires when the rocket falls past a height above the pad.
    • with_lag_s is the time from the charge to the lines stretching. With no filling rule given, one for how the canopy’s drag grows as it opens, each parachute opens fully at once.
  6. The flight. run flies the rocket until it lands. It returns a FlightResult, the record of the finished flight. That holds how it ended (termination), its events, each with a Sample of the flight at that moment, and the final sample.

    • The argument to run is an Observer: any type that is shown every step of the flight as it runs. TopSpeed, at the bottom of the program, is one: it keeps the fastest moment.
    • For a whole trajectory, to plot or save, pass a Recorder instead. It keeps the quantities you choose, each a Channel, such as the height or the Mach number, as a table. Recording a trajectory shows one, lists the channels, and shows what it prints.

A Sample is a snapshot of the flight at one instant. It holds what the program prints, and more. It has the time, and the center of gravity’s position (cg_enu_m, meters east, north and up of the pad) and velocity (cg_velocity_enu_m_s). It also has the height above the pad, the vertical speed, the airspeed, the Mach number, the angle of attack, the thrust and the mass. Every quantity is in SI units, the metric units of the International System, and its name ends in its unit:

endingunitexample
_mmetersheight_above_ground_m
_m_smeters per secondvertical_speed_m_s
_ssecondstime_s
_kgkilogramsmass_kg
_nnewtonsthrust_n
_radradiansangle_of_attack_rad

A number with no unit, such as the Mach number (mach), has none in its name.

Change it

Edit the program and run it again. The edits below are for you to try. Each says which way the results move; run it to see by how much. Nothing checks these edits or what they print, so this page gives no exact numbers for them. For example:

  • For more wind, change let wind_speed_m_s = 5.0; to 10.0. The apogee drops a little and the landing moves farther east.
  • To angle the rail into the wind, replace Rail::vertical(rail_length_m) with Rail { elevation_rad: 85_f64.to_radians(), azimuth_rad: 270_f64.to_radians(), ..Rail::vertical(rail_length_m) }, a rail tilted 5° toward the west. The rocket now lands west of the pad, upwind.
  • To open the main higher, change height_above_ground_m: 150.0 to 300.0. The rocket spends longer under its main and lands farther downwind.
  • To drop the drogue, delete the first Device, the drogue. The rocket now falls at over 100 m/s (328 ft/s) until the main opens, far faster than a real parachute survives. The simulator reports the violent deceleration as it opens. But it has no model of a parachute or its harness failing, so the flight still ends in a gentle landing (Recovery).

Your edited program no longer prints what first_flight.output.txt says. That’s expected.

If you propose a change to the program itself in a pull request, two more commands help. cargo xtask runs the project’s own maintenance tasks, a Rust program in the repository’s xtask folder:

  • cargo xtask examples runs every example program and writes its new output next to it;
  • cargo xtask site builds this documentation site, and checks that the quotes on this page still match the program and its output.

Where next

  • Recording a trajectory keeps the whole flight as a table, to plot or save.
  • How a flight is simulated explains what happens between ignition and landing, and links the page for each model.
  • Your own rocket builds a rocket of your own, with your dimensions and a bundled motor. It shows the rocket’s center of pressure, center of gravity and stability margin. The builder does the same in fewer lines.
  • .ork design files reads a design from OpenRocket. On a file’s own curves and the bundled motors alone, most motor configurations fly. hpr sim looks up a missing curve once and keeps what it finds (how many fly). Its parachutes and streamers fly as OpenRocket flies them.
  • Accuracy gathers every validation result, and Checking a claim shows how to trace a number to its source and its test.
  • The API reference documents every type used here, and cargo doc --open -p fusionspace-hpr-sim builds it on your machine.
FusionSpace HPRVersion 0.1.0Issued 2026-11-21In preparationAbout HPR Sim