cminject.result_storages package

Implementations of cminject.base.ResultStorage.

class cminject.result_storages.HDF5ResultStorage(filename: str, mode: str = 'r', force_writable: bool = False, metadata: Optional[Dict[str, Any]] = None)

Bases: cminject.base.ResultStorage

Stores and reads cminject.experiment.Experiment output data into and from an HDF5 file.

Note

Let n be the number of stored particles. The following groups and datasets will be stored:

  • particles (Group): Stores the constant and tracked properties of all particles.

    • properties (Dataset, shape (n,)): The fixed (non-tracked) properties of all particles, see cminject.base.Particle.constant_properties()

    • tracked (Group): Collections storing how the tracked properties, see cminject.base.Particle.tracked_properties(), changed during the simulation. The data type of all datasets in here is the same, as returned by the associated Particle subclass’s cminject.base.Particle.as_dtype() when called with the string ‘tracked’.

      • initial (Dataset, shape (n,)): The initial set of tracked properties

      • final (Dataset, shape (n,)): The final set of tracked properties

      • trajectories (Dataset, shape (n,)): The trajectories of all particles, stored as one variable-length array, since the lengths of the trajectories do not necessarily match. Might contain only empty trajectories if trajectories were not tracked during the simulation!

  • detectors (Group): Stores detector hits of all detectors, one Dataset for each Detector, stored by each Detector’s identifier, id.

    • id (Dataset): All hits on the detector with identifier id. Each entry is one hit, storing all properties of the hit’s Particle using the Particle’s ‘all’ dtype (see cminject.base.Particle.as_dtype(), called with the string ‘all’). Note that one particle can incur multiple hits.

Further attributes can be stored on the root node by passing a dictionary as the “metadata” argument to the constructor.

Warning

For efficient and predictable storage, it’s assumed that all detector hits on each detector return exactly the same shape and dtype. This should probably be the case in any a typical implementation of a detector.

property file_handle

Returns the file handle (a h5py.File instance) that this result storage currently has opened.

Returns

The file handle.

Raises

RuntimeError, if the file handle is not set (e.g., due to the result storage being accessed outside a with-block)

get_detectors() → Dict[str, numpy.ndarray]

The collection of all detectors.

Returns

The detectors, in a dictionary mapping their identifying string to their collection of detected hits.

Note

Detectors that did not detect at least one particle are not necessarily part of the output of this method, and that if there were no detectors or no detector detected at least one particle, None is returned.

get_dimensions() → int

The number of spatial dimensions that the stored simulation had.

get_properties() → numpy.ndarray

The collection of constant particle properties, i.e., the values of their Particle.constant_properties().

Returns

See above; None if these weren’t stored.

get_tracked_final() → numpy.ndarray

The collection of final particle states, i.e., the final values of their Particle.tracked_properties().

Returns

See above; None if these weren’t stored.

get_tracked_initial() → numpy.ndarray

The collection of initial particle states, i.e., the initial values of their Particle.tracked_properties().

Returns

See above; None if these weren’t stored.

get_trajectories() → numpy.ndarray

The collection of all particles’ trajectories.

Returns

See above; None if these weren’t stored.

store_results(particles: List[cminject.base.Particle]) → None

Stores the results of an experiment (which are always a list of modified Particle instances).

Parameters

particles – The list of particles, each in the state of after running a simulation.

Submodules

cminject.result_storages.hdf5 module

Implementations of cminject.base.ResultStorage that store results as HDF5 files.

class cminject.result_storages.hdf5.HDF5ResultStorage(filename: str, mode: str = 'r', force_writable: bool = False, metadata: Optional[Dict[str, Any]] = None)

Bases: cminject.base.ResultStorage

Stores and reads cminject.experiment.Experiment output data into and from an HDF5 file.

Note

Let n be the number of stored particles. The following groups and datasets will be stored:

  • particles (Group): Stores the constant and tracked properties of all particles.

    • properties (Dataset, shape (n,)): The fixed (non-tracked) properties of all particles, see cminject.base.Particle.constant_properties()

    • tracked (Group): Collections storing how the tracked properties, see cminject.base.Particle.tracked_properties(), changed during the simulation. The data type of all datasets in here is the same, as returned by the associated Particle subclass’s cminject.base.Particle.as_dtype() when called with the string ‘tracked’.

      • initial (Dataset, shape (n,)): The initial set of tracked properties

      • final (Dataset, shape (n,)): The final set of tracked properties

      • trajectories (Dataset, shape (n,)): The trajectories of all particles, stored as one variable-length array, since the lengths of the trajectories do not necessarily match. Might contain only empty trajectories if trajectories were not tracked during the simulation!

  • detectors (Group): Stores detector hits of all detectors, one Dataset for each Detector, stored by each Detector’s identifier, id.

    • id (Dataset): All hits on the detector with identifier id. Each entry is one hit, storing all properties of the hit’s Particle using the Particle’s ‘all’ dtype (see cminject.base.Particle.as_dtype(), called with the string ‘all’). Note that one particle can incur multiple hits.

Further attributes can be stored on the root node by passing a dictionary as the “metadata” argument to the constructor.

Warning

For efficient and predictable storage, it’s assumed that all detector hits on each detector return exactly the same shape and dtype. This should probably be the case in any a typical implementation of a detector.

property file_handle

Returns the file handle (a h5py.File instance) that this result storage currently has opened.

Returns

The file handle.

Raises

RuntimeError, if the file handle is not set (e.g., due to the result storage being accessed outside a with-block)

get_detectors() → Dict[str, numpy.ndarray]

The collection of all detectors.

Returns

The detectors, in a dictionary mapping their identifying string to their collection of detected hits.

Note

Detectors that did not detect at least one particle are not necessarily part of the output of this method, and that if there were no detectors or no detector detected at least one particle, None is returned.

get_dimensions() → int

The number of spatial dimensions that the stored simulation had.

get_properties() → numpy.ndarray

The collection of constant particle properties, i.e., the values of their Particle.constant_properties().

Returns

See above; None if these weren’t stored.

get_tracked_final() → numpy.ndarray

The collection of final particle states, i.e., the final values of their Particle.tracked_properties().

Returns

See above; None if these weren’t stored.

get_tracked_initial() → numpy.ndarray

The collection of initial particle states, i.e., the initial values of their Particle.tracked_properties().

Returns

See above; None if these weren’t stored.

get_trajectories() → numpy.ndarray

The collection of all particles’ trajectories.

Returns

See above; None if these weren’t stored.

store_results(particles: List[cminject.base.Particle]) → None

Stores the results of an experiment (which are always a list of modified Particle instances).

Parameters

particles – The list of particles, each in the state of after running a simulation.