From 56fa60983dce7cc606c794e43f5cf144fa29f105 Mon Sep 17 00:00:00 2001
From: Paul Romano <paul.k.romano@gmail.com>
Date: Mon, 8 Mar 2021 09:45:31 -0600
Subject: [PATCH] Add doc section on file-based sources

---
 docs/source/usersguide/settings.rst | 25 +++++++++++++++++++++++++
 openmc/source.py                    |  4 ++++
 2 files changed, 29 insertions(+)

diff --git a/docs/source/usersguide/settings.rst b/docs/source/usersguide/settings.rst
index 1f9636d393..84fc6ff475 100644
--- a/docs/source/usersguide/settings.rst
+++ b/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
diff --git a/openmc/source.py b/openmc/source.py
index 3d544f3a18..415aacd96c 100644
--- a/openmc/source.py
+++ b/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')])