Skip to content

Update the JOSS paper and reviewer-facing docs for the v1.0 review - #418

Merged
jbrodovsky merged 8 commits into
mainfrom
docs/joss-v1
Oct 2, 2026
Merged

jbrodovsky merged 8 commits into
mainfrom
docs/joss-v1

Conversation

@jbrodovsky

Copy link
Copy Markdown
Owner

Updates the JOSS paper and the reviewer-facing parts of the repository for the review that opened at openjournals/joss-reviews#11377. The book overhaul (#383) follows in a separate PR stacked on this one.

Paper (papers/joss/)

  • BibTeX now parses. The % comments in the wgs84 entry are what failed editorialbot. Every entry was checked with bibtex-ruby, the parser editorialbot uses, and all 10 load. groves gains its year, gtsam becomes the tech report it is, and the DOIs are bare. anom-pf has its DOI and pages (10.33012/2026.20618, pp. 399–410). Canciani & Raquet (2017) is added. The uncited nalgebra entry is removed.

  • Rewritten for v1.0. The paper drops from 2,521 to 1,292 words (JOSS allows 750–1,750). New title: strapdown-rs: Strapdown inertial navigation and GNSS-degradation simulation in Rust. Claims that no longer matched the code are fixed:

    Old claim Now
    strapdown and filter modules modules as they exist
    15-state UKF in closed loop ESKF is the default
    three CLI modes, two crates three crates
    WMM cited for a dipole WMM cited for yaw declination
    datasets "archived alongside the software" not tracked, so replaced with the test suite, CI accuracy gate and conf/ recipes

    The AI disclosure now matches the Claude Code and Copilot-agent commits visible in the history.

  • Draft PDF workflow builds on PRs and pushes to main that touch papers/joss/. It used to trigger only on a joss branch the review no longer uses.

Reviewer checklist items

  • README.
    • It said cargo add strapdown-rs (a legacy 0.4.0 crate) and cargo install strapdown-sim (never published). It now installs from git until v1.0.0 is published at acceptance.
    • New sections: statement of need, a quick start that runs as written, how to run the tests, contributing and support, citing.
    • Removed: the dead LOGGING.md link, the untracked-dataset claim, and "open loop" used to mean dead reckoning.
  • Added CODE_OF_CONDUCT.md (Contributor Covenant 2.1), bug and question issue templates, and CITATION.cff.
  • Fixed stale text in core/README.md and the placeholder description in analysis/pyproject.toml.

One code fix

