jejjohnson / jejjohnson/xrtoolz
Epic V3: Lagrangian — particle advection, transport diagnostics, trajectory metrics
- Dominant language
- Python
- Stars
- 1
- Forks
- 0
- Avg merge
- 13d 21h
- Merged PRs (30d)
- 3
Description
## Summary
Implement the Lagrangian half of the third validation view from [validation.md §3](docs/design/validation.md). Eulerian validation is necessary but not sufficient: small phase or gradient errors in a velocity field integrate into large trajectory divergence, wrong residence times, biased regional exchange. This epic gives users a first-class trajectory module + skill scores against drifters or twin trajectories.
## User story
> As an oceanographer, I want to evaluate both Eulerian fields and Lagrangian transport, so that a model that looks good on a grid is not accepted if it produces unrealistic trajectories, mixing, residence times, or connectivity.
## Lands in
- `xr_toolz.lagrangian` (**new top-level module**) — trajectory generation, advection, transport diagnostics
- `xr_toolz.metrics.lagrangian` (stub created by F1.1) — scalar comparisons of trajectories / statistics
- `xr_toolz.data` adapters (small) — observed-drifter ingestion via the same schema
## Sub-issues
- V3.1 — Trajectory schema + `SeedParticles`
- V3.2 — `AdvectParticles` (RK4 numpy backend)
- V3.3 — Transport diagnostics — `PairDispersion`, `ResidenceTime`, `ConnectivityMatrix`, `FTLE`
- V3.4 — Trajectory metrics — `TrajectoryRMSE`, `EndpointError`, `DispersionError`, `ResidenceTimeError`, `ConnectivityError`
- V3.5 — Drifter ingestion (observed trajectories conform to V3.1 schema)
- V3.6 — Demo notebook (twin advection on Gulf Stream `uo`/`vo`)
## Out of scope
- Eulerian process metrics (`GeostrophicBalanceError`, `DivergenceError`) — V4.
- Budget operators — V4.
- 3-D advection / depth resolved trajectories — initial scope is 2-D surface; revisit after V3.2 lands.
- JAX/numba acceleration — defer; numpy/scipy is the v1 backend per [validation.md §3 notes](docs/design/validation.md).
## Acceptance criteria
- [ ] V3.1–V3.6 closed.
- [ ] Trajectory schema documented and stable across all V3 sub-issues + V3.5 drifter ingest.
- [ ] No top-level dependency on parcels / OceanParcels — own the implementation per D7.
- [ ] mkdocs strict build is net-zero new warnings.
## References
- [docs/design/validation.md §3 Physical Representation](docs/design/validation.md)
- [docs/design/validation-decisions.md §D12 — Lagrangian diagnostics live outside metrics](docs/design/validation-decisions.md)
Contributor guide
Research direction
Start with docs/design/validation.md §3 and docs/design/validation-decisions.md §D12, then review V3.1–V3.6 to understand the planned trajectory schema, advection, diagnostics, metrics, ingestion, and demo. The epic is done when all sub-issues are closed, the schema is stable, no top-level parcels/OceanParcels dependency exists, and the mkdocs strict build adds no warnings.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- numpy, python
- Domain
- data
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100