Skip to content

PIConGPU Plugins

Jump to bottom Edit New page
Richard Pausch edited this page Apr 3, 2014 · 88 revisions

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
Intensity what is this?
LineSliceFields missing
LiveViewModule 3D live visualisation
ParticleDensity missing
ParticleSpectrum same as BinEnergyParticles - remove? @Heikman
PngModule pictures of 2D slices
PositionsParticles missing
Radiation compute emitted electromagnetic spectra
SliceFieldPrinter missing
SliceFieldPrinterMulti missing
SumCurrents missing
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 frequency 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.

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

LiveViewModule

What does this plugin compute?

3D Live visualization.

more information will follow soon.

How to set it up?

will come soon

References

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
 */
namespace radWindowFunctionRectangle { }
namespace radWindowFunctionTriangle { }

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.

References

Add a custom footer
Add a custom sidebar
Clone this wiki locally