Giter Site home page Giter Site logo

gt4py's Introduction

GT4Py: GridTools for Python

WARNING!

GT4Py is still under development and is in an incomplete state. While GT4Py has been proven to work for some basic applications already, we are working actively on making GT4Py suitable for more use cases by adding features, improving performance as well as reliability and adding a thorough documentation. GT4Py will be changing for the time being. New features will be implemented, APIs may change and dependencies will be added.

Description

GT4Py is a Python library for generating high performance implementations of stencil kernels from a high-level definition using regular Python functions. GT4Py uses the GridTools Framework for a native implementation of the kernel, but other code-generating backends are also available.

The GridTools framework is a set of libraries and utilities to develop performance portable applications in the area of weather and climate. To achieve the goal of performance portability, the user-code is written in a generic form which is then optimized for a given architecture at compile-time. The core of GridTools is the stencil composition module which implements a DSL embedded in C++ for stencils and stencil-like patterns. Further, GridTools provides modules for halo exchanges, boundary conditions, data management and bindings to C and Fortran.

Installation instructions

GT4Py contains a standard setup.py installation script that might be installed as usual with pip. Additional commands are provided to install and remove the GridTools C++ sources, which are not contained in the package.

IMPORTANT: if the user provides a custom installation of GridTools C++ sources, it should be compatible with the latest stable release of GridTools, which is the version targeted by GT4Py. Note that a compilation problem may also appear if there is a different GridTools C++ version installed in a standard prefix (e.g. /usr/local) which could be included in user-provided or standard setuptools include paths (for example if Boost is installed in the same prefix).

As usual in Python, we strongly recommended to create a new virtual environment for any project:

# Create a virtual environment using the 'venv' module
python -m venv path_for_the_new_venv

# Activate the virtual environment and make sure that 'wheel' is installed
source path_for_the_new_venv/bin/activate
pip install --upgrade wheel

Recommended installation for regular users

If you are not planning to modify GT4Py sources, the easiest way to complete the installation would be:

# First, clone the repository
git clone https://github.com/gridtools/gt4py.git

# Then install the Python package directly from the local repository
# For the CUDA backends add the '[cudaXX]' optional dependency
# (XX = 90, 91, 92, 100 or 101 depending on CUDA version 9.0, 9.1, ...)
pip install -e ./gt4py     # pip install -e ./gt4py[cudaXX]

Alternatively, if you do not need to build the documentation or look at the examples, you could install GT4Py directly from the GitHub repository:

# Install the package directly from GitHub:
# For the CUDA backends add the '[cudaXX]' optional dependency
# (XX = 90, 91, 92, 100 or 101 depending on CUDA version 9.0, 9.1, ...)
pip install git+https://github.com/gridtools/gt4py.git
# pip install git+https://github.com/gridtools/gt4py.git#egg=gt4py[cudaXX]

In either case, you need to run a post-installation script to install GridTools C++ sources.The new gtc: backends require GridTools v2, while the old GT4Py gt: backends require GridTools v1:

# Run the command to install GridTools v1.x C++ sources
python -m gt4py.gt_src_manager install -m 1

# Run the command to install GridTools v2.x C++ sources
python -m gt4py.gt_src_manager install -m 2

Note that pip will not delete GridTools C++ sources when uninstalling the package, so make sure you run the remove command in advance:

python -m gt4py.gt_src_manager remove  # -m 1 and/or -m 2
pip uninstall gt4py

Recommended installation for developers

For GT4Py developers and advanced users, it is recommended to clone the repository and use an editable installation of GT4Py:

# First, clone the repository
git clone https://github.com/gridtools/gt4py.git

# Then install the Python package directly from the local repository
# adding the '-e' flag to get an editable installation
# For the CUDA backends add the '[cudaXX]' optional dependency
# (XX = 90, 91, 92, 100 or 101 depending on CUDA version 9.0, 9.1, ...)
pip install -e ./gt4py     # pip install -e ./gt4py[cudaXX]

# Run the command to install GridTools C++ sources
python -m gt4py.gt_src_manager install

# Install the pre-commit checks
pip install pre-commit
# You need to have a python3.6 interpreter in your PATH for the following:
pre-commit install-hooks  # in the repo directory
# But you can develop using any version >= 3.6

Documentation

A proper documentation is in the works. Please refer to the jupyter notebooks in the examples folder of this repository for examples of how GT4Py can be used, or the Quickstart page of the documentation. To build it, you need to clone the repository first (follow the instructions in Recommended installation for developers) and then install the additional development requirements with:

pip install -r ./gt4py/requirements-dev.txt

and then build the docs with:

cd gt4py/docs
make html  # run 'make help' for a list of targets

Development roadmap

A short overview of the new features and changes planned for the coming weeks & months.

  • Update documentation (API reference, tutorial, notebooks and examples)
  • Missing features:
    • Support for unstructured grids (GTScript extensions)
    • Support for run-time values in interval definitions (run-time splitters)
    • Support for different field layouts (storages masks)
    • Support for OOP-based stencil definitions
    • Support for boundary condition functions
    • Support for proper function & stencil calls

gt4py's People

Contributors

dropd avatar eddie-c-davis avatar egparedes avatar floriandeconinck avatar fthaler avatar havogt avatar jdahm avatar rheacangeo avatar stubbiali avatar tbennun avatar tehrengruber avatar twicki avatar

Watchers

 avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.