PIConGPU Plugins

You are here: Home > PIConGPU User Documentation > PIConGPU Plugins

Plugin name	short description
ADIOS	stores simulation data as ADIOS files
BinEnergyParticles	energy histograms for electrons and ions
CountParticles	count macro particles
EnergyFields	electromagnetic field energy per time step
EnergyParticles	kinetic and total energies summed over all electrons and/or ions
FieldEnergy	missing @Heikman
HDF5	stores simulation data as libSplash-flavoured HDF5 files
Insituvolvis	3D live visualisation
Intensity	maximum and integrated electric field along the y-direction
LineSliceFields	missing
LiveViewModule	png based 2D live output
ParticleDensity	@Heikman
ParticleSpectrum	same as BinEnergyParticles - remove? @Heikman
PngModule	pictures of 2D slices
PositionsParticles	save trajectory, momentum, ... of a single particle
Radiation	compute emitted electromagnetic spectra
SliceFieldPrinter	missing
SliceFieldPrinterMulti	missing
SumCurrents	compute the total current summed over all cells
TotalDivJ	missing @Heikman (will be deleted)

ADIOS

What does this plugin do?

Stores simulation data such as fields and particles as ADIOS files. Files can be used for post-mortem analysis of the simulation data.

How to set it up?

You can use --adios.period and --adios.file to specify the output period and path and name of the created fileset. For example, --adios.period 128 --adios.file simData will write the simulation data to files of the form simData_0.bp, simData_128.bp in the default simulation output directory every 128 steps. Note that this plugin will only be available if ADIOS is found during compile configuration.

BinEnergyParticles

What does this plugin compute?

This plugin computes the energy histogram of both electrons and ions simulated with PIConGPU. The energy binning can be set up using comand line parameters. A virtual detector can be located in the y directon of the simulation to count only particles that would reach such a detector in an experimental setup. If the detector setup is not specified, all particles of a species are considered in the histogram.

How to set it up?

There are several command line parameters that can be used to set up this analyzer plugin. A list of all of associated flags for the electron species used in PIConGPU can be found below. All parameters apply also for the ion species. For setting up the ion histogram --bin_e. has to be replaced by --bin_i..

PIConGPU command line option	description
--bin_e.period	The ouput periodicity of the electron histogram. A value of 100 would mean aoutput at simulation time step 0, 100, 200, .... If set to a non-zero value, the energy histogram of all electrons is computed. By default, the value is 0 and no histogram for the electrons is computed.
--bin_e.binCount	Specifies the number of bins used for the electron histogram. Default is 1024.
--bin_e.minEnergy	Set the minimum energy for the electron histogram in keV. Default is 0, meaning 0 keV.
--bin_e.maxEnergy	Set the maximum energy for the electron histogram in keV. There is no default value. This has to be set by the user if --bin_e.period 1 is set.
--bin_e.distanceToDetector	Distance in meter of a electron detector located far away in y direction with slit opening in x and z direction. If set to non-zero value, only particles that would reach the detector are considered in the histogram. Default 0, meaning all particles are considered in the electron histogram and no detector is assumed.
--bin_e.slitDetectorX	Width of the electron detector in meter. If not set, all particles are counted.
--bin_e.slitDetectorZ	Hight of the electron detector in meter. If not set, all particles are counted.

Output and analysis tools

Output

The histograms are stored in ASCII files in the simOutput directory. The file for the electron histogram is named BinEnergyElectrons.dat and the file for the ion histogram is named BinEnergyIons.dat. The first line of these files does not contain histogram data and is commented-out using #. It describes the energy binning that needed to interpret the following data. It can be seen as the head of the following data table. The first column is an integer value describing the simulation time step. The second column counts the number of real particles below the minumum energy value used for the histogram. The following columns give the real electron count of the particles in the specific bin described by the first line/header. The second last column gives the number of real particles that have a higher energy than the maximum energy used for the histogram. The last column gives the total number of particles. In total there are 4 columns more than the number of bins specified with command line arguments. Each row describes another simulation time step.

