Skip to main content

Module real_flight

Module real_flight 

Source
Expand description

Real flights: hpr against the altitude logs of RocketPy’s example rockets, flown in the ERA5 weather of their day (M2.3b, decision ADR-082).

Each RealFlight is a rocket RocketPy’s documentation flies against its team’s log. hpr flies the same rocket (its design under validation/designs/, built from the example’s inputs), on the example’s own thrust file with the example’s burn options, from the example’s rail and site, in the ERA5 file the example reads, with hpr’s own aerodynamics: the way a user would fly it. The log is the reference.

The logs, most of the thrust files and the full weather files carry their own terms, so they are read from the pinned RocketPy checkout under the gitignored refs/ and never committed. What is committed is REPORT_JSON and REPORT_MD: per flight, the log’s apogee and hpr’s, the apogee error, the altitude-trace RMS, and the SHA-256 of every file read. cargo xtask real-flights writes them and --check flies them again; CI, which has no refs/, holds the summary to the rows and the page to the data (RealFlightReport::check_consistent).

What is compared, for each flight:

  • Heights: a barometric altimeter reads the standard atmosphere’s altitude of the pressure it measures, less the pad’s, not the height it climbed: on a warm day, less. So hpr’s height is read the same way, from the ERA5 pressure at its center of mass, for a log whose Altimeter is barometric (Barometer), and taken as it is otherwise. Each log’s height column is used as recorded.
  • Apogee: the highest height in the log, read up to Log::until_s where the recovery’s pressure transients would otherwise set it, against hpr’s apogee read the same way. The error is hpr’s less the log’s, as a percentage of the log’s.
  • Altitude-trace RMS: the log’s heights against hpr’s over the ascent. The two clocks are aligned where each trace first reaches ALIGN_HEIGHT_M, since a log’s zero is its own (armed, launch detected, or power on) and not hpr’s ignition. The RMS is over every log row from there until the first of the two apogees, hpr’s heights linearly interpolated from a GRID_S grid of its dense output. The descent is not compared: its events (which parachute opened, when) are the team’s, and one of these flights lost its main.

Two diagnostic flights, not predictions, say where a miss may come from: the same flight on the example’s own drag, and where the example reshapes its thrust file, on the file as recorded. Where a log keeps its pressure or the flight a satellite altitude, the report holds the barometric reading against them. Each row carries the SHA-256 of its flight’s entry in FLIGHTS, so CI sees an input change the report hasn’t caught up with.

The mean absolute apogee error is reported against the APOGEE_TARGET_PERCENT target of docs/VALIDATION.md; it is a target, not a gate. A flight outside it is an outlier, and each outlier carries its explanation in RealFlight::explanation.

Structs§

Barometer
A barometric altimeter on a pad, in the air of a day: it reads the standard atmosphere’s altitude of the day’s pressure where it is, less that at the pad, H(p(z)) − H(p(z₀)) (Ussa76::pressure_altitude_m).
FileRead
A file read and its SHA-256.
FlightRow
One flight’s result, as the report keeps it.
Gnss
Where a flight’s satellite altitude is and how to read it.
Log
Where a flight’s altitude log is and how to read it.
Means
The mean apogee errors over some of the report’s flights.
RealFlight
One logged flight.
RealFlightReport
The real-flight report.
RecordedThrust
The flight on the thrust file as recorded, without the example’s reshape.
Summary
What the report sums up: over every flight, the seven compared as soon as they were flown (RealFlightReport::flights) and the five predicted first (RealFlightReport::predicted_first), unless a field says otherwise.
TraceComparison
What the trace comparison gives.
Varied
A flight flown as a Variant of its report’s: its apogee, and whether its design has a stretch on its last guide alone for the tip-off phase to fly.

Enums§

Altimeter
What a log’s height is.
ExampleDrag
The drag the example flies, as its notebook gives it: the second, diagnostic flight’s.
Explanation
Why a flight’s apogee misses the log’s by more than APOGEE_TARGET_PERCENT: a claim the report’s own numbers are checked against (RealFlightReport::check_consistent), so a change that makes it false fails the check, with the words that argue it.
RealFlightError
Why a real flight could not be read, flown or reported.

Constants§

ALIGN_HEIGHT_M
The height each trace’s clock is aligned at, m above its start.
APOGEE_TARGET_PERCENT
The target for the mean absolute apogee error, per cent (docs/VALIDATION.md, “Principles”).
ERA5_CREDIT
The Copernicus attribution and the ERA5 citation that a page publishing results computed in RocketPy’s ERA5 files carries (#1095): the Copernicus license’s credit lines, in the words the guide’s pages use for the same flights, and the dataset with its license, as THIRD-PARTY-NOTICES.md names it. The real-flight and flight-residual reports print it under Sources; the from-boost and public-predictions reports don’t yet (#1481).
EUROC_2022_CONVERTED
What the real-flights page adds to ERA5_CREDIT: its three EuRoC 2022 flights read RocketPy’s EuRoC 2022 file as converted to the classic netCDF format (netCDF-3), since hpr’s reader refuses the netCDF-4 original; validation/oracles/netcdf/euroc_2022.py checks that the conversion holds the file’s geopotential, temperature and wind bit for bit.
FLIGHTS
The flights, in the order the report lists them.
GRID_S
The spacing of hpr’s heights the trace is compared against, s.
MASS_FIXTURE
The design fixture that records each example’s own thrust file and burn options.
REPORT_JSON
The report, as data.
REPORT_MD
The report, as a page.
ROCKETPY
The pinned RocketPy checkout the logs, thrust files and weather files are read from.

Functions§

compare_traces
The ascent of hpr (time since ignition, height) against the log’s, each aligned where it first reaches ALIGN_HEIGHT_M, over the log’s rows from there to the first of the two apogees.
example_thrust
The example’s own thrust file and burn options, from MASS_FIXTURE’s record of the case.
fly
Flies one flight and compares it with its log.
fly_corrected
The apogee of fly’s flight with correction flown, m above the start, as the log’s altimeter would read it: every motor’s impulse and the drag scaled (Correction), the log, design, thrust file, rail and air as fly reads them. Only that flight is flown: not the one on the example’s drag table, nor the one on the recorded thrust.
fly_varied
fly’s flight flown as variant, as fly_corrected flies a correction: its apogee as the log’s altimeter would read it and whether its design has two guides at different stations. With Variant::GUIDED it is the report’s flight itself, apogee for apogee.
launch_day
The flight’s environment in its ERA5 file’s air and wind, and that air alone.
parse_log
A log’s rows as (time, height in meters), in file order.
parse_thrust
A thrust file as RocketPy 1.13.0 reads it, with the example’s burn options.
rail_of
The flight’s rail.
read_bytes
The bytes of the file at relative under root, what naming why it is read.
rocket_on_curve
The design’s rocket on the thrust curve read from thrust_path.
run
Flies every flight in FLIGHTS, then the five predicted first (crate::public_predictions::run), compares each of those with its log (crate::predicted_first::compare) and builds the report.
sha256_hex
The SHA-256 of bytes, in lower-case hex.
summarize
The summary of rows, the flights compared first, and predicted, the flights predicted first: the means over all of them in that order, and over each part.