Project lifecycle#

hydromodpy.project.Project is the setup-once, run-many entry point. It validates the configuration, builds the geographic/domain context, loads the declared data, generates the mesh, then exposes simulate and calibrate for repeated launches.

Construction#

Construction is cheap: __init__ validates the configuration and does no I/O. The heavy model phase builds lazily on the first Project.simulate() call (or any accessor), or eagerly via Project.prepare() and the phase verbs (Project.build_geographic(), Project.load_data(), Project.build_mesh()).

import hydromodpy as hmp

project = hmp.Project("hydromodpy.toml")

The constructor is polymorphic: it accepts a path, a HydroModPyConfig, a dict, or a JSON string (auto-detected). Project.rerun() re-launches a new simulation from a persisted run snapshot.

Lifecycle as context manager#

A project owns a DuckDB catalog handle and a few cached preprocessing files. The recommended pattern is to use it as a context manager so Project.close() runs even when an exception is raised:

import hydromodpy as hmp

with hmp.Project("hydromodpy.toml") as p:
    p.setup_workspace()
    p.build_geographic()
    p.load_data()
    p.build_mesh()
    run = p.simulate(name="baseline", Sy=0.05)

Three concerns#

The public surface of Project splits into three concerns:

  1. Factory and lifecycle: constructors, context manager, Project.close(), __repr__, and inspection properties (data, runs, config, geographic, domain, store, time_grid, loaded_data, workflow_context, has_mesh, data_loaded, __getitem__).

  2. Model phase: Project.setup_workspace(), Project.build_geographic(), Project.rebuild_geographic(), Project.load_data(), Project.reload_data(), Project.build_mesh().

  3. Run phase: Project.simulate() and Project.calibrate(). A sweep is a plain loop over Project.simulate():

    for v in values:
    project.simulate(name=f"Sy_{v}", Sy=v)

Removed in the T1 interface refactor#

The methods Project.overview, Project.compare, Project.mesh and Project.report were removed. These workflows do not benefit from setup-once state, so they now run through hmp.run() on the [workflow] mode selector:

  • overview: hmp.run(toml) with [workflow] mode="overview"

  • compare: hmp.run(toml) with [workflow] mode="compare"

  • mesh: hmp.run(toml) with [workflow] mode="mesh"

Use Project for repeated simulations and calibration; use hmp.run() for the one-shot TOML workflows above.