Analysis Tools

PIConGPU comes with a command line analysis tool for the energy histograms. It is based on gnuplot and requires that gnuplot is available via command line. The tool can be found in src/tools/bin/ and is called BinEnergyPlot.sh. It accesses the gnuplot script BinEnergyPlot.gnuplot in src/tools/share/gnuplot/. BinEnergyPlot.sh requires exactly three command line arguments:

Argument	Value
1st	Path and filename to BinEnergyElectrons.dat or BinEnergyIons.dat file.
2nd	Simulation time step (needs to exist)
3rd	Label for particle count used in the graph that this tool produces.

Known Issues

Currently, the files BinEnergyElectrons.dat and BinEnergyIons.dat are overwritten when restarting the simulation. Therefore, all previously stored histograms are lost.

CountParticles

What does this plugin compute?

This plugin counts the total number of macro particles associated with electrons and writes them to a file for specified time steps. It is used mainly for debugging purposes. Only in case of constant particle density, where each macro particle describes the same number of real particles (weighting), conclusions on the plasma density can be drawn.

How to set it up?

The CountParticles plugin is always complied for electron-like macro particles. By specifying the perodicity of the output using the comand line argument --elec_cnt.period with picongpu, the plugin is enabled. Setting --elec_cnt.period 100 adds the number of all electron like macro particles to the file ElectronsCount.dat for every 100th time step of the simulation.

Output

In the output file ElectronsCount.dat, there are three columns. The first is the integer number of the time step. The second is the number of macro particles as integer - useful for exact counts. And the third is the number of macro particles in scintific floating point notation - provides better human readability.

Known Issues

Currently, the file ElectronsCount.dat is overwritten when restarting the simulation. Therefore, all previously stored counts are lost.

##EnergyFields

What does this plugin compute?

This plugin computes the total energy contained in the electric and magnetic field of the entire volume simulated. The energy is computed for user specified time steps.

How to set it up?

By setting the PIConGPU command line flag --energy_fields.period to a non-zero value the plugin computes the total field energy. The default value is 0, meaning that the total field energy is not stored. By setting e.g. --energy_fields.period 100 the total field energy is computed for time steps 0, 100, 200, ....

Output

The data ist stored in EnergyFields.dat. There are two columns. The first gives the time step. The second is the total field energy in Joule. The first row is a comment describing the columns:

#step Joule

Known Issues

Currently, the output file is overwritten after restart.

EnergyParticles

What does this plugin compute?

This plugin computes the kinetic and total energy summed over all particles of a species (electrons and/or ions) for time steps specified.

How to set it up?

Only the time steps at which the total kinetic energy of all particles should be specified needs to be set via command line argument.

PIConGPU command line option	description
--energy_e.period	Sets the time step period at which the energy of all electrons in the simulation should be simulated. If set to e.g. 100, the energy is computed for time steps 0, 100, 200, .... The default value is 0, meaning that the plugin does not compute the particle energy.
--energy_i.period	Same as above, but for ions.

Output

The plugin create the file EnergyElectrons.dat for the electron energies and EnergyIons.dat for the ions energies. The file contains a header describing the columns.

#step Ekin_Joule E_Joule

Following the header, each line is the output of one time step. The time step is given as first value. The second value is the kinetic energy of all particles at that time step. And the last value is the total energy (kinetc+rest energy) of all particles at that time step.

Known Issues

Currently, the output file is overwritten after restart.

HDF5

What does this plugin do?

Stores simulation data such as fields and particles along with domain information, conversion units etc. as HDF5 files. It uses libSplash for writing HDF5 data. It is used for post-simulation analysis and for restarts of the simulation after a crash or an intended stop.

How to set it up?

