The Config File

Configuration File

river-route computations are controlled by config values passed as keyword arguments or from a YAML/JSON file. The three routers (Muskingum, RapidMuskingum, UnitMuskingum) share a set of base config keys and each adds router-specific keys.

Minimum Required Inputs

All routing classes require the following 2 configuration options:

params_file - path to the routing parameters file (parquet)
One of two options for specifying where the routed discharge output is written
- discharge_dir - a string path to a directory where outputs are saved based on the names of the inputs
- discharge_files - list of explicit paths for each output file, one per input file required.

Muskingum (channel routing only, no lateral inflows) also requires:

channel_state_init_file - parquet state file to initialize discharge
dt_routing - routing timestep in seconds
dt_total - total simulation duration in seconds

RapidMuskingum also requires:

one water input source:
- qlateral_files, or
- grid_runoff_files plus grid_weights_file

UnitMuskingum also requires:

uh_kernel_file - pre-computed scipy sparse npz kernel
one water input source:
- qlateral_files, or
- grid_runoff_files plus grid_weights_file

Required config keys for each router

Config key	Description	Muskingum	RapidMuskingum	UnitMuskingum
core
`params_file`	Routing parameters parquet.	Required	Required	Required
state
`channel_state_init_file`	Path to initial channel state	Required	optional - default to 0	optional - default to 0
`channel_state_final_file`	Path to save final channel state	optional	optional	optional
output
`discharge_dir`	Directory for output files	Option 1	Option 1	Option 1
`discharge_files`	Explicit output paths	Option 2	Option 2	Option 2
input data
`qlateral_files`	Per-catchment runoff time series		Option 1	Option 1
`grid_runoff_files`	Gridded runoff depths		Option 2	Option 2
`grid_weights_file`	Converts depth grids to qlateral		Option 2	Option 2
unit hydrograph
`uh_kernel_file`	Pre-computed convolution kernel			Required
`uh_state_init_file`	Parquet with initial UH state			optional
`uh_state_final_file`	Path to save final UH state			optional
time
`start_datetime`	Simulation start date	optional
`dt_total`	Total simulation duration	Required	optional - time docs	optional - time docs
`dt_discharge`	Output timestep	optional	optional - time docs	optional - time docs
`dt_runoff`	Runoff data timestep		optional - time docs	optional - time docs
`dt_routing`	Routing computational timestep	Required	optional - time docs	optional - time docs

Optional configs with defaults

Config Key	Description	Default
`log`	Enable or disable logging	`True`
`progress_bar`	Show tqdm progress bar	`True`
`log_level`	Logger level, defaults to between INFO and WARNING	`'PROGRESS'`
`log_stream`	`'stdout'` or a file path	`'stdout'`
`log_format`	Python logging format string	`'%(levelname)s - %(asctime)s - %(message)s'`
`var_river_id`	River ID dimension name in files	`'river_id'`
`var_discharge`	Discharge variable name in output	`'Q'`
`var_grid_runoff`	Runoff variable name in `grid_runoff_files`	`'ro'`
`var_x`	X-dimension name in depth grids	`'x'`
`var_y`	Y-dimension name in depth grids	`'y'`
`var_t`	Time dimension name in depth grids	`'time'`
`grid_accumulation_type`	Is runoff grid `'incremental'` or `'cumulative'`	`'incremental'`
`runoff_processing_mode`	Are runoff `'sequential'` or `'ensemble'` inputs	`'sequential'`

Example Configuration YAMLs

The general template in YAML format lists all keys with comments. Template files for specific routers are available in the examples directory config_muskingum.yaml, config_rapid_muskingum.yaml, config_unit_muskingum.yaml.

General Config File

config.yaml

# river-route configuration template
# Routers: Muskingum | RapidMuskingum | UnitMuskingum

# required — all routers
params_file: ''                  # parquet: river_id, downstream_river_id, k, x

