Suite d'exemples alignée sur l'API publique v1 (CLI hmp + API Python import hydromodpy as hmp). Le dossier examples/ est lui-même un workspace HydroModPy : les projets vivent sous projects/ et partagent les données d'entrée via la résolution de chemins du workspace.

mamba activate hmp_refact
pip install -e .
hmp install-binaries     # MF6 + MFNWT + MP6 + MP7 + MT3D-USGS dans ~/.cache/hydromodpy/bin/
hmp doctor               # diagnostic env (Python, deps, solveurs, workspace)

Les champs gridded vivent en Zarr v2 (sortie split schema/writer/reader/finalizer) et respectent les conventions CF-1.11 + ACDD-1.3 + UGRID-1.0. Les sorties tabulaires vivent en Parquet v2.6. Les exports GeoTIFF, CSV, STAC, RO-Crate et PROV-O sont des sidecars utilisateur, pas la source de vérité V1.

Les sorties de run ne sont pas versionnees : outputs/, web/, web_review/, figures/, simulations/, catalog.duckdb et data/cache.duckdb sont des artefacts regenerables localement.

Les galeries et fixtures documentaires restent versionnees par intention. C'est le cas notamment de 07_mesh_gallery, 08_mesh_viewer, 09_capability_gallery et des dossiers fixtures/. Ces fichiers servent de references stables pour la documentation, les exemples inspectables et les tests de contrat.

hmp.open(...) lève FileNotFoundError si aucun catalog.duckdb n'existe (create=False par défaut) ; passer create=True pour initialiser un catalogue vide. C'est le point d'entrée recommandé pour inspecter les runs passés (cat.frame, cat.latest(), cat[ref]).

Liste à jour via hmp --help. Les nouveautés à connaître :

• hmp export-package <sim_ref> -o sim.hmp : archive portable (tar.zst + manifest.json, avec RO-Crate best-effort).
• hmp add sim.hmp / hmp import sim.hmp : roundtrip d'import.
• hmp index register|search|forget|prune : registre machine-wide des workspaces.
• hmp install-binaries : MF6 / MFNWT / MP6 / MP7 / MT3D-USGS.
• hmp gc : caches orphelins + tmp parquet + runs zombies.
• hmp vacuum : compaction DuckDB (CHECKPOINT) + consolidation Zarr.
• hmp privacy : purge auditée d'une simulation.
• hmp manage [--workspace ...] : UI navigateur locale pour inspecter les DuckDB.
• hmp run --resume <RUN_ID> / --from <STEP> : reprise cascade-aware via le journal append-only workflow_steps (HeartbeatPulse détecte les zombies).

1. 00_getting_started : structure minimale d'un project.toml, premier run, découverte du catalogue.
2. 01_calibration : [workflow].mode = "calibration" via hmp run et API hmp.calibrate.
3. 04_data_overview : workflow « données seulement », sans simulation.
4. 02_nancon_watershed : premier bassin réel, Nançon (~110 km²).
5. 11_nancon_watershed : showcase V1 du Nançon (tous les workflows, overlays, API Python complète).
6. 06_vire_selune : permanent / transitoire, MF6 vs NWT, maillage régulier vs irrégulier.
7. 07_mesh_gallery + 08_mesh_viewer : cas « maillage seul ».
8. 09_capability_gallery : figures de référence publiées.

Parcours data-scientist : 00 → 01 → explorer hmp.open("examples/") (cat.frame, cat.find(...), cat.read(ref, var), hmp.index() pour la fédération) puis RunSet pour les exports ML-ready.

• Tous les TOML des projets 00 à 09 et 11 ont été migrés vers la schema v1 (modflownwt -> modflow_nwt, restructuration de [overview], [geographic], [flow.param.X.field]).
• Les artefacts (catalog.duckdb, dossier simulations/<sim_id>.zarr, figures/<run_name>/) sont créés au niveau du workspace examples/ et ignorés par .gitignore.
• Trois fichiers ont été mis en quarantaine avec suffixe .draft parce qu'ils ne migrent pas proprement vers v1 :
  • projects/03_groundwater_1d/project.toml.draft : cas analytique pas dispatché par hmp run (maintainer-only).
  • projects/02_nancon_watershed/run_transient_prototype.py.draft : prototype Python en attente de réécriture.
  • Vérifier régulièrement : find examples -name "*.draft".

• hmp run complet bloqué par un bug Zarr v2 schema (ZarrSchemaVersionError: expected '2', found None). Le scénario end-to-end correspondant est skippé dans tests/e2e/test_workflow_from_scratch.py:287. En attendant le fix, valider les TOML avec hmp config check puis vérifier la résolution avec hmp run --dry-run.
• 02_nancon_watershed/run_sweep_sy.toml est un draft de design documenté : sweep reste Python-only en V1 via une boucle for v in values: project.simulate(name=..., Sy=v) et n'est pas accepté par [workflow].mode.
• Les overlays 11_nancon_watershed/overlays/*.toml sont des fragments minimaux et ne valident pas en standalone. Usage : hmp run base.toml --overlay overlays/X.toml.
• Les TOMLs spécialisés (schéma propre, pas HydroModPyConfig) ne passent pas hmp config check. Ils sont consommés par leur propre runner :
  • 08_mesh_viewer/config_*.toml -> tools/mesh_bundle_viewer/.
  • 09_comparison_workflow/stability_targets.toml -> validate_stability_targets (testbed).
  • 12_calibration_network_transient_b0/configs/*.toml -> run_real_parameter_grid.py.
  • 13_transport_mf6_gwt_disv_visual_guard/cases/*.toml -> run_visual_guard.py.

Chaque projet runnable est un sous-dossier auto-contenu sous projects/ :

examples/projects/<NN_nom>/
├── README.md         # description FR détaillée
├── project.toml      # configuration valide quand le dossier est runnable
└── run*.py / *.toml  # entrées CLI ou API additionnelles

Les brouillons de conception (*.draft) sont conservés dans leur dossier source avec une mention explicite en en-tête. Ils ne doivent pas être lancés avec hmp run tant que le workflow correspondant n'est pas exposé par le dispatcher hmp run.

Les exemples qui ne s'alignent plus sur l'API actuelle ne font plus partie du parcours public. Les projets versionnés sous projects/ restent la référence.