Starting a simulation

You are here: Home > PIConGPU User Documentation > Starting a simulation

---

This is a quick start guide on how to start a simulation using PIConGPU. For detailed installation and usage instructions, look here.

• PIConGPU enables detailed configuration of most simulation parameters. For performance reasons, most of these physics parameters must be set at compile time. As a result, you can not create a single PIConGPU binary and use it to start different types of simulations (but for multiple runs of the same simulation type, of course). Instead, you must re-compile if you change physical settings other than e.g. the area of simulation or the number of simulation processes.

• For now, we will start with one of the examples that ship with PIConGPU. It will be explained later how to modify examples to fit your own simulation needs.

Creating a parameter set

• Examples can be found in $PICSRC/examples/. We will use the $PICSRC/examples/LaserWakefield example here.

• You need to setup three directories next to the PIConGPU source tree. We will call them $PIC_BUILD, $PIC_PARAM and $PIC_RUNS

• Go to $PIC_BUILD and execute $PICSRC/createParameterSet $PICSRC/examples/LaserWakefield/ $PIC_PARAM/lw. This will create a copy of the LaserWakefield example configuration in $PIC_PARAM/lw.

Configuration

• Still in $PIC_BUILD, execute $PICSRC/configure $PIC_PARAM/lw. This will use cmake to configure our new configuration.
• A list of all available configuration flags can be found here.

Compilation

• If successful, just type make install. Since PIConGPU heavily relies on C++ templates, this might take a while, so be patient.
• Besides the picongpu binary, two other tools are compiled: cuda_memtest and mpiInfo. cuda_memtest will be run prior to PIConGPU in your job and test the target GPU device for memory problems.

Batch system submission

• At this point, we have a binary and configuration files for our example simulation in $PIC_PARAM/lw. Now, we want to actually start the simulation using another tool that ships with PIConGPU, tbg. It can be found in $PICSRC/src/tools/bin/tbg so it is easiest to add just add it to your PATH by executing export PATH=$PICSRC/src/tools/bin:$PATH.

• Whether you want to start your simulation on your local, CUDA-capable machine or on a cluster using its batch system determines how to use tbg. For this introduction, we will assume that your local machine (or the machine where you are building PIConGPU) has a CUDA-capable GPU.

• Go to $PIC_PARAM/lw and execute tbg -s bash -c submit/0001gpus.cfg -t submit/bash/bash_mpirun.tpl $PIC_RUNS/lw_test_01. Remenber to replace $PIC_RUNS with the appropriate directory path if you did not export it previously. This will start PIConGPU in your current bash instance.

Results

• Once the simulation run finishes, results can be found in $PIC_RUNS/lw_test_01/simOutput. For example, have a look at the generated PNG images in $PIC_RUNS/lw_test_01/simOutput/pngElectronsYX which show the laser pulse and the electron densities.

• Congratulations, you just finished your first PIConGPU simulation. Now go get some coffee, there is more to come!

Continue with "Configure an example".