3D rigid-body mechanics

From many particles to one rigid body

Imagine a body as particles with masses $m_i$, world positions $r_i$, and velocities $v_i$. Its total mass and center of mass are:

Linear momentum compresses all translational motion into one vector:

Angular momentum about the center of mass records rotational motion:

The last equality is frame-sensitive: $I$ and $\omega$ must be expressed in the same frame. With no external force, $p$ is constant. With no external torque, world-frame $L$ is constant—even though its body-frame components may dance.

A force changes translation; its lever arm changes rotation

Newton's translational and rotational laws have matching shapes:

A force $F$ applied at an offset $r$ from the center of mass produces torque:

Only the perpendicular component contributes. In the reference lab, $r=[0.3,0,0]\,m$ and $F=[0,5,0]\,N$ yield $\tau=[0,0,1.5]\,N\!\cdot\!m$. Point the force along the lever arm and the torque becomes zero.

offset = np.array([0.3, 0.0, 0.0])
force = np.array([0.0, 5.0, 0.0])
torque = np.cross(offset, force)

assert np.allclose(torque, [0.0, 0.0, 1.5])

Experiment 1: equal torque, unequal response

Mass measures resistance to translational acceleration. The inertia tensor measures resistance to angular acceleration and also depends on how mass is distributed.

For a box of full side lengths $w,h,d$ aligned with its principal body axes:

At rest, Euler's rotation equation reduces to $\alpha=I^{-1}\tau$. Away from rest, the coupling term matters:

Experiment 01verified

Push a cube and a rod with the same torque

If mass and torque match, how much does shape alone change angular acceleration?

A 0.2 m cube and a 0.8 × 0.2 × 0.2 m rod each have mass 1 kg. LavenderSim applies the same 0.02 N·m world-z torque. The rod's z inertia is 8.5 times larger, so the cube's angular acceleration is 8.5 times larger.

3.000 rad/s²cube prediction

0.353 rad/s²rod prediction

8.5×measured ratio

Failure modes to try: increase the timestep until integration error is visible; add damping and notice that the velocity ratio is no longer exactly constant; rotate a non-symmetric body and remember that diagonal body inertia is not diagonal in world coordinates.

Expected result

The command exits successfully and reproduces the numerical or visual relationship described in this card.

Failure modes

Non-finite values, a reversed trend, a failed assertion, or a materially different plot means the assumptions, seed, timestep, build, or backend should be inspected before continuing.

python examples/tutorials/simulation/ch03_rigid_body_mechanics/lavendersim_torque.py --quickView source ↗

For body-to-world rotation $R_{WB}$, the same physical inertia written in world coordinates is:

Orientation is not three independent numbers

A rotation matrix $R\in SO(3)$ has nine entries but only three degrees of freedom. It must satisfy $R^\mathsf{T}R=I$ and $\det R=1$. Axis-angle stores a unit axis $\hat u$ and one angle $\theta$. A unit quaternion stores the same rotation as:

LavenderSim's public convention is (x, y, z, w), with the scalar component last. Quaternions $q$ and $-q$ describe the same orientation. They avoid Euler-angle singularities, but their unit-length constraint must still be maintained numerically.

Experiment 2: Euler-angle addition versus quaternions

Experiment 02verified

Integrate a constant world angular velocity

What breaks if we treat angular velocity as three Euler-angle derivatives?

For a world-frame angular velocity, quaternion kinematics are:

$$\dot q=\frac{1}{2}\,[\omega_W,0]\otimes q$$

The lab integrates this equation while a deliberately incorrect method adds $\Delta t\,\omega$ directly to XYZ Euler angles. It also integrates a second quaternion without normalization.

87.6°naïve Euler error at 4 s

0.0087°quaternion error at 4 s

|q| = 1.0138without normalization

Failure modes to try: use a single-axis rotation, which can hide the Euler-angle bug; enlarge dt, which increases quaternion truncation error; swap world- and body-frame multiplication order.

