From fd9172927c560bdf6f4af717ab0a419392954d7d Mon Sep 17 00:00:00 2001
From: Paul Romano <paul.k.romano@gmail.com>
Date: Wed, 27 Sep 2023 14:44:37 -0500
Subject: [PATCH] Fix volume calculation IO format docs and
 `sample_external_source` bug (#2713)

---
 docs/source/io_formats/settings.rst | 47 ++++++++++++++++++++++++-----
 src/source.cpp                      |  5 +++
 2 files changed, 44 insertions(+), 8 deletions(-)

diff --git a/docs/source/io_formats/settings.rst b/docs/source/io_formats/settings.rst
index 226e9084e44..03abe9a3c4f 100644
--- a/docs/source/io_formats/settings.rst
+++ b/docs/source/io_formats/settings.rst
@@ -1068,8 +1068,14 @@ The ``<volume_calc>`` element indicates that a stochastic volume calculation
 should be run at the beginning of the simulation. This element has the following
 sub-elements/attributes:
 
-  :cells:
-    The unique IDs of cells for which the volume should be estimated.
+  :domain_type:
+    The type of each domain for the volume calculation ("cell", "material", or
+    "universe").
+
+    *Default*: None
+
+  :domain_ids:
+    The unique IDs of domains for which the volume should be estimated.
 
     *Default*: None
 
@@ -1079,16 +1085,41 @@ sub-elements/attributes:
     *Default*: None
 
   :lower_left:
-     The lower-left Cartesian coordinates of a bounding box that is used to
-     sample points within.
+    The lower-left Cartesian coordinates of a bounding box that is used to
+    sample points within.
 
-     *Default*: None
+    *Default*: None
 
   :upper_right:
-     The upper-right Cartesian coordinates of a bounding box that is used to
-     sample points within.
+    The upper-right Cartesian coordinates of a bounding box that is used to
+    sample points within.
 
-     *Default*: None
+    *Default*: None
+
+  :threshold:
+    Presence of a ``<threshold>`` sub-element indicates that the volume
+    calculation will be halted based on a threshold on the error. It has the
+    following sub-elements/attributes:
+
+    :type:
+      The type of the trigger. Accepted options are "variance", "std_dev",
+      and "rel_err".
+
+      :variance:
+        Variance of the mean, :math:`\sigma^2`
+
+      :std_dev:
+        Standard deviation of the mean, :math:`\sigma`
+
+      :rel_err:
+        Relative error of the mean, :math:`\frac{\sigma}{\mu}`
+
+      *Default*: None
+
+    :threshold:
+      The trigger's convergence criterion for the given type.
+
+      *Default*: None
 
 ----------------------------
 ``<weight_windows>`` Element
diff --git a/src/source.cpp b/src/source.cpp
index 817847b7618..3251ca0d0d8 100644
--- a/src/source.cpp
+++ b/src/source.cpp
@@ -457,6 +457,11 @@ extern "C" int openmc_sample_external_source(
     return OPENMC_E_INVALID_ARGUMENT;
   }
 
+  if (model::external_sources.empty()) {
+    set_errmsg("No external sources have been defined.");
+    return OPENMC_E_OUT_OF_BOUNDS;
+  }
+
   auto sites_array = static_cast<SourceSite*>(sites);
   for (size_t i = 0; i < n; ++i) {
     sites_array[i] = sample_external_source(seed);