Passa al contenuto principale

Numerical weather forecasting model ICON-CH1/2-EPS

MeteoSwiss uses two models, ICON-CH1-EPS and ICON-CH2-EPS, to forecast the atmospheric state in Switzerland and its surroundings over a longer period than nowcasting, providing predictions for up to five days. Both models include ensemble data assimilation, where multiple simulations with slightly perturbed initial conditions help account for forecast uncertainty. Forecasts can include the full ensemble or just the unperturbed control run.

Loading map...

The documentation covers the following topics:


Getting started quickly​

Example notebooks: From retrieval to visualization​

To get started quickly, explore the Jupyter notebooks, which provide hands-on examples for retrieving, processing, and visualizing numerical weather prediction (NWP) model data from MeteoSwiss.

Available data​

Models' specifications​

AttributesICON-CH1-EPSICON-CH2-EPS
Collectionch.meteoschweiz.ogd-forecasting-icon-ch1ch.meteoschweiz.ogd-forecasting-icon-ch2
Horizontal Grid Sizeapprox. 1 kmapprox. 2.1 km
Ensemble Members1121
Forecast Period33 h120 h
GridNative icosahedralNative icosahedral
Temporal Output Resolution1 h1 h
New Model Run (Initialization)every 3 hevery 6 h
Output Data FormatGRIB edition 2GRIB edition 2

Available parameters​

Each collection includes a downloadable CSV file with a continuously updated list of available parameters. The file includes metadata such as long name, standard unit, level type (single or multi level), vertical coordinate type, temporal horizon, aggregation type and start time. To access the parameter overview, open the collection page for the desired model - for example, ICON-CH1-EPS or ICON-CH2-EPS. In the Assets section, download the file labeled Parameter Overview.

24h window​

The data provided in the two collections described in the Models' specifications table is accessible for 24 hours.

Data older than this is no longer available.

Download options​

We recommend using MeteoSwiss's meteodata-lab library - a convenient tool to simplify accessing and working with numerical weather model data. The library supports downloading ICON-CH1/2-EPS GRIB2 data and loading it into xarray DataArray. It is particularly ideal for users who want a clean and easy way to integrate forecast data into Python workflows.

Data Structure​

GRIB format​

The data is provided in GRIB2 format, which is a binary format used internationally and defined by WMO. More information about the data format can be found in the Manual on Codes published by WMO.

⚠️ WARNING: Data located at the boundary of the spatial domain may be random.

GRIB file structure​

Each GRIB2 file contains data for a single model collection, one reference time, one forecast lead time, and one variable — either as the deterministic control run or the full ensemble. The following diagram shows a general overview.

StructureDiagram

Forecast data volume​

The following tables summarize the expected volume of the different forecast files for ICON-CH1-EPS and ICON-CH2-EPS.

ICON-CH1-EPS Data Volume

Single-Level FilesMulti-Level Files
Deterministic199.0 Bytes - 2.2 MiB19.7 - 177.4 MiB
Perturbed1.9 KiB - 22.4 MiB197.1 MiB - 1.7 GiB

ICON-CH2-EPS Data Volume

Single-Level FilesMulti-Level Files
Deterministic175.0 Bytes - 564.7 KiB4.9 MiB - 43.9 MiB
Perturbed3.4 KiB - 11 MiB97.5 MiB - 877.5 MiB

3D model grid​

The model data is structured on both a horizontal and vertical grid.

Vertical grid​

The vertical grid above the surface is a height-based coordinate system that describes terrain-following model levels. The closer the levels are to the surface, the narrower the layers they define, as shown in the image below. The model levels gradually change into levels of constant height as the distance from the surface increases. Each grid box is delimited at the top and bottom by so-called half levels of the grid, while the full levels are aligned with the center of the grid box.

The vertical grid uses a Lorenz-type staggering, meaning that some parameters are defined at full levels and others, e.g. the vertical velocity W, at half levels. There are 81 discrete half levels and 80 full levels in our data. The levels are numbered from top to bottom.

VerticalLayers
Illustration of ICON's vertical levels, Working with the ICON Model 2024, Figure 3.2


In addition to the vertical grid above the surface (half and full levels), there is also a grid below the land surface to describe parameters such as the soil temperature for example.

In the provided model data, some variables are also defined on a surface (e.g. total precipitation), or at a specific height above ground (e.g. temperature at 2m). To determine the vertical positioning of a parameter and the units corresponding to the vertical surface type, inspect the GRIB2 key typeOfLevel:

  • generalVertical: half levels (-)

  • generalVerticalLayer: full levels (-)

  • depthBelowLandLayer: depth below surface (m)

  • surface: ground or water surface (-)

  • heightAboveGround: specific height above ground (m)

