GridTools C++

2.3.9 verified Mon Apr 27 auth: no python

A Python wrapper for the GridTools C++ library, providing high-performance stencil computations on structured grids for weather and climate applications. Current version 2.3.9, released under a BSD license. Release cadence is irregular, with minor updates every few months.

pip install gridtools-cpp

Common errors

error ImportError: No module named gridtools_cpp ↓

cause Incorrect import name; the module is 'gridtools' not 'gridtools_cpp'.

fix

Change import to 'import gridtools'.

error ModuleNotFoundError: No module named 'gridtools' ↓

cause Package not installed or installed under different name.

fix

Run 'pip install gridtools-cpp' to install the package.

Warnings

gotcha The Python package name is 'gridtools' (no underscore) despite the PyPI package being 'gridtools-cpp'. Attempting to import 'gridtools_cpp' will fail. ↓

fix Use 'import gridtools' instead.

gotcha GridTools expects Fortran-contiguous (column-major) arrays. Passing C-contiguous arrays may result in incorrect results or performance degradation. ↓

fix Convert arrays using np.asfortranarray() before passing to GridTools functions.

deprecated The older version 1.x used a different API with 'gridtools_cpp' module. Many online examples still reference the old import path. ↓

fix Update imports to use 'gridtools' and refer to current documentation.

Imports

GridTools
wrong
```
from gridtools_cpp import GridTools
```
correct
```
import gridtools
```
The package uses the name 'gridtools' (no underscore) for the Python module, even though the PyPI package is 'gridtools-cpp'.

Quickstart

Basic usage of GridTools Python interface. Note that actual high-performance stencils require compiling C++ kernels via the GridTools library; this Python wrapper exposes that functionality.

import gridtools
import numpy as np

# Define a simple stencil: compute average of neighbors
def stencil(in_field, out_field):
    # GridTools expects Fortran-layout arrays
    in_field = np.asfortranarray(in_field)
    out_field = np.asfortranarray(out_field)
    
    # Example using the gridtools library (mock)
    # Real usage involves building a stencil object and applying it
    out_field[1:-1, 1:-1] = (in_field[:-2, 1:-1] + in_field[2:, 1:-1] +
                              in_field[1:-1, :-2] + in_field[1:-1, 2:]) / 4.0
    return out_field

# Create test data
nx, ny = 10, 10
in_field = np.random.rand(nx, ny)
out_field = np.zeros((nx, ny))

result = stencil(in_field, out_field)
print(result)