Source code for pyphare.pharein.diagnostics

import numpy as np

from ..core import phare_utilities
from . import global_vars


def all_timestamps(sim):
    # adaptive: no fixed step to build a dump grid from
    if sim.time_stepper.mode != "constant":
        raise RuntimeError(
            "Error: with time_step={'mode': 'adaptive', ...}, diagnostics require explicit "
            "'write_timestamps' (no default dump grid can be built without a fixed time_step)"
        )
    init_time = sim.start_time()
    stepper = sim.time_stepper
    # consume the authoritative integer step count rather than re-deriving it from
    # final_time/dt (fp-fragile). last stamp = init + nbr*dt = final_time exactly.
    return stepper.time_step * np.arange(stepper.time_step_nbr + 1) + init_time


# ------------------------------------------------------------------------------


def diagnostics_checker(func):
    def wrapper(diagnostics_object, name, **kwargs):
        mandatory_keywords = ["quantity"]

        # check if some mandatory keywords are not missing
        missing_mandatory_kwds = phare_utilities.check_mandatory_keywords(
            mandatory_keywords, **kwargs
        )
        if len(missing_mandatory_kwds) > 0:
            raise RuntimeError(
                "Error: missing mandatory parameters : "
                + ", ".join(missing_mandatory_kwds)
            )

        # at least one way to schedule dumps must be given
        one_of_required = ["write_timestamps", "elapsed_timestamps"]
        for k in one_of_required:
            if kwargs.get(k) is None:
                kwargs.pop(k, None)
        if not any(
            phare_utilities.np_array_ify(kwargs[k]).size > 0
            for k in one_of_required
            if k in kwargs
        ):
            raise RuntimeError(
                "Error: missing parameters - one required (non-empty): "
                + ", ".join(one_of_required)
            )

        accepted_keywords = [
            "path",
            "population_name",
            "flush_every",
            "elapsed_timestamps",
            "write_timestamps",
        ]
        accepted_keywords += mandatory_keywords

        # check that all passed keywords are in the accepted keyword list
        wrong_kwds = phare_utilities.not_in_keywords_list(accepted_keywords, **kwargs)
        if len(wrong_kwds) > 0:
            raise RuntimeError("Error: invalid arguments - " + " ".join(wrong_kwds))

        try:
            # just take mandatory arguments from the dict
            # since if we arrived here we are sure they are there

            kwargs["path"] = kwargs.get("path", "./")

            return func(diagnostics_object, name, **kwargs)

        except ValueError as msg:
            print(msg)

    return wrapper


# ------------------------------------------------------------------------------
def validate_timestamps(clazz, key, **kwargs):
    sim = global_vars.sim

    init_time = sim.start_time()

    timestamps = phare_utilities.np_array_ify(kwargs.get(key, []))

    if np.any(timestamps < init_time):
        timestamps = timestamps[timestamps >= init_time]
        print(f"Warning: some timestamps below ({init_time}) are filtered")

    final_time = sim.time_stepper.final_time
    if np.any(timestamps > final_time):
        raise RuntimeError(
            f"Error: timestamp({timestamps[timestamps > final_time]}) "
            f"cannot be greater than simulation.final_time({final_time}))"
        )
    if not np.all(np.diff(timestamps) >= 0):
        raise RuntimeError(f"Error: {clazz}.{key} not in ascending order)")

    if (
        sim.time_stepper.mode == "constant"
        and sim.time_stepper.time_step_nbr > 0
        and not np.all(
            np.abs(
                timestamps / sim.time_stepper.time_step
                - np.rint(timestamps / sim.time_stepper.time_step)
                < 1e-9
            )
        )
    ):
        raise RuntimeError(
            f"Error: {clazz}.{key} is inconsistent with simulation.time_step"
        )

    return timestamps


def validate_elapsed_timestamps(clazz, key, **kwargs):
    import datetime

    timestamps = phare_utilities.np_array_ify(kwargs.get(key, []))

    timestamps = [
        int(ts.total_seconds()) if isinstance(ts, datetime.timedelta) else ts
        for ts in phare_utilities.np_array_ify(timestamps)
    ]

    if not np.all(np.diff(timestamps) >= 0):
        raise RuntimeError(f"Error: {clazz}.{key} not in ascending order)")

    return timestamps


# ------------------------------------------------------------------------------


def try_cpp_dep_vers():
    try:
        from pyphare.cpp import cpp_etc_lib

        return cpp_etc_lib().phare_deps()
    except ImportError:
        return {}


