2. Module de modélisation hydrologique¶

INFO xhydro fournit des outils pour exécuter et calibrer des modèles hydrologiques, mais ne préparera pas le modèle lui-même. Cela devrait être fait au préalable.

xhydro fournit une collection de fonctions qui peuvent servir de point d’entrée principal pour la modélisation hydrologique. L’ensemble du framework est basé sur la fonction xh.modelling.hydrological_model et son dictionnaire model_config, qui contient toutes les informations nécessaires pour exécuter le modèle hydrologique donné. Par exemple, selon le modèle, il peut stocker directement des ejeux de données météorologiques, des chemins d’accès aux jeux de données (fichiers netCDF ou autres), des fichiers de configuration csv, des paramètres et, fondamentalement, tout ce qui est nécessaire pour configurer et exécuter un modèle hydrologique.

It then becomes the User’s responsibility to ensure that all required information for a given model are provided in the model_config object, both in the data preparation stage and in the hydrological model implementation. This can be addressed by calling the xh.modelling.get_hydrological_model_inputs function to get a list of the required keys for a given model, as well as the documentation. Parameters for that function are:

model_name: As listed below.
required_only: Whether to return all possible inputs, or only the required ones.

Currently available models are:

Hydrotel
Raven-emulated models: Blended, GR4JCN, HBVEC, HMETS, HYPR, Mohyse, SACSMA

[1]:

import xhydro as xh
import xhydro.modelling as xhm

# This function can be called to get a list of the keys for a given model, as well as its documentation.
inputs, docs = xhm.get_hydrological_model_inputs("Hydrotel", required_only=False)
inputs

