4. Modélisation hydrologique - HYDROTEL¶

AVERTISSEMENT

xHydro fournit des outils pour exécuter HYDROTEL, mais ne préparera pas le modèle lui-même. Cela doit être fait au préalable.

INFO

L’exécutable HYDROTEL peut être acquis à partir de ce dépôt GitHub.

xHydro propose une collection de fonctions conçues pour faciliter la modélisation hydrologique, en se concentrant sur deux modèles clés : HYDROTEL et une suite de modèles émulés par le Raven Hydrological Framework. Il est important de noter que Raven dispose déjà d’une vaste librairie Python, RavenPy, qui permet aux utilisateurs de construire, calibrer et exécuter des modèles. xHydro encapsule certaines de ces fonctions pour soutenir les évaluations multi-modèles avec HYDROTEL, mais les utilisateurs recherchant des fonctionnalités avancées préféreront utiliser RavenPy directement.

La principale contribution de xHydro à la modélisation hydrologique est donc son soutien à HYDROTEL, un modèle qui manquait auparavant d’une librairie Python dédiée. Cependant, la construction d’un projet HYDROTEL est mieux réalisée en utilisant PHYSITEL et l’interface graphique d’HYDROTEL, qui sont des logiciels propriétaires. Par conséquent, pour l’instant, xHydro est conçu pour faciliter l’exécution et la modification d’un projet HYDROTEL déjà établi, plutôt que d’aider à en construire un depuis zéro.

Un Notebook similaire à celui-ci, mais qui couvre les modèles RavenPy, est disponible ici.

4.1. Informations de base¶

[1]:

from IPython.display import clear_output
import xhydro as xh
import xhydro.modelling as xhm
clear_output(wait=False)

Le cadre de modélisation xHydro est basé sur un dictionnaire model_config, qui est censé contenir toutes les informations nécessaires pour exécuter un modèle hydrologique donné. Par exemple, en fonction du modèle, il peut stocker directement les jeux de données météorologiques, les chemins vers ces jeux de données (fichiers netCDF ou autres), les fichiers de configuration csv, les paramètres, et fondamentalement tout ce qui est nécessaire pour configurer et exécuter un modèle hydrologique.

La liste des entrées requises pour le dictionnaire peut être obtenue de deux façons. La première consiste à regarder la classe du modèle hydrologique, comme xhydro.modelling.Hydrotel. La seconde consiste à utiliser la fonction xh.modelling.get_hydrological_model_inputs pour obtenir la liste des clés requises pour un modèle donné, ainsi que sa documentation.

[3]:

help(xhm.get_hydrological_model_inputs)

Help on function get_hydrological_model_inputs in module xhydro.modelling.hydrological_modelling:

get_hydrological_model_inputs(model_name: str, required_only: bool = False) -> tuple[dict, str]
    Get the required inputs for a given hydrological model.

    Parameters
    ----------
    model_name : str
        The name of the hydrological model to use.
        Currently supported models are ["HYDROTEL", "Blended", "GR4JCN", "HBVEC", "HMETS", "HYPR", "Mohyse", "SACSMA"].
    required_only : bool
        If True, only the required inputs will be returned.

    Returns
    -------
    dict
        A dictionary containing the required configuration for the hydrological model.
    str
        The documentation for the hydrological model.

[4]:

# 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

[4]:

