Complete annotated TOML reference#

Every TOML section with its direct fields, defaults and types. Sub-models are linked back to their per-section page.

Tip

The blocks below produce a structurally valid TOML skeleton. Required and factory fields are commented out: uncomment and replace the placeholder before running the project. Lines tagged # example: come from Field(examples=...) declarations.

[data] (DataManagersConfig)

See [data] DataManagersConfig for the full description.

[data]
# EPSG code or WKT string of the project coordinate reference system. When set, all loaded data is reprojected to this CRS. Example: 'EPSG:2154' (Lambert-93).
# project_crs = ...  # default = None
# Ordered list of data-manager types explicitly requested in [data]. The launcher may append inferred types deduced from other sections (for example domain.zone_ids, flow.active_bc). Allowed values: 'dem', 'etp', 'geology', 'humidity', 'hydrography', 'hydrometry', 'intermittency', 'oceanic', 'piezometry', 'precipitation', 'radiation', 'recharge', 'runoff', 'soil_moisture', 'temperature', 'water_quality', 'wind'.
# types = ...  # uses factory default
# Policy applied when the planner infers types not explicitly listed in data.types. 'warn': keep inferred types and continue even if data.<type> is missing. 'strict': raise when an inferred type has no explicit data.<type> section (except geology, which can use its default typed config).
inference_mode = "warn"
# DEM configuration used when 'dem' is listed in data.types.
# dem = ...  # default = None
# Geology configuration used when 'geology' is listed in data.types.
# geology = ...  # default = None
# Hydrography configuration (stream network vector data).
# hydrography = ...  # default = None
# Hydrometry configuration (discharge time-series).
# hydrometry = ...  # default = None
# Intermittency configuration (ONDE stream flow-state observations).
# intermittency = ...  # default = None
# Oceanic configuration used when 'oceanic' is listed in data.types.
# oceanic = ...  # default = None
# Piezometry configuration (groundwater level time-series).
# piezometry = ...  # default = None
# Water quality configuration (physico-chemical parameters).
# water_quality = ...  # default = None
# Recharge configuration (drainage / soil infiltration time series).
# recharge = ...  # default = None
# Runoff configuration (surface runoff time series).
# runoff = ...  # default = None
# Precipitation configuration (liquid and solid precipitation).
# precipitation = ...  # default = None
# ETP configuration (potential evapotranspiration).
# etp = ...  # default = None
# Temperature configuration (air temperature time series).
# temperature = ...  # default = None
# Wind configuration (wind speed time series).
# wind = ...  # default = None
# Humidity configuration (relative humidity time series).
# humidity = ...  # default = None
# Radiation configuration (atmospheric and visible radiation).
# radiation = ...  # default = None
# Soil moisture configuration (soil moisture index).
# soil_moisture = ...  # default = None

[flow] (FlowConfig)

See [flow] FlowConfig for the full description.

