Composyx
Table of Contents
See html pages :
- html version
- literate programming documentation
- development branches (private access for developers)
1. Overview
Composyx
(previsouly Compose
, or Maphys++
) is a linear
algebra C++ library focused on composability. Its purpose is to
allow the user to express a large pannel of algorithms using a
high-level interface to range from laptop prototypes to many node
supercomputer parallel computations.
1.1. Main features
- Written in C++, C and Fortran interfaces, CMake build system
- Distributed MPI, hybrid MPI/threads parallelization(threads parallelism is disabled through CMake compilation option by default)
- Can use Blas/Lapack and Chameleon (matrix products, SPD linear systems, QR/LQ) for dense matrix operations
- Can use MUMPS, PaStiX or
qr_mumps
as direct sparse solver - Can use fabulous as Krylov solver with multiple RHS
- Can use arpack for some preconditioning techniques
- Matrices formats: general, symmetric, hermitian
- Sparse storage formats: IJV, CSC, eigen3
- Precisions: single, double, complex, double complex
2. Download
There are several ways to install composyx
and its dependencies.
- You just want to have a try, to see if it can be installed well on your system, what are the performances on simple cases, run the examples, or simply use the last stable version: we recommend to use one of our packages, .deb ones for those who work on a Linux Debian or Ubuntu distribution, Guix or Spack on other Linux systems, Brew on macOS.
- You want to use it but you need a change somewhere in the stack like considering another version (git branch), change the default BLAS/LAPACK or MPI, use your favorite compiler, modify some sources: you may try with Guix or Spack because these package managers allow to build from sources and thus many options can be changed dynamically (command line), or directly build from source with the native build system of the library (Makefile, GNU autotools, CMake) following the procedures described in the installation guide of the library, cf. 5.
- You need a tool for reproducibility of your experiments: Guix is recommended.
Git | Release source | Debian/Ubuntu | Brew (Mac) | Guix (Linux) | Spack (Linux/Mac) | |
---|---|---|---|---|---|---|
composyx | releases | * | brew-repo | guix-repo | spack |
- We cannot provide a simple debian package because some of
composyx
dependencies do not provide one (blaspp
andlapackpp
especially). However those are modern packages that can easily be installed, so you should be able to install them manually with instructions given in this section.
3. Dependencies
3.1. Required dependencies
3.1.1. General
- A modern C++ compiler
- GCC (version >= 11)
- Clang (version >= 16)
- Most tested versions: gcc-11.3, gcc-12.4, gcc-13.3, clang-16.0.6, clang-17.0.6, clang-18.1.8
- CMake (version >= 3.12)
- MPI
3.1.2. Blas/lapack
One of
- SLATE blaspp and SLATE lapackpp, respectively C++ blas and lapack interfaces (recommended).
- <T>LAPACK a blas/lapack C++ header-only implementation, can replace
a few blaspp/lapackpp functionalities for prototyping, but does
not guarantee performance. The
<T>LAPACK
repository is a git submodule of this one.
3.2. Optional dependencies
- Arpack-ng (version >= 3.8), necessary for GenEO on sparse matrix, must be compiled with C/C++ interface: ICB flag ON in CMake
- Chameleon (compiled without MPI, version >= 1.2.0) dense matrix solver
- Fabulous (version >= 1.1.3) Iterative Block Krylov solvers
- Librsb (version >= 1.3), for optimized sparse matrix computation kernels
- Mumps sparse direct solver
- PaStiX (version >= 6.3, compiled with MPI) sparse direct solver (requires SCOTCH >= 7.0.4)
Paddle (version >= 0.3.5), necessary to work on a centralized input matrix (requires SCOTCH >= 7.0.4)
Having at least one direct solver (Mumps and/or PaStiX) is strongly recommended.
3.4. Dependencies for experimental features
- SZ compressor (for GMRES with compressed basis feature)
- ZFP compressor (for GMRES with compressed basis feature)
- QRMUMPS (can be used as direct solver for SPD matrices)
4. Documentation
4.1. Literate programming documentation
For advanced users, developers, or people interested in contributing to the code, composyx is fully coded in literate programming using emacs's org-mode.
4.2. User documentation
No user documentation has been written yet, please refer to the tutorial or the quick start guide.
5. Quick start guide
5.1. Install
5.1.1. Manual installation on linux
- Dependencies
sudo apt-get update -y sudo apt-get install -y git cmake build-essential gfortran python wget tar curl pkg-config
For performance, you may also want to install a blas implementation, for instance
openblas
, and an MPI implementation, for instanceopenmpi
:sudo apt-get install -y git openblas openmpi
Then
blaspp
,lapackpp
andarpack-ng
can be easily installed from sources (don't forget theICB
flag forarpack-ng
to activate the C++ interface):# install blaspp, lapackpp and arpack-ng git clone https://github.com/icl-utk-edu/blaspp.git git clone https://github.com/icl-utk-edu/lapackpp.git git clone https://github.com/opencollab/arpack-ng.git cd blaspp cmake -B build -DCMAKE_INSTALL_PREFIX=/usr/local cmake --build build -j5 sudo cmake --install build cd ../ cd lapackpp cmake -B build -DCMAKE_INSTALL_PREFIX=/usr/local cmake --build build -j5 sudo cmake --install build cd ../ cd arpack-ng cmake -B build -DICB=ON cmake --build build -j5 sudo cmake --install build cd ../
Install Starpu (can be used by Chameleon, PaStiX, qrmumps):
git clone https://gitlab.inria.fr/starpu/starpu.git cd starpu ./configure --prefix=/usr/local --disable-build-doc --disable-build-test --disable-opencl --disable-fortran --disable-socl --disable-starpufft make -j5 sudo make install cd ../
Install Pastix:
git clone --recursive https://gitlab.inria.fr/solverstack/pastix.git cd pastix cmake -B build -DCMAKE_INSTALL_PREFIX=/usr/local -DBUILD_SHARED_LIBS=ON -DPASTIX_INT64=OFF -DPASTIX_WITH_MPI=ON # version with int64 can be enabled if scotch/metis are configured with int64 # version with starpu can be enabled with: -DPASTIX_WITH_STARPU=ON # if scotch and/or starpu are installed in specific paths add the following to the configuration: -DCMAKE_PREFIX_PATH="path to scotch;path to starpu" cmake --build build -j5 sudo cmake --install build cd ../
Install Chameleon:
git clone --recursive https://gitlab.inria.fr/solverstack/chameleon.git cd chameleon cmake -B build -DCHAMELEON_USE_MPI=OFF -DCMAKE_INSTALL_PREFIX=/usr/local -DBUILD_SHARED_LIBS=ON # if starpu is installed in a specific path add the following to the configuration: -DCMAKE_PREFIX_PATH="path to starpu" cmake --build build -j5 sudo cmake --install build cd ../
- composyx
Get
composyx
's sources (don't forget to get the git submodules !)# if git version >= 1.9 git clone --recursive https://gitlab.inria.fr/composyx/composyx.git cd composyx # else git clone https://gitlab.inria.fr/composyx/composyx.git cd composyx git submodule init git submodule update
Then
composyx
uses standard CMake installation. From the sources root directory:cmake -D build -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=/path/to/install # and other cmake flags needed cmake --build build -j5 [sudo] cmake --install build
Check
CMakeLists.txt
to see which CMake flags you want to use for your installation.
5.1.2. With guix
We use guix for reproducible research purposes. Here is the current configuration used for composyx.
composyx is distributed through guix in the guix-hpc repository.
The channel configuration (usually in ~/.config/guix/channels.scm
if not
configured differently):
(cons (channel
(name 'guix-hpc-non-free)
(url "https://gitlab.inria.fr/guix-hpc/guix-hpc-non-free.git"))
%default-channels)
To launch a bash with composyx installed:
guix shell --pure composyx -- /bin/bash --norc
For developers, to get an environment with all required tools and dependencies to build composyx with CMake, add some debugging packages and emacs to tangle and export from the org sources, to the following:
guix shell --pure -D composyx emacs emacs-org gdb valgrind -- /bin/bash --norc
To run tests, you might need to set the openmpi variable as follows (to allow more processes to run than you have physical CPU cores on your computer):
export OMPI_MCA_rmaps_base_oversubscribe=1
5.1.3. With spack
Install Spack : please read https://spack.readthedocs.io/en/latest/
git clone -c feature.manyFiles=true https://github.com/spack/spack.git . spack/share/spack/setup-env.sh # tips: source this script in your .bashrc to get the spack command in new terminals
Install composyx
spack install composyx # composyx is installed here: CPX_DIR=`spack location -i composyx` # Update installation paths (PATH, LD_LIBRARY_PATH, CPATH, CMAKE_PREFIX_PATH, PKG_CONFIG_PATH, ...) spack load composyx mpiexec -n 8 --oversubscribe composyx_driver_cg -P $CPX_DIR/matrices/partitioned/ -N 8 -p AS
Spack allows to expose many build variants so that it is difficult to ensure that all installations will succeed.
5.1.4. With brew (MacOS)
Brew packages for macOS are stored in our brew-repo git repository. Please refer to the README for installation instructions. Examples:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" git clone https://gitlab.inria.fr/solverstack/brew-repo.git cd brew-repo brew install -v --cc=clang --build-from-source blaspp.rb brew install -v --cc=clang --build-from-source lapackpp.rb brew install -v --cc=clang --build-from-source arpackng.rb brew install -v --cc=clang --build-from-source fabulous.rb brew install -v --cc=clang --build-from-source pastix.rb brew install llvm brew install -v --cc=llvm_clang --build-from-source composyx.rb
To ensure you use a recent Clang compiler install `llvm` with brew then
add the option --cc=llvm_clang
to the brew install command when
installing composyx.
5.2. Linking
If you build your project with CMake we provide a composyxConfig.cmake
file at installation, in the subdirectory lib/cmake/composyx/
of the
installation. Example of CMakeLists.txt
for composyx
, where your code is
in composyx_example.cpp
:
cmake_minimum_required(VERSION 3.12) project(COMPOSYX_EXAMPLE CXX C Fortran) find_package(composyx REQUIRED) # compile your example add_executable(composyx_example composyx_example.cpp) # link to composyx target_link_libraries(composyx_example PRIVATE COMPOSYX::composyx)
10. Authors
- Emmanual Agullo
- Gilles Marait
- Florent Pruvost
- Matthieu Simonin
- Yuxuan Wang
11. Acknowledgment
This software effort has been partially funded by Inria ADT and the EoCoE-2 european project.
Software development was performed using the PlaFRIM experimental testbed, supported by Inria, CNRS (LABRI and IMB), Université de Bordeaux, Bordeaux INP and Conseil Régional d’Aquitaine (see https://www.plafrim.fr).
12. See also
- Original MaPHyS fortran repository
- Louis Poirel's PhD thesis : Algebraic domain decomposition methods for hybrid (iterative/direct) solvers