Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Monte Carlo dispersion

Fly a rocket many times with its uncertain inputs scattered, see how far its apogee and landing spread, and choose each input’s scatter.

No two flights of one rocket are the same. The motor burns a little hotter or cooler than its label, and the rocket weighs a few grams more than the plan. The wind isn’t 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. 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).

Sampling tests check that:

  • 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.

Running a dispersion

Rust, the command line and Python fly the same flights for the same seed.

A run of 200 flights

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

cargo run --example monte_carlo -p fusionspace-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, and 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 m (3,412 ft) and 1,200 m (3,937 ft).

The mean isn’t the nominal flight. The mean apogee is 6.5 m (21 ft) above the nominal one. With 200 flights the mean itself is uncertain by about 47.4/200=3.4m (its standard error). So 6.5 m (21 ft) is 1.9 standard errors, and chance can account for most of it.

Part of the gap is that the apogee doesn’t respond evenly to drag. With 5% less drag it gains 29 m (95 ft), and with 5% more it loses 27 m (89 ft). So an even spread of drag lifts the mean apogee by about 1 m (3.3 ft).

The landing spreads far more than the apogee. The landing distance’s standard deviation is 209 m (686 ft), about a third of its mean of 660 m (2,165 ft). The apogee’s is 47 m (154 ft), 4% of 1,120 m (3,675 ft). 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. Each dispersion is 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, and when a device opens the opening shock’s and opening airspeed’s (after a separation with nothing left to burn, the part that keeps the nose counts too, the shock until an ejection parts it; hpr mc gives the rule), the landing ellipses below and the failed flights. --export runs.csv writes every flight’s draw and outcome, one row a flight. The command’s runs are the library’s for the same seed, bit for bit: a test 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. Failed flights are counted, and their figures are NaN. hpr.MonteCarlo 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. That holds on one platform, with both built in release mode (test_a_run_is_hpr_mcs_bit_for_bit). Landing ellipses aren’t in Python yet; NumPy finds them from the landing arrays. run.spread(name) gives a column’s spread, and its 5% and 95% with each failed flight placed past that end (Failed flights are counted). 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. It’s an area 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. It’s 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 simulator 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 short directions.

  1. The center is the landings’ mean: here 626 m (2,054 ft) east and 23 m (75 ft) south of the pad.

  2. The axes come from the landings’ covariance. It 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 (704 ft) and 203.0 m (666 ft). The spread is nearly round: the wind’s uncertain heading (15°) spreads the landings sideways about as much as its uncertain speed (25%) spreads them downwind.

  3. The size is how many standard deviations, k, the ellipse reaches along each axis. If the landings follow a two-dimensional normal distribution, that ellipse holds the share

    p=1−exp(−k2/2)

    of them. So the ellipse of level p has

    k=−2ln(1−p)
    Level pScale factor k
    50%1.177
    90%2.146
    95%2.448
    99%3.035

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

In two dimensions it takes more standard deviations to hold 95% than in one: 2.448 against 1.960. That’s 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; the simulator 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.

The next-flight ellipse’s k comes from Hotelling’s T2 distribution, which accounts for the mean and the spread both being estimated from the same flights. For n landings:

k2=n2−1n[(1−p)−2/(n−2)−1]

With 200 landings the next-flight ellipse’s axes are 1.3% longer: 532 m (1,745 ft) against 525 m (1,722 ft). With 10 they would be 36% longer.

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 (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).

The tests can catch a wrong ellipse. Take a spread 200 m (656 ft) long and 30 m (98 ft) wide, one standard deviation each way. Its 95% ellipse, turned 6° off the spread’s 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 the simulator draws a standard normal number z (mean 0, standard deviation 1) for each input. It moves the input by σz, with σ the standard deviation you gave. A rocket 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.

FieldWhat each flight flies
dry_mass_sd_fractionEach stage’s mass without motors times 1+σz. Its moments of inertia scale with it.
cg_sd_mEach stage’s center of mass moved σz meters towards the tail (towards the nose when negative).
drag_sd_fractionThe rocket’s zero-lift drag coefficient times 1+σz, whether HPR Sim’s own, a drag table’s or a drag model’s.
impulse_sd_fractionEach motor’s thrust and propellant mass, both times 1+σz. Its total impulse changes and its specific impulse doesn’t, as for a motor that holds a little more or less of the same propellant.
burn_time_sd_fractionEach motor’s thrust curve stretched in time by 1+σz and its thrust divided by the same: a longer, softer burn of the same impulse.
ejection_delay_sd_sEach motor’s ejection delay plus σz seconds, never below zero.
wind_speed_sd_fractionThe wind at every height times 1+σz, never below calm. A calm forecast stays calm.
wind_heading_sd_radThe wind at every height turned σz clockwise: the forecast’s direction, give or take.
rail_elevation_sd_radThe rail’s angle above the horizon plus σz. Past vertical, it leans the other way.
rail_azimuth_sd_radThe rail’s heading plus σz, clockwise.
deployment_lag_sd_sEach recovery device’s lag after its trigger plus σz seconds, never below zero. A part’s tumble, which the simulator adds to a separated part with no device open, starts at the split and has no lag to scatter.

