rockets-engine: Giving the Ballistics Engine a Motor

A.C. Jokela — Sun, 01 Nov 2026 01:00:00 GMT

A bullet gets all of its energy in the first few inches. Everything the ballistics engine does happens after the muzzle: a fixed mass coasting through air that slows it, a gravity that pulls it down, a spin that pushes it sideways. Nothing is added after the barrel and nothing is lost except speed.

A rocket breaks every one of those assumptions. It keeps pushing for a second or a minute. It gets lighter as it pushes, because the thing doing the pushing is its own mass leaving out the back. It can drop an empty stage and light the next one. It can be steered. And the interesting part of its flight, the part a simulator has to get right, is exactly the part a ballistics solver never sees.

rockets-engine is the crate I wrote to cover that part. It started as the flight model for a game that needed powered arcs, and it grew into something closer to a model-rocket simulator: motor files, parachutes, a geometry modeler, winds, Monte Carlo dispersion, a command-line tool and the same tool running in a browser. It went from 0.1.0 to 0.20.5 between October 23 and October 31: 63 commits and 28 published versions. This is how it is built, how I checked it, and where the checking found that I was wrong.

Don't fork the ballistics engine

The first decision was what not to do. The ballistics engine already has a drag kernel I trust: a standard atmosphere, Mach-dependent drag, wind, spin, and the derivative function that the Ballistics Insight app runs on every phone it is installed on. Forking it to add thrust would have meant two copies of that kernel drifting apart.

So rockets-engine calls it. The atmospheric adapter, BallisticForces, builds the engine's input structure once and, at every stage of every integration step, writes the rocket's current mass into it and calls the upstream compute_derivatives for gravity and drag. The ballistics engine thinks in grains and inches because rifles do, so the adapter also updates the imperial mass mirror (weight_grains) every time the SI mass changes, sets the caliber from the body diameter, and turns off the bullet-specific post-processing that has no meaning for a rocket. Thrust, mass flow and staging live entirely on the rocket side of that boundary.

Everything else follows from treating the engine as a library rather than a codebase to modify. The crate is SI throughout. The local frame is X downrange, Y up, Z to the right. The Simulator holds no evolving state: each call takes a FlightState, returns a new one, and leaves the caller's state alone if anything fails, which makes save, replay and "what if I had launched one degree higher" cheap. Guidance is a hook that returns a thrust direction and an optional steering acceleration; the crate has no idea what a target is.

Motors and mass

A motor is a thrust curve: thrust against time since ignition, piecewise linear between published samples. The crate reads RASP .eng files, the format thrustcurve.org distributes, in both of the layouts that exist in the wild, and it ships five curves built in:

Motor	Diameter	Propellant	Total impulse	Burn time	Peak thrust	Average thrust
Estes A8	18 mm	3.8 g	2.15 N·s	0.53 s	9.6 N	4.0 N
Estes B6	18 mm	5.6 g	4.33 N·s	0.86 s	12.1 N	5.1 N
Estes C6	18 mm	10.8 g	8.82 N·s	1.86 s	14.1 N	4.7 N
Estes D12	24 mm	21.1 g	16.84 N·s	1.65 s	29.7 N	10.2 N
AeroTech G80	29 mm	69.0 g	135.6 N·s	1.70 s	107.0 N	79.7 N

I computed the impulse and averages from the embedded curves rather than copying the labels, and they land where the letter says they should: an A is 1.26 to 2.5 N·s, a D is 10 to 20, a G is 80 to 160.

The five built-in curves. Black powder motors spike to light the grain and then sustain; the composite G80 is a different animal and gets its own scale.

Mass is where most simple rocket simulators cheat, usually by integrating a separate fuel state and clamping it at zero when the integrator overshoots. rockets-engine does not integrate fuel at all. It assumes propellant is consumed in proportion to delivered impulse: if I(t) is the impulse delivered so far and I_total is the curve's total, the remaining propellant is m_p(1 − I(t)/I_total). That is the same as assuming a constant effective exhaust velocity, I_total/m_p, which is the honest assumption when all you have is a thrust curve that already includes whatever the nozzle and the ambient pressure did. The mass is then a closed-form function of time, evaluated fresh at each of the four RK4 stages. It cannot drift, cannot go negative, and cannot disagree with the motor's phase in a saved state, because both are derived from the clock. When the curve ends, thrust is zero and the empty casing stays on board.

