![]() |
Eigen
5.0.1-dev+master
|
The contrib module contrib/Eigen/GPU runs dense and sparse linear algebra on NVIDIA GPUs from ordinary host code. It dispatches to the CUDA math libraries: cuBLAS, cuSOLVER, cuSPARSE, cuFFT, NPP, and optionally cuDSS. You write no kernels, and your source files stay regular .cpp files.
This is a different feature from using Eigen in CUDA kernels, where Eigen's fixed-size objects run inside your own kernels, one small problem per thread. Use this module to run large operations on the GPU, such as a matrix product or a factorization.
The module needs the CUDA Toolkit, version 11.8 or later. Sparse direct solvers also need cuDSS, which is installed separately and requires CUDA 12.0 or later. Define EIGEN_USE_GPU before including the header, because without it the header declares none of the module:
The module is header-only, but your program must link NVIDIA libraries. Always link -lcublas -lcublasLt -lcudart, and add the libraries of the features you use:
| Feature | Additional link flags |
|---|---|
DeviceMatrix, products, triangular solves | none |
| Dense solvers | -lcusolver |
norm(), DeviceScalar arithmetic, /=, cwiseProduct | -lnpps -lnppc |
gpu::SparseContext, gpu::DeviceSparseView | -lcusparse |
ConjugateGradient on a gpu::DeviceSparseView | -lcusparse -lnpps -lnppc |
gpu::FFT | -lcufft |
Sparse direct solvers (define EIGEN_CUDSS before the include) | -lcudss |
With CMake, the CUDAToolkit package provides these libraries as targets. This program uses the dense solvers:
For other features, add CUDA::cusparse, CUDA::cufft, CUDA::npps and CUDA::nppc as the table requires. cuDSS is not part of that package: find it with find_package(cudss) and link its cudss target.
GPU and CPU code coexist in one program, because there is no global switch: you choose the GPU by using the types in the Eigen::gpu namespace. A gpu::DeviceMatrix holds a dense, column-major matrix in device memory. Move data with fromHost() and toHost(). Between those calls, expressions look like their CPU counterparts:
The expression d_A.llt().solve(d_B) factorizes on every evaluation. To reuse a factorization, or to check for numerical failure, use a solver class instead. The classes are gpu::LLT, gpu::LU, gpu::QR, gpu::SVD and gpu::SelfAdjointEigenSolver:
The solvers also accept host matrices and handle the transfers themselves, which makes them the smallest change from CPU code:
Define EIGEN_CUDSS to enable gpu::SparseLLT, gpu::SparseLDLT and gpu::SparseLU. They take an ordinary SparseMatrix and host vectors:
As with the CPU solvers, a sequence of matrices with one sparsity pattern can share the symbolic analysis, by calling analyzePattern() once and factorize() for each matrix.
For sparse matrix-vector products, gpu::SparseContext uses cuSPARSE. Its deviceView() also lets Eigen's own ConjugateGradient run on the GPU, with the identity preconditioner and real scalars:
A gpu::SparseContext caches one matrix at a time, so another deviceView() or a multiply() with a host matrix invalidates its earlier views. Use one context per matrix.
Operations are asynchronous by default. The host waits only where it must: in fromHost(), toHost(), info(), when a gpu::DeviceScalar, the result type of dot() and norm(), converts to a host scalar, and in the forms that return host data, such as solve() on a host matrix, and gpu::FFT and gpu::SparseContext::multiply() on host vectors. The dense solvers also wait when compute() takes a host matrix, and an internal workspace that has to grow waits for the work using it. Debug builds also wait to check the factorization, on the first solve() after compute() and on each llt().solve(). Transfers are usually the main cost, so keep intermediate results on the device and download only what the host needs.
Each thread gets a default gpu::Context, which holds a CUDA stream and the library handles. One Context is not thread-safe. To run work on separate streams, or to share a stream with your own CUDA code, create contexts explicitly. DeviceMatrix synchronizes across streams automatically:
There are two kinds of failure:
EIGEN_GPU_CHECK_FAILED(error, expression, file,
line) before including the module.info(). Release builds do not check it for you, and the one-shot llt().solve() form has no info(), so use a solver class and call info() where failure is possible. cuSOLVER 11.4.1 and 11.4.2, from CUDA 11.8 and 12.0, do not detect a non-positive-definite input to gpu::LLT: info() reports success and the factor contains NaNs. CUDA 12.1 and later report it.DeviceMatrix is not an Eigen expression type and does not derive from MatrixBase, so it cannot be passed to code templated on MatrixBase. It also has no coefficient access.norm() is a dot product and an NPP square root, and llt().solve() is a copy, a factorization and a solve. Unlike CPU expressions, GPU expressions do not fuse into a single loop, and an unsupported expression is a compile error.float, double, std::complex<float> and std::complex<double>, unless a class states otherwise.EIGEN_NO_CUDA_TENSOR_OPS to disable them.The module README is the complete reference. It covers the BLAS operations, FFT, solver configuration, stream control, and the mapping from each expression to its library calls.