See also

You will need to understand how to use the terminal, what are environment variables and please read our compiling introduction.


If you are a scientific user at a supercomputing facility we might have already prepared a software setup for you. See the following chapter if you can skip this step fully or in part by loading existing modules on those systems.


Section author: Axel Huebl


overview of PIConGPU library dependencies

Overview of inter-library dependencies for parallel execution of PIConGPU on a typical HPC system. Due to common binary incompatibilities between compilers, MPI and boost versions, we recommend to organize software with a version-aware package manager such as spack and to deploy a hierarchical module system such as lmod. An Lmod example setup can be found here.




  • 5.5 - 10.0 (if you want to build for Nvidia GPUs, supported compilers depend on your current CUDA version)

    • CUDA 9.2 - 10.0: Use gcc 5.5 - 7

    • CUDA 10.1/10.2: Use gcc 5.5 - 8

    • CUDA 11.x: Used gcc 5.5 - 10.0

  • note: be sure to build all libraries/dependencies with the same gcc version; GCC 5 or newer is recommended

  • Debian/Ubuntu:

    • sudo apt-get install gcc-5 g++-5 build-essential

    • sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-5 60 --slave /usr/bin/g++ g++ /usr/bin/g++-5

  • Arch Linux:

  • Spack:

    • spack install gcc@5.5.0

    • make it the default in your packages.yaml or suffix all following spack install commands with a space and %gcc@5.5.0


  • 3.15.0 or higher

  • Debian/Ubuntu: sudo apt-get install cmake file cmake-curses-gui

  • Arch Linux: sudo pacman --sync cmake

  • Spack: spack install cmake

MPI 2.3+

  • OpenMPI 1.7+ / MVAPICH2 1.8+ or similar

  • for running on Nvidia GPUs, perform a GPU aware MPI install after installing CUDA

  • Debian/Ubuntu: sudo apt-get install libopenmpi-dev

  • Arch Linux: sudo pacman --sync openmpi

  • Spack:

    • GPU support: spack install openmpi+cuda

    • CPU only: spack install openmpi

  • environment:

    • export MPI_ROOT=<MPI_INSTALL>

    • as long as CUDA awareness (openmpi+cuda) is missing: export OMPI_MCA_mpi_leave_pinned=0


  • Debian/Ubuntu: sudo apt-get install zlib1g-dev

  • Arch Linux: sudo pacman --sync zlib

  • Spack: spack install zlib

  • from source:

    • ./configure --prefix=$HOME/lib/zlib

    • make && make install

  • environent: (assumes install from source in $HOME/lib/zlib)

    • export ZLIB_ROOT=$HOME/lib/zlib




  • 1.65.1 - 1.70.0 (program_options, filesystem, system, math, serialization and header-only libs, optional: fiber with context, thread, chrono, atomic, date_time)

  • Debian/Ubuntu: sudo apt-get install libboost-program-options-dev libboost-filesystem-dev libboost-system-dev libboost-thread-dev libboost-chrono-dev libboost-atomic-dev libboost-date-time-dev libboost-math-dev libboost-serialization-dev libboost-fiber-dev libboost-context-dev

  • Arch Linux: sudo pacman --sync boost

  • Spack: spack install boost

  • from source:

    • curl -Lo boost_1_65_1.tar.gz

    • tar -xzf boost_1_65_1.tar.gz

    • cd boost_1_65_1

    • ./ --with-libraries=atomic,chrono,context,date_time,fiber,filesystem,math,program_options,serialization,system,thread --prefix=$HOME/lib/boost

    • ./b2 cxxflags="-std=c++11" -j4 && ./b2 install

  • environment: (assumes install from source in $HOME/lib/boost)

    • export BOOST_ROOT=$HOME/lib/boost



  • or higher

  • Debian/Ubuntu: sudo apt-get install git

  • Arch Linux: sudo pacman --sync git

  • Spack: spack install git


  • Debian/Ubuntu: sudo apt-get install rsync

  • Arch Linux: sudo pacman --sync rsync

  • Spack: spack install rsync

alpaka 0.4.0

  • alpaka is included in the PIConGPU source code

cupla 0.2.0

  • cupla is included in the PIConGPU source code

mallocMC 2.3.0crp

  • only required for CUDA backend

  • mallocMC is included in the PIConGPU source code

