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

Moving mass

See what ballast or a payload sliding along the airframe during flight does to your rocket’s center of mass, stability margin and flight.

In short

  • What it models: a part carried inside the airframe, such as ballast or a payload, sliding along the rocket’s axis in flight on a trigger. The rocket’s center of mass and inertia follow the part, and so do the equations of motion. Use it to see what a payload that moves, or ballast moved on purpose, does to the stability margin and the flight. The model was added in the moving-mass milestone.
  • Sources: the parallel-axis theorem and the kinetics of a system of particles, from Meriam and Kraige’s Engineering Mechanics: Dynamics. Both are applied to the equations of motion on Rigid-body flight. The cycloidal motion of cam design is from Norton’s Design of Machinery.
  • How well it is validated: against exact answers only. No other simulator or real flight has been compared with it. The mass properties match a hand calculation to 1e-15, and the static margin to 1e-12 calibers. In free flight with nothing acting on the rocket, its angular momentum is kept to 6.9e-12 of itself and its center’s velocity to 2.6e-12 m/s.
  • What it leaves out: a mass that leaves the rocket, which is Released mass. A shift can’t come in a flight that also separates, ejects pieces or releases a mass, or before the rocket leaves the rail. A part can’t move across the axis or turn, and the shock of it hitting a stop isn’t modeled. The motion’s shape is a choice made here, not something a source gives for rockets.

The model

How a shift is described, and what it changes.

Describing a shift

A MassShift names the part, how far it moves, how long it takes, and when it starts:

fieldmeaning
triggerwhen it starts: the same triggers a parachute has (apogee, a height on the way down, a time after launch, a motor’s burnout or delay)
componentthe id of the internal component that moves; everything inside it moves too
travel_mhow far along the axis, in meters: positive toward the tail, negative toward the nose
duration_show long the move takes, in seconds: at least 0.01 s

In code, this slides a part with the id ballast 0.3 m (0.98 ft) toward the tail over 1 s, starting 5 s after launch:

let simulation = simulation.with_shifts(vec![MassShift::new(
    Trigger::Time { time_s: 5.0 },
    "ballast",
    0.3,
    1.0,
)])?;
let flight = simulation.run(&mut ())?;

The part is any internal component of your design, such as a mass component. Each shift that starts is recorded as an EventKind::Shift event. Simulation::mass_properties(flight, t) gives the mass, center of mass and inertia the flight had at any time.

Shifts of one part add up. The simulator can’t know before the flight which triggers will fire. So it adds all of a part’s moves toward the nose, and separately all of its moves toward the tail. It refuses either total that would take the part out of the component that holds it. A part the design already places partly outside its holder can go as far as it already reaches. A weight in a nose cone’s shoulder is one.

Some parts can’t move, and the simulator says which rule a refused one breaks:

  • a body component, or a part on the outside of the airframe;
  • a part holding a motor, since the motor would not go with it;
  • a part inside another part that moves;
  • one tube of a cluster;
  • a part covered by a mass override on its stage, or by one on a component around it that covers what that component holds. The override doesn’t say how much of that mass is the part’s.

A flight with a separation or ejections can’t have shifts yet. A shift can’t start before the rocket leaves the rail either. The rail has no stop at its foot. So a part thrown toward the tail on the pad could push the rocket up the rail and leave it hanging there. The simulator stops the flight with an error if one would. A shift timed close to the rail exit can therefore fly in one flight and stop another that leaves the rail later. Time it from the burnout or the apogee instead.

The motion. A part doesn’t jump from one place to the next. It follows a cycloid, the curve a cam designer calls cycloidal motion. It starts at rest, speeds up, and slows to rest again. Its acceleration is zero at both ends, so neither its speed nor its acceleration jumps. With τ the fraction of the move’s time gone, the part is s(τ) of the way along:

s(τ)=τ−sin(2πτ)2π,0≤τ≤1

At τ=12 it is exactly halfway, moving fastest, at twice the average speed. Its acceleration peaks at 2π×travel/T2 for a move taking T. A move shorter than 10 ms is refused. The peak there is 63 km/s² for each meter of travel, closer to an impact than a motion.

The move’s time is cut into 16 equal parts by stop times, so the integrator takes at least 16 steps across it. That matters with fixed-step RK4: a 10 ms step would otherwise take a 10 ms move in one step.

What the rocket’s mass properties do

Moving a part inside the rocket doesn’t change the rocket’s mass. It moves the center of mass the same way as the part, by the part’s share of the mass. With M the rocket’s mass, m the part’s and Δ how far it has moved:

center of mass moves bymΔM

The inertia changes as well. The simulator takes the part’s contribution out where it was and puts it back where it is, both about the new center of mass. It uses the parallel-axis theorem. The part’s own inertia about its own center goes with it unchanged. Write 𝐜0 for the part’s center where the design puts it and 𝜹 for the move. 𝐜𝐠new is the rocket’s new center and Inew its inertia about that center. Iwas is the rocket’s inertia with the part where it was, taken about 𝐜𝐠new. With E the unit matrix, J(𝐯)=|𝐯|2E−𝐯𝐯T:

