diff options
| -rw-r--r-- | Docs/source/install/dependencies.rst | 114 | ||||
| -rw-r--r-- | Docs/source/install/hpc/fugaku.rst | 1 | ||||
| -rw-r--r-- | Docs/source/install/users.rst | 16 |
3 files changed, 78 insertions, 53 deletions
diff --git a/Docs/source/install/dependencies.rst b/Docs/source/install/dependencies.rst index e363e6cf1..f2e0a16f3 100644 --- a/Docs/source/install/dependencies.rst +++ b/Docs/source/install/dependencies.rst @@ -41,14 +41,16 @@ Optional dependencies include: - `lasy <https://lasydoc.readthedocs.io>`__ - see our ``requirements.txt`` file for compatible versions +If you are on a high-performance computing (HPC) system, then :ref:`please see our separate HPC documentation <install-hpc>`. -Install -------- - +For all other systems, we recommend to use a **package dependency manager**: Pick *one* of the installation methods below to install all dependencies for WarpX development in a consistent manner. + Conda (Linux/macOS/Windows) -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +--------------------------- + +`Conda <https://conda.io>`__/`Mamba <https://mamba.readthedocs.io>`__ are cross-compatible, user-level package managers. .. tip:: @@ -60,42 +62,41 @@ Conda (Linux/macOS/Windows) conda install -n base conda-libmamba-solver conda config --set solver libmamba -With MPI (only Linux/macOS): + We recommend to deactivate that conda self-activates its ``base`` environment. + This `avoids interference with the system and other package managers <https://collegeville.github.io/CW20/WorkshopResources/WhitePapers/huebl-working-with-multiple-pkg-mgrs.pdf>`__. -.. code-block:: bash + .. code-block:: bash - conda create -n warpx-dev -c conda-forge blaspp boost ccache cmake compilers git lapackpp "openpmd-api=*=mpi_mpich*" python numpy pandas scipy yt "fftw=*=mpi_mpich*" pkg-config matplotlib mamba ninja mpich pip virtualenv - source activate warpx-dev + conda config --set auto_activate_base false -Without MPI: +.. tab-set:: -.. code-block:: bash + .. tab-item:: With MPI (only Linux/macOS) - conda create -n warpx-dev -c conda-forge blaspp boost ccache cmake compilers git lapackpp openpmd-api python numpy pandas scipy yt fftw pkg-config matplotlib mamba ninja pip virtualenv - source activate warpx-dev + .. code-block:: bash - # compile WarpX with -DWarpX_MPI=OFF + conda create -n warpx-cpu-mpich-dev -c conda-forge blaspp boost ccache cmake compilers git lapackpp "openpmd-api=*=mpi_mpich*" python numpy pandas scipy yt "fftw=*=mpi_mpich*" pkg-config matplotlib mamba ninja mpich pip virtualenv + conda activate warpx-cpu-mpich-dev -For legacy ``GNUmake`` builds, after each ``source activate warpx-dev``, you also need to set: + # compile WarpX with -DWarpX_MPI=ON + # for pip, use: export WARPX_MPI=ON -.. code-block:: bash + .. tab-item:: Without MPI - export FFTW_HOME=${CONDA_PREFIX} - export BLASPP_HOME=${CONDA_PREFIX} - export LAPACKPP_HOME=${CONDA_PREFIX} + .. code-block:: bash -.. tip:: + conda create -n warpx-cpu-dev -c conda-forge blaspp boost ccache cmake compilers git lapackpp openpmd-api python numpy pandas scipy yt fftw pkg-config matplotlib mamba ninja pip virtualenv + conda activate warpx-cpu-dev - A general option to deactivate that conda self-activates its base environment. - This `avoids interference with the system and other package managers <https://collegeville.github.io/CW20/WorkshopResources/WhitePapers/huebl-working-with-multiple-pkg-mgrs.pdf>`__. + # compile WarpX with -DWarpX_MPI=OFF + # for pip, use: export WARPX_MPI=OFF - .. code-block:: bash - - conda config --set auto_activate_base false +Spack (Linux/macOS) +------------------- -Spack (macOS/Linux) -^^^^^^^^^^^^^^^^^^^ +`Spack <https://spack.readthedocs.io>`__ 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 <https://github.com/ECP-WarpX/WarpX/blob/development/Tools/machines/desktop>`__ of your choice. For most desktop developments, pick the OpenMP environment for CPUs unless you have a supported GPU. @@ -141,17 +142,14 @@ In new terminal sessions, re-activate the environment with again. Replace ``openmp`` with the equivalent you chose. -For legacy ``GNUmake`` builds, after each ``source activate warpx-openmp-dev``, you also need to set: - -.. code-block:: bash - - export FFTW_HOME=${SPACK_ENV}/.spack-env/view - export BLASPP_HOME=${SPACK_ENV}/.spack-env/view - export LAPACKPP_HOME=${SPACK_ENV}/.spack-env/view +Compile WarpX with ``-DWarpX_MPI=ON``. +For ``pip``, use ``export WARPX_MPI=ON``. Brew (macOS/Linux) -^^^^^^^^^^^^^^^^^^ +------------------ + +`Homebrew (Brew) <https://brew.sh>`__ is a user-level package manager primarily for `Apple macOS <https://en.wikipedia.org/wiki/MacOS>`__, but also supports Linux. .. code-block:: bash @@ -184,17 +182,45 @@ If you also want to compile with PSATD in RZ, you need to manually install BLAS+ 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 WarpX with ``-DWarpX_MPI=ON``. +For ``pip``, use ``export WARPX_MPI=ON``. -Apt (Debian/Ubuntu) -^^^^^^^^^^^^^^^^^^^ -.. code-block:: bash +APT (Debian/Ubuntu Linux) +------------------------- + +The `Advanced Package Tool (APT) <https://en.wikipedia.org/wiki/APT_(software)>`__ 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 libfftw3-mpi-dev libfftw3-dev 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 WarpX with -DWarpX_MPI=ON + # for pip, use: export WARPX_MPI=ON + + .. tab-item:: Without MPI + + .. code-block:: bash + + sudo apt update + sudo apt install build-essential ccache cmake g++ git libfftw3-dev libfftw3-dev libhdf5-dev pkg-config python3 python3-matplotlib python3-numpy python3-pandas python3-pip python3-scipy python3-venv - 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-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 - # 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 WarpX with -DWarpX_MPI=OFF + # for pip, use: export WARPX_MPI=OFF diff --git a/Docs/source/install/hpc/fugaku.rst b/Docs/source/install/hpc/fugaku.rst index 618be472a..8f09f9673 100644 --- a/Docs/source/install/hpc/fugaku.rst +++ b/Docs/source/install/hpc/fugaku.rst @@ -48,6 +48,7 @@ Then, load ``cmake`` and ``ninja`` using ``spack``: At this point we need to download and compile the libraries required for OpenPMD support: .. code-block:: bash + export CC=$(which mpifcc) export CXX=$(which mpiFCC) export CFLAGS="-O3 -Nclang -Nlibomp -Klib -g -DNDEBUG" diff --git a/Docs/source/install/users.rst b/Docs/source/install/users.rst index 648a5e9a6..5174a3b53 100644 --- a/Docs/source/install/users.rst +++ b/Docs/source/install/users.rst @@ -53,6 +53,13 @@ A package for WarpX is available via the `Conda <https://conda.io>`_ package man conda install -n base conda-libmamba-solver conda config --set solver libmamba + We recommend to deactivate that conda self-activates its ``base`` environment. + This `avoids interference with the system and other package managers <https://collegeville.github.io/CW20/WorkshopResources/WhitePapers/huebl-working-with-multiple-pkg-mgrs.pdf>`__. + + .. code-block:: bash + + conda config --set auto_activate_base false + .. code-block:: bash conda create -n warpx -c conda-forge warpx @@ -62,15 +69,6 @@ A package for WarpX is available via the `Conda <https://conda.io>`_ package man The ``warpx`` `conda package <https://anaconda.org/conda-forge/warpx>`__ does not yet provide GPU support. -.. tip:: - - A general option to deactivate that conda self-activates its base environment. - This `avoids interference with the system and other package managers <https://collegeville.github.io/CW20/WorkshopResources/WhitePapers/huebl-working-with-multiple-pkg-mgrs.pdf>`__. - - .. code-block:: bash - - conda config --set auto_activate_base false - .. _install-spack: |