1. Need help? Please let us know in the UMEP Community.
  2. Find an issue within this page? Please report it in the GitHub issues.
  3. A good understanding of SUEWS is a prerequisite to the proper use of SuPy.


supy.util.gen_forcing_era5(lat_x: float, lon_x: float, start: str, end: str, dir_save=PosixPath('.'), grid=None, hgt_agl_diag=100.0, scale=0, force_download=True, simple_mode=True, logging_level=20) → 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 100; 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
  • force_download (boolean, optional) – flag to determine whether to download required ERA5 netCDF files; if False, all ERA5-related nc files in dir_save will be picked up for generation. by default True.
  • 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.
  • logging_level (logging level) – one of these values [50 (CRITICAL), 40 (ERROR), 30 (WARNING), 20 (INFO), 10 (DEBUG)]. A lower value informs SuPy for more verbose logging info.

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: https://cds.climate.copernicus.eu/api-how-to
  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. https://www.ecmwf.int/en/elibrary/16648-part-iv-physical-processes
  1. For start/end, it is recommended to use the format YYYY-MM-DD to avoid confusion in day/month-first convensions (an upstream known issue due to the dateutil behavior)