From c51877150ad3567b561d45c5769332690b85edf0 Mon Sep 17 00:00:00 2001 From: Joe Schoonover Date: Fri, 17 Jan 2025 07:17:10 -0500 Subject: [PATCH 1/3] Add statements on using `WORKSPACE` env variable --- docs/GettingStarted/install.md | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/GettingStarted/install.md b/docs/GettingStarted/install.md index 3282458e6..70870aee0 100644 --- a/docs/GettingStarted/install.md +++ b/docs/GettingStarted/install.md @@ -44,22 +44,31 @@ spack -e ~/SELF/share/spack-env install --no-check-signature Then, install SELF ``` -cd ~/SELF -spack env activate ~/SELF/share/spack-env -mkdir ~/SELF/build -cd ~/SELF/build +cd ${HOME}/SELF +spack env activate ${HOME}/SELF/share/spack-env +mkdir ${HOME}/SELF/build +cd ${HOME}/SELF/build cmake -DCMAKE_INSTALL_PREFIX=${HOME}/opt/self ../ make -make install ``` If you'd like to run the tests included with SELF, to verify your installation, you can use `ctest`. ``` -cd ${HOME}/opt/self/test +cd ${HOME}/SELF/build +export WORKSPACE=${HOME}/SELF ctest ``` +!!! note + Note that we're setting the environment variable `WORKSPACE` to the path to the SELF source code. This is due to the fact that some of the tests use this path to find mesh files that are read in during testing. If `WORKSPACE` is not set, some tests will fail. + +Once you confirm all tests have passed, you can finish installation + +``` +make install +``` + ### Once v0.0.1 is released The easiest way to get started is to use the [spack package manager](https://spack.io). The spack package manager provides you with an easy command line interface to install research software from source code with all of its dependencies. From 89153f5a1118dc8a7df806cffd67674ee820df40 Mon Sep 17 00:00:00 2001 From: Joe Schoonover Date: Sat, 18 Jan 2025 11:20:21 -0500 Subject: [PATCH 2/3] Update spack installation instructions This is in preparation for the coming spack package --- docs/GettingStarted/install.md | 108 +++++++-------------------------- 1 file changed, 22 insertions(+), 86 deletions(-) diff --git a/docs/GettingStarted/install.md b/docs/GettingStarted/install.md index 70870aee0..e39ec1862 100644 --- a/docs/GettingStarted/install.md +++ b/docs/GettingStarted/install.md @@ -2,74 +2,6 @@ ## Install with Spack -The easiest way to get started is to use the spack package manager. On a Linux platform, set up spack - -``` -git clone https://github.com/spack/spack ~/spack -source ~/spack/share/spack/setup-env.sh -``` - -Allow spack to locate your compilers (make sure you have C, C++, and Fortran compilers installed!) - -``` -spack compiler find -``` - -SELF comes with a spack environment file that defines the dependencies that are required for SELF. The versions listed in this environment file are the specific versions we regularly test against. To get this environment file, clone the SELF repository - -``` -git clone https://github.com/fluidnumerics/SELF/ ~/SELF/ -``` - -**If you have a preferred compiler** you would like for spack to use, you can use `spack config add`, e.g. - -``` -spack -e ~/SELF/share/spack-env config add packages:all:require:["'%gcc@12.2.0'"] -``` - -The example above will force packages to be built with version 12.2.0 of gfortran from the `gcc` compiler set. - -!!! note - If you do not set a preferred compiler, spack will pick one based on the available compilers found using `spack compiler find` - -To reduce build time, import existing packages on your system -``` -spack external find --not-buildable -``` - -Next, install SELF's dependencies (OpenMPI, HDF5, and feq-parse) -``` -spack -e ~/SELF/share/spack-env install --no-check-signature -``` - -Then, install SELF -``` -cd ${HOME}/SELF -spack env activate ${HOME}/SELF/share/spack-env -mkdir ${HOME}/SELF/build -cd ${HOME}/SELF/build -cmake -DCMAKE_INSTALL_PREFIX=${HOME}/opt/self ../ -make -``` - -If you'd like to run the tests included with SELF, to verify your installation, you can use `ctest`. - -``` -cd ${HOME}/SELF/build -export WORKSPACE=${HOME}/SELF -ctest -``` - -!!! note - Note that we're setting the environment variable `WORKSPACE` to the path to the SELF source code. This is due to the fact that some of the tests use this path to find mesh files that are read in during testing. If `WORKSPACE` is not set, some tests will fail. - -Once you confirm all tests have passed, you can finish installation - -``` -make install -``` - -### Once v0.0.1 is released The easiest way to get started is to use the [spack package manager](https://spack.io). The spack package manager provides you with an easy command line interface to install research software from source code with all of its dependencies. !!! note @@ -102,9 +34,13 @@ Next, install SELF and it's dependencies spack install self ``` +!!! note + Currently, GPU Accelerated builds of SELF are not supported through the Spack package manager. We are currently working on a few issues we encountered while integrating ROCm and CUDA package support in Spack. + By default, this will install SELF with the following features * Double precision floating point arithmetic -* No unit tests and no examples +* No unit tests +* Examples will be installed * No multi-threading, CPU-only You can view documentation on all possible variants using @@ -113,6 +49,21 @@ You can view documentation on all possible variants using spack info self ``` +You can find the installation path for SELF by using `spack location -i self`. + +To view the list of included examples : + +``` +ls $(spack location -i self)/test +``` + +To run a given example, you can do the following + +``` +spack load self +$(spack location -i self)/test/burgers1d_shock +``` + ### Enable Multithreading Many of the computationally intensive methods in SELF are written using the `do concurrent` structure. We have provided the variant `+multithreading` which will enable multithreading for all `do concurrent` blocks. You can install SELF with multithreading using @@ -123,28 +74,13 @@ spack install self+multithreading If you are using the GNU compiler suite, the number of threads used for `do concurrent` blocks is determined during build time. Because of this, we have provided the `nthreads` option, which defaults to 4. You can change this option to a value more sensible for your platform, e.g. ```shell -spack install self+multithreading nthreads=16 % gcc +spack install self+multithreading % gcc ``` The `%gcc` here indicates that you intend to build SELF with the GNU compilers. -### Enable Nvidia GPU Acceleration -SELF provides GPU accelerated implementations of all methods that are used in forward stepping conservation law solvers. On Nvidia GPU platforms, you can take advantage of this using the `+cuda` variant : - -```shell -spack install self+cuda -``` -This will also ensure that the MPI flavor that is used is GPU aware. You can specify the GPU architecture using the `gpu_arch` build option, e.g. for A100 GPUs - -```shell -spack install self+cuda gpu_arch=sm_80 -``` - -!!! note - AMD GPU-Aware MPI is currently not available in Spack. This means that these steps will not allow you to build SELF for multi-GPU platforms with AMD GPUs. See [Advanced Installation](#advanced-installation) for details on how to install for AMD GPU platforms. - - ## Advanced Installation +You can use these instructions for installing SELF on GPU accelerated platforms, or in cases where you do not wish to use the spack package manager. ### Dependencies The Spectral Element Library in Fortran can be built provided the following dependencies are met From 7997802a00eb967c92db7eaa54810048e3456b1d Mon Sep 17 00:00:00 2001 From: Joe Schoonover Date: Sat, 18 Jan 2025 12:12:12 -0500 Subject: [PATCH 3/3] Make note about multithreading support via spack --- docs/GettingStarted/install.md | 19 ++----------------- 1 file changed, 2 insertions(+), 17 deletions(-) diff --git a/docs/GettingStarted/install.md b/docs/GettingStarted/install.md index e39ec1862..15836ba06 100644 --- a/docs/GettingStarted/install.md +++ b/docs/GettingStarted/install.md @@ -35,7 +35,7 @@ spack install self ``` !!! note - Currently, GPU Accelerated builds of SELF are not supported through the Spack package manager. We are currently working on a few issues we encountered while integrating ROCm and CUDA package support in Spack. + Currently, GPU Accelerated and multithreaded builds of SELF are not supported through the Spack package manager. We are currently working on a few issues we encountered related to these features while integrating with Spack. By default, this will install SELF with the following features * Double precision floating point arithmetic @@ -64,23 +64,8 @@ spack load self $(spack location -i self)/test/burgers1d_shock ``` -### Enable Multithreading -Many of the computationally intensive methods in SELF are written using the `do concurrent` structure. We have provided the variant `+multithreading` which will enable multithreading for all `do concurrent` blocks. You can install SELF with multithreading using - -```shell -spack install self+multithreading -``` - -If you are using the GNU compiler suite, the number of threads used for `do concurrent` blocks is determined during build time. Because of this, we have provided the `nthreads` option, which defaults to 4. You can change this option to a value more sensible for your platform, e.g. - -```shell -spack install self+multithreading % gcc -``` - -The `%gcc` here indicates that you intend to build SELF with the GNU compilers. - ## Advanced Installation -You can use these instructions for installing SELF on GPU accelerated platforms, or in cases where you do not wish to use the spack package manager. +You can use these instructions for installing SELF on GPU accelerated platforms or with multithreading enabled, or in cases where you do not wish to use the spack package manager. ### Dependencies The Spectral Element Library in Fortran can be built provided the following dependencies are met