Parameters are classified as either single-level or multi-level:

  • Single-level parameters contain data at a specific vertical level.
  • Multi-level parameters span multiple vertical layers.

For more detailed information on the vertical grid, read section 3.4 in Working with the ICON Model.

Horizontal grid​

The horizontal grid of the ICON-CH1-EPS and ICON-CH2-EPS models is based on a native icosahedral grid used by the ICON model (illustration below).

IcosahedralGrid
Illustration of the ICON grid structure, Working with the ICON Model, Figure 2.1


Since the provided data is defined on the native grid, the horizontal grid points correspond to the center of the circumcircle of each triangle and not to the triangle’s vertices. Therefore, the longitude and latitude information corresponds to the middle of each triangle. For more detailed information on the horizontal grid, read section 2.1 in Working with the ICON Model.

Working with the forecast data​

Exploring GRIB files in Python​

Several Jupyter Notebooks explain how to download and work with forecast files in xarray.DataArray format. To explore them, check out the GitHub repository opendata-nwp-demos.

Reading GRIB files using ecCodes​

To work with GRIB files, you need a tool to decode the GRIB records. Each GRIB record holds the data for one parameter at one time and at one level. More information about the data format can be found in the Manual on Codes published by WMO. We recommend installing ecCodes from ECMWF to read the data. Follow the installation guide provided by ECMWF here.

Setting the local definitions of the COSMO consortium​

The GRIB format relies on tables and templates to encode the metadata. Those tables allow for example the mapping of a triplet of numbers encoding a parameter to a descriptive string (shortName). The international tables are provided in ecCodes. Additionally, local definitions can be defined by each center. ECMWF specific definitions are also shiped with ecCodes. Some of the provided ICON data also requires the local definitions of the COSMO consortium. In order to provide a consistent and comprehensive set of GRIB tables, check the ecCodes version you installed and clone the corresponding version of the GRIB tables in the same folder:

Then, set GRIB_DEFINITION_PATH for ecCodes to use those tables (add it to your .bashrc to make if availabe in each terminal session):

export GRIB_DEFINITION_PATH=<name_of_your_folder>/eccodes-cosmo-recources/definitions:<name_of_your_folder>r/eccodes/definitions

To check the details of your information, you can run

codes_info

Decoding GRIB files with ecCodes​

This section provides a brief introduction to decoding GRIB files using command-line tools provided by ecCodes. There are also C, Fortran 90 and Python interfaces, please refer to the ecCodes documentation.

Please look up the use of the command-line tools in the ECMWF documentation.

Some useful commands are:

  • List all the GRIB messages in a file:
grib_ls filename.grib
  • Filter GRIB messages based on key-value conditions:
grib_ls -w key1=value1,key2=value2 filename.grib
  • Specify a list of keys to be printed:
grib_ls -p key1,key2 filename.grib
  • Get a detailed view of the content of all GRIB messages:
grib_dump filename.grib
  • Get a detailed view of GRIB messages with filters:
grib_dump -w key1=value1,key2=value2 filename.grib

FAQ/Troubleshooting​

"Why can't I find the latitude or longitude coordinates?"

Raw forecast GRIB files loaded via the REST API do not contain information about height, longitude and latitude. To geolocate or interpret vertical levels, you must use the static vertical and horizontal grid parameter files provided in each collection. For more information, read section Accessing static grid information: Height, longitude and latitude.

"Why is my HTTP response empty?"

The data provided in the two collections described in the Model specifications table is accessible for only 24 hours. Data older than this is no longer available, which may be why your HTTP response is empty.

"Why do I get HTTPError: 403, when downloading forecast data using the Python API?"

The data provided in the two collections described in the Model specifications table is accessible for only 24 hours. Data older than this is no longer available. Therefore, when attempting to fetch unavailable data, HTTPError: 403 occurs.

"How do I interprete the different types of vertical levels?"

To determine the type of level (vertical position) of a parameter, inspect the GRIB2 key typeOfLevel. We distinguish between the following:

  • generalVertical: half levels (-)

  • generalVerticalLayer: full levels (-)

  • depthBelowLandLayer: depth below surface (m)

  • surface: ground or water surface (-)

  • heightAboveGround: specific height above ground (m)

For more details, refer to section Vertical grid.