Inew=Iwas+mJ(𝐜0+𝜹−𝐜𝐠new)−mJ(𝐜0−𝐜𝐠new)

As a check by hand, think of the rocket as two bodies: the part and everything else. About the center of mass, the rocket’s inertia is the sum of the two bodies’ own inertias plus μJ(𝐋). Here μ=m(M−m)/M is the reduced mass and 𝐋 is the line from the rest’s center to the part’s. Moving the part changes only 𝐋. The tests check the simulator’s inertia against this formula.

The stability margin. The static margin is the distance from the center of mass back to the center of pressure. It’s in calibers of the rocket’s diameter d (Flight metrics: stability margins). It takes the center of pressure with the air along the axis at Mach 0, which doesn’t depend on where the mass is. So a part moving Δ toward the tail changes it by:

change in static margin=−mΔMd

The flight margin, at the flight’s own Mach number, moves by the same amount at any one instant, since only its center of pressure differs.

What the equations of motion add

The equations of motion (Rigid-body flight) are written about the nose tip, O, a point fixed in the airframe, in body axes. 𝝎 is the airframe’s rate of turn and 𝐫 the center of mass seen from O. The equations already allow for a center of mass that moves through the airframe and an inertia that changes, because burning propellant does both. Primes there, as below, mean how fast something changes with time, as seen from the airframe. Then 𝐫′ and 𝐫″ are the center of mass’s velocity and acceleration through the airframe. I′ is how fast the inertia about O changes. A part that moves adds to those terms, and adds one term more.

Sum Newton’s law over every particle of the rocket. Each particle’s acceleration is the nose tip’s acceleration, plus the airframe’s rotation, plus its own motion inside the airframe. In the force equation, the particles’ motion inside the airframe gives the 𝐫′ and 𝐫″ terms, with nothing more. In the moment equation it gives I′𝝎, and also this term:

𝝎×𝐡+𝐡′,𝐡=∑m𝝆×𝝆′

𝐡 is the moving parts’ angular momentum about the nose tip, relative to the airframe. 𝝆 is a part’s center and 𝝆′ its velocity inside the airframe. A part only slides, so every point of it moves at the same 𝝆′. When the part is on the axis, 𝝆 and 𝝆′ both lie along the axis and 𝐡 is zero. When it is off the axis, 𝐡 is not zero, and the simulator carries it. The sum is over the parts that move, each with its own m, 𝝆 and 𝝆′. On the Rigid-body flight page, 𝐓21 is the name the equations (from RocketPy’s documentation) give the sum of the moments about the nose tip. 𝐓21 subtracts 𝝎×𝐡+𝐡′.

The simulator works out how fast the center of mass and the inertia change exactly, from the cycloid. For a burning motor it still estimates them from points 0.1 ms apart. The two add, so a part can move while the motor burns:

𝐫′=𝐫a′+∑m(𝜹′M−𝜹M′M2),𝐫″=𝐫a″+∑m(𝜹″M−2𝜹′M′M2+𝜹(2M′2M3−M″M2)),I′=Ia′+∑m(2(𝐜⋅𝜹′)E−𝜹′𝐜T−𝐜𝜹′T)

The sums are over the parts that move, each with its own m, 𝜹 and 𝐜. Here 𝐫a and Ia are the rocket’s with every part where the design puts it. M′ and M″ are how fast the rocket’s mass changes and how fast that changes, both zero once the motor is out. 𝜹′ and 𝜹″ are the part’s velocity and acceleration along its move, and 𝐜=𝐜0+𝜹 is the part’s center now.

A worked example

The example moving_ballast.rs flies the project’s 54 mm (2.1 in) test design (validation/designs/synthetic-54mm-three-fin.json, a body 56.3 mm (2.2 in) across) on an I175 motor. The design carries 200 g of ballast in its airframe. The ballast is a cylinder 50 mm (2.0 in) long on the axis, its center 0.375 m (1.23 ft) aft of the nose tip. At 5 s, well after the 2.5 s burn, it slides 0.3 m (0.98 ft) toward the tail over one second. What the example prints (the transverse inertia is about an axis across the rocket through its center of mass, the one it pitches about):

time (s)mass (kg)center of mass (m aft of the nose tip)transverse inertia (kg·m²)
4.000.81880.66810.09556
5.250.81880.67480.09248
5.500.81880.70480.08138
5.750.81880.73470.07483
7.000.81880.74140.07399