strapdown-sim pf with default settings diverged. On a 10-minute syn trajectory it stopped at the 500 m/s speed check. Both shipped example configs that run the particle filter did the same. The cause was the inherited horizontal_process_noise_std_m = 0 (the paper's eq. 19), which the docs already said diverges on MEMS data. The simulator and its config now default to 1 m/√s, which is what every conf/ recipe sets. RbpfConfig keeps the paper's zero as the library default. A new test holds the CLI and config defaults equal and non-zero.

Verification

  • cargo fmt-check, cargo lint, cargo lint-min, cargo test --workspace --all-features and cargo test-min all pass.
  • The README commands were run as written:
    • syn, cl with a duty-cycle outage, cl --filter ukf, dr and pf all ran on a synthetic trajectory.
    • examples/configs/particle_filter_comparison.yaml runs.
    • cargo add strapdown-core --git … builds and runs in a fresh cargo new project.
  • Every paper citation resolves (pandoc --citeproc).

After merge (maintainer, on the review thread)

  • @editorialbot generate pdf.
  • Ask the editor to update the title, and to set the version to v1.0.0 at acceptance.

🤖 Generated with Claude Code

jbrodovsky and others added 4 commits October 1, 2026 20:15
…per from main

The wgs84 entry carried inline % comments that bibtex-ruby rejects, which is the
editorialbot failure on openjournals/joss-reviews#11377. The rest of the file is
tidied while it is open: groves had no year and a local Zotero path, gtsam was an
@Article whose journal was a university, anom-ukf's DOI was a URL, anom-pf had
empty fields where its DOI and pages belong, and nalgebra was uncited and pointed
at the nav-types repository. Canciani & Raquet (2017) is added for the RBPF.

The Draft PDF workflow watched a joss branch the review no longer uses; it now
builds on pull requests and pushes to main that touch papers/joss/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The paper described the v0.3 code. It named modules that no longer exist, said
closed loop ran a 15-state UKF when the ESKF is the default, listed three CLI
modes and two crates, cited the World Magnetic Model for a dipole, and claimed
processed datasets were archived in a repository that tracks none. It was also
2,521 words against JOSS's 1,750.

The new text is 1,292 words. It retitles the paper and describes the four filters
behind one trait, the event-stream separation of scheduling and fault injection,
and the zero-panic and frame-check design. It replaces the dataset claim with
what can be verified: the test suite, the CI accuracy gate and the conf/ recipes.
The AI disclosure now matches the commit history reviewers can see.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The README's install line named strapdown-rs, a legacy crate at 0.4.0, and told
users to cargo install a strapdown-sim that has never been published. Its badges
pointed at the same wrong crate, it linked a LOGGING.md that does not exist,
advertised a dataset the repository does not track, and called dead reckoning
open loop. It also never said how to run the tests or where to ask for help,
both of which the reviewer checklist asks for.

Installation is now from git until v1.0.0 reaches crates.io at acceptance. The
README gains a statement of need, a quick start that runs as written on a
synthetic trajectory, test instructions, and contributing and support pointers.
CODE_OF_CONDUCT.md, issue templates and CITATION.cff are added. core/README.md
and the analysis package description lose their stale and placeholder text.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nverges

strapdown-sim pf with no flags diverged on a 10-minute synthetic trajectory and
stopped at its 500 m/s speed check. Both shipped example configs that run the
particle filter, particle_filter_comparison.yaml and parallel_example.toml, did
the same, because neither sets horizontal_process_noise_std_m. The simulator
inherited the library's default, Canciani & Raquet's zero (eq. 19), which the
docs already said diverges with GNSS-rate fixes on MEMS data. A reviewer's first
particle-filter run would have failed.

The CLI flag and the [particle_filter] section now default to 1 m/sqrt(s) on both
channels (sim::DEFAULT_PF_HORIZONTAL_PROCESS_NOISE_STD_M), which is what every conf/
recipe sets. RbpfConfig keeps the paper's zero as the library default, so the
filter still means what its module docs say. A test holds the CLI and config
defaults equal and non-zero.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings October 2, 2026 00:26

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 installation section incorrectly says Rust is the only requirement despite the simulator’s default native build prerequisites.

Review effort: Balanced
Findings: 1 Low severity

Open (1)
What changed in this PR

Updates the JOSS submission and reviewer-facing documentation for the v1.0 review, while correcting unstable particle-filter defaults.

Changes:

  • Rewrites the JOSS paper, bibliography, citation metadata, and PDF workflow.
  • Expands contributor, support, installation, and issue-reporting documentation.
  • Defaults simulator RBPF horizontal process noise to 1 m/√s while preserving the library default.
File Description
sim/​src/​main.rs Applies and tests the CLI particle-filter default.
README.md Rewrites project and reviewer-facing documentation.
papers/​README.md Documents the active JOSS review workflow.
papers/​joss/​paper.md Rewrites the JOSS manuscript for v1.0.
papers/​joss/​paper.bib Corrects and expands bibliography metadata.
core/​src/​sim.rs Defines the simulator-specific RBPF default.
core/​src/​rbpf.rs Clarifies the library/simulator default distinction.
core/​README.md Updates crate capabilities and terminology.
CODE_OF_CONDUCT.md Adds conduct and reporting guidance.
CLAUDE.md Records the revised RBPF default convention.
CITATION.cff Adds software citation metadata.
book/​src/​filters/​rbpf.md Updates documented simulator defaults.
analysis/​pyproject.toml Replaces the placeholder package description.
.github/​workflows/​draft-pdf.yml Runs paper builds on relevant PRs and main.
.github/​ISSUE_TEMPLATE/​question.md Adds a support template.
.github/​ISSUE_TEMPLATE/​config.yml Adds issue-form documentation links.
.github/​ISSUE_TEMPLATE/​bug_report.md Adds a structured bug template.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread README.md Resolved
jbrodovsky and others added 4 commits October 1, 2026 20:35
Without --no-noise, strapdown-sim syn writes sensor records with no truth columns.
The kinematic truth comes only from a --no-noise run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
'Rust is the only hard requirement' covered the simulator install below it.
strapdown-sim enables plotting by default, and that feature builds freetype from
source, which needs a C/C++ compiler and cmake. The requirements are now stated per
install: the library needs only Rust, and the simulator's needs are spelled out where
it is installed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The README called the default filter 15-state. strapdown-sim estimates a barometric
bias by default, so cl runs 16 error states unless --no-estimate-baro-bias is
given.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A duty cycle with no start phase begins in its off window, so --on-s 100 --off-s 50
denies GNSS for the first 50 s, then gives 100 s of fixes. The comment had the
order reversed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@jbrodovsky
jbrodovsky merged commit 53b2b29 into main Oct 2, 2026
10 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