crp/OpenMC
1
0
Fork 0
mirror of https://github.com/openmc-dev/openmc.git synced 2026-07-27 13:45:36 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update documentation around use of source classes (#2679)

Browse source
This commit is contained in:
Paul Romano 2023-09-01 21:43:19 -05:00 • committed by GitHub
parent 20877c61a1
commit 7a13bf6f0f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 59 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

5
docs/source/io_formats/settings.rst
View file

@ -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

8
docs/source/pythonapi/base.rst
View file

@ -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

90
docs/source/usersguide/settings.rst
View file

@ -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.
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.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.
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:

6
docs/source/usersguide/tallies.rst
View file

@ -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