jejjohnson / jejjohnson/xrtoolz

Epic V3: Lagrangian — particle advection, transport diagnostics, trajectory metrics

Open
#49 0 comments 0 reactions 0 assignees View on GitHub
area:code enhancement epic validation-framework
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.