Diagnostics

Diagnostics blocks tell PHARE what to write to disk, and when. Several diagnostics blocks are available, one per family of physical quantity; each can be declared multiple times (e.g. once per quantity, or once per population). Declaring the same quantity (and, for per-population diagnostics, the same population) twice does not create a duplicate: it just extends the existing one’s list of output times.

All diagnostics blocks share the parameters documented on Diagnostics, in particular quantity (what to write - valid values differ per block, see below) and, controlling when to write, write_timestamps and/or elapsed_timestamps. At least one of the two is required.

write_timestamps is a list of simulation times, in simulation time units, and each value must line up with the simulation’s time_step:

import numpy as np
import pyphare.pharein as ph

time_step_nbr = 1000
time_step = 0.001
final_time = time_step * time_step_nbr
dt = 10 * time_step
timestamps = dt * np.arange(final_time / dt + 1)

ph.ElectromagDiagnostics(quantity="E", write_timestamps=timestamps)
ph.ElectromagDiagnostics(quantity="B", write_timestamps=timestamps)

In this example E and B are written every 10 time steps. Timestamps don’t need to be equally spaced.

elapsed_timestamps is the wall-clock counterpart: instead of simulation times, it is a list of wall-clock durations (in seconds, or as datetime.timedelta) elapsed since the simulation started. It is handy when you don’t know in advance which simulation time a run will reach within a given wall-clock budget (e.g. on a cluster with a time limit), or when a diagnostic should be dumped on a wall-clock cadence rather than a simulation-time one:

import datetime

ph.ElectromagDiagnostics(
    quantity="E",
    elapsed_timestamps=[datetime.timedelta(minutes=10 * i) for i in range(6)],
)

This writes E roughly every 10 minutes of wall-clock time, for the first hour of the run. Unlike write_timestamps, each dump is triggered by comparing against the actual wall-clock time as the run progresses, so the simulation time (and time step) at which it happens depends on how fast the run goes - it is not reproducible across runs at different speeds or on different machines. write_timestamps and elapsed_timestamps can be combined on the same diagnostics block; PHARE writes whenever either condition is met.

Where diagnostics files are written, and in what format, is controlled by Simulation(diag_options=...) (see Simulation) rather than by the diagnostics blocks themselves.

Electromagnetic Diagnostics

class pyphare.pharein.ElectromagDiagnostics(**kwargs)[source]

Writes the electric or magnetic field to disk.

Usage example:

import pyphare.pharein as ph

ph.ElectromagDiagnostics(quantity="E", write_timestamps=timestamps)
ph.ElectromagDiagnostics(quantity="B", write_timestamps=timestamps)

quantity, one of: “E” (electric field), “B” (magnetic field).

Fluid Diagnostics

class pyphare.pharein.FluidDiagnostics(**kwargs)[source]

Writes ion fluid moments (density, velocity, pressure, …) to disk. These are moments of the particle distribution(s), either for one named population or, for some quantities, for the ions as a whole.

Usage example:

import pyphare.pharein as ph

# a per-population quantity: population_name required
ph.FluidDiagnostics(
    quantity="density",
    population_name="protons",
    write_timestamps=timestamps,
)

# a quantity that also works for the ions as a whole: population_name omitted
ph.FluidDiagnostics(quantity="mass_density", write_timestamps=timestamps)

quantity, always requires population_name:

  • “density” - particle density of the named population

  • “flux” - flux of the named population

quantity, works either for the ions as a whole (omit population_name) or for one named population (give population_name):

  • “charge_density” - charge density

  • “mass_density” - mass density

  • “bulkVelocity” - mass-weighted bulk velocity. For the ions as a whole it is a diagnostic only: on regions covered by a finer level it is the coarse level’s own value, and ghost nodes are not made consistent between patches

  • “momentum_tensor” - momentum tensor

  • “pressure_tensor” - pressure tensor. This is a convenience quantity: declaring it registers the underlying moments it is computed from (mass_density, bulkVelocity and momentum_tensor for the ions as a whole; density, flux and momentum_tensor for a named population) as separate diagnostics under the hood.

quantity, only for the ions as a whole (omit population_name):

  • “charge_flux” - charge flux sum_s q_s n_s V_s, the ion current density used in the electron velocity

population_name (str), name of the ion population this diagnostics applies to, as declared in MaxwellianFluidModel.

Important

Simulation(diag_export_format=...) and diag_options["format"] are two different, unrelated settings despite the similar name: diag_export_format currently only accepts "hdf5" and has no other effect; the actual on-disk diagnostics format ("phareh5" or "pharevtkhdf") is diag_options["format"], described below.

File formats: phareh5 vs pharevtkhdf

"phareh5" is PHARE’s own HDF5-based format. Quantities are written with their exact centering on the mesh (including ghost nodes), which is what makes it the format used in most tests: it preserves the raw, uninterpolated data.

"pharevtkhdf" is Kitware’s VTKHDF format. All quantities are interpolated to mesh nodes (point values), and the files are readily readable by ParaView.

Particle Diagnostics

class pyphare.pharein.ParticleDiagnostics(**kwargs)[source]

Writes raw macro-particles of one ion population to disk. Typically much heavier (in disk size and I/O time) than the other diagnostics types.

Usage example:

import pyphare.pharein as ph

ph.ParticleDiagnostics(
    quantity="domain",
    population_name="protons",
    write_timestamps=timestamps,
)

quantity, mandatory, one of:

  • “domain”, particles living within the interior of the simulation patches - the right choice for most uses.

  • “levelGhost”, particles living in the ghost region between two AMR levels - mainly useful for debugging refinement/coarsening.

population_name (str), mandatory, name of the ion population to write particles for, as declared in MaxwellianFluidModel.

MHD Diagnostics

class pyphare.pharein.MHDDiagnostics(**kwargs)[source]

Writes MHD fluid quantities to disk. Only meaningful in an MHD simulation (Simulation(model_options=["MHDModel"])).

Usage example:

import pyphare.pharein as ph

ph.MHDDiagnostics(quantity="rho", write_timestamps=timestamps)

quantity, one of:

  • “rho” - mass density

  • “V” - velocity

  • “P” - thermal pressure

  • “rhoV” - momentum density

  • “Etot” - total energy density

Info Diagnostics

class pyphare.pharein.InfoDiagnostics(**kwargs)[source]

Writes lightweight run-monitoring information to disk, cheap enough to dump at every time step.

Usage example:

import pyphare.pharein as ph

ph.InfoDiagnostics(quantity="particle_count")

quantity, one of:

  • “particle_count” - number of particles per patch/level, useful to monitor AMR/load-balancing behavior over the run.

Unlike other diagnostics, write_timestamps defaults to every simulation time step if not given explicitly.