HydroPol2D is controlled by binary and categorical switches. In the case workbook HydroPol2D_Inputs.xlsx, each switch sits at the top of the block it controls, on the tab of its process, and the block greys out while the switch is 0. There is no separate Flags sheet. The Case Workbook Settings page lists every block with its settings.
This page lists every switch by tab, then the rules for combining them.
Switches by tab​
Generated from the workbook catalog (tools/workbook_builder/input_catalog.yaml in the MATLAB repository). The descriptions are the workbook notes.
Run control​
| Switch | Block | Values | Default | Description |
|---|
flag_adaptive_timestepping | Surface time step | 0 / 1 | required | Updates the surface-routing timestep from the stability limits during the simulation. Keep enabled for most dynamic simulations. |
flag_GPU | Computing | 0 / 1 | required | Runs supported arrays and calculations on a compatible MATLAB GPU. Leave disabled when a compatible GPU is not available. |
flag_single | Computing | 0 / 1 | required | Stores supported numerical arrays in single precision to reduce memory use. Keep disabled when maximum numerical precision is required. |
flag_export_maps | Outputs and display | 0 / 1 | required | Exports scheduled spatial model outputs such as flood depth and related maps. |
flag_export_groundwater_maps | Outputs and display | 0 / 1 | 0 | Exports scheduled groundwater water-table-depth rasters when groundwater modelling is enabled. |
flag_wse | Outputs and display | 0 / 1 | required | flag_wse controls water-surface-elevation map output: 0 disables it and 1 enables it. The map uses DEM elevation plus simulated water depth where depth exceeds depth_wse. |
flag_waterbalance | Outputs and display | 0 / 1 | required | Writes water-balance diagnostics during the run. Enable this for validation and for routine model checks. |
flag_dashboard | Outputs and display | 0 / 1 | required | Creates the configured dashboard-oriented outputs during the simulation. |
flag_elapsed_time | Outputs and display | 0 / 1 | required | Prints or records elapsed computational time for the simulation. |
flag_warmup | Warm start | 0 / 1 | required | Initializes the simulation from the configured warm-up state rather than the standard initial-state rasters. |
flag_timestep | Advanced (keep the defaults unless you know why) | 0 / 1 | required | Selects the full timestep-stability treatment for supported routing solvers. Use the validated default unless testing a specific numerical formulation. |
Soil and groundwater​
| Switch | Block | Values | Default | Description |
|---|
flag_infiltration | Infiltration and evapotranspiration | 0 / 1 | required | Enables infiltration and the layered soil-water balance. Disabling it also disables evapotranspiration in the current model. |
flag_ETP | Infiltration and evapotranspiration | 0 / 1 | required | Enables evapotranspiration. HydroPol2D uses the configured meteorological or map inputs to calculate evaporation and transpiration. |
flag_abstraction | Infiltration and evapotranspiration | 0 / 1 | required | Enables canopy interception and initial abstraction processes. |
flag_capillary_rise | Infiltration and evapotranspiration | 0 / 1 | 1 | Enables capped upward flow from shallow groundwater to the transmission or root zone when storage deficits exist. |
flag_snow_modeling | Infiltration and evapotranspiration | 0 / 1 | required | Enables precipitation partition, snow storage, melt, sublimation, and compaction using the snow columns of the Land use classes tab. |
flag_spatial_albedo | Infiltration and evapotranspiration | 0 / 1 | required | Uses the supplied albedo raster instead of the scalar default albedo. |
flag_neglect_infiltration_river | Infiltration and evapotranspiration | 0 / 1 | required | Sets infiltration and initial abstraction to zero in identified river cells. |
flag_groundwater_modeling | Groundwater | 0 / 1 | required | Enables the coupled layered-soil recharge and saturated groundwater module. |
flag_baseflow | Groundwater | 0 / 1 | required | Enables the configured baseflow contribution where the selected hydrologic workflow supports it. |
flag_prescribed_recharge | Groundwater | 0 / 1 | 0 | Replaces the computed recharge to the water table with the series in Prescribed_Recharge_Timeseries_File (Input maps tab). Default 0. |
flag_layered_subsurface | Layered subsurface: column | 0 / 1 | 0 | Enables the layered subsurface: three soil layers over weathered-rock layers down to bedrock, one water table per cell (Miguez-Macho et al., 2007 rules). Settings are in the layered-subsurface blocks of the Soil and groundwater tab; the optional rasters sit under the values they override. Requires flag_groundwater_modeling = 1. |
flag_implicit_water_table_flux | Layered subsurface: soil and numerics | 0 / 1 | 1 | Solves the Darcy flux between the soil and the water table implicitly in the layered subsurface (one linearised backward-Euler step per cell): 1 (default) stays accurate at long time steps when the water table is shallow; 0 uses the explicit flux, which needs short steps there. Used only with flag_layered_subsurface = 1. |
flag_feddes | Feddes root-water stress | 0 / 1 | 0 | Enables Feddes root-water stress: transpiration from each soil layer is reduced by its suction head. Heads are in this block. Works with the layered and the legacy soil schemes. |
flag_deep_aquifer | Deep aquifer | 0 / 1 | 0 | Enables the deep aquifer: deep_recharge_fraction of the water-table recharge goes to one linear reservoir per subbasin and returns to the surface after deep_aquifer_tau_days. Requires DeepAquiferSubbasins_path and DeepAquiferChannelWeight_path. |
Surface flow​
| Switch | Block | Values | Default | Description |
|---|
flag_inertial | Routing scheme | 0 / 1 | required | Selects the local-inertial hydrodynamic solver. It is the required routing solver for the active Neal (2012) channel-subgrid extension. |
flag_CA | Routing scheme | 0 / 1 | required | Selects the cellular-automata hydrodynamic routing option. Do not enable it together with local inertial or full momentum routing. |
flag_kinematic | Routing scheme | 0 / 1 | required | Selects the kinematic-wave routing alternative. Do not combine it with local inertial, full momentum, or cellular automata routing. |
flag_diffusive | Routing scheme | 0 / 1 | required | Selects the diffusive-wave routing alternative. Do not combine it with local inertial, full momentum, or cellular automata routing. |
flag_D8 | Routing scheme | 0 / 1 | required | Retired: keep at 0. The old raster D8 was incomplete, and 1 stops the run. D8 local-inertial routing is flag_d8_local_inertial, set in the bypass script (see Limitations). |
flag_boundary | Outlets and boundaries | 0 / 1 | required | Activates the configured open/perimeter boundary treatment. Define the outlet mask and outlet slope carefully because this setting controls water removal at the domain edge. |
flag_critical | Outlets and boundaries | 0 / 1 | required | Uses the critical-flow outlet treatment where the selected routing solver supports it. This is distinct from the normal-flow outlet selected with flag_outlet_type. |
flag_neal_channel | River channel (sub-grid) | 0 / 1 | required | Activates the Neal (2012) embedded rectangular channel and floodplain extension. It requires flag_inertial = 1, structured raster topology, and valid river-width and river-depth rasters. |
flag_river_rasters | River channel (sub-grid) | 0 / 1 | required | Uses supplied RiverWidths and RiverDepths rasters to define the channel geometry for the active subgrid model. |
flag_resample | Terrain treatment | 0 / 1 | required | Resamples ancillary rasters to the DEM grid during preprocessing when their grid differs from the DEM. |
flag_fill_DEM | Terrain treatment | 0 / 1 | required | Fills terrain depressions before deriving drainage directions and flow accumulation. |
flag_smoothening | Terrain treatment | 0 / 1 | required | Applies constrained stream-profile smoothing during DEM preprocessing. This option requires Optimization Toolbox. |
flag_smooth_cells | Terrain treatment | 0 / 1 | required | Applies the configured cell-level DEM smoothing treatment during preprocessing. |
flag_trunk | Terrain treatment | 0 / 1 | required | Uses the trunk-stream processing option during terrain and drainage-network preparation. |
flag_reduce_DEM | Terrain treatment | 0 / 1 | required | Applies the configured river-channel DEM reduction during preprocessing. |
flag_DTM | Terrain treatment | 0 / 1 | required | Uses the DTM-processing pathway for terrain preparation when that workflow is required by the input data. |
flag_voronoi | Unstructured mesh | 0 / 1 | 0 | Runs the model on a prepared Voronoi (unstructured) mesh instead of the raster grid. Mesh options are read from the Mesh tab. |
flag_voronoi_subgrid | Unstructured mesh | 0 / 1 | required | Enables sub-grid face tables (stage versus flow area, wetted perimeter and conveyance) on the Voronoi mesh. Used only with flag_voronoi = 1; the table path is set in the Mesh tab. |
flag_inflow | Inflows and structures | 0 / 1 | required | Applies one or more prescribed discharge hydrographs at the inlet coordinates defined in the Inflow hydrographs tab. |
flag_stage_hydrograph | Inflows and structures | 0 / 1 | required | Applies a prescribed water-level hydrograph at the configured stage-boundary location(s). |
flag_reservoir | Inflows and structures | 0 / 1 | required | Enables the reservoir and control-structure module using the configured reservoir inputs. |
flag_structured_lookup_subgrid | Paused (keep at 0: setting 1 stops the run) | 0 / 1 | 0 | Enables the structured lookup-table subgrid formulation on the regular raster model. It uses level-dependent cell and face properties and cannot be combined with Neal or Voronoi subgrid. |
Rain and ET​
| Switch | Block | Values | Default | Description |
|---|
flag_rainfall | Rainfall source | 0 / 1 | required | Enables rainfall forcing. Use this with one selected rainfall source: a lumped time series, gauge interpolation, a scheduled raster sequence, or a satellite product. |
flag_spatial_rainfall | Rainfall source | 0 / 1 | required | Interpolates rainfall from the configured rainfall gauges to every model cell. Gauge coordinates and a common rainfall time series are required. |
flag_input_rainfall_map | Rainfall source | 0 / 1 | required | Reads a time-indexed sequence of rainfall rasters from the Rainfall maps list. Do not enable this together with another spatial-rainfall source. |
flag_satellite_rainfall | Rainfall source | 0 / 1 | required | Activates the satellite-rainfall forcing workflow. It prepares an hourly spatial-rainfall schedule and enables rainfall automatically. |
flag_real_time_satellite_rainfall | Rainfall source | 0 / 1 | required | Activates the real-time satellite rainfall workflow. This experimental option creates a short rolling spatial-rainfall schedule. |
flag_input_ETP_map | Evapotranspiration source | 0 / 1 | required | Reads paired transpiration and evaporation raster schedules from the Rain and ET tab. Both schedules must have the same time entries. |
flag_rainfall_multiple_runs | Advanced (keep the defaults unless you know why) | 0 / 1 | required | Activates the legacy multiple-rainfall-run workflow. Leave disabled for one standard rainfall event. |
Design storm​
| Switch | Block | Values | Default | Description |
|---|
flag_alternated_blocks | Hyetograph | 0 / 1 | required | Generates the configured alternating-block design storm instead of reading a rainfall time series. |
flag_huff | Hyetograph | 0 / 1 | required | Generates the configured Huff design storm instead of reading a rainfall time series. |
Water quality​
| Switch | Block | Values | Default | Description |
|---|
flag_waterquality | Water quality | 0 / 1 | required | Enables pollutant buildup, washoff, transport, and output calculations. |
flag_WQ_Rasters | Water quality | 0 / 1 | required | Uses spatial water-quality coefficient rasters B1, B2, W1, and W2 instead of the land-cover table coefficients. |
flag_initial_buildup | Water quality | 0 / 1 | required | Initializes water-quality buildup using the configured antecedent dry-period and buildup settings. |
flag_wq_model | Advanced (keep the defaults unless you know why) | 0 / ... | required | Selects the water-quality formulation. Value 0 uses the mass-based buildup/washoff mode; use other values only for supported legacy configurations. |
Risk and gauges​
| Switch | Block | Values | Default | Description |
|---|
flag_human_instability | Human instability | 0 / 1 / 3 | required | Calculates depth-velocity human-instability indicators. Value 0 disables it; value 1 uses the basic classification and value 3 enables the extended classification. |
flag_obs_gauges | Observation points | 0 / 1 | required | Exports modeled values at the observation-gauge coordinates listed in the gauge table. |
Rules for combining switches​
- Only one major routing family should be active at a time:
flag_full_momentum, flag_inertial, flag_diffusive, flag_kinematic, or flag_CA.
- Select at most one subgrid formulation: Neal channel, structured lookup, or Voronoi lookup.
flag_voronoi = 1 selects the mesh topology; flag_voronoi_subgrid = 1 additionally enables Voronoi lookup hydraulics.flag_D8 is retired; keep it at 0. D8 local-inertial routing (flag_d8_local_inertial), urban drainage, detention ponds and green infrastructure are set in the bypass script, not in the workbook (see Limitations).flag_numerical_scheme (1 Bates, 2 upwind, 3 centered) applies to the local-inertial family only.- Snow needs the internal meteorological forcing:
flag_ETP = 1 and flag_input_ETP_map = 0. Snow parameters are columns of the land-use class table.
flag_implicit_water_table_flux and the other layered-subsurface settings are read only with flag_layered_subsurface = 1.- Human-instability mode
2 is not implemented. Use 1 or 3.
Neal (2012) channel subgrid​
The supported channel-subgrid mode follows Neal et al. (2012). Use this combination:
| Switch | Required value |
|---|
flag_inertial | 1 |
flag_neal_channel | 1 |
flag_structured_lookup_subgrid | 0 |
flag_voronoi_subgrid | 0 |
flag_voronoi | 0 |
flag_full_momentum | 0 |
flag_diffusive | 0 |
flag_kinematic | 0 |
flag_CA | 0 |
flag_river_rasters | 1 when channel geometry is supplied as rasters |
The active channel cells require both RiverWidths_path and RiverDepths_path. Channel width and depth must be positive, and channel width must be smaller than the model-cell resolution. The channel Manning coefficient is the Manning setting on the Surface flow tab. The land-use roughness supplies the floodplain Manning coefficient.
The solver computes channel and floodplain discharge separately on each orthogonal face and updates cell storage in volume space. The formulation and validation range are described in Hydrodynamic Model and Neal (2012) Subgrid Model Validation.
Older layout​
In cases that use General_Data.xlsx, the switches are rows of its Flags sheet, with the value in column E. In the distributed workbooks flag_deep_aquifer, flag_layered_subsurface, flag_feddes and flag_implicit_water_table_flux are rows 37 to 40. The model reads the Flags sheet when the case has one, and the switches of the settings tabs otherwise.
- The retired switches
flag_data_source, flag_dam_break and flag_river_heigth_compensation are no longer required (default 0).
flag_subgrid and flag_overbanks are derived from the channel switches. Older inputs that still set them are accepted by the migration layer, with a warning.