PIConGPU User Documentation
You are here: Home > PIConGPU User Documentation
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/LaserWakefieldexample here. -
You need to setup three directories next to the PIConGPU source tree. We will call them
$PIC_BUILD,$PIC_PARAMand$PIC_RUNS -
Go to
$PIC_BUILDand 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/tbgso it is easiest to add just add it to your PATH by executingexport 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/lwand executetbg -s bash -c submit/0001gpus.cfg -t submit/bash/bash_mpirun.tpl $PIC_RUNS/lw_test_01. Remenber to replace$PIC_RUNSwith 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/pngElectronsYXwhich 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)
This section shows you how to modify example configurations to fit your own simulation needs, i.e. to set the physical parameters to want to investigate in a run. In general, PIConGPU has two types of configuration files, compile-time configuration and run-time configuration. As the names imply, you need to re-compile your simulation once you change any compile-time configuration while run-time configuration changes only require to re-submit it to the batch system.
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
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
.cfgfile. 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 Variablessection. Here you can modify or define new TBG variables for plugins. Directly below the existingTBG_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_pluginsvariable 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
pngplugin for electron densities (png_e) to create an image of the simulation area'syzaxis, at slice point 0.5 (50%) in the directorypngElectronsYZevery64timesteps. -
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_01simulation 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