crp/OpenMC
1
0
Fork 0
mirror of https://github.com/openmc-dev/openmc.git synced 2026-07-29 06:35:48 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 5

Updates to documentation

Browse source 
Accounts for serialized -> parameterized change.
Simplifies some of the examples to be more appropriate for
documentation.
Removes use of external destroy method.
This commit is contained in:
Dan Short 2020-08-05 15:55:18 +01:00
parent 64a4c96a94
commit 651c8825f3
2 changed files with 27 additions and 63 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -474,15 +474,13 @@ attributes/sub-elements:
defined by the string provided in this attribute. In this case, the
custom source library must define a class that inherits from the
``openmc::CustomSource`` abstract class. This class must implement a
``sample_source()`` function, which takes an array of integers as an
argument. The custom source library must also contain a ``create`` method,
which takes a serialized form of the source (as provided to the parameters
attribute) as an argument and returns a pointer to an instance of the custom
source, and a ``destroy`` method, which takes a pointer to an instance of
the custom source as an argument and deletes the memory allocated to the
custom source. If the library attribute is not provided then this attribute
will be ignored. More documentation on how to build serialized sources can
be found in :ref:`serialized_custom_source`.
``sample_source()`` function, which takes an unsigned integer pointer as an
argument. The custom source library must also contain an
``openmc_create_source`` method, which takes the value provided to the
parameters attribute as an argument and returns a pointer to an instance of
the custom source. If the library attribute is not provided then this
attribute will be ignored. More documentation on how to build parametrized
sources can be found in :ref:`parameterized_custom_source`.
*Default*: None

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

@ -235,55 +235,28 @@ 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.
.. _serialized_custom_source:
.. _parameterized_custom_source:
Custom Serialized Sources
-------------------------
Custom Parameterized Sources
----------------------------
If the custom source may be used with parameters at a variety of values then it
may be necessary to serialize the source to an appropriate format in order to
avoid recompiling the source library for each run. This is supported by defining
a class inheriting from ``openmc::CustomSource`` that implements a
``sample_source`` function. The class should also have logic to deserialise
the parameters provided via the settings.xml file in the
:attr:``openmc.Source.parameters`` attribute:
may be necessary to represent those parameters as a string in order to avoid
recompiling the source library for each run. This is supported by defining a
class inheriting from ``openmc::CustomSource`` that implements a
``sample_source`` function:
.. code-block:: c++
#include <unordered_map>
#include "openmc/random_lcg.h"
#include "openmc/source.h"
#include "openmc/particle.h"
class SerializedSource : public openmc::CustomSource {
protected:
double energy_;
// Protect the constructor so that the class can only be created by serialisation.
SerializedSource(double energy) {
energy_ = energy;
}
class ParameterizedSource : public openmc::CustomSource {
public:
// Getters for the values that we want to use in sampling.
double energy() { return energy_; }
// Defines a function that can create a pointer to a new instance of this class
// by deserializing from the provided string.
static SerializedSource* from_string(const char* 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;
}
return new SerializedSource(std::stod(parameter_mapping["energy"]));
double energy;
ParameterizedSource(double energy) {
this->energy = energy;
}
// Samples from an instance of this class.
@ -298,32 +271,25 @@ the parameters provided via the settings.xml file in the
particle.r.z = 0.0;
// angle
particle.u = {1.0, 0.0, 0.0};
particle.E = this->energy();
particle.E = this->energy;
particle.delayed_group = 0;
return particle;
}
};
The custom source library function in this case must also define a ``create``
method and a ``destroy`` method. The ``create`` method will be used to
generate an instance of the custom source, based on the value supplied in
the :attr:``openmc.Source.parameters`` attribute. The ``destroy`` method
will be used to destroy that instance once the sampling has completed. Both
must be defined with ``extern "C"``:
The custom source library function in this case must also define an
``openmc_create_source`` method, which will be used to generate an instance of
the custom source, based on the value supplied in the
:attr:``openmc.Source.parameters`` attribute. The
``openmc_create_source`` method must be defined with ``extern "C"``:
.. code-block:: c++
// you must have external C linkage here otherwise
// dlopen will not find the file
extern "C" SerializedSource* create(const char* serialized_source) {
return SerializedSource::from_string(serialized_source);
}
// you must have external C linkage here otherwise
// dlopen will not find the file
extern "C" void destroy(SerializedSource* source) {
delete source;
extern "C" ParameterizedSource* openmc_create_source(const char* parameterized_source) {
return new ParameterizedSource(std::stod(parameters));
}
As with the basic custom source functionality, the custom source library