[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.

run_id

str default = “” user source

Run identifier used as the output subfolder name under results_simulations/. When empty, derived from the TOML filename at load time (e.g. run_steady_nwt.toml -> steady_nwt).

Example: "steady_nwt"

on_collision

Literal[‘replace’, ‘fail’, ‘version’] default = “replace” user source

Behavior when registering a simulation whose name already exists in this project. replace soft-replaces (the previous sim keeps its UUID but loses its name), fail raises an error, version auto-suffixes name.v2, name.v3 …

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[Literal[‘hour’, ‘day’, ‘month’, ‘year’]] default = None user source

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

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

Literal[‘error’, ‘warn’, ‘ignore’] 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.

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.flow] – model FlowProcessConfig (set type = "flow").

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.transport] – model TransportProcessConfig (set type = "transport").

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.mesh] – model MeshProcessConfig (set type = "mesh").

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 SimulationCatalog, 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, lockfile).

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.

save_lock

bool default = True user source

Generate and refresh the hydromodpy.lock reproducibility manifest after data ingestion.

compression

Literal[‘none’, ‘zstd’, ‘lz4’, ‘gzip’, ‘snappy’] default = “zstd” dev source

Codec used for Zarr field arrays and Parquet tables. ‘none’ disables compression.

compression_level

int default = 3 dev source

Compression level (codec-dependent). Ignored when compression=’none’.

keep_solver_files

bool default = False dev source

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

solver_scratch

str default = “.solver_scratch” dev source

Directory for temporary solver files, relative to the project. Use an absolute path (e.g. /scratch/$USER/hmp) for HPC.

derived in TOML: [simulation.results.derived]

DerivedConfig factory user source

Derived variable computation toggles.

Fields of DerivedConfig

watertable_elevation

bool default = True user source

Compute water-table elevation from uppermost saturated layer.

watertable_depth

bool default = True user source

Compute water-table depth (surface minus water-table elevation).

seepage_areas

bool default = True user source

Identify seepage areas where water table >= surface elevation.

groundwater_flux

bool default = False dev source

Magnitude of inter-cell flow (right/front/lower face). Volumetric.

release_flux

bool default = True dev source

Positive total groundwater release flux from drains and surface excess.

accumulation_flux

bool default = True 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 = True 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 dev source

Budget extraction configuration.

Fields of BudgetConfig

spatial_fields

bool default = True dev source

Extract per-cell budget fields (DRN, RCH, etc.) into Zarr.

export in TOML: [simulation.results.export]

ExportConfig factory user source

Automated export configuration.

Fields of ExportConfig

netcdf

bool default = False user source

Export to NetCDF-4/UGRID.

csv_timeseries

bool default = True user source

Export time series to CSV.

vtu

bool default = False dev source

Export to VTU (ParaView).

geotiff

bool default = False dev source

Export to GeoTIFF.

shapefile

bool default = False dev source

Export to Shapefile.

output_dir

str | None default = None dev source

Output directory for exports. Defaults to project results folder.

variables in TOML: [simulation.results.export.variables]

ExportVariablesConfig factory user source

Which variables to include in exports.

Fields of ExportVariablesConfig

head

bool default = True user source

Export head field.

concentration

bool default = False user source

Export concentration field.

budget

bool default = False dev source

Export spatial budget fields.

pathlines

bool default = False dev source

Export pathline data.

derived

bool default = True user source

Export derived variables (watertable_depth, seepage_mask, etc.).

resolution

float | None default = None dev source

GeoTIFF pixel size in CRS units for toggle exports. Auto-derived from the grid when omitted.

artifacts in TOML: [[simulation.results.export.artifacts]]

list[ExportSpec] factory dev source

Explicit export artifacts: full control over variable, format, timestep and destination, beyond the format toggles above.

Fields of ExportSpec

var

str | list[str] required user source

Variable name, list of names, or ‘*’ (all timeseries, csv only).

dest

Path required user source

Output file path. Its extension can imply ‘fmt’.

fmt

ExportFormat | None default = None user source

Output format. Inferred from the ‘dest’ extension when omitted.

time

Union[int, list[int], Literal[‘first’, ‘last’, ‘all’], NoneType] default = None user source

Timestep selector: index, list of indices, ‘first’, ‘last’, ‘all’, or None (per-format default: all timesteps for netcdf, last for rasters).

layer

int | None default = None dev source

Layer index for 3D fields.

resolution

float | None default = None dev source

GeoTIFF pixel size in CRS units. Auto-derived from the grid when omitted.

crs

str | None default = None dev source

Output CRS (e.g. ‘EPSG:2154’). Auto-filled from the simulation when omitted.

nodata

float default = -9999.0 dev source

Nodata fill value for raster formats.

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 = ""
# run_id = ""
# on_collision = "replace"
# 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.