.. _Lake_res_model: Lake and Reservoir Models ========================= To simulate lakes, the variable ```` in the control file **must be set to true**. By default, this flag is set to ``false``; therefore, unless explicitly specified, ``mizuRoute`` does not simulate lakes. Instead, ``mizuRoute`` treats lakes as regular river reaches, using the provided reach length or slope from the network topology file. If these values are unavailable, default parameters are applied—typically a reach length of 100 meters or a minimum slope value (e.g., 0.00001)—for lake elements represented as river segments. .. list-table:: Global control keys for lake simulation :header-rows: 1 :widths: 20 15 15 50 :name: lake-global-flags * - Control key - Type - Default - Description * - ```` - Logical (Global Flag) - ``F`` - Indicates whether lakes are simulated. * ``F`` → lakes are not simulated. * ``T`` → lakes are included in the routing. * - ```` - Logical (Global Flag) - ``T`` - Controls whether all lakes are treated as natural or regulated. * ``F`` → all lakes are treated as natural (``lakeType = 1``) regardless of individual ``lakeModelType``. * ``T`` → regulation is applied (default). * - ```` - Integer (Global Flag) - ``0`` - Selects the type of fluxes used in lake simulation: * ``0`` → evaporation + precipitation (default, ignores runoff provided for lakes and reservoirs) * ``1`` → runoff (for cases that simulated runoff account for processes such as snow melt, ice formation, etc – resolving lakes and reservoirs water and energy balances in land surface model for example) * ``2`` → evaporation + precipitation + runoff The following variables need to be specified in the network topology file for each element of network topology that is identified as lake. .. list-table:: Lake-related control keys in the network topology file :widths: 20 20 15 15 15 30 :header-rows: 1 :name: lake-individual-flags * - Control key - Type - Variable type - Variable dimension - Variable unit - Description * - ```` - NetCDF variable name - int - seg - flag (0/1) - Flag to define whether the segment is a lake (``1`` = lake, ``0`` = reach). * - ```` - NetCDF variable name - int - seg - categorical - Defines the lake model type for the segment: ``0`` = Endorheic, ``1`` = Döll, ``2`` = Hanasaki, ``3`` = HYPE. * - ```` - NetCDF variable name - int - seg - flag (0/1) - Flag to follow the provided target volume for the lake (``1`` = yes, ``0`` = no). The variable defined by ``varname_islake`` identifies whether a river network element is classified as a lake or reservoir within the routing topology. The variable defined by ``varname_lakeModelType`` specifies the lake model type, including endorheic (closed) systems or one of the parametric lake formulations implemented in mizuRoute. In addition, when the water management option is enabled (see :ref:`WaterManagement_file`), the lake or reservoir simulation can be driven by externally provided target storage values. In this case, the variable ``vname_vol_wm`` is used to prescribe time series of target volumes (in m³), which override the default parametric lake formulation and force the system to follow the externally specified reservoir operation behavior. For further reading about the below formulation, please see `Gharari et al., 2024 `_. .. _Lake_model_Endorheic: Endorheic (closed) model ------------------------ This lake type represents **endorheic or closed lakes**, where **outflow is set to zero**. Water enters the lake only from upstream river segments or direct precipitation and is lost through **evaporation** or **water abstraction**. This model does not require any specific parameters. To designate a lake as endorheic, set the corresponding flag in the network topology file to ``0`` (variable identified by ````). .. _Lake_parametric_models: Lake and reservoir parametric models ------------------------------------ .. _Lake_model_Doll: Storage-based model (Döll) ^^^^^^^^^^^^^^^^^^^^^^^^^^ The least complex lake model in *mizuRoute-Lake* is the Döll formulation (based on Döll, 2003; Hanasaki, 2006). The Döll formulation links the outflow from the lake to the ratio of active storage to maximum active storage through a power function. .. list-table:: Doll lake model control keys for variables in the network topology file :widths: 20 20 15 15 15 30 :header-rows: 1 :name: lake-doll-parameters * - Control key - Type - Variable type - Variable dimension - Variable unit - Description * - ```` - NetCDF variable name - real - seg - m³ - Maximum active storage for Döll formulation. * - ```` - NetCDF variable name - real - seg - d⁻¹ - Release coefficient for Döll formulation. * - ```` - NetCDF variable name - real - seg - – - Power scaling exponent for Döll formulation. * - ```` - NetCDF variable name - real - seg - m³ - Inactive storage for Döll formulation. For the case when the storage is larger than inactive storage, :math:`S_0 < S`, the outflow is calculated as: .. math:: :name: lake-doll-equation O = K \, (S - S_0) \left( \frac{S - S_0}{S_{\text{max}} - S_0} \right)^P Outflow is set to zero, :math:`O = 0`, when the storage is equal to or smaller than inactive storage, :math:`S <= S0`. Where: - :math:`O` = outflow from the lake segment - :math:`S` = storage of the lake segment - :math:`S_0` = inactive storage of the lake segment (network topology variable name is identified by control key ````) - :math:`S_{\text{max}}` = maximum active storage of the lake segment (network topology variable name is identified by control key ````) - :math:`K` = release coefficient (network topology variable name is identified by control key ````) - :math:`P` = power scaling exponent (network topology variable name is identified by control key ````) .. _Lake_model_Hanasaki: Demand-based model (Hanasaki) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The Hanasaki 2006 formulation represents reservoirs with explicit consideration of water demand. It calculates target release based on storage, inflow, and demand, differentiating between “within-a-year” and “multi-year” reservoirs. .. list-table:: Hanasaki lake model control keys for variables in the network topology file :widths: 20 20 15 15 15 30 :header-rows: 1 :name: lake-hanasaki-parameters * - Control key - Type - Variable type - Variable dimension - Variable unit - Description * - ```` - NetCDF variable name - real - seg - m³ - Maximum reservoir storage * - ```` - NetCDF variable name - real - seg - – - Fraction of active storage compared to total storage * - ```` - NetCDF variable name - real - seg - – - Fraction of inflow that can be used to meet demand * - ```` - NetCDF variable name - real - seg - m³ - Initial storage used for estimating release coefficient * - ```` - NetCDF variable name - real - seg - – - Coefficient 1 for target release for irrigation reservoir * - ```` - NetCDF variable name - real - seg - – - Coefficient 2 for target release for irrigation reservoir * - ```` - NetCDF variable name - real - seg - – - Exponent for actual release for “within-a-year” reservoir * - ```` - NetCDF variable name - real - seg - – - Denominator of actual release for “within-a-year” reservoir * - ```` - NetCDF variable name - real - seg - – - Criterion to distinguish “within-a-year” vs “multi-year” reservoir * - ```` - NetCDF variable name - real - seg - – - Fraction of dead storage to maximum storage * - ```` - NetCDF variable name - real - seg - – - Initial release coefficient * - ```` … ```` - NetCDF variable name - real - seg - m³ s⁻¹ - Average monthly inflow for each month * - ```` … ```` - NetCDF variable name - real - seg - m³ s⁻¹ - Average monthly demand for each month * - ```` - NetCDF variable name - int - seg - – - Reservoir purpose flag (0 = non-irrigation, 1 = irrigation) * - ```` - NetCDF variable name - int - seg - – - Flag to transition to modelled inflow * - ```` - NetCDF variable name - int - seg - – - Flag to transition to modelled/provided demand * - ```` - NetCDF variable name - int - seg - year - Memory length in years for inflow * - ```` - NetCDF variable name - int - seg - year - Memory length in years for demand .. _Lake_model_HYPE: Elevation-based model (Hydropower Reservoir Formulation from HYPE) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The HYPE formulation describes the representation of a hydropower reservoir in *mizuRoute-Lake*. This includes parameters for spillways, turbine operations, and reservoir management rules. .. list-table:: HYPE lake model control keys for variables in the network topology file :widths: 20 20 15 15 15 30 :header-rows: 1 :name: lake-hype-parameters * - Control key - Type - Variable type - Variable dimension - Variable unit - Description * - ```` - NetCDF variable name - real - seg - m - Elevation of emergency spillway * - ```` - NetCDF variable name - real - seg - m - Elevation below which primary spillway flow is restricted * - ```` - NetCDF variable name - real - seg - m - Elevation below which outflow is zero * - ```` - NetCDF variable name - real - seg - m - Elevation at which lake/reservoir storage is zero * - ```` - NetCDF variable name - real - seg - m³ s⁻¹ - Emergency rate of flow for each unit of elevation above HYP_E_emr * - ```` - NetCDF variable name - real - seg - – - Power for the emergency spillway exponential flow curve * - ```` - NetCDF variable name - real - seg - m³ s⁻¹ - Average yearly/long-term output from primary spillway * - ```` - NetCDF variable name - real - seg - – - Amplitude of the primary spillway outflow * - ```` - NetCDF variable name - int - seg - – - Phase of the primary spillway outflow (day of year; default = 100) * - ```` - NetCDF variable name - int - seg - – - Reservoir primary spillway flag (1 if present, else 0) * - ```` - NetCDF variable name - real - seg - m² - Average area of lake (unused if bathymetry is provided) * - ```` - NetCDF variable name - int - seg - – - Outflow calculation mode (1 = sum of emergency + primary spillway; else = maximum of emergency or primary spillway) For hydropower reservoirs, a sinusoidal function defines the target hydropower production outflow. This function is shifted in time based on a day of the year, :math:`B_{\mathrm{phase}}`, as: .. math:: :label: HYPE_sin_equation F_{\mathrm{sin}} = \max \Big(0, 1 + A_{\mathrm{amp}} \sin\Big(\frac{2 \pi D_{\mathrm{julian}} + B_{\mathrm{phase}}}{365}\Big) \Big) Next, the limiting factor is defined when the lake elevation is between :math:`E_{\mathrm{prim}}` and :math:`E_{\mathrm{lim}}`. The linear scaling for restricted hydropower production is: .. math:: :label: HYPE_lim_equation F_{\mathrm{lim}} = \min \Big( \max \Big( \frac{E - E_{\mathrm{prim}}}{E_{\mathrm{lim}} - E_{\mathrm{prim}}}, 0 \Big), 1 \Big) If the water level is below :math:`E_{\mathrm{prim}}`, :math:`F_{\mathrm{lim}} = 0`. If the water level is above :math:`E_{\mathrm{lim}}`, :math:`F_{\mathrm{lim}} = 1`. The production outflow for hydropower is then calculated as: .. math:: :label: HYPE_main_equation Q_{\mathrm{main}} = F_{\mathrm{sin}} \, F_{\mathrm{lim}} \, F_{\mathrm{managed}} \, Q_{\mathrm{avg,rate}} If the reservoir elevation, :math:`E`, exceeds the emergency spillway elevation, :math:`E_{\mathrm{emg}}`, the emergency spillway is activated: .. math:: :label: HYPE_emg_equation Q_{\mathrm{emg}} = Q_{\mathrm{emg,rate}} (E - E_{\mathrm{emg}})^{P_{\mathrm{emg}}} Finally, the outflow from the reservoir is either the maximum of :math:`Q_{\mathrm{emg}}` and :math:`Q_{\mathrm{main}}` or their summation (depending on mizuRoute settings): .. math:: :label: HYPE_outflow_equation O = \max(Q_{\mathrm{emg}}, Q_{\mathrm{main}}) Where the parameters are defined as: - :math:`A_{\mathrm{amp}}` = amplitude of the sinusoidal function (network topology variable name is identified by control key ````) - :math:`B_{\mathrm{phase}}` = phase shift for the sinusoidal function (network topology variable name is identified by control key ````) - :math:`E_{\mathrm{prim}}` = primary spillway elevation (flow restricted below this) (network topology variable name is identified by control key ````) - :math:`E_{\mathrm{lim}}` = elevation at which primary spillway flow is unrestricted (network topology variable name is identified by control key ````) - :math:`F_{\mathrm{managed}}` = management factor (optional control) (network topology variable name is identified by control key ````) - :math:`Q_{\mathrm{avg,rate}}` = average rated outflow of primary spillway/turbine (network topology variable name is identified by control key ````) - :math:`Q_{\mathrm{emg,rate}}` = emergency spillway flow coefficient (network topology variable name is identified by control key ````) - :math:`P_{\mathrm{emg}}` = emergency spillway exponent (network topology variable name is identified by control key ````) - :math:`D_{\mathrm{julian}}` = Julian day of the year - :math:`E` = reservoir elevation - :math:`F_{\mathrm{sin}}` = sinusoidal target flow fraction - :math:`F_{\mathrm{lim}}` = limiting factor due to reservoir elevation - :math:`Q_{\mathrm{emg}}` = emergency spillway outflow - :math:`Q_{\mathrm{main}}` = main hydropower production outflow - :math:`O` = final outflow from the reservoir (m³/s) (network topology variable name is identified by control key ````) .. _Lake_Target_Volume: Lake Target Volume ------------------ To accommodate more complex lake and reservoir behavior, each lake can optionally be assigned a target volume time series. Lakes using this functionality are specified in the network topology file using the flag ````. In addition, the corresponding target volume time series must be provided in the optional water management input files (see :ref:`WaterManagement_file`). This capability allows representation of dynamics that are not captured by the parametric lake models, such as rule curves (provided as time series) or more complex reservoir drawdown operations. It also enables integration of external data sources, including in situ lake level measurements, storage estimates, or remote sensing products (e.g., satellite altimetry-derived storage changes). The target volume operation follows a simple rule: 1. If lake or reservoir storage is **below** the target volume, outflow is restricted to retain water in storage. 2. If lake or reservoir storage is **above** the target volume, excess water is released downstream. .. note:: Target volume scheme may introduce numerical uncertainties, particularly under rapidly varying flow conditions. Care should be taken when interpreting results. .. _Lake_Abstraction: Lake Abstraction ---------------- mizuRoute also provides the capability, in addition to parametric lake or reservoir simulations, to account for time series of water abstraction from or injection into a lake. This functionality enables more flexible reservoir modeling, for example in systems with multiple outlets, where one outlet can be represented using a parametric formulation while another can be emulated using a prescribed release time series. Furthermore, more complex hydrological fluxes, such as interactions between lake or reservoir storage and external hydrological processes or groundwater dynamics, can be represented within this framework. To use this functionality, the optional water management input file and its associated control keys must be activated (see :ref:`WaterManagement_file`).