1. Need help? Please let us know in the UMEP Community.

  2. Please report issues with the manual on the GitHub Issues.

  3. Please cite SUEWS with proper information from our Zenodo page. supy.util.gen_forcing_era5#

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, pressure_level=None, logging_level=20) list[source]#

Generate SUEWS forcing files using ERA-5 data. Parameters#


Latitude of centre at the area of interest.


Longitude of centre at the area of interest.


Any datetime-like string that can be parsed by pandas.daterange().


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.

gridlist, 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.

scaleint, 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.

pressure_level: float

pressure level to retrieve ERA5 atmospheric data, by default None. If None, this option is ignored. If not None, calculations implied by simple_mode will be skipped: the data at specified pressure level will be used as forcing data and the mean altitude of the pressure level between specified start and end will be assumed to be the forcing height (i.e., hgt_agl_diag will be ignored if set).

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. Returns#


A list of files in SUEWS forcing input format. Note#

  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.

  4. 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) Reference#

ECMWF, S. P. (2016). In IFS documentation CY41R2 Part IV: Physical Processes. ECMWF: Reading, UK, 111-113.