The API reference
The API reference documents hpr-sim’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
hpr-sim, as Getting started does. This page says which crate holds what, and
links each crate’s reference. The library is pre-alpha: none of its interface is stable yet, any of
it can change, and 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 reference is built from the same source that CI, the project’s automated checks, compiles on every change, so it describes the code as it is. Every link in it is checked in CI, apart from a few inside the vector types’ documentation, which rustdoc copies from glam, the vector library hpr-sim uses. Physics items give their equation and cite their source, as the model pages here do. Each crate’s front page links back to the pages here that explain its models.
The crates
hpr-sim is split into crates, Rust’s packages, so that a program takes only what it needs, and so that the models, which don’t read or write files or use the network, also build for the web. Eleven crates hold most of the code today:
| crate | what it holds | not yet | the guide’s pages |
|---|---|---|---|
hpr | One crate to depend on: the builder for environments, motors, rockets and flights, its parts made from catalog parts too (parts from a catalog), the other crates re-exported by name, hpr::ork::separation, which turns a .ork file’s staging into a flight’s separation (example), a drag model of your own in hpr’s place, and a guide in the reference, hpr::guide | 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 the 32 bundled curves | 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 | hpr’s own 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 | Generated TypeScript and Python types (M3.3c) | 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 a flight takes a pointed nose, its cylinder and a boattail behind them from the shock-expansion method, the boattail’s share unvalidated; 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, 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 | Aerodynamics |
hpr_sim | The flight: the launch rail, the equations of motion, time integration, events and recovery | Staging and air starts fly, checked by tests and against OpenRocket’s two-stage, cluster and air-start examples, each flight within 5% in apogee and largest speed (M1.9c, 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. A cluster flies, one mount of several tubes or one mount per motor, and so does a motor out, checked by tests against a hand calculation. A nose cone, a section or a payload can leave the airframe, optionally pushed by its charge, and land on its own under its own parachute or tumbling (ejection, M1.11a, M1.11b), checked against exact answers only. | 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: PerfectFlite’s .pf2 so far, and liftoff, apogee, the top speed, landing and the descent, each saying where it came from or why it was withheld. Depend on this crate directly rather than on hpr, which pulls in the simulator | Other loggers’ files (M7.1); the descent’s legs, Mach number and the rest of the readings (M7.2) | Reading a flight log, Flight-log readings, .pf2 files |
hpr_validate | The validation harness: cases, reference data, metrics and reports | Whole flights against RocketPy (M2.1b2) | Accuracy, Checking a claim |
hpr_py | The hpr Python package: the builder’s environment, motor, rocket and flight from Python, designs read from files, and a flight’s recording as NumPy arrays. Built by maturin into one wheel per operating system; not on PyPI | A drag table and RocketPy’s example flight (M4.3b); a drag and a wind written in Python (M4.3c) | Python |
The other six crates are for planned work. Each has a front page that says what it will hold.
One already holds some code, hpr_io, as its row says:
| crate | what it will hold | planned in |
|---|---|---|
hpr_io | Import and export of OpenRocket, RockSim and RASAero designs, export to RocketPy, and OpenRocket’s parts catalog: its 16 .orc files are bundled, every part found by maker and part number (the format page). A .ork file’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. Each powered separation comes out as a Staging, from the tail forward (MotorConfiguration::stagings): its time is known before the flight, and then a motor ahead of it is still burning or yet to light and none behind it is. Any other separation that could come before apogee is refused, a sustainer already burnt out at the split included. The configuration’s rocket doesn’t carry the Staging: hpr::ork::separation turns one into the flight’s separation, and hpr::ork::separations a configuration’s list, which you pass to the flight yourself, with a recovery device on each part, since hpr refuses the flight without them (example); hpr::ork::recovery turns a configuration’s parachutes and streamers into the flight’s recovery devices, as OpenRocket flies them (Recovery), and hpr::ork::separated_recovery puts each on its part when the configuration separates, as hpr sim flies it. A design is written back out as a .ork with hpr_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), and a GeoTIFF elevation file a site’s height (A launch site’s elevation) | M3.1a, M3.2a, M2.3a and M5.5a done; M3.1b to M3.6 next |
hpr_net | Optional online data, cached for offline use: weather, soundings, elevation and motor data. The cache, the offline mode and HTTP work today, HTTPS checked by hand but not in CI (Online data and the cache); 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) and motor.fusionspace.co’s motor stock and prices (Motor stock and prices) | M5.1 done; M5.2a, M5.2b and M5.2c done; M5.2d1, the command line’s hpr weather, done; M5.2d2 and M5.2d3 done; M5.3b, elevation, done; M5.4a, motor stock, done |
hpr_analysis | 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 over numbers and choices such as a motor, within limits such as a minimum margin; NSGA-II for two goals at once; EGO (efficient global optimization) for models too slow for more than tens of evaluations; on a rocket, answers only as good as hpr’s flight models; planned: competition rule files (M6.3) | M6.1 done; M6.2 done but for EGO on six variables (M6.2d2) and robust designs (M6.2e); M6.3 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 | M7.3 to M7.4 |
hpr_ffi | A C interface, for other languages | M4.4 |
hpr_wasm | WebAssembly bindings, for the browser | M4.4 |
The command-line tool, 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.
Using it from your own program
Release 0.1.0 is built and checked, but not on crates.io, Rust’s public package registry, yet.
Once it is, cargo add hpr adds the front door, hpr, 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.
Until then, a program outside this repository can depend on a crate straight from GitHub, pinned
to a commit, since anything can change between commits. Take the commit’s hash from
the history of main, and change it only on
purpose:
[dependencies]
hpr-sim = { git = "https://github.com/nrdptel/hpr-sim", rev = "<commit>" }
Reading it
- Names. Code names a crate with underscores (
use hpr_sim::Simulation;), andCargo.tomlnames its package with hyphens (hpr-sim). They are 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://nrdptel.github.io/hpr-sim/. Until it is live, read the same pages in the repository’s
docs/folder.