Skip to content
GridToolsPublic

About

Python library for generating high-performance implementations of stencil kernels for weather and climate modeling from a domain-specific language (DSL).

Resources

Contributing

Stars

155 stars

Watchers

9 watching

Forks

Latest commit

 

History

2,117 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

logo

license slack

Daily CI test-components qa

uv Nox

GT4Py: GridTools for Python

GT4Py is a Python library for generating high performance implementations of stencil kernels from a high-level definition using regular Python functions. GT4Py is part of the GridTools framework, a set of libraries and utilities to develop performance portable applications in the area of weather and climate modeling.

NOTE: GT4Py contains two generations of the library, which are not compatible with each other. gt4py.next is the current one, where most of the active development happens, and the one to choose for new projects. gt4py.cartesian is the previous generation, limited to Cartesian grids: it is still maintained for the models relying on it and enriched with features where needed.

🚜 Installation

GT4Py can be installed as a regular Python package using uv, pip or any other PEP-517 compatible frontend. We strongly recommended to useuv to create and manage virtual environments for your own projects.

⚙ Configuration

Other useful available environment variables are:

  • CUDA_ARCH: Set the compute capability of the NVIDIA GPU if it is not detected automatically by cupy.
  • CXX: Set the C++ compiler.
  • GT_CACHE_DIR_NAME: Name of the compiler's cache directory (defaults to .gt_cache)
  • GT_CACHE_ROOT: Path to the compiler cache (defaults to ./)

More options and details are available in config.py.

🛠 Development Instructions

Follow the installation instructions below to initialize a development virtual environment containing an editable installation of the GT4Py package. Make sure you read the CONTRIBUTING.md and CODING_GUIDELINES.md documents before you start working on the project.

Development Environment Installation using uv

GT4Py uses the uv project manager for the development workflow. uv is a versatile tool that consolidates functionality usually distributed across different applications into subcommands.

  • The uv pip subcommand provides a fast Python package manager, emulating pip.
  • The uv export | lock | sync subcommands manage dependency versions in a manner similar to the pip-tools command suite.
  • The uv init | add | remove | build | publish | ... subcommands facilitate project development workflows, akin to hatch.
  • The uv tool subcommand serves as a runner for Python applications in isolation, similar to pipx.
  • The uv python subcommands manage different Python installations and versions, much like pyenv.

We require a reasonably recent version of uv, which can be installed in various ways (see its installation instructions), with the recommended method being the standalone installer:

$ curl -LsSf https://astral.sh/uv/install.sh | sh

Once uv is installed in your system, it is enough to clone this repository and let uv handling the installation of the development environment.

# Clone the repository
git clone https://github.com/gridtools/gt4py.git
cd gt4py

# Let uv create the development environment at `.venv`.
uv sync --extra cartesian  # for gt4py.cartesian
uv sync --extra next       # for gt4py.next

# The `--extra cartesian` (or `--extra next`) option tells uv to install
# the optional run-time dependencies of gt4py.cartesian (or gt4py.next),
# and thus it is not strictly necessary.
# The 'dev' group with the core development dependencies is installed by default.

# Finally, activate the virtual environment and start writing code!
source .venv/bin/activate

The newly created venv is a standard Python virtual environment preconfigured with all necessary runtime and development dependencies. Additionally, the gt4py package is installed in editable mode, allowing for seamless development and testing. To install new packages in this environment, use the uv pip subcommand which emulates the pip interface and is generally much faster than the original pip tool (which is also available within the venv although its use is discouraged).

The pyproject.toml file contains both the definition of the gt4py Python distribution package and the settings of the development tools used in this project, most notably uv, ruff, and mypy. It also contains dependency groups (see PEP 735 for further reference) with the development requirements listed in different groups (build, docs, lint, test, typing, ...) and collected together in the general dev group, which gets installed by default by uv as mentioned above.

Development Tasks (/scripts)

Recurrent development tasks like bumping versions of used development tools or required third party dependencies have been collected as separate modules in the /scripts folder, and collected as subcommands of the ./scripts/run tool (see scripts/README.md for the conventions). Read the tool help for a brief description of every task and always use this tool to update the versions and sync the version configuration across different files (e.g. pyproject.toml and .pre-commit-config.yaml).

📖 Documentation

The user documentation is published at gridtools.github.io/gt4py. It is a welcome page linking to two independent subsites, one for gt4py.cartesian and one for gt4py.next, whose sources live in docs/user/ (the welcome page), docs/user/cartesian/ and docs/user/next/.

GT4Py uses the Sphinx tool for the documentation, with pages written in reStructuredText (gt4py.cartesian) or MyST Markdown (welcome page and gt4py.next). To build the whole site in a dedicated environment, run the docs nox session:

./noxfile.py -s docs  # the site is written to 'docs/user/_build/html'

The required tools are provided in the docs dependency group (included in the dev group, which is installed by default by uv sync), so a single site can also be built directly from the development environment:

uv run sphinx-build -b html docs/user/next docs/user/_build/html/next

See docs/development/tools/documentation.md for a description of how the documentation is organized, built and published.

⚖️ License

GT4Py is licensed under the terms of the BSD-3-Clause.

About

Python library for generating high-performance implementations of stencil kernels for weather and climate modeling from a domain-specific language (DSL).

Resources

Contributing

Stars

155 stars

Watchers

9 watching

Forks

Releases

Packages

Used by

Contributors

Languages