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.