PIConGPU Source Code

  • git clone $HOME/src/picongpu

    • optional: update the source code with cd $HOME/src/picongpu && git fetch && git pull

    • optional: change to a different branch with git branch (show) and git checkout <BranchName> (switch)

  • environment:

    • export PICSRC=$PICHOME/src/picongpu

    • export PIC_EXAMPLES=$PICSRC/share/picongpu/examples

    • export PATH=$PICSRC:$PATH

    • export PATH=$PICSRC/bin:$PATH

    • export PATH=$PICSRC/src/tools/bin:$PATH

    • export PYTHONPATH=$PICSRC/lib/python:$PYTHONPATH

Optional Libraries


  • 9.2 - 10.2

  • required if you want to run on Nvidia GPUs

  • Debian/Ubuntu: sudo apt-get install nvidia-cuda-toolkit

  • Arch Linux: sudo pacman --sync cuda

  • Spack: spack install cuda

  • at least one CUDA capable GPU

  • compute capability: sm_30 or higher

  • full list of CUDA GPUs and their compute capability

  • More is always better. Especially, if we are talking GPUs :-)

  • environment:


If you do not install the following libraries, you will not have the full amount of PIConGPU plugins. We recommend to install at least pngwriter and either libSplash (+ HDF5) or ADIOS.


  • 1.2.9+ (requires zlib)

  • Debian/Ubuntu dependencies: sudo apt-get install libpng-dev

  • Arch Linux dependencies: sudo pacman --sync libpng

  • Spack: spack install libpng

  • from source:

    • mkdir -p ~/src ~/lib

    • cd ~/src

    • curl -Lo libpng-1.6.34.tar.gz

    • tar -xf libpng-1.6.34.tar.gz

    • cd libpng-1.6.34

    • CPPFLAGS=-I$HOME/lib/zlib/include LDFLAGS=-L$HOME/lib/zlib/lib ./configure --enable-static --enable-shared --prefix=$HOME/lib/libpng

    • make

    • make install

  • environment: (assumes install from source in $HOME/lib/libpng)

    • export PNG_ROOT=$HOME/lib/libpng




  • 0.7.0+ (requires libpng, zlib, and optional freetype)

  • Spack: spack install pngwriter

  • from source:

    • mkdir -p ~/src ~/build ~/lib

    • git clone ~/src/pngwriter/

    • cd ~/build

    • cmake -DCMAKE_INSTALL_PREFIX=$HOME/lib/pngwriter ~/src/pngwriter

    • make install

  • environment: (assumes install from source in $HOME/lib/pngwriter)

    • export CMAKE_PREFIX_PATH=$HOME/lib/pngwriter:$CMAKE_PREFIX_PATH

    • export LD_LIBRARY_PATH=$HOME/lib/pngwriter/lib:$LD_LIBRARY_PATH


  • 1.7.0+ (requires HDF5, boost program-options)

  • Debian/Ubuntu dependencies: sudo apt-get install libhdf5-openmpi-dev libboost-program-options-dev

  • Arch Linux dependencies: sudo pacman --sync hdf5-openmpi boost

  • Spack: spack install libsplash ^hdf5~fortran

  • from source:

    • mkdir -p ~/src ~/build ~/lib

    • git clone ~/src/splash/

    • cd ~/build && rm -rf ../build/*

    • cmake -DCMAKE_INSTALL_PREFIX=$HOME/lib/splash -DSplash_USE_MPI=ON -DSplash_USE_PARALLEL=ON ~/src/splash

    • make install

  • environment: (assumes install from source in $HOME/lib/splash)


    • export LD_LIBRARY_PATH=$HOME/lib/splash/lib:$LD_LIBRARY_PATH


  • 1.8.13+

  • standard shared version (no C++, enable parallel)

  • Debian/Ubuntu: sudo apt-get install libhdf5-openmpi-dev

  • Arch Linux: sudo pacman --sync hdf5-openmpi

  • Spack: spack install hdf5~fortran

  • from source:

    • mkdir -p ~/src ~/lib

    • cd ~/src

    • download hdf5 source code from release list of the HDF5 group, for example:

    • curl -Lo hdf5-1.8.20.tar.gz

    • tar -xzf hdf5-1.8.20.tar.gz

    • cd hdf5-1.8.20

    • ./configure --enable-parallel --enable-shared --prefix $HOME/lib/hdf5/

    • make

    • optional: make test

    • make install

    • If you encounter errors related to linking MPI during ./configure, you might try setting the compiler manually via ./configure --enable-parallel --enable-shared --prefix $HOME/lib/hdf5/ CC=mpicc CXX=mpic++.

  • environment: (assumes install from source in $HOME/lib/hdf5)

    • export HDF5_ROOT=$HOME/lib/hdf5



  • requires libSplash and boost program_options

  • converts slices in dumped hdf5 files to plain txt matrices

  • assume you [downloaded](#requirements) PIConGPU to PICSRC=$HOME/src/picongpu

  • mkdir -p ~/build && cd ~/build

  • cmake -DCMAKE_INSTALL_PREFIX=$PICSRC/src/tools/bin $PICSRC/src/tools/splash2txt

  • make

  • make install

  • environment:

    • export PATH=$PATH:$PICSRC/src/splash2txt/build

  • options:

    • splash2txt --help

    • list all available datasets: splash2txt --list <FILE_PREFIX>


  • requires libSplash, pngwriter and boost program_options)

  • converts png files to hdf5 files that can be used as an input for species initial density profiles

  • compile and install exactly as splash2txt above


  • general purpose compressor, used in ADIOS for in situ data reduction

  • Debian/Ubuntu: sudo apt-get install libblosc-dev

  • Arch Linux: sudo pacman --sync blosc

  • Spack: spack install c-blosc

  • from source:

    • mkdir -p ~/src ~/build ~/lib

    • cd ~/src

    • curl -Lo c-blosc-1.15.0.tar.gz

    • tar -xzf c-blosc-1.15.0.tar.gz

    • cd ~/build && rm -rf ../build/*

    • cmake -DCMAKE_INSTALL_PREFIX=$HOME/lib/c-blosc -DPREFER_EXTERNAL_ZLIB=ON ~/src/c-blosc-1.15.0/

    • make

    • make install

  • environment: (assumes install from source in $HOME/lib/c-blosc)

    • export BLOSC_ROOT=$HOME/lib/c-blosc




  • 1.13.1+ (requires MPI, zlib and c-blosc)

  • Debian/Ubuntu: sudo apt-get install libadios-dev libadios-bin

  • Arch Linux using an AUR helper: pacaur --sync libadios

  • Arch Linux using the AUR manually:

    • sudo pacman --sync --needed base-devel

    • git clone

    • cd libadios

    • makepkg -sri

  • Spack: spack install adios

  • from source:

    • mkdir -p ~/src ~/lib

    • cd ~/src

    • curl -Lo adios-1.13.1.tar.gz

    • tar -xzf adios-1.13.1.tar.gz

    • cd adios-1.13.1

    • CFLAGS="-fPIC" ./configure --enable-static --enable-shared --prefix=$HOME/lib/adios --with-mpi=$MPI_ROOT --with-zlib=$HOME/lib/zlib --with-blosc=$HOME/lib/c-blosc

    • make

    • make install

  • environment: (assumes install from source in $HOME/lib/adios)

    • export ADIOS_ROOT=$HOME/lib/adios



  • 0.12.0+ (yet to be released, requires MPI)

  • Spack: spack install openpmd-api

  • from source:

    • mkdir -p ~/src ~/lib

    • cd ~/src

    • git clone

    • cd openPMD-api

    • mkdir build && cd build

    • cmake .. -DopenPMD_USE_MPI=ON -DCMAKE_INSTALL_PREFIX=~/lib/openPMD-api

    • make -j $(nproc) install

  • environment:* (assumes install from source in $HOME/lib/openPMD-api)


    • export LD_LIBRARY_PATH="$HOME/lib/openPMD-api/lib:$LD_LIBRARY_PATH"


  • 1.4.0+

  • requires boost (header only), IceT, Jansson, libjpeg (preferably libjpeg-turbo), libwebsockets (only for the ISAAC server, but not the plugin itself)

  • enables live in situ visualization, see more here Plugin description

  • Spack: spack install isaac

  • from source: build the in situ library and its dependencies as described in ISAAC’s

  • environment: set environment variable CMAKE_PREFIX_PATH for each dependency and the ISAAC in situ library


  • for developers: performance tracing support

  • download 5.14.4 or higher, e.g. from

  • from source:

    • mkdir -p ~/src ~/build ~/lib

    • cd ~/src

    • curl -Lo VampirTrace-5.14.4.tar.gz ""

    • tar -xzf VampirTrace-5.14.4.tar.gz

    • cd VampirTrace-5.14.4

    • ./configure --prefix=$HOME/lib/vampirtrace --with-cuda-dir=<CUDA_ROOT>

    • make all -j

    • make install

  • environment: (assumes install from source in $HOME/lib/vampirtrace)

    • export VT_ROOT=$HOME/lib/vampirtrace

    • export PATH=$VT_ROOT/bin:$PATH