You can use --hdf5.period and --hdf5.file to specify the output period and path and name of the created fileset. For example, --hdf5.period 128 --hdf5.file simData will write the simulation data to files of the form simData_0.h5, simData_128.h5 in the default simulation output directory every 128 steps. In order to restart a simulation from an existing hdf5 data dump (stored in the files specified by --hdf5.file), the user needs to set the flag --hdf5.continue. Note that this plugin will only be available if libSplash and HDF5 is found during compile configuration.

Insituvolvis

What does this plugin compute?

3D Live visualization.

currently not in the public omain of PIConGPU - will be added soon. more information will follow soon.

How to set it up?

will come soon

References

• In Situ Visualization of a Laser-Plasma Simulation

Intensity

What does this plugin compute?

The maximum amplitude of the electric field for each cell in y-cell-position in V/m and the integrated amplitude of the electric field (integrated over the entirer x- and z-extent of the simulated volume and given for each y-cell-position).

There might be an error in the units of the integrated output.

A renaming of this plugin would be very useful in order to understand its purpose more intuitively.

How to set it up?

By setting the PIConGPU command line flag --intensity.period to a non-zero value the plugin computes the maximum electric field and the integrated electric field for each cell-wide slice in y-direction. The default value is 0, meaning that nothing is computed. By setting e.g. --intensity.period 100 the electric field analysis is computed for time steps 0, 100, 200, ....

Output

The output of the maximum electric field for each y-slice is stored in Intensity_max.dat. The output of the integrated electric field for each y-slice is stored in Intensity_integrated.dat.

Both files have two header rows describing the data.

#step position_in_laser_propagation_direction
#step amplitude_data[*]

The following odd rows give the time step and then describe the y-position of the slice at which the maximum electric field or integrated electric field is computed. The even rows give the time step again and then the data (maximum electric field or integrated electric field) at the positions given in the previews row.

Known Issues

Currently, the output file is overwritten after restart. Additionally, this plugin does not work with non-regular domains, see here. This will be fixed in a future version.

There might be an error in the units of the integrated output.

LiveViewModule

What does this plugin compute?

2D slices of the simulation that can be viewed live using a client program more information will follow soon.

How to set it up?

will come soon

PngModule

What does this plugin compute?

This plugin generates images in the png format for slices through the simulated volume. It allows to draw either ion or electron density togeter with electric, magnetic and/or current field values. The exact field values, their coloring und their normalization can be set using *.param files. It is a very rudimental and useful tool to get a first impression on what happens in the simulation and to verify that the parameter set choosen leads to the desired physics.

In the near future, this plugin might be replaced by the insituvolvis live and interactive 3D visualization.

How to set it up?

Command line arguments

For electrons the following table describes the command line arguments used for the visualization. For ions the --png_e.has to be replaced with --png_i.. Next to the command line arguments, the two param files visualization.param and visColorScales.param are used to specify the desired output.

PIConGPU command line option	description
--png_e.period	This flag requires an integer value that specifies at what periodicity the png pictures should be created. E.g. setting --png_e.period 100 generates images for the 0th, 100th, 200th, ... time step. There is no default. If flags are not set, no pngs are created.
--png_e.axis	Set 2D slice through 3D volume that will be drawn. Combine two of the three diemsion x, yand z, the define a slice. E.g. setting --png_e.axis yz draws both the y and z dimesion and performes a slice in x-direction.
--png_e.slicePoint	Specifies at what ratio of the totel depth of the remaining dimenson, the slice should be performed. The value given shoulf lie between 0.0and 1.0.
--png_e.folder	Name of the folder, where all pngs for the above setup should be stored.

These flags use boost::program_options's multitoken(). Therefore, several setups can be specified e.g. to draw different slices. The order of the flags is imporant in this case. E.g. in the following example, two diffent slices are visualized and stored in different directories:

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

Specifing the field values using visualization.param

Depending on the used pefix in the command line flags, electron and/or ion density is drawn. Additionally to that, three field values can be visualized together with the particle density. In order to set up the visulzed field values, the visualization.param needs to be changed. In this file, a variety of other parameters used for the PngModule can be specified.

The ratio of the image can be set.

