Architecture and Developer Guide#
The developer-facing reference for HydroModPy. Documents the package architecture, design patterns, storage layout, test layers, and the contributor recipes for extending the toolbox.
For user-facing documentation, see User Guide. For scientific notes and equations, see Theory.
Get started as a contributor#
Editable clone, pre-commit hooks, [dev,test,docs] extras,
WSL/PETSc helpers, ruff workflow, test ladder, Sphinx build
with -j auto and PlantUML setup, and the pull-request
conventions. Start here on day one.
Foundations#
How a TOML becomes a persisted run. Read this once before diving into any package.
Canonical patterns reused across the codebase: SolverAdapter, Step, Figure, DataManager, ProcessSpatial.
The top-level subpackages, the facade layers, and the public-symbol contract.
The strict 18-layer dependency matrix and the one-way import rule that every commit must respect.
DuckDB schema, Zarr stores, Parquet tables, and the basename rule that ties them together.
Recommended package-by-package reading paths through the source tree.
Pull-request gate, specialized checks, scheduled suites, and how to triage each failing GitHub check.
Per-package reference#
One focused page per top-level subpackage. Each page covers the package role, its sub-modules, the key public symbols, and the recommended reading path through the code.
Contributor recipes#
Prescriptive recipes: add a solver, a config field, a data source, a figure, a test, a CLI command, a calibration method, an exporter, or build a frontend. Start here when extending HydroModPy.
Subsystem deep dives#
Orchestration walkthrough, class diagrams, time-cycle diagrams, the comparison-workflow internals, and the testbed workflow.
MODFLOW 6, MODFLOW-NWT, Boussinesq architecture notes, plus the MODFLOW DIS and BAS contracts honoured by HydroModPy.
Catchment-conformal Gmsh meshing, structured-grid path, and the cross-mesh pivot format used by every backend.
Code-oriented architecture map plus the full operational calibration guide for adding methods and objectives.
Data planning and runtime loading, the field abstraction shared by every solver, and the external data-source policy.
Support selection, hydrography UML, and the simulated active network inventory for stream and seepage diagnostics.