Repository navigation
Write the v1.0 book, and fix what writing it uncovered (#383) - #419
Merged
Merged
Conversation
Removes the six loose design and setup notes in book/ (RBPF.md, EKF_USAGE.md, EKF_GEONAV.md, PROJECT_SUMMARY.md, QUICK_REFERENCE.md, GITHUB_PAGES_SETUP.md). Each described APIs or binaries that no longer exist; the reusable parts are merged into src/ pages later in this branch. Also removes the one-line placeholder pages that the new outline folds together: the eight api/ stubs become one page pointing at rustdoc, the three GNSS scenario stubs become one reference page, and the three geonav stubs become one. open-loop.md is retired because dead reckoning is dr, and ol is unimplemented. The new SUMMARY lists only pages that the rest of this branch fills. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
GnssFaultModel is internally tagged (#[serde(tag = "kind")]), and serde cannot put a
tag on a newtype holding a sequence. So Combo(Vec<Self>) could be built in code
but never deserialized: kind = "combo" in TOML or YAML failed with "invalid type:
map, expected a sequence", while configuration.md advertised it as a fault kind.
The CLI's --fault offers no combo either, so the variant was unreachable outside
Rust.
It is now the struct variant Combo { faults: Vec<GnssFaultModel> }, written
kind = "combo" with the members under faults. Its documentation states that
members share one FaultState and should be of different kinds.
apply_fault's doc no longer says composition still needs wiring up. It has been
wired since the fault interval moved out of apply_fault.
The old test ran None twice, which would pass even if combo applied nothing. It
is replaced by a test that two hijacks on different axes both land, and by a
TOML/YAML round-trip test.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…CLI help The crate-level rustdoc got three of Groves' signs wrong. The attitude update showed -(Omega_ie - Omega_en) for -(Omega_ie + Omega_en) (eq. 5.46). The velocity update showed -(Omega_en - Omega_ie) v for -(Omega_en + 2 Omega_ie) v (eq. 5.54). The height update added the down velocity instead of subtracting it (eq. 5.56). The code is right and tested (velocity_update_coriolis_term_is_a_bare_cross_product); only the documentation was wrong. The docs also called the IMU data pre-filtered four paragraphs before saying it must not be, gave positions in degrees where StrapdownState holds radians, and listed nine of the sixteen modules. strapdown-sim --help described three modes, called dead reckoning open loop, said closed loop ran the UKF or EKF, and marked the particle filter 'CURRENTLY IN DEVELOPMENT'. ol's help described a working Kalman mode it does not have. These now describe dr, cl (ESKF by default), pf, syn and config, and say plainly that ol writes nothing. ParticleFilterType's doc described per-particle Kalman filters with IMU biases, which the Canciani & Raquet restructure removed. cargo doc --workspace --all-features now passes with -D warnings. The 21 public docs that linked to private items now name them in plain code spans, and four redundant explicit link targets are dropped. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… with it deploy-book.yml ran only on pushes to main, so a page that failed to build, or a link into a deleted page, was first seen on the live site. It now builds on every pull request that touches the book or a crate, and deploys only from main. The build also runs cargo doc for the whole workspace with -D warnings and publishes the output under /api/. The book can then link to the documentation of the commit it was built from; docs.rs has none for 1.0.0 until the release. An offline lychee pass checks every link between pages and into the API docs. Smaller fixes in the same area: - The workspace homepage pointed at www.strapdown.rs, a domain that was never configured. It now points at the GitHub Pages book, and book.toml sets the matching site-url. - examples/magnetometer-config.{yaml,json} described a magnetometer block that matches no struct, and nothing referenced them. - examples/configs/README.md linked a docs/USER_GUIDE.md that does not exist. - CLAUDE.md listed pseudorange and carrier-phase models that were never implemented, linked a LOGGING.md that is gone, and counted 21 conf recipes where there are 15. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
36 of the 54 pages were one-line placeholders, and four filled pages described APIs that do not exist. filters/particle-filter.md was a pre-implementation design for types never written; ekf.md called ExtendedKalmanFilter::new with the wrong arguments; data-format.md imported a load_test_data that never existed; faq.md documented config keys that were never read. Every page in the pruned outline is now written against the code: - Getting started: installation from git until v1.0.0 reaches crates.io, with per-feature build requirements, and a quick start run end to end on a syn trajectory. - User guide: the navigation model (Groves eqs. 5.46, 5.47, 5.54 and 5.56, written from the code), frames, state layouts, a reference page per subcommand, the input and output schemas, every configuration section, and library use through InsEngine. - Filters: the NavigationFilter trait, ESKF, EKF, UKF and RBPF, the particle building blocks, every measurement model, and gating. - GNSS degradation, experimental geonav, an API page pointing at the rustdoc that the deploy now publishes, architecture, analysis tooling, FAQ, publications and glossary. Rust in the book is pulled from compiled examples by anchor, so a signature change breaks cargo build --examples rather than silently staling a page. Five new examples back the filter and library pages (kalman_filters, eskf, aiding, lever_arm, score_run), and basic_ins/gnss_outage gain anchors. Every CLI command shown was run. Accuracy figures come only from the generated baseline tables. theme/head.hbs enables inline $...$ math. mdBook 0.4's MathJax 2 renders only $$ and \( \) by default, so the inline math would have shown as raw dollar signs. Spacing commands markdown would strip (\,) are written as \ instead. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
NavigationResult::to_netcdf and TestDataRecord::to_netcdf stored each row's time as timestamp(), whole Unix seconds, and the readers rebuilt it with from_timestamp(t, 0). Every row of a 10 Hz run within one second came back with the same time, so a netCDF file could no longer order or align its own rows. Both writers now store the time as fractional Unix seconds built from whole microseconds, and both readers round back to the nearest microsecond. An f64 holds about 15.9 significant digits and a present-day Unix time in microseconds needs 16, so microseconds are the finest resolution that survives; rounding rather than truncating keeps the round trip exact. A non-finite stored time is now an error rather than a cast to zero. HDF5 (RFC 3339 strings) and MCAP (serde) already kept the fraction. New tests hold all three formats to an exact round trip of sub-second timestamps, and the old netCDF test's note about whole seconds is gone. The output-format page described the truncation and recommended HDF5 or MCAP around it; it now describes the fix. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- ClosedLoopConfig::innovation_gate showed the YAML form
`innovation_gate: { chi_squared: { confidence: 0.999 } }`. InnovationGate is
externally tagged, and serde_yaml 0.9 reads that as a tag, `!chi_squared`; the map
form fails to parse. The doc now gives the TOML and YAML spellings, and a doctest
parses both and checks the map form is refused.
- ClosedLoopConfig::filter called the default "the 15-state ESKF", but
estimate_baro_bias is on by default, so the ESKF strapdown-sim runs carries sixteen
error states. estimate_baro_bias said it was not available on the geophysical path;
that path carries it for the UKF and EKF, after the map biases.
- The crate docs said the health checks bound altitude to [-11,000 m, 30,000 m]. That
is the range the mechanization is valid over; the default health band is +/-1e8 m
and enforces nothing like it. Both are now stated, in lib.rs and CLAUDE.md.
- principal_radii swapped the names: r_n is the meridian radius (Groves' R_N) and r_e
the transverse radius (R_E). The formulas were right.
- gravity said it excluded centrifugal effects. Somigliana normal gravity is the
magnitude of gravitation plus centrifugal acceleration, so it includes them.
gravitation's doc, which leaned on the old claim, now says it adds the centrifugal
term on top and so counts it twice; nothing in the mechanization calls it.
- The ESKF doc labelled the position error (m); inject_error_state adds it to
latitude and longitude in radians and altitude in metres.
- perf_baseline.rs said run_closed_loop labels rows one step early. #367 fixed that,
as the file's own module docs say. The comments now give the history and why the
50 Hz rate stays. No baseline value changes.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each of these was accepted and then ignored, or failed in a way that hid it: - `config` with stdin at end of file looped forever on "Configuration path cannot be empty": read_user_input read `read_line`'s Ok(0) as an empty answer, and every prompt without a default re-asks. End of input (and a read error) now ends the wizard with a message on stderr and status 1. - `pf --horizontal-process-noise-std-m 0.5,0.5`, the form its help text shows, failed with "2 values required but 1 was provided": clap counts arguments before splitting on the delimiter. `num_args = 1..=2` takes `0.5,0.5` and `0.5 0.5`; the existing length check still refuses one value. - A config file's `[closed_loop]` gate was never range-checked. Deserialization bypasses InnovationGate::chi_squared and GateRecovery::new, so confidence = 1.5 or rejection_inflation = 0.5 ran with exit 0 where the same flags were refused. Both paths now go through one validator, validated_gating, and a config run refuses a bad gate before reading any input. forced_update_after = 0 still means "never force", as --gate-force-after 0 does, since TOML has no null. - --plot and --parallel are global flags but only run_from_config read them. dr, cl (with and without --geo) and pf now honour both, through one batch runner shared with the config path; dr results are plotted too, on both paths. syn, config and ol refuse them, and --plot is refused by a build without the plotting feature. - A cl batch logged a filter failure and exited 0, and dr/pf did the same for files with no usable records while aborting the batch on a filter failure. Every subcommand now runs the rest of the batch and exits non-zero naming how many files failed, as the config path did. - dr accepted the execution and health limit flags and applied none. It now runs the new strapdown::sim::dead_reckoning_with_limits, which checks the wall-clock budgets and the latitude/longitude/altitude/speed bounds after every step; dead_reckoning itself is unchanged and stays unbounded. Dead reckoning has no covariance and no measurement update, and pf computes no NIS, so each limit flag's help now says which modes apply it rather than inventing a value. - `syn -o x.parquet` wrote CSV under a Parquet name, and `dr/cl/pf -o out.h5` made a directory called out.h5 full of CSV. An output path whose extension names another data format (h5, hdf5, nc, netcdf, mcap, parquet, json, yaml, yml, toml, txt) is now refused with a pointer at the library writers, unless it is an existing directory; `syn` requires a .csv file. Extension-less paths are still directories. - The `Using aiding config` log line was printed before baro_bias_index was derived, so every cl log reported None. It is logged after the derivation. - CreateConfigArgs was dead code. The wizard offered Open-Loop, which is not implemented; it now offers Synthetic instead, which needs only an output file and a seed to produce a runnable config. - --no-estimate-baro-bias's help began "Estimate a barometric altitude bias", the opposite of the flag. The cl help, --filter help and top-level help called the default filter the 15-state ESKF; with the barometric bias on by default it carries sixteen error states, and now says so. The bare URL in the module docs is wrapped so rustdoc accepts it. The user guide described several of these as current behaviour (the parquet directory, inert dr limits, plot/parallel config-only, unchecked file gates, the comma form failing, the wizard's Open-Loop); those pages, the FAQ, the installation page and CLAUDE.md now describe the fixed behaviour. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The geophysical measurement models return NaN from get_expected_measurement for a
point off the loaded map, because that method is infallible by signature. The UKF
maps every sigma point through it, so one off-map sigma point made z_hat, the
innovation covariance and the gain NaN, the update wrote NaN into the state, and
the run stopped with NonFinite { what: "filter state" } -- even while the estimate
itself was still on the map. The EKF and the particle filter meet the same edge as a
recoverable OutOfMapBounds and skip the fix with a warning.
UnscentedKalmanFilter::update now checks the predicted sigma-point measurements
before anything else and, if any is non-finite, returns the recoverable
MeasurementUnavailable with the state and covariance untouched. The runners already
skip recoverable errors with the same "Measurement rejected" warning they log for
the EKF, and still fail a run after 100 in a row. A test drives a model that cannot
predict north of the mean's latitude and checks the update is refused unchanged,
and that a model every sigma point can predict still updates.
The geonav pages documented the abort as a known limitation; they now describe the
skip.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A scenario file's top-level `seed` reached only the particle filter. The fault models were seeded by `[aiding] seed`, which defaulted to 42 on its own, so two closed-loop files differing only in `seed` gave byte-identical output, while on the command line `--seed` seeds both. AidingConfig::seed is now Option<u64>. None means "the run's seed": SimulationConfig::resolved_aiding fills it from the top-level seed, and strapdown-sim's config path builds every event stream from that, so the top-level seed alone seeds the whole run, as --seed does. An explicit `[aiding] seed` still wins, which keeps the documented Monte Carlo split -- vary the particle filter's seed with the faults held fixed, or the reverse -- available. Anything that builds an event stream from a None takes DEFAULT_AIDING_SEED, 42, so defaults and every shipped config (which set both seeds to 42) give the same output as before. The wizard leaves `[aiding] seed` unset, so editing one key changes the run. This is a breaking change to a pub field; call sites that set the seed now write Some(seed). Tests hold the resolution order and that two top-level seeds give two fault realizations. The configuration, scenario and architecture pages described the old behaviour and now describe this one. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
duty_cycle_is_on runs start_phase_s of initial availability, then off_s denied and
on_s available, repeating. With start_phase_s = 0 there is no initial window, so the
run opens with an outage. Several descriptions said the opposite:
- the MeasurementScheduler example ("starting in ON state at t=0") and the
DutyCycle field docs ("offset before the first toggle"), which now give the
timeline and an example with a start phase;
- the real_outage_60s and syn_outage_60s scenario descriptions in perf_baseline.rs
("120 s of GNSS then a 60 s outage"), and the same strings in perf_baseline.json,
which only render_baseline writes and compare() does not read. No metric, sample
count or tolerance in the baseline changes;
- the ukf_conditioning.rs bound's derivation ("60 s of GNSS then 60 s");
- examples/configs/simple_dropout.yaml and extended_gnss_denied.yaml, whose
start_phase_s: 0.0 now says it opens the run with the outage and what value would
open it with GNSS instead.
The user guide, quick start, FAQ and performance page already described it
correctly. No behaviour changes.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
convert_resolution_gravity and convert_resolution_magnetic ended in a catch-all, so a gravity resolution finer than one arc-minute was recorded as one-minute and a magnetic one finer than two arc-minutes as two-minutes, without a word. A run labelled thirty-second gravity aiding was one-minute aiding. Both now refuse a finer label with an error naming the supported resolutions, and check_map_resolutions runs them before any file is read: in GeoClosedLoopSettings::validate (cl --geo and a closed-loop config), at the start of pf, and in run_from_config for a particle-filter config. A test covers both conversions and both closed-loop entry points. conf/rbpf_mag.toml, conf/real/rbpf_mag.toml and examples/configs/geonav_example.toml asked for one-minute magnetic maps, which these runs already recorded as two-minutes; they now say two_minutes, so they keep running with no change in behaviour. The geonav overview said finer labels were recorded as the coarser ones; it now says they are refused. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- geonav::build_event_stream's doc listed positional gravity_map, gravity_noise_std, magnetic_map, magnetic_noise_std, geo_interval_s and bias_layout arguments. The function takes is_enu and one &GeophysicalAiding; the doc now lists those. - README.md's library example called build_event_stream with that old seven-argument signature and ran an undefined `ukf`. It now builds a gravity-aided stream against the real API -- checked by compiling it as a test -- and points at run_closed_loop_with_geo and the CLI's runner for the bias-state wiring. - The README's CLI examples used --dropout-start-s/--dropout-duration-s, which do not exist, and two of them omitted --filter, so they ran the default ESKF, which has no geophysical arm and refuses. They now use --sched fixed and pass --filter. The interval flag is --geo-interval-s; --geo-frequency-s is its alias. - CombinedGeophysicalMeasurement claimed a joint update "enables cross-correlation between the two modalities" and is more efficient than sequential updates. Its R is diagonal, so a linearized joint update equals two sequential ones; the doc now says that, and where correlation does enter (H P H^T). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Twenty-four conf/ recipes justified the 35 m degraded profile as "about 14x this dataset's 2.58 m median advertised accuracy". The median depends on which recordings data/input holds and does not reproduce on the current data (2.46-3.06 m across trajectories), so the comment went stale the moment the data changed. It now says the wander is roughly an order of magnitude above a phone GNSS fix's few-metre accuracy, which is the claim the profile actually rests on. Comments only; no key or value changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
CONTRIBUTING.md's "Before you open a pull request" block gave fmt-check, lint and the workspace tests. CI also gates on the --no-default-features configuration of strapdown-core, which those cannot see: an item used only behind a feature gate is dead without it. The block now lists cargo lint-min and cargo test-min and says why. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
GateRecovery::forced_update_after was documented as "the number of consecutive rejections after which the next measurement is applied". GatePolicy::decide counts the measurement it is deciding: the N-th consecutive failure is itself forced through. With the default 5 that is four rejections and a forced fifth, which is what core/examples/aiding.rs prints (t = 61-64 rejected, t = 65 forced). The field, the struct's recovery list, DEFAULT_FORCED_UPDATE_AFTER, UpdateOutcome::forced, MIN_FORCED_UPDATE_AFTER and the module summary now say so, as do --gate-force-after's help, the aiding example's header and the tutorial, closed-loop and configuration pages; filters/measurements.md already had it right. The warning logged on a forced update said "after N consecutive rejections" and now says N in a row have failed. Behaviour is unchanged, so no baseline moves. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
matrix_square_root returns StrapdownError::NotSquare for a non-square matrix and then asserted the same condition. The assert could never fire, contradicted the function's "Does not panic" section, and was the zero-panic policy's one surviving assert! in library code. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- EkfConfig::imu_quality said the value was inert on the EKF because its Jacobian had no nav-bias block (#394). The EKF predict now widens F with widen_with_imu_bias_coupling, so the bias prior matters; the doc says so. - InsEngineConfig::initial_covariance_diagonal said None uses initialize_eskf's defaults. Position, velocity and attitude match, but the engine's DEFAULT_INITIAL_COVARIANCE keeps fixed 1e-6/1e-8 bias variances where initialize_eskf derives them from imu_quality. Both docs now say that; the values are unchanged, since moving them would move the examples' output. - IMUQuality::velocity_process_noise said the filters propagate with "no internal dt scaling". Since #374 every filter takes a density and forms Q = q dt, so the doc now warns that passing this per-step variance to a filter would apply dt twice, and gives the density. - Four kalman.rs doctests built filters with P0 = 1e-6 on every state and Q = 1e-9, the #308 units trap: 1e-6 rad^2 is a 6 km horizontal sigma. They now use per-state units, the IMU grade's bias prior and DEFAULT_PROCESS_NOISE_DENSITY, and still pass. - linearize.rs said altitude is positive down in NED; it is height above the ellipsoid, positive up in both frames. body_rotation_vector_to_euler_jacobian said callers fall back to differencing at gimbal lock; its one caller, the ESKF update, zeroes the attitude columns instead, for the reason its own comment gives. - RbpfConfig::horizontal_process_noise_std_m and the five conf/rbpf_*.toml comments said 1 m/sqrt(s) held the reference recording to 3.8 m. That was the first measurement, before later particle-filter fixes; the current accuracy baseline (real_rbpf_slice__rbpf) is 3.235 m, which book/src/filters/rbpf.md already gives. Comments only in conf/. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
tutorial-basic.md showed basic_ins ending 0.00 m from truth with 3.01/2.32/1.08 m position sigmas; the example now prints 0.10 m and 0.80/0.78/1.04 m. The page read the 3 m as the filter being unable to beat its aiding source. That no longer holds: having fused a fix and a velocity fix every second, the filter reports less than any one fix advertises, which is what averaging repeated fixes should do. The prose now says so, and notes that the page used to show otherwise. tutorial-gps-degradation.md showed a 49.4 m peak, a 0.2987 deg pitch error and a 0.0511 m/s^2 gravity leak; gnss_outage now prints 54.0 m, 0.2879 deg and 0.0493 m/s^2, and its table rows moved with them (0.2 m before the outage, 0.1 m after recovery). The explanation -- the filter absorbs the accelerometer bias into pitch, and the tilt's gravity leak nearly cancels it -- still holds and is kept, with the ratio to the 360 m textbook figure updated to "nearly seven". Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
core/README.md called cl's default filter "the 15-state ESKF". With the barometric bias estimated by default it carries sixteen error states unless --no-estimate-baro-bias is given, as the CLI help now says. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… and nav-types with it gravitation added the Earth's centrifugal acceleration to gravity(), which is Somigliana normal gravity and already includes it. The vertical component was therefore about 0.034 m/s^2 too large at the equator, and the unit test pinned the wrong value (GE + 0.0339). The doc also called the result ENU with gravity along -Z, while the function returned +g on Z. Nothing called it: the mechanization uses gravity() along the vertical, which is the correct normal-gravity vector, so there is nothing to repair it into. It was also the only code in the workspace that used nav-types, so that dependency and its transitive crates go too. The JOSS paper said the mechanization was 'built on nav-types', which this makes plainly untrue; the claim and its bibliography entry are removed in the same commit so the paper never disagrees with the code it ships with. The crate and module docs that credited nav-types with the coordinate conversions are corrected as well. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nd re-bless strapdown-sim syn modelled two sensors with no independent noise. - relativeAltitude was the noisy GNSS altitude minus its first value. The barometer shared the GNSS's noise draw, so on synthetic data it could aid nothing. - --baro-noise-std-pa reached only the pressure column, which no estimator reads, and pressure was written in pascals while TestDataRecord documents millibars. - speed and bearing were noise-free while speedAccuracy claimed the 2.5 m horizontal position noise, so velocity fixes were perfect but weighted as 2.5 m/s. Now: - relativeAltitude comes from the noisy pressure through the same isothermal atmosphere that expected_barometric_pressure uses, referenced to the first noisy reading as a phone's is. Its first-sample error is the constant barometric bias the filters estimate. - The default pressure noise is the sea-level equivalent of the 2.24 m the filters assume (BAROMETRIC_ALTITUDE_NOISE_M), about 27 Pa, not an unsourced 50 Pa (4.2 m). - pressure is written in hPa. - New --gnss-velocity-noise-mps (default 0.5) perturbs north/east velocity on its own RNG stream, so the IMU, GNSS position and barometer realizations are unchanged. It is written as speedAccuracy, with bearingAccuracy the angle that error subtends at the current speed. earth::barometric_altitude, needed for the inverse, mixed the lapse-rate and isothermal models and returned about -152 km for the pressure of 100 m. Its test only checked for a finite result, under a comment saying the formula looked wrong. It is now the exact inverse of expected_barometric_pressure, and the test round-trips it. Re-blessed. Only the six syn_* scenarios move; every real-data row is identical. Horizontal RMSE in syn_cruise_1hz falls from 2.60 m to 1.72 m, because velocity fixes now carry an honest 0.5 m/s. Vertical RMSE falls from 2.28 m to 1.52 m, because the barometer is now an independent aid. ESKF attitude error rises from 0.42 to 0.65 deg geodesic, because real velocity noise now reaches tilt. syn_dead_reckoning moves because dr takes its initial velocity from the first record's speed and bearing. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…t what went stale
The book was written before cd635d2 (independent synthetic barometer and GNSS velocity)
and the CLI fixes in 35ab5d4 and its neighbours landed. Every CLI command, config file
and cargo example in SUMMARY.md's pages was rerun on a fresh syn trajectory; these are
the pages whose output or statements no longer held.
Synthetic generator (cd635d2):
- synthetic.md, data-format.md, quick-start.md: relativeAltitude is now the height of a
noisy pressure, independent of the GNSS altitude and offset by its first reading;
pressure is hPa, not Pa; speed/bearing carry --gnss-velocity-noise-mps (new flag,
default 0.5) and speedAccuracy/bearingAccuracy describe it; the barometric default is
about 26.86 Pa, not 50. The [synthetic] example gains gnss_velocity_noise_mps.
- Every printed number that depends on a syn trajectory moved: quick-start's last ESKF
row and score table, the PF tutorial's score tables, the health-limit speed in
simulations.md (49.798 m/s, from the first record's noisy speed), the gated-event
count in closed-loop.md (7, was 78), and the kalman_filters and eskf example outputs
in kalman.md and eskf.md.
- particle-filter.md and the PF tutorial said zero horizontal process noise diverges on
the synthetic runs. It now finishes on both; the tutorial shows its score (NEES 9.8,
containment 0.93: over-confident) and both pages point at the recorded-data divergence
the library documents instead.
CLI fixes (35ab5d4 and others):
- dr now applies the health limits, so `dr` on the 600 s syn trajectory stops at the
500 m/s speed bound. quick-start, dead-reckoning, data-format and the PF tutorial pass
--health-speed-mps-max 1000 and say why; the blank-acc_x error is now
NonFinite { what: "filter state" }. architecture.md names dead_reckoning_with_limits,
and configuration.md no longer says config-file dr ignores the limits.
- --parallel works on subcommands (faq.md said it needed --config); generate_plot also
plots dr results; a bad --gate-confidence now reports through the gate validator.
- The single-file ENU refusal no longer logs an [ERROR] line first (coordinate-frames).
- AidingConfig.seed is Option<u64> (scenarios.md's table said 42).
- Synthetic mode reads [logging] as well as [synthetic].
Other corrections found on the way: output-format.md said mcap is Rust-only (it builds
bundled LZ4 and Zstandard C code); the FAQ's toolchain list omitted the C compiler that
plotting and mcap need; closed-loop.md said the duty run had two outages (it has four);
geonav overview said unused map-bias columns are NaN (they are empty); ukf.md described
the conditioning test's duty cycle as starting on; combo_duty_hijack.yaml opens with its
outage; the RUST_LOG example now shows only the first line, since that dr run now exits
1. quick-start's score.py is reformatted the way `ruff format --check` (CI's
python.yml, which also formats Markdown code blocks) requires.
baseline-tables.md is untouched; prose that quotes accuracy agrees with it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Earlier on this branch, dr began applying every health limit the filters are held to. A plain strapdown-sim dr on a ten-minute syn trajectory then stopped at the default 500 m/s speed bound, exited 1 and wrote nothing. The book had to pass --health-speed-mps-max 1000 everywhere dr appeared, and the README's quick start would have failed for anyone who ran it. The health bounds exist to stop a diverged filter from burning the rest of its budget. An unaided MEMS arc is expected to leave them, and the arc is the result. dr now passes only the execution limits. A non-finite state still stops it, and dead_reckoning_with_limits still takes health limits for library callers who want them. The flags' help, the config docs and the book no longer claim dr applies them, and the speed-limit workarounds are gone. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The first run of the new link check passed 4,180 links and failed on one: the <base href="/strapdown-rs/"> that mdBook writes into 404.html from site-url. That link is root-relative, which lychee cannot resolve against local files without a root directory. It is generated, correct on the deployed site, and not a link any page author wrote. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
The documentation workflow fails on its generated 404 page, and the glossary misstates the repository’s nonstandard ENU axis convention.
Review effort: Balanced
Findings: 1
Open (2)
What changed in this PR
Overhauls the v1.0 user book and fixes implementation defects uncovered while validating its examples and documentation.
Changes:
- Replaces placeholder documentation with verified user, filter, geophysical-navigation, and development guides.
- Corrects CLI, configuration, synthetic-data, filtering, and serialization behavior with tests.
- Adds compiled examples, documentation CI, and refreshed performance baselines.
| File | Description |
|---|---|
.github/workflows/deploy-book.yml |
Builds and checks book and rustdoc. |
CLAUDE.md |
Updates repository behavior guidance. |
CONTRIBUTING.md |
Updates documentation workflow. |
Cargo.lock |
Removes obsolete dependency resolution. |
Cargo.toml |
Updates workspace dependencies/configuration. |
book/EKF_GEONAV.md |
Removes stale design note. |
book/EKF_USAGE.md |
Removes stale design note. |
book/GITHUB_PAGES_SETUP.md |
Removes obsolete deployment note. |
book/PROJECT_SUMMARY.md |
Removes stale project summary. |
book/QUICK_REFERENCE.md |
Removes stale reference. |
book/RBPF.md |
Removes stale design note. |
book/book.toml |
Configures generated book output. |
book/src/SUMMARY.md |
Defines the completed book structure. |
book/src/api/core.md |
Removes redundant API stub. |
book/src/api/earth.md |
Removes redundant API stub. |
book/src/api/geonav.md |
Removes redundant API stub. |
book/src/api/index.md |
Directs readers to rustdoc. |
book/src/api/kalman.md |
Removes redundant API stub. |
book/src/api/measurements.md |
Removes redundant API stub. |
book/src/api/particles.md |
Removes redundant API stub. |
book/src/api/sim-binary.md |
Removes redundant API stub. |
book/src/api/sim.md |
Removes redundant API stub. |
book/src/chapter_1.md |
Removes orphan placeholder. |
book/src/development/analysis.md |
Documents analysis tooling. |
book/src/development/architecture.md |
Documents system architecture. |
book/src/development/baseline-tables.md |
Adds generated baseline tables. |
book/src/development/building.md |
Updates build instructions. |
book/src/development/contributing.md |
Documents contribution workflow. |
book/src/development/performance.md |
Updates performance-gate guidance. |
book/src/development/structure.md |
Documents repository structure. |
book/src/examples/configurations.md |
Documents scenario configurations. |
book/src/examples/tutorial-basic.md |
Adds basic tutorial. |
book/src/examples/tutorial-gps-degradation.md |
Adds degradation tutorial. |
book/src/examples/tutorial-particle-filter.md |
Removes obsolete placeholder. |
book/src/faq.md |
Expands troubleshooting guidance. |
book/src/filters/comparison.md |
Compares supported filters. |
book/src/filters/ekf.md |
Updates EKF documentation. |
book/src/filters/eskf.md |
Documents ESKF operation. |
book/src/filters/kalman.md |
Introduces Kalman filtering. |
book/src/filters/measurements.md |
Documents measurement models. |
book/src/filters/particle-filter.md |
Updates particle-filter guidance. |
book/src/filters/rbpf.md |
Documents RBPF design. |
book/src/filters/ukf.md |
Documents UKF design. |
book/src/geonav/data-sources.md |
Documents map sources. |
book/src/geonav/gravity.md |
Documents gravity aiding. |
book/src/geonav/magnetic.md |
Documents magnetic aiding. |
book/src/geonav/maps.md |
Documents map handling. |
book/src/geonav/overview.md |
Introduces geophysical navigation. |
book/src/gnss/corruption.md |
Documents GNSS corruption models. |
book/src/gnss/dropouts.md |
Documents GNSS outages. |
book/src/gnss/fault-simulation.md |
Documents fault simulation. |
book/src/gnss/reduced-rates.md |
Documents reduced update rates. |
book/src/gnss/scenarios.md |
Documents scenario composition. |
book/src/installation/building.md |
Documents source builds. |
book/src/installation/crates-io.md |
Clarifies package availability. |
book/src/installation/installation.md |
Adds installation overview. |
book/src/installation/requirements.md |
Documents prerequisites. |
book/src/introduction.md |
Updates project introduction. |
book/src/quick-start.md |
Adds verified quick start. |
book/src/resources/glossary.md |
Adds terminology reference. |
book/src/resources/links.md |
Adds relevant resources. |
book/src/resources/publications.md |
Documents publications. |
book/src/user-guide/closed-loop.md |
Documents closed-loop mode. |
book/src/user-guide/concepts.md |
Explains navigation concepts. |
book/src/user-guide/configuration.md |
Documents configuration schema. |
book/src/user-guide/coordinate-frames.md |
Documents frame conventions. |
book/src/user-guide/data-format.md |
Updates input schema. |
book/src/user-guide/dead-reckoning.md |
Documents dead reckoning. |
book/src/user-guide/library.md |
Documents library usage. |
book/src/user-guide/logging.md |
Updates logging guidance. |
book/src/user-guide/open-loop.md |
Clarifies unimplemented mode. |
book/src/user-guide/output-format.md |
Documents output schema. |
book/src/user-guide/overview.md |
Updates user-guide overview. |
book/src/user-guide/particle-filter.md |
Documents CLI particle filtering. |
book/src/user-guide/simulations.md |
Documents simulation workflow. |
book/src/user-guide/state-representation.md |
Documents state layouts. |
book/src/user-guide/synthetic.md |
Documents synthetic generation. |
book/theme/head.hbs |
Enables inline math rendering. |
conf/ekf_both.toml |
Refreshes EKF scenario configuration. |
conf/ekf_degraded.toml |
Refreshes degraded EKF scenario. |
conf/ekf_grav.toml |
Refreshes gravity-aided EKF scenario. |
conf/ekf_mag.toml |
Refreshes magnetic EKF scenario. |
conf/rbpf_both.toml |
Refreshes combined RBPF scenario. |
conf/rbpf_degraded.toml |
Refreshes degraded RBPF scenario. |
conf/rbpf_grav.toml |
Refreshes gravity-aided RBPF scenario. |
conf/rbpf_mag.toml |
Refreshes magnetic RBPF scenario. |
conf/rbpf_truth.toml |
Refreshes truth RBPF scenario. |
conf/real/ekf_both.toml |
Updates real-data EKF scenario. |
conf/real/ekf_degraded.toml |
Updates degraded real-data EKF scenario. |
conf/real/ekf_grav.toml |
Updates real gravity EKF scenario. |
conf/real/ekf_mag.toml |
Updates real magnetic EKF scenario. |
conf/real/rbpf_both.toml |
Updates real combined RBPF scenario. |
conf/real/rbpf_degraded.toml |
Updates degraded real RBPF scenario. |
conf/real/rbpf_grav.toml |
Updates real gravity RBPF scenario. |
conf/real/rbpf_mag.toml |
Updates real magnetic RBPF scenario. |
conf/real/ukf_both.toml |
Updates real combined UKF scenario. |
conf/real/ukf_degraded.toml |
Updates degraded real UKF scenario. |
conf/real/ukf_grav.toml |
Updates real gravity UKF scenario. |
conf/real/ukf_mag.toml |
Updates real magnetic UKF scenario. |
conf/ukf_both.toml |
Refreshes combined UKF scenario. |
conf/ukf_degraded.toml |
Refreshes degraded UKF scenario. |
conf/ukf_grav.toml |
Refreshes gravity-aided UKF scenario. |
conf/ukf_mag.toml |
Refreshes magnetic UKF scenario. |
core/Cargo.toml |
Removes unused nav-types dependency. |
core/README.md |
Corrects core-library documentation. |
core/examples/aiding.rs |
Adds compiled aiding example. |
core/examples/basic_ins.rs |
Updates basic INS example. |
core/examples/eskf.rs |
Adds compiled ESKF example. |
core/examples/gnss_outage.rs |
Updates outage example. |
core/examples/kalman_filters.rs |
Adds compiled filter example. |
core/examples/lever_arm.rs |
Adds compiled lever-arm example. |
core/examples/score_run.rs |
Adds compiled scoring example. |
core/src/earth.rs |
Corrects atmospheric and gravity calculations. |
core/src/engine.rs |
Updates engine behavior and documentation. |
core/src/gating.rs |
Clarifies gating behavior. |
core/src/kalman.rs |
Handles unavailable UKF map predictions. |
core/src/lib.rs |
Corrects equations and public documentation. |
core/src/linalg.rs |
Repairs rustdoc links. |
core/src/linearize.rs |
Corrects linearization documentation. |
core/src/measurements.rs |
Updates measurement documentation. |
core/src/messages.rs |
Fixes fault serialization and seeding. |
core/src/metrics.rs |
Supports documented scoring example. |
core/src/rbpf.rs |
Updates RBPF documentation and behavior. |
core/src/sim.rs |
Fixes serialization, configuration, and synthesis. |
core/tests/example_configs.rs |
Extends configuration validation tests. |
core/tests/perf_baseline.json |
Re-blesses synthetic performance results. |
core/tests/perf_baseline.rs |
Updates baseline reporting. |
core/tests/ukf_conditioning.rs |
Tests unavailable UKF measurements. |
examples/configs/README.md |
Updates configuration examples. |
examples/configs/extended_gnss_denied.yaml |
Updates fault-model syntax. |
examples/configs/geonav_example.toml |
Updates geonav configuration. |
examples/configs/simple_dropout.yaml |
Updates dropout configuration. |
examples/magnetometer-config.json |
Updates magnetometer example. |
examples/magnetometer-config.yaml |
Updates magnetometer example. |
geonav/README.md |
Corrects geonav usage examples. |
geonav/src/lib.rs |
Updates geophysical APIs and documentation. |
papers/joss/paper.bib |
Removes obsolete nav-types citation. |
papers/joss/paper.md |
Corrects implementation claim. |
sim/src/common.rs |
Validates output paths and wizard EOF. |
sim/src/main.rs |
Fixes CLI flags, validation, and failures. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
The glossary gave the textbook East-North-Up, but this crate's 'ENU' keeps the north-then-east horizontal order and flips only the vertical axis, as StrapdownState::to_enu does and the Coordinate Frames page says. A reader who took the glossary at its word would swap the horizontal components. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.


Stacked on #418 (base
docs/joss-v1); GitHub retargets it tomainwhen #418 merges. Closes #383.The book is what JOSS reviewers will check under "functionality documented" and "example usage". Before this PR, 36 of its 54 pages were one-line placeholders, and four filled pages documented APIs that do not exist. Writing it against the code turned up about 40 defects in the code itself. Those are fixed here, with tests, so the book describes software that behaves the way it says.
The book
book/(RBPF.md,EKF_USAGE.md, …) are removed, along with the orphan and stub pages. The eightapi/*stubs become one page pointing at rustdoc.SUMMARY.mdis written and verified. That covers:kalman_filters,eskf,aiding,lever_arm,score_run), so an API change breakscargo build --examplesinstead of quietly staling a page.$…$math now renders. mdBook 0.4's MathJax 2 doesn't handle it by default (theme/head.hbs). Every page was checked in a browser for MathJax errors and leftover raw TeX.deploy-book.ymlnow builds on pull requests, publishescargo docoutput under/api/with-D warnings, and link-checks offline. Workspace rustdoc was cleaned to pass that: 21 private intra-doc links and 4 redundant link targets.Defects fixed
CLI (
strapdown-sim)--plotand--parallelwere ignored on every subcommand. They are now honoured by dr/cl/pf and refused where they can't apply.-o out.h5/.parquet/.ncsilently created a directory and wrote CSV into it. These extensions are now refused, andsynrequires.csv.CLAUDE.mdalready claimed they were refused; now it is true.pf --horizontal-process-noise-std-m 0.5,0.5failed to parse; both the comma and space forms now work.configwith stdin at EOF looped forever; it now exits 1.--help:ol,clandpfhelp described three modes and a workingol.--no-estimate-baro-biassaid the opposite of what it does.drnow applies wall-clock limits, but not the health bounds, because an unaided arc is expected to diverge.Library
comboGNSS fault could not be read from any config file: serde cannot tag a sequence newtype. Breaking: it is nowCombo { faults }.seednever reached the fault models. Breaking:AidingConfig::seedis nowOption<u64>.NonFinite) when a sigma point left a geophysical map. It now skips that update, as the EKF and PF do.to_netcdftruncated timestamps to whole seconds.earth::barometric_altitudereturned about −152 km for the pressure of 100 m. It is now the exact inverse ofexpected_barometric_pressure.earth::gravitationdouble-counted the centrifugal term, and nothing called it. Breaking: removed, along withnav-types, its only user. The paper's "built on nav-types" claim goes in the same commit.relativeAltitudewas the GNSS altitude's own noise draw, so the barometer aided nothing.--baro-noise-std-pareached only an unread column.pressurewas in Pa against a documented hPa.speed/bearingwere noise-free under aspeedAccuracythat said otherwise. A new--gnss-velocity-noise-mps(default 0.5) fixes this, on its own RNG stream.Baseline re-bless
Only the six
syn_*scenarios move, because of the synthetic sensor fix; every real-data row is bit-identical.syn_cruise_1hz: horizontal RMSE 2.60 → 1.72 m (velocity fixes now carry an honest 0.5 m/s); vertical RMSE 2.28 → 1.52 m (the barometer is independent).Verification
cargo fmt-check,cargo lint,cargo lint-min,cargo test --workspace --all-features(939 passed),cargo test-min, andcargo doc --workspace --all-featureswith-D warnings.uv run ruff check,ruff format --checkandpytestpass.mdbook build(0.4.40) has no warnings. Every page's math was checked rendered in a browser.🤖 Generated with Claude Code