Builds standardised wind, current and wave conditions along vessel routes — downloads met-ocean
data (Copernicus Marine and/or ERA5), harmonises it onto one grid, and samples it onto route
geometry into the ready-to-use bundle
water-path consumes. A Snakemake
workflow, managed with pixi.
📖 Full documentation: frasanvit.github.io/water-routefinder
— quickstart, every config/config.yaml key, architecture, and the v0.2 bundle contract.
The workflow supports only cmems and era5 for now (a later stage may add an offline mock
provider back for demos/CI) — running run-demo for real needs live credentials (see the
Quickstart).
pixi install # creates the project environment (pixi.toml)
pixi run test-unit # offline unit + input-format tests (no credentials needed)
pixi run dry-run # sanity-check the DAG without running anything (no credentials needed)
cp .env.example .env # then fill in CMEMS_USERNAME/CMEMS_PASSWORD (see the docs
# for alternatives, incl. `copernicusmarine login`)
pixi run run-demo # builds resources/user/dublin-bay -> results/dublin-bay/run-demo produces, from the example network under resources/user/dublin-bay/:
results/dublin-bay/
network/{harbours.csv, routes.geojson} # the water-path bundle
environment/{conditions.parquet, conditions.meta.yaml}
validation.txt # "OK", or the contract violations found
dublin-bay_diag_plot.png # route map (real coastlines) + conditions-over-time + data-quality panel
See Configuring your own network
for routes.geojson/harbours.csv shape and every config/config.yaml key.
pixi.toml, pyproject.toml # pixi workspace + the water_routefinder package (hatchling)
mkdocs.yml, docs/ # the documentation site (published to GitHub Pages)
INTERFACE.yaml # path-variable documentation
config/ # user-editable config + its schema doc
workflow/ # Snakefile, rules/*.smk, scripts/*.py, internal/ (schema + settings)
src/water_routefinder/ # the reusable, unit-tested core the workflow scripts call into
resources/user/ # your input networks (routes.geojson + harbours.csv)
resources/automatic/ # downloads + intermediates (safe to delete; regenerated)
resources/basemap/ # bundled offline land polygons for the diagnostic plot's map panel
results/ # the built bundle(s) + validation report + diagnostic plot
tests/ # unit, input-format, and end-to-end workflow tests
See Architecture for how it fits together and the bundle contract for the exact output format.
pixi run test-unit # offline: unit tests + input-format tests
pixi run test # same, minus any @pytest.mark.integration test
pixi run test-cov # same, + a coverage report (coverage.xml, for Codecov)
pixi run test-integration-live # needs CMEMS_USERNAME/CMEMS_PASSWORD and/or CDS API credentials
# -- includes the full end-to-end Snakemake workflow testdocs/ (built with MkDocs Material) is published
automatically to GitHub Pages on every push to main that touches it
(.github/workflows/docs.yml). To preview locally:
pixi run docs-serve # http://127.0.0.1:8000, live-reloads on edit
pixi run docs-build # static build to site/ (--strict: fails on broken links)Apache-2.0 — see LICENSE.