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:
| field | meaning |
|---|---|
trigger | when 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) |
component | the id of the internal component that moves; everything inside it moves too |
travel_m | how far along the axis, in meters: positive toward the tail, negative toward the nose |
duration_s | how 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 of the way along:
At it is exactly halfway, moving fastest, at twice the average speed. Its acceleration peaks at for a move taking . 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 the rocket’s mass, the part’s and how far it has moved:
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 for the part’s center where the design puts it and for the move. is the rocket’s new center and its inertia about that center. is the rocket’s inertia with the part where it was, taken about . With the unit matrix, :
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 . Here 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 (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:
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, , a point fixed in the airframe, in body axes. is the airframe’s rate of turn and the center of mass seen from . 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. is how fast the inertia about 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 , and also this term:
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 , and . On the Rigid-body flight page, is the name the equations (from RocketPy’s documentation) give the sum of the moments about the nose tip. 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:
The sums are over the parts that move, each with its own , and . Here and are the rocket’s with every part where the design puts it. and 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 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.00 | 0.8188 | 0.6681 | 0.09556 |
| 5.25 | 0.8188 | 0.6748 | 0.09248 |
| 5.50 | 0.8188 | 0.7048 | 0.08138 |
| 5.75 | 0.8188 | 0.7347 | 0.07483 |
| 7.00 | 0.8188 | 0.7414 | 0.07399 |
By hand, the center of mass moves 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:
-
.
-
The rest of the rocket, 0.6188 kg, has its center at
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
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 , with . 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.
| test | what it shows | measured (bound) |
|---|---|---|
a_part_moved_inside_a_body_gives_the_hand_computed_whole | a point moved inside a cube matches a hand calculation, and the whole rebuilt with the point moved | exact (1e-15) |
mass_properties_before_during_and_after_a_shift_match_the_hand_calculation | the 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_calculation | the static margin at every coast sample of the flight equals from its start | (1e-12 calibers) |
a_part_moving_off_the_axis_keeps_both_momenta_in_free_space | no 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 constant | 6.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_properties | the 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_stops | the free-flight case with RK4 at 10 ms steps and a 10 ms move: 16 steps across it | 1.2e-4 m/s (3e-4) |
a_canopy_that_opens_while_the_ballast_moves_keeps_the_center_s_velocity | in 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_too | a move started at apogee gets its 16 stop times when it starts | exactly 16 steps |
a_shift_starts_at_apogee_or_at_its_height_on_the_way_down | the 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
-
The equations of motion this adds to: the RocketPy technical documentation, “Equations of Motion” v0 and v1 (Rigid-body flight).