Project#

class hydromodpy.project.Project(config, *, solver=None, headless=False, no_display=False)[source]#

Bases: object

Setup-once, run-many interface for HydroModPy simulations.

Project(config) is cheap: it validates the configuration and builds an empty runtime context. The heavy model phase (geographic, data, mesh) is built lazily on the first simulate() (or eagerly via prepare() or the per-phase verbs build_geographic / load_data / build_mesh). Run many simulations with parameter overrides; inspect past runs through runs and inputs through data.

Parameters#

configstr, Path, HydroModPyConfig, dict, or JSON str

A TOML path, a fully-built HydroModPyConfig, a dict payload, or a JSON string (auto-detected).

solverstr, optional

Flow solver name. Auto-detected from the config, defaults to "modflow_nwt".

headlessbool, optional

Disable display and postprocess runners (useful for calibration loops where generating figures per iteration is wasteful).

no_displaybool, optional

Skip display generation for later run phases.

Examples#

>>> import hydromodpy as hmp
>>> project = hmp.Project("project.toml")  
>>> run = project.simulate(Sy=0.05)  
>>> project.close()
param config:

type config:

str | Path | object | dict

param solver:

type solver:

str | None

param headless:

type headless:

bool

param no_display:

type no_display:

bool

Validate config and build an empty runtime context (cheap).

No heavy I/O: geographic delineation, data download and meshing are deferred to the first simulate() (or prepare()).

param config:

type config:

str | Path | object | dict

param solver:

type solver:

str | None

param headless:

type headless:

bool

param no_display:

type no_display:

bool

prepare()[source]#

Eagerly build the model phase (geographic, data, mesh). Returns self.

Return type:

Project

classmethod rerun(run, *, name=None, config_overrides=None, solver=None, headless=False, no_display=False, **overrides)[source]#

Launch a new simulation from a persisted run snapshot.

run remains a read-only result view; this Project-level helper owns the orchestration required to rebuild the configuration, execute the workflow, and record the new run with parent_sim_id pointing to the original simulation.

Return type:

Run

Parameters:

Parameters#

run

Persisted run to use as the reproducible source snapshot.

name

Optional name for the derived run.

config_overrides

Deep-merge patch applied to the stored config snapshot. Keys must match HydroModPyConfig top-level fields; the merged payload is validated by Pydantic, so unknown keys raise.

solver, headless, no_display

Options forwarded to the derived Project.

overrides

Flow parameter overrides forwarded to Project.simulate().

Returns#

Run

Persisted run view for the derived simulation.

Raises#

ConfigMissingError

If run has no persisted config snapshot.

PipelineError

If the derived pipeline produces no new Run, e.g. dry_run mode.

param run:

type run:

Run

param name:

type name:

str | None

param config_overrides:

type config_overrides:

Mapping[str, Any] | None

param solver:

type solver:

str | None

param headless:

type headless:

bool

param no_display:

type no_display:

bool

setup_workspace()[source]#

Bootstrap shared runtime state for the project session.

This Project-level verb prepares the workspace/catalog anchor and the shared geographic/domain/process objects used by later data, mesh, and solver phases. It is not a standalone Pipeline step; Pipeline runs get the same setup through BuildGeographicStep.

Return type:

None

build_geographic(*, reuse_dem=False)[source]#

Mark geographic/domain runtime ready and invalidate downstream state.

Parameters:

reuse_dem (bool)

Return type:

None

load_data(*, types=None)[source]#

Load the external forcings declared in [data].

Parameters:

types (list[str] | None)

Return type:

None

reload_data(*, types)[source]#

Reload a subset of data variables without touching the others.

Parameters:

types (list[str])

Return type:

None

rebuild_geographic(*, reuse_dem=False)[source]#

Rerun the geographic pipeline and invalidate the mesh.

Parameters:

reuse_dem (bool)

Return type:

None

build_mesh(**overrides)[source]#

Build the catchment mesh from the current geographic context.

Return type:

None

property config: HydroModPyConfig#

Validated configuration driving this project (read-only).

property has_mesh: bool#

True once the mesh has been built for the project.

property data_loaded: set[str]#

Set of data types already loaded for this project.

property data: ProjectDataAccessor#

Accessor for the input-data cache scoped to this project.

property runs: ProjectRunsAccessor#

Accessor for the simulation catalog scoped to this project.

property geographic: CatchmentDelineation | None#

Geographic runtime object (DEM, watershed, CRS). Triggers build.

property domain: Domain | None#

Spatial domain (mesh, layers, zones). Triggers build.

property store: Catalog | None#

Open Catalog for direct queries across all runs. Triggers build.

property time_grid: ResolvedSimulationTimeGrid | ResolvedSteadySimulationTimeGrid | None#

Resolved simulation time grid.

property loaded_data: LoadedDataContext#

Loaded data context (recharge, geology, hydrometry, etc.). Triggers build.

property workflow_context: WorkflowContext#

Mutable workflow runtime state threaded through workflow steps.

simulate(*, name=None, resume=None, from_step=None, until_step=None, dry_run=False, frozen=False, no_display=False, parallel=True, **overrides)[source]#

