GT4Py

1.1.9 verified Fri May 01 auth: no python

GT4Py (GridTools for Python) is a Python library for generating high-performance implementations of stencil kernels for weather and climate modeling from a domain-specific language (DSL). It supports multiple backends including numpy, CUDA, and DaCe. Currently at version 1.1.9, released irregularly (multiple minor releases per year). Requires Python >=3.10, <3.15.

pip install gt4py

Common errors

error ModuleNotFoundError: No module named 'gt4py' ↓

cause Library not installed, or Python environment not activated.

fix

Run 'pip install gt4py' in the correct Python environment.

error ImportError: cannot import name 'Stencil' from 'gt4py' ↓

cause Wrong import path; Stencil is in gt4py.cartesian.

fix

Use 'from gt4py.cartesian import Stencil'.

error ValueError: Backend 'cuda' is not available. ↓

cause CUDA backend was removed in v1.1.0.

fix

Use 'gtcuda' or 'dace:cuda' as backend. See docs for details.

Warnings

breaking The 'cuda' backend was removed in v1.1.0. Use 'gtcuda' or 'dace:cuda' instead. ↓

fix Change backend from 'cuda' to 'gtcuda' or use Dace with CUDA backend 'dace:cuda'.

deprecated The 'redundant region syntax' is removed in v1.1.9. Old code using `region` that is now redundant will break. ↓

fix Remove redundant region syntax; ensure all regions are necessary.

gotcha For DaCe backends, field layout must match the stencil's iteration order. Use `dace:gpu` with Fortran layout or specify layout explicitly. ↓

fix Set environment variable GT4PY_CARTESIAN_ENABLE_OPENMP=0 if OpenMP is not available (e.g., on macOS with Apple Clang).

gotcha OpenMP is enabled by default but may not be supported by all compilers (e.g., Apple Clang). This can cause build failures. ↓

fix Set environment variable GT4PY_CARTESIAN_ENABLE_OPENMP=0 to disable OpenMP.

Imports

Stencil

wrong

from gt4py import Stencil

correct

from gt4py.cartesian import Stencil

Stencil class is in the cartesian subpackage

computation
wrong
```
from gt4py.gtscript import computation
```
correct
```
from gt4py.cartesian.gtscript import computation
```
computation is a function inside gtscript module, accessible via gt4py.cartesian.gtscript

Quickstart

Define a simple stencil that adds 1 to each element, compile it with the numpy backend, and execute.

import numpy as np
from gt4py.cartesian import Stencil, gtscript

def my_stencil_def(in_field: gtscript.Field[float], out_field: gtscript.Field[float]):
    with computation(PARALLEL), interval(...):
        out_field = in_field[0, 0, 0] + 1.0

# Create the stencil
my_stencil = Stencil(
    definition=my_stencil_def,
    backend="numpy",
    rebuild=False,
)

# Run on sample data
inp = np.random.rand(10, 10, 10).astype(np.float64)
out = np.empty_like(inp)
my_stencil(inp=inp, out_field=out, origin=(0, 0, 0), domain=(10, 10, 10))