[geographic] GeographicConfig

TOML section: [geographic]

Pydantic model: GeographicConfig defined in hydromodpy.spatial.geographic.geographic_config.

Source on GitHub

Geographic configuration for watershed delineation.

This model stores parameters used to extract and prepare the physical domain (watershed geometry and rasters) based on various possible input definitions.

Standard mode uses an external DEM with one of the catchment definitions: direct DEM, XYZ text grid, outlet coordinate, or polygon shapefile. Synthetic mode builds an analytical support and bypasses external DEM delineation.

Show fields: User User + Dev All

Fields

source_mode

str default = “standard” user source

Geographic runtime mode. ‘standard’ keeps the historical DEM/outlet/polygon workflow. ‘synthetic’ builds one analytical support from [geographic.synthetic].

One of: "standard" "synthetic"

catchment in TOML: [geographic.catchment]

catch_def = “dem” | “txt” | “from_outlet_coord” | “from_polyg_shp” default = None user source

Catchment definition payload used when source_mode=’standard’. Discriminated by ‘catch_def’ on the nested table: ‘dem’ | ‘txt’ | ‘from_outlet_coord’ | ‘from_polyg_shp’.

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

dem

TOML: [geographic.catchment] with catch_def = "dem" – model DemCatchDef.

dem_init_path

Path | None default = None user source

Path to the DEM raster used as input. For ‘dem’ and ‘txt’ modes: defines the model domain directly. For ‘from_outlet_coord’ and ‘from_polyg_shp’ modes: regional DEM used for flow analysis. May be left absent when [data.dem.sources] declares the DEM.

txt

TOML: [geographic.catchment] with catch_def = "txt" – model TxtCatchDef.

dem_init_path

Path | None default = None user source

Path to the DEM raster used as input. For ‘dem’ and ‘txt’ modes: defines the model domain directly. For ‘from_outlet_coord’ and ‘from_polyg_shp’ modes: regional DEM used for flow analysis. May be left absent when [data.dem.sources] declares the DEM.

cell_size

float required user source

Grid cell size in metres used to rasterise the XYZ point cloud. Accepts inline units (e.g. ‘25 m’, ‘0.025 km’).

from_outlet_coord

TOML: [geographic.catchment] with catch_def = "from_outlet_coord" – model OutletCatchDef.

dem_init_path

Path | None default = None user source

Path to the DEM raster used as input. For ‘dem’ and ‘txt’ modes: defines the model domain directly. For ‘from_outlet_coord’ and ‘from_polyg_shp’ modes: regional DEM used for flow analysis. May be left absent when [data.dem.sources] declares the DEM.

x_outlet

float required user source

X coordinate of the watershed outlet in the projected CRS.

y_outlet

float required user source

Y coordinate of the watershed outlet in the projected CRS.

snap_dist

float required user source

Maximum snapping distance (metres) to move the outlet to the nearest stream cell. Accepts inline units (e.g. 50, ‘50 m’, ‘0.05 km’).

buff_area

str | float required user source

Buffer around the watershed polygon. Numeric values are interpreted as a percentage of sqrt(area [km^2]). String values are interpreted as explicit distances (for example ‘500 m’, ‘2 km’).

from_polyg_shp

TOML: [geographic.catchment] with catch_def = "from_polyg_shp" – model PolygonCatchDef.

dem_init_path

Path | None default = None user source

Path to the DEM raster used as input. For ‘dem’ and ‘txt’ modes: defines the model domain directly. For ‘from_outlet_coord’ and ‘from_polyg_shp’ modes: regional DEM used for flow analysis. May be left absent when [data.dem.sources] declares the DEM.

polyg_shp_path

Path required user source

Path to the watershed polygon shapefile.

buff_area

str | float required user source

Buffer around the watershed polygon. Numeric values are interpreted as a percentage of sqrt(area [km^2]). String values are interpreted as explicit distances (for example ‘500 m’, ‘2 km’).

crs_project

str | None default = None user source

Target projected CRS for all outputs (e.g. ‘EPSG:2154’). If not set, derived from the input DEM.

dem_correc_type

str default = “breach” user source

DEM depression correction method. ‘breach’ (recommended) preserves natural flow paths. ‘fill’ raises sinks to their pour point.

One of: "breach" "fill"

domain_extent

str default = “box” user source