# where to save the outputs
# option 1: a directory where the output files will be named based on the input file routed
discharge_dir: ''                # directory for output netCDF files (named after input files)
# option 2: explicit output paths instead of discharge_dir
discharge_files:                 # optional: explicit output paths instead of discharge_dir
  - ''

# runoff input — RapidMuskingum, UnitMuskingum (choose one option)
# option 1: pre-aggregated per-catchment lateral inflows
# qlateral_files:                 # netCDF: dims (time, river_id); var: qlateral
#  - ''
# option 2: gridded depths remapped to catchments (comment out option 1 to use)
# grid_runoff_files:
#   - ''
# grid_weights_file: ''          # required with grid_runoff_files

# unit hydrograph — UnitMuskingum only
# uh_kernel_file: ''    # scipy sparse npz: shape (n_basins, n_timesteps)
# uh_state_init_file: ''
# uh_state_final_file: ''

# channel state — optional, all routers
channel_state_init_file: ''      # parquet: column Q; omit to default to zero
channel_state_final_file: ''     # omit to skip writing

# time — required for Muskingum; auto-detected for RapidMuskingum, UnitMuskingum
dt_routing: 0                    # seconds; routing sub-step (defaults to dt_runoff)
dt_total: 0                      # seconds; total duration (defaults to full input)
dt_discharge: 0                  # seconds; output timestep (defaults to dt_runoff)
dt_runoff: 0                     # seconds; auto-detected from input file if omitted
start_datetime: '1970-01-01'     # ISO date for output timestamps

# compute options — optional
runoff_processing_mode: 'sequential'   # sequential | ensemble
grid_accumulation_type: 'incremental' # incremental | cumulative

# logging — optional
log: true
progress_bar: true
log_level: 'PROGRESS'            # DEBUG | INFO | PROGRESS | WARNING | ERROR | CRITICAL
log_stream: 'stdout'             # stdout | /path/to/logfile.log
log_format: '%(levelname)s - %(asctime)s - %(message)s'

# variable names — optional; override if your files use different names
var_river_id: 'river_id'
var_discharge: 'Q'
var_grid_runoff: 'ro'
var_x: 'x'
var_y: 'y'
var_t: 'time'

Muskingum Config File

config_muskingum.yaml

# Muskingum config template — channel routing only, no lateral inflow

# required
params_file: ''                  # parquet: river_id, downstream_river_id, k, x
# where to save the outputs
# option 1: a directory where the output files will be named based on the input file routed
discharge_dir: ''                # directory for output netCDF files (named after input files)
# option 2: explicit output paths instead of discharge_dir
discharge_files:                 # optional: explicit output paths instead of discharge_dir
  - ''
dt_routing: 0                    # seconds; routing sub-step
dt_total: 0                      # seconds; total simulation duration
channel_state_init_file: ''      # parquet: column Q

# optional
channel_state_final_file: ''     # omit to skip writing
dt_discharge: 0                  # seconds; output timestep (defaults to dt_routing)
start_datetime: '1970-01-01'     # ISO date for output timestamps

# logging
log: true
progress_bar: true
log_level: 'PROGRESS'            # DEBUG | INFO | PROGRESS | WARNING | ERROR | CRITICAL
log_stream: 'stdout'             # stdout | /path/to/logfile.log
log_format: '%(levelname)s - %(asctime)s - %(message)s'

# variable names
var_river_id: 'river_id'
var_discharge: 'Q'
var_t: 'time'

Rapid Muskingum Config File

config_rapid_muskingum.yaml

# RapidMuskingum config template — direct runoff-to-channel routing

# required
params_file: ''                  # parquet: river_id, downstream_river_id, k, x
# where to save the outputs
# option 1: a directory where the output files will be named based on the input file routed
discharge_dir: ''                # directory for output netCDF files (named after input files)
# option 2: explicit output paths instead of discharge_dir
discharge_files:                 # optional: explicit output paths instead of discharge_dir
  - ''

