This space gives an overview of the migration to GRIB edition 2, informs about the progress, and will be continuously updated.
It is complementary to the existing documentation at ECMWF and used to merge and link relevant information. Code and file examples will also be published here.

The space also contains a short introduction into GRIB editions 1 and 2 including the advantages of GRIB2 over GRIB1.

The information presented on this page is subject to further change. To receive notifications of any updates please "watch" this page (requires log in) or subscribe to the mailing list .

What will you find here?

We have prepared separate pages to refresh your knowledge about GRIB format, and for the information about new WMO parameters and the full list of ecCodes changes:

• About GRIB data format
• The mapping of parameters in GRIB1 and GRIB2
• GRIB edition 2 template example for Product Definition Section
• Migration to GRIB2 - new in ecCodes
• Migration to GRIB2 - new WMO parameters

Changes in ecCodes

Changes in ecCodes for decoding

The user interaction with the GRIB2 files via ecCodes is in principle the same as in GRIB1 by using the paramId or shortName keys to select a message or other edition independent high-level keys like dataDate or level.

There are some changes in the specification of parameters which can be classified into the following categories:

• some parameters have a different paramId in GRIB2 than in GRIB1
• a paramId in GRIB2 needs to be complemented by an additional key, e.g., a layer, whereas in GRIB1 a single paramId was sufficient
• a paramId is split into two Id's (paramId + chemId)
• some parameters have a different unit than in the official WMO GRIB2 parameter definitions.
  

Decoders other than ecCodes must be extended by the new parameters and templates proposed to the WMO before they can decode the data. ecCodes must be linked to the libaec library to be able to decode CCSDS compressed GRIB2 fields and a new ecCodes version is needed, which includes the new parameter and template definitions.

Changes in ecCodes for encoding

Besides the mapping of parameters and creating new templates, GRIB2 also impacts workflows for encoding data:

• several additional keys have to be set besides the keys defined in the concepts for encoding 
• for some parameters it is necessary to define the Product Definition Template Number before they can be encoded

There will be changes in some parameters like for example for soil, ice, and snow parameters on layers. Instead of having a paramId for each layer in GRIB1, in GRIB2 there will be only a single paramId for each soil parameter on layers, which can be distinguished by the level information encoded in the message. This means that instead of using a paramId for Volumetric soil water layer 1 and another for Volumetric soil water layer 2, only a single paramId is used for Volumetric soil water, and users have additionally to choose the layer in their workflow.

Another example is a splitting of the paramId’s for chemical parameters into a paramId and a chemId. This allows for more flexibility in adding new or additional chemical species. 

Changes in the MARS language

MARS requests for some parameters will also be affected by the migration to GRIB2.

Changes to param keyword

For GRIB1 parameters, the param keyword in the mars request can be set to param=indicatorOfParameter.table2Version. Requests with this structure will not work for GRIB2 as these two keys do not exist in this edition. The paramId must be used for GRIB2 parameters. This is the recommended way of specifying parameters in MARS requests.

An example is the retrieval of the U-component of the 10 metre wind, which is in GRIB1 in the indicatorOfParameter.table2Version representation param=165.128, but in GRIB2 param=165.

retrieve,
  class=od,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=sfc,
  param=165.128,
  target="output_10u.grib1"

retrieve,
  class=od,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=sfc,
  param=165,
  target="output_10u.grib2"

Changes for parameters archived with levtype=sol

Parameters on surface levels will be archived with levtype=sol (surface other levels). 

For example, in GRIB1, a separate param is used to retrieve Volumetric soil water layer 1 and a different param o retrieve Volumetric soil water layer 2, etc with levtype=sfc .  In GRIB2, only a single paramId is used for Volumetric soil water, with the layer being selected by the levelist keyword and using levtype=sol .

Instead of specifying a single parameter Id in the request, for some parameters additional keys will need to be added, for example for snow layer parameters the layer. These parameters will be archived with the new MARS keyword levtype=sol which has to be specified in the request together with the MARS keyword levelist .

Example of a retrieval of snow depth parameters with levtype=sol .

retrieve,
  class=od,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=sfc,
  param=141.128,
  target="output_sd.grib1"

retrieve,
  class=od,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=sol,
  levelist=1/2/3/4/5,
  param=228141,
  target="output_sd.grib2"

Addition of new MARS keyword chem for retrieval of chemical species

Another example are chemical parameters. Besides using the MARS keyword param in the request to specify the parameter type, e.g., mass mixing ratio, an additional MARS keyword chem will be used to specify the chemical substance(s), e.g., nitrogen dioxide.

retrieve,
  class=mc,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=ml,
  levelist=1/to/137,
  param=210121,
  target="output_no2.grib1"

retrieve,
  class=mc,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=ml,
  levelist=1/to/137,
  param=402000,      # Mass mixing ratio
  chem=no2,          # Nitrogen dioxide
  target="output_no2.grib2"

Change of MARS packing for GRIB2 parameters retrieved on a grid

GRIB2 parameters retrieved on a grid will be compressed with CCSDS. To decode these parameter, ecCodes must be linked to libaec. Alternatively, the data can be retrieved in another packing type such as grid_simple packing, which was in use for the model level GRIB2 parameters.

retrieve,
  class=mc,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=ml,
  levelist=1/to/137,
  param=210121,
  target="output_no2.grib1"

retrieve,
  class=mc,
  stream=oper,
  expver=1,
  date=-2,
  time=00:00:00,
  type=fc,
  step=0,
  levtype=ml,
  levelist=1/to/137,
  param=402000,      # Mass mixing ratio
  chem=no2,          # Nitrogen dioxide
  packing=simple,    # Simple packing
  target="output_no2.grib2"

Outlook

The design phase for the next edition 3 of GRIB has already started. The next edition 3 will bring improvements like a finer sub-division of the message into twelve sections and an extended template-based approach giving even more flexibility than is currently available in GRIB2. An example is the representation of parameters processed over the vertical dimension via a separate Vertical Domain Section, which can also be expanded via new templates. Such “total-column” parameters have to be listed in GRIB2 instead as specific parameters in the WMO parameter code table. The migration from GRIB2 to GRIB3 will be much smoother, since GRIB3 is a de facto extension/improvement/revision of the GRIB2 format.  This next step from edition 2 to edition 3 will still take several years. The expected user impact will be considerably smaller than for the transition from edition 1 to 2. The actual migration to GRIB2 is also a good opportunity to learn from user feedback and challenges experienced during the transition to tailor user-oriented proposals to be submitted to WMO as a potential part of the next migration to GRIB3.

Further reading

• Migration from GRIB1 to GRIB2: preparing ECMWF model output for the future - ECMWF Newsletter Number 175 - Spring 2023