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. , and 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;
- along the rotation axis toward the north pole;
- through the prime meridian at the equator;
- completes the right-handed set (90° E).
A geodetic position gives the latitude (positive north, in ) and the longitude (positive east). The height is above the ellipsoid, along its normal.
is ellipsoidal height, not height above mean sea level. The two differ by the geoid undulation (, with 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 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 , at the pad on the ground.
-
The axes are east, north, up along the ellipsoid normal at the origin.
-
To ECEF, . The columns of are, in ECEF components:
-
is Earth-fixed, so not inertial. It turns with the Earth at in components, with . The translational equations in add the Coriolis term . The centrifugal term is already inside normal gravity and must not be added again (Gravity).
-
is a tangent plane, so is not altitude. A point at at horizontal distance from the pad stands about 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 (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.
- lies along the axis of symmetry, positive toward the nose. is the design’s zero radial direction, the angle from which fins, rail buttons and lugs are placed. .
- The thrust of a motor aligned with the axis acts along .
- Design stations are measured aft from the nose tip, as design files state them. They map to with , so and the whole rocket lies at (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 and the rocket’s velocity relative to the air, in .
-
The flow roll is the direction in which the air crosses the body, measured in the - plane from toward . Fin of a set sits at from the lateral airflow, with the set’s base angle.
-
There is no separate sideslip angle: says how far the air crosses the body and which way.
-
With the lateral air direction in , the normal and side forces are
is positive along , the way the crossing air pushes the body, and is across the flow’s plane (Aerodynamics). The axial force is . is positive when the flow meets the nose and drag pushes toward the tail. It is negative past , when the rocket moves tail first.
-
The rolling moment is about , right-handed, with the reference diameter. A positive one turns toward . A fin set’s positive cant turns the leading edge of fin 0 (the fin along ) toward . So it turns the rocket about , clockwise seen from ahead of the nose, and the roll rate settles negative (Roll: forcing and damping).
Attitude
The attitude is a unit Hamilton quaternion (glam DQuat, stored x, y, z, w) that maps
body components to launch-frame components (in glam, q.mul_vec3(v_B)):
- and are the same attitude.
- The body angular velocity is the rate of relative to , in components.
- The kinematics are (Solà 2017, eq. 200). The integrator renormalizes
after every step (
attitude::renormalize). - itself turns at (above), so differs from the inertial rate by , 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 , the heading of the body axis, clockwise from true north ( is east), in ;
- the elevation , the angle of the body axis above the horizon ( is vertical), in ;
- the roll , the turn about , in .
-
At zero roll, is horizontal, to the right of the heading: in . is
-
Vertical is a singularity: at , and turn about the same axis.
LaunchAngles::from_quaternionthen reports 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:
- is the heading and the inclination.
- is the rail-button angular position for a
tail_to_noserocket, and minus it for anose_to_tailrocket. - RocketPy 1.13.0 sets precession , nutation and spin ,
then builds (
rocketpy/simulation/flight.py:1557-1579,rocketpy/tools.pyeuler313_to_quaternions). validation/oracles/rocketpy/attitude.pybuilds real RocketPy flights for 8 rail setups, with both orientations, and records the initiale0…e3.frames::tests::launch_angles_match_the_rocketpy_oraclechecks that (w, x, y, z) is the same attitude to 1e-12 rad.- RocketPy’s body 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 due east, there being the radius Geodesy calls , 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.