Expected result

The command exits successfully and reproduces the numerical or visual relationship described in this card.

Failure modes

Non-finite values, a reversed trend, a failed assertion, or a materially different plot means the assumptions, seed, timestep, build, or backend should be inspected before continuing.

python examples/tutorials/simulation/ch03_rigid_body_mechanics/rigid_body.py --quickView source ↗

If $\omega$ is expressed in the body frame instead, multiplication moves to the other side:

Experiment 3: steady spin and tumbling

In principal body axes, torque-free motion follows Euler's equations:

Spin exactly around a principal axis and the other components stay zero. Start with components on several axes and the body-frame angular velocity evolves, even though world angular momentum and rotational kinetic energy remain constant:

Experiment 03verified

Integrate torque-free Euler equations

How can angular velocity change when no external torque acts?

0 changeprincipal-axis body ω

3.30 rad/smixed-axis body ω change

< 4e-7world momentum error

Failure modes to try: replace RK4 with explicit Euler and plot energy drift; forget whether $\omega$ is in the body or world frame; test rotation near the intermediate principal axis.

Expected result

The command exits successfully and reproduces the numerical or visual relationship described in this card.

Failure modes

Non-finite values, a reversed trend, a failed assertion, or a materially different plot means the assumptions, seed, timestep, build, or backend should be inspected before continuing.

pytest -q tests/tutorials/test_ch03_rigid_body_mechanics.pyView source ↗

Experiment 4: trade angular momentum internally

A reaction wheel motor exerts equal and opposite torques on its rotor and housing. In an ideal isolated system:

Experiment 04verified

Command ReactionWheelCube-v0

Can an internal actuator rotate a body without pushing on the outside world?

A positive x-wheel command makes every recorded wheel sample positive and every cube sample negative.

Scope of the claim: the current environment contains damping and a world-anchored spherical joint. It demonstrates opposite angular-velocity response and useful control physics, not exact conservation for a perfectly isolated spacecraft.

Failure modes to try: saturate the actuator, reverse the command, or command two wheels simultaneously and inspect cross-axis coupling.

Expected result

The command exits successfully and reproduces the numerical or visual relationship described in this card.

Failure modes

Non-finite values, a reversed trend, a failed assertion, or a materially different plot means the assumptions, seed, timestep, build, or backend should be inspected before continuing.

python examples/tutorials/simulation/ch03_rigid_body_mechanics/reaction_wheel_exchange.py --quickView source ↗

Let Python choose what the browser explains

Live frames now accept Python-defined body axes and vectors. That makes the visualization part of an experiment rather than a hard-coded renderer feature.

viewer.publish_frame(
    sim,
    overlays={
        "axes": [{"body": "cube", "scale": 0.34}],
        "vectors": [
            {
                "label": "angular velocity",
                "origin": cube_position.tolist(),
                "vector": cube_omega.tolist(),
                "scale": 0.12,
                "color": [0.51, 0.87, 0.76, 0.95],
            },
            {
                "label": "torque",
                "origin": cube_position.tolist(),
                "vector": commanded_torque.tolist(),
                "scale": 3.0,
                "color": [0.95, 0.66, 0.77, 0.95],
            },
        ],
    },
)

The browser rotates the three body axes using authoritative body transforms and draws vector arrows in world coordinates. The same payload path can display angular momentum or any diagnostic vector computed by a Python controller.

Paw-check: reason in the right frame

1. Double every mass in the center-of-mass example. Which quantities change, and which remain fixed?
2. Move the force application point from 0.3 m to −0.3 m. Predict the torque before running the code.
3. Rotate the rod 90° about y, apply world-z torque, and compute the relevant world inertia.
4. Modify the orientation lab to use body-frame angular velocity and the corresponding quaternion multiplication order.
5. Start torque-free motion almost—but not exactly—on each principal axis. Which axis is least forgiving?
6. Reverse the reaction-wheel command and assert that both signs reverse.