### First-time setup: set PIC_PROFILE and install dependencies

Source: https://picongpu.readthedocs.io/en/latest/_sources/install/profiles/perlmutter-nersc/README.md.txt

First-time setup: set the PIC_PROFILE environment variable to the gpu.profile path, then install missing dependencies from source on a login node.

```bash
export PIC_PROFILE=/path/to/gpu.profile
```

```bash
source dependencies_autoinstall.sh
```

--------------------------------

### CMake out-of-source build example

Source: https://picongpu.readthedocs.io/en/latest/_sources/install/instructions.rst.txt

Shows the typical out-of-source build workflow with CMake: configure with -DCMAKE_INSTALL_PREFIX, then make and make install. Options can be passed with -DOPTION=VALUE or modified interactively with ccmake. Use make -j to parallelize compilation, and prefix make install with sudo if installing to a system directory.

```bash
# go to an empty, temporary build directory
cd $HOME/build
rm -rf ../build/*

# configurate, build and install into $HOME/lib/project
cmake -DCMAKE_INSTALL_PREFIX=$HOME/lib/project $HOME/src/project_to_compile
make
make install
```

--------------------------------

### Expected output of ls -lah $SCRATCH

Source: https://picongpu.readthedocs.io/en/latest/tutorials/hemeraIn5min.html

Example output showing a successful setup: the directory exists and is accessible.

```bash
total 0
drwxr-xr-x  2 <username>    fwt   40 Nov 12 10:09 .
drwxrwxrwt 17 root     root 400 Nov 12 10:09 ..

```

--------------------------------

### Autotools in-source build example

Source: https://picongpu.readthedocs.io/en/latest/_sources/install/instructions.rst.txt

Shows the typical in-source build workflow with autotools: configure with --prefix, then make and make install. Options can be passed with --with-something=VALUE or --enable-thing, and see configure --help for available options.

```bash
# go to the source directory of the project
cd $HOME/src/project_to_compile

# configurate, build and install into $HOME/lib/project
configure --prefix=$HOME/lib/project
make
make install
```

--------------------------------

### Compile all examples with compile script

Source: https://picongpu.readthedocs.io/en/latest/_sources/dev/docs/COMMIT.md.txt

Run the compile script with the -l option to compile all examples in the examples/ directory. Assumes repo and tmpPath variables are set.

```bash
$repo/compile -l $repo/examples/ $tmpPath
```

--------------------------------

### Build Boost from Source

Source: https://picongpu.readthedocs.io/en/latest/_sources/install/dependencies.rst.txt

Steps to download, build, and install Boost 1.74.0 from source.

```bash
mkdir -p ~/src ~/lib
cd ~/src
curl -Lo boost_1_74_0.tar.gz https://boostorg.jfrog.io/artifactory/main/release/1.74.0/source/boost_1_74_0.tar.gz
tar -xzf boost_1_74_0.tar.gz
cd boost_1_74_0
./bootstrap.sh --with-libraries=program_options --prefix=$HOME/lib/boost
./b2 cxxflags="-std=c++20" -j4 && ./b2 install
```

--------------------------------

### Create a Scenario

Source: https://picongpu.readthedocs.io/en/latest/_sources/tutorials/hemeraIn5min.rst.txt

Create a project directory and copy the LaserWakefield example into it.

```bash
mkdir -p ~/picongpu-projects/laser-wakefield-example
pic-create $PIC_EXAMPLES/LaserWakefield ~/picongpu-projects/laser-wakefield-example/try01
cd ~/picongpu-projects/laser-wakefield-example/try01
```

--------------------------------

### Load and analyze phase space data in Python

Source: https://picongpu.readthedocs.io/en/latest/_sources/usage/plugins/phaseSpace.rst.txt

Python example using PhaseSpaceData to load and interact with phase space data. Shows how to get available iterations and times, load data for a specific iteration or time, and perform unit conversions.

