From 106bb0dbe8027c6ddc95386bdac715d90d066ac6 Mon Sep 17 00:00:00 2001
From: Paul Romano <paul.k.romano@gmail.com>
Date: Wed, 1 Mar 2017 21:14:33 -0600
Subject: [PATCH] Address a few comments from @wbinventor

---
 docs/source/pythonapi/index.rst |  3 ++-
 openmc/executor.py              | 24 ++++++++++++++++++++----
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/docs/source/pythonapi/index.rst b/docs/source/pythonapi/index.rst
index 1b13dfbfe..d07cf60d3 100644
--- a/docs/source/pythonapi/index.rst
+++ b/docs/source/pythonapi/index.rst
@@ -57,6 +57,7 @@ Simulation Settings
 
    openmc.Source
    openmc.ResonanceScattering
+   openmc.VolumeCalculation
    openmc.Settings
 
 Material Specification
@@ -185,7 +186,7 @@ Running OpenMC
    :template: myfunction.rst
 
    openmc.run
-   openmc.run_volume_calculation
+   openmc.calculate_volumes
    openmc.plot_geometry
 
 Post-processing
diff --git a/openmc/executor.py b/openmc/executor.py
index f0ea91370..9bd97ca1d 100644
--- a/openmc/executor.py
+++ b/openmc/executor.py
@@ -1,10 +1,11 @@
 from __future__ import print_function
 import subprocess
 from numbers import Integral
-import sys
 
 from six import string_types
 
+from openmc import VolumeCalculation
+
 _summary_indicator = "TIMING STATISTICS"
 
 
@@ -56,9 +57,20 @@ def plot_geometry(output=True, openmc_exec='openmc', cwd='.'):
     return _run([openmc_exec, '-p'], output, cwd)
 
 
-def run_volume_calculation(threads=None, output=True, cwd='.',
-                           openmc_exec='openmc', mpi_args=None):
-    """Run stochastic volume calculations in OpenMC
+def calculate_volumes(threads=None, output=True, cwd='.',
+                      openmc_exec='openmc', mpi_args=None):
+    """Run stochastic volume calculations in OpenMC.
+
+    This function runs OpenMC in stochastic volume calculation mode. To specify
+    the parameters of a volume calculation, one must first create a
+    :class:`openmc.VolumeCalculation` instance and assign it to
+    :attr:`openmc.Settings.volume_calculations`. For example:
+
+    >>> vol = openmc.VolumeCalculation(domains=[cell1, cell2], samples=100000)
+    >>> settings = openmc.Settings()
+    >>> settings.volume_calculations = [vol]
+    >>> settings.export_to_xml()
+    >>> openmc.calculate_volumes()
 
     Parameters
     ----------
@@ -78,6 +90,10 @@ def run_volume_calculation(threads=None, output=True, cwd='.',
         Path to working directory to run in. Defaults to the current working
         directory.
 
+    See Also
+    --------
+    openmc.VolumeCalculation
+
     """
     args = [openmc_exec, '--volume']