User Guide#
This section groups the operational documentation that sits after the first quickstart and before the low-level developer/API reference.
Use it when you already know how to launch HydroModPy, but need to understand which workflow to run, how projects and runs are organized, how to compare outputs, or where to find the scientific and architecture details behind a topic.
If this is your first visit, start with Getting Started instead. If you want equations or implementation diagrams, jump directly to Theory or Architecture and Developer Guide.
Core concepts#
Configuration reference
The TOML-first public API of HydroModPy. Every section validated by
HydroModPyConfig with fields, defaults, types, and the JSON
Schema explorer.
Workflow families and driving modes
Overview, simulation, testbed, calibration, and comparison workflows (with the regional_lab profile for site-catalog campaigns), plus the seven driving modes (CLI TOML, JSON, Python, notebooks, and low-level primitives).
Workspace layout
Where HydroModPy stores inputs, caches, generated artifacts, runs, and reports.
Project vs run
The distinction between reusable project state and one persisted model execution.
Workspace-first organization#
The cleanest long-term organization is to use the workspace layout as the backbone, then describe workflows as operations that populate parts of that workspace.
Read the documentation in this order when you want to avoid duplicates:
Workspace Layout explains the durable folders: data cache, project TOMLs, generated child configs, runs, outputs, reports, and gallery evidence.
Workflow Reference explains which operation writes to those folders: overview for data identity cards, simulation for one persisted run, testbed for controlled variants (including regional_lab profile campaigns), calibration for repeated candidate runs, and comparison for shared-case solver contrasts.
Topic guides such as Testbed Workflow, Comparison Workflow, and Calibration Workflow are the single source of truth for each workflow family. They link out to theory, gallery, and architecture rather than re-describing the workflow walkthroughs.
The capability gallery should remain the evidence layer: stable figures, metrics, and reproducible examples that illustrate the workspace artifacts.
This structure keeps workspace layout as the index of where things live,
workflow pages as the index of what operation creates them, and topic
pages as cross-cutting reading maps.
Topic guides#
Mesh diagnostics
Mesh-only runs via simulation with [[simulation.process]] type=mesh,
testbed-based discretization studies, refinement policies, and the
route to mesh scientific and architecture pages.
Comparison workflows
How to run shared-case comparisons and how to read their generated metrics and figures.
Calibration workflows
Entry points for inverse problems, calibration architecture, and calibration benchmark pages.
Solvers
Process-first map of flow, transport, postprocess, and display solvers, with the trade-offs between MODFLOW-NWT, MODFLOW 6, Boussinesq, mesh families, and the XT3D option.
Capability and API-oriented guides#
CLI reference
Registered top-level commands, workflow flags, and nested command families.
Data loading
Retrieval workflow, provider matrix, local custom data conventions, cache inspection, lockfiles, and frozen runs.
Results and exports
How runs are registered, queried, inspected, packaged, and exported to external formats.
Figure catalog
Registered figure names, expected result families, and rendering entry points for reports and scripts.
Catchment HTML reports
The catchment_report.toml contract and the standard
hmp report catchment commands for building watershed report pages.
Project API
Python lifecycle for workspace setup, geographic preprocessing, data, mesh, run execution, comparison, calibration, and cleanup.
Theory
Method notes, solver equations, and modelling assumptions backing each workflow: foundations, hydrology, mesh, calibration, and solvers.
Reading outputs#
Use these pages once you have generated or opened result pages:
How To Read Gallery, Comparison, and Validation Pages explains how to read gallery, comparison, and validation pages.
Comparison Output Reading Order gives the reading order for comparison artifacts.