Install rocALUTION

Install rocALUTION#

You can install rocALUTION as part of the AMD ROCm software stack on Linux, or build it from source. Install ROCm before you build or use rocALUTION.

When you install rocALUTION through ROCm, you get a single-node, accelerator-enabled library. If you need a different configuration, such as multi-node or distributed execution, build rocALUTION from source.

Prerequisites#

You need a ROCm enabled platform to use rocALUTION. For more information, including a list of supported GPUs and Linux distributions, see the ROCm on Linux install guide.

You need the following prerequisites to build rocALUTION from source:

Install these components before you build rocALUTION. Refer to their respective documentation for install instructions.

For multi-node configurations, you must also install:

Install pre-built packages#

Use the following commands to install rocALUTION on Ubuntu or Debian:

sudo apt-get update
sudo apt-get install rocalution

Use the following commands to install rocALUTION on RHEL-based platforms:

sudo yum update
sudo yum install rocalution

Use the following commands to install rocALUTION on SLES:

sudo zypper refresh
sudo zypper install rocalution

Note

On SLES, use zypper instead of dnf. The ROCm repositories must be configured first, and installing the full rocm package is usually recommended because rocALUTION depends on other ROCm components.

After you install rocALUTION, you can use it like any other library with a C++ API. Include the header file in your code to call rocALUTION. The rocALUTION shared library becomes a link-time and run-time dependency for your application.

Build rocALUTION from source#

You don’t need to build rocALUTION from source if you install the prebuilt packages described above. To build rocALUTION from source, follow the instructions in this section.

You need the AMD ROCm Platform to compile and run rocALUTION. When you build rocALUTION from source, select supported versions of the math library dependencies (rocBLAS, rocSPARSE, rocRAND, and rocPRIM). Given a version of rocALUTION, you must use versions of these dependencies that are the same or later.

Download rocALUTION#

You can find the rocALUTION source code in the ROCm/rocm-libraries repository.

To limit your local checkout to only the rocALUTION project, configure sparse-checkout before you clone. The partial clone feature (--filter=blob:none) reduces how much data you download. Use the following commands for a sparse checkout:

Note

To include the rocBLAS, rocSPARSE, rocRAND, and rocPRIM dependencies, set the projects for the sparse checkout using git sparse-checkout set projects/rocalution projects/rocblas projects/rocsparse projects/rocrand projects/rocprim.

git clone --no-checkout --filter=blob:none https://github.com/ROCm/rocm-libraries.git
cd rocm-libraries
git sparse-checkout init --cone
git sparse-checkout set projects/rocalution
git checkout develop
cd projects/rocalution

Note

For ROCm preview releases (7.11, 7.12, 7.13, 7.14), use the develop branch. For production ROCm 7.2.x, use release/rocm-rel-7.2. To build ROCm 6.4.3 and earlier, use the standalone rocALUTION repository. For more information, see the documentation associated with the release you want to build.

To download the develop branch for all projects in rocm-libraries, use these commands. This process takes longer, but use it if you work with a large number of libraries.

git clone -b develop https://github.com/ROCm/rocm-libraries.git
cd rocm-libraries/projects/rocalution

Build rocALUTION using the install script#

Use the install.sh script to install rocALUTION. The following tables describe how to build different packages of the library, including the dependencies and clients.

Note

Run the install.sh script from the projects/rocalution directory.

Use install.sh to build rocALUTION with dependencies#

The following table lists the common ways to use install.sh to build the rocALUTION dependencies and library.

Command

Description

./install.sh -h

Print the help information.

./install.sh -d

Build the dependencies and library in your local directory. Use the -d flag only once. For subsequent invocations of install.sh, you don’t need to rebuild the dependencies.

./install.sh

Build the library in your local directory. The script assumes the dependencies are available.

./install.sh -i

Build the library, then build and install the rocALUTION package in /opt/rocm. The script prompts you for sudo access. This installs rocALUTION for all users.

./install.sh --mpi=<dir> -i

Build the library with MPI support enabled, then build and install the rocALUTION package in /opt/rocm.

Use install.sh to build rocALUTION with dependencies and clients#

The clients contain example code, unit tests, and benchmarks. The following table lists common ways to use install.sh to build the library, dependencies, and clients.

Command

Description

./install.sh -dc

Build the dependencies, library, and client in your local directory. Use the -d flag only once. For subsequent invocations of install.sh, you don’t need to rebuild the dependencies.

./install.sh -c

Build the library and client in your local directory. The script assumes the dependencies are available.

./install.sh -idc

Build the library, dependencies, and client, then build and install the rocALUTION package in /opt/rocm. The script prompts you for sudo access. This installs rocALUTION for all users.

./install.sh -ic

Build the library and client, then build and install the rocALUTION package in /opt/rocm. The script prompts you for sudo access. This installs rocALUTION for all users.

./install.sh -o

Build the client executables using an already installed version of the library.

Build rocALUTION using individual make commands#

The rocALUTION library contains both host and device code, so specify the HIP compiler during the CMake configuration process.

You can build rocALUTION using the following commands:

Note

Run these commands from the projects/rocalution directory.

Note

You need CMake 3.5 or later to build rocALUTION.

# Create and change to build directory
mkdir -p build/release
cd build/release

# Default install path is /opt/rocm, use -DCMAKE_INSTALL_PREFIX= to adjust it
CXX=/opt/rocm/bin/amdclang++ cmake ../..

# Compile rocALUTION library
make -j$(nproc)

# Install rocALUTION to /opt/rocm
make install

You can also configure the following optional CMake directives:

  • SUPPORT_HIP: Enable HIP support. This option is ON by default.

  • SUPPORT_OMP: Enable OpenMP support. This option is ON by default.

  • SUPPORT_MPI: Enable MPI support for multi-node execution. This option is OFF by default.

  • BUILD_SHARED_LIBS: Build rocALUTION as a shared library. This option is ON by default and is recommended.

  • BUILD_EXAMPLES: Build the example programs. This option is ON by default.

For example, to build rocALUTION with MPI support enabled:

CXX=/opt/rocm/bin/amdclang++ cmake ../.. -DSUPPORT_MPI=ON -DROCM_PATH=/opt/rocm/

Test your rocALUTION installation#

Verify that you built and installed rocALUTION correctly by running the Conjugate Gradient (CG) solver client on a sample Laplacian matrix.

These steps assume you built rocALUTION with client applications enabled (the default configuration).

  1. Open a terminal and ensure the ROCm environment is available (for example, rocminfo and hipcc are in your PATH).

  2. Change to the directory containing the built CG client. For a Release build:

    cd build/release/clients/staging

    For a Debug build:

    cd build/debug/clients/staging

  3. Download a test matrix in Matrix Market format:

    wget https://math.nist.gov/pub/MatrixMarket2/Harwell-Boeing/laplace/gr_30_30.mtx.gz

  4. Extract the matrix file:

    gzip -d gr_30_30.mtx.gz

  5. Run the CG solver client:

    ./cg gr_30_30.mtx

If your installation succeeded, the solver prints iteration and residual information and converges without errors.

Contents