Where the step breaks

RK4 is a beautiful method for smooth problems, and a rocket is not smooth. Thrust jumps at ignition. It has corners at every sample on the curve. It drops to zero at burnout. At a separation, a whole stage, with its dry mass, its motor and any propellant it did not burn, leaves the vehicle in an instant. Step across one of those discontinuities and RK4 averages two different rockets into one that never existed.

The integrator never steps across them. Every ignition, every curve knot, every burnout and every separation splits the step, and the step grid itself stays anchored to fixed multiples of the maximum step from the start of each call, so splitting one interval does not shift every interval after it. Within each piece, all four RK stages see the same attached stages and burning motors, frozen at the start of the piece: a step that ends exactly at a separation still carries the departing stage, and the next one starts without it. A short burn is never skipped by a long step: one test requires a flight taken in two-second steps to match the same flight at half-millisecond steps to within a nanometre.

Staging falls out of the same structure. A vehicle is a base mass plus any number of stages, each with its own motor, ignition time and optional separation time. Total thrust is the sum over attached motors that are burning, so serial staging (light the next stage after the last one drops) and parallel staging (strap-on boosters burning alongside a core) are the same model. Separating a stage that is still burning, hot staging, simply ends its thrust.

The crate's staging example: 24 N, 16 N and 12 N stages with short coasts between them. Mass falls smoothly while a motor burns and in a step when a stage leaves.

Is RK4 doing its job?

The cleanest way to know whether an integrator is right is to give it a problem with an exact answer. A vertical burn with constant thrust, no drag and uniform gravity has one. With constant thrust the mass falls linearly, and the velocity at time t is the rocket equation minus gravity:

v(t) = v_e ln(m_0 / m(t)) − g t

where v_e is the effective exhaust velocity and m_0 the mass at ignition. Integrating once more gives the altitude in closed form. I set up a 0.5 kg rocket with 0.1 kg of propellant and a 100 N, two-second burn, which reaches 426.674 m/s and 410.090 m at burnout, and flew it through rockets-engine with the maximum internal step anywhere from half a second down to a millisecond. For contrast I wrote the same physics as a forward Euler loop.

Velocity error at burnout against the exact solution. RK4 falls sixteen-fold for every halving of the step until it reaches the floating-point floor.

Halving the step from 0.5 to 0.25 seconds cuts the RK4 error from 3.7×10⁻⁵ m/s to 2.3×10⁻⁶ m/s, a factor of 16. That is what fourth order means, and it holds all the way down until the error reaches about 2×10⁻¹³ m/s below a 5 ms step, where the rounding of double-precision arithmetic takes over. At the default 10 ms step the error is 6×10⁻¹² m/s. Forward Euler at the same step is off by a quarter of a metre per second, and at half-second steps by 12 m/s.

The crate's own test suite asks the same kind of question in more than a dozen ways. A few of the external references:

Test	Compared against	Tolerance
Vacuum burn	Rocket equation, velocity and position	2×10⁻¹¹ m/s
Variable-mass convergence	Error ratio when the step halves	above 14 (16 is ideal)
Two-burn Δv	Rocket equation across two motors	10⁻⁶ m/s
400 km circular orbit, 1 s steps	Energy and angular momentum	drift below 10⁻¹²
Unpowered flight, six configurations	The ballistics engine's own integrator	2×10⁻⁹
Parachute descent	Terminal velocity √(2mg/ρC_dA)	2%
Coriolis deflection	The exact −2Ω×v	10⁻⁹

The suite has a little over 200 tests and runs in about 14 seconds.

The orbit tests matter because rocket flight does not stay small. For trajectories that leave the neighbourhood of the pad, the crate has a CentralGravity model: inverse-square gravity measured from the center of the Earth, in an Earth-centered frame. The icbm_midcourse example starts a 500 kg post-boost body at 300 km, moving at 6.5 km/s and 25° above horizontal, and coasts it until it falls back through 120 km.

A 1,650-second coast under inverse-square gravity, at one-second steps.

