HydPy-G-GR5 (Génie Rural model with 5 parameters)

The GR5 model (modèle du Génie Rural à 5 parametres Journalier) is a daily lumped five-parameter rainfall-runoff model and belongs to the family of soil moisture accounting models. It was initially published by Le Moine (2008) and is a modification of GR4J. Our implementation, gland_gr5, follows the one of the R package airGR (Coron et al., 2017) but with a few extensions that we explain in the documentation of gland_gr4, which implements and extends GR4J.

The main differences between GR5 and GR4 are that GR5 only applies a single Unit Hydrograph and uses a fifth parameter, X5, to allow for a more flexible configuration of the groundwater exchange term. In gland_gr5, one can choose between different types of runoff concentration submodels, as explained for gland_gr4.

The following figure (Coron et al., 2023) shows the general structure of gland_gr5:

_images/HydPy-G-GR5.png

Integration tests

Note

When new to HydPy, consider reading section Integration Tests first.

The settings of the following tests are similar to the ones of application model gland_gr4. Hence, comparing the test results gives a good impression of the functional differences between both models.

The following settings are identical:

>>> from hydpy import pub
>>> pub.timegrids = "1990-01-01", "1990-02-20", "1d"

>>> from hydpy.models.gland_gr5 import *
>>> parameterstep("1d")
>>> from hydpy import Element
>>> land = Element("land", outlets="outlet")
>>> land.model = model

>>> area(360.0)

>>> with model.add_petmodel_v1("evap_ret_io"):
...     evapotranspirationfactor(1.0)

>>> from hydpy import IntegrationTest
>>> test = IntegrationTest(land)
>>> test.plotting_options.axis1 = inputs.p, fluxes.e, fluxes.qh
>>> test.dateformat = "%d.%m."

>>> inputs.p.series = (
...     0.0, 9.3, 3.2, 7.3, 0.0, 0.0, 0.0, 0.0, 0.1, 0.2, 2.9, 0.2, 0.0, 0.0, 0.0, 3.3,
...     4.6, 0.8, 1.8, 1.1, 0.0, 5.0, 13.1, 14.6, 4.0, 0.8, 0.1, 3.3, 7.7, 10.3, 3.7,
...     15.3, 3.2, 2.7, 2.2, 8.0, 14.3, 6.3, 0.0, 5.9, 9.2, 6.1, 0.1, 0.0, 2.8, 10.6,
...     8.8, 7.2, 4.9, 1.8
... )
>>> model.petmodel.sequences.inputs.referenceevapotranspiration.series = (
...     0.3, 0.4, 0.4, 0.3, 0.1, 0.1, 0.1, 0.2, 0.2, 0.3, 0.3, 0.2, 0.2, 0.2, 0.2, 0.3,
...     0.3, 0.2, 0.2, 0.3, 0.2, 0.2, 0.3, 0.6, 0.4, 0.4, 0.4, 0.5, 0.4, 0.3, 0.3, 0.5,
...     0.5, 0.3, 0.3, 0.4, 0.4, 0.3, 0.2, 0.1, 0.1, 0.0, 0.1, 0.1, 0.0, 0.2, 0.9, 0.9,
...     0.5, 0.9
... )

base example

The following parameter values do not agree with the ones of the base example on application model gland_gr4 but with the ones of the example given by Coron et al. (2023):

>>> imax(0.0)
>>> x1(245.918)
>>> x2(1.027)
>>> x3(90.017)
>>> x5(0.434)

>>> with model.add_rconcmodel_v1("rconc_uh"):
...     uh("gr_uh2", x4=2.198)

>>> test.inits = (
...     (states.i, 0.0),
...     (states.s, 0.3 * x1),
...     (states.r, 0.5 * x3),
...     (model.rconcmodel.sequences.logs.quh, 0.0),
... )

The following simulation results agree with those of the GR5J airGR implementation:

>>> conditions = test("gland_gr5_base_example", get_conditions="1990-01-01")
Click to see the table
Click to see the graph

