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 inMaxwellianFluidModel.
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 inMaxwellianFluidModel.
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.