(LS)2D 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)2D briefly supported the new format, this led to several issues. Therefore, starting November 2024, (LS)2D 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)2D was installed using pip, upgrade (LS)2D with pip install --upgrade ls2d.
(LS)2D 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)2D, we kindly request citing this paper.
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/api-how-to .
It is easiest to install (LS)2D 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]
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)2D, add the (LS)2D 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.
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).
(LS)2D 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)2D 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)2D will check the status of the CDS request, and if the request is finished, download the ERA5 data.
All settings for (LS)2D are wrapped in a dictionary:
central_lat: central latitude of LES/SCM domaincentral_lon: central longitude of LES/SCM domainarea_size: spatial size of ERA5 download (central lat/lon +/-area_sizedegrees)era5_path: storage location of ERA5 downloads/dataera5_expver: ERA5 experiment version number (1=normal ERA5,5=near realtime). With CDS, only1works.case_name: experiment name, only used to create subdirectory inera5_path.start_date: Pythondatetimeobject with start date/timeend_date: Pythondatetimeobject with end date/timewrite_log: Write ERA5 download to screen (False) or log file (True)data_source: Download method (CDSorMARS).MARSonly works on e.g. the ECMWF supercomputer.