Skip to content

Latest commit

 

History

History
504 lines (444 loc) · 23.3 KB

EXT_ED-PIC.md

File metadata and controls

504 lines (444 loc) · 23.3 KB
Raw

Domain-Specific Naming Conventions for Electro-Dynamic/Static PIC Codes

openPMD extension name: ED-PIC

openPMD extension ID: 1

Introduction

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.

Mesh Based Records (Fields)

Additional Attributes for the Group meshesPath

The following additional attributes are defined to this extension. The individual requirement is given in scope.

  • fieldSolver

  • fieldSolverParameters

    • type: (string)
    • scope: required if fieldSolver is other or GPSTD, 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, N is 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
    • allowed values:
      • periodic
      • open (optionally add scheme specification, such as PML, Silver-Muller, etc., in the fieldBoundaryParameters string)
      • reflecting (optionally add scheme specification, such as Neumann-type or Dirichlet-type, in the fieldBoundaryParameters string)
      • other

  • fieldBoundaryParameters

    • type: array of (string) of length 2 N
    • scope: required if fieldBoundary is other, optional otherwise
    • description: additional scheme and parameters specification for the boundary conditions

  • particleBoundary

    • type: array of (string) of length 2 N

    • scope: required

    • description: boundary conditions in each direction (in the above, N is 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

    • allowed values:

      • periodic
      • absorbing
      • reflecting
      • reinjecting (optionally add scheme specification - such as "thermal, T=1keV" - in the particleBoundaryParameters string)
      • 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 particleBoundary is other, optional otherwise
    • description: additional scheme and parameters specification for the boundary conditions

  • 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:
      • Binomial
      • other
      • none

  • currentSmoothingParameters

    • type: (string)
    • scope: required if currentSmoothing is not none
    • 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

  • chargeCorrectionParameters

    • type: (string)
    • scope: required if chargeCorrection is not none
    • description: additional parameters to describe the charge correction parameter
    • example: period=100

Additional Attributes for each mesh record (field record)

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 fieldSmoothing is not none
    • description: additional parameters to describe the applied filter further (similar to currentSmoothingParameters)

Naming Conventions for mesh records (field records)

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 as electron_J for current densities created by the particles in particle species electron
        • density: such as electron_density (elements per volume/area/line)
        • chargeDensity: such as electron_chargeDensity (charge per volume/area/line)
        • particleEnergy: kinetic energy of all particles, with their weighted contribution to a cell
        • energyDensity: same as particleEnergy but divided by density
        • particleCounter: ignores the shape of a particle and just checks if the position of it "corresponds" to a cell

    • 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

Particle Records (Macroparticles)

Additional Attributes for the Group of each Particle Species

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 point number

  • currentDeposition

    • type: (string)
    • scope: required
    • description: current deposition scheme
    • allowed values:

  • currentDepositionParameters

    • type (string)
    • scope: optional
    • description: further parameters for current deposition schemes; reserved for future use

  • 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:
      • Binomial
      • other
      • none

  • particleSmoothingParameters

    • type: (string)
    • scope: required if particleSmoothing is not none
    • description: additional parameters to describe the applied filter further
    • example: period=1;numPasses=2;compensator=false
    • reserved for future use: direction=array(), stride=array()

Additional Attributes for each Particle Record

The following additional attributes for particle records are defined in this extension. The individual requirement is given in scope.

When using macroparticles (see below for the definition of the macroparticle weighting), there is an ambiguity regarding whether the particle quantity that is written (e.g. energy, momentum) is that of the full macroparticle, or that of the underlying individual particle. Therefore, this extension requires the two following attributes:

  • macroWeighted

    • type: (uint32)
    • scope: required
    • description: indicates whether this quantity is written for the underlying particle (macroWeighted = 0) or for the full macroparticle (macroWeighted = 1)
    • example: Let us assume that a user writes the charge attribute of a macroparticle that represents 100 electrons. If this user chooses to write -1.6e-19 (charge of one individual electron) then macroWeighted must be 0. If the user writes -1.6e-17 (total charge of 100 electrons), then macroweighted must be 1

  • weightingPower

    • type: (float64 / REAL8)
    • scope: required
    • description: indicates with which power of weighting (see below) the quantity should be multiplied, in order to go from the individual-particle representation to the full-macroparticle representation
    • example: Let us consider a macroparticle that represents 100 electrons. In this case, weighting is w=100 and the charge of each underlying individual particle is q=-1.6e-19. Then the charge Q of the full macroparticle is given by: Q=q w^1 and therefore weightingPower must be 1.
    • advice to implementors: reading example (with h5py) and extracting charge of the macroparticles in Python. When not absolutely necessary, reading the additional weighting record can be avoided for performance reasons like this:
    

    • 



f = h5py.File('example.h5')
species = f["<path_to_species_group>"]
q = species["charge"][:]
u_si = q.attrs["unitSI"]
p = q.attrs["weightingPower"]
if q.attrs["macroWeighted"] == 0 and p != 0:
w = species["weighting"][:]
q_macro = u_si * q * w**p
else :
# No need to read the weighting from disk
q_macro = u_si * q



### Namings for `Records` per Particle Species

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 `macroWeighted` flag)
    - advice to implementors: must have `weightingPower = 1` and
                              `unitDimension = (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 `macroWeighted` flag)
    - advice to implementors: must have `weightingPower = 1` and
                              `unitDimension = (0., 1., 0., 0., 0., 0., 0.)`
                              (mass)

  - `weighting`
    - type: *(floatX)* or *(intX)* or *(uintX)*
    - description: the number of underlying individual particles that
                   the macroparticles represent
    - advice to implementors: must have `weightingPower = 1`,
                              `macroWeighted = 1`, `unitSI = 1` and
                              `unitDimension == (0., ..., 0.)`

  - `momentum/` + components such as `x`, `y` and `z`
    - 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
                   `macroWeighted` flag)
    - advice to implementors: must have `weightingPower = 1` and
                              `unitDimension = (1., 1., -1., 0., 0., 0., 0.)`
                              (momentum = mass * length / time)

  - `position/` + components such as `x`, `y` and `z`
    - type: each component in *(floatX)* or *(intX)* or *(uintX)*
    - description: component-wise position of a particle, relative to
                   `positionOffset`
      - in the case where the `component`s of `positionOffset` are constant,
        position is the position relative to a global offset (e.g., the offset
        of a moving window)
      - in the case where the `component`s of `positionOffset` are
        non-constant, `position` must represent the in-cell-position and
        `positionOffset` must represent the position of the beginning of the
        cell (see below)
    - 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 = 0` and
                              `unitDimension = (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 `x` and `y` in 2D

  - `positionOffset/` + components such as `x`, `y` and `z`
    - type: each component in *(floatX)* or *(intX)* or *(uintX)*
    - description: if the `component`s 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 index `i` of the first cartesian field
                   coordinate, the position of the beginning of the cell is
                   defined via `gridGlobalOffset + i * gridSpacing`;
                   the `unitSI` of each component must be set to the
                   corresponding lengths of the cell's edges in SI units
    - advice to implementors: the interpretation of `position` and
                              `positionOffset` does 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 = 0` and
                              `unitDimension = (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 `positionOffset` components, the
                   position for `offset` and `extent` refers to the
                   position of the beginning of the cell (see `positionOffset`)
    - advice to implementors: the calculation and description of
                              `position` and `positionOffset` is as in
                              the base standard still the same;
                              for non-constant components in `positionOffset`
                              (beginning-of-cell representation) one can simply
                              check `offset` and `extent` against the
                              `positionOffset` record to select particles
                              in patches "by cell"

  - `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 = 1` and
                              `unitDimension = (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 = 1` and
                              `unitDimension = (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 = 1` and
                              `unitDimension = (0., ..., 0.)` (dimensionless)