Selects the DEM surface used for the domain. ‘box’ (default) keeps the full buffered rectangular support. ‘watershed’ / ‘watershed_buff’ select the catchment (optionally with a buffer ring) surface. Note: the MODFLOW 6 mesh still covers the buffered box (the buffer stays active for inter-basin exchange); out-of-watershed drainage is kept out of the catchment discharge by the DRN watershed-routing, not by an idomain mask. Experimental.

One of: "box" "watershed_buff" "watershed"

bottom_path

Path | None default = None user source

Path to a raster representing the aquifer bottom elevation. Must share the same grid as the model domain.

reg_fold

Path | None default = None dev source

Folder with pre-computed regional flow rasters. When set, rasters are loaded instead of recomputed.

synthetic in TOML: [geographic.synthetic]

SyntheticGeographicConfig factory user source

Synthetic geographic support used when source_mode=’synthetic’. This analytical mode bypasses watershed delineation from external DEM files.

Fields of SyntheticGeographicConfig

case_id

str default = “flat20” user source

Identifier used by local case runners and outputs.

grid in TOML: [geographic.synthetic.grid]

SyntheticGridConfig factory user source

Synthetic grid definition (extent and cell size).

Fields of SyntheticGridConfig

length_x

float default = 100.0 user source

Total domain length along x (metres). Accepts inline units, e.g. ‘0.1 km’.

length_y

float default = 1.0 user source

Total domain length along y (metres). Accepts inline units, e.g. ‘1 m’.

nx

int default = 100 user source

Number of cells along x.

ny

int default = 1 user source

Number of cells along y.

xmin

float default = 0.0 dev source

Lower x coordinate of the support extent.

ymin

float default = 0.0 dev source

Lower y coordinate of the support extent.

crs

str default = “EPSG:2154” dev source

Projected CRS attached to synthetic outputs.

nodata

float default = -9999.0 dev source

Nodata sentinel exported to raster artefacts.

topography in TOML: [geographic.synthetic.topography]

kind = “flat” | “linear” | “radial_island” factory user source

Synthetic topography definition (shape, elevations, slope).

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

flat

TOML: [geographic.synthetic.topography] with kind = "flat" – model FlatTopography.

base_elevation

float default = 20.0 user source

Constant surface elevation (m).

linear

TOML: [geographic.synthetic.topography] with kind = "linear" – model LinearTopography.

base_elevation

float default = 20.0 user source

Reference elevation (m) on the right boundary.

right_to_left_amplitude

float default = 0.0 dev source

Additional elevation reached on the left boundary relative to the right boundary. Positive values make the surface rise from right to left.

radial_island

TOML: [geographic.synthetic.topography] with kind = "radial_island" – model RadialIslandTopography.

base_elevation

float default = -1.0 user source

Submerged ocean-floor elevation (m). Must be < 0.

island_radius

Optional[float] default = None dev source

Circular shoreline radius (metres). Defaults to 35% of the smallest domain length. Accepts inline units.

crest_elevation

float default = 10.0 dev source

Central island elevation (m). The land surface decays nonlinearly to sea level at the shoreline.

center_x

Optional[float] default = None dev source

Optional x coordinate (metres) of the island center. Defaults to the grid midpoint.

center_y

Optional[float] default = None dev source

Optional y coordinate (metres) of the island center. Defaults to the grid midpoint.

river_network in TOML: [geographic.river_network]

RiverNetworkConfig factory user source

Optional DEM-derived river-network extraction settings. When disabled, no stream network is generated in geographic preprocessing.

Fields of RiverNetworkConfig

enabled

bool default = False user source

Enable DEM-based river-network extraction from flow accumulation during geographic preprocessing.

threshold_mode

str default = “area_km2” user source

Stream-initiation threshold selector. ‘area_km2’ uses contributing area in km^2. ‘cells’ uses contributing-cell count directly.

One of: "area_km2" "cells"

threshold_area_km2

float | None default = None user source

Contributing area threshold (km^2), required when threshold_mode=’area_km2’.

threshold_cells

float | None default = None user source

Contributing-cell threshold, required when threshold_mode=’cells’.

prune_short_streams

bool default = False user source

If true, remove short stream segments after extraction.

min_stream_length_m

float default = 0.0 user source

Minimum stream length (metres) used by short-segment pruning. Accepts inline units (e.g. 0, 250, ‘250 m’, ‘0.5 km’).

compute_strahler_order

bool default = True user source

Compute Strahler order raster from extracted streams.

compute_stream_links

bool default = True user source

Compute stream-link identifier raster from extracted streams.

