Technical Documentation

HydroLand converts two meteorological variables — precipitation and near-surface temperature — into a consistent representation of the land water cycle: soil water storage, the return of water to the atmosphere through evapotranspiration, runoff generation, and the routing of that runoff through the river network as discharge. This page documents the processing chain from the Climate DT forcing to the final hydrological products.

HydroLand is implemented as a reproducible Python layer (the standalone hydroland package) wrapped around two well-established, unmodified models: the mesoscale Hydrologic Model (mHM) and the multiscale Routing Model (mRM). The Python layer prepares the inputs, executes the models in sequence, and packages the outputs. Within Climate DT, the workflow driver orchestrates this chain through five stages: initialisation, preprocess, mhm, mrm, and completion.

Workflow overview

Climate DT forcing                                                          Products
(precipitation, temperature)
        │
        ▼
┌────────────────┐   ┌────────────┐   ┌──────────┐   ┌──────────┐   ┌──────────────┐
│ initialisation │ → │ preprocess │ → │   mHM    │ → │   mRM    │ → │  completion  │
└────────────────┘   └────────────┘   └──────────┘   └──────────┘   └──────────────┘
   set up the run      reformat input    land-surface   route runoff    clean up and
   and restarts        & compute PET     hydrology      into rivers     keep restarts

Each stage is self-contained and performs a defined role:

Stage

Description

initialisation

Creates the HydroLand directory tree, prepares namelists, and links the appropriate cold-start or warm-start restart files.

preprocess

Reads Climate DT forcing from the GSV/OPA interface, reformats precipitation and temperature to mHM conventions, and computes the potential evapotranspiration (PET) forcing.

mhm

Runs the land-surface hydrology model and writes the mHM flux/state output together with the next restart file.

mrm

Routes the gridded runoff across the river network and assembles a single global discharge product from many routing subdomains.

completion

Removes temporary files, keeps the restart and log material needed for robust restarts, and can preserve forcing files for the indicator chain.

These stages describe how HydroLand is run inside the Climate DT workflow. Users normally interact with the resulting data products rather than running the individual stages manually.

Forcing preparation

HydroLand requires two input variables delivered through the Climate DT interfaces: precipitation and near-surface air temperature. It expects one OPA file per variable and period, for example:

  • daily aggregated files such as 1990_01_01_2t_timestep_60_daily_mean.nc and 1990_01_01_avg_tprate_timestep_60_daily_mean.nc;

  • hourly raw files such as 1990_01_01_T00_00_to_1990_01_01_T23_00_2t_raw_data.nc and 1990_01_01_T00_00_to_1990_01_01_T23_00_avg_tprate_raw_data.nc.

For a daily workflow chunk, HydroLand uses one temperature and one precipitation file for the chosen day. For a monthly workflow chunk, it uses the corresponding per-day files for every day of the month and builds one forcing triplet per day for mHM.

Preprocessing converts the raw forcing into model-ready input. For each day, HydroLand produces three files:

  • mHM_<date>_to_<date>_pre.nc — precipitation;

  • mHM_<date>_to_<date>_tavg.nc — average temperature;

  • mHM_<date>_to_<date>_pet.nc — potential evapotranspiration.

For example, the hourly OPA pair 1990_01_01_T00_00_to_1990_01_01_T23_00_2t_raw_data.nc and 1990_01_01_T00_00_to_1990_01_01_T23_00_avg_tprate_raw_data.nc becomes mHM_1990_01_01_to_1990_01_01_tavg.nc, mHM_1990_01_01_to_1990_01_01_pre.nc, and mHM_1990_01_01_to_1990_01_01_pet.nc.

During preprocessing, HydroLand standardises variable names to pre and tavg, converts temperature from Kelvin to degrees Celsius, converts precipitation to millimetres, and harmonises coordinate ordering. PET, the atmospheric water demand, is estimated internally from temperature and latitude using a temperature-based formulation.

For monthly runs, the workflow can also deliver aggregated monthly products instead of daily files:

  • 1990_01_01_to_1990_01_31_mHM_Fluxes_States.nc;

  • 1990_01_01_to_1990_01_31_mRM_Fluxes_States.nc;

  • 1990_01_01_T00_00_to_1990_01_31_T23_00_mHM_Fluxes_States.nc;

  • 1990_01_01_T00_00_to_1990_01_31_T23_00_mRM_Fluxes_States.nc.

Hydrological simulation

Two models perform the physical simulation. mHM resolves land-surface processes — soil water storage, evapotranspiration, and runoff generation — cell by cell. mRM then routes the resulting runoff through the river network to produce simulated routed discharge in river channels.

HydroLand runs at 0.1 degree (≈ 10 km) and 0.05 degree (≈ 5 km) resolution. Routing is the most computationally demanding step, because the discharge in one cell depends on the inflow from upstream cells and cannot be solved for each cell in isolation. To limit runtimes, HydroLand splits the globe into large basin-based subdomains (53 for the 0.1 degree setup, 26 for 0.05 degree), routes each one independently, and merges them back into a single global discharge file. If a specialised experiment needs more output variables, these can be enabled in the HydroLand configuration.

Outputs are date-stamped to indicate the period they cover. Typical single-period mHM examples are:

  • 1990_01_01_to_1990_01_01_mHM_Fluxes_States.nc for a one-day daily run;

  • 1990_01_01_T00_00_to_1990_01_01_T23_00_mHM_Fluxes_States.nc for a one-day hourly run.