/home/docs/checkouts/readthedocs.org/user_builds/xhydro-fr/conda/latest/lib/python3.12/site-packages/esmpy/interface/loadESMF.py:94: VersionWarning: ESMF installation version 8.8.0, ESMPy version 8.8.0b0
  warnings.warn("ESMF installation version {}, ESMPy version {}".format(
ERROR 1: PROJ: proj_create_from_database: Open of /home/docs/checkouts/readthedocs.org/user_builds/xhydro-fr/conda/latest/share/proj failed

[1]:

{'model_name': 'Hydrotel',
 'project_dir': str | os.PathLike,
 'project_file': str,
 'executable': str | os.PathLike,
 'project_config': dict | None,
 'simulation_config': dict | None,
 'output_config': dict | None,
 'use_defaults': bool}

[2]:

print(docs)

Class to handle Hydrotel simulations.

    Parameters
    ----------
    project_dir : str or os.PathLike
        Path to the project folder.
    project_file : str
        Name of the project file (e.g. 'projet.csv').
    executable : str or os.PathLike
        Command to execute Hydrotel.
        On Windows, this should be the path to Hydrotel.exe.
    project_config : dict, optional
        Dictionary of configuration options to overwrite in the project file.
    simulation_config : dict, optional
        Dictionary of configuration options to overwrite in the simulation file (simulation.csv).
    output_config : dict, optional
        Dictionary of configuration options to overwrite in the output file (output.csv).
    use_defaults : bool
        If True, use default configuration options loaded from xhydro/modelling/data/hydrotel_defaults/.
        If False, read the configuration options directly from the files in the project folder.

    Notes
    -----
    At minimum, the project folder must already exist when this function is called
    and either 'use_defaults' must be True or 'SIMULATION COURANTE' must be specified
    as a keyword argument in 'project_config'.

Hydrological models can differ from one another in terms of required inputs and available functions, but an effort will be made to homogenize them as much as possible as new models get added. Currently, all models have these 3 functions:

.run() which will execute the model, reformat the outputs to be compatible with analysis tools in xhydro, then return the simulated streamflows as a xarray.Dataset.
- The streamflow will be called streamflow and have units in m3 s-1.
- In the case of 1D data (such as hydrometric stations), that dimension in the dataset will be identified through a cf_role: timeseries_id attribute.
.get_inputs() to retrieve the meteorological inputs.
.get_streamflow() to retrieve the simulated streamflow.

2.2. Initializing the model¶

L’exemple suivant utilisera le modèle Hydrotel. Il est plus complexe, avec la plupart de ses paramètres cachés dans les fichiers de configuration, mais xhydro peut être utilisé pour facilement mettre à jour les fichiers de configuration, valider le répertoire du projet et les entrées météorologiques, exécuter le modèle et reformater les sorties pour être plus conformes aux conventions CF et aux autres fonctions de xhydro.

Notez que xhydro ne prépare pas le répertoire du projet lui-même, ce qui devrait être fait au préalable. Ce que fait la classe, lors du lancement d’une nouvelle instance de xhydro.modelling.Hydrotel, c’est autoriser le contrôle sur les entrées situées dans les trois fichiers de configuration principaux : le fichier de projet, simulation.csv et output.csv. Les autres arguments pour la classe, obtenus à partir de get_hydrological_model_inputs, sont listés ci-dessus. A tout moment après l’initialisation de la classe, update_config() peut être appelée pour mettre à jour les trois fichiers de configuration. Lorsqu’elle est appelée, cette fonction écrasera les fichiers CSV sur le disque.

[10]:

import os
from pathlib import Path

# The executable depends on the platform
if os.name == "nt":
    executable = "path/to/Hydrotel.exe"
else:
    executable = "hydrotel"

# Prepare the model configuration options
model_config = {
    "model_name": "Hydrotel",
    "project_dir": Path(notebook_folder) / "_data" / "example_hydrotel",
    "project_file": "projet.csv",
    "simulation_config": {
        "DATE DEBUT": "1981-01-01",
        "DATE FIN": "1981-12-31",
        "FICHIER STATIONS METEO": "meteo/ERA5.nc",
        "PAS DE TEMPS": 24,
    },
    "output_config": {"TRONCONS": 1, "DEBITS_AVAL": 1},
    "use_defaults": True,
    "executable": executable,
}

Pour HYDROTEL, DATE DEBUT, DATE FIN et PAS DE TEMPS devront toujours être spécifiés. Ils doivent donc être ajoutés à simulation_config s’ils n’existent pas déjà dans simulation.csv. De plus, soit FICHIER STATIONS METEO (fichier des stations météorologiques) soit FICHIER GRILLE METEO (fichier de grille météorologique) doivent être spécifiés pour guider le modèle vers les données météorologiques.

Si vous utilisez les valeurs par défaut, le débit de tous les tronçons de rivière sera affiché. Vous pouvez modifier output.csv pour changer ce comportement.

[11]:

# Note that xhm.Hydrotel(**model_config) could also be used to initiate the model.
ht = xhm.hydrological_model(model_config)

print(f"Simulation directory, taken from the project file: '{ht.simulation_dir}'\n")
print(f"Project configuration: '{ht.project_config}'\n")
print(f"Simulation configuration: '{ht.simulation_config}'\n")
print(f"Output configuration: '{ht.output_config}'")

Simulation directory, taken from the project file: '/home/docs/checkouts/readthedocs.org/user_builds/xhydro-fr/checkouts/latest/docs/notebooks/_data/example_hydrotel/simulation/simulation'

Project configuration: '{'PROJET HYDROTEL VERSION': '', 'FICHIER ALTITUDE': 'physitel/altitude.tif', 'FICHIER PENTE': 'physitel/pente.tif', 'FICHIER ORIENTATION': 'physitel/orientation.tif', 'FICHIER ZONE': 'physitel/uhrh.tif', 'FICHIER NOEUD': 'physitel/noeuds.nds', 'FICHIER TRONCON': 'physitel/troncon.trl', 'FICHIER PIXELS': 'physitel/point.rdx', 'FICHIER MILIEUX HUMIDES PROFONDEUR TRONCONS': '', 'SIMULATION COURANTE': 'simulation'}'

Simulation configuration: '{'SIMULATION HYDROTEL VERSION': '', 'FICHIER OCCUPATION SOL': 'physitel/occupation_sol.cla', 'FICHIER PROPRIETE HYDROLIQUE': 'physitel/proprietehydrolique.sol', 'FICHIER TYPE SOL COUCHE1': 'physitel/type_sol.cla', 'FICHIER TYPE SOL COUCHE2': 'physitel/type_sol.cla', 'FICHIER TYPE SOL COUCHE3': 'physitel/type_sol.cla', 'COEFFICIENT ADDITIF PROPRIETE HYDROLIQUE': '0', 'FICHIER INDICE FOLIERE': 'physio/ind_fol.def', 'FICHIER PROFONDEUR RACINAIRE': 'physio/pro_rac.def', 'FICHIER GRILLE METEO': '', 'FICHIER STATIONS METEO': 'meteo/ERA5.nc', 'FICHIER STATIONS HYDRO': '', 'PREVISION METEO': '0', 'FICHIER GRILLE PREVISION': '', 'DATE DEBUT PREVISION': '', 'DATE DEBUT': '1981-01-01 00:00', 'DATE FIN': '1981-12-31 00:00', 'PAS DE TEMPS': 24, 'TRONCON EXUTOIRE': '1', 'TRONCONS DECONNECTER': 'off', 'NOM FICHIER CORRECTIONS': 'correction.csv', 'LECTURE ETAT FONTE NEIGE': '', 'LECTURE ETAT TEMPERATURE DU SOL': '', 'LECTURE ETAT BILAN VERTICAL': '', 'LECTURE ETAT RUISSELEMENT SURFACE': '', 'LECTURE ETAT ACHEMINEMENT RIVIERE': '', 'ECRITURE ETAT FONTE NEIGE': '', 'ECRITURE ETAT TEMPERATURE DU SOL': '', 'ECRITURE ETAT BILAN VERTICAL': '', 'ECRITURE ETAT RUISSELEMENT SURFACE': '', 'ECRITURE ETAT ACHEMINEMENT RIVIERE': '', 'REPERTOIRE ECRITURE ETAT FONTE NEIGE': 'etat', 'REPERTOIRE ECRITURE ETAT TEMPERATURE DU SOL': 'etat', 'REPERTOIRE ECRITURE ETAT BILAN VERTICAL': 'etat', 'REPERTOIRE ECRITURE ETAT RUISSELEMENT SURFACE': 'etat', 'REPERTOIRE ECRITURE ETAT ACHEMINEMENT RIVIERE': 'etat', 'INTERPOLATION DONNEES': 'THIESSEN', 'FONTE DE NEIGE': 'DEGRE JOUR MODIFIE', 'TEMPERATURE DU SOL': '', 'EVAPOTRANSPIRATION': 'HYDRO-QUEBEC', 'BILAN VERTICAL': 'BV3C', 'RUISSELEMENT': 'ONDE CINEMATIQUE', 'ACHEMINEMENT RIVIERE': 'ONDE CINEMATIQUE MODIFIEE', 'MILIEUX HUMIDES ISOLES': '0', 'MILIEUX HUMIDES RIVERAINS': '0', 'FICHIER DE PARAMETRE GLOBAL': '0', 'LECTURE INTERPOLATION DONNEES': 'lecture_interpolation.csv', 'THIESSEN': 'thiessen.csv', 'MOYENNE 3 STATIONS': 'moyenne_3_stations.csv', 'LECTURE FONTE NEIGE': 'lecture_fonte_neige.csv', 'DEGRE JOUR MODIFIE': 'degre_jour_modifie.csv', 'LECTURE TEMPERATURE DU SOL': 'lecture_tempsol.csv', 'RANKINEN': 'rankinen.csv', 'THORSEN': 'thorsen.csv', 'LECTURE EVAPOTRANSPIRATION': 'lecture_etp.csv', 'HYDRO-QUEBEC': 'hydro_quebec.csv', 'THORNTHWAITE': 'thornthwaite.csv', 'LINACRE': 'linacre.csv', 'PENMAN': 'penman.csv', 'PRIESTLAY-TAYLOR': 'priestlay_taylor.csv', 'PENMAN-MONTEITH': 'penman_monteith.csv', 'ETP-MC-GUINESS': 'etp-mc-guiness.csv', 'LECTURE BILAN VERTICAL': 'lecture_bilan_vertical.csv', 'BV3C': 'bv3c.csv', 'CEQUEAU': 'cequeau.csv', 'LECTURE RUISSELEMENT SURFACE': 'lecture_ruisselement.csv', 'ONDE CINEMATIQUE': 'onde_cinematique.csv', 'LECTURE ACHEMINEMENT RIVIERE': 'lecture_acheminement.csv', 'ONDE CINEMATIQUE MODIFIEE': 'onde_cinematique_modifiee.csv', 'FICHIER MILIEUX HUMIDES ISOLES': '', 'FICHIER MILIEUX HUMIDES RIVERAINS': ''}'

Output configuration: '{'TRONCONS': 1, 'TMIN': '0', 'TMAX': '0', 'TMIN_JOUR': '0', 'TMAX_JOUR': '0', 'PLUIE': '0', 'NEIGE': '0', 'APPORT': '0', 'COUVERT_NIVAL': '0', 'HAUTEUR_NEIGE': '0', 'ALBEDO_NEIGE': '0', 'PROFONDEUR_GEL': '0', 'ETP': '0', 'ETR1': '0', 'ETR2': '0', 'ETR3': '0', 'ETR_TOTAL': '0', 'PRODUCTION_BASE': '0', 'PRODUCTION_HYPO': '0', 'PRODUCTION_SURF': '0', 'Q12': '0', 'Q23': '0', 'THETA1': '0', 'THETA2': '0', 'THETA3': '0', 'APPORT_LATERAL': '0', 'DEBITS_AMONT': '0', 'DEBITS_AVAL': 1, 'FICHIERS_ETATS_SEPARATEUR': ';', 'SEPARATEUR': ';', 'OUTPUT_NETCDF': '1'}'

2.3. Validation des données météorologiques¶

Quelques contrôles de base seront automatiquement effectués avant d’exécuter des modèles hydrologiques, mais un utilisateur avancé pourrait souhaiter effectuer des contrôles de santé plus avancés (par exemple, des entrées météorologiques irréalistes). Ceci est possible grâce à l’utilisation de xhydro.utils.health_checks. Consultez la documentation “xscen” <https://xscen.readthedocs.io/en/latest/notebooks/3_diagnostics.html#Health-checks>`__ pour la liste complète des vérifications possibles.

Dans cet exemple, nous veillerons à ce qu’il n’y ait pas de valeurs météorologiques ou de séquences de valeurs anormales. Étant donné que les données utilisées pour cet exemple sont fausses, cette fonction déclenchera certains signaux d’alarme.

[12]:

health_checks = {
    "raise_on": [],  # If an entry is not here, it will warn the user instead of raising an exception.
    "flags": {
        "pr": {  # You can have specific flags per variable.
            "negative_accumulation_values": {},
            "very_large_precipitation_events": {},
            "outside_n_standard_deviations_of_climatology": {"n": 5},
            "values_repeating_for_n_or_more_days": {"n": 5},
        },
        "tasmax": {
            "tasmax_below_tasmin": {},
            "temperature_extremely_low": {},
            "temperature_extremely_high": {},
            "outside_n_standard_deviations_of_climatology": {"n": 5},
            "values_repeating_for_n_or_more_days": {"n": 5},
        },
        "tasmin": {
            "temperature_extremely_low": {},
            "temperature_extremely_high": {},
            "outside_n_standard_deviations_of_climatology": {"n": 5},
            "values_repeating_for_n_or_more_days": {"n": 5},
        },
    },
}

[13]:

from xclim.core.units import amount2rate

# We can use get_inputs() to automatically retrieve the meteorological data. This is very useful for instances like Hydrotel, where this information is hidden within configuration files.
ds_in = ht.get_inputs()
ds_in["pr"] = amount2rate(
    ds_in["pr"]
)  # Hydrotel-to-xclim compatibility. Precipitation in xclim needs to be a flux.

xh.utils.health_checks(ds_in, **health_checks)

2. Module de modélisation hydrologique¶

2.1. Acquiring and formatting meteorological data¶

2.2. Initializing the model¶

2.3. Validation des données météorologiques¶

2.4. Exécution du modèle¶

2.5. Calage du modèle¶