Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
30 changes: 30 additions & 0 deletions .github/ISSUE_TEMPLATE/bug_report.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
---
name: Bug report
about: Something produced a wrong result, an error, or a crash
labels: bug
---

**What happened**

<!-- What you ran, what you expected, and what you got instead. -->

**How to reproduce**

<!-- The exact command or code. Attach the scenario/config file if there is one. A synthetic
trajectory (`strapdown-sim syn ... --seed N`) that shows the problem is the easiest input to
share. -->

```bash

```

**Environment**

- strapdown-rs version or commit:
- Crate(s) involved: strapdown-core / strapdown-sim / strapdown-geonav / analysis
- Cargo features enabled:
- OS and `rustc --version`:

**Output**

<!-- Error messages or log output (`--log-level debug`), trimmed to the relevant part. -->
8 changes: 8 additions & 0 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
blank_issues_enabled: true
contact_links:
- name: User guide
url: https://jbrodovsky.github.io/strapdown-rs/
about: Installation, the CLI, configuration files and the filters.
- name: API documentation
url: https://docs.rs/strapdown-core
about: Reference documentation for the strapdown-core library.
13 changes: 13 additions & 0 deletions .github/ISSUE_TEMPLATE/question.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
name: Question / support
about: Ask how to use strapdown-rs, or whether it can do something
labels: question
---

**What are you trying to do?**

<!-- The navigation problem or experiment, not only the command. -->

**What have you tried?**

<!-- Commands, config files or code, and which pages of the user guide you looked at. -->
5 changes: 3 additions & 2 deletions .github/workflows/draft-pdf.yml
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
name: Draft PDF
on:
push:
branches: [ "joss" ]
branches: [ "main" ]
paths: [ "papers/joss/**", ".github/workflows/draft-pdf.yml" ]
pull_request:
branches: [ "joss" ]
paths: [ "papers/joss/**", ".github/workflows/draft-pdf.yml" ]

jobs:
paper:
Expand Down
20 changes: 20 additions & 0 deletions CITATION.cff
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
cff-version: 1.2.0
message: "If you use this software, please cite it as below."
title: "strapdown-rs: Strapdown inertial navigation and GNSS-degradation simulation in Rust"
type: software
authors:
- family-names: Brodovsky
given-names: James
orcid: "https://orcid.org/0000-0002-1371-9044"
affiliation: Temple University
version: 1.0.0
license: MIT
repository-code: "https://github.com/jbrodovsky/strapdown-rs"
url: "https://jbrodovsky.github.io/strapdown-rs/"
keywords:
- inertial navigation
- strapdown INS
- GNSS
- Kalman filter
- particle filter
- Rust
6 changes: 4 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -269,8 +269,10 @@ The Free Core implementation must achieve the following capabilities:
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
- `horizontal_process_noise_std_m`: `RbpfConfig` (the library) defaults to the paper's zero
(eq. 19), which **diverges** with GNSS-rate fixes on MEMS data. `strapdown-sim` and its
`[particle_filter]` section default to 1 m/√s (`sim::DEFAULT_PF_HORIZONTAL_PROCESS_NOISE_STD_M`),
as the `conf/` recipes set
- 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
Expand Down
15 changes: 15 additions & 0 deletions CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Code of Conduct

This project adopts the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/)
as its code of conduct. It applies to everyone taking part in the project's spaces: the issue
tracker, pull requests, discussions, and any other channel used to work on `strapdown-rs`.

In short: be respectful and constructive, assume good faith, and critique work rather than
people. Harassment, personal attacks and discriminatory language are not acceptable.

## Reporting