After routing and merging, the mRM outputs follow the same naming logic:

  • 1990_01_01_to_1990_01_01_mRM_Fluxes_States.nc;

  • 1990_01_01_T00_00_to_1990_01_01_T23_00_mRM_Fluxes_States.nc.

Both mHM and mRM files carry metadata inherited from the driving climate variables, so attributes such as activity, experiment, generation, model, realization, stream, and resolution travel with the data, together with the global attribute application = “HydroLand”. This ensures that each product remains traceable to the simulation that produced it.

Workflow orchestration

Inside Climate DT, HydroLand is called for a defined workflow chunk, usually a day or a month. The workflow locates the corresponding OPA forcing files, prepares the temporary mHM and mRM working directories, runs the five HydroLand stages in order, and writes date-stamped NetCDF products into the experiment output tree.

A daily workflow chunk produces one set of mHM and mRM products for one day. A monthly workflow chunk processes all days in the month and can merge them into monthly NetCDF files with daily or hourly time steps.

Restarts and recovery

Climate simulations span decades, so HydroLand is designed to stop, resume, and recover without loss of continuity:

  • if the expected previous mHM restart file is missing, the run begins as a cold start; otherwise it resumes as a warm start;

  • cold starts can pull restart files either from static initialisation material or from a previous HydroLand execution;

  • when bias adjustment is active, the code backs up and restores the monthly bias-adjustment pickle files so that restart behaviour stays consistent across month boundaries;

  • the completion step retains the restart and log files needed for recovery and diagnostics;

  • forcing files can be preserved when the downstream indicator routines need to reuse them;

  • log files are written for mHM and for every mRM subdomain, which supports the tracing of failed steps.

Historical and projection simulations are often run as separate experiments. A historical run for 1990–2014 may already exist under one experiment output tree, while a projection experiment starts in 2015 and should continue from that simulated state rather than from a fresh cold start. HydroLand can reuse restart files from the earlier run, keeping the projection physically continuous with the historical run even though the two are stored separately.

A completed run produces the following output tree:

hydroland/
├── forcings/
├── mhm/
│   ├── current_run/
│   │   ├── input/
│   │   │   ├── meteo/
│   │   │   └── restart/
│   │   └── output/
│   ├── fluxes/
│   ├── log_files/
│   └── restart_files/
└── mrm/
    ├── current_run/
    ├── fluxes/
    ├── log_files/
    │   └── subdomain_<n>/
    └── restart_files/
        └── subdomain_<n>/

Derived indicators

From the simulated fluxes and discharge, HydroLand derives stakeholder-oriented indicators that characterise the frequency of flood events, the persistence of droughts, and the degree of dryness of a region. Indicators are computed for the period passed to the workflow. Historical and projection experiments can therefore be processed separately, with comparisons interpreted according to the threshold definition used for each indicator run.

Discharge-based indicators

These are derived from the routed discharge produced by mRM (Qrouted). High percentiles such as \(p90\), \(p95\), and \(p99\) describe flood-type conditions, while low percentiles such as \(p10\), \(p5\), and \(p1\) describe drought-type conditions. The standard configuration uses the 90th, 95th, 10th, and 5th percentiles.

For each threshold, HydroLand reports three summaries per grid cell:

  • count: the number of distinct flood or drought events in the period;

  • duration: the number of event time steps, read as days or hours depending on the temporal resolution of the routed discharge;

  • intensity: the accumulated exceedance or deficit relative to the threshold.

In simplified form, the intensity is given by

\[I = \sum_t |Q(t) - Q_p|\]

evaluated only over the event time steps. Results are written with names such as 1990_2014_90th_percentile_discharge_indicators.nc or 2020_2039_5th_percentile_discharge_indicators.nc.

Dryness indicators

HydroLand also derives land-surface dryness indicators from mHM fluxes and soil-water states.

The aridity_index routine implements the HydroLand aridity indicator from actual evapotranspiration and precipitation. It builds monthly sums, aggregates them to annual sums, and then computes the ratio of mean annual actual evapotranspiration to mean annual precipitation:

\[AI = \frac{\overline{aET_{\mathrm{annual}}}}{\overline{P_{\mathrm{annual}}}}\]

The output is a single-period file such as 1990_2014_aridity_index.nc.

The soil_moisture_deficit routine focuses on persistent deficits relative to the local long-term soil moisture tendency. By default it uses the upper soil layer SWC_L01 and keeps only the deficit below the fitted trend:

\[\epsilon(t) = \max \left( \widehat{SM}(t) - SM(t), 0 \right)\]

The reported field is the time-mean deficit for the supplied period. The soil moisture deficit, HydroLand aridity indicator, and discharge-based indicators are implemented in HydroLand. Indicator products for IFS-NEMO, IFS-FESOM, and ICON will be published with the corresponding data as they become available (see Examples).

Implementation and runtime components

HydroLand is distributed as the standalone hydroland Python package. The Climate DT workflow uses this package together with:

  • Python ≥ 3.9

  • the mHM executable (Fortran model binary)

  • the mRM executable (Fortran routing model binary)

  • a NetCDF-capable Python environment

  • key Python dependencies: xarray, numpy, pandas, dask, cdo, scipy, netcdf4, crick

Operational installation and developer run instructions are maintained in the HydroLand package repository.