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

Frames and sign conventions

This page defines the axes and signs all of HPR Sim shares, from the Earth-centered frame to the rocket’s body, attitude and launch angles.

In short

  • What it models: the directions and signs the whole simulator shares. They define a frame fixed to the Earth at its center, the launch-site frame (east, north, up) and the rocket’s body frame. They also define its angle to the airflow, its attitude (which way it points) and its launch angles.
  • Sources: the WGS 84 standard, NGA.STND.0036 (2014), as in Geodesy. J. Solà, Quaternion kinematics for the error-state Kalman filter (2017). RocketPy 1.13.0, for its launch-angle convention.
  • How well it is validated: unit tests, and one check against another simulator. For 8 rail setups, launch angles give RocketPy’s starting attitude to 1e-12 rad. Over 1e6 integration steps, attitude stays within 1e-9 rad of the exact answer. Eight of NASA’s check cases fly through the launch frame against the codes NASA published, two of them shots that carry a body kilometers from the pad, which come out inside the codes’ spread (a free body against NASA’s check cases). No real-flight check.
  • What it leaves out: heights are above the WGS 84 ellipsoid, not sea level. The two are up to about 100 m (328 ft) apart. The attitude equations leave out the Earth’s rotation rate, 7.3e-5 rad/s, which is tiny next to a rocket’s pitch rates (the rigid-body flight decision). On a tumbling brick, NASA’s check case 2, what that leaves out grows to 0.01633 deg/s within 30 s (a free body against NASA’s check cases, #1521).

Sources and units

Where the frames are defined in the code, and the units and rotation rules every frame uses.

Code and sources

This is the single definition of the frames, and every crate follows it. Code: hpr_core::{geodesy, frames, attitude}. The frames and gravity decision records why these choices were made.

Units and angles

  • SI throughout: meters, seconds, kilograms, radians. Degrees exist only at I/O boundaries (Geodetic::from_degrees).
  • Every rotation is right-handed. Rx(θ), Ry(θ) and Rz(θ) turn vectors by +θ about the named axis (active rotations).

The frames

The three frames: one fixed to the Earth, one at the launch site, and one fixed to the rocket.

Earth-centered Earth-fixed (ECEF)

The WGS 84 conventional terrestrial frame:

  • origin at the Earth’s center of mass;
  • +Z along the rotation axis toward the north pole;
  • +X through the prime meridian at the equator;
  • +Y completes the right-handed set (90° E).

A geodetic position (φ,λ,h) gives the latitude φ (positive north, in [−π/2,π/2]) and the longitude λ (positive east). The height h is above the ellipsoid, along its normal.

h is ellipsoidal height, not height above mean sea level. The two differ by the geoid undulation N (h=H+N, with |N| up to about 100 m (328 ft)). Inputs quoted above sea level must be converted before use. HPR Sim has no geoid model, so a flight takes N at the launch site as an input. Atmosphere shows where it is used.

Launch frame L (East-North-Up)

  • The origin is the launch site’s geodetic position (φ0,λ0,h0), at the pad on the ground.

  • The axes are xL east, yL north, zL up along the ellipsoid normal at the origin.

  • To ECEF, 𝐫ECEF=𝐫0+R𝐫L. The columns of R are, in ECEF components:

    𝐞ˆ=(−sinλ0cosλ00),𝐧ˆ=(−sinφ0cosλ0−sinφ0sinλ0cosφ0),𝐮ˆ=(cosφ0cosλ0cosφ0sinλ0sinφ0)
  • L is Earth-fixed, so not inertial. It turns with the Earth at 𝛀=ω(0,cosφ0,sinφ0) in L components, with ω=7.292115×10−5rad/s. The translational equations in L add the Coriolis term −2𝛀×𝐯. The centrifugal term is already inside normal gravity and must not be added again (Gravity).

  • L is a tangent plane, so zL is not altitude. A point at zL=0 at horizontal distance d from the pad stands about d2/(2ρ) higher above the ellipsoid than the pad. Here ρ is the Earth’s radius of curvature at the pad, plus the pad’s height. At 10 km (6.2 mi) to the east, the rise is 7.8 m (26 ft). Height above the ellipsoid comes from LaunchFrame::geodetic_from_enu. The flight engine detects apogee and ground contact with that height, not with zL (Rigid-body flight, Loft’s lesson on apogee height).

Body frame B

  • The origin is the nose tip, on the axis (the design-tree decision). Positions in mass properties are measured from it.
  • zB lies along the axis of symmetry, positive toward the nose. xB is the design’s zero radial direction, the angle from which fins, rail buttons and lugs are placed. yB=zB×xB.
  • The thrust of a motor aligned with the axis acts along +zB.
  • Design stations s are measured aft from the nose tip, as design files state them. They map to zB=zref−s with zref=0, so zB=−s and the whole rocket lies at zB≤0 (Design tree).

Angles and attitude

The rocket’s angles to the airflow, its attitude, and the launch angles used for input and output.

Aerodynamic angles

  • The angle of attack α is the total angle between +zB and the rocket’s velocity relative to the air, in [0,π].

  • The flow roll φ is the direction in which the air crosses the body, measured in the xB-yB plane from xB toward yB. Fin k of a set sits at Λk=θ0+2πk/N−φ from the lateral airflow, with θ0 the set’s base angle.

  • There is no separate sideslip angle: α says how far the air crosses the body and φ which way.

  • With 𝐰ˆ=(cosφ,sinφ,0) the lateral air direction in B, the normal and side forces are

    qAref(CN𝐰ˆ+CY(𝐳ˆB×𝐰ˆ)):

    CN is positive along 𝐰ˆ, the way the crossing air pushes the body, and CY is across the flow’s plane (Aerodynamics). The axial force is −qArefCA𝐳ˆB. CA is positive when the flow meets the nose and drag pushes toward the tail. It is negative past α=90°, when the rocket moves tail first.

  • The rolling moment is qArefdCl about +zB, right-handed, with d the reference diameter. A positive one turns xB toward yB. A fin set’s positive cant turns the leading edge of fin 0 (the fin along +xB) toward −yB. So it turns the rocket about −zB, clockwise seen from ahead of the nose, and the roll rate p=ωz settles negative (Roll: forcing and damping).

Attitude

The attitude is a unit Hamilton quaternion q (glam DQuat, stored x, y, z, w) that maps body components to launch-frame components (in glam, q.mul_vec3(v_B)):

𝐯L=q⊗𝐯B⊗q∗
  • q and −q are the same attitude.
  • The body angular velocity 𝝎B is the rate of B relative to L, in B components.
  • The kinematics are q˙=12q⊗(0,𝝎B) (Solà 2017, eq. 200). The integrator renormalizes q after every step (attitude::renormalize).
  • L itself turns at 𝛀 (above), so 𝝎B differs from the inertial rate by R(q)𝖳𝛀, at most 7.3e-5 rad/s. The flight engine’s rotational equations leave that term out (the rigid-body flight decision).

Launch angles

Launch-rail-style angles describe the attitude for input and output (frames::LaunchAngles):

  • the azimuth A, the heading of the body axis, clockwise from true north (π/2 is east), in [0,2π);
  • the elevation E, the angle of the body axis above the horizon (π/2 is vertical), in [−π/2,π/2];
  • the roll φ, the turn about zB, in (−π,π].
q=Rz(−A)⊗Rx(E−π/2)⊗Rz(φ),zB in L=(sinAcosEcosAcosEsinE)
  • At zero roll, xB is horizontal, to the right of the heading: (cosA,−sinA,0) in L. yB is

    (sinEsinAsinEcosA−cosE)
  • Vertical is a singularity: at E=±π/2, A and φ turn about the same axis. LaunchAngles::from_quaternion then reports A=0 and puts the whole turn into φ. This is for reporting only: the state is always the quaternion.

  • These angles are RocketPy’s 3-1-3 convention:

    • A is the heading and E the inclination.
    • φ is the rail-button angular position for a tail_to_nose rocket, and 2π minus it for a nose_to_tail rocket.
    • RocketPy 1.13.0 sets precession ψ=−heading, nutation θ=inclination−90° and spin φ, then builds q=qz(ψ)qx(θ)qz(φ) (rocketpy/simulation/flight.py:1557-1579, rocketpy/tools.py euler313_to_quaternions).
    • validation/oracles/rocketpy/attitude.py builds real RocketPy flights for 8 rail setups, with both orientations, and records the initial e0…e3.
    • frames::tests::launch_angles_match_the_rocketpy_oracle checks that q (w, x, y, z) is the same attitude to 1e-12 rad.
    • RocketPy’s body +z also points toward the nose.

Tests that pin this

  • In hpr_core::geodesy::tests:
    • geodetic → ECEF → geodetic, from −10 km (−6.2 mi) to 1,000 km (621 mi);
    • ECEF → geodetic → ECEF, from 6,250 km (3,884 mi) to 46,000 km (28,583 mi) from the center;
    • axis points, the sphere limit, and the ENU rotation being proper with 𝐮ˆ normal to the ellipsoid.
  • In hpr_core::frames::tests:
    • angles → quaternion → angles (off vertical), and quaternion → angles → quaternion (everywhere, exactly vertical included);
    • ENU ↔ ECEF ↔ geodetic round trips for sites anywhere, within 2,000 km (1,243 mi) and up to 1,000 km (621 mi) high;
    • named attitudes, and the tangent-plane rise d2/(2ρ) due east, ρ there being the radius Geodesy calls N, plus the site’s height.
  • In hpr_core::attitude::tests: the kinematic equation checked against a closed-form coning motion, and norm drift ≤ 1e-12 over 1e6 RK4 steps with attitude error < 1e-9 rad.
  • cargo xtask check-cases, held by the gate where the codes’ files are fetched: NASA’s check cases 1 to 3 and 6 to 10 flown in the launch frame, the positions of cases 6 to 10 turned into Earth-fixed axes and compared as distances (a free body against NASA’s check cases). Two things of this page are in them. The height above the ellipsoid is read back from the launch frame along a 4.4 km (2.7 mi) fall, down the site’s vertical on the equator, where the ellipsoid’s shape hardly enters. The Earth’s rate is turned from the launch frame into the body’s axes to give inertial rates. In cases 1 and 2, with the two named model differences taken off each kept code’s largest difference, at most 0.1364 mm (0.0054 in) of altitude and 0.001005 deg/s of body rate are left, both inside the codes’ spread; read at every sample, case 2’s rates are left just past it. Case 3’s rates and the sphere’s positions in cases 6 to 8 are traced to inside the spread, and cases 9 and 10 come out inside it as flown; the flight page’s table gives each. The attitude itself is not compared.
FusionSpace HPRVersion 0.1.0Issued 2026-11-21In preparationAbout HPR Sim