Note

THIS PROJECT HAS BEEN MERGED INTO SUEWS AND ARCHIVED.

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:

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

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

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.

  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. https://www.ecmwf.int/en/elibrary/16648-part-iv-physical-processes