/*scale image before write to file, only scale if value is not 1.0
 */
const double scale_image = 1.0;

/*if true image is scaled if cellsize is not quadratic, else no scale*/
const bool scale_to_cellsize = true;

In order to scale the image, scale_to_cellsizeneeds to be set tu true and scale_image needs to specify the x/y ratio of the image.

not shure if scale_image specifies x/y or y/x ratio

There are three field values that can be drawn: CHANNEL1, CHANNEL2 and CHANNEL3.

Since an adequate color scaling is essential, there several option the user can choose from.

// normalize EM fields to typical laser or plasma quantities
//-1: Auto: enable adaptive scaling for each output
// 1: Laser: typical fields calculated out of the laser amplitude
// 2: Drift: typical fields caused by a drifting plasma
// 3: PlWave: typical fields calculated out of the plasma freq.,
// assuming the wave moves approx. with c
// 4: Thermal: typical fields calculated out of the electron temperature
// 5: BlowOut: typical fields, assuming that a LWFA in the blowout
// regime causes a bubble with radius of approx. the laser's
// beam waist (use for bubble fields)
#define EM_FIELD_SCALE_CHANNEL1 -1
#define EM_FIELD_SCALE_CHANNEL2 -1
#define EM_FIELD_SCALE_CHANNEL3 -1

In the above example, all channels are set to auto scale. Be careful, when using other narmalizations than auto scale, because depending on your set up, the normalization might fail due to parameters not set by PIConGPU. *Use the other normalization options only in case of the specified scenarios or if you know, how the scaling is computed. *

You can also add opacity to the particle density and the three field values:

// multiply highest undisturbed particle density with factor
const float_X preParticleDens_opacity = 0.25;
const float_X preChannel1_opacity = 1.0;
const float_X preChannel2_opacity = 1.0;
const float_X preChannel3_opacity = 1.0;

and add different coloring:

// specify color scales for each channel
namespace preParticleDensCol = colorScales::red;  /* draw density in red */
namespace preChannel1Col = colorScales::blue;     /* draw channel 1 in blue */
namespace preChannel2Col = colorScales::green;    /* draw channel 2 in green */
namespace preChannel3Col = colorScales::none;     /* do not draw channel 3 */

The colors available are defined in visColorScales.param and their usage is described below. If colorScales::noneis used, the channel is not drawn.

In order to specify what the three channels represent, three functions can be defined in ``. The define the values computed for the png visualization. The data structures used are those available in PIConGPU.

/* png preview and liveview settings for each channel */
DINLINE float_X preChannel1(const float3_X& field_B, const float3_X& field_E, const float3_X& field_J)
{
    /* Channel1 
     * computes the absolute value squared of the electric current */
    return math::abs2(field_J);
}

DINLINE float_X preChannel2(const float3_X& field_B, const float3_X& field_E, const float3_X& field_J)
{
    /* Channel2 
     * computes the square of the x-component of the electric field */
    return field_E.x() * field_E.x();
}

DINLINE float_X preChannel3(const float3_X& field_B, const float3_X& field_E, const float3_X& field_J)
{
    /* Channel3
     * computes the negative values of the y-component of the electric field
     * positiv field_E.y() return as negative values and are NOT drawn */
    return -float_X(1.0) * field_E.y();
}

Only positiv values are drawn. Negative values are clipped to zero. In the above example, this feature is used for preChannel3.

Defining coloring schemes in visColorScales.param

There are several predifined color schemes available:

• none (do not draw anything)
• gray
• grayInv
• red
• green
• blue

