\( \newcommand{\blu}[1]{{\color{blue}#1}} \newcommand{\red}[1]{{\color{red}#1}} \newcommand{\grn}[1]{{\color{green!50!black}#1}} \newcommand{\local}{_i} \newcommand{\inv}{^{-1}} % Index for interface and interior \newcommand{\G}{\Gamma} \newcommand{\Gi}{\Gamma_i} \newcommand{\I}{{\cal I}} \newcommand{\Ii}{\I_i} % Matrix A \newcommand{\A}{{\cal A}} \newcommand{\Ai}{\A\local} \newcommand{\Aj}{\A_j} \newcommand{\Aib}{\bar{\A}\local} \newcommand{\AII}{\A_{\I\I}} \newcommand{\AIG}{\A_{\I\G}} \newcommand{\AGI}{\A_{\G\I}} \newcommand{\AGG}{\A_{\G\G}} \newcommand{\AIiIi}{\A_{\Ii\Ii}} \newcommand{\AIiGi}{\A_{\Ii\Gi}} \newcommand{\AGiIi}{\A_{\Gi\Ii}} \newcommand{\AGiGi}{\A_{\Gi\Gi}} \newcommand{\AGiGiw} {{\ensuremath{\A_{\Gi\Gi}^w}}} \newcommand{\AIIi}{\AII\local} \newcommand{\AIGi}{\AIG\local} \newcommand{\AGIi}{\AGI\local} \newcommand{\AGGi}{\AGG\local} \newcommand{\Ab}{\bar{\A}} \newcommand{\Ah}{{\widehat{\A}}} \newcommand{\Aih}{{\Ah\local}} \newcommand{\At}{{\widetilde{\A}}} \newcommand{\Ait}{{\At\local}} \newcommand{\Ao}{\A_0} \newcommand{\Aot}{\At_0} \newcommand{\Aob}{\Ab_0} \newcommand{\AiNN}{\Ai^{(NN)}{}} \newcommand{\AitNN}{\Ait^{(NN)}{}} \newcommand{\AiAS}{\Ai^{(AS)}{}} \newcommand{\AitAS}{\Ait^{(AS)}{}} % Matrix S \renewcommand{\S}{{\cal S}} \newcommand{\Si}{\S\local} \newcommand{\Sb}{\bar{\S}} \newcommand{\Sib}{\Sb\local} \newcommand{\Sh}{{\widehat{\S}}} \newcommand{\Sih}{{\Sh\local}} \newcommand{\St}{{\widetilde{\S}}} \newcommand{\Sit}{{\St\local}} \newcommand{\So}{\S_0} \newcommand{\Soi}{\S_0^i} \newcommand{\Sot}{\St_0} \newcommand{\Sob}{\Sb_0} \newcommand{\SiNN}{\Si^{(NN)}{}} \newcommand{\SitNN}{\Sit^{(NN)}{}} \newcommand{\SiAS}{\Si^{(AS)}{}} \newcommand{\SitAS}{\Sit^{(AS)}{}} % Matrix K \newcommand{\K}{{\cal K}} \newcommand{\Ki}{\K\local} \newcommand{\Kb}{\bar{\K}} \newcommand{\Kib}{\Kb\local} \newcommand{\Kh}{{\widehat{\K}}} \newcommand{\Kih}{{\Kh\local}} \newcommand{\Kt}{{\widetilde{\K}}} \newcommand{\Kit}{{\Kt\local}} \newcommand{\Ko}{\K_0} \newcommand{\Kot}{\Kt_0} \newcommand{\Kob}{\Kb_0} \newcommand{\KiNN}{\Ki^{(NN)}{}} \newcommand{\KitNN}{\Kit^{(NN)}{}} \newcommand{\KiAS}{\Ki^{(AS)}{}} \newcommand{\KitAS}{\Kit^{(AS)}{}} \newcommand{\KII}{\K_{\I\I}} \newcommand{\KIG}{\K_{\I\G}} \newcommand{\KGI}{\K_{\G\I}} \newcommand{\KGG}{\K_{\G\G}} \newcommand{\KIiIi}{\K_{\Ii\Ii}} \newcommand{\KIiGi}{\K_{\Ii\Gi}} \newcommand{\KGiIi}{\K_{\Gi\Ii}} \newcommand{\KGiGi}{\K_{\Gi\Gi}} \newcommand{\KIIi}{\KII\local} \newcommand{\KIGi}{\KIG\local} \newcommand{\KGIi}{\KGI\local} \newcommand{\KGGi}{\KGG\local} \newcommand{\KGiGiw} {{\ensuremath{\K_{\Gi\Gi}^w}}} % Matrix B \newcommand{\B}{{\cal B}} \newcommand{\Bi}{\B\local} \newcommand{\Bib}{\widehat{\B}\local} \newcommand{\Bob}{\widehat{\B}_0} % Matrix C \newcommand{\C}{{\cal C}} % Matrix T \newcommand{\T}{{\cal T}} \newcommand{\Ti}{{\T\local}} % Vectors \newcommand{\uI}{u_\I} \newcommand{\uG}{u_\G} \newcommand{\xI}{x_\I} \newcommand{\xG}{x_\G} \newcommand{\bI}{b_\I} \newcommand{\bG}{b_\G} \newcommand{\fI}{f_\I} \newcommand{\fG}{f_\G} \newcommand{\ftG}{\widetilde f_\G} \newcommand{\ftGi}{\widetilde f_\Gi^{(i)}} \newcommand{\ftGj}{\widetilde f_\Gj^{(j)}} \)

Composyx

Table of Contents

See html pages :

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

DAG of composyx image

2. Download

There are several ways to install composyx and its dependencies.

  1. 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.
  2. 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.
  3. 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 and lapackpp 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.3. Additional supported matrices types

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.

https://composyx.gitlabpages.inria.fr/composyx/main/

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

  1. 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 instance openmpi:

    sudo apt-get install -y git openblas openmpi
    

    Then blaspp, lapackpp and arpack-ng can be easily installed from sources (don't forget the ICB flag for arpack-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 ../
    
  2. 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)

6. Tutorial

7. Benchmarks

8. Publications

9. Contact

  • Emmanual Agullo
  • Luc Giraud
  • Gilles Marait

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

13. LICENSE

Date: 27/09/2024 at 12:18:27

Author: Concace

Created: 2024-09-27 Fri 12:18

Validate