{'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}

[5]:

print(docs)


Class to handle HYDROTEL simulations.

Parameters
----------
project_dir : str or Path
    Path to the project folder.
project_file : str
    Name of the project file (e.g. 'projet.csv').
executable : str or Path
    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. See the Notes section for more details.
output_config : dict, optional
    Dictionary of configuration options to overwrite in the output file (output.csv).

Notes
-----
The name of the simulation file must match the name of the 'SIMULATION COURANTE' option in the project file.

This class is designed to handle the execution of HYDROTEL simulations, with the ability to overwrite configuration options,
but it does not handle the creation of the project folder itself. The project folder must be created beforehand.

For more information on how to configure the project, refer to the documentation of HYDROTEL:
https://github.com/INRS-Modelisation-hydrologique/hydrotel

HYDROTEL et Raven varient en termes d’entrées requises et de fonctions disponibles, mais un effort sera fait pour standardiser les sorties autant que possible. Actuellement, tous les modèles incluent les trois fonctions suivantes :

.run() : Exécute le modèle, reformate les sorties pour être compatibles avec les outils d’analyse dans xHydro, et retourne le débit simulé en tant que xarray.Dataset.
- La variable de débit sera nommée q et aura pour unités m3 s-1.
- Pour les données 1D (comme les stations hydrométriques), la dimension correspondante dans le jeux de données sera identifiée par l’attribut cf_role: timeseries_id.
.get_inputs() : Récupère les entrées météorologiques utilisées par le modèle.
.get_outputs() : Récupère les sorties simulées du modèle.
- Utilisez .get_outputs("q") pour obtenir le débit simulé dans un xarray.Dataset.
.standardize_outputs() : Standardise les sorties pour garantir la cohérence entre différents modèles, facilitant ainsi la comparaison et l’analyse. Cette fonction est utilisée par défaut dans la méthode .run(), mais peut également être appelée séparément si nécessaire.

4.3. Récupération de sorties supplémentaires¶

output_config permet aux utilisateurs de spécifier quelles variables sortir. Il est donc facile de récupérer des variables supplémentaires simplement en mettant à jour la configuration et en relançant le modèle.

[22]:

# "Couvert nival" is the snow water equivalent
hm.update_config(output_config={"COUVERT_NIVAL": "1"})
hm.run(overwrite=True, return_streamflow=False)
clear_output(wait=False)

La fonction .get_outputs() peut être utilisée pour récupérer n’importe laquelle de ces variables sous la forme d’un xarray.Dataset.

[23]:

help(hm.get_outputs)

Help on method get_outputs in module xhydro.modelling._hydrotel:

get_outputs(output: str, return_paths: bool = False, **kwargs) -> xr.Dataset | Path | list[Path] method of xhydro.modelling._hydrotel.Hydrotel instance
    Get the outputs of the simulation.

    Parameters
    ----------
    output : str
        "path" to return the output directory.
        Otherwise, the name of the output to retrieve, or "q" for the streamflow.
        This should match the name of the output file without the extension (e.g. "neige" for "neige.nc").
        Wildcards can be used.
    return_paths : bool
        If True, return the path to the output file(s) instead of the dataset. Default is False.
    \*\*kwargs : dict
        Keyword arguments to pass to :py:func:`xarray.open_dataset`.

    Returns
    -------
    xr.Dataset
        The requested output variable.
    Path
        The path to the output directory if output is set to "path".
    list[Path]
        The path to the output file(s) if return_path is True.

[24]:

files = hm.get_outputs("*", return_paths=True)
files

[24]:

[PosixPath('/tmp/tmpww7qb255/hydrotel_demo/simulation/simulation/resultat/couvert_nival.nc'),
 PosixPath('/tmp/tmpww7qb255/hydrotel_demo/simulation/simulation/resultat/debit_aval.nc')]

[25]:

snow = hm.get_outputs("couvert_nival")
snow

[25]:

<xarray.Dataset> Size: 791kB
Dimensions:                  (time: 364, unit_id: 495)
Coordinates: (12/14)
  * time                     (time) datetime64[ns] 3kB 1981-01-01 ... 1981-12-30
  * unit_id                  (unit_id) <U3 6kB '1' '2' '3' ... '493' '494' '495'
    dowsub_id                (unit_id) <U3 6kB dask.array<chunksize=(495,), meta=np.ndarray>
    station_id               (unit_id) <U7 14kB dask.array<chunksize=(495,), meta=np.ndarray>
    subbasin_id              (unit_id) <U3 6kB dask.array<chunksize=(495,), meta=np.ndarray>
    lon                      (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>
    ...                       ...
    unit_centroid_latitude   (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>
    drainage_area            (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>
    subbasin_drainage_area   (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>
    unit_drainage_area       (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>
    subbasin_elevation       (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>
    unit_elevation           (unit_id) float64 4kB dask.array<chunksize=(495,), meta=np.ndarray>
Data variables:
    couvert_nival            (time, unit_id) float32 721kB dask.array<chunksize=(364, 495), meta=np.ndarray>
Attributes:
    description:              Variable de sortie simulation Hydrotel
    creation_time:            17-06-2026 14:02:26
    HYDROTEL_version:         4.3.6.0000
    HYDROTEL_config_version:  4.3.1.0000

[26]:

snow["couvert_nival"].isel(unit_id=0).plot()

[26]:

[<matplotlib.lines.Line2D at 0x7f70e6e792b0>]

../_images/notebooks_hydrological_modelling_hydrotel_37_1.png

Quelques notes importantes concernant ces sorties supplémentaires :

Il n’y a actuellement aucune standardisation des noms de variables ou de leurs unités.
Dans le but de standardiser les sorties entre différents modèles, les niveaux d’agrégation suivants ont été définis. Ceux-ci sont notés dans un attribut aggregation_level dans les métadonnées de la variable, et peuvent être utilisés pour identifier la résolution spatiale de la sortie :
- ComputationalUnit : Dans HYDROTEL, cela correspond aux Unités Hydrologiques Relativement Homogènes (UHRH).
- Subbasin : Selon la convention Raven, cela correspond à la zone de drainage immédiatement autour d’un tronçon de rivière, excluant la zone de drainage en amont.
- DrainageArea : Cela correspond à la zone de drainage totale d’un tronçon de rivière.

À une exception près qui est calculée à l’échelle du sous-bassin (APPORT LATERAL), toutes les sorties supplémentaires dans HYDROTEL sont fournies à l’échelle de l’unité de calcul. La fonction aggregate_outputs a donc été implémentée dans xHydro pour permettre l’agrégation des sorties a posteriori, si nécessaire. Notez que cette fonction repose sur plusieurs propriétés du bassin versant qui sont déduites des fichiers du modèle.

[27]:

help(hm.aggregate_outputs)

Help on method aggregate_outputs in module xhydro.modelling._hydrotel:

aggregate_outputs(
to: Literal['subbasin', 'drainage_area'],
subset: list[str] | None = None,
**kwargs
) -> None method of xhydro.modelling._hydrotel.Hydrotel instance
Aggregate the model outputs to a different spatial unit. See the Notes section for more details.

Parameters
----------
to : {"subbasin", "drainage_area"}
The spatial unit to aggregate to.
subset : list[str] | None
The list of variables to aggregate. If None, all variables will be processed.
The strings should match the names produced by the HYDROTEL model.
\*\*kwargs : dict
Keyword arguments to pass to :py:func:`xarray.open_dataset`.

Returns
-------
None
The aggregated outputs will be saved as new NetCDF files in the output directory, with a name pattern
roughly following what is produced by HYDROTEL (e.g. "variable}_By{aggregation}.nc").
Aggregation will be 'BySubbasin' or 'ByDrainageArea', depending on the 'to' parameter.

Notes
-----
Unlike Raven, HYDROTEL always produces output files at the RHHU level, which is the finest spatial unit in the model.
Therefore, unlike its Raven variant, this method does not need a 'by' parameter to specify the spatial unit of the input files.
Furthermore, this method expects that the 'standardize_outputs' method has been called beforehand to ensure that the output
files are in a consistent format and contain the necessary spatial information for the aggregation.

[28]:

hm.aggregate_outputs(to="drainage_area")

[29]:

snow_agg = hm.get_outputs("couvert_nival_ByDrainageArea")
snow_agg

[29]:

<xarray.Dataset> Size: 589kB
Dimensions:        (time: 364, subbasin_id: 196)
Coordinates:
  * time           (time) datetime64[ns] 3kB 1981-01-01 ... 1981-12-30
  * subbasin_id    (subbasin_id) <U3 2kB '1' '2' '3' '4' ... '194' '195' '196'
    dowsub_id      (subbasin_id) <U3 2kB dask.array<chunksize=(196,), meta=np.ndarray>
    station_id     (subbasin_id) <U7 5kB dask.array<chunksize=(196,), meta=np.ndarray>
    lon            (subbasin_id) float64 2kB dask.array<chunksize=(196,), meta=np.ndarray>
    lat            (subbasin_id) float64 2kB dask.array<chunksize=(196,), meta=np.ndarray>
    drainage_area  (subbasin_id) float64 2kB dask.array<chunksize=(196,), meta=np.ndarray>
Data variables:
    couvert_nival  (time, subbasin_id) float64 571kB dask.array<chunksize=(364, 196), meta=np.ndarray>
Attributes:
    description:              Variable de sortie simulation Hydrotel
    creation_time:            17-06-2026 14:02:26
    HYDROTEL_version:         4.3.6.0000
    HYDROTEL_config_version:  4.3.1.0000

4.4. Calage du modèle¶

AVERTISSEMENT

Seuls les modèles basés sur Raven sont actuellement implémentés

4. Modélisation hydrologique - HYDROTEL¶

4.1. Informations de base¶

4.2. Initialisation et exécution d’un modèle calé¶

4.2.1. Mise en forme des données météorologiques¶

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

4.2.3. Exécution du modèle¶

4.3. Récupération de sorties supplémentaires¶

4.4. Calage du modèle¶