Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
0f6ad50
fixed non-moving geophysical bias bug
jbrodovsky Sep 22, 2026
1b0e127
wired in rbpf and postprocessing
jbrodovsky Sep 22, 2026
e50135f
fixed a last-row bug
jbrodovsky Sep 22, 2026
1114610
bugfix on preprocessing sample rate and scheduler
jbrodovsky Sep 22, 2026
f668444
updated preprocessing to auto-split
jbrodovsky Sep 22, 2026
58ce23d
checked in analysis package
jbrodovsky Sep 23, 2026
e4aea0f
Return the gravity anomaly in milligal, the unit it is consumed in
jbrodovsky Sep 23, 2026
30c4dc0
Measure the geophysical measurements, and make the repo a monorepo
jbrodovsky Sep 23, 2026
98eea5c
Run geophysical closed loop from a config file, as the RBPF already c…
jbrodovsky Sep 23, 2026
96a47f4
Make GNSS degradation represent jamming, and decouple it from the sch…
jbrodovsky Sep 23, 2026
2506a3d
Seed the randomized Jacobian test, and bound it outside its own noise
jbrodovsky Sep 23, 2026
d06dc00
Wire the new scenario tiers through the justfile, and fix `pipeline`
jbrodovsky Sep 23, 2026
b66c595
Preprocess at 10 Hz into data/input, the directory everything else reads
jbrodovsky Sep 23, 2026
bc4b02b
removed compare filters
jbrodovsky Sep 23, 2026
3f85160
Fix the duplicate [dependency-groups] that broke `uv sync`
jbrodovsky Sep 23, 2026
be7e220
Make `just pipeline` actually run, end to end
jbrodovsky Sep 23, 2026
a93f2e9
Score geophysical aiding against the denial baseline, like for like
jbrodovsky Sep 23, 2026
59c2788
Pad each map by an absolute margin, not a fraction of track length
jbrodovsky Sep 23, 2026
19cb1b6
Adopt the measured geophysical noise into the configs, in one command
claude Sep 23, 2026
e9d673d
fixed maps bug in geo-stats
jbrodovsky Sep 23, 2026
4575081
Re-wrap geostats.py at the repo's line length
claude Sep 23, 2026
38757d7
fixed implementation and plotting bugs
jbrodovsky Sep 24, 2026
827db06
bug fixes and RBPF perf verified
jbrodovsky Sep 26, 2026
2a40f1e
confirmed configurations
jbrodovsky Sep 26, 2026
967de6f
Regenerate the baseline book tables from the committed perf baseline
jbrodovsky Sep 26, 2026
014fc1d
updated font size
jbrodovsky Sep 26, 2026
c3e3553
fixed plotting font
jbrodovsky Oct 1, 2026
2d0f311
updated docs and work queue items
jbrodovsky Oct 1, 2026
77484db
Wrap the long _finite call in plotting.py to the 100-column format
jbrodovsky Oct 1, 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
49 changes: 49 additions & 0 deletions .github/workflows/python.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
name: Test and Lint Python Package

# Separate from rust.yml rather than a job inside it. The two halves of the monorepo fail for
# unrelated reasons, and a Python lint failure reported under "Test, Lint, and Build Rust
# Project" is a check name that lies about what broke.
#
# Trigger list mirrors rust.yml's, including the stacked-pull-request bases: a pull request is
# filtered on its *base*, so `main` alone gives no CI at all to every pull request in a stack
# except the bottom one.
on:
push:
branches: [ "main" ]
pull_request:
branches: [ "main", "v1/**", "claude/**" ]

jobs:
analysis:
name: analysis (lint + tests)
runs-on: ubuntu-latest
# Sized like rust.yml's jobs: enough for a cold uv resolve plus the test suite, short
# enough that a hang is reported rather than burning GitHub's 360-minute default.
timeout-minutes: 20
steps:
- uses: actions/checkout@v4

- name: Install uv
uses: astral-sh/setup-uv@v5
with:
enable-cache: true

# Resolves from the workspace root, which builds `analysis` as a member. `--frozen`
# makes a stale uv.lock a failure rather than something CI silently papers over by
# re-resolving -- the same contract Cargo.lock has on the Rust side.
- name: Sync
run: uv sync --frozen

# No GMT here on purpose. pygmt dlopens the GMT C library, and installing it would be
# several minutes of apt for one plotting function. Every import of it is inside the
# function that uses it, so the package, its CLI and its tests all load without it --
# and this job is what keeps that true. If someone moves `import pygmt` back to module
# scope, this fails.
- name: Lint
run: uv run ruff check

- name: Format check
run: uv run ruff format --check

- name: Test
run: uv run pytest -q
30 changes: 24 additions & 6 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,26 @@ target
data/raw
data/

