Exponential store gr6

doc/source/_static/bib/references.bib

@@ -1258,6 +1258,34 @@ @article{todini1996arno
   abstract = {This paper describes in detail a semi-distributed conceptual rainfall-runoff model known as the ARNO model, which is now in widespread use both in land-surface-atmosphere process research and as an operational flood forecasting tool on several catchments in different parts of the world. The model, which derives its name from its first application to the Arno River, incorporates the concepts of a spatial probability distribution of soil moisture capacity and of dynamically varying saturated contributing areas. The ARNO model is characterized by two main components: the first and most important component represents the soil moisture balance, and the second describes the transfer of runoff to the outlet of the basin. The relevance of the soil component emerges from the highly nonlinear mechanism with which the soil moisture content and its distribution controls the dynamically varying size of the saturated areas mainly responsible for a direct conversion of rainfall into runoff. The second component describes the way in which runoff is routed and transferred along the hillslopes to the drainage channels and along the channel network to the outlet of the basin. Additional components, such as the evapotranspiration, snowmelt and groundwater modules, are also described. A discussion on the advantages of the model, calibration requirements and techniques is also presented, together with the physical interpretation of model parameters. Finally, after describing the original calibration of the ARNO model on the Arno basin, and a comparison with several conceptual models, recent applications of the ARNO model, as part of a real-time flood forecasting system, as a tool for investigating land use changes and as an interesting approach to the evaluation of land-surface-atmosphere interactions at general circulation model (GCM) scale, are illustrated.}
 }
 
+@article{pushpalatha,
+  TITLE = {{A downward structural sensitivity analysis of hydrological models to improve low-flow simulation}},
+  AUTHOR = {Pushpalatha, Raji and Perrin, Charles and Le Moine, Nicolas and Mathevet, Thibault and Andr{\'e}assian, Vazken},
+  URL = {https://hal.science/hal-04110441},
+  JOURNAL = {{Journal of Hydrology}},
+  VOLUME = {411},
+  PAGES = {66-76},
+  YEAR = {2011},
+  DOI = {10.1016/j.jhydrol.2011.09.034},
+  KEYWORDS = {Earth Science},
+  HAL_ID = {hal-04110441},
+  HAL_VERSION = {v1},
+}
+
+@article{michel2003,
+  TITLE = {{The exponential store: a correct formulation for rainfall-runoff modelling}},
+  AUTHOR = {Michel, Claude and Perrin, Charles and Andr{\'e}assian, Vazken},
+  URL = {https://hal.inrae.fr/hal-02581237},
+  NOTE = {[Departement\_IRSTEA]GMA [TR1\_IRSTEA]11 - VERSEAU / TRANSFEAU},
+  JOURNAL = {{Journal des sciences hydrologiques}},
+  VOLUME = {48},
+  NUMBER = {1},
+  PAGES = {109-124},
+  YEAR = {2003},
+  KEYWORDS = {CEMAGREF ; QHAN ; TOPMO},
+  HAL_ID = {hal-02581237},
+  HAL_VERSION = {v1},
+}
 
 @book{monnier2021coursevariational,
   title={Data Assimilation - Inverse Problems, Assimilation, Control, Learning},

doc/source/math_num_documentation/forward_structure.rst

@@ -350,6 +350,152 @@ Hydrological processes can be described at pixel scale in `smash` with one of th
 
     Same as ``gr4`` transfer, see :ref:`GR4 Transfer <math_num_documentation.forward_structure.hydrological_module.gr4>`
 
+
+.. _math_num_documentation.forward_structure.hydrological_module.gr6:
+
+
+.. dropdown:: gr6 (Génie Rural 6)
+    :animate: fade-in-slide-down
+
+    This hydrological module is derived from the GR6 model :cite:p:`michel2003` and :cite:p:`pushpalatha`.
+
+    .. hint::
+
+        Helpful links about GR:
+
+        - `Brief history of GR models <https://webgr.inrae.fr/models/a-brief-history/>`__
+        - `Scientific papers <https://webgr.inrae.fr/publications/articles/>`__
+        - `GR models in a R package <https://hydrogr.github.io/airGR/>`__
+
+    .. figure:: ../_static/gr6_structure.svg
+        :align: center
+        :width: 400
+
+        Diagram of the ``gr6`` like hydrological operator
+
+    It can be expressed as follows:
+
+    .. math::
+
+        q_{t}(x, t) = f\left(\left[P, E\right](x, t), m_{lt}(x, t), \left[c_i, c_p, c_t, b_e, k_{exc}, a_{exc}\right](x), \left[h_i, h_p, h_t, h_e\right](x, t)\right)
+
+    with :math:`q_{t}` the elemental discharge, :math:`P` the precipitation, :math:`E` the potential evapotranspiration,
+    :math:`m_{lt}` the melt flux from the snow module, :math:`c_i` the maximum capacity of the interception reservoir,
+    :math:`c_p` the maximum capacity of the production reservoir, :math:`c_t` the maximum capacity of the transfer reservoir,
+    :math:`b_e` controls the slope of the recession, 
+    :math:`k_{exc}` the exchange coefficient, :math:`a_{exc}` the exchange threshold, :math:`h_i` the state of the interception reservoir, 
+    :math:`h_p` the state of the production reservoir and :math:`h_t` the state of the transfer reservoir,
+    :math:`h_e` the state of the exponential reservoir.
+
+    .. note::
+
+        Linking with the forward problem equation :ref:`Eq. 1 <math_num_documentation.forward_inverse_problem.forward_problem_M_1>`
+
+        - Internal fluxes, :math:`\{q_{t}, m_{lt}\}\in\boldsymbol{q}`
+        - Atmospheric forcings, :math:`\{P, E\}\in\boldsymbol{\mathcal{I}}`
+        - Parameters, :math:`\{c_i, c_p, c_t, b_e, k_{exc}, a_{exc}\}\in\boldsymbol{\theta}`
+        - States, :math:`\{h_i, h_p, h_t, h_e\}\in\boldsymbol{h}`
+
+    The function :math:`f` is resolved numerically as follows:
+
+
+    **Interception**
+
+    Same as ``gr4`` interception, see :ref:`GR4 Interception <math_num_documentation.forward_structure.hydrological_module.gr4>`
+
+    **Production**
+
+    Same as ``gr4`` production, see :ref:`GR4 Production <math_num_documentation.forward_structure.hydrological_module.gr4>`
+
+    **Exchange**
+
+    Same as ``gr5`` exchange, see :ref:`GR5 Production <math_num_documentation.forward_structure.hydrological_module.gr5>`
+
+    **Transfer**
+
+    - Split the production runoff :math:`p_r` into three branches (transfer, exponential and direct), :math:`p_{rr}`, :math:`p_{re}` and :math:`p_{rd}`
+
+    .. math::
+        :nowrap:
+
+        \begin{eqnarray}
+
+            &p_{rr}(x, t)& &=& &0.6 \times 0.9(p_r(x, t) + p_{erc}(x, t)) + l_{exc}(x, t)\\
+            &p_{re}(x, t)& &=& &0.4 \times 0.9(p_r(x, t) + p_{erc}(x, t)) + l_{exc}(x, t)\\
+            &p_{rd}(x, t)& &=& &0.1(p_r(x, t) + p_{erc}(x, t))
+
+        \end{eqnarray}
+
+    - Update the transfer reservoir state :math:`h_t`
+
+    .. math::
+
+        h_t(x, t^*) = \max\left(0, h_t(x, t - 1) + \frac{p_{rr}(x, t)}{c_t(x)}\right)
+
+    - Compute the transfer branch elemental discharge :math:`q_r`
+
+    .. math::
+        :nowrap:
+
+        \begin{eqnarray}
+
+            q_r(x, t) = h_t(x, t^*)c_t(x) - \left(\left(h_t(x, t^*)c_t(x)\right)^{-4} + c_t(x)^{-4}\right)^{-1/4}
+
+        \end{eqnarray}
+
+    - Update the transfer reservoir state :math:`h_t`
+
+    .. math::
+
+        h_t(x, t) = h_t(x, t^*) - \frac{q_r(x, t)}{c_t(x)}
+
+
+    - Update the exponential state :math:`h_e`
+
+    .. math::
+
+        h_e(x, t^*) = h_e(x, t - 1) + p_{re}
+
+    - Compute the exponential branch elemental discharge :math:`q_{e}`
+
+    .. math::
+        :nowrap:
+
+        \begin{eqnarray}
+
+            q_{e}(x, t) =
+            \begin{cases}
+
+                b_e(x) \ln \left( 1 + \exp \left( \frac{h_e(x, t^*)}{b_e(x)} \right) \right) &\text{if} \; -7 \lt \frac{h_e(x, t^*)}{b_e(x)} \lt 7 \\
+
+                b_e(x) * \exp \left( \frac{h_e(x, t^*)}{b_e(x)} \right) &\text{if} \; \frac{h_e(x, t^*)}{b_e(x)} \lt -7 \\
+
+                h_e(x, t^*) + \frac{ b_e(x) }{ \exp \left( \frac{h_e(x, t^*)}{b_e(x)} \right) } \; &\text{otherwise}.
+
+            \end{cases}
+
+        \end{eqnarray}
+
+    - Update the exponential reservoir state :math:`h_e`
+
+    .. math::
+
+        h_e(x, t) = h_e(x, t^*) - q_{e}
+
+
+    - Compute the direct branch elemental discharge :math:`q_d`
+
+    .. math::
+
+        q_d(x, t) = \max(0, p_{rd}(x, t) + l_{exc}(x, t))
+
+    - Compute the elemental discharge :math:`q_t`
+
+    .. math::
+
+        q_t(x, t) = q_r(x, t) + q_{e}(x, t) + q_d(x, t) 
+
+
 .. _math_num_documentation.forward_structure.hydrological_module.grd:
 
 .. dropdown:: grd (Génie Rural Distribué)

smash/_constant.py

@@ -42,7 +42,7 @@ def get_rr_internal_fluxes_from_structure(structure: str) -> list[str]:
 
 SNOW_MODULE = ["zero", "ssn"]
 
-HYDROLOGICAL_MODULE = ["gr4", "gr5", "grd", "loieau", "vic3l"]
+HYDROLOGICAL_MODULE = ["gr4", "gr5", "gr6", "grd", "loieau", "vic3l"]
 
 ROUTING_MODULE = ["lag0", "lr", "kw"]
 
@@ -67,6 +67,7 @@ def get_rr_internal_fluxes_from_structure(structure: str) -> list[str]:
         [
             ["ci", "cp", "ct", "kexc"],  # % gr4
             ["ci", "cp", "ct", "kexc", "aexc"],  # % gr5
+            ["ci", "cp", "ct", "be", "kexc", "aexc"],  # % gr6
             ["cp", "ct"],  # % grd
             ["ca", "cc", "kb"],  # % loieau
             ["b", "cusl", "cmsl", "cbsl", "ks", "pbc", "ds", "dsm", "ws"],  # % vic3l
@@ -104,6 +105,7 @@ def get_rr_internal_fluxes_from_structure(structure: str) -> list[str]:
         [
             ["hi", "hp", "ht"],  # % gr4
             ["hi", "hp", "ht"],  # % gr5
+            ["hi", "hp", "ht", "he"],  # % gr6
             ["hp", "ht"],  # % grd
             ["ha", "hc"],  # % loieau
             ["hcl", "husl", "hmsl", "hbsl"],  # % vic3l
@@ -143,6 +145,7 @@ def get_rr_internal_fluxes_from_structure(structure: str) -> list[str]:
         [
             ["pn", "en", "pr", "perc", "lexc", "prr", "prd", "qr", "qd", "qt"],  # % gr4
             ["pn", "en", "pr", "perc", "lexc", "prr", "prd", "qr", "qd", "qt"],  # % gr5
+            ["pn", "en", "pr", "perc", "lexc", "prr", "prd", "pre", "qr", "qd", "qe", "qt"],  # % gr6
             ["ei", "pn", "en", "pr", "perc", "prr", "qr", "qt"],  # % grd
             ["ei", "pn", "en", "pr", "perc", "prr", "prd", "qr", "qd", "qt"],  # % loieau
             ["pn", "en", "qr", "qb", "qt"],  # % vic3l
@@ -204,11 +207,12 @@ def get_rr_internal_fluxes_from_structure(structure: str) -> list[str]:
 
 RR_PARAMETERS = [
     "kmlt",  # % ssn
-    "ci",  # % (gr4, gr5)
-    "cp",  # % (gr4, gr5, grd)
-    "ct",  # % (gr4, gr5, grd)
-    "kexc",  # % (gr4, gr5)
-    "aexc",  # % gr5
+    "ci",  # % (gr4, gr5, gr6)
+    "cp",  # % (gr4, gr5, gr6, grd)
+    "ct",  # % (gr4, gr5, gr6, grd)
+    "be",  # % (gr6)
+    "kexc",  # % (gr4, gr5, gr6)
+    "aexc",  # % (gr5, gr6)
     "ca",  # % loieau
     "cc",  # % loieau
     "kb",  # % loieau
@@ -228,9 +232,10 @@ def get_rr_internal_fluxes_from_structure(structure: str) -> list[str]:
 
 RR_STATES = [
     "hs",  # % ssn
-    "hi",  # % (gr4, gr5)
-    "hp",  # % (gr4, gr5, grd)
-    "ht",  # % (gr4, gr5, grd)
+    "hi",  # % (gr4, gr5, gr6)
+    "hp",  # % (gr4, gr5, gr6, grd)
+    "ht",  # % (gr4, gr5, gr6, grd)
+    "he",  # % (gr6)
     "ha",  # % loieau
     "hc",  # % loieau
     "hcl",  # % vic3l
@@ -252,6 +257,7 @@ def get_rr_internal_fluxes_from_structure(structure: str) -> list[str]:
             (0, np.inf),  # % ci
             (0, np.inf),  # % cp
             (0, np.inf),  # % ct
+            (0, np.inf),  # % be
             (-np.inf, np.inf),  # % kexc
             (0, 1),  # % aexc
             (0, np.inf),  # % ca
@@ -282,6 +288,7 @@ def get_rr_internal_fluxes_from_structure(structure: str) -> list[str]:
             (0, 1),  # % hi
             (0, 1),  # % hp
             (0, 1),  # % ht
+            (-np.inf, np.inf),  # % he
             (0, 1),  # % ha
             (0, 1),  # % hc
             (0, 1),  # % hcl
@@ -307,6 +314,7 @@ def get_rr_internal_fluxes_from_structure(structure: str) -> list[str]:
             1e-6,  # % ci
             200,  # % cp
             500,  # % ct
+            10,  # % be
             0,  # % kexc
             0.1,  # % aexc
             200,  # % ca
@@ -337,6 +345,7 @@ def get_rr_internal_fluxes_from_structure(structure: str) -> list[str]:
             1e-2,  # % hi
             1e-2,  # % hp
             1e-2,  # % ht
+            -100,  # % he
             1e-2,  # % ha
             1e-2,  # % hc
             1e-2,  # % hcl
@@ -360,6 +369,7 @@ def get_rr_internal_fluxes_from_structure(structure: str) -> list[str]:
             (1e-6, 1e2),  # % ci
             (1e-6, 1e3),  # % cp
             (1e-6, 1e3),  # % ct
+            (1e-3, 20),  # % be
             (-50, 50),  # % kexc
             (1e-6, 0.999999),  # % aexc
             (1e-6, 1e3),  # % ca
@@ -390,6 +400,7 @@ def get_rr_internal_fluxes_from_structure(structure: str) -> list[str]:
             (1e-6, 0.999999),  # % hi
             (1e-6, 0.999999),  # % hp
             (1e-6, 0.999999),  # % ht
+            (-1e3, 0),         # % he
             (1e-6, 0.999999),  # % ha
             (1e-6, 0.999999),  # % hc
             (1e-6, 0.999999),  # % hcl

smash/core/model/model.py

@@ -119,6 +119,7 @@ class Model:
 
             - ``'gr4'``
             - ``'gr5'``
+            - ``'gr6'``
             - ``'grd'``
             - ``'loieau'``
             - ``'vic3l'``