Report unacceptable behaviour privately to the maintainer, James Brodovsky, at
[jbrodovsky@temple.edu](mailto:jbrodovsky@temple.edu). Reports are handled confidentially, and
the maintainer will respond with the enforcement steps described in the Contributor Covenant's
[enforcement guidelines](https://www.contributor-covenant.org/version/2/1/code_of_conduct/#enforcement-guidelines).
237 changes: 177 additions & 60 deletions README.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion analysis/pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[project]
name = "analysis"
version = "0.1.0"
description = "Add your description here"
description = "Preprocessing, measurement characterisation and result analysis for strapdown-rs experiments"
readme = "README.md"
authors = [
{ name = "James Brodovsky", email = "james.brodovsky@gmail.com" }
Expand Down
4 changes: 2 additions & 2 deletions book/src/filters/rbpf.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ following:
| key | meaning | default |
| --- | --- | --- |
| `velocity_process_noise_std_mps`, `attitude_process_noise_std_rad` | VRW and ARW, per √s (eq. 20) | 1e-3, 0.01 |
| `horizontal_process_noise_std_m` | `[north, east]` random walk on the sampled position, m/√s | `[0, 0]`, the paper's eq. 19 |
| `horizontal_process_noise_std_m` | `[north, east]` random walk on the sampled position, m/√s | `[1, 1]`; the paper's eq. 19 is `[0, 0]` (see below) |
| `baro_loop_time_constant_s` | the loop's gains place its three poles at `-1/τ` | 10 |
| `baro_error_std_m`, `baro_error_time_constant_s` | the barometer-aiding error as a Gauss-Markov process (`σ_b`, `τ_b`) | 8.3 m, 3600 s |
| `vertical_accel_error_init_std_mps2` | prior on `δâ` | 0.1 |
Expand All @@ -63,7 +63,7 @@ starts from its stationary distribution, and `c` takes the rest of `*_bias_init_
paper's magnetic temporal variation is `magnetic_variation_std = 5` with
`magnetic_variation_time_constant_s = 300`.

## Horizontal process noise: why the recipes set 1 m/√s
## Horizontal process noise: why the default is 1 m/√s

The paper's zero (eq. 19) makes every epoch's time update a noiseless observation of the
velocity and tilt errors. That moves their uncertainty out of the shared covariance and into
Expand Down
14 changes: 9 additions & 5 deletions core/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,10 @@
# Strapdown - A simple strapdown INS implementation
# strapdown-core

Strapdown-rs is a straightforward strapdown inertial navigation system (INS) implementation in Rust. It is designed to be simple and easy to understand, making it a great starting point for those interested in learning about strapdown INS algorithms. It is currently under active development.
The library half of [strapdown-rs](https://github.com/jbrodovsky/strapdown-rs): local-level
strapdown inertial navigation (Groves, 2nd ed., §5.4), four loosely coupled navigation filters
behind one `NavigationFilter` trait (ESKF, EKF, UKF and a Rao-Blackwellized particle filter),
measurement models, and the event-stream engine that simulates GNSS outages and faults. The
[user guide](https://jbrodovsky.github.io/strapdown-rs/) covers the concepts and the CLI.

## Installation

Expand Down Expand Up @@ -41,17 +45,17 @@ strapdown-core = { version = "1.0", features = ["hdf5", "netcdf"] }

## Summary

`strapdown-rs` is a Rust-based software library for implementing strapdown inertial navigation systems (INS). It provides core functionality for processing inertial measurement unit (IMU) data to estimate position, velocity, and orientation using a strapdown mechanization model that is typical of modern systems particularly in the low size, weight, and power (low SWaP) domain (cell phones, drones, robotics, UAVs, UUVs, etc.). Additionally, it provides some basic simulation capabilities for simulating INS scenarios (e.g. dead reckoning, closed-loop INS, intermitent GPS, GPS degradation, etc.).
`strapdown-rs` is a Rust-based software library for implementing strapdown inertial navigation systems (INS). It provides core functionality for processing inertial measurement unit (IMU) data to estimate position, velocity, and orientation using a strapdown mechanization model that is typical of modern systems particularly in the low size, weight, and power (low SWaP) domain (cell phones, drones, robotics, UAVs, UUVs, etc.). Additionally, it provides some basic simulation capabilities for simulating INS scenarios (e.g. dead reckoning, closed-loop INS, intermittent GPS, GPS degradation, etc.).

`strapdown-rs` prioritizes correctness, numerical stability, and performance. It is built with extensibility in mind, allowing researchers and engineers to implement additional filtering, sensor fusion, or aiding algorithms on top of the base INS framework. This library is not intended to be a full-featured INS solution, notably it does not have code for processing raw IMU or GPS signals and only implements a loosely-couple INS.
`strapdown-rs` prioritizes correctness, numerical stability, and performance. It is built with extensibility in mind, allowing researchers and engineers to implement additional filtering, sensor fusion, or aiding algorithms on top of the base INS framework. This library is not intended to be a full-featured INS solution, notably it does not have code for processing raw IMU or GPS signals and only implements a loosely coupled INS.

The toolbox is designed for research, teaching, and development purposes and aims to serve the broader robotics, aerospace, and autonomous systems communities. The intent is to provide a high-performance, memory-safe, and cross-platform implementation of strapdown INS algorithms that can be easily integrated into existing systems. The simulation is intended to be used for testing and verifying the correctness of the INS algorithms, by providing a simple simulation that allows users to generate a "ground truth" trajectory.

## Functionality

`strapdown-rs` is intended to be both a source code library included into your INS software and simulation environment as well as very light-weight INS simulator. The library provides a set of modules modeling the WGS84 Earth ellipsoid, a common 9-state strapdown forward mechanization, and a set of navigation filters for estimating position, velocity, and orientation from inertial measurement unit (IMU) data.

The simulation program provides a simple command line interface for running various configurations of the INS. In can run in open-loop (dead reckoning) mode or closed-loop (full state loosely couple UKF) mode. It can simulate various scenarios such as intermittent GPS, GPS degradation, and more. The simulation is designed to be easy to use and provides a simple API for generating datsets for further navigation processing or research.
The simulation program provides a simple command line interface for running various configurations of the INS. It runs dead reckoning (`dr`), closed-loop Kalman filtering (`cl`: the 15-state ESKF by default, with the UKF and EKF selectable) and the particle filter (`pf`). It can simulate various scenarios such as intermittent GPS, GPS degradation, and more. The simulation is designed to be easy to use and provides a simple API for generating datasets for further navigation processing or research.

`strapdown-sim` includes built-in logging capabilities using the Rust `log` crate. Library functions use log macros for diagnostic output that can be captured by any logging backend.

Expand Down
8 changes: 5 additions & 3 deletions core/src/rbpf.rs
Original file line number Diff line number Diff line change
Expand Up @@ -74,8 +74,8 @@
//! misstate a Gauss-Markov state's variance, and this does not.
//! 6. **Horizontal position process noise is configurable**
//! ([`RbpfConfig::horizontal_process_noise_std_m`]). Its default is the paper's zero
//! (eq. 19), which diverges with GNSS-rate fixes on MEMS data; the configurations under
//! `conf/` use 1 m per root-second.
//! (eq. 19), which diverges with GNSS-rate fixes on MEMS data; `strapdown-sim` and the
//! configurations under `conf/` use 1 m per root-second.

use crate::StrapdownError;
use crate::gating::{
Expand Down Expand Up @@ -388,7 +388,9 @@ pub struct RbpfConfig {
/// the particles' spread, and resampling on a metre-level fix destroys that spread. On the
/// reference recording the conditional velocity sigma fell to millimetres per second,
/// GNSS velocity fixes stopped correcting anything, and the solution ran 17 km off; 1 m per
/// root-second held it to 3.8 m. The configurations under `conf/` set that.
/// root-second held it to 3.8 m. The configurations under `conf/` set that, and so does
/// `strapdown-sim` by default ([`crate::sim::DEFAULT_PF_HORIZONTAL_PROCESS_NOISE_STD_M`]);
/// only this library-level default keeps the paper's value.
pub horizontal_process_noise_std_m: Vector2<f64>,
/// Time constant of the barometer loop, seconds. The gains place all three closed-loop
/// poles at `-1 / tau`: `k₁ = 3/tau`, `k₂ = 3/tau² + 2g/R`, `k₃ = 1/tau³`.
Expand Down
21 changes: 15 additions & 6 deletions core/src/sim.rs
Original file line number Diff line number Diff line change
Expand Up @@ -328,6 +328,16 @@ pub const DEFAULT_PROCESS_NOISE_DENSITY: [f64; 15] = [
1e-8, // gyro bias z, (rad/s)^2/s
];

/// Default [`ParticleFilterConfig::horizontal_process_noise_std_m`], m per sqrt(s), applied
/// to both the north and east channels.
///
/// The simulator departs here from the library's [`crate::rbpf::RbpfConfig`], whose default is
/// Canciani & Raquet's zero (eq. 19). That zero diverges with GNSS-rate fixes on MEMS data --
/// `strapdown-sim pf` with no flags left a 10-minute synthetic trajectory at 500 m/s -- so a
/// simulator default that only works on navigation-grade data would fail the first thing a new
/// user tries. One metre per root-second is what every recipe under `conf/` uses.
pub const DEFAULT_PF_HORIZONTAL_PROCESS_NOISE_STD_M: f64 = 1.0;

/// Default [`ExecutionLimits::max_wall_clock_ratio`]: a run may burn at most a quarter of a
/// second of wall-clock time per second of trajectory it simulates.
pub const DEFAULT_MAX_WALL_CLOCK_RATIO: f64 = 0.25;
Expand Down Expand Up @@ -5337,7 +5347,8 @@ pub struct ParticleFilterConfig {
/// [`crate::rbpf::RbpfConfig::attitude_process_noise_std_rad`].
pub attitude_process_noise_std_rad: f64,
/// Random walk on the sampled horizontal position error, [`north`, `east`] in m per
/// sqrt(s). The filter's default is Canciani & Raquet's zero (eq. 19), which diverges with
/// sqrt(s). Defaults to [`DEFAULT_PF_HORIZONTAL_PROCESS_NOISE_STD_M`] on both channels,
/// not the library filter's zero (Canciani & Raquet's eq. 19), which diverges with
/// GNSS-rate fixes on MEMS data; see
/// [`crate::rbpf::RbpfConfig::horizontal_process_noise_std_m`].
pub horizontal_process_noise_std_m: Vec<f64>,
Expand Down Expand Up @@ -5560,7 +5571,8 @@ impl Default for ParticleFilterConfig {
fn default() -> Self {
// The barometer-loop and resampling defaults are the filter's own, read from it rather
// than restated, so a config file that omits them runs the filter `RbpfConfig`
// documents.
// documents. The horizontal process noise is the one deliberate exception; see
// `DEFAULT_PF_HORIZONTAL_PROCESS_NOISE_STD_M`.
let filter = crate::rbpf::RbpfConfig::default();
Self {
num_particles: default_num_particles(),
Expand All @@ -5569,10 +5581,7 @@ impl Default for ParticleFilterConfig {
attitude_init_std_rad: default_attitude_init_std_rad(),
velocity_process_noise_std_mps: default_velocity_process_noise_std_mps(),
attitude_process_noise_std_rad: default_attitude_process_noise_std_rad(),
horizontal_process_noise_std_m: filter
.horizontal_process_noise_std_m
.as_slice()
.to_vec(),
horizontal_process_noise_std_m: vec![DEFAULT_PF_HORIZONTAL_PROCESS_NOISE_STD_M; 2],
baro_loop_time_constant_s: filter.baro_loop_time_constant_s,
baro_error_std_m: filter.baro_error_std_m,
baro_error_time_constant_s: filter.baro_error_time_constant_s,
Expand Down
7 changes: 5 additions & 2 deletions papers/README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,11 @@
# Papers

This directory holds the [JOSS](https://joss.theoj.org/) submission for
`strapdown-rs`. It is built by the `Draft PDF` GitHub Actions workflow
(`.github/workflows/draft-pdf.yml`) on pushes to the `joss` branch.
`strapdown-rs`, under review at
[openjournals/joss-reviews#11377](https://github.com/openjournals/joss-reviews/issues/11377).
The review reads the paper from `main`. The `Draft PDF` GitHub Actions workflow
(`.github/workflows/draft-pdf.yml`) builds it on every pull request and push to `main` that
touches `papers/joss/`, and uploads the PDF as a workflow artifact.

- `joss/paper.md` — the submission manuscript
- `joss/paper.bib` — its bibliography
Expand Down
Loading
Loading