diff --git a/docs/source/install/cmake.rst b/docs/source/install/cmake.rst index 5f27c587d..b9b6c3e8a 100644 --- a/docs/source/install/cmake.rst +++ b/docs/source/install/cmake.rst @@ -36,7 +36,7 @@ ImpactX depends on popular third party software. .. code-block:: bash python3 -m pip install -U pip setuptools wheel pytest - python3 -m pip install -r examples/requirements.txt + python3 -m pip install -U -r examples/requirements.txt Compile diff --git a/docs/source/install/dependencies.rst b/docs/source/install/dependencies.rst index 6e00a9a7e..d459102d8 100644 --- a/docs/source/install/dependencies.rst +++ b/docs/source/install/dependencies.rst @@ -6,113 +6,226 @@ Dependencies ImpactX depends on the following popular third party software. Please see installation instructions below. -- a mature `C++17 `__ compiler, e.g., GCC 7, Clang 7, NVCC 11.0, MSVC 19.15 or newer -- `CMake 3.15.0+ `__ +- a mature `C++17 `__ compiler, e.g., GCC 8.4+, Clang 7, NVCC 11.0, MSVC 19.15 or newer +- `CMake 3.20.0+ `__ - `Git 2.18+ `__ - `AMReX `__: we automatically download and compile a copy -- `WarpX `__: we automatically download and compile a copy +- `ABLASTR/WarpX `__: we automatically download and compile a copy Optional dependencies include: - `MPI 3.0+ `__: for multi-node and/or multi-GPU execution -- `CUDA Toolkit 11.3+ `__: for Nvidia GPU support (see `matching host-compilers `_) -- `OpenMP 3.1+ `__: for threaded CPU execution -- `FFTW3 `_: for spectral solver support +- for on-node accelerated compute *one of either*: + + - `OpenMP 3.1+ `__: for threaded CPU execution or + - `CUDA Toolkit 11.0+ (11.3+ recommended) `__: for Nvidia GPU support (see `matching host-compilers `_) or + - `ROCm 5.2+ (5.5+ recommended) `__: for AMD GPU support - `openPMD-api 0.15.1+ `__: we automatically download and compile a copy of openPMD-api for openPMD I/O support - see `optional I/O backends `__ -- `CCache `__: to speed up rebuilds (needs 3.7.9+ for CUDA) +- `CCache `__: to speed up rebuilds (For CUDA support, needs version 3.7.9+ and 4.2+ is recommended) - `Ninja `__: for faster parallel compiles +- `Python 3.7+ `__ + - `mpi4py `__ + - `numpy `__ + - `openPMD-api `__ + - see our ``requirements.txt`` file for compatible versions -Install -------- +If you are on a high-performance computing (HPC) system, then :ref:`please see our separate HPC documentation `. +For all other systems, we recommend to use a **package dependency manager**: Pick *one* of the installation methods below to install all dependencies for ImpactX development in a consistent manner. -Conda (Linux/macOS/Windows) -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -With MPI (only Linux/macOS): - -.. code-block:: bash - conda create -n impactx-dev -c conda-forge ccache cmake compilers git "openpmd-api=*=mpi_mpich*" python mpich numpy scipy yt "fftw=*=mpi_mpich*" matplotlib mamba ninja numpy pandas pytest scipy - conda activate impactx-dev +Conda (Linux/macOS/Windows) +--------------------------- -Without MPI: +`Conda `__/`Mamba `__ are cross-compatible, user-level package managers. -.. code-block:: bash +.. tip:: - conda create -n impactx-nompi-dev -c conda-forge ccache cmake compilers git openpmd-api python numpy scipy yt fftw matplotlib mamba ninja numpy pandas scipy - conda activate impactx-nompi-dev + We recommend to configure your conda to use the faster ``libmamba`` `dependency solver `__. - # compile ImpactX with -DImpactX_MPI=OFF + .. code-block:: bash -.. note:: + conda update -n base conda + conda install -n base conda-libmamba-solver + conda config --set solver libmamba - A general option to deactivate that conda self-activates its base environment. + We recommend to deactivate that conda self-activates its ``base`` environment. This `avoids interference with the system and other package managers `__. .. code-block:: bash conda config --set auto_activate_base false +.. tab-set:: + + .. tab-item:: With MPI (only Linux/macOS) + + .. code-block:: bash + + conda create -n impactx-cpu-mpich-dev -c conda-forge blaspp boost ccache cmake compilers git lapackpp "openpmd-api=*=mpi_mpich*" python numpy pandas scipy yt pkg-config matplotlib mamba ninja mpich pip virtualenv + conda activate impactx-cpu-mpich-dev + + # compile ImpactX with -DImpactX_MPI=ON + # for pip, use: export IMPACTX_MPI=ON + + .. tab-item:: Without MPI + + .. code-block:: bash + + conda create -n impactx-cpu-dev -c conda-forge blaspp boost ccache cmake compilers git lapackpp openpmd-api python numpy pandas scipy yt pkg-config matplotlib mamba ninja pip virtualenv + conda activate impactx-cpu-dev + + # compile ImpactX with -DImpactX_MPI=OFF + # for pip, use: export IMPACTX_MPI=OFF + +For OpenMP support, you will further need: + +.. tab-set:: + + .. tab-item:: Linux + + .. code-block:: bash + + conda install -c conda-forge libgomp + + .. tab-item:: macOS or Windows + + .. code-block:: bash + + conda install -c conda-forge llvm-openmp + + +Spack (Linux/macOS) +------------------- + +`Spack `__ is a user-level package manager. +It is primarily written for Linux, with slightly less support for macOS, and future support for Windows. + +First, download a `WarpX Spack desktop development environment `__ of your choice (which will also work for ImpactX). +For most desktop developments, pick the OpenMP environment for CPUs unless you have a supported GPU. + +* **Debian/Ubuntu** Linux: + + * OpenMP: ``system=ubuntu; compute=openmp`` (CPUs) + * CUDA: ``system=ubuntu; compute=cuda`` (Nvidia GPUs) + * ROCm: ``system=ubuntu; compute=rocm`` (AMD GPUs) + * SYCL: *todo* (Intel GPUs) +* **macOS**: first, prepare with ``brew install gpg2; brew install gcc`` -Spack (macOS/Linux) -^^^^^^^^^^^^^^^^^^^ + * OpenMP: ``system=macos; compute=openmp`` + +If you already `installed Spack `__, we recommend to activate its `binary caches `__ for faster builds: + +.. code-block:: bash + + spack mirror add rolling https://binaries.spack.io/develop + spack buildcache keys --install --trust + +Now install the WarpX/ImpactX dependencies in a new development environment: .. code-block:: bash - spack env create impactx-dev - spack env activate impactx-dev - spack add adios2 # for openPMD - spack add ccache - spack add cmake - spack add fftw - spack add hdf5 # for openPMD - spack add mpi - spack add pkgconfig # for fftw - spack add python - spack add py-pip - spack add py-setuptools - spack add py-wheel - - # OpenMP support on macOS - [[ $OSTYPE == 'darwin'* ]] && spack add llvm-openmp - - # optional: Linux only - #spack add cuda + # download environment file + curl -sLO https://raw.githubusercontent.com/ECP-WarpX/WarpX/development/Tools/machines/desktop/spack-${system}-${compute}.yaml + + # create new development environment + spack env create impactx-${compute}-dev spack-${system}-${compute}.yaml + spack env activate impactx-${compute}-dev + # installation spack install - python3 -m pip install matplotlib numpy openpmd-api pandas pytest scipy + python3 -m pip install jupyter matplotlib numpy openpmd-api openpmd-viewer pandas scipy virtualenv yt -In new terminals, re-activate the environment with ``spack env activate impactx-dev`` again. +In new terminal sessions, re-activate the environment with + +.. code-block:: bash + + spack env activate impactx-openmp-dev + +again. +Replace ``openmp`` with the equivalent you chose. + +Compile ImpactX with ``-DImpactX_MPI=ON``. +For ``pip``, use ``export IMPACTX_MPI=ON``. Brew (macOS/Linux) -^^^^^^^^^^^^^^^^^^ +------------------ + +`Homebrew (Brew) `__ is a user-level package manager primarily for `Apple macOS `__, but also supports Linux. .. code-block:: bash brew update + brew tap openpmd/openpmd brew install adios2 # for openPMD brew install ccache brew install cmake - brew install fftw brew install git brew install hdf5-mpi # for openPMD - brew install libomp # for OpenMP - brew install pkg-config # for fftw + brew install libomp + brew unlink gcc + brew link --force libomp brew install open-mpi - brew install python - python3 -m pip install matplotlib yt scipy numpy openpmd-api + brew install openblas # for PSATD in RZ + brew install openpmd-api # for openPMD - -Apt (Debian/Ubuntu) -^^^^^^^^^^^^^^^^^^^ +If you also want to compile with PSATD in RZ, you need to manually install BLAS++ and LAPACK++: .. code-block:: bash - sudo apt update - sudo apt install build-essential ccache cmake g++ git libfftw3-mpi-dev libfftw3-dev libhdf5-openmpi-dev libopenmpi-dev pkg-config python3 python3-matplotlib python3-numpy python3-pandas python3-scipy + sudo mkdir -p /usr/local/bin/ + sudo curl -L -o /usr/local/bin/cmake-easyinstall https://raw.githubusercontent.com/ax3l/cmake-easyinstall/main/cmake-easyinstall + sudo chmod a+x /usr/local/bin/cmake-easyinstall + + cmake-easyinstall --prefix=/usr/local git+https://github.com/icl-utk-edu/blaspp.git \ + -Duse_openmp=OFF -Dbuild_tests=OFF -DCMAKE_VERBOSE_MAKEFILE=ON + cmake-easyinstall --prefix=/usr/local git+https://github.com/icl-utk-edu/lapackpp.git \ + -Duse_cmake_find_lapack=ON -Dbuild_tests=OFF -DCMAKE_VERBOSE_MAKEFILE=ON + +Compile ImpactX with ``-DImpactX_MPI=ON``. +For ``pip``, use ``export IMPACTX_MPI=ON``. + + +APT (Debian/Ubuntu Linux) +------------------------- + +The `Advanced Package Tool (APT) `__ is a system-level package manager on Debian-based Linux distributions, including Ubuntu. + +.. tab-set:: + + .. tab-item:: With MPI (only Linux/macOS) + + .. code-block:: bash + + sudo apt update + sudo apt install build-essential ccache cmake g++ git libhdf5-openmpi-dev libopenmpi-dev pkg-config python3 python3-matplotlib python3-numpy python3-pandas python3-pip python3-scipy python3-venv + + # optional: + # for CUDA, either install + # https://developer.nvidia.com/cuda-downloads (preferred) + # or, if your Debian/Ubuntu is new enough, use the packages + # sudo apt install nvidia-cuda-dev libcub-dev + + # compile ImpactX with -DImpactX_MPI=ON + # for pip, use: export IMPACTX_MPI=ON + + .. tab-item:: Without MPI + + .. code-block:: bash + + sudo apt update + sudo apt install build-essential ccache cmake g++ git libhdf5-dev pkg-config python3 python3-matplotlib python3-numpy python3-pandas python3-pip python3-scipy python3-venv + + # optional: + # for CUDA, either install + # https://developer.nvidia.com/cuda-downloads (preferred) + # or, if your Debian/Ubuntu is new enough, use the packages + # sudo apt install nvidia-cuda-dev libcub-dev + + # compile ImpactX with -DImpactX_MPI=OFF + # for pip, use: export IMPACTX_MPI=OFF