Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
710d193
Prune the book to the pages v1.0 will actually carry (#383)
jbrodovsky Oct 2, 2026
5b4e7bc
Make the combo GNSS fault readable from a configuration file
jbrodovsky Oct 2, 2026
e6a4fe5
Correct the mechanization equations in the crate docs, and the stale …
jbrodovsky Oct 2, 2026
a4d2e31
Build the book and its API docs on pull requests, and publish rustdoc…
jbrodovsky Oct 2, 2026
5fbdcac
Fill the book: every page in SUMMARY now documents v1.0 as it is (#383)
jbrodovsky Oct 2, 2026
a4cdbbe
Write netCDF timestamps with their fractional seconds
jbrodovsky Oct 2, 2026
757a247
Correct core docs that contradicted the code
jbrodovsky Oct 2, 2026
5ab051f
Make strapdown-sim's flags, outputs and exit codes do what they say
jbrodovsky Oct 2, 2026
550fd4d
Skip a UKF update whose sigma points cannot all be predicted
jbrodovsky Oct 2, 2026
e52ee92
Seed the GNSS faults from a config file's top-level seed
jbrodovsky Oct 2, 2026
591742d
Say that a duty cycle with no start phase opens with its outage
jbrodovsky Oct 2, 2026
06bc5c8
Refuse map resolutions finer than the maps support
jbrodovsky Oct 2, 2026
8bd0304
Bring the geonav docs back in line with its API
jbrodovsky Oct 2, 2026
77ec501
Drop a dataset median from the degraded-GNSS recipe comments
jbrodovsky Oct 2, 2026
57aeed7
List lint-min and test-min in the pull-request checklist
jbrodovsky Oct 2, 2026
032dc0c
Describe the forced update as the code applies it
jbrodovsky Oct 2, 2026
2f798e7
Remove a dead assert from matrix_square_root
jbrodovsky Oct 2, 2026
4aa4c7b
Correct core docs that went stale behind later fixes
jbrodovsky Oct 2, 2026
7baddfe
Rerun the two tutorial examples and print what they print now
jbrodovsky Oct 2, 2026
acb9171
Give the ESKF's state count correctly in the core README
jbrodovsky Oct 2, 2026
aa587f8
Remove earth::gravitation, which double-counted the centrifugal term,…
jbrodovsky Oct 2, 2026
8cd664a
Make the synthetic barometer and GNSS velocity independent sensors, a…
jbrodovsky Oct 2, 2026
9a2e098
Rerun every command in the book against the current binary and correc…
jbrodovsky Oct 2, 2026
0963ce9
Hold dr to its wall-clock budget, not to the health bounds
jbrodovsky Oct 2, 2026
f64c825
Leave mdBook's generated 404 page out of the offline link check
jbrodovsky Oct 2, 2026
d0991b4
Define the crate's ENU in the glossary as it actually is
jbrodovsky Oct 2, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 55 additions & 16 deletions .github/workflows/deploy-book.yml
Original file line number Diff line number Diff line change
@@ -1,49 +1,88 @@
name: Deploy mdBook to GitHub Pages

# The book and the API documentation it links to are built on every pull request that could
# change them, and deployed only from `main`. Until #383 the build ran on `main` alone, so a
# page that failed to build -- or a link into a page that had been deleted -- was first seen
# on the live site.
on:
push:
branches: [ "main" ]
# pull_request:
# branches: [ "main" ]
pull_request:
paths:
- "book/**"
- "core/**"
- "sim/**"
- "geonav/**"
- "CONTRIBUTING.md"
- "katex-header.html"
- ".github/workflows/deploy-book.yml"

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
# One deployment at a time, never cancelling one in progress. Pull-request builds get their
# own group so they neither queue behind nor cancel a deployment.
concurrency:
group: "pages"
cancel-in-progress: false
group: ${{ github.event_name == 'pull_request' && format('book-pr-{0}', github.event.pull_request.number) || 'pages' }}
cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
build:
runs-on: ubuntu-latest
timeout-minutes: 20
timeout-minutes: 45
steps:
- name: Checkout repository
uses: actions/checkout@v4

- name: Setup Rust
uses: dtolnay/rust-toolchain@stable

# `+stable` is deliberate. `rust-toolchain.toml` pins the workspace to 1.91 for lint
# reproducibility, and that pin would otherwise apply here too -- building a
# `+stable` for mdBook is deliberate. `rust-toolchain.toml` pins the workspace to 1.91
# for lint reproducibility, and that pin would otherwise apply here too -- building a
# third-party tool against an older toolchain than it supports is the classic way to
# break a docs deploy for a reason that has nothing to do with the docs.
- name: Setup Rust (stable, for mdBook)
uses: dtolnay/rust-toolchain@stable

- name: Setup Rust (pinned, for rustdoc)
uses: dtolnay/rust-toolchain@1.91

- uses: Swatinem/rust-cache@v2

- name: Install mdBook
run: |
cargo +stable install mdbook --version 0.4.40
cargo +stable install mdbook --version 0.4.40 --locked
mdbook --version

- name: Build the book
run: mdbook build book

# The API reference is published inside the book, under /api/, so the book can link to
# the documentation of the exact commit it was built from. docs.rs only has a crate's
# documentation once that version is on crates.io.
#
# `-D warnings` makes a broken intra-doc link fail the build. RUSTDOCFLAGS replaces the
# `rustdocflags` in .cargo/config.toml rather than adding to it, so the KaTeX header is
# repeated here, with an absolute path because rustdoc runs from each crate's directory.
- name: Build the API documentation
env:
RUSTDOCFLAGS: -D warnings --html-in-header ${{ github.workspace }}/katex-header.html
run: |
cd book
mdbook build
cargo doc --workspace --no-deps --all-features --locked
cp -r target/doc/. book/book/api/

# Offline: checks every relative link between book pages and into the API docs,
# without depending on external sites being up. 404.html is mdBook's generated error
# page; its `<base href="/strapdown-rs/">` (from `site-url`) is root-relative, which an
# offline check of local files cannot resolve.
- name: Check links
uses: lycheeverse/lychee-action@v2
with:
args: --offline --no-progress --exclude-path book/book/api --exclude-path book/book/404.html 'book/book/**/*.html'
fail: true

- name: Upload artifact
if: github.event_name == 'push'
uses: actions/upload-pages-artifact@v3
with:
path: ./book/book
Expand All @@ -55,7 +94,7 @@ jobs:
runs-on: ubuntu-latest
timeout-minutes: 10
needs: build
if: github.ref == 'refs/heads/main'
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
steps:
- name: Deploy to GitHub Pages
id: deployment
Expand Down
32 changes: 19 additions & 13 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ The core library implementing strapdown INS algorithms and simulation framework:
- **kalman.rs**: Kalman-style navigation filters including Unscented Kalman Filter (UKF) for nonlinear state estimation
- **particle.rs**: Particle-filter building blocks (the `Particle` trait, resampling and averaging strategies); not a filter on its own
- **rbpf.rs**: The Rao-Blackwellized particle filter, after Canciani & Raquet (2017) -- the one concrete particle filter
- **measurements.rs**: Measurement models (GPS position/velocity, barometric altitude, pseudorange, carrier phase) implementing the `MeasurementModel` trait
- **measurements.rs**: Measurement models (GPS position/velocity, barometric altitude, magnetometer yaw, ZUPT/ZARU) implementing the `MeasurementModel` trait. Loosely coupled only: there are no pseudorange or carrier-phase models
- **messages.rs**: Event stream handling for GNSS scheduling and fault injection scenarios
- **sim.rs**: Simulation utilities, CSV data loading (Sensor Logger format), dead reckoning and closed-loop functions
- **linalg.rs**: Linear algebra utilities for matrix operations
Expand All @@ -43,12 +43,15 @@ Command-line tool for running INS simulations with GNSS degradation:
- GNSS fault simulation: dropouts, reduced update rates, measurement corruption, bias injection
- Input: CSV files with IMU and GNSS measurements (Sensor Logger format)
- Output: **the CLI writes CSV only.** Every path through `strapdown-sim` ends in
`NavigationResult::to_csv`, and `OUTPUT_FILE_EXTENSIONS` in `sim/src/common.rs` is `["csv"]`,
so any other extension is rejected rather than filled with CSV. `to_hdf5`, `to_netcdf` and
`to_mcap` exist as **library** writers on `NavigationResult`, reachable from Rust but not
from this binary. There is no Parquet writer at all
`NavigationResult::to_csv`. In `sim/src/common.rs`, a `-o` ending in `.csv`
(`OUTPUT_FILE_EXTENSIONS`) names a file; one whose extension names another data format
(`REFUSED_OUTPUT_EXTENSIONS`: h5, hdf5, nc, netcdf, mcap, parquet, json, yaml, yml, toml, txt)
is refused unless it is an existing directory; anything else is a directory of CSV results.
`syn` must be given a `.csv` file. `to_hdf5`, `to_netcdf` and `to_mcap` exist as **library**
writers on `NavigationResult`, reachable from Rust but not from this binary. There is no
Parquet writer at all
- Configuration: TOML/YAML/JSON scenario files or command-line arguments
- Built-in logging: Use `--log-level` and `--log-file` flags (see LOGGING.md for details)
- Built-in logging: Use `--log-level` and `--log-file` flags (see `book/src/user-guide/logging.md`)

**Free Core scope**: Basic GNSS degradation (outages, noise, reduced availability)
**Future Pro scope**: Advanced faults (spoofing, jamming, multipath, terrain masking)
Expand All @@ -58,7 +61,7 @@ Command-line tool for running INS simulations with GNSS degradation:
- Loads NetCDF geophysical maps (gravity/magnetic anomaly grids)
- Integrates geophysical measurements with INS/GNSS filters
- Provides alternative PNT in GNSS-denied environments
- Built-in logging: Use `--log-level` and `--log-file` flags (see LOGGING.md for details)
- Built-in logging: Use `--log-level` and `--log-file` flags (see `book/src/user-guide/logging.md`)
- Status: Experimental feature for research, may be commercialized in future roadmap

### 4. `analysis` (/analysis, Python)
Expand All @@ -68,7 +71,7 @@ Post-processing and experiment tooling, exposed as the `analyze` CLI:
`_magnetic.nc` maps beside each trajectory. `just preprocess` runs it at **10 Hz**, which
gives 10 Hz inertial propagation against the ~1 Hz the GNSS was actually recorded at (the
GNSS columns stay NaN in nine rows out of ten; do not interpolate them up). `data/input` is
the one directory every consumer reads -- all 21 `conf/*.toml`, `geo-stats`, `postprocess`
the one directory every consumer reads -- all 15 `conf/*.toml`, `geo-stats`, `postprocess`
and `geoperf-*` -- so change the rate, not the path. `just preprocess-1hz` is the 1 Hz
variant, which is the rate every result before the geophysical fixes used
- **geostats.py**: characterises the geophysical measurements against those maps -- per-field
Expand Down Expand Up @@ -186,8 +189,8 @@ The Free Core implementation must achieve the following capabilities:
5. **Output Formats**:
- CSV, HDF5, NetCDF and MCAP export for analysis in Python/MATLAB/R. **These are
`NavigationResult` methods, not CLI output modes**: `strapdown-sim` writes CSV and
rejects every other extension, so reaching the other three means calling `to_hdf5`,
`to_netcdf` or `to_mcap` from Rust
refuses an output path naming another data format, so reaching the other three means
calling `to_hdf5`, `to_netcdf` or `to_mcap` from Rust
- Parquet is deliberately **not** supported at either layer: `sim/src/common.rs` refuses
`.parquet` rather than naming a file Parquet and filling it with CSV
- Navigation solution time series with position, velocity, attitude estimates
Expand Down Expand Up @@ -229,8 +232,10 @@ The Free Core implementation must achieve the following capabilities:
- Users control via `is_enu` boolean flags and sign conventions; `StrapdownState::to_ned`
and `to_enu` convert an existing state between the two
- Vertical velocity: positive down in NED, positive up in ENU
- `altitude` is height above the ellipsoid -- positive up -- in **both** frames, valid over
[-11,000m, 30,000m]. It is not a "down" coordinate in NED
- `altitude` is height above the ellipsoid -- positive up -- in **both** frames. The
mechanization is valid over [-11,000m, 30,000m], but nothing enforces that by default: the
health check's default altitude band is +/-1e8 m (`DEFAULT_HEALTH_ALT_{MIN,MAX}_M`), so
narrow `HealthLimits::alt_m` to make it a gate. It is not a "down" coordinate in NED
- `TestDataRecord` carries no frame tag, so every entry point that loads one takes the
frame from its caller: `sim::dead_reckoning(records, is_enu)` and `is_enu` on
`UkfConfig`/`EkfConfig`/`EskfConfig`, all defaulting to NED. On the CLI that is `--enu`
Expand All @@ -254,7 +259,8 @@ The Free Core implementation must achieve the following capabilities:
- **Forward propagation**: Uses `StrapdownState::propagate()` with strapdown equations (Chapter 5.4-5.5)
- **Measurement models**: Implement the `MeasurementModel` trait for update step
- Trait provides `predict_measurement()` and `innovation_covariance()` methods
- Implemented models: GPS position, GPS velocity, barometric altitude, pseudorange, carrier phase
- Implemented models: GPS position, velocity, and position+velocity; relative (barometric)
altitude; magnetometer yaw; ZUPT and ZARU. Geophysical models live in `strapdown-geonav`
- **UKF implementation**:
- Uses unscented transform with sigma points for nonlinear state estimation
- Handles full 9-state navigation solution
Expand Down
8 changes: 7 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,15 +39,21 @@ or put the release binary on your `PATH`.

## Before you open a pull request

The workspace enforces a strict lint gate rather than a warning-level one. Both of these must
The workspace enforces a strict lint gate rather than a warning-level one. All of these must
be clean, and CI runs exactly the same commands on the same pinned 1.91 toolchain:

```bash
cargo fmt-check # cargo fmt --all -- --check
cargo lint # cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo lint-min # cargo clippy -p strapdown-core --all-targets --no-default-features -- -D warnings
cargo test --workspace --all-features
cargo test-min # cargo test -p strapdown-core --no-default-features
```

`cargo lint` alone is not the whole gate. The two configurations disagree about what is dead:
an item used only behind a feature gate is live under `--all-features` and unused without it,
so `cargo lint-min` and `cargo test-min` catch what `cargo lint` cannot.

`clippy::pedantic` and `clippy::nursery` are denied workspace-wide, as are `missing_docs` and
the zero-panic lints (`unwrap_used`, `expect_used`, `panic`) in library code -- return a
`StrapdownError` instead. Every `pub` item, including struct fields and enum variants, needs a
Expand Down
60 changes: 5 additions & 55 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ resolver = "3"
authors = ["James Brodovsky"]
edition = "2024"
license = "MIT"
homepage = "https://www.strapdown.rs"
homepage = "https://jbrodovsky.github.io/strapdown-rs/"
repository = "https://github.com/jbrodovsky/strapdown-rs"
# Minimum supported Rust version. Keep this in sync with `channel` in
# rust-toolchain.toml, `msrv` in clippy.toml and the CI toolchain pins; raising
Expand Down
Loading
Loading