Tutorial 1: Getting Started

Previous: Building a 2D Poisson Solver; Next: Implement: Matrices

Objectives

In this tutorial, we will guide you through the installation process of Ginkgo. We will explain what software you need to install Ginkgo, how to build Ginkgo, run its unit tests, install it in a system folder, and finally run the examples shipped with it.

Prerequisites

The detailed prerequisites are available in your Ginkgo version of choice's README.md and INSTALL.md. In this tutorial, we assume that the develop version is used and we explain some common use cases of the Ginkgo library.

Building ginkgo

As a first step, clone the Ginkgo repository on your local machine.

git clone https://github.com/ginkgo-project/ginkgo.git

Next, enter the cloned repository, create a build directory and enter it.

cd ginkgo
mkdir build
cd build

In the next step, you have to configure the Ginkgo installation process.

If your system supports it, the easiest way to configure your installation is to use the CMake curses interface

ccmake ..

and then configure the options as desired. After having generated the CMake configuration, you initiate the build process via

make -j4

where 4 defines the number of cores you want to use in the parallel compilation.

The alternative way for configuring the installation process is to follow the standard cmake build procedure as

cmake -G "Unix Makefiles" [OPTIONS] .. && make

where you can replace [OPTIONS] with the desired cmake options. To build the reference version of all of the kernels in Ginkgo, use -DGINKGO_BUILD_REFERENCE={ON,OFF} (default is ON). The reference kernels are not optimized for performance, they serve as a correctness-check for the algorithms, and are guaranteed to compute the correct result. If your platform supports OpenMP and you want to use optimized OpenMP kernels, use -DGINKGO_BUILD_OMP={ON,OFF} (default is OFF). Similarly, if your platform supports CUDA (i.e. has a CUDA-capable accelerator) and you want to use CUDA kernels, use -DGINKGO_BUILD_CUDA={ON,OFF} (default is OFF).

If you want to build Ginkgo's unit tests use -DGINKGO_BUILD_TESTS={ON,OFF} (default is ON). The unit tests are based on googletest, and if there is no googletest installation available on your system, the cmake build process with automatically download and install googletest.

To build further examples on the functionality of Ginkgo, use -DGINKGO_BUILD_EXAMPLES={ON,OFF} (default is ON).

The option -DGINKGO_DEVEL_TOOLS={ON,OFF} (default is ON) sets up the build system for development. In case you want to implement new algorithms inside Ginkgo, you need to set it to ON. If you only plan to use Ginkgo as a library inside a larger application, you can turn it off.

To build Ginkgo in Debug mode with these options, the cmake build procedure would be

cmake -G "Unix Makefiles" -BDebug -DCMAKE_BUILD_TYPE=Debug -DGINKGO_DEVEL_TOOLS=ON \
         -DGINKGO_BUILD_TESTS=ON -DGINKGO_BUILD_EXAMPLES=ON -DGINKGO_BUILD_REFERENCE=ON \
	    -DGINKGO_BUILD_OMP=ON -DGINKGO_BUILD_CUDA=ON ..
cmake --build Debug -j [JOBS]

where you replace [JOBS] with the number of jobs you want to use.

In case you want to install Ginkgo into a specific location, you can use the option -DCMAKE_INSTALL_PREFIX=path. The default location is usually /usr/local/.

For a detailed description of all the available build options please see the Installation page.

Running unit tests [optional]

Assuming you have built Ginkgo with -DGINKGO_BUILD_TESTS=ON, you now can run Ginkgo's unit tests by calling

cd Debug/
make test

You will see tests for the Reference, OpenMP, and CUDA implementations of all the routines in Ginkgo, depending on which build options you have chosen.

Installation

After all tests passed you are ready to install Ginkgo into the specified path. This can simply be done with

make install

If you didn't set an installation prefix with -DCMAKE_INSTALL_PREFIX or if the installation prefix is not writable for your user, you might have to call