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=None, fldobject=None, comm=None, fieldtypes=['rho', 'E', 'B', 'J'], write_dir=None, iteration_min=0, iteration_max=inf, dt_period=None)[source]

Initialize the field diagnostic.

Parameters:

  • period (int, optional) – The period of the diagnostics, in number of timesteps. (i.e. the diagnostics are written whenever the number of iterations is divisible by period). Specify either this or dt_period.

  • dt_period (float (in seconds), optional) – The period of the diagnostics, in physical time of the simulation. Specify either this or 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_min (ints) – The iterations between which data should be written (iteration_min is inclusive, iteration_max is exclusive)

  • iteration_max (ints) – The iterations between which data should be written (iteration_min is inclusive, iteration_max is exclusive)

Particle diagnostic

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

Initialize the particle diagnostics.

Parameters:

  • period (int, optional) – The period of the diagnostics, in number of timesteps. (i.e. the diagnostics are written whenever the number of iterations is divisible by period). Specify either this or dt_period.

  • dt_period (float (in seconds), optional) – The period of the diagnostics, in physical time of the simulation. Specify either this or period

  • species (a dictionary of Particles objects) – The object that is written (e.g. elec) is assigned to the particle name 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) – Possible values are: [“position”, “momentum”, “weighting”, “E” , “B”, “gamma”] “E” and “B” writes the E and B fields at the particles’ positions, respectively, but is turned off by default. “gamma” writes the particles’ Lorentz factor. By default, if a particle is tracked, its id is always written; Also, if a particle has spin tracking enabled, the spin components are written to file.

  • 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_min (ints) – The iterations between which data should be written (iteration_min is inclusive, iteration_max is exclusive)

  • iteration_max (ints) – The iterations between which data should be written (iteration_min is inclusive, iteration_max is exclusive)

  • subsampling_fraction (float, optional) – If this is not None, the particle data is subsampled with subsampling_fraction probability

Particle density diagnostic

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

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

Parameters:

  • period (int, optional) – The period of the diagnostics, in number of timesteps. (i.e. the diagnostics are written whenever the number of iterations is divisible by period). Specify either this or dt_period.

  • dt_period (float (in seconds), optional) – The period of the diagnostics, in physical time of the simulation. Specify either this or period

  • sim (an fbpic Simulation object) – Contains the information of the simulation

  • species (a dictionary of Particles 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_min (ints) – The iterations between which data should be written (iteration_min is inclusive, iteration_max is exclusive)

  • iteration_max (ints) – 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.BackTransformedFieldDiagnostic(zmin_lab, zmax_lab, v_lab, dt_snapshots_lab, Ntot_snapshots_lab, gamma_boost, period, fldobject, comm=None, fieldtypes=['E', 'B'], write_dir=None, t_min_snapshots_lab=0.0, t_max_snapshots_lab=inf)[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.

  • t_min_snapshots_lab (floats (seconds)) –

    The time in the lab frame between which snapshots are created (t_min_snapshots_lab is inclusive,

    t_max_snapshots_lab is exclusive).

  • t_max_snapshots_lab (floats (seconds)) –

    The time in the lab frame between which snapshots are created (t_min_snapshots_lab is inclusive,

    t_max_snapshots_lab is exclusive).

Warning

The former class BoostedFieldDiagnostic has been renamed as BackTransformedFieldDiagnostic.

Although the name BoostedFieldDiagnostic can still be used (for backward compatibility), we recommend using BackTransformedFieldDiagnostic instead.

Particle diagnostic

class fbpic.openpmd_diag.BackTransformedParticleDiagnostic(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, t_min_snapshots_lab=0.0, t_max_snapshots_lab=inf)[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 ParticleDiagnostic for the other parameters.

Warning

The output of the gathered fields on the particles (particle_data=["E", "B"]) and of the Lorentz factor (particle_data=["gamma"]) is not currently supported for BackTransformedParticleDiagnostic.

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

  • t_min_snapshots_lab (floats (seconds)) –

    The time in the lab frame between which snapshots are created (t_min_snapshots_lab is inclusive,

    t_max_snapshots_lab is exclusive).

  • t_max_snapshots_lab (floats (seconds)) –

    The time in the lab frame between which snapshots are created (t_min_snapshots_lab is inclusive,

    t_max_snapshots_lab is exclusive).

Warning

The former class BoostedParticleDiagnostic has been renamed as BackTransformedParticleDiagnostic.

Although the name BoostedParticleDiagnostic can still be used (for backward compatibility), we recommend using BackTransformedParticleDiagnostic instead.