ls2d 1.0.16

Python toolkit to downscale ERA5 with doubly-periodic large-eddy simulation

(LS)²D: LES and SCM - Large Scale Dynamics

(LS)²D is a Python toolkit, developed to simplify all the steps required to downscale ERA5 with doubly-periodic large-eddy simulation (LES), or single-column models (SCMs). For the retrieval of ERA data, it relies on the Copernicus Data Store (CDS), or the Meteorological Archival and Retrieval System (MARS) at ECMWF computer systems.

[!IMPORTANT] In September 2024, Copernicus upgraded the Copernicus and Atmosphere Data Stores (CDS/ADS), introducing changes in the NetCDF file structure. The updated files now have different dimension names, time units, and even some reordered dimensions (!!). Unfortunately, these changes made the new NetCDF files incompatible with older versions or files extracted from MARS. Although (LS)²D briefly supported the new format, this led to several issues. Therefore, starting November 2024, (LS)²D will automatically patch new NetCDF files to ensure compatibility with the previous NetCDF file structure. On the user side, nothing should change:

• Old NetCDF files from CDS or MARS remain compatible.
• New NetCDF files from CDS/ADS are automatically patched after download.
• Unpatched new NetCDF files are patched once prior to reading.

To upgrade to the new CDS and ADS, please follow the steps described here. If (LS)²D was installed using pip, upgrade (LS)²D with pip install --upgrade ls2d.

References

(LS)²D is described in:

B.J.H. van Stratum, C.C. van Heerwaarden, & J. Vilà-Guerau de Arellano (2023). The benefits and challenges of downscaling a global reanalysis with doubly-periodic large-eddy simulations. JAMES, https://doi.org/10.1029/2023MS003750

If you use (LS)²D, we kindly request citing this paper.

Installation

If you want to use CDS to download the ERA5 data, then please start by following the steps explained at https://cds.climate.copernicus.eu/how-to-api .

PyPI

It is easiest to install (LS)²D from PyPI:

pip install ls2d

By default, this excludes the cdsapi as a dependency. If you do want to install that as a dependency, use:

pip install ls2d[cds]

Manual

For a manual installation, you can clone the package from Github:

git clone https://github.com/LS2D/LS2D.git

In each script where you want to use (LS)²D, add the (LS)²D root directory to the Python path:

import sys
sys.path.append('/path/to/LS2D')

You will have to manually install the dependencies with pip install numpy scipy netCDF4 matplotlib cdsapi.

Usage

Some examples are provided at https://github.com/LS2D/LS2D/tree/main/examples. The script example_1.py downloads the ERA5 data, calculates the initial conditions and large scale forcings, and creates an example plot.

The examples directory also contains example cases for MicroHH (https://github.com/microhh/microhh).

Downloading ERA5 data

(LS)²D contains two methods to download ERA5: through the Copernicus Data Store (open for everyone), or using MARS at ECMWF systems.

The ERA5 model level data that (LS)²D requires is stored on tape archives, so downloads using CDS tend to be slow with long queueing times. For that reason, ls2d.download_era5() will stop the Python script once the download requests are submitted to CDS. On subsequent calls of ls2d.download_era5(), (LS)²D will check the status of the CDS request, and if the request is finished, download the ERA5 data.

The settings dictionary

All settings for (LS)²D are wrapped in a dictionary:

• central_lat: central latitude of LES/SCM domain
• central_lon: central longitude of LES/SCM domain
• area_size: spatial size of ERA5 download (central lat/lon +/- area_size degrees)
• era5_path: storage location of ERA5 downloads/data
• era5_expver: ERA5 experiment version number (1=normal ERA5, 5=near realtime). With CDS, only 1 works.
• case_name: experiment name, only used to create subdirectory in era5_path.
• start_date: Python datetime object with start date/time
• end_date: Python datetime object with end date/time
• write_log: Write ERA5 download to screen (False) or log file (True)
• data_source: Download method (CDS or MARS). MARS only works on e.g. the ECMWF supercomputer.

Contributing guidelines

Contributions through pull requests are always appreciated. To keep the code style consistent, we stick to PEP8 with two modifications (see project.toml):

• The maximum line length is set to 120 characters instead of 80.
• Single quotes are used for strings instead of double quotes.

To ensure consistent formatting, the code should be automatically formatted using ruff. It can be installed via pip and can be run on the entire codebase from the project root (this directory) like

ruff format .