The API reference
Find which crate of FusionSpace HPR holds what, and reach each crate’s rustdoc reference for every public type, function and constant.
The API reference documents FusionSpace HPR’s code: every public type, function and constant,
generated from the source by rustdoc, Rust’s documentation tool. Use it when you write a program
with the hpr library, as Getting started does. The library is released (0.1.0)
but not yet at 1.0, so none of its interface is stable: any of it can change. The simplest way in is the hpr
crate’s builder (The builder).
Where to read it. On the site, the crate names below open the reference. On GitHub they lead nowhere, because the reference is built rather than stored in the repository. Build it on your own machine instead:
cargo doc --workspace --no-deps --open
That opens one crate’s front page; the others are in the list of crates on the left. cargo xtask site builds this whole site, with the reference beside the guide.
The crates
The code is split into crates, Rust’s packages, so that a program takes only
what it needs. The split also lets the models, which don’t read or write files or use the network,
build for the web. Eleven crates hold most of the code today. The names below are the ones a
program writes in its code (use hpr_core::…). A published crate’s package, the name crates.io
and Cargo.toml know it by, adds FusionSpace’s prefix
(the public name).
So hpr is the package fusionspace-hpr, hpr_core is fusionspace-hpr-core, and so on.
hpr_validate, hpr_py, hpr_ffi and hpr_wasm aren’t published.
| crate | what it holds | limits and open work | the guide’s pages |
|---|---|---|---|
hpr | One crate to depend on: the builder for environments, motors, rockets and flights, with the other crates re-exported by name (more below) | One motor per built rocket | The builder, Models of your own |
hpr_core | Vectors and quaternions (a compact way to store a rotation), frames, the Earth’s shape, distance and bearing between places, gravity and magnetic field, interpolation tables and numerical integration of functions | Frames, Geodesy, Gravity, The magnetic field, Interpolation tables, Adaptive quadrature | |
hpr_atmos | The standard atmosphere, humidity, soundings, wind profiles and turbulence | A flight doesn’t use the turbulence yet | Atmosphere, Wind, Turbulence |
hpr_motor | Solid motors: thrust curves, mass and inertia through the burn, .eng and .rse files, and ThrustCurve.org’s whole solid catalog, bundled | Hybrid and liquid motors, which are out of scope | Solid motors, .eng files, .rse files |
hpr_design | The rocket: its tree of parts, their shapes and materials, mass properties and design checks | The design tree, Shapes, Mass properties | |
hpr_format | The HPR design format: a design as one JSON document (.hpr) with its JSON Schema, read from and written to .ork, in a zip container with other files (.hprz), older versions migrated | None. Its TypeScript and Python types are done, outside the crate | The HPR design format |
hpr_aero | Aerodynamics: normal force, center of pressure and drag to Mach 5, tables from other programs for the drag and the normal force, and drag models of your own (Models of your own) | Faster than sound, some shapes are checked on one case or not at all, and some use a theory that reads low past Mach 3 (below) | Aerodynamics |
hpr_sim | The flight: the launch rail, the equations of motion, time integration, events and recovery | Staging, air starts and clusters are checked by tests and against OpenRocket, a dropped stage’s own flight not at all, and parts that leave the airframe against exact answers only (below) | How a flight is simulated, Rigid-body flight, Time integration, Recovery, Staging |
hpr_flightdata | Reading a flight log on its own, with no design and no simulation, and the readings taken from it (below) | Not yet: formats no sample holds (listed as needing samples, evidence row G9); readings from a GPS track; the top acceleration from a board’s three axes (#781); the Mach number; a 90% interval on each reading | Reading a flight log, Flight-log readings, .pf2 files, Flight logs |
hpr_validate | The validation harness: cases, whole flights against RocketPy among them, reference data, metrics and reports | None | Accuracy, Checking a claim |
hpr_py | The fusionspace-hpr Python package (fusionspace.hpr): the builder’s environment, motor, rocket and flight from Python (more below) | Python |
Six more crates are partly built or not yet begun, and each front page says what it will hold.
hpr_ffi and hpr_wasm hold no code yet; the other four already hold some:
| crate | what it holds or will hold | done and planned |
|---|---|---|
hpr_io | Import and export of OpenRocket, RockSim and RASAero designs, export to RocketPy, OpenRocket’s parts catalog, and weather and elevation files (below) | Done: reading a .ork and its parts, writing one, ERA5 files and the parts catalog; RockSim, RASAero and RocketPy files next |
hpr_net | Optional online data, cached for offline use: weather, soundings, elevation and motor data (below) | Done: the cache, Open-Meteo’s weather, soundings, GFS and RAP, hpr weather, whole GRIB2 files in complex packing and JPEG 2000, elevation and motor stock |
hpr_analysis | Monte Carlo dispersion, sensitivity analysis and optimization (below) | Monte Carlo done; optimization done, EGO on six variables too, but for robust designs; competition rules not yet |
hpr_forensics | A flown flight against a simulation of it: what will differ, what that says about drag, mass, impulse and wind, and what went wrong | Planned: residuals and fits to a log and diagnosis |
hpr_ffi | A C interface, for other languages | Planned: use from C and in the browser |
hpr_wasm | WebAssembly bindings, for the browser | Planned: use from C and in the browser |
The command-line tool, the package fusionspace-hpr-cli, is a program rather than a library, so it has no reference here.
The command line documents its commands, output and exit codes.
The builder crate
hpr holds the builder and re-exports the other crates by name. A rocket’s parts can be made
from catalog parts (parts from a catalog). A drag model
of your own can fly in the simulator’s place.
hpr::ork::separation turns a .ork file’s staging into a
flight’s separation (example).
The reference holds a guide too, hpr::guide.
Aerodynamics faster than sound
Faster than sound, what hpr_aero flies depends on the body’s shape:
- A pointed nose, its cylinder and a boattail behind them take the shock-expansion method. The boattail’s share is unvalidated (evidence row G29).
- A blunt or vertical tip flies the method behind a Newtonian cap, checked on a sphere-cone only.
- A conical flare flush with the part ahead of it flies the method too and ends the run. It’s checked against one measured flare.
- Any other widening shape, or any step, behind the nose keeps slender-body theory, which reads low past Mach 3.
Staging, clusters and parts that leave
- Staging and air starts fly. Tests check them, and so does a comparison with OpenRocket’s two-stage, cluster and air-start examples. Each flight is within 5% of OpenRocket’s in apogee and largest speed (a two-stage and a cluster design against OpenRocket). Three cluster apogees are compared with OpenRocket’s flight with no parachute, since its parachute opened before apogee. The flight of a dropped booster or middle stage after its split isn’t validated at all (evidence row G13).
- A cluster flies, one mount of several tubes or one mount per motor, and so does a motor out. Tests check them against a hand calculation.
- A nose cone, a section or a payload can leave the airframe, optionally pushed by its charge. It lands on its own, under its own parachute or tumbling (ejection, the airframe parting, a charge’s push). This is checked against exact answers only.
Flight logs
hpr_flightdata reads a flight log on its own, with no design and no simulation, into one record.
It keeps every column but those a table pasted over a FIP sheet covers, and reads the files of a
zip archive one by one. Depend on this crate directly rather than on hpr, which pulls in the
simulator. It reads:
- PerfectFlite’s
.pf2and exports, and PerfectFlite’s older.pfa. - AltOS’s CSV, its radio telemetry (
.telem) and raw downloads (.eeprom), and its radio telemetry decoded to a table. It also reads AltOS’s CSV re-saved by a spreadsheet, its formulas kept as text, or cut to its columns. - The Raven’s FIP CSV and the Blue Raven’s, and the Raven’s
.FIParaw download. - A Raven FIP export pasted below no header, under a header you state.
- A Blue Raven’s USB download, each line held to its CRC.
- RRC3’s CSV and the RRC3’s
.rffraw download. - Eggtimer’s CSV, an Eggtimer TRS’s terminal text, and an Eggtimer’s download saved as RTF.
- AltimeterCloud’s CSV.
- Entacore AIM’s CSV, its
.xtrafiles and raw memory dumps. - AerospaceNU’s SillyGoose logs, and AerospaceNU’s flight computer board’s CSV and its ground station’s text.
- Silicdyne Fluctus’s CSV.
- The ARTS2’s interpreted data, its
.odfand its raw CSV. - A phone app’s
launchCSV. - The Featherweight app’s flight summaries (the logger’s figures, no samples).
- The R-DAS’s raw text (its counts kept as written).
- An AltiMAX altimeter’s
.xlsexport and its own.ALSfile. - A MARSA altimeter’s download.
- A course’s Teensy data logger, and one team’s radio telemetry packets,
255:…:254. - GPS tracks from Featherweight’s GPS CSV, KML, NMEA and Missile Works’ RTx (its
.rtxfile and exports). - GPS tracks in GPX, checked on invented files only (evidence row G1).
- Tables from loggers no other reader knows, by the units their headers state.
- Binary records, from a raw file or a console capture, by a layout you state.
- Tables whose headers state too little, by a column mapping you state. Such a table may have a clock that turns over, rows written as lists or behind a date and time, or columns left out.
From any logger’s barometric altitude or pressure it reads liftoff, apogee, the top speed,
landing, the flight time and the descent under each canopy. From an accelerometer along the
rocket’s axis it reads the top acceleration and burnout. Each reading comes within a stated
bound, or is withheld with the reason. A top acceleration that clipped, or whose thrust the
accelerometer shows no end to, is a floor. Clip says why it clipped: at the
part’s range, or held flat at its top.
The Python package
hpr_py builds the builder’s environment, motor, rocket and flight from Python. It flies
a drag table and RocketPy’s example flight and takes
a drag and a wind written in Python. It reads designs from
files and returns a flight’s recording as NumPy arrays. Maturin builds it into one wheel per
operating system, and it’s on PyPI as fusionspace-hpr.
Design and data files
hpr_io reads and writes design files, and reads weather and elevation files:
- OpenRocket’s parts catalog: its 16
.orcfiles are bundled, every part found by maker and part number (the format page). - A
.orkfile’s container, design document and components are read into a design (the format page). So are its motors, when each lights, and its recovery settings. - A design is written back out as a
.orkwithhpr_io::ork::export(writing a.ork). - An ERA5 weather file (netCDF classic) gives the atmosphere over a launch site at launch time (ERA5 weather files).
- A GeoTIFF elevation file gives a site’s height (A launch site’s elevation).
Each powered separation in a .ork comes out as a
Staging, from the tail forward
(MotorConfiguration::stagings). A powered separation’s time is known before the flight. At that
time a motor ahead of it is still burning or yet to light. None behind it is, but at a stage’s
first burnout its own other motors may still burn, and they drop burning. A separation may have
nothing ahead of it left to burn, as when the sustainer has burnt out by the split. Such a
separation is read only when it’s the configuration’s only one. The other separations that could come before apogee
are refused. The configuration’s rocket doesn’t carry the Staging. These functions in hpr carry it,
and the recovery settings, into the flight:
hpr::ork::separationturns one into the flight’s separation, andhpr::ork::separationsa configuration’s list. You pass the list to the flight yourself, with a recovery device on each part, since the simulator refuses the flight without them (example).hpr::ork::recoveryturns a configuration’s parachutes and streamers into the flight’s recovery devices, as OpenRocket flies them (Recovery).hpr::ork::separated_recoveryputs each on its part when the configuration separates, ashpr simflies it.
Online data
hpr_net’s cache, offline mode and HTTP work today; HTTPS is checked by hand but not in CI
(Online data and the cache). It has five sources:
- Open-Meteo’s weather (Launch-day weather).
- Weather-balloon soundings (Weather-balloon soundings).
- NOAA’s GFS and RAP forecasts (NOAA forecasts: GFS and RAP).
- Open-Meteo’s ground elevation (A launch site’s elevation).
- motor.fusionspace.co’s motor stock and prices (Motor stock and prices).
Analysis
hpr_analysis holds:
- Monte Carlo dispersion (flying many copies of a flight with randomly scattered inputs), the spread of its results, and landing ellipses (Monte Carlo dispersion).
- Sensitivity analysis, Morris screening and Sobol’ indices (Sensitivity analysis).
- Optimization (Optimization). CMA-ES searches over numbers and choices such as a motor, within limits such as a minimum margin. NSGA-II takes two goals at once. EGO (efficient global optimization) is for models too slow for more than tens of evaluations. On a rocket, each gives answers only as good as the simulator’s flight models.
- Planned: competition rule files.
Using it from your own program
Release 0.1.0 is on crates.io, Rust’s public package registry. cargo add fusionspace-hpr adds
the front door, which your code calls hpr and which re-exports the crates under it. Its features
net, parquet and parallel add the online data sources, Parquet export and Monte Carlo on
worker threads (Install a release). Until 1.0, a
new minor version, such as 0.2, may change the API.
To follow main instead of a release, a program outside this repository can depend on a crate
straight from GitHub. Pin it to a commit, since anything can change between commits. Take its hash from
the history of main, and change it only on
purpose:
[dependencies]
fusionspace-hpr = { git = "https://github.com/nrdptel/fusionspace-eridanus", rev = "<commit>" }
Cargo finds the crate in the repository by its package name, fusionspace-hpr; your code still
says use hpr::….
Reading it
- Names. Code names a crate with underscores (
use hpr_sim::Simulation;), andCargo.tomlandcargo -pname its package with hyphens and thefusionspace-prefix (fusionspace-hpr-sim). They’re the same crate. - Search. The search box at the top of every reference page, or the S key, finds a type or function in any crate.
- Source. Each item’s Source link shows the code it documents.
- Links to the guide on the crates’ front pages go to the published site,
https://hpr.fusionspace.co/; the same pages are in the repository’s
docs/folder.