```python
from picongpu.extra.plugins.data import PhaseSpaceData
import numpy as np


ps_data = PhaseSpaceData('/home/axel/runs/lwfa_001')
# show available iterations
ps_data.get_iterations(ps="xpx", species="e", species_filter='all')

# show available simulation times
ps_data.get_times(ps="xpx", species="e", species_filter='all')

# load data for a given iteration
ps, meta = ps_data.get(ps='ypy', species='e', species_filter='all', iteration=2000)

# unit conversion from SI
mu = 1.e6  # meters to microns
e_mc_r = 1. / (9.109e-31 * 2.9979e8)  # electrons: kg * m / s to beta * gamma

Q_dr_dp = np.abs(ps) * meta.dV  # unit: Coulomb
extent = meta.extent * [mu, mu, e_mc_r, e_mc_r]  # spatial: microns, momentum: beta*gamma

# load data for a given time
ps, ps_meta = ps_data.get(ps="xpx", species="e", species_filter='all', time=1.3900e-14)

# load data for multiple iterations
ret = ps_data.get(ps="xpx", species="e", species_filter='all', iteration=[2000, 4000])
```

--------------------------------

### Example Directory Listing Output

Source: https://picongpu.readthedocs.io/en/latest/_sources/tutorials/hemeraIn5min.rst.txt

Sample output confirming the directory exists and is accessible.

```text
total 0
drwxr-xr-x  2 <username>    fwt   40 Nov 12 10:09 .
drwxrwxrwt 17 root     root 400 Nov 12 10:09 ..
```

--------------------------------

### Configure multiple PNG slices via command line

Source: https://picongpu.readthedocs.io/en/latest/_sources/usage/plugins/png.rst.txt

Command-line example showing how to specify two different slices for electrons using the --e_png.* flags. The order of flags is important; each setup must be given in sequence. No default values exist; if flags are not set, no PNGs are created.

```bash
picongpu [more args]
  # first
  --e_png.period 100
  --e_png.axis xy
  --e_png.slicePoint 0.5
  --e_png.folder pngElectronsXY
  # second
  --e_png.period 100
  --e_png.axis xz
  --e_png.slicePoint 0.5
  --e_png.folder pngElectronsXZ
```

--------------------------------

### Source the picongpu.profile environment

Source: https://picongpu.readthedocs.io/en/latest/install/profile.html

Run 'source $HOME/picongpu.profile' after logging in to set up the PIConGPU environment as configured in the profile.

```bash
source $HOME/picongpu.profile

```

--------------------------------

### Install requirements with pip install -r requirements.txt

Source: https://picongpu.readthedocs.io/en/latest/pypicongpu/faq.html

Install the project dependencies from the repository root. Run this command from the root directory of the repository.

```bash
pip install -r requirements.txt

```

--------------------------------

### pic-build --help output

Source: https://picongpu.readthedocs.io/en/latest/usage/basics.html

Full output of `pic-build --help`. Lists all options including -j, -b/--backend, -c/--cmake, -t, -f, -G, and -h. Must be run inside an input directory; default backend is cuda unless PIC_BACKEND is set.

```text
Build new binaries for a PIConGPU input set

Creates or updates the binaries in an input set. This step needs to
be performed every time a .param file is changed.

This tools creates a temporary build directory, configures and
compiles current input set in it and installs the resulting
binaries.
This is just a short-hand tool for switching to a temporary build
directory and running 'pic-configure ..' and 'make install'
manually.

You must run this command inside an input directory.

usage: pic-build [OPTIONS]

-j [N]                - allow N jobs at once; infinite jobs with no arg
-b | --backend        - set compute backend and optionally the architecture
                        syntax: backend[:architecture]
                        supported backends: cuda, hip, omp2b, serial, tbb, threads
                        (e.g.: "cuda:35;37;52;60" or "omp2b:native" or "omp2b")
                        default: "cuda" if not set via environment variable PIC_BACKEND
                        note: architecture names are compiler dependent
-c | --cmake          - overwrite options for cmake
                        (e.g.: "-DPIC_VERBOSE=21 -DCMAKE_BUILD_TYPE=Debug")
-t <presetNumber>     - configure this preset from cmakeFlags
-f | --force          - clear the cmake file cache and scan for new param files
-G <cmakeBuildSystem> - select the build system used by CMake, e.g. Ninja, ...
-h | --help           - show this help message
```

