ICON Grid Generator

Pure Python generation of deterministic ICON-style triangular grids.

The package provides spherical R<n>B<k> grids, planar triangular grids, limited-area extraction, geometry diagnostics and transforms, xarray conversion, and ICON-compatible NetCDF export. The same file-oriented API handles every grid family. File-oriented generation computes NetCDF-only fields in bounded chunks; large global grids and large global construction parents for limited-area grids also use compact staged generation and resumable disk checkpoints.

Installation

The base package requires Python 3.10 or newer and NumPy:

python -m pip install icon-grid-generator

With uv, add the package to an existing project:

uv add icon-grid-generator

For a standalone uv-managed virtual environment, use:

uv venv
uv pip install icon-grid-generator

The NetCDF calls in the quick start require the netcdf extra. Install acceleration and common output integrations for high-resolution work with:

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

The equivalent uv command for an existing project is:

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

Numba acceleration is optional for in-memory grids and required for the high-resolution export-first path.

Quick Start

Generate an in-memory grid and write the complete NetCDF schema:

from grid_generator import generate_grid

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

NetCDF grid_geometry follows ICON's geometry enum: spherical global and limited-area grids use 1, planar tori use 2, planar channels use 3, and general planar grids use 4. Regional spherical files carry a separate open_boundary=1 attribute; openness is not a coordinate-geometry type. ICON 2024.10's standard NWP interpolation path supports spherical grids and planar tori, but not its channel or general-plane enum values; those additional planar families remain useful for diagnostics and consumers with matching operators rather than as standard ICON-NWP simulation grids. Planar files write domain_length and domain_height from the physical spec extents; they never inherit spherical-Earth dimensions.

Planar tori use rectangular, independently wrapped x/y periods by default and therefore require an even number of rows. The former coupled skew lattice remains available explicitly:

from grid_generator import TorusGridSpec, generate_grid

torus = generate_grid(TorusGridSpec(nx=12, ny=6, edge_length=1_000.0))
skew_torus = generate_grid(
    TorusGridSpec(nx=12, ny=5, edge_length=1_000.0, periodic_layout="skew")
)

Generate any grid directly to NetCDF when the in-memory object is not needed:

from grid_generator import TorusGridSpec, generate_grid_to_netcdf

generate_grid_to_netcdf(
    TorusGridSpec(nx=12, ny=6, edge_length=1_000.0),
    "torus.nc",
)

The same call automatically selects compact checkpoint stages for a large global grid, or for the global parent of a limited-area request:

from grid_generator import generate_grid_to_netcdf

generate_grid_to_netcdf(
    "R2B8",
    "icon_grid_R02B08.nc",
    max_cells=None,
    accelerator="numba",
    work_dir="icon-grid-R2B08-work",
    fields="reduced",
)

All grid types use the same validated, chunked, atomic file-publication path. Global grids and limited-area construction parents add resumable bisection checkpoints when they exceed the in-memory base-stage budget. Regional selection is evaluated in chunks directly against that compact parent, so a LAM based on R2B12 no longer requires a complete global R2B11/R2B12 IconGrid; only the selected regional result is materialized. Planar grids have no multilevel refinement stages to checkpoint, and use preallocated array builders that avoid per-cell and per-edge Python object graphs. R2B8 is a practical first large-grid example at about 9.86 km resolution; check the resource tables before requesting finer grids.

The default full profile contains 88 fields, including the established quadrilateral_area, vlon_vertices, and vlat_vertices fields. reduced contains the 46-field union required by the standard ICON and icon4py global-grid readers. Dedicated icon and icon4py profiles and exact custom field lists are also available. The icon4py profile targets spherical grids; use fields="icon4py_torus" for a torus to include the nine Cartesian coordinate fields its reader needs. This 35-field profile is specific to icon4py; use full for general exchange. Place large outputs and checkpoint directories on disk-backed storage. Each checkpoint manifest atomically selects a complete array snapshot, so an interrupted overwrite leaves the preceding completed checkpoint resumable. The final NetCDF file is also published atomically after it closes successfully. Allow extra disk headroom when replacing checkpoints or an existing output: old and new snapshots/files can coexist temporarily. After a successful export, the work directory can be deleted unless it is being kept for a later resume.

Performance

Measurements used an exclusive dual-socket AMD EPYC 7713 node with 128 physical cores and about 446 GiB of available memory. Times cover independent generation and uncompressed NetCDF export; shared-filesystem I/O varies with storage load. R2B12 has approximately 0.616 km resolution and is the largest standard R2 grid whose one-based exported identifiers fit signed 32-bit integers.

The full timing predates the three added grid-description fields. The current 88-field R2B12 payload is approximately 1,122.5 GiB; it requires a new scaling run before quoting an updated export time.

See Performance and Scaling for R2B8–R2B12 measurements, component timings, validation details, and all field-profile storage sizes.

Documentation

• In-memory consumer contract documents supported array keys, layouts, dtypes, units, and indexing for consumers that use an IconGrid directly without a NetCDF round-trip.
• Documentation home
• API and usage
• Examples
• Design, limits, and performance
• Contributing
• Changelog

Citation metadata is provided in CITATION.cff. The package is distributed under the BSD 3-Clause License.