# Python build and cache artefacts. `analysis/` is a checked-in workspace member as of the
# monorepo change, so these need naming explicitly -- the blanket `analysis/` ignore that
# used to cover them is gone, and the first commit of the package brought eight .pyc files
# with it.
__pycache__/
*.py[cod]
.venv/
*.egg-info/
.ruff_cache/
.pytest_cache/
.mypy_cache/

# Map files
*.nc

# GMT writes a gmt.conf into whatever directory it runs in the moment anything calls
# `gmtset`, which pygmt does on some paths. It records machine-local settings (data server,
# cache paths) and belongs to nobody's checkout.
gmt.conf

# MCAP test output files
*.mcap

Expand Down Expand Up @@ -43,8 +60,8 @@ book/book/
data/output/*.png

# Research artifacts kept locally, out of the v1.0 release scope.
# See papers/README.md for where these live now.
analysis/
# See papers/README.md for where these live now. `analysis/` used to be on this list; it is a
# checked-in workspace member now, but these loose scripts and notebooks are not.
papers/anomaly_rbpf/
papers/anomaly_ukf/
papers/data_paper/
Expand All @@ -53,9 +70,10 @@ analysis_rbpf_results.py
README_files/
log/

# Analysis notebooks, untracked in #335 for the same reason as analysis/: they import pygmt,
# cartopy, numpy and filterpy against the Python environment that pixi used to provide, and
# nothing in this Rust-only repository can run them. Kept on disk, out of the index. The map
# provenance they used to be the only record of now lives in geonav/README.md.
# Analysis notebooks, untracked in #335. They import pygmt, cartopy, numpy and filterpy
# against the Python environment pixi used to provide. `analysis/` is now a checked-in
# workspace member with its own dependency set, so a notebook worth keeping should move
# there rather than be un-ignored here. The map provenance they used to be the only record
# of now lives in geonav/README.md.
examples/geonav-sim/
examples/strapdown-sim/
22 changes: 15 additions & 7 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,11 +128,19 @@ forward-looking `allow` for a lint the pinned toolchain does not know about is m
or Ubuntu package is new enough (Ubuntu 26.04 and Debian trixie ship 2.46, bookworm 2.23), so
take it from [cli.github.com](https://github.com/cli/cli/blob/trunk/docs/install_linux.md) or
put the release binary on `PATH`. Diagnosed in #365; `gh api` was never affected.
- The repository is **Rust-only**. The Python post-processing package under `analysis/` was
untracked in `c5f72c6` when the repo was scoped to the v1.0 crate set, and the two analysis
notebooks under `examples/` followed in #335 -- they import pygmt, cartopy and filterpy
against the environment pixi used to provide, and nothing here can run them. So there is no
Python source, no `pyproject.toml` and no `ruff`/`ty` configuration to maintain. If Python bindings
or an analysis package return (`strapdown_py` is a commented-out workspace member), they get
their own tooling gate at that point.
- The repository is a **two-language monorepo**. Three Rust crates in a Cargo workspace, and
the Python `analysis` package in a uv workspace declared by the root `pyproject.toml`. The
`analysis/` package was untracked between `c5f72c6` and the monorepo change and is checked in
again now; the two analysis notebooks under `examples/` are still untracked, because they
import filterpy against the environment pixi used to provide.
- **The Python half has its own gate**, and it is separate from the Rust one:
`uv run ruff check`, `uv run ruff format --check`, `uv run pytest -q` from the repository
root -- `just check-python`, or `.github/workflows/python.yml` in CI. Configuration lives in
`[tool.ruff]` and `[tool.pytest.ini_options]` in the root `pyproject.toml`.
- **Never import pygmt at module scope.** It `dlopen`s the GMT C library on import, so a
module-scope import makes importing `analysis` fail wherever GMT is absent -- every
subcommand, including the ones that draw no maps, and CI, which installs no GMT on purpose.
Import it inside the function that uses it, as `plot_geo_map` and `download_maps` do.
- Python bindings to the Rust crates are still future work (`strapdown_py` is a commented-out
Cargo member); `analysis/` is post-processing, not bindings.
- Scenarios use YAML/JSON configs; CSV inputs follow Sensor Logger-style IMU/GNSS columns.
76 changes: 64 additions & 12 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@ The core library implementing strapdown INS algorithms and simulation framework:
- **lib.rs**: Library entry point and 9-state strapdown mechanization in local-level frame (NED). Implements forward propagation equations from Groves textbook (Chapter 5.4-5.5)
- **earth.rs**: WGS84 Earth ellipsoid model and geodetic calculations
- **kalman.rs**: Kalman-style navigation filters including Unscented Kalman Filter (UKF) for nonlinear state estimation
- **particle.rs**: Particle filter (Sequential Monte Carlo) implementation for non-Gaussian estimation with resampling strategies
- **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
- **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
Expand Down Expand Up @@ -60,6 +61,32 @@ Command-line tool for running INS simulations with GNSS degradation:
- Built-in logging: Use `--log-level` and `--log-file` flags (see LOGGING.md for details)
- Status: Experimental feature for research, may be commercialized in future roadmap

### 4. `analysis` (/analysis, Python)
Post-processing and experiment tooling, exposed as the `analyze` CLI:
- **preprocess.py**: rebuilds `data/input` from the Sensor Logger exports in `data/raw` --
resampling, splitting recordings at IMU dropouts, and downloading the `_gravity.nc` /
`_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`
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
bias, measurement noise and signal-to-noise, plus the de-correlation length that sets
`geo_interval_s`. Its anomaly models mirror `core/src/earth.rs` and `geonav/src/lib.rs` term
for term, and `self_check()` asserts they still agree; a statistic computed from a
*differently* computed anomaly would describe a quantity the filter never sees. `--apply-to
conf` (`just geo-adopt`) writes the measured bias, noise and bias prior into all 18
geophysical configs, line by line so the comments survive, rewriting only keys already
present so a `*_grav.toml` stays gravity-only. `geo_frequency_s` is held back behind
`--apply-interval`: the noise figures are measurements, but moving the interval from 1 s to
one measurement per de-correlation length changes what the experiment asks of the aid.
`core/tests/example_configs.rs` asserts all 18 carry the same values, so a partial adoption
fails the build rather than producing a comparison across two different R
Comment on lines +79 to +85
- **compare.py / plotting.py**: error statistics, LaTeX tables and map figures

Run it with `uv run analyze <subcommand>` from the repository root.

## Common Commands

### Build & Test
Expand Down Expand Up @@ -231,12 +258,21 @@ The Free Core implementation must achieve the following capabilities:
- **UKF implementation**:
- Uses unscented transform with sigma points for nonlinear state estimation
- Handles full 9-state navigation solution
- **Particle filter implementation** (`particle.rs`):
- Extended state: 15+ states (9 nav states + 3 accel bias + 3 gyro bias + optional)
- Resampling strategies: systematic, stratified, residual
- Averaging strategies: mean, weighted mean, maximum weight
- Includes vertical channel damping with altitude error feedback
- Each particle propagates independently through strapdown equations
- **Particle filter implementation** (`rbpf.rs`): Canciani & Raquet's marginalized particle
filter (IEEE TAES 53(1), 2017), error-state and closed-loop
- Particles sample horizontal position error only (`δlat, δlon`); the paper's linear states
-- altitude, velocity, nav-frame tilt, the barometer-aiding error `δh_a`, the barometer
loop's vertical-acceleration error `δâ`, and each map bias as `V` (Gauss-Markov) + `c`
(constant) -- are one Kalman filter whose covariance all particles share. **No IMU bias
states**: adding them made the RBPF diverge on degraded-GNSS runs
- Barometer aiding is a third-order loop in the mechanization; barometer readings feed the
loop and are not measurement updates
- Time update once per measurement epoch (transition and noise accumulate between); one
measurement update for every other sensor (`C = H T`, weights under `C P Cᵀ + R`)
- `horizontal_process_noise_std_m` defaults to the paper's zero (eq. 19), which **diverges**
with GNSS-rate fixes on MEMS data; the `conf/` recipes set 1 m/√s
- Reports the Kalman filters' layout, `[9 nav, b_a, b_g, map biases]`, with zero bias rows;
`core/src/rbpf.rs`'s module docs list the departures from the paper
- **Process noise**: `sim::DEFAULT_PROCESS_NOISE_DENSITY` is a **spectral density** -- a
variance per second. Each filter forms $Q_k = q\,\Delta t$; it was a per-step variance with
no `dt` anywhere until #374, which made effective Q a function of sample rate (a 50x spread
Expand Down Expand Up @@ -275,13 +311,29 @@ is the whole setup.
set, even with `static` on, and the vendored netCDF build then fails against those headers
- libfontconfig is a *runtime* dependency of `strapdown-sim`'s `plotting` feature (`dlopen`ed),
not a build-time one
- The repository is **Rust-only** -- the Python `analysis/` package was untracked in `c5f72c6`
when the repo was scoped to the v1.0 crate set, and the notebooks under `examples/` were
untracked in #335 for the same reason
- The repository is a **two-language monorepo**: three Rust crates in a Cargo workspace, and
the Python `analysis` package in a uv workspace declared by the root `pyproject.toml`. The
two share the directory and nothing else -- `analysis/` is not a Cargo member and the crates
are not uv members. `analysis/` was untracked between `c5f72c6` and the monorepo change; the
notebooks under `examples/` are still untracked
- **Python setup is `uv sync` from the repository root.** That builds the `analysis` member and
puts its `analyze` CLI on `uv run`, which is why the justfile recipes say `uv run analyze ...`
and not `uv run --project analysis ...`
- **pygmt is imported inside the functions that use it, never at module scope.** It `dlopen`s
the GMT C library on import, so a module-scope import makes importing `analysis` at all fail
wherever GMT is absent -- which took down every subcommand, including the ones that touch no
maps, and would take down CI. `.github/workflows/python.yml` deliberately installs no GMT, so
it is what keeps this true

### Lint Policy
Lints are **enforced at `deny`**, workspace-wide, not warn-level. `cargo lint` and one of the
blocking CI jobs run `cargo clippy --workspace --all-targets --all-features -- -D warnings`.

**Python.** `uv run ruff check`, `uv run ruff format --check` and `uv run pytest -q` from the
repository root, which is what `.github/workflows/python.yml` runs and what `just check-python`
wraps. Configuration is `[tool.ruff]` in the root `pyproject.toml`; `target-version` there and
`requires-python` in `analysis/pyproject.toml` must agree.

**Rust.** Lints are **enforced at `deny`**, workspace-wide, not warn-level. `cargo lint` and one
of the blocking CI jobs run `cargo clippy --workspace --all-targets --all-features -- -D warnings`.

**That is only half the gate.** A second blocking job runs
`cargo clippy -p strapdown-core --all-targets --no-default-features -- -D warnings`, and the
Expand Down
25 changes: 25 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,10 +20,35 @@ The primary contributions of this project are:

Additionally experimental research is being conducted on improving the accuracy and robustness of strapdown INS algorithms under degraded and denied GNSS conditions by providing an alternative PNT solution in the form of geophysical anomaly data (`strapdown-geonav`: /geonav). This is an area of active research.

## Repository layout

The repository is a two-language monorepo. The Rust crates are a Cargo workspace; the Python
package is a [uv](https://docs.astral.sh/uv/) workspace declared by the root `pyproject.toml`.
Neither is a member of the other.

| Path | Language | What it is |
|---|---|---|
| [`core/`](core/) | Rust | `strapdown-core` -- the mechanization, the filters and the simulation framework |
| [`sim/`](sim/) | Rust | `strapdown-sim` -- the command-line simulator |
| [`geonav/`](geonav/) | Rust | `strapdown-geonav` -- experimental gravity and magnetic anomaly aiding |
| [`analysis/`](analysis/) | Python | the `analyze` CLI: preprocessing, measurement characterisation and performance analysis |

## Installation

To use `strapdown-rs`, you can add it as a dependency in your `Cargo.toml` file: `cargo add strapdown-rs`. You can install the whole package or just the core library. Similarly you can install the simulation binary `cargo install strapdown-sim`.

To work on the repository itself, build both halves:

```bash
cargo build --workspace --release # the Rust crates; the toolchain fetches itself
uv sync # the analysis package, from the workspace root
```

`just setup` runs both. Nothing beyond Rust and uv is needed for the Rust crates; the
`analyze` CLI's map-drawing subcommands additionally want the GMT C library installed, though
every other subcommand -- preprocessing and measurement characterisation included -- runs
without it.
Comment on lines +47 to +50

## Runnable examples

Two worked examples live in [`core/examples/`](core/examples/). Both are self-contained --
Expand Down
Empty file added analysis/README.md
Empty file.
43 changes: 43 additions & 0 deletions analysis/pyproject.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
[project]
name = "analysis"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
authors = [
{ name = "James Brodovsky", email = "james.brodovsky@gmail.com" }
]
requires-python = ">=3.13"
dependencies = [
"cartopy>=0.25.0",
"haversine>=2.9.0",
"matplotlib>=3.10.8",
# NetCDF backend for xarray, so `geostats` can read the .nc maps `preprocess` writes.
# xarray arrives via pygmt but brings no engine of its own.
"netcdf4>=1.7.0",
"numpy>=2.4.0",
# Pure-Python World Magnetic Model. `geostats` needs the core field to turn a
# magnetometer reading into an anomaly; without it the "anomaly" is the whole ~50,000 nT
# total field. Agrees with the `world_magnetic_model` crate the Rust side uses.
"pygeomag>=1.1.0",
"pandas>=2.3.3",
"pygmt>=0.17.0",
"scipy>=1.16.3",
"tqdm>=4.67.1",
]

[tool.pytest.ini_options]
testpaths = ["tests"]

[build-system]
requires = ["uv_build>=0.9.21,<0.10.0"]
build-backend = "uv_build"

[dependency-groups]
dev = [
"pytest>=8.0",
"ruff>=0.14",
]

[project.scripts]
analyze = "analysis.__init__:main"
# generate-report = "analysis.scripts.report:generate"
Loading
Loading