GRsuite
==========

Copyright (C) 2026 Najim Bouhafa and the GRsuite contributors.

GRsuite is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 2 of the License, or (at your option) any later
version. See the LICENSE file for the full text.


Origin and licence rationale
----------------------------

GRsuite is a Python re-implementation of the airGR R package. Its numerical
kernels were written by translating airGR's Fortran sources, and its calibration,
criteria and input-handling logic by translating airGR's R sources. GRsuite is
therefore a derivative work of airGR and is distributed under the same licence,
the GNU General Public License version 2 or later.

    airGR: Suite of GR Hydrological Models for Precipitation-Runoff Modelling
    Copyright (C) INRAE, HYCAR Research Unit, Antony, France
    Authors: Laurent Coron, Olivier Delaigue, Guillaume Thirel, David Dorchies,
             Charles Perrin, Claude Michel, and contributors
    Licence: GPL-2
    https://cran.r-project.org/package=airGR
    https://hydrogr.github.io/airGR/

GRsuite is an independent project. It is not produced, endorsed or supported
by INRAE. Questions about GRsuite should go to the GRsuite issue tracker,
not to the airGR maintainers.


Reference data included in this repository
------------------------------------------

The files under tests/data/ are numerical outputs generated by airGR 1.7.9 run
on the demonstration catchments distributed with that package. They are included
so the test suite can assert agreement with the reference implementation without
requiring an R installation. They carry airGR's licence.

The catchment attributes in docs/data/reference_basins.csv are derived from the
CAMELS-FR dataset:

    Delaigue, O., Brigode, P., Andreassian, V., Perrin, C., Etchevers, P.,
    Soubeyroux, J.-M., Janet, B., Addor, N. (2024). CAMELS-FR dataset:
    A large-sample hydroclimatic dataset for France to explore hydrological
    diversity and support model benchmarking.
    Recherche Data Gouv, doi:10.57745/WH7FJR
    Licence: Etalab Open Licence 2.0

    Meteorological forcing: SAFRAN/ISBA reanalysis, Meteo-France.
    Streamflow observations: Hydro / Eaufrance.


Scientific references implemented
---------------------------------

GRsuite implements published models; it originates none of them. Each component
below is the work of its authors. Full entries with DOIs, and the reference for
every criterion, transformation and dataset, are in docs/REFERENCES.md.

Rainfall-runoff models

  Perrin, C., Michel, C., Andreassian, V. (2003). Improvement of a parsimonious
      model for streamflow simulation. Journal of Hydrology 279, 275-289.  [GR4J]
  Le Moine, N. (2008). Le bassin versant de surface vu par le souterrain : une
      voie d'amelioration des performances et du realisme des modeles
      pluie-debit ? PhD thesis, Universite Pierre et Marie Curie / Cemagref.
                                                                          [GR5J]
  Pushpalatha, R., Perrin, C., Le Moine, N., Mathevet, T., Andreassian, V. (2011).
      A downward structural sensitivity analysis of hydrological models to improve
      low-flow simulation. Journal of Hydrology 411, 66-76.          [GR6J, GR5J]
  Mathevet, T. (2005). Quels modeles pluie-debit globaux au pas de temps horaire ?
      PhD thesis, ENGREF / Cemagref, Antony.                               [GR4H]
  Ficchi, A. (2017). An adaptive hydrological model for multiple time steps.
      PhD thesis, Universite Pierre et Marie Curie / Irstea, Antony.       [GR5H]
  Ficchi, A., Perrin, C., Andreassian, V. (2019). Hydrological modelling at
      multiple sub-daily time steps: model improvement via flux-matching.
      Journal of Hydrology 575, 1308-1327.        [GR5H, interception store]
  Mouelhi, S., Michel, C., Perrin, C., Andreassian, V. (2006). Stepwise
      development of a two-parameter monthly water balance model.
      Journal of Hydrology 318, 200-214.                                   [GR2M]
  Mouelhi, S., Michel, C., Perrin, C., Andreassian, V. (2006). Linking stream flow
      to rainfall at the annual time step: the Manabe bucket model revisited.
      Journal of Hydrology 328, 283-296.                                   [GR1A]
  Mouelhi, S. (2003). Vers une chaine coherente de modeles pluie-debit
      conceptuels globaux aux pas de temps pluriannuel, annuel, mensuel et
      journalier. PhD thesis, ENGREF / Cemagref.                     [GR2M, GR1A]

Snow module

  Valery, A. (2010). Modelisation precipitations-debit sous influence nivale.
      Elaboration d'un module neige et evaluation sur 380 bassins versants.
      PhD thesis, AgroParisTech / Cemagref.      [CemaNeige, elevation bands]
  Valery, A., Andreassian, V., Perrin, C. (2014). 'As simple as possible but not
      simpler': what is useful in a temperature-based snow-accounting routine?
      Parts 1 and 2. Journal of Hydrology 517, 1166-1175 and 1176-1187.
  Riboust, P., Thirel, G., Le Moine, N., Ribstein, P. (2019). Revisiting a simple
      degree-day model for integrating satellite data: implementation of
      SWE-SCA hystereses. Journal of Hydrology and Hydromechanics 67, 70-81.
                                                             [linear hysteresis]
  Turcotte, R., Fortin, L.-G., Fortin, V., Fortin, J.-P., Villeneuve, J.-P. (2007).
      Operational analysis of the spatial distribution and the temporal evolution
      of the snowpack water equivalent in southern Quebec, Canada.
      Nordic Hydrology 38, 211-234.                    [Hydrotel solid fraction]

Evapotranspiration

  Oudin, L., Hervieu, F., Michel, C., Perrin, C., Andreassian, V., Anctil, F.,
      Loumagne, C. (2005). Which potential evapotranspiration input for a lumped
      rainfall-runoff model? Part 2. Journal of Hydrology 303, 290-306.

Criteria, calibration and evaluation

  Nash, J.E., Sutcliffe, J.V. (1970). River flow forecasting through conceptual
      models part I. Journal of Hydrology 10, 282-290.                     [NSE]
  Gupta, H.V., Kling, H., Yilmaz, K.K., Martinez, G.F. (2009). Decomposition of
      the mean squared error and NSE performance criteria.
      Journal of Hydrology 377, 80-91.                                     [KGE]
  Kling, H., Fuchs, M., Paulin, M. (2012). Runoff conditions in the upper Danube
      basin under an ensemble of climate change scenarios.
      Journal of Hydrology 424-425, 264-277.                        [KGE', KGE2]
  Box, G.E.P., Cox, D.R. (1964). An analysis of transformations. Journal of the
      Royal Statistical Society B 26, 211-243.            [boxcox transformation]
  Santos, L., Thirel, G., Perrin, C. (2018). Technical note: pitfalls in using
      log-transformed flows within the KGE criterion. Hydrology and Earth System
      Sciences 22, 4583-4591.                              [flow transformations]
  Michel, C. (1991). Hydrologie appliquee aux petits bassins ruraux. Cemagref,
      Antony.                                            [calibration algorithm]
  Klemes, V. (1986). Operational testing of hydrological simulation models.
      Hydrological Sciences Journal 31, 13-24.                [split-sample test]

Semi-distributed routing

  Lobligeois, F. (2014). Mieux connaitre la distribution spatiale des pluies
      ameliore-t-il la modelisation des crues ? PhD thesis, AgroParisTech /
      Irstea, Antony.
  de Lavenne, A., Thirel, G., Andreassian, V., Perrin, C., Ramos, M.-H. (2016).
      Spatial variability of the parameters of a semi-distributed hydrological
      model. Proceedings of the IAHS 373, 87-94.

Reference implementation

  Coron, L., Thirel, G., Delaigue, O., Perrin, C., Andreassian, V. (2017).
      The suite of lumped GR hydrological models in an R package.
      Environmental Modelling & Software 94, 166-171.
  Coron, L., Delaigue, O., Thirel, G., Dorchies, D., Perrin, C., Michel, C.
      airGR: Suite of GR Hydrological Models for Precipitation-Runoff Modelling.
      R package version 1.7.9, INRAE, HYCAR Research Unit, Antony, France.
      doi:10.15454/EX11NA