# runoff input — choose one of two choices
# option 1: pre-aggregated per-catchment volumes (m³)
qlateral_files:                  # netCDF: dims (time, river_id); var: qlateral
  - ''
# option 2: gridded depths remapped to catchments (comment out option 1 to use)
# grid_runoff_files:
#   - ''
# grid_weights_file: ''          # required with grid_runoff_files

# channel state — optional
channel_state_init_file: ''      # parquet: column Q; omit to default to zero
channel_state_final_file: ''     # omit to skip writing

# time — optional; auto-detected from input file if omitted
dt_routing: 0                    # seconds; routing sub-step (defaults to dt_runoff)
dt_total: 0                      # seconds; total duration (defaults to full input)
dt_discharge: 0                  # seconds; output timestep (defaults to dt_runoff)
start_datetime: '1970-01-01'     # ISO date for output timestamps

# compute options
grid_accumulation_type: 'incremental' # incremental | cumulative
runoff_processing_mode: 'sequential'   # sequential | ensemble

# logging
log: true
progress_bar: true
log_level: 'PROGRESS'            # DEBUG | INFO | PROGRESS | WARNING | ERROR | CRITICAL
log_stream: 'stdout'             # stdout | /path/to/logfile.log
log_format: '%(levelname)s - %(asctime)s - %(message)s'

# variable names
var_river_id: 'river_id'
var_discharge: 'Q'
var_grid_runoff: 'ro'
var_x: 'x'
var_y: 'y'
var_t: 'time'

Unit Muskingum Config File

config_unit_muskingum.yaml

# UnitMuskingum config template — unit hydrograph transform then Muskingum routing

# required
params_file: ''                  # parquet: river_id, downstream_river_id, k, x
uh_kernel_file: ''      # scipy sparse npz: shape (n_basins, n_timesteps)

# where to save the outputs
# option 1: a directory where the output files will be named based on the input file routed
discharge_dir: ''                # directory for output netCDF files (named after input files)
# option 2: explicit output paths instead of discharge_dir
discharge_files:                 # optional: explicit output paths instead of discharge_dir
  - ''

# runoff input — choose one of two choices for RapidMuskingum, UnitMuskingum
# option 1: pre-aggregated per-catchment depths (m)
qlateral_files:                  # netCDF: dims (time, river_id); var: qlateral
  - ''
# option 2: gridded depths remapped to catchments (comment out option 1 to use)
grid_runoff_files:
  - ''
grid_weights_file: ''            # required with grid_runoff_files

# channel state — optional
channel_state_init_file: ''      # parquet: column Q; omit to default to zero
channel_state_final_file: ''     # omit to skip writing

# UH state — optional; for warm-starting across runs
uh_state_init_file: ''           # parquet: shape (n_basins, n_timesteps)
uh_state_final_file: ''          # omit to skip writing

# time — optional; auto-detected from input file if omitted
dt_routing: 0                    # seconds; routing sub-step (defaults to dt_runoff)
dt_total: 0                      # seconds; total duration (defaults to full input)
dt_discharge: 0                  # seconds; output timestep (defaults to dt_runoff)
start_datetime: '1970-01-01'     # ISO date for output timestamps

# compute options
grid_accumulation_type: 'incremental' # incremental | cumulative
runoff_processing_mode: 'sequential'   # sequential | ensemble

# logging
log: true
progress_bar: true
log_level: 'PROGRESS'            # DEBUG | INFO | PROGRESS | WARNING | ERROR | CRITICAL
log_stream: 'stdout'             # stdout | /path/to/logfile.log
log_format: '%(levelname)s - %(asctime)s - %(message)s'

# variable names
var_river_id: 'river_id'
var_discharge: 'Q'
var_grid_runoff: 'ro'
var_x: 'x'
var_y: 'y'
var_t: 'time'