PIConGPU User Documentation

You are here: Home > PIConGPU User Documentation

1. Starting a simulation
2. Configure an example
3. Particle Attributes
4. Plugins
5. Post-Processing

---

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.

• 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.

• Still in $PIC_BUILD, execute $PICSRC/configure $PIC_PARAM/lw. This will use cmake to configure our new configuration.

• If successful, just type make install. Since PIConGPU heavily relies on C++ templates, this might take a while so be patient.

• 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.

• 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.

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

---

Configure an example (where to get files from, how to modify work flow)

---

Particle Attributes

From #142

What particle attributes are there and how can they be accessed?

• a picturesque "tree" of all the available namespaces,a short explanation of their substructure and where to find what

---

Plugins:

This section introduces PIConGPUs plugin system and will show you how to setup a plugin for your simulation. There is also a comprehensive summary which lists all available plugins. It is recommended to read the Starting a Simulation section first.

• Plugins provide an important part of PIConGPUs functionality, next to the core functions provided. However, most plugins are not mandatory to run a simulation and can be added or removed, depending on which features you want to use in your simulation run.

• This tutorial will show you how to setup the PNG plugin which creates images of 2D slices of the simulation area.

• The first step to use a plugin is making sure that PIConGPU compiles with the plugin enabled. Most plugins that ship with PIConGPU are enabled in the code by default, given that required includes and libraries (if any) are found during compile configuration. Plugin source code can be found under $PICSRC/src/picongpu/include/plugins/.

• For this example, you will need pngwriter. Installation instructions can be found in INSTALL.md. When pngwriter is found during compile configuration, the plugin is enabled for compilation automatically in PluginController.hpp.

• Which plugins are used at runtime can be configured in your simulation's .cfg file. Let us assume you installed your LaserWakefield simulation in $PIC_PARAM/lw/ as described here, the configuration file would be $PIC_PARAM/lw/submit/0001gpus.cfg.

• Open the file and go to the Optional Variables section. Here you can modify or define new TBG variables for plugins. Directly below the existing TBG_pngYX, define a new variable: TBG_pngXZ="--png_e.period 64 --png_e.axis yz --png_e.slicePoint 0.5 --png_e.folder pngElectronsYZ".

• Now, we need to tell PIConGPU to actually use our new variable. To do this, add it to the TBG_plugins variable in the same file like this:

TBG_plugins="!TBG_pngYX \
             !TBG_pngYZ \
             !TBG_binaryDensity \
             --elec_cnt.period 100"

• The variable defines that you want to use the png plugin for electron densities (png_e) to create an image of the simulation area's yz axis, at slice point 0.5 (50%) in the directory pngElectronsYZ every 64timesteps.

• When you start a new simulation run, PIConGPU will recognize this plugin setting and create png images in the simOutput directory of your lw_test_01 simulation run: $PIC_RUNS/lw_test_01/simOutput/pngElectronsYZ.

---

HDF5 Parallel Post-Processing and Visualization

• Parallel Rendering and Analysis with ParaView
• Parallel Rendering and Analysis with VisIt
• Parallel Analysis with IPython Notebook