By hand, the center of mass moves 0.2×0.3/0.8188=0.0733m aft. At 5.5 s, halfway through the move, it has gone exactly half of that. The transverse inertia falls because the ballast ends up near the center of mass. The two-body check gives the change too:

  • μ=0.2×0.6188/0.8188 =0.1511kg.

  • The rest of the rocket, 0.6188 kg, has its center at

    (0.8188×0.6681−0.2×0.375)/0.6188=0.7628m

    aft of the tip.

  • The ballast’s center moves from 0.375 m (1.23 ft) to 0.675 m (2.21 ft). So its distance from the rest’s center shrinks from 0.3878 m (1.272 ft) to 0.0878 m (0.288 ft).

  • The inertia changes by

    0.1511×(0.08782−0.38782)=−0.0216kg⋅m2,

    as the table shows.

The static margin falls from 4.297 calibers to 2.996, a change of −1.302 from the unrounded values. By hand it is −0.0733/0.0563=−1.302, with d=0.0563m. The apogee barely moves: 1,749.8 m (5,741 ft) with the ballast moving, 1,749.9 m (5,741 ft) with it held still.

Checks, limits and sources

How the model is checked, what it leaves out, and its sources.

How it is checked

The tests are in hpr_sim::shifts and hpr_design::mass. The last column is what each test measured, where it records it, and in brackets the bound it holds the code to.

testwhat it showsmeasured (bound)
a_part_moved_inside_a_body_gives_the_hand_computed_wholea point moved inside a cube matches a hand calculation, and the whole rebuilt with the point movedexact (1e-15)
mass_properties_before_during_and_after_a_shift_match_the_hand_calculationthe example’s rocket before, halfway and after, against the two-body formula(1e-15 m and kg·m²)
a_moving_mass_shifts_the_static_margin_by_the_hand_calculationthe static margin at every coast sample of the flight equals −mΔs(τ)/(Md) from its start(1e-12 calibers)
a_part_moving_off_the_axis_keeps_both_momenta_in_free_spaceno air or gravity, the rocket turning about all three axes, the ballast 1 cm (0.39 in) off the axis: the angular momentum about the center and the center’s velocity stay constant6.9e-12 of the angular momentum (1e-10), 2.6e-12 m/s (1e-10)
a_shift_s_rates_are_the_derivatives_of_its_mass_propertiesthe exact rates against differences of the mass properties, during the burn and after it𝐫′ 2e-11 m/s (1e-9), 𝐫″ 3e-8 of itself (1e-7)
a_fixed_step_follows_a_short_shift_in_its_stopsthe free-flight case with RK4 at 10 ms steps and a 10 ms move: 16 steps across it1.2e-4 m/s (3e-4)
a_canopy_that_opens_while_the_ballast_moves_keeps_the_center_s_velocityin a vacuum, a drogue opening halfway through a move keeps the center’s velocity, and from then on the center falls freely while the ballast finishes its move(1e-12 m/s at the opening, 1e-9 m/s after)
a_shift_the_flight_starts_gets_its_stops_tooa move started at apogee gets its 16 stop times when it startsexactly 16 steps
a_shift_starts_at_apogee_or_at_its_height_on_the_way_downthe triggers the flight watches for start the move at the apogee, and at 200 m (656 ft) on the way down(1e-6 m)

The free-flight test is the one that checks the new term. Without 𝝎×𝐡+𝐡′, its error would be the size of the ballast’s own angular momentum relative to the airframe. That peaks at 1.8% of the rocket’s angular momentum. It measures 6.9e-12.

A first version took the part’s rates from differences 0.1 ms apart, as the motor’s are. In free flight it kept the center’s velocity only to 1e-8 m/s, the error of the difference itself, so the rates were made exact. A check with RK4 taking a 10 ms move in a single step found the center’s velocity off by 0.071 m/s (0.23 ft/s). The 16 stop times across each move bring it to 1.2e-4.

Every refusal has a test that checks which rule fired, in shifts_that_cannot_be_made_are_refused, refusals_that_need_a_design_of_their_own and triggers_a_shift_cannot_have_are_refused_in_its_own_words.

What it leaves out

  • Ballast or a payload that leaves the rocket while the rest flies on is Released mass, added in the released-mass milestone.
  • A separation, ejections or a release can’t come with shifts. Their pieces and parts are fixed before the flight, with every part where the design puts it.
  • A part can only slide along the axis, at whatever distance from the axis the design puts it. It can’t move across the axis or turn.
  • The cycloid brings the part to rest smoothly. A real mechanism may stop it with a shock, which a rigid airframe can’t model.
  • The simulator doesn’t warn when a shift takes the margin below a safe value. Read the margin from the flight’s metrics (Flight metrics).

The decision record is ADR-087.

References

  • [MK] J. L. Meriam and L. G. Kraige, Engineering Mechanics: Dynamics. Chapter 4 (kinetics of systems of particles) sums the force and moment equations over particles. It also covers angular momentum about a moving point. Appendix B has the parallel-axis theorem and the inertia tensor.

  • [N] R. L. Norton, Design of Machinery, the chapter on cam design, with the cycloidal displacement

    s=h[θβ−12πsin2πθβ].
  • The equations of motion this adds to: the RocketPy technical documentation, “Equations of Motion” v0 and v1 (Rigid-body flight).

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