Skip to content

ICON Grid Generator

ICON Grid Generator is a pure Python package for creating ICON-style triangular grids without depending on ICON model runtimes or stencil frameworks.

Global ICON grid resolutions

What It Provides

  • Global spherical ICON R<n>B<k> grids.
  • Rectangular-periodic planar tori and open planar triangular grids for local experiments; coupled skew tori remain an explicit option.
  • Limited-area grids extracted from generated global parent grids.
  • ICON-style NetCDF export when the optional netCDF4 dependency is installed.
  • One chunked, atomic file-oriented NetCDF generation API for every grid family, with resumable disk checkpoints for large global grids and limited-area construction parents.
  • full, reduced, icon, icon4py, and icon4py_torus NetCDF field profiles plus exact custom field selection.
  • In-memory geometry, topology, connectivity, metric, and refinement arrays for plotting, diagnostics, and downstream conversion.

Basic Usage

Install icon-grid-generator[netcdf] before running this NetCDF example:

python -m pip install "icon-grid-generator[netcdf]"

With uv, add it to an existing project instead:

uv add "icon-grid-generator[netcdf]"

from grid_generator import generate_grid

grid = generate_grid("R2B4")
print(grid.name)
print(grid.dims)
grid.to_netcdf("icon_grid_R02B04.nc")

Global grids are optimized by default. Pass optimize_global=False only for raw topology diagnostics.

For high-resolution global grids, install the optional Numba acceleration path:

python -m pip install "icon-grid-generator[accelerate,netcdf]"

Or with uv:

uv add "icon-grid-generator[accelerate,netcdf]"

Without accelerate, generate_grid() with accelerator="auto" uses the correct NumPy fallback, but large-grid runtime is substantially higher. The export-first high-resolution path fails early instead of selecting that impractical fallback. See Performance and Scaling for measured time, memory, and storage requirements.

Which Grid Should I Use?

Goal Use
In-memory grid for analysis generate_grid("R2B4")
Any grid written directly generate_grid_to_netcdf(spec, path)
Large global or LAM file generate_grid_to_netcdf(spec, path, ...)
Raw topology checks generate_grid("R2B4", optimize_global=False)
Periodic planar experiment TorusGridSpec(...)
Regional extract from a global parent LimitedAreaGridSpec(...)
Cut an existing grid grid_generator.cutting.cut_grid(...)