all_vertices

bool default = False user source

Forwarded to Whitebox raster_streams_to_vector. False keeps a lighter vector geometry.

enforce_streams in TOML: [geographic.enforce_streams]

StreamEnforcementConfig factory user source

Optional stream burning of the routing DEM: lower the mapped network cells so the computed D8 paths follow the observed network, without touching the model grid top. Applied before the lake carve.

Fields of StreamEnforcementConfig

enabled

bool default = False user source

Lower the mapped stream cells in the routing DEM before D8 so the computed flow paths follow the observed network.

stream_geometry_path

Path | None default = None user source

Observed stream network (gpkg/shp) to burn. A bare filename resolves against <workspace>/data/hydrography/. When left empty and enabled, it falls back to the network [[data.hydrography.sources]] declares, so the same file is named once; declare it here only to burn a network that differs from the one the data family loads.

mode

str default = “constant” user source

Trench depth rule. ‘constant’ lowers every stream cell by depth_m. ‘adaptive’ derives one depth from the measured local relief along the network. Either way a single depth is used, so the along-channel gradient the trench exists to preserve is not rewritten.

One of: "constant" "adaptive"

depth_m

float default = 30.0 user source

Trench depth (metres) for mode=’constant’. It must exceed the local drop between a stream cell and its lowest non-stream neighbour; 5 m clears 0.90 agreement on every measured catchment, 10 to 20 m are needed for 0.95 to 0.99 on the difficult ones, and 1 m buys almost nothing. Accepts inline units (e.g. 30, ‘30 m’).

adaptive_percentile

float default = 95.0 user source

Percentile of the local relief along the network used as the trench depth when mode=’adaptive’.

relief_report_percentile

float default = 95.0 expert source

Percentile of the local relief along the network reported in the burn report and compared to the depth actually used, whatever the mode. It is the drop a constant trench must clear to keep the flow on the mapped network, so a depth below it warns. Independent of adaptive_percentile, which SETS the depth; this one only JUDGES it.

rasterize_all_touched

bool default = True expert source

Rasterize the network with the all-touched rule, so every cell a reach crosses is burned and not only those whose centre falls under the line. A one-cell-wide trace that skips a cell leaves a step the flow escapes through, which is what the trench exists to prevent. False uses the centre rule and is only there to reproduce a raster written that way.

dem_nodata_fallback

float default = -9999.0 expert source

Nodata value assumed when the DEM to burn declares none in its header. It decides which cells are excluded from the burn and from the relief measurement, so a raster using another sentinel must say so here.

alpha_warning_threshold

float default = 0.9 expert source

Below this agreement between the mapped network and the D8 paths of the routing DEM, a warning fires. alpha is the share of the downstream closure of the network that the network itself covers: 1.00 means the computed paths never leave the map, 0.50 is the signature of a systematic one-pixel shift. Below the threshold, any length measured along those paths reports a DEM-versus-map disagreement rather than hydrogeology.

max_catchment_area_drift

float default = 0.05 user source

Relative change of the delineated catchment area the burn may cause. A trench that crosses a divide (mis-georeferenced trace, canal, flat area) reconnects two catchments and the delineation changes without any other sign, so the catchment is delineated before and after the burn and a larger drift raises. This costs one extra delineation pass whenever the burn is on.

enforce_lakes in TOML: [geographic.enforce_lakes]

LakeEnforcementConfig factory user source

Optional lake hydro-enforcement of the routing DEM: carve the lake footprints so streams route into the lakes and drain to the outlet, without touching the model grid top.

Fields of LakeEnforcementConfig

enabled

bool default = False user source

Carve the lake footprints into the routing DEM before D8 so streams converge into the lakes and drain to the outlet through them.

lake_geometry_path

Path | None default = None user source

Lake footprint polygons (gpkg/shp) to carve. A bare filename resolves against <workspace>/data/lake_geometry/. Required when enabled.

slope

float default = 0.003 user source

Ramp gradient (m per m of distance to the outlet). Small and positive so each lake slopes gently toward the outlet with no flat depression (a flat sink would make the breach crawl).

buffer_m

float default = 15.0 user source

Buffer (metres) applied to each lake footprint to bridge inter-lake sills and knit the shoreline into the carve.

capture_radius_m

float default = 0.0 user source

If > 0, run a SECOND delineation pass: any stream that dead-ends within this distance of a lake (a near-miss over a flat forebay) is carved to the lake and re-delineated, so its channel reaches the shoreline. 0 disables the capture pass (lake carve only).