There is no indication of an error in the water balance:

>>> from hydpy import round_
>>> round_(model.check_waterbalance(conditions))
0.0

groundwater loss

This integration test corresponds to the groundwater loss example on gland_gr4:

>>> x2(-1.027)
>>> test.inits.s = 0.0
>>> test.inits.r = 0.0

>>> conditions = test("gland_gr5_groundwater_loss", get_conditions="1990-01-01")
Click to see the table
Click to see the graph

There is no indication of an error in the water balance:

>>> round_(model.check_waterbalance(conditions))
0.0

interception

This integration test corresponds to the interception example on gland_gr4:

>>> imax(10.0)
>>> x2(1.027)
>>> test.inits.s = 0.3 * x1
>>> test.inits.r = 0.5 * x3

>>> conditions = test("gland_gr5_interception", get_conditions="1990-01-01")
Click to see the table
Click to see the graph

There is no indication of an error in the water balance:

>>> round_(model.check_waterbalance(conditions))
0.0

no rconc submodels

This integration test corresponds to the no rconc submodels example on gland_gr4:

>>> model.rconcmodel = None

>>> conditions = test("gland_gr5_no_rconc_submodels", get_conditions="1990-01-01")
Click to see the table
Click to see the graph

There is no indication of an error in the water balance:

>>> round_(model.check_waterbalance(conditions))
0.0
class hydpy.models.gland_gr5.Model[source]

Bases: Main_PETModel_V1, Main_RConcModel_V1

HydPy-G-GR5 (Génie Rural model with 5 parameters).

The following “run methods” are called in the given sequence during each simulation step:

  • Calc_E_V1 Let a submodel that conforms to the PETModel_V1 interface calculate the potential evapotranspiration.

  • Calc_EI_V1 Calculate the actual evaporation from the interception store.

  • Calc_PN_V1 Calculate the net precipitation by considering all interception losses.

  • Calc_EN_V1 Calculate the net evapotranspiration capacity by considering interception evaporation.

  • Update_I_V1 Update the interception store based on precipitation, net precipitation, and interception evaporation.

  • Calc_PS_V1 Calculate the part of net precipitation filling the production store.

  • Calc_ES_V1 Calculate the actual evapotranspiration from the production store.

  • Update_S_V1 Update the production store by adding precipitation and evapotranspiration.

  • Calc_Perc_V1 Calculate the percolation from the production store.

  • Update_S_V2 Update the production store by subtracting percolation.

  • Calc_AE_V1 Calculate the total actual evapotranspiration.

  • Calc_Pr_V1 Calculate the total inflow into the runoff concentration module.

  • Calc_Q10_V1 Transform PR into Q10.

  • Calc_Q1_Q9_V2 Calculate Q1 and Q9 by splitting Q10.

  • Calc_FR_V2 Calculate the groundwater exchange affecting the routing store according to GR5 and GR6.

  • Update_R_V1 Update the level of the non-linear routing store by adding its inflows according to GR4 and GR5.

  • Calc_QR_V1 Calculate the outflow of the routing store.

  • Update_R_V3 Update the non-linear routing store by subtracting its outflow.

  • Calc_FD_V1 Calculate the groundwater exchange affecting the direct runoff.

  • Calc_QD_V1 Calculate the direct runoff.

  • Calc_QH_V1 Calculate the total runoff according to GR4 and GR5.

  • Calc_QV_V1 Calculate total discharge in m³/s.

The following “outlet update methods” are called in the given sequence at the end of each simulation step:
The following “additional methods” might be called by one or more of the other methods or are meant to be directly called by the user:
Users can hook submodels into the defined main model if they satisfy one of the following interfaces:

  • PETModel_V1 Simple interface for calculating all potential evapotranspiration values in one step.

  • RConcModel_V1 Simple interface for calculating runoff concentration processes.

DOCNAME: DocName = ('G-GR5', 'Génie Rural model with 5 parameters')
petmodel: modeltools.SubmodelProperty

Required submodel that complies with the following interface: PETModel_V1.

rconcmodel: modeltools.SubmodelProperty

Optional submodel that complies with the following interface: RConcModel_V1.

check_waterbalance(initial_conditions: dict[str, dict[str, dict[str, float | ndarray[tuple[int, ...], dtype[float64]]]]]) → float[source]

Determine the water balance error of the previous simulation run in mm.

Method check_waterbalance() calculates the balance error as follows:

\[\begin{split}Error = \Sigma InOut - \Delta Vol - \Delta Rconc \\ \\ \Sigma InOut = \sum_{t=t0}^{t1} P_t - AE_t + FR_t + FD_t - QH_t \\ \Delta Vol = \left( I_{t1} - I_{t0} \right) + \left( S_{t1} - S_{t0} \right) + \left( R_{t1} - R_{t0} \right) \\ \Delta Rconc = get\_waterbalance_{runof\!f \ concentration}(*)\end{split}\]
REUSABLE_METHODS: ClassVar[tuple[type[ReusableMethod], ...]] = ()
class hydpy.models.gland_gr5.ControlParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: SubParameters

Control parameters of model gland_gr5.

The following classes are selected:

  • Area() Subbasin area [km²].

  • IMax() Interception store capacity [mm].

  • X1() Maximum capacity of the production storage [mm].

  • X2() Groundwater exchange coefficient (positive for water imports, negative for exports) [mm/T].

  • X3() One timestep ahead maximum capacity of the routing store [mm].

  • X5() Intercatchment exchange threshold [-].

class hydpy.models.gland_gr5.DerivedParameters(master: Parameters, cls_fastaccess: type[FastAccessParameter] | None = None, cymodel: CyModelProtocol | None = None)

Bases: SubParameters

Derived parameters of model gland_gr5.

The following classes are selected:

  • Beta() Percolation factor [T].

  • QFactor() Factor for converting mm/stepsize to m³/s.

class hydpy.models.gland_gr5.FluxSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: FluxSequences

Flux sequences of model gland_gr5.

The following classes are selected:

  • E() Potential evapotranspiration [mm/T].

  • EN() Net evapotranspiration capacity [mm/T].

  • PN() Net precipitation [mm/T].

  • PS() Part of PN filling the production store [mm/T].

  • EI() Actual evaporation from the interception store [mm/T].

  • ES() Actual evapotranspiration from the production store [mm/T].

  • AE() Total actual evapotranspiration [mm/T].

  • PR() Total inflow into the runoff concentration module [mm/T].

  • Q10() Total outflow of runoff concentration module [mm/T].

  • Perc() Percolation [mm/T].

  • Q9() Outflow of runoff concentration submodel receiving PR9 [mm/T].

  • Q1() Outflow of runoff concentration submodel receiving PR1 [mm/T].

  • FD() Groundwater exchange affecting the direct runoff [mm/T].

  • FR() Groundwater exchange affecting the routing store [mm/T].

  • QR() Outflow of the routing store [mm/T].

  • QD() Direct runoff [mm/T].

  • QH() Total runoff [mm/T].

  • QV() Total discharge [m³/s].

class hydpy.models.gland_gr5.InputSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: InputSequences

Input sequences of model gland_gr5.

The following classes are selected:

  • P() Precipitation [mm/T].

class hydpy.models.gland_gr5.OutletSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: OutletSequences

Outlet sequences of model gland_gr5.

The following classes are selected:

  • Q() Runoff [m³/s].

class hydpy.models.gland_gr5.StateSequences(master: Sequences, cls_fastaccess: type[TypeFastAccess_co] | None = None, cymodel: CyModelProtocol | None = None)

Bases: StateSequences

State sequences of model gland_gr5.

The following classes are selected:

  • I() Water content of the interception store [mm].

  • S() Water content of the production store [mm].

  • R() Water content of the routing store [mm].