Python source class refactor (openmc-dev#2524)

Co-authored-by: Paul Romano <[email protected]>

docs/source/io_formats/settings.rst

@@ -449,24 +449,27 @@ attributes/sub-elements:
 
     *Default*: 1.0
 
+  :type:
+    Indicator of source type. One of ``independent``, ``file``, or ``compiled``.
+
   :particle:
     The source particle type, either ``neutron`` or ``photon``.
 
     *Default*: neutron
 
   :file:
-    If this attribute is given, it indicates that the source is to be read from
-    a binary source file whose path is given by the value of this element. Note,
-    the number of source sites needs to be the same as the number of particles
-    simulated in a fission source generation.
+    If this attribute is given, it indicates that the source type is ``file``,
+    meaning particles are to be read from a binary source file whose path is
+    given by the value of this element.
 
     *Default*: None
 
   :library:
-    If this attribute is given, it indicates that the source is to be
-    instantiated from an externally compiled source function. This source can be
-    as complex as is required to define the source for your problem. The library
-    has a few basic requirements:
+    If this attribute is given, it indicates that the source type is
+    ``compiled``, meaning that particles are instantiated from an externally
+    compiled source function. This source can be completely customized as needed
+    to define the source for your problem. The library has a few basic
+    requirements:
 
     * It must contain a class that inherits from ``openmc::Source``;
     * The class must implement a function called ``sample()``;
@@ -476,14 +479,12 @@ attributes/sub-elements:
 
     More documentation on how to build sources can be found in :ref:`custom_source`.
 
-    *Default*: None
-
   :parameters:
-    If this attribute is given, it provides the parameters to pass through to the
-    class generated using the ``library`` parameter . More documentation on how to
-    build parametrized sources can be found in :ref:`parameterized_custom_source`.
-
-    *Default*: None
+    If this attribute is given, it indicated that the source type is
+    ``compiled``. Its value provides the parameters to pass through to the class
+    generated using the ``library`` parameter. More documentation on how to
+    build parametrized sources can be found in
+    :ref:`parameterized_custom_source`.
 
   :space:
     An element specifying the spatial distribution of source sites. This element

examples/assembly/assembly.py

@@ -112,7 +112,7 @@ def assembly_model():
     model.settings.batches = 150
     model.settings.inactive = 50
     model.settings.particles = 1000
-    model.settings.source = openmc.Source(space=openmc.stats.Box(
+    model.settings.source = openmc.IndependentSource(space=openmc.stats.Box(
         (-pitch/2, -pitch/2, -1),
         (pitch/2, pitch/2, 1),
         only_fissionable=True

examples/custom_source/build_xml.py

@@ -18,7 +18,7 @@
 settings.run_mode = 'fixed source'
 settings.batches = 10
 settings.particles = 1000
-source = openmc.Source()
+source = openmc.IndependentSource()
 source.library = 'build/libsource.so'
 settings.source = source
 settings.export_to_xml()

examples/parameterized_custom_source/build_xml.py

@@ -18,7 +18,7 @@
 settings.run_mode = 'fixed source'
 settings.batches = 10
 settings.particles = 1000
-source = openmc.Source()
+source = openmc.IndependentSource()
 source.library = 'build/libparameterized_source.so'
 source.parameters = 'radius=3.0, energy=14.08e6'
 settings.source = source

include/openmc/source.h

@@ -115,26 +115,26 @@ class FileSource : public Source {
 //! Wrapper for custom sources that manages opening/closing shared library
 //==============================================================================
 
-class CustomSourceWrapper : public Source {
+class CompiledSourceWrapper : public Source {
 public:
   // Constructors, destructors
-  CustomSourceWrapper(std::string path, std::string parameters);
-  ~CustomSourceWrapper();
+  CompiledSourceWrapper(std::string path, std::string parameters);
+  ~CompiledSourceWrapper();
 
   // Defer implementation to custom source library
   SourceSite sample(uint64_t* seed) const override
   {
-    return custom_source_->sample(seed);
+    return compiled_source_->sample(seed);
   }
 
-  double strength() const override { return custom_source_->strength(); }
+  double strength() const override { return compiled_source_->strength(); }
 
 private:
   void* shared_library_; //!< library from dlopen
-  unique_ptr<Source> custom_source_;
+  unique_ptr<Source> compiled_source_;
 };
 
-typedef unique_ptr<Source> create_custom_source_t(std::string parameters);
+typedef unique_ptr<Source> create_compiled_source_t(std::string parameters);
 
 //==============================================================================
 // Functions

openmc/examples.py

@@ -76,7 +76,7 @@ def pwr_pin_cell():
     model.settings.batches = 10
     model.settings.inactive = 5
     model.settings.particles = 100
-    model.settings.source = openmc.Source(space=openmc.stats.Box(
+    model.settings.source = openmc.IndependentSource(space=openmc.stats.Box(
         [-pitch/2, -pitch/2, -1], [pitch/2, pitch/2, 1], only_fissionable=True))
 
     plot = openmc.Plot.from_geometry(model.geometry)
@@ -415,7 +415,7 @@ def pwr_core():
     model.settings.batches = 10
     model.settings.inactive = 5
     model.settings.particles = 100
-    model.settings.source = openmc.Source(space=openmc.stats.Box(
+    model.settings.source = openmc.IndependentSource(space=openmc.stats.Box(
         [-160, -160, -183], [160, 160, 183]))
 
     plot = openmc.Plot()
@@ -527,7 +527,7 @@ def pwr_assembly():
     model.settings.batches = 10
     model.settings.inactive = 5
     model.settings.particles = 100
-    model.settings.source = openmc.Source(space=openmc.stats.Box(
+    model.settings.source = openmc.IndependentSource(space=openmc.stats.Box(
         [-pitch/2, -pitch/2, -1], [pitch/2, pitch/2, 1], only_fissionable=True))
 
     plot = openmc.Plot()
@@ -629,7 +629,7 @@ def slab_mg(num_regions=1, mat_names=None, mgxslib_name='2g.h5'):
     INF = 1000.
     bounds = [0., -INF, -INF, rads[0], INF, INF]
     uniform_dist = openmc.stats.Box(bounds[:3], bounds[3:])
-    settings_file.source = openmc.source.Source(space=uniform_dist)
+    settings_file.source = openmc.IndependentSource(space=uniform_dist)
 
     settings_file.output = {'summary': False}
 

openmc/settings.py

@@ -13,8 +13,8 @@
 import openmc.checkvalue as cv
 from openmc.stats.multivariate import MeshSpatial
 
-from . import (RegularMesh, Source, VolumeCalculation, WeightWindows,
-               WeightWindowGenerator)
+from . import (RegularMesh, SourceBase, IndependentSource,
+               VolumeCalculation, WeightWindows, WeightWindowGenerator)
 from ._xml import clean_indentation, get_text, reorder_attributes
 from openmc.checkvalue import PathLike
 from .mesh import _read_meshes
@@ -150,7 +150,7 @@ class Settings:
         The type of calculation to perform (default is 'eigenvalue')
     seed : int
         Seed for the linear congruential pseudorandom number generator
-    source : Iterable of openmc.Source
+    source : Iterable of openmc.SourceBase
         Distribution of source sites in space, angle, and energy
     sourcepoint : dict
         Options for writing source points. Acceptable keys are:
@@ -265,7 +265,7 @@ def __init__(self, **kwargs):
         self._max_order = None
 
         # Source subelement
-        self._source = cv.CheckedList(Source, 'source distributions')
+        self._source = cv.CheckedList(SourceBase, 'source distributions')
 
         self._confidence_intervals = None
         self._electron_treatment = None
@@ -459,14 +459,14 @@ def max_order(self, max_order: Optional[int]):
         self._max_order = max_order
 
     @property
-    def source(self) -> typing.List[Source]:
+    def source(self) -> typing.List[SourceBase]:
         return self._source
 
     @source.setter
-    def source(self, source: typing.Union[Source, typing.Iterable[Source]]):
+    def source(self, source: typing.Union[SourceBase, typing.Iterable[SourceBase]]):
         if not isinstance(source, MutableSequence):
             source = [source]
-        self._source = cv.CheckedList(Source, 'source distributions', source)
+        self._source = cv.CheckedList(SourceBase, 'source distributions', source)
 
     @property
     def confidence_intervals(self) -> bool:
@@ -969,7 +969,7 @@ def weight_window_generators(self, wwgs):
         if not isinstance(wwgs, MutableSequence):
             wwgs = [wwgs]
         self._weight_window_generators = cv.CheckedList(WeightWindowGenerator, 'weight window generators', wwgs)
-        
+
     def _create_run_mode_subelement(self, root):
         elem = ET.SubElement(root, "run_mode")
         elem.text = self._run_mode.value
@@ -1024,7 +1024,7 @@ def _create_max_order_subelement(self, root):
     def _create_source_subelement(self, root):
         for source in self.source:
             root.append(source.to_xml_element())
-            if isinstance(source.space, MeshSpatial):
+            if isinstance(source, IndependentSource) and isinstance(source.space, MeshSpatial):
                 path = f"./mesh[@id='{source.space.mesh.id}']"
                 if root.find(path) is None:
                     root.append(source.space.mesh.to_xml_element())
@@ -1402,7 +1402,7 @@ def _keff_trigger_from_xml_element(self, root):
 
     def _source_from_xml_element(self, root, meshes=None):
         for elem in root.findall('source'):
-            src = Source.from_xml_element(elem, meshes)
+            src = SourceBase.from_xml_element(elem, meshes)
             # add newly constructed source object to the list
             self.source.append(src)