[simulation] SimulationConfig

TOML section: [simulation]

Pydantic model: SimulationConfig defined in hydromodpy.simulation.planning.config.

Source on GitHub

Minimal orchestration block declared under [simulation].

Show fields: User User + Dev All

Fields

name

str default = “” user source

Human-readable simulation name and the run’s identity. When empty, derived from the TOML filename at load time (run_steady_nwt.toml -> steady_nwt); a programmatic run without a name gets a deterministic memorable slug.

Example: "cheze_baseline"

tags

list[str] factory user source

Free-text tags attached at registration; editable later via ‘hmp catalog tag’.

if_exists

str default = “version” user source

Behavior when registering a simulation whose name already exists in this project. version (default) mints the next stem.vN and keeps every run addressable; replace trashes the predecessor (restorable) and takes the name; fail raises an error.

One of: "replace" "fail" "version"

description

str default = “” user source

Short free-text description of the simulation intent.

scientific_objective

str | None default = None user source

Scientific objective used for catalog and ML stratification.

contact_email

str | None default = None user source

Contact email for the simulation metadata.

doi

str | None default = None user source

DOI or reference identifier for the simulation metadata.

study_area_name

str | None default = None user source

Human-readable study area name.

outlet_x

float | None default = None user source

Outlet X coordinate in the project CRS units.

outlet_y

float | None default = None user source

Outlet Y coordinate in the project CRS units.

time in TOML: [simulation.time]

SimulationTimeConfig | None default = None user source

Optional canonical simulation window used to align solver temporal settings and validate forcing coverage. Required for launcher flow processes and for runtime features that explicitly consume simulation-window dates.

Fields of SimulationTimeConfig

start_datetime

datetime.datetime | None default = None user source

Simulation window lower datetime bound used by launcher-level time alignment and forcing checks.

Example: "2019-01-01"

end_datetime

datetime.datetime | None default = None user source

Simulation window upper datetime bound, interpreted as inclusive. Must be greater than or equal to start_datetime.

Example: "2025-12-31"

step_value

int | float | str default = “1 month” user source

Forcing/stress-period time-step scalar or inline token ‘<value> <unit>’ (for example ‘30 day’). This controls the temporal aggregation step for forcing series (for example recharge/runoff) and the resulting stress periods.

Examples

• "1 month"

• "10 day"

step_unit

Optional[str] default = None user source

Optional forcing/stress-period base time unit used with step_value when step_value is provided without an inline unit.

"hour"

Treats step_value as whole hours, for sub-daily forcing and stress periods.

"day"

Treats step_value as whole days, the common granularity for daily forcing series.

"month"

Treats step_value as calendar months, so the step length varies by month.

"year"

Treats step_value as calendar years, so the step length varies with leap years.

substeps_per_period

int default = 1 dev source

Number of solver time steps within each stress period. Higher values improve transient accuracy (e.g., 30 for daily substeps inside monthly stress periods).

coverage_policy

str default = “error” dev source

Behavior when recharge does not fully cover the declared simulation window bounds [start_datetime, end_datetime]: ‘error’ raises, ‘warn’ emits a warning, ‘ignore’ skips checks.

One of: "error" "warn" "ignore"

process in TOML: [[simulation.process]]

type = “flow” | “transport” | “mesh” factory user source

Ordered list of requested processes loaded from [[simulation.process]]. At most one process per type is supported.

Pick a tab below: setting type selects the matching schema.

flow

TOML: [[simulation.process]] with type = "flow" – model FlowProcessConfig.

id

str required user source

User-facing identifier for the process. This id is required and must be unique within the simulation.

Example: "flow_main"

solvers

list[str] required user source

Ordered list of active flow solver names. At least one solver is required for flow processes.

transport

TOML: [[simulation.process]] with type = "transport" – model TransportProcessConfig.

id

str required user source

User-facing identifier for the process. This id is required and must be unique within the simulation.

Example: "flow_main"

solvers

list[str] required user source

Ordered list of active transport solver names. At least one solver is required for transport processes.

mesh

TOML: [[simulation.process]] with type = "mesh" – model MeshProcessConfig.

id

str required user source

User-facing identifier for the process. This id is required and must be unique within the simulation.

Example: "flow_main"

backend

Literal[‘catchment’] default = “catchment” user source

Backend used by the mesh process. Currently only ‘catchment’ is supported (delegates to the [mesh_catchment] runtime).

solvers

list[str] factory user source

Reserved for future use. Mesh processes must not declare solvers; set ‘backend’ instead.

results in TOML: [simulation.results]

ResultsConfig factory dev source

Results storage and export configuration loaded from [simulation.results]. Controls Catalog, derived variables, and automated exports.

Fields of ResultsConfig

persistence in TOML: [simulation.results.persistence]

PersistenceConfig factory user source

