From 7a13bf6f0fa17b57f549517c1df8e478a69b32a2 Mon Sep 17 00:00:00 2001 From: Paul Romano Date: Fri, 1 Sep 2023 21:43:19 -0500 Subject: [PATCH] Update documentation around use of source classes (#2679) --- docs/source/io_formats/settings.rst | 5 +- docs/source/pythonapi/base.rst | 8 +-- docs/source/usersguide/settings.rst | 92 ++++++++++++++++------------- docs/source/usersguide/tallies.rst | 6 +- 4 files changed, 60 insertions(+), 51 deletions(-) diff --git a/docs/source/io_formats/settings.rst b/docs/source/io_formats/settings.rst index a52de1b9048..db90d93dc0d 100644 --- a/docs/source/io_formats/settings.rst +++ b/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 diff --git a/docs/source/pythonapi/base.rst b/docs/source/pythonapi/base.rst index ffd521a7583..afecaff5333 100644 --- a/docs/source/pythonapi/base.rst +++ b/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 diff --git a/docs/source/usersguide/settings.rst b/docs/source/usersguide/settings.rst index 69089d14d33..81fa78991a7 100644 --- a/docs/source/usersguide/settings.rst +++ b/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 openmc_create_source(std::string parameters) + extern "C" std::unique_ptr openmc_create_source(std::string parameters) { - return std::make_unique(); + return std::make_unique(); } 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 openmc_create_source(std::string parameter) { + extern "C" std::unique_ptr openmc_create_source(std::string parameter) { double energy = std::stod(parameter); - return std::make_unique(energy); + return std::make_unique(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: diff --git a/docs/source/usersguide/tallies.rst b/docs/source/usersguide/tallies.rst index 28ce6795fc0..02328af58ca 100644 --- a/docs/source/usersguide/tallies.rst +++ b/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