rocALUTION

Note

The published documentation is available at rocALUTION in an organized, easy-to-read format, with search and a table of contents. The documentation source files reside in the docs folder of this repository. As with all ROCm projects, the documentation is open source. For more information on contributing to the documentation, see Contribute to ROCm documentation.

rocALUTION is a sparse linear algebra library that can be used to explore fine-grained parallelism on top of the ROCm platform runtime and toolchains. Based on C++ and HIP, rocALUTION provides a portable, generic, and flexible design that allows seamless integration with other scientific software packages.

rocALUTION offers various backends for different (parallel) hardware:

• Host
• OpenMP: Designed for multi-core CPUs
• HIP: Designed for ROCm-compatible devices
• MPI: Designed for multi-node clusters and multi-GPU setups

Requirements

To use rocALUTION on GPU devices, you must first install the rocBLAS, rocSPARSE, and rocRAND libraries. You can install these from the ROCm repository, the GitHub 'releases' tab, or you can manually compile them.

Documentation

Documentation for rocALUTION is available at https://rocm.docs.amd.com/projects/rocALUTION/en/latest/.

To build our documentation locally, use the following code:

cd docs

pip3 install -r sphinx/requirements.txt

python3 -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html

Build

You can compile rocALUTION using CMake 3.5 or later. Note that all compiler specifications are determined automatically.

# Clone rocALUTION using git
git clone https://github.com/ROCm/rocALUTION.git

# Go to rocALUTION directory, create and change to build directory
cd rocALUTION; mkdir build; cd build

# Configure rocALUTION
# Build options:
#   SUPPORT_HIP         - build rocALUTION with HIP support (ON)
#   SUPPORT_OMP         - build rocALUTION with OpenMP support (ON)
#   SUPPORT_MPI         - build rocALUTION with MPI (multi-node) support (OFF)
#   BUILD_SHARED_LIBS   - build rocALUTION as shared library (ON, recommended)
#   BUILD_EXAMPLES      - build rocALUTION examples (ON)
cmake .. -DSUPPORT_HIP=ON -DROCM_PATH=/opt/rocm/

# Build
make

To test your installation, run a CG solver on a Laplacian matrix:

cd rocALUTION; cd build
wget ftp://math.nist.gov/pub/MatrixMarket2/Harwell-Boeing/laplace/gr_30_30.mtx.gz
gzip -d gr_30_30.mtx.gz
./clients/staging/cg gr_30_30.mtx

General information

rocALUTION is based on a generic and robust design that allows expansion in the direction of new solvers and preconditioners with support for various hardware types. The library's design allows the use of all solvers as preconditioners in other solvers. For example, you can define a CG solver with a multi-elimination preconditioner, in which the last-block is preconditioned with another Chebyshev iteration method that itself is preconditioned with a multi-colored symmetric Gauss-Seidel scheme.

Iterative solvers

• Fixed-point iteration schemes: Jacobi, (Symmetric) Gauss-Seidel, SOR, SSOR
• Krylov subspace methods: CR, CG, BiCGStab, BiCGStab(l), GMRES, IDR, QMRCGSTAB, Flexible CG/GMRES
• Mixed-precision defect correction scheme
• Chebyshev iteration scheme
• Multigrid: Geometric and algebraic

Preconditioners

• Matrix splitting schemes: Jacobi, (multi-colored) (symmetric) Gauss-Seidel, SOR, SSOR
• Factorization schemes: ILU(0), ILU(p) (based on levels), ILU(p,q) (power(q)-pattern method), multi-elimination ILU (nested/recursive), ILUT (based on threshold), IC(0)
• Approximate Inverses: Chebyshev matrix-valued polynomial, SPAI, FSAI, TNS
• Diagonal-based preconditioner for Saddle-point problems
• Block-type of sub-preconditioners/solvers
• Additive Schwarz (restricted)
• Variable type of preconditioners

Sparse matrix formats

• Compressed Sparse Row (CSR)
• Modified Compressed Sparse Row (MCSR)
• Dense (DENSE)
• Coordinate (COO)
• ELL
• Diagonal (DIA)
• Hybrid ELL+COO (HYB)

Portability

All code based on rocALUTION is portable and hardware-independent. It compiles and runs on any supported platform. All solvers and preconditioners are based on a single source code implementation that delivers portable results across all backends (note that variations are possible due to different hardware rounding modes). The only visible difference between hardware is performance variation.