But the user can also specify his or her own color scheme by defining a namespace with the color name that provides an addRGBfunction:

        namespace NameOfColor /* name needs to be unique */
        {
            HDINLINE void addRGB( float3_X& img, /* the already existing image */
                                  const float_X value, /* the value to draw */
                                  const float_X opacity ) /* the opacity specified */
            {
                /* myChannel specifies the color in RGB values (RedGreenBlue) with
                 * each value ranging from 0.0 to 1.0 .
                 * In this example, the color yellow (RGB=1,1,0) is used. */
                const float3_X myChannel( 1.0, 1.0, 0.0 );

/* here, the previously calculated image (in case, other channels have already 
 * contributed to the png) is changed.
 * First of all, the total image intensity is reduced by the opacity of this
 * channel, but only in the color channels specified by this color "NameOfColor".
 * Then, the actual values are added with the correct color (myChannel) and opacity. */ 
                img = img 
                      - opacity * float3_X( myChannel.x() * img.x(),
                                            myChannel.y() * img.y(),
                                            myChannel.z() * img.z() )
                      + myChannel * value * opacity;
            }
        }

For most cases, using the predefined colors should be enough.

Output

The ouput of this plugin are pngs stored in the directories specified by --png_e.folder or --png_i.folder. There can be as many of these folders as the user wants. The pngs follow a naming convention:

PngImageElectrons_yx_0.5_002000.png

First, either PngImageElectrons or PngImageIons specify the particle type. Following the underscore, the drawn dimensions are given. Then the slice ratio, specified by --png_e.slicePointor --png_i.slicePoint, is stated in the file name. The last part of the file name is a 6 digit number, specifing the simulation time step, at which the picture was created. This naming convention allows to put all pngs in one directory and still be able to identify them correctly.

PositionsParticles

What does this plugin compute?

This plugin prints out the position, momentum, mass, macro particle weighting, electric charge and relativistic gamma factor of one electron simulated with PIConGPU. It only works with one particle.

How to set it up?

By setting the command line flag --pos_e.period to a non-zero number, the analyzer is used. In order to get the particle trajectory for each time step the period needs to be set to 1, meaning --pos_e.period 1. If less output is needed, e.g. only every 10th time step, the period can be set to different values, e.g. --pos_e.period 10.

Output

The electron trajectory is written directly to the standard out. Therefore, it goes both to ./simOutput/outputas well as to the output file specified by the machine used (usually the stdout file in the main directory of the simulation). The output is ASCII-text only. It has the following format:

[ANALYSIS] [_rank] [COUNTER] [_analyzerName] [_currentTimeStep] _currentTime {_position.x _position.y _position.z} {_momentum.x _momentum.y _momentum.z} _mass _weighting _charge _gamma

Value	Description	Unit
_rank	MPI rank at which prints the particle position	none
_analyzerName	name of the plugin	always PositionsElectrons
_currentTimeStep	simulation time step = number of PIC cycles	none
_currentTime	simulation time in SI units	seconds
_position.x _position.y _position.z	location of the particle in space	meter
_momentum.x _momentum.y _momentum.z	momentum of particle	kg* m/s
_mass	mass of macro particle	kg
_weighting	number of electrons represented by the macro particle	none
_charge	charge of macro particle	Coulomb
_gamma	relativistic gamma factor of particle	none

# an example output line:
[ANALYSIS] [2] [COUNTER] [PositionsElectrons] [878] 1.46440742e-14 {1.032e-05 4.570851689815522e-05 5.2e-06} {0 -1.
337873603181226e-21 0} 9.109382e-31 1 -1.602176e-19 4.999998569488525

In order to extract only the trajectory informations from the total output stored in stdout, the following command on a bash command line could be used:

grep PositionsElectrons stdout > trajectory.dat

The particle data is then stored in trajectory.dat.

Warning

This plugin only works correctly if a single particle is simulated. If more than one particle is simulated, the output becomes random, because only the information of one particle is printed.

Perhaps, with the introduction of more particle species, this plugin might be upgraded to work with multiple particles.

Known Issues

Currently, both output and stdoutare overwritten at restart. All data from the plugin is lost, if these file are not backuped manually.

Radiation

What does this plugin compute?

The spectrally resolved far field radiation of charged macro particles (usually only electrons).

Our simulation computes the Liénard Wiechert potentials to calculate the emitted electromagnetic spectra for different observation directions.

