Getting started¶

Dependencies¶

To build the HighFM library, you must have the following packages installed:

A C++20 compiler with support to OpenMP (e.g., clang, gcc, etc.)
CMake
The {fmt} formatting library
A BLAS/LAPACK library, for instance, Intel MKL or AMD AOCL
HDF5 (optional)
NVIDIA CUDA Toolkit (optional)

Note

Intel(R) MKL, AMD AOCL and NVIDIA CUDA are proprietary software and it is the responsibility of users to buy or register for community (free) licenses for their products.

Installation¶

First, clone the source code from the GitLab repository:

git clone https://gitlab.com/highfm/highfm

Then, build and install the library using the following commands:

cd highfm
cmake -B build -DCMAKE_INSTALL_PREFIX=<install directory>
make -C build/ -j
make -C build/ install -j

Additionally, you can customize your installation by adding -D<option>=<value> when calling cmake.

CMake Options¶
Variable	Description	Default Value
`HIGHFM_BLAS`	Specify the BLAS backend used by HighFM. Options: `MKL`, `AOCL`	`MKL`
`HIGHFM_ENABLE_CUDA`	Enable support for NVIDIA CUDA. See CUDA (Experimental) for more details.	`OFF`
`HIGHFM_ENABLE_HDF5`	Enable native support for writing/reading HDF5 files. See HDF5 for more details.	`ON`
`HIGHFM_ENABLE_ARPACK`	Enable the ARPACK package for solving large eigenvalue problems. It requires a FORTRAN compiler and the GNU FORTRAN library (`gfortran`). See arpack for more details.	`ON`
`HIGHFM_ENABLE_COMPLEX`	Enable support for complex numbers.	`ON`
`HIGHFM_ENABLE_PSTL`	Enable support for the Parallel STL. It requires the Intel TBB.	`OFF`
`HIGHFM_USE_32_INDEX`	Use 32-bit indexing instead of 64-bit.	`OFF`
`HIGHFM_DOCS`	Generate the documentation.	`OFF`
`HIGHFM_INSTALL`	Install the library.	`OFF`
`HIGHFM_TEST`	Build the test suite.	`ON`
`HIGHFM_SHARED`	Create a shared library instead of a static one.	`OFF`

Usage¶

First, import the HighFM package and link the library against your executable in the CMakeLists.txt script in your project,

set(HighFM_DIR <install directory>/lib/cmake)
# set(HIGHFM_ENABLE_CUDA ON)    # Enable the CUDA backend (optional)
# set(HIGHFM_ENABLE_ARPACK ON)  # Enable ARPACK (optional)
find_package(HighFM)

# ... #

# <target> is the name of your executable
target_link_libraries(<target> PRIVATE HighFM::HighFM)

# Optionally, link against the additional modules: HighFM::CUDA and/or HighFM::ARPACK
# target_link_libraries(<target> PRIVATE <additional modules>)

Then, in your code, include the highfm/core.hpp header and optionally, any of the following:

#include <highfm/lapack.hpp>            // LAPACK routines (matrix factorization, least-square, etc.)
#include <highfm/random.hpp>            // Random number generation and associated routines
#include <highfm/ode-solvers.hpp>       // Methods for solving ODEs
#include <highfm/funm.hpp>              // Methods for evaluating matrix functions
#include <highfm/linsys/*.hpp>          // Methods for solving linear systems
#include <highfm/extras/*.hpp>          // Other routines (IO with HDF5/MTX, ARPACK, etc.)

Alternatively, you can include only the headers your project needs, e.g., highfm/funm/krylov.hpp for the Restarted Krylov solver.

IMPORTANT: In your main function, add the following lines to initialize and clean the environment used by the library (e.g., internal allocations, hardware context, etc.):

int main(int argc, char* argv[])
{
    HighFM::initialize();
    // ... //
    HighFM::terminate();
    return EXIT_SUCCESS;
}

Documentation¶

To build the documentation, you need the following packages:

And, when building the library, pass -DHIGHFM_DOCS=ON to cmake. The html documentation will be generated and copied to <install directory>/docs.

Testing Suite¶

HighFM uses the Doctest framework for testing. All the necessary files are already included in the repository and do not need to be installed separately.

To built the test suite, pass -DHIGHFM_TEST=ON to cmake. Then, call ./build/tests/validate_highfm to run the test suite. You can control which tests are executed using the command line options specified here. Likewise, The test module for CUDA can be run with ./build/tests/validate_highfm_cuda.