Start here

hpr-sim is a flight simulator for hobby and high-power rockets, and it is not ready to rely on yet. This site explains what it models, where each model comes from, and how well each one has been checked. It is written for a rocketeer who knows some physics and some code, but not this project. This page covers what hpr-sim is, what works today, what doesn’t yet, how far to trust it, and how to read the other pages.

Every number hpr-sim produces is an estimate from a model, not a measurement, and never a go/no-go verdict. Your motor’s printed data and your range safety officer are authoritative.

What hpr-sim is

hpr-sim simulates a rocket’s flight from the launch rail to landing. It is a 6-DOF simulator: it follows all six degrees of freedom, the rocket’s position along three axes and its rotation about three. Meanwhile the motor burns, and the rocket’s mass, center of gravity and inertia (how hard it is to turn) change.

It is a Rust library first, meant to be built into other programs, as RocketPy is. RocketPy is an open-source rocket flight simulator, written in Python and used as a Python library. hpr-sim has a Python package too (Python), and a graphical app is planned. OpenRocket .ork design files are read today. The command-line tool, hpr, flies a .ork or a rocket’s JSON, looks up and converts motor files, searches vendors’ motor stock and prices, re-runs the validation, reads an altimeter’s flight log, and fetches a launch day’s weather (The command line).

It is also built to be checked. Every model cites a published source, and tests pin every model. The simulator is compared against RocketPy, OpenRocket and the logs of real flights, with the results committed to the repository.

For now it covers only commercial off-the-shelf solid rocket motors (COTS motors), the kind you buy from a manufacturer. That stays true until the first app.

Nothing has been released yet. Release 0.1.0’s files are built and checked but not published; until they are, you build it from source, and once they are, they install as Install a release says. What a release holds, and how each of its files is checked, is in How a release is built; the changelog says what 0.1.0 does, how far to trust it, and its known gaps, the open issues that make a number look safer than it is among them. Releases come at product boundaries, and no dates are promised (Phase 8, releases); a dated estimate for each is in Plan and timeline:

• 0.1, the simulator: the library, the command line and the Python package, with Monte Carlo dispersion from the command line and Python. It waits on M2.3c1, the logged flights’ apogees and named fixes (release 0.1). It ships with its known limits listed, among them drag that reads high above Mach 0.8, so apogee there reads low.
• 0.2, the flight analyzer: the common altimeters’ logs read on their own, with no design file, then compared with its simulation and the rocket’s drag fitted from it.
• 0.3, accuracy and diagnosis: the simulator measured against logged flights and improved, and a flight’s likely faults ranked from its log.
• 0.4, the competition kit: rules presets for Student Launch, IREC and others, an optimizer, the numbers a submission asks for, ejection-charge sizing, and RASAero and RocketPy files.
• 0.5, an app preview: open a design or a log, fly it and replay it in 3D, with the simulated flight drawn as a “ghost” beside the real one, on the desktop and in a web browser.
• 1.0, the app, with its design editor.

After 1.0, new product lines come one at a time, in an order that may still change: designing your own solid motors, then parachutes, then a pad-day mode on your phone (the day’s forecast, the best launch hour, drift on the field, a flight card), then flight computers and trackers. Hybrids and liquids come last (the second-pass plan).

What works today

These parts are built and tested. Each page gives its sources, and most say what they leave out. The pages, the program’s messages and the library’s names use US spelling for the eight words the style guide checks. The saved forms that held a British-spelled key (a landing ellipse, a design-check finding, a laid-out rocket and a few more) still read the old key and write the new one, so an older build may not read what this one saves; design files never held one and are unchanged (M0.6e, US names).

What doesn’t work yet

These are the gaps you are most likely to meet. Each model page lists what its own model leaves out.

Speed and angle of attack

• Drag near and past Mach 1 is lightly checked. Since M1.8b1 (drag through Mach 1), a flight on hpr’s own drag flies from Mach 0 to 5, and one that reaches Mach 5, the top of the models, stops with an error.
  • Near and above the speed of sound, the transonic and supersonic speeds, the drag is Niskanen’s 2009 method, which is semi-empirical: formulas fitted to measurements.
  • Against NASA’s wind-tunnel tests of the Arcas Robin sounding rocket, from Mach 0.6 to 4.63, it reads high at most speeds, most of all with fins past Mach 1 (Aerodynamics).
  • So for a rocket that goes past Mach 1, expect hpr’s apogee to come out low rather than high. Its base drag, on the flat aft end, hasn’t been checked faster than Mach 0.3 at all.
  • It has been compared with RASAero II’s drag near Mach 1; the comparison is not uniformly within the 10% target. See Accuracy for the cases and errors. A drag table from another tool can replace hpr’s own drag (Aerodynamics).
• The normal force still has gaps near Mach 1 and on some supersonic bodies. The current body and Arcas Robin comparisons, including their measured error ranges, are in Aerodynamics and Accuracy.
• Small angles of attack only. Nothing models stall, the loss of lift at a large angle of attack, yet a flight uses the same models at every angle. So results near rail exit in a strong crosswind, and near apogee, are the least trustworthy.

Staging, two-stage rockets, clusters and air starts

• Staging is new, and checked against OpenRocket on its own examples. Each motor lights at its own time, an air start included, and a sustainer flies on after dropping its booster, which lands on its own (Staging). Tests check the bookkeeping. OpenRocket’s two-stage and three-stage examples, its cluster example and its air-start example, 15 flights in all, are each within 5% of OpenRocket’s apogee and largest speed. Five apogees, three of the cluster’s and two of the three-stage example’s, are compared with OpenRocket’s flight with no parachute, since its parachute opened before apogee (M1.9c, a two-stage and a cluster design against OpenRocket; M4.5g2, several separations; results).
  • A .ork file’s ignition settings and every powered separation are read, from the tail forward (M4.5g2, several separations). A powered separation has a time known before the flight, and then a motor ahead of it is still burning or yet to light and none behind it is. One at its own stage’s first burnout may drop the stage’s own other motors still burning, if they lit strictly before the split, as OpenRocket does (M4.5n, a stage’s first burnout). The ignitions come with the rocket. Your program passes the separation to the flight, with a recovery device on each part, since hpr refuses the flight without them; hpr sim does the same for you (Separation). The example ork_two_stage.rs does both. A lone separation with nothing ahead of it left to burn, such as a payload’s, is read too; hpr sim flies it when the payload’s own device opens at the split (M4.5g3, a payload’s split). One beside another separation, or at or after apogee beside another, isn’t flown (which configurations fly).
  • A cluster, several motors burning side by side, flies, whether they share one mount of several tubes or each has its own: hpr adds up their thrust and mass, and a motor off the rocket’s center line adds a turning moment. A motor that fails to light can be set, and the rocket then turns as a hand calculation says (Clusters). A .ork file’s cluster flies with a motor in every tube.
  • A rocket can separate into parts for recovery once the aft part’s motors have burnt out.

Effects left out

• Some effects are left out of a flight, or approximated:
  • tip-off (the rocket pitching as it leaves the rail), thrust misalignment (a motor pushing slightly off the rocket’s axis), and turbulence (the model exists, but a flight doesn’t use it), none of which a milestone plans yet (issue #39 tracks turbulence);
  • the shock load when a parachute opens, and the canopy’s overshoot of its steady drag (Recovery);
  • the internal momentum of the burning propellant, which is counted twice, as RocketPy counts it: a thrust curve measured on a test stand already includes its effect, and the equations of motion add it again. On Valetudo, the rocket that Getting started flies, it adds 21 N to the push at liftoff and changes the burnout speed by at most 0.05 m/s (Rigid-body flight).

Outputs and ways to use it

• Output files. Exporting a flight writes a recording as CSV, JSON or Parquet (M1.10c2), and the flight path with its landings as GeoJSON or KML for a map. A flight’s peaks, its stability margin from the rail exit to apogee (the weakest direction’s, for a rocket with a fin set of one or two fins; #329), the optimum ejection delay and its landing’s latitude and longitude are in Flight metrics, and its fins’ flutter speed and margin in Fin flutter.
• The command line flies powered separations only. hpr sim flies a .ork or hpr design file, exports its recording (The command line), and with --plot draws its altitude, speed and acceleration against time, events marked and listed in a table, as an SVG in the FusionSpace chart style (Plotting the flight; M4.5e, plots; M0.6c, their style).
• hpr sim reads by name. It leads with the static margin, apogee, rail exit speed, ejection delay and the descent speed under open parachutes, and calls configurations and parts by name, such as [C6-5] for a configuration the file leaves unnamed (M4.5d, readable output). It flies a .ork file’s parachutes and streamers, and its powered separations, one or several (M4.5g1, powered separation in hpr sim; M4.5g2, several separations), and a payload dropped with nothing left to burn, when its own parachute opens at the split (M4.5g3, a payload’s split). A rocket’s .json carries no parachute. A Rust program flies separations and parachutes: Getting started flies a first rocket, and The builder builds and flies one of your own in a few calls. A Python program flies the parachutes of a rocket it builds part by part, or a design file’s with recovery=True, but no staging (Python).
• .ork files are read, but most don’t fly with their own motors. A .ork file is read (.ork design files), but few of its motor configurations fly as written, as hpr has few motors’ curves. Its parachutes and streamers fly as OpenRocket flies them (Recovery). hpr sim --motor flies one with a motor you give (The command line).
• Monte Carlo runs give the apogee’s spread and landing ellipses, from Rust, the command line or Python. A Monte Carlo run flies a rocket many times with its mass, drag, motor, wind and rail scattered, seeded and reproducible (Monte Carlo dispersion), and draws the ellipse its landings fall in (Landing ellipses). hpr mc runs one on any design hpr sim flies and exports every flight as CSV; for a design without staging, hpr.MonteCarlo returns the same flights to Python as NumPy arrays (Python), but not the ellipses. Morris screening and Sobol’ indices rank which inputs matter most (Sensitivity analysis). CMA-ES finds the values of a design’s numbers that hit a target, such as the ballast and body length for a 3,048 m apogee with a chosen margin. CMA-ES also chooses a motor and a nose cone within a competition’s limits, and NSGA-II weighs apogee against stability (Optimization). Their answers are only as good as hpr’s flight models. Competition rule files are not built yet. No app yet: it is on the roadmap.
• The flight-log analyzer reads one logger so far. hpr analyze reads a PerfectFlite altimeter’s .pf2 log on its own, with no design file and no simulation, and prints liftoff, apogee, the top speed, landing and the descent, each saying where it came from, or withheld with the reason the log can’t support it (Reading a flight log). The other loggers come with M7.1: Altus Metrum (AltOS), Featherweight (Raven, Blue Raven and the GPS tracker), Missile Works RRC3, Eggtimer, Entacore AIM, Mercury/AltimeterCloud, CATS, and plain CSV with column mapping. The rest of the readings, such as burnout and each leg of the descent, come with M7.2, and comparing a flight with a simulation of it with M7.3.

How far to trust it

Accuracy gathers every result so far, gaps included. The accuracy work aims first at the flights most rocketeers make, the core band: up to Mach 2.5. It assumes angles of attack of 15° or less. The wider envelope runs to Mach 3.5, at any angle (the operating envelope). Whole flights are checked mostly below about Mach 1.15 so far. Faster flights still fly, and say so: a flight beyond the validated range, at high angle of attack, outside the core band or beyond the envelope carries a flag (M1.14a1, the envelope flags), and a flight that meets a known error in hpr’s drag or stability warns by its issue number (M1.14a2, the drag issue warnings; M1.14a3, the stability ones; M10.1d2, four more and a flight unstable under power). A flight whose static margin falls below zero while a motor burns says its apogee is not a prediction. In brief:

• Whole flights match RocketPy’s in height, speed and time when both codes fly the same drag. Six of RocketPy’s example rockets agree within 3% on apogee, speeds, burnout and flight time (M2.1b2, the whole-flight comparison). So does where they go, except for rockets that leave the rail slowly in a wind. There hpr’s body lift, which RocketPy leaves out, its later release from the rail and, for one rocket, its simpler fin model put the apogee’s drift −4.333% to −38.158% from RocketPy’s, and the landing’s −21.686% to +36.678% (report; Accuracy). With hpr’s own drag, against RocketPy flying the drag its examples ship, hpr’s heights differ from RocketPy’s by −7.280% to +10.302% (report). The larger gaps are where the two drags differ most: hpr’s is well below the example’s for two rockets, and above it at high speed for Prometheus 2022, which flies through Mach 1 (Accuracy).

• Against seven real flights, hpr’s apogees miss by 6.04% on average, outside the 5% target, and by −8.90% to +10.40% one by one. hpr’s height is read the way each log’s barometric altimeter reads the air (four of the seven assumed barometric); drift and speed are not compared yet (real flights, report).

• Against 55 more real flights, from a private collection, hpr and OpenRocket both over-predict the logged apogee, hpr by 9.83% on average and OpenRocket by 9.00%, while agreeing with each other within 5% on 53 of them; neither meets the 5% target. The flights’ owners allow only aggregate numbers (private collection, report).

• The descent under a parachute matches RocketPy’s. The comparison flies the descents of five of RocketPy’s example rockets in both codes:

  • Each starts from the same state near apogee, with the first parachute opening at once.
  • Both codes get the same drag areas and wind.
  • RocketPy’s parachutes can add random noise, which would make each run differ; it is switched off.
  • hpr uses RocketPy’s formula for gravity, and RocketPy’s way of interpolating the wind, that is, of working out the wind between the heights it is given.

  Six numbers are compared for each rocket: the descent time, the mean descent rate, the descent rate at landing, and the drift in total, to the east and to the north. All 30 agree with RocketPy’s within 3%; the largest difference is +2.865%. That shows the two codes agree on the descent physics, not that either matches a real flight. The committed validation report has every number, and Recovery explains the comparison.

• Each model is tested on its own: against exact answers, and where its source prints tables or worked examples, against those; several parts also against RocketPy. Each test states its tolerance. The largest known gaps:

  • The drag was checked at Mach 0.3 against other programs’ curves (below), and from Mach 0.6 to 4.63 against NASA’s Arcas Robin wind tunnel. There it reads high at most speeds, most of all with fins past Mach 1: 2 of 44 measurements are within the 10% target set before measuring (Aerodynamics). The normal force and center of pressure were checked at Mach 0 against Barrowman’s worked examples and from Mach 0.6 to 4.63 against the same wind tunnel, where they miss between Mach 0.8 and 1.2, and past Mach 3, the current comparison and its measured range are reported in Aerodynamics.
  • The drag was compared with drag curves that come with RocketPy’s example rockets, labelled as RASAero II’s (another rocket aerodynamics program). The curves don’t record the fins’ edges or the surface finish, so hpr’s copies of the designs follow a declared guess. hpr is within 10% in four of the seven cases.
  • hpr’s drag is 18% low for Cavour, another of RocketPy’s examples, while its motor burns (power-on drag); the cause is not known yet.
  • hpr’s drag is 47% to 50% below Valetudo’s example curve. Valetudo is the rocket that Getting started flies. Its references disagree with each other, though: at Mach 0.3 the example curve gives a drag coefficient of 1.05, 1.44 times the 0.728 in an OpenRocket file of the same rocket. Given that OpenRocket file’s own surface finish and launch lugs, hpr gives 0.714, 1.9% under the file’s 0.728 (Aerodynamics).
  • The Recruiter is a six-fin model rocket that J. S. Barrowman, whose method hpr follows for the normal force, works through in his 1970 report Centuri TIR-33. hpr’s normal-force slope for it, how fast the sideways force grows with angle of attack, is 2.87% above his printed value, and 3.42% on the fins alone. Most of that comes from a different rule for six fins (Aerodynamics).
  • Tumbling drag is −10 to +19% off its source’s own drop tests. A separated body’s parachute can open at a higher speed than it would for real, because the body falls with no drag until then (Recovery).

• You can check it yourself. Getting started says how: run a program that shows how much the drag moves the apogee, trace any number with Checking a claim, or compare hpr’s apogee by hand with your own altimeter’s or another simulator’s.

Reading these pages

New here? Getting started builds hpr-sim and flies a first rocket, and How a flight is simulated follows a flight from the pad to the ground, linking the page for each model on the way.

Have an OpenRocket design? Three how-to guides take it through hpr on the command line: Fly your .ork, Pick a motor and Check stability for a certification flight.

Each model page opens with In short: what it models, its sources, how well it is validated and what it leaves out. Below that, it names the code that implements the model, the sources it follows and the tests that pin it.

Sources are cited by a short key in square brackets, such as [N09] for Niskanen’s 2009 thesis on model rocket simulation, with the full reference near the top of the page.

Equations are written in plain text, so they read the same here, on GitHub and in the code’s documentation. For example, once its drag balances its weight, a rocket under a parachute falls at the steady speed v_e = √(2 m g / (ρ C_D S)), where m is its mass, g gravity, ρ the air’s density and C_D S the parachute’s drag area (Recovery).

Terms are defined in the Glossary, and Checking a claim shows how to trace any number to its source, its test and its validation.

The code itself is documented in the API reference, which Rust’s documentation tool generates from the source. It lists every public type and function, and each crate’s front page links back to the pages here that explain its models.

Three kinds of label link to the project’s records on GitHub, which Decisions and the roadmap introduces:

• A milestone, such as M1.8, is a step of the roadmap, the ordered plan of work.
• A decision record, such as ADR-011, explains a significant choice and the alternatives that were considered. All of them are in the decision log.
• A Loft lesson, such as Loft lesson L15, is a mistake found in Loft, the project that came before hpr-sim. A test here guards against it, or will once its milestone ships. They are listed in Lessons from Loft.

Every page’s source is a Markdown file in the repository’s docs/ folder. The pencil icon at the top of a page opens its source in GitHub’s editor, where you can propose a fix.

Title block

This page ends with a title block, the box in the corner of an engineering drawing that says what a document is, who issued it, when, and which sources it rests on. It describes the whole site and this version of hpr-sim. FusionSpace, the family of tools hpr-sim belongs to, closes its pages this way; FS · SW · TOOL 005 is hpr-sim’s number in that family’s register.

Getting started

This page takes you from nothing to a first simulated flight: install Rust, build hpr-sim, and run a short program that flies a rocket from the launch rail to the ground and prints what happened. Then it 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 numbers this example prints are not validated. hpr’s whole flights match RocketPy’s in height, speed and time when both codes are given the same drag, and in where they go, except for rockets that leave the rail slowly in a wind (see How far to trust it). With its own drag, hpr flies this rocket about 10% higher than RocketPy does on the drag table RocketPy’s example ships (770 m against 700 m in the validation case); which drag is closer to the truth is open. This rocket left no flight log, so it can’t be checked against its real flight; seven other rockets have been, and hpr’s apogees missed theirs by 6.04% on average, outside the 5% target (real flights). Against 55 more, from a private collection, hpr’s apogees were +9.83% above the logs on average, and OpenRocket’s +9.00% (private collection). How far to trust it below says what that means for this one.

Install a release

Release 0.1.0 is built and checked, but not published yet. Until it is, build hpr-sim from the repository, as the rest of this page does. Once it is published, each part installs without a copy of the repository:

• The command line, hpr. Download the archive for your system from the releases page, unpack it, and put hpr on your path. There are archives for Linux on x86-64, Macs with Apple silicon, and Windows on x86-64. Elsewhere (an Intel Mac, Linux on ARM), or with Rust installed, cargo install hpr-cli --locked builds it. The command line documents its commands.
• The Python package. pip install hpr-sim installs it, and it imports as hpr. One wheel serves CPython 3.10 and later on each of those three systems; elsewhere pip builds it from source, which needs Rust (Python).
• The library, for your own Rust program. cargo add hpr adds the front-door crate, which re-exports the others (The builder; the API reference).

Each archive and wheel holds hpr-sim’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.

Two 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.
• Linux files need the GNU C library (glibc) 2.35 or later, as in Ubuntu 22.04. On an older system, cargo install hpr-cli --locked builds the command line and pip builds the Python package from source (issue #372).

What you need

• Rust, through rustup, Rust’s installer. The repository pins the version it is 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 hpr-sim uses. After that, everything here works offline, on macOS, Windows and Linux.

Nothing else: no Python, Java or other simulator.

Build it and fly

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

The first run compiles hpr-sim 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, and -p hpr-sim (short for --package) names the crate, one of the repository’s Rust packages, that holds it: hpr-sim, the crate that flies the rocket. 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. For the peaks, the stability margin through the climb, the best ejection delay and the landing’s latitude and longitude, see Flight metrics; 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, and 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 hpr’s copy of it is one of the project’s example rockets.

Its motor is not a real K400C. It keeps the size and mass of the motor in RocketPy’s example, and takes the thrust curve of a K400C, a commercial motor (motor designation) whose curve hpr bundles, in place of the original’s. Like RocketPy’s example, hpr flies the curve as it was measured: it adds no thrust for the thinner air at the site, 1,400 m above sea level. The rocket launches from a 3 m vertical rail, in a 5 m/s wind that blows from the west at every height, and comes down on a drogue and a main parachute.

The table lists the flight’s events in order:

And the events:

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: the propellant and gas moving inside the motor as it burns.

• A thrust curve measured on a test stand already includes that effect, and hpr’s equations of motion add it again, so it is counted twice.
• hpr does this on purpose, as RocketPy does, so that the two codes can be compared like for like. It is a known approximation, listed with the other gaps on Start here.
• It is small here: it changes the burnout speed by at most 0.05 m/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. At landing it falls at 6.4 m/s while the 5 m/s wind carries it east, 8.1 m/s in all (√(6.4² + 5²) ≈ 8.1).

Below the table:

• Apogee is the highest point, in meters and feet, and where it was: 88.7 m 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 (its speed through the air as a fraction of the speed of sound). It 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, and that is where hpr’s models are least trustworthy (see what is left out). hpr 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 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.

How far to trust it

• Heights, speeds and times match RocketPy’s, given the same drag. Five of RocketPy’s example rockets, this airframe among them, flown from the pad to the ground by both codes with one declared drag coefficient, agree within 3% on how high, how fast and how long (M2.1b2, 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 in a 5 m/s wind, at a steep angle to the airflow. At such angles hpr’s body lift, a sideways push on the body that RocketPy leaves out, and its later release from the rail put the drifts of two of RocketPy’s rockets 10 to 38% from RocketPy’s; how much body lift a body makes is itself uncertain (Accuracy). So this example’s apogee 86 m upwind and its landing point are the least trustworthy numbers it prints. Drift and landing have not been compared with any real flight yet (real flights compare heights).

• The thrust is likely a little low for this site. hpr 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. With hpr’s correction for that, which assumes a sea-level test, this flight reached 874 m. Motor files don’t say where the curve was measured, so neither number is certain; treat 779 m as a little low (Solid motors).

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

  • That is 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 (short tubes on the outside of the body that ride along the rail, like rail buttons), hpr gives 0.714, 1.9% under it.
  • 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’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’s drag, held at every Mach number. Run it the same way:

  cargo run --example drag_what_if -p 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 to 711.5 m, 8.6% lower. That is a spread, not a bound:

  • It shows how much this rocket’s apogee depends on its drag. It doesn’t say how far hpr’s apogee is from the truth.
  • Three values don’t fence in the true drag: it could lie outside them.
  • hpr’s drag has been checked against reference drag curves at Mach 0.3 only. It is within 10% in four of seven cases, 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 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, with no filling time and no drag overshoot (the canopy’s drag briefly rising above its steady value as it fills). So the opening load hpr 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. From the same start near apogee, with the first parachute opening at once and RocketPy’s formula for gravity, hpr’s descent agrees with RocketPy’s within 3% for five rockets (Recovery). This example opens the drogue after half a second and uses hpr’s own gravity, and its landing point also depends on where the apogee is, which on each code’s own drag 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:

• 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.
• Trace a number to its source. Checking a claim 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.
• 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’s apogee beside your altimeter’s. hpr’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 hpr the day’s temperature too: Ussa76::with_offset shifts the standard atmosphere, and Environment::new takes it. hpr reads a PerfectFlite altimeter’s log (Reading a flight log); other altimeters’ logs come with M7.1, and comparing one with a simulation with M7.3.
• 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’s drag coefficient from 0.5566 to 0.714, as above. hpr can’t import an OpenRocket design yet: that comes with M3.1, OpenRocket import.

The project’s own comparison of whole flights against RocketPy, with the drag given to both codes, is M2.1b2; with each code’s own drag it is M2.1c2.

The program, step by step

This is the whole program. It is 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 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 format is hpr’s own and provisional: the open design format (M3.3) will replace it, and import from OpenRocket (M3.1) comes later. 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, from wind_from_deg, 270°, clockwise from north (see wind direction). Angles in hpr are in radians, hence to_radians().
3. The rail. Rail::vertical(rail_length_m) is a rail 3 m 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, the name of the configuration to fly (a design can hold several, one per motor choice), 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: 0.6 m for the drogue and 2.4 m for the main.
   • CanopyType::FlatCircular is a flat circular canopy. It is 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: 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: the time, the center of gravity’s position (cg_enu_m, meters east, north and up of the pad) and velocity (cg_velocity_enu_m_s), 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:

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 numbers for them. For example:

• More wind. Change let wind_speed_m_s = 5.0; to 10.0. The apogee drops a little and the landing moves farther east.
• 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.
• 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.
• Drop the drogue. Delete the first Device, the drogue. The rocket now falls at over 100 m/s until the main opens, far faster than a real parachute survives. hpr 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, which is 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, and shows its center of pressure, center of gravity and stability margin. The builder does the same in fewer lines, and .ork design files reads a design from OpenRocket, though few of its motor configurations fly yet; 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 hpr-sim builds it on your machine.

Fly your .ork

This guide flies a rocket you designed in OpenRocket with hpr sim, from the command line, and says how to read what it prints. It is for a flier who has a .ork file and wants a second simulator’s view of it. Every flight here is a model’s estimate, not a measurement: Accuracy says how close hpr comes to OpenRocket and to real flights, and its summary sits at the top of the README. The outputs on this page are made by running each command, and CI checks that they still match what hpr prints.

The steps:

1. Fly the file as it is.
2. Choose the configuration and the launch.
3. Fetch a motor hpr doesn’t have.
4. Plot it, or save the numbers.
5. When hpr refuses.

You need hpr installed: the README’s Install and first flight takes a few minutes. The examples fly the guides’ own rocket, validation/fixtures/ork/guides/level-1.ork: a 66 mm, 0.82 kg rocket with a 38 mm motor mount and one parachute on the motor’s ejection charge, saved with two motors, an AeroTech H170M and an I175WS. OpenRocket 24.12 opens it. Run the commands from a copy of the repository, or put your own file’s path in its place.

Fly the file as it is

hpr sim with the file’s name flies its default configuration, with the motors, delays and parachutes the file holds. The guide rocket’s motors are among the 32 built into hpr, so it flies with no network:

$ hpr sim validation/fixtures/ork/guides/level-1.ork
Level 1 guide rocket (level-1.ork)
configuration 1 of 2: [H170M-10]
help: --config flies the others, by number or name: 2 [I175WS-9]

static margin         1.70 calibres off the rail; least 1.70 calibres, at 0.12 s, before apogee
apogee                1065.1 m above the site at 11.62 s
rail exit speed       26.3 m/s
delay                 apogee 9.48 s after burnout; the motor's set delay: 10 s; its charge fires 0.52 s after apogee
descent               4.4 m/s at landing under `Parachute`

motor: 1 × H170M (the design's) in `Motor mount tube`, lit at launch
recovery: `Parachute` at the ejection charge, 0.520 m² of drag area, opened at 12.14 s
launched at 0° N, 0° E, 0 m above sea level, from a 1.5 m vertical rail, in calm air
help: see the Accuracy page before trusting these numbers: https://nrdptel.github.io/hpr-sim/accuracy.html
note: the file's 1 recovery device flies as OpenRocket flies it: each opens fully at its event, with the file's drag coefficient or OpenRocket's own, and once one opens the rocket descends as a point under the open devices' drag alone
warning: drag: issue #67: a cone-like nose's or shoulder's pressure drag reads high from Mach 0.8 (about twice a measured cone's at Mach 0.85, still +15% at 1.5), so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are; this flight reaches Mach 0.84 at 1.7 s (https://github.com/nrdptel/hpr-sim/issues/67)
warning: drag: issue #68: base drag reads high from Mach 0.8 to 1.2 (0.225 against a measured 0.156 at Mach 0.9), so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are; this flight reaches Mach 0.84 at 1.7 s (https://github.com/nrdptel/hpr-sim/issues/68)
warning: drag: issue #18: skin friction is taken as fully turbulent, but on a smooth surface the flow stays laminar near the nose, where friction is lower: hpr's reads high by 3.6% on RocketPy's Calisto at Mach 0.3; if this surface is that smooth, the drag reads high, so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are (https://github.com/nrdptel/hpr-sim/issues/18)
warning: stability: issue #172: the static margin read up to 0.1108 calibres higher than OpenRocket's on four private designs, for a reason not yet found, so this flight's margin may read high by as much (https://github.com/nrdptel/hpr-sim/issues/172)

event                   time     height       speed
liftoff               0.00 s      0.4 m     0.0 m/s
rail exit             0.12 s      1.9 m    26.3 m/s
burnout               2.14 s    406.4 m   240.4 m/s
apogee               11.62 s   1065.1 m     0.1 m/s
charge               12.14 s   1063.7 m     5.1 m/s
deployment           12.14 s   1063.7 m     5.1 m/s
ground hit          245.78 s      0.0 m     4.4 m/s
(heights are the center of gravity's above the site; speeds are over the ground)

top speed             285.6 m/s at 1.73 s
top Mach number       0.842
landing               0.7 m from the pad at 245.78 s, at 4.4 m/s

The five lines under the configuration are the ones to read first:

• static margin: how far the center of pressure sits behind the center of gravity, in body diameters (calibres), as the rocket leaves the rail, and its least value before apogee. A rocket with a fin set of one or two fins has a different margin for each direction the air crosses it, and hpr prints the least (Flight metrics). Check stability for a certification flight says how to use it.
• apogee: the highest point of the center of gravity, above the launch site.
• rail exit speed: the speed as the rocket leaves the rail. The slower it is, the more a crosswind tips the rocket just after.
• delay: the coast from burnout to apogee, beside the delay the file sets. Here the H170M’s 10 s charge fires about half a second after apogee. Pick a motor says how to choose one.
• descent: how fast the rocket comes down under its open parachutes, without the wind’s drift.

The recovery line names each parachute, when it opened and its drag area; the events table gives each event’s time, height and speed. The note says how the parachute is flown: it opens fully at once, as OpenRocket’s does. The command line explains every line, and any warning you may see.

Choose the configuration and the launch

--config picks another of the file’s configurations, by its number, its name or its motors. The output’s second and third lines list them. A configuration the file leaves unnamed is called by its motors and delays in brackets, so the guide rocket’s second is [I175WS-9], and --config 2, --config I175WS-9 and --config i175ws-9 all fly it.

hpr sim does not read the launch conditions saved with the file’s simulations: give them as options. Without them, the rocket flies from a 1.5 m vertical rail at sea level, at 0° N, 0° E, in calm air. Set the site’s elevation for every real field: air thins with height, and a rocket climbs higher from a high one. This flies the second configuration from a field 1,400 m up, off a 2.4 m rail tilted 5° toward the west, in a 4 m/s west wind:

$ hpr sim validation/fixtures/ork/guides/level-1.ork --config 2 --elevation 1400 --rail-length 2.4 --inclination 85 --heading 270 --wind 4 --wind-from 270
Level 1 guide rocket (level-1.ork)
configuration 2 of 2: [I175WS-9]
help: --config flies the others, by number or name: 1 [H170M-10]

static margin         1.69 calibres off the rail; least 1.69 calibres, at 0.17 s, before apogee
apogee                1174.3 m above the site at 11.51 s
rail exit speed       36.8 m/s
delay                 apogee 9.54 s after burnout; the motor's set delay: 9 s; its charge fires 0.54 s before apogee
descent               4.9 m/s at landing under `Parachute`

motor: 1 × I175WS (the design's) in `Motor mount tube`, lit at launch
recovery: `Parachute` at the ejection charge, 0.520 m² of drag area, opened at 10.97 s
launched at 0° N, 0° E, 1400 m above sea level, from a 2.4 m rail 85° above the horizon, leaning toward 270°, in a 4 m/s wind from 270°
help: see the Accuracy page before trusting these numbers: https://nrdptel.github.io/hpr-sim/accuracy.html
note: the file's 1 recovery device flies as OpenRocket flies it: each opens fully at its event, with the file's drag coefficient or OpenRocket's own, and once one opens the rocket descends as a point under the open devices' drag alone
warning: drag: issue #67: a cone-like nose's or shoulder's pressure drag reads high from Mach 0.8 (about twice a measured cone's at Mach 0.85, still +15% at 1.5), so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are; this flight reaches Mach 0.87 at 1.8 s (https://github.com/nrdptel/hpr-sim/issues/67)
warning: drag: issue #68: base drag reads high from Mach 0.8 to 1.2 (0.225 against a measured 0.156 at Mach 0.9), so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are; this flight reaches Mach 0.87 at 1.8 s (https://github.com/nrdptel/hpr-sim/issues/68)
warning: drag: issue #18: skin friction is taken as fully turbulent, but on a smooth surface the flow stays laminar near the nose, where friction is lower: hpr's reads high by 3.6% on RocketPy's Calisto at Mach 0.3; if this surface is that smooth, the drag reads high, so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are (https://github.com/nrdptel/hpr-sim/issues/18)
warning: stability: issue #172: the static margin read up to 0.1108 calibres higher than OpenRocket's on four private designs, for a reason not yet found, so this flight's margin may read high by as much (https://github.com/nrdptel/hpr-sim/issues/172)

event                   time     height       speed
liftoff               0.02 s      0.4 m     0.0 m/s
rail exit             0.17 s      2.8 m    36.8 m/s
burnout               1.97 s    389.9 m   271.2 m/s
charge               10.97 s   1172.0 m    15.4 m/s
deployment           10.97 s   1172.0 m    15.4 m/s
apogee               11.51 s   1174.3 m     1.0 m/s
ground hit          246.17 s      0.0 m     6.3 m/s
(heights are the center of gravity's above the site; speeds are over the ground)

top speed             290.9 m/s at 1.75 s
top Mach number       0.874
landing               755.8 m from the pad at 246.17 s, at 6.3 m/s

--inclination is the rail’s angle above the horizon, so 85 is 5° off vertical (OpenRocket gives the same rail as 5°, from the vertical), and --heading 270 leans it toward the west, into the wind. The wind is the same at every height. The launch lists every option and its default.

Fetch a motor hpr doesn’t have

A motor outside hpr’s 32 is fetched from ThrustCurve.org the first time you fly it, then kept in hpr’s cache, so it flies offline after. A .ork names its motor but rarely carries its thrust curve. With no network, and no copy in the cache, hpr sim refuses and prints the command that fetches it. This test rocket names an AeroTech H128W:

$ hpr sim validation/fixtures/ork/pod-flights/pods-none.ork --offline
error: configuration [H128W-0] can't be flown as the file has it: no thrust curve for H128W: no embedded curve, and no motor of that manufacturer and designation in the bundled catalog; AeroTech H128W is not in hpr's cache of ThrustCurve.org, and the run is offline
help: with a network connection, `hpr motors fetch --manufacturer AeroTech H128W` fetches it into the cache
help: give a motor with --motor
$ echo $?
1

Run that command once with a network connection, or fly the file once online:

hpr motors fetch --manufacturer AeroTech H128W

The curve is ThrustCurve’s, found by the file’s manufacturer and designation. For the motors of OpenRocket’s own example designs, hpr knows which file holds the curve OpenRocket flies and takes it; for any other motor, the file may not be the one OpenRocket flies. A note under the flight names the curve file, who measured it, and which of the two it is. Motors from ThrustCurve.org says how hpr picks one. If you have the motor’s .eng or .rse file, fly it with --motor: hpr sim my-rocket.ork --motor AeroTech_H128W.eng.

Plot it, or save the numbers

--plot draws the flight as a picture; --export saves every number.

hpr sim validation/fixtures/ork/guides/level-1.ork --plot level-1.svg --export level-1.csv

The plot is one fixed figure: altitude, speed and acceleration against time, each event marked. An SVG opens in any web browser; Plotting the flight shows one. The export holds every quantity hpr tracks, every 0.01 s; the file’s extension picks the format (.csv, .json, .parquet, .geojson or .kml), and Exporting a flight says what each column means. --json prints the summary itself as data, for a script to read.

When hpr refuses

hpr sim refuses, with the reason, rather than fly something other than your design. The common reasons, and what to do:

Warnings are not refusals. A warning: line flags something the design’s checks found unusual but buildable, such as a motor longer than its mount tube, and the flight goes on.

What it leaves out

• The launch conditions in your file. Give them as options, above.
• Real weather. One wind at every height, in the standard atmosphere. hpr weather fetches a launch day’s profile, but hpr sim doesn’t fly it yet (#265, flying a weather profile).
• A fall with no parachute open. The landing is then marked “not a prediction” (the landing).
• A verdict. hpr prints estimates. Whether a rocket is fit to fly is for you, the motor’s printed data and your range safety officer to decide.

Pick a motor

This guide shortlists the motors that fit a rocket, flies the rocket on each, and picks an ejection delay, all with hpr on the command line. It is for a flier choosing a motor for a design they already have. hpr’s figures are estimates from a model: Accuracy says how close they come, and the motor’s printed data and your range safety officer have the last word. The outputs on this page are made by running each command, and CI checks that they still match what hpr prints.

The steps:

1. List the motors that fit.
2. Fly the rocket on each.
3. Compare them.
4. Choose the delay.
5. Put the choice in your design.

The examples use the guides’ own rocket, level-1.ork, with a 38 mm motor mount; Fly your .ork introduces it.

List the motors that fit

Start from the mount’s diameter: a motor’s case must match it. In OpenRocket, the motor mount tube’s inner diameter is the size; a 38 mm mount takes 38 mm motors. hpr motors list filters the 32 motors built into hpr by diameter, impulse class or maker:

$ hpr motors list --diameter 38
6 motors from ThrustCurve.org data files marked public domain, downloaded 2026-09-17; size, masses and delays from each file's header, the rest from its curve.

designation  maker     class  dia mm  len mm  impulse N·s  avg N  burn s  delays
G69N         AeroTech  G          38     106        136.3   72.1    1.89  1000
H170M        AeroTech  H          38     191        318.0  165.4    1.92  2,4,6,8,10,14
H125-CT      Loki      H          38   177.8        241.7  125.0    1.93  8-18
I175WS       AeroTech  I          38     214        333.2  177.5    1.88  5-9-13
411I175-14A  Cesaroni  I          38     245        411.4  174.1    2.36  6-8-9-11-12-13
I377-CT      Loki      I          38     292        525.8  377.9    1.39  8-18

The figures are worked out from each motor’s public-domain ThrustCurve.org curve file, the curve hpr flies (The bundled motors). The delays column lists the ejection delays as the file’s header writes them, in seconds after burnout, with - between settings (5-9-13 is 5, 9 and 13 s; 8-18 is 8 and 18 s), which can be fewer than the maker sells: check the motor’s instructions. P (or 1000) is a plugged motor with no ejection charge. A Level 1 certification flight uses an H or I motor (NAR and Tripoli’s Level 1 rules; Check stability for a certification flight quotes them).

Many more motors exist than the 32 built in. Name any motor ThrustCurve.org lists, such as --motor H128W, and hpr fetches its thrust curve once online and keeps it (Fetch a motor hpr doesn’t have). hpr motors search lists what vendors have in stock and at what price (Motors you can buy). hpr motors show gives one motor’s figures as hpr reads its curve:

$ hpr motors show I175WS
I175WS (AeroTech), from the bundled catalog
  impulse class    I
  total impulse    333.2 N·s
  average thrust   177.5 N
  peak thrust      252.6 N
  burn time        1.88 s, from 0.023 s to 1.900 s (NFPA 1125, 5% of peak)
  propellant       168.0 g of 348.0 g loaded
  casing           38 mm across, 214 mm long
  delays           5 s, 9 s, 13 s
  curve file       https://www.thrustcurve.org/simfiles/5f4294d20002e900000008bf/ (public domain)

Fly the rocket on each

--motor flies the design with another motor in its mount, and --delay sets that motor’s ejection delay. Without --delay, the motor fires no charge, so a parachute set to open on the charge, as the guide rocket’s is, never opens. Give one of the motor’s delays, in seconds, or P for a plugged motor when your electronics fire the charges. This flies the guide rocket on a Loki H125, with a 10 s delay:

$ hpr sim validation/fixtures/ork/guides/level-1.ork --motor H125-CT --delay 10
Level 1 guide rocket (level-1.ork)
configuration 1 of 2: [H170M-10] with --motor H125-CT --delay 10
help: --config flies the others, by number or name: 2 [I175WS-9]

static margin         1.59 calibres off the rail; least 1.59 calibres, at 0.17 s, before apogee
apogee                914.5 m above the site at 11.42 s
rail exit speed       25.9 m/s
delay                 apogee 9.42 s after burnout; the motor's set delay: 10 s; its charge fires 0.58 s after apogee
descent               4.7 m/s at landing under `Parachute`

motor: 1 × H125-CT (from the bundled catalog) in `Motor mount tube`, lit at launch
recovery: `Parachute` at the ejection charge, 0.520 m² of drag area, opened at 12.00 s
launched at 0° N, 0° E, 0 m above sea level, from a 1.5 m vertical rail, in calm air
help: see the Accuracy page before trusting these numbers: https://nrdptel.github.io/hpr-sim/accuracy.html
note: the file's 1 recovery device flies as OpenRocket flies it: each opens fully at its event, with the file's drag coefficient or OpenRocket's own, and once one opens the rocket descends as a point under the open devices' drag alone
warning: drag: issue #18: skin friction is taken as fully turbulent, but on a smooth surface the flow stays laminar near the nose, where friction is lower: hpr's reads high by 3.6% on RocketPy's Calisto at Mach 0.3; if this surface is that smooth, the drag reads high, so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are (https://github.com/nrdptel/hpr-sim/issues/18)
warning: stability: issue #172: the static margin read up to 0.1108 calibres higher than OpenRocket's on four private designs, for a reason not yet found, so this flight's margin may read high by as much (https://github.com/nrdptel/hpr-sim/issues/172)

event                   time     height       speed
liftoff               0.02 s      0.4 m     0.0 m/s
rail exit             0.17 s      1.9 m    25.9 m/s
burnout               2.00 s    303.8 m   201.2 m/s
apogee               11.42 s    914.5 m     0.1 m/s
charge               12.00 s    912.8 m     5.6 m/s
deployment           12.00 s    912.8 m     5.6 m/s
ground hit          202.71 s      0.0 m     4.7 m/s
(heights are the center of gravity's above the site; speeds are over the ground)

top speed             217.0 m/s at 1.56 s
top Mach number       0.639
landing               0.7 m from the pad at 202.71 s, at 4.7 m/s

And on the hardest-hitting motor in the list, a Loki I377, with the same delay:

$ hpr sim validation/fixtures/ork/guides/level-1.ork --motor I377-CT --delay 10
Level 1 guide rocket (level-1.ork)
configuration 1 of 2: [H170M-10] with --motor I377-CT --delay 10
help: --config flies the others, by number or name: 2 [I175WS-9]

static margin         1.18 calibres off the rail; least 1.18 calibres, at 0.08 s, before apogee
apogee                1320.4 m above the site at 12.02 s
rail exit speed       42.3 m/s
delay                 apogee 10.59 s after burnout; the motor's set delay: 10 s; its charge fires 0.59 s before apogee
descent               5.0 m/s at landing under `Parachute`

motor: 1 × I377-CT (from the bundled catalog) in `Motor mount tube`, lit at launch
recovery: `Parachute` at the ejection charge, 0.520 m² of drag area, opened at 11.43 s
launched at 0° N, 0° E, 0 m above sea level, from a 1.5 m vertical rail, in calm air
help: see the Accuracy page before trusting these numbers: https://nrdptel.github.io/hpr-sim/accuracy.html
note: the file's 1 recovery device flies as OpenRocket flies it: each opens fully at its event, with the file's drag coefficient or OpenRocket's own, and once one opens the rocket descends as a point under the open devices' drag alone
warning: design checks: the motor in `Motor mount tube` reaches 22.0 mm past the mount's forward end (configuration [H170M-10] with --motor I377-CT --delay 10)
warning: drag: issue #67: a cone-like nose's or shoulder's pressure drag reads high from Mach 0.8 (about twice a measured cone's at Mach 0.85, still +15% at 1.5), so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are; this flight reaches Mach 1.10 at 1.1 s (https://github.com/nrdptel/hpr-sim/issues/67)
warning: drag: issue #68: base drag reads high from Mach 0.8 to 1.2 (0.225 against a measured 0.156 at Mach 0.9), so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are; this flight reaches Mach 1.10 at 1.1 s (https://github.com/nrdptel/hpr-sim/issues/68)
warning: drag: issue #222: supersonic pressure drag on an ogive nose or airfoil fins is about twice OpenRocket's, and which is right is unresolved: if hpr's is high, so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are; this flight reaches Mach 1.10 at 1.1 s (https://github.com/nrdptel/hpr-sim/issues/222)
warning: drag: issue #18: skin friction is taken as fully turbulent, but on a smooth surface the flow stays laminar near the nose, where friction is lower: hpr's reads high by 3.6% on RocketPy's Calisto at Mach 0.3; if this surface is that smooth, the drag reads high, so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are (https://github.com/nrdptel/hpr-sim/issues/18)
warning: stability: issue #172: the static margin read up to 0.1108 calibres higher than OpenRocket's on four private designs, for a reason not yet found, so this flight's margin may read high by as much (https://github.com/nrdptel/hpr-sim/issues/172)

event                   time     height       speed
liftoff               0.00 s      0.3 m     0.0 m/s
rail exit             0.08 s      1.8 m    42.3 m/s
burnout               1.43 s    384.0 m   335.1 m/s
charge               11.43 s   1318.2 m    10.1 m/s
deployment           11.43 s   1318.2 m    10.1 m/s
apogee               12.02 s   1320.4 m     0.0 m/s
ground hit          269.86 s      0.0 m     5.0 m/s
(heights are the center of gravity's above the site; speeds are over the ground)

top speed             371.7 m/s at 1.08 s
top Mach number       1.095
landing               0.8 m from the pad at 269.86 s, at 5.0 m/s

The warning says the I377’s 292 mm case, which sits 10 mm out of the back of the rocket’s 260 mm mount tube, reaches 22.1 mm past the tube’s forward end. hpr flies it as drawn; whether it fits the real rocket is for you to check. --motor replaces the motor of the configuration flown, so --config picks which of the file’s configurations it goes in, and --mount which mount, if the design has several.

Compare them

Read the same five lines for each motor: margin, apogee, rail exit speed, delay and descent. Between the two flights above:

• Apogee. The I377 climbs higher. If your field has a ceiling, its waiver sets it, not hpr.
• Rail exit speed. The I377 leaves the rail much faster. The safety codes ask for a speed that ensures a stable flight but give no number; competitions set their own, such as 25 m/s for the Spaceport America Cup (Rail exit speed quotes them).
• Stability margin. It changes with the motor: a motor’s mass sits behind the center of gravity, so a heavier motor moves the center of gravity aft, toward the center of pressure, and shrinks the margin. Check it with every motor you might fly (Check stability for a certification flight).
• Top Mach number. The I377 takes the rocket past the speed of sound, Mach 1; the H125 stays well below it, and the H170M, at Mach 0.842, just reaches the range below. Between Mach 0.8 and 1.2, hpr’s center of pressure is up to 2.36 calibres behind NASA’s wind-tunnel data, so its margin there reads high (Known gaps), and published guidance asks for a larger margin (Compare with published guidance).

Flying a few more motors is quick: change --motor and --delay and run again. --json prints each flight as data, for a script that tabulates many.

Choose the delay

The delay line’s first figure is the coast, from burnout to apogee: a delay near it fires the charge near apogee, where the rocket moves slowest. The second figure is the delay you gave, and the third says how far from apogee the charge then fires. In the events table, the charge row gives the speed at that moment: the further the charge is from apogee, the faster the rocket moves when the parachute comes out.

In the H125 flight above, the coast is 9.42 s, and the 10 s delay fires the charge 0.58 s after apogee. The H125’s delays are 8, 10, 12, 14 and 18 s, so 10 s is the nearest. hpr flies any delay you give; give one the maker sells, or one your motor’s delay can be adjusted to. A delay is a burning fuse, and real ones vary from motor to motor; hpr flies the stated time exactly. Monte Carlo dispersion, in the library, can scatter it.

The guide rocket’s own second configuration, [I175WS-9], is an example where the set delay fires before apogee:

$ hpr sim validation/fixtures/ork/guides/level-1.ork --config 2
Level 1 guide rocket (level-1.ork)
configuration 2 of 2: [I175WS-9]
help: --config flies the others, by number or name: 1 [H170M-10]

static margin         1.67 calibres off the rail; least 1.67 calibres, at 0.14 s, before apogee
apogee                1100.7 m above the site at 11.48 s
rail exit speed       28.9 m/s
delay                 apogee 9.51 s after burnout; the motor's set delay: 9 s; its charge fires 0.51 s before apogee
descent               4.5 m/s at landing under `Parachute`

motor: 1 × I175WS (the design's) in `Motor mount tube`, lit at launch
recovery: `Parachute` at the ejection charge, 0.520 m² of drag area, opened at 10.97 s
launched at 0° N, 0° E, 0 m above sea level, from a 1.5 m vertical rail, in calm air
help: see the Accuracy page before trusting these numbers: https://nrdptel.github.io/hpr-sim/accuracy.html
note: the file's 1 recovery device flies as OpenRocket flies it: each opens fully at its event, with the file's drag coefficient or OpenRocket's own, and once one opens the rocket descends as a point under the open devices' drag alone
warning: drag: issue #67: a cone-like nose's or shoulder's pressure drag reads high from Mach 0.8 (about twice a measured cone's at Mach 0.85, still +15% at 1.5), so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are; this flight reaches Mach 0.83 at 1.8 s (https://github.com/nrdptel/hpr-sim/issues/67)
warning: drag: issue #68: base drag reads high from Mach 0.8 to 1.2 (0.225 against a measured 0.156 at Mach 0.9), so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are; this flight reaches Mach 0.83 at 1.8 s (https://github.com/nrdptel/hpr-sim/issues/68)
warning: drag: issue #18: skin friction is taken as fully turbulent, but on a smooth surface the flow stays laminar near the nose, where friction is lower: hpr's reads high by 3.6% on RocketPy's Calisto at Mach 0.3; if this surface is that smooth, the drag reads high, so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are (https://github.com/nrdptel/hpr-sim/issues/18)
warning: stability: issue #172: the static margin read up to 0.1108 calibres higher than OpenRocket's on four private designs, for a reason not yet found, so this flight's margin may read high by as much (https://github.com/nrdptel/hpr-sim/issues/172)

event                   time     height       speed
liftoff               0.02 s      0.4 m     0.0 m/s
rail exit             0.14 s      1.9 m    28.9 m/s
burnout               1.97 s    385.2 m   260.5 m/s
charge               10.97 s   1099.1 m     8.0 m/s
deployment           10.97 s   1099.1 m     8.0 m/s
apogee               11.48 s   1100.7 m     0.0 m/s
ground hit          247.48 s      0.0 m     4.5 m/s
(heights are the center of gravity's above the site; speeds are over the ground)

top speed             281.3 m/s at 1.75 s
top Mach number       0.830
landing               0.7 m from the pad at 247.48 s, at 4.5 m/s

Put the choice in your design

hpr doesn’t change your .ork file: set the motor and its delay in OpenRocket, save, and fly the file again. Without --motor, hpr sim flies the motors and delays the file holds, as Fly your .ork shows, and its delay line checks the delay you set.

What it leaves out

• Motor-to-motor differences. Each motor flies one thrust curve, ThrustCurve.org’s, and its stated delay exactly. Real motors differ a little from their published curves.
• Fit. hpr’s design checks flag a motor wider than its mount, and warn on one longer than its tube; they don’t know your motor retainer, thrust ring or closure.
• A verdict. hpr ranks nothing as safe or unsafe. The motor’s printed data, the safety codes and your range safety officer decide.

Check stability for a certification flight

This guide reads hpr’s stability numbers for a rocket you plan to fly for a certification, checks them with every motor you might use, and says how far to trust them. It is for a flier preparing a certification flight; the rules it quotes are Level 1’s. hpr gives no verdict: the safety codes ask you to check stability, and the range safety officer (RSO) and your certifying member decide. hpr’s margin at rod clearance agrees with OpenRocket 24.12’s to within 0.016 calibres on 41 of OpenRocket’s 53 example flights, but no margin of hpr’s has been checked against a measured rocket. On OpenRocket’s two pod examples it reads 0.07 calibres above OpenRocket’s, and near the speed of sound its flight margin reads high (how far to trust it). The outputs on this page are made by running each command, and CI checks that they still match what hpr prints.

The steps:

1. Know what the rules ask.
2. Read the margin.
3. Check every motor you might fly.
4. Compare with published guidance.
5. Check the rail exit speed.
6. Fly the rocket you built.

What the rules ask

The safety codes require a stability check, but name no margin. The words below are the organisations’ own, read on 2026-10-04; check their current pages before your flight. This is not legal or regulatory advice.

• The NAR’s High Power Rocket Safety Code (revision of August 2012): “I will check the stability of my rocket before flight and will not fly it if it cannot be determined to be stable.”
• Tripoli’s Unified Safety Code (version 2, effective January 2026), 7-1.2: “Stability; the flier shall document the location of the center of pressure and be able to demonstrate the center of gravity.”
• A Level 1 flight uses an H or I motor. The NAR’s Level 1 procedures (revision of January 1, 2022): “at least one H or I impulse class motor”; Tripoli’s: “a single certified H or I motor”. Neither page states a margin.

The NAR’s procedures add that the candidate may be asked about “the model’s center of gravity and center of pressure, methods used to determine model stability”. hpr’s output gives both points’ separation; --json and --export give more.

Read the margin

The static margin line is the distance from the center of gravity back to the center of pressure, in body diameters (calibres), as the rocket leaves the rail; then its least value up to apogee. A positive margin turns the nose back into the oncoming air when the rocket is disturbed (stability margin). This flies the guides’ own rocket, level-1.ork, on its default motor, an AeroTech H170M:

$ hpr sim validation/fixtures/ork/guides/level-1.ork
Level 1 guide rocket (level-1.ork)
configuration 1 of 2: [H170M-10]
help: --config flies the others, by number or name: 2 [I175WS-9]

static margin         1.70 calibres off the rail; least 1.70 calibres, at 0.12 s, before apogee
apogee                1065.1 m above the site at 11.62 s
rail exit speed       26.3 m/s
delay                 apogee 9.48 s after burnout; the motor's set delay: 10 s; its charge fires 0.52 s after apogee
descent               4.4 m/s at landing under `Parachute`

motor: 1 × H170M (the design's) in `Motor mount tube`, lit at launch
recovery: `Parachute` at the ejection charge, 0.520 m² of drag area, opened at 12.14 s
launched at 0° N, 0° E, 0 m above sea level, from a 1.5 m vertical rail, in calm air
help: see the Accuracy page before trusting these numbers: https://nrdptel.github.io/hpr-sim/accuracy.html
note: the file's 1 recovery device flies as OpenRocket flies it: each opens fully at its event, with the file's drag coefficient or OpenRocket's own, and once one opens the rocket descends as a point under the open devices' drag alone
warning: drag: issue #67: a cone-like nose's or shoulder's pressure drag reads high from Mach 0.8 (about twice a measured cone's at Mach 0.85, still +15% at 1.5), so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are; this flight reaches Mach 0.84 at 1.7 s (https://github.com/nrdptel/hpr-sim/issues/67)
warning: drag: issue #68: base drag reads high from Mach 0.8 to 1.2 (0.225 against a measured 0.156 at Mach 0.9), so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are; this flight reaches Mach 0.84 at 1.7 s (https://github.com/nrdptel/hpr-sim/issues/68)
warning: drag: issue #18: skin friction is taken as fully turbulent, but on a smooth surface the flow stays laminar near the nose, where friction is lower: hpr's reads high by 3.6% on RocketPy's Calisto at Mach 0.3; if this surface is that smooth, the drag reads high, so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are (https://github.com/nrdptel/hpr-sim/issues/18)
warning: stability: issue #172: the static margin read up to 0.1108 calibres higher than OpenRocket's on four private designs, for a reason not yet found, so this flight's margin may read high by as much (https://github.com/nrdptel/hpr-sim/issues/172)

event                   time     height       speed
liftoff               0.00 s      0.4 m     0.0 m/s
rail exit             0.12 s      1.9 m    26.3 m/s
burnout               2.14 s    406.4 m   240.4 m/s
apogee               11.62 s   1065.1 m     0.1 m/s
charge               12.14 s   1063.7 m     5.1 m/s
deployment           12.14 s   1063.7 m     5.1 m/s
ground hit          245.78 s      0.0 m     4.4 m/s
(heights are the center of gravity's above the site; speeds are over the ground)

top speed             285.6 m/s at 1.73 s
top Mach number       0.842
landing               0.7 m from the pad at 245.78 s, at 4.4 m/s

A calibre here is the rocket’s widest body diameter, 66 mm, so a margin of 1.70 calibres puts the center of pressure 1.70 × 66 mm ≈ 112 mm behind the center of gravity. hpr computes the static margin at Mach 0, with the air along the rocket’s axis. The margin grows as propellant burns and the center of gravity moves forward, so its least value is usually the one at the rail. --json also gives the flight margin, at the flight’s own Mach number (min_flight_margin_cal), and where each least value falls (Flight metrics).

Check every motor you might fly

The margin depends on the motor, so check each one you might fly, with its delay. A motor’s mass sits behind the center of gravity, so a heavier motor moves the center of gravity aft and shrinks the margin. The guide rocket’s second configuration flies an I175WS:

$ hpr sim validation/fixtures/ork/guides/level-1.ork --config 2
Level 1 guide rocket (level-1.ork)
configuration 2 of 2: [I175WS-9]
help: --config flies the others, by number or name: 1 [H170M-10]

static margin         1.67 calibres off the rail; least 1.67 calibres, at 0.14 s, before apogee
apogee                1100.7 m above the site at 11.48 s
rail exit speed       28.9 m/s
delay                 apogee 9.51 s after burnout; the motor's set delay: 9 s; its charge fires 0.51 s before apogee
descent               4.5 m/s at landing under `Parachute`

motor: 1 × I175WS (the design's) in `Motor mount tube`, lit at launch
recovery: `Parachute` at the ejection charge, 0.520 m² of drag area, opened at 10.97 s
launched at 0° N, 0° E, 0 m above sea level, from a 1.5 m vertical rail, in calm air
help: see the Accuracy page before trusting these numbers: https://nrdptel.github.io/hpr-sim/accuracy.html
note: the file's 1 recovery device flies as OpenRocket flies it: each opens fully at its event, with the file's drag coefficient or OpenRocket's own, and once one opens the rocket descends as a point under the open devices' drag alone
warning: drag: issue #67: a cone-like nose's or shoulder's pressure drag reads high from Mach 0.8 (about twice a measured cone's at Mach 0.85, still +15% at 1.5), so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are; this flight reaches Mach 0.83 at 1.8 s (https://github.com/nrdptel/hpr-sim/issues/67)
warning: drag: issue #68: base drag reads high from Mach 0.8 to 1.2 (0.225 against a measured 0.156 at Mach 0.9), so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are; this flight reaches Mach 0.83 at 1.8 s (https://github.com/nrdptel/hpr-sim/issues/68)
warning: drag: issue #18: skin friction is taken as fully turbulent, but on a smooth surface the flow stays laminar near the nose, where friction is lower: hpr's reads high by 3.6% on RocketPy's Calisto at Mach 0.3; if this surface is that smooth, the drag reads high, so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are (https://github.com/nrdptel/hpr-sim/issues/18)
warning: stability: issue #172: the static margin read up to 0.1108 calibres higher than OpenRocket's on four private designs, for a reason not yet found, so this flight's margin may read high by as much (https://github.com/nrdptel/hpr-sim/issues/172)

event                   time     height       speed
liftoff               0.02 s      0.4 m     0.0 m/s
rail exit             0.14 s      1.9 m    28.9 m/s
burnout               1.97 s    385.2 m   260.5 m/s
charge               10.97 s   1099.1 m     8.0 m/s
deployment           10.97 s   1099.1 m     8.0 m/s
apogee               11.48 s   1100.7 m     0.0 m/s
ground hit          247.48 s      0.0 m     4.5 m/s
(heights are the center of gravity's above the site; speeds are over the ground)

top speed             281.3 m/s at 1.75 s
top Mach number       0.830
landing               0.7 m from the pad at 247.48 s, at 4.5 m/s

--motor flies any other motor in the mount, and --delay sets its ejection delay (Pick a motor). There, the heaviest motor tried, a Loki I377, leaves the guide rocket the smallest margin of the motors flown, and takes it past Mach 1, where the guidance below asks for more.

Compare with published guidance

Published rules of thumb set a lower bound of one calibre, and more for fast flights; these are the sources’ guidance, not hpr’s judgement.

• James Barrowman, who devised the standard way to find the center of pressure, wrote: “A good rule of thumb is to have the static margin equal to the largest diameter of the rocket”, and “Remember that one maximum body diameter is the smallest safe static margin” (Stability of a Model Rocket in Flight, Centuri Technical Information Report TIR-30, 1970, as reprinted in this scanned compilation, PDF pages 73 and 76).
• OpenRocket’s user guide: “The recommended stability margin for subsonic flights is not less than 1.0 caliber, and not less than 2.0 calibers for transonic and supersonic flights” (Overrides and surface finish).
• NASA’s Student Launch handbook for 2027 asks for “a minimum static stability margin of 2.0 while sitting on the pad”.
• The Spaceport America Cup’s design guide (2026, version 1.1) states its limits as a share of the rocket’s length instead: at least 7.5% through a subsonic flight, at most 18% at launch.

A large margin isn’t free. A very stable rocket turns into a crosswind as it leaves the rail (weathercocking), and so flies off the vertical.

Rail exit speed

The rocket must leave the rail fast enough to fly straight, and the codes name no figure. The NAR’s code asks for “rigid guidance until the rocket has attained a speed that ensures a stable flight”; Tripoli’s, 7-3, for guidance “until it has reached the velocity necessary for stable flight”. Competitions set numbers: the Spaceport America Cup’s guide asks for at least 25 m/s (5.3.1), and NASA’s Student Launch handbook for 52 ft/s (15.8 m/s).

The reason is the wind. Just off the rail, a crosswind meets the rocket at an angle whose tangent is the wind speed over the rocket’s speed. At the guide rocket’s 26.3 m/s in a 4 m/s crosswind, that is about 8.6°, since 4 / 26.3 = 0.152 and the angle whose tangent is 0.152 is 8.6°. The larger that angle of attack, the further the rocket turns into the wind, and hpr’s aerodynamics hold only at small angles. Both of hpr’s margins are taken with the air along the axis, at no angle at all. A longer rail raises the exit speed: --rail-length sets it, and --wind the wind (Fly your .ork).

Fly the rocket you built

A design’s center of gravity is a calculation; your built rocket’s is a measurement, and the codes ask you to demonstrate it. Weigh the finished rocket, ready to fly but without its motor, and balance it to find its center of gravity. In OpenRocket, set that mass and center of gravity as overrides on the stage, covering its parts, save, and fly the file again in hpr, which reads those overrides (the .ork page). Leave the motor out of the measurement: an override never covers a motor, in hpr or OpenRocket, and both add the motor’s own mass, so a rocket weighed with its motor in would carry it twice. The margin then rests on your rocket’s measured mass, not the drawing’s.

How far to trust the margin

hpr’s margin has been compared with OpenRocket’s, not with a measured rocket. Both programs start from Barrowman’s method, so agreement says hpr computes it as OpenRocket does, not that either is right (Accuracy).

• OpenRocket’s examples: within 0.016 calibres on 41 of 53 flights, with hpr’s margin taken with the air along the rocket’s axis, as OpenRocket’s is. The margin hpr prints is the weakest plane’s, which on a rocket with a fin set of one or two fins can be lower.
• The three-stage example: on its three flights hpr’s margin is 0.039 to 0.058 calibres below OpenRocket’s. hpr’s center of mass at rod clearance sits 0.043 to 0.062 calibres further aft than OpenRocket’s there, where OpenRocket’s recorded mass reads light (#185); that cause is not yet sized.
• The tube-fin example: a rocket with tube fins is 1.08 calibres below OpenRocket’s: hpr gives 0.79 calibres to OpenRocket’s 1.87. Neither program has been checked against a measured tube-fin rocket; check such a design in both and treat the smaller margin as the more cautious figure, not a bound.
• The pods-and-winglets example: on the five flights of Pods–airframes and winglets, hpr’s margin is 0.071 to 0.076 calibres above OpenRocket’s, the flattering side: hpr calls the rocket more stable than OpenRocket does. Two causes are open: how the two programs count fins that interfere across sets (#325), and the center of pressure of its kinked freeform wings (#326). A flight whose fin sets share a station, more than four fins between them, warns of #325, and a flight with a freeform fin set warns of #326. On a design with pods or freeform fins, check the margin in both and treat the smaller as the more cautious figure, not a bound. The three flights of Pods–powered with recovery deployment read 0.070 calibres above OpenRocket’s too, cause not yet traced.
• Private designs: on 35 flights of 11 designs, hpr’s margin runs from 0.0166 calibres below OpenRocket’s to 0.1108 above. Four designs read 0.0350 to 0.1108 calibres more stable in hpr than in OpenRocket, none with a measured cause yet (#172 and #186, two of the open causes; the private designs). A fifth, launched from a tilted rod, reads 0.0125 to 0.0366 above, most of it traced to the tilt. Reading more stable is the flattering side, so leave room for it near any limit.
• Near the speed of sound: between Mach 0.8 and 1.2, hpr’s center of pressure is up to 2.36 calibres behind NASA’s wind-tunnel data, and wherever it misses by more than half a calibre it sits behind, so the flight margin there reads high: the flattering side (Known gaps). The static margin is computed at Mach 0, so it says nothing about the rocket’s stability in that range; use the transonic guidance above.

Recording a trajectory

This page shows how to get a whole flight out of hpr-sim as a table of numbers over time, which a spreadsheet or a plotting tool reads. It flies the rocket of Getting started again, in the same weather, and keeps its height, speed and position every 5 seconds. It needs the first page’s setup, and a little Rust.

These numbers are not validated. They are the first flight’s, and How far to trust it on that page applies to them too.

Run it

cargo run --example trajectory -p hpr-sim > trajectory.csv

This runs crates/hpr-sim/examples/trajectory.rs and saves what it prints in trajectory.csv, a CSV (comma-separated values) file: a header line naming each column, then one line per moment of the flight. It holds this:

time_s,height_above_ground_m,vertical_speed_m_s,airspeed_m_s,cg_east_m,cg_north_m,cg_up_m
0.000,0.9,0.0,5.0,0.0,0.0,0.9
0.002,0.9,0.0,5.0,0.0,0.0,0.9
0.371,3.9,16.2,17.0,0.0,0.0,3.9
3.259,216.0,110.6,111.4,-9.7,0.0,216.0
5.000,390.8,90.3,91.3,-24.1,0.0,390.8
10.000,707.8,37.5,39.4,-62.1,0.0,707.8
13.830,778.7,0.0,11.4,-88.7,0.0,778.7
14.330,777.6,-4.5,12.0,-91.9,0.0,777.6
15.000,772.6,-10.2,14.3,-95.6,0.0,772.6
20.000,665.5,-26.4,26.5,-98.4,0.1,665.5
25.000,531.1,-27.0,27.0,-78.6,0.1,531.1
30.000,396.4,-26.8,26.8,-54.4,0.1,396.4
35.000,262.6,-26.7,26.7,-29.5,0.1,262.6
39.234,150.0,-26.5,26.5,-8.4,0.1,150.0
40.000,129.7,-26.5,26.5,-4.5,0.0,129.7
40.234,123.5,-26.5,26.5,-3.3,0.0,123.5
45.000,89.0,-6.4,6.4,20.5,0.0,89.0
50.000,57.0,-6.4,6.4,45.5,0.0,57.0
55.000,25.1,-6.4,6.4,70.5,0.0,25.1
58.933,0.0,-6.4,6.4,90.2,0.0,0.0

Like the first flight’s, this output is committed in trajectory.output.txt, and CI runs the program on macOS, Windows and Linux and fails if it prints anything else.

This program rounds as it prints. To save a recording with every digit, as CSV or JSON, or the flight path as a map, see Exporting a flight.

Reading the table

There is a row every 5 seconds, and one at every event, at the moment it happened:

What the numbers show:

• On the pad the airspeed is 5.0 m/s with the rocket standing still: that is the wind.
• The rocket climbs into the wind. The wind blows from the west, and off the rail a stable rocket turns its nose toward the wind it feels (weathercocking), so it drifts west: cg_east_m is −88.7 m at apogee.
• Under the drogue alone it falls at about 27 m/s, and the wind carries it east.
• The main slows it from 26.5 to 6.4 m/s between the row where it opens (40.234) and the next (45.000), and it lands at 6.4 m/s, 90.2 m east of the pad.
• cg_north_m shows 0.1 m for a while, with no wind from the south. The Earth’s rotation nudges a moving rocket sideways, to the right of its motion in the northern hemisphere (Coriolis acceleration). While the rocket moves west, that is north: it drifts up to 6.3 cm, which the table rounds to 0.0 or 0.1 m.
• cg_up_m and height_above_ground_m agree here, and don’t in general. The launch frame is a flat plane, and the Earth curves away below it, so far from the pad cg_up_m reads low: on the ground 10 km from the pad, it is −7.8 m. At this landing, 94 m out, it is under a millimeter low. For heights, use height_above_ground_m.

Record something else

The program below makes its recorder with Recorder::new(vec![Channel::Time, Channel::HeightAboveGround, ...], Some(5.0)), and passes it to run, which feeds it every step of the flight. Change either argument:

• The interval is Some(5.0), a row every 5 s. Some(0.1) gives a smooth plot, about 600 rows for this flight. None keeps a row at the end of every step the integrator takes, which is as fine as the flight was computed (Time integration).
• The channels are the columns. Others include the Mach number, the angle of attack, the dynamic pressure, the thrust, the mass, the attitude and the rotation rates. The Channel page of the API reference lists every one with its unit, and Channel::ALL keeps them all.
• After the flight, recorder.columns() gives the column names, units included, and recorder.rows() gives one list of numbers per row, in the same order.

To save a file straight from Rust instead of printing, write the same lines to a std::fs::File.

The program

This is the whole program, line for line the file CI runs. Everything above the recorder is the first flight’s setup, which Getting started explains step by step.

//! A trajectory to plot: the flight of `first_flight.rs`, recorded every 5 s and at every event,
//! printed as CSV (comma-separated values), which a spreadsheet or a plotting tool reads.
//!
//! Run it from anywhere in the repository, and save what it prints to a file:
//!
//! ```text
//! cargo run --example trajectory -p hpr-sim > trajectory.csv
//! ```
//!
//! The documentation site's *Recording a trajectory* page (`docs/recording-a-trajectory.md`)
//! walks through it. What it prints is kept next to it in `trajectory.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::geodesy::Geodetic;
use hpr_design::Rocket;
use hpr_sim::{
    CanopyType, Channel, Device, DeviceDrag, Environment, FlightSettings, Rail, Recorder,
    Simulation, Termination, Trigger,
};

fn main() -> Result<(), Box<dyn Error>> {
    // The first flight: Valetudo on a K400C, from a 3 m vertical rail in New Mexico, in 5 m/s of
    // wind from the west, with a drogue at apogee and a main at 150 m.
    let rocket: Rocket = serde_json::from_str(include_str!(
        "../../../validation/designs/rocketpy-valetudo.json"
    ))?;
    let site = Geodetic::from_degrees(32.99, -106.97, 1400.0)?;
    let environment =
        Environment::standard(site)?.with_wind(ConstantWind::new(5.0, 270_f64.to_radians())?);
    let simulation = Simulation::new(
        &rocket,
        "example",
        environment,
        Rail::vertical(3.0),
        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),
    ])?;

    // What to keep, and how often: the time, the height above the pad, the vertical speed, the
    // airspeed and where the center of gravity is (meters east, north and up of the pad), every
    // 5 s. A recorder also keeps a row at every event, such as burnout or a parachute opening.
    // For a smooth plot, use `Some(0.1)`; `None` keeps a row at the end of every step.
    let mut recorder = Recorder::new(
        vec![
            Channel::Time,
            Channel::HeightAboveGround,
            Channel::VerticalSpeed,
            Channel::Airspeed,
            Channel::CgPosition,
        ],
        Some(5.0),
    )?;
    let flight = simulation.run(&mut recorder)?;
    if flight.termination != Termination::GroundHit {
        return Err(format!("the flight ended with {:?}", flight.termination).into());
    }

    // One header line with each column's name and unit, then one line per row: the time to
    // 0.001 s, the rest to 0.1.
    println!("{}", recorder.columns().join(","));
    for row in recorder.rows() {
        let fields: Vec<String> = row
            .iter()
            .enumerate()
            .map(|(column, &value)| rounded(value, if column == 0 { 3 } else { 1 }))
            .collect();
        println!("{}", fields.join(","));
    }
    Ok(())
}

/// `value` to `decimals` places, without the minus sign of a value that rounds to zero. Some values
/// that are zero in principle come out a hair below it: the vertical speed at ignition and at
/// apogee, the landing height, which is found just below the ground, and the landing's `cg_up_m`,
/// under a millimeter below the pad's level because the ground curves away.
fn rounded(value: f64, decimals: usize) -> String {
    let text = format!("{value:.decimals$}");
    match text.strip_prefix('-') {
        Some(unsigned) if unsigned.chars().all(|c| c == '0' || c == '.') => unsigned.to_owned(),
        _ => text,
    }
}

Exporting a flight

This page shows how to save a flight as files other programs read: a table of numbers over time for a spreadsheet or a plotting tool (CSV, JSON or Parquet), and a map of the flight path and the landing (GeoJSON or KML, which Google Earth, QGIS and most web maps open). It flies the rocket of Getting started again and writes all five files. It needs the first page’s setup, and a little Rust.

Without writing Rust, hpr sim --export writes the same five formats for a .ork or hpr design file, every quantity hpr tracks in each (The command line). Its maps mark the landing when a parachute or streamer opened, as a .ork file’s do, and no landing otherwise (the landing).

The files are exact, the flight is not validated. Every number in a file reads back to exactly the value the simulator computed, and tests check that. The flight itself is the first flight’s, and How far to trust it on that page applies to it too.

Run it

cargo run --example export_flight -p hpr-sim --features parquet -- my-flight

This runs crates/hpr-sim/examples/export_flight.rs, which writes five files into the folder my-flight (without a folder, into hpr-sim-export in the system’s temporary folder) and prints what it wrote. Parquet is an optional feature of hpr-sim, named parquet, so the command turns it on; without it, cargo says the example needs it. The feature adds no other library; it is optional so that a program with no use for a binary file format leaves it out. In your own program, turn it on in Cargo.toml with hpr-sim = { ..., features = ["parquet"] }.

wrote 67 rows of 5 columns, a path of 67 points
  flight.csv
  flight.json
  flight.parquet, 3203 bytes
  flight.geojson
  flight.kml
landed at 32.99000° N, 106.96904° W, 90 m from the pad, at 58.9 s

CI runs it on macOS, Windows and Linux and fails if it prints anything else. The files hold every number to its last digit, which may differ in the last place between operating systems, so the program prints a rounded summary instead of the files.

The five files

Which program wrote a file

Each file but the CSV names the program that wrote it, its version and its designation in the FusionSpace product system, the way a drawing’s title block names the tool that made it:

• JSON and GeoJSON: a tool object at the top, {"name": "hpr-sim", "version": "0.1.0", "designation": "FS · SW · TOOL 005"}. In GeoJSON it is a foreign member, a key the standard doesn’t define, which RFC 7946 (section 6.1) allows and map programs pass over.
• KML: a comment on the second line, <!-- hpr-sim 0.1.0 · FS · SW · TOOL 005 -->.
• Parquet: three entries of the file’s key-value metadata: tool (hpr-sim), tool_version and designation. pyarrow shows them with pyarrow.parquet.read_metadata(path).metadata.

The CSV holds only the header and the rows, so a spreadsheet opens it cleanly. hpr sim writes its title block beside it instead: flight.meta.json for flight.csv, with the same tool object, the CSV’s file name, the design and configuration flown, and the number of rows. The library’s export::csv writes the CSV alone.

To look at the Parquet file from Python, install pandas and pyarrow (pip install pandas pyarrow; pandas can’t read Parquet on its own), then:

python -c "import pandas; print(pandas.read_parquet('my-flight/flight.parquet'))"

or, with DuckDB’s command-line program, duckdb -c "SELECT * FROM 'my-flight/flight.parquet'".

The tables hold whatever channels the recorder kept, one row per recorded moment. The maps need the recorder to keep the time and the center of gravity’s position (Channel::Time and Channel::CgPosition); they place each recorded position on the Earth, with the same conversion as the landing point in Flight metrics.

A map line in KML looks like this, one longitude,latitude,height per recorded moment (the digits here are cut short):

<LineString>
<altitudeMode>absolute</altitudeMode>
<coordinates>
-106.97,32.99,1400.93591...
-106.97,32.98999...,1403.85869...

Heights: two datums

A height needs something to count from, a datum. The two map formats use different ones, because their standards say so:

• GeoJSON heights are above the WGS 84 ellipsoid, the smooth shape GPS uses (ellipsoidal height; RFC 7946, section 4).
• KML heights with altitudeMode absolute are above sea level, which KML takes from the EGM96 geoid (height above sea level; OGC KML 2.2, 07-147r2).

Sea level sits above or below the ellipsoid by the geoid undulation N, up to about 100 m. hpr has no model of it, so it uses the value the flight was given (Environment::with_geoid_undulation_m, zero unless set), the same for every point of the flight. The geoid’s slope, about 5 cm per kilometer and up to some 30 cm in mountains, moves it by centimeters to decimeters over a rocket’s few kilometers. For example, at a site where sea level is 25 m below the ellipsoid (N = −25 m), a point 1500 m above the ellipsoid is written as 1500 m in GeoJSON and as 1525 m in KML. The first flight leaves N at zero, so its two files agree; at the real site sea level is some tens of meters below the ellipsoid, so give N for heights you mean to trust.

How the files are checked

• Numbers: each is written in the shortest form that reads back to the same number, and the tests read every file back and compare it with the recording exactly, not within a tolerance. A value that isn’t a finite number is refused with an error rather than written as NaN or null, which different programs read differently.
• GeoJSON: checked against the published GeoJSON schema (geojson.org/schema), with longitude before latitude as the standard requires. A test also shows the check rejects a broken file.
• KML: parsed by a strict XML parser, and checked for the KML 2.2 namespace, the height mode and every coordinate.
• Parquet: hpr-sim writes the file itself, from the format’s specification. The tests read it back with an independent reader, Apache’s own Parquet library for Rust, and compare every number bit for bit. One test uses a recording of every channel (30 columns today) long enough to fill at least three data pages per column, and another compares a small file with bytes worked out by hand from the specification. Once, by hand, when this was written, pyarrow 25.0.1 and DuckDB 1.5.5 each read the example’s file and a 30-column, 3005-row file and got the same numbers as the matching CSV. CI does not repeat that check.

The tests are in crates/hpr-sim/src/export.rs and crates/hpr-sim/src/export/parquet.rs.

What it leaves out

• Parquet compression and statistics: the Parquet file is not compressed and carries no per-page minimum and maximum. It takes 8 bytes per number, plus a header of about 20 bytes per page of up to 1024 numbers and a short index of the columns at the end of the file: the example’s is 3203 bytes, and its CSV about 5.5 kB. Without the minimums and maximums, a tool such as DuckDB can’t skip parts of the file when filtering (say WHERE time_s > 10) and reads it all, which for one flight takes no noticeable time.
• A path over the antimeridian (±180° longitude) is not cut in two as RFC 7946 asks, so a map would draw it the long way round the globe.
• Landing heights: a landing is a point on the ground, without a height.
• A summary file: the flight’s peaks and margins (Flight metrics) are not in these files. A FlightSummary converts to JSON on its own with serde_json::to_string, but that path writes a value that isn’t finite as null rather than refusing it.

The choices are recorded in ADR-079: exports as text built in the core and ADR-080: Parquet written in-house, read back by Apache’s library.

The program

This is the whole program, line for line the file CI runs. Everything above the recorder is the first flight’s setup, which Getting started explains step by step.

//! A flight written out for other programs: the flight of `first_flight.rs`, recorded every 1 s
//! and at every event, saved as CSV, JSON and Parquet tables and as a GeoJSON and a KML map of its
//! path and landing.
//!
//! Run it from anywhere in the repository, naming the folder to write the five files to. Parquet
//! is an optional feature of the library, so the command turns it on:
//!
//! ```text
//! cargo run --example export_flight -p hpr-sim --features parquet -- my-flight
//! ```
//!
//! Without a folder it writes them to `hpr-sim-export` in the system's temporary folder. The
//! documentation site's *Exporting a flight* page (`docs/exporting-a-flight.md`) walks through it.
//! What it prints is kept next to it in `export_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"
)]
#![allow(
    clippy::disallowed_methods,
    reason = "the library builds each file's text without I/O; this program writes the files"
)]

use std::error::Error;
use std::path::PathBuf;

use hpr_atmos::ConstantWind;
use hpr_core::geodesy::Geodetic;
use hpr_design::Rocket;
use hpr_sim::{
    CanopyType, Channel, Device, DeviceDrag, Environment, FlightMetrics, FlightSettings, Rail,
    Recorder, Simulation, Termination, Trigger, export,
};

fn main() -> Result<(), Box<dyn Error>> {
    // The first flight: Valetudo on a K400C, from a 3 m vertical rail in New Mexico, in 5 m/s of
    // wind from the west, with a drogue at apogee and a main at 150 m.
    let rocket: Rocket = serde_json::from_str(include_str!(
        "../../../validation/designs/rocketpy-valetudo.json"
    ))?;
    let site = Geodetic::from_degrees(32.99, -106.97, 1400.0)?;
    let environment =
        Environment::standard(site)?.with_wind(ConstantWind::new(5.0, 270_f64.to_radians())?);
    let simulation = Simulation::new(
        &rocket,
        "example",
        environment,
        Rail::vertical(3.0),
        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),
    ])?;

    // Two watchers on one flight: the metrics, for the landing, and a recorder of the time, the
    // height above the pad and the center of gravity's position, which a map needs.
    let recorder = Recorder::new(
        vec![
            Channel::Time,
            Channel::HeightAboveGround,
            Channel::CgPosition,
        ],
        Some(1.0),
    )?;
    let mut watchers = (FlightMetrics::new(), recorder);
    let flight = simulation.run(&mut watchers)?;
    if flight.termination != Termination::GroundHit {
        return Err(format!("the flight ended with {:?}", flight.termination).into());
    }
    let (metrics, recorder) = watchers;
    let summary = metrics.summary(&flight, simulation.environment())?;

    // The path on the Earth, then the five files. Each function returns the file's contents:
    // text, or bytes for Parquet, which is a binary format.
    let track = export::track(&recorder, simulation.environment())?;
    let files = [
        ("flight.csv", export::csv(&recorder)?.into_bytes()),
        ("flight.json", export::json(&recorder)?.into_bytes()),
        ("flight.parquet", export::parquet(&recorder)?),
        (
            "flight.geojson",
            export::geojson(&track, &summary)?.into_bytes(),
        ),
        (
            "flight.kml",
            export::kml(&track, &summary, "Valetudo, K400C")?.into_bytes(),
        ),
    ];
    let folder = match std::env::args_os().nth(1) {
        Some(folder) => PathBuf::from(folder),
        None => std::env::temp_dir().join("hpr-sim-export"),
    };
    std::fs::create_dir_all(&folder)?;
    for (name, contents) in &files {
        std::fs::write(folder.join(name), contents)?;
    }

    // What was written, and where it landed, to five decimal places of a degree (about a meter).
    // The site is west of Greenwich, so the longitude is printed as degrees west.
    println!(
        "wrote {} rows of {} columns, a path of {} points",
        recorder.rows().len(),
        recorder.columns().len(),
        track.len()
    );
    for (name, contents) in &files {
        // The Parquet file's size is the same on every system: its numbers take 8 bytes each,
        // however many digits they have.
        if name.ends_with(".parquet") {
            println!("  {name}, {} bytes", contents.len());
        } else {
            println!("  {name}");
        }
    }
    if let Some(landing) = summary.landing {
        println!(
            "landed at {:.5}° N, {:.5}° W, {:.0} m from the pad, at {:.1} s",
            landing.latitude_deg, -landing.longitude_deg, landing.distance_m, landing.time_s
        );
    }
    Ok(())
}

The builder

This page shows the shortest way to fly a rocket of your own with hpr-sim. The hpr crate has four types for it: Environment, Motor, Rocket and Flight. You describe the rocket part by part from the nose back, put a motor in it, and fly it from a rail. The page runs four example programs and walks through them. It needs the setup from Getting started, and some Rust.

How far to trust it. The builder adds no physics. It writes the same design tree that Your own rocket writes by hand, and flies it with the same simulation. A test builds that page’s rocket with the builder and flies it: the mass properties and the whole flight come out the same, bit for bit (the_builder_makes_the_rocket_own_rocket_builds_by_hand). So what that page says about trusting its numbers holds here. The masses come from each part’s shape and a published density, so glue, paint and hardware are missing until you weigh the parts. This rocket has never been flown for real, so no flight checks it. Where it lands in a wind is the least certain number of all: on two of RocketPy’s example rockets, hpr’s drift and RocketPy’s differ by 11 to 43% (Getting started explains why).

Run it

cargo run --example build_and_fly -p hpr

This builds the small rocket of Your own rocket. Its airframe is 54 mm inside and 56.3 mm outside, and it takes 29 mm motors. It weighs the rocket, and finds its center of gravity (CG), its center of pressure (CP) and its stability margin. Then it flies the rocket on a Cesaroni H54 from a rail leaning into a light wind, with a parachute that opens at the motor’s ejection delay. It prints this:

My 54 mm rocket on a 168H54-10A
Not yet validated: see the Accuracy page before trusting these numbers.

                                 liftoff     spent
mass (kg)                          0.675     0.579
center of gravity (m from nose)    0.671     0.610
center of pressure (m from nose)   0.779     0.779
stability margin (calibres)         1.92      2.99

From a 1.8 m rail leaning 5° west, in 5 m/s of wind from the west:
Rail exit:  21.7 m/s
Apogee:     1106.6 m above the pad, at 13.69 s, 282 m west of it
Top speed:  186 m/s (Mach 0.56)
Landing:    877 m east of the pad, at 4.6 m/s, at 246.3 s

What the lines say:

• Liftoff and spent. The rocket loses 96 g of propellant as the motor burns. That moves the CG 6 cm forward, and the margin grows from 1.92 to 2.99 calibres.
• The CP is worked out by Barrowman’s method at Mach 0.3, a typical subsonic speed, with the air straight along the rocket. It depends on the shape alone, so it doesn’t move as the motor burns.
• The flight. The rail exit speed is how fast the rocket leaves the rail. The rail leans 5° west, into the wind, and the rocket turns further into the wind as it climbs, a rocket’s usual weathercocking. The lean and the turn together put its apogee 282 m west of the pad. Under the parachute the wind carries it back, to land 877 m east of the pad.
• Heights are the height of the rocket’s CG above the launch site. The CG starts above the ground, sitting on the rail, so the apogee includes that starting height.

The program

The program is crates/hpr/examples/build_and_fly.rs. It takes four steps: the motor, the rocket, the weighing and the flight.

The motor

Motor::from_catalog("H54") takes a motor from the catalog built into hpr-sim. It finds the motor by its designation, such as 168H54-10A, or by its common name, the short form such as H54, and ignores case, spaces and hyphens. Only the 32 motors that come with a thrust curve can be found; the motor page lists them. A name that matches two motors, as I175 does, is refused with both listed rather than guessed. The delay is never read from the designation: with_delay_s(10.0) sets it, and a parachute opened by the motor’s charge needs it. Motor::from_eng reads the text of a RASP .eng file, such as one downloaded from ThrustCurve.org, instead.

The rocket

Rocket::new(name, diameter_m) starts an empty rocket with an outer body diameter. Then each add_ call adds one part and returns the rocket, so the calls chain. Body parts stack from the nose tip in the order you add them. The parts that go inside or on the airframe attach to the last body tube you added:

A position (Position) is measured along the tube the part is on: Top places the part’s fore end a distance aft of the tube’s, Bottom its aft end from the tube’s aft end, Middle its middle from the tube’s middle, After its fore end behind the part before it, and Absolute its fore end from the nose tip. So a Mass given a size with packed has its center half that length from the end its position names, or at the point itself when placed by its Middle. In the example, packing the recovery bay 15 cm long, its top 7 cm down the tube, moves the rocket’s CG at liftoff 22 mm aft of where a point mass at the top puts it.

Every part names its material, and every hollow part its wall. material("abs") finds one of the built-in materials, each with the source of its density; the mass page explains how the masses are found. The builder has no default material or wall, because each would be a guess at your rocket’s mass. The defaults it does have change the drag, not the mass: fins have square edges, and every outer surface has the design’s default finish, mass-production paint, which sets the friction of the air on it (Drag). The builder can’t change the finish yet.

set_motor puts the motor in the motor tube, lit at launch. add_parachute adds a recovery device: here a 90 cm flat parachute opened by the ejection charge of motor number 0, the first, Trigger::MotorDelay { motor: 0 }. A device adds drag, not mass; the parachute’s mass is in the 200 g recovery bay. The recovery page explains the devices and what opens them.

Weighing it

mass_properties(t) gives the mass, CG and inertia t seconds after the motor lights. margin(t, mach) gives the CP and the margin, and static_margin_cal(t, mach) the margin alone. The CG is in the body frame, whose z axis points to the nose, so a point 0.671 m behind the nose tip is at z = −0.671. The CP is a station, meters aft of the tip, so the example prints it as it comes and the CG with its sign turned. Weighing runs the same checks on the design as a flight does, so a motor wider than its tube is refused by both.

Flying it

Environment::new(latitude, longitude, elevation) is the launch site, in degrees north, degrees east (so the Americas are negative) and meters. It has the standard atmosphere and no wind; with_constant_wind(5.0, 270.0) adds 5 m/s blowing from 270°, the west. The elevation is taken both as the height above sea level, where the air is read, and as the height above the ellipsoid.

Flight::builder(&rocket, &environment, 1.8) sets up a flight from a vertical 1.8 m rail. inclination_deg is the rail’s angle above the horizon: 90 is vertical, and 85 leans 5° off it. OpenRocket measures its launch rod angle from the vertical instead, so its 5° is 85 here. heading_deg is the way the rail leans, clockwise from true north (add the declination to a compass reading). A wind’s direction is where it comes from, so a rail leaning into a west wind has both at 270. fly() flies the rocket to the ground. The flight’s apogee_m, max_speed_m_s, rail_exit_speed_m_s and landing are the numbers most asked for; summary() has every metric the metrics page describes.

Which motor

The second example flies the same rocket on each 29 mm motor that comes with hpr-sim, from a vertical rail, with the parachute opening at apogee whatever the delay:

cargo run --example motor_choice -p hpr

My 54 mm rocket from a 1.8 m vertical rail, in 5 m/s of wind from the west
Not yet validated: see the Accuracy page before trusting these numbers.

motor        liftoff  margin  rail exit   apogee  top speed  best delay
               (kg)   (cal)     (m/s)      (m)     (m/s)        (s)
F15            0.569    3.00       10.0    206.9         55         4.6
F52C           0.548    3.32       18.5    438.6        106         8.0
168H54-10A     0.675    1.92       21.7   1134.6        186        10.5

set_motor swaps the motor in the tube, so one rocket flies on all three. The H54 reaches 1134.6 m here, from a vertical rail in the wind. The same rocket reaches 1144.5 m on Your own rocket, from a vertical rail in calm air, and 1106.6 m at the top of this page, from a leaning rail. The parachutes open at different times too: here at apogee, there at the motor’s charge.

The best delay is the time from burnout, the end of the thrust curve, to apogee, so the charge fires at the top. It is 10.5 s on the H54, near the 10 s delay that motor’s designation names. The H54 burns out at 3.5 s, so on the leaning rail at the top of this page its 10 s delay fires at 13.5 s, 0.2 s before its apogee. The F52 wants 8 s. The F15 leaves the rail at only 10 m/s, the slowest of the three, and a slow rocket’s fins have the least air to steer with.

Sizing fins

The third example builds the same rocket with fins of five spans, the fin’s height from the body tube to its tip, and flies each from a vertical rail, in calm air and in 5 m/s of wind from the west. The parachute opens at apogee here, not at the motor’s charge, so the charge doesn’t cut the climb short:

cargo run --example fin_sizing -p hpr

My 54 mm rocket on an H54, fins of five spans, in calm air and a 5 m/s west wind
Not yet validated: see the Accuracy page before trusting these numbers.

fin span  liftoff  margin   apogee (m)       in the wind: drift (m)
    (mm)     (kg)   (cal)   calm   wind   apogee upwind  landing downwind
      25    0.666   -2.11   too little margin to fly
      35    0.671    0.33   too little margin to fly
      45    0.675    1.92   1145   1135             119              1068
      55    0.680    2.97   1126   1110             156              1001
      65    0.684    3.67   1107   1088             176               954

Because a rocket is a value built by a function, a design study is a loop. The example’s rocket(span_m) builds the rocket with fins of that span, and the loop weighs and flies each.

• The margin, at liftoff and at Mach 0.3, grows fast with the span: from −2.11 calibres, a CP ahead of the CG, to 3.67. The usual rule of thumb asks for at least one calibre (stability margin), so the program doesn’t fly the two smallest; the example’s own fins are the 45 mm ones.
• Bigger fins cost height. In calm air the 65 mm fins reach 38 m less than the 45 mm ones: that is their drag and their extra mass, about 9 g. In the wind they lose 47 m, since they also turn the rocket further into it, as the apogee drift shows: 119 m upwind with the 45 mm fins, 176 m with the 65 mm.
• The landing is closer with bigger fins, 114 m closer from the 45 mm to the 65 mm: the parachute opens further upwind, and lower, so it drifts for less time.

Parts from a catalog

A rocket can also be built from a maker’s parts, as sold, from a parts catalog. hpr-sim bundles the one OpenRocket ships: 3,449 parts from Estes, LOC Precision and a dozen more makers, read as the .orc page explains. The fourth example finds LOC Precision’s 2.56 in (65 mm) airframe parts in it by maker and part number, builds the rocket from them, and flies it on an AeroTech H170:

cargo run --example catalog_rocket -p hpr

LOC 2.56 in from the catalog, with motor H170M
Not yet validated: see the Accuracy page before trusting these numbers.

part                                     mass (g)
LOC Precision PNC-2.56                       87.7
LOC Precision BT-2.56                       120.0
LOC Precision BT-1.52, MMT-1.52              43.6
LOC Precision CR-2.56-38mm                    4.2
LOC Precision CR-2.56-38mm                    4.2
fins                                         99.7
LOC Precision LP-36-2022                     70.7
structure                                   430.1

At liftoff: 0.760 kg, center of gravity 0.728 m from the nose,
stability margin 1.07 calibres at Mach 0.3.

Rail exit:  30.0 m/s
Apogee:     1119.3 m above the pad, at 11.77 s
Top speed:  302 m/s (Mach 0.91)
Landing:    at 4.6 m/s, at 250.8 s

Each part is named by its maker and its part number, as the design keeps it. LOC’s numbers say what the part is and its size in inches: PNC-2.56 is a plastic nose cone for the 2.56 in tube, BT-2.56 the body tube, MMT-1.52 the 1.52 in (38 mm) motor tube, CR-2.56-38mm a centering ring between the two, and LP-36-2022 a 36 in parachute. Structure is all the parts together, without the motor.

How far to trust these numbers. Nearly every part weighs what OpenRocket 24.12 weighs when it builds the same catalog part: within 0.1%, with its center of mass within 0.1% of its length. The few exceptions are counted in “How far to trust it” below. One is deliberate, and this nose has it: its shoulder, the short tube that slides into the body, has the nose’s own plastic wall here and weighs nothing in OpenRocket. OpenRocket weighs the nose at 61.5 g; here it weighs 87.7 g, 26.1 g of it the shoulder. That is 6% of the structure. Nothing checks the flight itself; the note at the top of this page applies. The top speed, Mach 0.91, is close to the speed of sound, where drag rises steeply and is least certain (Drag through Mach 1). The stability margin, 1.07 calibres, is taken at Mach 0.3, about 100 m/s, more than three times the speed the rocket leaves the rail at.

The program is catalog_rocket.rs. Its steps:

• Find the part. hpr::hpr_io::orc::bundled().find("LOC Precision", "PNC-2.56") returns the parts with that maker and number. Use the maker’s name as the file writes it (“LOC Precision”, where OpenRocket shows “LOC/Precision”).
• Make the builder’s part from it. Nose::from_catalog(part), Tube::from_catalog, Transition::from_catalog and MotorTube::from_catalog (a body tube used as the motor tube) take the catalog’s sizes, material and density. A catalog nose or transition states its own diameters, so the tube behind it takes the nose’s diameter, not the one given to Rocket::new.
• Cut a tube. Catalog tubes are sold long (LOC’s motor tube is 34 in). with_length_m cuts one to length, and its mass follows.
• Fittings. A fitting is a part that goes in or on the last body tube: a coupler, an engine block, a centering ring, a bulkhead, a launch lug, or a packed parachute or streamer. Fitting::from_catalog(part) makes one from a catalog part, and Rocket::add_fitting adds it, flush with the tube’s aft end unless at places it. Fitting::centering_ring, bulkhead, coupler and launch_lug make one to your own sizes.
• A parachute is two things. As a fitting it is its weight: canopy and shroud lines, at its place in the tube. Its drag is a recovery device, as in the first example. The example gives that device the catalog’s diameter.
• The fins are made by hand: the catalog has none.

229 of the 3,449 parts state their mass in the catalog, and each weighs that mass. The builder sets the part’s density so that the part, as the catalog sizes it, weighs the stated mass, and the material’s name gains “, density set by the part’s stated mass”. A part changed afterwards, such as a tube cut shorter, keeps that density, so its mass follows the change. OpenRocket gives a rigid part its stated mass the same way. It gives a parachute its stated mass as an override, which comes to the same for a parachute left as it is. It ignores a streamer’s.

What the catalog leaves unsaid

A catalog leaves some sizes out. The builder fills each one in the way OpenRocket 24.12 does when it builds the part, with one exception, a hollow part’s shoulder. The shapes are explained in Shapes:

A clipped transition is cut from a whole nose cone, rather than stretched from one (Shapes). A molded plastic nose cone’s shoulder is a tube of the same plastic, so a shoulder that weighs nothing would be wrong. The catalog’s stated masses agree: on the 74 hollow parts with a shoulder that state their mass, the file’s density weighs nearer the stated mass with the shoulder’s wall than without it on 46. The median stated mass is 0.97 of the mass with the wall, and 1.30 of the mass without it.

How far to trust it

tests/catalog_openrocket.rs builds every part in the catalog with the builder. It holds each part’s mass and center of mass to what OpenRocket builds from it, run as an oracle and recorded by orc_built.py. The tolerances were set before measuring. Every part is in one row:

Where the masses differ, the test checks each cause:

• OpenRocket’s volumes are close, not exact. Even a cone, whose volume has a formula, differs a little. The test holds hpr’s 85 filled cones to that formula, so the difference is OpenRocket’s.
• Hollow shoulders. A hollow part’s shoulders are taken out of hpr’s mass and center, each worked out on its own as a tube of the part’s wall. That leaves the body, which is what OpenRocket weighs.
• Two walls. hpr’s wall is every point within its thickness of the outer surface. OpenRocket’s masses follow a wall measured across each station instead, whose inner radius is r − t √(1 + r′²) (r the radius, t the thickness, r′ the slope). The test works out both on its own. All 185 hollow parts’ OpenRocket centers agree with the station-wise wall to 1.1e-4 of the length, and their masses to 2.5e-4, on the 111 that state no mass (a stated mass is OpenRocket’s whatever the wall). hpr’s 113 hollow conical, tangent-ogive and elliptical nose cones agree with integrals of its own wall, in volume and center, to 1e-9. The other 72 hollow parts (Haack and parabolic noses, and transitions) have no such integral: they are checked only against OpenRocket, within the tolerance. The two walls differ most on short, blunt nose cones. Four elliptical ones fall outside the tolerance: three up to 0.48% heavier here, their centers up to 1.7e-3 of their length apart, and one, which states its mass, by its center alone, 1.0e-3 of its length.
• Masses stated in ounces, on 185 parts of every kind (a different 185 from the hollow parts above), differ by OpenRocket’s rounded ounce, 8.8e-10 of the mass.
• The 4 refused parts. One nose cone names a material its file doesn’t define. Three tubes or rings have a bore no narrower than their outside.

The test compares mass and center of mass, not the moments of inertia. What it checks is each part as the catalog describes it. A catalog’s sizes and densities are the makers’ or the database’s, and none was weighed here. Glue, paint and hardware are still missing: weigh the finished parts when you can.

Beyond the builder

The builder covers a single-stage rocket with one motor. Two ways lead further, both into the crates the builder is made of.

• Change the design. A rocket’s design() is its design tree, which a design file holds. Clone it, add what the builder can’t with the hpr_design crate (a cluster, pods, rail buttons, a stage), and make a rocket of it with Rocket::from_design(tree, configuration), which names the configuration, the motors, to fly. from_design also takes a design file, or an OpenRocket file read as the .ork page shows. A second stage also needs a separation, which the flight builder’s separation takes, and a recovery device on each part it makes. For a .ork, hpr::ork::separated_recovery puts the file’s own devices on their parts, as hpr sim does (Separation); the ork_two_stage example flies one, building its simulation with Simulation::new rather than through the builder.
• Change the flight. A flight builder’s simulation() hands over the simulation fly() would run. The motor_choice example passes it to hpr_sim::metrics::optimum_delays. The simulation’s methods add a separation, events of your own, or moving or released masses. A drag model of your own, or another program’s drag table, needs no detour: the flight builder’s drag_model and drag_table take them (Models of your own). run(&mut ()) flies it, with no observer watching. A flight flown that way returns the simulation’s own result, without the builder’s Flight methods; hpr_sim::FlightMetrics gives the same metrics (Flight metrics).

What it refuses

Each part’s numbers are checked when the part is added: a negative length, a NaN, a zero diameter, zero fins, a shape parameter out of range. The error names the number, such as tube diameter, m is 0, outside its domain. So is a part in an order the tree can’t take: fins before any tube, a second motor tube, a nose behind a tube. The launch site and wind are checked when they are given, the rail when the flight is set up, and a design that comes in whole through from_design before it flies. Tests try each of these and pin which check refuses it (parts_out_of_order_are_refused, degenerate_designs_error_or_stay_finite). One rocket in them has no fins at all: it flies, tumbling, to finite numbers. That test is Loft lesson L95’s: a Loft lesson is a mistake of the project before this one, with the test that guards against it here.

A catalog part is refused when the builder can’t make it as the catalog describes it: a part of another kind than the from_catalog it is given (a body tube given to Nose::from_catalog), a material its file names but doesn’t define, a shape the builder doesn’t have, a nose cone or transition the file neither fills nor gives a wall thickness, a tube or ring whose bore is no narrower than its outside, or a part stating a mass with no volume to give it. The error names the part by maker, number and file. Rocket::add_fitting also refuses a fitting before any body tube, and a part that isn’t a fitting.

What it can’t do yet

• One motor, one stage. Clusters, staging and pods go through the design, as above; the staging page explains how they fly.
• Rail buttons go through the design. Without them the rocket leaves the rail when its aft end passes the rail’s top. A launch lug is a fitting (above), with its drag; without one, a lug’s drag is missing. With one, the rocket leaves the rail when the lug’s aft edge passes the rail’s top.
• The finish. Every surface is painted, as above.

Where next

• Models of your own flies a drag model and a wind of your own in hpr-sim’s place.
• The API reference’s guide module is this page’s walk-through in five short chapters, each with code that CI runs.
• The API reference documents every method, starting at the hpr crate.
• Your own rocket builds the same rocket without the builder, and shows every field a part has.
• Recording a trajectory keeps the flight’s path: pass a recorder to fly_with instead of calling fly.

Python

This page shows how to fly a rocket from Python with the hpr package. The package has the same four types as the Rust builder: an Environment, a Motor, a Rocket and a Flight. You describe the rocket part by part from the nose back, or read it from a design file, then fly it from a rail, once or, as a MonteCarlo run, many times with its inputs scattered. A flight’s metrics come back as numbers and dictionaries, and its recording and a run’s flights as NumPy arrays. You need Python 3.10 or later and some familiarity with it. Today you also build the package yourself, which needs the Rust toolchain (Install it).

How far to trust it. The package adds no physics. Each call hands its numbers to the Rust builder and returns what that returns, so a flight made in Python runs the same code as one the Rust builder makes from the same numbers. A test builds The builder’s example rocket in Python and matches every digit that Rust example prints (test_prints_what_the_rust_example_prints). Digits beyond those printed can differ between a release and a debug build. Because the code is the same, what that page and Accuracy say about the numbers holds here too. The rocket below has never been flown for real, so no flight checks it. Where it lands in a wind is the least certain number of all: on two of RocketPy’s example rockets, hpr’s drift and RocketPy’s differ by 10 to 38% (Getting started explains why). The package is new and covers less than the Rust library (What is not here yet). The gap that matters most if you bring a design file: most .ork configurations are refused (A design from a file). The package is built and tested on Linux, macOS and Windows, but not published on PyPI, Python’s package index.

Install it

Release 0.1.0 is built and checked, but not on PyPI yet. Once it is, pip install hpr-sim installs it, with NumPy. One wheel serves CPython 3.10 and later on Linux on x86-64, Macs with Apple silicon, and Windows on x86-64; elsewhere, and on Linux older than glibc 2.35, pip builds the source package, which needs Rust (Install a release).

Until then, you build it from this repository. You need the Rust toolchain from Getting started and maturin, the tool that builds Python packages from Rust. From the repository’s root, make a virtual environment and build into it:

python3 -m venv .venv
source .venv/bin/activate          # on Windows: .venv\Scripts\activate
pip install maturin
maturin develop --release --manifest-path crates/hpr-py/Cargo.toml

maturin develop builds the package and installs it into the environment, with NumPy. It links the environment to the build, so after a change to the Rust code, run it again.

To install elsewhere, build a wheel instead, the file pip install takes: maturin build --release --manifest-path crates/hpr-py/Cargo.toml writes it to target/wheels/. One wheel serves every CPython (the standard Python) from 3.10 on (tested on 3.10 and 3.13), on the operating system and processor that built it. scripts/python-tests.sh builds one and runs the package’s tests on it, which needs uv.

The package imports as hpr. Its distribution name, the one pip lists, is hpr-sim.

A first flight

This builds a simpler version of the rocket in Your own rocket and The builder: a 54 mm airframe with an ogive nose, three fins and a Cesaroni H54, whose recovery bay here is a point mass and whose nose has no shoulder. It flies from a 1.8 m rail leaning 5° into a 5 m/s west wind, with a parachute opened by the motor’s ejection charge at the end of its ejection delay.

import hpr

environment = hpr.Environment(32.99, -106.97, 1400.0, wind_speed_m_s=5.0, wind_from_deg=270.0)

rocket = hpr.Rocket("My 54 mm rocket", 0.0563)
rocket.add_nose("ogive", 0.22, "abs", wall_m=0.0015)
rocket.add_tube(0.9, 0.00115, "kraft_phenolic")
rocket.add_motor_tube(0.2, 0.029, 0.001, "kraft_phenolic", overhang_m=0.005)
rocket.add_fins(
    3,
    root_chord_m=0.1,
    tip_chord_m=0.04,
    span_m=0.045,
    sweep_m=0.05,
    thickness_m=0.003175,
    material="birch_plywood",
    cross_section="rounded",
)
rocket.add_mass(0.2, position="top", offset_m=0.07, name="recovery bay")
rocket.set_motor(hpr.Motor.from_catalog("H54", delay_s=10.0))
rocket.add_parachute("parachute", diameter_m=0.9, trigger="motor_delay")

print(f"Stability at liftoff: {rocket.static_margin_cal(0.0, 0.3):.2f} calibres")

flight = hpr.Flight(rocket, environment, 1.8, inclination_deg=85.0, heading_deg=270.0)
print(f"Apogee:    {flight.apogee_m:.1f} m at {flight.apogee_time_s:.2f} s")
print(f"Top speed: {flight.max_speed_m_s:.0f} m/s (Mach {flight.max_mach:.2f})")
landing = flight.landing
print(f"Landing:   {landing['distance_m']:.0f} m from the pad, descending at {landing['descent_rate_m_s']:.1f} m/s")

It prints:

Stability at liftoff: 2.12 calibres
Apogee:    1118.3 m at 13.67 s
Top speed: 190 m/s (Mach 0.57)
Landing:   905 m from the pad, descending at 4.6 m/s

Line by line:

• Environment takes the launch site’s latitude and longitude in degrees (longitude positive east, so negative in the Americas) and its elevation in meters. The air is the US Standard Atmosphere 1976. The wind is the same at every height, and blows from wind_from_deg, clockwise from north.
• Rocket takes a name and the airframe’s outside diameter, m.
• The nose is a tangent ogive 0.22 m long, of ABS, hollow with a 1.5 mm wall. The tube is 0.9 m long with a 1.15 mm wall. The motor tube is 0.2 m long, with a 29 mm bore and a 1 mm wall.
• Parts go on from the nose back: the nose, then tubes. Fins, a motor tube and masses go on or in the tube before them.
• Each part names its material by an id from the built-in list, hpr.materials(), and takes its mass from its shape and that material’s density.
• The fins’ lengths are named, so two can’t swap unseen: the root chord, tip chord and span, and the sweep, how far aft of the root’s leading edge the tip’s is.
• Motor.from_catalog finds one of the 32 bundled motors by its name. It doesn’t take the delay from the designation (the H54’s full one is 168H54-10A), so give it as delay_s: a parachute opened by the motor needs one. Motor.from_file reads a RASP .eng or RockSim .rse file.
• static_margin_cal(0.0, 0.3) is the stability margin at ignition (0 s) and Mach 0.3.
• Flight flies the rocket as soon as it is made. The rail is 1.8 m long and leans inclination_deg above the horizon, 90 by default, toward heading_deg, clockwise from north.
• The landing’s descent_rate_m_s is how fast it comes down. Its ground_hit_speed_m_s is faster, as it adds the wind’s drift.

The stability margin is the distance from the center of gravity back to the center of pressure, in body diameters (calibres). It is 2.12 here, where The builder’s example says 1.92. That example packs its 200 g recovery bay into a 15 cm cylinder, which moves the bay’s center, and so the rocket’s center of gravity, aft: about 0.4 calibres less. It also gives the nose a capped shoulder, which adds mass at the front: about 0.2 calibres more. A test holds both steps to these sizes (test_the_margin_moves_as_the_python_page_says).

The recording

A flight is recorded at every step of the integrator, or every interval_s seconds (at least 0.001 s) if you give Flight one, with a row at every event too. flight.columns names the columns, each with its unit, and flight["name"] gives one as a NumPy array. flight.series gives them all, as a dictionary of arrays. Continuing from above:

height_m = flight["height_above_ground_m"]
time_s = flight["time_s"]
print(len(flight.columns), "columns:", ", ".join(flight.columns[:3]), "...")
print(f"Highest recorded height: {height_m.max():.1f} m at {time_s[height_m.argmax()]:.2f} s")
for event in flight.events[:4]:
    print(f"{event['kind']:>10} at {event['time_s']:6.3f} s")

30 columns: time_s, position_east_m, position_north_m ...
Highest recorded height: 1118.3 m at 13.67 s
   liftoff at  0.001 s
 rail_exit at  0.174 s
   burnout at  3.500 s
   trigger at 13.500 s

The columns are the ones Recording a trajectory lists: time, position and velocity east, north and up of the pad, attitude, height, airspeed, Mach number, angle of attack, thrust, mass and more. Heights are the center of gravity’s, above the pad; it stands on the rail at the start, so the first height isn’t zero. The arrays are read-only copies, so a slip can’t change the flight’s record. To plot one, hand the arrays to any plotting library, for example matplotlib.pyplot.plot(time_s, height_m).

flight.events lists what happened, in the order it happened. Each event is a dictionary with its kind, the index of the parachute or motor it is about, its time_s, and the flight’s state then, sample. The kinds are "liftoff", "rail_exit", "burnout", "apogee", "trigger" (a parachute’s charge fires), "deployment" (it is open) and "ground_hit". Here the parachute’s charge fires at 13.5 s, the H54’s 3.5 s burn plus its 10 s delay, 0.17 s before apogee.

flight.landing is a dictionary of the landing: its time_s, latitude_deg, longitude_deg, east_m and north_m of the pad, distance_m, ground_hit_speed_m_s, descent_rate_m_s, and body, which separated body landed (None for a rocket that didn’t come apart). flight.summary has every metric of the flight as a dictionary: the apogee, top speed, Mach number and dynamic pressure, the stability margins and the landings, each explained in Flight metrics. flight.envelope_flags lists where the flight went past what hpr’s numbers have been checked for (the operating envelope), and "unstable_under_power" for a static margin below zero while a motor burns, or "unstable_without_margin" for a pitching moment that turns the rocket away while a motor burns where hpr can give no margin (Flight metrics: unstable under power): each a dictionary with its flag, such as "beyond_validated_range", the value that raised it (a Mach number, an angle of attack in radians, a margin in calibres, or a pitch-moment slope per radian), its time_s and height_above_ground_m, and a message. It is empty for a flight that raises none. flight.issue_warnings lists the known errors in hpr’s drag or stability the flight meets (the list): each a dictionary with its issue number, such as 67, its kind ("drag" or "stability"), its url, the flight’s max_mach and its time_s, the parts whose shape meets it, and a message saying which way its numbers lean. flight.to_json() is the whole record as JSON text.

A design from a file

Rocket.from_file reads a design instead of building one: an hpr design (.hpr or .hprz, The hpr design format), an OpenRocket .ork file (.ork design files), or a rocket’s JSON. It flies the motor configuration you name, or the file’s default one, or its only one, as hpr sim does.

Most .ork files won’t fly yet. A configuration flies only if every motor lights at launch and has a thrust curve, in the file or among hpr’s 32 bundled motors: that is 4 of the 170 configurations in the reference library. Otherwise from_file raises HprError and says why, and Python can’t yet swap in a motor as hpr sim --motor does.

A design read from a file flies without the parachutes it stores unless you ask for them with recovery=True: Rocket.from_file("validation/fixtures/ork/guides/level-1.ork", recovery=True) flies the file’s devices as hpr sim does, each opening fully at its event with the file’s drag coefficient or OpenRocket’s own (When parachutes open and stages separate). Without it, add parachutes with add_parachute; until you do, the rocket falls to the ground unslowed, and its landing numbers mean nothing. Parachutes added after recovery=True come after the file’s, so the file’s first is parachute 0 for released_by. Stage separations are never flown. rocket.notes lists what reading the file said: the .ork reader’s warnings, a design written by an older version of the format, what the file holds that isn’t flown, and a file’s parachute that never opens in the configuration flown. A file’s recovery hpr can’t fly, such as a device opened by an event hpr doesn’t read, raises HprError with why.

This one is RocketPy’s example rocket, Calisto, from the file the validation suite uses, with its two parachutes as RocketPy’s example gives them. The path is the repository’s, so run it from the repository’s root:

calisto = hpr.Rocket.from_file("validation/designs/rocketpy-calisto-tests-motor-at-minus-1.373.json")
calisto.add_parachute("drogue", cd_s_m2=1.0, lag_s=1.5)
calisto.add_parachute("main", cd_s_m2=10.0, trigger="altitude", altitude_m=800.0, lag_s=1.5)
site = hpr.Environment(32.990254, -106.974998, 1400.0)
flight = hpr.Flight(calisto, site, 5.2, inclination_deg=85.0)
print(f"{calisto.configuration}: apogee {flight.apogee_m:.0f} m, landing at {flight.landing['descent_rate_m_s']:.1f} m/s")

example: apogee 2807 m, landing at 5.2 m/s

This flight uses hpr’s own drag, in calm air. The validation suite flies the same design with hpr’s own drag too, in a wind and in RocketPy’s atmosphere, and its apogee is 0.609% below RocketPy’s. That is the closest of the suite’s six rockets: on the others, hpr’s own drag puts the apogee from 7.280% below RocketPy’s to 10.302% above (Whole flights with each code’s own drag, same-drag and predicted mode). The next section flies Calisto from Python as that suite does, and compares it with RocketPy.

RocketPy’s example, flown as the suite flies it

This section flies Calisto again, this time the way the validation suite flies it against RocketPy. It is for checking hpr against RocketPy, or for moving a RocketPy script across. Both codes fly the same drag and the same inputs, so the comparison tests the rest of the physics: the equations of motion, the atmosphere, the rail and the parachutes. It is a comparison between two codes, not with a real flight.

Three options make it RocketPy’s flight:

• A drag table. DragTable holds a zero-lift drag coefficient C_D0 against Mach number, as RocketPy’s power_off_drag and power_on_drag do. Its power-on curve is flown while the motor burns, its power-off curve the rest of the time. Pass it to a flight as drag_table=; it replaces hpr’s own drag, and nothing else. DragTable.from_csv reads RocketPy’s two-column drag files.
• RocketPy’s gravity. Environment(..., gravity="vertical_taylor") uses RocketPy’s formula for gravity instead of hpr’s default. Near the ground the two differ in size by about one part in 10⁸, but hpr’s default also turns with the rocket’s position over the ground. On this flight the switch moves the apogee by 2 parts in 10⁷ and the landing point by 0.3 m (Gravity).
• One parachute at a time. RocketPy flies only the last parachute to open, and hpr adds together every one that is open. released_by is another parachute’s number, counted from 0 in the order they were added: add_parachute(..., released_by=1) cuts this one away once the second parachute is fully open (Recovery).

Here is an invented table with less drag while the motor burns. Calisto flies it in calm air, as in the section above, to 2650 m above the pad:

table = hpr.DragTable([(0.0, 0.5), (3.0, 0.5)], [(0.0, 0.45), (3.0, 0.45)])
print(f"C_D0 at Mach 0.6: {table.cd0(0.6):.2f} coasting, {table.cd0(0.6, thrusting=True):.2f} burning")
flight = hpr.Flight(calisto, site, 5.2, inclination_deg=85.0, drag_table=table)
print(f"apogee {flight.apogee_m:.0f} m")

C_D0 at Mach 0.6: 0.50 coasting, 0.45 burning
apogee 2650 m

The example crates/hpr-py/examples/calisto.py puts it all together. It is written as notebook cells (# %%), which editors such as VS Code run one at a time. It reads the rocket, the wind, the drag and the parachutes from the repository’s files, then flies them. Then it measures each metric as RocketPy defines it, and not always as hpr’s own summary does:

• RocketPy follows the rocket’s dry center of mass, its center of mass without propellant, and starts that point at ground level. hpr stands the rocket on its rail, so the same point starts 1.250 m up (the first line printed below). The example subtracts 1.250 m from every height, and opens the main 1.250 m above RocketPy’s 800 m.
• RocketPy’s rail exit is when its forward rail button leaves the rail, after 3.745 m of travel (RocketPy’s effective_1rl). hpr’s is when its aft-most rail guide clears the top of the 5.2 m rail, after 4.45 m of travel, so the example reads RocketPy’s off the recording.
• RocketPy’s flight ends when the dry center of mass is back at its starting height.

Run from the repository’s root, python crates/hpr-py/examples/calisto.py prints:

The dry center of mass starts 1.250 m above the ground.
metric                                  hpr   RocketPy  difference
apogee_agl_m                        2613.59    2612.22      +0.05%
apogee_time_s                         22.88      22.85      +0.10%
max_speed_m_s                        243.56     243.52      +0.01%
max_mach                             0.7321     0.7329      -0.12%
max_acceleration_m_s2                112.35     112.24      +0.10%
max_acceleration_power_on_m_s2       112.35     112.24      +0.10%
rail_exit_speed_m_s                   28.20      28.20      -0.01%
rail_exit_time_s                     0.2945     0.2947      -0.07%
burnout_altitude_agl_m               684.23     684.10      +0.02%
burnout_speed_m_s                    235.65     235.60      +0.02%
flight_time_s                        260.86     260.53      +0.12%
apogee_drift_m                       422.52     426.36      -0.90%
landing_drift_m                     1277.36    1261.50      +1.26%
impact_speed_m_s                     5.4549     5.4560      -0.02%
largest difference 1.26%, within 3%: True

Every metric is within 3% of RocketPy’s, the bound the validation suite holds this flight to (M2.1). These are the suite’s numbers: a test holds each to within 0.001% of what the suite’s report records for the same flight (test_calisto.py). Because both codes fly the same drag, this says nothing about hpr’s own drag, the largest source of difference: flying its own, hpr puts the suite’s six rockets’ apogees 7.280% below RocketPy’s to 10.302% above, as the section before says. The drifts differ most here. On two of RocketPy’s other example rockets, Juno III and Bella Lui, flown in a wind, the drifts differ by 10 to 38% (Getting started explains why).

Drag and wind of your own

A flight can fly a drag and a wind you write as Python functions, in place of hpr’s own drag and the environment’s wind: a drag curve from a wind tunnel or another program, say, or a wind profile from a weather balloon. hpr calls them as it flies, several times for each time step of its integrator, and keeps everything else its own: the rest of the aerodynamics, the thrust, the masses and the atmosphere. They are the Python side of the Rust library’s models of your own. How far to trust it: as far as your functions. hpr checks that each number is finite, and that a drag is not negative, but not that it is right.

Three things about the drag number, as for a Rust drag model:

• It is not rescaled. A DragTable can carry the diameter it was measured on; a function’s number must already be on the rocket’s reference area.
• At an angle of attack hpr scales it, as it scales its own.
• Under a parachute the drag is the parachute’s, not the function’s.

The wind’s two numbers are the way the air moves, so a wind from the west is (+speed, 0): the opposite of wind_from_deg, which names where the wind comes from.

Here the drag rises through Mach 0.8 to 1.1 and drops 10% under power, and the wind strengthens with height:

def drag(mach, thrusting):
    """0.5 below Mach 0.8, rising to 0.8 by Mach 1.1; 10% less while the motor burns."""
    rise = min(max((mach - 0.8) / 0.3, 0.0), 1.0)
    cd0 = 0.5 + 0.3 * rise
    return 0.9 * cd0 if thrusting else cd0


def wind(height_m):
    """From the west, 3 m/s at the 1400 m site, 1 m/s stronger every 100 m above it."""
    above_m = max(height_m - 1400.0, 0.0)
    return (3.0 + above_m / 100.0, 0.0)


windy = hpr.Environment(32.99, -106.97, 1400.0, wind=wind)
flight = hpr.Flight(rocket, windy, 1.8, drag=drag)
print(f"apogee {flight.apogee_m:.0f} m, landed {flight.landing['east_m']:.0f} m east")

table = hpr.DragTable([(0.0, 0.5), (3.0, 0.5)])
same = hpr.Flight(rocket, windy, 1.8, drag=lambda mach, thrusting: 0.5)
print(same.apogee_m == hpr.Flight(rocket, windy, 1.8, drag_table=table).apogee_m)


def refuses(mach, thrusting):
    if mach > 0.3:
        raise LookupError("no drag measured past Mach 0.3")
    return 0.5


try:
    hpr.Flight(rocket, windy, 1.8, drag=refuses)
except LookupError as error:
    print(type(error).__name__, error)

apogee 1109 m, landed 1963 m east
True
LookupError no drag measured past Mach 0.3

A function that always returns the same number flies as a drag table of that number does. At 0.5 the two agree to the last digit; at some numbers, 0.3 or 0.45 say, they differ in the eleventh, because the table’s interpolation rounds its own constant.

A function that raises stops the flight, and Flight raises its exception unchanged, with its type and traceback. That holds even for an exception at a trial step: the integrator tries a step, and when a model refuses, it would normally retry with a shorter one. It asks at speeds and heights a little past the flight’s own (the landing’s search, for one, asks the wind a few meters below the ground), so a function that refuses past its data wants some margin.

A function can’t be given alongside its constant counterpart: drag with drag_table, or wind with wind_speed_m_s or wind_from_deg, raises hpr.HprError, as does something that can’t be called. So does a drag coefficient that is negative or not finite, or a wind that isn’t finite; an answer of the wrong type, such as a string, raises Python’s TypeError.

Each call takes Python’s global interpreter lock, so a flight with a Python function runs slower than one without, and flights in other threads wait while it calls. The functions should give the same answer to the same question, or a flight can’t be repeated.

Monte Carlo

A Monte Carlo run flies the rocket many times, each time with its uncertain inputs drawn afresh about their planned values, to show how far the apogee and the landing spread (Monte Carlo dispersion explains the method and how to choose the numbers). hpr.MonteCarlo takes the rocket, the site and the rail as Flight does (a vertical rail by default), how many flights to fly (100 by default), a seed (0 by default), and one standard deviation for each input to scatter: a fraction for a share (impulse_sd_fraction=0.03 is 3%), degrees for an angle, meters or seconds otherwise. An input left out isn’t scattered. Like Flight, it flies as soon as it is made, its flights spread over the computer’s cores. The spread it shows is only as good as the standard deviations you give and hpr’s flight models, which are not yet checked against repeated real flights (Accuracy); where a rocket lands in a wind is the least certain number of all.

The run reads as a dictionary of NumPy arrays, one value a flight: what each flight drew (motor_1_impulse_scale, drag_scale and the rest) and what it came to (apogee_m, landing_distance_m, max_mach and the rest). run.columns lists them, in the order of hpr mc --export’s CSV columns. This flies a level 1 certification rocket’s .ork design 200 times from a 1.5 m vertical rail, in its default motor configuration, with the parachute stored in its file (recovery=True, A design from a file):

import numpy

level_1 = hpr.Rocket.from_file("validation/fixtures/ork/guides/level-1.ork", recovery=True)
windy = hpr.Environment(0.0, 0.0, 0.0, wind_speed_m_s=4.0, wind_from_deg=270.0)
run = hpr.MonteCarlo(
    level_1, windy, 1.5, runs=200, seed=2026,
    mass_sd_fraction=0.02, drag_sd_fraction=0.05, impulse_sd_fraction=0.03,
    wind_sd_fraction=0.25, wind_from_sd_deg=15.0,
)
apogee = run["apogee_m"]
print(f"{run.flown} of {run.runs} flights flown, {run.failed} failed")
print(f"apogee: mean {numpy.nanmean(apogee):.0f} m, 5% to 95% "
      f"{numpy.nanpercentile(apogee, 5):.0f} to {numpy.nanpercentile(apogee, 95):.0f} m")
print(f"mean landing: {numpy.nanmean(run['landing_east_m']):.0f} m east of the pad")

200 of 200 flights flown, 0 failed
apogee: mean 1069 m, 5% to 95% 1002 to 1134 m
mean landing: 842 m east of the pad

The command line flies the same run: hpr mc validation/fixtures/ork/guides/level-1.ork --runs 200 --seed 2026 --wind 4 --wind-from 270 --mass-sd 0.02 --drag-sd 0.05 --impulse-sd 0.03 --wind-sd 0.25 --wind-from-sd 15. run.to_csv() returns the text hpr mc --export writes.

A test holds the two equal (test_a_run_is_hpr_mcs_bit_for_bit). It flies 40 flights of this design with all eleven inputs scattered, and finds every number of every column equal, bit for bit, and the two CSV texts equal byte for byte. That holds on one platform, with both built in release mode (maturin develop --release, cargo build --release); a debug build’s last digits can differ.

A flight that fails, such as one whose drawn mass is negative, is counted and kept, never dropped. run.failed counts them, run.failures groups them by why (a dictionary each: at, "inputs" or "flight"; reason; count; and first_index, the first one’s row), and the outcome, failed_at and reason columns say which they were. A failed flight’s figures are NaN, so use NumPy’s nanmean, nanpercentile and the like, as above, or pick the flown ones with run["outcome"] == "flown". run.nominal is the flight with nothing scattered, as Flight.summary gives it, and run.dispersion the standard deviations given, by name.

The eleven inputs, each named for its unit:

A drag or wind function of your own is called from every flight of the run, one call at a time, and an exception it raises stops the run and is raised by MonteCarlo. The calls come in no set order, so a run repeats bit for bit only if the function’s answer depends on its arguments alone. A run takes 1 to 100,000 flights; a standard deviation that is negative or not finite raises hpr.HprError, named by its argument.

When something is wrong

A value out of its range, a part out of order, or a motor or material that isn’t there raises hpr.HprError, a kind of ValueError, with the library’s own message. So does an argument that doesn’t apply, such as a canopy beside a cd_s_m2:

try:
    hpr.Motor.from_catalog("Z9000")
except hpr.HprError as error:
    print(error)

no motor with a bundled thrust curve matches `Z9000`

Names and units

Every value is in SI units, and every argument and attribute that carries one names it, as the Rust API does: length_m, mass_kg, apogee_m, max_speed_m_s, wind_from_deg. Names that pick one of several things are strings, in any case, with a space or hyphen allowed where the name has an underscore:

A parachute is either a canopy diameter_m across, with its type’s drag coefficient or your own drag_coefficient, or a drag area cd_s_m2, its drag coefficient times its area in m², as RocketPy’s cd_s.

Every class and method

An argument written name= above can be left out, and is given by name: add_fins’ lengths have no default, but are named too. Each class and method has a docstring that says what its arguments mean: help(hpr.Rocket.add_fins), for example. The Rust reference for the package, hpr_py, says how it is built.

What is not here yet

The package covers the Rust builder, not the whole library. Not yet:

• An atmosphere written in Python. Rust programs have one today (Models of your own).
• Staging and mass shifts. A configuration that drops a stage under power is refused. Any other design of several stages flies as one stack: no stage drops away, a motor lit by another’s burnout lights on the whole stack, one lit by a separation never does, and rocket.notes says so.
• Swapping a motor into a design read from a file, as hpr sim --motor does.
• Separations stored in a design file, as above.
• Monte Carlo’s landing ellipses and spread summaries, which hpr mc prints and Rust programs get from hpr_analysis. From Python, NumPy finds them from the run’s arrays.
• The library’s built-in winds that change with height (power law, log law, layers) and weather files fly only from Rust. From Python you can write any of them as a wind function (Drag and wind of your own).
• Parts from a parts catalog, which only Rust programs build with (Parts from a catalog).
• Type stubs, so an editor sees the docstrings but not the arguments’ types.

Models of your own

This page shows how to fly a model of your own in place of one of hpr-sim’s: a drag model, a wind, or an atmosphere. You might have a drag curve from a wind tunnel, from another program, or from your own flights, or a wind profile from a weather balloon that none of the built-in winds fits. The page runs two example programs and walks through them. It follows on from The builder, and needs some Rust. From Python, a drag and a wind can be plain functions (Python).

How far to trust it. As far as your model, and no further than hpr-sim’s other models, which still fly the rest of the rocket and are not yet validated against real flights (Accuracy).

• Refused: a drag coefficient that is negative or not a finite number, a wind velocity that is not finite, and air the flight can’t use: a density or pressure that is negative or not finite, or a temperature, speed of sound or viscosity that is zero, negative or not finite. Each error names the wind or the air’s field, and the height.
• Tested: a drag model that hands back hpr-sim’s own drag flies the same flight, bit for bit, as flying without one, and a model that gives the same drag at every speed flies exactly as a drag table of that value does (a_drag_model_is_flown_in_place_of_hprs_drag).
• Not checked: whether your model is right. hpr-sim can’t know.
• Invented: the drag curve and the wind on this page. They are not measurements of any rocket or any day.

Which models you can replace

Each is a Rust trait: a set of methods your own type provides. Write the type, give it the method, and hand it over.

The zero-lift drag coefficient is the drag with the rocket pointed straight into the air, divided by the dynamic pressure and the rocket’s reference area: by default the area of a circle of its largest body diameter. A drag model replaces that number and nothing else:

• At an angle of attack, hpr-sim scales your number up and down with the angle as it scales its own (Drag).
• The normal force, center of pressure, roll and damping stay hpr-sim’s. So the stability margin a rocket reports doesn’t change with the drag model.
• Recovery doesn’t use it: under a parachute the drag is the parachute’s.
• Staging: a drag model is the whole stack’s drag, so a flight with a powered separation refuses it at the separation (Staging).

A drag table read from another program’s export (the flight builder’s drag_table, or with_drag_table on a simulation, which Getting started uses) replaces the same number; a drag model is the same idea with your code in place of the table. The last one set is the one flown. One difference matters: a table can carry the diameter it was measured on, and hpr-sim rescales it to the rocket’s reference area. A negative coefficient is refused from either, where the flight meets it: a table can give one past its rows or between them if its curve extrapolates linearly or bends. A model’s number is not rescaled. If your curve was measured on another area, multiply it by your area over query.reference_area_m2() before returning it.

A drag model

cargo run --example custom_drag -p hpr

This flies the rocket of The builder three times on a Cesaroni H54, from a vertical rail in calm air: with hpr-sim’s own drag, with that drag made 10% higher, and with a drag curve of invented numbers. The parachute opens at apogee, so only the drag changes from one flight to the next. Then it tries a curve that stops short of the rocket’s speed. It prints this:

My 54 mm rocket on a 168H54-10A, from a 1.8 m vertical rail in calm air
Not yet validated: see the Accuracy page before trusting these numbers.

drag                  apogee  apogee at  top speed
                         (m)        (s)      (m/s)
hpr's own drag         1145.1      14.06        187
hpr's, 10% higher      1091.2      13.65        183
a curve (invented)     1146.5      13.99        188

A curve that ends at Mach 0.4 stops the flight: Mach number past the drag curve's last point, 0.40

What the lines say:

• 10% more drag costs 53.9 m of apogee, 4.7%, and reaches it 0.41 s sooner. That is a quick way to see how much a rougher finish, or an uncertain drag, could matter.
• The curve is invented. Its apogee lands within 2 m of hpr-sim’s because of the numbers chosen, which says nothing about whether either is right. A curve from your own data would put your numbers here.
• The short curve refuses to guess past its last point, so the flight stops there and says why, instead of flying on made-up drag.

The program

The program is crates/hpr/examples/custom_drag.rs. Each model is a type with one method, zero_lift_drag, which gets a DragQuery and returns the coefficient:

• query.mach() is the Mach number.
• query.conditions().thrusting says whether a motor is burning. A burning motor fills the base of the rocket, so its drag is lower (power-on and power-off drag). The example’s curve has a column for each.
• query.conditions().reynolds_per_m is the Reynolds number per meter, for a model that depends on it.
• query.buildup() is hpr-sim’s own drag at that flow, what the flight would have used without the model. The 10% model multiplies its zero_lift_coefficient by 1.1.

The method returns a Result, so a model can refuse a question it can’t answer, as the curve does past Mach 0.4. The flight stops with that error, wrapped to say it came from the drag model. The integrator tries speeds a little past the flight’s own as it works out each step, so a curve that refuses past its end wants some margin beyond the top speed. A model is asked several times every step of the flight, so it should be quick, and give the same answer to the same question: a flight is only as repeatable as its models. Whatever the drag model, a flight stops at Mach 5, where hpr-sim’s normal force ends.

A wind model

cargo run --example custom_wind -p hpr

hpr-sim has steady, power-law, log-law and layered winds built in (Wind), and they reach the flight through the same Wind trait. This example writes one of its own: a wind that grows from 4 m/s at the ground to 10 m/s at 1,000 m, and veers, turning clockwise, from the west (270°) to the north-west (315°) on the way up. Above 1,000 m it holds steady. It flies the same rocket in that wind and in a steady 4 m/s west wind:

My 54 mm rocket on a 168H54-10A, from a 1.8 m vertical rail
Not yet validated: see the Accuracy page before trusting these numbers.

wind                    apogee   landing east  landing south  descent
                           (m)            (m)            (m)    (m/s)
steady, from the west   1138.0            853              0      4.6
veering                 1135.7           1395            835      4.6

Both winds are the same at the ground, where a flier would measure them. Aloft, the veering wind is stronger and comes from further north, so the rocket drifts further under its parachute, and to the south-east rather than due east. The parachute’s descent rate is the same in both.

The program is crates/hpr/examples/custom_wind.rs. Its Veering type has one method, wind, which gets a height above mean sea level and returns a WindSample: the air’s velocity as east, north and up components, and whether the model had to extrapolate past its data (never, for this one). A wind is asked by height above sea level, not above the ground, so the type keeps the ground’s elevation to measure from. Environment::with_wind flies it. The wind direction is where the wind blows from, so a west wind moves the air east.

hpr-sim refuses a wind velocity that isn’t finite wherever it reads the wind. A wind that returns a NaN (not a number) or an infinity stops the flight with a SimError::Domain error. Its message names the wind and gives the height above sea level, in meters, where the wind was asked. For a test wind that turns to NaN above 1,700 m, the message reads “height above sea level, m, at which the wind’s velocity is not finite is outside its domain: 1700.0…”, the height of the first step to ask above 1,700 m, so its digits depend on the step. This holds while climbing, under a canopy, and for bodies flown apart after a separation (issue #237, the report that asked for it). Tests pin each case: a_wind_that_is_not_finite_stops_the_flight and a_wind_that_is_not_finite_under_a_canopy_stops_the_descent, and a_separated_body_refuses_a_wind_that_is_not_finite. hpr-sim can’t tell whether a finite wind is right; that is up to the model.

An atmosphere

An atmosphere of your own works the same way, through Environment::with_atmosphere. hpr-sim’s own are the standard atmosphere and a weather balloon’s sounding (Atmosphere); there is no example program for one of your own yet. Its one method, air, gets a height above mean sea level and returns an AirSample: the air’s temperature, pressure, density, speed of sound and viscosity, and whether the model had to extrapolate past its data.

hpr-sim refuses air it can’t use wherever it reads the air. Every field must be a finite number. The temperature, speed of sound and viscosity must also be above zero. The density and pressure may be zero, as in a vacuum, but not negative. hpr-sim’s standard atmosphere is the reason zero is allowed: far above its 86 km top, its pressure and density shrink to zero.

Air that breaks a rule stops the flight with a SimError::Domain error. Its message names the field and gives the height above sea level, in meters, where the air was asked. For a test atmosphere whose density turns to NaN above 1,700 m, the message reads “height above sea level, m, at which the air’s density is negative or not finite is outside its domain:”, then the height of the first step to ask above 1,700 m. If more than one field is bad, the first in the order density, pressure, temperature, speed of sound, viscosity is the one named.

This holds while climbing, under a canopy, and for bodies flown apart after a separation (issue #301, the report that asked for it). Before, a density that was NaN or negative turned the drag off with no error. In the tests, a rocket climbed about twice as high, and bodies flown apart landed at about 140 m/s. Tests pin each case: air_the_flight_cannot_use_stops_the_climb and air_the_flight_cannot_use_under_a_canopy_stops_the_descent, and a_separated_body_refuses_air_it_cannot_use. Another test checks that hpr-sim’s own atmospheres pass, from 5 km below sea level to a million kilometers up (the_check_on_the_air_takes_every_stock_atmosphere). hpr-sim can’t tell whether air that passes is right; that is up to the model.

Where next

• The API reference’s guide module says the same in five short chapters, each with code that CI runs, and hpr_aero::custom documents the drag trait.
• The builder builds the rocket these examples fly.
• Accuracy says how well hpr-sim’s own models have been checked, which is what a model of your own replaces.

Monte Carlo dispersion

No two flights of one rocket are the same. The motor burns a little hotter or cooler than its label, the rocket weighs a few grams more than the plan, the wind is not the forecast’s. A Monte Carlo run flies the rocket hundreds or thousands of times. Each time it draws the uncertain inputs afresh around their planned (nominal) values, and the run shows how far the apogee and the landing spread, and draws the ellipse the landings fall in. This page runs one, says what each dispersion does to a flight, and how to choose the numbers. Its examples need some Rust and follow on from The builder; hpr mc runs the same from the command line, with no code (below), and hpr.MonteCarlo from Python (From Python).

How far to trust it. The sampling is tested; the spread it gives is only as good as the uncertainties you give it and hpr-sim’s flight models, which are not yet validated against real flights (Accuracy).

• Tested: the same seed gives the same run, bit for bit, however many flights it has and however many threads fly them; a run with no dispersion flies the nominal flight in every sample; each dispersion moves its input as the table below says; a dispersed motor keeps its specific impulse; failed flights are counted (montecarlo.rs’s tests). The landing ellipses are tested against normal spreads with known answers.
• Not checked: whether the spread matches the spread of real flights. No measured set of repeated flights has been compared yet.
• Left out: correlations between inputs, distributions other than the normal, and the inputs listed under What is not dispersed. A run flies what Flight::builder sets up, a staged flight’s separations included; events of your own can’t be part of one yet.

A run of 200 flights

The example program crates/hpr/examples/monte_carlo.rs takes the 54 mm rocket of The builder on a Cesaroni H54 (motor designation 168H54-10A), at Spaceport America in a forecast wind of 4 m/s from the west, off a rail leaned 5° into the wind. It disperses the rocket’s mass, its center of mass, its drag, the motor’s impulse and burn time, the wind and the rail, and flies 200 flights. Run it from a copy of the repository with:

cargo run --example monte_carlo -p hpr

The heart of it:

let launch = Flight::builder(&rocket, &environment, 1.8)
    .inclination_deg(85.0)
    .heading_deg(270.0);
let dispersion = Dispersion {
    dry_mass_sd_fraction: 0.02,              // 2% of the mass without the motor
    cg_sd_m: 0.005,                          // 5 mm
    drag_sd_fraction: 0.05,                  // 5% of the drag coefficient
    impulse_sd_fraction: 0.03,               // 3% of the motor's total impulse
    burn_time_sd_fraction: 0.02,             // 2% of its burn time
    wind_speed_sd_fraction: 0.25,            // 25% of the wind's speed
    wind_heading_sd_rad: 15_f64.to_radians(),
    rail_elevation_sd_rad: 1_f64.to_radians(),
    rail_azimuth_sd_rad: 2_f64.to_radians(),
    ..Dispersion::default()
};
let monte_carlo = MonteCarlo::new(launch.inputs()?, dispersion)?;
let run = monte_carlo.run(2026, 200);          // seed 2026, 200 flights
let apogee = run.apogee()?;                    // the apogees' spread
let landing = run.landing()?;                  // where they landed
let ellipse = landing
    .prediction_ellipse(0.95)?                 // where the next flight lands, 95 times in 100
    .ok_or("too few landings")?;

It prints:

My 54 mm rocket on a 168H54-10A, from a 1.8 m rail at 85°, heading west into a 4 m/s west wind
200 flights, seed 2026: 0 failed
Not yet validated: see the Accuracy page before trusting these numbers.

                       nominal     mean  std dev       5%   median      95%
apogee (m)              1113.3   1119.8     47.4   1040.5   1121.3   1198.8
landing distance (m)     662.4    660.3    208.9    329.3    670.5    996.5
landing east (m)         662.4    626.1    209.6    274.9    635.5    957.7

Landing ellipses, centered 626 m east and 23 m south of the pad:
                       semi-major  semi-minor  heading  landings inside
50%                         253 m       239 m     131°            48.0%
95%                         525 m       497 m     131°            94.5%
95%, the next flight        532 m       503 m     131°            95.5%

Reached 1,100 m: 65.5% of the flights
Apogee with 5% less drag: +29 m; with 5% more: -27 m

How to read it:

• Nominal is the one flight with every input at its planned value.
• Landing distance is how far from the pad the rocket lands; landing east is the eastward, downwind, part of it. The nominal flight lands due east, so the two are equal. In the run the wind’s heading has a standard deviation of 15°, which pushes some flights north or south, so the mean landing east is smaller than the mean distance.
• Std dev is the standard deviation. If the spread is normal, about two values in three lie within one standard deviation of the mean. 5% and 95% are percentiles: one flight in twenty went lower than the 5% value, one in twenty higher than the 95% value. So nine flights in ten reached between about 1,040 and 1,200 m.
• The mean is not the nominal flight. The mean apogee is 6.5 m above the nominal one. With 200 flights the mean itself is uncertain by about 47.4 / √200 = 3.4 m (its standard error), so 6.5 m is 1.9 standard errors: chance can account for most of it. Part is that the apogee doesn’t respond evenly: 5% less drag gains 29 m and 5% more loses 27 m, so an even spread of drag lifts the mean apogee by about 1 m.
• The landing spreads far more than the apogee. The landing distance’s standard deviation is about a third of its mean (209 of 660 m); the apogee’s is 4% (47 of 1,120 m). Under the parachute the drift is the wind’s speed times the time in the air, and the wind’s speed is the most uncertain input here.

From the command line

hpr mc flies any design hpr sim flies, a staged .ork included, with each dispersion an option in the units the command line uses elsewhere: degrees for angles, a fraction for a percentage (--impulse-sd 0.03 is 3%). It prints the apogee’s and the landing distance’s spreads, the landing ellipses below and the failed flights, and --export runs.csv writes every flight’s draw and outcome, one row a flight. Its runs are the library’s for the same seed, bit for bit: a test flies both and compares them (mc_flies_a_public_ork_as_the_library_does).

hpr mc my-rocket.ork --runs 200 --seed 2026 --wind 4 --wind-from 270 \
  --mass-sd 0.02 --drag-sd 0.05 --impulse-sd 0.03 --wind-sd 0.25 --wind-from-sd 15

From Python

hpr.MonteCarlo in the Python package flies the same run and returns it as NumPy arrays. Each array is one column of the table hpr mc --export writes, with one value per flight; failed flights are counted and their figures are NaN. It takes the same eleven dispersions as hpr mc’s options, named for their units (impulse_sd_fraction, wind_from_sd_deg). A test runs both on 40 flights with every input scattered and finds every number equal, bit for bit, on one platform with both built in release mode (test_a_run_is_hpr_mcs_bit_for_bit). Landing ellipses and the summary tables aren’t in Python yet; NumPy finds the spreads from the arrays. A configuration that drops a stage can’t be read from Python yet, so it runs only from Rust and hpr mc.

Landing ellipses

A landing ellipse is the outline a range safety officer or a competition asks for: an area on the ground that the rocket lands inside, say, 95 times in 100. Comparing it with the field’s boundary says whether the field is big enough for this rocket in this wind. For that check, use the next-flight ellipse below (Scatter::prediction_ellipse).

The ellipse assumes the landings follow a normal distribution, and it is only as good as the run’s landings, which carry the flight models’ errors and those of the dispersions you chose; neither has been compared with real flights yet. The section ends with how to tell when the landings aren’t normal.

hpr-sim draws the ellipse from the run’s landing points (Run::landing, then Scatter::ellipse) in three steps. Its semi-major and semi-minor axes are its half-lengths along its long and its short direction.

1. The center is the landings’ mean: here 626 m east and 23 m south of the pad.

2. The axes. The landings’ covariance gives the direction they spread most, the major axis, and the direction across it, the minor axis, with a standard deviation along each. Here those are about 214.6 m and 203.0 m. The spread is nearly round, because the wind’s uncertain heading (15°) spreads the landings sideways about as much as its uncertain speed (25%) spreads them downwind.

3. The size. If the landings follow a two-dimensional normal distribution, the ellipse reaching k standard deviations along each axis holds the share p = 1 − e^(−k²/2) of them. So the ellipse of level p has k = √(−2 ln(1 − p)):

   Level p	50%	90%	95%	99%
   Scale k	1.177	2.146	2.448	3.035

   The 95% ellipse’s semi-axes are 2.448 × 214.6 m = 525 m and 2.448 × 203.0 m = 497 m.

In two dimensions it takes more standard deviations to hold 95% than in one (2.448 against 1.960), because a landing can stray in two directions at once.

Heading is the major axis’s direction, clockwise from north, between 0° and 180°: here 131°, running from north-west to south-east. With axes this close to equal the heading means little: a few landings more or less could turn it a long way. A circle has no heading at all; hpr-sim then reports 90°, east.

The next flight. The mean and covariance of 200 flights are only estimates, so an ellipse drawn from them holds a little less than its level of the flights still to come. For normal landings Scatter::prediction_ellipse allows for that exactly. Its k comes from Hotelling’s T² distribution, the one that accounts for the mean and the spread both being estimated from the same flights: k² = ((n² − 1)/n)((1 − p)^(−2/(n − 2)) − 1) for n landings. With 200 landings its axes are 1.3% longer (532 m against 525 m); with 10 they would be 36% longer. Use it to answer “will my next flight land in the field?”.

Landings inside counts the run’s landings each ellipse really holds (Scatter::share_inside). Here they are 48.0%, 94.5% and 95.5%. Those are within the standard error of a share p from a run of 200, √(p(1 − p)/200): about 3.5 percentage points at 50%, 1.5 at 95%. So the landings are consistent with a normal spread, though that doesn’t prove it. With few landings the shares run high, because the ellipse is fitted to the same points: with three landings, even the 50% ellipse holds all three. If the share is far from the level in a run of hundreds of flights, the landings aren’t normal: an uncertain wind heading in a strong wind spreads them along an arc, and an ellipse is then the wrong shape. Look at the points themselves (Scatter::points). A failed flight has no landing; it counts as outside for the lower bound and inside for the upper (Failed flights are counted).

How far to trust it. The ellipse math is tested against normal spreads whose answers are known exactly (ellipse.rs’s tests):

• The scale matches the NIST/SEMATECH handbook’s chi-square table and its closed form.
• The axes and heading of turned, stretched covariances come back to 1e-14.
• Integrating a normal density over its ellipse gives the level to 1e-12.
• 100,000 points drawn from a known normal spread give back its covariance, and land inside each ellipse at its level, within five standard errors.
• A new point lands inside the next-flight ellipse of 3, 5 or 20 others at its level, within five standard errors, and inside the plain ellipse visibly less often.

The tests can catch a wrong ellipse: the 95% ellipse of a spread 200 m long and 30 m wide (one standard deviation each way), turned 6° off its axes, holds 90.6%, and the test pins that.

What each dispersion does

Each dispersion is a standard deviation: zero, the default, leaves its input at the nominal value. For each flight hpr-sim draws a standard normal number z (mean 0, standard deviation 1) for each input and moves the input by σ z, with σ the standard deviation you gave. A rocket built of more than one stage gets a draw for each stage, whether its stages fly together or separate; each motor and each parachute gets its own draw too.

Four cases need a word:

• A draw that makes an input impossible fails that flight. With a 60% mass spread, a draw of z below −1.67 gives a negative mass; a rail drawn below the horizon is another. That flight is kept in the run as failed, with its reason, and counted (next section). The two delays and the wind’s speed are the exceptions: a charge can’t fire before its event and a wind can’t blow at less than calm, so a draw below zero is flown as zero.
• A cluster is one draw. hpr-sim holds a cluster as one motor in a mount with several tubes, so all its motors get the same impulse and burn time.
• A vertical rail leans along one line. The elevation is dispersed in the plane of the rail’s heading, so on a vertical rail with only its elevation dispersed every flight leans towards or away from that heading, never sideways. RocketPy disperses its rail the same way, an inclination and a heading (rocketpy/stochastic/stochastic_flight.py:21-24, version 1.13.0). Disperse the heading too for leans in every direction.
• A staged flight keeps its separations. Every flight comes apart where the nominal one does: at the same event, or at the same time for a split the file times in seconds. A split timed by a burnout follows the dispersed burn. One timed in seconds doesn’t, so a flight whose booster still burns then stops with the flight’s error and counts as failed, unless the split may drop a burning motor, as OpenRocket’s first burnout of a stage does (decision record ADR-172). --delay-sd moves a booster’s ejection charge, and the parachute it fires, but not a split the file times in seconds.
• A part dropped on the way up needs its device open. After a split with nothing left to burn, each part flies as a point with only its open devices’ drag. A part whose device fired by the split but waits out a dispersed lag would climb through the lag with no drag at all, so hpr refuses that flight, and it counts as failed.

Failed flights are counted

A run never drops a flight. Run::failed lists those that failed, saying whether the draw made an impossible input or the flight refused it. A spread like Run::apogee counts every flight tried: attempted() is the run’s size, count() the flights that gave a value, and missing() the rest. Its mean and percentiles are over the flights that gave a value, so many failures can bias them: check missing() first.

A share such as “reached 1,100 m” is given as two bounds, share_at_least(1100.0):

• low counts a failed flight as not reaching it;
• high counts it as reaching it.

With no failures the two are equal. With some, the truth lies between them, and a wide gap says the run can’t answer the question.

The same seed, the same run

Every number a flight draws comes from its own stream of random numbers, picked out by the run’s seed, the flight’s number in the run and the input it is for. So:

• flight 37 of a run is the same flight in a run of 100 or of 10,000;
• a run flown on one thread or on twelve is the same, bit for bit (with the parallel feature, run_parallel);
• turning a dispersion on or off doesn’t change what the other inputs draw.

To fly on several threads, turn on the parallel feature where your program depends on hpr, as Using it from your own program describes, and call run_parallel instead of run:

[dependencies]
hpr = { git = "https://github.com/nrdptel/hpr-sim", rev = "<commit>", features = ["parallel"] }

On another platform (operating system and processor) a draw can differ in its last binary digit, because the normal numbers use the platform’s logarithm; a run then agrees to many digits, not to the bit. The decision record is ADR-134.

How long a run takes

On the development machine, an Apple M5 with 10 cores, 10,000 flights of a Level 2 rocket (one on a J, K or L impulse class motor) from ignition to the ground, under a drogue and a main, take:

No flight failed. These are release builds, with optimisation on: add --release to cargo run, or build your program with it. A debug build, what plain cargo run gives, is many times slower. To time it on your own machine, from a copy of the repository:

cargo bench -p hpr --features parallel --bench ten_thousand

It takes about a minute. Its output, the before-and-after numbers and where the time goes are on Performance. Other machines haven’t been timed.

A rocket that passes Mach 1.2 flies on a supersonic table: its body’s lift and center of pressure by the shock-expansion method, worked out at every 0.05 Mach once and then looked up (The body faster than sound in a flight). Building it takes about a fifth of a second for the rocket above. A dispersion changes the rocket’s masses, its motor, the weather and a scale on its drag, never its shape, so the flights of a run share the nominal flight’s table: the run builds it once. Each flight also reuses the nominal rocket’s layout, its parts placed and weighed. Every flight flies exactly as it would alone, bit for bit; a unit test holds a supersonic flight to that, on one, two and five threads (samples_share_the_nominal_table_and_fly_as_alone).

Before this speed-up (M6.1d, October 2026), each flight built its own table, and the supersonic run above took 264 s. To fly draws of your own, as a sensitivity analysis does, use monte_carlo.fly(&draw), which shares the same work. Flying a draw’s inputs yourself, monte_carlo.inputs(&draw)?.fly(), builds its own table and layout. A two-stage rocket’s sustainer, built when the stages separate, still builds its own table in every flight. Issue #285 is about making each flight itself faster.

This times the run. It says nothing about how accurate a Mach 2 flight is: no validation flight goes past Mach 1.06 (see The body faster than sound in a flight).

Choosing the numbers

The spread a run gives is the spread you put in. Some places to start:

• Motor impulse. NFPA 1125, the code commercial motors are certified to, requires that the “standard deviation of the total impulse data shall be no greater than 6.7 percent of the mean” over a motor type’s certification firings (§8.1.7 and §8.2.7). Four certification reports of the National Association of Rocketry (NAR) measured 1.3% to 3.1%: an Estes C6 (2.0%), D12 (3.1%), E12 (1.28%) and an AeroTech G80 (2.3%), hosted on ThrustCurve.org. So 2% to 3% is a fair guess, and 6.7% the most the code allows.
• Ejection delay. The same code allows a measured delay to differ from the labelled one by “1.5 seconds or 20 percent (whichever is greater, but not to exceed 3 seconds)”. The E12 and G80 reports’ firings of one delay scatter by 0.2 to 0.9 s, and a delay’s average can sit more than a second from its label: the G80’s 7 s delay averaged 5.88 s. A dispersion is about the nominal value, so give the delay you expect, not only the one printed on the motor.
• Burn time. The code sets no limit of its own. The four reports disagree: the E12’s and G80’s burn times scatter by 1.5% and 1.8%, the older C6’s and D12’s by 17% and 18%. Why isn’t recorded; the older sheets may time the burn differently. Start from a few percent for a composite motor, and try a larger value to see whether it matters to your flight.
• Mass, center of mass and drag depend on how well you know your rocket. A rocket weighed ready to fly needs a smaller mass dispersion than one weighed on paper. Drag is usually the least certain of the three: Accuracy shows how far hpr-sim’s drag sits from other programs’ and from wind-tunnel data.
• Wind depends on the forecast, its age and the hour. A sounding of the day, or a forecast’s spread between models, is a better guide than a guess.

The NFPA wording is the 2019 edition’s, as quoted in the public first-draft documents of its next revision (public inputs 4 and 5), whose first revisions FR-7 and FR-8 keep both sentences (1125_A2021_PYR_AAA_FD_FRStatements.pdf). The edition in force today hasn’t been checked.

What is not dispersed

• Inputs are independent: a heavier rocket isn’t also draggier.
• Every dispersion is normal; there are no uniform or skewed ones.
• Moving a stage’s center of mass keeps its inertia about the center.
• The drag dispersion scales the zero-lift drag only, not the normal force or the moments; a recovery device’s drag isn’t dispersed.
• A stretched thrust curve keeps its shape.
• The atmosphere’s temperature and pressure, a motor’s ignition time, a separation’s trigger or time, and events of your own.

What comes next

The run gives each flight’s whole FlightSummary, so any number a flight reports can be spread with run.distribution(...), as the example does for the landing. To find which input moves the apogee most, see Sensitivity analysis.

The API reference is hpr_analysis::montecarlo, hpr_analysis::statistics and hpr_analysis::ellipse.

Sensitivity analysis

A Monte Carlo run shows how far a rocket’s apogee spreads. It doesn’t say which input causes the spread. Sensitivity analysis does: it ranks the uncertain inputs by how much each moves a result, so you know which to measure more carefully and which you can stop worrying about. This page shows hpr-sim’s two methods. They are Morris’s screening, which is cheap, and Sobol’ indices, which cost more and say more. It runs both on two test functions whose answers are known, then screens a rocket’s apogee and landing. It needs some Rust, and follows on from Monte Carlo dispersion.

How far to trust it. The two methods are tested against answers known in closed form. On a rocket, the ranking they give is only as good as the ranges you give and hpr-sim’s flight models, which are not yet validated against real flights (Accuracy).

• Tested: both methods match the known answers of two standard test functions within four of their own standard errors. Repeated with 500 to 1,000 different seeds, the error an analysis reports is the scatter the repeats really show: for every Sobol’ index of Ishigami’s function, and for the Sobol’ indices and Morris μ*s of a four-factor g function. The same seed gives the same numbers, bit for bit (tests/sensitivity.rs).
• Not checked: whether a rocket’s ranking matches what real flights would show.
• Left out: inputs that depend on each other, inputs that aren’t spread evenly over a range, and the Sobol’ indices of pairs of inputs. A Sobol’ analysis costs thousands of runs per input: 65,536 flights for this page’s rocket, against Morris’s 70, so the rocket example uses only the Morris screening.

Inputs as factors

Each uncertain input is a factor: a name and a range, with every value in the range equally likely (Factor). The drag might be anywhere from 10% below its estimate to 10% above, say, or the wind anywhere from calm to 8 m/s. Factors are independent: a heavier rocket isn’t also draggier.

Both methods work the same way. They lay out the points to try (a design), you run your model at each point in order, and they analyze what came back. The model can be a whole flight, with the factors set into its inputs, or any function. So you can run the points however you like, on many threads or many machines. Each method also has a shortcut that takes a closure and runs the points itself.

Morris screening

Morris’s method nudges one factor at a time and watches the output move. It works on a grid: each factor’s range is cut into p evenly spaced levels (4 is usual). A step moves one factor p/2 levels (two of four), which is a fraction Δ = p / (2(p − 1)) of its range: 2/3 for four levels.

The change in the output over one step, divided by Δ, is an elementary effect. It is the change the factor would cause across its whole range, at the slope measured over the step. A path starts at a random grid point and steps each factor once, in a random order, so k factors take k + 1 runs per path. Each step gives one effect. After r paths, each factor has r effects, and the screening reports three numbers for each factor (ElementaryEffects):

A factor with μ* near zero can be left at its planned value. The screening also gives μ*’s standard error, which shrinks as 1/√r: ten paths are usually enough to rank, and the cost is r (k + 1) runs.

For example, Ishigami’s test function (below) has a sin² x₂ as a term, with a = 7. On a four-level grid from −π to π, a step of x₂ moves sin² by exactly 3/4, up or down, so every effect of x₂ is ± (3/4)(7)/(2/3) = ± 7.875. The example’s screening finds μ* = 7.875 with no error, and μ near zero.

M. D. Morris, “Factorial sampling plans for preliminary computational experiments”, Technometrics 33(2), 161–174, 1991, defines the effects, the grid and the paths. F. Campolongo, J. Cariboni and A. Saltelli, “An effective screening design for sensitivity analysis of large models”, Environmental Modelling & Software 22, 1509–1518, 2007, add μ*. They found, by experiment rather than proof, that it ranks factors in the same order as the total Sobol’ index.

That is usual, not certain. A step spans about half of each range, so it can miss a response that repeats over about half the range. Ishigami’s sin² x₂ repeats every π, half of its range from −π to π. At four levels, Morris puts x₂ first (μ* 7.875 against 7.704 for x₁), while the total index puts x₁ first (0.558 against 0.442). At six levels or more, Morris puts x₂ last (2.687 at six levels), though it causes the largest share of the variance alone. A rocket’s outputs rarely repeat like that, but treat factors whose μ*s are close as tied, and use Sobol’ indices to settle an order that matters.

hpr_analysis::sensitivity::morris gives the equations and page numbers.

Sobol’ indices

Sobol’s method splits the output’s variance (the square of its standard deviation) among the factors. It reports two shares for each factor (SobolIndex):

• The first-order index Sᵢ is the share of the variance the factor causes alone. If you could pin the factor to its true value, the variance would drop by this share, on average.
• The total index S_Tᵢ is the share it has any part in, alone or together with others. If you pinned every other factor, this share of the variance would remain, on average.

Sᵢ ≤ S_Tᵢ. The gap is how much the factor acts through others. A factor with a total index near zero can be left at its planned value.

The analysis draws two independent tables, A and B, each of N rows with every factor spread over its range. Then, for each factor i, it builds a third table: A with factor i’s column taken from B. Comparing the outputs of the three tables row by row gives both indices. A. Saltelli and others (“Variance based sensitivity analysis of model output”, Computer Physics Communications 181, 259–270, 2010) give the estimates used here, the best of those they compared. The cost is N (k + 2) runs, and the error shrinks as 1/√N: with N = 8,192, an index comes out to about ±0.01.

Each index comes with its standard error, found by the delta method from how much the rows scatter. hpr_analysis::sensitivity::sobol gives the formulas.

Checked against

Two test functions have Sobol’ indices known in closed form (hpr_analysis::sensitivity::benchmark):

• Ishigami and Homma’s function, y = sin x₁ + 7 sin² x₂ + 0.1 x₃⁴ sin x₁, each x from −π to π. x₃ does nothing alone (S₃ = 0), yet it is part of a quarter of the variance, through x₁. The closed forms are I. M. Sobol’ and Y. L. Levitan’s (Computer Physics Communications 117, 1999, p. 57).
• Sobol’s g function, a product of one term per factor, each with a weight aᵢ: the factor matters most at aᵢ = 0 and hardly at all at 99. The closed forms are Saltelli and others’ (2010, p. 268). The tests use aᵢ = 0, 1, 4.5, 9 and four 99s, spanning the four classes Marrel and others (2008) name, as the SFU library of test functions quotes them: very important at 0, relatively important at 1, non-important at 9 and non-significant at 99.

For Morris there is also an exact answer. A screening estimates the moments of a finite set of effects: every step on the grid. Morris::population runs the model at every grid point and computes them exactly: the example’s “whole grid” column. For both functions they also follow in closed form, which the tests check.

The tests in tests/sensitivity.rs check four things:

• Every Sobol’ index of both functions, from 32,768 and 16,384 rows, lies within four standard errors of its closed form.
• Every Morris μ*, from 1,000 paths, lies within four standard errors of the exact one.
• The standard errors are honest. Take each estimate’s distance from the known answer, divided by its standard error. Over n seeds, these have a mean within 4/√n of 0 and a standard deviation within 4/√(2n) of 1. This holds for every Sobol’ index of Ishigami’s function (1,000 seeds) and of the g function’s first four factors (500 seeds), and for Morris’s μ* of those four (1,000 seeds). The same test checks that standard errors 15% too small would fail. A separate unit test computes each Sobol’ standard error a second way, from the raw row means.
• On the g function, twenty Morris paths rank the four factors that matter in the order of their total indices.

An example

The example program crates/hpr/examples/sensitivity.rs runs both methods on the two test functions and prints them beside the known answers. Then it screens the rocket of Monte Carlo dispersion over six inputs. Run it from a copy of the repository with:

cargo run --example sensitivity -p hpr

Excerpts from it follow. The test functions take a closure:

let ishigami = Ishigami::STANDARD;
let sobol = Sobol::new(Ishigami::factors()?, 8192)?;     // N = 8,192 rows: 40,960 runs
let indices = sobol.indices(seed, |x| ishigami.evaluate(x))?;

For the rocket, the screening lays out its points and the program flies each one. A Monte Carlo set-up with no dispersion turns a draw (each input’s factor or offset) into the flight it flies (MonteCarlo::inputs):

let monte_carlo = MonteCarlo::new(launch.inputs()?, Dispersion::default())?;
let nominal = monte_carlo.draw(seed, 0);                 // every input as planned
let factors = vec![
    Factor::new("dry mass factor", 0.95, 1.05)?,
    Factor::new("drag factor", 0.9, 1.1)?,
    Factor::new("impulse factor", 0.94, 1.06)?,
    Factor::new("wind speed (m/s)", 0.0, 8.0)?,
    Factor::new("wind turn (°)", -30.0, 30.0)?,
    Factor::new("rail angle (°)", 80.0, 90.0)?,
];
let morris = Morris::new(factors, 4, 10)?;               // 4 levels, 10 paths: 70 flights
let design = morris.design(seed);
for x in design.points() {
    let mut draw = nominal.clone();
    draw.drag_scale = x[1];                              // a factor on the drag
    draw.wind_speed_scale = x[3] / 4.0;                  // a factor on the 4 m/s forecast
    draw.rail_elevation_offset_rad = (x[5] - 85.0).to_radians(); // an offset from 85°
    // ... and the dry mass, impulse and wind turn the same way
    let flight = monte_carlo.fly(&draw)?;
    apogees.push(flight.apogee.as_ref().ok_or("no apogee")?.height_above_ground_m);
}
let apogee = design.analyze(&apogees)?;                  // the same flights, any output

The six inputs, with ranges made up for the example:

A Draw can also move a stage’s center of mass, the motor’s burn time and ejection delay, the rail’s heading and a recovery device’s delay (What each dispersion does).

It prints:

Sobol' indices of Ishigami's function (a = 7, b = 0.1), 8192 rows, 40960 runs
        first order: known  estimate ± error      total: known  estimate ± error
x1                 0.3139    0.3101 ± 0.0108             0.5576    0.5453 ± 0.0154
x2                 0.4424    0.4549 ± 0.0098             0.4424    0.4494 ± 0.0074
x3                 0.0000   -0.0071 ± 0.0099             0.2437    0.2404 ± 0.0050

Sobol' indices of the g function, a = 0, 1, 4.5, 9, 99 (four times), 8192 rows, 81920 runs
        first order: known  estimate ± error      total: known  estimate ± error
x1                 0.7162    0.7162 ± 0.0124             0.7871    0.7844 ± 0.0127
x2                 0.1790    0.1683 ± 0.0077             0.2422    0.2444 ± 0.0050
x3                 0.0237    0.0246 ± 0.0029             0.0343    0.0353 ± 0.0008
x4                 0.0072    0.0059 ± 0.0017             0.0105    0.0109 ± 0.0003
x5                 0.0001    0.0001 ± 0.0002             0.0001    0.0001 ± 0.0000
(x6 to x8 are as x5)

Morris screening of Ishigami's function, 4 levels, 100 paths, 400 runs
            μ*: whole grid  estimate ± error       σ: whole grid  estimate
x1                     7.704     7.079 ± 0.625                6.249     6.249
x2                     7.875     7.875 ± 0.000                7.875     7.915
x3                     6.249     6.124 ± 0.628                8.837     8.784

Morris screening of the Monte Carlo page's rocket, 4 levels, 10 paths, 70 flights
Not yet validated: see the Accuracy page before trusting these numbers.
Each effect is the change across the input's whole range, m.
                     apogee: μ*  ± error      σ     landing distance: μ*  ± error      σ
dry mass factor             36.0 ±   1.8    5.6                       70.0 ±  22.5   72.0
drag factor                112.9 ±   3.2   10.3                       80.5 ±  18.0   57.0
impulse factor             118.3 ±   2.3    7.1                      107.5 ±  23.7   75.1
wind speed (m/s)            50.3 ±   4.1   13.1                     1417.5 ± 101.4  320.7
wind turn (°)                4.4 ±   1.0    5.4                       53.4 ±  10.5   64.5
rail angle (°)              68.4 ±   3.1    9.9                      350.2 ±  17.6  231.0

How to read it:

• The test functions land within 1.4 standard errors of the known answers, from the printed digits. S₃ comes out slightly below zero: the estimate of a share that is really zero scatters around zero. The g function’s x5 shows “± 0.0000” because its error is below 0.00005.
• Ishigami’s Morris screening at 400 runs puts x2, x1, x3 in the whole grid’s order, but the gaps are only about one standard error, so at 100 paths they aren’t really ranked. Its σs are as large as its μ*s, the sign of a function that bends or whose factors act together.
• The rocket’s apogee moves most with the motor’s impulse (118 m across ±6%) and the drag (113 m across ±10%), then the rail’s angle (68 m across 80° to 90°), the wind’s speed (50 m) and the dry mass (36 m across ±5%). The wind’s direction hardly matters (4 m). The σs are small beside the μ*s: each input acts nearly in a straight line and alone. The exception is the wind’s direction, whose σ (5.4 m) exceeds its μ* (4.4 m): its effects differ in size or sign from path to path. The impulse and the drag are 1.4 combined standard errors apart: ten paths don’t settle which comes first.
• The landing is the wind’s: 1,418 m across calm to 8 m/s, then the rail’s angle (350 m). Here the σs are large, so these effects bend or depend on the other inputs.

The ranges are made up for the example. With your own rocket, use the ranges your measurements support; a factor’s effect grows with its range.

Choosing the numbers

• Levels: four, an even number as the method needs. More levels let a path start from more places in each range, at the same cost per path, but the step stays about half the range, so more levels don’t help with a response that repeats (see Morris screening).
• Paths: ten to twenty to rank. Check μ*’s standard error: two factors whose μ*s differ by less than a couple of errors aren’t ranked yet.
• Rows: a Sobol’ analysis needs about 8,000 rows, each k + 2 runs, to pin an index to about ±0.01 to ±0.015 (one standard error). Use Morris first to find the few factors that matter, then Sobol’ on those if you need the shares or the order of two close ones.
• Normal inputs: give each one the same multiple of its standard deviation, such as ±2, so they are compared alike. A range spreads the input evenly, which weighs its ends more than a normal spread does.

Left out

• Factors are uniform over their ranges and independent. A normal input can be given as a range about its mean, such as ±2 standard deviations, which spreads it more evenly than it really is.
• Sobol’ rows are plain pseudo-random draws, not quasi-random ones (evenly spread sequences, such as Sobol’s own), which converge faster.
• No second-order Sobol’ indices (the share of each pair alone).
• No choice of the most spread-out Morris paths among many (Campolongo’s improvement).
• No command-line or Python front end yet.

The API reference is hpr_analysis::sensitivity.

Optimization

Sometimes you know the result you want and need the design that gives it: that is optimization. That might be a rocket that reaches exactly 3,048 m (10,000 ft) for a competition, or the lightest fins that keep it stable. An optimizer searches for that design. It tries designs, flies each one, and uses what it learns to choose better ones, until it finds the best it can. This page shows hpr-sim’s optimizer, CMA-ES. It runs on test functions whose answers are known, then finds the nose ballast and body length that send a rocket to 3,048 m with a chosen stability margin. Then it chooses a motor and a catalog nose cone as well, within a competition’s limits on stability and speed off the rail. Then a second optimizer, NSGA-II, weighs two goals against each other: how much apogee each extra calibre of stability costs. A third, EGO, is for models so slow that only tens of evaluations can be afforded. It needs some Rust.

How far to trust it. All three optimizers are tested against answers known exactly; CMA-ES and NSGA-II also against outside implementations, EGO not yet. On a rocket, their answers are only as good as hpr-sim’s flight models, which are not yet validated against real flights (Accuracy).

• Tested: four standard test functions of ten variables are run from 20 seeds each. Every run reaches a value of 10⁻¹⁰ or less, which puts its best point within 10⁻⁵ of the known minimum (10⁻⁴ for Rosenbrock’s function). The exception is 3 of the 20 Rosenbrock runs, which end in that function’s known local minimum instead. An evaluation is one call of your model: here, one flight. Over the 20 seeds, the median number of evaluations is within 25% of pycma’s, the method’s author’s own Python implementation run from the same starts. That 25% is the test’s bound; measured, they are within 5%. Twelve generations of a three-variable run are also recomputed by a separate implementation of the published formulas, and agree to rounding (tests/optimize.rs). A run is repeated bit for bit from its seed (a_seed_fixes_the_run in optimize/cmaes.rs).
• Checked by re-flying: the design each of the first two examples finds is flown again from scratch, and again with the flight’s numerical integration 100 times stricter (tolerances). Both reach apogee within 0.1 m of 3,048 m (the first example’s within 2 mm, measured).
• Limits (a minimum stability margin, say): held to three test problems whose answers on their limits are known exactly, from 20 seeds each, to 10⁻¹⁰ (tests/constrained.rs). The second example’s winner is flown again and keeps its margin limits over the whole ascent and its rail-exit limit.
• Choices (which motor, which catalog part): held to three test functions mixing continuous and whole-number variables, at two sizes, from 20 seeds each. Every run reaches the known minimum, with every whole number exactly right, and the median evaluations are within 25% of an outside implementation’s (the test’s bound; measured, within 5%; tests/mixed.rs). The second example chooses a motor and a nose cone that hit 3,048 m, checked by flying them again (Choices). It finds a design that does; it doesn’t promise the best of several that would.
• Trade-offs between goals (a Pareto front): NSGA-II is held to three test problems whose fronts are known exactly, from 20 seeds each, and to pymoo, an outside implementation run with the same settings. Every run’s front lies within twice pymoo’s worst distance from the true front (the test’s bound). At the median, hpr-sim’s fronts lie 1% to 8% closer to the true front than pymoo’s, and cover it as evenly, within 3% (the test allows a factor of 1.25 either way; Trade-offs). The third example’s front designs are flown again and give the same apogee and margin to the bit: that shows the result repeats, not that it is right. At 2.5 calibres the front is within 0.5% of the apogee CMA-ES finds alone (the example’s check).
• Few evaluations (EGO): from 20 seeds each, two standard test functions with several local minima, Branin’s (two variables) and Hartmann’s (three), end within 1% of their known minima in 50 evaluations (the test’s bound; measured, within 0.12%). Hartmann’s six-variable function needs its values transformed first, as the method’s authors did: then all 20 runs end within 1% in 250 evaluations (measured, within 0.29%), against 6 of 20 without. That check takes minutes in a release build, so the local gate runs it, not CI (Few evaluations).
• Left out, for now: optimizing a Monte Carlo run’s statistics, EGO beyond six variables, and a rule that stops NSGA-II when its front has settled (it runs the generations it is given). They are the next steps of M6.2, the optimization milestone. There is no command-line or Python front end yet.

What the optimizer does

The optimizer changes variables: numbers in the design, such as a ballast mass or a body length (Variable). For each variable you give three things:

• a start, the value to begin from;
• a step, how far to try from the start at first, about a quarter to a third of the range you expect the answer in;
• optional bounds, the range the variable must stay in.

It minimizes one number your model returns. To maximize something, minimize its negative. To hit a target, minimize the squared miss: (apogee − 3,048 m)² is smallest, zero, on the target.

How CMA-ES searches

CMA-ES is the covariance matrix adaptation evolution strategy, N. Hansen’s method (“The CMA Evolution Strategy: A Tutorial”, arXiv:1604.00772, 2023). It keeps a cloud of likely designs, shaped like a stretched, tilted ball (a normal distribution), and repeats four steps each generation:

1. Sample. Draw a handful of designs from the cloud: λ = 4 + ⌊3 ln n⌋ of them for n variables, so 6 for two variables and 10 for ten.
2. Rank. Fly each one and sort them by the number to minimize. Only the order matters, not the values.
3. Move. Move the cloud’s center to a weighted average of the better half, the best weighted most.
4. Learn. Stretch and tilt the cloud toward the directions the good designs lay in. Widen it when successive moves go the same way, which means the steps are too short, and shrink it when they cancel out, which means the steps overshoot.

So the cloud learns the problem’s shape. If the apogee depends far more on one variable than on another, or on a combination of them, the cloud stretches to match. No derivatives are needed, which suits flights: their outputs wobble slightly in the last digits as the integrator’s steps change, which would spoil a slope.

The formulas and default settings are the tutorial’s (Appendix A and Table 1). Table 1 also gives the worse half of each generation negative weights, which push the cloud away from them: the active variant. hpr-sim gives them zero weight, as the tutorial’s own code does.

The cloud is shaped in each variable divided by its step, so variables in meters and in kilograms start on an equal footing, as the tutorial advises. hpr_analysis::optimize::cmaes lists every equation.

Bounds

A sampled design outside a variable’s bounds is thrown away and drawn again, the tutorial’s simplest way of handling bounds. It works well while the answer lies inside the range. If it lies on a bound, the run slows down near it. If any one design of a generation is still outside after 1,000 tries, the run stops and says so. With many variables near their bounds this comes soon: each such variable halves the chance that a draw falls inside.

When a run stops

A run stops at the first of these (Stop):

Both tolerances can be changed or turned off (with_tolerance_x, with_tolerance_value).

The result (Optimum) gives the best design found, its value, how many evaluations the run made, and why it stopped. If every design so far failed (your model returned infinity for each), the value is infinite: check it before using the design.

Checked against

Four test functions from CMA-ES’s authors (N. Hansen, S. D. Müller and P. Koumoutsakos, Evolutionary Computation 11(1), 2003, Table 1), each with ten variables (hpr_analysis::optimize::benchmark):

Each run starts with every variable at 1 (at 0 for Rosenbrock’s function) and steps of 0.5, and goes until the value is 10⁻¹⁰ or less, the stopping value of the 2003 paper. The tests in tests/optimize.rs run each function from 20 seeds and check:

• Every sphere and ellipsoid run reaches the minimum, which puts its best point within 10⁻⁵ of x = 0.
• 17 of 20 Rosenbrock runs reach the minimum at x = 1. The other 3 end in the function’s local minimum near (−1, 1, …, 1). The test requires at least 17. CMA-ES’s authors note that local minimum, and report 1 to 3 runs of 20 missing the global one at 4 to 16 variables (Kern, Hansen and Koumoutsakos, 2006). pycma ends in the local minimum in 1 of 20. Measured once over seeds 1 to 300, hpr-sim reaches the global minimum in 290 (97%), so 17 of 20 is at the low end of what chance gives.
• The median number of evaluations is within 25% of pycma’s from the same starts (the test’s bound). Measured, they are within 5%:

• Tilting the ellipsoid changes the count by under 10%: the cloud learns the tilt.
• Every generation’s mean, cloud size and shape, over twelve generations with steps that differ 200-fold, match a second, separate implementation of the tutorial’s formulas to rounding. It takes the cloud’s inverse square root by a different method (the Denman–Beavers iteration), and passes through both branches of the step that pauses the shape’s learning when the cloud grows fast.
• The default settings that pycma also takes from the tutorial’s Table 1 match its values to rounding. pycma departs from the table in a few places by its author’s choice, such as how fast the cloud’s size adapts. That is why the counts differ a little.

The tests catch real faults. Without the step that learns the cloud’s shape from a generation’s better half (the rank-μ update, μ being the size of that half), the ellipsoid takes a third more evaluations (7,875) and the pycma comparison fails. A reviewer found three faults the pycma comparison misses: the shape’s learning never paused, the pause’s test off by one generation, and the mean’s step not scaled back to the variable’s units. Each fails the second implementation’s check. These were one-off checks, recorded in ADR-138 (the decision record for this work), not run in CI.

pycma is run by validation/oracles/cmaes/pycma_runs.py, whose results are committed beside the test.

An example

The example program crates/hpr/examples/optimization.rs runs CMA-ES on three of the test functions. Then it takes a 66 mm rocket on a J760, starting from a 3 m rail at 85° into 5 m/s of wind. It finds the nose ballast and body tube length that give it two things at once: an apogee of 3,048 m above the pad, and a static margin of 2.20 calibres at launch mass (at Mach 0.3). Run it from a copy of the repository with:

cargo run --example optimization -p hpr

Why two goals? With one goal, the apogee, and two variables, there is a whole curve of answers: more ballast and a shorter body cancel out, and the run would stop at whichever hit it reached first. A second goal, the margin, leaves one design that meets both, so the answer is the rocket’s, not the run’s.

The heart of it, abridged from the example:

let variables = vec![
    Variable::new("nose ballast (kg)", 0.3, 0.15)?.within(0.0, 1.0)?,
    Variable::new("body tube (m)", 1.0, 0.1)?.within(0.6, 1.4)?,
];
let optimizer = Cmaes::new(variables)?
    .with_target(1e-4)?            // stop within a centimeter and a ten-thousandth of a calibre
    .with_max_evaluations(2_000)?;
let optimum = optimizer.minimize(seed, |x| {
    // (apogee miss in m)² + (margin miss in hundredths of a calibre)²;
    // a design the simulator refuses ranks last
    miss(x[0], x[1], FlightSettings::default()).unwrap_or(f64::INFINITY)
})?;

miss builds the rocket with that ballast and body length, flies it, and adds the two squared misses, each in a unit that makes a miss of one about equally bad. A design that can’t fly returns infinity, which ranks below every real flight. Then the example flies the winner twice more: once from a fresh build, which must give the optimizer’s result to the last bit, and once with the integrator’s tolerances 100 times tighter, which must still reach apogee within 0.1 m of 3,048 m.

The example prints whether each test function reached its minimum, not how many evaluations it took. Operating systems round the last bit of ln and exp differently, and an optimizer’s path amplifies that, so the counts move by a few per cent between macOS, Linux and Windows. The medians above are the test’s, on the development machine. It prints:

CMA-ES on three test functions, 10 variables from 1.0, run to f ≤ 1e-10 (seed 2026)
function             reached f ≤ 1e-10   best point within 1e-5 of x = 0
sphere                             yes                               yes
ellipsoid                          yes                               yes
rotated ellipsoid                  yes                               yes

A 66 mm rocket on a J760: find the nose ballast and body length for a 3,048 m apogee
and a static margin of 2.20 calibres at launch mass, at Mach 0.3
Not yet validated: see the Accuracy page before trusting these numbers.
Start: 0.30 kg of ballast, a 1.00 m body: apogee 3128.8 m, margin 1.79 calibres
Found: 0.34 kg of ballast, a 1.11 m body (stopped: Target)
Flown again: apogee 3048.0 m, margin 2.20 calibres
Flown again, tolerances 100 times tighter: apogee 3048.0 m

The rocket started 81 m too high, with a margin of 1.79 calibres. The optimizer found the design in 300 flights on the development machine, about 50 generations. Flown again with tighter tolerances, its apogee moves by 1.4 mm. Limits on other things, such as the rail-exit speed, are the subject of Limits on a design, and the second example uses them.

Evaluating designs your own way

minimize flies one design after another. To fly a generation’s designs on several threads or machines, use the run’s steps yourself (Run): Cmaes::start draws the first generation, candidates lists its designs, and tell takes their values, in the same order, and draws the next. It returns the result once the run stops.

Choosing the numbers

• Steps: about a quarter to a third of the range the answer is likely in, in the variable’s own units. Steps of very different sizes are fine: the run works in each variable divided by its step.
• Target: for a target apogee, the squared miss you accept: 0.1 * 0.1 for 0.1 m. Without a target, a run goes on until it converges, which can take many more flights than a hit needs.
• Evaluations: a cap on flights, 10,000 by default. The first example’s two variables needed 300 flights, the second example’s four variables 360; the ten-variable test functions take 1,600 to 6,500 evaluations to converge.
• Population: leave it at the default unless the output has many local minima. Then a larger population (Cmaes::with_population) searches more widely, at more flights per generation.
• Seed: a different seed gives a different run. Rerun with two or three seeds if the answer matters: if they agree, the answer is not luck.
• NSGA-II’s population and generations: the number of flights is the population times the generations. The defaults, 100 designs for 250 generations, are 25,000 flights, sized for 30 variables; the third example’s two variables needed 20 designs for 25 generations, 500 flights, to pass its 0.5% check. The population is also how many designs the front can hold. Compare the fronts from two seeds before trusting one.

Limits on a design

A design usually has limits as well as a goal: a stability margin of at least 1.5 calibres, say, or at least 15 m/s off the rail. The optimizer takes them as constraints, each written as a number g that must not be above zero. A margin of at least 1.5 calibres is g = 1.5 − margin. Your model returns an Evaluation: the value, and the violation, the sum of every g that is above zero. Evaluation::constrained(value, &[g1, g2]) adds them up for you.

Candidates are ranked by K. Deb’s feasibility rules (ADR-139, from Deb’s 2000 paper):

No penalty weight is needed, because a value is never weighed against a violation. Do scale the limits so that they count alike: a margin 0.1 calibre short and a rail speed 0.1 m/s short are not equally bad, so divide each g by a size you care about (the 1.5 calibres, the 15 m/s).

Candidates that break a limit are kept and ranked, not redrawn, so a run can close in on an answer that sits right on a limit, as most good designs do. Only a point that keeps every limit counts as reaching a target; the Optimum reports its violation, zero when it keeps them all. For a bound that the answer will sit on, leave the variable unbounded on that side and write the bound as a limit; clamp the value you fly (no negative ballast), and work the limit out from the unclamped one. A design that can’t be flown at all returns Evaluation::failed(), which ranks behind every other, and a run that never keeps every limit says so: its violation is above zero.

The tests hold this to three problems whose answers on their limits are known exactly:

From each of 20 seeds the run reaches the answer to 10⁻¹⁰ of its size and to within 10⁻⁴ of the point, also when it starts where the limit is broken. The next section’s example puts limits on a rocket: its stability margin and its speed off the rail.

Choices: a motor, a catalog part

Some variables are choices from a list rather than amounts: which motor, which nose cone from a maker’s catalog. Make each one an integer variable (Variable::integer). It takes only the whole numbers from its low bound to its high one, and your model uses the number as a place in your list: 0 for the first motor, 1 for the second, and so on.

The optimizer still draws a real number for the variable, and gives your model the nearest whole number. Left at that, the cloud would shrink in that variable until every draw rounded to the same number, and the choice would freeze, even with a better one next to it. CMA-ES with margin (R. Hamano, S. Saito, M. Nomura and S. Shirakawa, GECCO 2022, arXiv:2205.13482) prevents that. After each generation it keeps at least a small chance, the margin (nothing to do with a stability margin), that a draw lands on another value. It does so by moving the cloud’s center towards the edge between two values, or by widening the cloud in that variable. The margin is 1/(n λ), for n variables and λ designs a generation: 1 in 32 for the example below. So a choice is never final: its neighbours keep being tried.

Put the list in an order where neighbours are alike, such as motors by total impulse. The optimizer steps between neighbouring numbers, so in that order a step up means a little more motor. A list in no order still works, but the search has less to go on.

The example

The example program crates/hpr/examples/motor_and_nose.rs builds a 2.6 in rocket from Madcow Rocketry’s parts in the built-in catalog: a 1.0 m fiberglass body tube, an 18 in motor tube and three fiberglass fins. It flies it from a 3 m rail at 85° into 5 m/s of wind. The optimizer chooses four things:

The goal is the squared miss from 3,048 m. The limits come from the International Rocket Engineering Competition’s rules (its Design, Test & Evaluation Guide, 2025), and hold over the whole ascent, from the rail exit to apogee (§10.3.1 says “from launch”; on the rail, the rail holds the rocket):

• a stability margin of at least 1.5 calibres in flight (§10.3.1 asks for a “dynamic” margin; the example takes the flight margin, the margin at the flight’s own Mach number, as the flight metrics define it);
• a static margin, the one at Mach 0, of at most 4 calibres, and a flight margin of at most 6, so the rocket isn’t over-stable (§10.4.1);
• at least 30 m/s off the rail (§10.2.1).

The margins change through the flight: the center of mass moves forward as the motor burns, so the margin grows, and the flight margin changes with speed as well. For the lower limit the example uses the least flight margin of the ascent, which the flight finds inside its steps, not only at their ends. For the upper limits it uses the largest static and flight margins seen at the end of each integration step. The static margin only grows during the burn and stays put after it, so its largest is exact. A peak of the flight margin between two step ends could be missed; the winner’s largest, 4.83 calibres, is well under its limit of 6.

The heart of it, abridged from the example. A choice is an integer variable: set its bounds with within, then mark it integer, and use the whole number your model is given as a place in your list. With limits, use the run’s steps yourself (Run) and give tell_constrained an Evaluation per design:

let variables = vec![
    Variable::new("motor", 2.0, 1.0)?.within(0.0, 4.0)?.integer()?, // a place in the motor list
    Variable::new("nose", 1.0, 1.0)?.within(0.0, 3.0)?.integer()?,  // a place in the nose list
    Variable::new("nose ballast (kg)", 0.4, 0.15)?.within(0.0, 1.5)?,
    Variable::new("fin span (m)", 0.07, 0.015)?.within(0.03, 0.15)?,
];
let mut run = Cmaes::new(variables)?.with_target(1e-4)?.with_max_evaluations(3_000)?.start(seed)?;
let optimum = loop {
    let mut evaluations = Vec::new();
    for x in run.candidates() {
        // x[0] and x[1] are whole numbers within their bounds
        let (motor, nose) = (x[0] as usize, x[1] as usize);
        let design = Design { nose, ballast_kg: x[2], fin_span_m: x[3] };
        evaluations.push(match flyer.fly(&motors[motor], &design) {
            Ok(flown) => {
                let miss = flown.apogee_m - 3048.0;
                Evaluation::constrained(miss * miss, &flown.limits()) // each limit g ≤ 0
            }
            Err(_) => Evaluation::failed(), // a design that can't fly ranks last
        });
    }
    if let Some(optimum) = run.tell_constrained(&evaluations)? {
        break optimum;
    }
};

Design, Flyer::fly and limits are the example’s own: they build the rocket, fly it, and write each limit as a number g that must not be above zero, as Limits on a design describes. A draw for an integer variable outside its bounds is clamped to the nearest end, not drawn again. Run it from a copy of the repository with:

cargo run --example motor_and_nose -p hpr

It takes about half a minute in a debug build. It prints:

A 2.6 in rocket of Madcow Rocketry's parts: choose the motor, the nose cone, the nose
ballast and the fin span for a 3,048 m apogee, with margins over the ascent of at
least 1.5 calibres (flight), at most 4 (static) and 6 (flight), and at least 30 m/s off a 3 m rail
Not yet validated: see the Accuracy page before trusting these numbers.
motor    total impulse (N·s)   designs flown   nearest apogee within the limits
J450DM                1061.6               3   2648 m
J300LR                1212.8               6   none
J760                  1267.3              25   3057 m
K400C                 1307.3             307   3048 m
K940                  1636.1              19   3150 m
Found: the K400C with the PNC26K-W nose (3:1 ogive, plastic), 0.35 kg of ballast, fins 8.9 cm in span
(stopped: Target, after 360 flights)
Flown again: apogee 3048.0 m, top speed Mach 1.23, rail exit 33.8 m/s, liftoff mass 2.60 kg;
margins over the ascent: flight 3.04 to 4.83 calibres, static at most 3.88
Flown again, tolerances 100 times tighter: apogee 3048.0 m, rail exit 33.8 m/s
Both flights within 0.1 m of 3,048 m and within every limit: yes

The table counts the designs the run flew with each motor; the total impulse is from the motor’s thrust curve. The last column is the apogee nearest 3,048 m among the designs that kept every limit. The run tried every motor. Its few J450DM designs that kept the limits fell well short. None of its J300LR designs kept them all. It settled on the K400C and stopped once it was within a centimeter of the target. Flown again, with the integrator’s tolerances as set and then 100 times tighter, the winner is within 0.1 m of 3,048 m, and keeps every limit over the whole ascent.

Read the table as what this one run saw, not as what each motor can do: a few designs, or a few dozen, say little about a motor. The answer is not unique. A scan of every motor and nose over the ballast and the fin span, run once on the development machine and not kept, found that the J760, the K400C and the K940 can each hit 3,048 m within the limits, with any of the four noses. A hit with any of them scores the same, so another seed may well settle on another. To prefer one, say so in the goal. A small cost for liftoff mass is one way.

Unlike the first example’s counts, this run’s come out the same on all three operating systems: CI checks the output on macOS, Linux and Windows, whose last bits of ln and exp differ. On the development machine the run was also tried with every flight perturbed (the integrator’s tolerance changed by up to 1%) and with the step size moved by a few bits each generation, and neither changed a line of the output; those trials are not kept. Your own runs repeat bit for bit on one machine from the same seed, but on another machine a run can take another path.

A goal that changes only when the choice changes, such as “the smallest motor that can do it”, gives the search nothing to follow between choices. For that question, run the optimizer once for each motor, the motor fixed, and compare. The continuous search then only has to find a design that keeps the limits.

The body tube’s length is fixed on purpose. Past Mach 1.2 a flight needs a table of the body’s supersonic pressures, which takes a fifth of a second or more to build. Designs with the same outside shape can share one table, so with the length fixed the example builds at most three, one per fiberglass nose cone (the next paragraph says why the plastic one has none). With the length a variable, every design would build its own, and the run would take minutes. The example shows how to share the table, in its Flyer::fly.

The winning plastic nose cone gets no table at all. The catalog lists it 0.05 mm narrower than the tube (2.638 in against 2.640 in), and the method behind the table doesn’t yet take a step in the body’s outline larger than a millionth of its area (issue #87). So for the short stretch of its flight past Mach 1.2 (its top speed is Mach 1.23) hpr-sim falls back on slender-body theory for the body’s normal force, its lift at an angle (Bodies faster than sound). How much that moves the apogee hasn’t been measured; the flight spends only a moment above Mach 1.2.

Checked against

Three test functions of Hamano and co-authors (§5.1 of their paper), each with half its variables continuous and half whole numbers (benchmark::mixed):

Each runs with 10 and with 20 variables, from 20 seeds, to a value of 10⁻¹⁰. The starts and settings are those of validation/oracles/cmawm/cmawm_runs.py, which runs the same functions with cmaes 0.13.1, an outside implementation (MIT) adapted from the method’s authors’ code, with its active weights off as hpr-sim’s are. Every run of every case reaches the minimum, with each whole number exactly right. The median evaluations are within the test’s 25% of the outside implementation’s, and measured within 5%:

A unit test checks the margin itself after every generation of a mixed run, with each kind of whole-number variable (integer_draws_keep_the_margin in optimize/cmaes.rs). Another sets up a run’s state by hand and checks one correction of each kind against the paper’s equations worked out to 40 digits (margin_correction_matches_the_equations). With the margin taken out, three of the six cases fail: some runs stall with a whole number stuck on a wrong value. That was a one-off check, recorded in ADR-140, not run in CI.

Trade-offs: a Pareto front

Often two goals pull against each other. Bigger fins or more nose weight make a rocket more stable, and both cost apogee. There is no single best design then. Instead there is a set of designs, none of which can improve one goal without giving up some of the other: the Pareto front. A design dominates another when it is no worse in either goal and better in at least one; the front is the designs nothing dominates. Knowing the front shows what each extra calibre of stability costs, before you pick one design from it.

CMA-ES finds one design. For a front, hpr-sim has NSGA-II, a genetic algorithm by K. Deb and co-authors (2002). It keeps a population of designs and, each generation:

1. breeds as many children as there are parents. Each pair of parents is chosen by two tournaments: of two designs picked at random, the one on a better front wins, or, on the same front, the one further from its neighbours (its crowding distance: the gaps between its two neighbours’ values of each goal, each as a share of that goal’s range in the front, added up). Every design plays two tournaments a generation. A pair’s children mix their parents’ values (crossover), then a few values are nudged at random (mutation);
2. flies the children;
3. sorts parents and children together into fronts: the designs nothing dominates, then those only the first front dominates, and so on;
4. keeps the best half, front by front. The front that doesn’t fit whole keeps its designs with the most room around them, so the front stays spread out instead of bunching up.

Each variable needs a low and a high bound: the first generation is drawn evenly between them, and the variable’s start and step are not used. The defaults are the paper’s: 100 designs, 250 generations, crossover of 90% of pairs and mutation of one variable in n, the number of variables, on average (Nsga2). NSGA-II makes every goal as small as it can; to maximize one, give its negative. It runs the generations it is given and has no test of when the front has settled: run it again from a second seed, or for more generations, and compare the fronts. Limits work as they do for CMA-ES: Goals::constrained takes each limit as a number g ≤ 0, and a design that keeps every limit beats one that doesn’t. A design that can’t be flown is Goals::failed, behind every other.

The example

The example program crates/hpr/examples/pareto_front.rs takes the 66 mm rocket on a J760 from An example, with its body fixed at 1.0 m. It varies two things, the nose ballast (0 to 0.8 kg) and the fins’ span (4 to 10 cm), for two goals: the highest apogee, and the largest static margin at launch mass, at Mach 0.3. Every design must keep at least 1.5 calibres. The heart of it, abridged:

let variables = vec![
    // A start and step are required by `Variable`; NSGA-II uses only the bounds.
    Variable::new("nose ballast (kg)", 0.3, 0.15)?.within(0.0, 0.8)?,
    Variable::new("fin span (m)", 0.06, 0.015)?.within(0.04, 0.10)?,
];
let optimizer = Nsga2::new(variables, 2)?.with_population(20)?.with_generations(25)?;
let front = optimizer.minimize_constrained(seed, |x| match flyer.design(x[0], x[1]) {
    // Both goals as large as they can be: their negatives as small.
    Ok((apogee, margin)) => Goals::constrained(vec![-apogee, -margin], &[1.5 - margin]),
    Err(_) => Goals::failed(), // a design that can't fly ranks last
})?;
for member in &front.members {
    // member.point: ballast and span; member.objectives: −apogee and −margin
}

flyer.design is the example’s own: it builds the rocket, works out its margin and flies it. Run it from a copy of the repository with:

cargo run --example pareto_front -p hpr

It takes about a minute in a debug build. It prints:

A 66 mm rocket on a J760: how much apogee each calibre of static margin costs, over
its nose ballast (0 to 0.8 kg) and fin span (4 to 10 cm), with a margin of at least
1.5 calibres at launch mass, at Mach 0.3
Not yet validated: see the Accuracy page before trusting these numbers.
NSGA-II: 20 designs a generation, 25 generations, 500 flights (seed 2026)
The front: 20 designs, each flown again to the same apogee and margin

margin (cal)   apogee on the front (m), interpolated between the two designs either side
         2.0       3100
         2.5       3050
         3.0       2990
         3.5       2940

At 2.5 calibres, CMA-ES alone (200 flights): apogee 3050 m; the front within 0.5%: yes

Between 2 and 3.5 calibres, each extra half calibre of margin costs this rocket 50 to 60 m of apogee. Each apogee in the table is interpolated in a straight line between the two front designs whose margins bracket it. Two checks back the front up:

• Every one of its 20 designs is flown again from a fresh build and gives the same apogee and margin to the last bit. That shows the result repeats; it doesn’t show it is right.
• At 2.5 calibres, CMA-ES alone, told to find the highest apogee with at least that margin, gets the same 3,050 m (to the nearest 10 m) in 200 flights: the front is within 0.5% of it, the example’s check.

How much that depends on the seed was measured once, on the development machine, and isn’t checked in CI. From each of the 26 seeds 2020 to 2045, the front came within the 0.5%, from 0.46% below CMA-ES’s apogee to 0.18% above (CMA-ES’s own answer in 200 flights varies by 0.24% over those seeds). An earlier version of the example missed the check: with 20 designs for 12 generations its front fell 0.66% short, and the generations were raised to 25. (Before that, 24 designs over wider ranges spread the front from 1.5 to 5.3 calibres, too thinly, and the ranges were narrowed.) The 0.5% was not changed (ADR-141).

Checked against

Three test problems of E. Zitzler, K. Deb and L. Thiele (2000), with 30 variables from 0 to 1 each, whose fronts are known exactly (benchmark::zdt):

Each is run from 20 seeds with the paper’s settings: 100 designs for 250 generations, 25,000 evaluations. Two numbers measure a run’s front against the true one:

• the generational distance (GD): the mean, over the front’s designs, of each one’s distance to the true front. Small when the front lies on the true one.
• the inverted generational distance (IGD): the mean, over points spread along the true front, of each one’s distance to the nearest design. Small only if the front also covers all of the true one, evenly. The points are at 1,000 evenly spaced f₁; on ZDT3, the 265 of them that fall on its pieces.

hpr-sim measures GD to the true front’s curve itself, not to points along it. The same problems are run with pymoo 0.6.2, an outside implementation (Apache-2.0) by J. Blank and K. Deb, set up as the paper describes, from seeds 1 to 20 (pymoo_runs.py). Both sets of columns below are scored by hpr-sim’s measures; the pymoo columns are pymoo’s fronts. The rules were set from pymoo’s runs before hpr-sim’s were measured: every hpr-sim run within twice pymoo’s worst, and hpr-sim’s median at most 25% above pymoo’s, the margin CMA-ES’s tests allow against pycma. Review of the first results added a second rule: the median at most 20% below pymoo’s, a factor of 1.25 either way. On these problems every variable but the first is best at its lower bound, and an optimizer that drifts toward its bounds would score better than pymoo without being better. Measured:

At the median, hpr-sim’s fronts lie 1% to 8% closer to the true front than pymoo’s, and cover it as evenly (IGD 1.3% to 2.3% smaller). Each problem’s worst hpr-sim run is 1.9 to 2.1 times inside its bound. The worst ZDT3 run of each has an IGD six times its median: it missed part of the front, a known hazard on a front in pieces. The per-run bound on ZDT3’s IGD is loose for the same reason, set by pymoo’s one such run; the median rule is what holds ZDT3’s coverage. These come from cargo test -p hpr-analysis --test nsga2 -- --nocapture (tests/nsga2.rs). The same test checks hpr-sim’s generational_distance against pymoo’s own, on pymoo’s fronts and 500 reference points, to 10⁻¹².

Deb and co-authors’ own runs (their Table II) report a mean distance of 0.033, 0.072 and 0.115 on these three problems, measured to 500 points of the true front: 18 to 87 times pymoo’s mean here, to the same 500 points (0.0013 to 0.0019). Why the paper’s are so much larger was not investigated.

Unit tests check the pieces by hand (optimize/nsga2.rs):

• fronts and crowding distances of small sets worked out on paper;
• that crossover spreads children by the distribution its authors give, far from a bound and cut at one, and mutation steps likewise, cut at each side’s bound, each within five standard errors over 100,000 draws; and that crossover’s two children come out in either order;
• that children never leave a variable’s bounds, nor pile up on them;
• that a failed design, or one breaking a limit, ranks behind every design that keeps them.

ZDT3’s five pieces were solved to 40 digits and are checked against the equations that define their ends (benchmark.rs). They agree with pymoo’s to its ten digits, except where pymoo prints the second piece’s start as 0.182228780, a digit short of 0.1822287280.

Few evaluations: EGO

CMA-ES and NSGA-II spend hundreds of flights. That is fine when a flight takes a tenth of a second, but not when one evaluation is a long Monte Carlo run, or a slow outside program. EGO (efficient global optimization; D. R. Jones, M. Schonlau and W. J. Welch, 1998), a form of Bayesian optimization, is built for that case. It spends its effort thinking between evaluations, so it needs only tens of them.

It works like this:

1. It evaluates an initial design: 10 points per variable, spread evenly over the box the variables’ bounds make. The design is a Latin hypercube: each variable’s range is cut into as many equal slices as there are points, and each slice gets one point.
2. It fits a surrogate: a smooth guess at the model, drawn through every point evaluated so far. The surrogate is kriging (a Gaussian process). Besides its guess ŷ at any point, it gives a standard error s: zero at the points already evaluated, and growing away from them.
3. It asks where an evaluation is most worth making. The expected improvement at a point is the average amount by which an evaluation there would beat the best value so far, outcomes that don’t beat it counting as zero. It is large where the guess is low, and where the guess is unsure.
4. It evaluates the point of largest expected improvement, refits, and repeats.

Each variable needs a low and a high bound, as for NSGA-II; its start and step are not used. By default a run stops after 20 evaluations per variable. Ego::with_max_evaluations sets the budget, Ego::with_target stops at a good enough value, and Ego::with_tolerance_improvement stops once no point is expected to gain more than a set amount, in the model’s units (with a transform, below, in the transformed units); it is off by default. Jones and co-authors stop at 1% of the best value’s size. That can end a run well short of 1% from the minimum: on Hartmann’s three-variable function, 8 of 20 runs (seeds 1 to 20) stopped more than 1% away, the worst 4.7% (a reviewer’s measurement). Use a smaller amount (the paper suggests 0.1%) where it matters. It never fires for a goal near zero (a miss): there, give an amount. A model that fails at a design returns +∞; EGO fits it as the worst value so far and goes on.

A worked example, on Branin’s function of two variables: its least value is 5/(4π) ≈ 0.397887, at three points. The initial design is 20 points, and 30 more follow. The 1 is the seed; a variable’s start and step are required by Variable::new but EGO doesn’t use them. This is the example on Ego’s API page, which runs as a test from seed 1; tests/ego.rs runs seeds 1 to 20:

use hpr_analysis::optimize::Variable;
use hpr_analysis::optimize::benchmark::global::{BRANIN_MINIMUM, branin};
use hpr_analysis::optimize::ego::Ego;

let variables = vec![
    Variable::new("x0", 2.5, 3.0)?.within(-5.0, 10.0)?,
    Variable::new("x1", 7.5, 3.0)?.within(0.0, 15.0)?,
];
let optimum = Ego::new(variables)?.with_max_evaluations(50)?.minimize(1, branin)?;
assert_eq!(optimum.evaluations, 50);
assert!(optimum.value < 1.01 * BRANIN_MINIMUM);

Transforming the values

The surrogate assumes the model varies about as much everywhere. Some models don’t: Hartmann’s six-variable function is nearly flat at values near zero over most of its box, then drops into narrow wells, the deepest at −3.32237. Fitted to the raw values, the surrogate misjudges how deep an unexplored well could be, and EGO settles in the second-deepest, near −3.20.

Jones and co-authors meet this by fitting the surrogate to a transformation of the values, chosen by checking how well the fit predicts points left out of it. They “typically try the log transformation, ln(y), or the inverse transformation, −1/y” (§3, p. 468). On their test functions this chose ln y for Goldstein and Price’s function and −ln(−y) for Hartmann’s six-variable function (§4.2, p. 474). Ego::with_transform offers the two log transformations:

• Transform::Log, z = ln y, for a model whose values are all positive;
• Transform::NegativeLog, z = −ln(−y), for one whose values are all negative.

Both rise with y, so the least z is at the least y. The surrogate, its guess and the expected improvement are all on the z scale, as in the paper; the best point, a target and the result stay in the model’s units. −ln(−y) turns −3.32 into −1.20 and −0.01 into 4.6: it pulls the deep wells close together and pushes the near-zero plateau far out, so the wells no longer look like narrow spikes against a flat floor. Jones and co-authors chose it after checking the fit (§4.2) and give no deeper reason; neither does hpr-sim. A value outside the transform’s range (zero or positive under −ln(−y)) is an error, not something to fit. hpr-sim doesn’t choose a transform for you: it runs none of the paper’s checks of the fit.

A worked example: Hartmann’s six-variable function from seed 10, in 100 evaluations, the initial design’s 60 included. Its second-lowest minimum is −3.20316, a well 3.6% above the deepest one. With the transform, the run’s best value is −3.30740 on macOS, 0.45% above the minimum, so it found the deepest well. Without it, the same seed ends at −3.20245, inside the shallower well. How close the run gets inside the deepest well depends on the computer: the same run ended 1.01% above the minimum on Linux and 1.47% on Windows, as a seeded run magnifies the last-bit differences between their maths libraries (most likely; Rust’s arithmetic is the same on all three). So the test in tests/ego.rs checks only which well the run ends in, a value below −3.2032, and accepts any run up to 3.59% above the minimum:

use hpr_analysis::optimize::benchmark::global::hartmann6;
use hpr_analysis::optimize::ego::{Ego, Transform};

// `variables`: six, each within [0, 1].
let optimum = Ego::new(variables)?
    .with_max_evaluations(100)?
    .with_transform(Transform::NegativeLog)
    .minimize(10, hartmann6)?;
assert!(optimum.value < -3.2032); // below the second-lowest minimum

Checked against

tests/ego.rs runs EGO from seeds 1 to 20 on two test functions: Branin’s, with three minima of one value, and Hartmann’s, with local minima above its least. The rule is Jones and co-authors’ measure of success: the best value within 1% of the minimum’s size. The budget was set from a probe on seeds 1 to 10 at 40 evaluations, where Branin’s worst run missed by 1.03%; at 50 the 20 seeds gave the gaps below (macOS debug build; print them with cargo test -p hpr-analysis --test ego -- --nocapture).

Branin’s minimum is exact. Hartmann’s is the value printed to six figures, and the test checks it by polishing with CMA-ES from the printed point. Unit tests in optimize/ego.rs check that the surrogate passes through its points, its fit, guess and standard error on three points against the formulas worked by hand, the expected improvement’s limits, and that the initial design fills every slice. Unlike CMA-ES and NSGA-II, EGO isn’t compared with an outside implementation: the minima are known exactly, which is what the milestone asks for.

Hartmann’s six-variable function is held to the same rule with the −ln(−y) transform, from seeds 1 to 20, in a program of its own, benches/ego_hartmann6.rs (cargo bench -p hpr-analysis --bench ego_hartmann6). Every run ended within 1%; the last to get there did so at evaluation 205, so the budget of 250 was set from these same runs, with 45 to spare. Jones and co-authors needed 121 evaluations from one run, with an initial design of 65 points and an exact search for the largest expected improvement. Without the transform, 14 of the same 20 runs ended at the local minimum near −3.20 after 250 evaluations, 3.6% to 3.7% above the minimum; the 6 that found the deepest well got within 1% by evaluation 78 in 5 of them and at 241 in the sixth, so the transform is the more reliable route, not always the faster one. The budget of 250 was set from these same 20 seeds, so treat the 20 of 20 as in-sample.

The 20 runs take about 3 minutes spread over 10 cores in a release build. CI’s tests use a debug build, about 20 times slower, where they would take hours. So the local gate runs the program whenever EGO’s code changes (scripts/gate.sh ego), and CI runs only the one-seed example above, with and without the transform. The program’s numbers are from macOS; the debug and release builds gave the same runs bit for bit there. Nobody has run the 20 on Linux or Windows: a run there may end further from the minimum, or even in the shallower well, 3.6% away. The one-seed example’s spread above (0.45% to 1.47%) shows that runs move; it doesn’t bound how far. EGO takes no limits, whole-number variables or noisy outputs yet (ADR-142; the transform: ADR-152).

Left out

• A choice is a whole number in a list you order. There is no separate handling for choices with no order, beyond putting alike ones next to each other.
• Limits are inequalities only. For an equality h = 0, write |h| − ε ≤ 0 with a small ε.
• NSGA-II takes only continuous variables with two bounds: no choices from a list yet. It runs the generations it is given, with no test of when its front has settled.
• EGO is checked on two, three and six variables only. It doesn’t choose a transform of the values for you (the paper checks the fit to choose one), and offers no −1/y. It takes no limits, whole-number variables or noisy outputs.
• No optimizing of a Monte Carlo run’s statistics, such as the chance of landing within a distance.
• No command-line or Python front end yet.

The API reference is hpr_analysis::optimize.

The command line

hpr is hpr-sim’s command-line tool. This page is for anyone who wants to use it from a terminal or a script. It says what each command does, shows its output, and lists the exit codes.

Today hpr does eight things:

• It flies a design, read from an OpenRocket file or an hpr design file, and prints how the flight went.
• It flies a design many times, its uncertain inputs scattered at random (Monte Carlo), and prints how far its apogee and landing spread.
• It looks up motors, from the catalog built into it or from a motor file of your own, and searches vendors’ stock and prices from motor.fusionspace.co.
• It converts motor files between the two common formats, and designs between OpenRocket’s .ork and hpr’s own format (.hpr, and .hprz with other files beside the design).
• It re-runs hpr-sim’s validation against RocketPy and checks the results against the published ones.
• It reads a flight log from an altimeter and prints what it says about the flight, with no design file and no simulation.
• It fetches a launch day’s weather, or reads a weather file, and writes the air and wind over the site as a profile.
• It writes shell completion scripts.

Its other commands are registered but not available yet: each refuses and names the milestone, the step of the roadmap, that brings it (the table below).

How far to trust it.

• hpr sim prints what the library computes: a test flies the rocket of the example below through hpr sim and through the Rust library, and gets identical numbers, to the last bit. How close those are to a real flight is the Accuracy page’s subject. hpr sim flies a .ork file’s parachutes and streamers as OpenRocket flies them, and lands within 0.02% of OpenRocket’s landing speed on 50 of its 53 example flights, and within 0.12% on all 53 (Recovery). It flies a separation under power, or several in turn as on a three-stage rocket, but a dropped stage’s own flight is not validated. With no device open within 1 s of apogee, where and how fast its rocket comes down are not predictions (what it leaves out).
• hpr motors show works out each figure from the motor’s thrust curve with the same code a flight uses. On all 32 bundled curves, that code matches ThrustCurve.org’s own statistics code to 1.8e-15, relative (Solid motors). hpr motors list gives the same figures for the bundled motors, worked out by the same code from the same ThrustCurve.org files.
• hpr convert keeps the thrust curve, the size and the masses. On all 32 bundled motor files, converting to the other format and back gives each of them again as hpr reads the file, bit for bit, except two masses written with 17 digits, each flagged by a warning (test). OpenRocket 24.12 opens all 32 converted files and reads 29 as it reads the originals; the other three differ only in the motor’s type or a delay (other programs). Whether RockSim opens them is not checked.
• hpr doesn’t re-run the validation cases. To run the check the project’s automated tests make on every change, clone the repository and run cargo xtask validate --check (what it checks).
• hpr weather runs the library’s readers and writes the profiles they build, to the last bit (how far to trust it). Its online fetch is not tested automatically.
• hpr motors search gives back motor.fusionspace.co’s values unchanged (how far to trust it). Its online fetch is not tested automatically.
• The tests in crates/hpr-cli/tests/ run every command as a user would, and check each --json document against its published schema.

Running it

There is no ready-built download yet. hpr needs Rust and a copy of the repository, set up as Getting started shows. From that copy, run it through Cargo:

cargo run -p hpr-cli -- motors list

Or install it once, so that hpr works from any directory:

cargo install --path crates/hpr-cli --locked
hpr --help

hpr --version prints its version and its designation, FS · SW · TOOL 005: hpr-sim’s number among FusionSpace’s tools, the family of programs whose design rules it follows (ADR-164).

Colors and messages

The result, with its warning:, note: and help: lines, goes to standard output. A refusal goes to standard error, or to standard output as a JSON document with --json. Each message line starts with a word that says what it is, so it reads the same with or without color:

The colors are your terminal’s own red, yellow and blue, so its theme decides how they look. hpr decides for standard output and standard error separately, in this order:

1. --color always or --color never, if given.
2. NO_COLOR set to anything but an empty value: no color.
3. FORCE_COLOR set to anything but an empty value, or CLICOLOR_FORCE set to anything but an empty value or 0: color, even into a file or a pipe.
4. Otherwise (--color auto, the default) a stream gets color only when it is a terminal and TERM isn’t dumb.

So hpr sim rocket.ork > flight.txt writes plain text to the file while an error on the terminal stays red. --json output never has color, whatever the flag or the variables say. To turn color off everywhere, set NO_COLOR=1; for one run, give --color never, which every command takes.

The commands

This table is written from the tool’s own list of commands, so it names only what hpr has, and only the files each command really reads. “Not yet” commands exit with status 3.

hpr sim

hpr sim flies a design from a launch rail to the ground, and prints what happened: its stability margin as it leaves the rail, its apogee, its speed off the rail, how its ejection delay suits the climb, how fast it comes down, its events, its top speed, and where it came down. It reads an OpenRocket .ork file, a design in the hpr design format (.hpr, or a .hprz with its attachments), or a rocket’s JSON (.json, the tree Your own rocket describes). A .hpr or .hprz flies exactly as the .ork it was converted from (converting a design), though it doesn’t print the .ork reader’s warnings, which hpr convert printed. It runs the same simulation code as the Rust library, so a Rust program flying the same design gets the same numbers.

Flying a design

This flies one of the repository’s own test rockets, a small single-stage OpenRocket design. Its file names an AeroTech H128W, which isn’t among the 32 motors built into hpr, so --motor H54 puts the catalog’s Cesaroni H54 in its motor mount instead:

$ hpr sim validation/fixtures/ork/pod-flights/pods-none.ork --motor H54
pods-none (pods-none.ork)
configuration 1 of 1: [H128W-0] with --motor H54

static margin         2.69 calibres off the rail; least 2.69 calibres, at 0.15 s, before apogee
apogee                846.1 m above the site at 11.21 s
rail exit speed       21.3 m/s
delay                 apogee 7.71 s after burnout
descent               no recovery device opened, so the fall is not a prediction

motor: 1 × 168H54-10A (from the bundled catalog) in `Motor mount`, lit at launch
launched at 0° N, 0° E, 0 m above sea level, from a 1.5 m vertical rail, in calm air
help: see the Accuracy page before trusting these numbers: https://nrdptel.github.io/hpr-sim/accuracy.html
note: the file has no recovery device, so the rocket falls from apogee on its airframe alone, on aerodynamics that hold only at small angles of attack: its landing time, speed and place, and any peak it sets in the fall, are not a prediction
warning: drag: issue #18: skin friction is taken as fully turbulent, but on a smooth surface the flow stays laminar near the nose, where friction is lower: hpr's reads high by 3.6% on RocketPy's Calisto at Mach 0.3; if this surface is that smooth, the drag reads high, so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are (https://github.com/nrdptel/hpr-sim/issues/18)
warning: stability: issue #172: the static margin read up to 0.1108 calibres higher than OpenRocket's on four private designs, for a reason not yet found, so this flight's margin may read high by as much (https://github.com/nrdptel/hpr-sim/issues/172)

event                   time     height       speed
liftoff               0.00 s      0.3 m     0.0 m/s
rail exit             0.15 s      1.8 m    21.3 m/s
burnout               3.50 s    466.0 m   136.3 m/s
apogee               11.21 s    846.1 m     0.1 m/s
ground hit           29.71 s      0.0 m    65.9 m/s
(heights are the center of gravity's above the site; speeds are over the ground)

top speed             178.3 m/s at 2.31 s
top Mach number       0.525
landing               17.4 m from the pad at 29.71 s, at 65.9 m/s: with no recovery device opened soon after apogee, not a prediction

What each part says:

The text names configurations and parts by their names, in backticks, not by the long ids an OpenRocket file gives them; a part with no name is called by its id. --json prints the same flight as data, with the ids beside the names: each configuration’s id, name and label, the label being what the text calls it, and each motor’s mount and mount_name.

A missing motor is fetched, then kept: it flies offline from the cache. A .ork file names its motor but rarely carries its thrust curve, and hpr’s catalog holds 32 motors. When the file embeds no curve and the catalog lacks the motor, hpr sim finds it on ThrustCurve.org by the file’s manufacturer and designation, keeps it in hpr’s cache, and flies it; a note names the curve file, who measured it and its license (Motors from ThrustCurve.org). For the motors of OpenRocket’s own example designs, hpr takes the ThrustCurve file that holds OpenRocket’s curve; for any other motor the curve may not be the one OpenRocket flies, and no such flight has been compared with OpenRocket’s own curve yet. With --offline, or no network, and no copy in the cache, hpr sim refuses and names the command that fetches it (abridged):

$ hpr sim validation/fixtures/ork/pod-flights/pods-none.ork --offline
error: configuration [H128W-0] can't be flown as the file has it: no thrust curve for H128W: ...; AeroTech H128W is not in hpr's cache of ThrustCurve.org, and the run is offline
help: with a network connection, `hpr motors fetch --manufacturer AeroTech H128W` fetches it into the cache
help: give a motor with --motor

Run that command once with a network connection, or fly the design once while online, and it flies offline after. Or give a motor file you have: hpr sim my-rocket.ork --motor AeroTech_H128W.eng.

The landing

A .ork file’s parachutes and streamers fly, as OpenRocket flies them. So do those of a .hpr or .hprz converted from a .ork. hpr sim flies them through hpr::ork::recovery, so its numbers are the library’s. Each opens fully at once, the file’s delay after its event, and the rocket then comes down under the open devices’ drag alone. That lands within 0.02% of OpenRocket’s landing speed on 50 of its 53 example flights, and within 0.12% on all 53 (Recovery). Those flights are in calm air: they check how fast and how long the rocket comes down, not where wind drifts it. When the first device opens within 1 s of apogee, the landing is no longer marked “not a prediction”, and neither is a peak set once a device is open. A later first opening, such as a main alone at 150 m, keeps the mark on the landing and on any peak in the fall before it, and a note says how long the rocket fell first: where and how fast the device opens come from that fall, on the airframe alone, as below. The JSON’s recovery list gives each device’s name, body (the part that carries it, below), opens_at (apogee, altitude, ejection, launch or separation), height_above_ground_m, delay_s, drag_area_m2 and opened_s. A device the file sets to never, or to an ejection charge a plugged motor doesn’t fire, opens nothing, and a note says so. So does one set to its stage’s ejection charge in a stage where no motor lights, as in OpenRocket: the note says “Main never opens: it opens at its stage’s ejection charge, and no motor of its stage lights”, and the other devices fly. A device hpr can’t fly as written, such as one inside a part hpr doesn’t read, is refused: the rocket then flies with none, and a note says why.

This flies the repository’s dual-deploy test rocket, a drogue at apogee and a main at 150 m, with the catalog’s H54 in place of its own motor; the descent line gives the speed under the drogue as the main opens, then at landing:

$ hpr sim validation/fixtures/ork/loft-demo/demo-dual-deploy.ork --motor H54
Loft Demo 54mm — dual deploy (demo-dual-deploy.ork)
configuration 1 of 1: [K550W-P] with --motor H54

static margin         6.25 calibres off the rail; least 6.25 calibres, at 0.27 s, before apogee
apogee                324.0 m above the site at 9.12 s
rail exit speed       11.2 m/s
delay                 apogee 5.62 s after burnout
descent               14.1 m/s at 150.0 m under `Drogue parachute`; 4.7 m/s at landing with `Main parachute` open too

motor: 1 × 168H54-10A (from the bundled catalog) in `Booster / motor bay`, lit at launch
recovery: `Main parachute` at 150 m on the way down, 1.052 m² of drag area, opened at 22.41 s
recovery: `Drogue parachute` at apogee, 0.133 m² of drag area, opened at 9.12 s
launched at 0° N, 0° E, 0 m above sea level, from a 1.5 m vertical rail, in calm air
help: see the Accuracy page before trusting these numbers: https://nrdptel.github.io/hpr-sim/accuracy.html
note: the file's 2 recovery devices fly as OpenRocket flies them: each opens fully at its event, with the file's drag coefficient or OpenRocket's own, and once one opens the rocket descends as a point under the open devices' drag alone
warning: drag: issue #18: skin friction is taken as fully turbulent, but on a smooth surface the flow stays laminar near the nose, where friction is lower: hpr's reads high by 3.6% on RocketPy's Calisto at Mach 0.3; if this surface is that smooth, the drag reads high, so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are (https://github.com/nrdptel/hpr-sim/issues/18)
warning: stability: issue #172: the static margin read up to 0.1108 calibres higher than OpenRocket's on four private designs, for a reason not yet found, so this flight's margin may read high by as much (https://github.com/nrdptel/hpr-sim/issues/172)

event                   time     height       speed
liftoff               0.00 s      0.6 m     0.0 m/s
rail exit             0.27 s      2.1 m    11.2 m/s
burnout               3.50 s    163.1 m    59.6 m/s
apogee                9.12 s    324.0 m     0.0 m/s
charge                9.12 s    324.0 m     0.0 m/s
deployment            9.12 s    324.0 m     0.0 m/s
charge               22.41 s    150.0 m    14.1 m/s
deployment           22.41 s    150.0 m    14.1 m/s
ground hit           53.94 s      0.0 m     4.7 m/s
(heights are the center of gravity's above the site; speeds are over the ground)

top speed             65.9 m/s at 2.73 s
top Mach number       0.194
landing               0.4 m from the pad at 53.94 s, at 4.7 m/s

With no device open soon after apogee, the landing is not a prediction. The rocket then falls from apogee on its airframe alone, as the example’s does. hpr’s aerodynamics hold only at small angles of attack, and a falling airframe turns far past them, so where it lands, and how fast, are artifacts of the model; one test design glides tail-first far from the pad in calm air (issue #241). So is a top speed or Mach number set in the fall: a rocket that falls faster than it climbed shows its top speed after apogee, and hpr sim marks it “in the fall: not a prediction” (after_apogee in the JSON). The ascent, up to apogee, is what to read.

Separation

A .ork configuration whose booster drops away under power flies, as does one that drops several stages in turn, but a dropped stage’s own flight is rough. hpr sim reads the staging from the file, as hpr::ork::separations does, and flies it with no --motor: a motor of your own can’t be told when the stages separate, so with --motor it is refused. Each parachute and streamer rides the part its stage is in (hpr::ork::separated_recovery). On both configurations of OpenRocket’s Two stage high power rocket, the sustainer’s landing speed is +0.00% off OpenRocket’s, and its flight time +0.32% and +0.73%. On the first, its main opens 1.09 s before OpenRocket’s, mostly as its apogee is 1.79% lower and OpenRocket opens 8.9 m below the set height (Staging).

After the split, each part flies as a point, with only its devices’ drag. So the booster tumbles from the split until its first own device opens, and a sustainer with no device tumbles from its apogee. A real booster flies nose-first for a while, so its peak and landing are likely too low and too close to the pad (issue #179); a note says so, and a map export draws no pin for it. The sustainer, which keeps the nose, is part 0; the booster is part 1. Each device line names its part (on part 1), and the booster’s landing is printed as landing, part 1, marked rough. A tumble hpr adds counts as no recovery device for the landing’s caveat, so a sustainer that only tumbles lands with “not a prediction”. In the JSON, a device’s body is null for the sustainer and the part’s index otherwise, added is true for a tumble hpr added, and a tumble opened at the split has opens_at separation. The M4.5g1 milestone shipped this; the decision record says why each part needs a device.

Several separations fly too, one after another, from the tail forward. At each split the stages behind it drop away, and the rest flies on as a new sustainer, which must still have a motor to burn. The parts are numbered in the order they drop. On OpenRocket’s Three stage low power rocket (one of the example designs OpenRocket ships), the booster is part 1 and the middle stage part 2; the file names both of them Booster stage. On its first configuration, an A8-5 above two B6-0s, the note reads: “the stack comes apart under power 2 times: at 0.857 s part 1, Booster stage, drops away, at 1.714 s part 2, Booster stage, drops away; the sustainer, part 0, flies on”. The output then prints landing, part 1 and landing, part 2, each marked rough like a booster’s.

• Against OpenRocket, on its own thrust curves. All three configurations separate at OpenRocket’s times. Their apogees are within 1.48% and their largest speeds within 1.64% of OpenRocket’s (Staging).
• With the curves hpr sim fetches. The file holds no curves, so hpr sim fetches them from ThrustCurve.org (Motors from ThrustCurve.org), taking the files that hold OpenRocket’s own curves. Its largest speeds are within 1.67% of OpenRocket’s; the first configuration reads 78.61 m/s against OpenRocket’s 78.37. Its apogees, with the file’s parachutes, are within 1.37% of OpenRocket’s own record, which opens them too, and within 2.48% of OpenRocket’s flight with nothing deployed.
• Not validated: the dropped middle stage’s own flight, like the booster’s (issue #179).

The M4.5g2 milestone shipped this; its decision record (several powered separations) has the numbers.

Boosters strapped beside the core fly too, on a rocket of one stage on the axis: a parallel stage, which burns with the core and drops at its own separation. On OpenRocket’s Parallel booster staging, the boosters’ E12s light with the core’s I115W at launch, and the note reads “the stack comes apart under power at 2.440 s: part 1, Booster Set, drops away”. Boosters with no motor that lights stay on to the landing, as OpenRocket flies them. Both configurations’ apogees are within 1.23% of OpenRocket’s (Staging: Boosters beside the core); the dropped boosters’ own flight is not validated, like a booster’s. The M4.5m milestone shipped this; its decision record says how a parallel stage is read and flown.

A booster may drop with motors still burning, when the file separates it at its first burnout. A stage with motors in more than one mount burns out when its first motor does, as OpenRocket flies it, and drops the rest still burning. The dropped part flies with no thrust, so a note names the motors and the impulse its flight leaves out. On the first configuration of OpenRocket’s Pods–powered with recovery deployment, [C6-7; 2× A3-4, B6-0] (its motors by stage, sustainer first, the stages separated by ;), the note begins “part 1 drops at 0.860 s with A3, A3 still burning”. The impulse it gives, 0.509 N·s, is the one the report’s Parts dropped still burning section holds. This sustainer is unstable, with a least margin of −4.21 calibres. In the conditions of OpenRocket’s record, a 0.15 m rod at 28.61° N with no wind, hpr’s sustainer turns over at 2.04 s. From hpr sim’s defaults, a 1.5 m rail with no wind, it does not, so the apogee printed assumes it stays upright, and why the two differ is not traced. hpr sim warns that the rocket is unstable under power and marks that apogee as not a prediction (Flight metrics: unstable under power; #335). The M4.5n milestone shipped this (Staging: A booster dropped still burning).

A payload dropped with nothing left to burn flies when its own parachute opens at the split. Some rockets drop a payload section at the booster’s ejection charge, after the motor has burned out, sometimes before apogee. From the split, each part flies as a point with only its own devices’ drag, as OpenRocket flies a descent. A payload with nothing open would coast as if in a vacuum, so hpr sim flies the split only when the part that keeps the nose has a device of its own open by then. A device set to lowerstageseparation opens at the split, its delay after. Otherwise the configuration is refused with “the part that keeps the nose, would coast with no drag from the separation at …”. To fly it, set one of the payload’s devices to open at the split: in OpenRocket, its deployment event “Lower stage separation” with no delay.

The payload is part 0: its apogee is the flight’s, and its own events, such as its apogee and its landing, follow the stack’s in the events table. A dropped part that climbs higher gets a note, “part 1 peaks at … above the flight’s apogee”, as a waiver’s height is the highest any part reaches. The note reads “the stack comes apart at 4.860 s with nothing left to burn: part 1, Booster, drops away”. On OpenRocket’s Deployable payload and ARC payload rocket, all six configurations fly. The payload’s apogee is within 1.1% of OpenRocket’s, and every descent meets the targets: each deployment within 0.1 s of OpenRocket’s or 2% of its time, whichever is larger, and the landing speed and flight time within 5% (Recovery). Two of the six separate before apogee. Each of the Deployable payload’s five configurations flies with two warnings: the payload and the parachute are 25 mm across in a 21 mm bore, so they can’t fit as drawn. Their width sets only their own inertia (a packed part wider than its bore).

• What the refusal avoids. Coasting from the split with no drag, the Deployable payload’s C6-3 payload would reach 268.8 m, 4.00% above OpenRocket’s 258.5 m for the same payload flying on its own airframe.
• Not validated: the booster’s flight after the split, as above (issue #179). Nor a real payload whose parachute opens late, which would land later and further away: OpenRocket’s record holds no such flight.
• The figure and the exports stop at the split. --plot and --export follow the stack, which ends where it comes apart; after that, each part’s flight is in the events and landings only, and a note says so.

The M4.5g3 milestone shipped this; its decision record (a separation with nothing left to burn) has the numbers.

The launch

Every flight starts from a rail, at a site, in the standard atmosphere. Without options, the site is at sea level at 0° N, 0° E, the rail is vertical and 1.5 m long, and the air is calm. The rail has no friction. hpr sim doesn’t read the launch conditions an OpenRocket file stores with its simulations: give them with these options.

Set --elevation for any real field. The air thins with height, so the same rocket flies higher from a high site: from 1,400 m, the rocket above climbs about 8% higher than from sea level. Latitude changes gravity only a little: at 45° N its apogee moves by less than 0.2%. Set --latitude and --longitude too before exporting a map, which is drawn where you say the pad is.

OpenRocket measures its launch rod’s angle from the vertical instead, so its 5° is 85 here. This flies the same rocket from Spaceport America’s field, on a rail leaning 5° into a west wind:

$ hpr sim validation/fixtures/ork/pod-flights/pods-none.ork --motor H54 --latitude 32.99 --longitude -106.97 --elevation 1400 --rail-length 3 --inclination 85 --heading 270 --wind 5 --wind-from 270
pods-none (pods-none.ork)
configuration 1 of 1: [H128W-0] with --motor H54

static margin         2.71 calibres off the rail; least 2.71 calibres, at 0.21 s, before apogee
apogee                877.4 m above the site at 11.48 s
rail exit speed       30.2 m/s
delay                 apogee 7.98 s after burnout
descent               no recovery device opened, so the fall is not a prediction

motor: 1 × 168H54-10A (from the bundled catalog) in `Motor mount`, lit at launch
launched at 32.99° N, 106.97° W, 1400 m above sea level, from a 3 m rail 85° above the horizon, leaning toward 270°, in a 5 m/s wind from 270°
help: see the Accuracy page before trusting these numbers: https://nrdptel.github.io/hpr-sim/accuracy.html
note: the file has no recovery device, so the rocket falls from apogee on its airframe alone, on aerodynamics that hold only at small angles of attack: its landing time, speed and place, and any peak it sets in the fall, are not a prediction
warning: drag: issue #18: skin friction is taken as fully turbulent, but on a smooth surface the flow stays laminar near the nose, where friction is lower: hpr's reads high by 3.6% on RocketPy's Calisto at Mach 0.3; if this surface is that smooth, the drag reads high, so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are (https://github.com/nrdptel/hpr-sim/issues/18)
warning: stability: issue #172: the static margin read up to 0.1108 calibres higher than OpenRocket's on four private designs, for a reason not yet found, so this flight's margin may read high by as much (https://github.com/nrdptel/hpr-sim/issues/172)

event                   time     height       speed
liftoff               0.00 s      0.3 m     0.0 m/s
rail exit             0.21 s      3.3 m    30.2 m/s
burnout               3.50 s    468.6 m   144.4 m/s
apogee               11.48 s    877.4 m    11.3 m/s
ground hit           28.71 s      0.0 m    70.3 m/s
(heights are the center of gravity's above the site; speeds are over the ground)

top speed             184.3 m/s at 2.35 s
top Mach number       0.556
landing               310.4 m from the pad at 28.71 s, at 70.3 m/s: with no recovery device opened soon after apogee, not a prediction

It climbs about 4% higher than the same rocket at sea level, in the first example, not the 8% the altitude alone gives: the rocket turns into the wind as it climbs, and the rail already leans that way, so its climb tips away from the vertical. The wind does most of it.

The motor and the configuration

• --config NAME flies the configuration of that number, name or id. The output’s first lines list the file’s configurations by number and name.
  • A configuration the file leaves unnamed, as OpenRocket files usually do (50 of the 56 in OpenRocket’s own examples), is called by its motors and their delays in brackets: [C6-5], [C6-P] for a plugged motor, [C6-5; B6-0] for two motors.
  • --config ignores case and brackets, so --config c6-5 takes [C6-5], as does its number, such as --config 4.
  • A name two configurations share is refused, with their numbers; so is a word that is one configuration’s number and another’s id or name, with their names and ids.
  • Without --config, hpr sim flies the file’s default configuration, or its only one; if it can’t tell which, it refuses and lists them.
• --motor NAME flies a motor of the built-in catalog, by its designation or common name (H54, 168H54-10A); hpr motors list shows the catalog. A name the catalog lacks is fetched from ThrustCurve.org and cached, as hpr motors fetch NAME does (Motors from ThrustCurve.org). --motor FILE flies the motor in a .eng or .rse file (RASP and RockSim files). Either way, the motor goes in the configuration’s motor mount, in place of the file’s motor, and lights at launch.
• --delay S gives --motor’s motor an ejection delay of S seconds after burnout, and --delay P makes it a plugged motor. Without it, the motor fires no ejection charge, so a parachute set to open on the charge stays shut. The first line then says with --motor H125-CT --delay 10, and the delay line how far from apogee the charge fires (Pick a motor).
• --offline takes a fetched motor from the cache alone, never the network. Setting the environment variable HPR_OFFLINE=1 does the same for every command.
• --mount NAME says which mount --motor goes in, by its name or id, when the design has several and no configuration says, or to move the motor to another. A name two mounts share is refused, with their ids; --json lists each motor’s mount id too.
• --accept-design-errors flies a design whose checks find errors, such as a motor wider than its mount. The flight’s notes then list the errors: such a rocket can’t be built as drawn.

hpr sim refuses, with the reason, rather than fly something other than the design:

• with --motor, a configuration with motors in more than one mount, as --motor flies one;
• a rocket whose stages separate in a way hpr sim doesn’t fly: unpowered before apogee, at or after apogee beside another separation, or before the separation behind it; a .ork configuration’s powered splits fly, one or several (Separation);
• a motor lit by a stage’s separation, in a design that states no separation, such as a rocket’s .json;
• with --motor, a .ork rocket of more than one stage, or a configuration that switches a stage off;
• a .ork rocket hpr couldn’t read exactly as written, such as one with a parallel stage on a rocket of several stages;
• a design whose checks find errors, unless --accept-design-errors is given;
• a hybrid motor in a .rse file, which says so: hpr flies solid motors only. A .eng file doesn’t say what kind of motor it holds, so a hybrid’s is flown as a solid; check the motor.

Exporting the recording

--export FILE writes the flight’s recording: every quantity hpr tracks, every 0.01 s (set it with --interval, down to 0.001 s), and at every event. The file’s extension picks the format; repeat --export for several files. hpr sim won’t write over a file it reads.

The maps draw the whole path. They mark the landing point when a recovery device opened, and no landing point otherwise: with none open, the path after apogee and where it ends are not predictions.

Each file names the program that wrote it, its version and its designation. A CSV file can’t without breaking a spreadsheet’s reading of it, so hpr sim writes a small file beside it, flight.meta.json for flight.csv, which does, with the design and configuration flown and the number of rows. Exporting a flight says where each format keeps it, and what each column and field means.

Plotting the flight

--plot FILE.svg draws the flight as one picture, to look at rather than to analyze: the altitude, the speed and the acceleration against time, in three panels over one time axis, with each event marked. The figure is always the same set, so any two flights read alike. An SVG opens in any web browser. The numbers behind it come from the same flight as the text: for the data itself, or a plot of your own, use --export (above). The name must end in .svg and its folder must exist.

• Altitude: the height of the center of gravity above the launch site, as the events table gives it.
• Speed: the center of gravity’s speed over the ground, whose peak is the top speed line, and its vertical speed (the thin line, up positive), whose value under the parachutes is the descent line’s rate.
• Acceleration: the size of the nose tip’s acceleration, and its vertical part (the thin line, up positive). The nose tip is the point hpr’s equations of motion track, and the peak acceleration of the --json summary is taken there too; for a rocket that isn’t turning, every point of it accelerates alike. A recovery device opens fully at once (the landing), so its opening shows as a sharp spike.
• Not what an accelerometer reads. The panel shows how the motion changes: zero on the pad, and in a coast about −10 m/s² vertically, gravity plus drag. An accelerometer reads about zero in that coast, and 9.8 m/s² on the pad.
• Events: each instant with events is a numbered balloon (a circle) above the panels, with a dotted line through them. The table under the figure gives each event a row: its balloon’s number, its time, the altitude then, and its name, with each parachute or streamer by name.
• Not a prediction: when no recovery device opens within 1 s of apogee, the fall from apogee to the first opening (or to the ground) is hatched and labeled, the rule the summary’s “not a prediction” marks follow, for the reason the landing gives. The example below has no hatching, as its drogue opens at apogee.

The figure is drawn in the chart style of the FusionSpace product system, the design rules shared by hpr and its sister tools (ADR-164, the decision to follow them). In that style, magenta marks a prediction, and every line here is one. There is no legend box; a caption under the title says once what the lines mean:

The caption’s first line is the figure’s summary: the apogee, its time and the top speed, the summary’s own numbers. The SVG carries the same sentence as its description, which a screen reader reads out. Numbers on the figure are written for reading, 1,000 and a real minus sign −20; copy numbers from --export or --json, which are plain. The text is set in Cascadia Mono where it is installed, else another fixed-width font, so the lines keep their widths.

The panels sample the flight every --interval (0.01 s unless set), at every event, and at the start and end of every step the integrator takes, so a jump such as a parachute’s opening is drawn at its instant and full height. Where a pixel column of the figure covers many samples, it keeps the column’s first, least, greatest and last, so a long descent stays a small file and no sampled peak is lost. A peak the summary prints is found between samples, so the plotted one can sit just below it: in the example, a test holds the plotted top speed and the main’s opening peak within 1% of the summary’s (ADR-157, the plot’s design; ADR-175, its style).

This draws the dual-deploy rocket of the landing:

$ hpr sim validation/fixtures/ork/loft-demo/demo-dual-deploy.ork --motor H54 --plot sim-plot.svg

cargo xtask cli draws this figure with the command above, so it shows what the current hpr draws.

What hpr sim doesn’t fly yet

• A rocket’s .json has no recovery devices. It holds no parachute, so the rocket falls from apogee on its airframe alone, and the fall is not a prediction; the output’s notes say so. A Rust program can fly one (Getting started). The devices of a .ork, or of a .hpr or .hprz converted from one, fly (the landing). One set to open at the lower stage’s separation (lowerstageseparation) flies only on a split with nothing left to burn (separation), and is refused otherwise.
• Separation, beyond powered splits. A .ork configuration whose booster drops away under power flies, and so does one that drops several stages under power in turn, such as OpenRocket’s Three stage low power rocket (separation). A design whose only separation can come only after apogee flies as one stack, with a note, as does a design with no separation stated. A payload dropped with nothing left to burn flies when its own device opens at the split. These are refused by name: such a payload whose device opens later, or that has none; a separation with nothing left to burn beside another; a separation at or after apogee beside another separation; and one that comes before the separation behind it. With your own --motor, a staged configuration is refused too, since that motor can’t be told when the stages separate.
• Real weather. One wind at every height, in the standard atmosphere. hpr weather writes a launch day’s profile, but hpr sim doesn’t fly it yet (issue #265).

hpr mc

hpr mc flies a design many times, each flight’s uncertain inputs drawn afresh about their planned values, and prints how far the apogee and the landing spread, with the ellipses the landings fall in. It reads whatever hpr sim reads, with the same options for the design, the motor and the launch, and flies each flight as hpr sim does, a staged .ork’s separations included. Monte Carlo dispersion explains the method, what each dispersion does and how to choose the numbers.

How far to trust it. The run is the Rust library’s: a test flies the same design through MonteCarlo::run and gets the same flights, bit for bit, on one platform. The spread is only as good as the standard deviations you give and hpr’s flight models, which are not yet validated against repeated real flights (Accuracy).

Scattering a flight

This flies the repository’s small test rocket on the catalog’s Cesaroni H54 200 times, in a 4 m/s wind from the west, off a rail leaned 5° into it, each flight’s mass, drag, motor, wind and rail drawn afresh:

$ hpr mc validation/fixtures/ork/pod-flights/pods-none.ork --motor H54 --runs 200 --seed 2026 --wind 4 --wind-from 270 --inclination 85 --heading 270 --mass-sd 0.02 --drag-sd 0.05 --impulse-sd 0.03 --burn-time-sd 0.02 --wind-sd 0.25 --wind-from-sd 15 --inclination-sd 1 --heading-sd 2
pods-none (pods-none.ork)
configuration 1 of 1: [H128W-0] with --motor H54

200 flights, seed 2026: 0 failed
                        nominal     mean  std dev       5%   median      95%
apogee (m)                813.9    819.4     34.4    765.0    818.8    870.8
landing distance (m)      286.9    283.2     44.8    208.8    281.8    354.5

200 of 200 flights landed, centered 282 m west and 2 m north of the pad
landing ellipse        semi-major  semi-minor  heading   flights inside
50%                          53 m        33 m      89°            48.5%
95%                         110 m        68 m      89°            93.5%
95%, the next flight        111 m        69 m      89°            93.5%

motor: 1 × 168H54-10A (from the bundled catalog) in `Motor mount`, lit at launch
launched at 0° N, 0° E, 0 m above sea level, from a 1.5 m rail 85° above the horizon, leaning toward 270°, in a 4 m/s wind from 270°
help: see the Accuracy page before trusting these numbers: https://nrdptel.github.io/hpr-sim/accuracy.html
scattered, one standard deviation each: --mass-sd 0.02, --drag-sd 0.05, --impulse-sd 0.03, --burn-time-sd 0.02, --wind-sd 0.25, --wind-from-sd 15, --inclination-sd 1, --heading-sd 2
note: the file has no recovery device, so the rocket falls from apogee on its airframe alone, on aerodynamics that hold only at small angles of attack: its landing time, speed and place, and any peak it sets in the fall, are not a prediction
warning: drag, the nominal flight: issue #18: skin friction is taken as fully turbulent, but on a smooth surface the flow stays laminar near the nose, where friction is lower: hpr's reads high by 3.6% on RocketPy's Calisto at Mach 0.3; if this surface is that smooth, the drag reads high, so the apogee, the top speed and the drift read low, and the flutter margin and the largest dynamic pressure look better than they are (https://github.com/nrdptel/hpr-sim/issues/18)
warning: stability, the nominal flight: issue #172: the static margin read up to 0.1108 calibres higher than OpenRocket's on four private designs, for a reason not yet found, so this flight's margin may read high by as much (https://github.com/nrdptel/hpr-sim/issues/172)

The table gives the nominal flight’s figure (the flight hpr sim flies with the same options), then the run’s mean, standard deviation, 5th percentile, median and 95th percentile. A failed flight counts as tried with no value. The landing ellipses are the Landing ellipses section’s: the 50% and 95% ellipses hold that share of a normal scatter with the run’s mean and spread, and the last allows for the run’s spread being only an estimate, so the next flight lands inside it 95% of the time. An ellipse’s heading is the direction of its long axis, in degrees clockwise from north, and flights inside counts the run’s own landings inside each, a failed flight counted outside. This rocket has no parachute, so its landings are not a prediction, and the note says so.

The options

Each dispersion is one standard deviation, zero by default, which leaves its input at its nominal value. With none given, every flight is the nominal one, and a note says so. Choosing the numbers gives values to start from, with their sources.

--runs N sets how many flights, 1 to 100,000 (100 by default). --seed N picks the random draws (0 by default): the same seed, design and options give the same flights, bit for bit, on one platform, whatever the machine’s number of cores. hpr mc refuses a negative standard deviation, a run of no flights, and an export that isn’t a .csv, before it flies.

Exporting every flight

--export runs.csv writes one row a flight, in index order: what it drew, then what its flight came to. Each number is written in the shortest form that reads back to the same bits, so a spreadsheet or a script reading the file gets the run’s own numbers; a number a flight doesn’t have is an empty cell. Beside it, runs.meta.json names the program that wrote it, the design, the configuration, the seed, the number of flights and the dispersion. The columns:

The same table is hpr_analysis::table::RunTable in the Rust library.

What the output warns of

Failed flights are counted, never dropped: each reason is printed once, with how many flights failed so and the first one’s index, its row in the export. The operating envelope’s flags, and the flag for a rocket unstable under power, are counted over the flights, and the known issues in hpr’s drag and stability are the nominal flight’s, as hpr sim prints them. So are hpr sim’s notes on the flight’s own numbers, such as a fall from apogee before a device opened, each beginning “the nominal flight:”.

A staged flight can fail where its nominal flight flies, and is counted with its reason:

• A separation timed in seconds isn’t scattered, so a flight whose drawn burn is longer still burns at it, which hpr refuses unless the split may drop a burning motor. A separation at a burnout follows the drawn burn.
• A part dropped on the way up with nothing left to burn, by a separation or an ejection charge, flies as a point, with only its open devices’ drag. If its device fired by the split but waits out a drawn lag, the part would climb through the lag with no drag at all, so the flight is refused. --json prints all of it as one document, its schema schema/cli/mc.schema.json.

hpr motors

hpr motors looks motors up. The catalog built into hpr holds 32 motors, from class B to class O, each with a public-domain thrust curve from ThrustCurve.org (Solid motors says how they were chosen). hpr motors fetch fetches any other motor’s curve from ThrustCurve.org into hpr’s cache, for hpr sim to fly (Motors from ThrustCurve.org); or download its .eng or .rse file (RASP and RockSim files) and show that. hpr motors search lists the motors vendors have in stock, with their prices (Motors you can buy).

Listing the catalog

hpr motors list lists the catalog. Three filters narrow it, and each one given must match:

• --class takes an impulse class, such as J.
• --diameter takes a casing diameter in millimeters, such as 54, and matches within 0.5 mm.
• --manufacturer takes a maker as the maker column spells it (AeroTech, Cesaroni, Loki, Estes, Quest, AMW) or its full name (Cesaroni Technology), in any case.

A class or diameter the catalog has no motor for lists none, and exits with 0. A class that doesn’t exist, a diameter that isn’t a positive number, or a maker the catalog doesn’t know is refused with status 1: a misspelt maker would otherwise look like a maker with no motors.

The figures are the catalog’s, each worked out from the motor’s public-domain ThrustCurve.org curve file: size, masses and delays from its header, the rest from its curve (The bundled motors). In the delays column, P (or 1000) means plugged: the motor has no ejection charge (ejection delay). The delays are as the header writes them, which can be fewer than the maker sells.

$ hpr motors list --class J
3 motors from ThrustCurve.org data files marked public domain, downloaded 2026-09-17; size, masses and delays from each file's header, the rest from its curve.

designation   maker     class  dia mm  len mm  impulse N·s  avg N  burn s  delays
J450DM        AeroTech  J          54     359       1061.6  465.6    2.28  14
1266J760-19A  Cesaroni  J          54     329       1267.3  758.2    1.67  8-10-12-14-16-18-19
J300LR        Loki      J          54     327       1212.8  297.0    4.08  P

A motor’s figures

hpr motors show takes a motor’s name or a file’s path. A name can be the full designation (1266J760-19A) or the common name (J760), in any case, with or without spaces and hyphens. When several motors share a name, it shows each of them. An argument ending in .eng or .rse is read as a file; anything else is looked up by name.

It works each figure out from the thrust curve, the list of time and thrust points in the motor’s file:

• The total impulse is the area under the curve, with its points joined by straight lines. It sets the impulse class.
• The burn time is measured the NFPA 1125 way: from when the thrust first reaches 5% of its peak to when it last falls back to it.
• The average thrust is the total impulse divided by that burn time.
• The masses and the casing size are the catalog’s, or the file’s for a file.

For a catalog motor, the last line names the public-domain curve file the figures come from. hpr motors list gives the same figures, as a test checks: ThrustCurve.org’s own published figures are not bundled, as it states no terms for them (issue #295). When the 32 were chosen, their total impulse, average thrust and burn time agreed with ThrustCurve.org’s within 1%, and hpr’s peak, the curve file’s highest point, runs from 16.7% below ThrustCurve.org’s (Cesaroni 26E31-15A) to 2.1% above (Loki M1378LR) (Solid motors).

$ hpr motors show J760
1266J760-19A (Cesaroni Technology), from the bundled catalog
  impulse class    J
  total impulse    1267.3 N·s
  average thrust   758.2 N
  peak thrust      938.6 N
  burn time        1.67 s, from 0.001 s to 1.672 s (NFPA 1125, 5% of peak)
  propellant       576.0 g of 1076.8 g loaded
  casing           54 mm across, 329 mm long
  delays           8 s, 10 s, 12 s, 14 s, 16 s, 18 s, 19 s
  curve file       https://www.thrustcurve.org/simfiles/5f4294d20002e9000000074a/ (public domain)

A motor file shows every motor in it, as one .eng or .rse file can hold several. The repository holds the 32 catalog motors’ files to try, such as:

hpr motors show crates/hpr-motor/data/thrustcurve/curves/5f4294d20002e90000000724.eng

Some motor data is ambiguous. A delay of 0 can mean an ejection charge at burnout, or a plugged motor with no charge. hpr shows it as “0 (at burnout, or plugged)” and ends the output with a warning; the Estes F15 in the catalog is one example. The warning’s “RASP spec” is the .eng format’s description (RASP and RockSim files).

Motors you can buy

hpr motors search lists the motors that U.S. vendors carry, with who has each one in stock and at what price. The list comes from motor.fusionspace.co, a free site that reads a dozen vendors’ public listings every hour and covers AeroTech, Cesaroni and Loki motors of class D and up (Motor stock and prices says what it publishes and how hpr reads it). Five filters narrow the list, and each one given must match:

• --in-stock keeps the motors at least one vendor has in stock.
• --class takes an impulse class, such as L.
• --diameter takes a diameter in millimeters, such as 54, and matches within 0.5 mm.
• --manufacturer takes AeroTech, Cesaroni or Loki, or the full name the site uses (Cesaroni Technology, Loki Research), in any case.
• --max-price takes U.S. dollars, such as 150 or 149.99, and keeps the motors in stock whose price for one motor, at the cheapest vendor with it in stock, is at most that. A motor sold in a pack counts at the pack’s price divided by its size, as the site works it out, to the cent (What the site publishes). A motor out of stock has no such price, and nor does one whose cheapest vendor shows no price or prices it in another currency than U.S. dollars (every vendor’s price was in dollars on the recording): --max-price never keeps them.

The motors come cheapest first, by that price. The motors with no such price, including every motor out of stock, come last, by maker and designation. A filter that can’t match anything real (a class that doesn’t exist, a maker the site doesn’t cover, a price that isn’t dollars and cents) is refused with status 1, as hpr motors list refuses one. A list with nothing in it exits with 0. When --max-price leaves nothing, the last line names the cheapest motor in stock that the other filters keep, and its price, so you know what one costs.

The list is fetched and saved as hpr weather’s answers are (Online, offline, and saved answers): the first search fetches it over HTTPS and keeps a copy in hpr’s cache folder, a search within the hour reads the copy, and --offline reads the copy however old it is. --from FILE reads a list saved earlier, the site’s motors.json or in-stock.json, and touches neither the network nor the cache. With --in-stock or --max-price, which keep only motors in stock, hpr fetches the site’s list of motors in stock (about 1 MB); otherwise, the whole list (about 1.6 MB). The two are saved separately. Offline, a search of motors in stock reads the whole list’s copy when it has no copy of the in-stock one; a search of every motor needs the whole list’s copy.

Every list, even an empty one, carries two credit lines, under its first two lines: the site’s, “Motor stock data from motor.fusionspace.co”, which its data license (CC BY 4.0) asks for, with its caution to check stock and price on the vendor’s own page before relying on them; and ThrustCurve.org’s, since the motors’ figures (impulse, average thrust, burn time) are its published values, which the site repeats (Credit and terms). The JSON output carries both in attribution. Keep them wherever you show the list.

This reads the list of motors in stock that the tests use, recorded at 07:07 UTC on 1 October 2026, and keeps the L motors in stock at up to $300 each:

$ hpr motors search --in-stock --class L --max-price 300 --from crates/hpr-net/tests/fixtures/replay/motor-finder-in-stock.json
4 motors (in stock, class L, at most $300.00 each) in motor.fusionspace.co's list built 2026-10-01T07:07:29Z.
Read from motor-finder-in-stock.json
Motor stock data from motor.fusionspace.co, licensed CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); aggregated from public vendor listings and ThrustCurve.org; provided as is, with no warranty: check stock and price on the vendor's own page before relying on them
Motor data and thrust curves courtesy of ThrustCurve.org, https://www.thrustcurve.org/

designation  maker     class  dia mm  impulse N·s   avg N  burn s  each $  pack  vendor
L1520T       AeroTech  L          75       3715.9  1567.8    2.36  260.99     1  Balsa Machining Service
L850W        AeroTech  L          75       3646.2   850.0    4.42  282.74     1  Sirius Rocketry
3419L645-P   Cesaroni  L          75       3419.8   644.8    5.30  286.36     1  Performance Hobbies
3683L851-P   Cesaroni  L          75       3683.2   849.1    4.34  290.39     1  Animal Motor Works

each $ is the price of one motor and pack how many come in the pack, both at the vendor named last. A motor out of stock shows - for both and out of stock for the vendor; a vendor that shows no price gives - under each $; a price in another currency names it, such as 282.74 CAD. The full product page is in the JSON output (cheapest_in_stock.url). At $150, the same recording lists nothing:

$ hpr motors search --in-stock --class L --max-price 150 --from crates/hpr-net/tests/fixtures/replay/motor-finder-in-stock.json
0 motors (in stock, class L, at most $150.00 each) in motor.fusionspace.co's list built 2026-10-01T07:07:29Z.
Read from motor-finder-in-stock.json
Motor stock data from motor.fusionspace.co, licensed CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/); aggregated from public vendor listings and ThrustCurve.org; provided as is, with no warranty: check stock and price on the vendor's own page before relying on them
Motor data and thrust curves courtesy of ThrustCurve.org, https://www.thrustcurve.org/
None costs $150.00 or less: of the 20 motors in stock the other filters pass, the cheapest is AeroTech L1520T at $260.99.

How far to trust it. hpr motors search gives back the site’s values unchanged, and reads the list with the same checks the library makes on every answer from the site (What hpr refuses). The tests in crates/hpr-cli/tests/motors_search.rs run it offline on the recorded lists, from the file and from the cache, and check every motor it lists, and their order, against the recording’s own JSON, filtered by the test itself, not by hpr’s code. With one L motor’s price edited to $149.99 in a copy, the --max-price 150 search lists exactly that motor. Fetching online is not tested automatically. Whether a vendor really has a motor at that price is the vendor’s to say. A list fetched now, or read from a copy under an hour old, can be up to two hours behind the vendors’ pages. A list read with --offline, with --from, or after a failed fetch is as old as the “built” time on its first line (How far to trust it).

Motors from ThrustCurve.org

hpr motors fetch NAME finds a motor on ThrustCurve.org and keeps its curve in hpr’s cache (Where the cache lives), so hpr sim flies it with no network after. It is for a motor hpr’s 32-motor catalog lacks; hpr sim fetches on its own too, so the command matters most before a trip with no signal. This is ThrustCurve’s data, as its contributors uploaded it: hpr checks that a file makes a motor it can fly, not that its curve is right.

• Before a trip. For a .ork, run the command hpr sim --offline prints for it, which names the motor’s manufacturer as the file writes it (hpr motors fetch --manufacturer AeroTech H128W), or fly the design once with a network connection: either fills the cache the design reads offline. hpr motors fetch H128W, without --manufacturer, fills the cache for hpr sim --motor H128W instead.
• Which motor. NAME is a designation (F27R/L) or common name (F27), as ThrustCurve.org spells it; --manufacturer adds the maker, by name or abbreviation. ThrustCurve matches a designation exactly, any case; if no motor has it, hpr asks for the common name. Exactly one motor must answer: J450 names four makers’ motors, and the refusal lists them, so give the designation or --manufacturer. A hybrid is refused, as hpr flies solid motors only.
• Which curve. A motor can have several curve files. hpr takes the first RASP (.eng) file that makes a motor hpr flies, ranked by who measured it: a certification test, then the manufacturer, then a user, then a file that names no source; with none, a RockSim (.rse) file the same way. --file ID takes the file of that ThrustCurve id first, when the motor has it and it reads; the id is the one hpr motors fetch prints on its curve file line, and an offline refusal’s command names it when the flight asks for a file. The output names the file, who measured it and its license, as ThrustCurve states them, and gives ThrustCurve’s credit.
• OpenRocket’s curve for a .ork motor. ThrustCurve can hold several files of one motor with different curves, and OpenRocket may fly another than the first by that order: the Estes A8’s first certification file burns 0.536 s, the one OpenRocket’s examples fly 0.73 s. A .ork records which curve OpenRocket flies by a digest, a fingerprint of the curve, so for the motors of OpenRocket’s example designs hpr sim keeps a table from digest to the ThrustCurve file holding that curve, matched by comparing the curves (cargo xtask ork-curves). It takes that file first, and the note on the motor says so. A motor outside the table flies the file by the order above, and the note says it may not be the curve OpenRocket flies. An offline refusal’s command then carries --file, so it fetches the file the flight takes. Offline with a cache that holds only some of the motor’s files, a file the cache lacks is given up for the usual order’s, and the note says the curve may not be OpenRocket’s. The table is as of 2026-10-04; if ThrustCurve’s files change, cargo xtask ork-curves rewrites it.
• Offline. --offline, or HPR_OFFLINE=1, reads the cache alone, and a copy of any age flies; with no copy, the command fails with exit status 1. Online, a copy stays fresh for a day; after that hpr asks again, and keeps the old copy if the network fails.

A fetch with a network connection printed this on 2026-10-04 (pasted by hand, not run in CI; its help: line as hpr writes it since M0.6b, which made each hint a help: line):

$ hpr motors fetch F27R/L
F27R/L (AeroTech), from ThrustCurve.org: fetched now
  curve file       5f4294d20002e90000000372, RASP (.eng), from a user, no license stated
  case             29 × 83 mm
help: kept in the cache: `hpr sim --motor F27R/L` flies it, offline too
Motor data and thrust curves courtesy of ThrustCurve.org, https://www.thrustcurve.org/

Offline with nothing cached, it says what to run:

$ hpr motors fetch H128W --offline
error: H128W is not in hpr's cache of ThrustCurve.org, and the run is offline
help: with a network connection, `hpr motors fetch H128W` fetches it into the cache
$ echo $?
1

hpr bundles none of these curves: ThrustCurve.org grants no license for its motor records, and each file carries its contributor’s own license. The decision record on fetching motors, ADR-154, has the reasoning.

hpr convert

hpr convert writes a motor as a RASP .eng file or a RockSim .rse file, the two formats ThrustCurve.org offers (RASP and RockSim files), and a design as a .ork, .hpr or .hprz file (converting a design). Give it the file to read and the file to write; the extensions pick the formats. It reads a motor file, or a motor of the bundled catalog by its name:

hpr convert H170M H170M.eng

A catalog motor is written with the size and masses the catalog gives, which are the ones hpr flies; where its curve file’s header says otherwise, a warning says so. Written as .rse, the figures worked out from them (the mass fraction, the specific impulse, and the mass and center of gravity at each point) are rescaled to match, and a warning says that too. The delays are the curve file’s, which can differ from the ones hpr motors show lists. An existing file of the output’s name is replaced, but never the file being read: to rewrite a .eng file in hpr’s layout, convert it to a new .eng file name. Here the Estes F15’s .rse file, from the catalog’s curves, becomes a .eng file:

$ hpr convert crates/hpr-motor/data/thrustcurve/curves/5f923edb1bca5800041716ab.rse F15.eng
read   5f923edb1bca5800041716ab.rse
wrote  F15.eng: F15
warning: line 3: engine "F15": delay 0 in "0,4,6,8" is ambiguous: the RASP spec means an ejection charge with no delay, but files mostly mean plugged
warning: F15: a .eng maker is one word, so "Estes Industries, Inc." is written "Estes_Industries,_Inc."
warning: F15: dropped the comments' blank lines and the spaces that end their lines: a .eng comment is one line of text
warning: F15: dropped Type, auto-calc-mass, auto-calc-cg, avgThrust, peakThrust, throatDia, exitDia, Itot, burn-time, massFrac, Isp, m, cg: a .eng file has no place for them. hpr doesn't use them for a solid motor: it works the mass and center of gravity out from the curve and the masses

What a conversion keeps

Both formats give a motor’s name, maker, diameter and length, its loaded and propellant masses, its delays, and its thrust curve. The curve, the size and the masses are kept: converting a file and converting the result back gives each of them again as hpr reads the file, bit for bit, but for a mass of 16 or 17 digits (below). The formats write some things differently, and hpr convert translates:

Masses move between kilograms and grams by moving the decimal point, not by multiplying, which would round: 0.0041 kg times 1000 is 4.1000000000000005 in a computer’s arithmetic, while moving the point gives 4.1. A mass written with 16 or 17 digits may still change in its last digit; a warning says so. A flight turns a .rse file’s grams into kilograms by dividing by 1000, and the catalog’s by multiplying by 0.001, so the same motor flown from a .eng file and from its converted .rse can differ in a mass’s last digit, a part in 10¹⁶.

Some things come back written differently, though they mean the same:

• Delays spelled p, 1000 or with spaces come back in the table’s spelling. hpr reads them as the same delays.
• A name or maker of several words comes back with _ between the words, in any .eng file hpr convert writes. A .eng header is seven fields split by spaces, and OpenRocket 24.12 refuses one of eight (the script checks it); a warning says so.
• A .eng motor whose delays are -, which names none, is written to .rse without delays, so converting it back to .eng needs --delays.
• Comments lose their blank lines and the spaces ending their lines, and comments after the last motor of a .eng file are dropped; a warning says so.

A .rse file also gives figures a .eng file has no place for: the motor’s type, its total impulse, average and peak thrust, burn time, mass fraction, specific impulse, nozzle throat and exit diameters, two flags saying whether RockSim works the mass and center of gravity out itself, and the mass and center of gravity at each point of the curve. Going to .eng, they are dropped, and a warning names them. hpr doesn’t use them for a solid motor: it works the mass and center of gravity out from the curve and the masses, whichever format it reads. Going to .rse, they are filled in the way ThrustCurve.org’s .rse files are: the total impulse by adding up the curve, the remaining propellant falling in step with the impulse delivered, the center of gravity at half the length, both flags set, and the type unspecified. The rules, and the counts of real files behind them, are in the .rse format notes.

hpr convert refuses to write a hybrid motor as .eng, which couldn’t mark it as a hybrid (hpr models solid motors only). A .eng header must give delays, so a .rse motor without them is refused until --delays gives them, such as --delays P for a plugged motor. --delays fills only the motors that give none.

Other programs. OpenRocket 24.12 opens all 32 files hpr convert writes from the bundled curves. A script compares what OpenRocket reads from each converted file with what it reads from the original: the name, the maker as OpenRocket names it, the type, the diameter and length, the launch and burnout masses, the curve’s points, and the delays. 29 of the 32 read the same.

• Two are .rse files that say the motor is reloadable or single-use. A .eng file can’t say it, so OpenRocket reads the converted files’ type as unknown. hpr flies both types alike.
• The third is the Aerotech G69N’s .eng file, which writes its plugged delay as 1000. OpenRocket reads no delay from that original, but a plugged motor from the converted .rse. hpr reads both as plugged, so the difference is in OpenRocket’s reading of the original, not in what hpr convert wrote.

The project’s automated tests don’t run the script, as they have no OpenRocket. Whether RockSim opens the files is not checked.

Converting a design

Given design files, hpr convert takes a design between OpenRocket’s .ork and the hpr design format: .hpr, one JSON document, or .hprz, a zip archive of the document with other files beside it. The extensions pick the formats, any of the three to any. Here one of the repository’s public designs becomes a .hpr:

$ hpr convert validation/fixtures/ork/loft-demo/demo-multi-config.ork demo.hpr
read   demo-multi-config.ork
wrote  demo.hpr: "Loft Demo 38mm — motor comparison", 2 motor configurations, hpr design format 0.2

The document holds everything hpr read from the .ork, including what hpr doesn’t model, so hpr convert demo.hpr demo.ork writes the .ork hpr would write from the original, byte for byte. hpr sim demo.hpr flies it to the same flight as the .ork, but without the .ork reader’s warnings, which hpr prints only when it reads the .ork itself. A document of an older version of the format is migrated as it is read, and the output says from which version. hpr sim may refuse --motor for a version 0.1 document, which didn’t record whether the rocket was read exactly as written; converting the .ork again fixes that (versions).

--attach adds a file to a .hprz, once for each file: a flight log, a photograph, anything, up to 256 MiB for the whole container. Each goes at the top of the container, under its file name, and a name the container can’t hold, such as CON.txt, is refused (the container’s name rules). Converting a .hprz to a .hprz keeps its attachments, and adds any --attach names. Converting one to a .hpr or a .ork leaves its attachments out, and a warning names each. With --json, the output (convert.schema.json) gives:

• the files read and written, with their formats;
• the rocket’s name, and how many motor configurations the design holds;
• the version of the format the input was migrated from, if it was;
• the attachments written into a .hprz;
• the warnings: the .ork reader’s, the .ork writer’s, and each attachment left out.

hpr analyze

hpr analyze reads the log an altimeter recorded during a flight and prints what it says: when the rocket lifted off, how high it went, how fast it climbed, and when it landed. It needs only the log. It takes no design file and runs no simulation, so it answers “what did my rocket do?” for anyone who flew one, whatever they designed it in.

It reads PerfectFlite’s .pf2 logs so far (the format). The one real file read is a Pnut’s; the StratoLogger and StratoLoggerCF are expected to write the same layout, but no file of theirs has been tried. Other loggers’ files come with M7.1, the milestone that reads the other formats. It has no check yet for a barometer’s errors near the speed of sound. If the flight may have come near Mach 0.9, about 300 m/s (1,000 ft/s), treat the top speed and the heights near it with care: the barometer’s error can pull the top speed down too.

hpr analyze flight.pf2

Each reading is either a value that says where it came from, or withheld with the reason the log can’t support it. The text output gives the reason as a sentence; the JSON output adds its code, listed on Flight-log readings. A log read with readings withheld still exits with 0; a file hpr can’t read exits with 1 (Exit codes). A PerfectFlite has a barometer and no accelerometer, so the top acceleration is always withheld: working it out from the altitude would turn the altitude’s one-foot steps into spikes of many g. What the file states about itself, such as the altimeter’s own apogee, is printed beside hpr’s readings, never in their place. Heights are meters above the altimeter’s reading on the pad, with feet in brackets; times are seconds on the log’s clock.

This example log is invented, so every reading can be checked against the flight it was made from (Reading a flight log works through it). Its true apogee is 390.3 m (1280.5 ft), at 10.26 s:

$ hpr analyze validation/fixtures/logs/synthetic-pnut.pf2
synthetic-pnut.pf2: PerfectFlite Pnut, serial 0, flight 1
984 samples every 0.050 s, from 0.00 s to 49.15 s; heights from the altitude after a 0.30 s running median
the logger states: apogee 390.4 m (1281 ft); ground elevation 182.9 m (600 ft) above sea level

liftoff           0.55 s
apogee            390.1 m (1280 ft) at 10.28 s, 9.72 s after liftoff
                  highest sample 400.5 m (1314 ft) at 11.35 s, set aside by the median
top speed         79.9 m/s (262 ft/s) at 2.10 s, 64.0 m (210 ft) up: the logger's own, from its barometer
top acceleration  withheld: a PerfectFlite logger has no accelerometer; hpr doesn't difference the altitude twice to make one, as its one-foot steps would read as spikes of many g
landing           45.85 s, 45.30 s after liftoff; 35.58 s from apogee, at 10.9 m/s (36 ft/s) on average

The highest sample in the file is 10.4 m above the apogee: the pressure pulse of the ejection charge that fired a second after it. The readings are taken from the altitude after a running median, which sets that pulse aside. Reading a flight log explains each reading, and how far to trust it.

hpr weather

hpr weather writes down the air and the wind over a launch site, level by level from the ground up: at each height, the pressure, the temperature, the humidity, and the wind’s speed and the direction it blows from. That list of levels is a profile (a sounding, when a weather balloon measured it). It comes from one of five sources:

hpr sim doesn’t fly a profile yet (issue #265). A Rust program can: each source’s page flies Calisto, RocketPy’s example rocket, through the weather it fetched.

How far to trust it. hpr weather runs each source’s reader from the library and adds no physics of its own. Each reader is checked against the recorded answers on its source’s page. The tests in crates/hpr-cli/tests/weather.rs run the four online sources through hpr weather offline, both from a saved answer and from the cache, and ERA5 from its file. Each run writes the profile the library builds from the same bytes, to the last bit, and lists the same levels left out. Fetching online is not tested automatically: it was run once by hand, on 30 September 2026, for all four online sources. On a network that inspects encrypted traffic, every fetch fails (Fetching over HTTP). How good a forecast is at your launch is not measured.

Asking for the weather

• Times are UTC, written 2025-06-21T15:30Z: the date, a T, the hour and minutes, and a Z for UTC. Seconds are optional, and so are the minutes: 2026-09-30T00Z is midnight. A time without its Z is refused, so local time can’t be mistaken for UTC.
• Open-Meteo reads the forecast at --time, between the two hours around it. Add --historical for a launch already gone: that asks Open-Meteo’s archive of past forecasts. --model names one of Open-Meteo’s weather models, by the name its documentation gives; by default it picks one (What hpr asks for).
• Wyoming takes the station’s number, such as 72364 for Santa Teresa, New Mexico (finding a station), and your launch --time. It fetches that station’s latest sounding before the launch. Soundings are named for 00 and 12 UTC, and the balloon goes up about an hour before: the example’s 12 UTC sounding left at 11:02. --bufr asks for the detailed version, a row every second or two of the climb.
• GFS and RAP take the forecast run and the hour: --cycle is when the run started, and --hour is how many hours after it the forecast is for. GFS runs every 6 hours and RAP every hour. What hpr asks for lists the hours each run covers, and how long NOAA keeps them.
• ERA5 reads a file you downloaded, at your site and time (Getting a file).

Online, offline, and saved answers

The first time you ask, hpr weather fetches the answer over HTTPS and keeps a copy in hpr’s cache folder (Where the cache lives; HPR_CACHE_DIR moves it). Ask again and it reads the copy while that is fresh (How long a copy stays fresh). If the network fails, it falls back to an older copy, and the output says so.

• --offline never goes online. It answers from the cache, fresh or not. With no copy it fails, with exit status 1, and names what it would have fetched.
• --from FILE reads an answer saved earlier and touches neither the network nor the cache: Open-Meteo’s JSON, the Wyoming archive’s CSV, or a GRIB2 file for GFS and RAP. For GFS and RAP, still give --latitude and --longitude: the file covers an area, and the site picks the point in it. For Open-Meteo and Wyoming, the file says where and when it is for, so the options that choose what to fetch are refused beside it: Open-Meteo’s --latitude, --longitude, --historical and --model, and Wyoming’s --station, --time and --bufr. Open-Meteo’s --time stays, and must fall within the file’s hours. A GRIB2 file is checked as a fetched one is: it must be on its model’s grid, and when you give --cycle and --hour, it must be that run and hour. Check the first line of the output, which says where and when the profile is for.
• --output FILE (or -o) writes the profile as JSON, described below.

hpr reads the small GRIB2 files that NOAA’s download server, NOMADS, cuts out around a site, and whole GFS files you download yourself, which are packed more tightly (A whole GFS file). The decoder also reads fields compressed as JPEG 2000 images, which RAP’s whole files use, but no whole RAP file has been run through hpr weather yet (Files in JPEG 2000).

An example

This reads a recorded answer from Open-Meteo’s archive, for Spaceport America in New Mexico at 15:30 UTC on 21 June 2025, and writes the profile to profile.json. (hpr names the folder it wrote to in full; here that folder is shown as <the scratch folder>.)

$ hpr weather open-meteo --time 2025-06-21T15:30Z --from crates/hpr-net/tests/fixtures/replay/open-meteo-historical.json --output profile.json
Open-Meteo at 32.9965° N, 106.9695° W, for 2025-06-21T15:30:00Z
Read from open-meteo-historical.json
Weather data by Open-Meteo.com (CC BY 4.0)

   height  pressure    temp  humidity    wind   from
    m MSL       hPa      °C         %     m/s      °
   1400.0     859.5    29.6        18     3.3    162
   1482.0     850.0    28.2        16     2.9    189
   2014.4     800.0    23.4        16     2.8    225
   3160.6     700.0    14.5        28     6.8    236
   4439.1     600.0     3.3        60     9.8    219
   5894.6     500.0    -7.0        70     9.9    200
   7604.0     400.0   -17.1        34     8.3    218
   9712.0     300.0   -31.5         8     4.4    261
  10981.7     250.0   -41.2         9    10.6    261
  12465.1     200.0   -52.2        13     9.8    253
  14276.4     150.0   -64.8        18     9.9    263
  16716.8     100.0   -70.8        12     6.3    253
  18863.9      70.0   -66.2         4     7.8    164
  20940.5      50.0   -60.0         0     5.4    108
  24212.5      30.0   -54.0         0     8.6     83

Left out: 5 levels
  below the ground, 5 levels: 1000 hPa, 975 hPa, 950 hPa, 925 hPa, 900 hPa

Profile written to <the scratch folder>/profile.json

The first line says where and when the profile is for: for Open-Meteo, its model’s grid point nearest the site; for GFS and RAP, the site itself, blended from the four grid points around it; for Wyoming, where the balloon was released. The ground comes first: its height above sea level (MSL), its pressure in hectopascals (hPa; 1013 hPa is sea level’s standard), its temperature and humidity, and the wind 10 m above it. Each pressure level above the ground follows. The levels the model gives below the ground are listed as left out: here the ground is at about 1,400 m, and 1000 to 900 hPa lie beneath it. Where each value comes from, and why levels are left out, is on the source’s page.

The profile file

--output writes the profile in SI units, the way the library holds it. Its levels run from the lowest up, each with:

Beside them, latitude_rad is the latitude the profile was measured or forecast at, in radians, and wind_interpolation says how the wind is blended between levels (speed_direction). The Rust library reads the file back as a SoundingProfile, with the same checks. The text output and --json give the same levels with the direction in degrees.

What the profile leaves out

• Time between forecast hours, for GFS and RAP: pick the run and hour nearest your launch. Open-Meteo and ERA5 blend the two hours around it.
• The site’s real ground. A forecast’s ground is its model’s smoothed terrain, not your pad’s height, and an ERA5 file has no ground at all: its levels start at 1000 hPa, which can lie below a high site.
• Humidity in ERA5. hpr doesn’t read it yet, so ERA5’s profile is dry air.
• Above the top level, the library carries the air on as the standard atmosphere and holds the top wind; each source’s page gives its top.

JSON output

With --json, a command prints exactly one JSON document on standard output, and nothing on standard error. That holds when the command fails, too. A failure prints an error document. Each document has a published JSON Schema, which describes its fields and units:

Every document opens with the same tool object, the program that wrote it: {"name": "hpr-sim", "version": "0.1.0", "designation": "FS · SW · TOOL 005"}. An error document’s help lists what to do about the failure, the lines the text output starts with help:, and is empty when there is nothing to suggest. The sidecar of a CSV recording (Exporting the recording) has its own schema, sim-export-meta.schema.json.

Units are SI, and each field’s name says its unit: total_impulse_ns is in newton-seconds and diameter_m in meters. The exceptions say so in their names too: hpr sim gives angles in degrees (latitude_deg) and margins in calibres (margin_cal), hpr weather gives the wind’s direction in degrees (wind_from_deg) and humidity as a fraction (relative_humidity, 0 to 1), hpr motors list keeps the catalog’s millimeters (diameter_mm), and hpr motors search the site’s millimeters and cents (diameter_mm, unit_price_cents). Numbers are not rounded, so a converted value can end in digits such as 0.0036000000000000003; a motor’s figures carry no more precision than its curve file.

hpr is pre-alpha, so the fields may still change. The schemas are published beside the code, and a change to a document changes its schema in the same commit.

$ hpr motors show B4 --json
{
  "tool": {
    "name": "hpr-sim",
    "version": "0.1.0",
    "designation": "FS · SW · TOOL 005"
  },
  "motors": [
    {
      "name": "B4",
      "manufacturer": "Quest Aerospace",
      "source": {
        "kind": "catalog",
        "curve_url": "https://www.thrustcurve.org/simfiles/5f4294d20002e9000000088e/",
        "format": "eng"
      },
      "diameter_m": 0.018,
      "length_m": 0.08,
      "propellant_mass_kg": 0.0036000000000000003,
      "loaded_mass_kg": 0.0198,
      "total_impulse_ns": 4.892141999999999,
      "impulse_class": "B",
      "average_thrust_n": 4.403753380057823,
      "peak_thrust_n": 7.2,
      "burn_time_s": 1.110902808988764,
      "burn_start_s": 0.01745,
      "burn_end_s": 1.128352808988764,
      "curve_end_s": 1.184,
      "delays": [
        {
          "kind": "seconds",
          "value": 4.0
        },
        {
          "kind": "seconds",
          "value": 6.0
        }
      ]
    }
  ],
  "warnings": []
}

A failure prints an error document. Its kind matches the exit status, and milestone is set only for a command not available yet. Here hpr sim --offline refuses the test rocket above without --motor, as neither the file, the bundled catalog nor the cache holds a curve for its motor:

$ hpr sim validation/fixtures/ork/pod-flights/pods-none.ork --offline --json
{
  "tool": {
    "name": "hpr-sim",
    "version": "0.1.0",
    "designation": "FS · SW · TOOL 005"
  },
  "error": {
    "kind": "input",
    "message": "configuration [H128W-0] can't be flown as the file has it: no thrust curve for H128W: no embedded curve, and no motor of that manufacturer and designation in the bundled catalog; AeroTech H128W is not in hpr's cache of ThrustCurve.org, and the run is offline",
    "command": "sim",
    "milestone": null,
    "help": [
      "with a network connection, `hpr motors fetch --manufacturer AeroTech H128W` fetches it into the cache",
      "give a motor with --motor"
    ]
  }
}
$ echo $?
1

Exit codes

hpr --help and hpr --version print text and exit with 0, even with --json.

hpr completions

hpr completions writes a script that lets your shell complete hpr’s commands and options when you press Tab. Save it where your shell looks for completions:

What it leaves out

• Unpowered stage separations, a dropped stage’s accuracy, and a rocket .json‘s parachutes. hpr sim flies powered separations, one or several in turn, but not an unpowered one before apogee. A dropped stage flies as a point under its devices’ drag, so its landing is rough. It flies a .ork file’s parachutes and streamers, but a rocket’s .json comes down with no recovery device (what it doesn’t fly yet).
• One log format. hpr analyze reads PerfectFlite’s .pf2 so far; other loggers’ files, and readings such as the drogue and main descent rates and the Mach number, come with M7.1 and M7.2.
• Only OpenRocket’s and hpr’s own design files. hpr convert and hpr sim read OpenRocket’s .ork and hpr’s .hpr and .hprz, not RockSim’s .rkt or RASAero’s .CDX1 (how the formats compare).
• No validation check. The validation cases and their reference results are files in the repository, not part of the tool. To re-run them, clone the repository and run cargo xtask validate --check (what it checks).
• RockSim is unchecked. OpenRocket opens the files hpr convert writes; whether RockSim does is not checked.
• hpr sim doesn’t fly the weather. hpr weather writes a profile that only a program reads so far (issue #265).
• Stock from one site. hpr motors search covers what motor.fusionspace.co does: U.S. vendors, prices in dollars, and AeroTech, Cesaroni and Loki motors of class D and up (what it leaves out). It has no filter by total impulse or by reload case.
• Only 32 motors are built in. Any other motor needs its .eng or .rse file. hpr never goes online to fetch one: hpr motors search lists motors you can buy, not their curves.
• No ready-built program. hpr is built from source with Rust; downloads for macOS, Windows and Linux wait until the project publishes releases.
• The text output is for people. Its layout may change between versions; scripts should read --json, whose schemas are published.

Online data and the cache

This page covers hpr-net, the one crate that uses the network, and the cache that makes its answers work offline. It is for anyone who will pull weather, elevation or motor data into a flight. Today the crate holds the cache, the offline rule and an HTTP client (M5.1, the online layer), and six data sources: Open-Meteo’s weather (Launch-day weather), weather-balloon soundings from the University of Wyoming (Weather-balloon soundings), NOAA’s GFS and RAP forecasts (NOAA forecasts: GFS and RAP), Open-Meteo’s ground elevation (A launch site’s elevation), motor.fusionspace.co’s motor stock and prices, and ThrustCurve.org’s motor records and thrust curves (both on Motor stock and prices; hpr sim and hpr motors fetch fetch a curve the bundled catalog lacks, Motors from ThrustCurve.org). Its tests replay a small hand-written sample response and answers recorded from each, from a folder and from a test web server on the machine running the tests, never the live network. Those tests speak plain HTTP only: encrypted HTTPS was checked by hand, against Open-Meteo and then through the command line’s hpr weather against all four sources, not in CI.

What it promises

hpr’s simulation itself never touches the network (the architecture’s pure-core rule: no filesystem, network or clock). Anything fetched from the internet goes through a client, which puts a cache (a folder of saved responses) in front of a transport (the thing that actually fetches). The client runs in one of two modes:

• Online: if the cache holds a fresh copy, the client returns it without fetching. Otherwise it fetches, saves the response, and returns it. If the fetch fails and an old copy exists, it returns the old copy, marked stale, with the reason the fetch failed; with no old copy, the fetch’s error.
• Offline: it never calls the transport. It returns whatever the cache holds, marked stale if it is old, or an error saying the URL is not cached.

Each answer says how fresh it is (Fetched, Cached or Stale), when it was fetched, and the data source’s attribution, the credit line that its terms ask you to show with the data.

A data source can also give the client a check, its own parser (Client::fetch_checked). Then an answer the parser refuses, such as an error page sent as a success or a forecast whose hours are still empty, is never saved, so it can’t take a good copy’s place. Online, a good copy that has gone stale comes back instead, with the reason; with no copy, the fetch fails. A saved copy the check refuses counts as missing online, and is the error offline.

How long a copy stays fresh

Each source has a time to live (TTL): how many seconds a saved copy counts as fresh. A copy exactly one TTL old is no longer fresh: online it is fetched again, offline it comes back marked Stale. A copy dated later than the time asked (saved while the clock ran fast) is never fresh. The caller passes the time, in seconds since 1 January 1970 (Unix time); the crate reads no clock, so the tests can use small numbers.

Here is a worked example with a one-hour TTL (3,600 s), from the tests. Each scenario starts with an empty cache and fills it at 1,000 s:

Fetching over HTTP

The HTTP client is Http. It is behind hpr-net’s http cargo feature, so a program that depends on hpr-net alone and needs only the cache and saved responses builds no network code. The hpr library’s net feature turns HTTP on: with hpr = { ..., features = ["net"] } in Cargo.toml it is hpr::hpr_net::Http. Its API page has an example, compiled in CI, that fetches into the platform’s cache folder. Building with HTTP needs a C compiler, since the encryption library compiles some C and assembly.

A failed fetch (an error status, a timeout, a refused or dropped connection, a too-long answer) is handled as above: online, the client falls back to an old copy marked stale.

The time and size limits, and whether to use the environment’s proxy, are fields of HttpConfig. Start from HttpConfig::default(), change a field (for example config.timeout = Duration::from_secs(300)), and pass it to Http::with_config(config).

Because the computer’s certificate store is not read, a network that inspects encrypted traffic with its own certificate (common on company and school networks) makes every HTTPS fetch fail, and there is no setting yet to add a certificate.

Where the cache lives

The cache folder is whatever you pass. Cache::platform_dir gives the usual place for caches on each system, and the folder is created on the first save:

Setting the environment variable HPR_CACHE_DIR puts the cache in that folder instead, on every system; a relative path there is taken from the current folder. The folders come from environment variables alone: on Windows LOCALAPPDATA is read rather than asking the system, which gives the same folder unless the variable was changed. If HPR_CACHE_DIR is not set and HOME (macOS, Linux) or LOCALAPPDATA (Windows) is unset or empty, Cache::platform_dir returns nothing and you must name a folder.

Setting HPR_OFFLINE to anything but empty or 0 makes every hpr command answer from the cache alone, as each command’s --offline does: for a script, or a field laptop, that must not reach the network.

How it is checked

The tests in crates/hpr-net/tests/offline.rs replay a hand-written sample from a folder instead of using the network:

• The offline test gives the client a transport that fails the test if it is ever called, then asks for a URL before and after it is cached, fresh and thirty days stale.
• Offline, a corrupt entry is an error; online, it is fetched again and overwritten.
• The checked fetch is tested through Open-Meteo’s source (Launch-day weather): an answer with an hour’s values missing is not saved, and an earlier good copy comes back and stays saved. The soundings’ source is tested the same way (Weather-balloon soundings), and NOAA’s forecasts refuse, and don’t save, a file for another run or hour than the one asked for (NOAA forecasts: GFS and RAP). The elevation source refuses an answer with no heights, and a lookup made once works offline (A launch site’s elevation). The motor-stock source refuses, and doesn’t save, a motor’s page that holds another motor, and the ThrustCurve.org source a download of another motor’s file (Motor stock and prices).

The cache’s own tests check that a saved body reads back, and that another URL’s entry in the same file reads as a miss. They also check that the hash that names each file (FNV-1a, a standard 64-bit hash, so names stay the same on every platform) matches its published test values. The cache folder rules are checked for each system with a made-up environment, HPR_CACHE_DIR included; the XDG_CACHE_HOME case runs only on Unix test machines. The API reference for hpr_net has a runnable example.

The HTTP tests in crates/hpr-net/tests/http.rs start a small web server inside the test, on the computer’s own loopback address (127.0.0.1), which serves the same sample. Nothing leaves the machine, and the tests turn off any proxy the environment names. They check that:

• a fetch saves the sample in the cache, a second fetch inside the time to live sends no request, and offline mode answers from the cache without a request while the server is still running;
• a compressed answer arrives unpacked, and the request names hpr-sim and asks for gzip;
• a redirect is followed and saved under the address asked for;
• a 404 and a 304 are failed fetches and save nothing;
• an answer one byte over the limit is refused and one at the limit passes, and a megabyte of zeros that compresses to under 64 KiB is refused at a 64 KiB limit;
• a server that never answers is cut off at a 0.3 s limit (the test requires under 5 s; the server stalls for 10 s), and a timeout of Duration::MAX (the usual way to say “no limit”), which hpr treats as 30 days, does not crash;
• when the server hangs up without answering, an old copy comes back marked stale, with the reason.

What it leaves out

• No retries: a failed fetch is tried once. Plain, unencrypted http:// addresses are accepted; nothing forces HTTPS. The 60 s time limit covers the whole transfer, so a large answer on a slow connection can time out; raise it in HttpConfig.
• No test makes an encrypted (HTTPS) connection: the test server speaks plain HTTP, since a local encrypted server would need certificates made for the test. One manual run on a Mac fetched a real Open-Meteo forecast over HTTPS and refused a site with an expired certificate (ADR-118: M5.1b, HTTP over the cache), but that is not repeated in CI.
• Freshness comes only from the source’s TTL: a server’s cache headers are ignored, and the cache key is the URL alone.
• If saving a fetched body fails (a full disk, a read-only folder), the fetch fails too.
• Nothing prunes old entries, and nothing locks the cache. Each file is written whole under a temporary name and then renamed, so no file is ever half written. But two programs saving the same URL at once, or a crash between the two renames, can leave a body beside another fetch’s time. Temporary files a crash leaves behind are not cleaned up.

Launch-day weather

This page covers fetching the weather over a launch site at launch time from Open-Meteo, a free weather service, and flying a rocket through it. The weather arrives as a sounding: temperature, pressure, humidity and wind at a column of heights, from the ground up to about 24 km. It is for anyone who wants a flight in a day’s forecast instead of the standard atmosphere with one wind.

How far to trust it. hpr turns Open-Meteo’s answer into a profile that gives back the pressure, temperature, humidity and wind of every level it keeps, to rounding error. That is checked on two recorded answers, below. How good the forecast is depends on the weather model behind it, and nothing here measures that: no flight has been flown in Open-Meteo’s weather and compared with its log, and no forecast has been compared with a weather balloon. The wind on the launch rail is the model’s wind 10 m above the ground. The tests replay recorded answers; the live, encrypted (HTTPS) connection to Open-Meteo was checked once by hand, not in CI.

Code: hpr_net::open_meteo (API reference), written for the first weather increment, M5.2a. It needs the net feature of the hpr crate. Weather from a file you download is on ERA5 weather files, the air a weather balloon measured is on Weather-balloon soundings, and NOAA’s own GFS and RAP forecasts are on NOAA forecasts: GFS and RAP. The choices are in ADR-119: Open-Meteo’s pressure levels as a sounding.

What hpr asks for

Open-Meteo has two services with winds above the ground (its documentation). Both give the output of numerical weather models, hour by hour, on 19 pressure levels: heights named by the air pressure there, in hectopascals (hPa; sea-level pressure is about 1013 hPa). They run from 1000 hPa, about sea level, to 30 hPa, about 24 km up.

hpr asks for the two whole hours around the launch time, in UTC (universal time, the time at Greenwich). On each level it asks for the temperature, relative humidity, wind speed and direction, and the level’s geopotential height. At the ground it asks for the pressure, the temperature and humidity 2 m up, and the wind 10 m up. The request names the units, and hpr refuses an answer in any other. Wind directions are where the wind blows from, clockwise from north, as weather services give them.

The answer goes through hpr-net’s cache (Online data and the cache), so a second request within the “stays fresh” time above is answered from the disk, and offline mode answers from the disk only. An answer hpr can’t read is never saved, so it can’t replace a good copy. hpr writes the site’s latitude and longitude to 5 decimal places, about 1 m on the ground and far finer than any model’s grid. So a site given to 8 decimals or fewer, which your program keeps in radians and turns back into degrees (that can change its last digits), still finds its saved answer. Open-Meteo’s data is licensed CC BY 4.0: show the credit “Weather data by Open-Meteo.com (CC BY 4.0)” wherever you show the weather. Every answer carries it. The free service is for non-commercial use, under 10,000 calls a day (Open-Meteo’s terms). A self-hosted Open-Meteo server can stand in for Open-Meteo’s own: set the request’s endpoint.

How the answer becomes a sounding

• The ground is at the answer’s elevation, with the ground pressure, the 2 m temperature and humidity, and the 10 m wind. Putting the 10 m wind at the ground makes it the wind on the launch rail, rather than jumping to the lowest level’s wind above it (Loft lesson L6: a forecast profile that stepped at its lowest level).
• Levels below the ground are left out. The weather models report all 19 levels everywhere, inventing values beneath high ground. A level is kept only when its pressure is below the ground pressure and its height is above the ground. A level with a missing value at either hour is left out too, and so is one whose relative humidity is outside 0 to 100%. The profile lists every level it left out, and why.
• Heights. The models give a level’s height in geopotential meters, which hpr converts to heights above sea level at the site’s latitude with the World Meteorological Organization’s formula (WMO-No. 8 eq. 12.16, as the atmosphere page explains). Open-Meteo’s documentation calls the value an altitude above sea level, so hpr checks which it is on the two recorded answers. Air pressure falls with height at a rate set by the air’s temperature and humidity (the hypsometric equation), which fixes how thick each layer between two levels must be, in geopotential meters. From 500 to 30 hPa, the recorded layers match that to within 0.03% to 0.13% on average. Read as meters above sea level instead, they would be 0.58% to 0.68% too thin. So they are geopotential meters.
• Between the two hours every value is linear in time. The wind is interpolated by its east and north parts, so a wind that turns through the hour takes the shorter way round.
• Between levels the sounding works as for any other: the temperature and humidity are linear, the pressure is hydrostatic, and the wind is interpolated by its speed and direction (or by its east and north parts, as RocketPy does, if you ask). Above the top level the standard atmosphere continues, and the air is marked as extrapolated.
• Humidity is taken as relative to liquid water. A model that reports it relative to ice at cold levels changes the density there by very little: the two differ by at most 27 Pa of water vapour (near −12 °C), which moves the density by under 0.03% at 400 hPa. Higher up the air is colder and the gap smaller: about 6 Pa at −40 °C, 0.08% even at 30 hPa.

An example

crates/hpr/examples/open_meteo_weather.rs asks for the weather over Spaceport America at 15:30 UTC (9:30 local) on 21 June 2025. It makes five calls:

1. Client::new(transport, Cache::new(folder), Mode::Online) sets up the fetching. The transport is what fetches (Online data and the cache). A real program passes hpr_net::Http::new() and keeps its cache in Cache::platform_dir(). This one never uses the network: a stand-in transport answers with the historical-forecast answer recorded for the tests, which holds 15:00 and 16:00.
2. OpenMeteoRequest::new(latitude, longitude, time, OpenMeteoApi::HistoricalForecast) says what to ask for, and open_meteo::fetch(&client, &request, now) fetches it and reads it at the launch time.
3. profile.sounding(WindInterpolation::SpeedDirection) makes the sounding, and sounding.wind() its wind.
4. hpr_sim::Environment::new(earth, sounding, wind) puts both in a flight’s environment.

The program prints the ground and the levels below 6 km, then the air at the pad and above it next to the standard atmosphere. Last, it flies RocketPy’s Calisto (one of the example rockets) in both, without its parachutes. Run it from a copy of the repository with cargo run --example open_meteo_weather -p hpr --features net. It prints:

Open-Meteo over 32.99° N, 106.97° W at 2025-06-21 15:30 UTC
Weather data by Open-Meteo.com (CC BY 4.0)
freshness: Fetched

level (hPa)   height (m)   temperature (°C)   humidity (%)   wind (m/s)   from (°)
      859.5         1400               29.6             18          3.3        162   the ground
        850         1482               28.2             16          2.9        189
        800         2014               23.4             16          2.8        225
        700         3161               14.5             28          6.8        236
        600         4439                3.3             60          9.8        219
        500         5895               -7.0             70          9.9        200
Below the ground, left out: 1000, 975, 950, 925, 900 hPa

height above the pad (m)   pressure (hPa)   temperature (°C)   density (kg/m³)
     0 Open-Meteo                   859.5               29.6            0.9858
     0 standard                     856.0                5.9            1.0687
  1000 Open-Meteo                   765.2               20.4            0.9058
  1000 standard                     756.3               -0.6            0.9667
  3000 Open-Meteo                   602.9                3.6            0.7565
  3000 standard                     585.2              -13.6            0.7854

Calisto to apogee      apogee (m above the pad)   east of the pad (m)   north (m)
Open-Meteo                                 2880.9                  15.7      -155.6
standard, calm                             2821.3                  -5.1         0.0

freshness: Fetched means the answer came from the transport, not the cache; a second call within the hour would say Cached. The ground is at 1,400 m, so the five levels from 1000 to 900 hPa are left out. That June morning was 24 °C warmer at the pad than the standard atmosphere, and the air was 8% less dense there and 4% less dense 3 km up. Calisto climbs 2.1% higher in it. At apogee it is 156 m south of the pad (and 16 m east), upwind: the wind blows from the south-southeast at the ground, turning to the southwest by 600 m above the pad (2,014 m above sea level), and a rocket just off the rail, still slow, turns into the wind (weathercocking) and flies that way. The calm flight’s 5.1 m west is Earth’s rotation: a climbing rocket is pushed west (the Coriolis effect), and with the rotation turned off it drifts 0.006 m.

How it is checked

The tests in crates/hpr-net/tests/open_meteo.rs use two answers recorded from Open-Meteo for Spaceport America: one from the historical-forecast service (21 June 2025, 15:00 and 16:00 UTC) and one from the forecast service (2 October 2026, 18:00 and 19:00 UTC). No test uses the network.

• At each recorded hour, the sounding is sampled at every kept level’s height. It gives back the recorded pressure to a relative 1e-12, the temperature to 1e-9 K and the wind to 1e-9 m/s, and holds the recorded humidity. The expected values are read from the recording by the test itself, not by the code under test. The ground is checked the same way.
• Both answers leave out exactly the five levels below the 1,400 m ground, and keep 14. Each half of the rule (the pressure, the height) leaves a level out on its own, in an edited answer.
• At 10 and 30 minutes past the hour, every value is the weighted average of the two hours, and the wind the weighted average of its parts. A wind from 350° then 10° is from due north at half past, and a direction never reads 360°.
• A humidity of 100% at both hours stays 100% at any time between; above 100%, a level is left out and the ground refused.
• The request’s address is the one recorded, so a replayed answer fills the cache. A second request is answered from the cache, and offline mode answers without the network. tests/http.rs does the same over HTTP, from a test server on the machine’s own address.
• An answer with an hour’s values missing is not saved: with no earlier copy the request fails, and with one, the earlier copy comes back, marked stale, and stays saved. A saved answer that can’t be read at a later launch time in the same hour is fetched again online, and is the error offline.
• Text that is not JSON, Open-Meteo’s error answer, a unit other than the one asked for, a missing field, hours outside 1970 to 9999, and a time outside the answer’s hours are refused.
• The heights are geopotential, by the hypsometric check above; the test holds each average to the ranges quoted there.

What it leaves out

• Nothing checks a forecast against the weather that came. Weather-balloon soundings, the measured air, can be fetched too (Weather-balloon soundings), but no forecast has been compared with one. NOAA’s Global Forecast System and Rapid Refresh (GFS and RAP) can be fetched by name, or read from a whole GFS file you download (NOAA forecasts: GFS and RAP).
• The 2 m temperature and humidity and the 10 m wind are placed at the ground itself, so the whole launch rail sees the 10 m wind. A real wind is weaker close to the ground; how much that changes a rocket’s turn into the wind off the rail is not measured.
• A relative humidity above 100% at the ground refuses the answer rather than trimming it.
• When Open-Meteo refuses a request (a place or date it doesn’t cover), the error names the HTTP status but not Open-Meteo’s reason, because the HTTP transport drops the body of a failed answer.
• Only one place and one launch time per request, and Open-Meteo’s own choice of weather model unless you name one.
• The command line fetches it with hpr weather open-meteo, but hpr sim doesn’t fly it yet (issue #265), and the Python package doesn’t fetch weather.

Weather-balloon soundings

This page covers fetching a weather balloon’s measurements from the University of Wyoming’s archive and flying a rocket through them. The balloon carries a radiosonde, which measures the air on the way up, from the ground to 30 km or more. What it records is a sounding: temperature, pressure, humidity and wind at a column of heights. Hundreds of stations release one at 00 and 12 UTC (universal time, the time at Greenwich) every day. This page is for anyone who wants a flight in the air that was measured near a launch, instead of a forecast (Launch-day weather, NOAA forecasts: GFS and RAP) or the standard atmosphere.

How far to trust it.

• hpr turns the archive’s answer into a profile that gives back the pressure, temperature, humidity and wind of every level it keeps, to rounding error. That is checked on three recorded soundings, below.
• A sounding is a measurement, but only at its station and time. The nearest station can be 100 km or more from a launch site (Santa Teresa, below, is about 130 km from Spaceport America), and the balloon goes up hours before or after the flight. Nothing here measures how much that changes a flight.
• Each row’s height is checked against the row before it, which catches a gross error in a pressure or height (57 hPa recorded for 557). More than 10 bad rows in a row refuse the answer, and so does a ground that the rows after it agree is wrong. That can refuse a good ground too, when the first few rows after it are a little off. A wrong wind, humidity or temperature is not caught: on layers under about 100 m thick the check allows any temperature from −150 to 80 °C.
• The archive serves two versions of most soundings, and they can disagree near the ground. In the example below, Calisto is 402 m from the pad at apogee in one and 563 m in the other.
• The tests replay recorded answers; the live connection to the archive is not tested in CI.

Code: hpr_net::wyoming (API reference), written for the second weather increment, M5.2b. It needs the net feature of the hpr crate. The choices are in ADR-120: University of Wyoming soundings.

What hpr asks for

A request names a station and the sounding’s hour. The station is its World Meteorological Organization (WMO) number, such as 72364 for Santa Teresa, New Mexico; the archive’s page has a map of them. WyomingRequest::latest_before(station, launch_time) picks the last 00 or 12 UTC sounding at or before a launch, with times in seconds since 1 January 1970 UTC (Unix time). The balloon goes up about an hour before that hour.

hpr asks for the archive’s comma-separated text, one row per level, and reads these columns. Pressures are in hectopascals (hPa, 100 Pa; sea-level pressure is about 1013 hPa).

The units are in the column names, and hpr refuses a file with any other. The archive serves two versions of most soundings:

The coded message holds the standard pressure levels (850, 700, 500 hPa and so on) and the significant levels between them, where the temperature or wind changes its trend.

The answer goes through hpr-net’s cache (Online data and the cache), and wyoming::fetch(&client, &request, now) takes the time now, in Unix seconds, to judge how fresh a saved copy is. For a day after its hour the archive’s copy of a sounding can still fill in, as a station’s later messages arrive:

Offline mode answers from the disk only, however old the copy. An answer hpr can’t read is never saved, so it can’t replace a good copy. A sounding the archive doesn’t have comes back as an HTTP error (404, or 400 for a BUFR file the station doesn’t send), which the request reports; no test covers that.

The archive states no terms of use. Show the credit “Sounding from the University of Wyoming’s radiosonde archive” wherever you show the sounding. Every answer carries it.

How the answer becomes a sounding

Heights. The file gives geopotential meters, which hpr converts to heights above sea level at the first row’s latitude with the World Meteorological Organization’s formula (WMO-No. 8, its Guide to Instruments and Methods of Observation, eqs. 12.15 and 12.16, as the atmosphere page explains). The balloon drifts as it climbs. Converting at the latitude it reached instead would move a height by about 0.8 m per degree of drift at 10 km, and 2.5 m at 30 km; the example’s balloon drifted 0.06°.

Why geopotential. Air pressure falls with height at a rate set by the air’s temperature and humidity. The hypsometric equation turns that into how thick each layer between two pressures must be, in geopotential meters:

thickness = (R_d T̄_v / g₀) ln(p_bottom / p_top)

Here p_bottom and p_top are the pressures at the layer’s bottom and top, R_d is dry air’s gas constant (287.05 J/(kg·K)), g₀ standard gravity (9.80665 m/s²) and T̄_v the mean of the two rows’ virtual temperatures: the temperature, raised a little for the humidity (WMO-No. 8, eqs. 12.17 and 12.18). In the three recorded soundings, across the 13 layers between the standard levels from 850 to 10 hPa, the recorded thicknesses match that to 0.01% to 0.03% on average; single layers are off by 0.05% to 0.13% on average, either way. Read as meters above sea level instead, the layers would be 0.51% to 0.60% too thin on average. So they are geopotential meters, as the column says. The test holds the average under 0.1% as geopotential meters, and more than 0.4% too thin as meters above sea level.

Each row is checked against the row before it. A row with a pressure, height and temperature fits the row before it when its height above that row is the layer’s thickness, give or take an allowance: 5% of the thickness, plus what rounding the two pressures can move it, plus 30 m. The pressures are rounded to 1 hPa in the coded message at 100 hPa or more, and to 0.1 hPa elsewhere. For example, from the coded message’s row at 557 hPa to the next at 549 hPa:

Rows are kept from a chain. hpr looks for the longest chain of rows from the ground in which each row fits the one before it in the chain. The chain may pass by up to 10 rows at a time, and the rows it passes by are left out. Of two chains equally long, it takes the one whose layers fit more closely: the smaller total of each layer’s miss as a share of its allowance (a miss of 25 m with an allowance of 50 m is a share of 0.5).

Why a chain: every row kept must also lie above the last row kept, so one bad row kept can hide the good ones. A 557 hPa row with a digit lost, 57 hPa at 5,035 m, would be kept, and every good row up to 57 hPa, about 20 km, would lie below it and be dropped. It would have to be 18.6 km above the row before it, at 570 hPa, not 183 m, so it doesn’t fit: the chain passes it by, from 570 hPa to 549 hPa, and it is left out. Two or three bad rows that fit each other are passed by the same way, since a chain through them would have to pass by more good rows. A row with no wind or humidity is left out of the profile but can still be in the chain, so the next row is checked across a thin layer, not a thick one. A row with no temperature can’t be checked: the chain steps over it without counting it, and it is left out as missing a value.

In the three recordings every row fits the one before it, missing by at most 1 m beyond rounding. So the 30 m and the 5% are margin, and the check is for gross errors, not small ones:

• The 30 m leaves room for the coded message’s heights from 500 hPa up, which are rounded to 10 m. A height 30 m off misplaces its level by about as much as a 0.33% to 0.55% pressure error (the air’s scale height, the climb over which pressure falls by a factor of e, is 5.5 to 9 km).
• The 5% is a judgment, not a measurement: no row in the recordings needs any of it. It leaves room for a layer whose inner rows have no temperature, where the mean of its two ends’ temperatures gives its thickness less well.

Then hpr keeps:

• The ground, the first row: the pressure, temperature, humidity and wind at the station when the balloon was released. A first row with a value missing or impossible refuses the answer.
• One row of each run of rows in the chain with the same pressure, the middle one. The BUFR file gives pressures to 0.1 hPa, and high up the balloon climbs tens of meters while the pressure falls that much, so runs of rows share one pressure. The rounded value is the pressure at about the middle of its run. In the example, 1,931 of the BUFR file’s 5,851 rows are the other rows of such runs. The coded message has none.
• Each such row that lies above the last row kept, higher and at a lower pressure. Rows that fall or stay at one height, a balloon coming down, fit but don’t lie above, and are left out however many.

It leaves out:

• A row the chain passes by, as above.
• A row with a value missing or impossible: the last row often has no wind, and a pressure below 0.1 hPa or above 1,200 hPa, a temperature outside −150 to 80 °C, a height outside −1 to 60 km, a wind speed below zero or above 300 m/s, a humidity below zero or a direction beyond 360° is dropped the same way.

The profile lists every row it left out, and why. Two things refuse the answer:

• A ground the rows after it disagree with. No row before the ground checks it, so hpr also looks for chains that start after it, at one of the next 11 rows with a pressure, height and temperature within the bounds. If one of them beats every chain from the ground (it is longer, or as long and fits more closely), the ground is taken as wrong. Bad rows right after a good ground can do the same: rows that miss the ground but fit the rows above them, within the allowance, beat it when the chain through them is longer (it passes by fewer good rows than it holds bad ones, less one) or as long and closer. That happens in narrow bands of error, just past the ground’s allowance: in the BUFR file, whose first layers are about 8 m thick, two rows 31 m high refuse the answer, but not 20 m high (they fit the ground and are kept) or 35 m (they fit nothing but each other, and are passed by); in the winter coded message, three rows 45 m high. So do 11 bad rows that fit each other, however far off. hpr can’t tell these from a bad ground, and refuses the answer. Rows grossly off (850 m, say) fit nothing above them and are passed by, up to 10.
• More than 10 rows after the chain’s end. The chain can pass by only 10 rows at a time, so 11 bad rows in a row end it. hpr takes that to mean the chain’s end is wrong, or all of them are (a block of heights 1 km off). A long run of rows with no temperature can also refuse the answer: the layer across the run is then too thick for its two ends’ temperatures to give. In a BUFR file 10 rows are about 10 s of the climb, some 50 m; in a coded message they can span kilometers.

A refused answer names the lines and is not cached; the other version, or the sounding 12 hours earlier, may be usable instead.

In the profile:

• Humidity above 100%, which radiosondes can report in cloud, is kept in the level as recorded and taken as 100%.
• Between levels the sounding works as for any other: the temperature and humidity are linear, and the pressure is hydrostatic (as the atmosphere page explains). The wind is interpolated by its speed and direction; pass WindInterpolation::Components to interpolate its east and north parts instead, as RocketPy does. Above the top level the standard atmosphere continues, and the air is marked as extrapolated.

An example

crates/hpr/examples/wyoming_sounding.rs fetches the Santa Teresa sounding a launch at 15:30 UTC on 21 June 2025 would have had, in both versions, and flies Calisto (one of the example rockets) from the station without its parachutes. It makes these calls:

1. Client::new(transport, Cache::new(folder), Mode::Online) sets up the fetching. A real program passes hpr_net::Http::new() as the transport (what fetches) and keeps its cache in Cache::platform_dir(). This one never uses the network: a stand-in transport answers with the two versions recorded for the tests.
2. WyomingRequest::latest_before("72364", launch_time) picks the 12 UTC sounding, and wyoming::fetch(&client, &request, now) fetches and reads it. Setting the request’s version to WyomingVersion::Bufr asks for the BUFR file instead.
3. sounding.sounding(WindInterpolation::SpeedDirection) makes the profile, and profile.wind() its wind.
4. hpr_sim::Environment::new(earth, profile, wind) puts both in a flight’s environment.

It prints the ground and five standard levels, with heights in meters above sea level, and each version’s second row. Then it prints the air at the pad and above it next to the standard atmosphere, and where Calisto is at apogee: east and north of the pad, negative for west and south. Each flight starts on its own sounding’s ground. The third flight keeps the BUFR file’s ground row and its rows from 1,438 geopotential meters up (the height of the coded message’s second row), dropping those between. Run it from a copy of the repository with cargo run --example wyoming_sounding -p hpr --features net. It prints:

Santa Teresa, New Mexico (72364), 2025-06-21 12 UTC
Sounding from the University of Wyoming's radiosonde archive
freshness: Fetched
released 58 minutes before 12 UTC
coded message: 227 levels kept, 1 left out
BUFR file: 3920 levels kept, 1931 left out

level (hPa)   height (m)   temperature (°C)   humidity (%)   wind (m/s)   from (°)
        872         1254               28.4             31          5.7        265   the ground
        850         1482               26.6             32         11.8        270
        700         3165               14.6             36          2.6        215
        500         5903               -5.3             63          8.2        180
        250        11002              -40.1              7         13.9        260
        100        16724              -73.1             13         13.9        255

second row       above the ground (m)   wind (m/s)   from (°)
coded message                     186         10.7        269
BUFR file                           8         11.1        264

height above the pad (m)   pressure (hPa)   temperature (°C)   density (kg/m³)
     0 sounding                     872.0               28.4            1.0022
     0 standard                     871.4                6.9            1.0842
  1000 sounding                     778.5               22.3            0.9151
  1000 standard                     770.3                0.4            0.9811
  3000 sounding                     613.5                4.9            0.7664
  3000 standard                     596.5              -12.6            0.7977

Calisto to apogee      apogee (m above the pad)   east of the pad (m)   north (m)
coded message                              2848.1                -401.4       -23.4
BUFR file                                  2822.5                -561.3       -48.0
BUFR above 1,438 m                         2845.9                -419.1       -19.1
standard, calm                             2811.0                  -5.1         0.0

freshness: Fetched means the answer came from the transport, not the cache. That early morning (6 a.m. local) was 21.5 °C warmer at the station than the standard atmosphere, and the air was 7.6% less dense at the ground and 3.9% less dense 3 km up. Calisto climbs 1.3% higher in it than in the standard atmosphere with no wind; the thinner air and the wind both play a part.

At apogee Calisto is about 400 m west of the pad, upwind: the wind blows from the west, and a rocket just off the rail, still slow, turns into the wind (weathercocking) and flies that way. The calm flight’s 5.1 m west is Earth’s rotation: a climbing rocket is pushed west (the Coriolis effect), as on the Launch-day weather page.

The two versions put Calisto’s apogee 26 m apart, and the BUFR flight 160 m further west. Most of that is the first 186 m of the climb. Both start from the station’s wind at the ground, 5.7 m/s. The coded message’s second row, 186 m up, is 10.7 m/s from the west, so its wind grows steadily over that climb. In the BUFR file the wind is already 11.1 m/s 8 m above the ground, where the rocket is slowest and turns into the wind the most. Without its rows below 1,438 geopotential meters the BUFR flight is 419 m west at apogee and peaks at 2,846 m, within 18 m and 2 m of the coded message’s. Which of the two is nearer the wind a rocket meets is not measured: a balloon’s first seconds of drift are not a steady wind either.

How it is checked

The tests in crates/hpr-net/tests/wyoming.rs use three answers recorded from the archive: Santa Teresa on 21 June 2025 at 12 UTC in both versions, and Salt Lake City on 15 January 2025 at 12 UTC, a winter sounding. No test uses the network.

• The sounding is sampled at every kept row’s height. It gives back the recorded pressure to a relative 1e-12, the temperature to 1e-9 K, the humidity to 1e-15 and the wind to 1e-9 m/s. The test reads the expected values from the recording itself, not through the code under test, and applies the rules above on its own.
• The rows left out are exactly those the rules leave out: the last row of each coded message (no wind), and 1,931 rows of the BUFR file (the other rows of a run). The coded messages keep 227 and 241 rows, the BUFR file 3,920.
• Every BUFR row, kept or not, lies within 0.08 hPa of the profile’s pressure at its height; the worst is 0.071 hPa. Keeping the first row of each run instead would miss by 0.093 hPa.
• The ground’s wind, 5.7 m/s from 265°, is checked against its east and north parts worked out by hand: 5.678 m/s east and 0.497 m/s north.
• An edited file drops a row with a missing temperature; one with a humidity below zero, a temperature of −999 °C, a negative wind speed or pressure, or a direction of 361°; one that fits but lies below the last row kept (and not merely the row before); and a row at the ground’s pressure. The rows left out are listed in line order. A humidity of 103% is kept and taken as 100%, and a wind from 360° reads as from north.
• Every row with a pressure, height and temperature in the three recordings fits the one before it, missing by at most 1 m beyond rounding (0 m in the coded messages, 0.97 m in the BUFR file). The test works out the thickness on its own, with the file’s mixing ratio (grams of water vapour per kilogram of dry air) for the humidity. Unit tests pin the check, and the worked example above, to thicknesses and allowances worked out by hand, 0.01 m either side of the edge.
• Rows the chain passes by, with the rest of the answer kept:
  • A pressure missing a digit (57 hPa at 5 km); the profile is the recording’s without the row.
  • A height raised 850 m, and a height lowered to 4,000 m.
  • Two bad rows in a row, and two blocks of six raised rows with a good row between them.
  • A bad row after which the balloon bursts and falls back.
  • A row whose vapour pressure would exceed the air’s pressure (16 hPa at 30 °C, saturated).
  • A row that only just fits the row before it, alone: 854 hPa 50 m low, 101 hPa 95 m high, and a BUFR row at 112.8 hPa 35 m high. The next row misses it, and a chain through it is not longer and fits less closely. The rows before and after it are kept.
  • A row that misses the good row before it but only just fits the one below that, alone: 808 hPa raised 50 m, and a BUFR row at 244.2 hPa raised 35 m. A chain could skip the good row to reach it, but the chain through the good row is longer, or as long and closer.
  • A BUFR row at 150.6 hPa raised 50 m, whose pressure is rounded to 0.1 hPa. In the coded message, 549 hPa raised 45 m fits within its pressures’ 1 hPa rounding and is kept.
  • Blocks of bad rows that fit each other but not the good rows beside them, which are kept: 820 and 808 hPa raised 50 m; 101, 100 and 99 hPa raised 100 m; BUFR rows at 112.8 and 112.7 hPa raised 50 m; and two BUFR rows at 13.9 hPa lowered 50 m, and two at 10.1 hPa lowered 60 m, each inside a run sharing one pressure.
  • The two or three rows after the ground raised 850 m; the ground and the rest are kept.
  • A row inserted at 870 hPa recorded 65 m above the ground, where the air’s thickness puts it about 20 m up. It misses the ground, but the next row fits the ground, and a chain starting at the inserted row fits less closely: the row is left out and the answer is not refused.
• Rows kept or left out as they fit:
  • With no wind, or no humidity, from 250 to 55 hPa (73 rows), every row after the gap fits and is kept. Checked across the gap instead, the next row would not fit.
  • Rows falling or staying at one height at the end are left out without refusing the answer. When a row that fits and lies above follows them, the rows are left out and the row is kept. Of rows crossing back and forth over the last row kept, the first above it is kept.
  • A BUFR run of three rows at one pressure whose middle is raised 100 m keeps its first row.
  • A row at 0.1 hPa and −150 °C, 55.6 km up, fits the row below it and is kept.
• Answers refused:
  • A block of 10 rows raised 1 km is left out; 11 refuse the answer.
  • In the coded message, a ground at 87.2 hPa (872 with its decimal point misplaced), at 125 m (1,252 m with a digit lost), 8 hPa off, or 52 m or 80 m high; and a BUFR ground 34 m high, whose first layer is 8 m thick. Also a ground at 1,200 hPa, at −1,000 m or at −150 °C: these are within the bounds, but no row above fits them. In the coded message a ground 40 m high, or at 80 °C, fits the first layer (186 m thick) and is kept with every row. With only one row after a bad ground, the ground is kept and the row left out. A row with no temperature right after a bad ground isn’t counted: the refusal names the row after it.
  • Rows after a good ground that beat it: two raised 31 m and four lowered 35 m in the BUFR file; three raised 45 m in the winter coded message and four raised 50 m in the other; and 11 rows raised 1 km. Two BUFR rows raised 20 m fit the ground and are kept, leaving out the three good rows no higher than them. Two BUFR rows raised 35 m, and 10 coded-message rows raised 1 km, are passed by. A chain without the ground may start only at the 11 rows after it: after 11 rows that fit nothing, the answer is refused for the gap.
• A row raised within its allowance is kept, and leaves out the good rows just above it, which now lie below it. Raising one row, or a block of two or three, by 20, 35, 50 or 100 m, or lowering it by 50 or 100 m, refuses no answer. It loses at most 2 other levels of a coded message. In the BUFR file, sampled at every 150th row (to keep the test under a minute) and at the rows where a sweep of every row (run once, not in the tests) found the worst, it loses at most 8 other rows for one row and 10, about 50 m of the climb, for a block. Lowering one row, or changing its pressure by 3%, loses no other.
• Values just past the bounds above are left out. Unit tests keep values at each bound; at the top row, temperatures of −150 and 80 °C and a wind of 300 m/s are kept and make a profile.
• The request’s address is the one recorded, so a replayed answer fills the cache. A second request is answered from the cache, and offline mode answers without the network. A copy saved while the sounding was young is fetched again once it has settled.
• An answer that isn’t the archive’s text (such as an error page) is not saved: with no earlier copy the request fails, and with one, the earlier copy comes back, marked stale.
• Text with no header, a missing or doubled column, a unit other than the one required, a row with too few or too many fields, a field that isn’t a number, a first row with no date, and a first row with a value missing are refused. A header or a row of a million commas, and more than 100,000 rows, are refused without being read further.
• The heights are geopotential, by the hypsometric check above: the test holds each average under 0.1% as geopotential meters, and more than 0.4% too thin as meters above sea level.

What it leaves out

• How far a station’s sounding is from the air over a launch site is not measured, in distance or in time. A rocket flown hours from the balloon, 100 km away, flies other air.
• Which version is nearer the truth near the ground, where they differ most, is not known.
• A level with any value missing is left out whole, even when its other values are good.
• The check catches a gross error in a row’s pressure or height. It keeps:
  • A wrong wind, or a wrong humidity: the check doesn’t use the wind, and humidity moves the thickness by only a few percent (1.6% for saturated air at 30 °C and sea-level pressure). Only a wind outside 0 to 300 m/s is caught.
  • A wrong temperature that keeps the thickness within the allowance, and a height error within it: 50 m on the example’s layer, more on thicker ones.
  • A row whose pressure and height are both wrong yet fit each other.
  • A wrong ground that fits the row after it (in the coded message, 40 m high, or 80 °C instead of 28.4 °C), or has only one row after it.
  • Bad rows that fit their neighbours: a block of them can be kept, and good rows beside them passed by instead, no more than the block holds, and fewer unless the block fits more closely. In the coded message, 683 and 673 hPa both raised 50 m are kept, and 664 hPa is left out. High in a BUFR file, where rounding the pressure to 0.1 hPa widens the allowance, four rows at 13.9 hPa lowered 50 m are kept, and the two good rows at 14.0 hPa before them are left out.
• A good ground followed by bad rows that fit the rows above them is refused, as if the ground were wrong, when the chain through them wins: two BUFR rows 31 m high do it.
• A row, or a short block, kept a little too high leaves out the good rows just above it: in the tests, at most 2 other levels of a coded message and 10 other rows of a BUFR file (8 for one row).
• Only the archive’s comma-separated text is read, not its other formats, and there is no list of stations to search by place.
• Its terms of use are not stated; only soundings from U.S. stations, which are U.S. government works, are committed as test data (ADR-120).
• The command line fetches them with hpr weather wyoming, but hpr sim doesn’t fly them yet (issue #265), and the Python package doesn’t fetch soundings.

NOAA forecasts: GFS and RAP

This page covers fetching the United States weather service’s own forecasts over a launch site and flying a rocket through them. NOAA’s National Centers for Environmental Prediction (NCEP) run two weather models whose output hpr reads:

• the Global Forecast System (GFS), which covers the whole Earth on a grid a quarter of a degree apart (about 28 km), and
• the Rapid Refresh (RAP), which covers the contiguous United States and nearby parts of Canada and Mexico on a grid 13 km apart, and is started again every hour.

hpr asks NOAA’s download server, NOMADS (NOAA Operational Model Archive and Distribution System), for a small piece of one forecast around the site. The piece arrives as a GRIB2 file, the World Meteorological Organization’s binary format for weather on a grid, and hpr reads it with its own decoder. The result is a sounding: temperature, pressure, humidity and wind at a column of heights, from the ground up to about 31 km (GFS) or 16 km (RAP). You can also download a whole GFS file and read it offline, which goes up to about 79 km (A whole GFS file). This page is for anyone who wants a flight in a named NOAA model’s forecast, rather than Open-Meteo’s choice of model (Launch-day weather) or a weather balloon’s measurement (Weather-balloon soundings).

How far to trust it.

• hpr’s decoder gives every value in the two recorded files that ecCodes, the European weather center’s reference decoder, gives: all 6,123 values within 2.2e-16 of each other, relatively (one rounding in the last binary digit). The profile gives back those values, interpolated to the site, at every level it keeps. That is checked below.
• A whole GFS file you download yourself reads too (A whole GFS file): every one of the 746,770,303 values in one such file is within 4.4e-16 of ecCodes’, relatively, and its profile at Spaceport America is the recorded cut’s to 1.04e-7. That check was a script run once outside CI; CI checks eight of the file’s messages.
• How good a forecast is depends on the model, and nothing here measures that: no forecast has been compared with a weather balloon or a flight log.
• The pad sits on the model’s ground, which is smoothed: at Spaceport America it is 1,476 m in GFS and 1,429 m in RAP, where Open-Meteo gives 1,400 m (Launch-day weather’s example).
• Fields packed as JPEG 2000 images, as in RAP’s whole files, read too: four public RAP fields, 182,443 points, match ecCodes in CI (Files in JPEG 2000). No whole RAP file has been tried.
• The tests replay two recorded answers; the live connection to NOMADS is not tested in CI.

Code: hpr_net::nomads (API reference), with the decoder in hpr_io::grib2 (API reference), written for the third weather increment, M5.2c, and extended to whole GFS files in M5.2d2 and to JPEG 2000 in M5.2d3. It needs the net feature of the hpr crate. The choices are in ADR-121: GFS and RAP from NOMADS’ grib filter, read by an in-house GRIB2 decoder and ADR-123: Complex packing, and a whole GFS file, and ADR-124: JPEG 2000 packing.

What hpr asks for

A forecast comes from a run: the model starts from the weather observed at one hour, its cycle, and steps forward. Each forecast hour is the forecast for that many hours after the cycle. Times are in UTC (universal time, the time at Greenwich) and given in seconds since 1 January 1970 UTC (Unix time). Pressures are in hectopascals (hPa, 100 Pa; sea-level pressure is about 1013 hPa). A pressure level is a height named by the pressure there.

NomadsRequest::new(latitude, longitude, model, cycle, forecast_hour) says what to ask for; it can’t fail. The request’s url(), and so nomads::fetch, refuse a cycle the model doesn’t run or a forecast hour its run doesn’t have (NomadsModel::has_forecast_hour(cycle_hour, hour) says which it has). hpr picks neither for you: to fly at 18 UTC, ask for GFS’s 00 UTC run at hour 18, say, or RAP’s 12 UTC run at hour 6. A site outside the model’s grid is refused once the answer arrives.

The request’s address is NOMADS’ grib filter, a web form that cuts chosen variables, levels and a box of latitude and longitude out of a run’s file. hpr asks for a box 0.3° each way around the site, which holds 9 GFS or about 25 RAP grid points, among them the four around the site: about 28 KB for GFS and 40 KB for RAP. The box’s edges are written to hundredths of a degree, worked out from the site rounded to 5 decimals (about 1 m). So a site given to 8 decimals or fewer, which your program keeps in radians and turns back into degrees (that can change its last digits), asks for the same box and finds its saved answer. It asks for:

GRIB2 fixes each variable’s unit, so there are no units to check. The filter also sends the ground’s own (skin) temperature, since it asks for temperature at the surface; hpr decodes it but doesn’t use it. With it, a cut holds 147 GFS or 192 RAP messages, one variable on one level each. A cut of more than 1,000 is refused unread.

The answer goes through hpr-net’s cache (Online data and the cache), and nomads::fetch(&client, &request, now) takes the time now, in Unix seconds, to judge how fresh a saved copy is. A run’s files don’t change once NOAA writes them, so a saved copy stays fresh for 30 days. NOMADS keeps only recent runs; on 2026-09-30 its grib filters listed 10 days of GFS runs and 2 of RAP, so a past launch needs a copy saved while NOMADS still had it. A run appears on NOMADS some hours after its start time, and NOMADS limits how often one may ask, so keep to that. Offline mode answers from the disk only. Only an answer that decodes, makes a sounding, and is for the run and hour asked for is saved, so a bad answer can’t replace a good copy.

NCEP’s forecasts are U.S. government works, free of copyright. Every answer carries the credit “Forecast data from NOAA/NCEP (GFS, RAP), via NOMADS”; show it wherever you show the forecast.

How the answer becomes a sounding

Between grid points. A model gives each value only at its grid points. hpr takes the four around the site and blends them bilinearly: each point’s weight grows as the site nears it, in the grid’s own rows and columns, and the four weights add up to 1. A cut whose grid steps and projection aren’t the model’s (GFS’s 0.25° steps, RAP’s 13,545 m cells about 265° E) is refused and not saved.

The ground is at the model’s terrain height at the site, with the surface pressure, the 2 m temperature and humidity, and the 10 m wind. Putting the 10 m wind at the ground makes it the wind on the launch rail, rather than jumping to the lowest level’s wind above it (Loft lesson L6: a forecast profile that stepped at its lowest level). This is what Open-Meteo’s page does too.

Levels below the ground are left out. The models give every level everywhere, inventing values beneath high ground. A level is kept only when its pressure is below the ground’s and its height is above the ground. A level with a value missing at any of the four grid points is left out too. At Spaceport America, about 1,400 m up, six levels are underground in each model: 1000 to 850 hPa in GFS and 1000 to 875 hPa in RAP. GFS keeps 22 of its 28 levels and RAP 31 of its 37. The profile lists every level it left out, and why.

Heights. GRIB2 gives heights in geopotential meters, which hpr converts to heights above sea level at the site’s latitude with the World Meteorological Organization’s formula (WMO-No. 8 eq. 12.16, as the atmosphere page explains). The model’s terrain height is also given in geopotential meters and converted the same way. At this latitude that adds about 2 m: GFS’s 1,474.4 gpm becomes 1,476.4 m. If the model’s terrain were really a height above sea level, as for Open-Meteo’s elevation, the ground would sit about 2 m too high.

RAP’s winds are turned to east and north. RAP’s map is a cone unrolled flat (a Lambert conformal projection), and it gives each wind as two components along its map’s rows and columns, not east and north. “Up” on that map points true north only along one line of longitude, 95° W. Elsewhere the lines of longitude lean towards the map’s center, so the map’s “up” is turned from true north by an angle that grows with the distance from 95° W:

θ = n (λ − λ₀),   n = sin 25°,   λ₀ = 265° (95° W)

Here λ is the site’s longitude, and 25° N is where RAP’s cone touches the Earth. At Spaceport America, 106.97° W (253.03° E), θ = 0.4226 × (253.03° − 265°) = −5.06°: the map’s “up” points 5.06° west of true north. hpr turns the wind by that angle, with u and v the components along the map’s rows and columns:

east  =  u cos θ + v sin θ
north = −u sin θ + v cos θ

Left unturned, a 20 m/s wind would be about 1.8 m/s off sideways (20 m/s × sin 5.06°). The components are blended between grid points first and turned once, at the site; across one 13 km cell θ changes by about 0.06°. GFS gives its winds east and north already.

Humidity is taken as relative to liquid water, as for Open-Meteo. Whether NCEP’s models give it relative to ice at cold levels is not settled here; if they do, the density there moves by under 0.1% (Launch-day weather explains the bound). A humidity above 100% is kept in the level as given and taken as 100% in the sounding.

Between levels the sounding works as for any other: the temperature and humidity are linear, and the pressure is hydrostatic. The wind is interpolated by its speed and direction; pass WindInterpolation::Components to interpolate its east and north parts instead, as RocketPy does.

An example

crates/hpr/examples/nomads_forecast.rs fetches both models’ forecasts for Spaceport America at 18 UTC (noon local) on 30 September 2026: GFS’s 00 UTC run at hour 18 and RAP’s 12 UTC run at hour 6. It flies Calisto (one of the example rockets) through each, without its parachutes. It makes these calls:

1. Client::new(transport, Cache::new(folder), Mode::Online) sets up the fetching. A real program passes hpr_net::Http::new() as the transport (what fetches) and keeps its cache in Cache::platform_dir(). This one never uses the network: a stand-in transport answers with the two files recorded for the tests.
2. NomadsRequest::new(latitude, longitude, NomadsModel::Gfs, cycle, 18) says what to ask for (and NomadsModel::Rap for RAP), and nomads::fetch(&client, &request, now) fetches it and reads it at the site. Here it reads the two recorded forecasts, as a real program would fetch them.
3. profile.sounding(WindInterpolation::SpeedDirection) makes the sounding, and sounding.wind() its wind.
4. hpr_sim::Environment::new(earth, sounding, wind) puts both in a flight’s environment.

It prints each model’s ground and the standard levels 850, 700, 500, 250 and 100 hPa that lie above it, with heights in meters above sea level and the wind’s direction as where it blows from, clockwise from north. Then it prints where Calisto is at apogee: east and north of the pad, negative for west and south. Each flight starts on its own model’s ground; the standard-atmosphere flight starts on GFS’s. Run it from a copy of the repository with cargo run --example nomads_forecast -p hpr --features net. It prints:

Spaceport America, 2026-09-30 18 UTC
Forecast data from NOAA/NCEP (GFS, RAP), via NOMADS
freshness: Fetched
GFS: run of 00 UTC, hour 18: 22 levels kept, 6 left out
RAP: run of 12 UTC, hour 6: 31 levels kept, 6 left out
RAP's winds turned by -5.06° to east and north

GFS   level (hPa)   height (m)   temperature (°C)   humidity (%)   wind (m/s)   from (°)
              848         1476               19.3             42          5.5        242   the ground
              700         3077                2.8             90          7.3        262
              500         5720              -12.9             55         17.0        246
              250        10822              -32.7              1         45.8        230
              100        16741              -70.6             17         17.7        209

RAP   level (hPa)   height (m)   temperature (°C)   humidity (%)   wind (m/s)   from (°)
              854         1429               16.9             70          3.7        246   the ground
              850         1463               16.1             67          4.4        249
              700         3076                2.6             77          8.1        272
              500         5722              -12.0             39         20.5        242
              250        10822              -32.6              1         42.9        231
              100        16739              -70.8             10         13.0        211

Calisto to apogee      apogee (m above the pad)   east of the pad (m)   north (m)
GFS                                        2842.8                -253.0      -131.7
RAP                                        2841.3                -204.3       -83.9
standard, calm                             2826.9                  -5.1         0.0

freshness: Fetched means the answer came from the transport, not the cache; a second call within 30 days would say Cached. GFS has no 850 hPa row because its ground, at 848 hPa, is above that level. The two models agree closely aloft: at 500 hPa their heights are 2 m apart and their temperatures 0.9 °C. Near the ground they differ more: GFS’s ground is 47 m higher and 2.4 °C warmer, and its 10 m wind 1.8 m/s stronger.

Calisto climbs 14 to 16 m higher in either forecast than in the standard atmosphere with no wind. At apogee it is west-southwest of the pad, upwind: the wind at the ground blows from the west-southwest (242° and 246°), and a rocket just off the rail, still slow, turns into the wind (weathercocking) and flies that way. GFS’s stronger wind near the ground turns it further into the wind; it ends 49 m further west and 48 m further south than in RAP’s forecast. How much of that comes from the ground’s wind and how much from the winds aloft is not separated. The calm flight’s 5.1 m west is Earth’s rotation: a climbing rocket is pushed west (the Coriolis effect), as on the Launch-day weather page. Which model is nearer the air Calisto would have met is not measured.

A whole GFS file

Instead of asking NOMADS for a cut, you can download a whole GFS file and read it offline, for example before driving out to a launch with no signal. NOMADS keeps the most recent runs, and NOAA’s open data bucket on Amazon’s cloud older ones. A file holds one run’s forecast for one hour over the whole Earth, about 550 MB:

https://nomads.ncep.noaa.gov/pub/data/nccf/com/gfs/prod/gfs.20260930/00/atmos/gfs.t00z.pgrb2.0p25.f018
https://noaa-gfs-bdp-pds.s3.amazonaws.com/gfs.20260930/00/atmos/gfs.t00z.pgrb2.0p25.f018

Here 20260930/00 and t00z are the run (00 UTC on 30 September 2026) and f018 the forecast hour. Only the 0.25° files (pgrb2.0p25) read: the smaller 0.5° and 1° files are refused, since hpr checks the file is on GFS’s 0.25° grid. The command line reads the file as it reads a saved cut, with the site you want: hpr weather gfs --latitude 32.99 --longitude -106.97 --cycle 2026-09-30T00Z --hour 18 --from gfs.t00z.pgrb2.0p25.f018 --output profile.json. It took about a third of a second on a Mac.

NCEP packs whole files more tightly than the grib filter’s cuts, with GRIB2’s complex packing: the values are split into groups, each with its own smallest value and number of bits, and most fields store the differences between neighbouring values rather than the values (spatial differencing). GRIB2 numbers these packings as templates 5.2 and 5.3; hpr’s decoder reads both. A whole file also holds 743 messages where a cut holds 147:

• totals and averages over a time span, such as the rain that fell in the last six hours, which hpr reads but the profile doesn’t use;
• values for a layer between two heights, such as the humidity from the ground to mid-air, which hpr skips because they don’t belong to one level;
• every pressure level up to 0.01 hPa, so the profile goes on above 10 hPa, where a cut stops. In the profile hpr writes from this file, the 0.01 hPa level is 79.2 km above sea level. The highest levels are near the top of the model, and nothing here checks how good its forecast is there.

The grid runs all the way round the Earth, so hpr joins its last column to its first: a site between 359.75° and 0° of longitude still has four grid points around it (checked by a_grid_round_the_earth_wraps_its_columns in crates/hpr-net/tests/nomads.rs).

For that run and hour at Spaceport America, the whole file’s profile has the cut’s 22 levels, within 1.04e-7 of each value, relatively, and 13 more above them. Why they differ at all: NOMADS packs its cuts again in fewer bits. Read with ecCodes, without hpr, the two files already differ by up to 2.4e-6, relatively, at the cut’s grid points.

Files in JPEG 2000

Some of NCEP’s files compress each field as a picture: the packed whole numbers become a greyscale image, stored in the JPEG 2000 image format (GRIB2’s template 5.40). RAP’s whole pressure-level files are packed this way. hpr decodes them with hayro-jpeg2000, a JPEG 2000 decoder written in Rust, then turns each whole number into a value as it does for the other packings.

A lossless image gives back exactly the numbers packed into it; a lossy one gives back approximations. hpr reads lossless images of up to 21 bits a value, coded the way NCEP codes them; the four RAP fields below have 6 to 16 bits. Anything else is refused, naming what it is: a lossy image, one with more bits, or one coded some other way. The limit of 21 bits comes from the decoder’s arithmetic: it works in 32-bit floats, which keep whole numbers exact only up to 16,777,216, and its intermediate sums run about 8 times larger than the values. A field with a bitmap is stored as one row of its values, and the decoder takes at most 60,000 in a row, so such a field of more values is refused too.

A picture has to be decoded whole, so reading one point decodes the whole field; read all the values you need in one go (Field::values_at), as hpr weather does. A whole RAP file through hpr weather rap --from has not been tried: no whole RAP file was downloaded, only four of its fields (How it is checked).

How it is checked

The tests in crates/hpr-net/tests/nomads.rs use the two files the example reads, recorded unchanged from NOMADS’ grib filter on 30 September 2026 for Spaceport America (32.99° N, 106.97° W): GFS’s 00 UTC run at hour 18 (27,586 bytes) and RAP’s 12 UTC run at hour 6 (40,026 bytes), both for 18 UTC. No test uses the network. The expected values come from ecCodes 2.49.0, the European Centre for Medium-Range Weather Forecasts’ decoder, run on the same files by validation/oracles/grib2/eccodes_dump.py and committed as crates/hpr-net/tests/fixtures/nomads-eccodes.json. The tests read that file directly, not through the decoder under test.

Each line gives what was measured, then the bound the test holds it to.

All the measurements below were made on macOS; CI runs the same tests with the same bounds on Linux and Windows.

• Every value. Each of the 147 GFS messages (9 grid points each) and 192 RAP messages (25 grid points each) names the same variable, level and times as ecCodes, and all 6,123 values are within 2.2e-16 of ecCodes’, relatively (bound 2.5e-16). That is one rounding: ecCodes multiplies by an inexact 10^−D where hpr divides by an exact 10^D. It uses only basic arithmetic, which is the same on every platform.

• Every grid point’s position is within 5.7e-14° of ecCodes’ (bound 1e-12°, since other platforms’ maths libraries can differ in the last digits). The four points’ weights add up to 1, and the blend of their positions is the site, to 1e-5°.

• RAP’s wind turn is sin 25° × (λ − 265°), −5.06° at the site. ecCodes’ own positions of two neighbouring grid points show the map’s rows bearing 90° + θ from north, to 2.2e-6° (bound 3e-6°), which pins the sign. GFS’s winds are not turned.

• The profile. The sounding is sampled at the ground and every kept level’s height. It gives back ecCodes’ values interpolated to the site: the pressure within a relative 1e-13, the temperature within 1e-11 K and the wind within 1e-11 m/s, and each level holds the humidity within 1e-14. The six underground levels of each model are the ones left out.

• The heights are geopotential meters. From 500 hPa up, each layer’s thickness matches what the hypsometric equation gives it when the file’s heights are read as geopotential meters, on average to −0.002% (GFS, 15 layers to 10 hPa) and −0.08% (RAP, 16 layers to 100 hPa). Read as meters above sea level, the layers would be 0.63% and 0.51% too thin. The test holds each average to those figures as rounded.

• The two models read alike for the same hour: their 2 m temperatures within 3 K, their 500 hPa heights within 30 m and their 500 hPa winds within 5 m/s. That is a guard against a misread file, not a check of either forecast.

• The cache. The request’s address is the one recorded, so a replayed answer fills the cache. A second request is answered from the cache, and offline mode answers without the network, 40 days later, marked stale.

• Wrong answers aren’t saved. A RAP request answered with a GFS cut, and a cut of another run or hour than the one asked for, are refused and not saved. A GFS cut whose steps are changed to 0.5° still reads, but is not GFS’s grid, so it would be refused too.

• Humidity. A humidity over 100% is kept in the level and taken as 100% in the sounding (a unit test).

• Missing and hostile data. A level whose field has no value at one of the four points around the site is left out as missing data; a cut of more than 1,000 fields is refused before it is read (a real one has 147 or 192).

• A whole GFS file (the 00 UTC run of 30 September 2026 at hour 18, 550 MB, not committed):

  check	where it runs	measured	bound
  every one of its 746,770,303 values against ecCodes’, relatively	a script, run once outside CI	4.4e-16	none
  its 24,642,017 grid points without a value are ecCodes’	the same script	all the same	all
  eight whole messages cut from it, one of each kind: which field each is, its points without a value, and every 997th value	CI	4.4e-16 or less	4.5e-16
  the same eight messages: two sums over all their values	CI	within the bound	1.35e-15 of the terms’ sizes
  hpr weather writes the cut’s profile from it, relatively	a test skipped in CI, which doesn’t have the file	1.04e-7	1.1e-7

  The script is validation/oracles/grib2/whole_file.py; its record, with ecCodes’ survey of the file, is gfs-whole-file.json. The sums catch a value decoded wrong anywhere in a message: off by a single packing step, a value would move a sum at least 23,000 times more than the bound allows.

• Complex packing in CI. The recorded GFS cut, packed again by ecCodes with complex packing and both orders of differencing (repack.py), goes through every check above: its 1,323 values match ecCodes’ to one rounding (bound 2.5e-16), and its profile matches at every level. hpr weather writes its profile, which is the cut’s within 6.9e-8, relatively (bound 7e-8).

• JPEG 2000 in CI. Four fields cut unchanged from RAP’s run of 00 UTC, 30 September 2026: 500 hPa temperature on RAP’s 13 km grid (151,987 points) and on a coarser one (10,152), and the heights of cloud base and cloud top, which have a value only where there is cloud (6,824 and 434 points of 10,152). Their 182,443 points match ecCodes’ reading: which points have no value, the plain sum of every value and a sum weighted by each point’s position (which catches a value in the wrong place), and every 13th value alone (rap_messages_in_jpeg2000_decode_to_eccodes_values in crates/hpr-io/tests/grib2_gfs.rs; ecCodes’ reading is written by validation/oracles/grib2/whole_file.py cut-rap, ADR-124). A damaged image is refused, never a crash: damaged_jpeg2000_never_panics in crates/hpr-io/src/grib2/tests.rs changes bytes of one at random, 256 times in CI, and another test cuts it short at every length.

• Refusals. A site outside the file’s grid, text that isn’t GRIB2, a cycle the model doesn’t run and a forecast hour its run doesn’t have are refused. The decoder’s own tests build small files by hand to pin the unpacking formula, bitmaps (masks of grid points with no value), both kinds of grid, complex packing’s groups, missing values and both orders of differencing, and refusals of every other kind of file by name.

What it leaves out

• Other JPEG 2000. A lossy image, one of more than 21 bits a value, one coded otherwise than NCEP codes, or a bitmap field of more than 60,000 values is refused by name (Files in JPEG 2000).
• Whole RAP files. Their packing is read, but a whole file has not been run through hpr weather.
• Coarser GFS files. GFS’s 0.5° and 1° files are refused: hpr checks for the 0.25° grid.
• Forecast accuracy. Nothing here checks a forecast against the weather that came.
• Time. One forecast hour per request, with no interpolation between hours: you pick the run and the hour closest to your launch.
• Above the top level. RAP stops at 100 hPa, about 16 km, and GFS as asked for here at 10 hPa, about 31 km (a whole GFS file goes on to 0.01 hPa, about 79 km, and the layer thickness check above stops at 10 hPa). Above that the sounding continues as the standard atmosphere, shifted to pass through the top level’s temperature and pressure, with the top level’s share of water vapour (capped where the air saturates). The wind holds the top level’s wind. Both are marked as extrapolated. A flight above 16 km in RAP’s forecast is flying on that guess.
• Underground grid points. A kept level is blended from the four grid points even where one of them has that level underground. In the RAP cut, 850 hPa takes 13% of its weight from a point whose ground is at 845.8 hPa; the effect here is about 0.02 K, and larger in steep terrain.
• The ground. The pad is placed on the model’s smoothed terrain, not the site’s real height; hpr doesn’t shift the profile to the real ground.
• Humidity over ice. Whether NCEP gives humidity over ice at cold levels is unsettled here; it moves the density by under 0.1%.
• The live connection to NOMADS is not tested in CI, and nothing tells you which runs NOMADS still holds before you ask.
• The command line fetches them with hpr weather gfs and rap, but hpr sim doesn’t fly them yet (issue #265), and the Python package doesn’t fetch NOAA’s forecasts.

A launch site’s elevation

This page covers two ways to get a launch site’s elevation, its altitude above sea level (the field elevation a club lists). The first looks it up from Open-Meteo, a free weather and terrain service; the answer is saved, so the same lookup works later with no network, on a field with no signal. The second reads it from an elevation file you have, a GeoTIFF (below). It is for anyone who needs a site’s height above sea level to start a flight at the right air pressure and density. There is no hpr command for either yet: a Rust program calls the library.

How far to trust it, online. hpr gives back Open-Meteo’s number unchanged, and the saved copy gives it back offline. That is checked on two recorded answers, below. The number comes from a terrain model whose cells are about 90 m across, and it is a surface height: over trees or buildings it sits above the bare ground. The model’s makers state its accuracy as better than 4 m for 90% of points, averaged over the world outside Antarctica and Greenland; in about 1 area in 90 it is worse than 10 m. hpr hasn’t measured it. In the standard atmosphere, 10 m of height error changes the air’s density by about 0.1%: the example below shows it 12.8% thinner over 1,400 m. The recorded heights are whole meters; Open-Meteo doesn’t document its rounding.

The tests replay two saved answers and never contact Open-Meteo. The live service was contacted by hand, over an encrypted (HTTPS) connection, to record them. So a change in Open-Meteo’s answers would show only when a program runs, as a refused answer.

How far to trust it, from a file. At a given place, hpr reads the same stored value as GDAL, the library most mapping programs read terrain with. That is checked at 2,800 places in seven small files, in CI, and at 2,000 places in a whole tile from the US Geological Survey (USGS), on machines that have downloaded it, not in CI (how). Only files on a latitude and longitude grid are read. How accurate the height itself is depends on who made the file; hpr gives back what is stored.

Code:

• Online: hpr_net::elevation (API reference), written for M5.3b, the second launch-site increment. It needs the net feature of the hpr crate. The choices are in ADR-126: Open-Meteo’s elevation through the cache.
• From a file: hpr_io::geotiff (API reference), which the hpr crate re-exports as hpr::hpr_io::geotiff, with no feature needed. It was written for M5.3c2, with its choices in ADR-128: a site’s height from a user’s GeoTIFF.

The weather over a site is on Launch-day weather, and the compass’s offset from true north on The magnetic field and declination.

What hpr asks for

Open-Meteo’s elevation service (its documentation) takes a list of places, each a latitude and longitude in degrees, and answers one height for each, in the same order. hpr asks for one place or up to 100 in one request, the service’s limit. This is a request recorded for the tests, for Spaceport America, the Dead Sea and a point in the open Atlantic:

A request can name another server instead (ElevationRequest::endpoint), for a copy of Open-Meteo you run yourself.

hpr writes each coordinate to 5 decimal places, about 1 m on the ground. So a place given to 8 decimals or fewer, which your program keeps in radians and turns back into degrees (that can change its last digits), still finds its saved answer.

A saved answer is found again only by the same request: the same places, in the same order. If you look up three club fields in one request at home, a later lookup of one of them alone is a new request, and offline it fails. To use a site offline, look it up alone, or repeat the exact list you used before.

The terrain model

The heights come from the Copernicus DEM GLO-90, a digital elevation model (DEM): a grid of heights over the whole Earth, made by the European Union’s Copernicus programme from radar satellites. Its points are 3 seconds of arc apart north to south, about 93 m. East to west they are 93 m apart at the equator and 60 m at 50° of latitude; further north and south the spacing widens in steps (product handbook, issue 5.0, Table 3, page 15). It is a digital surface model: its heights include buildings and vegetation (the dataset’s readme).

Its stated accuracy is under 4 m for 90% of points (handbook, Table 1, page 10). That is a mean over the world outside Antarctica and Greenland, and the makers warn that it varies from place to place: of the 16,363 tiles there, each about a degree across, 184 (1.1%) are worse than 10 m (Table 12, page 31, which prints 0.9%, a share of all tiles, Antarctica and Greenland included).

The ground doesn’t move, so a saved answer stays fresh for a year. Open-Meteo’s forecast for Spaceport America (Launch-day weather) gives the same ground height there, 1,400 m.

What hpr refuses

hpr refuses an answer with another number of heights than places asked for, a height that is not a number, or a height outside −1,000 m to 9,000 m. The lowest land, by the Dead Sea, lies a little over 400 m below sea level, and the highest, Everest’s summit, 8,849 m above it, so a height outside is a broken answer, such as the value −32,768 that some terrain files use for “no data”. An answer hpr refuses is never saved, as on Online data and the cache.

When Open-Meteo itself refuses a request (it answers with HTTP status 400 and a reason), the HTTP transport reports a failed fetch naming the status, without Open-Meteo’s reason. hpr checks each place’s latitude and longitude before asking, so that is rare.

What the height means

The height is above mean sea level. The model’s heights are measured from EGM2008, a worldwide model of the geoid: the shape the sea’s surface would take if it were still, extended under the land (product handbook, section 1.2.1, page 13). That is the height above sea level the atmosphere is looked up by (Atmosphere: the height datum). The sea has no tiles in the model and reads 0 m, so 0 m can also mean “no data”. The Dead Sea reads −427 m, its surface when the radar satellites measured it, between December 2010 and January 2015 (handbook, page 30); the lake has fallen since.

A flight’s launch site takes its height above the WGS 84 ellipsoid instead (its ellipsoidal height). The two differ by the geoid undulation N, the height of sea level above the ellipsoid there: between about −107 m and +86 m around the world. hpr has no model of N; a geoid calculator gives it for a place, such as GeographicLib’s GeoidEval, which gives EGM2008’s −23.85 m at Spaceport America (32.99° N, 106.97° W). Then:

• If you know N, place the site with Geodetic::from_degrees(latitude, longitude, H + N), where H is the height from this page, and give the flight’s environment N with Environment::standard(site)?.with_geoid_undulation_m(N). At Spaceport America, H = 1,400 m and N = −23.85 m, so the site’s ellipsoidal height is 1,376.15 m.
• If you don’t, place the site at H and leave N at 0, as the example below does. The atmosphere still sees the right height above sea level, so the air, the drag and the flight are right. The site’s place in space is off by N, which moves gravity by about 3×10⁻⁴ m/s² per 100 m, 0.003% (normal gravity’s height term). A flight exported as KML keeps its heights above sea level, which stay right; the GeoJSON export’s heights are above the ellipsoid, and are off by N.

An example

crates/hpr/examples/site_elevation.rs looks up the three places above in one request. It makes these calls:

1. Client::new(transport, Cache::new(folder), Mode::Online) sets up the fetching. The transport is what fetches (Online data and the cache). A real program passes hpr_net::Http::new(), and keeps its saved answers in Cache::platform_dir(), the system’s usual folder for them. This one never uses the network: a stand-in transport answers with the answer recorded for the tests.
2. ElevationRequest::new(places) says what to ask for, and elevation::fetch(&client, &request, now) fetches the heights and saves them; now is the time, in seconds since 1 January 1970. Each comes back with its place, as height_msl_m, the height above mean sea level.
3. The same elevation::fetch a day later, through a client in Mode::Offline whose transport has no network, answers from the saved copy.
4. Ussa76::standard().air(height) gives the standard atmosphere (the 1976 US Standard Atmosphere) at each height, and Environment::standard(site) puts a flight’s start on the first place, Spaceport America.

Run it from a copy of the repository with cargo run --example site_elevation -p hpr --features net. It prints:

Elevation data by Open-Meteo.com (CC BY 4.0), from the Copernicus DEM GLO-90: © DLR e.V. 2010-2014 and © Airbus Defence and Space GmbH 2014-2018 provided under COPERNICUS by the European Union and ESA; all rights reserved
first lookup: Fetched; offline a day later: Cached, the same heights: true

place                            lat (°)     height (m)   pressure (hPa)  density / sea
Spaceport America, New Mexico      32.99           1400           856.02          0.872
the Dead Sea (its surface)         31.50           -427          1065.61          1.042
the open Atlantic                   0.00              0          1013.25          1.000

A flight from Spaceport America, New Mexico starts 1400 m above sea level, at 856.02 hPa.

The first line is the credit that Open-Meteo’s license and the terrain model’s license ask for; show it wherever the height is shown. The column density / sea is the air’s density as a fraction of sea level’s. Fetched and Cached say where an answer came from (how long a copy stays fresh). At Spaceport America’s 1,400 m the standard air is about 13% thinner than at sea level, so at the same speed and drag coefficient the drag there is about 13% lower.

How it is checked

The tests in crates/hpr-net/tests/elevation.rs replay two answers recorded from the service on 1 October 2026 (UTC), one for Spaceport America alone and one for the three places above. They read the expected heights from the recordings themselves, not through the code being tested, and check that:

• a lookup gives each recorded height exactly, in order, each with the place asked for, and with the credit line;
• a second lookup online, inside the year, is answered from the saved copy without a fetch;
• offline, with a transport that fails the test if it is ever called, the same lookup gives the same heights, still fresh an hour later and marked stale a year later;
• offline, a place never looked up is an error naming its address;
• an answer with no heights is refused and not saved; a later good answer is saved, and when an answer that isn’t JSON arrives after the year, the good copy comes back, marked stale with the reason;
• a saved copy hpr would refuse (a −32,768 m height) is an error offline, naming the height, and online is fetched again and replaced;
• a place turned into radians and back, which changes its last digits, finds its saved answer offline.

The code’s own tests check the address hpr builds, for one place and three, and that it is the same after a trip through radians for every longitude in steps of 0.01°, and for 720,000 values given to 6 or 8 decimals, the 6-decimal ones all sitting on a rounding half step. They check that it refuses no places, 101 places, a latitude or longitude out of range or not a number (naming the place, counting from 0), and a bad server address. They check that the reader takes negative heights and the range’s edges, and refuses each kind of broken answer above.

What it leaves out

• No command. The command line has no elevation command yet, and hpr sim doesn’t look a site up; a program calls the library and passes the height on.
• No geoid model. The height is above sea level, and turning it into a height above the ellipsoid needs the undulation N, which you give (above).
• No accuracy check. Nothing compares the model’s heights with surveyed ones; the 4 m is the makers’ statement.
• A surface, not the ground. Over a tree line or buildings the height can sit meters above the pad; for a pad cut out of forest, use a surveyed height.
• One number per place. The answer is the model’s height there, at about 90 m spacing; a pad on a hill or beside a cliff can sit meters off it.
• Your own terrain file is read by a separate reader, below.

From an elevation file of your own

A DEM (digital elevation model) is a grid of ground heights. Most are published as GeoTIFF files: an image whose pixels are heights, with tags saying where on Earth each pixel lies (the OGC GeoTIFF Standard 1.1). The United States Geological Survey (USGS) publishes the United States this way, free and in the public domain, through its 3D Elevation Program:

• Its 1-arc-second tiles (about 30 m) are what hpr is tested on. Its 1/3- and 1/9-arc-second tiles use the same latitude and longitude grid, but none has been tried.
• Its 1 m files are on a map projection (UTM) and are refused; GDAL’s free gdalwarp tool converts them first, as the table below says.
• Copernicus and NASA publish the world as GeoTIFFs too; no file of theirs has been tried.

Reading your own file

1. Bring the reader in: use hpr::hpr_io::geotiff::ElevationRaster;.
2. Read the whole file into memory: let bytes = std::fs::read(path)?;.
3. ElevationRaster::parse(&bytes) reads its tags. info() then holds what they say: the size, the corner and pixel size in degrees, the CRS, the sample type, the scale and offset, the unit and whether the file states it (vertical_unit_stated), the vertical datum’s code (vertical_crs_epsg) and the nodata value.
4. height_at(latitude_deg, longitude_deg), in degrees, gives Result<Option<f64>, GeoTiffError>: Ok(Some(height)) in meters, Ok(None) where the file has no data, or an error from the table below.
5. For many places, values_at(&[(lat, lon), …]) reads them in one pass. It gives a Vec with one Result<Option<f64>, GeoTiffError> per place, in order. Each is the raw stored value, not meters: info().meters(value) applies the scale, offset and unit.

The API reference shows the same steps as a short program that CI compiles and runs. The height is the value of the pixel the place falls in, as GDAL gives it. There is no smoothing between pixels, so on a 1-arc-second grid it is the ground within about 20 m of the site. A lookup decodes only the tile or strip of the file that holds the place, so it adds about one tile’s memory to the file’s.

What it reads

You rarely need this table: a USGS 1-arc-second tile reads as it comes. It is for checking an odd file.

Which height it is. The height is above the file’s own vertical datum. The reader reports the datum’s EPSG code (vertical_crs_epsg) when the file names one, and doesn’t change the height. Check two things in info(), the first one first:

• vertical_unit_stated is false: the file states no unit, and hpr took meters. A file in feet read as meters gives heights 3.28 times too high.
• vertical_crs_epsg is None: the file names no datum. The USGS tile in the example below names none; the USGS’s own description of its data says its heights are above NAVD88, the North American vertical datum. Check your publisher’s description.

EGM2008 is a model of the geoid. NAVD88 was defined by levelling, and the US National Geodetic Survey puts it about half a meter off the best geoid models, tilted by about a meter from coast to coast (NGS, new datums): a meter or two at most. hpr takes a height above either as the H of What the height means: the height above sea level the air is looked up by. A meter’s difference changes the air’s density by about 0.01%. That section also shows how to place a flight’s site from H and the geoid undulation N.

An example with a file

crates/hpr/examples/site_geotiff.rs reads two small files cut from the USGS tile around Spaceport America, both with some pixels blanked out as nodata: one in meters, one in whole US survey feet. It makes these calls:

1. ElevationRaster::parse(bytes) reads the tags; info() holds what they say.
2. height_at(lat, lon) gives the height at three places: the runway, a place in a blanked-out hole (None) and Albuquerque, off the file (an error naming the file’s edges).
3. value_at gives the feet file’s raw value, and height_at the same in meters.
4. Ussa76::standard().air(height) gives the standard atmosphere at the runway’s height.

Run it from a copy of the repository with cargo run --example site_geotiff -p hpr. It prints:

70 by 50 pixels of 1.000" by 1.000", PixelIsArea, CRS EPSG:4269, values F32 in Meter (stated: false)
latitudes 32.98333 to 32.99722, longitudes -106.98500 to -106.96556

place                            lat (°)     lon (°)  height
Spaceport America, New Mexico    32.9900   -106.9700  1400.691 m
a hole in the data               32.9960   -106.9832  no data
Albuquerque, New Mexico          35.0844   -106.6504  refused: latitude 35.0844° and longitude -106.6504° are outside the raster, which spans latitudes 32.983333° to 32.997222° and longitudes -106.985000° to -106.965556°

in feet: 4595 UsSurveyFoot (vertical CRS EPSG:6360) = 1400.559 m, -0.132 m from the meters file
at 1400.7 m: 855.95 hPa, density 0.872 of sea level's

• 1.000" is one arc-second, PixelIsArea says the tiepoint is a pixel’s corner, and EPSG:4269 is NAD83.
• F32 is 32-bit floating point, and Meter (stated: false) says the file states no unit, so hpr took meters.
• In the feet file, EPSG:6360 is NAVD88 in US survey feet, which the file states.

The runway reads 1,400.691 m. Open-Meteo’s answer for the same place, above, is 1,400 m, from a different terrain model whose cells are 90 m across, above EGM2008. The feet file stores 4,595 US survey feet, which is 1,400.559 m, 0.132 m from the meters file: rounding to whole feet moves a height by up to 0.152 m.

How the file reader is checked

The oracle, the outside program hpr is held to, is GDAL 3.12.2, run through rasterio 1.5.2, its Python interface. A script, validation/oracles/geotiff/dem.py, cut 70 by 50 pixels around Spaceport America from the USGS’s 1-arc-second tile n33w107 and wrote them in seven encodings:

The script recorded what rasterio reads from each, and from the whole 3,612 by 3,612 tile:

• the corner, the pixel size, the CRS, the vertical datum and unit, the scale and offset, and the nodata value;
• the exactly rounded sum of every value, and of each value times its index (row × width + column), so a swapped pair of pixels would show;
• at 400 places in each small file and 2,000 in the tile (some off the edge), which pixel rasterio puts the place in, and its value.

The tests in crates/hpr-io/tests/geotiff_rasterio.rs hold hpr to all of it exactly:

CI checks the seven small files; the whole tile (45 MB, fetched by cargo xtask refs fetch) is checked where it has been downloaded. The code’s own tests build files to check each refusal in the table above, the half-pixel move of pixel is point, the units, the scale and offset, and nodata. Property tests check, on random strip and tile layouts, that every place reads the pixel it is placed in, and that a file with bytes changed is read or refused without a crash.

The places are random, so none sits exactly on a pixel’s edge. Rounding can put a place on either side of an edge, in hpr and in GDAL, if it is closer to the edge than about 10⁻¹³ of a pixel’s width. A coordinate typed to a few decimals never comes that close.

What the file reader leaves out

• No map projections. A UTM file, or one on an older datum, needs gdalwarp first.
• No smoothing. A place reads its pixel’s value; on a slope the next pixel can be meters higher.
• No datum changes. A datum within a few meters of WGS 84 is taken as WGS 84, and the vertical datum is reported, not converted. Near the rupture of a large earthquake since a datum was fixed (Chile’s in 2010 for SIRGAS 2000, for example) the ground has moved further, by several meters.
• The file’s accuracy is the file’s. The reader gives back what is stored; the USGS and other publishers state their own accuracy.
• No command. As for the online lookup, a program calls the library.

Motor stock and prices

This page covers where hpr gets motor stock and prices: motor.fusionspace.co (the motor finder), a free site that reads a dozen U.S. vendors’ public listings every hour and publishes, for every AeroTech, Cesaroni and Loki motor of impulse class D and up that they carry, who has it in stock and at what price. hpr reads the site’s public data API (its machine-readable files) and saves each answer, so the same list works later with no network. It is for anyone choosing a motor they can actually buy: “which L motors are in stock, and what does one cost?” hpr then matches each motor in stock to its record on ThrustCurve.org, the public database of motor data, and can download that record’s thrust curve, so a motor you can buy is a motor you can fly (A motor from a file). At the command line, hpr motors search --in-stock --class L --max-price 150 lists the motors in stock by class and price (Motors you can buy); a Rust program calls the library, as below.

How far to trust it. hpr gives back the site’s values unchanged, and the saved copy gives them back offline. That is checked on recorded answers, below: eight from motor.fusionspace.co and two curve files from ThrustCurve.org, beside three stand-in searches in ThrustCurve.org’s shape, since ThrustCurve.org grants no license for its motor records (its site reads “All rights under copyright reserved”). Whether a vendor really has a motor, at that price, is the vendor’s to say. The site’s data is up to about an hour old when it is built, and hpr counts its saved copy as fresh for another hour, so a fresh answer can be two hours behind the vendor’s page; a stale copy is as old as its date says. (ThrustCurve.org’s answers count as fresh for a day.) The site’s terms ask you to check stock and price on the vendor’s own page before relying on them. Prices are in U.S. dollars.

The match is by name. On ThrustCurve.org’s answers of 1 October 2026, all 282 motors in stock matched exactly one ThrustCurve.org record (below), and each matched record’s size, impulse, average thrust and burn time equal the motor finder’s. A curve is the file someone uploaded to ThrustCurve.org, read by the same readers as a motor file on your disk.

The tests replay saved answers, and CI never contacts either live site. Both were contacted by hand, over an encrypted (HTTPS) connection, to record them. If a site changes its format, you will find out when your program, or hpr motors search, gets a refused answer, not from a failing test.

Code: hpr_net::motor_finder (API reference), written for M5.4a, the first motor-stock increment, and hpr_net::thrustcurve (API reference), written for M5.4b, the second. They need the net feature of the hpr crate: hpr = { ..., features = ["net"] } in Cargo.toml, then hpr::hpr_net::motor_finder. The choices are in ADR-129: motor stock through the cache and ADR-130: ThrustCurve.org and the match. hpr motors search was added by M5.4c, the third; its choices are in ADR-131: the command. How saved answers work is on Online data and the cache. The motors hpr carries with it, with their thrust curves, are on Solid motors.

What the site publishes

The site documents its API, and its terms, in its own repository. The API is a handful of files, rebuilt about every hour. There is no key, no limit on how often you ask, and no way to ask for part of a file: a program fetches a whole file and picks what it needs.

Each motor carries its maker; its designation (L1150R, 3683L851-P), spelled as ThrustCurve.org spells it; its impulse class, diameter, total impulse, average thrust and burn time, taken from ThrustCurve.org; its propellant; for a reload, the reusable case it needs (RMS-29/180); its delays; whether it is discontinued (old stock only: two motors in stock were, on the recorded morning); whether it ships as hazardous material, as the site labels it from the propellant’s weight; and every vendor’s listing of it.

A listing is one product page: its status, its sticker price, its pack size, the price of one motor, units on hand when the vendor shows them (267 of the 3,685 listings did), and when the site last read it. The status is in stock, out of stock, special order (made or ordered for you, often with a lead time of weeks; not counted as in stock), or unknown. A vendor may list one motor several times, for different delays or pack sizes. Each motor in stock also names its cheapest offer, by the price of one motor.

Prices are whole cents. The price of one motor is the sticker price over the pack size, to the nearest cent: a $38.49 two-pack is $19.25 a motor (the 263 of the 3,685 listings that fall on a half cent all round up).

What hpr refuses

An answer is refused, and not saved, when:

• it isn’t JSON, or a field is missing or of the wrong type;
• its schema version (the number the API puts on its format) isn’t 1: the API puts a breaking change under a new address;
• its build time isn’t a UTC time;
• a list’s count disagrees with the list;
• a motor’s impulse class isn’t one capital letter, its diameter isn’t above zero, or its impulse, thrust or burn time is below zero;
• a motor’s listing count disagrees with its listings;
• a motor has a cheapest offer but isn’t in stock, or is in stock with none;
• a pack holds no motors, or a motor costs more than its pack;
• in-stock.json holds a motor out of stock;
• a motor’s own page holds another motor.

One broken value refuses the whole file: hpr keeps its last good copy rather than a list it can’t trust, and online it hands that copy back, marked stale, with the reason. Two things the API allows are read, not refused: a cheapest offer with no price (when no vendor with the motor in stock shows one), and a listing status the API adds later, which reads as unknown.

Asking for a motor the site doesn’t list gets the site’s “not found” page; hpr returns it as an error naming the address, and doesn’t save it. The makers can be named in full or in short: aerotech, cesaroni and loki, in any case.

Matching motors to ThrustCurve.org

The motor finder carries no thrust curves, and no ThrustCurve.org id. ThrustCurve.org has both: it aims to hold a record for every certified motor, each with its own id (24 hexadecimal digits, such as 5f4294d2000231000000044f), and the simulator files people have uploaded for it. hpr asks its public API two things:

The match. The finder spells each designation exactly as ThrustCurve.org does. So hpr matches a motor in stock to the record whose maker (full name, such as Cesaroni Technology) and designation are the same, character for character. If no record has that name, or more than one does, the motor is a miss, and the match’s report (Join::report()) lists it with the reason. hpr doesn’t guess: it doesn’t compare impulse or diameter, or try other spellings. A motor ThrustCurve.org spells differently is reported as a miss, never matched by a guess. (The report and the code call a matched motor mapped.) thrustcurve::fetch_finder_records fetches the records the match needs, one search for each of the three makers the finder reads, and thrustcurve::join matches them.

On ThrustCurve.org’s answers of 1 October 2026, every motor in stock matched (ADR-130: ThrustCurve.org and the match):

Every matched record listed at least one data file, in some format, and for every match the diameter, total impulse, average thrust and burn time were the same on both sides, so each match was the right motor by more than its name. The motor finder copies ThrustCurve.org’s names and figures, so a full match is expected; the match is there to catch drift.

ThrustCurve.org grants no license for its motor records; its site reads “All rights under copyright reserved”. So the repository no longer keeps those three answers, and the tests replay stand-ins in the same shape instead (ADR-145: the recordings’ licenses). They hold 297 records:

• 15 wholly invented, five per maker, with designations ending -INVENTED;
• 282, one for each motor in the finder’s in-stock list. Each carries only the values that list states, which are ThrustCurve.org’s published figures as the finder relays them under CC BY 4.0, plus an invented id and an invented count of data files. J450DM and F27R/L keep their real ids, those of the two public-domain downloads, so the match leads to a committed file. The fields only ThrustCurve.org states (length, weights, peak thrust, certifying body, dates, links) are left out.

On them, too, all 282 motors match. The tests write the match’s report into validation/reports/thrustcurve-join.md, and check it against the match on every run. So the committed tests show that the code keeps the rule; the full match on ThrustCurve.org’s own records is the measurement of 1 October 2026 above, which last ran at commit 5150e0d (the test was added by PR #277). The milestone’s goal (M5.4b) was 95% of the motors in stock; the test asserts that too.

The curve. A download’s file is read by the same readers as a motor file on your disk (Solid motors): .eng by hpr_motor::eng, .rse by hpr_motor::rse. DataFile::read() picks the reader by the file’s format, and Curve::thrust_curve() gives the first motor’s curve. Each file says who measured it (cert, a certification test; mfr, the maker; or user) and its license: PD for public domain, free or other, or none given. ThrustCurve.org’s API doesn’t define free and other, and hpr doesn’t interpret them; only PD files are recorded for the tests. An answer with no files gives an empty list, not an error; that is how the API answered an unknown id when tried by hand on 1 October 2026.