Introduction¶
What Is GridTools¶
The GridTools (GT) framework is a set of libraries and utilities to develop performance portable applications in which stencil operations on grids are central. The focus of the project is on regular and block-structured grids as are commonly found in the weather and climate application field. In this context, GT provides a useful level of abstraction to enhance productivity and obtain excellent performance on a wide range of computer architectures. Additionally, it addresses the challenges that arise from integration into production code, such as the expression of boundary conditions, or conditional execution. The framework is structured such that it can be called from different weather models (numerical weather and climate codes) or programming interfaces, and can target various computer architectures. This is achieved by separating the GT core library in a user facing part (frontend) and architecture specific (backend) parts. The core library also abstracts various possible data layouts and applies optimizations on stages with multiple stencils. The core library is complemented by facilities to interoperate with other languages (such as C and Fortran), to aid code development and a communication layer.
GridTools provides optimized backends for GPUs and manycore architectures. Stencils can be run efficiently on different architectures without any code change needed. Stencils can be built up by small composeable units called stages, using GridTools domain-specific language. Such a functor can be as simple as being just a copy stencil, copying data from one field to another:
struct copy_functor {
using in = in_accessor<0>;
using out = inout_accessor<1>;
using param_list = make_param_list<in, out>;
template <typename Evaluation>
GT_FUNCTION static void apply(Evaluation eval) {
eval(out()) = eval(in());
}
};
Several such stages can be composed into a computation and be applied on each grid-point of a grid. Requiring this abstract descriptions of a stencils, the DSL allows GridTools can apply architecture-specific optimizations to the stencil computations in order to be optimal on the target hardware.
Dependencies¶
GridTools requires at least a header-only installation of Boost. Besides some boost utilities, it depends on boost::mpl
and boost::fusion
.
Additionally, GridTools requires a recent version of CMake.
GridTools requires a modern compiler. A list of supported compilers can be found on github.
Installation and Use¶
Simple Script¶
We first provide a sample of the commands needed to enable the multicore and CUDA backends, install them in /usr/local
,
and run the gridtools tests.
git clone http://github.com/eth-cscs/gridtools.git
cd gridtools
mkdir build && cd build
cmake -DGT_ENABLE_BACKEND_MC=ON -DGT_ENABLE_BACKEND_CUDA=ON -DCMAKE_INSTALL_PREFIX=/usr/local ..
make install -j4
make test
GridTools uses CMake as building system. The installation can be configured using ccmake. The following variables control the back-ends that will be supported by the runtime components of the installation, namely GCL.
GT_ENABLE_BACKEND_CUDA # For CUDA GPUs
GT_ENABLE_BACKEND_X86 # For cache based multicores
GT_ENABLE_BACKEND_NAIVE # For naive implementation
GT_ENABLE_BACKEND_MC # For optimized multicores and KNL
All the targets can be installed and used at the same time, but some runtime components may lead to incompatibilities or complex environments to make the codes run. It may be more effective to do multiple installs of the library for different targets in this case.
At the moment the only runtime component of GridTools is the GCL, the communication module. By default, this component will be installed in the system as a single-node mockery of the full distributed memory capability. To enable the full GCL you must set to ON
the following variable
GT_USE_MPI
In addition, it may be convenient to install the library without compiling and running the tests, that use multiple nodes. To do so you can set to ON
the following variable:
GT_GCL_ONLY
Other variables can be useful for your system, and you can find their descriptions using ccmake
.
When installing GridTools all the source codes of the components will be copied to the installation path. To avoid compiling and running tests for specific components, GridTools allows to enable or disable components using the following variables, with obvious meaning:
INSTALL_BOUNDARY_CONDITIONS
INSTALL_DISTRIBUTED_BOUNDARIES
INSTALL_COMMON
INSTALL_STENCIL_COMPOSITION
INSTALL_STORAGE
INSTALL_C_BINDINGS
INSTALL_INTERFACE
INSTALL_TOOLS
To have access to these variables INSTALL_ALL
should be set to OFF
.
Examples can be installed by enabling GT_INSTALL_EXAMPLES
. This will install the examples into the path given by
GT_INSTALL_EXAMPLES_PATH
. The examples come with a standalone CMake project and can be built separately, e.g. with
the following set of instructions:
cd examples
mkdir build && cd build
cmake ..
make -j4
Using GridTools¶
Using GridTools follows standard CMake practices. To indicate where the GridTools can be found,
CMake should be provided with the variable GridTools_DIR
,
e.g. by calling CMake with -DGridTools_DIR=</path/to/gridtools/lib/cmake>
.
The CMakeLists.txt
file should then contain the following lines:
find_package(GridTools VERSION ... REQUIRED)
list(APPEND CMAKE_MODULE_PATH "${GridTools_MODULE_PATH}")
Note
If GridTools uses the CUDA backend, you must call enable_language(CUDA)
before finding the package.
Targets that need GridTools should link against GridTools::gridtools
. If the communication module is needed GridTools::gcl
should be used instead.
add_library(my_library source.cpp)
target_link_libraries(my_library PUBLIC GridTools::gridtools)
Contributing¶
Contributions to the GridTools set of libraries are welcome. However, our policy is that we will be the official maintainers and providers of the GridTools code. We believe that this will provide our users with a clear reference point for support and guarantees on timely interactions. For this reason, we require that external contributions to GridTools will be accepted after their authors provide to us a signed copy of a copyright release form to ETH Zurich.