$$ \frac{\operatorname{d}^2I}{\operatorname{d}\Omega \operatorname{d} \omega} \left( \omega, \vec n \right) $$

Currently this allows to predict the emitted radiation from plasmas if it can be described by classical means. Not considered are emissions from ionization, Compton scattering or any bremsstrahlung that originate from scattering on scales smaler than the PIC cell size.

more information will follow soon.

How to set it up?

In order to setup the radiation analyzer plugin, both the radiationConfig.param and the observer.hpp have to be configured. In radiationConfig.param, the number of frequencies N_omegaand observation directions N_theta is defined.

Frequency range

The frequency range is set up by choosing a specific namespace that defines the frequency setup

namespace radiation_frequencies = rad_linear_frequencies; /* choose linear frequency range */

Currently you can choose from the following setups for the frequency range:

namespace	description
rad_linear_frequencies	linear frequency range from SI::omega_minto SI::omega_max with N_omega steps
rad_log_frequencies	logarithmic frequency range from SI::omega_minto SI::omega_max with N_omega steps
rad_frequencies_from_list	N_omega frequencies taken from a text file with location listLocation[]

Observation directions

The number of observation directions N_theta is defined in radiationConfig.param, but the distribution of observation directions is given in observer.hpp There, the function DINLINE vec2 picongpu::radiation_observer::observation_direction(const int theta_id_extern) defines the observation directions.

This function returns the x,y and z component of a unit vector pointing in the observation direction.

DINLINE vec2 observation_direction(const int theta_id_extern)
{
  /* use the scalar index theta_id_extern to compute an 
     observation direction (x,y,y) */
  return vec2( x , y , z ) ;
}

The observer.hpp set up will be subject to further changes. These might be namespaces that describe several preconfigured layouts or a functor if C++ 11 is included in the nvcc.

Nyquist limit

A major limitation of discrete Fourer transform is the limited frequeny resolution due to the discrete time steps of the temporal signal. (see Nyquist-Shannon sampling theorem) Due to the consideration of relativitic delays, the sampling of the emitted radiation is not equidistantly sampled. The plugin has the option to ignore any frequency contributions that lies above the frequeny resolution given by the Nyquist-Shannon sampling theorem. Because performing this check costs computation time, it can be swithched off. This is done via a precomiler pragma:

// Nyquist low pass allows only amplitudes for frequencies below Nyquist frequency
// 1 = on (slower and more memory, no fourier reflections)
// 0 = off (faster but with fourier reflections)
#define __NYQUISTCHECK__ 0

Additionally, the maximally resolvable frequency compared to the Nyquist frequency can be set.

namespace radiationNyquist
{
  const float NyquistFactor = 0.5; /* only use frequencies below 1/2*Omega_Nyquist */
}

This allows to make a save margin to the hard limit of the Nyquist frequency. By using NyquistFactor = 0.5 for periodic boundary conditions, particles that jump from one border to another and back can still be considered.

Form factor

The form factor is an estill xperimental method trying to consider the shape of the macro particles when computing the radiation. By default, it should be switsched off by setting __COHERENTINCOHERENTWEIGHTING__ to zero.

// corect treatment of coherent and incoherent radiation from macroparticles
// 1 = on (slower and more memory, but correct quantitativ treatment)
// 0 = off (faster but macroparticles are treated as highly charged, point-like particle)
#define __COHERENTINCOHERENTWEIGHTING__ 0

If switsched on, one can select between different marco particle shapes. Currently three shapes are implemented. A shape can be selected by choosing one of the available namespaces:

namespace radFormFactor_selected = radFormFactor_CIC_3D; /* choosing the 3D CIC-like macro particle shape*/

namespace	description
radFormFactor_CIC_3D	3D Cloud-In-Cell shape
radFormFactor_CIC_1Dy	Cloud-In-Cell shape in y-direction, dot like in the other directions
radFormFactor_incoherent	forces a completly incoherent emission by scaling the macro particle charge with the square root of the weighting

