Mentions légales du service

Skip to content
Snippets Groups Projects
Commit d3996959 authored by PRUVOST Florent's avatar PRUVOST Florent
Browse files

Merge branch 'notest-doc' into 'master' 

user doc: updates about v1.3.0, packages, install

See merge request !519
parents a76c320e a9593deb
No related branches found
No related tags found
1 merge request!519user doc: updates about v1.3.0, packages, install
Pipeline #1122279 passed
Stage: docker
    Stage: test
      Hide whitespace changes
      Inline Side-by-side
      doc/user/chapters/installing.org
      + 27
      − 60
      View file @ d3996959
      ......@@ -3,13 +3,14 @@ libraries that must be installed on the system.
      # , it provides an interface to be called from Fortran
      Chameleon can be built and installed on UNIX systems (Linux) by the
      standard means of [[http://www.cmake.org/][CMake]]. General information about CMake, as well as
      installation binaries and CMake source code are available from [[http://www.cmake.org/cmake/resources/software.html][here]].
      standard means of [[http://www.cmake.org/][CMake]].
      General information about CMake, as well as installation binaries and CMake
      source code are available from
      [[http://www.cmake.org/cmake/resources/software.html][here]].
      To get support to install a full distribution Chameleon + dependencies
      we encourage users to use [[sec:ug:guix][GNU Guix]] or [[sec:ug:spack][Spack]].
      Finally some packages or also available for [[sec:ug:debian][Debian/Ubuntu]] and [[sec:ug:brew][MacOSX]].
      we encourage users to use [[sec:ug:guix][GNU Guix]] or [[sec:ug:spack][Spack]]
      and [[sec:ug:brew][Brew]] on macOS.
      *** Getting Chameleon
      :PROPERTIES:
      ......@@ -90,9 +91,9 @@ Finally some packages or also available for [[sec:ug:debian][Debian/Ubuntu]] and
      # Install StarPU (with MPI and FxT enabled)
      mkdir -p $HOME/install
      cd $HOME/install
      wget https://files.inria.fr/starpu/starpu-1.3.10/starpu-1.3.10.tar.gz
      tar xvzf starpu-1.3.10.tar.gz
      cd starpu-1.3.10/
      wget https://files.inria.fr/starpu/starpu-1.4.7/starpu-1.4.7.tar.gz
      tar xvf starpu-1.4.7.tar.gz
      cd starpu-1.4.7
      ./configure --prefix=/usr/local --with-fxt=/usr/lib/x86_64-linux-gnu/
      make -j5
      sudo make install
      ......@@ -203,8 +204,8 @@ Finally some packages or also available for [[sec:ug:debian][Debian/Ubuntu]] and
      StarPU can be used to benefit from GPUs and distributed-memory
      environment. Note StarPU is enabled by default.
      *Caution about the compatibility:* Chameleon has been mainly tested
      with StarPU-1.1, 1.2 and 1.3 releases.
      *Caution about the compatibility:* current Chameleon has been mainly tested
      with StarPU-1.4 releases.
      ***** PaRSEC
      [[http://icl.utk.edu/parsec/][PaRSEC]] is a generic framework for architecture aware scheduling
      and management of micro-tasks on distributed many-core
      ......@@ -462,40 +463,6 @@ Finally some packages or also available for [[sec:ug:debian][Debian/Ubuntu]] and
      The [[https://cmake.org/cmake/help/latest/variable/CMAKE_PREFIX_PATH.html#variable:CMAKE_PREFIX_PATH][CMAKE_PREFIX_PATH]]
      can be used to indicate where dependencies are installed.
      *** Distribution Debian
      :PROPERTIES:
      :CUSTOM_ID: doc-install-debian
      :END:
      <<sec:ug:debian>>
      Download one of the available package for your distribution here
      https://gitlab.inria.fr/solverstack/chameleon/-/packages, then
      install as follows
      #+begin_src sh
      sudo apt-get install ./chameleon_1.2.0-1_amd64.deb -y
      // and to uninstall use
      // sudo apt-get autoremove -y chameleon
      #+end_src
      Chameleon will be installed on your system meaning you can use
      drivers for performance tests
      #+begin_src sh
      export OPENBLAS_NUM_THREADS=1
      mpiexec -n 2 chameleon_stesting -o gemm -n 6400
      #+end_src
      and use Chameleon library in your own project
      #+begin_src sh
      # example usage: use chameleon library in your own cmake project (we provide a CHAMELEONConfig.cmake)
      git clone https://gitlab.inria.fr/solverstack/distrib.git
      cd distrib/cmake/test/chameleon && mkdir build && cd build && cmake .. && make && ./test_chameleon
      # example usage: use chameleon library in your own not cmake project
      # use pkg-config to get compiler flags and linking
      pkg-config --cflags chameleon
      pkg-config --libs chameleon
      # if there are static libraries use the --static option of pkg-config
      #+end_src
      Do not hesitate to send an [[mailto:florent.pruvost@inria.fr][email]] if you need a package for your
      Debian distribution.
      *** Distribution of Chameleon using GNU Guix
      :PROPERTIES:
      :CUSTOM_ID: doc-install-guix
      ......@@ -503,7 +470,7 @@ Finally some packages or also available for [[sec:ug:debian][Debian/Ubuntu]] and
      <<sec:ug:guix>>
      We provide [[http://guix.gnu.org/][Guix]] packages to install Chameleon with its dependencies
      in a reproducible way on GNU/Linux systems. For MacOSX please refer
      in a reproducible way on GNU/Linux systems. For macOS please refer
      to the next sections about Brew or Spack packaging.
      If you are "root" on the system you can install Guix and directly
      ......@@ -523,11 +490,6 @@ Finally some packages or also available for [[sec:ug:debian][Debian/Ubuntu]] and
      sudo ./guix-install.sh
      #+end_src
      or on Debian
      #+begin_src sh :eval never-export
      sudo apt install guix
      #+end_src
      The Chameleon packages are not official Guix packages. It is then
      necessary to add a channel to get additional packages. Create a
      ~/.config/guix/channels.scm file with the following snippet:
      ......@@ -574,12 +536,18 @@ Finally some packages or also available for [[sec:ug:debian][Debian/Ubuntu]] and
      Notice that there exist several build variants
      - chameleon (default) : with starpu - with mpi - with OpenBlas
      - chameleon-aocl : with starpu - with mpi - with FLAME/BLIS from AMD
      - chameleon-mkl : default version but with Intel MKL sequential to replace OpenBlas
      - chameleon-mkl-mt : default version but with Intel MKL multithreaded to replace OpenBlas
      - chameleon-mkl-mt-wompi : with Intel MKL multithreaded and without mpi
      - chameleon-cuda : with starpu - with mpi - with cuda
      - chameleon-cuda-wompi : with starpu - without mpi - with cuda
      - chameleon-cuda-mkl-mt : with starpu - with mpi - with cuda - with Intel MKL multithreaded to replace OpenBlas
      - chameleon-cuda-mkl-mt-wompi : with starpu - without mpi - with cuda - with Intel MKL multithreaded to replace OpenBlas
      - chameleon-mkl-mt-nompi : with Intel MKL multithreaded and without mpi
      - chameleon-cuda : with starpu - with cuda - with OpenBlas - with mpi
      - chameleon-cuda-nompi : with starpu - with cuda - with OpenBlas - without mpi
      - chameleon-cuda-mkl-mt : with starpu - with cuda - with Intel MKL multithreaded - with mpi
      - chameleon-cuda-mkl-mt-nompi : with starpu - with cuda - with Intel MKL multithreaded - without mpi
      - chameleon-hip : with starpu - with hip - with OpenBlas - with mpi
      - chameleon-hip-nompi : with starpu - with hip - with OpenBlas - without mpi
      - chameleon-hip-mkl-mt : with starpu - with hip - with Intel MKL multithreaded - with mpi
      - chameleon-hip-mkl-mt-nompi : with starpu - with hip - with Intel MKL multithreaded - without mpi
      - chameleon-simgrid : with starpu - with mpi - with simgrid
      - chameleon-openmp : with openmp - without mpi
      - chameleon-parsec : with parsec - without mpi
      ......@@ -599,7 +567,7 @@ Finally some packages or also available for [[sec:ug:debian][Debian/Ubuntu]] and
      Change some dependencies
      #+begin_src sh
      # install chameleon with intel mkl to replace openblas, nmad to replace openmpi and starpu with fxt
      guix install chameleon --with-input=openblas=mkl --with-input=openmpi=nmad --with-input=starpu=starpu-fxt
      guix install chameleon --with-input=openblas=intel-oneapi-mkl --with-input=openmpi=nmad --with-input=starpu=starpu-fxt
      #+end_src
      **** Generate a Chameleon Docker image with Guix
      ......@@ -607,7 +575,7 @@ Finally some packages or also available for [[sec:ug:debian][Debian/Ubuntu]] and
      To install Chameleon and its dependencies within a docker image
      (OpenMPI stack)
      #+begin_src sh
      docker_chameleon=`guix pack -f docker chameleon chameleon --with-branch=chameleon=master --with-input=openblas=mkl mkl starpu hwloc openmpi openssh slurm bash coreutils inetutils util-linux procps git grep tar sed gzip which gawk perl emacs-minimal vim gcc-toolchain make cmake pkg-config -S /bin=bin --entry-point=/bin/bash`
      docker_chameleon=`guix pack -f docker chameleon chameleon --with-branch=chameleon=master --with-input=openblas=intel-oneapi-mkl intel-oneapi-mkl starpu hwloc openmpi@4 openssh slurm bash coreutils inetutils util-linux procps git grep tar sed gzip which gawk perl emacs-minimal vim gcc-toolchain pkg-config -S /bin=bin --entry-point=/bin/bash`
      # Load the generated tarball as a docker image
      docker_chameleon_tag=`docker load --input $docker_chameleon | grep "Loaded image: " | cut -d " " -f 3-`
      # Change tag name, see the existing image name with "docker images" command, then change to a more simple name
      ......@@ -656,7 +624,7 @@ Finally some packages or also available for [[sec:ug:debian][Debian/Ubuntu]] and
      #+begin_src sh
      # define reproducible guix environment
      guix describe -f channels > guix-channels.scm
      guix shell --export-manifest chameleon-cuda --with-branch=chameleon=master --with-input=openblas=mkl bash coreutils emacs gawk grep inetutils openmpi openssh procps sed time util-linux vim which > guix-manifests.scm
      guix shell --export-manifest chameleon-cuda --with-branch=chameleon=master --with-input=openblas=intel-oneapi-mkl bash coreutils emacs gawk grep inetutils openmpi@4 openssh procps sed time util-linux vim which > guix-manifests.scm
      SINGULARITY_IMAGE=`guix time-machine -C guix-channels.scm -- pack -f squashfs -m guix-manifests.scm -S /bin=bin --entry-point=/bin/bash`
      cp $SINGULARITY_IMAGE chameleon-cuda.gz.sif
      ......@@ -682,7 +650,7 @@ Finally some packages or also available for [[sec:ug:debian][Debian/Ubuntu]] and
      One can generate a tar.gz archive the same way as the singularity image
      #+begin_src sh
      guix describe -f channels > guix-channels.scm
      guix shell --export-manifest chameleon-cuda --with-branch=chameleon=master --with-input=openblas=mkl bash coreutils emacs gawk grep inetutils openmpi openssh procps sed time util-linux vim which > guix-manifests.scm
      guix shell --export-manifest chameleon-cuda --with-branch=chameleon=master --with-input=openblas=intel-oneapi-mkl bash coreutils emacs gawk grep inetutils openmpi openssh procps sed time util-linux vim which > guix-manifests.scm
      PACKRR=`guix time-machine --channels=guix-channels.scm -- pack -RR --manifest=guix-manifests.scm -S /bin=bin`
      cp $PACKRR chameleon-cuda.tar.gz
      # copy the archive on the supercomputer, e.g. 'supercomputer'
      ......@@ -716,7 +684,6 @@ Finally some packages or also available for [[sec:ug:debian][Debian/Ubuntu]] and
      git clone https://github.com/spack/spack.git
      . spack/share/spack/setup-env.sh
      cd spack
      git checkout v0.19.1
      #+end_src
      Chameleon is then available
      ......
      doc/user/homepage.org
      + 35
      − 64
      View file @ d3996959
      ......@@ -58,35 +58,34 @@
      propose several solutions.
      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 recommand
      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.
      the examples, or simply use the last stable version: we recommend
      to use one of our packages, Guix or Spack on 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. [[sec:quickstartguide]].
      with CMake following the procedures described in the installation guide of
      the library, cf. [[sec:quickstartguide]].
      3) You need a tool for reproducibility of your experiments: Guix is
      recommended.
      #+ATTR_HTML: :alt Table of download materials image :title Table of download materials :align center
      | Git | Release source | Debian/Ubuntu | [[https://brew.sh/][Brew]] (Mac) | [[https://guix.gnu.org/en/][Guix]] (Linux) | [[https://spack.readthedocs.io/en/latest/][Spack]] (Linux/Mac) |
      | Git | Release source | [[https://brew.sh/][Brew]] (Mac) | [[https://guix.gnu.org/en/][Guix]] (Linux) | [[https://spack.readthedocs.io/en/latest/][Spack]] (Linux/Mac) |
      |-----------+----------------+---------------+------------+--------------+-------------------|
      | [[https://gitlab.inria.fr/solverstack/chameleon][Chameleon]] | [[https://gitlab.inria.fr/api/v4/projects/616/packages/generic/source/v1.2.0/chameleon-1.2.0.tar.gz][1.2.0]] | [[https://gitlab.inria.fr/solverstack/chameleon/-/packages][packages]] | [[https://gitlab.inria.fr/solverstack/brew-repo][brew-repo]] | [[https://gitlab.inria.fr/guix-hpc/guix-hpc-non-free][guix-repo]] | [[https://github.com/spack/spack][spack-repo]] |
      | [[https://gitlab.inria.fr/solverstack/chameleon][Chameleon]] | [[https://gitlab.inria.fr/api/v4/projects/616/packages/generic/source/v1.3.0/chameleon-1.3.0.tar.gz][v1.3.0]] | [[https://gitlab.inria.fr/solverstack/brew-repo][brew-repo]] | [[https://gitlab.inria.fr/guix-hpc/guix-hpc-non-free][guix-repo]] | [[https://github.com/spack/spack][spack-repo]] |
      Some packages are part of the official distribution and we just
      provide the package name. For others we provide links where you can
      find either a file to install or a package recipe that can be used
      with Brew, Guix, Spack. If there are no package available for your
      distribution please [[sec:contact][contact us]] and we will try to find a solution.
      distribution please [[sec:contact][contact us]] and we will try to find a
      solution.
      All these packages have been successfully installed and tested on
      Unix systems: *Linux* (Debian testing, Ubuntu 22.04 LTS) and *macOS*
      Unix systems: *Linux* (Debian testing, Ubuntu 22.04 and 24.04 LTS) and *macOS*
      (Catalina).
      * Quick start guide
      ......@@ -108,7 +107,7 @@
      :PROPERTIES:
      :CUSTOM_ID: quickstart-install-cmake
      :END:
      **** Linux Ubuntu 22.04
      **** Linux Ubuntu
      :PROPERTIES:
      :CUSTOM_ID: quickstart-install-cmake-ubuntu
      :END:
      ......@@ -135,14 +134,14 @@
      Then to install Chameleon from sources with CMake, proceed as follows
      #+begin_src sh :eval never-export
      wget https://gitlab.inria.fr/api/v4/projects/616/packages/generic/source/v1.2.0/chameleon-1.2.0.tar.gz
      tar xvf chameleon-1.2.0.tar.gz
      cd chameleon-1.2.0
      wget https://gitlab.inria.fr/api/v4/projects/616/packages/generic/source/v1.3.0/chameleon-1.3.0.tar.gz
      tar xvf chameleon-1.3.0.tar.gz
      cd chameleon-1.3.0
      # or clone the master branch from the git repository to get the last version
      # git clone --recursive https://gitlab.inria.fr/solverstack/chameleon.git && cd chameleon
      mkdir build && cd build
      cmake .. -DCHAMELEON_USE_MPI=ON -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=$PWD/install
      make -j5 install
      cmake -B build -DCHAMELEON_USE_MPI=ON -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=$PWD/install
      cmake --build build/ -j5
      cmake --install build/
      #+end_src
      See more examples in the [[sec:ug:cmake][user's guide]].
      ......@@ -157,9 +156,9 @@
      /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
      # install compiler and tools
      brew install htop tmux gcc automake autoconf libtool doxygen emacs zlib bzip2 bison hwloc pkgconfig openblas openmpi
      brew install htop tmux gcc llvm automake autoconf libtool doxygen emacs zlib bzip2 bison hwloc pkgconfig openblas openmpi
      # gcc and g++ are missing (avoid to use clang version in /usr/bin)
      # gcc and g++ are missing (avoid to use clang version in /usr/bin or use the clang from brew, see package llvm, e.g. clang-17)
      ln -sf /usr/local/bin/gcc-11 /usr/local/bin/gcc
      ln -sf /usr/local/bin/g++-11 /usr/local/bin/g++
      ......@@ -169,15 +168,14 @@
      # cmake checks blas.pc not openblas.pc
      sudo cp /usr/local/opt/openblas/lib/pkgconfig/openblas.pc /usr/local/opt/openblas/lib/pkgconfig/blas.pc
      #+end_src
      - CBLAS/LAPACKE is required (OpenBLAS or Intel MKL)
      - we recommend to install StarPU as runtime system with MPI
      enabled
      - CBLAS/LAPACKE is required (OpenBLAS or Intel MKL or Reference Lapack)
      - we recommend to install StarPU as runtime system with MPI enabled
      #+begin_src sh :eval never-export
      # install last starpu release
      cd $HOME
      wget https://files.inria.fr/starpu/starpu-1.3.10/starpu-1.3.10.tar.gz
      tar xvf starpu-1.3.10.tar.gz
      cd starpu-1.3.10
      wget https://files.inria.fr/starpu/starpu-1.4.7/starpu-1.4.7.tar.gz
      tar xvf starpu-1.4.7.tar.gz
      cd starpu-1.4.7
      ./configure
      make -j5
      sudo make install
      ......@@ -185,31 +183,15 @@
      Then to install Chameleon from sources with CMake, proceed as follows
      #+begin_src sh :eval never-export
      wget https://gitlab.inria.fr/api/v4/projects/616/packages/generic/source/v1.2.0/chameleon-1.2.0.tar.gz
      tar xvf chameleon-1.2.0.tar.gz
      cd chameleon-1.2.0
      wget https://gitlab.inria.fr/api/v4/projects/616/packages/generic/source/v1.3.0/chameleon-1.3.0.tar.gz
      tar xvf chameleon-1.3.0.tar.gz
      cd chameleon-1.3.0
      # or clone from git repository
      # git clone --recursive https://gitlab.inria.fr/solverstack/chameleon.git && cd chameleon
      mkdir build && cd build
      cmake .. -DCHAMELEON_USE_MPI=ON -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=$PWD/install
      make -j5 install
      cmake -B build -DCHAMELEON_USE_MPI=ON -DBLA_PREFER_PKGCONFIG=ON -DBUILD_SHARED_LIBS=ON
      cmake --build build -j5
      sudo cmake --install build
      #+end_src
      *** Debian/Ubuntu packages
      :PROPERTIES:
      :CUSTOM_ID: quickstart-install-debian-ubuntu
      :END:
      Visit the [[https://gitlab.inria.fr/solverstack/chameleon/-/packages][packages]] page and download the appropriate file for your
      system. Then in a shell terminal
      #+begin_src sh :eval never-export
      # to install one of our non offical package, for example on Ubuntu 22.04
      wget https://gitlab.inria.fr/api/v4/projects/616/packages/generic/ubuntu_22.04/1.2.0/chameleon_1.2.0-1_amd64.deb
      sudo apt-get install -y ./chameleon_1.2.0-1_amd64.deb
      // and to uninstall use
      // sudo apt-get autoremove -y chameleon
      mpiexec -n 2 chameleon_dtesting -o potrf -t 2 -n 3200 --nowarmup
      #+end_src
      If there are no package available for your Debian/Ubuntu
      distribution please [[sec:contact][contact us]] and we will try to provide one.
      *** Brew packages
      :PROPERTIES:
      ......@@ -240,11 +222,6 @@
      sudo ./guix-install.sh
      #+end_src
      or on Debian
      #+begin_src sh :eval never-export
      sudo apt install guix
      #+end_src
      Guix packages are stored in our [[https://gitlab.inria.fr/guix-hpc/guix-hpc][guix-hpc]], and [[https://gitlab.inria.fr/guix-hpc/guix-hpc-non-free][guix-hpc-non-free]]
      (for versions with Intel MKL and/or CUDA) git repositories. Please
      refer to the README to see how to add our package to the list of
      ......@@ -283,10 +260,8 @@
      Examples:
      #+begin_src sh :eval never-export
      # please read https://spack.readthedocs.io/en/latest/getting_started.html
      git clone https://github.com/spack/spack.git
      git clone -c feature.manyFiles=true --depth=2 https://github.com/spack/spack.git
      . spack/share/spack/setup-env.sh
      cd spack
      git checkout v0.19.1
      spack install chameleon
      # chameleon is installed here:
      spack location -i chameleon
      ......@@ -318,18 +293,14 @@
      the ~CMAKE_PREFIX_PATH~
      (https://cmake.org/cmake/help/latest/envvar/CMAKE_PREFIX_PATH.html)
      as environment variable or CMake variable to give the root
      installation directory where Chameleon is installed or use the
      ~CHAMELEON_ROOT~ environment variable. Example of ~CMakeLists.txt~ for
      Chameleon
      installation directory where Chameleon is installed.
      Example of ~CMakeLists.txt~ for project using Chameleon
      #+begin_src :eval never-export
      project(CHAMELEON_EXAMPLE C Fortran)
      # to be able to use CHAMELEON_ROOT env. var.
      cmake_policy(SET CMP0074 NEW)
      # look for CHAMELEON on the system
      # Hint: use CHAMELEON_ROOT (env. var. or cmake var.) to the installation directory of
      # CHAMELEON if not installed in a standard path
      # Hint if not installed in a standard system directory:
      # add chameleon installation directory in the CMAKE_PREFIX_PATH (env. var. or cmake var.)
      find_package(CHAMELEON REQUIRED)
      ......
      doc/user/news.org
      + 1
      − 0
      View file @ d3996959
      + [2025-02-19] *Release 1.3.0* available, see [[https://gitlab.inria.fr/solverstack/chameleon/-/releases/v1.3.0][changes]], [[https://gitlab.inria.fr/api/v4/projects/616/packages/generic/source/v1.3.0/chameleon-1.3.0.tar.gz][download source tarball]].
      + [2023-07-04] *Release 1.2.0* available, see [[https://gitlab.inria.fr/solverstack/chameleon/-/releases/v1.2.0][changes]], [[https://gitlab.inria.fr/api/v4/projects/616/packages/generic/source/v1.2.0/chameleon-1.2.0.tar.gz][download source tarball]].
      + [2023-02-08] *Added support for HIP and hipblas (CUDA and ROC backend)*, see [[https://gitlab.inria.fr/solverstack/chameleon/-/merge_requests/355][MR 355]].
      + [2023-01-18] *Add parallel kernels support*, see [[https://gitlab.inria.fr/solverstack/chameleon/-/merge_requests/206][MR 206]].
      ......
      0% or .
      You are about to add 0 people to the discussion. Proceed with caution.
      Finish editing this message first!
      Please register or to comment