Update documentation around use of source classes (#2679)

docs/source/io_formats/settings.rst

@@ -508,14 +508,15 @@ attributes/sub-elements:
       as a unique pointer. This function can be used to pass parameters through to
       the source from the XML, if needed.
 
-    More documentation on how to build sources can be found in :ref:`custom_source`.
+    More documentation on how to build sources can be found in
+    :ref:`compiled_source`.
 
   :parameters:
     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`.
+    :ref:`parameterized_compiled_source`.
 
   :space:
     An element specifying the spatial distribution of source sites. This element

docs/source/pythonapi/base.rst

@@ -21,7 +21,10 @@ Simulation Settings
    :nosignatures:
    :template: myclass.rst
 
-   openmc.Source
+   openmc.SourceBase
+   openmc.IndependentSource
+   openmc.FileSource
+   openmc.CompiledSource
    openmc.SourceParticle
    openmc.VolumeCalculation
    openmc.Settings
@@ -42,9 +45,6 @@ Material Specification
    :nosignatures:
    :template: myclass.rst
 
-   openmc.Nuclide
-   openmc.Element
-   openmc.Macroscopic
    openmc.Material
    openmc.Materials
 

docs/source/usersguide/settings.rst

@@ -169,16 +169,19 @@ External Source Distributions
 
 External source distributions can be specified through the
 :attr:`Settings.source` attribute. If you have a single external source, you can
-create an instance of :class:`openmc.Source` and use it to set the
-:attr:`Settings.source` attribute. If you have multiple external sources with
-varying source strengths, :attr:`Settings.source` should be set to a list of
-:class:`openmc.Source` objects.
-
-The :class:`openmc.Source` class has four main attributes that one can set:
-:attr:`Source.space`, which defines the spatial distribution,
-:attr:`Source.angle`, which defines the angular distribution,
-:attr:`Source.energy`, which defines the energy distribution, and
-:attr:`Source.time`, which defines the time distribution.
+create an instance of any of the subclasses of :class:`openmc.SourceBase`
+(:class:`openmc.IndependentSource`, :class:`openmc.FileSource`,
+:class:`openmc.CompiledSource`) and use it to set the :attr:`Settings.source`
+attribute. If you have multiple external sources with varying source strengths,
+:attr:`Settings.source` should be set to a list of :class:`openmc.SourceBase`
+objects.
+
+The :class:`openmc.IndependentSource` class is the primary class for defining
+source distributions and has four main attributes that one can set:
+:attr:`IndependentSource.space`, which defines the spatial distribution,
+:attr:`IndependentSource.angle`, which defines the angular distribution,
+:attr:`IndependentSource.energy`, which defines the energy distribution, and
+:attr:`IndependentSource.time`, which defines the time distribution.
 
 The spatial distribution can be set equal to a sub-class of
 :class:`openmc.stats.Spatial`; common choices are :class:`openmc.stats.Point` or
@@ -232,10 +235,10 @@ would run::
   source.time = openmc.stats.Uniform(0, 1e-6)
   settings.source = source
 
-The :class:`openmc.Source` class also has a :attr:`Source.strength` attribute
-that indicates the relative strength of a source distribution if multiple are
-used. For example, to create two sources, one that should be sampled 70% of the
-time and another that should be sampled 30% of the time::
+All subclasses of :class:`openmc.SourceBase` have a :attr:`SourceBase.strength`
+attribute that indicates the relative strength of a source distribution if
+multiple are used. For example, to create two sources, one that should be
+sampled 70% of the time and another that should be sampled 30% of the time::
 
   src1 = openmc.IndependentSource()
   src1.strength = 0.7
@@ -247,9 +250,9 @@ time and another that should be sampled 30% of the time::
 
   settings.source = [src1, src2]
 
-Finally, the :attr:`Source.particle` attribute can be used to indicate the
-source should be composed of particles other than neutrons. For example, the
-following would generate a photon source::
+Finally, the :attr:`IndependentSource.particle` attribute can be used to
+indicate the source should be composed of particles other than neutrons. For
+example, the following would generate a photon source::
 
   source = openmc.IndependentSource()
   source.particle = 'photon'
@@ -263,10 +266,10 @@ For a full list of all classes related to statistical distributions, see
 File-based Sources
 ------------------
 
-OpenMC can use a pregenerated HDF5 source file by specifying the ``filename``
-argument to :class:`openmc.Source`::
+OpenMC can use a pregenerated HDF5 source file through the
+:class:`openmc.FileSource` class::
 
-  settings.source = openmc.IndependentSource(filename='source.h5')
+  settings.source = openmc.FileSource('source.h5')
 
 Statepoint and source files are generated automatically when a simulation is run
 and can be used as the starting source in a new simulation. Alternatively, a
@@ -286,10 +289,10 @@ attribute::
 In this example, at most 10,000 source particles are stored when particles cross
 surfaces with IDs of 1, 2, or 3.
 
-.. _custom_source:
+.. _compiled_source:
 
-Custom Sources
---------------
+Compiled Sources
+----------------
 
 It is often the case that one may wish to simulate a complex source distribution
 that is not possible to represent with the classes described above. For these
@@ -305,7 +308,7 @@ below.
   #include "openmc/source.h"
   #include "openmc/particle.h"
 
-  class CustomSource : public openmc::Source
+  class CompiledSource : public openmc::Source
   {
     openmc::SourceSite sample(uint64_t* seed) const
     {
@@ -327,9 +330,9 @@ below.
     }
   };
 
-  extern "C" std::unique_ptr<CustomSource> openmc_create_source(std::string parameters)
+  extern "C" std::unique_ptr<CompiledSource> openmc_create_source(std::string parameters)
   {
-    return std::make_unique<CustomSource>();
+    return std::make_unique<CompiledSource>();
   }
 
 The above source creates monodirectional 14.08 MeV neutrons that are distributed
@@ -356,19 +359,21 @@ OpenMC shared library. This can be done by writing a CMakeLists.txt file:
    target_link_libraries(source OpenMC::libopenmc)
 
 After running ``cmake`` and ``make``, you will have a libsource.so (or .dylib)
-file in your build directory. Setting the :attr:`openmc.Source.library`
-attribute to the path of this shared library will indicate that it should be
-used for sampling source particles at runtime.
+file in your build directory. You can then use this as an external source during
+an OpenMC run by passing the path of the shared library to the
+:class:`openmc.CompiledSource` class, which is then set as the
+:attr:`Settings.source` attribute::
 
-.. _parameterized_custom_source:
+  settings.source = openmc.CompiledSource('libsource.so')
 
-Custom Parameterized Sources
-----------------------------
+.. _parameterized_compiled_source:
 
-Some custom sources may have values (parameters) that can be changed between
-runs. This is supported by using the ``openmc_create_source()`` function to
-pass parameters defined in the :attr:`openmc.Source.parameters` attribute to
-the source class when it is created:
+Parameterized Compiled Sources
+------------------------------
+
+Some compiled sources may have values (parameters) that can be changed between
+runs. This is supported by using the ``openmc_create_source()`` function to pass
+parameters to the source class when it is created:
 
 .. code-block:: c++
 
@@ -377,9 +382,9 @@ the source class when it is created:
   #include "openmc/source.h"
   #include "openmc/particle.h"
 
-  class CustomSource : public openmc::Source {
+  class CompiledSource : public openmc::Source {
   public:
-    CustomSource(double energy) : energy_{energy} { }
+    CompiledSource(double energy) : energy_{energy} { }
 
     // Samples from an instance of this class.
     openmc::SourceSite sample(uint64_t* seed) const
@@ -404,13 +409,16 @@ the source class when it is created:
     double energy_;
   };
 
-  extern "C" std::unique_ptr<CustomSource> openmc_create_source(std::string parameter) {
+  extern "C" std::unique_ptr<CompiledSource> openmc_create_source(std::string parameter) {
     double energy = std::stod(parameter);
-    return std::make_unique<CustomSource>(energy);
+    return std::make_unique<CompiledSource>(energy);
   }
 
-As with the basic custom source functionality, the custom source library
-location must be provided in the :attr:`openmc.Source.library` attribute.
+When creating an instance of the :class:`openmc.CompiledSource` class, you will
+need to pass both the path of the shared library as well as the parameters as a
+string, which gets passed down to the ``openmc_create_source()`` function::
+
+  settings.source = openmc.CompiledSource('libsource.so', '3.5e6')
 
 .. _usersguide_entropy:
 

docs/source/usersguide/tallies.rst

@@ -318,9 +318,9 @@ The following tables show all valid scores:
     |                      |NJOY's HEATR module.                               |
     +----------------------+---------------------------------------------------+
     |pulse-height          |The energy deposited by an entire photon's history |
-    |                      |(including its progeny). Units are eV per source   | 
+    |                      |(including its progeny). Units are eV per source   |
     |                      |particle. Note that this score can only be combined|
-    |                      |with a cell filter and an energy filter.           |   
+    |                      |with a cell filter and an energy filter.           |
     +----------------------+---------------------------------------------------+
 
 .. _usersguide_tally_normalization:
@@ -337,7 +337,7 @@ it is usually straightforward to convert units if the source rate is known. For
 example, if the system being modeled includes a source that is emitting 10\
 :sup:`4` neutrons per second, the tally results just need to be multipled by 10\
 :sup:`4`. This can either be done manually or using the
-:attr:`openmc.Source.strength` attribute.
+:attr:`openmc.SourceBase.strength` attribute.
 
 For a :math:`k`\ -eigenvalue calculation, normalizing tally results is not as
 simple because the source rate is not actually known. Instead, we typically know