hipSOLVER is a LAPACK marshalling library, with multiple supported backends. It sits between the application and a 'worker' LAPACK library, marshalling inputs into the backend library and marshalling results back to the application. hipSOLVER exports an interface that does not require the client to change, regardless of the chosen backend. Currently, hipSOLVER supports rocSOLVER and cuSOLVER as backends.

Download pre-built packages from ROCm's package servers. Release notes are available on the releases tab of the library's github page.

• sudo apt update && sudo apt install hipsolver

The root of this repository has a helper bash script install.sh to build and install hipSOLVER on Ubuntu with a single command. It does not take a lot of options and hard-codes configuration that can be specified through invoking cmake directly, but it's a great way to get started quickly and can serve as an example of how to build/install. A few commands in the script need sudo access, so it may prompt you for a password.

• ./install.sh -id -- build library, build dependencies, and install (-d flag only needs to be passed once on a system).
• ./install.sh -ic -- build library, build clients (tests, benchmarks, and samples), and install.

To see more options, use the help option of the install script.

• ./install.sh -h

For a standard library installation, follow these steps:

mkdir -p <HIPSOLVER_BUILD_DIR_PATH>/release
cd <HIPSOLVER_BUILD_DIR_PATH>/release
CXX=/opt/rocm/bin/hipcc cmake <HIPSOLVER_SOURCE_DIR_PATH>
make -j$(nproc)
sudo make install

sudo is required if installing into a system directory such as /opt/rocm, which is the default option.

• Use -DCMAKE_INSTALL_PREFIX=<other_path> to specify a different install directory.
• Use -DCMAKE_BUILD_TYPE=<other_configuration> to specify a build configuration, such as 'Debug'. The default build configuration is 'Release'.

The repository contains source code for client programs that serve as tests, benchmarks, and samples. Client source code can be found in the clients subdirectory.

The hipSOLVER samples have no external dependencies, but our unit test and benchmarking applications do. These clients introduce the following dependencies:

1. boost
2. lapack (lapack itself brings a dependency on a fortran compiler)
3. googletest

Linux distros typically have an easy installation mechanism for boost through the native package manager.

• Ubuntu: sudo apt install libboost-program-options-dev
• Fedora: sudo dnf install boost-program-options

Unfortunately, googletest and lapack are not as easy to install. Many distros do not provide a googletest package with pre-compiled libraries, and the lapack packages do not have the necessary cmake config files for cmake to configure linking the cblas library. hipSOLVER provide a cmake script that builds the above dependencies from source. This is an optional step; users can provide their own builds of these dependencies and help cmake find them by setting the CMAKE_PREFIX_PATH definition. The following is a sequence of steps to build dependencies and install them to the cmake default, /usr/local.

mkdir -p <HIPSOLVER_BUILD_DIR_PATH>/release/deps
cd <HIPSOLVER_BUILD_DIR_PATH>/release/deps
cmake -DBUILD_BOOST=OFF <HIPSOLVER_SOURCE_PATH>/deps   #assuming boost is installed through package manager as above
make -j$(nproc) install

Once dependencies are available on the system, it is possible to configure the clients to build. This requires a few extra cmake flags to the library's cmake configure script. If the dependencies are not installed into system defaults (like /usr/local), you should pass the CMAKE_PREFIX_PATH to cmake to help find them.

• -DCMAKE_PREFIX_PATH="<semicolon separated paths>"

CXX=/opt/rocm/bin/hcc cmake -DBUILD_CLIENTS_TESTS=ON -DBUILD_CLIENTS_BENCHMARKS=ON [HIPSOLVER_SOURCE]
make -j$(nproc)
sudo make install   # sudo required if installing into system directory such as /opt/rocm

The hipSOLVER interface is compatible with rocSOLVER and cuBLAS-v11 APIs. Porting a CUDA application that originally calls the cuSOLVER API to an application calling the hipSOLVER API should be relatively straightforward. For example, the hipSOLVER SGETRF interface is

hipsolverStatus_t
hipsolverSgetrf_bufferSize(hipsolverHandle_t handle,
                           int m,
                           int n,
                           float* A,
                           int lda,
                           int* lwork);

hipsolverStatus_t
hipsolverSgetrf(hipsolverHandle_t handle,
                int               m,
                int               n,
                float*            A,
                int               lda,
                float*            work,
                int*              devIpiv,
                int*              devInfo);

While the API of hipSOLVER is, overall, modeled after that of cuSOLVER, there are some notable differences. In particular:

• hipsolverXgesvd_bufferSize requires jobu and jobv as arguments
• hipsolverXgetrf requires lwork as an argument
• hipsolverXgetrs requires work and lwork as arguments, and
• hipsolverXpotrfBatched requires work and lwork as arguments.

In order to support these changes, hipSOLVER adds the following functions as well:

• hipsolverXgetrs_bufferSize
• hipsolverXpotrfBatched_bufferSize

Furthermore, due to differences in implementation and API design between rocSOLVER and cuSOLVER, not all arguments are handled identically between the two backends. When using the rocSOLVER backend, keep in mind the following differences:

• While many cuSOLVER functions (and, consequently, hipSOLVER functions) take a workspace pointer and size as arguments, rocSOLVER maintains its own internal device workspace by default. In order to take advantage of this feature, users may pass a null pointer for the work argument of any function when using the rocSOLVER backend, and the workspace will be automatically managed behind-the-scenes. It is recommended to use a consistent strategy for workspace management, as performance issues may arise if the internal workspace is made to flip-flop between user-provided and automatically allocated workspaces.

• Additionally, unlike cuSOLVER, rocSOLVER does not provide information on invalid arguments in its info arguments, though it will provide info on singularities and algorithm convergence. As a result, the info argument of many functions will not be referenced or altered by the rocSOLVER backend, excepting those that provide info on singularities or convergence.

For a complete description of all the supported functions, see the corresponding backends' documentation at rocSOLVER API and/or cuSOLVER API.