Add doc section on file-based sources

docs/source/usersguide/settings.rst

@@ -248,6 +248,31 @@ following would generate a photon source::
 For a full list of all classes related to statistical distributions, see
 :ref:`pythonapi_stats`.
 
+File-based Sources
+------------------
+
+OpenMC can use a pregenerated HDF5 source file by specfying the ``filename``
+argument to :class:`openmc.Source`::
+
+  settings.source = openmc.Source(filename='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
+source file can be manually generated with the :func:`openmc.write_source_file`
+function. This is particularly useful for coupling OpenMC with another program
+that generates a source to be used in OpenMC.
+
+A source file based on particles that cross one or surfaces can be generated
+during a simulation using the :attr:`Settings.surf_source_write` attribute::
+
+  settings.surf_source_write = {
+      'surfaces_ids': [1, 2, 3],
+      'max_particles': 10000
+  }
+
+In this example, at most 10,000 source particles are stored when particles cross
+surfaces with IDs of 1, 2, or 3.
+
 .. _custom_source:
 
 Custom Sources

openmc/source.py

@@ -298,6 +298,10 @@ def write_source_file(source_particles, filename, **kwargs):
     **kwargs
         Keyword arguments to pass to :class:`h5py.File`
 
+    See Also
+    --------
+    openmc.SourceParticle
+
     """
     # Create compound datatype for source particles
     pos_dtype = np.dtype([('x', '<f8'), ('y', '<f8'), ('z', '<f8')])