--------------------------------

### Cross-compile PIConGPU for RISC-V with environment setup and pic-build

Source: https://picongpu.readthedocs.io/en/latest/usage/crosscompile.html

Set up the environment for cross-compiling PIConGPU for RISC-V. First, export linker and compiler flags, including MPI paths and RISC-V architecture flags. Then set the toolchain installation roots for GNU or Clang. Finally, run pic-build with the provided CMake toolchain file and the -DMPI_CXX_WORKS=ON flag to disable CMake MPI detection.

```bash
# set MPI_ROOT to the root MPI directory
export LDFLAGS="-L$MPI_ROOT/lib -lmpi -lompitrace -lopen-rte -lopen-pal -ldl -lpthread -lutil -lrt"
# compile for 64bit RISC-V with double floating point support
export CXXFLAGS="-I$MPI_ROOT/include -pthread -march=rv64gc -mabi=lp64d"
export CFLAGS=$CXXFLAGS

```

```bash
export RISCV_GNU_INSTALL_ROOT="$(dirname $(which riscv64-unknown-linux-gnu-gcc))/.."
export RISCV_CLANG_INSTALL_ROOT="$(dirname $(which clang))/.."

```

```bash
# ``omp2b`` for OpenMP and ``serial`` for serial execution on one core
pic-build -b omp2b -c"-DMPI_CXX_WORKS=ON  -DCMAKE_TOOLCHAIN_FILE=<PATH_TO_PICONGPU_SRC>/cmake/riscv64-gnu.toolchain.cmake"

```

--------------------------------

### Install and Initialize pre-commit

Source: https://picongpu.readthedocs.io/en/latest/_sources/dev/docs/COMMIT.md.txt

Commands to install the required pre-commit dependencies and initialize the hooks in your local repository clone.

```bash
# set up a virtual environment if you prefer, then:
$ python3 -m pip install -r requirements_pre-commit.txt

# run this inside of your local clone of the repo:
$ pre-commit install
```

--------------------------------

### Install MPI

Source: https://picongpu.readthedocs.io/en/latest/install/dependencies.html

Installation commands for MPI and environment configuration.

```bash
sudo apt-get install libopenmpi-dev
sudo pacman --sync openmpi
spack install openmpi+cuda
spack install openmpi
export MPI_ROOT=<MPI_INSTALL>
export OMPI_MCA_mpi_leave_pinned=0
```

--------------------------------

### Install Rsync

Source: https://picongpu.readthedocs.io/en/latest/_sources/install/dependencies.rst.txt

Commands to install Rsync on various platforms.

```bash
sudo apt-get install rsync
sudo pacman --sync rsync
spack install rsync
```

--------------------------------

### Show available options with picongpu --help

Source: https://picongpu.readthedocs.io/en/latest/_sources/usage/basics.rst.txt

Displays all available runtime options for the current configuration after a successful pic-build run. The first line is emphasized in the source.

```bash
.build/picongpu --help
```

--------------------------------

### Show available runtime options with pic-build binary

Source: https://picongpu.readthedocs.io/en/latest/usage/basics.html

Lists all available runtime options for the built configuration. Must be run successfully after `pic-build` to reflect the current build.

```bash
.build/picongpu --help

```

--------------------------------

### Install Git

Source: https://picongpu.readthedocs.io/en/latest/_sources/install/dependencies.rst.txt

Commands to install Git on various platforms.

```bash
sudo apt-get install git
sudo pacman --sync git
spack install git
```

--------------------------------

### Install openPMD-api from source

Source: https://picongpu.readthedocs.io/en/latest/_sources/install/dependencies.rst.txt

Commands to clone, build, and install the openPMD-api library from source.

```bash
mkdir -p ~/src ~/lib
git clone -b 0.15.0 https://github.com/openPMD/openPMD-api.git ~/src/openPMD-api
cd ~/src/openPMD-api
mkdir build && cd build
cmake .. -DopenPMD_USE_MPI=ON -DCMAKE_INSTALL_PREFIX=~/lib/openPMD-api
make -j $(nproc) install
```