PIConGPU User Documentation

You are here: Home > PIConGPU User Documentation

---

1. 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!

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

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

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

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

• ...

From #142 Extensive documentation of the plug-ins.

5. HDF5 Parallel Post-Processing and Visualization

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