possibly more shapes (f.e. spaghetti shape) will be added

Reducing the particle sample

In order to save computation time, only a random subset of all macro marticles can be used to compute the emitted radiation. The fraction of particles that contribute to the radiation can be specified by setting the precompiler variable RAD_MARK_PARTICLE. Only every RAD_MARK_PARTICLE's particle is contributing to the spectra.

//marked every N particle for calculate radiation
//mark no particle at beginning
#define RAD_MARK_PARTICLE 20
/* every 20th macroparticle has the radiation flag 
   set and contributes to the radiation */

The reduction of the total intensity is not considered in the output. The intensity will be (in the incoherent case) by 1/RAD_MARK_PARTICLE smaler than in the case of selecting all particles.

The radiation flag is only added to particles, if RAD_MARK_PARTICLE ≠ 1. Adding the radiation falg costs memory.

In future updates, the radiation will only be computed using an extra particle species. Therefore, this setup will be subject to further changes.

Gamma filter

Additionally, a simple filter to only consider particles above a specified energy threshold can be selected by setting RAD_ACTIVATE_GAMMA_FILTER to 1.

//disable or enable gamme filter
//diable (0) / enable (1)
#define RAD_ACTIVATE_GAMMA_FILTER 0

A minimum ralativistic gamma factor can be specified by setting RadiationGamma.

const float RadiationGamma = 5.; /* only consider particles with gamma ≥ 5*/

More sophisticated filters might come in the near future. Therefore, this part of the code might be subject to changes.

Window function filter

A window function can be added to the simulation area to reduce ringing artifacts due to sharp transition from radiating regions to non-radiating regions at the boundaries of the simulation box. This should be applied to simulation setups where the entire volume simulated is radiationg (e.g. Kelvin-Helholtz Instability).

In radiationConfig.param the precompiler variable PIC_RADWINDOWFUNCTION defines if the window function filter should be used or not.

// add a window function weighting to the radiation in order
// to avoid ringing effects from sharpe boundaries
// 1 = on (slower but with noise/ringing reduction)
// 0 = off (faster but might contain ringing)
#define PIC_RADWINDOWFUNCTION 0

If set to 1, the window function filter is used.

There are several different window function availabe:

/* Choose different window function in order to get better ringing reduction
 * radWindowFunctionRectangle
 * radWindowFunctionTriangle
 * radWindowFunctionHamming
 * radWindowFunctionTriplett
 * radWindowFunctionGauss
 */
namespace radWindowFunctionRectangle { }
namespace radWindowFunctionTriangle { }
namespace radWindowFunctionHamming { }
namespace radWindowFunctionTriplett { }
namespace radWindowFunctionGauss { }

namespace radWindowFunction = radWindowFunctionTriangle;

By setting radWindowFunction a specific window function is selected.

Command line arguments

PIConGPU command line option	description
--radiation_e.period	Gives the number of time steps between which the radiation should be calculated. Default is 0, which means that the radiation in never calculated and therfore off. Using 1 calculates the radiation constantly. Any value ≥2 is currently producing nonsense.
--radiation_e.dump	Period, after which the calculated radiation data should be dumped to the file system. Default is 0, therfore never. In order to store the radiation data, a value ≥1 should be used.
--radiation_e.lastRadiation	If set to 1, the radiation spectra summed between the last and the current dump-time-step are stored. Default 0. Used for a better evaluation of the temporal evolution of the emitted radiation.
--radiation_e.folderLastRad	Name of the folder, in which the summed spectra for the simulation time between the last dump and the current dump are stored. Default is lastRad.
--radiation_e.totalRadiation	If set to 1 the spectra summed from simulation start till current time step are stored. Default: 0, no integrated (totalRad) spectra are stored.
--radiation_e.folderTotalRad	Folder name in which the total radiation spectra, integrated from the beginning of the simulation, are stored. Default totalRad.
--radiation_e.start	Time step, at which PIConGPU starts calculating the radition. Default is 2in order to get enough history of the particles.
--radiation_e.end	Time step, at which the radiation calculation should end. Default: 0(stopps right away).
--radiation_e.omegaList	In case the frequencies for the spectrum are comming from a list stored in a file, this gives the path to this list. Default: _noPath_ throws an error. This does not switch on the frequency calculation via list.
--radiation_e.radPerGPU	If set to 1, each GPU additionally stores its own spectra without summing over the entire simulation area. This allows for a localisation of specific spectral features. Default: 0.
--radiation_e.folderRadPerGPU	Name of the folder, where the GPU specific spectras are stored. Default: radPerGPU
--radiation_e.restart	If set to 1, the amplitudes stored for restart are used to inizalised the spectra in order to continue a stopped/crashed simulation. Default is 0, which means the amplitudes are iniziled with zero.

