Hydrological Network Routing

The module mogestpy.quantity.hydrological.routing combines local rainfall-runoff estimates from SMAP with upstream routing through the Muskingum method. It is imported lazily, so users can load it only when a network simulation is required.

from mogestpy.quantity.hydrological.routing import run_network

Input Data

The function run_network expects three pandas.DataFrame objects:

params: One row per subcatchment. Required columns are id, area, str, crec, capc, kkt, k2t, ai, tuin, ebin, k, x and downstream_id.
precipitation: Time series with one column per subcatchment ID. Values are precipitation depths in millimetres per time step.
evapotranspiration: Time series with one column per subcatchment ID. Values are potential evapotranspiration depths in millimetres per time step.

Parameter Table Format

id: Unique subcatchment identifier. The value must also exist as a column in the precipitation and evapotranspiration DataFrames.
area: Drainage area in square kilometres.
str, crec, capc, kkt, k2t, ai, tuin and ebin: SMAP parameters. tuin must be informed as a percentage from 0 to 100; the routing module converts it to the fraction expected by SmapD.
k and x: Muskingum routing parameters. k must be non-negative and must be positive for basins that receive upstream flow. x must be between 0 and 0.5.
downstream_id: Identifier of the directly downstream subcatchment. Use a null value for an outlet basin.

Example

import numpy as np
import pandas as pd

from mogestpy.quantity.hydrological.routing import run_network

params = pd.DataFrame(
    {
        "id": ["headwater", "outlet"],
        "area": [513.37, 400.0],
        "str": [1559.91, 1200.0],
        "crec": [0.25, 0.2],
        "capc": [40.0, 40.0],
        "kkt": [83.63, 70.0],
        "k2t": [6.49, 5.5],
        "ai": [2.5, 2.5],
        "tuin": [50.0, 45.0],
        "ebin": [11.05, 8.0],
        "k": [1.0, 1.0],
        "x": [0.2, 0.2],
        "downstream_id": ["outlet", np.nan],
    }
)

index = pd.date_range("2026-01-01", periods=3, freq="D")
precipitation = pd.DataFrame(
    {
        "headwater": [0.0, 5.0, 0.0],
        "outlet": [0.0, 3.0, 1.0],
    },
    index=index,
)
evapotranspiration = pd.DataFrame(
    {
        "headwater": [4.5, 4.5, 4.5],
        "outlet": [4.5, 4.5, 4.5],
    },
    index=index,
)

discharge = run_network(params, precipitation, evapotranspiration)

Output Data

The result is a pandas.DataFrame indexed by the common time steps shared by precipitation and evapotranspiration. Each column is a subcatchment ID, and values are simulated discharge in cubic metres per second.

Validation

The module validates required parameter columns, duplicated IDs, invalid downstream_id references, network cycles, missing forcing columns, null forcing values and non-numeric forcing values before running the simulation.