Refactor ParticleType to use PDG Monte Carlo numbering scheme (#3756)

Co-authored-by: GuySten <62616591+GuySten@users.noreply.github.com>
Co-authored-by: Amanda Lund <alund1187@gmail.com>

Author: 3 people

CMakeLists.txt

@@ -372,6 +372,7 @@ list(APPEND libopenmc_SOURCES
   src/particle.cpp
   src/particle_data.cpp
   src/particle_restart.cpp
+  src/particle_type.cpp
   src/photon.cpp
   src/physics.cpp
   src/physics_common.cpp

docs/source/io_formats/collision_track.rst

@@ -10,7 +10,7 @@ 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.
+The current revision of the collision track file format is 1.1.
 
 **/**
 
@@ -37,9 +37,9 @@ The current revision of the collision track file format is 1.0.
               - ``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.
+              - ``particle`` (*int32_t*) -- Particle type (PDG number).
+              - ``parent_id`` (*int64_t*) -- Unique ID of the parent particle.
+              - ``progeny_id`` (*int64_t*) -- 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

docs/source/io_formats/particle_restart.rst

@@ -4,7 +4,7 @@
 Particle Restart File Format
 ============================
 
-The current version of the particle restart file format is 2.0.
+The current version of the particle restart file format is 2.1.
 
 **/**
 
@@ -26,8 +26,7 @@ The current version of the particle restart file format is 2.0.
            - **run_mode** (*char[]*) -- Run mode used, either 'fixed source',
              'eigenvalue', or 'particle restart'.
            - **id** (*int8_t*) -- Unique identifier of the particle.
-           - **type** (*int*) -- Particle type (0=neutron, 1=photon, 2=electron,
-             3=positron)
+           - **type** (*int32_t*) -- Particle type (PDG number)
            - **weight** (*double*) -- Weight of the particle.
            - **energy** (*double*) -- Energy of the particle in eV for
              continuous-energy mode, or the energy group of the particle for

docs/source/io_formats/settings.rst

@@ -721,7 +721,10 @@ attributes/sub-elements:
     is present.
 
   :particle:
-    The source particle type, either ``neutron`` or ``photon``.
+    The source particle type, specified as a PDG number or a string alias (e.g.,
+    ``neutron``/``n``, ``photon``/``gamma``, ``electron``, ``positron``,
+    ``proton``/``p``, ``deuteron``/``d``, ``triton``/``t``, ``alpha``, or GNDS
+    nuclide names like ``Fe57``).
 
     *Default*: neutron
 
@@ -1537,7 +1540,8 @@ sub-elements/attributes:
     *Default*: None
 
   :particle_type:
-    The particle that the weight windows will apply to (e.g., 'neutron')
+    The particle that the weight windows will apply to, specified as a PDG
+    code or string (e.g., ``neutron``).
 
     *Default*: 'neutron'
 
@@ -1597,7 +1601,8 @@ mesh-based weight windows.
     *Default*: None
 
   :particle_type:
-    The particle that the weight windows will apply to (e.g., 'neutron')
+    The particle that the weight windows will apply to, specified as a PDG
+    code or string (e.g., ``neutron``).
 
     *Default*: neutron
 

docs/source/io_formats/source.rst

@@ -15,12 +15,14 @@ following the same format.
 **/**
 
 :Attributes: - **filetype** (*char[]*) -- String indicating the type of file.
+             - **version** (*int[2]*) -- Major and minor version of the source
+               file format.
 
 :Datasets:
 
            - **source_bank** (Compound type) -- Source bank information for each
              particle. The compound type has fields ``r``, ``u``, ``E``,
              ``time``, ``wgt``, ``delayed_group``, ``surf_id`` and ``particle``,
              which represent the position, direction, energy, time, weight,
-             delayed group, surface ID, and particle type (0=neutron, 1=photon,
-             2=electron, 3=positron), respectively.
+             delayed group, surface ID, and particle type (PDG number),
+             respectively.

docs/source/io_formats/statepoint.rst

@@ -4,7 +4,7 @@
 State Point File Format
 =======================
 
-The current version of the statepoint file format is 18.1.
+The current version of the statepoint file format is 18.2.
 
 **/**
 
@@ -56,8 +56,8 @@ The current version of the statepoint file format is 18.1.
              ``time``, ``wgt``, ``delayed_group``, ``surf_id``, and
              ``particle``, which represent the position, direction, energy,
              time, weight, delayed group, surface ID, and particle type
-             (0=neutron, 1=photon, 2=electron, 3=positron), respectively. Only
-             present when `run_mode` is 'eigenvalue'.
+             (PDG number), respectively. Only present when `run_mode` is
+             'eigenvalue'.
 
 **/tallies/**
 

docs/source/io_formats/tallies.rst

@@ -318,8 +318,8 @@ should be set to:
   they use ``energy`` and ``y``.
 
 :particle:
-  A list of integers indicating the type of particles to tally ('neutron' = 1,
-  'photon' = 2, 'electron' = 3, 'positron' = 4).
+  A list of particle identifiers to tally, specified as strings (e.g.,
+  ``neutron``, ``photon``, ``He4``) or as integer PDG numbers.
 
 ------------------
 ``<mesh>`` Element

docs/source/io_formats/track.rst

@@ -4,7 +4,7 @@
 Track File Format
 =================
 
-The current revision of the particle track file format is 3.0.
+The current revision of the particle track file format is 3.1.
 
 **/**
 
@@ -32,6 +32,5 @@ The current revision of the particle track file format is 3.0.
                             the array for each primary/secondary particle. The
                             last offset should match the total size of the
                             array.
-                          - **particles** (*int[]*) -- Particle type for each
-                            primary/secondary particle (0=neutron, 1=photon,
-                            2=electron, 3=positron).
+                          - **particles** (*int32_t[]*) -- Particle type for
+                            each primary/secondary particle (PDG number).

docs/source/usersguide/settings.rst

@@ -400,7 +400,7 @@ below.
     {
       openmc::SourceSite particle;
       // weight
-      particle.particle = openmc::ParticleType::neutron;
+      particle.particle = openmc::ParticleType::neutron();
       particle.wgt = 1.0;
       // position
       double angle = 2.0 * M_PI * openmc::prn(seed);
@@ -477,7 +477,7 @@ parameters to the source class when it is created:
     {
       openmc::SourceSite particle;
       // weight
-      particle.particle = openmc::ParticleType::neutron;
+      particle.particle = openmc::ParticleType::neutron();
       particle.wgt = 1.0;
       // position
       particle.r.x = 0.0;

examples/custom_source/source_ring.cpp

@@ -1,17 +1,16 @@
-#include <cmath> // for M_PI
+#include <cmath>  // for M_PI
 #include <memory> // for unique_ptr
 
+#include "openmc/particle.h"
 #include "openmc/random_lcg.h"
 #include "openmc/source.h"
-#include "openmc/particle.h"
 
-class RingSource : public openmc::Source
-{
+class RingSource : public openmc::Source {
   openmc::SourceSite sample(uint64_t* seed) const
   {
     openmc::SourceSite particle;
     // particle type
-    particle.particle = openmc::ParticleType::neutron;
+    particle.particle = openmc::ParticleType::neutron();
     // position
     double angle = 2.0 * M_PI * openmc::prn(seed);
     double radius = 3.0;
@@ -25,10 +24,11 @@ class RingSource : public openmc::Source
   }
 };
 
-// A function to create a unique pointer to an instance of this class when generated
-// via a plugin call using dlopen/dlsym.
-// You must have external C linkage here otherwise dlopen will not find the file
-extern "C" std::unique_ptr<RingSource> openmc_create_source(std::string parameters)
+// A function to create a unique pointer to an instance of this class when
+// generated via a plugin call using dlopen/dlsym. You must have external C
+// linkage here otherwise dlopen will not find the file
+extern "C" std::unique_ptr<RingSource> openmc_create_source(
+  std::string parameters)
 {
   return std::make_unique<RingSource>();
 }