The deal.II Readme on interfacing to Ginkgo
Keywords: deal.II

# Interfacing deal.II to Ginkgo

Ginkgo is A numerical linear algebra software package that provides its users with highly optimized fine grid level linear algebra operations. It currently has the capability to solve on the CPU with the support of OpenMP and on the GPU with NVIDIA's CUDA libraries. For some operations it uses NVIDIA's own libraries, CuSparse and CuBLAS, but some routines also have self implemented CUDA functions.See the Ginkgo documentation for more details.

deal.II has wrapper classes to the linear algebra parts of Ginkgo that provide almost the same interfaces as the built-in deal.II linear algebra operations.

## Installing deal.II with Ginkgo

During the CMake configuration, the following flags should be specified:

- `-DDEAL_II_WITH_GINKGO=ON`, to enable the Ginkgo library.
- `-DGINKGO_DIR=`, to specify the path where Ginkgo has been installed.

### Installing Ginkgo

Installing Ginkgo is quite simple. Ginkgo currently uses CMake and hence one can use the following commands to easily install Ginkgo. For different dependencies and compatible libraries, please refer to Ginkgo. The different flags that can be added are:

- `-DGINKGO_BUILD_REFERENCE={ON,OFF}`: Builds the reference single thread implementation used to check the more sophisticated implementations of the GPU/CPU.
- `-DGINKGO_BUILD_CUDA={ON,OFF}`: Builds the GPU implementation, specifically the NVIDIA CUDA implementations. This needs CUDA to be installed on the machine.
- `-DGINKGO_BUILD_OMP={ON,OFF}`: Builds the multithreaded OpenMP implementations.

To install Ginkgo, you would need to:

    	git clone https://github.com/ginkgo-project/ginkgo.git
      mkdir build; cd build
      cmake -DGINKGO_BUILD_REFERENCE=on/off -DGINKGO_BUILD_CUDA=on/off -DGINKGO_BUILD_OMP=on/off -DCMAKE_INSTALL_PREFIX=/path/to/install/ -DCMAKE_BUILD_TYPE=Release/Debug
    	make install

#### Running the Ginkgo tests

Ginkgo uses `gtests` to run unit tests. The reference implementations are non-optimized versions to which the OpenMP and CUDA versions are compared with for correctness. The following command, executed in Ginkgo's build directory, launches its test suite.

    	make test

The output should contain several lines of the form:

         Start  1: path/to/test
     1/13 Test  #1: path/to/test .............................   Passed    0.01 sec

To run only a specific test for more details, from the build directory, run

    	./path/to/test