Simulation-run persistence switch passed to the result catalog (DuckDB rows, Zarr fields, Parquet tables).

Fields of PersistenceConfig

save_catalog

bool default = True user source

Persist DuckDB rows (simulations, parameters, metrics, calibration_iterations). When False, catalog writes are skipped.

save_zarr

bool default = True user source

Persist per-simulation field arrays (head, concentration, derived) into the Zarr store.

save_parquet

bool default = True user source

Persist per-simulation tabular outputs (timeseries, budgets, mass_balance) as Parquet files.

compression

str default = “zstd” dev source

Codec DECLARED for Zarr field arrays and Parquet tables. The writers carry their own codec (zstd) and do not read this field, so changing it changes nothing today; it records the intent and is the field a writer would read once the choice is threaded through.

One of: "none" "zstd" "lz4" "gzip" "snappy"

compression_level

int default = 5 dev source

Compression level DECLARED for those writers. Same as the codec: core/io/parquet.py and core/io/geoparquet.py hold level 5 and do not read this field. The default says 5 rather than 3 so the declaration at least matches the bytes actually written.

keep_solver_files

bool default = False dev source

Keep raw solver output files (.hds, .cbc, .lst) after ingestion.

derived in TOML: [simulation.results.derived]

DerivedConfig factory user source

Derived variable computation toggles.

Fields of DerivedConfig

watertable_elevation

bool default = False user source

Persist water-table elevation (uppermost saturated layer) as a Zarr field. Off by default: figures recompute it on the fly from the stored head.

watertable_depth

bool default = False user source

Persist water-table depth (surface minus water-table elevation) as a Zarr field. Off by default: recomputed on the fly from head at render time.

seepage_areas

bool default = False user source

Persist the seepage mask (water table >= surface elevation) as a Zarr field. Off by default: recomputed on the fly from head at render time.

release_flux

bool default = False dev source

Positive total groundwater release flux from drains and surface excess.

accumulation_flux

bool default = False dev source

Drain flux routed on the drainage network.

release_accumulation_flux

bool default = False dev source

Release flux routed on surface drainage paths.

outflow_drain

bool default = False dev source

Positive per-cell drain outflow summed over layers.

concentration_seepage

bool default = False dev source

Concentration at seepage cells only. Requires transport.

mass_seepage

bool default = False dev source

Mass flux at seepage cells. Requires transport + budget.

mass_accumulated

bool default = False dev source

Cumulative mass_seepage over time.

budget in TOML: [simulation.results.budget]

BudgetConfig factory user source

Budget extraction configuration.

Fields of BudgetConfig

spatial_fields

bool default = False user source

Persist per-cell budget fields (DRN, RCH, etc.) into Zarr. Off by default: the lumped per-component budget still lands in the budgets table, and the catchment scalars (discharge, well pumping) are derived from it. Turn it on to map or export a per-cell flux, at the cost of the heaviest arrays a run can hold.

rng_seed

int | None default = None user source

Master RNG seed for the simulation. When set, every stochastic consumer (mesh point sampling, synthetic forcing, …) derives its own deterministic sub-seed via hydromodpy.core.rng.RngManager. Persisted in runs_environment.rng_seed so the run can be re-executed from the catalog snapshot.

Starter TOML snippet

Click to expand a copy-pasteable [simulation] TOML skeleton

Copy this block into your project.toml and uncomment the lines you want to set. Sub-tables ([parent.subfield]) appear in the order Pydantic expects them.

[simulation]
# name = ""
# tags = ...  # uses factory default
# if_exists = "version"
# description = ""
# scientific_objective = ...  # default = None
# contact_email = ...  # default = None
# doi = ...  # default = None
# study_area_name = ...  # default = None
# outlet_x = ...  # default = None
# outlet_y = ...  # default = None
# rng_seed = ...  # default = None

[simulation.time]
# start_datetime = ...  # default = None
# end_datetime = ...  # default = None
# step_value = "1 month"
# step_unit = ...  # default = None

[[simulation.process]]
# id = ""  # REQUIRED
# type = "flow"
# solvers = []  # REQUIRED

Cases using this section

Validation gallery cases that reference fields from this section:

• Boussinesq Circular-Island Piecewise-K 2D

• Brutsaert Recession Validation: Thin Nonlinear Aquifer

• Brutsaert Recession Validation: Deep Linearized Aquifer

• Dupuit Circular-Island Ocean 2D

• Late-Time Unconfined Pumping 2D

• Linearized Unconfined Boundary Piecewise 1D

• Linearized Unconfined 1D Boundary Step

• Linearized Unconfined 1D Periodic Recharge

• Linearized Unconfined 1D Recharge Step

• Linearized Unconfined 1D Recharge Step (Deep Aquifer)

Entity-relationship diagram

Click to zoom and pan. Press Esc or click outside to close.