Output and analysis tools

Output

Depending on the comand line options used, there are different output files.

Command line flag	Output description
--radiation_e.totalRadiation 1	Conatins ASCII files that have the total spectral intensity until the timestep specified by the filename. Each row gives data for one observation direction (same order as specified in the observer.py). The values for each frequency are seperated by tabs and have the same order as specified in radiationConfig.param. The spectral intensity is stored in the units [J·s].
--radiation_e.lastRadiation 1	has the same format as the output of totalRadiation. The spectral intensity is only summed over the last radiation dump period.
--radiation_e.radPerGPU 1	Same output as totalRadiation but only summed over each GPU. Because each GPU specifies a spatial region, the origin of radiation signatures can be distinguished.
Restart data	In the folder radRestart, binary data for each radiation dump are stored. These are complex amplitudes in units used by PIConGPU. These are for restart purposes. But can be used to analyse the phase of the emited radiation as well. Tools for this are developed in gbAnalysis.

Analysing tools

In picongp/src/tools/bin, there are tools to analyse the radiation data after the simulation.

Tool	Description
plotRadiation	Reads ASCII radiation data and plots spectra over angles as color plots. This is a python script that has its own help. Run plotRadiation --helpfor more informations.
radiationSyntheticDetector	Reads ASCII radiation data and statistically analysis the spectra for a user specified region of observation angles and frequencies. This is a python script that has its own help. Run radiationSyntheticDetector --helpfor more informations.
smooth.py	Python module needed by plotRadiation.

Known Issues

Currently, the radiation plugin does not support 2D simulations. This should be fixed with issue #289

References

• Electromagnetic Radiation from Relativistic Electrons as Characteristic Signature of their Dynamics
  Diploma thesis on the radiation plugin
• How to test and verify radiation diagnostics simulations within particle-in-cell frameworks
  Some tests that have been performed to validate the code

SumCurrents

What does this plugin compute?

This plugin computes the total current integrated/added over the entire volume simulated.

How to set it up?

The plugin can be activated by setting a non-zero value with the command line flag --sumcurr.period. The value set with --sumcurr.period is the periodicity, at which the total current is computed. E.g. --sumcurr.period 100 computes and prints the total current for time step 0, 100, 200, ....

Output

The result is printed to standard output. Therefore, it goes both to ./simOutput/outputas well as to the output file specified by the machine used (usually the stdout file in the main directory of the simulation). The output is ASCII-text only. It has the following format:

[ANALYSIS] [_rank] [COUNTER] [SumCurrents] [_currentTimeStep] {_current.x _current.y _current.z} Abs:_absCurrent

Value	Description	Unit
_rank	MPI rank at which prints the particle position	none
_currentTimeStep	simulation time step = number of PIC cycles	none
_current.x _current.y _current.z	electric current	Ampere per second
_absCurrent	magnitude of current	Ampere per second

In order to extract only the total current information from the output stored in stdout, the following command on a bash command line could be used:

grep SumCurrents stdout > totalCurrent.dat

The plugin data is then stored in totalCurrent.dat.

Known Issues

Currently, both output and stdoutare overwritten at restart. All data from the plugin is lost, if these file are not backuped manually.