The openPMD diagnostics

During a simulation, FBPIC outputs diagnostics of fields and particles in the form of openPMD files.

A diagnostic can be directly added to simulation (or removed) by adding or removing a corresponding diagnostic object in the list of diagnostics diags, which is an attribute of the Simulation class.

Below are the different available diagnostics objects:

Regular diagnostics

Field diagnostic

class fbpic.openpmd_diag.FieldDiagnostic(period, fldobject, comm=None, fieldtypes=['rho', 'E', 'B', 'J'], write_dir=None, iteration_min=0, iteration_max=inf)[source]

Initialize the field diagnostic.

Parameters:
  • period (int) – The period of the diagnostics, in number of timesteps. (i.e. the diagnostics are written whenever the number of iterations is divisible by period)
  • fldobject (a Fields object) – Points to the data that has to be written at each output
  • comm (an fbpic BoundaryCommunicator object or None) – If this is not None, the data is gathered on the first proc, and the guard cells are removed from the output. Otherwise, each proc writes its own data, including guard cells. (Make sure to use different write_dir in this case.)
  • fieldtypes (a list of strings, optional) – The strings are either “rho”, “E”, “B” or “J” and indicate which field should be written. Default : all fields are written
  • write_dir (string, optional) – The POSIX path to the directory where the results are to be written. If none is provided, this will be the path of the current working directory.
  • iteration_max (iteration_min,) – The iterations between which data should be written (iteration_min is inclusive, iteration_max is exclusive)

Particle diagnostic

class fbpic.openpmd_diag.ParticleDiagnostic(period, species={'electrons': None}, comm=None, particle_data=['position', 'momentum', 'weighting'], select=None, write_dir=None, iteration_min=0, iteration_max=inf)[source]

Initialize the particle diagnostics.

Parameters:
  • period (int) – The period of the diagnostics, in number of timesteps. (i.e. the diagnostics are written whenever the number of iterations is divisible by period)
  • species (a dictionary of Particle objects) – The object that is written (e.g. elec) is assigned to the particleName of this species. (e.g. {“electrons” : elec })
  • comm (an fbpic BoundaryCommunicator object or None) – If this is not None, the data is gathered by the communicator, and guard cells are removed. Otherwise, each rank writes its own data, including guard cells. (Make sure to use different write_dir in this case.)
  • particle_data (a list of strings, optional) – The particle properties are given by: [“position”, “momentum”, “weighting”] for the coordinates x,y,z. By default, if a particle is tracked, its id is always written.
  • select (dict, optional) – Either None or a dictionary of rules to select the particles, of the form ‘x’ : [-4., 10.] (Particles having x between -4 and 10 microns) ‘ux’ : [-0.1, 0.1] (Particles having ux between -0.1 and 0.1 mc) ‘uz’ : [5., None] (Particles with uz above 5 mc)
  • write_dir (a list of strings, optional) – The POSIX path to the directory where the results are to be written. If none is provided, this will be the path of the current working directory.
  • iteration_max (iteration_min,) – The iterations between which data should be written (iteration_min is inclusive, iteration_max is exclusive)

Particle density diagnostic

class fbpic.openpmd_diag.ParticleChargeDensityDiagnostic(period, sim, species={'electrons': None}, write_dir=None, iteration_min=0, iteration_max=inf)[source]

Writes the charge density of the specified species in the openPMD file (one dataset per species)

Parameters:
  • period (int) – The period of the diagnostics, in number of timesteps. (i.e. the diagnostics are written whenever the number of iterations is divisible by period)
  • sim (an fbpic Simulation object) – Contains the information of the simulation
  • species (a dictionary of Particle objects) – Similar to the corresponding object for ParticleDiagnostic Specifies the density of which species should be written
  • write_dir (string, optional) – The POSIX path to the directory where the results are to be written. If none is provided, this will be the path of the current working directory.
  • iteration_max (iteration_min,) – The iterations between which data should be written (iteration_min is inclusive, iteration_max is exclusive)

Back-transformed diagnostics (boosted-frame simulations)

These diagnostics recontruct and output the lab-frame quantities on the fly, during a boosted-frame simulation.

Field diagnostic

class fbpic.openpmd_diag.BoostedFieldDiagnostic(zmin_lab, zmax_lab, v_lab, dt_snapshots_lab, Ntot_snapshots_lab, gamma_boost, period, fldobject, comm=None, fieldtypes=['E', 'B'], write_dir=None)[source]

Initialize diagnostics that retrieve the data in the lab frame, as a series of snapshot (one file per snapshot), within a virtual moving window defined by zmin_lab, zmax_lab, v_lab.

The parameters defined below are specific to the back-transformed diagnostics. See the documentation of FieldDiagnostic for the other parameters.

Parameters:
  • zmin_lab (float (in meters)) – The position of the left edge of the virtual moving window, in the lab frame, at t=0
  • zmax_lab (float (in meters)) – The position of the right edge of the virtual moving window, in the lab frame, at t=0
  • v_lab (float (in m.s^-1)) – Speed of the moving window in the lab frame
  • dt_snapshots_lab (float (in seconds)) – Time interval in the lab frame between two successive snapshots
  • Ntot_snapshots_lab (int) – Total number of snapshots that this diagnostic will produce
  • period (int) – Number of iterations for which the data is accumulated in memory, before finally writing it to the disk.
  • fieldtypes (a list of strings, optional) – The strings are either “rho”, “E”, “B” or “J” and indicate which field should be written. Default : only “E” and “B” are written. This is because the backward Lorentz transform is not as precise for “rho” and “J” as for “E” and “B” (because “rho” and “J” are staggered in time). The user can still output “rho” and “J” by changing fieldtypes, but has to be aware that there may errors in the backward transform. Moreover, writing rho/J slows down the simulation, as these fields are then brought from spectral to real space, at each iteration.

Particle diagnostic

class fbpic.openpmd_diag.BoostedParticleDiagnostic(zmin_lab, zmax_lab, v_lab, dt_snapshots_lab, Ntot_snapshots_lab, gamma_boost, period, fldobject, particle_data=['position', 'momentum', 'weighting'], select=None, write_dir=None, species={'electrons': None}, comm=None)[source]

Initialize diagnostics that retrieve the data in the lab frame, as a series of snapshot (one file per snapshot), within a virtual moving window defined by zmin_lab, zmax_lab, v_lab.

The parameters defined below are specific to the back-transformed diagnostics. See the documentation of FieldDiagnostic for the other parameters.

Parameters:
  • zmin_lab (float (in meters)) – The position of the left edge of the virtual moving window, in the lab frame, at t=0
  • zmax_lab (float (in meters)) – The position of the right edge of the virtual moving window, in the lab frame, at t=0
  • v_lab (float (m.s^-1)) – Speed of the moving window in the lab frame
  • dt_snapshots_lab (float (seconds)) – Time interval in the lab frame between two successive snapshots
  • Ntot_snapshots_lab (int) – Total number of snapshots that this diagnostic will produce
  • period (int) – Number of iterations for which the data is accumulated in memory, before finally writing it to the disk.
  • fldobject (a Fields object,) – The Fields object of the simulation, that is needed to extract some information about the grid