Tip

  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

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.

Parameters

  • 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.

Returns

A list of files in SUEWS forcing input format.

Return type

List

Note

  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)