capture_max_streams

int default = 8 expert source

Capture pass: cap on how many near-miss stream terminals are carved to lakes per pass (kept by decreasing flow accumulation).

capture_min_acc_fraction

float default = 0.3 expert source

Capture pass: keep only near-miss terminals whose flow accumulation is at least this fraction of the largest, so a tiny rivulet is not carved.

dam_carve in TOML: [geographic.dam_carve]

DamCarveConfig factory user source

Optional dam structure-carve of the model-top DEM: lower the dam footprint to the valley floor so a cutoff wall sits at the dam on a raw DEM (mirror of enforce_lakes, on the top instead of the routing DEM).

Fields of DamCarveConfig

enabled

bool default = False user source

Carve the dam footprint of the model-top DEM down to the local valley floor so the cutoff wall sits at the true dam on a raw DEM.

line_path

Path | None default = None user source

Dam trace (gpkg/shp/csv) along which the top is carved. A bare filename resolves against <workspace>/data/cutoff_wall/. Usually the same surveyed voile axis as the cutoff_wall. Required when enabled.

buffer_m

float default = 40.0 user source

Half-width (metres) of the carved corridor around the dam trace. Make it a bit wider than one DEM/cell size so the whole dam body is brought to the valley floor.

search_radius_m

Optional[float] default = None user source

Radius (metres) of the neighborhood whose minimum elevation defines the valley floor the corridor is carved to. When omitted, derives 3 * buffer_m.

reuse_existing_outputs

bool default = False user source

If true, reuse previously generated geographic artifacts when the cached fingerprint matches the current DEM, outlet/polygon and geographic settings. This is useful for profiling repeated simulation runs in the same workspace.

write_intermediates

bool default = False dev source

Keep intermediate rasters and shapefiles on disk after geographic preprocessing. When false (default), .hmp/scratch/_preprocessing/ is removed after ingestion into the run field store.

Starter TOML snippet

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

[geographic]
# source_mode = "standard"
# crs_project = ...  # default = None
# dem_correc_type = "breach"
# domain_extent = "box"
# bottom_path = ...  # default = None
# reuse_existing_outputs = false

[geographic.catchment]
# dem_init_path = ...  # default = None
# catch_def = "dem"

[geographic.synthetic]
# case_id = "flat20"
# grid = ...  # factory default
# topography = ...  # factory default

[geographic.river_network]
# enabled = false
# threshold_mode = "area_km2"
# threshold_area_km2 = ...  # default = None
# threshold_cells = ...  # default = None
# prune_short_streams = false
# min_stream_length_m = 0.0
# compute_strahler_order = true
# compute_stream_links = true
# all_vertices = false

[geographic.enforce_streams]
# enabled = false
# stream_geometry_path = ...  # default = None
# mode = "constant"
# depth_m = 30.0
# adaptive_percentile = 95.0
# max_catchment_area_drift = 0.05

[geographic.enforce_lakes]
# enabled = false
# lake_geometry_path = ...  # default = None
# slope = 0.003
# buffer_m = 15.0
# capture_radius_m = 0.0

[geographic.dam_carve]
# enabled = false
# line_path = ...  # default = None
# buffer_m = 40.0
# search_radius_m = ...  # default = None

Cases using this section

Validation gallery cases that reference fields from this section:

• Boussinesq Circular-Island Piecewise-K 2D

• Boussinesq Divide-Fixed-Head Piecewise-K 1D

• Boussinesq Fixed-Head Piecewise-K 1D

• Boussinesq Sloping-Substratum Constant-Thickness 1D

• Boussinesq Sloping-Substratum Fixed-Head 1D

• Boussinesq Sloping-Substratum Uniform-Recharge 1D

• Boussinesq Uniform-Recharge Piecewise-K 1D

• Brutsaert Recession Validation: Thin Nonlinear Aquifer

• Brutsaert Recession Validation: Deep Linearized Aquifer

• Dupuit Circular-Island Ocean 2D

• Dupuit Divide-River 1D

• Dupuit Fixed-Head 1D

• Dupuit Uniform Recharge 1D

• Late-Time Unconfined Pumping 2D

• Linearized Unconfined Boundary Piecewise 1D

• Linearized Unconfined 1D Boundary Step

• Linearized Unconfined Drainage 1D

• Linearized Unconfined Hillslope Drainage 1D

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