It reaches 1,364 km, crosses 8,064 km of the Earth's surface, and hands off at 105 km and 6,771 m/s after 1,650 seconds. Specific orbital energy, which should be exactly conserved in a vacuum coast, changes by two parts in 10¹⁵. At that scale a flat frame is simply the wrong model, and the crate says so: the flat-frame models are documented as invalid at intercontinental ranges, and the central-gravity model carries no atmosphere.

Checking against OpenRocket

Exact solutions check the integrator. They say nothing about whether the rocket's aerodynamics are right, and for a model rocket the aerodynamics are most of the answer. For that there is a better reference than anything I could derive: OpenRocket, the open-source simulator most hobbyists use, and in particular its test suite.

rockets-engine has a Barrowman geometry modeler, written against OpenRocket's technical documentation and its FinSetCalc and SymmetricComponentCalc sources. Give it a nose cone, a body tube and a fin set, and it returns the drag, normal-force slope (Cnα) and center of pressure as functions of Mach number, plus mass properties from the component masses. OpenRocket's own unit tests include the Estes Alpha III, Estes's long-running beginner kit, with known Cnα and center-of-pressure values. The crate's parity tests build the same rocket and must match OpenRocket's numbers within half a percent, for three fins and for four.

Matching a coefficient is not the same as matching a flight, so the next step was to fly the same rocket in both. A small Java driver boots OpenRocket 24.12's core headless, loads its Alpha III test fixture, adjusts the parts my modeler does not have (no launch lug, rounded fin edges, a smooth finish, zero wind), flies it on OpenRocket's test motors, and prints the apogees. CI downloads the pinned OpenRocket jar and runs that driver on every push, and the parity tests then fly the same configuration through the rockets command line and require agreement within 10%.

Apogee on OpenRocket's Alpha III fixture. All four flights land within 5%, and rockets-engine is consistently a little low.

Flight	Regime	OpenRocket 24.12	rockets-engine	Difference
Alpha III, "A8" test triangle (9 N·s)	subsonic, Mach 0.42	409.6 m	390.1 m	−4.8%
Alpha III, "D21" test triangle (32 N·s)	transonic, Mach 0.85	697.0 m	678.1 m	−2.7%
Alpha III, synthetic G64 (128 N·s)	supersonic, Mach 1.60	1,112.1 m	1,085.7 m	−2.4%
Beta, two stages (B4 booster, D21)	staging	845.3 m	831.6 m	−1.6%

Two things about this table are easy to misread. OpenRocket's test motors are synthetic triangles, not the real motors their names suggest: its "A8" delivers 9 N·s, about four times a real Estes A8, which is why an Alpha III reaches 390 m on it. And the Beta flight feeds both sides OpenRocket's own drag curve, so it checks staging, not aerodynamics.

The more interesting story is how the subsonic number got there. Early on, the A8 flight agreed with OpenRocket to within 8%, then to within 0.6%. Then I added the G64, a motor that exists only to push the Alpha III past Mach 1, and compared the drag breakdown at matched Mach numbers term by term. It found three errors. OpenRocket computes fin form drag per fin and multiplies by the fin count; I had one fin's worth. For an ogive nose it takes the surface angle at 99% of the nose length, where an ogive is nearly parallel to the body; I had used the angle of a straight line from tip to base, charging the nose wave drag it does not have. And I had misread the exponents in the supersonic leading-edge correction. With all three fixed, the subsonic flight moved from +0.6% to −4.8%. The earlier, better agreement had come partly from errors cancelling. An earlier bug of the same kind, caught by the coefficient tests rather than the flights, had counted every fin's normal force twice: the Diederich formula gives the slope for a pair of fins, and a three-fin rocket is one and a half pairs, not three.

I would rather publish a −4.8% that I can explain than a +0.6% that I cannot.

Real motors, real delays

OpenRocket checks the engine against another simulator. The physical world gets a vote too, and Estes publishes one in a form a simulator can be checked against without a single flight: the delay charge.

A black powder motor burns its propellant, then a slow-burning delay grain, then pops an ejection charge to deploy the recovery system. The delay is chosen so the charge fires near apogee, when the rocket is moving slowest. For the Alpha III, Estes's recommended motors include the A8-3, B6-4 and C6-5: three, four and five seconds of delay. If the simulator's coast from burnout to apogee comes out near those numbers on the real thrust curves, it is getting the drag and the mass right in the regime that matters.

