Please report issues with this page on the GitHub page.


supy.util.gen_forcing_era5(lat_x: float, lon_x: float, start: str, end: str, dir_save=PosixPath('.'), grid=[0.125, 0.125], hgt_agl_diag=100.0, scale=0, simple_mode=True) → list[source]

Generate SUEWS forcing files using ERA-5 data.

  • lat_x (float) – Latitude of centre at the area of interest.
  • lon_x (float) – Longitude of centre at the area of interest.
  • start (str) – Any datetime-like string that can be parsed by pandas.daterange().
  • end (str) – Any datetime-like string that can be parsed by pandas.daterange().
  • dir_save (Path or path-like string) – path to directory for saving downloaded ERA5 netCDF files.
  • grid (list, optional) – grid size used in CDS request API, by default [0.125, 0.125].
  • hgt_agl_diag (float) – height above ground level to diagnose forcing variables, by default 0; the ground level is taken from ERA5 grid altitude.
  • scale (int, optional) – scaling factor that determines the area of interest (i.e., area=grid[0]*scale), by default 0
  • simple_mode (boolean) – if use the simple mode for diagnosing the forcing variables, by default True. In the simple mode, temperature is diagnosed using environmental lapse rate 6.5 K/km and wind speed using MOST under neutral condition. If False, MOST with consideration of stability conditions will be used to diagnose forcing variables.

A list of files in SUEWS forcing input format.

Return type:



  1. This function uses CDS API to download ERA5 data; follow this for configuration first:
  2. The generated forcing files can be imported using supy.util.read_forcing to get simulation-ready `pandas.DataFrame`s.
  3. See Section 3.10.2 and 3.10.3 in the reference for details of diagnostics calculation.
ECMWF, S. P. (2016). In IFS documentation CY41R2 Part IV: Physical Processes. ECMWF: Reading, UK, 111-113.