/DLA-Future

Distributed Linear Algebra with Future

Primary LanguageC++BSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

pipeline status codecov

Distributed Linear Algebra with Futures.

Getting started with DLAF

Get DLA-Future

If you have git you can clone this repository with the command

git clone https://github.com/eth-cscs/DLA-Future.git

Otherwise you can download the archive of the latest master branch as a zip or tar.gz archive.

Dependencies

Build using Spack

We provide a spack package dla-future that can be easily added to your own spack as follows:

spack repo add $DLAF_ROOT/spack

This will add a new repository with namespace dlaf.

Example installation:

spack install dla-future ^intel-mkl

Or you can go even further with a more detailed spec like this one, which builds dla-future in debug mode, using the clang compiler, specifying that the pika on which it depends has to be built in debug mode too, and that we want to use MPICH as MPI implementation, without fortran support (because clang does not support it).

spack install dla-future %clang build_type=Debug ^pika build_type=Debug ^mpich ~fortran

Build the old good way

You can build all the dependencies by yourself, but you have to ensure that:

  • BLAS/LAPACK implementation is not multithreaded
  • pika: PIKA_WITH_CUDA=ON (if building for CUDA) + PIKA_WITH_MPI

And here the main CMake options for DLAF build customization:

CMake option Values Note
pika_DIR CMAKE:PATH Location of the pika CMake-config file
blaspp_DIR CMAKE:PATH Location of the blaspp CMake-config file
lapackpp_DIR CMAKE:PATH Location of the lapackpp CMake-config file
DLAF_WITH_MKL {ON,OFF} (default: OFF) if blaspp/lapackpp is built with MKL
MKL_ROOT CMAKE:PATH Location of the MKL library
DLAF_ASSERT_ENABLE {ON,OFF} (default: ON) enable/disable cheap assertions
DLAF_ASSERT_MODERATE_ENABLE {ON,OFF} (default: ON in Debug, OFF otherwise) enable/disable moderate assertions
DLAF_ASSERT_HEAVY_ENABLE {ON,OFF} (default: ON in Debug, OFF otherwise) enable/disable heavy assertions
DLAF_WITH_CUDA {ON,OFF} (default: OFF) enable CUDA support
DLAF_WITH_HIP {ON,OFF} (default: OFF) enable HIP support
DLAF_BUILD_MINIAPPS {ON,OFF} (default: ON) enable/disable building miniapps
DLAF_BUILD_TESTING {ON,OFF} (default: ON) enable/disable building tests
DLAF_INSTALL_TESTS {ON,OFF} (default: OFF) enable/disable installing tests
DLAF_MPI_PRESET {plain-mpi, slurm, custom} (default plain-mpi) presets for MPI configuration for tests. See CMake Doc for additional information
DLAF_TEST_RUNALL_WITH_MPIEXEC {ON, OFF} (default: OFF) Use mpi runner also for non-MPI based tests
DLAF_PIKATEST_EXTRA_ARGS CMAKE:STRING Additional pika command-line options for tests
DLAF_BUILD_DOC {ON,OFF} (default: OFF) enable/disable documentation generation

Link your program/library with DLAF

Using DLAF in a CMake project is extremely easy!

In the following, the variable DLAF_INSTALL_PREFIX is set to where DLAF is installed. In case you used spack for installing DLAF, you can easily set it with:

export DLAF_INSTALL_PREFIX=`spack location -i dla-future`

Then, you can configure your project with one of the following:

# By appending the value to the CMAKE_INSTALL_PREFIX
cmake -DCMAKE_INSTALL_PREFIX=${DLAF_INSTALL_PREFIX} ..

# ... or by setting DLAF_DIR
cmake -DDLAF_DIR="$DLAF_INSTALL_PREFIX/lib/cmake" ..

Then, it is just as simple as adding these directives in your CMakeLists.txt:

find_package(DLAF)
# ... and then for your executable/library target
target_link_libraries(<your_target> PRIVATE DLAF::DLAF)

How to generate the documentation

The documentation can be built together with the project by enabling its generation with the flag DLAF_BUILD_DOC=on and then use the doc target to eventually generate it.

# from the build folder, if you have already configured the CMake project
cmake -DDLAF_BUILD_DOC=on .
make doc

Alternatively, the documentation can be generated independently by using doc/Doxyfile.in, which is a template configuration file in which you have to replace the text ${DLAF_SOURCE_DIR} with the root folder of DLAF containing the source code (e.g. where you cloned this repository).

As a shortcut for this process a doc/Makefile is available, which automatically performs the substitution and then generates the documentation.

cd doc
make doc

Acknowledgements

The development of DLAF library would not be possible without support of the following organizations (in alphabetic order):

CINECA: Cineca Consorzio Interuniversitario
CSCS: Swiss National Supercomputing Centre
ETH Zurich: Swiss Federal Institute of Technology Zurich
PASC: Platform for Advanced Scientific Computing
PRACE: Partnership for Advanced Computing in Europe
As part of IP6 WP8