From 198df07311cc5747e8eb5915c8dcb209b5fdeb63 Mon Sep 17 00:00:00 2001
From: Paul Romano <paul.k.romano@gmail.com>
Date: Thu, 9 Nov 2017 15:53:57 -0600
Subject: [PATCH] Add subdivide convenience function

---
 docs/source/pythonapi/index.rst |  8 ++++----
 docs/source/pythonapi/model.rst | 10 ++++++++++
 openmc/capi/core.py             |  2 +-
 openmc/model/__init__.py        |  1 +
 openmc/model/funcs.py           | 25 +++++++++++++++++++++++++
 5 files changed, 41 insertions(+), 5 deletions(-)
 create mode 100644 openmc/model/funcs.py

diff --git a/docs/source/pythonapi/index.rst b/docs/source/pythonapi/index.rst
index bb99dd470..862acb238 100644
--- a/docs/source/pythonapi/index.rst
+++ b/docs/source/pythonapi/index.rst
@@ -40,13 +40,13 @@ Modules
 -------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    base
-   stats
-   mgxs
    model
+   examples
+   mgxs
+   stats
    data
    capi
-   examples
    openmoc
diff --git a/docs/source/pythonapi/model.rst b/docs/source/pythonapi/model.rst
index 6e589b7eb..55a5d17b1 100644
--- a/docs/source/pythonapi/model.rst
+++ b/docs/source/pythonapi/model.rst
@@ -2,6 +2,16 @@
 :mod:`openmc.model` -- Model Building
 -------------------------------------
 
+Convenience Functions
+---------------------
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: myfunction.rst
+
+   openmc.model.subdivide
+
 TRISO Fuel Modeling
 -------------------
 
diff --git a/openmc/capi/core.py b/openmc/capi/core.py
index 77c9ca7a4..1f7225f64 100644
--- a/openmc/capi/core.py
+++ b/openmc/capi/core.py
@@ -17,7 +17,6 @@ class _Bank(Structure):
                 ('delayed_group', c_int)]
 
 
-
 _dll.openmc_calculate_volumes.restype = None
 _dll.openmc_finalize.restype = None
 _dll.openmc_find.argtypes = [POINTER(c_double*3), c_int, POINTER(c_int32),
@@ -168,6 +167,7 @@ def keff():
     _dll.openmc_get_keff(k)
     return tuple(k)
 
+
 def next_batch():
     """Run next batch."""
     return _dll.openmc_next_batch()
diff --git a/openmc/model/__init__.py b/openmc/model/__init__.py
index 557effcef..9fa999dd4 100644
--- a/openmc/model/__init__.py
+++ b/openmc/model/__init__.py
@@ -1,2 +1,3 @@
 from .triso import *
 from .model import *
+from .funcs import *
diff --git a/openmc/model/funcs.py b/openmc/model/funcs.py
new file mode 100644
index 000000000..d9755b0e8
--- /dev/null
+++ b/openmc/model/funcs.py
@@ -0,0 +1,25 @@
+def subdivide(surfaces):
+    """Create regions separated by a series of surfaces.
+
+    This function allows regions to be constructed from a set of a surfaces that
+    are "in order". For example, if you had four instances of
+    :class:`openmc.ZPlane` at z=-10, z=-5, z=5, and z=10, this function would
+    return a list of regions corresponding to z < -10, -10 < z < -5, -5 < z < 5,
+    5 < z < 10, and 10 < z. That is, for n surfaces, n+1 regions are returned.
+
+    Parameters
+    ----------
+    surfaces : sequence of openmc.Surface
+        Surfaces separating regions
+
+    Returns
+    -------
+    list of openmc.Region
+        Regions formed by the given surfaces
+
+    """
+    regions = [-surfaces[0]]
+    for s0, s1 in zip(surfaces[:-1], surfaces[1:]):
+        regions.append(+s0 & -s1)
+    regions.append(+surfaces[-1])
+    return regions