The OpenRocket parity airframe on three real Estes curves. The X marks where each motor's printed delay would fire the ejection charge.

Motor	Liftoff mass	Burnout	Max speed	Apogee	Coast to apogee	Estes delay
A8	38.6 g	0.54 s	50 m/s	84 m at 4.02 s	3.48 s	3 s
B6	40.3 g	0.86 s	93 m/s	208 m at 5.64 s	4.78 s	4 s
C6	47.8 g	1.86 s	131 m/s	387 m at 7.40 s	5.54 s	5 s

All three coasts come out about half a second longer than the delay Estes chose, so in all three the charge fires just before the top, which is where you want it: a hair early is a little speed on the shock cord, a hair late is a rocket already falling. The built-in A8 and B6 curves are the zero-delay booster versions. A delay grain adds a few grams to the motor without changing its thrust curve, so the real A8-3 and B6-4 flights would be a touch lower and slower than these.

The C6 apogee, 387 m, is about 10% above the 351 m (1,150 ft) Estes projects for the kit. That is the direction it should be: the parity airframe has no launch lug and smooth, rounded fins, where a kit built on a kitchen table has a lug, square fin edges and a coat of paint, and every one of those adds drag.

Wind, parachutes and a few thousand flights

A model rocket's flight is mostly the part after apogee. RecoveryForces wraps any force model and swaps in parachute drag once the rocket is descending. The terminal velocity is never written down anywhere in the code; it has to emerge. For a 120 g rocket under a parachute with 0.25 m² of drag area, √(2mg/ρC_dA) at sea level is 2.77 m/s, and the simulated rocket lands at 2.77 m/s.

The deployment rule shows the kind of bug that dominated the week. The first version deployed the chute when vertical velocity was less than or equal to zero, which is true of a rocket sitting on the pad. With no wind, nothing happened. With a standing wind, the open parachute dragged the rocket sideways before it lifted off, and a uniform wind and an identical wind zone flew differently. The gate is now strictly descending. The weathercock model, which turns the rocket's axis into the relative wind, had the same problem from the other direction: a standing wind tipped the rocket over on the rail, where a real launch rod holds it upright. The axis is now pinned until it clears the rail.

Wind itself comes from winds-engine, a sibling crate: a uniform vector, wind zones by downrange distance, vertical profiles, a radiosonde sounding, a GRIB2 forecast grid, or terrain-adjusted wind over a digital elevation model. Turbulence is a frozen field rather than a random process: eight sine waves per axis with log-spaced frequencies and amplitudes falling with frequency, a pink spectrum scaled to the RMS you ask for, with phases from a seeded generator. Because the field is a pure function of position and time, the four RK4 stages, a saved and restored flight, and a replay with the same seed all see exactly the same gusts. Every force reads the same air: drag, the parachute, the weathercock and body lift all sample one shared atmosphere, which was itself a fix. Atmosphere zones originally reached only the drag kernel while the other forces quietly built their own standard day.

A D12 in an illustrative 24 mm airframe (120 g, drag coefficient 0.4). The ascent takes ten seconds and the descent three minutes, so the descent decides where it lands.

The dispersion command flies the same rocket hundreds of times, perturbing the drag scale (lognormal, 3%), the wind (1 m/s per axis) and the launch speed (1%), and reports apogee, landing range and the circular error probable, the radius that contains half the landings. It has its own tiny SplitMix64 generator rather than a dependency, so the same seed reproduces the same set of flights.

500 runs, seed 42	Apogee	Landing range	CEP	Still aloft after an hour	Time
Calm	489.5 m (sd 6.3)	326 m (sd 562)	232 m	2	4.0 s
Steady 4 m/s	489.2 m (sd 6.6)	962 m (sd 981)	383 m	2	4.0 s
Steady 4 m/s plus gusts	488.4 m (sd 10.3)	853 m (sd 456)	327 m	0	16.8 s

The apogee statistics are tight and well behaved. The landing statistics carry a lesson about what a perturbation means. The 1 m/s wind uncertainty applies to all three axes, vertical included, and it is held for the whole flight. A rocket descending at 2.8 m/s under its parachute, given a steady updraft of comparable size, comes down very slowly or not at all: two runs in five hundred were still in the air an hour after launch, and the few that hung for many minutes drifted far enough to dominate the standard deviation of the landing range. A real updraft is a thermal, not a property of the entire sky. For landing-zone estimates the vertical term deserves its own, much smaller sigma.

The same commands in a browser

The command-line tool, rockets, has three subcommands: simulate prints a trajectory as a table, CSV or JSON with an apogee and impact summary; dispersion runs the Monte Carlo; solve-range finds the launch elevation that lands at a given distance. All of its options are parsed by one module, and that module compiles to WebAssembly unchanged. The browser build at rockets.rs/sh is a 39-line binding over the same parser, so the native tool and the web page accept exactly the same commands. The module is 836 KB, about 285 KB compressed. The page has a dozen example buttons, deep links that carry a command in the URL, and --plot draws an interactive altitude chart by re-running the command with --format json. Options that read files or terrain models are native-only and say so.

One of the examples flies an Alpha III modified with a 24 mm mount on an Estes D12, which no stock Alpha can take: 66.6 g at liftoff, 591 m at apogee.

What it doesn't do

rockets-engine is a point-mass simulator with a few rungs added above point mass. The thrust axis is commanded, not earned: the weathercock model is a reduced-order second-order system relaxing the axis toward the relative wind, roll is a single scalar channel, and body lift is quasi-static, computed from the angle between the commanded axis and the relative wind rather than from an integrated attitude. There is no inertia tensor, no quaternion and no gyroscopic coupling. It is fixed-step RK4, not an adaptive solver, so a new vehicle model needs a convergence check, and the documentation says so. The standard atmosphere it borrows is defined to about 80 km; above that, an AltitudeSwitch hands the flight to a vacuum model. The flat frame is wrong at intercontinental ranges, the central-gravity frame has no air, and Earth rotation is the caller's problem in an inertial frame.

The Barrowman modeler is deliberately narrower than OpenRocket: conical, ogive, elliptical and parabolic noses; trapezoidal, elliptical and free-form fins; conical boat-tails; no launch lugs, shoulders or multi-diameter bodies. It is the subset I could check against OpenRocket's own numbers.

Nine days of it

The crate is 8,327 lines of Rust in the library, 3,014 in tests and 487 in six examples. Its heaviest file is the command-line module at 2,654 lines, because the command surface is where every feature has to agree with every other feature. The commit history reads like a list of the places the physics was fine and the bookkeeping was not.

Most of the crate arrived in the first four days; the last three were dependency updates and bug fixes.

The first day produced the integrator, staging, central gravity, the command line and the browser terminal. The second added motor files, recovery and the geometry modeler, and put OpenRocket into CI. The third took the modeler through the transonic and supersonic regimes and brought in winds-engine. On the 30th, a fix for a division of zero by zero at apogee in the body-lift model, where the angle between the axis and the wind passes through exactly 180 degrees and the guard written for zero degrees did not catch it. Writing this post turned up two more, both fixed in 0.20.5 on the 31st. Nothing holds a rocket on the pad, so while thrust climbs past its weight it sags a few millimetres below the ground, and dispersion took that sag for a landing and reported zeros. And the weathercock took a single explicit step of a stiff oscillator per output step, so at the default settings it flew the Alpha III to 213 m in a 4 m/s wind instead of 371; it now integrates the axis in substeps and agrees with itself to half a percent.

In The Bullet Doesn't Go Where You Point It I wrote that almost none of the ballistics engine's memorable bugs were physics bugs. The rocket engine repeated the lesson with a twist. Its physics bugs were found by comparison, against an exact solution, against OpenRocket, against a delay grain Estes chose decades ago. Its other bugs lived at the edges of a flight: on the pad before liftoff, and at the instant of apogee, where velocities and angles pass through the values that formulas written for the middle of a flight never see.

rockets-engine is on crates.io with documentation on docs.rs, the source is on GitHub, and every command in this post runs at rockets.rs/sh. The rest of the ballistics work is collected, in order, on the ballistics page.

TinyComputers.io (Posts about rockets-engine)