Refactor ParticleType to use PDG Monte Carlo numbering scheme

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>();
 }

examples/parameterized_custom_source/parameterized_source_ring.cpp

@@ -1,63 +1,65 @@
-#include <cmath> // for M_PI
+#include <cmath>  // for M_PI
 #include <memory> // for unique_ptr
 #include <unordered_map>
 
+#include "openmc/particle.h"
 #include "openmc/random_lcg.h"
 #include "openmc/source.h"
-#include "openmc/particle.h"
 
 class RingSource : public openmc::Source {
-  public:
-    RingSource(double radius, double energy) : radius_(radius), energy_(energy) { }
-
-    // Defines a function that can create a unique pointer to a new instance of this class
-    // by extracting the parameters from the provided string.
-    static std::unique_ptr<RingSource> from_string(std::string parameters)
-    {
-      std::unordered_map<std::string, std::string> parameter_mapping;
-
-      std::stringstream ss(parameters);
-      std::string parameter;
-      while (std::getline(ss, parameter, ',')) {
-        parameter.erase(0, parameter.find_first_not_of(' '));
-        std::string key = parameter.substr(0, parameter.find_first_of('='));
-        std::string value = parameter.substr(parameter.find_first_of('=') + 1, parameter.length());
-        parameter_mapping[key] = value;
-      }
-
-      double radius = std::stod(parameter_mapping["radius"]);
-      double energy = std::stod(parameter_mapping["energy"]);
-      return std::make_unique<RingSource>(radius, energy);
-    }
+public:
+  RingSource(double radius, double energy) : radius_(radius), energy_(energy) {}
+
+  // Defines a function that can create a unique pointer to a new instance of
+  // this class by extracting the parameters from the provided string.
+  static std::unique_ptr<RingSource> from_string(std::string parameters)
+  {
+    std::unordered_map<std::string, std::string> parameter_mapping;
 
-    // Samples from an instance of this class.
-    openmc::SourceSite sample(uint64_t* seed) const
-    {
-      openmc::SourceSite particle;
-      // particle type
-      particle.particle = openmc::ParticleType::neutron;
-      // position
-      double angle = 2.0 * M_PI * openmc::prn(seed);
-      double radius = this->radius_;
-      particle.r.x = radius * std::cos(angle);
-      particle.r.y = radius * std::sin(angle);
-      particle.r.z = 0.0;
-      // angle
-      particle.u = {1.0, 0.0, 0.0};
-      particle.E = this->energy_;
-
-      return particle;
+    std::stringstream ss(parameters);
+    std::string parameter;
+    while (std::getline(ss, parameter, ',')) {
+      parameter.erase(0, parameter.find_first_not_of(' '));
+      std::string key = parameter.substr(0, parameter.find_first_of('='));
+      std::string value =
+        parameter.substr(parameter.find_first_of('=') + 1, parameter.length());
+      parameter_mapping[key] = value;
     }
 
-  private:
-    double radius_;
-    double energy_;
+    double radius = std::stod(parameter_mapping["radius"]);
+    double energy = std::stod(parameter_mapping["energy"]);
+    return std::make_unique<RingSource>(radius, energy);
+  }
+
+  // Samples from an instance of this class.
+  openmc::SourceSite sample(uint64_t* seed) const
+  {
+    openmc::SourceSite particle;
+    // particle type
+    particle.particle = openmc::ParticleType::neutron();
+    // position
+    double angle = 2.0 * M_PI * openmc::prn(seed);
+    double radius = this->radius_;
+    particle.r.x = radius * std::cos(angle);
+    particle.r.y = radius * std::sin(angle);
+    particle.r.z = 0.0;
+    // angle
+    particle.u = {1.0, 0.0, 0.0};
+    particle.E = this->energy_;
+
+    return particle;
+  }
+
+private:
+  double radius_;
+  double energy_;
 };
 
-// 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 RingSource::from_string(parameters);
 }

include/openmc/capi.h

@@ -201,8 +201,8 @@ int openmc_weight_windows_set_energy_bounds(
   int32_t index, double* e_bounds, size_t e_bounds_size);
 int openmc_weight_windows_get_energy_bounds(
   int32_t index, const double** e_bounds, size_t* e_bounds_size);
-int openmc_weight_windows_set_particle(int32_t index, int particle);
-int openmc_weight_windows_get_particle(int32_t index, int* particle);
+int openmc_weight_windows_set_particle(int32_t index, int32_t particle);
+int openmc_weight_windows_get_particle(int32_t index, int32_t* particle);
 int openmc_weight_windows_get_bounds(int32_t index, const double** lower_bounds,
   const double** upper_bounds, size_t* size);
 int openmc_weight_windows_set_bounds(int32_t index, const double* lower_bounds,
@@ -227,7 +227,7 @@ int openmc_zernike_filter_set_order(int32_t index, int order);
 int openmc_zernike_filter_set_params(
   int32_t index, const double* x, const double* y, const double* r);
 
-int openmc_particle_filter_get_bins(int32_t idx, int bins[]);
+int openmc_particle_filter_get_bins(int32_t idx, int32_t bins[]);
 
 //! Sets the mesh and energy grid for CMFD reweight
 //! \param[in] meshtyally_id id of CMFD Mesh Tally

include/openmc/constants.h

@@ -25,16 +25,16 @@ using double_4dvec = vector<vector<vector<vector<double>>>>;
 constexpr int HDF5_VERSION[] {3, 0};
 
 // Version numbers for binary files
-constexpr array<int, 2> VERSION_STATEPOINT {18, 1};
-constexpr array<int, 2> VERSION_PARTICLE_RESTART {2, 0};
-constexpr array<int, 2> VERSION_TRACK {3, 0};
+constexpr array<int, 2> VERSION_STATEPOINT {18, 2};
+constexpr array<int, 2> VERSION_PARTICLE_RESTART {2, 1};
+constexpr array<int, 2> VERSION_TRACK {3, 1};
 constexpr array<int, 2> VERSION_SUMMARY {6, 1};
 constexpr array<int, 2> VERSION_VOLUME {1, 0};
 constexpr array<int, 2> VERSION_VOXEL {2, 0};
 constexpr array<int, 2> VERSION_MGXS_LIBRARY {1, 0};
 constexpr array<int, 2> VERSION_PROPERTIES {1, 1};
 constexpr array<int, 2> VERSION_WEIGHT_WINDOWS {1, 0};
-constexpr array<int, 2> VERSION_COLLISION_TRACK {1, 0};
+constexpr array<int, 2> VERSION_COLLISION_TRACK {1, 1};
 
 // ============================================================================
 // ADJUSTABLE PARAMETERS

include/openmc/nuclide.h

@@ -163,7 +163,7 @@ bool multipole_in_range(const Nuclide& nuc, double E);
 namespace data {
 
 // Minimum/maximum transport energy for each particle type. Order corresponds to
-// that of the ParticleType enum
+// transport_index() for supported transport particles.
 extern array<double, 4> energy_min;
 extern array<double, 4> energy_max;
 

include/openmc/particle.h

@@ -126,10 +126,6 @@ class Particle : public ParticleData {
 //! Functions
 //============================================================================
 
-std::string particle_type_to_str(ParticleType type);
-
-ParticleType str_to_particle_type(std::string str);
-
 void add_surf_source_to_bank(Particle& p, const Surface& surf);
 
 } // namespace openmc