Addition of a collision tracking feature (#3417)

Co-authored-by: Paul Romano <paul.k.romano@gmail.com>

docs/source/io_formats/collision_track.rst

@@ -0,0 +1,46 @@
+.. _io_collision_track:
+
+===========================
+Collision Track File Format
+===========================
+
+When collision tracking is enabled with ``mcpl=false`` (the default), OpenMC
+writes binary data to an HDF5 file named ``collision_track.h5``. The same data
+may also be written after each batch when multiple files are requested
+(``collision_track.N.h5``) or when the run is performed in parallel. The file
+contains the information needed to reconstruct each recorded collision.
+
+The current revision of the collision track file format is 1.0.
+
+**/**
+
+:Attributes:
+            - **filetype** (*char[]*) -- String indicating the type of file.
+              For collision-track files the value is ``"collision_track"``.
+
+:Datasets:
+
+          - **collision_track_bank** (Compound type) -- Collision information
+            for each stored event. Each entry in the dataset corresponds to one
+            collision and contains the following fields:
+
+              - ``r`` (*double[3]*) -- Position of the collision in [cm].
+              - ``u`` (*double[3]*) -- Direction unit vector immediately after the collision.
+              - ``E`` (*double*) -- Incident particle energy before the collision in [eV].
+              - ``dE`` (*double*) -- Energy loss over the collision (:math:`E_\text{before} - E_\text{after}`) in [eV].
+              - ``time`` (*double*) -- Time of the collision in [s].
+              - ``wgt`` (*double*) -- Particle weight at the collision.
+              - ``event_mt`` (*int*) -- ENDF MT number identifying the reaction.
+              - ``delayed_group`` (*int*) -- Delayed neutron group index (non-zero for delayed events).
+              - ``cell_id`` (*int*) -- ID of the cell in which the collision occurred.
+              - ``nuclide_id`` (*int*) -- ZA identifier of the nuclide (ZZZAAAM format).
+              - ``material_id`` (*int*) -- ID of the material containing the collision site.
+              - ``universe_id`` (*int*) -- ID of the universe containing the collision site.
+              - ``n_collision`` (*int*) -- Collision counter for the particle history.
+              - ``particle`` (*int*) -- Particle type (0=neutron, 1=photon, 2=electron, 3=positron).
+              - ``parent_id`` (*int64*) -- Unique ID of the parent particle.
+              - ``progeny_id`` (*int64*) -- Progeny ID of the particle.
+
+In an MPI run, OpenMC writes the combined dataset by gathering collision-track
+entries from all ranks before flushing them to disk, so the final file appears
+as though it were produced serially.

docs/source/io_formats/index.rst

@@ -44,6 +44,7 @@ Output Files
 
    statepoint
    source
+   collision_track
    summary
    properties
    depletion_results

docs/source/io_formats/settings.rst

@@ -20,6 +20,85 @@ source neutrons.
 
   *Default*: None
 
+-----------------------------
+``<collision_track>`` Element
+-----------------------------
+
+The ``<collision_track>`` element indicates to track information about particle
+collisions based on a set of criteria and store these events in a file named
+``collision_track.h5``. This file records details such as the position of the
+interaction, direction of the incoming particle, incident energy and deposited
+energy, weight, time of the interaction, and the delayed neutron group (0 for
+prompt neutrons). Additional information such as the cell ID, material ID,
+universe ID, nuclide ZAID, particle type, and event MT number are also stored.
+Users can specify one or more criterion to filter collisions. If no criteria are
+specified, it defaults to tracking all collisions across the model.
+
+.. warning::
+    Storing all collisions can be very memory intensive. For more targeted
+    tracking, users can employ a variety of parameters such as ``cell_ids``,
+    ``reactions``, ``universe_ids``, ``material_ids``, ``nuclides``, and
+    ``deposited_E_threshold`` to refine the selection of particle interactions
+    to be banked.
+
+This element can contain one or more of the following attributes or
+sub-elements:
+
+  :max_collisions:
+    An integer indicating the maximum number of collisions to be banked per file.
+
+    *Default*: 1000
+
+  :max_collision_track_files:
+    An integer indicating the number of collision_track files to be used.
+
+    *Default*: 1
+
+  :mcpl:
+    An optional boolean to enable MCPL_-format instead of the native HDF5-based
+    format. If activated, the output file name and type is changed to
+    ``collision_track.mcpl``.
+
+    *Default*: false
+
+    .. _MCPL: https://mctools.github.io/mcpl/mcpl.pdf
+
+  :cell_ids:
+    A list of integers representing cell IDs to define specific cells in which
+    collisions are to be banked.
+
+    *Default*: None
+
+  :universe_ids:
+    A list of integers representing the universe IDs to define specific
+    universes in which collisions are to be banked.
+
+    *Default*: None
+
+  :material_ids:
+    A list of integers representing the material IDs to define specific
+    materials in which collisions are to be banked.
+
+    *Default*: None
+
+  :nuclides:
+    A list of strings representing the nuclide, to define specific
+    define specific target nuclide collisions to be banked.
+
+    *Default*: None
+
+  :reactions:
+    A list of integers representing the ENDF-6 format MT numbers or strings
+    (e.g. (n,fission)) to define specific reaction types to be banked.
+
+    *Default*: None
+
+  :deposited_E_threshold:
+    A float defining the minimum deposited energy per collision (in eV) to
+    trigger banking.
+
+    *Default*: 0.0
+
 ----------------------------------
 ``<confidence_intervals>`` Element
 ----------------------------------

docs/source/pythonapi/base.rst

@@ -216,6 +216,9 @@ Post-processing
    :nosignatures:
    :template: myfunction.rst
 
+   openmc.read_collision_track_file
+   openmc.read_collision_track_hdf5
+   openmc.read_collision_track_mcpl
    openmc.voxel_to_vtk
 
 The following classes and functions are used for functional expansion reconstruction.

docs/source/usersguide/settings.rst

@@ -756,6 +756,62 @@ instance, whereas the :meth:`openmc.Track.filter` method returns a new
             track_files = [f"tracks_p{rank}.h5" for rank in range(32)]
             openmc.Tracks.combine(track_files, "tracks.h5")
 
+Collision Track File
+---------------------
+
+OpenMC can generate a collision track file that contains detailed collision
+information (position, direction, energy, deposited energy, time, weight, cell
+ID, material ID, universe ID, nuclide ZAID, particle type, particle delayed
+group and particle ID) for each particle collision depending on user-defined
+parameters. To invoke this feature, set the
+:attr:`~openmc.Settings.collision_track` attribute as shown in this example::
+
+  settings.collision_track = {
+      "max_collisions": 300,
+      "reactions": ["(n,fission)", "(n,2n)"],
+      "material_ids": [1,2],
+      "nuclides": ["U238", "O16"],
+      "cell_ids": [5, 12]
+  }
+
+In this example, collision track information is written to the
+collision_track.h5 file at the end of the simulation. The file contains
+300 recorded collisions that occurred in materials with IDs 1 or 2, involving
+fission or (n,2n) reactions on the nuclides U-238 or O-16, within cells
+with IDs 5 and 12.
+The file can be read using :func:`openmc.read_collision_track_file`.
+The example below shows how to extract the data from the collision_track
+feature and displays the fields stored in the file:
+
+>>> data = openmc.read_collision_track_file('collision_track.h5')
+>>> data.dtype
+    dtype([('r', [('x', '<f8'), ('y', '<f8'), ('z', '<f8')]),
+    ('u', [('x', '<f8'), ('y', '<f8'), ('z', '<f8')]), ('E', '<f8'),
+    ('dE', '<f8'), ('time', '<f8'), ('wgt', '<f8'), ('event_mt', '<i4'),
+    ('delayed_group', '<i4'), ('cell_id', '<i4'), ('nuclide_id', '<i4'),
+    ('material_id', '<i4'), ('universe_id', '<i4'), ('n_collision', '<i4'),
+    ('particle', '<i4'), ('parent_id', '<i8'), ('progeny_id', '<i8')])
+
+
+The full list of fields is as follows:
+
+  :r: Position (each direction in [cm])
+  :u: Direction
+  :E: Energy in [eV]
+  :dE: Energy deposited during collision in [eV]
+  :time: Time in [s]
+  :wgt: Weight of the particle
+  :event_mt: Reaction MT number
+  :delayed_group: Delayed group of the particle
+  :cell_id: Cell ID
+  :nuclide_id: Nuclide ID (10000×Z + 10×A + M)
+  :material_id: Material ID
+  :universe_id: Universe ID
+  :n_collision: Number of collision suffered by the particle
+  :particle: Particle type
+  :parent_id: Source particle ID
+  :progeny_id: Progeny ID
+
 -----------------------
 Restarting a Simulation
 -----------------------