development.md

Development Guide

Managing Dependencies

Dependencies are defined in pyproject.toml, while uv.lock stores the exact resolved versions.

Install the existing locked environment without changing uv.lock:

uv sync --locked

After changing dependencies in pyproject.toml, update the lockfile and environment with:

uv lock
uv sync

Commit pyproject.toml and uv.lock together.

Command-Line Tools

Synchronize the project environment before running the tools:

uv sync --locked

1. Ship Simulator

Use the interactive simulator to generate synthetic ship-trajectory CSV files when recorded trajectory data are unavailable. Run it from the project root:

uv run ship-simulator

2. Trajectory Predictor

Inspect the ship's trajectory and Bayesian CTRV posterior updates in one desktop window. Run from the project root after synchronizing the environment:

uv run trajectory-predictor

The built-in Help window describes the controls, settings, and keyboard shortcuts. RBPF and SMC update online; VI and MCMC refit an expanding prefix and are slower.

Code Quality and Tests

GitHub Actions runs the tests on Python 3.10, 3.12, and 3.14 for every push and pull request. Run the checks locally from the project root with:

uv run pytest

To apply Ruff formatting automatically:

uv run ruff format .