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
>
classamgcl::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
¶
-
class
OpenMP (builtin) hybrid backend¶
-
template<class
ScalarType
, classBlockType
>
classamgcl::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
¶
-
class
NVIDIA CUDA backend¶
-
template<class
ValueType
>
classamgcl::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.
-
cusparseHandle_t
-
class
VexCL backend¶
-
template<class
ValueType
>
classamgcl::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.
-
std::vector<vex::backend::command_queue>
-
class
VexCL hybrid backend¶
-
template<class
ScalarType
, classBlockType
>
classamgcl::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.
-
std::vector<vex::backend::command_queue>
-
class
ViennaCL backend¶
-
template<class
Matrix
>
classamgcl::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>
, andviennacl::hyb_matrix<T>
. The backend has no runtime parameters.-
class
params
¶ The backend parameters
-
class
Eigen backend¶
-
template<class
ValueType
>
classamgcl::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
-
class
Blaze backend¶
-
template<class
ValueType
>
classamgcl::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
-
class