Run one simulation through the configured workflow and return its result.

Builds the model phase on first call (lazy), then runs the Pipeline. Flow parameter overrides (Sy, K, Ss) and the special keys thickness, first_clim, properties are applied to the plan before the Pipeline runs. Call once per point to sweep a parameter.

Return type:

Run | None

Parameters:

Parameters#

name

Optional run name persisted in the catalog.

resume

Existing run identifier to resume from the workflow journal.

from_step, until_step

Optional step bounds for partial workflow execution.

dry_run

Build and validate the workflow without executing solver work.

frozen

Require frozen input-data references.

no_display

Skip display rendering for this run.

overrides

Parameter overrides applied to the simulation plan.

Returns#

Run or None

Persisted run view for simulation workflows. Dry runs and some non-simulation workflows may return None.

Raises#

PipelineError

If a workflow step fails during execution.

SolverError

If the configured solver crashes or fails to converge.

ResumeError

If resume references an incompatible journal state.

Examples#

>>> run = project.simulate(Sy=0.05, name="probe")  
>>> run.summary()

See Also#

hydromodpy.run

Functional facade for one-off TOML execution.

hydromodpy.results.run.Run

Per-simulation result view returned by successful runs.

param name:

type name:

str | None

param resume:

type resume:

str | None

param from_step:

type from_step:

str | int | None

param until_step:

type until_step:

str | int | None

param dry_run:

type dry_run:

bool

param frozen:

type frozen:

bool

param no_display:

type no_display:

bool

param parallel:

type parallel:

bool

calibrate(*, config_path=None, parameters=None, outputs=None, objective_blocks=None, method=None, max_iter=None, save_runs=None, seed=None, phase=None, **kwargs)[source]#

Run a calibration campaign on this project.

Three modes are supported:

  • TOML mode (config_path supplied): delegate to run_calibration_cli with the given TOML path. Extra keyword arguments are forwarded.

  • Python mode (parameters supplied): build a CalibrationConfig in memory from the declarations and run the same loop.

  • Embedded mode (neither supplied): use the [calibration] section carried by this project’s config, so a fully in-memory HydroModPyConfig calibrates without re-declaring parameters.

A configuration declaring [[calibration.phases]] routes to run_staged_calibration() in TOML mode, and in embedded mode when this project was built from a file. An embedded declaration on a project built in memory is refused: each phase forks a fresh configuration from the source file, and there is none. Python mode declares its own parameter space, so the phases of the project config do not apply to it.

Parameters#

config_path

Calibration TOML path for TOML mode.

parameters

Python-mode parameter declarations.

outputs

Python-mode output declarations.

objective_blocks

Python-mode objective block declarations.

method

Optimizer method name.

max_iter

Maximum number of optimizer iterations.

save_runs

Policy controlling which trial runs remain persisted.

seed

Optional optimizer seed.

phase

Run only the named phase of a staged calibration.

kwargs

Extra options forwarded to the calibration runner.

Returns#

CalibrationReport or StagedCalibrationReport or Any

Structured calibration report when return_report is true, otherwise the runner-specific result.

Raises#

ConfigMissingError

Raised when neither config_path nor parameters is supplied.

ConfigError

Raised when phase is given and config_path cannot be read, because the answer is what the file says.

CalibrationError

Raised when [[calibration.phases]] cannot be run as declared, and when phase names a phase no configuration declares.

param config_path:

type config_path:

str | Path | None

param parameters:

type parameters:

dict[str, dict] | None

param outputs:

type outputs:

dict[str, dict] | None

param objective_blocks:

type objective_blocks:

list[dict] | None

param method:

type method:

str | None

param max_iter:

type max_iter:

int | None

param save_runs:

type save_runs:

str | None

param seed:

type seed:

int | None

param phase:

type phase:

str | None

Parameters:

  • config_path (str | Path | None)

  • parameters (dict[str, dict] | None)

  • outputs (dict[str, dict] | None)

  • objective_blocks (list[dict] | None)

  • method (str | None)

  • max_iter (int | None)

  • save_runs (str | None)

  • seed (int | None)

  • phase (str | None)

spinup(*, spinup=None, name_prefix='spinup')[source]#

Run the cyclic spin-up loop on this project.

Restarts the representative window each cycle from the previous cycle’s state until the aquifer heads and the lake stage converge. Defaults to the [spinup] section of this project’s config; pass spinup to override it in memory. Feed result.restart_from to a production run’s [flow] restart_from.

Return type:

SpinupResult

Parameters:

  • spinup (SpinupConfig | None)

  • name_prefix (str)

Parameters#

spinup

Spin-up settings override. None uses config.spinup.

name_prefix

Prefix for the per-cycle run names recorded in the catalog.

Returns#

hydromodpy.project.spinup.SpinupResult

The loop outcome (converged state, restart_from handle).

param spinup:

type spinup:

SpinupConfig | None

param name_prefix:

type name_prefix:

str

close()[source]#

Close the Catalog and clean up preprocessing files.

Return type:

None

Parameters: