GRsuite

An unofficial, independent Python port of the airGR suite of GR rainfall-runoff models — a personal project, checked value by value against airGR.

This is not an official package, and it is not airGR. GRsuite is one person's work, developed independently and on personal time. It is not produced, endorsed, reviewed or supported by INRAE, and it carries no institutional guarantee. The models, the science and the reference implementation belong to INRAE's HYCAR unit; what is mine is the translation into Python and the mistakes in it.

If your work needs the reference implementation, use airGR — and please report problems found here to this repository's issue tracker, never to the airGR maintainers.

GR4J, GR5J, GR6J, GR2M, GR1A, GR4H, GR5H and the CemaNeige snow module — the models hydrologists have been running in R for twenty years, now in Python with no R dependency, no Fortran toolchain, and no reimplementation risk.

Every model output, every criterion and every calibrated parameter set in this package has been checked against airGR 1.7.9 itself: 502 quantities — 1.23 million individual values — agree to 2 × 10⁻¹³, and across 500 calibrations on 100 French catchments the largest deviation is 1.9 × 10⁻¹³.

pip install grsuite

Sixty seconds

import grsuite as gr

catchment = gr.Catchment(dates, precip=P, pot_evap=E, obs_discharge=Q)

fit = catchment.calibrate("GR4J", period=("2000-01-01", "2009-12-31"))
print(fit.describe())

check = fit.evaluate(period=("2010-01-01", "2019-12-31"))
print(check.nse(), check.kge())

GR4J calibrated on KGE = 0.8694
  X1       170.7158   production store capacity [mm]
  X2         0.5897   groundwater exchange coefficient [mm/step]
  X3        78.2571   routing store capacity [mm]
  X4         2.2568   unit hydrograph time constant [step]
  17 iterations, 202 model runs
0.799 0.776

A split-sample test is one call:

fit, validation = catchment.split_sample(
    "GR6J",
    calibration=("2000-01-01", "2009-12-31"),
    validation=("2010-01-01", "2019-12-31"),
    criterion="KGE",
)

Snow, on five elevation bands, needs only temperature and a hypsometric curve:

alpine = gr.Catchment(dates, precip=P, pot_evap=E, obs_discharge=Q,
                      temperature=T, hypsometry=elevation_quantiles)
fit = alpine.calibrate("CemaNeigeGR4J")

Every internal flux is available, under airGR's own names:

sim = fit.simulate()
sim.to_dataframe()[["Qobs", "Qsim", "Prod", "Rout", "Perc", "Exch"]]
sim.plot(log=True)

Why this exists

airGR is the reference implementation of the GR models: careful, peer-reviewed, maintained at INRAE. Its one constraint is that it lives in R. Python users have had to choose between calling R over a bridge, or trusting a reimplementation nobody checked.

GRsuite removes that choice. It was written by translating airGR's Fortran kernels and R logic line by line, and it is continuously verified against airGR's own outputs, which ship with the test suite. If GRsuite and airGR ever disagree, CI fails.

What is covered

Full bibliographic entries, with DOIs, are in docs/REFERENCES.md.

CreateErrorCrit_GAPX (de Lavenne et al., 2019) and airGR's plotting helpers are the only pieces left out. GR6H does not exist in airGR 1.7.9, so it does not exist here either.

Validation

The brief was to stay within 5 %. The measured agreement is eleven orders of magnitude better than that, and sits at the precision limit of the reference files themselves.

Across 500 independent calibrations — five model configurations on 100 CAMELS-FR catchments — 34 parameter sets came out bit-identical to airGR's, and the rest differ only in the last significant digit of a double.

Read the full validation report →

Two implementation details decide whether a re-implementation of airGR is merely correct or actually identical. Both are documented in docs/FIDELITY.md; the short version is that airGR's Fortran evaluates 0.9 in single precision before promoting it, and that its automatic warm-up period carries a leap-year correction. Miss either and your discharge is off by 2.4 × 10⁻⁷ or 3 × 10⁻⁶ respectively.

Two APIs, on purpose

The high-level one — for getting work done.

catchment = gr.Catchment(dates, precip=P, pot_evap=E, obs_discharge=Q)
fit = catchment.calibrate("GR6J", criterion="KGE", transfo="sqrt")

The faithful one — a direct translation of airGR, function by function, for porting an existing R workflow without rethinking it.

inputs = gr.InputsModel(dates, precip=P, pot_evap=E)
options = gr.RunOptions(inputs, "GR4J", ind_period_run=index)
crit = gr.InputsCrit("NSE", obs=Q[index])
result = gr.calibration_michel(inputs, options, crit, gr.CalibOptions("GR4J"))

The mapping from every airGR function to its GRsuite counterpart is in docs/MIGRATING_FROM_AIRGR.md.

Examples

All of them run against the demonstration catchment shipped in tests/data, so they work straight after a clone.

Installation

pip install grsuite            # runtime: numpy, numba
pip install "grsuite[io]"      # adds pandas for the DataFrame helpers

From source:

git clone https://github.com/Najim33/GRsuite
cd GRsuite
pip install -e ".[dev]"
pytest

Python 3.9 to 3.13, on Linux, macOS and Windows.

Performance

The kernels are JIT-compiled by Numba, so the first call to a model pays a compilation cost of a second or two and everything afterwards runs at compiled speed. Recompilation is cached on disk between sessions.

On the 500-calibration benchmark (5 configurations × 100 catchments, 20 years of daily data each):

Same parameters, same criteria, same iteration counts.

Citing

GRsuite introduces no new hydrology. The models, the calibration algorithm and the reference implementation belong to their authors, at Cemagref / Irstea / INRAE. If GRsuite supports published work, cite airGR:

Coron, L., Thirel, G., Delaigue, O., Perrin, C., Andréassian, V. (2017). The suite of lumped GR hydrological models in an R package. Environmental Modelling & Software, 94, 166–171. doi:10.1016/j.envsoft.2017.05.002

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

and the model you actually ran — GR4J is Perrin et al. (2003), CemaNeige is Valéry (2010), and so on. Every one of them, with its DOI, is listed in docs/REFERENCES.md.

If the port itself is relevant to your methods, cite this repository too — see CITATION.cff.

Contributing

Bug reports, models, criteria and examples are all welcome. The one hard rule: anything that changes model numerics must keep the airGR comparison tests green. See CONTRIBUTING.md.

Licence

GPL-2.0-or-later. GRsuite is a derivative work of airGR (INRAE, GPL-2) and carries the same licence — see NOTICE for the full attribution.

GRsuite is an independent, unofficial project. It is not produced, endorsed or supported by INRAE, and it is not a release of airGR.

Ce README existe aussi en français.