diff --git a/CONTRIBUTING.org b/CONTRIBUTING.org index debbd85d269b9d448c381a23fbe96baed711dee8..7dc155606ba2d57aa83933133a4fb1fbc5c5ffc6 100644 --- a/CONTRIBUTING.org +++ b/CONTRIBUTING.org @@ -1,5 +1,11 @@ ** To contribute to the project, you need to do it through merge request +:PROPERTIES: +:CUSTOM_ID: contributing-mr +:END: *** Regular / Inria contributors +:PROPERTIES: +:CUSTOM_ID: contributing-mr-inria +:END: **** Create a fork First you need to fork the repository into your own account. You can do that simply by clicking the fork button on the gitlab interface. @@ -25,7 +31,6 @@ #+end_src **** Create a "Feature" branch in your fork - To add a new feature, fix a bug, and so on, you need to create a new branch from the last state of the master branch #+begin_src sh @@ -74,6 +79,9 @@ Then push the button *merge request*. *** Occasional / external contributors +:PROPERTIES: +:CUSTOM_ID: contributing-mr-external +:END: **** Create a gitlab account Whereas [[https://gitlab.inria.fr/solverstack/chameleon][Chameleon]] is a public project and does not require an authentication to access it, a gitlab account is necessary to @@ -95,6 +103,9 @@ on the branch and eventually perform your merge request. ** Configure a runner to test your branch +:PROPERTIES: +:CUSTOM_ID: contributing-runner +:END: To be effectively merged, your branch must be tested through the [[https://gitlab.inria.fr/help/ci/README.md][gitlab-ci]] mechanism. @@ -118,53 +129,58 @@ newgrp docker #+end_src -**** Register your runner - Please read first the [[https://gitlab.inria.fr/help/ci/runners/README.md][Gitlab documentation]] for general information - about runners registration. - - Three steps are required: - 1) install the gitlab-runner program - 2) register your runner to your project (your fork of Chameleon) - 3) start gitlab-runner as a service - #+begin_src sh - # install gitlab-runner - sudo wget -O /usr/local/bin/gitlab-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-linux-amd64 - sudo chmod +x /usr/local/bin/gitlab-runner - sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash +*** Register your runner + :PROPERTIES: + :CUSTOM_ID: contributing-runner-register + :END: + Please read first the [[https://gitlab.inria.fr/help/ci/runners/README.md][Gitlab documentation]] for general information + about runners registration. + + Three steps are required: + 1) install the gitlab-runner program + 2) register your runner to your project (your fork of Chameleon) + 3) start gitlab-runner as a service + #+begin_src sh + # install gitlab-runner + sudo wget -O /usr/local/bin/gitlab-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-linux-amd64 + sudo chmod +x /usr/local/bin/gitlab-runner + sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash - # register runner to https://gitlab.inria.fr/ - sudo gitlab-runner register # see just after for an example + # register runner to https://gitlab.inria.fr/ + sudo gitlab-runner register # see just after for an example - # install and run as a service - sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner - sudo gitlab-runner start - #+end_src + # install and run as a service + sudo gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner + sudo gitlab-runner start + #+end_src - Example of registering sequence: - #+begin_example - sudo gitlab-runner register - Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/): - https://gitlab.inria.fr/ - Please enter the gitlab-ci token for this runner: - # copy/paste the project's secret token here - Please enter the gitlab-ci description for this runner: - [ubuntu1604]: - Please enter the gitlab-ci tags for this runner (comma separated): - linux, ubuntu - Whether to run untagged builds [true/false]: - [false]: true - Whether to lock Runner to current project [true/false]: - [false]: - Registering runner... succeeded runner=4jknGvoz - Please enter the executor: shell, ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh: - docker - Please enter the default Docker image (e.g. ruby:2.1): - ubuntu - Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded! - #+end_example + Example of registering sequence: + #+begin_example + sudo gitlab-runner register + Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/): + https://gitlab.inria.fr/ + Please enter the gitlab-ci token for this runner: + # copy/paste the project's secret token here + Please enter the gitlab-ci description for this runner: + [ubuntu1604]: + Please enter the gitlab-ci tags for this runner (comma separated): + linux, ubuntu + Whether to run untagged builds [true/false]: + [false]: true + Whether to lock Runner to current project [true/false]: + [false]: + Registering runner... succeeded runner=4jknGvoz + Please enter the executor: shell, ssh, docker+machine, docker-ssh+machine, kubernetes, docker, parallels, virtualbox, docker-ssh: + docker + Please enter the default Docker image (e.g. ruby:2.1): + ubuntu + Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded! + #+end_example ** To review locally a private pull request submitted by someone else - +:PROPERTIES: +:CUSTOM_ID: contributing-localreview +:END: Get the patch from the pull request (Need to update that !!!! Coming from bitbucket) #+begin_src sh diff --git a/doc/user/CMakeLists.txt b/doc/user/CMakeLists.txt index 09c3300030c61f3e4222df73c97feda8c9a26a92..776a06dff2d128e72d164578d55b35fa8eb6eb3a 100644 --- a/doc/user/CMakeLists.txt +++ b/doc/user/CMakeLists.txt @@ -81,6 +81,10 @@ if(EMACS_COMPILER) ${CMAKE_CURRENT_BINARY_DIR}/news.org ${CMAKE_CURRENT_BINARY_DIR}/version.org ${CMAKE_CURRENT_BINARY_DIR}/users_guide.org + ${CMAKE_CURRENT_SOURCE_DIR}/chapters/introduction.org + ${CMAKE_CURRENT_SOURCE_DIR}/chapters/installing.org + ${CMAKE_CURRENT_SOURCE_DIR}/chapters/using.org + ${CMAKE_CURRENT_SOURCE_DIR}/chapters/performances.org ${CMAKE_CURRENT_BINARY_DIR}/CONTRIBUTING.org ${CMAKE_CURRENT_BINARY_DIR}/publish.el ${CMAKE_CURRENT_BINARY_DIR}/chameleon.svg) diff --git a/doc/user/chapters/installing.org b/doc/user/chapters/installing.org index 2a50258bfcc869163d8c0a6b08053212fab9de63..a8ed8454e2314556c1632f0f3cc8cbcfce246d1e 100644 --- a/doc/user/chapters/installing.org +++ b/doc/user/chapters/installing.org @@ -1,7 +1,3 @@ -# This file is part of the Chameleon User's Guide. -# Copyright (C) 2017 Inria -# See the file ../users_guide.org for copying conditions. - Chameleon is written in C and depends on a couple of external libraries that must be installed on the system. # , it provides an interface to be called from Fortran @@ -16,6 +12,9 @@ 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]]. *** Getting Chameleon +:PROPERTIES: +:CUSTOM_ID: doc-install-getting +:END: <<sec:ug:git>> The latest official release tarballs of Chameleon sources are @@ -27,6 +26,9 @@ Finally some packages or also available for [[sec:ug:debian][Debian/Ubuntu]] and #+end_src *** Prerequisites for installing Chameleon +:PROPERTIES: +:CUSTOM_ID: doc-install-prerequisites +:END: <<sec:ug:prereq>> To install Chameleon's libraries, header files, and executables, one @@ -260,6 +262,9 @@ Finally some packages or also available for [[sec:ug:debian][Debian/Ubuntu]] and *Caution about the compatibility:* your compiler must be compatible with CUDA. *** Build and install Chameleon with CMake +:PROPERTIES: +:CUSTOM_ID: doc-install-cmake +:END: <<sec:ug:cmake>> Compilation of Chameleon libraries and executables are done with CMake (http://www.cmake.org/). This version has been tested with @@ -422,6 +427,9 @@ Finally some packages or also available for [[sec:ug:debian][Debian/Ubuntu]] and Note that PaRSEC and StarPU are only detected with pkg-config mechanism because it is always provided and this avoids errors. *** 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 @@ -450,6 +458,9 @@ Finally some packages or also available for [[sec:ug:debian][Debian/Ubuntu]] and 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 +:END: <<sec:ug:guix>> We provide [[http://guix.gnu.org/][Guix]] packages to install Chameleon with its dependencies @@ -608,6 +619,9 @@ Finally some packages or also available for [[sec:ug:debian][Debian/Ubuntu]] and #+end_src *** Distribution of Chameleon using Spack +:PROPERTIES: +:CUSTOM_ID: doc-install-spack +:END: <<sec:ug:spack>> **** Installing Spack @@ -676,12 +690,18 @@ Finally some packages or also available for [[sec:ug:debian][Debian/Ubuntu]] and spack install -v chameleon ^nmad #+end_src *** Distribution Brew for Mac OS X +:PROPERTIES: +:CUSTOM_ID: doc-install-macos +:END: <<sec:ug:brew>> We provide some [[https://brew.sh/][brew]] packages here https://gitlab.inria.fr/solverstack/brew-repo (under construction). *** Linking an external application with Chameleon libraries +:PROPERTIES: +:CUSTOM_ID: doc-install-linking +:END: <<sec:ug:link>> Compilation and link with Chameleon libraries have been tested with the GNU compiler suite ~gcc/gfortran~ and the Intel compiler suite diff --git a/doc/user/chapters/introduction.org b/doc/user/chapters/introduction.org index a1fbc023b9e9b934b45ea5a51a4d19c33cb8ea99..86821edecebffef514ab0b73bab7d8bc6b13cec4 100644 --- a/doc/user/chapters/introduction.org +++ b/doc/user/chapters/introduction.org @@ -2,6 +2,9 @@ # Copyright (C) 2018 Inria # See the file ../users_guide.org for copying conditions. *** MORSE project +:PROPERTIES: +:CUSTOM_ID: doc-intro-morse +:END: #+NAME: fig:chameleon_header #+ATTR_HTML: :align center [[file:chameleon_header.png]] @@ -115,6 +118,9 @@ Research papers about MORSE can be found [[http://icl.cs.utk.edu/projectsdev/morse/pubs/index.html][here]]. *** Chameleon +:PROPERTIES: +:CUSTOM_ID: doc-intro-chameleon +:END: **** Chameleon software The main purpose is to address the performance shortcomings of the [[http://www.netlib.org/lapack/][LAPACK]] and [[http://www.netlib.org/scalapack/][ScaLAPACK]] libraries on multicore processors and diff --git a/doc/user/chapters/performances.org b/doc/user/chapters/performances.org index cbf157482270056b9c66d3cba0ec35dd4475c911..083c89d57e3fa92d6651500f5a51e2b23070c021 100644 --- a/doc/user/chapters/performances.org +++ b/doc/user/chapters/performances.org @@ -22,6 +22,9 @@ mpiexec -np $nmpi $CHAMELEON_BUILD/testing/chameleon_${precision}testing -o ${al - m = n = k - b : depends on the node *** bora (36 CPUs) nodes +:PROPERTIES: +:CUSTOM_ID: doc-perf-bora +:END: - nmpi = *1*, *4*, *9* - 2D block cyclic parameters : PxQ = 1x1, 2x2 and 3x3 - Number of threads (t) = *34*, one CPU being dedicated for the @@ -39,8 +42,10 @@ mpiexec -np $nmpi $CHAMELEON_BUILD/testing/chameleon_${precision}testing -o ${al #+NAME: fig:chameleon_plafrim_bora_perf_openmpi #+ATTR_HTML: :align center :width 75% [[file:chameleon_plafrim_bora_perf_openmpi.png]] - *** sirocco [14-17] (32 CPUs + 2 GPUs V100) nodes +:PROPERTIES: +:CUSTOM_ID: doc-perf-sirocco +:END: - nmpi = *1* - 2D block cyclic parameters : PxQ = 1x1 - Number of threads (t) = *29*, one CPU being dedicated for the diff --git a/doc/user/chapters/using.org b/doc/user/chapters/using.org index f56150aeb1bd687e8ce5bbd4a585025d2e4ba860..1d36408cb79ee661d250818606adb13a043fd4d0 100644 --- a/doc/user/chapters/using.org +++ b/doc/user/chapters/using.org @@ -1,7 +1,7 @@ -# This file is part of the Chameleon User's Guide. -# Copyright (C) 2017 Inria -# See the file ../users_guide.org for copying conditions. *** Using Chameleon executables +:PROPERTIES: +:CUSTOM_ID: doc-using-executables +:END: <<sec:usetesting>> Chameleon provides several test executables that are compiled and @@ -266,8 +266,10 @@ for example: ~STARPU_DISK_SWAP_BACKEND=unistd_o_direct~ * *STARPU_LIMIT_CPU_MEM* environment variable to the amount of memory that can be used in MBytes, for example: ~STARPU_LIMIT_CPU_MEM=1000~ - *** Tutorial LAPACK to Chameleon +:PROPERTIES: +:CUSTOM_ID: doc-using-tuto-lapack-to-chameleon +:END: <<sec:tuto>> Chameleon provides routines to solve dense general systems of @@ -737,6 +739,9 @@ function. *** List of available routines +:PROPERTIES: +:CUSTOM_ID: doc-using-list-routines +:END: **** Linear Algebra routines We list the linear algebra routines of the form diff --git a/doc/user/homepage.org b/doc/user/homepage.org index 4604ba0f1440cdb66cc0772e8d35b749cb44b758..ac5fcc8fb1f73d59549eeff2158e69f29c884842 100644 --- a/doc/user/homepage.org +++ b/doc/user/homepage.org @@ -9,6 +9,9 @@ #+SETUPFILE: https://mfelsoci.gitlabpages.inria.fr/inria-org-html-themes/online-theme-readtheorginria.setup * Overview +:PROPERTIES: +:CUSTOM_ID: overview +:END: <<sec:overview>> Chameleon is a framework written in C which provides routines to @@ -39,10 +42,16 @@ [[./chameleon.svg]] * News +:PROPERTIES: +:CUSTOM_ID: news +:END: <<sec:news>> #+INCLUDE: "news.org" * Download +:PROPERTIES: +:CUSTOM_ID: download +:END: <<sec:download>> Depending on how much you need to tune the library installation we @@ -81,16 +90,28 @@ (Catalina). * Quick start guide +:PROPERTIES: +:CUSTOM_ID: quickstart +:END: <<sec:quickstartguide>> Here a quick starting guide for using Chameleon. For more information please refer to the [[sec:documentation][full documentation]]. ** Install +:PROPERTIES: +:CUSTOM_ID: quickstart-install +:END: In the following we present quick examples of installation of the [[sec:download][packages]]. *** Release source installation with CMake +:PROPERTIES: +:CUSTOM_ID: quickstart-install-cmake +:END: **** Linux Ubuntu 20.04 +:PROPERTIES: +:CUSTOM_ID: quickstart-install-cmake-ubuntu +:END: Start by installing common development tools #+begin_src sh :eval never-export sudo apt-get update -y @@ -127,6 +148,9 @@ See more examples in the [[sec:ug:cmake][user's guide]]. **** macOS +:PROPERTIES: +:CUSTOM_ID: quickstart-install-macos +:END: Start by installing common development tools #+begin_src sh :eval never-export # install Homebrew if not already available @@ -171,6 +195,9 @@ make -j5 install #+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 @@ -182,6 +209,9 @@ distribution please [[sec:contact][contact us]] and we will try to provide one. *** Brew packages +:PROPERTIES: +:CUSTOM_ID: quickstart-install-brew +:END: Brew packages for macOS are stored in our [[https://gitlab.inria.fr/solverstack/brew-repo][brew-repo]] git repository. Please refer to the [[https://gitlab.inria.fr/solverstack/brew-repo/-/blob/master/README.org][README]] for installation instructions. @@ -195,6 +225,9 @@ #+end_src *** Guix packages +:PROPERTIES: +:CUSTOM_ID: quickstart-install-guix +:END: [[https://guix.gnu.org/][Guix]] requires a running GNU/Linux system, GNU tar and Xz. #+begin_src sh :eval never-export gpg --keyserver pgp.mit.edu --recv-keys 3CE464558A84FDC69DB40CFB090B11993D9AEBB5 @@ -232,6 +265,9 @@ See more examples in the [[sec:ug:guix][user's guide]]. *** Spack packages +:PROPERTIES: +:CUSTOM_ID: quickstart-install-spack +:END: Spack packages for Linux or macOS are stored in our [[https://gitlab.inria.fr/solverstack/spack-repo][spack-repo]] git repository. Please refer to the [[https://gitlab.inria.fr/solverstack/spack-repo/-/blob/master/README.org][README]] for installation instructions. @@ -260,6 +296,9 @@ See more examples in the [[sec:ug:spack][user's guide]]. ** Linking +:PROPERTIES: +:CUSTOM_ID: quickstart-linking +:END: If you do not use CMake we provide a pkg-config file at installation in the subdirectory ~lib/pkgconfig~. #+begin_src sh :eval never-export @@ -297,6 +336,9 @@ target_link_libraries(chameleon_example PRIVATE CHAMELEON::chameleon) #+end_src ** Using +:PROPERTIES: +:CUSTOM_ID: quickstart-using +:END: Considering that the ~bin/~ directory of the Chameleon installation is in the ~PATH~, the testing executables can be used to check main linear algebra operations such as 'gemm', 'potrf', 'getrf', @@ -495,9 +537,15 @@ #+end_src * Documentation +:PROPERTIES: +:CUSTOM_ID: doc +:END: <<sec:documentation>> #+INCLUDE: "users_guide.org" * Tutorials +:PROPERTIES: +:CUSTOM_ID: tutorials +:END: <<sec:tutorials>> * [[sec:usetesting][Using Chameleon executables]] @@ -505,6 +553,9 @@ * [[https://fpruvost.gitlabpages.inria.fr/exa2pro/][Exa2pro: Chameleon usage on a supercomputer]] * Contact +:PROPERTIES: +:CUSTOM_ID: contact +:END: <<sec:contact>> If you have an account on [[https://gitlab.inria.fr/][gitlab inria]] please submit a [[https://gitlab.inria.fr/solverstack/chameleon/-/issues][new issue]]. @@ -516,11 +567,16 @@ [[https://sympa.inria.fr/sympa/info/chameleon-announce][chameleon-announce@inria.fr]] (click on "S'abonner" on the left panel). -* Get involved! +* Contributing +:PROPERTIES: +:CUSTOM_ID: contributing +:END: #+INCLUDE: "CONTRIBUTING.org" * Authors - +:PROPERTIES: +:CUSTOM_ID: authors +:END: First, since the Chameleon library started as an extension of the PLASMA library to support multiple runtime systems, all developpers of the PLASMA library are developpers of the Chameleon library. @@ -545,7 +601,9 @@ If we forgot your name, please let us know that we can fix that mistake. * Citing Chameleon - +:PROPERTIES: +:CUSTOM_ID: citing +:END: Feel free to use the following publications to reference Chameleon: * Original paper that initiated Chameleon and the principles: @@ -575,4 +633,7 @@ Feel free to use the following publications to reference Chameleon: [[https://hal.inria.fr/hal-01332774][First Online: 16 June 2016]]. * Licence +:PROPERTIES: +:CUSTOM_ID: licence +:END: [[https://gitlab.inria.fr/solverstack/chameleon/-/blob/master/LICENCE.txt][LICENCE]] diff --git a/doc/user/news.org b/doc/user/news.org index 488f4af81b1ac75014db45fcc45b3e54cbc41e7d..8db19325a5a5778fb76f8cdfa94bb7b5a40f1dab 100644 --- a/doc/user/news.org +++ b/doc/user/news.org @@ -1,6 +1,12 @@ ** [2021-04-21] *Release 1.1.0* available +:PROPERTIES: +:CUSTOM_ID: news-20210421 +:END: * See [[https://gitlab.inria.fr/solverstack/chameleon/-/releases/v1.1.0][changes]] * [[https://gitlab.inria.fr/solverstack/chameleon/uploads/b299d6037d7636c6be16108c89bc2aab/chameleon-1.1.0.tar.gz][Download source tarball]] ** [2021-04-06] Chameleon integration into FMR +:PROPERTIES: +:CUSTOM_ID: news-20210406 +:END: Chameleon has been successfully integrated into the C++ Randomized SVD library [[https://gitlab.inria.fr/compose/oldstack/fmr][FMR]]. diff --git a/doc/user/users_guide.org.in b/doc/user/users_guide.org.in index 106be47a5d30f8b5dbcea05d44ab830de9fa85b9..59436009411cdcf6b6900c54ff9ec64c5a59e702 100644 --- a/doc/user/users_guide.org.in +++ b/doc/user/users_guide.org.in @@ -6,15 +6,23 @@ documentation]]. ** Version +:PROPERTIES: +:CUSTOM_ID: doc-version +:END: This manual documents the usage of Chameleon *version {{{VERSION}}}*. It was last updated on {{{UPDATED}}}. ** Authors +:PROPERTIES: +:CUSTOM_ID: doc-authors +:END: * Inria * University of Tennessee * University of Colorado Denver * King Abdullah University of Science and Technology ** Copying - +:PROPERTIES: +:CUSTOM_ID: doc-copying +:END: * Copyright \copy {{{UPDATED-YEAR}}} Inria * Copyright \copy 2014 The University of Tennessee * Copyright \copy 2014 King Abdullah University of Science and Technology @@ -46,10 +54,19 @@ of this software, even if advised of the possibility of such damage. ** Introduction to Chameleon +:PROPERTIES: +:CUSTOM_ID: doc-intro +:END: #+INCLUDE: @CMAKE_CURRENT_SOURCE_DIR@/chapters/introduction.org ** Installing Chameleon +:PROPERTIES: +:CUSTOM_ID: doc-install +:END: <<sec:ug:install>> #+INCLUDE: @CMAKE_CURRENT_SOURCE_DIR@/chapters/installing.org ** Using Chameleon +:PROPERTIES: +:CUSTOM_ID: doc-using +:END: <<sec:ug:using>> #+INCLUDE: @CMAKE_CURRENT_SOURCE_DIR@/chapters/using.org diff --git a/tools/pages.sh b/tools/pages.sh index e16f6a0f12921c80f8f03a535dc31f65ced3a669..33adaa79cc75deb950a27c27edd08277a2b3fbc4 100755 --- a/tools/pages.sh +++ b/tools/pages.sh @@ -38,6 +38,9 @@ Rscript ${CHAMELEON_SRC_DIR}/tools/bench/jube/GenFigures.R # here by default cat >> ${CHAMELEON_SRC_DIR}/doc/user/users_guide.org.in <<EOF ** Chameleon Performances on PlaFRIM +:PROPERTIES: +:CUSTOM_ID: doc-perf +:END: Chameleon commit: *$commit_sha*. #+INCLUDE: @CMAKE_CURRENT_SOURCE_DIR@/chapters/performances.org EOF