Metadata-Version: 2.4
Name: icon-grid-generator
Version: 0.6.2
Summary: Pure Python generation of ICON-style triangular grids
Project-URL: Changelog, https://github.com/ofuhrer/icon-grid-generator/blob/main/CHANGELOG.md
Project-URL: Documentation, https://ofuhrer.github.io/icon-grid-generator/
Project-URL: Homepage, https://github.com/ofuhrer/icon-grid-generator
Project-URL: Issues, https://github.com/ofuhrer/icon-grid-generator/issues
Project-URL: Repository, https://github.com/ofuhrer/icon-grid-generator
Project-URL: Source, https://github.com/ofuhrer/icon-grid-generator
Author: Oliver Fuhrer, MeteoSwiss
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: ICON,geodesic,grid,netcdf,torus
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Requires-Dist: numpy
Provides-Extra: accelerate
Requires-Dist: numba>=0.63; extra == 'accelerate'
Provides-Extra: docs
Requires-Dist: mkdocs; extra == 'docs'
Requires-Dist: mkdocs-material; extra == 'docs'
Provides-Extra: netcdf
Requires-Dist: netcdf4; extra == 'netcdf'
Provides-Extra: test
Requires-Dist: netcdf4; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: ruff; extra == 'test'
Requires-Dist: xarray; extra == 'test'
Provides-Extra: xarray
Requires-Dist: xarray; extra == 'xarray'
Description-Content-Type: text/markdown

# ICON Grid Generator

[![Tests](https://github.com/ofuhrer/icon-grid-generator/actions/workflows/test.yml/badge.svg)](https://github.com/ofuhrer/icon-grid-generator/actions/workflows/test.yml)
[![Docs](https://github.com/ofuhrer/icon-grid-generator/actions/workflows/docs.yml/badge.svg)](https://ofuhrer.github.io/icon-grid-generator/)
[![PyPI](https://img.shields.io/pypi/v/icon-grid-generator.svg)](https://pypi.org/project/icon-grid-generator/)
[![Python](https://img.shields.io/badge/python-3.10--3.14-blue.svg)](.github/workflows/test.yml)
[![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE)

Pure Python generation of deterministic ICON-style triangular grids.

![Global ICON grid resolutions](docs/assets/global-icon-grid-series.png)

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. Large global grids use export-first generation
with bounded derived-field memory and resumable disk checkpoints.

## Installation

The base package requires Python 3.10 or newer and NumPy:

```bash
python -m 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:

```bash
python -m pip install "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:

```python
from grid_generator import generate_grid

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

Generate a large global grid directly to NetCDF:

```py
from grid_generator import generate_grid_to_netcdf

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

This export-first path supports global grids only. `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 85 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.
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.

| R2B12 output | Generation | NetCDF export | Total | Peak RSS | Checkpoints | NetCDF |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| Full | 43.51 min | 91.24 min | 134.74 min | 328.18 GiB | 162.46 GiB | 1,047.50 GiB |
| Reduced | 42.03 min | 42.05 min | 84.08 min | 328.18 GiB | 162.46 GiB | 485.00 GiB |

See [Performance and Scaling](https://ofuhrer.github.io/icon-grid-generator/design/#performance-and-scaling)
for R2B8–R2B12 measurements, component timings, validation details, and all
field-profile storage sizes.

## Documentation

- [Documentation home](https://ofuhrer.github.io/icon-grid-generator/)
- [API and usage](https://ofuhrer.github.io/icon-grid-generator/api/)
- [Examples](https://ofuhrer.github.io/icon-grid-generator/examples/)
- [Design, limits, and performance](https://ofuhrer.github.io/icon-grid-generator/design/)
- [Contributing](CONTRIBUTING.md)
- [Changelog](CHANGELOG.md)

Citation metadata is provided in [CITATION.cff](CITATION.cff). The package is
distributed under the [BSD 3-Clause License](LICENSE).
