[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

Literal[‘standard’, ‘synthetic’] default = “standard” user source

Geographic runtime mode. ‘standard’ keeps the historical DEM/outlet/polygon workflow. ‘synthetic’ builds one analytical support from [geographic.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.dem] – model DemCatchDef (set catch_def = "dem").

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.txt] – model TxtCatchDef (set catch_def = "txt").

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.from_outlet_coord] – model OutletCatchDef (set catch_def = "from_outlet_coord").

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.from_polyg_shp] – model PolygonCatchDef (set catch_def = "from_polyg_shp").

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

Literal[‘breach’, ‘fill’] default = “breach” user source

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

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.flat] – model FlatTopography (set kind = "flat").

base_elevation

float default = 20.0 user source

Constant surface elevation (m).

linear

TOML: [geographic.synthetic.topography.linear] – model LinearTopography (set kind = "linear").

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.radial_island] – model RadialIslandTopography (set kind = "radial_island").

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

Literal[‘area_km2’, ‘cells’] default = “area_km2” user source

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

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.

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), results_stable/ is removed after ingestion into the simulation Zarr 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"
# 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

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.