io_grib.py — Writing FLEXPART-Ready GRIB2 Files¶

Overview¶

FLEXPART expects meteorological input files in GRIB2 format, one file per forecast step (e.g. dispf2025072912.grib). This module takes meteorological fields stored as xarray.DataArray objects and writes them to GRIB2 files that FLEXPART can directly use.

GRIB1 inputs are automatically converted to GRIB2 by overriding metadata from a GRIB2 Template 4.0 (instantaneous forecast).

Purpose¶

This module standardizes all fields by:

Standardization of all fields to GRIB2
Normalization of metadata for surface and model-level parameters
Definition of temporal properties, such as instantaneous versus 1-hour accumulated fields
Consistent writing of one GRIB file per forecast step

Key GRIB Metadata¶

Key	Meaning	Example
typeOfFirstFixedSurface	Lower boundary of the field	`1` = surface, `103` = height above ground, `105` = hybrid model level
scaledValueOfFirstFixedSurface	Numeric value of the level	`2` → 2 m above ground
typeOfSecondFixedSurface	Upper boundary of the layer	`8` = top of atmosphere, `255` = missing
productDefinitionTemplateNumber	Time interpretation	`0` = instantaneous, `8` = accumulation
indicatorOfUnitOfTimeRange	Unit of forecast step	`1` = hours

Field-Specific Conversions¶

Each variable type is mapped to GRIB2 metadata describing its vertical level and temporal behavior. The table below summarizes all transformations applied in io_grib.py.

Note

“Instantaneous” means a snapshot at the forecast time.
“Accumulation” means the value represents the total or flux over the previous hour.

Variable(s)	Meaning	Temporal Type	Vertical Definition	Template (`PDTN`)	Notes
u, v, t, q	Model-level wind, temperature, humidity	Instantaneous	As in source	0	Already GRIB2.
10u, 10v	10 m wind	Instantaneous	HeightAboveGround / 10 m	0	Added explicit 10 m level.
2t, 2d	2 m temperature & dewpoint	Instantaneous	HeightAboveGround / 2 m	0	Added explicit 2 m level.
sp, lsm	Surface pressure, land–sea mask	Instantaneous	Surface / 1	0	Converted from GRIB1; scale keys unset for GRIB2 compliance.
tcc	Total cloud cover	Instantaneous	Surface → TopOfAtmosphere	0	Defines vertical column layer.
sd, sdor, z	Snow depth, orography, geopotential	Instantaneous	Hybrid level 1	0	Model-level fields.
cp, lsp, sshf, ssr, ewss, nsss	Precipitation & fluxes	1-hour accumulation	Surface / 1	8	Written as 1-hour sums (PDT 8).
omega (w)	Vertical velocity	Instantaneous	Hybrid model level K	0	Written with canonical `w` shortName.

Output¶

For each forecast step, one GRIB2 file is produced:

dispfYYYYMMDDHH.grib