def try_cpp_build_config():
    try:
        from pyphare import cpp

        return cpp.build_config()
    except ImportError:
        return {}


class Diagnostics:
    """
    Base parameters shared by every diagnostics block below
    (:class:`ElectromagDiagnostics`, :class:`FluidDiagnostics`,
    :class:`ParticleDiagnostics`, :class:`MHDDiagnostics`,
    :class:`MetaDiagnostics`, :class:`InfoDiagnostics`). A diagnostics block
    writes one physical `quantity` to disk at a chosen set of times.

    **Common parameters**:

        * **quantity** (``str``), mandatory, which quantity to write - valid values depend on the diagnostics type, see each class below.
        * **write_timestamps** (``list`` of ``float``), simulation times at which to write this quantity. Required unless `elapsed_timestamps` is given instead.
        * **elapsed_timestamps** (``list`` of ``float`` seconds or ``datetime.timedelta``), write this quantity every time this much wall-clock time has elapsed since the simulation started, instead of at fixed simulation times. Can be given instead of, or in addition to, `write_timestamps`.
        * **path** (``str``), default="./", directory the diagnostics files for this block are written to.
        * **flush_every** (``int``), default=1, write to disk every `flush_every` dump (1 flushes every time, safest but slowest; larger values buffer more dumps in memory before writing, trading safety against a crash for I/O throughput).

    Declaring two diagnostics blocks of the same type with the same
    `quantity` (and, where relevant, the same `population_name`) does not
    create two independent diagnostics: it extends the existing one's list
    of timestamps with the new ones instead.
    """
    h5_flush_never = 0
    cpp_dep_vers = try_cpp_dep_vers()

    @diagnostics_checker
    def __init__(self, name, **kwargs):
        if global_vars.sim is None:
            raise RuntimeError("A simulation must be created before adding diagnostics")

        self.name = name
        self.path = kwargs["path"]

        self.write_timestamps = validate_timestamps(
            self.__class__.__name__, "write_timestamps", **kwargs
        )

        self.elapsed_timestamps = validate_elapsed_timestamps(
            self.__class__.__name__, "elapsed_timestamps", **kwargs
        )
        # for now every diagnostics needing computation (like momentum tensor)
        # is computing at the same time as written.
        # later this parameter can evolve to allow for different timestamps
        # that will depend on the type of diagnostics.
        self.compute_timestamps = self.write_timestamps

        self.attributes = kwargs.get("attributes", {})

        build_config = try_cpp_build_config()
        self.attributes["git_hash"] = build_config.get(
            "GIT_HASH", "git hash not available"
        )

        for dep, dep_ver in Diagnostics.cpp_dep_vers.items():
            self.attributes[f"{dep}_version"] = dep_ver

        for key in self.attributes:
            self.attributes[key] = self.attributes[key]

        self.quantity = None  # set in next line, stops pylint complaining
        self._setSubTypeAttributes(**kwargs)
        self.flush_every = kwargs.get(
            "flush_every", 1
        )  # flushes every dump, safe, but costly

        if self.flush_every < 0:
            raise RuntimeError(
                f"{(self.__class__.__name__,)}.flush_every cannot be negative"
            )

        self.__extent = None

        # if a diag already is registered we just concatenate the timestamps
        addIt = True
        registered_diags = global_vars.sim.diagnostics
        for diagname, diag in registered_diags.items():
            if self.quantity == diag.quantity:
                print(
                    f"{diag.name} already registered {self.quantity}, merging timestamps"
                )
                my_times = self.write_timestamps
                existing_times = diag.write_timestamps
                new_times = np.concatenate((my_times, existing_times))
                new_times.sort()
                mask = np.ones(len(new_times), dtype=bool)
                mask[1:] = (
                    np.diff(new_times) > 1e-10
                )  # assumed smaller than any realistic dt
                global_vars.sim.diagnostics[diagname].write_timestamps = new_times[mask]
                addIt = False
                break  # there can be only one

        if addIt:
            global_vars.sim.add_diagnostics(self)

    def extent(self):
        return self.__extent

    def _setSubTypeAttributes(self, **kwargs):  # stop pyline complaining
        raise RuntimeError("Never to be called, defined in subclass")

    def to_dict(self, type, **kwargs):
        return {
            "name": self.name,
            "type": type,
            "quantity": self.quantity,
            "write_timestamps": self.write_timestamps,
            "elapsed_timestamps": self.elapsed_timestamps,
            "compute_timestamps": self.compute_timestamps,
            "path": self.path,
            **kwargs,
        }


# ------------------------------------------------------------------------------
[docs] class MHDDiagnostics(Diagnostics): """ Writes MHD fluid quantities to disk. Only meaningful in an MHD simulation (``Simulation(model_options=["MHDModel"])``). **Usage example:** .. code-block:: python 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 """ mhd_quantities = ("rho", "V", "P", "rhoV", "Etot") type = "mhd" def __init__(self, **kwargs): super().__init__( MHDDiagnostics.type + str(global_vars.sim.count_diagnostics(MHDDiagnostics.type)), **kwargs, ) def _setSubTypeAttributes(self, **kwargs): if kwargs["quantity"] not in MHDDiagnostics.mhd_quantities: error_msg = "Error: '{}' not a valid mhd diagnostics : " + ", ".join( MHDDiagnostics.mhd_quantities ) raise ValueError(error_msg.format(kwargs["quantity"])) else: self.quantity = "/mhd/" + kwargs["quantity"] self.attributes["heat_capacity_ratio"] = global_vars.sim.gamma def to_dict(self): return { "name": self.name, "type": MHDDiagnostics.type, "quantity": self.quantity, "write_timestamps": self.write_timestamps, "compute_timestamps": self.compute_timestamps, "path": self.path, }
# ------------------------------------------------------------------------------
[docs] class ElectromagDiagnostics(Diagnostics): """ Writes the electric or magnetic field to disk. **Usage example:** .. code-block:: python 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). """ em_quantities = ("E", "B") type = "electromag" def __init__(self, **kwargs): super().__init__( ElectromagDiagnostics.type + str(global_vars.sim.count_diagnostics(ElectromagDiagnostics.type)), **kwargs, ) def _setSubTypeAttributes(self, **kwargs): if kwargs["quantity"] not in ElectromagDiagnostics.em_quantities: error_msg = "Error: '{}' not a valid electromag diagnostics : " + ", ".join( ElectromagDiagnostics.em_quantities ) raise ValueError(error_msg.format(kwargs["quantity"])) else: self.quantity = "/EM_" + kwargs["quantity"] def to_dict(self): return super().to_dict(type(self).type)
# ------------------------------------------------------------------------------ def population_in_model(population): return population in global_vars.sim.model.populations class FluidDiagnostics_(Diagnostics): """:meta private:""" fluid_quantities = ( "density", "charge_density", "mass_density", "flux", "bulkVelocity", "charge_flux", "momentum_tensor", ) type = "fluid" def __init__(self, **kwargs): super().__init__( FluidDiagnostics_.type + str(global_vars.sim.count_diagnostics(FluidDiagnostics_.type)), **kwargs, ) def _setSubTypeAttributes(self, **kwargs): self.population_name = None if "population_name" not in kwargs and kwargs["quantity"] == "flux": raise ValueError("Error: missing population_name") elif "population_name" in kwargs: self.population_name = kwargs["population_name"] if "population_name" not in kwargs and kwargs["quantity"] == "density": raise ValueError("Error: cannot use density without population name") if kwargs["quantity"] not in FluidDiagnostics_.fluid_quantities: error_msg = "Error: '{}' not a valid fluid diagnostics : " + ", ".join( FluidDiagnostics_.fluid_quantities ) raise ValueError(error_msg.format(kwargs["quantity"])) elif kwargs["quantity"] == "charge_flux" and self.population_name is not None: raise ValueError("'charge_flux' is only available for the ions as a whole") elif kwargs["quantity"] == "flux" and kwargs["population_name"] == "ions": raise ValueError( "'flux' is only available for specific populations, try 'bulkVelocity" ) elif kwargs["quantity"] == "pressure_tensor": raise ValueError("'pressure_tensor' is not available yet") else: self.quantity = kwargs["quantity"] if self.population_name is None: self.quantity = "/ions/" + self.quantity else: if not population_in_model(self.population_name): raise ValueError( f"Error: population '{self.population_name}' not in simulation initial model" ) self.quantity = "/ions/pop/" + self.population_name + "/" + self.quantity def to_dict(self): return super().to_dict(type(self).type, population_name=self.population_name) def for_total_ions(**kwargs): return "population_name" not in kwargs
[docs] class FluidDiagnostics: """ 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:** .. code-block:: python 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 :class:`~pyphare.pharein.MaxwellianFluidModel`. """ def __init__(self, **kwargs): if kwargs["quantity"] == "pressure_tensor": if for_total_ions(**kwargs): needed_quantities = ["mass_density", "bulkVelocity", "momentum_tensor"] else: needed_quantities = ["density", "flux", "momentum_tensor"] for quantity in needed_quantities: kwargs["quantity"] = quantity FluidDiagnostics_(**kwargs) else: FluidDiagnostics_(**kwargs)
# ------------------------------------------------------------------------------
[docs] class ParticleDiagnostics(Diagnostics): """ 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:** .. code-block:: python 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 :class:`~pyphare.pharein.MaxwellianFluidModel`. """ particle_quantities = ("space_box", "domain", "levelGhost") type = "particle" def __init__(self, **kwargs): super().__init__( ParticleDiagnostics.type + str(global_vars.sim.count_diagnostics(ParticleDiagnostics.type)), **kwargs, ) def _setSubTypeAttributes(self, **kwargs): # domain is good default for users who should not worry about what that means # even less about ghosts... kwargs["quantity"] = kwargs.get("quantity", "domain") if kwargs["quantity"] not in ParticleDiagnostics.particle_quantities: error_msg = "Error: '{}' not a valid particle diagnostics : " + ", ".join( ParticleDiagnostics.particle_quantities ) raise ValueError(error_msg.format(kwargs["quantity"])) self.quantity = kwargs["quantity"] self.space_box(**kwargs) if "population_name" not in kwargs: raise ValueError("Error: missing population_name") else: self.population_name = kwargs["population_name"] if not population_in_model(self.population_name): raise ValueError( f"Error: population '{self.population_name}' not in simulation initial model" ) self.quantity = "/ions/pop/" + self.population_name + "/" + self.quantity def space_box(self, **kwargs): if "extent" not in kwargs and self.quantity == "space_box": raise ValueError( "Error: missing 'extent' parameter required by 'space_box' the ParticleDiagnostics type" ) elif "extent" in kwargs: self.extent = kwargs["extent"] def to_dict(self): return super().to_dict( type(self).type, extent=", ".join([str(x) for x in self.extent]), population_name=self.population_name, )
# ------------------------------------------------------------------------------ class MetaDiagnostics(Diagnostics): """ Writes bookkeeping information about the AMR hierarchy itself, rather than a physical quantity. **Usage example:** .. code-block:: python import pyphare.pharein as ph ph.MetaDiagnostics(quantity="tags", write_timestamps=timestamps) **quantity**, one of: * "tags" - the per-cell refinement tags produced by ``refinement="tagging"``, i.e. which cells were flagged for refinement at each write time. Useful to inspect/tune `tagging_threshold` and `tag_buffer`. """ meta_quantities = ("tags",) type = "meta" def __init__(self, **kwargs): super().__init__( MetaDiagnostics.type + str(global_vars.sim.count_diagnostics(MetaDiagnostics.type)), **kwargs, ) def _setSubTypeAttributes(self, **kwargs): if kwargs["quantity"] not in MetaDiagnostics.meta_quantities: error_msg = "Error: '{}' not a valid meta diagnostics : " + ", ".join( MetaDiagnostics.meta_quantities ) raise ValueError(error_msg.format(kwargs["quantity"])) self.quantity = f"/{kwargs['quantity']}" def to_dict(self): return super().to_dict(type(self).type) # ------------------------------------------------------------------------------
[docs] class InfoDiagnostics(Diagnostics): """ Writes lightweight run-monitoring information to disk, cheap enough to dump at every time step. **Usage example:** .. code-block:: python 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. """ info_quantities = ("particle_count",) type = "info" @classmethod def default_kwargs(cls, **kwargs): if "write_timestamps" not in kwargs: kwargs["write_timestamps"] = all_timestamps(global_vars.sim) return kwargs def __init__(self, **kwargs): super().__init__( InfoDiagnostics.type + str(global_vars.sim.count_diagnostics(InfoDiagnostics.type)), **InfoDiagnostics.default_kwargs(**kwargs), ) def _setSubTypeAttributes(self, **kwargs): if kwargs["quantity"] not in InfoDiagnostics.info_quantities: error_msg = "Error: '{}' not a valid info diagnostics : " + ", ".join( InfoDiagnostics.info_quantities ) raise ValueError(error_msg.format(kwargs["quantity"])) self.quantity = f"/{kwargs['quantity']}" def to_dict(self): return super().to_dict(type(self).type)