Backends

A backend in AMGCL is a class that binds datatypes like matrix and vector with parallel primitives like matrix-vector product, linear combination of vectors, or inner product computation. The backend system is implemented using free functions and partial template specializations, which allows to decouple the implementation of common parallel primitives from the specific datatypes used in the supported backends. This makes it possible to adopt third-party or user-defined datatypes for use within AMGCL without any modification of the core library code.

Algorithm setup in AMGCL is performed using internal data structures. As soon as the setup is completed, the necessary objects (mostly matrices and vectors) are transferred to the backend datatypes. Solution phase of the algorithms is expressed in terms of the predefined parallel primitives which makes it possible to switch parallelization technology (such as OpenMP, CUDA, or OpenCL) simply by changing the backend template parameter of the algorithm. For example, the norm of the residual \(\epsilon = ||f - Ax||\) in AMGCL is computed with amgcl::backend::residual() and amgcl::backend::inner_product() primitives:

backend::residual(f, A, x, r);
auto e = sqrt(backend::inner_product(r, r));

The backends currenly supported by AMGCL are listed below.

OpenMP (builtin) backend

template<class ValueType>
class amgcl::backend::builtin

Include <amgcl/backend/builtin.hpp>.

This is the bultin backend that does not have any external dependencies and uses OpenMP-parallelization for its primitives. As with any backend in AMGCL, it is defined with a value type template parameter, which specifies the type of the system matrix elements. The backend is also used internally by AMGCL during construction phase, and so moving the constructed datatypes (matrices and vectors) to the backend has no overhead. The backend has no parameters (the params subtype is an empty struct).

class params

OpenMP (builtin) hybrid backend

template<class ScalarType, class BlockType>
class amgcl::backend::builtin_hybrid

Include <amgcl/backend/builtin_hybrid.hpp>.

The hybrid builtin backend uses the scalar value type to build the hierarchy in the same way the builtin backend does. But before the constructed matrices are moved to the backend, they are converted to the block-wise format in order to improve the solution performance. This is especially helpful when a set of near null-space vectors is provided to the AMG preconditioner. In this case it is impossible to use block value type during the preconditioner construction, but the matrices still have block-wise structure.

See Using near null-space vectors and issue #215 for more details.

Similar to the builtin backend, the hybrid builtin backend has no parameters.

class params

NVIDIA CUDA backend

template<class ValueType>
class amgcl::backend::cuda

Include <amgcl/backend/cuda.hpp>.

The backend uses the NVIDIA CUDA technology for the parallelization of its primitives. It depends on the Thrust and cuSPARSE libraries. The code using the backend has to be compiled with NVIDIA’s nvcc compiler. The user needs to initialize the cuSPARSE library with a call to the cusparseCreate() function and pass the returned handle to AMGCL in the backend parameters.

class params

The backend parameters

cusparseHandle_t cusparse_handle

cuSPARSE handle created with the cusparseCreate() function.

VexCL backend

template<class ValueType>
class amgcl::backend::vexcl

Include <amgcl/backend/vexcl.hpp>.

The backend uses the VexCL library for the implementation of its primitives. VexCL provides OpenMP, OpenCL, or CUDA parallelization, selected at compile time with a preprocessor definition. The user has to initialize the VexCL context and pass it to AMGCL via the backend parameter.

class params

The backend parameters

std::vector<vex::backend::command_queue> q

VexCL command queues identifying the compute devices in the compute context.

bool fast_matrix_setup = true

Transform the CSR matrices into the internal VexCL format on the GPU. This is faster, but temporarily requires more memory on the GPU.

VexCL hybrid backend

template<class ScalarType, class BlockType>
class amgcl::backend::vexcl_hybrid

Include <amgcl/backend/vexcl.hpp>.

The hybrid VexCL backend, similar to the hybrid OpenMP backend, uses scalar value type during the method setup, and converts the constructed matrices to block-wise format before moving them to the backend.

class params

The backend parameters

std::vector<vex::backend::command_queue> q

VexCL command queues identifying the compute devices in the compute context.

bool fast_matrix_setup = true

Transform the CSR matrices into the internal VexCL format on the GPU. This is faster, but temporarily requires more memory on the GPU.

ViennaCL backend

template<class Matrix>
class amgcl::backend::viennacl

Include <amgcl/backend/viennacl.hpp>.

The backend uses the ViennaCL library for the implementation of its primitives. ViennaCL is a free open-source linear algebra library for computations on many-core architectures (GPUs, MIC) and multi-core CPUs. The library is written in C++ and supports CUDA, OpenCL, and OpenMP (including switches at runtime). The template parameter for the backend specifies ViennaCL matrix class to use. Possible choices are viannacl::compressed_matrix<T>, viennacl::ell_matrix<T>, and viennacl::hyb_matrix<T>. The backend has no runtime parameters.

class params

The backend parameters

Eigen backend

template<class ValueType>
class amgcl::backend::eigen

Include <amgcl/backend/eigen.hpp>.

The backend uses Eigen library datatypes for implementation of its primitives. It could be useful in case the user already works with the Eigen library, for example, to assemble the linear system to be solved with AMGCL. AMGCL also provides an Eigen matrix adapter, so that Eigen matrices may be transparently used with AMGCL solvers.

class params

The backend parameters

Blaze backend

template<class ValueType>
class amgcl::backend::blaze

Include <amgcl/backend/blaze.hpp>.

The backend uses Blaze library datatypes for implementation of its primitives. It could be useful in case the user already works with the Blaze library, for example, to assemble the linear system to be solved with AMGCL.

class params

The backend parameters