Five 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. The simulator 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.
  • Every flight of a staged run separates where the nominal one does. It separates 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. If a booster still burns at a split timed in seconds, the flight stops with its error and counts as failed. The exception is a split that may drop a burning motor, as OpenRocket’s first burnout of a stage does (the decision record). --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. So the simulator refuses that flight, and it counts as failed.

How a run behaves

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.

How much a failure can move a percentile has a bound. If every failed flight had gone past one end, the 95th percentile of all the flights tried is the percentile of the flown ones with the failed ones counted as infinitely high. The percentile is the straight-line rule NumPy uses by default: with n values sorted, the p percentile sits at position h=(n−1)p, counted from 0.

Say 100 flights are tried and 2 fail. The 95th percentile of all 100 sits at position h=99×0.95=94.05. With the 2 failures placed last, positions 94 and 95 are the 95th and 96th smallest flown values, so it lies 0.05 of the way from one to the other. Over the 98 flown flights alone it sits at 97×0.95=92.15, 1.9 places lower. With 5 or more of the 100 failed, position 95 is a failed flight, and the answer can’t be bounded.

hpr mc prints both ends whenever a flight has no value (its output), and Python’s MonteCarlo.spread gives the same numbers. From Rust, quantile_counting_missing(0.95, MissingEnd::Above) gives the 95th percentile’s worst case, and MissingEnd::Below the 5th’s; too many failures give CountedQuantile::Unbounded.

A share such as “reached 1,100 m (3,609 ft)” 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. The stream is picked out by the run’s seed, the flight’s number in the run and the input it’s 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 the hpr library. Using it from your own program describes how. Then call run_parallel instead of run:

[dependencies]
fusionspace-hpr = { git = "https://github.com/nrdptel/fusionspace-eridanus", 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 on Monte Carlo dispersion sets out the draws.

How long a run takes

On the development machine, an Apple M5 with 10 cores, these are the times for 10,000 flights of a Level 2 rocket. That’s a rocket on a J, K or L impulse class motor. Each flight runs from ignition to the ground, under a drogue and a main:

rocketpeak Mach10,000 flights, 10 threadsone flight, one thread
Valetudo, one of RocketPy’s examples: 9.7 kg on a K400C0.3 to 0.43.0 s1.9 ms
a 66 mm (2.6 in) rocket with a 54 mm motor mount on a K9401.6 to 2.09.4 s5.7 ms

No flight failed. These are release builds, with optimization 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 fusionspace-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. The table holds the body’s lift and center of pressure by the shock-expansion method (The body faster than sound in a flight). They’re worked out once at every 0.05 Mach and then looked up. Building the table 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 (sharing the table, October 2026), each flight built its own table. The supersonic run above then took 264 s. To fly draws of your own, as a sensitivity analysis does, use monte_carlo.fly(&draw), which shares the 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.

The times say nothing about how accurate a Mach 2 flight is. No validation flight goes past Mach 1.06 (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 has its limit in NFPA 1125, the code commercial motors are certified to (§8.1.7 and §8.2.7). Over a motor type’s certification firings, the “standard deviation of the total impulse data shall be no greater than 6.7 percent of the mean”. Four National Association of Rocketry (NAR) certification reports measured 1.3% to 3.1%: an Estes C6 (2.0%), D12 (3.1%), E12 (1.28%) and an AeroTech G80 (2.3%). The G80’s report is hosted on ThrustCurve.org. So 2% to 3% is a fair guess, and 6.7% the most the code allows.
  • Ejection delay. The code lets a measured delay differ from its label 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. 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. It’s quoted in the public first-draft documents of the code’s next revision (public inputs 4 and 5). The draft’s 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.

FusionSpace HPRVersion 0.1.0Issued 2026-11-21In preparationAbout HPR Sim