[flow]
# Optional nonlinear runtime backend hint used by the Boussinesq solver implementation. Other flow solvers may ignore this field.
# example: runtime_backend = "local"
# example: runtime_backend = "scipy_sparse"
runtime_backend = "local"
# Optional Boussinesq surface-interaction closure selector. 'regularized_partition' uses the Marcais-style q_ex = G_r(theta) R(balance) law; 'complementarity' uses the mixed PETSc q_ex-perp-(z_top-h) formulation; 'vi_obstacle' uses the experimental PETSc head-only VI obstacle formulation; 'auto' keeps the historical backend-dependent default.
# example: surface_interaction_model = "auto"
# example: surface_interaction_model = "regularized_partition"
surface_interaction_model = "auto"
# Optional override for the nonlinear iteration budget used by the Boussinesq runtime backend.
# runtime_max_iterations = ...  # default = None
# Optional override for the infinity-norm residual tolerance used by the Boussinesq runtime backend.
# runtime_tol_residual_inf = ...  # default = None
# Optional override for the infinity-norm state-update tolerance used by Boussinesq backends that track it.
# runtime_tol_state_update_inf = ...  # default = None
# Fixed number of Backward-Euler substeps per stress period for the experimental PETSc VI obstacle runtime. Rate-based forcing values are kept unchanged on each substep.
vi_substeps_per_period = 1
# When true, retry a failed PETSc VI obstacle stress period with increasing substep counts.
vi_substep_on_failure = false
# Maximum number of PETSc VI obstacle substeps allowed for adaptive failure retries.
# vi_max_adaptive_substeps = ...  # default = None
# Fixed PETSc TS Backward-Euler steps per stress period for the experimental TS VI obstacle runtime.
ts_vi_steps_per_period = 4
# Enable experimental PETSc TS adaptivity for the TS VI obstacle runtime.
ts_vi_adapt = false
# Minimum TS VI time-step as a fraction of the stress-period length.
ts_vi_dt_min_fraction = 0.015625
# Maximum TS VI time-step as a fraction of the stress-period length.
ts_vi_dt_max_fraction = 0.25
# PETSc TS type for the experimental TS VI obstacle runtime.
ts_vi_type = "beuler"
# PETSc SNES type for the experimental TS VI obstacle runtime.
ts_vi_snes_type = "vinewtonrsls"
# Ordered list of flow-parameter identifiers used to build runtime parameters (for example ['K', 'Ss', 'Sy']).
# example: param_list = ["K", "Sy", "Ss"]
# param_list = ...  # uses factory default
# Mapping of flow-parameter identifiers to native FieldParamConfig payloads.
# param = ...  # uses factory default
# Validated flow initial-condition structure parsed from [flow.ic]. Stored as FlowInitialConditions(h=FlowInitialCondition).
# ic = ...  # uses factory default
# Mapping of flow boundary-condition payloads parsed from ``[flow.bc]``.  **Supported TOML sections**  - ``[flow.bc.dirichlet.<id>]`` where ``<id>`` is one of ``ocean``, ``stream``, ``north_side``, ``south_side``, ``east_side``, ``west_side`` - ``[flow.bc.cauchy.drainage]`` - ``[flow.bc.robin.drainage]`` - ``[flow.bc.<custom_id>]`` for generic payloads  **Common keys**  - ``value`` (required): numeric or ``'<value> <unit>'`` - ``application_domain``: optional for dirichlet when ``<id>`` implies it (e.g. ``west_side`` -> ``'west side'``); required for ``cauchy`` and ``robin`` drainage  **Allowed application_domain values:** ``top``, ``north side``, ``south side``, ``east side``, ``west side``.  **Default units:** ``m`` for dirichlet, ``m2/s`` for cauchy/robin.  **Cauchy vs Robin:** both map to the same MODFLOW ``DRN`` package; the distinction only matters for the Boussinesq solver, which uses two different surface-interaction closures (``cauchy`` for the linear formulation ``q = C(h - h_ref)``, ``robin`` for the regularized partition / complementarity variants selected by ``flow.surface_interaction_model``).
# bc = ...  # uses factory default
# Typed sinks/sources payload (for example pumping wells).
# sinks_sources = ...  # uses factory default
# Explicitly activated sink/source names for this flow run. Allowed values: 'recharge', 'wells', 'etp'. Boussinesq currently rejects 'etp' at solver-contract validation. An empty list means no sink/source package is assembled by the solver.
# example: active_sinks_sources = ["recharge"]
# example: active_sinks_sources = ["recharge", "wells"]
# example: active_sinks_sources = ["etp"]
# active_sinks_sources = ...  # uses factory default
# Explicitly activated boundary-condition ids for this flow run. Allowed values are the canonical ids declared in the flow boundary-condition registry: 'ocean', 'stream', 'north_side', 'south_side', 'east_side', 'west_side', 'drainage'. An empty list means no boundary-condition package is assembled by the solver.
# example: active_bc = ["ocean"]
# example: active_bc = ["west_side", "east_side", "drainage"]
# active_bc = ...  # uses factory default
# Global flow simulation regime used by solvers consuming [flow] (steady or transient).
# example: flow_regime = "steady"
# example: flow_regime = "transient"
flow_regime = "transient"
# For transient flow, mark the first solver stress period as steady-state. Ignored for steady flow, where all solver periods are steady.
# example: first_period_steady = true
# example: first_period_steady = false
first_period_steady = true

[mesh_catchment] (MeshCatchmentConfig)

See [mesh_catchment] MeshCatchmentConfig for the full description.

[mesh_catchment]
# Meshing compliance target. 'geology_only' conforms the mesh to geology interfaces only, 'rivers_only' conforms the mesh to river traces only, and 'geology_rivers' enforces both sets of constraints in one mesh.
constraints_mode = "geology_rivers"
# Optional `.msh` output path for the generated planar mesh. When omitted, the launcher writes the mesh to `results_stable/mesh/mesh_catchment.msh` inside the active catchment workspace in standard layout, or directly to `workspace.project_root/mesh_catchment.msh` when `output_layout='flat'` is used.
# output_mesh = ...  # default = None
# Optional JSON sidecar path for QA metrics, cleaned-input diagnostics, and summary metadata describing the generated mesh. When omitted, the launcher writes it next to the default mesh output.
# output_summary_json = ...  # default = None
# Optional overview figure path. Use it when you want a quick visual QA artifact showing the support domain, geology zones, river constraints, and final mesh footprint.
# output_figure = ...  # default = None
# Optional regional overview figure path. When omitted but output_figure is set, the launcher writes a second figure next to the main one with suffix `_regional` to show where the catchment sits on the full DEM.
# output_figure_regional = ...  # default = None
# If true, generate the overview figure artifacts when figure output paths are configured. Set it to false to skip figure creation entirely, even in batch mode where default filename patterns are present.
figures_enabled = true
# If true, export the solver-exchange mesh bundle next to the generated mesh. Set it to false for profiling or mesh-only runs that do not need bundle metadata. Downstream solvers that require runtime mesh support may fail without this bundle.
export_exchange_bundle = true
# Pixel density used when rendering the main mesh overview figure. Increase it when you need to inspect mesh edges and constraints more closely in the saved PNG.
figure_dpi = 300
# Pixel density used when rendering the regional overview figure. Keep it lower than figure_dpi when you want detailed local mesh inspection without making the regional PNG too heavy.
figure_regional_dpi = 220
# Dedicated-launcher output layout. Use 'standard' to keep final mesh artifacts under `results_stable/mesh/`, or 'flat' to write final mesh artifacts directly under `workspace.project_root` while keeping intermediate runtime folders out of that final directory.
output_layout = "standard"
# If true, open the generated overview figure interactively at the end of the run. Keep it false for batch or headless execution.
show_plot = false
# Control what happens to intermediate geographic preprocessing artifacts after the mesh run. Use 'keep' to preserve the canonical `results_stable/geographic` and `results_stable/demcorrecflow` folders, or 'cleanup' to delete them at the end of the dedicated mesh launcher once the mesh outputs and exchange bundle have been written.
geographic_outputs_mode = "keep"
# River-constraint section used when constraints_mode includes rivers. The default behavior is to reuse the in-memory river trace already built by the geographic pipeline.
# rivers = ...  # uses factory default
# Optional geology support used when constraints_mode includes geology. This section defines which polygon source represents lithological zones and how those polygons should be interpreted before conformal meshing. Validated through the geology data-source Protocol; stored as a normalized mapping.
# geology = ...  # default = None
# Optional watershed-boundary mesh constraint. Enable it to force a conformal mesh line along the catchment boundary while keeping the geology zonation represented on the whole support domain.
# watershed_boundary = ...  # uses factory default
# Optional hydraulic-property tables keyed by geology zones. The launcher projects geology on the mesh and exports per-cell conductivity/storage values as weighted averages of geology fractions.
# hydraulic_properties = ...  # default = None
# Effective support domain to mesh. The default `geographic_box_buffer` mode reuses the catchment bounding box plus geographic buffer prepared during delineation, which is usually the right support for mono-catchment meshing.
# domain = ...  # uses factory default
# Low-level Gmsh sizing and cleanup parameters controlling cell size, simplification, and interface refinement. Defaults are valid, but project examples typically override them to target a desired number of cells.
# zone_meshing = ...  # uses factory default

[calibration] (CalibrationConfig)

See [calibration] CalibrationConfig for the full description.

[calibration]
# Optimization method. Optuna is installed by default; install the calibration extra for cma_es and Optuna's cmaes sampler.
method = "grid"
# Maximum number of calibration iterations.
max_iter = 100
# Number of suggestions drawn per ask (for parallel optimizers).
batch_size = 1
# Number of trials evaluated concurrently inside one batch via a thread pool. parallel=1 keeps the legacy sequential loop.
parallel = 1
# Random seed for reproducibility.
# seed = ...  # default = None
# How much to persist per iteration: - 'none': 1 DuckDB row per iteration, no Zarr. - 'best_n': same + promote top N to full simulations after the loop. - 'all': every iteration becomes a full simulation (Zarr included).
save_runs = "none"
# Number of top iterations to promote when save_runs='best_n'.
save_best_n = 10
# Enable params_hash content-addressable cache.
use_cache = true
# Skip Parquet/Zarr writes for lumped models (GR4J, ...) and read simulated series from the per-trial RAM cache instead. Only the promoted runs go through the catalog write path.
lightweight_extraction = true
# Metric key used by the default ScalarObjective.
objective = "nse"
# Observed variable (for ObservationSet).
variable = "head"
# Extra keyword arguments forwarded to the optimizer adapter.
# optimizer_kwargs = ...  # uses factory default
# Per-parameter declarations (bounds, transform, prior, path).
# parameters = ...  # uses factory default
# Named observables extracted from each candidate run.
# outputs = ...  # uses factory default
# Weighted blocks making up a composite objective. When empty, a single implicit block is built from 'objective' and 'variable'.
# objective_blocks = ...  # uses factory default
# 'none' skips component metrics; 'summary' keeps block totals; 'full' also stores per-block raw and normalized costs.
persist_iteration_detail = "summary"
# Persist the candidate distribution alongside the session.
persist_model_distribution = false
# Replay the best candidate with full outputs after the loop.
rerun_best_with_outputs = false
# Write a standalone override TOML for each candidate under 'candidates_root' so runs can be replayed later.
materialize_candidates = false
# Directory for per-candidate overlay TOMLs. Required when materialize_candidates is True.
# candidates_root = ...  # default = None
# Single switch governing every persistence sink (catalog, Zarr, Parquet, lockfile) for calibration outputs.
# persistence = ...  # uses factory default