openPMD extension name: ED-PIC
This extension is specifically designed for the domain of electro-dynamic and electro-static particle-in-cell (PIC) codes.
The current version of this extension is suitable to allow the output of arbitrary simulation codes to be post-processed and compared with common tools and frameworks. Future versions will define a common set of required records and further attributes (e.g., for moving window and boosted frame simulations) that will allow to restart the checkpoints of one PIC code with an other.
This extension depends on the ParticleWeighting extension.
It is sufficient for writers to only declare the ED-PIC extension to express this dependency. Thus, reading implementations need to be aware that a declared ED-PIC extension implies ParticleWeighting is also applied.
The following additional attributes are defined to this extension.
The individual requirement is given in scope.
-
fieldSolver- type: (string)
- scope: required
- description: Maxwell/field solver
- allowed values:
Yee(doi:10.1109/TAP.1966.1138693)CK(Cole-Karkkainen type solvers: doi:10.1016/j.jcp.2011.04.003, doi:10.1063/1.168620, doi:10.1109/TAP.2002.801268; M. Karkkainen et al., Low-dispersion wake field calculation tools, ICAP 2006)Lehe(doi:10.1103/PhysRevSTAB.16.021301)DS(Directional Splitting after Yasuhiko Sentoku, doi:10.1140/epjd/e2014-50162-y)PSTD(Pseudo-Spectral Time Domain, e.g., Q. H. Liu, Letters 15 (3) (1997) 158–165)PSATD(Pseudo-Spectral Analytical Time Domain, I. Haber, R. Lee, H. Klein, J. Boris, Advances in electromagnetic simulation techniques, 1973)GPSTDothernone
-
fieldSolverParameters- type: (string)
- scope: required if
fieldSolverisotherorGPSTD, optional otherwise - description: additional scheme and parameters specification for fields solvers
-
fieldBoundary- type: array of (string) of length 2
N - scope: required
- description: boundary conditions in each direction (in the
above,
Nis the dimensionality of the field mesh) ; the strings are stored in the following order:- boundary at the lower end of the first axis as in
axisLabels - boundary at the upper end of the first axis as in
axisLabels - boundary at the lower end of the second axis as in
axisLabels - boundary at the upper end of the second axis as in
axisLabels - ...
- boundary at the upper end of the last axis as in
axisLabels
- boundary at the lower end of the first axis as in
- allowed values:
periodicopen(optionally add scheme specification, such as PML, Silver-Muller, etc., in thefieldBoundaryParametersstring)reflecting(optionally add scheme specification, such as Neumann-type or Dirichlet-type, in thefieldBoundaryParametersstring)other
- type: array of (string) of length 2
-
fieldBoundaryParameters- type: array of (string) of length 2
N - scope: required if
fieldBoundaryisother, optional otherwise - description: additional scheme and parameters specification for the boundary conditions
- type: array of (string) of length 2
-
currentSmoothing- type: (string)
- scope: required
- description: applied filters to the current field after the particles' current deposition
- note: may becomes a particle record attribute in the future
- allowed values:
Binomialothernone
-
currentSmoothingParameters- type: (string)
- scope: required if
currentSmoothingis notnone - description: additional parameters to describe the applied filter further
- note: may becomes a particle record attribute in the future
- example:
period=10;numPasses=4;compensator=true - reserved for future use:
direction=array(),stride=array()
-
chargeCorrection- type: (string)
- scope: required
- description: applied corrections to fields to ensure charge conservation
- allowed values:
Marder(doi:10.1016/0021-9991(87)90043-X)Langdon(doi:10.1016/0010-4655(92)90105-8)Boris(Birdsall & Langdon, Plasma Physics via Computer Simulation, 15-6)hyperbolic(section III-B in doi:10.1063/1.872648, doi:http://dx.doi.org/10.1006/jcph.2000.6507, section 2.3 in doi:10.1016/S0920-3796(96)00502-9)spectral(various)othernone
-
chargeCorrectionParameters- type: (string)
- scope: required if
chargeCorrectionis notnone - description: additional parameters to describe the charge correction parameter
- example:
period=100
The following additional attributes for mesh records are defined in this
extension. The individual requirement is given in scope.
-
fieldSmoothing- type: (string)
- scope: required
- description: applied field filters for E and B
- allowed values: same as for
currentSmoothing
-
fieldSmoothingParameters- type: (string)
- scope: required if
fieldSmoothingis notnone - description: additional parameters to describe the applied filter
further (similar to
currentSmoothingParameters)
When added to an output, the following naming conventions shall be used for
mesh records to allow an easy the identification of essential fields. If
these namings are not used, tools might still detect a record by it's
unitDimension as, e.g., an electric field but not as the main electric
field that should be distributed again on the cells.
-
fundamental fields:
E- type: (floatX) or (intX) or (uintX)
- description: the electric field
- advice to implementors: a (floatX) type is likely the most frequent case for this record
- advice to implementors: must have
unitDimension = (1., 1., -3., -1., 0., 0., 0.)(V/m = kg * m / (A * s^3))
B- type: (floatX) or (intX) or (uintX)
- description: the magnetic field
- advice to implementors: must have
unitDimension = (0., 1., -2., -1., 0., 0., 0.)(T = kg / (A * s^2)) - advice to implementors: a (floatX) type is likely the most frequent case for this record
-
auxiliary fields:
-
fields derived from particle species, discretized on the mesh (cells): prefix them with
<particleSpecies>_*:- defined names and examples:
J: such aselectron_Jfor current densities created by the particles in particle specieselectrondensity: such aselectron_density(elements per volume/area/line)chargeDensity: such aselectron_chargeDensity(charge per volume/area/line)particleEnergy: kinetic energy of all particles, with their weighted contribution to a cellenergyDensity: same asparticleEnergybut divided bydensityparticleCounter: ignores the shape of a particle and just checks if the position of it "corresponds" to a cell
- defined names and examples:
-
to store the same quantities as above, but summed for each cell over all particles in all particle species, skip the prefix and use the defined names directly
-
The following additional attributes are defined in this extension.
The individual requirement is given in scope.
-
particleShape- type: (floatX)
- scope: required
- description: the order of the particle assignment function shape (see Hockney reprint 1989, ISBN:0-85274-392-0, table 5-1)
- example values:
0.pointlike (NGP)1.linear (CIC)2.quadratic (TSC)3.quadrilinear (PQS)- or any other positive
floating pointnumber
-
currentDeposition- type: (string)
- scope: required
- description: current deposition scheme
- allowed values:
VillaBune(doi:10.1016/0010-4655(92)90169-Y)Esirkepov(doi:10.1016/S0010-4655(00)00228-9)ZigZagdirectBoris(Birdsall & Langdon, Plasma Physics via Computer Simulation, 15-5)directMorseNielson(Birdsall & Langdon, Plasma Physics via Computer Simulation, 15-5)othernone
-
currentDepositionParameters- type (string)
- scope: optional
- description: further parameters for current deposition schemes; reserved for future use
-
particleBoundary-
type: array of (string) of length 2
N -
scope: required
-
description: boundary conditions in each direction (in the above,
Nis the dimensionality of the field mesh) The strings are stored in the following order:- boundary at the lower end of the first axis as in
axisLabels - boundary at the upper end of the first axis as in
axisLabels - boundary at the lower end of the second axis as in
axisLabels - boundary at the upper end of the second axis as in
axisLabels - ...
- boundary at the upper end of the last axis as in
axisLabels
- boundary at the lower end of the first axis as in
-
allowed values:
periodicabsorbingreflectingreinjecting(optionally add scheme specification - such as "thermal, T=1keV" - in theparticleBoundaryParametersstring)other
-
note: currently all particles must have the same boundary condition, might become a particle attribute in the future
-
-
particleBoundaryParameters- type: array of (string) of length 2
N - scope: required if
particleBoundaryisother, optional otherwise - description: additional scheme and parameters specification for the boundary conditions
- type: array of (string) of length 2
-
particlePush- type: (string)
- scope: required
- description: Particle-Pushing Algorithm
- allowed values:
Boris(J.P. Boris. Relativistic plasma simulation-optimization of a hybrid code. USA, 1970)Vay(doi:10.1063/1.2837054)free-streaming(constantly moving with initial momentum)LLRK4(reduced Laundau-Lifshitz pusher via RK4 and classical radiation reaction, doi:10.1016/j.cpc.2016.04.002)none(static particles such as probes)other
-
particleInterpolation- type: (string)
- scope: required
- description: method that was used to interpolate fields to particle positions, as described in doi:10.1016/j.crme.2014.07.006 section 2.4
- allowed values:
uniform: The fields are interpolated directly from the staggered grid to the particle positions (with the same interpolation order in all directions).energyConserving: Also known as Galerkin method. The fields are interpolated directly from the staggered grid to the particle positions (with reduced interpolation order in the parallel direction). This scheme is energy conserving in the limit of infinitely small time steps.momentumConserving: The fields are first interpolated from the staggered grid points to the corners of each cell, and then from the cell corners to the particle position (with the same order of interpolation in all directions). This scheme is momentum conserving in the limit of infinitely small time steps.other
-
particleSmoothing- type: (string)
- scope: required
- description: applied transformations or smoothing filters on copied versions of the fields while interpolating those to the particle
- allowed values:
Binomialothernone
-
particleSmoothingParameters- type: (string)
- scope: required if
particleSmoothingis notnone - description: additional parameters to describe the applied filter further
- example:
period=1;numPasses=2;compensator=false - reserved for future use:
direction=array(),stride=array()
Note the definitions of the attributes macroWeighted and weightingPower in the ParticleWeighting extension.
When added as records to a particle output, the following naming conventions
shall be used to allow an easy identification of essential particle
properties. If these namings are not used, tools might still detect a particles
property by it's unitDimension as, e.g., an arbitrary momentum (could be,
e.g., an additional record defined by the user that stores the integrated
momentum change due to collisions) but not as the particle momentum that
should be used to push the particle.
-
charge- type: (floatX) or (intX) or (uintX)
- description: electric charge of the macroparticle or of the underlying
individual particle (depending on the
macroWeightedflag) - advice to implementors: must have
weightingPower = 1andunitDimension = (0., 0., 1., 1., 0., 0., 0.)(charge = current * time)
-
mass- type: (floatX) or (intX) or (uintX)
- description: mass of the macroparticle or of the underlying individual
particle (depending on the
macroWeightedflag) - advice to implementors: must have
weightingPower = 1andunitDimension = (0., 1., 0., 0., 0., 0., 0.)(mass)
-
weighting- see the ParticleWeighting extension
-
momentum/+ components such asx,yandz- type: each component in (floatX) or (intX) or (uintX)
- description: component-wise momentum of the macroparticle or of the
underlying individual particle (depending on the
macroWeightedflag) - advice to implementors: must have
weightingPower = 1andunitDimension = (1., 1., -1., 0., 0., 0., 0.)(momentum = mass * length / time)
-
position/+ components such asx,yandz- type: each component in (floatX) or (intX) or (uintX)
- description: component-wise position of a particle, relative to
positionOffset- in the case where the
components ofpositionOffsetare constant, position is the position relative to a global offset (e.g., the offset of a moving window) - in the case where the
components ofpositionOffsetare non-constant,positionmust represent the in-cell-position andpositionOffsetmust represent the position of the beginning of the cell (see below)
- in the case where the
- rationale: dividing the particle position in a beginning of the cell (as (intX)) and in-cell position (as (floatX)) can dramatically improve the precision of stored particle positions; this division creates a connection between particles and the fields on their cells
- advice to implementors: must have
weightingPower = 0andunitDimension = (1., 0., 0., 0., 0., 0., 0.)(length) - advice to implementors: a (floatX) type is likely the most frequent case for this record
- example: use only
xandyin 2D
-
positionOffset/+ components such asx,yandz- type: each component in (floatX) or (intX) or (uintX)
- description: if the
components of this record are non-constant this must represent the position of the beginning of the cell the particle is associated with; for the zero-based indexiof the first cartesian field coordinate, the position of the beginning of the cell is defined viagridGlobalOffset + i * gridSpacing; theunitSIof each component must be set to the corresponding lengths of the cell's edges in SI units - advice to implementors: the interpretation of
positionandpositionOffsetdoes not alter the pure calculation of the global position of the particle from the base standard; see the base standard for a code example - advice to implementors: must have
weightingPower = 0andunitDimension = (1., 0., 0., 0., 0., 0., 0.)(length) - advice to implementors: an (intX) or (uintX) type is likely the most frequent case for this record
- advice to implementors: if you want to neglect the relation between particles and their cells, simply store this record with constant components, e.g., the global moving window offset
-
particlePatches- description: if this sub-group is used in combination with non-constant
components in the
positionOffsetcomponents, the position foroffsetandextentrefers to the position of the beginning of the cell (seepositionOffset) - advice to implementors: the calculation and description of
positionandpositionOffsetis as in the base standard still the same; for non-constant components inpositionOffset(beginning-of-cell representation) one can simply checkoffsetandextentagainst thepositionOffsetrecord to select particles in patches "by cell"
- description: if this sub-group is used in combination with non-constant
components in the
-
boundElectrons- type: (floatX) or (intX) or (uintX)
- description: number of bound electrons of an ion/atom; to provide information to atomic physics algorithms
- advice to implementors: must have
weightingPower = 1andunitDimension = (0., ..., 0.)(dimensionless)
-
protonNumber- type: (floatX) or (intX) or (uintX)
- description: the atomic number Z of an ion/atom; to provide information to atomic physics algorithms
- advice to implementors: must have
weightingPower = 1andunitDimension = (0., ..., 0.)(dimensionless)
-
neutronNumber- type: (floatX) or (intX) or (uintX)
- description: the neutron number N = the mass number - A and the atomic number Z of an ion/atom; to provide information to atomic physics algorithms
- advice to implementors: must have
weightingPower = 1andunitDimension = (0., ..., 0.)(dimensionless)