Add documentation

This describes the general concept of serialization and gives an example
of how to write a source_sampling function that deserializes the input
and uses values set via the serialized form.

docs/source/io_formats/settings.rst

@@ -468,6 +468,19 @@ attributes/sub-elements:
 
     *Default*: None
 
+  :serialization:
+    If this attribute is given, it indicates that the source is to be
+    instantiated from an externally compiled source function, with parameters
+    defined by a serialized form of the source. The serialized source will be
+    read from a file in the location provided by this attribute. In this case,
+    the ``sample_source()`` function must take as input an additional character
+    array containing the serialization that OpenMC will have read from the
+    provided file. 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`.
+
+    *Default*: None
+
   :space:
     An element specifying the spatial distribution of source sites. This element
     has the following attributes:

docs/source/usersguide/settings.rst

@@ -235,6 +235,56 @@ 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:
+
+Custom Serialized 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 (XML, JSON,
+etc.) in order to avoid recompiling the source library for each run. This is
+supported by defining the ``source_sampling`` function with an additional
+parameter that receives the serialized form of the source:
+
+.. code-block:: c++
+
+   // you must have external C linkage here
+   extern "C" openmc::Particle::Bank sample_source(uint64_t* seed, char* serialized_source) {
+     // function to deserialize the source
+     SerializedSource source = SerializedSource::from_xml(serialized_source);
+
+     openmc::Particle::Bank particle;
+     // wgt
+     particle.particle = openmc::Particle::Type::neutron;
+     particle.wgt = 1.0;
+     // position
+     double angle = 2. * M_PI * openmc::prn(seed);
+
+     // get the radius from the serialized form of the source
+     double radius = source.radius();
+     particle.r.x = radius * std::cos(angle);
+     particle.r.y = radius * std::sin(angle);
+     particle.r.z = 0.0;
+     // angle
+     particle.u = {1.0, 0.0, 0.0};
+
+     // get the energy from the serialized form of the source
+     particle.E = source.energy();
+     particle.delayed_group = 0;
+
+     return particle;
+   }
+
+The details of the serialization routine, in particular the schema of the source
+are to be defined by the implementation of the serializable source class. The
+location of the serialized representation of the source to be used must be
+provided via the :attr:`openmc.Source.serialization` attribute, along with the
+custom source library location in :attr:`openmc.Source.library`.
+
+When defining a class to be implemented via this deserialization approach, care
+must be taken to ensure that unique symbols in the resulting binary are
+discoverable when the ``sample_source`` function is loaded via ``dlsym``.
+
 ---------------
 Shannon Entropy
 ---------------