Skip to content

Write the v1.0 book, and fix what writing it uncovered (#383) - #419

Merged
jbrodovsky merged 26 commits into
docs/joss-v1from
docs/book-v1
Oct 2, 2026
Merged

jbrodovsky merged 26 commits into
docs/joss-v1from
docs/book-v1

Conversation

@jbrodovsky

Copy link
Copy Markdown
Owner

Stacked on #418 (base docs/joss-v1); GitHub retargets it to main when #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

  • Pruned outline. The six stale design notes in book/ (RBPF.md, EKF_USAGE.md, …) are removed, along with the orphan and stub pages. The eight api/* stubs become one page pointing at rustdoc.
  • Every page in SUMMARY.md is written and verified. That covers:
    • installation and quick start;
    • the navigation model (Groves eqs. 5.46/5.47/5.54/5.56, taken from the code), frames and state layouts;
    • one page per subcommand, input and output schemas, every configuration section, and library use;
    • the filters: ESKF, EKF, UKF and RBPF, measurements and gating;
    • GNSS degradation, experimental geonav, architecture, analysis tooling, FAQ, publications and glossary.
  • Rust in the book is included by anchor from compiled examples. Five new ones (kalman_filters, eskf, aiding, lever_arm, score_run), so an API change breaks cargo build --examples instead of quietly staling a page.
  • Every CLI command shown was run, and printed outputs were re-run after the code changes below. Accuracy figures come only from the generated baseline tables.
  • Inline $…$ 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.yml now builds on pull requests, publishes cargo doc output 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)

  • --plot and --parallel were ignored on every subcommand. They are now honoured by dr/cl/pf and refused where they can't apply.
  • A failed file in a batch still exited 0. It now exits non-zero after running the rest.
  • Output paths:
    • -o out.h5 / .parquet / .nc silently created a directory and wrote CSV into it. These extensions are now refused, and syn requires .csv.
    • CLAUDE.md already claimed they were refused; now it is true.
  • Particle filter, gating and input:
    • pf --horizontal-process-noise-std-m 0.5,0.5 failed to parse; both the comma and space forms now work.
    • Gate values in config files were never validated. They now go through the same validator as the CLI flags.
    • config with stdin at EOF looped forever; it now exits 1.
  • --help:
    • The top-level, ol, cl and pf help described three modes and a working ol.
    • --no-estimate-baro-bias said the opposite of what it does.
    • The ESKF state count omitted the barometric bias.
  • dr now applies wall-clock limits, but not the health bounds, because an unaided arc is expected to diverge.
  • The wizard offered the unimplemented open-loop mode; it now offers synthetic generation instead.

Library

  • A combo GNSS fault could not be read from any config file: serde cannot tag a sequence newtype. Breaking: it is now Combo { faults }.
  • A config file's top-level seed never reached the fault models. Breaking: AidingConfig::seed is now Option<u64>.
  • The UKF aborted (NonFinite) when a sigma point left a geophysical map. It now skips that update, as the EKF and PF do.
  • Map resolutions finer than the data supports were silently relabelled; they are now refused.
  • to_netcdf truncated timestamps to whole seconds.
  • earth::barometric_altitude returned about −152 km for the pressure of 100 m. It is now the exact inverse of expected_barometric_pressure.
  • earth::gravitation double-counted the centrifugal term, and nothing called it. Breaking: removed, along with nav-types, its only user. The paper's "built on nav-types" claim goes in the same commit.
  • Synthetic generator. Each item below was wrong before; all are fixed.
    • relativeAltitude was the GNSS altitude's own noise draw, so the barometer aided nothing.
    • --baro-noise-std-pa reached only an unread column.
    • pressure was in Pa against a documented hPa.
    • speed/bearing were noise-free under a speedAccuracy that said otherwise. A new --gnss-velocity-noise-mps (default 0.5) fixes this, on its own RNG stream.
  • Docs that contradicted the code, all corrected:

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).
  • ESKF attitude error 0.42° → 0.65° geodesic (real velocity noise now reaches tilt).

Verification

  • All of these pass: cargo fmt-check, cargo lint, cargo lint-min, cargo test --workspace --all-features (939 passed), cargo test-min, and cargo doc --workspace --all-features with -D warnings.
  • Python: uv run ruff check, ruff format --check and pytest pass.
  • mdbook build (0.4.40) has no warnings. Every page's math was checked rendered in a browser.
  • Every command in the book was re-run against the final binary.

🤖 Generated with Claude Code

jbrodovsky and others added 24 commits October 1, 2026 21:56
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>
Copilot AI balanced review requested due to automatic review settings October 2, 2026 01:58
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>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 High severity · 1 Low severity

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.

Comment thread .github/workflows/deploy-book.yml Resolved
Comment thread book/src/resources/glossary.md Resolved
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>
@jbrodovsky
jbrodovsky merged commit 0d89789 into docs/joss-v1 Oct 2, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants