[mesh_catchment] MeshCatchmentConfig

TOML section: [mesh_catchment]

Pydantic model: MeshCatchmentConfig defined in hydromodpy.spatial.mesh.config.main.

Source on GitHub

Top-level launcher contract for one mono-catchment meshing run.

Show fields: User User + Dev All

Fields

constraints_mode

str default = “geology_rivers” user source

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.

One of: "geology_only" "rivers_only" "geology_rivers"

output_mesh

Optional[str] default = None dev source

Optional .msh output path for the generated planar mesh. When omitted, the launcher writes the mesh to .hmp/scratch/_preprocessing/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_summary_json

Optional[str] default = None dev source

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_figure

Optional[str] default = None dev source

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_regional

Optional[str] default = None dev source

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.

figures_enabled

bool default = True user source

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.

export_exchange_bundle

bool default = True user source

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.

cache

bool default = False user source

If true, reuse a previously generated mesh when its inputs (domain geometry, river constraint, lake/dam refinement, mesh and delineation configuration) are unchanged, instead of regenerating it. Gmsh is not reproducible run to run (it reseeds from the system clock), so regeneration yields a different mesh and makes results and calibration objectives irreproducible; caching pins the mesh. Default off (regenerate every run). See hydromodpy.spatial.mesh.mesh_cache.

figure_dpi

int default = 300 user source

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_regional_dpi

int default = 220 user source

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.

output_layout

str default = “standard” user source

Dedicated-launcher output layout. Use ‘standard’ to keep final mesh artifacts under .hmp/scratch/_preprocessing/mesh/, or ‘flat’ to write final mesh artifacts directly under workspace.project_root while keeping intermediate runtime folders out of that final directory.

One of: "standard" "flat"

show_plot

bool default = False user source

If true, open the generated overview figure interactively at the end of the run. Keep it false for batch or headless execution.

geographic_outputs_mode

str default = “keep” dev source

Control what happens to intermediate geographic preprocessing artifacts after the mesh run. Use ‘keep’ to preserve the canonical .hmp/scratch/_preprocessing/geographic and .hmp/scratch/_preprocessing/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.

One of: "keep" "cleanup"

rivers in TOML: [mesh_catchment.rivers]

MeshCatchmentRiversConfig factory user source

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.

Fields of MeshCatchmentRiversConfig

source

str default = “geographic_features” user source

Origin of the river constraints used to force mesh edges along the river network. Use ‘geographic_features’ for the in-memory river trace produced by geographic preprocessing, or ‘file’ to reload a vector river dataset from disk.

One of: "geographic_features" "file"

path

Optional[str] default = None user source

Vector file path used only when source=’file’. The path may be absolute or relative to the TOML location and should point to a line dataset describing the river centerlines to honor during meshing.

clip_to_domain

bool default = True user source

If true, clip the river trace to the effective meshing support before sending it to Gmsh. Keep this enabled in most workflows to avoid constraining the mesh with segments that lie outside the chosen domain or scope.

min_segment_length

Any default = 0.0 user source

Minimum retained river segment length, in projected metres after reprojection. Use this to discard tiny residual segments created by clipping or noisy hydrography that would only add mesh complexity without hydraulic meaning.

snap_tolerance

Any default = 0.0 user source

Reserved snapping tolerance, in projected metres, for possible future cleanup of nearly coincident river vertices. The current workflow stores the value in the launcher contract but does not apply an additional snapping pass.

geology in TOML: [mesh_catchment.geology.<id>]

dict[str, Any] | None default = None user source

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.

watershed_boundary in TOML: [mesh_catchment.watershed_boundary]

MeshCatchmentWatershedBoundaryConfig factory user source

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.

Fields of MeshCatchmentWatershedBoundaryConfig

enabled

bool default = False user source

If true, inject the watershed boundary as one dedicated linear constraint in addition to geology and/or river constraints.

boundary_refinement_distance

Optional[Any] default = None dev source

Optional influence distance, in projected metres, used for the watershed-boundary refinement family. When omitted, the mesher derives one conservative distance from the boundary extent.

smoothing in TOML: [mesh_catchment.watershed_boundary.smoothing]

MeshCatchmentWatershedBoundarySmoothingConfig factory user source

Optional regularization controls applied before the watershed boundary is converted to a linear constraint.

Fields of MeshCatchmentWatershedBoundarySmoothingConfig

enabled

bool default = False user source

If true, apply the smoothing controls below before converting the watershed boundary into one linear constraint.

distance

Optional[Any] default = None dev source

Optional regularization tolerance, in projected metres, used to simplify the watershed boundary at roughly the target internal mesh scale before it is injected as a linear mesh constraint. When omitted, the mesher reuses zone_meshing.global_size.

river_buffer_distance

Optional[Any] default = None dev source

Optional protective buffer around river traces, in projected metres, merged into the boundary-support polygon before smoothing so the final watershed boundary stays slightly outside river corridors near the basin edge.

outer_bias_distance

Optional[Any] default = None dev source

Optional outward bias, in projected metres, applied after smoothing so the final watershed boundary remains slightly englobing instead of cutting back toward the raw catchment contour.

outside_coarsening in TOML: [mesh_catchment.watershed_boundary.outside_coarsening]

MeshCatchmentWatershedOutsideCoarseningConfig factory user source

Optional coarse-background size field applied outside the regularized watershed while keeping the geology partition unchanged.

Fields of MeshCatchmentWatershedOutsideCoarseningConfig

enabled

bool default = False user source

If true, add one regional mesh-size field that keeps the current background size inside the watershed and coarsens the mesh outside it.

size_factor

float default = 2.0 dev source

Multiplicative factor applied to zone_meshing.global_size outside the watershed. Use 2.0 for an outside background roughly twice as coarse as the internal baseline.

transition_distance

Optional[Any] default = None dev source

Optional transition width, in projected metres, used to ramp from the internal background size to the coarser outside size away from the watershed boundary.

grid_resolution

Optional[Any] default = None dev source

Optional structured-grid resolution, in projected metres, used to discretize the outside coarsening field. When omitted, the mesher reuses zone_meshing.global_size.

geology_conformity in TOML: [mesh_catchment.watershed_boundary.geology_conformity]

MeshCatchmentWatershedGeologyConformityConfig factory user source

Optional control of where geology remains conformal relative to the watershed. Keep the default full_domain mode to preserve the current behavior.

Fields of MeshCatchmentWatershedGeologyConformityConfig

mode

str default = “full_domain” user source

Control where geology remains conformal. Use ‘full_domain’ to keep the current behavior, or ‘buffered_watershed_envelope’ to keep geology interfaces active only inside one buffered envelope around the regularized watershed, without creating one strict partition boundary on that envelope.

One of: "full_domain" "buffered_watershed_envelope"

buffer_distance

Optional[Any] default = None dev source

Optional outward buffer, in projected metres, added around the regularized watershed before selecting where geology interfaces remain active. When omitted in buffered_watershed_envelope mode, the mesher reuses zone_meshing.global_size.

hydraulic_properties in TOML: [mesh_catchment.hydraulic_properties]

MeshCatchmentHydraulicPropertiesConfig | None default = None user source

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.

Fields of MeshCatchmentHydraulicPropertiesConfig

conductivity in TOML: [mesh_catchment.hydraulic_properties.conductivity]

MeshCatchmentHydraulicConductivity | None default = None user source

Optional hydraulic-conductivity mapping by geology key. When provided, the bundle exports one hydraulic_conductivity_m_s value per cell.

Fields of MeshCatchmentHydraulicConductivity

values_source

str default = “inline” user source

Source of the geology-key to property mapping. Use ‘inline’ for TOML dictionaries or ‘csv’ for an external table.

One of: "inline" "csv"

values in TOML: [mesh_catchment.hydraulic_properties.conductivity.values.<id>]

dict[str, object] | None default = None user source

Inline mapping from geology zone key to property value. Keys must match the normalized zone_key values exported by the geology loader.

values_csv_file

Optional[str] default = None dev source

CSV file used when values_source=’csv’. Relative paths are resolved from the launcher TOML directory.

csv_key_column

str default = “zone_key” dev source

CSV column containing geology zone keys.

csv_value_column

str default = “value” dev source

CSV column containing numeric property values.

default_value

object | None default = None user source

Fallback value applied when one geology zone has no explicit mapping. Leave empty to keep exported cell values undefined for unmapped zones.

unit

str default = “m/s” dev source

Input unit used by conductivity values. Exported bundle values are always converted to m/s.

storage_coefficient in TOML: [mesh_catchment.hydraulic_properties.storage_coefficient]

MeshCatchmentStorageCoefficient | None default = None user source

Optional storage-coefficient mapping by geology key. When provided, the bundle exports one storage_coefficient value per cell.

Fields of MeshCatchmentStorageCoefficient

values_source

str default = “inline” user source

Source of the geology-key to property mapping. Use ‘inline’ for TOML dictionaries or ‘csv’ for an external table.

One of: "inline" "csv"

values in TOML: [mesh_catchment.hydraulic_properties.storage_coefficient.values.<id>]

dict[str, object] | None default = None user source

Inline mapping from geology zone key to property value. Keys must match the normalized zone_key values exported by the geology loader.

values_csv_file

Optional[str] default = None dev source

CSV file used when values_source=’csv’. Relative paths are resolved from the launcher TOML directory.

csv_key_column

str default = “zone_key” dev source

CSV column containing geology zone keys.

csv_value_column

str default = “value” dev source

CSV column containing numeric property values.

default_value

object | None default = None user source

Fallback value applied when one geology zone has no explicit mapping. Leave empty to keep exported cell values undefined for unmapped zones.

domain in TOML: [mesh_catchment.domain]

kind = “bbox” | “polygon” | “vector” | “geographic_box_buffer” | “geographic_watershed” | “geographic_watershed_box” factory user source

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.

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

bbox

TOML: [mesh_catchment.domain] with kind = "bbox" – model ZoneMeshingDomainBBox.

bbox

list[float] required user source

polygon

TOML: [mesh_catchment.domain] with kind = "polygon" – model ZoneMeshingDomainPolygon.

coordinates

list[list[float]] required user source

vector

TOML: [mesh_catchment.domain] with kind = "vector" – model ZoneMeshingDomainVector.

path

str required user source

id_field

Optional[str] default = None user source

Optional vector attribute field name used to filter features.

selected_id

Optional[str] default = None user source

Optional value of id_field that selects a single feature in the vector source.

geographic_box_buffer

TOML: [mesh_catchment.domain] with kind = "geographic_box_buffer" – model ZoneMeshingDomainGeographicBoxBuffer.

geographic_watershed

TOML: [mesh_catchment.domain] with kind = "geographic_watershed" – model ZoneMeshingDomainGeographicWatershed.

geographic_watershed_box

TOML: [mesh_catchment.domain] with kind = "geographic_watershed_box" – model ZoneMeshingDomainGeographicWatershedBox.

zone_meshing in TOML: [mesh_catchment.zone_meshing]

ZoneMeshingSettings factory dev source

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.

Fields of ZoneMeshingSettings

algorithm

str default = “delaunay” user source

Planar Gmsh algorithm name. In practice the examples use ‘delaunay’, which is a robust default for irregular geological and river-constrained domains.

global_size

float default = 250.0 user source

Baseline target cell size in projected metres over the full support domain. Think of it as the coarse background resolution before local interface refinement is added.

min_size

Optional[float] default = None user source

Lower bound on local cell size in projected metres. Use it to prevent extreme refinement from generating very small cells in narrow features.

max_size

Optional[float] default = None user source

Upper bound on local cell size in projected metres. Use it when you want to cap the coarsening far from interfaces.

simplify_tolerance

float default = 0.0 dev source

Geometry simplification tolerance, in projected metres, applied before meshing. Increase it only when the source polygons contain excessive vertex noise that does not carry hydrogeological meaning.

heal_tolerance

float default = 0.0 dev source

Cleanup tolerance, in projected metres, used to repair tiny gaps or slivers between input polygons. Keep it near zero unless the source dataset is known to contain topology artifacts.

linear_constraint_snap_tolerance

float default = 0.0 dev source

Optional global snapping tolerance, in projected metres, applied to internal linear constraints such as rivers or watershed-boundary segments before partition splitting and Gmsh embedding.

min_polygon_area

float default = 0.0 dev source

Minimum polygon area, in square metres, kept after cleaning. Use it to drop microscopic remnants that would otherwise create meaningless tiny mesh patches.

refine_interfaces

bool default = False user source

Enable a distance-based size field around geology or river interfaces. When false, the mesh uses only the global background size constraints.

interface_size

Optional[float] default = None dev source

Target local size, in projected metres, close to constrained interfaces. When omitted and refine_interfaces=true, the schema derives a conservative default from global_size/min_size.

interface_distance

Optional[float] default = None dev source

Influence distance, in projected metres, over which the local interface refinement fades back to the background size. Larger values spread refinement farther away from the interface network.

interface_sampling

int default = 64 dev source

Sampling density used to discretize interface-based distance fields. Higher values better capture long and sinuous interfaces but increase Gmsh preprocessing cost.

refinement_policy in TOML: [mesh_catchment.zone_meshing.refinement_policy]

ZoneMeshingRefinementPolicy | None default = None user source

Optional local hotspot policy used to selectively thin low-priority refinement families when the mixed interface network becomes too dense for one robust Gmsh Delaunay run.

Fields of ZoneMeshingRefinementPolicy

enabled

bool default = False user source

If True, the local refinement policy runs on top of the global zone meshing.

mode

str default = “family_priority_local_budget” user source

Refinement mode selector. One of ‘family_priority_local_budget’ or ‘grid_local_budget’.

One of: "family_priority_local_budget" "grid_local_budget"

hotspot in TOML: [mesh_catchment.zone_meshing.refinement_policy.hotspot]

ZoneMeshingRefinementHotspotSettings factory dev source

Hotspot-detection thresholds used when budgeting local refinement.

Fields of ZoneMeshingRefinementHotspotSettings

radius

Optional[float] default = None dev source

Hotspot detection radius in projected metres. None lets the mesher derive a default.

max_curve_count

int default = 180 dev source

Maximum number of constraint curves admitted in one hotspot before triggering local refinement.

max_family_count

int default = 2 dev source

Maximum number of distinct constraint families coexisting in one hotspot.

min_gap

float default = 80.0 dev source

Minimum acceptable gap between non-conformal curves in projected metres.

max_node_degree

int default = 4 dev source

Maximum tolerated topological degree at a hotspot junction node.

short_segment_length

float default = 120.0 dev source

Length threshold below which a constraint segment is counted as short, in projected metres.

max_short_segment_count

int default = 12 dev source

Maximum tolerated number of short segments inside one hotspot.

grid in TOML: [mesh_catchment.zone_meshing.refinement_policy.grid]

ZoneMeshingRefinementGridSettings factory user source

Grid settings used by the locality-first refinement policy.

Fields of ZoneMeshingRefinementGridSettings

cell_size

Optional[float] default = None user source

Target cell size in projected metres. None lets the mesher derive a default from constraints.

neighborhood_rings

int default = 1 dev source

Number of cell rings inspected around each hotspot when projecting refinement budget.

enable_exact_gap_check

bool default = True dev source

If True, run the exact pairwise gap check between candidate hotspot curves.

max_exact_gap_candidates

int default = 256 dev source

Cap on the number of curves submitted to the exact gap check before falling back to a heuristic.

families in TOML: [mesh_catchment.zone_meshing.refinement_policy.families.<id>]

dict[str, ZoneMeshingRefinementFamilySettings] factory user source

Per-family refinement settings keyed by family name.

Fields of ZoneMeshingRefinementFamilySettings

enabled

bool default = True user source

If False, this family is parsed but skipped during refinement. Per-family defaults: river and geology_interface are enabled, watershed_boundary is disabled (whole-divide refinement is opt-in).

priority

int default = 0 user source

Application order between families. Higher values win when budgets compete.

interface_size

Optional[float] default = None dev source

Override target cell size at the family interface, in projected metres.

interface_distance

Optional[float] default = None dev source

Override influence distance from the family interface, in projected metres.

interface_sampling

int | None default = None dev source

Override the number of sampled points along the family interface (>=2).

lake_refinement in TOML: [mesh_catchment.lake_refinement]

LakeRefinementConfig factory user source

Optional local refinement on the lake shoreline band and the hydraulic structures (cutoff wall, sill, dam outlet). Disabled by default; set enabled = true to add the lake size fields.

Fields of LakeRefinementConfig

enabled

bool default = False user source

Refine the GMSH mesh on the lake shoreline band (+ hydraulic structures).

cell_size

float default = 40.0 user source

Target cell size [L] in the lake shoreline band.

shoreline_band

float | None default = None user source

Half-width [L] of the refined band around the lake shoreline. When omitted, derives 2 * cell_size. Must be >= cell_size so the band holds at least one target cell (a thinner band would slip between the size-field sampling nodes).

buffer

float default = 200.0 user source

Transition distance [L] over which the lake sizes ramp back to global.

interior_size

float | None default = None user source

Optional target cell size [L] inside the whole lake footprint (marnage / bathymetry resolution). When omitted, the interior keeps the background size.

dam_cell_size

float default = 30.0 user source

Target cell size [L] in the hydraulic-structure zones (cutoff wall, sill).

dam_buffer

float default = 150.0 user source

Base half-width [L] of the structure refinement corridors; also the radius of the optional dam-outlet disk.

hfb_buffer

float | None default = None user source

Half-width [L] of the refined zone around the dam cutoff wall (HFB). The zone covers the lake outlet area. When omitted, derives 2 * dam_buffer. Must be >= dam_cell_size so the zone holds at least one target cell.

dam_outlet_disk

bool | None default = None user source

Refine a disk of radius dam_buffer around the dam / catchment outlet. None (auto) emits the disk unless a cutoff-wall zone overlaps it: the widened HFB zone then already covers the outlet.

refinement_zone in TOML: [[mesh_catchment.refinement_zone]]

list[RefinementZoneConfig] factory user source

User-provided zones of interest for local refinement. Each entry names one vector layer (polygons = zones, points / lines = corridors) and a target cell size; declare entries as [[mesh_catchment.refinement_zone]] tables.

Fields of RefinementZoneConfig

path

str required user source

Vector layer (gpkg / shp / GeoJSON) of polygons (zones) and/or points or lines (corridors). A bare filename resolves against <workspace>/data/refinement_zone/; relative paths resolve against that directory, the data directory, then the config directory.

cell_size

float required user source

Target cell size [L] inside the zone.

buffer

float | None default = None user source

Corridor half-width [L] for point / line features, and transition distance back to the background size. When omitted, derives 2 * cell_size. Must be >= cell_size so the corridor holds at least one target cell.

Starter TOML snippet

Click to expand a copy-pasteable [mesh_catchment] 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.

[mesh_catchment]
# constraints_mode = "geology_rivers"
# figures_enabled = true
# export_exchange_bundle = true
# cache = false
# figure_dpi = 300
# figure_regional_dpi = 220
# output_layout = "standard"
# show_plot = false
# [mesh_catchment.geology.<id>]

[mesh_catchment.rivers]
# source = "geographic_features"
# path = ...  # default = None
# clip_to_domain = true
# min_segment_length = 0.0
# snap_tolerance = 0.0

[mesh_catchment.watershed_boundary]
# enabled = false
# smoothing = ...  # factory default
# outside_coarsening = ...  # factory default
# geology_conformity = ...  # factory default

[mesh_catchment.hydraulic_properties]
# conductivity = ...  # default = None
# storage_coefficient = ...  # default = None

[mesh_catchment.domain]
# kind = "bbox"
# bbox = 0.0  # REQUIRED

[mesh_catchment.lake_refinement]
# enabled = false
# cell_size = 40.0
# shoreline_band = ...  # default = None
# buffer = 200.0
# interior_size = ...  # default = None
# dam_cell_size = 30.0
# dam_buffer = 150.0
# hfb_buffer = ...  # default = None
# dam_outlet_disk = ...  # default = None

[[mesh_catchment.refinement_zone]]
# path = ""  # REQUIRED
# cell_size = 0.0  # REQUIRED
# buffer = ...  # default = None

Entity-relationship diagram

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