From 9b968f7580a817510959f68e086561c815ef7bf2 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 18 Jun 2019 09:45:26 -0500
Subject: [PATCH 001/644] Initial branch commit for persistent APOSMM work;
 starting work outside APOSMM

---
 libensemble/alloc_funcs/start_persistent_local_opt_gens.py      | 2 +-
 libensemble/gen_funcs/uniform_or_localopt.py                    | 1 +
 ...hump_camel_uniform_sampling_with_persistent_localopt_gens.py | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/libensemble/alloc_funcs/start_persistent_local_opt_gens.py b/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
index 3a0bbe0a3..3ddc8a969 100644
--- a/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
+++ b/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
@@ -63,7 +63,7 @@ def start_persistent_local_opt_gens(W, H, sim_specs, gen_specs, alloc_specs, per
         # Start persistent generator for local opt run unless it would use all workers
         if starting_inds and gen_count + 1 < len(W):
             # Start at the best possible starting point
-            ind = starting_inds[np.argmin(H['f'][starting_inds])]
+            ind = np.array([0,1])
             gen_work(Work, i,
                      sim_specs['in'] + [n[0] for n in sim_specs['out']],
                      np.atleast_1d(ind), persis_info[i], persistent=True)
diff --git a/libensemble/gen_funcs/uniform_or_localopt.py b/libensemble/gen_funcs/uniform_or_localopt.py
index 7c6950634..c839c26d1 100644
--- a/libensemble/gen_funcs/uniform_or_localopt.py
+++ b/libensemble/gen_funcs/uniform_or_localopt.py
@@ -20,6 +20,7 @@ def uniform_or_localopt(H, persis_info, gen_specs, libE_info):
     """
 
     if libE_info.get('persistent'):
+        import ipdb; ipdb.set_trace()
         x_opt, persis_info_updates, tag_out = try_and_run_nlopt(H, gen_specs, libE_info)
         O = []
         return O, persis_info_updates, tag_out
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
index bcaa94c91..c17878827 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
@@ -53,7 +53,7 @@
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
-exit_criteria = {'sim_max': 1000, 'elapsed_wallclock_time': 300}
+exit_criteria = {'sim_max': 1000}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,

From 968237200d3924eaccfa2d4604d21a4d54b9d6bf Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 28 Jun 2019 14:50:18 -0500
Subject: [PATCH 002/644] WIP: starts a mp implementation of the asynchronous
 runs;

---
 libensemble/libE_worker.py | 58 ++++++++++++++++++++++++++++++++------
 1 file changed, 50 insertions(+), 8 deletions(-)

diff --git a/libensemble/libE_worker.py b/libensemble/libE_worker.py
index 9e217fcf0..30a9273b6 100644
--- a/libensemble/libE_worker.py
+++ b/libensemble/libE_worker.py
@@ -170,7 +170,11 @@ def _handle_calc(self, Work, calc_in):
             with timer:
                 with self.loc_stack.loc(calc_type):
                     logger.debug("Calling calc {}".format(calc_type))
+                    # this would be stuck here.
+                    # I would fork here.
                     out = calc(calc_in, Work['persis_info'], Work['libE_info'])
+                    # when do I join.
+                    # So every time I get an inpt.
                     logger.debug("Return from calc call")
 
             assert isinstance(out, tuple), \
@@ -251,17 +255,55 @@ def run(self):
             logger.info("Worker {} initiated on node {}".
                         format(self.workerID, socket.gethostname()))
 
+            rank = self.comm.get_Rank()
+            from multiprocessing import Process
+
             for worker_iter in count(start=1):
+                # This 'for' loop is like a while loop.
                 logger.debug("Iteration {}".format(worker_iter))
 
-                mtag, Work = self.comm.recv()
-                if mtag == STOP_TAG:
-                    break
-
-                response = self._handle(Work)
-                if response is None:
-                    break
-                self.comm.send(0, response)
+                if rank == 1:
+                    #FIXME: this will not work always, we need to 
+                    # persistent mode operation
+                    mtag, Work = self.comm.recv()
+                    if mtag == STOP_TAG:
+                        break
+
+                    # what does this repsonse stand for?
+                    # this is where we fork?
+                    # yep
+
+                    p = Process(target=self._handle, args=(Work,))
+                    p.start()
+                    # Ok..
+                    # Things to do: append the result of the run to one of our
+                    # variables
+
+                    # response = self._handle(Work)
+                    if response is None:
+                        break
+
+                    # this is where we send.
+                    self.comm.send(0, response)
+                    p.join()
+                else:
+                    mtag, Work = self.comm.recv()
+                    if mtag == STOP_TAG:
+                        break
+
+                    # what does this repsonse stand for?
+                    # this is where we fork?
+                    # yep
+
+                    response = self._handle(Work)
+                    if response is None:
+                        break
+
+                    print(response)
+                    1/0
+
+                    # this is where we send.
+                    self.comm.send(0, response)
 
         except Exception as e:
             self.comm.send(0, WorkerErrMsg(str(e), format_exc()))

From ec9425b9b9707a81e72a9ed39903eaa0662181d8 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 5 Jul 2019 08:24:07 -0500
Subject: [PATCH 003/644] Reverting some changes

---
 .../alloc_funcs/start_only_persistent.py      |  8 +--
 .../start_persistent_local_opt_gens.py        |  2 +-
 .../gen_funcs/persistent_uniform_sampling.py  |  1 +
 libensemble/gen_funcs/uniform_or_localopt.py  |  1 -
 libensemble/libE_worker.py                    | 58 +++----------------
 ..._sampling_with_persistent_localopt_gens.py |  5 +-
 6 files changed, 16 insertions(+), 59 deletions(-)

diff --git a/libensemble/alloc_funcs/start_only_persistent.py b/libensemble/alloc_funcs/start_only_persistent.py
index a96186018..9bef765b3 100644
--- a/libensemble/alloc_funcs/start_only_persistent.py
+++ b/libensemble/alloc_funcs/start_only_persistent.py
@@ -13,11 +13,12 @@ def only_persistent_gens(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     :See:
         ``/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py``
     """
+    import ipdb; ipdb.set_trace()
 
     Work = {}
     gen_count = count_persis_gens(W)
 
-    # If i is idle, but in persistent mode, and its calculated values have
+    # If i is in persistent mode, and any of its calculated values have
     # returned, give them back to i. Otherwise, give nothing to i
     for i in avail_worker_ids(W, persistent=True):
         gen_inds = (H['gen_worker'] == i)
@@ -31,14 +32,13 @@ def only_persistent_gens(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     task_avail = ~H['given']
     for i in avail_worker_ids(W, persistent=False):
         if np.any(task_avail):
-
-            # perform sim evaluations from existing runs (if they exist).
+            # perform sim evaluations (if they exist in History).
             sim_ids_to_send = np.nonzero(task_avail)[0][0]  # oldest point
             sim_work(Work, i, sim_specs['in'], np.atleast_1d(sim_ids_to_send), persis_info[i])
             task_avail[sim_ids_to_send] = False
 
         elif gen_count == 0:
-            # Finally, generate points since there is nothing else to do.
+            # Finally, call a persistent generator as there is nothing else to do.
             gen_count += 1
             gen_work(Work, i, gen_specs['in'], [], persis_info[i],
                      persistent=True)
diff --git a/libensemble/alloc_funcs/start_persistent_local_opt_gens.py b/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
index 3ddc8a969..3a0bbe0a3 100644
--- a/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
+++ b/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
@@ -63,7 +63,7 @@ def start_persistent_local_opt_gens(W, H, sim_specs, gen_specs, alloc_specs, per
         # Start persistent generator for local opt run unless it would use all workers
         if starting_inds and gen_count + 1 < len(W):
             # Start at the best possible starting point
-            ind = np.array([0,1])
+            ind = starting_inds[np.argmin(H['f'][starting_inds])]
             gen_work(Work, i,
                      sim_specs['in'] + [n[0] for n in sim_specs['out']],
                      np.atleast_1d(ind), persis_info[i], persistent=True)
diff --git a/libensemble/gen_funcs/persistent_uniform_sampling.py b/libensemble/gen_funcs/persistent_uniform_sampling.py
index 3d13916a9..66a8ea21e 100644
--- a/libensemble/gen_funcs/persistent_uniform_sampling.py
+++ b/libensemble/gen_funcs/persistent_uniform_sampling.py
@@ -12,6 +12,7 @@ def persistent_uniform(H, persis_info, gen_specs, libE_info):
     :See:
         ``libensemble/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py``
     """
+    import ipdb; ipdb.set_trace()
     ub = gen_specs['ub']
     lb = gen_specs['lb']
     n = len(lb)
diff --git a/libensemble/gen_funcs/uniform_or_localopt.py b/libensemble/gen_funcs/uniform_or_localopt.py
index c839c26d1..7c6950634 100644
--- a/libensemble/gen_funcs/uniform_or_localopt.py
+++ b/libensemble/gen_funcs/uniform_or_localopt.py
@@ -20,7 +20,6 @@ def uniform_or_localopt(H, persis_info, gen_specs, libE_info):
     """
 
     if libE_info.get('persistent'):
-        import ipdb; ipdb.set_trace()
         x_opt, persis_info_updates, tag_out = try_and_run_nlopt(H, gen_specs, libE_info)
         O = []
         return O, persis_info_updates, tag_out
diff --git a/libensemble/libE_worker.py b/libensemble/libE_worker.py
index 30a9273b6..9e217fcf0 100644
--- a/libensemble/libE_worker.py
+++ b/libensemble/libE_worker.py
@@ -170,11 +170,7 @@ def _handle_calc(self, Work, calc_in):
             with timer:
                 with self.loc_stack.loc(calc_type):
                     logger.debug("Calling calc {}".format(calc_type))
-                    # this would be stuck here.
-                    # I would fork here.
                     out = calc(calc_in, Work['persis_info'], Work['libE_info'])
-                    # when do I join.
-                    # So every time I get an inpt.
                     logger.debug("Return from calc call")
 
             assert isinstance(out, tuple), \
@@ -255,55 +251,17 @@ def run(self):
             logger.info("Worker {} initiated on node {}".
                         format(self.workerID, socket.gethostname()))
 
-            rank = self.comm.get_Rank()
-            from multiprocessing import Process
-
             for worker_iter in count(start=1):
-                # This 'for' loop is like a while loop.
                 logger.debug("Iteration {}".format(worker_iter))
 
-                if rank == 1:
-                    #FIXME: this will not work always, we need to 
-                    # persistent mode operation
-                    mtag, Work = self.comm.recv()
-                    if mtag == STOP_TAG:
-                        break
-
-                    # what does this repsonse stand for?
-                    # this is where we fork?
-                    # yep
-
-                    p = Process(target=self._handle, args=(Work,))
-                    p.start()
-                    # Ok..
-                    # Things to do: append the result of the run to one of our
-                    # variables
-
-                    # response = self._handle(Work)
-                    if response is None:
-                        break
-
-                    # this is where we send.
-                    self.comm.send(0, response)
-                    p.join()
-                else:
-                    mtag, Work = self.comm.recv()
-                    if mtag == STOP_TAG:
-                        break
-
-                    # what does this repsonse stand for?
-                    # this is where we fork?
-                    # yep
-
-                    response = self._handle(Work)
-                    if response is None:
-                        break
-
-                    print(response)
-                    1/0
-
-                    # this is where we send.
-                    self.comm.send(0, response)
+                mtag, Work = self.comm.recv()
+                if mtag == STOP_TAG:
+                    break
+
+                response = self._handle(Work)
+                if response is None:
+                    break
+                self.comm.send(0, response)
 
         except Exception as e:
             self.comm.send(0, WorkerErrMsg(str(e), format_exc()))
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
index c17878827..1f522c336 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
@@ -14,8 +14,7 @@
 # TESTSUITE_COMMS: mpi local tcp
 # TESTSUITE_NPROCS: 3 4
 
-import sys
-import numpy as np
+import sys import numpy as np
 
 # Import libEnsemble main, sim_specs, gen_specs, alloc_specs, and persis_info
 from libensemble.libE import libE
@@ -53,7 +52,7 @@
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
-exit_criteria = {'sim_max': 1000}
+exit_criteria = {'sim_max': 1000, 'elapsed_wallclock_time': 300}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,

From b09c7d0bd224301e3e71b9506d471a23a79d73ba Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 5 Jul 2019 08:26:33 -0500
Subject: [PATCH 004/644] Cleaning up a bit

---
 libensemble/alloc_funcs/start_only_persistent.py               | 1 -
 libensemble/gen_funcs/persistent_uniform_sampling.py           | 1 -
 ...ump_camel_uniform_sampling_with_persistent_localopt_gens.py | 3 ++-
 3 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/libensemble/alloc_funcs/start_only_persistent.py b/libensemble/alloc_funcs/start_only_persistent.py
index 9bef765b3..2d2d93fdc 100644
--- a/libensemble/alloc_funcs/start_only_persistent.py
+++ b/libensemble/alloc_funcs/start_only_persistent.py
@@ -13,7 +13,6 @@ def only_persistent_gens(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     :See:
         ``/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py``
     """
-    import ipdb; ipdb.set_trace()
 
     Work = {}
     gen_count = count_persis_gens(W)
diff --git a/libensemble/gen_funcs/persistent_uniform_sampling.py b/libensemble/gen_funcs/persistent_uniform_sampling.py
index 66a8ea21e..3d13916a9 100644
--- a/libensemble/gen_funcs/persistent_uniform_sampling.py
+++ b/libensemble/gen_funcs/persistent_uniform_sampling.py
@@ -12,7 +12,6 @@ def persistent_uniform(H, persis_info, gen_specs, libE_info):
     :See:
         ``libensemble/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py``
     """
-    import ipdb; ipdb.set_trace()
     ub = gen_specs['ub']
     lb = gen_specs['lb']
     n = len(lb)
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
index 1f522c336..bcaa94c91 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
@@ -14,7 +14,8 @@
 # TESTSUITE_COMMS: mpi local tcp
 # TESTSUITE_NPROCS: 3 4
 
-import sys import numpy as np
+import sys
+import numpy as np
 
 # Import libEnsemble main, sim_specs, gen_specs, alloc_specs, and persis_info
 from libensemble.libE import libE

From 54602bc30615bef35102573776550a3757733c7a Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 5 Jul 2019 08:27:26 -0500
Subject: [PATCH 005/644] Adding new files for persistent aposmm

---
 libensemble/gen_funcs/persistent_aposmm.py    | 890 ++++++++++++++++++
 .../test_6-hump_camel_persistent_aposmm.py    |  55 ++
 2 files changed, 945 insertions(+)
 create mode 100644 libensemble/gen_funcs/persistent_aposmm.py
 create mode 100644 libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
new file mode 100644
index 000000000..fe747da27
--- /dev/null
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -0,0 +1,890 @@
+"""
+This module contains methods used our implementation of the Asynchronously
+Parallel Optimization Solver for finding Multiple Minima (APOSMM) method
+described in detail in the paper
+`https://doi.org/10.1007/s12532-017-0131-4 <https://doi.org/10.1007/s12532-017-0131-4>`_
+"""
+__all__ = ['aposmm_logic', 'initialize_APOSMM',
+           'decide_where_to_start_localopt', 'update_history_dist']
+
+import sys
+import pickle
+import traceback
+import numpy as np
+from scipy.spatial.distance import cdist, pdist, squareform
+from scipy import optimize as scipy_optimize
+
+from mpi4py import MPI
+from petsc4py import PETSc
+
+from numpy.lib.recfunctions import merge_arrays
+
+from math import log, gamma, pi, sqrt
+
+import nlopt
+
+
+class APOSMMException(Exception):
+    "Raised for any exception in APOSMM"
+
+
+def aposmm(H, persis_info, gen_specs, libE_info):
+    """
+    APOSMM coordinates multiple local optimization runs, starting from points
+    which do not have a better point nearby (within a distance ``r_k``). This
+    generation function produces/requires the following fields in ``H``:
+
+    - ``'x' [n floats]``: Parameters being optimized over
+    - ``'x_on_cube' [n floats]``: Parameters scaled to the unit cube
+    - ``'f' [float]``: Objective function being minimized
+    - ``'local_pt' [bool]``: True if point from a local optimization run
+    - ``'dist_to_unit_bounds' [float]``: Distance to domain boundary
+    - ``'dist_to_better_l' [float]``: Dist to closest better local opt point
+    - ``'dist_to_better_s' [float]``: Dist to closest better sample point
+    - ``'ind_of_better_l' [int]``: Index of point ``'dist_to_better_l``' away
+    - ``'ind_of_better_s' [int]``: Index of point ``'dist_to_better_s``' away
+    - ``'started_run' [bool]``: True if point has started a local opt run
+    - ``'num_active_runs' [int]``: Number of active local runs point is in
+    - ``'local_min' [float]``: True if point has been ruled a local minima
+    - ``'sim_id' [int]``: Row number of entry in history
+
+    and optionally
+
+    - ``'priority' [float]``: Value quantifying a point's desirability
+    - ``'f_i' [float]``: Value of ith objective component (if single_component)
+    - ``'fvec' [m floats]``: All objective components (if calculated together)
+    - ``'obj_component' [int]``: Index corresponding to value in ``'f_i``'
+    - ``'pt_id' [int]``: Identify the point (useful when evaluating different
+      objective components for a given ``'x'``)
+
+    When using libEnsemble to do individual objective component evaluations,
+    APOSMM will return ``gen_specs['components']`` copies of each point, but
+    the component=0 entry of each point will only be considered when
+
+    - deciding where to start a run,
+    - best nearby point,
+    - storing the order of the points is the run
+    - storing the combined objective function value
+    - etc
+
+    Necessary quantities in ``gen_specs`` are:
+
+    - ``'lb' [n floats]``: Lower bound on search domain
+    - ``'ub' [n floats]``: Upper bound on search domain
+    - ``'initial_sample_size' [int]``: Number of uniformly sampled points
+      must be returned (non-nan value) before a local opt run is started
+
+    - ``'localopt_method' [str]``: Name of an NLopt, PETSc/TAO, or SciPy method
+      (see 'advance_local_run' below for supported methods)
+
+    Optional ``gen_specs`` entries are:
+
+    - ``'sample_points' [numpy array]``: Points to be sampled (original domain)
+    - ``'combine_component_func' [func]``: Function to combine obj components
+    - ``'components' [int]``: Number of objective components
+    - ``'dist_to_bound_multiple' [float in (0,1]]``: What fraction of the
+      distance to the nearest boundary should the initial step size be in
+      localopt runs
+    - ``'high_priority_to_best_localopt_runs': [bool]``: True if localopt runs
+      with smallest observed function value are given priority
+    - ``'lhs_divisions' [int]``: Number of Latin hypercube sampling partitions
+      (0 or 1 results in uniform sampling)
+    - ``'min_batch_size' [int]``: Lower bound on the number of points given
+      every time APOSMM is called
+    - ``'mu' [float]``: Distance from the boundary that all localopt starting
+      points must satisfy
+    - ``'nu' [float]``: Distance from identified minima that all starting
+      points must satisfy
+    - ``'single_component_at_a_time' [bool]``: True if single objective
+      components will be evaluated at a time
+    - ``'rk_const' [float]``: Multiplier in front of the r_k value
+    - ``'max_active_runs' [int]``: Bound on number of runs APOSMM is advancing
+
+    And ``gen_specs`` convergence tolerances for NLopt, PETSc/TAO, SciPy
+
+    - ``'fatol' [float]``:
+    - ``'ftol_abs' [float]``:
+    - ``'ftol_rel' [float]``:
+    - ``'gatol' [float]``:
+    - ``'grtol' [float]``:
+    - ``'xtol_abs' [float]``:
+    - ``'xtol_rel' [float]``:
+    - ``'tol' [float]``:
+
+
+    As a default, APOSMM starts a local optimization runs from a point that:
+
+    - is not in an active local optimization run,
+    - is more than ``mu`` from the boundary (in the unit-cube domain),
+    - is more than ``nu`` from identified minima (in the unit-cube domain),
+    - does not have a better point within a distance ``r_k`` of it.
+
+    If the above results in more than ``'max_active_runs'`` being advanced, the
+    best point in each run is determined and the dist_to_better is computed
+    (with inf being the value for the best run). Then those
+    ``'max_active_runs'`` runs with largest dist_to_better are advanced
+    (breaking ties arbitrarily).
+
+    :Note:
+        ``gen_specs['combine_component_func']`` must be defined when there are
+        multiple objective components.
+
+    :Note:
+        APOSMM critically uses ``persis_info`` to store information about
+        active runs, order of points in each run, etc. The allocation function
+        must ensure it's always given.
+
+    :See:
+        ``libensemble/tests/regression_tests/test_branin_aposmm.py``
+        for basic APOSMM usage.
+    :See:
+        ``libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py``
+        for an example of APOSMM coordinating multiple local optimization runs
+        for an objective with more than one component.
+    """
+    """
+    Description of intermediate variables in aposmm_logic:
+
+    n:                domain dimension
+    c_flag:           True if giving libEnsemble individual components of fvec
+                      to evaluate. (Note if c_flag is True, APOSMM will use
+                      only the component to store the function value f)
+    n_s:              the number of complete evaluations of sampled points
+    updated_inds:     indices of H that have been updated (and so all their
+                      information must be sent back to libE manager to update)
+    O:                new points to be sent back to the history
+
+
+    When re-running a local opt method to get the next point:
+    advance_local_run.x_new:      stores the first new point requested by
+                                  a local optimization method
+    advance_local_run.pt_in_run:  counts function evaluations to know
+                                  when a new point is given
+
+    starting_inds:    indices where a runs should be started.
+    active_runs:      indices of active local optimization runs
+    sorted_run_inds:  indices of the considered run (in the order they were
+                      requested by the localopt method)
+    x_opt:            the reported minimum from a localopt run (disregarded
+                      unless exit_code isn't 0)
+    exit_code:        0 if a new localopt point has been found, otherwise it's
+                      the NLopt/TAO/SciPy code
+    samples_needed:   Number of additional uniformly drawn samples needed
+
+
+    Description of persistent variables used to maintain the state of APOSMM
+
+    persis_info['total_runs']: Running count of started/completed localopt runs
+    persis_info['run_order']: Sequence of indices of points in unfinished runs
+    persis_info['old_runs']: Sequence of indices of points in finished runs
+
+    """
+    import ipdb; ipdb.set_trace()
+
+    n, n_s, c_flag, rk_const, mu, nu, comm = initialize_APOSMM(H, gen_specs, libE_info)
+
+    tag = None
+
+    while tag not in [STOP_TAG, PERSIS_STOP]:
+        n_s = count_samples(H,gen_specs)
+
+        if n_s >= gen_specs['initial_sample_size']:
+            update_history_dist(H, n, gen_specs, c_flag)
+
+            starting_inds = decide_where_to_start_localopt(H, n_s, rk_const, mu, nu)
+
+            for ind in starting_inds:
+                # Mark point as having started a run
+                new_run_num = total_runs
+                total_runs += 1
+                H['started_run'][ind] = 1
+                run_order[new_run_num] = [ind]
+
+                # Initialize child process for new localopt run
+                x_new = start_localopt(H, gen_specs, c_flag)
+
+                # Send x_new to manager for evaluation
+                O = np.zeros(1, dtype=gen_specs['out'])
+                add_to_O(O, x_new, H, gen_specs, c_flag, persis_info, local_flag=1)
+                tag, Work, calc_in = send_mgr_worker_msg(comm, O)
+
+            # Receive from manager (if possible), contact child process to get
+            # x_new, and send back to manager
+            get_mgr_worker_msg(comm, status)
+
+        else:
+            O = np.zeros(gen_specs['initial_sample_size'], dtype=gen_specs['out'])
+            sampled_points = persis_info['rand_stream'].uniform(0, 1, (len(O), n))
+            on_cube = True
+            add_to_O(O, sampled_points, H, gen_specs, c_flag, persis_info, on_cube=on_cube)
+
+            tag, Work, calc_in = send_mgr_worker_msg(comm, O)
+
+    return O, persis_info, tag
+
+
+def add_to_O(O, pts, H, gen_specs, c_flag, persis_info, local_flag=0,
+             sorted_run_inds=[], run=[], on_cube=True):
+    """
+    Adds points to O, the numpy structured array to be sent back to the manager
+    """
+
+    assert not local_flag or len(pts) == 1, "Can't > 1 local points"
+
+    original_len_O = len(O)
+
+    len_H = len(H)
+    ub = gen_specs['ub']
+    lb = gen_specs['lb']
+    if c_flag:
+        m = gen_specs['components']
+
+        assert len_H % m == 0, "Number of points in len_H not congruent to 0 mod 'components'"
+        pt_ids = np.sort(np.tile(np.arange((len_H+original_len_O)/m, (len_H+original_len_O)/m+len(pts)), (1, m)))
+        pts = np.tile(pts, (m, 1))
+
+    num_pts = len(pts)
+
+    O.resize(len(O)+num_pts, refcheck=False)  # Adds num_pts rows of zeros to O
+
+    if on_cube:
+        O['x_on_cube'][-num_pts:] = pts
+        O['x'][-num_pts:] = pts*(ub-lb)+lb
+    else:
+        O['x_on_cube'][-num_pts:] = (pts-lb)/(ub-lb)
+        O['x'][-num_pts:] = pts
+
+    O['sim_id'][-num_pts:] = np.arange(len_H+original_len_O, len_H+original_len_O+num_pts)
+    O['local_pt'][-num_pts:] = local_flag
+
+    O['dist_to_unit_bounds'][-num_pts:] = np.inf
+    O['dist_to_better_l'][-num_pts:] = np.inf
+    O['dist_to_better_s'][-num_pts:] = np.inf
+    O['ind_of_better_l'][-num_pts:] = -1
+    O['ind_of_better_s'][-num_pts:] = -1
+
+    if c_flag:
+        O['obj_component'][-num_pts:] = np.tile(range(0, m), (1, num_pts//m))
+        O['pt_id'][-num_pts:] = pt_ids
+
+    if local_flag:
+        O['num_active_runs'][-num_pts] += 1
+        # O['priority'][-num_pts:] = 1
+        # O['priority'][-num_pts:] = np.random.uniform(0,1,num_pts)
+        if 'high_priority_to_best_localopt_runs' in gen_specs and gen_specs['high_priority_to_best_localopt_runs']:
+            O['priority'][-num_pts:] = -min(H['f'][persis_info['run_order'][run]])  # Give highest priority to run with lowest function value
+        else:
+            O['priority'][-num_pts:] = persis_info['rand_stream'].uniform(0, 1, num_pts)
+        persis_info['run_order'][run].append(O[-num_pts]['sim_id'])
+    else:
+        if c_flag:
+            # p_tmp = np.sort(np.tile(np.random.uniform(0,1,num_pts/m),(m,1))) # If you want all "duplicate points" to have the same priority (meaning libEnsemble gives them all at once)
+            # p_tmp = np.random.uniform(0,1,num_pts)
+            p_tmp = persis_info['rand_stream'].uniform(0, 1, num_pts)
+        else:
+            # p_tmp = np.random.uniform(0,1,num_pts)
+            # persis_info['rand_stream'].uniform(lb,ub,(1,n))
+            if 'high_priority_to_best_localopt_runs' in gen_specs and gen_specs['high_priority_to_best_localopt_runs']:
+                p_tmp = -np.inf*np.ones(num_pts)
+            else:
+                p_tmp = persis_info['rand_stream'].uniform(0, 1, num_pts)
+        O['priority'][-num_pts:] = p_tmp
+        # O['priority'][-num_pts:] = 1
+
+    return persis_info
+
+
+def update_history_dist(H, n, gen_specs, c_flag):
+    """
+    Updates distances/indices after new points that have been evaluated.
+
+    :See:
+        ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
+    """
+
+    new_inds = np.where(~H['known_to_aposmm'])[0]
+
+    if c_flag:
+        for v in np.unique(H['pt_id'][new_inds]):
+            inds = H['pt_id'] == v
+            H['f'][inds] = np.inf
+            H['f'][np.where(inds)[0][0]] = gen_specs['combine_component_func'](H['f_i'][inds])
+
+        p = np.logical_and.reduce((H['returned'], H['obj_component'] == 0, ~np.isnan(H['f'])))
+    else:
+        p = np.logical_and.reduce((H['returned'], ~np.isnan(H['f'])))
+
+    for new_ind in new_inds:
+        # Loop over new returned points and update their distances
+        if p[new_ind]:
+            H['known_to_aposmm'][new_ind] = True
+
+            # Compute distance to boundary
+            H['dist_to_unit_bounds'][new_ind] = min(min(np.ones(n)-H['x_on_cube'][new_ind]), min(H['x_on_cube'][new_ind]-np.zeros(n)))
+
+            dist_to_all = cdist(H['x_on_cube'][[new_ind]], H['x_on_cube'][p], 'euclidean').flatten()
+            new_better_than = H['f'][new_ind] < H['f'][p]
+
+            # Update any other points if new_ind is closer and better
+            if H['local_pt'][new_ind]:
+                inds_of_p = np.logical_and(dist_to_all < H['dist_to_better_l'][p], new_better_than)
+                updates = np.where(p)[0][inds_of_p]
+                H['dist_to_better_l'][updates] = dist_to_all[inds_of_p]
+                H['ind_of_better_l'][updates] = new_ind
+            else:
+                inds_of_p = np.logical_and(dist_to_all < H['dist_to_better_s'][p], new_better_than)
+                updates = np.where(p)[0][inds_of_p]
+                H['dist_to_better_s'][updates] = dist_to_all[inds_of_p]
+                H['ind_of_better_s'][updates] = new_ind
+
+            # Since we allow equality when deciding better_than_new_l and
+            # better_than_new_s, we have to prevent new_ind from being its own
+            # better point.
+            better_than_new_l = np.logical_and.reduce((~new_better_than, H['local_pt'][p], H['sim_id'][p] != new_ind))
+            better_than_new_s = np.logical_and.reduce((~new_better_than, ~H['local_pt'][p], H['sim_id'][p] != new_ind))
+
+            # Who is closest to ind and better
+            if np.any(better_than_new_l):
+                ind = dist_to_all[better_than_new_l].argmin()
+                H['ind_of_better_l'][new_ind] = H['sim_id'][p][np.nonzero(better_than_new_l)[0][ind]]
+                H['dist_to_better_l'][new_ind] = dist_to_all[better_than_new_l][ind]
+
+            if np.any(better_than_new_s):
+                ind = dist_to_all[better_than_new_s].argmin()
+                H['ind_of_better_s'][new_ind] = H['sim_id'][p][np.nonzero(better_than_new_s)[0][ind]]
+                H['dist_to_better_s'][new_ind] = dist_to_all[better_than_new_s][ind]
+
+            # if not ignore_L8:
+            #     r_k = calc_rk(len(H['x_on_cube'][0]), n_s, rk_const, lhs_divisions)
+            #     H['worse_within_rk'][new_ind][p] = np.logical_and.reduce((H['f'][new_ind] <= H['f'][p], dist_to_all <= r_k))
+
+            #     # Add trues if new point is 'worse_within_rk'
+            #     inds_to_change = np.logical_and.reduce((H['dist_to_all'][p,new_ind] <= r_k, H['f'][new_ind] >= H['f'][p], H['sim_id'][p] != new_ind))
+            #     H['worse_within_rk'][inds_to_change,new_ind] = True
+
+            #     if not H['local_pt'][new_ind]:
+            #         H['worse_within_rk'][H['dist_to_all'] > r_k] = False
+
+
+
+def update_history_optimal(x_opt, H, run_inds):
+    """
+    Updated the history after any point has been declared a local minimum
+    """
+
+    # opt_ind = np.where(np.logical_and(np.equal(x_opt,H['x_on_cube']).all(1),~np.isinf(H['f'])))[0] # This fails on some problems. x_opt is 1e-16 away from the point that was given and opt_ind is empty
+    run_inds = np.unique(run_inds)
+
+    dists = np.linalg.norm(H['x_on_cube'][run_inds]-x_opt, axis=1)
+    ind = np.argmin(dists)
+    opt_ind = run_inds[ind]
+
+    if dists[ind] > 1e-15:
+        print("Dist from x_opt to closest point is:"+str(dists[ind]))
+        print("Report this!")
+        print(x_opt)
+        print(run_inds)
+        sys.stdout.flush()
+    assert dists[ind] <= 1e-15, "Closest point to x_opt not within 1e-15?"
+
+    failsafe = np.logical_and(H['f'][run_inds] < H['f'][opt_ind], dists < 1e-8)
+    if np.any(failsafe):
+        # Rare event, but want to not start another run next to a minimum
+        print('Marking more than 1 point in this run as a min!')
+        print("Report this!")
+        sys.stdout.flush()
+        H['local_min'][run_inds[failsafe]] = 1
+
+    H['local_min'][opt_ind] = 1
+    H['num_active_runs'][run_inds] -= 1
+
+
+def advance_local_run(H, gen_specs, c_flag, run, persis_info):
+    """
+    Moves a local optimization method one iteration forward. We currently do
+    this by feeding all past evaluations from a run to the method and then
+    storing the first new point generated
+    """
+
+    while 1:
+        sorted_run_inds = persis_info['run_order'][run]
+        advance_local_run.x_new = np.ones((1, len(gen_specs['ub'])))*np.inf
+        advance_local_run.pt_in_run = 0
+
+        if gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA',
+                                            'LN_COBYLA', 'LN_NELDERMEAD',
+                                            'LD_MMA']:
+
+            if gen_specs['localopt_method'] in ['LD_MMA']:
+                fields_to_pass = ['x_on_cube', 'f', 'grad']
+            else:
+                fields_to_pass = ['x_on_cube', 'f']
+
+            try:
+                x_opt, exit_code = set_up_and_run_nlopt(H[fields_to_pass][sorted_run_inds], gen_specs)
+            except Exception as e:
+                x_opt = 0
+                exit_code = 0
+                display_exception(e)
+
+        elif gen_specs['localopt_method'] in ['pounders']:
+
+            if c_flag:
+                Run_H_F = np.zeros(len(sorted_run_inds), dtype=[('fvec', float, gen_specs['components'])])
+                for i, ind in enumerate(sorted_run_inds):
+                    a1 = H['pt_id'] == H['pt_id'][ind]
+                    Run_H_F['fvec'][i, :] = H['f_i'][a1]
+                Run_H = merge_arrays([H[['x_on_cube']][sorted_run_inds], Run_H_F], flatten=True)
+            else:
+                Run_H = H[['x_on_cube', 'fvec']][sorted_run_inds]
+
+            try:
+                x_opt, exit_code = set_up_and_run_tao(Run_H, gen_specs)
+            except Exception as e:
+                x_opt = 0
+                exit_code = 0
+                display_exception(e)
+
+        elif gen_specs['localopt_method'] == 'scipy_COBYLA':
+
+            fields_to_pass = ['x_on_cube', 'f']
+
+            try:
+                x_opt, exit_code = set_up_and_run_scipy_minimize(H[fields_to_pass][sorted_run_inds], gen_specs)
+            except Exception as e:
+                x_opt = 0
+                exit_code = 0
+                display_exception(e)
+
+        else:
+            raise APOSMMException("Unknown localopt method. Exiting")
+
+        match_ind = np.equal(advance_local_run.x_new, H['x_on_cube']).all(1)
+        if ~match_ind.any():
+            # Generated a new point
+            break
+        else:
+            # We need to add a previously evaluated point into this run
+            persis_info['run_order'][run].append(np.nonzero(match_ind)[0][0])
+
+    return x_opt, exit_code, persis_info, sorted_run_inds, advance_local_run.x_new
+
+
+def set_up_and_run_scipy_minimize(Run_H, gen_specs):
+    """ Set up objective and runs scipy
+
+    Declares the appropriate syntax for our special objective function to read
+    through Run_H, sets the parameters and starting points for the run.
+    """
+
+    def scipy_obj_fun(x, Run_H):
+        out = look_in_history(x, Run_H)
+
+        return out
+
+    obj = lambda x: scipy_obj_fun(x, Run_H)
+    x0 = Run_H['x_on_cube'][0]
+
+    # Construct the bounds in the form of constraints
+    cons = []
+    for factor in range(len(x0)):
+        lo = {'type': 'ineq',
+              'fun': lambda x, lb=gen_specs['lb'][factor], i=factor: x[i]-lb}
+        up = {'type': 'ineq',
+              'fun': lambda x, ub=gen_specs['ub'][factor], i=factor: ub-x[i]}
+        cons.append(lo)
+        cons.append(up)
+
+    method = gen_specs['localopt_method'][6:]
+    res = scipy_optimize.minimize(obj, x0, method=method, options={'maxiter': len(Run_H['x_on_cube'])+1, 'tol': gen_specs['tol']})
+
+    if res['status'] == 2:  # SciPy code for exhausting budget of evaluations, so not at a minimum
+        exit_code = 0
+    else:
+        if method == 'COBYLA':
+            assert res['status'] == 1, "Unknown status for COBYLA"
+            exit_code = 1
+
+    x_opt = res['x']
+    return x_opt, exit_code
+
+
+def set_up_and_run_nlopt(Run_H, gen_specs):
+    """ Set up objective and runs nlopt
+
+    Declares the appropriate syntax for our special objective function to read
+    through Run_H, sets the parameters and starting points for the run.
+    """
+
+    assert 'xtol_rel' or 'xtol_abs' or 'ftol_rel' or 'ftol_abs' in gen_specs, "NLopt can cycle if xtol_rel, xtol_abs, ftol_rel, or ftol_abs are not set"
+
+    def nlopt_obj_fun(x, grad, Run_H):
+        out = look_in_history(x, Run_H)
+
+        if gen_specs['localopt_method'] in ['LD_MMA']:
+            grad[:] = out[1]
+            out = out[0]
+
+        return out
+
+    n = len(gen_specs['ub'])
+
+    opt = nlopt.opt(getattr(nlopt, gen_specs['localopt_method']), n)
+
+    lb = np.zeros(n)
+    ub = np.ones(n)
+    opt.set_lower_bounds(lb)
+    opt.set_upper_bounds(ub)
+    x0 = Run_H['x_on_cube'][0]
+
+    # Care must be taken here because a too-large initial step causes nlopt to move the starting point!
+    dist_to_bound = min(min(ub-x0), min(x0-lb))
+    assert dist_to_bound > np.finfo(np.float32).eps, "The distance to the boundary is too small for NLopt to handle"
+
+    if 'dist_to_bound_multiple' in gen_specs:
+        opt.set_initial_step(dist_to_bound*gen_specs['dist_to_bound_multiple'])
+    else:
+        opt.set_initial_step(dist_to_bound)
+
+    opt.set_maxeval(len(Run_H)+1)  # evaluate one more point
+    opt.set_min_objective(lambda x, grad: nlopt_obj_fun(x, grad, Run_H))
+    if 'xtol_rel' in gen_specs:
+        opt.set_xtol_rel(gen_specs['xtol_rel'])
+    if 'ftol_rel' in gen_specs:
+        opt.set_ftol_rel(gen_specs['ftol_rel'])
+    if 'xtol_abs' in gen_specs:
+        opt.set_xtol_abs(gen_specs['xtol_abs'])
+    if 'ftol_abs' in gen_specs:
+        opt.set_ftol_abs(gen_specs['ftol_abs'])
+
+    x_opt = opt.optimize(x0)
+    exit_code = opt.last_optimize_result()
+
+    if exit_code == 5:  # NLOPT code for exhausting budget of evaluations, so not at a minimum
+        exit_code = 0
+
+    return x_opt, exit_code
+
+
+def set_up_and_run_tao(Run_H, gen_specs):
+    """ Set up objective and runs PETSc on the comm_self communicator
+
+    Declares the appropriate syntax for our special objective function to read
+    through Run_H, sets the parameters and starting points for the run.
+    """
+    tao_comm = MPI.COMM_SELF
+    n = len(gen_specs['ub'])
+    m = len(Run_H['fvec'][0])
+
+    def pounders_obj_func(tao, X, F, Run_H):
+        F.array = look_in_history(X.array, Run_H, vector_return=True)
+        return F
+
+    # def blmvm_obj_func(tao, X, G, Run_H):
+    #     (f, grad) = look_in_history_fd_grad(X.array, Run_H)
+    #     G.array = grad
+    #     return f
+
+    # Create starting point, bounds, and tao object
+    x = PETSc.Vec().create(tao_comm)
+    x.setSizes(n)
+    x.setFromOptions()
+    x.array = Run_H['x_on_cube'][0]
+    lb = x.duplicate()
+    ub = x.duplicate()
+    lb.array = 0*np.ones(n)
+    ub.array = 1*np.ones(n)
+    tao = PETSc.TAO().create(tao_comm)
+    tao.setType(gen_specs['localopt_method'])
+
+    # if gen_specs['localopt_method'] == 'pounders':
+    f = PETSc.Vec().create(tao_comm)
+    f.setSizes(m)
+    f.setFromOptions()
+
+    delta_0 = gen_specs['dist_to_bound_multiple']*np.min([np.min(ub.array-x.array), np.min(x.array-lb.array)])
+
+    PETSc.Options().setValue('-tao_pounders_delta', str(delta_0))
+    # PETSc.Options().setValue('-pounders_subsolver_tao_type','bqpip')
+    if hasattr(tao, 'setResidual'):
+        tao.setResidual(lambda tao, x, f: pounders_obj_func(tao, x, f, Run_H), f)
+    else:
+        tao.setSeparableObjective(lambda tao, x, f: pounders_obj_func(tao, x, f, Run_H), f)
+    # elif gen_specs['localopt_method'] == 'blmvm':
+    #     g = PETSc.Vec().create(tao_comm)
+    #     g.setSizes(n)
+    #     g.setFromOptions()
+    #     tao.setObjectiveGradient(lambda tao, x, g: blmvm_obj_func(tao, x, g, Run_H))
+
+    # Set everything for tao before solving
+    PETSc.Options().setValue('-tao_max_funcs', str(len(Run_H)+1))
+    tao.setFromOptions()
+    tao.setVariableBounds((lb, ub))
+    # tao.setObjectiveTolerances(fatol=gen_specs['fatol'], frtol=gen_specs['frtol'])
+    # tao.setGradientTolerances(grtol=gen_specs['grtol'], gatol=gen_specs['gatol'])
+    tao.setTolerances(grtol=gen_specs['grtol'], gatol=gen_specs['gatol'])
+    tao.setInitial(x)
+
+    tao.solve(x)
+
+    x_opt = tao.getSolution().getArray()
+    exit_code = tao.getConvergedReason()
+    # print(exit_code)
+    # print(tao.view())
+    # print(x_opt)
+
+    # if gen_specs['localopt_method'] == 'pounders':
+    f.destroy()
+    # elif gen_specs['localopt_method'] == 'blmvm':
+    #     g.destroy()
+
+    lb.destroy()
+    ub.destroy()
+    x.destroy()
+    tao.destroy()
+
+    return x_opt, exit_code
+
+
+def decide_where_to_start_localopt(H, n_s, rk_const, mu=0, nu=0):
+    """
+    Finds points in the history that satisfy the conditions (S1-S5 and L1-L8) in
+    Table 1 of the `APOSMM paper <https://doi.org/10.1007/s12532-017-0131-4>`_
+    This method first identifies sample points satisfying S2-S5, and then
+    identifies all localopt points that satisfy L1-L7.
+    We then start from any sample point also satisfying S1.
+    We do not check condition L8 currently.
+
+    We don't consider points in the history that have not returned from
+    computation, or that have a ``nan`` value. Also, note that ``mu`` and ``nu``
+    implicitly depend on the scaling that is happening with the domain. That
+    is, adjusting the initial domain can make a run start (or not start) at
+    a point that didn't (or did) previously.
+
+    Parameters
+    ----------
+    H: numpy structured array
+        History array storing rows for each point.
+    r_k_const: float
+        Radius for deciding when to start runs
+    lhs_divisions: integer
+        Number of Latin hypercube sampling divisions (0 or 1 means uniform
+        random sampling over the domain)
+    mu: nonnegative float
+        Distance from the boundary that all starting points must satisfy
+    nu: nonnegative float
+        Distance from identified minima that all starting points must satisfy
+    gamma_quantile: float in (0,1]
+        Only sample points whose function values are in the lower
+        gamma_quantile can start localopt runs
+
+    Returns
+    ----------
+    start_inds: list
+        Indices where a local opt run should be started
+
+
+    :See:
+        ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
+    """
+
+    r_k = calc_rk(n, n_s, rk_const)
+
+    if nu > 0:
+        test_2_through_5 = np.logical_and.reduce((
+            H['returned'] == 1,  # have a returned function value
+            H['dist_to_better_s'] >
+            r_k,  # no better sample point within r_k (L2)
+            ~H['started_run'],  # have not started a run (L3)
+            H['dist_to_unit_bounds'] >=
+            mu,  # have all components at least mu away from bounds (L4)
+            np.all(
+                cdist(H['x_on_cube'], H['x_on_cube'][H['local_min']]) >= nu,
+                axis=1)  # distance nu away from known local mins (L5)
+        ))
+    else:
+        test_2_through_5 = np.logical_and.reduce((
+            H['returned'] == 1,  # have a returned function value
+            H['dist_to_better_s'] >
+            r_k,  # no better sample point within r_k (L2)
+            ~H['started_run'],  # have not started a run (L3)
+            H['dist_to_unit_bounds'] >=
+            mu,  # have all components at least mu away from bounds (L4)
+        ))  # (L5) is always true when nu = 0
+
+    assert gamma_quantile == 1, "This is not supported yet. What is the best way to decide this when there are NaNs present in H['f']?"
+    # if gamma_quantile < 1:
+    #     cut_off_value = np.sort(H['f'][~H['local_pt']])[np.floor(gamma_quantile*(sum(~H['local_pt'])-1)).astype(int)]
+    # else:
+    #     cut_off_value = np.inf
+
+    # Find the indices of points that...
+    sample_seeds = np.logical_and.reduce((
+        ~H['local_pt'],  # are not localopt points
+        # H['f'] <= cut_off_value,      # have a small enough objective value
+        ~np.isinf(H['f']),  # have a non-infinity objective value
+        ~np.isnan(H['f']),  # have a non-NaN objective value
+        test_2_through_5,  # satisfy tests 2 through 5
+    ))
+
+    # Uncomment the following to test the effect of ignorning LocalOpt points
+    # in APOSMM. This allows us to test a parallel MLSL.
+    # return list(np.ix_(sample_seeds)[0])
+
+    those_satisfying_S1 = H['dist_to_better_l'][sample_seeds] > r_k  # no better localopt point within r_k
+    sample_start_inds = np.ix_(sample_seeds)[0][those_satisfying_S1]
+
+    # Find the indices of points that...
+    local_seeds = np.logical_and.reduce((
+        H['local_pt'],  # are localopt points
+        H['dist_to_better_l'] > r_k,  # no better local point within r_k (L1)
+        ~np.isinf(H['f']),  # have a non-infinity objective value
+        ~np.isnan(H['f']),  # have a non-NaN objective value
+        test_2_through_5,
+        H['num_active_runs'] == 0,  # are not in an active run (L6)
+        ~H['local_min']  # are not a local min (L7)
+    ))
+
+    local_start_inds2 = list(np.ix_(local_seeds)[0])
+
+    # If paused is a field in H, don't start from paused points.
+    if 'paused' in H.dtype.names:
+        sample_start_inds = sample_start_inds[~H[sample_start_inds]['paused']]
+        start_inds = list(sample_start_inds)+local_start_inds2
+    else:
+        start_inds = list(sample_start_inds)+local_start_inds2
+
+    return start_inds
+
+
+def look_in_history(x, Run_H, vector_return=False):
+    """ See if Run['x_on_cube'][advance_local_run.pt_in_run] matches x,
+    returning f or fvec, or saves x to advance_local_run.x_new if every point in Run_H has been
+    checked.
+    """
+
+    if vector_return:
+        to_return = 'fvec'
+    else:
+        if 'grad' in Run_H.dtype.names:
+            to_return = ['f', 'grad']
+        else:
+            to_return = 'f'
+
+    if advance_local_run.pt_in_run < len(Run_H):
+        # Return the value in history to the localopt algorithm.
+        assert np.allclose(x, Run_H['x_on_cube'][advance_local_run.pt_in_run], rtol=1e-08, atol=1e-08), \
+            "History point does not match Localopt point"
+        f_out = Run_H[to_return][advance_local_run.pt_in_run]
+    else:
+        if advance_local_run.pt_in_run == len(Run_H):
+            # The history of points is exhausted. Save the requested point x to
+            # x_new. x_new will be returned to the manager.
+            advance_local_run.x_new[:] = x
+
+        # Just in case the local opt method requests more points after a new
+        # point has been identified.
+        f_out = Run_H[to_return][-1]
+
+    advance_local_run.pt_in_run += 1
+
+    return f_out
+
+
+def calc_rk(n, n_s, rk_const, lhs_divisions=0):
+    """ Calculate the critical distance r_k """
+
+    if lhs_divisions == 0:
+        r_k = rk_const*(log(n_s)/n_s)**(1/n)
+    else:
+        k = np.floor(n_s/lhs_divisions).astype(int)
+        if k <= 1:  # to prevent r_k=0
+            r_k = np.inf
+        else:
+            r_k = rk_const*(log(k)/k)**(1/n)
+
+    return r_k
+
+def count_samples(H,gen_specs):
+    if 'single_component_at_a_time' in gen_specs and gen_specs['single_component_at_a_time']:
+        # Get the pt_id for non-nan, returned points
+        pt_ids = H['pt_id'][np.logical_and(H['returned'], ~np.isnan(H['f_i']))]
+        _, counts = np.unique(pt_ids, return_counts=True)
+        n_s = np.sum(counts == gen_specs['components'])
+
+    else:
+        # Number of returned sampled points (excluding nans)
+        n_s = np.sum(np.logical_and.reduce((~np.isnan(H['f']), ~H['local_pt'], H['returned'])))
+
+    return n_s
+
+def initialize_APOSMM(H, gen_specs, libE_info):
+    """
+    Computes common values every time that APOSMM is reinvoked
+
+    :See:
+        ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
+    """
+    n = len(gen_specs['ub'])
+
+    n_s = 0
+
+    if 'single_component_at_a_time' in gen_specs and gen_specs['single_component_at_a_time']:
+        assert gen_specs['batch_mode'], ("Must be in batch mode when using "
+                                         "'single_component_at_a_time'")
+        c_flag = True
+    else:
+        c_flag = False
+
+    if 'rk_const' in gen_specs:
+        rk_c = gen_specs['rk_const']
+    else:
+        rk_c = ((gamma(1+(n/2.0))*5.0)**(1.0/n))/sqrt(pi)
+
+    if 'lhs_divisions' in gen_specs:
+        ld = gen_specs['lhs_divisions']
+    else:
+        ld = 0
+
+    if 'mu' in gen_specs:
+        mu = gen_specs['mu']
+    else:
+        mu = 1e-4
+
+    if 'nu' in gen_specs:
+        nu = gen_specs['nu']
+    else:
+        nu = 0
+
+    total_runs = 0
+
+
+    comm = libE_info['comm']
+
+
+    return n, n_s, c_flag, rk_c, mu, nu, total_runs, comm
+
+
+def display_exception(e):
+    print(e.__doc__)
+    print(e.args)
+    _, _, tb = sys.exc_info()
+    traceback.print_tb(tb)  # Fixed format
+    tb_info = traceback.extract_tb(tb)
+    filename, line, func, text = tb_info[-1]
+    print('An error occurred on line {} of function {} with statement {}'.format(line, func, text))
+
+    # PETSc/TAO errors are printed in the following manner:
+    if hasattr(e, '_traceback_'):
+        print('The error was:')
+        for i in e._traceback_:
+            print(i)
+    sys.stdout.flush()
+
+
+# if __name__ == "__main__":
+#     [H,gen_specs,persis_info] = [np.load('H20.npz')[i] for i in ['H','gen_specs','persis_info']]
+#     gen_specs = gen_specs.item()
+#     persis_info = persis_info.item()
+#     import ipdb; ipdb.set_trace()
+#     aposmm_logic(H,persis_info,gen_specs,{})
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
new file mode 100644
index 000000000..e6b7f433a
--- /dev/null
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -0,0 +1,55 @@
+# """
+# Runs libEnsemble on the 6-hump camel problem. Documented here:
+#    https://www.sfu.ca/~ssurjano/camel6.html
+#
+# Execute via one of the following commands (e.g. 3 workers):
+#    mpiexec -np 4 python3 test_6-hump_camel_persistent_uniform_sampling.py
+#    python3 test_6-hump_camel_persistent_uniform_sampling.py --nworkers 3 --comms local
+#    python3 test_6-hump_camel_persistent_uniform_sampling.py --nworkers 3 --comms tcp
+#
+# The number of concurrent evaluations of the objective function will be 4-1=3.
+# """
+
+# Do not change these lines - they are parsed by run-tests.sh
+# TESTSUITE_COMMS: mpi local tcp
+# TESTSUITE_NPROCS: 3 4
+
+import sys
+import numpy as np
+
+# Import libEnsemble items for this test
+from libensemble.libE import libE
+from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
+from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
+from libensemble.alloc_funcs.start_only_persistent import only_persistent_gens as alloc_f
+from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+
+nworkers, is_master, libE_specs, _ = parse_args()
+
+if nworkers < 2:
+    sys.exit("Cannot run with a persistent worker if only one worker -- aborting...")
+
+n = 2
+sim_specs = {'sim_f': sim_f,
+             'in': ['x'],
+             'out': [('f', float), ('grad', float, n)]}
+
+gen_specs = {'gen_f': gen_f,
+             'in': [],
+             'gen_batch_size': 20,
+             'out': [('x', float, (n,))],
+             'lb': np.array([-3, -2]),
+             'ub': np.array([3, 2])}
+
+alloc_specs = {'alloc_f': alloc_f, 'out': []}
+
+persis_info = per_worker_stream({}, nworkers + 1)
+
+exit_criteria = {'sim_max': 40}
+
+# Perform the run
+H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
+                            alloc_specs, libE_specs)
+
+if is_master:
+    save_libE_output(H, persis_info, __file__, nworkers)

From 56be7c6d68ab50b3d0a7396d0e70d5b1ea88e7e4 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 5 Jul 2019 11:14:09 -0500
Subject: [PATCH 006/644] Example of persistent APOSMM ready for Kaushik

---
 libensemble/gen_funcs/persistent_aposmm.py    | 160 ++++++++++--------
 .../test_6-hump_camel_aposmm_LD_MMA.py        |   1 -
 .../test_6-hump_camel_persistent_aposmm.py    |   8 +-
 3 files changed, 96 insertions(+), 73 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index fe747da27..d0f6592ef 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -23,6 +23,10 @@
 
 import nlopt
 
+from libensemble.message_numbers import STOP_TAG, PERSIS_STOP
+from libensemble.gen_funcs.support import send_mgr_worker_msg
+from libensemble.gen_funcs.support import get_mgr_worker_msg
+
 
 class APOSMMException(Exception):
     "Raised for any exception in APOSMM"
@@ -179,119 +183,108 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     persis_info['old_runs']: Sequence of indices of points in finished runs
 
     """
-    import ipdb; ipdb.set_trace()
 
-    n, n_s, c_flag, rk_const, mu, nu, comm = initialize_APOSMM(H, gen_specs, libE_info)
+    n, n_s, c_flag, rk_const, mu, nu, total_runs, comm, local_H = initialize_APOSMM(H, gen_specs, libE_info)
+
+    send_initial_sample(gen_specs, persis_info, n, c_flag, comm, local_H)
 
     tag = None
+    while 1:
+        # Receive from manager
+        tag, Work, calc_in = get_mgr_worker_msg(comm)
 
-    while tag not in [STOP_TAG, PERSIS_STOP]:
-        n_s = count_samples(H,gen_specs)
+        if tag in [STOP_TAG, PERSIS_STOP]:
+            continue
 
-        if n_s >= gen_specs['initial_sample_size']:
-            update_history_dist(H, n, gen_specs, c_flag)
+        n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
 
-            starting_inds = decide_where_to_start_localopt(H, n_s, rk_const, mu, nu)
+        # If manager returned function values for an existing local opt run,
+        # contact child process to get another x_new and send back to manager
+        import ipdb; ipdb.set_trace()
 
+        # Decide if there are any new points to start a localopt run
+        starting_inds = decide_where_to_start_localopt(local_H, n, n_s, rk_const, mu, nu)
+
+        if len(starting_inds): 
+            O = np.empty(0, dtype=gen_specs['out'])
             for ind in starting_inds:
+                # Start localopt child processes
+
                 # Mark point as having started a run
                 new_run_num = total_runs
                 total_runs += 1
-                H['started_run'][ind] = 1
+                local_H['started_run'][ind] = 1
                 run_order[new_run_num] = [ind]
 
                 # Initialize child process for new localopt run
-                x_new = start_localopt(H, gen_specs, c_flag)
+                x_new = start_localopt(local_H, gen_specs, c_flag)
 
-                # Send x_new to manager for evaluation
-                O = np.zeros(1, dtype=gen_specs['out'])
-                add_to_O(O, x_new, H, gen_specs, c_flag, persis_info, local_flag=1)
-                tag, Work, calc_in = send_mgr_worker_msg(comm, O)
+                # Add x_new to O (which will be sent to the manager for evaluation)
+                add_to_O(O, x_new, local_H, gen_specs, c_flag, persis_info, local_flag=1)
 
-            # Receive from manager (if possible), contact child process to get
-            # x_new, and send back to manager
-            get_mgr_worker_msg(comm, status)
+            send_mgr_worker_msg(comm, O)
 
-        else:
-            O = np.zeros(gen_specs['initial_sample_size'], dtype=gen_specs['out'])
-            sampled_points = persis_info['rand_stream'].uniform(0, 1, (len(O), n))
-            on_cube = True
-            add_to_O(O, sampled_points, H, gen_specs, c_flag, persis_info, on_cube=on_cube)
+    return O, persis_info, tag
 
-            tag, Work, calc_in = send_mgr_worker_msg(comm, O)
+def update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in):
 
-    return O, persis_info, tag
+    for name in calc_in.dtype.names: 
+        local_H[name][Work['libE_info']['H_rows']] = calc_in[name]
+
+    local_H['returned'][Work['libE_info']['H_rows']] = True
+    n_s += np.sum(~local_H[Work['libE_info']['H_rows']]['local_pt'])
 
+    update_history_dist(local_H, n, gen_specs, c_flag)
 
-def add_to_O(O, pts, H, gen_specs, c_flag, persis_info, local_flag=0,
-             sorted_run_inds=[], run=[], on_cube=True):
+    return n_s
+
+
+def add_to_local_H(local_H, pts, gen_specs, c_flag, local_flag=0, sorted_run_inds=[], run=[], on_cube=True):
     """
     Adds points to O, the numpy structured array to be sent back to the manager
     """
 
     assert not local_flag or len(pts) == 1, "Can't > 1 local points"
 
-    original_len_O = len(O)
+    len_local_H = len(local_H)
 
-    len_H = len(H)
     ub = gen_specs['ub']
     lb = gen_specs['lb']
     if c_flag:
         m = gen_specs['components']
 
-        assert len_H % m == 0, "Number of points in len_H not congruent to 0 mod 'components'"
-        pt_ids = np.sort(np.tile(np.arange((len_H+original_len_O)/m, (len_H+original_len_O)/m+len(pts)), (1, m)))
+        assert len_local_H % m == 0, "Number of points in local_H not congruent to 0 mod 'components'"
+        pt_ids = np.sort(np.tile(np.arange((len_local_H)/m, (len_local_H)/m+len(pts)), (1, m)))
         pts = np.tile(pts, (m, 1))
 
     num_pts = len(pts)
 
-    O.resize(len(O)+num_pts, refcheck=False)  # Adds num_pts rows of zeros to O
+    local_H.resize(len(local_H)+num_pts, refcheck=False)  # Adds num_pts rows of zeros to O
 
     if on_cube:
-        O['x_on_cube'][-num_pts:] = pts
-        O['x'][-num_pts:] = pts*(ub-lb)+lb
+        local_H['x_on_cube'][-num_pts:] = pts
+        local_H['x'][-num_pts:] = pts*(ub-lb)+lb
     else:
-        O['x_on_cube'][-num_pts:] = (pts-lb)/(ub-lb)
-        O['x'][-num_pts:] = pts
+        local_H['x_on_cube'][-num_pts:] = (pts-lb)/(ub-lb)
+        local_H['x'][-num_pts:] = pts
 
-    O['sim_id'][-num_pts:] = np.arange(len_H+original_len_O, len_H+original_len_O+num_pts)
-    O['local_pt'][-num_pts:] = local_flag
+    local_H['sim_id'][-num_pts:] = np.arange(len_local_H, len_local_H+num_pts)
+    local_H['local_pt'][-num_pts:] = local_flag
 
-    O['dist_to_unit_bounds'][-num_pts:] = np.inf
-    O['dist_to_better_l'][-num_pts:] = np.inf
-    O['dist_to_better_s'][-num_pts:] = np.inf
-    O['ind_of_better_l'][-num_pts:] = -1
-    O['ind_of_better_s'][-num_pts:] = -1
+    local_H['dist_to_unit_bounds'][-num_pts:] = np.inf
+    local_H['dist_to_better_l'][-num_pts:] = np.inf
+    local_H['dist_to_better_s'][-num_pts:] = np.inf
+    local_H['ind_of_better_l'][-num_pts:] = -1
+    local_H['ind_of_better_s'][-num_pts:] = -1
 
     if c_flag:
-        O['obj_component'][-num_pts:] = np.tile(range(0, m), (1, num_pts//m))
-        O['pt_id'][-num_pts:] = pt_ids
+        local_H['obj_component'][-num_pts:] = np.tile(range(0, m), (1, num_pts//m))
+        local_H['pt_id'][-num_pts:] = pt_ids
 
     if local_flag:
-        O['num_active_runs'][-num_pts] += 1
-        # O['priority'][-num_pts:] = 1
-        # O['priority'][-num_pts:] = np.random.uniform(0,1,num_pts)
-        if 'high_priority_to_best_localopt_runs' in gen_specs and gen_specs['high_priority_to_best_localopt_runs']:
-            O['priority'][-num_pts:] = -min(H['f'][persis_info['run_order'][run]])  # Give highest priority to run with lowest function value
-        else:
-            O['priority'][-num_pts:] = persis_info['rand_stream'].uniform(0, 1, num_pts)
-        persis_info['run_order'][run].append(O[-num_pts]['sim_id'])
+        local_H['num_active_runs'][-num_pts] += 1
     else:
-        if c_flag:
-            # p_tmp = np.sort(np.tile(np.random.uniform(0,1,num_pts/m),(m,1))) # If you want all "duplicate points" to have the same priority (meaning libEnsemble gives them all at once)
-            # p_tmp = np.random.uniform(0,1,num_pts)
-            p_tmp = persis_info['rand_stream'].uniform(0, 1, num_pts)
-        else:
-            # p_tmp = np.random.uniform(0,1,num_pts)
-            # persis_info['rand_stream'].uniform(lb,ub,(1,n))
-            if 'high_priority_to_best_localopt_runs' in gen_specs and gen_specs['high_priority_to_best_localopt_runs']:
-                p_tmp = -np.inf*np.ones(num_pts)
-            else:
-                p_tmp = persis_info['rand_stream'].uniform(0, 1, num_pts)
-        O['priority'][-num_pts:] = p_tmp
-        # O['priority'][-num_pts:] = 1
-
-    return persis_info
+        local_H['priority'][-num_pts:] = 1
 
 
 def update_history_dist(H, n, gen_specs, c_flag):
@@ -646,7 +639,7 @@ def pounders_obj_func(tao, X, F, Run_H):
     return x_opt, exit_code
 
 
-def decide_where_to_start_localopt(H, n_s, rk_const, mu=0, nu=0):
+def decide_where_to_start_localopt(H, n, n_s, rk_const, mu=0, nu=0):
     """
     Finds points in the history that satisfy the conditions (S1-S5 and L1-L8) in
     Table 1 of the `APOSMM paper <https://doi.org/10.1007/s12532-017-0131-4>`_
@@ -712,7 +705,7 @@ def decide_where_to_start_localopt(H, n_s, rk_const, mu=0, nu=0):
             mu,  # have all components at least mu away from bounds (L4)
         ))  # (L5) is always true when nu = 0
 
-    assert gamma_quantile == 1, "This is not supported yet. What is the best way to decide this when there are NaNs present in H['f']?"
+    # assert gamma_quantile == 1, "This is not supported yet. What is the best way to decide this when there are NaNs present in H['f']?"
     # if gamma_quantile < 1:
     #     cut_off_value = np.sort(H['f'][~H['local_pt']])[np.floor(gamma_quantile*(sum(~H['local_pt'])-1)).astype(int)]
     # else:
@@ -861,8 +854,35 @@ def initialize_APOSMM(H, gen_specs, libE_info):
 
     comm = libE_info['comm']
 
-
-    return n, n_s, c_flag, rk_c, mu, nu, total_runs, comm
+    local_H_fields = [('f',float),
+                      ('grad',float,n),
+                      ('x', float, n),
+                      ('x_on_cube', float, n),
+                      ('priority', float),
+                      ('local_pt', bool),
+                      ('known_to_aposmm', bool),
+                      ('dist_to_unit_bounds', float),
+                      ('dist_to_better_l', float),
+                      ('dist_to_better_s', float),
+                      ('ind_of_better_l', int),
+                      ('ind_of_better_s', int),
+                      ('started_run', bool),
+                      ('num_active_runs', int),
+                      ('local_min', bool),
+                      ('sim_id', int),
+                      ('paused', bool),
+                      ('returned', bool),
+                      ('pt_id', int), # Identify the same point evaluated by different sim_f's or components
+                      ]
+
+    local_H = np.empty(0,dtype=local_H_fields);
+
+    return n, n_s, c_flag, rk_c, mu, nu, total_runs, comm, local_H
+
+def send_initial_sample(gen_specs, persis_info, n, c_flag, comm, local_H):
+    sampled_points = persis_info['rand_stream'].uniform(0, 1, (gen_specs['initial_sample_size'], n))
+    add_to_local_H(local_H, sampled_points, gen_specs, c_flag, on_cube=True)
+    send_mgr_worker_msg(comm, local_H[['x','sim_id']])
 
 
 def display_exception(e):
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
index 829b48fbf..ddae2ce7f 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
@@ -36,7 +36,6 @@
 gen_specs = {'gen_f': gen_f,
              'in': [o[0] for o in gen_out] + ['f', 'grad', 'returned'],
              'out': gen_out,
-             'num_active_gens': 1,
              'batch_mode': True,
              'initial_sample_size': 100,
              'sample_points': np.round(minima, 1),
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index e6b7f433a..307dcadfa 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -34,10 +34,14 @@
              'in': ['x'],
              'out': [('f', float), ('grad', float, n)]}
 
+gen_out = [('x', float, n), ('x_on_cube', float, n), ('sim_id', int)]
 gen_specs = {'gen_f': gen_f,
              'in': [],
-             'gen_batch_size': 20,
-             'out': [('x', float, (n,))],
+             'out': gen_out,
+             'batch_mode': True,
+             'initial_sample_size': 5,
+             'localopt_method': 'LD_MMA',
+             'xtol_rel': 1e-3,
              'lb': np.array([-3, -2]),
              'ub': np.array([3, 2])}
 

From 5627ce3302b2427c644ad53ce59888f25b443e79 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 5 Jul 2019 13:39:06 -0500
Subject: [PATCH 007/644] minor changes to persis aposmm

---
 libensemble/gen_funcs/persistent_aposmm.py | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index d0f6592ef..2b11398b0 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -194,18 +194,14 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         tag, Work, calc_in = get_mgr_worker_msg(comm)
 
         if tag in [STOP_TAG, PERSIS_STOP]:
-            continue
+            break
 
         n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
 
-        # If manager returned function values for an existing local opt run,
-        # contact child process to get another x_new and send back to manager
-        import ipdb; ipdb.set_trace()
-
         # Decide if there are any new points to start a localopt run
         starting_inds = decide_where_to_start_localopt(local_H, n, n_s, rk_const, mu, nu)
 
-        if len(starting_inds): 
+        if len(starting_inds):
             O = np.empty(0, dtype=gen_specs['out'])
             for ind in starting_inds:
                 # Start localopt child processes
@@ -217,6 +213,8 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 run_order[new_run_num] = [ind]
 
                 # Initialize child process for new localopt run
+                #FIXME: Instead of rading the first value, poll for values from
+                # child processes later.
                 x_new = start_localopt(local_H, gen_specs, c_flag)
 
                 # Add x_new to O (which will be sent to the manager for evaluation)
@@ -224,8 +222,11 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
             send_mgr_worker_msg(comm, O)
 
+    raise NotImplementedError("Persistent APOSMM is not fully supported, yet.")
+
     return O, persis_info, tag
 
+
 def update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in):
 
     for name in calc_in.dtype.names: 

From e5fce96a0f945734975a31375b4e5c8d913baa33 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Wed, 10 Jul 2019 14:54:42 -0500
Subject: [PATCH 008/644] chalks out the main plan for the implementation

---
 libensemble/gen_funcs/persistent_aposmm.py    | 107 +++++++++++++++---
 .../test_6-hump_camel_persistent_aposmm.py    |   2 +-
 2 files changed, 94 insertions(+), 15 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 2b11398b0..72e7d22d7 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -28,6 +28,9 @@
 from libensemble.gen_funcs.support import get_mgr_worker_msg
 
 
+from multiprocessing import Event, Process, Queue
+
+
 class APOSMMException(Exception):
     "Raised for any exception in APOSMM"
 
@@ -184,57 +187,133 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
     """
 
+    # {{{ multiprocessing initialization
+
+    child_can_read_evts = []
+    processes = []
+    parent_can_read_from_queue = Event()
+    comm_queue = Queue()
+
+    # }}}
+
     n, n_s, c_flag, rk_const, mu, nu, total_runs, comm, local_H = initialize_APOSMM(H, gen_specs, libE_info)
 
+    if gen_specs['initial_sample_size'] != 1:
+        raise RuntimeError("sample size > not supported for now.")
+
     send_initial_sample(gen_specs, persis_info, n, c_flag, comm, local_H)
 
+    # Separate the logic of filling local_H and sending it.
+    # Reason: To a new developer this doesn't look like local_H will get
+    # edited.
+
+    print('local_H =', local_H)
+
     tag = None
+    O = np.empty(0, dtype=gen_specs['out'])  # noqa: E741
     while 1:
         # Receive from manager
         tag, Work, calc_in = get_mgr_worker_msg(comm)
 
+        # KK: tag: what tag is it?(need helpful naming)
+        # KK: 'tag' is present in 'Work' as well.(repitition accounts for
+        # more confusion and increases scope for human error)
+        # Aah ok, looking further tag seems one of the enums in libEnsemble.
+        # Anyways just the name 'tag' is not desciptive enough, something more
+        # descriptive would be better.
+
+        # persis_info contains something called H_rows
+
+        # print('Tag =', tag)
+        # print('Work =', Work)
+        print('calc_in =', calc_in)
+
         if tag in [STOP_TAG, PERSIS_STOP]:
+            # FIXME: We need to kill all the child processes here.
+            raise NotImplementedError("Killing of child processes in not"
+                    " implmeneted by the devs.")
             break
 
+        # Look at the message here. Is it a message for a point from which
+        # local optimization has to be started or does it have to be supplied
+        # to a currently running local optimization run.
+        # local_H contains a ton of information.
+
         n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
 
-        # Decide if there are any new points to start a localopt run
-        starting_inds = decide_where_to_start_localopt(local_H, n, n_s, rk_const, mu, nu)
 
-        if len(starting_inds):
-            O = np.empty(0, dtype=gen_specs['out'])
+        if current_eval_received_for_a_run(tag, Work, calc_in):
+
+            child_idx = get_child_idx_for_the_received_evaluation(calc_in)
+
+            comm_queue.push(f_x)
+
+            parent_can_read_from_queue.unset()
+
+            child_can_read_evts[child_idx].set()
+            parent_can_read_from_queue.wait()
+
+            x_new = comm_queue.get()
+
+            add_to_local_H(local_H, x_new, gen_specs, c_flag, local_flag=1, on_cube=True)
+
+            #FIXME: Be very careful about the sim_id.
+            # Once we have set the sim_id correctly our job
+            send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
+        else:
+            n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
+
+            # Decide if there are any new points to start a localopt run
+            starting_inds = decide_where_to_start_localopt(local_H, n, n_s, rk_const, mu, nu)
+
             for ind in starting_inds:
                 # Start localopt child processes
 
                 # Mark point as having started a run
-                new_run_num = total_runs
+                # Why does it help to mark the total number of runs?
                 total_runs += 1
                 local_H['started_run'][ind] = 1
-                run_order[new_run_num] = [ind]
 
-                # Initialize child process for new localopt run
-                #FIXME: Instead of rading the first value, poll for values from
-                # child processes later.
-                x_new = start_localopt(local_H, gen_specs, c_flag)
+                child_can_read_evts.append(Event())
+
+                # FIXME: f_x must be read from local_H.
+
+                p = Process(run_local_opt, args=(comm_queue, x_start,
+                    child_can_read, parent_can_read))
+                processes.append(p)
+                p.start()
+
+                comm_queue.push(f_x)
+                parent_can_read_from_queue.unset()
 
-                # Add x_new to O (which will be sent to the manager for evaluation)
-                add_to_O(O, x_new, local_H, gen_specs, c_flag, persis_info, local_flag=1)
+                child_can_read_evts[-1].set()
+                parent_can_read_from_queue.wait()
 
-            send_mgr_worker_msg(comm, O)
+                x_new = comm_queue.get()
+
+                add_to_local_H(local_H, x_new, gen_specs, c_flag, local_flag=1, on_cube=True)
+
+                #FIXME: Be very careful about the sim_id.
+                # That is all what we have.
+                send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
 
     raise NotImplementedError("Persistent APOSMM is not fully supported, yet.")
 
+    for p in processes:
+        p.join()
+
     return O, persis_info, tag
 
 
 def update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in):
 
-    for name in calc_in.dtype.names: 
+    for name in calc_in.dtype.names:
         local_H[name][Work['libE_info']['H_rows']] = calc_in[name]
 
     local_H['returned'][Work['libE_info']['H_rows']] = True
     n_s += np.sum(~local_H[Work['libE_info']['H_rows']]['local_pt'])
 
+    # dist -> distance
     update_history_dist(local_H, n, gen_specs, c_flag)
 
     return n_s
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index 307dcadfa..6dea74657 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -39,7 +39,7 @@
              'in': [],
              'out': gen_out,
              'batch_mode': True,
-             'initial_sample_size': 5,
+             'initial_sample_size': 1,
              'localopt_method': 'LD_MMA',
              'xtol_rel': 1e-3,
              'lb': np.array([-3, -2]),

From 34fcf063eeffa5547caab59bc8987ada3e8e711c Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 10 Jul 2019 15:45:58 -0500
Subject: [PATCH 009/644] Answering one question.

---
 libensemble/gen_funcs/persistent_aposmm.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 72e7d22d7..8252bbd4c 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -270,7 +270,10 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 # Start localopt child processes
 
                 # Mark point as having started a run
-                # Why does it help to mark the total number of runs?
+                # Why does it help to mark the total number of runs? JL: it's
+                # useful to assign a unique ID to each run that is started.
+                # Such information is one way (but not the only way) to give
+                # funciton values to the correct child process.
                 total_runs += 1
                 local_H['started_run'][ind] = 1
 

From a61d9de4c65a48910da102687fe1e3880ab1aa22 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 11 Jul 2019 13:55:53 -0500
Subject: [PATCH 010/644] Giving back sim_id to persistent gens

---
 libensemble/alloc_funcs/start_only_persistent.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/alloc_funcs/start_only_persistent.py b/libensemble/alloc_funcs/start_only_persistent.py
index 2d2d93fdc..a126f796d 100644
--- a/libensemble/alloc_funcs/start_only_persistent.py
+++ b/libensemble/alloc_funcs/start_only_persistent.py
@@ -25,7 +25,7 @@ def only_persistent_gens(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
             last_time_gen_gave_batch = np.max(H['gen_time'][gen_inds])
             inds_of_last_batch_from_gen = H['sim_id'][gen_inds][H['gen_time'][gen_inds] == last_time_gen_gave_batch]
             gen_work(Work, i,
-                     sim_specs['in'] + [n[0] for n in sim_specs['out']],
+                     sim_specs['in'] + [n[0] for n in sim_specs['out']] + [('sim_id')],
                      np.atleast_1d(inds_of_last_batch_from_gen), persis_info[i], persistent=True)
 
     task_avail = ~H['given']

From 517acb6b2da6fdd3b00b7bda4e2db831632acef3 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Thu, 11 Jul 2019 13:56:52 -0500
Subject: [PATCH 011/644] WIP: some more changes for persis aposmm

---
 libensemble/gen_funcs/persistent_aposmm.py | 40 +++++++++++++++++++---
 1 file changed, 35 insertions(+), 5 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 72e7d22d7..8c51d775a 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -207,8 +207,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     # Reason: To a new developer this doesn't look like local_H will get
     # edited.
 
-    print('local_H =', local_H)
-
     tag = None
     O = np.empty(0, dtype=gen_specs['out'])  # noqa: E741
     while 1:
@@ -224,9 +222,13 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
         # persis_info contains something called H_rows
 
+        # calc_in contains the tuple (x, f, grad_f).
+        # So one can theoretically read the local_H and do some operations to
+        # figure out the origin of this 'x'.
+
         # print('Tag =', tag)
         # print('Work =', Work)
-        print('calc_in =', calc_in)
+        # print('calc_in =', calc_in)
 
         if tag in [STOP_TAG, PERSIS_STOP]:
             # FIXME: We need to kill all the child processes here.
@@ -241,6 +243,9 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
         n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
 
+        print(local_H)
+        1/0
+
 
         if current_eval_received_for_a_run(tag, Work, calc_in):
 
@@ -278,12 +283,12 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                 # FIXME: f_x must be read from local_H.
 
-                p = Process(run_local_opt, args=(comm_queue, x_start,
+                p = Process(run_local_opt, args=(local_opt_type, comm_queue, x_start,
                     child_can_read, parent_can_read))
                 processes.append(p)
                 p.start()
 
-                comm_queue.push(f_x)
+                comm_queue.push((f_x, grad_f_x))
                 parent_can_read_from_queue.unset()
 
                 child_can_read_evts[-1].set()
@@ -305,6 +310,30 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     return O, persis_info, tag
 
 
+def callback_function(x, grad, comm_queue, child_can_read, parent_can_read, gen_specs):
+    comm_queue.put(x)
+    parent_can_read.set()
+    child_can_read.wait()
+    result = comm_queue.get()
+    child_can_read.unset()
+    if gen_specs['localopt_method'] in ['LD_MMA']:
+        grad[:] = result[1]
+
+    return result[0]
+
+
+def run_local_opt(gen_specs, comm_queue, x0, child_can_read,
+        parent_can_read):
+
+    opt = nlopt.opt(nlopt.LN_BOBYQA, 2)
+    opt.set_min_objective(lambda x, grad: callback_function(x, grad,
+        comm_queue, child_can_read, parent_can_read, gen_specs))
+
+    opt.set_lower_bounds(-np.array([3, 2]))
+    opt.set_upper_bounds(np.array([3, 2]))
+    opt.set_ftol_rel(1e-4)
+
+
 def update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in):
 
     for name in calc_in.dtype.names:
@@ -962,6 +991,7 @@ def initialize_APOSMM(H, gen_specs, libE_info):
 def send_initial_sample(gen_specs, persis_info, n, c_flag, comm, local_H):
     sampled_points = persis_info['rand_stream'].uniform(0, 1, (gen_specs['initial_sample_size'], n))
     add_to_local_H(local_H, sampled_points, gen_specs, c_flag, on_cube=True)
+    print('Sent =', local_H[['x','sim_id']])
     send_mgr_worker_msg(comm, local_H[['x','sim_id']])
 
 

From 618007a604603bc5a12e07fb5968d5c952cc47ac Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Thu, 11 Jul 2019 15:20:07 -0500
Subject: [PATCH 012/644] reads sim_id into gen_func

---
 libensemble/gen_funcs/persistent_aposmm.py | 29 +++++++++++-----------
 1 file changed, 14 insertions(+), 15 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 77b5a7bd6..51facf8dd 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -198,6 +198,8 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
     n, n_s, c_flag, rk_const, mu, nu, total_runs, comm, local_H = initialize_APOSMM(H, gen_specs, libE_info)
 
+    sim_id_to_child_indices = {}
+
     if gen_specs['initial_sample_size'] != 1:
         raise RuntimeError("sample size > not supported for now.")
 
@@ -212,6 +214,9 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     while 1:
         # Receive from manager
         tag, Work, calc_in = get_mgr_worker_msg(comm)
+        x_recv, f_x_recv, grad_f_recv, sim_id_recv = calc_in[0]
+        print(calc_in)
+        1/0
 
         # KK: tag: what tag is it?(need helpful naming)
         # KK: 'tag' is present in 'Work' as well.(repitition accounts for
@@ -246,25 +251,19 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         print(local_H)
         1/0
 
+        if sim_id_to_child_indices.get(sim_id):
+            for child_idx in sim_id_to_child_indices[sim_id_recv]:
+                comm_queue.push((f_x_recv, grad_f_recv))
 
-        if current_eval_received_for_a_run(tag, Work, calc_in):
-
-            child_idx = get_child_idx_for_the_received_evaluation(calc_in)
-
-            comm_queue.push(f_x)
-
-            parent_can_read_from_queue.unset()
-
-            child_can_read_evts[child_idx].set()
-            parent_can_read_from_queue.wait()
+                parent_can_read_from_queue.unset()
 
-            x_new = comm_queue.get()
+                child_can_read_evts[child_idx].set()
+                parent_can_read_from_queue.wait()
 
-            add_to_local_H(local_H, x_new, gen_specs, c_flag, local_flag=1, on_cube=True)
+                x_new = comm_queue.get()
 
-            #FIXME: Be very careful about the sim_id.
-            # Once we have set the sim_id correctly our job
-            send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
+                add_to_local_H(local_H, x_new, gen_specs, c_flag, local_flag=1, on_cube=True)
+                send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
         else:
             n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
 

From d4a2932a666f7aa46443b48cbe2fac70154a3060 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 12 Jul 2019 15:10:17 -0500
Subject: [PATCH 013/644] saving s'more progress

---
 libensemble/gen_funcs/persistent_aposmm.py | 37 ++++++++++++++++------
 1 file changed, 27 insertions(+), 10 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 51facf8dd..be24f7da0 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -203,7 +203,8 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     if gen_specs['initial_sample_size'] != 1:
         raise RuntimeError("sample size > not supported for now.")
 
-    send_initial_sample(gen_specs, persis_info, n, c_flag, comm, local_H)
+    send_initial_sample(gen_specs, persis_info, n, c_flag, comm, local_H,
+            sim_id_to_child_indices)
 
     # Separate the logic of filling local_H and sending it.
     # Reason: To a new developer this doesn't look like local_H will get
@@ -214,7 +215,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     while 1:
         # Receive from manager
         tag, Work, calc_in = get_mgr_worker_msg(comm)
-        x_recv, f_x_recv, grad_f_recv, sim_id_recv = calc_in[0]
+        x_recv, f_x_recv, grad_f_x_recv, sim_id_recv = calc_in[0]
         print(calc_in)
         1/0
 
@@ -251,9 +252,9 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         print(local_H)
         1/0
 
-        if sim_id_to_child_indices.get(sim_id):
+        if sim_id_to_child_indices.get(sim_id_recv):
             for child_idx in sim_id_to_child_indices[sim_id_recv]:
-                comm_queue.push((f_x_recv, grad_f_recv))
+                comm_queue.push((f_x_recv, grad_f_x_recv))
 
                 parent_can_read_from_queue.unset()
 
@@ -263,7 +264,13 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 x_new = comm_queue.get()
 
                 add_to_local_H(local_H, x_new, gen_specs, c_flag, local_flag=1, on_cube=True)
+                # TODO:[KK]: Would it be true that the local_H[-1] would be our
+                # new point?
                 send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
+                if local_H[-1]['sim_id'] in sim_id_to_child_indices:
+                    sim_id_to_child_indices[local_H[-1]['sim_id']] += (child_idx, )
+                else:
+                    sim_id_to_child_indices[local_H[-1]['sim_id']] = (child_idx, )
         else:
             n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
 
@@ -285,12 +292,12 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                 # FIXME: f_x must be read from local_H.
 
-                p = Process(run_local_opt, args=(local_opt_type, comm_queue, x_start,
-                    child_can_read, parent_can_read))
+                p = Process(run_local_opt, args=(gen_specs, comm_queue, x_recv,
+                    child_can_read_evts[-1], parent_can_read_from_queue))
                 processes.append(p)
                 p.start()
 
-                comm_queue.push((f_x, grad_f_x))
+                comm_queue.push((f_x_recv, grad_f_x_recv))
                 parent_can_read_from_queue.unset()
 
                 child_can_read_evts[-1].set()
@@ -300,6 +307,11 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                 add_to_local_H(local_H, x_new, gen_specs, c_flag, local_flag=1, on_cube=True)
 
+                if local_H[-1]['sim_id'] in sim_id_to_child_indices:
+                    sim_id_to_child_indices[local_H[-1]['sim_id']] += (len(processes), )
+                else:
+                    sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(processes), )
+
                 #FIXME: Be very careful about the sim_id.
                 # That is all what we have.
                 send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
@@ -990,11 +1002,16 @@ def initialize_APOSMM(H, gen_specs, libE_info):
 
     return n, n_s, c_flag, rk_c, mu, nu, total_runs, comm, local_H
 
-def send_initial_sample(gen_specs, persis_info, n, c_flag, comm, local_H):
+def send_initial_sample(gen_specs, persis_info, n, c_flag, comm, local_H,
+        sim_id_to_child_indices):
     sampled_points = persis_info['rand_stream'].uniform(0, 1, (gen_specs['initial_sample_size'], n))
     add_to_local_H(local_H, sampled_points, gen_specs, c_flag, on_cube=True)
-    print('Sent =', local_H[['x','sim_id']])
-    send_mgr_worker_msg(comm, local_H[['x','sim_id']])
+    for sim_id in local_H['sim_id'][-gen_specs['initial_sample_size']:]:
+        assert sim_id not in sim_id_to_child_indices
+        sim_id_to_child_indices[sim_id] = None
+
+    print('Sent =', local_H[['x', 'sim_id']])
+    send_mgr_worker_msg(comm, local_H[['x', 'sim_id']])
 
 
 def display_exception(e):

From e8da8e3b563fdbcd4e21039b518d82e9d564777c Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 12 Jul 2019 15:31:14 -0500
Subject: [PATCH 014/644] some cleanup

---
 libensemble/gen_funcs/persistent_aposmm.py | 37 ----------------------
 1 file changed, 37 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index be24f7da0..463e995ac 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -216,25 +216,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         # Receive from manager
         tag, Work, calc_in = get_mgr_worker_msg(comm)
         x_recv, f_x_recv, grad_f_x_recv, sim_id_recv = calc_in[0]
-        print(calc_in)
-        1/0
-
-        # KK: tag: what tag is it?(need helpful naming)
-        # KK: 'tag' is present in 'Work' as well.(repitition accounts for
-        # more confusion and increases scope for human error)
-        # Aah ok, looking further tag seems one of the enums in libEnsemble.
-        # Anyways just the name 'tag' is not desciptive enough, something more
-        # descriptive would be better.
-
-        # persis_info contains something called H_rows
-
-        # calc_in contains the tuple (x, f, grad_f).
-        # So one can theoretically read the local_H and do some operations to
-        # figure out the origin of this 'x'.
-
-        # print('Tag =', tag)
-        # print('Work =', Work)
-        # print('calc_in =', calc_in)
 
         if tag in [STOP_TAG, PERSIS_STOP]:
             # FIXME: We need to kill all the child processes here.
@@ -242,16 +223,8 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     " implmeneted by the devs.")
             break
 
-        # Look at the message here. Is it a message for a point from which
-        # local optimization has to be started or does it have to be supplied
-        # to a currently running local optimization run.
-        # local_H contains a ton of information.
-
         n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
 
-        print(local_H)
-        1/0
-
         if sim_id_to_child_indices.get(sim_id_recv):
             for child_idx in sim_id_to_child_indices[sim_id_recv]:
                 comm_queue.push((f_x_recv, grad_f_x_recv))
@@ -274,17 +247,9 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         else:
             n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
 
-            # Decide if there are any new points to start a localopt run
             starting_inds = decide_where_to_start_localopt(local_H, n, n_s, rk_const, mu, nu)
 
             for ind in starting_inds:
-                # Start localopt child processes
-
-                # Mark point as having started a run
-                # Why does it help to mark the total number of runs? JL: it's
-                # useful to assign a unique ID to each run that is started.
-                # Such information is one way (but not the only way) to give
-                # funciton values to the correct child process.
                 total_runs += 1
                 local_H['started_run'][ind] = 1
 
@@ -312,8 +277,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 else:
                     sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(processes), )
 
-                #FIXME: Be very careful about the sim_id.
-                # That is all what we have.
                 send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
 
     raise NotImplementedError("Persistent APOSMM is not fully supported, yet.")

From 4e2cea592f5e9198fde27e8046741e8ef3599d8a Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Mon, 15 Jul 2019 13:23:13 -0500
Subject: [PATCH 015/644] logic fix for the starting the process

---
 libensemble/gen_funcs/persistent_aposmm.py | 44 ++++++++++++++--------
 1 file changed, 28 insertions(+), 16 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 463e995ac..096413104 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -206,21 +206,22 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     send_initial_sample(gen_specs, persis_info, n, c_flag, comm, local_H,
             sim_id_to_child_indices)
 
-    # Separate the logic of filling local_H and sending it.
-    # Reason: To a new developer this doesn't look like local_H will get
-    # edited.
-
     tag = None
     O = np.empty(0, dtype=gen_specs['out'])  # noqa: E741
     while 1:
         # Receive from manager
         tag, Work, calc_in = get_mgr_worker_msg(comm)
-        x_recv, f_x_recv, grad_f_x_recv, sim_id_recv = calc_in[0]
+        (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in[0]
 
         if tag in [STOP_TAG, PERSIS_STOP]:
-            # FIXME: We need to kill all the child processes here.
-            raise NotImplementedError("Killing of child processes in not"
-                    " implmeneted by the devs.")
+            # FIXME: If there is any indication that all child processes are
+            # done with their work, we can do this a bit more cleanly i.e.
+            # first join and check if they are still alive, only then kill.
+
+            # sending SIGKILL to the processes.
+            # TODO: should we use SIGTERM instead?
+            for p in processes:
+                p.kill()
             break
 
         n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
@@ -237,7 +238,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 x_new = comm_queue.get()
 
                 add_to_local_H(local_H, x_new, gen_specs, c_flag, local_flag=1, on_cube=True)
-                # TODO:[KK]: Would it be true that the local_H[-1] would be our
+                # FIXME:[KK]: Would it be true that the local_H[-1] would be our
                 # new point?
                 send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
                 if local_H[-1]['sim_id'] in sim_id_to_child_indices:
@@ -254,15 +255,18 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 local_H['started_run'][ind] = 1
 
                 child_can_read_evts.append(Event())
+                child_can_read_evts[-1].unset()
 
-                # FIXME: f_x must be read from local_H.
-
-                p = Process(run_local_opt, args=(gen_specs, comm_queue, x_recv,
+                parent_can_read_from_queue.unset()
+                p = Process(run_local_opt, args=(gen_specs, comm_queue, local_H[ind]['x'],
                     child_can_read_evts[-1], parent_can_read_from_queue))
                 processes.append(p)
                 p.start()
 
-                comm_queue.push((f_x_recv, grad_f_x_recv))
+                parent_can_read_from_queue.wait()
+                assert comm_queue.get() == local_H[ind]['x']
+
+                comm_queue.push(local_H[ind][['f', 'grad']])
                 parent_can_read_from_queue.unset()
 
                 child_can_read_evts[-1].set()
@@ -272,17 +276,25 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                 add_to_local_H(local_H, x_new, gen_specs, c_flag, local_flag=1, on_cube=True)
 
+                # FIXME: again makes the assumption that the the newly added
+                # point comes in local_H[-1]
+
                 if local_H[-1]['sim_id'] in sim_id_to_child_indices:
-                    sim_id_to_child_indices[local_H[-1]['sim_id']] += (len(processes), )
+                    sim_id_to_child_indices[local_H[-1]['sim_id']] += (len(processes)-1, )
                 else:
-                    sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(processes), )
+                    sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(processes)-1, )
 
                 send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
 
+    comm_queue.close()
+    comm_queue.join_thread()
+
     raise NotImplementedError("Persistent APOSMM is not fully supported, yet.")
 
     for p in processes:
-        p.join()
+        if p.is_alive():
+            raise RuntimeError("Atleast one child process is still active, even after"
+                    " killing all the children.")
 
     return O, persis_info, tag
 

From a97c96411bd6b88b5dd6fd41a5a6601c82ab26bf Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Mon, 15 Jul 2019 13:56:44 -0500
Subject: [PATCH 016/644] fixes multiprocessing syntax errors

---
 libensemble/gen_funcs/persistent_aposmm.py | 19 ++++++++-----------
 1 file changed, 8 insertions(+), 11 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 096413104..f15792f59 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -211,7 +211,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     while 1:
         # Receive from manager
         tag, Work, calc_in = get_mgr_worker_msg(comm)
-        (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in[0]
+        (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in
 
         if tag in [STOP_TAG, PERSIS_STOP]:
             # FIXME: If there is any indication that all child processes are
@@ -230,7 +230,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
             for child_idx in sim_id_to_child_indices[sim_id_recv]:
                 comm_queue.push((f_x_recv, grad_f_x_recv))
 
-                parent_can_read_from_queue.unset()
+                parent_can_read_from_queue.clear()
 
                 child_can_read_evts[child_idx].set()
                 parent_can_read_from_queue.wait()
@@ -255,11 +255,11 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 local_H['started_run'][ind] = 1
 
                 child_can_read_evts.append(Event())
-                child_can_read_evts[-1].unset()
 
-                parent_can_read_from_queue.unset()
-                p = Process(run_local_opt, args=(gen_specs, comm_queue, local_H[ind]['x'],
-                    child_can_read_evts[-1], parent_can_read_from_queue))
+                parent_can_read_from_queue.clear()
+                p = Process(target=run_local_opt, args=(gen_specs, comm_queue, local_H[ind]['x'],
+                    child_can_read_evts[-1],
+                    parent_can_read_from_queue))
                 processes.append(p)
                 p.start()
 
@@ -267,7 +267,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 assert comm_queue.get() == local_H[ind]['x']
 
                 comm_queue.push(local_H[ind][['f', 'grad']])
-                parent_can_read_from_queue.unset()
+                parent_can_read_from_queue.clear()
 
                 child_can_read_evts[-1].set()
                 parent_can_read_from_queue.wait()
@@ -289,8 +289,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     comm_queue.close()
     comm_queue.join_thread()
 
-    raise NotImplementedError("Persistent APOSMM is not fully supported, yet.")
-
     for p in processes:
         if p.is_alive():
             raise RuntimeError("Atleast one child process is still active, even after"
@@ -304,7 +302,7 @@ def callback_function(x, grad, comm_queue, child_can_read, parent_can_read, gen_
     parent_can_read.set()
     child_can_read.wait()
     result = comm_queue.get()
-    child_can_read.unset()
+    child_can_read.clear()
     if gen_specs['localopt_method'] in ['LD_MMA']:
         grad[:] = result[1]
 
@@ -985,7 +983,6 @@ def send_initial_sample(gen_specs, persis_info, n, c_flag, comm, local_H,
         assert sim_id not in sim_id_to_child_indices
         sim_id_to_child_indices[sim_id] = None
 
-    print('Sent =', local_H[['x', 'sim_id']])
     send_mgr_worker_msg(comm, local_H[['x', 'sim_id']])
 
 

From acfce629e30787e3ec8c7f2d5e04b0fb879ec894 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Mon, 15 Jul 2019 16:44:50 -0500
Subject: [PATCH 017/644] takes nlopt from develop

---
 libensemble/gen_funcs/persistent_aposmm.py | 57 ++++++++++++++++++----
 1 file changed, 48 insertions(+), 9 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index f15792f59..c06f521d8 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -209,6 +209,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     tag = None
     O = np.empty(0, dtype=gen_specs['out'])  # noqa: E741
     while 1:
+        print('Here now!')
         # Receive from manager
         tag, Work, calc_in = get_mgr_worker_msg(comm)
         (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in
@@ -228,7 +229,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
         if sim_id_to_child_indices.get(sim_id_recv):
             for child_idx in sim_id_to_child_indices[sim_id_recv]:
-                comm_queue.push((f_x_recv, grad_f_x_recv))
+                comm_queue.put((f_x_recv, grad_f_x_recv))
 
                 parent_can_read_from_queue.clear()
 
@@ -256,21 +257,25 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                 child_can_read_evts.append(Event())
 
+                print('Initing process')
+
                 parent_can_read_from_queue.clear()
-                p = Process(target=run_local_opt, args=(gen_specs, comm_queue, local_H[ind]['x'],
+                p = Process(target=run_local_nlopt, args=(gen_specs, comm_queue, local_H[ind]['x'],
                     child_can_read_evts[-1],
                     parent_can_read_from_queue))
                 processes.append(p)
                 p.start()
+                print('[Master]: Started a process')
 
                 parent_can_read_from_queue.wait()
-                assert comm_queue.get() == local_H[ind]['x']
+                assert np.allclose(comm_queue.get(), local_H[ind]['x'])
 
-                comm_queue.push(local_H[ind][['f', 'grad']])
+                comm_queue.put(local_H[ind][['f', 'grad']])
                 parent_can_read_from_queue.clear()
 
                 child_can_read_evts[-1].set()
                 parent_can_read_from_queue.wait()
+                print('[Master]: Getting a new x_new.')
 
                 x_new = comm_queue.get()
 
@@ -298,27 +303,61 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
 
 def callback_function(x, grad, comm_queue, child_can_read, parent_can_read, gen_specs):
+    print('[Child]: Hello, here I am ')
     comm_queue.put(x)
     parent_can_read.set()
     child_can_read.wait()
     result = comm_queue.get()
     child_can_read.clear()
     if gen_specs['localopt_method'] in ['LD_MMA']:
+        print('Result =', result[1])
+        print('Grad.shape =', grad.shape)
+        1/0
         grad[:] = result[1]
 
     return result[0]
 
 
-def run_local_opt(gen_specs, comm_queue, x0, child_can_read,
+def run_local_nlopt(gen_specs, comm_queue, x0, child_can_read,
         parent_can_read):
+    print('[Child]: Whats up')
+
+    n = len(gen_specs['ub'])
+
+    opt = nlopt.opt(getattr(nlopt, gen_specs['localopt_method']), n)
+
+    lb = gen_specs['lb']
+    ub = gen_specs['ub']
+    opt.set_lower_bounds(lb)
+    opt.set_upper_bounds(ub)
+
+    # Care must be taken here because a too-large initial step causes nlopt to move the starting point!
+    dist_to_bound = min(min(ub-x0), min(x0-lb))
+    assert dist_to_bound > np.finfo(np.float32).eps, "The distance to the boundary is too small for NLopt to handle"
+
+    if 'dist_to_bound_multiple' in gen_specs:
+        opt.set_initial_step(dist_to_bound*gen_specs['dist_to_bound_multiple'])
+    else:
+        opt.set_initial_step(dist_to_bound)
+
+    # FIXME: Setting max evaluations = 100
+    opt.set_maxeval(100)
 
-    opt = nlopt.opt(nlopt.LN_BOBYQA, 2)
     opt.set_min_objective(lambda x, grad: callback_function(x, grad,
         comm_queue, child_can_read, parent_can_read, gen_specs))
 
-    opt.set_lower_bounds(-np.array([3, 2]))
-    opt.set_upper_bounds(np.array([3, 2]))
-    opt.set_ftol_rel(1e-4)
+    if 'xtol_rel' in gen_specs:
+        opt.set_xtol_rel(gen_specs['xtol_rel'])
+    if 'ftol_rel' in gen_specs:
+        opt.set_ftol_rel(gen_specs['ftol_rel'])
+    if 'xtol_abs' in gen_specs:
+        opt.set_xtol_abs(gen_specs['xtol_abs'])
+    if 'ftol_abs' in gen_specs:
+        opt.set_ftol_abs(gen_specs['ftol_abs'])
+
+    x_opt = opt.optimize(x0)
+
+    #FIXME: Do we need to do of the final 'x_opt'?
 
 
 def update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in):

From 75e1b29f18f5ba95be57fd2f3089455d19179977 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 16 Jul 2019 04:45:13 -0500
Subject: [PATCH 018/644] Noting a possible trip-up in processing calc_in

---
 libensemble/gen_funcs/persistent_aposmm.py | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index c06f521d8..843fa0349 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -213,6 +213,16 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         # Receive from manager
         tag, Work, calc_in = get_mgr_worker_msg(comm)
         (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in
+        # Kaushik, I have concerns about the above approach for processing calc_in
+        # 1. I'm not sure that the contents of calc_in will always be in the order, x, f, grad, sim_id. 
+        # 2. Note that grad might not be available for some objectives. 
+        # Perhaps it's better to use something like
+        # x_recv = calc_in['x']
+        # f_x_recv = calc_in['f']
+        # sim_id_recv = calc_in['sim_id']
+        # if 'grad' in calc_in.dtype.names:
+        #     grad_f_x_recv = calc_in['grad']
+
 
         if tag in [STOP_TAG, PERSIS_STOP]:
             # FIXME: If there is any indication that all child processes are

From e07f7bcc67405c84ea54cb6672930f0b2c412787 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Tue, 16 Jul 2019 14:04:23 -0500
Subject: [PATCH 019/644] adds debug statements, maintains consistency of
 x_on_cube

---
 libensemble/gen_funcs/persistent_aposmm.py | 45 ++++++++++++----------
 1 file changed, 25 insertions(+), 20 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index c06f521d8..4ed0afd54 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -209,12 +209,13 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     tag = None
     O = np.empty(0, dtype=gen_specs['out'])  # noqa: E741
     while 1:
-        print('Here now!')
         # Receive from manager
         tag, Work, calc_in = get_mgr_worker_msg(comm)
-        (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in
+        if calc_in:
+            (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in
 
         if tag in [STOP_TAG, PERSIS_STOP]:
+            print('[Parent]: Received a stop tag, killing all children.')
             # FIXME: If there is any indication that all child processes are
             # done with their work, we can do this a bit more cleanly i.e.
             # first join and check if they are still alive, only then kill.
@@ -229,6 +230,8 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
         if sim_id_to_child_indices.get(sim_id_recv):
             for child_idx in sim_id_to_child_indices[sim_id_recv]:
+                print('[Parent]: Received the eval for {}, giving it to the'
+                    ' child_idx: {}.'.format(x_recv, child_idx))
                 comm_queue.put((f_x_recv, grad_f_x_recv))
 
                 parent_can_read_from_queue.clear()
@@ -237,8 +240,11 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 parent_can_read_from_queue.wait()
 
                 x_new = comm_queue.get()
+                print('[Parent]: The child returned {}.'.format(x_new))
+
+                add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
+                assert np.allclose(x_new, local_H[-1]['x_on_cube'])
 
-                add_to_local_H(local_H, x_new, gen_specs, c_flag, local_flag=1, on_cube=True)
                 # FIXME:[KK]: Would it be true that the local_H[-1] would be our
                 # new point?
                 send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
@@ -260,15 +266,18 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 print('Initing process')
 
                 parent_can_read_from_queue.clear()
-                p = Process(target=run_local_nlopt, args=(gen_specs, comm_queue, local_H[ind]['x'],
+                p = Process(target=run_local_nlopt, args=(gen_specs,
+                    comm_queue, local_H[ind]['x_on_cube'],
                     child_can_read_evts[-1],
                     parent_can_read_from_queue))
                 processes.append(p)
                 p.start()
-                print('[Master]: Started a process')
+                print('[Parent]: Started a child process')
 
                 parent_can_read_from_queue.wait()
-                assert np.allclose(comm_queue.get(), local_H[ind]['x'])
+                print('[Parent]: Done waiting.')
+
+                assert np.allclose(comm_queue.get(), local_H[ind]['x_on_cube'])
 
                 comm_queue.put(local_H[ind][['f', 'grad']])
                 parent_can_read_from_queue.clear()
@@ -279,7 +288,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                 x_new = comm_queue.get()
 
-                add_to_local_H(local_H, x_new, gen_specs, c_flag, local_flag=1, on_cube=True)
+                add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
 
                 # FIXME: again makes the assumption that the the newly added
                 # point comes in local_H[-1]
@@ -294,25 +303,24 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     comm_queue.close()
     comm_queue.join_thread()
 
+    print('Done with everything')
+
     for p in processes:
         if p.is_alive():
-            raise RuntimeError("Atleast one child process is still active, even after"
+            raise RuntimeError("[Parent]: Atleast one child process is still active, even after"
                     " killing all the children.")
 
     return O, persis_info, tag
 
 
 def callback_function(x, grad, comm_queue, child_can_read, parent_can_read, gen_specs):
-    print('[Child]: Hello, here I am ')
     comm_queue.put(x)
+    print('[Child]: Parent should no longer wait.')
     parent_can_read.set()
     child_can_read.wait()
     result = comm_queue.get()
     child_can_read.clear()
     if gen_specs['localopt_method'] in ['LD_MMA']:
-        print('Result =', result[1])
-        print('Grad.shape =', grad.shape)
-        1/0
         grad[:] = result[1]
 
     return result[0]
@@ -320,14 +328,13 @@ def callback_function(x, grad, comm_queue, child_can_read, parent_can_read, gen_
 
 def run_local_nlopt(gen_specs, comm_queue, x0, child_can_read,
         parent_can_read):
-    print('[Child]: Whats up')
-
+    print('[Child]: Started local opt at {}.'.format(x0))
     n = len(gen_specs['ub'])
 
     opt = nlopt.opt(getattr(nlopt, gen_specs['localopt_method']), n)
 
-    lb = gen_specs['lb']
-    ub = gen_specs['ub']
+    lb = np.zeros(n)
+    ub = np.ones(n)
     opt.set_lower_bounds(lb)
     opt.set_upper_bounds(ub)
 
@@ -355,10 +362,10 @@ def run_local_nlopt(gen_specs, comm_queue, x0, child_can_read,
     if 'ftol_abs' in gen_specs:
         opt.set_ftol_abs(gen_specs['ftol_abs'])
 
+    #FIXME: Do we need to do something of the final 'x_opt'?
+    print('[Child]: Started my optimization')
     x_opt = opt.optimize(x0)
 
-    #FIXME: Do we need to do of the final 'x_opt'?
-
 
 def update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in):
 
@@ -378,7 +385,6 @@ def add_to_local_H(local_H, pts, gen_specs, c_flag, local_flag=0, sorted_run_ind
     """
     Adds points to O, the numpy structured array to be sent back to the manager
     """
-
     assert not local_flag or len(pts) == 1, "Can't > 1 local points"
 
     len_local_H = len(local_H)
@@ -986,7 +992,6 @@ def initialize_APOSMM(H, gen_specs, libE_info):
 
     total_runs = 0
 
-
     comm = libE_info['comm']
 
     local_H_fields = [('f',float),

From 5a7494ac39b568c196b2db54bf93c362dc217bf2 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Wed, 17 Jul 2019 09:54:46 -0500
Subject: [PATCH 020/644] smore progress

---
 libensemble/gen_funcs/persistent_aposmm.py | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index f0623c142..792a70b0d 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -213,7 +213,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         tag, Work, calc_in = get_mgr_worker_msg(comm)
         if calc_in:
             (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in
-        # Kaushik, I have concerns about the above approach for processing calc_in
+        # JL: Kaushik, I have concerns about the above approach for processing calc_in
         # 1. I'm not sure that the contents of calc_in will always be in the order, x, f, grad, sim_id. 
         # 2. Note that grad might not be available for some objectives. 
         # Perhaps it's better to use something like
@@ -223,8 +223,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         # if 'grad' in calc_in.dtype.names:
         #     grad_f_x_recv = calc_in['grad']
 
->>>>>>> 75e1b29f18f5ba95be57fd2f3089455d19179977
-
         if tag in [STOP_TAG, PERSIS_STOP]:
             print('[Parent]: Received a stop tag, killing all children.')
             # FIXME: If there is any indication that all child processes are

From fb4397408f296758c6926d03965f119eece0aa1e Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Wed, 17 Jul 2019 13:51:46 -0500
Subject: [PATCH 021/644] idenitifies when the child local opt converges

---
 libensemble/gen_funcs/persistent_aposmm.py | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 792a70b0d..f6922d299 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -201,7 +201,9 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     sim_id_to_child_indices = {}
 
     if gen_specs['initial_sample_size'] != 1:
-        raise RuntimeError("sample size > not supported for now.")
+        raise RuntimeError("sample size > 1 not supported for now.")
+
+    # We just sampled a single point.
 
     send_initial_sample(gen_specs, persis_info, n, c_flag, comm, local_H,
             sim_id_to_child_indices)
@@ -214,8 +216,8 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         if calc_in:
             (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in
         # JL: Kaushik, I have concerns about the above approach for processing calc_in
-        # 1. I'm not sure that the contents of calc_in will always be in the order, x, f, grad, sim_id. 
-        # 2. Note that grad might not be available for some objectives. 
+        # 1. I'm not sure that the contents of calc_in will always be in the order, x, f, grad, sim_id.
+        # 2. Note that grad might not be available for some objectives.
         # Perhaps it's better to use something like
         # x_recv = calc_in['x']
         # f_x_recv = calc_in['f']
@@ -246,9 +248,13 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 parent_can_read_from_queue.clear()
 
                 child_can_read_evts[child_idx].set()
+                print('[Parent]: I am waiting')
                 parent_can_read_from_queue.wait()
+                print('[Parent]: Wohoo I am free again')
 
                 x_new = comm_queue.get()
+                if x_new == 'Converged':
+                    raise NotImplementedError("We don't know what to do yet.")
                 print('[Parent]: The child returned {}.'.format(x_new))
 
                 add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
@@ -283,6 +289,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 p.start()
                 print('[Parent]: Started a child process')
 
+                print('[Parent]: I am waiting')
                 parent_can_read_from_queue.wait()
                 print('[Parent]: Done waiting.')
 
@@ -326,7 +333,9 @@ def callback_function(x, grad, comm_queue, child_can_read, parent_can_read, gen_
     comm_queue.put(x)
     print('[Child]: Parent should no longer wait.')
     parent_can_read.set()
+    print('[Child]: I have started waiting')
     child_can_read.wait()
+    print('[Child]: Wohooo.. I am free folks')
     result = comm_queue.get()
     child_can_read.clear()
     if gen_specs['localopt_method'] in ['LD_MMA']:
@@ -374,6 +383,9 @@ def run_local_nlopt(gen_specs, comm_queue, x0, child_can_read,
     #FIXME: Do we need to do something of the final 'x_opt'?
     print('[Child]: Started my optimization')
     x_opt = opt.optimize(x0)
+    print('[Child]: I have converged.')
+    comm_queue.put('Converged')
+    parent_can_read.set()
 
 
 def update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in):
@@ -1062,3 +1074,5 @@ def display_exception(e):
 #     persis_info = persis_info.item()
 #     import ipdb; ipdb.set_trace()
 #     aposmm_logic(H,persis_info,gen_specs,{})
+
+# vim:fdm=marker

From fa68d4a9dec197a78112972396432ba1b97c3d36 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Thu, 18 Jul 2019 10:25:30 -0500
Subject: [PATCH 022/644] readds the support for >1 initial_sample_size

---
 libensemble/gen_funcs/persistent_aposmm.py | 38 ++++++++++++----------
 1 file changed, 21 insertions(+), 17 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index f6922d299..7043f2ef8 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -200,9 +200,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
     sim_id_to_child_indices = {}
 
-    if gen_specs['initial_sample_size'] != 1:
-        raise RuntimeError("sample size > 1 not supported for now.")
-
     # We just sampled a single point.
 
     send_initial_sample(gen_specs, persis_info, n, c_flag, comm, local_H,
@@ -253,20 +250,26 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 print('[Parent]: Wohoo I am free again')
 
                 x_new = comm_queue.get()
-                if x_new == 'Converged':
-                    raise NotImplementedError("We don't know what to do yet.")
                 print('[Parent]: The child returned {}.'.format(x_new))
-
-                add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
-                assert np.allclose(x_new, local_H[-1]['x_on_cube'])
-
-                # FIXME:[KK]: Would it be true that the local_H[-1] would be our
-                # new point?
-                send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
-                if local_H[-1]['sim_id'] in sim_id_to_child_indices:
-                    sim_id_to_child_indices[local_H[-1]['sim_id']] += (child_idx, )
+                if isinstance(x_new, tuple):
+                    # FIXME: [KK]: This is ugly and every bit of it happens in
+                    # my mind, this should be cleaned up duing the cleanup
+                    # phase.
+                    x_opt = x_new[1]
+                    # Need to figure out what are run_ids.
+                    update_history_optimal(x_opt, H, 1/0)
+                    raise NotImplementedError("We don't know what to do yet.")
                 else:
-                    sim_id_to_child_indices[local_H[-1]['sim_id']] = (child_idx, )
+                    add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
+                    assert np.allclose(x_new, local_H[-1]['x_on_cube'])
+
+                    # FIXME:[KK]: Would it be true that the local_H[-1] would be our
+                    # new point?
+                    send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
+                    if local_H[-1]['sim_id'] in sim_id_to_child_indices:
+                        sim_id_to_child_indices[local_H[-1]['sim_id']] += (child_idx, )
+                    else:
+                        sim_id_to_child_indices[local_H[-1]['sim_id']] = (child_idx, )
         else:
             n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
 
@@ -384,7 +387,7 @@ def run_local_nlopt(gen_specs, comm_queue, x0, child_can_read,
     print('[Child]: Started my optimization')
     x_opt = opt.optimize(x0)
     print('[Child]: I have converged.')
-    comm_queue.put('Converged')
+    comm_queue.put(('Converged', x_opt))
     parent_can_read.set()
 
 
@@ -1048,7 +1051,8 @@ def send_initial_sample(gen_specs, persis_info, n, c_flag, comm, local_H,
         assert sim_id not in sim_id_to_child_indices
         sim_id_to_child_indices[sim_id] = None
 
-    send_mgr_worker_msg(comm, local_H[['x', 'sim_id']])
+    for i in range(len(local_H)):
+        send_mgr_worker_msg(comm, local_H[i][['x', 'sim_id']])
 
 
 def display_exception(e):

From 5f87d104a875f0d869bad07158aea2eca2acdafa Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Thu, 18 Jul 2019 16:54:42 -0500
Subject: [PATCH 023/644] introduces child_id_to_run_id

---
 libensemble/gen_funcs/persistent_aposmm.py | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 7043f2ef8..469283213 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -199,6 +199,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     n, n_s, c_flag, rk_const, mu, nu, total_runs, comm, local_H = initialize_APOSMM(H, gen_specs, libE_info)
 
     sim_id_to_child_indices = {}
+    child_id_to_run_id = {}
 
     # We just sampled a single point.
 
@@ -266,6 +267,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     # FIXME:[KK]: Would it be true that the local_H[-1] would be our
                     # new point?
                     send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
+                    persis_info['run_order'][child_id_to_run_id[child_idx]].append(local_H[-1]['sim_id'])
                     if local_H[-1]['sim_id'] in sim_id_to_child_indices:
                         sim_id_to_child_indices[local_H[-1]['sim_id']] += (child_idx, )
                     else:
@@ -311,6 +313,9 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                 # FIXME: again makes the assumption that the the newly added
                 # point comes in local_H[-1]
+                persis_info['run_order'][total_runs] = [local_H[-1]['sim_id']]
+                child_id_to_run_id[len(processes)-1] = total_runs
+                # Need to figure out the child number from the run number.
 
                 if local_H[-1]['sim_id'] in sim_id_to_child_indices:
                     sim_id_to_child_indices[local_H[-1]['sim_id']] += (len(processes)-1, )

From b0192f60c64bcfbb6b405baa1e13a5ea5c69d138 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 19 Jul 2019 16:09:01 -0500
Subject: [PATCH 024/644] brings back in update_history_optimal and uses a
 local run_order

---
 libensemble/gen_funcs/persistent_aposmm.py | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 469283213..4c2e5dbd9 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -186,7 +186,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     persis_info['old_runs']: Sequence of indices of points in finished runs
 
     """
-
     # {{{ multiprocessing initialization
 
     child_can_read_evts = []
@@ -200,6 +199,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
     sim_id_to_child_indices = {}
     child_id_to_run_id = {}
+    run_order = {}
 
     # We just sampled a single point.
 
@@ -258,16 +258,17 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     # phase.
                     x_opt = x_new[1]
                     # Need to figure out what are run_ids.
-                    update_history_optimal(x_opt, H, 1/0)
-                    raise NotImplementedError("We don't know what to do yet.")
+                    add_to_local_H(local_H, (x_opt, ), gen_specs, c_flag, local_flag=1, on_cube=True)
+                    update_history_optimal(x_opt, local_H,
+                            run_order[child_id_to_run_id[child_idx]])
                 else:
                     add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
-                    assert np.allclose(x_new, local_H[-1]['x_on_cube'])
+                    assert np.allclose(local_H[-1]['x_on_cube'], x_new)
 
                     # FIXME:[KK]: Would it be true that the local_H[-1] would be our
                     # new point?
                     send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
-                    persis_info['run_order'][child_id_to_run_id[child_idx]].append(local_H[-1]['sim_id'])
+                    run_order[child_id_to_run_id[child_idx]].append(local_H[-1]['sim_id'])
                     if local_H[-1]['sim_id'] in sim_id_to_child_indices:
                         sim_id_to_child_indices[local_H[-1]['sim_id']] += (child_idx, )
                     else:
@@ -278,7 +279,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
             starting_inds = decide_where_to_start_localopt(local_H, n, n_s, rk_const, mu, nu)
 
             for ind in starting_inds:
-                total_runs += 1
                 local_H['started_run'][ind] = 1
 
                 child_can_read_evts.append(Event())
@@ -310,11 +310,17 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 x_new = comm_queue.get()
 
                 add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
+                assert np.allclose(local_H[-1]['x_on_cube'], x_new)
+
+                print('Index:', ind)
+                print('Sim_ids:', local_H[:]['sim_id'])
+                assert np.allclose(local_H[-1]['x_on_cube'], x_new)
 
                 # FIXME: again makes the assumption that the the newly added
                 # point comes in local_H[-1]
-                persis_info['run_order'][total_runs] = [local_H[-1]['sim_id']]
+                run_order[total_runs] = [local_H[-1]['sim_id']]
                 child_id_to_run_id[len(processes)-1] = total_runs
+                total_runs += 1
                 # Need to figure out the child number from the run number.
 
                 if local_H[-1]['sim_id'] in sim_id_to_child_indices:

From 119b4f6baaafab80d39ed25a00d5c30846e32c9f Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Mon, 22 Jul 2019 11:48:42 -0500
Subject: [PATCH 025/644] adds some fancy debug statements

---
 libensemble/gen_funcs/persistent_aposmm.py | 34 +++++++++++++++-------
 1 file changed, 23 insertions(+), 11 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 4c2e5dbd9..5e2d1c979 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -209,10 +209,14 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     tag = None
     O = np.empty(0, dtype=gen_specs['out'])  # noqa: E741
     while 1:
+
         # Receive from manager
         tag, Work, calc_in = get_mgr_worker_msg(comm)
+
         if calc_in:
             (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in
+            print(23*"-", "Received f({})".format(x_recv), 24*"-",
+                    flush=True)
         # JL: Kaushik, I have concerns about the above approach for processing calc_in
         # 1. I'm not sure that the contents of calc_in will always be in the order, x, f, grad, sim_id.
         # 2. Note that grad might not be available for some objectives.
@@ -224,7 +228,8 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         #     grad_f_x_recv = calc_in['grad']
 
         if tag in [STOP_TAG, PERSIS_STOP]:
-            print('[Parent]: Received a stop tag, killing all children.')
+
+            print('[Parent]: Received a stop tag, killing all children.', flush=True)
             # FIXME: If there is any indication that all child processes are
             # done with their work, we can do this a bit more cleanly i.e.
             # first join and check if they are still alive, only then kill.
@@ -240,18 +245,18 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         if sim_id_to_child_indices.get(sim_id_recv):
             for child_idx in sim_id_to_child_indices[sim_id_recv]:
                 print('[Parent]: Received the eval for {}, giving it to the'
-                    ' child_idx: {}.'.format(x_recv, child_idx))
+                    ' child_idx: {}.'.format(x_recv, child_idx), flush=True)
                 comm_queue.put((f_x_recv, grad_f_x_recv))
 
                 parent_can_read_from_queue.clear()
 
                 child_can_read_evts[child_idx].set()
-                print('[Parent]: I am waiting')
+                print('[Parent]: I am waiting for child idx {}'.format(child_idx), flush=True)
                 parent_can_read_from_queue.wait()
-                print('[Parent]: Wohoo I am free again')
+                print('[Parent]: Wohoo I am free again', flush=True)
 
                 x_new = comm_queue.get()
-                print('[Parent]: The child returned {}.'.format(x_new))
+                print('[Parent]: The child returned {}.'.format(x_new), flush=True)
                 if isinstance(x_new, tuple):
                     # FIXME: [KK]: This is ugly and every bit of it happens in
                     # my mind, this should be cleaned up duing the cleanup
@@ -261,6 +266,9 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     add_to_local_H(local_H, (x_opt, ), gen_specs, c_flag, local_flag=1, on_cube=True)
                     update_history_optimal(x_opt, local_H,
                             run_order[child_id_to_run_id[child_idx]])
+                    print("[Parent]: Child {} has converged, miss you :'(".format(child_idx), flush=True)
+                    processes[child_idx].join()
+                    print("[Parent]: Child {} has been joined.".format(child_idx), flush=True)
                 else:
                     add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
                     assert np.allclose(local_H[-1]['x_on_cube'], x_new)
@@ -273,7 +281,10 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                         sim_id_to_child_indices[local_H[-1]['sim_id']] += (child_idx, )
                     else:
                         sim_id_to_child_indices[local_H[-1]['sim_id']] = (child_idx, )
+
         else:
+            print('[Parent]: Did not find any local opt run to associate with.',
+                    flush=True)
             n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
 
             starting_inds = decide_where_to_start_localopt(local_H, n, n_s, rk_const, mu, nu)
@@ -283,7 +294,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                 child_can_read_evts.append(Event())
 
-                print('Initing process')
+                print('[Parent]: Initing process', flush=True)
 
                 parent_can_read_from_queue.clear()
                 p = Process(target=run_local_nlopt, args=(gen_specs,
@@ -292,11 +303,11 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     parent_can_read_from_queue))
                 processes.append(p)
                 p.start()
-                print('[Parent]: Started a child process')
+                print('[Parent]: Started a child process', flush=True)
 
-                print('[Parent]: I am waiting')
+                print('[Parent]: I am waiting', flush=True)
                 parent_can_read_from_queue.wait()
-                print('[Parent]: Done waiting.')
+                print('[Parent]: Done waiting.', flush=True)
 
                 assert np.allclose(comm_queue.get(), local_H[ind]['x_on_cube'])
 
@@ -305,7 +316,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                 child_can_read_evts[-1].set()
                 parent_can_read_from_queue.wait()
-                print('[Master]: Getting a new x_new.')
+                print('[Master]: Getting a new x_new.', flush=True)
 
                 x_new = comm_queue.get()
 
@@ -329,6 +340,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(processes)-1, )
 
                 send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
+        print('[Parent]: Heading to next iteration', flush=True)
 
     comm_queue.close()
     comm_queue.join_thread()
@@ -1063,7 +1075,7 @@ def send_initial_sample(gen_specs, persis_info, n, c_flag, comm, local_H,
         sim_id_to_child_indices[sim_id] = None
 
     for i in range(len(local_H)):
-        send_mgr_worker_msg(comm, local_H[i][['x', 'sim_id']])
+        send_mgr_worker_msg(comm, local_H[i:i+1][['x', 'sim_id']])
 
 
 def display_exception(e):

From 1409424a6c9bfcf3d605af1d8c6d777e28841e1d Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Tue, 23 Jul 2019 11:06:16 -0500
Subject: [PATCH 026/644] some more progress by ignoring same eval received
 from manager

---
 libensemble/gen_funcs/persistent_aposmm.py | 64 ++++++++++++++++------
 1 file changed, 47 insertions(+), 17 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 5e2d1c979..0035be5e8 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -197,14 +197,17 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
     n, n_s, c_flag, rk_const, mu, nu, total_runs, comm, local_H = initialize_APOSMM(H, gen_specs, libE_info)
 
+    received_values = set()
+
     sim_id_to_child_indices = {}
     child_id_to_run_id = {}
     run_order = {}
 
     # We just sampled a single point.
 
-    send_initial_sample(gen_specs, persis_info, n, c_flag, comm, local_H,
-            sim_id_to_child_indices)
+    for _ in range(gen_specs['initial_sample_size']):
+        send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
+                sim_id_to_child_indices)
 
     tag = None
     O = np.empty(0, dtype=gen_specs['out'])  # noqa: E741
@@ -217,6 +220,15 @@ def aposmm(H, persis_info, gen_specs, libE_info):
             (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in
             print(23*"-", "Received f({})".format(x_recv), 24*"-",
                     flush=True)
+            if tuple(x_recv) in received_values:
+                #FIXME:: This should never be the case.
+                print("DANGER!! Re-received a value ignoring it for now, but"
+                        " need to fix it in manager, I guess?", flush=True)
+                send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
+                        sim_id_to_child_indices)
+                continue
+
+            received_values.add(tuple(x_recv))
         # JL: Kaushik, I have concerns about the above approach for processing calc_in
         # 1. I'm not sure that the contents of calc_in will always be in the order, x, f, grad, sim_id.
         # 2. Note that grad might not be available for some objectives.
@@ -244,8 +256,8 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
         if sim_id_to_child_indices.get(sim_id_recv):
             for child_idx in sim_id_to_child_indices[sim_id_recv]:
-                print('[Parent]: Received the eval for {}, giving it to the'
-                    ' child_idx: {}.'.format(x_recv, child_idx), flush=True)
+                print('[Parent]:Giving f = {} it to the'
+                    ' child_idx: {}.'.format(f_x_recv, child_idx), flush=True)
                 comm_queue.put((f_x_recv, grad_f_x_recv))
 
                 parent_can_read_from_queue.clear()
@@ -269,22 +281,26 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     print("[Parent]: Child {} has converged, miss you :'(".format(child_idx), flush=True)
                     processes[child_idx].join()
                     print("[Parent]: Child {} has been joined.".format(child_idx), flush=True)
+
+                    # TODO: send a sample point on converging..
+                    # This one still sends the number of points equal to the 
+                    send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
+                            sim_id_to_child_indices)
                 else:
                     add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
                     assert np.allclose(local_H[-1]['x_on_cube'], x_new)
 
-                    # FIXME:[KK]: Would it be true that the local_H[-1] would be our
-                    # new point?
                     send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
                     run_order[child_id_to_run_id[child_idx]].append(local_H[-1]['sim_id'])
                     if local_H[-1]['sim_id'] in sim_id_to_child_indices:
                         sim_id_to_child_indices[local_H[-1]['sim_id']] += (child_idx, )
                     else:
                         sim_id_to_child_indices[local_H[-1]['sim_id']] = (child_idx, )
-
         else:
             print('[Parent]: Did not find any local opt run to associate with.',
                     flush=True)
+            if n_s < gen_specs['initial_sample_size']:
+                continue
             n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
 
             starting_inds = decide_where_to_start_localopt(local_H, n, n_s, rk_const, mu, nu)
@@ -323,12 +339,8 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
                 assert np.allclose(local_H[-1]['x_on_cube'], x_new)
 
-                print('Index:', ind)
-                print('Sim_ids:', local_H[:]['sim_id'])
                 assert np.allclose(local_H[-1]['x_on_cube'], x_new)
 
-                # FIXME: again makes the assumption that the the newly added
-                # point comes in local_H[-1]
                 run_order[total_runs] = [local_H[-1]['sim_id']]
                 child_id_to_run_id[len(processes)-1] = total_runs
                 total_runs += 1
@@ -340,6 +352,9 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(processes)-1, )
 
                 send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
+            if len(starting_inds) == 0:
+                send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
+                        sim_id_to_child_indices)
         print('[Parent]: Heading to next iteration', flush=True)
 
     comm_queue.close()
@@ -352,16 +367,19 @@ def aposmm(H, persis_info, gen_specs, libE_info):
             raise RuntimeError("[Parent]: Atleast one child process is still active, even after"
                     " killing all the children.")
 
+    #TODO: Figure out what do we need to do from here.
+    1/0
+
     return O, persis_info, tag
 
 
 def callback_function(x, grad, comm_queue, child_can_read, parent_can_read, gen_specs):
     comm_queue.put(x)
-    print('[Child]: Parent should no longer wait.')
+    print('[Child]: Parent should no longer wait.', flush=True)
     parent_can_read.set()
-    print('[Child]: I have started waiting')
+    print('[Child]: I have started waiting', flush=True)
     child_can_read.wait()
-    print('[Child]: Wohooo.. I am free folks')
+    print('[Child]: Wohooo.. I am free folks', flush=True)
     result = comm_queue.get()
     child_can_read.clear()
     if gen_specs['localopt_method'] in ['LD_MMA']:
@@ -372,7 +390,7 @@ def callback_function(x, grad, comm_queue, child_can_read, parent_can_read, gen_
 
 def run_local_nlopt(gen_specs, comm_queue, x0, child_can_read,
         parent_can_read):
-    print('[Child]: Started local opt at {}.'.format(x0))
+    print('[Child]: Started local opt at {}.'.format(x0), flush=True)
     n = len(gen_specs['ub'])
 
     opt = nlopt.opt(getattr(nlopt, gen_specs['localopt_method']), n)
@@ -407,9 +425,9 @@ def run_local_nlopt(gen_specs, comm_queue, x0, child_can_read,
         opt.set_ftol_abs(gen_specs['ftol_abs'])
 
     #FIXME: Do we need to do something of the final 'x_opt'?
-    print('[Child]: Started my optimization')
+    print('[Child]: Started my optimization', flush=True)
     x_opt = opt.optimize(x0)
-    print('[Child]: I have converged.')
+    print('[Child]: I have converged.', flush=True)
     comm_queue.put(('Converged', x_opt))
     parent_can_read.set()
 
@@ -1066,8 +1084,20 @@ def initialize_APOSMM(H, gen_specs, libE_info):
 
     return n, n_s, c_flag, rk_c, mu, nu, total_runs, comm, local_H
 
+
+def send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
+        sim_id_to_child_indices):
+    sampled_points = persis_info['rand_stream'].uniform(0, 1, (1, n))
+    add_to_local_H(local_H, sampled_points, gen_specs, c_flag, on_cube=True)
+    assert local_H['sim_id'][-1] not in sim_id_to_child_indices
+    sim_id_to_child_indices[local_H['sim_id'][-1]] = None
+
+    send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
+
+
 def send_initial_sample(gen_specs, persis_info, n, c_flag, comm, local_H,
         sim_id_to_child_indices):
+    1/0
     sampled_points = persis_info['rand_stream'].uniform(0, 1, (gen_specs['initial_sample_size'], n))
     add_to_local_H(local_H, sampled_points, gen_specs, c_flag, on_cube=True)
     for sim_id in local_H['sim_id'][-gen_specs['initial_sample_size']:]:

From ae4dbe512c5e7af9ff83c450c9930c442f6f79d0 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Tue, 23 Jul 2019 13:55:09 -0500
Subject: [PATCH 027/644] updates current test params

---
 .../regression_tests/test_6-hump_camel_persistent_aposmm.py   | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index 6dea74657..4a1ccaaf9 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -39,7 +39,7 @@
              'in': [],
              'out': gen_out,
              'batch_mode': True,
-             'initial_sample_size': 1,
+             'initial_sample_size': 50,
              'localopt_method': 'LD_MMA',
              'xtol_rel': 1e-3,
              'lb': np.array([-3, -2]),
@@ -49,7 +49,7 @@
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
-exit_criteria = {'sim_max': 40}
+exit_criteria = {'sim_max': 400}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,

From a1968f89eceb8adc133976d3ba37acd86e2e6792 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Tue, 23 Jul 2019 13:57:10 -0500
Subject: [PATCH 028/644] debug statements

---
 libensemble/alloc_funcs/support.py         | 3 +++
 libensemble/gen_funcs/persistent_aposmm.py | 7 ++++---
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/libensemble/alloc_funcs/support.py b/libensemble/alloc_funcs/support.py
index 927003ffe..56ebe43aa 100644
--- a/libensemble/alloc_funcs/support.py
+++ b/libensemble/alloc_funcs/support.py
@@ -25,6 +25,7 @@ def count_persis_gens(W):
 
 def sim_work(Work, i, H_fields, H_rows, persis_info, **libE_info):
     "Add sim work record to work array."
+    print('[Allocator]: Calling sim_work for {}.'.format(H_rows), flush=True)
     libE_info['H_rows'] = H_rows
     Work[i] = {'H_fields': H_fields,
                'persis_info': persis_info,
@@ -34,6 +35,8 @@ def sim_work(Work, i, H_fields, H_rows, persis_info, **libE_info):
 
 def gen_work(Work, i, H_fields, H_rows, persis_info, **libE_info):
     "Add gen work record to work array."
+    print('[Allocator]: Calling gen_work for {}.'.format(H_rows), flush=True)
+
     libE_info['H_rows'] = H_rows
     Work[i] = {'H_fields': H_fields,
                'persis_info': persis_info,
diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 0035be5e8..c41ec4f6b 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -222,8 +222,8 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     flush=True)
             if tuple(x_recv) in received_values:
                 #FIXME:: This should never be the case.
-                print("DANGER!! Re-received a value ignoring it for now, but"
-                        " need to fix it in manager, I guess?", flush=True)
+                print("DANGER!! Re-received a value(SimID = {}) ignoring it for now, but"
+                        " need to fix it in manager, I guess?".format(sim_id_recv), flush=True)
                 send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
                         sim_id_to_child_indices)
                 continue
@@ -360,7 +360,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     comm_queue.close()
     comm_queue.join_thread()
 
-    print('Done with everything')
+    print('Done with everything', flush=True)
 
     for p in processes:
         if p.is_alive():
@@ -369,6 +369,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
     #TODO: Figure out what do we need to do from here.
     1/0
+    print('This line should not appear', flush=True)
 
     return O, persis_info, tag
 

From fac46436e658922d0ecd75b07ba68bd74e215c60 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 23 Jul 2019 15:20:17 -0500
Subject: [PATCH 029/644] Broken code, but coming up to talk

---
 libensemble/alloc_funcs/start_only_persistent.py              | 4 +++-
 .../regression_tests/test_6-hump_camel_persistent_aposmm.py   | 2 +-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/libensemble/alloc_funcs/start_only_persistent.py b/libensemble/alloc_funcs/start_only_persistent.py
index a126f796d..c1a35e228 100644
--- a/libensemble/alloc_funcs/start_only_persistent.py
+++ b/libensemble/alloc_funcs/start_only_persistent.py
@@ -21,13 +21,15 @@ def only_persistent_gens(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     # returned, give them back to i. Otherwise, give nothing to i
     for i in avail_worker_ids(W, persistent=True):
         gen_inds = (H['gen_worker'] == i)
-        if np.all(H['returned'][gen_inds]):
+        if np.any(np.logical_and(H['returned'][gen_inds],~H['given_back'][gen_inds])):
             last_time_gen_gave_batch = np.max(H['gen_time'][gen_inds])
             inds_of_last_batch_from_gen = H['sim_id'][gen_inds][H['gen_time'][gen_inds] == last_time_gen_gave_batch]
             gen_work(Work, i,
                      sim_specs['in'] + [n[0] for n in sim_specs['out']] + [('sim_id')],
                      np.atleast_1d(inds_of_last_batch_from_gen), persis_info[i], persistent=True)
 
+            H['given_back'][inds_of_last_batch_from_gen] = True
+
     task_avail = ~H['given']
     for i in avail_worker_ids(W, persistent=False):
         if np.any(task_avail):
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index 4a1ccaaf9..9c3b7313b 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -45,7 +45,7 @@
              'lb': np.array([-3, -2]),
              'ub': np.array([3, 2])}
 
-alloc_specs = {'alloc_f': alloc_f, 'out': []}
+alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back',bool)]}
 
 persis_info = per_worker_stream({}, nworkers + 1)
 

From bddfdc675a89979450b97c3cb4e46d1b81a3b099 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 23 Jul 2019 16:12:01 -0500
Subject: [PATCH 030/644] Helping with the debugging for Kaushik

---
 libensemble/gen_funcs/support.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/libensemble/gen_funcs/support.py b/libensemble/gen_funcs/support.py
index e5084828d..e083c937e 100644
--- a/libensemble/gen_funcs/support.py
+++ b/libensemble/gen_funcs/support.py
@@ -11,6 +11,7 @@ def sendrecv_mgr_worker_msg(comm, O, status=None):
 def send_mgr_worker_msg(comm, O):
     """Send message from worker to manager.
     """
+    print('About to send: ', O['sim_id'])
     D = {'calc_out': O,
          'libE_info': {'persistent': True},
          'calc_status': UNSET_TAG,

From f39155ee82213107805cca6a514112208218c02f Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 24 Jul 2019 07:50:40 -0500
Subject: [PATCH 031/644] Helping with the debugging for Kaushik

---
 libensemble/gen_funcs/support.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/gen_funcs/support.py b/libensemble/gen_funcs/support.py
index e083c937e..094914344 100644
--- a/libensemble/gen_funcs/support.py
+++ b/libensemble/gen_funcs/support.py
@@ -11,7 +11,7 @@ def sendrecv_mgr_worker_msg(comm, O, status=None):
 def send_mgr_worker_msg(comm, O):
     """Send message from worker to manager.
     """
-    print('About to send: ', O['sim_id'])
+    print('About to send: ', O['sim_id'],flush=True)
     D = {'calc_out': O,
          'libE_info': {'persistent': True},
          'calc_status': UNSET_TAG,

From 10f6f726868820c398ac13210f24a7eb3d1d2397 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 24 Jul 2019 08:53:05 -0500
Subject: [PATCH 032/644] Adding a libE check that generated sim_ids are in
 order

---
 libensemble/history.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/libensemble/history.py b/libensemble/history.py
index ce852d1f1..6dc4c1100 100644
--- a/libensemble/history.py
+++ b/libensemble/history.py
@@ -150,7 +150,11 @@ def update_history_x_in(self, gen_worker, O):
             update_inds = np.arange(self.index, self.index+num_new)
             self.H['sim_id'][self.index:self.index+num_new] = range(self.index, self.index+num_new)
         else:
-            # gen method is building sim_id.
+            # gen method is building sim_id or adjusting values in existing sim_id rows.
+
+            # Ensure there aren't any gaps in the generated sim_id values:
+            assert np.all(np.isin(np.arange(self.index,np.max(O['sim_id'])+1),O['sim_id'])), "The generator function has produced sim_id that are not in order."
+
             num_new = len(np.setdiff1d(O['sim_id'], self.H['sim_id']))
 
             if num_new > rows_remaining:

From 9e8d5103bb61a8eca02973b234b835a275375cdc Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Wed, 24 Jul 2019 09:17:17 -0500
Subject: [PATCH 033/644] some more debug statements about send/receive

---
 libensemble/gen_funcs/support.py | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/libensemble/gen_funcs/support.py b/libensemble/gen_funcs/support.py
index e5084828d..8e432e7b3 100644
--- a/libensemble/gen_funcs/support.py
+++ b/libensemble/gen_funcs/support.py
@@ -1,4 +1,5 @@
 from libensemble.message_numbers import STOP_TAG, PERSIS_STOP, UNSET_TAG, EVAL_GEN_TAG
+import sys
 
 
 def sendrecv_mgr_worker_msg(comm, O, status=None):
@@ -11,6 +12,8 @@ def sendrecv_mgr_worker_msg(comm, O, status=None):
 def send_mgr_worker_msg(comm, O):
     """Send message from worker to manager.
     """
+    assert len(O) == 1
+    print(25*"-", "Sending {}".format(O[0][0]), 25*"-", flush=True)
     D = {'calc_out': O,
          'libE_info': {'persistent': True},
          'calc_status': UNSET_TAG,
@@ -22,9 +25,14 @@ def send_mgr_worker_msg(comm, O):
 def get_mgr_worker_msg(comm, status=None):
     """Get message to worker from manager.
     """
+    print('[Parent]: Expecting a message from Manager...', flush=True)
     tag, Work = comm.recv()
+    print('[Parent]: Received a tag {}'.format(tag), flush=True)
+    sys.stdout.flush()
     if tag in [STOP_TAG, PERSIS_STOP]:
         comm.push_back(tag, Work)
         return tag, None, None
+    print('[Parent]: Expecting a message from Manager...', flush=True)
     _, calc_in = comm.recv()
+    print('[Parent]: Received some message.', flush=True)
     return tag, Work, calc_in

From 8cd262cd01250333e9da69e9a4d569389af47d26 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Wed, 24 Jul 2019 11:19:13 -0500
Subject: [PATCH 034/644] fixes the bug of giving non-consecutive sim_ids

---
 libensemble/gen_funcs/persistent_aposmm.py | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index c41ec4f6b..6eb4dcbc3 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -275,15 +275,12 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     # phase.
                     x_opt = x_new[1]
                     # Need to figure out what are run_ids.
-                    add_to_local_H(local_H, (x_opt, ), gen_specs, c_flag, local_flag=1, on_cube=True)
                     update_history_optimal(x_opt, local_H,
                             run_order[child_id_to_run_id[child_idx]])
                     print("[Parent]: Child {} has converged, miss you :'(".format(child_idx), flush=True)
                     processes[child_idx].join()
                     print("[Parent]: Child {} has been joined.".format(child_idx), flush=True)
 
-                    # TODO: send a sample point on converging..
-                    # This one still sends the number of points equal to the 
                     send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
                             sim_id_to_child_indices)
                 else:

From 26ea1b54d475dc8b5c67413337b7cd5ab47e7178 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 24 Jul 2019 13:31:57 -0500
Subject: [PATCH 035/644] Using a much older numpy function to accomplish the
 same thing

---
 libensemble/history.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/history.py b/libensemble/history.py
index 6dc4c1100..22f3907e9 100644
--- a/libensemble/history.py
+++ b/libensemble/history.py
@@ -153,7 +153,7 @@ def update_history_x_in(self, gen_worker, O):
             # gen method is building sim_id or adjusting values in existing sim_id rows.
 
             # Ensure there aren't any gaps in the generated sim_id values:
-            assert np.all(np.isin(np.arange(self.index,np.max(O['sim_id'])+1),O['sim_id'])), "The generator function has produced sim_id that are not in order."
+            assert np.all(np.in1d(np.arange(self.index, np.max(O['sim_id'])+1), O['sim_id'])), "The generator function has produced sim_id that are not in order."
 
             num_new = len(np.setdiff1d(O['sim_id'], self.H['sim_id']))
 

From fda88612efc3dbb70fb155ce29e51951dce3b23b Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Thu, 25 Jul 2019 14:54:21 -0500
Subject: [PATCH 036/644] adds back the max_active_runs

---
 libensemble/gen_funcs/persistent_aposmm.py | 130 +++++++++++++++------
 1 file changed, 93 insertions(+), 37 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 6eb4dcbc3..a3384de91 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -210,6 +210,8 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 sim_id_to_child_indices)
 
     tag = None
+    max_active_runs = gen_specs.get('max_active_runs', np.inf)
+    waiting_starting_inds = []
     O = np.empty(0, dtype=gen_specs['out'])  # noqa: E741
     while 1:
 
@@ -281,7 +283,57 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     processes[child_idx].join()
                     print("[Parent]: Child {} has been joined.".format(child_idx), flush=True)
 
-                    send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
+                    if waiting_starting_inds:
+                        print('[Parent]: There was a waiting starting index'
+                                ' and started a run from there.', flush=True)
+                        ind = waiting_starting_inds[0]
+                        waiting_starting_inds = waiting_starting_inds[1:]
+
+                        # {{{ logic duplication(need to get rid of it)
+
+                        p = Process(target=run_local_nlopt, args=(gen_specs,
+                            comm_queue, local_H[ind]['x_on_cube'],
+                            child_can_read_evts[-1],
+                            parent_can_read_from_queue))
+                        processes.append(p)
+                        p.start()
+                        print('[Parent]: Started a child process', flush=True)
+
+                        print('[Parent]: I am waiting', flush=True)
+                        parent_can_read_from_queue.wait()
+                        print('[Parent]: Done waiting.', flush=True)
+
+                        assert np.allclose(comm_queue.get(), local_H[ind]['x_on_cube'])
+
+                        comm_queue.put(local_H[ind][['f', 'grad']])
+                        parent_can_read_from_queue.clear()
+
+                        child_can_read_evts[-1].set()
+                        parent_can_read_from_queue.wait()
+                        print('[Master]: Getting a new x_new.', flush=True)
+
+                        x_new = comm_queue.get()
+
+                        add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
+                        assert np.allclose(local_H[-1]['x_on_cube'], x_new)
+
+                        assert np.allclose(local_H[-1]['x_on_cube'], x_new)
+
+                        run_order[total_runs] = [local_H[-1]['sim_id']]
+                        child_id_to_run_id[len(processes)-1] = total_runs
+                        total_runs += 1
+                        # Need to figure out the child number from the run number.
+
+                        if local_H[-1]['sim_id'] in sim_id_to_child_indices:
+                            sim_id_to_child_indices[local_H[-1]['sim_id']] += (len(processes)-1, )
+                        else:
+                            sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(processes)-1, )
+
+                        send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
+
+                        # }}}
+                    else:
+                        send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
                             sim_id_to_child_indices)
                 else:
                     add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
@@ -310,46 +362,52 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 print('[Parent]: Initing process', flush=True)
 
                 parent_can_read_from_queue.clear()
-                p = Process(target=run_local_nlopt, args=(gen_specs,
-                    comm_queue, local_H[ind]['x_on_cube'],
-                    child_can_read_evts[-1],
-                    parent_can_read_from_queue))
-                processes.append(p)
-                p.start()
-                print('[Parent]: Started a child process', flush=True)
-
-                print('[Parent]: I am waiting', flush=True)
-                parent_can_read_from_queue.wait()
-                print('[Parent]: Done waiting.', flush=True)
 
-                assert np.allclose(comm_queue.get(), local_H[ind]['x_on_cube'])
+                if len([p for p in processes if p.is_alive()]) < max_active_runs:
+                    p = Process(target=run_local_nlopt, args=(gen_specs,
+                        comm_queue, local_H[ind]['x_on_cube'],
+                        child_can_read_evts[-1],
+                        parent_can_read_from_queue))
+                    processes.append(p)
+                    p.start()
+                    print('[Parent]: Started a child process', flush=True)
 
-                comm_queue.put(local_H[ind][['f', 'grad']])
-                parent_can_read_from_queue.clear()
+                    print('[Parent]: I am waiting', flush=True)
+                    parent_can_read_from_queue.wait()
+                    print('[Parent]: Done waiting.', flush=True)
 
-                child_can_read_evts[-1].set()
-                parent_can_read_from_queue.wait()
-                print('[Master]: Getting a new x_new.', flush=True)
+                    assert np.allclose(comm_queue.get(), local_H[ind]['x_on_cube'])
 
-                x_new = comm_queue.get()
+                    comm_queue.put(local_H[ind][['f', 'grad']])
+                    parent_can_read_from_queue.clear()
 
-                add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
-                assert np.allclose(local_H[-1]['x_on_cube'], x_new)
+                    child_can_read_evts[-1].set()
+                    parent_can_read_from_queue.wait()
+                    print('[Master]: Getting a new x_new.', flush=True)
 
-                assert np.allclose(local_H[-1]['x_on_cube'], x_new)
+                    x_new = comm_queue.get()
 
-                run_order[total_runs] = [local_H[-1]['sim_id']]
-                child_id_to_run_id[len(processes)-1] = total_runs
-                total_runs += 1
-                # Need to figure out the child number from the run number.
+                    add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
+                    assert np.allclose(local_H[-1]['x_on_cube'], x_new)
 
-                if local_H[-1]['sim_id'] in sim_id_to_child_indices:
-                    sim_id_to_child_indices[local_H[-1]['sim_id']] += (len(processes)-1, )
-                else:
-                    sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(processes)-1, )
+                    assert np.allclose(local_H[-1]['x_on_cube'], x_new)
 
-                send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
-            if len(starting_inds) == 0:
+                    run_order[total_runs] = [local_H[-1]['sim_id']]
+                    child_id_to_run_id[len(processes)-1] = total_runs
+                    total_runs += 1
+                    # Need to figure out the child number from the run number.
+
+                    if local_H[-1]['sim_id'] in sim_id_to_child_indices:
+                        sim_id_to_child_indices[local_H[-1]['sim_id']] += (len(processes)-1, )
+                    else:
+                        sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(processes)-1, )
+
+                    send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
+                else:
+                    print('[Parent]: Not exceeding max active runs, putting it'
+                                ' in our stash', flush=True)
+                    waiting_starting_inds.append(ind)
+            if len(starting_inds) == 0 and len(waiting_starting_inds) == 0:
                 send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
                         sim_id_to_child_indices)
         print('[Parent]: Heading to next iteration', flush=True)
@@ -365,10 +423,8 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     " killing all the children.")
 
     #TODO: Figure out what do we need to do from here.
-    1/0
-    print('This line should not appear', flush=True)
 
-    return O, persis_info, tag
+    return local_H, persis_info, tag
 
 
 def callback_function(x, grad, comm_queue, child_can_read, parent_can_read, gen_specs):
@@ -1075,10 +1131,10 @@ def initialize_APOSMM(H, gen_specs, libE_info):
                       ('sim_id', int),
                       ('paused', bool),
                       ('returned', bool),
-                      ('pt_id', int), # Identify the same point evaluated by different sim_f's or components
+                      ('pt_id', int),  # Identify the same point evaluated by different sim_f's or components
                       ]
 
-    local_H = np.empty(0,dtype=local_H_fields);
+    local_H = np.empty(0, dtype=local_H_fields)
 
     return n, n_s, c_flag, rk_c, mu, nu, total_runs, comm, local_H
 

From dad7f5274ed2bcb4111d721379d485b2469a3250 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Thu, 25 Jul 2019 14:55:03 -0500
Subject: [PATCH 037/644] enforces max active runs through gen_specs

---
 .../regression_tests/test_6-hump_camel_persistent_aposmm.py      | 1 +
 1 file changed, 1 insertion(+)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index 9c3b7313b..cafb39620 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -42,6 +42,7 @@
              'initial_sample_size': 50,
              'localopt_method': 'LD_MMA',
              'xtol_rel': 1e-3,
+             'max_active_runs': 1,
              'lb': np.array([-3, -2]),
              'ub': np.array([3, 2])}
 

From 52d8aa3eccc3ca5d31d43fc0ccca7350d8126c17 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Sun, 28 Jul 2019 19:07:35 -0500
Subject: [PATCH 038/644] preliminary work on porting the local optimization
 techniques to TAO/SciPy

---
 libensemble/gen_funcs/persistent_aposmm.py | 167 ++++++++++++++++++++-
 1 file changed, 162 insertions(+), 5 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index a3384de91..32494a9a5 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -203,7 +203,18 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     child_id_to_run_id = {}
     run_order = {}
 
-    # We just sampled a single point.
+    if gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA',
+            'LN_NELDERMEAD', 'LD_MMA']:
+        run_local_opt = run_local_nlopt
+        pass
+    elif gen_specs['localopt_method'] in ['pounders']:
+        run_local_opt = run_local_tao
+    elif gen_specs['localopt_method'] in ['scipy_COBYLA']:
+        run_local_opt = run_local_scipy
+        pass
+    else:
+        raise NotImplementedError("Unknown local optimization method "
+                "'{}'.".format(gen_specs['localopt_method']))
 
     for _ in range(gen_specs['initial_sample_size']):
         send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
@@ -364,7 +375,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 parent_can_read_from_queue.clear()
 
                 if len([p for p in processes if p.is_alive()]) < max_active_runs:
-                    p = Process(target=run_local_nlopt, args=(gen_specs,
+                    p = Process(target=run_local_opt, args=(gen_specs,
                         comm_queue, local_H[ind]['x_on_cube'],
                         child_can_read_evts[-1],
                         parent_can_read_from_queue))
@@ -412,6 +423,9 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                         sim_id_to_child_indices)
         print('[Parent]: Heading to next iteration', flush=True)
 
+    print('[Parent]: The optimal points are:\n',
+            local_H[np.where(local_H['local_min'])]['x'], flush=True)
+
     comm_queue.close()
     comm_queue.join_thread()
 
@@ -427,7 +441,9 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     return local_H, persis_info, tag
 
 
-def callback_function(x, grad, comm_queue, child_can_read, parent_can_read, gen_specs):
+# {{{ NLOPT for local opt..
+
+def nlopt_callback_function(x, grad, comm_queue, child_can_read, parent_can_read, gen_specs):
     comm_queue.put(x)
     print('[Child]: Parent should no longer wait.', flush=True)
     parent_can_read.set()
@@ -442,7 +458,7 @@ def callback_function(x, grad, comm_queue, child_can_read, parent_can_read, gen_
     return result[0]
 
 
-def run_local_nlopt(gen_specs, comm_queue, x0, child_can_read,
+def run_local_nlopt(gen_specs, comm_queue, x0, f0, child_can_read,
         parent_can_read):
     print('[Child]: Started local opt at {}.'.format(x0), flush=True)
     n = len(gen_specs['ub'])
@@ -466,7 +482,7 @@ def run_local_nlopt(gen_specs, comm_queue, x0, child_can_read,
     # FIXME: Setting max evaluations = 100
     opt.set_maxeval(100)
 
-    opt.set_min_objective(lambda x, grad: callback_function(x, grad,
+    opt.set_min_objective(lambda x, grad: nlopt_callback_function(x, grad,
         comm_queue, child_can_read, parent_can_read, gen_specs))
 
     if 'xtol_rel' in gen_specs:
@@ -485,6 +501,147 @@ def run_local_nlopt(gen_specs, comm_queue, x0, child_can_read,
     comm_queue.put(('Converged', x_opt))
     parent_can_read.set()
 
+# }}}
+
+
+# {{{ SciPy optimization
+
+def scipy_callback_function(x, comm_queue, child_can_read, parent_can_read, gen_specs):
+    comm_queue.put(x)
+    print('[Child]: Parent should no longer wait.', flush=True)
+    parent_can_read.set()
+    print('[Child]: I have started waiting', flush=True)
+    child_can_read.wait()
+    print('[Child]: Wohooo.. I am free folks', flush=True)
+    result, = comm_queue.get()
+    child_can_read.clear()
+    return result
+
+
+def run_local_scipy_opt(gen_specs, comm_queue, x0, f0, child_can_read,
+        parent_can_read):
+
+    # Construct the bounds in the form of constraints
+    cons = []
+    for factor in range(len(x0)):
+        lo = {'type': 'ineq',
+              'fun': lambda x, lb=gen_specs['lb'][factor], i=factor: x[i]-lb}
+        up = {'type': 'ineq',
+              'fun': lambda x, ub=gen_specs['ub'][factor], i=factor: ub-x[i]}
+        cons.append(lo)
+        cons.append(up)
+
+    method = gen_specs['localopt_method'][6:]
+    print('[Child]: Started my optimization', flush=True)
+    res = scipy_optimize.minimize(lambda x: scipy_callback_function(x,
+        comm_queue, child_can_read, parent_can_read, gen_specs), x0,
+        method=method, options={'maxiter': 100, 'tol': gen_specs['tol']})
+
+    if res['status'] == 2:  # SciPy code for exhausting budget of evaluations, so not at a minimum
+        exit_code = 0
+    else:
+        if method == 'COBYLA':
+            assert res['status'] == 1, "Unknown status for COBYLA"
+            exit_code = 1
+
+    x_opt = res['x']
+
+    # FIXME: Need to do something with the exit codes.
+
+    print('[Child]: I have converged.', flush=True)
+    comm_queue.put(('Converged', x_opt))
+    parent_can_read.set()
+
+# }}}
+
+
+# {{{ TAO routines for local opt
+
+
+def tao_callback_function(tao, x, f, comm_queue, child_can_read, parent_can_read, gen_specs):
+    comm_queue.put(x)
+    print('[Child]: Parent should no longer wait.', flush=True)
+    parent_can_read.set()
+    print('[Child]: I have started waiting', flush=True)
+    child_can_read.wait()
+    print('[Child]: Wohooo.. I am free folks', flush=True)
+    result = comm_queue.get()
+    child_can_read.clear()
+    f.array[:] = result[0]
+    return f
+
+
+def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read,
+        parent_can_read):
+    assert isinstance(x0, np.array)
+
+    tao_comm = MPI.COMM_SELF
+    n, = x0.shape
+    m, = f0.shape
+
+    # Create starting point, bounds, and tao object
+    x = PETSc.Vec().create(tao_comm)
+    x.setSizes(n)
+    x.setFromOptions()
+    x.array = x0
+    lb = x.duplicate()
+    ub = x.duplicate()
+    lb.array = 0*np.ones(n)
+    ub.array = 1*np.ones(n)
+    tao = PETSc.TAO().create(tao_comm)
+    tao.setType(gen_specs['localopt_method'])
+
+    f = PETSc.Vec().create(tao_comm)
+    f.setSizes(m)
+    f.setFromOptions()
+
+    delta_0 = gen_specs['dist_to_bound_multiple']*np.min([np.min(ub.array-x.array), np.min(x.array-lb.array)])
+
+    PETSc.Options().setValue('-tao_pounders_delta', str(delta_0))
+    # PETSc.Options().setValue('-pounders_subsolver_tao_type','bqpip')
+
+    tao.setResidual(lambda tao, x, f: tao_callback_function(tao, x, f,
+        comm_queue, child_can_read, parent_can_read, gen_specs), f)
+
+    # Set everything for tao before solving
+    # FIXME: Hard-coding 100 as the max funcs as couldn't find any other
+    # sensible value.
+    PETSc.Options().setValue('-tao_max_funcs', '100')
+    tao.setFromOptions()
+    tao.setVariableBounds((lb, ub))
+    # tao.setObjectiveTolerances(fatol=gen_specs['fatol'], frtol=gen_specs['frtol'])
+    # tao.setGradientTolerances(grtol=gen_specs['grtol'], gatol=gen_specs['gatol'])
+    tao.setTolerances(grtol=gen_specs['grtol'], gatol=gen_specs['gatol'])
+    tao.setInitial(x)
+
+    print('[Child]: Started my optimization', flush=True)
+    tao.solve(x)
+
+    x_opt = tao.getSolution().getArray()
+    exit_code = tao.getConvergedReason()
+    # print(exit_code)
+    # print(tao.view())
+    # print(x_opt)
+
+    # if gen_specs['localopt_method'] == 'pounders':
+    f.destroy()
+    # elif gen_specs['localopt_method'] == 'blmvm':
+    #     g.destroy()
+
+    lb.destroy()
+    ub.destroy()
+    x.destroy()
+    tao.destroy()
+
+    #FIXME: Do we need to do something of the final 'x_opt'?
+    print('[Child]: I have converged.', flush=True)
+    comm_queue.put(('Converged', x_opt))
+    parent_can_read.set()
+
+    # FIXME: What do we do about the exit_code?
+
+# }}}
+
 
 def update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in):
 

From c23852ea3ea0d619363e90d756ea101f4fc3e114 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Mon, 29 Jul 2019 09:58:41 -0500
Subject: [PATCH 039/644] generalizes the passing of f and grad_f

---
 libensemble/gen_funcs/persistent_aposmm.py | 46 ++++++++++++++--------
 1 file changed, 30 insertions(+), 16 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 32494a9a5..5d87f5bf2 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -203,19 +203,35 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     child_id_to_run_id = {}
     run_order = {}
 
+    # {{{ setting the local optimization method
+
     if gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA',
             'LN_NELDERMEAD', 'LD_MMA']:
         run_local_opt = run_local_nlopt
-        pass
     elif gen_specs['localopt_method'] in ['pounders']:
         run_local_opt = run_local_tao
     elif gen_specs['localopt_method'] in ['scipy_COBYLA']:
-        run_local_opt = run_local_scipy
-        pass
+        run_local_opt = run_local_scipy_opt
+    else:
+        raise NotImplementedError("Unknown local optimization method "
+                "'{}'.".format(gen_specs['localopt_method']))
+
+    # }}}
+
+    # {{{ setting the data needed by the local optimization method
+
+    if gen_specs['localopt_method'] in ['LD_MMA']:
+        fields_to_pass = ['f', 'grad']
+    elif gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA',
+            'LN_NELDERMEAD', 'pounders', 'scipy_COBYLA']:
+        fields_to_pass = ['f']
     else:
         raise NotImplementedError("Unknown local optimization method "
                 "'{}'.".format(gen_specs['localopt_method']))
 
+    # }}}
+
+
     for _ in range(gen_specs['initial_sample_size']):
         send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
                 sim_id_to_child_indices)
@@ -230,7 +246,14 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         tag, Work, calc_in = get_mgr_worker_msg(comm)
 
         if calc_in:
-            (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in
+            if fields_to_pass == ['f', 'grad']:
+                (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in
+                data_to_give_processes = (f_x_recv, grad_f_x_recv)
+            else:
+                assert(fields_to_pass == ['f'])
+                (x_recv, f_x_recv, sim_id_recv),  = calc_in
+                data_to_give_processes = (f_x_recv, )
+
             print(23*"-", "Received f({})".format(x_recv), 24*"-",
                     flush=True)
             if tuple(x_recv) in received_values:
@@ -242,15 +265,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 continue
 
             received_values.add(tuple(x_recv))
-        # JL: Kaushik, I have concerns about the above approach for processing calc_in
-        # 1. I'm not sure that the contents of calc_in will always be in the order, x, f, grad, sim_id.
-        # 2. Note that grad might not be available for some objectives.
-        # Perhaps it's better to use something like
-        # x_recv = calc_in['x']
-        # f_x_recv = calc_in['f']
-        # sim_id_recv = calc_in['sim_id']
-        # if 'grad' in calc_in.dtype.names:
-        #     grad_f_x_recv = calc_in['grad']
 
         if tag in [STOP_TAG, PERSIS_STOP]:
 
@@ -271,7 +285,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
             for child_idx in sim_id_to_child_indices[sim_id_recv]:
                 print('[Parent]:Giving f = {} it to the'
                     ' child_idx: {}.'.format(f_x_recv, child_idx), flush=True)
-                comm_queue.put((f_x_recv, grad_f_x_recv))
+                comm_queue.put(data_to_give_processes)
 
                 parent_can_read_from_queue.clear()
 
@@ -316,7 +330,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                         assert np.allclose(comm_queue.get(), local_H[ind]['x_on_cube'])
 
-                        comm_queue.put(local_H[ind][['f', 'grad']])
+                        comm_queue.put(local_H[ind][[*fields_to_pass]])
                         parent_can_read_from_queue.clear()
 
                         child_can_read_evts[-1].set()
@@ -389,7 +403,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                     assert np.allclose(comm_queue.get(), local_H[ind]['x_on_cube'])
 
-                    comm_queue.put(local_H[ind][['f', 'grad']])
+                    comm_queue.put(local_H[ind][[*fields_to_pass]])
                     parent_can_read_from_queue.clear()
 
                     child_can_read_evts[-1].set()

From 94c0ef2580efceb3c78a02075ab419ce3b3e43fb Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Mon, 29 Jul 2019 10:10:20 -0500
Subject: [PATCH 040/644] makes var names more intuitive

---
 libensemble/gen_funcs/persistent_aposmm.py | 24 +++++++++++++---------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 5d87f5bf2..3858670a3 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -316,7 +316,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                         # {{{ logic duplication(need to get rid of it)
 
-                        p = Process(target=run_local_nlopt, args=(gen_specs,
+                        p = Process(target=run_local_opt, args=(gen_specs,
                             comm_queue, local_H[ind]['x_on_cube'],
                             child_can_read_evts[-1],
                             parent_can_read_from_queue))
@@ -464,12 +464,17 @@ def nlopt_callback_function(x, grad, comm_queue, child_can_read, parent_can_read
     print('[Child]: I have started waiting', flush=True)
     child_can_read.wait()
     print('[Child]: Wohooo.. I am free folks', flush=True)
-    result = comm_queue.get()
-    child_can_read.clear()
     if gen_specs['localopt_method'] in ['LD_MMA']:
-        grad[:] = result[1]
+        f_recv, grad_recv = comm_queue.get()
+        grad[:] = grad_recv
+    else:
+        assert gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA',
+                'LN_COBYLA', 'LN_NELDERMEAD', 'LD_MMA']
+        f_recv, = comm_queue.get()
 
-    return result[0]
+    child_can_read.clear()
+
+    return f_recv
 
 
 def run_local_nlopt(gen_specs, comm_queue, x0, f0, child_can_read,
@@ -527,9 +532,9 @@ def scipy_callback_function(x, comm_queue, child_can_read, parent_can_read, gen_
     print('[Child]: I have started waiting', flush=True)
     child_can_read.wait()
     print('[Child]: Wohooo.. I am free folks', flush=True)
-    result, = comm_queue.get()
+    f_x_recv, = comm_queue.get()
     child_can_read.clear()
-    return result
+    return f_x_recv
 
 
 def run_local_scipy_opt(gen_specs, comm_queue, x0, f0, child_can_read,
@@ -571,7 +576,6 @@ def run_local_scipy_opt(gen_specs, comm_queue, x0, f0, child_can_read,
 
 # {{{ TAO routines for local opt
 
-
 def tao_callback_function(tao, x, f, comm_queue, child_can_read, parent_can_read, gen_specs):
     comm_queue.put(x)
     print('[Child]: Parent should no longer wait.', flush=True)
@@ -579,9 +583,9 @@ def tao_callback_function(tao, x, f, comm_queue, child_can_read, parent_can_read
     print('[Child]: I have started waiting', flush=True)
     child_can_read.wait()
     print('[Child]: Wohooo.. I am free folks', flush=True)
-    result = comm_queue.get()
+    f_recv,  = comm_queue.get()
     child_can_read.clear()
-    f.array[:] = result[0]
+    f.array[:] = f_recv
     return f
 
 

From 64b8a3dd9153de6d7536bdb0738bd3a91faaa4ea Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Mon, 29 Jul 2019 10:42:31 -0500
Subject: [PATCH 041/644] need to fix parent hanging

---
 libensemble/gen_funcs/persistent_aposmm.py | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 3858670a3..73d7fe68a 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -251,7 +251,12 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 data_to_give_processes = (f_x_recv, grad_f_x_recv)
             else:
                 assert(fields_to_pass == ['f'])
-                (x_recv, f_x_recv, sim_id_recv),  = calc_in
+                if len(calc_in[0]) == 3:
+                    (x_recv, f_x_recv, sim_id_recv),  = calc_in
+                else:
+                    # FIXME: *BIG BIG!*, even if we are passing grad_f even
+                    # though we are not using it.
+                    (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in
                 data_to_give_processes = (f_x_recv, )
 
             print(23*"-", "Received f({})".format(x_recv), 24*"-",
@@ -318,6 +323,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                         p = Process(target=run_local_opt, args=(gen_specs,
                             comm_queue, local_H[ind]['x_on_cube'],
+                            local_H[ind]['f'],
                             child_can_read_evts[-1],
                             parent_can_read_from_queue))
                         processes.append(p)
@@ -391,6 +397,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 if len([p for p in processes if p.is_alive()]) < max_active_runs:
                     p = Process(target=run_local_opt, args=(gen_specs,
                         comm_queue, local_H[ind]['x_on_cube'],
+                        local_H[ind]['f'],
                         child_can_read_evts[-1],
                         parent_can_read_from_queue))
                     processes.append(p)
@@ -591,11 +598,14 @@ def tao_callback_function(tao, x, f, comm_queue, child_can_read, parent_can_read
 
 def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read,
         parent_can_read):
-    assert isinstance(x0, np.array)
+    assert isinstance(x0, np.ndarray)
 
     tao_comm = MPI.COMM_SELF
     n, = x0.shape
-    m, = f0.shape
+    if f0.shape == ():
+        m = 1
+    else:
+        m, = f0.shape
 
     # Create starting point, bounds, and tao object
     x = PETSc.Vec().create(tao_comm)

From ef5c1bc01365ae2b4803076eb294ab77e1c7a2ea Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Mon, 29 Jul 2019 11:14:32 -0500
Subject: [PATCH 042/644] pounders is running

---
 libensemble/gen_funcs/persistent_aposmm.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 73d7fe68a..d54c0c5e2 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -408,7 +408,9 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     parent_can_read_from_queue.wait()
                     print('[Parent]: Done waiting.', flush=True)
 
+                    print('[Parent]: Starting with assertion checking', flush=True)
                     assert np.allclose(comm_queue.get(), local_H[ind]['x_on_cube'])
+                    print('[Parent]: Assertion holds.', flush=True)
 
                     comm_queue.put(local_H[ind][[*fields_to_pass]])
                     parent_can_read_from_queue.clear()
@@ -584,7 +586,8 @@ def run_local_scipy_opt(gen_specs, comm_queue, x0, f0, child_can_read,
 # {{{ TAO routines for local opt
 
 def tao_callback_function(tao, x, f, comm_queue, child_can_read, parent_can_read, gen_specs):
-    comm_queue.put(x)
+    comm_queue.put(x.array)
+    print('[Child]: I just put x_on_cube =', x.array, flush=True)
     print('[Child]: Parent should no longer wait.', flush=True)
     parent_can_read.set()
     print('[Child]: I have started waiting', flush=True)

From c3cf881d562a243ac6952d96af76f387844f7696 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Mon, 29 Jul 2019 11:45:22 -0500
Subject: [PATCH 043/644] removes the checking of receiving duplicate value as
 it is being checked at the allocation stage

---
 libensemble/gen_funcs/persistent_aposmm.py | 14 +++-----------
 1 file changed, 3 insertions(+), 11 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index d54c0c5e2..01dcfcaeb 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -197,8 +197,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
     n, n_s, c_flag, rk_const, mu, nu, total_runs, comm, local_H = initialize_APOSMM(H, gen_specs, libE_info)
 
-    received_values = set()
-
     sim_id_to_child_indices = {}
     child_id_to_run_id = {}
     run_order = {}
@@ -261,15 +259,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
             print(23*"-", "Received f({})".format(x_recv), 24*"-",
                     flush=True)
-            if tuple(x_recv) in received_values:
-                #FIXME:: This should never be the case.
-                print("DANGER!! Re-received a value(SimID = {}) ignoring it for now, but"
-                        " need to fix it in manager, I guess?".format(sim_id_recv), flush=True)
-                send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
-                        sim_id_to_child_indices)
-                continue
-
-            received_values.add(tuple(x_recv))
 
         if tag in [STOP_TAG, PERSIS_STOP]:
 
@@ -336,6 +325,9 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                         assert np.allclose(comm_queue.get(), local_H[ind]['x_on_cube'])
 
+                        print('[Parent]: Assertion holds.', flush=True)
+
+
                         comm_queue.put(local_H[ind][[*fields_to_pass]])
                         parent_can_read_from_queue.clear()
 

From a6daa563eea6a9f6350e35b8a1aed55e0b485355 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Mon, 29 Jul 2019 17:19:46 -0500
Subject: [PATCH 044/644] adds the test file for pounders

---
 .../test_6-hump_camel_persistent_aposmm.py       | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index cafb39620..03dc303ed 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -34,19 +34,24 @@
              'in': ['x'],
              'out': [('f', float), ('grad', float, n)]}
 
-gen_out = [('x', float, n), ('x_on_cube', float, n), ('sim_id', int)]
+gen_out = [('x', float, n), ('x_on_cube', float, n), ('sim_id', int),
+        ('local_min', bool)]
 gen_specs = {'gen_f': gen_f,
              'in': [],
              'out': gen_out,
              'batch_mode': True,
              'initial_sample_size': 50,
-             'localopt_method': 'LD_MMA',
+             'localopt_method': 'pounders',
              'xtol_rel': 1e-3,
-             'max_active_runs': 1,
+             'local_min': True,
+             'dist_to_bound_multiple': 0.5,
+             'grtol': 1e-4,
+             'gatol': 1e-4,
+             'tol': 1e-5,
              'lb': np.array([-3, -2]),
              'ub': np.array([3, 2])}
 
-alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back',bool)]}
+alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)]}
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
@@ -57,4 +62,5 @@
                             alloc_specs, libE_specs)
 
 if is_master:
-    save_libE_output(H, persis_info, __file__, nworkers)
+    print('[Manager]:', H[np.where(H['local_min'])]['x'])
+    # save_libE_output(H, persis_info, __file__, nworkers)

From b0332e24ca42d8f8f0ba8f7be53a39f496fa035e Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Mon, 29 Jul 2019 21:58:10 -0500
Subject: [PATCH 045/644] handles a major bug in max_active runs

---
 libensemble/gen_funcs/persistent_aposmm.py    | 23 ++++++++++++-------
 .../test_6-hump_camel_persistent_aposmm.py    | 12 +++++++---
 2 files changed, 24 insertions(+), 11 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 01dcfcaeb..2e3fb1c7d 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -229,7 +229,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
     # }}}
 
-
     for _ in range(gen_specs['initial_sample_size']):
         send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
                 sim_id_to_child_indices)
@@ -257,7 +256,8 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in
                 data_to_give_processes = (f_x_recv, )
 
-            print(23*"-", "Received f({})".format(x_recv), 24*"-",
+            print(23*"-", "Received f({})(SimID: {})".format(x_recv,
+                sim_id_recv), 24*"-",
                     flush=True)
 
         if tag in [STOP_TAG, PERSIS_STOP]:
@@ -308,6 +308,12 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                         ind = waiting_starting_inds[0]
                         waiting_starting_inds = waiting_starting_inds[1:]
 
+                        child_can_read_evts.append(Event())
+
+                        print('[Parent]: Initing process', flush=True)
+
+                        parent_can_read_from_queue.clear()
+
                         # {{{ logic duplication(need to get rid of it)
 
                         p = Process(target=run_local_opt, args=(gen_specs,
@@ -327,7 +333,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                         print('[Parent]: Assertion holds.', flush=True)
 
-
                         comm_queue.put(local_H[ind][[*fields_to_pass]])
                         parent_can_read_from_queue.clear()
 
@@ -378,20 +383,22 @@ def aposmm(H, persis_info, gen_specs, libE_info):
             starting_inds = decide_where_to_start_localopt(local_H, n, n_s, rk_const, mu, nu)
 
             for ind in starting_inds:
+
                 local_H['started_run'][ind] = 1
 
-                child_can_read_evts.append(Event())
+                if len([p for p in processes if p.is_alive()]) < max_active_runs:
 
-                print('[Parent]: Initing process', flush=True)
+                    child_can_read_evts.append(Event())
 
-                parent_can_read_from_queue.clear()
+                    print('[Parent]: Initing process', flush=True)
+
+                    parent_can_read_from_queue.clear()
 
-                if len([p for p in processes if p.is_alive()]) < max_active_runs:
                     p = Process(target=run_local_opt, args=(gen_specs,
                         comm_queue, local_H[ind]['x_on_cube'],
                         local_H[ind]['f'],
                         child_can_read_evts[-1],
-                        parent_can_read_from_queue))
+                        parent_can_read_from_queue, len(processes)))
                     processes.append(p)
                     p.start()
                     print('[Parent]: Started a child process', flush=True)
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index 03dc303ed..f42f5c9f8 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -19,10 +19,12 @@
 
 # Import libEnsemble items for this test
 from libensemble.libE import libE
+from math import gamma, pi, sqrt
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
 from libensemble.alloc_funcs.start_only_persistent import only_persistent_gens as alloc_f
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
@@ -40,11 +42,15 @@
              'in': [],
              'out': gen_out,
              'batch_mode': True,
-             'initial_sample_size': 50,
-             'localopt_method': 'pounders',
+             'initial_sample_size': 100,
+             'sample_points': np.round(minima, 1),
+             'localopt_method': 'LD_MMA',
+             'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
              'xtol_rel': 1e-3,
+             'num_active_gens': 1,
              'local_min': True,
              'dist_to_bound_multiple': 0.5,
+             'max_active_runs': 6,
              'grtol': 1e-4,
              'gatol': 1e-4,
              'tol': 1e-5,
@@ -55,7 +61,7 @@
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
-exit_criteria = {'sim_max': 400}
+exit_criteria = {'sim_max': 1000}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,

From d378f8d8485fc3eb43a5184a9751a7fff5aec0f6 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Mon, 29 Jul 2019 22:07:22 -0500
Subject: [PATCH 046/644] cleans up extra arg to the local opt

---
 libensemble/gen_funcs/persistent_aposmm.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 2e3fb1c7d..b3f115595 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -398,7 +398,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                         comm_queue, local_H[ind]['x_on_cube'],
                         local_H[ind]['f'],
                         child_can_read_evts[-1],
-                        parent_can_read_from_queue, len(processes)))
+                        parent_can_read_from_queue))
                     processes.append(p)
                     p.start()
                     print('[Parent]: Started a child process', flush=True)

From 091ee73fdad7c53b739d6b9909dd8e2e84257241 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Tue, 30 Jul 2019 09:03:11 -0500
Subject: [PATCH 047/644] comments debug statements

---
 libensemble/gen_funcs/persistent_aposmm.py    | 101 +++++++++---------
 .../test_6-hump_camel_persistent_aposmm.py    |   5 +
 2 files changed, 57 insertions(+), 49 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index b3f115595..7262688ee 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -186,6 +186,9 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     persis_info['old_runs']: Sequence of indices of points in finished runs
 
     """
+    np.random.seed(10)
+
+
     # {{{ multiprocessing initialization
 
     child_can_read_evts = []
@@ -256,13 +259,13 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in
                 data_to_give_processes = (f_x_recv, )
 
-            print(23*"-", "Received f({})(SimID: {})".format(x_recv,
-                sim_id_recv), 24*"-",
-                    flush=True)
+            # print(23*"-", "Received f({})(SimID: {})".format(x_recv,
+            #     sim_id_recv), 24*"-",
+            #         flush=True)
 
         if tag in [STOP_TAG, PERSIS_STOP]:
 
-            print('[Parent]: Received a stop tag, killing all children.', flush=True)
+            # print('[Parent]: Received a stop tag, killing all children.', flush=True)
             # FIXME: If there is any indication that all child processes are
             # done with their work, we can do this a bit more cleanly i.e.
             # first join and check if they are still alive, only then kill.
@@ -277,19 +280,19 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
         if sim_id_to_child_indices.get(sim_id_recv):
             for child_idx in sim_id_to_child_indices[sim_id_recv]:
-                print('[Parent]:Giving f = {} it to the'
-                    ' child_idx: {}.'.format(f_x_recv, child_idx), flush=True)
+                # print('[Parent]:Giving f = {} it to the'
+                #     ' child_idx: {}.'.format(f_x_recv, child_idx), flush=True)
                 comm_queue.put(data_to_give_processes)
 
                 parent_can_read_from_queue.clear()
 
                 child_can_read_evts[child_idx].set()
-                print('[Parent]: I am waiting for child idx {}'.format(child_idx), flush=True)
+                # print('[Parent]: I am waiting for child idx {}'.format(child_idx), flush=True)
                 parent_can_read_from_queue.wait()
-                print('[Parent]: Wohoo I am free again', flush=True)
+                # print('[Parent]: Wohoo I am free again', flush=True)
 
                 x_new = comm_queue.get()
-                print('[Parent]: The child returned {}.'.format(x_new), flush=True)
+                # print('[Parent]: The child returned {}.'.format(x_new), flush=True)
                 if isinstance(x_new, tuple):
                     # FIXME: [KK]: This is ugly and every bit of it happens in
                     # my mind, this should be cleaned up duing the cleanup
@@ -298,19 +301,19 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     # Need to figure out what are run_ids.
                     update_history_optimal(x_opt, local_H,
                             run_order[child_id_to_run_id[child_idx]])
-                    print("[Parent]: Child {} has converged, miss you :'(".format(child_idx), flush=True)
+                    # print("[Parent]: Child {} has converged, miss you :'(".format(child_idx), flush=True)
                     processes[child_idx].join()
-                    print("[Parent]: Child {} has been joined.".format(child_idx), flush=True)
+                    # print("[Parent]: Child {} has been joined.".format(child_idx), flush=True)
 
                     if waiting_starting_inds:
-                        print('[Parent]: There was a waiting starting index'
-                                ' and started a run from there.', flush=True)
+                        # print('[Parent]: There was a waiting starting index'
+                        #        ' and started a run from there.', flush=True)
                         ind = waiting_starting_inds[0]
                         waiting_starting_inds = waiting_starting_inds[1:]
 
                         child_can_read_evts.append(Event())
 
-                        print('[Parent]: Initing process', flush=True)
+                        # print('[Parent]: Initing process', flush=True)
 
                         parent_can_read_from_queue.clear()
 
@@ -323,22 +326,22 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                             parent_can_read_from_queue))
                         processes.append(p)
                         p.start()
-                        print('[Parent]: Started a child process', flush=True)
+                        # print('[Parent]: Started a child process', flush=True)
 
-                        print('[Parent]: I am waiting', flush=True)
+                        # print('[Parent]: I am waiting', flush=True)
                         parent_can_read_from_queue.wait()
-                        print('[Parent]: Done waiting.', flush=True)
+                        # print('[Parent]: Done waiting.', flush=True)
 
                         assert np.allclose(comm_queue.get(), local_H[ind]['x_on_cube'])
 
-                        print('[Parent]: Assertion holds.', flush=True)
+                        # print('[Parent]: Assertion holds.', flush=True)
 
                         comm_queue.put(local_H[ind][[*fields_to_pass]])
                         parent_can_read_from_queue.clear()
 
                         child_can_read_evts[-1].set()
                         parent_can_read_from_queue.wait()
-                        print('[Master]: Getting a new x_new.', flush=True)
+                        # print('[Master]: Getting a new x_new.', flush=True)
 
                         x_new = comm_queue.get()
 
@@ -374,8 +377,8 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     else:
                         sim_id_to_child_indices[local_H[-1]['sim_id']] = (child_idx, )
         else:
-            print('[Parent]: Did not find any local opt run to associate with.',
-                    flush=True)
+            # print('[Parent]: Did not find any local opt run to associate with.',
+            #         flush=True)
             if n_s < gen_specs['initial_sample_size']:
                 continue
             n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
@@ -390,7 +393,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                     child_can_read_evts.append(Event())
 
-                    print('[Parent]: Initing process', flush=True)
+                    # print('[Parent]: Initing process', flush=True)
 
                     parent_can_read_from_queue.clear()
 
@@ -401,22 +404,22 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                         parent_can_read_from_queue))
                     processes.append(p)
                     p.start()
-                    print('[Parent]: Started a child process', flush=True)
+                    # print('[Parent]: Started a child process', flush=True)
 
-                    print('[Parent]: I am waiting', flush=True)
+                    # print('[Parent]: I am waiting', flush=True)
                     parent_can_read_from_queue.wait()
-                    print('[Parent]: Done waiting.', flush=True)
+                    # print('[Parent]: Done waiting.', flush=True)
 
-                    print('[Parent]: Starting with assertion checking', flush=True)
+                    # print('[Parent]: Starting with assertion checking', flush=True)
                     assert np.allclose(comm_queue.get(), local_H[ind]['x_on_cube'])
-                    print('[Parent]: Assertion holds.', flush=True)
+                    # print('[Parent]: Assertion holds.', flush=True)
 
                     comm_queue.put(local_H[ind][[*fields_to_pass]])
                     parent_can_read_from_queue.clear()
 
                     child_can_read_evts[-1].set()
                     parent_can_read_from_queue.wait()
-                    print('[Master]: Getting a new x_new.', flush=True)
+                    # print('[Master]: Getting a new x_new.', flush=True)
 
                     x_new = comm_queue.get()
 
@@ -437,13 +440,13 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                     send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
                 else:
-                    print('[Parent]: Not exceeding max active runs, putting it'
-                                ' in our stash', flush=True)
+                    # print('[Parent]: Not exceeding max active runs, putting it'
+                    #             ' in our stash', flush=True)
                     waiting_starting_inds.append(ind)
             if len(starting_inds) == 0 and len(waiting_starting_inds) == 0:
                 send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
                         sim_id_to_child_indices)
-        print('[Parent]: Heading to next iteration', flush=True)
+        # print('[Parent]: Heading to next iteration', flush=True)
 
     print('[Parent]: The optimal points are:\n',
             local_H[np.where(local_H['local_min'])]['x'], flush=True)
@@ -451,7 +454,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     comm_queue.close()
     comm_queue.join_thread()
 
-    print('Done with everything', flush=True)
+    # print('Done with everything', flush=True)
 
     for p in processes:
         if p.is_alive():
@@ -467,11 +470,11 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
 def nlopt_callback_function(x, grad, comm_queue, child_can_read, parent_can_read, gen_specs):
     comm_queue.put(x)
-    print('[Child]: Parent should no longer wait.', flush=True)
+    # print('[Child]: Parent should no longer wait.', flush=True)
     parent_can_read.set()
-    print('[Child]: I have started waiting', flush=True)
+    # print('[Child]: I have started waiting', flush=True)
     child_can_read.wait()
-    print('[Child]: Wohooo.. I am free folks', flush=True)
+    # print('[Child]: Wohooo.. I am free folks', flush=True)
     if gen_specs['localopt_method'] in ['LD_MMA']:
         f_recv, grad_recv = comm_queue.get()
         grad[:] = grad_recv
@@ -487,7 +490,7 @@ def nlopt_callback_function(x, grad, comm_queue, child_can_read, parent_can_read
 
 def run_local_nlopt(gen_specs, comm_queue, x0, f0, child_can_read,
         parent_can_read):
-    print('[Child]: Started local opt at {}.'.format(x0), flush=True)
+    # print('[Child]: Started local opt at {}.'.format(x0), flush=True)
     n = len(gen_specs['ub'])
 
     opt = nlopt.opt(getattr(nlopt, gen_specs['localopt_method']), n)
@@ -522,9 +525,9 @@ def run_local_nlopt(gen_specs, comm_queue, x0, f0, child_can_read,
         opt.set_ftol_abs(gen_specs['ftol_abs'])
 
     #FIXME: Do we need to do something of the final 'x_opt'?
-    print('[Child]: Started my optimization', flush=True)
+    # print('[Child]: Started my optimization', flush=True)
     x_opt = opt.optimize(x0)
-    print('[Child]: I have converged.', flush=True)
+    # print('[Child]: I have converged.', flush=True)
     comm_queue.put(('Converged', x_opt))
     parent_can_read.set()
 
@@ -535,11 +538,11 @@ def run_local_nlopt(gen_specs, comm_queue, x0, f0, child_can_read,
 
 def scipy_callback_function(x, comm_queue, child_can_read, parent_can_read, gen_specs):
     comm_queue.put(x)
-    print('[Child]: Parent should no longer wait.', flush=True)
+    # print('[Child]: Parent should no longer wait.', flush=True)
     parent_can_read.set()
-    print('[Child]: I have started waiting', flush=True)
+    # print('[Child]: I have started waiting', flush=True)
     child_can_read.wait()
-    print('[Child]: Wohooo.. I am free folks', flush=True)
+    # print('[Child]: Wohooo.. I am free folks', flush=True)
     f_x_recv, = comm_queue.get()
     child_can_read.clear()
     return f_x_recv
@@ -559,7 +562,7 @@ def run_local_scipy_opt(gen_specs, comm_queue, x0, f0, child_can_read,
         cons.append(up)
 
     method = gen_specs['localopt_method'][6:]
-    print('[Child]: Started my optimization', flush=True)
+    # print('[Child]: Started my optimization', flush=True)
     res = scipy_optimize.minimize(lambda x: scipy_callback_function(x,
         comm_queue, child_can_read, parent_can_read, gen_specs), x0,
         method=method, options={'maxiter': 100, 'tol': gen_specs['tol']})
@@ -575,7 +578,7 @@ def run_local_scipy_opt(gen_specs, comm_queue, x0, f0, child_can_read,
 
     # FIXME: Need to do something with the exit codes.
 
-    print('[Child]: I have converged.', flush=True)
+    # print('[Child]: I have converged.', flush=True)
     comm_queue.put(('Converged', x_opt))
     parent_can_read.set()
 
@@ -586,12 +589,12 @@ def run_local_scipy_opt(gen_specs, comm_queue, x0, f0, child_can_read,
 
 def tao_callback_function(tao, x, f, comm_queue, child_can_read, parent_can_read, gen_specs):
     comm_queue.put(x.array)
-    print('[Child]: I just put x_on_cube =', x.array, flush=True)
-    print('[Child]: Parent should no longer wait.', flush=True)
+    # print('[Child]: I just put x_on_cube =', x.array, flush=True)
+    # print('[Child]: Parent should no longer wait.', flush=True)
     parent_can_read.set()
-    print('[Child]: I have started waiting', flush=True)
+    # print('[Child]: I have started waiting', flush=True)
     child_can_read.wait()
-    print('[Child]: Wohooo.. I am free folks', flush=True)
+    # print('[Child]: Wohooo.. I am free folks', flush=True)
     f_recv,  = comm_queue.get()
     child_can_read.clear()
     f.array[:] = f_recv
@@ -644,7 +647,7 @@ def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read,
     tao.setTolerances(grtol=gen_specs['grtol'], gatol=gen_specs['gatol'])
     tao.setInitial(x)
 
-    print('[Child]: Started my optimization', flush=True)
+    # print('[Child]: Started my optimization', flush=True)
     tao.solve(x)
 
     x_opt = tao.getSolution().getArray()
@@ -664,7 +667,7 @@ def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read,
     tao.destroy()
 
     #FIXME: Do we need to do something of the final 'x_opt'?
-    print('[Child]: I have converged.', flush=True)
+    # print('[Child]: I have converged.', flush=True)
     comm_queue.put(('Converged', x_opt))
     parent_can_read.set()
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index f42f5c9f8..606080994 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -25,9 +25,13 @@
 from libensemble.alloc_funcs.start_only_persistent import only_persistent_gens as alloc_f
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
+from time import time
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
+if is_master:
+    start_time = time()
+
 if nworkers < 2:
     sys.exit("Cannot run with a persistent worker if only one worker -- aborting...")
 
@@ -69,4 +73,5 @@
 
 if is_master:
     print('[Manager]:', H[np.where(H['local_min'])]['x'])
+    print('[Manager]: Time taken =', time() - start_time, flush=True)
     # save_libE_output(H, persis_info, __file__, nworkers)

From 30e6f487f4c97b509ed7f06170bd8987fcfcc31a Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Tue, 30 Jul 2019 09:03:59 -0500
Subject: [PATCH 048/644] some more commenting statements

---
 libensemble/alloc_funcs/support.py |  4 ++--
 libensemble/gen_funcs/support.py   | 12 ++++++------
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/libensemble/alloc_funcs/support.py b/libensemble/alloc_funcs/support.py
index 56ebe43aa..49f7907d4 100644
--- a/libensemble/alloc_funcs/support.py
+++ b/libensemble/alloc_funcs/support.py
@@ -25,7 +25,7 @@ def count_persis_gens(W):
 
 def sim_work(Work, i, H_fields, H_rows, persis_info, **libE_info):
     "Add sim work record to work array."
-    print('[Allocator]: Calling sim_work for {}.'.format(H_rows), flush=True)
+    # print('[Allocator]: Calling sim_work for {}.'.format(H_rows), flush=True)
     libE_info['H_rows'] = H_rows
     Work[i] = {'H_fields': H_fields,
                'persis_info': persis_info,
@@ -35,7 +35,7 @@ def sim_work(Work, i, H_fields, H_rows, persis_info, **libE_info):
 
 def gen_work(Work, i, H_fields, H_rows, persis_info, **libE_info):
     "Add gen work record to work array."
-    print('[Allocator]: Calling gen_work for {}.'.format(H_rows), flush=True)
+    # print('[Allocator]: Calling gen_work for {}.'.format(H_rows), flush=True)
 
     libE_info['H_rows'] = H_rows
     Work[i] = {'H_fields': H_fields,
diff --git a/libensemble/gen_funcs/support.py b/libensemble/gen_funcs/support.py
index faa04199f..696ccf5d7 100644
--- a/libensemble/gen_funcs/support.py
+++ b/libensemble/gen_funcs/support.py
@@ -13,8 +13,8 @@ def send_mgr_worker_msg(comm, O):
     """Send message from worker to manager.
     """
     assert len(O) == 1
-    print(25*"-", "Sending {}(SimID: {})".format(O[0][0], O['sim_id']), 25*"-",
-        flush=True)
+    # print(25*"-", "Sending {}(SimID: {})".format(O[0][0], O['sim_id']), 25*"-",
+    #     flush=True)
     D = {'calc_out': O,
          'libE_info': {'persistent': True},
          'calc_status': UNSET_TAG,
@@ -26,14 +26,14 @@ def send_mgr_worker_msg(comm, O):
 def get_mgr_worker_msg(comm, status=None):
     """Get message to worker from manager.
     """
-    print('[Parent]: Expecting a message from Manager...', flush=True)
+    # print('[Parent]: Expecting a message from Manager...', flush=True)
     tag, Work = comm.recv()
-    print('[Parent]: Received a tag {}'.format(tag), flush=True)
+    # print('[Parent]: Received a tag {}'.format(tag), flush=True)
     sys.stdout.flush()
     if tag in [STOP_TAG, PERSIS_STOP]:
         comm.push_back(tag, Work)
         return tag, None, None
-    print('[Parent]: Expecting a message from Manager...', flush=True)
+    # print('[Parent]: Expecting a message from Manager...', flush=True)
     _, calc_in = comm.recv()
-    print('[Parent]: Received some message.', flush=True)
+    # print('[Parent]: Received some message.', flush=True)
     return tag, Work, calc_in

From 90c65e33983905fdef6f9f1f286a705e7b4a1796 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 2 Aug 2019 11:03:54 -0500
Subject: [PATCH 049/644] some cleanup

---
 libensemble/gen_funcs/persistent_aposmm.py | 277 ++++++++++-----------
 1 file changed, 125 insertions(+), 152 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 7262688ee..6e471f827 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -15,7 +15,6 @@
 from scipy import optimize as scipy_optimize
 
 from mpi4py import MPI
-from petsc4py import PETSc
 
 from numpy.lib.recfunctions import merge_arrays
 
@@ -35,6 +34,14 @@ class APOSMMException(Exception):
     "Raised for any exception in APOSMM"
 
 
+class ConvergedMsg(object):
+    """
+    Message communicated when a local optimization is converged.
+    """
+    def __init__(self, x):
+        self.x = x
+
+
 def aposmm(H, persis_info, gen_specs, libE_info):
     """
     APOSMM coordinates multiple local optimization runs, starting from points
@@ -186,13 +193,9 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     persis_info['old_runs']: Sequence of indices of points in finished runs
 
     """
-    np.random.seed(10)
-
-
     # {{{ multiprocessing initialization
 
-    child_can_read_evts = []
-    processes = []
+    local_opters = []
     parent_can_read_from_queue = Event()
     comm_queue = Queue()
 
@@ -239,10 +242,8 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     tag = None
     max_active_runs = gen_specs.get('max_active_runs', np.inf)
     waiting_starting_inds = []
-    O = np.empty(0, dtype=gen_specs['out'])  # noqa: E741
+    O = np.empty(0, dtype=gen_specs['out'])
     while 1:
-
-        # Receive from manager
         tag, Work, calc_in = get_mgr_worker_msg(comm)
 
         if calc_in:
@@ -259,21 +260,10 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in
                 data_to_give_processes = (f_x_recv, )
 
-            # print(23*"-", "Received f({})(SimID: {})".format(x_recv,
-            #     sim_id_recv), 24*"-",
-            #         flush=True)
-
         if tag in [STOP_TAG, PERSIS_STOP]:
-
-            # print('[Parent]: Received a stop tag, killing all children.', flush=True)
-            # FIXME: If there is any indication that all child processes are
-            # done with their work, we can do this a bit more cleanly i.e.
-            # first join and check if they are still alive, only then kill.
-
-            # sending SIGKILL to the processes.
-            # TODO: should we use SIGTERM instead?
-            for p in processes:
-                p.kill()
+            # FIXME: This has to be a clean exit.
+            for p in local_opters:
+                p.terminate()
             break
 
         n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
@@ -282,87 +272,35 @@ def aposmm(H, persis_info, gen_specs, libE_info):
             for child_idx in sim_id_to_child_indices[sim_id_recv]:
                 # print('[Parent]:Giving f = {} it to the'
                 #     ' child_idx: {}.'.format(f_x_recv, child_idx), flush=True)
-                comm_queue.put(data_to_give_processes)
-
-                parent_can_read_from_queue.clear()
-
-                child_can_read_evts[child_idx].set()
-                # print('[Parent]: I am waiting for child idx {}'.format(child_idx), flush=True)
-                parent_can_read_from_queue.wait()
-                # print('[Parent]: Wohoo I am free again', flush=True)
-
-                x_new = comm_queue.get()
+                x_new = local_opters.iterate(*data_to_give_processes)
                 # print('[Parent]: The child returned {}.'.format(x_new), flush=True)
-                if isinstance(x_new, tuple):
-                    # FIXME: [KK]: This is ugly and every bit of it happens in
-                    # my mind, this should be cleaned up duing the cleanup
-                    # phase.
-                    x_opt = x_new[1]
-                    # Need to figure out what are run_ids.
+                if isinstance(x_new, ConvergedMsg):
+                    x_opt = x_new.x
                     update_history_optimal(x_opt, local_H,
                             run_order[child_id_to_run_id[child_idx]])
-                    # print("[Parent]: Child {} has converged, miss you :'(".format(child_idx), flush=True)
-                    processes[child_idx].join()
-                    # print("[Parent]: Child {} has been joined.".format(child_idx), flush=True)
 
                     if waiting_starting_inds:
-                        # print('[Parent]: There was a waiting starting index'
-                        #        ' and started a run from there.', flush=True)
                         ind = waiting_starting_inds[0]
                         waiting_starting_inds = waiting_starting_inds[1:]
-
-                        child_can_read_evts.append(Event())
-
-                        # print('[Parent]: Initing process', flush=True)
-
-                        parent_can_read_from_queue.clear()
-
-                        # {{{ logic duplication(need to get rid of it)
-
-                        p = Process(target=run_local_opt, args=(gen_specs,
-                            comm_queue, local_H[ind]['x_on_cube'],
-                            local_H[ind]['f'],
-                            child_can_read_evts[-1],
-                            parent_can_read_from_queue))
-                        processes.append(p)
-                        p.start()
-                        # print('[Parent]: Started a child process', flush=True)
-
-                        # print('[Parent]: I am waiting', flush=True)
-                        parent_can_read_from_queue.wait()
-                        # print('[Parent]: Done waiting.', flush=True)
-
-                        assert np.allclose(comm_queue.get(), local_H[ind]['x_on_cube'])
-
-                        # print('[Parent]: Assertion holds.', flush=True)
-
-                        comm_queue.put(local_H[ind][[*fields_to_pass]])
-                        parent_can_read_from_queue.clear()
-
-                        child_can_read_evts[-1].set()
-                        parent_can_read_from_queue.wait()
-                        # print('[Master]: Getting a new x_new.', flush=True)
-
-                        x_new = comm_queue.get()
-
+                        local_opter = LocalOptInterfacer(gen_specs,
+                                local_H[ind]['x_on_cube'],
+                                parent_can_read_from_queue, comm_queue,
+                                local_H[ind]['f'])
+                        local_opters.append(local_opter)
+                        x_new = local_opter.iterate(local_H[ind][fields_to_pass])
                         add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
                         assert np.allclose(local_H[-1]['x_on_cube'], x_new)
 
-                        assert np.allclose(local_H[-1]['x_on_cube'], x_new)
-
                         run_order[total_runs] = [local_H[-1]['sim_id']]
-                        child_id_to_run_id[len(processes)-1] = total_runs
+                        child_id_to_run_id[len(local_opters)-1] = total_runs
                         total_runs += 1
-                        # Need to figure out the child number from the run number.
 
                         if local_H[-1]['sim_id'] in sim_id_to_child_indices:
-                            sim_id_to_child_indices[local_H[-1]['sim_id']] += (len(processes)-1, )
+                            sim_id_to_child_indices[local_H[-1]['sim_id']] += (len(local_opters)-1, )
                         else:
-                            sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(processes)-1, )
+                            sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(local_opters)-1, )
 
                         send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
-
-                        # }}}
                     else:
                         send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
                             sim_id_to_child_indices)
@@ -370,15 +308,13 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
                     assert np.allclose(local_H[-1]['x_on_cube'], x_new)
 
-                    send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
                     run_order[child_id_to_run_id[child_idx]].append(local_H[-1]['sim_id'])
                     if local_H[-1]['sim_id'] in sim_id_to_child_indices:
                         sim_id_to_child_indices[local_H[-1]['sim_id']] += (child_idx, )
                     else:
                         sim_id_to_child_indices[local_H[-1]['sim_id']] = (child_idx, )
+                    send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
         else:
-            # print('[Parent]: Did not find any local opt run to associate with.',
-            #         flush=True)
             if n_s < gen_specs['initial_sample_size']:
                 continue
             n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
@@ -389,64 +325,33 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                 local_H['started_run'][ind] = 1
 
-                if len([p for p in processes if p.is_alive()]) < max_active_runs:
-
-                    child_can_read_evts.append(Event())
-
-                    # print('[Parent]: Initing process', flush=True)
-
-                    parent_can_read_from_queue.clear()
-
-                    p = Process(target=run_local_opt, args=(gen_specs,
-                        comm_queue, local_H[ind]['x_on_cube'],
-                        local_H[ind]['f'],
-                        child_can_read_evts[-1],
-                        parent_can_read_from_queue))
-                    processes.append(p)
-                    p.start()
-                    # print('[Parent]: Started a child process', flush=True)
-
-                    # print('[Parent]: I am waiting', flush=True)
-                    parent_can_read_from_queue.wait()
-                    # print('[Parent]: Done waiting.', flush=True)
-
-                    # print('[Parent]: Starting with assertion checking', flush=True)
-                    assert np.allclose(comm_queue.get(), local_H[ind]['x_on_cube'])
-                    # print('[Parent]: Assertion holds.', flush=True)
-
-                    comm_queue.put(local_H[ind][[*fields_to_pass]])
-                    parent_can_read_from_queue.clear()
-
-                    child_can_read_evts[-1].set()
-                    parent_can_read_from_queue.wait()
-                    # print('[Master]: Getting a new x_new.', flush=True)
-
-                    x_new = comm_queue.get()
+                if len([p for p in local_opters if p.is_running]) < max_active_runs:
+                    local_opter = LocalOptInterfacer(gen_specs,
+                            local_H[ind]['x_on_cube'],
+                            parent_can_read_from_queue, comm_queue,
+                            local_H[ind]['f'])
+                    local_opters.append(local_opter)
+                    x_new = local_opter.iterate(local_H[ind][fields_to_pass])
 
                     add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
                     assert np.allclose(local_H[-1]['x_on_cube'], x_new)
 
-                    assert np.allclose(local_H[-1]['x_on_cube'], x_new)
-
                     run_order[total_runs] = [local_H[-1]['sim_id']]
-                    child_id_to_run_id[len(processes)-1] = total_runs
+                    child_id_to_run_id[len(local_opters)-1] = total_runs
                     total_runs += 1
-                    # Need to figure out the child number from the run number.
 
                     if local_H[-1]['sim_id'] in sim_id_to_child_indices:
-                        sim_id_to_child_indices[local_H[-1]['sim_id']] += (len(processes)-1, )
+                        sim_id_to_child_indices[local_H[-1]['sim_id']] += (len(local_opters)-1, )
                     else:
-                        sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(processes)-1, )
+                        sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(local_opters)-1, )
 
                     send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
                 else:
-                    # print('[Parent]: Not exceeding max active runs, putting it'
-                    #             ' in our stash', flush=True)
                     waiting_starting_inds.append(ind)
+
             if len(starting_inds) == 0 and len(waiting_starting_inds) == 0:
                 send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
                         sim_id_to_child_indices)
-        # print('[Parent]: Heading to next iteration', flush=True)
 
     print('[Parent]: The optimal points are:\n',
             local_H[np.where(local_H['local_min'])]['x'], flush=True)
@@ -454,19 +359,98 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     comm_queue.close()
     comm_queue.join_thread()
 
-    # print('Done with everything', flush=True)
-
-    for p in processes:
-        if p.is_alive():
+    for local_opter in local_opters:
+        if local_opter.is_running:
             raise RuntimeError("[Parent]: Atleast one child process is still active, even after"
                     " killing all the children.")
 
-    #TODO: Figure out what do we need to do from here.
-
     return local_H, persis_info, tag
 
 
-# {{{ NLOPT for local opt..
+class LocalOptInterfacer(object):
+    def __init__(self, gen_specs, x0, parent_can_read, comm_queue, f0,
+            grad0=None):
+        """
+        :param x0: A numpy array of the initial guess solution. This guess
+            should be scaled to a unit cube.
+        :param f0: A numpy array of the initial function value.
+
+
+        .. warning:: In order to have correct functioning of the local
+            optimization child processes. ~self.iterate~ should be called
+            immediately after creating the class.
+
+        """
+        self.parent_can_read = parent_can_read
+
+        self.comm_queue = comm_queue
+        self.child_can_read = Event()
+
+        # {{{ setting the local optimization method
+
+        if gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA',
+                'LN_NELDERMEAD', 'LD_MMA']:
+            run_local_opt = run_local_nlopt
+        elif gen_specs['localopt_method'] in ['pounders']:
+            run_local_opt = run_local_tao
+        elif gen_specs['localopt_method'] in ['scipy_COBYLA']:
+            run_local_opt = run_local_scipy_opt
+        else:
+            raise NotImplementedError("Unknown local optimization method "
+                    "'{}'.".format(gen_specs['localopt_method']))
+
+        # }}}
+
+        self.parent_can_read_from_queue.clear()
+        self.process = Process(target=run_local_opt, args=(gen_specs,
+            comm_queue,
+            x0, f0,
+            self.child_can_read,
+            parent_can_read))
+
+        self.process.start()
+        self.is_running = True
+        self.parent_can_read.wait()
+        assert np.allclose(comm_queue.get(), x0)
+
+    def iterate(self, f, grad=None):
+        """
+        Returns an instance of either :class:`numpy.ndarray` corresponding to the next
+        iterative guess or :class:`ConvergedMsg` when the solver is converged.
+
+        :param f: A numpy array of the function evaluation.
+        :param grad: A numpy array of the function's gradient.
+        """
+        if grad is not None:
+            self.comm_queue.put((f, grad))
+        else:
+            self.comm_queue.put((f, ))
+
+        self.parent_can_read.clear()
+        self.child_can_read.set()
+        self.parent_can_read.wait()
+
+        x_new = self.comm_queue.get()
+        if isinstance(x_new, ConvergedMsg):
+            self.is_running = False
+            self.process.join()
+
+        return x_new
+
+    def clean_exit(self):
+        self.comm_queue.put((np.nan*np.ones_like(self.f0), ))
+        self.parent_can_read.clear()
+        self.child_can_read.set()
+        self.parent_can_read.wait()
+
+        x_new = self.comm_queue.get()
+        assert isinstance(x_new, ConvergedMsg)
+        self.is_running = False
+        self.process.join()
+
+
+
+# {{{ NLOPT for local opt
 
 def nlopt_callback_function(x, grad, comm_queue, child_can_read, parent_can_read, gen_specs):
     comm_queue.put(x)
@@ -603,6 +587,8 @@ def tao_callback_function(tao, x, f, comm_queue, child_can_read, parent_can_read
 
 def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read,
         parent_can_read):
+
+    from petsc4py import PETSc
     assert isinstance(x0, np.ndarray)
 
     tao_comm = MPI.COMM_SELF
@@ -1339,19 +1325,6 @@ def send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm
     send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
 
 
-def send_initial_sample(gen_specs, persis_info, n, c_flag, comm, local_H,
-        sim_id_to_child_indices):
-    1/0
-    sampled_points = persis_info['rand_stream'].uniform(0, 1, (gen_specs['initial_sample_size'], n))
-    add_to_local_H(local_H, sampled_points, gen_specs, c_flag, on_cube=True)
-    for sim_id in local_H['sim_id'][-gen_specs['initial_sample_size']:]:
-        assert sim_id not in sim_id_to_child_indices
-        sim_id_to_child_indices[sim_id] = None
-
-    for i in range(len(local_H)):
-        send_mgr_worker_msg(comm, local_H[i:i+1][['x', 'sim_id']])
-
-
 def display_exception(e):
     print(e.__doc__)
     print(e.args)

From ff89687fd4e0bbe0f0bdcd30d522f3441d030e64 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 2 Aug 2019 11:24:58 -0500
Subject: [PATCH 050/644] Adding blmvm support for PETSc/TAO

---
 libensemble/gen_funcs/aposmm.py               | 60 ++++++++++---------
 .../test_6-hump_camel_aposmm_LD_MMA.py        | 11 +++-
 2 files changed, 41 insertions(+), 30 deletions(-)

diff --git a/libensemble/gen_funcs/aposmm.py b/libensemble/gen_funcs/aposmm.py
index 5b22e0fa6..f48ce9070 100644
--- a/libensemble/gen_funcs/aposmm.py
+++ b/libensemble/gen_funcs/aposmm.py
@@ -506,7 +506,7 @@ def advance_local_run(H, gen_specs, c_flag, run, persis_info):
                 exit_code = 0
                 display_exception(e)
 
-        elif gen_specs['localopt_method'] in ['pounders']:
+        elif gen_specs['localopt_method'] in ['pounders','blmvm']:
 
             if c_flag:
                 Run_H_F = np.zeros(len(sorted_run_inds), dtype=[('fvec', float, gen_specs['components'])])
@@ -515,7 +515,10 @@ def advance_local_run(H, gen_specs, c_flag, run, persis_info):
                     Run_H_F['fvec'][i, :] = H['f_i'][a1]
                 Run_H = merge_arrays([H[['x_on_cube']][sorted_run_inds], Run_H_F], flatten=True)
             else:
-                Run_H = H[['x_on_cube', 'fvec']][sorted_run_inds]
+                if gen_specs['localopt_method'] == 'pounders':
+                    Run_H = H[['x_on_cube', 'fvec']][sorted_run_inds]
+                else:
+                    Run_H = H[['x_on_cube', 'f', 'grad']][sorted_run_inds]
 
             try:
                 x_opt, exit_code = set_up_and_run_tao(Run_H, gen_specs)
@@ -653,16 +656,15 @@ def set_up_and_run_tao(Run_H, gen_specs):
     """
     tao_comm = MPI.COMM_SELF
     n = len(gen_specs['ub'])
-    m = len(Run_H['fvec'][0])
 
     def pounders_obj_func(tao, X, F, Run_H):
-        F.array = look_in_history(X.array, Run_H, vector_return=True)
+        F.array = look_in_history(X.array_r, Run_H, vector_return=True)
         return F
 
-    # def blmvm_obj_func(tao, X, G, Run_H):
-    #     (f, grad) = look_in_history_fd_grad(X.array, Run_H)
-    #     G.array = grad
-    #     return f
+    def blmvm_obj_func(tao, X, G, Run_H):
+        (f, grad) = look_in_history(X.array_r, Run_H)
+        G.array = grad
+        return f
 
     # Create starting point, bounds, and tao object
     x = PETSc.Vec().create(tao_comm)
@@ -676,24 +678,26 @@ def pounders_obj_func(tao, X, F, Run_H):
     tao = PETSc.TAO().create(tao_comm)
     tao.setType(gen_specs['localopt_method'])
 
-    # if gen_specs['localopt_method'] == 'pounders':
-    f = PETSc.Vec().create(tao_comm)
-    f.setSizes(m)
-    f.setFromOptions()
+    if gen_specs['localopt_method'] == 'pounders':
+        f = PETSc.Vec().create(tao_comm)
+        f.setSizes(len(Run_H['fvec'][0]))
+        f.setFromOptions()
 
-    delta_0 = gen_specs['dist_to_bound_multiple']*np.min([np.min(ub.array-x.array), np.min(x.array-lb.array)])
+        delta_0 = gen_specs['dist_to_bound_multiple']*np.min([np.min(ub.array-x.array), np.min(x.array-lb.array)])
 
-    PETSc.Options().setValue('-tao_pounders_delta', str(delta_0))
-    # PETSc.Options().setValue('-pounders_subsolver_tao_type','bqpip')
-    if hasattr(tao, 'setResidual'):
-        tao.setResidual(lambda tao, x, f: pounders_obj_func(tao, x, f, Run_H), f)
-    else:
-        tao.setSeparableObjective(lambda tao, x, f: pounders_obj_func(tao, x, f, Run_H), f)
-    # elif gen_specs['localopt_method'] == 'blmvm':
-    #     g = PETSc.Vec().create(tao_comm)
-    #     g.setSizes(n)
-    #     g.setFromOptions()
-    #     tao.setObjectiveGradient(lambda tao, x, g: blmvm_obj_func(tao, x, g, Run_H))
+        PETSc.Options().setValue('-tao_pounders_delta', str(delta_0))
+        
+        # PETSc.Options().setValue('-pounders_subsolver_tao_type','bqpip')
+        if hasattr(tao, 'setResidual'):
+            tao.setResidual(lambda tao, x, f: pounders_obj_func(tao, x, f, Run_H), f)
+        else:
+            tao.setSeparableObjective(lambda tao, x, f: pounders_obj_func(tao, x, f, Run_H), f)
+
+    elif gen_specs['localopt_method'] == 'blmvm':
+        g = PETSc.Vec().create(tao_comm)
+        g.setSizes(n)
+        g.setFromOptions()
+        tao.setObjectiveGradient(lambda tao, x, g: blmvm_obj_func(tao, x, g, Run_H))
 
     # Set everything for tao before solving
     PETSc.Options().setValue('-tao_max_funcs', str(len(Run_H)+1))
@@ -712,10 +716,10 @@ def pounders_obj_func(tao, X, F, Run_H):
     # print(tao.view())
     # print(x_opt)
 
-    # if gen_specs['localopt_method'] == 'pounders':
-    f.destroy()
-    # elif gen_specs['localopt_method'] == 'blmvm':
-    #     g.destroy()
+    if gen_specs['localopt_method'] == 'pounders':
+        f.destroy()
+    if gen_specs['localopt_method'] == 'blmvm':
+        g.destroy()
 
     lb.destroy()
     ub.destroy()
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
index 829b48fbf..4a88c1473 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
@@ -72,11 +72,18 @@ def libE_mpi_abort():
     quit()
 
 # Perform the run
-for run in range(2):
+for run in range(3):
     if libE_specs['comms'] == 'tcp' and is_master:
         libE_specs['worker_cmd'].append(str(run))
 
     if run == 1:
+        gen_specs['localopt_method'] = 'blmvm'
+        gen_specs['grtol'] = 1e-5
+        gen_specs['gatol'] = 1e-5
+        persis_info = deepcopy(persis_info_safe)
+
+    if run == 2:
+        gen_specs['localopt_method'] = 'LD_MMA'
         # Change the bounds to put a local min at a corner point (to test that
         # APOSMM handles the same point being in multiple runs) ability to
         # give back a previously evaluated point)
@@ -94,7 +101,7 @@ def libE_mpi_abort():
         exit_criteria = {'sim_max': 200, 'elapsed_wallclock_time': 300}
         minima = np.array([[-2.9, -1.9]])
 
-        persis_info = persis_info_safe
+        persis_info = deepcopy(persis_info_safe)
 
     H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria,
                                 persis_info, alloc_specs, libE_specs)

From 70f09d298f23f587f11e85f62b33f83af5eb921d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 2 Aug 2019 11:37:28 -0500
Subject: [PATCH 051/644] flake8

---
 libensemble/gen_funcs/aposmm.py | 4 ++--
 setup.py                        | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/libensemble/gen_funcs/aposmm.py b/libensemble/gen_funcs/aposmm.py
index f48ce9070..806bc1447 100644
--- a/libensemble/gen_funcs/aposmm.py
+++ b/libensemble/gen_funcs/aposmm.py
@@ -506,7 +506,7 @@ def advance_local_run(H, gen_specs, c_flag, run, persis_info):
                 exit_code = 0
                 display_exception(e)
 
-        elif gen_specs['localopt_method'] in ['pounders','blmvm']:
+        elif gen_specs['localopt_method'] in ['pounders', 'blmvm']:
 
             if c_flag:
                 Run_H_F = np.zeros(len(sorted_run_inds), dtype=[('fvec', float, gen_specs['components'])])
@@ -686,7 +686,7 @@ def blmvm_obj_func(tao, X, G, Run_H):
         delta_0 = gen_specs['dist_to_bound_multiple']*np.min([np.min(ub.array-x.array), np.min(x.array-lb.array)])
 
         PETSc.Options().setValue('-tao_pounders_delta', str(delta_0))
-        
+
         # PETSc.Options().setValue('-pounders_subsolver_tao_type','bqpip')
         if hasattr(tao, 'setResidual'):
             tao.setResidual(lambda tao, x, f: pounders_obj_func(tao, x, f, Run_H), f)
diff --git a/setup.py b/setup.py
index e8df45a9b..a5327c053 100644
--- a/setup.py
+++ b/setup.py
@@ -60,7 +60,7 @@ def run_tests(self):
                    'mock'
                    ],
 
-    extras_require = {
+    extras_require={
            'extras': ['scipy', 'nlopt', 'mpi4py', 'petsc', 'petsc4py']},
 
     classifiers=[

From 5f574fa05c4b4e628a81012e2f22abd8ef22d426 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 2 Aug 2019 13:01:54 -0500
Subject: [PATCH 052/644] minor fix to pass both f and grad_f to the local
 optimization

---
 libensemble/gen_funcs/persistent_aposmm.py | 25 ++++++++++++----------
 1 file changed, 14 insertions(+), 11 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 6e471f827..fa9c711c9 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -263,7 +263,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         if tag in [STOP_TAG, PERSIS_STOP]:
             # FIXME: This has to be a clean exit.
             for p in local_opters:
-                p.terminate()
+                p.destroy()
             break
 
         n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
@@ -287,7 +287,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                                 parent_can_read_from_queue, comm_queue,
                                 local_H[ind]['f'])
                         local_opters.append(local_opter)
-                        x_new = local_opter.iterate(local_H[ind][fields_to_pass])
+                        x_new = local_opter.iterate(*local_H[ind][fields_to_pass])
                         add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
                         assert np.allclose(local_H[-1]['x_on_cube'], x_new)
 
@@ -331,7 +331,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                             parent_can_read_from_queue, comm_queue,
                             local_H[ind]['f'])
                     local_opters.append(local_opter)
-                    x_new = local_opter.iterate(local_H[ind][fields_to_pass])
+                    x_new = local_opter.iterate(*local_H[ind][fields_to_pass])
 
                     add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
                     assert np.allclose(local_H[-1]['x_on_cube'], x_new)
@@ -401,7 +401,7 @@ def __init__(self, gen_specs, x0, parent_can_read, comm_queue, f0,
 
         # }}}
 
-        self.parent_can_read_from_queue.clear()
+        self.parent_can_read.clear()
         self.process = Process(target=run_local_opt, args=(gen_specs,
             comm_queue,
             x0, f0,
@@ -421,12 +421,12 @@ def iterate(self, f, grad=None):
         :param f: A numpy array of the function evaluation.
         :param grad: A numpy array of the function's gradient.
         """
-        if grad is not None:
-            self.comm_queue.put((f, grad))
-        else:
+        self.parent_can_read.clear()
+        if grad is None:
             self.comm_queue.put((f, ))
+        else:
+            self.comm_queue.put((f, grad))
 
-        self.parent_can_read.clear()
         self.child_can_read.set()
         self.parent_can_read.wait()
 
@@ -437,7 +437,10 @@ def iterate(self, f, grad=None):
 
         return x_new
 
-    def clean_exit(self):
+    def destroy(self):
+        # FIXME: This isn't a clean exit yet, need to handle it.
+        self.process.terminate()
+        return
         self.comm_queue.put((np.nan*np.ones_like(self.f0), ))
         self.parent_can_read.clear()
         self.child_can_read.set()
@@ -512,7 +515,7 @@ def run_local_nlopt(gen_specs, comm_queue, x0, f0, child_can_read,
     # print('[Child]: Started my optimization', flush=True)
     x_opt = opt.optimize(x0)
     # print('[Child]: I have converged.', flush=True)
-    comm_queue.put(('Converged', x_opt))
+    comm_queue.put(ConvergedMsg(x_opt))
     parent_can_read.set()
 
 # }}}
@@ -654,7 +657,7 @@ def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read,
 
     #FIXME: Do we need to do something of the final 'x_opt'?
     # print('[Child]: I have converged.', flush=True)
-    comm_queue.put(('Converged', x_opt))
+    comm_queue.put(ConvergedMsg(x_opt))
     parent_can_read.set()
 
     # FIXME: What do we do about the exit_code?

From 09c6e6a4aa0dc31ad96adc04200c773758139ae7 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 2 Aug 2019 13:07:28 -0500
Subject: [PATCH 053/644] some more progress on cleaning up the code

---
 libensemble/gen_funcs/persistent_aposmm.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index fa9c711c9..268c426dc 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -272,7 +272,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
             for child_idx in sim_id_to_child_indices[sim_id_recv]:
                 # print('[Parent]:Giving f = {} it to the'
                 #     ' child_idx: {}.'.format(f_x_recv, child_idx), flush=True)
-                x_new = local_opters.iterate(*data_to_give_processes)
+                x_new = local_opters[child_idx].iterate(*data_to_give_processes)
                 # print('[Parent]: The child returned {}.'.format(x_new), flush=True)
                 if isinstance(x_new, ConvergedMsg):
                     x_opt = x_new.x

From 1e43a4e1f745552827885f2b9a50fd8798033b17 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 2 Aug 2019 14:31:35 -0500
Subject: [PATCH 054/644] preliminary work on clean exit

---
 libensemble/gen_funcs/persistent_aposmm.py | 71 +++++++++++-----------
 1 file changed, 35 insertions(+), 36 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 268c426dc..c8eab82e6 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -207,21 +207,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     child_id_to_run_id = {}
     run_order = {}
 
-    # {{{ setting the local optimization method
-
-    if gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA',
-            'LN_NELDERMEAD', 'LD_MMA']:
-        run_local_opt = run_local_nlopt
-    elif gen_specs['localopt_method'] in ['pounders']:
-        run_local_opt = run_local_tao
-    elif gen_specs['localopt_method'] in ['scipy_COBYLA']:
-        run_local_opt = run_local_scipy_opt
-    else:
-        raise NotImplementedError("Unknown local optimization method "
-                "'{}'.".format(gen_specs['localopt_method']))
-
-    # }}}
-
     # {{{ setting the data needed by the local optimization method
 
     if gen_specs['localopt_method'] in ['LD_MMA']:
@@ -247,6 +232,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         tag, Work, calc_in = get_mgr_worker_msg(comm)
 
         if calc_in:
+            grad_f_x_recv = None
             if fields_to_pass == ['f', 'grad']:
                 (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in
                 data_to_give_processes = (f_x_recv, grad_f_x_recv)
@@ -262,18 +248,20 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
         if tag in [STOP_TAG, PERSIS_STOP]:
             # FIXME: This has to be a clean exit.
+
+            print('[Parent]: The optimal points are:\n',
+                    local_H[np.where(local_H['local_min'])]['x'], flush=True)
+
             for p in local_opters:
-                p.destroy()
+                if p.is_running:
+                    p.destroy()
             break
 
         n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
 
         if sim_id_to_child_indices.get(sim_id_recv):
             for child_idx in sim_id_to_child_indices[sim_id_recv]:
-                # print('[Parent]:Giving f = {} it to the'
-                #     ' child_idx: {}.'.format(f_x_recv, child_idx), flush=True)
                 x_new = local_opters[child_idx].iterate(*data_to_give_processes)
-                # print('[Parent]: The child returned {}.'.format(x_new), flush=True)
                 if isinstance(x_new, ConvergedMsg):
                     x_opt = x_new.x
                     update_history_optimal(x_opt, local_H,
@@ -282,10 +270,13 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     if waiting_starting_inds:
                         ind = waiting_starting_inds[0]
                         waiting_starting_inds = waiting_starting_inds[1:]
+
+                        # {{{ initing a local opt run
+
                         local_opter = LocalOptInterfacer(gen_specs,
                                 local_H[ind]['x_on_cube'],
                                 parent_can_read_from_queue, comm_queue,
-                                local_H[ind]['f'])
+                                local_H[ind]['f'], grad_f_x_recv)
                         local_opters.append(local_opter)
                         x_new = local_opter.iterate(*local_H[ind][fields_to_pass])
                         add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
@@ -300,6 +291,8 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                         else:
                             sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(local_opters)-1, )
 
+                        # }}}
+
                         send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
                     else:
                         send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
@@ -326,10 +319,13 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 local_H['started_run'][ind] = 1
 
                 if len([p for p in local_opters if p.is_running]) < max_active_runs:
+
+                    # {{{ initing a local opt run
+
                     local_opter = LocalOptInterfacer(gen_specs,
                             local_H[ind]['x_on_cube'],
                             parent_can_read_from_queue, comm_queue,
-                            local_H[ind]['f'])
+                            local_H[ind]['f'], grad_f_x_recv)
                     local_opters.append(local_opter)
                     x_new = local_opter.iterate(*local_H[ind][fields_to_pass])
 
@@ -345,6 +341,8 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     else:
                         sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(local_opters)-1, )
 
+                    # }}}
+
                     send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
                 else:
                     waiting_starting_inds.append(ind)
@@ -353,9 +351,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
                         sim_id_to_child_indices)
 
-    print('[Parent]: The optimal points are:\n',
-            local_H[np.where(local_H['local_min'])]['x'], flush=True)
-
     comm_queue.close()
     comm_queue.join_thread()
 
@@ -386,6 +381,10 @@ def __init__(self, gen_specs, x0, parent_can_read, comm_queue, f0,
         self.comm_queue = comm_queue
         self.child_can_read = Event()
 
+        self.x0 = x0
+        self.f0 = f0
+        self.grad0 = grad0
+
         # {{{ setting the local optimization method
 
         if gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA',
@@ -438,30 +437,30 @@ def iterate(self, f, grad=None):
         return x_new
 
     def destroy(self):
-        # FIXME: This isn't a clean exit yet, need to handle it.
-        self.process.terminate()
-        return
-        self.comm_queue.put((np.nan*np.ones_like(self.f0), ))
-        self.parent_can_read.clear()
-        self.child_can_read.set()
-        self.parent_can_read.wait()
+        x_new = None
+        while not isinstance(x_new, ConvergedMsg):
+            self.parent_can_read.clear()
+            if self.grad0 is None:
+                self.comm_queue.put((-np.inf*np.ones_like(self.f0),))
+            else:
+                self.comm_queue.put((-np.inf*np.ones_like(self.f0),
+                    np.zeros_like(self.grad0)))
 
-        x_new = self.comm_queue.get()
+            self.child_can_read.set()
+            self.parent_can_read.wait()
+
+            x_new = self.comm_queue.get()
         assert isinstance(x_new, ConvergedMsg)
         self.is_running = False
         self.process.join()
 
 
-
 # {{{ NLOPT for local opt
 
 def nlopt_callback_function(x, grad, comm_queue, child_can_read, parent_can_read, gen_specs):
     comm_queue.put(x)
-    # print('[Child]: Parent should no longer wait.', flush=True)
     parent_can_read.set()
-    # print('[Child]: I have started waiting', flush=True)
     child_can_read.wait()
-    # print('[Child]: Wohooo.. I am free folks', flush=True)
     if gen_specs['localopt_method'] in ['LD_MMA']:
         f_recv, grad_recv = comm_queue.get()
         grad[:] = grad_recv

From 359f5e29188024828e3c22bc86db8092a5bd1999 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 2 Aug 2019 15:21:13 -0500
Subject: [PATCH 055/644] checks clean exit for scipy and nlopt

---
 libensemble/gen_funcs/persistent_aposmm.py | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index c8eab82e6..7f4dfdb2b 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -232,7 +232,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         tag, Work, calc_in = get_mgr_worker_msg(comm)
 
         if calc_in:
-            grad_f_x_recv = None
             if fields_to_pass == ['f', 'grad']:
                 (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in
                 data_to_give_processes = (f_x_recv, grad_f_x_recv)
@@ -276,7 +275,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                         local_opter = LocalOptInterfacer(gen_specs,
                                 local_H[ind]['x_on_cube'],
                                 parent_can_read_from_queue, comm_queue,
-                                local_H[ind]['f'], grad_f_x_recv)
+                                local_H[ind]['f'], grad_f_x_recv if 'grad' in fields_to_pass else None)
                         local_opters.append(local_opter)
                         x_new = local_opter.iterate(*local_H[ind][fields_to_pass])
                         add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
@@ -325,7 +324,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     local_opter = LocalOptInterfacer(gen_specs,
                             local_H[ind]['x_on_cube'],
                             parent_can_read_from_queue, comm_queue,
-                            local_H[ind]['f'], grad_f_x_recv)
+                            local_H[ind]['f'], grad_f_x_recv if 'grad' in fields_to_pass else None)
                     local_opters.append(local_opter)
                     x_new = local_opter.iterate(*local_H[ind][fields_to_pass])
 
@@ -431,8 +430,8 @@ def iterate(self, f, grad=None):
 
         x_new = self.comm_queue.get()
         if isinstance(x_new, ConvergedMsg):
-            self.is_running = False
             self.process.join()
+            self.is_running = False
 
         return x_new
 
@@ -441,9 +440,9 @@ def destroy(self):
         while not isinstance(x_new, ConvergedMsg):
             self.parent_can_read.clear()
             if self.grad0 is None:
-                self.comm_queue.put((-np.inf*np.ones_like(self.f0),))
+                self.comm_queue.put((0*np.ones_like(self.f0),))
             else:
-                self.comm_queue.put((-np.inf*np.ones_like(self.f0),
+                self.comm_queue.put((0*np.ones_like(self.f0),
                     np.zeros_like(self.grad0)))
 
             self.child_can_read.set()
@@ -451,8 +450,8 @@ def destroy(self):
 
             x_new = self.comm_queue.get()
         assert isinstance(x_new, ConvergedMsg)
-        self.is_running = False
         self.process.join()
+        self.is_running = False
 
 
 # {{{ NLOPT for local opt
@@ -565,7 +564,7 @@ def run_local_scipy_opt(gen_specs, comm_queue, x0, f0, child_can_read,
     # FIXME: Need to do something with the exit codes.
 
     # print('[Child]: I have converged.', flush=True)
-    comm_queue.put(('Converged', x_opt))
+    comm_queue.put(ConvergedMsg(x_opt))
     parent_can_read.set()
 
 # }}}

From c3742d1571d8bb3afe56ba029ba4d1e0b118d5f9 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 2 Aug 2019 15:28:43 -0500
Subject: [PATCH 056/644] imports petsc at the top

---
 libensemble/gen_funcs/persistent_aposmm.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 7f4dfdb2b..b1bb17772 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -13,6 +13,7 @@
 import numpy as np
 from scipy.spatial.distance import cdist, pdist, squareform
 from scipy import optimize as scipy_optimize
+from petsc4py import PETSc
 
 from mpi4py import MPI
 
@@ -589,7 +590,6 @@ def tao_callback_function(tao, x, f, comm_queue, child_can_read, parent_can_read
 def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read,
         parent_can_read):
 
-    from petsc4py import PETSc
     assert isinstance(x0, np.ndarray)
 
     tao_comm = MPI.COMM_SELF

From f1d86c5a3afcda993a43b19d1a53d40480425b64 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 2 Aug 2019 15:58:29 -0500
Subject: [PATCH 057/644] reverts any changes in support.py

---
 libensemble/gen_funcs/support.py | 9 ---------
 1 file changed, 9 deletions(-)

diff --git a/libensemble/gen_funcs/support.py b/libensemble/gen_funcs/support.py
index 696ccf5d7..e5084828d 100644
--- a/libensemble/gen_funcs/support.py
+++ b/libensemble/gen_funcs/support.py
@@ -1,5 +1,4 @@
 from libensemble.message_numbers import STOP_TAG, PERSIS_STOP, UNSET_TAG, EVAL_GEN_TAG
-import sys
 
 
 def sendrecv_mgr_worker_msg(comm, O, status=None):
@@ -12,9 +11,6 @@ def sendrecv_mgr_worker_msg(comm, O, status=None):
 def send_mgr_worker_msg(comm, O):
     """Send message from worker to manager.
     """
-    assert len(O) == 1
-    # print(25*"-", "Sending {}(SimID: {})".format(O[0][0], O['sim_id']), 25*"-",
-    #     flush=True)
     D = {'calc_out': O,
          'libE_info': {'persistent': True},
          'calc_status': UNSET_TAG,
@@ -26,14 +22,9 @@ def send_mgr_worker_msg(comm, O):
 def get_mgr_worker_msg(comm, status=None):
     """Get message to worker from manager.
     """
-    # print('[Parent]: Expecting a message from Manager...', flush=True)
     tag, Work = comm.recv()
-    # print('[Parent]: Received a tag {}'.format(tag), flush=True)
-    sys.stdout.flush()
     if tag in [STOP_TAG, PERSIS_STOP]:
         comm.push_back(tag, Work)
         return tag, None, None
-    # print('[Parent]: Expecting a message from Manager...', flush=True)
     _, calc_in = comm.recv()
-    # print('[Parent]: Received some message.', flush=True)
     return tag, Work, calc_in

From 87ed78e9fb3b4d3552775033c6fb1c2355269f36 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 2 Aug 2019 16:11:44 -0500
Subject: [PATCH 058/644] reverts any changes in alloc_funcs/support.py

---
 libensemble/alloc_funcs/support.py | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/libensemble/alloc_funcs/support.py b/libensemble/alloc_funcs/support.py
index 49f7907d4..927003ffe 100644
--- a/libensemble/alloc_funcs/support.py
+++ b/libensemble/alloc_funcs/support.py
@@ -25,7 +25,6 @@ def count_persis_gens(W):
 
 def sim_work(Work, i, H_fields, H_rows, persis_info, **libE_info):
     "Add sim work record to work array."
-    # print('[Allocator]: Calling sim_work for {}.'.format(H_rows), flush=True)
     libE_info['H_rows'] = H_rows
     Work[i] = {'H_fields': H_fields,
                'persis_info': persis_info,
@@ -35,8 +34,6 @@ def sim_work(Work, i, H_fields, H_rows, persis_info, **libE_info):
 
 def gen_work(Work, i, H_fields, H_rows, persis_info, **libE_info):
     "Add gen work record to work array."
-    # print('[Allocator]: Calling gen_work for {}.'.format(H_rows), flush=True)
-
     libE_info['H_rows'] = H_rows
     Work[i] = {'H_fields': H_fields,
                'persis_info': persis_info,

From 8536e30b982a2db431f1c0cb1fc74353e1f55843 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 2 Aug 2019 16:13:24 -0500
Subject: [PATCH 059/644] reverts any changes in other tests

---
 .../test_6-hump_camel_aposmm_LD_MMA.py        | 72 ++++---------------
 1 file changed, 12 insertions(+), 60 deletions(-)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
index ddae2ce7f..3da958d54 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
@@ -16,6 +16,7 @@
 import numpy as np
 from math import gamma, pi, sqrt
 from copy import deepcopy
+from mpi4py import MPI
 
 # Import libEnsemble items for this test
 from libensemble.libE import libE, libE_tcp_worker
@@ -24,8 +25,13 @@
 from libensemble.alloc_funcs.fast_alloc_to_aposmm import give_sim_work_first as alloc_f
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import persis_info_1 as persis_info, aposmm_gen_out as gen_out, six_hump_camel_minima as minima
+from time import time
 
 nworkers, is_master, libE_specs, _ = parse_args()
+np.random.seed(MPI.COMM_WORLD.Get_rank())
+
+if is_master:
+    start_time = time()
 
 n = 2
 sim_specs = {'sim_f': sim_f,
@@ -36,6 +42,7 @@
 gen_specs = {'gen_f': gen_f,
              'in': [o[0] for o in gen_out] + ['f', 'grad', 'returned'],
              'out': gen_out,
+             'num_active_gens': 1,
              'batch_mode': True,
              'initial_sample_size': 100,
              'sample_points': np.round(minima, 1),
@@ -55,65 +62,10 @@
 exit_criteria = {'sim_max': 1000}
 
 # Set up appropriate abort mechanism depending on comms
-libE_abort = quit
-if libE_specs['comms'] == 'mpi':
-    from mpi4py import MPI
-
-    def libE_mpi_abort():
-        MPI.COMM_WORLD.Abort(1)
-
-    libE_abort = libE_mpi_abort
-
-# Perform the run (TCP worker mode)
-if libE_specs['comms'] == 'tcp' and not is_master:
-    run = int(sys.argv[-1])
-    libE_tcp_worker(sim_specs, gen_specs[run], libE_specs)
-    quit()
-
-# Perform the run
-for run in range(2):
-    if libE_specs['comms'] == 'tcp' and is_master:
-        libE_specs['worker_cmd'].append(str(run))
-
-    if run == 1:
-        # Change the bounds to put a local min at a corner point (to test that
-        # APOSMM handles the same point being in multiple runs) ability to
-        # give back a previously evaluated point)
-        gen_specs['ub'] = np.array([-2.9, -1.9])
-        gen_specs['mu'] = 1e-4
-        gen_specs['rk_const'] = 0.01*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi)
-        gen_specs['lhs_divisions'] = 2
-        # APOSMM can be called when some run is incomplete
-        gen_specs.pop('batch_mode')
-
-        gen_specs.pop('xtol_rel')
-        gen_specs['ftol_rel'] = 1e-2
-        gen_specs['xtol_abs'] = 1e-3
-        gen_specs['ftol_abs'] = 1e-8
-        exit_criteria = {'sim_max': 200, 'elapsed_wallclock_time': 300}
-        minima = np.array([[-2.9, -1.9]])
-
-        persis_info = persis_info_safe
-
-    H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria,
-                                persis_info, alloc_specs, libE_specs)
-
-    if is_master:
-        if flag != 0:
-            print("Exit was not on convergence (code {})".format(flag))
-            sys.stdout.flush()
-            libE_abort()
 
-        tol = 1e-5
-        for m in minima:
-            # The minima are known on this test problem.
-            # 1) We use their values to test APOSMM has identified all minima
-            # 2) We use their approximate values to ensure APOSMM evaluates a
-            #    point in each minima's basin of attraction.
-            print(np.min(np.sum((H[H['local_min']]['x'] - m)**2, 1)))
-            sys.stdout.flush()
-            if np.min(np.sum((H[H['local_min']]['x'] - m)**2, 1)) > tol:
-                libE_abort()
+H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria,
+                            persis_info, alloc_specs, libE_specs)
 
-        print("\nlibEnsemble with APOSMM using a gradient-based localopt method has identified the " + str(np.shape(minima)[0]) + " minima within a tolerance " + str(tol))
-        save_libE_output(H, persis_info, __file__, nworkers)
+if is_master:
+    print('[Manager]:', H[np.where(H['local_min'])]['x'])
+    print('[Manager]: Time taken =', time()-start_time)

From 271ba78992e59b523c35be5bd8572b4cd1a0ac6a Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 2 Aug 2019 16:16:54 -0500
Subject: [PATCH 060/644] re-adds 2 runs in test_6humpcamel_aposmm_LD_MMA.py

---
 .../test_6-hump_camel_aposmm_LD_MMA.py        | 71 ++++++++++++++++---
 1 file changed, 60 insertions(+), 11 deletions(-)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
index 3da958d54..829b48fbf 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
@@ -16,7 +16,6 @@
 import numpy as np
 from math import gamma, pi, sqrt
 from copy import deepcopy
-from mpi4py import MPI
 
 # Import libEnsemble items for this test
 from libensemble.libE import libE, libE_tcp_worker
@@ -25,13 +24,8 @@
 from libensemble.alloc_funcs.fast_alloc_to_aposmm import give_sim_work_first as alloc_f
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import persis_info_1 as persis_info, aposmm_gen_out as gen_out, six_hump_camel_minima as minima
-from time import time
 
 nworkers, is_master, libE_specs, _ = parse_args()
-np.random.seed(MPI.COMM_WORLD.Get_rank())
-
-if is_master:
-    start_time = time()
 
 n = 2
 sim_specs = {'sim_f': sim_f,
@@ -62,10 +56,65 @@
 exit_criteria = {'sim_max': 1000}
 
 # Set up appropriate abort mechanism depending on comms
+libE_abort = quit
+if libE_specs['comms'] == 'mpi':
+    from mpi4py import MPI
+
+    def libE_mpi_abort():
+        MPI.COMM_WORLD.Abort(1)
+
+    libE_abort = libE_mpi_abort
+
+# Perform the run (TCP worker mode)
+if libE_specs['comms'] == 'tcp' and not is_master:
+    run = int(sys.argv[-1])
+    libE_tcp_worker(sim_specs, gen_specs[run], libE_specs)
+    quit()
+
+# Perform the run
+for run in range(2):
+    if libE_specs['comms'] == 'tcp' and is_master:
+        libE_specs['worker_cmd'].append(str(run))
+
+    if run == 1:
+        # Change the bounds to put a local min at a corner point (to test that
+        # APOSMM handles the same point being in multiple runs) ability to
+        # give back a previously evaluated point)
+        gen_specs['ub'] = np.array([-2.9, -1.9])
+        gen_specs['mu'] = 1e-4
+        gen_specs['rk_const'] = 0.01*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi)
+        gen_specs['lhs_divisions'] = 2
+        # APOSMM can be called when some run is incomplete
+        gen_specs.pop('batch_mode')
+
+        gen_specs.pop('xtol_rel')
+        gen_specs['ftol_rel'] = 1e-2
+        gen_specs['xtol_abs'] = 1e-3
+        gen_specs['ftol_abs'] = 1e-8
+        exit_criteria = {'sim_max': 200, 'elapsed_wallclock_time': 300}
+        minima = np.array([[-2.9, -1.9]])
+
+        persis_info = persis_info_safe
+
+    H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria,
+                                persis_info, alloc_specs, libE_specs)
+
+    if is_master:
+        if flag != 0:
+            print("Exit was not on convergence (code {})".format(flag))
+            sys.stdout.flush()
+            libE_abort()
 
-H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria,
-                            persis_info, alloc_specs, libE_specs)
+        tol = 1e-5
+        for m in minima:
+            # The minima are known on this test problem.
+            # 1) We use their values to test APOSMM has identified all minima
+            # 2) We use their approximate values to ensure APOSMM evaluates a
+            #    point in each minima's basin of attraction.
+            print(np.min(np.sum((H[H['local_min']]['x'] - m)**2, 1)))
+            sys.stdout.flush()
+            if np.min(np.sum((H[H['local_min']]['x'] - m)**2, 1)) > tol:
+                libE_abort()
 
-if is_master:
-    print('[Manager]:', H[np.where(H['local_min'])]['x'])
-    print('[Manager]: Time taken =', time()-start_time)
+        print("\nlibEnsemble with APOSMM using a gradient-based localopt method has identified the " + str(np.shape(minima)[0]) + " minima within a tolerance " + str(tol))
+        save_libE_output(H, persis_info, __file__, nworkers)

From 83167c582e4741a574ec1751456459a19c37e245 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 2 Aug 2019 23:07:48 -0500
Subject: [PATCH 061/644] removes unused parts from earlier aposmm logic

---
 libensemble/gen_funcs/persistent_aposmm.py | 293 ---------------------
 1 file changed, 293 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index b1bb17772..cce506729 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -829,253 +829,6 @@ def update_history_optimal(x_opt, H, run_inds):
     H['num_active_runs'][run_inds] -= 1
 
 
-def advance_local_run(H, gen_specs, c_flag, run, persis_info):
-    """
-    Moves a local optimization method one iteration forward. We currently do
-    this by feeding all past evaluations from a run to the method and then
-    storing the first new point generated
-    """
-
-    while 1:
-        sorted_run_inds = persis_info['run_order'][run]
-        advance_local_run.x_new = np.ones((1, len(gen_specs['ub'])))*np.inf
-        advance_local_run.pt_in_run = 0
-
-        if gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA',
-                                            'LN_COBYLA', 'LN_NELDERMEAD',
-                                            'LD_MMA']:
-
-            if gen_specs['localopt_method'] in ['LD_MMA']:
-                fields_to_pass = ['x_on_cube', 'f', 'grad']
-            else:
-                fields_to_pass = ['x_on_cube', 'f']
-
-            try:
-                x_opt, exit_code = set_up_and_run_nlopt(H[fields_to_pass][sorted_run_inds], gen_specs)
-            except Exception as e:
-                x_opt = 0
-                exit_code = 0
-                display_exception(e)
-
-        elif gen_specs['localopt_method'] in ['pounders']:
-
-            if c_flag:
-                Run_H_F = np.zeros(len(sorted_run_inds), dtype=[('fvec', float, gen_specs['components'])])
-                for i, ind in enumerate(sorted_run_inds):
-                    a1 = H['pt_id'] == H['pt_id'][ind]
-                    Run_H_F['fvec'][i, :] = H['f_i'][a1]
-                Run_H = merge_arrays([H[['x_on_cube']][sorted_run_inds], Run_H_F], flatten=True)
-            else:
-                Run_H = H[['x_on_cube', 'fvec']][sorted_run_inds]
-
-            try:
-                x_opt, exit_code = set_up_and_run_tao(Run_H, gen_specs)
-            except Exception as e:
-                x_opt = 0
-                exit_code = 0
-                display_exception(e)
-
-        elif gen_specs['localopt_method'] == 'scipy_COBYLA':
-
-            fields_to_pass = ['x_on_cube', 'f']
-
-            try:
-                x_opt, exit_code = set_up_and_run_scipy_minimize(H[fields_to_pass][sorted_run_inds], gen_specs)
-            except Exception as e:
-                x_opt = 0
-                exit_code = 0
-                display_exception(e)
-
-        else:
-            raise APOSMMException("Unknown localopt method. Exiting")
-
-        match_ind = np.equal(advance_local_run.x_new, H['x_on_cube']).all(1)
-        if ~match_ind.any():
-            # Generated a new point
-            break
-        else:
-            # We need to add a previously evaluated point into this run
-            persis_info['run_order'][run].append(np.nonzero(match_ind)[0][0])
-
-    return x_opt, exit_code, persis_info, sorted_run_inds, advance_local_run.x_new
-
-
-def set_up_and_run_scipy_minimize(Run_H, gen_specs):
-    """ Set up objective and runs scipy
-
-    Declares the appropriate syntax for our special objective function to read
-    through Run_H, sets the parameters and starting points for the run.
-    """
-
-    def scipy_obj_fun(x, Run_H):
-        out = look_in_history(x, Run_H)
-
-        return out
-
-    obj = lambda x: scipy_obj_fun(x, Run_H)
-    x0 = Run_H['x_on_cube'][0]
-
-    # Construct the bounds in the form of constraints
-    cons = []
-    for factor in range(len(x0)):
-        lo = {'type': 'ineq',
-              'fun': lambda x, lb=gen_specs['lb'][factor], i=factor: x[i]-lb}
-        up = {'type': 'ineq',
-              'fun': lambda x, ub=gen_specs['ub'][factor], i=factor: ub-x[i]}
-        cons.append(lo)
-        cons.append(up)
-
-    method = gen_specs['localopt_method'][6:]
-    res = scipy_optimize.minimize(obj, x0, method=method, options={'maxiter': len(Run_H['x_on_cube'])+1, 'tol': gen_specs['tol']})
-
-    if res['status'] == 2:  # SciPy code for exhausting budget of evaluations, so not at a minimum
-        exit_code = 0
-    else:
-        if method == 'COBYLA':
-            assert res['status'] == 1, "Unknown status for COBYLA"
-            exit_code = 1
-
-    x_opt = res['x']
-    return x_opt, exit_code
-
-
-def set_up_and_run_nlopt(Run_H, gen_specs):
-    """ Set up objective and runs nlopt
-
-    Declares the appropriate syntax for our special objective function to read
-    through Run_H, sets the parameters and starting points for the run.
-    """
-
-    assert 'xtol_rel' or 'xtol_abs' or 'ftol_rel' or 'ftol_abs' in gen_specs, "NLopt can cycle if xtol_rel, xtol_abs, ftol_rel, or ftol_abs are not set"
-
-    def nlopt_obj_fun(x, grad, Run_H):
-        out = look_in_history(x, Run_H)
-
-        if gen_specs['localopt_method'] in ['LD_MMA']:
-            grad[:] = out[1]
-            out = out[0]
-
-        return out
-
-    n = len(gen_specs['ub'])
-
-    opt = nlopt.opt(getattr(nlopt, gen_specs['localopt_method']), n)
-
-    lb = np.zeros(n)
-    ub = np.ones(n)
-    opt.set_lower_bounds(lb)
-    opt.set_upper_bounds(ub)
-    x0 = Run_H['x_on_cube'][0]
-
-    # Care must be taken here because a too-large initial step causes nlopt to move the starting point!
-    dist_to_bound = min(min(ub-x0), min(x0-lb))
-    assert dist_to_bound > np.finfo(np.float32).eps, "The distance to the boundary is too small for NLopt to handle"
-
-    if 'dist_to_bound_multiple' in gen_specs:
-        opt.set_initial_step(dist_to_bound*gen_specs['dist_to_bound_multiple'])
-    else:
-        opt.set_initial_step(dist_to_bound)
-
-    opt.set_maxeval(len(Run_H)+1)  # evaluate one more point
-    opt.set_min_objective(lambda x, grad: nlopt_obj_fun(x, grad, Run_H))
-    if 'xtol_rel' in gen_specs:
-        opt.set_xtol_rel(gen_specs['xtol_rel'])
-    if 'ftol_rel' in gen_specs:
-        opt.set_ftol_rel(gen_specs['ftol_rel'])
-    if 'xtol_abs' in gen_specs:
-        opt.set_xtol_abs(gen_specs['xtol_abs'])
-    if 'ftol_abs' in gen_specs:
-        opt.set_ftol_abs(gen_specs['ftol_abs'])
-
-    x_opt = opt.optimize(x0)
-    exit_code = opt.last_optimize_result()
-
-    if exit_code == 5:  # NLOPT code for exhausting budget of evaluations, so not at a minimum
-        exit_code = 0
-
-    return x_opt, exit_code
-
-
-def set_up_and_run_tao(Run_H, gen_specs):
-    """ Set up objective and runs PETSc on the comm_self communicator
-
-    Declares the appropriate syntax for our special objective function to read
-    through Run_H, sets the parameters and starting points for the run.
-    """
-    tao_comm = MPI.COMM_SELF
-    n = len(gen_specs['ub'])
-    m = len(Run_H['fvec'][0])
-
-    def pounders_obj_func(tao, X, F, Run_H):
-        F.array = look_in_history(X.array, Run_H, vector_return=True)
-        return F
-
-    # def blmvm_obj_func(tao, X, G, Run_H):
-    #     (f, grad) = look_in_history_fd_grad(X.array, Run_H)
-    #     G.array = grad
-    #     return f
-
-    # Create starting point, bounds, and tao object
-    x = PETSc.Vec().create(tao_comm)
-    x.setSizes(n)
-    x.setFromOptions()
-    x.array = Run_H['x_on_cube'][0]
-    lb = x.duplicate()
-    ub = x.duplicate()
-    lb.array = 0*np.ones(n)
-    ub.array = 1*np.ones(n)
-    tao = PETSc.TAO().create(tao_comm)
-    tao.setType(gen_specs['localopt_method'])
-
-    # if gen_specs['localopt_method'] == 'pounders':
-    f = PETSc.Vec().create(tao_comm)
-    f.setSizes(m)
-    f.setFromOptions()
-
-    delta_0 = gen_specs['dist_to_bound_multiple']*np.min([np.min(ub.array-x.array), np.min(x.array-lb.array)])
-
-    PETSc.Options().setValue('-tao_pounders_delta', str(delta_0))
-    # PETSc.Options().setValue('-pounders_subsolver_tao_type','bqpip')
-    if hasattr(tao, 'setResidual'):
-        tao.setResidual(lambda tao, x, f: pounders_obj_func(tao, x, f, Run_H), f)
-    else:
-        tao.setSeparableObjective(lambda tao, x, f: pounders_obj_func(tao, x, f, Run_H), f)
-    # elif gen_specs['localopt_method'] == 'blmvm':
-    #     g = PETSc.Vec().create(tao_comm)
-    #     g.setSizes(n)
-    #     g.setFromOptions()
-    #     tao.setObjectiveGradient(lambda tao, x, g: blmvm_obj_func(tao, x, g, Run_H))
-
-    # Set everything for tao before solving
-    PETSc.Options().setValue('-tao_max_funcs', str(len(Run_H)+1))
-    tao.setFromOptions()
-    tao.setVariableBounds((lb, ub))
-    # tao.setObjectiveTolerances(fatol=gen_specs['fatol'], frtol=gen_specs['frtol'])
-    # tao.setGradientTolerances(grtol=gen_specs['grtol'], gatol=gen_specs['gatol'])
-    tao.setTolerances(grtol=gen_specs['grtol'], gatol=gen_specs['gatol'])
-    tao.setInitial(x)
-
-    tao.solve(x)
-
-    x_opt = tao.getSolution().getArray()
-    exit_code = tao.getConvergedReason()
-    # print(exit_code)
-    # print(tao.view())
-    # print(x_opt)
-
-    # if gen_specs['localopt_method'] == 'pounders':
-    f.destroy()
-    # elif gen_specs['localopt_method'] == 'blmvm':
-    #     g.destroy()
-
-    lb.destroy()
-    ub.destroy()
-    x.destroy()
-    tao.destroy()
-
-    return x_opt, exit_code
-
-
 def decide_where_to_start_localopt(H, n, n_s, rk_const, mu=0, nu=0):
     """
     Finds points in the history that satisfy the conditions (S1-S5 and L1-L8) in
@@ -1187,40 +940,6 @@ def decide_where_to_start_localopt(H, n, n_s, rk_const, mu=0, nu=0):
     return start_inds
 
 
-def look_in_history(x, Run_H, vector_return=False):
-    """ See if Run['x_on_cube'][advance_local_run.pt_in_run] matches x,
-    returning f or fvec, or saves x to advance_local_run.x_new if every point in Run_H has been
-    checked.
-    """
-
-    if vector_return:
-        to_return = 'fvec'
-    else:
-        if 'grad' in Run_H.dtype.names:
-            to_return = ['f', 'grad']
-        else:
-            to_return = 'f'
-
-    if advance_local_run.pt_in_run < len(Run_H):
-        # Return the value in history to the localopt algorithm.
-        assert np.allclose(x, Run_H['x_on_cube'][advance_local_run.pt_in_run], rtol=1e-08, atol=1e-08), \
-            "History point does not match Localopt point"
-        f_out = Run_H[to_return][advance_local_run.pt_in_run]
-    else:
-        if advance_local_run.pt_in_run == len(Run_H):
-            # The history of points is exhausted. Save the requested point x to
-            # x_new. x_new will be returned to the manager.
-            advance_local_run.x_new[:] = x
-
-        # Just in case the local opt method requests more points after a new
-        # point has been identified.
-        f_out = Run_H[to_return][-1]
-
-    advance_local_run.pt_in_run += 1
-
-    return f_out
-
-
 def calc_rk(n, n_s, rk_const, lhs_divisions=0):
     """ Calculate the critical distance r_k """
 
@@ -1235,18 +954,6 @@ def calc_rk(n, n_s, rk_const, lhs_divisions=0):
 
     return r_k
 
-def count_samples(H,gen_specs):
-    if 'single_component_at_a_time' in gen_specs and gen_specs['single_component_at_a_time']:
-        # Get the pt_id for non-nan, returned points
-        pt_ids = H['pt_id'][np.logical_and(H['returned'], ~np.isnan(H['f_i']))]
-        _, counts = np.unique(pt_ids, return_counts=True)
-        n_s = np.sum(counts == gen_specs['components'])
-
-    else:
-        # Number of returned sampled points (excluding nans)
-        n_s = np.sum(np.logical_and.reduce((~np.isnan(H['f']), ~H['local_pt'], H['returned'])))
-
-    return n_s
 
 def initialize_APOSMM(H, gen_specs, libE_info):
     """

From 1e95d93628d4c2a5a7fb01805c01f74e72cddef8 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Sat, 3 Aug 2019 23:59:14 -0500
Subject: [PATCH 062/644] Trying to get blmvm

---
 libensemble/gen_funcs/persistent_aposmm.py | 51 ++++++++++++++++------
 1 file changed, 37 insertions(+), 14 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index b1bb17772..0c42d31d7 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -210,7 +210,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
     # {{{ setting the data needed by the local optimization method
 
-    if gen_specs['localopt_method'] in ['LD_MMA']:
+    if gen_specs['localopt_method'] in ['LD_MMA','blmvm']:
         fields_to_pass = ['f', 'grad']
     elif gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA',
             'LN_NELDERMEAD', 'pounders', 'scipy_COBYLA']:
@@ -390,7 +390,7 @@ def __init__(self, gen_specs, x0, parent_can_read, comm_queue, f0,
         if gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA',
                 'LN_NELDERMEAD', 'LD_MMA']:
             run_local_opt = run_local_nlopt
-        elif gen_specs['localopt_method'] in ['pounders']:
+        elif gen_specs['localopt_method'] in ['pounders','blmvm']:
             run_local_opt = run_local_tao
         elif gen_specs['localopt_method'] in ['scipy_COBYLA']:
             run_local_opt = run_local_scipy_opt
@@ -586,6 +586,24 @@ def tao_callback_function(tao, x, f, comm_queue, child_can_read, parent_can_read
     f.array[:] = f_recv
     return f
 
+def tao_callback_function_grad(tao, x, f, g, comm_queue, child_can_read, parent_can_read, gen_specs):
+    import ipdb; ipdb.set_trace()
+    comm_queue.put(x.array)
+    # print('[Child]: I just put x_on_cube =', x.array, flush=True)
+    # print('[Child]: Parent should no longer wait.', flush=True)
+    parent_can_read.set()
+    # print('[Child]: I have started waiting', flush=True)
+    child_can_read.wait()
+    # print('[Child]: Wohooo.. I am free folks', flush=True)
+    if gen_specs['localopt_method'] in ['blmvm']:
+        f_recv, grad_recv = comm_queue.get()
+        g.array[:] = grad_recv
+    else:
+        assert gen_specs['localopt_method'] in ['pounders']
+        f_recv, = comm_queue.get()
+    child_can_read.clear()
+    f.array[:] = f_recv
+    return f
 
 def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read,
         parent_can_read):
@@ -611,17 +629,22 @@ def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read,
     tao = PETSc.TAO().create(tao_comm)
     tao.setType(gen_specs['localopt_method'])
 
-    f = PETSc.Vec().create(tao_comm)
-    f.setSizes(m)
-    f.setFromOptions()
+    if gen_specs['localopt_method'] == 'pounders':
+        f = PETSc.Vec().create(tao_comm)
+        f.setSizes(m)
+        f.setFromOptions()
 
-    delta_0 = gen_specs['dist_to_bound_multiple']*np.min([np.min(ub.array-x.array), np.min(x.array-lb.array)])
+        tao.setResidual(lambda tao, x, f: tao_callback_function(tao, x, f,
+            comm_queue, child_can_read, parent_can_read, gen_specs), f)
 
-    PETSc.Options().setValue('-tao_pounders_delta', str(delta_0))
-    # PETSc.Options().setValue('-pounders_subsolver_tao_type','bqpip')
+    elif gen_specs['localopt_method'] == 'blmvm':
+        g = PETSc.Vec().create(tao_comm)
+        g.setSizes(n)
+        g.setFromOptions()
+        tao.setObjectiveGradient(lambda tao, x, f, g: tao_callback_function_grad(tao, x, f, g, comm_queue, child_can_read, parent_can_read, gen_specs))
 
-    tao.setResidual(lambda tao, x, f: tao_callback_function(tao, x, f,
-        comm_queue, child_can_read, parent_can_read, gen_specs), f)
+    delta_0 = gen_specs['dist_to_bound_multiple']*np.min([np.min(ub.array-x.array), np.min(x.array-lb.array)])
+    PETSc.Options().setValue('-tao_pounders_delta', str(delta_0))
 
     # Set everything for tao before solving
     # FIXME: Hard-coding 100 as the max funcs as couldn't find any other
@@ -643,10 +666,10 @@ def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read,
     # print(tao.view())
     # print(x_opt)
 
-    # if gen_specs['localopt_method'] == 'pounders':
-    f.destroy()
-    # elif gen_specs['localopt_method'] == 'blmvm':
-    #     g.destroy()
+    if gen_specs['localopt_method'] == 'pounders':
+        f.destroy()
+    elif gen_specs['localopt_method'] == 'blmvm':
+        g.destroy()
 
     lb.destroy()
     ub.destroy()

From 95b7e63472c8a7cd6dcb51f0c7612eb8dff31adc Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Mon, 5 Aug 2019 07:10:50 -0500
Subject: [PATCH 063/644] Trying blmvm

---
 .../regression_tests/test_6-hump_camel_persistent_aposmm.py     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index 606080994..8a95151b4 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -48,7 +48,7 @@
              'batch_mode': True,
              'initial_sample_size': 100,
              'sample_points': np.round(minima, 1),
-             'localopt_method': 'LD_MMA',
+             'localopt_method': 'blmvm',
              'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
              'xtol_rel': 1e-3,
              'num_active_gens': 1,

From 00bfb923a9bc4e24d696ee87da47dc61c56a4a7e Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 6 Aug 2019 04:01:38 -0500
Subject: [PATCH 064/644] flake8

---
 .../alloc_funcs/start_only_persistent.py      |   2 +-
 libensemble/gen_funcs/persistent_aposmm.py    | 142 ++++++++----------
 .../test_6-hump_camel_persistent_aposmm.py    |   5 +-
 3 files changed, 70 insertions(+), 79 deletions(-)

diff --git a/libensemble/alloc_funcs/start_only_persistent.py b/libensemble/alloc_funcs/start_only_persistent.py
index c1a35e228..4b3543b60 100644
--- a/libensemble/alloc_funcs/start_only_persistent.py
+++ b/libensemble/alloc_funcs/start_only_persistent.py
@@ -21,7 +21,7 @@ def only_persistent_gens(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     # returned, give them back to i. Otherwise, give nothing to i
     for i in avail_worker_ids(W, persistent=True):
         gen_inds = (H['gen_worker'] == i)
-        if np.any(np.logical_and(H['returned'][gen_inds],~H['given_back'][gen_inds])):
+        if np.any(np.logical_and(H['returned'][gen_inds], ~H['given_back'][gen_inds])):
             last_time_gen_gave_batch = np.max(H['gen_time'][gen_inds])
             inds_of_last_batch_from_gen = H['sim_id'][gen_inds][H['gen_time'][gen_inds] == last_time_gen_gave_batch]
             gen_work(Work, i,
diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index a64fe3cb8..a079d5bca 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -4,21 +4,17 @@
 described in detail in the paper
 `https://doi.org/10.1007/s12532-017-0131-4 <https://doi.org/10.1007/s12532-017-0131-4>`_
 """
-__all__ = ['aposmm_logic', 'initialize_APOSMM',
-           'decide_where_to_start_localopt', 'update_history_dist']
+__all__ = ['initialize_APOSMM', 'decide_where_to_start_localopt', 'update_history_dist']
 
 import sys
-import pickle
 import traceback
 import numpy as np
-from scipy.spatial.distance import cdist, pdist, squareform
-from scipy import optimize as scipy_optimize
-from petsc4py import PETSc
+from scipy.spatial.distance import cdist
+from scipy import optimize as sp_opt
+from petsc5py import PETSc
 
 from mpi4py import MPI
 
-from numpy.lib.recfunctions import merge_arrays
-
 from math import log, gamma, pi, sqrt
 
 import nlopt
@@ -202,7 +198,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
     # }}}
 
-    n, n_s, c_flag, rk_const, mu, nu, total_runs, comm, local_H = initialize_APOSMM(H, gen_specs, libE_info)
+    n, n_s, c_flag, rk_const, ld, mu, nu, total_runs, comm, local_H = initialize_APOSMM(H, gen_specs, libE_info)
 
     sim_id_to_child_indices = {}
     child_id_to_run_id = {}
@@ -210,47 +206,46 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
     # {{{ setting the data needed by the local optimization method
 
-    if gen_specs['localopt_method'] in ['LD_MMA','blmvm']:
+    if gen_specs['localopt_method'] in ['LD_MMA', 'blmvm']:
         fields_to_pass = ['f', 'grad']
     elif gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA',
-            'LN_NELDERMEAD', 'pounders', 'scipy_COBYLA']:
+                                          'LN_NELDERMEAD', 'pounders', 'scipy_COBYLA']:
         fields_to_pass = ['f']
     else:
-        raise NotImplementedError("Unknown local optimization method "
-                "'{}'.".format(gen_specs['localopt_method']))
+        raise NotImplementedError("Unknown local optimization method " "'{}'.".format(gen_specs['localopt_method']))
 
     # }}}
 
     for _ in range(gen_specs['initial_sample_size']):
-        send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
-                sim_id_to_child_indices)
+        send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag,
+                                             comm, local_H, sim_id_to_child_indices)
 
     tag = None
     max_active_runs = gen_specs.get('max_active_runs', np.inf)
     waiting_starting_inds = []
-    O = np.empty(0, dtype=gen_specs['out'])
+
     while 1:
         tag, Work, calc_in = get_mgr_worker_msg(comm)
 
         if calc_in:
             if fields_to_pass == ['f', 'grad']:
-                (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in
+                (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv), = calc_in
                 data_to_give_processes = (f_x_recv, grad_f_x_recv)
             else:
                 assert(fields_to_pass == ['f'])
                 if len(calc_in[0]) == 3:
-                    (x_recv, f_x_recv, sim_id_recv),  = calc_in
+                    (x_recv, f_x_recv, sim_id_recv), = calc_in
                 else:
                     # FIXME: *BIG BIG!*, even if we are passing grad_f even
                     # though we are not using it.
-                    (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv),  = calc_in
+                    (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv), = calc_in
                 data_to_give_processes = (f_x_recv, )
 
         if tag in [STOP_TAG, PERSIS_STOP]:
             # FIXME: This has to be a clean exit.
 
             print('[Parent]: The optimal points are:\n',
-                    local_H[np.where(local_H['local_min'])]['x'], flush=True)
+                  local_H[np.where(local_H['local_min'])]['x'], flush=True)
 
             for p in local_opters:
                 if p.is_running:
@@ -264,8 +259,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 x_new = local_opters[child_idx].iterate(*data_to_give_processes)
                 if isinstance(x_new, ConvergedMsg):
                     x_opt = x_new.x
-                    update_history_optimal(x_opt, local_H,
-                            run_order[child_id_to_run_id[child_idx]])
+                    update_history_optimal(x_opt, local_H, run_order[child_id_to_run_id[child_idx]])
 
                     if waiting_starting_inds:
                         ind = waiting_starting_inds[0]
@@ -274,9 +268,10 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                         # {{{ initing a local opt run
 
                         local_opter = LocalOptInterfacer(gen_specs,
-                                local_H[ind]['x_on_cube'],
-                                parent_can_read_from_queue, comm_queue,
-                                local_H[ind]['f'], grad_f_x_recv if 'grad' in fields_to_pass else None)
+                                                         local_H[ind]['x_on_cube'],
+                                                         parent_can_read_from_queue, comm_queue,
+                                                         local_H[ind]['f'], grad_f_x_recv if 'grad' in
+                                                         fields_to_pass else None)
                         local_opters.append(local_opter)
                         x_new = local_opter.iterate(*local_H[ind][fields_to_pass])
                         add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
@@ -296,7 +291,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                         send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
                     else:
                         send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
-                            sim_id_to_child_indices)
+                                                             sim_id_to_child_indices)
                 else:
                     add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
                     assert np.allclose(local_H[-1]['x_on_cube'], x_new)
@@ -312,7 +307,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 continue
             n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
 
-            starting_inds = decide_where_to_start_localopt(local_H, n, n_s, rk_const, mu, nu)
+            starting_inds = decide_where_to_start_localopt(local_H, n, n_s, rk_const, ld, mu, nu)
 
             for ind in starting_inds:
 
@@ -323,9 +318,9 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     # {{{ initing a local opt run
 
                     local_opter = LocalOptInterfacer(gen_specs,
-                            local_H[ind]['x_on_cube'],
-                            parent_can_read_from_queue, comm_queue,
-                            local_H[ind]['f'], grad_f_x_recv if 'grad' in fields_to_pass else None)
+                                                     local_H[ind]['x_on_cube'],
+                                                     parent_can_read_from_queue, comm_queue,
+                                                     local_H[ind]['f'], grad_f_x_recv if 'grad' in fields_to_pass else None)
                     local_opters.append(local_opter)
                     x_new = local_opter.iterate(*local_H[ind][fields_to_pass])
 
@@ -349,7 +344,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
             if len(starting_inds) == 0 and len(waiting_starting_inds) == 0:
                 send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
-                        sim_id_to_child_indices)
+                                                     sim_id_to_child_indices)
 
     comm_queue.close()
     comm_queue.join_thread()
@@ -357,14 +352,13 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     for local_opter in local_opters:
         if local_opter.is_running:
             raise RuntimeError("[Parent]: Atleast one child process is still active, even after"
-                    " killing all the children.")
+                               " killing all the children.")
 
     return local_H, persis_info, tag
 
 
 class LocalOptInterfacer(object):
-    def __init__(self, gen_specs, x0, parent_can_read, comm_queue, f0,
-            grad0=None):
+    def __init__(self, gen_specs, x0, parent_can_read, comm_queue, f0, grad0=None):
         """
         :param x0: A numpy array of the initial guess solution. This guess
             should be scaled to a unit cube.
@@ -387,25 +381,22 @@ def __init__(self, gen_specs, x0, parent_can_read, comm_queue, f0,
 
         # {{{ setting the local optimization method
 
-        if gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA',
-                'LN_NELDERMEAD', 'LD_MMA']:
+        if gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA', 'LN_NELDERMEAD', 'LD_MMA']:
             run_local_opt = run_local_nlopt
-        elif gen_specs['localopt_method'] in ['pounders','blmvm']:
+        elif gen_specs['localopt_method'] in ['pounders', 'blmvm']:
             run_local_opt = run_local_tao
         elif gen_specs['localopt_method'] in ['scipy_COBYLA']:
             run_local_opt = run_local_scipy_opt
         else:
             raise NotImplementedError("Unknown local optimization method "
-                    "'{}'.".format(gen_specs['localopt_method']))
+                                      "'{}'.".format(gen_specs['localopt_method']))
 
         # }}}
 
         self.parent_can_read.clear()
         self.process = Process(target=run_local_opt, args=(gen_specs,
-            comm_queue,
-            x0, f0,
-            self.child_can_read,
-            parent_can_read))
+                               comm_queue, x0, f0, self.child_can_read,
+                               parent_can_read))
 
         self.process.start()
         self.is_running = True
@@ -443,8 +434,7 @@ def destroy(self):
             if self.grad0 is None:
                 self.comm_queue.put((0*np.ones_like(self.f0),))
             else:
-                self.comm_queue.put((0*np.ones_like(self.f0),
-                    np.zeros_like(self.grad0)))
+                self.comm_queue.put((0*np.ones_like(self.f0), np.zeros_like(self.grad0)))
 
             self.child_can_read.set()
             self.parent_can_read.wait()
@@ -457,7 +447,7 @@ def destroy(self):
 
 # {{{ NLOPT for local opt
 
-def nlopt_callback_function(x, grad, comm_queue, child_can_read, parent_can_read, gen_specs):
+def nlopt_callback_fun(x, grad, comm_queue, child_can_read, parent_can_read, gen_specs):
     comm_queue.put(x)
     parent_can_read.set()
     child_can_read.wait()
@@ -466,7 +456,7 @@ def nlopt_callback_function(x, grad, comm_queue, child_can_read, parent_can_read
         grad[:] = grad_recv
     else:
         assert gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA',
-                'LN_COBYLA', 'LN_NELDERMEAD', 'LD_MMA']
+                                                'LN_COBYLA', 'LN_NELDERMEAD', 'LD_MMA']
         f_recv, = comm_queue.get()
 
     child_can_read.clear()
@@ -474,8 +464,7 @@ def nlopt_callback_function(x, grad, comm_queue, child_can_read, parent_can_read
     return f_recv
 
 
-def run_local_nlopt(gen_specs, comm_queue, x0, f0, child_can_read,
-        parent_can_read):
+def run_local_nlopt(gen_specs, comm_queue, x0, f0, child_can_read, parent_can_read):
     # print('[Child]: Started local opt at {}.'.format(x0), flush=True)
     n = len(gen_specs['ub'])
 
@@ -498,8 +487,9 @@ def run_local_nlopt(gen_specs, comm_queue, x0, f0, child_can_read,
     # FIXME: Setting max evaluations = 100
     opt.set_maxeval(100)
 
-    opt.set_min_objective(lambda x, grad: nlopt_callback_function(x, grad,
-        comm_queue, child_can_read, parent_can_read, gen_specs))
+    opt.set_min_objective(lambda x, grad: nlopt_callback_fun(x, grad,
+                          comm_queue, child_can_read, parent_can_read,
+                          gen_specs))
 
     if 'xtol_rel' in gen_specs:
         opt.set_xtol_rel(gen_specs['xtol_rel'])
@@ -510,7 +500,7 @@ def run_local_nlopt(gen_specs, comm_queue, x0, f0, child_can_read,
     if 'ftol_abs' in gen_specs:
         opt.set_ftol_abs(gen_specs['ftol_abs'])
 
-    #FIXME: Do we need to do something of the final 'x_opt'?
+    # FIXME: Do we need to do something of the final 'x_opt'?
     # print('[Child]: Started my optimization', flush=True)
     x_opt = opt.optimize(x0)
     # print('[Child]: I have converged.', flush=True)
@@ -522,7 +512,7 @@ def run_local_nlopt(gen_specs, comm_queue, x0, f0, child_can_read,
 
 # {{{ SciPy optimization
 
-def scipy_callback_function(x, comm_queue, child_can_read, parent_can_read, gen_specs):
+def scipy_callback_fun(x, comm_queue, child_can_read, parent_can_read, gen_specs):
     comm_queue.put(x)
     # print('[Child]: Parent should no longer wait.', flush=True)
     parent_can_read.set()
@@ -534,8 +524,7 @@ def scipy_callback_function(x, comm_queue, child_can_read, parent_can_read, gen_
     return f_x_recv
 
 
-def run_local_scipy_opt(gen_specs, comm_queue, x0, f0, child_can_read,
-        parent_can_read):
+def run_local_scipy_opt(gen_specs, comm_queue, x0, f0, child_can_read, parent_can_read):
 
     # Construct the bounds in the form of constraints
     cons = []
@@ -549,9 +538,9 @@ def run_local_scipy_opt(gen_specs, comm_queue, x0, f0, child_can_read,
 
     method = gen_specs['localopt_method'][6:]
     # print('[Child]: Started my optimization', flush=True)
-    res = scipy_optimize.minimize(lambda x: scipy_callback_function(x,
-        comm_queue, child_can_read, parent_can_read, gen_specs), x0,
-        method=method, options={'maxiter': 100, 'tol': gen_specs['tol']})
+    res = sp_opt.minimize(lambda x: scipy_callback_fun(x, comm_queue,
+                          child_can_read, parent_can_read, gen_specs), x0,
+                          method=method, options={'maxiter': 100, 'tol': gen_specs['tol']})
 
     if res['status'] == 2:  # SciPy code for exhausting budget of evaluations, so not at a minimum
         exit_code = 0
@@ -563,6 +552,7 @@ def run_local_scipy_opt(gen_specs, comm_queue, x0, f0, child_can_read,
     x_opt = res['x']
 
     # FIXME: Need to do something with the exit codes.
+    print(exit_code)
 
     # print('[Child]: I have converged.', flush=True)
     comm_queue.put(ConvergedMsg(x_opt))
@@ -573,7 +563,7 @@ def run_local_scipy_opt(gen_specs, comm_queue, x0, f0, child_can_read,
 
 # {{{ TAO routines for local opt
 
-def tao_callback_function(tao, x, f, comm_queue, child_can_read, parent_can_read, gen_specs):
+def tao_callback_fun(tao, x, f, comm_queue, child_can_read, parent_can_read, gen_specs):
     comm_queue.put(x.array)
     # print('[Child]: I just put x_on_cube =', x.array, flush=True)
     # print('[Child]: Parent should no longer wait.', flush=True)
@@ -581,13 +571,14 @@ def tao_callback_function(tao, x, f, comm_queue, child_can_read, parent_can_read
     # print('[Child]: I have started waiting', flush=True)
     child_can_read.wait()
     # print('[Child]: Wohooo.. I am free folks', flush=True)
-    f_recv,  = comm_queue.get()
+    f_recv, = comm_queue.get()
     child_can_read.clear()
     f.array[:] = f_recv
     return f
 
-def tao_callback_function_grad(tao, x, f, g, comm_queue, child_can_read, parent_can_read, gen_specs):
-    import ipdb; ipdb.set_trace()
+
+def tao_callback_fun_grad(tao, x, f, g, comm_queue, child_can_read, parent_can_read, gen_specs):
+
     comm_queue.put(x.array)
     # print('[Child]: I just put x_on_cube =', x.array, flush=True)
     # print('[Child]: Parent should no longer wait.', flush=True)
@@ -605,8 +596,8 @@ def tao_callback_function_grad(tao, x, f, g, comm_queue, child_can_read, parent_
     f.array[:] = f_recv
     return f
 
-def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read,
-        parent_can_read):
+
+def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read, parent_can_read):
 
     assert isinstance(x0, np.ndarray)
 
@@ -634,14 +625,13 @@ def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read,
         f.setSizes(m)
         f.setFromOptions()
 
-        tao.setResidual(lambda tao, x, f: tao_callback_function(tao, x, f,
-            comm_queue, child_can_read, parent_can_read, gen_specs), f)
+        tao.setResidual(lambda tao, x, f: tao_callback_fun(tao, x, f, comm_queue, child_can_read, parent_can_read, gen_specs), f)
 
     elif gen_specs['localopt_method'] == 'blmvm':
         g = PETSc.Vec().create(tao_comm)
         g.setSizes(n)
         g.setFromOptions()
-        tao.setObjectiveGradient(lambda tao, x, f, g: tao_callback_function_grad(tao, x, f, g, comm_queue, child_can_read, parent_can_read, gen_specs))
+        tao.setObjectiveGradient(lambda tao, x, f, g: tao_callback_fun_grad(tao, x, f, g, comm_queue, child_can_read, parent_can_read, gen_specs))
 
     delta_0 = gen_specs['dist_to_bound_multiple']*np.min([np.min(ub.array-x.array), np.min(x.array-lb.array)])
     PETSc.Options().setValue('-tao_pounders_delta', str(delta_0))
@@ -662,7 +652,9 @@ def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read,
 
     x_opt = tao.getSolution().getArray()
     exit_code = tao.getConvergedReason()
-    # print(exit_code)
+
+    # FIXME: Need to do something with the exit codes.
+    print(exit_code)
     # print(tao.view())
     # print(x_opt)
 
@@ -676,7 +668,7 @@ def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read,
     x.destroy()
     tao.destroy()
 
-    #FIXME: Do we need to do something of the final 'x_opt'?
+    # FIXME: Do we need to do something of the final 'x_opt'?
     # print('[Child]: I have converged.', flush=True)
     comm_queue.put(ConvergedMsg(x_opt))
     parent_can_read.set()
@@ -819,7 +811,6 @@ def update_history_dist(H, n, gen_specs, c_flag):
             #         H['worse_within_rk'][H['dist_to_all'] > r_k] = False
 
 
-
 def update_history_optimal(x_opt, H, run_inds):
     """
     Updated the history after any point has been declared a local minimum
@@ -852,7 +843,7 @@ def update_history_optimal(x_opt, H, run_inds):
     H['num_active_runs'][run_inds] -= 1
 
 
-def decide_where_to_start_localopt(H, n, n_s, rk_const, mu=0, nu=0):
+def decide_where_to_start_localopt(H, n, n_s, rk_const, ld=0, mu=0, nu=0):
     """
     Finds points in the history that satisfy the conditions (S1-S5 and L1-L8) in
     Table 1 of the `APOSMM paper <https://doi.org/10.1007/s12532-017-0131-4>`_
@@ -894,7 +885,7 @@ def decide_where_to_start_localopt(H, n, n_s, rk_const, mu=0, nu=0):
         ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
     """
 
-    r_k = calc_rk(n, n_s, rk_const)
+    r_k = calc_rk(n, n_s, rk_const, ld)
 
     if nu > 0:
         test_2_through_5 = np.logical_and.reduce((
@@ -1020,8 +1011,8 @@ def initialize_APOSMM(H, gen_specs, libE_info):
 
     comm = libE_info['comm']
 
-    local_H_fields = [('f',float),
-                      ('grad',float,n),
+    local_H_fields = [('f', float),
+                      ('grad', float, n),
                       ('x', float, n),
                       ('x_on_cube', float, n),
                       ('priority', float),
@@ -1043,11 +1034,10 @@ def initialize_APOSMM(H, gen_specs, libE_info):
 
     local_H = np.empty(0, dtype=local_H_fields)
 
-    return n, n_s, c_flag, rk_c, mu, nu, total_runs, comm, local_H
+    return n, n_s, c_flag, rk_c, ld, mu, nu, total_runs, comm, local_H
 
 
-def send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
-        sim_id_to_child_indices):
+def send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H, sim_id_to_child_indices):
     sampled_points = persis_info['rand_stream'].uniform(0, 1, (1, n))
     add_to_local_H(local_H, sampled_points, gen_specs, c_flag, on_cube=True)
     assert local_H['sim_id'][-1] not in sim_id_to_child_indices
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index 8a95151b4..f6fc3c0c5 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -41,7 +41,8 @@
              'out': [('f', float), ('grad', float, n)]}
 
 gen_out = [('x', float, n), ('x_on_cube', float, n), ('sim_id', int),
-        ('local_min', bool)]
+           ('local_min', bool)]
+
 gen_specs = {'gen_f': gen_f,
              'in': [],
              'out': gen_out,
@@ -74,4 +75,4 @@
 if is_master:
     print('[Manager]:', H[np.where(H['local_min'])]['x'])
     print('[Manager]: Time taken =', time() - start_time, flush=True)
-    # save_libE_output(H, persis_info, __file__, nworkers)
+    save_libE_output(H, persis_info, __file__, nworkers)

From 44d8881da98e61cd2905a1ad20cc454e5266ccd7 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 6 Aug 2019 06:41:11 -0500
Subject: [PATCH 065/644] Fixing typo

---
 libensemble/gen_funcs/persistent_aposmm.py                      | 2 +-
 .../regression_tests/test_6-hump_camel_persistent_aposmm.py     | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index a079d5bca..a5600c132 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -11,7 +11,7 @@
 import numpy as np
 from scipy.spatial.distance import cdist
 from scipy import optimize as sp_opt
-from petsc5py import PETSc
+from petsc4py import PETSc
 
 from mpi4py import MPI
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index f6fc3c0c5..c6d0a1dc5 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -49,7 +49,7 @@
              'batch_mode': True,
              'initial_sample_size': 100,
              'sample_points': np.round(minima, 1),
-             'localopt_method': 'blmvm',
+             'localopt_method': 'LD_MMA',
              'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
              'xtol_rel': 1e-3,
              'num_active_gens': 1,

From 31aaa40d3bde953d7acd7a96db29512c7c80caad Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 7 Aug 2019 03:48:48 -0500
Subject: [PATCH 066/644] Updating travis file

---
 .travis.yml | 78 +++++++++++++++++++++++++++++++++--------------------
 1 file changed, 49 insertions(+), 29 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 9aa0d66a7..8dacfbeda 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -6,57 +6,71 @@ python:
   - 3.5
   - 3.6
   - 3.7
-  
+
 os: linux
 
 env:
   global:
     - HYDRA_LAUNCHER=fork
-    - OMPI_MCA_rmaps_base_oversubscribe=yes  
+    - OMPI_MCA_rmaps_base_oversubscribe=yes
   matrix:
     - MPI=mpich
     #- MPI=openmpi
 
-#matrix:
+matrix:
+  include:
+    - os: osx
+      osx_image: xcode11
+      env: MPI=mpich PY=3
+      language: generic
+      python: 3
+
+
+# matrix:
 #  allow_failures:
 #    - env: MPI=openmpi
-    
-addons:
-  apt:
-    packages:
-      - gfortran
-      - libblas-dev
-      - liblapack-dev
-    
-cache: 
+
+# addons:
+#   apt:
+#     packages:
+#       - gfortran
+#       - libblas-dev
+#       - liblapack-dev
+
+cache:
   pip: true
   apt: true
 
 # Setup Miniconda
 before_install:
-  # Do this conditionally because it saves some downloading if the version is the same.
-  - if [[ "$TRAVIS_PYTHON_VERSION" == "2.7" ]]; then
-      wget https://repo.continuum.io/miniconda/Miniconda2-latest-Linux-x86_64.sh -O miniconda.sh;
+  - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
+      wget https://repo.continuum.io/miniconda/Miniconda3-4.6.14-MacOSX-x86_64.sh -O miniconda.sh;
     else
-      wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh;
+      wget https://repo.continuum.io/miniconda/Miniconda3-4.6.14-Linux-x86_64.sh -O miniconda.sh;
     fi
   - bash miniconda.sh -b -p $HOME/miniconda
   - export PATH="$HOME/miniconda/bin:$PATH"
   - hash -r
   - conda config --set always_yes yes --set changeps1 no
-  - conda update -q -y conda
+  #- conda update -q -y conda
   - conda info -a # For debugging any issues with conda
-  - conda config --add channels conda-forge  
-  - conda create --yes --name condaenv python=$TRAVIS_PYTHON_VERSION 
+  - conda config --add channels conda-forge
+  - conda create --yes --name condaenv python=$TRAVIS_PYTHON_VERSION
   - source activate condaenv
 
 install:
-  - conda install gcc_linux-64
-  - conda install $MPI
-  - conda install --no-update-deps scipy # includes numpy
-  - conda install --no-update-deps mpi4py
-  - conda install petsc4py petsc
-  - conda install --no-update-deps nlopt
+  - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
+        wget https://github.com/phracker/MacOSX-SDKs/releases/download/10.13/MacOSX10.13.sdk.tar.xz;
+        mkdir ../sdk; tar xf MacOSX10.13.sdk.tar.xz -C ../sdk;
+        COMPILERS=clang_osx-64;
+        MUMPS=mumps-mpi=5.1.2=haf446c3_1007;
+    else
+        COMPILERS=gcc_linux-64;
+        MUMPS=mumps-mpi=5.1.2=h5bebb2f_1007;
+    fi
+  - conda install $COMPILERS
+  #S- conda install nlopt petsc4py petsc mpi4py scipy $MPI
+  - conda install nlopt petsc4py petsc $MUMPS mpi4py scipy $MPI
   # pip install these as the conda installs downgrade pytest on python3.4
   - pip install flake8
   - pip install pytest
@@ -65,12 +79,18 @@ install:
   - pip install mock
   - pip install coveralls
   # For confirmation of MPI library being used.
-  - python conda/find_mpi.py #locate compilers
-  - mpiexec --version #Show MPI library details
+  - python conda/find_mpi.py # locate compilers
+  - mpiexec --version # Show MPI library details
   - pip install -e .
 
+
 before_script:
-  - flake8 libensemble 
+  - flake8 libensemble
+  # Set conda compilers to use new SDK instead of Travis default.
+  - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
+        echo "export CONDA_BUILD_SYSROOT=/Users/travis/build/Libensemble/sdk/MacOSX10.13.sdk" > setenv.sh;
+        source setenv.sh;
+    fi
 
 # Run test (-z show output)
 script:
@@ -78,7 +98,7 @@ script:
 
 # Coverage
 after_success:
-  - mv libensemble/tests/.cov* . 
+  - mv libensemble/tests/.cov* .
   - coveralls
 
 after_failure:

From 882064856e53bfffa595699c8315d2409edd289e Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 8 Aug 2019 11:34:11 -0500
Subject: [PATCH 067/644] Modifies .travis.yml to include postgresql service.
 Adds line for balsam-setup. Adds balsam-setup script to generate balsam db
 and initialize. Adds regression test that modifies balsam, then submits
 script as job to balsam

---
 .travis.yml                                   |   4 +
 conda/balsam-setup.sh                         |  17 +++
 ...script_test_jobcontroller_hworld_balsam.py | 103 ++++++++++++++++++
 .../test_jobcontroller_hworld_balsam.py       |  36 ++++++
 4 files changed, 160 insertions(+)
 create mode 100755 conda/balsam-setup.sh
 create mode 100644 libensemble/tests/regression_tests/script_test_jobcontroller_hworld_balsam.py
 create mode 100644 libensemble/tests/regression_tests/test_jobcontroller_hworld_balsam.py

diff --git a/.travis.yml b/.travis.yml
index 8dacfbeda..4487d1883 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -25,6 +25,8 @@ matrix:
       language: generic
       python: 3
 
+services:
+    - postgresql
 
 # matrix:
 #  allow_failures:
@@ -72,6 +74,7 @@ install:
   #S- conda install nlopt petsc4py petsc mpi4py scipy $MPI
   - conda install nlopt petsc4py petsc $MUMPS mpi4py scipy $MPI
   # pip install these as the conda installs downgrade pytest on python3.4
+  - pip install balsam-flow
   - pip install flake8
   - pip install pytest
   - pip install pytest-cov
@@ -86,6 +89,7 @@ install:
 
 before_script:
   - flake8 libensemble
+  - ./conda/balsam-setup.sh
   # Set conda compilers to use new SDK instead of Travis default.
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
         echo "export CONDA_BUILD_SYSROOT=/Users/travis/build/Libensemble/sdk/MacOSX10.13.sdk" > setenv.sh;
diff --git a/conda/balsam-setup.sh b/conda/balsam-setup.sh
new file mode 100755
index 000000000..af614f35e
--- /dev/null
+++ b/conda/balsam-setup.sh
@@ -0,0 +1,17 @@
+balsam init ~/test-balsam
+source balsamactivate test-balsam
+
+export EXE=script_test_jobcontroller_hworld_balsam.py
+export NUM_WORKERS=2
+export WORKFLOW_NAME=libe_test-balsam
+export SCRIPT_ARGS=$NUM_WORKERS
+export LIBE_WALLCLOCK=3
+export THIS_DIR=$PWD
+export SCRIPT_BASENAME=${EXE%.*}
+
+balsam rm apps --all --force
+balsam rm jobs --all --force
+
+balsam app --name $SCRIPT_BASENAME.app --exec $EXE --desc "Run $SCRIPT_BASENAME"
+
+balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --args $SCRIPT_ARGS --wall-time-minutes $LIBE_WALLCLOCK --num-nodes 1 --ranks-per-node $((NUM_WORKERS+1)) --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
diff --git a/libensemble/tests/regression_tests/script_test_jobcontroller_hworld_balsam.py b/libensemble/tests/regression_tests/script_test_jobcontroller_hworld_balsam.py
new file mode 100644
index 000000000..5bd61c26e
--- /dev/null
+++ b/libensemble/tests/regression_tests/script_test_jobcontroller_hworld_balsam.py
@@ -0,0 +1,103 @@
+# This script is meant to be launched by Balsam
+
+import os
+import numpy as np
+import multiprocessing
+
+from libensemble.message_numbers import WORKER_DONE, WORKER_KILL_ON_ERR, WORKER_KILL_ON_TIMEOUT, JOB_FAILED
+from libensemble.libE import libE
+from libensemble.sim_funcs.job_control_hworld import job_control_hworld as sim_f
+from libensemble.gen_funcs.uniform_sampling import uniform_random_sample as gen_f
+from libensemble.tests.regression_tests.common import build_simfunc, parse_args, per_worker_stream
+
+from mpi4py import MPI
+
+nworkers = MPI.COMM_WORLD.Get_size() - 1
+is_master = MPI.COMM_WORLD.Get_rank() == 0
+libE_specs = {'comm': MPI.COMM_WORLD, 'color': 0, 'comms': 'mpi'}
+
+cores_per_job = 1
+logical_cores = multiprocessing.cpu_count()
+cores_all_jobs = nworkers*cores_per_job
+
+if cores_all_jobs > logical_cores:
+    use_auto_resources = False
+    mess_resources = 'Oversubscribing - auto_resources set to False'
+else:
+    use_auto_resources = True
+    mess_resources = 'Auto_resources set to True'
+
+if is_master:
+    print('\nCores req: {} Cores avail: {}\n  {}\n'.format(cores_all_jobs, logical_cores, mess_resources))
+
+sim_app = './my_simjob.x'
+if not os.path.isfile(sim_app):
+    build_simfunc()
+
+from libensemble.balsam_controller import BalsamJobController
+jobctrl = BalsamJobController(auto_resources=use_auto_resources)
+
+jobctrl.register_calc(full_path=sim_app, calc_type='sim')
+
+sim_specs = {'sim_f': sim_f,
+             'in': ['x'],
+             'out': [('f', float), ('cstat', int)],
+             'save_every_k': 400,
+             'cores': cores_per_job}
+
+gen_specs = {'gen_f': gen_f,
+             'in': ['sim_id'],
+             'out': [('x', float, (2,))],
+             'lb': np.array([-3, -2]),
+             'ub': np.array([3, 2]),
+             'gen_batch_size': nworkers,
+             'batch_mode': True,
+             'num_active_gens': 1,
+             'save_every_k': 20}
+
+persis_info = per_worker_stream({}, nworkers + 1)
+
+exit_criteria = {'elapsed_wallclock_time': 10}
+
+# Perform the run
+H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
+                            libE_specs=libE_specs)
+
+if is_master:
+    print('\nChecking expected job status against Workers ...\n')
+
+    # Expected list: Last is zero as will not be entered into H array on
+    # manager kill - but should show in the summary file.
+    # Repeat expected lists nworkers times and compare with list of status's
+    # received from workers
+    calc_status_list_in = np.asarray([WORKER_DONE, WORKER_KILL_ON_ERR, WORKER_KILL_ON_TIMEOUT, JOB_FAILED, 0])
+    calc_status_list = np.repeat(calc_status_list_in, nworkers)
+
+    # For debug
+    print("Expecting: {}".format(calc_status_list))
+    print("Received:  {}\n".format(H['cstat']))
+
+    assert np.array_equal(H['cstat'], calc_status_list), "Error - unexpected calc status. Received: " + str(H['cstat'])
+
+    # Check summary file:
+    print('Checking expected job status against job summary file ...\n')
+
+    calc_desc_list_in = ['Completed', 'Worker killed job on Error',
+                         'Worker killed job on Timeout', 'Job Failed',
+                         'Manager killed on finish']
+
+    # Repeat N times for N workers and insert Completed at start for generator
+    calc_desc_list = ['Completed'] + calc_desc_list_in*nworkers
+    # script_name = os.path.splitext(os.path.basename(__file__))[0]
+    # short_name = script_name.split("test_", 1).pop()
+    # summary_file_name = short_name + '.libe_summary.txt'
+    # with open(summary_file_name,'r') as f:
+    #     i=0
+    #     for line in f:
+    #         if "Status:" in line:
+    #             _, file_status = line.partition("Status:")[::2]
+    #             print("Expected: {}   Filestatus: {}".format(calc_desc_list[i], file_status.strip()))
+    #             assert calc_desc_list[i] == file_status.strip(), "Status does not match file"
+    #             i+=1
+
+    print("\n\n\nRun completed.")
diff --git a/libensemble/tests/regression_tests/test_jobcontroller_hworld_balsam.py b/libensemble/tests/regression_tests/test_jobcontroller_hworld_balsam.py
new file mode 100644
index 000000000..0d2126b42
--- /dev/null
+++ b/libensemble/tests/regression_tests/test_jobcontroller_hworld_balsam.py
@@ -0,0 +1,36 @@
+import subprocess
+import os
+import balsam
+
+# Balsam is meant for HPC systems that commonly distribute jobs across many
+#   nodes. Due to the nature of testing Balsam on local or CI systems which usually
+#   only contain a single node, we need to change Balsam's default worker setup
+#   so multiple workers can be run on a single node (until this feature is [hopefully] added!).
+#   For our purposes, we append ten workers to Balsam's WorkerGroup
+
+
+### MODIFY BALSAM WORKERGROUP ###
+
+home = os.getcwd()
+balsam_worker_path = os.path.dirname(balsam.__file__) + '/launcher'
+os.chdir(balsam_worker_path)
+
+with open('worker.py', 'r') as f:
+    lines = f.readlines()
+
+if lines[-3] != "        for idx in range(10):\n":
+    lines = lines[:-2] # Will re-add these lines
+    lines.extend(["        for idx in range(10):\n",
+                  "            w = Worker(1, host_type='DEFAULT', num_nodes=1)\n",
+                  "            self.workers.append(w)\n"])
+
+with open('testworker.py', 'w') as f:
+    for line in lines:
+        f.write(line)
+
+os.chdir(home)
+
+### EXECUTE BALSAM JOB ###
+
+runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
+subprocess.check_call(runstr.split(' '))

From 393ca75fce428c332d9cc84694398c4e2cfa85ea Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 8 Aug 2019 11:46:18 -0500
Subject: [PATCH 068/644] flake8

---
 .../script_test_jobcontroller_hworld_balsam.py           | 9 ++++++---
 .../regression_tests/test_jobcontroller_hworld_balsam.py | 6 +++---
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/libensemble/tests/regression_tests/script_test_jobcontroller_hworld_balsam.py b/libensemble/tests/regression_tests/script_test_jobcontroller_hworld_balsam.py
index 5bd61c26e..56131e3ec 100644
--- a/libensemble/tests/regression_tests/script_test_jobcontroller_hworld_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_jobcontroller_hworld_balsam.py
@@ -1,17 +1,21 @@
-# This script is meant to be launched by Balsam
+# This script is meant to be submitted to Balsam for execution
 
 import os
 import numpy as np
 import multiprocessing
 
+from libensemble.balsam_controller import BalsamJobController
 from libensemble.message_numbers import WORKER_DONE, WORKER_KILL_ON_ERR, WORKER_KILL_ON_TIMEOUT, JOB_FAILED
 from libensemble.libE import libE
 from libensemble.sim_funcs.job_control_hworld import job_control_hworld as sim_f
 from libensemble.gen_funcs.uniform_sampling import uniform_random_sample as gen_f
-from libensemble.tests.regression_tests.common import build_simfunc, parse_args, per_worker_stream
+from libensemble.tests.regression_tests.common import build_simfunc, per_worker_stream
 
 from mpi4py import MPI
 
+# This script is meant to be launched by Balsam
+
+
 nworkers = MPI.COMM_WORLD.Get_size() - 1
 is_master = MPI.COMM_WORLD.Get_rank() == 0
 libE_specs = {'comm': MPI.COMM_WORLD, 'color': 0, 'comms': 'mpi'}
@@ -34,7 +38,6 @@
 if not os.path.isfile(sim_app):
     build_simfunc()
 
-from libensemble.balsam_controller import BalsamJobController
 jobctrl = BalsamJobController(auto_resources=use_auto_resources)
 
 jobctrl.register_calc(full_path=sim_app, calc_type='sim')
diff --git a/libensemble/tests/regression_tests/test_jobcontroller_hworld_balsam.py b/libensemble/tests/regression_tests/test_jobcontroller_hworld_balsam.py
index 0d2126b42..983178d21 100644
--- a/libensemble/tests/regression_tests/test_jobcontroller_hworld_balsam.py
+++ b/libensemble/tests/regression_tests/test_jobcontroller_hworld_balsam.py
@@ -9,7 +9,7 @@
 #   For our purposes, we append ten workers to Balsam's WorkerGroup
 
 
-### MODIFY BALSAM WORKERGROUP ###
+# MODIFY BALSAM WORKERGROUP
 
 home = os.getcwd()
 balsam_worker_path = os.path.dirname(balsam.__file__) + '/launcher'
@@ -19,7 +19,7 @@
     lines = f.readlines()
 
 if lines[-3] != "        for idx in range(10):\n":
-    lines = lines[:-2] # Will re-add these lines
+    lines = lines[:-2]  # Will re-add these lines
     lines.extend(["        for idx in range(10):\n",
                   "            w = Worker(1, host_type='DEFAULT', num_nodes=1)\n",
                   "            self.workers.append(w)\n"])
@@ -30,7 +30,7 @@
 
 os.chdir(home)
 
-### EXECUTE BALSAM JOB ###
+# EXECUTE BALSAM JOB
 
 runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
 subprocess.check_call(runstr.split(' '))

From 72cb078056812ae394fb76af9bf42d8a8a5d10e9 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 8 Aug 2019 14:23:04 -0500
Subject: [PATCH 069/644] db configuration attempts

---
 conda/balsam-setup.sh | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/conda/balsam-setup.sh b/conda/balsam-setup.sh
index af614f35e..92e367e3b 100755
--- a/conda/balsam-setup.sh
+++ b/conda/balsam-setup.sh
@@ -1,4 +1,6 @@
-balsam init ~/test-balsam
+psql -c 'create database ../test-balsam;' -U postgres
+balsam init ../test-balsam
+sudo chown -R postgres:postgres /var/run/postgresql
 source balsamactivate test-balsam
 
 export EXE=script_test_jobcontroller_hworld_balsam.py

From 3c016769d70a807a94b0845ef5202b6257f27ed7 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 8 Aug 2019 14:51:31 -0500
Subject: [PATCH 070/644] changes init location, modifies permissions

---
 conda/balsam-setup.sh | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/conda/balsam-setup.sh b/conda/balsam-setup.sh
index 92e367e3b..511f0bf19 100755
--- a/conda/balsam-setup.sh
+++ b/conda/balsam-setup.sh
@@ -1,6 +1,7 @@
-psql -c 'create database ../test-balsam;' -U postgres
-balsam init ../test-balsam
+export BALSAM_DB_PATH='~/test-balsam'
 sudo chown -R postgres:postgres /var/run/postgresql
+balsam init ~/test-balsam
+sudo chmod -R 700 ~/test-balsam/balsamdb
 source balsamactivate test-balsam
 
 export EXE=script_test_jobcontroller_hworld_balsam.py

From 4786b002cc0af90fc4c4b33e7f808225211b9f82 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 8 Aug 2019 15:11:04 -0500
Subject: [PATCH 071/644] modifies local travis build script for balsam

---
 conda/run_travis_locally/build_mpich_libE.sh | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/conda/run_travis_locally/build_mpich_libE.sh b/conda/run_travis_locally/build_mpich_libE.sh
index cb6e0de9e..757015092 100755
--- a/conda/run_travis_locally/build_mpich_libE.sh
+++ b/conda/run_travis_locally/build_mpich_libE.sh
@@ -5,8 +5,8 @@
 # -x echo commands
 set -x # problem with this - loads of conda internal commands shown - overwhelming.
 
-export PYTHON_VERSION=3.7       # default - override with -p <version>
-export LIBE_BRANCH="develop"    # default - override with -b <branchname>
+export PYTHON_VERSION=3.6       # default - override with -p <version>
+export LIBE_BRANCH="experimental/balsam-on-travis"    # default - override with -b <branchname>
 export SYSTEM="Linux"         # default - override with -s <OS>
                                 # Options for miniconda - Linux, MacOSX, Windows
 export MPI=MPICH
@@ -76,6 +76,7 @@ conda install nlopt petsc4py petsc mumps-mpi=5.1.2=h5bebb2f_1007 mpi4py scipy $M
 # conda install nlopt || return
 
 # pip install these as the conda installs downgrade pytest on python3.4
+pip install balsam-flow || return
 pip install pytest || return
 pip install pytest-cov || return
 pip install pytest-timeout || return
@@ -87,6 +88,7 @@ git clone -b $LIBE_BRANCH https://github.com/Libensemble/libensemble.git || retu
 cd libensemble/ || return
 pip install -e . || return
 
+conda/balsam-setup.sh
 libensemble/tests/run-tests.sh
 
 echo -e "\n\nScript completed...\n\n"

From bfd523b4e90b8797df8ae04dbb37874ff47e7be8 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 9 Aug 2019 15:20:56 -0500
Subject: [PATCH 072/644] Adds lots of permission and directory changes to
 setup scripts. Temporary ease-of-testing changes. Renames testing scripts.

---
 conda/balsam-setup.sh                         |  3 +-
 conda/run_travis_locally/build_mpich_libE.sh  | 40 +++++++++++++++++--
 ...hworld_balsam.py => script_test_balsam.py} |  0
 ...roller_hworld_balsam.py => test_balsam.py} |  0
 4 files changed, 39 insertions(+), 4 deletions(-)
 rename libensemble/tests/regression_tests/{script_test_jobcontroller_hworld_balsam.py => script_test_balsam.py} (100%)
 rename libensemble/tests/regression_tests/{test_jobcontroller_hworld_balsam.py => test_balsam.py} (100%)

diff --git a/conda/balsam-setup.sh b/conda/balsam-setup.sh
index 511f0bf19..f2af6e8e3 100755
--- a/conda/balsam-setup.sh
+++ b/conda/balsam-setup.sh
@@ -1,10 +1,11 @@
 export BALSAM_DB_PATH='~/test-balsam'
 sudo chown -R postgres:postgres /var/run/postgresql
+sudo chmod a+w /var/run/postgresql
 balsam init ~/test-balsam
 sudo chmod -R 700 ~/test-balsam/balsamdb
 source balsamactivate test-balsam
 
-export EXE=script_test_jobcontroller_hworld_balsam.py
+export EXE=$PWD/libensemble/tests/regression_tests/script_test_balsam.py
 export NUM_WORKERS=2
 export WORKFLOW_NAME=libe_test-balsam
 export SCRIPT_ARGS=$NUM_WORKERS
diff --git a/conda/run_travis_locally/build_mpich_libE.sh b/conda/run_travis_locally/build_mpich_libE.sh
index 757015092..aba4357e4 100755
--- a/conda/run_travis_locally/build_mpich_libE.sh
+++ b/conda/run_travis_locally/build_mpich_libE.sh
@@ -41,7 +41,16 @@ done
 
 echo -e "\nBuilding libE on ${SYSTEM} with python $PYTHON_VERSION and branch ${LIBE_BRANCH}\n"
 
-# sudo apt-get update
+# mkdir pg; cd pg;
+# wget http://sbp.enterprisedb.com/getfile.jsp?fileid=11966
+# tar xf getfile.jsp?fileid=11966
+# export PATH="$PATH:/home/travis/pg/pgsql/bin"
+# cd ~
+
+sudo pip install --upgrade pip
+sudo /etc/init.d/postgresql stop 9.2
+sudo /etc/init.d/postgresql start 9.6
+export PATH=$PATH:/usr/lib/postgresql/9.6/bin
 
 # This works if not sourced but if sourced its no good.
 # set -e
@@ -88,8 +97,33 @@ git clone -b $LIBE_BRANCH https://github.com/Libensemble/libensemble.git || retu
 cd libensemble/ || return
 pip install -e . || return
 
-conda/balsam-setup.sh
-libensemble/tests/run-tests.sh
+export BALSAM_DB_PATH='~/test-balsam'
+sudo chown -R postgres:postgres /var/run/postgresql
+sudo chmod a+w /var/run/postgresql
+balsam init ~/test-balsam
+sudo chmod -R 700 ~/test-balsam/balsamdb
+source balsamactivate test-balsam
+
+export EXE=$PWD/libensemble/tests/regression_tests/script_test_balsam.py
+export NUM_WORKERS=2
+export WORKFLOW_NAME=libe_test-balsam
+export SCRIPT_ARGS=$NUM_WORKERS
+export LIBE_WALLCLOCK=3
+export THIS_DIR=$PWD
+export SCRIPT_BASENAME=${EXE%.*}
+
+balsam rm apps --all --force
+balsam rm jobs --all --force
+
+balsam app --name $SCRIPT_BASENAME.app --exec $EXE --desc "Run $SCRIPT_BASENAME"
+
+balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --args $SCRIPT_ARGS --wall-time-minutes $LIBE_WALLCLOCK --num-nodes 1 --ranks-per-node $((NUM_WORKERS+1)) --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
+
+MYHOME=$PWD
+cd libensemble/tests/regression_tests
+mpiexec -n 3 python test_balsam.py
+cd $MYHOME
+#libensemble/tests/run-tests.sh
 
 echo -e "\n\nScript completed...\n\n"
 set +ex
diff --git a/libensemble/tests/regression_tests/script_test_jobcontroller_hworld_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
similarity index 100%
rename from libensemble/tests/regression_tests/script_test_jobcontroller_hworld_balsam.py
rename to libensemble/tests/regression_tests/script_test_balsam.py
diff --git a/libensemble/tests/regression_tests/test_jobcontroller_hworld_balsam.py b/libensemble/tests/regression_tests/test_balsam.py
similarity index 100%
rename from libensemble/tests/regression_tests/test_jobcontroller_hworld_balsam.py
rename to libensemble/tests/regression_tests/test_balsam.py

From 6a55cd6f1aaa9b240f85886b21ba621ec0808679 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 9 Aug 2019 15:37:44 -0500
Subject: [PATCH 073/644] Removes extra args, adds mpi4py import, other
 cleaning

---
 conda/balsam-setup.sh                                    | 6 ++++--
 conda/run_travis_locally/build_mpich_libE.sh             | 8 +++++---
 libensemble/tests/regression_tests/script_test_balsam.py | 6 +++---
 3 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/conda/balsam-setup.sh b/conda/balsam-setup.sh
index f2af6e8e3..88bb5ef40 100755
--- a/conda/balsam-setup.sh
+++ b/conda/balsam-setup.sh
@@ -8,7 +8,7 @@ source balsamactivate test-balsam
 export EXE=$PWD/libensemble/tests/regression_tests/script_test_balsam.py
 export NUM_WORKERS=2
 export WORKFLOW_NAME=libe_test-balsam
-export SCRIPT_ARGS=$NUM_WORKERS
+# export SCRIPT_ARGS=$NUM_WORKERS
 export LIBE_WALLCLOCK=3
 export THIS_DIR=$PWD
 export SCRIPT_BASENAME=${EXE%.*}
@@ -18,4 +18,6 @@ balsam rm jobs --all --force
 
 balsam app --name $SCRIPT_BASENAME.app --exec $EXE --desc "Run $SCRIPT_BASENAME"
 
-balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --args $SCRIPT_ARGS --wall-time-minutes $LIBE_WALLCLOCK --num-nodes 1 --ranks-per-node $((NUM_WORKERS+1)) --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
+# balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --args $SCRIPT_ARGS --wall-time-minutes $LIBE_WALLCLOCK --num-nodes 1 --ranks-per-node $((NUM_WORKERS+1)) --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
+
+balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --wall-time-minutes $LIBE_WALLCLOCK --num-nodes 1 --ranks-per-node $((NUM_WORKERS+1)) --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
diff --git a/conda/run_travis_locally/build_mpich_libE.sh b/conda/run_travis_locally/build_mpich_libE.sh
index aba4357e4..88b561d44 100755
--- a/conda/run_travis_locally/build_mpich_libE.sh
+++ b/conda/run_travis_locally/build_mpich_libE.sh
@@ -107,7 +107,7 @@ source balsamactivate test-balsam
 export EXE=$PWD/libensemble/tests/regression_tests/script_test_balsam.py
 export NUM_WORKERS=2
 export WORKFLOW_NAME=libe_test-balsam
-export SCRIPT_ARGS=$NUM_WORKERS
+#export SCRIPT_ARGS=$NUM_WORKERS
 export LIBE_WALLCLOCK=3
 export THIS_DIR=$PWD
 export SCRIPT_BASENAME=${EXE%.*}
@@ -117,11 +117,13 @@ balsam rm jobs --all --force
 
 balsam app --name $SCRIPT_BASENAME.app --exec $EXE --desc "Run $SCRIPT_BASENAME"
 
-balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --args $SCRIPT_ARGS --wall-time-minutes $LIBE_WALLCLOCK --num-nodes 1 --ranks-per-node $((NUM_WORKERS+1)) --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
+# balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --args $SCRIPT_ARGS --wall-time-minutes $LIBE_WALLCLOCK --num-nodes 1 --ranks-per-node $((NUM_WORKERS+1)) --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
+
+balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --wall-time-minutes $LIBE_WALLCLOCK --num-nodes 1 --ranks-per-node $((NUM_WORKERS+1)) --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
 
 MYHOME=$PWD
 cd libensemble/tests/regression_tests
-mpiexec -n 3 python test_balsam.py
+python test_balsam.py
 cd $MYHOME
 #libensemble/tests/run-tests.sh
 
diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index 56131e3ec..c88978d7a 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -11,14 +11,14 @@
 from libensemble.gen_funcs.uniform_sampling import uniform_random_sample as gen_f
 from libensemble.tests.regression_tests.common import build_simfunc, per_worker_stream
 
+import mpi4py
 from mpi4py import MPI
 
 # This script is meant to be launched by Balsam
 
-
+mpi4py.rc.recv_mprobe = False
 nworkers = MPI.COMM_WORLD.Get_size() - 1
-is_master = MPI.COMM_WORLD.Get_rank() == 0
-libE_specs = {'comm': MPI.COMM_WORLD, 'color': 0, 'comms': 'mpi'}
+is_master = (MPI.COMM_WORLD.Get_rank() == 0)
 
 cores_per_job = 1
 logical_cores = multiprocessing.cpu_count()

From f05cf990da6a88f43be718b0a30193b407eb908d Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 9 Aug 2019 16:08:24 -0500
Subject: [PATCH 074/644] truncates test script basename to prevent too many
 nested directories.

---
 conda/balsam-setup.sh                                |  3 ++-
 conda/run_travis_locally/build_mpich_libE.sh         |  3 ++-
 .../tests/regression_tests/script_test_balsam.py     | 12 +++++++++++-
 3 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/conda/balsam-setup.sh b/conda/balsam-setup.sh
index 88bb5ef40..b826a3949 100755
--- a/conda/balsam-setup.sh
+++ b/conda/balsam-setup.sh
@@ -11,7 +11,8 @@ export WORKFLOW_NAME=libe_test-balsam
 # export SCRIPT_ARGS=$NUM_WORKERS
 export LIBE_WALLCLOCK=3
 export THIS_DIR=$PWD
-export SCRIPT_BASENAME=${EXE%.*}
+#export SCRIPT_BASENAME=${EXE%.*}
+export SCRIPT_BASENAME=script_test_balsam
 
 balsam rm apps --all --force
 balsam rm jobs --all --force
diff --git a/conda/run_travis_locally/build_mpich_libE.sh b/conda/run_travis_locally/build_mpich_libE.sh
index 88b561d44..84e72b6ed 100755
--- a/conda/run_travis_locally/build_mpich_libE.sh
+++ b/conda/run_travis_locally/build_mpich_libE.sh
@@ -110,7 +110,8 @@ export WORKFLOW_NAME=libe_test-balsam
 #export SCRIPT_ARGS=$NUM_WORKERS
 export LIBE_WALLCLOCK=3
 export THIS_DIR=$PWD
-export SCRIPT_BASENAME=${EXE%.*}
+#export SCRIPT_BASENAME=${EXE%.*}
+export SCRIPT_BASENAME=script_test_balsam
 
 balsam rm apps --all --force
 balsam rm jobs --all --force
diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index c88978d7a..acdbfc33f 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -9,11 +9,21 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.job_control_hworld import job_control_hworld as sim_f
 from libensemble.gen_funcs.uniform_sampling import uniform_random_sample as gen_f
-from libensemble.tests.regression_tests.common import build_simfunc, per_worker_stream
+from libensemble.tests.regression_tests.common import per_worker_stream
 
 import mpi4py
 from mpi4py import MPI
 
+def build_simfunc():
+    import subprocess
+    print(os.getcwd())
+
+    # Build simfunc
+    # buildstring='mpif90 -o my_simjob.x my_simjob.f90' # On cray need to use ftn
+    buildstring = 'mpicc -o my_simjob.x ../unit_tests/simdir/my_simjob.c'
+    # subprocess.run(buildstring.split(),check=True) #Python3.5+
+    subprocess.check_call(buildstring.split())
+
 # This script is meant to be launched by Balsam
 
 mpi4py.rc.recv_mprobe = False

From 5afdb581c583fc8c80c9c885d3ce04c8062ef167 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 9 Aug 2019 16:31:35 -0500
Subject: [PATCH 075/644] fixes build_simfunc path, attempt at prepopulating
 libE_specs

---
 libensemble/tests/regression_tests/script_test_balsam.py | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index acdbfc33f..6690d8b50 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -16,16 +16,16 @@
 
 def build_simfunc():
     import subprocess
-    print(os.getcwd())
-
     # Build simfunc
     # buildstring='mpif90 -o my_simjob.x my_simjob.f90' # On cray need to use ftn
-    buildstring = 'mpicc -o my_simjob.x ../unit_tests/simdir/my_simjob.c'
+    buildstring = 'mpicc -o my_simjob.x libensemble/tests/unit_tests/simdir/my_simjob.c'
     # subprocess.run(buildstring.split(),check=True) #Python3.5+
     subprocess.check_call(buildstring.split())
 
 # This script is meant to be launched by Balsam
 
+libE_specs = {'comm': MPI.COMM_WORLD, 'color': 0, 'comms': 'mpi'}
+
 mpi4py.rc.recv_mprobe = False
 nworkers = MPI.COMM_WORLD.Get_size() - 1
 is_master = (MPI.COMM_WORLD.Get_rank() == 0)
@@ -49,7 +49,6 @@ def build_simfunc():
     build_simfunc()
 
 jobctrl = BalsamJobController(auto_resources=use_auto_resources)
-
 jobctrl.register_calc(full_path=sim_app, calc_type='sim')
 
 sim_specs = {'sim_f': sim_f,

From 78cd783cfc1cda0870d80769d00738e6298a8c6b Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 9 Aug 2019 16:57:06 -0500
Subject: [PATCH 076/644] Removes duplicate code, cleans up commented-out code

---
 conda/balsam-setup.sh                        |  6 +---
 conda/run_travis_locally/build_mpich_libE.sh | 36 +++++---------------
 2 files changed, 9 insertions(+), 33 deletions(-)

diff --git a/conda/balsam-setup.sh b/conda/balsam-setup.sh
index b826a3949..3532e7adc 100755
--- a/conda/balsam-setup.sh
+++ b/conda/balsam-setup.sh
@@ -6,12 +6,10 @@ sudo chmod -R 700 ~/test-balsam/balsamdb
 source balsamactivate test-balsam
 
 export EXE=$PWD/libensemble/tests/regression_tests/script_test_balsam.py
-export NUM_WORKERS=2
+export NUM_WORKERS=1
 export WORKFLOW_NAME=libe_test-balsam
-# export SCRIPT_ARGS=$NUM_WORKERS
 export LIBE_WALLCLOCK=3
 export THIS_DIR=$PWD
-#export SCRIPT_BASENAME=${EXE%.*}
 export SCRIPT_BASENAME=script_test_balsam
 
 balsam rm apps --all --force
@@ -19,6 +17,4 @@ balsam rm jobs --all --force
 
 balsam app --name $SCRIPT_BASENAME.app --exec $EXE --desc "Run $SCRIPT_BASENAME"
 
-# balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --args $SCRIPT_ARGS --wall-time-minutes $LIBE_WALLCLOCK --num-nodes 1 --ranks-per-node $((NUM_WORKERS+1)) --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
-
 balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --wall-time-minutes $LIBE_WALLCLOCK --num-nodes 1 --ranks-per-node $((NUM_WORKERS+1)) --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
diff --git a/conda/run_travis_locally/build_mpich_libE.sh b/conda/run_travis_locally/build_mpich_libE.sh
index 84e72b6ed..48a35f3e9 100755
--- a/conda/run_travis_locally/build_mpich_libE.sh
+++ b/conda/run_travis_locally/build_mpich_libE.sh
@@ -11,6 +11,7 @@ export SYSTEM="Linux"         # default - override with -s <OS>
                                 # Options for miniconda - Linux, MacOSX, Windows
 export MPI=MPICH
 export HYDRA_LAUNCHER=fork
+export TESTBALSAM=true
 
 # Allow user to optionally set python version and branch
 # E.g: ". ./build_mpich_libE.sh -p 3.4 -b feature/myfeature"
@@ -97,35 +98,14 @@ git clone -b $LIBE_BRANCH https://github.com/Libensemble/libensemble.git || retu
 cd libensemble/ || return
 pip install -e . || return
 
-export BALSAM_DB_PATH='~/test-balsam'
-sudo chown -R postgres:postgres /var/run/postgresql
-sudo chmod a+w /var/run/postgresql
-balsam init ~/test-balsam
-sudo chmod -R 700 ~/test-balsam/balsamdb
-source balsamactivate test-balsam
-
-export EXE=$PWD/libensemble/tests/regression_tests/script_test_balsam.py
-export NUM_WORKERS=2
-export WORKFLOW_NAME=libe_test-balsam
-#export SCRIPT_ARGS=$NUM_WORKERS
-export LIBE_WALLCLOCK=3
-export THIS_DIR=$PWD
-#export SCRIPT_BASENAME=${EXE%.*}
-export SCRIPT_BASENAME=script_test_balsam
-
-balsam rm apps --all --force
-balsam rm jobs --all --force
-
-balsam app --name $SCRIPT_BASENAME.app --exec $EXE --desc "Run $SCRIPT_BASENAME"
-
-# balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --args $SCRIPT_ARGS --wall-time-minutes $LIBE_WALLCLOCK --num-nodes 1 --ranks-per-node $((NUM_WORKERS+1)) --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
-
-balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --wall-time-minutes $LIBE_WALLCLOCK --num-nodes 1 --ranks-per-node $((NUM_WORKERS+1)) --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
+if [[ "$TESTBALSAM" == true]]; then
+    source /conda/balsam-setup.sh
+    MYHOME=$PWD
+    cd libensemble/tests/regression_tests
+    python test_balsam.py
+    cd $MYHOME
+fi
 
-MYHOME=$PWD
-cd libensemble/tests/regression_tests
-python test_balsam.py
-cd $MYHOME
 #libensemble/tests/run-tests.sh
 
 echo -e "\n\nScript completed...\n\n"

From 58a83607cd14b14956da41bbeedd2667c8074ea6 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 9 Aug 2019 17:10:23 -0500
Subject: [PATCH 077/644] attempt to fix if block

---
 conda/run_travis_locally/build_mpich_libE.sh | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/conda/run_travis_locally/build_mpich_libE.sh b/conda/run_travis_locally/build_mpich_libE.sh
index 48a35f3e9..d35ccf024 100755
--- a/conda/run_travis_locally/build_mpich_libE.sh
+++ b/conda/run_travis_locally/build_mpich_libE.sh
@@ -99,11 +99,11 @@ cd libensemble/ || return
 pip install -e . || return
 
 if [[ "$TESTBALSAM" == true]]; then
-    source /conda/balsam-setup.sh
-    MYHOME=$PWD
-    cd libensemble/tests/regression_tests
-    python test_balsam.py
-    cd $MYHOME
+    source /conda/balsam-setup.sh;
+    MYHOME=$PWD;
+    cd libensemble/tests/regression_tests;
+    python test_balsam.py;
+    cd $MYHOME;
 fi
 
 #libensemble/tests/run-tests.sh

From 6e0e9b93895ed298f8576e0a070a344866cd8566 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 9 Aug 2019 17:21:50 -0500
Subject: [PATCH 078/644] added period

---
 conda/run_travis_locally/build_mpich_libE.sh | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/conda/run_travis_locally/build_mpich_libE.sh b/conda/run_travis_locally/build_mpich_libE.sh
index d35ccf024..64b191344 100755
--- a/conda/run_travis_locally/build_mpich_libE.sh
+++ b/conda/run_travis_locally/build_mpich_libE.sh
@@ -98,8 +98,8 @@ git clone -b $LIBE_BRANCH https://github.com/Libensemble/libensemble.git || retu
 cd libensemble/ || return
 pip install -e . || return
 
-if [[ "$TESTBALSAM" == true]]; then
-    source /conda/balsam-setup.sh;
+if [[ "$TESTBALSAM" == true ]]; then
+    source ./conda/balsam-setup.sh;
     MYHOME=$PWD;
     cd libensemble/tests/regression_tests;
     python test_balsam.py;

From 64ed27f03b034584bba74b8137e0a6e3794ffdfb Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Mon, 12 Aug 2019 08:49:11 -0500
Subject: [PATCH 079/644] corrects the setObjectiveGradient invocation

---
 libensemble/gen_funcs/persistent_aposmm.py | 15 +++++----------
 1 file changed, 5 insertions(+), 10 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index a5600c132..80c5fe1c8 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -577,7 +577,7 @@ def tao_callback_fun(tao, x, f, comm_queue, child_can_read, parent_can_read, gen
     return f
 
 
-def tao_callback_fun_grad(tao, x, f, g, comm_queue, child_can_read, parent_can_read, gen_specs):
+def tao_callback_fun_grad(tao, x, g, comm_queue, child_can_read, parent_can_read, gen_specs):
 
     comm_queue.put(x.array)
     # print('[Child]: I just put x_on_cube =', x.array, flush=True)
@@ -586,15 +586,10 @@ def tao_callback_fun_grad(tao, x, f, g, comm_queue, child_can_read, parent_can_r
     # print('[Child]: I have started waiting', flush=True)
     child_can_read.wait()
     # print('[Child]: Wohooo.. I am free folks', flush=True)
-    if gen_specs['localopt_method'] in ['blmvm']:
-        f_recv, grad_recv = comm_queue.get()
-        g.array[:] = grad_recv
-    else:
-        assert gen_specs['localopt_method'] in ['pounders']
-        f_recv, = comm_queue.get()
+    f_recv, grad_recv = comm_queue.get()
+    g.array[:] = grad_recv
     child_can_read.clear()
-    f.array[:] = f_recv
-    return f
+    return f_recv
 
 
 def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read, parent_can_read):
@@ -631,7 +626,7 @@ def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read, parent_can_read
         g = PETSc.Vec().create(tao_comm)
         g.setSizes(n)
         g.setFromOptions()
-        tao.setObjectiveGradient(lambda tao, x, f, g: tao_callback_fun_grad(tao, x, f, g, comm_queue, child_can_read, parent_can_read, gen_specs))
+        tao.setObjectiveGradient(lambda tao, x, g: tao_callback_fun_grad(tao, x, g, comm_queue, child_can_read, parent_can_read, gen_specs))
 
     delta_0 = gen_specs['dist_to_bound_multiple']*np.min([np.min(ub.array-x.array), np.min(x.array-lb.array)])
     PETSc.Options().setValue('-tao_pounders_delta', str(delta_0))

From b7b4f0bac1c0cd9427cd92186c179314d75861ec Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 12 Aug 2019 09:03:22 -0500
Subject: [PATCH 080/644] re-adds TESTSUITE fields for proper parsing by
 run-tests

---
 libensemble/tests/regression_tests/test_balsam.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/libensemble/tests/regression_tests/test_balsam.py b/libensemble/tests/regression_tests/test_balsam.py
index 983178d21..8c9dff107 100644
--- a/libensemble/tests/regression_tests/test_balsam.py
+++ b/libensemble/tests/regression_tests/test_balsam.py
@@ -8,6 +8,8 @@
 #   so multiple workers can be run on a single node (until this feature is [hopefully] added!).
 #   For our purposes, we append ten workers to Balsam's WorkerGroup
 
+# TESTSUITE_COMMS: local
+# TESTSUITE_NPROCS: 2
 
 # MODIFY BALSAM WORKERGROUP
 

From 2197da5388a36718b9b30e9e8d27a4c2f743ff79 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 12 Aug 2019 09:05:44 -0500
Subject: [PATCH 081/644] flake8

---
 libensemble/tests/regression_tests/script_test_balsam.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index 6690d8b50..93f05ecd2 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -14,6 +14,7 @@
 import mpi4py
 from mpi4py import MPI
 
+
 def build_simfunc():
     import subprocess
     # Build simfunc
@@ -22,6 +23,7 @@ def build_simfunc():
     # subprocess.run(buildstring.split(),check=True) #Python3.5+
     subprocess.check_call(buildstring.split())
 
+
 # This script is meant to be launched by Balsam
 
 libE_specs = {'comm': MPI.COMM_WORLD, 'color': 0, 'comms': 'mpi'}

From 09c0e4ed93798049d7b19590deb53918e282e049 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 12 Aug 2019 09:40:07 -0500
Subject: [PATCH 082/644] Fixes balsam worker file modification, some numerical
 changes

---
 .../tests/regression_tests/script_test_balsam.py   |  2 +-
 libensemble/tests/regression_tests/test_balsam.py  | 14 ++++++++------
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index 93f05ecd2..82537dad8 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -71,7 +71,7 @@ def build_simfunc():
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
-exit_criteria = {'elapsed_wallclock_time': 10}
+exit_criteria = {'elapsed_wallclock_time': 15}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
diff --git a/libensemble/tests/regression_tests/test_balsam.py b/libensemble/tests/regression_tests/test_balsam.py
index 8c9dff107..34ebb7e56 100644
--- a/libensemble/tests/regression_tests/test_balsam.py
+++ b/libensemble/tests/regression_tests/test_balsam.py
@@ -9,24 +9,26 @@
 #   For our purposes, we append ten workers to Balsam's WorkerGroup
 
 # TESTSUITE_COMMS: local
-# TESTSUITE_NPROCS: 2
+# TESTSUITE_NPROCS: 3
 
 # MODIFY BALSAM WORKERGROUP
 
+workerfile = 'worker.py'
+
 home = os.getcwd()
 balsam_worker_path = os.path.dirname(balsam.__file__) + '/launcher'
 os.chdir(balsam_worker_path)
 
-with open('worker.py', 'r') as f:
+with open(workerfile, 'r') as f:
     lines = f.readlines()
 
-if lines[-3] != "        for idx in range(10):\n":
+if lines[-3] != "        for idx in range(3):\n":
     lines = lines[:-2]  # Will re-add these lines
-    lines.extend(["        for idx in range(10):\n",
+    lines.extend(["        for idx in range(3):\n",
                   "            w = Worker(1, host_type='DEFAULT', num_nodes=1)\n",
                   "            self.workers.append(w)\n"])
 
-with open('testworker.py', 'w') as f:
+with open(workerfile, 'w') as f:
     for line in lines:
         f.write(line)
 
@@ -35,4 +37,4 @@
 # EXECUTE BALSAM JOB
 
 runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
-subprocess.check_call(runstr.split(' '))
+subprocess.check_call(runstr.split())

From 3aa4cebff5d66306e2cce58f12924cce2f4364c1 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 12 Aug 2019 10:17:40 -0500
Subject: [PATCH 083/644] balsam-specific sim func added

---
 .../sim_funcs/job_control_hworld_balsam.py    | 121 ++++++++++++++++++
 .../regression_tests/script_test_balsam.py    |   3 +-
 2 files changed, 123 insertions(+), 1 deletion(-)
 create mode 100644 libensemble/sim_funcs/job_control_hworld_balsam.py

diff --git a/libensemble/sim_funcs/job_control_hworld_balsam.py b/libensemble/sim_funcs/job_control_hworld_balsam.py
new file mode 100644
index 000000000..638eb9ef8
--- /dev/null
+++ b/libensemble/sim_funcs/job_control_hworld_balsam.py
@@ -0,0 +1,121 @@
+from libensemble.balsam_controller import BalsamJobController
+from libensemble.message_numbers import UNSET_TAG, WORKER_KILL_ON_ERR, MAN_SIGNAL_FINISH, WORKER_DONE, JOB_FAILED, WORKER_KILL_ON_TIMEOUT
+import numpy as np
+
+__all__ = ['job_control_hworld']
+
+# Alt send values through X
+sim_count = 0
+
+
+def polling_loop(comm, jobctl, job, timeout_sec=3.0, delay=0.3):
+    import time
+
+    calc_status = UNSET_TAG  # Sim func determines status of libensemble calc - returned to worker
+
+    while job.runtime < timeout_sec:
+        time.sleep(delay)
+
+        # print('Probing manager at time: ', job.runtime)
+        jobctl.manager_poll(comm)
+        if jobctl.manager_signal == 'finish':
+            jobctl.kill(job)
+            calc_status = MAN_SIGNAL_FINISH  # Worker will pick this up and close down
+            print('Job {} killed by manager on worker {}'.format(job.id, jobctl.workerID))
+            break
+
+        # print('Polling job at time', job.runtime)
+        job.poll()
+        if job.finished:
+            break
+        elif job.state == 'RUNNING':
+            print('Job {} still running on worker {} ....'.format(job.id, jobctl.workerID))
+
+        # Check output file for error
+        # print('Checking output file for error at time:', job.runtime)
+        if job.stdout_exists():
+            if 'Error' in job.read_stdout():
+                print("Found (deliberate) Error in ouput file - cancelling job {} on worker {}".format(job.id, jobctl.workerID))
+                jobctl.kill(job)
+                calc_status = WORKER_KILL_ON_ERR
+                break
+
+    # After exiting loop
+    if job.finished:
+        print('Job {} done on worker {}'.format(job.id, jobctl.workerID))
+        # Fill in calc_status if not already
+        if calc_status == UNSET_TAG:
+            if job.state == 'FINISHED':  # Means finished succesfully
+                calc_status = WORKER_DONE
+            elif job.state == 'FAILED':
+                calc_status = JOB_FAILED
+            # elif job.state == 'USER_KILLED':
+            #     calc_status = WORKER_KILL
+    else:
+        # assert job.state == 'RUNNING', "job.state expected to be RUNNING. Returned: " + str(job.state)
+        print("Job {} timed out - killing on worker {}".format(job.id, jobctl.workerID))
+        jobctl.kill(job)
+        if job.finished:
+            print('Job {} done on worker {}'.format(job.id, jobctl.workerID))
+        calc_status = WORKER_KILL_ON_TIMEOUT
+
+    return job, calc_status
+
+
+def job_control_hworld(H, persis_info, sim_specs, libE_specs):
+    """ Test of launching and polling job and exiting on job finish"""
+    jobctl = BalsamJobController.controller
+    cores = sim_specs['cores']
+    comm = libE_specs['comm']
+
+    args_for_sim = 'sleep 1'
+    # pref send this in X as a sim_in from calling script
+    global sim_count
+    sim_count += 1
+    timeout = 3.0
+    if sim_count == 1:
+        args_for_sim = 'sleep 1'  # Should finish
+    elif sim_count == 2:
+        args_for_sim = 'sleep 1 Error'  # Worker kill on error
+    elif sim_count == 3:
+        args_for_sim = 'sleep 3'  # Worker kill on timeout
+        timeout = 1.0
+    elif sim_count == 4:
+        args_for_sim = 'sleep 1 Fail'  # Manager kill - if signal received else completes
+    elif sim_count == 5:
+        args_for_sim = 'sleep 18'  # Manager kill - if signal received else completes
+        timeout = 20.0
+
+    job = jobctl.launch(calc_type='sim', num_procs=cores, app_args=args_for_sim, hyperthreads=True)
+    job, calc_status = polling_loop(comm, jobctl, job, timeout)
+
+    # assert job.finished, "job.finished should be True. Returned " + str(job.finished)
+    # assert job.state == 'FINISHED', "job.state should be FINISHED. Returned " + str(job.state)
+
+    # This is temp - return something - so doing six_hump_camel_func again...
+    batch = len(H['x'])
+    O = np.zeros(batch, dtype=sim_specs['out'])
+    for i, x in enumerate(H['x']):
+        O['f'][i] = six_hump_camel_func(x)
+
+    # This is just for testing at calling script level - status of each job
+    O['cstat'] = calc_status
+
+    # v = np.random.uniform(0, 10)
+    # print('About to sleep for :' + str(v))
+    # time.sleep(v)
+
+    return O, persis_info, calc_status
+
+
+def six_hump_camel_func(x):
+    """
+    Definition of the six-hump camel
+    """
+    x1 = x[0]
+    x2 = x[1]
+    term1 = (4-2.1*x1**2+(x1**4)/3) * x1**2
+    term2 = x1*x2
+    term3 = (-4+4*x2**2) * x2**2
+
+    return term1 + term2 + term3
diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index 82537dad8..0b13ac564 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -7,11 +7,12 @@
 from libensemble.balsam_controller import BalsamJobController
 from libensemble.message_numbers import WORKER_DONE, WORKER_KILL_ON_ERR, WORKER_KILL_ON_TIMEOUT, JOB_FAILED
 from libensemble.libE import libE
-from libensemble.sim_funcs.job_control_hworld import job_control_hworld as sim_f
+from libensemble.sim_funcs.job_control_hworld_balsam import job_control_hworld as sim_f
 from libensemble.gen_funcs.uniform_sampling import uniform_random_sample as gen_f
 from libensemble.tests.regression_tests.common import per_worker_stream
 
 import mpi4py
+mpi4py.rc.recv_mprobe = False  # Disable matching probes
 from mpi4py import MPI
 
 

From 014c2e4bb6bdf02954e07266f0080e5230c37df8 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Mon, 12 Aug 2019 10:34:34 -0500
Subject: [PATCH 084/644] Using array_r to PETSc read array (Otherwise I get
 errors)

---
 libensemble/gen_funcs/persistent_aposmm.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 80c5fe1c8..0952f8298 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -564,7 +564,7 @@ def run_local_scipy_opt(gen_specs, comm_queue, x0, f0, child_can_read, parent_ca
 # {{{ TAO routines for local opt
 
 def tao_callback_fun(tao, x, f, comm_queue, child_can_read, parent_can_read, gen_specs):
-    comm_queue.put(x.array)
+    comm_queue.put(x.array_r)
     # print('[Child]: I just put x_on_cube =', x.array, flush=True)
     # print('[Child]: Parent should no longer wait.', flush=True)
     parent_can_read.set()
@@ -579,7 +579,7 @@ def tao_callback_fun(tao, x, f, comm_queue, child_can_read, parent_can_read, gen
 
 def tao_callback_fun_grad(tao, x, g, comm_queue, child_can_read, parent_can_read, gen_specs):
 
-    comm_queue.put(x.array)
+    comm_queue.put(x.array_r)
     # print('[Child]: I just put x_on_cube =', x.array, flush=True)
     # print('[Child]: Parent should no longer wait.', flush=True)
     parent_can_read.set()

From 29e550e195e9a68bcf576eaa8958595682ee778b Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 12 Aug 2019 11:26:54 -0500
Subject: [PATCH 085/644] experimental numerical adjustments

---
 conda/balsam-setup.sh                                    | 2 +-
 libensemble/tests/regression_tests/script_test_balsam.py | 5 ++---
 libensemble/tests/regression_tests/test_balsam.py        | 4 ++--
 3 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/conda/balsam-setup.sh b/conda/balsam-setup.sh
index 3532e7adc..aa658cb19 100755
--- a/conda/balsam-setup.sh
+++ b/conda/balsam-setup.sh
@@ -6,7 +6,7 @@ sudo chmod -R 700 ~/test-balsam/balsamdb
 source balsamactivate test-balsam
 
 export EXE=$PWD/libensemble/tests/regression_tests/script_test_balsam.py
-export NUM_WORKERS=1
+export NUM_WORKERS=2
 export WORKFLOW_NAME=libe_test-balsam
 export LIBE_WALLCLOCK=3
 export THIS_DIR=$PWD
diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index 0b13ac564..1cfe851b0 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -29,9 +29,8 @@ def build_simfunc():
 
 libE_specs = {'comm': MPI.COMM_WORLD, 'color': 0, 'comms': 'mpi'}
 
-mpi4py.rc.recv_mprobe = False
 nworkers = MPI.COMM_WORLD.Get_size() - 1
-is_master = (MPI.COMM_WORLD.Get_rank() == 0)
+is_master = MPI.COMM_WORLD.Get_rank() == 0
 
 cores_per_job = 1
 logical_cores = multiprocessing.cpu_count()
@@ -72,7 +71,7 @@ def build_simfunc():
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
-exit_criteria = {'elapsed_wallclock_time': 15}
+exit_criteria = {'elapsed_wallclock_time': 10}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
diff --git a/libensemble/tests/regression_tests/test_balsam.py b/libensemble/tests/regression_tests/test_balsam.py
index 34ebb7e56..016588960 100644
--- a/libensemble/tests/regression_tests/test_balsam.py
+++ b/libensemble/tests/regression_tests/test_balsam.py
@@ -22,9 +22,9 @@
 with open(workerfile, 'r') as f:
     lines = f.readlines()
 
-if lines[-3] != "        for idx in range(3):\n":
+if lines[-3] != "        for idx in range(10):\n":
     lines = lines[:-2]  # Will re-add these lines
-    lines.extend(["        for idx in range(3):\n",
+    lines.extend(["        for idx in range(10):\n",
                   "            w = Worker(1, host_type='DEFAULT', num_nodes=1)\n",
                   "            self.workers.append(w)\n"])
 

From 3e16c37b74a7e3e47f9760c987c796b92af5db48 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 12 Aug 2019 13:55:22 -0500
Subject: [PATCH 086/644] try disabling autoresources, get job controller
 instance from JobController class instead

---
 libensemble/sim_funcs/job_control_hworld_balsam.py |  4 +++-
 .../tests/regression_tests/script_test_balsam.py   | 14 +++++++-------
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/libensemble/sim_funcs/job_control_hworld_balsam.py b/libensemble/sim_funcs/job_control_hworld_balsam.py
index 638eb9ef8..92aed518b 100644
--- a/libensemble/sim_funcs/job_control_hworld_balsam.py
+++ b/libensemble/sim_funcs/job_control_hworld_balsam.py
@@ -1,4 +1,5 @@
 from libensemble.balsam_controller import BalsamJobController
+from libensemble.controller import JobController
 from libensemble.message_numbers import UNSET_TAG, WORKER_KILL_ON_ERR, MAN_SIGNAL_FINISH, WORKER_DONE, JOB_FAILED, WORKER_KILL_ON_TIMEOUT
 import numpy as np
 
@@ -64,7 +65,8 @@ def polling_loop(comm, jobctl, job, timeout_sec=3.0, delay=0.3):
 
 def job_control_hworld(H, persis_info, sim_specs, libE_specs):
     """ Test of launching and polling job and exiting on job finish"""
-    jobctl = BalsamJobController.controller
+    #jobctl = BalsamJobController.controller
+    jobctl = JobController.controller
     cores = sim_specs['cores']
     comm = libE_specs['comm']
 
diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index 1cfe851b0..521e0fc7a 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -36,12 +36,12 @@ def build_simfunc():
 logical_cores = multiprocessing.cpu_count()
 cores_all_jobs = nworkers*cores_per_job
 
-if cores_all_jobs > logical_cores:
-    use_auto_resources = False
-    mess_resources = 'Oversubscribing - auto_resources set to False'
-else:
-    use_auto_resources = True
-    mess_resources = 'Auto_resources set to True'
+# if cores_all_jobs > logical_cores:
+#     use_auto_resources = False
+#     mess_resources = 'Oversubscribing - auto_resources set to False'
+# else:
+#     use_auto_resources = True
+#     mess_resources = 'Auto_resources set to True'
 
 if is_master:
     print('\nCores req: {} Cores avail: {}\n  {}\n'.format(cores_all_jobs, logical_cores, mess_resources))
@@ -50,7 +50,7 @@ def build_simfunc():
 if not os.path.isfile(sim_app):
     build_simfunc()
 
-jobctrl = BalsamJobController(auto_resources=use_auto_resources)
+jobctrl = BalsamJobController(auto_resources=False)
 jobctrl.register_calc(full_path=sim_app, calc_type='sim')
 
 sim_specs = {'sim_f': sim_f,

From 61cf005a514eacadee70c63954910a1e8e5390c8 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 12 Aug 2019 14:47:42 -0500
Subject: [PATCH 087/644] remove reference to autoresources, reenable resource
 message

---
 .../tests/regression_tests/script_test_balsam.py   | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index 521e0fc7a..1b56ec4cb 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -36,12 +36,12 @@ def build_simfunc():
 logical_cores = multiprocessing.cpu_count()
 cores_all_jobs = nworkers*cores_per_job
 
-# if cores_all_jobs > logical_cores:
-#     use_auto_resources = False
-#     mess_resources = 'Oversubscribing - auto_resources set to False'
-# else:
-#     use_auto_resources = True
-#     mess_resources = 'Auto_resources set to True'
+if cores_all_jobs > logical_cores:
+    use_auto_resources = False
+    mess_resources = 'Oversubscribing - auto_resources set to False'
+else:
+    use_auto_resources = True
+    mess_resources = 'Auto_resources set to True'
 
 if is_master:
     print('\nCores req: {} Cores avail: {}\n  {}\n'.format(cores_all_jobs, logical_cores, mess_resources))
@@ -50,7 +50,7 @@ def build_simfunc():
 if not os.path.isfile(sim_app):
     build_simfunc()
 
-jobctrl = BalsamJobController(auto_resources=False)
+jobctrl = BalsamJobController()
 jobctrl.register_calc(full_path=sim_app, calc_type='sim')
 
 sim_specs = {'sim_f': sim_f,

From b837119be4ebe7251f555c597b43bc4e3fdc1f26 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 12 Aug 2019 16:14:40 -0500
Subject: [PATCH 088/644] re-add autoresources = false flag

---
 libensemble/tests/regression_tests/script_test_balsam.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index 1b56ec4cb..fbdd2d284 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -50,7 +50,7 @@ def build_simfunc():
 if not os.path.isfile(sim_app):
     build_simfunc()
 
-jobctrl = BalsamJobController()
+jobctrl = BalsamJobController(use_auto_resources=False)
 jobctrl.register_calc(full_path=sim_app, calc_type='sim')
 
 sim_specs = {'sim_f': sim_f,

From f4f8d9ca2295e6ad35dd06c34bd06e7c000e3717 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 12 Aug 2019 16:33:01 -0500
Subject: [PATCH 089/644] Timing and settings adjustments

---
 libensemble/sim_funcs/job_control_hworld_balsam.py       | 4 ++--
 libensemble/tests/regression_tests/script_test_balsam.py | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/libensemble/sim_funcs/job_control_hworld_balsam.py b/libensemble/sim_funcs/job_control_hworld_balsam.py
index 92aed518b..5dd615d98 100644
--- a/libensemble/sim_funcs/job_control_hworld_balsam.py
+++ b/libensemble/sim_funcs/job_control_hworld_balsam.py
@@ -74,7 +74,7 @@ def job_control_hworld(H, persis_info, sim_specs, libE_specs):
     # pref send this in X as a sim_in from calling script
     global sim_count
     sim_count += 1
-    timeout = 3.0
+    timeout = 6.0
     if sim_count == 1:
         args_for_sim = 'sleep 1'  # Should finish
     elif sim_count == 2:
@@ -88,7 +88,7 @@ def job_control_hworld(H, persis_info, sim_specs, libE_specs):
         args_for_sim = 'sleep 18'  # Manager kill - if signal received else completes
         timeout = 20.0
 
-    job = jobctl.launch(calc_type='sim', num_procs=cores, app_args=args_for_sim, hyperthreads=True)
+    job = jobctl.launch(calc_type='sim', num_procs=cores, app_args=args_for_sim, hyperthreads=True, wait_on_run=True)
     job, calc_status = polling_loop(comm, jobctl, job, timeout)
 
     # assert job.finished, "job.finished should be True. Returned " + str(job.finished)
diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index fbdd2d284..a4c7d0c1d 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -71,7 +71,7 @@ def build_simfunc():
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
-exit_criteria = {'elapsed_wallclock_time': 10}
+exit_criteria = {'elapsed_wallclock_time': 30}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,

From 8fd59a11d8bd67f4eaf2be71e7d2f3919ce2e397 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 12 Aug 2019 16:46:50 -0500
Subject: [PATCH 090/644] fixes autoresources, reeanbles running all tests with
 setup script

---
 conda/run_travis_locally/build_mpich_libE.sh             | 6 +-----
 libensemble/tests/regression_tests/script_test_balsam.py | 2 +-
 2 files changed, 2 insertions(+), 6 deletions(-)

diff --git a/conda/run_travis_locally/build_mpich_libE.sh b/conda/run_travis_locally/build_mpich_libE.sh
index 64b191344..47d50ff4e 100755
--- a/conda/run_travis_locally/build_mpich_libE.sh
+++ b/conda/run_travis_locally/build_mpich_libE.sh
@@ -100,13 +100,9 @@ pip install -e . || return
 
 if [[ "$TESTBALSAM" == true ]]; then
     source ./conda/balsam-setup.sh;
-    MYHOME=$PWD;
-    cd libensemble/tests/regression_tests;
-    python test_balsam.py;
-    cd $MYHOME;
 fi
 
-#libensemble/tests/run-tests.sh
+libensemble/tests/run-tests.sh
 
 echo -e "\n\nScript completed...\n\n"
 set +ex
diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index a4c7d0c1d..39358d271 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -50,7 +50,7 @@ def build_simfunc():
 if not os.path.isfile(sim_app):
     build_simfunc()
 
-jobctrl = BalsamJobController(use_auto_resources=False)
+jobctrl = BalsamJobController(auto_resources=False)
 jobctrl.register_calc(full_path=sim_app, calc_type='sim')
 
 sim_specs = {'sim_f': sim_f,

From b7c7f35a3df07be9e2c7df11706249549205f47d Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 12 Aug 2019 16:53:08 -0500
Subject: [PATCH 091/644] flake8

---
 libensemble/sim_funcs/job_control_hworld_balsam.py       | 4 +---
 libensemble/tests/regression_tests/script_test_balsam.py | 4 ++--
 2 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/libensemble/sim_funcs/job_control_hworld_balsam.py b/libensemble/sim_funcs/job_control_hworld_balsam.py
index 5dd615d98..a8dd89e8c 100644
--- a/libensemble/sim_funcs/job_control_hworld_balsam.py
+++ b/libensemble/sim_funcs/job_control_hworld_balsam.py
@@ -1,5 +1,4 @@
 from libensemble.balsam_controller import BalsamJobController
-from libensemble.controller import JobController
 from libensemble.message_numbers import UNSET_TAG, WORKER_KILL_ON_ERR, MAN_SIGNAL_FINISH, WORKER_DONE, JOB_FAILED, WORKER_KILL_ON_TIMEOUT
 import numpy as np
 
@@ -65,8 +64,7 @@ def polling_loop(comm, jobctl, job, timeout_sec=3.0, delay=0.3):
 
 def job_control_hworld(H, persis_info, sim_specs, libE_specs):
     """ Test of launching and polling job and exiting on job finish"""
-    #jobctl = BalsamJobController.controller
-    jobctl = JobController.controller
+    jobctl = BalsamJobController.controller
     cores = sim_specs['cores']
     comm = libE_specs['comm']
 
diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index 39358d271..05f413f3b 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -3,6 +3,8 @@
 import os
 import numpy as np
 import multiprocessing
+import mpi4py
+from mpi4py import MPI
 
 from libensemble.balsam_controller import BalsamJobController
 from libensemble.message_numbers import WORKER_DONE, WORKER_KILL_ON_ERR, WORKER_KILL_ON_TIMEOUT, JOB_FAILED
@@ -11,9 +13,7 @@
 from libensemble.gen_funcs.uniform_sampling import uniform_random_sample as gen_f
 from libensemble.tests.regression_tests.common import per_worker_stream
 
-import mpi4py
 mpi4py.rc.recv_mprobe = False  # Disable matching probes
-from mpi4py import MPI
 
 
 def build_simfunc():

From 84e8c76e56cc8e1944475305b3aba94bdf494e57 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 13 Aug 2019 10:19:34 -0500
Subject: [PATCH 092/644] Most recent version of balsam obtained from github.
 py-version dependent balsam testing and configuring.

---
 .travis.yml | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 4487d1883..2bef8cbc7 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -74,7 +74,6 @@ install:
   #S- conda install nlopt petsc4py petsc mpi4py scipy $MPI
   - conda install nlopt petsc4py petsc $MUMPS mpi4py scipy $MPI
   # pip install these as the conda installs downgrade pytest on python3.4
-  - pip install balsam-flow
   - pip install flake8
   - pip install pytest
   - pip install pytest-cov
@@ -85,11 +84,16 @@ install:
   - python conda/find_mpi.py # locate compilers
   - mpiexec --version # Show MPI library details
   - pip install -e .
+  - if [[ $TRAVIS_PYTHON_VERSION >= 3.6 ]]; then
+        git clone https://github.com/balsam-alcf/balsam.git ../balsam;
+        cd ../balsam; pip install -e .; cd ../libensemble;
+        mv ./conda/test_balsam.py ./libensemble/tests/regression_tests;
+        ./conda/balsam-setup.sh;
+    fi
 
 
 before_script:
   - flake8 libensemble
-  - ./conda/balsam-setup.sh
   # Set conda compilers to use new SDK instead of Travis default.
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
         echo "export CONDA_BUILD_SYSROOT=/Users/travis/build/Libensemble/sdk/MacOSX10.13.sdk" > setenv.sh;

From 4511f638368f5ce1b2b426b45ac0ff9f0c94ff62 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 13 Aug 2019 10:24:32 -0500
Subject: [PATCH 093/644] fixes py version comparision

---
 .travis.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index 2bef8cbc7..de130fbbb 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -84,7 +84,7 @@ install:
   - python conda/find_mpi.py # locate compilers
   - mpiexec --version # Show MPI library details
   - pip install -e .
-  - if [[ $TRAVIS_PYTHON_VERSION >= 3.6 ]]; then
+  - if [[ $TRAVIS_PYTHON_VERSION -ge 3.6 ]]; then
         git clone https://github.com/balsam-alcf/balsam.git ../balsam;
         cd ../balsam; pip install -e .; cd ../libensemble;
         mv ./conda/test_balsam.py ./libensemble/tests/regression_tests;

From 7d07f21a1680f102dfdc1578a013d42b6792a24b Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 13 Aug 2019 11:08:14 -0500
Subject: [PATCH 094/644] better version comparision

---
 .travis.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index de130fbbb..f6461ae7a 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -84,7 +84,7 @@ install:
   - python conda/find_mpi.py # locate compilers
   - mpiexec --version # Show MPI library details
   - pip install -e .
-  - if [[ $TRAVIS_PYTHON_VERSION -ge 3.6 ]]; then
+  - if [[ "{ $TRAVIS_PYTHON_VERSION | cut -c 3 } -ge 6" ]]; then
         git clone https://github.com/balsam-alcf/balsam.git ../balsam;
         cd ../balsam; pip install -e .; cd ../libensemble;
         mv ./conda/test_balsam.py ./libensemble/tests/regression_tests;

From 998dd22164e0abff7c577669131b4cb57b63c634 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 13 Aug 2019 12:08:52 -0500
Subject: [PATCH 095/644] Moved python version comparision, balsam installation
 to external py script.

---
 .travis.yml                                        | 13 +++++++------
 .../{balsam-setup.sh => configure-balsam-test.sh}  |  0
 conda/install-balsam.py                            | 14 ++++++++++++++
 3 files changed, 21 insertions(+), 6 deletions(-)
 rename conda/{balsam-setup.sh => configure-balsam-test.sh} (100%)
 create mode 100644 conda/install-balsam.py

diff --git a/.travis.yml b/.travis.yml
index f6461ae7a..de9db6390 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -84,12 +84,13 @@ install:
   - python conda/find_mpi.py # locate compilers
   - mpiexec --version # Show MPI library details
   - pip install -e .
-  - if [[ "{ $TRAVIS_PYTHON_VERSION | cut -c 3 } -ge 6" ]]; then
-        git clone https://github.com/balsam-alcf/balsam.git ../balsam;
-        cd ../balsam; pip install -e .; cd ../libensemble;
-        mv ./conda/test_balsam.py ./libensemble/tests/regression_tests;
-        ./conda/balsam-setup.sh;
-    fi
+  - python conda/install-balsam.py
+  # - if [[ "{ $TRAVIS_PYTHON_VERSION | cut -c 3 } -ge 6" ]]; then
+  #       git clone https://github.com/balsam-alcf/balsam.git ../balsam;
+  #       cd ../balsam; pip install -e .; cd ../libensemble;
+  #       mv ./conda/test_balsam.py ./libensemble/tests/regression_tests;
+  #       ./conda/balsam-setup.sh;
+  #   fi
 
 
 before_script:
diff --git a/conda/balsam-setup.sh b/conda/configure-balsam-test.sh
similarity index 100%
rename from conda/balsam-setup.sh
rename to conda/configure-balsam-test.sh
diff --git a/conda/install-balsam.py b/conda/install-balsam.py
new file mode 100644
index 000000000..c7aaf4d44
--- /dev/null
+++ b/conda/install-balsam.py
@@ -0,0 +1,14 @@
+import sys
+import os
+import subprocess
+
+balsamclone = 'git clone https://github.com/balsam-alcf/balsam.git ../balsam'
+
+if sys.version[2] >= 6:
+    subprocess.check_call(balsamclone.split())
+    os.chdir('../balsam')
+    subprocess.check_call('pip install -e .'.split())
+    os.chdir('../libensemble')
+    os.rename('./conda/test_balsam.py', 
+              './libensemble/tests/regression_tests/test_balsam.py')
+    subprocess.check_call('./conda/configure-balsam-test.sh')

From 68919a4bef99ed6e24e24f2d2de57fbb07385d3e Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 13 Aug 2019 12:13:44 -0500
Subject: [PATCH 096/644] fixes version check

---
 conda/install-balsam.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index c7aaf4d44..df8356541 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -4,11 +4,11 @@
 
 balsamclone = 'git clone https://github.com/balsam-alcf/balsam.git ../balsam'
 
-if sys.version[2] >= 6:
+if int(sys.version[2]) >= 6:
     subprocess.check_call(balsamclone.split())
     os.chdir('../balsam')
     subprocess.check_call('pip install -e .'.split())
     os.chdir('../libensemble')
-    os.rename('./conda/test_balsam.py', 
+    os.rename('./conda/test_balsam.py',
               './libensemble/tests/regression_tests/test_balsam.py')
     subprocess.check_call('./conda/configure-balsam-test.sh')

From 7ec42ec5eb0f69070133cfd83cdf44505291e5d7 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 13 Aug 2019 13:03:30 -0500
Subject: [PATCH 097/644] moved test to correct starting directory

---
 {libensemble/tests/regression_tests => conda}/test_balsam.py | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename {libensemble/tests/regression_tests => conda}/test_balsam.py (100%)

diff --git a/libensemble/tests/regression_tests/test_balsam.py b/conda/test_balsam.py
similarity index 100%
rename from libensemble/tests/regression_tests/test_balsam.py
rename to conda/test_balsam.py

From 4cf3f471fbe78bea4266993cee0cd140504c650b Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 13 Aug 2019 13:26:10 -0500
Subject: [PATCH 098/644] implements install-balsam script in build_mpich
 script. fixes check_call

---
 conda/install-balsam.py                      | 2 +-
 conda/run_travis_locally/build_mpich_libE.sh | 7 +------
 2 files changed, 2 insertions(+), 7 deletions(-)

diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index df8356541..e4e64ba57 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -11,4 +11,4 @@
     os.chdir('../libensemble')
     os.rename('./conda/test_balsam.py',
               './libensemble/tests/regression_tests/test_balsam.py')
-    subprocess.check_call('./conda/configure-balsam-test.sh')
+    subprocess.check_call(['./conda/configure-balsam-test.sh'])
diff --git a/conda/run_travis_locally/build_mpich_libE.sh b/conda/run_travis_locally/build_mpich_libE.sh
index 47d50ff4e..b5c4361dd 100755
--- a/conda/run_travis_locally/build_mpich_libE.sh
+++ b/conda/run_travis_locally/build_mpich_libE.sh
@@ -11,7 +11,6 @@ export SYSTEM="Linux"         # default - override with -s <OS>
                                 # Options for miniconda - Linux, MacOSX, Windows
 export MPI=MPICH
 export HYDRA_LAUNCHER=fork
-export TESTBALSAM=true
 
 # Allow user to optionally set python version and branch
 # E.g: ". ./build_mpich_libE.sh -p 3.4 -b feature/myfeature"
@@ -86,7 +85,6 @@ conda install nlopt petsc4py petsc mumps-mpi=5.1.2=h5bebb2f_1007 mpi4py scipy $M
 # conda install nlopt || return
 
 # pip install these as the conda installs downgrade pytest on python3.4
-pip install balsam-flow || return
 pip install pytest || return
 pip install pytest-cov || return
 pip install pytest-timeout || return
@@ -97,10 +95,7 @@ pip install coveralls || return
 git clone -b $LIBE_BRANCH https://github.com/Libensemble/libensemble.git || return
 cd libensemble/ || return
 pip install -e . || return
-
-if [[ "$TESTBALSAM" == true ]]; then
-    source ./conda/balsam-setup.sh;
-fi
+python conda/install-balsam.py
 
 libensemble/tests/run-tests.sh
 

From 7544c7f18decc580874f48b723857c0a179d9554 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 13 Aug 2019 13:45:42 -0500
Subject: [PATCH 099/644] check_call() -> os.system()

---
 conda/install-balsam.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index e4e64ba57..8c0645b0f 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -1,3 +1,5 @@
+#! /usr/bin/env python
+
 import sys
 import os
 import subprocess
@@ -11,4 +13,4 @@
     os.chdir('../libensemble')
     os.rename('./conda/test_balsam.py',
               './libensemble/tests/regression_tests/test_balsam.py')
-    subprocess.check_call(['./conda/configure-balsam-test.sh'])
+    os.system('./conda/configure-balsam-test.sh')

From 2aac867eaea207b486a9f9bb41cc8d711282f70d Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 13 Aug 2019 13:55:27 -0500
Subject: [PATCH 100/644] bang bin bash

---
 conda/configure-balsam-test.sh | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/conda/configure-balsam-test.sh b/conda/configure-balsam-test.sh
index aa658cb19..7b1d6b99f 100755
--- a/conda/configure-balsam-test.sh
+++ b/conda/configure-balsam-test.sh
@@ -1,3 +1,5 @@
+#!/bin/bash
+
 export BALSAM_DB_PATH='~/test-balsam'
 sudo chown -R postgres:postgres /var/run/postgresql
 sudo chmod a+w /var/run/postgresql

From 12fc6b92a8b6463e38cc94f849fb34e7dee0a0ba Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 13 Aug 2019 14:21:22 -0500
Subject: [PATCH 101/644] trying to ensure that BALSAM_DB_PATH stays set

---
 .travis.yml             | 2 ++
 conda/install-balsam.py | 2 +-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index de9db6390..a2e0bffe4 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -95,6 +95,8 @@ install:
 
 before_script:
   - flake8 libensemble
+  - echo "export BALSAM_DB_PATH=~/test-balsam" > setbalsampath.sh
+  - source setbalsampath.sh
   # Set conda compilers to use new SDK instead of Travis default.
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
         echo "export CONDA_BUILD_SYSROOT=/Users/travis/build/Libensemble/sdk/MacOSX10.13.sdk" > setenv.sh;
diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index 8c0645b0f..46534168e 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -13,4 +13,4 @@
     os.chdir('../libensemble')
     os.rename('./conda/test_balsam.py',
               './libensemble/tests/regression_tests/test_balsam.py')
-    os.system('./conda/configure-balsam-test.sh')
+    os.system('source ./conda/configure-balsam-test.sh')

From b05286809f64bcac0d8b90ebd1f40625f881b3a1 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 13 Aug 2019 14:26:28 -0500
Subject: [PATCH 102/644] remove redundant source (?)

---
 conda/install-balsam.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index 46534168e..8c0645b0f 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -13,4 +13,4 @@
     os.chdir('../libensemble')
     os.rename('./conda/test_balsam.py',
               './libensemble/tests/regression_tests/test_balsam.py')
-    os.system('source ./conda/configure-balsam-test.sh')
+    os.system('./conda/configure-balsam-test.sh')

From bf495c8e029356ab3aec0f822fc3cdbb685e1c99 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 13 Aug 2019 15:39:24 -0500
Subject: [PATCH 103/644] Updating persistent_uniform_sampling call

---
 libensemble/gen_funcs/persistent_aposmm.py                    | 3 +++
 .../test_6-hump_camel_persistent_uniform_sampling.py          | 4 ++--
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 0952f8298..5746b5364 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -192,6 +192,9 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     """
     # {{{ multiprocessing initialization
 
+    # from libensemble.util.forkpdb import ForkablePdb
+    # ForkablePdb().set_trace()
+
     local_opters = []
     parent_can_read_from_queue = Event()
     comm_queue = Queue()
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py
index c64bb672f..c0eda0790 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py
@@ -41,11 +41,11 @@
              'lb': np.array([-3, -2]),
              'ub': np.array([3, 2])}
 
-alloc_specs = {'alloc_f': alloc_f, 'out': []}
+alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)]}
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
-exit_criteria = {'sim_max': 40, 'elapsed_wallclock_time': 300}
+exit_criteria = {'gen_max': 40, 'elapsed_wallclock_time': 300}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,

From 87c859ee83639e29c264b6ec316d85d7c04c7c5a Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 13 Aug 2019 16:11:38 -0500
Subject: [PATCH 104/644] fix build simfunc path

---
 conda/run_travis_locally/build_mpich_libE.sh             | 1 +
 libensemble/tests/regression_tests/script_test_balsam.py | 3 ++-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/conda/run_travis_locally/build_mpich_libE.sh b/conda/run_travis_locally/build_mpich_libE.sh
index b5c4361dd..2efe9243e 100755
--- a/conda/run_travis_locally/build_mpich_libE.sh
+++ b/conda/run_travis_locally/build_mpich_libE.sh
@@ -96,6 +96,7 @@ git clone -b $LIBE_BRANCH https://github.com/Libensemble/libensemble.git || retu
 cd libensemble/ || return
 pip install -e . || return
 python conda/install-balsam.py
+export BALSAM_DB_PATH=~/test-balsam
 
 libensemble/tests/run-tests.sh
 
diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index 05f413f3b..46c98ed19 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -20,7 +20,8 @@ def build_simfunc():
     import subprocess
     # Build simfunc
     # buildstring='mpif90 -o my_simjob.x my_simjob.f90' # On cray need to use ftn
-    buildstring = 'mpicc -o my_simjob.x libensemble/tests/unit_tests/simdir/my_simjob.c'
+    # buildstring = 'mpicc -o my_simjob.x libensemble/tests/unit_tests/simdir/my_simjob.c'
+    buildstring = 'mpicc -o my_simjob.x ../unit_tests/simdir/my_simjob.c'
     # subprocess.run(buildstring.split(),check=True) #Python3.5+
     subprocess.check_call(buildstring.split())
 

From 85fce8c369c93fdcce1d79cf43e583a1dd2f8c34 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 13 Aug 2019 16:50:39 -0500
Subject: [PATCH 105/644] check if test_balsam already moved, more verbose
 tests, error checking

---
 conda/install-balsam.py                                  | 5 +++--
 conda/run_travis_locally/build_mpich_libE.sh             | 2 +-
 libensemble/tests/regression_tests/script_test_balsam.py | 1 +
 3 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index 8c0645b0f..40489521d 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -11,6 +11,7 @@
     os.chdir('../balsam')
     subprocess.check_call('pip install -e .'.split())
     os.chdir('../libensemble')
-    os.rename('./conda/test_balsam.py',
-              './libensemble/tests/regression_tests/test_balsam.py')
+    if not os.path.isfile('./libensemble/tests/regression_tests/test_balsam.py'):
+        os.rename('./conda/test_balsam.py',
+                  './libensemble/tests/regression_tests/test_balsam.py')
     os.system('./conda/configure-balsam-test.sh')
diff --git a/conda/run_travis_locally/build_mpich_libE.sh b/conda/run_travis_locally/build_mpich_libE.sh
index 2efe9243e..6a560a77f 100755
--- a/conda/run_travis_locally/build_mpich_libE.sh
+++ b/conda/run_travis_locally/build_mpich_libE.sh
@@ -98,7 +98,7 @@ pip install -e . || return
 python conda/install-balsam.py
 export BALSAM_DB_PATH=~/test-balsam
 
-libensemble/tests/run-tests.sh
+libensemble/tests/run-tests.sh -z
 
 echo -e "\n\nScript completed...\n\n"
 set +ex
diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index 46c98ed19..30fc8575b 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -18,6 +18,7 @@
 
 def build_simfunc():
     import subprocess
+    print('Balsam job launched in: {}'.format(os.getcwd()))
     # Build simfunc
     # buildstring='mpif90 -o my_simjob.x my_simjob.f90' # On cray need to use ftn
     # buildstring = 'mpicc -o my_simjob.x libensemble/tests/unit_tests/simdir/my_simjob.c'

From 468777cbebcca62ed704c2fe3cfc2b989245575d Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 14 Aug 2019 09:26:54 -0500
Subject: [PATCH 106/644] fix buildstring path (again)

---
 libensemble/tests/regression_tests/script_test_balsam.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index 30fc8575b..9677908a0 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -21,8 +21,8 @@ def build_simfunc():
     print('Balsam job launched in: {}'.format(os.getcwd()))
     # Build simfunc
     # buildstring='mpif90 -o my_simjob.x my_simjob.f90' # On cray need to use ftn
-    # buildstring = 'mpicc -o my_simjob.x libensemble/tests/unit_tests/simdir/my_simjob.c'
-    buildstring = 'mpicc -o my_simjob.x ../unit_tests/simdir/my_simjob.c'
+    buildstring = 'mpicc -o my_simjob.x libensemble/tests/unit_tests/simdir/my_simjob.c'
+    # buildstring = 'mpicc -o my_simjob.x ../unit_tests/simdir/my_simjob.c'
     # subprocess.run(buildstring.split(),check=True) #Python3.5+
     subprocess.check_call(buildstring.split())
 

From c076a0cce2c6ef135c906dc3387188bd79b50c78 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 14 Aug 2019 10:12:12 -0500
Subject: [PATCH 107/644] parse_args to address errors when running through
 run-tests

---
 conda/test_balsam.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 016588960..2bb2061c9 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -1,7 +1,7 @@
 import subprocess
 import os
 import balsam
-
+from libensemble.tests.regression_tests.common import parse_args
 # Balsam is meant for HPC systems that commonly distribute jobs across many
 #   nodes. Due to the nature of testing Balsam on local or CI systems which usually
 #   only contain a single node, we need to change Balsam's default worker setup
@@ -13,6 +13,8 @@
 
 # MODIFY BALSAM WORKERGROUP
 
+nworkers, is_master, libE_specs, _ = parse_args() # None of these will be used here
+
 workerfile = 'worker.py'
 
 home = os.getcwd()

From 73ba84e572b447be6c70b2f9c84e924ccc7224be Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 14 Aug 2019 10:21:50 -0500
Subject: [PATCH 108/644] flake8 and comments

---
 conda/test_balsam.py                                     | 5 ++++-
 libensemble/tests/regression_tests/script_test_balsam.py | 4 +++-
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 2bb2061c9..83b2435fe 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -2,6 +2,7 @@
 import os
 import balsam
 from libensemble.tests.regression_tests.common import parse_args
+
 # Balsam is meant for HPC systems that commonly distribute jobs across many
 #   nodes. Due to the nature of testing Balsam on local or CI systems which usually
 #   only contain a single node, we need to change Balsam's default worker setup
@@ -13,7 +14,7 @@
 
 # MODIFY BALSAM WORKERGROUP
 
-nworkers, is_master, libE_specs, _ = parse_args() # None of these will be used here
+nworkers, is_master, libE_specs, _ = parse_args()  # None of these will be used here
 
 workerfile = 'worker.py'
 
@@ -37,6 +38,8 @@
 os.chdir(home)
 
 # EXECUTE BALSAM JOB
+# By this point, script_test_balsam.py has been submitted as an app and job to Balsam
+# This line launches the queued job in the Balsam database
 
 runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
 subprocess.check_call(runstr.split())
diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index 9677908a0..dd99e0a9b 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -1,4 +1,6 @@
-# This script is meant to be submitted to Balsam for execution
+# This script is submitted as an app to Balsam, and jobs are launched
+#   based on this app. This submission is via 'balsam launch' executed
+#   in the test_balsam.py script.
 
 import os
 import numpy as np

From 48810710e098c57da1f697b7ac973f5bae419355 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 14 Aug 2019 11:50:09 -0500
Subject: [PATCH 109/644] build script back to original settings, new
 subprocess call function attempt

---
 conda/run_travis_locally/build_mpich_libE.sh | 4 ++--
 conda/test_balsam.py                         | 5 +++--
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/conda/run_travis_locally/build_mpich_libE.sh b/conda/run_travis_locally/build_mpich_libE.sh
index 6a560a77f..aab538e09 100755
--- a/conda/run_travis_locally/build_mpich_libE.sh
+++ b/conda/run_travis_locally/build_mpich_libE.sh
@@ -5,8 +5,8 @@
 # -x echo commands
 set -x # problem with this - loads of conda internal commands shown - overwhelming.
 
-export PYTHON_VERSION=3.6       # default - override with -p <version>
-export LIBE_BRANCH="experimental/balsam-on-travis"    # default - override with -b <branchname>
+export PYTHON_VERSION=3.7       # default - override with -p <version>
+export LIBE_BRANCH="develop"    # default - override with -b <branchname>
 export SYSTEM="Linux"         # default - override with -s <OS>
                                 # Options for miniconda - Linux, MacOSX, Windows
 export MPI=MPICH
diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 83b2435fe..c0933cece 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -14,7 +14,8 @@
 
 # MODIFY BALSAM WORKERGROUP
 
-nworkers, is_master, libE_specs, _ = parse_args()  # None of these will be used here
+# None of these will be used here. Preventative measure against run-tests bugs
+nworkers, is_master, libE_specs, _ = parse_args()
 
 workerfile = 'worker.py'
 
@@ -42,4 +43,4 @@
 # This line launches the queued job in the Balsam database
 
 runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
-subprocess.check_call(runstr.split())
+subprocess.check_output(runstr.split())

From d97fa1b02959381a5303c551936a7cac091f0350 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 14 Aug 2019 15:07:07 -0500
Subject: [PATCH 110/644] source testing script for env var availability

---
 .travis.yml                                  | 2 +-
 conda/run_travis_locally/build_mpich_libE.sh | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index a2e0bffe4..3dab30afc 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -105,7 +105,7 @@ before_script:
 
 # Run test (-z show output)
 script:
-  - libensemble/tests/run-tests.sh -z
+  - source libensemble/tests/run-tests.sh -z
 
 # Coverage
 after_success:
diff --git a/conda/run_travis_locally/build_mpich_libE.sh b/conda/run_travis_locally/build_mpich_libE.sh
index aab538e09..960744597 100755
--- a/conda/run_travis_locally/build_mpich_libE.sh
+++ b/conda/run_travis_locally/build_mpich_libE.sh
@@ -98,7 +98,7 @@ pip install -e . || return
 python conda/install-balsam.py
 export BALSAM_DB_PATH=~/test-balsam
 
-libensemble/tests/run-tests.sh -z
+source libensemble/tests/run-tests.sh -z
 
 echo -e "\n\nScript completed...\n\n"
 set +ex

From 69a2bfc8ce52833958f6f2caaa3829415a606744 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 14 Aug 2019 15:27:34 -0500
Subject: [PATCH 111/644] cleanup and comments

---
 .travis.yml                                   |  7 ---
 conda/configure-balsam-test.sh                | 23 +++++--
 conda/test_balsam.py                          | 63 ++++++++++---------
 .../regression_tests/script_test_balsam.py    | 24 +------
 4 files changed, 52 insertions(+), 65 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 3dab30afc..c01b6bc76 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -85,13 +85,6 @@ install:
   - mpiexec --version # Show MPI library details
   - pip install -e .
   - python conda/install-balsam.py
-  # - if [[ "{ $TRAVIS_PYTHON_VERSION | cut -c 3 } -ge 6" ]]; then
-  #       git clone https://github.com/balsam-alcf/balsam.git ../balsam;
-  #       cd ../balsam; pip install -e .; cd ../libensemble;
-  #       mv ./conda/test_balsam.py ./libensemble/tests/regression_tests;
-  #       ./conda/balsam-setup.sh;
-  #   fi
-
 
 before_script:
   - flake8 libensemble
diff --git a/conda/configure-balsam-test.sh b/conda/configure-balsam-test.sh
index 7b1d6b99f..bce2ed440 100755
--- a/conda/configure-balsam-test.sh
+++ b/conda/configure-balsam-test.sh
@@ -1,11 +1,11 @@
 #!/bin/bash
 
-export BALSAM_DB_PATH='~/test-balsam'
-sudo chown -R postgres:postgres /var/run/postgresql
-sudo chmod a+w /var/run/postgresql
-balsam init ~/test-balsam
-sudo chmod -R 700 ~/test-balsam/balsamdb
-source balsamactivate test-balsam
+# Run this script between each repeated local run of the Balsam
+#   job_control_hworld_balsam test. Besides ensuring that postgres and the
+#   generated Balsam db have the proper permissions, this script flushes previous
+#   apps and jobs in the db before submitting the test_balsam app/job script.
+#
+#   Most of this comes from scaling_tests/forces/balsam_local.sh
 
 export EXE=$PWD/libensemble/tests/regression_tests/script_test_balsam.py
 export NUM_WORKERS=2
@@ -14,9 +14,20 @@ export LIBE_WALLCLOCK=3
 export THIS_DIR=$PWD
 export SCRIPT_BASENAME=script_test_balsam
 
+# Set proper permissions, initialize Balsam DB, activate DB
+export BALSAM_DB_PATH='~/test-balsam'
+sudo chown -R postgres:postgres /var/run/postgresql
+sudo chmod a+w /var/run/postgresql
+balsam init ~/test-balsam
+sudo chmod -R 700 ~/test-balsam/balsamdb
+source balsamactivate test-balsam
+
+# Refresh DB
 balsam rm apps --all --force
 balsam rm jobs --all --force
 
+# Submit script_test_balsam as app
 balsam app --name $SCRIPT_BASENAME.app --exec $EXE --desc "Run $SCRIPT_BASENAME"
 
+# Submit job based on script_test_balsam app
 balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --wall-time-minutes $LIBE_WALLCLOCK --num-nodes 1 --ranks-per-node $((NUM_WORKERS+1)) --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index c0933cece..07e92c759 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -3,44 +3,49 @@
 import balsam
 from libensemble.tests.regression_tests.common import parse_args
 
-# Balsam is meant for HPC systems that commonly distribute jobs across many
-#   nodes. Due to the nature of testing Balsam on local or CI systems which usually
-#   only contain a single node, we need to change Balsam's default worker setup
-#   so multiple workers can be run on a single node (until this feature is [hopefully] added!).
-#   For our purposes, we append ten workers to Balsam's WorkerGroup
-
 # TESTSUITE_COMMS: local
 # TESTSUITE_NPROCS: 3
 
-# MODIFY BALSAM WORKERGROUP
+new_lines = ["        for idx in range(10):\n",
+             "            w = Worker(1, host_type='DEFAULT', num_nodes=1)\n",
+             "            self.workers.append(w)\n"]
+
+
+def modify_Balsam_worker():
+    # Balsam is meant for HPC systems that commonly distribute jobs across many
+    #   nodes. Due to the nature of testing Balsam on local or CI systems which usually
+    #   only contain a single node, we need to change Balsam's default worker setup
+    #   so multiple workers can be run on a single node (until this feature is [hopefully] added!).
+    #   For our purposes, we append ten workers to Balsam's WorkerGroup
 
-# None of these will be used here. Preventative measure against run-tests bugs
-nworkers, is_master, libE_specs, _ = parse_args()
+    workerfile = 'worker.py'
+    home = os.getcwd()
+    balsam_worker_path = os.path.dirname(balsam.__file__) + '/launcher'
+    os.chdir(balsam_worker_path)
 
-workerfile = 'worker.py'
+    with open(workerfile, 'r') as f:
+        lines = f.readlines()
 
-home = os.getcwd()
-balsam_worker_path = os.path.dirname(balsam.__file__) + '/launcher'
-os.chdir(balsam_worker_path)
+    if lines[-3] != new_lines[0]:
+        lines = lines[:-2]  # effectively inserting new_lines[0] above
+        lines.extend(new_lines)
 
-with open(workerfile, 'r') as f:
-    lines = f.readlines()
+    with open(workerfile, 'w') as f:
+        for line in lines:
+            f.write(line)
 
-if lines[-3] != "        for idx in range(10):\n":
-    lines = lines[:-2]  # Will re-add these lines
-    lines.extend(["        for idx in range(10):\n",
-                  "            w = Worker(1, host_type='DEFAULT', num_nodes=1)\n",
-                  "            self.workers.append(w)\n"])
+    os.chdir(home)
 
-with open(workerfile, 'w') as f:
-    for line in lines:
-        f.write(line)
 
-os.chdir(home)
+def run_Balsam_job():
+    # Executes Balsam Job
+    # By this point, script_test_balsam.py has been submitted as an app and job to Balsam
+    # This line launches the queued job in the Balsam database
+    runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
+    subprocess.check_output(runstr.split())
 
-# EXECUTE BALSAM JOB
-# By this point, script_test_balsam.py has been submitted as an app and job to Balsam
-# This line launches the queued job in the Balsam database
 
-runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
-subprocess.check_output(runstr.split())
+if __name__ == '__main__':
+    nworkers, is_master, libE_specs, _ = parse_args()  # None used. Bug-prevention
+    modify_Balsam_worker()
+    run_Balsam_job()
diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index dd99e0a9b..ba3a15ff9 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -21,11 +21,7 @@
 def build_simfunc():
     import subprocess
     print('Balsam job launched in: {}'.format(os.getcwd()))
-    # Build simfunc
-    # buildstring='mpif90 -o my_simjob.x my_simjob.f90' # On cray need to use ftn
     buildstring = 'mpicc -o my_simjob.x libensemble/tests/unit_tests/simdir/my_simjob.c'
-    # buildstring = 'mpicc -o my_simjob.x ../unit_tests/simdir/my_simjob.c'
-    # subprocess.run(buildstring.split(),check=True) #Python3.5+
     subprocess.check_call(buildstring.split())
 
 
@@ -40,15 +36,8 @@ def build_simfunc():
 logical_cores = multiprocessing.cpu_count()
 cores_all_jobs = nworkers*cores_per_job
 
-if cores_all_jobs > logical_cores:
-    use_auto_resources = False
-    mess_resources = 'Oversubscribing - auto_resources set to False'
-else:
-    use_auto_resources = True
-    mess_resources = 'Auto_resources set to True'
-
 if is_master:
-    print('\nCores req: {} Cores avail: {}\n  {}\n'.format(cores_all_jobs, logical_cores, mess_resources))
+    print('\nCores req: {} Cores avail: {}\n'.format(cores_all_jobs, logical_cores))
 
 sim_app = './my_simjob.x'
 if not os.path.isfile(sim_app):
@@ -106,16 +95,5 @@ def build_simfunc():
 
     # Repeat N times for N workers and insert Completed at start for generator
     calc_desc_list = ['Completed'] + calc_desc_list_in*nworkers
-    # script_name = os.path.splitext(os.path.basename(__file__))[0]
-    # short_name = script_name.split("test_", 1).pop()
-    # summary_file_name = short_name + '.libe_summary.txt'
-    # with open(summary_file_name,'r') as f:
-    #     i=0
-    #     for line in f:
-    #         if "Status:" in line:
-    #             _, file_status = line.partition("Status:")[::2]
-    #             print("Expected: {}   Filestatus: {}".format(calc_desc_list[i], file_status.strip()))
-    #             assert calc_desc_list[i] == file_status.strip(), "Status does not match file"
-    #             i+=1
 
     print("\n\n\nRun completed.")

From 10b79bec87a198e9bda8d9a5e47e690910406181 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 14 Aug 2019 15:32:07 -0500
Subject: [PATCH 112/644] trying different calling method

---
 conda/test_balsam.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 07e92c759..304827d50 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -42,7 +42,7 @@ def run_Balsam_job():
     # By this point, script_test_balsam.py has been submitted as an app and job to Balsam
     # This line launches the queued job in the Balsam database
     runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
-    subprocess.check_output(runstr.split())
+    subprocess.call(runstr.split())
 
 
 if __name__ == '__main__':

From 3aed4ccf6ad9bfb3996c79f169232c6c08bdfb20 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 15 Aug 2019 09:41:19 -0500
Subject: [PATCH 113/644] reorganize test_balsam, adds more descriptive print
 statements

---
 conda/run_travis_locally/build_mpich_libE.sh |  2 +-
 conda/test_balsam.py                         | 58 +++++++++-----------
 2 files changed, 28 insertions(+), 32 deletions(-)

diff --git a/conda/run_travis_locally/build_mpich_libE.sh b/conda/run_travis_locally/build_mpich_libE.sh
index 960744597..34dddabbf 100755
--- a/conda/run_travis_locally/build_mpich_libE.sh
+++ b/conda/run_travis_locally/build_mpich_libE.sh
@@ -6,7 +6,7 @@
 set -x # problem with this - loads of conda internal commands shown - overwhelming.
 
 export PYTHON_VERSION=3.7       # default - override with -p <version>
-export LIBE_BRANCH="develop"    # default - override with -b <branchname>
+export LIBE_BRANCH="experimental/balsam-on-travis"    # default - override with -b <branchname>
 export SYSTEM="Linux"         # default - override with -s <OS>
                                 # Options for miniconda - Linux, MacOSX, Windows
 export MPI=MPICH
diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 304827d50..1097027e0 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -10,42 +10,38 @@
              "            w = Worker(1, host_type='DEFAULT', num_nodes=1)\n",
              "            self.workers.append(w)\n"]
 
+nworkers, is_master, libE_specs, _ = parse_args()  # None used. Bug-prevention
 
-def modify_Balsam_worker():
-    # Balsam is meant for HPC systems that commonly distribute jobs across many
-    #   nodes. Due to the nature of testing Balsam on local or CI systems which usually
-    #   only contain a single node, we need to change Balsam's default worker setup
-    #   so multiple workers can be run on a single node (until this feature is [hopefully] added!).
-    #   For our purposes, we append ten workers to Balsam's WorkerGroup
 
-    workerfile = 'worker.py'
-    home = os.getcwd()
-    balsam_worker_path = os.path.dirname(balsam.__file__) + '/launcher'
-    os.chdir(balsam_worker_path)
+# Balsam is meant for HPC systems that commonly distribute jobs across many
+#   nodes. Due to the nature of testing Balsam on local or CI systems which usually
+#   only contain a single node, we need to change Balsam's default worker setup
+#   so multiple workers can be run on a single node (until this feature is [hopefully] added!).
+#   For our purposes, we append ten workers to Balsam's WorkerGroup
+print("Currently in {}. Beginning Balsam worker modification".format(os.getcwd()))
+workerfile = 'worker.py'
+home = os.getcwd()
+balsam_worker_path = os.path.dirname(balsam.__file__) + '/launcher'
+os.chdir(balsam_worker_path)
 
-    with open(workerfile, 'r') as f:
-        lines = f.readlines()
+with open(workerfile, 'r') as f:
+    lines = f.readlines()
 
-    if lines[-3] != new_lines[0]:
-        lines = lines[:-2]  # effectively inserting new_lines[0] above
-        lines.extend(new_lines)
+if lines[-3] != new_lines[0]:
+    lines = lines[:-2]  # effectively inserting new_lines[0] above
+    lines.extend(new_lines)
 
-    with open(workerfile, 'w') as f:
-        for line in lines:
-            f.write(line)
+with open(workerfile, 'w') as f:
+    for line in lines:
+        f.write(line)
 
-    os.chdir(home)
+print("Modified worker file in {}".format(os.getcwd()))
+os.chdir(home)
 
 
-def run_Balsam_job():
-    # Executes Balsam Job
-    # By this point, script_test_balsam.py has been submitted as an app and job to Balsam
-    # This line launches the queued job in the Balsam database
-    runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
-    subprocess.call(runstr.split())
-
-
-if __name__ == '__main__':
-    nworkers, is_master, libE_specs, _ = parse_args()  # None used. Bug-prevention
-    modify_Balsam_worker()
-    run_Balsam_job()
+# Executes Balsam Job
+# By this point, script_test_balsam.py has been submitted as an app and job to Balsam
+# This line launches the queued job in the Balsam database
+runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
+print('Executing Balsam job with command: {}'.format(runstr))
+subprocess.call(runstr.split())

From de3a552cf68bc80d3e9a16fd847c4853360da23b Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 15 Aug 2019 10:45:37 -0500
Subject: [PATCH 114/644] trying sleep

---
 conda/test_balsam.py | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 1097027e0..2810af145 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -1,6 +1,7 @@
 import subprocess
 import os
 import balsam
+import time
 from libensemble.tests.regression_tests.common import parse_args
 
 # TESTSUITE_COMMS: local
@@ -12,6 +13,8 @@
 
 nworkers, is_master, libE_specs, _ = parse_args()  # None used. Bug-prevention
 
+print('Sleeping for a couple seconds (just in case)')
+time.sleep(5)
 
 # Balsam is meant for HPC systems that commonly distribute jobs across many
 #   nodes. Due to the nature of testing Balsam on local or CI systems which usually
@@ -45,3 +48,5 @@
 runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
 print('Executing Balsam job with command: {}'.format(runstr))
 subprocess.call(runstr.split())
+
+os.chdir('~/test-balsam/data/')

From 5eece5aa7397ec8c78d35beabc7a15f9724916fe Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 15 Aug 2019 12:13:49 -0500
Subject: [PATCH 115/644] modify Balsam worker moved to common. Adding test
 output from DB output directory

---
 conda/test_balsam.py                         | 32 +++++---------------
 libensemble/tests/regression_tests/common.py | 32 ++++++++++++++++++++
 2 files changed, 39 insertions(+), 25 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 2810af145..c2c128826 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -2,15 +2,11 @@
 import os
 import balsam
 import time
-from libensemble.tests.regression_tests.common import parse_args
+from libensemble.tests.regression_tests.common import parse_args, modify_Balsam_worker
 
 # TESTSUITE_COMMS: local
 # TESTSUITE_NPROCS: 3
 
-new_lines = ["        for idx in range(10):\n",
-             "            w = Worker(1, host_type='DEFAULT', num_nodes=1)\n",
-             "            self.workers.append(w)\n"]
-
 nworkers, is_master, libE_specs, _ = parse_args()  # None used. Bug-prevention
 
 print('Sleeping for a couple seconds (just in case)')
@@ -22,25 +18,7 @@
 #   so multiple workers can be run on a single node (until this feature is [hopefully] added!).
 #   For our purposes, we append ten workers to Balsam's WorkerGroup
 print("Currently in {}. Beginning Balsam worker modification".format(os.getcwd()))
-workerfile = 'worker.py'
-home = os.getcwd()
-balsam_worker_path = os.path.dirname(balsam.__file__) + '/launcher'
-os.chdir(balsam_worker_path)
-
-with open(workerfile, 'r') as f:
-    lines = f.readlines()
-
-if lines[-3] != new_lines[0]:
-    lines = lines[:-2]  # effectively inserting new_lines[0] above
-    lines.extend(new_lines)
-
-with open(workerfile, 'w') as f:
-    for line in lines:
-        f.write(line)
-
-print("Modified worker file in {}".format(os.getcwd()))
-os.chdir(home)
-
+modify_Balsam_worker()
 
 # Executes Balsam Job
 # By this point, script_test_balsam.py has been submitted as an app and job to Balsam
@@ -49,4 +27,8 @@
 print('Executing Balsam job with command: {}'.format(runstr))
 subprocess.call(runstr.split())
 
-os.chdir('~/test-balsam/data/')
+os.chdir('~/test-balsam/data/libe_test-balsam/job_script_test_balsam_*')
+with open('job_script_test_balsam.out', 'r') as f:
+    lines = f.readlines()
+for line in lines:
+    print(line)
diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index 1b21883aa..41fc4bbd7 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -170,3 +170,35 @@ def build_simfunc():
     buildstring = 'mpicc -o my_simjob.x ../unit_tests/simdir/my_simjob.c'
     # subprocess.run(buildstring.split(),check=True) #Python3.5+
     subprocess.check_call(buildstring.split())
+
+
+def modify_Balsam_worker():
+    # Balsam is meant for HPC systems that commonly distribute jobs across many
+    #   nodes. Due to the nature of testing Balsam on local or CI systems which usually
+    #   only contain a single node, we need to change Balsam's default worker setup
+    #   so multiple workers can be run on a single node (until this feature is [hopefully] added!).
+    #   For our purposes, we append ten workers to Balsam's WorkerGroup
+    import balsam
+
+    new_lines = ["        for idx in range(10):\n",
+                 "            w = Worker(1, host_type='DEFAULT', num_nodes=1)\n",
+                 "            self.workers.append(w)\n"]
+
+    workerfile = 'worker.py'
+    home = os.getcwd()
+    balsam_worker_path = os.path.dirname(balsam.__file__) + '/launcher'
+    os.chdir(balsam_worker_path)
+
+    with open(workerfile, 'r') as f:
+        lines = f.readlines()
+
+    if lines[-3] != new_lines[0]:
+        lines = lines[:-2]  # effectively inserting new_lines[0] above
+        lines.extend(new_lines)
+
+    with open(workerfile, 'w') as f:
+        for line in lines:
+            f.write(line)
+
+    print("Modified worker file in {}".format(os.getcwd()))
+    os.chdir(home)

From 65f1bd63fee076303ca40959acc503b7a3cdac31 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 15 Aug 2019 12:22:18 -0500
Subject: [PATCH 116/644] flake8

---
 conda/test_balsam.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index c2c128826..cee4ed886 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -1,6 +1,5 @@
 import subprocess
 import os
-import balsam
 import time
 from libensemble.tests.regression_tests.common import parse_args, modify_Balsam_worker
 

From 39819bff8220716cc58a30817b6e20c3650cd865 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 15 Aug 2019 13:18:27 -0500
Subject: [PATCH 117/644] print call_process error messages (if any)

---
 conda/test_balsam.py | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index cee4ed886..16e7cb540 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -24,10 +24,17 @@
 # This line launches the queued job in the Balsam database
 runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
 print('Executing Balsam job with command: {}'.format(runstr))
-subprocess.call(runstr.split())
+try:
+    subprocess.check_output(runstr.split())
+except subprocess.CalledProcessError as e:
+    print e.output
+
+curdir = os.getcwd()
 
 os.chdir('~/test-balsam/data/libe_test-balsam/job_script_test_balsam_*')
 with open('job_script_test_balsam.out', 'r') as f:
     lines = f.readlines()
 for line in lines:
     print(line)
+
+os.chdir(curdir)

From d9858b45cc8b53ff7401ebc3a19c9e0e7ba4e730 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 15 Aug 2019 13:29:00 -0500
Subject: [PATCH 118/644] flake8

---
 conda/test_balsam.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 16e7cb540..42e081494 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -27,7 +27,7 @@
 try:
     subprocess.check_output(runstr.split())
 except subprocess.CalledProcessError as e:
-    print e.output
+    print(e.output)
 
 curdir = os.getcwd()
 

From 634943cda3c4d95113ec3442cbf4d3ca4abfe511 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 15 Aug 2019 14:28:19 -0500
Subject: [PATCH 119/644] remove sleep, attempt reading file in home libe dir

---
 conda/test_balsam.py | 11 ++---------
 1 file changed, 2 insertions(+), 9 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 42e081494..3e29f2f49 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -8,9 +8,6 @@
 
 nworkers, is_master, libE_specs, _ = parse_args()  # None used. Bug-prevention
 
-print('Sleeping for a couple seconds (just in case)')
-time.sleep(5)
-
 # Balsam is meant for HPC systems that commonly distribute jobs across many
 #   nodes. Due to the nature of testing Balsam on local or CI systems which usually
 #   only contain a single node, we need to change Balsam's default worker setup
@@ -29,12 +26,8 @@
 except subprocess.CalledProcessError as e:
     print(e.output)
 
-curdir = os.getcwd()
-
-os.chdir('~/test-balsam/data/libe_test-balsam/job_script_test_balsam_*')
-with open('job_script_test_balsam.out', 'r') as f:
+print('Attempting to print Balsam job output')
+with open('../../../job_script_test_balsam.out', 'r') as f:
     lines = f.readlines()
 for line in lines:
     print(line)
-
-os.chdir(curdir)

From bfa6ce2bd17dab3426c3f4c0df6d06210ad60afa Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 15 Aug 2019 14:33:46 -0500
Subject: [PATCH 120/644] flake8

---
 conda/test_balsam.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 3e29f2f49..740414475 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -1,6 +1,5 @@
 import subprocess
 import os
-import time
 from libensemble.tests.regression_tests.common import parse_args, modify_Balsam_worker
 
 # TESTSUITE_COMMS: local

From 8f978f042632485c081fb2702d3d0ecc964d3933 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 15 Aug 2019 15:08:20 -0500
Subject: [PATCH 121/644] newer calling function

---
 conda/test_balsam.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 740414475..dc1385624 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -21,7 +21,7 @@
 runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
 print('Executing Balsam job with command: {}'.format(runstr))
 try:
-    subprocess.check_output(runstr.split())
+    subprocess.run(runstr.split(), check=True)
 except subprocess.CalledProcessError as e:
     print(e.output)
 

From e47bfd8e5017a587b49b414447ff699a5360df99 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 15 Aug 2019 15:21:01 -0500
Subject: [PATCH 122/644] attempting without try block

---
 conda/test_balsam.py | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index dc1385624..cd667d566 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -20,10 +20,12 @@
 # This line launches the queued job in the Balsam database
 runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
 print('Executing Balsam job with command: {}'.format(runstr))
-try:
-    subprocess.run(runstr.split(), check=True)
-except subprocess.CalledProcessError as e:
-    print(e.output)
+# try:
+#     subprocess.run(runstr.split(), check=True)
+# except subprocess.CalledProcessError as cpe:
+#     print(cpe.output)
+
+subprocess.run(runstr.split())
 
 print('Attempting to print Balsam job output')
 with open('../../../job_script_test_balsam.out', 'r') as f:

From 1deefc8050a42f22c46dc061a581d43287dc6fe3 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 15 Aug 2019 15:42:06 -0500
Subject: [PATCH 123/644] Trying longer timeout limit. More error checking,
 subprocess instead of os.system

---
 conda/install-balsam.py        |  3 ++-
 conda/test_balsam.py           | 22 ++++++++++------------
 libensemble/tests/run-tests.sh |  2 +-
 3 files changed, 13 insertions(+), 14 deletions(-)

diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index 40489521d..2e18a9938 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -14,4 +14,5 @@
     if not os.path.isfile('./libensemble/tests/regression_tests/test_balsam.py'):
         os.rename('./conda/test_balsam.py',
                   './libensemble/tests/regression_tests/test_balsam.py')
-    os.system('./conda/configure-balsam-test.sh')
+    # os.system('./conda/configure-balsam-test.sh')
+    subprocess.run('./conda/configure-balsam-test.sh'.split())
diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index cd667d566..1c2dce9b7 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -20,15 +20,13 @@
 # This line launches the queued job in the Balsam database
 runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
 print('Executing Balsam job with command: {}'.format(runstr))
-# try:
-#     subprocess.run(runstr.split(), check=True)
-# except subprocess.CalledProcessError as cpe:
-#     print(cpe.output)
-
-subprocess.run(runstr.split())
-
-print('Attempting to print Balsam job output')
-with open('../../../job_script_test_balsam.out', 'r') as f:
-    lines = f.readlines()
-for line in lines:
-    print(line)
+try:
+    subprocess.run(runstr.split(), check=True)
+except subprocess.CalledProcessError as cpe:
+    print(cpe.output)
+else:
+    print('Attempting to print Balsam job output')
+    with open('../../../job_script_test_balsam.out', 'r') as f:
+        lines = f.readlines()
+    for line in lines:
+        print(line)
diff --git a/libensemble/tests/run-tests.sh b/libensemble/tests/run-tests.sh
index a48bff814..9a021e11e 100755
--- a/libensemble/tests/run-tests.sh
+++ b/libensemble/tests/run-tests.sh
@@ -378,7 +378,7 @@ if [ "$root_found" = true ]; then
 
     TIMEOUT=""
     if [ -x "$(command -v timeout)" ] ; then
-        TIMEOUT="timeout 60s"
+        TIMEOUT="timeout 90s"
     fi
     #Build any sim/gen source code dependencies here .....
 

From e103c1e2c2564f5ad098a17e0f464cd0538bc623 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 15 Aug 2019 16:00:32 -0500
Subject: [PATCH 124/644] more timing changes

---
 libensemble/tests/regression_tests/script_test_balsam.py | 2 +-
 libensemble/tests/run-tests.sh                           | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index ba3a15ff9..cbafad8ad 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -64,7 +64,7 @@ def build_simfunc():
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
-exit_criteria = {'elapsed_wallclock_time': 30}
+exit_criteria = {'elapsed_wallclock_time': 60}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
diff --git a/libensemble/tests/run-tests.sh b/libensemble/tests/run-tests.sh
index 9a021e11e..7b363dc81 100755
--- a/libensemble/tests/run-tests.sh
+++ b/libensemble/tests/run-tests.sh
@@ -378,7 +378,7 @@ if [ "$root_found" = true ]; then
 
     TIMEOUT=""
     if [ -x "$(command -v timeout)" ] ; then
-        TIMEOUT="timeout 90s"
+        TIMEOUT="timeout --preserve-status 60s"
     fi
     #Build any sim/gen source code dependencies here .....
 

From 15b7b9e7dba7f8e3aee6a817354626996f479ca7 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 15 Aug 2019 16:02:27 -0500
Subject: [PATCH 125/644] adds verbosity option to timeout line

---
 libensemble/tests/run-tests.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/run-tests.sh b/libensemble/tests/run-tests.sh
index 7b363dc81..0e31e0e30 100755
--- a/libensemble/tests/run-tests.sh
+++ b/libensemble/tests/run-tests.sh
@@ -378,7 +378,7 @@ if [ "$root_found" = true ]; then
 
     TIMEOUT=""
     if [ -x "$(command -v timeout)" ] ; then
-        TIMEOUT="timeout --preserve-status 60s"
+        TIMEOUT="timeout --preserve-status --verbose 60s"
     fi
     #Build any sim/gen source code dependencies here .....
 

From 94ac6e0a1142ed371bbea4d5cf3bdf04e6387661 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 15 Aug 2019 16:12:50 -0500
Subject: [PATCH 126/644] removes 'verbose', apparently not supported on the
 included version of timeout

---
 libensemble/tests/run-tests.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/run-tests.sh b/libensemble/tests/run-tests.sh
index 0e31e0e30..7b363dc81 100755
--- a/libensemble/tests/run-tests.sh
+++ b/libensemble/tests/run-tests.sh
@@ -378,7 +378,7 @@ if [ "$root_found" = true ]; then
 
     TIMEOUT=""
     if [ -x "$(command -v timeout)" ] ; then
-        TIMEOUT="timeout --preserve-status --verbose 60s"
+        TIMEOUT="timeout --preserve-status 60s"
     fi
     #Build any sim/gen source code dependencies here .....
 

From a814aa872d081b0888de642090a0473e653a476d Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 15 Aug 2019 16:35:12 -0500
Subject: [PATCH 127/644] timeout increased again, removes preserve status

---
 libensemble/tests/run-tests.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/run-tests.sh b/libensemble/tests/run-tests.sh
index 7b363dc81..9a021e11e 100755
--- a/libensemble/tests/run-tests.sh
+++ b/libensemble/tests/run-tests.sh
@@ -378,7 +378,7 @@ if [ "$root_found" = true ]; then
 
     TIMEOUT=""
     if [ -x "$(command -v timeout)" ] ; then
-        TIMEOUT="timeout --preserve-status 60s"
+        TIMEOUT="timeout 90s"
     fi
     #Build any sim/gen source code dependencies here .....
 

From 7ea782674d8051fb5a97545391f30f98e80851d3 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 15 Aug 2019 16:55:16 -0500
Subject: [PATCH 128/644] adjusts balsam job script test timing, better checks
 for output file

---
 conda/test_balsam.py                                  | 11 ++++++++---
 .../tests/regression_tests/script_test_balsam.py      |  2 +-
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 1c2dce9b7..5bfe42e21 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -24,9 +24,14 @@
     subprocess.run(runstr.split(), check=True)
 except subprocess.CalledProcessError as cpe:
     print(cpe.output)
-else:
-    print('Attempting to print Balsam job output')
-    with open('../../../job_script_test_balsam.out', 'r') as f:
+
+print('Attempting to print Balsam job output')
+outfile = '../../../job_script_test_balsam.out'
+if os.path.isfile(outfile):
+    print('Balsam job output found!')
+    with open(outfile, 'r') as f:
         lines = f.readlines()
     for line in lines:
         print(line)
+else:
+    print('No job output found! Check the Balsam DB?')
diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index cbafad8ad..ba3a15ff9 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -64,7 +64,7 @@ def build_simfunc():
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
-exit_criteria = {'elapsed_wallclock_time': 60}
+exit_criteria = {'elapsed_wallclock_time': 30}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,

From 2eb280076c2e845d01fa2afd6f4aedc6996a2e33 Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 16 Aug 2019 01:13:50 -0500
Subject: [PATCH 129/644] do not allocate memory for sim_id checking

---
 libensemble/history.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/history.py b/libensemble/history.py
index 22f3907e9..eb27fe833 100644
--- a/libensemble/history.py
+++ b/libensemble/history.py
@@ -153,7 +153,7 @@ def update_history_x_in(self, gen_worker, O):
             # gen method is building sim_id or adjusting values in existing sim_id rows.
 
             # Ensure there aren't any gaps in the generated sim_id values:
-            assert np.all(np.in1d(np.arange(self.index, np.max(O['sim_id'])+1), O['sim_id'])), "The generator function has produced sim_id that are not in order."
+            assert all(i in O['sim_id'] for i in range(self.index, np.max(O['sim_id'])+1)), "The generator function has produced sim_id that are not in order."
 
             num_new = len(np.setdiff1d(O['sim_id'], self.H['sim_id']))
 

From 3956d32f8ae82f2a492a5bff7eacfbc94a6d923c Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 16 Aug 2019 03:15:23 -0500
Subject: [PATCH 130/644] adding debug statements removes error?

---
 libensemble/gen_funcs/support.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/libensemble/gen_funcs/support.py b/libensemble/gen_funcs/support.py
index e5084828d..51a6ad065 100644
--- a/libensemble/gen_funcs/support.py
+++ b/libensemble/gen_funcs/support.py
@@ -11,6 +11,8 @@ def sendrecv_mgr_worker_msg(comm, O, status=None):
 def send_mgr_worker_msg(comm, O):
     """Send message from worker to manager.
     """
+    print(25*"-", "Sending {}(SimID: {})".format(O[0][0], O['sim_id']), 25*"-",
+            flush=True)
     D = {'calc_out': O,
          'libE_info': {'persistent': True},
          'calc_status': UNSET_TAG,

From 54b6875533f3ae7dd67b5415639792f9e8713a5f Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 16 Aug 2019 03:22:30 -0500
Subject: [PATCH 131/644] placate flake8

---
 libensemble/gen_funcs/support.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/libensemble/gen_funcs/support.py b/libensemble/gen_funcs/support.py
index 51a6ad065..ed8335a57 100644
--- a/libensemble/gen_funcs/support.py
+++ b/libensemble/gen_funcs/support.py
@@ -11,8 +11,7 @@ def sendrecv_mgr_worker_msg(comm, O, status=None):
 def send_mgr_worker_msg(comm, O):
     """Send message from worker to manager.
     """
-    print(25*"-", "Sending {}(SimID: {})".format(O[0][0], O['sim_id']), 25*"-",
-            flush=True)
+    print(25*"-", "Sending {}(SimID: {})".format(O[0][0], O['sim_id']), 25*"-", flush=True)
     D = {'calc_out': O,
          'libE_info': {'persistent': True},
          'calc_status': UNSET_TAG,

From 0afb244f7d733b94b357b9f6ad6e269470d4a14f Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Fri, 16 Aug 2019 03:35:42 -0500
Subject: [PATCH 132/644] guards the print statement

---
 libensemble/gen_funcs/support.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/libensemble/gen_funcs/support.py b/libensemble/gen_funcs/support.py
index ed8335a57..0ae971e7a 100644
--- a/libensemble/gen_funcs/support.py
+++ b/libensemble/gen_funcs/support.py
@@ -11,7 +11,8 @@ def sendrecv_mgr_worker_msg(comm, O, status=None):
 def send_mgr_worker_msg(comm, O):
     """Send message from worker to manager.
     """
-    print(25*"-", "Sending {}(SimID: {})".format(O[0][0], O['sim_id']), 25*"-", flush=True)
+    if 'sim_id' in O.dtype.names:
+        print(25*"-", "Sending {}(SimID: {})".format(O[0][0], O['sim_id']), 25*"-", flush=True)
     D = {'calc_out': O,
          'libE_info': {'persistent': True},
          'calc_status': UNSET_TAG,

From e35e4d7e89849bee0df13bdcf84965ee128ee8d9 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 09:35:56 -0500
Subject: [PATCH 133/644] trying additional timing adjustment for timeout

---
 libensemble/tests/run-tests.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/run-tests.sh b/libensemble/tests/run-tests.sh
index 9a021e11e..a52a08ca2 100755
--- a/libensemble/tests/run-tests.sh
+++ b/libensemble/tests/run-tests.sh
@@ -378,7 +378,7 @@ if [ "$root_found" = true ]; then
 
     TIMEOUT=""
     if [ -x "$(command -v timeout)" ] ; then
-        TIMEOUT="timeout 90s"
+        TIMEOUT="timeout 120s"
     fi
     #Build any sim/gen source code dependencies here .....
 

From 75ef199179fd86f216687539de64fd7c38d8a351 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 09:55:03 -0500
Subject: [PATCH 134/644] trying 10 whole minutes... trying job execution
 without check

---
 conda/test_balsam.py           | 16 +++++++++++-----
 libensemble/tests/run-tests.sh |  2 +-
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 5bfe42e21..f7744ae63 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -1,5 +1,6 @@
 import subprocess
 import os
+import time
 from libensemble.tests.regression_tests.common import parse_args, modify_Balsam_worker
 
 # TESTSUITE_COMMS: local
@@ -18,12 +19,17 @@
 # Executes Balsam Job
 # By this point, script_test_balsam.py has been submitted as an app and job to Balsam
 # This line launches the queued job in the Balsam database
-runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
+runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1 &'
 print('Executing Balsam job with command: {}'.format(runstr))
-try:
-    subprocess.run(runstr.split(), check=True)
-except subprocess.CalledProcessError as cpe:
-    print(cpe.output)
+# try:
+#     subprocess.run(runstr.split(), check=True)
+# except subprocess.CalledProcessError as cpe:
+#     print(cpe.output)
+
+subprocess.run(runstr.split())
+
+print('Sleeping until the job should complete')
+time.sleep(31)
 
 print('Attempting to print Balsam job output')
 outfile = '../../../job_script_test_balsam.out'
diff --git a/libensemble/tests/run-tests.sh b/libensemble/tests/run-tests.sh
index a52a08ca2..4bc69eedf 100755
--- a/libensemble/tests/run-tests.sh
+++ b/libensemble/tests/run-tests.sh
@@ -378,7 +378,7 @@ if [ "$root_found" = true ]; then
 
     TIMEOUT=""
     if [ -x "$(command -v timeout)" ] ; then
-        TIMEOUT="timeout 120s"
+        TIMEOUT="timeout 600s"
     fi
     #Build any sim/gen source code dependencies here .....
 

From 7c12b509fe41c171910ad46ac12b13cd03e61d0f Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 10:07:31 -0500
Subject: [PATCH 135/644] Attempting Popen so test_balsam doesn't wait on
 balsam launcher to complete

---
 conda/test_balsam.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index f7744ae63..239e8df76 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -19,16 +19,16 @@
 # Executes Balsam Job
 # By this point, script_test_balsam.py has been submitted as an app and job to Balsam
 # This line launches the queued job in the Balsam database
-runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1 &'
+runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
 print('Executing Balsam job with command: {}'.format(runstr))
 # try:
 #     subprocess.run(runstr.split(), check=True)
 # except subprocess.CalledProcessError as cpe:
 #     print(cpe.output)
 
-subprocess.run(runstr.split())
+subprocess.Popen(runstr.split())
 
-print('Sleeping until the job should complete')
+print('Sleeping until job should complete')
 time.sleep(31)
 
 print('Attempting to print Balsam job output')

From 50f7d457759cccea241fa9775e1e5b96198d39d3 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 10:42:01 -0500
Subject: [PATCH 136/644] returns to normal timeout interval. testing cycle of
 checking for balsam output

---
 conda/test_balsam.py           | 30 +++++++++++++++---------------
 libensemble/tests/run-tests.sh |  2 +-
 2 files changed, 16 insertions(+), 16 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 239e8df76..47589455f 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -21,23 +21,23 @@
 # This line launches the queued job in the Balsam database
 runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
 print('Executing Balsam job with command: {}'.format(runstr))
-# try:
-#     subprocess.run(runstr.split(), check=True)
-# except subprocess.CalledProcessError as cpe:
-#     print(cpe.output)
 
 subprocess.Popen(runstr.split())
 
-print('Sleeping until job should complete')
-time.sleep(31)
+print('Beginning cycle of checking for Balsam output')
+
+sleeptime = 0
 
-print('Attempting to print Balsam job output')
 outfile = '../../../job_script_test_balsam.out'
-if os.path.isfile(outfile):
-    print('Balsam job output found!')
-    with open(outfile, 'r') as f:
-        lines = f.readlines()
-    for line in lines:
-        print(line)
-else:
-    print('No job output found! Check the Balsam DB?')
+while sleeptime != 56:
+    if os.path.isfile(outfile):
+        print('{}: Balsam job output found!'.format(sleeptime))
+        with open(outfile, 'r') as f:
+            lines = f.readlines()
+        for line in lines:
+            print(line)
+        break
+    else:
+        print('{}: No job output found. Checking again.'.format(sleeptime))
+        sleeptime += 1
+        time.sleep(1)
diff --git a/libensemble/tests/run-tests.sh b/libensemble/tests/run-tests.sh
index 4bc69eedf..a48bff814 100755
--- a/libensemble/tests/run-tests.sh
+++ b/libensemble/tests/run-tests.sh
@@ -378,7 +378,7 @@ if [ "$root_found" = true ]; then
 
     TIMEOUT=""
     if [ -x "$(command -v timeout)" ] ; then
-        TIMEOUT="timeout 600s"
+        TIMEOUT="timeout 60s"
     fi
     #Build any sim/gen source code dependencies here .....
 

From 34a6204bb8a0392dae5b283f51d64ae0b09f618f Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 11:06:08 -0500
Subject: [PATCH 137/644] Trying stdout piping, adjust exit_criteria, check for
 output every 2 seconds

---
 conda/test_balsam.py                                     | 8 ++++----
 libensemble/tests/regression_tests/script_test_balsam.py | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 47589455f..aa952f6a8 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -22,14 +22,14 @@
 runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
 print('Executing Balsam job with command: {}'.format(runstr))
 
-subprocess.Popen(runstr.split())
+subprocess.Popen(runstr.split(), stderr=stdout, stdout=subprocess.PIPE)
 
 print('Beginning cycle of checking for Balsam output')
 
 sleeptime = 0
 
 outfile = '../../../job_script_test_balsam.out'
-while sleeptime != 56:
+while sleeptime != 60:
     if os.path.isfile(outfile):
         print('{}: Balsam job output found!'.format(sleeptime))
         with open(outfile, 'r') as f:
@@ -39,5 +39,5 @@
         break
     else:
         print('{}: No job output found. Checking again.'.format(sleeptime))
-        sleeptime += 1
-        time.sleep(1)
+        sleeptime += 2
+        time.sleep(2)
diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index ba3a15ff9..cbafad8ad 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -64,7 +64,7 @@ def build_simfunc():
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
-exit_criteria = {'elapsed_wallclock_time': 30}
+exit_criteria = {'elapsed_wallclock_time': 60}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,

From 71b1e05eb6c69ce377796a5a305ffe6197ece42e Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 11:15:19 -0500
Subject: [PATCH 138/644] flake8

---
 conda/test_balsam.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index aa952f6a8..b10ccf05f 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -22,7 +22,7 @@
 runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
 print('Executing Balsam job with command: {}'.format(runstr))
 
-subprocess.Popen(runstr.split(), stderr=stdout, stdout=subprocess.PIPE)
+subprocess.Popen(runstr.split(), stderr=subprocess.STDOUT, stdout=subprocess.PIPE)
 
 print('Beginning cycle of checking for Balsam output')
 

From d58db725219da35e1a544907c8816de8638190b2 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 11:19:31 -0500
Subject: [PATCH 139/644] using communicate to check for process errors or
 output

---
 conda/test_balsam.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index b10ccf05f..71d2a82d8 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -22,7 +22,7 @@
 runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
 print('Executing Balsam job with command: {}'.format(runstr))
 
-subprocess.Popen(runstr.split(), stderr=subprocess.STDOUT, stdout=subprocess.PIPE)
+bp = subprocess.Popen(runstr.split(), stderr=subprocess.STDOUT, stdout=subprocess.PIPE)
 
 print('Beginning cycle of checking for Balsam output')
 
@@ -38,6 +38,8 @@
             print(line)
         break
     else:
-        print('{}: No job output found. Checking again.'.format(sleeptime))
+        print('{}: No job output found. Checking again and checking possible stdout or stderr.'.format(sleeptime))
+        outs, errs = bp.communicate()
+        print('{} {}'.format(out, errs))
         sleeptime += 2
         time.sleep(2)

From 01f0d06fb4eb036c8fc5f6e3b92355b9f24925de Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 11:20:36 -0500
Subject: [PATCH 140/644] flake8

---
 conda/test_balsam.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 71d2a82d8..f4dfa246c 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -40,6 +40,6 @@
     else:
         print('{}: No job output found. Checking again and checking possible stdout or stderr.'.format(sleeptime))
         outs, errs = bp.communicate()
-        print('{} {}'.format(out, errs))
+        print('{} {}'.format(outs, errs))
         sleeptime += 2
         time.sleep(2)

From 54974579ec6ad7632698e5619ecbabfa5b327797 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 11:36:04 -0500
Subject: [PATCH 141/644] undoing pip and stderr reading

---
 conda/test_balsam.py | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index f4dfa246c..6f11c47ce 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -22,7 +22,7 @@
 runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
 print('Executing Balsam job with command: {}'.format(runstr))
 
-bp = subprocess.Popen(runstr.split(), stderr=subprocess.STDOUT, stdout=subprocess.PIPE)
+bp = subprocess.Popen(runstr.split())
 
 print('Beginning cycle of checking for Balsam output')
 
@@ -38,8 +38,6 @@
             print(line)
         break
     else:
-        print('{}: No job output found. Checking again and checking possible stdout or stderr.'.format(sleeptime))
-        outs, errs = bp.communicate()
-        print('{} {}'.format(outs, errs))
+        print('{}: No job output found. Checking again.'.format(sleeptime))
         sleeptime += 2
         time.sleep(2)

From d68ed3c95cd79b18fa9414abd064868dcce5d4e3 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 11:47:21 -0500
Subject: [PATCH 142/644] timing adjustments

---
 conda/test_balsam.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 6f11c47ce..058ae9bd7 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -22,14 +22,14 @@
 runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
 print('Executing Balsam job with command: {}'.format(runstr))
 
-bp = subprocess.Popen(runstr.split())
+subprocess.Popen(runstr.split())
 
 print('Beginning cycle of checking for Balsam output')
 
 sleeptime = 0
 
 outfile = '../../../job_script_test_balsam.out'
-while sleeptime != 60:
+while sleeptime != 58:
     if os.path.isfile(outfile):
         print('{}: Balsam job output found!'.format(sleeptime))
         with open(outfile, 'r') as f:
@@ -39,5 +39,5 @@
         break
     else:
         print('{}: No job output found. Checking again.'.format(sleeptime))
-        sleeptime += 2
-        time.sleep(2)
+        sleeptime += 1
+        time.sleep(1)

From 29234762fd10540c509c6cb26fee767491b95f43 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 14:05:46 -0500
Subject: [PATCH 143/644] Improved mechanism to read Balsam DB data dir, wait
 for various output files.

---
 conda/test_balsam.py                          | 23 ++++++++++++++-----
 .../regression_tests/script_test_balsam.py    |  2 +-
 2 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 058ae9bd7..b5f3598f7 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -21,16 +21,25 @@
 # This line launches the queued job in the Balsam database
 runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
 print('Executing Balsam job with command: {}'.format(runstr))
-
 subprocess.Popen(runstr.split())
 
-print('Beginning cycle of checking for Balsam output')
+basedb = os.path.expanduser('~/test-balsam/data/libe_test-balsam')
 
 sleeptime = 0
 
-outfile = '../../../job_script_test_balsam.out'
+while len(os.listdir(basedb)) == 0 and sleeptime != 58:
+    print('{}: Waiting for Job directory'.format(sleeptime))
+    sleeptime += 1
+    time.sleep(1)
+
+# Find output script in Balsam DB
+jobdirname = os.listdir(basedb)[0]
+jobdir = os.path.join(basedb, jobdirname)
+outscript = os.path.join(jobdir, 'job_script_test_balsam.out')
+
+print('Beginning cycle of checking for Balsam output')
 while sleeptime != 58:
-    if os.path.isfile(outfile):
+    if os.path.isfile(outscript):
         print('{}: Balsam job output found!'.format(sleeptime))
         with open(outfile, 'r') as f:
             lines = f.readlines()
@@ -39,5 +48,7 @@
         break
     else:
         print('{}: No job output found. Checking again.'.format(sleeptime))
-        sleeptime += 1
-        time.sleep(1)
+        sleeptime += 2
+        time.sleep(2)
+
+print('Test completed.')
diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index cbafad8ad..ba3a15ff9 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -64,7 +64,7 @@ def build_simfunc():
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
-exit_criteria = {'elapsed_wallclock_time': 60}
+exit_criteria = {'elapsed_wallclock_time': 30}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,

From 5f4b1c8983d82b6c72ba321344dfa358a1d740f4 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 14:08:16 -0500
Subject: [PATCH 144/644] flake8

---
 conda/test_balsam.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index b5f3598f7..4c33cad7f 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -41,7 +41,7 @@
 while sleeptime != 58:
     if os.path.isfile(outscript):
         print('{}: Balsam job output found!'.format(sleeptime))
-        with open(outfile, 'r') as f:
+        with open(outscript, 'r') as f:
             lines = f.readlines()
         for line in lines:
             print(line)

From 54a798c97f3754ef62ea6b55d3fcac0e0eef28bb Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 14:42:22 -0500
Subject: [PATCH 145/644] check for additional directory before continuing

---
 conda/run_travis_locally/build_mpich_libE.sh |  2 +-
 conda/test_balsam.py                         | 10 +++++++---
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/conda/run_travis_locally/build_mpich_libE.sh b/conda/run_travis_locally/build_mpich_libE.sh
index 34dddabbf..8a606502e 100755
--- a/conda/run_travis_locally/build_mpich_libE.sh
+++ b/conda/run_travis_locally/build_mpich_libE.sh
@@ -3,7 +3,7 @@
 # Note for other MPIs may need to install some packages from source (eg. petsc)
 
 # -x echo commands
-set -x # problem with this - loads of conda internal commands shown - overwhelming.
+# set -x # problem with this - loads of conda internal commands shown - overwhelming.
 
 export PYTHON_VERSION=3.7       # default - override with -p <version>
 export LIBE_BRANCH="experimental/balsam-on-travis"    # default - override with -b <branchname>
diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 4c33cad7f..ad892af1d 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -27,17 +27,21 @@
 
 sleeptime = 0
 
+while not os.path.isdir(basedb) and sleeptime != 58:
+    print('{}: Waiting for Workflow directory'.format(sleeptime))
+    sleeptime += 1
+    time.sleep(1)
+
 while len(os.listdir(basedb)) == 0 and sleeptime != 58:
-    print('{}: Waiting for Job directory'.format(sleeptime))
+    print('{}: Waiting for Job Directory'.format(sleeptime))
     sleeptime += 1
     time.sleep(1)
 
-# Find output script in Balsam DB
 jobdirname = os.listdir(basedb)[0]
 jobdir = os.path.join(basedb, jobdirname)
 outscript = os.path.join(jobdir, 'job_script_test_balsam.out')
 
-print('Beginning cycle of checking for Balsam output')
+print('Beginning cycle of checking for Balsam output: {}'.format(outscript))
 while sleeptime != 58:
     if os.path.isfile(outscript):
         print('{}: Balsam job output found!'.format(sleeptime))

From d25d970c72c2f10682a11b8fae8cac89f6747585 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 15:08:30 -0500
Subject: [PATCH 146/644] print every output line as it is written, temporarily
 disable timeout

---
 conda/test_balsam.py           | 11 ++++++-----
 libensemble/tests/run-tests.sh |  3 ++-
 2 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index ad892af1d..16dea588d 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -45,11 +45,12 @@
 while sleeptime != 58:
     if os.path.isfile(outscript):
         print('{}: Balsam job output found!'.format(sleeptime))
-        with open(outscript, 'r') as f:
-            lines = f.readlines()
-        for line in lines:
-            print(line)
-        break
+        with open(outscript, 'r') as f
+            while True:
+                line = f.readline()
+                if not line:
+                    break
+                print(line)
     else:
         print('{}: No job output found. Checking again.'.format(sleeptime))
         sleeptime += 2
diff --git a/libensemble/tests/run-tests.sh b/libensemble/tests/run-tests.sh
index a48bff814..700fe8de9 100755
--- a/libensemble/tests/run-tests.sh
+++ b/libensemble/tests/run-tests.sh
@@ -378,7 +378,8 @@ if [ "$root_found" = true ]; then
 
     TIMEOUT=""
     if [ -x "$(command -v timeout)" ] ; then
-        TIMEOUT="timeout 60s"
+        # TIMEOUT="timeout 60s"
+        TIMEOUT=""
     fi
     #Build any sim/gen source code dependencies here .....
 

From c354daafa7d6ca10405250f1a851eb1176b94c50 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 15:09:43 -0500
Subject: [PATCH 147/644] flake8

---
 conda/test_balsam.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 16dea588d..37bb38c2d 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -45,7 +45,7 @@
 while sleeptime != 58:
     if os.path.isfile(outscript):
         print('{}: Balsam job output found!'.format(sleeptime))
-        with open(outscript, 'r') as f
+        with open(outscript, 'r') as f:
             while True:
                 line = f.readline()
                 if not line:

From 94dbe5798e8e1c207d5d0f5eb1e599327e863601 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 15:18:52 -0500
Subject: [PATCH 148/644] Fixes outscript logic not doing anything until 58
 seconds in!

---
 conda/test_balsam.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 37bb38c2d..97ca1455a 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -27,12 +27,12 @@
 
 sleeptime = 0
 
-while not os.path.isdir(basedb) and sleeptime != 58:
+while not os.path.isdir(basedb) and sleeptime < 58:
     print('{}: Waiting for Workflow directory'.format(sleeptime))
     sleeptime += 1
     time.sleep(1)
 
-while len(os.listdir(basedb)) == 0 and sleeptime != 58:
+while len(os.listdir(basedb)) == 0 and sleeptime < 58:
     print('{}: Waiting for Job Directory'.format(sleeptime))
     sleeptime += 1
     time.sleep(1)
@@ -42,7 +42,7 @@
 outscript = os.path.join(jobdir, 'job_script_test_balsam.out')
 
 print('Beginning cycle of checking for Balsam output: {}'.format(outscript))
-while sleeptime != 58:
+while sleeptime < 58:
     if os.path.isfile(outscript):
         print('{}: Balsam job output found!'.format(sleeptime))
         with open(outscript, 'r') as f:

From 8611dfd538a5474c4606b8bb58b05e288b464905 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 15:44:23 -0500
Subject: [PATCH 149/644] prevent infinite loop, only print new lines

---
 conda/test_balsam.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 97ca1455a..1544d286d 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -44,13 +44,17 @@
 print('Beginning cycle of checking for Balsam output: {}'.format(outscript))
 while sleeptime < 58:
     if os.path.isfile(outscript):
+        sleeptime = 58
         print('{}: Balsam job output found!'.format(sleeptime))
         with open(outscript, 'r') as f:
+            lastline = None
             while True:
                 line = f.readline()
+                if line != lastline:
+                    lastline = line
+                    print(line)
                 if not line:
                     break
-                print(line)
     else:
         print('{}: No job output found. Checking again.'.format(sleeptime))
         sleeptime += 2

From 2de69929073d0bf2ec3df006cbc7a1c5a98c6774 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 16:14:07 -0500
Subject: [PATCH 150/644] reorganize outscript reading logic

---
 conda/test_balsam.py | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 1544d286d..67f6e4de0 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -44,20 +44,25 @@
 print('Beginning cycle of checking for Balsam output: {}'.format(outscript))
 while sleeptime < 58:
     if os.path.isfile(outscript):
-        sleeptime = 58
         print('{}: Balsam job output found!'.format(sleeptime))
-        with open(outscript, 'r') as f:
-            lastline = None
-            while True:
-                line = f.readline()
-                if line != lastline:
-                    lastline = line
-                    print(line)
-                if not line:
-                    break
+        break
     else:
         print('{}: No job output found. Checking again.'.format(sleeptime))
         sleeptime += 2
         time.sleep(2)
 
+fileout = []
+with open(outscript, 'r') as f:
+    lastline = None
+    while True:
+        line = f.readline()
+        if line != lastline:
+            lastline = line
+            fileout.append(line)
+        if not line:
+            break
+
+for line in fileout:
+    print(line)
+
 print('Test completed.')

From 92607fef880989cc5de3f166c9ae41a8999fdcca Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 16:43:20 -0500
Subject: [PATCH 151/644] added continues for perpetual outscript opening until
 fileout len achieved

---
 conda/test_balsam.py | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 67f6e4de0..94c48a108 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -52,15 +52,17 @@
         time.sleep(2)
 
 fileout = []
-with open(outscript, 'r') as f:
-    lastline = None
-    while True:
+lastline = None
+while True:
+    with open(outscript, 'r') as f:
         line = f.readline()
         if line != lastline:
             lastline = line
             fileout.append(line)
-        if not line:
+            continue
+        if not line and len(fileout) > 20:
             break
+        continue
 
 for line in fileout:
     print(line)

From eacacf738073d841e33d77ee8c1a9076b5717475 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 16 Aug 2019 17:14:07 -0500
Subject: [PATCH 152/644] Trying new outscript output by line

---
 conda/test_balsam.py | 23 ++++++++++-------------
 1 file changed, 10 insertions(+), 13 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 94c48a108..aba550a38 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -1,6 +1,7 @@
 import subprocess
 import os
 import time
+import sys
 from libensemble.tests.regression_tests.common import parse_args, modify_Balsam_worker
 
 # TESTSUITE_COMMS: local
@@ -51,20 +52,16 @@
         sleeptime += 2
         time.sleep(2)
 
-fileout = []
-lastline = None
+print('Writing output file to terminal')
+last = 0
 while True:
     with open(outscript, 'r') as f:
-        line = f.readline()
-        if line != lastline:
-            lastline = line
-            fileout.append(line)
-            continue
-        if not line and len(fileout) > 20:
-            break
-        continue
-
-for line in fileout:
-    print(line)
+        f.seek(last)
+        new = f.read()
+        last = f.tell()
+    print(new)
+    sys.stdout.flush()
+    if new == 'Job 4 done on worker 1':
+        break
 
 print('Test completed.')

From 8df8e97a0a484176b411c1a100e61e7ac591b08d Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 19 Aug 2019 09:18:09 -0500
Subject: [PATCH 153/644] adds logic for concluding output printing when last
 line encountered

---
 conda/test_balsam.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index aba550a38..c35d2d17c 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -54,6 +54,7 @@
 
 print('Writing output file to terminal')
 last = 0
+lastline = 'Job 4 done on worker 1'
 while True:
     with open(outscript, 'r') as f:
         f.seek(last)
@@ -61,7 +62,7 @@
         last = f.tell()
     print(new)
     sys.stdout.flush()
-    if new == 'Job 4 done on worker 1':
+    if new[-len(lastline):] == lastline:
         break
 
 print('Test completed.')

From 66ed4878af368dfeaad4c97e5ce324449915aeb7 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 19 Aug 2019 09:39:52 -0500
Subject: [PATCH 154/644] saving print for once final line in log detected

---
 conda/test_balsam.py | 33 +++++++++++++++++++++++++--------
 1 file changed, 25 insertions(+), 8 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index c35d2d17c..e6ef2a5d3 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -24,10 +24,11 @@
 print('Executing Balsam job with command: {}'.format(runstr))
 subprocess.Popen(runstr.split())
 
+# Location of Balsam DB location defined in configure-balsam-test.sh
 basedb = os.path.expanduser('~/test-balsam/data/libe_test-balsam')
 
+# Periodically wait for Workflow and Job directory within Balsam DB
 sleeptime = 0
-
 while not os.path.isdir(basedb) and sleeptime < 58:
     print('{}: Waiting for Workflow directory'.format(sleeptime))
     sleeptime += 1
@@ -38,6 +39,7 @@
     sleeptime += 1
     time.sleep(1)
 
+# Periodically check for Balsam general output
 jobdirname = os.listdir(basedb)[0]
 jobdir = os.path.join(basedb, jobdirname)
 outscript = os.path.join(jobdir, 'job_script_test_balsam.out')
@@ -52,17 +54,32 @@
         sleeptime += 2
         time.sleep(2)
 
-print('Writing output file to terminal')
-last = 0
+# Output from Balsam Job (script_test_balsam.py)
+# print('Writing output file to terminal')
+# last = 0
+# lastline = 'Job 4 done on worker 1'
+# while True:
+#     with open(outscript, 'r') as f:
+#         f.seek(last)
+#         new = f.read()
+#         last = f.tell()
+#     print(new)
+#     sys.stdout.flush()
+#     if new[-len(lastline):] == lastline:
+#         break
+
+
 lastline = 'Job 4 done on worker 1'
 while True:
     with open(outscript, 'r') as f:
-        f.seek(last)
         new = f.read()
-        last = f.tell()
-    print(new)
+        time.sleep(0.5)
+        if new[-len(lastline):] == lastline:
+            break
+
+with open(outscript, 'r') as f:
+    lines = f.read()
+    print(lines)
     sys.stdout.flush()
-    if new[-len(lastline):] == lastline:
-        break
 
 print('Test completed.')

From e9b1df5a97accc371723491973799abe559a1e4f Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 19 Aug 2019 09:58:04 -0500
Subject: [PATCH 155/644] Adds newline character to lastline

---
 conda/test_balsam.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index e6ef2a5d3..e2d67509d 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -69,7 +69,7 @@
 #         break
 
 
-lastline = 'Job 4 done on worker 1'
+lastline = 'Job 4 done on worker 1\n'
 while True:
     with open(outscript, 'r') as f:
         new = f.read()

From 7cef85e311d79fac7a97f982738ae45e7e666d74 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 19 Aug 2019 10:30:36 -0500
Subject: [PATCH 156/644] Moved some prints to prevent redundancy. Attempting
 to prevent constant blank lines and repeating output,

---
 conda/run_travis_locally/build_mpich_libE.sh |  2 +-
 conda/test_balsam.py                         | 25 ++++++++++----------
 2 files changed, 14 insertions(+), 13 deletions(-)

diff --git a/conda/run_travis_locally/build_mpich_libE.sh b/conda/run_travis_locally/build_mpich_libE.sh
index 8a606502e..748059c87 100755
--- a/conda/run_travis_locally/build_mpich_libE.sh
+++ b/conda/run_travis_locally/build_mpich_libE.sh
@@ -5,7 +5,7 @@
 # -x echo commands
 # set -x # problem with this - loads of conda internal commands shown - overwhelming.
 
-export PYTHON_VERSION=3.7       # default - override with -p <version>
+export PYTHON_VERSION=3.6       # default - override with -p <version>
 export LIBE_BRANCH="experimental/balsam-on-travis"    # default - override with -b <branchname>
 export SYSTEM="Linux"         # default - override with -s <OS>
                                 # Options for miniconda - Linux, MacOSX, Windows
diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index e2d67509d..522b99e49 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -29,13 +29,13 @@
 
 # Periodically wait for Workflow and Job directory within Balsam DB
 sleeptime = 0
+print('{}: Waiting for Workflow directory'.format(sleeptime))
 while not os.path.isdir(basedb) and sleeptime < 58:
-    print('{}: Waiting for Workflow directory'.format(sleeptime))
     sleeptime += 1
     time.sleep(1)
 
+print('{}: Waiting for Job Directory'.format(sleeptime))
 while len(os.listdir(basedb)) == 0 and sleeptime < 58:
-    print('{}: Waiting for Job Directory'.format(sleeptime))
     sleeptime += 1
     time.sleep(1)
 
@@ -68,18 +68,19 @@
 #     if new[-len(lastline):] == lastline:
 #         break
 
-
-lastline = 'Job 4 done on worker 1\n'
-while True:
+lastposition = 0
+lastlines = ['Job 4 done on worker 1\n', 'Job 4 done on worker 2\n']
+while sleeptime < 58:
     with open(outscript, 'r') as f:
+        f.seek(lastposition)
         new = f.read()
-        time.sleep(0.5)
-        if new[-len(lastline):] == lastline:
-            break
+        last = f.tell()
+    if len(new) > 0:
+        print(new)
+        sys.stdout.flush()
+    if new[-len(lastline):] in lastlines:
+        break
+    time.sleep(1)
 
-with open(outscript, 'r') as f:
-    lines = f.read()
-    print(lines)
-    sys.stdout.flush()
 
 print('Test completed.')

From b47f26d582c503ee689fcefe8714146ac196ca8f Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 19 Aug 2019 10:37:15 -0500
Subject: [PATCH 157/644] flake8

---
 conda/test_balsam.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 522b99e49..efc65be23 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -78,7 +78,7 @@
     if len(new) > 0:
         print(new)
         sys.stdout.flush()
-    if new[-len(lastline):] in lastlines:
+    if new[-len(lastlines[0]):] in lastlines:
         break
     time.sleep(1)
 

From 9a83a98ef9807307c6ab9e5328260c4032ce4a5e Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 19 Aug 2019 10:50:09 -0500
Subject: [PATCH 158/644] fixes lastposition not being updated

---
 conda/test_balsam.py | 17 ++---------------
 1 file changed, 2 insertions(+), 15 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index efc65be23..d7f1fc1db 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -54,33 +54,20 @@
         sleeptime += 2
         time.sleep(2)
 
-# Output from Balsam Job (script_test_balsam.py)
-# print('Writing output file to terminal')
-# last = 0
-# lastline = 'Job 4 done on worker 1'
-# while True:
-#     with open(outscript, 'r') as f:
-#         f.seek(last)
-#         new = f.read()
-#         last = f.tell()
-#     print(new)
-#     sys.stdout.flush()
-#     if new[-len(lastline):] == lastline:
-#         break
-
 lastposition = 0
 lastlines = ['Job 4 done on worker 1\n', 'Job 4 done on worker 2\n']
 while sleeptime < 58:
     with open(outscript, 'r') as f:
         f.seek(lastposition)
         new = f.read()
-        last = f.tell()
+        lastposition = f.tell()
     if len(new) > 0:
         print(new)
         sys.stdout.flush()
     if new[-len(lastlines[0]):] in lastlines:
         break
     time.sleep(1)
+    sleeptime += 1
 
 
 print('Test completed.')

From db3cd3c4fb96c34bced0d52ef58f7304797732b7 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 19 Aug 2019 11:31:27 -0500
Subject: [PATCH 159/644] Reenables timeout in run-tests. All-around commenting
 and cleanup

---
 conda/configure-balsam-test.sh                |  7 +++---
 conda/install-balsam.py                       |  7 +++++-
 conda/run_travis_locally/build_mpich_libE.sh  | 13 +----------
 conda/test_balsam.py                          | 23 ++++++++++---------
 .../regression_tests/script_test_balsam.py    | 22 +++++++++---------
 libensemble/tests/run-tests.sh                |  3 +--
 6 files changed, 35 insertions(+), 40 deletions(-)

diff --git a/conda/configure-balsam-test.sh b/conda/configure-balsam-test.sh
index bce2ed440..344c0c59a 100755
--- a/conda/configure-balsam-test.sh
+++ b/conda/configure-balsam-test.sh
@@ -1,9 +1,10 @@
 #!/bin/bash
 
 # Run this script between each repeated local run of the Balsam
-#   job_control_hworld_balsam test. Besides ensuring that postgres and the
-#   generated Balsam db have the proper permissions, this script flushes previous
-#   apps and jobs in the db before submitting the test_balsam app/job script.
+#   job_control_hworld_balsam test in the base libensemble directory.
+#   Besides ensuring that postgres and the generated Balsam db have the proper
+#   permissions, this script flushes previous apps and jobs in the db before
+#   submitting the test_balsam app/job script.
 #
 #   Most of this comes from scaling_tests/forces/balsam_local.sh
 
diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index 2e18a9938..ac340fca8 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -1,12 +1,17 @@
 #! /usr/bin/env python
 
+# Installing Balsam consists of both cloning and pip installing the latest version
+#   of Balsam from source but also moving the Balsam-relevant test to the regression_tests
+#   directory. This way, run-tests won't run a non-relevant test if Balsam isn't
+#   installed or the necessary Python version isn't installed.
+
 import sys
 import os
 import subprocess
 
 balsamclone = 'git clone https://github.com/balsam-alcf/balsam.git ../balsam'
 
-if int(sys.version[2]) >= 6:
+if int(sys.version[2]) >= 6: # Balsam only supports Python 3.6+
     subprocess.check_call(balsamclone.split())
     os.chdir('../balsam')
     subprocess.check_call('pip install -e .'.split())
diff --git a/conda/run_travis_locally/build_mpich_libE.sh b/conda/run_travis_locally/build_mpich_libE.sh
index 748059c87..cd7e00254 100755
--- a/conda/run_travis_locally/build_mpich_libE.sh
+++ b/conda/run_travis_locally/build_mpich_libE.sh
@@ -6,7 +6,7 @@
 # set -x # problem with this - loads of conda internal commands shown - overwhelming.
 
 export PYTHON_VERSION=3.6       # default - override with -p <version>
-export LIBE_BRANCH="experimental/balsam-on-travis"    # default - override with -b <branchname>
+export LIBE_BRANCH="develop"    # default - override with -b <branchname>
 export SYSTEM="Linux"         # default - override with -s <OS>
                                 # Options for miniconda - Linux, MacOSX, Windows
 export MPI=MPICH
@@ -41,12 +41,6 @@ done
 
 echo -e "\nBuilding libE on ${SYSTEM} with python $PYTHON_VERSION and branch ${LIBE_BRANCH}\n"
 
-# mkdir pg; cd pg;
-# wget http://sbp.enterprisedb.com/getfile.jsp?fileid=11966
-# tar xf getfile.jsp?fileid=11966
-# export PATH="$PATH:/home/travis/pg/pgsql/bin"
-# cd ~
-
 sudo pip install --upgrade pip
 sudo /etc/init.d/postgresql stop 9.2
 sudo /etc/init.d/postgresql start 9.6
@@ -78,11 +72,6 @@ else
   conda install gcc_linux-64 || return
 fi
 conda install nlopt petsc4py petsc mumps-mpi=5.1.2=h5bebb2f_1007 mpi4py scipy $MPI
-#conda install numpy || return #scipy includes numpy
-# conda install scipy || return
-# conda install mpi4py || return
-# conda install petsc4py petsc || return
-# conda install nlopt || return
 
 # pip install these as the conda installs downgrade pytest on python3.4
 pip install pytest || return
diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index d7f1fc1db..6e66a7d8e 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -7,12 +7,15 @@
 # TESTSUITE_COMMS: local
 # TESTSUITE_NPROCS: 3
 
+# This test is NOT submitted as a job to Balsam. That would be script_test_balsam.py
+#   This test executes that job through the 'runstr' line defined further down.
+
 nworkers, is_master, libE_specs, _ = parse_args()  # None used. Bug-prevention
 
 # Balsam is meant for HPC systems that commonly distribute jobs across many
 #   nodes. Due to the nature of testing Balsam on local or CI systems which usually
 #   only contain a single node, we need to change Balsam's default worker setup
-#   so multiple workers can be run on a single node (until this feature is [hopefully] added!).
+#   so multiple workers can be run on a single node.
 #   For our purposes, we append ten workers to Balsam's WorkerGroup
 print("Currently in {}. Beginning Balsam worker modification".format(os.getcwd()))
 modify_Balsam_worker()
@@ -44,21 +47,19 @@
 jobdir = os.path.join(basedb, jobdirname)
 outscript = os.path.join(jobdir, 'job_script_test_balsam.out')
 
-print('Beginning cycle of checking for Balsam output: {}'.format(outscript))
-while sleeptime < 58:
-    if os.path.isfile(outscript):
-        print('{}: Balsam job output found!'.format(sleeptime))
-        break
-    else:
-        print('{}: No job output found. Checking again.'.format(sleeptime))
-        sleeptime += 2
-        time.sleep(2)
+# Periodically wait for Balsam Job output
+print('{}: Beginning cycle of checking for Balsam output: {}'.format(sleeptime, outscript))
+while not os.path.isfile(outscript) and sleeptime < 58:
+    sleeptime += 2
+    time.sleep(2)
 
+# Print sections of Balsam output to screen every second until complete
+print('{}: Balsam job output found! Printing to screen.'.format(sleeptime))
 lastposition = 0
 lastlines = ['Job 4 done on worker 1\n', 'Job 4 done on worker 2\n']
 while sleeptime < 58:
     with open(outscript, 'r') as f:
-        f.seek(lastposition)
+        f.seek(lastposition)    # Prevents outputting already printed sections
         new = f.read()
         lastposition = f.tell()
     if len(new) > 0:
diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index ba3a15ff9..d8c4a43a1 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -1,6 +1,6 @@
-# This script is submitted as an app to Balsam, and jobs are launched
-#   based on this app. This submission is via 'balsam launch' executed
-#   in the test_balsam.py script.
+# This script is submitted as an app and job to Balsam, and jobs
+#   are launched based on this app. This submission is via '
+#   balsam launch' executed in the test_balsam.py script.
 
 import os
 import numpy as np
@@ -17,16 +17,13 @@
 
 mpi4py.rc.recv_mprobe = False  # Disable matching probes
 
-
+# Slighty different due to not executing in /regression_tests
 def build_simfunc():
     import subprocess
     print('Balsam job launched in: {}'.format(os.getcwd()))
     buildstring = 'mpicc -o my_simjob.x libensemble/tests/unit_tests/simdir/my_simjob.c'
     subprocess.check_call(buildstring.split())
 
-
-# This script is meant to be launched by Balsam
-
 libE_specs = {'comm': MPI.COMM_WORLD, 'color': 0, 'comms': 'mpi'}
 
 nworkers = MPI.COMM_WORLD.Get_size() - 1
@@ -37,7 +34,8 @@ def build_simfunc():
 cores_all_jobs = nworkers*cores_per_job
 
 if is_master:
-    print('\nCores req: {} Cores avail: {}\n'.format(cores_all_jobs, logical_cores))
+    print('\nCores req: {} Cores avail: {}\n'.format(cores_all_jobs,
+                                                     logical_cores))
 
 sim_app = './my_simjob.x'
 if not os.path.isfile(sim_app):
@@ -67,8 +65,8 @@ def build_simfunc():
 exit_criteria = {'elapsed_wallclock_time': 30}
 
 # Perform the run
-H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
-                            libE_specs=libE_specs)
+H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria,
+                            persis_info, libE_specs=libE_specs)
 
 if is_master:
     print('\nChecking expected job status against Workers ...\n')
@@ -77,7 +75,9 @@ def build_simfunc():
     # manager kill - but should show in the summary file.
     # Repeat expected lists nworkers times and compare with list of status's
     # received from workers
-    calc_status_list_in = np.asarray([WORKER_DONE, WORKER_KILL_ON_ERR, WORKER_KILL_ON_TIMEOUT, JOB_FAILED, 0])
+    calc_status_list_in = np.asarray([WORKER_DONE, WORKER_KILL_ON_ERR,
+                                      WORKER_KILL_ON_TIMEOUT,
+                                      JOB_FAILED, 0])
     calc_status_list = np.repeat(calc_status_list_in, nworkers)
 
     # For debug
diff --git a/libensemble/tests/run-tests.sh b/libensemble/tests/run-tests.sh
index 700fe8de9..a48bff814 100755
--- a/libensemble/tests/run-tests.sh
+++ b/libensemble/tests/run-tests.sh
@@ -378,8 +378,7 @@ if [ "$root_found" = true ]; then
 
     TIMEOUT=""
     if [ -x "$(command -v timeout)" ] ; then
-        # TIMEOUT="timeout 60s"
-        TIMEOUT=""
+        TIMEOUT="timeout 60s"
     fi
     #Build any sim/gen source code dependencies here .....
 

From 21f05f3f01ea45e3a171d156b6ab89bbf91cc802 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 19 Aug 2019 11:37:15 -0500
Subject: [PATCH 160/644] flake8

---
 conda/install-balsam.py                                  | 2 +-
 libensemble/tests/regression_tests/script_test_balsam.py | 2 ++
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index ac340fca8..cd6c1a3d2 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -11,7 +11,7 @@
 
 balsamclone = 'git clone https://github.com/balsam-alcf/balsam.git ../balsam'
 
-if int(sys.version[2]) >= 6: # Balsam only supports Python 3.6+
+if int(sys.version[2]) >= 6:  # Balsam only supports Python 3.6+
     subprocess.check_call(balsamclone.split())
     os.chdir('../balsam')
     subprocess.check_call('pip install -e .'.split())
diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index d8c4a43a1..e604aa699 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -17,6 +17,7 @@
 
 mpi4py.rc.recv_mprobe = False  # Disable matching probes
 
+
 # Slighty different due to not executing in /regression_tests
 def build_simfunc():
     import subprocess
@@ -24,6 +25,7 @@ def build_simfunc():
     buildstring = 'mpicc -o my_simjob.x libensemble/tests/unit_tests/simdir/my_simjob.c'
     subprocess.check_call(buildstring.split())
 
+
 libE_specs = {'comm': MPI.COMM_WORLD, 'color': 0, 'comms': 'mpi'}
 
 nworkers = MPI.COMM_WORLD.Get_size() - 1

From 000b2cffd7e391657b514bce1567c8888ffe85a5 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 19 Aug 2019 12:04:25 -0500
Subject: [PATCH 161/644] try adding progress to file/dir waiters. try
 disabling timeout again

---
 conda/test_balsam.py           | 3 +++
 libensemble/tests/run-tests.sh | 3 ++-
 2 files changed, 5 insertions(+), 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 6e66a7d8e..621836578 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -35,11 +35,13 @@
 print('{}: Waiting for Workflow directory'.format(sleeptime))
 while not os.path.isdir(basedb) and sleeptime < 58:
     sleeptime += 1
+    print('{}'.format(sleeptime), end=" ")
     time.sleep(1)
 
 print('{}: Waiting for Job Directory'.format(sleeptime))
 while len(os.listdir(basedb)) == 0 and sleeptime < 58:
     sleeptime += 1
+    print('{}'.format(sleeptime), end=" ")
     time.sleep(1)
 
 # Periodically check for Balsam general output
@@ -51,6 +53,7 @@
 print('{}: Beginning cycle of checking for Balsam output: {}'.format(sleeptime, outscript))
 while not os.path.isfile(outscript) and sleeptime < 58:
     sleeptime += 2
+    print('{}'.format(sleeptime), end=" ")
     time.sleep(2)
 
 # Print sections of Balsam output to screen every second until complete
diff --git a/libensemble/tests/run-tests.sh b/libensemble/tests/run-tests.sh
index a48bff814..700fe8de9 100755
--- a/libensemble/tests/run-tests.sh
+++ b/libensemble/tests/run-tests.sh
@@ -378,7 +378,8 @@ if [ "$root_found" = true ]; then
 
     TIMEOUT=""
     if [ -x "$(command -v timeout)" ] ; then
-        TIMEOUT="timeout 60s"
+        # TIMEOUT="timeout 60s"
+        TIMEOUT=""
     fi
     #Build any sim/gen source code dependencies here .....
 

From e64c962ccdd5a563a5d060727c6c48a72b1ad6ed Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 19 Aug 2019 14:08:42 -0500
Subject: [PATCH 162/644] attempt to use typical job_control_hworld sim_f

---
 libensemble/tests/regression_tests/script_test_balsam.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index e604aa699..9c6034f11 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -11,7 +11,7 @@
 from libensemble.balsam_controller import BalsamJobController
 from libensemble.message_numbers import WORKER_DONE, WORKER_KILL_ON_ERR, WORKER_KILL_ON_TIMEOUT, JOB_FAILED
 from libensemble.libE import libE
-from libensemble.sim_funcs.job_control_hworld_balsam import job_control_hworld as sim_f
+from libensemble.sim_funcs.job_control_hworld import job_control_hworld as sim_f
 from libensemble.gen_funcs.uniform_sampling import uniform_random_sample as gen_f
 from libensemble.tests.regression_tests.common import per_worker_stream
 

From 2edfdccef9cd65b4000d3fe9abd6adc851d55155 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 19 Aug 2019 14:21:18 -0500
Subject: [PATCH 163/644] removes duplicate code, adjusts timeout of
 job_control_hworld (which will be used instead)

---
 libensemble/sim_funcs/job_control_hworld.py   |   2 +-
 .../sim_funcs/job_control_hworld_balsam.py    | 121 ------------------
 2 files changed, 1 insertion(+), 122 deletions(-)
 delete mode 100644 libensemble/sim_funcs/job_control_hworld_balsam.py

diff --git a/libensemble/sim_funcs/job_control_hworld.py b/libensemble/sim_funcs/job_control_hworld.py
index 9cb7403d6..7b772fb0d 100644
--- a/libensemble/sim_funcs/job_control_hworld.py
+++ b/libensemble/sim_funcs/job_control_hworld.py
@@ -72,7 +72,7 @@ def job_control_hworld(H, persis_info, sim_specs, libE_specs):
     # pref send this in X as a sim_in from calling script
     global sim_count
     sim_count += 1
-    timeout = 3.0
+    timeout = 6.0
     if sim_count == 1:
         args_for_sim = 'sleep 1'  # Should finish
     elif sim_count == 2:
diff --git a/libensemble/sim_funcs/job_control_hworld_balsam.py b/libensemble/sim_funcs/job_control_hworld_balsam.py
deleted file mode 100644
index a8dd89e8c..000000000
--- a/libensemble/sim_funcs/job_control_hworld_balsam.py
+++ /dev/null
@@ -1,121 +0,0 @@
-from libensemble.balsam_controller import BalsamJobController
-from libensemble.message_numbers import UNSET_TAG, WORKER_KILL_ON_ERR, MAN_SIGNAL_FINISH, WORKER_DONE, JOB_FAILED, WORKER_KILL_ON_TIMEOUT
-import numpy as np
-
-__all__ = ['job_control_hworld']
-
-# Alt send values through X
-sim_count = 0
-
-
-def polling_loop(comm, jobctl, job, timeout_sec=3.0, delay=0.3):
-    import time
-
-    calc_status = UNSET_TAG  # Sim func determines status of libensemble calc - returned to worker
-
-    while job.runtime < timeout_sec:
-        time.sleep(delay)
-
-        # print('Probing manager at time: ', job.runtime)
-        jobctl.manager_poll(comm)
-        if jobctl.manager_signal == 'finish':
-            jobctl.kill(job)
-            calc_status = MAN_SIGNAL_FINISH  # Worker will pick this up and close down
-            print('Job {} killed by manager on worker {}'.format(job.id, jobctl.workerID))
-            break
-
-        # print('Polling job at time', job.runtime)
-        job.poll()
-        if job.finished:
-            break
-        elif job.state == 'RUNNING':
-            print('Job {} still running on worker {} ....'.format(job.id, jobctl.workerID))
-
-        # Check output file for error
-        # print('Checking output file for error at time:', job.runtime)
-        if job.stdout_exists():
-            if 'Error' in job.read_stdout():
-                print("Found (deliberate) Error in ouput file - cancelling job {} on worker {}".format(job.id, jobctl.workerID))
-                jobctl.kill(job)
-                calc_status = WORKER_KILL_ON_ERR
-                break
-
-    # After exiting loop
-    if job.finished:
-        print('Job {} done on worker {}'.format(job.id, jobctl.workerID))
-        # Fill in calc_status if not already
-        if calc_status == UNSET_TAG:
-            if job.state == 'FINISHED':  # Means finished succesfully
-                calc_status = WORKER_DONE
-            elif job.state == 'FAILED':
-                calc_status = JOB_FAILED
-            # elif job.state == 'USER_KILLED':
-            #     calc_status = WORKER_KILL
-    else:
-        # assert job.state == 'RUNNING', "job.state expected to be RUNNING. Returned: " + str(job.state)
-        print("Job {} timed out - killing on worker {}".format(job.id, jobctl.workerID))
-        jobctl.kill(job)
-        if job.finished:
-            print('Job {} done on worker {}'.format(job.id, jobctl.workerID))
-        calc_status = WORKER_KILL_ON_TIMEOUT
-
-    return job, calc_status
-
-
-def job_control_hworld(H, persis_info, sim_specs, libE_specs):
-    """ Test of launching and polling job and exiting on job finish"""
-    jobctl = BalsamJobController.controller
-    cores = sim_specs['cores']
-    comm = libE_specs['comm']
-
-    args_for_sim = 'sleep 1'
-    # pref send this in X as a sim_in from calling script
-    global sim_count
-    sim_count += 1
-    timeout = 6.0
-    if sim_count == 1:
-        args_for_sim = 'sleep 1'  # Should finish
-    elif sim_count == 2:
-        args_for_sim = 'sleep 1 Error'  # Worker kill on error
-    elif sim_count == 3:
-        args_for_sim = 'sleep 3'  # Worker kill on timeout
-        timeout = 1.0
-    elif sim_count == 4:
-        args_for_sim = 'sleep 1 Fail'  # Manager kill - if signal received else completes
-    elif sim_count == 5:
-        args_for_sim = 'sleep 18'  # Manager kill - if signal received else completes
-        timeout = 20.0
-
-    job = jobctl.launch(calc_type='sim', num_procs=cores, app_args=args_for_sim, hyperthreads=True, wait_on_run=True)
-    job, calc_status = polling_loop(comm, jobctl, job, timeout)
-
-    # assert job.finished, "job.finished should be True. Returned " + str(job.finished)
-    # assert job.state == 'FINISHED', "job.state should be FINISHED. Returned " + str(job.state)
-
-    # This is temp - return something - so doing six_hump_camel_func again...
-    batch = len(H['x'])
-    O = np.zeros(batch, dtype=sim_specs['out'])
-    for i, x in enumerate(H['x']):
-        O['f'][i] = six_hump_camel_func(x)
-
-    # This is just for testing at calling script level - status of each job
-    O['cstat'] = calc_status
-
-    # v = np.random.uniform(0, 10)
-    # print('About to sleep for :' + str(v))
-    # time.sleep(v)
-
-    return O, persis_info, calc_status
-
-
-def six_hump_camel_func(x):
-    """
-    Definition of the six-hump camel
-    """
-    x1 = x[0]
-    x2 = x[1]
-    term1 = (4-2.1*x1**2+(x1**4)/3) * x1**2
-    term2 = x1*x2
-    term3 = (-4+4*x2**2) * x2**2
-
-    return term1 + term2 + term3

From 268d40470e0a5785d4723c8b68f1912bc05a6c2d Mon Sep 17 00:00:00 2001
From: Kaushik Kulkarni <kaushikcfd@gmail.com>
Date: Tue, 20 Aug 2019 18:50:32 +0530
Subject: [PATCH 164/644] removes debug message

---
 libensemble/gen_funcs/support.py | 2 --
 1 file changed, 2 deletions(-)

diff --git a/libensemble/gen_funcs/support.py b/libensemble/gen_funcs/support.py
index 0ae971e7a..e5084828d 100644
--- a/libensemble/gen_funcs/support.py
+++ b/libensemble/gen_funcs/support.py
@@ -11,8 +11,6 @@ def sendrecv_mgr_worker_msg(comm, O, status=None):
 def send_mgr_worker_msg(comm, O):
     """Send message from worker to manager.
     """
-    if 'sim_id' in O.dtype.names:
-        print(25*"-", "Sending {}(SimID: {})".format(O[0][0], O['sim_id']), 25*"-", flush=True)
     D = {'calc_out': O,
          'libE_info': {'persistent': True},
          'calc_status': UNSET_TAG,

From 3b5f3c0e6662432f96ee4ef2200354a160e00145 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 20 Aug 2019 08:27:34 -0500
Subject: [PATCH 165/644] Removing 3.4

---
 .travis.yml | 2 --
 1 file changed, 2 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 8dacfbeda..92bca6f08 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -2,7 +2,6 @@ language: python
 sudo: required
 dist: xenial
 python:
-  - 3.4
   - 3.5
   - 3.6
   - 3.7
@@ -25,7 +24,6 @@ matrix:
       language: generic
       python: 3
 
-
 # matrix:
 #  allow_failures:
 #    - env: MPI=openmpi

From 907b94ae6d1f3a00bd203a1a654a38dfef348d79 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 21 Aug 2019 10:44:43 -0500
Subject: [PATCH 166/644] Adds function to modify Balsam's newapp routine to
 add coverage runtime.

---
 conda/install-balsam.py                      |  3 +-
 conda/test_balsam.py                         |  7 +++--
 libensemble/tests/regression_tests/common.py | 30 ++++++++++++++++++++
 3 files changed, 36 insertions(+), 4 deletions(-)

diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index cd6c1a3d2..5aee31a31 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -8,6 +8,7 @@
 import sys
 import os
 import subprocess
+from libensemble.tests.regression_tests.common import modify_Balsam_pyCoverage
 
 balsamclone = 'git clone https://github.com/balsam-alcf/balsam.git ../balsam'
 
@@ -19,5 +20,5 @@
     if not os.path.isfile('./libensemble/tests/regression_tests/test_balsam.py'):
         os.rename('./conda/test_balsam.py',
                   './libensemble/tests/regression_tests/test_balsam.py')
-    # os.system('./conda/configure-balsam-test.sh')
+    modify_Balsam_pyCoverage() # Need to add "coverage" before jobs added
     subprocess.run('./conda/configure-balsam-test.sh'.split())
diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 621836578..50a4844b3 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -68,10 +68,11 @@
     if len(new) > 0:
         print(new)
         sys.stdout.flush()
-    if new[-len(lastlines[0]):] in lastlines:
+    #if new[-len(lastlines[0]):] in lastlines:
+    if any(new.endswith(line) for line in lastlines):
         break
     time.sleep(1)
     sleeptime += 1
 
-
-print('Test completed.')
+print('Test completed. Importing coverage into local directory.')
+# Coming soon!
diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index 41fc4bbd7..30fd275f9 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -202,3 +202,33 @@ def modify_Balsam_worker():
 
     print("Modified worker file in {}".format(os.getcwd()))
     os.chdir(home)
+
+def modify_Balsam_pyCoverage():
+    # Tracking line coverage of our code through our tests requires running a test
+    #   with the format 'python -m coverage run test.py args'. Balsam explicitely
+    #   configures Python executable runs with 'python test.py args' with no current
+    #   capability for specifying runtime Python options. This hack attempts to resolve
+    #   this for our purposes only.
+    import balsam
+
+    old_line = "            path = ' '.join((exe, script_path, args))"
+    new_line = "            path = ' '.join((exe, '-m coverage run --parallel-mode', script_path, args))"
+
+    commandfile = 'cli_commands.py'
+    home = os.getcwd()
+    balsam_scripts_path = os.path.dirname(balsam.__file__) + '/scripts'
+    os.chdir(balsam_scripts_path)
+
+    with open(commandfile, 'r') as f:
+        lines = f.readlines()
+
+    for i in range(len(lines)):
+        if lines[i] == old_line:
+            lines[i] = new_line
+
+    with open(commandfile, 'w') as f:
+        for line in lines:
+            f.write(line)
+
+    print("Modified cli_commands file in {}".format(os.getcwd()))
+    os.chdir(home)

From a73942d337bf732711dd497a4ddc9749c4320c24 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 21 Aug 2019 11:18:48 -0500
Subject: [PATCH 167/644] Moves Balsam modification line

---
 conda/configure-balsam-test.sh | 3 +++
 conda/install-balsam.py        | 3 +--
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/conda/configure-balsam-test.sh b/conda/configure-balsam-test.sh
index 344c0c59a..6eacd80aa 100755
--- a/conda/configure-balsam-test.sh
+++ b/conda/configure-balsam-test.sh
@@ -8,6 +8,9 @@
 #
 #   Most of this comes from scaling_tests/forces/balsam_local.sh
 
+# Can't run this line in calling Python file. Balsam installation hasn't been
+#   noticed by the Python runtime yet.
+python -c 'from libensemble.tests.regression_tests.common import modify_Balsam_pyCoverage; modify_Balsam_pyCoverage()'
 export EXE=$PWD/libensemble/tests/regression_tests/script_test_balsam.py
 export NUM_WORKERS=2
 export WORKFLOW_NAME=libe_test-balsam
diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index 5aee31a31..140ecf2c0 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -8,7 +8,7 @@
 import sys
 import os
 import subprocess
-from libensemble.tests.regression_tests.common import modify_Balsam_pyCoverage
+
 
 balsamclone = 'git clone https://github.com/balsam-alcf/balsam.git ../balsam'
 
@@ -20,5 +20,4 @@
     if not os.path.isfile('./libensemble/tests/regression_tests/test_balsam.py'):
         os.rename('./conda/test_balsam.py',
                   './libensemble/tests/regression_tests/test_balsam.py')
-    modify_Balsam_pyCoverage() # Need to add "coverage" before jobs added
     subprocess.run('./conda/configure-balsam-test.sh'.split())

From c14c87c0d060c656a67f0ae2bbc6e1858930523b Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 21 Aug 2019 11:48:01 -0500
Subject: [PATCH 168/644] newlines, stdout flushes for progress

---
 conda/test_balsam.py                         | 3 +++
 libensemble/tests/regression_tests/common.py | 4 ++--
 2 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 50a4844b3..5c455d0e8 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -36,12 +36,14 @@
 while not os.path.isdir(basedb) and sleeptime < 58:
     sleeptime += 1
     print('{}'.format(sleeptime), end=" ")
+    sys.stdout.flush()
     time.sleep(1)
 
 print('{}: Waiting for Job Directory'.format(sleeptime))
 while len(os.listdir(basedb)) == 0 and sleeptime < 58:
     sleeptime += 1
     print('{}'.format(sleeptime), end=" ")
+    sys.stdout.flush()
     time.sleep(1)
 
 # Periodically check for Balsam general output
@@ -54,6 +56,7 @@
 while not os.path.isfile(outscript) and sleeptime < 58:
     sleeptime += 2
     print('{}'.format(sleeptime), end=" ")
+    sys.stdout.flush()
     time.sleep(2)
 
 # Print sections of Balsam output to screen every second until complete
diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index 30fd275f9..b62503db9 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -211,8 +211,8 @@ def modify_Balsam_pyCoverage():
     #   this for our purposes only.
     import balsam
 
-    old_line = "            path = ' '.join((exe, script_path, args))"
-    new_line = "            path = ' '.join((exe, '-m coverage run --parallel-mode', script_path, args))"
+    old_line = "            path = ' '.join((exe, script_path, args))\n"
+    new_line = "            path = ' '.join((exe, '-m coverage run --parallel-mode', script_path, args))\n"
 
     commandfile = 'cli_commands.py'
     home = os.getcwd()

From 6a79da820eaf14625c4aec6ab9ef36a8c7423691 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 21 Aug 2019 14:36:22 -0500
Subject: [PATCH 169/644] First attempt to move coverage from Balsam to tests
 directory

---
 conda/test_balsam.py | 15 ++++++++++++---
 1 file changed, 12 insertions(+), 3 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 5c455d0e8..3cdca52f4 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -60,7 +60,7 @@
     time.sleep(2)
 
 # Print sections of Balsam output to screen every second until complete
-print('{}: Balsam job output found! Printing to screen.'.format(sleeptime))
+print('{}: Attempting to print output.'.format(sleeptime))
 lastposition = 0
 lastlines = ['Job 4 done on worker 1\n', 'Job 4 done on worker 2\n']
 while sleeptime < 58:
@@ -77,5 +77,14 @@
     time.sleep(1)
     sleeptime += 1
 
-print('Test completed. Importing coverage into local directory.')
-# Coming soon!
+print('Test completed. Importing any coverage from Balsam.')
+here = os.getcwd()
+
+# Move coverage files from Balsam DB to ./regression_tests (for concatenation)
+for file in os.listdir(jobdir):
+    if file[:10] == '.coverage.':
+        print('Coverage found: {}'.format(file))
+        coveragefile = os.path.join(jobdir, file)
+        os.rename(coveragefile, here)
+
+print('test_balsam processing complete.')

From d325287afc3bce3f3f0b3998bda206b64b212ce7 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 21 Aug 2019 15:01:09 -0500
Subject: [PATCH 170/644] specifies .coveragerc file explicitly, fixes file
 move path

---
 conda/test_balsam.py                         | 5 +++--
 libensemble/tests/regression_tests/common.py | 2 +-
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 3cdca52f4..415bb4440 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -84,7 +84,8 @@
 for file in os.listdir(jobdir):
     if file[:10] == '.coverage.':
         print('Coverage found: {}'.format(file))
-        coveragefile = os.path.join(jobdir, file)
-        os.rename(coveragefile, here)
+        balsam_cov = os.path.join(jobdir, file)
+        here_cov = os.path.join(here, file)
+        os.rename(balsam_cov, here_cov)
 
 print('test_balsam processing complete.')
diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index b62503db9..da45fce3c 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -212,7 +212,7 @@ def modify_Balsam_pyCoverage():
     import balsam
 
     old_line = "            path = ' '.join((exe, script_path, args))\n"
-    new_line = "            path = ' '.join((exe, '-m coverage run --parallel-mode', script_path, args))\n"
+    new_line = "            path = ' '.join((exe, '-m coverage run --parallel-mode --rcfile=./libensemble/tests/regression_tests/.coveragerc', script_path, args))\n"
 
     commandfile = 'cli_commands.py'
     home = os.getcwd()

From d115586b3d9c7e8a1b5908ed8b5e39c4312436db Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 21 Aug 2019 15:16:19 -0500
Subject: [PATCH 171/644] flake8

---
 conda/test_balsam.py                         | 2 +-
 libensemble/tests/regression_tests/common.py | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 415bb4440..826c5dace 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -71,7 +71,7 @@
     if len(new) > 0:
         print(new)
         sys.stdout.flush()
-    #if new[-len(lastlines[0]):] in lastlines:
+    # if new[-len(lastlines[0]):] in lastlines:
     if any(new.endswith(line) for line in lastlines):
         break
     time.sleep(1)
diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index da45fce3c..e23706f13 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -203,6 +203,7 @@ def modify_Balsam_worker():
     print("Modified worker file in {}".format(os.getcwd()))
     os.chdir(home)
 
+
 def modify_Balsam_pyCoverage():
     # Tracking line coverage of our code through our tests requires running a test
     #   with the format 'python -m coverage run test.py args'. Balsam explicitely

From fa9956900690a5c7816361dcf552818210a4c336 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 21 Aug 2019 16:05:25 -0500
Subject: [PATCH 172/644] don't need to source run-tests.sh

---
 .travis.yml                                  | 2 +-
 conda/run_travis_locally/build_mpich_libE.sh | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index b36a6fa0b..b1cee2631 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -97,7 +97,7 @@ before_script:
 
 # Run test (-z show output)
 script:
-  - source libensemble/tests/run-tests.sh -z
+  - ./libensemble/tests/run-tests.sh -z
 
 # Coverage
 after_success:
diff --git a/conda/run_travis_locally/build_mpich_libE.sh b/conda/run_travis_locally/build_mpich_libE.sh
index ad224dd91..345b8ec97 100755
--- a/conda/run_travis_locally/build_mpich_libE.sh
+++ b/conda/run_travis_locally/build_mpich_libE.sh
@@ -87,7 +87,7 @@ pip install -e . || return
 python conda/install-balsam.py
 export BALSAM_DB_PATH=~/test-balsam
 
-source libensemble/tests/run-tests.sh -z
+./libensemble/tests/run-tests.sh -z
 
 echo -e "\n\nScript completed...\n\n"
 set +ex

From d9d0aab2676e4ed6ad5408b354e89b53d51e6e28 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 21 Aug 2019 16:17:50 -0500
Subject: [PATCH 173/644] fixes coverage filename

---
 conda/test_balsam.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 826c5dace..8b5af641d 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -81,8 +81,9 @@
 here = os.getcwd()
 
 # Move coverage files from Balsam DB to ./regression_tests (for concatenation)
+covname = '.cov_reg_out.'
 for file in os.listdir(jobdir):
-    if file[:10] == '.coverage.':
+    if file[:len(covname)] == covname: # Filename starts with...
         print('Coverage found: {}'.format(file))
         balsam_cov = os.path.join(jobdir, file)
         here_cov = os.path.join(here, file)

From 86f4e0d1ace43b08a655aeeae32388cf783a706f Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 21 Aug 2019 16:23:36 -0500
Subject: [PATCH 174/644] flake8...

---
 conda/test_balsam.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 8b5af641d..0c1248c26 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -83,7 +83,7 @@
 # Move coverage files from Balsam DB to ./regression_tests (for concatenation)
 covname = '.cov_reg_out.'
 for file in os.listdir(jobdir):
-    if file[:len(covname)] == covname: # Filename starts with...
+    if file[:len(covname)] == covname:  # Filename starts with...
         print('Coverage found: {}'.format(file))
         balsam_cov = os.path.join(jobdir, file)
         here_cov = os.path.join(here, file)

From 88129ae88566bcd8bf280d0c9242e8369e3f6f16 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 22 Aug 2019 13:21:49 -0500
Subject: [PATCH 175/644] better print for coverage file moving

---
 conda/test_balsam.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 0c1248c26..2b9b1540d 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -84,9 +84,9 @@
 covname = '.cov_reg_out.'
 for file in os.listdir(jobdir):
     if file[:len(covname)] == covname:  # Filename starts with...
-        print('Coverage found: {}'.format(file))
         balsam_cov = os.path.join(jobdir, file)
         here_cov = os.path.join(here, file)
+        print('Moved {} from {} to {}.'.format(file, jobdir, here))
         os.rename(balsam_cov, here_cov)
 
 print('test_balsam processing complete.')

From 59cc1fb7f3aa11bd4929bdee28211cc3fa129202 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 22 Aug 2019 14:14:50 -0500
Subject: [PATCH 176/644] experiment with appending balsam script coverage to
 run-tests coverage

---
 conda/test_balsam.py                         | 2 +-
 libensemble/tests/regression_tests/common.py | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 2b9b1540d..c7fe7a981 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -86,7 +86,7 @@
     if file[:len(covname)] == covname:  # Filename starts with...
         balsam_cov = os.path.join(jobdir, file)
         here_cov = os.path.join(here, file)
-        print('Moved {} from {} to {}.'.format(file, jobdir, here))
+        print('Moved {} from {} to {}'.format(file, jobdir, here))
         os.rename(balsam_cov, here_cov)
 
 print('test_balsam processing complete.')
diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index e23706f13..bda680b8a 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -213,7 +213,7 @@ def modify_Balsam_pyCoverage():
     import balsam
 
     old_line = "            path = ' '.join((exe, script_path, args))\n"
-    new_line = "            path = ' '.join((exe, '-m coverage run --parallel-mode --rcfile=./libensemble/tests/regression_tests/.coveragerc', script_path, args))\n"
+    new_line = "            path = ' '.join((exe, '-m coverage run --append --parallel-mode --rcfile=./libensemble/tests/regression_tests/.coveragerc', script_path, args))\n"
 
     commandfile = 'cli_commands.py'
     home = os.getcwd()

From 749a91c8d41bf9ec8dc9a11a209cf6c47b6b2eaf Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 22 Aug 2019 14:30:02 -0500
Subject: [PATCH 177/644] removes append

---
 libensemble/tests/regression_tests/common.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index bda680b8a..e23706f13 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -213,7 +213,7 @@ def modify_Balsam_pyCoverage():
     import balsam
 
     old_line = "            path = ' '.join((exe, script_path, args))\n"
-    new_line = "            path = ' '.join((exe, '-m coverage run --append --parallel-mode --rcfile=./libensemble/tests/regression_tests/.coveragerc', script_path, args))\n"
+    new_line = "            path = ' '.join((exe, '-m coverage run --parallel-mode --rcfile=./libensemble/tests/regression_tests/.coveragerc', script_path, args))\n"
 
     commandfile = 'cli_commands.py'
     home = os.getcwd()

From 00f18ecd33ad8b1918b604a21d1f3e903d71ae78 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 26 Aug 2019 09:57:48 -0500
Subject: [PATCH 178/644] misc small changes

---
 conda/test_balsam.py | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index c7fe7a981..b92ec6dd5 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -71,22 +71,21 @@
     if len(new) > 0:
         print(new)
         sys.stdout.flush()
-    # if new[-len(lastlines[0]):] in lastlines:
     if any(new.endswith(line) for line in lastlines):
         break
     time.sleep(1)
     sleeptime += 1
 
-print('Test completed. Importing any coverage from Balsam.')
+print('{}: Importing any coverage from Balsam.'.format(sleeptime))
 here = os.getcwd()
 
 # Move coverage files from Balsam DB to ./regression_tests (for concatenation)
 covname = '.cov_reg_out.'
 for file in os.listdir(jobdir):
-    if file[:len(covname)] == covname:  # Filename starts with...
+    if file.startswith(covname):
         balsam_cov = os.path.join(jobdir, file)
         here_cov = os.path.join(here, file)
         print('Moved {} from {} to {}'.format(file, jobdir, here))
         os.rename(balsam_cov, here_cov)
 
-print('test_balsam processing complete.')
+print('Test complete.')

From acde8df9cfb122d616a5c2278c780bde8ea4df45 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 26 Aug 2019 11:16:44 -0500
Subject: [PATCH 179/644] exploring coverage not collecting coverage info
 (based on warning message)

---
 conda/test_balsam.py                          | 14 ++++-----
 .../tests/regression_tests/.bal_coveragerc    | 30 +++++++++++++++++++
 libensemble/tests/regression_tests/common.py  |  2 +-
 3 files changed, 38 insertions(+), 8 deletions(-)
 create mode 100644 libensemble/tests/regression_tests/.bal_coveragerc

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index b92ec6dd5..019c478d5 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -80,12 +80,12 @@
 here = os.getcwd()
 
 # Move coverage files from Balsam DB to ./regression_tests (for concatenation)
-covname = '.cov_reg_out.'
-for file in os.listdir(jobdir):
-    if file.startswith(covname):
-        balsam_cov = os.path.join(jobdir, file)
-        here_cov = os.path.join(here, file)
-        print('Moved {} from {} to {}'.format(file, jobdir, here))
-        os.rename(balsam_cov, here_cov)
+# covname = '.cov_reg_out.'
+# for file in os.listdir(jobdir):
+#     if file.startswith(covname):
+#         balsam_cov = os.path.join(jobdir, file)
+#         here_cov = os.path.join(here, file)
+#         print('Moved {} from {} to {}'.format(file, jobdir, here))
+#         os.rename(balsam_cov, here_cov)
 
 print('Test complete.')
diff --git a/libensemble/tests/regression_tests/.bal_coveragerc b/libensemble/tests/regression_tests/.bal_coveragerc
new file mode 100644
index 000000000..ba9b70e2b
--- /dev/null
+++ b/libensemble/tests/regression_tests/.bal_coveragerc
@@ -0,0 +1,30 @@
+[run]
+source = .
+
+omit =
+    */tests/*
+    */unit_tests/*
+    */unit_tests_nompi/*
+    */regression_tests/*
+    */branin_*/*
+
+branch = true
+
+data_file = .cov_reg_out
+
+parallel = true
+
+[report]
+omit =
+    */__init__.py/*
+    */setup.py/*
+    */tests/*
+    */unit_tests/*
+    */unit_tests_nompi/*
+    */regression_tests/*
+
+exclude_lines =
+    if __name__ == .__main__.:
+
+[html]
+directory = cov_reg
diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index e23706f13..075ea3263 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -213,7 +213,7 @@ def modify_Balsam_pyCoverage():
     import balsam
 
     old_line = "            path = ' '.join((exe, script_path, args))\n"
-    new_line = "            path = ' '.join((exe, '-m coverage run --parallel-mode --rcfile=./libensemble/tests/regression_tests/.coveragerc', script_path, args))\n"
+    new_line = "            path = ' '.join((exe, '-m coverage run --parallel-mode --rcfile=./libensemble/tests/regression_tests/.bal_coveragerc', script_path, args))\n"
 
     commandfile = 'cli_commands.py'
     home = os.getcwd()

From 156c556da3696395bc4111cdc7636950eeff0e5c Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 26 Aug 2019 12:16:32 -0500
Subject: [PATCH 180/644] adding explicit libensemble location

---
 libensemble/tests/regression_tests/.bal_coveragerc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/regression_tests/.bal_coveragerc b/libensemble/tests/regression_tests/.bal_coveragerc
index ba9b70e2b..59fbb96d7 100644
--- a/libensemble/tests/regression_tests/.bal_coveragerc
+++ b/libensemble/tests/regression_tests/.bal_coveragerc
@@ -1,5 +1,5 @@
 [run]
-source = .
+source = /home/travis/libensemble/
 
 omit =
     */tests/*

From 209975636d15b175230e3d62e346c1821c1c3d68 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 26 Aug 2019 13:11:09 -0500
Subject: [PATCH 181/644] un-commented code block

---
 conda/test_balsam.py | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 019c478d5..1f63a2926 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -79,13 +79,13 @@
 print('{}: Importing any coverage from Balsam.'.format(sleeptime))
 here = os.getcwd()
 
-# Move coverage files from Balsam DB to ./regression_tests (for concatenation)
-# covname = '.cov_reg_out.'
-# for file in os.listdir(jobdir):
-#     if file.startswith(covname):
-#         balsam_cov = os.path.join(jobdir, file)
-#         here_cov = os.path.join(here, file)
-#         print('Moved {} from {} to {}'.format(file, jobdir, here))
-#         os.rename(balsam_cov, here_cov)
+Move coverage files from Balsam DB to ./regression_tests (for concatenation)
+covname = '.cov_reg_out.'
+for file in os.listdir(jobdir):
+    if file.startswith(covname):
+        balsam_cov = os.path.join(jobdir, file)
+        here_cov = os.path.join(here, file)
+        print('Moved {} from {} to {}'.format(file, jobdir, here))
+        os.rename(balsam_cov, here_cov)
 
 print('Test complete.')

From 653bd9ede801a8fa66dfc7fce429ac403dceb534 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 26 Aug 2019 13:20:11 -0500
Subject: [PATCH 182/644] flake8

---
 conda/test_balsam.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index 1f63a2926..b92ec6dd5 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -79,7 +79,7 @@
 print('{}: Importing any coverage from Balsam.'.format(sleeptime))
 here = os.getcwd()
 
-Move coverage files from Balsam DB to ./regression_tests (for concatenation)
+# Move coverage files from Balsam DB to ./regression_tests (for concatenation)
 covname = '.cov_reg_out.'
 for file in os.listdir(jobdir):
     if file.startswith(covname):

From 93638082cc5f787c6d3914befe5838230b94fcd7 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 26 Aug 2019 14:01:22 -0500
Subject: [PATCH 183/644] trying travis-server libe path

---
 libensemble/tests/regression_tests/.bal_coveragerc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/regression_tests/.bal_coveragerc b/libensemble/tests/regression_tests/.bal_coveragerc
index 59fbb96d7..e3a4097db 100644
--- a/libensemble/tests/regression_tests/.bal_coveragerc
+++ b/libensemble/tests/regression_tests/.bal_coveragerc
@@ -1,5 +1,5 @@
 [run]
-source = /home/travis/libensemble/
+source = /home/travis/build/Libensemble/libensemble
 
 omit =
     */tests/*

From 0a8cabf61cf514119bfe4d3325e685c2f8d742a4 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 26 Aug 2019 15:32:10 -0500
Subject: [PATCH 184/644] Attempts to make base libensemble path more dynamic
 for coverage. Misc housekeeping changes

---
 conda/test_balsam.py                          | 22 ++++++-----
 .../tests/regression_tests/.bal_coveragerc    |  2 +-
 libensemble/tests/regression_tests/common.py  | 39 +++++++++----------
 .../regression_tests/script_test_balsam.py    |  7 ++--
 4 files changed, 35 insertions(+), 35 deletions(-)

diff --git a/conda/test_balsam.py b/conda/test_balsam.py
index b92ec6dd5..d64697aa0 100644
--- a/conda/test_balsam.py
+++ b/conda/test_balsam.py
@@ -2,6 +2,7 @@
 import os
 import time
 import sys
+import libensemble
 from libensemble.tests.regression_tests.common import parse_args, modify_Balsam_worker
 
 # TESTSUITE_COMMS: local
@@ -12,15 +13,17 @@
 
 nworkers, is_master, libE_specs, _ = parse_args()  # None used. Bug-prevention
 
+# Set libensemble base directory to environment variable for Balsam coverage
+#   orientation purposes. Otherwise coverage in the Balsam data directory is
+#   (unsuccessfully) collected.
+libepath = os.path.dirname(libensemble.__file__)
+os.environ['LIBE_PATH'] = libepath
+
 # Balsam is meant for HPC systems that commonly distribute jobs across many
-#   nodes. Due to the nature of testing Balsam on local or CI systems which usually
-#   only contain a single node, we need to change Balsam's default worker setup
-#   so multiple workers can be run on a single node.
-#   For our purposes, we append ten workers to Balsam's WorkerGroup
+#   nodes. For our purposes, we append (hack) ten workers to Balsam's WorkerGroup
 print("Currently in {}. Beginning Balsam worker modification".format(os.getcwd()))
 modify_Balsam_worker()
 
-# Executes Balsam Job
 # By this point, script_test_balsam.py has been submitted as an app and job to Balsam
 # This line launches the queued job in the Balsam database
 runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
@@ -46,13 +49,13 @@
     sys.stdout.flush()
     time.sleep(1)
 
-# Periodically check for Balsam general output
+# Job directory now exists
 jobdirname = os.listdir(basedb)[0]
 jobdir = os.path.join(basedb, jobdirname)
 outscript = os.path.join(jobdir, 'job_script_test_balsam.out')
 
 # Periodically wait for Balsam Job output
-print('{}: Beginning cycle of checking for Balsam output: {}'.format(sleeptime, outscript))
+print('{}: Checking for Balsam output file: {}'.format(sleeptime, outscript))
 while not os.path.isfile(outscript) and sleeptime < 58:
     sleeptime += 2
     print('{}'.format(sleeptime), end=" ")
@@ -60,12 +63,12 @@
     time.sleep(2)
 
 # Print sections of Balsam output to screen every second until complete
-print('{}: Attempting to print output.'.format(sleeptime))
+print('{}: Output file exists. Waiting for Balsam Job Output.'.format(sleeptime))
 lastposition = 0
 lastlines = ['Job 4 done on worker 1\n', 'Job 4 done on worker 2\n']
 while sleeptime < 58:
     with open(outscript, 'r') as f:
-        f.seek(lastposition)    # Prevents outputting already printed sections
+        f.seek(lastposition)    # (should) prevent outputting already printed sections
         new = f.read()
         lastposition = f.tell()
     if len(new) > 0:
@@ -73,6 +76,7 @@
         sys.stdout.flush()
     if any(new.endswith(line) for line in lastlines):
         break
+    print('{}'.format(sleeptime), end=" ")
     time.sleep(1)
     sleeptime += 1
 
diff --git a/libensemble/tests/regression_tests/.bal_coveragerc b/libensemble/tests/regression_tests/.bal_coveragerc
index e3a4097db..40a5b152f 100644
--- a/libensemble/tests/regression_tests/.bal_coveragerc
+++ b/libensemble/tests/regression_tests/.bal_coveragerc
@@ -1,5 +1,5 @@
 [run]
-source = /home/travis/build/Libensemble/libensemble
+source = $LIBE_PATH
 
 omit =
     */tests/*
diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index 075ea3263..4b5662489 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -174,10 +174,11 @@ def build_simfunc():
 
 def modify_Balsam_worker():
     # Balsam is meant for HPC systems that commonly distribute jobs across many
-    #   nodes. Due to the nature of testing Balsam on local or CI systems which usually
-    #   only contain a single node, we need to change Balsam's default worker setup
-    #   so multiple workers can be run on a single node (until this feature is [hopefully] added!).
-    #   For our purposes, we append ten workers to Balsam's WorkerGroup
+    #   nodes. Due to the nature of testing Balsam on local or CI systems which
+    #   usually only contain a single node, we need to change Balsam's default
+    #   worker setup so multiple workers can be run on a single node (until this
+    #   feature is [hopefully] added!).For our purposes, we append ten workers
+    #   to Balsam's WorkerGroup
     import balsam
 
     new_lines = ["        for idx in range(10):\n",
@@ -185,51 +186,47 @@ def modify_Balsam_worker():
                  "            self.workers.append(w)\n"]
 
     workerfile = 'worker.py'
-    home = os.getcwd()
-    balsam_worker_path = os.path.dirname(balsam.__file__) + '/launcher'
-    os.chdir(balsam_worker_path)
+    balsam_path = os.path.dirname(balsam.__file__) + '/launcher'
+    balsam_worker_path = os.path.join(balsam_path, workerfile)
 
-    with open(workerfile, 'r') as f:
+    with open(balsam_worker_path, 'r') as f:
         lines = f.readlines()
 
     if lines[-3] != new_lines[0]:
         lines = lines[:-2]  # effectively inserting new_lines[0] above
         lines.extend(new_lines)
 
-    with open(workerfile, 'w') as f:
+    with open(balsam_worker_path, 'w') as f:
         for line in lines:
             f.write(line)
 
-    print("Modified worker file in {}".format(os.getcwd()))
-    os.chdir(home)
+    print("Modified worker file in {}".format(balsam_path))
 
 
 def modify_Balsam_pyCoverage():
     # Tracking line coverage of our code through our tests requires running a test
     #   with the format 'python -m coverage run test.py args'. Balsam explicitely
-    #   configures Python executable runs with 'python test.py args' with no current
-    #   capability for specifying runtime Python options. This hack attempts to resolve
-    #   this for our purposes only.
+    #   configures Python runs with 'python test.py args' with no current
+    #   capability for specifying runtime Python options. This hack attempts to
+    #   resolve this for our purposes only.
     import balsam
 
     old_line = "            path = ' '.join((exe, script_path, args))\n"
     new_line = "            path = ' '.join((exe, '-m coverage run --parallel-mode --rcfile=./libensemble/tests/regression_tests/.bal_coveragerc', script_path, args))\n"
 
     commandfile = 'cli_commands.py'
-    home = os.getcwd()
-    balsam_scripts_path = os.path.dirname(balsam.__file__) + '/scripts'
-    os.chdir(balsam_scripts_path)
+    balsam_path = os.path.dirname(balsam.__file__) + '/scripts'
+    balsam_commands_path = os.path.join(balsam_path, commandfile)
 
-    with open(commandfile, 'r') as f:
+    with open(balsam_commands_path, 'r') as f:
         lines = f.readlines()
 
     for i in range(len(lines)):
         if lines[i] == old_line:
             lines[i] = new_line
 
-    with open(commandfile, 'w') as f:
+    with open(balsam_commands_path, 'w') as f:
         for line in lines:
             f.write(line)
 
-    print("Modified cli_commands file in {}".format(os.getcwd()))
-    os.chdir(home)
+    print("Modified cli_commands file in {}".format(balsam_scripts_path))
diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam.py
index 9c6034f11..d606bd099 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam.py
@@ -1,6 +1,5 @@
-# This script is submitted as an app and job to Balsam, and jobs
-#   are launched based on this app. This submission is via '
-#   balsam launch' executed in the test_balsam.py script.
+# This script is submitted as an app and job to Balsam. The job submission is
+#   via 'balsam launch' executed in the test_balsam.py script.
 
 import os
 import numpy as np
@@ -18,7 +17,7 @@
 mpi4py.rc.recv_mprobe = False  # Disable matching probes
 
 
-# Slighty different due to not executing in /regression_tests
+# Slighty different due to working directory not being /regression_tests
 def build_simfunc():
     import subprocess
     print('Balsam job launched in: {}'.format(os.getcwd()))

From 748bbe1ae3638d66baf586f5cff214afdacb5b14 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 26 Aug 2019 15:40:07 -0500
Subject: [PATCH 185/644] flake8

---
 libensemble/tests/regression_tests/common.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index 4b5662489..12518c49b 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -229,4 +229,4 @@ def modify_Balsam_pyCoverage():
         for line in lines:
             f.write(line)
 
-    print("Modified cli_commands file in {}".format(balsam_scripts_path))
+    print("Modified cli_commands file in {}".format(balsam_path))

From c6c2079eedf615cc7087ca497f4d05267a6aab28 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 27 Aug 2019 10:43:14 -0500
Subject: [PATCH 186/644] Renamed Balsam tests to include hworld, dramatic
 refactoring throughout

---
 conda/configure-balsam-test.sh                |  10 +-
 conda/install-balsam.py                       |  32 +++--
 conda/test_balsam.py                          |  95 ---------------
 conda/test_balsam_hworld.py                   | 109 ++++++++++++++++++
 libensemble/tests/regression_tests/common.py  |  21 ++--
 ...balsam.py => script_test_balsam_hworld.py} |   8 +-
 6 files changed, 144 insertions(+), 131 deletions(-)
 delete mode 100644 conda/test_balsam.py
 create mode 100644 conda/test_balsam_hworld.py
 rename libensemble/tests/regression_tests/{script_test_balsam.py => script_test_balsam_hworld.py} (91%)

diff --git a/conda/configure-balsam-test.sh b/conda/configure-balsam-test.sh
index 6eacd80aa..a284fd92e 100755
--- a/conda/configure-balsam-test.sh
+++ b/conda/configure-balsam-test.sh
@@ -4,19 +4,19 @@
 #   job_control_hworld_balsam test in the base libensemble directory.
 #   Besides ensuring that postgres and the generated Balsam db have the proper
 #   permissions, this script flushes previous apps and jobs in the db before
-#   submitting the test_balsam app/job script.
+#   submitting the test_balsam_hworld app/job script.
 #
 #   Most of this comes from scaling_tests/forces/balsam_local.sh
 
 # Can't run this line in calling Python file. Balsam installation hasn't been
 #   noticed by the Python runtime yet.
 python -c 'from libensemble.tests.regression_tests.common import modify_Balsam_pyCoverage; modify_Balsam_pyCoverage()'
-export EXE=$PWD/libensemble/tests/regression_tests/script_test_balsam.py
+export EXE=$PWD/libensemble/tests/regression_tests/script_test_balsam_hworld.py
 export NUM_WORKERS=2
 export WORKFLOW_NAME=libe_test-balsam
 export LIBE_WALLCLOCK=3
 export THIS_DIR=$PWD
-export SCRIPT_BASENAME=script_test_balsam
+export SCRIPT_BASENAME=script_test_balsam_hworld
 
 # Set proper permissions, initialize Balsam DB, activate DB
 export BALSAM_DB_PATH='~/test-balsam'
@@ -30,8 +30,8 @@ source balsamactivate test-balsam
 balsam rm apps --all --force
 balsam rm jobs --all --force
 
-# Submit script_test_balsam as app
+# Submit script_test_balsam_hworld as app
 balsam app --name $SCRIPT_BASENAME.app --exec $EXE --desc "Run $SCRIPT_BASENAME"
 
-# Submit job based on script_test_balsam app
+# Submit job based on script_test_balsam_hworld app
 balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --wall-time-minutes $LIBE_WALLCLOCK --num-nodes 1 --ranks-per-node $((NUM_WORKERS+1)) --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index 140ecf2c0..853c84f8e 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -1,23 +1,33 @@
 #! /usr/bin/env python
 
-# Installing Balsam consists of both cloning and pip installing the latest version
-#   of Balsam from source but also moving the Balsam-relevant test to the regression_tests
-#   directory. This way, run-tests won't run a non-relevant test if Balsam isn't
-#   installed or the necessary Python version isn't installed.
+# Configuring Balsam for libEnsemble consists of installing the latest version
+#   of Balsam from source and moving Balsam-relevant tests to the regression_tests
+#   directory. This way, run-tests won't run a non-relevant test if Balsam or the
+#   necessary Python version aren't installed.
 
 import sys
 import os
 import subprocess
 
 
-balsamclone = 'git clone https://github.com/balsam-alcf/balsam.git ../balsam'
-
-if int(sys.version[2]) >= 6:  # Balsam only supports Python 3.6+
+def install_balsam():
+    # Installs Balsam in a directory on the same level as the current directory.
+    here = os.getcwd()
+    balsamclone = 'git clone https://github.com/balsam-alcf/balsam.git ../balsam'
     subprocess.check_call(balsamclone.split())
     os.chdir('../balsam')
     subprocess.check_call('pip install -e .'.split())
-    os.chdir('../libensemble')
-    if not os.path.isfile('./libensemble/tests/regression_tests/test_balsam.py'):
-        os.rename('./conda/test_balsam.py',
-                  './libensemble/tests/regression_tests/test_balsam.py')
+    os.chdir(here)
+
+
+def move_test_balsam(balsam_test):
+    # Moves specified test from /conda to /regression_tests
+    reg_dir_with_btest = os.path.join('./libensemble/tests/regression_tests', balsam_test)
+    if not os.path.isfile(reg_dir_with_btest):
+        os.rename('./conda/{}'.format(balsam_test), reg_dir_with_btest)
+
+
+if int(sys.version[2]) >= 6:  # Balsam only supports Python 3.6+
+    install_balsam()
+    move_test_balsam('test_balsam_hworld.py')
     subprocess.run('./conda/configure-balsam-test.sh'.split())
diff --git a/conda/test_balsam.py b/conda/test_balsam.py
deleted file mode 100644
index d64697aa0..000000000
--- a/conda/test_balsam.py
+++ /dev/null
@@ -1,95 +0,0 @@
-import subprocess
-import os
-import time
-import sys
-import libensemble
-from libensemble.tests.regression_tests.common import parse_args, modify_Balsam_worker
-
-# TESTSUITE_COMMS: local
-# TESTSUITE_NPROCS: 3
-
-# This test is NOT submitted as a job to Balsam. That would be script_test_balsam.py
-#   This test executes that job through the 'runstr' line defined further down.
-
-nworkers, is_master, libE_specs, _ = parse_args()  # None used. Bug-prevention
-
-# Set libensemble base directory to environment variable for Balsam coverage
-#   orientation purposes. Otherwise coverage in the Balsam data directory is
-#   (unsuccessfully) collected.
-libepath = os.path.dirname(libensemble.__file__)
-os.environ['LIBE_PATH'] = libepath
-
-# Balsam is meant for HPC systems that commonly distribute jobs across many
-#   nodes. For our purposes, we append (hack) ten workers to Balsam's WorkerGroup
-print("Currently in {}. Beginning Balsam worker modification".format(os.getcwd()))
-modify_Balsam_worker()
-
-# By this point, script_test_balsam.py has been submitted as an app and job to Balsam
-# This line launches the queued job in the Balsam database
-runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
-print('Executing Balsam job with command: {}'.format(runstr))
-subprocess.Popen(runstr.split())
-
-# Location of Balsam DB location defined in configure-balsam-test.sh
-basedb = os.path.expanduser('~/test-balsam/data/libe_test-balsam')
-
-# Periodically wait for Workflow and Job directory within Balsam DB
-sleeptime = 0
-print('{}: Waiting for Workflow directory'.format(sleeptime))
-while not os.path.isdir(basedb) and sleeptime < 58:
-    sleeptime += 1
-    print('{}'.format(sleeptime), end=" ")
-    sys.stdout.flush()
-    time.sleep(1)
-
-print('{}: Waiting for Job Directory'.format(sleeptime))
-while len(os.listdir(basedb)) == 0 and sleeptime < 58:
-    sleeptime += 1
-    print('{}'.format(sleeptime), end=" ")
-    sys.stdout.flush()
-    time.sleep(1)
-
-# Job directory now exists
-jobdirname = os.listdir(basedb)[0]
-jobdir = os.path.join(basedb, jobdirname)
-outscript = os.path.join(jobdir, 'job_script_test_balsam.out')
-
-# Periodically wait for Balsam Job output
-print('{}: Checking for Balsam output file: {}'.format(sleeptime, outscript))
-while not os.path.isfile(outscript) and sleeptime < 58:
-    sleeptime += 2
-    print('{}'.format(sleeptime), end=" ")
-    sys.stdout.flush()
-    time.sleep(2)
-
-# Print sections of Balsam output to screen every second until complete
-print('{}: Output file exists. Waiting for Balsam Job Output.'.format(sleeptime))
-lastposition = 0
-lastlines = ['Job 4 done on worker 1\n', 'Job 4 done on worker 2\n']
-while sleeptime < 58:
-    with open(outscript, 'r') as f:
-        f.seek(lastposition)    # (should) prevent outputting already printed sections
-        new = f.read()
-        lastposition = f.tell()
-    if len(new) > 0:
-        print(new)
-        sys.stdout.flush()
-    if any(new.endswith(line) for line in lastlines):
-        break
-    print('{}'.format(sleeptime), end=" ")
-    time.sleep(1)
-    sleeptime += 1
-
-print('{}: Importing any coverage from Balsam.'.format(sleeptime))
-here = os.getcwd()
-
-# Move coverage files from Balsam DB to ./regression_tests (for concatenation)
-covname = '.cov_reg_out.'
-for file in os.listdir(jobdir):
-    if file.startswith(covname):
-        balsam_cov = os.path.join(jobdir, file)
-        here_cov = os.path.join(here, file)
-        print('Moved {} from {} to {}'.format(file, jobdir, here))
-        os.rename(balsam_cov, here_cov)
-
-print('Test complete.')
diff --git a/conda/test_balsam_hworld.py b/conda/test_balsam_hworld.py
new file mode 100644
index 000000000..900301bd8
--- /dev/null
+++ b/conda/test_balsam_hworld.py
@@ -0,0 +1,109 @@
+import subprocess
+import os
+import time
+import sys
+import libensemble
+from libensemble.tests.regression_tests.common import modify_Balsam_worker
+
+# TESTSUITE_COMMS: local
+# TESTSUITE_NPROCS: 3
+
+# This test is NOT submitted as a job to Balsam. Instead, script_test_balsam_hworld.py
+#   This test executes that job through the 'runstr' line in run_Balsam_job()
+
+
+def run_Balsam_job():
+    runstr = 'balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1'
+    print('Executing Balsam job with command: {}'.format(runstr))
+    subprocess.Popen(runstr.split())
+
+
+def wait_for_job_dir(basedb):
+    sleeptime = 0
+
+    while not os.path.isdir(basedb) and sleeptime < 15:
+        time.sleep(1)
+        sleeptime += 1
+
+    print('Waiting for Job Directory'.format(sleeptime))
+    while len(os.listdir(basedb)) == 0 and sleeptime < 15:
+        print('{}'.format(sleeptime), end=" ")
+        sys.stdout.flush()
+        time.sleep(1)
+        sleeptime += 1
+
+    jobdirname = os.listdir(basedb)[0]
+    jobdir = os.path.join(basedb, jobdirname)
+    return jobdir
+
+
+def wait_for_job_output(jobdir):
+    sleeptime = 0
+
+    output = os.path.join(jobdir, 'job_script_test_balsam_hworld.out')
+    print('Checking for Balsam output file: {}'.format(output))
+
+    while not os.path.isfile(output) and sleeptime < 30:
+        print('{}'.format(sleeptime), end=" ")
+        sys.stdout.flush()
+        time.sleep(2)
+        sleeptime += 2
+
+    return output
+
+
+def print_job_output(outscript):
+    sleeptime = 0
+
+    print('Output file found. Waiting for complete Balsam Job Output.')
+    lastlines = ['Job 4 done on worker 1\n', 'Job 4 done on worker 2\n']
+    lastposition = 0
+
+    while sleeptime < 60:
+        with open(outscript, 'r') as f:
+            f.seek(lastposition)
+            new = f.read()
+            lastposition = f.tell()
+
+        if len(new) > 0:
+            print(new)
+        else:
+            print('{}'.format(sleeptime), end=" ")
+        sys.stdout.flush()
+
+        if any(new.endswith(line) for line in lastlines):
+            break
+
+        time.sleep(1)
+        sleeptime += 1
+
+
+def move_job_coverage(jobdir):
+    # Move coverage files from Balsam DB to ./regression_tests (for concatenation)
+    here = os.getcwd()
+    covname = '.cov_reg_out.'
+
+    for file in os.listdir(jobdir):
+        if file.startswith(covname):
+            balsam_cov = os.path.join(jobdir, file)
+            here_cov = os.path.join(here, file)
+            os.rename(balsam_cov, here_cov)
+
+
+if __name__ == '__main__':
+
+    # For Balsam-specific Coverage config file, to not evaluate Balsam data dir
+    libepath = os.path.dirname(libensemble.__file__)
+    os.environ['LIBE_PATH'] = libepath
+
+    basedb = os.path.expanduser('~/test-balsam/data/libe_test-balsam')
+
+    modify_Balsam_worker()
+    run_Balsam_job()
+
+    jobdir = wait_for_job_dir(basedb)
+    output = wait_for_job_output(jobdir)
+    print_job_output(output)
+    move_job_coverage(jobdir)
+
+    print('Test complete.')
diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index 12518c49b..65f8ff953 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -176,9 +176,7 @@ def modify_Balsam_worker():
     # Balsam is meant for HPC systems that commonly distribute jobs across many
     #   nodes. Due to the nature of testing Balsam on local or CI systems which
     #   usually only contain a single node, we need to change Balsam's default
-    #   worker setup so multiple workers can be run on a single node (until this
-    #   feature is [hopefully] added!).For our purposes, we append ten workers
-    #   to Balsam's WorkerGroup
+    #   worker setup so multiple workers can be run on a single node.
     import balsam
 
     new_lines = ["        for idx in range(10):\n",
@@ -200,19 +198,18 @@ def modify_Balsam_worker():
         for line in lines:
             f.write(line)
 
-    print("Modified worker file in {}".format(balsam_path))
-
 
 def modify_Balsam_pyCoverage():
-    # Tracking line coverage of our code through our tests requires running a test
-    #   with the format 'python -m coverage run test.py args'. Balsam explicitely
-    #   configures Python runs with 'python test.py args' with no current
-    #   capability for specifying runtime Python options. This hack attempts to
-    #   resolve this for our purposes only.
+    # Tracking line coverage through our tests requires running the Python module
+    #   'coverage' directly. Balsam explicitely configures Python runs with
+    #   'python [script].py args' with no current capability for specifying
+    #   modules. This hack specifies the coverage module and some options.
     import balsam
 
     old_line = "            path = ' '.join((exe, script_path, args))\n"
-    new_line = "            path = ' '.join((exe, '-m coverage run --parallel-mode --rcfile=./libensemble/tests/regression_tests/.bal_coveragerc', script_path, args))\n"
+    new_line = "            path = ' '.join((exe, '-m coverage run " + \
+               "--parallel-mode --rcfile=./libensemble/tests/regression_tests/" + \
+               ".bal_coveragerc', script_path, args))\n"
 
     commandfile = 'cli_commands.py'
     balsam_path = os.path.dirname(balsam.__file__) + '/scripts'
@@ -228,5 +225,3 @@ def modify_Balsam_pyCoverage():
     with open(balsam_commands_path, 'w') as f:
         for line in lines:
             f.write(line)
-
-    print("Modified cli_commands file in {}".format(balsam_path))
diff --git a/libensemble/tests/regression_tests/script_test_balsam.py b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
similarity index 91%
rename from libensemble/tests/regression_tests/script_test_balsam.py
rename to libensemble/tests/regression_tests/script_test_balsam_hworld.py
index d606bd099..fd9430229 100644
--- a/libensemble/tests/regression_tests/script_test_balsam.py
+++ b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
@@ -1,5 +1,5 @@
 # This script is submitted as an app and job to Balsam. The job submission is
-#   via 'balsam launch' executed in the test_balsam.py script.
+#   via 'balsam launch' executed in the test_balsam_hworld.py script.
 
 import os
 import numpy as np
@@ -71,17 +71,11 @@ def build_simfunc():
 
 if is_master:
     print('\nChecking expected job status against Workers ...\n')
-
-    # Expected list: Last is zero as will not be entered into H array on
-    # manager kill - but should show in the summary file.
-    # Repeat expected lists nworkers times and compare with list of status's
-    # received from workers
     calc_status_list_in = np.asarray([WORKER_DONE, WORKER_KILL_ON_ERR,
                                       WORKER_KILL_ON_TIMEOUT,
                                       JOB_FAILED, 0])
     calc_status_list = np.repeat(calc_status_list_in, nworkers)
 
-    # For debug
     print("Expecting: {}".format(calc_status_list))
     print("Received:  {}\n".format(H['cstat']))
 

From 0a29517982a6df9e290c57840407885ba9653634 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 28 Aug 2019 09:55:07 -0500
Subject: [PATCH 187/644] Printing stuff

---
 libensemble/gen_funcs/support.py | 5 +++++
 libensemble/libE_manager.py      | 5 +++++
 2 files changed, 10 insertions(+)

diff --git a/libensemble/gen_funcs/support.py b/libensemble/gen_funcs/support.py
index e5084828d..75da6303a 100644
--- a/libensemble/gen_funcs/support.py
+++ b/libensemble/gen_funcs/support.py
@@ -16,6 +16,10 @@ def send_mgr_worker_msg(comm, O):
          'calc_status': UNSET_TAG,
          'calc_type': EVAL_GEN_TAG
          }
+    if O['sim_id'] > 200 or O['sim_id'] < 0 : 
+        import sys
+        sys.exit('Bad send')
+
     comm.send(EVAL_GEN_TAG, D)
 
 
@@ -27,4 +31,5 @@ def get_mgr_worker_msg(comm, status=None):
         comm.push_back(tag, Work)
         return tag, None, None
     _, calc_in = comm.recv()
+    print("Next to receive:", calc_in['sim_id'],flush=True)
     return tag, Work, calc_in
diff --git a/libensemble/libE_manager.py b/libensemble/libE_manager.py
index 2a1c24a46..dc18028ec 100644
--- a/libensemble/libE_manager.py
+++ b/libensemble/libE_manager.py
@@ -252,6 +252,11 @@ def _update_state_on_worker_msg(self, persis_info, D_recv, w):
             if calc_type == EVAL_SIM_TAG:
                 self.hist.update_history_f(D_recv)
             if calc_type == EVAL_GEN_TAG:
+                print('Outside_recieve:', D_recv['calc_out']['sim_id'],flush=True)
+                if (D_recv['calc_out']['sim_id'] > 200) or (D_recv['calc_out']['sim_id'] < 0):
+                    import ipdb; ipdb.set_trace()
+                    print("HA", D_recv['calc_out']['sim_id'], self.index)
+
                 self.hist.update_history_x_in(w, D_recv['calc_out'])
                 assert len(D_recv['calc_out']) or np.any(self.W['active']), \
                     "Gen must return work when is is the only thing active."

From c3821af8a7a709c8d394b1464ed38c66af7ca2d3 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 28 Aug 2019 10:41:24 -0500
Subject: [PATCH 188/644] Commenting-out prints and removing local from test

---
 libensemble/gen_funcs/support.py                          | 8 ++++----
 libensemble/libE_manager.py                               | 8 ++++----
 .../test_6-hump_camel_persistent_aposmm.py                | 2 +-
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/libensemble/gen_funcs/support.py b/libensemble/gen_funcs/support.py
index 75da6303a..d8774c2a1 100644
--- a/libensemble/gen_funcs/support.py
+++ b/libensemble/gen_funcs/support.py
@@ -16,9 +16,9 @@ def send_mgr_worker_msg(comm, O):
          'calc_status': UNSET_TAG,
          'calc_type': EVAL_GEN_TAG
          }
-    if O['sim_id'] > 200 or O['sim_id'] < 0 : 
-        import sys
-        sys.exit('Bad send')
+    # if O['sim_id'] > 200 or O['sim_id'] < 0:
+    #     import sys
+    #     sys.exit('Bad send')
 
     comm.send(EVAL_GEN_TAG, D)
 
@@ -31,5 +31,5 @@ def get_mgr_worker_msg(comm, status=None):
         comm.push_back(tag, Work)
         return tag, None, None
     _, calc_in = comm.recv()
-    print("Next to receive:", calc_in['sim_id'],flush=True)
+    # print("Next to receive:", calc_in['sim_id'], flush=True)
     return tag, Work, calc_in
diff --git a/libensemble/libE_manager.py b/libensemble/libE_manager.py
index dc18028ec..07610ae65 100644
--- a/libensemble/libE_manager.py
+++ b/libensemble/libE_manager.py
@@ -252,10 +252,10 @@ def _update_state_on_worker_msg(self, persis_info, D_recv, w):
             if calc_type == EVAL_SIM_TAG:
                 self.hist.update_history_f(D_recv)
             if calc_type == EVAL_GEN_TAG:
-                print('Outside_recieve:', D_recv['calc_out']['sim_id'],flush=True)
-                if (D_recv['calc_out']['sim_id'] > 200) or (D_recv['calc_out']['sim_id'] < 0):
-                    import ipdb; ipdb.set_trace()
-                    print("HA", D_recv['calc_out']['sim_id'], self.index)
+                # print('Outside_recieve:', D_recv['calc_out']['sim_id'], flush=True)
+                # if (D_recv['calc_out']['sim_id'] > 200) or (D_recv['calc_out']['sim_id'] < 0):
+                #     import ipdb; ipdb.set_trace()
+                #     print("HA", D_recv['calc_out']['sim_id'], self.index)
 
                 self.hist.update_history_x_in(w, D_recv['calc_out'])
                 assert len(D_recv['calc_out']) or np.any(self.W['active']), \
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index c6d0a1dc5..6e17ea272 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -11,7 +11,7 @@
 # """
 
 # Do not change these lines - they are parsed by run-tests.sh
-# TESTSUITE_COMMS: mpi local tcp
+# TESTSUITE_COMMS: mpi tcp
 # TESTSUITE_NPROCS: 3 4
 
 import sys

From 477161cccf96745169a5b70d0010d0b6bbb6ef7f Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 28 Aug 2019 10:47:14 -0500
Subject: [PATCH 189/644] Reverting and leaving example with (broken) prints

---
 libensemble/gen_funcs/support.py                          | 8 ++++----
 libensemble/libE_manager.py                               | 8 ++++----
 .../test_6-hump_camel_persistent_aposmm.py                | 4 ++--
 3 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/libensemble/gen_funcs/support.py b/libensemble/gen_funcs/support.py
index d8774c2a1..75da6303a 100644
--- a/libensemble/gen_funcs/support.py
+++ b/libensemble/gen_funcs/support.py
@@ -16,9 +16,9 @@ def send_mgr_worker_msg(comm, O):
          'calc_status': UNSET_TAG,
          'calc_type': EVAL_GEN_TAG
          }
-    # if O['sim_id'] > 200 or O['sim_id'] < 0:
-    #     import sys
-    #     sys.exit('Bad send')
+    if O['sim_id'] > 200 or O['sim_id'] < 0 : 
+        import sys
+        sys.exit('Bad send')
 
     comm.send(EVAL_GEN_TAG, D)
 
@@ -31,5 +31,5 @@ def get_mgr_worker_msg(comm, status=None):
         comm.push_back(tag, Work)
         return tag, None, None
     _, calc_in = comm.recv()
-    # print("Next to receive:", calc_in['sim_id'], flush=True)
+    print("Next to receive:", calc_in['sim_id'],flush=True)
     return tag, Work, calc_in
diff --git a/libensemble/libE_manager.py b/libensemble/libE_manager.py
index 07610ae65..dc18028ec 100644
--- a/libensemble/libE_manager.py
+++ b/libensemble/libE_manager.py
@@ -252,10 +252,10 @@ def _update_state_on_worker_msg(self, persis_info, D_recv, w):
             if calc_type == EVAL_SIM_TAG:
                 self.hist.update_history_f(D_recv)
             if calc_type == EVAL_GEN_TAG:
-                # print('Outside_recieve:', D_recv['calc_out']['sim_id'], flush=True)
-                # if (D_recv['calc_out']['sim_id'] > 200) or (D_recv['calc_out']['sim_id'] < 0):
-                #     import ipdb; ipdb.set_trace()
-                #     print("HA", D_recv['calc_out']['sim_id'], self.index)
+                print('Outside_recieve:', D_recv['calc_out']['sim_id'],flush=True)
+                if (D_recv['calc_out']['sim_id'] > 200) or (D_recv['calc_out']['sim_id'] < 0):
+                    import ipdb; ipdb.set_trace()
+                    print("HA", D_recv['calc_out']['sim_id'], self.index)
 
                 self.hist.update_history_x_in(w, D_recv['calc_out'])
                 assert len(D_recv['calc_out']) or np.any(self.W['active']), \
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index 6e17ea272..7921717df 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -11,7 +11,7 @@
 # """
 
 # Do not change these lines - they are parsed by run-tests.sh
-# TESTSUITE_COMMS: mpi tcp
+# TESTSUITE_COMMS: mpi local tcp
 # TESTSUITE_NPROCS: 3 4
 
 import sys
@@ -66,7 +66,7 @@
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
-exit_criteria = {'sim_max': 1000}
+exit_criteria = {'sim_max': 200}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,

From 165af8d8428ca6d5e9be13b5f5ba3402ed5d9091 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 28 Aug 2019 11:27:10 -0500
Subject: [PATCH 190/644] Fixing 1d FutureWarnings

---
 .../tests/regression_tests/test_inverse_bayes_example.py    | 2 +-
 libensemble/tests/unit_tests/setup.py                       | 6 +++++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/libensemble/tests/regression_tests/test_inverse_bayes_example.py b/libensemble/tests/regression_tests/test_inverse_bayes_example.py
index fbe0100af..bcbec1a3d 100644
--- a/libensemble/tests/regression_tests/test_inverse_bayes_example.py
+++ b/libensemble/tests/regression_tests/test_inverse_bayes_example.py
@@ -37,7 +37,7 @@
 gen_specs = {'gen_f': gen_f,
              'in': [],
              'out': [('x', float, 2), ('batch', int), ('subbatch', int),
-                     ('prior', float, 1), ('prop', float, 1), ('weight', float, 1)],
+                     ('prior', float), ('prop', float), ('weight', float)],
              'lb': np.array([-3, -2]),
              'ub': np.array([3, 2]),
              'subbatch_size': 3,
diff --git a/libensemble/tests/unit_tests/setup.py b/libensemble/tests/unit_tests/setup.py
index 592c52ed5..3f3f8173b 100644
--- a/libensemble/tests/unit_tests/setup.py
+++ b/libensemble/tests/unit_tests/setup.py
@@ -8,7 +8,11 @@
 
 def make_criteria_and_specs_0(simx=10, n=1):
     sim_specs = {'sim_f': np.linalg.norm, 'in': ['x_on_cube'], 'out': [('f', float), ('fvec', float, 3)], }
-    gen_specs = {'gen_f': np.random.uniform, 'in': [], 'out': [('x_on_cube', float, n), ('priority', float), ('local_pt', bool), ('local_min', bool), ('num_active_runs', int)], 'ub': np.ones(n), 'lb': np.zeros(n), 'nu': 0}
+    gen_specs = {'gen_f': np.random.uniform, 'in': [], 'out': [('priority', float), ('local_pt', bool), ('local_min', bool), ('num_active_runs', int)], 'ub': np.ones(n), 'lb': np.zeros(n), 'nu': 0}
+    if n == 1: 
+        gen_specs['out'] += [('x_on_cube', float)]
+    else:
+        gen_specs['out'] += [('x_on_cube', float, n)]
     exit_criteria = {'sim_max': simx}
 
     return sim_specs, gen_specs, exit_criteria

From e9e75d85fe2fcb35175baafceb596864358d9073 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 28 Aug 2019 13:46:56 -0500
Subject: [PATCH 191/644] flake8

---
 libensemble/tests/unit_tests/setup.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/unit_tests/setup.py b/libensemble/tests/unit_tests/setup.py
index 3f3f8173b..66114bcfe 100644
--- a/libensemble/tests/unit_tests/setup.py
+++ b/libensemble/tests/unit_tests/setup.py
@@ -9,7 +9,7 @@
 def make_criteria_and_specs_0(simx=10, n=1):
     sim_specs = {'sim_f': np.linalg.norm, 'in': ['x_on_cube'], 'out': [('f', float), ('fvec', float, 3)], }
     gen_specs = {'gen_f': np.random.uniform, 'in': [], 'out': [('priority', float), ('local_pt', bool), ('local_min', bool), ('num_active_runs', int)], 'ub': np.ones(n), 'lb': np.zeros(n), 'nu': 0}
-    if n == 1: 
+    if n == 1:
         gen_specs['out'] += [('x_on_cube', float)]
     else:
         gen_specs['out'] += [('x_on_cube', float, n)]

From 1eca03c8b041ef892db6934cdd5ade11dba10829 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 28 Aug 2019 14:57:04 -0500
Subject: [PATCH 192/644] Update history comparison script

---
 postproc_scripts/compare_npy.py | 19 ++++++++++++++++---
 postproc_scripts/readme.rst     |  2 +-
 2 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/postproc_scripts/compare_npy.py b/postproc_scripts/compare_npy.py
index cb274ffbc..0489ff512 100755
--- a/postproc_scripts/compare_npy.py
+++ b/postproc_scripts/compare_npy.py
@@ -1,16 +1,29 @@
 #!/usr/bin/env python
 
+'''Script to compare libEnsemble history arrays in files.
+
+If two *.npy files are provided they are compared with each other.
+If one *.npy file is provided if is compared with a hard-coded expected file 
+(by default located at ../expected.npy)
+Default NumPy tolerances are used for comparison (rtol=1e-05, atol=1e-08) and
+Nans compare as equal. Variable fields (such as those containing a time)
+are ignored.
+'''
+
 import sys
 import numpy as np
 
-if len(sys.argv) > 1:
+if len(sys.argv) > 2:
+    results = np.load(sys.argv[1])
+    exp_results = np.load(sys.argv[2])
+elif len(sys.argv) > 1:
     results = np.load(sys.argv[1])
+    exp_results_file = "../expected.npy"
+    exp_results = np.load(exp_results_file)    
 else:
     print('You need to supply an .npy file - aborting')
     sys.exit()
 
-exp_results_file = "../expected.npy"
-exp_results = np.load(exp_results_file)
 exclude_fields = ['gen_worker', 'sim_worker', 'gen_time', 'given_time']  # list of fields to ignore
 locate_mismatch = True
 
diff --git a/postproc_scripts/readme.rst b/postproc_scripts/readme.rst
index b2a102d36..1bed83f25 100644
--- a/postproc_scripts/readme.rst
+++ b/postproc_scripts/readme.rst
@@ -21,4 +21,4 @@ Results analysis scripts
 
     ./print_npy.py run_libe_forces_results_History_length=1000_evals=8.npy done
 
-* **compare_npy.py**: Compares a provided ``*.npy`` file with an expected results file (by default located at ../expected.npy). A tolerance is given on floating point results, nans are compared as equal, and variable fields (such as those containing a time) are ignored. These fields may need to be modified depending on user's history array.
+* **compare_npy.py**: Compares either two provided ``*.npy`` files or one provided ``*.npy`` file with an expected results file (by default located at ../expected.npy). A tolerance is given on floating point results and NANs are compared as equal. Variable fields (such as those containing a time) are ignored. These fields may need to be modified depending on user's history array.

From 66bd418ab6b483e48d0d3e60754599c1efbcc7c2 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 28 Aug 2019 16:01:02 -0500
Subject: [PATCH 193/644] Removing local until we can resolve the issue with
 nested multiprocessing

---
 .../regression_tests/test_6-hump_camel_persistent_aposmm.py     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index c6d0a1dc5..6e17ea272 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -11,7 +11,7 @@
 # """
 
 # Do not change these lines - they are parsed by run-tests.sh
-# TESTSUITE_COMMS: mpi local tcp
+# TESTSUITE_COMMS: mpi tcp
 # TESTSUITE_NPROCS: 3 4
 
 import sys

From 09752d69e681518082eba8df5ca668874af5964a Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 29 Aug 2019 08:28:02 -0500
Subject: [PATCH 194/644] Update .travis.yml

Agreeing with `develop` version
---
 .travis.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index df3df5dc4..b1cee2631 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -85,7 +85,6 @@ install:
   - pip install -e .
   - python conda/install-balsam.py
 
-
 before_script:
   - flake8 libensemble
   - echo "export BALSAM_DB_PATH=~/test-balsam" > setbalsampath.sh

From d3c7928e8bf9a63b6049083c2c59178ae405b1db Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 29 Aug 2019 12:39:53 -0500
Subject: [PATCH 195/644] Putting in a pause and still having the issue.

---
 libensemble/gen_funcs/persistent_aposmm.py                    | 1 +
 libensemble/libE_manager.py                                   | 4 ++--
 .../regression_tests/test_6-hump_camel_persistent_aposmm.py   | 2 +-
 3 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 5746b5364..b1a19347b 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -223,6 +223,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag,
                                              comm, local_H, sim_id_to_child_indices)
 
+    time.sleep(5)
     tag = None
     max_active_runs = gen_specs.get('max_active_runs', np.inf)
     waiting_starting_inds = []
diff --git a/libensemble/libE_manager.py b/libensemble/libE_manager.py
index dc18028ec..481c6c9ae 100644
--- a/libensemble/libE_manager.py
+++ b/libensemble/libE_manager.py
@@ -253,9 +253,9 @@ def _update_state_on_worker_msg(self, persis_info, D_recv, w):
                 self.hist.update_history_f(D_recv)
             if calc_type == EVAL_GEN_TAG:
                 print('Outside_recieve:', D_recv['calc_out']['sim_id'],flush=True)
-                if (D_recv['calc_out']['sim_id'] > 200) or (D_recv['calc_out']['sim_id'] < 0):
+                if D_recv['calc_out']['sim_id'] != self.hist.index:
                     import ipdb; ipdb.set_trace()
-                    print("HA", D_recv['calc_out']['sim_id'], self.index)
+                    print("HA", D_recv['calc_out']['sim_id'], self.hist.index)
 
                 self.hist.update_history_x_in(w, D_recv['calc_out'])
                 assert len(D_recv['calc_out']) or np.any(self.W['active']), \
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index 7921717df..f3e4e99ae 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -66,7 +66,7 @@
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
-exit_criteria = {'sim_max': 200}
+exit_criteria = {'sim_max': 100}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,

From 77d3b803be48029da35fa474b2e03554eb8161f0 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Fri, 30 Aug 2019 15:51:25 -0500
Subject: [PATCH 196/644] Add srun option to mpi_controller

---
 libensemble/mpi_controller.py |  3 ++-
 libensemble/resources.py      | 24 +++++++++++++++++-------
 2 files changed, 19 insertions(+), 8 deletions(-)

diff --git a/libensemble/mpi_controller.py b/libensemble/mpi_controller.py
index 31991bbf1..ec3c7ccfd 100644
--- a/libensemble/mpi_controller.py
+++ b/libensemble/mpi_controller.py
@@ -87,7 +87,8 @@ def __init__(self, auto_resources=True, central_mode=False,
             'aprun': ['aprun', '-e {env}',
                       '-L {hostlist}', '-n {num_procs}',
                       '-N {ranks_per_node}'],
-            'jsrun': ['jsrun', '--np {num_procs}']
+            'jsrun': ['jsrun', '--np {num_procs}'],  # Need to add more
+            'srun': ['srun', '-w {hostlist}', '-n {num_procs}']  # Need to add more
         }
         self.mpi_launch_type = MPIResources.get_MPI_variant()
         self.mpi_command = mpi_commands[self.mpi_launch_type]
diff --git a/libensemble/resources.py b/libensemble/resources.py
index 9d143bba2..a5254499c 100644
--- a/libensemble/resources.py
+++ b/libensemble/resources.py
@@ -150,13 +150,23 @@ def get_MPI_variant():
         except OSError:
             pass
 
-        # Explore mpi4py.MPI.get_vendor() and mpi4py.MPI.Get_library_version() for mpi4py
-        try_mpich = subprocess.Popen(['mpirun', '-npernode'], stdout=subprocess.PIPE,
-                                     stderr=subprocess.STDOUT)
-        stdout, _ = try_mpich.communicate()
-        if 'unrecognized argument npernode' in stdout.decode():
-            return 'mpich'
-        return 'openmpi'
+        try:
+            # Explore mpi4py.MPI.get_vendor() and mpi4py.MPI.Get_library_version() for mpi4py
+            try_mpich = subprocess.Popen(['mpirun', '-npernode'], stdout=subprocess.PIPE,
+                                         stderr=subprocess.STDOUT)
+            stdout, _ = try_mpich.communicate()
+            if 'unrecognized argument npernode' in stdout.decode():
+                return 'mpich'
+            return 'openmpi'
+        except Exception as e:
+            print('Testing: Error on MPI command: {}'.format(e))
+            pass
+
+        try:
+            subprocess.check_call(['srun', '--version'], stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+            return 'srun'
+        except OSError:
+            pass
 
     # ---------------------------------------------------------------------------
 

From 77f310e9ea813bb766759b8570f710a519e27ee8 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Fri, 30 Aug 2019 15:53:22 -0500
Subject: [PATCH 197/644] Correction to get_slurm_nodelist

---
 libensemble/env_resources.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/libensemble/env_resources.py b/libensemble/env_resources.py
index 9d1f118da..3271c8127 100644
--- a/libensemble/env_resources.py
+++ b/libensemble/env_resources.py
@@ -112,13 +112,13 @@ def get_slurm_nodelist(node_list_env):
         fullstr = os.environ[node_list_env]
         if not fullstr:
             return []
-        splitstr = fullstr.split('-', 1)
+        splitstr = fullstr.split('[', 1)
         prefix = splitstr[0]
-        nidstr = splitstr[1].strip("[]")
+        nidstr = splitstr[1].strip("]")
         for nidgroup in nidstr.split(','):
             a, b, nnum_len = EnvResources._range_split(nidgroup)
             for nid in range(a, b):
-                nidlst.append(prefix + '-' + str(nid).zfill(nnum_len))
+                nidlst.append(prefix + str(nid).zfill(nnum_len))
         return sorted(nidlst)
 
     @staticmethod

From 32241157a445979ec46158502291e84affe86f4f Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Fri, 30 Aug 2019 17:30:15 -0500
Subject: [PATCH 198/644] Fix single node case and add tests

---
 libensemble/env_resources.py                     |  2 ++
 .../tests/unit_tests/test_env_resources.py       | 16 ++++++++++++++++
 2 files changed, 18 insertions(+)

diff --git a/libensemble/env_resources.py b/libensemble/env_resources.py
index 3271c8127..2225bf795 100644
--- a/libensemble/env_resources.py
+++ b/libensemble/env_resources.py
@@ -113,6 +113,8 @@ def get_slurm_nodelist(node_list_env):
         if not fullstr:
             return []
         splitstr = fullstr.split('[', 1)
+        if len(splitstr) == 1:
+            return splitstr
         prefix = splitstr[0]
         nidstr = splitstr[1].strip("]")
         for nidgroup in nidstr.split(','):
diff --git a/libensemble/tests/unit_tests/test_env_resources.py b/libensemble/tests/unit_tests/test_env_resources.py
index 59169701e..b63bbd0fa 100644
--- a/libensemble/tests/unit_tests/test_env_resources.py
+++ b/libensemble/tests/unit_tests/test_env_resources.py
@@ -38,6 +38,13 @@ def test_slurm_nodelist_single():
     assert nodelist == exp_out, "Nodelist returned does not match expected"
 
 
+def test_slurm_nodelist_single_nodash():
+    os.environ["LIBE_RESOURCES_TEST_NODE_LIST"] = "nid00056"
+    exp_out = ["nid00056"]
+    nodelist = EnvResources.get_slurm_nodelist(node_list_env="LIBE_RESOURCES_TEST_NODE_LIST")
+    assert nodelist == exp_out, "Nodelist returned does not match expected"
+
+
 def test_slurm_nodelist_knl_seq():
     os.environ["LIBE_RESOURCES_TEST_NODE_LIST"] = "knl-[0009-0012]"
     exp_out = ['knl-0009', 'knl-0010', 'knl-0011', 'knl-0012']
@@ -59,6 +66,13 @@ def test_slurm_nodelist_groups():
     assert nodelist == exp_out, "Nodelist returned does not match expected"
 
 
+def test_slurm_nodelist_groups_nodash():
+    os.environ["LIBE_RESOURCES_TEST_NODE_LIST"] = "nid0[0020-0022,0137-0139,1234]"
+    exp_out = ['nid00020', 'nid00021', 'nid00022', 'nid00137', 'nid00138', 'nid00139', 'nid01234']
+    nodelist = EnvResources.get_slurm_nodelist(node_list_env="LIBE_RESOURCES_TEST_NODE_LIST")
+    assert nodelist == exp_out, "Nodelist returned does not match expected"
+
+
 def test_slurm_nodelist_groups_longprefix():
     os.environ["LIBE_RESOURCES_TEST_NODE_LIST"] = "super-[000020-000022,000137-000139,001234,023456-023458]"
     exp_out = ['super-000020', 'super-000021', 'super-000022', 'super-000137', 'super-000138', 'super-000139',
@@ -191,9 +205,11 @@ def test_abbrev_nodenames_cobalt():
 
     test_slurm_nodelist_empty()
     test_slurm_nodelist_single()
+    test_slurm_nodelist_single_nodash()
     test_slurm_nodelist_knl_seq()
     test_slurm_nodelist_bdw_seq()
     test_slurm_nodelist_groups()
+    test_slurm_nodelist_groups_nodash()
     test_slurm_nodelist_groups_longprefix()
     test_slurm_nodelist_reverse_grp()
 

From 80ff1d59d5b64e37d7d2e7a28e73c1e33e2eac9f Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 4 Sep 2019 09:52:29 -0500
Subject: [PATCH 199/644] Trying to debug too many files open error on
 OSX+Python-multiprocessing

---
 libensemble/gen_funcs/persistent_aposmm.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 5746b5364..9e0f80474 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -259,6 +259,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
         if sim_id_to_child_indices.get(sim_id_recv):
             for child_idx in sim_id_to_child_indices[sim_id_recv]:
+                print(np.sum([i.is_running for i in local_opters]))
                 x_new = local_opters[child_idx].iterate(*data_to_give_processes)
                 if isinstance(x_new, ConvergedMsg):
                     x_opt = x_new.x

From bb167d9e3bfc142d3050235328e2d9efff667b12 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 4 Sep 2019 09:57:28 -0500
Subject: [PATCH 200/644] Trying to join and then terminate processes

---
 libensemble/gen_funcs/persistent_aposmm.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 9e0f80474..70daab13d 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -427,6 +427,7 @@ def iterate(self, f, grad=None):
         x_new = self.comm_queue.get()
         if isinstance(x_new, ConvergedMsg):
             self.process.join()
+            self.process.terminate()
             self.is_running = False
 
         return x_new

From ad3659a0dc9038cc46f7c475044c2aa2c0faae97 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 4 Sep 2019 10:41:41 -0500
Subject: [PATCH 201/644] experimental sleep on worker -> manager message to
 prevent data corruption

---
 libensemble/gen_funcs/support.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/libensemble/gen_funcs/support.py b/libensemble/gen_funcs/support.py
index 75da6303a..231daf410 100644
--- a/libensemble/gen_funcs/support.py
+++ b/libensemble/gen_funcs/support.py
@@ -1,5 +1,7 @@
 from libensemble.message_numbers import STOP_TAG, PERSIS_STOP, UNSET_TAG, EVAL_GEN_TAG
 
+import time
+
 
 def sendrecv_mgr_worker_msg(comm, O, status=None):
     """Send message from worker to manager and receive response.
@@ -16,11 +18,12 @@ def send_mgr_worker_msg(comm, O):
          'calc_status': UNSET_TAG,
          'calc_type': EVAL_GEN_TAG
          }
-    if O['sim_id'] > 200 or O['sim_id'] < 0 : 
+    if O['sim_id'] > 200 or O['sim_id'] < 0 :
         import sys
         sys.exit('Bad send')
 
     comm.send(EVAL_GEN_TAG, D)
+    time.sleep(0.01)
 
 
 def get_mgr_worker_msg(comm, status=None):

From 9d282a95b227b10f974d07de9bb88392fc41423b Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 4 Sep 2019 10:52:24 -0500
Subject: [PATCH 202/644] Removing terminate (which should be unnecessary)

---
 libensemble/gen_funcs/persistent_aposmm.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 70daab13d..9e0f80474 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -427,7 +427,6 @@ def iterate(self, f, grad=None):
         x_new = self.comm_queue.get()
         if isinstance(x_new, ConvergedMsg):
             self.process.join()
-            self.process.terminate()
             self.is_running = False
 
         return x_new

From 7e038fba6b9d5d46e4cd867ddadaf16d496e3fef Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 4 Sep 2019 14:57:36 -0500
Subject: [PATCH 203/644] comments on sleep, reenables local (for testing)

---
 libensemble/gen_funcs/support.py                               | 3 +--
 .../regression_tests/test_6-hump_camel_persistent_aposmm.py    | 2 +-
 2 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/libensemble/gen_funcs/support.py b/libensemble/gen_funcs/support.py
index 231daf410..2529ac2ce 100644
--- a/libensemble/gen_funcs/support.py
+++ b/libensemble/gen_funcs/support.py
@@ -23,8 +23,7 @@ def send_mgr_worker_msg(comm, O):
         sys.exit('Bad send')
 
     comm.send(EVAL_GEN_TAG, D)
-    time.sleep(0.01)
-
+    time.sleep(0.01)  # May prevent queue corruption. Investigate
 
 def get_mgr_worker_msg(comm, status=None):
     """Get message to worker from manager.
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index 97ab7a3f8..f3e4e99ae 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -11,7 +11,7 @@
 # """
 
 # Do not change these lines - they are parsed by run-tests.sh
-# TESTSUITE_COMMS: mpi tcp
+# TESTSUITE_COMMS: mpi local tcp
 # TESTSUITE_NPROCS: 3 4
 
 import sys

From d935007644277c47c7c6acbe6675894f30dc5917 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 4 Sep 2019 14:59:39 -0500
Subject: [PATCH 204/644] Adds ulimit adjustment to travis

---
 .travis.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.travis.yml b/.travis.yml
index b1cee2631..4cc24d54c 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -89,6 +89,8 @@ before_script:
   - flake8 libensemble
   - echo "export BALSAM_DB_PATH=~/test-balsam" > setbalsampath.sh
   - source setbalsampath.sh
+  # Allow 10000 files to be open at once (critical for persistent_aposmm)
+  - ulimit -Sn 10000
   # Set conda compilers to use new SDK instead of Travis default.
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
         echo "export CONDA_BUILD_SYSROOT=/Users/travis/build/Libensemble/sdk/MacOSX10.13.sdk" > setenv.sh;

From ebf39c5b4902b9473e7f5ccb97873736cb57a113 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 4 Sep 2019 15:15:54 -0500
Subject: [PATCH 205/644] flake8, comment out debug statements

---
 libensemble/gen_funcs/persistent_aposmm.py |  1 -
 libensemble/gen_funcs/support.py           | 10 +++++-----
 libensemble/libE_manager.py                |  8 ++++----
 3 files changed, 9 insertions(+), 10 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index b1a19347b..5746b5364 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -223,7 +223,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag,
                                              comm, local_H, sim_id_to_child_indices)
 
-    time.sleep(5)
     tag = None
     max_active_runs = gen_specs.get('max_active_runs', np.inf)
     waiting_starting_inds = []
diff --git a/libensemble/gen_funcs/support.py b/libensemble/gen_funcs/support.py
index 2529ac2ce..f7e14b69c 100644
--- a/libensemble/gen_funcs/support.py
+++ b/libensemble/gen_funcs/support.py
@@ -1,5 +1,4 @@
 from libensemble.message_numbers import STOP_TAG, PERSIS_STOP, UNSET_TAG, EVAL_GEN_TAG
-
 import time
 
 
@@ -18,13 +17,14 @@ def send_mgr_worker_msg(comm, O):
          'calc_status': UNSET_TAG,
          'calc_type': EVAL_GEN_TAG
          }
-    if O['sim_id'] > 200 or O['sim_id'] < 0 :
-        import sys
-        sys.exit('Bad send')
+    # if O['sim_id'] > 200 or O['sim_id'] < 0:
+    #     import sys
+    #     sys.exit('Bad send')
 
     comm.send(EVAL_GEN_TAG, D)
     time.sleep(0.01)  # May prevent queue corruption. Investigate
 
+
 def get_mgr_worker_msg(comm, status=None):
     """Get message to worker from manager.
     """
@@ -33,5 +33,5 @@ def get_mgr_worker_msg(comm, status=None):
         comm.push_back(tag, Work)
         return tag, None, None
     _, calc_in = comm.recv()
-    print("Next to receive:", calc_in['sim_id'],flush=True)
+    # print("Next to receive:", calc_in['sim_id'], flush=True)
     return tag, Work, calc_in
diff --git a/libensemble/libE_manager.py b/libensemble/libE_manager.py
index 36c98b89f..3a08afcbe 100644
--- a/libensemble/libE_manager.py
+++ b/libensemble/libE_manager.py
@@ -294,10 +294,10 @@ def _update_state_on_worker_msg(self, persis_info, D_recv, w):
             if calc_type == EVAL_SIM_TAG:
                 self.hist.update_history_f(D_recv)
             if calc_type == EVAL_GEN_TAG:
-                print('Outside_recieve:', D_recv['calc_out']['sim_id'],flush=True)
-                if D_recv['calc_out']['sim_id'] != self.hist.index:
-                    import ipdb; ipdb.set_trace()
-                    print("HA", D_recv['calc_out']['sim_id'], self.hist.index)
+                # print('Outside_recieve:', D_recv['calc_out']['sim_id'], flush=True)
+                # if D_recv['calc_out']['sim_id'] != self.hist.index:
+                #     import ipdb; ipdb.set_trace()
+                #     print("HA", D_recv['calc_out']['sim_id'], self.hist.index)
 
                 self.hist.update_history_x_in(w, D_recv['calc_out'])
                 assert len(D_recv['calc_out']) or np.any(self.W['active']), \

From 105da229390baae999b11506d1518cb987b0a8e9 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 4 Sep 2019 15:32:24 -0500
Subject: [PATCH 206/644] update exit_criteria

---
 .../regression_tests/test_6-hump_camel_persistent_aposmm.py     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index f3e4e99ae..c6d0a1dc5 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -66,7 +66,7 @@
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
-exit_criteria = {'sim_max': 100}
+exit_criteria = {'sim_max': 1000}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,

From 770e814ba98a39737b5b0b1e45e1ecccfbbc9f5e Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Fri, 6 Sep 2019 12:53:38 -0500
Subject: [PATCH 207/644] Add srun options

---
 libensemble/mpi_controller.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/libensemble/mpi_controller.py b/libensemble/mpi_controller.py
index ec3c7ccfd..c5e5f2ec8 100644
--- a/libensemble/mpi_controller.py
+++ b/libensemble/mpi_controller.py
@@ -88,7 +88,8 @@ def __init__(self, auto_resources=True, central_mode=False,
                       '-L {hostlist}', '-n {num_procs}',
                       '-N {ranks_per_node}'],
             'jsrun': ['jsrun', '--np {num_procs}'],  # Need to add more
-            'srun': ['srun', '-w {hostlist}', '-n {num_procs}']  # Need to add more
+            'srun': ['srun', '-w {hostlist}', '-n {num_procs}',
+                     '--ntasks-per-node {ranks_per_node}']  # Need to add more
         }
         self.mpi_launch_type = MPIResources.get_MPI_variant()
         self.mpi_command = mpi_commands[self.mpi_launch_type]

From 5801e947c85704cf221ffb72dd42c84d113bccc0 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 6 Sep 2019 15:52:01 -0500
Subject: [PATCH 208/644] Trying to communicate only in batches

---
 .../alloc_funcs/persistent_aposmm_alloc.py    |  53 +++++
 libensemble/gen_funcs/persistent_aposmm.py    | 198 ++++++------------
 .../test_6-hump_camel_persistent_aposmm.py    |   2 +-
 3 files changed, 122 insertions(+), 131 deletions(-)
 create mode 100644 libensemble/alloc_funcs/persistent_aposmm_alloc.py

diff --git a/libensemble/alloc_funcs/persistent_aposmm_alloc.py b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
new file mode 100644
index 000000000..652d85f8e
--- /dev/null
+++ b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
@@ -0,0 +1,53 @@
+import numpy as np
+
+from libensemble.alloc_funcs.support import avail_worker_ids, sim_work, gen_work, count_persis_gens
+
+
+def persistent_aposmm_alloc(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
+    """
+    This allocation function will give simulation work if possible, but
+    otherwise start up to 1 persistent generator.  If all points requested by
+    the persistent generator have been returned from the simulation evaluation,
+    then this information is given back to the persistent generator.
+
+    :See:
+        ``/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py``
+    """
+
+    Work = {}
+    gen_count = count_persis_gens(W)
+
+    # If i is in persistent mode, and any of its calculated values have
+    # returned, give them back to i. Otherwise, give nothing to i
+    for i in avail_worker_ids(W, persistent=True):
+        gen_inds = (H['gen_worker'] == i)
+        returned_but_not_given = np.logical_and(H['returned'][gen_inds], ~H['given_back'][gen_inds])
+        if np.any(returned_but_not_given):
+            # If a point is a sample point, only return it if all other sample
+            # points requested at the same time are returned. 
+            last_time_gen_gave_batch = np.unique(H['gen_time'][returned_but_not_given])
+            assert(len(last_time_gen_gave_batch)) == 1, "It shouldn't be possible for persistent aposmm to give two batches."
+            inds_of_last_batch_from_gen = H['sim_id'][gen_inds][H['gen_time'][gen_inds] == last_time_gen_gave_batch]
+
+            if np.all(H[inds_of_last_batch_from_gen]['returned']):
+                gen_work(Work, i,
+                         sim_specs['in'] + [n[0] for n in sim_specs['out']] + [('sim_id')],
+                         np.atleast_1d(inds_of_last_batch_from_gen), persis_info[i], persistent=True)
+
+                H['given_back'][inds_of_last_batch_from_gen] = True
+
+    task_avail = ~H['given']
+    for i in avail_worker_ids(W, persistent=False):
+        if np.any(task_avail):
+            # perform sim evaluations (if they exist in History).
+            sim_ids_to_send = np.nonzero(task_avail)[0][0]  # oldest point
+            sim_work(Work, i, sim_specs['in'], np.atleast_1d(sim_ids_to_send), persis_info[i])
+            task_avail[sim_ids_to_send] = False
+
+        elif gen_count == 0:
+            # Finally, call a persistent generator as there is nothing else to do.
+            gen_count += 1
+            gen_work(Work, i, gen_specs['in'], [], persis_info[i],
+                     persistent=True)
+
+    return Work, persis_info
diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 5746b5364..b65044a3c 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -190,25 +190,16 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     persis_info['old_runs']: Sequence of indices of points in finished runs
 
     """
-    # {{{ multiprocessing initialization
-
-    # from libensemble.util.forkpdb import ForkablePdb
-    # ForkablePdb().set_trace()
+    n, n_s, c_flag, rk_const, ld, mu, nu, comm, local_H = initialize_APOSMM(H, gen_specs, libE_info)
 
+    # Initialize stuff for localopt children
     local_opters = []
     parent_can_read_from_queue = Event()
     comm_queue = Queue()
-
-    # }}}
-
-    n, n_s, c_flag, rk_const, ld, mu, nu, total_runs, comm, local_H = initialize_APOSMM(H, gen_specs, libE_info)
-
     sim_id_to_child_indices = {}
     child_id_to_run_id = {}
     run_order = {}
-
-    # {{{ setting the data needed by the local optimization method
-
+    total_runs = 0
     if gen_specs['localopt_method'] in ['LD_MMA', 'blmvm']:
         fields_to_pass = ['f', 'grad']
     elif gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA',
@@ -217,137 +208,74 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     else:
         raise NotImplementedError("Unknown local optimization method " "'{}'.".format(gen_specs['localopt_method']))
 
-    # }}}
 
-    for _ in range(gen_specs['initial_sample_size']):
-        send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag,
-                                             comm, local_H, sim_id_to_child_indices)
+    # Send our initial sample.W e don't need to check that n_s is large enough:
+    # the alloc_func only returns when the initial sample has function values.
+    send_k_sample_points_for_evaluation(gen_specs['initial_sample_size'],gen_specs,
+                                        persis_info, n, c_flag, comm, local_H,
+                                        sim_id_to_child_indices)
 
     tag = None
-    max_active_runs = gen_specs.get('max_active_runs', np.inf)
-    waiting_starting_inds = []
-
     while 1:
         tag, Work, calc_in = get_mgr_worker_msg(comm)
 
-        if calc_in:
-            if fields_to_pass == ['f', 'grad']:
-                (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv), = calc_in
-                data_to_give_processes = (f_x_recv, grad_f_x_recv)
-            else:
-                assert(fields_to_pass == ['f'])
-                if len(calc_in[0]) == 3:
-                    (x_recv, f_x_recv, sim_id_recv), = calc_in
-                else:
-                    # FIXME: *BIG BIG!*, even if we are passing grad_f even
-                    # though we are not using it.
-                    (x_recv, f_x_recv, grad_f_x_recv, sim_id_recv), = calc_in
-                data_to_give_processes = (f_x_recv, )
-
         if tag in [STOP_TAG, PERSIS_STOP]:
-            # FIXME: This has to be a clean exit.
-
-            print('[Parent]: The optimal points are:\n',
-                  local_H[np.where(local_H['local_min'])]['x'], flush=True)
-
-            for p in local_opters:
-                if p.is_running:
-                    p.destroy()
+            clean_up_and_stop(local_H, local_opters) 
             break
 
         n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
 
-        if sim_id_to_child_indices.get(sim_id_recv):
-            for child_idx in sim_id_to_child_indices[sim_id_recv]:
-                x_new = local_opters[child_idx].iterate(*data_to_give_processes)
-                if isinstance(x_new, ConvergedMsg):
-                    x_opt = x_new.x
-                    update_history_optimal(x_opt, local_H, run_order[child_id_to_run_id[child_idx]])
-
-                    if waiting_starting_inds:
-                        ind = waiting_starting_inds[0]
-                        waiting_starting_inds = waiting_starting_inds[1:]
-
-                        # {{{ initing a local opt run
-
-                        local_opter = LocalOptInterfacer(gen_specs,
-                                                         local_H[ind]['x_on_cube'],
-                                                         parent_can_read_from_queue, comm_queue,
-                                                         local_H[ind]['f'], grad_f_x_recv if 'grad' in
-                                                         fields_to_pass else None)
-                        local_opters.append(local_opter)
-                        x_new = local_opter.iterate(*local_H[ind][fields_to_pass])
-                        add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
-                        assert np.allclose(local_H[-1]['x_on_cube'], x_new)
-
-                        run_order[total_runs] = [local_H[-1]['sim_id']]
-                        child_id_to_run_id[len(local_opters)-1] = total_runs
-                        total_runs += 1
+        counter = 0
+        for row in calc_in:
+            if sim_id_to_child_indices.get(row['sim_id']):
+                # Point came from a child local opt run
+                for child_idx in sim_id_to_child_indices[row['sim_id']]:
+                    x_new = local_opters[child_idx].iterate(row[fields_to_pass])
+                    if isinstance(x_new, ConvergedMsg):
+                        x_opt = x_new.x
+                        update_history_optimal(x_opt, local_H, run_order[child_id_to_run_id[child_idx]])
+                    else:
+                        add_to_local_H(local_H, x_new, gen_specs, c_flag, local_flag=1, on_cube=True)
+                        counter += 1
 
+                        run_order[child_id_to_run_id[child_idx]].append(local_H[-1]['sim_id'])
                         if local_H[-1]['sim_id'] in sim_id_to_child_indices:
-                            sim_id_to_child_indices[local_H[-1]['sim_id']] += (len(local_opters)-1, )
+                            sim_id_to_child_indices[local_H[-1]['sim_id']] += (child_idx, )
                         else:
-                            sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(local_opters)-1, )
+                            sim_id_to_child_indices[local_H[-1]['sim_id']] = (child_idx, )
 
-                        # }}}
-
-                        send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
-                    else:
-                        send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
-                                                             sim_id_to_child_indices)
-                else:
-                    add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
-                    assert np.allclose(local_H[-1]['x_on_cube'], x_new)
-
-                    run_order[child_id_to_run_id[child_idx]].append(local_H[-1]['sim_id'])
-                    if local_H[-1]['sim_id'] in sim_id_to_child_indices:
-                        sim_id_to_child_indices[local_H[-1]['sim_id']] += (child_idx, )
-                    else:
-                        sim_id_to_child_indices[local_H[-1]['sim_id']] = (child_idx, )
-                    send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
-        else:
-            if n_s < gen_specs['initial_sample_size']:
-                continue
-            n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
-
-            starting_inds = decide_where_to_start_localopt(local_H, n, n_s, rk_const, ld, mu, nu)
-
-            for ind in starting_inds:
+        starting_inds = decide_where_to_start_localopt(local_H, n, n_s, rk_const, ld, mu, nu)
 
+        for ind in starting_inds:
+            if len([p for p in local_opters if p.is_running]) < gen_specs.get('max_active_runs', np.inf):
                 local_H['started_run'][ind] = 1
 
-                if len([p for p in local_opters if p.is_running]) < max_active_runs:
+                # Initialize a local opt run
+                local_opter = LocalOptInterfacer(gen_specs, local_H[ind]['x_on_cube'], parent_can_read_from_queue, comm_queue,
+                                                 local_H[ind]['f'], local_H[ind]['grad'] if 'grad' in fields_to_pass else None)
 
-                    # {{{ initing a local opt run
+                local_opters.append(local_opter)
 
-                    local_opter = LocalOptInterfacer(gen_specs,
-                                                     local_H[ind]['x_on_cube'],
-                                                     parent_can_read_from_queue, comm_queue,
-                                                     local_H[ind]['f'], grad_f_x_recv if 'grad' in fields_to_pass else None)
-                    local_opters.append(local_opter)
-                    x_new = local_opter.iterate(*local_H[ind][fields_to_pass])
+                x_new = local_opter.iterate(local_H[ind][fields_to_pass]) # Assuming the second point can't be ruled optimal 
 
-                    add_to_local_H(local_H, (x_new, ), gen_specs, c_flag, local_flag=1, on_cube=True)
-                    assert np.allclose(local_H[-1]['x_on_cube'], x_new)
+                add_to_local_H(local_H, x_new, gen_specs, c_flag, local_flag=1, on_cube=True)
+                counter += 1
 
-                    run_order[total_runs] = [local_H[-1]['sim_id']]
-                    child_id_to_run_id[len(local_opters)-1] = total_runs
-                    total_runs += 1
-
-                    if local_H[-1]['sim_id'] in sim_id_to_child_indices:
-                        sim_id_to_child_indices[local_H[-1]['sim_id']] += (len(local_opters)-1, )
-                    else:
-                        sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(local_opters)-1, )
+                run_order[total_runs] = [ind, local_H[-1]['sim_id']]
+                child_id_to_run_id[len(local_opters)-1] = total_runs
+                total_runs += 1
 
-                    # }}}
-
-                    send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
+                if local_H[-1]['sim_id'] in sim_id_to_child_indices:
+                    sim_id_to_child_indices[local_H[-1]['sim_id']] += (len(local_opters)-1, )
                 else:
-                    waiting_starting_inds.append(ind)
+                    sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(local_opters)-1, )
+
 
-            if len(starting_inds) == 0 and len(waiting_starting_inds) == 0:
-                send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H,
-                                                     sim_id_to_child_indices)
+        if counter == 0:
+            send_k_sample_points_for_evaluation(1, gen_specs, persis_info, n, c_flag, comm, local_H,
+                                                 sim_id_to_child_indices)
+        else: 
+            send_mgr_worker_msg(comm, local_H[-counter:][['x', 'sim_id']])
 
     comm_queue.close()
     comm_queue.join_thread()
@@ -406,7 +334,7 @@ def __init__(self, gen_specs, x0, parent_can_read, comm_queue, f0, grad0=None):
         self.parent_can_read.wait()
         assert np.allclose(comm_queue.get(), x0)
 
-    def iterate(self, f, grad=None):
+    def iterate(self, data):
         """
         Returns an instance of either :class:`numpy.ndarray` corresponding to the next
         iterative guess or :class:`ConvergedMsg` when the solver is converged.
@@ -415,10 +343,11 @@ def iterate(self, f, grad=None):
         :param grad: A numpy array of the function's gradient.
         """
         self.parent_can_read.clear()
-        if grad is None:
-            self.comm_queue.put((f, ))
+
+        if 'grad' in data.dtype.names:
+            self.comm_queue.put((data['f'], data['grad']))
         else:
-            self.comm_queue.put((f, grad))
+            self.comm_queue.put((data['f'], ))
 
         self.child_can_read.set()
         self.parent_can_read.wait()
@@ -427,6 +356,8 @@ def iterate(self, f, grad=None):
         if isinstance(x_new, ConvergedMsg):
             self.process.join()
             self.is_running = False
+        else: 
+            x_new = np.atleast_2d(x_new)
 
         return x_new
 
@@ -1005,8 +936,6 @@ def initialize_APOSMM(H, gen_specs, libE_info):
     else:
         nu = 0
 
-    total_runs = 0
-
     comm = libE_info['comm']
 
     local_H_fields = [('f', float),
@@ -1032,17 +961,26 @@ def initialize_APOSMM(H, gen_specs, libE_info):
 
     local_H = np.empty(0, dtype=local_H_fields)
 
-    return n, n_s, c_flag, rk_c, ld, mu, nu, total_runs, comm, local_H
+    return n, n_s, c_flag, rk_c, ld, mu, nu, comm, local_H
 
 
-def send_one_sample_point_for_evaluation(gen_specs, persis_info, n, c_flag, comm, local_H, sim_id_to_child_indices):
-    sampled_points = persis_info['rand_stream'].uniform(0, 1, (1, n))
+def send_k_sample_points_for_evaluation(k, gen_specs, persis_info, n, c_flag, comm, local_H, sim_id_to_child_indices):
+    sampled_points = persis_info['rand_stream'].uniform(0, 1, (k, n))
     add_to_local_H(local_H, sampled_points, gen_specs, c_flag, on_cube=True)
-    assert local_H['sim_id'][-1] not in sim_id_to_child_indices
-    sim_id_to_child_indices[local_H['sim_id'][-1]] = None
+    assert local_H['sim_id'][-k] not in sim_id_to_child_indices
+    # sim_id_to_child_indices[local_H['sim_id'][-k:]] = None
+
+    send_mgr_worker_msg(comm, local_H[-k:][['x', 'sim_id']])
+
+def clean_up_and_stop(local_H, local_opters):
+    # FIXME: This has to be a clean exit.
 
-    send_mgr_worker_msg(comm, local_H[-1:][['x', 'sim_id']])
+    print('[Parent]: The optimal points are:\n',
+          local_H[np.where(local_H['local_min'])]['x'], flush=True)
 
+    for p in local_opters:
+        if p.is_running:
+            p.destroy()
 
 def display_exception(e):
     print(e.__doc__)
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index c6d0a1dc5..74076c4b1 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -22,7 +22,7 @@
 from math import gamma, pi, sqrt
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
-from libensemble.alloc_funcs.start_only_persistent import only_persistent_gens as alloc_f
+from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 from time import time

From 077ba932aff8f62a4b51d7e65ae281c2bd4b306d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 6 Sep 2019 16:27:41 -0500
Subject: [PATCH 209/644] Now having each child use their own queue, and doing
 a handshake check with x_on_cube

---
 .../alloc_funcs/persistent_aposmm_alloc.py    |  2 +-
 libensemble/gen_funcs/persistent_aposmm.py    | 32 ++++++++++---------
 2 files changed, 18 insertions(+), 16 deletions(-)

diff --git a/libensemble/alloc_funcs/persistent_aposmm_alloc.py b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
index 652d85f8e..2edb3fe39 100644
--- a/libensemble/alloc_funcs/persistent_aposmm_alloc.py
+++ b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
@@ -31,7 +31,7 @@ def persistent_aposmm_alloc(W, H, sim_specs, gen_specs, alloc_specs, persis_info
 
             if np.all(H[inds_of_last_batch_from_gen]['returned']):
                 gen_work(Work, i,
-                         sim_specs['in'] + [n[0] for n in sim_specs['out']] + [('sim_id')],
+                         sim_specs['in'] + [n[0] for n in sim_specs['out']] + [('sim_id'),('x_on_cube')],
                          np.atleast_1d(inds_of_last_batch_from_gen), persis_info[i], persistent=True)
 
                 H['given_back'][inds_of_last_batch_from_gen] = True
diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index b65044a3c..a818b7a53 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -201,10 +201,10 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     run_order = {}
     total_runs = 0
     if gen_specs['localopt_method'] in ['LD_MMA', 'blmvm']:
-        fields_to_pass = ['f', 'grad']
+        fields_to_pass = ['x_on_cube', 'f', 'grad']
     elif gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA',
                                           'LN_NELDERMEAD', 'pounders', 'scipy_COBYLA']:
-        fields_to_pass = ['f']
+        fields_to_pass = ['x_on_cube', 'f']
     else:
         raise NotImplementedError("Unknown local optimization method " "'{}'.".format(gen_specs['localopt_method']))
 
@@ -251,7 +251,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 local_H['started_run'][ind] = 1
 
                 # Initialize a local opt run
-                local_opter = LocalOptInterfacer(gen_specs, local_H[ind]['x_on_cube'], parent_can_read_from_queue, comm_queue,
+                local_opter = LocalOptInterfacer(gen_specs, local_H[ind]['x_on_cube'], 
                                                  local_H[ind]['f'], local_H[ind]['grad'] if 'grad' in fields_to_pass else None)
 
                 local_opters.append(local_opter)
@@ -275,7 +275,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
             send_k_sample_points_for_evaluation(1, gen_specs, persis_info, n, c_flag, comm, local_H,
                                                  sim_id_to_child_indices)
         else: 
-            send_mgr_worker_msg(comm, local_H[-counter:][['x', 'sim_id']])
+            send_mgr_worker_msg(comm, local_H[-counter:][['x', 'x_on_cube', 'sim_id']])
 
     comm_queue.close()
     comm_queue.join_thread()
@@ -289,7 +289,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
 
 class LocalOptInterfacer(object):
-    def __init__(self, gen_specs, x0, parent_can_read, comm_queue, f0, grad0=None):
+    def __init__(self, gen_specs, x0, parent_can_read, f0, grad0=None):
         """
         :param x0: A numpy array of the initial guess solution. This guess
             should be scaled to a unit cube.
@@ -301,9 +301,9 @@ def __init__(self, gen_specs, x0, parent_can_read, comm_queue, f0, grad0=None):
             immediately after creating the class.
 
         """
-        self.parent_can_read = parent_can_read
+        self.parent_can_read = Event()
 
-        self.comm_queue = comm_queue
+        self.comm_queue = Queue()
         self.child_can_read = Event()
 
         self.x0 = x0
@@ -326,13 +326,13 @@ def __init__(self, gen_specs, x0, parent_can_read, comm_queue, f0, grad0=None):
 
         self.parent_can_read.clear()
         self.process = Process(target=run_local_opt, args=(gen_specs,
-                               comm_queue, x0, f0, self.child_can_read,
-                               parent_can_read))
+                               self.comm_queue, x0, f0, self.child_can_read,
+                               self.parent_can_read))
 
         self.process.start()
         self.is_running = True
         self.parent_can_read.wait()
-        assert np.allclose(comm_queue.get(), x0)
+        assert np.allclose(self.comm_queue.get(), x0)
 
     def iterate(self, data):
         """
@@ -345,9 +345,9 @@ def iterate(self, data):
         self.parent_can_read.clear()
 
         if 'grad' in data.dtype.names:
-            self.comm_queue.put((data['f'], data['grad']))
+            self.comm_queue.put((data['x_on_cube'], data['f'], data['grad']))
         else:
-            self.comm_queue.put((data['f'], ))
+            self.comm_queue.put((data['x_on_cube'], data['f'], ))
 
         self.child_can_read.set()
         self.parent_can_read.wait()
@@ -386,12 +386,14 @@ def nlopt_callback_fun(x, grad, comm_queue, child_can_read, parent_can_read, gen
     parent_can_read.set()
     child_can_read.wait()
     if gen_specs['localopt_method'] in ['LD_MMA']:
-        f_recv, grad_recv = comm_queue.get()
+        x_recv, f_recv, grad_recv = comm_queue.get()
         grad[:] = grad_recv
     else:
         assert gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA',
                                                 'LN_COBYLA', 'LN_NELDERMEAD', 'LD_MMA']
-        f_recv, = comm_queue.get()
+        x_recv, f_recv = comm_queue.get()
+
+    assert np.array_equal(x,x_recv), "The point I gave is not the point I got back!"
 
     child_can_read.clear()
 
@@ -970,7 +972,7 @@ def send_k_sample_points_for_evaluation(k, gen_specs, persis_info, n, c_flag, co
     assert local_H['sim_id'][-k] not in sim_id_to_child_indices
     # sim_id_to_child_indices[local_H['sim_id'][-k:]] = None
 
-    send_mgr_worker_msg(comm, local_H[-k:][['x', 'sim_id']])
+    send_mgr_worker_msg(comm, local_H[-k:][['x', 'x_on_cube', 'sim_id']])
 
 def clean_up_and_stop(local_H, local_opters):
     # FIXME: This has to be a clean exit.

From b80a2c9404fe4c6dcd370d53027b1521f5a56537 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 6 Sep 2019 16:31:59 -0500
Subject: [PATCH 210/644] flake8

---
 .../alloc_funcs/persistent_aposmm_alloc.py    |  4 +--
 libensemble/gen_funcs/persistent_aposmm.py    | 28 +++++++++----------
 2 files changed, 15 insertions(+), 17 deletions(-)

diff --git a/libensemble/alloc_funcs/persistent_aposmm_alloc.py b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
index 2edb3fe39..a4bc95772 100644
--- a/libensemble/alloc_funcs/persistent_aposmm_alloc.py
+++ b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
@@ -24,14 +24,14 @@ def persistent_aposmm_alloc(W, H, sim_specs, gen_specs, alloc_specs, persis_info
         returned_but_not_given = np.logical_and(H['returned'][gen_inds], ~H['given_back'][gen_inds])
         if np.any(returned_but_not_given):
             # If a point is a sample point, only return it if all other sample
-            # points requested at the same time are returned. 
+            # points requested at the same time are returned.
             last_time_gen_gave_batch = np.unique(H['gen_time'][returned_but_not_given])
             assert(len(last_time_gen_gave_batch)) == 1, "It shouldn't be possible for persistent aposmm to give two batches."
             inds_of_last_batch_from_gen = H['sim_id'][gen_inds][H['gen_time'][gen_inds] == last_time_gen_gave_batch]
 
             if np.all(H[inds_of_last_batch_from_gen]['returned']):
                 gen_work(Work, i,
-                         sim_specs['in'] + [n[0] for n in sim_specs['out']] + [('sim_id'),('x_on_cube')],
+                         sim_specs['in'] + [n[0] for n in sim_specs['out']] + [('sim_id'), ('x_on_cube')],
                          np.atleast_1d(inds_of_last_batch_from_gen), persis_info[i], persistent=True)
 
                 H['given_back'][inds_of_last_batch_from_gen] = True
diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index a818b7a53..4e62b8f68 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -194,8 +194,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
     # Initialize stuff for localopt children
     local_opters = []
-    parent_can_read_from_queue = Event()
-    comm_queue = Queue()
     sim_id_to_child_indices = {}
     child_id_to_run_id = {}
     run_order = {}
@@ -208,10 +206,9 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     else:
         raise NotImplementedError("Unknown local optimization method " "'{}'.".format(gen_specs['localopt_method']))
 
-
-    # Send our initial sample.W e don't need to check that n_s is large enough:
+    # Send our initial sample. We don't need to check that n_s is large enough:
     # the alloc_func only returns when the initial sample has function values.
-    send_k_sample_points_for_evaluation(gen_specs['initial_sample_size'],gen_specs,
+    send_k_sample_points_for_evaluation(gen_specs['initial_sample_size'], gen_specs,
                                         persis_info, n, c_flag, comm, local_H,
                                         sim_id_to_child_indices)
 
@@ -220,7 +217,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         tag, Work, calc_in = get_mgr_worker_msg(comm)
 
         if tag in [STOP_TAG, PERSIS_STOP]:
-            clean_up_and_stop(local_H, local_opters) 
+            clean_up_and_stop(local_H, local_opters)
             break
 
         n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
@@ -251,12 +248,12 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 local_H['started_run'][ind] = 1
 
                 # Initialize a local opt run
-                local_opter = LocalOptInterfacer(gen_specs, local_H[ind]['x_on_cube'], 
+                local_opter = LocalOptInterfacer(gen_specs, local_H[ind]['x_on_cube'],
                                                  local_H[ind]['f'], local_H[ind]['grad'] if 'grad' in fields_to_pass else None)
 
                 local_opters.append(local_opter)
 
-                x_new = local_opter.iterate(local_H[ind][fields_to_pass]) # Assuming the second point can't be ruled optimal 
+                x_new = local_opter.iterate(local_H[ind][fields_to_pass])  # Assuming the second point can't be ruled optimal
 
                 add_to_local_H(local_H, x_new, gen_specs, c_flag, local_flag=1, on_cube=True)
                 counter += 1
@@ -270,15 +267,14 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 else:
                     sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(local_opters)-1, )
 
-
         if counter == 0:
             send_k_sample_points_for_evaluation(1, gen_specs, persis_info, n, c_flag, comm, local_H,
-                                                 sim_id_to_child_indices)
-        else: 
+                                                sim_id_to_child_indices)
+        else:
             send_mgr_worker_msg(comm, local_H[-counter:][['x', 'x_on_cube', 'sim_id']])
 
-    comm_queue.close()
-    comm_queue.join_thread()
+    # comm_queue.close()
+    # comm_queue.join_thread()
 
     for local_opter in local_opters:
         if local_opter.is_running:
@@ -356,7 +352,7 @@ def iterate(self, data):
         if isinstance(x_new, ConvergedMsg):
             self.process.join()
             self.is_running = False
-        else: 
+        else:
             x_new = np.atleast_2d(x_new)
 
         return x_new
@@ -393,7 +389,7 @@ def nlopt_callback_fun(x, grad, comm_queue, child_can_read, parent_can_read, gen
                                                 'LN_COBYLA', 'LN_NELDERMEAD', 'LD_MMA']
         x_recv, f_recv = comm_queue.get()
 
-    assert np.array_equal(x,x_recv), "The point I gave is not the point I got back!"
+    assert np.array_equal(x, x_recv), "The point I gave is not the point I got back!"
 
     child_can_read.clear()
 
@@ -974,6 +970,7 @@ def send_k_sample_points_for_evaluation(k, gen_specs, persis_info, n, c_flag, co
 
     send_mgr_worker_msg(comm, local_H[-k:][['x', 'x_on_cube', 'sim_id']])
 
+
 def clean_up_and_stop(local_H, local_opters):
     # FIXME: This has to be a clean exit.
 
@@ -984,6 +981,7 @@ def clean_up_and_stop(local_H, local_opters):
         if p.is_running:
             p.destroy()
 
+
 def display_exception(e):
     print(e.__doc__)
     print(e.args)

From ce8d1c4977f54f1dbcc0aace4a7d1f36436423ca Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Mon, 9 Sep 2019 08:46:00 -0500
Subject: [PATCH 211/644] Removing some unused gen_specs

---
 .../regression_tests/test_6-hump_camel_persistent_aposmm.py  | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index 74076c4b1..7f0e7a20e 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -51,14 +51,11 @@
              'sample_points': np.round(minima, 1),
              'localopt_method': 'LD_MMA',
              'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
-             'xtol_rel': 1e-3,
+             'xtol_rel': 1e-6,
              'num_active_gens': 1,
              'local_min': True,
              'dist_to_bound_multiple': 0.5,
              'max_active_runs': 6,
-             'grtol': 1e-4,
-             'gatol': 1e-4,
-             'tol': 1e-5,
              'lb': np.array([-3, -2]),
              'ub': np.array([3, 2])}
 

From f4f56dcb60296e7a445cd03d6a10c0bde37c4e74 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Mon, 9 Sep 2019 08:46:54 -0500
Subject: [PATCH 212/644] Not returning to persistent_aposmm until initial
 sample is complete, and then returning after each evaluation

---
 .../alloc_funcs/persistent_aposmm_alloc.py    | 23 +++++++++----------
 1 file changed, 11 insertions(+), 12 deletions(-)

diff --git a/libensemble/alloc_funcs/persistent_aposmm_alloc.py b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
index a4bc95772..97a82548b 100644
--- a/libensemble/alloc_funcs/persistent_aposmm_alloc.py
+++ b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
@@ -20,21 +20,20 @@ def persistent_aposmm_alloc(W, H, sim_specs, gen_specs, alloc_specs, persis_info
     # If i is in persistent mode, and any of its calculated values have
     # returned, give them back to i. Otherwise, give nothing to i
     for i in avail_worker_ids(W, persistent=True):
+        if sum(H['returned']) < gen_specs['initial_sample_size']:
+            # Don't return if the initial sample is not complete   
+            continue
+
         gen_inds = (H['gen_worker'] == i)
         returned_but_not_given = np.logical_and(H['returned'][gen_inds], ~H['given_back'][gen_inds])
         if np.any(returned_but_not_given):
-            # If a point is a sample point, only return it if all other sample
-            # points requested at the same time are returned.
-            last_time_gen_gave_batch = np.unique(H['gen_time'][returned_but_not_given])
-            assert(len(last_time_gen_gave_batch)) == 1, "It shouldn't be possible for persistent aposmm to give two batches."
-            inds_of_last_batch_from_gen = H['sim_id'][gen_inds][H['gen_time'][gen_inds] == last_time_gen_gave_batch]
-
-            if np.all(H[inds_of_last_batch_from_gen]['returned']):
-                gen_work(Work, i,
-                         sim_specs['in'] + [n[0] for n in sim_specs['out']] + [('sim_id'), ('x_on_cube')],
-                         np.atleast_1d(inds_of_last_batch_from_gen), persis_info[i], persistent=True)
-
-                H['given_back'][inds_of_last_batch_from_gen] = True
+            inds_to_give = np.where(returned_but_not_given)[0]
+
+            gen_work(Work, i,
+                     sim_specs['in'] + [n[0] for n in sim_specs['out']] + [('sim_id'), ('x_on_cube')],
+                     np.atleast_1d(inds_to_give), persis_info[i], persistent=True)
+
+            H['given_back'][inds_to_give] = True
 
     task_avail = ~H['given']
     for i in avail_worker_ids(W, persistent=False):

From 3dfe4e943a47843b254369621a2ab9bfb9dc1ae4 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Mon, 9 Sep 2019 08:47:33 -0500
Subject: [PATCH 213/644] close() and join_thread() for queue items

---
 libensemble/gen_funcs/persistent_aposmm.py | 36 +++++++++++-----------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 4e62b8f68..63e762b51 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -217,7 +217,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         tag, Work, calc_in = get_mgr_worker_msg(comm)
 
         if tag in [STOP_TAG, PERSIS_STOP]:
-            clean_up_and_stop(local_H, local_opters)
+            clean_up_and_stop(local_H, local_opters, run_order)
             break
 
         n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
@@ -273,9 +273,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         else:
             send_mgr_worker_msg(comm, local_H[-counter:][['x', 'x_on_cube', 'sim_id']])
 
-    # comm_queue.close()
-    # comm_queue.join_thread()
-
     for local_opter in local_opters:
         if local_opter.is_running:
             raise RuntimeError("[Parent]: Atleast one child process is still active, even after"
@@ -285,7 +282,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
 
 class LocalOptInterfacer(object):
-    def __init__(self, gen_specs, x0, parent_can_read, f0, grad0=None):
+    def __init__(self, gen_specs, x0, f0, grad0=None):
         """
         :param x0: A numpy array of the initial guess solution. This guess
             should be scaled to a unit cube.
@@ -302,9 +299,9 @@ def __init__(self, gen_specs, x0, parent_can_read, f0, grad0=None):
         self.comm_queue = Queue()
         self.child_can_read = Event()
 
-        self.x0 = x0
-        self.f0 = f0
-        self.grad0 = grad0
+        self.x0 = x0.copy()
+        self.f0 = f0.copy()
+        self.grad0 = grad0.copy()
 
         # {{{ setting the local optimization method
 
@@ -351,27 +348,30 @@ def iterate(self, data):
         x_new = self.comm_queue.get()
         if isinstance(x_new, ConvergedMsg):
             self.process.join()
+            self.comm_queue.close()
+            self.comm_queue.join_thread()
             self.is_running = False
         else:
             x_new = np.atleast_2d(x_new)
 
         return x_new
 
-    def destroy(self):
-        x_new = None
-        while not isinstance(x_new, ConvergedMsg):
+    def destroy(self,previous_x):
+        while not isinstance(previous_x, ConvergedMsg):
             self.parent_can_read.clear()
             if self.grad0 is None:
-                self.comm_queue.put((0*np.ones_like(self.f0),))
+                self.comm_queue.put((previous_x, 0*np.ones_like(self.f0),))
             else:
-                self.comm_queue.put((0*np.ones_like(self.f0), np.zeros_like(self.grad0)))
+                self.comm_queue.put((previous_x,0*np.ones_like(self.f0), np.zeros_like(self.grad0)))
 
             self.child_can_read.set()
             self.parent_can_read.wait()
 
-            x_new = self.comm_queue.get()
-        assert isinstance(x_new, ConvergedMsg)
+            previous_x = self.comm_queue.get()
+        assert isinstance(previous_x, ConvergedMsg)
         self.process.join()
+        self.comm_queue.close()
+        self.comm_queue.join_thread()
         self.is_running = False
 
 
@@ -971,15 +971,15 @@ def send_k_sample_points_for_evaluation(k, gen_specs, persis_info, n, c_flag, co
     send_mgr_worker_msg(comm, local_H[-k:][['x', 'x_on_cube', 'sim_id']])
 
 
-def clean_up_and_stop(local_H, local_opters):
+def clean_up_and_stop(local_H, local_opters, run_order):
     # FIXME: This has to be a clean exit.
 
     print('[Parent]: The optimal points are:\n',
           local_H[np.where(local_H['local_min'])]['x'], flush=True)
 
-    for p in local_opters:
+    for i,p in enumerate(local_opters):
         if p.is_running:
-            p.destroy()
+            p.destroy(local_H['x_on_cube'][run_order[i][-1]])
 
 
 def display_exception(e):

From a98280ae12fc9ac93861f0b2ddf12bb99545eb80 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Mon, 9 Sep 2019 08:48:29 -0500
Subject: [PATCH 214/644] flake8

---
 libensemble/alloc_funcs/persistent_aposmm_alloc.py | 2 +-
 libensemble/gen_funcs/persistent_aposmm.py         | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/libensemble/alloc_funcs/persistent_aposmm_alloc.py b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
index 97a82548b..e92d531c1 100644
--- a/libensemble/alloc_funcs/persistent_aposmm_alloc.py
+++ b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
@@ -21,7 +21,7 @@ def persistent_aposmm_alloc(W, H, sim_specs, gen_specs, alloc_specs, persis_info
     # returned, give them back to i. Otherwise, give nothing to i
     for i in avail_worker_ids(W, persistent=True):
         if sum(H['returned']) < gen_specs['initial_sample_size']:
-            # Don't return if the initial sample is not complete   
+            # Don't return if the initial sample is not complete
             continue
 
         gen_inds = (H['gen_worker'] == i)
diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 63e762b51..c7fa02356 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -356,13 +356,13 @@ def iterate(self, data):
 
         return x_new
 
-    def destroy(self,previous_x):
+    def destroy(self, previous_x):
         while not isinstance(previous_x, ConvergedMsg):
             self.parent_can_read.clear()
             if self.grad0 is None:
                 self.comm_queue.put((previous_x, 0*np.ones_like(self.f0),))
             else:
-                self.comm_queue.put((previous_x,0*np.ones_like(self.f0), np.zeros_like(self.grad0)))
+                self.comm_queue.put((previous_x, 0*np.ones_like(self.f0), np.zeros_like(self.grad0)))
 
             self.child_can_read.set()
             self.parent_can_read.wait()
@@ -977,7 +977,7 @@ def clean_up_and_stop(local_H, local_opters, run_order):
     print('[Parent]: The optimal points are:\n',
           local_H[np.where(local_H['local_min'])]['x'], flush=True)
 
-    for i,p in enumerate(local_opters):
+    for i, p in enumerate(local_opters):
         if p.is_running:
             p.destroy(local_H['x_on_cube'][run_order[i][-1]])
 

From 9d36229308d8dd69c965e865fa28ef1a5228f4f5 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Mon, 9 Sep 2019 11:19:43 -0500
Subject: [PATCH 215/644] Now removing any trace of old runs when they are
 done.

---
 libensemble/gen_funcs/persistent_aposmm.py | 26 ++++++++++++----------
 1 file changed, 14 insertions(+), 12 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index c7fa02356..95fcaa532 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -193,7 +193,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     n, n_s, c_flag, rk_const, ld, mu, nu, comm, local_H = initialize_APOSMM(H, gen_specs, libE_info)
 
     # Initialize stuff for localopt children
-    local_opters = []
+    local_opters = {}
     sim_id_to_child_indices = {}
     child_id_to_run_id = {}
     run_order = {}
@@ -231,6 +231,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     if isinstance(x_new, ConvergedMsg):
                         x_opt = x_new.x
                         update_history_optimal(x_opt, local_H, run_order[child_id_to_run_id[child_idx]])
+                        local_opters.pop(child_id_to_run_id[child_idx])
                     else:
                         add_to_local_H(local_H, x_new, gen_specs, c_flag, local_flag=1, on_cube=True)
                         counter += 1
@@ -244,14 +245,14 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         starting_inds = decide_where_to_start_localopt(local_H, n, n_s, rk_const, ld, mu, nu)
 
         for ind in starting_inds:
-            if len([p for p in local_opters if p.is_running]) < gen_specs.get('max_active_runs', np.inf):
+            if len([p for p in local_opters.values() if p.is_running]) < gen_specs.get('max_active_runs', np.inf):
                 local_H['started_run'][ind] = 1
 
                 # Initialize a local opt run
                 local_opter = LocalOptInterfacer(gen_specs, local_H[ind]['x_on_cube'],
                                                  local_H[ind]['f'], local_H[ind]['grad'] if 'grad' in fields_to_pass else None)
 
-                local_opters.append(local_opter)
+                local_opters[total_runs] = local_opter
 
                 x_new = local_opter.iterate(local_H[ind][fields_to_pass])  # Assuming the second point can't be ruled optimal
 
@@ -259,13 +260,14 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 counter += 1
 
                 run_order[total_runs] = [ind, local_H[-1]['sim_id']]
-                child_id_to_run_id[len(local_opters)-1] = total_runs
-                total_runs += 1
+                child_id_to_run_id[total_runs] = total_runs
 
                 if local_H[-1]['sim_id'] in sim_id_to_child_indices:
-                    sim_id_to_child_indices[local_H[-1]['sim_id']] += (len(local_opters)-1, )
+                    sim_id_to_child_indices[local_H[-1]['sim_id']] += (total_runs, )
                 else:
-                    sim_id_to_child_indices[local_H[-1]['sim_id']] = (len(local_opters)-1, )
+                    sim_id_to_child_indices[local_H[-1]['sim_id']] = (total_runs, )
+
+                total_runs += 1
 
         if counter == 0:
             send_k_sample_points_for_evaluation(1, gen_specs, persis_info, n, c_flag, comm, local_H,
@@ -273,10 +275,10 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         else:
             send_mgr_worker_msg(comm, local_H[-counter:][['x', 'x_on_cube', 'sim_id']])
 
-    for local_opter in local_opters:
-        if local_opter.is_running:
-            raise RuntimeError("[Parent]: Atleast one child process is still active, even after"
-                               " killing all the children.")
+    # for local_opter in local_opters:
+    #     if local_opter.is_running:
+    #         raise RuntimeError("[Parent]: Atleast one child process is still active, even after"
+    #                            " killing all the children.")
 
     return local_H, persis_info, tag
 
@@ -977,7 +979,7 @@ def clean_up_and_stop(local_H, local_opters, run_order):
     print('[Parent]: The optimal points are:\n',
           local_H[np.where(local_H['local_min'])]['x'], flush=True)
 
-    for i, p in enumerate(local_opters):
+    for i, p in local_opters.items():
         if p.is_running:
             p.destroy(local_H['x_on_cube'][run_order[i][-1]])
 

From 01f454c96c924780854a5acaa5dd7a53cce9e4aa Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 9 Sep 2019 11:35:38 -0500
Subject: [PATCH 216/644] removes ulimit change

---
 .travis.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index 4cc24d54c..20b85977f 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -90,7 +90,6 @@ before_script:
   - echo "export BALSAM_DB_PATH=~/test-balsam" > setbalsampath.sh
   - source setbalsampath.sh
   # Allow 10000 files to be open at once (critical for persistent_aposmm)
-  - ulimit -Sn 10000
   # Set conda compilers to use new SDK instead of Travis default.
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
         echo "export CONDA_BUILD_SYSROOT=/Users/travis/build/Libensemble/sdk/MacOSX10.13.sdk" > setenv.sh;

From fcbe6e27681fdda51497cd291caa7fed16b155d6 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Mon, 9 Sep 2019 14:12:02 -0500
Subject: [PATCH 217/644] removing child_id_to_run_id

---
 libensemble/gen_funcs/persistent_aposmm.py | 8 +++-----
 1 file changed, 3 insertions(+), 5 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 95fcaa532..d25d22b88 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -195,7 +195,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     # Initialize stuff for localopt children
     local_opters = {}
     sim_id_to_child_indices = {}
-    child_id_to_run_id = {}
     run_order = {}
     total_runs = 0
     if gen_specs['localopt_method'] in ['LD_MMA', 'blmvm']:
@@ -230,13 +229,13 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     x_new = local_opters[child_idx].iterate(row[fields_to_pass])
                     if isinstance(x_new, ConvergedMsg):
                         x_opt = x_new.x
-                        update_history_optimal(x_opt, local_H, run_order[child_id_to_run_id[child_idx]])
-                        local_opters.pop(child_id_to_run_id[child_idx])
+                        update_history_optimal(x_opt, local_H, run_order[child_idx])
+                        local_opters.pop(child_idx)
                     else:
                         add_to_local_H(local_H, x_new, gen_specs, c_flag, local_flag=1, on_cube=True)
                         counter += 1
 
-                        run_order[child_id_to_run_id[child_idx]].append(local_H[-1]['sim_id'])
+                        run_order[child_idx].append(local_H[-1]['sim_id'])
                         if local_H[-1]['sim_id'] in sim_id_to_child_indices:
                             sim_id_to_child_indices[local_H[-1]['sim_id']] += (child_idx, )
                         else:
@@ -260,7 +259,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 counter += 1
 
                 run_order[total_runs] = [ind, local_H[-1]['sim_id']]
-                child_id_to_run_id[total_runs] = total_runs
 
                 if local_H[-1]['sim_id'] in sim_id_to_child_indices:
                     sim_id_to_child_indices[local_H[-1]['sim_id']] += (total_runs, )

From e32726f1b56be7d57ee9b553b8d96943728dcbaa Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 10 Sep 2019 06:32:35 -0500
Subject: [PATCH 218/644] Communicating gen_specs['out'] to/from manager.

---
 libensemble/gen_funcs/persistent_aposmm.py                    | 4 ++--
 .../regression_tests/test_6-hump_camel_persistent_aposmm.py   | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index d25d22b88..9c4cd11a3 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -271,7 +271,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
             send_k_sample_points_for_evaluation(1, gen_specs, persis_info, n, c_flag, comm, local_H,
                                                 sim_id_to_child_indices)
         else:
-            send_mgr_worker_msg(comm, local_H[-counter:][['x', 'x_on_cube', 'sim_id']])
+            send_mgr_worker_msg(comm, local_H[-counter:][[i[0] for i in gen_specs['out']]])
 
     # for local_opter in local_opters:
     #     if local_opter.is_running:
@@ -968,7 +968,7 @@ def send_k_sample_points_for_evaluation(k, gen_specs, persis_info, n, c_flag, co
     assert local_H['sim_id'][-k] not in sim_id_to_child_indices
     # sim_id_to_child_indices[local_H['sim_id'][-k:]] = None
 
-    send_mgr_worker_msg(comm, local_H[-k:][['x', 'x_on_cube', 'sim_id']])
+    send_mgr_worker_msg(comm, local_H[-k:][[i[0] for i in gen_specs['out']]])
 
 
 def clean_up_and_stop(local_H, local_opters, run_order):
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index 7f0e7a20e..a20bacdf5 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -41,7 +41,7 @@
              'out': [('f', float), ('grad', float, n)]}
 
 gen_out = [('x', float, n), ('x_on_cube', float, n), ('sim_id', int),
-           ('local_min', bool)]
+           ('local_min', bool), ('local_pt',bool)]
 
 gen_specs = {'gen_f': gen_f,
              'in': [],

From c20771232d5a3400959addb5929ce828991f83fa Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 10 Sep 2019 07:09:15 -0500
Subject: [PATCH 219/644] Communicating gen_specs['out'] to/from manager.

---
 libensemble/alloc_funcs/persistent_aposmm_alloc.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/libensemble/alloc_funcs/persistent_aposmm_alloc.py b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
index e92d531c1..1e10ff619 100644
--- a/libensemble/alloc_funcs/persistent_aposmm_alloc.py
+++ b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
@@ -29,8 +29,7 @@ def persistent_aposmm_alloc(W, H, sim_specs, gen_specs, alloc_specs, persis_info
         if np.any(returned_but_not_given):
             inds_to_give = np.where(returned_but_not_given)[0]
 
-            gen_work(Work, i,
-                     sim_specs['in'] + [n[0] for n in sim_specs['out']] + [('sim_id'), ('x_on_cube')],
+            gen_work(Work, i, [n[0] for n in sim_specs['out']] + [n[0] for n in gen_specs['out']],
                      np.atleast_1d(inds_to_give), persis_info[i], persistent=True)
 
             H['given_back'][inds_to_give] = True

From 0e147897ecc2b49b4bce5b7ebc58edc6d257d499 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 10 Sep 2019 07:10:03 -0500
Subject: [PATCH 220/644] Using gen_specs['sample_points'] if available.

---
 libensemble/gen_funcs/persistent_aposmm.py | 50 ++++++++++++++--------
 1 file changed, 32 insertions(+), 18 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 9c4cd11a3..885afe600 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -207,9 +207,10 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
     # Send our initial sample. We don't need to check that n_s is large enough:
     # the alloc_func only returns when the initial sample has function values.
-    send_k_sample_points_for_evaluation(gen_specs['initial_sample_size'], gen_specs,
-                                        persis_info, n, c_flag, comm, local_H,
-                                        sim_id_to_child_indices)
+    persis_info = add_k_sample_points_to_local_H(gen_specs['initial_sample_size'], gen_specs,
+                                                 persis_info, n, c_flag, comm, local_H,
+                                                  sim_id_to_child_indices)
+    send_mgr_worker_msg(comm, local_H[:gen_specs['initial_sample_size']][[i[0] for i in gen_specs['out']]])
 
     tag = None
     while 1:
@@ -221,7 +222,8 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
         n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
 
-        counter = 0
+        new_opt_inds_to_send_mgr = []
+        new_inds_to_send_mgr = [] 
         for row in calc_in:
             if sim_id_to_child_indices.get(row['sim_id']):
                 # Point came from a child local opt run
@@ -229,11 +231,12 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                     x_new = local_opters[child_idx].iterate(row[fields_to_pass])
                     if isinstance(x_new, ConvergedMsg):
                         x_opt = x_new.x
-                        update_history_optimal(x_opt, local_H, run_order[child_idx])
+                        opt_ind = update_history_optimal(x_opt, local_H, run_order[child_idx])
+                        new_opt_inds_to_send_mgr.append(opt_ind)
                         local_opters.pop(child_idx)
                     else:
                         add_to_local_H(local_H, x_new, gen_specs, c_flag, local_flag=1, on_cube=True)
-                        counter += 1
+                        new_inds_to_send_mgr.append(len(local_H)-1)
 
                         run_order[child_idx].append(local_H[-1]['sim_id'])
                         if local_H[-1]['sim_id'] in sim_id_to_child_indices:
@@ -256,7 +259,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 x_new = local_opter.iterate(local_H[ind][fields_to_pass])  # Assuming the second point can't be ruled optimal
 
                 add_to_local_H(local_H, x_new, gen_specs, c_flag, local_flag=1, on_cube=True)
-                counter += 1
+                new_inds_to_send_mgr.append(len(local_H)-1)
 
                 run_order[total_runs] = [ind, local_H[-1]['sim_id']]
 
@@ -267,11 +270,12 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                 total_runs += 1
 
-        if counter == 0:
-            send_k_sample_points_for_evaluation(1, gen_specs, persis_info, n, c_flag, comm, local_H,
-                                                sim_id_to_child_indices)
-        else:
-            send_mgr_worker_msg(comm, local_H[-counter:][[i[0] for i in gen_specs['out']]])
+        if len(new_inds_to_send_mgr) == 0:
+            persis_info = add_k_sample_points_to_local_H(1, gen_specs, persis_info, n,
+                                                         c_flag, comm, local_H, sim_id_to_child_indices)
+            new_inds_to_send_mgr.append(len(local_H)-1)
+
+        send_mgr_worker_msg(comm, local_H[new_inds_to_send_mgr + new_opt_inds_to_send_mgr][[i[0] for i in gen_specs['out']]])
 
     # for local_opter in local_opters:
     #     if local_opter.is_running:
@@ -769,6 +773,8 @@ def update_history_optimal(x_opt, H, run_inds):
     H['local_min'][opt_ind] = 1
     H['num_active_runs'][run_inds] -= 1
 
+    return opt_ind
+
 
 def decide_where_to_start_localopt(H, n, n_s, rk_const, ld=0, mu=0, nu=0):
     """
@@ -962,13 +968,21 @@ def initialize_APOSMM(H, gen_specs, libE_info):
     return n, n_s, c_flag, rk_c, ld, mu, nu, comm, local_H
 
 
-def send_k_sample_points_for_evaluation(k, gen_specs, persis_info, n, c_flag, comm, local_H, sim_id_to_child_indices):
-    sampled_points = persis_info['rand_stream'].uniform(0, 1, (k, n))
-    add_to_local_H(local_H, sampled_points, gen_specs, c_flag, on_cube=True)
-    assert local_H['sim_id'][-k] not in sim_id_to_child_indices
-    # sim_id_to_child_indices[local_H['sim_id'][-k:]] = None
+def add_k_sample_points_to_local_H(k, gen_specs, persis_info, n, c_flag, comm, local_H, sim_id_to_child_indices):
+
+    if 'sample_points' in gen_specs:
+        v = np.sum(~local_H['local_pt'])  # Number of sample points so far
+        sampled_points = gen_specs['sample_points'][v:v+k]
+        on_cube = False  # Assume points are on original domain, not unit cube
+        if len(sampled_points):
+            add_to_local_H(local_H, sampled_points, gen_specs, c_flag, on_cube=on_cube)
+        k = k-len(sampled_points)
+
+    if k > 0:
+        sampled_points = persis_info['rand_stream'].uniform(0, 1, (k, n))
+        add_to_local_H(local_H, sampled_points, gen_specs, c_flag, on_cube=True)
 
-    send_mgr_worker_msg(comm, local_H[-k:][[i[0] for i in gen_specs['out']]])
+    return persis_info
 
 
 def clean_up_and_stop(local_H, local_opters, run_order):

From 3e20a8353de0db3547da7f5399a72548c25506e3 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 10 Sep 2019 07:11:01 -0500
Subject: [PATCH 221/644] Testing that all minima are found

---
 .../test_6-hump_camel_persistent_aposmm.py               | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index a20bacdf5..985e49095 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -72,4 +72,13 @@
 if is_master:
     print('[Manager]:', H[np.where(H['local_min'])]['x'])
     print('[Manager]: Time taken =', time() - start_time, flush=True)
+
+    tol = 1e-5
+    for m in minima:
+        # The minima are known on this test problem.
+        # We use their values to test APOSMM has identified all minima
+        print(np.min(np.sum((H[H['local_min']]['x'] - m)**2, 1)),flush=True)
+        if np.min(np.sum((H[H['local_min']]['x'] - m)**2, 1)) > tol:
+            libE_abort()
+
     save_libE_output(H, persis_info, __file__, nworkers)

From c705a8569243bca889564e3316ddbc41da4573b7 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 10 Sep 2019 07:56:03 -0500
Subject: [PATCH 222/644] Using persis_info to speed up alloc_func

---
 .../alloc_funcs/persistent_aposmm_alloc.py    | 44 ++++++++++---------
 1 file changed, 23 insertions(+), 21 deletions(-)

diff --git a/libensemble/alloc_funcs/persistent_aposmm_alloc.py b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
index 1e10ff619..a623b5325 100644
--- a/libensemble/alloc_funcs/persistent_aposmm_alloc.py
+++ b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
@@ -6,45 +6,47 @@
 def persistent_aposmm_alloc(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     """
     This allocation function will give simulation work if possible, but
-    otherwise start up to 1 persistent generator.  If all points requested by
+    otherwise start a persistent APOSMM generator.  If all points requested by
     the persistent generator have been returned from the simulation evaluation,
     then this information is given back to the persistent generator.
 
+    This function assumes that one persistent APOSMM will be started and never
+    stopped (until some exit_criterion is satisfied).
+
     :See:
-        ``/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py``
+        ``/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py``
     """
 
     Work = {}
-    gen_count = count_persis_gens(W)
+    if 'next_to_give' not in persis_info:
+        persis_info['next_to_give'] = 0
+
 
-    # If i is in persistent mode, and any of its calculated values have
-    # returned, give them back to i. Otherwise, give nothing to i
+    # If any persistent worker's calculated values have returned, give them back.
     for i in avail_worker_ids(W, persistent=True):
-        if sum(H['returned']) < gen_specs['initial_sample_size']:
+        if persis_info.get('sample_done') or sum(H['returned']) >= gen_specs['initial_sample_size']:
             # Don't return if the initial sample is not complete
-            continue
+            persis_info['sample_done'] = True
 
-        gen_inds = (H['gen_worker'] == i)
-        returned_but_not_given = np.logical_and(H['returned'][gen_inds], ~H['given_back'][gen_inds])
-        if np.any(returned_but_not_given):
-            inds_to_give = np.where(returned_but_not_given)[0]
+            returned_but_not_given = np.logical_and(H['returned'], ~H['given_back'])
+            if np.any(returned_but_not_given):
+                inds_to_give = np.where(returned_but_not_given)[0]
 
-            gen_work(Work, i, [n[0] for n in sim_specs['out']] + [n[0] for n in gen_specs['out']],
-                     np.atleast_1d(inds_to_give), persis_info[i], persistent=True)
+                gen_work(Work, i, [n[0] for n in sim_specs['out']] + [n[0] for n in gen_specs['out']],
+                         np.atleast_1d(inds_to_give), persis_info[i], persistent=True)
 
-            H['given_back'][inds_to_give] = True
+                H['given_back'][inds_to_give] = True
 
-    task_avail = ~H['given']
     for i in avail_worker_ids(W, persistent=False):
-        if np.any(task_avail):
+        if persis_info['next_to_give'] < len(H):
             # perform sim evaluations (if they exist in History).
-            sim_ids_to_send = np.nonzero(task_avail)[0][0]  # oldest point
-            sim_work(Work, i, sim_specs['in'], np.atleast_1d(sim_ids_to_send), persis_info[i])
-            task_avail[sim_ids_to_send] = False
+            sim_work(Work, i, sim_specs['in'], np.atleast_1d(persis_info['next_to_give']), persis_info[i])
+            persis_info['next_to_give'] += 1
 
-        elif gen_count == 0:
+        elif persis_info.get('gen_started') is None:
             # Finally, call a persistent generator as there is nothing else to do.
-            gen_count += 1
+            persis_info['gen_started'] = True
+
             gen_work(Work, i, gen_specs['in'], [], persis_info[i],
                      persistent=True)
 

From 0bbf8d9d3fe6d6ed4adc1a86e993103feb858f10 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 10 Sep 2019 08:09:53 -0500
Subject: [PATCH 223/644] flake8

---
 libensemble/alloc_funcs/persistent_aposmm_alloc.py         | 3 +--
 libensemble/gen_funcs/persistent_aposmm.py                 | 4 ++--
 .../test_6-hump_camel_persistent_aposmm.py                 | 7 +++----
 3 files changed, 6 insertions(+), 8 deletions(-)

diff --git a/libensemble/alloc_funcs/persistent_aposmm_alloc.py b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
index a623b5325..3a3035e2d 100644
--- a/libensemble/alloc_funcs/persistent_aposmm_alloc.py
+++ b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
@@ -1,6 +1,6 @@
 import numpy as np
 
-from libensemble.alloc_funcs.support import avail_worker_ids, sim_work, gen_work, count_persis_gens
+from libensemble.alloc_funcs.support import avail_worker_ids, sim_work, gen_work
 
 
 def persistent_aposmm_alloc(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
@@ -21,7 +21,6 @@ def persistent_aposmm_alloc(W, H, sim_specs, gen_specs, alloc_specs, persis_info
     if 'next_to_give' not in persis_info:
         persis_info['next_to_give'] = 0
 
-
     # If any persistent worker's calculated values have returned, give them back.
     for i in avail_worker_ids(W, persistent=True):
         if persis_info.get('sample_done') or sum(H['returned']) >= gen_specs['initial_sample_size']:
diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 885afe600..60a0925bc 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -209,7 +209,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     # the alloc_func only returns when the initial sample has function values.
     persis_info = add_k_sample_points_to_local_H(gen_specs['initial_sample_size'], gen_specs,
                                                  persis_info, n, c_flag, comm, local_H,
-                                                  sim_id_to_child_indices)
+                                                 sim_id_to_child_indices)
     send_mgr_worker_msg(comm, local_H[:gen_specs['initial_sample_size']][[i[0] for i in gen_specs['out']]])
 
     tag = None
@@ -223,7 +223,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
 
         new_opt_inds_to_send_mgr = []
-        new_inds_to_send_mgr = [] 
+        new_inds_to_send_mgr = []
         for row in calc_in:
             if sim_id_to_child_indices.get(row['sim_id']):
                 # Point came from a child local opt run
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
index 985e49095..ebfd920d8 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
@@ -41,7 +41,7 @@
              'out': [('f', float), ('grad', float, n)]}
 
 gen_out = [('x', float, n), ('x_on_cube', float, n), ('sim_id', int),
-           ('local_min', bool), ('local_pt',bool)]
+           ('local_min', bool), ('local_pt', bool)]
 
 gen_specs = {'gen_f': gen_f,
              'in': [],
@@ -77,8 +77,7 @@
     for m in minima:
         # The minima are known on this test problem.
         # We use their values to test APOSMM has identified all minima
-        print(np.min(np.sum((H[H['local_min']]['x'] - m)**2, 1)),flush=True)
-        if np.min(np.sum((H[H['local_min']]['x'] - m)**2, 1)) > tol:
-            libE_abort()
+        print(np.min(np.sum((H[H['local_min']]['x'] - m)**2, 1)), flush=True)
+        assert np.min(np.sum((H[H['local_min']]['x'] - m)**2, 1)) < tol
 
     save_libE_output(H, persis_info, __file__, nworkers)

From 7be87e1c633763d3a3a7626efff01945fe16e4fe Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 10 Sep 2019 10:03:16 -0500
Subject: [PATCH 224/644] use HOME env var instead of ~ or expanduser

---
 conda/configure-balsam-test.sh | 6 +++---
 conda/test_balsam_hworld.py    | 3 ++-
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/conda/configure-balsam-test.sh b/conda/configure-balsam-test.sh
index a284fd92e..56377aa5f 100755
--- a/conda/configure-balsam-test.sh
+++ b/conda/configure-balsam-test.sh
@@ -19,11 +19,11 @@ export THIS_DIR=$PWD
 export SCRIPT_BASENAME=script_test_balsam_hworld
 
 # Set proper permissions, initialize Balsam DB, activate DB
-export BALSAM_DB_PATH='~/test-balsam'
+export BALSAM_DB_PATH=$HOME/test-balsam
 sudo chown -R postgres:postgres /var/run/postgresql
 sudo chmod a+w /var/run/postgresql
-balsam init ~/test-balsam
-sudo chmod -R 700 ~/test-balsam/balsamdb
+balsam init $HOME/test-balsam
+sudo chmod -R 700 $HOME/test-balsam/balsamdb
 source balsamactivate test-balsam
 
 # Refresh DB
diff --git a/conda/test_balsam_hworld.py b/conda/test_balsam_hworld.py
index 900301bd8..94ec92d50 100644
--- a/conda/test_balsam_hworld.py
+++ b/conda/test_balsam_hworld.py
@@ -95,8 +95,9 @@ def move_job_coverage(jobdir):
     # For Balsam-specific Coverage config file, to not evaluate Balsam data dir
     libepath = os.path.dirname(libensemble.__file__)
     os.environ['LIBE_PATH'] = libepath
+    home = os.environ['HOME']
 
-    basedb = os.path.expanduser('~/test-balsam/data/libe_test-balsam')
+    basedb = home + '/test-balsam/data/libe_test-balsam'
 
     modify_Balsam_worker()
     run_Balsam_job()

From a592345bb230cceb70877999066027a1ed5f7844 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 10 Sep 2019 14:57:38 -0500
Subject: [PATCH 225/644] spring cleaning

---
 conda/test_balsam_hworld.py                   | 22 ++++++++-----------
 .../script_test_balsam_hworld.py              |  8 +------
 2 files changed, 10 insertions(+), 20 deletions(-)

diff --git a/conda/test_balsam_hworld.py b/conda/test_balsam_hworld.py
index 94ec92d50..844847ef6 100644
--- a/conda/test_balsam_hworld.py
+++ b/conda/test_balsam_hworld.py
@@ -1,15 +1,15 @@
 import subprocess
 import os
 import time
-import sys
 import libensemble
 from libensemble.tests.regression_tests.common import modify_Balsam_worker
 
 # TESTSUITE_COMMS: local
 # TESTSUITE_NPROCS: 3
 
-# This test is NOT submitted as a job to Balsam. Instead, script_test_balsam_hworld.py
-#   This test executes that job through the 'runstr' line in run_Balsam_job()
+# This test is NOT submitted as a job to Balsam. script_test_balsam_hworld.py is
+#   the executable submitted to Balsam as a job. This test executes that job
+#   through the 'runstr' line in run_Balsam_job()
 
 
 def run_Balsam_job():
@@ -27,8 +27,7 @@ def wait_for_job_dir(basedb):
 
     print('Waiting for Job Directory'.format(sleeptime))
     while len(os.listdir(basedb)) == 0 and sleeptime < 15:
-        print('{}'.format(sleeptime), end=" ")
-        sys.stdout.flush()
+        print('{}'.format(sleeptime), end=" ", flush=True)
         time.sleep(1)
         sleeptime += 1
 
@@ -44,8 +43,7 @@ def wait_for_job_output(jobdir):
     print('Checking for Balsam output file: {}'.format(output))
 
     while not os.path.isfile(output) and sleeptime < 30:
-        print('{}'.format(sleeptime), end=" ")
-        sys.stdout.flush()
+        print('{}'.format(sleeptime), end=" ", flush=True)
         time.sleep(2)
         sleeptime += 2
 
@@ -66,10 +64,9 @@ def print_job_output(outscript):
             lastposition = f.tell()
 
         if len(new) > 0:
-            print(new)
+            print(new, flush=True)
         else:
-            print('{}'.format(sleeptime), end=" ")
-        sys.stdout.flush()
+            print('{}'.format(sleeptime), end=" ", flush=True)
 
         if any(new.endswith(line) for line in lastlines):
             break
@@ -92,12 +89,11 @@ def move_job_coverage(jobdir):
 
 if __name__ == '__main__':
 
-    # For Balsam-specific Coverage config file, to not evaluate Balsam data dir
+    # Used by Balsam Coverage config file. Dont evaluate Balsam data dir
     libepath = os.path.dirname(libensemble.__file__)
     os.environ['LIBE_PATH'] = libepath
-    home = os.environ['HOME']
 
-    basedb = home + '/test-balsam/data/libe_test-balsam'
+    basedb = os.environ['HOME'] + '/test-balsam/data/libe_test-balsam'
 
     modify_Balsam_worker()
     run_Balsam_job()
diff --git a/libensemble/tests/regression_tests/script_test_balsam_hworld.py b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
index fd9430229..e86ff3b82 100644
--- a/libensemble/tests/regression_tests/script_test_balsam_hworld.py
+++ b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
@@ -31,12 +31,6 @@ def build_simfunc():
 is_master = MPI.COMM_WORLD.Get_rank() == 0
 
 cores_per_job = 1
-logical_cores = multiprocessing.cpu_count()
-cores_all_jobs = nworkers*cores_per_job
-
-if is_master:
-    print('\nCores req: {} Cores avail: {}\n'.format(cores_all_jobs,
-                                                     logical_cores))
 
 sim_app = './my_simjob.x'
 if not os.path.isfile(sim_app):
@@ -63,7 +57,7 @@ def build_simfunc():
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
-exit_criteria = {'elapsed_wallclock_time': 30}
+exit_criteria = {'elapsed_wallclock_time': 15}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria,

From c9584caa19198ca75b27714b1790db09a42c347c Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 10 Sep 2019 15:32:44 -0500
Subject: [PATCH 226/644] Removing comments

---
 libensemble/gen_funcs/support.py | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/libensemble/gen_funcs/support.py b/libensemble/gen_funcs/support.py
index f7e14b69c..759eeeb49 100644
--- a/libensemble/gen_funcs/support.py
+++ b/libensemble/gen_funcs/support.py
@@ -17,9 +17,6 @@ def send_mgr_worker_msg(comm, O):
          'calc_status': UNSET_TAG,
          'calc_type': EVAL_GEN_TAG
          }
-    # if O['sim_id'] > 200 or O['sim_id'] < 0:
-    #     import sys
-    #     sys.exit('Bad send')
 
     comm.send(EVAL_GEN_TAG, D)
     time.sleep(0.01)  # May prevent queue corruption. Investigate
@@ -33,5 +30,5 @@ def get_mgr_worker_msg(comm, status=None):
         comm.push_back(tag, Work)
         return tag, None, None
     _, calc_in = comm.recv()
-    # print("Next to receive:", calc_in['sim_id'], flush=True)
+ 
     return tag, Work, calc_in

From 8591fa1e151b6a00e5888dce6b93f5d6ede87ec9 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 10 Sep 2019 15:33:20 -0500
Subject: [PATCH 227/644] Update .travis.yml

---
 .travis.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index 20b85977f..b1cee2631 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -89,7 +89,6 @@ before_script:
   - flake8 libensemble
   - echo "export BALSAM_DB_PATH=~/test-balsam" > setbalsampath.sh
   - source setbalsampath.sh
-  # Allow 10000 files to be open at once (critical for persistent_aposmm)
   # Set conda compilers to use new SDK instead of Travis default.
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
         echo "export CONDA_BUILD_SYSROOT=/Users/travis/build/Libensemble/sdk/MacOSX10.13.sdk" > setenv.sh;

From ffae961894ebafac88912cc3eb2bfbdd419b9332 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 10 Sep 2019 15:33:59 -0500
Subject: [PATCH 228/644] Update support.py

---
 libensemble/gen_funcs/support.py | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/libensemble/gen_funcs/support.py b/libensemble/gen_funcs/support.py
index 759eeeb49..32b05218c 100644
--- a/libensemble/gen_funcs/support.py
+++ b/libensemble/gen_funcs/support.py
@@ -1,5 +1,4 @@
 from libensemble.message_numbers import STOP_TAG, PERSIS_STOP, UNSET_TAG, EVAL_GEN_TAG
-import time
 
 
 def sendrecv_mgr_worker_msg(comm, O, status=None):
@@ -19,7 +18,6 @@ def send_mgr_worker_msg(comm, O):
          }
 
     comm.send(EVAL_GEN_TAG, D)
-    time.sleep(0.01)  # May prevent queue corruption. Investigate
 
 
 def get_mgr_worker_msg(comm, status=None):
@@ -30,5 +28,4 @@ def get_mgr_worker_msg(comm, status=None):
         comm.push_back(tag, Work)
         return tag, None, None
     _, calc_in = comm.recv()
- 
     return tag, Work, calc_in

From 45a8d9b773c4e27b64c19c19dc3c997fe8d0371e Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 10 Sep 2019 15:34:21 -0500
Subject: [PATCH 229/644] Update support.py

---
 libensemble/gen_funcs/support.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/libensemble/gen_funcs/support.py b/libensemble/gen_funcs/support.py
index 32b05218c..e5084828d 100644
--- a/libensemble/gen_funcs/support.py
+++ b/libensemble/gen_funcs/support.py
@@ -16,7 +16,6 @@ def send_mgr_worker_msg(comm, O):
          'calc_status': UNSET_TAG,
          'calc_type': EVAL_GEN_TAG
          }
-
     comm.send(EVAL_GEN_TAG, D)
 
 

From bb8dbef1242b06ff5578f22d686ef10445fb5e20 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 10 Sep 2019 15:35:15 -0500
Subject: [PATCH 230/644] Update libE_manager.py

---
 libensemble/libE_manager.py | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/libensemble/libE_manager.py b/libensemble/libE_manager.py
index 3a08afcbe..0ff9bdba8 100644
--- a/libensemble/libE_manager.py
+++ b/libensemble/libE_manager.py
@@ -294,11 +294,6 @@ def _update_state_on_worker_msg(self, persis_info, D_recv, w):
             if calc_type == EVAL_SIM_TAG:
                 self.hist.update_history_f(D_recv)
             if calc_type == EVAL_GEN_TAG:
-                # print('Outside_recieve:', D_recv['calc_out']['sim_id'], flush=True)
-                # if D_recv['calc_out']['sim_id'] != self.hist.index:
-                #     import ipdb; ipdb.set_trace()
-                #     print("HA", D_recv['calc_out']['sim_id'], self.hist.index)
-
                 self.hist.update_history_x_in(w, D_recv['calc_out'])
                 assert len(D_recv['calc_out']) or np.any(self.W['active']), \
                     "Gen must return work when is is the only thing active."

From 965fa05ce190a8820972899db7d3c11ce6c950ba Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 10 Sep 2019 16:41:48 -0500
Subject: [PATCH 231/644] adjusting prints

---
 conda/test_balsam_hworld.py                        | 14 ++++++++------
 .../regression_tests/script_test_balsam_hworld.py  |  3 +--
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/conda/test_balsam_hworld.py b/conda/test_balsam_hworld.py
index 844847ef6..c5cd6fb7c 100644
--- a/conda/test_balsam_hworld.py
+++ b/conda/test_balsam_hworld.py
@@ -27,7 +27,7 @@ def wait_for_job_dir(basedb):
 
     print('Waiting for Job Directory'.format(sleeptime))
     while len(os.listdir(basedb)) == 0 and sleeptime < 15:
-        print('{}'.format(sleeptime), end=" ", flush=True)
+        print(sleeptime, end=" ", flush=True)
         time.sleep(1)
         sleeptime += 1
 
@@ -43,9 +43,9 @@ def wait_for_job_output(jobdir):
     print('Checking for Balsam output file: {}'.format(output))
 
     while not os.path.isfile(output) and sleeptime < 30:
-        print('{}'.format(sleeptime), end=" ", flush=True)
-        time.sleep(2)
-        sleeptime += 2
+        print(sleeptime, end=" ", flush=True)
+        time.sleep(1)
+        sleeptime += 1
 
     return output
 
@@ -54,7 +54,9 @@ def print_job_output(outscript):
     sleeptime = 0
 
     print('Output file found. Waiting for complete Balsam Job Output.')
-    lastlines = ['Job 4 done on worker 1\n', 'Job 4 done on worker 2\n']
+    lastlines = ['Job 4 done on worker 1\n', 'Job 4 done on worker 2\n',
+                 'Run completed.\n']
+
     lastposition = 0
 
     while sleeptime < 60:
@@ -66,7 +68,7 @@ def print_job_output(outscript):
         if len(new) > 0:
             print(new, flush=True)
         else:
-            print('{}'.format(sleeptime), end=" ", flush=True)
+            print(sleeptime, end=" ", flush=True)
 
         if any(new.endswith(line) for line in lastlines):
             break
diff --git a/libensemble/tests/regression_tests/script_test_balsam_hworld.py b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
index e86ff3b82..16772441b 100644
--- a/libensemble/tests/regression_tests/script_test_balsam_hworld.py
+++ b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
@@ -3,7 +3,6 @@
 
 import os
 import numpy as np
-import multiprocessing
 import mpi4py
 from mpi4py import MPI
 
@@ -57,7 +56,7 @@ def build_simfunc():
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
-exit_criteria = {'elapsed_wallclock_time': 15}
+exit_criteria = {'elapsed_wallclock_time': 30}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria,

From 3626625fc2a4e2b378362328f6e0970c4437bdb6 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 11 Sep 2019 08:22:10 -0500
Subject: [PATCH 232/644] Asserting that the allocation function must declare
 fields when giving rows to be sent

---
 libensemble/libE_manager.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/libensemble/libE_manager.py b/libensemble/libE_manager.py
index 0ff9bdba8..2b2aed25f 100644
--- a/libensemble/libE_manager.py
+++ b/libensemble/libE_manager.py
@@ -203,6 +203,9 @@ def _check_work_order(self, Work, w):
         work_rows = Work['libE_info']['H_rows']
         if len(work_rows):
             work_fields = set(Work['H_fields'])
+            assert len(work_fields), \
+                "Allocation function requested rows={} be sent to worker={}, "\
+                "but requested no fields to be sent.".format(work_rows, w)
             hist_fields = self.hist.H.dtype.names
             diff_fields = list(work_fields.difference(hist_fields))
             assert not diff_fields, \

From d13dc20498571043b99c319d57da1b8fdb851f73 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 11 Sep 2019 10:03:52 -0500
Subject: [PATCH 233/644] Adding tests for more of persistent_aposmm

---
 libensemble/gen_funcs/persistent_aposmm.py    | 37 +++++---
 ... test_6-hump_camel_persistent_aposmm_1.py} |  4 +-
 .../test_6-hump_camel_persistent_aposmm_2.py  | 83 ++++++++++++++++++
 .../test_6-hump_camel_persistent_aposmm_3.py  | 84 +++++++++++++++++++
 .../test_6-hump_camel_persistent_aposmm_4.py  | 84 +++++++++++++++++++
 5 files changed, 278 insertions(+), 14 deletions(-)
 rename libensemble/tests/regression_tests/{test_6-hump_camel_persistent_aposmm.py => test_6-hump_camel_persistent_aposmm_1.py} (98%)
 create mode 100644 libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
 create mode 100644 libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
 create mode 100644 libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 60a0925bc..dc22ae119 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -200,7 +200,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     if gen_specs['localopt_method'] in ['LD_MMA', 'blmvm']:
         fields_to_pass = ['x_on_cube', 'f', 'grad']
     elif gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA',
-                                          'LN_NELDERMEAD', 'pounders', 'scipy_COBYLA']:
+                                          'LN_NELDERMEAD', 'pounders', 'scipy_Nelder-Mead']:
         fields_to_pass = ['x_on_cube', 'f']
     else:
         raise NotImplementedError("Unknown local optimization method " "'{}'.".format(gen_specs['localopt_method']))
@@ -305,7 +305,11 @@ def __init__(self, gen_specs, x0, f0, grad0=None):
 
         self.x0 = x0.copy()
         self.f0 = f0.copy()
-        self.grad0 = grad0.copy()
+        if grad0 is not None:
+            self.grad0 = grad0.copy()
+        else:
+            self.grad0 = None
+
 
         # {{{ setting the local optimization method
 
@@ -313,7 +317,7 @@ def __init__(self, gen_specs, x0, f0, grad0=None):
             run_local_opt = run_local_nlopt
         elif gen_specs['localopt_method'] in ['pounders', 'blmvm']:
             run_local_opt = run_local_tao
-        elif gen_specs['localopt_method'] in ['scipy_COBYLA']:
+        elif gen_specs['localopt_method'] in ['scipy_Nelder-Mead']:
             run_local_opt = run_local_scipy_opt
         else:
             raise NotImplementedError("Unknown local optimization method "
@@ -361,6 +365,7 @@ def iterate(self, data):
         return x_new
 
     def destroy(self, previous_x):
+
         while not isinstance(previous_x, ConvergedMsg):
             self.parent_can_read.clear()
             if self.grad0 is None:
@@ -455,7 +460,9 @@ def scipy_callback_fun(x, comm_queue, child_can_read, parent_can_read, gen_specs
     # print('[Child]: I have started waiting', flush=True)
     child_can_read.wait()
     # print('[Child]: Wohooo.. I am free folks', flush=True)
-    f_x_recv, = comm_queue.get()
+    x_recv, f_x_recv, = comm_queue.get()
+
+    assert np.array_equal(x, x_recv), "The point I gave is not the point I got back!"
     child_can_read.clear()
     return f_x_recv
 
@@ -476,19 +483,19 @@ def run_local_scipy_opt(gen_specs, comm_queue, x0, f0, child_can_read, parent_ca
     # print('[Child]: Started my optimization', flush=True)
     res = sp_opt.minimize(lambda x: scipy_callback_fun(x, comm_queue,
                           child_can_read, parent_can_read, gen_specs), x0,
-                          method=method, options={'maxiter': 100, 'tol': gen_specs['tol']})
+                          method=method, options={'maxiter': 10, 'fatol': gen_specs['fatol'], 'xatol': gen_specs['xatol']})
 
     if res['status'] == 2:  # SciPy code for exhausting budget of evaluations, so not at a minimum
         exit_code = 0
     else:
-        if method == 'COBYLA':
-            assert res['status'] == 1, "Unknown status for COBYLA"
+        if method == 'Nelder-Mead':
+            assert res['status'] == 0, "Unknown status for Nelder-Mead"
             exit_code = 1
 
     x_opt = res['x']
 
     # FIXME: Need to do something with the exit codes.
-    print(exit_code)
+    # print(exit_code)
 
     # print('[Child]: I have converged.', flush=True)
     comm_queue.put(ConvergedMsg(x_opt))
@@ -507,9 +514,12 @@ def tao_callback_fun(tao, x, f, comm_queue, child_can_read, parent_can_read, gen
     # print('[Child]: I have started waiting', flush=True)
     child_can_read.wait()
     # print('[Child]: Wohooo.. I am free folks', flush=True)
-    f_recv, = comm_queue.get()
-    child_can_read.clear()
+    x_recv, f_recv, = comm_queue.get()
+
+    assert np.array_equal(x.array_r, x_recv), "The point I gave is not the point I got back!"
+
     f.array[:] = f_recv
+    child_can_read.clear()
     return f
 
 
@@ -522,7 +532,10 @@ def tao_callback_fun_grad(tao, x, g, comm_queue, child_can_read, parent_can_read
     # print('[Child]: I have started waiting', flush=True)
     child_can_read.wait()
     # print('[Child]: Wohooo.. I am free folks', flush=True)
-    f_recv, grad_recv = comm_queue.get()
+    x_recv, f_recv, grad_recv = comm_queue.get()
+
+    assert np.array_equal(x.array_r, x_recv), "The point I gave is not the point I got back!"
+    
     g.array[:] = grad_recv
     child_can_read.clear()
     return f_recv
@@ -585,7 +598,7 @@ def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read, parent_can_read
     exit_code = tao.getConvergedReason()
 
     # FIXME: Need to do something with the exit codes.
-    print(exit_code)
+    # print(exit_code)
     # print(tao.view())
     # print(x_opt)
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
similarity index 98%
rename from libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
rename to libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
index ebfd920d8..aacef9de1 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
@@ -11,8 +11,8 @@
 # """
 
 # Do not change these lines - they are parsed by run-tests.sh
-# TESTSUITE_COMMS: mpi local tcp
-# TESTSUITE_NPROCS: 3 4
+# TESTSUITE_COMMS: local 
+# TESTSUITE_NPROCS: 4
 
 import sys
 import numpy as np
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
new file mode 100644
index 000000000..36d840fd2
--- /dev/null
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
@@ -0,0 +1,83 @@
+# """
+# Runs libEnsemble on the 6-hump camel problem. Documented here:
+#    https://www.sfu.ca/~ssurjano/camel6.html
+#
+# Execute via one of the following commands (e.g. 3 workers):
+#    mpiexec -np 4 python3 test_6-hump_camel_persistent_uniform_sampling.py
+#    python3 test_6-hump_camel_persistent_uniform_sampling.py --nworkers 3 --comms local
+#    python3 test_6-hump_camel_persistent_uniform_sampling.py --nworkers 3 --comms tcp
+#
+# The number of concurrent evaluations of the objective function will be 4-1=3.
+# """
+
+# Do not change these lines - they are parsed by run-tests.sh
+# TESTSUITE_COMMS: mpi 
+# TESTSUITE_NPROCS: 3 
+
+import sys
+import numpy as np
+
+# Import libEnsemble items for this test
+from libensemble.libE import libE
+from math import gamma, pi, sqrt
+from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
+from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
+from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
+from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
+from time import time
+
+nworkers, is_master, libE_specs, _ = parse_args()
+
+if is_master:
+    start_time = time()
+
+if nworkers < 2:
+    sys.exit("Cannot run with a persistent worker if only one worker -- aborting...")
+
+n = 2
+sim_specs = {'sim_f': sim_f,
+             'in': ['x'],
+             'out': [('f', float), ('grad', float, n)]}
+
+gen_out = [('x', float, n), ('x_on_cube', float, n), ('sim_id', int),
+           ('local_min', bool), ('local_pt', bool)]
+
+gen_specs = {'gen_f': gen_f,
+             'in': [],
+             'out': gen_out,
+             'batch_mode': True,
+             'initial_sample_size': 100,
+             'sample_points': np.round(minima, 1),
+             'localopt_method': 'LN_BOBYQA',
+             'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
+             'xtol_rel': 1e-6,
+             'num_active_gens': 1,
+             'local_min': True,
+             'dist_to_bound_multiple': 0.5,
+             'max_active_runs': 6,
+             'lb': np.array([-3, -2]),
+             'ub': np.array([3, 2])}
+
+alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)]}
+
+persis_info = per_worker_stream({}, nworkers + 1)
+
+exit_criteria = {'sim_max': 1000}
+
+# Perform the run
+H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
+                            alloc_specs, libE_specs)
+
+if is_master:
+    print('[Manager]:', H[np.where(H['local_min'])]['x'])
+    print('[Manager]: Time taken =', time() - start_time, flush=True)
+
+    tol = 1e-5
+    for m in minima:
+        # The minima are known on this test problem.
+        # We use their values to test APOSMM has identified all minima
+        print(np.min(np.sum((H[H['local_min']]['x'] - m)**2, 1)), flush=True)
+        assert np.min(np.sum((H[H['local_min']]['x'] - m)**2, 1)) < tol
+
+    save_libE_output(H, persis_info, __file__, nworkers)
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
new file mode 100644
index 000000000..925b327b7
--- /dev/null
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
@@ -0,0 +1,84 @@
+# """
+# Runs libEnsemble on the 6-hump camel problem. Documented here:
+#    https://www.sfu.ca/~ssurjano/camel6.html
+#
+# Execute via one of the following commands (e.g. 3 workers):
+#    mpiexec -np 4 python3 test_6-hump_camel_persistent_uniform_sampling.py
+#    python3 test_6-hump_camel_persistent_uniform_sampling.py --nworkers 3 --comms local
+#    python3 test_6-hump_camel_persistent_uniform_sampling.py --nworkers 3 --comms tcp
+#
+# The number of concurrent evaluations of the objective function will be 4-1=3.
+# """
+
+# Do not change these lines - they are parsed by run-tests.sh
+# TESTSUITE_COMMS: local 
+# TESTSUITE_NPROCS: 4
+
+import sys
+import numpy as np
+
+# Import libEnsemble items for this test
+from libensemble.libE import libE
+from math import gamma, pi, sqrt
+from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
+from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
+from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
+from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
+from time import time
+
+nworkers, is_master, libE_specs, _ = parse_args()
+
+if is_master:
+    start_time = time()
+
+if nworkers < 2:
+    sys.exit("Cannot run with a persistent worker if only one worker -- aborting...")
+
+n = 2
+sim_specs = {'sim_f': sim_f,
+             'in': ['x'],
+             'out': [('f', float), ('grad', float, n)]}
+
+gen_out = [('x', float, n), ('x_on_cube', float, n), ('sim_id', int),
+           ('local_min', bool), ('local_pt', bool)]
+
+gen_specs = {'gen_f': gen_f,
+             'in': [],
+             'out': gen_out,
+             'batch_mode': True,
+             'initial_sample_size': 100,
+             'sample_points': np.round(minima, 1),
+             'localopt_method': 'blmvm',
+             'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
+             'grtol': 1e-4,
+             'gatol': 1e-4,
+             'num_active_gens': 1,
+             'local_min': True,
+             'dist_to_bound_multiple': 0.5,
+             'max_active_runs': 6,
+             'lb': np.array([-3, -2]),
+             'ub': np.array([3, 2])}
+
+alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)]}
+
+persis_info = per_worker_stream({}, nworkers + 1)
+
+exit_criteria = {'sim_max': 1000}
+
+# Perform the run
+H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
+                            alloc_specs, libE_specs)
+
+if is_master:
+    print('[Manager]:', H[np.where(H['local_min'])]['x'])
+    print('[Manager]: Time taken =', time() - start_time, flush=True)
+
+    tol = 1e-5
+    for m in minima:
+        # The minima are known on this test problem.
+        # We use their values to test APOSMM has identified all minima
+        print(np.min(np.sum((H[H['local_min']]['x'] - m)**2, 1)), flush=True)
+        assert np.min(np.sum((H[H['local_min']]['x'] - m)**2, 1)) < tol
+
+    save_libE_output(H, persis_info, __file__, nworkers)
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
new file mode 100644
index 000000000..b11bcdaff
--- /dev/null
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
@@ -0,0 +1,84 @@
+# """
+# Runs libEnsemble on the 6-hump camel problem. Documented here:
+#    https://www.sfu.ca/~ssurjano/camel6.html
+#
+# Execute via one of the following commands (e.g. 3 workers):
+#    mpiexec -np 4 python3 test_6-hump_camel_persistent_uniform_sampling.py
+#    python3 test_6-hump_camel_persistent_uniform_sampling.py --nworkers 3 --comms local
+#    python3 test_6-hump_camel_persistent_uniform_sampling.py --nworkers 3 --comms tcp
+#
+# The number of concurrent evaluations of the objective function will be 4-1=3.
+# """
+
+# Do not change these lines - they are parsed by run-tests.sh
+# TESTSUITE_COMMS: local 
+# TESTSUITE_NPROCS: 4
+
+import sys
+import numpy as np
+
+# Import libEnsemble items for this test
+from libensemble.libE import libE
+from math import gamma, pi, sqrt
+from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
+from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
+from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
+from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
+from time import time
+
+nworkers, is_master, libE_specs, _ = parse_args()
+
+if is_master:
+    start_time = time()
+
+if nworkers < 2:
+    sys.exit("Cannot run with a persistent worker if only one worker -- aborting...")
+
+n = 2
+sim_specs = {'sim_f': sim_f,
+             'in': ['x'],
+             'out': [('f', float), ('grad', float, n)]}
+
+gen_out = [('x', float, n), ('x_on_cube', float, n), ('sim_id', int),
+           ('local_min', bool), ('local_pt', bool)]
+
+gen_specs = {'gen_f': gen_f,
+             'in': [],
+             'out': gen_out,
+             'batch_mode': True,
+             'initial_sample_size': 100,
+             'sample_points': np.round(minima, 1),
+             'localopt_method': 'scipy_Nelder-Mead',
+             'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
+             'fatol': 1e-5,
+             'xatol': 1e-5,
+             'num_active_gens': 1,
+             'local_min': True,
+             'dist_to_bound_multiple': 0.5,
+             'max_active_runs': 6,
+             'lb': np.array([-3, -2]),
+             'ub': np.array([3, 2])}
+
+alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)]}
+
+persis_info = per_worker_stream({}, nworkers + 1)
+
+exit_criteria = {'sim_max': 1000}
+
+# Perform the run
+H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
+                            alloc_specs, libE_specs)
+
+if is_master:
+    print('[Manager]:', H[np.where(H['local_min'])]['x'])
+    print('[Manager]: Time taken =', time() - start_time, flush=True)
+
+    tol = 1e-3
+    for m in minima:
+        # The minima are known on this test problem.
+        # We use their values to test APOSMM has identified all minima
+        print(np.min(np.sum((H[H['local_min']]['x'] - m)**2, 1)), flush=True)
+        assert np.min(np.sum((H[H['local_min']]['x'] - m)**2, 1)) < tol
+
+    save_libE_output(H, persis_info, __file__, nworkers)

From 24598f0bf15f07ae0fc029c8a569550dec526410 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 11 Sep 2019 10:44:47 -0500
Subject: [PATCH 234/644] flake8

---
 libensemble/gen_funcs/persistent_aposmm.py      | 17 ++++++++---------
 .../test_6-hump_camel_persistent_aposmm_1.py    |  2 +-
 .../test_6-hump_camel_persistent_aposmm_2.py    |  4 ++--
 .../test_6-hump_camel_persistent_aposmm_3.py    |  2 +-
 .../test_6-hump_camel_persistent_aposmm_4.py    |  2 +-
 5 files changed, 13 insertions(+), 14 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index dc22ae119..d7843d3f9 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -310,7 +310,6 @@ def __init__(self, gen_specs, x0, f0, grad0=None):
         else:
             self.grad0 = None
 
-
         # {{{ setting the local optimization method
 
         if gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA', 'LN_NELDERMEAD', 'LD_MMA']:
@@ -485,12 +484,12 @@ def run_local_scipy_opt(gen_specs, comm_queue, x0, f0, child_can_read, parent_ca
                           child_can_read, parent_can_read, gen_specs), x0,
                           method=method, options={'maxiter': 10, 'fatol': gen_specs['fatol'], 'xatol': gen_specs['xatol']})
 
-    if res['status'] == 2:  # SciPy code for exhausting budget of evaluations, so not at a minimum
-        exit_code = 0
-    else:
-        if method == 'Nelder-Mead':
-            assert res['status'] == 0, "Unknown status for Nelder-Mead"
-            exit_code = 1
+    # if res['status'] == 2:  # SciPy code for exhausting budget of evaluations, so not at a minimum
+    #     exit_code = 0
+    # else:
+    #     if method == 'Nelder-Mead':
+    #         assert res['status'] == 0, "Unknown status for Nelder-Mead"
+    #         exit_code = 1
 
     x_opt = res['x']
 
@@ -535,7 +534,7 @@ def tao_callback_fun_grad(tao, x, g, comm_queue, child_can_read, parent_can_read
     x_recv, f_recv, grad_recv = comm_queue.get()
 
     assert np.array_equal(x.array_r, x_recv), "The point I gave is not the point I got back!"
-    
+
     g.array[:] = grad_recv
     child_can_read.clear()
     return f_recv
@@ -595,7 +594,7 @@ def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read, parent_can_read
     tao.solve(x)
 
     x_opt = tao.getSolution().getArray()
-    exit_code = tao.getConvergedReason()
+    # exit_code = tao.getConvergedReason()
 
     # FIXME: Need to do something with the exit codes.
     # print(exit_code)
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
index aacef9de1..d28c1ffd6 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
@@ -11,7 +11,7 @@
 # """
 
 # Do not change these lines - they are parsed by run-tests.sh
-# TESTSUITE_COMMS: local 
+# TESTSUITE_COMMS: local
 # TESTSUITE_NPROCS: 4
 
 import sys
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
index 36d840fd2..2206c0ffa 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
@@ -11,8 +11,8 @@
 # """
 
 # Do not change these lines - they are parsed by run-tests.sh
-# TESTSUITE_COMMS: mpi 
-# TESTSUITE_NPROCS: 3 
+# TESTSUITE_COMMS: mpi
+# TESTSUITE_NPROCS: 3
 
 import sys
 import numpy as np
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
index 925b327b7..52803938c 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
@@ -11,7 +11,7 @@
 # """
 
 # Do not change these lines - they are parsed by run-tests.sh
-# TESTSUITE_COMMS: local 
+# TESTSUITE_COMMS: local
 # TESTSUITE_NPROCS: 4
 
 import sys
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
index b11bcdaff..504ca9582 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
@@ -11,7 +11,7 @@
 # """
 
 # Do not change these lines - they are parsed by run-tests.sh
-# TESTSUITE_COMMS: local 
+# TESTSUITE_COMMS: local
 # TESTSUITE_NPROCS: 4
 
 import sys

From a1171030b8506560aa8758d3616b395f730dce51 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 11 Sep 2019 10:59:24 -0500
Subject: [PATCH 235/644] Modify Balsam to print hosttype

---
 conda/test_balsam_hworld.py                  | 21 +++++++++++++++++-
 libensemble/tests/regression_tests/common.py | 23 ++++++++++++++++++++
 2 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/conda/test_balsam_hworld.py b/conda/test_balsam_hworld.py
index c5cd6fb7c..cef3f1ed1 100644
--- a/conda/test_balsam_hworld.py
+++ b/conda/test_balsam_hworld.py
@@ -2,7 +2,7 @@
 import os
 import time
 import libensemble
-from libensemble.tests.regression_tests.common import modify_Balsam_worker
+from libensemble.tests.regression_tests.common import modify_Balsam_worker, modify_Balsam_hostprint
 
 # TESTSUITE_COMMS: local
 # TESTSUITE_NPROCS: 3
@@ -98,6 +98,7 @@ def move_job_coverage(jobdir):
     basedb = os.environ['HOME'] + '/test-balsam/data/libe_test-balsam'
 
     modify_Balsam_worker()
+    modify_Balsam_hostprint()
     run_Balsam_job()
 
     jobdir = wait_for_job_dir(basedb)
@@ -106,3 +107,21 @@ def move_job_coverage(jobdir):
     move_job_coverage(jobdir)
 
     print('Test complete.')
+
+# travis_run_before_install && travis_run_install && travis_run_before_script
+
+# 11-Sep-2019 14:36:27|7301|   ERROR|balsam:47] Uncaught Exception <class 'ValueError'>: Cooley WorkerGroup needs workers_file to setup
+# Traceback (most recent call last):
+#   File "/home/travis/build/Libensemble/balsam/balsam/launcher/launcher.py", line 443, in <module>
+#     main(args)
+#   File "/home/travis/build/Libensemble/balsam/balsam/launcher/launcher.py", line 422, in main
+#     launcher = Launcher(wf_filter, timelimit_min, gpus_per_node)
+#   File "/home/travis/build/Libensemble/balsam/balsam/launcher/launcher.py", line 104, in __init__
+#     self.worker_group = worker.WorkerGroup()
+#   File "/home/travis/build/Libensemble/balsam/balsam/launcher/worker.py", line 50, in __init__
+#     self.setup()
+#   File "/home/travis/build/Libensemble/balsam/balsam/launcher/worker.py", line 112, in setup_COOLEY
+#     raise ValueError("Cooley WorkerGroup needs workers_file to setup")
+# ValueError: Cooley WorkerGroup needs workers_file to setup
+
+# print('HOST TYPE:', self.host_type)
diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index 65f8ff953..d8094a5fc 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -225,3 +225,26 @@ def modify_Balsam_pyCoverage():
     with open(balsam_commands_path, 'w') as f:
         for line in lines:
             f.write(line)
+
+def modify_Balsam_hostprint():
+    # Also modify Balsam to print Host type (for debugging purposes)
+    import balsam
+
+    print_line = "        print('HOST TYPE: ', self.host_type)\n"
+
+    workerfile = 'worker.py'
+    balsam_path = os.path.dirname(balsam.__file__) + '/launcher'
+    balsam_worker_path = os.path.join(balsam_path, workerfile)
+
+    with open(balsam_worker_path, 'r') as f:
+        lines = f.readlines()
+
+    newlines = []
+    for line in lines:
+        newlines.append(line)
+        if line == "        self.host_type = JobEnv.host_type\n":
+            newlines.append(print_line)
+
+    with open(balsam_worker_path, 'w') as f:
+        for line in newlines:
+            f.write(line)

From a34f86da8a4788865089dde6c39621fc3d730f7b Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 11 Sep 2019 11:07:43 -0500
Subject: [PATCH 236/644] flake8

---
 libensemble/tests/regression_tests/common.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index d8094a5fc..2f64cf673 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -226,6 +226,7 @@ def modify_Balsam_pyCoverage():
         for line in lines:
             f.write(line)
 
+
 def modify_Balsam_hostprint():
     # Also modify Balsam to print Host type (for debugging purposes)
     import balsam

From 32a980ba4392a9744f7439a17aa7b08ba69cb86f Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 11 Sep 2019 11:29:16 -0500
Subject: [PATCH 237/644] don't append print line on subsequent runs

---
 libensemble/tests/regression_tests/common.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index 2f64cf673..f804592d5 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -242,10 +242,13 @@ def modify_Balsam_hostprint():
 
     newlines = []
     for line in lines:
+        if line == print_line:
+            continue
         newlines.append(line)
         if line == "        self.host_type = JobEnv.host_type\n":
             newlines.append(print_line)
 
+
     with open(balsam_worker_path, 'w') as f:
         for line in newlines:
             f.write(line)

From 975b119a16ba877c0f937e711c634d265cea9d8b Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 11 Sep 2019 11:41:25 -0500
Subject: [PATCH 238/644] flake8...

---
 libensemble/tests/regression_tests/common.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index f804592d5..d5e03d306 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -248,7 +248,6 @@ def modify_Balsam_hostprint():
         if line == "        self.host_type = JobEnv.host_type\n":
             newlines.append(print_line)
 
-
     with open(balsam_worker_path, 'w') as f:
         for line in newlines:
             f.write(line)

From 1349275d8e1c62b20987311032c88f32ca4f275b Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 11 Sep 2019 14:12:42 -0500
Subject: [PATCH 239/644] test commit

---
 conda/test_balsam_hworld.py | 2 --
 1 file changed, 2 deletions(-)

diff --git a/conda/test_balsam_hworld.py b/conda/test_balsam_hworld.py
index cef3f1ed1..5270763e5 100644
--- a/conda/test_balsam_hworld.py
+++ b/conda/test_balsam_hworld.py
@@ -123,5 +123,3 @@ def move_job_coverage(jobdir):
 #   File "/home/travis/build/Libensemble/balsam/balsam/launcher/worker.py", line 112, in setup_COOLEY
 #     raise ValueError("Cooley WorkerGroup needs workers_file to setup")
 # ValueError: Cooley WorkerGroup needs workers_file to setup
-
-# print('HOST TYPE:', self.host_type)

From d722c7c96081a293e8e716857902c92b258f8dc0 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 11 Sep 2019 14:45:35 -0500
Subject: [PATCH 240/644] Making mpi to get more code coverage

---
 .../regression_tests/test_6-hump_camel_persistent_aposmm_1.py   | 2 +-
 .../regression_tests/test_6-hump_camel_persistent_aposmm_3.py   | 2 +-
 .../regression_tests/test_6-hump_camel_persistent_aposmm_4.py   | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
index d28c1ffd6..6026f75c9 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
@@ -11,7 +11,7 @@
 # """
 
 # Do not change these lines - they are parsed by run-tests.sh
-# TESTSUITE_COMMS: local
+# TESTSUITE_COMMS: mpi
 # TESTSUITE_NPROCS: 4
 
 import sys
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
index 52803938c..fd82b0984 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
@@ -11,7 +11,7 @@
 # """
 
 # Do not change these lines - they are parsed by run-tests.sh
-# TESTSUITE_COMMS: local
+# TESTSUITE_COMMS: mpi
 # TESTSUITE_NPROCS: 4
 
 import sys
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
index 504ca9582..2d52fffd5 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
@@ -11,7 +11,7 @@
 # """
 
 # Do not change these lines - they are parsed by run-tests.sh
-# TESTSUITE_COMMS: local
+# TESTSUITE_COMMS: mpi local
 # TESTSUITE_NPROCS: 4
 
 import sys

From 4cc561012d915bfce769468dbe0d76f925d5604d Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 11 Sep 2019 15:07:56 -0500
Subject: [PATCH 241/644] additional modifications to Balsam for debugging

---
 conda/test_balsam_hworld.py                  |  3 ++-
 libensemble/tests/regression_tests/common.py | 26 +++++++++++++++-----
 2 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/conda/test_balsam_hworld.py b/conda/test_balsam_hworld.py
index 5270763e5..bb728b3d7 100644
--- a/conda/test_balsam_hworld.py
+++ b/conda/test_balsam_hworld.py
@@ -108,7 +108,8 @@ def move_job_coverage(jobdir):
 
     print('Test complete.')
 
-# travis_run_before_install && travis_run_install && travis_run_before_script
+
+# IN BALSAM LOG:
 
 # 11-Sep-2019 14:36:27|7301|   ERROR|balsam:47] Uncaught Exception <class 'ValueError'>: Cooley WorkerGroup needs workers_file to setup
 # Traceback (most recent call last):
diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index d5e03d306..82b2bc49e 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -228,10 +228,20 @@ def modify_Balsam_pyCoverage():
 
 
 def modify_Balsam_hostprint():
-    # Also modify Balsam to print Host type (for debugging purposes)
+    # Also modify Balsam Worker & Worker Gropu to print Host type (for debugging
+    #    purposes). Balsam test bug may be caused by setup_COOLEY() being called
+    #   instead of setup_DEFAULT() within Balsam's worker.py
     import balsam
 
-    print_line = "        print('HOST TYPE: ', self.host_type)\n"
+    print_lines = {"host": "        print('HOST TYPE: ', self.host_type)\n",
+                   "COOLEY": "        print('IN setup_COOLEY')\n",
+                   "DEFAULT": "        print('IN setup_DEFAULT')\n"}
+
+    host_prior_lines = ["        self.host_type = JobEnv.host_type\n",
+                        "        self.host_type = host_type\n"]
+
+    setup_prior_lines = ["    def setup_COOLEY(self):\n",
+                         "    def setup_DEFAULT(self):\n"]
 
     workerfile = 'worker.py'
     balsam_path = os.path.dirname(balsam.__file__) + '/launcher'
@@ -242,11 +252,15 @@ def modify_Balsam_hostprint():
 
     newlines = []
     for line in lines:
-        if line == print_line:
+        if line in print_lines.values():
             continue
-        newlines.append(line)
-        if line == "        self.host_type = JobEnv.host_type\n":
-            newlines.append(print_line)
+        newlines.append(line)               # Line of code from prior
+        if line in host_prior_lines:        #
+            newlines.append(print_lines['host'])
+        elif line == setup_prior_lines[0]:
+            newlines.append(print_lines['COOLEY'])
+        elif line == setup_prior_lines[1]:
+            newlines.append(print_lines['DEFAULT'])
 
     with open(balsam_worker_path, 'w') as f:
         for line in newlines:

From fd0458a7c6ff999664b8e4dd358ba14eee10f2c2 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 11 Sep 2019 16:21:43 -0500
Subject: [PATCH 242/644] Showing Steve something unexpected

---
 .../regression_tests/test_6-hump_camel_persistent_aposmm_1.py   | 2 +-
 .../regression_tests/test_6-hump_camel_persistent_aposmm_2.py   | 2 +-
 .../regression_tests/test_6-hump_camel_persistent_aposmm_3.py   | 2 +-
 .../regression_tests/test_6-hump_camel_persistent_aposmm_4.py   | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
index 6026f75c9..d28c1ffd6 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
@@ -11,7 +11,7 @@
 # """
 
 # Do not change these lines - they are parsed by run-tests.sh
-# TESTSUITE_COMMS: mpi
+# TESTSUITE_COMMS: local
 # TESTSUITE_NPROCS: 4
 
 import sys
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
index 2206c0ffa..f94884265 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
@@ -11,7 +11,7 @@
 # """
 
 # Do not change these lines - they are parsed by run-tests.sh
-# TESTSUITE_COMMS: mpi
+# TESTSUITE_COMMS: local
 # TESTSUITE_NPROCS: 3
 
 import sys
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
index fd82b0984..52803938c 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
@@ -11,7 +11,7 @@
 # """
 
 # Do not change these lines - they are parsed by run-tests.sh
-# TESTSUITE_COMMS: mpi
+# TESTSUITE_COMMS: local
 # TESTSUITE_NPROCS: 4
 
 import sys
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
index 2d52fffd5..504ca9582 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
@@ -11,7 +11,7 @@
 # """
 
 # Do not change these lines - they are parsed by run-tests.sh
-# TESTSUITE_COMMS: mpi local
+# TESTSUITE_COMMS: local
 # TESTSUITE_NPROCS: 4
 
 import sys

From c5126a6e67143fb25c3969675dd2f10f9d591d5d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 12 Sep 2019 06:44:36 -0500
Subject: [PATCH 243/644] Including multiprocessing in code coverage

---
 libensemble/tests/run-tests.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/run-tests.sh b/libensemble/tests/run-tests.sh
index 700fe8de9..e55b3a64e 100755
--- a/libensemble/tests/run-tests.sh
+++ b/libensemble/tests/run-tests.sh
@@ -316,7 +316,7 @@ COV_LINE_PARALLEL=''
 if [ $RUN_COV_TESTS = "true" ]; then
    COV_LINE_SERIAL='--cov --cov-report html:cov_unit'
    #COV_LINE_PARALLEL='-m coverage run --parallel-mode --rcfile=../.coveragerc' #running in sub-dirs
-   COV_LINE_PARALLEL='-m coverage run --parallel-mode' #running in regression dir itself
+   COV_LINE_PARALLEL='-m coverage run --parallel-mode --concurrency=multiprocessing' #running in regression dir itself
 
    #include branch coverage? eg. flags if never jumped a statement block... [see .coveragerc file]
    #COV_LINE_PARALLEL='-m coverage run --branch --parallel-mode'

From 1dd35fb63614f07c91b49794578643d46696e0b4 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 12 Sep 2019 06:44:36 -0500
Subject: [PATCH 244/644] Including multiprocessing in code coverage

(cherry picked from commit c5126a6e67143fb25c3969675dd2f10f9d591d5d)
---
 libensemble/tests/run-tests.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/run-tests.sh b/libensemble/tests/run-tests.sh
index 700fe8de9..e55b3a64e 100755
--- a/libensemble/tests/run-tests.sh
+++ b/libensemble/tests/run-tests.sh
@@ -316,7 +316,7 @@ COV_LINE_PARALLEL=''
 if [ $RUN_COV_TESTS = "true" ]; then
    COV_LINE_SERIAL='--cov --cov-report html:cov_unit'
    #COV_LINE_PARALLEL='-m coverage run --parallel-mode --rcfile=../.coveragerc' #running in sub-dirs
-   COV_LINE_PARALLEL='-m coverage run --parallel-mode' #running in regression dir itself
+   COV_LINE_PARALLEL='-m coverage run --parallel-mode --concurrency=multiprocessing' #running in regression dir itself
 
    #include branch coverage? eg. flags if never jumped a statement block... [see .coveragerc file]
    #COV_LINE_PARALLEL='-m coverage run --branch --parallel-mode'

From b6101f26a82a197dbdf986ea76e9da3ecfd74a86 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 12 Sep 2019 10:01:05 -0500
Subject: [PATCH 245/644] Adding support for pounders

---
 libensemble/gen_funcs/persistent_aposmm.py | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index d7843d3f9..2cd982c3c 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -200,8 +200,10 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     if gen_specs['localopt_method'] in ['LD_MMA', 'blmvm']:
         fields_to_pass = ['x_on_cube', 'f', 'grad']
     elif gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA',
-                                          'LN_NELDERMEAD', 'pounders', 'scipy_Nelder-Mead']:
+                                          'LN_NELDERMEAD', 'scipy_Nelder-Mead']:
         fields_to_pass = ['x_on_cube', 'f']
+    elif gen_specs['localopt_method'] in ['pounders']: 
+        fields_to_pass = ['x_on_cube', 'fvec']
     else:
         raise NotImplementedError("Unknown local optimization method " "'{}'.".format(gen_specs['localopt_method']))
 
@@ -252,7 +254,8 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                 # Initialize a local opt run
                 local_opter = LocalOptInterfacer(gen_specs, local_H[ind]['x_on_cube'],
-                                                 local_H[ind]['f'], local_H[ind]['grad'] if 'grad' in fields_to_pass else None)
+                                                 local_H[ind]['f'] if 'f' in fields_to_pass else local_H[ind]['fvec'], 
+                                                 local_H[ind]['grad'] if 'grad' in fields_to_pass else None)
 
                 local_opters[total_runs] = local_opter
 
@@ -318,9 +321,6 @@ def __init__(self, gen_specs, x0, f0, grad0=None):
             run_local_opt = run_local_tao
         elif gen_specs['localopt_method'] in ['scipy_Nelder-Mead']:
             run_local_opt = run_local_scipy_opt
-        else:
-            raise NotImplementedError("Unknown local optimization method "
-                                      "'{}'.".format(gen_specs['localopt_method']))
 
         # }}}
 
@@ -346,6 +346,8 @@ def iterate(self, data):
 
         if 'grad' in data.dtype.names:
             self.comm_queue.put((data['x_on_cube'], data['f'], data['grad']))
+        elif 'fvec' in data.dtype.names:
+            self.comm_queue.put((data['x_on_cube'], data['fvec']))
         else:
             self.comm_queue.put((data['x_on_cube'], data['f'], ))
 
@@ -925,7 +927,7 @@ def initialize_APOSMM(H, gen_specs, libE_info):
 
     n_s = 0
 
-    if 'single_component_at_a_time' in gen_specs and gen_specs['single_component_at_a_time']:
+    if gen_specs.get('single_component_at_a_time'):
         assert gen_specs['batch_mode'], ("Must be in batch mode when using "
                                          "'single_component_at_a_time'")
         c_flag = True
@@ -975,6 +977,9 @@ def initialize_APOSMM(H, gen_specs, libE_info):
                       ('pt_id', int),  # Identify the same point evaluated by different sim_f's or components
                       ]
 
+    if 'components' in gen_specs:
+        local_H_fields += [('fvec', float, gen_specs['components'])] 
+
     local_H = np.empty(0, dtype=local_H_fields)
 
     return n, n_s, c_flag, rk_c, ld, mu, nu, comm, local_H

From 57bdfc79179255ea9160258d137cf06fd749e353 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 12 Sep 2019 10:02:41 -0500
Subject: [PATCH 246/644] Adding test for pounders in persistent_aposmm

---
 .../test_chwirut_pounders_persistent.py       | 80 +++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py

diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
new file mode 100644
index 000000000..2b89a50e9
--- /dev/null
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
@@ -0,0 +1,80 @@
+# """
+# Runs libEnsemble with APOSMM+POUNDERS on the chwirut least squares problem.
+# All 214 residual calculations for a given point are performed as a single
+# simulation evaluation.
+#
+# Execute via one of the following commands (e.g. 3 workers):
+#    mpiexec -np 4 python3 test_chwirut_pounders.py
+#
+# The number of concurrent evaluations of the objective function will be 4-1=3.
+# """
+
+# Do not change these lines - they are parsed by run-tests.sh
+# TESTSUITE_COMMS: local
+# TESTSUITE_NPROCS: 4
+
+import sys
+import numpy as np
+
+# Import libEnsemble items for this test
+from libensemble.libE import libE
+from math import gamma, pi, sqrt
+from libensemble.sim_funcs.chwirut1 import chwirut_eval as sim_f
+from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
+from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
+from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+
+nworkers, is_master, libE_specs, _ = parse_args()
+
+if nworkers < 2:
+    sys.exit("Cannot run with a persistent worker if only one worker -- aborting...")
+
+# Declare the run parameters/functions
+m = 214
+n = 3
+budget = 10
+
+sim_specs = {'sim_f': sim_f,
+             'in': ['x'],
+             'out': [('f', float), ('fvec', float, m)],
+             'combine_component_func': lambda x: np.sum(np.power(x, 2))}
+
+gen_out = [('x', float, n), ('x_on_cube', float, n), ('sim_id', int),
+           ('local_min', bool), ('local_pt', bool)]
+
+# lb tries to avoid x[1]=-x[2], which results in division by zero in chwirut.
+gen_specs = {'gen_f': gen_f,
+             'in': [],
+             'out': gen_out,
+             'batch_mode': True,
+             'initial_sample_size': 100,
+             'localopt_method': 'pounders',
+             'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
+             'grtol': 1e-5,
+             'gatol': 1e-5,
+             'num_active_gens': 1,
+             'dist_to_bound_multiple': 0.5,
+             'components': m,
+             'lb': (-2-np.pi/10)*np.ones(n),
+             'ub': 2*np.ones(n)}
+
+alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)]}
+
+persis_info = per_worker_stream({}, nworkers + 1)
+
+exit_criteria = {'sim_max': 500}
+
+# Perform the run
+H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
+                            alloc_specs, libE_specs)
+
+if is_master:
+    assert flag == 0
+    assert len(H) >= budget
+
+    save_libE_output(H, persis_info, __file__, nworkers)
+    # Calculating the Jacobian at the best point (though this information was not used by pounders)
+    from libensemble.sim_funcs.chwirut1 import EvaluateJacobian
+    J = EvaluateJacobian(H['x'][np.argmin(H['f'])])
+    assert np.linalg.norm(J) < 2000
+

From ff0b4cded6fef92444fb0e4f949de06538d45956 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 12 Sep 2019 10:03:25 -0500
Subject: [PATCH 247/644] Varying tests slightly for coverage

---
 .../regression_tests/test_6-hump_camel_persistent_aposmm_1.py | 3 +--
 .../regression_tests/test_6-hump_camel_persistent_aposmm_2.py | 4 ++--
 .../regression_tests/test_6-hump_camel_persistent_aposmm_3.py | 1 -
 .../regression_tests/test_6-hump_camel_persistent_aposmm_4.py | 1 -
 4 files changed, 3 insertions(+), 6 deletions(-)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
index d28c1ffd6..94a145662 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
@@ -52,9 +52,8 @@
              'localopt_method': 'LD_MMA',
              'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
              'xtol_rel': 1e-6,
+             'ftol_rel': 1e-6,
              'num_active_gens': 1,
-             'local_min': True,
-             'dist_to_bound_multiple': 0.5,
              'max_active_runs': 6,
              'lb': np.array([-3, -2]),
              'ub': np.array([3, 2])}
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
index f94884265..abe9d1dca 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
@@ -51,9 +51,9 @@
              'sample_points': np.round(minima, 1),
              'localopt_method': 'LN_BOBYQA',
              'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
-             'xtol_rel': 1e-6,
+             'xtol_abs': 1e-6,
+             'ftol_abs': 1e-6,
              'num_active_gens': 1,
-             'local_min': True,
              'dist_to_bound_multiple': 0.5,
              'max_active_runs': 6,
              'lb': np.array([-3, -2]),
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
index 52803938c..a8f566eca 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
@@ -54,7 +54,6 @@
              'grtol': 1e-4,
              'gatol': 1e-4,
              'num_active_gens': 1,
-             'local_min': True,
              'dist_to_bound_multiple': 0.5,
              'max_active_runs': 6,
              'lb': np.array([-3, -2]),
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
index 504ca9582..e054031a5 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
@@ -54,7 +54,6 @@
              'fatol': 1e-5,
              'xatol': 1e-5,
              'num_active_gens': 1,
-             'local_min': True,
              'dist_to_bound_multiple': 0.5,
              'max_active_runs': 6,
              'lb': np.array([-3, -2]),

From 08a1257255033a66f1cdd8536d960006be96474d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 12 Sep 2019 10:13:59 -0500
Subject: [PATCH 248/644] phlayke-ate

---
 libensemble/gen_funcs/persistent_aposmm.py                  | 6 +++---
 .../regression_tests/test_chwirut_pounders_persistent.py    | 1 -
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 2cd982c3c..7d9221484 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -202,7 +202,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     elif gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA',
                                           'LN_NELDERMEAD', 'scipy_Nelder-Mead']:
         fields_to_pass = ['x_on_cube', 'f']
-    elif gen_specs['localopt_method'] in ['pounders']: 
+    elif gen_specs['localopt_method'] in ['pounders']:
         fields_to_pass = ['x_on_cube', 'fvec']
     else:
         raise NotImplementedError("Unknown local optimization method " "'{}'.".format(gen_specs['localopt_method']))
@@ -254,7 +254,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                 # Initialize a local opt run
                 local_opter = LocalOptInterfacer(gen_specs, local_H[ind]['x_on_cube'],
-                                                 local_H[ind]['f'] if 'f' in fields_to_pass else local_H[ind]['fvec'], 
+                                                 local_H[ind]['f'] if 'f' in fields_to_pass else local_H[ind]['fvec'],
                                                  local_H[ind]['grad'] if 'grad' in fields_to_pass else None)
 
                 local_opters[total_runs] = local_opter
@@ -978,7 +978,7 @@ def initialize_APOSMM(H, gen_specs, libE_info):
                       ]
 
     if 'components' in gen_specs:
-        local_H_fields += [('fvec', float, gen_specs['components'])] 
+        local_H_fields += [('fvec', float, gen_specs['components'])]
 
     local_H = np.empty(0, dtype=local_H_fields)
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
index 2b89a50e9..39416371a 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
@@ -77,4 +77,3 @@
     from libensemble.sim_funcs.chwirut1 import EvaluateJacobian
     J = EvaluateJacobian(H['x'][np.argmin(H['f'])])
     assert np.linalg.norm(J) < 2000
-

From 6fb4b6d686544cd32b510a2c155014cdc982490a Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 12 Sep 2019 11:42:36 -0500
Subject: [PATCH 249/644] Supporting older petsc4py call

---
 libensemble/gen_funcs/persistent_aposmm.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 7d9221484..407694fa1 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -570,7 +570,10 @@ def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read, parent_can_read
         f.setSizes(m)
         f.setFromOptions()
 
-        tao.setResidual(lambda tao, x, f: tao_callback_fun(tao, x, f, comm_queue, child_can_read, parent_can_read, gen_specs), f)
+        if hasattr(tao, 'setResidual'):
+            tao.setResidual(lambda tao, x, f: tao_callback_fun(tao, x, f, comm_queue, child_can_read, parent_can_read, gen_specs), f)
+        else:
+            tao.setSeparableObjective(lambda tao, x, f: tao_callback_fun(tao, x, f, comm_queue, child_can_read, parent_can_read, gen_specs), f)
 
     elif gen_specs['localopt_method'] == 'blmvm':
         g = PETSc.Vec().create(tao_comm)

From 688e3e8082dcf547d7a68672eafb55cfc6ad6e2d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 13 Sep 2019 08:10:38 -0500
Subject: [PATCH 250/644] Tightening convergence

---
 .../regression_tests/test_chwirut_pounders_persistent.py      | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
index 39416371a..5ec11264a 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
@@ -50,8 +50,8 @@
              'initial_sample_size': 100,
              'localopt_method': 'pounders',
              'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
-             'grtol': 1e-5,
-             'gatol': 1e-5,
+             'grtol': 1e-6,
+             'gatol': 1e-6,
              'num_active_gens': 1,
              'dist_to_bound_multiple': 0.5,
              'components': m,

From 1a139d70577f388bdf3b3ba2164c1bcdf2f56213 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 4 Sep 2019 14:59:39 -0500
Subject: [PATCH 251/644] Adds ulimit adjustment to travis

(cherry picked from commit d935007644277c47c7c6acbe6675894f30dc5917)
---
 .travis.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.travis.yml b/.travis.yml
index b1cee2631..4cc24d54c 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -89,6 +89,8 @@ before_script:
   - flake8 libensemble
   - echo "export BALSAM_DB_PATH=~/test-balsam" > setbalsampath.sh
   - source setbalsampath.sh
+  # Allow 10000 files to be open at once (critical for persistent_aposmm)
+  - ulimit -Sn 10000
   # Set conda compilers to use new SDK instead of Travis default.
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
         echo "export CONDA_BUILD_SYSROOT=/Users/travis/build/Libensemble/sdk/MacOSX10.13.sdk" > setenv.sh;

From 31f42d1df9f7b36dda7879b9405bee87b13dddbd Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 13 Sep 2019 10:28:55 -0500
Subject: [PATCH 252/644] Pounders may not find points with small Jacobians

---
 .../regression_tests/test_chwirut_pounders_persistent.py  | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
index 5ec11264a..4bb3bfea6 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
@@ -73,7 +73,7 @@
     assert len(H) >= budget
 
     save_libE_output(H, persis_info, __file__, nworkers)
-    # Calculating the Jacobian at the best point (though this information was not used by pounders)
-    from libensemble.sim_funcs.chwirut1 import EvaluateJacobian
-    J = EvaluateJacobian(H['x'][np.argmin(H['f'])])
-    assert np.linalg.norm(J) < 2000
+    # # Calculating the Jacobian at the best point (though this information was not used by pounders)
+    # from libensemble.sim_funcs.chwirut1 import EvaluateJacobian
+    # J = EvaluateJacobian(H['x'][np.argmin(H['f'])])
+    # assert np.linalg.norm(J) < 2000

From 063e33db9b5e29de2a050786ea4c81459f7ad037 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 13 Sep 2019 11:35:09 -0500
Subject: [PATCH 253/644] modifies Balsam to not think self on Cooley if 'cc'
 in hostname

---
 conda/test_balsam_hworld.py                  | 21 +--------
 libensemble/tests/regression_tests/common.py | 46 +++++++-------------
 2 files changed, 18 insertions(+), 49 deletions(-)

diff --git a/conda/test_balsam_hworld.py b/conda/test_balsam_hworld.py
index bb728b3d7..0c837d8f0 100644
--- a/conda/test_balsam_hworld.py
+++ b/conda/test_balsam_hworld.py
@@ -2,7 +2,7 @@
 import os
 import time
 import libensemble
-from libensemble.tests.regression_tests.common import modify_Balsam_worker, modify_Balsam_hostprint
+from libensemble.tests.regression_tests.common import modify_Balsam_worker, modify_Balsam_JobEnv
 
 # TESTSUITE_COMMS: local
 # TESTSUITE_NPROCS: 3
@@ -98,7 +98,7 @@ def move_job_coverage(jobdir):
     basedb = os.environ['HOME'] + '/test-balsam/data/libe_test-balsam'
 
     modify_Balsam_worker()
-    modify_Balsam_hostprint()
+    modify_Balsam_JobEnv()
     run_Balsam_job()
 
     jobdir = wait_for_job_dir(basedb)
@@ -107,20 +107,3 @@ def move_job_coverage(jobdir):
     move_job_coverage(jobdir)
 
     print('Test complete.')
-
-
-# IN BALSAM LOG:
-
-# 11-Sep-2019 14:36:27|7301|   ERROR|balsam:47] Uncaught Exception <class 'ValueError'>: Cooley WorkerGroup needs workers_file to setup
-# Traceback (most recent call last):
-#   File "/home/travis/build/Libensemble/balsam/balsam/launcher/launcher.py", line 443, in <module>
-#     main(args)
-#   File "/home/travis/build/Libensemble/balsam/balsam/launcher/launcher.py", line 422, in main
-#     launcher = Launcher(wf_filter, timelimit_min, gpus_per_node)
-#   File "/home/travis/build/Libensemble/balsam/balsam/launcher/launcher.py", line 104, in __init__
-#     self.worker_group = worker.WorkerGroup()
-#   File "/home/travis/build/Libensemble/balsam/balsam/launcher/worker.py", line 50, in __init__
-#     self.setup()
-#   File "/home/travis/build/Libensemble/balsam/balsam/launcher/worker.py", line 112, in setup_COOLEY
-#     raise ValueError("Cooley WorkerGroup needs workers_file to setup")
-# ValueError: Cooley WorkerGroup needs workers_file to setup
diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index 82b2bc49e..aaa2f9784 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -227,41 +227,27 @@ def modify_Balsam_pyCoverage():
             f.write(line)
 
 
-def modify_Balsam_hostprint():
-    # Also modify Balsam Worker & Worker Gropu to print Host type (for debugging
-    #    purposes). Balsam test bug may be caused by setup_COOLEY() being called
-    #   instead of setup_DEFAULT() within Balsam's worker.py
+def modify_Balsam_JobEnv():
+    # If Balsam detects that the system on which it is running contains the string
+    #   'cc' in it's hostname, then it thinks it's on Cooley! Travis hostnames are
+    #   randomly generated and occasionally may contain that offending string. This
+    #   modifies Balsam's JobEnvironment class to not check for 'cc'.
     import balsam
 
-    print_lines = {"host": "        print('HOST TYPE: ', self.host_type)\n",
-                   "COOLEY": "        print('IN setup_COOLEY')\n",
-                   "DEFAULT": "        print('IN setup_DEFAULT')\n"}
+    bad_line = "        'COOLEY' : 'cooley cc'.split()\n"
+    new_line = "        'COOLEY' : 'cooley'.split()\n"
 
-    host_prior_lines = ["        self.host_type = JobEnv.host_type\n",
-                        "        self.host_type = host_type\n"]
+    jobenv_file = 'JobEnvironment.py'
+    balsam_path = os.path.dirname(balsam.__file__) + '/service/schedulers'
+    balsam_jobenv_path = os.path.join(balsam_path, jobenv_file)
 
-    setup_prior_lines = ["    def setup_COOLEY(self):\n",
-                         "    def setup_DEFAULT(self):\n"]
-
-    workerfile = 'worker.py'
-    balsam_path = os.path.dirname(balsam.__file__) + '/launcher'
-    balsam_worker_path = os.path.join(balsam_path, workerfile)
-
-    with open(balsam_worker_path, 'r') as f:
+    with open(balsam_jobenv_path, 'r') as f:
         lines = f.readlines()
 
-    newlines = []
-    for line in lines:
-        if line in print_lines.values():
-            continue
-        newlines.append(line)               # Line of code from prior
-        if line in host_prior_lines:        #
-            newlines.append(print_lines['host'])
-        elif line == setup_prior_lines[0]:
-            newlines.append(print_lines['COOLEY'])
-        elif line == setup_prior_lines[1]:
-            newlines.append(print_lines['DEFAULT'])
+    for i in range(len(lines)):
+        if lines[i] == bad_line:
+            lines[i] = new_line
 
-    with open(balsam_worker_path, 'w') as f:
-        for line in newlines:
+    with open(balsam_jobenv_path, 'w') as f:
+        for line in lines:
             f.write(line)

From 85b9d564b451f03cd69a9960fb9a88997ff1fbe2 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 13 Sep 2019 11:56:59 -0500
Subject: [PATCH 254/644] More coverage of persistent_aposmm

---
 libensemble/gen_funcs/persistent_aposmm.py    | 43 ++++++++-----------
 .../test_6-hump_camel_persistent_aposmm_4.py  |  5 ++-
 2 files changed, 21 insertions(+), 27 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 407694fa1..228f97f71 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -7,7 +7,6 @@
 __all__ = ['initialize_APOSMM', 'decide_where_to_start_localopt', 'update_history_dist']
 
 import sys
-import traceback
 import numpy as np
 from scipy.spatial.distance import cdist
 from scipy import optimize as sp_opt
@@ -280,11 +279,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
         send_mgr_worker_msg(comm, local_H[new_inds_to_send_mgr + new_opt_inds_to_send_mgr][[i[0] for i in gen_specs['out']]])
 
-    # for local_opter in local_opters:
-    #     if local_opter.is_running:
-    #         raise RuntimeError("[Parent]: Atleast one child process is still active, even after"
-    #                            " killing all the children.")
-
     return local_H, persis_info, tag
 
 
@@ -1012,25 +1006,24 @@ def clean_up_and_stop(local_H, local_opters, run_order):
           local_H[np.where(local_H['local_min'])]['x'], flush=True)
 
     for i, p in local_opters.items():
-        if p.is_running:
-            p.destroy(local_H['x_on_cube'][run_order[i][-1]])
-
-
-def display_exception(e):
-    print(e.__doc__)
-    print(e.args)
-    _, _, tb = sys.exc_info()
-    traceback.print_tb(tb)  # Fixed format
-    tb_info = traceback.extract_tb(tb)
-    filename, line, func, text = tb_info[-1]
-    print('An error occurred on line {} of function {} with statement {}'.format(line, func, text))
-
-    # PETSc/TAO errors are printed in the following manner:
-    if hasattr(e, '_traceback_'):
-        print('The error was:')
-        for i in e._traceback_:
-            print(i)
-    sys.stdout.flush()
+        p.destroy(local_H['x_on_cube'][run_order[i][-1]])
+
+
+# def display_exception(e):
+#     print(e.__doc__)
+#     print(e.args)
+#     _, _, tb = sys.exc_info()
+#     traceback.print_tb(tb)  # Fixed format
+#     tb_info = traceback.extract_tb(tb)
+#     filename, line, func, text = tb_info[-1]
+#     print('An error occurred on line {} of function {} with statement {}'.format(line, func, text))
+
+#     # PETSc/TAO errors are printed in the following manner:
+#     if hasattr(e, '_traceback_'):
+#         print('The error was:')
+#         for i in e._traceback_:
+#             print(i)
+#     sys.stdout.flush()
 
 
 # if __name__ == "__main__":
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
index e054031a5..995d266f3 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
@@ -19,7 +19,6 @@
 
 # Import libEnsemble items for this test
 from libensemble.libE import libE
-from math import gamma, pi, sqrt
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
 from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
@@ -50,9 +49,11 @@
              'initial_sample_size': 100,
              'sample_points': np.round(minima, 1),
              'localopt_method': 'scipy_Nelder-Mead',
-             'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
              'fatol': 1e-5,
              'xatol': 1e-5,
+             'nu': 1e-8,
+             'mu': 1e-8,
+             'lhs_divisions': 5,
              'num_active_gens': 1,
              'dist_to_bound_multiple': 0.5,
              'max_active_runs': 6,

From d39e2e5bbfb832a9a293673e9b219c11340ce1fa Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 13 Sep 2019 11:58:58 -0500
Subject: [PATCH 255/644] bump up exit criteria

---
 libensemble/tests/regression_tests/script_test_balsam_hworld.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/regression_tests/script_test_balsam_hworld.py b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
index 16772441b..ee6cc5609 100644
--- a/libensemble/tests/regression_tests/script_test_balsam_hworld.py
+++ b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
@@ -56,7 +56,7 @@ def build_simfunc():
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
-exit_criteria = {'elapsed_wallclock_time': 30}
+exit_criteria = {'elapsed_wallclock_time': 35}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria,

From e935b830428c46a0ab21f4f502d23ebf449eda3b Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 13 Sep 2019 12:29:25 -0500
Subject: [PATCH 256/644] tries modifying hostname within travis.yml

---
 .travis.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.travis.yml b/.travis.yml
index b1cee2631..be0832a1e 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -27,6 +27,9 @@ matrix:
 services:
     - postgresql
 
+addons:
+  hostname: libensemble-travis
+
 # matrix:
 #  allow_failures:
 #    - env: MPI=openmpi

From 34cd68148a078e3d6b24bbb7b5a3d2253bfc4610 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 13 Sep 2019 12:51:09 -0500
Subject: [PATCH 257/644] Adjusting tests

---
 .../test_6-hump_camel_persistent_aposmm_4.py                 | 5 ++---
 .../regression_tests/test_chwirut_pounders_persistent.py     | 1 +
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
index 995d266f3..f6e9bf0b3 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
@@ -53,9 +53,8 @@
              'xatol': 1e-5,
              'nu': 1e-8,
              'mu': 1e-8,
-             'lhs_divisions': 5,
              'num_active_gens': 1,
-             'dist_to_bound_multiple': 0.5,
+             'dist_to_bound_multiple': 0.01,
              'max_active_runs': 6,
              'lb': np.array([-3, -2]),
              'ub': np.array([3, 2])}
@@ -64,7 +63,7 @@
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
-exit_criteria = {'sim_max': 1000}
+exit_criteria = {'sim_max': 2000}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
index 4bb3bfea6..ca5ea9b5f 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
@@ -54,6 +54,7 @@
              'gatol': 1e-6,
              'num_active_gens': 1,
              'dist_to_bound_multiple': 0.5,
+             'lhs_divisions': 5,
              'components': m,
              'lb': (-2-np.pi/10)*np.ones(n),
              'ub': 2*np.ones(n)}

From fde0b038bb26bbf3f2acdeed3e024fbcf611f057 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 13 Sep 2019 13:59:09 -0500
Subject: [PATCH 258/644] removing travis hostname. seems to break postgresql

---
 .travis.yml | 2 --
 1 file changed, 2 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index be0832a1e..e5e1aaa35 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -27,8 +27,6 @@ matrix:
 services:
     - postgresql
 
-addons:
-  hostname: libensemble-travis
 
 # matrix:
 #  allow_failures:

From 8000fb11e765fc4e1961f8df65df0db747c31f97 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 13 Sep 2019 14:04:26 -0500
Subject: [PATCH 259/644] attempting to rearrange hostname

---
 .travis.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.travis.yml b/.travis.yml
index e5e1aaa35..ed989c370 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -24,6 +24,9 @@ matrix:
       language: generic
       python: 3
 
+addons:
+  hostname: libensemble-travis
+
 services:
     - postgresql
 

From 5a14d5629cc00740f747f8e100a4a5848c52aa09 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 13 Sep 2019 14:11:26 -0500
Subject: [PATCH 260/644] actually removes hostname line

---
 .travis.yml | 2 --
 1 file changed, 2 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index ed989c370..23e8340b3 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -24,8 +24,6 @@ matrix:
       language: generic
       python: 3
 
-addons:
-  hostname: libensemble-travis
 
 services:
     - postgresql

From 8c037797c0f4177b47b393bd6003d2461c94f47a Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Mon, 16 Sep 2019 08:39:39 -0500
Subject: [PATCH 261/644] Removing blank lines

---
 .travis.yml | 2 --
 1 file changed, 2 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 23e8340b3..b1cee2631 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -24,11 +24,9 @@ matrix:
       language: generic
       python: 3
 
-
 services:
     - postgresql
 
-
 # matrix:
 #  allow_failures:
 #    - env: MPI=openmpi

From e8d4470ca1f571851f3b6620a56df41a16ee1af1 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Mon, 16 Sep 2019 11:39:35 -0500
Subject: [PATCH 262/644] Removing c_flag or single_component from persistent
 aposmm. If wanted, this functionality should come from the alloc func, not
 the generator.

---
 libensemble/gen_funcs/persistent_aposmm.py | 62 ++++++----------------
 1 file changed, 15 insertions(+), 47 deletions(-)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 228f97f71..9914ce761 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -61,7 +61,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     and optionally
 
     - ``'priority' [float]``: Value quantifying a point's desirability
-    - ``'f_i' [float]``: Value of ith objective component (if single_component)
     - ``'fvec' [m floats]``: All objective components (if calculated together)
     - ``'obj_component' [int]``: Index corresponding to value in ``'f_i``'
     - ``'pt_id' [int]``: Identify the point (useful when evaluating different
@@ -105,8 +104,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
       points must satisfy
     - ``'nu' [float]``: Distance from identified minima that all starting
       points must satisfy
-    - ``'single_component_at_a_time' [bool]``: True if single objective
-      components will be evaluated at a time
     - ``'rk_const' [float]``: Multiplier in front of the r_k value
     - ``'max_active_runs' [int]``: Bound on number of runs APOSMM is advancing
 
@@ -156,9 +153,6 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     Description of intermediate variables in aposmm_logic:
 
     n:                domain dimension
-    c_flag:           True if giving libEnsemble individual components of fvec
-                      to evaluate. (Note if c_flag is True, APOSMM will use
-                      only the component to store the function value f)
     n_s:              the number of complete evaluations of sampled points
     updated_inds:     indices of H that have been updated (and so all their
                       information must be sent back to libE manager to update)
@@ -189,7 +183,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     persis_info['old_runs']: Sequence of indices of points in finished runs
 
     """
-    n, n_s, c_flag, rk_const, ld, mu, nu, comm, local_H = initialize_APOSMM(H, gen_specs, libE_info)
+    n, n_s, rk_const, ld, mu, nu, comm, local_H = initialize_APOSMM(H, gen_specs, libE_info)
 
     # Initialize stuff for localopt children
     local_opters = {}
@@ -209,7 +203,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     # Send our initial sample. We don't need to check that n_s is large enough:
     # the alloc_func only returns when the initial sample has function values.
     persis_info = add_k_sample_points_to_local_H(gen_specs['initial_sample_size'], gen_specs,
-                                                 persis_info, n, c_flag, comm, local_H,
+                                                 persis_info, n, comm, local_H,
                                                  sim_id_to_child_indices)
     send_mgr_worker_msg(comm, local_H[:gen_specs['initial_sample_size']][[i[0] for i in gen_specs['out']]])
 
@@ -221,7 +215,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
             clean_up_and_stop(local_H, local_opters, run_order)
             break
 
-        n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in)
+        n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, Work, calc_in)
 
         new_opt_inds_to_send_mgr = []
         new_inds_to_send_mgr = []
@@ -236,7 +230,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                         new_opt_inds_to_send_mgr.append(opt_ind)
                         local_opters.pop(child_idx)
                     else:
-                        add_to_local_H(local_H, x_new, gen_specs, c_flag, local_flag=1, on_cube=True)
+                        add_to_local_H(local_H, x_new, gen_specs, local_flag=1, on_cube=True)
                         new_inds_to_send_mgr.append(len(local_H)-1)
 
                         run_order[child_idx].append(local_H[-1]['sim_id'])
@@ -260,7 +254,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                 x_new = local_opter.iterate(local_H[ind][fields_to_pass])  # Assuming the second point can't be ruled optimal
 
-                add_to_local_H(local_H, x_new, gen_specs, c_flag, local_flag=1, on_cube=True)
+                add_to_local_H(local_H, x_new, gen_specs, local_flag=1, on_cube=True)
                 new_inds_to_send_mgr.append(len(local_H)-1)
 
                 run_order[total_runs] = [ind, local_H[-1]['sim_id']]
@@ -274,7 +268,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
         if len(new_inds_to_send_mgr) == 0:
             persis_info = add_k_sample_points_to_local_H(1, gen_specs, persis_info, n,
-                                                         c_flag, comm, local_H, sim_id_to_child_indices)
+                                                         comm, local_H, sim_id_to_child_indices)
             new_inds_to_send_mgr.append(len(local_H)-1)
 
         send_mgr_worker_msg(comm, local_H[new_inds_to_send_mgr + new_opt_inds_to_send_mgr][[i[0] for i in gen_specs['out']]])
@@ -620,7 +614,7 @@ def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read, parent_can_read
 # }}}
 
 
-def update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, calc_in):
+def update_local_H_after_receiving(local_H, n, n_s, gen_specs, Work, calc_in):
 
     for name in calc_in.dtype.names:
         local_H[name][Work['libE_info']['H_rows']] = calc_in[name]
@@ -629,12 +623,12 @@ def update_local_H_after_receiving(local_H, n, n_s, gen_specs, c_flag, Work, cal
     n_s += np.sum(~local_H[Work['libE_info']['H_rows']]['local_pt'])
 
     # dist -> distance
-    update_history_dist(local_H, n, gen_specs, c_flag)
+    update_history_dist(local_H, n, gen_specs)
 
     return n_s
 
 
-def add_to_local_H(local_H, pts, gen_specs, c_flag, local_flag=0, sorted_run_inds=[], run=[], on_cube=True):
+def add_to_local_H(local_H, pts, gen_specs, local_flag=0, sorted_run_inds=[], run=[], on_cube=True):
     """
     Adds points to O, the numpy structured array to be sent back to the manager
     """
@@ -644,12 +638,6 @@ def add_to_local_H(local_H, pts, gen_specs, c_flag, local_flag=0, sorted_run_ind
 
     ub = gen_specs['ub']
     lb = gen_specs['lb']
-    if c_flag:
-        m = gen_specs['components']
-
-        assert len_local_H % m == 0, "Number of points in local_H not congruent to 0 mod 'components'"
-        pt_ids = np.sort(np.tile(np.arange((len_local_H)/m, (len_local_H)/m+len(pts)), (1, m)))
-        pts = np.tile(pts, (m, 1))
 
     num_pts = len(pts)
 
@@ -671,17 +659,13 @@ def add_to_local_H(local_H, pts, gen_specs, c_flag, local_flag=0, sorted_run_ind
     local_H['ind_of_better_l'][-num_pts:] = -1
     local_H['ind_of_better_s'][-num_pts:] = -1
 
-    if c_flag:
-        local_H['obj_component'][-num_pts:] = np.tile(range(0, m), (1, num_pts//m))
-        local_H['pt_id'][-num_pts:] = pt_ids
-
     if local_flag:
         local_H['num_active_runs'][-num_pts] += 1
     else:
         local_H['priority'][-num_pts:] = 1
 
 
-def update_history_dist(H, n, gen_specs, c_flag):
+def update_history_dist(H, n, gen_specs):
     """
     Updates distances/indices after new points that have been evaluated.
 
@@ -691,15 +675,7 @@ def update_history_dist(H, n, gen_specs, c_flag):
 
     new_inds = np.where(~H['known_to_aposmm'])[0]
 
-    if c_flag:
-        for v in np.unique(H['pt_id'][new_inds]):
-            inds = H['pt_id'] == v
-            H['f'][inds] = np.inf
-            H['f'][np.where(inds)[0][0]] = gen_specs['combine_component_func'](H['f_i'][inds])
-
-        p = np.logical_and.reduce((H['returned'], H['obj_component'] == 0, ~np.isnan(H['f'])))
-    else:
-        p = np.logical_and.reduce((H['returned'], ~np.isnan(H['f'])))
+    p = np.logical_and.reduce((H['returned'], ~np.isnan(H['f'])))
 
     for new_ind in new_inds:
         # Loop over new returned points and update their distances
@@ -924,13 +900,6 @@ def initialize_APOSMM(H, gen_specs, libE_info):
 
     n_s = 0
 
-    if gen_specs.get('single_component_at_a_time'):
-        assert gen_specs['batch_mode'], ("Must be in batch mode when using "
-                                         "'single_component_at_a_time'")
-        c_flag = True
-    else:
-        c_flag = False
-
     if 'rk_const' in gen_specs:
         rk_c = gen_specs['rk_const']
     else:
@@ -971,7 +940,6 @@ def initialize_APOSMM(H, gen_specs, libE_info):
                       ('sim_id', int),
                       ('paused', bool),
                       ('returned', bool),
-                      ('pt_id', int),  # Identify the same point evaluated by different sim_f's or components
                       ]
 
     if 'components' in gen_specs:
@@ -979,22 +947,22 @@ def initialize_APOSMM(H, gen_specs, libE_info):
 
     local_H = np.empty(0, dtype=local_H_fields)
 
-    return n, n_s, c_flag, rk_c, ld, mu, nu, comm, local_H
+    return n, n_s, rk_c, ld, mu, nu, comm, local_H
 
 
-def add_k_sample_points_to_local_H(k, gen_specs, persis_info, n, c_flag, comm, local_H, sim_id_to_child_indices):
+def add_k_sample_points_to_local_H(k, gen_specs, persis_info, n, comm, local_H, sim_id_to_child_indices):
 
     if 'sample_points' in gen_specs:
         v = np.sum(~local_H['local_pt'])  # Number of sample points so far
         sampled_points = gen_specs['sample_points'][v:v+k]
         on_cube = False  # Assume points are on original domain, not unit cube
         if len(sampled_points):
-            add_to_local_H(local_H, sampled_points, gen_specs, c_flag, on_cube=on_cube)
+            add_to_local_H(local_H, sampled_points, gen_specs, on_cube=on_cube)
         k = k-len(sampled_points)
 
     if k > 0:
         sampled_points = persis_info['rand_stream'].uniform(0, 1, (k, n))
-        add_to_local_H(local_H, sampled_points, gen_specs, c_flag, on_cube=True)
+        add_to_local_H(local_H, sampled_points, gen_specs, on_cube=True)
 
     return persis_info
 

From cbdc8c97982a3243f90a0fd3dc531b889d1fdd61 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Mon, 23 Sep 2019 16:14:06 -0500
Subject: [PATCH 263/644] Add OpenMP for CPU and GPU/accelerator to the forces
 test case

---
 .../tests/scaling_tests/forces/forces.c       | 74 ++++++++++++++++---
 1 file changed, 62 insertions(+), 12 deletions(-)

diff --git a/libensemble/tests/scaling_tests/forces/forces.c b/libensemble/tests/scaling_tests/forces/forces.c
index 1aebfa44b..7b99b74ca 100755
--- a/libensemble/tests/scaling_tests/forces/forces.c
+++ b/libensemble/tests/scaling_tests/forces/forces.c
@@ -8,6 +8,9 @@
     Each rank computes forces for a subset of particles.
     Particle force arrays are allreduced across ranks.
     
+    Sept 2019: 
+    Added OpenMP options for CPU and GPU. Toggle in forces_naive function.
+    
     Run executable on N procs:
     
     mpirun -np N ./forces.x <NUM_PARTICLES> <NUM_TIMESTEPS>
@@ -18,8 +21,9 @@
 #include <stdlib.h>
 #include <stdio.h>
 #include <math.h>
-#include <time.h>
+#include <sys/time.h>
 #include <mpi.h>
+#include <omp.h>
 
 #define min(a,b) \
   ({ __typeof__ (a) _a = (a); \
@@ -29,14 +33,38 @@
 // Flags 0 or 1
 #define PRINT_PARTICLE_DECOMP 0
 #define PRINT_ALL_PARTICLES 0
+#define CHECK_THREADS 0
 
 static FILE* stat_fp;
 
+// Return elapsed wall clock time from start/end timevals
+double elapsed(struct timeval *tv1, struct timeval *tv2) {
+    return (double)(tv2->tv_usec - tv1->tv_usec) / 1000000 
+    + (double)(tv2->tv_sec - tv1->tv_sec);  
+}
+
+// Print from each thread.
+int check_threads(int rank) {
+    int tid, nthreads;
+
+    #pragma omp parallel private(tid,nthreads)
+    {
+        #if defined(_OPENMP)
+            nthreads = omp_get_num_threads();
+            tid = omp_get_thread_num();
+            printf("Rank: %d:   ThreadID: %d    Num threads: %d\n",rank,tid,nthreads);
+        #else
+            printf("Rank: %d: OpenMP is disabled\n",rank);
+        #endif
+    }
+    return 0;
+}
+
 typedef struct particle {
     double p[3]; // Particle position
     double f[3]; // Particle force
     double q;    // Particle charge
-} particle;  
+}__attribute__((__packed__)) particle;  
 
 
 // Seed RNG
@@ -92,7 +120,18 @@ double forces_naive(int n, int lower, int upper, particle* parr) {
     double ret = 0.0;
     double dx, dy, dz, r, force;
 
-    for(i=lower; i<upper; i++) {          
+    // For GPU/Accelerators
+    /*
+    #pragma omp target teams distribute parallel for \
+                map(to: lower,upper,n) map(tofrom: parr[0:n]) \
+                reduction(+: ret) //thread_limit(128) //*/
+                
+    // For CPU
+    //*
+    #pragma omp parallel for default(none) shared(n,lower,upper,parr) \
+                             private(i,j,dx,dy,dz,r,force) \
+                             reduction(+:ret)  //*/                
+    for(i=lower; i<upper; i++) {
         for(j=0; j<n; j++){
             if (i==j) {
                 continue;
@@ -102,7 +141,7 @@ double forces_naive(int n, int lower, int upper, particle* parr) {
             dz = parr[i].p[2] - parr[j].p[2];
             r = sqrt(dx * dx + dy * dy + dz * dz);
 
-            //ret += parr[i].q * parr[j].q / r;
+            //force = parr[i].q * parr[j].q / r;
             force = parr[i].q * parr[j].q / (r*r);
 
             parr[i].f[0] += dx * force;
@@ -284,7 +323,11 @@ int main(int argc, char **argv) {
     int ierr, rank, num_procs, k, m, p_lower, p_upper, local_n;
     int step;
     double compute_forces_time, comms_time, total_time;
-    clock_t start, compute_start, comms_start;
+//     clock_t start, compute_start, comms_start;
+    struct timeval tstart, tend;
+    struct timeval compute_start, compute_end;
+    struct timeval comms_start, comms_end;
+    
     double local_en, total_en;
     double step_survival_rate;
     int badrun = 0;
@@ -322,6 +365,10 @@ int main(int argc, char **argv) {
         printf("Random seed: %d\n",rand_seed);
     }
     
+    if (CHECK_THREADS) {
+        check_threads(rank);
+    }
+
     k = num_particles / num_procs;
     m = num_particles % num_procs; //Remainder = no. procs with extra particle
     p_lower = rank * k + min(rank, m);
@@ -339,20 +386,21 @@ int main(int argc, char **argv) {
         open_stat_file();
     }
 
-    start = clock();    
+    gettimeofday(&tstart, NULL);
     for (step=0; step<num_steps; step++) {
         
-        compute_start = clock();
+        gettimeofday(&compute_start, NULL);
         
         init_forces(0, num_particles, parr); // Whole array
         
         local_en = forces_naive(num_particles, p_lower, p_upper, parr);
         //local_en = forces_eqopp(num_particles, p_lower, p_upper, parr);
-        
-        compute_forces_time = (double)(clock() - compute_start)/CLOCKS_PER_SEC;
+
+        gettimeofday(&compute_end, NULL);
+        compute_forces_time = elapsed(&compute_start, &compute_end);
         
         // Note: Will need to add barrier to get pure comms time
-        comms_start = clock();
+        gettimeofday(&comms_start, NULL);
         
         // Now allreduce forces and update particle positions on master
         
@@ -362,7 +410,8 @@ int main(int argc, char **argv) {
         // Scalar reduce energy
         MPI_Allreduce(&local_en, &total_en, 1, MPI_DOUBLE, MPI_SUM, MPI_COMM_WORLD);
 
-        comms_time = (double)(clock() - comms_start)/CLOCKS_PER_SEC;
+        gettimeofday(&comms_end, NULL);
+        comms_time = elapsed(&comms_start, &comms_end);
         
         // Update positions globally (each rank replicates)
         move_particles(0, num_particles, parr);
@@ -385,7 +434,8 @@ int main(int argc, char **argv) {
     
     fflush(stdout);
     MPI_Barrier(MPI_COMM_WORLD);
-    total_time = (double)(clock() - start)/CLOCKS_PER_SEC;
+    gettimeofday(&tend, NULL);
+    total_time = elapsed(&tstart, &tend);
     
     if (rank == 0) {
         printf("\nFinal total %f after total time of %.3f seconds.",total_en, total_time);

From 42b137c7643a7c480fe72c03ef3515b4865ae636 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Mon, 23 Sep 2019 16:19:38 -0500
Subject: [PATCH 264/644] Add mini_forces non-MPI standalone code for
 experimentation

---
 .../forces/mini_forces/mini_forces.c          | 179 ++++++++++++++++++
 1 file changed, 179 insertions(+)
 create mode 100644 libensemble/tests/scaling_tests/forces/mini_forces/mini_forces.c

diff --git a/libensemble/tests/scaling_tests/forces/mini_forces/mini_forces.c b/libensemble/tests/scaling_tests/forces/mini_forces/mini_forces.c
new file mode 100644
index 000000000..0c9c7729a
--- /dev/null
+++ b/libensemble/tests/scaling_tests/forces/mini_forces/mini_forces.c
@@ -0,0 +1,179 @@
+/* --------------------------------------------------------------------
+    Non-MPI, Single Step, Electostatics Code Example
+    
+    This is a complete working example to test threading/vectorization
+    without MPI or other non-trivial features.
+    
+    E.g: gcc build and run on 2 threads on CPU:
+    
+    gcc -O3 -fopenmp -o serial_forces.x serial_forces.c -lm
+    export OMP_NUM_THREADS=2
+    ./mini_forces.x
+    
+    E.g: xlc build and run on GPU:
+    
+    # First toggle #omp pragma line to target in forces_naive function.
+    xlc_r -O3 -qsmp=omp -qoffload -o mini_forces_xlc_gpu.x mini_forces.c
+    ./mini_forces.x
+    
+    Functionality:
+    Particles position and charge are initiated by a random stream.
+    Computes forces for all particles. Note: This version uses
+    parallel arrays to store the data (SoA).
+    
+    OpenMP options for CPU and GPU. Toggle in forces_naive function.
+    
+    Author: S Hudson.
+-------------------------------------------------------------------- */
+#include <stdlib.h>
+#include <stdio.h>
+#include <math.h>
+#include <sys/time.h>
+#include <omp.h>
+
+#define CHECK_THREADS 1
+#define NUM_PARTICLES 6000
+
+// Seed RNG
+int seed_rand(int seed) {
+    srand(seed);    
+    return 0;
+}
+
+// Return a random number from a persistent stream
+double get_rand() {
+    double randnum;              
+    randnum = (double)rand()/(double)(RAND_MAX + 1.0); //[0,1)    
+    return randnum;
+}
+
+
+// Particles start at random locations in 10x10x10 cube
+int build_system(int n, double* x, double* y, double* z, double* fx, double* fy, double* fz, double* q) {
+    int q_range_low = -10;
+    int q_range_high = 10;
+    double extent = 10.0;
+    int i;
+    
+    for(i=0; i<n; i++) {
+        x[i] = get_rand()*extent;
+        y[i] = get_rand()*extent;
+        z[i] = get_rand()*extent;
+        fx[i] = 0.0;
+        fy[i] = 0.0;
+        fz[i] = 0.0;
+        q[i] = ((q_range_high+1)-q_range_low)*get_rand() + q_range_low;;
+    }
+    return 0;
+}
+
+
+// Initialize forces to zero for all particles
+int init_forces(int lower, int upper, double* fx, double* fy, double* fz) {
+    int i;
+    for(i=lower; i<upper; i++) {
+        fx[i] = 0.0;
+        fy[i] = 0.0;
+        fz[i] = 0.0;       
+    }
+    return 0;
+}
+
+
+// Print from each thread.
+int check_threads() {
+    int tid, nthreads;
+
+    #pragma omp parallel private(tid,nthreads)
+    {
+        #if defined(_OPENMP)
+            nthreads = omp_get_num_threads();
+            tid = omp_get_thread_num();
+            printf("ThreadID: %d    Num threads: %d\n",tid,nthreads);
+        #else
+            printf("OpenMP is disabled\n");
+        #endif
+    }
+    return 0;
+}
+
+
+// Electostatics pairwise forces kernel (O(N^2))
+double forces_naive(int n,  double* x, double* y, double* z, double* fx, double* fy, double* fz, double* q) {
+    int i,j;
+    double ret = 0.0;
+    double dx, dy, dz, r, force;
+    struct timeval tv1, tv2;
+
+    gettimeofday(&tv1, NULL);
+
+    // For GPU/Accelerators
+    /*
+    #pragma omp target teams distribute parallel for map(to: n) \
+                       map(tofrom: x[:n],y[:n],z[:n],fx[:n],fy[:n],fz[:n],q[:n]) \
+                       reduction(+:ret) //thread_limit(128) //*/
+
+    // For CPU
+    //*
+    #pragma omp parallel for default(none) shared(n,x,y,z,fx,fy,fz,q) \
+                             private(i,j,dx,dy,dz,r,force) \
+                             reduction(+:ret)  //*/
+    for(i=0; i<n; i++) {
+        #pragma omp simd private(dx,dy,dz,r,force) reduction(+:fx[i],fy[i],fz[i],ret) // Enable vectorization
+        for(j=0; j<n; j++){
+            if (i==j) {
+                continue;
+            }
+            dx = x[i] - x[j];
+            dy = y[i] - y[j];
+            dz = z[i] - z[j];
+            r = sqrt(dx * dx + dy * dy + dz * dz);
+
+            force = q[i] * q[j] / (r*r);
+            fx[i] += dx * force;
+            fy[i] += dy * force;
+            fz[i] += dz * force;
+            
+            ret += 0.5 * force;
+        }
+    }
+
+    gettimeofday(&tv2, NULL);
+    printf ("Time taken for loop (Wallclock) = %f seconds\n",
+         (double) (tv2.tv_usec - tv1.tv_usec) / 1000000 +
+         (double) (tv2.tv_sec - tv1.tv_sec));
+   
+    return ret;
+}
+
+
+int main(int argc, char **argv) {
+    
+    int num_particles = NUM_PARTICLES;
+    double local_en;        
+    double *pos_x   = malloc(num_particles * sizeof(double));
+    double *pos_y   = malloc(num_particles * sizeof(double));
+    double *pos_z   = malloc(num_particles * sizeof(double));
+    double *force_x = malloc(num_particles * sizeof(double));
+    double *force_y = malloc(num_particles * sizeof(double));
+    double *force_z = malloc(num_particles * sizeof(double));
+    double *charge  = malloc(num_particles * sizeof(double));
+    
+    if (CHECK_THREADS) {
+        check_threads();
+    }
+    
+    build_system(num_particles, pos_x, pos_y, pos_z, force_x, force_y, force_z, charge);
+    init_forces(0, num_particles, force_x, force_y, force_z);
+    local_en = forces_naive(num_particles, pos_x, pos_y, pos_z, force_x, force_y, force_z, charge);
+    printf("energy is %f \n",local_en);
+
+    free(pos_x  );
+    free(pos_y  );
+    free(pos_z  );
+    free(force_x);
+    free(force_y);
+    free(force_z);
+    free(charge );
+    return 0;
+}

From b9d79a681093b7ae38fab75cf9977787680d90c6 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Mon, 23 Sep 2019 21:08:26 -0500
Subject: [PATCH 265/644] Add build variations to build_forces.sh

---
 .../scaling_tests/forces/build_forces.sh      | 31 ++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/libensemble/tests/scaling_tests/forces/build_forces.sh b/libensemble/tests/scaling_tests/forces/build_forces.sh
index d16443292..564e42c5a 100755
--- a/libensemble/tests/scaling_tests/forces/build_forces.sh
+++ b/libensemble/tests/scaling_tests/forces/build_forces.sh
@@ -1,10 +1,39 @@
 #!/bin/bash
 
+# Building flat MPI
+
 # GCC
 mpicc -O3 -o forces.x forces.c -lm
 
 # Intel
-# mpicc -O3 -o forces.x forces.c
+# mpiicc -O3 -o forces.x forces.c
 
 # Cray
 # cc -O3 -o forces.x forces.c
+
+# ----------------------------------------------
+
+# Building with OpenMP for CPU
+
+# GCC
+# mpicc -O3 -fopenmp -o forces.x forces.c -lm
+
+# Intel
+# mpiicc -O3 -qopenmp -o forces.x forces.c
+
+# Cray / Intel (for CCE OpenMP is recognized by default)
+# cc -O3 -qopenmp -o forces.x forces.c
+
+# xl
+# xlc_r -O3 -qsmp=omp -o forces.x forces.c
+
+# ----------------------------------------------
+
+# Building with OpenMP for target device (e.g. GPU)
+# Need to toggle to OpenMP target directive in forces.c.
+
+# xl
+# xlc_r -O3 -qsmp=omp -qoffload -o forces.x forces.c
+
+# IRIS node (Intel Gen9 GPU)
+# env MPICH_CC=icx mpigcc -g -fiopenmp -fopenmp-targets=spir64 -o forces.x forces.c

From b67266d28efa2e9d0ab9554d6193278e48ef9be1 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 24 Sep 2019 10:34:41 -0500
Subject: [PATCH 266/644] Trying updating SDK version

---
 .travis.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 4cc24d54c..0dd56154b 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -61,8 +61,8 @@ before_install:
 
 install:
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
-        wget https://github.com/phracker/MacOSX-SDKs/releases/download/10.13/MacOSX10.13.sdk.tar.xz;
-        mkdir ../sdk; tar xf MacOSX10.13.sdk.tar.xz -C ../sdk;
+        wget https://github.com/phracker/MacOSX-SDKs/releases/download/10.14-beta4/MacOSX10.14.sdk.tar.xz;
+        mkdir ../sdk; tar xf MacOSX10.14.sdk.tar.xz -C ../sdk;
         COMPILERS=clang_osx-64;
         MUMPS=mumps-mpi=5.1.2=haf446c3_1007;
     else

From 516b6a0df055a0811427cbdacd992971bdc792ad Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 24 Sep 2019 11:10:26 -0500
Subject: [PATCH 267/644] update conda_build_sysroot

---
 .travis.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index 0dd56154b..f47236d21 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -93,7 +93,7 @@ before_script:
   - ulimit -Sn 10000
   # Set conda compilers to use new SDK instead of Travis default.
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
-        echo "export CONDA_BUILD_SYSROOT=/Users/travis/build/Libensemble/sdk/MacOSX10.13.sdk" > setenv.sh;
+        echo "export CONDA_BUILD_SYSROOT=/Users/travis/build/Libensemble/sdk/MacOSX10.14.sdk" > setenv.sh;
         source setenv.sh;
     fi
 

From 314137920a5a56745cd23e6c1d7c8e1da078c5f0 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 24 Sep 2019 11:19:35 -0500
Subject: [PATCH 268/644] set conda build sysroot definition earlier

---
 .travis.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.travis.yml b/.travis.yml
index f47236d21..94bca1b6e 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -65,6 +65,8 @@ install:
         mkdir ../sdk; tar xf MacOSX10.14.sdk.tar.xz -C ../sdk;
         COMPILERS=clang_osx-64;
         MUMPS=mumps-mpi=5.1.2=haf446c3_1007;
+        echo "export CONDA_BUILD_SYSROOT=/Users/travis/build/Libensemble/sdk/MacOSX10.14.sdk" > setenv.sh;
+        source setenv.sh;
     else
         COMPILERS=gcc_linux-64;
         MUMPS=mumps-mpi=5.1.2=h5bebb2f_1007;

From 788b5da2bf4fee303345d468cb8544bf6d202b25 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 24 Sep 2019 12:00:13 -0500
Subject: [PATCH 269/644] Attempt to force clang 8.0.1

---
 .travis.yml | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 94bca1b6e..27032df52 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -65,13 +65,12 @@ install:
         mkdir ../sdk; tar xf MacOSX10.14.sdk.tar.xz -C ../sdk;
         COMPILERS=clang_osx-64;
         MUMPS=mumps-mpi=5.1.2=haf446c3_1007;
-        echo "export CONDA_BUILD_SYSROOT=/Users/travis/build/Libensemble/sdk/MacOSX10.14.sdk" > setenv.sh;
-        source setenv.sh;
+        conda install clang=8.0.1
     else
         COMPILERS=gcc_linux-64;
         MUMPS=mumps-mpi=5.1.2=h5bebb2f_1007;
     fi
-  - conda install $COMPILERS
+  - conda install --no-update-dependencies $COMPILERS
   #S- conda install nlopt petsc4py petsc mpi4py scipy $MPI
   - conda install nlopt petsc4py petsc $MUMPS mpi4py scipy $MPI
   # pip install these as the conda installs downgrade pytest on python3.4

From 84fef2995fd127ab18241d56613866df270e6075 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 24 Sep 2019 12:10:20 -0500
Subject: [PATCH 270/644] fix clang 8.0.1 installation

---
 .travis.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 27032df52..2f9b7af15 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -65,12 +65,12 @@ install:
         mkdir ../sdk; tar xf MacOSX10.14.sdk.tar.xz -C ../sdk;
         COMPILERS=clang_osx-64;
         MUMPS=mumps-mpi=5.1.2=haf446c3_1007;
-        conda install clang=8.0.1
+        conda install clang=8.0.1;
     else
         COMPILERS=gcc_linux-64;
         MUMPS=mumps-mpi=5.1.2=h5bebb2f_1007;
     fi
-  - conda install --no-update-dependencies $COMPILERS
+  - conda install --freeze-installed $COMPILERS
   #S- conda install nlopt petsc4py petsc mpi4py scipy $MPI
   - conda install nlopt petsc4py petsc $MUMPS mpi4py scipy $MPI
   # pip install these as the conda installs downgrade pytest on python3.4

From 061a543464ea56163089a882846d663f93672c95 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 24 Sep 2019 14:22:55 -0500
Subject: [PATCH 271/644] add brew update/upgrade, try installing sdk header
 files

---
 .travis.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.travis.yml b/.travis.yml
index 2f9b7af15..10b3b526e 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -46,6 +46,8 @@ cache:
 before_install:
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
       wget https://repo.continuum.io/miniconda/Miniconda3-4.6.14-MacOSX-x86_64.sh -O miniconda.sh;
+      brew update && brew upgrade;
+      sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /
     else
       wget https://repo.continuum.io/miniconda/Miniconda3-4.6.14-Linux-x86_64.sh -O miniconda.sh;
     fi

From cd35b8df9a4c2ad63396b3e3f08149945381881f Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 24 Sep 2019 14:28:26 -0500
Subject: [PATCH 272/644] semicolon

---
 .travis.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index 10b3b526e..67c98b44b 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -47,7 +47,7 @@ before_install:
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
       wget https://repo.continuum.io/miniconda/Miniconda3-4.6.14-MacOSX-x86_64.sh -O miniconda.sh;
       brew update && brew upgrade;
-      sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /
+      sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /;
     else
       wget https://repo.continuum.io/miniconda/Miniconda3-4.6.14-Linux-x86_64.sh -O miniconda.sh;
     fi

From 59e8bf47092d1a44c52063bf5eef8575aac3a78f Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 24 Sep 2019 14:44:30 -0500
Subject: [PATCH 273/644] update miniconda, use recent clang

---
 .travis.yml | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 67c98b44b..7773de198 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -45,8 +45,7 @@ cache:
 # Setup Miniconda
 before_install:
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
-      wget https://repo.continuum.io/miniconda/Miniconda3-4.6.14-MacOSX-x86_64.sh -O miniconda.sh;
-      brew update && brew upgrade;
+      wget https://repo.continuum.io/miniconda/Miniconda3-4.7.10-MacOSX-x86_64.sh -O miniconda.sh;
       sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /;
     else
       wget https://repo.continuum.io/miniconda/Miniconda3-4.6.14-Linux-x86_64.sh -O miniconda.sh;
@@ -67,12 +66,12 @@ install:
         mkdir ../sdk; tar xf MacOSX10.14.sdk.tar.xz -C ../sdk;
         COMPILERS=clang_osx-64;
         MUMPS=mumps-mpi=5.1.2=haf446c3_1007;
-        conda install clang=8.0.1;
+        #conda install clang=8.0.1;
     else
         COMPILERS=gcc_linux-64;
         MUMPS=mumps-mpi=5.1.2=h5bebb2f_1007;
     fi
-  - conda install --freeze-installed $COMPILERS
+  - conda install $COMPILERS
   #S- conda install nlopt petsc4py petsc mpi4py scipy $MPI
   - conda install nlopt petsc4py petsc $MUMPS mpi4py scipy $MPI
   # pip install these as the conda installs downgrade pytest on python3.4

From a79821f601aa106e97470c57c59f337b19c42bc9 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 24 Sep 2019 14:47:18 -0500
Subject: [PATCH 274/644] trigger build?

---
 .travis.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index 7773de198..bc658a5f3 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -55,7 +55,7 @@ before_install:
   - hash -r
   - conda config --set always_yes yes --set changeps1 no
   #- conda update -q -y conda
-  - conda info -a # For debugging any issues with conda
+  - conda info -a # For debugging any issues with conda 
   - conda config --add channels conda-forge
   - conda create --yes --name condaenv python=$TRAVIS_PYTHON_VERSION
   - source activate condaenv

From 291a9fbdb435c76c03346579e57a3d8ec948443f Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 24 Sep 2019 14:52:20 -0500
Subject: [PATCH 275/644] valid yaml

---
 .travis.yml | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index bc658a5f3..5c67d7321 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -55,7 +55,7 @@ before_install:
   - hash -r
   - conda config --set always_yes yes --set changeps1 no
   #- conda update -q -y conda
-  - conda info -a # For debugging any issues with conda 
+  - conda info -a # For debugging any issues with conda
   - conda config --add channels conda-forge
   - conda create --yes --name condaenv python=$TRAVIS_PYTHON_VERSION
   - source activate condaenv
@@ -66,7 +66,6 @@ install:
         mkdir ../sdk; tar xf MacOSX10.14.sdk.tar.xz -C ../sdk;
         COMPILERS=clang_osx-64;
         MUMPS=mumps-mpi=5.1.2=haf446c3_1007;
-        #conda install clang=8.0.1;
     else
         COMPILERS=gcc_linux-64;
         MUMPS=mumps-mpi=5.1.2=h5bebb2f_1007;

From 3a5b940df494666413432bc5876c636228b26e00 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 24 Sep 2019 15:05:39 -0500
Subject: [PATCH 276/644] try not using sdk

---
 .travis.yml | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 5c67d7321..79412fee7 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -62,14 +62,14 @@ before_install:
 
 install:
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
-        wget https://github.com/phracker/MacOSX-SDKs/releases/download/10.14-beta4/MacOSX10.14.sdk.tar.xz;
-        mkdir ../sdk; tar xf MacOSX10.14.sdk.tar.xz -C ../sdk;
         COMPILERS=clang_osx-64;
         MUMPS=mumps-mpi=5.1.2=haf446c3_1007;
     else
         COMPILERS=gcc_linux-64;
         MUMPS=mumps-mpi=5.1.2=h5bebb2f_1007;
     fi
+    # wget https://github.com/phracker/MacOSX-SDKs/releases/download/10.14-beta4/MacOSX10.14.sdk.tar.xz;
+    # mkdir ../sdk; tar xf MacOSX10.14.sdk.tar.xz -C ../sdk;
   - conda install $COMPILERS
   #S- conda install nlopt petsc4py petsc mpi4py scipy $MPI
   - conda install nlopt petsc4py petsc $MUMPS mpi4py scipy $MPI
@@ -93,10 +93,10 @@ before_script:
   # Allow 10000 files to be open at once (critical for persistent_aposmm)
   - ulimit -Sn 10000
   # Set conda compilers to use new SDK instead of Travis default.
-  - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
-        echo "export CONDA_BUILD_SYSROOT=/Users/travis/build/Libensemble/sdk/MacOSX10.14.sdk" > setenv.sh;
-        source setenv.sh;
-    fi
+  # - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
+  #       echo "export CONDA_BUILD_SYSROOT=/Users/travis/build/Libensemble/sdk/MacOSX10.14.sdk" > setenv.sh;
+  #       source setenv.sh;
+  #   fi
 
 # Run test (-z show output)
 script:

From e4d545a166ed42038b5899e4cbf94ecf18c45fb3 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 24 Sep 2019 15:17:07 -0500
Subject: [PATCH 277/644] test lower versions of xcode

---
 .travis.yml | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/.travis.yml b/.travis.yml
index 79412fee7..7b6db7353 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -23,6 +23,16 @@ matrix:
       env: MPI=mpich PY=3
       language: generic
       python: 3
+    - os: osx
+      osx_image: xcode10.3
+      env: MPI=mpich PY=3
+      language: generic
+      python: 3
+    - os: osx
+      osx_image: xcode9.4
+      env: MPI=mpich PY=3
+      language: generic
+      python: 3
 
 services:
     - postgresql

From 8a4b86b23ab01aa9cb20165fd5631229203bdc99 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 24 Sep 2019 15:26:48 -0500
Subject: [PATCH 278/644] dont install headers

---
 .travis.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index 7b6db7353..f2aa048cf 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -56,7 +56,6 @@ cache:
 before_install:
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
       wget https://repo.continuum.io/miniconda/Miniconda3-4.7.10-MacOSX-x86_64.sh -O miniconda.sh;
-      sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /;
     else
       wget https://repo.continuum.io/miniconda/Miniconda3-4.6.14-Linux-x86_64.sh -O miniconda.sh;
     fi
@@ -69,6 +68,7 @@ before_install:
   - conda config --add channels conda-forge
   - conda create --yes --name condaenv python=$TRAVIS_PYTHON_VERSION
   - source activate condaenv
+        # sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /;
 
 install:
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then

From 902792a462c4c0a40c5ac67e20cfaffb73001e99 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Tue, 24 Sep 2019 15:53:36 -0500
Subject: [PATCH 279/644] Update mini_forces with AoS variation and build
 variants

---
 .../forces/mini_forces/build_forces.sh        |  26 +++
 .../forces/mini_forces/mini_forces.c          |   2 +-
 .../forces/mini_forces/mini_forces_AoS.c      | 180 ++++++++++++++++++
 3 files changed, 207 insertions(+), 1 deletion(-)
 create mode 100755 libensemble/tests/scaling_tests/forces/mini_forces/build_forces.sh
 create mode 100644 libensemble/tests/scaling_tests/forces/mini_forces/mini_forces_AoS.c

diff --git a/libensemble/tests/scaling_tests/forces/mini_forces/build_forces.sh b/libensemble/tests/scaling_tests/forces/mini_forces/build_forces.sh
new file mode 100755
index 000000000..a3a9fb297
--- /dev/null
+++ b/libensemble/tests/scaling_tests/forces/mini_forces/build_forces.sh
@@ -0,0 +1,26 @@
+#!/bin/bash
+
+# Building with OpenMP for CPU
+
+# GCC for current host (generally not as good at vectorization as intel).
+gcc -O3 -fopenmp -march=native -o mini_forces.x mini_forces.c -lm
+
+# Intel (fat binary covering vectorization for hswell/bdwell/skylake/knl)
+# icc -O3 -qopenmp -axAVX,CORE-AVX2,CORE-AVX512,MIC-AVX512 -o mini_forces.x mini_forces.c
+
+# Intel with vectorization for current host (no cross-compilation).
+# icc -O3 -qopenmp -xhost -o mini_forces.x mini_forces.c
+
+# xl
+# xlc_r -O3 -qsimd=auto -qsmp=omp -o mini_forces.x mini_forces.c
+
+# ----------------------------------------------
+
+# Building with OpenMP for target device (e.g. GPU)
+# Need to toggle to OpenMP target directive in mini_forces.c.
+
+# xl
+# xlc_r -O3 -qsmp=omp -qoffload -o mini_forces.x mini_forces.c
+
+# IRIS node (Intel Gen9 GPU)
+# env MPICH_CC=icx mpigcc -g -fiopenmp -fopenmp-targets=spir64 -o mini_forces.x mini_forces.c
diff --git a/libensemble/tests/scaling_tests/forces/mini_forces/mini_forces.c b/libensemble/tests/scaling_tests/forces/mini_forces/mini_forces.c
index 0c9c7729a..625fac687 100644
--- a/libensemble/tests/scaling_tests/forces/mini_forces/mini_forces.c
+++ b/libensemble/tests/scaling_tests/forces/mini_forces/mini_forces.c
@@ -6,7 +6,7 @@
     
     E.g: gcc build and run on 2 threads on CPU:
     
-    gcc -O3 -fopenmp -o serial_forces.x serial_forces.c -lm
+    gcc -O3 -fopenmp -o mini_forces.x mini_forces.c -lm
     export OMP_NUM_THREADS=2
     ./mini_forces.x
     
diff --git a/libensemble/tests/scaling_tests/forces/mini_forces/mini_forces_AoS.c b/libensemble/tests/scaling_tests/forces/mini_forces/mini_forces_AoS.c
new file mode 100644
index 000000000..33d3b1cdb
--- /dev/null
+++ b/libensemble/tests/scaling_tests/forces/mini_forces/mini_forces_AoS.c
@@ -0,0 +1,180 @@
+/* --------------------------------------------------------------------
+    Non-MPI, Single Step, Electostatics Code Example
+    
+    This is a complete working example to test threading/vectorization
+    without MPI or other non-trivial features.
+    
+    E.g: gcc build and run on 2 threads on CPU:
+    
+    gcc -O3 -fopenmp -march=native -o mini_forces_AoS.x mini_forces_AoS.c -lm
+    export OMP_NUM_THREADS=2
+    ./mini_forces_AoS.x
+    
+    E.g: xlc build and run on GPU:
+    
+    # First toggle #omp pragma line to target in forces_naive function.
+    xlc_r -O3 -qsmp=omp -qoffload -o mini_forces_AoS_xlc_gpu.x mini_forces_AoS.c
+    ./mini_forces_AoS.x
+    
+    Functionality:
+    Particles position and charge are initiated by a random stream.
+    Computes forces for all particles. Note: This version uses
+    an array of structures to store the data (AoS). The forces loop
+    should vectorize but will have overhead of gathers.
+    
+    OpenMP options for CPU and GPU. Toggle in forces_naive function.
+    
+    Author: S Hudson.
+-------------------------------------------------------------------- */
+#include <stdlib.h>
+#include <stdio.h>
+#include <math.h>
+#include <sys/time.h>
+#include <omp.h>
+
+#define CHECK_THREADS 1
+#define NUM_PARTICLES 6000
+
+typedef struct particle {
+    double p[3]; // Particle position
+    double f[3]; // Particle force
+    double q;    // Particle charge
+}__attribute__((__packed__)) particle;
+
+// Seed RNG
+int seed_rand(int seed) {
+    srand(seed);    
+    return 0;
+}
+
+// Return a random number from a persistent stream
+double get_rand() {
+    double randnum;              
+    randnum = (double)rand()/(double)(RAND_MAX + 1.0); //[0,1)    
+    return randnum;
+}
+
+
+// Particles start at random locations in 10x10x10 cube
+int build_system(int n, particle* parr) {
+    int q_range_low = -10;
+    int q_range_high = 10;
+    double extent = 10.0;
+    int i, dim;
+    
+    for(i=0; i<n; i++) {
+        for(dim=0; dim<3; dim++) {
+            parr[i].p[dim] = get_rand()*extent;
+            parr[i].f[dim] = 0.0;
+        }
+        parr[i].q = ((q_range_high+1)-q_range_low)*get_rand() + q_range_low;
+    }
+    return 0;
+}
+
+
+// Initialize forces to zero for all particles
+int init_forces(int lower, int upper, particle* parr) {
+    int i, dim;
+    for(i=lower; i<upper; i++) {
+        for(dim=0; dim<3; dim++) {
+            parr[i].f[dim] = 0.0;
+        }        
+    }
+    return 0;
+}
+
+
+// Print from each thread.
+int check_threads() {
+    int tid, nthreads;
+
+    #pragma omp parallel private(tid,nthreads)
+    {
+        #if defined(_OPENMP)
+            nthreads = omp_get_num_threads();
+            tid = omp_get_thread_num();
+            printf("ThreadID: %d    Num threads: %d\n",tid,nthreads);
+        #else
+            printf("OpenMP is disabled\n");
+        #endif
+    }
+    return 0;
+}
+
+
+// Electostatics pairwise forces kernel (O(N^2))
+double forces_naive(int n,  particle* parr) {
+    int i,j;
+    double ret = 0.0;
+    double dx, dy, dz, r, force;
+    double fx, fy, fz;
+    struct timeval tv1, tv2;
+
+    gettimeofday(&tv1, NULL);
+
+    // For GPU/Accelerators
+    /*
+    #pragma omp target teams distribute parallel for map(to: n) \
+                       map(tofrom: parr[0:n]) \
+                       reduction(+:ret) //thread_limit(128) //*/
+
+    // For CPU
+    //*
+    #pragma omp parallel for default(none) shared(n,parr) \
+                             private(i,j,dx,dy,dz,r,force,fx,fy,fz) \
+                             reduction(+:ret)  //*/
+    for(i=0; i<n; i++) {
+        fx = 0.0;
+        fy = 0.0;
+        fz = 0.0;
+        #pragma omp simd private(dx,dy,dz,r,force) reduction(+:fx,fy,fz,ret) // Enable vectorization
+        for(j=0; j<n; j++){
+            if (i==j) {
+                continue;
+            }
+            dx = parr[i].p[0] - parr[j].p[0];
+            dy = parr[i].p[1] - parr[j].p[1];
+            dz = parr[i].p[2] - parr[j].p[2];
+            r = sqrt(dx * dx + dy * dy + dz * dz);
+
+            force = parr[i].q * parr[j].q / (r*r);
+
+            fx += dx * force;
+            fy += dy * force;
+            fz += dz * force;
+            
+            ret += 0.5 * force;
+        }
+        parr[i].f[0] += fx;
+        parr[i].f[1] += fy;
+        parr[i].f[2] += fz;
+    }
+
+    gettimeofday(&tv2, NULL);
+    printf ("Time taken for loop (Wallclock) = %f seconds\n",
+         (double) (tv2.tv_usec - tv1.tv_usec) / 1000000 +
+         (double) (tv2.tv_sec - tv1.tv_sec));
+   
+    return ret;
+}
+
+
+int main(int argc, char **argv) {
+    
+    int num_particles = NUM_PARTICLES;
+    double local_en;        
+    particle* parr = malloc(num_particles * sizeof(particle));
+
+    
+    if (CHECK_THREADS) {
+        check_threads();
+    }
+    
+    build_system(num_particles, parr);
+    init_forces(0, num_particles, parr); // Whole array
+    local_en = forces_naive(num_particles, parr);
+    printf("energy is %f \n",local_en);
+    free(parr);
+    return 0;
+}

From b2875190efe582d304ce18cc98e42ef2d091fd31 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 24 Sep 2019 16:10:40 -0500
Subject: [PATCH 280/644] only activate xcode 9.4 for now

---
 .travis.yml | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index f2aa048cf..ed23f77d2 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -18,16 +18,16 @@ env:
 
 matrix:
   include:
-    - os: osx
-      osx_image: xcode11
-      env: MPI=mpich PY=3
-      language: generic
-      python: 3
-    - os: osx
-      osx_image: xcode10.3
-      env: MPI=mpich PY=3
-      language: generic
-      python: 3
+    # - os: osx
+    #   osx_image: xcode11
+    #   env: MPI=mpich PY=3
+    #   language: generic
+    #   python: 3
+    # - os: osx
+    #   osx_image: xcode10.3
+    #   env: MPI=mpich PY=3
+    #   language: generic
+    #   python: 3
     - os: osx
       osx_image: xcode9.4
       env: MPI=mpich PY=3
@@ -57,7 +57,7 @@ before_install:
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
       wget https://repo.continuum.io/miniconda/Miniconda3-4.7.10-MacOSX-x86_64.sh -O miniconda.sh;
     else
-      wget https://repo.continuum.io/miniconda/Miniconda3-4.6.14-Linux-x86_64.sh -O miniconda.sh;
+      wget https://repo.continuum.io/miniconda/Miniconda3-4.7.10-Linux-x86_64.sh -O miniconda.sh;
     fi
   - bash miniconda.sh -b -p $HOME/miniconda
   - export PATH="$HOME/miniconda/bin:$PATH"
@@ -68,7 +68,7 @@ before_install:
   - conda config --add channels conda-forge
   - conda create --yes --name condaenv python=$TRAVIS_PYTHON_VERSION
   - source activate condaenv
-        # sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /;
+    # sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /;
 
 install:
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then

From f501208495404554963fbce6e2790301421c6848 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 24 Sep 2019 16:32:33 -0500
Subject: [PATCH 281/644] narrow down working xcode versions

---
 .travis.yml | 35 +++++++++++++++++++++++++----------
 1 file changed, 25 insertions(+), 10 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index ed23f77d2..4799cc687 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -18,16 +18,31 @@ env:
 
 matrix:
   include:
-    # - os: osx
-    #   osx_image: xcode11
-    #   env: MPI=mpich PY=3
-    #   language: generic
-    #   python: 3
-    # - os: osx
-    #   osx_image: xcode10.3
-    #   env: MPI=mpich PY=3
-    #   language: generic
-    #   python: 3
+    - os: osx
+      osx_image: xcode11
+      env: MPI=mpich PY=3
+      language: generic
+      python: 3
+    - os: osx
+      osx_image: xcode10.3
+      env: MPI=mpich PY=3
+      language: generic
+      python: 3
+    - os: osx
+      osx_image: xcode10.2
+      env: MPI=mpich PY=3
+      language: generic
+      python: 3
+    - os: osx
+      osx_image: xcode10.1
+      env: MPI=mpich PY=3
+      language: generic
+      python: 3
+    - os: osx
+      osx_image: xcode10
+      env: MPI=mpich PY=3
+      language: generic
+      python: 3
     - os: osx
       osx_image: xcode9.4
       env: MPI=mpich PY=3

From 31c0fce0ab8a9db660d070355aa737d98bd771f4 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Tue, 24 Sep 2019 22:40:47 -0500
Subject: [PATCH 282/644] Fix mini_forces.c build line for icx

---
 .../tests/scaling_tests/forces/mini_forces/build_forces.sh      | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/scaling_tests/forces/mini_forces/build_forces.sh b/libensemble/tests/scaling_tests/forces/mini_forces/build_forces.sh
index a3a9fb297..4c737ade0 100755
--- a/libensemble/tests/scaling_tests/forces/mini_forces/build_forces.sh
+++ b/libensemble/tests/scaling_tests/forces/mini_forces/build_forces.sh
@@ -23,4 +23,4 @@ gcc -O3 -fopenmp -march=native -o mini_forces.x mini_forces.c -lm
 # xlc_r -O3 -qsmp=omp -qoffload -o mini_forces.x mini_forces.c
 
 # IRIS node (Intel Gen9 GPU)
-# env MPICH_CC=icx mpigcc -g -fiopenmp -fopenmp-targets=spir64 -o mini_forces.x mini_forces.c
+# icx -g -fiopenmp -fopenmp-targets=spir64 -o mini_forces.x mini_forces.c

From 43a0e32d6600ae39f7ff2d756f487ec2d63633bd Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 25 Sep 2019 17:10:10 -0500
Subject: [PATCH 283/644] narrow down to most recent working version

---
 .travis.yml | 26 +-------------------------
 1 file changed, 1 insertion(+), 25 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 4799cc687..09c52672a 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -18,36 +18,12 @@ env:
 
 matrix:
   include:
-    - os: osx
-      osx_image: xcode11
-      env: MPI=mpich PY=3
-      language: generic
-      python: 3
-    - os: osx
-      osx_image: xcode10.3
-      env: MPI=mpich PY=3
-      language: generic
-      python: 3
-    - os: osx
-      osx_image: xcode10.2
-      env: MPI=mpich PY=3
-      language: generic
-      python: 3
     - os: osx
       osx_image: xcode10.1
       env: MPI=mpich PY=3
       language: generic
       python: 3
-    - os: osx
-      osx_image: xcode10
-      env: MPI=mpich PY=3
-      language: generic
-      python: 3
-    - os: osx
-      osx_image: xcode9.4
-      env: MPI=mpich PY=3
-      language: generic
-      python: 3
+
 
 services:
     - postgresql

From f90b7a370444cfb6135fd66df6d31ce6d60e27a7 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 26 Sep 2019 11:48:24 -0500
Subject: [PATCH 284/644] try omitting balsam_controller in non-balsam coverage

---
 libensemble/tests/regression_tests/.coveragerc | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/libensemble/tests/regression_tests/.coveragerc b/libensemble/tests/regression_tests/.coveragerc
index eecb88a91..19178f1e8 100644
--- a/libensemble/tests/regression_tests/.coveragerc
+++ b/libensemble/tests/regression_tests/.coveragerc
@@ -9,7 +9,7 @@ omit =
     */branin_*/*
 
 branch = true
-	 
+
 data_file = .cov_reg_out
 
 parallel = true
@@ -22,9 +22,11 @@ omit =
     */unit_tests/*
     */unit_tests_nompi/*
     */regression_tests/*
+    */balsam_controller.py
+
 
 exclude_lines =
     if __name__ == .__main__.:
 
-[html]    
+[html]
 directory = cov_reg

From bf07e710a29cd23e59b24efdfd3d553344298fde Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 26 Sep 2019 12:08:16 -0500
Subject: [PATCH 285/644] adjust path

---
 libensemble/tests/regression_tests/.coveragerc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/regression_tests/.coveragerc b/libensemble/tests/regression_tests/.coveragerc
index 19178f1e8..525564f11 100644
--- a/libensemble/tests/regression_tests/.coveragerc
+++ b/libensemble/tests/regression_tests/.coveragerc
@@ -22,7 +22,7 @@ omit =
     */unit_tests/*
     */unit_tests_nompi/*
     */regression_tests/*
-    */balsam_controller.py
+    balsam_controller.py
 
 
 exclude_lines =

From a7ab284e77ba48fd01243acf4f4c5dbadbdb43df Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 26 Sep 2019 12:53:05 -0500
Subject: [PATCH 286/644] Removing tabs

---
 .../release_platforms/rel_spack.rst                |  2 +-
 .../job_submission_scripts/bebop_submit_slurm.sh   |  2 +-
 .../bebop_submit_slurm_centralmode.sh              |  2 +-
 libensemble/tests/regression_tests/.coveragerc     |  2 +-
 libensemble/tests/scaling_tests/forces/readme.md   | 14 +++++++-------
 libensemble/tests/unit_tests/.coveragerc           |  2 +-
 libensemble/tests/unit_tests_logger/.coveragerc    |  2 +-
 libensemble/tests/unit_tests_nompi/.coveragerc     |  2 +-
 8 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/docs/dev_guide/release_management/release_platforms/rel_spack.rst b/docs/dev_guide/release_management/release_platforms/rel_spack.rst
index c1b20b436..6a6c5c6c0 100644
--- a/docs/dev_guide/release_management/release_platforms/rel_spack.rst
+++ b/docs/dev_guide/release_management/release_platforms/rel_spack.rst
@@ -34,7 +34,7 @@ To set upstream repo::
 (Optional) Prevent accidental pushes to upstream::
 
     git remote set-url --push upstream no_push
-    git remote -v # Check for line: `upstream	no_push (push)`
+    git remote -v # Check for line: `upstream no_push (push)`
     
 
 Now to update (the main develop branch)
diff --git a/examples/job_submission_scripts/bebop_submit_slurm.sh b/examples/job_submission_scripts/bebop_submit_slurm.sh
index d73de4fa5..49f58cf81 100644
--- a/examples/job_submission_scripts/bebop_submit_slurm.sh
+++ b/examples/job_submission_scripts/bebop_submit_slurm.sh
@@ -43,7 +43,7 @@ fi;
 #---------------------------------------------------------------------------------------------
 #Test
 echo -e "Slurm job ID: $SLURM_JOBID"
- 	
+ 
 #cd $PBS_O_WORKDIR
 cd $SLURM_SUBMIT_DIR
 
diff --git a/examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh b/examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
index d852b158f..48eb43026 100644
--- a/examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
+++ b/examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
@@ -31,7 +31,7 @@ export LIBE_WALLCLOCK=55
 #---------------------------------------------------------------------------------------------
 #Test
 echo -e "Slurm job ID: $SLURM_JOBID"
- 	
+ 
 #cd $PBS_O_WORKDIR
 cd $SLURM_SUBMIT_DIR
 
diff --git a/libensemble/tests/regression_tests/.coveragerc b/libensemble/tests/regression_tests/.coveragerc
index eecb88a91..c55ce25e9 100644
--- a/libensemble/tests/regression_tests/.coveragerc
+++ b/libensemble/tests/regression_tests/.coveragerc
@@ -9,7 +9,7 @@ omit =
     */branin_*/*
 
 branch = true
-	 
+ 
 data_file = .cov_reg_out
 
 parallel = true
diff --git a/libensemble/tests/scaling_tests/forces/readme.md b/libensemble/tests/scaling_tests/forces/readme.md
index 27ad70fcb..39490cbfd 100644
--- a/libensemble/tests/scaling_tests/forces/readme.md
+++ b/libensemble/tests/scaling_tests/forces/readme.md
@@ -66,28 +66,28 @@ scripts such as `theta_submit_balsam.sh`.
 
 The scripts are set up assuming a conda environment. To use script directly you will need to replace the following templated values:
 
-	<projectID> in the COBALT -A directive with your project ID.
+  <projectID> in the COBALT -A directive with your project ID.
 
-	<conda_env_name> is the name of your conda environment.
+  <conda_env_name> is the name of your conda environment.
 
 and in Balsam scripts:
 
-	<dbase_name> The name of an initialized balsam database.
-	             (with max_connections enough for number of workers)
+  <dbase_name> The name of an initialized balsam database.
+               (with max_connections enough for number of workers)
 
 The included scripts are.
 
 * theta_submit_mproc.sh:
 
-	Example Theta submission script to run libEnsemble in central mode on the Theta launch (MOM) nodes with multiprocessing worker concurrency.
+  Example Theta submission script to run libEnsemble in central mode on the Theta launch (MOM) nodes with multiprocessing worker concurrency.
 
 * summit_submit_mproc.sh:
 
-	Example Summit submission script to run libEnsemble in central mode on the Summit launch nodes with multiprocessing worker concurrency.
+  Example Summit submission script to run libEnsemble in central mode on the Summit launch nodes with multiprocessing worker concurrency.
 
 * theta_submit_balsam.sh:
 
-	Example Theta submission script to run libEnsemble in central mode with MPI worker concurrency using Balsam. In this case libEnsemble manager and workers run on compute nodes and sumit jobs via Balsam.
+  Example Theta submission script to run libEnsemble in central mode with MPI worker concurrency using Balsam. In this case libEnsemble manager and workers run on compute nodes and sumit jobs via Balsam.
 
 #### Plotting Options
 
diff --git a/libensemble/tests/unit_tests/.coveragerc b/libensemble/tests/unit_tests/.coveragerc
index c520890fe..434d58279 100644
--- a/libensemble/tests/unit_tests/.coveragerc
+++ b/libensemble/tests/unit_tests/.coveragerc
@@ -8,7 +8,7 @@ omit =
     */regression_tests/*
 
 branch = true
-	 
+ 
 data_file = .cov_unit_out
 
 #parallel = true
diff --git a/libensemble/tests/unit_tests_logger/.coveragerc b/libensemble/tests/unit_tests_logger/.coveragerc
index 50900a2c2..0a22a922f 100644
--- a/libensemble/tests/unit_tests_logger/.coveragerc
+++ b/libensemble/tests/unit_tests_logger/.coveragerc
@@ -8,7 +8,7 @@ omit =
     */regression_tests/*
 
 branch = true
-	 
+ 
 data_file = .cov_unit_out3
 
 #parallel = true
diff --git a/libensemble/tests/unit_tests_nompi/.coveragerc b/libensemble/tests/unit_tests_nompi/.coveragerc
index 95072f617..2c9a3a53d 100644
--- a/libensemble/tests/unit_tests_nompi/.coveragerc
+++ b/libensemble/tests/unit_tests_nompi/.coveragerc
@@ -8,7 +8,7 @@ omit =
     */regression_tests/*
 
 branch = true
-	 
+ 
 data_file = .cov_unit_out2
 
 #parallel = true

From b90ebec7ed29eaf86b7a135bb348ea297d56a5f2 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 26 Sep 2019 13:18:53 -0500
Subject: [PATCH 287/644] removing whitespace

---
 .flake8                                       | 10 +++---
 .readthedocs.yml                              |  2 +-
 .style.yapf                                   |  2 +-
 CONTRIBUTING.rst                              |  2 +-
 conda/run_travis_locally/readme.md            | 31 +++++++++----------
 docs/data_structures/alloc_specs.rst          |  8 ++---
 docs/data_structures/gen_specs.rst            | 12 +++----
 docs/data_structures/persis_info.rst          |  2 +-
 docs/data_structures/sim_specs.rst            | 14 ++++-----
 docs/data_structures/work_dict.rst            | 26 ++++++++--------
 docs/data_structures/worker_array.rst         | 16 +++++-----
 .../dev_API/env_resources_module.rst          |  2 +-
 docs/dev_guide/dev_API/history_module.rst     |  2 +-
 docs/dev_guide/dev_API/manager_module.rst     |  4 +--
 docs/dev_guide/dev_API/resources_module.rst   |  4 +--
 docs/dev_guide/dev_API/worker_module.rst      |  2 +-
 .../release_platforms/rel_pypi.rst            |  2 +-
 .../release_platforms/rel_spack.rst           | 28 ++++++++---------
 docs/examples/alloc_funcs.rst                 |  4 +--
 docs/examples/examples_index.rst              |  2 +-
 docs/examples/gen_funcs.rst                   |  3 +-
 docs/examples/sim_funcs.rst                   |  2 +-
 docs/job_controller/balsam_controller.rst     |  8 ++---
 docs/job_controller/jc_index.rst              |  2 +-
 docs/job_controller/job_controller.rst        | 12 +++----
 docs/job_controller/mpi_controller.rst        |  6 ++--
 docs/job_controller/overview.rst              | 12 +++----
 docs/user_funcs.rst                           |  2 +-
 .../bebop_submit_slurm.sh                     | 16 +++++-----
 .../bebop_submit_slurm_centralmode.sh         | 16 +++++-----
 .../job_submission_scripts/blues_script.pbs   |  8 ++---
 .../theta_submit_balsam.sh                    |  2 +-
 libensemble/tests/.coveragerc                 |  2 +-
 .../bash_scripts/setup_balsam_tests.sh        |  6 ++--
 libensemble/tests/balsam_tests/readme.rst     | 24 +++++++-------
 .../tests/regression_tests/.coveragerc        |  4 +--
 .../scaling_tests/forces/balsam_local.sh      |  2 +-
 .../tests/scaling_tests/forces/clone.sh       |  4 +--
 .../tests/scaling_tests/forces/readme.md      |  8 ++---
 .../forces/summit_submit_mproc.sh             |  6 ++--
 .../forces/theta_submit_balsam.sh             |  4 +--
 .../forces/theta_submit_mproc.sh              |  2 +-
 .../kill_test/log.autotest.txt                | 17 +++++-----
 .../kill_test/log.burn_time_test_with_top.txt | 28 ++++++++---------
 .../standalone_tests/kill_test/readme.txt     |  2 +-
 .../mpi_launch_test/readme.txt                |  2 +-
 libensemble/tests/unit_tests/.coveragerc      |  6 ++--
 .../tests/unit_tests_logger/.coveragerc       |  6 ++--
 .../tests/unit_tests_nompi/.coveragerc        |  6 ++--
 postproc_scripts/compare_npy.py               |  4 +--
 postproc_scripts/plot_libE_histogram.py       |  6 ++--
 postproc_scripts/readme.rst                   |  2 +-
 52 files changed, 198 insertions(+), 207 deletions(-)

diff --git a/.flake8 b/.flake8
index 5d7132daf..6f4334ab3 100644
--- a/.flake8
+++ b/.flake8
@@ -1,5 +1,5 @@
 [flake8]
-ignore = 
+ignore =
         # Not worrying about line length for now
         E501,
         # Not worrying about spaces around arithmetic operations
@@ -12,12 +12,12 @@ ignore =
         W504
         # Lambda expressions are okay
         E731
-exclude = 
+exclude =
         # Don't need to check .git
         .git,
         # Largely autogenerated
         docs/conf.py
-        # Keeping bad python format to match PETSc source code 
+        # Keeping bad python format to match PETSc source code
         libensemble/sim_funcs/chwirut1.py
         examples/sim_funcs/chwirut1.py
         # This is not implemented yet
@@ -35,5 +35,5 @@ per-file-ignores =
         libensemble/libensemble/__init__.py:F401
         # Need to turn of matching probes (before other imports) on some
         # systems/versions of MPI:
-        libensemble/tests/standalone_tests/mpi_launch_test/create_mpi_jobs.py:E402 
-        libensemble/libensemble/tests/standalone_tests/mpi_launch_test/create_mpi_jobs.py:E402 
+        libensemble/tests/standalone_tests/mpi_launch_test/create_mpi_jobs.py:E402
+        libensemble/libensemble/tests/standalone_tests/mpi_launch_test/create_mpi_jobs.py:E402
diff --git a/.readthedocs.yml b/.readthedocs.yml
index 2695aca1c..a8f801e04 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -1,6 +1,6 @@
 conda:
     file: conda/environment.yml
-    
+
 python:
     version: 3.6
     pip_install: true
diff --git a/.style.yapf b/.style.yapf
index 4908524cd..31be33349 100644
--- a/.style.yapf
+++ b/.style.yapf
@@ -6,7 +6,7 @@ SPLIT_BEFORE_DOT = True
 COLUMN_LIMIT = 79
 SPLIT_BEFORE_NAMED_ASSIGNS = False
 SPACE_BETWEEN_ENDING_COMMA_AND_CLOSING_BRACKET = False
-ALLOW_SPLIT_BEFORE_DEFAULT_OR_NAMED_ASSIGNS = False 
+ALLOW_SPLIT_BEFORE_DEFAULT_OR_NAMED_ASSIGNS = False
 ALLOW_SPLIT_BEFORE_DICT_VALUE = False
 DEDENT_CLOSING_BRACKETS = False
 EACH_DICT_ENTRY_ON_SEPARATE_LINE = True
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 411f069ad..ad252cb8d 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -13,7 +13,7 @@ given in the ".flake8" configuration file in the project directory.
 Issues can be raised at:
 
     https://github.com/Libensemble/libensemble/issues
-    
+
 Issues may include reporting bugs or suggested features. Administrators
 will add issues, as appropriate, to the project board at:
 
diff --git a/conda/run_travis_locally/readme.md b/conda/run_travis_locally/readme.md
index fa8979c67..c0476c606 100644
--- a/conda/run_travis_locally/readme.md
+++ b/conda/run_travis_locally/readme.md
@@ -4,7 +4,7 @@
 
 This explains how to replicate the Travis container environment locally.
 
-This can save a lot of git pushes and trial-and-error when there is problems in Travis builds that are not 
+This can save a lot of git pushes and trial-and-error when there is problems in Travis builds that are not
 observed locally.
 
 #### References:
@@ -32,8 +32,8 @@ Add user name to docker group so dont need sudo before docker:
     sudo usermod -aG docker ${USER}
     su - ${USER}
     id -nG # Confirm username added to docker users
-    
-    
+
+
 ### Install Travis Image for Python and create a container
 
 Name your new travis container:
@@ -46,7 +46,7 @@ Install the Travis Docker image for Python and run the container (server):
 
 This might take a while if image is not downloaded. Once image is downloaded it will be run from cache.
 
-Note: 
+Note:
 travisci/ci-garnet:packer-1512502276-986baf0 is the Travis Python image. The name in
 $CONTAINER is the name you are assigning to the new container made from the image.
 
@@ -58,7 +58,7 @@ Alternative travisCI docker images can be found [here](https://hub.docker.com/r/
 Then open a shell in running container:
 
     sudo docker exec -it $CONTAINER bash -l
-    
+
 Prompt should say travis@ rather than root@:
 
 
@@ -72,7 +72,7 @@ the installs against .travis.yml in the top level libEnsemble package directory.
 
 #### Copy build script from host system to the running container
 
-Run the following **from your host machine environment**. This copies the given file into an existing 
+Run the following **from your host machine environment**. This copies the given file into an existing
 container named $CONTAINER. Where /home/travis is target location in container
 filesystem.
 
@@ -82,19 +82,19 @@ On the docker side you may need to set ownership of the script:
 
     chown travis:travis /home/travis/build_mpich_libE.sh
 
-    
+
 #### Run the libEnsemble build-and-run script
 
 Now, in the docker container, become user travis:
 
     su - travis
- 
+
 Source the script, setting python version and libEnsemble branch if necessary (see script for defaults).
 **Always source** to maintain environment variables after running (inc. miniconda path). The following
 would run with Python 3.7 and test the libEnsemble branch hotfix/logging:
 
     . ./build_mpich_libE.sh -p 3.7 -b hotfix/logging
-    
+
 Note: libEnsemble will be git cloned and checked out at the given branch.
 
 The script should build all dependencies and run tests. Having sourced the script, you should
@@ -108,12 +108,12 @@ If the conda output is too verbose, remove the "set -x" line in the script.
 To exit the container session (client).
     exit # Travis user
     exit # Exit running session (but container server is still running.
-    
+
 Re-enter while background container still running:
 
     sudo docker exec -it $CONTAINER bash -l
     su - travis
-    
+
 Note that environment variables are not saved.
 
 To save the modified container as an image (with your changes to filesystem):
@@ -123,7 +123,7 @@ Note: This will not by default save your environment variables
 First to check running containers (ie. running server - whether or not you are in a session):
 
     docker ps
-    
+
 OR
 
     docker container ls
@@ -144,13 +144,13 @@ Now it should show if you do:
 If it is saved you can stop the container (server) thats running and restart eg.
 
     docker stop $CONTAINER
-    
+
 where $CONTAINER is the name you gave the container on the docker run command.
 
 You can restart from your new image with docker run and docker exec or to run server and run session in one:
 
     docker run -it <user_name>/<image_name> /bin/bash
-    
+
 where <user_name>/<image_name> is as used above to save (or from first column in "docker images" output).
 
 
@@ -164,6 +164,3 @@ container can be [restricted](https://docs.docker.com/config/containers/resource
 An alternative to this process is to log in to your Travis build and debug. For public
 repositories, this requires contacting Travis support for a token that can only be used by
 the given user. See [here](https://docs.travis-ci.com/user/running-build-in-debug-mode/).
-
-
-    
diff --git a/docs/data_structures/alloc_specs.rst b/docs/data_structures/alloc_specs.rst
index c1ab58c4f..a02c37f8d 100644
--- a/docs/data_structures/alloc_specs.rst
+++ b/docs/data_structures/alloc_specs.rst
@@ -8,13 +8,13 @@ Allocation function specifications to be set in user calling script and passed t
 
     alloc_specs: [dict, optional] :
 
-        Required keys :  
-        
+        Required keys :
+
         'alloc_f' [func] :
             Default: give_sim_work_first
-            
+
         Optional keys :
-        
+
         'out' [list of tuples] :
             Default: [('allocated',bool)]
 
diff --git a/docs/data_structures/gen_specs.rst b/docs/data_structures/gen_specs.rst
index 97c87e8c4..2a937f492 100644
--- a/docs/data_structures/gen_specs.rst
+++ b/docs/data_structures/gen_specs.rst
@@ -7,17 +7,17 @@ Generation function specifications to be set in user calling script and passed t
 
     gen_specs: [dict]:
 
-        Required keys :     
-        
-        'gen_f' [func] : 
+        Required keys :
+
+        'gen_f' [func] :
             generates inputs to sim_f
-        'in' [list] : 
+        'in' [list] :
             field names (as strings) that will be given to gen_f
         'out' [list of tuples (field name, data type, [size])] :
             gen_f outputs that will be stored in the libEnsemble history
-            
+
         Optional keys :
-    
+
         'save_every_k' [int] :
             Save history array to file after every k generated points.
 
diff --git a/docs/data_structures/persis_info.rst b/docs/data_structures/persis_info.rst
index 5bb8f6d25..3f5bfbbd2 100644
--- a/docs/data_structures/persis_info.rst
+++ b/docs/data_structures/persis_info.rst
@@ -13,7 +13,7 @@ is a randon number generator to be used in consecutive calls to a generator.
 
 If worker ``i`` sends back ``persis_info``, it is stored in ``persis_info[i]``. This functionality
 can be used to, for example, pass a random stream back to the manager to be included in future work
-from the allocation function. 
+from the allocation function.
 
 :Examples:
 
diff --git a/docs/data_structures/sim_specs.rst b/docs/data_structures/sim_specs.rst
index 58afa8412..63a6396c1 100644
--- a/docs/data_structures/sim_specs.rst
+++ b/docs/data_structures/sim_specs.rst
@@ -8,18 +8,18 @@ Simulation function specifications to be set in user calling script and passed t
 
     sim_specs: [dict]:
 
-        Required keys :    
-        
-        'sim_f' [func] : 
+        Required keys :
+
+        'sim_f' [func] :
             the simulation function being evaluated
         'in' [list] :
             field names (as strings) that will be given to sim_f
         'out' [list of tuples (field name, data type, [size])] :
             sim_f outputs that will be stored in the libEnsemble history
-            
+
 
         Optional keys :
-        
+
         'save_every_k' [int] :
             Save history array to file after every k simulated points.
         'sim_dir' [str] :
@@ -32,7 +32,7 @@ Simulation function specifications to be set in user calling script and passed t
             Profile using cProfile. Default: False
 
         Additional entires in sim_specs will be given to sim_f
-        
+
 :Notes:
 
 * The user may define other fields to be passed to the simulator function.
@@ -49,7 +49,7 @@ From: ``libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
     sim_specs = {'sim_f': six_hump_camel, # This is the function whose output is being minimized
                  'in': ['x'],             # These keys will be given to the above function
                  'out': [('f',float)],    # This is the output from the function being minimized
-                 'save_every_k': 400  
+                 'save_every_k': 400
                  }
 
 Note that the dimensions and type of the ``'in'`` field variable ``'x'`` is specified by the corresponding
diff --git a/docs/data_structures/work_dict.rst b/docs/data_structures/work_dict.rst
index 1d78bf187..6e4bc7ec6 100644
--- a/docs/data_structures/work_dict.rst
+++ b/docs/data_structures/work_dict.rst
@@ -3,38 +3,38 @@
 work dictionary
 ===============
 
-Dictionary with integer keys ``i`` and dictionary values to be given to worker ``i``. 
+Dictionary with integer keys ``i`` and dictionary values to be given to worker ``i``.
 ``Work[i]`` has the following form::
 
 
     Work[i]: [dict]:
 
-        Required keys :    
-        'persis_info' [dict]: Any persistent info to be sent to worker 'i' 
+        Required keys :
+        'persis_info' [dict]: Any persistent info to be sent to worker 'i'
 
-        'H_fields' [list]: The field names of the history 'H' to be sent to worker 'i' 
+        'H_fields' [list]: The field names of the history 'H' to be sent to worker 'i'
 
-        'tag' [int]: 'EVAL_SIM_TAG' (resp. 'EVAL_GEN_TAG') if worker 'i' is to call sim_func (resp. gen_func) 
+        'tag' [int]: 'EVAL_SIM_TAG' (resp. 'EVAL_GEN_TAG') if worker 'i' is to call sim_func (resp. gen_func)
 
-        'libE_info' [dict]: This information is sent to and returned from the worker to help libEnsemble quickly update the 'H' and 'W'. 
+        'libE_info' [dict]: This information is sent to and returned from the worker to help libEnsemble quickly update the 'H' and 'W'.
             Available keys are:
 
             H_rows' [list of ints]: History rows to send to worker 'i'
 
             blocking' [list of ints]: Workers to be blocked by the calculation given to worker 'i'
 
-            persistent' [bool]: True if worker 'i' will enter persistent mode 
-        
-        
+            persistent' [bool]: True if worker 'i' will enter persistent mode
+
+
 :Examples:
 
 .. How to link directly to the file?
 
-| For allocation functions using persistent workers, see 
-| ``libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py`` 
-| or 
+| For allocation functions using persistent workers, see
+| ``libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py``
+| or
 | ``libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py``
 |
-| For allocation functions giving work that blocks other workers, see 
+| For allocation functions giving work that blocks other workers, see
 | ``libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py``
 
diff --git a/docs/data_structures/worker_array.rst b/docs/data_structures/worker_array.rst
index a26112204..88420549e 100644
--- a/docs/data_structures/worker_array.rst
+++ b/docs/data_structures/worker_array.rst
@@ -10,14 +10,14 @@ convention:
 =========================================   =======  ============  =======
 Worker state                                 active  persis_state  blocked
 =========================================   =======  ============  =======
-idle worker                                    0          0           0   
-active, nonpersistent sim                      1          0           0   
-active, nonpersistent gen                      2          0           0   
-active, persistent sim                         1          1           0   
-active, persistent gen                         2          2           0   
-waiting, persistent sim                        0          1           0   
-waiting, persistent gen                        0          2           0   
-worker blocked by some other calculation       1          0           1   
+idle worker                                    0          0           0
+active, nonpersistent sim                      1          0           0
+active, nonpersistent gen                      2          0           0
+active, persistent sim                         1          1           0
+active, persistent gen                         2          2           0
+waiting, persistent sim                        0          1           0
+waiting, persistent gen                        0          2           0
+worker blocked by some other calculation       1          0           1
 =========================================   =======  ============  =======
 
 :Note:
diff --git a/docs/dev_guide/dev_API/env_resources_module.rst b/docs/dev_guide/dev_API/env_resources_module.rst
index 08747268a..3f4367034 100644
--- a/docs/dev_guide/dev_API/env_resources_module.rst
+++ b/docs/dev_guide/dev_API/env_resources_module.rst
@@ -6,5 +6,5 @@ Environment Resources Module
 .. autoclass:: EnvResources
   :member-order: bysource
   :members:
-  
+
   .. automethod:: __init__
diff --git a/docs/dev_guide/dev_API/history_module.rst b/docs/dev_guide/dev_API/history_module.rst
index 57c97d821..0a5527380 100644
--- a/docs/dev_guide/dev_API/history_module.rst
+++ b/docs/dev_guide/dev_API/history_module.rst
@@ -6,5 +6,5 @@ History Module
 .. autoclass:: History
   :member-order: bysource
   :members:
-  
+
   .. automethod:: __init__
diff --git a/docs/dev_guide/dev_API/manager_module.rst b/docs/dev_guide/dev_API/manager_module.rst
index c0917af21..ae4d97e9d 100644
--- a/docs/dev_guide/dev_API/manager_module.rst
+++ b/docs/dev_guide/dev_API/manager_module.rst
@@ -3,9 +3,9 @@ Manager Module
 .. automodule:: libE_manager
   :members: manager_main
   :undoc-members:
-  
+
 .. autoclass:: Manager
   :member-order: bysource
   :members:
-  
+
   .. automethod:: __init__
diff --git a/docs/dev_guide/dev_API/resources_module.rst b/docs/dev_guide/dev_API/resources_module.rst
index cc998cbf9..a05669f45 100644
--- a/docs/dev_guide/dev_API/resources_module.rst
+++ b/docs/dev_guide/dev_API/resources_module.rst
@@ -6,11 +6,11 @@ Resources Module
 .. autoclass:: Resources
   :member-order: bysource
   :members:
-  
+
   .. automethod:: __init__
 
 .. autoclass:: WorkerResources
   :member-order: bysource
   :members:
-  
+
   .. automethod:: __init__
diff --git a/docs/dev_guide/dev_API/worker_module.rst b/docs/dev_guide/dev_API/worker_module.rst
index 855e39c4d..79a27b1f8 100644
--- a/docs/dev_guide/dev_API/worker_module.rst
+++ b/docs/dev_guide/dev_API/worker_module.rst
@@ -6,6 +6,6 @@ Worker Module
 .. autoclass:: Worker
   :member-order: bysource
   :members:
-  
+
   .. automethod:: __init__
 
diff --git a/docs/dev_guide/release_management/release_platforms/rel_pypi.rst b/docs/dev_guide/release_management/release_platforms/rel_pypi.rst
index 906d250af..3cbdd32f3 100644
--- a/docs/dev_guide/release_management/release_platforms/rel_pypi.rst
+++ b/docs/dev_guide/release_management/release_platforms/rel_pypi.rst
@@ -3,7 +3,7 @@
 PyPI release
 ============
 
-libEnsemble is released on the Python Package Index (commonly known as PyPI). This enable users to “pip install” the package. 
+libEnsemble is released on the Python Package Index (commonly known as PyPI). This enable users to “pip install” the package.
 
 The package is stored on PyPI in the form of a source distribution (commonly known as a tarball). The tarball could be obtained from github, though historically this has been created with a checkout of libensemble from git.
 
diff --git a/docs/dev_guide/release_management/release_platforms/rel_spack.rst b/docs/dev_guide/release_management/release_platforms/rel_spack.rst
index 6a6c5c6c0..db058de05 100644
--- a/docs/dev_guide/release_management/release_platforms/rel_spack.rst
+++ b/docs/dev_guide/release_management/release_platforms/rel_spack.rst
@@ -35,7 +35,7 @@ To set upstream repo::
 
     git remote set-url --push upstream no_push
     git remote -v # Check for line: `upstream no_push (push)`
-    
+
 
 Now to update (the main develop branch)
 ---------------------------------------
@@ -66,12 +66,12 @@ Or to make your local machine identical to upstream repo (**WARNING** Any local
 
     git reset --hard upstream/develop
 
-    
+
 (Optional) You may want to update your forked (origin) repo on github at this point.
 This may requires a forced push::
 
     git push origin develop --force
-    
+
 
 Making changes
 --------------
@@ -87,14 +87,14 @@ Quick example to update libensemble::
 
     git branch update_libensemble
     git checkout update_libensemble
-    
+
 This will open the libensemble package.py file in your editor (given by env variable EDITOR)::
 
     spack edit py-libensemble  # SPACK_ROOT must be set (see above) (python packages use "py-" prefix)
 
 Or just open it manually: var/spack/repos/builtin/packages/py-libensemble/package.py
-    
-    
+
+
 Now get checksum for new lines:
 
 Get the tarball (see PyPI instructions), for the new release and use::
@@ -112,22 +112,22 @@ If OK add, commit and push to origin (forked repo)::
 
      git commit -am "Update libensemble"
      git push origin update_libensemble --force
-     
+
 Once the branch is pushed to the forked repo - go to github and do a pull request from this
 branch on the fork to the develop branch on the upstream.
 
-    
+
 Express summary: Make fork identical to upstream
 ------------------------------------------------
 
 Quick summary for bringing develop branch on forked repo up to speed with upstream
 (YOU WILL LOSE ANY CHANGES)::
 
-    git remote add upstream https://github.com/spack/spack.git  
-    git fetch upstream  
-    git checkout develop  
-    git reset --hard upstream/develop  
-    git push origin develop --force  
+    git remote add upstream https://github.com/spack/spack.git
+    git fetch upstream
+    git checkout develop
+    git reset --hard upstream/develop
+    git push origin develop --force
 
 Reference: <https://stackoverflow.com/questions/9646167/clean-up-a-fork-and-restart-it-from-the-upstream/39628366>
-    
+
diff --git a/docs/examples/alloc_funcs.rst b/docs/examples/alloc_funcs.rst
index 75583bf7f..3ab9f1e8d 100644
--- a/docs/examples/alloc_funcs.rst
+++ b/docs/examples/alloc_funcs.rst
@@ -13,7 +13,7 @@ give_sim_work_first
 .. automodule:: give_sim_work_first
   :members:
   :undoc-members:
-  
+
 fast_alloc
 ----------
 .. automodule:: fast_alloc
@@ -37,5 +37,3 @@ start_persistent_local_opt_gens
 .. automodule:: start_persistent_local_opt_gens
   :members:
   :undoc-members:
-  
-  
diff --git a/docs/examples/examples_index.rst b/docs/examples/examples_index.rst
index f5f29dd7a..d4a4dd89d 100644
--- a/docs/examples/examples_index.rst
+++ b/docs/examples/examples_index.rst
@@ -7,7 +7,7 @@ Example gen, sim and alloc functions for libEnsemble.
 .. toctree::
    :maxdepth: 2
    :caption: libEnsemble Example Functions:
-   
+
    gen_funcs
    sim_funcs
    alloc_funcs
diff --git a/docs/examples/gen_funcs.rst b/docs/examples/gen_funcs.rst
index 64250d174..110216e36 100644
--- a/docs/examples/gen_funcs.rst
+++ b/docs/examples/gen_funcs.rst
@@ -17,7 +17,7 @@ APOSMM
 .. automodule:: aposmm
   :members:
   :undoc-members:
-  
+
 uniform_or_localopt
 -------------------
 .. automodule:: uniform_or_localopt
@@ -29,4 +29,3 @@ persistent_uniform_sampling
 .. automodule:: persistent_uniform_sampling
   :members:
   :undoc-members:
-  
diff --git a/docs/examples/sim_funcs.rst b/docs/examples/sim_funcs.rst
index 377daa6f5..78ccc1438 100644
--- a/docs/examples/sim_funcs.rst
+++ b/docs/examples/sim_funcs.rst
@@ -17,7 +17,7 @@ chwirut
 .. automodule:: chwirut1
   :members:
   :undoc-members:
-  
+
 job_control_hworld
 ------------------
 .. automodule:: job_control_hworld
diff --git a/docs/job_controller/balsam_controller.rst b/docs/job_controller/balsam_controller.rst
index df3489a58..52fe72d46 100644
--- a/docs/job_controller/balsam_controller.rst
+++ b/docs/job_controller/balsam_controller.rst
@@ -8,20 +8,20 @@ To create a Balsam job controller, the calling script should contain::
     jobctr = BalsamJobController()
 
 The Balsam job controller inherits from the MPI job controller. See the
-:doc:`MPIJobController<mpi_controller>` for shared API. Any differences are 
+:doc:`MPIJobController<mpi_controller>` for shared API. Any differences are
 shown below.
 
 .. automodule:: balsam_controller
   :no-undoc-members:
-  
+
 .. autoclass:: BalsamJobController
   :show-inheritance:
 ..  :inherited-members:
-..  :member-order: bysource  
+..  :member-order: bysource
 ..  :members: __init__, launch, poll, manager_poll, kill, set_kill_mode
 
 .. autoclass:: BalsamJob
   :show-inheritance:
   :member-order: bysource
-..  :members: workdir_exists, file_exists_in_workdir, read_file_in_workdir, stdout_exists, read_stdout  
+..  :members: workdir_exists, file_exists_in_workdir, read_file_in_workdir, stdout_exists, read_stdout
 ..  :inherited-members:
diff --git a/docs/job_controller/jc_index.rst b/docs/job_controller/jc_index.rst
index 6318f06a6..16bed80a8 100644
--- a/docs/job_controller/jc_index.rst
+++ b/docs/job_controller/jc_index.rst
@@ -9,6 +9,6 @@ The job controller can be used within the simulator (and potentially generator)
    :maxdepth: 2
    :titlesonly:
    :caption: libEnsemble Job Controller:
-   
+
    overview
    job_controller
diff --git a/docs/job_controller/job_controller.rst b/docs/job_controller/job_controller.rst
index 84bd6a2f1..a2a312e9b 100644
--- a/docs/job_controller/job_controller.rst
+++ b/docs/job_controller/job_controller.rst
@@ -3,15 +3,15 @@ Job Controller Module
 
 .. automodule:: controller
   :no-undoc-members:
- 
+
 See  :doc:`example<overview>` for usage.
 
-See the controller APIs for optional arguments. 
+See the controller APIs for optional arguments.
 
 .. toctree::
    :maxdepth: 1
    :caption: Job Controllers:
-   
+
    mpi_controller
    balsam_controller
 
@@ -32,10 +32,10 @@ polled/killed (or through other job or job controller functions).
 
 Job Attributes
 --------------
-                
+
 Following is a list of job status and configuration attributes that can be retrieved from a job.
 
-:NOTE: These should not be set directly. Jobs are launched by the job controller and job information can be queired through the job attributes below and the query functions. 
+:NOTE: These should not be set directly. Jobs are launched by the job controller and job information can be queired through the job attributes below and the query functions.
 
 Job Status attributes include:
 
@@ -53,7 +53,7 @@ Run configuration attributes - Some will be auto-generated:
 :job.workdir: (string) Work directory for the job
 :job.name: (string) Name of job - auto-generated
 :job.app: (app obj) Use application/executable, registered using jobctl.register_calc
-:job.app_args: (string) Application arguments as a string  
+:job.app_args: (string) Application arguments as a string
 :job.stdout: (string) Name of file where the standard output of the job is written (in job.workdir)
 :job.stderr: (string) Name of file where the standard error of the job is written (in job.workdir)
 
diff --git a/docs/job_controller/mpi_controller.rst b/docs/job_controller/mpi_controller.rst
index f3e0915c4..117ea8293 100644
--- a/docs/job_controller/mpi_controller.rst
+++ b/docs/job_controller/mpi_controller.rst
@@ -5,8 +5,8 @@ To create an MPI job controller, the calling script should contain::
 
     jobctl = MPIJobController()
 
-See the controller API below for optional arguments.    
-    
+See the controller API below for optional arguments.
+
 .. automodule:: mpi_controller
   :no-undoc-members:
 
@@ -15,7 +15,7 @@ See the controller API below for optional arguments.
   :inherited-members:
 
   .. automethod:: __init__
-  
+
 ..  :member-order: bysource
 ..  :members: __init__, register_calc, launch, manager_poll
 
diff --git a/docs/job_controller/overview.rst b/docs/job_controller/overview.rst
index 9e34033e3..95b87bc53 100644
--- a/docs/job_controller/overview.rst
+++ b/docs/job_controller/overview.rst
@@ -13,16 +13,16 @@ cluster, or any other provision of compute resources.
 In order to remove the burden of system interaction from the user, and enable sim_f
 scripts that are portable between systems, a job_controller interface is provided by
 libEnsemble. The job_controller provides the key functions: ``launch()``, ``poll()`` and
-``kill()``. libEnsemble auto-detects a number of system criteria, such as the MPI launcher, 
+``kill()``. libEnsemble auto-detects a number of system criteria, such as the MPI launcher,
 along with correct mechanisms for polling and killing jobs, on supported systems. It also
 contains built in resilience, such as re-launching jobs that fail due to system factors.
 User scripts that employ the job_controller interface will be portable between supported
-systems. Job attributes can be queried to determine status after each poll. Functions are 
+systems. Job attributes can be queried to determine status after each poll. Functions are
 also provided to access and interrogate files in the job's working directory.
 
 The Job Controller module can be used to submit
 and manage jobs using a portable interface. Various back-end mechanisms may be
-used to implement this interface on the system, including a proxy launcher and 
+used to implement this interface on the system, including a proxy launcher and
 job management system, such as Balsam. Currently, these job_controllers launch
 at the application level within an existing resource pool. However, submissions
 to a batch schedular may be supported in the future.
@@ -62,7 +62,7 @@ In user sim func::
 
     timeout_sec = 600
     poll_delay_sec = 1
-    
+
     while(not job.finished):
 
         # Has manager sent a finish signal
@@ -82,10 +82,10 @@ In user sim func::
         else:
             time.sleep(poll_delay_sec)
             job.poll()
-    
+
     print(job.state)  # state may be finished/failed/killed
 
-See the :doc:`job_controller<job_controller>` interface for API.  
+See the :doc:`job_controller<job_controller>` interface for API.
 
 For a more realistic example see:
 
diff --git a/docs/user_funcs.rst b/docs/user_funcs.rst
index 4cc352bc6..6c8d60211 100644
--- a/docs/user_funcs.rst
+++ b/docs/user_funcs.rst
@@ -10,6 +10,6 @@ must be provided. The required API and examples are given here.
 .. toctree::
    :maxdepth: 2
    :caption: libEnsemble User Functions:
-   
+
    sim_gen_alloc_funcs
    examples/examples_index
diff --git a/examples/job_submission_scripts/bebop_submit_slurm.sh b/examples/job_submission_scripts/bebop_submit_slurm.sh
index 49f58cf81..fa2e07a18 100644
--- a/examples/job_submission_scripts/bebop_submit_slurm.sh
+++ b/examples/job_submission_scripts/bebop_submit_slurm.sh
@@ -3,9 +3,9 @@
 #SBATCH -N 4
 #SBATCH -p knlall
 ##SBATCH -A <my_project>
-#SBATCH -o tlib.%j.%N.out 
-#SBATCH -e tlib.%j.%N.error 
-#SBATCH -t 01:00:00 
+#SBATCH -o tlib.%j.%N.out
+#SBATCH -e tlib.%j.%N.error
+#SBATCH -t 01:00:00
 
 #Launch script that evenly spreads workers and adds manager to the first node.
 #Requires even distribution - either multiple workers per node or nodes per worker
@@ -43,7 +43,7 @@ fi;
 #---------------------------------------------------------------------------------------------
 #Test
 echo -e "Slurm job ID: $SLURM_JOBID"
- 
+
 #cd $PBS_O_WORKDIR
 cd $SLURM_SUBMIT_DIR
 
@@ -56,7 +56,7 @@ srun hostname | sort -u > node_list
 
 #Generate list of nodes for workers
 if [[ $MANAGER_NODE = "true" ]]; then
-  tail -n +2 node_list > worker_list  
+  tail -n +2 node_list > worker_list
 else
   cp node_list worker_list
 fi
@@ -79,9 +79,9 @@ export SLURM_HOSTFILE=machinefile.$SLURM_JOBID
 # cmd="srun --ntasks $(($NUM_WORKERS+1)) -m arbitrary python $EXE"
 cmd="srun --ntasks $(($NUM_WORKERS+1)) -m arbitrary python $EXE $LIBE_WALLCLOCK"
 
-echo The command is: $cmd 
-echo End PBS script information. 
-echo All further output is from the process being run and not the pbs script.\n\n $cmd # Print the date again -- when finished 
+echo The command is: $cmd
+echo End PBS script information.
+echo All further output is from the process being run and not the pbs script.\n\n $cmd # Print the date again -- when finished
 
 $cmd
 
diff --git a/examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh b/examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
index 48eb43026..700a8da06 100644
--- a/examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
+++ b/examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
@@ -3,12 +3,12 @@
 #SBATCH -N 5
 #SBATCH -p knlall
 ##SBATCH -A <my_project>
-#SBATCH -o tlib.%j.%N.out 
-#SBATCH -e tlib.%j.%N.error 
-#SBATCH -t 01:00:00 
+#SBATCH -o tlib.%j.%N.out
+#SBATCH -e tlib.%j.%N.error
+#SBATCH -t 01:00:00
 
 #Launch script for running in central mode.
-#LibEnsemble will run on a dedicated node (or nodes). 
+#LibEnsemble will run on a dedicated node (or nodes).
 #The remaining nodes in the allocation will be dedicated to the jobs launched by the workers.
 
 #Requirements for running:
@@ -31,7 +31,7 @@ export LIBE_WALLCLOCK=55
 #---------------------------------------------------------------------------------------------
 #Test
 echo -e "Slurm job ID: $SLURM_JOBID"
- 
+
 #cd $PBS_O_WORKDIR
 cd $SLURM_SUBMIT_DIR
 
@@ -42,9 +42,9 @@ echo -e "Directory is:  $PWD"
 #This will work for the number of contexts that will fit on one node (eg. 320 on Bebop) - increase libE nodes for more.
 cmd="srun --overcommit --ntasks=$(($NUM_WORKERS+1)) --nodes=1 python $EXE $LIBE_WALLCLOCK"
 
-echo The command is: $cmd 
-echo End PBS script information. 
-echo All further output is from the process being run and not the pbs script.\n\n $cmd # Print the date again -- when finished 
+echo The command is: $cmd
+echo End PBS script information.
+echo All further output is from the process being run and not the pbs script.\n\n $cmd # Print the date again -- when finished
 
 $cmd
 
diff --git a/examples/job_submission_scripts/blues_script.pbs b/examples/job_submission_scripts/blues_script.pbs
index f24c32d93..1afac76f1 100644
--- a/examples/job_submission_scripts/blues_script.pbs
+++ b/examples/job_submission_scripts/blues_script.pbs
@@ -24,7 +24,7 @@
 # Specify CPU time needed
 #PBS -l walltime=0:01:00
 
-# Select queue 
+# Select queue
 ##PBS -q haswell
 ##PBS -q biggpu
 ##PBS -q ivy
@@ -46,7 +46,7 @@ echo This job has allocated $NPROCS cores
 rm libE_machinefile
 # Parse the PBS_NODEFILE to a machinefile (to be used below) in order to put
 # ranks 1-4 on each of the 4 nodes, and put rank 0 (the manager) on the first
-# node as well. 
+# node as well.
 head -n 1 $PBS_NODEFILE > libE_machinefile
 cat $PBS_NODEFILE | sort | uniq >> libE_machinefile
 
@@ -57,11 +57,11 @@ echo Starting executation at: `date`
 pwd
 cmd="mpiexec -np 5 -machinefile libE_machinefile python2 libE_calling_script.py libE_machinefile"
 # This note that this command passes the libE_machinefile to both MPI and the
-# libE_calling_script, in the latter script, it can be parsed and given to the 
+# libE_calling_script, in the latter script, it can be parsed and given to the
 # alloc_func
 
 echo The command is: $cmd
-echo End PBS script information. 
+echo End PBS script information.
 echo All further output is from the process being run and not the pbs script.\n\n
 $cmd
 
diff --git a/examples/job_submission_scripts/theta_submit_balsam.sh b/examples/job_submission_scripts/theta_submit_balsam.sh
index 89a85a172..a06c7a2ae 100644
--- a/examples/job_submission_scripts/theta_submit_balsam.sh
+++ b/examples/job_submission_scripts/theta_submit_balsam.sh
@@ -29,7 +29,7 @@ export LIBE_WALLCLOCK=45
 export WORKFLOW_NAME=libe_workflow #sh - todo - may currently be hardcoded to this in libE - allow user to specify
 
 #Tell libE manager to stop workers, dump timing.dat and exit after this time. Script must be set up to receive as argument.
-export SCRIPT_ARGS=$(($LIBE_WALLCLOCK-3)) 
+export SCRIPT_ARGS=$(($LIBE_WALLCLOCK-3))
 # export SCRIPT_ARGS='' #Default No args
 
 # Name of Conda environment (Need to have set up: https://balsam.alcf.anl.gov/quick/quickstart.html)
diff --git a/libensemble/tests/.coveragerc b/libensemble/tests/.coveragerc
index fa2110df3..543436d73 100644
--- a/libensemble/tests/.coveragerc
+++ b/libensemble/tests/.coveragerc
@@ -4,7 +4,7 @@
 [run]
 data_file = .cov_merge_out
 
-[html]    
+[html]
 directory = cov_merge
 
 #Report files can be controlled here
diff --git a/libensemble/tests/balsam_tests/bash_scripts/setup_balsam_tests.sh b/libensemble/tests/balsam_tests/bash_scripts/setup_balsam_tests.sh
index 54b5c2302..c24234f88 100755
--- a/libensemble/tests/balsam_tests/bash_scripts/setup_balsam_tests.sh
+++ b/libensemble/tests/balsam_tests/bash_scripts/setup_balsam_tests.sh
@@ -37,7 +37,7 @@ balsam app --name $SIM_APP_NAME --exec $SIM_DIR/$SIM_APP --desc "Run $SIM_APP_NA
 for LIBE_APP in $JOB_LIST
 do
   LIBE_APP_NAME=${LIBE_APP%.*}
-  balsam app --name $LIBE_APP_NAME --exec $WORK_DIR/$LIBE_APP --desc "Run $LIBE_APP_NAME"  
+  balsam app --name $LIBE_APP_NAME --exec $WORK_DIR/$LIBE_APP --desc "Run $LIBE_APP_NAME"
 
   #Add jobs
   balsam job --name job_$LIBE_APP_NAME --workflow libe_workflow --application $LIBE_APP_NAME \
@@ -45,10 +45,10 @@ do
              --url-out="local:$WORK_DIR" \
              --stage-out-files="${JOB_NAME}*" \
              --yes
-  
+
   #Add dependency so jobs run one at a time ....
   # *** Currently all jobs added will run simultaneously - kills may be an issue there
-  
+
 done
 
 echo -e "\nListing apps:"
diff --git a/libensemble/tests/balsam_tests/readme.rst b/libensemble/tests/balsam_tests/readme.rst
index 4939e9e51..6a309984b 100644
--- a/libensemble/tests/balsam_tests/readme.rst
+++ b/libensemble/tests/balsam_tests/readme.rst
@@ -13,7 +13,7 @@ If the instructions are followed to set up a conda environment called balsam, th
 Quickstart - Balsam tests for libensemble
 -----------------------------------------
 
-Having set up balsam, the tests here can be run as follows.  
+Having set up balsam, the tests here can be run as follows.
 
 **i) Set up the tests**
 
@@ -66,9 +66,9 @@ Register tests:
 .. code-block:: bash
 
     balsam app --name test_balsam_1__runjobs     --exec test_balsam_1__runjobs.py     --desc "Run balsam test 1"
-    
+
     balsam app --name test_balsam_2__workerkill  --exec test_balsam_2__workerkill.py  --desc "Run balsam test 2"
-    
+
     balsam app --name test_balsam_3__managerkill --exec test_balsam_3__managerkill.py --desc "Run balsam test 3"
 
 Register user application that will be called inside tests:
@@ -121,13 +121,13 @@ In this case 4 ranks per node and 1 node are selected. This is for running on th
 Note that the user jobs (launched in a libensemble job) are registered from within the code. For staging out files, the output directory needs to somehow be accessible to the code. For the tests here, this is simply the directory of the test scripts (accessed via the __file__ variable in python). Search for dag.add_job in test scripts (eg. test_balsam_1__runjobs.py)
 
 
-To list jobs: 
+To list jobs:
 
 .. code-block:: bash
 
   balsam ls jobs
 
-To clean: 
+To clean:
 
 .. code-block:: bash
 
@@ -143,15 +143,15 @@ Launch all jobs:
 
 .. code-block:: bash
 
-  balsam launcher --consume-all 
- 
+  balsam launcher --consume-all
+
 For other launcher options:
 
 .. code-block:: bash
 
   balsam launcher -h
- 
- 
+
+
 4 Reset jobs
 ------------
 
@@ -159,7 +159,7 @@ A script to reset the tests is available: reset_balsam_tests.py
 
 This script can be modified easily. However, to reset from the command line - without removing and re-adding jobs you can do the following.
 
- 
+
 Note: After running tests the balsam job database will contain something like the following (job_ids abbreviated for space):
 
 .. code-block:: bash
@@ -167,7 +167,7 @@ Note: After running tests the balsam job database will contain something like th
   $ balsam ls jobs
 
 ::
-  
+
      job_id            | name                            | workflow       | application    | latest update
     -------------------------------------------------------------------------------------------------------------
      29add031-8e7c-... | job_balsam1                     | libe_workflow  | test_balsam_1  | [01-30-2018 18:57:47 JOB_FINISHED]
@@ -196,7 +196,7 @@ To remove only the generated jobs you can just use a sub-string of the job name
      job_id            | name             | workflow        | application      | latest update
     -----------------------------------------------------------------------------------------------------------------------
      29add031-8e7c-... | job_balsam1      | libe_workflow   | test_balsam_1    | [01-30-2018 18:57:47 JOB_FINISHED]
-    
+
 
 To run again - change status attribute to READY (you need to specify job_id - an abbreviation is ok) eg:
 
diff --git a/libensemble/tests/regression_tests/.coveragerc b/libensemble/tests/regression_tests/.coveragerc
index c55ce25e9..25dfd8d59 100644
--- a/libensemble/tests/regression_tests/.coveragerc
+++ b/libensemble/tests/regression_tests/.coveragerc
@@ -9,7 +9,7 @@ omit =
     */branin_*/*
 
 branch = true
- 
+
 data_file = .cov_reg_out
 
 parallel = true
@@ -26,5 +26,5 @@ omit =
 exclude_lines =
     if __name__ == .__main__.:
 
-[html]    
+[html]
 directory = cov_reg
diff --git a/libensemble/tests/scaling_tests/forces/balsam_local.sh b/libensemble/tests/scaling_tests/forces/balsam_local.sh
index dd7828fea..9e447b743 100755
--- a/libensemble/tests/scaling_tests/forces/balsam_local.sh
+++ b/libensemble/tests/scaling_tests/forces/balsam_local.sh
@@ -12,7 +12,7 @@ export EXE=run_libe_forces.py
 export NUM_WORKERS=2
 
 # Name of working directory where Balsam places running jobs/output (inside the database directory)
-export WORKFLOW_NAME=libe_workflow 
+export WORKFLOW_NAME=libe_workflow
 
 export SCRIPT_ARGS=$NUM_WORKERS
 
diff --git a/libensemble/tests/scaling_tests/forces/clone.sh b/libensemble/tests/scaling_tests/forces/clone.sh
index 80f7bed07..a0f491179 100644
--- a/libensemble/tests/scaling_tests/forces/clone.sh
+++ b/libensemble/tests/scaling_tests/forces/clone.sh
@@ -3,11 +3,11 @@ then
   echo -e "Need output dir name: ./clone NEW_DIR"
 else
   NEWDIR=$1
-  
+
   INPUTS="sim/ forces.c forces_simf.py \
           run_libe_forces.py forces.x \
           *.sh"
   # Take you there if source script.
-  mkdir ../$NEWDIR && cp -rp $INPUTS ../$NEWDIR && cd ../$NEWDIR 
+  mkdir ../$NEWDIR && cp -rp $INPUTS ../$NEWDIR && cd ../$NEWDIR
 fi
 
diff --git a/libensemble/tests/scaling_tests/forces/readme.md b/libensemble/tests/scaling_tests/forces/readme.md
index 39490cbfd..68cf8899f 100644
--- a/libensemble/tests/scaling_tests/forces/readme.md
+++ b/libensemble/tests/scaling_tests/forces/readme.md
@@ -11,17 +11,17 @@ code for a libEnsemble sim func.
 A system of charged particles is set up and simulated over a number of time-steps.
 
 Particles position and charge are initiated by a random stream.
-Particles are replicated on all ranks. 
+Particles are replicated on all ranks.
 **Each rank** computes forces for a subset of particles (O(N^2))
 Particle force arrays are allreduced across ranks.
 Particles are moved (replicated on each rank)
 Total energy is appended to file forces.stat
 
 To run forces as a standalone executable on N procs:
-    
+
     mpirun -np N ./forces.x <NUM_PARTICLES> <NUM_TIMESTEPS> <SEED>
 
-    
+
 ### Running with libEnsemble.
 
 A random sample of seeds is taken and used as imput to the sim func (forces miniapp).
@@ -61,7 +61,7 @@ While the key output files will be copied back to the run dir at completion. Als
 the log in `<DIR>/log` if there are any issues. To run on batch systems, see the example
 scripts such as `theta_submit_balsam.sh`.
 
-    
+
 ### Using batch scripts
 
 The scripts are set up assuming a conda environment. To use script directly you will need to replace the following templated values:
diff --git a/libensemble/tests/scaling_tests/forces/summit_submit_mproc.sh b/libensemble/tests/scaling_tests/forces/summit_submit_mproc.sh
index f10d1d344..2279b50dd 100644
--- a/libensemble/tests/scaling_tests/forces/summit_submit_mproc.sh
+++ b/libensemble/tests/scaling_tests/forces/summit_submit_mproc.sh
@@ -21,7 +21,7 @@ export EXE=run_libe_forces.py
 # Wallclock for libE. Slightly smaller than job wallclock
 #export LIBE_WALLCLOCK=15 # Optional if pass to script
 
-# Name of Conda environment 
+# Name of Conda environment
 export CONDA_ENV_NAME=<conda_env_name>
 
 export LIBE_PLOTS=true # Require plot scripts in $PLOT_DIR (see at end)
@@ -38,13 +38,13 @@ export PYTHONNOUSERSITE=1
 # hash -d python # Check pick up python in conda env
 hash -r # Check no commands hashed (pip/python...)
 
-# Launch libE. 
+# Launch libE.
 #python $EXE $NUM_WORKERS $LIBE_WALLCLOCK > out.txt 2>&1
 #python $EXE $NUM_WORKERS > out.txt 2>&1
 python $EXE > out.txt 2>&1
 
 if [[ $LIBE_PLOTS = "true" ]]; then
   python $PLOT_DIR/plot_libe_calcs_util_v_time.py
-  python $PLOT_DIR/plot_libe_runs_util_v_time.py  
+  python $PLOT_DIR/plot_libe_runs_util_v_time.py
   python $PLOT_DIR/plot_libE_histogram.py
 fi
diff --git a/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh b/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh
index b24a7010d..d51a5692f 100755
--- a/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh
+++ b/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh
@@ -25,7 +25,7 @@ export LIBE_WALLCLOCK=25
 export WORKFLOW_NAME=libe_workflow #sh - todo - may currently be hardcoded to this in libE - allow user to specify
 
 #Tell libE manager to stop workers, dump timing.dat and exit after this time. Script must be set up to receive as argument.
-export SCRIPT_ARGS=$(($LIBE_WALLCLOCK-5)) 
+export SCRIPT_ARGS=$(($LIBE_WALLCLOCK-5))
 # export SCRIPT_ARGS='' #Default No args
 
 # Name of Conda environment (Need to have set up: https://balsam.alcf.anl.gov/quick/quickstart.html)
@@ -95,7 +95,7 @@ if [[ $LIBE_PLOTS = "true" ]]; then
 
 if [[ $BALSAM_PLOTS = "true" ]]; then
 #   export MPLBACKEND=TkAgg
-  python $PLOT_DIR/plot_util_v_time.py  
+  python $PLOT_DIR/plot_util_v_time.py
   python $PLOT_DIR/plot_jobs_v_time.py
   python $PLOT_DIR/plot_waiting_v_time.py
 fi
diff --git a/libensemble/tests/scaling_tests/forces/theta_submit_mproc.sh b/libensemble/tests/scaling_tests/forces/theta_submit_mproc.sh
index c62cc19f9..6454e4f7b 100755
--- a/libensemble/tests/scaling_tests/forces/theta_submit_mproc.sh
+++ b/libensemble/tests/scaling_tests/forces/theta_submit_mproc.sh
@@ -47,6 +47,6 @@ python $EXE > out.txt 2>&1
 
 if [[ $LIBE_PLOTS = "true" ]]; then
   python $PLOT_DIR/plot_libe_calcs_util_v_time.py
-  python $PLOT_DIR/plot_libe_runs_util_v_time.py  
+  python $PLOT_DIR/plot_libe_runs_util_v_time.py
   python $PLOT_DIR/plot_libE_histogram.py
 fi
diff --git a/libensemble/tests/standalone_tests/kill_test/log.autotest.txt b/libensemble/tests/standalone_tests/kill_test/log.autotest.txt
index 9950cfc5c..82d4865ee 100644
--- a/libensemble/tests/standalone_tests/kill_test/log.autotest.txt
+++ b/libensemble/tests/standalone_tests/kill_test/log.autotest.txt
@@ -16,7 +16,7 @@ Build the C program:
 Either run on local node - or create an allocation of nodes and run::
 
     python killtest.py <kill_type> <num_nodes> <num_procs_per_node>
-    
+
 where kill_type currently is 1 or 2. [1. is the original kill - 2. is using group ID approach]
 
 E.g Single node with 4 processes:
@@ -65,8 +65,8 @@ Cooley (intelmpi)::
 
     Two nodes with 2 processes each:
 
-    kill 1: 
-    kill 2: 
+    kill 1:
+    kill 2:
 
 Theta (intelmpi)::
 
@@ -79,18 +79,15 @@ Theta (intelmpi)::
 
     kill 1: Fails (Works with 'module unload xalt')
     kill 2: Launch does not work
-    
+
     Kill type 2:
       Detaches subprocess from controlling terminal - but ALPS uses PID to keep track of things
       so cannot do this on Theta.
-      
+
     Solution:
     Module unload xalt
-    
+
     Now kill type 1 works (presumably supported by ALPS system).
     xalt creates a wrapper around aprun - and kill just kills the wrapping process.
-    
+
     Alternative - may be to use apkill. This may work without unloading xalt - not tried.
-    
-    
-    
diff --git a/libensemble/tests/standalone_tests/kill_test/log.burn_time_test_with_top.txt b/libensemble/tests/standalone_tests/kill_test/log.burn_time_test_with_top.txt
index 5b55d0487..0ebc1535f 100644
--- a/libensemble/tests/standalone_tests/kill_test/log.burn_time_test_with_top.txt
+++ b/libensemble/tests/standalone_tests/kill_test/log.burn_time_test_with_top.txt
@@ -10,7 +10,7 @@ Instructions
 Either run on local node - or create an allocation of nodes and run::
 
     python killtest.py <kill_type> <num_nodes> <num_procs_per_node>
-    
+
 where kill_type currently is 1 or 2. [1. is the original kill - 2. is using group ID approach]
 
 Then observe "top" on target nodes for burn_time.x processes.
@@ -52,11 +52,11 @@ Cooley (intelmpi)::
 
 Theta (intelmpi)::
 
-    kill 1: 
-    kill 2: 
-    
+    kill 1:
+    kill 2:
+
+
 
-    
 2018-07-02:
 
 Two nodes with 4 processes per node:
@@ -72,17 +72,17 @@ Bebop (intelmpi)::
 
 Cooley (intelmpi)::
 
-    kill 1: 
-    kill 2: 
+    kill 1:
+    kill 2:
 
 Theta (intelmpi)::
 
-    kill 1: 
-    kill 2: 
-    
-    
-    
-Example: 
+    kill 1:
+    kill 2:
+
+
+
+Example:
 ---------------------------------------------------------------------
 
 Running on Cooley - for my dir setup (maybe should store in project space).
@@ -97,7 +97,7 @@ Make sure got intel/mpi modules loaded. Then run:
 
     ./build.sh
     python killtest.py 1 1 4  #observe with top in another shell on that node (see below)
-    python killtest.py 2 1 4  #observe with top in another shell on that node (see below) 
+    python killtest.py 2 1 4  #observe with top in another shell on that node (see below)
 
 If processes dont stop:
 
diff --git a/libensemble/tests/standalone_tests/kill_test/readme.txt b/libensemble/tests/standalone_tests/kill_test/readme.txt
index 3c1382272..a68623a49 100644
--- a/libensemble/tests/standalone_tests/kill_test/readme.txt
+++ b/libensemble/tests/standalone_tests/kill_test/readme.txt
@@ -22,7 +22,7 @@ Build the C program:
 Either run on local node - or create an allocation of nodes and run::
 
     python killtest.py <kill_type> <num_nodes> <num_procs_per_node>
-    
+
 where kill_type currently is 1 or 2. [1. is the original kill - 2. is using group ID approach]
 
 E.g Single node with 4 processes:
diff --git a/libensemble/tests/standalone_tests/mpi_launch_test/readme.txt b/libensemble/tests/standalone_tests/mpi_launch_test/readme.txt
index 222c2d984..1a853b11d 100644
--- a/libensemble/tests/standalone_tests/mpi_launch_test/readme.txt
+++ b/libensemble/tests/standalone_tests/mpi_launch_test/readme.txt
@@ -5,7 +5,7 @@ You specify the size of the outer jobs and inner jobs as follows:
     mpirun -np 16 python create_mpi_jobs.py 4
 
 runs a 16 way job, each launching a 4 processor python hello_world with a short sleep.
-    
+
 This is a good test to run to ensure basic functioning on a system, including nested launching.
 
 The test should create an output file (job_N.out) for each outer rank. A hello_world line is printed in these for each inner rank.
diff --git a/libensemble/tests/unit_tests/.coveragerc b/libensemble/tests/unit_tests/.coveragerc
index 434d58279..856148509 100644
--- a/libensemble/tests/unit_tests/.coveragerc
+++ b/libensemble/tests/unit_tests/.coveragerc
@@ -8,7 +8,7 @@ omit =
     */regression_tests/*
 
 branch = true
- 
+
 data_file = .cov_unit_out
 
 #parallel = true
@@ -21,9 +21,9 @@ omit =
     */unit_tests/*
     */regression_tests/*
 
-exclude_lines =    
+exclude_lines =
     if __name__ == .__main__.:
     comm.Abort()
 
-[html]    
+[html]
 directory = cov_unit
diff --git a/libensemble/tests/unit_tests_logger/.coveragerc b/libensemble/tests/unit_tests_logger/.coveragerc
index 0a22a922f..d09401055 100644
--- a/libensemble/tests/unit_tests_logger/.coveragerc
+++ b/libensemble/tests/unit_tests_logger/.coveragerc
@@ -8,7 +8,7 @@ omit =
     */regression_tests/*
 
 branch = true
- 
+
 data_file = .cov_unit_out3
 
 #parallel = true
@@ -22,9 +22,9 @@ omit =
     */unit_tests_nompi/*
     */regression_tests/*
 
-exclude_lines =    
+exclude_lines =
     if __name__ == .__main__.:
     comm.Abort()
 
-[html]    
+[html]
 directory = cov_unit
diff --git a/libensemble/tests/unit_tests_nompi/.coveragerc b/libensemble/tests/unit_tests_nompi/.coveragerc
index 2c9a3a53d..a919317be 100644
--- a/libensemble/tests/unit_tests_nompi/.coveragerc
+++ b/libensemble/tests/unit_tests_nompi/.coveragerc
@@ -8,7 +8,7 @@ omit =
     */regression_tests/*
 
 branch = true
- 
+
 data_file = .cov_unit_out2
 
 #parallel = true
@@ -22,9 +22,9 @@ omit =
     */unit_tests_nompi/*
     */regression_tests/*
 
-exclude_lines =    
+exclude_lines =
     if __name__ == .__main__.:
     comm.Abort()
 
-[html]    
+[html]
 directory = cov_unit
diff --git a/postproc_scripts/compare_npy.py b/postproc_scripts/compare_npy.py
index 0489ff512..c408552ce 100755
--- a/postproc_scripts/compare_npy.py
+++ b/postproc_scripts/compare_npy.py
@@ -3,7 +3,7 @@
 '''Script to compare libEnsemble history arrays in files.
 
 If two *.npy files are provided they are compared with each other.
-If one *.npy file is provided if is compared with a hard-coded expected file 
+If one *.npy file is provided if is compared with a hard-coded expected file
 (by default located at ../expected.npy)
 Default NumPy tolerances are used for comparison (rtol=1e-05, atol=1e-08) and
 Nans compare as equal. Variable fields (such as those containing a time)
@@ -19,7 +19,7 @@
 elif len(sys.argv) > 1:
     results = np.load(sys.argv[1])
     exp_results_file = "../expected.npy"
-    exp_results = np.load(exp_results_file)    
+    exp_results = np.load(exp_results_file)
 else:
     print('You need to supply an .npy file - aborting')
     sys.exit()
diff --git a/postproc_scripts/plot_libE_histogram.py b/postproc_scripts/plot_libE_histogram.py
index dd71ca57a..020196523 100755
--- a/postproc_scripts/plot_libE_histogram.py
+++ b/postproc_scripts/plot_libE_histogram.py
@@ -67,7 +67,7 @@ def append_to_list(mylst, glob_list, found_time):
                     append_to_list(in_times_kill,in_times,found_time) # Assumes Time comes first
                 elif search_for_keyword(lst[i+1:len(lst)], run_exception):
                     exceptions = True
-                    append_to_list(in_times_exception,in_times,found_time) # Assumes Time comes first                
+                    append_to_list(in_times_exception,in_times,found_time) # Assumes Time comes first
                 else:
                     print('Error: Unkown status - rest of line: {}'.format(lst[i+1:len(lst)]))
                     sys.exit()
@@ -98,8 +98,8 @@ def append_to_list(mylst, glob_list, found_time):
     calc_type = 'sim'
 else:
     calc_type = 'calc'
-    
-title = 'libEnsemble histogram of ' + calc_type  + ' times' + ' (' + str(active_line_count) + ' user calcs)'  +  str(num_bins) + ' bins'   
+
+title = 'libEnsemble histogram of ' + calc_type  + ' times' + ' (' + str(active_line_count) + ' user calcs)'  +  str(num_bins) + ' bins'
 
 plt.title(title)
 plt.xlabel('Calc run-time (sec)')
diff --git a/postproc_scripts/readme.rst b/postproc_scripts/readme.rst
index 1bed83f25..ec861b81c 100644
--- a/postproc_scripts/readme.rst
+++ b/postproc_scripts/readme.rst
@@ -4,7 +4,7 @@ Timing analysis scripts
 
 Note that all plotting scripts produce a file rather than opening a plot interactively.
 
-The following scripts must be run in the directory with the **libE_stats.txt** file. They extract and plot information from that file.  
+The following scripts must be run in the directory with the **libE_stats.txt** file. They extract and plot information from that file.
 
 * **plot_libe_calcs_util_v_time.py**: Extract worker utilization v time plot (with one second sampling). Shows number of workers running user sim or gen functions over time.
 

From c166db5f2a55f2f90c902db68be2bcd8d7f404f8 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 26 Sep 2019 13:24:00 -0500
Subject: [PATCH 288/644] Removing blank lines at the end

---
 conda/environment.yml                                         | 1 -
 docs/conf.py                                                  | 3 ---
 docs/data_structures/persis_info.rst                          | 1 -
 docs/data_structures/work_dict.rst                            | 1 -
 docs/data_structures/worker_array.rst                         | 1 -
 docs/dev_guide/dev_API/worker_module.rst                      | 1 -
 .../release_management/release_platforms/rel_pypi.rst         | 3 ---
 .../release_management/release_platforms/rel_spack.rst        | 1 -
 docs/job_controller/job_controller.rst                        | 1 -
 docs/job_controller/mpi_controller.rst                        | 4 ----
 docs/job_controller/overview.rst                              | 1 -
 docs/sim_gen_alloc_funcs.rst                                  | 1 -
 .../tests/balsam_tests/bash_scripts/setup_balsam_tests.sh     | 1 -
 libensemble/tests/balsam_tests/readme.balsam_tests.txt        | 1 -
 libensemble/tests/balsam_tests/readme.rst                     | 2 --
 libensemble/tests/controller_tests/readme.txt                 | 4 ----
 libensemble/tests/scaling_tests/forces/clone.sh               | 1 -
 libensemble/tests/standalone_tests/kill_test/build.sh         | 1 -
 .../kill_test/log.burn_time_test_with_top.txt                 | 1 -
 libensemble/tests/standalone_tests/kill_test/readme.txt       | 2 --
 20 files changed, 32 deletions(-)

diff --git a/conda/environment.yml b/conda/environment.yml
index f79b595ff..57e16c744 100644
--- a/conda/environment.yml
+++ b/conda/environment.yml
@@ -1,3 +1,2 @@
 dependencies:
  - python>=3.6
-
diff --git a/docs/conf.py b/docs/conf.py
index 0becb45d4..d4fc3b2f3 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -209,6 +209,3 @@ def __getattr__(cls, name):
      author, 'libEnsemble', 'One line description of project.',
      'Miscellaneous'),
 ]
-
-
-
diff --git a/docs/data_structures/persis_info.rst b/docs/data_structures/persis_info.rst
index 3f5bfbbd2..3f1a6e6ce 100644
--- a/docs/data_structures/persis_info.rst
+++ b/docs/data_structures/persis_info.rst
@@ -24,4 +24,3 @@ From: libEnsemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MAA.py::
 
     for i in range(MPI.COMM_WORLD.Get_size()):
         persis_info[i] = {'rand_stream': np.random.RandomState(i)} # used as a random number stream for each worker
-
diff --git a/docs/data_structures/work_dict.rst b/docs/data_structures/work_dict.rst
index 6e4bc7ec6..4c1310b34 100644
--- a/docs/data_structures/work_dict.rst
+++ b/docs/data_structures/work_dict.rst
@@ -37,4 +37,3 @@ Dictionary with integer keys ``i`` and dictionary values to be given to worker `
 |
 | For allocation functions giving work that blocks other workers, see
 | ``libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py``
-
diff --git a/docs/data_structures/worker_array.rst b/docs/data_structures/worker_array.rst
index 88420549e..e378caaf8 100644
--- a/docs/data_structures/worker_array.rst
+++ b/docs/data_structures/worker_array.rst
@@ -24,4 +24,3 @@ worker blocked by some other calculation       1          0           1
 
 * libE only receives from workers with 'active' nonzero
 * libE only calls the alloc_f if some worker has 'active' zero
-
diff --git a/docs/dev_guide/dev_API/worker_module.rst b/docs/dev_guide/dev_API/worker_module.rst
index 79a27b1f8..1b68af668 100644
--- a/docs/dev_guide/dev_API/worker_module.rst
+++ b/docs/dev_guide/dev_API/worker_module.rst
@@ -8,4 +8,3 @@ Worker Module
   :members:
 
   .. automethod:: __init__
-
diff --git a/docs/dev_guide/release_management/release_platforms/rel_pypi.rst b/docs/dev_guide/release_management/release_platforms/rel_pypi.rst
index 3cbdd32f3..a299dca6a 100644
--- a/docs/dev_guide/release_management/release_platforms/rel_pypi.rst
+++ b/docs/dev_guide/release_management/release_platforms/rel_pypi.rst
@@ -32,6 +32,3 @@ It should also be visible here:
 https://pypi.org/project/libensemble/
 
 For more details on creating PyPI packages see https://betterscientificsoftware.github.io/python-for-hpc/tutorials/python-pypi-packaging/
-
-
-
diff --git a/docs/dev_guide/release_management/release_platforms/rel_spack.rst b/docs/dev_guide/release_management/release_platforms/rel_spack.rst
index db058de05..7191abcfd 100644
--- a/docs/dev_guide/release_management/release_platforms/rel_spack.rst
+++ b/docs/dev_guide/release_management/release_platforms/rel_spack.rst
@@ -130,4 +130,3 @@ Quick summary for bringing develop branch on forked repo up to speed with upstre
     git push origin develop --force
 
 Reference: <https://stackoverflow.com/questions/9646167/clean-up-a-fork-and-restart-it-from-the-upstream/39628366>
-
diff --git a/docs/job_controller/job_controller.rst b/docs/job_controller/job_controller.rst
index a2a312e9b..9b0a891b0 100644
--- a/docs/job_controller/job_controller.rst
+++ b/docs/job_controller/job_controller.rst
@@ -58,4 +58,3 @@ Run configuration attributes - Some will be auto-generated:
 :job.stderr: (string) Name of file where the standard error of the job is written (in job.workdir)
 
 A list of job_controller and job functions can be found under the Job Controller Module.
-
diff --git a/docs/job_controller/mpi_controller.rst b/docs/job_controller/mpi_controller.rst
index 117ea8293..559a13a57 100644
--- a/docs/job_controller/mpi_controller.rst
+++ b/docs/job_controller/mpi_controller.rst
@@ -35,7 +35,3 @@ Example. To increase resilience against launch failures::
     jobctrl.fail_time = 5
 
 Note that an the re-try delay on launches starts at 5 seconds and increments by 5 seconds for each retry. So the 4th re-try will wait for 20 seconds before re-launching.
-
-
-
-
diff --git a/docs/job_controller/overview.rst b/docs/job_controller/overview.rst
index 95b87bc53..fa3c63748 100644
--- a/docs/job_controller/overview.rst
+++ b/docs/job_controller/overview.rst
@@ -92,4 +92,3 @@ For a more realistic example see:
 - libensemble/tests/scaling_tests/forces/
 
 which launches the forces.x application as an MPI job.
-
diff --git a/docs/sim_gen_alloc_funcs.rst b/docs/sim_gen_alloc_funcs.rst
index 6f253d24a..7e56753ba 100644
--- a/docs/sim_gen_alloc_funcs.rst
+++ b/docs/sim_gen_alloc_funcs.rst
@@ -124,4 +124,3 @@ Returns:
 
   **persis_info**: :obj:`dict`
   :doc:`(example)<data_structures/persis_info>`
-
diff --git a/libensemble/tests/balsam_tests/bash_scripts/setup_balsam_tests.sh b/libensemble/tests/balsam_tests/bash_scripts/setup_balsam_tests.sh
index c24234f88..c05e8f802 100755
--- a/libensemble/tests/balsam_tests/bash_scripts/setup_balsam_tests.sh
+++ b/libensemble/tests/balsam_tests/bash_scripts/setup_balsam_tests.sh
@@ -59,4 +59,3 @@ balsam ls jobs
 
 #Run launcher in either interactive session or via script
 echo -e "\nTo launch jobs run: balsam launcher --consume-all"
-
diff --git a/libensemble/tests/balsam_tests/readme.balsam_tests.txt b/libensemble/tests/balsam_tests/readme.balsam_tests.txt
index 7e1e51970..fd19a9616 100644
--- a/libensemble/tests/balsam_tests/readme.balsam_tests.txt
+++ b/libensemble/tests/balsam_tests/readme.balsam_tests.txt
@@ -10,4 +10,3 @@ test_balsam_3__managerkill.py:
 Process 0 sends out a kill for jobs which include sim_id_1 in their name. This will kill any such jobs in the database at the time of the kill. Note that if a job has not yet been added to database at the time of the kill, it will still run.
 
 Note that test3 exploits the fact that balsam is built on a django database, and all django functionality for manipulating the database can easily be exposed.
-
diff --git a/libensemble/tests/balsam_tests/readme.rst b/libensemble/tests/balsam_tests/readme.rst
index 6a309984b..8b4461347 100644
--- a/libensemble/tests/balsam_tests/readme.rst
+++ b/libensemble/tests/balsam_tests/readme.rst
@@ -229,5 +229,3 @@ To see time remaining:
 .. code-block:: bash
 
   qstat -fu <username>
-
-
diff --git a/libensemble/tests/controller_tests/readme.txt b/libensemble/tests/controller_tests/readme.txt
index d7212edce..ef7459e8d 100644
--- a/libensemble/tests/controller_tests/readme.txt
+++ b/libensemble/tests/controller_tests/readme.txt
@@ -47,7 +47,3 @@ and:
 > balsam launcher --consume-all
 
 Note: On systems like Theta only one job can be launched per node. You will need at least 2 nodes. The first will run the parent script. The test test_jobcontroller_multi.py launches 3 sub-jobs which Balsam will launch as nodes become available. To run all 3 concurrently would require 4 nodes.
-
-
-
-
diff --git a/libensemble/tests/scaling_tests/forces/clone.sh b/libensemble/tests/scaling_tests/forces/clone.sh
index a0f491179..5ce6e0ba7 100644
--- a/libensemble/tests/scaling_tests/forces/clone.sh
+++ b/libensemble/tests/scaling_tests/forces/clone.sh
@@ -10,4 +10,3 @@ else
   # Take you there if source script.
   mkdir ../$NEWDIR && cp -rp $INPUTS ../$NEWDIR && cd ../$NEWDIR
 fi
-
diff --git a/libensemble/tests/standalone_tests/kill_test/build.sh b/libensemble/tests/standalone_tests/kill_test/build.sh
index e638f0e00..8e47571e8 100755
--- a/libensemble/tests/standalone_tests/kill_test/build.sh
+++ b/libensemble/tests/standalone_tests/kill_test/build.sh
@@ -1,3 +1,2 @@
 mpicc -g -o burn_time.x burn_time.c
 mpicc -g -o sleep_and_print.x sleep_and_print.c
-
diff --git a/libensemble/tests/standalone_tests/kill_test/log.burn_time_test_with_top.txt b/libensemble/tests/standalone_tests/kill_test/log.burn_time_test_with_top.txt
index 0ebc1535f..8c16ea60a 100644
--- a/libensemble/tests/standalone_tests/kill_test/log.burn_time_test_with_top.txt
+++ b/libensemble/tests/standalone_tests/kill_test/log.burn_time_test_with_top.txt
@@ -107,4 +107,3 @@ In second shell. Log in to whatever qsub node you got:
     top
 
 Four burn_time.x processes should appear, then go, then come, then go.
-
diff --git a/libensemble/tests/standalone_tests/kill_test/readme.txt b/libensemble/tests/standalone_tests/kill_test/readme.txt
index a68623a49..1ab630b12 100644
--- a/libensemble/tests/standalone_tests/kill_test/readme.txt
+++ b/libensemble/tests/standalone_tests/kill_test/readme.txt
@@ -40,5 +40,3 @@ kill 2: python killtest.py 2 2 2
 If the test fails, an assertion error will occur.
 
 Output files are produced out_0.txt and out_1.txt (one for each job). These can be deleted between runs.
-
-

From e86709f99abd92a64f0848d15bd543c4236c0dac Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 26 Sep 2019 13:33:04 -0500
Subject: [PATCH 289/644] Why not do the same with f90 and c files

---
 .../tests/controller_tests/simdir/my_simjob.c |  18 +--
 .../controller_tests/simdir/my_simjob.f90     |  20 ++--
 .../tests/scaling_tests/forces/forces.c       | 112 +++++++++---------
 .../standalone_tests/kill_test/burn_time.c    |   6 +-
 .../kill_test/sleep_and_print.c               |  22 ++--
 .../tests/unit_tests/simdir/my_simjob.c       |  22 ++--
 .../tests/unit_tests/simdir/my_simjob.f90     |  20 ++--
 7 files changed, 110 insertions(+), 110 deletions(-)

diff --git a/libensemble/tests/controller_tests/simdir/my_simjob.c b/libensemble/tests/controller_tests/simdir/my_simjob.c
index 86fa6225d..94acb2c39 100644
--- a/libensemble/tests/controller_tests/simdir/my_simjob.c
+++ b/libensemble/tests/controller_tests/simdir/my_simjob.c
@@ -4,13 +4,13 @@
 #include <string.h>
 #include <mpi.h>
 
-int main(int argc, char **argv) 
+int main(int argc, char **argv)
 {
     int ierr, num_procs, rank, delay, error;
-        
+
     delay=3;
     error=0;
-    
+
     if (argc >=3) {
         if (strcmp( argv[1],"sleep") == 0 ) {
             delay = atoi(argv[2]);
@@ -20,23 +20,23 @@ int main(int argc, char **argv)
         if (strcmp( argv[3],"Error") == 0 ) {
             error=1;
         }
-    }    
+    }
     ierr = MPI_Init(&argc, &argv);
     ierr = MPI_Comm_rank(MPI_COMM_WORLD, &rank);
     ierr = MPI_Comm_size(MPI_COMM_WORLD, &num_procs);
-    
+
     printf("Hello world sleeping for %d seconds on rank %d of %d\n",delay, rank,num_procs);
 
     sleep(delay);
-    //printf("Woken up on rank %d of %d\n",rank,num_procs);  
-    
+    //printf("Woken up on rank %d of %d\n",rank,num_procs);
+
     if (rank==0) {
         if (error==1) {
             printf("Oh Dear! An non-fatal Error seems to have occured on rank %d\n",rank);
             sleep(delay);
         }
     }
-    
-    ierr = MPI_Finalize();   
+
+    ierr = MPI_Finalize();
     return(0);
 }
diff --git a/libensemble/tests/controller_tests/simdir/my_simjob.f90 b/libensemble/tests/controller_tests/simdir/my_simjob.f90
index 1f4d2c0c6..1a1a631ad 100644
--- a/libensemble/tests/controller_tests/simdir/my_simjob.f90
+++ b/libensemble/tests/controller_tests/simdir/my_simjob.f90
@@ -17,21 +17,21 @@ program hello_fortran
   use mpi
   use, intrinsic :: iso_c_binding, only: c_int
   use Fortran_Sleep
-  
+
   implicit none
-  
+
   integer (kind = 4) :: err
   integer (kind = 4) :: rank
   integer (kind = 4) :: nprocs
   character(len=32)  :: arg
-  character(len=32)  :: arglist(2) 
+  character(len=32)  :: arglist(2)
   integer (c_int)    :: delay,dummy
   integer            :: i
-  
+
   delay=5
   dummy = FortSleep(delay)
- 
-  
+
+
   !init in case get no args
   DO i = 1, 2
     arglist(i) = "None"
@@ -41,15 +41,15 @@ program hello_fortran
     CALL getarg(i, arg)
     arglist(i) = arg
   END DO
-  
+
   call mpi_init(err)
   call mpi_comm_size (MPI_COMM_WORLD, nprocs, err)
   call mpi_comm_rank (MPI_COMM_WORLD, rank, err)
-  
-  
+
+
 
   write(*,100) rank, nprocs, trim(arglist(1)), trim(arglist(2))
-  
+
   call MPI_Finalize (err)
 
   100 FORMAT('Hello World from proc: ',i3,' of',i3,'  arg1: ',a,'  arg2: ',a)
diff --git a/libensemble/tests/scaling_tests/forces/forces.c b/libensemble/tests/scaling_tests/forces/forces.c
index 1aebfa44b..827b7973d 100755
--- a/libensemble/tests/scaling_tests/forces/forces.c
+++ b/libensemble/tests/scaling_tests/forces/forces.c
@@ -2,16 +2,16 @@
     Naive Electostatics Code Example
     This is designed only as an artificial, highly conifurable test
     code for a libEnsemble sim func.
-    
+
     Particles position and charge are initiated by a random stream.
-    Particles are replicated on all ranks. 
+    Particles are replicated on all ranks.
     Each rank computes forces for a subset of particles.
     Particle force arrays are allreduced across ranks.
-    
+
     Run executable on N procs:
-    
+
     mpirun -np N ./forces.x <NUM_PARTICLES> <NUM_TIMESTEPS>
-    
+
     Author: S Hudson.
 -------------------------------------------------------------------- */
 
@@ -36,20 +36,20 @@ typedef struct particle {
     double p[3]; // Particle position
     double f[3]; // Particle force
     double q;    // Particle charge
-} particle;  
+} particle;
 
 
 // Seed RNG
 int seed_rand(int seed) {
-    srand(seed);    
+    srand(seed);
     return 0;
 }
 
 // Return a random number from a persistent stream
 //TODO Use parallel RNG - As replicated data can currently do on master rank.
 double get_rand() {
-    double randnum;              
-    randnum = (double)rand()/(double)(RAND_MAX + 1.0); //[0,1)    
+    double randnum;
+    randnum = (double)rand()/(double)(RAND_MAX + 1.0); //[0,1)
     return randnum;
 }
 
@@ -60,7 +60,7 @@ int build_system(int n, particle* parr) {
     int q_range_high = 10;
     double extent = 10.0;
     int i, dim;
-    
+
     for(i=0; i<n; i++) {
         for(dim=0; dim<3; dim++) {
             parr[i].p[dim] = get_rand()*extent;
@@ -78,7 +78,7 @@ int init_forces(int lower, int upper, particle* parr) {
     for(i=lower; i<upper; i++) {
         for(dim=0; dim<3; dim++) {
             parr[i].f[dim] = 0.0;
-        }        
+        }
     }
     return 0;
 }
@@ -87,12 +87,12 @@ int init_forces(int lower, int upper, particle* parr) {
 // Electostatics pairwise forces kernel (O(N^2))
 // No Eq/Opp - no reduction required (poss adv on fine-grained parallel arch).
 double forces_naive(int n, int lower, int upper, particle* parr) {
-    
+
     int i,j;
     double ret = 0.0;
     double dx, dy, dz, r, force;
 
-    for(i=lower; i<upper; i++) {          
+    for(i=lower; i<upper; i++) {
         for(j=0; j<n; j++){
             if (i==j) {
                 continue;
@@ -108,7 +108,7 @@ double forces_naive(int n, int lower, int upper, particle* parr) {
             parr[i].f[0] += dx * force;
             parr[i].f[1] += dy * force;
             parr[i].f[2] += dz * force;
-            
+
             ret += 0.5 * force;
         }
     }
@@ -119,13 +119,13 @@ double forces_naive(int n, int lower, int upper, particle* parr) {
 // Electostatics pairwise forces kernel (O(N^2))
 // Triangle loop structure (eq/opp)
 double forces_eqopp(int n, int lower, int upper, particle* parr) {
-    
+
     int i,j;
     double ret = 0.0;
     double dx, dy, dz, r, force;
 
     for(i=lower; i<upper; i++) {
-        for(j=i+1; j<n; j++) {    
+        for(j=i+1; j<n; j++) {
 
             dx = parr[i].p[0] - parr[j].p[0];
             dy = parr[i].p[1] - parr[j].p[1];
@@ -134,7 +134,7 @@ double forces_eqopp(int n, int lower, int upper, particle* parr) {
 
             //ret += parr[i].q * parr[j].q / r;
             force = parr[i].q * parr[j].q / (r*r);
-        
+
             parr[i].f[0] += dx * force;
             parr[i].f[1] += dy * force;
             parr[i].f[2] += dz * force;
@@ -142,7 +142,7 @@ double forces_eqopp(int n, int lower, int upper, particle* parr) {
             parr[j].f[0] -= dx * force;
             parr[j].f[1] -= dy * force;
             parr[j].f[2] -= dz * force;
-            
+
             ret += force;
         }
     }
@@ -179,23 +179,23 @@ int print_particles(int n, particle* parr) {
     printf("\nPrinting %d particles:\n", n);
 
     for(i=0; i<n; i++) {
-        printf("Point %4d: ",i); 
-        
+        printf("Point %4d: ",i);
+
         // Positions
         x = parr[i].p[0];
         y = parr[i].p[1];
         z = parr[i].p[2];
         printf("Pos (%6.3f, %6.3f, %6.3f)", x, y, z);
-        
+
         // Forces
         x = parr[i].f[0];
         y = parr[i].f[1];
-        z = parr[i].f[2];        
+        z = parr[i].f[2];
         printf("   Forces (%7.3f, %7.3f, %7.3f)", x, y, z);
         printf("   Charge: %.2f\n", parr[i].q);
     }
     return 0;
-} 
+}
 
 
 int print_step_summary(int step, double total_en,
@@ -211,8 +211,8 @@ int print_step_summary(int step, double total_en,
 int open_stat_file() {
     stat_fp = fopen("forces.stat", "w");
     if(stat_fp == NULL) {
-        printf("Error opening statfile");   
-        return 1;             
+        printf("Error opening statfile");
+        return 1;
     }
     fflush(stat_fp);
     return 0;
@@ -239,7 +239,7 @@ int pack_forces(int n, particle* parr, double forces[][3]) {
     int i, dim;
     for(i=0; i<n; i++) {
         for(dim=0; dim<3; dim++) {
-            forces[i][dim] = parr[i].f[dim]; 
+            forces[i][dim] = parr[i].f[dim];
         }
     }
     return 0;
@@ -249,9 +249,9 @@ int unpack_forces(int n, particle* parr, double forces[][3]) {
     int i, dim;
     for(i=0; i<n; i++) {
         for(dim=0; dim<3; dim++) {
-            parr[i].f[dim] = forces[i][dim]; 
+            parr[i].f[dim] = forces[i][dim];
         }
-    }    
+    }
     return 0;
 }
 
@@ -275,12 +275,12 @@ int test_badrun(double rate) {
 
 
 int main(int argc, char **argv) {
-    
+
     int num_particles = 10; // default no. of particles
     int num_steps = 10; // default no. of timesteps
     int rand_seed = 1; // default seed
     double kill_rate = 0; // default proportion of jobs to kill
-    
+
     int ierr, rank, num_procs, k, m, p_lower, p_upper, local_n;
     int step;
     double compute_forces_time, comms_time, total_time;
@@ -288,90 +288,90 @@ int main(int argc, char **argv) {
     double local_en, total_en;
     double step_survival_rate;
     int badrun = 0;
-    
+
     if (argc >=2) {
         num_particles = atoi(argv[1]); // no. of particles
     }
-    
+
     if (argc >=3) {
         num_steps = atoi(argv[2]); // no. of timesteps
     }
-    
+
     if (argc >=4) {
         rand_seed = atoi(argv[3]); // RNG seed
         seed_rand(rand_seed);
     }
-    
+
     if (argc >=5) {
         kill_rate = atof(argv[4]); // Proportion of jobs to kill
         step_survival_rate = pow((1-kill_rate),(1.0/num_steps));
     }
-    
+
     particle* parr = malloc(num_particles * sizeof(particle));
     build_system(num_particles, parr);
     //printf("\n");
-    
+
     ierr = MPI_Init(&argc, &argv);
     ierr = MPI_Comm_rank(MPI_COMM_WORLD, &rank);
     ierr = MPI_Comm_size(MPI_COMM_WORLD, &num_procs);
-    
+
     if (rank == 0) {
         printf("Particles: %d\n",num_particles);
         printf("Timesteps: %d\n",num_steps);
         printf("MPI Ranks: %d\n",num_procs);
         printf("Random seed: %d\n",rand_seed);
     }
-    
+
     k = num_particles / num_procs;
     m = num_particles % num_procs; //Remainder = no. procs with extra particle
     p_lower = rank * k + min(rank, m);
     p_upper = (rank + 1) * k + min(rank + 1, m);
     local_n = p_upper - p_lower;
-    
+
     if (PRINT_PARTICLE_DECOMP) {
         MPI_Barrier(MPI_COMM_WORLD);
         printf("Proc: %d has %d particles\n", rank, local_n);
     }
     MPI_Barrier(MPI_COMM_WORLD);
-    fflush(stdout); 
+    fflush(stdout);
 
     if (rank == 0) {
         open_stat_file();
     }
 
-    start = clock();    
+    start = clock();
     for (step=0; step<num_steps; step++) {
-        
+
         compute_start = clock();
-        
+
         init_forces(0, num_particles, parr); // Whole array
-        
+
         local_en = forces_naive(num_particles, p_lower, p_upper, parr);
         //local_en = forces_eqopp(num_particles, p_lower, p_upper, parr);
-        
+
         compute_forces_time = (double)(clock() - compute_start)/CLOCKS_PER_SEC;
-        
+
         // Note: Will need to add barrier to get pure comms time
         comms_start = clock();
-        
+
         // Now allreduce forces and update particle positions on master
-        
+
         // Forces array reduction
-        comm_forces(num_particles, parr);       
+        comm_forces(num_particles, parr);
 
         // Scalar reduce energy
         MPI_Allreduce(&local_en, &total_en, 1, MPI_DOUBLE, MPI_SUM, MPI_COMM_WORLD);
 
         comms_time = (double)(clock() - comms_start)/CLOCKS_PER_SEC;
-        
+
         // Update positions globally (each rank replicates)
         move_particles(0, num_particles, parr);
-        
+
         if (!badrun) {
             badrun = test_badrun(step_survival_rate);
         }
-        
-        
+
+
         if (rank == 0) {
             print_step_summary(step, total_en, compute_forces_time, comms_time);
             if (badrun) {
@@ -382,11 +382,11 @@ int main(int argc, char **argv) {
             }
         }
     }
-    
+
     fflush(stdout);
     MPI_Barrier(MPI_COMM_WORLD);
     total_time = (double)(clock() - start)/CLOCKS_PER_SEC;
-    
+
     if (rank == 0) {
         printf("\nFinal total %f after total time of %.3f seconds.",total_en, total_time);
         if (badrun) {
@@ -405,6 +405,6 @@ int main(int argc, char **argv) {
         close_stat_file();
     }
     free(parr); //todo - prob do in teardown routine.
-    ierr = MPI_Finalize();   
+    ierr = MPI_Finalize();
     return 0;
 }
diff --git a/libensemble/tests/standalone_tests/kill_test/burn_time.c b/libensemble/tests/standalone_tests/kill_test/burn_time.c
index 99013ff94..7f2eed0c4 100644
--- a/libensemble/tests/standalone_tests/kill_test/burn_time.c
+++ b/libensemble/tests/standalone_tests/kill_test/burn_time.c
@@ -13,17 +13,17 @@ int main(int argc, char **argv)
     ierr = MPI_Comm_size(MPI_COMM_WORLD, &num_procs);
 
     num = 10000000000;
-    
+
     /*  for loop terminates when n is less than count */
     sum = 0.0;
     for(count = 1; count <= num; ++count)
     {
         sum += (double)(count/1000000.0);
     }
-    
+
     /* If sum is printed - job finished */
     printf("Proc %d: Sum = %f\n", rank, sum);
 
-    ierr = MPI_Finalize();     
+    ierr = MPI_Finalize();
     return 0;
 }
diff --git a/libensemble/tests/standalone_tests/kill_test/sleep_and_print.c b/libensemble/tests/standalone_tests/kill_test/sleep_and_print.c
index 1eb88301d..66d4a0ef1 100644
--- a/libensemble/tests/standalone_tests/kill_test/sleep_and_print.c
+++ b/libensemble/tests/standalone_tests/kill_test/sleep_and_print.c
@@ -9,34 +9,34 @@ int main(int argc, char **argv)
     int ierr, num_procs, rank, delay, count, num_sleeps;
     time_t start, diff;
     double time_secs;
-    
+
     delay=1;
     num_sleeps = 12;
-    
+
     ierr = MPI_Init(&argc, &argv);
     ierr = MPI_Comm_rank(MPI_COMM_WORLD, &rank);
     ierr = MPI_Comm_size(MPI_COMM_WORLD, &num_procs);
-    
+
     start = time(NULL);;
-    
+
     printf("Proc %d has started\n", rank);
     fflush(stdout);
-    
+
     for(count = 0; count < num_sleeps; ++count) {
-        
+
         sleep(delay);
         /*diff = clock() - start;
         time_secs = (double)diff/CLOCKS_PER_SEC;*/
         time_secs = (double)(time(NULL) - start);
-        
-                
+
+
         /* Flush or use stderr */
         printf("Proc %d: Printing after %f seconds\n", rank, time_secs);
-        fflush(stdout);       
+        fflush(stdout);
     }
-    
+
     printf("Proc %d has finished\n", rank);
     fflush(stdout);
-    ierr = MPI_Finalize();   
+    ierr = MPI_Finalize();
     return 0;
 }
diff --git a/libensemble/tests/unit_tests/simdir/my_simjob.c b/libensemble/tests/unit_tests/simdir/my_simjob.c
index 227b7b517..e02850f64 100644
--- a/libensemble/tests/unit_tests/simdir/my_simjob.c
+++ b/libensemble/tests/unit_tests/simdir/my_simjob.c
@@ -4,14 +4,14 @@
 #include <string.h>
 #include <mpi.h>
 
-int main(int argc, char **argv) 
+int main(int argc, char **argv)
 {
     int ierr, num_procs, rank, usec_delay, error;
     double fdelay;
-        
+
     fdelay=3.0;
     error=0;
-    
+
     if (argc >=3) {
         if (strcmp( argv[1],"sleep") == 0 ) {
             fdelay = atof(argv[2]);
@@ -21,22 +21,22 @@ int main(int argc, char **argv)
         if (strcmp( argv[3],"Error") == 0 ) {
             error=1;
         }
-    }    
+    }
     if (argc >=4) {
         if (strcmp( argv[3],"Fail") == 0 ) {
             return(1);
         }
-    }    
+    }
     ierr = MPI_Init(&argc, &argv);
     ierr = MPI_Comm_rank(MPI_COMM_WORLD, &rank);
     ierr = MPI_Comm_size(MPI_COMM_WORLD, &num_procs);
-    
+
     printf("Hello world sleeping for %f seconds on rank %d of %d\n",fdelay, rank,num_procs);
-    
+
     usec_delay = (int)(fdelay*1e6);
     usleep(usec_delay);
-    //printf("Woken up on rank %d of %d\n",rank,num_procs);  
-    
+    //printf("Woken up on rank %d of %d\n",rank,num_procs);
+
     if (rank==0) {
         if (error==1) {
             printf("Oh Dear! An non-fatal Error seems to have occured on rank %d\n",rank);
@@ -44,7 +44,7 @@ int main(int argc, char **argv)
             usleep(usec_delay);
         }
     }
-    
-    ierr = MPI_Finalize();   
+
+    ierr = MPI_Finalize();
     return(0);
 }
diff --git a/libensemble/tests/unit_tests/simdir/my_simjob.f90 b/libensemble/tests/unit_tests/simdir/my_simjob.f90
index 1f4d2c0c6..1a1a631ad 100644
--- a/libensemble/tests/unit_tests/simdir/my_simjob.f90
+++ b/libensemble/tests/unit_tests/simdir/my_simjob.f90
@@ -17,21 +17,21 @@ program hello_fortran
   use mpi
   use, intrinsic :: iso_c_binding, only: c_int
   use Fortran_Sleep
-  
+
   implicit none
-  
+
   integer (kind = 4) :: err
   integer (kind = 4) :: rank
   integer (kind = 4) :: nprocs
   character(len=32)  :: arg
-  character(len=32)  :: arglist(2) 
+  character(len=32)  :: arglist(2)
   integer (c_int)    :: delay,dummy
   integer            :: i
-  
+
   delay=5
   dummy = FortSleep(delay)
- 
-  
+
+
   !init in case get no args
   DO i = 1, 2
     arglist(i) = "None"
@@ -41,15 +41,15 @@ program hello_fortran
     CALL getarg(i, arg)
     arglist(i) = arg
   END DO
-  
+
   call mpi_init(err)
   call mpi_comm_size (MPI_COMM_WORLD, nprocs, err)
   call mpi_comm_rank (MPI_COMM_WORLD, rank, err)
-  
-  
+
+
 
   write(*,100) rank, nprocs, trim(arglist(1)), trim(arglist(2))
-  
+
   call MPI_Finalize (err)
 
   100 FORMAT('Hello World from proc: ',i3,' of',i3,'  arg1: ',a,'  arg2: ',a)

From d961726a18643f07c6465a6bcf96aa23a9bc669f Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 26 Sep 2019 13:51:46 -0500
Subject: [PATCH 290/644] move omission from report to run

---
 libensemble/tests/regression_tests/.coveragerc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/libensemble/tests/regression_tests/.coveragerc b/libensemble/tests/regression_tests/.coveragerc
index 525564f11..090c7ad5d 100644
--- a/libensemble/tests/regression_tests/.coveragerc
+++ b/libensemble/tests/regression_tests/.coveragerc
@@ -7,6 +7,8 @@ omit =
     */unit_tests_nompi/*
     */regression_tests/*
     */branin_*/*
+    balsam_controller.py
+
 
 branch = true
 
@@ -22,7 +24,6 @@ omit =
     */unit_tests/*
     */unit_tests_nompi/*
     */regression_tests/*
-    balsam_controller.py
 
 
 exclude_lines =

From e384df681b6a3792cff1336faf3d1b9460fd1541 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 26 Sep 2019 16:45:57 -0500
Subject: [PATCH 291/644] Try moving omission to /tests rc. Adds conditional
 omission on Balsam installation

---
 conda/install-balsam.py                        | 12 ++++++++++++
 libensemble/tests/.coveragerc                  |  3 ++-
 libensemble/tests/regression_tests/.coveragerc |  3 ---
 3 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index 853c84f8e..8d38e816e 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -26,8 +26,20 @@ def move_test_balsam(balsam_test):
     if not os.path.isfile(reg_dir_with_btest):
         os.rename('./conda/{}'.format(balsam_test), reg_dir_with_btest)
 
+def configure_coverage():
+    # Enables coverage of balsam_controller.py if running test
+    coveragerc = './libensemble/tests/.coveragerc'
+    with open(coveragerc, 'r') as f:
+        lines = f.readlines()
+
+    newlines = [i for i in lines if i != '    */balsam_controller.py\n']
+
+    with open(coveragerc, 'w') as f:
+        for line in newlines:
+            f.write(line)
 
 if int(sys.version[2]) >= 6:  # Balsam only supports Python 3.6+
     install_balsam()
     move_test_balsam('test_balsam_hworld.py')
+    configure_coverage()
     subprocess.run('./conda/configure-balsam-test.sh'.split())
diff --git a/libensemble/tests/.coveragerc b/libensemble/tests/.coveragerc
index fa2110df3..0888f1435 100644
--- a/libensemble/tests/.coveragerc
+++ b/libensemble/tests/.coveragerc
@@ -4,7 +4,7 @@
 [run]
 data_file = .cov_merge_out
 
-[html]    
+[html]
 directory = cov_merge
 
 #Report files can be controlled here
@@ -20,6 +20,7 @@ omit =
     */unit_tests_logger/*
     */regression_tests/*
     */sim_funcs/helloworld.py
+    */balsam_controller.py
 #    */sim_funcs/*
 #    */gen_funcs/*
 exclude_lines =
diff --git a/libensemble/tests/regression_tests/.coveragerc b/libensemble/tests/regression_tests/.coveragerc
index 090c7ad5d..25dfd8d59 100644
--- a/libensemble/tests/regression_tests/.coveragerc
+++ b/libensemble/tests/regression_tests/.coveragerc
@@ -7,8 +7,6 @@ omit =
     */unit_tests_nompi/*
     */regression_tests/*
     */branin_*/*
-    balsam_controller.py
-
 
 branch = true
 
@@ -25,7 +23,6 @@ omit =
     */unit_tests_nompi/*
     */regression_tests/*
 
-
 exclude_lines =
     if __name__ == .__main__.:
 

From 796fe2ca38d8019278432d54837dacf2ad9a0550 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 27 Sep 2019 08:35:55 -0500
Subject: [PATCH 292/644] Starting readthedocs editing branch

---
 CONTRIBUTING.rst                              |  4 ++--
 README.rst                                    |  2 +-
 .../release_platforms/rel_github.rst          | 20 +++++++++++++------
 .../release_platforms/rel_pypi.rst            | 19 ++++++++++++------
 .../release_platforms/rel_spack.rst           |  8 ++++----
 .../release_management/release_process.rst    | 11 ++++++----
 6 files changed, 41 insertions(+), 23 deletions(-)

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index ad252cb8d..8145b0009 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -1,7 +1,7 @@
 Contributing
 ============
 
-Contributions may be made via Github pull request to:
+Contributions may be made via GitHub pull request to:
 
     https://github.com/Libensemble/libensemble
 
@@ -20,7 +20,7 @@ will add issues, as appropriate, to the project board at:
     https://github.com/Libensemble/libensemble/projects
 
 By convention, user branch names should have a <type>/<name> format, where
-example types are feature, bugfix, testing, docs and experimental.
+example types are feature, bugfix, testing, docs, and experimental.
 Administrators may take a hotfix branch from the the master, which will be
 merged into master (as a patch) and develop. Administrators may also take a
 release branch off develop and merge into master and develop for a release.
diff --git a/README.rst b/README.rst
index cb73848dc..94fcca7d1 100644
--- a/README.rst
+++ b/README.rst
@@ -103,7 +103,7 @@ libEnsemble is also available in the Spack_ distribution. It can be installed fr
 
 .. _Spack: https://spack.readthedocs.io/en/latest
 
-The tests and examples can be accessed in the `github <https://github.com/Libensemble/libensemble>`_ repository.
+The tests and examples can be accessed in the `GitHub <https://github.com/Libensemble/libensemble>`_ repository.
 A `tarball <https://github.com/Libensemble/libensemble/releases/latest>`_ of the most recent release is also available.
 
 
diff --git a/docs/dev_guide/release_management/release_platforms/rel_github.rst b/docs/dev_guide/release_management/release_platforms/rel_github.rst
index 8e59107f8..da345b173 100644
--- a/docs/dev_guide/release_management/release_platforms/rel_github.rst
+++ b/docs/dev_guide/release_management/release_platforms/rel_github.rst
@@ -1,18 +1,26 @@
 .. _rel-github:
 
-Github release
+GitHub release
 ==============
 
-The administrator should follow the github instructions to draft a new release. These can currently be found at: https://help.github.com/en/articles/creating-releases
+The administrator should follow the GitHub instructions to draft a new release.
+These can currently be found at:
+https://help.github.com/en/articles/creating-releases
 
 Both the version and title will be of the form vX.Y.Z::
 
     E.g. v0.5.0.
 
-From version 1.0, these should follow semantic versioning where, where X/Y/Z are major, minor and patch revisions.
+From version 1.0, these should follow semantic versioning where, where X/Y/Z
+are major, minor and patch revisions.
 
-Prior to version 1.0, the second number may include breaking API changes, and the third number may include minor additions.
+Prior to version 1.0, the second number may include breaking API changes, and
+the third number may include minor additions.
 
-The release notes should be included in the description. These should already be in `docs/release_notes.rst`. The release nots should be copied just the current release, starting from the date. Hint: To see example of raw input click *edit* next to one of the previous releases.
+The release notes should be included in the description. These should already
+be in `docs/release_notes.rst`. The release nots should be copied just the
+current release, starting from the date. Hint: To see example of raw input
+click *edit* next to one of the previous releases.
 
-Note, unlike some platforms (e.g. PyPI), github releases can be edited or deleted once created.
+Note, unlike some platforms (e.g. PyPI), GitHub releases can be edited or
+deleted once created.
diff --git a/docs/dev_guide/release_management/release_platforms/rel_pypi.rst b/docs/dev_guide/release_management/release_platforms/rel_pypi.rst
index a299dca6a..e660f6c13 100644
--- a/docs/dev_guide/release_management/release_platforms/rel_pypi.rst
+++ b/docs/dev_guide/release_management/release_platforms/rel_pypi.rst
@@ -3,15 +3,20 @@
 PyPI release
 ============
 
-libEnsemble is released on the Python Package Index (commonly known as PyPI). This enable users to “pip install” the package.
+libEnsemble is released on the Python Package Index (commonly known as PyPI).
+This enables users to "``pip install``" the package.
 
-The package is stored on PyPI in the form of a source distribution (commonly known as a tarball). The tarball could be obtained from github, though historically this has been created with a checkout of libensemble from git.
+The package is stored on PyPI in the form of a source distribution (commonly
+known as a tarball). The tarball could be obtained from GitHub, though
+historically this has been created with a checkout of libensemble from git.
 
 
-You will need logon credentials for the libEnsemble PyPI. You will also need twine (which can be pip or conda installed).
+You will need logon credentials for the libEnsemble PyPI. You will also need
+twine (which can be pip or conda installed).
 
 
-In the package directory on the master branch (the one containing setup.py) do the following:
+In the package directory on the master branch (the one containing setup.py) do
+the following:
 
 
 Create distribution:
@@ -24,11 +29,13 @@ Upload (you will need username/password here):
     twine upload dist/*
 
 
-If you now do "pip install libensemble" it should find the new version.
+If you now do "``pip install libensemble``" it should find the new version.
 
 
 It should also be visible here:
 
 https://pypi.org/project/libensemble/
 
-For more details on creating PyPI packages see https://betterscientificsoftware.github.io/python-for-hpc/tutorials/python-pypi-packaging/
+For more details on creating PyPI packages see::
+
+https://betterscientificsoftware.github.io/python-for-hpc/tutorials/python-pypi-packaging/
diff --git a/docs/dev_guide/release_management/release_platforms/rel_spack.rst b/docs/dev_guide/release_management/release_platforms/rel_spack.rst
index 7191abcfd..851bc24f8 100644
--- a/docs/dev_guide/release_management/release_platforms/rel_spack.rst
+++ b/docs/dev_guide/release_management/release_platforms/rel_spack.rst
@@ -9,13 +9,13 @@ Introduction
 This assumes you have already:
 
  - Made a PyPI package for new version of libensemble
- - Made a github fork of Spack and cloned it to your local system.
+ - Made a GitHub fork of Spack and cloned it to your local system.
 
 Details on how to create forks can be found at: https://help.github.com/articles/fork-a-repo
 
 You now have a configuration like shown in answer at: https://stackoverflow.com/questions/6286571/are-git-forks-actually-git-clones
 
-Upstream, in this case, is the official Spack repository on github. Origin is your fork on github and Local Machine is your local clone (from your fork).
+Upstream, in this case, is the official Spack repository on GitHub. Origin is your fork on GitHub and Local Machine is your local clone (from your fork).
 
 
 Make sure SPACK_ROOT is set and spack binary is in your path::
@@ -67,7 +67,7 @@ Or to make your local machine identical to upstream repo (**WARNING** Any local
     git reset --hard upstream/develop
 
 
-(Optional) You may want to update your forked (origin) repo on github at this point.
+(Optional) You may want to update your forked (origin) repo on GitHub at this point.
 This may requires a forced push::
 
     git push origin develop --force
@@ -113,7 +113,7 @@ If OK add, commit and push to origin (forked repo)::
      git commit -am "Update libensemble"
      git push origin update_libensemble --force
 
-Once the branch is pushed to the forked repo - go to github and do a pull request from this
+Once the branch is pushed to the forked repo - go to GitHub and do a pull request from this
 branch on the fork to the develop branch on the upstream.
 
 
diff --git a/docs/dev_guide/release_management/release_process.rst b/docs/dev_guide/release_management/release_process.rst
index 48475aa87..a26c36b7d 100644
--- a/docs/dev_guide/release_management/release_process.rst
+++ b/docs/dev_guide/release_management/release_process.rst
@@ -1,12 +1,15 @@
 Release Process
 ===============
 
-This document details the current release process for libEnsemble. A release can only be undertaken by a project administrator. A project administrator should have an administrator role on the libEnsemble github,  PyPI and readthedocs pages.
+This document details the current release process for libEnsemble. A release
+can only be undertaken by a project administrator. A project administrator
+should have an administrator role on the libEnsemble GitHub, PyPI, and
+readthedocs pages.
 
 Before release
 --------------
 
-- A github issue is created with a checklist for the release.
+- A GitHub issue is created with a checklist for the release.
 
 - A release branch should be taken off develop (or develop pulls controlled).
 
@@ -43,7 +46,7 @@ An administrator will take the following steps.
 
 - Once CI tests have passed on master.
 
-  - A github release will be taken from the master (:ref:`github release<rel-github>`).
+  - A GitHub release will be taken from the master (:ref:`github release<rel-github>`).
 
   - A tarball (source distribution) will be uploaded to PyPI (:ref:`PyPI release<rel-pypi>`).
 
@@ -56,4 +59,4 @@ An administrator will take the following steps.
 After release
 -------------
 
-- Ensure all relevant github issues are closed and moved to the *Done* column on the kanban project board (inc. the release checklist).
+- Ensure all relevant GitHub issues are closed and moved to the *Done* column on the kanban project board (inc. the release checklist).

From 9e5c3d948261d6c9e01ae3a806befad39cb679ab Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 27 Sep 2019 10:27:02 -0500
Subject: [PATCH 293/644] Clarify and update macOS Security Prompts

---
 docs/FAQ.rst | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/docs/FAQ.rst b/docs/FAQ.rst
index a535a7655..7ece89094 100644
--- a/docs/FAQ.rst
+++ b/docs/FAQ.rst
@@ -142,18 +142,18 @@ error.
 macOS - Firewall prompts
 ------------------------
 
-**macOS - System constantly prompts Firewall Security Permission windows throughout execution**
+**macOS - Constant Firewall Security permission windows throughout Job Controller task**
 
 
-There are several ways to address this nuisance. One easy (but insecure) solution is
-temporarily disabling the Firewall through System Preferences -> Security & Privacy
--> Firewall -> Turn Off Firewall. Alternatively, adding a Firewall "Allow incoming
-connections" rule can be tried for the offending Python installations,
-but this may not prevent the prompts and only clear them shortly after appearing.
-Finally, `Signing your Python installation with a self-signed certificate`_ may
-be effective.
+There are several ways to address this nuisance, but all involve trial and error.
+One easy (but insecure) solution is temporarily disabling the Firewall through System Preferences
+-> Security & Privacy -> Firewall -> Turn Off Firewall. Alternatively, adding a Firewall "Allow incoming
+connections" rule can be tried for the offending Job Controller executable.
+Based on a suggestion from here here_, we've had the most success running
+``sudo codesign --force --deep --sign - /path/to/application.app`` on our Job Controller executables,
+then confirming the next alerts for the executable and ``mpiexec.hydra``.
 
-.. _`Signing your Python installation with a self-signed certificate`: https://coderwall.com/p/5b_apq/stop-mac-os-x-firewall-from-prompting-with-python-in-virtualenv
+.. _`here`: https://coderwall.com/p/5b_apq/stop-mac-os-x-firewall-from-prompting-with-python-in-virtualenv
 
 
 Running out of contexts when running libEnsemble in distributed mode on TMI fabric

From eecc30ec6c3091436c2cf9df46784aee02aebbf2 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 27 Sep 2019 10:42:31 -0500
Subject: [PATCH 294/644] extra here

---
 docs/FAQ.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/FAQ.rst b/docs/FAQ.rst
index 7ece89094..84ebef677 100644
--- a/docs/FAQ.rst
+++ b/docs/FAQ.rst
@@ -149,7 +149,7 @@ There are several ways to address this nuisance, but all involve trial and error
 One easy (but insecure) solution is temporarily disabling the Firewall through System Preferences
 -> Security & Privacy -> Firewall -> Turn Off Firewall. Alternatively, adding a Firewall "Allow incoming
 connections" rule can be tried for the offending Job Controller executable.
-Based on a suggestion from here here_, we've had the most success running
+Based on a suggestion from here_, we've had the most success running
 ``sudo codesign --force --deep --sign - /path/to/application.app`` on our Job Controller executables,
 then confirming the next alerts for the executable and ``mpiexec.hydra``.
 

From d3fd0611b5f326e62fe8f9113c444061c50951e4 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 27 Sep 2019 10:56:34 -0500
Subject: [PATCH 295/644] Some edits

---
 .../release_platforms/rel_github.rst          |  6 ++--
 .../release_platforms/rel_pypi.rst            |  8 ++---
 .../release_platforms/rel_spack.rst           | 13 ++++----
 docs/quickstart.rst                           | 30 +++++++++++--------
 libensemble/tests/balsam_tests/readme.rst     |  8 ++---
 libensemble/tests/run-tests.sh                |  4 +--
 .../tests/scaling_tests/forces/readme.md      | 10 ++++++-
 .../standalone_tests/kill_test/readme.txt     | 23 ++++++++++----
 .../mpi_launch_test/readme.txt                | 16 ++++++----
 9 files changed, 72 insertions(+), 46 deletions(-)

diff --git a/docs/dev_guide/release_management/release_platforms/rel_github.rst b/docs/dev_guide/release_management/release_platforms/rel_github.rst
index da345b173..f4173aac3 100644
--- a/docs/dev_guide/release_management/release_platforms/rel_github.rst
+++ b/docs/dev_guide/release_management/release_platforms/rel_github.rst
@@ -7,9 +7,7 @@ The administrator should follow the GitHub instructions to draft a new release.
 These can currently be found at:
 https://help.github.com/en/articles/creating-releases
 
-Both the version and title will be of the form vX.Y.Z::
-
-    E.g. v0.5.0.
+Both the version and title will be of the form vX.Y.Z, for example, v0.5.0.
 
 From version 1.0, these should follow semantic versioning where, where X/Y/Z
 are major, minor and patch revisions.
@@ -18,7 +16,7 @@ Prior to version 1.0, the second number may include breaking API changes, and
 the third number may include minor additions.
 
 The release notes should be included in the description. These should already
-be in `docs/release_notes.rst`. The release nots should be copied just the
+be in ``docs/release_notes.rst``. The release nots should be copied just the
 current release, starting from the date. Hint: To see example of raw input
 click *edit* next to one of the previous releases.
 
diff --git a/docs/dev_guide/release_management/release_platforms/rel_pypi.rst b/docs/dev_guide/release_management/release_platforms/rel_pypi.rst
index e660f6c13..98f1b6f84 100644
--- a/docs/dev_guide/release_management/release_platforms/rel_pypi.rst
+++ b/docs/dev_guide/release_management/release_platforms/rel_pypi.rst
@@ -8,7 +8,7 @@ This enables users to "``pip install``" the package.
 
 The package is stored on PyPI in the form of a source distribution (commonly
 known as a tarball). The tarball could be obtained from GitHub, though
-historically this has been created with a checkout of libensemble from git.
+historically this has been created with a checkout of libEnsemble from git.
 
 
 You will need logon credentials for the libEnsemble PyPI. You will also need
@@ -19,12 +19,12 @@ In the package directory on the master branch (the one containing setup.py) do
 the following:
 
 
-Create distribution:
+Create distribution::
 
     python setup.py sdist
 
 
-Upload (you will need username/password here):
+Upload (you will need username/password here)::
 
     twine upload dist/*
 
@@ -36,6 +36,6 @@ It should also be visible here:
 
 https://pypi.org/project/libensemble/
 
-For more details on creating PyPI packages see::
+For more details on creating PyPI packages see:
 
 https://betterscientificsoftware.github.io/python-for-hpc/tutorials/python-pypi-packaging/
diff --git a/docs/dev_guide/release_management/release_platforms/rel_spack.rst b/docs/dev_guide/release_management/release_platforms/rel_spack.rst
index 851bc24f8..da6c73f14 100644
--- a/docs/dev_guide/release_management/release_platforms/rel_spack.rst
+++ b/docs/dev_guide/release_management/release_platforms/rel_spack.rst
@@ -8,7 +8,7 @@ Introduction
 
 This assumes you have already:
 
- - Made a PyPI package for new version of libensemble
+ - Made a PyPI package for new version of libEnsemble
  - Made a GitHub fork of Spack and cloned it to your local system.
 
 Details on how to create forks can be found at: https://help.github.com/articles/fork-a-repo
@@ -18,7 +18,7 @@ You now have a configuration like shown in answer at: https://stackoverflow.com/
 Upstream, in this case, is the official Spack repository on GitHub. Origin is your fork on GitHub and Local Machine is your local clone (from your fork).
 
 
-Make sure SPACK_ROOT is set and spack binary is in your path::
+Make sure ``SPACK_ROOT`` is set and spack binary is in your path::
 
     export SPACK_ROOT=<PATH/TO/LOCAL/SPACK/REPO>
     export PATH=$SPACK_ROOT/bin:$PATH
@@ -62,11 +62,10 @@ If you have local changes to go "on top" of latest code::
 
     git rebase upstream/develop
 
-Or to make your local machine identical to upstream repo (**WARNING** Any local changes WILL BE LOST)::
+Or to make your local machine identical to upstream repo (**WARNING** Any local changes will be lost!)::
 
     git reset --hard upstream/develop
 
-
 (Optional) You may want to update your forked (origin) repo on GitHub at this point.
 This may requires a forced push::
 
@@ -83,12 +82,12 @@ See the Spack [packaging](https://spack.readthedocs.io/en/latest/packaging_guide
 [contibution](https://spack.readthedocs.io/en/latest/contribution_guide.html) guides for more info.
 
 
-Quick example to update libensemble::
+Quick example to update libEnsemble::
 
     git branch update_libensemble
     git checkout update_libensemble
 
-This will open the libensemble package.py file in your editor (given by env variable EDITOR)::
+This will open the libEnsemble ``package.py`` file in your editor (given by env variable EDITOR)::
 
     spack edit py-libensemble  # SPACK_ROOT must be set (see above) (python packages use "py-" prefix)
 
@@ -101,7 +100,7 @@ Get the tarball (see PyPI instructions), for the new release and use::
 
     sha256sum libensemble-*.tar.gz
 
-Update the `package.py` file by pasting in the new checksum lines (and make sure url line points to latest version).
+Update the ``package.py`` file by pasting in the new checksum lines (and make sure url line points to latest version).
 Also update any dependencies for the new version.
 
 Check package::
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index cb964522b..7292a27fe 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -86,20 +86,10 @@ The example sim and gen functions and tests require the following dependencies:
 * NLopt_ - Installed with `shared libraries enabled <http://ab-initio.mit.edu/wiki/index.php/NLopt_Installation#Shared_libraries>`_.
 
 PETSc and NLopt must be built with shared libraries enabled and present in
-sys.path (e.g., via setting the PYTHONPATH environment variable). NLopt should
+sys.path (e.g., via setting the ``PYTHONPATH`` environment variable). NLopt should
 produce a file nlopt.py if Python is found on the system. NLopt may also require SWIG_
 to be installed on certain systems.
 
-.. _PETSc:  http://www.mcs.anl.gov/petsc
-.. _Python: http://www.python.org
-.. _nlopt: http://ab-initio.mit.edu/wiki/index.php/NLopt
-.. _NumPy:  http://www.numpy.org
-.. _SciPy:  http://www.scipy.org
-.. _mpi4py:  https://bitbucket.org/mpi4py/mpi4py
-.. _petsc4py:  https://bitbucket.org/petsc/petsc4py
-.. _Balsam: https://www.alcf.anl.gov/balsam
-.. _SWIG: http://swig.org/
-
 
 Installation
 ------------
@@ -129,7 +119,7 @@ regularly on:
 
 * `Travis CI <https://travis-ci.org/Libensemble/libensemble>`_
 
-The test suite requires the mock, pytest, pytest-cov and pytest-timeout
+The test suite requires the mock_, pytest_, pytest-cov_, and pytest-timeout_
 packages to be installed and can be run from the libensemble/tests directory of
 the source distribution by running::
 
@@ -169,7 +159,7 @@ Basic Usage
 The examples directory contains example libEnsemble calling scripts, sim
 functions, gen functions, alloc functions and job submission scripts.
 
-The user will create a python script to call the libEnsemble :doc:`libE<libE_module>` function.
+The user will create a python script to call the libEnsemble :doc:`libE <libE_module>` function.
 This must supply the :ref:`sim_specs<datastruct-sim-specs>` and :ref:`gen_specs<datastruct-gen-specs>`,
 and optionally :ref:`libE_specs<datastruct-libe-specs>`, :ref:`alloc_specs<datastruct-alloc-specs>` and :ref:`persis_info<datastruct-persis-info>`.
 
@@ -192,5 +182,19 @@ function used in the regression tests, which can be found in
 
 See the `user-guide <https://libensemble.readthedocs.io/en/latest/user_guide.html>`_ for more information.
 
+.. _PETSc:  http://www.mcs.anl.gov/petsc
+.. _Python: http://www.python.org
+.. _nlopt: http://ab-initio.mit.edu/wiki/index.php/NLopt
+.. _NumPy:  http://www.numpy.org
+.. _SciPy:  http://www.scipy.org
+.. _mpi4py:  https://bitbucket.org/mpi4py/mpi4py
+.. _petsc4py:  https://bitbucket.org/petsc/petsc4py
+.. _Balsam: https://www.alcf.anl.gov/balsam
+.. _SWIG: http://swig.org/
+.. _mock: https://pypi.org/project/mock
+.. _pytest: https://pypi.org/project/pytest/ 
+.. _pytest-cov: https://pypi.org/project/pytest-cov/ 
+.. _pytest-timeout: https://pypi.org/project/pytest-timeout/ 
+
 .. include:: ../README.rst
     :start-after: docs-include-tag
diff --git a/libensemble/tests/balsam_tests/readme.rst b/libensemble/tests/balsam_tests/readme.rst
index 8b4461347..d2d1ac3e5 100644
--- a/libensemble/tests/balsam_tests/readme.rst
+++ b/libensemble/tests/balsam_tests/readme.rst
@@ -10,7 +10,7 @@ Theta:
 If the instructions are followed to set up a conda environment called balsam, then the script env_setup_theta.sh, under the balsam tests dir, can be sourced in future logins for theta. Or modified for other platforms. In some platforms you may need to only activate the balsam conda environment.
 
 -----------------------------------------
-Quickstart - Balsam tests for libensemble
+Quickstart - Balsam tests for libEnsemble
 -----------------------------------------
 
 Having set up balsam, the tests here can be run as follows.
@@ -56,7 +56,7 @@ General Usage
 1. Register applications
 ------------------------
 
-You must register with balsam the parent application (eg. libensemble) and any user application (eg. sim funcs/gen funcs).
+You must register with balsam the parent application (eg. libEnsemble) and any user application (eg. sim funcs/gen funcs).
 This only need be done once - unless eg. name of application changes.
 
 Example (as used in tests) - run from within balsam_tests dir:
@@ -116,9 +116,9 @@ A log will also be created when run under hpc-edge-service/log/
 The standard output will go to file <jobname>.out. So in above case this will be job_balsam1.out which will be staged out to $WORKDIR
 
 
-In this case 4 ranks per node and 1 node are selected. This is for running on the parent application (eg. libensemble). This does not constrain the running of sub-apps (eg. helloworld), which will use the full allocation available.
+In this case 4 ranks per node and 1 node are selected. This is for running on the parent application (e.g., libEnsemble). This does not constrain the running of sub-apps (eg. helloworld), which will use the full allocation available.
 
-Note that the user jobs (launched in a libensemble job) are registered from within the code. For staging out files, the output directory needs to somehow be accessible to the code. For the tests here, this is simply the directory of the test scripts (accessed via the __file__ variable in python). Search for dag.add_job in test scripts (eg. test_balsam_1__runjobs.py)
+Note that the user jobs (launched in a libEnsemble job) are registered from within the code. For staging out files, the output directory needs to somehow be accessible to the code. For the tests here, this is simply the directory of the test scripts (accessed via the __file__ variable in python). Search for dag.add_job in test scripts (eg. test_balsam_1__runjobs.py)
 
 
 To list jobs:
diff --git a/libensemble/tests/run-tests.sh b/libensemble/tests/run-tests.sh
index e55b3a64e..669ee5d5d 100755
--- a/libensemble/tests/run-tests.sh
+++ b/libensemble/tests/run-tests.sh
@@ -302,8 +302,8 @@ hint_colour=$(tput bold;tput setaf 4) #blue
 # Exit code 5:  No tests were collected
 
 tput bold
-#echo -e "\nRunning $RUN_PREFIX libensemble Test-suite .......\n"
-echo -e "\n************** Running: Libensemble Test-Suite **************\n"
+#echo -e "\nRunning $RUN_PREFIX libEnsemble Test-suite .......\n"
+echo -e "\n************** Running: libEnsemble Test-Suite **************\n"
 tput sgr 0
 echo -e "Selected:"
 [ $RUN_UNIT_TESTS = "true" ] && echo -e "Unit Tests"
diff --git a/libensemble/tests/scaling_tests/forces/readme.md b/libensemble/tests/scaling_tests/forces/readme.md
index 68cf8899f..2ab01d893 100644
--- a/libensemble/tests/scaling_tests/forces/readme.md
+++ b/libensemble/tests/scaling_tests/forces/readme.md
@@ -98,4 +98,12 @@ If either of the plotting options in the submission scripts are set to true, the
 
 #### Note on theta_submit_balsam.sh
 
-Adjusting the node/core/worker count.: The NUM_WORKERS variable is only currently used if libEnsemble is running on one node, in which case it should be one less than the number of nodes in the job allocation (leaving one dedicated node to run libEnsemble). If more workers are used then the variables NUM_NODES and RANKS_PER_NODE need to be explicitly set (these are for libensemble which will require one task for the manager and the rest will be workers). The total node allocation (in the COBALT -n directive) will need to be the number of nodes for libEnsemble + number of nodes for each worker to launch jobs to.
+Adjusting the node/core/worker count.: The NUM_WORKERS variable is only
+currently used if libEnsemble is running on one node, in which case it should
+be one less than the number of nodes in the job allocation (leaving one
+dedicated node to run libEnsemble). If more workers are used then the variables
+NUM_NODES and RANKS_PER_NODE need to be explicitly set (these are for
+libEnsemble which will require one task for the manager and the rest will be
+workers). The total node allocation (in the COBALT -n directive) will need to
+be the number of nodes for libEnsemble + number of nodes for each worker to
+launch jobs to.
diff --git a/libensemble/tests/standalone_tests/kill_test/readme.txt b/libensemble/tests/standalone_tests/kill_test/readme.txt
index 1ab630b12..0191fd0cc 100644
--- a/libensemble/tests/standalone_tests/kill_test/readme.txt
+++ b/libensemble/tests/standalone_tests/kill_test/readme.txt
@@ -1,15 +1,24 @@
 Kill tests
 ==========
 
-This is to test the killing of MPI jobs. There are two tests and different kill methods which can be selected on the command line. The aim is that kills in libensemble will be automatically configured to work correctly based on system detection. However, this test will show what type of kill works for a given system, and this may be configurable in libensemble in the future.
+This is to test the killing of MPI jobs. There are two tests and different kill
+methods which can be selected on the command line. The aim is that kills in
+libEnsemble will be automatically configured to work correctly based on system
+detection. However, this test will show what type of kill works for a given
+system, and this may be configurable in libEnsemble in the future.
 
 Test: sleep_and_print
 
-The default test (sleep_and_print), should automatically test if all processes of an MPI job are correctly killed and also that a second job can be launched and killed.
+The default test (sleep_and_print), should automatically test if all processes
+of an MPI job are correctly killed and also that a second job can be launched
+and killed.
 
-Launching MPI jobs which write from each MPI task, at regular intervals, to an output file (see sleep_and_print.c).
+Launching MPI jobs which write from each MPI task, at regular intervals, to an
+output file (see sleep_and_print.c).
 
-This test launches a job, then kills after a few seconds, and then monitors output file to see if output continues. If the first job is succesfully killed, a second is launched and the test repeated.
+This test launches a job, then kills after a few seconds, and then monitors
+output file to see if output continues. If the first job is succesfully killed,
+a second is launched and the test repeated.
 
 Instructions
 ------------
@@ -23,7 +32,8 @@ Either run on local node - or create an allocation of nodes and run::
 
     python killtest.py <kill_type> <num_nodes> <num_procs_per_node>
 
-where kill_type currently is 1 or 2. [1. is the original kill - 2. is using group ID approach]
+where kill_type currently is 1 or 2. [1. is the original kill - 2. is using
+group ID approach]
 
 E.g Single node with 4 processes:
 --------------------------------
@@ -39,4 +49,5 @@ kill 2: python killtest.py 2 2 2
 
 If the test fails, an assertion error will occur.
 
-Output files are produced out_0.txt and out_1.txt (one for each job). These can be deleted between runs.
+Output files are produced out_0.txt and out_1.txt (one for each job). These can
+be deleted between runs.
diff --git a/libensemble/tests/standalone_tests/mpi_launch_test/readme.txt b/libensemble/tests/standalone_tests/mpi_launch_test/readme.txt
index 1a853b11d..6dc355d0b 100644
--- a/libensemble/tests/standalone_tests/mpi_launch_test/readme.txt
+++ b/libensemble/tests/standalone_tests/mpi_launch_test/readme.txt
@@ -1,13 +1,19 @@
-This test creates an mpi4py job where each processor launches MPI jobs on a node. This is an essential capability for libensemble with mpi4py.
+This test creates an mpi4py job where each processor launches MPI jobs on a
+node. This is an essential capability for libEnsemble with mpi4py.
 
 You specify the size of the outer jobs and inner jobs as follows:
 
     mpirun -np 16 python create_mpi_jobs.py 4
 
-runs a 16 way job, each launching a 4 processor python hello_world with a short sleep.
+runs a 16 way job, each launching a 4 processor python hello_world with a short
+sleep.
 
-This is a good test to run to ensure basic functioning on a system, including nested launching.
+This is a good test to run to ensure basic functioning on a system, including
+nested launching.
 
-The test should create an output file (job_N.out) for each outer rank. A hello_world line is printed in these for each inner rank.
+The test should create an output file (job_N.out) for each outer rank. A
+hello_world line is printed in these for each inner rank.
 
-Additionally it will print the total number of processes being launched (including outer and inner). This can help test, for example, if oversubscription is supported.
+Additionally it will print the total number of processes being launched
+(including outer and inner). This can help test, for example, if
+oversubscription is supported.

From a82d454866cb2ec64718f83a8841ffaa4cc0c8dc Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 27 Sep 2019 10:59:06 -0500
Subject: [PATCH 296/644] Adding a possible formatting guidelines

---
 docs/rst_formatting_guidelines | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)
 create mode 100644 docs/rst_formatting_guidelines

diff --git a/docs/rst_formatting_guidelines b/docs/rst_formatting_guidelines
new file mode 100644
index 000000000..83329a529
--- /dev/null
+++ b/docs/rst_formatting_guidelines
@@ -0,0 +1,21 @@
+
+Put variables (e.g., gen_f or H) in between double ticks ``stuff here`` (no quotes)
+
+Put short code in between double ticks ``stuff here`` (no quotes)
+
+Put referenced file names in between double ticks ``stuff here`` (no quotes)
+
+Put environment variables in between double ticks ``stuff here`` (no quotes)
+
+Put warnings line: **WARNING:** 
+
+Put breakout code snippets into a box using two colons :: 
+
+No italics on text of links
+
+Use italics for emphasis
+
+
+* Unfortunately, the Sphinx crossrefs (e.g., :doc:`ref`) are different then
+* hrefs, and they are italicized in the pdf. I assume there is a way to change
+* this formatting, but I couldn't find it.

From 8dcca8550782c364950831935e07f5bdaf46ded4 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 27 Sep 2019 12:26:50 -0500
Subject: [PATCH 297/644] More edits

---
 CONTRIBUTING.rst                         |  2 +-
 docs/FAQ.rst                             | 24 ++++++-------
 docs/data_structures/data_structures.rst |  2 +-
 docs/tutorials/local_sine_tutorial.rst   | 46 +++++++++++++-----------
 4 files changed, 40 insertions(+), 34 deletions(-)

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 8145b0009..46b5dcba6 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -8,7 +8,7 @@ Contributions may be made via GitHub pull request to:
 libEnsemble uses the Gitflow model. Contributors should branch from, and
 make pull requests to, the develop branch. The master branch is used only
 for releases. Code should pass flake8 tests, allowing for the exceptions
-given in the ".flake8" configuration file in the project directory.
+given in the ``.flake8`` configuration file in the project directory.
 
 Issues can be raised at:
 
diff --git a/docs/FAQ.rst b/docs/FAQ.rst
index 84ebef677..deae12a49 100644
--- a/docs/FAQ.rst
+++ b/docs/FAQ.rst
@@ -20,7 +20,7 @@ need to install xQuartz_.
 
 .. _xQuartz: https://www.xquartz.org/
 
-If running in ``'local'`` comms mode try using one of the ``ForkablePdb``
+If running in ``local`` comms mode try using one of the ``ForkablePdb``
 routines in ``libensemble/util/forkpdb.py`` to set breakpoints. How well these
 work may depend on the system. Usage::
 
@@ -31,7 +31,7 @@ work may depend on the system. Usage::
 AssertionError - Idle workers
 -----------------------------
 
-**"AssertionError: Should not wait for workers when all workers are idle."**
+**AssertionError: Should not wait for workers when all workers are idle.**
 
 with ``mpiexec -np 1 python [calling script].py``
 
@@ -46,7 +46,7 @@ The generator will occupy the one worker, leaving none to run simulation functio
 Not enough processors per worker to honour arguments
 ----------------------------------------------------
 
-**"libensemble.resources.ResourcesException: Not enough processors per worker to honour arguments."**
+**libensemble.resources.ResourcesException: Not enough processors per worker to honour arguments.**
 
 This is likely when using the job_controller, when there are not enough
 cores/nodes available to launch jobs. This can be disabled if you want
@@ -63,13 +63,13 @@ hyperthreads/SMT threads available.
 FileExistsError
 ---------------
 
-**"FileExistsError: [Errno 17] File exists: './sim_worker1'"**
+**FileExistsError: [Errno 17] File exists: './sim_worker1'**
 
 This can happen when libEnsemble tries to create sim directories that already exist. If
 the directory does not already exist, a possible cause is that you are trying
-to run using ``mpiexec``, when the ``libE_specs['comms']`` option is set to ``'local'``.
+to run using ``mpiexec``, when the ``libE_specs['comms']`` option is set to ``local``.
 Note that to run with differently named sub-directories you can use the
-``'sim_dir_suffix'`` option to :ref:`sim_specs<datastruct-sim-specs>`.
+``sim_dir_suffix`` option to :ref:`sim_specs<datastruct-sim-specs>`.
 
 
 libEnsemble hangs when using mpi4py
@@ -81,7 +81,7 @@ observed with Intels Truescale (TMI) fabric at time of writing. This can be solv
 either by switch fabric or turning off matching probes before the MPI module is first
 imported.
 
-Add these two lines BEFORE 'from mpi4py import MPI'::
+Add these two lines BEFORE ``from mpi4py import MPI``::
 
     import mpi4py
     mpi4py.rc.recv_mprobe = False
@@ -94,7 +94,7 @@ Messages are not received correctly when using mpi4py
 
 This may manifest itself with the following error:
 
-**"_pickle.UnpicklingError: invalid load key, '\x00'."**
+**_pickle.UnpicklingError: invalid load key, '\x00'.**
 
 or some similar variation. This has been observed with the OFA fabric. The solution
 is to either switch fabric or turn off matching probes.
@@ -115,7 +115,7 @@ PETSc and MPI errors
 with ``python [test with PETSc].py --comms local --nworkers 4``
 
 This error occurs on some platforms, including Travis, when using PETSc with libEnsemble
-in 'local' (multiprocessing) mode. We believe this is due to PETSc initializing MPI
+in ``local`` (multiprocessing) mode. We believe this is due to PETSc initializing MPI
 before libEnsemble forks processes using multiprocessing. The recommended solution
 is running libEnsemble in MPI mode. An alternative solution may be using a serial
 build of PETSc.
@@ -127,7 +127,7 @@ handles an existing MPI communicator in a particular platform.
 Fatal error in MPI_Init_thread
 ------------------------------
 
-**"Fatal error in MPI_Init_thread: Other MPI error, error stack: ... gethostbyname failed"**
+**Fatal error in MPI_Init_thread: Other MPI error, error stack: ... gethostbyname failed**
 
 
 This error may be macOS specific. MPI uses TCP to initiate connections,
@@ -161,8 +161,8 @@ Running out of contexts when running libEnsemble in distributed mode on TMI fabr
 
 The error message may be similar to below:
 
-**"can't open hfi unit: -1 (err=23)"**
-**"[13] MPI startup(): tmi fabric is not available and fallback fabric is not enabled"**
+**can't open hfi unit: -1 (err=23)**
+**[13] MPI startup(): tmi fabric is not available and fallback fabric is not enabled**
 
 This may occur on TMI when libEnsemble Python processes have been launched to a node and these,
 in turn, launch jobs on the node; creating too many processes for the available contexts. Note that
diff --git a/docs/data_structures/data_structures.rst b/docs/data_structures/data_structures.rst
index 9f0a7b52a..dc55d7ae6 100644
--- a/docs/data_structures/data_structures.rst
+++ b/docs/data_structures/data_structures.rst
@@ -1,7 +1,7 @@
 Data Structures
 ===============
 
-Users can check the formatting and consistency of ``exit_criteria`` and each ``'specs'``
+Users can check the formatting and consistency of ``exit_criteria`` and each ``specs``
 dictionary with the ``check_inputs()`` function within the ``libE module``.
 Provide any combination of these data structures as keyword arguments.
 For example::
diff --git a/docs/tutorials/local_sine_tutorial.rst b/docs/tutorials/local_sine_tutorial.rst
index 1f0b46d62..0e23fb40a 100644
--- a/docs/tutorials/local_sine_tutorial.rst
+++ b/docs/tutorials/local_sine_tutorial.rst
@@ -7,10 +7,10 @@ calculations in parallel using :doc:`libEnsemble<../quickstart>` with Python's M
 
 The foundation of writing libEnsemble routines is accounting for four components:
 
-    1. The *Generator Function* :ref:`gen_f<api_gen_f>`, which produces values for simulations.
-    2. The *Simulator Function* :ref:`sim_f<api_sim_f>`, which performs simulations based on values from ``gen_f``.
-    3. The *Allocation Function* :ref:`alloc_f<api_alloc_f>`, which decides which of the previous two functions should be called, when.
-    4. The *Calling Script*, which defines parameters and information about these functions and the libEnsemble task, then begins execution.
+    1. The generator function :ref:`gen_f<api_gen_f>`, which produces values for simulations.
+    2. The simulator function :ref:`sim_f<api_sim_f>`, which performs simulations based on values from ``gen_f``.
+    3. The allocation function :ref:`alloc_f<api_alloc_f>`, which decides which of the previous two functions should be called, when.
+    4. The calling script, which defines parameters and information about these functions and the libEnsemble task, then begins execution.
 
 libEnsemble initializes a *manager* process and as many *worker* processes as the
 user requests. The manager coordinates data-transfer between workers and assigns each
@@ -66,15 +66,22 @@ function.
 
 An available libEnsemble worker will call this generator function with the following parameters:
 
-* :ref:`H<datastruct-history-array>`: The History array. Updated by the workers with ``gen_f`` and ``sim_f`` inputs and outputs, then returned to the user. libEnsemble passes ``H`` to the generator function in case the user wants to generate new values based on previous data.
+* :ref:`H<datastruct-history-array>`: The History array. Updated by the workers
+  with ``gen_f`` and ``sim_f`` inputs and outputs, then returned to the user.
+  libEnsemble passes ``H`` to the generator function in case the user wants to
+  generate new values based on previous data.
 
-* :ref:`persis_info<datastruct-persis-info>`: Dictionary with worker-specific information. In our case this dictionary contains mechanisms called random streams for generating random numbers.
+* :ref:`persis_info<datastruct-persis-info>`: Dictionary with worker-specific
+  information. In our case this dictionary contains mechanisms called random
+  streams for generating random numbers.
 
-* :ref:`gen_specs<datastruct-gen-specs>`: Dictionary with ``gen_f`` specifications like simulation IDs, inputs and outputs, data-types, and other fields.
+* :ref:`gen_specs<datastruct-gen-specs>`: Dictionary with ``gen_f``
+  specifications like simulation IDs, inputs and outputs, data-types, and other
+  fields.
 
 Later on, we'll populate ``gen_specs`` and ``persis_info`` in our calling script.
 
-For now, create a new Python file named 'generator.py'. Write the following:
+For now, create a new Python file named ``generator.py``. Write the following:
 
 .. code-block:: python
     :linenos:
@@ -117,7 +124,7 @@ functions perform calculations based on values from the generator function.
 The only new parameter here is :ref:`sim_specs<datastruct-sim-specs>`, which serves
 a similar purpose to ``gen_specs``.
 
-Create a new Python file named 'simulator.py'. Write the following:
+Create a new Python file named ``simulator.py``. Write the following:
 
 .. code-block:: python
     :linenos:
@@ -148,7 +155,7 @@ Calling Script
 Now we can write the calling script that configures our generator and simulator
 functions and calls libEnsemble.
 
-Create an empty Python file named 'calling_script.py'.
+Create an empty Python file named ``calling_script.py``.
 In this file, we'll start by importing NumPy, libEnsemble, and the generator and
 simulator functions we just created.
 
@@ -159,7 +166,6 @@ use. Our communication method, 'local', refers to Python's Multiprocessing.
 .. code-block:: python
     :linenos:
 
-    import numpy as np
     from libensemble.libE import libE
     from generator import gen_random_sample
     from simulator import sim_find_sine
@@ -213,7 +219,7 @@ This :ref:`H<datastruct-history-array>` is the final version of the History arra
     :linenos:
 
     H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
-                              libE_specs=libE_specs)
+                                libE_specs=libE_specs)
 
     print([i for i in H.dtype.fields])            # Some (optional) statements to visualize our History array
     print(H)
@@ -302,7 +308,7 @@ Modifying the Calling Script
 """"""""""""""""""""""""""""
 
 Only a few changes are necessary to make our code MPI-compatible. Modify the top
-of the Calling Script as follows:
+of the calling script as follows:
 
 .. code-block:: python
     :linenos:
@@ -321,14 +327,14 @@ of the Calling Script as follows:
     is_master = (MPI.COMM_WORLD.Get_rank() == 0)    # master process has MPI rank 0
 
 So that only one process executes the graphing and printing portion of our code,
-modify the bottom of the Calling Script like this:
+modify the bottom of the calling script like this:
 
 .. code-block:: python
   :linenos:
   :emphasize-lines: 4
 
     H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
-                            libE_specs=libE_specs)
+                                libE_specs=libE_specs)
 
     if is_master:
 
@@ -339,15 +345,15 @@ modify the bottom of the Calling Script like this:
         colors = ['b', 'g', 'r', 'y', 'm', 'c', 'k', 'w']
 
         for i in range(1, nworkers + 1):
-          worker_xy = np.extract(H['sim_worker'] == i, H)
-          x = [entry.tolist()[0] for entry in worker_xy['x']]
-          y = [entry for entry in worker_xy['y']]
-          plt.scatter(x, y, label='Worker {}'.format(i), c=colors[i-1])
+            worker_xy = np.extract(H['sim_worker'] == i, H)
+            x = [entry.tolist()[0] for entry in worker_xy['x']]
+            y = [entry for entry in worker_xy['y']]
+            plt.scatter(x, y, label='Worker {}'.format(i), c=colors[i-1])
 
         plt.title('Sine calculations for a uniformly sampled random distribution')
         plt.xlabel('x')
         plt.ylabel('sine(x)')
-        plt.legend(loc = 'lower right')
+        plt.legend(loc='lower right')
         plt.show()
 
 With these changes in place, our libEnsemble code can be run with MPI by:

From 874aa5dc5dda1cbcd645df10434e34d93a52153a Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Tue, 1 Oct 2019 12:19:08 -0500
Subject: [PATCH 298/644] Modify test launch line

---
 libensemble/mpi_controller.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/libensemble/mpi_controller.py b/libensemble/mpi_controller.py
index 31991bbf1..32e790f12 100644
--- a/libensemble/mpi_controller.py
+++ b/libensemble/mpi_controller.py
@@ -228,8 +228,7 @@ def launch(self, calc_type, num_procs=None, num_nodes=None,
             runline.extend(job.app_args.split())
 
         if test:
-            logger.info('Test selected: Not launching job')
-            logger.info('runline args are {}'.format(runline))
+            logger.info('Test (No launch) Runline: {}'.format(' '.join(runline)))
         else:
             subgroup_launch = True
             if self.mpi_launch_type in ['aprun']:

From cbab9f1c369a2ae247aa607386b8785b3fa65132 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Tue, 1 Oct 2019 13:39:56 -0500
Subject: [PATCH 299/644] Clean up forces.c

---
 .../tests/scaling_tests/forces/forces.c       | 79 +++++++++----------
 1 file changed, 39 insertions(+), 40 deletions(-)

diff --git a/libensemble/tests/scaling_tests/forces/forces.c b/libensemble/tests/scaling_tests/forces/forces.c
index 7b99b74ca..829bc4c11 100755
--- a/libensemble/tests/scaling_tests/forces/forces.c
+++ b/libensemble/tests/scaling_tests/forces/forces.c
@@ -2,19 +2,19 @@
     Naive Electostatics Code Example
     This is designed only as an artificial, highly conifurable test
     code for a libEnsemble sim func.
-    
+
     Particles position and charge are initiated by a random stream.
     Particles are replicated on all ranks. 
     Each rank computes forces for a subset of particles.
     Particle force arrays are allreduced across ranks.
-    
+
     Sept 2019: 
     Added OpenMP options for CPU and GPU. Toggle in forces_naive function.
-    
+
     Run executable on N procs:
-    
+
     mpirun -np N ./forces.x <NUM_PARTICLES> <NUM_TIMESTEPS>
-    
+
     Author: S Hudson.
 -------------------------------------------------------------------- */
 
@@ -39,8 +39,8 @@ static FILE* stat_fp;
 
 // Return elapsed wall clock time from start/end timevals
 double elapsed(struct timeval *tv1, struct timeval *tv2) {
-    return (double)(tv2->tv_usec - tv1->tv_usec) / 1000000 
-    + (double)(tv2->tv_sec - tv1->tv_sec);  
+    return (double)(tv2->tv_usec - tv1->tv_usec) / 1000000
+    + (double)(tv2->tv_sec - tv1->tv_sec);
 }
 
 // Print from each thread.
@@ -64,7 +64,7 @@ typedef struct particle {
     double p[3]; // Particle position
     double f[3]; // Particle force
     double q;    // Particle charge
-}__attribute__((__packed__)) particle;  
+}__attribute__((__packed__)) particle;
 
 
 // Seed RNG
@@ -125,12 +125,12 @@ double forces_naive(int n, int lower, int upper, particle* parr) {
     #pragma omp target teams distribute parallel for \
                 map(to: lower,upper,n) map(tofrom: parr[0:n]) \
                 reduction(+: ret) //thread_limit(128) //*/
-                
+
     // For CPU
     //*
     #pragma omp parallel for default(none) shared(n,lower,upper,parr) \
                              private(i,j,dx,dy,dz,r,force) \
-                             reduction(+:ret)  //*/                
+                             reduction(+:ret)  //*/
     for(i=lower; i<upper; i++) {
         for(j=0; j<n; j++){
             if (i==j) {
@@ -314,67 +314,66 @@ int test_badrun(double rate) {
 
 
 int main(int argc, char **argv) {
-    
+
     int num_particles = 10; // default no. of particles
     int num_steps = 10; // default no. of timesteps
     int rand_seed = 1; // default seed
     double kill_rate = 0; // default proportion of jobs to kill
-    
+
     int ierr, rank, num_procs, k, m, p_lower, p_upper, local_n;
     int step;
     double compute_forces_time, comms_time, total_time;
-//     clock_t start, compute_start, comms_start;
     struct timeval tstart, tend;
     struct timeval compute_start, compute_end;
     struct timeval comms_start, comms_end;
-    
+
     double local_en, total_en;
     double step_survival_rate;
     int badrun = 0;
-    
+
     if (argc >=2) {
-        num_particles = atoi(argv[1]); // no. of particles
+        num_particles = atoi(argv[1]); // No. of particles
     }
-    
+
     if (argc >=3) {
-        num_steps = atoi(argv[2]); // no. of timesteps
+        num_steps = atoi(argv[2]); // No. of timesteps
     }
-    
+
     if (argc >=4) {
         rand_seed = atoi(argv[3]); // RNG seed
         seed_rand(rand_seed);
     }
-    
+
     if (argc >=5) {
         kill_rate = atof(argv[4]); // Proportion of jobs to kill
         step_survival_rate = pow((1-kill_rate),(1.0/num_steps));
     }
-    
+
     particle* parr = malloc(num_particles * sizeof(particle));
     build_system(num_particles, parr);
     //printf("\n");
-    
+
     ierr = MPI_Init(&argc, &argv);
     ierr = MPI_Comm_rank(MPI_COMM_WORLD, &rank);
     ierr = MPI_Comm_size(MPI_COMM_WORLD, &num_procs);
-    
+
     if (rank == 0) {
         printf("Particles: %d\n",num_particles);
         printf("Timesteps: %d\n",num_steps);
         printf("MPI Ranks: %d\n",num_procs);
         printf("Random seed: %d\n",rand_seed);
     }
-    
+
     if (CHECK_THREADS) {
         check_threads(rank);
     }
 
     k = num_particles / num_procs;
-    m = num_particles % num_procs; //Remainder = no. procs with extra particle
+    m = num_particles % num_procs; // Remainder = no. procs with extra particle
     p_lower = rank * k + min(rank, m);
     p_upper = (rank + 1) * k + min(rank + 1, m);
     local_n = p_upper - p_lower;
-    
+
     if (PRINT_PARTICLE_DECOMP) {
         MPI_Barrier(MPI_COMM_WORLD);
         printf("Proc: %d has %d particles\n", rank, local_n);
@@ -388,39 +387,39 @@ int main(int argc, char **argv) {
 
     gettimeofday(&tstart, NULL);
     for (step=0; step<num_steps; step++) {
-        
+
         gettimeofday(&compute_start, NULL);
-        
+
         init_forces(0, num_particles, parr); // Whole array
-        
+
         local_en = forces_naive(num_particles, p_lower, p_upper, parr);
         //local_en = forces_eqopp(num_particles, p_lower, p_upper, parr);
 
         gettimeofday(&compute_end, NULL);
         compute_forces_time = elapsed(&compute_start, &compute_end);
-        
+
         // Note: Will need to add barrier to get pure comms time
         gettimeofday(&comms_start, NULL);
-        
+
         // Now allreduce forces and update particle positions on master
-        
+
         // Forces array reduction
-        comm_forces(num_particles, parr);       
+        comm_forces(num_particles, parr);
 
         // Scalar reduce energy
         MPI_Allreduce(&local_en, &total_en, 1, MPI_DOUBLE, MPI_SUM, MPI_COMM_WORLD);
 
         gettimeofday(&comms_end, NULL);
         comms_time = elapsed(&comms_start, &comms_end);
-        
+
         // Update positions globally (each rank replicates)
         move_particles(0, num_particles, parr);
-        
+
         if (!badrun) {
             badrun = test_badrun(step_survival_rate);
         }
-        
-        
+
+
         if (rank == 0) {
             print_step_summary(step, total_en, compute_forces_time, comms_time);
             if (badrun) {
@@ -431,12 +430,12 @@ int main(int argc, char **argv) {
             }
         }
     }
-    
+
     fflush(stdout);
     MPI_Barrier(MPI_COMM_WORLD);
     gettimeofday(&tend, NULL);
     total_time = elapsed(&tstart, &tend);
-    
+
     if (rank == 0) {
         printf("\nFinal total %f after total time of %.3f seconds.",total_en, total_time);
         if (badrun) {
@@ -455,6 +454,6 @@ int main(int argc, char **argv) {
         close_stat_file();
     }
     free(parr); //todo - prob do in teardown routine.
-    ierr = MPI_Finalize();   
+    ierr = MPI_Finalize();
     return 0;
 }

From 8bad1d96fdb5fffcb4b0a2cb60186f4dcef503ad Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Tue, 1 Oct 2019 13:54:36 -0500
Subject: [PATCH 300/644] Space cleanup forces and mini_forces files

---
 .../tests/scaling_tests/forces/forces.c       | 48 +++++++++----------
 .../forces/mini_forces/mini_forces.c          | 38 +++++++--------
 .../forces/mini_forces/mini_forces_AoS.c      | 38 +++++++--------
 3 files changed, 62 insertions(+), 62 deletions(-)

diff --git a/libensemble/tests/scaling_tests/forces/forces.c b/libensemble/tests/scaling_tests/forces/forces.c
index 829bc4c11..6526b939b 100755
--- a/libensemble/tests/scaling_tests/forces/forces.c
+++ b/libensemble/tests/scaling_tests/forces/forces.c
@@ -4,11 +4,11 @@
     code for a libEnsemble sim func.
 
     Particles position and charge are initiated by a random stream.
-    Particles are replicated on all ranks. 
+    Particles are replicated on all ranks.
     Each rank computes forces for a subset of particles.
     Particle force arrays are allreduced across ranks.
 
-    Sept 2019: 
+    Sept 2019:
     Added OpenMP options for CPU and GPU. Toggle in forces_naive function.
 
     Run executable on N procs:
@@ -69,15 +69,15 @@ typedef struct particle {
 
 // Seed RNG
 int seed_rand(int seed) {
-    srand(seed);    
+    srand(seed);
     return 0;
 }
 
 // Return a random number from a persistent stream
 //TODO Use parallel RNG - As replicated data can currently do on master rank.
 double get_rand() {
-    double randnum;              
-    randnum = (double)rand()/(double)(RAND_MAX + 1.0); //[0,1)    
+    double randnum;
+    randnum = (double)rand()/(double)(RAND_MAX + 1.0); //[0,1)
     return randnum;
 }
 
@@ -88,7 +88,7 @@ int build_system(int n, particle* parr) {
     int q_range_high = 10;
     double extent = 10.0;
     int i, dim;
-    
+
     for(i=0; i<n; i++) {
         for(dim=0; dim<3; dim++) {
             parr[i].p[dim] = get_rand()*extent;
@@ -106,7 +106,7 @@ int init_forces(int lower, int upper, particle* parr) {
     for(i=lower; i<upper; i++) {
         for(dim=0; dim<3; dim++) {
             parr[i].f[dim] = 0.0;
-        }        
+        }
     }
     return 0;
 }
@@ -115,7 +115,7 @@ int init_forces(int lower, int upper, particle* parr) {
 // Electostatics pairwise forces kernel (O(N^2))
 // No Eq/Opp - no reduction required (poss adv on fine-grained parallel arch).
 double forces_naive(int n, int lower, int upper, particle* parr) {
-    
+
     int i,j;
     double ret = 0.0;
     double dx, dy, dz, r, force;
@@ -147,7 +147,7 @@ double forces_naive(int n, int lower, int upper, particle* parr) {
             parr[i].f[0] += dx * force;
             parr[i].f[1] += dy * force;
             parr[i].f[2] += dz * force;
-            
+
             ret += 0.5 * force;
         }
     }
@@ -158,13 +158,13 @@ double forces_naive(int n, int lower, int upper, particle* parr) {
 // Electostatics pairwise forces kernel (O(N^2))
 // Triangle loop structure (eq/opp)
 double forces_eqopp(int n, int lower, int upper, particle* parr) {
-    
+
     int i,j;
     double ret = 0.0;
     double dx, dy, dz, r, force;
 
     for(i=lower; i<upper; i++) {
-        for(j=i+1; j<n; j++) {    
+        for(j=i+1; j<n; j++) {
 
             dx = parr[i].p[0] - parr[j].p[0];
             dy = parr[i].p[1] - parr[j].p[1];
@@ -173,7 +173,7 @@ double forces_eqopp(int n, int lower, int upper, particle* parr) {
 
             //ret += parr[i].q * parr[j].q / r;
             force = parr[i].q * parr[j].q / (r*r);
-        
+
             parr[i].f[0] += dx * force;
             parr[i].f[1] += dy * force;
             parr[i].f[2] += dz * force;
@@ -181,7 +181,7 @@ double forces_eqopp(int n, int lower, int upper, particle* parr) {
             parr[j].f[0] -= dx * force;
             parr[j].f[1] -= dy * force;
             parr[j].f[2] -= dz * force;
-            
+
             ret += force;
         }
     }
@@ -218,23 +218,23 @@ int print_particles(int n, particle* parr) {
     printf("\nPrinting %d particles:\n", n);
 
     for(i=0; i<n; i++) {
-        printf("Point %4d: ",i); 
-        
+        printf("Point %4d: ",i);
+
         // Positions
         x = parr[i].p[0];
         y = parr[i].p[1];
         z = parr[i].p[2];
         printf("Pos (%6.3f, %6.3f, %6.3f)", x, y, z);
-        
+
         // Forces
         x = parr[i].f[0];
         y = parr[i].f[1];
-        z = parr[i].f[2];        
+        z = parr[i].f[2];
         printf("   Forces (%7.3f, %7.3f, %7.3f)", x, y, z);
         printf("   Charge: %.2f\n", parr[i].q);
     }
     return 0;
-} 
+}
 
 
 int print_step_summary(int step, double total_en,
@@ -250,8 +250,8 @@ int print_step_summary(int step, double total_en,
 int open_stat_file() {
     stat_fp = fopen("forces.stat", "w");
     if(stat_fp == NULL) {
-        printf("Error opening statfile");   
-        return 1;             
+        printf("Error opening statfile");
+        return 1;
     }
     fflush(stat_fp);
     return 0;
@@ -278,7 +278,7 @@ int pack_forces(int n, particle* parr, double forces[][3]) {
     int i, dim;
     for(i=0; i<n; i++) {
         for(dim=0; dim<3; dim++) {
-            forces[i][dim] = parr[i].f[dim]; 
+            forces[i][dim] = parr[i].f[dim];
         }
     }
     return 0;
@@ -288,9 +288,9 @@ int unpack_forces(int n, particle* parr, double forces[][3]) {
     int i, dim;
     for(i=0; i<n; i++) {
         for(dim=0; dim<3; dim++) {
-            parr[i].f[dim] = forces[i][dim]; 
+            parr[i].f[dim] = forces[i][dim];
         }
-    }    
+    }
     return 0;
 }
 
@@ -379,7 +379,7 @@ int main(int argc, char **argv) {
         printf("Proc: %d has %d particles\n", rank, local_n);
     }
     MPI_Barrier(MPI_COMM_WORLD);
-    fflush(stdout); 
+    fflush(stdout);
 
     if (rank == 0) {
         open_stat_file();
diff --git a/libensemble/tests/scaling_tests/forces/mini_forces/mini_forces.c b/libensemble/tests/scaling_tests/forces/mini_forces/mini_forces.c
index 625fac687..3bea6d782 100644
--- a/libensemble/tests/scaling_tests/forces/mini_forces/mini_forces.c
+++ b/libensemble/tests/scaling_tests/forces/mini_forces/mini_forces.c
@@ -1,28 +1,28 @@
 /* --------------------------------------------------------------------
     Non-MPI, Single Step, Electostatics Code Example
-    
+
     This is a complete working example to test threading/vectorization
     without MPI or other non-trivial features.
-    
+
     E.g: gcc build and run on 2 threads on CPU:
-    
+
     gcc -O3 -fopenmp -o mini_forces.x mini_forces.c -lm
     export OMP_NUM_THREADS=2
     ./mini_forces.x
-    
+
     E.g: xlc build and run on GPU:
-    
+
     # First toggle #omp pragma line to target in forces_naive function.
     xlc_r -O3 -qsmp=omp -qoffload -o mini_forces_xlc_gpu.x mini_forces.c
     ./mini_forces.x
-    
+
     Functionality:
     Particles position and charge are initiated by a random stream.
     Computes forces for all particles. Note: This version uses
     parallel arrays to store the data (SoA).
-    
+
     OpenMP options for CPU and GPU. Toggle in forces_naive function.
-    
+
     Author: S Hudson.
 -------------------------------------------------------------------- */
 #include <stdlib.h>
@@ -36,14 +36,14 @@
 
 // Seed RNG
 int seed_rand(int seed) {
-    srand(seed);    
+    srand(seed);
     return 0;
 }
 
 // Return a random number from a persistent stream
 double get_rand() {
-    double randnum;              
-    randnum = (double)rand()/(double)(RAND_MAX + 1.0); //[0,1)    
+    double randnum;
+    randnum = (double)rand()/(double)(RAND_MAX + 1.0); //[0,1)
     return randnum;
 }
 
@@ -54,7 +54,7 @@ int build_system(int n, double* x, double* y, double* z, double* fx, double* fy,
     int q_range_high = 10;
     double extent = 10.0;
     int i;
-    
+
     for(i=0; i<n; i++) {
         x[i] = get_rand()*extent;
         y[i] = get_rand()*extent;
@@ -74,7 +74,7 @@ int init_forces(int lower, int upper, double* fx, double* fy, double* fz) {
     for(i=lower; i<upper; i++) {
         fx[i] = 0.0;
         fy[i] = 0.0;
-        fz[i] = 0.0;       
+        fz[i] = 0.0;
     }
     return 0;
 }
@@ -133,7 +133,7 @@ double forces_naive(int n,  double* x, double* y, double* z, double* fx, double*
             fx[i] += dx * force;
             fy[i] += dy * force;
             fz[i] += dz * force;
-            
+
             ret += 0.5 * force;
         }
     }
@@ -142,15 +142,15 @@ double forces_naive(int n,  double* x, double* y, double* z, double* fx, double*
     printf ("Time taken for loop (Wallclock) = %f seconds\n",
          (double) (tv2.tv_usec - tv1.tv_usec) / 1000000 +
          (double) (tv2.tv_sec - tv1.tv_sec));
-   
+
     return ret;
 }
 
 
 int main(int argc, char **argv) {
-    
+
     int num_particles = NUM_PARTICLES;
-    double local_en;        
+    double local_en;
     double *pos_x   = malloc(num_particles * sizeof(double));
     double *pos_y   = malloc(num_particles * sizeof(double));
     double *pos_z   = malloc(num_particles * sizeof(double));
@@ -158,11 +158,11 @@ int main(int argc, char **argv) {
     double *force_y = malloc(num_particles * sizeof(double));
     double *force_z = malloc(num_particles * sizeof(double));
     double *charge  = malloc(num_particles * sizeof(double));
-    
+
     if (CHECK_THREADS) {
         check_threads();
     }
-    
+
     build_system(num_particles, pos_x, pos_y, pos_z, force_x, force_y, force_z, charge);
     init_forces(0, num_particles, force_x, force_y, force_z);
     local_en = forces_naive(num_particles, pos_x, pos_y, pos_z, force_x, force_y, force_z, charge);
diff --git a/libensemble/tests/scaling_tests/forces/mini_forces/mini_forces_AoS.c b/libensemble/tests/scaling_tests/forces/mini_forces/mini_forces_AoS.c
index 33d3b1cdb..d9462539e 100644
--- a/libensemble/tests/scaling_tests/forces/mini_forces/mini_forces_AoS.c
+++ b/libensemble/tests/scaling_tests/forces/mini_forces/mini_forces_AoS.c
@@ -1,29 +1,29 @@
 /* --------------------------------------------------------------------
     Non-MPI, Single Step, Electostatics Code Example
-    
+
     This is a complete working example to test threading/vectorization
     without MPI or other non-trivial features.
-    
+
     E.g: gcc build and run on 2 threads on CPU:
-    
+
     gcc -O3 -fopenmp -march=native -o mini_forces_AoS.x mini_forces_AoS.c -lm
     export OMP_NUM_THREADS=2
     ./mini_forces_AoS.x
-    
+
     E.g: xlc build and run on GPU:
-    
+
     # First toggle #omp pragma line to target in forces_naive function.
     xlc_r -O3 -qsmp=omp -qoffload -o mini_forces_AoS_xlc_gpu.x mini_forces_AoS.c
     ./mini_forces_AoS.x
-    
+
     Functionality:
     Particles position and charge are initiated by a random stream.
     Computes forces for all particles. Note: This version uses
     an array of structures to store the data (AoS). The forces loop
     should vectorize but will have overhead of gathers.
-    
+
     OpenMP options for CPU and GPU. Toggle in forces_naive function.
-    
+
     Author: S Hudson.
 -------------------------------------------------------------------- */
 #include <stdlib.h>
@@ -43,14 +43,14 @@ typedef struct particle {
 
 // Seed RNG
 int seed_rand(int seed) {
-    srand(seed);    
+    srand(seed);
     return 0;
 }
 
 // Return a random number from a persistent stream
 double get_rand() {
-    double randnum;              
-    randnum = (double)rand()/(double)(RAND_MAX + 1.0); //[0,1)    
+    double randnum;
+    randnum = (double)rand()/(double)(RAND_MAX + 1.0); //[0,1)
     return randnum;
 }
 
@@ -61,7 +61,7 @@ int build_system(int n, particle* parr) {
     int q_range_high = 10;
     double extent = 10.0;
     int i, dim;
-    
+
     for(i=0; i<n; i++) {
         for(dim=0; dim<3; dim++) {
             parr[i].p[dim] = get_rand()*extent;
@@ -79,7 +79,7 @@ int init_forces(int lower, int upper, particle* parr) {
     for(i=lower; i<upper; i++) {
         for(dim=0; dim<3; dim++) {
             parr[i].f[dim] = 0.0;
-        }        
+        }
     }
     return 0;
 }
@@ -143,7 +143,7 @@ double forces_naive(int n,  particle* parr) {
             fx += dx * force;
             fy += dy * force;
             fz += dz * force;
-            
+
             ret += 0.5 * force;
         }
         parr[i].f[0] += fx;
@@ -155,22 +155,22 @@ double forces_naive(int n,  particle* parr) {
     printf ("Time taken for loop (Wallclock) = %f seconds\n",
          (double) (tv2.tv_usec - tv1.tv_usec) / 1000000 +
          (double) (tv2.tv_sec - tv1.tv_sec));
-   
+
     return ret;
 }
 
 
 int main(int argc, char **argv) {
-    
+
     int num_particles = NUM_PARTICLES;
-    double local_en;        
+    double local_en;
     particle* parr = malloc(num_particles * sizeof(particle));
 
-    
+
     if (CHECK_THREADS) {
         check_threads();
     }
-    
+
     build_system(num_particles, parr);
     init_forces(0, num_particles, parr); // Whole array
     local_en = forces_naive(num_particles, parr);

From af825d5294f5256bfdf4fdae16a54146c53590a3 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 2 Oct 2019 11:31:29 -0500
Subject: [PATCH 301/644] Trying a more-modern sphinx version

---
 docs/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index d4fc3b2f3..25373417b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -53,7 +53,7 @@ def __getattr__(cls, name):
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-# needs_sphinx = '1.0'
+needs_sphinx = '2.0'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

From cc9d658772e4b19960e8762f74768b4315b789c7 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 2 Oct 2019 13:45:39 -0500
Subject: [PATCH 302/644] Change srun to kill type 1

---
 libensemble/mpi_controller.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/mpi_controller.py b/libensemble/mpi_controller.py
index c5e5f2ec8..5f4412df3 100644
--- a/libensemble/mpi_controller.py
+++ b/libensemble/mpi_controller.py
@@ -234,7 +234,7 @@ def launch(self, calc_type, num_procs=None, num_nodes=None,
             logger.info('runline args are {}'.format(runline))
         else:
             subgroup_launch = True
-            if self.mpi_launch_type in ['aprun']:
+            if self.mpi_launch_type in ['aprun', 'srun']:
                 subgroup_launch = False
 
             retry_count = 0

From 8bccb5e765ded86de37863a73b4b31919dcae558 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 2 Oct 2019 13:47:59 -0500
Subject: [PATCH 303/644] Update kill test and info for Cori

---
 .../kill_test/log.autotest.txt                | 19 ++++++++++++++++++-
 .../standalone_tests/kill_test/readme.txt     |  2 +-
 .../kill_test/sleep_and_print.c               |  2 +-
 3 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/libensemble/tests/standalone_tests/kill_test/log.autotest.txt b/libensemble/tests/standalone_tests/kill_test/log.autotest.txt
index 9950cfc5c..fcb690ba3 100644
--- a/libensemble/tests/standalone_tests/kill_test/log.autotest.txt
+++ b/libensemble/tests/standalone_tests/kill_test/log.autotest.txt
@@ -10,7 +10,7 @@ Instructions
 
 Build the C program:
     mpicc -g -o sleep_and_print.x sleep_and_print.c
-    OR (e.g. on Theta):
+    OR (e.g. on Theta/Cori):
     cc -g -o sleep_and_print.x sleep_and_print.c
 
 Either run on local node - or create an allocation of nodes and run::
@@ -55,6 +55,8 @@ Bebop (intelmpi)::
 
     kill 1: Fails
     kill 2: Works
+    
+    [*Update 2019: kill 1 seems to also work if use srun instead of mpirun]
 
 Cooley (intelmpi)::
 
@@ -93,4 +95,19 @@ Theta (intelmpi)::
     Alternative - may be to use apkill. This may work without unloading xalt - not tried.
     
     
+Cori (intelmpi - launched with srun)::
+
+    Single node on 4 processes:   
+    
+    kill 1: Works
+    kill 2: Works
+    
+    Two nodes with 2 processes each:
+
+    kill 1: Works
+    kill 2: Works
+
+    *Note: Launching of sruns from python subprocess is slow.
+
+    
     
diff --git a/libensemble/tests/standalone_tests/kill_test/readme.txt b/libensemble/tests/standalone_tests/kill_test/readme.txt
index 3c1382272..d0c00e3d1 100644
--- a/libensemble/tests/standalone_tests/kill_test/readme.txt
+++ b/libensemble/tests/standalone_tests/kill_test/readme.txt
@@ -16,7 +16,7 @@ Instructions
 
 Build the C program:
     mpicc -g -o sleep_and_print.x sleep_and_print.c
-    OR (e.g. on Theta):
+    OR (e.g. on Theta/Cori):
     cc -g -o sleep_and_print.x sleep_and_print.c
 
 Either run on local node - or create an allocation of nodes and run::
diff --git a/libensemble/tests/standalone_tests/kill_test/sleep_and_print.c b/libensemble/tests/standalone_tests/kill_test/sleep_and_print.c
index 1eb88301d..569616c4e 100644
--- a/libensemble/tests/standalone_tests/kill_test/sleep_and_print.c
+++ b/libensemble/tests/standalone_tests/kill_test/sleep_and_print.c
@@ -11,7 +11,7 @@ int main(int argc, char **argv)
     double time_secs;
     
     delay=1;
-    num_sleeps = 12;
+    num_sleeps = 16;
     
     ierr = MPI_Init(&argc, &argv);
     ierr = MPI_Comm_rank(MPI_COMM_WORLD, &rank);

From 3c71d7af49e1d484ff8a1cbac1f57ddf8f83a63f Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 2 Oct 2019 16:10:53 -0500
Subject: [PATCH 304/644] trigger unique build with small change

---
 .travis.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index 09c52672a..7b6344214 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -93,7 +93,6 @@ before_script:
   - source setbalsampath.sh
   # Allow 10000 files to be open at once (critical for persistent_aposmm)
   - ulimit -Sn 10000
-  # Set conda compilers to use new SDK instead of Travis default.
   # - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
   #       echo "export CONDA_BUILD_SYSROOT=/Users/travis/build/Libensemble/sdk/MacOSX10.14.sdk" > setenv.sh;
   #       source setenv.sh;

From bf70f8517819cf92d75b254c592fc61ad4bd8456 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 2 Oct 2019 17:25:01 -0500
Subject: [PATCH 305/644] Add node count when using hostlist on srun

This is required as the hostlist option on srun
is not exclusive.
---
 libensemble/mpi_controller.py | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/libensemble/mpi_controller.py b/libensemble/mpi_controller.py
index 63bda3764..1623c983e 100644
--- a/libensemble/mpi_controller.py
+++ b/libensemble/mpi_controller.py
@@ -89,7 +89,8 @@ def __init__(self, auto_resources=True, central_mode=False,
                       '-N {ranks_per_node}'],
             'jsrun': ['jsrun', '--np {num_procs}'],  # Need to add more
             'srun': ['srun', '-w {hostlist}', '-n {num_procs}',
-                     '--ntasks-per-node {ranks_per_node}']  # Need to add more
+                     '--nodes {num_nodes}',
+                     '--ntasks-per-node {ranks_per_node}']
         }
         self.mpi_launch_type = MPIResources.get_MPI_variant()
         self.mpi_command = mpi_commands[self.mpi_launch_type]

From 2f265c88586f0d72265697c205800dcb62872736 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 2 Oct 2019 20:28:27 -0500
Subject: [PATCH 306/644] Use hostlist if one worker per node

---
 libensemble/mpi_controller.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/libensemble/mpi_controller.py b/libensemble/mpi_controller.py
index 1623c983e..739f26a0d 100644
--- a/libensemble/mpi_controller.py
+++ b/libensemble/mpi_controller.py
@@ -126,8 +126,8 @@ def _get_mpi_specs(self, num_procs, num_nodes, ranks_per_node,
                                              ranks_per_node=ranks_per_node,
                                              hyperthreads=hyperthreads)
 
-            # Use hostlist if multiple nodes, otherwise machinefile
-            if num_nodes > 1:
+            # Use hostlist if full nodes, otherwise machinefile
+            if self.resources.worker_resources.workers_per_node == 1:
                 hostlist = self.resources.get_hostlist()
             else:
                 machinefile = "machinefile_autogen"

From e316abc606e7298a41968d4dc2bb63396a59df30 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 3 Oct 2019 10:43:35 -0500
Subject: [PATCH 307/644] attempt installing libopenblas earlier

---
 .travis.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.travis.yml b/.travis.yml
index 7b6344214..574b3d4da 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -73,6 +73,7 @@ install:
     # mkdir ../sdk; tar xf MacOSX10.14.sdk.tar.xz -C ../sdk;
   - conda install $COMPILERS
   #S- conda install nlopt petsc4py petsc mpi4py scipy $MPI
+  - conda install libopenblas
   - conda install nlopt petsc4py petsc $MUMPS mpi4py scipy $MPI
   # pip install these as the conda installs downgrade pytest on python3.4
   - pip install flake8

From 35f09ff5c872c754f31bda3e0e3802f32b4a01b7 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 3 Oct 2019 15:57:31 -0500
Subject: [PATCH 308/644] user guide reformatting

---
 docs/user_guide.rst | 96 ++++++++++++++++++++++-----------------------
 1 file changed, 48 insertions(+), 48 deletions(-)

diff --git a/docs/user_guide.rst b/docs/user_guide.rst
index 0be2d95d8..135e6b959 100644
--- a/docs/user_guide.rst
+++ b/docs/user_guide.rst
@@ -5,24 +5,24 @@ libEnsemble overview
 --------------------
 libEnsemble is a software library to coordinate the concurrent evaluation of
 ensembles of calculations. libEnsemble uses a manager to allocate work to
-various workers. (A libEnsemble worker is the smallest indivisible unit to
-perform some calculation.) The work performed by libEnsemble is governed by
+various workers. A libEnsemble worker is the smallest indivisible unit to
+perform some calculation. The work performed by libEnsemble is governed by
 three routines:
 
-* gen_f: Generates inputs to sim_f.
-* sim_f: Evaluates a simulation or other evaluation at output from gen_f.
-* alloc_f: Decides whether sim_f or gen_f should be called (and with what input/resources) as workers become available.
+* :ref:`gen_f<api_gen_f>`: Generates inputs to ``sim_f``.
+* :ref:`sim_f<api_sim_f>`: Evaluates a simulation or other evaluation at output from ``gen_f``.
+* :ref:`alloc_f<api_alloc_f>`: Decides whether ``sim_f`` or ``gen_f`` should be called (and with what input/resources) as workers become available.
 
-Example sim_f, gen_f, and alloc_f routines can be found in the
+Example ``sim_f``, ``gen_f``, and ``alloc_f`` routines can be found in the
 ``examples/sim_funcs/``, ``examples/gen_funcs/``, and ``examples/alloc_funcs/`` directories,
 respectively. Examples of scripts used for calling libEnsemble can be found in
 ``examples/calling_scripts/``. To enable portability, a :doc:`job_controller<job_controller/overview>`
-interface is supplied for users to launch and monitor jobs in their user-provided sim_f and
-gen_f routines.
+interface is supplied for users to launch and monitor jobs in their user-provided ``sim_f`` and
+``gen_f`` routines.
 
-The default alloc_f tells each available worker to call sim_f with the highest
-priority unit of work from gen_f. If a worker is idle and there is no gen_f
-output to give, the worker is told to call gen_f.
+The default ``alloc_f`` tells each available worker to call ``sim_f`` with the highest
+priority unit of work from ``gen_f``. If a worker is idle and there is no ``gen_f``
+output to give, the worker is told to call ``gen_f``.
 
 
 Expected use cases
@@ -34,36 +34,36 @@ to support) and plan to have examples of:
 * A user is looking to optimize a simulation calculation. The simulation may
   already be using parallel resources, but not a large fraction of some
   computer. libEnsemble can coordinate the concurrent evaluation of the
-  simulation sim_f at various parameter values and gen_f would return candidate
-  parameter values (possibly after each sim_f output).
+  simulation ``sim_f`` at various parameter values and ``gen_f`` would return candidate
+  parameter values (possibly after each ``sim_f`` output).
 
-* A user has a gen_f that produces different meshes to be used within a
-  sim_f. Given the sim_f output, gen_f will refine a mesh or produce a new
+* A user has a ``gen_f`` that produces different meshes to be used within a
+  ``sim_f``. Given the ``sim_f`` output, ``gen_f`` will refine a mesh or produce a new
   mesh. libEnsemble can ensure that the calculated meshes can be used by
   multiple simulations without requiring movement of data.
 
-* A user is attempting to sample a simulation sim_f at some parameter values,
+* A user is attempting to sample a simulation ``sim_f`` at some parameter values,
   many of which will cause the simulation to fail. libEnsemble can stop
   unresponsive evaluations, and recover computational resources for future
-  evaluations. gen_f can possibly update the sampling after discovering regions
-  where evaluations of sim_f fail.
+  evaluations. ``gen_f`` can possibly update the sampling after discovering regions
+  where evaluations of ``sim_f`` fail.
 
-* A user has a simulation sim_f that requires calculating multiple expensive
-  quantities, some of which depend on other quantities. sim_f can observe
+* A user has a simulation ``sim_f`` that requires calculating multiple expensive
+  quantities, some of which depend on other quantities. ``sim_f`` can observe
   intermediate quantities in order to stop related calculations and preempt
   future calculations associated with poor parameter values.
 
-* A user has a sim_f with multiple fidelities, with the
+* A user has a ``sim_f`` with multiple fidelities, with the
   higher-fidelity evaluations requiring more computational resources, and a
-  gen_f/alloc_f that decides which parameters should be evaluated and at what
+  ``gen_f``/``alloc_f`` that decides which parameters should be evaluated and at what
   fidelity level. libEnsemble can coordinate these evaluations without
   requiring the user know parallel programming.
 
-* A user wishes to identify multiple local optima for a sim_f. Furthermore,
+* A user wishes to identify multiple local optima for a ``sim_f``. Furthermore,
   sensitivity analysis is desired at each identified optimum. libEnsemble can
-  use the points from the APOSMM gen_f to identify optima; and after a point is
-  ruled to be an optimum, a different gen_f can produce a collection of
-  parameters necessary for sensitivity analysis of sim_f.
+  use the points from the APOSMM ``gen_f`` to identify optima; and after a point is
+  ruled to be an optimum, a different ``gen_f`` can produce a collection of
+  parameters necessary for sensitivity analysis of ``sim_f``.
 
 
 Naturally, combinations of these use cases are supported as well. An example of
@@ -74,51 +74,51 @@ relies on simulations that fail frequently.
 The libEnsemble History Array
 -----------------------------
 
-libEnsemble uses a numpy structured array H to store output from gen_f and
-corresponding sim_f output. Similarly, gen_f and sim_f are expected to return
-output in numpy structured arrays. The names of the fields to be given as input
-to gen_f and sim_f must be an output from gen_f or sim_f. In addition to the
-fields output from sim_f and gen_f, the final history returned from libEnsemble
+libEnsemble uses a NumPy structured array :ref:`H<datastruct-history-array>` to store output from ``gen_f`` and
+corresponding ``sim_f`` output. Similarly, ``gen_f`` and ``sim_f`` are expected to return
+output in NumPy structured arrays. The names of the fields to be given as input
+to ``gen_f`` and ``sim_f`` must be an output from ``gen_f`` or ``sim_f``. In addition to the
+fields output from ``sim_f`` and ``gen_f``, the final history returned from libEnsemble
 will include the following fields:
 
-* sim_id' [int]: Each unit of work output from gen_f must have an associated
-  sim_id. The generator can assign this, but users must be careful to ensure
-  points are added in order. For example, if alloc_f allows for two gen_f
-  instances to be running simultaneously, alloc_f should ensure that both don’t
-  generate points with the same sim_id.
+* ``sim_id`` [int]: Each unit of work output from ``gen_f`` must have an associated
+  ``sim_id``. The generator can assign this, but users must be careful to ensure
+  points are added in order. For example, ``if alloc_f`` allows for two ``gen_f``
+  instances to be running simultaneously, ``alloc_f`` should ensure that both don’t
+  generate points with the same ``sim_id``.
 
-* given' [bool]: Has this gen_f output been given to a libEnsemble worker to be
+* ``given`` [bool]: Has this ``gen_f`` output been given to a libEnsemble worker to be
   evaluated yet?
 
-* given_time' [float]: At what time (since the epoch) was this gen_f output
+* ``given_time`` [float]: At what time (since the epoch) was this ``gen_f`` output
   given to a worker?
 
-* sim_worker' [int]: libEnsemble worker that it was given to be evaluated.
+* ``sim_worker`` [int]: libEnsemble worker that it was given to be evaluated.
 
-* gen_worker' [int]: libEnsemble worker that generated this sim_id
+* ``gen_worker`` [int]: libEnsemble worker that generated this ``sim_id``
 
-* gen_time' [float]: At what time (since the epoch) was this entry (or
-  collection of entries) put into H by the manager
+* ``gen_time`` [float]: At what time (since the epoch) was this entry (or
+  collection of entries) put into ``H`` by the manager
 
-* returned' [bool]: Has this worker completed the evaluation of this unit of
+* ``returned`` [bool]: Has this worker completed the evaluation of this unit of
   work?
 
 
 libEnsemble Output
 ------------------
 
-The history array and persis_info dictionary are returned to the user by libEnsemble.
-In the case that libEnsemble aborts on an exception, these are dumped to files. The
+The history array and :ref:`persis_info<datastruct-persis-info>` dictionary are returned to the user by libEnsemble.
+If libEnsemble aborts on an exception, these structures are dumped to files. The
 existing history array is dumped to a file named ``libE_history_at_abort_<sim_count>.npy``,
-and the persis_info to ``libE_history_at_abort_<sim_count>.pickle``, where sim_count is
+and ``persis_info`` to ``libE_history_at_abort_<sim_count>.pickle``, where ``sim_count`` is
 the number of points evaluated.
 
 Other libEnsemble files produced by default are:
 
-**libE_stats.txt**: This contains a one-line summary of all user calculations. Each
+``libE_stats.txt``: This contains a one-line summary of all user calculations. Each
 calculation summary is sent by workers to the manager and printed as the run progresses.
 
-**ensemble.log**: This is the logging output from libEnsemble. The default logging
+``ensemble.log``: This is the logging output from libEnsemble. The default logging
 is at INFO level. To gain additional diagnostics logging level can be set to DEBUG.
 If this file is not removed, multiple runs will append output. Messages at or above
 level MANAGER_WARNING are also copied to stderr to alert the user promptly.

From 19a0f9b2cab6decc9d6247bfef9f48262cc45534 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 3 Oct 2019 15:59:41 -0500
Subject: [PATCH 309/644] all-around reformatting and clarification

---
 docs/FAQ.rst        | 61 ++++++++++++++++++++++-----------------------
 docs/logging.rst    |  4 +--
 docs/quickstart.rst | 55 +++++++++++++++++++++-------------------
 3 files changed, 61 insertions(+), 59 deletions(-)

diff --git a/docs/FAQ.rst b/docs/FAQ.rst
index deae12a49..d0c44346f 100644
--- a/docs/FAQ.rst
+++ b/docs/FAQ.rst
@@ -13,6 +13,7 @@ Parallel Debugging
 **How can I perform parallel debugging on libEnsemble, or debug specific processes?**
 
 
+This is most easily addressed when running with MPI.
 Try the following: ``mpiexec -np [num processes] xterm -e 'python [calling script].py'``
 
 This will launch an xterm terminal window specific to each process. Mac users will
@@ -28,18 +29,18 @@ work may depend on the system. Usage::
     ForkablePdb().set_trace()
 
 
-AssertionError - Idle workers
+AssertionError - idle workers
 -----------------------------
 
 **AssertionError: Should not wait for workers when all workers are idle.**
 
 with ``mpiexec -np 1 python [calling script].py``
 
-This error occurs when the manager is waiting, although no workers are busy.
+This error occurs when the manager is waiting although no workers are busy.
 In the above case, this occurs because an MPI libEnsemble run was initiated with
 only one process, resulting in one manager but no workers.
 
-Note: this may also occur with two processes if you are using a persistent generator.
+This may also occur with two processes if you are using a persistent generator.
 The generator will occupy the one worker, leaving none to run simulation functions.
 
 
@@ -48,16 +49,15 @@ Not enough processors per worker to honour arguments
 
 **libensemble.resources.ResourcesException: Not enough processors per worker to honour arguments.**
 
-This is likely when using the job_controller, when there are not enough
-cores/nodes available to launch jobs. This can be disabled if you want
-to oversubscribe (often if testing on a local machine). Set up the
-job_controller with ``auto_resources=False``. E.g.::
+This error often occurs when there aren't enough cores/nodes available to launch
+jobs with the job controller. Automatic partitioning of resources can be disabled
+if you want to oversubscribe (often if testing on a local machine) by configuring
+the job controller with ``auto_resources=False``. E.g.::
 
     jobctrl = MPIJobController(auto_resources=False)
 
-Also, note that the job_controller launch command has the argument
-hyperthreads, which is set to True, will attempt to use all
-hyperthreads/SMT threads available.
+Note that the job_controller ``.launch()`` method has a parameter``hyperthreads``
+which will attempt to use all hyperthreads/SMT threads available if set to ``True``
 
 
 FileExistsError
@@ -65,21 +65,22 @@ FileExistsError
 
 **FileExistsError: [Errno 17] File exists: './sim_worker1'**
 
-This can happen when libEnsemble tries to create sim directories that already exist. If
-the directory does not already exist, a possible cause is that you are trying
-to run using ``mpiexec``, when the ``libE_specs['comms']`` option is set to ``local``.
-Note that to run with differently named sub-directories you can use the
-``sim_dir_suffix`` option to :ref:`sim_specs<datastruct-sim-specs>`.
+This can happen when libEnsemble tries to create sim directories that already exist.
+If these directories do not already exist, another possibility is that you are trying
+to run libEnsemble using ``mpiexec`` when the ``libE_specs['comms']`` option is
+set to ``local``.
+
+To create differently named sim directories, you can use the ``sim_dir_suffix``
+option in :ref:`sim_specs<datastruct-sim-specs>`.
 
 
 libEnsemble hangs when using mpi4py
 -----------------------------------
 
-One cause of this could be that the communications fabric does not support matching
-probes (part of the MPI 3.0 standard), which mpi4py uses by default. This has been
-observed with Intels Truescale (TMI) fabric at time of writing. This can be solved
-either by switch fabric or turning off matching probes before the MPI module is first
-imported.
+This may occur if matching probes, which mpi4py uses by default, are not supported
+by the communications fabric. This has been observed with Intels Truescale (TMI)
+fabric at time of writing. This can be solved either by switching fabrics or disabling
+matching probes before the MPI module is first imported.
 
 Add these two lines BEFORE ``from mpi4py import MPI``::
 
@@ -89,10 +90,10 @@ Add these two lines BEFORE ``from mpi4py import MPI``::
 Also see https://software.intel.com/en-us/articles/python-mpi4py-on-intel-true-scale-and-omni-path-clusters
 
 
-Messages are not received correctly when using mpi4py
-------------------------------------------------------
+Messages not received correctly when using mpi4py
+-------------------------------------------------
 
-This may manifest itself with the following error:
+This may manifest with the following error:
 
 **_pickle.UnpicklingError: invalid load key, '\x00'.**
 
@@ -146,14 +147,12 @@ macOS - Firewall prompts
 
 
 There are several ways to address this nuisance, but all involve trial and error.
-One easy (but insecure) solution is temporarily disabling the Firewall through System Preferences
--> Security & Privacy -> Firewall -> Turn Off Firewall. Alternatively, adding a Firewall "Allow incoming
-connections" rule can be tried for the offending Job Controller executable.
-Based on a suggestion from here_, we've had the most success running
-``sudo codesign --force --deep --sign - /path/to/application.app`` on our Job Controller executables,
-then confirming the next alerts for the executable and ``mpiexec.hydra``.
-
-.. _`here`: https://coderwall.com/p/5b_apq/stop-mac-os-x-firewall-from-prompting-with-python-in-virtualenv
+An easy (but insecure) solution is temporarily disabling the Firewall through
+System Preferences -> Security & Privacy -> Firewall -> Turn Off Firewall. Alternatively,
+adding a Firewall "Allow incoming connections" rule can be attempted for the offending
+Job Controller executable. We've had limited success running ``sudo codesign --force --deep --sign - /path/to/application.app``
+on our Job Controller executables, then confirming the next alerts for the executable
+and ``mpiexec.hydra``.
 
 
 Running out of contexts when running libEnsemble in distributed mode on TMI fabric
diff --git a/docs/logging.rst b/docs/logging.rst
index d8ed600dc..a5bdd53b6 100644
--- a/docs/logging.rst
+++ b/docs/logging.rst
@@ -9,7 +9,7 @@ and when jobs are killed. To gain additional diagnostics, the logging level can
 to DEBUG. libEnsemble produces logging to the file ensemble.log by default. A log
 file name can also be supplied.
 
-E.g. To change the logging level to DEBUG, provide the following in your the calling scripts::
+To change the logging level to DEBUG, provide the following in your the calling scripts::
 
     from libensemble import libE_logger
     libE_logger.set_level('DEBUG')
@@ -22,7 +22,7 @@ This boundary can be adjusted as follows::
     # Only display messages with level >= ERROR
     libE_logger.set_stderr_level('ERROR')
 
-This feature can be effectively disabled by setting the stderr level to CRITICAL.
+stderr displaying can be effectively disabled by setting the stderr level to CRITICAL.
 
 
 Logging API
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index 7292a27fe..d74f4061c 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -22,9 +22,9 @@
 What is libEnsemble?
 ====================
 
-libEnsemble is a Python library to coordinate the concurrent evaluation of ensembles of computations.
-Designed with flexibility in mind, libEnsemble can utilize massively parallel resources to accelerate
-the solution of design, decision, and inference problems.
+libEnsemble is a Python library to coordinate the concurrent evaluation of ensembles
+of computations. Designed with flexibility in mind, libEnsemble can utilize massively
+parallel resources to accelerate the solution of design, decision, and inference problems.
 
 A visual overview is given in the libEnsemble poster_.
 
@@ -38,18 +38,18 @@ libEnsemble aims for:
 • Portability and flexibility
 • Exploitation of persistent data/control flow.
 
-The user selects or supplies a generation function that produces simulation input as well as
-a simulation function that performs and monitors the simulations. The generation function
-may contain, for example, an optimization method to generate new simulation parameters
-on-the-fly and based on the results of previous simulations. Examples and templates of these
-functions are included in the library.
+The user selects or supplies a generation function that produces simulation input
+as well as a simulation function that performs and monitors the simulations. The
+generation function may contain, for example, an optimization method to generate
+new simulation parameters on-the-fly and based on the results of previous simulations.
+Examples and templates of these functions are included in the library.
 
-libEnsemble employs a manager-worker scheme that can run on various communication media
-(including MPI, multiprocessing, and TCP). Each worker can control and monitor any type
-of job from small sub-node jobs to huge many-node simulations. A job controller
-interface is provided to ensure scripts are portable, resilient and flexible; it also
-enables automatic detection of the nodes and cores in a system and can split up
-jobs automatically if nodes/cores are not supplied.
+libEnsemble employs a manager-worker scheme that can run on various communication
+media (including MPI, multiprocessing, and TCP). Each worker can control and monitor
+any level of work from small sub-node jobs to huge many-node simulations. A job
+controller interface is provided to ensure scripts are portable, resilient and
+flexible; it also enables automatic detection of the nodes and cores in a system
+and can split up jobs automatically if resource data isn't supplied.
 
 
 Dependencies
@@ -75,8 +75,9 @@ Optional dependency:
 
 From v0.2.0, libEnsemble has the option of using the Balsam job manager. This
 is required for running libEnsemble on the compute nodes of some supercomputing
-platforms (e.g., Cray XC40); platforms that do not support launching jobs from compute nodes.
-Note that as of v0.5.0, libEnsemble can also be run on the launch nodes using multiprocessing.
+platforms (e.g., Cray XC40); platforms that do not support launching jobs from
+compute nodes. Note that as of v0.5.0, libEnsemble can also be run on the launch
+nodes using multiprocessing.
 
 The example sim and gen functions and tests require the following dependencies:
 
@@ -104,7 +105,8 @@ libEnsemble is also available in the Spack_ distribution. It can be installed fr
 
 .. _Spack: https://spack.readthedocs.io/en/latest
 
-The tests and examples can be accessed in the `GitHub <https://github.com/Libensemble/libensemble>`_ repository. If necessary, you may install all optional dependencies (listed above) at once with::
+The tests and examples can be accessed in the `GitHub <https://github.com/Libensemble/libensemble>`_ repository.
+If necessary, you may install all optional dependencies (listed above) at once with::
 
     pip install libensemble[extras]
 
@@ -143,14 +145,15 @@ in the top-level directory containing the setup script.
 Coverage reports are produced separately for unit tests and regression tests
 under the relevant directories. For parallel tests, the union of all processors
 is taken. Furthermore, a combined coverage report is created at the top level,
-which can be viewed after running the tests via the html file
-libensemble/tests/cov_merge/index.html. The Travis CI coverage results are
-given online at
+which can be viewed after running the tests via the HTML file
+``libensemble/tests/cov_merge/index.html``. The Travis CI coverage results are
+available online at
 `Coveralls <https://coveralls.io/github/Libensemble/libensemble?branch=master>`_.
 
 Note: The job_controller tests can be run using the direct-launch or
-Balsam job controllers. However, currently only the direct-launch versions can
-be run on Travis CI, which reduces the test coverage results.
+Balsam job controllers. Although only the direct-launch versions can
+be run on Travis CI, Balsam integration with libEnsemble is now tested via
+``test_balsam_hworld.py``.
 
 
 Basic Usage
@@ -159,7 +162,7 @@ Basic Usage
 The examples directory contains example libEnsemble calling scripts, sim
 functions, gen functions, alloc functions and job submission scripts.
 
-The user will create a python script to call the libEnsemble :doc:`libE <libE_module>` function.
+The user creates a python script to call the libEnsemble :doc:`libE <libE_module>` function.
 This must supply the :ref:`sim_specs<datastruct-sim-specs>` and :ref:`gen_specs<datastruct-gen-specs>`,
 and optionally :ref:`libE_specs<datastruct-libe-specs>`, :ref:`alloc_specs<datastruct-alloc-specs>` and :ref:`persis_info<datastruct-persis-info>`.
 
@@ -192,9 +195,9 @@ See the `user-guide <https://libensemble.readthedocs.io/en/latest/user_guide.htm
 .. _Balsam: https://www.alcf.anl.gov/balsam
 .. _SWIG: http://swig.org/
 .. _mock: https://pypi.org/project/mock
-.. _pytest: https://pypi.org/project/pytest/ 
-.. _pytest-cov: https://pypi.org/project/pytest-cov/ 
-.. _pytest-timeout: https://pypi.org/project/pytest-timeout/ 
+.. _pytest: https://pypi.org/project/pytest/
+.. _pytest-cov: https://pypi.org/project/pytest-cov/
+.. _pytest-timeout: https://pypi.org/project/pytest-timeout/
 
 .. include:: ../README.rst
     :start-after: docs-include-tag

From 53761d73b1b1ac1b332907955a3f22cb4e28f660 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 3 Oct 2019 18:02:39 -0500
Subject: [PATCH 310/644] Adds env_resources capability to parse different
 partitions in same allocation

---
 libensemble/env_resources.py                  | 36 +++++++++++++------
 .../tests/unit_tests/test_env_resources.py    |  8 +++++
 2 files changed, 34 insertions(+), 10 deletions(-)

diff --git a/libensemble/env_resources.py b/libensemble/env_resources.py
index 2225bf795..9c406ebc8 100644
--- a/libensemble/env_resources.py
+++ b/libensemble/env_resources.py
@@ -105,23 +105,39 @@ def _range_split(s):
         b = b + 1
         return a, b, nnum_len
 
+    @staticmethod
+    def _noderange_split(prefix, nidstr, nidlst):
+        for nidgroup in nidstr.split(','):
+            a, b, nnum_len = EnvResources._range_split(nidgroup)
+            for nid in range(a, b):
+                nidlst.append(prefix + str(nid).zfill(nnum_len))
+        return nidlst
+
     @staticmethod
     def get_slurm_nodelist(node_list_env):
         """Get global libEnsemble nodelist from the Slurm environment"""
-        nidlst = []
         fullstr = os.environ[node_list_env]
         if not fullstr:
             return []
-        splitstr = fullstr.split('[', 1)
+        splitstr = fullstr.split('],')
         if len(splitstr) == 1:
-            return splitstr
-        prefix = splitstr[0]
-        nidstr = splitstr[1].strip("]")
-        for nidgroup in nidstr.split(','):
-            a, b, nnum_len = EnvResources._range_split(nidgroup)
-            for nid in range(a, b):
-                nidlst.append(prefix + str(nid).zfill(nnum_len))
-        return sorted(nidlst)
+            splitstr = fullstr.split('[', 1)
+            if len(splitstr) == 1:
+                return splitstr
+            prefix = splitstr[0]
+            nidstr = splitstr[1].strip("]")
+            nidlst = EnvResources._noderange_split(prefix, nidstr, [])
+            return sorted(nidlst)
+        else:
+            splitgroups = [str.split('[', 1) for str in splitstr]
+            prefixgroups = [group[0] for group in splitgroups]
+            nodegroups = [group[1].strip(']') for group in splitgroups]
+            nidlst = []
+            for i in range(len(prefixgroups)):
+                prefix = prefixgroups[i]
+                nidstr = nodegroups[i]
+                nidlst.extend(EnvResources._noderange_split(prefix, nidstr, nidlst))
+            return sorted(set(nidlst))
 
     @staticmethod
     def get_cobalt_nodelist(node_list_env):
diff --git a/libensemble/tests/unit_tests/test_env_resources.py b/libensemble/tests/unit_tests/test_env_resources.py
index b63bbd0fa..3ed5be38e 100644
--- a/libensemble/tests/unit_tests/test_env_resources.py
+++ b/libensemble/tests/unit_tests/test_env_resources.py
@@ -66,6 +66,13 @@ def test_slurm_nodelist_groups():
     assert nodelist == exp_out, "Nodelist returned does not match expected"
 
 
+def test_slurm_nodelist_groups_partitions():
+    os.environ["LIBE_RESOURCES_TEST_NODE_LIST"] = "bdw-[0254,0384,0565-0568],bdwd-[0004,0009]"
+    exp_out = ['bdw-0254', 'bdw-0384', 'bdw-0565', 'bdw-0566', 'bdw-0567', 'bdw-0568', 'bdwd-0004', 'bdwd-0009']
+    nodelist = EnvResources.get_slurm_nodelist(node_list_env="LIBE_RESOURCES_TEST_NODE_LIST")
+    assert nodelist == exp_out, "Nodelist returned does not match expected"
+
+
 def test_slurm_nodelist_groups_nodash():
     os.environ["LIBE_RESOURCES_TEST_NODE_LIST"] = "nid0[0020-0022,0137-0139,1234]"
     exp_out = ['nid00020', 'nid00021', 'nid00022', 'nid00137', 'nid00138', 'nid00139', 'nid01234']
@@ -209,6 +216,7 @@ def test_abbrev_nodenames_cobalt():
     test_slurm_nodelist_knl_seq()
     test_slurm_nodelist_bdw_seq()
     test_slurm_nodelist_groups()
+    test_slurm_nodelist_groups_partitions()
     test_slurm_nodelist_groups_nodash()
     test_slurm_nodelist_groups_longprefix()
     test_slurm_nodelist_reverse_grp()

From 593597bcc0d9886d1f1084e4e4ca13dff8e6e2d7 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 3 Oct 2019 18:03:29 -0500
Subject: [PATCH 311/644] misc flake8 (that wasn't caught previously?)

---
 conda/install-balsam.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index 8d38e816e..0c358c575 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -26,6 +26,7 @@ def move_test_balsam(balsam_test):
     if not os.path.isfile(reg_dir_with_btest):
         os.rename('./conda/{}'.format(balsam_test), reg_dir_with_btest)
 
+
 def configure_coverage():
     # Enables coverage of balsam_controller.py if running test
     coveragerc = './libensemble/tests/.coveragerc'
@@ -38,6 +39,7 @@ def configure_coverage():
         for line in newlines:
             f.write(line)
 
+
 if int(sys.version[2]) >= 6:  # Balsam only supports Python 3.6+
     install_balsam()
     move_test_balsam('test_balsam_hworld.py')

From 5d9ceb493f8a1976244994ff0d6d0e7c9f2a3b38 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 4 Oct 2019 08:07:37 -0500
Subject: [PATCH 312/644] Removing .svg errors

---
 docs/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index 25373417b..58fe4632a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -58,7 +58,7 @@ def __getattr__(cls, name):
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.imgconverter']
 #extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'numpydoc']
 #extensions = ['sphinx.ext.autodoc', 'breathe']
 #breathe_projects = { "libEnsemble": "../code/src/xml/" }

From b65d1b05acd011c695b0b92b032e3854f4b15e39 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 4 Oct 2019 08:13:20 -0500
Subject: [PATCH 313/644] Wrapping/harmonizing README and quickstart

---
 README.rst          | 69 +++++++++++++++++++++++++++++----------------
 docs/quickstart.rst | 58 +++++++++++++++++++------------------
 2 files changed, 76 insertions(+), 51 deletions(-)

diff --git a/README.rst b/README.rst
index 94fcca7d1..7105a700a 100644
--- a/README.rst
+++ b/README.rst
@@ -1,5 +1,5 @@
 .. image:: docs/images/libE_logo.png
-  :alt: libEnsemble
+   :alt: libEnsemble
 
 |
 
@@ -22,15 +22,16 @@
 What is libEnsemble?
 ====================
 
-libEnsemble is a Python library to coordinate the concurrent evaluation of ensembles of computations.
-Designed with flexibility in mind, libEnsemble can utilize massively parallel resources to accelerate
-the solution of design, decision, and inference problems.
+libEnsemble is a Python library to coordinate the concurrent evaluation of
+ensembles of computations. Designed with flexibility in mind, libEnsemble can
+utilize massively parallel resources to accelerate the solution of design,
+decision, and inference problems.
 
 libEnsemble aims for:
 
 • Extreme scaling
-• Fault tolerance
-• Monitoring/killing jobs (recovers resources)
+• Resilience/fault tolerance
+• Monitoring/killing jobs (and recovering resources)
 • Portability and flexibility
 • Exploitation of persistent data/control flow.
 
@@ -66,8 +67,9 @@ Optional dependency:
 
 From v0.2.0, libEnsemble has the option of using the Balsam job manager. This
 is required for running libEnsemble on the compute nodes of some supercomputing
-platforms (eg. Cray XC40); platforms that do not support launching jobs from compute nodes.
-Note that as of v0.5.0, libEnsemble can also be run on the launch nodes using multiprocessing.
+platforms (e.g., Cray XC40); platforms that do not support launching jobs from
+compute nodes. Note that as of v0.5.0, libEnsemble can also be run on the
+launch nodes using multiprocessing.
 
 The example sim and gen functions and tests require the following dependencies:
 
@@ -77,17 +79,9 @@ The example sim and gen functions and tests require the following dependencies:
 * NLopt_ - Installed with `shared libraries enabled <http://ab-initio.mit.edu/wiki/index.php/NLopt_Installation#Shared_libraries>`_.
 
 PETSc and NLopt must be built with shared libraries enabled and present in
-sys.path (eg. via setting the PYTHONPATH environment variable). NLopt should
-produce a file nlopt.py if Python is found on the system.
+``sys.path`` (e.g., via setting the ``PYTHONPATH`` environment variable). NLopt
+should produce a file nlopt.py if Python is found on the system.
 
-.. _PETSc:  http://www.mcs.anl.gov/petsc
-.. _Python: http://www.python.org
-.. _nlopt: http://ab-initio.mit.edu/wiki/index.php/NLopt
-.. _NumPy:  http://www.numpy.org
-.. _SciPy:  http://www.scipy.org
-.. _mpi4py:  https://bitbucket.org/mpi4py/mpi4py
-.. _petsc4py:  https://bitbucket.org/petsc/petsc4py
-.. _Balsam: https://www.alcf.anl.gov/balsam
 
 
 Installation
@@ -104,6 +98,10 @@ libEnsemble is also available in the Spack_ distribution. It can be installed fr
 .. _Spack: https://spack.readthedocs.io/en/latest
 
 The tests and examples can be accessed in the `GitHub <https://github.com/Libensemble/libensemble>`_ repository.
+If necessary, you may install all optional dependencies (listed above) at once with::
+
+    pip install libensemble[extras]
+
 A `tarball <https://github.com/Libensemble/libensemble/releases/latest>`_ of the most recent release is also available.
 
 
@@ -115,7 +113,7 @@ regularly on:
 
 * `Travis CI <https://travis-ci.org/Libensemble/libensemble>`_
 
-The test suite requires the mock, pytest, pytest-cov and pytest-timeout
+The test suite requires the mock_, pytest_, pytest-cov_, and pytest-timeout_
 packages to be installed and can be run from the libensemble/tests directory of
 the source distribution by running::
 
@@ -129,17 +127,25 @@ Further options are available. To see a complete list of options run::
 
     ./run-tests.sh -h
 
+If you have the source distribution, you can download (but not install) the testing
+prerequisites and run the tests with::
+
+    python setup.py test
+
+in the top-level directory containing the setup script.
+
 Coverage reports are produced separately for unit tests and regression tests
 under the relevant directories. For parallel tests, the union of all processors
 is taken. Furthermore, a combined coverage report is created at the top level,
-which can be viewed after running the tests via the html file
-libensemble/tests/cov_merge/index.html. The Travis CI coverage results are
-given online at
+which can be viewed after running the tests via the HTML file
+``libensemble/tests/cov_merge/index.html``. The Travis CI coverage results are
+available online at
 `Coveralls <https://coveralls.io/github/Libensemble/libensemble?branch=master>`_.
 
 Note: The job_controller tests can be run using the direct-launch or
-Balsam job controllers. However, currently only the direct-launch versions can
-be run on Travis CI, which reduces the test coverage results.
+Balsam job controllers. Although only the direct-launch versions can
+be run on Travis CI, Balsam integration with libEnsemble is now tested via
+``test_balsam_hworld.py``.
 
 
 Basic Usage
@@ -186,3 +192,18 @@ or email questions to:
 or communicate (and establish a private channel, if desired) at:
 
 * https://libensemble.slack.com
+
+.. _PETSc:  http://www.mcs.anl.gov/petsc
+.. _Python: http://www.python.org
+.. _nlopt: http://ab-initio.mit.edu/wiki/index.php/NLopt
+.. _NumPy:  http://www.numpy.org
+.. _SciPy:  http://www.scipy.org
+.. _mpi4py:  https://bitbucket.org/mpi4py/mpi4py
+.. _petsc4py:  https://bitbucket.org/petsc/petsc4py
+.. _Balsam: https://www.alcf.anl.gov/balsam
+.. _SWIG: http://swig.org/
+.. _mock: https://pypi.org/project/mock
+.. _pytest: https://pypi.org/project/pytest/
+.. _pytest-cov: https://pypi.org/project/pytest-cov/
+.. _pytest-timeout: https://pypi.org/project/pytest-timeout/
+
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index d74f4061c..f46cb3995 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -1,5 +1,5 @@
 .. image:: images/libE_logo.png
-  :alt: libEnsemble
+   :alt: libEnsemble
 
 |
 
@@ -22,34 +22,37 @@
 What is libEnsemble?
 ====================
 
-libEnsemble is a Python library to coordinate the concurrent evaluation of ensembles
-of computations. Designed with flexibility in mind, libEnsemble can utilize massively
-parallel resources to accelerate the solution of design, decision, and inference problems.
-
-A visual overview is given in the libEnsemble poster_.
-
-.. _poster:  https://figshare.com/articles/LibEnsemble_PETSc_TAO-_Sustaining_a_library_for_dynamic_ensemble-based_computations/7765454
+libEnsemble is a Python library to coordinate the concurrent evaluation of
+ensembles of computations. Designed with flexibility in mind, libEnsemble can
+utilize massively parallel resources to accelerate the solution of design,
+decision, and inference problems.
 
 libEnsemble aims for:
 
 • Extreme scaling
-• Resilience/Fault tolerance
+• Resilience/fault tolerance
 • Monitoring/killing jobs (and recovering resources)
 • Portability and flexibility
 • Exploitation of persistent data/control flow.
 
-The user selects or supplies a generation function that produces simulation input
-as well as a simulation function that performs and monitors the simulations. The
-generation function may contain, for example, an optimization method to generate
-new simulation parameters on-the-fly and based on the results of previous simulations.
-Examples and templates of these functions are included in the library.
+The user selects or supplies a generation function that produces simulation
+input as well as a simulation function that performs and monitors the
+simulations. The generation function may contain, for example, an optimization
+method to generate new simulation parameters on-the-fly and based on the
+results of previous simulations.  Examples and templates of these functions are
+included in the library.
+
+libEnsemble employs a manager-worker scheme that can run on various
+communication media (including MPI, multiprocessing, and TCP). Each worker can
+control and monitor any level of work from small sub-node jobs to huge
+many-node simulations. A job controller interface is provided to ensure scripts
+are portable, resilient and flexible; it also enables automatic detection of
+the nodes and cores in a system and can split up jobs automatically if resource
+data isn't supplied.
+
+A visual overview is given in the libEnsemble poster_.
 
-libEnsemble employs a manager-worker scheme that can run on various communication
-media (including MPI, multiprocessing, and TCP). Each worker can control and monitor
-any level of work from small sub-node jobs to huge many-node simulations. A job
-controller interface is provided to ensure scripts are portable, resilient and
-flexible; it also enables automatic detection of the nodes and cores in a system
-and can split up jobs automatically if resource data isn't supplied.
+.. _poster:  https://figshare.com/articles/LibEnsemble_PETSc_TAO-_Sustaining_a_library_for_dynamic_ensemble-based_computations/7765454
 
 
 Dependencies
@@ -76,8 +79,8 @@ Optional dependency:
 From v0.2.0, libEnsemble has the option of using the Balsam job manager. This
 is required for running libEnsemble on the compute nodes of some supercomputing
 platforms (e.g., Cray XC40); platforms that do not support launching jobs from
-compute nodes. Note that as of v0.5.0, libEnsemble can also be run on the launch
-nodes using multiprocessing.
+compute nodes. Note that as of v0.5.0, libEnsemble can also be run on the
+launch nodes using multiprocessing.
 
 The example sim and gen functions and tests require the following dependencies:
 
@@ -87,9 +90,9 @@ The example sim and gen functions and tests require the following dependencies:
 * NLopt_ - Installed with `shared libraries enabled <http://ab-initio.mit.edu/wiki/index.php/NLopt_Installation#Shared_libraries>`_.
 
 PETSc and NLopt must be built with shared libraries enabled and present in
-sys.path (e.g., via setting the ``PYTHONPATH`` environment variable). NLopt should
-produce a file nlopt.py if Python is found on the system. NLopt may also require SWIG_
-to be installed on certain systems.
+``sys.path`` (e.g., via setting the ``PYTHONPATH`` environment variable). NLopt
+should produce a file nlopt.py if Python is found on the system. NLopt may also
+require SWIG_ to be installed on certain systems.
 
 
 Installation
@@ -185,6 +188,9 @@ function used in the regression tests, which can be found in
 
 See the `user-guide <https://libensemble.readthedocs.io/en/latest/user_guide.html>`_ for more information.
 
+.. include:: ../README.rst
+    :start-after: docs-include-tag
+
 .. _PETSc:  http://www.mcs.anl.gov/petsc
 .. _Python: http://www.python.org
 .. _nlopt: http://ab-initio.mit.edu/wiki/index.php/NLopt
@@ -199,5 +205,3 @@ See the `user-guide <https://libensemble.readthedocs.io/en/latest/user_guide.htm
 .. _pytest-cov: https://pypi.org/project/pytest-cov/
 .. _pytest-timeout: https://pypi.org/project/pytest-timeout/
 
-.. include:: ../README.rst
-    :start-after: docs-include-tag

From 773fd6210f2a244dbd49b04c393947d1e17f9d3d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 4 Oct 2019 08:36:41 -0500
Subject: [PATCH 314/644] Wrapping/editing user_guide.

---
 docs/user_guide.rst | 121 +++++++++++++++++++++++---------------------
 1 file changed, 63 insertions(+), 58 deletions(-)

diff --git a/docs/user_guide.rst b/docs/user_guide.rst
index 135e6b959..cbdbe20fb 100644
--- a/docs/user_guide.rst
+++ b/docs/user_guide.rst
@@ -13,16 +13,15 @@ three routines:
 * :ref:`sim_f<api_sim_f>`: Evaluates a simulation or other evaluation at output from ``gen_f``.
 * :ref:`alloc_f<api_alloc_f>`: Decides whether ``sim_f`` or ``gen_f`` should be called (and with what input/resources) as workers become available.
 
-Example ``sim_f``, ``gen_f``, and ``alloc_f`` routines can be found in the
-``examples/sim_funcs/``, ``examples/gen_funcs/``, and ``examples/alloc_funcs/`` directories,
-respectively. Examples of scripts used for calling libEnsemble can be found in
-``examples/calling_scripts/``. To enable portability, a :doc:`job_controller<job_controller/overview>`
-interface is supplied for users to launch and monitor jobs in their user-provided ``sim_f`` and
-``gen_f`` routines.
+Example ``sim_f``, ``gen_f``, ``alloc_f``, and calling scripts 
+be found in the ``examples/`` directory. To enable portability, a
+:doc:`job_controller<job_controller/overview>`
+interface is supplied for users to launch and monitor jobs in their
+user-provided ``sim_f`` and ``gen_f`` routines.
 
-The default ``alloc_f`` tells each available worker to call ``sim_f`` with the highest
-priority unit of work from ``gen_f``. If a worker is idle and there is no ``gen_f``
-output to give, the worker is told to call ``gen_f``.
+The default ``alloc_f`` tells each available worker to call ``sim_f`` with the
+highest priority unit of work from ``gen_f``. If a worker is idle and there is
+no ``gen_f`` output to give, the worker is told to call ``gen_f``.
 
 
 Expected use cases
@@ -34,36 +33,36 @@ to support) and plan to have examples of:
 * A user is looking to optimize a simulation calculation. The simulation may
   already be using parallel resources, but not a large fraction of some
   computer. libEnsemble can coordinate the concurrent evaluation of the
-  simulation ``sim_f`` at various parameter values and ``gen_f`` would return candidate
-  parameter values (possibly after each ``sim_f`` output).
+  simulation ``sim_f`` at various parameter values and ``gen_f`` would return
+  candidate parameter values (possibly after each ``sim_f`` output).
 
 * A user has a ``gen_f`` that produces different meshes to be used within a
-  ``sim_f``. Given the ``sim_f`` output, ``gen_f`` will refine a mesh or produce a new
-  mesh. libEnsemble can ensure that the calculated meshes can be used by
-  multiple simulations without requiring movement of data.
+  ``sim_f``. Given the ``sim_f`` output, ``gen_f`` will refine a mesh or
+  produce a new mesh. libEnsemble can ensure that the calculated meshes can be
+  used by multiple simulations without requiring movement of data.
 
-* A user is attempting to sample a simulation ``sim_f`` at some parameter values,
-  many of which will cause the simulation to fail. libEnsemble can stop
+* A user is attempting to sample a simulation ``sim_f`` at some parameter
+  values, many of which will cause the simulation to fail. libEnsemble can stop
   unresponsive evaluations, and recover computational resources for future
-  evaluations. ``gen_f`` can possibly update the sampling after discovering regions
-  where evaluations of ``sim_f`` fail.
-
-* A user has a simulation ``sim_f`` that requires calculating multiple expensive
-  quantities, some of which depend on other quantities. ``sim_f`` can observe
-  intermediate quantities in order to stop related calculations and preempt
-  future calculations associated with poor parameter values.
-
-* A user has a ``sim_f`` with multiple fidelities, with the
-  higher-fidelity evaluations requiring more computational resources, and a
-  ``gen_f``/``alloc_f`` that decides which parameters should be evaluated and at what
-  fidelity level. libEnsemble can coordinate these evaluations without
+  evaluations. ``gen_f`` can possibly update the sampling after discovering
+  regions where evaluations of ``sim_f`` fail.
+
+* A user has a simulation ``sim_f`` that requires calculating multiple
+  expensive quantities, some of which depend on other quantities. ``sim_f`` can
+  observe intermediate quantities in order to stop related calculations and
+  preempt future calculations associated with poor parameter values.
+
+* A user has a ``sim_f`` with multiple fidelities, with the higher-fidelity
+  evaluations requiring more computational resources, and a
+  ``gen_f``/``alloc_f`` that decides which parameters should be evaluated and
+  at what fidelity level. libEnsemble can coordinate these evaluations without
   requiring the user know parallel programming.
 
 * A user wishes to identify multiple local optima for a ``sim_f``. Furthermore,
   sensitivity analysis is desired at each identified optimum. libEnsemble can
-  use the points from the APOSMM ``gen_f`` to identify optima; and after a point is
-  ruled to be an optimum, a different ``gen_f`` can produce a collection of
-  parameters necessary for sensitivity analysis of ``sim_f``.
+  use the points from the APOSMM ``gen_f`` to identify optima; and after a
+  point is ruled to be an optimum, a different ``gen_f`` can produce a
+  collection of parameters necessary for sensitivity analysis of ``sim_f``.
 
 
 Naturally, combinations of these use cases are supported as well. An example of
@@ -74,24 +73,25 @@ relies on simulations that fail frequently.
 The libEnsemble History Array
 -----------------------------
 
-libEnsemble uses a NumPy structured array :ref:`H<datastruct-history-array>` to store output from ``gen_f`` and
-corresponding ``sim_f`` output. Similarly, ``gen_f`` and ``sim_f`` are expected to return
-output in NumPy structured arrays. The names of the fields to be given as input
-to ``gen_f`` and ``sim_f`` must be an output from ``gen_f`` or ``sim_f``. In addition to the
-fields output from ``sim_f`` and ``gen_f``, the final history returned from libEnsemble
-will include the following fields:
+libEnsemble uses a NumPy structured array :ref:`H<datastruct-history-array>` to
+store output from ``gen_f`` and corresponding ``sim_f`` output. Similarly,
+``gen_f`` and ``sim_f`` are expected to return output in NumPy structured
+arrays. The names of the fields to be given as input to ``gen_f`` and ``sim_f``
+must be an output from ``gen_f`` or ``sim_f``. In addition to the fields output
+from ``sim_f`` and ``gen_f``, the final history returned from libEnsemble will
+include the following fields:
 
-* ``sim_id`` [int]: Each unit of work output from ``gen_f`` must have an associated
-  ``sim_id``. The generator can assign this, but users must be careful to ensure
-  points are added in order. For example, ``if alloc_f`` allows for two ``gen_f``
-  instances to be running simultaneously, ``alloc_f`` should ensure that both don’t
-  generate points with the same ``sim_id``.
+* ``sim_id`` [int]: Each unit of work output from ``gen_f`` must have an
+  associated ``sim_id``. The generator can assign this, but users must be
+  careful to ensure points are added in order. For example, ``if alloc_f``
+  allows for two ``gen_f`` instances to be running simultaneously, ``alloc_f``
+  should ensure that both don’t generate points with the same ``sim_id``.
 
-* ``given`` [bool]: Has this ``gen_f`` output been given to a libEnsemble worker to be
-  evaluated yet?
+* ``given`` [bool]: Has this ``gen_f`` output been given to a libEnsemble
+  worker to be evaluated yet?
 
-* ``given_time`` [float]: At what time (since the epoch) was this ``gen_f`` output
-  given to a worker?
+* ``given_time`` [float]: At what time (since the epoch) was this ``gen_f``
+  output given to a worker?
 
 * ``sim_worker`` [int]: libEnsemble worker that it was given to be evaluated.
 
@@ -107,19 +107,24 @@ will include the following fields:
 libEnsemble Output
 ------------------
 
-The history array and :ref:`persis_info<datastruct-persis-info>` dictionary are returned to the user by libEnsemble.
-If libEnsemble aborts on an exception, these structures are dumped to files. The
-existing history array is dumped to a file named ``libE_history_at_abort_<sim_count>.npy``,
-and ``persis_info`` to ``libE_history_at_abort_<sim_count>.pickle``, where ``sim_count`` is
-the number of points evaluated.
+The history array :ref:`H<datastruct-history-array>` and
+:ref:`persis_info<datastruct-persis-info>` dictionary are returned to the user
+by libEnsemble.  If libEnsemble aborts on an exception, these structures are
+dumped to the respective files, 
+
+* ``libE_history_at_abort_<sim_count>.npy``
+* ``libE_history_at_abort_<sim_count>.pickle``
+
+where ``sim_count`` is the number of points evaluated.
 
 Other libEnsemble files produced by default are:
 
-``libE_stats.txt``: This contains a one-line summary of all user calculations. Each
-calculation summary is sent by workers to the manager and printed as the run progresses.
+* ``libE_stats.txt``: This contains a one-line summary of all user
+  calculations.  Each calculation summary is sent by workers to the manager and
+  printed as the run progresses.
 
-``ensemble.log``: This is the logging output from libEnsemble. The default logging
-is at INFO level. To gain additional diagnostics logging level can be set to DEBUG.
-If this file is not removed, multiple runs will append output. Messages at or above
-level MANAGER_WARNING are also copied to stderr to alert the user promptly.
-For more info, see :doc:`Logging<logging>`.
+* ``ensemble.log``: This is the logging output from libEnsemble. The default
+  logging is at INFO level. To gain additional diagnostics logging level can be
+  set to DEBUG.  If this file is not removed, multiple runs will append output.
+  Messages at or above level MANAGER_WARNING are also copied to stderr to alert
+  the user promptly.  For more info, see :doc:`Logging<logging>`.

From 1bc48def78cca713d783117c999ae1ae80a17e1d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 4 Oct 2019 08:58:43 -0500
Subject: [PATCH 315/644] Removing badges from PDF (only HTML)

---
 docs/index.rst      | 24 +++++++++++++-----------
 docs/quickstart.rst | 27 ++++++++++++++-------------
 2 files changed, 27 insertions(+), 24 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index 85870d4e4..6b81824f4 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -5,22 +5,24 @@
 .. image:: images/libE_logo.png
  :alt: libEnsemble
 
-|
 
-.. image:: https://img.shields.io/pypi/v/libensemble.svg?color=blue
-  :target: https://pypi.org/project/libensemble
+.. only::html
+  |
 
-.. image::  https://travis-ci.org/Libensemble/libensemble.svg?branch=master
-  :target: https://travis-ci.org/Libensemble/libensemble
+  .. image:: https://img.shields.io/pypi/v/libensemble.svg?color=blue
+    :target: https://pypi.org/project/libensemble
 
-.. image:: https://coveralls.io/repos/github/Libensemble/libensemble/badge/?maxAge=2592000/?branch=master
-  :target: https://coveralls.io/github/Libensemble/libensemble?branch=master
+  .. image::  https://travis-ci.org/Libensemble/libensemble.svg?branch=master
+    :target: https://travis-ci.org/Libensemble/libensemble
 
-.. image::  https://readthedocs.org/projects/libensemble/badge/?maxAge=2592000
-  :target: https://libensemble.readthedocs.org/en/latest/
-  :alt: Documentation Status
+  .. image:: https://coveralls.io/repos/github/Libensemble/libensemble/badge/?maxAge=2592000/?branch=master
+    :target: https://coveralls.io/github/Libensemble/libensemble?branch=master
 
-|
+  .. image::  https://readthedocs.org/projects/libensemble/badge/?maxAge=2592000
+    :target: https://libensemble.readthedocs.org/en/latest/
+    :alt: Documentation Status
+
+  |
 
 =======================================
 Welcome to libEnsemble's documentation!
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index f46cb3995..cd02cc87a 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -1,22 +1,23 @@
-.. image:: images/libE_logo.png
-   :alt: libEnsemble
+.. only::html
+  .. image:: images/libE_logo.png
+     :alt: libEnsemble
 
-|
+  |
 
-.. image:: https://img.shields.io/pypi/v/libensemble.svg?color=blue
-   :target: https://pypi.org/project/libensemble
+  .. image:: https://img.shields.io/pypi/v/libensemble.svg?color=blue
+     :target: https://pypi.org/project/libensemble
 
-.. image::  https://travis-ci.org/Libensemble/libensemble.svg?branch=master
-   :target: https://travis-ci.org/Libensemble/libensemble
+  .. image::  https://travis-ci.org/Libensemble/libensemble.svg?branch=master
+     :target: https://travis-ci.org/Libensemble/libensemble
 
-.. image:: https://coveralls.io/repos/github/Libensemble/libensemble/badge/?maxAge=2592000/?branch=master
-   :target: https://coveralls.io/github/Libensemble/libensemble?branch=master
+  .. image:: https://coveralls.io/repos/github/Libensemble/libensemble/badge/?maxAge=2592000/?branch=master
+     :target: https://coveralls.io/github/Libensemble/libensemble?branch=master
 
-.. image::  https://readthedocs.org/projects/libensemble/badge/?maxAge=2592000
-   :target: https://libensemble.readthedocs.org/en/latest/
-   :alt: Documentation Status
+  .. image::  https://readthedocs.org/projects/libensemble/badge/?maxAge=2592000
+     :target: https://libensemble.readthedocs.org/en/latest/
+     :alt: Documentation Status
 
-|
+  |
 
 ====================
 What is libEnsemble?

From 11dc2495d89c6ee3b19479708c341b851be039b5 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 4 Oct 2019 09:05:54 -0500
Subject: [PATCH 316/644] early install other blas

---
 .travis.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index 574b3d4da..7c9bd938a 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -73,7 +73,7 @@ install:
     # mkdir ../sdk; tar xf MacOSX10.14.sdk.tar.xz -C ../sdk;
   - conda install $COMPILERS
   #S- conda install nlopt petsc4py petsc mpi4py scipy $MPI
-  - conda install libopenblas
+  - conda install libblas libopenblas # Attempt to prevent 'File exists' error
   - conda install nlopt petsc4py petsc $MUMPS mpi4py scipy $MPI
   # pip install these as the conda installs downgrade pytest on python3.4
   - pip install flake8

From 8e8560eff9c3d0fb20e2e71ec47207f777a6c3cd Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 4 Oct 2019 10:24:45 -0500
Subject: [PATCH 317/644] refactoring

---
 libensemble/env_resources.py | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/libensemble/env_resources.py b/libensemble/env_resources.py
index 9c406ebc8..25390d020 100644
--- a/libensemble/env_resources.py
+++ b/libensemble/env_resources.py
@@ -106,7 +106,8 @@ def _range_split(s):
         return a, b, nnum_len
 
     @staticmethod
-    def _noderange_split(prefix, nidstr, nidlst):
+    def _noderange_split(prefix, nidstr):
+        nidlst = []
         for nidgroup in nidstr.split(','):
             a, b, nnum_len = EnvResources._range_split(nidgroup)
             for nid in range(a, b):
@@ -126,8 +127,7 @@ def get_slurm_nodelist(node_list_env):
                 return splitstr
             prefix = splitstr[0]
             nidstr = splitstr[1].strip("]")
-            nidlst = EnvResources._noderange_split(prefix, nidstr, [])
-            return sorted(nidlst)
+            nidlst = EnvResources._noderange_split(prefix, nidstr)
         else:
             splitgroups = [str.split('[', 1) for str in splitstr]
             prefixgroups = [group[0] for group in splitgroups]
@@ -136,8 +136,9 @@ def get_slurm_nodelist(node_list_env):
             for i in range(len(prefixgroups)):
                 prefix = prefixgroups[i]
                 nidstr = nodegroups[i]
-                nidlst.extend(EnvResources._noderange_split(prefix, nidstr, nidlst))
-            return sorted(set(nidlst))
+                nidlst.extend(EnvResources._noderange_split(prefix, nidstr))
+
+        return sorted(nidlst)
 
     @staticmethod
     def get_cobalt_nodelist(node_list_env):

From 4ed85170572f645c315379b94440094bed856e93 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 4 Oct 2019 10:38:38 -0500
Subject: [PATCH 318/644] comments, formatting

---
 libensemble/env_resources.py | 25 ++++++++++++++++++-------
 1 file changed, 18 insertions(+), 7 deletions(-)

diff --git a/libensemble/env_resources.py b/libensemble/env_resources.py
index 25390d020..9ce951e04 100644
--- a/libensemble/env_resources.py
+++ b/libensemble/env_resources.py
@@ -33,6 +33,7 @@ class EnvResources:
     default_nodelist_env_lsf = 'LSB_HOSTS'
     default_nodelist_env_lsf_shortform = 'LSB_MCPU_HOSTS'
 
+
     def __init__(self,
                  nodelist_env_slurm=None,
                  nodelist_env_cobalt=None,
@@ -76,6 +77,7 @@ def __init__(self,
         self.ndlist_funcs['LSF'] = EnvResources.get_lsf_nodelist
         self.ndlist_funcs['LSF_shortform'] = EnvResources.get_lsf_nodelist_frm_shortform
 
+
     def get_nodelist(self):
         """Return nodelist from environment or an empty list"""
         for env, env_var in self.nodelists.items():
@@ -87,12 +89,14 @@ def get_nodelist(self):
                 return global_nodelist
         return []
 
+
     def abbrev_nodenames(self, node_list):
         """Return nodelist with entries in abbreviated form"""
         if self.schedular == 'Cobalt':
             return EnvResources.cobalt_abbrev_nodenames(node_list)
         return node_list
 
+
     @staticmethod
     def _range_split(s):
         """Split ID range string."""
@@ -105,8 +109,10 @@ def _range_split(s):
         b = b + 1
         return a, b, nnum_len
 
+
     @staticmethod
-    def _noderange_split(prefix, nidstr):
+    def _noderange_append(prefix, nidstr):
+        """Format and append nodes to overall nodelist"""
         nidlst = []
         for nidgroup in nidstr.split(','):
             a, b, nnum_len = EnvResources._range_split(nidgroup)
@@ -114,21 +120,22 @@ def _noderange_split(prefix, nidstr):
                 nidlst.append(prefix + str(nid).zfill(nnum_len))
         return nidlst
 
+
     @staticmethod
     def get_slurm_nodelist(node_list_env):
         """Get global libEnsemble nodelist from the Slurm environment"""
         fullstr = os.environ[node_list_env]
         if not fullstr:
             return []
-        splitstr = fullstr.split('],')
-        if len(splitstr) == 1:
+        part_splitstr = fullstr.split('],')
+        if len(part_splitstr) == 1:     # Single Partition
             splitstr = fullstr.split('[', 1)
-            if len(splitstr) == 1:
+            if len(splitstr) == 1:      # Single Node
                 return splitstr
             prefix = splitstr[0]
             nidstr = splitstr[1].strip("]")
-            nidlst = EnvResources._noderange_split(prefix, nidstr)
-        else:
+            nidlst = EnvResources._noderange_append(prefix, nidstr)
+        else:                           # Multiple Partitions
             splitgroups = [str.split('[', 1) for str in splitstr]
             prefixgroups = [group[0] for group in splitgroups]
             nodegroups = [group[1].strip(']') for group in splitgroups]
@@ -136,10 +143,11 @@ def get_slurm_nodelist(node_list_env):
             for i in range(len(prefixgroups)):
                 prefix = prefixgroups[i]
                 nidstr = nodegroups[i]
-                nidlst.extend(EnvResources._noderange_split(prefix, nidstr))
+                nidlst.extend(EnvResources._noderange_append(prefix, nidstr))
 
         return sorted(nidlst)
 
+
     @staticmethod
     def get_cobalt_nodelist(node_list_env):
         """Get global libEnsemble nodelist from the Cobalt environment"""
@@ -153,6 +161,7 @@ def get_cobalt_nodelist(node_list_env):
                 nidlst.append(str(nid))
         return sorted(nidlst, key=int)
 
+
     @staticmethod
     def cobalt_abbrev_nodenames(node_list, prefix='nid'):
         """Return nodelist with prefix and leading zeros stripped"""
@@ -160,6 +169,7 @@ def cobalt_abbrev_nodenames(node_list, prefix='nid'):
         newlist = [s.lstrip('0') for s in newlist]
         return newlist
 
+
     @staticmethod
     def get_lsf_nodelist(node_list_env):
         """Get global libEnsemble nodelist from the LSF environment"""
@@ -170,6 +180,7 @@ def get_lsf_nodelist(node_list_env):
         nodes = [n for n in unique_entries if 'batch' not in n]
         return nodes
 
+
     @staticmethod
     def get_lsf_nodelist_frm_shortform(node_list_env):
         """Get global libEnsemble nodelist from the LSF environment from short-form version"""

From 155ba0c0517046e8ec305e76862bc6f0a44fafc7 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 4 Oct 2019 10:40:02 -0500
Subject: [PATCH 319/644] rename var

---
 libensemble/env_resources.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/env_resources.py b/libensemble/env_resources.py
index 9ce951e04..bcccee3ec 100644
--- a/libensemble/env_resources.py
+++ b/libensemble/env_resources.py
@@ -136,7 +136,7 @@ def get_slurm_nodelist(node_list_env):
             nidstr = splitstr[1].strip("]")
             nidlst = EnvResources._noderange_append(prefix, nidstr)
         else:                           # Multiple Partitions
-            splitgroups = [str.split('[', 1) for str in splitstr]
+            splitgroups = [str.split('[', 1) for str in part_splitstr]
             prefixgroups = [group[0] for group in splitgroups]
             nodegroups = [group[1].strip(']') for group in splitgroups]
             nidlst = []

From 6205eeef6aeec5d7809f1c0e964be09c8f9b50f5 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 4 Oct 2019 10:53:47 -0500
Subject: [PATCH 320/644] flake8

---
 libensemble/env_resources.py | 10 ----------
 1 file changed, 10 deletions(-)

diff --git a/libensemble/env_resources.py b/libensemble/env_resources.py
index bcccee3ec..b818780cb 100644
--- a/libensemble/env_resources.py
+++ b/libensemble/env_resources.py
@@ -33,7 +33,6 @@ class EnvResources:
     default_nodelist_env_lsf = 'LSB_HOSTS'
     default_nodelist_env_lsf_shortform = 'LSB_MCPU_HOSTS'
 
-
     def __init__(self,
                  nodelist_env_slurm=None,
                  nodelist_env_cobalt=None,
@@ -77,7 +76,6 @@ def __init__(self,
         self.ndlist_funcs['LSF'] = EnvResources.get_lsf_nodelist
         self.ndlist_funcs['LSF_shortform'] = EnvResources.get_lsf_nodelist_frm_shortform
 
-
     def get_nodelist(self):
         """Return nodelist from environment or an empty list"""
         for env, env_var in self.nodelists.items():
@@ -89,14 +87,12 @@ def get_nodelist(self):
                 return global_nodelist
         return []
 
-
     def abbrev_nodenames(self, node_list):
         """Return nodelist with entries in abbreviated form"""
         if self.schedular == 'Cobalt':
             return EnvResources.cobalt_abbrev_nodenames(node_list)
         return node_list
 
-
     @staticmethod
     def _range_split(s):
         """Split ID range string."""
@@ -109,7 +105,6 @@ def _range_split(s):
         b = b + 1
         return a, b, nnum_len
 
-
     @staticmethod
     def _noderange_append(prefix, nidstr):
         """Format and append nodes to overall nodelist"""
@@ -120,7 +115,6 @@ def _noderange_append(prefix, nidstr):
                 nidlst.append(prefix + str(nid).zfill(nnum_len))
         return nidlst
 
-
     @staticmethod
     def get_slurm_nodelist(node_list_env):
         """Get global libEnsemble nodelist from the Slurm environment"""
@@ -147,7 +141,6 @@ def get_slurm_nodelist(node_list_env):
 
         return sorted(nidlst)
 
-
     @staticmethod
     def get_cobalt_nodelist(node_list_env):
         """Get global libEnsemble nodelist from the Cobalt environment"""
@@ -161,7 +154,6 @@ def get_cobalt_nodelist(node_list_env):
                 nidlst.append(str(nid))
         return sorted(nidlst, key=int)
 
-
     @staticmethod
     def cobalt_abbrev_nodenames(node_list, prefix='nid'):
         """Return nodelist with prefix and leading zeros stripped"""
@@ -169,7 +161,6 @@ def cobalt_abbrev_nodenames(node_list, prefix='nid'):
         newlist = [s.lstrip('0') for s in newlist]
         return newlist
 
-
     @staticmethod
     def get_lsf_nodelist(node_list_env):
         """Get global libEnsemble nodelist from the LSF environment"""
@@ -180,7 +171,6 @@ def get_lsf_nodelist(node_list_env):
         nodes = [n for n in unique_entries if 'batch' not in n]
         return nodes
 
-
     @staticmethod
     def get_lsf_nodelist_frm_shortform(node_list_env):
         """Get global libEnsemble nodelist from the LSF environment from short-form version"""

From 713319765c87c808ead1ebf69b280c42290f86eb Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 4 Oct 2019 11:38:13 -0500
Subject: [PATCH 321/644] Adding better 'basic usage' section to README

---
 README.rst | 54 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 47 insertions(+), 7 deletions(-)

diff --git a/README.rst b/README.rst
index 7105a700a..c57e58f62 100644
--- a/README.rst
+++ b/README.rst
@@ -35,9 +35,20 @@ libEnsemble aims for:
 • Portability and flexibility
 • Exploitation of persistent data/control flow.
 
-A more detailed overview can be found in the docs_.
-
-.. _docs:  https://libensemble.readthedocs.org/en/latest/
+The user selects or supplies a generation function that produces simulation
+input as well as a simulation function that performs and monitors the
+simulations. The generation function may contain, for example, an optimization
+method to generate new simulation parameters on-the-fly and based on the
+results of previous simulations.  Examples and templates of these functions are
+included in the library.
+
+libEnsemble employs a manager-worker scheme that can run on various
+communication media (including MPI, multiprocessing, and TCP). Each worker can
+control and monitor any level of work from small sub-node jobs to huge
+many-node simulations. A job controller interface is provided to ensure scripts
+are portable, resilient and flexible; it also enables automatic detection of
+the nodes and cores in a system and can split up jobs automatically if resource
+data isn't supplied.
 
 A visual overview is given in the libEnsemble poster_.
 
@@ -80,8 +91,8 @@ The example sim and gen functions and tests require the following dependencies:
 
 PETSc and NLopt must be built with shared libraries enabled and present in
 ``sys.path`` (e.g., via setting the ``PYTHONPATH`` environment variable). NLopt
-should produce a file nlopt.py if Python is found on the system.
-
+should produce a file nlopt.py if Python is found on the system. NLopt may also
+require SWIG_ to be installed on certain systems.
 
 
 Installation
@@ -154,9 +165,38 @@ Basic Usage
 The examples directory contains example libEnsemble calling scripts, sim
 functions, gen functions, alloc functions and job submission scripts.
 
-See the `user-guide <https://libensemble.readthedocs.io/en/latest/quickstart.html#basic-usage>`_ for more information.
+The user creates a python script to call the libEnsemble :doc:`libE
+<libE_module>` function.  This must supply the
+:ref:`sim_specs<datastruct-sim-specs>` and
+:ref:`gen_specs<datastruct-gen-specs>`, and optionally
+:ref:`libE_specs<datastruct-libe-specs>`,
+:ref:`alloc_specs<datastruct-alloc-specs>` and
+:ref:`persis_info<datastruct-persis-info>`.
+
+The default manager/worker communications mode is MPI. The user script is
+launched as::
+
+    mpiexec -np N python myscript.py
+
+where ``N`` is the number of processors. This will launch one manager and
+``N-1`` workers.
+
+If running in local mode, which uses Python's multiprocessing module, the
+'local' comms option and the number of workers must be specified in
+:ref:`libE_specs<datastruct-libe-specs>`. The script can then be run as a
+regular python script::
+
+    python myscript.py
+
+When specifying these options via command line options, one may use the
+``parse_args`` function used in the regression tests, which can be found in
+``libensemble/tests/regression_tests/common.py``
+
+
+See the
+`user-guide<https://libensemble.readthedocs.io/en/latest/user_guide.html>`_ for
+more information.
 
-.. docs-include-tag
 
 Documentation
 -------------

From 0c9263ae3e8fe6c0a110b8912fed0ae2b340928c Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 4 Oct 2019 11:47:19 -0500
Subject: [PATCH 322/644] Using README inside quickstart

---
 README.rst          |  10 ++-
 docs/quickstart.rst | 186 +-------------------------------------------
 2 files changed, 7 insertions(+), 189 deletions(-)

diff --git a/README.rst b/README.rst
index c57e58f62..f45f2dcef 100644
--- a/README.rst
+++ b/README.rst
@@ -17,6 +17,7 @@
    :alt: Documentation Status
 
 |
+.. after_badges_tag
 
 ====================
 What is libEnsemble?
@@ -193,9 +194,9 @@ When specifying these options via command line options, one may use the
 ``libensemble/tests/regression_tests/common.py``
 
 
-See the
-`user-guide<https://libensemble.readthedocs.io/en/latest/user_guide.html>`_ for
-more information.
+See the 
+`user-guide <https://libensemble.readthedocs.io/en/latest/user_guide.html>`_
+for more information.
 
 
 Documentation
@@ -210,7 +211,8 @@ Please use the following to cite libEnsemble in a publication:
 .. code-block:: bibtex
 
   @techreport{libEnsemble,
-    author      = {Stephen Hudson and Jeffrey Larson and Stefan M. Wild and David Bindel and John-Luke Navarro},
+    author      = {Stephen Hudson and Jeffrey Larson and Stefan M. Wild and
+                   David Bindel and John-Luke Navarro},
     title       = {{libEnsemble} Users Manual},
     institution = {Argonne National Laboratory},
     number      = {Revision 0.5.2},
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index cd02cc87a..755fd6fbd 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -19,190 +19,6 @@
 
   |
 
-====================
-What is libEnsemble?
-====================
-
-libEnsemble is a Python library to coordinate the concurrent evaluation of
-ensembles of computations. Designed with flexibility in mind, libEnsemble can
-utilize massively parallel resources to accelerate the solution of design,
-decision, and inference problems.
-
-libEnsemble aims for:
-
-• Extreme scaling
-• Resilience/fault tolerance
-• Monitoring/killing jobs (and recovering resources)
-• Portability and flexibility
-• Exploitation of persistent data/control flow.
-
-The user selects or supplies a generation function that produces simulation
-input as well as a simulation function that performs and monitors the
-simulations. The generation function may contain, for example, an optimization
-method to generate new simulation parameters on-the-fly and based on the
-results of previous simulations.  Examples and templates of these functions are
-included in the library.
-
-libEnsemble employs a manager-worker scheme that can run on various
-communication media (including MPI, multiprocessing, and TCP). Each worker can
-control and monitor any level of work from small sub-node jobs to huge
-many-node simulations. A job controller interface is provided to ensure scripts
-are portable, resilient and flexible; it also enables automatic detection of
-the nodes and cores in a system and can split up jobs automatically if resource
-data isn't supplied.
-
-A visual overview is given in the libEnsemble poster_.
-
-.. _poster:  https://figshare.com/articles/LibEnsemble_PETSc_TAO-_Sustaining_a_library_for_dynamic_ensemble-based_computations/7765454
-
-
-Dependencies
-------------
-
-Required dependencies:
-
-* Python_ 3.5 or above.
-
-* NumPy_
-
-For libEnsemble running with the mpi4py parallelism:
-
-* A functional MPI 1.x/2.x/3.x implementation such as `MPICH
-  <http://www.mpich.org/>`_  built with shared/dynamic libraries.
-
-* mpi4py_ v2.0.0 or above
-
-
-Optional dependency:
-
-* Balsam_
-
-From v0.2.0, libEnsemble has the option of using the Balsam job manager. This
-is required for running libEnsemble on the compute nodes of some supercomputing
-platforms (e.g., Cray XC40); platforms that do not support launching jobs from
-compute nodes. Note that as of v0.5.0, libEnsemble can also be run on the
-launch nodes using multiprocessing.
-
-The example sim and gen functions and tests require the following dependencies:
-
-* SciPy_
-* petsc4py_
-* PETSc_ - This can optionally be installed by pip along with petsc4py
-* NLopt_ - Installed with `shared libraries enabled <http://ab-initio.mit.edu/wiki/index.php/NLopt_Installation#Shared_libraries>`_.
-
-PETSc and NLopt must be built with shared libraries enabled and present in
-``sys.path`` (e.g., via setting the ``PYTHONPATH`` environment variable). NLopt
-should produce a file nlopt.py if Python is found on the system. NLopt may also
-require SWIG_ to be installed on certain systems.
-
-
-Installation
-------------
-
-Use pip to install libEnsemble and its dependencies::
-
-    pip install libensemble
-
-libEnsemble is also available in the Spack_ distribution. It can be installed from Spack with::
-
-    spack install py-libensemble
-
-.. _Spack: https://spack.readthedocs.io/en/latest
-
-The tests and examples can be accessed in the `GitHub <https://github.com/Libensemble/libensemble>`_ repository.
-If necessary, you may install all optional dependencies (listed above) at once with::
-
-    pip install libensemble[extras]
-
-A `tarball <https://github.com/Libensemble/libensemble/releases/latest>`_ of the most recent release is also available.
-
-
-Testing
----------
-
-The provided test suite includes both unit and regression tests and is run
-regularly on:
-
-* `Travis CI <https://travis-ci.org/Libensemble/libensemble>`_
-
-The test suite requires the mock_, pytest_, pytest-cov_, and pytest-timeout_
-packages to be installed and can be run from the libensemble/tests directory of
-the source distribution by running::
-
-    ./run-tests.sh
-
-To clean the test repositories run::
-
-    ./run-tests.sh -c
-
-Further options are available. To see a complete list of options run::
-
-    ./run-tests.sh -h
-
-If you have the source distribution, you can download (but not install) the testing
-prerequisites and run the tests with::
-
-    python setup.py test
-
-in the top-level directory containing the setup script.
-
-Coverage reports are produced separately for unit tests and regression tests
-under the relevant directories. For parallel tests, the union of all processors
-is taken. Furthermore, a combined coverage report is created at the top level,
-which can be viewed after running the tests via the HTML file
-``libensemble/tests/cov_merge/index.html``. The Travis CI coverage results are
-available online at
-`Coveralls <https://coveralls.io/github/Libensemble/libensemble?branch=master>`_.
-
-Note: The job_controller tests can be run using the direct-launch or
-Balsam job controllers. Although only the direct-launch versions can
-be run on Travis CI, Balsam integration with libEnsemble is now tested via
-``test_balsam_hworld.py``.
-
-
-Basic Usage
------------
-
-The examples directory contains example libEnsemble calling scripts, sim
-functions, gen functions, alloc functions and job submission scripts.
-
-The user creates a python script to call the libEnsemble :doc:`libE <libE_module>` function.
-This must supply the :ref:`sim_specs<datastruct-sim-specs>` and :ref:`gen_specs<datastruct-gen-specs>`,
-and optionally :ref:`libE_specs<datastruct-libe-specs>`, :ref:`alloc_specs<datastruct-alloc-specs>` and :ref:`persis_info<datastruct-persis-info>`.
-
-The default manager/worker communications mode is MPI. The user script is launched as::
-
-    mpiexec -np N python myscript.py
-
-where ``N`` is the number of processors. This will launch one manager and ``N-1`` workers.
-
-If running in local mode, which uses Python's multiprocessing module, the 'local'
-comms option and the number of workers must be specified in :ref:`libE_specs<datastruct-libe-specs>`.
-The script can then be run as a regular python script::
-
-    python myscript.py
-
-When specifying these options via command line options, one may use the ``parse_args``
-function used in the regression tests, which can be found in
-``libensemble/tests/regression_tests/common.py``
-
-
-See the `user-guide <https://libensemble.readthedocs.io/en/latest/user_guide.html>`_ for more information.
-
 .. include:: ../README.rst
-    :start-after: docs-include-tag
-
-.. _PETSc:  http://www.mcs.anl.gov/petsc
-.. _Python: http://www.python.org
-.. _nlopt: http://ab-initio.mit.edu/wiki/index.php/NLopt
-.. _NumPy:  http://www.numpy.org
-.. _SciPy:  http://www.scipy.org
-.. _mpi4py:  https://bitbucket.org/mpi4py/mpi4py
-.. _petsc4py:  https://bitbucket.org/petsc/petsc4py
-.. _Balsam: https://www.alcf.anl.gov/balsam
-.. _SWIG: http://swig.org/
-.. _mock: https://pypi.org/project/mock
-.. _pytest: https://pypi.org/project/pytest/
-.. _pytest-cov: https://pypi.org/project/pytest-cov/
-.. _pytest-timeout: https://pypi.org/project/pytest-timeout/
+    :start-after: after_badges_tag 
 

From bbe1bab0bfe6806d9b4668b772e16f0981133431 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 4 Oct 2019 11:58:43 -0500
Subject: [PATCH 323/644] Better logo quality

---
 docs/conf.py              |   1 +
 docs/images/libE_logo.png | Bin 10227 -> 54153 bytes
 2 files changed, 1 insertion(+)
 mode change 100644 => 100755 docs/images/libE_logo.png

diff --git a/docs/conf.py b/docs/conf.py
index 58fe4632a..0a0e70d4b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -188,6 +188,7 @@ def __getattr__(cls, name):
      'Stephen Hudson, Jeffrey Larson, Stefan M. Wild, \\\\ \\hfill David Bindel, John-Luke Navarro', 'manual'),
 ]
 
+latex_logo = 'images/libEnsemble_Logo.png'
 
 # -- Options for manual page output ---------------------------------------
 
diff --git a/docs/images/libE_logo.png b/docs/images/libE_logo.png
old mode 100644
new mode 100755
index 81d1e2589e340395778ed9251dfd4b84abf032c9..17f051faab46f91a58f98c4dc617304e97707fcf
GIT binary patch
literal 54153
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
C=c%y(

literal 10227
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
C)^VZ$


From efbf91be0c09f88fac5f451247e48a699c1b393d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 4 Oct 2019 12:33:46 -0500
Subject: [PATCH 324/644] Removing sphinx refs from README

---
 README.rst                     | 13 ++-----------
 docs/conf.py                   |  2 +-
 docs/quickstart.rst            |  3 +--
 docs/rst_formatting_guidelines |  4 ++--
 docs/user_guide.rst            |  4 ++--
 5 files changed, 8 insertions(+), 18 deletions(-)

diff --git a/README.rst b/README.rst
index f45f2dcef..b9a6527ae 100644
--- a/README.rst
+++ b/README.rst
@@ -166,14 +166,6 @@ Basic Usage
 The examples directory contains example libEnsemble calling scripts, sim
 functions, gen functions, alloc functions and job submission scripts.
 
-The user creates a python script to call the libEnsemble :doc:`libE
-<libE_module>` function.  This must supply the
-:ref:`sim_specs<datastruct-sim-specs>` and
-:ref:`gen_specs<datastruct-gen-specs>`, and optionally
-:ref:`libE_specs<datastruct-libe-specs>`,
-:ref:`alloc_specs<datastruct-alloc-specs>` and
-:ref:`persis_info<datastruct-persis-info>`.
-
 The default manager/worker communications mode is MPI. The user script is
 launched as::
 
@@ -183,9 +175,8 @@ where ``N`` is the number of processors. This will launch one manager and
 ``N-1`` workers.
 
 If running in local mode, which uses Python's multiprocessing module, the
-'local' comms option and the number of workers must be specified in
-:ref:`libE_specs<datastruct-libe-specs>`. The script can then be run as a
-regular python script::
+'local' comms option and the number of workers must be specified. The script
+can then be run as a regular python script::
 
     python myscript.py
 
diff --git a/docs/conf.py b/docs/conf.py
index 0a0e70d4b..c92efaa9d 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -188,7 +188,7 @@ def __getattr__(cls, name):
      'Stephen Hudson, Jeffrey Larson, Stefan M. Wild, \\\\ \\hfill David Bindel, John-Luke Navarro', 'manual'),
 ]
 
-latex_logo = 'images/libEnsemble_Logo.png'
+latex_logo = 'images/libE_logo.png'
 
 # -- Options for manual page output ---------------------------------------
 
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index 755fd6fbd..8d1e85bbf 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -20,5 +20,4 @@
   |
 
 .. include:: ../README.rst
-    :start-after: after_badges_tag 
-
+    :start-after: after_badges_tag
diff --git a/docs/rst_formatting_guidelines b/docs/rst_formatting_guidelines
index 83329a529..bedb5707f 100644
--- a/docs/rst_formatting_guidelines
+++ b/docs/rst_formatting_guidelines
@@ -7,9 +7,9 @@ Put referenced file names in between double ticks ``stuff here`` (no quotes)
 
 Put environment variables in between double ticks ``stuff here`` (no quotes)
 
-Put warnings line: **WARNING:** 
+Put warnings line: **WARNING:**
 
-Put breakout code snippets into a box using two colons :: 
+Put breakout code snippets into a box using two colons ::
 
 No italics on text of links
 
diff --git a/docs/user_guide.rst b/docs/user_guide.rst
index cbdbe20fb..78ac30302 100644
--- a/docs/user_guide.rst
+++ b/docs/user_guide.rst
@@ -13,7 +13,7 @@ three routines:
 * :ref:`sim_f<api_sim_f>`: Evaluates a simulation or other evaluation at output from ``gen_f``.
 * :ref:`alloc_f<api_alloc_f>`: Decides whether ``sim_f`` or ``gen_f`` should be called (and with what input/resources) as workers become available.
 
-Example ``sim_f``, ``gen_f``, ``alloc_f``, and calling scripts 
+Example ``sim_f``, ``gen_f``, ``alloc_f``, and calling scripts
 be found in the ``examples/`` directory. To enable portability, a
 :doc:`job_controller<job_controller/overview>`
 interface is supplied for users to launch and monitor jobs in their
@@ -110,7 +110,7 @@ libEnsemble Output
 The history array :ref:`H<datastruct-history-array>` and
 :ref:`persis_info<datastruct-persis-info>` dictionary are returned to the user
 by libEnsemble.  If libEnsemble aborts on an exception, these structures are
-dumped to the respective files, 
+dumped to the respective files,
 
 * ``libE_history_at_abort_<sim_count>.npy``
 * ``libE_history_at_abort_<sim_count>.pickle``

From 5db1aaef56550f54cc9d99d00649b236845739d4 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 4 Oct 2019 13:25:17 -0500
Subject: [PATCH 325/644] Removing blank pages in pdf

---
 docs/conf.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/conf.py b/docs/conf.py
index c92efaa9d..9c7caf46a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -163,6 +163,9 @@ def __getattr__(cls, name):
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
+    # Sonny, Lenny, or Bjornstrup
+    'fncychap': '\\usepackage[Lenny]{fncychap}',
+    'extraclassoptions': 'openany',
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',

From cabaeb1abbfc2f22d0820712997ca9345bbae538 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 4 Oct 2019 13:56:42 -0500
Subject: [PATCH 326/644] Avoiding linewraps in pdf

---
 docs/conf.py                           | 10 ++++++
 docs/tutorials/local_sine_tutorial.rst | 46 +++++++++++++-------------
 2 files changed, 33 insertions(+), 23 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 9c7caf46a..3440c1048 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -68,6 +68,12 @@ def __getattr__(cls, name):
 #breathe_projects_source = {"libEnsemble" : ( "../code/src/", ["test.cpp","test2.cpp"] )}
 
 autodoc_mock_imports = ["balsam"]
+extlinks = {'duref': ('http://docutils.sourceforge.net/docs/ref/rst/'
+                      'restructuredtext.html#%s', ''),
+            'durole': ('http://docutils.sourceforge.net/docs/ref/rst/'
+                       'roles.html#%s', ''),
+            'dudir': ('http://docutils.sourceforge.net/docs/ref/rst/'
+                      'directives.html#%s', '')}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -166,6 +172,10 @@ def __getattr__(cls, name):
     # Sonny, Lenny, or Bjornstrup
     'fncychap': '\\usepackage[Lenny]{fncychap}',
     'extraclassoptions': 'openany',
+    'preamble':
+    r'''
+
+                ''',
     # The paper size ('letterpaper' or 'a4paper').
     #
     # 'papersize': 'letterpaper',
diff --git a/docs/tutorials/local_sine_tutorial.rst b/docs/tutorials/local_sine_tutorial.rst
index 0e23fb40a..54c8fccf5 100644
--- a/docs/tutorials/local_sine_tutorial.rst
+++ b/docs/tutorials/local_sine_tutorial.rst
@@ -182,16 +182,16 @@ inputs and outputs from those functions to expect.
 .. code-block:: python
     :linenos:
 
-    gen_specs = {'gen_f': gen_random_sample,      # Our generator function
-                 'in': ['sim_id'],                  # Input field names. 'sim_id' necessary default
-                 'out': [('x', float, (1,))],       # gen_f output (name, type, size).
-                 'lower': np.array([-3]),           # lower boundary for random sampling.
-                 'upper': np.array([3]),            # upper boundary for random sampling.
-                 'gen_batch_size': 5}               # number of values gen_f will generate per call
-
-    sim_specs = {'sim_f': sim_find_sine,          # Our simulator function
-                 'in': ['x'],                       # Input field names. 'x' from gen_f output
-                 'out': [('y', float)]}             # sim_f output. 'y' = sine('x')
+    gen_specs = {'gen_f': gen_random_sample,   # Our generator function
+                 'in': ['sim_id'],             # Input field names. 'sim_id' necessary default
+                 'out': [('x', float, (1,))],  # gen_f output (name, type, size)
+                 'lower': np.array([-3]),      # lower boundary for random sampling
+                 'upper': np.array([3]),       # upper boundary for random sampling
+                 'gen_batch_size': 5}          # number of x's gen_f generates per call
+                                               
+    sim_specs = {'sim_f': sim_find_sine,       # Our simulator function
+                 'in': ['x'],                  # Input field names. 'x' from gen_f output
+                 'out': [('y', float)]}        # sim_f output. 'y' = sine('x')
 
 
 Recall that each worker is assigned an entry in the :ref:`persis_info<datastruct-persis-info>`
@@ -204,12 +204,12 @@ circumstances where libEnsemble should stop execution in :ref:`exit_criteria<dat
 
     persis_info = {}
 
-    for i in range(1, nworkers+1):                # Worker numbers start at 1.
+    for i in range(1, nworkers+1):            # Worker numbers start at 1
         persis_info[i] = {
             'rand_stream': np.random.RandomState(i),
             'worker_num': i}
 
-    exit_criteria = {'sim_max': 80}               # Stop libEnsemble after 80 simulations
+    exit_criteria = {'sim_max': 80}           # Stop libEnsemble after 80 simulations
 
 Now we're ready to write our libEnsemble :doc:`libE<../libE_module>` function call.
 This :ref:`H<datastruct-history-array>` is the final version of the History array.
@@ -221,7 +221,7 @@ This :ref:`H<datastruct-history-array>` is the final version of the History arra
     H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
                                 libE_specs=libE_specs)
 
-    print([i for i in H.dtype.fields])            # Some (optional) statements to visualize our History array
+    print([i for i in H.dtype.fields])        # Some (optional) statements to visualize our History array
     print(H)
 
 That's it! Now that these files are complete, we can run our simulation.
@@ -237,11 +237,11 @@ be rearranged.
 .. code-block::
 
   ['y', 'given_time', 'gen_worker', 'sim_worker', 'given', 'returned', 'x', 'allocated', 'sim_id', 'gen_time']
-  [(-0.37466051, 1.55968252e+09, 2, 2,  True,  True, [-0.38403059],  True,  0, 1.55968252e+09)
-  (-0.29279634, 1.55968252e+09, 2, 3,  True,  True, [-2.84444261],  True,  1, 1.55968252e+09)
-  ( 0.29358492, 1.55968252e+09, 2, 4,  True,  True, [ 0.29797487],  True,  2, 1.55968252e+09)
-  (-0.3783986 , 1.55968252e+09, 2, 1,  True,  True, [-0.38806564],  True,  3, 1.55968252e+09)
-  (-0.45982062, 1.55968252e+09, 2, 2,  True,  True, [-0.47779319],  True,  4, 1.55968252e+09)
+  [(-0.37466051, 1.559+09, 2, 2,  True,  True, [-0.38403059],  True,  0, 1.559+09)
+  (-0.29279634, 1.559+09, 2, 3,  True,  True, [-2.84444261],  True,  1, 1.559+09)
+  ( 0.29358492, 1.559+09, 2, 4,  True,  True, [ 0.29797487],  True,  2, 1.559+09)
+  (-0.3783986 , 1.559+09, 2, 1,  True,  True, [-0.38806564],  True,  3, 1.559+09)
+  (-0.45982062, 1.559+09, 2, 2,  True,  True, [-0.47779319],  True,  4, 1.559+09)
   ...
 
 In this arrangement, our output values are listed on the far-left with the generated
@@ -320,11 +320,11 @@ of the calling script as follows:
     from simulator import sim_find_sine
     from mpi4py import MPI
 
-    # nworkers = 4                                  # nworkers will come from MPI
-    libE_specs = {'comms': 'mpi'}                   # 'nworkers' removed, 'comms' now 'mpi'
+    # nworkers = 4                                # nworkers will come from MPI
+    libE_specs = {'comms': 'mpi'}                 # 'nworkers' removed, 'comms' now 'mpi'
 
     nworkers = MPI.COMM_WORLD.Get_size() - 1
-    is_master = (MPI.COMM_WORLD.Get_rank() == 0)    # master process has MPI rank 0
+    is_master = (MPI.COMM_WORLD.Get_rank() == 0)  # master process has MPI rank 0
 
 So that only one process executes the graphing and printing portion of our code,
 modify the bottom of the calling script like this:
@@ -337,8 +337,8 @@ modify the bottom of the calling script like this:
                                 libE_specs=libE_specs)
 
     if is_master:
-
-        print([i for i in H.dtype.fields])            # Some (optional) statements to visualize our History array
+        # Some (optional) statements to visualize our History array
+        print([i for i in H.dtype.fields])  
         print(H)
 
         import matplotlib.pyplot as plt

From 47713d7ba991c78f439a4929f40daa94fa5342c1 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 4 Oct 2019 14:07:07 -0500
Subject: [PATCH 327/644] Editing comments for clarity/space

---
 docs/data_structures/work_dict.rst | 17 ++++++-----------
 libensemble/libE_fields.py         | 12 ++++++------
 2 files changed, 12 insertions(+), 17 deletions(-)

diff --git a/docs/data_structures/work_dict.rst b/docs/data_structures/work_dict.rst
index 4c1310b34..4dd50482c 100644
--- a/docs/data_structures/work_dict.rst
+++ b/docs/data_structures/work_dict.rst
@@ -11,19 +11,14 @@ Dictionary with integer keys ``i`` and dictionary values to be given to worker `
 
         Required keys :
         'persis_info' [dict]: Any persistent info to be sent to worker 'i'
-
         'H_fields' [list]: The field names of the history 'H' to be sent to worker 'i'
+        'tag' [int]: 'EVAL_SIM_TAG'/'EVAL_GEN_TAG') if worker 'i' is to call sim/gen_func
+        'libE_info' [dict]: Info sent to/from worker to help manager update the 'H'
 
-        'tag' [int]: 'EVAL_SIM_TAG' (resp. 'EVAL_GEN_TAG') if worker 'i' is to call sim_func (resp. gen_func)
-
-        'libE_info' [dict]: This information is sent to and returned from the worker to help libEnsemble quickly update the 'H' and 'W'.
-            Available keys are:
-
-            H_rows' [list of ints]: History rows to send to worker 'i'
-
-            blocking' [list of ints]: Workers to be blocked by the calculation given to worker 'i'
-
-            persistent' [bool]: True if worker 'i' will enter persistent mode
+        Available keys are:
+        'H_rows' [list of ints]: History rows to send to worker 'i'
+        'blocking' [list of ints]: Workers to be blocked by this calculation 
+        'persistent' [bool]: True if worker 'i' will enter persistent mode
 
 
 :Examples:
diff --git a/libensemble/libE_fields.py b/libensemble/libE_fields.py
index fc74f8346..00176bcce 100644
--- a/libensemble/libE_fields.py
+++ b/libensemble/libE_fields.py
@@ -1,11 +1,11 @@
 """
 Below are the fields used within libEnsemble
 """
-libE_fields = [('sim_id', int),        # The number of the entry in H that was generated
-               ('given', bool),        # True if the entry has been given to a worker for a sim eval
-               ('given_time', float),  # Time (since epoch) that the entry was given to a worker for a sim eval
-               ('sim_worker', int),    # Worker that did (or is doing) the sim eval
+libE_fields = [('sim_id', int),        # Unique id of entry in H that was generated
                ('gen_worker', int),    # Worker that generated the entry
-               ('gen_time', float),    # Time (since epoch) that entry was entered into H
-               ('returned', bool),     # True if the entry has been returned from the sim eval
+               ('gen_time', float),    # Time (since epoch) entry was entered into H
+               ('given', bool),        # True if entry has been given for sim eval
+               ('returned', bool),     # True if entry has been returned from sim eval
+               ('given_time', float),  # Time (since epoch) that the entry was given 
+               ('sim_worker', int),    # Worker that did (or is doing) the sim eval
                ]

From 92bd3e0b29c2acceb6e2433cc3f403dfa7ce0af5 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 4 Oct 2019 14:09:47 -0500
Subject: [PATCH 328/644] Seeing if i can control this image

---
 README.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/README.rst b/README.rst
index b9a6527ae..60ef78d63 100644
--- a/README.rst
+++ b/README.rst
@@ -1,4 +1,6 @@
 .. image:: docs/images/libE_logo.png
+   :scale: 90
+   :align: center
    :alt: libEnsemble
 
 |

From 5b8fdf7b13c4ff52d0a1f16da395695b7b5de18e Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 4 Oct 2019 14:10:18 -0500
Subject: [PATCH 329/644] Seeing if i can control this image

---
 README.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.rst b/README.rst
index 60ef78d63..fc29af6e0 100644
--- a/README.rst
+++ b/README.rst
@@ -1,5 +1,5 @@
 .. image:: docs/images/libE_logo.png
-   :scale: 90
+   :scale: 10
    :align: center
    :alt: libEnsemble
 

From 29763f5063cd8fa1965200ea46efaecd0fdf1b74 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 4 Oct 2019 14:12:01 -0500
Subject: [PATCH 330/644] Doesn't seem to work

---
 README.rst | 1 -
 1 file changed, 1 deletion(-)

diff --git a/README.rst b/README.rst
index fc29af6e0..8618d9eaa 100644
--- a/README.rst
+++ b/README.rst
@@ -1,5 +1,4 @@
 .. image:: docs/images/libE_logo.png
-   :scale: 10
    :align: center
    :alt: libEnsemble
 

From a47d1dc96c00f588b5fb8f6255b14a24c822966f Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 4 Oct 2019 14:28:27 -0500
Subject: [PATCH 331/644] flake8

---
 libensemble/libE_fields.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/libE_fields.py b/libensemble/libE_fields.py
index 00176bcce..32f23eba0 100644
--- a/libensemble/libE_fields.py
+++ b/libensemble/libE_fields.py
@@ -6,6 +6,6 @@
                ('gen_time', float),    # Time (since epoch) entry was entered into H
                ('given', bool),        # True if entry has been given for sim eval
                ('returned', bool),     # True if entry has been returned from sim eval
-               ('given_time', float),  # Time (since epoch) that the entry was given 
+               ('given_time', float),  # Time (since epoch) that the entry was given
                ('sim_worker', int),    # Worker that did (or is doing) the sim eval
                ]

From e5c4add0d8e0b0aaf1f9414db59c36cde2b88937 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 4 Oct 2019 20:28:10 -0500
Subject: [PATCH 332/644] Making pdf crossrefs texttt

---
 docs/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index 3440c1048..f742f4460 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -174,7 +174,7 @@ def __getattr__(cls, name):
     'extraclassoptions': 'openany',
     'preamble':
     r'''
-
+    \protected\def\sphinxcrossref#1{\texttt{#1}}
                 ''',
     # The paper size ('letterpaper' or 'a4paper').
     #

From 29eabfe45e8242021b3d9f04195a60f024d77fbe Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 8 Oct 2019 11:15:09 -0500
Subject: [PATCH 333/644] Changing default alloc func to only give
 gen_specs['in'] if it's a field with length

---
 libensemble/alloc_funcs/give_sim_work_first.py               | 5 ++++-
 .../tests/regression_tests/test_1d_uniform_sampling.py       | 1 -
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/libensemble/alloc_funcs/give_sim_work_first.py b/libensemble/alloc_funcs/give_sim_work_first.py
index f52118972..6b2f9d78b 100644
--- a/libensemble/alloc_funcs/give_sim_work_first.py
+++ b/libensemble/alloc_funcs/give_sim_work_first.py
@@ -78,6 +78,9 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
 
             # Give gen work
             gen_count += 1
-            gen_work(Work, i, gen_specs['in'], range(len(H)), persis_info[i])
+            if 'in' in gen_specs and len(gen_specs['in']):
+                gen_work(Work, i, gen_specs['in'], range(len(H)), persis_info[i])
+            else:
+                gen_work(Work, i, [], [], persis_info[i])
 
     return Work, persis_info
diff --git a/libensemble/tests/regression_tests/test_1d_uniform_sampling.py b/libensemble/tests/regression_tests/test_1d_uniform_sampling.py
index 131d9cd5a..2ce48ab30 100644
--- a/libensemble/tests/regression_tests/test_1d_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_1d_uniform_sampling.py
@@ -26,7 +26,6 @@
 sim_specs = {'sim_f': sim_f, 'in': ['x'], 'out': [('f', float)]}
 
 gen_specs = {'gen_f': gen_f,
-             'in': ['sim_id'],
              'out': [('x', float, (1,))],
              'lb': np.array([-3]),
              'ub': np.array([3]),

From 1d54948abb1b960a44f27ee0802038196277fe55 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 8 Oct 2019 11:35:28 -0500
Subject: [PATCH 334/644] removes gen_specs['in']

---
 examples/tutorials/tutorial_calling.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/examples/tutorials/tutorial_calling.py b/examples/tutorials/tutorial_calling.py
index 83ae83efb..8db2e8609 100644
--- a/examples/tutorials/tutorial_calling.py
+++ b/examples/tutorials/tutorial_calling.py
@@ -8,7 +8,6 @@
 libE_specs = {'nprocesses': nworkers, 'comms': 'local'}
 
 gen_specs = {'gen_f': gen_random_sample,        # Our generator function
-             'in': ['sim_id'],                  # Input field names. 'sim_id' necessary default
              'out': [('x', float, (1,))],       # gen_f output (name, type, size).
              'lower': np.array([-3]),           # lower boundary for random sampling.
              'upper': np.array([3]),            # upper boundary for random sampling.

From b062156b071a02fcf40e78f2059408423483159c Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 8 Oct 2019 11:36:36 -0500
Subject: [PATCH 335/644] also removes from mpi version

---
 examples/tutorials/tutorial_calling_mpi.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/examples/tutorials/tutorial_calling_mpi.py b/examples/tutorials/tutorial_calling_mpi.py
index 84a00fe31..2ba751353 100644
--- a/examples/tutorials/tutorial_calling_mpi.py
+++ b/examples/tutorials/tutorial_calling_mpi.py
@@ -12,7 +12,6 @@
 is_master = (MPI.COMM_WORLD.Get_rank() == 0)    # master process has MPI rank 0
 
 gen_specs = {'gen_f': gen_random_sample,        # Our generator function
-             'in': ['sim_id'],                  # Input field names. 'sim_id' necessary default
              'out': [('x', float, (1,))],       # gen_f output (name, type, size).
              'lower': np.array([-3]),           # lower boundary for random sampling.
              'upper': np.array([3]),            # upper boundary for random sampling.

From c27d72b5a07eba93aa322599051413e8e422e2b6 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 8 Oct 2019 11:44:00 -0500
Subject: [PATCH 336/644] update tutorial, touch-up formatting

---
 docs/tutorials/local_sine_tutorial.rst | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/docs/tutorials/local_sine_tutorial.rst b/docs/tutorials/local_sine_tutorial.rst
index 1f0b46d62..f1739fe16 100644
--- a/docs/tutorials/local_sine_tutorial.rst
+++ b/docs/tutorials/local_sine_tutorial.rst
@@ -74,7 +74,7 @@ An available libEnsemble worker will call this generator function with the follo
 
 Later on, we'll populate ``gen_specs`` and ``persis_info`` in our calling script.
 
-For now, create a new Python file named 'generator.py'. Write the following:
+For now, create a new Python file named ``generator.py``. Write the following:
 
 .. code-block:: python
     :linenos:
@@ -117,7 +117,7 @@ functions perform calculations based on values from the generator function.
 The only new parameter here is :ref:`sim_specs<datastruct-sim-specs>`, which serves
 a similar purpose to ``gen_specs``.
 
-Create a new Python file named 'simulator.py'. Write the following:
+Create a new Python file named ``simulator.py``. Write the following:
 
 .. code-block:: python
     :linenos:
@@ -148,13 +148,13 @@ Calling Script
 Now we can write the calling script that configures our generator and simulator
 functions and calls libEnsemble.
 
-Create an empty Python file named 'calling_script.py'.
+Create an empty Python file named ``calling_script.py``.
 In this file, we'll start by importing NumPy, libEnsemble, and the generator and
 simulator functions we just created.
 
 Next, in a dictionary called :ref:`libE_specs<datastruct-libe-specs>` we'll specify
 the number of workers and the type of manager/worker communication libEnsemble will
-use. Our communication method, 'local', refers to Python's Multiprocessing.
+use. Our communication method, ``'local'``, refers to Python's Multiprocessing.
 
 .. code-block:: python
     :linenos:
@@ -177,7 +177,6 @@ inputs and outputs from those functions to expect.
     :linenos:
 
     gen_specs = {'gen_f': gen_random_sample,      # Our generator function
-                 'in': ['sim_id'],                  # Input field names. 'sim_id' necessary default
                  'out': [('x', float, (1,))],       # gen_f output (name, type, size).
                  'lower': np.array([-3]),           # lower boundary for random sampling.
                  'upper': np.array([3]),            # upper boundary for random sampling.
@@ -242,8 +241,8 @@ In this arrangement, our output values are listed on the far-left with the gener
 values being the fourth column from the right.
 
 Two additional log files should also have been created.
-'ensemble.log' contains debugging or informational logging output from libEnsemble,
-while 'libE_stats.txt' contains a quick summary of all calculations performed.
+``ensemble.log`` contains debugging or informational logging output from libEnsemble,
+while ``libE_stats.txt`` contains a quick summary of all calculations performed.
 
 I graphed my output using Matplotlib, coloring entries by which worker performed
 the simulation:

From c198ac49d296fb95d94f7f11f31342334ce9ab56 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 11 Oct 2019 14:38:58 -0500
Subject: [PATCH 337/644] Trying to split pdf and html orders

---
 docs/index.rst | 71 ++++++++++++++++++++++++++++++++------------------
 1 file changed, 46 insertions(+), 25 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index 6b81824f4..8a624bfca 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -36,42 +36,63 @@ libEnsemble is a library for managing ensemble-like collections of computations.
 * Go in-depth by reading the :doc:`User Guide<user_guide>`.
 * Check the :doc:`FAQ<FAQ>` for common questions and answers, errors and resolutions.
 
+.. only:: (latex or latexpdf)
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Getting Started:
+  .. toctree::
+     :maxdepth: 2
 
-   Quickstart<quickstart>
-   contributing
-   release_notes
-   FAQ
+     Quickstart<quickstart>
+     user_guide
+     tutorials/local_sine_tutorial
+     contributing
+     FAQ
+     libE_module
+     data_structures/data_structures
+     user_funcs
+     job_controller/jc_index
+     logging
+     dev_guide/release_management/release_index.rst
+     dev_guide/dev_API/developer_API.rst
+     release_notes
 
 
-.. toctree::
-   :maxdepth: 1
-   :caption: Tutorials:
+.. only:: html
 
-   tutorials/local_sine_tutorial
+  .. toctree::
+     :maxdepth: 2
+     :caption: Getting Started:
 
+     Quickstart<quickstart>
+     contributing
+     release_notes
+     FAQ
 
-.. toctree::
-   :maxdepth: 2
-   :caption: User Guide:
 
-   user_guide
-   libE_module
-   data_structures/data_structures
-   user_funcs
-   job_controller/jc_index
-   logging
+  .. toctree::
+     :maxdepth: 1
+     :caption: Tutorials:
 
+     tutorials/local_sine_tutorial
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Developer Guide:
 
-   dev_guide/release_management/release_index.rst
-   dev_guide/dev_API/developer_API.rst
+  .. toctree::
+     :maxdepth: 2
+     :caption: User Guide:
+
+     user_guide
+     libE_module
+     data_structures/data_structures
+     user_funcs
+     job_controller/jc_index
+     logging
+
+
+  .. toctree::
+     :maxdepth: 2
+     :caption: Developer Guide:
+
+     dev_guide/release_management/release_index.rst
+     dev_guide/dev_API/developer_API.rst
 
 
 

From 5fc3eb77c93f4869808f9a4e87f54c08967de60b Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 11 Oct 2019 16:03:06 -0500
Subject: [PATCH 338/644] Adding code and test for LHS sampling

---
 libensemble/gen_funcs/uniform_sampling.py     | 42 +++++++++++++++++++
 libensemble/tests/regression_tests/.gitignore |  5 +++
 ...niform_sampling.py => test_1d_sampling.py} | 10 ++---
 .../test_chwirut_pounders_persistent.py       | 11 ++++-
 4 files changed, 61 insertions(+), 7 deletions(-)
 rename libensemble/tests/regression_tests/{test_1d_uniform_sampling.py => test_1d_sampling.py} (79%)

diff --git a/libensemble/gen_funcs/uniform_sampling.py b/libensemble/gen_funcs/uniform_sampling.py
index 162fa276f..30d521f11 100644
--- a/libensemble/gen_funcs/uniform_sampling.py
+++ b/libensemble/gen_funcs/uniform_sampling.py
@@ -88,3 +88,45 @@ def uniform_random_sample(H, persis_info, gen_specs, _):
     O['x'] = persis_info['rand_stream'].uniform(lb, ub, (b, n))
 
     return O, persis_info
+
+
+def latin_hypercube_sample(H, persis_info, gen_specs, _):
+    """
+    Generates ``gen_specs['gen_batch_size']`` in a Latin hypercube sample over
+    the domain defined by ``gen_specs['ub']`` and ``gen_specs['lb']``.
+    """
+
+    ub = gen_specs['ub']
+    lb = gen_specs['lb']
+
+    n = len(lb)
+    b = gen_specs['gen_batch_size']
+
+    O = np.zeros(b, dtype=gen_specs['out'])
+
+    A = lhs_sample(n, b)
+
+    O['x'] = A*(ub-lb)+lb
+
+    return O, persis_info
+
+
+def lhs_sample(n, k):
+
+    # Generate the intervals and random values
+    intervals = np.linspace(0, 1, k + 1)    
+    rand_source = np.random.uniform(0,1,(k, n))
+    rand_pts = np.zeros((k, n))
+    sample = np.zeros((k, n))
+    
+    # Add a point uniformly in each interval
+    a = intervals[:k]
+    b = intervals[1:]
+    for j in range(n):
+        rand_pts[:, j] = rand_source[:, j]*(b-a) + a
+    
+    # Randomly perturb
+    for j in range(n):
+        sample[:, j] = rand_pts[np.random.permutation(k), j]
+    
+    return sample
diff --git a/libensemble/tests/regression_tests/.gitignore b/libensemble/tests/regression_tests/.gitignore
index ea1472ec1..ef2668a41 100644
--- a/libensemble/tests/regression_tests/.gitignore
+++ b/libensemble/tests/regression_tests/.gitignore
@@ -1 +1,6 @@
 output/
+*.npy
+*.pickle
+ensemble.log
+libE_stats.txt
+
diff --git a/libensemble/tests/regression_tests/test_1d_uniform_sampling.py b/libensemble/tests/regression_tests/test_1d_sampling.py
similarity index 79%
rename from libensemble/tests/regression_tests/test_1d_uniform_sampling.py
rename to libensemble/tests/regression_tests/test_1d_sampling.py
index 2ce48ab30..438cf7993 100644
--- a/libensemble/tests/regression_tests/test_1d_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_1d_sampling.py
@@ -1,10 +1,10 @@
 # """
-# Runs libEnsemble with random sampling on a simple 1D problem
+# Runs libEnsemble with Latin hypercube sampling on a simple 1D problem
 #
 # Execute via one of the following commands (e.g. 3 workers):
-#    mpiexec -np 4 python3 test_1d_uniform_sampling.py
-#    python3 test_1d_uniform_sampling.py --nworkers 3 --comms local
-#    python3 test_1d_uniform_sampling.py --nworkers 3 --comms tcp
+#    mpiexec -np 4 python3 test_1d_sampling.py
+#    python3 test_1d_sampling.py --nworkers 3 --comms local
+#    python3 test_1d_sampling.py --nworkers 3 --comms tcp
 #
 # The number of concurrent evaluations of the objective function will be 4-1=3.
 # """
@@ -18,7 +18,7 @@
 # Import libEnsemble items for this test
 from libensemble.libE import libE
 from libensemble.sim_funcs.one_d_func import one_d_example as sim_f
-from libensemble.gen_funcs.uniform_sampling import uniform_random_sample as gen_f
+from libensemble.gen_funcs.uniform_sampling import latin_hypercube_sample as gen_f
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
index ca5ea9b5f..974e1ecdb 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
@@ -18,9 +18,10 @@
 
 # Import libEnsemble items for this test
 from libensemble.libE import libE
-from math import gamma, pi, sqrt
+from math import gamma, pi, sqrt, ceil
 from libensemble.sim_funcs.chwirut1 import chwirut_eval as sim_f
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
+from libensemble.gen_funcs.uniform_sampling import lhs_sample
 from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
 
@@ -54,7 +55,7 @@
              'gatol': 1e-6,
              'num_active_gens': 1,
              'dist_to_bound_multiple': 0.5,
-             'lhs_divisions': 5,
+             'lhs_divisions': 50,
              'components': m,
              'lb': (-2-np.pi/10)*np.ones(n),
              'ub': 2*np.ones(n)}
@@ -65,6 +66,12 @@
 
 exit_criteria = {'sim_max': 500}
 
+sample_points = np.zeros((0,n))
+for i in range(ceil(exit_criteria['sim_max']/gen_specs['lhs_divisions'])):
+    sample_points = np.append(sample_points,lhs_sample(n,gen_specs['lhs_divisions']),axis=0)
+
+gen_specs['sample_points'] = sample_points*(gen_specs['ub']-gen_specs['lb']) + gen_specs['lb']
+
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
                             alloc_specs, libE_specs)

From 381efcfafa3c8e28ef83806296888f06b72ebf96 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 11 Oct 2019 16:07:46 -0500
Subject: [PATCH 339/644] Renaming uniform_sampling to sampling as it can
 contain more methods than just uniform

---
 libensemble/gen_funcs/{uniform_sampling.py => sampling.py}      | 0
 libensemble/tests/regression_tests/script_test_balsam_hworld.py | 2 +-
 libensemble/tests/regression_tests/test_1d_sampling.py          | 2 +-
 .../regression_tests/test_1d_uniform_sampling_with_comm_dup.py  | 2 +-
 .../regression_tests/test_6-hump_camel_elapsed_time_abort.py    | 2 +-
 .../regression_tests/test_6-hump_camel_uniform_sampling.py      | 2 +-
 .../test_6-hump_camel_with_different_nodes_uniform_sample.py    | 2 +-
 libensemble/tests/regression_tests/test_calc_exception.py       | 2 +-
 .../tests/regression_tests/test_chwirut_pounders_persistent.py  | 2 +-
 .../test_chwirut_uniform_sampling_one_residual_at_a_time.py     | 2 +-
 libensemble/tests/regression_tests/test_comms.py                | 2 +-
 libensemble/tests/regression_tests/test_fast_alloc.py           | 2 +-
 libensemble/tests/regression_tests/test_jobcontroller_hworld.py | 2 +-
 libensemble/tests/regression_tests/test_worker_exceptions.py    | 2 +-
 libensemble/tests/scaling_tests/forces/run_libe_forces.py       | 2 +-
 15 files changed, 14 insertions(+), 14 deletions(-)
 rename libensemble/gen_funcs/{uniform_sampling.py => sampling.py} (100%)

diff --git a/libensemble/gen_funcs/uniform_sampling.py b/libensemble/gen_funcs/sampling.py
similarity index 100%
rename from libensemble/gen_funcs/uniform_sampling.py
rename to libensemble/gen_funcs/sampling.py
diff --git a/libensemble/tests/regression_tests/script_test_balsam_hworld.py b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
index ee6cc5609..4260b98e5 100644
--- a/libensemble/tests/regression_tests/script_test_balsam_hworld.py
+++ b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
@@ -10,7 +10,7 @@
 from libensemble.message_numbers import WORKER_DONE, WORKER_KILL_ON_ERR, WORKER_KILL_ON_TIMEOUT, JOB_FAILED
 from libensemble.libE import libE
 from libensemble.sim_funcs.job_control_hworld import job_control_hworld as sim_f
-from libensemble.gen_funcs.uniform_sampling import uniform_random_sample as gen_f
+from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
 from libensemble.tests.regression_tests.common import per_worker_stream
 
 mpi4py.rc.recv_mprobe = False  # Disable matching probes
diff --git a/libensemble/tests/regression_tests/test_1d_sampling.py b/libensemble/tests/regression_tests/test_1d_sampling.py
index 438cf7993..5e7990f02 100644
--- a/libensemble/tests/regression_tests/test_1d_sampling.py
+++ b/libensemble/tests/regression_tests/test_1d_sampling.py
@@ -18,7 +18,7 @@
 # Import libEnsemble items for this test
 from libensemble.libE import libE
 from libensemble.sim_funcs.one_d_func import one_d_example as sim_f
-from libensemble.gen_funcs.uniform_sampling import latin_hypercube_sample as gen_f
+from libensemble.gen_funcs.sampling import latin_hypercube_sample as gen_f
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py b/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
index 9be7ba91f..089b2d44c 100644
--- a/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
+++ b/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
@@ -22,7 +22,7 @@
 # Import libEnsemble items for this test
 from libensemble.libE import libE
 from libensemble.sim_funcs.one_d_func import one_d_example as sim_f
-from libensemble.gen_funcs.uniform_sampling import uniform_random_sample as gen_f
+from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py b/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
index 3dca719df..1e3cb393b 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
@@ -19,7 +19,7 @@
 # Import libEnsemble items for this test
 from libensemble.libE import libE
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
-from libensemble.gen_funcs.uniform_sampling import uniform_random_sample as gen_f
+from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream, eprint
 
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
index ce5603e74..53121d511 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
@@ -19,7 +19,7 @@
 # Import libEnsemble items for this test
 from libensemble.libE import libE
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
-from libensemble.gen_funcs.uniform_sampling import uniform_random_sample as gen_f
+from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py b/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
index 72cc2d065..ac319ea8a 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
@@ -20,7 +20,7 @@
 # Import libEnsemble items for this test
 from libensemble.libE import libE
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel_with_different_ranks_and_nodes as sim_f
-from libensemble.gen_funcs.uniform_sampling import uniform_random_sample_with_different_nodes_and_ranks as gen_f
+from libensemble.gen_funcs.sampling import uniform_random_sample_with_different_nodes_and_ranks as gen_f
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_calc_exception.py b/libensemble/tests/regression_tests/test_calc_exception.py
index 74ba6c575..604779a63 100644
--- a/libensemble/tests/regression_tests/test_calc_exception.py
+++ b/libensemble/tests/regression_tests/test_calc_exception.py
@@ -17,7 +17,7 @@
 
 from libensemble.libE import libE
 from libensemble.libE_manager import ManagerException
-from libensemble.gen_funcs.uniform_sampling import uniform_random_sample as gen_f
+from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
 from libensemble.tests.regression_tests.common import parse_args, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
index 974e1ecdb..7443d5bf9 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
@@ -21,7 +21,7 @@
 from math import gamma, pi, sqrt, ceil
 from libensemble.sim_funcs.chwirut1 import chwirut_eval as sim_f
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
-from libensemble.gen_funcs.uniform_sampling import lhs_sample
+from libensemble.gen_funcs.sampling import lhs_sample
 from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
index 17f561389..7cdd9548c 100644
--- a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
+++ b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
@@ -24,7 +24,7 @@
 # Import libEnsemble items
 from libensemble.libE import libE
 from libensemble.sim_funcs.chwirut1 import chwirut_eval as sim_f
-from libensemble.gen_funcs.uniform_sampling import uniform_random_sample_obj_components as gen_f
+from libensemble.gen_funcs.sampling import uniform_random_sample_obj_components as gen_f
 from libensemble.alloc_funcs.fast_alloc_and_pausing import give_sim_work_first as alloc_f
 from libensemble.tests.regression_tests.support import persis_info_3 as persis_info
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
diff --git a/libensemble/tests/regression_tests/test_comms.py b/libensemble/tests/regression_tests/test_comms.py
index 41404fc8c..d719fc6fe 100644
--- a/libensemble/tests/regression_tests/test_comms.py
+++ b/libensemble/tests/regression_tests/test_comms.py
@@ -19,7 +19,7 @@
 # Import libEnsemble items for this test
 from libensemble.libE import libE
 from libensemble.sim_funcs.comms_testing import float_x1000 as sim_f
-from libensemble.gen_funcs.uniform_sampling import uniform_random_sample as gen_f
+from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
 from libensemble.mpi_controller import MPIJobController  # Only used to get workerID in float_x1000
 jobctrl = MPIJobController(auto_resources=False)
diff --git a/libensemble/tests/regression_tests/test_fast_alloc.py b/libensemble/tests/regression_tests/test_fast_alloc.py
index 67a4f7742..1741232c7 100644
--- a/libensemble/tests/regression_tests/test_fast_alloc.py
+++ b/libensemble/tests/regression_tests/test_fast_alloc.py
@@ -19,7 +19,7 @@
 # Import libEnsemble items for this test
 from libensemble.libE import libE
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel_simple as sim_f
-from libensemble.gen_funcs.uniform_sampling import uniform_random_sample as gen_f
+from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
 from libensemble.alloc_funcs.fast_alloc import give_sim_work_first as alloc_f
 from libensemble.tests.regression_tests.common import parse_args, per_worker_stream
 
diff --git a/libensemble/tests/regression_tests/test_jobcontroller_hworld.py b/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
index 2dca7fbf2..14237f09b 100644
--- a/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
+++ b/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
@@ -20,7 +20,7 @@
 from libensemble.message_numbers import WORKER_DONE, WORKER_KILL_ON_ERR, WORKER_KILL_ON_TIMEOUT, JOB_FAILED
 from libensemble.libE import libE
 from libensemble.sim_funcs.job_control_hworld import job_control_hworld as sim_f
-from libensemble.gen_funcs.uniform_sampling import uniform_random_sample as gen_f
+from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
 from libensemble.tests.regression_tests.common import build_simfunc, parse_args, per_worker_stream
 
 # Do not change these lines - they are parsed by run-tests.sh
diff --git a/libensemble/tests/regression_tests/test_worker_exceptions.py b/libensemble/tests/regression_tests/test_worker_exceptions.py
index 1229ff228..4ba4ab3be 100644
--- a/libensemble/tests/regression_tests/test_worker_exceptions.py
+++ b/libensemble/tests/regression_tests/test_worker_exceptions.py
@@ -17,7 +17,7 @@
 
 from libensemble.libE import libE
 from libensemble.tests.regression_tests.support import nan_func as sim_f
-from libensemble.gen_funcs.uniform_sampling import uniform_random_sample as gen_f
+from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
 from libensemble.libE_manager import ManagerException
 from libensemble.tests.regression_tests.common import parse_args, per_worker_stream
 
diff --git a/libensemble/tests/scaling_tests/forces/run_libe_forces.py b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
index fdf30dd71..f19c8506e 100644
--- a/libensemble/tests/scaling_tests/forces/run_libe_forces.py
+++ b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
@@ -6,7 +6,7 @@
 
 # Import libEnsemble modules
 from libensemble.libE import libE
-from libensemble.gen_funcs.uniform_sampling import uniform_random_sample
+from libensemble.gen_funcs.sampling import uniform_random_sample
 
 from libensemble import libE_logger
 libE_logger.set_level('INFO')

From a245c14a7156e4d9fd2f15fb2651ac031dd3c45c Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 11 Oct 2019 16:23:26 -0500
Subject: [PATCH 340/644] flayk ate

---
 libensemble/gen_funcs/sampling.py                      | 10 +++++-----
 .../test_chwirut_pounders_persistent.py                |  4 ++--
 .../tests/standalone_tests/kill_test/log.autotest.txt  | 10 +++++-----
 3 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/libensemble/gen_funcs/sampling.py b/libensemble/gen_funcs/sampling.py
index 30d521f11..74431fc94 100644
--- a/libensemble/gen_funcs/sampling.py
+++ b/libensemble/gen_funcs/sampling.py
@@ -114,19 +114,19 @@ def latin_hypercube_sample(H, persis_info, gen_specs, _):
 def lhs_sample(n, k):
 
     # Generate the intervals and random values
-    intervals = np.linspace(0, 1, k + 1)    
-    rand_source = np.random.uniform(0,1,(k, n))
+    intervals = np.linspace(0, 1, k+1)
+    rand_source = np.random.uniform(0, 1, (k, n))
     rand_pts = np.zeros((k, n))
     sample = np.zeros((k, n))
-    
+
     # Add a point uniformly in each interval
     a = intervals[:k]
     b = intervals[1:]
     for j in range(n):
         rand_pts[:, j] = rand_source[:, j]*(b-a) + a
-    
+
     # Randomly perturb
     for j in range(n):
         sample[:, j] = rand_pts[np.random.permutation(k), j]
-    
+
     return sample
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
index 7443d5bf9..f1fbcb913 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
@@ -66,9 +66,9 @@
 
 exit_criteria = {'sim_max': 500}
 
-sample_points = np.zeros((0,n))
+sample_points = np.zeros((0, n))
 for i in range(ceil(exit_criteria['sim_max']/gen_specs['lhs_divisions'])):
-    sample_points = np.append(sample_points,lhs_sample(n,gen_specs['lhs_divisions']),axis=0)
+    sample_points = np.append(sample_points, lhs_sample(n, gen_specs['lhs_divisions']), axis=0)
 
 gen_specs['sample_points'] = sample_points*(gen_specs['ub']-gen_specs['lb']) + gen_specs['lb']
 
diff --git a/libensemble/tests/standalone_tests/kill_test/log.autotest.txt b/libensemble/tests/standalone_tests/kill_test/log.autotest.txt
index 1f0682ad8..baeb7d0ab 100644
--- a/libensemble/tests/standalone_tests/kill_test/log.autotest.txt
+++ b/libensemble/tests/standalone_tests/kill_test/log.autotest.txt
@@ -55,7 +55,7 @@ Bebop (intelmpi)::
 
     kill 1: Fails
     kill 2: Works
-    
+
     [*Update 2019: kill 1 seems to also work if use srun instead of mpirun]
 
 Cooley (intelmpi)::
@@ -94,14 +94,14 @@ Theta (intelmpi)::
 
     Alternative - may be to use apkill. This may work without unloading xalt - not tried.
 
-    
+
 Cori (intelmpi - launched with srun)::
 
-    Single node on 4 processes:   
-    
+    Single node on 4 processes:
+
     kill 1: Works
     kill 2: Works
-    
+
     Two nodes with 2 processes each:
 
     kill 1: Works

From c7aff91caf02f3b62724848fc226db57a45dc151 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 14 Oct 2019 12:01:06 -0500
Subject: [PATCH 341/644] update symlink

---
 examples/gen_funcs/sampling.py         | 1 +
 examples/gen_funcs/uniform_sampling.py | 1 -
 2 files changed, 1 insertion(+), 1 deletion(-)
 create mode 120000 examples/gen_funcs/sampling.py
 delete mode 120000 examples/gen_funcs/uniform_sampling.py

diff --git a/examples/gen_funcs/sampling.py b/examples/gen_funcs/sampling.py
new file mode 120000
index 000000000..7733bb711
--- /dev/null
+++ b/examples/gen_funcs/sampling.py
@@ -0,0 +1 @@
+../../libensemble/gen_funcs/sampling.py
\ No newline at end of file
diff --git a/examples/gen_funcs/uniform_sampling.py b/examples/gen_funcs/uniform_sampling.py
deleted file mode 120000
index 29ae9b98c..000000000
--- a/examples/gen_funcs/uniform_sampling.py
+++ /dev/null
@@ -1 +0,0 @@
-../../libensemble/gen_funcs/uniform_sampling.py
\ No newline at end of file

From 223cfa8e24f161511f3b3a0007b43e644a74adc4 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 15 Oct 2019 14:33:38 -0500
Subject: [PATCH 342/644] Removing whitespace

---
 docs/data_structures/work_dict.rst     | 2 +-
 docs/tutorials/local_sine_tutorial.rst | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/data_structures/work_dict.rst b/docs/data_structures/work_dict.rst
index 4dd50482c..852156dd8 100644
--- a/docs/data_structures/work_dict.rst
+++ b/docs/data_structures/work_dict.rst
@@ -17,7 +17,7 @@ Dictionary with integer keys ``i`` and dictionary values to be given to worker `
 
         Available keys are:
         'H_rows' [list of ints]: History rows to send to worker 'i'
-        'blocking' [list of ints]: Workers to be blocked by this calculation 
+        'blocking' [list of ints]: Workers to be blocked by this calculation
         'persistent' [bool]: True if worker 'i' will enter persistent mode
 
 
diff --git a/docs/tutorials/local_sine_tutorial.rst b/docs/tutorials/local_sine_tutorial.rst
index 54c8fccf5..0df9bf50e 100644
--- a/docs/tutorials/local_sine_tutorial.rst
+++ b/docs/tutorials/local_sine_tutorial.rst
@@ -188,7 +188,7 @@ inputs and outputs from those functions to expect.
                  'lower': np.array([-3]),      # lower boundary for random sampling
                  'upper': np.array([3]),       # upper boundary for random sampling
                  'gen_batch_size': 5}          # number of x's gen_f generates per call
-                                               
+
     sim_specs = {'sim_f': sim_find_sine,       # Our simulator function
                  'in': ['x'],                  # Input field names. 'x' from gen_f output
                  'out': [('y', float)]}        # sim_f output. 'y' = sine('x')
@@ -338,7 +338,7 @@ modify the bottom of the calling script like this:
 
     if is_master:
         # Some (optional) statements to visualize our History array
-        print([i for i in H.dtype.fields])  
+        print([i for i in H.dtype.fields])
         print(H)
 
         import matplotlib.pyplot as plt

From 7ce771743c0eb155e823bfed81c24930fd95c4b2 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 15 Oct 2019 16:40:25 -0500
Subject: [PATCH 343/644] Better rst tags and avoiding line numbers in includes

---
 README.rst                             | 2 +-
 docs/data_structures/history_array.rst | 2 +-
 docs/quickstart.rst                    | 2 +-
 docs/sim_gen_alloc_funcs.rst           | 4 ++--
 docs/tutorials/local_sine_tutorial.rst | 3 +--
 libensemble/message_numbers.py         | 4 ++--
 6 files changed, 8 insertions(+), 9 deletions(-)

diff --git a/README.rst b/README.rst
index 8618d9eaa..f4a4932b7 100644
--- a/README.rst
+++ b/README.rst
@@ -18,7 +18,7 @@
    :alt: Documentation Status
 
 |
-.. after_badges_tag
+.. after_badges_rst_tag
 
 ====================
 What is libEnsemble?
diff --git a/docs/data_structures/history_array.rst b/docs/data_structures/history_array.rst
index a097cd57b..017b7430d 100644
--- a/docs/data_structures/history_array.rst
+++ b/docs/data_structures/history_array.rst
@@ -17,7 +17,7 @@ Fields in ``H`` include those specified in ``sim_specs['out']``,
 Below are the protected fields used in ``H``
 
 ..  literalinclude:: ../../libensemble/libE_fields.py
-    :lines: 4-
+    :start-at: libE_fields
 
 :Examples:
 
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index 8d1e85bbf..240804990 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -20,4 +20,4 @@
   |
 
 .. include:: ../README.rst
-    :start-after: after_badges_tag
+    :start-after: after_badges_rst_tag
diff --git a/docs/sim_gen_alloc_funcs.rst b/docs/sim_gen_alloc_funcs.rst
index 7e56753ba..cfcaeba66 100644
--- a/docs/sim_gen_alloc_funcs.rst
+++ b/docs/sim_gen_alloc_funcs.rst
@@ -40,7 +40,7 @@ Returns:
   Used to tell manager why a persistent worker is stopping.
 
 ..  literalinclude:: ../libensemble/message_numbers.py
-    :lines: 1-8
+    :end-before: last_message_number_rst_tag
 
 .. _api_gen_f:
 
@@ -82,7 +82,7 @@ Returns:
   Used to tell manager why a persistent worker is stopping.
 
 ..  literalinclude:: ../libensemble/message_numbers.py
-    :lines: 1-8
+    :end-before: last_message_number_rst_tag
 
 .. _api_alloc_f:
 
diff --git a/docs/tutorials/local_sine_tutorial.rst b/docs/tutorials/local_sine_tutorial.rst
index 0df9bf50e..244906085 100644
--- a/docs/tutorials/local_sine_tutorial.rst
+++ b/docs/tutorials/local_sine_tutorial.rst
@@ -183,7 +183,6 @@ inputs and outputs from those functions to expect.
     :linenos:
 
     gen_specs = {'gen_f': gen_random_sample,   # Our generator function
-                 'in': ['sim_id'],             # Input field names. 'sim_id' necessary default
                  'out': [('x', float, (1,))],  # gen_f output (name, type, size)
                  'lower': np.array([-3]),      # lower boundary for random sampling
                  'upper': np.array([3]),       # upper boundary for random sampling
@@ -221,7 +220,7 @@ This :ref:`H<datastruct-history-array>` is the final version of the History arra
     H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
                                 libE_specs=libE_specs)
 
-    print([i for i in H.dtype.fields])        # Some (optional) statements to visualize our History array
+    print([i for i in H.dtype.fields])  # (optional) to visualize our History array
     print(H)
 
 That's it! Now that these files are complete, we can run our simulation.
diff --git a/libensemble/message_numbers.py b/libensemble/message_numbers.py
index fc664e822..d868fb9d4 100644
--- a/libensemble/message_numbers.py
+++ b/libensemble/message_numbers.py
@@ -1,13 +1,13 @@
 # --- Tags
 
-UNSET_TAG = 0  # sh temp - this is a libe feature that is to be reviewed for best solution
+UNSET_TAG = 0  # sh temp - this is a libE feature that is to be reviewed for best solution
 EVAL_SIM_TAG = 1
 EVAL_GEN_TAG = 2
 STOP_TAG = 3
 PERSIS_STOP = 4                     # manager tells persistent worker to desist
 FINISHED_PERSISTENT_SIM_TAG = 11    # tells manager sim_f done persistent mode
 FINISHED_PERSISTENT_GEN_TAG = 12    # tells manager gen_f done persistent mode
-# ABORT_ENSEMBLE = 13 # Worker asks manager to abort (and dump history)
+# last_message_number_rst_tag
 
 calc_type_strings = {
     EVAL_SIM_TAG: 'sim',

From 0b5310a63dcc1bcb538e3a51e043504712580698 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 15 Oct 2019 16:43:01 -0500
Subject: [PATCH 344/644] Whitespace removal

---
 README.rst                                             |  2 +-
 .../tests/standalone_tests/kill_test/log.autotest.txt  | 10 +++++-----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/README.rst b/README.rst
index f4a4932b7..36766cc9f 100644
--- a/README.rst
+++ b/README.rst
@@ -186,7 +186,7 @@ When specifying these options via command line options, one may use the
 ``libensemble/tests/regression_tests/common.py``
 
 
-See the 
+See the
 `user-guide <https://libensemble.readthedocs.io/en/latest/user_guide.html>`_
 for more information.
 
diff --git a/libensemble/tests/standalone_tests/kill_test/log.autotest.txt b/libensemble/tests/standalone_tests/kill_test/log.autotest.txt
index 1f0682ad8..baeb7d0ab 100644
--- a/libensemble/tests/standalone_tests/kill_test/log.autotest.txt
+++ b/libensemble/tests/standalone_tests/kill_test/log.autotest.txt
@@ -55,7 +55,7 @@ Bebop (intelmpi)::
 
     kill 1: Fails
     kill 2: Works
-    
+
     [*Update 2019: kill 1 seems to also work if use srun instead of mpirun]
 
 Cooley (intelmpi)::
@@ -94,14 +94,14 @@ Theta (intelmpi)::
 
     Alternative - may be to use apkill. This may work without unloading xalt - not tried.
 
-    
+
 Cori (intelmpi - launched with srun)::
 
-    Single node on 4 processes:   
-    
+    Single node on 4 processes:
+
     kill 1: Works
     kill 2: Works
-    
+
     Two nodes with 2 processes each:
 
     kill 1: Works

From 7425ba5e052fd61b9c25514685bcba5899587344 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 16 Oct 2019 08:33:50 -0500
Subject: [PATCH 345/644] Removing copy/paste text and editing source comments

---
 docs/data_structures/sim_specs.rst            | 33 ++++++-------------
 .../test_6-hump_camel_uniform_sampling.py     | 10 +++---
 .../scaling_tests/forces/run_libe_forces.py   | 29 ++++++++--------
 3 files changed, 31 insertions(+), 41 deletions(-)

diff --git a/docs/data_structures/sim_specs.rst b/docs/data_structures/sim_specs.rst
index 63a6396c1..c0e9c7077 100644
--- a/docs/data_structures/sim_specs.rst
+++ b/docs/data_structures/sim_specs.rst
@@ -44,35 +44,22 @@ Simulation function specifications to be set in user calling script and passed t
 
 .. _sim-specs-exmple1:
 
-From: ``libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py``::
+From: ``libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py``
+
+..  literalinclude:: ../../libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
+    :start-at: sim_specs
+    :end-before: end_sim_specs_rst_tag
 
-    sim_specs = {'sim_f': six_hump_camel, # This is the function whose output is being minimized
-                 'in': ['x'],             # These keys will be given to the above function
-                 'out': [('f',float)],    # This is the output from the function being minimized
-                 'save_every_k': 400
-                 }
 
 Note that the dimensions and type of the ``'in'`` field variable ``'x'`` is specified by the corresponding
 generator ``'out'`` field ``'x'`` (see :ref:`gen_specs example<gen-specs-exmple1>`).
 Only the variable name is then required in sim_specs.
 
-From: ``libensemble/tests/scaling_tests/forces/run_libe_forces.py``::
-
-    sim_specs = {'sim_f': run_forces,             # This is the function whose output is being minimized (sim func)
-                 'in': ['x'],                     # Name of input data structure for sim func
-                 'out': [('energy', float)],      # Output from sim func
-                 'keys': ['seed'],                # Key/keys for input data
-                 'sim_dir': './sim',              # Simulation input dir to be copied for each worker (*currently empty)
-                 'sim_dir_suffix': 'test',        # Suffix for copied sim dirs to indentify run (in case multiple)
-                 'simdir_basename': 'forces',     # User attribute to name sim directories (forces_***)
-                 'cores': 2,                      # User attribute to set number of cores for sim func runs (optional)
-                 'sim_particles': 1e3,            # User attribute for number of particles in simulations
-                 'sim_timesteps': 5,              # User attribute for number of timesteps in simulations
-                 'sim_kill_minutes': 10.0,        # User attribute for max time for simulations
-                 'kill_rate': 0.5,                # Between 0 and 1 for proportion of jobs that go bad (for testing kills)
-                 'particle_variance': 0.2,        # Range over which particle count varies (for testing load imbalance)
-                 'profile': False
-                 }
+From: ``libensemble/tests/scaling_tests/forces/run_libe_forces.py``
+
+..  literalinclude:: ../../libensemble/tests/scaling_tests/forces/run_libe_forces.py
+    :start-at: sim_f
+    :end-before: end_sim_specs_rst_tag
 
 This example uses a number of user specific fields, that will be dealt with in the corresponding sim f, which
 can be found at ``libensemble/tests/scaling_tests/forces/forces_simf.py``
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
index ce5603e74..5c062698a 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
@@ -25,10 +25,12 @@
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
-sim_specs = {'sim_f': sim_f,
-             'in': ['x'],
-             'out': [('f', float)],
-             'save_every_k': 400}
+sim_specs = {'sim_f': sim_f,         # Function whose output is being minimized  
+             'in': ['x'],            # Keys to be given to the above function
+             'out': [('f', float)],  # Output from the function being minimized
+             'save_every_k': 400,    # Want progress saved every 400 evals
+             }                       
+# end_sim_specs_rst_tag
 
 gen_specs = {'gen_f': gen_f,
              'in': ['sim_id'],
diff --git a/libensemble/tests/scaling_tests/forces/run_libe_forces.py b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
index fdf30dd71..cd3e68559 100644
--- a/libensemble/tests/scaling_tests/forces/run_libe_forces.py
+++ b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
@@ -66,21 +66,22 @@
 # Note: Attributes such as kill_rate are to control forces tests, this would not be a typical parameter.
 
 # State the objective function, its arguments, output, and necessary parameters (and their sizes)
-sim_specs = {'sim_f': run_forces,             # This is the function whose output is being minimized (sim func)
-             'in': ['x'],                     # Name of input data structure for sim func
-             'out': [('energy', float)],      # Output from sim func
-             'keys': ['seed'],                # Key/keys for input data
-             'sim_dir': './sim',              # Simulation input dir to be copied for each worker (*currently empty)
-             'sim_dir_suffix': 'test',        # Suffix for copied sim dirs to indentify run (in case multiple)
-             'simdir_basename': 'forces',     # User attribute to name sim directories (forces_***)
-             'cores': 2,                      # User attribute to set number of cores for sim func runs (optional)
-             'sim_particles': 1e3,            # User attribute for number of particles in simulations
-             'sim_timesteps': 5,              # User attribute for number of timesteps in simulations
-             'sim_kill_minutes': 10.0,        # User attribute for max time for simulations
-             'kill_rate': 0.5,                # Between 0 and 1 for proportion of jobs that go bad (for testing kills)
-             'particle_variance': 0.2,        # Range over which particle count varies (for testing load imbalance)
-             'profile': False
+sim_specs = {'sim_f': run_forces,         # Function whose output is being minimized
+             'in': ['x'],                 # Name of input data structure for sim func
+             'out': [('energy', float)],  # Output from sim func
+             'keys': ['seed'],            # Key/keys for input data
+             'sim_dir': './sim',          # Sim dir to be copied for each worker 
+             'sim_dir_suffix': 'test',    # Suffix for copied sim dirs (to ID run)
+             'profile': False,            # Don't have libE profile run
+             'simdir_basename': 'force',  # Used by sim_f to name sim directories 
+             'cores': 2,                  # Used by sim_f to set number of cores used
+             'sim_particles': 1e3,        # Used by sim_f for number of particles 
+             'sim_timesteps': 5,          # Used by sim_f for number of timesteps 
+             'sim_kill_minutes': 10.0,    # Used by sim_f to set max run time
+             'particle_variance': 0.2,    # Used by sim_f to vary load imbalance
+             'kill_rate': 0.5,            # Fraction of bad sim_f evals (tests kills)
              }
+# end_sim_specs_rst_tag
 
 # State the generating function, its arguments, output, and necessary parameters.
 gen_specs = {'gen_f': uniform_random_sample,  # Generator function

From fbc1d5ff5fd2fc08a8f6161c1fc01e473678aa3c Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 16 Oct 2019 08:47:03 -0500
Subject: [PATCH 346/644] Removing copy/paste and editing source comments

---
 docs/data_structures/persis_info.rst          |  9 ++++-----
 libensemble/tests/regression_tests/support.py | 19 ++++++++++---------
 2 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/docs/data_structures/persis_info.rst b/docs/data_structures/persis_info.rst
index 3f1a6e6ce..a051e95d2 100644
--- a/docs/data_structures/persis_info.rst
+++ b/docs/data_structures/persis_info.rst
@@ -17,10 +17,9 @@ from the allocation function.
 
 :Examples:
 
-From: libEnsemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MAA.py::
+From: ``libEnsemble/tests/regression_tests/support.py``
 
-    persis_info = {'next_to_give':0} # used in alloc_funcs/fast_alloc_to_aposmm.py to store the next entry in H to give
-    persis_info['total_gen_calls'] = 0 # used in alloc_funcs/fast_alloc_to_aposmm.py to count total gen calls
+..  literalinclude:: ../../libensemble/tests/regression_tests/support.py
+    :start-at: persis_info_1
+    :end-before: end_persis_info_rst_tag
 
-    for i in range(MPI.COMM_WORLD.Get_size()):
-        persis_info[i] = {'rand_stream': np.random.RandomState(i)} # used as a random number stream for each worker
diff --git a/libensemble/tests/regression_tests/support.py b/libensemble/tests/regression_tests/support.py
index 4cfc78500..23cf171bf 100644
--- a/libensemble/tests/regression_tests/support.py
+++ b/libensemble/tests/regression_tests/support.py
@@ -35,15 +35,16 @@ def nan_func(calc_in, persis_info, sim_specs, libE_info):
                    ('pt_id', int)]  # Identify the same point evaluated by different sim_f's or components
 
 # give_sim_work_first persis_info
-persis_info_1 = {}
-# Below persis_info fields store APOSMM information, but can be passed to various workers.
-persis_info_1['total_gen_calls'] = 0
-persis_info_1['last_worker'] = 0
-persis_info_1['next_to_give'] = 0
-persis_info_1[0] = {'run_order': {},
-                    'old_runs': {},
-                    'total_runs': 0,
-                    'rand_stream': np.random.RandomState(1)}
+persis_info_1 = {'total_gen_calls': 0,  # Counts gen calls in alloc_f
+                 'last_worker': 0,      # Remembers last gen worker in alloc_f
+                 'next_to_give': 0,     # Remembers next H row to give in alloc_f
+                }
+persis_info_1[0] = {'run_order': {},    # Used by manager to remember run order
+                    'old_runs': {},     # Used by manager to store old runs order
+                    'total_runs': 0,    # Used by manager to count total runs
+                    'rand_stream': np.random.RandomState(1)
+                   }
+# end_persis_info_rst_tag
 
 persis_info_2 = copy.deepcopy(persis_info_1)
 persis_info_2[1] = persis_info_2[0]

From 6f037143c6f19bbd3a65c85b47ba6a078978247e Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 16 Oct 2019 08:47:33 -0500
Subject: [PATCH 347/644] Whitespace

---
 docs/data_structures/persis_info.rst | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/data_structures/persis_info.rst b/docs/data_structures/persis_info.rst
index a051e95d2..87ff5ca7b 100644
--- a/docs/data_structures/persis_info.rst
+++ b/docs/data_structures/persis_info.rst
@@ -22,4 +22,3 @@ From: ``libEnsemble/tests/regression_tests/support.py``
 ..  literalinclude:: ../../libensemble/tests/regression_tests/support.py
     :start-at: persis_info_1
     :end-before: end_persis_info_rst_tag
-

From 3ee5cc9d6a003787ff8b4aa4ef1d6f5f02e41ea3 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 16 Oct 2019 08:55:39 -0500
Subject: [PATCH 348/644] Removing copy/paste and editing source comments

---
 docs/data_structures/gen_specs.rst                | 15 +++++----------
 .../test_6-hump_camel_uniform_sampling.py         | 15 ++++++++-------
 2 files changed, 13 insertions(+), 17 deletions(-)

diff --git a/docs/data_structures/gen_specs.rst b/docs/data_structures/gen_specs.rst
index 2a937f492..a90529afa 100644
--- a/docs/data_structures/gen_specs.rst
+++ b/docs/data_structures/gen_specs.rst
@@ -36,16 +36,11 @@ Generation function specifications to be set in user calling script and passed t
 
 .. _gen-specs-exmple1:
 
-From: libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py::
-
-    gen_specs = {'gen_f': uniform_random_sample,
-                 'in': ['sim_id'],
-                 'out': [('x',float,2)],
-                 'lb': np.array([-3,-2]),
-                 'ub': np.array([ 3, 2]),
-                 'gen_batch_size': 500,
-                 'save_every_k': 300
-                 }
+From: ``libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py``
+
+..  literalinclude:: ../../libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
+    :start-at: gen_specs
+    :end-before: end_gen_specs_rst_tag
 
 In this example, the generation function *uniform_random_sample* will generate 500 random points
 uniformly over the 2D domain defined by ``gen_specs['ub']`` and ``gen_specs['lb']``.
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
index 5c062698a..c7d15ff75 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
@@ -32,13 +32,14 @@
              }                       
 # end_sim_specs_rst_tag
 
-gen_specs = {'gen_f': gen_f,
-             'in': ['sim_id'],
-             'gen_batch_size': 500,
-             'save_every_k': 300,
-             'out': [('x', float, (2,))],
-             'lb': np.array([-3, -2]),
-             'ub': np.array([3, 2])}
+gen_specs = {'gen_f': gen_f,               # Tell libE function generating sim_f input
+             'out': [('x', float, (2,))],  # Tell libE gen_f output, type, size
+             'save_every_k': 300,          # Tell libE to save every 300 gen entries
+             'gen_batch_size': 500,        # Tell gen_f how much to generate per call 
+             'lb': np.array([-3, -2]),     # Tell gen_f lower bounds
+             'ub': np.array([3, 2]),       # Tell gen_f upper bounds
+             }
+# end_gen_specs_rst_tag   
 
 persis_info = per_worker_stream({}, nworkers + 1)
 

From 829e62b2a7c1252c19f726f387849e40bcbd447a Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 16 Oct 2019 08:56:59 -0500
Subject: [PATCH 349/644] Whitespace

---
 .../test_6-hump_camel_uniform_sampling.py                 | 8 ++++----
 libensemble/tests/scaling_tests/forces/run_libe_forces.py | 8 ++++----
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
index c7d15ff75..f26bad7b0 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
@@ -25,21 +25,21 @@
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
-sim_specs = {'sim_f': sim_f,         # Function whose output is being minimized  
+sim_specs = {'sim_f': sim_f,         # Function whose output is being minimized
              'in': ['x'],            # Keys to be given to the above function
              'out': [('f', float)],  # Output from the function being minimized
              'save_every_k': 400,    # Want progress saved every 400 evals
-             }                       
+             }
 # end_sim_specs_rst_tag
 
 gen_specs = {'gen_f': gen_f,               # Tell libE function generating sim_f input
              'out': [('x', float, (2,))],  # Tell libE gen_f output, type, size
              'save_every_k': 300,          # Tell libE to save every 300 gen entries
-             'gen_batch_size': 500,        # Tell gen_f how much to generate per call 
+             'gen_batch_size': 500,        # Tell gen_f how much to generate per call
              'lb': np.array([-3, -2]),     # Tell gen_f lower bounds
              'ub': np.array([3, 2]),       # Tell gen_f upper bounds
              }
-# end_gen_specs_rst_tag   
+# end_gen_specs_rst_tag
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
diff --git a/libensemble/tests/scaling_tests/forces/run_libe_forces.py b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
index cd3e68559..5f8b4cee6 100644
--- a/libensemble/tests/scaling_tests/forces/run_libe_forces.py
+++ b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
@@ -70,13 +70,13 @@
              'in': ['x'],                 # Name of input data structure for sim func
              'out': [('energy', float)],  # Output from sim func
              'keys': ['seed'],            # Key/keys for input data
-             'sim_dir': './sim',          # Sim dir to be copied for each worker 
+             'sim_dir': './sim',          # Sim dir to be copied for each worker
              'sim_dir_suffix': 'test',    # Suffix for copied sim dirs (to ID run)
              'profile': False,            # Don't have libE profile run
-             'simdir_basename': 'force',  # Used by sim_f to name sim directories 
+             'simdir_basename': 'force',  # Used by sim_f to name sim directories
              'cores': 2,                  # Used by sim_f to set number of cores used
-             'sim_particles': 1e3,        # Used by sim_f for number of particles 
-             'sim_timesteps': 5,          # Used by sim_f for number of timesteps 
+             'sim_particles': 1e3,        # Used by sim_f for number of particles
+             'sim_timesteps': 5,          # Used by sim_f for number of timesteps
              'sim_kill_minutes': 10.0,    # Used by sim_f to set max run time
              'particle_variance': 0.2,    # Used by sim_f to vary load imbalance
              'kill_rate': 0.5,            # Fraction of bad sim_f evals (tests kills)

From 82db49b8ca9c509f0535cda3160f31daf484857c Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 16 Oct 2019 13:36:50 -0500
Subject: [PATCH 350/644] Better, but open to discussion

---
 docs/conf.py                                  |  1 +
 docs/data_structures/sim_specs.rst            | 39 +++++++++----------
 docs/data_structures/work_dict.rst            | 18 ++++-----
 .../release_management/release_process.rst    |  6 +--
 libensemble/message_numbers.py                |  2 +-
 5 files changed, 31 insertions(+), 35 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index f742f4460..2359576ea 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -172,6 +172,7 @@ def __getattr__(cls, name):
     # Sonny, Lenny, or Bjornstrup
     'fncychap': '\\usepackage[Lenny]{fncychap}',
     'extraclassoptions': 'openany',
+    'sphinxsetup': 'admonitioncolor={RGB}{255,204,204}',
     'preamble':
     r'''
     \protected\def\sphinxcrossref#1{\texttt{#1}}
diff --git a/docs/data_structures/sim_specs.rst b/docs/data_structures/sim_specs.rst
index c0e9c7077..02fca0801 100644
--- a/docs/data_structures/sim_specs.rst
+++ b/docs/data_structures/sim_specs.rst
@@ -33,33 +33,32 @@ Simulation function specifications to be set in user calling script and passed t
 
         Additional entires in sim_specs will be given to sim_f
 
-:Notes:
+.. note::
+  * The user may define other fields to be passed to the simulator function.
+  * The tuples defined in the ``'out'`` list are entered into the master :ref:`history array<datastruct-history-array>`
+  * The ``sim_dir_prefix`` option may be used to create simulation working directories in node local/scratch storage when workers are distributed. This may have a performance benefit with I/O heavy sim funcs.
 
-* The user may define other fields to be passed to the simulator function.
-* The tuples defined in the ``'out'`` list are entered into the master :ref:`history array<datastruct-history-array>`
-* The ``sim_dir_prefix`` option may be used to create simulation working directories in node local/scratch storage when workers are distributed. This may have a performance benefit with I/O heavy sim funcs.
 
+.. seealso::
 
-:Examples:
+  .. _sim-specs-exmple1:
 
-.. _sim-specs-exmple1:
+  From: ``libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py``
 
-From: ``libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py``
+  ..  literalinclude:: ../../libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
+      :start-at: sim_specs
+      :end-before: end_sim_specs_rst_tag
 
-..  literalinclude:: ../../libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
-    :start-at: sim_specs
-    :end-before: end_sim_specs_rst_tag
 
+  The dimensions and type of the ``'in'`` field variable ``'x'`` is specified by the corresponding
+  generator ``'out'`` field ``'x'`` (see :ref:`gen_specs example<gen-specs-exmple1>`).
+  Only the variable name is then required in ``sim_specs['in']``.
 
-Note that the dimensions and type of the ``'in'`` field variable ``'x'`` is specified by the corresponding
-generator ``'out'`` field ``'x'`` (see :ref:`gen_specs example<gen-specs-exmple1>`).
-Only the variable name is then required in sim_specs.
+  From: ``libensemble/tests/scaling_tests/forces/run_libe_forces.py``
 
-From: ``libensemble/tests/scaling_tests/forces/run_libe_forces.py``
+  ..  literalinclude:: ../../libensemble/tests/scaling_tests/forces/run_libe_forces.py
+      :start-at: sim_f
+      :end-before: end_sim_specs_rst_tag
 
-..  literalinclude:: ../../libensemble/tests/scaling_tests/forces/run_libe_forces.py
-    :start-at: sim_f
-    :end-before: end_sim_specs_rst_tag
-
-This example uses a number of user specific fields, that will be dealt with in the corresponding sim f, which
-can be found at ``libensemble/tests/scaling_tests/forces/forces_simf.py``
+  This example uses a number of user specific fields, that will be dealt with in the corresponding sim f, which
+  can be found at ``libensemble/tests/scaling_tests/forces/forces_simf.py``
diff --git a/docs/data_structures/work_dict.rst b/docs/data_structures/work_dict.rst
index 852156dd8..1a75d9743 100644
--- a/docs/data_structures/work_dict.rst
+++ b/docs/data_structures/work_dict.rst
@@ -15,20 +15,16 @@ Dictionary with integer keys ``i`` and dictionary values to be given to worker `
         'tag' [int]: 'EVAL_SIM_TAG'/'EVAL_GEN_TAG') if worker 'i' is to call sim/gen_func
         'libE_info' [dict]: Info sent to/from worker to help manager update the 'H'
 
-        Available keys are:
+        Optional keys are:
         'H_rows' [list of ints]: History rows to send to worker 'i'
         'blocking' [list of ints]: Workers to be blocked by this calculation
         'persistent' [bool]: True if worker 'i' will enter persistent mode
 
 
-:Examples:
+.. Hint::
+  For allocation functions giving Work dictionaries using persistent workers, see `start_only_persistent.py`_ or `start_persistent_local_opt_gens.py`_.
+  For a use case where the allocation and generator functions combine to do simulation evaluations with different resources (blocking some workers), see `test_6-hump_camel_with_different_nodes_uniform_sample.py`_.
 
-.. How to link directly to the file?
-
-| For allocation functions using persistent workers, see
-| ``libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py``
-| or
-| ``libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py``
-|
-| For allocation functions giving work that blocks other workers, see
-| ``libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py``
+.. _start_only_persistent.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_only_persistent.py 
+.. _start_persistent_local_opt_gens.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
+.. _test_6-hump_camel_with_different_nodes_uniform_sample.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
diff --git a/docs/dev_guide/release_management/release_process.rst b/docs/dev_guide/release_management/release_process.rst
index a26c36b7d..86274e1e9 100644
--- a/docs/dev_guide/release_management/release_process.rst
+++ b/docs/dev_guide/release_management/release_process.rst
@@ -15,11 +15,11 @@ Before release
 
 - Release notes for this version are added to the documentation with release date, including a list of supported (tested) platforms.
 
-- Version number is updated wherever it appears (in `setup.py`, `libensemble/__init__.py`, `README.rst` and twice in `docs/conf.py`)
+- Version number is updated wherever it appears (in ``setup.py``, ``libensemble/__init__.py``, ``README.rst`` and twice in ``docs/conf.py``)
 
-- Check year is correct in README.rst under `Citing libEnsemble` and in `docs/conf.py`.
+- Check year is correct in ``README.rst`` under *Citing libEnsemble* and in ``docs/conf.py``.
 
-- setup.py and `libensemble/__init__.py` are checked to ensure all information is up to date.
+- ``setup.py`` and ``libensemble/__init__.py`` are checked to ensure all information is up to date.
 
 - Tests are run with source to be released (this may iterate):
 
diff --git a/libensemble/message_numbers.py b/libensemble/message_numbers.py
index d868fb9d4..59e747179 100644
--- a/libensemble/message_numbers.py
+++ b/libensemble/message_numbers.py
@@ -1,6 +1,6 @@
 # --- Tags
 
-UNSET_TAG = 0  # sh temp - this is a libE feature that is to be reviewed for best solution
+UNSET_TAG = 0  # sh temp - this is a libE feature to be reviewed for best solution
 EVAL_SIM_TAG = 1
 EVAL_GEN_TAG = 2
 STOP_TAG = 3

From 669846c9fd23257cc06a0b251d5199e8e9149d1d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 16 Oct 2019 14:19:58 -0500
Subject: [PATCH 351/644] Using correct admonitions

---
 docs/conf.py                                  |  1 -
 docs/data_structures/alloc_specs.rst          | 10 +++---
 docs/data_structures/exit_criteria.rst        |  3 ++
 docs/data_structures/gen_specs.rst            | 36 +++++++++----------
 docs/data_structures/history_array.rst        | 12 +++----
 docs/data_structures/persis_info.rst          | 10 +++---
 docs/data_structures/work_dict.rst            |  2 +-
 docs/data_structures/worker_array.rst         |  7 ++--
 libensemble/tests/regression_tests/support.py |  7 ++--
 9 files changed, 44 insertions(+), 44 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 2359576ea..f742f4460 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -172,7 +172,6 @@ def __getattr__(cls, name):
     # Sonny, Lenny, or Bjornstrup
     'fncychap': '\\usepackage[Lenny]{fncychap}',
     'extraclassoptions': 'openany',
-    'sphinxsetup': 'admonitioncolor={RGB}{255,204,204}',
     'preamble':
     r'''
     \protected\def\sphinxcrossref#1{\texttt{#1}}
diff --git a/docs/data_structures/alloc_specs.rst b/docs/data_structures/alloc_specs.rst
index a02c37f8d..0e06b01a2 100644
--- a/docs/data_structures/alloc_specs.rst
+++ b/docs/data_structures/alloc_specs.rst
@@ -19,10 +19,10 @@ Allocation function specifications to be set in user calling script and passed t
             Default: [('allocated',bool)]
 
 
-:Notes:
+.. note::
 
-* The alloc_specs has the default keys as given above, but may be overidden by the user.
-* The tuples defined in the 'out' list are entered into the master :ref:`history array<datastruct-history-array>`
+  * The alloc_specs has the default keys as given above, but may be overidden by the user.
+  * The tuples defined in the 'out' list are entered into the master :ref:`history array<datastruct-history-array>`
 
-
-:Examples:
+.. seealso::
+  * JL fill
diff --git a/docs/data_structures/exit_criteria.rst b/docs/data_structures/exit_criteria.rst
index 70492bc76..07de7f50d 100644
--- a/docs/data_structures/exit_criteria.rst
+++ b/docs/data_structures/exit_criteria.rst
@@ -17,3 +17,6 @@ Exit criteria for libEnsemble::
             Stop after this amount of seconds have elapsed (since the libEnsemble manager has been initialized)
         'stop_val' [(str,float)] :
             Stop when H[str] (for some field str returned from sim_out or gen_out) has been observed with a value less than the float given
+
+.. seealso::
+  JL fill
diff --git a/docs/data_structures/gen_specs.rst b/docs/data_structures/gen_specs.rst
index a90529afa..528146ed3 100644
--- a/docs/data_structures/gen_specs.rst
+++ b/docs/data_structures/gen_specs.rst
@@ -21,28 +21,28 @@ Generation function specifications to be set in user calling script and passed t
         'save_every_k' [int] :
             Save history array to file after every k generated points.
 
-:Notes:
+.. note::
 
-* The user may define other fields to be passed to the generator function.
-* The tuples defined in the 'out' list are entered into the master :ref:`history array<datastruct-history-array>`
-* The generator 'out' field will generally include a variable(s) which is used for the simulator 'in' field,
-  in which case only the variable name is required for the simulator 'in' field.  E.g. The
-  **test_6-hump_camel_uniform_sampling.py** example below, matches the corresponding
-  :ref:`sim_specs example<sim-specs-exmple1>`, where 'x' is defined in the gen_specs 'out' field to give
-  two positional floats.
+  * The user may define other fields to be passed to the generator function.
+  * The tuples defined in the 'out' list are entered into the master :ref:`history array<datastruct-history-array>`
+  * The generator 'out' field will generally include a variable(s) which is used for the simulator 'in' field,
+    in which case only the variable name is required for the simulator 'in' field.  E.g. The
+    **test_6-hump_camel_uniform_sampling.py** example below, matches the corresponding
+    :ref:`sim_specs example<sim-specs-exmple1>`, where 'x' is defined in the gen_specs 'out' field to give
+    two positional floats.
 
 
-:Examples:
+.. seealso::
 
-.. _gen-specs-exmple1:
+  .. _gen-specs-exmple1:
 
-From: ``libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py``
+  From: ``libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py``
 
-..  literalinclude:: ../../libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
-    :start-at: gen_specs
-    :end-before: end_gen_specs_rst_tag
+  ..  literalinclude:: ../../libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
+      :start-at: gen_specs
+      :end-before: end_gen_specs_rst_tag
 
-In this example, the generation function *uniform_random_sample* will generate 500 random points
-uniformly over the 2D domain defined by ``gen_specs['ub']`` and ``gen_specs['lb']``.
-The libEnsemble manager is set to dump the history array to file after every 300 generated points,
-though in this case it will only happen after 500 points due to the batch size.
+  In this example, the generation function *uniform_random_sample* will generate 500 random points
+  uniformly over the 2D domain defined by ``gen_specs['ub']`` and ``gen_specs['lb']``.
+  The libEnsemble manager is set to dump the history array to file after every 300 generated points,
+  though in this case it will only happen after 500 points due to the batch size.
diff --git a/docs/data_structures/history_array.rst b/docs/data_structures/history_array.rst
index 017b7430d..78a5f8f3c 100644
--- a/docs/data_structures/history_array.rst
+++ b/docs/data_structures/history_array.rst
@@ -19,13 +19,13 @@ Below are the protected fields used in ``H``
 ..  literalinclude:: ../../libensemble/libE_fields.py
     :start-at: libE_fields
 
-:Examples:
+.. seealso:: 
 
-See example :doc:`sim_specs<./sim_specs>`, :doc:`gen_specs<./gen_specs>`, and :doc:`alloc_specs<./alloc_specs>`.
+  See example :doc:`sim_specs<./sim_specs>`, :doc:`gen_specs<./gen_specs>`, and :doc:`alloc_specs<./alloc_specs>`.
 
-Users can also check the internal consistency of a History array by importing ``check_inputs()``
-and calling it with their gen, alloc, and sim specs as keyword arguments::
+  Users can also check the internal consistency of a History array by importing ``check_inputs()``
+  and calling it with their gen, alloc, and sim specs as keyword arguments::
 
-    from libensemble.libE import check_inputs
+      from libensemble.libE import check_inputs
 
-    check_inputs(H0=my_H, sim_specs=sim_specs, alloc_specs=alloc_specs, gen_specs=gen_specs)
+      check_inputs(H0=my_H, sim_specs=sim_specs, alloc_specs=alloc_specs, gen_specs=gen_specs)
diff --git a/docs/data_structures/persis_info.rst b/docs/data_structures/persis_info.rst
index 87ff5ca7b..29fa51f8c 100644
--- a/docs/data_structures/persis_info.rst
+++ b/docs/data_structures/persis_info.rst
@@ -15,10 +15,10 @@ If worker ``i`` sends back ``persis_info``, it is stored in ``persis_info[i]``.
 can be used to, for example, pass a random stream back to the manager to be included in future work
 from the allocation function.
 
-:Examples:
+.. seealso::
 
-From: ``libEnsemble/tests/regression_tests/support.py``
+  From: ``libEnsemble/tests/regression_tests/support.py``
 
-..  literalinclude:: ../../libensemble/tests/regression_tests/support.py
-    :start-at: persis_info_1
-    :end-before: end_persis_info_rst_tag
+  ..  literalinclude:: ../../libensemble/tests/regression_tests/support.py
+      :start-at: persis_info_1
+      :end-before: end_persis_info_rst_tag
diff --git a/docs/data_structures/work_dict.rst b/docs/data_structures/work_dict.rst
index 1a75d9743..a7dfaaef7 100644
--- a/docs/data_structures/work_dict.rst
+++ b/docs/data_structures/work_dict.rst
@@ -21,7 +21,7 @@ Dictionary with integer keys ``i`` and dictionary values to be given to worker `
         'persistent' [bool]: True if worker 'i' will enter persistent mode
 
 
-.. Hint::
+.. seealso::
   For allocation functions giving Work dictionaries using persistent workers, see `start_only_persistent.py`_ or `start_persistent_local_opt_gens.py`_.
   For a use case where the allocation and generator functions combine to do simulation evaluations with different resources (blocking some workers), see `test_6-hump_camel_with_different_nodes_uniform_sample.py`_.
 
diff --git a/docs/data_structures/worker_array.rst b/docs/data_structures/worker_array.rst
index e378caaf8..e592789bd 100644
--- a/docs/data_structures/worker_array.rst
+++ b/docs/data_structures/worker_array.rst
@@ -20,7 +20,6 @@ waiting, persistent gen                        0          2           0
 worker blocked by some other calculation       1          0           1
 =========================================   =======  ============  =======
 
-:Note:
-
-* libE only receives from workers with 'active' nonzero
-* libE only calls the alloc_f if some worker has 'active' zero
+.. note::
+  * libE only receives from workers with a nonzero 'active' state
+  * libE only calls the alloc_f if some worker has an 'active' state of zero
diff --git a/libensemble/tests/regression_tests/support.py b/libensemble/tests/regression_tests/support.py
index 23cf171bf..dcd2ec220 100644
--- a/libensemble/tests/regression_tests/support.py
+++ b/libensemble/tests/regression_tests/support.py
@@ -37,13 +37,12 @@ def nan_func(calc_in, persis_info, sim_specs, libE_info):
 # give_sim_work_first persis_info
 persis_info_1 = {'total_gen_calls': 0,  # Counts gen calls in alloc_f
                  'last_worker': 0,      # Remembers last gen worker in alloc_f
-                 'next_to_give': 0,     # Remembers next H row to give in alloc_f
-                }
+                 'next_to_give': 0}     # Remembers next H row to give in alloc_f
+
 persis_info_1[0] = {'run_order': {},    # Used by manager to remember run order
                     'old_runs': {},     # Used by manager to store old runs order
                     'total_runs': 0,    # Used by manager to count total runs
-                    'rand_stream': np.random.RandomState(1)
-                   }
+                    'rand_stream': np.random.RandomState(1)}
 # end_persis_info_rst_tag
 
 persis_info_2 = copy.deepcopy(persis_info_1)

From 44c234bfbd10ccc96a8816f343d17497d0747d80 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 16 Oct 2019 15:34:55 -0500
Subject: [PATCH 352/644] Working on more documentation

---
 docs/data_structures/alloc_specs.rst           |  9 ++++++++-
 docs/data_structures/exit_criteria.rst         | 18 ++++++++++++------
 docs/data_structures/gen_specs.rst             |  6 ++++--
 docs/data_structures/libE_specs.rst            |  5 +++++
 .../test_branin_aposmm_nlopt_and_then_scipy.py |  1 +
 ..._uniform_sampling_one_residual_at_a_time.py |  9 +++++----
 6 files changed, 35 insertions(+), 13 deletions(-)

diff --git a/docs/data_structures/alloc_specs.rst b/docs/data_structures/alloc_specs.rst
index 0e06b01a2..4131d6c83 100644
--- a/docs/data_structures/alloc_specs.rst
+++ b/docs/data_structures/alloc_specs.rst
@@ -25,4 +25,11 @@ Allocation function specifications to be set in user calling script and passed t
   * The tuples defined in the 'out' list are entered into the master :ref:`history array<datastruct-history-array>`
 
 .. seealso::
-  * JL fill
+  The script `test_chwirut_uniform_sampling_one_residual_at_a_time.py`_
+  specifies fields to be used by the allocation function.
+
+  ..  literalinclude:: ../../libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
+      :start-at: alloc_specs
+      :end-before: end_alloc_specs_rst_tag
+
+.. _test_chwirut_uniform_sampling_one_residual_at_a_time.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
diff --git a/docs/data_structures/exit_criteria.rst b/docs/data_structures/exit_criteria.rst
index 07de7f50d..5a2cd6114 100644
--- a/docs/data_structures/exit_criteria.rst
+++ b/docs/data_structures/exit_criteria.rst
@@ -10,13 +10,19 @@ Exit criteria for libEnsemble::
         Optional keys (At least one must be given) :
 
         'sim_max' [int] :
-            Stop after this many points have been evaluated (by sim_f) in current run
+            Stop when this many new points have been evaluated by sim_f 
         'gen_max' [int] :
-            Stop after this many points have been generated by gen_f in current run
+            Stop when this many new points have been generated by gen_f
         'elapsed_wallclock_time' [float] :
-            Stop after this amount of seconds have elapsed (since the libEnsemble manager has been initialized)
-        'stop_val' [(str,float)] :
-            Stop when H[str] (for some field str returned from sim_out or gen_out) has been observed with a value less than the float given
+            Stop when this time (since the manager has been initialized) has elapsed
+        'stop_val' [(str, float)] :
+            Stop when H[str] < float for the given (str, float pair)
 
 .. seealso::
-  JL fill
+  From `test_branin_aposmm_nlopt_and_then_scipy.py`_.
+
+  ..  literalinclude:: ../../libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
+      :start-at: exit_criteria
+      :end-before: end_exit_criteria_rst_tag
+
+.. _test_branin_aposmm_nlopt_and_then_scipy.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
diff --git a/docs/data_structures/gen_specs.rst b/docs/data_structures/gen_specs.rst
index 528146ed3..c2cfd8c8a 100644
--- a/docs/data_structures/gen_specs.rst
+++ b/docs/data_structures/gen_specs.rst
@@ -36,13 +36,15 @@ Generation function specifications to be set in user calling script and passed t
 
   .. _gen-specs-exmple1:
 
-  From: ``libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py``
+  From `test_6-hump_camel_uniform_sampling.py`_
 
   ..  literalinclude:: ../../libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
       :start-at: gen_specs
       :end-before: end_gen_specs_rst_tag
 
-  In this example, the generation function *uniform_random_sample* will generate 500 random points
+  In this example, the generation function ``uniform_random_sample`` will generate 500 random points
   uniformly over the 2D domain defined by ``gen_specs['ub']`` and ``gen_specs['lb']``.
   The libEnsemble manager is set to dump the history array to file after every 300 generated points,
   though in this case it will only happen after 500 points due to the batch size.
+
+.. _test_6-hump_camel_uniform_sampling.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
diff --git a/docs/data_structures/libE_specs.rst b/docs/data_structures/libE_specs.rst
index 6fdad35e4..2d47e4e19 100644
--- a/docs/data_structures/libE_specs.rst
+++ b/docs/data_structures/libE_specs.rst
@@ -16,3 +16,8 @@ Specifications for libEnsemble::
         'abort_on_exception' [boolean] :
             In MPI mode, whether to call MPI_ABORT on an exception. Default: True
             IF False, an exception will be raised by the manager.
+
+.. seealso::
+  Examples in `common.py`_
+
+.. _common.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/common.py
diff --git a/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py b/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
index 075efc66d..ef22e533e 100644
--- a/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
+++ b/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
@@ -66,6 +66,7 @@
 exit_criteria = {'sim_max': 150,
                  'elapsed_wallclock_time': 100,
                  'stop_val': ('f', -1)}
+# end_exit_criteria_rst_tag
 
 # Perform the run
 for run in range(2):
diff --git a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
index 17f561389..fdee1c242 100644
--- a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
+++ b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
@@ -63,10 +63,11 @@
              'ub': 2*np.ones(n),
              'components': m}
 
-alloc_specs = {'alloc_f': alloc_f,
-               'out': [('allocated', bool)],
-               'stop_on_NaNs': True,
-               'stop_partial_fvec_eval': True}
+alloc_specs = {'alloc_f': alloc_f,              # Allocation function
+               'out': [('allocated', bool)],    # Output fields (included in History) 
+               'stop_on_NaNs': True,            # Should alloc_f preempt evals 
+               'stop_partial_fvec_eval': True}  # Should alloc_f preempt evals
+# end_alloc_specs_rst_tag
 
 persis_info = per_worker_stream(persis_info, nworkers + 1)
 persis_info_safe = deepcopy(persis_info)

From 0c74a26570ff0cda642fca599c366754fcd4f273 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 16 Oct 2019 15:40:42 -0500
Subject: [PATCH 353/644] Whitespace

---
 docs/data_structures/exit_criteria.rst                        | 2 +-
 docs/data_structures/history_array.rst                        | 2 +-
 docs/data_structures/work_dict.rst                            | 2 +-
 .../test_chwirut_uniform_sampling_one_residual_at_a_time.py   | 4 ++--
 4 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/data_structures/exit_criteria.rst b/docs/data_structures/exit_criteria.rst
index 5a2cd6114..a4a762ac4 100644
--- a/docs/data_structures/exit_criteria.rst
+++ b/docs/data_structures/exit_criteria.rst
@@ -10,7 +10,7 @@ Exit criteria for libEnsemble::
         Optional keys (At least one must be given) :
 
         'sim_max' [int] :
-            Stop when this many new points have been evaluated by sim_f 
+            Stop when this many new points have been evaluated by sim_f
         'gen_max' [int] :
             Stop when this many new points have been generated by gen_f
         'elapsed_wallclock_time' [float] :
diff --git a/docs/data_structures/history_array.rst b/docs/data_structures/history_array.rst
index 78a5f8f3c..38ede0a0e 100644
--- a/docs/data_structures/history_array.rst
+++ b/docs/data_structures/history_array.rst
@@ -19,7 +19,7 @@ Below are the protected fields used in ``H``
 ..  literalinclude:: ../../libensemble/libE_fields.py
     :start-at: libE_fields
 
-.. seealso:: 
+.. seealso::
 
   See example :doc:`sim_specs<./sim_specs>`, :doc:`gen_specs<./gen_specs>`, and :doc:`alloc_specs<./alloc_specs>`.
 
diff --git a/docs/data_structures/work_dict.rst b/docs/data_structures/work_dict.rst
index a7dfaaef7..fcf9a3398 100644
--- a/docs/data_structures/work_dict.rst
+++ b/docs/data_structures/work_dict.rst
@@ -25,6 +25,6 @@ Dictionary with integer keys ``i`` and dictionary values to be given to worker `
   For allocation functions giving Work dictionaries using persistent workers, see `start_only_persistent.py`_ or `start_persistent_local_opt_gens.py`_.
   For a use case where the allocation and generator functions combine to do simulation evaluations with different resources (blocking some workers), see `test_6-hump_camel_with_different_nodes_uniform_sample.py`_.
 
-.. _start_only_persistent.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_only_persistent.py 
+.. _start_only_persistent.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_only_persistent.py
 .. _start_persistent_local_opt_gens.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
 .. _test_6-hump_camel_with_different_nodes_uniform_sample.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
diff --git a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
index fdee1c242..046048881 100644
--- a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
+++ b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
@@ -64,8 +64,8 @@
              'components': m}
 
 alloc_specs = {'alloc_f': alloc_f,              # Allocation function
-               'out': [('allocated', bool)],    # Output fields (included in History) 
-               'stop_on_NaNs': True,            # Should alloc_f preempt evals 
+               'out': [('allocated', bool)],    # Output fields (included in History)
+               'stop_on_NaNs': True,            # Should alloc_f preempt evals
                'stop_partial_fvec_eval': True}  # Should alloc_f preempt evals
 # end_alloc_specs_rst_tag
 

From 043bbb4c4cf5eb20824b1fa7201ea053e95e0f10 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 16 Oct 2019 15:54:51 -0500
Subject: [PATCH 354/644] Removing usage of 'color' to avoid confusion

---
 libensemble/tests/regression_tests/common.py         | 12 ++++++------
 .../regression_tests/script_test_balsam_hworld.py    |  2 +-
 .../test_chwirut_pounders_splitcomm.py               |  4 ++--
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index aaa2f9784..672fd362b 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -36,7 +36,7 @@ def mpi_parse_args(args):
     from mpi4py import MPI
     nworkers = MPI.COMM_WORLD.Get_size()-1
     is_master = MPI.COMM_WORLD.Get_rank() == 0
-    libE_specs = {'comm': MPI.COMM_WORLD, 'color': 0, 'comms': 'mpi'}
+    libE_specs = {'comm': MPI.COMM_WORLD, 'comms': 'mpi'}
     return nworkers, is_master, libE_specs, args.tester_args
 
 
@@ -50,16 +50,16 @@ def mpi_comm_excl(exc=[0], comm=None):
     return mpi_comm, MPI.COMM_NULL
 
 
-def mpi_comm_split(num_colors, comm=None):
+def mpi_comm_split(num_parts, comm=None):
     "Split COMM_WORLD into sub-communicators for MPI comms."
     from mpi4py import MPI
     parent_comm = comm or MPI.COMM_WORLD
     parent_size = parent_comm.Get_size()
     key = parent_comm.Get_rank()
-    row_size = parent_size // num_colors
-    color = key // row_size
-    sub_comm = parent_comm.Split(color, key)
-    return sub_comm, color
+    row_size = parent_size // num_parts
+    sub_comm_number = key // row_size
+    sub_comm = parent_comm.Split(sub_comm_number, key)
+    return sub_comm, sub_comm_number
 
 
 def local_parse_args(args):
diff --git a/libensemble/tests/regression_tests/script_test_balsam_hworld.py b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
index ee6cc5609..16ac5b694 100644
--- a/libensemble/tests/regression_tests/script_test_balsam_hworld.py
+++ b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
@@ -24,7 +24,7 @@ def build_simfunc():
     subprocess.check_call(buildstring.split())
 
 
-libE_specs = {'comm': MPI.COMM_WORLD, 'color': 0, 'comms': 'mpi'}
+libE_specs = {'comm': MPI.COMM_WORLD, 'comms': 'mpi'}
 
 nworkers = MPI.COMM_WORLD.Get_size() - 1
 is_master = MPI.COMM_WORLD.Get_rank() == 0
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py b/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
index 2b2f8dc3f..377d22bf8 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
@@ -25,7 +25,7 @@
 
 num_comms = 2  # Must have atleast num_comms*2 processors
 nworkers, is_master, libE_specs, _ = parse_args()
-libE_specs['comm'], color = mpi_comm_split(num_comms)
+libE_specs['comm'], sub_comm_number = mpi_comm_split(num_comms)
 is_master = (libE_specs['comm'].Get_rank() == 0)
 
 # Declare the run parameters/functions
@@ -72,5 +72,5 @@
     J = EvaluateJacobian(H['x'][np.argmin(H['f'])])
     assert np.linalg.norm(J) < 2000
 
-    outname = os.path.splitext(__file__)[0] + '_color' + str(color)
+    outname = os.path.splitext(__file__)[0] + '_sub_comm' + str(sub_comm_number)
     save_libE_output(H, persis_info, outname, nworkers)

From 0aaadbb7236298013804c6b9077fd4db51551113 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 8 Oct 2019 11:15:09 -0500
Subject: [PATCH 355/644] Changing default alloc func to only give
 gen_specs['in'] if it's a field with length

(cherry picked from commit 29eabfe45e8242021b3d9f04195a60f024d77fbe)
---
 libensemble/alloc_funcs/give_sim_work_first.py               | 5 ++++-
 .../tests/regression_tests/test_1d_uniform_sampling.py       | 1 -
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/libensemble/alloc_funcs/give_sim_work_first.py b/libensemble/alloc_funcs/give_sim_work_first.py
index f52118972..6b2f9d78b 100644
--- a/libensemble/alloc_funcs/give_sim_work_first.py
+++ b/libensemble/alloc_funcs/give_sim_work_first.py
@@ -78,6 +78,9 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
 
             # Give gen work
             gen_count += 1
-            gen_work(Work, i, gen_specs['in'], range(len(H)), persis_info[i])
+            if 'in' in gen_specs and len(gen_specs['in']):
+                gen_work(Work, i, gen_specs['in'], range(len(H)), persis_info[i])
+            else:
+                gen_work(Work, i, [], [], persis_info[i])
 
     return Work, persis_info
diff --git a/libensemble/tests/regression_tests/test_1d_uniform_sampling.py b/libensemble/tests/regression_tests/test_1d_uniform_sampling.py
index 131d9cd5a..2ce48ab30 100644
--- a/libensemble/tests/regression_tests/test_1d_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_1d_uniform_sampling.py
@@ -26,7 +26,6 @@
 sim_specs = {'sim_f': sim_f, 'in': ['x'], 'out': [('f', float)]}
 
 gen_specs = {'gen_f': gen_f,
-             'in': ['sim_id'],
              'out': [('x', float, (1,))],
              'lb': np.array([-3]),
              'ub': np.array([3]),

From a6f9ca363abcc8fc5e831a371d018b87f55b998c Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 17 Oct 2019 11:14:55 -0500
Subject: [PATCH 356/644] Adding comment

---
 .../regression_tests/test_6-hump_camel_persistent_aposmm_1.py   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
index 94a145662..d537012a0 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
@@ -46,7 +46,7 @@
 gen_specs = {'gen_f': gen_f,
              'in': [],
              'out': gen_out,
-             'batch_mode': True,
+             'batch_mode': True,     #  a different comment
              'initial_sample_size': 100,
              'sample_points': np.round(minima, 1),
              'localopt_method': 'LD_MMA',

From a6f0445c12ccb15c473fcd7c4d961c3eb3d8c49c Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 17 Oct 2019 11:36:49 -0500
Subject: [PATCH 357/644] Revert "Adding comment"

This reverts commit a6f9ca363abcc8fc5e831a371d018b87f55b998c.
---
 .../regression_tests/test_6-hump_camel_persistent_aposmm_1.py   | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
index d537012a0..94a145662 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
@@ -46,7 +46,7 @@
 gen_specs = {'gen_f': gen_f,
              'in': [],
              'out': gen_out,
-             'batch_mode': True,     #  a different comment
+             'batch_mode': True,
              'initial_sample_size': 100,
              'sample_points': np.round(minima, 1),
              'localopt_method': 'LD_MMA',

From 119139c4a649f8b086c13b153c9af9e9d7d1ef41 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Mon, 21 Oct 2019 07:05:02 -0500
Subject: [PATCH 358/644] Background color on hints

---
 docs/conf.py                           |  8 ++++++++
 docs/data_structures/history_array.rst | 11 ++++++-----
 docs/data_structures/worker_array.rst  | 22 +++++++++++++++++++---
 docs/examples/gen_funcs.rst            |  4 ++--
 4 files changed, 35 insertions(+), 10 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index f742f4460..7ef1e3929 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -175,6 +175,14 @@ def __getattr__(cls, name):
     'preamble':
     r'''
     \protected\def\sphinxcrossref#1{\texttt{#1}}
+
+    \newsavebox\mytempbox
+\definecolor{sphinxnoteBgColor}{RGB}{221,233,239}
+\renewenvironment{sphinxnote}[1]
+   {\begin{lrbox}{\mytempbox}\begin{minipage}{\columnwidth}%
+    \begin{sphinxlightbox}\sphinxstrong{#1} }
+   {\end{sphinxlightbox}\end{minipage}\end{lrbox}%
+    \colorbox{sphinxnoteBgColor}{\usebox{\mytempbox}}}
                 ''',
     # The paper size ('letterpaper' or 'a4paper').
     #
diff --git a/docs/data_structures/history_array.rst b/docs/data_structures/history_array.rst
index 38ede0a0e..ab0c7a1b5 100644
--- a/docs/data_structures/history_array.rst
+++ b/docs/data_structures/history_array.rst
@@ -2,11 +2,10 @@
 
 history array
 =============
-
-Stores the history of the output from gen_f, sim_f, and alloc_f::
+::
 
     H: numpy structured array
-        History array storing rows for each point.
+        History to store output from ``gen_f``/``sim_f``/``alloc_f`` for each entry
 
 Fields in ``H`` include those specified in ``sim_specs['out']``,
 ``gen_specs['out']``, and ``alloc_specs['out']``. All values are initiated to
@@ -23,8 +22,10 @@ Below are the protected fields used in ``H``
 
   See example :doc:`sim_specs<./sim_specs>`, :doc:`gen_specs<./gen_specs>`, and :doc:`alloc_specs<./alloc_specs>`.
 
-  Users can also check the internal consistency of a History array by importing ``check_inputs()``
-  and calling it with their gen, alloc, and sim specs as keyword arguments::
+.. hint::
+  Users can check the internal consistency of a History array by importing
+  ``check_inputs()`` and calling it with their ``gen_specs``, ``alloc_specs``,
+  and ``sim_specs`` as keyword arguments::
 
       from libensemble.libE import check_inputs
 
diff --git a/docs/data_structures/worker_array.rst b/docs/data_structures/worker_array.rst
index e592789bd..bf73f9913 100644
--- a/docs/data_structures/worker_array.rst
+++ b/docs/data_structures/worker_array.rst
@@ -2,10 +2,20 @@
 
 worker array
 =============
+::
 
-Stores information to inform the allocation function about the current state of
-the workers. Workers can be in a variety of states. We take the following
-convention:
+    W: numpy structured array
+        'active' [int]:
+            Is the worker active or not
+        'persis_state' [int]:
+            Is the worker in a persis_state
+        'blocked' [int]:
+            Is the worker's resources blocked by another calculation
+
+Since workers can be an a variety of states, the worker array ``W`` is contains
+information about each workers state. This can allow an allocation functions to
+determine what work should be performed.
+We take the following convention:
 
 =========================================   =======  ============  =======
 Worker state                                 active  persis_state  blocked
@@ -23,3 +33,9 @@ worker blocked by some other calculation       1          0           1
 .. note::
   * libE only receives from workers with a nonzero 'active' state
   * libE only calls the alloc_f if some worker has an 'active' state of zero
+
+.. seealso:: 
+  For an example allocation function that queries the worker array, see
+  `persistent_aposmm_alloc`_.
+
+.. _persistent_aposmm_alloc: https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/persistent_aposmm_alloc.py
diff --git a/docs/examples/gen_funcs.rst b/docs/examples/gen_funcs.rst
index 110216e36..5c3fd2495 100644
--- a/docs/examples/gen_funcs.rst
+++ b/docs/examples/gen_funcs.rst
@@ -6,9 +6,9 @@ Below are example generation functions available in libEnsemble.
 .. IMPORTANT::
   See the API for generation functions :ref:`here<api_gen_f>`
 
-uniform_sampling
+sampling
 ----------------
-.. automodule:: uniform_sampling
+.. automodule:: sampling
   :members:
   :undoc-members:
 

From d8528262bed80357f8e7d410a3d41efad19b477d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Mon, 21 Oct 2019 07:46:11 -0500
Subject: [PATCH 359/644] A space

---
 docs/data_structures/worker_array.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/data_structures/worker_array.rst b/docs/data_structures/worker_array.rst
index bf73f9913..338096d3b 100644
--- a/docs/data_structures/worker_array.rst
+++ b/docs/data_structures/worker_array.rst
@@ -34,7 +34,7 @@ worker blocked by some other calculation       1          0           1
   * libE only receives from workers with a nonzero 'active' state
   * libE only calls the alloc_f if some worker has an 'active' state of zero
 
-.. seealso:: 
+.. seealso::
   For an example allocation function that queries the worker array, see
   `persistent_aposmm_alloc`_.
 

From 337c7919856e469dc3d0e8432e5cb55dd639704c Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 21 Oct 2019 12:56:40 -0500
Subject: [PATCH 360/644] rewording FAQ, move mac-stuff to own question

---
 docs/FAQ.rst | 127 +++++++++++++++++++++++----------------------------
 1 file changed, 56 insertions(+), 71 deletions(-)

diff --git a/docs/FAQ.rst b/docs/FAQ.rst
index d0c44346f..f72a72cca 100644
--- a/docs/FAQ.rst
+++ b/docs/FAQ.rst
@@ -7,52 +7,52 @@ If you have any further questions, feel free to contact us through Support_
 .. _Support: https://libensemble.readthedocs.io/en/latest/quickstart.html#support
 
 
-Parallel Debugging
-------------------
+Local Parallel Debugging
+------------------------
 
-**How can I perform parallel debugging on libEnsemble, or debug specific processes?**
+**How can I debug specific libEnsemble processes?**
 
+This is most easily addressed when running libEnsemble locally. Try
 
-This is most easily addressed when running with MPI.
-Try the following: ``mpiexec -np [num processes] xterm -e 'python [calling script].py'``
+ ``mpiexec -np [num processes] xterm -e 'python [calling script].py'``
 
-This will launch an xterm terminal window specific to each process. Mac users will
+to launch an xterm terminal window specific to each process. Mac users will
 need to install xQuartz_.
 
-.. _xQuartz: https://www.xquartz.org/
-
-If running in ``local`` comms mode try using one of the ``ForkablePdb``
-routines in ``libensemble/util/forkpdb.py`` to set breakpoints. How well these
-work may depend on the system. Usage::
+If running in ``local`` mode try using one of the ``ForkablePdb``
+routines in ``libensemble/util/forkpdb.py`` to set breakpoints and debug similarly
+to ``pdb``. How well this works varies by system::
 
     from libensemble.util.forkpdb import ForkablePdb
     ForkablePdb().set_trace()
 
 
+.. _xQuartz: https://www.xquartz.org/
+
+
 AssertionError - idle workers
 -----------------------------
 
-**AssertionError: Should not wait for workers when all workers are idle.**
-
-with ``mpiexec -np 1 python [calling script].py``
+**What does "AssertionError: Should not wait for workers when all workers are idle."
+mean?**
 
-This error occurs when the manager is waiting although no workers are busy.
-In the above case, this occurs because an MPI libEnsemble run was initiated with
-only one process, resulting in one manager but no workers.
+This error occurs when the manager is waiting although no workers are busy, or
+an MPI libEnsemble run was initiated with only one process, resulting in one
+manager but no workers.
 
 This may also occur with two processes if you are using a persistent generator.
 The generator will occupy the one worker, leaving none to run simulation functions.
 
 
-Not enough processors per worker to honour arguments
-----------------------------------------------------
+Not enough processors per worker to honor arguments
+---------------------------------------------------
 
-**libensemble.resources.ResourcesException: Not enough processors per worker to honour arguments.**
+**I keep getting: "Not enough processors per worker to honor arguments." when
+using the job controller. Can I launch jobs anyway?**
 
-This error often occurs when there aren't enough cores/nodes available to launch
-jobs with the job controller. Automatic partitioning of resources can be disabled
-if you want to oversubscribe (often if testing on a local machine) by configuring
-the job controller with ``auto_resources=False``. E.g.::
+Automatic partitioning of resources can be disabled if you want to oversubscribe
+(often if testing on a local machine) by configuring the job controller with
+``auto_resources=False``. E.g.::
 
     jobctrl = MPIJobController(auto_resources=False)
 
@@ -65,9 +65,8 @@ FileExistsError
 
 **FileExistsError: [Errno 17] File exists: './sim_worker1'**
 
-This can happen when libEnsemble tries to create sim directories that already exist.
-If these directories do not already exist, another possibility is that you are trying
-to run libEnsemble using ``mpiexec`` when the ``libE_specs['comms']`` option is
+This can happen when libEnsemble tries to create sim directories that already exist,
+or libEnsemble is launched with ``mpiexec`` when the ``libE_specs['comms']`` option is
 set to ``local``.
 
 To create differently named sim directories, you can use the ``sim_dir_suffix``
@@ -77,9 +76,11 @@ option in :ref:`sim_specs<datastruct-sim-specs>`.
 libEnsemble hangs when using mpi4py
 -----------------------------------
 
+**Why does libEnsemble hang on certain systems when running with MPI?**
+
 This may occur if matching probes, which mpi4py uses by default, are not supported
 by the communications fabric. This has been observed with Intels Truescale (TMI)
-fabric at time of writing. This can be solved either by switching fabrics or disabling
+fabric at time of writing. This can be solved by switching fabrics or disabling
 matching probes before the MPI module is first imported.
 
 Add these two lines BEFORE ``from mpi4py import MPI``::
@@ -98,12 +99,8 @@ This may manifest with the following error:
 **_pickle.UnpicklingError: invalid load key, '\x00'.**
 
 or some similar variation. This has been observed with the OFA fabric. The solution
-is to either switch fabric or turn off matching probes.
-
-Add these two lines BEFORE 'from mpi4py import MPI'::
-
-    import mpi4py
-    mpi4py.rc.recv_mprobe = False
+is to either switch fabric or turn off matching probes. See the answer for "Why
+does libEnsemble hang on certain systems when running with MPI?"
 
 For more information see: https://bitbucket.org/mpi4py/mpi4py/issues/102/unpicklingerror-on-commrecv-after-iprobe
 
@@ -115,48 +112,18 @@ PETSc and MPI errors
 
 with ``python [test with PETSc].py --comms local --nworkers 4``
 
-This error occurs on some platforms, including Travis, when using PETSc with libEnsemble
+This error occurs on some platforms, including Travis CI, when using PETSc with libEnsemble
 in ``local`` (multiprocessing) mode. We believe this is due to PETSc initializing MPI
 before libEnsemble forks processes using multiprocessing. The recommended solution
 is running libEnsemble in MPI mode. An alternative solution may be using a serial
 build of PETSc.
 
-Note: This error does not occur on all platforms and may depend on how multiprocessing
-handles an existing MPI communicator in a particular platform.
-
-
-Fatal error in MPI_Init_thread
-------------------------------
-
-**Fatal error in MPI_Init_thread: Other MPI error, error stack: ... gethostbyname failed**
-
-
-This error may be macOS specific. MPI uses TCP to initiate connections,
-and needs the local hostname to function. MPI checks /etc/hosts for this information,
-and causes the above error if it can't find the correct entry.
-
-Resolve this by appending ``127.0.0.1   [your hostname]`` to /etc/hosts.
-Unfortunately, ``127.0.0.1   localhost`` isn't satisfactory for preventing this
-error.
-
-
-macOS - Firewall prompts
-------------------------
-
-**macOS - Constant Firewall Security permission windows throughout Job Controller task**
+Note: This error may depend on how multiprocessing handles an existing MPI
+communicator in a particular platform.
 
 
-There are several ways to address this nuisance, but all involve trial and error.
-An easy (but insecure) solution is temporarily disabling the Firewall through
-System Preferences -> Security & Privacy -> Firewall -> Turn Off Firewall. Alternatively,
-adding a Firewall "Allow incoming connections" rule can be attempted for the offending
-Job Controller executable. We've had limited success running ``sudo codesign --force --deep --sign - /path/to/application.app``
-on our Job Controller executables, then confirming the next alerts for the executable
-and ``mpiexec.hydra``.
-
-
-Running out of contexts when running libEnsemble in distributed mode on TMI fabric
-----------------------------------------------------------------------------------
+Running out of contexts in distributed mode on TMI fabric
+---------------------------------------------------------
 
 The error message may be similar to below:
 
@@ -178,8 +145,26 @@ Another alternative is to run libEnsemble in central mode, in which libEnsemble
 nodes, while launching all sub-jobs to other nodes.
 
 
-macOS - PETSc Installation issues
----------------------------------
+macOS - Common Issues
+-------------------
+
+**"Fatal error in MPI_Init_thread: Other MPI error, error stack: ... gethostbyname failed"**
+
+Resolve this by appending ``127.0.0.1   [your hostname]`` to /etc/hosts.
+Unfortunately, ``127.0.0.1   localhost`` isn't satisfactory for preventing this
+error.
+
+
+**How do I stop the Firewall Security popups when running with the Job Controller?**
+
+There are several ways to address this nuisance, but all involve trial and error.
+An easy (but insecure) solution is temporarily disabling the Firewall through
+System Preferences -> Security & Privacy -> Firewall -> Turn Off Firewall. Alternatively,
+adding a Firewall "Allow incoming connections" rule can be attempted for the offending
+Job Controller executable. We've had limited success running ``sudo codesign --force --deep --sign - /path/to/application.app``
+on our Job Controller executables, then confirming the next alerts for the executable
+and ``mpiexec.hydra``.
+
 
 **Frozen PETSc installation following a failed wheel build with** ``pip install petsc petsc4py``
 

From 56ada89c3a52498c7f192b7ae50f42f18bc85faf Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 21 Oct 2019 14:45:12 -0500
Subject: [PATCH 361/644] notes -> note blocks. Reformatting. fixes reference.
 first round of platforms info.

---
 README.rst                  | 12 +++++-----
 docs/FAQ.rst                |  7 +++---
 docs/examples/gen_funcs.rst |  2 +-
 docs/index.rst              | 10 ++++++++
 docs/platforms/bebop.rst    | 47 +++++++++++++++++++++++++++++++++++++
 docs/platforms/theta.rst    | 19 +++++++++++++++
 6 files changed, 87 insertions(+), 10 deletions(-)
 create mode 100644 docs/platforms/bebop.rst
 create mode 100644 docs/platforms/theta.rst

diff --git a/README.rst b/README.rst
index 36766cc9f..297ee22c3 100644
--- a/README.rst
+++ b/README.rst
@@ -155,10 +155,11 @@ which can be viewed after running the tests via the HTML file
 available online at
 `Coveralls <https://coveralls.io/github/Libensemble/libensemble?branch=master>`_.
 
-Note: The job_controller tests can be run using the direct-launch or
-Balsam job controllers. Although only the direct-launch versions can
-be run on Travis CI, Balsam integration with libEnsemble is now tested via
-``test_balsam_hworld.py``.
+.. note::
+    The job_controller tests can be run using the direct-launch or
+    Balsam job controllers. Although only the direct-launch versions can be run
+    on Travis CI, Balsam integration with libEnsemble is now tested via
+    ``test_balsam_hworld.py``.
 
 
 Basic Usage
@@ -176,7 +177,7 @@ where ``N`` is the number of processors. This will launch one manager and
 ``N-1`` workers.
 
 If running in local mode, which uses Python's multiprocessing module, the
-'local' comms option and the number of workers must be specified. The script
+``local`` comms option and the number of workers must be specified. The script
 can then be run as a regular python script::
 
     python myscript.py
@@ -240,4 +241,3 @@ or communicate (and establish a private channel, if desired) at:
 .. _pytest: https://pypi.org/project/pytest/
 .. _pytest-cov: https://pypi.org/project/pytest-cov/
 .. _pytest-timeout: https://pypi.org/project/pytest-timeout/
-
diff --git a/docs/FAQ.rst b/docs/FAQ.rst
index f72a72cca..6110e180f 100644
--- a/docs/FAQ.rst
+++ b/docs/FAQ.rst
@@ -118,8 +118,9 @@ before libEnsemble forks processes using multiprocessing. The recommended soluti
 is running libEnsemble in MPI mode. An alternative solution may be using a serial
 build of PETSc.
 
-Note: This error may depend on how multiprocessing handles an existing MPI
-communicator in a particular platform.
+.. note::
+    This error may depend on how multiprocessing handles an existing MPI
+    communicator in a particular platform.
 
 
 Running out of contexts in distributed mode on TMI fabric
@@ -146,7 +147,7 @@ nodes, while launching all sub-jobs to other nodes.
 
 
 macOS - Common Issues
--------------------
+---------------------
 
 **"Fatal error in MPI_Init_thread: Other MPI error, error stack: ... gethostbyname failed"**
 
diff --git a/docs/examples/gen_funcs.rst b/docs/examples/gen_funcs.rst
index 110216e36..30fe00f12 100644
--- a/docs/examples/gen_funcs.rst
+++ b/docs/examples/gen_funcs.rst
@@ -8,7 +8,7 @@ Below are example generation functions available in libEnsemble.
 
 uniform_sampling
 ----------------
-.. automodule:: uniform_sampling
+.. automodule:: sampling
   :members:
   :undoc-members:
 
diff --git a/docs/index.rst b/docs/index.rst
index 8a624bfca..f3eaac54d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -44,6 +44,8 @@ libEnsemble is a library for managing ensemble-like collections of computations.
      Quickstart<quickstart>
      user_guide
      tutorials/local_sine_tutorial
+     platforms/bebop
+     platforms/theta
      contributing
      FAQ
      libE_module
@@ -75,6 +77,14 @@ libEnsemble is a library for managing ensemble-like collections of computations.
      tutorials/local_sine_tutorial
 
 
+  .. toctree::
+     :maxdepth: 2
+     :caption: Running on:
+
+     platforms/bebop
+     platforms/theta
+
+
   .. toctree::
      :maxdepth: 2
      :caption: User Guide:
diff --git a/docs/platforms/bebop.rst b/docs/platforms/bebop.rst
new file mode 100644
index 000000000..551f21042
--- /dev/null
+++ b/docs/platforms/bebop.rst
@@ -0,0 +1,47 @@
+=====
+Bebop
+=====
+
+Bebop_ is the newest addition to the computational power of LCRC at Argonne
+National Laboratory, featuring both Intel Broadwell and Knights Landing nodes.
+
+
+
+Before getting started
+----------------------
+
+An Argonne LCRC_ account is required to access Bebop. Interested users will need
+to apply for and be granted an account before continuing.
+
+
+
+Configuring Python
+------------------
+
+Begin by loading the Python 3 Anaconda_ module::
+
+    module load anaconda3/2018.12
+
+Create a Conda_ virtual environment in which to install libEnsemble and all
+dependencies::
+
+    conda config --add channels intel
+    conda create --name my_env intelpython3_core python=3
+    source activate my_env
+
+You should have an indication that the virtual environment is activated.
+Install mpi4py_ and libEnsemble in this environment, making sure to reference
+the pre-installed Intel MPI Compiler. Your prompt should be similar to the
+following block:
+
+.. code-block:: console
+
+    (my_env) user@beboplogin4:~$ CC=mpiicc MPICC=mpiicc pip install mpi4py --no-binary mpi4py
+    (my_env) user@beboplogin4:~$ pip install libensemble
+
+
+.. _Bebop: https://www.lcrc.anl.gov/systems/resources/bebop/
+.. _LCRC: https://www.lcrc.anl.gov
+.. _Anaconda: https://www.anaconda.com/distribution/
+.. _Conda: https://conda.io/en/latest/
+.. _mpi4py: https://mpi4py.readthedocs.io/en/stable/
diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
new file mode 100644
index 000000000..4395272f9
--- /dev/null
+++ b/docs/platforms/theta.rst
@@ -0,0 +1,19 @@
+=====
+Theta
+=====
+
+Theta_ is a 11.69 petaflops system based on the second-generation Intel® Xeon Phi™
+ processor, available within ALCF at Argonne National Laboratory.
+
+
+
+Before getting started
+----------------------
+
+An Argonne ALCF_ account is required to access Theta. Interested users will need
+to apply for and be granted an account before continuing.
+
+
+
+.. _ALCF: https://www.alcf.anl.gov/
+.. _Theta: https://www.alcf.anl.gov/theta

From a574b99138936565a4c75a77eb9c0734a315ee4f Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 21 Oct 2019 16:17:25 -0500
Subject: [PATCH 362/644] complete first draft for bebop

---
 docs/platforms/bebop.rst | 92 +++++++++++++++++++++++++++++++++++++++-
 docs/platforms/theta.rst |  4 +-
 2 files changed, 93 insertions(+), 3 deletions(-)

diff --git a/docs/platforms/bebop.rst b/docs/platforms/bebop.rst
index 551f21042..284a588c7 100644
--- a/docs/platforms/bebop.rst
+++ b/docs/platforms/bebop.rst
@@ -11,8 +11,8 @@ Before getting started
 ----------------------
 
 An Argonne LCRC_ account is required to access Bebop. Interested users will need
-to apply for and be granted an account before continuing.
-
+to apply for and be granted an account before continuing. To submit jobs to Bebop,
+users can charge hours to a project or their personal allocation (default).
 
 
 Configuring Python
@@ -29,6 +29,10 @@ dependencies::
     conda create --name my_env intelpython3_core python=3
     source activate my_env
 
+
+Installing Dependencies and libEnsemble
+---------------------------------------
+
 You should have an indication that the virtual environment is activated.
 Install mpi4py_ and libEnsemble in this environment, making sure to reference
 the pre-installed Intel MPI Compiler. Your prompt should be similar to the
@@ -40,8 +44,92 @@ following block:
     (my_env) user@beboplogin4:~$ pip install libensemble
 
 
+Job Submission
+--------------
+
+Bebop uses Slurm_ for job management. The two commands you'll likely use the most
+to run jobs are ``srun`` and ``sbatch`` for running interactively and batch, respectively.
+
+
+Interactive Runs
+^^^^^^^^^^^^^^^^
+
+You can allocate four Knights Landing nodes for thirty minutes through the following::
+
+    salloc -N 4 -p knl -A [username OR project] -t 00:30:00
+
+
+With your nodes allocated, queue your job to start with five MPI ranks::
+
+    srun -n 5 python calling.py
+
+
+``mpirun`` should also work. This launches a worker on every node, on which every
+worker can perform stand-alone calculations or launch jobs through the job controller.
+
+.. note::
+    When performing an MPI libEnsemble run and not oversubscribing, specify one
+    more MPI process than the number of allocated nodes. The Manager and first
+    worker run together on a node.
+
+
+Batch Runs
+^^^^^^^^^^
+
+Batch scripts specify run-settings using ``#SBATCH`` statements. A simple example
+for a libEnsemble use-case running on Broadwell nodes resembles the following:
+
+.. code-block:: bash
+
+    #!/bin/bash
+    #SBATCH -J myjob
+    #SBATCH -N 4
+    #SBATCH -p bdwall
+    #SBATCH -A myproject
+    #SBATCH -o myjob.out
+    #SBATCH -e myjob.error
+    #SBATCH -t 00:15:00
+
+    # These four lines construct a machinefile for the job controller and slurm
+    srun hostname | sort -u > node_list
+    head -n 1 node_list > machinefile.$SLURM_JOBID
+    cat node_list >> machinefile.$SLURM_JOBID
+    export SLURM_HOSTFILE=machinefile.$SLURM_JOBID
+
+    srun --ntasks 5 python3 calling_script.py
+
+
+With this saved as ``myscript.sh``, allocating, configuring, and running libEnsemble
+on Bebop is as simple as::
+
+    sbatch myscript.sh
+
+
+Debugging Strategies
+--------------------
+
+View the status of your submitted jobs with ``squeue``.
+
+It's not recommended to debug compute-intensive tasks on the login nodes. Start
+a bash session on a Knights Landing node for thirty minutes with::
+
+    srun --pty -A [username OR project] -p knl -t 00:30:00 /bin/bash
+
+.. note::
+    You will need to re-activate your conda virtual environment and reload your
+    modules! Configuring this routine to occur automatically is recommended.
+
+
+Additional Information
+----------------------
+
+See the LCRC Bebop docs here_ for much more information.
+
+
 .. _Bebop: https://www.lcrc.anl.gov/systems/resources/bebop/
 .. _LCRC: https://www.lcrc.anl.gov
 .. _Anaconda: https://www.anaconda.com/distribution/
 .. _Conda: https://conda.io/en/latest/
 .. _mpi4py: https://mpi4py.readthedocs.io/en/stable/
+.. _Slurm: https://slurm.schedmd.com/
+.. _here: https://www.lcrc.anl.gov/for-users/using-lcrc/running-jobs/running-jobs-on-bebop/
diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index 4395272f9..88d3ca871 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -11,7 +11,9 @@ Before getting started
 ----------------------
 
 An Argonne ALCF_ account is required to access Theta. Interested users will need
-to apply for and be granted an account before continuing.
+to apply for and be granted an account before continuing. To submit jobs to Theta,
+users must charge their jobs to a project (likely specified while requesting an
+account.)
 
 
 

From 6ee450772c5470ce4981dc881516ec99e3f36ba4 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 21 Oct 2019 17:27:45 -0500
Subject: [PATCH 363/644] bebop clarification. beginning theta info

---
 docs/platforms/bebop.rst | 14 +++---
 docs/platforms/theta.rst | 97 +++++++++++++++++++++++++++++++++++++++-
 2 files changed, 104 insertions(+), 7 deletions(-)

diff --git a/docs/platforms/bebop.rst b/docs/platforms/bebop.rst
index 284a588c7..232e35f5e 100644
--- a/docs/platforms/bebop.rst
+++ b/docs/platforms/bebop.rst
@@ -7,13 +7,16 @@ National Laboratory, featuring both Intel Broadwell and Knights Landing nodes.
 
 
 
-Before getting started
+Before Getting Started
 ----------------------
 
 An Argonne LCRC_ account is required to access Bebop. Interested users will need
 to apply for and be granted an account before continuing. To submit jobs to Bebop,
 users can charge hours to a project or their personal allocation (default).
 
+Bebop consists primarily of login and compute nodes. Users start on the login
+nodes, and schedule work for execution on the compute nodes.
+
 
 Configuring Python
 ------------------
@@ -30,7 +33,7 @@ dependencies::
     source activate my_env
 
 
-Installing Dependencies and libEnsemble
+Installing libEnsemble and Dependencies
 ---------------------------------------
 
 You should have an indication that the virtual environment is activated.
@@ -47,7 +50,7 @@ following block:
 Job Submission
 --------------
 
-Bebop uses Slurm_ for job management. The two commands you'll likely use the most
+Bebop uses Slurm_ for job submission and management. The two commands you'll likely use the most
 to run jobs are ``srun`` and ``sbatch`` for running interactively and batch, respectively.
 
 
@@ -80,6 +83,7 @@ Batch scripts specify run-settings using ``#SBATCH`` statements. A simple exampl
 for a libEnsemble use-case running on Broadwell nodes resembles the following:
 
 .. code-block:: bash
+    :linenos:
 
     #!/bin/bash
     #SBATCH -J myjob
@@ -100,7 +104,7 @@ for a libEnsemble use-case running on Broadwell nodes resembles the following:
 
 
 With this saved as ``myscript.sh``, allocating, configuring, and running libEnsemble
-on Bebop is as simple as::
+on Bebop becomes::
 
     sbatch myscript.sh
 
@@ -123,7 +127,7 @@ a bash session on a Knights Landing node for thirty minutes with::
 Additional Information
 ----------------------
 
-See the LCRC Bebop docs here_ for much more information.
+See the LCRC Bebop docs here_ for much more information about Bebop.
 
 
 .. _Bebop: https://www.lcrc.anl.gov/systems/resources/bebop/
diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index 88d3ca871..e6a969e48 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -2,8 +2,8 @@
 Theta
 =====
 
-Theta_ is a 11.69 petaflops system based on the second-generation Intel® Xeon Phi™
- processor, available within ALCF at Argonne National Laboratory.
+Theta_ is a 11.69 petaflops system based on the second-generation Intel Xeon Phi
+processor, available within ALCF at Argonne National Laboratory.
 
 
 
@@ -15,7 +15,100 @@ to apply for and be granted an account before continuing. To submit jobs to Thet
 users must charge their jobs to a project (likely specified while requesting an
 account.)
 
+Theta consists of numerous types of nodes, but libEnsemble users will mostly interact
+with login, Machine Oriented Mini-server (MOM) and compute nodes. MOM nodes execute
+user batch scripts to run on the compute nodes.
+
+Configuring Python
+------------------
+
+
+
+Installing libEnsemble and Dependencies
+---------------------------------------
+
+
+Balsam
+^^^^^^
+
+
+Job Submission
+--------------
+
+Theta features one default production queue, ``default``, and two debug queues,
+``debug-cache-quad`` and ``debug-flat-quad``.
+
+.. note::
+    For the default queue, the minimum number of nodes to allocate is 128!
+
+Theta uses Cobalt for job submission and management. The most important two
+commands to run and manage jobs are ``qsub`` and ``aprun``, for submitting batch
+scripts from the login nodes and launching jobs to the compute nodes respectively.
+
+Because mpi4py doesn't function on the Theta MOM nodes, libEnsemble is commonly
+run in multiprocessing mode with all workers running on the MOM nodes. In these
+circumstances, libEnsemble's job controller takes responsibility for ``aprun``
+submissions of jobs to compute nodes.
+
+
+
+Interactive Runs
+^^^^^^^^^^^^^^^^
+
+Users can run interactively with ``qsub`` by specifying the ``-I`` flag, similarly
+to the following::
+
+    qsub -A [project] -n 128 -q default -t 120 -I
+
+This will place the user on a MOM node. To launch the job to the allocated compute nodes,
+run::
+
+    aprun...
+
+.. note::
+    You will need to re-activate your conda virtual environment and reload your
+    modules! Configuring this routine to occur automatically is recommended.
+
+Batch Runs
+^^^^^^^^^^
+
+Batch scripts specify run-settings using ``#COBALT`` statements. A simple example
+for a libEnsemble use-case resembles the following:
+
+.. code-block:: bash
+
+    <code>
+
+With this saved as ``myscript.sh``, allocating, configuring, and running libEnsemble
+on Theta becomes::
+
+    qsub --mode script myscript.sh
+
+
+Running with Balsam
+^^^^^^^^^^^^^^^^^^^
+
+
+Debugging Strategies
+--------------------
+
+Each of the two debug queues has sixteen nodes apiece. A user can use up to
+eight nodes at a time for a maximum of one hour. Allocate nodes on the debug
+queue interactively::
+
+    qsub -A [project] -n 4 -q debug-flat-quad -t 60 -I
+
+
+Additional Information
+----------------------
+
+See the ALCF guides_ on XC40 systems for much more information about Theta.
+
+Become more familiar with Balsam here_.
+
 
 
 .. _ALCF: https://www.alcf.anl.gov/
 .. _Theta: https://www.alcf.anl.gov/theta
+.. _guides: https://www.alcf.anl.gov/user-guides/computational-systems
+.. _here: https://balsam.readthedocs.io/en/latest/

From 88b04f6e40ef7ba4320d357a1bf4ed795309d0e0 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 22 Oct 2019 13:01:32 -0500
Subject: [PATCH 364/644] further formatting, external links, batch scripts,
 theta setup/balsam information

---
 docs/platforms/bebop.rst |   7 +-
 docs/platforms/theta.rst | 238 +++++++++++++++++++++++++++++++++------
 2 files changed, 209 insertions(+), 36 deletions(-)

diff --git a/docs/platforms/bebop.rst b/docs/platforms/bebop.rst
index 232e35f5e..5ff711620 100644
--- a/docs/platforms/bebop.rst
+++ b/docs/platforms/bebop.rst
@@ -6,7 +6,6 @@ Bebop_ is the newest addition to the computational power of LCRC at Argonne
 National Laboratory, featuring both Intel Broadwell and Knights Landing nodes.
 
 
-
 Before Getting Started
 ----------------------
 
@@ -112,9 +111,9 @@ on Bebop becomes::
 Debugging Strategies
 --------------------
 
-View the status of your submitted jobs with ``squeue``.
+View the status of your submitted jobs with ``squeue`` and cancel jobs with ``scancel [jobID]``.
 
-It's not recommended to debug compute-intensive tasks on the login nodes. Start
+It's not recommended to debug compute-intensive tasks on the login nodes. Instead, start
 a bash session on a Knights Landing node for thirty minutes with::
 
     srun --pty -A [username OR project] -p knl -t 00:30:00 /bin/bash
@@ -127,7 +126,7 @@ a bash session on a Knights Landing node for thirty minutes with::
 Additional Information
 ----------------------
 
-See the LCRC Bebop docs here_ for much more information about Bebop.
+See the LCRC Bebop docs here_ for more information about Bebop.
 
 
 .. _Bebop: https://www.lcrc.anl.gov/systems/resources/bebop/
diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index e6a969e48..c87fd2280 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -3,53 +3,106 @@ Theta
 =====
 
 Theta_ is a 11.69 petaflops system based on the second-generation Intel Xeon Phi
-processor, available within ALCF at Argonne National Laboratory.
+processor, available within ALCF_ at Argonne National Laboratory.
 
 
-
-Before getting started
+Before Getting Started
 ----------------------
 
-An Argonne ALCF_ account is required to access Theta. Interested users will need
+An Argonne ALCF account is required to access Theta. Interested users will need
 to apply for and be granted an account before continuing. To submit jobs to Theta,
-users must charge their jobs to a project (likely specified while requesting an
-account.)
+users must charge their jobs to a project (specified while requesting an
+account).
 
-Theta consists of numerous types of nodes, but libEnsemble users will mostly interact
+Theta contains numerous node-types, but libEnsemble users will mostly interact
 with login, Machine Oriented Mini-server (MOM) and compute nodes. MOM nodes execute
-user batch scripts to run on the compute nodes.
+user batch-scripts to run on the compute nodes.
+
+libEnsemble functions need to incorporate the libEnsemble
+:ref:`job controller<jobcontroller_index>` to perform calculations on Theta.
+
 
 Configuring Python
 ------------------
 
+Begin by loading the Python 3 Miniconda_ module::
+
+    $ module load miniconda-3.6/conda-4.5.12
+
+Create a Conda_ virtual environment in which to install libEnsemble and all
+dependencies::
+
+    $ conda config --add channels intel
+    $ conda create --name my_env intelpython3_core python=3
+    $ source activate my_env
+
+More information_ on using Conda on Theta.
 
 
 Installing libEnsemble and Dependencies
 ---------------------------------------
 
 
+libEnsemble and mpi4py
+^^^^^^^^^^^^^^^^^^^^^^
+
+There should be an indication that the virtual environment is activated.
+Install mpi4py_ and libEnsemble in this environment, making sure to reference
+the pre-installed Intel MPI Compiler. Your prompt should be similar to the
+following block:
+
+.. code-block:: console
+
+    (my_env) user@thetalogin6:~$ CC=mpiicc MPICC=mpiicc pip install mpi4py --no-binary mpi4py
+    (my_env) user@thetalogin6:~$ pip install libensemble
+
+
 Balsam
 ^^^^^^
 
+Balsam_ is an ALCF Python utility for coordinating and executing workflows of
+computations on systems like Theta. Balsam can stage in tasks from many sources,
+including libEnsemble's job controller, and submit these tasks dynamically to the
+compute nodes. If running with MPI, Balsam is necessary to launch libEnsemble on
+Theta.
+
+Load the Balsam module with::
+
+    $ module load balsam/0.3.5.1
+
+Balsam stages tasks in and out from a database. Initialize a new database similarly
+to thefollowing:
+
+.. code-block:: bash
+
+    $ balsam init ~/libe-workflow
+    $ source balsamactivate libe-workflow
+    $ balsam app --name libe-app --executable "calling.py"
+    $ balsam job --name libe-job --workflow test --application libe-app --args "hello!"
+    $ balsam submit-launch -A [project] -q default -t 5 -n 1 --job-mode=mpi
+    $ watch balsam ls   #  follow status in realtime from command-line
+
+See **Additional Information** for the Balsam docs.
 
 Job Submission
 --------------
 
-Theta features one default production queue, ``default``, and two debug queues,
-``debug-cache-quad`` and ``debug-flat-quad``.
+Theta uses Cobalt_ for job submission and management. For libEnsemble, the most
+important command is ``qsub``, for submitting batch scripts from the login nodes.
 
-.. note::
-    For the default queue, the minimum number of nodes to allocate is 128!
+On Theta, libEnsemble is commonly configured to run in one of two ways:
 
-Theta uses Cobalt for job submission and management. The most important two
-commands to run and manage jobs are ``qsub`` and ``aprun``, for submitting batch
-scripts from the login nodes and launching jobs to the compute nodes respectively.
+    1. Multiprocessing mode, with libEnsemble's MPI job controller taking
+    responsibility for direct submissions of jobs to compute nodes.
 
-Because mpi4py doesn't function on the Theta MOM nodes, libEnsemble is commonly
-run in multiprocessing mode with all workers running on the MOM nodes. In these
-circumstances, libEnsemble's job controller takes responsibility for ``aprun``
-submissions of jobs to compute nodes.
+    2. MPI mode, with libEnsemble's Balsam job controller interfacing with a Balsam
+    backend for dynamic job submission.
+
+Theta features one default production queue, ``default``, and two debug queues,
+``debug-cache-quad`` and ``debug-flat-quad``.
 
+.. note::
+    For the default queue, the minimum number of nodes to allocate at once is 128
 
 
 Interactive Runs
@@ -58,12 +111,10 @@ Interactive Runs
 Users can run interactively with ``qsub`` by specifying the ``-I`` flag, similarly
 to the following::
 
-    qsub -A [project] -n 128 -q default -t 120 -I
+    $ qsub -A [project] -n 128 -q default -t 120 -I
 
-This will place the user on a MOM node. To launch the job to the allocated compute nodes,
-run::
-
-    aprun...
+This will place the user on a MOM node. If running in multiprocessing mode, launching
+jobs to the compute nodes is as simple as ``python calling_script.py``
 
 .. note::
     You will need to re-activate your conda virtual environment and reload your
@@ -73,42 +124,165 @@ Batch Runs
 ^^^^^^^^^^
 
 Batch scripts specify run-settings using ``#COBALT`` statements. A simple example
-for a libEnsemble use-case resembles the following:
+for a libEnsemble use-case may resemble the following:
 
 .. code-block:: bash
 
-    <code>
+    #!/bin/bash -x
+    #COBALT -t 02:00:00
+    #COBALT -n 128
+    #COBALT -q default
+    #COBALT -A [project]
+    #COBALT -O libE-project
+
+    module load miniconda-3.6/conda-4.5.12
+
+    # Name of calling script
+    export EXE=calling_script.py
+
+    # Communication Method
+    export COMMS='--comms local'
+
+    # Number of workers.
+    export NWORKERS='--nworkers 128'
+
+    # Name of Conda environment
+    export CONDA_ENV_NAME=my_env
+
+    # Activate Conda environment
+    export PYTHONNOUSERSITE=1
+    source activate $CONDA_ENV_NAME
+
+    # Conda location - theta specific
+    export PATH=/home/user/path/to/packages/:$PATH
+    export LD_LIBRARY_PATH=/home/user/path/to/packages/:$LD_LIBRARY_PATH
+    export PYTHONPATH=/home/user/path/to/env/packages:$PYTHONPATH
+
+    # Required for python kills on Theta
+    export PMI_NO_FORK=1
+
+    python $EXE $COMMS $NWORKERS > out.txt 2>&1
+
 
 With this saved as ``myscript.sh``, allocating, configuring, and running libEnsemble
 on Theta becomes::
 
-    qsub --mode script myscript.sh
+    $ qsub --mode script myscript.sh
+
+
+Balsam Runs
+^^^^^^^^^^^
+
+Balsam runs are Batch runs, except Balsam is responsible for submitting libEnsemble
+for execution. This is an example Balsam submission script:
+
+.. code-block:: bash
+
+    #!/bin/bash -x
+    #COBALT -t 60
+    #COBALT -O libE_test
+    #COBALT -n 128
+    #COBALT -q default
+    ##COBALT -A [project]
+
+    # Name of calling script
+    export EXE=calling_script.py
+
+    # Number of workers.
+    export NUM_WORKERS=128
+
+    # Wall-clock for libE job (supplied to Balsam)
+    export LIBE_WALLCLOCK=45
+
+    # Name of working directory where Balsam places running jobs/output
+    export WORKFLOW_NAME=libe_workflow
+
+    #Tell libE manager to stop workers, dump timing.dat and exit after time.
+    export SCRIPT_ARGS=$(($LIBE_WALLCLOCK-3))
 
+    # Name of Conda environment
+    export CONDA_ENV_NAME=my_env
 
-Running with Balsam
-^^^^^^^^^^^^^^^^^^^
+    # Conda location - theta specific
+    export PATH=/path/to/python/bin:$PATH
+    export LD_LIBRARY_PATH=~/path/to/conda/env/lib:$LD_LIBRARY_PATH
+
+    #Ensure environment isolated
+    export PYTHONNOUSERSITE=1
+
+    # Required for python kills on Theta
+    export PMI_NO_FORK=1
+
+    # Activate conda environment
+    . activate $CONDA_ENV_NAME
+
+    # Activate Balsam database
+    . balsamactivate default
+
+
+    # Currently need at least one DB connection per worker (for postgres).
+    if [[ $NUM_WORKERS -gt 128 ]]
+    then
+       #Add a margin
+       echo -e "max_connections=$(($NUM_WORKERS+10)) #Appended by submission script" >> $BALSAM_DB_PATH/balsamdb/postgresql.conf
+    fi
+    wait
+
+    # Make sure no existing apps/jobs
+    balsam rm apps --all --force
+    balsam rm jobs --all --force
+    wait
+    sleep 3
+
+    # Add calling script to Balsam database as app and job.
+    THIS_DIR=$PWD
+    SCRIPT_BASENAME=${EXE%.*}
+
+    balsam app --name $SCRIPT_BASENAME.app --exec $EXE --desc "Run $SCRIPT_BASENAME"
+
+    # Running libE on one node - one manager and upto 63 workers
+    balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --args $SCRIPT_ARGS --wall-time-minutes $LIBE_WALLCLOCK --num-nodes 1 --ranks-per-node $((NUM_WORKERS+1)) --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
+
+    #Run job
+    balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1
+
+    . balsamdeactivate
+
+See **Additional Information** for the Balsam docs.
 
 
 Debugging Strategies
 --------------------
 
+View the status of your submitted jobs with ``qstat -fu [user]``.
+
+It's not recommended to debug compute-intensive tasks on the login or MOM nodes,
+and if running in MPI mode, may be impossible. Allocate nodes on the debug queues
+for the best results.
+
 Each of the two debug queues has sixteen nodes apiece. A user can use up to
 eight nodes at a time for a maximum of one hour. Allocate nodes on the debug
 queue interactively::
 
-    qsub -A [project] -n 4 -q debug-flat-quad -t 60 -I
+    $ qsub -A [project] -n 4 -q debug-flat-quad -t 60 -I
 
 
 Additional Information
 ----------------------
 
-See the ALCF guides_ on XC40 systems for much more information about Theta.
+See the ALCF guides_ on XC40 systems for more information about Theta.
 
-Become more familiar with Balsam here_.
+Read the documentation for Balsam here_.
 
 
 
 .. _ALCF: https://www.alcf.anl.gov/
 .. _Theta: https://www.alcf.anl.gov/theta
+.. _Balsam: https://www.alcf.anl.gov/balsam
+.. _Cobalt: https://www.alcf.anl.gov/cobalt-scheduler
 .. _guides: https://www.alcf.anl.gov/user-guides/computational-systems
 .. _here: https://balsam.readthedocs.io/en/latest/
+.. _Miniconda: https://docs.conda.io/en/latest/miniconda.html
+.. _Conda: https://conda.io/en/latest/
+.. _information: https://www.alcf.anl.gov/user-guides/conda
+.. _mpi4py: https://mpi4py.readthedocs.io/en/stable/

From 86a3937964db8f35f270dd71c7a113fb32f0d287 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 22 Oct 2019 13:43:30 -0500
Subject: [PATCH 365/644] reorganize FAQ into categories

---
 docs/FAQ.rst | 126 ++++++++++++++++++++++++---------------------------
 1 file changed, 60 insertions(+), 66 deletions(-)

diff --git a/docs/FAQ.rst b/docs/FAQ.rst
index 6110e180f..8c089aa46 100644
--- a/docs/FAQ.rst
+++ b/docs/FAQ.rst
@@ -7,31 +7,9 @@ If you have any further questions, feel free to contact us through Support_
 .. _Support: https://libensemble.readthedocs.io/en/latest/quickstart.html#support
 
 
-Local Parallel Debugging
-------------------------
-
-**How can I debug specific libEnsemble processes?**
-
-This is most easily addressed when running libEnsemble locally. Try
-
- ``mpiexec -np [num processes] xterm -e 'python [calling script].py'``
-
-to launch an xterm terminal window specific to each process. Mac users will
-need to install xQuartz_.
-
-If running in ``local`` mode try using one of the ``ForkablePdb``
-routines in ``libensemble/util/forkpdb.py`` to set breakpoints and debug similarly
-to ``pdb``. How well this works varies by system::
-
-    from libensemble.util.forkpdb import ForkablePdb
-    ForkablePdb().set_trace()
-
 
-.. _xQuartz: https://www.xquartz.org/
-
-
-AssertionError - idle workers
------------------------------
+Common Errors
+-------------
 
 **What does "AssertionError: Should not wait for workers when all workers are idle."
 mean?**
@@ -44,9 +22,6 @@ This may also occur with two processes if you are using a persistent generator.
 The generator will occupy the one worker, leaving none to run simulation functions.
 
 
-Not enough processors per worker to honor arguments
----------------------------------------------------
-
 **I keep getting: "Not enough processors per worker to honor arguments." when
 using the job controller. Can I launch jobs anyway?**
 
@@ -60,9 +35,6 @@ Note that the job_controller ``.launch()`` method has a parameter``hyperthreads`
 which will attempt to use all hyperthreads/SMT threads available if set to ``True``
 
 
-FileExistsError
----------------
-
 **FileExistsError: [Errno 17] File exists: './sim_worker1'**
 
 This can happen when libEnsemble tries to create sim directories that already exist,
@@ -73,8 +45,25 @@ To create differently named sim directories, you can use the ``sim_dir_suffix``
 option in :ref:`sim_specs<datastruct-sim-specs>`.
 
 
-libEnsemble hangs when using mpi4py
------------------------------------
+**PETSc and MPI errors with "[unset]: write_line error; fd=-1 buf=:cmd=abort exitcode=59"**
+
+with ``python [test with PETSc].py --comms local --nworkers 4``
+
+This error occurs on some platforms, including Travis CI, when using PETSc with libEnsemble
+in ``local`` (multiprocessing) mode. We believe this is due to PETSc initializing MPI
+before libEnsemble forks processes using multiprocessing. The recommended solution
+is running libEnsemble in MPI mode. An alternative solution may be using a serial
+build of PETSc.
+
+.. note::
+    This error may depend on how multiprocessing handles an existing MPI
+    communicator in a particular platform.
+
+
+
+HPC Errors and Questions
+------------------------
+
 
 **Why does libEnsemble hang on certain systems when running with MPI?**
 
@@ -91,62 +80,67 @@ Add these two lines BEFORE ``from mpi4py import MPI``::
 Also see https://software.intel.com/en-us/articles/python-mpi4py-on-intel-true-scale-and-omni-path-clusters
 
 
-Messages not received correctly when using mpi4py
--------------------------------------------------
+**can't open hfi unit: -1 (err=23)**
+**[13] MPI startup(): tmi fabric is not available and fallback fabric is not enabled**
 
-This may manifest with the following error:
+This may occur on TMI when libEnsemble Python processes have been launched to a node and these,
+in turn, launch jobs on the node; creating too many processes for the available contexts. Note that
+while processes can share contexts, the system is confused by the fact that there are two
+phases, first libEnsemble processes and then sub-processes to run user jobs. The solution is to
+either reduce the number processes running or to specify a fallback fabric through environment
+variables::
+
+    unset I_MPI_FABRICS
+    export I_MPI_FABRICS_LIST=tmi,tcp
+    export I_MPI_FALLBACK=1
+
+Another alternative is to run libEnsemble in central mode, in which libEnsemble runs on dedicated
+nodes, while launching all sub-jobs to other nodes.
 
-**_pickle.UnpicklingError: invalid load key, '\x00'.**
 
-or some similar variation. This has been observed with the OFA fabric. The solution
+**What does "_pickle.UnpicklingError: invalid load key, '\x00'." indicate?**
+
+This has been observed with the OFA fabric, and usually indicates MPI messages
+aren't being received correctly when using mpi4py. The solution
 is to either switch fabric or turn off matching probes. See the answer for "Why
 does libEnsemble hang on certain systems when running with MPI?"
 
 For more information see: https://bitbucket.org/mpi4py/mpi4py/issues/102/unpicklingerror-on-commrecv-after-iprobe
 
 
-PETSc and MPI errors
---------------------
 
-**PETSc and MPI errors with "[unset]: write_line error; fd=-1 buf=:cmd=abort exitcode=59"**
+libEnsemble-theory
+------------------
 
-with ``python [test with PETSc].py --comms local --nworkers 4``
+**How can I debug specific libEnsemble processes?**
 
-This error occurs on some platforms, including Travis CI, when using PETSc with libEnsemble
-in ``local`` (multiprocessing) mode. We believe this is due to PETSc initializing MPI
-before libEnsemble forks processes using multiprocessing. The recommended solution
-is running libEnsemble in MPI mode. An alternative solution may be using a serial
-build of PETSc.
+This is most easily addressed when running libEnsemble locally. Try
 
-.. note::
-    This error may depend on how multiprocessing handles an existing MPI
-    communicator in a particular platform.
+ ``mpiexec -np [num processes] xterm -e 'python [calling script].py'``
 
+to launch an xterm terminal window specific to each process. Mac users will
+need to install xQuartz_.
 
-Running out of contexts in distributed mode on TMI fabric
----------------------------------------------------------
+If running in ``local`` mode try using one of the ``ForkablePdb``
+routines in ``libensemble/util/forkpdb.py`` to set breakpoints and debug similarly
+to ``pdb``. How well this works varies by system::
 
-The error message may be similar to below:
+    from libensemble.util.forkpdb import ForkablePdb
+    ForkablePdb().set_trace()
 
-**can't open hfi unit: -1 (err=23)**
-**[13] MPI startup(): tmi fabric is not available and fallback fabric is not enabled**
 
-This may occur on TMI when libEnsemble Python processes have been launched to a node and these,
-in turn, launch jobs on the node; creating too many processes for the available contexts. Note that
-while processes can share contexts, the system is confused by the fact that there are two
-phases, first libEnsemble processes and then sub-processes to run user jobs. The solution is to
-either reduce the number processes running or to specify a fallback fabric through environment
-variables::
+.. _xQuartz: https://www.xquartz.org/
 
-    unset I_MPI_FABRICS
-    export I_MPI_FABRICS_LIST=tmi,tcp
-    export I_MPI_FALLBACK=1
 
-Another alternative is to run libEnsemble in central mode, in which libEnsemble runs on dedicated
-nodes, while launching all sub-jobs to other nodes.
+**Can I use the MPI Job Controller when running libEnsemble with multiprocessing?**
+
+Actually, yes! The job controller type only determines how launched jobs communicate
+with libEnsemble, and is independent of ``comms`` chosen for manager-worker
+communications.
+
 
 
-macOS - Common Issues
+macOS-specific Errors
 ---------------------
 
 **"Fatal error in MPI_Init_thread: Other MPI error, error stack: ... gethostbyname failed"**

From f5e04652025240919d2b9779c88f541b4c563a37 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 22 Oct 2019 13:57:49 -0500
Subject: [PATCH 366/644] additional question

---
 docs/FAQ.rst | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/FAQ.rst b/docs/FAQ.rst
index 8c089aa46..7a5d66d46 100644
--- a/docs/FAQ.rst
+++ b/docs/FAQ.rst
@@ -11,6 +11,13 @@ If you have any further questions, feel free to contact us through Support_
 Common Errors
 -------------
 
+**I keep getting "Manager only - must be at least one worker (2 MPI tasks)" when
+running with multiprocessing and multiple workers specified.**
+
+If your calling script code was switched from MPI to multiprocessing, make sure that
+libE_specs is populated with ``comms: local`` and ``nworkers: [num]``.
+
+
 **What does "AssertionError: Should not wait for workers when all workers are idle."
 mean?**
 

From 24e469a5e8bc83d842a15de626e6f12c1aecf290 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 22 Oct 2019 15:00:25 -0500
Subject: [PATCH 367/644] adjust toctree depth

---
 docs/index.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/index.rst b/docs/index.rst
index f3eaac54d..ffeed0f44 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -78,7 +78,7 @@ libEnsemble is a library for managing ensemble-like collections of computations.
 
 
   .. toctree::
-     :maxdepth: 2
+     :maxdepth: 1
      :caption: Running on:
 
      platforms/bebop

From c7b5298607a70d610e2f72c12b0c130fe20ac58a Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 22 Oct 2019 15:05:09 -0500
Subject: [PATCH 368/644] Edits for Jeff

---
 docs/data_structures/history_array.rst        |  2 +-
 docs/data_structures/work_dict.rst            |  2 +-
 libensemble/mpi_resources.py                  | 10 +++++-----
 libensemble/tests/regression_tests/.gitignore |  1 -
 4 files changed, 7 insertions(+), 8 deletions(-)

diff --git a/docs/data_structures/history_array.rst b/docs/data_structures/history_array.rst
index 78a5f8f3c..38ede0a0e 100644
--- a/docs/data_structures/history_array.rst
+++ b/docs/data_structures/history_array.rst
@@ -19,7 +19,7 @@ Below are the protected fields used in ``H``
 ..  literalinclude:: ../../libensemble/libE_fields.py
     :start-at: libE_fields
 
-.. seealso:: 
+.. seealso::
 
   See example :doc:`sim_specs<./sim_specs>`, :doc:`gen_specs<./gen_specs>`, and :doc:`alloc_specs<./alloc_specs>`.
 
diff --git a/docs/data_structures/work_dict.rst b/docs/data_structures/work_dict.rst
index a7dfaaef7..fcf9a3398 100644
--- a/docs/data_structures/work_dict.rst
+++ b/docs/data_structures/work_dict.rst
@@ -25,6 +25,6 @@ Dictionary with integer keys ``i`` and dictionary values to be given to worker `
   For allocation functions giving Work dictionaries using persistent workers, see `start_only_persistent.py`_ or `start_persistent_local_opt_gens.py`_.
   For a use case where the allocation and generator functions combine to do simulation evaluations with different resources (blocking some workers), see `test_6-hump_camel_with_different_nodes_uniform_sample.py`_.
 
-.. _start_only_persistent.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_only_persistent.py 
+.. _start_only_persistent.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_only_persistent.py
 .. _start_persistent_local_opt_gens.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
 .. _test_6-hump_camel_with_different_nodes_uniform_sample.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
diff --git a/libensemble/mpi_resources.py b/libensemble/mpi_resources.py
index be88ff7a6..3bf4a68f4 100644
--- a/libensemble/mpi_resources.py
+++ b/libensemble/mpi_resources.py
@@ -58,7 +58,7 @@ def get_resources(self, num_procs=None, num_nodes=None,
         user supplied config is valid, and fills in any missing config
         information (ie. num_procs/num_nodes/ranks_per_node)
 
-        User supplied config options are honoured, and an exception is
+        User supplied config options are honored, and an exception is
         raised if these are infeasible.
         """
 
@@ -97,22 +97,22 @@ def get_resources(self, num_procs=None, num_nodes=None,
 
         # Could just downgrade to those available with warning - for now error
         rassert(num_nodes <= local_node_count,
-                "Not enough nodes to honour arguments. "
+                "Not enough nodes to honor arguments. "
                 "Requested {}. Only {} available".
                 format(num_nodes, local_node_count))
 
         rassert(ranks_per_node <= cores_avail_per_node,
-                "Not enough processors on a node to honour arguments. "
+                "Not enough processors on a node to honor arguments. "
                 "Requested {}. Only {} available".
                 format(ranks_per_node, cores_avail_per_node))
 
         rassert(ranks_per_node <= cores_avail_per_node_per_worker,
-                "Not enough processors per worker to honour arguments. "
+                "Not enough processors per worker to honor arguments. "
                 "Requested {}. Only {} available".
                 format(ranks_per_node, cores_avail_per_node_per_worker))
 
         rassert(num_procs <= (cores_avail_per_node * local_node_count),
-                "Not enough procs to honour arguments. "
+                "Not enough procs to honor arguments. "
                 "Requested {}. Only {} available".
                 format(num_procs, cores_avail_per_node*local_node_count))
 
diff --git a/libensemble/tests/regression_tests/.gitignore b/libensemble/tests/regression_tests/.gitignore
index ef2668a41..7791bddc5 100644
--- a/libensemble/tests/regression_tests/.gitignore
+++ b/libensemble/tests/regression_tests/.gitignore
@@ -3,4 +3,3 @@ output/
 *.pickle
 ensemble.log
 libE_stats.txt
-

From 7318eca2f73b891a1c6dfb78fe7d5b0a01424e80 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 22 Oct 2019 15:15:07 -0500
Subject: [PATCH 369/644] Changing on line

---
 docs/FAQ.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/FAQ.rst b/docs/FAQ.rst
index 7a5d66d46..be0592545 100644
--- a/docs/FAQ.rst
+++ b/docs/FAQ.rst
@@ -101,8 +101,8 @@ variables::
     export I_MPI_FABRICS_LIST=tmi,tcp
     export I_MPI_FALLBACK=1
 
-Another alternative is to run libEnsemble in central mode, in which libEnsemble runs on dedicated
-nodes, while launching all sub-jobs to other nodes.
+Alternatively, libEnsemble can be run in central mode where all workers run on dedicated
+nodes, while launching all sub-jobs onto other nodes.
 
 
 **What does "_pickle.UnpicklingError: invalid load key, '\x00'." indicate?**

From fce674b67053ddc95615ea1d1fb8c3a3c8f047b5 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 22 Oct 2019 16:16:12 -0500
Subject: [PATCH 370/644] one typo

---
 docs/data_structures/work_dict.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/data_structures/work_dict.rst b/docs/data_structures/work_dict.rst
index fcf9a3398..2863fbd6a 100644
--- a/docs/data_structures/work_dict.rst
+++ b/docs/data_structures/work_dict.rst
@@ -12,7 +12,7 @@ Dictionary with integer keys ``i`` and dictionary values to be given to worker `
         Required keys :
         'persis_info' [dict]: Any persistent info to be sent to worker 'i'
         'H_fields' [list]: The field names of the history 'H' to be sent to worker 'i'
-        'tag' [int]: 'EVAL_SIM_TAG'/'EVAL_GEN_TAG') if worker 'i' is to call sim/gen_func
+        'tag' [int]: 'EVAL_SIM_TAG'/'EVAL_GEN_TAG' if worker 'i' is to call sim/gen_func
         'libE_info' [dict]: Info sent to/from worker to help manager update the 'H'
 
         Optional keys are:

From 43b161d9648b93f8bf50afeb16e34f0a1f5fc11c Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 30 Oct 2019 13:10:01 -0500
Subject: [PATCH 371/644] Starting restructuring specs


From 507fdea5086d3efa514e61be0c8b9c6c4c36d6e8 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 30 Oct 2019 13:14:37 -0500
Subject: [PATCH 372/644] Moving all user sim_specs references to use
 sim_specs['user']

---
 libensemble/sim_funcs/branin/branin_obj.py  | 4 ++--
 libensemble/sim_funcs/chwirut1.py           | 4 ++--
 libensemble/sim_funcs/job_control_hworld.py | 2 +-
 libensemble/sim_funcs/six_hump_camel.py     | 6 +++---
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/libensemble/sim_funcs/branin/branin_obj.py b/libensemble/sim_funcs/branin/branin_obj.py
index 315189b11..0a21384b8 100644
--- a/libensemble/sim_funcs/branin/branin_obj.py
+++ b/libensemble/sim_funcs/branin/branin_obj.py
@@ -23,7 +23,7 @@ def call_branin(H, persis_info, sim_specs, _):
 
         O['f'][i] = branin(x[0], x[1])
 
-        if 'uniform_random_pause_ub' in sim_specs:
-            time.sleep(sim_specs['uniform_random_pause_ub']*np.random.uniform())
+        if 'uniform_random_pause_ub' in sim_specs['user']:
+            time.sleep(sim_specs['user']['uniform_random_pause_ub']*np.random.uniform())
 
     return O, persis_info
diff --git a/libensemble/sim_funcs/chwirut1.py b/libensemble/sim_funcs/chwirut1.py
index c55db701f..279962c35 100644
--- a/libensemble/sim_funcs/chwirut1.py
+++ b/libensemble/sim_funcs/chwirut1.py
@@ -272,14 +272,14 @@ def chwirut_eval(H, persis_info, sim_specs, _):
 
     for i, x in enumerate(H['x']):
         if 'obj_component' in H.dtype.names:
-            if 'component_nan_frequency' in sim_specs and np.random.uniform(0, 1) < sim_specs['component_nan_frequency']:
+            if 'component_nan_frequency' in sim_specs['user'] and np.random.uniform(0, 1) < sim_specs['user']['component_nan_frequency']:
                 O['f_i'][i] = np.nan
             else:
                 O['f_i'][i] = EvaluateFunction(x, H['obj_component'][i])
 
         else:
             O['fvec'][i] = EvaluateFunction(x)
-            O['f'][i] = sim_specs['combine_component_func'](O['fvec'][i])
+            O['f'][i] = sim_specs['user']['combine_component_func'](O['fvec'][i])
 
     return O, persis_info
 
diff --git a/libensemble/sim_funcs/job_control_hworld.py b/libensemble/sim_funcs/job_control_hworld.py
index 7b772fb0d..84351d93b 100644
--- a/libensemble/sim_funcs/job_control_hworld.py
+++ b/libensemble/sim_funcs/job_control_hworld.py
@@ -65,7 +65,7 @@ def polling_loop(comm, jobctl, job, timeout_sec=3.0, delay=0.3):
 def job_control_hworld(H, persis_info, sim_specs, libE_specs):
     """ Test of launching and polling job and exiting on job finish"""
     jobctl = MPIJobController.controller
-    cores = sim_specs['cores']
+    cores = sim_specs['user']['cores']
     comm = libE_specs['comm']
 
     args_for_sim = 'sleep 1'
diff --git a/libensemble/sim_funcs/six_hump_camel.py b/libensemble/sim_funcs/six_hump_camel.py
index 3f452df9e..eab355806 100644
--- a/libensemble/sim_funcs/six_hump_camel.py
+++ b/libensemble/sim_funcs/six_hump_camel.py
@@ -34,7 +34,7 @@ def six_hump_camel_with_different_ranks_and_nodes(H, persis_info, sim_specs, lib
 
         with open(machinefilename, 'w') as f:
             for rank in ranks_involved:
-                b = sim_specs['nodelist'][rank] + '\n'
+                b = sim_specs['user']['nodelist'][rank] + '\n'
                 f.write(b*H['ranks_per_node'][i])
 
         outfile_name = "outfile_" + machinefilename + ".txt"
@@ -74,7 +74,7 @@ def six_hump_camel(H, persis_info, sim_specs, _):
             O['grad'][i] = six_hump_camel_grad(x)
 
         if 'pause_time' in sim_specs:
-            time.sleep(sim_specs['pause_time'])
+            time.sleep(sim_specs['user']['pause_time'])
 
     return O, persis_info
 
@@ -92,7 +92,7 @@ def six_hump_camel_simple(x, persis_info, sim_specs, _):
     O['f'] = six_hump_camel_func(x[0][0])
 
     if 'pause_time' in sim_specs:
-        time.sleep(sim_specs['pause_time'])
+        time.sleep(sim_specs['user']['pause_time'])
 
     return O, persis_info
 

From 642e6cc0367e51406bdae588aa64bb38444e6feb Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 30 Oct 2019 13:30:02 -0500
Subject: [PATCH 373/644] Moving all user gen_specs references to use
 gen_specs['user'] or dereferencing to user_specs = gen_specs['user']

---
 libensemble/gen_funcs/aposmm.py               | 156 ++++++++--------
 libensemble/gen_funcs/persistent_aposmm.py    | 172 +++++++++---------
 .../gen_funcs/persistent_inverse_bayes.py     |   8 +-
 .../gen_funcs/persistent_uniform_sampling.py  |   6 +-
 libensemble/gen_funcs/sampling.py             |  46 ++---
 libensemble/gen_funcs/uniform_or_localopt.py  |  26 +--
 6 files changed, 208 insertions(+), 206 deletions(-)

diff --git a/libensemble/gen_funcs/aposmm.py b/libensemble/gen_funcs/aposmm.py
index 806bc1447..aea8a5d25 100644
--- a/libensemble/gen_funcs/aposmm.py
+++ b/libensemble/gen_funcs/aposmm.py
@@ -58,7 +58,7 @@ def aposmm_logic(H, persis_info, gen_specs, _):
       objective components for a given ``'x'``)
 
     When using libEnsemble to do individual objective component evaluations,
-    APOSMM will return ``gen_specs['components']`` copies of each point, but
+    APOSMM will return ``gen_specs['user']['components']`` copies of each point, but
     the component=0 entry of each point will only be considered when
 
     - deciding where to start a run,
@@ -67,7 +67,7 @@ def aposmm_logic(H, persis_info, gen_specs, _):
     - storing the combined objective function value
     - etc
 
-    Necessary quantities in ``gen_specs`` are:
+    Necessary quantities in ``gen_specs['user']`` are:
 
     - ``'lb' [n floats]``: Lower bound on search domain
     - ``'ub' [n floats]``: Upper bound on search domain
@@ -77,7 +77,7 @@ def aposmm_logic(H, persis_info, gen_specs, _):
     - ``'localopt_method' [str]``: Name of an NLopt, PETSc/TAO, or SciPy method
       (see 'advance_local_run' below for supported methods)
 
-    Optional ``gen_specs`` entries are:
+    Optional ``gen_specs['user']`` entries are:
 
     - ``'sample_points' [numpy array]``: Points to be sampled (original domain)
     - ``'combine_component_func' [func]``: Function to combine obj components
@@ -100,7 +100,7 @@ def aposmm_logic(H, persis_info, gen_specs, _):
     - ``'rk_const' [float]``: Multiplier in front of the r_k value
     - ``'max_active_runs' [int]``: Bound on number of runs APOSMM is advancing
 
-    And ``gen_specs`` convergence tolerances for NLopt, PETSc/TAO, SciPy
+    And ``gen_specs['user']`` convergence tolerances for NLopt, PETSc/TAO, SciPy
 
     - ``'fatol' [float]``:
     - ``'ftol_abs' [float]``:
@@ -126,7 +126,7 @@ def aposmm_logic(H, persis_info, gen_specs, _):
     (breaking ties arbitrarily).
 
     :Note:
-        ``gen_specs['combine_component_func']`` must be defined when there are
+        ``gen_specs['user']['combine_component_func']`` must be defined when there are
         multiple objective components.
 
     :Note:
@@ -180,10 +180,10 @@ def aposmm_logic(H, persis_info, gen_specs, _):
 
     """
 
-    n, n_s, c_flag, O, r_k, mu, nu = initialize_APOSMM(H, gen_specs)
+    n, n_s, c_flag, O, r_k, mu, nu = initialize_APOSMM(H, gen_specs['user'])
 
     # np.savez('H'+str(len(H)),H=H,gen_specs=gen_specs,persis_info=persis_info)
-    if n_s < gen_specs['initial_sample_size']:
+    if n_s < gen_specs['user']['initial_sample_size']:
         updated_inds = set()
 
     else:
@@ -203,7 +203,7 @@ def aposmm_logic(H, persis_info, gen_specs, _):
             persis_info['total_runs'] += 1
 
         num_runs = len(persis_info['run_order'])
-        if 'max_active_runs' in gen_specs and gen_specs['max_active_runs'] < num_runs:
+        if 'max_active_runs' in gen_specs['user'] and gen_specs['user']['max_active_runs'] < num_runs:
             # Store run number and sim_id of the best point in each run
             run_vals = np.zeros((num_runs, 2), dtype=int)
             for i, run in enumerate(persis_info['run_order'].keys()):
@@ -221,8 +221,8 @@ def aposmm_logic(H, persis_info, gen_specs, _):
                     dist_to_better[i] = np.min(P[i, better])
 
             # Take max_active_runs largest
-            k_sorted = np.argpartition(-dist_to_better, kth=gen_specs['max_active_runs']-1)
-            active_runs = set(run_vals[k_sorted[:gen_specs['max_active_runs']], 0].astype(int))
+            k_sorted = np.argpartition(-dist_to_better, kth=gen_specs['user']['max_active_runs']-1)
+            active_runs = set(run_vals[k_sorted[:gen_specs['user']['max_active_runs']], 0].astype(int))
         else:
             active_runs = set(persis_info['run_order'].keys())
 
@@ -233,7 +233,7 @@ def aposmm_logic(H, persis_info, gen_specs, _):
             if not np.all(H['returned'][persis_info['run_order'][run]]):
                 continue  # Can't advance a run if all points aren't returned.
 
-            x_opt, exit_code, persis_info, sorted_run_inds, x_new = advance_local_run(H, gen_specs, c_flag, run, persis_info)
+            x_opt, exit_code, persis_info, sorted_run_inds, x_new = advance_local_run(H, gen_specs['user'], c_flag, run, persis_info)
 
             if np.isinf(x_new).all():
                 if exit_code == 0:
@@ -271,15 +271,15 @@ def aposmm_logic(H, persis_info, gen_specs, _):
             persis_info['old_runs'][i] = old_run
 
     if len(H) == 0:
-        samples_needed = gen_specs['initial_sample_size']
-    elif 'min_batch_size' in gen_specs:
-        samples_needed = gen_specs['min_batch_size']-len(O)
+        samples_needed = gen_specs['user']['initial_sample_size']
+    elif 'min_batch_size' in gen_specs['user']:
+        samples_needed = gen_specs['user']['min_batch_size']-len(O)
     else:
         samples_needed = int(not bool(len(O)))  # 1 if len(O)==0, 0 otherwise
 
-    if samples_needed > 0 and 'sample_points' in gen_specs:
+    if samples_needed > 0 and 'sample_points' in gen_specs['user']:
         v = np.sum(~H['local_pt'])  # Number of sample points so far
-        sampled_points = gen_specs['sample_points'][v:v+samples_needed]
+        sampled_points = gen_specs['user']['sample_points'][v:v+samples_needed]
         on_cube = False  # Assume points are on original domain, not unit cube
         if len(sampled_points):
             persis_info = add_to_O(O, sampled_points, H, gen_specs,
@@ -308,10 +308,10 @@ def add_to_O(O, pts, H, gen_specs, c_flag, persis_info, local_flag=0,
     original_len_O = len(O)
 
     len_H = len(H)
-    ub = gen_specs['ub']
-    lb = gen_specs['lb']
+    ub = gen_specs['user']['ub']
+    lb = gen_specs['user']['lb']
     if c_flag:
-        m = gen_specs['components']
+        m = gen_specs['user']['components']
 
         assert len_H % m == 0, "Number of points in len_H not congruent to 0 mod 'components'"
         pt_ids = np.sort(np.tile(np.arange((len_H+original_len_O)/m, (len_H+original_len_O)/m+len(pts)), (1, m)))
@@ -345,7 +345,7 @@ def add_to_O(O, pts, H, gen_specs, c_flag, persis_info, local_flag=0,
         O['num_active_runs'][-num_pts] += 1
         # O['priority'][-num_pts:] = 1
         # O['priority'][-num_pts:] = np.random.uniform(0,1,num_pts)
-        if 'high_priority_to_best_localopt_runs' in gen_specs and gen_specs['high_priority_to_best_localopt_runs']:
+        if 'high_priority_to_best_localopt_runs' in gen_specs['user'] and gen_specs['user']['high_priority_to_best_localopt_runs']:
             O['priority'][-num_pts:] = -min(H['f'][persis_info['run_order'][run]])  # Give highest priority to run with lowest function value
         else:
             O['priority'][-num_pts:] = persis_info['rand_stream'].uniform(0, 1, num_pts)
@@ -358,7 +358,7 @@ def add_to_O(O, pts, H, gen_specs, c_flag, persis_info, local_flag=0,
         else:
             # p_tmp = np.random.uniform(0,1,num_pts)
             # persis_info['rand_stream'].uniform(lb,ub,(1,n))
-            if 'high_priority_to_best_localopt_runs' in gen_specs and gen_specs['high_priority_to_best_localopt_runs']:
+            if 'high_priority_to_best_localopt_runs' in gen_specs['user'] and gen_specs['user']['high_priority_to_best_localopt_runs']:
                 p_tmp = -np.inf*np.ones(num_pts)
             else:
                 p_tmp = persis_info['rand_stream'].uniform(0, 1, num_pts)
@@ -384,7 +384,7 @@ def update_history_dist(H, n, gen_specs, c_flag):
         for v in np.unique(H['pt_id'][new_inds]):
             inds = H['pt_id'] == v
             H['f'][inds] = np.inf
-            H['f'][np.where(inds)[0][0]] = gen_specs['combine_component_func'](H['f_i'][inds])
+            H['f'][np.where(inds)[0][0]] = gen_specs['user']['combine_component_func'](H['f_i'][inds])
 
         p = np.logical_and.reduce((H['returned'], H['obj_component'] == 0, ~np.isnan(H['f'])))
     else:
@@ -478,7 +478,7 @@ def update_history_optimal(x_opt, H, run_inds):
     H['num_active_runs'][run_inds] -= 1
 
 
-def advance_local_run(H, gen_specs, c_flag, run, persis_info):
+def advance_local_run(H, user_specs, c_flag, run, persis_info):
     """
     Moves a local optimization method one iteration forward. We currently do
     this by feeding all past evaluations from a run to the method and then
@@ -487,52 +487,52 @@ def advance_local_run(H, gen_specs, c_flag, run, persis_info):
 
     while 1:
         sorted_run_inds = persis_info['run_order'][run]
-        advance_local_run.x_new = np.ones((1, len(gen_specs['ub'])))*np.inf
+        advance_local_run.x_new = np.ones((1, len(user_specs['ub'])))*np.inf
         advance_local_run.pt_in_run = 0
 
-        if gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA',
+        if user_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA',
                                             'LN_COBYLA', 'LN_NELDERMEAD',
                                             'LD_MMA']:
 
-            if gen_specs['localopt_method'] in ['LD_MMA']:
+            if user_specs['localopt_method'] in ['LD_MMA']:
                 fields_to_pass = ['x_on_cube', 'f', 'grad']
             else:
                 fields_to_pass = ['x_on_cube', 'f']
 
             try:
-                x_opt, exit_code = set_up_and_run_nlopt(H[fields_to_pass][sorted_run_inds], gen_specs)
+                x_opt, exit_code = set_up_and_run_nlopt(H[fields_to_pass][sorted_run_inds], user_specs)
             except Exception as e:
                 x_opt = 0
                 exit_code = 0
                 display_exception(e)
 
-        elif gen_specs['localopt_method'] in ['pounders', 'blmvm']:
+        elif user_specs['localopt_method'] in ['pounders', 'blmvm']:
 
             if c_flag:
-                Run_H_F = np.zeros(len(sorted_run_inds), dtype=[('fvec', float, gen_specs['components'])])
+                Run_H_F = np.zeros(len(sorted_run_inds), dtype=[('fvec', float, user_specs['components'])])
                 for i, ind in enumerate(sorted_run_inds):
                     a1 = H['pt_id'] == H['pt_id'][ind]
                     Run_H_F['fvec'][i, :] = H['f_i'][a1]
                 Run_H = merge_arrays([H[['x_on_cube']][sorted_run_inds], Run_H_F], flatten=True)
             else:
-                if gen_specs['localopt_method'] == 'pounders':
+                if user_specs['localopt_method'] == 'pounders':
                     Run_H = H[['x_on_cube', 'fvec']][sorted_run_inds]
                 else:
                     Run_H = H[['x_on_cube', 'f', 'grad']][sorted_run_inds]
 
             try:
-                x_opt, exit_code = set_up_and_run_tao(Run_H, gen_specs)
+                x_opt, exit_code = set_up_and_run_tao(Run_H, user_specs)
             except Exception as e:
                 x_opt = 0
                 exit_code = 0
                 display_exception(e)
 
-        elif gen_specs['localopt_method'] == 'scipy_COBYLA':
+        elif user_specs['localopt_method'] == 'scipy_COBYLA':
 
             fields_to_pass = ['x_on_cube', 'f']
 
             try:
-                x_opt, exit_code = set_up_and_run_scipy_minimize(H[fields_to_pass][sorted_run_inds], gen_specs)
+                x_opt, exit_code = set_up_and_run_scipy_minimize(H[fields_to_pass][sorted_run_inds], user_specs)
             except Exception as e:
                 x_opt = 0
                 exit_code = 0
@@ -552,7 +552,7 @@ def advance_local_run(H, gen_specs, c_flag, run, persis_info):
     return x_opt, exit_code, persis_info, sorted_run_inds, advance_local_run.x_new
 
 
-def set_up_and_run_scipy_minimize(Run_H, gen_specs):
+def set_up_and_run_scipy_minimize(Run_H, user_specs):
     """ Set up objective and runs scipy
 
     Declares the appropriate syntax for our special objective function to read
@@ -571,14 +571,14 @@ def scipy_obj_fun(x, Run_H):
     cons = []
     for factor in range(len(x0)):
         lo = {'type': 'ineq',
-              'fun': lambda x, lb=gen_specs['lb'][factor], i=factor: x[i]-lb}
+              'fun': lambda x, lb=user_specs['lb'][factor], i=factor: x[i]-lb}
         up = {'type': 'ineq',
-              'fun': lambda x, ub=gen_specs['ub'][factor], i=factor: ub-x[i]}
+              'fun': lambda x, ub=user_specs['ub'][factor], i=factor: ub-x[i]}
         cons.append(lo)
         cons.append(up)
 
-    method = gen_specs['localopt_method'][6:]
-    res = scipy_optimize.minimize(obj, x0, method=method, options={'maxiter': len(Run_H['x_on_cube'])+1, 'tol': gen_specs['tol']})
+    method = user_specs['localopt_method'][6:]
+    res = scipy_optimize.minimize(obj, x0, method=method, options={'maxiter': len(Run_H['x_on_cube'])+1, 'tol': user_specs['tol']})
 
     if res['status'] == 2:  # SciPy code for exhausting budget of evaluations, so not at a minimum
         exit_code = 0
@@ -591,27 +591,27 @@ def scipy_obj_fun(x, Run_H):
     return x_opt, exit_code
 
 
-def set_up_and_run_nlopt(Run_H, gen_specs):
+def set_up_and_run_nlopt(Run_H, user_specs):
     """ Set up objective and runs nlopt
 
     Declares the appropriate syntax for our special objective function to read
     through Run_H, sets the parameters and starting points for the run.
     """
 
-    assert 'xtol_rel' or 'xtol_abs' or 'ftol_rel' or 'ftol_abs' in gen_specs, "NLopt can cycle if xtol_rel, xtol_abs, ftol_rel, or ftol_abs are not set"
+    assert 'xtol_rel' or 'xtol_abs' or 'ftol_rel' or 'ftol_abs' in user_specs, "NLopt can cycle if xtol_rel, xtol_abs, ftol_rel, or ftol_abs are not set"
 
     def nlopt_obj_fun(x, grad, Run_H):
         out = look_in_history(x, Run_H)
 
-        if gen_specs['localopt_method'] in ['LD_MMA']:
+        if user_specs['localopt_method'] in ['LD_MMA']:
             grad[:] = out[1]
             out = out[0]
 
         return out
 
-    n = len(gen_specs['ub'])
+    n = len(user_specs['ub'])
 
-    opt = nlopt.opt(getattr(nlopt, gen_specs['localopt_method']), n)
+    opt = nlopt.opt(getattr(nlopt, user_specs['localopt_method']), n)
 
     lb = np.zeros(n)
     ub = np.ones(n)
@@ -623,21 +623,21 @@ def nlopt_obj_fun(x, grad, Run_H):
     dist_to_bound = min(min(ub-x0), min(x0-lb))
     assert dist_to_bound > np.finfo(np.float32).eps, "The distance to the boundary is too small for NLopt to handle"
 
-    if 'dist_to_bound_multiple' in gen_specs:
-        opt.set_initial_step(dist_to_bound*gen_specs['dist_to_bound_multiple'])
+    if 'dist_to_bound_multiple' in user_specs:
+        opt.set_initial_step(dist_to_bound*user_specs['dist_to_bound_multiple'])
     else:
         opt.set_initial_step(dist_to_bound)
 
     opt.set_maxeval(len(Run_H)+1)  # evaluate one more point
     opt.set_min_objective(lambda x, grad: nlopt_obj_fun(x, grad, Run_H))
-    if 'xtol_rel' in gen_specs:
-        opt.set_xtol_rel(gen_specs['xtol_rel'])
-    if 'ftol_rel' in gen_specs:
-        opt.set_ftol_rel(gen_specs['ftol_rel'])
-    if 'xtol_abs' in gen_specs:
-        opt.set_xtol_abs(gen_specs['xtol_abs'])
-    if 'ftol_abs' in gen_specs:
-        opt.set_ftol_abs(gen_specs['ftol_abs'])
+    if 'xtol_rel' in user_specs:
+        opt.set_xtol_rel(user_specs['xtol_rel'])
+    if 'ftol_rel' in user_specs:
+        opt.set_ftol_rel(user_specs['ftol_rel'])
+    if 'xtol_abs' in user_specs:
+        opt.set_xtol_abs(user_specs['xtol_abs'])
+    if 'ftol_abs' in user_specs:
+        opt.set_ftol_abs(user_specs['ftol_abs'])
 
     x_opt = opt.optimize(x0)
     exit_code = opt.last_optimize_result()
@@ -648,14 +648,14 @@ def nlopt_obj_fun(x, grad, Run_H):
     return x_opt, exit_code
 
 
-def set_up_and_run_tao(Run_H, gen_specs):
+def set_up_and_run_tao(Run_H, user_specs):
     """ Set up objective and runs PETSc on the comm_self communicator
 
     Declares the appropriate syntax for our special objective function to read
     through Run_H, sets the parameters and starting points for the run.
     """
     tao_comm = MPI.COMM_SELF
-    n = len(gen_specs['ub'])
+    n = len(user_specs['ub'])
 
     def pounders_obj_func(tao, X, F, Run_H):
         F.array = look_in_history(X.array_r, Run_H, vector_return=True)
@@ -676,14 +676,14 @@ def blmvm_obj_func(tao, X, G, Run_H):
     lb.array = 0*np.ones(n)
     ub.array = 1*np.ones(n)
     tao = PETSc.TAO().create(tao_comm)
-    tao.setType(gen_specs['localopt_method'])
+    tao.setType(user_specs['localopt_method'])
 
-    if gen_specs['localopt_method'] == 'pounders':
+    if user_specs['localopt_method'] == 'pounders':
         f = PETSc.Vec().create(tao_comm)
         f.setSizes(len(Run_H['fvec'][0]))
         f.setFromOptions()
 
-        delta_0 = gen_specs['dist_to_bound_multiple']*np.min([np.min(ub.array-x.array), np.min(x.array-lb.array)])
+        delta_0 = user_specs['dist_to_bound_multiple']*np.min([np.min(ub.array-x.array), np.min(x.array-lb.array)])
 
         PETSc.Options().setValue('-tao_pounders_delta', str(delta_0))
 
@@ -693,7 +693,7 @@ def blmvm_obj_func(tao, X, G, Run_H):
         else:
             tao.setSeparableObjective(lambda tao, x, f: pounders_obj_func(tao, x, f, Run_H), f)
 
-    elif gen_specs['localopt_method'] == 'blmvm':
+    elif user_specs['localopt_method'] == 'blmvm':
         g = PETSc.Vec().create(tao_comm)
         g.setSizes(n)
         g.setFromOptions()
@@ -703,9 +703,9 @@ def blmvm_obj_func(tao, X, G, Run_H):
     PETSc.Options().setValue('-tao_max_funcs', str(len(Run_H)+1))
     tao.setFromOptions()
     tao.setVariableBounds((lb, ub))
-    # tao.setObjectiveTolerances(fatol=gen_specs['fatol'], frtol=gen_specs['frtol'])
-    # tao.setGradientTolerances(grtol=gen_specs['grtol'], gatol=gen_specs['gatol'])
-    tao.setTolerances(grtol=gen_specs['grtol'], gatol=gen_specs['gatol'])
+    # tao.setObjectiveTolerances(fatol=user_specs['fatol'], frtol=user_specs['frtol'])
+    # tao.setGradientTolerances(grtol=user_specs['grtol'], gatol=user_specs['gatol'])
+    tao.setTolerances(grtol=user_specs['grtol'], gatol=user_specs['gatol'])
     tao.setInitial(x)
 
     tao.solve(x)
@@ -716,9 +716,9 @@ def blmvm_obj_func(tao, X, G, Run_H):
     # print(tao.view())
     # print(x_opt)
 
-    if gen_specs['localopt_method'] == 'pounders':
+    if user_specs['localopt_method'] == 'pounders':
         f.destroy()
-    if gen_specs['localopt_method'] == 'blmvm':
+    if user_specs['localopt_method'] == 'blmvm':
         g.destroy()
 
     lb.destroy()
@@ -887,7 +887,7 @@ def calc_rk(n, n_s, rk_const, lhs_divisions=0):
     return r_k
 
 
-def initialize_APOSMM(H, gen_specs):
+def initialize_APOSMM(H, user_specs):
     """
     Computes common values every time that APOSMM is reinvoked
 
@@ -895,10 +895,10 @@ def initialize_APOSMM(H, gen_specs):
         ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
     """
 
-    n = len(gen_specs['ub'])
+    n = len(user_specs['ub'])
 
-    if 'single_component_at_a_time' in gen_specs and gen_specs['single_component_at_a_time']:
-        assert gen_specs['batch_mode'], ("Must be in batch mode when using "
+    if 'single_component_at_a_time' in user_specs and user_specs['single_component_at_a_time']:
+        assert user_specs['batch_mode'], ("Must be in batch mode when using "
                                          "'single_component_at_a_time'")
         c_flag = True
     else:
@@ -908,32 +908,32 @@ def initialize_APOSMM(H, gen_specs):
         # Get the pt_id for non-nan, returned points
         pt_ids = H['pt_id'][np.logical_and(H['returned'], ~np.isnan(H['f_i']))]
         _, counts = np.unique(pt_ids, return_counts=True)
-        n_s = np.sum(counts == gen_specs['components'])
+        n_s = np.sum(counts == user_specs['components'])
     else:
         # Number of returned sampled points (excluding nans)
         n_s = np.sum(np.logical_and.reduce((~np.isnan(H['f']), ~H['local_pt'], H['returned'])))
 
     # Rather than build up a large output, we will just make changes in the
     # given H, and then send back the rows corresponding to updated H entries.
-    Out = np.empty(0, dtype=gen_specs['out'])
+    Out = np.empty(0, dtype=user_specs['out'])
 
-    if 'rk_const' in gen_specs:
-        rk_c = gen_specs['rk_const']
+    if 'rk_const' in user_specs:
+        rk_c = user_specs['rk_const']
     else:
         rk_c = ((gamma(1+(n/2.0))*5.0)**(1.0/n))/sqrt(pi)
 
-    if 'lhs_divisions' in gen_specs:
-        ld = gen_specs['lhs_divisions']
+    if 'lhs_divisions' in user_specs:
+        ld = user_specs['lhs_divisions']
     else:
         ld = 0
 
-    if 'mu' in gen_specs:
-        mu = gen_specs['mu']
+    if 'mu' in user_specs:
+        mu = user_specs['mu']
     else:
         mu = 1e-4
 
-    if 'nu' in gen_specs:
-        nu = gen_specs['nu']
+    if 'nu' in user_specs:
+        nu = user_specs['nu']
     else:
         nu = 0
 
diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 9914ce761..13f9d8f40 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -67,7 +67,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
       objective components for a given ``'x'``)
 
     When using libEnsemble to do individual objective component evaluations,
-    APOSMM will return ``gen_specs['components']`` copies of each point, but
+    APOSMM will return ``gen_specs['user']['components']`` copies of each point, but
     the component=0 entry of each point will only be considered when
 
     - deciding where to start a run,
@@ -76,7 +76,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     - storing the combined objective function value
     - etc
 
-    Necessary quantities in ``gen_specs`` are:
+    Necessary quantities in ``gen_specs['user']`` are:
 
     - ``'lb' [n floats]``: Lower bound on search domain
     - ``'ub' [n floats]``: Upper bound on search domain
@@ -86,7 +86,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     - ``'localopt_method' [str]``: Name of an NLopt, PETSc/TAO, or SciPy method
       (see 'advance_local_run' below for supported methods)
 
-    Optional ``gen_specs`` entries are:
+    Optional ``gen_specs['user']`` entries are:
 
     - ``'sample_points' [numpy array]``: Points to be sampled (original domain)
     - ``'combine_component_func' [func]``: Function to combine obj components
@@ -107,7 +107,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     - ``'rk_const' [float]``: Multiplier in front of the r_k value
     - ``'max_active_runs' [int]``: Bound on number of runs APOSMM is advancing
 
-    And ``gen_specs`` convergence tolerances for NLopt, PETSc/TAO, SciPy
+    And ``gen_specs['user']`` convergence tolerances for NLopt, PETSc/TAO, SciPy
 
     - ``'fatol' [float]``:
     - ``'ftol_abs' [float]``:
@@ -133,7 +133,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     (breaking ties arbitrarily).
 
     :Note:
-        ``gen_specs['combine_component_func']`` must be defined when there are
+        ``gen_specs['user']['combine_component_func']`` must be defined when there are
         multiple objective components.
 
     :Note:
@@ -183,29 +183,31 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     persis_info['old_runs']: Sequence of indices of points in finished runs
 
     """
-    n, n_s, rk_const, ld, mu, nu, comm, local_H = initialize_APOSMM(H, gen_specs, libE_info)
+    user_specs = gen_specs['user']
+
+    n, n_s, rk_const, ld, mu, nu, comm, local_H = initialize_APOSMM(H, user_specs, libE_info)
 
     # Initialize stuff for localopt children
     local_opters = {}
     sim_id_to_child_indices = {}
     run_order = {}
     total_runs = 0
-    if gen_specs['localopt_method'] in ['LD_MMA', 'blmvm']:
+    if user_specs['localopt_method'] in ['LD_MMA', 'blmvm']:
         fields_to_pass = ['x_on_cube', 'f', 'grad']
-    elif gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA',
+    elif user_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA',
                                           'LN_NELDERMEAD', 'scipy_Nelder-Mead']:
         fields_to_pass = ['x_on_cube', 'f']
-    elif gen_specs['localopt_method'] in ['pounders']:
+    elif user_specs['localopt_method'] in ['pounders']:
         fields_to_pass = ['x_on_cube', 'fvec']
     else:
-        raise NotImplementedError("Unknown local optimization method " "'{}'.".format(gen_specs['localopt_method']))
+        raise NotImplementedError("Unknown local optimization method " "'{}'.".format(user_specs['localopt_method']))
 
     # Send our initial sample. We don't need to check that n_s is large enough:
     # the alloc_func only returns when the initial sample has function values.
-    persis_info = add_k_sample_points_to_local_H(gen_specs['initial_sample_size'], gen_specs,
+    persis_info = add_k_sample_points_to_local_H(user_specs['initial_sample_size'], user_specs,
                                                  persis_info, n, comm, local_H,
                                                  sim_id_to_child_indices)
-    send_mgr_worker_msg(comm, local_H[:gen_specs['initial_sample_size']][[i[0] for i in gen_specs['out']]])
+    send_mgr_worker_msg(comm, local_H[:user_specs['initial_sample_size']][[i[0] for i in gen_specs['out']]])
 
     tag = None
     while 1:
@@ -215,7 +217,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
             clean_up_and_stop(local_H, local_opters, run_order)
             break
 
-        n_s = update_local_H_after_receiving(local_H, n, n_s, gen_specs, Work, calc_in)
+        n_s = update_local_H_after_receiving(local_H, n, n_s, user_specs, Work, calc_in)
 
         new_opt_inds_to_send_mgr = []
         new_inds_to_send_mgr = []
@@ -230,7 +232,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                         new_opt_inds_to_send_mgr.append(opt_ind)
                         local_opters.pop(child_idx)
                     else:
-                        add_to_local_H(local_H, x_new, gen_specs, local_flag=1, on_cube=True)
+                        add_to_local_H(local_H, x_new, user_specs, local_flag=1, on_cube=True)
                         new_inds_to_send_mgr.append(len(local_H)-1)
 
                         run_order[child_idx].append(local_H[-1]['sim_id'])
@@ -242,11 +244,11 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         starting_inds = decide_where_to_start_localopt(local_H, n, n_s, rk_const, ld, mu, nu)
 
         for ind in starting_inds:
-            if len([p for p in local_opters.values() if p.is_running]) < gen_specs.get('max_active_runs', np.inf):
+            if len([p for p in local_opters.values() if p.is_running]) < user_specs.get('max_active_runs', np.inf):
                 local_H['started_run'][ind] = 1
 
                 # Initialize a local opt run
-                local_opter = LocalOptInterfacer(gen_specs, local_H[ind]['x_on_cube'],
+                local_opter = LocalOptInterfacer(user_specs, local_H[ind]['x_on_cube'],
                                                  local_H[ind]['f'] if 'f' in fields_to_pass else local_H[ind]['fvec'],
                                                  local_H[ind]['grad'] if 'grad' in fields_to_pass else None)
 
@@ -254,7 +256,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
                 x_new = local_opter.iterate(local_H[ind][fields_to_pass])  # Assuming the second point can't be ruled optimal
 
-                add_to_local_H(local_H, x_new, gen_specs, local_flag=1, on_cube=True)
+                add_to_local_H(local_H, x_new, user_specs, local_flag=1, on_cube=True)
                 new_inds_to_send_mgr.append(len(local_H)-1)
 
                 run_order[total_runs] = [ind, local_H[-1]['sim_id']]
@@ -267,7 +269,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
                 total_runs += 1
 
         if len(new_inds_to_send_mgr) == 0:
-            persis_info = add_k_sample_points_to_local_H(1, gen_specs, persis_info, n,
+            persis_info = add_k_sample_points_to_local_H(1, user_specs, persis_info, n,
                                                          comm, local_H, sim_id_to_child_indices)
             new_inds_to_send_mgr.append(len(local_H)-1)
 
@@ -277,7 +279,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
 
 
 class LocalOptInterfacer(object):
-    def __init__(self, gen_specs, x0, f0, grad0=None):
+    def __init__(self, user_specs, x0, f0, grad0=None):
         """
         :param x0: A numpy array of the initial guess solution. This guess
             should be scaled to a unit cube.
@@ -303,17 +305,17 @@ def __init__(self, gen_specs, x0, f0, grad0=None):
 
         # {{{ setting the local optimization method
 
-        if gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA', 'LN_NELDERMEAD', 'LD_MMA']:
+        if user_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA', 'LN_NELDERMEAD', 'LD_MMA']:
             run_local_opt = run_local_nlopt
-        elif gen_specs['localopt_method'] in ['pounders', 'blmvm']:
+        elif user_specs['localopt_method'] in ['pounders', 'blmvm']:
             run_local_opt = run_local_tao
-        elif gen_specs['localopt_method'] in ['scipy_Nelder-Mead']:
+        elif user_specs['localopt_method'] in ['scipy_Nelder-Mead']:
             run_local_opt = run_local_scipy_opt
 
         # }}}
 
         self.parent_can_read.clear()
-        self.process = Process(target=run_local_opt, args=(gen_specs,
+        self.process = Process(target=run_local_opt, args=(user_specs,
                                self.comm_queue, x0, f0, self.child_can_read,
                                self.parent_can_read))
 
@@ -375,15 +377,15 @@ def destroy(self, previous_x):
 
 # {{{ NLOPT for local opt
 
-def nlopt_callback_fun(x, grad, comm_queue, child_can_read, parent_can_read, gen_specs):
+def nlopt_callback_fun(x, grad, comm_queue, child_can_read, parent_can_read, user_specs):
     comm_queue.put(x)
     parent_can_read.set()
     child_can_read.wait()
-    if gen_specs['localopt_method'] in ['LD_MMA']:
+    if user_specs['localopt_method'] in ['LD_MMA']:
         x_recv, f_recv, grad_recv = comm_queue.get()
         grad[:] = grad_recv
     else:
-        assert gen_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA',
+        assert user_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA',
                                                 'LN_COBYLA', 'LN_NELDERMEAD', 'LD_MMA']
         x_recv, f_recv = comm_queue.get()
 
@@ -394,11 +396,11 @@ def nlopt_callback_fun(x, grad, comm_queue, child_can_read, parent_can_read, gen
     return f_recv
 
 
-def run_local_nlopt(gen_specs, comm_queue, x0, f0, child_can_read, parent_can_read):
+def run_local_nlopt(user_specs, comm_queue, x0, f0, child_can_read, parent_can_read):
     # print('[Child]: Started local opt at {}.'.format(x0), flush=True)
-    n = len(gen_specs['ub'])
+    n = len(user_specs['ub'])
 
-    opt = nlopt.opt(getattr(nlopt, gen_specs['localopt_method']), n)
+    opt = nlopt.opt(getattr(nlopt, user_specs['localopt_method']), n)
 
     lb = np.zeros(n)
     ub = np.ones(n)
@@ -409,8 +411,8 @@ def run_local_nlopt(gen_specs, comm_queue, x0, f0, child_can_read, parent_can_re
     dist_to_bound = min(min(ub-x0), min(x0-lb))
     assert dist_to_bound > np.finfo(np.float32).eps, "The distance to the boundary is too small for NLopt to handle"
 
-    if 'dist_to_bound_multiple' in gen_specs:
-        opt.set_initial_step(dist_to_bound*gen_specs['dist_to_bound_multiple'])
+    if 'dist_to_bound_multiple' in user_specs:
+        opt.set_initial_step(dist_to_bound*user_specs['dist_to_bound_multiple'])
     else:
         opt.set_initial_step(dist_to_bound)
 
@@ -419,16 +421,16 @@ def run_local_nlopt(gen_specs, comm_queue, x0, f0, child_can_read, parent_can_re
 
     opt.set_min_objective(lambda x, grad: nlopt_callback_fun(x, grad,
                           comm_queue, child_can_read, parent_can_read,
-                          gen_specs))
+                          user_specs))
 
-    if 'xtol_rel' in gen_specs:
-        opt.set_xtol_rel(gen_specs['xtol_rel'])
-    if 'ftol_rel' in gen_specs:
-        opt.set_ftol_rel(gen_specs['ftol_rel'])
-    if 'xtol_abs' in gen_specs:
-        opt.set_xtol_abs(gen_specs['xtol_abs'])
-    if 'ftol_abs' in gen_specs:
-        opt.set_ftol_abs(gen_specs['ftol_abs'])
+    if 'xtol_rel' in user_specs:
+        opt.set_xtol_rel(user_specs['xtol_rel'])
+    if 'ftol_rel' in user_specs:
+        opt.set_ftol_rel(user_specs['ftol_rel'])
+    if 'xtol_abs' in user_specs:
+        opt.set_xtol_abs(user_specs['xtol_abs'])
+    if 'ftol_abs' in user_specs:
+        opt.set_ftol_abs(user_specs['ftol_abs'])
 
     # FIXME: Do we need to do something of the final 'x_opt'?
     # print('[Child]: Started my optimization', flush=True)
@@ -442,7 +444,7 @@ def run_local_nlopt(gen_specs, comm_queue, x0, f0, child_can_read, parent_can_re
 
 # {{{ SciPy optimization
 
-def scipy_callback_fun(x, comm_queue, child_can_read, parent_can_read, gen_specs):
+def scipy_callback_fun(x, comm_queue, child_can_read, parent_can_read, user_specs):
     comm_queue.put(x)
     # print('[Child]: Parent should no longer wait.', flush=True)
     parent_can_read.set()
@@ -456,23 +458,23 @@ def scipy_callback_fun(x, comm_queue, child_can_read, parent_can_read, gen_specs
     return f_x_recv
 
 
-def run_local_scipy_opt(gen_specs, comm_queue, x0, f0, child_can_read, parent_can_read):
+def run_local_scipy_opt(user_specs, comm_queue, x0, f0, child_can_read, parent_can_read):
 
     # Construct the bounds in the form of constraints
     cons = []
     for factor in range(len(x0)):
         lo = {'type': 'ineq',
-              'fun': lambda x, lb=gen_specs['lb'][factor], i=factor: x[i]-lb}
+              'fun': lambda x, lb=user_specs['lb'][factor], i=factor: x[i]-lb}
         up = {'type': 'ineq',
-              'fun': lambda x, ub=gen_specs['ub'][factor], i=factor: ub-x[i]}
+              'fun': lambda x, ub=user_specs['ub'][factor], i=factor: ub-x[i]}
         cons.append(lo)
         cons.append(up)
 
-    method = gen_specs['localopt_method'][6:]
+    method = user_specs['localopt_method'][6:]
     # print('[Child]: Started my optimization', flush=True)
     res = sp_opt.minimize(lambda x: scipy_callback_fun(x, comm_queue,
-                          child_can_read, parent_can_read, gen_specs), x0,
-                          method=method, options={'maxiter': 10, 'fatol': gen_specs['fatol'], 'xatol': gen_specs['xatol']})
+                          child_can_read, parent_can_read, user_specs), x0,
+                          method=method, options={'maxiter': 10, 'fatol': user_specs['fatol'], 'xatol': user_specs['xatol']})
 
     # if res['status'] == 2:  # SciPy code for exhausting budget of evaluations, so not at a minimum
     #     exit_code = 0
@@ -495,7 +497,7 @@ def run_local_scipy_opt(gen_specs, comm_queue, x0, f0, child_can_read, parent_ca
 
 # {{{ TAO routines for local opt
 
-def tao_callback_fun(tao, x, f, comm_queue, child_can_read, parent_can_read, gen_specs):
+def tao_callback_fun(tao, x, f, comm_queue, child_can_read, parent_can_read, user_specs):
     comm_queue.put(x.array_r)
     # print('[Child]: I just put x_on_cube =', x.array, flush=True)
     # print('[Child]: Parent should no longer wait.', flush=True)
@@ -512,7 +514,7 @@ def tao_callback_fun(tao, x, f, comm_queue, child_can_read, parent_can_read, gen
     return f
 
 
-def tao_callback_fun_grad(tao, x, g, comm_queue, child_can_read, parent_can_read, gen_specs):
+def tao_callback_fun_grad(tao, x, g, comm_queue, child_can_read, parent_can_read, user_specs):
 
     comm_queue.put(x.array_r)
     # print('[Child]: I just put x_on_cube =', x.array, flush=True)
@@ -530,7 +532,7 @@ def tao_callback_fun_grad(tao, x, g, comm_queue, child_can_read, parent_can_read
     return f_recv
 
 
-def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read, parent_can_read):
+def run_local_tao(user_specs, comm_queue, x0, f0, child_can_read, parent_can_read):
 
     assert isinstance(x0, np.ndarray)
 
@@ -551,25 +553,25 @@ def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read, parent_can_read
     lb.array = 0*np.ones(n)
     ub.array = 1*np.ones(n)
     tao = PETSc.TAO().create(tao_comm)
-    tao.setType(gen_specs['localopt_method'])
+    tao.setType(user_specs['localopt_method'])
 
-    if gen_specs['localopt_method'] == 'pounders':
+    if user_specs['localopt_method'] == 'pounders':
         f = PETSc.Vec().create(tao_comm)
         f.setSizes(m)
         f.setFromOptions()
 
         if hasattr(tao, 'setResidual'):
-            tao.setResidual(lambda tao, x, f: tao_callback_fun(tao, x, f, comm_queue, child_can_read, parent_can_read, gen_specs), f)
+            tao.setResidual(lambda tao, x, f: tao_callback_fun(tao, x, f, comm_queue, child_can_read, parent_can_read, user_specs), f)
         else:
-            tao.setSeparableObjective(lambda tao, x, f: tao_callback_fun(tao, x, f, comm_queue, child_can_read, parent_can_read, gen_specs), f)
+            tao.setSeparableObjective(lambda tao, x, f: tao_callback_fun(tao, x, f, comm_queue, child_can_read, parent_can_read, user_specs), f)
 
-    elif gen_specs['localopt_method'] == 'blmvm':
+    elif user_specs['localopt_method'] == 'blmvm':
         g = PETSc.Vec().create(tao_comm)
         g.setSizes(n)
         g.setFromOptions()
-        tao.setObjectiveGradient(lambda tao, x, g: tao_callback_fun_grad(tao, x, g, comm_queue, child_can_read, parent_can_read, gen_specs))
+        tao.setObjectiveGradient(lambda tao, x, g: tao_callback_fun_grad(tao, x, g, comm_queue, child_can_read, parent_can_read, user_specs))
 
-    delta_0 = gen_specs['dist_to_bound_multiple']*np.min([np.min(ub.array-x.array), np.min(x.array-lb.array)])
+    delta_0 = user_specs['dist_to_bound_multiple']*np.min([np.min(ub.array-x.array), np.min(x.array-lb.array)])
     PETSc.Options().setValue('-tao_pounders_delta', str(delta_0))
 
     # Set everything for tao before solving
@@ -578,9 +580,9 @@ def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read, parent_can_read
     PETSc.Options().setValue('-tao_max_funcs', '100')
     tao.setFromOptions()
     tao.setVariableBounds((lb, ub))
-    # tao.setObjectiveTolerances(fatol=gen_specs['fatol'], frtol=gen_specs['frtol'])
-    # tao.setGradientTolerances(grtol=gen_specs['grtol'], gatol=gen_specs['gatol'])
-    tao.setTolerances(grtol=gen_specs['grtol'], gatol=gen_specs['gatol'])
+    # tao.setObjectiveTolerances(fatol=user_specs['fatol'], frtol=user_specs['frtol'])
+    # tao.setGradientTolerances(grtol=user_specs['grtol'], gatol=user_specs['gatol'])
+    tao.setTolerances(grtol=user_specs['grtol'], gatol=user_specs['gatol'])
     tao.setInitial(x)
 
     # print('[Child]: Started my optimization', flush=True)
@@ -594,9 +596,9 @@ def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read, parent_can_read
     # print(tao.view())
     # print(x_opt)
 
-    if gen_specs['localopt_method'] == 'pounders':
+    if user_specs['localopt_method'] == 'pounders':
         f.destroy()
-    elif gen_specs['localopt_method'] == 'blmvm':
+    elif user_specs['localopt_method'] == 'blmvm':
         g.destroy()
 
     lb.destroy()
@@ -614,7 +616,7 @@ def run_local_tao(gen_specs, comm_queue, x0, f0, child_can_read, parent_can_read
 # }}}
 
 
-def update_local_H_after_receiving(local_H, n, n_s, gen_specs, Work, calc_in):
+def update_local_H_after_receiving(local_H, n, n_s, user_specs, Work, calc_in):
 
     for name in calc_in.dtype.names:
         local_H[name][Work['libE_info']['H_rows']] = calc_in[name]
@@ -623,12 +625,12 @@ def update_local_H_after_receiving(local_H, n, n_s, gen_specs, Work, calc_in):
     n_s += np.sum(~local_H[Work['libE_info']['H_rows']]['local_pt'])
 
     # dist -> distance
-    update_history_dist(local_H, n, gen_specs)
+    update_history_dist(local_H, n)
 
     return n_s
 
 
-def add_to_local_H(local_H, pts, gen_specs, local_flag=0, sorted_run_inds=[], run=[], on_cube=True):
+def add_to_local_H(local_H, pts, user_specs, local_flag=0, sorted_run_inds=[], run=[], on_cube=True):
     """
     Adds points to O, the numpy structured array to be sent back to the manager
     """
@@ -636,8 +638,8 @@ def add_to_local_H(local_H, pts, gen_specs, local_flag=0, sorted_run_inds=[], ru
 
     len_local_H = len(local_H)
 
-    ub = gen_specs['ub']
-    lb = gen_specs['lb']
+    ub = user_specs['ub']
+    lb = user_specs['lb']
 
     num_pts = len(pts)
 
@@ -665,7 +667,7 @@ def add_to_local_H(local_H, pts, gen_specs, local_flag=0, sorted_run_inds=[], ru
         local_H['priority'][-num_pts:] = 1
 
 
-def update_history_dist(H, n, gen_specs):
+def update_history_dist(H, n):
     """
     Updates distances/indices after new points that have been evaluated.
 
@@ -889,34 +891,34 @@ def calc_rk(n, n_s, rk_const, lhs_divisions=0):
     return r_k
 
 
-def initialize_APOSMM(H, gen_specs, libE_info):
+def initialize_APOSMM(H, user_specs, libE_info):
     """
     Computes common values every time that APOSMM is reinvoked
 
     :See:
         ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
     """
-    n = len(gen_specs['ub'])
+    n = len(user_specs['ub'])
 
     n_s = 0
 
-    if 'rk_const' in gen_specs:
-        rk_c = gen_specs['rk_const']
+    if 'rk_const' in user_specs:
+        rk_c = user_specs['rk_const']
     else:
         rk_c = ((gamma(1+(n/2.0))*5.0)**(1.0/n))/sqrt(pi)
 
-    if 'lhs_divisions' in gen_specs:
-        ld = gen_specs['lhs_divisions']
+    if 'lhs_divisions' in user_specs:
+        ld = user_specs['lhs_divisions']
     else:
         ld = 0
 
-    if 'mu' in gen_specs:
-        mu = gen_specs['mu']
+    if 'mu' in user_specs:
+        mu = user_specs['mu']
     else:
         mu = 1e-4
 
-    if 'nu' in gen_specs:
-        nu = gen_specs['nu']
+    if 'nu' in user_specs:
+        nu = user_specs['nu']
     else:
         nu = 0
 
@@ -942,27 +944,27 @@ def initialize_APOSMM(H, gen_specs, libE_info):
                       ('returned', bool),
                       ]
 
-    if 'components' in gen_specs:
-        local_H_fields += [('fvec', float, gen_specs['components'])]
+    if 'components' in user_specs:
+        local_H_fields += [('fvec', float, user_specs['components'])]
 
     local_H = np.empty(0, dtype=local_H_fields)
 
     return n, n_s, rk_c, ld, mu, nu, comm, local_H
 
 
-def add_k_sample_points_to_local_H(k, gen_specs, persis_info, n, comm, local_H, sim_id_to_child_indices):
+def add_k_sample_points_to_local_H(k, user_specs, persis_info, n, comm, local_H, sim_id_to_child_indices):
 
-    if 'sample_points' in gen_specs:
+    if 'sample_points' in user_specs:
         v = np.sum(~local_H['local_pt'])  # Number of sample points so far
-        sampled_points = gen_specs['sample_points'][v:v+k]
+        sampled_points = user_specs['sample_points'][v:v+k]
         on_cube = False  # Assume points are on original domain, not unit cube
         if len(sampled_points):
-            add_to_local_H(local_H, sampled_points, gen_specs, on_cube=on_cube)
+            add_to_local_H(local_H, sampled_points, user_specs, on_cube=on_cube)
         k = k-len(sampled_points)
 
     if k > 0:
         sampled_points = persis_info['rand_stream'].uniform(0, 1, (k, n))
-        add_to_local_H(local_H, sampled_points, gen_specs, on_cube=True)
+        add_to_local_H(local_H, sampled_points, user_specs, on_cube=True)
 
     return persis_info
 
diff --git a/libensemble/gen_funcs/persistent_inverse_bayes.py b/libensemble/gen_funcs/persistent_inverse_bayes.py
index fafb67079..1e8e3096e 100644
--- a/libensemble/gen_funcs/persistent_inverse_bayes.py
+++ b/libensemble/gen_funcs/persistent_inverse_bayes.py
@@ -7,12 +7,12 @@
 def persistent_updater_after_likelihood(H, persis_info, gen_specs, libE_info):
     """
     """
-    ub = gen_specs['ub']
-    lb = gen_specs['lb']
+    ub = gen_specs['user']['ub']
+    lb = gen_specs['user']['lb']
     n = len(lb)
     comm = libE_info['comm']
-    subbatch_size = gen_specs['subbatch_size']
-    num_subbatches = gen_specs['num_subbatches']
+    subbatch_size = gen_specs['user']['subbatch_size']
+    num_subbatches = gen_specs['user']['num_subbatches']
 
     # Receive information from the manager (or a STOP_TAG)
     batch = -1
diff --git a/libensemble/gen_funcs/persistent_uniform_sampling.py b/libensemble/gen_funcs/persistent_uniform_sampling.py
index 3d13916a9..ed51ec599 100644
--- a/libensemble/gen_funcs/persistent_uniform_sampling.py
+++ b/libensemble/gen_funcs/persistent_uniform_sampling.py
@@ -12,10 +12,10 @@ def persistent_uniform(H, persis_info, gen_specs, libE_info):
     :See:
         ``libensemble/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py``
     """
-    ub = gen_specs['ub']
-    lb = gen_specs['lb']
+    ub = gen_specs['user']['ub']
+    lb = gen_specs['user']['lb']
     n = len(lb)
-    b = gen_specs['gen_batch_size']
+    b = gen_specs['user']['gen_batch_size']
     comm = libE_info['comm']
 
     # Send batches until manager sends stop tag
diff --git a/libensemble/gen_funcs/sampling.py b/libensemble/gen_funcs/sampling.py
index 74431fc94..bc045edbe 100644
--- a/libensemble/gen_funcs/sampling.py
+++ b/libensemble/gen_funcs/sampling.py
@@ -8,19 +8,19 @@
 
 def uniform_random_sample_with_different_nodes_and_ranks(H, persis_info, gen_specs, _):
     """
-    Generates points uniformly over the domain defined by ``gen_specs['ub']`` and
-    ``gen_specs['lb']``. Also randomly requests a different ``number_of_nodes``
+    Generates points uniformly over the domain defined by ``gen_specs['user']['ub']`` and
+    ``gen_specs['user']['lb']``. Also randomly requests a different ``number_of_nodes``
     and ``ranks_per_node`` to be used in the evaluation of the generated point.
 
     :See:
         ``libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py``
     """
-    ub = gen_specs['ub']
-    lb = gen_specs['lb']
+    ub = gen_specs['user']['ub']
+    lb = gen_specs['user']['lb']
     n = len(lb)
 
     if len(H) == 0:
-        b = gen_specs['initial_batch_size']
+        b = gen_specs['user']['initial_batch_size']
 
         O = np.zeros(b, dtype=gen_specs['out'])
         for i in range(0, b):
@@ -33,8 +33,8 @@ def uniform_random_sample_with_different_nodes_and_ranks(H, persis_info, gen_spe
     else:
         O = np.zeros(1, dtype=gen_specs['out'])
         O['x'] = len(H)*np.ones(n)
-        O['num_nodes'] = np.random.randint(1, gen_specs['max_num_nodes']+1)
-        O['ranks_per_node'] = np.random.randint(1, gen_specs['max_ranks_per_node']+1)
+        O['num_nodes'] = np.random.randint(1, gen_specs['user']['max_num_nodes']+1)
+        O['ranks_per_node'] = np.random.randint(1, gen_specs['user']['max_ranks_per_node']+1)
         O['priority'] = 10*O['num_nodes']
 
     return O, persis_info
@@ -42,19 +42,19 @@ def uniform_random_sample_with_different_nodes_and_ranks(H, persis_info, gen_spe
 
 def uniform_random_sample_obj_components(H, persis_info, gen_specs, _):
     """
-    Generates points uniformly over the domain defined by ``gen_specs['ub']``
-    and ``gen_specs['lb']`` but requests each ``obj_component`` be evaluated
+    Generates points uniformly over the domain defined by ``gen_specs['user']['ub']``
+    and ``gen_specs['user']['lb']`` but requests each ``obj_component`` be evaluated
     separately.
 
     :See:
         ``libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py``
     """
-    ub = gen_specs['ub']
-    lb = gen_specs['lb']
+    ub = gen_specs['user']['ub']
+    lb = gen_specs['user']['lb']
 
     n = len(lb)
-    m = gen_specs['components']
-    b = gen_specs['gen_batch_size']
+    m = gen_specs['user']['components']
+    b = gen_specs['user']['gen_batch_size']
 
     O = np.zeros(b*m, dtype=gen_specs['out'])
     for i in range(0, b):
@@ -71,17 +71,17 @@ def uniform_random_sample_obj_components(H, persis_info, gen_specs, _):
 
 def uniform_random_sample(H, persis_info, gen_specs, _):
     """
-    Generates ``gen_specs['gen_batch_size']`` points uniformly over the domain
-    defined by ``gen_specs['ub']`` and ``gen_specs['lb']``.
+    Generates ``gen_specs['user']['gen_batch_size']`` points uniformly over the domain
+    defined by ``gen_specs['user']['ub']`` and ``gen_specs['user']['lb']``.
 
     :See:
         ``libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py``
     """
-    ub = gen_specs['ub']
-    lb = gen_specs['lb']
+    ub = gen_specs['user']['ub']
+    lb = gen_specs['user']['lb']
 
     n = len(lb)
-    b = gen_specs['gen_batch_size']
+    b = gen_specs['user']['gen_batch_size']
 
     O = np.zeros(b, dtype=gen_specs['out'])
 
@@ -92,15 +92,15 @@ def uniform_random_sample(H, persis_info, gen_specs, _):
 
 def latin_hypercube_sample(H, persis_info, gen_specs, _):
     """
-    Generates ``gen_specs['gen_batch_size']`` in a Latin hypercube sample over
-    the domain defined by ``gen_specs['ub']`` and ``gen_specs['lb']``.
+    Generates ``gen_specs['user']['gen_batch_size']`` in a Latin hypercube sample over
+    the domain defined by ``gen_specs['user']['ub']`` and ``gen_specs['user']['lb']``.
     """
 
-    ub = gen_specs['ub']
-    lb = gen_specs['lb']
+    ub = gen_specs['user']['ub']
+    lb = gen_specs['user']['lb']
 
     n = len(lb)
-    b = gen_specs['gen_batch_size']
+    b = gen_specs['user']['gen_batch_size']
 
     O = np.zeros(b, dtype=gen_specs['out'])
 
diff --git a/libensemble/gen_funcs/uniform_or_localopt.py b/libensemble/gen_funcs/uniform_or_localopt.py
index 7c6950634..53342f15c 100644
--- a/libensemble/gen_funcs/uniform_or_localopt.py
+++ b/libensemble/gen_funcs/uniform_or_localopt.py
@@ -10,7 +10,7 @@
 
 def uniform_or_localopt(H, persis_info, gen_specs, libE_info):
     """
-    This generation function returns ``gen_specs['gen_batch_size']`` uniformly
+    This generation function returns ``gen_specs['user']['gen_batch_size']`` uniformly
     sampled points when called in nonpersistent mode (i.e., when
     ``libE_info['persistent']`` isn't ``True``).  Otherwise, the generation
     function a persistent nlopt local optimization run.
@@ -24,10 +24,10 @@ def uniform_or_localopt(H, persis_info, gen_specs, libE_info):
         O = []
         return O, persis_info_updates, tag_out
     else:
-        ub = gen_specs['ub']
-        lb = gen_specs['lb']
+        ub = gen_specs['user']['ub']
+        lb = gen_specs['user']['lb']
         n = len(lb)
-        b = gen_specs['gen_batch_size']
+        b = gen_specs['user']['gen_batch_size']
 
         O = np.zeros(b, dtype=gen_specs['out'])
         for i in range(0, b):
@@ -50,43 +50,43 @@ def nlopt_obj_fun(x, grad):
 
         # Check if we can do an early return
         if np.array_equiv(x, H['x']):
-            if gen_specs['localopt_method'] in ['LD_MMA']:
+            if gen_specs['user']['localopt_method'] in ['LD_MMA']:
                 grad[:] = H['grad']
             return np.float(H['f'])
 
         # Send back x to the manager, then receive info or stop tag
         O = add_to_O(np.zeros(1, dtype=gen_specs['out']), x, 0,
-                     gen_specs['ub'], gen_specs['lb'], local=True, active=True)
+                     gen_specs['user']['ub'], gen_specs['user']['lb'], local=True, active=True)
         tag, Work, calc_in = sendrecv_mgr_worker_msg(comm, O)
         if tag in [STOP_TAG, PERSIS_STOP]:
             nlopt.forced_stop.message = 'tag=' + str(tag)
             raise nlopt.forced_stop
 
         # Return function value (and maybe gradient)
-        if gen_specs['localopt_method'] in ['LD_MMA']:
+        if gen_specs['user']['localopt_method'] in ['LD_MMA']:
             grad[:] = calc_in['grad']
         return float(calc_in['f'])
 
     # ---------------------------------------------------------------------
 
     x0 = H['x'].flatten()
-    lb = gen_specs['lb']
-    ub = gen_specs['ub']
+    lb = gen_specs['user']['lb']
+    ub = gen_specs['user']['ub']
     n = len(ub)
 
-    opt = nlopt.opt(getattr(nlopt, gen_specs['localopt_method']), n)
+    opt = nlopt.opt(getattr(nlopt, gen_specs['user']['localopt_method']), n)
     opt.set_lower_bounds(lb)
     opt.set_upper_bounds(ub)
 
     # Care must be taken with NLopt because a too-large initial step causes
     # nlopt to move the starting point!
     dist_to_bound = min(min(ub-x0), min(x0-lb))
-    init_step = dist_to_bound*gen_specs.get('dist_to_bound_multiple', 1)
+    init_step = dist_to_bound*gen_specs['user'].get('dist_to_bound_multiple', 1)
     opt.set_initial_step(init_step)
 
-    opt.set_maxeval(gen_specs.get('localopt_maxeval', 100*n))
+    opt.set_maxeval(gen_specs['user'].get('localopt_maxeval', 100*n))
     opt.set_min_objective(nlopt_obj_fun)
-    opt.set_xtol_rel(gen_specs['xtol_rel'])
+    opt.set_xtol_rel(gen_specs['user']['xtol_rel'])
 
     # Run local optimization.  Only send persis_info_updates back so new
     # information added to persis_info since this persistent instance started

From b0d9a9944ed2c72ba94729ab23a80148790289cc Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 30 Oct 2019 14:20:45 -0500
Subject: [PATCH 374/644] Moving all user references in alloc_funcs to
 gen_specs['user'] or alloc_specs['user']

---
 libensemble/alloc_funcs/fast_alloc.py         |  4 ++--
 .../alloc_funcs/fast_alloc_and_pausing.py     | 20 +++++++++----------
 .../alloc_funcs/fast_alloc_to_aposmm.py       |  6 +++---
 .../alloc_funcs/give_sim_work_first.py        | 10 +++++-----
 .../alloc_funcs/inverse_bayes_allocf.py       |  2 +-
 .../alloc_funcs/persistent_aposmm_alloc.py    |  2 +-
 .../start_persistent_local_opt_gens.py        |  4 ++--
 7 files changed, 24 insertions(+), 24 deletions(-)

diff --git a/libensemble/alloc_funcs/fast_alloc.py b/libensemble/alloc_funcs/fast_alloc.py
index 4919e9f98..dd7322a57 100644
--- a/libensemble/alloc_funcs/fast_alloc.py
+++ b/libensemble/alloc_funcs/fast_alloc.py
@@ -7,7 +7,7 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     to evaluate in the simulation function. The fields in ``sim_specs['in']``
     are given. If all entries in `H` have been given a be evaluated, a worker
     is told to call the generator function, provided this wouldn't result in
-    more than ``gen_specs['num_active_gen']`` active generators.
+    more than ``gen_specs['user']['num_active_gen']`` active generators.
 
     :See:
         ``/libensemble/tests/regression_tests/test_fast_alloc.py``
@@ -23,7 +23,7 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
             sim_work(Work, i, sim_specs['in'], [persis_info['next_to_give']], [])
             persis_info['next_to_give'] += 1
 
-        elif gen_count < gen_specs.get('num_active_gens', gen_count+1):
+        elif gen_count < gen_specs['user'].get('num_active_gens', gen_count+1):
 
             # Give gen work
             persis_info['total_gen_calls'] += 1
diff --git a/libensemble/alloc_funcs/fast_alloc_and_pausing.py b/libensemble/alloc_funcs/fast_alloc_and_pausing.py
index 9b116fc61..f1cfea0d9 100644
--- a/libensemble/alloc_funcs/fast_alloc_and_pausing.py
+++ b/libensemble/alloc_funcs/fast_alloc_and_pausing.py
@@ -9,16 +9,16 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     to evaluate in the simulation function. The fields in ``sim_specs['in']``
     are given. If all entries in `H` have been given a be evaluated, a worker
     is told to call the generator function, provided this wouldn't result in
-    more than ``gen_specs['num_active_gen']`` active generators. Also allows
+    more than ``gen_specs['user']['num_active_gen']`` active generators. Also allows
     for a 'batch_mode'.
 
     When there are multiple objective components, this allocation function
     does not evaluate further components for some point in the following
     scenarios:
 
-    alloc_specs['stop_on_NaNs']: True --- after a NaN has been found in returned in some
+    alloc_specs['user']['stop_on_NaNs']: True --- after a NaN has been found in returned in some
         objective component
-    allocated['stop_partial_fvec_eval']: True --- after the value returned from
+    alloc_specs['user']['stop_partial_fvec_eval']: True --- after the value returned from
         combine_component_func is larger than a known upper bound on the objective.
 
     :See:
@@ -46,14 +46,14 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
         if len(persis_info['need_to_give']):
             # If 'stop_on_NaN' is true and any f_i is a NaN, then pause
             # evaluations of other f_i, corresponding to the same pt_id
-            if 'stop_on_NaNs' in alloc_specs and alloc_specs['stop_on_NaNs']:
+            if alloc_specs['user'].get('stop_on_NaNs'):
                 pt_ids_to_pause.update(H['pt_id'][np.isnan(H['f_i'])])
 
             # If 'stop_partial_fvec_eval' is true, pause entries in H if a
             # partial combine_component_func evaluation is # worse than the
             # best, known, complete evaluation (and the point is not a
             # local_pt).
-            if 'stop_partial_fvec_eval' in alloc_specs and alloc_specs['stop_partial_fvec_eval']:
+            if alloc_specs['user'].get(['stop_partial_fvec_eval']):
                 pt_ids = set(persis_info['pt_ids']) - persis_info['has_nan'] - persis_info['complete']
                 pt_ids = np.array(list(pt_ids))
                 partial_fvals = np.zeros(len(pt_ids))
@@ -71,11 +71,11 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
 
                     if np.all(H['returned'][a1]):
                         persis_info['complete'].add(pt_id)
-                        persis_info['best_complete_val'] = min(persis_info['best_complete_val'], gen_specs['combine_component_func'](H['f_i'][a1]))
+                        persis_info['best_complete_val'] = min(persis_info['best_complete_val'], gen_specs['user']['combine_component_func'](H['f_i'][a1]))
                     else:
                         # Ensure combine_component_func calculates partial fevals correctly
                         # with H['f_i'] = 0 for non-returned point
-                        partial_fvals[j] = gen_specs['combine_component_func'](H['f_i'][a1])
+                        partial_fvals[j] = gen_specs['user']['combine_component_func'](H['f_i'][a1])
 
                 if len(persis_info['complete']) and len(pt_ids) > 1:
 
@@ -102,13 +102,13 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
                 i, idle_workers = idle_workers[0], idle_workers[1:]
                 sim_work(Work, i, sim_specs['in'], [next_row], [])
 
-        elif gen_count < gen_specs.get('num_active_gens', gen_count+1):
+        elif gen_count < gen_specs['user'].get('num_active_gens', gen_count+1):
             lw = persis_info['last_worker']
 
             last_size = persis_info.get('last_size')
             if len(H):
                 # Don't give gen instances in batch mode if points are unfinished
-                if (gen_specs.get('batch_mode')
+                if (gen_specs['user'].get('batch_mode')
                     and not all(np.logical_or(H['returned'][last_size:],
                                               H['paused'][last_size:]))):
                     break
@@ -131,7 +131,7 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
 
             persis_info['last_worker'] = i
 
-        elif gen_count >= gen_specs.get('num_active_gens', gen_count+1):
+        elif gen_count >= gen_specs['user'].get('num_active_gens', gen_count+1):
             idle_workers = []
 
     return Work, persis_info
diff --git a/libensemble/alloc_funcs/fast_alloc_to_aposmm.py b/libensemble/alloc_funcs/fast_alloc_to_aposmm.py
index 47119e73d..8ee694c62 100644
--- a/libensemble/alloc_funcs/fast_alloc_to_aposmm.py
+++ b/libensemble/alloc_funcs/fast_alloc_to_aposmm.py
@@ -9,7 +9,7 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     to evaluate in the simulation function. The fields in ``sim_specs['in']``
     are given. If all entries in `H` have been given a be evaluated, a worker
     is told to call the generator function, provided this wouldn't result in
-    more than ``gen_specs['num_active_gen']`` active generators. Also allows
+    more than ``gen_specs['user']['num_active_gen']`` active generators. Also allows
     for a 'batch_mode'.
 
     :See:
@@ -27,13 +27,13 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
             sim_work(Work, i, sim_specs['in'], [persis_info['next_to_give']], [])
             persis_info['next_to_give'] += 1
 
-        elif gen_count < gen_specs.get('num_active_gens', gen_count+1):
+        elif gen_count < gen_specs['user'].get('num_active_gens', gen_count+1):
             lw = persis_info['last_worker']
 
             last_size = persis_info.get('last_size')
             if len(H):
                 # Don't give gen instances in batch mode if points are unfinished
-                if (gen_specs.get('batch_mode')
+                if (gen_specs['user'].get('batch_mode')
                     and not all(np.logical_or(H['returned'][last_size:],
                                               H['paused'][last_size:]))):
                     break
diff --git a/libensemble/alloc_funcs/give_sim_work_first.py b/libensemble/alloc_funcs/give_sim_work_first.py
index 6b2f9d78b..90bbdd6d8 100644
--- a/libensemble/alloc_funcs/give_sim_work_first.py
+++ b/libensemble/alloc_funcs/give_sim_work_first.py
@@ -7,10 +7,10 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     """
     Decide what should be given to workers. This allocation function gives any
     available simulation work first, and only when all simulations are
-    completed or running does it start (at most ``gen_specs['num_active_gens']``)
+    completed or running does it start (at most ``gen_specs['user']['num_active_gens']``)
     generator instances.
 
-    Allows for a ``gen_specs['batch_mode']`` where no generation
+    Allows for a ``gen_specs['user']['batch_mode']`` where no generation
     work is given out unless all entries in ``H`` are returned.
 
     Allows for ``blocking`` of workers that are not active, for example, so
@@ -39,7 +39,7 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
             # Pick all high priority, oldest high priority, or just oldest point
             if 'priority' in H.dtype.fields:
                 priorities = H['priority'][~H['allocated']]
-                if gen_specs.get('give_all_with_same_priority'):
+                if gen_specs['user'].get('give_all_with_same_priority'):
                     q_inds = (priorities == np.max(priorities))
                 else:
                     q_inds = np.argmax(priorities)
@@ -68,12 +68,12 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
         else:
 
             # Allow at most num_active_gens active generator instances
-            if gen_count >= gen_specs.get('num_active_gens', gen_count+1):
+            if gen_count >= gen_specs['user'].get('num_active_gens', gen_count+1):
                 break
 
             # No gen instances in batch mode if workers still working
             still_working = ~H['returned']
-            if gen_specs.get('batch_mode') and np.any(still_working):
+            if gen_specs['user'].get('batch_mode') and np.any(still_working):
                 break
 
             # Give gen work
diff --git a/libensemble/alloc_funcs/inverse_bayes_allocf.py b/libensemble/alloc_funcs/inverse_bayes_allocf.py
index 668cc19a9..05b0133a4 100644
--- a/libensemble/alloc_funcs/inverse_bayes_allocf.py
+++ b/libensemble/alloc_funcs/inverse_bayes_allocf.py
@@ -32,7 +32,7 @@ def only_persistent_gens_for_inverse_bayes(W, H, sim_specs, gen_specs, alloc_spe
             inds_to_send_back = np.where(np.logical_and(inds_generated_by_i,
                                                         last_batch_inds))[0]
             if H['batch'][-1] > 0:
-                n = gen_specs['subbatch_size']*gen_specs['num_subbatches']
+                n = gen_specs['user']['subbatch_size']*gen_specs['user']['num_subbatches']
                 k = H['batch'][-1]
                 H['weight'][(n*(k-1)):(n*k)] = H['weight'][(n*k):(n*(k+1))]
 
diff --git a/libensemble/alloc_funcs/persistent_aposmm_alloc.py b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
index 3a3035e2d..df0586274 100644
--- a/libensemble/alloc_funcs/persistent_aposmm_alloc.py
+++ b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
@@ -23,7 +23,7 @@ def persistent_aposmm_alloc(W, H, sim_specs, gen_specs, alloc_specs, persis_info
 
     # If any persistent worker's calculated values have returned, give them back.
     for i in avail_worker_ids(W, persistent=True):
-        if persis_info.get('sample_done') or sum(H['returned']) >= gen_specs['initial_sample_size']:
+        if persis_info.get('sample_done') or sum(H['returned']) >= gen_specs['user']['initial_sample_size']:
             # Don't return if the initial sample is not complete
             persis_info['sample_done'] = True
 
diff --git a/libensemble/alloc_funcs/start_persistent_local_opt_gens.py b/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
index 3a0bbe0a3..13ef1931d 100644
--- a/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
+++ b/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
@@ -54,8 +54,8 @@ def start_persistent_local_opt_gens(W, H, sim_specs, gen_specs, alloc_specs, per
     for i in avail_worker_ids(W, persistent=False):
         # Find candidates to start local opt runs if a sample has been evaluated
         if np.any(np.logical_and(~H['local_pt'], H['returned'])):
-            n, _, _, _, r_k, mu, nu = initialize_APOSMM(H, gen_specs)
-            update_history_dist(H, n, gen_specs, c_flag=False)
+            n, _, _, _, r_k, mu, nu = initialize_APOSMM(H, gen_specs['user'])
+            update_history_dist(H, n, gen_specs['user'], c_flag=False)
             starting_inds = decide_where_to_start_localopt(H, r_k, mu, nu)
         else:
             starting_inds = []

From 40abfb8fe72cdaea44109f1175ef3a8bf5d20919 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 30 Oct 2019 16:12:02 -0500
Subject: [PATCH 375/644] Starting list of allowable keys to gen_, sim_, and
 alloc_specs

---
 libensemble/libE.py | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/libensemble/libE.py b/libensemble/libE.py
index 9b5cb0e3c..6a78051bd 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -29,6 +29,9 @@
 # To change logging level for just this module
 # logger.setLevel(logging.DEBUG)
 
+allowed_sim_spec_keys = ['sim_f', 'in', 'out', 'save_every_k', 'user']
+allowed_gen_spec_keys = ['gen_f', 'in', 'out', 'save_every_k', 'user']
+allowed_alloc_spec_keys = ['alloc_f', 'in', 'out', 'user']
 
 def report_manager_exception(hist, persis_info, mgr_exc=None):
     "Write out exception manager exception to log."
@@ -477,6 +480,9 @@ def check_alloc_specs(alloc_specs):
     assert isinstance(alloc_specs, dict), "alloc_specs must be a dictionary"
     assert alloc_specs['alloc_f'], "Allocation function must be specified"
 
+    for k in alloc_specs.keys():
+        assert k in allowed_alloc_spec_keys, "Key %s is not allowed in alloc_specs. Supported keys are: %s " % (k,allowed_alloc_spec_keys)
+
 
 def check_sim_specs(sim_specs):
     assert isinstance(sim_specs, dict), "sim_specs must be a dictionary"
@@ -486,11 +492,17 @@ def check_sim_specs(sim_specs):
     assert len(sim_specs['out']), "sim_specs must have 'out' entries"
     assert isinstance(sim_specs['in'], list), "'in' field must exist and be a list of field names"
 
+    for k in sim_specs.keys():
+        assert k in allowed_sim_spec_keys, "Key %s is not allowed in sim_specs. Supported keys are: %s " % (k,allowed_sim_spec_keys)
+
 
 def check_gen_specs(gen_specs):
     assert isinstance(gen_specs, dict), "gen_specs must be a dictionary"
     assert not bool(gen_specs) or len(gen_specs['out']), "gen_specs must have 'out' entries"
 
+    for k in alloc_specs.keys():
+        assert k in allowed_gen_spec_keys, "Key %s in gen_specs is not an allowable key" % (k,allowed_gen_spec_keys)
+
 
 def check_exit_criteria(exit_criteria, sim_specs, gen_specs):
     assert isinstance(exit_criteria, dict), "exit_criteria must be a dictionary"

From 8e105178471ca3897d0466b1a060737342ffd512 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 30 Oct 2019 16:15:12 -0500
Subject: [PATCH 376/644] Fixing test of gen_spec keys

---
 libensemble/libE.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/libensemble/libE.py b/libensemble/libE.py
index 6a78051bd..9abf50f65 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -500,8 +500,8 @@ def check_gen_specs(gen_specs):
     assert isinstance(gen_specs, dict), "gen_specs must be a dictionary"
     assert not bool(gen_specs) or len(gen_specs['out']), "gen_specs must have 'out' entries"
 
-    for k in alloc_specs.keys():
-        assert k in allowed_gen_spec_keys, "Key %s in gen_specs is not an allowable key" % (k,allowed_gen_spec_keys)
+    for k in gen_specs.keys():
+        assert k in allowed_gen_spec_keys, "Key %s is not allowed in gen_specs. Supported keys are: %s " % (k,allowed_gen_spec_keys)
 
 
 def check_exit_criteria(exit_criteria, sim_specs, gen_specs):

From 9b3f9c310989c448b66892f5f5fdc53ef2fcf63b Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 30 Oct 2019 16:42:49 -0500
Subject: [PATCH 377/644] New calling scripts with 'user' fields

---
 .../alloc_funcs/fast_alloc_and_pausing.py     |  2 +-
 .../start_persistent_local_opt_gens.py        |  2 +-
 libensemble/gen_funcs/aposmm.py               |  7 +--
 libensemble/libE.py                           |  2 +-
 libensemble/sim_funcs/branin/branin_obj.py    |  2 +-
 libensemble/sim_funcs/chwirut1.py             |  2 +-
 libensemble/sim_funcs/six_hump_camel.py       |  4 +-
 .../script_test_balsam_hworld.py              |  8 +--
 .../regression_tests/test_1d_sampling.py      | 10 ++--
 .../test_1d_uniform_sampling_with_comm_dup.py | 10 ++--
 ...mp_camel_active_persistent_worker_abort.py | 20 ++++----
 .../test_6-hump_camel_aposmm_LD_MMA.py        | 50 ++++++++++---------
 .../test_6-hump_camel_elapsed_time_abort.py   | 14 +++---
 .../test_6-hump_camel_persistent_aposmm_1.py  | 23 +++++----
 .../test_6-hump_camel_persistent_aposmm_2.py  | 25 +++++-----
 .../test_6-hump_camel_persistent_aposmm_3.py  | 25 +++++-----
 .../test_6-hump_camel_persistent_aposmm_4.py  | 27 +++++-----
 ...-hump_camel_persistent_uniform_sampling.py |  7 +--
 .../test_6-hump_camel_uniform_sampling.py     |  7 +--
 ..._sampling_with_persistent_localopt_gens.py | 17 ++++---
 ...mel_with_different_nodes_uniform_sample.py | 20 ++++----
 ...test_branin_aposmm_nlopt_and_then_scipy.py | 33 ++++++------
 .../regression_tests/test_calc_exception.py   |  8 +--
 ...t_chwirut_aposmm_one_residual_at_a_time.py | 30 +++++------
 .../regression_tests/test_chwirut_pounders.py | 22 ++++----
 .../test_chwirut_pounders_persistent.py       | 34 +++++++------
 .../test_chwirut_pounders_splitcomm.py        | 22 ++++----
 .../test_chwirut_pounders_subcomm.py          | 24 +++++----
 ...uniform_sampling_one_residual_at_a_time.py | 29 ++++++-----
 .../tests/regression_tests/test_comms.py      | 13 ++---
 .../tests/regression_tests/test_fast_alloc.py | 17 ++++---
 .../test_inverse_bayes_example.py             | 15 +++---
 .../test_jobcontroller_hworld.py              | 17 ++++---
 .../regression_tests/test_nan_func_aposmm.py  | 17 ++++---
 .../test_worker_exceptions.py                 | 11 ++--
 35 files changed, 311 insertions(+), 265 deletions(-)

diff --git a/libensemble/alloc_funcs/fast_alloc_and_pausing.py b/libensemble/alloc_funcs/fast_alloc_and_pausing.py
index f1cfea0d9..d8e96d4cd 100644
--- a/libensemble/alloc_funcs/fast_alloc_and_pausing.py
+++ b/libensemble/alloc_funcs/fast_alloc_and_pausing.py
@@ -53,7 +53,7 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
             # partial combine_component_func evaluation is # worse than the
             # best, known, complete evaluation (and the point is not a
             # local_pt).
-            if alloc_specs['user'].get(['stop_partial_fvec_eval']):
+            if alloc_specs['user'].get('stop_partial_fvec_eval'):
                 pt_ids = set(persis_info['pt_ids']) - persis_info['has_nan'] - persis_info['complete']
                 pt_ids = np.array(list(pt_ids))
                 partial_fvals = np.zeros(len(pt_ids))
diff --git a/libensemble/alloc_funcs/start_persistent_local_opt_gens.py b/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
index 13ef1931d..a56b49906 100644
--- a/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
+++ b/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
@@ -54,7 +54,7 @@ def start_persistent_local_opt_gens(W, H, sim_specs, gen_specs, alloc_specs, per
     for i in avail_worker_ids(W, persistent=False):
         # Find candidates to start local opt runs if a sample has been evaluated
         if np.any(np.logical_and(~H['local_pt'], H['returned'])):
-            n, _, _, _, r_k, mu, nu = initialize_APOSMM(H, gen_specs['user'])
+            n, _, _, _, r_k, mu, nu = initialize_APOSMM(H, gen_specs)
             update_history_dist(H, n, gen_specs['user'], c_flag=False)
             starting_inds = decide_where_to_start_localopt(H, r_k, mu, nu)
         else:
diff --git a/libensemble/gen_funcs/aposmm.py b/libensemble/gen_funcs/aposmm.py
index aea8a5d25..3fab1459b 100644
--- a/libensemble/gen_funcs/aposmm.py
+++ b/libensemble/gen_funcs/aposmm.py
@@ -180,7 +180,7 @@ def aposmm_logic(H, persis_info, gen_specs, _):
 
     """
 
-    n, n_s, c_flag, O, r_k, mu, nu = initialize_APOSMM(H, gen_specs['user'])
+    n, n_s, c_flag, O, r_k, mu, nu = initialize_APOSMM(H, gen_specs)
 
     # np.savez('H'+str(len(H)),H=H,gen_specs=gen_specs,persis_info=persis_info)
     if n_s < gen_specs['user']['initial_sample_size']:
@@ -887,7 +887,7 @@ def calc_rk(n, n_s, rk_const, lhs_divisions=0):
     return r_k
 
 
-def initialize_APOSMM(H, user_specs):
+def initialize_APOSMM(H, gen_specs):
     """
     Computes common values every time that APOSMM is reinvoked
 
@@ -895,6 +895,7 @@ def initialize_APOSMM(H, user_specs):
         ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
     """
 
+    user_specs = gen_specs['user']
     n = len(user_specs['ub'])
 
     if 'single_component_at_a_time' in user_specs and user_specs['single_component_at_a_time']:
@@ -915,7 +916,7 @@ def initialize_APOSMM(H, user_specs):
 
     # Rather than build up a large output, we will just make changes in the
     # given H, and then send back the rows corresponding to updated H entries.
-    Out = np.empty(0, dtype=user_specs['out'])
+    Out = np.empty(0, dtype=gen_specs['out'])
 
     if 'rk_const' in user_specs:
         rk_c = user_specs['rk_const']
diff --git a/libensemble/libE.py b/libensemble/libE.py
index 9abf50f65..9e9bc7989 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -29,7 +29,7 @@
 # To change logging level for just this module
 # logger.setLevel(logging.DEBUG)
 
-allowed_sim_spec_keys = ['sim_f', 'in', 'out', 'save_every_k', 'user']
+allowed_sim_spec_keys = ['sim_f', 'in', 'out', 'sim_dir', 'clean_jobs', 'save_every_k', 'user']
 allowed_gen_spec_keys = ['gen_f', 'in', 'out', 'save_every_k', 'user']
 allowed_alloc_spec_keys = ['alloc_f', 'in', 'out', 'user']
 
diff --git a/libensemble/sim_funcs/branin/branin_obj.py b/libensemble/sim_funcs/branin/branin_obj.py
index 0a21384b8..00a801858 100644
--- a/libensemble/sim_funcs/branin/branin_obj.py
+++ b/libensemble/sim_funcs/branin/branin_obj.py
@@ -23,7 +23,7 @@ def call_branin(H, persis_info, sim_specs, _):
 
         O['f'][i] = branin(x[0], x[1])
 
-        if 'uniform_random_pause_ub' in sim_specs['user']:
+        if 'user' in sim_specs and 'uniform_random_pause_ub' in sim_specs['user']:
             time.sleep(sim_specs['user']['uniform_random_pause_ub']*np.random.uniform())
 
     return O, persis_info
diff --git a/libensemble/sim_funcs/chwirut1.py b/libensemble/sim_funcs/chwirut1.py
index 279962c35..59c205b33 100644
--- a/libensemble/sim_funcs/chwirut1.py
+++ b/libensemble/sim_funcs/chwirut1.py
@@ -272,7 +272,7 @@ def chwirut_eval(H, persis_info, sim_specs, _):
 
     for i, x in enumerate(H['x']):
         if 'obj_component' in H.dtype.names:
-            if 'component_nan_frequency' in sim_specs['user'] and np.random.uniform(0, 1) < sim_specs['user']['component_nan_frequency']:
+            if 'user' in sim_specs and 'component_nan_frequency' in sim_specs['user'] and np.random.uniform(0, 1) < sim_specs['user']['component_nan_frequency']:
                 O['f_i'][i] = np.nan
             else:
                 O['f_i'][i] = EvaluateFunction(x, H['obj_component'][i])
diff --git a/libensemble/sim_funcs/six_hump_camel.py b/libensemble/sim_funcs/six_hump_camel.py
index eab355806..8848c638b 100644
--- a/libensemble/sim_funcs/six_hump_camel.py
+++ b/libensemble/sim_funcs/six_hump_camel.py
@@ -57,7 +57,7 @@ def six_hump_camel(H, persis_info, sim_specs, _):
     """
     Evaluates the six hump camel function for a collection of points given in ``H['x']``.
     Additionally evaluates the gradient if ``'grad'`` is a field in
-    ``sim_specs['out']`` and pauses for ``sim_specs['pause_time']]`` if
+    ``sim_specs['out']`` and pauses for ``sim_specs['user']['pause_time']]`` if
     defined.
 
     :See:
@@ -73,7 +73,7 @@ def six_hump_camel(H, persis_info, sim_specs, _):
         if 'grad' in O.dtype.names:
             O['grad'][i] = six_hump_camel_grad(x)
 
-        if 'pause_time' in sim_specs:
+        if 'user' in sim_specs and 'pause_time' in sim_specs['user']:
             time.sleep(sim_specs['user']['pause_time'])
 
     return O, persis_info
diff --git a/libensemble/tests/regression_tests/script_test_balsam_hworld.py b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
index e38c51b93..02e201b00 100644
--- a/libensemble/tests/regression_tests/script_test_balsam_hworld.py
+++ b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
@@ -42,17 +42,19 @@ def build_simfunc():
              'in': ['x'],
              'out': [('f', float), ('cstat', int)],
              'save_every_k': 400,
-             'cores': cores_per_job}
+             'user': {'cores': cores_per_job}}
 
 gen_specs = {'gen_f': gen_f,
              'in': ['sim_id'],
              'out': [('x', float, (2,))],
+             'save_every_k': 20,
+             'user': {
              'lb': np.array([-3, -2]),
              'ub': np.array([3, 2]),
              'gen_batch_size': nworkers,
              'batch_mode': True,
-             'num_active_gens': 1,
-             'save_every_k': 20}
+             'num_active_gens': 1}
+             }
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
diff --git a/libensemble/tests/regression_tests/test_1d_sampling.py b/libensemble/tests/regression_tests/test_1d_sampling.py
index 5e7990f02..ea55ad0e3 100644
--- a/libensemble/tests/regression_tests/test_1d_sampling.py
+++ b/libensemble/tests/regression_tests/test_1d_sampling.py
@@ -27,10 +27,12 @@
 
 gen_specs = {'gen_f': gen_f,
              'out': [('x', float, (1,))],
-             'lb': np.array([-3]),
-             'ub': np.array([3]),
-             'gen_batch_size': 500,
-             'save_every_k': 300}
+             'save_every_k': 300,
+             'user': {'gen_batch_size': 500,
+                      'lb': np.array([-3]),
+                      'ub': np.array([3]),
+                     }
+             }
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
diff --git a/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py b/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
index 089b2d44c..dd5cc05a7 100644
--- a/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
+++ b/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
@@ -45,10 +45,12 @@
 gen_specs = {'gen_f': gen_f,
              'in': ['sim_id'],
              'out': [('x', float, (1,))],
-             'lb': np.array([-3]),
-             'ub': np.array([3]),
-             'gen_batch_size': 500,
-             'save_every_k': 300}
+             'save_every_k': 300,
+             'user': {'lb': np.array([-3]),
+                      'ub': np.array([3]),
+                      'gen_batch_size': 500
+                     }
+             }
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py b/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py
index c8d9d5a33..40c9d639a 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py
@@ -32,16 +32,18 @@
 gen_out += [('x', float, 2), ('x_on_cube', float, 2)]
 gen_specs = {'gen_f': gen_f,
              'in': [],
-             'localopt_method': 'LN_BOBYQA',
-             'xtol_rel': 1e-4,
              'out': gen_out,
-             'lb': np.array([-3, -2]),
-             'ub': np.array([3, 2]),
-             'gen_batch_size': 2,
-             'batch_mode': True,
-             'num_active_gens': 1,
-             'dist_to_bound_multiple': 0.5,
-             'localopt_maxeval': 4}
+             'user': {'localopt_method': 'LN_BOBYQA',
+                      'xtol_rel': 1e-4,
+                      'lb': np.array([-3, -2]),
+                      'ub': np.array([3, 2]),
+                      'gen_batch_size': 2,
+                      'batch_mode': True,
+                      'num_active_gens': 1,
+                      'dist_to_bound_multiple': 0.5,
+                      'localopt_maxeval': 4
+                     }
+            }
 
 alloc_specs = {'alloc_f': alloc_f, 'out': gen_out}
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
index 4a88c1473..93c7ae864 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
@@ -36,17 +36,19 @@
 gen_specs = {'gen_f': gen_f,
              'in': [o[0] for o in gen_out] + ['f', 'grad', 'returned'],
              'out': gen_out,
-             'num_active_gens': 1,
-             'batch_mode': True,
-             'initial_sample_size': 100,
-             'sample_points': np.round(minima, 1),
-             'localopt_method': 'LD_MMA',
-             'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
-             'xtol_rel': 1e-3,
-             'num_active_gens': 1,
-             'max_active_runs': 6,
-             'lb': np.array([-3, -2]),
-             'ub': np.array([3, 2])}
+             'user': {'num_active_gens': 1,
+                      'batch_mode': True,
+                      'initial_sample_size': 100,
+                      'sample_points': np.round(minima, 1),
+                      'localopt_method': 'LD_MMA',
+                      'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
+                      'xtol_rel': 1e-3,
+                      'num_active_gens': 1,
+                      'max_active_runs': 6,
+                      'lb': np.array([-3, -2]),
+                      'ub': np.array([3, 2])
+                      }
+             }
 
 alloc_specs = {'alloc_f': alloc_f, 'out': [('allocated', bool)]}
 
@@ -77,27 +79,27 @@ def libE_mpi_abort():
         libE_specs['worker_cmd'].append(str(run))
 
     if run == 1:
-        gen_specs['localopt_method'] = 'blmvm'
-        gen_specs['grtol'] = 1e-5
-        gen_specs['gatol'] = 1e-5
+        gen_specs['user']['localopt_method'] = 'blmvm'
+        gen_specs['user']['grtol'] = 1e-5
+        gen_specs['user']['gatol'] = 1e-5
         persis_info = deepcopy(persis_info_safe)
 
     if run == 2:
-        gen_specs['localopt_method'] = 'LD_MMA'
+        gen_specs['user']['localopt_method'] = 'LD_MMA'
         # Change the bounds to put a local min at a corner point (to test that
         # APOSMM handles the same point being in multiple runs) ability to
         # give back a previously evaluated point)
-        gen_specs['ub'] = np.array([-2.9, -1.9])
-        gen_specs['mu'] = 1e-4
-        gen_specs['rk_const'] = 0.01*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi)
-        gen_specs['lhs_divisions'] = 2
+        gen_specs['user']['ub'] = np.array([-2.9, -1.9])
+        gen_specs['user']['mu'] = 1e-4
+        gen_specs['user']['rk_const'] = 0.01*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi)
+        gen_specs['user']['lhs_divisions'] = 2
         # APOSMM can be called when some run is incomplete
-        gen_specs.pop('batch_mode')
+        gen_specs['user'].pop('batch_mode')
 
-        gen_specs.pop('xtol_rel')
-        gen_specs['ftol_rel'] = 1e-2
-        gen_specs['xtol_abs'] = 1e-3
-        gen_specs['ftol_abs'] = 1e-8
+        gen_specs['user'].pop('xtol_rel')
+        gen_specs['user']['ftol_rel'] = 1e-2
+        gen_specs['user']['xtol_abs'] = 1e-3
+        gen_specs['user']['ftol_abs'] = 1e-8
         exit_criteria = {'sim_max': 200, 'elapsed_wallclock_time': 300}
         minima = np.array([[-2.9, -1.9]])
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py b/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
index 1e3cb393b..bf1b1cb52 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
@@ -27,16 +27,18 @@
 sim_specs = {'sim_f': sim_f,
              'in': ['x'],
              'out': [('f', float)],
-             'pause_time': 2}
+             'user': {'pause_time': 2}
+             }
 
 gen_specs = {'gen_f': gen_f,
              'in': ['sim_id'],
-             'gen_batch_size': 5,
-             'num_active_gens': 1,
-             'batch_mode': False,
              'out': [('x', float, (2,))],
-             'lb': np.array([-3, -2]),
-             'ub': np.array([3, 2])}
+             'user': {'gen_batch_size': 5,
+                      'num_active_gens': 1,
+                      'batch_mode': False,
+                      'lb': np.array([-3, -2]),
+                      'ub': np.array([3, 2])}
+             }
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
index 94a145662..e112e8688 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
@@ -46,17 +46,18 @@
 gen_specs = {'gen_f': gen_f,
              'in': [],
              'out': gen_out,
-             'batch_mode': True,
-             'initial_sample_size': 100,
-             'sample_points': np.round(minima, 1),
-             'localopt_method': 'LD_MMA',
-             'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
-             'xtol_rel': 1e-6,
-             'ftol_rel': 1e-6,
-             'num_active_gens': 1,
-             'max_active_runs': 6,
-             'lb': np.array([-3, -2]),
-             'ub': np.array([3, 2])}
+             'user': {'batch_mode': True,
+                      'initial_sample_size': 100,
+                      'sample_points': np.round(minima, 1),
+                      'localopt_method': 'LD_MMA',
+                      'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
+                      'xtol_rel': 1e-6,
+                      'ftol_rel': 1e-6,
+                      'num_active_gens': 1,
+                      'max_active_runs': 6,
+                      'lb': np.array([-3, -2]),
+                      'ub': np.array([3, 2])}
+             }
 
 alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)]}
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
index abe9d1dca..102c7782c 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
@@ -46,18 +46,19 @@
 gen_specs = {'gen_f': gen_f,
              'in': [],
              'out': gen_out,
-             'batch_mode': True,
-             'initial_sample_size': 100,
-             'sample_points': np.round(minima, 1),
-             'localopt_method': 'LN_BOBYQA',
-             'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
-             'xtol_abs': 1e-6,
-             'ftol_abs': 1e-6,
-             'num_active_gens': 1,
-             'dist_to_bound_multiple': 0.5,
-             'max_active_runs': 6,
-             'lb': np.array([-3, -2]),
-             'ub': np.array([3, 2])}
+             'user': {'initial_sample_size': 100,
+                      'sample_points': np.round(minima, 1),
+                      'localopt_method': 'LN_BOBYQA',
+                      'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
+                      'xtol_abs': 1e-6,
+                      'ftol_abs': 1e-6,
+                      'num_active_gens': 1,
+                      'dist_to_bound_multiple': 0.5,
+                      'max_active_runs': 6,
+                      'batch_mode': True,
+                      'lb': np.array([-3, -2]),
+                      'ub': np.array([3, 2])}
+             }
 
 alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)]}
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
index a8f566eca..7fe9264c5 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
@@ -46,18 +46,19 @@
 gen_specs = {'gen_f': gen_f,
              'in': [],
              'out': gen_out,
-             'batch_mode': True,
-             'initial_sample_size': 100,
-             'sample_points': np.round(minima, 1),
-             'localopt_method': 'blmvm',
-             'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
-             'grtol': 1e-4,
-             'gatol': 1e-4,
-             'num_active_gens': 1,
-             'dist_to_bound_multiple': 0.5,
-             'max_active_runs': 6,
-             'lb': np.array([-3, -2]),
-             'ub': np.array([3, 2])}
+             'user': {'initial_sample_size': 100,
+                      'sample_points': np.round(minima, 1),
+                      'batch_mode': True,
+                      'localopt_method': 'blmvm',
+                      'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
+                      'grtol': 1e-4,
+                      'gatol': 1e-4,
+                      'num_active_gens': 1,
+                      'dist_to_bound_multiple': 0.5,
+                      'max_active_runs': 6,
+                      'lb': np.array([-3, -2]),
+                      'ub': np.array([3, 2])}
+             }
 
 alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)]}
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
index f6e9bf0b3..288ce5980 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
@@ -45,19 +45,20 @@
 gen_specs = {'gen_f': gen_f,
              'in': [],
              'out': gen_out,
-             'batch_mode': True,
-             'initial_sample_size': 100,
-             'sample_points': np.round(minima, 1),
-             'localopt_method': 'scipy_Nelder-Mead',
-             'fatol': 1e-5,
-             'xatol': 1e-5,
-             'nu': 1e-8,
-             'mu': 1e-8,
-             'num_active_gens': 1,
-             'dist_to_bound_multiple': 0.01,
-             'max_active_runs': 6,
-             'lb': np.array([-3, -2]),
-             'ub': np.array([3, 2])}
+             'user': {'initial_sample_size': 100,
+                      'batch_mode': True,
+                      'sample_points': np.round(minima, 1),
+                      'localopt_method': 'scipy_Nelder-Mead',
+                      'fatol': 1e-5,
+                      'xatol': 1e-5,
+                      'nu': 1e-8,
+                      'mu': 1e-8,
+                      'num_active_gens': 1,
+                      'dist_to_bound_multiple': 0.01,
+                      'max_active_runs': 6,
+                      'lb': np.array([-3, -2]),
+                      'ub': np.array([3, 2])}
+             }
 
 alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)]}
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py
index c0eda0790..769d0e10a 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py
@@ -36,10 +36,11 @@
 
 gen_specs = {'gen_f': gen_f,
              'in': [],
-             'gen_batch_size': 20,
              'out': [('x', float, (n,))],
-             'lb': np.array([-3, -2]),
-             'ub': np.array([3, 2])}
+             'user': {'gen_batch_size': 20,
+                      'lb': np.array([-3, -2]),
+                      'ub': np.array([3, 2])}
+             }
 
 alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)]}
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
index bd4e96352..e1c74b961 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
@@ -35,9 +35,10 @@
 gen_specs = {'gen_f': gen_f,               # Tell libE function generating sim_f input
              'out': [('x', float, (2,))],  # Tell libE gen_f output, type, size
              'save_every_k': 300,          # Tell libE to save every 300 gen entries
-             'gen_batch_size': 500,        # Tell gen_f how much to generate per call
-             'lb': np.array([-3, -2]),     # Tell gen_f lower bounds
-             'ub': np.array([3, 2]),       # Tell gen_f upper bounds
+             'user': {'gen_batch_size': 500,        # Tell gen_f how much to generate per call
+                      'lb': np.array([-3, -2]),     # Tell gen_f lower bounds
+                      'ub': np.array([3, 2]),       # Tell gen_f upper bounds
+                     }
              }
 # end_gen_specs_rst_tag
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
index bcaa94c91..a9f8eea70 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
@@ -39,15 +39,16 @@
 gen_out += [('x', float, n), ('x_on_cube', float, n)]
 gen_specs = {'gen_f': gen_f,
              'in': [],
-             'xtol_rel': 1e-4,
              'out': gen_out,
-             'lb': np.array([-3, -2]),
-             'ub': np.array([3, 2]),
-             'gen_batch_size': 2,
-             'batch_mode': True,
-             'num_active_gens': 1,
-             'localopt_method': 'LD_MMA',
-             'xtol_rel': 1e-4}
+             'user': {'xtol_rel': 1e-4,
+                      'batch_mode': True,
+                      'lb': np.array([-3, -2]),
+                      'ub': np.array([3, 2]),
+                      'gen_batch_size': 2,
+                      'num_active_gens': 1,
+                      'localopt_method': 'LD_MMA',
+                      'xtol_rel': 1e-4}
+             }
 
 alloc_specs = {'alloc_f': alloc_f, 'out': gen_out}
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py b/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
index ac319ea8a..b787596d8 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
@@ -46,7 +46,8 @@
 sim_specs = {'sim_f': sim_f,
              'in': ['x', 'num_nodes', 'ranks_per_node'],
              'out': [('f', float)],
-             'nodelist': libE_machinefile}
+             'user': {'nodelist': libE_machinefile}
+             }
 
 gen_specs = {'gen_f': gen_f,
              'in': ['sim_id'],
@@ -55,14 +56,15 @@
                      ('ranks_per_node', int),
                      ('x', float, n),
                      ('x_on_cube', float, n)],
-             'initial_batch_size': 5,
-             'max_ranks_per_node': 8,
-             'num_active_gens': 1,
-             'batch_mode': False,
-             'give_all_with_same_priority': True,
-             'max_num_nodes': nworkers,  # Used in uniform_random_sample_with_different_nodes_and_ranks,
-             'lb': np.array([-3, -2]),
-             'ub': np.array([3, 2])}
+             'user': {'initial_batch_size': 5,
+                      'batch_mode': False,
+                      'max_ranks_per_node': 8,
+                      'num_active_gens': 1,
+                      'give_all_with_same_priority': True,
+                      'max_num_nodes': nworkers,  # Used in uniform_random_sample_with_different_nodes_and_ranks,
+                      'lb': np.array([-3, -2]),
+                      'ub': np.array([3, 2])}
+             }
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
diff --git a/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py b/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
index ef22e533e..dc6089255 100644
--- a/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
+++ b/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
@@ -40,24 +40,25 @@
     # Otherwise, will just copy in same directory as sim_dir
     sim_specs['sim_dir_prefix'] = '~'
 elif nworkers == 3:
-    sim_specs['uniform_random_pause_ub'] = 0.05
+    sim_specs['user'] = {'uniform_random_pause_ub': 0.05}
 
 n = 2
 gen_out += [('x', float, n), ('x_on_cube', float, n)]
 gen_specs = {'gen_f': gen_f,
              'in': [o[0] for o in gen_out] + ['f', 'returned'],
              'out': gen_out,
-             'num_active_gens': 1,
-             'batch_mode': True,
-             'lb': np.array([-5, 0]),
-             'ub': np.array([10, 15]),
-             'initial_sample_size': 20,
-             'localopt_method': 'LN_BOBYQA',
-             'dist_to_bound_multiple': 0.99,
-             'xtol_rel': 1e-3,
-             'min_batch_size': nworkers,
-             'high_priority_to_best_localopt_runs': True,
-             'max_active_runs': 3}
+             'user': {'num_active_gens': 1,
+                      'batch_mode': True,
+                      'lb': np.array([-5, 0]),
+                      'ub': np.array([10, 15]),
+                      'initial_sample_size': 20,
+                      'localopt_method': 'LN_BOBYQA',
+                      'dist_to_bound_multiple': 0.99,
+                      'xtol_rel': 1e-3,
+                      'min_batch_size': nworkers,
+                      'high_priority_to_best_localopt_runs': True,
+                      'max_active_runs': 3}
+             }
 
 persis_info = per_worker_stream(persis_info, nworkers + 1)
 persis_info_safe = deepcopy(persis_info)
@@ -71,9 +72,9 @@
 # Perform the run
 for run in range(2):
     if run == 1:
-        gen_specs['localopt_method'] = 'scipy_COBYLA'
-        gen_specs.pop('xtol_rel')
-        gen_specs['tol'] = 1e-5
+        gen_specs['user']['localopt_method'] = 'scipy_COBYLA'
+        gen_specs['user'].pop('xtol_rel')
+        gen_specs['user']['tol'] = 1e-5
         exit_criteria['sim_max'] = 500
         persis_info = deepcopy(persis_info_safe)
 
@@ -89,5 +90,5 @@
             print(dist)
             assert dist < tol
 
-        print("\nAPOSMM + " + gen_specs['localopt_method'] + " found " + str(k) + " minima to tolerance " + str(tol))
+        print("\nAPOSMM + " + gen_specs['user']['localopt_method'] + " found " + str(k) + " minima to tolerance " + str(tol))
         save_libE_output(H, persis_info, __file__, nworkers)
diff --git a/libensemble/tests/regression_tests/test_calc_exception.py b/libensemble/tests/regression_tests/test_calc_exception.py
index 604779a63..58247bb9c 100644
--- a/libensemble/tests/regression_tests/test_calc_exception.py
+++ b/libensemble/tests/regression_tests/test_calc_exception.py
@@ -29,12 +29,14 @@ def six_hump_camel_err(H, persis_info, sim_specs, _):
 
 
 sim_specs = {'sim_f': six_hump_camel_err, 'in': ['x'], 'out': [('f', float)]}
+
 gen_specs = {'gen_f': gen_f,
              'in': ['sim_id'],
              'out': [('x', float, 2)],
-             'lb': np.array([-3, -2]),
-             'ub': np.array([3, 2]),
-             'gen_batch_size': 10}
+             'user': {'lb': np.array([-3, -2]),
+                      'ub': np.array([3, 2]),
+                      'gen_batch_size': 10}
+             }
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py b/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py
index 55bb6994c..3d0108126 100644
--- a/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py
+++ b/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py
@@ -42,25 +42,27 @@
 gen_specs = {'gen_f': gen_f,
              'in': [o[0] for o in gen_out] + ['f_i', 'returned'],
              'out': gen_out,
-             'initial_sample_size': 5,
-             'num_active_gens': 1,
-             'batch_mode': True,
-             'lb': LB,
-             'ub': UB,
-             'localopt_method': 'pounders',
-             'dist_to_bound_multiple': 0.5,
-             'single_component_at_a_time': True,
-             'components': m,
-             'combine_component_func': lambda x: np.sum(np.power(x, 2))}
+             'user': {'initial_sample_size': 5,
+                      'batch_mode': True,
+                      'num_active_gens': 1,
+                      'lb': LB,
+                      'ub': UB,
+                      'localopt_method': 'pounders',
+                      'dist_to_bound_multiple': 0.5,
+                      'single_component_at_a_time': True,
+                      'components': m,
+                      'combine_component_func': lambda x: np.sum(np.power(x, 2))}
+             }
 
-gen_specs.update({'grtol': 1e-4, 'gatol': 1e-4, 'frtol': 1e-15, 'fatol': 1e-15})
+gen_specs['user'].update({'grtol': 1e-4, 'gatol': 1e-4, 'frtol': 1e-15, 'fatol': 1e-15})
 
 np.random.RandomState(0)
-gen_specs['sample_points'] = np.random.uniform(0, 1, (budget, n))*(UB-LB)+LB
+gen_specs['user']['sample_points'] = np.random.uniform(0, 1, (budget, n))*(UB-LB)+LB
 alloc_specs = {'alloc_f': alloc_f,
                'out': [('allocated', bool)],
-               'stop_on_NaNs': True,
-               'stop_partial_fvec_eval': True}
+               'user': {'stop_on_NaNs': True,
+                        'stop_partial_fvec_eval': True}
+               }
 
 persis_info = per_worker_stream(persis_info, nworkers + 1)
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders.py b/libensemble/tests/regression_tests/test_chwirut_pounders.py
index e65adba26..0cf677c9d 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders.py
@@ -32,7 +32,8 @@
 sim_specs = {'sim_f': sim_f,
              'in': ['x'],
              'out': [('f', float), ('fvec', float, m)],
-             'combine_component_func': lambda x: np.sum(np.power(x, 2))}
+             'user': {'combine_component_func': lambda x: np.sum(np.power(x, 2))}
+             }
 
 gen_out += [('x', float, n), ('x_on_cube', float, n)]
 
@@ -40,16 +41,17 @@
 gen_specs = {'gen_f': gen_f,
              'in': [o[0] for o in gen_out]+['f', 'fvec', 'returned'],
              'out': gen_out,
-             'initial_sample_size': 5,
-             'num_active_gens': 1,
-             'batch_mode': True,
-             'lb': (-2-np.pi/10)*np.ones(n),
-             'ub': 2*np.ones(n),
-             'localopt_method': 'pounders',
-             'dist_to_bound_multiple': 0.5,
-             'components': m}
+             'user': {'initial_sample_size': 5,
+                      'batch_mode': True,
+                      'num_active_gens': 1,
+                      'lb': (-2-np.pi/10)*np.ones(n),
+                      'ub': 2*np.ones(n),
+                      'localopt_method': 'pounders',
+                      'dist_to_bound_multiple': 0.5,
+                      'components': m}
+             }
 
-gen_specs.update({'grtol': 1e-4, 'gatol': 1e-4, 'frtol': 1e-15, 'fatol': 1e-15})
+gen_specs['user'].update({'grtol': 1e-4, 'gatol': 1e-4, 'frtol': 1e-15, 'fatol': 1e-15})
 
 persis_info = per_worker_stream(persis_info, nworkers + 1)
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
index f1fbcb913..62873ea16 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
@@ -38,7 +38,8 @@
 sim_specs = {'sim_f': sim_f,
              'in': ['x'],
              'out': [('f', float), ('fvec', float, m)],
-             'combine_component_func': lambda x: np.sum(np.power(x, 2))}
+             'user': {'combine_component_func': lambda x: np.sum(np.power(x, 2))}
+             }
 
 gen_out = [('x', float, n), ('x_on_cube', float, n), ('sim_id', int),
            ('local_min', bool), ('local_pt', bool)]
@@ -47,18 +48,19 @@
 gen_specs = {'gen_f': gen_f,
              'in': [],
              'out': gen_out,
-             'batch_mode': True,
-             'initial_sample_size': 100,
-             'localopt_method': 'pounders',
-             'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
-             'grtol': 1e-6,
-             'gatol': 1e-6,
-             'num_active_gens': 1,
-             'dist_to_bound_multiple': 0.5,
-             'lhs_divisions': 50,
-             'components': m,
-             'lb': (-2-np.pi/10)*np.ones(n),
-             'ub': 2*np.ones(n)}
+             'user': {'initial_sample_size': 100,
+                      'localopt_method': 'pounders',
+                      'batch_mode': True,
+                      'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
+                      'grtol': 1e-6,
+                      'gatol': 1e-6,
+                      'num_active_gens': 1,
+                      'dist_to_bound_multiple': 0.5,
+                      'lhs_divisions': 50,
+                      'components': m,
+                      'lb': (-2-np.pi/10)*np.ones(n),
+                      'ub': 2*np.ones(n)}
+             }
 
 alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)]}
 
@@ -67,10 +69,10 @@
 exit_criteria = {'sim_max': 500}
 
 sample_points = np.zeros((0, n))
-for i in range(ceil(exit_criteria['sim_max']/gen_specs['lhs_divisions'])):
-    sample_points = np.append(sample_points, lhs_sample(n, gen_specs['lhs_divisions']), axis=0)
+for i in range(ceil(exit_criteria['sim_max']/gen_specs['user']['lhs_divisions'])):
+    sample_points = np.append(sample_points, lhs_sample(n, gen_specs['user']['lhs_divisions']), axis=0)
 
-gen_specs['sample_points'] = sample_points*(gen_specs['ub']-gen_specs['lb']) + gen_specs['lb']
+gen_specs['user']['sample_points'] = sample_points*(gen_specs['user']['ub']-gen_specs['user']['lb']) + gen_specs['user']['lb']
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py b/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
index 377d22bf8..db5861484 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
@@ -36,7 +36,8 @@
 sim_specs = {'sim_f': sim_f,
              'in': ['x'],
              'out': [('f', float), ('fvec', float, m)],
-             'combine_component_func': lambda x: np.sum(np.power(x, 2))}
+             'user': {'combine_component_func': lambda x: np.sum(np.power(x, 2))}
+             }
 
 gen_out += [('x', float, n), ('x_on_cube', float, n)]
 
@@ -44,16 +45,17 @@
 gen_specs = {'gen_f': gen_f,
              'in': [o[0] for o in gen_out]+['f', 'fvec', 'returned'],
              'out': gen_out,
-             'initial_sample_size': 5,
-             'num_active_gens': 1,
-             'batch_mode': True,
-             'lb': (-2-np.pi/10)*np.ones(n),
-             'ub': 2*np.ones(n),
-             'localopt_method': 'pounders',
-             'dist_to_bound_multiple': 0.5,
-             'components': m}
+             'user': {'initial_sample_size': 5,
+                      'batch_mode': True,
+                      'num_active_gens': 1,
+                      'lb': (-2-np.pi/10)*np.ones(n),
+                      'ub': 2*np.ones(n),
+                      'localopt_method': 'pounders',
+                      'dist_to_bound_multiple': 0.5,
+                      'components': m}
+             }
 
-gen_specs.update({'grtol': 1e-4, 'gatol': 1e-4, 'frtol': 1e-15, 'fatol': 1e-15})
+gen_specs['user'].update({'grtol': 1e-4, 'gatol': 1e-4, 'frtol': 1e-15, 'fatol': 1e-15})
 
 persis_info = per_worker_stream(persis_info, nworkers + 1)
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py b/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
index 97350fcc0..860c0acd2 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
@@ -40,7 +40,8 @@
 sim_specs = {'sim_f': sim_f,
              'in': ['x'],
              'out': [('f', float), ('fvec', float, m)],
-             'combine_component_func': lambda x: np.sum(np.power(x, 2))}
+             'user': {'combine_component_func': lambda x: np.sum(np.power(x, 2))}
+             }
 
 gen_out += [('x', float, n), ('x_on_cube', float, n)]
 
@@ -48,16 +49,17 @@
 gen_specs = {'gen_f': gen_f,
              'in': [o[0] for o in gen_out]+['f', 'fvec', 'returned'],
              'out': gen_out,
-             'initial_sample_size': 5,
-             'num_active_gens': 1,
-             'batch_mode': True,
-             'lb': (-2-np.pi/10)*np.ones(n),
-             'ub': 2*np.ones(n),
-             'localopt_method': 'pounders',
-             'dist_to_bound_multiple': 0.5,
-             'components': m}
-
-gen_specs.update({'grtol': 1e-4, 'gatol': 1e-4, 'frtol': 1e-15, 'fatol': 1e-15})
+             'user': {'initial_sample_size': 5,
+                      'batch_mode': True,
+                      'num_active_gens': 1,
+                      'lb': (-2-np.pi/10)*np.ones(n),
+                      'ub': 2*np.ones(n),
+                      'localopt_method': 'pounders',
+                      'dist_to_bound_multiple': 0.5,
+                      'components': m}
+             }
+
+gen_specs['user'].update({'grtol': 1e-4, 'gatol': 1e-4, 'frtol': 1e-15, 'fatol': 1e-15})
 
 persis_info = per_worker_stream(persis_info, nworkers + 1)
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
index 559a9681a..aba1eb713 100644
--- a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
+++ b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
@@ -44,7 +44,8 @@
 sim_specs = {'sim_f': sim_f,
              'in': ['x', 'obj_component'],
              'out': [('f_i', float)],
-             'component_nan_frequency': 0.01}
+             'user': {'component_nan_frequency': 0.01}
+             }
 
 # lb tries to avoid x[1]=-x[2], which results in division by zero in chwirut.
 gen_specs = {'gen_f': gen_f,
@@ -54,19 +55,21 @@
                      ('paused', bool),
                      ('obj_component', int),
                      ('pt_id', int)],
-             'gen_batch_size': 2,
-             'single_component_at_a_time': True,
-             'combine_component_func': lambda x: np.sum(np.power(x, 2)),
-             'num_active_gens': 1,
-             'batch_mode': True,
-             'lb': (-2-np.pi/10)*np.ones(n),
-             'ub': 2*np.ones(n),
-             'components': m}
+             'user': {'gen_batch_size': 2,
+                      'batch_mode': True,
+                      'single_component_at_a_time': True,
+                      'combine_component_func': lambda x: np.sum(np.power(x, 2)),
+                      'num_active_gens': 1,
+                      'lb': (-2-np.pi/10)*np.ones(n),
+                      'ub': 2*np.ones(n),
+                      'components': m}
+             }
 
 alloc_specs = {'alloc_f': alloc_f,              # Allocation function
                'out': [('allocated', bool)],    # Output fields (included in History)
-               'stop_on_NaNs': True,            # Should alloc_f preempt evals
-               'stop_partial_fvec_eval': True}  # Should alloc_f preempt evals
+               'user': {'stop_on_NaNs': True,            # Should alloc_f preempt evals
+                        'stop_partial_fvec_eval': True}  # Should alloc_f preempt evals
+               }
 # end_alloc_specs_rst_tag
 
 persis_info = per_worker_stream(persis_info, nworkers + 1)
@@ -82,7 +85,7 @@
     save_libE_output(H, persis_info, __file__, nworkers)
 
 # Perform the run but not stopping on NaNs
-alloc_specs.pop('stop_on_NaNs')
+alloc_specs['user'].pop('stop_on_NaNs')
 persis_info = deepcopy(persis_info_safe)
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
                             alloc_specs, libE_specs)
@@ -90,7 +93,7 @@
     assert flag == 0
 
 # Perform the run also not stopping on partial fvec evals
-alloc_specs.pop('stop_partial_fvec_eval')
+alloc_specs['user'].pop('stop_partial_fvec_eval')
 persis_info = deepcopy(persis_info_safe)
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
                             alloc_specs, libE_specs)
diff --git a/libensemble/tests/regression_tests/test_comms.py b/libensemble/tests/regression_tests/test_comms.py
index d719fc6fe..f240621c6 100644
--- a/libensemble/tests/regression_tests/test_comms.py
+++ b/libensemble/tests/regression_tests/test_comms.py
@@ -37,12 +37,13 @@
 gen_specs = {'gen_f': gen_f,
              'in': ['sim_id'],
              'out': [('x', float, (2,))],
-             'lb': np.array([-3, -2]),
-             'ub': np.array([3, 2]),
-             'gen_batch_size': sim_max,
-             'batch_mode': True,
-             'num_active_gens': 1,
-             'save_every_k': 300}
+             'save_every_k': 300,
+             'user': {'lb': np.array([-3, -2]),
+                      'ub': np.array([3, 2]),
+                      'batch_mode': True,
+                      'gen_batch_size': sim_max,
+                      'num_active_gens': 1}
+             }
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
diff --git a/libensemble/tests/regression_tests/test_fast_alloc.py b/libensemble/tests/regression_tests/test_fast_alloc.py
index 1741232c7..012039a29 100644
--- a/libensemble/tests/regression_tests/test_fast_alloc.py
+++ b/libensemble/tests/regression_tests/test_fast_alloc.py
@@ -27,15 +27,16 @@
 
 num_pts = 30*(nworkers - 1)
 
-sim_specs = {'sim_f': sim_f, 'in': ['x'], 'out': [('f', float)]}
+sim_specs = {'sim_f': sim_f, 'in': ['x'], 'out': [('f', float)], 'user': {}}
 
 gen_specs = {'gen_f': gen_f,
              'in': ['sim_id'],
              'out': [('x', float, (2,))],
-             'gen_batch_size': num_pts,
-             'num_active_gens': 1,
-             'lb': np.array([-3, -2]),
-             'ub': np.array([3, 2])}
+             'user': {'gen_batch_size': num_pts,
+                      'num_active_gens': 1,
+                      'lb': np.array([-3, -2]),
+                      'ub': np.array([3, 2])}
+             }
 
 alloc_specs = {'alloc_f': alloc_f, 'out': [('allocated', bool)]}
 
@@ -51,11 +52,11 @@
 
 for time in np.append([0], np.logspace(-5, -1, 5)):
     for rep in range(1):
-        sim_specs['pause_time'] = time
+        sim_specs['user']['pause_time'] = time
 
         if time == 0:
-            sim_specs.pop('pause_time')
-            gen_specs['gen_batch_size'] = num_pts//2
+            sim_specs['user'].pop('pause_time')
+            gen_specs['user']['gen_batch_size'] = num_pts//2
 
         persis_info['next_to_give'] = 0
         persis_info['total_gen_calls'] = 1
diff --git a/libensemble/tests/regression_tests/test_inverse_bayes_example.py b/libensemble/tests/regression_tests/test_inverse_bayes_example.py
index bcbec1a3d..a117a83f9 100644
--- a/libensemble/tests/regression_tests/test_inverse_bayes_example.py
+++ b/libensemble/tests/regression_tests/test_inverse_bayes_example.py
@@ -38,17 +38,18 @@
              'in': [],
              'out': [('x', float, 2), ('batch', int), ('subbatch', int),
                      ('prior', float), ('prop', float), ('weight', float)],
-             'lb': np.array([-3, -2]),
-             'ub': np.array([3, 2]),
-             'subbatch_size': 3,
-             'num_subbatches': 2,
-             'num_batches': 10}
+             'user': {'lb': np.array([-3, -2]),
+                      'ub': np.array([3, 2]),
+                      'subbatch_size': 3,
+                      'num_subbatches': 2,
+                      'num_batches': 10}
+             }
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
 # Tell libEnsemble when to stop
 exit_criteria = {
-    'sim_max': gen_specs['subbatch_size']*gen_specs['num_subbatches']*gen_specs['num_batches'],
+    'sim_max': gen_specs['user']['subbatch_size']*gen_specs['user']['num_subbatches']*gen_specs['user']['num_batches'],
     'elapsed_wallclock_time': 300}
 
 alloc_specs = {'out': [], 'alloc_f': alloc_f}
@@ -60,6 +61,6 @@
 if is_master:
     assert flag == 0
     # Change the last weights to correct values (H is a list on other cores and only array on manager)
-    ind = 2*gen_specs['subbatch_size']*gen_specs['num_subbatches']
+    ind = 2*gen_specs['user']['subbatch_size']*gen_specs['user']['num_subbatches']
     H[-ind:] = H['prior'][-ind:] + H['like'][-ind:] - H['prop'][-ind:]
     assert len(H) == 60, "Failed"
diff --git a/libensemble/tests/regression_tests/test_jobcontroller_hworld.py b/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
index 14237f09b..df50984ab 100644
--- a/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
+++ b/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
@@ -69,17 +69,20 @@
              'in': ['x'],
              'out': [('f', float), ('cstat', int)],
              'save_every_k': 400,
-             'cores': cores_per_job}
+             'user': {'cores': cores_per_job}
+             }
 
 gen_specs = {'gen_f': gen_f,
              'in': ['sim_id'],
              'out': [('x', float, (2,))],
-             'lb': np.array([-3, -2]),
-             'ub': np.array([3, 2]),
-             'gen_batch_size': nworkers,
-             'batch_mode': True,
-             'num_active_gens': 1,
-             'save_every_k': 20}
+             'save_every_k': 20,
+             'user': {'lb': np.array([-3, -2]),
+                      'ub': np.array([3, 2]),
+                      'batch_mode': True,
+                      'gen_batch_size': nworkers,
+                      'num_active_gens': 1,
+                      }
+             }
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
diff --git a/libensemble/tests/regression_tests/test_nan_func_aposmm.py b/libensemble/tests/regression_tests/test_nan_func_aposmm.py
index be7e59790..0be876285 100644
--- a/libensemble/tests/regression_tests/test_nan_func_aposmm.py
+++ b/libensemble/tests/regression_tests/test_nan_func_aposmm.py
@@ -33,16 +33,17 @@
 gen_specs = {'gen_f': gen_f,
              'in': [o[0] for o in gen_out] + ['f', 'f_i', 'returned'],
              'out': gen_out,
-             'lb': -2*np.ones(n),
-             'ub': 2*np.ones(n),
-             'initial_sample_size': 5,
-             'num_active_gens': 1,
-             'batch_mode': True}
+             'user': {'initial_sample_size': 5,
+                      'lb': -2*np.ones(n),
+                      'ub': 2*np.ones(n),
+                      'batch_mode': True,
+                      'num_active_gens': 1}
+             }
 
 if nworkers == 3:
-    gen_specs['single_component_at_a_time'] = True
-    gen_specs['components'] = 1
-    gen_specs['combine_component_func'] = np.linalg.norm
+    gen_specs['user']['single_component_at_a_time'] = True
+    gen_specs['user']['components'] = 1
+    gen_specs['user']['combine_component_func'] = np.linalg.norm
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
diff --git a/libensemble/tests/regression_tests/test_worker_exceptions.py b/libensemble/tests/regression_tests/test_worker_exceptions.py
index 4ba4ab3be..5d19c06c1 100644
--- a/libensemble/tests/regression_tests/test_worker_exceptions.py
+++ b/libensemble/tests/regression_tests/test_worker_exceptions.py
@@ -29,11 +29,12 @@
 gen_specs = {'gen_f': gen_f,
              'in': [],
              'out': [('x', float, 2)],
-             'lb': np.array([-3, -2]),
-             'ub': np.array([3, 2]),
-             'initial_sample': 100,
-             'batch_mode': True,
-             'num_active_gens': 1}
+             'user': {'lb': np.array([-3, -2]),
+                      'ub': np.array([3, 2]),
+                      'initial_sample': 100,
+                      'batch_mode': True,
+                      'num_active_gens': 1}
+             }
 
 persis_info = per_worker_stream({}, nworkers + 1)
 

From 60f34daae875f6d2123020ec39ac9f4b61b23215 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 30 Oct 2019 16:45:30 -0500
Subject: [PATCH 378/644] Formating one calling script

---
 .../regression_tests/script_test_balsam_hworld.py     | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/libensemble/tests/regression_tests/script_test_balsam_hworld.py b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
index 02e201b00..08fbb9033 100644
--- a/libensemble/tests/regression_tests/script_test_balsam_hworld.py
+++ b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
@@ -48,12 +48,11 @@ def build_simfunc():
              'in': ['sim_id'],
              'out': [('x', float, (2,))],
              'save_every_k': 20,
-             'user': {
-             'lb': np.array([-3, -2]),
-             'ub': np.array([3, 2]),
-             'gen_batch_size': nworkers,
-             'batch_mode': True,
-             'num_active_gens': 1}
+             'user': {'lb': np.array([-3, -2]),
+                      'ub': np.array([3, 2]),
+                      'gen_batch_size': nworkers,
+                      'batch_mode': True,
+                      'num_active_gens': 1}
              }
 
 persis_info = per_worker_stream({}, nworkers + 1)

From b791c182278522efb4fc3ab9b33ea73357481fbf Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 30 Oct 2019 17:06:30 -0500
Subject: [PATCH 379/644] Fixing unit tests and adding one more allowed
 sim_specs key

---
 libensemble/libE.py                            |  2 +-
 libensemble/tests/unit_tests/setup.py          |  6 +++---
 .../tests/unit_tests/test_aposmm_logic.py      | 18 +++++++++---------
 3 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/libensemble/libE.py b/libensemble/libE.py
index 9e9bc7989..d609751b0 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -29,7 +29,7 @@
 # To change logging level for just this module
 # logger.setLevel(logging.DEBUG)
 
-allowed_sim_spec_keys = ['sim_f', 'in', 'out', 'sim_dir', 'clean_jobs', 'save_every_k', 'user']
+allowed_sim_spec_keys = ['sim_f', 'in', 'out', 'sim_dir', 'sim_dir_prefix', 'clean_jobs', 'save_every_k', 'user']
 allowed_gen_spec_keys = ['gen_f', 'in', 'out', 'save_every_k', 'user']
 allowed_alloc_spec_keys = ['alloc_f', 'in', 'out', 'user']
 
diff --git a/libensemble/tests/unit_tests/setup.py b/libensemble/tests/unit_tests/setup.py
index 66114bcfe..e677fe37d 100644
--- a/libensemble/tests/unit_tests/setup.py
+++ b/libensemble/tests/unit_tests/setup.py
@@ -8,7 +8,7 @@
 
 def make_criteria_and_specs_0(simx=10, n=1):
     sim_specs = {'sim_f': np.linalg.norm, 'in': ['x_on_cube'], 'out': [('f', float), ('fvec', float, 3)], }
-    gen_specs = {'gen_f': np.random.uniform, 'in': [], 'out': [('priority', float), ('local_pt', bool), ('local_min', bool), ('num_active_runs', int)], 'ub': np.ones(n), 'lb': np.zeros(n), 'nu': 0}
+    gen_specs = {'gen_f': np.random.uniform, 'in': [], 'out': [('priority', float), ('local_pt', bool), ('local_min', bool), ('num_active_runs', int)], 'user': {'ub': np.ones(n), 'lb': np.zeros(n), 'nu': 0}}
     if n == 1:
         gen_specs['out'] += [('x_on_cube', float)]
     else:
@@ -20,7 +20,7 @@ def make_criteria_and_specs_0(simx=10, n=1):
 
 def make_criteria_and_specs_1(simx=10):
     sim_specs = {'sim_f': np.linalg.norm, 'in': ['x'], 'out': [('g', float)], }
-    gen_specs = {'gen_f': np.random.uniform, 'in': [], 'out': [('x', float), ('priority', float)], }
+    gen_specs = {'gen_f': np.random.uniform, 'in': [], 'out': [('x', float), ('priority', float)], 'user': {} }
     exit_criteria = {'sim_max': simx, 'stop_val': ('g', -1), 'elapsed_wallclock_time': 0.5}
 
     return sim_specs, gen_specs, exit_criteria
@@ -28,7 +28,7 @@ def make_criteria_and_specs_1(simx=10):
 
 def make_criteria_and_specs_1A(simx=10):
     sim_specs = {'sim_f': np.linalg.norm, 'in': ['x'], 'out': [('g', float)], }
-    gen_specs = {'gen_f': np.random.uniform, 'in': [], 'out': [('x', float), ('priority', float), ('sim_id', int)], }
+    gen_specs = {'gen_f': np.random.uniform, 'in': [], 'out': [('x', float), ('priority', float), ('sim_id', int)], 'user': {} }
     exit_criteria = {'sim_max': simx, 'stop_val': ('g', -1), 'elapsed_wallclock_time': 0.5}
 
     return sim_specs, gen_specs, exit_criteria
diff --git a/libensemble/tests/unit_tests/test_aposmm_logic.py b/libensemble/tests/unit_tests/test_aposmm_logic.py
index 9d0adfd0a..7dfc22ed4 100644
--- a/libensemble/tests/unit_tests/test_aposmm_logic.py
+++ b/libensemble/tests/unit_tests/test_aposmm_logic.py
@@ -26,10 +26,10 @@ def test_failing_localopt_method():
 
     hist.H['returned'] = 1
 
-    gen_specs_0['localopt_method'] = 'BADNAME'
+    gen_specs_0['user']['localopt_method'] = 'BADNAME'
 
     try:
-        al.advance_local_run(hist.H, gen_specs_0, 0, 0, {'run_order': {0: [0, 1]}})
+        al.advance_local_run(hist.H, gen_specs_0['user'], 0, 0, {'run_order': {0: [0, 1]}})
     except al.APOSMMException:
         assert 1, "Failed like it should have"
     else:
@@ -41,9 +41,9 @@ def test_exception_raising():
     hist.H['returned'] = 1
 
     for method in ['LN_SBPLX', 'pounders', 'scipy_COBYLA']:
-        gen_specs_0['localopt_method'] = method
+        gen_specs_0['user']['localopt_method'] = method
 
-        out = al.advance_local_run(hist.H, gen_specs_0, 0, 0, {'run_order': {0: [0, 1]}})
+        out = al.advance_local_run(hist.H, gen_specs_0['user'], 0, 0, {'run_order': {0: [0, 1]}})
 
         assert out[0] == 0, "Failed like it should have"
 
@@ -100,11 +100,11 @@ def test_localopt_error_saving():
     H['f'] = np.random.uniform(0, 1, 4)
     H['returned'] = True
     H['local_pt'][1:] = True
-    gen_specs_0['initial_sample_size'] = 1
-    gen_specs_0['localopt_method'] = 'scipy_COBYLA'
-    gen_specs_0['tol'] = 0.1
-    gen_specs_0['ub'] = np.ones(2)
-    gen_specs_0['lb'] = np.zeros(2)
+    gen_specs_0['user']['initial_sample_size'] = 1
+    gen_specs_0['user']['localopt_method'] = 'scipy_COBYLA'
+    gen_specs_0['user']['tol'] = 0.1
+    gen_specs_0['user']['ub'] = np.ones(2)
+    gen_specs_0['user']['lb'] = np.zeros(2)
 
     persis_info_1 = {'run_order': {0: [1, 2, 3]},
                      'old_runs': {},

From c81ad46d8760206e85fe7a51690e659bb464fce4 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 30 Oct 2019 17:11:28 -0500
Subject: [PATCH 380/644] Flake8 changes

---
 libensemble/gen_funcs/aposmm.py                            | 6 +++---
 libensemble/gen_funcs/persistent_aposmm.py                 | 4 ++--
 libensemble/libE.py                                        | 7 ++++---
 libensemble/tests/regression_tests/test_1d_sampling.py     | 2 +-
 .../test_1d_uniform_sampling_with_comm_dup.py              | 2 +-
 .../test_6-hump_camel_active_persistent_worker_abort.py    | 4 ++--
 .../regression_tests/test_6-hump_camel_uniform_sampling.py | 4 ++--
 libensemble/tests/unit_tests/setup.py                      | 4 ++--
 8 files changed, 17 insertions(+), 16 deletions(-)

diff --git a/libensemble/gen_funcs/aposmm.py b/libensemble/gen_funcs/aposmm.py
index 3fab1459b..de2001db8 100644
--- a/libensemble/gen_funcs/aposmm.py
+++ b/libensemble/gen_funcs/aposmm.py
@@ -491,8 +491,8 @@ def advance_local_run(H, user_specs, c_flag, run, persis_info):
         advance_local_run.pt_in_run = 0
 
         if user_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA',
-                                            'LN_COBYLA', 'LN_NELDERMEAD',
-                                            'LD_MMA']:
+                                             'LN_COBYLA', 'LN_NELDERMEAD',
+                                             'LD_MMA']:
 
             if user_specs['localopt_method'] in ['LD_MMA']:
                 fields_to_pass = ['x_on_cube', 'f', 'grad']
@@ -900,7 +900,7 @@ def initialize_APOSMM(H, gen_specs):
 
     if 'single_component_at_a_time' in user_specs and user_specs['single_component_at_a_time']:
         assert user_specs['batch_mode'], ("Must be in batch mode when using "
-                                         "'single_component_at_a_time'")
+                                          "'single_component_at_a_time'")
         c_flag = True
     else:
         c_flag = False
diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 13f9d8f40..7b085afd9 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -195,7 +195,7 @@ def aposmm(H, persis_info, gen_specs, libE_info):
     if user_specs['localopt_method'] in ['LD_MMA', 'blmvm']:
         fields_to_pass = ['x_on_cube', 'f', 'grad']
     elif user_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA',
-                                          'LN_NELDERMEAD', 'scipy_Nelder-Mead']:
+                                           'LN_NELDERMEAD', 'scipy_Nelder-Mead']:
         fields_to_pass = ['x_on_cube', 'f']
     elif user_specs['localopt_method'] in ['pounders']:
         fields_to_pass = ['x_on_cube', 'fvec']
@@ -386,7 +386,7 @@ def nlopt_callback_fun(x, grad, comm_queue, child_can_read, parent_can_read, use
         grad[:] = grad_recv
     else:
         assert user_specs['localopt_method'] in ['LN_SBPLX', 'LN_BOBYQA',
-                                                'LN_COBYLA', 'LN_NELDERMEAD', 'LD_MMA']
+                                                 'LN_COBYLA', 'LN_NELDERMEAD', 'LD_MMA']
         x_recv, f_recv = comm_queue.get()
 
     assert np.array_equal(x, x_recv), "The point I gave is not the point I got back!"
diff --git a/libensemble/libE.py b/libensemble/libE.py
index d609751b0..4fc801de2 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -33,6 +33,7 @@
 allowed_gen_spec_keys = ['gen_f', 'in', 'out', 'save_every_k', 'user']
 allowed_alloc_spec_keys = ['alloc_f', 'in', 'out', 'user']
 
+
 def report_manager_exception(hist, persis_info, mgr_exc=None):
     "Write out exception manager exception to log."
     if mgr_exc is not None:
@@ -481,7 +482,7 @@ def check_alloc_specs(alloc_specs):
     assert alloc_specs['alloc_f'], "Allocation function must be specified"
 
     for k in alloc_specs.keys():
-        assert k in allowed_alloc_spec_keys, "Key %s is not allowed in alloc_specs. Supported keys are: %s " % (k,allowed_alloc_spec_keys)
+        assert k in allowed_alloc_spec_keys, "Key %s is not allowed in alloc_specs. Supported keys are: %s " % (k, allowed_alloc_spec_keys)
 
 
 def check_sim_specs(sim_specs):
@@ -493,7 +494,7 @@ def check_sim_specs(sim_specs):
     assert isinstance(sim_specs['in'], list), "'in' field must exist and be a list of field names"
 
     for k in sim_specs.keys():
-        assert k in allowed_sim_spec_keys, "Key %s is not allowed in sim_specs. Supported keys are: %s " % (k,allowed_sim_spec_keys)
+        assert k in allowed_sim_spec_keys, "Key %s is not allowed in sim_specs. Supported keys are: %s " % (k, allowed_sim_spec_keys)
 
 
 def check_gen_specs(gen_specs):
@@ -501,7 +502,7 @@ def check_gen_specs(gen_specs):
     assert not bool(gen_specs) or len(gen_specs['out']), "gen_specs must have 'out' entries"
 
     for k in gen_specs.keys():
-        assert k in allowed_gen_spec_keys, "Key %s is not allowed in gen_specs. Supported keys are: %s " % (k,allowed_gen_spec_keys)
+        assert k in allowed_gen_spec_keys, "Key %s is not allowed in gen_specs. Supported keys are: %s " % (k, allowed_gen_spec_keys)
 
 
 def check_exit_criteria(exit_criteria, sim_specs, gen_specs):
diff --git a/libensemble/tests/regression_tests/test_1d_sampling.py b/libensemble/tests/regression_tests/test_1d_sampling.py
index ea55ad0e3..cea7d39ac 100644
--- a/libensemble/tests/regression_tests/test_1d_sampling.py
+++ b/libensemble/tests/regression_tests/test_1d_sampling.py
@@ -31,7 +31,7 @@
              'user': {'gen_batch_size': 500,
                       'lb': np.array([-3]),
                       'ub': np.array([3]),
-                     }
+                      }
              }
 
 persis_info = per_worker_stream({}, nworkers + 1)
diff --git a/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py b/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
index dd5cc05a7..e4913bec6 100644
--- a/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
+++ b/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
@@ -49,7 +49,7 @@
              'user': {'lb': np.array([-3]),
                       'ub': np.array([3]),
                       'gen_batch_size': 500
-                     }
+                      }
              }
 
 persis_info = per_worker_stream({}, nworkers + 1)
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py b/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py
index 40c9d639a..a96beedcc 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py
@@ -42,8 +42,8 @@
                       'num_active_gens': 1,
                       'dist_to_bound_multiple': 0.5,
                       'localopt_maxeval': 4
-                     }
-            }
+                      }
+             }
 
 alloc_specs = {'alloc_f': alloc_f, 'out': gen_out}
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
index e1c74b961..87cbfc508 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
@@ -37,8 +37,8 @@
              'save_every_k': 300,          # Tell libE to save every 300 gen entries
              'user': {'gen_batch_size': 500,        # Tell gen_f how much to generate per call
                       'lb': np.array([-3, -2]),     # Tell gen_f lower bounds
-                      'ub': np.array([3, 2]),       # Tell gen_f upper bounds
-                     }
+                      'ub': np.array([3, 2])        # Tell gen_f upper bounds
+                      }
              }
 # end_gen_specs_rst_tag
 
diff --git a/libensemble/tests/unit_tests/setup.py b/libensemble/tests/unit_tests/setup.py
index e677fe37d..a07da9bac 100644
--- a/libensemble/tests/unit_tests/setup.py
+++ b/libensemble/tests/unit_tests/setup.py
@@ -20,7 +20,7 @@ def make_criteria_and_specs_0(simx=10, n=1):
 
 def make_criteria_and_specs_1(simx=10):
     sim_specs = {'sim_f': np.linalg.norm, 'in': ['x'], 'out': [('g', float)], }
-    gen_specs = {'gen_f': np.random.uniform, 'in': [], 'out': [('x', float), ('priority', float)], 'user': {} }
+    gen_specs = {'gen_f': np.random.uniform, 'in': [], 'out': [('x', float), ('priority', float)], 'user': {}}
     exit_criteria = {'sim_max': simx, 'stop_val': ('g', -1), 'elapsed_wallclock_time': 0.5}
 
     return sim_specs, gen_specs, exit_criteria
@@ -28,7 +28,7 @@ def make_criteria_and_specs_1(simx=10):
 
 def make_criteria_and_specs_1A(simx=10):
     sim_specs = {'sim_f': np.linalg.norm, 'in': ['x'], 'out': [('g', float)], }
-    gen_specs = {'gen_f': np.random.uniform, 'in': [], 'out': [('x', float), ('priority', float), ('sim_id', int)], 'user': {} }
+    gen_specs = {'gen_f': np.random.uniform, 'in': [], 'out': [('x', float), ('priority', float), ('sim_id', int)], 'user': {}}
     exit_criteria = {'sim_max': simx, 'stop_val': ('g', -1), 'elapsed_wallclock_time': 0.5}
 
     return sim_specs, gen_specs, exit_criteria

From 559f795c1722175724d69bbf2d67c9dcbe6c5977 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 08:36:16 -0500
Subject: [PATCH 381/644] Adjusting forces to use 'user' fields

---
 libensemble/libE.py                           |  2 +-
 .../tests/scaling_tests/forces/forces_simf.py | 18 +++++------
 .../scaling_tests/forces/run_libe_forces.py   | 32 ++++++++++---------
 3 files changed, 27 insertions(+), 25 deletions(-)

diff --git a/libensemble/libE.py b/libensemble/libE.py
index 4fc801de2..14409d7ad 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -29,7 +29,7 @@
 # To change logging level for just this module
 # logger.setLevel(logging.DEBUG)
 
-allowed_sim_spec_keys = ['sim_f', 'in', 'out', 'sim_dir', 'sim_dir_prefix', 'clean_jobs', 'save_every_k', 'user']
+allowed_sim_spec_keys = ['sim_f', 'in', 'out', 'sim_dir', 'sim_dir_prefix', 'clean_jobs', 'save_every_k', 'profile', 'user']
 allowed_gen_spec_keys = ['gen_f', 'in', 'out', 'save_every_k', 'user']
 allowed_alloc_spec_keys = ['alloc_f', 'in', 'out', 'user']
 
diff --git a/libensemble/tests/scaling_tests/forces/forces_simf.py b/libensemble/tests/scaling_tests/forces/forces_simf.py
index 99360ff57..7988d031a 100644
--- a/libensemble/tests/scaling_tests/forces/forces_simf.py
+++ b/libensemble/tests/scaling_tests/forces/forces_simf.py
@@ -45,17 +45,17 @@ def run_forces(x, persis_info, sim_specs, libE_info):
 
     calc_status = 0  # Returns to worker
 
-    simdir_basename = sim_specs['simdir_basename']
-    # cores           = sim_specs['cores']
-    keys = sim_specs['keys']
-    sim_particles = sim_specs['sim_particles']
-    sim_timesteps = sim_specs['sim_timesteps']
-    time_limit = sim_specs['sim_kill_minutes'] * 60.0
+    simdir_basename = sim_specs['user']['simdir_basename']
+    # cores           = sim_specs['user']['cores']
+    keys = sim_specs['user']['keys']
+    sim_particles = sim_specs['user']['sim_particles']
+    sim_timesteps = sim_specs['user']['sim_timesteps']
+    time_limit = sim_specs['user']['sim_kill_minutes'] * 60.0
 
     # Get from dictionary if key exists, else return default (e.g. 0)
-    cores = sim_specs.get('cores', None)
-    kill_rate = sim_specs.get('kill_rate', 0)
-    particle_variance = sim_specs.get('particle_variance', 0)
+    cores = sim_specs['user'].get('cores', None)
+    kill_rate = sim_specs['user'].get('kill_rate', 0)
+    particle_variance = sim_specs['user'].get('particle_variance', 0)
 
     # Composing variable names and x values to set up simulation
     # arguments = []
diff --git a/libensemble/tests/scaling_tests/forces/run_libe_forces.py b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
index 21eab128e..1b1439d3e 100644
--- a/libensemble/tests/scaling_tests/forces/run_libe_forces.py
+++ b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
@@ -69,17 +69,18 @@
 sim_specs = {'sim_f': run_forces,         # Function whose output is being minimized
              'in': ['x'],                 # Name of input data structure for sim func
              'out': [('energy', float)],  # Output from sim func
-             'keys': ['seed'],            # Key/keys for input data
              'sim_dir': './sim',          # Sim dir to be copied for each worker
-             'sim_dir_suffix': 'test',    # Suffix for copied sim dirs (to ID run)
              'profile': False,            # Don't have libE profile run
-             'simdir_basename': 'force',  # Used by sim_f to name sim directories
-             'cores': 2,                  # Used by sim_f to set number of cores used
-             'sim_particles': 1e3,        # Used by sim_f for number of particles
-             'sim_timesteps': 5,          # Used by sim_f for number of timesteps
-             'sim_kill_minutes': 10.0,    # Used by sim_f to set max run time
-             'particle_variance': 0.2,    # Used by sim_f to vary load imbalance
-             'kill_rate': 0.5,            # Fraction of bad sim_f evals (tests kills)
+             'user': {'sim_dir_suffix': 'test',    # Suffix for copied sim dirs (to ID run)
+                      'simdir_basename': 'force',  # Used by sim_f to name sim directories
+                      'keys': ['seed'],            # Key/keys for input data
+                      'cores': 2,                  # Used by sim_f to set number of cores used
+                      'sim_particles': 1e3,        # Used by sim_f for number of particles
+                      'sim_timesteps': 5,          # Used by sim_f for number of timesteps
+                      'sim_kill_minutes': 10.0,    # Used by sim_f to set max run time
+                      'particle_variance': 0.2,    # Used by sim_f to vary load imbalance
+                      'kill_rate': 0.5,            # Fraction of bad sim_f evals (tests kills)
+                      }
              }
 # end_sim_specs_rst_tag
 
@@ -87,12 +88,13 @@
 gen_specs = {'gen_f': uniform_random_sample,  # Generator function
              'in': ['sim_id'],                # Generator input
              'out': [('x', float, (1,))],     # Name, type and size of data produced (must match sim_specs 'in')
-             'lb': np.array([0]),             # Lower bound for random sample array (1D)
-             'ub': np.array([32767]),         # Upper bound for random sample array (1D)
-             'gen_batch_size': 1000,          # How many random samples to generate in one call
-             'batch_mode': True,              # If true wait for sims to process before generate more
-             'num_active_gens': 1,            # Only one active generator at a time.
-             'save_every_k': 1000             # Save every K steps
+             'save_every_k': 1000,             # Save every K steps
+             'user': {'lb': np.array([0]),             # Lower bound for random sample array (1D)
+                      'ub': np.array([32767]),         # Upper bound for random sample array (1D)
+                      'gen_batch_size': 1000,          # How many random samples to generate in one call
+                      'batch_mode': True,              # If true wait for sims to process before generate more
+                      'num_active_gens': 1,            # Only one active generator at a time.
+                      }
              }
 
 # Maximum number of simulations

From d3153a5eb8cdf48c25f73aea9a9c437f81904469 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 09:51:30 -0500
Subject: [PATCH 382/644] Fixing 'user' in a sim_func

---
 libensemble/sim_funcs/six_hump_camel.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/sim_funcs/six_hump_camel.py b/libensemble/sim_funcs/six_hump_camel.py
index 8848c638b..7f51e14d8 100644
--- a/libensemble/sim_funcs/six_hump_camel.py
+++ b/libensemble/sim_funcs/six_hump_camel.py
@@ -91,7 +91,7 @@ def six_hump_camel_simple(x, persis_info, sim_specs, _):
 
     O['f'] = six_hump_camel_func(x[0][0])
 
-    if 'pause_time' in sim_specs:
+    if 'pause_time' in sim_specs['user']:
         time.sleep(sim_specs['user']['pause_time'])
 
     return O, persis_info

From 1f9edc24eecf38d24d59f751ad2cd11d522f175d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 09:51:52 -0500
Subject: [PATCH 383/644] Testing persistent_aposmm handling of unrecognized
 localopt names

---
 .../unit_tests/test_persistent_aposmm.py      | 24 +++++++++++++++++++
 1 file changed, 24 insertions(+)
 create mode 100644 libensemble/tests/unit_tests/test_persistent_aposmm.py

diff --git a/libensemble/tests/unit_tests/test_persistent_aposmm.py b/libensemble/tests/unit_tests/test_persistent_aposmm.py
new file mode 100644
index 000000000..94ddb1282
--- /dev/null
+++ b/libensemble/tests/unit_tests/test_persistent_aposmm.py
@@ -0,0 +1,24 @@
+import numpy as np
+import libensemble.gen_funcs.persistent_aposmm as al
+import libensemble.tests.unit_tests.setup as setup
+
+libE_specs = {'comm': {}}
+
+def test_persis_apossm_localopt_test():
+    _, _, gen_specs_0, _, _ = setup.hist_setup1()
+
+    H = np.zeros(4, dtype=[('f', float), ('returned', bool)])
+    gen_specs_0['user']['localopt_method'] = 'BADNAME'
+    gen_specs_0['user']['ub'] = np.ones(2)
+    gen_specs_0['user']['lb'] = np.zeros(2)
+
+    try:
+        al.aposmm(H, {}, gen_specs_0, libE_specs)
+    except NotImplementedError:
+        assert 1, "Failed because method is unknown."
+    else:
+        assert 0
+
+
+if __name__ == "__main__":
+    test_persis_apossm_localopt_test()

From 679043ddcfb08ca610faf1b4d97e0d623cde03d2 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 10:03:04 -0500
Subject: [PATCH 384/644] flake8

---
 libensemble/tests/unit_tests/test_persistent_aposmm.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/libensemble/tests/unit_tests/test_persistent_aposmm.py b/libensemble/tests/unit_tests/test_persistent_aposmm.py
index 94ddb1282..53648abc0 100644
--- a/libensemble/tests/unit_tests/test_persistent_aposmm.py
+++ b/libensemble/tests/unit_tests/test_persistent_aposmm.py
@@ -4,6 +4,7 @@
 
 libE_specs = {'comm': {}}
 
+
 def test_persis_apossm_localopt_test():
     _, _, gen_specs_0, _, _ = setup.hist_setup1()
 

From 9d813c8224ef7e81d9b62953a50ec123d1806eac Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 10:56:59 -0500
Subject: [PATCH 385/644] Starting reorg of specs


From b97d770b3830d76c0927402828ffa843dcfafd86 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 31 Oct 2019 11:00:46 -0500
Subject: [PATCH 386/644] try installing balsam 3.5 via pip

---
 conda/install-balsam.py | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index 0c358c575..a25bfb474 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -11,13 +11,15 @@
 
 
 def install_balsam():
-    # Installs Balsam in a directory on the same level as the current directory.
-    here = os.getcwd()
-    balsamclone = 'git clone https://github.com/balsam-alcf/balsam.git ../balsam'
-    subprocess.check_call(balsamclone.split())
-    os.chdir('../balsam')
-    subprocess.check_call('pip install -e .'.split())
-    os.chdir(here)
+    # Installs Balsam
+    balsaminstall = 'pip install -Iv balsam-flow==0.3.5'
+    subprocess.check_call(balsaminstall.split())
+    # here = os.getcwd()
+    # balsamclone = 'git clone https://github.com/balsam-alcf/balsam.git ../balsam'
+    # subprocess.check_call(balsamclone.split())
+    # os.chdir('../balsam')
+    # subprocess.check_call('pip install -e .'.split())
+    # os.chdir(here)
 
 
 def move_test_balsam(balsam_test):

From 87a0065f6b819109f2e14e03f84729082c09e2ec Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 31 Oct 2019 11:27:57 -0500
Subject: [PATCH 387/644] remove unneeded options (?)

---
 conda/install-balsam.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index a25bfb474..cc71af28b 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -12,7 +12,7 @@
 
 def install_balsam():
     # Installs Balsam
-    balsaminstall = 'pip install -Iv balsam-flow==0.3.5'
+    balsaminstall = 'pip install balsam-flow==0.3.5'
     subprocess.check_call(balsaminstall.split())
     # here = os.getcwd()
     # balsamclone = 'git clone https://github.com/balsam-alcf/balsam.git ../balsam'

From 3ddfcc71964d101f9eec120d4692fcd001e1bfdd Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 12:15:30 -0500
Subject: [PATCH 388/644] Enforcing libE_specs too, and moving things to
 libE_specs

---
 libensemble/libE.py | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/libensemble/libE.py b/libensemble/libE.py
index 14409d7ad..ed1efa1d0 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -29,9 +29,10 @@
 # To change logging level for just this module
 # logger.setLevel(logging.DEBUG)
 
-allowed_sim_spec_keys = ['sim_f', 'in', 'out', 'sim_dir', 'sim_dir_prefix', 'clean_jobs', 'save_every_k', 'profile', 'user']
-allowed_gen_spec_keys = ['gen_f', 'in', 'out', 'save_every_k', 'user']
+allowed_sim_spec_keys = ['sim_f', 'in', 'out', 'user']
+allowed_gen_spec_keys = ['gen_f', 'in', 'out', 'user']
 allowed_alloc_spec_keys = ['alloc_f', 'in', 'out', 'user']
+allowed_libE_spec_keys = ['sim_dir', 'sim_dir_prefix', 'clean_jobs', 'save_every_k_sims', 'save_every_k_gens', 'profile_worker']
 
 
 def report_manager_exception(hist, persis_info, mgr_exc=None):
@@ -476,6 +477,9 @@ def check_libE_specs(libE_specs, serial_check=False):
         # TODO, differentiate and test SSH/Client
         assert libE_specs['nprocesses'] >= 1, "Must specify at least one worker"
 
+    for k in libE_specs.keys():
+        assert k in allowed_libE_spec_keys, "Key %s is not allowed in libE_specs. Supported keys are: %s " % (k, allowed_libE_spec_keys)
+
 
 def check_alloc_specs(alloc_specs):
     assert isinstance(alloc_specs, dict), "alloc_specs must be a dictionary"

From 5b0defc428bb84d3cc3657cf961b8a45968caf6d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 12:20:42 -0500
Subject: [PATCH 389/644] Making a spot to (in source) document the various
 spec keys

---
 libensemble/libE.py | 29 +++++++++++++++++++++++++----
 1 file changed, 25 insertions(+), 4 deletions(-)

diff --git a/libensemble/libE.py b/libensemble/libE.py
index ed1efa1d0..f2b349255 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -29,10 +29,31 @@
 # To change logging level for just this module
 # logger.setLevel(logging.DEBUG)
 
-allowed_sim_spec_keys = ['sim_f', 'in', 'out', 'user']
-allowed_gen_spec_keys = ['gen_f', 'in', 'out', 'user']
-allowed_alloc_spec_keys = ['alloc_f', 'in', 'out', 'user']
-allowed_libE_spec_keys = ['sim_dir', 'sim_dir_prefix', 'clean_jobs', 'save_every_k_sims', 'save_every_k_gens', 'profile_worker']
+allowed_sim_spec_keys = ['sim_f',  #
+                         'in',     #
+                         'out',    #
+                         'user']   #
+
+allowed_gen_spec_keys = ['gen_f',  #
+                         'in',     #
+                         'out',    #
+                         'user']   #
+
+allowed_alloc_spec_keys = ['alloc_f',  #
+                           'in',       #
+                           'out',      #
+                           'user']     #
+
+allowed_libE_spec_keys = ['comms',               #
+                          'comm',                #
+                          'nprocesses',          #
+                          'abort_on_exception',  #
+                          'sim_dir',             #
+                          'sim_dir_prefix',      #
+                          'clean_jobs',          #
+                          'save_every_k_sims',   #
+                          'save_every_k_gens',   #
+                          'profile_worker']      #
 
 
 def report_manager_exception(hist, persis_info, mgr_exc=None):

From d8a7f624edcc4008ebf3f7cf8cf2e363b211c46e Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 13:04:58 -0500
Subject: [PATCH 390/644] Adding option to only run MPI tests (to speed up
 testing)

---
 libensemble/tests/run-tests.sh | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/libensemble/tests/run-tests.sh b/libensemble/tests/run-tests.sh
index 669ee5d5d..a481b6098 100755
--- a/libensemble/tests/run-tests.sh
+++ b/libensemble/tests/run-tests.sh
@@ -9,6 +9,7 @@ export RUN_UNIT_TESTS=true    #Recommended for pre-push / CI tests
 export RUN_COV_TESTS=true     #Provide coverage report
 export RUN_REG_TESTS=true     #Recommended for pre-push / CI tests
 export RUN_PEP_TESTS=false     #Code syle conventions
+export RUN_ONLY_MPI=false
 
 # Regression test options
 #export REG_TEST_LIST='test_number1.py test_number2.py' #selected/ordered
@@ -179,7 +180,7 @@ RTEST_SHOW_OUT_ERR=false
 
 usage() {
   echo -e "\nUsage:"
-  echo "  $0 [-hcsurz] [-p <2|3>] [-n <string>] [-a <string>]" 1>&2;
+  echo "  $0 [-hcsurmz] [-p <2|3>] [-n <string>] [-a <string>]" 1>&2;
   echo ""
   echo "Options:"
   echo "  -h              Show this help message and exit"
@@ -188,6 +189,7 @@ usage() {
   echo "  -z              Print stdout and stderr to screen when running regression tests (run without pytest)"
   echo "  -u              Run only the unit tests"
   echo "  -r              Run only the regression tests"
+  echo "  -m              Run the regression tests only using MPI"
   echo "  -p {version}    Select a version of python. E.g. -p 2 will run with the python2 exe"
   echo "                  Note: This will literally run the python2/python3 exe. Default runs python"
   echo "  -n {name}       Supply a name to this test run"
@@ -196,7 +198,7 @@ usage() {
   exit 1
 }
 
-while getopts ":p:n:a:hcszur" opt; do
+while getopts ":p:n:a:hcszurm" opt; do
   case $opt in
     p)
       echo "Parameter supplied for Python version: $OPTARG" >&2
@@ -230,6 +232,10 @@ while getopts ":p:n:a:hcszur" opt; do
       echo "Running only the regression tests"
       export RUN_UNIT_TESTS=false
       ;;
+    m)
+      echo "Running only the MPI regression tests"
+      export RUN_ONLY_MPI=true
+      ;;
     h)
       usage
       ;;
@@ -308,6 +314,7 @@ tput sgr 0
 echo -e "Selected:"
 [ $RUN_UNIT_TESTS = "true" ] && echo -e "Unit Tests"
 [ $RUN_REG_TESTS = "true" ]  && echo -e "Regression Tests"
+[ $RUN_ONLY_MPI = "true" ]  && echo -e "Only MPI Regression Tests"
 [ $RUN_COV_TESTS = "true" ]  && echo -e "Including coverage analysis"
 [ $RUN_PEP_TESTS = "true" ]  && echo -e "PEP Code Standard Tests (static code test)"
 
@@ -412,6 +419,10 @@ if [ "$root_found" = true ]; then
       COMMS_LIST=$(sed -n '/# TESTSUITE_COMMS/s/# TESTSUITE_COMMS: //p' $TEST_SCRIPT)
       for LAUNCHER in $COMMS_LIST
       do
+        if [ "$RUN_ONLY_MPI" = true ] && [ "$LAUNCHER" != mpi ]; then
+          echo "Skipping non MPI testnumber 5"
+          continue
+        fi
         #Need proc count here for now - still stop on failure etc.
         NPROCS_LIST=$(sed -n '/# TESTSUITE_NPROCS/s/# TESTSUITE_NPROCS: //p' $TEST_SCRIPT)
         for NPROCS in $NPROCS_LIST

From 33c629e98f59e861be9e1fc570e0be58294b3643 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 13:06:04 -0500
Subject: [PATCH 391/644] Moving regression test specs to libE_specs

---
 libensemble/libE.py                                      | 5 +++++
 .../tests/regression_tests/script_test_balsam_hworld.py  | 8 +++++---
 libensemble/tests/regression_tests/test_1d_sampling.py   | 2 +-
 .../test_1d_uniform_sampling_with_comm_dup.py            | 1 -
 .../test_6-hump_camel_persistent_aposmm_1.py             | 4 ++--
 .../test_6-hump_camel_persistent_aposmm_3.py             | 2 +-
 .../test_6-hump_camel_persistent_aposmm_4.py             | 2 +-
 .../test_6-hump_camel_uniform_sampling.py                | 4 ++--
 .../test_branin_aposmm_nlopt_and_then_scipy.py           | 9 +++++----
 libensemble/tests/regression_tests/test_comms.py         | 1 -
 .../tests/regression_tests/test_jobcontroller_hworld.py  | 2 --
 11 files changed, 22 insertions(+), 18 deletions(-)

diff --git a/libensemble/libE.py b/libensemble/libE.py
index f2b349255..2650ba296 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -46,7 +46,12 @@
 
 allowed_libE_spec_keys = ['comms',               #
                           'comm',                #
+                          'ip',                  #
+                          'port',                #
+                          'authkey',             #
+                          'workerID',            #
                           'nprocesses',          #
+                          'worker_cmd',          #
                           'abort_on_exception',  #
                           'sim_dir',             #
                           'sim_dir_prefix',      #
diff --git a/libensemble/tests/regression_tests/script_test_balsam_hworld.py b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
index 08fbb9033..3a58b2c2d 100644
--- a/libensemble/tests/regression_tests/script_test_balsam_hworld.py
+++ b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
@@ -24,7 +24,11 @@ def build_simfunc():
     subprocess.check_call(buildstring.split())
 
 
-libE_specs = {'comm': MPI.COMM_WORLD, 'comms': 'mpi'}
+libE_specs = {'comm': MPI.COMM_WORLD,
+              'comms': 'mpi',
+              'save_every_k_sims': 400,
+              'save_every_k_gens': 20,
+              }
 
 nworkers = MPI.COMM_WORLD.Get_size() - 1
 is_master = MPI.COMM_WORLD.Get_rank() == 0
@@ -41,13 +45,11 @@ def build_simfunc():
 sim_specs = {'sim_f': sim_f,
              'in': ['x'],
              'out': [('f', float), ('cstat', int)],
-             'save_every_k': 400,
              'user': {'cores': cores_per_job}}
 
 gen_specs = {'gen_f': gen_f,
              'in': ['sim_id'],
              'out': [('x', float, (2,))],
-             'save_every_k': 20,
              'user': {'lb': np.array([-3, -2]),
                       'ub': np.array([3, 2]),
                       'gen_batch_size': nworkers,
diff --git a/libensemble/tests/regression_tests/test_1d_sampling.py b/libensemble/tests/regression_tests/test_1d_sampling.py
index cea7d39ac..626d08ed6 100644
--- a/libensemble/tests/regression_tests/test_1d_sampling.py
+++ b/libensemble/tests/regression_tests/test_1d_sampling.py
@@ -22,12 +22,12 @@
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
+libE_specs['save_every_k_gens'] = 300
 
 sim_specs = {'sim_f': sim_f, 'in': ['x'], 'out': [('f', float)]}
 
 gen_specs = {'gen_f': gen_f,
              'out': [('x', float, (1,))],
-             'save_every_k': 300,
              'user': {'gen_batch_size': 500,
                       'lb': np.array([-3]),
                       'ub': np.array([3]),
diff --git a/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py b/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
index e4913bec6..8e25f531c 100644
--- a/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
+++ b/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
@@ -45,7 +45,6 @@
 gen_specs = {'gen_f': gen_f,
              'in': ['sim_id'],
              'out': [('x', float, (1,))],
-             'save_every_k': 300,
              'user': {'lb': np.array([-3]),
                       'ub': np.array([3]),
                       'gen_batch_size': 500
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
index e112e8688..06166be75 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
@@ -46,8 +46,7 @@
 gen_specs = {'gen_f': gen_f,
              'in': [],
              'out': gen_out,
-             'user': {'batch_mode': True,
-                      'initial_sample_size': 100,
+             'user': {'initial_sample_size': 100,
                       'sample_points': np.round(minima, 1),
                       'localopt_method': 'LD_MMA',
                       'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
@@ -55,6 +54,7 @@
                       'ftol_rel': 1e-6,
                       'num_active_gens': 1,
                       'max_active_runs': 6,
+                      'batch_mode': True,
                       'lb': np.array([-3, -2]),
                       'ub': np.array([3, 2])}
              }
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
index 7fe9264c5..67f2ebc13 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
@@ -48,7 +48,6 @@
              'out': gen_out,
              'user': {'initial_sample_size': 100,
                       'sample_points': np.round(minima, 1),
-                      'batch_mode': True,
                       'localopt_method': 'blmvm',
                       'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
                       'grtol': 1e-4,
@@ -56,6 +55,7 @@
                       'num_active_gens': 1,
                       'dist_to_bound_multiple': 0.5,
                       'max_active_runs': 6,
+                      'batch_mode': True,
                       'lb': np.array([-3, -2]),
                       'ub': np.array([3, 2])}
              }
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
index 288ce5980..126ed3e33 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
@@ -46,7 +46,6 @@
              'in': [],
              'out': gen_out,
              'user': {'initial_sample_size': 100,
-                      'batch_mode': True,
                       'sample_points': np.round(minima, 1),
                       'localopt_method': 'scipy_Nelder-Mead',
                       'fatol': 1e-5,
@@ -56,6 +55,7 @@
                       'num_active_gens': 1,
                       'dist_to_bound_multiple': 0.01,
                       'max_active_runs': 6,
+                      'batch_mode': True,
                       'lb': np.array([-3, -2]),
                       'ub': np.array([3, 2])}
              }
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
index 87cbfc508..5aee7dc9a 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
@@ -24,17 +24,17 @@
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 
 nworkers, is_master, libE_specs, _ = parse_args()
+libE_specs['save_every_k_sims'] = 400
+libE_specs['save_every_k_gens'] = 300
 
 sim_specs = {'sim_f': sim_f,         # Function whose output is being minimized
              'in': ['x'],            # Keys to be given to the above function
              'out': [('f', float)],  # Output from the function being minimized
-             'save_every_k': 400,    # Want progress saved every 400 evals
              }
 # end_sim_specs_rst_tag
 
 gen_specs = {'gen_f': gen_f,               # Tell libE function generating sim_f input
              'out': [('x', float, (2,))],  # Tell libE gen_f output, type, size
-             'save_every_k': 300,          # Tell libE to save every 300 gen entries
              'user': {'gen_batch_size': 500,        # Tell gen_f how much to generate per call
                       'lb': np.array([-3, -2]),     # Tell gen_f lower bounds
                       'ub': np.array([3, 2])        # Tell gen_f upper bounds
diff --git a/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py b/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
index dc6089255..c77fae025 100644
--- a/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
+++ b/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
@@ -25,20 +25,21 @@
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
+libE_specs['clean_jobs'] = True
+libE_specs['sim_dir'] = pkg_resources.resource_filename('libensemble.sim_funcs.branin', ''),  # to be copied by each worker
+
 if libE_specs['comms'] == 'tcp':
     sys.exit("Cannot run with tcp when repeated calls to libE -- aborting...")
 
 sim_specs = {'sim_f': sim_f,
              'in': ['x'],
-             'out': [('f', float)],
-             'sim_dir': pkg_resources.resource_filename('libensemble.sim_funcs.branin', ''),  # to be copied by each worker
-             'clean_jobs': True}
+             'out': [('f', float)]}
 
 if nworkers == 1:
     # Have the workers put their directories in a different (e.g., a faster
     # /sandbox/ or /scratch/ directory)
     # Otherwise, will just copy in same directory as sim_dir
-    sim_specs['sim_dir_prefix'] = '~'
+    libE_specs['sim_dir_prefix'] = '~'
 elif nworkers == 3:
     sim_specs['user'] = {'uniform_random_pause_ub': 0.05}
 
diff --git a/libensemble/tests/regression_tests/test_comms.py b/libensemble/tests/regression_tests/test_comms.py
index f240621c6..8d8f084d8 100644
--- a/libensemble/tests/regression_tests/test_comms.py
+++ b/libensemble/tests/regression_tests/test_comms.py
@@ -37,7 +37,6 @@
 gen_specs = {'gen_f': gen_f,
              'in': ['sim_id'],
              'out': [('x', float, (2,))],
-             'save_every_k': 300,
              'user': {'lb': np.array([-3, -2]),
                       'ub': np.array([3, 2]),
                       'batch_mode': True,
diff --git a/libensemble/tests/regression_tests/test_jobcontroller_hworld.py b/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
index df50984ab..04220a4ae 100644
--- a/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
+++ b/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
@@ -68,14 +68,12 @@
 sim_specs = {'sim_f': sim_f,
              'in': ['x'],
              'out': [('f', float), ('cstat', int)],
-             'save_every_k': 400,
              'user': {'cores': cores_per_job}
              }
 
 gen_specs = {'gen_f': gen_f,
              'in': ['sim_id'],
              'out': [('x', float, (2,))],
-             'save_every_k': 20,
              'user': {'lb': np.array([-3, -2]),
                       'ub': np.array([3, 2]),
                       'batch_mode': True,

From 9fcc4c267e3801358065fa0f86f94644cc9d1d10 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 13:25:33 -0500
Subject: [PATCH 392/644] Moving scaling test specs to libE_specs

---
 libensemble/tests/scaling_tests/forces/run_libe_forces.py | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/libensemble/tests/scaling_tests/forces/run_libe_forces.py b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
index 1b1439d3e..9fe21d235 100644
--- a/libensemble/tests/scaling_tests/forces/run_libe_forces.py
+++ b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
@@ -69,8 +69,6 @@
 sim_specs = {'sim_f': run_forces,         # Function whose output is being minimized
              'in': ['x'],                 # Name of input data structure for sim func
              'out': [('energy', float)],  # Output from sim func
-             'sim_dir': './sim',          # Sim dir to be copied for each worker
-             'profile': False,            # Don't have libE profile run
              'user': {'sim_dir_suffix': 'test',    # Suffix for copied sim dirs (to ID run)
                       'simdir_basename': 'force',  # Used by sim_f to name sim directories
                       'keys': ['seed'],            # Key/keys for input data
@@ -88,7 +86,6 @@
 gen_specs = {'gen_f': uniform_random_sample,  # Generator function
              'in': ['sim_id'],                # Generator input
              'out': [('x', float, (1,))],     # Name, type and size of data produced (must match sim_specs 'in')
-             'save_every_k': 1000,             # Save every K steps
              'user': {'lb': np.array([0]),             # Lower bound for random sample array (1D)
                       'ub': np.array([32767]),         # Upper bound for random sample array (1D)
                       'gen_batch_size': 1000,          # How many random samples to generate in one call
@@ -97,6 +94,10 @@
                       }
              }
 
+libE_specs['save_every_k_gens'] = 1000  # Save every K steps
+libE_specs['sim_dir'] = './sim'         # Sim dir to be copied for each worker
+libE_specs['profile'] =  False,         # Don't have libE profile run
+
 # Maximum number of simulations
 sim_max = 8
 exit_criteria = {'sim_max': sim_max}

From 16f97148d1f6355192bc26c2290420934b1dab7b Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 31 Oct 2019 13:29:23 -0500
Subject: [PATCH 393/644] increment version

---
 conda/install-balsam.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index cc71af28b..c27f12fa7 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -12,7 +12,7 @@
 
 def install_balsam():
     # Installs Balsam
-    balsaminstall = 'pip install balsam-flow==0.3.5'
+    balsaminstall = 'pip install balsam-flow==0.3.6'
     subprocess.check_call(balsaminstall.split())
     # here = os.getcwd()
     # balsamclone = 'git clone https://github.com/balsam-alcf/balsam.git ../balsam'

From 3feaeb6e43b05da508373e57d7ab101726a52895 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 14:04:52 -0500
Subject: [PATCH 394/644] Adding libE_spces to worker_main

---
 libensemble/libE.py | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/libensemble/libE.py b/libensemble/libE.py
index 2650ba296..d1a942eb2 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -55,6 +55,7 @@
                           'abort_on_exception',  #
                           'sim_dir',             #
                           'sim_dir_prefix',      #
+                          'sim_dir_suffix',      #
                           'clean_jobs',          #
                           'save_every_k_sims',   #
                           'save_every_k_gens',   #
@@ -232,7 +233,7 @@ def libE_mpi(sim_specs, gen_specs, exit_criteria,
     libE_specs, mpi_comm_null = libE_mpi_defaults(libE_specs)
     comm = libE_specs['comm']
 
-    if libE_specs['comm'] == mpi_comm_null:
+    if comm == mpi_comm_null:
         return [], persis_info, 3  # Process not in comm
 
     rank = comm.Get_rank()
@@ -251,7 +252,7 @@ def libE_mpi(sim_specs, gen_specs, exit_criteria,
                                 persis_info, alloc_specs, libE_specs, H0)
 
     # Worker returns a subset of MPI output
-    libE_mpi_worker(comm, sim_specs, gen_specs, libE_specs)
+    libE_mpi_worker(sim_specs, gen_specs, libE_specs)
     return [], persis_info, []
 
 
@@ -279,19 +280,19 @@ def on_abort():
                         on_abort=on_abort)
 
 
-def libE_mpi_worker(mpi_comm, sim_specs, gen_specs, libE_specs):
+def libE_mpi_worker(sim_specs, gen_specs, libE_specs):
     "Worker routine run at ranks > 0."
 
     from libensemble.comms.mpi import MainMPIComm
-    comm = MainMPIComm(mpi_comm)
-    worker_main(comm, sim_specs, gen_specs, log_comm=True)
+    comm = MainMPIComm(libE_specs['comm'])
+    worker_main(comm, sim_specs, gen_specs, libE_specs, log_comm=True)
     logger.debug("Worker {} exiting".format(libE_specs['comm'].Get_rank()))
 
 
 # ==================== Process version =================================
-def start_proc_team(nworkers, sim_specs, gen_specs, log_comm=True):
+def start_proc_team(nworkers, sim_specs, gen_specs, libE_specs, log_comm=True):
     "Launch a process worker team."
-    wcomms = [QCommProcess(worker_main, sim_specs, gen_specs, w, log_comm)
+    wcomms = [QCommProcess(worker_main, sim_specs, gen_specs, libE_specs, w, log_comm)
               for w in range(1, nworkers+1)]
     for wcomm in wcomms:
         wcomm.run()
@@ -322,7 +323,7 @@ def libE_local(sim_specs, gen_specs, exit_criteria,
     hist = History(alloc_specs, sim_specs, gen_specs, exit_criteria, H0)
 
     # Launch worker team and set up logger
-    wcomms = start_proc_team(nworkers, sim_specs, gen_specs)
+    wcomms = start_proc_team(nworkers, sim_specs, gen_specs, libE_specs)
     manager_logging_config()
 
     # Set up cleanup routine to shut down worker team
@@ -468,7 +469,7 @@ def libE_tcp_worker(sim_specs, gen_specs, libE_specs):
     workerID = libE_specs['workerID']
 
     with ClientQCommManager(ip, port, authkey, workerID) as comm:
-        worker_main(comm, sim_specs, gen_specs,
+        worker_main(comm, sim_specs, gen_specs, libE_specs,
                     workerID=workerID, log_comm=True)
         logger.debug("Worker {} exiting".format(workerID))
 

From 18218dde83f40635a68129ce193f42cf14156b01 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 14:05:36 -0500
Subject: [PATCH 395/644] Using libE_specs['save_every_k_sims/gens]

---
 libensemble/libE_manager.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/libensemble/libE_manager.py b/libensemble/libE_manager.py
index 2b2aed25f..0bbfc48d9 100644
--- a/libensemble/libE_manager.py
+++ b/libensemble/libE_manager.py
@@ -184,13 +184,13 @@ def _save_every_k_sims(self):
         "Save history every kth sim step."
         self._save_every_k('libE_history_after_sim_{}.npy',
                            self.hist.sim_count,
-                           self.sim_specs['save_every_k'])
+                           self.libE_specs['save_every_k_sims'])
 
     def _save_every_k_gens(self):
         "Save history every kth gen step."
         self._save_every_k('libE_history_after_gen_{}.npy',
                            self.hist.index,
-                           self.gen_specs['save_every_k'])
+                           self.libE_specs['save_every_k_gens'])
 
     # --- Handle outgoing messages to workers (work orders from alloc)
 
@@ -276,9 +276,9 @@ def _receive_from_workers(self, persis_info):
                     new_stuff = True
                     self._handle_msg_from_worker(persis_info, w)
 
-        if 'save_every_k' in self.sim_specs:
+        if 'save_every_k_sims' in self.libE_specs:
             self._save_every_k_sims()
-        if 'save_every_k' in self.gen_specs:
+        if 'save_every_k_gens' in self.libE_specs:
             self._save_every_k_gens()
         return persis_info
 

From 1fa4c2350432bcd87e11668060e9e421a6a97bc3 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 14:06:16 -0500
Subject: [PATCH 396/644] Passing and using libE_specs

---
 libensemble/libE_worker.py | 30 +++++++++++++++++-------------
 1 file changed, 17 insertions(+), 13 deletions(-)

diff --git a/libensemble/libE_worker.py b/libensemble/libE_worker.py
index 1defa57a0..90791ef06 100644
--- a/libensemble/libE_worker.py
+++ b/libensemble/libE_worker.py
@@ -31,7 +31,7 @@
 job_timing = False
 
 
-def worker_main(comm, sim_specs, gen_specs, workerID=None, log_comm=True):
+def worker_main(comm, sim_specs, gen_specs, libE_specs, workerID=None, log_comm=True):
     """Evaluate calculations given to it by the manager.
 
     Creates a worker object, receives work from manager, runs worker,
@@ -49,6 +49,9 @@ def worker_main(comm, sim_specs, gen_specs, workerID=None, log_comm=True):
     gen_specs: dict
         Parameters/information for generation calculations
 
+    libE_specs: dict
+        Parameters/information for libE operations 
+
     workerID: int
         Manager assigned worker ID (if None, default is comm.rank)
 
@@ -56,7 +59,7 @@ def worker_main(comm, sim_specs, gen_specs, workerID=None, log_comm=True):
         Whether to send logging over comm
     """
 
-    if sim_specs.get('profile'):
+    if libE_specs.get('profile_worker'):
         pr = cProfile.Profile()
         pr.enable()
 
@@ -69,10 +72,10 @@ def worker_main(comm, sim_specs, gen_specs, workerID=None, log_comm=True):
         worker_logging_config(comm, workerID)
 
     # Set up and run worker
-    worker = Worker(comm, dtypes, workerID, sim_specs, gen_specs)
+    worker = Worker(comm, dtypes, workerID, sim_specs, gen_specs, libE_specs)
     worker.run()
 
-    if sim_specs.get('profile'):
+    if libE_specs.get('profile_worker'):
         pr.disable()
         profile_state_fname = 'worker_%d.prof' % (workerID)
 
@@ -120,7 +123,7 @@ class Worker:
         Stack holding directory structure of this Worker
     """
 
-    def __init__(self, comm, dtypes, workerID, sim_specs, gen_specs):
+    def __init__(self, comm, dtypes, workerID, sim_specs, gen_specs, libE_specs):
         """Initialise new worker object.
 
         """
@@ -128,6 +131,7 @@ def __init__(self, comm, dtypes, workerID, sim_specs, gen_specs):
         self.dtypes = dtypes
         self.workerID = workerID
         self.sim_specs = sim_specs
+        self.libE_specs = libE_specs
         self.calc_iter = {EVAL_SIM_TAG: 0, EVAL_GEN_TAG: 0}
         self.loc_stack = None  # Worker._make_sim_worker_dir(sim_specs, workerID)
         self._run_calc = Worker._make_runners(sim_specs, gen_specs)
@@ -135,13 +139,13 @@ def __init__(self, comm, dtypes, workerID, sim_specs, gen_specs):
         Worker._set_job_controller(self.workerID, self.comm)
 
     @staticmethod
-    def _make_sim_worker_dir(sim_specs, workerID, locs=None):
-        "Create a dir for sim workers if 'sim_dir' is in sim_specs"
+    def _make_sim_worker_dir(libE_specs, workerID, locs=None):
+        "Create a dir for sim workers if 'sim_dir' is in libE_specs"
         locs = locs or LocationStack()
-        if 'sim_dir' in sim_specs:
-            sim_dir = sim_specs['sim_dir'].rstrip('/')
-            prefix = sim_specs.get('sim_dir_prefix')
-            suffix = sim_specs.get('sim_dir_suffix', '')
+        if 'sim_dir' in libE_specs:
+            sim_dir = libE_specs['sim_dir'].rstrip('/')
+            prefix = libE_specs.get('sim_dir_prefix')
+            suffix = libE_specs.get('sim_dir_suffix', '')
             if suffix != '':
                 suffix = '_' + suffix
             worker_dir = "{}{}_worker{}".format(sim_dir, suffix, workerID)
@@ -216,7 +220,7 @@ def _handle_calc(self, Work, calc_in):
                         out = calc(calc_in, Work['persis_info'], Work['libE_info'])
 
                 elif calc_type == EVAL_SIM_TAG and not self.loc_stack:
-                    self.loc_stack = Worker._make_sim_worker_dir(self.sim_specs, self.workerID)
+                    self.loc_stack = Worker._make_sim_worker_dir(self.libE_specs, self.workerID)
                     with self.loc_stack.loc(calc_type):
                         out = calc(calc_in, Work['persis_info'], Work['libE_info'])
 
@@ -320,5 +324,5 @@ def run(self):
         else:
             self.comm.kill_pending()
         finally:
-            if self.sim_specs.get('clean_jobs') and self.loc_stack is not None:
+            if self.libE_specs.get('clean_jobs') and self.loc_stack is not None:
                 self.loc_stack.clean_locs()

From 6b641ba45c1676f362fb9a7e612166588c9e625c Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 14:07:08 -0500
Subject: [PATCH 397/644] Typo tuple

---
 .../regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py b/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
index c77fae025..cd78866a4 100644
--- a/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
+++ b/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
@@ -26,7 +26,7 @@
 nworkers, is_master, libE_specs, _ = parse_args()
 
 libE_specs['clean_jobs'] = True
-libE_specs['sim_dir'] = pkg_resources.resource_filename('libensemble.sim_funcs.branin', ''),  # to be copied by each worker
+libE_specs['sim_dir'] = pkg_resources.resource_filename('libensemble.sim_funcs.branin', '')  # to be copied by each worker
 
 if libE_specs['comms'] == 'tcp':
     sys.exit("Cannot run with tcp when repeated calls to libE -- aborting...")

From d3cf62b679ce5daa6749c444422bc7bb15cfb7e4 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 14:09:13 -0500
Subject: [PATCH 398/644] Flake8

---
 libensemble/libE_worker.py                                | 2 +-
 libensemble/tests/scaling_tests/forces/run_libe_forces.py | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/libensemble/libE_worker.py b/libensemble/libE_worker.py
index 90791ef06..a133b6d1d 100644
--- a/libensemble/libE_worker.py
+++ b/libensemble/libE_worker.py
@@ -50,7 +50,7 @@ def worker_main(comm, sim_specs, gen_specs, libE_specs, workerID=None, log_comm=
         Parameters/information for generation calculations
 
     libE_specs: dict
-        Parameters/information for libE operations 
+        Parameters/information for libE operations
 
     workerID: int
         Manager assigned worker ID (if None, default is comm.rank)
diff --git a/libensemble/tests/scaling_tests/forces/run_libe_forces.py b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
index 9fe21d235..b647422b0 100644
--- a/libensemble/tests/scaling_tests/forces/run_libe_forces.py
+++ b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
@@ -96,7 +96,7 @@
 
 libE_specs['save_every_k_gens'] = 1000  # Save every K steps
 libE_specs['sim_dir'] = './sim'         # Sim dir to be copied for each worker
-libE_specs['profile'] =  False,         # Don't have libE profile run
+libE_specs['profile'] = False           # Don't have libE profile run
 
 # Maximum number of simulations
 sim_max = 8

From c89e4f0b72361ba84884a3c691d73d8f62b98014 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 14:31:34 -0500
Subject: [PATCH 399/644] Using alloc_specs for batch mode (and making batch
 mode default)

---
 libensemble/alloc_funcs/fast_alloc_and_pausing.py | 2 +-
 libensemble/alloc_funcs/fast_alloc_to_aposmm.py   | 2 +-
 libensemble/alloc_funcs/give_sim_work_first.py    | 2 +-
 libensemble/libE.py                               | 3 ++-
 4 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/libensemble/alloc_funcs/fast_alloc_and_pausing.py b/libensemble/alloc_funcs/fast_alloc_and_pausing.py
index d8e96d4cd..257e229d2 100644
--- a/libensemble/alloc_funcs/fast_alloc_and_pausing.py
+++ b/libensemble/alloc_funcs/fast_alloc_and_pausing.py
@@ -108,7 +108,7 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
             last_size = persis_info.get('last_size')
             if len(H):
                 # Don't give gen instances in batch mode if points are unfinished
-                if (gen_specs['user'].get('batch_mode')
+                if (alloc_specs['user'].get('batch_mode')
                     and not all(np.logical_or(H['returned'][last_size:],
                                               H['paused'][last_size:]))):
                     break
diff --git a/libensemble/alloc_funcs/fast_alloc_to_aposmm.py b/libensemble/alloc_funcs/fast_alloc_to_aposmm.py
index 8ee694c62..3a260a6c0 100644
--- a/libensemble/alloc_funcs/fast_alloc_to_aposmm.py
+++ b/libensemble/alloc_funcs/fast_alloc_to_aposmm.py
@@ -33,7 +33,7 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
             last_size = persis_info.get('last_size')
             if len(H):
                 # Don't give gen instances in batch mode if points are unfinished
-                if (gen_specs['user'].get('batch_mode')
+                if (alloc_specs['user'].get('batch_mode')
                     and not all(np.logical_or(H['returned'][last_size:],
                                               H['paused'][last_size:]))):
                     break
diff --git a/libensemble/alloc_funcs/give_sim_work_first.py b/libensemble/alloc_funcs/give_sim_work_first.py
index 90bbdd6d8..8525706c1 100644
--- a/libensemble/alloc_funcs/give_sim_work_first.py
+++ b/libensemble/alloc_funcs/give_sim_work_first.py
@@ -73,7 +73,7 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
 
             # No gen instances in batch mode if workers still working
             still_working = ~H['returned']
-            if gen_specs['user'].get('batch_mode') and np.any(still_working):
+            if alloc_specs['user'].get('batch_mode') and np.any(still_working):
                 break
 
             # Give gen work
diff --git a/libensemble/libE.py b/libensemble/libE.py
index d1a942eb2..b5c606369 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -84,7 +84,8 @@ def report_manager_exception(hist, persis_info, mgr_exc=None):
 def libE(sim_specs, gen_specs, exit_criteria,
          persis_info={},
          alloc_specs={'alloc_f': give_sim_work_first,
-                      'out': [('allocated', bool)]},
+                      'out': [('allocated', bool)],
+                      'user': {'batch_mode': True}},
          libE_specs={},
          H0=[]):
     """This is the outer libEnsemble routine.

From 02797282f6b69c1ed80d84c934473cd86e9e2daa Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 31 Oct 2019 14:32:25 -0500
Subject: [PATCH 400/644] insist on balsam 0.3.5 on Python 3.6 for now.

---
 conda/install-balsam.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index c27f12fa7..56aae1150 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -12,7 +12,7 @@
 
 def install_balsam():
     # Installs Balsam
-    balsaminstall = 'pip install balsam-flow==0.3.6'
+    balsaminstall = 'pip install balsam-flow==0.3.5'
     subprocess.check_call(balsaminstall.split())
     # here = os.getcwd()
     # balsamclone = 'git clone https://github.com/balsam-alcf/balsam.git ../balsam'
@@ -42,7 +42,7 @@ def configure_coverage():
             f.write(line)
 
 
-if int(sys.version[2]) >= 6:  # Balsam only supports Python 3.6+
+if int(sys.version[2]) == 6:  # Balsam 0.3.5 only supports Python 3.6
     install_balsam()
     move_test_balsam('test_balsam_hworld.py')
     configure_coverage()

From f244b7cff40219b6ac8e75c1986b77c42bf31e0e Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 14:45:55 -0500
Subject: [PATCH 401/644] Don't need to declare batch_mode=True for default
 alloc_func, because that's the default

---
 libensemble/tests/regression_tests/script_test_balsam_hworld.py  | 1 -
 .../regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py  | 1 -
 libensemble/tests/regression_tests/test_chwirut_pounders.py      | 1 -
 .../tests/regression_tests/test_chwirut_pounders_splitcomm.py    | 1 -
 .../tests/regression_tests/test_chwirut_pounders_subcomm.py      | 1 -
 libensemble/tests/regression_tests/test_comms.py                 | 1 -
 libensemble/tests/regression_tests/test_jobcontroller_hworld.py  | 1 -
 libensemble/tests/regression_tests/test_nan_func_aposmm.py       | 1 -
 libensemble/tests/regression_tests/test_worker_exceptions.py     | 1 -
 9 files changed, 9 deletions(-)

diff --git a/libensemble/tests/regression_tests/script_test_balsam_hworld.py b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
index 3a58b2c2d..6db317c1d 100644
--- a/libensemble/tests/regression_tests/script_test_balsam_hworld.py
+++ b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
@@ -53,7 +53,6 @@ def build_simfunc():
              'user': {'lb': np.array([-3, -2]),
                       'ub': np.array([3, 2]),
                       'gen_batch_size': nworkers,
-                      'batch_mode': True,
                       'num_active_gens': 1}
              }
 
diff --git a/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py b/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
index cd78866a4..0de243fe7 100644
--- a/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
+++ b/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
@@ -49,7 +49,6 @@
              'in': [o[0] for o in gen_out] + ['f', 'returned'],
              'out': gen_out,
              'user': {'num_active_gens': 1,
-                      'batch_mode': True,
                       'lb': np.array([-5, 0]),
                       'ub': np.array([10, 15]),
                       'initial_sample_size': 20,
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders.py b/libensemble/tests/regression_tests/test_chwirut_pounders.py
index 0cf677c9d..d438ea63e 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders.py
@@ -42,7 +42,6 @@
              'in': [o[0] for o in gen_out]+['f', 'fvec', 'returned'],
              'out': gen_out,
              'user': {'initial_sample_size': 5,
-                      'batch_mode': True,
                       'num_active_gens': 1,
                       'lb': (-2-np.pi/10)*np.ones(n),
                       'ub': 2*np.ones(n),
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py b/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
index db5861484..6abcf01ea 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
@@ -46,7 +46,6 @@
              'in': [o[0] for o in gen_out]+['f', 'fvec', 'returned'],
              'out': gen_out,
              'user': {'initial_sample_size': 5,
-                      'batch_mode': True,
                       'num_active_gens': 1,
                       'lb': (-2-np.pi/10)*np.ones(n),
                       'ub': 2*np.ones(n),
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py b/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
index 860c0acd2..33f4b5d69 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
@@ -50,7 +50,6 @@
              'in': [o[0] for o in gen_out]+['f', 'fvec', 'returned'],
              'out': gen_out,
              'user': {'initial_sample_size': 5,
-                      'batch_mode': True,
                       'num_active_gens': 1,
                       'lb': (-2-np.pi/10)*np.ones(n),
                       'ub': 2*np.ones(n),
diff --git a/libensemble/tests/regression_tests/test_comms.py b/libensemble/tests/regression_tests/test_comms.py
index 8d8f084d8..619ae2d65 100644
--- a/libensemble/tests/regression_tests/test_comms.py
+++ b/libensemble/tests/regression_tests/test_comms.py
@@ -39,7 +39,6 @@
              'out': [('x', float, (2,))],
              'user': {'lb': np.array([-3, -2]),
                       'ub': np.array([3, 2]),
-                      'batch_mode': True,
                       'gen_batch_size': sim_max,
                       'num_active_gens': 1}
              }
diff --git a/libensemble/tests/regression_tests/test_jobcontroller_hworld.py b/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
index 04220a4ae..73abc3748 100644
--- a/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
+++ b/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
@@ -76,7 +76,6 @@
              'out': [('x', float, (2,))],
              'user': {'lb': np.array([-3, -2]),
                       'ub': np.array([3, 2]),
-                      'batch_mode': True,
                       'gen_batch_size': nworkers,
                       'num_active_gens': 1,
                       }
diff --git a/libensemble/tests/regression_tests/test_nan_func_aposmm.py b/libensemble/tests/regression_tests/test_nan_func_aposmm.py
index 0be876285..d78e2424a 100644
--- a/libensemble/tests/regression_tests/test_nan_func_aposmm.py
+++ b/libensemble/tests/regression_tests/test_nan_func_aposmm.py
@@ -36,7 +36,6 @@
              'user': {'initial_sample_size': 5,
                       'lb': -2*np.ones(n),
                       'ub': 2*np.ones(n),
-                      'batch_mode': True,
                       'num_active_gens': 1}
              }
 
diff --git a/libensemble/tests/regression_tests/test_worker_exceptions.py b/libensemble/tests/regression_tests/test_worker_exceptions.py
index 5d19c06c1..982ce2781 100644
--- a/libensemble/tests/regression_tests/test_worker_exceptions.py
+++ b/libensemble/tests/regression_tests/test_worker_exceptions.py
@@ -32,7 +32,6 @@
              'user': {'lb': np.array([-3, -2]),
                       'ub': np.array([3, 2]),
                       'initial_sample': 100,
-                      'batch_mode': True,
                       'num_active_gens': 1}
              }
 

From fe4209709fcf3e966559233bc19c7812dd47555a Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 14:49:42 -0500
Subject: [PATCH 402/644] Moving batch_mode to alloc_spec

---
 .../test_6-hump_camel_active_persistent_worker_abort.py        | 3 +--
 .../tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py  | 3 +--
 .../regression_tests/test_6-hump_camel_persistent_aposmm_1.py  | 3 +--
 .../regression_tests/test_6-hump_camel_persistent_aposmm_2.py  | 3 +--
 .../regression_tests/test_6-hump_camel_persistent_aposmm_3.py  | 3 +--
 .../regression_tests/test_6-hump_camel_persistent_aposmm_4.py  | 3 +--
 ...ump_camel_uniform_sampling_with_persistent_localopt_gens.py | 3 +--
 .../tests/regression_tests/test_chwirut_pounders_persistent.py | 3 +--
 8 files changed, 8 insertions(+), 16 deletions(-)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py b/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py
index a96beedcc..3b0252e99 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py
@@ -38,14 +38,13 @@
                       'lb': np.array([-3, -2]),
                       'ub': np.array([3, 2]),
                       'gen_batch_size': 2,
-                      'batch_mode': True,
                       'num_active_gens': 1,
                       'dist_to_bound_multiple': 0.5,
                       'localopt_maxeval': 4
                       }
              }
 
-alloc_specs = {'alloc_f': alloc_f, 'out': gen_out}
+alloc_specs = {'alloc_f': alloc_f, 'out': gen_out, 'user': {'batch_mode': True}}
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
index 93c7ae864..a6fb5385f 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
@@ -37,7 +37,6 @@
              'in': [o[0] for o in gen_out] + ['f', 'grad', 'returned'],
              'out': gen_out,
              'user': {'num_active_gens': 1,
-                      'batch_mode': True,
                       'initial_sample_size': 100,
                       'sample_points': np.round(minima, 1),
                       'localopt_method': 'LD_MMA',
@@ -50,7 +49,7 @@
                       }
              }
 
-alloc_specs = {'alloc_f': alloc_f, 'out': [('allocated', bool)]}
+alloc_specs = {'alloc_f': alloc_f, 'out': [('allocated', bool)], 'user': {'batch_mode': True}}
 
 persis_info = per_worker_stream(persis_info, nworkers + 1)
 persis_info_safe = deepcopy(persis_info)
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
index 06166be75..b8e7a27ec 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
@@ -54,12 +54,11 @@
                       'ftol_rel': 1e-6,
                       'num_active_gens': 1,
                       'max_active_runs': 6,
-                      'batch_mode': True,
                       'lb': np.array([-3, -2]),
                       'ub': np.array([3, 2])}
              }
 
-alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)]}
+alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)], 'user': {'batch_mode': True}}
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
index 102c7782c..f3c554ca9 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
@@ -55,12 +55,11 @@
                       'num_active_gens': 1,
                       'dist_to_bound_multiple': 0.5,
                       'max_active_runs': 6,
-                      'batch_mode': True,
                       'lb': np.array([-3, -2]),
                       'ub': np.array([3, 2])}
              }
 
-alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)]}
+alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)], 'user': {'batch_mode': True}}
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
index 67f2ebc13..87b46b2e4 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
@@ -55,12 +55,11 @@
                       'num_active_gens': 1,
                       'dist_to_bound_multiple': 0.5,
                       'max_active_runs': 6,
-                      'batch_mode': True,
                       'lb': np.array([-3, -2]),
                       'ub': np.array([3, 2])}
              }
 
-alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)]}
+alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)], 'user': {'batch_mode': True}}
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
index 126ed3e33..6fd1b0d5b 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
@@ -55,12 +55,11 @@
                       'num_active_gens': 1,
                       'dist_to_bound_multiple': 0.01,
                       'max_active_runs': 6,
-                      'batch_mode': True,
                       'lb': np.array([-3, -2]),
                       'ub': np.array([3, 2])}
              }
 
-alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)]}
+alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)], 'user': {'batch_mode': True}}
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
index a9f8eea70..0cfe45ca4 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
@@ -41,7 +41,6 @@
              'in': [],
              'out': gen_out,
              'user': {'xtol_rel': 1e-4,
-                      'batch_mode': True,
                       'lb': np.array([-3, -2]),
                       'ub': np.array([3, 2]),
                       'gen_batch_size': 2,
@@ -50,7 +49,7 @@
                       'xtol_rel': 1e-4}
              }
 
-alloc_specs = {'alloc_f': alloc_f, 'out': gen_out}
+alloc_specs = {'alloc_f': alloc_f, 'out': gen_out, 'user': {'batch_mode': True}}
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
index 62873ea16..2cfe788e6 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
@@ -50,7 +50,6 @@
              'out': gen_out,
              'user': {'initial_sample_size': 100,
                       'localopt_method': 'pounders',
-                      'batch_mode': True,
                       'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
                       'grtol': 1e-6,
                       'gatol': 1e-6,
@@ -62,7 +61,7 @@
                       'ub': 2*np.ones(n)}
              }
 
-alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)]}
+alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)], 'user': {'batch_mode': True}}
 
 persis_info = per_worker_stream({}, nworkers + 1)
 

From 34ca70d8ec185766e50fc702adea217e76c55507 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 14:50:41 -0500
Subject: [PATCH 403/644] Moving batch_mode to alloc_spec

---
 .../test_chwirut_aposmm_one_residual_at_a_time.py               | 2 +-
 .../test_chwirut_uniform_sampling_one_residual_at_a_time.py     | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py b/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py
index 3d0108126..3df028cb0 100644
--- a/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py
+++ b/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py
@@ -43,7 +43,6 @@
              'in': [o[0] for o in gen_out] + ['f_i', 'returned'],
              'out': gen_out,
              'user': {'initial_sample_size': 5,
-                      'batch_mode': True,
                       'num_active_gens': 1,
                       'lb': LB,
                       'ub': UB,
@@ -61,6 +60,7 @@
 alloc_specs = {'alloc_f': alloc_f,
                'out': [('allocated', bool)],
                'user': {'stop_on_NaNs': True,
+                        'batch_mode': True,
                         'stop_partial_fvec_eval': True}
                }
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
index aba1eb713..054a60224 100644
--- a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
+++ b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
@@ -56,7 +56,6 @@
                      ('obj_component', int),
                      ('pt_id', int)],
              'user': {'gen_batch_size': 2,
-                      'batch_mode': True,
                       'single_component_at_a_time': True,
                       'combine_component_func': lambda x: np.sum(np.power(x, 2)),
                       'num_active_gens': 1,
@@ -68,6 +67,7 @@
 alloc_specs = {'alloc_f': alloc_f,              # Allocation function
                'out': [('allocated', bool)],    # Output fields (included in History)
                'user': {'stop_on_NaNs': True,            # Should alloc_f preempt evals
+                        'batch_mode': True,
                         'stop_partial_fvec_eval': True}  # Should alloc_f preempt evals
                }
 # end_alloc_specs_rst_tag

From 789c861fc151c2482b0a240cfc85e62ad52f2661 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 14:51:06 -0500
Subject: [PATCH 404/644] Testing batch_mode=False for default alloc_f

---
 .../test_6-hump_camel_elapsed_time_abort.py               | 8 ++++++--
 ...st_6-hump_camel_with_different_nodes_uniform_sample.py | 8 ++++++--
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py b/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
index bf1b1cb52..879984ba5 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
@@ -20,6 +20,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
+from libensemble.alloc_funcs.give_sim_work_first import give_sim_work_first
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream, eprint
 
 nworkers, is_master, libE_specs, _ = parse_args()
@@ -35,18 +36,21 @@
              'out': [('x', float, (2,))],
              'user': {'gen_batch_size': 5,
                       'num_active_gens': 1,
-                      'batch_mode': False,
                       'lb': np.array([-3, -2]),
                       'ub': np.array([3, 2])}
              }
 
+alloc_specs={'alloc_f': give_sim_work_first,
+             'out': [('allocated', bool)],
+             'user': {'batch_mode': False}}
+
 persis_info = per_worker_stream({}, nworkers + 1)
 
 exit_criteria = {'elapsed_wallclock_time': 1}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
-                            libE_specs=libE_specs)
+                            libE_specs=libE_specs,alloc_specs=alloc_specs)
 
 if is_master:
     eprint(flag)
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py b/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
index b787596d8..4c1b27bbc 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
@@ -21,6 +21,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel_with_different_ranks_and_nodes as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample_with_different_nodes_and_ranks as gen_f
+from libensemble.alloc_funcs.give_sim_work_first import give_sim_work_first
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
@@ -57,7 +58,6 @@
                      ('x', float, n),
                      ('x_on_cube', float, n)],
              'user': {'initial_batch_size': 5,
-                      'batch_mode': False,
                       'max_ranks_per_node': 8,
                       'num_active_gens': 1,
                       'give_all_with_same_priority': True,
@@ -66,13 +66,17 @@
                       'ub': np.array([3, 2])}
              }
 
+alloc_specs={'alloc_f': give_sim_work_first,
+             'out': [('allocated', bool)],
+             'user': {'batch_mode': False}},
+
 persis_info = per_worker_stream({}, nworkers + 1)
 
 exit_criteria = {'sim_max': 10, 'elapsed_wallclock_time': 300}
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
-                            libE_specs=libE_specs)
+                            libE_specs=libE_specs, alloc_specs=alloc_specs)
 
 if is_master:
     assert flag == 0

From 4b2bc963c34ecadf585643c8075c6e74601f11cd Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 31 Oct 2019 15:40:05 -0500
Subject: [PATCH 405/644] revert to normal

---
 conda/install-balsam.py | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index 56aae1150..0c358c575 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -11,15 +11,13 @@
 
 
 def install_balsam():
-    # Installs Balsam
-    balsaminstall = 'pip install balsam-flow==0.3.5'
-    subprocess.check_call(balsaminstall.split())
-    # here = os.getcwd()
-    # balsamclone = 'git clone https://github.com/balsam-alcf/balsam.git ../balsam'
-    # subprocess.check_call(balsamclone.split())
-    # os.chdir('../balsam')
-    # subprocess.check_call('pip install -e .'.split())
-    # os.chdir(here)
+    # Installs Balsam in a directory on the same level as the current directory.
+    here = os.getcwd()
+    balsamclone = 'git clone https://github.com/balsam-alcf/balsam.git ../balsam'
+    subprocess.check_call(balsamclone.split())
+    os.chdir('../balsam')
+    subprocess.check_call('pip install -e .'.split())
+    os.chdir(here)
 
 
 def move_test_balsam(balsam_test):
@@ -42,7 +40,7 @@ def configure_coverage():
             f.write(line)
 
 
-if int(sys.version[2]) == 6:  # Balsam 0.3.5 only supports Python 3.6
+if int(sys.version[2]) >= 6:  # Balsam only supports Python 3.6+
     install_balsam()
     move_test_balsam('test_balsam_hworld.py')
     configure_coverage()

From cf9833b8e62d8fe19508878873134b70e9ef0a3d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 15:51:51 -0500
Subject: [PATCH 406/644] Moving APOSMM check for batch mode to alloc_f, and
 fixing some other typos

---
 libensemble/alloc_funcs/fast_alloc_and_pausing.py              | 3 +++
 libensemble/gen_funcs/aposmm.py                                | 2 --
 .../tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py  | 2 +-
 .../test_6-hump_camel_with_different_nodes_uniform_sample.py   | 2 +-
 4 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/libensemble/alloc_funcs/fast_alloc_and_pausing.py b/libensemble/alloc_funcs/fast_alloc_and_pausing.py
index 257e229d2..3aedc0fd8 100644
--- a/libensemble/alloc_funcs/fast_alloc_and_pausing.py
+++ b/libensemble/alloc_funcs/fast_alloc_and_pausing.py
@@ -28,6 +28,9 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     Work = {}
     gen_count = count_gens(W)
 
+    if gen_specs.get('single_component_at_a_time'):
+        assert alloc_specs['batch_mode'], ("Must be in batch mode when using "
+                                          "'single_component_at_a_time'")
     if len(H) != persis_info['H_len']:
         # Something new is in the history.
         persis_info['need_to_give'].update(H['sim_id'][persis_info['H_len']:].tolist())
diff --git a/libensemble/gen_funcs/aposmm.py b/libensemble/gen_funcs/aposmm.py
index de2001db8..84b53c949 100644
--- a/libensemble/gen_funcs/aposmm.py
+++ b/libensemble/gen_funcs/aposmm.py
@@ -899,8 +899,6 @@ def initialize_APOSMM(H, gen_specs):
     n = len(user_specs['ub'])
 
     if 'single_component_at_a_time' in user_specs and user_specs['single_component_at_a_time']:
-        assert user_specs['batch_mode'], ("Must be in batch mode when using "
-                                          "'single_component_at_a_time'")
         c_flag = True
     else:
         c_flag = False
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
index a6fb5385f..106dcd9e5 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
@@ -93,7 +93,7 @@ def libE_mpi_abort():
         gen_specs['user']['rk_const'] = 0.01*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi)
         gen_specs['user']['lhs_divisions'] = 2
         # APOSMM can be called when some run is incomplete
-        gen_specs['user'].pop('batch_mode')
+        alloc_specs['user'].pop('batch_mode')
 
         gen_specs['user'].pop('xtol_rel')
         gen_specs['user']['ftol_rel'] = 1e-2
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py b/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
index 4c1b27bbc..c158d1000 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
@@ -68,7 +68,7 @@
 
 alloc_specs={'alloc_f': give_sim_work_first,
              'out': [('allocated', bool)],
-             'user': {'batch_mode': False}},
+             'user': {'batch_mode': False}}
 
 persis_info = per_worker_stream({}, nworkers + 1)
 

From 19f002eb4170c3a11d55bd41772c74f64ff0db08 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 17:55:41 -0500
Subject: [PATCH 407/644] Flake8

---
 libensemble/alloc_funcs/fast_alloc_and_pausing.py         | 2 +-
 .../test_6-hump_camel_elapsed_time_abort.py               | 8 ++++----
 ...st_6-hump_camel_with_different_nodes_uniform_sample.py | 6 +++---
 3 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/libensemble/alloc_funcs/fast_alloc_and_pausing.py b/libensemble/alloc_funcs/fast_alloc_and_pausing.py
index 3aedc0fd8..f8c9983e2 100644
--- a/libensemble/alloc_funcs/fast_alloc_and_pausing.py
+++ b/libensemble/alloc_funcs/fast_alloc_and_pausing.py
@@ -30,7 +30,7 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
 
     if gen_specs.get('single_component_at_a_time'):
         assert alloc_specs['batch_mode'], ("Must be in batch mode when using "
-                                          "'single_component_at_a_time'")
+                                           "'single_component_at_a_time'")
     if len(H) != persis_info['H_len']:
         # Something new is in the history.
         persis_info['need_to_give'].update(H['sim_id'][persis_info['H_len']:].tolist())
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py b/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
index 879984ba5..46e968542 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
@@ -40,9 +40,9 @@
                       'ub': np.array([3, 2])}
              }
 
-alloc_specs={'alloc_f': give_sim_work_first,
-             'out': [('allocated', bool)],
-             'user': {'batch_mode': False}}
+alloc_specs = {'alloc_f': give_sim_work_first,
+               'out': [('allocated', bool)],
+               'user': {'batch_mode': False}}
 
 persis_info = per_worker_stream({}, nworkers + 1)
 
@@ -50,7 +50,7 @@
 
 # Perform the run
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
-                            libE_specs=libE_specs,alloc_specs=alloc_specs)
+                            libE_specs=libE_specs, alloc_specs=alloc_specs)
 
 if is_master:
     eprint(flag)
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py b/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
index c158d1000..de7890af4 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
@@ -66,9 +66,9 @@
                       'ub': np.array([3, 2])}
              }
 
-alloc_specs={'alloc_f': give_sim_work_first,
-             'out': [('allocated', bool)],
-             'user': {'batch_mode': False}}
+alloc_specs = {'alloc_f': give_sim_work_first,
+               'out': [('allocated', bool)],
+               'user': {'batch_mode': False}}
 
 persis_info = per_worker_stream({}, nworkers + 1)
 

From ee679742bd1c2b1f3d1362d817bbf42e2a2ffa5c Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 20:28:03 -0500
Subject: [PATCH 408/644] Correcly using 'user' fields

---
 libensemble/alloc_funcs/fast_alloc_and_pausing.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/libensemble/alloc_funcs/fast_alloc_and_pausing.py b/libensemble/alloc_funcs/fast_alloc_and_pausing.py
index f8c9983e2..c52fcce06 100644
--- a/libensemble/alloc_funcs/fast_alloc_and_pausing.py
+++ b/libensemble/alloc_funcs/fast_alloc_and_pausing.py
@@ -28,8 +28,8 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     Work = {}
     gen_count = count_gens(W)
 
-    if gen_specs.get('single_component_at_a_time'):
-        assert alloc_specs['batch_mode'], ("Must be in batch mode when using "
+    if gen_specs['user'].get('single_component_at_a_time'):
+        assert alloc_specs['user']['batch_mode'], ("Must be in batch mode when using "
                                            "'single_component_at_a_time'")
     if len(H) != persis_info['H_len']:
         # Something new is in the history.

From eb59fb99baf98a94e399bfc6e72b62bd11e0643e Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 20:47:12 -0500
Subject: [PATCH 409/644] Flake8

---
 libensemble/alloc_funcs/fast_alloc_and_pausing.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/alloc_funcs/fast_alloc_and_pausing.py b/libensemble/alloc_funcs/fast_alloc_and_pausing.py
index c52fcce06..6bcc9ffec 100644
--- a/libensemble/alloc_funcs/fast_alloc_and_pausing.py
+++ b/libensemble/alloc_funcs/fast_alloc_and_pausing.py
@@ -30,7 +30,7 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
 
     if gen_specs['user'].get('single_component_at_a_time'):
         assert alloc_specs['user']['batch_mode'], ("Must be in batch mode when using "
-                                           "'single_component_at_a_time'")
+                                                   "'single_component_at_a_time'")
     if len(H) != persis_info['H_len']:
         # Something new is in the history.
         persis_info['need_to_give'].update(H['sim_id'][persis_info['H_len']:].tolist())

From 9066997ee14f4b475aee4f43d9d54d6493ea7ba4 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 21:07:58 -0500
Subject: [PATCH 410/644] Trying python3.8, and seeing if OSX is failing.

---
 .travis.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.travis.yml b/.travis.yml
index 7c9bd938a..9f3792897 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -5,6 +5,7 @@ python:
   - 3.5
   - 3.6
   - 3.7
+  - 3.8
 
 os: linux
 

From d105dc9301e011453f6feda04a826b01d0828223 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 21:13:21 -0500
Subject: [PATCH 411/644] Trying to enforce 3.7 for OSX

---
 .travis.yml | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 9f3792897..72d30dde0 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -5,7 +5,6 @@ python:
   - 3.5
   - 3.6
   - 3.7
-  - 3.8
 
 os: linux
 
@@ -23,7 +22,7 @@ matrix:
       osx_image: xcode10.1
       env: MPI=mpich PY=3
       language: generic
-      python: 3
+      python: 3.7
 
 
 services:

From 18692b00e0da5e2cfd2ef2b7887349a089d8db19 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 21:13:21 -0500
Subject: [PATCH 412/644] Trying to enforce 3.7 for OSX

(cherry picked from commit d105dc9301e011453f6feda04a826b01d0828223)
---
 .travis.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index 7c9bd938a..72d30dde0 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -22,7 +22,7 @@ matrix:
       osx_image: xcode10.1
       env: MPI=mpich PY=3
       language: generic
-      python: 3
+      python: 3.7
 
 
 services:

From e6438e201a36edbdbe2e56cdaa66c1f49711f996 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 31 Oct 2019 21:32:35 -0500
Subject: [PATCH 413/644] Trying to enforce 3.7 for OSX

---
 .travis.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index 72d30dde0..766ca2ea3 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -20,7 +20,7 @@ matrix:
   include:
     - os: osx
       osx_image: xcode10.1
-      env: MPI=mpich PY=3
+      env: MPI=mpich PY=3.7
       language: generic
       python: 3.7
 

From ac9e4ae8ddd31deacbbaa9ef326137bb43e0e3d8 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 1 Nov 2019 06:13:32 -0500
Subject: [PATCH 414/644] Trying python3.7, and seeing if OSX is failing.

---
 .travis.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index 766ca2ea3..1eaae6c71 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -57,7 +57,7 @@ before_install:
   #- conda update -q -y conda
   - conda info -a # For debugging any issues with conda
   - conda config --add channels conda-forge
-  - conda create --yes --name condaenv python=$TRAVIS_PYTHON_VERSION
+  - conda create --yes --name condaenv python=3.7
   - source activate condaenv
     # sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /;
 

From 2ee4916524dd79bee6b750bdfdd1411bb791d3d9 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 1 Nov 2019 06:13:32 -0500
Subject: [PATCH 415/644] Trying python3.7, and seeing if OSX is failing.

(cherry picked from commit ac9e4ae8ddd31deacbbaa9ef326137bb43e0e3d8)
---
 .travis.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index 72d30dde0..9a91ab120 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -57,7 +57,7 @@ before_install:
   #- conda update -q -y conda
   - conda info -a # For debugging any issues with conda
   - conda config --add channels conda-forge
-  - conda create --yes --name condaenv python=$TRAVIS_PYTHON_VERSION
+  - conda create --yes --name condaenv python=3.7
   - source activate condaenv
     # sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /;
 

From d47bf79506c6e78568fa0de0107f930114bf45c9 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 1 Nov 2019 09:53:56 -0500
Subject: [PATCH 416/644] wget recent release tar, install

---
 .travis.yml             | 4 +++-
 conda/install-balsam.py | 4 ++--
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 1eaae6c71..3775b05e7 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -85,7 +85,9 @@ install:
   # For confirmation of MPI library being used.
   - python conda/find_mpi.py # locate compilers
   - mpiexec --version # Show MPI library details
-  - pip install -e .
+  - pip install -e . # Installing libEnsemble
+  - wget https://github.com/balsam-alcf/balsam/archive/0.3.5.1.tar.gz
+  - mkdir ../balsam; tar xf balsam-0.3.5.1.tar.gz -C ../balsam;
   - python conda/install-balsam.py
 
 before_script:
diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index 0c358c575..afc8cefc1 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -13,8 +13,8 @@
 def install_balsam():
     # Installs Balsam in a directory on the same level as the current directory.
     here = os.getcwd()
-    balsamclone = 'git clone https://github.com/balsam-alcf/balsam.git ../balsam'
-    subprocess.check_call(balsamclone.split())
+    # balsamclone = 'git clone https://github.com/balsam-alcf/balsam.git ../balsam'
+    # subprocess.check_call(balsamclone.split())
     os.chdir('../balsam')
     subprocess.check_call('pip install -e .'.split())
     os.chdir(here)

From e41f3ac25aa0e52519284d5ed07109a2c0bcec28 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 1 Nov 2019 10:31:10 -0500
Subject: [PATCH 417/644] adjust tar name, install dirx

---
 .travis.yml             | 2 +-
 conda/install-balsam.py | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 3775b05e7..e688a4f4f 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -87,7 +87,7 @@ install:
   - mpiexec --version # Show MPI library details
   - pip install -e . # Installing libEnsemble
   - wget https://github.com/balsam-alcf/balsam/archive/0.3.5.1.tar.gz
-  - mkdir ../balsam; tar xf balsam-0.3.5.1.tar.gz -C ../balsam;
+  - mkdir ../balsam; tar xf 0.3.5.1.tar.gz -C ../balsam;
   - python conda/install-balsam.py
 
 before_script:
diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index afc8cefc1..c75e5b7fc 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -15,7 +15,7 @@ def install_balsam():
     here = os.getcwd()
     # balsamclone = 'git clone https://github.com/balsam-alcf/balsam.git ../balsam'
     # subprocess.check_call(balsamclone.split())
-    os.chdir('../balsam')
+    os.chdir('../balsam/balsam-0.3.5.1')
     subprocess.check_call('pip install -e .'.split())
     os.chdir(here)
 

From 7e9914692d9cb8bce3ad490e71b90d286c6845a1 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 1 Nov 2019 11:18:48 -0500
Subject: [PATCH 418/644] replace older balsamactivate

---
 conda/install-balsam.py | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index c75e5b7fc..839637912 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -13,18 +13,21 @@
 def install_balsam():
     # Installs Balsam in a directory on the same level as the current directory.
     here = os.getcwd()
-    # balsamclone = 'git clone https://github.com/balsam-alcf/balsam.git ../balsam'
-    # subprocess.check_call(balsamclone.split())
     os.chdir('../balsam/balsam-0.3.5.1')
     subprocess.check_call('pip install -e .'.split())
+
+    # Replace old version of balsamactivate
+    os.chdir('./balsam/scripts'); os.remove('balsamactivate')
+    subprocess.check_call('wget https://raw.githubusercontent.com/balsam-alcf/balsam/master/balsam/scripts/balsamactivate'.split())
+
     os.chdir(here)
 
 
 def move_test_balsam(balsam_test):
     # Moves specified test from /conda to /regression_tests
-    reg_dir_with_btest = os.path.join('./libensemble/tests/regression_tests', balsam_test)
+    reg_dir_with_btest = './libensemble/tests/regression_tests/' + balsam_test
     if not os.path.isfile(reg_dir_with_btest):
-        os.rename('./conda/{}'.format(balsam_test), reg_dir_with_btest)
+        os.rename('./conda/' + balsam_test, reg_dir_with_btest)
 
 
 def configure_coverage():

From 8420fb7483314618db727b42012aef616d46f55c Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 1 Nov 2019 11:31:52 -0500
Subject: [PATCH 419/644] rearrange new balsamactivate and pip install

---
 conda/install-balsam.py | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/conda/install-balsam.py b/conda/install-balsam.py
index 839637912..43aaa1609 100644
--- a/conda/install-balsam.py
+++ b/conda/install-balsam.py
@@ -11,15 +11,17 @@
 
 
 def install_balsam():
-    # Installs Balsam in a directory on the same level as the current directory.
     here = os.getcwd()
-    os.chdir('../balsam/balsam-0.3.5.1')
-    subprocess.check_call('pip install -e .'.split())
+    os.chdir('../balsam/balsam-0.3.5.1/balsam/scripts')
 
     # Replace old version of balsamactivate
-    os.chdir('./balsam/scripts'); os.remove('balsamactivate')
+    os.remove('balsamactivate')
     subprocess.check_call('wget https://raw.githubusercontent.com/balsam-alcf/balsam/master/balsam/scripts/balsamactivate'.split())
 
+    # Pip install Balsam
+    os.chdir('../..')
+    subprocess.check_call('pip install -e .'.split())
+
     os.chdir(here)
 
 

From 45a0fb8329ff9eba046502bf2577d77b2799fa95 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 1 Nov 2019 11:45:52 -0500
Subject: [PATCH 420/644] ensure condaenv python version (reverts recent fix
 for 3.8 tests on osx, but 3.7 now enforced on that platform (?) )

---
 .travis.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.travis.yml b/.travis.yml
index e688a4f4f..a6eaf013b 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -57,7 +57,7 @@ before_install:
   #- conda update -q -y conda
   - conda info -a # For debugging any issues with conda
   - conda config --add channels conda-forge
-  - conda create --yes --name condaenv python=3.7
+  - conda create --yes --name condaenv python=$TRAVIS_PYTHON_VERSION
   - source activate condaenv
     # sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /;
 

From 6ca88621b0f5f630ebd24cfe4b4a99ee0b732970 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 1 Nov 2019 12:12:15 -0500
Subject: [PATCH 421/644] conditional env version by system, clean up
 travis.yml

---
 .travis.yml | 59 +++++++++++++++++++++++------------------------------
 1 file changed, 25 insertions(+), 34 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index a6eaf013b..8f2a2f793 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -6,15 +6,17 @@ python:
   - 3.6
   - 3.7
 
+
 os: linux
 
+
 env:
   global:
     - HYDRA_LAUNCHER=fork
     - OMPI_MCA_rmaps_base_oversubscribe=yes
   matrix:
     - MPI=mpich
-    #- MPI=openmpi
+
 
 matrix:
   include:
@@ -28,22 +30,12 @@ matrix:
 services:
     - postgresql
 
-# matrix:
-#  allow_failures:
-#    - env: MPI=openmpi
-
-# addons:
-#   apt:
-#     packages:
-#       - gfortran
-#       - libblas-dev
-#       - liblapack-dev
 
 cache:
   pip: true
   apt: true
 
-# Setup Miniconda
+
 before_install:
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
       wget https://repo.continuum.io/miniconda/Miniconda3-4.7.10-MacOSX-x86_64.sh -O miniconda.sh;
@@ -54,12 +46,15 @@ before_install:
   - export PATH="$HOME/miniconda/bin:$PATH"
   - hash -r
   - conda config --set always_yes yes --set changeps1 no
-  #- conda update -q -y conda
-  - conda info -a # For debugging any issues with conda
+  - conda info -a # For debugging conda issues
   - conda config --add channels conda-forge
-  - conda create --yes --name condaenv python=$TRAVIS_PYTHON_VERSION
+  - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
+      conda create --yes --name condaenv python=3.7;
+    else
+      conda create --yes --name condaenv python=$TRAVIS_PYTHON_VERSION;
+    fi
   - source activate condaenv
-    # sudo installer -pkg /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg -target /;
+
 
 install:
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
@@ -69,46 +64,42 @@ install:
         COMPILERS=gcc_linux-64;
         MUMPS=mumps-mpi=5.1.2=h5bebb2f_1007;
     fi
-    # wget https://github.com/phracker/MacOSX-SDKs/releases/download/10.14-beta4/MacOSX10.14.sdk.tar.xz;
-    # mkdir ../sdk; tar xf MacOSX10.14.sdk.tar.xz -C ../sdk;
+
   - conda install $COMPILERS
-  #S- conda install nlopt petsc4py petsc mpi4py scipy $MPI
-  - conda install libblas libopenblas # Attempt to prevent 'File exists' error
+  - conda install libblas libopenblas # Prevent 'File exists' error
   - conda install nlopt petsc4py petsc $MUMPS mpi4py scipy $MPI
-  # pip install these as the conda installs downgrade pytest on python3.4
-  - pip install flake8
+  - pip install flake8       # Conda installs downgrade pytest on python3.4
   - pip install pytest
   - pip install pytest-cov
   - pip install pytest-timeout
   - pip install mock
   - pip install coveralls
-  # For confirmation of MPI library being used.
-  - python conda/find_mpi.py # locate compilers
-  - mpiexec --version # Show MPI library details
-  - pip install -e . # Installing libEnsemble
+  - python conda/find_mpi.py # Locate compilers. Confirm MPI library
+  - mpiexec --version        # Show MPI library details
+  - pip install -e .         # Installing libEnsemble
   - wget https://github.com/balsam-alcf/balsam/archive/0.3.5.1.tar.gz
   - mkdir ../balsam; tar xf 0.3.5.1.tar.gz -C ../balsam;
   - python conda/install-balsam.py
 
+
 before_script:
   - flake8 libensemble
   - echo "export BALSAM_DB_PATH=~/test-balsam" > setbalsampath.sh
-  - source setbalsampath.sh
-  # Allow 10000 files to be open at once (critical for persistent_aposmm)
-  - ulimit -Sn 10000
-  # - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
-  #       echo "export CONDA_BUILD_SYSROOT=/Users/travis/build/Libensemble/sdk/MacOSX10.14.sdk" > setenv.sh;
-  #       source setenv.sh;
-  #   fi
+  - source setbalsampath.sh # Imperfect method for env var persist after setup
+  - ulimit -Sn 10000   # More concurrent file descriptors (for persis aposmm)
+
+
 
 # Run test (-z show output)
 script:
   - ./libensemble/tests/run-tests.sh -z
 
-# Coverage
+
+# Track code coverage
 after_success:
   - mv libensemble/tests/.cov* .
   - coveralls
 
+
 after_failure:
 - cat libensemble/tests/regression_tests/log.err

From 4f24e7a51249fdf86e04e487f7e74de813caf114 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 1 Nov 2019 13:03:26 -0500
Subject: [PATCH 422/644] Starting to document new specs


From f98764ce6c54f680816a5a16914372e69c9f391f Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 1 Nov 2019 14:00:30 -0500
Subject: [PATCH 423/644] Moving function from libE.py to a utils file

---
 docs/data_structures/alloc_specs.rst          |   3 +
 docs/data_structures/history_array.rst        |   5 +-
 libensemble/history.py                        |   4 +-
 libensemble/libE.py                           | 212 +---------------
 libensemble/libE_fields.py                    |  11 -
 .../tests/unit_tests/tofix__test_worker.py    |   2 +-
 libensemble/utils.py                          | 228 ++++++++++++++++++
 7 files changed, 239 insertions(+), 226 deletions(-)
 delete mode 100644 libensemble/libE_fields.py
 create mode 100644 libensemble/utils.py

diff --git a/docs/data_structures/alloc_specs.rst b/docs/data_structures/alloc_specs.rst
index 4131d6c83..55d108b4f 100644
--- a/docs/data_structures/alloc_specs.rst
+++ b/docs/data_structures/alloc_specs.rst
@@ -18,6 +18,9 @@ Allocation function specifications to be set in user calling script and passed t
         'out' [list of tuples] :
             Default: [('allocated',bool)]
 
+        'batch_mode' [bool] :
+            Default: True
+
 
 .. note::
 
diff --git a/docs/data_structures/history_array.rst b/docs/data_structures/history_array.rst
index ab0c7a1b5..29cfba004 100644
--- a/docs/data_structures/history_array.rst
+++ b/docs/data_structures/history_array.rst
@@ -5,7 +5,7 @@ history array
 ::
 
     H: numpy structured array
-        History to store output from ``gen_f``/``sim_f``/``alloc_f`` for each entry
+        History to store output from gen_f/sim_f/alloc_f for each entry
 
 Fields in ``H`` include those specified in ``sim_specs['out']``,
 ``gen_specs['out']``, and ``alloc_specs['out']``. All values are initiated to
@@ -15,8 +15,9 @@ Fields in ``H`` include those specified in ``sim_specs['out']``,
 
 Below are the protected fields used in ``H``
 
-..  literalinclude:: ../../libensemble/libE_fields.py
+..  literalinclude:: ../../libensemble/utils.py
     :start-at: libE_fields
+    :end-before: end_libE_fields_rst_tag
 
 .. seealso::
 
diff --git a/libensemble/history.py b/libensemble/history.py
index d21bb1c2a..e73db4622 100644
--- a/libensemble/history.py
+++ b/libensemble/history.py
@@ -2,7 +2,7 @@
 import time
 import logging
 
-from libensemble.libE_fields import libE_fields
+from libensemble.utils import libE_fields
 
 logger = logging.getLogger(__name__)
 
@@ -20,7 +20,7 @@ class History:
 
     :ivar numpy_structured_array H:
         History array storing rows for each point. Field names are in
-        libensemble/libE_fields.py
+        libensemble/utils.py
 
     :ivar int offset:
         Starting index for this ensemble (after H0 read in)
diff --git a/libensemble/libE.py b/libensemble/libE.py
index b5c606369..fe9aaf0dd 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -4,7 +4,7 @@
 
 """
 
-__all__ = ['libE', 'check_inputs']
+__all__ = ['libE']
 
 import os
 import logging
@@ -24,62 +24,12 @@
 from libensemble.comms.logs import manager_logging_config
 from libensemble.comms.tcp_mgr import ServerQCommManager, ClientQCommManager
 from libensemble.controller import JobController
+from libensemble.utils import check_inputs, _USER_SIM_ID_WARNING, report_manager_exception
 
 logger = logging.getLogger(__name__)
 # To change logging level for just this module
 # logger.setLevel(logging.DEBUG)
 
-allowed_sim_spec_keys = ['sim_f',  #
-                         'in',     #
-                         'out',    #
-                         'user']   #
-
-allowed_gen_spec_keys = ['gen_f',  #
-                         'in',     #
-                         'out',    #
-                         'user']   #
-
-allowed_alloc_spec_keys = ['alloc_f',  #
-                           'in',       #
-                           'out',      #
-                           'user']     #
-
-allowed_libE_spec_keys = ['comms',               #
-                          'comm',                #
-                          'ip',                  #
-                          'port',                #
-                          'authkey',             #
-                          'workerID',            #
-                          'nprocesses',          #
-                          'worker_cmd',          #
-                          'abort_on_exception',  #
-                          'sim_dir',             #
-                          'sim_dir_prefix',      #
-                          'sim_dir_suffix',      #
-                          'clean_jobs',          #
-                          'save_every_k_sims',   #
-                          'save_every_k_gens',   #
-                          'profile_worker']      #
-
-
-def report_manager_exception(hist, persis_info, mgr_exc=None):
-    "Write out exception manager exception to log."
-    if mgr_exc is not None:
-        from_line, msg, exc = mgr_exc.args
-        logger.error("---- {} ----".format(from_line))
-        logger.error("Message: {}".format(msg))
-        logger.error(exc)
-    else:
-        logger.error(traceback.format_exc())
-    logger.error("Manager exception raised .. aborting ensemble:")
-    logger.error("Dumping ensemble history with {} sims evaluated:".
-                 format(hist.sim_count))
-
-    filename = 'libE_history_at_abort_' + str(hist.sim_count)
-    np.save(filename + '.npy', hist.trim_H())
-    with open(filename + '.pickle', "wb") as f:
-        pickle.dump(persis_info, f)
-
 
 def libE(sim_specs, gen_specs, exit_criteria,
          persis_info={},
@@ -475,161 +425,3 @@ def libE_tcp_worker(sim_specs, gen_specs, libE_specs):
         logger.debug("Worker {} exiting".format(workerID))
 
 
-# ==================== Common input checking =================================
-_USER_SIM_ID_WARNING = \
-    ('\n' + 79*'*' + '\n' +
-     "User generator script will be creating sim_id.\n" +
-     "Take care to do this sequentially.\n" +
-     "Also, any information given back for existing sim_id values will be overwritten!\n" +
-     "So everything in gen_specs['out'] should be in gen_specs['in']!" +
-     '\n' + 79*'*' + '\n\n')
-
-
-def check_consistent_field(name, field0, field1):
-    "Check that new field (field1) is compatible with an old field (field0)."
-    assert field0.ndim == field1.ndim, \
-        "H0 and H have different ndim for field {}".format(name)
-    assert (np.all(np.array(field1.shape) >= np.array(field0.shape))), \
-        "H too small to receive all components of H0 in field {}".format(name)
-
-
-def check_libE_specs(libE_specs, serial_check=False):
-    assert isinstance(libE_specs, dict), "libE_specs must be a dictionary"
-    comms_type = libE_specs.get('comms', 'mpi')
-    if comms_type in ['mpi']:
-        if not serial_check:
-            assert libE_specs['comm'].Get_size() > 1, "Manager only - must be at least one worker (2 MPI tasks)"
-    elif comms_type in ['local']:
-        assert libE_specs['nprocesses'] >= 1, "Must specify at least one worker"
-    elif comms_type in ['tcp']:
-        # TODO, differentiate and test SSH/Client
-        assert libE_specs['nprocesses'] >= 1, "Must specify at least one worker"
-
-    for k in libE_specs.keys():
-        assert k in allowed_libE_spec_keys, "Key %s is not allowed in libE_specs. Supported keys are: %s " % (k, allowed_libE_spec_keys)
-
-
-def check_alloc_specs(alloc_specs):
-    assert isinstance(alloc_specs, dict), "alloc_specs must be a dictionary"
-    assert alloc_specs['alloc_f'], "Allocation function must be specified"
-
-    for k in alloc_specs.keys():
-        assert k in allowed_alloc_spec_keys, "Key %s is not allowed in alloc_specs. Supported keys are: %s " % (k, allowed_alloc_spec_keys)
-
-
-def check_sim_specs(sim_specs):
-    assert isinstance(sim_specs, dict), "sim_specs must be a dictionary"
-    assert any([term_field in sim_specs for term_field in ['sim_f', 'in', 'out']]), \
-        "sim_specs must contain 'sim_f', 'in', 'out'"
-
-    assert len(sim_specs['out']), "sim_specs must have 'out' entries"
-    assert isinstance(sim_specs['in'], list), "'in' field must exist and be a list of field names"
-
-    for k in sim_specs.keys():
-        assert k in allowed_sim_spec_keys, "Key %s is not allowed in sim_specs. Supported keys are: %s " % (k, allowed_sim_spec_keys)
-
-
-def check_gen_specs(gen_specs):
-    assert isinstance(gen_specs, dict), "gen_specs must be a dictionary"
-    assert not bool(gen_specs) or len(gen_specs['out']), "gen_specs must have 'out' entries"
-
-    for k in gen_specs.keys():
-        assert k in allowed_gen_spec_keys, "Key %s is not allowed in gen_specs. Supported keys are: %s " % (k, allowed_gen_spec_keys)
-
-
-def check_exit_criteria(exit_criteria, sim_specs, gen_specs):
-    assert isinstance(exit_criteria, dict), "exit_criteria must be a dictionary"
-
-    assert len(exit_criteria) > 0, "Must have some exit criterion"
-
-    # Ensure termination criteria are valid
-    valid_term_fields = ['sim_max', 'gen_max',
-                         'elapsed_wallclock_time', 'stop_val']
-    assert all([term_field in valid_term_fields for term_field in exit_criteria]), \
-        "Valid termination options: " + str(valid_term_fields)
-
-    # Make sure stop-values match parameters in gen_specs or sim_specs
-    if 'stop_val' in exit_criteria:
-        stop_name = exit_criteria['stop_val'][0]
-        sim_out_names = [e[0] for e in sim_specs['out']]
-        gen_out_names = [e[0] for e in gen_specs['out']]
-        assert stop_name in sim_out_names + gen_out_names, \
-            "Can't stop on {} if it's not in a sim/gen output".format(stop_name)
-
-
-def check_H(H0, sim_specs, alloc_specs, gen_specs):
-    if len(H0):
-        # Handle if gen outputs sim IDs
-        from libensemble.libE_fields import libE_fields
-
-        # Set up dummy history to see if it agrees with H0
-        Dummy_H = np.zeros(1 + len(H0), dtype=libE_fields + list(set(sum([k['out'] for k in [sim_specs, alloc_specs, gen_specs] if k], []))))  # Combines all 'out' fields (if they exist) in sim_specs, gen_specs, or alloc_specs
-
-        fields = H0.dtype.names
-
-        # Prior history must contain the fields in new history
-        assert set(fields).issubset(set(Dummy_H.dtype.names)), \
-            "H0 contains fields {} not in the History.".\
-            format(set(fields).difference(set(Dummy_H.dtype.names)))
-
-        # Prior history cannot contain unreturned points
-        # assert 'returned' not in fields or np.all(H0['returned']), \
-        #     "H0 contains unreturned points."
-
-        # Fail if prior history contains unreturned points (or returned but not given).
-        assert('returned' not in fields or np.all(H0['given'] == H0['returned'])), \
-            'H0 contains unreturned or invalid points'
-
-        # Check dimensional compatibility of fields
-        for field in fields:
-            check_consistent_field(field, H0[field], Dummy_H[field])
-
-
-def check_inputs(libE_specs=None, alloc_specs=None, sim_specs=None, gen_specs=None, exit_criteria=None, H0=None, serial_check=False):
-    """
-    Check if the libEnsemble arguments are of the correct data type and contain
-    sufficient information to perform a run. There is no return value. An
-    exception is raised if any of the checks fail.
-
-    Parameters
-    ----------
-
-    libE_specs, alloc_specs, sim_specs, gen_specs, exit_criteria: :obj:`dict`, optional
-
-        libEnsemble data structures
-
-    H0: :obj:`numpy structured array`, optional
-
-        A previous libEnsemble history to be prepended to the history in the
-        current libEnsemble run
-        :doc:`(example)<data_structures/history_array>`
-
-    serial_check : :obj:`boolean`
-
-        If True, assumes running a serial check. This means, for example,
-        the details of current MPI communicator are not checked (can be
-        run with libE_specs{'comm': 'mpi'} without running through mpiexec.
-
-    """
-    # Detailed checking based on Required Keys in docs for each specs
-    if libE_specs is not None:
-        check_libE_specs(libE_specs, serial_check)
-
-    if alloc_specs is not None:
-        check_alloc_specs(alloc_specs)
-
-    if sim_specs is not None:
-        check_sim_specs(sim_specs)
-
-    if gen_specs is not None:
-        check_gen_specs(gen_specs)
-
-    if exit_criteria is not None:
-        assert sim_specs is not None and gen_specs is not None, \
-            "Can't check exit_criteria without sim_specs and gen_specs"
-        check_exit_criteria(exit_criteria, sim_specs, gen_specs)
-
-    if H0 is not None:
-        assert sim_specs is not None and alloc_specs is not None and gen_specs is not None, \
-            "Can't check H0 without sim_specs, alloc_specs, gen_specs"
-        check_H(H0, sim_specs, alloc_specs, gen_specs)
diff --git a/libensemble/libE_fields.py b/libensemble/libE_fields.py
deleted file mode 100644
index 32f23eba0..000000000
--- a/libensemble/libE_fields.py
+++ /dev/null
@@ -1,11 +0,0 @@
-"""
-Below are the fields used within libEnsemble
-"""
-libE_fields = [('sim_id', int),        # Unique id of entry in H that was generated
-               ('gen_worker', int),    # Worker that generated the entry
-               ('gen_time', float),    # Time (since epoch) entry was entered into H
-               ('given', bool),        # True if entry has been given for sim eval
-               ('returned', bool),     # True if entry has been returned from sim eval
-               ('given_time', float),  # Time (since epoch) that the entry was given
-               ('sim_worker', int),    # Worker that did (or is doing) the sim eval
-               ]
diff --git a/libensemble/tests/unit_tests/tofix__test_worker.py b/libensemble/tests/unit_tests/tofix__test_worker.py
index e4db0d837..8ef863734 100644
--- a/libensemble/tests/unit_tests/tofix__test_worker.py
+++ b/libensemble/tests/unit_tests/tofix__test_worker.py
@@ -1,5 +1,5 @@
 import libensemble.tests.unit_tests.setup as setup
-from libensemble.libE_fields import libE_fields
+from libensemble.utils import libE_fields
 from libensemble.libE_worker import Worker
 from libensemble.message_numbers import EVAL_SIM_TAG
 import numpy as np
diff --git a/libensemble/utils.py b/libensemble/utils.py
new file mode 100644
index 000000000..f5d34a476
--- /dev/null
+++ b/libensemble/utils.py
@@ -0,0 +1,228 @@
+"""
+libEnsemble utilities
+============================================
+
+"""
+
+
+"""
+Below are the fields used within libEnsemble
+"""
+libE_fields = [('sim_id', int),        # Unique id of entry in H that was generated
+               ('gen_worker', int),    # Worker that generated the entry
+               ('gen_time', float),    # Time (since epoch) entry was entered into H
+               ('given', bool),        # True if entry has been given for sim eval
+               ('returned', bool),     # True if entry has been returned from sim eval
+               ('given_time', float),  # Time (since epoch) that the entry was given
+               ('sim_worker', int),    # Worker that did (or is doing) the sim eval
+               ]
+# end_libE_fields_rst_tag
+
+allowed_sim_spec_keys = ['sim_f',  #
+                         'in',     #
+                         'out',    #
+                         'user']   #
+
+allowed_gen_spec_keys = ['gen_f',  #
+                         'in',     #
+                         'out',    #
+                         'user']   #
+
+allowed_alloc_spec_keys = ['alloc_f',  #
+                           'in',       #
+                           'out',      #
+                           'user']     #
+
+allowed_libE_spec_keys = ['comms',               #
+                          'comm',                #
+                          'ip',                  #
+                          'port',                #
+                          'authkey',             #
+                          'workerID',            #
+                          'nprocesses',          #
+                          'worker_cmd',          #
+                          'abort_on_exception',  #
+                          'sim_dir',             #
+                          'sim_dir_prefix',      #
+                          'sim_dir_suffix',      #
+                          'clean_jobs',          #
+                          'save_every_k_sims',   #
+                          'save_every_k_gens',   #
+                          'profile_worker']      #
+
+
+def report_manager_exception(hist, persis_info, mgr_exc=None):
+    "Write out exception manager exception to log."
+    if mgr_exc is not None:
+        from_line, msg, exc = mgr_exc.args
+        logger.error("---- {} ----".format(from_line))
+        logger.error("Message: {}".format(msg))
+        logger.error(exc)
+    else:
+        logger.error(traceback.format_exc())
+    logger.error("Manager exception raised .. aborting ensemble:")
+    logger.error("Dumping ensemble history with {} sims evaluated:".
+                 format(hist.sim_count))
+
+    filename = 'libE_history_at_abort_' + str(hist.sim_count)
+    np.save(filename + '.npy', hist.trim_H())
+    with open(filename + '.pickle', "wb") as f:
+        pickle.dump(persis_info, f)
+
+
+
+# ==================== Common input checking =================================
+_USER_SIM_ID_WARNING = \
+    ('\n' + 79*'*' + '\n' +
+     "User generator script will be creating sim_id.\n" +
+     "Take care to do this sequentially.\n" +
+     "Also, any information given back for existing sim_id values will be overwritten!\n" +
+     "So everything in gen_specs['out'] should be in gen_specs['in']!" +
+     '\n' + 79*'*' + '\n\n')
+
+
+def check_consistent_field(name, field0, field1):
+    "Check that new field (field1) is compatible with an old field (field0)."
+    assert field0.ndim == field1.ndim, \
+        "H0 and H have different ndim for field {}".format(name)
+    assert (np.all(np.array(field1.shape) >= np.array(field0.shape))), \
+        "H too small to receive all components of H0 in field {}".format(name)
+
+
+def check_libE_specs(libE_specs, serial_check=False):
+    assert isinstance(libE_specs, dict), "libE_specs must be a dictionary"
+    comms_type = libE_specs.get('comms', 'mpi')
+    if comms_type in ['mpi']:
+        if not serial_check:
+            assert libE_specs['comm'].Get_size() > 1, "Manager only - must be at least one worker (2 MPI tasks)"
+    elif comms_type in ['local']:
+        assert libE_specs['nprocesses'] >= 1, "Must specify at least one worker"
+    elif comms_type in ['tcp']:
+        # TODO, differentiate and test SSH/Client
+        assert libE_specs['nprocesses'] >= 1, "Must specify at least one worker"
+
+    for k in libE_specs.keys():
+        assert k in allowed_libE_spec_keys, "Key %s is not allowed in libE_specs. Supported keys are: %s " % (k, allowed_libE_spec_keys)
+
+
+def check_alloc_specs(alloc_specs):
+    assert isinstance(alloc_specs, dict), "alloc_specs must be a dictionary"
+    assert alloc_specs['alloc_f'], "Allocation function must be specified"
+
+    for k in alloc_specs.keys():
+        assert k in allowed_alloc_spec_keys, "Key %s is not allowed in alloc_specs. Supported keys are: %s " % (k, allowed_alloc_spec_keys)
+
+
+def check_sim_specs(sim_specs):
+    assert isinstance(sim_specs, dict), "sim_specs must be a dictionary"
+    assert any([term_field in sim_specs for term_field in ['sim_f', 'in', 'out']]), \
+        "sim_specs must contain 'sim_f', 'in', 'out'"
+
+    assert len(sim_specs['out']), "sim_specs must have 'out' entries"
+    assert isinstance(sim_specs['in'], list), "'in' field must exist and be a list of field names"
+
+    for k in sim_specs.keys():
+        assert k in allowed_sim_spec_keys, "Key %s is not allowed in sim_specs. Supported keys are: %s " % (k, allowed_sim_spec_keys)
+
+
+def check_gen_specs(gen_specs):
+    assert isinstance(gen_specs, dict), "gen_specs must be a dictionary"
+    assert not bool(gen_specs) or len(gen_specs['out']), "gen_specs must have 'out' entries"
+
+    for k in gen_specs.keys():
+        assert k in allowed_gen_spec_keys, "Key %s is not allowed in gen_specs. Supported keys are: %s " % (k, allowed_gen_spec_keys)
+
+
+def check_exit_criteria(exit_criteria, sim_specs, gen_specs):
+    assert isinstance(exit_criteria, dict), "exit_criteria must be a dictionary"
+
+    assert len(exit_criteria) > 0, "Must have some exit criterion"
+
+    # Ensure termination criteria are valid
+    valid_term_fields = ['sim_max', 'gen_max',
+                         'elapsed_wallclock_time', 'stop_val']
+    assert all([term_field in valid_term_fields for term_field in exit_criteria]), \
+        "Valid termination options: " + str(valid_term_fields)
+
+    # Make sure stop-values match parameters in gen_specs or sim_specs
+    if 'stop_val' in exit_criteria:
+        stop_name = exit_criteria['stop_val'][0]
+        sim_out_names = [e[0] for e in sim_specs['out']]
+        gen_out_names = [e[0] for e in gen_specs['out']]
+        assert stop_name in sim_out_names + gen_out_names, \
+            "Can't stop on {} if it's not in a sim/gen output".format(stop_name)
+
+
+def check_H(H0, sim_specs, alloc_specs, gen_specs):
+    if len(H0):
+        # Set up dummy history to see if it agrees with H0
+        Dummy_H = np.zeros(1 + len(H0), dtype=libE_fields + list(set(sum([k['out'] for k in [sim_specs, alloc_specs, gen_specs] if k], []))))  # Combines all 'out' fields (if they exist) in sim_specs, gen_specs, or alloc_specs
+
+        fields = H0.dtype.names
+
+        # Prior history must contain the fields in new history
+        assert set(fields).issubset(set(Dummy_H.dtype.names)), \
+            "H0 contains fields {} not in the History.".\
+            format(set(fields).difference(set(Dummy_H.dtype.names)))
+
+        # Prior history cannot contain unreturned points
+        # assert 'returned' not in fields or np.all(H0['returned']), \
+        #     "H0 contains unreturned points."
+
+        # Fail if prior history contains unreturned points (or returned but not given).
+        assert('returned' not in fields or np.all(H0['given'] == H0['returned'])), \
+            'H0 contains unreturned or invalid points'
+
+        # Check dimensional compatibility of fields
+        for field in fields:
+            check_consistent_field(field, H0[field], Dummy_H[field])
+
+
+def check_inputs(libE_specs=None, alloc_specs=None, sim_specs=None, gen_specs=None, exit_criteria=None, H0=None, serial_check=False):
+    """
+    Check if the libEnsemble arguments are of the correct data type and contain
+    sufficient information to perform a run. There is no return value. An
+    exception is raised if any of the checks fail.
+
+    Parameters
+    ----------
+
+    libE_specs, alloc_specs, sim_specs, gen_specs, exit_criteria: :obj:`dict`, optional
+
+        libEnsemble data structures
+
+    H0: :obj:`numpy structured array`, optional
+
+        A previous libEnsemble history to be prepended to the history in the
+        current libEnsemble run
+        :doc:`(example)<data_structures/history_array>`
+
+    serial_check : :obj:`boolean`
+
+        If True, assumes running a serial check. This means, for example,
+        the details of current MPI communicator are not checked (can be
+        run with libE_specs{'comm': 'mpi'} without running through mpiexec.
+
+    """
+    # Detailed checking based on Required Keys in docs for each specs
+    if libE_specs is not None:
+        check_libE_specs(libE_specs, serial_check)
+
+    if alloc_specs is not None:
+        check_alloc_specs(alloc_specs)
+
+    if sim_specs is not None:
+        check_sim_specs(sim_specs)
+
+    if gen_specs is not None:
+        check_gen_specs(gen_specs)
+
+    if exit_criteria is not None:
+        assert sim_specs is not None and gen_specs is not None, \
+            "Can't check exit_criteria without sim_specs and gen_specs"
+        check_exit_criteria(exit_criteria, sim_specs, gen_specs)
+
+    if H0 is not None:
+        assert sim_specs is not None and alloc_specs is not None and gen_specs is not None, \
+            "Can't check H0 without sim_specs, alloc_specs, gen_specs"
+        check_H(H0, sim_specs, alloc_specs, gen_specs)

From 5ba6df1bb032bde48cc62e69ab9a740fc5ab3203 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 1 Nov 2019 14:14:49 -0500
Subject: [PATCH 424/644] An inital movement of documenting 'user'

---
 docs/data_structures/alloc_specs.rst |  3 ++-
 docs/data_structures/gen_specs.rst   | 20 +++++++++-----------
 docs/data_structures/libE_specs.rst  | 16 +++++++++++++++-
 docs/data_structures/sim_specs.rst   | 25 +++++++------------------
 4 files changed, 33 insertions(+), 31 deletions(-)

diff --git a/docs/data_structures/alloc_specs.rst b/docs/data_structures/alloc_specs.rst
index 55d108b4f..4ed81d8e1 100644
--- a/docs/data_structures/alloc_specs.rst
+++ b/docs/data_structures/alloc_specs.rst
@@ -4,7 +4,8 @@
 alloc_specs
 ===========
 
-Allocation function specifications to be set in user calling script and passed to libE.libE()::
+Allocation function specifications to be set in user calling script and passed
+to main ``libE()`` routine::
 
     alloc_specs: [dict, optional] :
 
diff --git a/docs/data_structures/gen_specs.rst b/docs/data_structures/gen_specs.rst
index c2cfd8c8a..8e8f15711 100644
--- a/docs/data_structures/gen_specs.rst
+++ b/docs/data_structures/gen_specs.rst
@@ -3,7 +3,8 @@
 gen_specs
 =========
 
-Generation function specifications to be set in user calling script and passed to libE.libE()::
+Generation function specifications to be set in user calling script and passed
+to main ``libE()`` routine::
 
     gen_specs: [dict]:
 
@@ -15,21 +16,18 @@ Generation function specifications to be set in user calling script and passed t
             field names (as strings) that will be given to gen_f
         'out' [list of tuples (field name, data type, [size])] :
             gen_f outputs that will be stored in the libEnsemble history
-
-        Optional keys :
-
-        'save_every_k' [int] :
-            Save history array to file after every k generated points.
+        'user' [dict]: 
+            Data structure to contain problem specific constants and/or input data
 
 .. note::
 
-  * The user may define other fields to be passed to the generator function.
+  * The user may define fields only in ``'user'`` to be passed to the generator function.
   * The tuples defined in the 'out' list are entered into the master :ref:`history array<datastruct-history-array>`
-  * The generator 'out' field will generally include a variable(s) which is used for the simulator 'in' field,
-    in which case only the variable name is required for the simulator 'in' field.  E.g. The
+  * The generator ``'out'`` field will generally include a variable(s) which is used for the simulator 'in' field,
+    in which case only the variable name is required for the simulator ``'in'`` field.  E.g. The
     **test_6-hump_camel_uniform_sampling.py** example below, matches the corresponding
-    :ref:`sim_specs example<sim-specs-exmple1>`, where 'x' is defined in the gen_specs 'out' field to give
-    two positional floats.
+    :ref:`sim_specs example<sim-specs-exmple1>`, where ``'x'`` is defined in the gen_specs ``'out'`` field to give
+    two-dimensional floats.
 
 
 .. seealso::
diff --git a/docs/data_structures/libE_specs.rst b/docs/data_structures/libE_specs.rst
index 2d47e4e19..5fbff8752 100644
--- a/docs/data_structures/libE_specs.rst
+++ b/docs/data_structures/libE_specs.rst
@@ -5,7 +5,7 @@ libE_specs
 
 Specifications for libEnsemble::
 
-    libE_specs: [dict] :
+    libE_specs: [dict, optional] :
         'comms' [string] :
             Manager/Worker communications mode. Default: mpi
             Options are 'mpi', 'local', 'tcp'
@@ -16,6 +16,20 @@ Specifications for libEnsemble::
         'abort_on_exception' [boolean] :
             In MPI mode, whether to call MPI_ABORT on an exception. Default: True
             IF False, an exception will be raised by the manager.
+        'save_every_k_sims' [int] :
+            Save history array to file after every k simulated points.
+        'save_every_k_gens' [int] :
+            Save history array to file after every k generated points.
+        'sim_dir' [str] :
+            Name of simulation directory which will be copied for each worker
+        'clean_jobs' [bool] :
+            Clean up sim_dirs after libEnsemble completes. Default: False
+        'sim_dir_prefix' [str] :
+            A prefix path specifying where to create sim directories
+        'sim_dir_suffix' [str] :
+            A suffix to add to worker copies of sim_dir to distinguish runs.
+        'profile_worker' [Boolean] :
+            Profile using cProfile. Default: False
 
 .. seealso::
   Examples in `common.py`_
diff --git a/docs/data_structures/sim_specs.rst b/docs/data_structures/sim_specs.rst
index 02fca0801..8fb726bb3 100644
--- a/docs/data_structures/sim_specs.rst
+++ b/docs/data_structures/sim_specs.rst
@@ -3,40 +3,29 @@
 sim_specs
 =========
 
-Simulation function specifications to be set in user calling script and passed to ``libE.libE()``::
+Simulation function specifications to be set in user calling script and passed
+to main ``libE()`` routine::
 
 
     sim_specs: [dict]:
 
-        Required keys :
-
         'sim_f' [func] :
             the simulation function being evaluated
         'in' [list] :
-            field names (as strings) that will be given to sim_f
+            field names (as strings) to be given to sim_f by alloc_f
         'out' [list of tuples (field name, data type, [size])] :
             sim_f outputs that will be stored in the libEnsemble history
+        'user' [dict,optional]: 
+            Data structure to contain problem specific constants and/or input data
 
 
-        Optional keys :
-
-        'save_every_k' [int] :
-            Save history array to file after every k simulated points.
-        'sim_dir' [str] :
-            Name of simulation directory which will be copied for each worker
-        'sim_dir_prefix' [str] :
-            A prefix path specifying where to create sim directories
-        'sim_dir_suffix' [str] :
-            A suffix to add to worker copies of sim_dir to distinguish runs.
-         'profile' [Boolean] :
-            Profile using cProfile. Default: False
 
         Additional entires in sim_specs will be given to sim_f
 
 .. note::
-  * The user may define other fields to be passed to the simulator function.
+  * The user may define fields only in ``'user'`` to be passed to the simulator function.
   * The tuples defined in the ``'out'`` list are entered into the master :ref:`history array<datastruct-history-array>`
-  * The ``sim_dir_prefix`` option may be used to create simulation working directories in node local/scratch storage when workers are distributed. This may have a performance benefit with I/O heavy sim funcs.
+  * The ``libE_specs['sim_dir_prefix']`` option may be used to create simulation working directories in node local/scratch storage when workers are distributed. This may have a performance benefit with I/O heavy sim funcs.
 
 
 .. seealso::

From 853d6372c577a57a99c020e52bd235274eeaabcf Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 1 Nov 2019 14:19:06 -0500
Subject: [PATCH 425/644] adding a word

---
 libensemble/libE.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/libensemble/libE.py b/libensemble/libE.py
index fe9aaf0dd..9aa0fbc85 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -102,7 +102,9 @@ def libE(sim_specs, gen_specs, exit_criteria,
 
     exit_flag: :obj:`int`
 
-        Flag containing job status: 0 = No errors,
+        Flag containing final job status: 
+
+        0 = No errors
         1 = Exception occured
         2 = Manager timed out and ended simulation
         3 = Current process is not in libEnsemble MPI communicator

From 49f814cc5171b22da6e72fec253349b0ff637603 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 1 Nov 2019 15:25:14 -0500
Subject: [PATCH 426/644] Moving imports from libE to utils

---
 libensemble/libE.py  |  7 +------
 libensemble/utils.py | 10 +++++++++-
 2 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/libensemble/libE.py b/libensemble/libE.py
index 9aa0fbc85..089c87e07 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -8,12 +8,9 @@
 
 import os
 import logging
-import traceback
 import random
 import socket
-import pickle  # Only used when saving output on error
 
-import numpy as np
 import libensemble.util.launcher as launcher
 from libensemble.util.timer import Timer
 from libensemble.history import History
@@ -102,7 +99,7 @@ def libE(sim_specs, gen_specs, exit_criteria,
 
     exit_flag: :obj:`int`
 
-        Flag containing final job status: 
+        Flag containing final job status:
 
         0 = No errors
         1 = Exception occured
@@ -425,5 +422,3 @@ def libE_tcp_worker(sim_specs, gen_specs, libE_specs):
         worker_main(comm, sim_specs, gen_specs, libE_specs,
                     workerID=workerID, log_comm=True)
         logger.debug("Worker {} exiting".format(workerID))
-
-
diff --git a/libensemble/utils.py b/libensemble/utils.py
index f5d34a476..435ef1cd1 100644
--- a/libensemble/utils.py
+++ b/libensemble/utils.py
@@ -4,6 +4,15 @@
 
 """
 
+import traceback
+import logging
+import numpy as np
+import pickle  # Only used when saving output on error
+
+logger = logging.getLogger(__name__)
+# To change logging level for just this module
+# logger.setLevel(logging.DEBUG)
+
 
 """
 Below are the fields used within libEnsemble
@@ -70,7 +79,6 @@ def report_manager_exception(hist, persis_info, mgr_exc=None):
         pickle.dump(persis_info, f)
 
 
-
 # ==================== Common input checking =================================
 _USER_SIM_ID_WARNING = \
     ('\n' + 79*'*' + '\n' +

From 79c110ec14ce548802abfa7f21d37bf984e0fecd Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 1 Nov 2019 16:03:47 -0500
Subject: [PATCH 427/644] Starting re-org of documentation

---
 docs/data_structures/data_structures.rst      | 25 +++++++------
 docs/data_structures/gen_specs.rst            |  2 +-
 docs/data_structures/sim_specs.rst            | 36 +++++++++++--------
 .../test_6-hump_camel_uniform_sampling.py     | 14 ++++----
 .../scaling_tests/forces/run_libe_forces.py   | 23 ++++++------
 5 files changed, 55 insertions(+), 45 deletions(-)

diff --git a/docs/data_structures/data_structures.rst b/docs/data_structures/data_structures.rst
index dc55d7ae6..71c2398db 100644
--- a/docs/data_structures/data_structures.rst
+++ b/docs/data_structures/data_structures.rst
@@ -1,25 +1,30 @@
 Data Structures
 ===============
 
-Users can check the formatting and consistency of ``exit_criteria`` and each ``specs``
-dictionary with the ``check_inputs()`` function within the ``libE module``.
-Provide any combination of these data structures as keyword arguments.
-For example::
+This section outlines the data structures used by libEnsemble.
+
+.. note::
+  Users can check the formatting and consistency of ``exit_criteria`` and each ``specs``
+  dictionary with the ``check_inputs()`` function from the ``utils`` module.
+  Provide any combination of these data structures as keyword arguments.
+  For example::
 
     from libensemble.libE import check_inputs
 
     check_inputs(sim_specs=my-sim_specs, gen_specs=my-gen_specs, exit_criteria=ec)
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
    :caption: libEnsemble Data Structures:
 
-   history_array
-   worker_array
-   work_dict
-   libE_specs
    sim_specs
    gen_specs
-   exit_criteria
    alloc_specs
+   libE_specs
    persis_info
+   exit_criteria
+
+
+   history_array
+   worker_array
+   work_dict
diff --git a/docs/data_structures/gen_specs.rst b/docs/data_structures/gen_specs.rst
index 8e8f15711..152105ca6 100644
--- a/docs/data_structures/gen_specs.rst
+++ b/docs/data_structures/gen_specs.rst
@@ -16,7 +16,7 @@ to main ``libE()`` routine::
             field names (as strings) that will be given to gen_f
         'out' [list of tuples (field name, data type, [size])] :
             gen_f outputs that will be stored in the libEnsemble history
-        'user' [dict]: 
+        'user' [dict]:
             Data structure to contain problem specific constants and/or input data
 
 .. note::
diff --git a/docs/data_structures/sim_specs.rst b/docs/data_structures/sim_specs.rst
index 8fb726bb3..1ad4138c6 100644
--- a/docs/data_structures/sim_specs.rst
+++ b/docs/data_structures/sim_specs.rst
@@ -1,31 +1,37 @@
-.. _datastruct-sim-specs:
+*********************
+Input data structures
+*********************
+We first describe the dictionaries given to libEnsemble to specify the
+inputs/outputs of the ensemble of calculations to be performed.
 
 sim_specs
 =========
+.. _datastruct-sim-specs:
 
-Simulation function specifications to be set in user calling script and passed
-to main ``libE()`` routine::
-
+Used to specify the simulation function, its inputs and outputs, and user data::
 
     sim_specs: [dict]:
 
-        'sim_f' [func] :
+        'sim_f' [func]:
             the simulation function being evaluated
-        'in' [list] :
+        'in' [list]:
             field names (as strings) to be given to sim_f by alloc_f
-        'out' [list of tuples (field name, data type, [size])] :
-            sim_f outputs that will be stored in the libEnsemble history
-        'user' [dict,optional]: 
+        'out' [list of tuples (field name, data type, [size])]:
+            sim_f outputs to be stored in the libEnsemble history
+        'user' [dict, optional]:
             Data structure to contain problem specific constants and/or input data
 
+.. note::
+  * The entirety of ``sim_specs`` is passed from the worker each time a
+    simulation is requested by the allocation function.
 
+  * The tuples in ``sim_specs['out']`` are entered into the master
+    :ref:`history array<datastruct-history-array>`
 
-        Additional entires in sim_specs will be given to sim_f
-
-.. note::
-  * The user may define fields only in ``'user'`` to be passed to the simulator function.
-  * The tuples defined in the ``'out'`` list are entered into the master :ref:`history array<datastruct-history-array>`
-  * The ``libE_specs['sim_dir_prefix']`` option may be used to create simulation working directories in node local/scratch storage when workers are distributed. This may have a performance benefit with I/O heavy sim funcs.
+  * The ``libE_specs['sim_dir_prefix']`` option may be used to create
+    simulation working directories in node local/scratch storage when workers
+    are distributed. This may have a performance benefit with I/O heavy
+    simulations.
 
 
 .. seealso::
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
index 5aee7dc9a..d6263f0dc 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
@@ -28,16 +28,16 @@
 libE_specs['save_every_k_gens'] = 300
 
 sim_specs = {'sim_f': sim_f,         # Function whose output is being minimized
-             'in': ['x'],            # Keys to be given to the above function
-             'out': [('f', float)],  # Output from the function being minimized
+             'in': ['x'],            # Keys to be given to sim_f
+             'out': [('f', float)],  # Name of the outputs from sim_f
              }
 # end_sim_specs_rst_tag
 
-gen_specs = {'gen_f': gen_f,               # Tell libE function generating sim_f input
-             'out': [('x', float, (2,))],  # Tell libE gen_f output, type, size
-             'user': {'gen_batch_size': 500,        # Tell gen_f how much to generate per call
-                      'lb': np.array([-3, -2]),     # Tell gen_f lower bounds
-                      'ub': np.array([3, 2])        # Tell gen_f upper bounds
+gen_specs = {'gen_f': gen_f,                     # Function generating sim_f input
+             'out': [('x', float, (2,))],        # Tell libE gen_f output, type, size
+             'user': {'gen_batch_size': 500,     # Used by this specific gen_f
+                      'lb': np.array([-3, -2]),  # Used by this specific gen_f
+                      'ub': np.array([3, 2])     # Used by this specific gen_f
                       }
              }
 # end_gen_specs_rst_tag
diff --git a/libensemble/tests/scaling_tests/forces/run_libe_forces.py b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
index b647422b0..1ab8a0fd2 100644
--- a/libensemble/tests/scaling_tests/forces/run_libe_forces.py
+++ b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
@@ -67,18 +67,17 @@
 
 # State the objective function, its arguments, output, and necessary parameters (and their sizes)
 sim_specs = {'sim_f': run_forces,         # Function whose output is being minimized
-             'in': ['x'],                 # Name of input data structure for sim func
-             'out': [('energy', float)],  # Output from sim func
-             'user': {'sim_dir_suffix': 'test',    # Suffix for copied sim dirs (to ID run)
-                      'simdir_basename': 'force',  # Used by sim_f to name sim directories
-                      'keys': ['seed'],            # Key/keys for input data
-                      'cores': 2,                  # Used by sim_f to set number of cores used
-                      'sim_particles': 1e3,        # Used by sim_f for number of particles
-                      'sim_timesteps': 5,          # Used by sim_f for number of timesteps
-                      'sim_kill_minutes': 10.0,    # Used by sim_f to set max run time
-                      'particle_variance': 0.2,    # Used by sim_f to vary load imbalance
-                      'kill_rate': 0.5,            # Fraction of bad sim_f evals (tests kills)
-                      }
+             'in': ['x'],                 # Name of input for sim_f
+             'out': [('energy', float)],  # Name, type of output from sim_f
+             'user': {'sim_dir_suffix': 'test',    
+                      'simdir_basename': 'force',  
+                      'keys': ['seed'],            
+                      'cores': 2,                  
+                      'sim_particles': 1e3,        
+                      'sim_timesteps': 5,          
+                      'sim_kill_minutes': 10.0,    
+                      'particle_variance': 0.2,    
+                      'kill_rate': 0.5}   # Used by this specific sim_f
              }
 # end_sim_specs_rst_tag
 

From 756d0f4c115287d724e7d3b4bb3b83862cbca7eb Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 1 Nov 2019 16:04:27 -0500
Subject: [PATCH 428/644] Whitespace

---
 .../scaling_tests/forces/run_libe_forces.py      | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/libensemble/tests/scaling_tests/forces/run_libe_forces.py b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
index 1ab8a0fd2..d0ed23af8 100644
--- a/libensemble/tests/scaling_tests/forces/run_libe_forces.py
+++ b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
@@ -69,14 +69,14 @@
 sim_specs = {'sim_f': run_forces,         # Function whose output is being minimized
              'in': ['x'],                 # Name of input for sim_f
              'out': [('energy', float)],  # Name, type of output from sim_f
-             'user': {'sim_dir_suffix': 'test',    
-                      'simdir_basename': 'force',  
-                      'keys': ['seed'],            
-                      'cores': 2,                  
-                      'sim_particles': 1e3,        
-                      'sim_timesteps': 5,          
-                      'sim_kill_minutes': 10.0,    
-                      'particle_variance': 0.2,    
+             'user': {'sim_dir_suffix': 'test',
+                      'simdir_basename': 'force',
+                      'keys': ['seed'],
+                      'cores': 2,
+                      'sim_particles': 1e3,
+                      'sim_timesteps': 5,
+                      'sim_kill_minutes': 10.0,
+                      'particle_variance': 0.2,
                       'kill_rate': 0.5}   # Used by this specific sim_f
              }
 # end_sim_specs_rst_tag

From 004d361020794850ed95826970d6372ffe51d8dc Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 1 Nov 2019 16:06:06 -0500
Subject: [PATCH 429/644] adding another level of organization to data
 structure section

---
 docs/data_structures/history_array.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/data_structures/history_array.rst b/docs/data_structures/history_array.rst
index 29cfba004..d74488f3d 100644
--- a/docs/data_structures/history_array.rst
+++ b/docs/data_structures/history_array.rst
@@ -1,3 +1,7 @@
+***********************************
+Internal libEnsemble data structure
+***********************************
+
 .. _datastruct-history-array:
 
 history array

From ea313628f214e6bcae98a485dbd5eebb6323a3ac Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 5 Nov 2019 17:27:41 -0600
Subject: [PATCH 430/644] Trialing new affinity diagrams, structural changes,
 remove unnecessary content, reorganization

---
 docs/images/centralized_Balsam_ThS.png | Bin 0 -> 57918 bytes
 docs/images/centralized_Bb.png         | Bin 0 -> 35065 bytes
 docs/images/distributed_Bb.png         | Bin 0 -> 26099 bytes
 docs/index.rst                         |   3 +-
 docs/platforms/bebop.rst               |  46 ++++++++++-------------
 docs/platforms/platforms_index.rst     |  50 +++++++++++++++++++++++++
 docs/platforms/theta.rst               |  23 ++++--------
 7 files changed, 77 insertions(+), 45 deletions(-)
 create mode 100644 docs/images/centralized_Balsam_ThS.png
 create mode 100644 docs/images/centralized_Bb.png
 create mode 100644 docs/images/distributed_Bb.png
 create mode 100644 docs/platforms/platforms_index.rst

diff --git a/docs/images/centralized_Balsam_ThS.png b/docs/images/centralized_Balsam_ThS.png
new file mode 100644
index 0000000000000000000000000000000000000000..f6ff9451d904ea2450a687108b54599cf88123e6
GIT binary patch
literal 57918
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

literal 0
HcmV?d00001

diff --git a/docs/images/centralized_Bb.png b/docs/images/centralized_Bb.png
new file mode 100644
index 0000000000000000000000000000000000000000..0a9ffa175d08843193db2d716533d7b7b46a132f
GIT binary patch
literal 35065
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

literal 0
HcmV?d00001

diff --git a/docs/images/distributed_Bb.png b/docs/images/distributed_Bb.png
new file mode 100644
index 0000000000000000000000000000000000000000..086c8b1ae4e86657f9dd7b3cbbe2a69a211c4aa0
GIT binary patch
literal 26099
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
MRc)0#B~$-@1IMNnJpcdz

literal 0
HcmV?d00001

diff --git a/docs/index.rst b/docs/index.rst
index ffeed0f44..874c54101 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -81,8 +81,7 @@ libEnsemble is a library for managing ensemble-like collections of computations.
      :maxdepth: 1
      :caption: Running on:
 
-     platforms/bebop
-     platforms/theta
+     platforms/platforms_index
 
 
   .. toctree::
diff --git a/docs/platforms/bebop.rst b/docs/platforms/bebop.rst
index 5ff711620..6c419ba87 100644
--- a/docs/platforms/bebop.rst
+++ b/docs/platforms/bebop.rst
@@ -2,19 +2,8 @@
 Bebop
 =====
 
-Bebop_ is the newest addition to the computational power of LCRC at Argonne
-National Laboratory, featuring both Intel Broadwell and Knights Landing nodes.
-
-
-Before Getting Started
-----------------------
-
-An Argonne LCRC_ account is required to access Bebop. Interested users will need
-to apply for and be granted an account before continuing. To submit jobs to Bebop,
-users can charge hours to a project or their personal allocation (default).
-
-Bebop consists primarily of login and compute nodes. Users start on the login
-nodes, and schedule work for execution on the compute nodes.
+Bebop_ is a Cray CS400 cluster available within LCRC at Argonne National Laboratory,
+featuring both Intel Broadwell and Knights Landing compute nodes.
 
 
 Configuring Python
@@ -22,7 +11,7 @@ Configuring Python
 
 Begin by loading the Python 3 Anaconda_ module::
 
-    module load anaconda3/2018.12
+    module load anaconda3
 
 Create a Conda_ virtual environment in which to install libEnsemble and all
 dependencies::
@@ -49,8 +38,9 @@ following block:
 Job Submission
 --------------
 
-Bebop uses Slurm_ for job submission and management. The two commands you'll likely use the most
-to run jobs are ``srun`` and ``sbatch`` for running interactively and batch, respectively.
+Bebop uses Slurm_ for job submission and management. The two commands you'll
+likely use the most to run jobs are ``srun`` and ``sbatch`` for running
+interactively and batch, respectively.
 
 
 Interactive Runs
@@ -75,6 +65,17 @@ worker can perform stand-alone calculations or launch jobs through the job contr
     worker run together on a node.
 
 
+If you would like to interact directly with the compute nodes via a shell,
+the following showcases starting a bash session on a Knights Landing node
+for thirty minutes::
+
+    srun --pty -A [username OR project] -p knl -t 00:30:00 /bin/bash
+
+.. note::
+    You will need to re-activate your conda virtual environment and reload your
+    modules! Configuring this routine to occur automatically is recommended.
+
+
 Batch Runs
 ^^^^^^^^^^
 
@@ -111,16 +112,8 @@ on Bebop becomes::
 Debugging Strategies
 --------------------
 
-View the status of your submitted jobs with ``squeue`` and cancel jobs with ``scancel [jobID]``.
-
-It's not recommended to debug compute-intensive tasks on the login nodes. Instead, start
-a bash session on a Knights Landing node for thirty minutes with::
-
-    srun --pty -A [username OR project] -p knl -t 00:30:00 /bin/bash
-
-.. note::
-    You will need to re-activate your conda virtual environment and reload your
-    modules! Configuring this routine to occur automatically is recommended.
+View the status of your submitted jobs with ``squeue`` and cancel jobs with
+``scancel [jobID]``.
 
 
 Additional Information
@@ -130,7 +123,6 @@ See the LCRC Bebop docs here_ for more information about Bebop.
 
 
 .. _Bebop: https://www.lcrc.anl.gov/systems/resources/bebop/
-.. _LCRC: https://www.lcrc.anl.gov
 .. _Anaconda: https://www.anaconda.com/distribution/
 .. _Conda: https://conda.io/en/latest/
 .. _mpi4py: https://mpi4py.readthedocs.io/en/stable/
diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst
new file mode 100644
index 000000000..28861c59e
--- /dev/null
+++ b/docs/platforms/platforms_index.rst
@@ -0,0 +1,50 @@
+
+libEnsemble has been largely developed, supported, and tested on Linux
+distributions and macOS. Although libEnsemble and most user functions are
+cross-platform compatible, there are platform-specific differences
+for installing and configuring libEnsemble.
+
+Personal Machines
+=================
+
+Users interested in installing and running libEnsemble on their personal machines
+are encouraged to read the Quickstart guide :doc:`here<../quickstart>`.
+
+
+High-Powered Computing Machines
+===============================
+
+libEnsemble's worker processes can scale collections of computations across
+small and large resource sets. When running at massive resource scales
+on High-Powered Computing (HPC) machines, libEnsemble workers can
+be distributed much more flexibly.
+
+libEnsemble's architecture lends it best to two general modes of worker
+distributions across allocated compute nodes. The first mode we refer
+to as *centralized* mode, where the libEnsemble manager and worker processes
+all co-exist on a single node, but through the libEnsemble job controller or a
+job-launch command can execute calculations on the other allocated nodes.
+
+.. image:: ../images/centralized_Bb.png
+    :alt: centralized
+
+
+
+Alternatively, in *distributed* mode, each worker process runs independently of
+other workers directly on one or more allocated nodes.
+
+.. image:: ../images/distributed_Bb.png
+    :alt: distributed
+
+
+.. note::
+
+    Certain machines (like Theta and Summit) do not support distributed mode
+
+
+.. toctree::
+    :maxdepth: 2
+    :titlesonly:
+
+    bebop
+    theta
diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index c87fd2280..91dfd3e58 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -2,24 +2,15 @@
 Theta
 =====
 
-Theta_ is a 11.69 petaflops system based on the second-generation Intel Xeon Phi
-processor, available within ALCF_ at Argonne National Laboratory.
+Theta_ is a 11.69 petaflops Cray XC40 system based on the second-generation Intel
+Xeon Phi processor, available within ALCF_ at Argonne National Laboratory.
 
+On Theta, libEnsemble users will mostly interact with login, Machine Oriented
+Mini-server (MOM) and compute nodes. MOM nodes execute user batch-scripts to run
+on the compute nodes.
 
-Before Getting Started
-----------------------
-
-An Argonne ALCF account is required to access Theta. Interested users will need
-to apply for and be granted an account before continuing. To submit jobs to Theta,
-users must charge their jobs to a project (specified while requesting an
-account).
-
-Theta contains numerous node-types, but libEnsemble users will mostly interact
-with login, Machine Oriented Mini-server (MOM) and compute nodes. MOM nodes execute
-user batch-scripts to run on the compute nodes.
-
-libEnsemble functions need to incorporate the libEnsemble
-:ref:`job controller<jobcontroller_index>` to perform calculations on Theta.
+It is recommended that libEnsemble functions incorporate the libEnsemble
+:ref:`job controller<jobcontroller_index>` for performing calculations on Theta.
 
 
 Configuring Python

From 6bb9c33c6219106ae81fa9d62cd3b412597960af Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 6 Nov 2019 12:05:42 -0600
Subject: [PATCH 431/644] Adds job script example page, adjusts formatting and
 diagram size, clarifies information throughout

---
 docs/examples/gen_funcs.rst        |  4 +-
 docs/platforms/bebop.rst           |  4 +-
 docs/platforms/example_scripts.rst | 33 +++++++++++++++
 docs/platforms/platforms_index.rst | 44 +++++++++++--------
 docs/platforms/theta.rst           | 68 +++++++++++++++++-------------
 5 files changed, 102 insertions(+), 51 deletions(-)
 create mode 100644 docs/platforms/example_scripts.rst

diff --git a/docs/examples/gen_funcs.rst b/docs/examples/gen_funcs.rst
index 5c3fd2495..660b1b583 100644
--- a/docs/examples/gen_funcs.rst
+++ b/docs/examples/gen_funcs.rst
@@ -7,13 +7,13 @@ Below are example generation functions available in libEnsemble.
   See the API for generation functions :ref:`here<api_gen_f>`
 
 sampling
-----------------
+--------
 .. automodule:: sampling
   :members:
   :undoc-members:
 
 APOSMM
-------------
+------
 .. automodule:: aposmm
   :members:
   :undoc-members:
diff --git a/docs/platforms/bebop.rst b/docs/platforms/bebop.rst
index 6c419ba87..8922c30a0 100644
--- a/docs/platforms/bebop.rst
+++ b/docs/platforms/bebop.rst
@@ -2,8 +2,8 @@
 Bebop
 =====
 
-Bebop_ is a Cray CS400 cluster available within LCRC at Argonne National Laboratory,
-featuring both Intel Broadwell and Knights Landing compute nodes.
+Bebop_ is a Cray CS400 cluster available within LCRC at Argonne National
+Laboratory, featuring both Intel Broadwell and Knights Landing compute nodes.
 
 
 Configuring Python
diff --git a/docs/platforms/example_scripts.rst b/docs/platforms/example_scripts.rst
new file mode 100644
index 000000000..9300b8abc
--- /dev/null
+++ b/docs/platforms/example_scripts.rst
@@ -0,0 +1,33 @@
+Example Job Submission Scripts
+==============================
+
+Below are some example job-submission scripts used to configure and launch libEnsemble
+on a variety of high-powered systems. See :doc:`here<platforms_index>` for more
+information about the respective systems and configuration.
+
+Bebop - Central Mode
+--------------------
+
+..  literalinclude:: ../../examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
+    :language: bash
+
+
+Bebop - Distributed Mode
+------------------------
+
+..  literalinclude:: ../../examples/job_submission_scripts/bebop_submit_slurm.sh
+    :language: bash
+
+
+Blues
+-----
+
+..  literalinclude:: ../../examples/job_submission_scripts/blues_script.pbs
+    :language: bash
+
+
+Theta - Central Mode with Balsam
+--------------------------------
+
+..  literalinclude:: ../../examples/job_submission_scripts/theta_submit_balsam.sh
+    :language: bash
diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst
index 28861c59e..22a8e5380 100644
--- a/docs/platforms/platforms_index.rst
+++ b/docs/platforms/platforms_index.rst
@@ -1,46 +1,52 @@
 
 libEnsemble has been largely developed, supported, and tested on Linux
-distributions and macOS. Although libEnsemble and most user functions are
-cross-platform compatible, there are platform-specific differences
-for installing and configuring libEnsemble.
+distributions and macOS, from single-nodes to hundreds. Although libEnsemble
+and most user functions are cross-platform compatible, there are platform-specific
+differences for installing and configuring libEnsemble.
 
-Personal Machines
-=================
+Local
+=====
 
 Users interested in installing and running libEnsemble on their personal machines
 are encouraged to read the Quickstart guide :doc:`here<../quickstart>`.
 
 
-High-Powered Computing Machines
-===============================
+High-Powered Systems
+====================
 
-libEnsemble's worker processes can scale collections of computations across
-small and large resource sets. When running at massive resource scales
-on High-Powered Computing (HPC) machines, libEnsemble workers can
-be distributed much more flexibly.
-
-libEnsemble's architecture lends it best to two general modes of worker
+libEnsemble's flexible architecture lends it best to two general modes of worker
 distributions across allocated compute nodes. The first mode we refer
 to as *centralized* mode, where the libEnsemble manager and worker processes
-all co-exist on a single node, but through the libEnsemble job controller or a
-job-launch command can execute calculations on the other allocated nodes.
+are grouped on one or more nodes, but through the libEnsemble job-controller or a
+job-launch command can execute calculations on the other allocated nodes:
 
 .. image:: ../images/centralized_Bb.png
     :alt: centralized
+    :scale: 75
+    :align: center
 
 
 
 Alternatively, in *distributed* mode, each worker process runs independently of
-other workers directly on one or more allocated nodes.
+other workers directly on one or more allocated nodes:
 
 .. image:: ../images/distributed_Bb.png
     :alt: distributed
+    :scale: 75
+    :align: center
 
 
 .. note::
 
-    Certain machines (like Theta and Summit) do not support distributed mode
+    Certain machines (like Theta and Summit) that do not support child-process
+    launches also do not support libEnsemble in distributed mode.
+
+Due to this factor, Theta and Summit approach centralized mode differently.
+On these machines, libEnsemble is run centralized on either a compute-node with
+the support of Balsam_ or on a frontend server called a MOM
+(Machine-Oriented Mini-server) node.
 
+Read more about configuring and launching libEnsemble on some HPC machines:
 
 .. toctree::
     :maxdepth: 2
@@ -48,3 +54,7 @@ other workers directly on one or more allocated nodes.
 
     bebop
     theta
+    example_scripts
+
+
+.. _Balsam: https://balsam.readthedocs.io/en/latest/
diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index 91dfd3e58..f884d9451 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -5,12 +5,8 @@ Theta
 Theta_ is a 11.69 petaflops Cray XC40 system based on the second-generation Intel
 Xeon Phi processor, available within ALCF_ at Argonne National Laboratory.
 
-On Theta, libEnsemble users will mostly interact with login, Machine Oriented
-Mini-server (MOM) and compute nodes. MOM nodes execute user batch-scripts to run
-on the compute nodes.
-
-It is recommended that libEnsemble functions incorporate the libEnsemble
-:ref:`job controller<jobcontroller_index>` for performing calculations on Theta.
+Theta features three tiers of nodes: login, MOM (Machine-Oriented Mini-server),
+and compute nodes. MOM nodes execute user batch-scripts to run on the compute nodes.
 
 
 Configuring Python
@@ -47,22 +43,32 @@ following block:
     (my_env) user@thetalogin6:~$ CC=mpiicc MPICC=mpiicc pip install mpi4py --no-binary mpi4py
     (my_env) user@thetalogin6:~$ pip install libensemble
 
+.. note::
+    If you encounter pip errors, run ``python -m pip install --upgrade pip`` first
+
 
-Balsam
-^^^^^^
+Balsam (Optional)
+^^^^^^^^^^^^^^^^^
 
 Balsam_ is an ALCF Python utility for coordinating and executing workflows of
-computations on systems like Theta. Balsam can stage in tasks from many sources,
-including libEnsemble's job controller, and submit these tasks dynamically to the
-compute nodes. If running with MPI, Balsam is necessary to launch libEnsemble on
-Theta.
+computations on systems like Theta. Balsam can stage in tasks to a database hosted
+on a MOM node and submit these tasks dynamically to the compute nodes. libEnsemble
+can also be submitted to Balsam for centralized execution on a compute-node. At
+this point, libEnsemble can then submit tasks to Balsam through libEnsemble's
+Balsam job-controller for execution on additional allocated nodes:
+
+.. image:: ../images/centralized_Balsam_ThS.png
+    :alt: central_Balsam
+    :scale: 75
+    :align: center
+
 
 Load the Balsam module with::
 
     $ module load balsam/0.3.5.1
 
-Balsam stages tasks in and out from a database. Initialize a new database similarly
-to thefollowing:
+
+Initialize a new database similarly to the following (from the Balsam docs):
 
 .. code-block:: bash
 
@@ -73,21 +79,26 @@ to thefollowing:
     $ balsam submit-launch -A [project] -q default -t 5 -n 1 --job-mode=mpi
     $ watch balsam ls   #  follow status in realtime from command-line
 
-See **Additional Information** for the Balsam docs.
+
+See **Additional Information** for Balsam's documentation.
 
 Job Submission
 --------------
 
-Theta uses Cobalt_ for job submission and management. For libEnsemble, the most
-important command is ``qsub``, for submitting batch scripts from the login nodes.
+Theta uses Cobalt_ for job management and submission. For libEnsemble, the most
+important command is ``qsub``, for submitting batch scripts from the login nodes
+to execute on the MOM nodes.
 
-On Theta, libEnsemble is commonly configured to run in one of two ways:
+On Theta, libEnsemble's communications are commonly configured to run in one of two ways:
 
-    1. Multiprocessing mode, with libEnsemble's MPI job controller taking
-    responsibility for direct submissions of jobs to compute nodes.
+    1. **Multiprocessing mode**, where libEnsemble's MPI job-controller takes
+    responsibility for direct submissions of jobs to compute nodes. In this mode,
+    libEnsemble itself, including all manager and worker processes, runs on the
+    MOM nodes.
 
-    2. MPI mode, with libEnsemble's Balsam job controller interfacing with a Balsam
-    backend for dynamic job submission.
+    2. **MPI mode**, with libEnsemble's Balsam job-controller interfacing with the
+    previously-mentioned Balsam backend for dynamic task submission. In this mode
+    libEnsemble has been submitted to Balsam and tasked to a compute-node.
 
 Theta features one default production queue, ``default``, and two debug queues,
 ``debug-cache-quad`` and ``debug-flat-quad``.
@@ -108,8 +119,9 @@ This will place the user on a MOM node. If running in multiprocessing mode, laun
 jobs to the compute nodes is as simple as ``python calling_script.py``
 
 .. note::
-    You will need to re-activate your conda virtual environment and reload your
-    modules! Configuring this routine to occur automatically is recommended.
+    You will need to re-activate your conda virtual environment, re-activate your
+    Balsam database (if using Balsam), and reload your modules! Configuring this
+    routine to occur automatically is recommended.
 
 Batch Runs
 ^^^^^^^^^^
@@ -247,12 +259,8 @@ Debugging Strategies
 
 View the status of your submitted jobs with ``qstat -fu [user]``.
 
-It's not recommended to debug compute-intensive tasks on the login or MOM nodes,
-and if running in MPI mode, may be impossible. Allocate nodes on the debug queues
-for the best results.
-
-Each of the two debug queues has sixteen nodes apiece. A user can use up to
-eight nodes at a time for a maximum of one hour. Allocate nodes on the debug
+Theta features two debug queues with sixteen nodes apiece. Each user can allocate
+up to eight nodes at once for a maximum of one hour. Allocate nodes on a debug
 queue interactively::
 
     $ qsub -A [project] -n 4 -q debug-flat-quad -t 60 -I

From 692eda8e6f656a1914441c6b4f4499065ef03a14 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 6 Nov 2019 14:41:59 -0600
Subject: [PATCH 432/644] adjustments

---
 docs/platforms/bebop.rst           | 2 +-
 docs/platforms/platforms_index.rst | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/platforms/bebop.rst b/docs/platforms/bebop.rst
index 8922c30a0..c2ae554f8 100644
--- a/docs/platforms/bebop.rst
+++ b/docs/platforms/bebop.rst
@@ -113,7 +113,7 @@ Debugging Strategies
 --------------------
 
 View the status of your submitted jobs with ``squeue`` and cancel jobs with
-``scancel [jobID]``.
+``scancel [Job ID]``.
 
 
 Additional Information
diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst
index 22a8e5380..9092a9110 100644
--- a/docs/platforms/platforms_index.rst
+++ b/docs/platforms/platforms_index.rst
@@ -1,8 +1,8 @@
 
 libEnsemble has been largely developed, supported, and tested on Linux
-distributions and macOS, from single-nodes to hundreds. Although libEnsemble
-and most user functions are cross-platform compatible, there are platform-specific
-differences for installing and configuring libEnsemble.
+distributions and macOS, from laptops to hundreds of compute-nodes. Although
+libEnsemble and most user functions are cross-platform compatible, there are
+platform-specific differences for installing and configuring libEnsemble.
 
 Local
 =====

From 051ebd496109380bfede49ffb5ca6ccd8da13802 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 6 Nov 2019 15:31:07 -0600
Subject: [PATCH 433/644] user_specs changes

---
 docs/tutorials/local_sine_tutorial.rst | 34 +++++++++++++++++---------
 1 file changed, 22 insertions(+), 12 deletions(-)

diff --git a/docs/tutorials/local_sine_tutorial.rst b/docs/tutorials/local_sine_tutorial.rst
index ff9a7b8ce..186e2b2bc 100644
--- a/docs/tutorials/local_sine_tutorial.rst
+++ b/docs/tutorials/local_sine_tutorial.rst
@@ -20,8 +20,8 @@ launching and controlling user-applications with a :ref:`job controller<jobcontr
 Finally, workers pass results back to the manager.
 
 For this tutorial, we'll write our ``gen_f`` and ``sim_f`` entirely in Python without
-other applications. our ``gen_f`` will produce uniform randomly-sampled
-values, and our ``sim_f`` will find the sine of each. By default we don't need to
+other applications. Our ``gen_f`` will produce uniform randomly-sampled
+values, and our ``sim_f`` will calculate the sine of each. By default we don't need to
 write a new allocation function. All generated and simulated values alongside other
 parameters are stored in :ref:`H<datastruct-history-array>`, the History array.
 
@@ -30,7 +30,8 @@ parameters are stored in :ref:`H<datastruct-history-array>`, the History array.
 Getting started
 ---------------
 
-libEnsemble and it's functions are written entirely in Python_. Let's make sure Python 3 is installed.
+libEnsemble and it's functions are written entirely in Python_. Let's make sure
+Python 3 is installed.
 
 Note: If you have a Python version-specific virtual environment set up (e.g. Conda),
 then ``python`` and ``pip`` will work in place of ``python3`` and ``pip3``.
@@ -75,9 +76,11 @@ An available libEnsemble worker will call this generator function with the follo
   information. In our case this dictionary contains mechanisms called random
   streams for generating random numbers.
 
-* :ref:`gen_specs<datastruct-gen-specs>`: Dictionary with ``gen_f``
-  specifications like simulation IDs, inputs and outputs, data-types, and other
-  fields.
+* :ref:`gen_specs<datastruct-gen-specs>`: Dictionary with user-defined and
+  operational parameters for the ``gen_f``. The user places function-specific
+  parameters like boundaries and batch-sizes within the nested ``user`` dictionary,
+  while parameters that libEnsemble depends on to operate the ``gen_f`` are placed
+  outside ``user``.
 
 Later on, we'll populate ``gen_specs`` and ``persis_info`` in our calling script.
 
@@ -92,13 +95,16 @@ For now, create a new Python file named ``generator.py``. Write the following:
     def gen_random_sample(H, persis_info, gen_specs, _):
         # underscore parameter for internal/testing arguments
 
+        # Pull out user parameters to perform calculations
+        user_specs = gen_specs['user']
+
         # Get lower and upper bounds from gen_specs
-        lower = gen_specs['lower']
-        upper = gen_specs['upper']
+        lower = user_specs['lower']
+        upper = user_specs['upper']
 
         # Determine how many values to generate
         num = len(lower)
-        batch_size = gen_specs['gen_batch_size']
+        batch_size = user_specs['gen_batch_size']
 
         # Create array of 'batch_size' zeros
         out = np.zeros(batch_size, dtype=gen_specs['out'])
@@ -185,9 +191,13 @@ inputs and outputs from those functions to expect.
 
     gen_specs = {'gen_f': gen_random_sample,   # Our generator function
                  'out': [('x', float, (1,))],  # gen_f output (name, type, size)
-                 'lower': np.array([-3]),      # lower boundary for random sampling
-                 'upper': np.array([3]),       # upper boundary for random sampling
-                 'gen_batch_size': 5}          # number of x's gen_f generates per call
+                 'user': {
+                    'lower': np.array([-3]),   # lower boundary for random sampling
+                    'upper': np.array([3]),    # upper boundary for random sampling
+                    'gen_batch_size': 5        # number of x's gen_f generates per call
+                    }
+                 }
+
 
     sim_specs = {'sim_f': sim_find_sine,       # Our simulator function
                  'in': ['x'],                  # Input field names. 'x' from gen_f output

From 63b60ea1992384b8e1a4df059d720662226ceb5b Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 6 Nov 2019 15:35:26 -0600
Subject: [PATCH 434/644] Reverting to one toctree

---
 docs/index.rst | 132 ++++++++++++++++++++++++-------------------------
 1 file changed, 65 insertions(+), 67 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index ffeed0f44..a6fcab64a 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -36,73 +36,71 @@ libEnsemble is a library for managing ensemble-like collections of computations.
 * Go in-depth by reading the :doc:`User Guide<user_guide>`.
 * Check the :doc:`FAQ<FAQ>` for common questions and answers, errors and resolutions.
 
-.. only:: (latex or latexpdf)
-
-  .. toctree::
-     :maxdepth: 2
-
-     Quickstart<quickstart>
-     user_guide
-     tutorials/local_sine_tutorial
-     platforms/bebop
-     platforms/theta
-     contributing
-     FAQ
-     libE_module
-     data_structures/data_structures
-     user_funcs
-     job_controller/jc_index
-     logging
-     dev_guide/release_management/release_index.rst
-     dev_guide/dev_API/developer_API.rst
-     release_notes
-
-
-.. only:: html
-
-  .. toctree::
-     :maxdepth: 2
-     :caption: Getting Started:
-
-     Quickstart<quickstart>
-     contributing
-     release_notes
-     FAQ
-
-
-  .. toctree::
-     :maxdepth: 1
-     :caption: Tutorials:
-
-     tutorials/local_sine_tutorial
-
-
-  .. toctree::
-     :maxdepth: 1
-     :caption: Running on:
-
-     platforms/bebop
-     platforms/theta
-
-
-  .. toctree::
-     :maxdepth: 2
-     :caption: User Guide:
-
-     user_guide
-     libE_module
-     data_structures/data_structures
-     user_funcs
-     job_controller/jc_index
-     logging
-
-
-  .. toctree::
-     :maxdepth: 2
-     :caption: Developer Guide:
-
-     dev_guide/release_management/release_index.rst
-     dev_guide/dev_API/developer_API.rst
+.. .. only:: (latex or latexpdf)
+.. 
+..   .. toctree::
+..      :maxdepth: 2
+.. 
+..      Quickstart<quickstart>
+..      user_guide
+..      tutorials/local_sine_tutorial
+..      platforms/bebop
+..      platforms/theta
+..      contributing
+..      FAQ
+..      libE_module
+..      data_structures/data_structures
+..      user_funcs
+..      job_controller/jc_index
+..      logging
+..      dev_guide/release_management/release_index.rst
+..      dev_guide/dev_API/developer_API.rst
+..      release_notes
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting Started:
+
+   Quickstart<quickstart>
+   contributing
+   release_notes
+   FAQ
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Tutorials:
+
+   tutorials/local_sine_tutorial
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Running on:
+
+   platforms/bebop
+   platforms/theta
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User Guide:
+
+   user_guide
+   libE_module
+   data_structures/data_structures
+   user_funcs
+   job_controller/jc_index
+   logging
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Developer Guide:
+
+   dev_guide/release_management/release_index.rst
+   dev_guide/dev_API/developer_API.rst
 
 
 

From e71dd824e8c43792620cb1e41b72ffd723a16b4e Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 7 Nov 2019 06:06:48 -0600
Subject: [PATCH 435/644] Splitting html and latex toctrees

---
 docs/conf.py         |  9 ++++++---
 docs/index.rst       | 22 ----------------------
 docs/latex_index.rst | 45 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 51 insertions(+), 25 deletions(-)
 create mode 100644 docs/latex_index.rst

diff --git a/docs/conf.py b/docs/conf.py
index 7ef1e3929..00aaf27d3 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -87,6 +87,9 @@ def __getattr__(cls, name):
 # The master toctree document.
 master_doc = 'index'
 
+# The latex toctree document.
+latex_doc = 'latex_index'
+
 # General information about the project.
 project = 'libEnsemble'
 copyright = '2019, Jeffrey Larson'
@@ -205,7 +208,7 @@ def __getattr__(cls, name):
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'libEnsemble.tex', 'libEnsemble User Manual',
+    (latex_doc, 'libEnsemble.tex', 'libEnsemble User Manual',
      'Stephen Hudson, Jeffrey Larson, Stefan M. Wild, \\\\ \\hfill David Bindel, John-Luke Navarro', 'manual'),
 ]
 
@@ -216,7 +219,7 @@ def __getattr__(cls, name):
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'libEnsemble', 'libEnsemble User Manual',
+    (latex_doc, 'libEnsemble', 'libEnsemble User Manual',
      [author], 1)
 ]
 
@@ -227,7 +230,7 @@ def __getattr__(cls, name):
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'libEnsemble', 'libEnsemble User Manual',
+    (latex_doc, 'libEnsemble', 'libEnsemble User Manual',
      author, 'libEnsemble', 'One line description of project.',
      'Miscellaneous'),
 ]
diff --git a/docs/index.rst b/docs/index.rst
index a6fcab64a..9d5246845 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -36,28 +36,6 @@ libEnsemble is a library for managing ensemble-like collections of computations.
 * Go in-depth by reading the :doc:`User Guide<user_guide>`.
 * Check the :doc:`FAQ<FAQ>` for common questions and answers, errors and resolutions.
 
-.. .. only:: (latex or latexpdf)
-.. 
-..   .. toctree::
-..      :maxdepth: 2
-.. 
-..      Quickstart<quickstart>
-..      user_guide
-..      tutorials/local_sine_tutorial
-..      platforms/bebop
-..      platforms/theta
-..      contributing
-..      FAQ
-..      libE_module
-..      data_structures/data_structures
-..      user_funcs
-..      job_controller/jc_index
-..      logging
-..      dev_guide/release_management/release_index.rst
-..      dev_guide/dev_API/developer_API.rst
-..      release_notes
-
-
 .. toctree::
    :maxdepth: 2
    :caption: Getting Started:
diff --git a/docs/latex_index.rst b/docs/latex_index.rst
new file mode 100644
index 000000000..59f78a832
--- /dev/null
+++ b/docs/latex_index.rst
@@ -0,0 +1,45 @@
+.. libEnsemble documentation master file for the latex build
+
+.. image:: images/libE_logo.png
+ :alt: libEnsemble
+
+
+=======================================
+Welcome to libEnsemble's documentation!
+=======================================
+
+libEnsemble is a library for managing ensemble-like collections of computations.
+
+
+* New to libEnsemble? Start :doc:`here<quickstart>`.
+* Try out libEnsemble with a :doc:`tutorial<tutorials/local_sine_tutorial>`.
+* Go in-depth by reading the :doc:`User Guide<user_guide>`.
+* Check the :doc:`FAQ<FAQ>` for common questions and answers, errors and resolutions.
+
+
+.. toctree::
+   :maxdepth: 2
+
+   Quickstart<quickstart>
+   user_guide
+   tutorials/local_sine_tutorial
+   platforms/bebop
+   platforms/theta
+   contributing
+   FAQ
+   libE_module
+   data_structures/data_structures
+   user_funcs
+   job_controller/jc_index
+   logging
+   dev_guide/release_management/release_index.rst
+   dev_guide/dev_API/developer_API.rst
+   release_notes
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

From b83f3855e47b201d57881ee112f2cda713b48fd6 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 7 Nov 2019 07:09:22 -0600
Subject: [PATCH 436/644] Moving duplicate welcome to welcome.rst

---
 docs/index.rst       | 39 ++++++++++-----------------------------
 docs/latex_index.rst | 18 +-----------------
 docs/welcome.rst     | 32 ++++++++++++++++++++++++++++++++
 3 files changed, 43 insertions(+), 46 deletions(-)
 create mode 100644 docs/welcome.rst

diff --git a/docs/index.rst b/docs/index.rst
index 9d5246845..9a95c8ee3 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -5,36 +5,20 @@
 .. image:: images/libE_logo.png
  :alt: libEnsemble
 
+.. image:: https://img.shields.io/pypi/v/libensemble.svg?color=blue
+  :target: https://pypi.org/project/libensemble
 
-.. only::html
-  |
+.. image::  https://travis-ci.org/Libensemble/libensemble.svg?branch=master
+  :target: https://travis-ci.org/Libensemble/libensemble
 
-  .. image:: https://img.shields.io/pypi/v/libensemble.svg?color=blue
-    :target: https://pypi.org/project/libensemble
+.. image:: https://coveralls.io/repos/github/Libensemble/libensemble/badge/?maxAge=2592000/?branch=master
+  :target: https://coveralls.io/github/Libensemble/libensemble?branch=master
 
-  .. image::  https://travis-ci.org/Libensemble/libensemble.svg?branch=master
-    :target: https://travis-ci.org/Libensemble/libensemble
+.. image::  https://readthedocs.org/projects/libensemble/badge/?maxAge=2592000
+  :target: https://libensemble.readthedocs.org/en/latest/
+  :alt: Documentation Status
 
-  .. image:: https://coveralls.io/repos/github/Libensemble/libensemble/badge/?maxAge=2592000/?branch=master
-    :target: https://coveralls.io/github/Libensemble/libensemble?branch=master
-
-  .. image::  https://readthedocs.org/projects/libensemble/badge/?maxAge=2592000
-    :target: https://libensemble.readthedocs.org/en/latest/
-    :alt: Documentation Status
-
-  |
-
-=======================================
-Welcome to libEnsemble's documentation!
-=======================================
-
-libEnsemble is a library for managing ensemble-like collections of computations.
-
-
-* New to libEnsemble? Start :doc:`here<quickstart>`.
-* Try out libEnsemble with a :doc:`tutorial<tutorials/local_sine_tutorial>`.
-* Go in-depth by reading the :doc:`User Guide<user_guide>`.
-* Check the :doc:`FAQ<FAQ>` for common questions and answers, errors and resolutions.
+.. include:: welcome.rst
 
 .. toctree::
    :maxdepth: 2
@@ -81,11 +65,8 @@ libEnsemble is a library for managing ensemble-like collections of computations.
    dev_guide/dev_API/developer_API.rst
 
 
-
-
 Indices and tables
 ==================
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
diff --git a/docs/latex_index.rst b/docs/latex_index.rst
index 59f78a832..7c801667a 100644
--- a/docs/latex_index.rst
+++ b/docs/latex_index.rst
@@ -1,21 +1,6 @@
 .. libEnsemble documentation master file for the latex build
 
-.. image:: images/libE_logo.png
- :alt: libEnsemble
-
-
-=======================================
-Welcome to libEnsemble's documentation!
-=======================================
-
-libEnsemble is a library for managing ensemble-like collections of computations.
-
-
-* New to libEnsemble? Start :doc:`here<quickstart>`.
-* Try out libEnsemble with a :doc:`tutorial<tutorials/local_sine_tutorial>`.
-* Go in-depth by reading the :doc:`User Guide<user_guide>`.
-* Check the :doc:`FAQ<FAQ>` for common questions and answers, errors and resolutions.
-
+.. include:: welcome.rst
 
 .. toctree::
    :maxdepth: 2
@@ -42,4 +27,3 @@ Indices and tables
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
diff --git a/docs/welcome.rst b/docs/welcome.rst
new file mode 100644
index 000000000..dab1afb1c
--- /dev/null
+++ b/docs/welcome.rst
@@ -0,0 +1,32 @@
+.. image:: images/libE_logo.png
+ :alt: libEnsemble
+
+.. only::html
+  |
+
+  .. image:: https://img.shields.io/pypi/v/libensemble.svg?color=blue
+    :target: https://pypi.org/project/libensemble
+
+  .. image::  https://travis-ci.org/Libensemble/libensemble.svg?branch=master
+    :target: https://travis-ci.org/Libensemble/libensemble
+
+  .. image:: https://coveralls.io/repos/github/Libensemble/libensemble/badge/?maxAge=2592000/?branch=master
+    :target: https://coveralls.io/github/Libensemble/libensemble?branch=master
+
+  .. image::  https://readthedocs.org/projects/libensemble/badge/?maxAge=2592000
+    :target: https://libensemble.readthedocs.org/en/latest/
+    :alt: Documentation Status
+
+  |
+
+=======================================
+Welcome to libEnsemble's documentation!
+=======================================
+
+libEnsemble is a library for managing ensemble-like collections of computations.
+
+
+* New to libEnsemble? Start :doc:`here<quickstart>`.
+* Try out libEnsemble with a :doc:`tutorial<tutorials/local_sine_tutorial>`.
+* Go in-depth by reading the :doc:`User Guide<user_guide>`.
+* Check the :doc:`FAQ<FAQ>` for common questions and answers, errors and resolutions.

From 1abd69807beb88d9bc371a562ddfe37043aee10c Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 7 Nov 2019 07:12:05 -0600
Subject: [PATCH 437/644] Removing duplicate welcome from index.rst

---
 docs/index.rst | 15 ---------------
 1 file changed, 15 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index 9a95c8ee3..f02175da7 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -2,21 +2,6 @@
    sphinx-quickstart on Fri Aug 18 11:52:31 2017.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
-.. image:: images/libE_logo.png
- :alt: libEnsemble
-
-.. image:: https://img.shields.io/pypi/v/libensemble.svg?color=blue
-  :target: https://pypi.org/project/libensemble
-
-.. image::  https://travis-ci.org/Libensemble/libensemble.svg?branch=master
-  :target: https://travis-ci.org/Libensemble/libensemble
-
-.. image:: https://coveralls.io/repos/github/Libensemble/libensemble/badge/?maxAge=2592000/?branch=master
-  :target: https://coveralls.io/github/Libensemble/libensemble?branch=master
-
-.. image::  https://readthedocs.org/projects/libensemble/badge/?maxAge=2592000
-  :target: https://libensemble.readthedocs.org/en/latest/
-  :alt: Documentation Status
 
 .. include:: welcome.rst
 

From a58d13b1af502126dcf4cbd1258f9f7a6f50d0ca Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 7 Nov 2019 07:20:09 -0600
Subject: [PATCH 438/644] Using xSDK wording

---
 README.rst              | 2 +-
 docs/user_guide.rst     | 4 ++--
 docs/welcome.rst        | 2 +-
 libensemble/__init__.py | 2 +-
 setup.py                | 2 +-
 5 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/README.rst b/README.rst
index 297ee22c3..37ec8a6ac 100644
--- a/README.rst
+++ b/README.rst
@@ -25,7 +25,7 @@ What is libEnsemble?
 ====================
 
 libEnsemble is a Python library to coordinate the concurrent evaluation of
-ensembles of computations. Designed with flexibility in mind, libEnsemble can
+dynamic ensembles of calculations. Designed with flexibility in mind, libEnsemble can
 utilize massively parallel resources to accelerate the solution of design,
 decision, and inference problems.
 
diff --git a/docs/user_guide.rst b/docs/user_guide.rst
index 78ac30302..a9fc1b5b8 100644
--- a/docs/user_guide.rst
+++ b/docs/user_guide.rst
@@ -3,8 +3,8 @@ Introduction
 
 libEnsemble overview
 --------------------
-libEnsemble is a software library to coordinate the concurrent evaluation of
-ensembles of calculations. libEnsemble uses a manager to allocate work to
+libEnsemble is a Python library to coordinate the concurrent evaluation of
+dynamic ensembles of calculations. libEnsemble uses a manager to allocate work to
 various workers. A libEnsemble worker is the smallest indivisible unit to
 perform some calculation. The work performed by libEnsemble is governed by
 three routines:
diff --git a/docs/welcome.rst b/docs/welcome.rst
index dab1afb1c..160e69055 100644
--- a/docs/welcome.rst
+++ b/docs/welcome.rst
@@ -23,7 +23,7 @@
 Welcome to libEnsemble's documentation!
 =======================================
 
-libEnsemble is a library for managing ensemble-like collections of computations.
+libEnsemble is a library to coordinate the concurrent evaluation of dynamic ensembles of calculations.
 
 
 * New to libEnsemble? Start :doc:`here<quickstart>`.
diff --git a/libensemble/__init__.py b/libensemble/__init__.py
index 1b5ad41a3..c4a9bdf34 100644
--- a/libensemble/__init__.py
+++ b/libensemble/__init__.py
@@ -1,7 +1,7 @@
 """
 libEnsemble.
 
-Library for managing ensemble-like collections of computations.
+Library to coordinate the concurrent evaluation of dynamic ensembles of calculations.
 """
 
 __version__ = "0.5.2"
diff --git a/setup.py b/setup.py
index 82f74fb8d..b6439cba8 100644
--- a/setup.py
+++ b/setup.py
@@ -31,7 +31,7 @@ def run_tests(self):
 setup(
     name='libensemble',
     version='0.5.2',
-    description='Library for managing ensemble-like collections of computations',
+    description='Library to coordinate the concurrent evaluation of dynamic ensembles of calculations',
     url='https://github.com/Libensemble/libensemble',
     author='Jeffrey Larson, Stephen Hudson, Stefan M. Wild, David Bindel and John-Luke Navarro',
     author_email='libensemble@lists.mcs.anl.gov',

From fcd5db110be1b549ad613d55abc0d0d8662b506e Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 7 Nov 2019 07:27:55 -0600
Subject: [PATCH 439/644] Folding xSDK wording into README

---
 README.rst | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/README.rst b/README.rst
index 37ec8a6ac..64ed05d3b 100644
--- a/README.rst
+++ b/README.rst
@@ -25,9 +25,10 @@ What is libEnsemble?
 ====================
 
 libEnsemble is a Python library to coordinate the concurrent evaluation of
-dynamic ensembles of calculations. Designed with flexibility in mind, libEnsemble can
-utilize massively parallel resources to accelerate the solution of design,
-decision, and inference problems.
+dynamic ensembles of calculations. The library is developed to use massively
+parallel resources to accelerate the solution of design, decision, and
+inference problems and to expand the class of problems that can benefit from
+increased concurrency levels.
 
 libEnsemble aims for:
 
@@ -37,15 +38,16 @@ libEnsemble aims for:
 • Portability and flexibility
 • Exploitation of persistent data/control flow.
 
-The user selects or supplies a generation function that produces simulation
-input as well as a simulation function that performs and monitors the
-simulations. The generation function may contain, for example, an optimization
-method to generate new simulation parameters on-the-fly and based on the
-results of previous simulations.  Examples and templates of these functions are
+The user selects or supplies a function that generates simulation
+input as well as a function that performs and monitors the
+simulations. For example, the generation function may contain an
+optimization routine to generate new simulation parameters on-the-fly based on the
+results of previous simulations. Examples and templates of such functions are
 included in the library.
 
 libEnsemble employs a manager-worker scheme that can run on various
-communication media (including MPI, multiprocessing, and TCP). Each worker can
+communication media (including MPI, multiprocessing, and TCP); interfacing with
+user-provided executables is also supported. Each worker can
 control and monitor any level of work from small sub-node jobs to huge
 many-node simulations. A job controller interface is provided to ensure scripts
 are portable, resilient and flexible; it also enables automatic detection of

From c60da93611060a27196865d43a80f81d811b6f66 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 7 Nov 2019 07:30:42 -0600
Subject: [PATCH 440/644] Removing badges (which weren't working) from
 quickstart

---
 docs/quickstart.rst | 21 ---------------------
 1 file changed, 21 deletions(-)

diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index 240804990..0152356dc 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -1,23 +1,2 @@
-.. only::html
-  .. image:: images/libE_logo.png
-     :alt: libEnsemble
-
-  |
-
-  .. image:: https://img.shields.io/pypi/v/libensemble.svg?color=blue
-     :target: https://pypi.org/project/libensemble
-
-  .. image::  https://travis-ci.org/Libensemble/libensemble.svg?branch=master
-     :target: https://travis-ci.org/Libensemble/libensemble
-
-  .. image:: https://coveralls.io/repos/github/Libensemble/libensemble/badge/?maxAge=2592000/?branch=master
-     :target: https://coveralls.io/github/Libensemble/libensemble?branch=master
-
-  .. image::  https://readthedocs.org/projects/libensemble/badge/?maxAge=2592000
-     :target: https://libensemble.readthedocs.org/en/latest/
-     :alt: Documentation Status
-
-  |
-
 .. include:: ../README.rst
     :start-after: after_badges_rst_tag

From b3fb8485e89b1dea90236521c5d52fc7f897d28e Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 7 Nov 2019 07:32:08 -0600
Subject: [PATCH 441/644] Including image in quickstart

---
 docs/quickstart.rst | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index 0152356dc..a470df97f 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -1,2 +1,5 @@
+.. image:: images/libE_logo.png
+   :alt: libEnsemble
+
 .. include:: ../README.rst
     :start-after: after_badges_rst_tag

From 561e498aa42ddb43638d7c7de28ea8760851ff5d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 7 Nov 2019 07:43:14 -0600
Subject: [PATCH 442/644] Removing multiple blank lines from rst files

---
 docs/FAQ.rst                                  | 19 -------------------
 docs/data_structures/alloc_specs.rst          |  1 -
 docs/data_structures/gen_specs.rst            |  1 -
 docs/data_structures/history_array.rst        |  2 --
 docs/data_structures/sim_specs.rst            |  4 ----
 docs/data_structures/work_dict.rst            |  2 --
 docs/dev_guide/dev_API/developer_API.rst      |  1 -
 .../release_platforms/rel_pypi.rst            |  6 ------
 .../release_platforms/rel_spack.rst           |  7 -------
 .../release_management/release_process.rst    |  4 ----
 docs/examples/examples_index.rst              |  1 -
 docs/index.rst                                |  5 -----
 docs/job_controller/job_controller.rst        |  1 -
 docs/job_controller/mpi_controller.rst        |  1 -
 docs/latex_index.rst                          |  1 -
 docs/logging.rst                              |  1 -
 docs/platforms/bebop.rst                      | 12 ------------
 docs/platforms/theta.rst                      | 13 -------------
 docs/sim_gen_alloc_funcs.rst                  |  4 ----
 docs/tutorials/local_sine_tutorial.rst        |  9 ---------
 docs/user_funcs.rst                           |  1 -
 docs/user_guide.rst                           |  4 ----
 docs/welcome.rst                              |  1 -
 23 files changed, 101 deletions(-)

diff --git a/docs/FAQ.rst b/docs/FAQ.rst
index be0592545..6a9a52aa6 100644
--- a/docs/FAQ.rst
+++ b/docs/FAQ.rst
@@ -6,8 +6,6 @@ If you have any further questions, feel free to contact us through Support_
 
 .. _Support: https://libensemble.readthedocs.io/en/latest/quickstart.html#support
 
-
-
 Common Errors
 -------------
 
@@ -17,7 +15,6 @@ running with multiprocessing and multiple workers specified.**
 If your calling script code was switched from MPI to multiprocessing, make sure that
 libE_specs is populated with ``comms: local`` and ``nworkers: [num]``.
 
-
 **What does "AssertionError: Should not wait for workers when all workers are idle."
 mean?**
 
@@ -28,7 +25,6 @@ manager but no workers.
 This may also occur with two processes if you are using a persistent generator.
 The generator will occupy the one worker, leaving none to run simulation functions.
 
-
 **I keep getting: "Not enough processors per worker to honor arguments." when
 using the job controller. Can I launch jobs anyway?**
 
@@ -41,7 +37,6 @@ Automatic partitioning of resources can be disabled if you want to oversubscribe
 Note that the job_controller ``.launch()`` method has a parameter``hyperthreads``
 which will attempt to use all hyperthreads/SMT threads available if set to ``True``
 
-
 **FileExistsError: [Errno 17] File exists: './sim_worker1'**
 
 This can happen when libEnsemble tries to create sim directories that already exist,
@@ -51,7 +46,6 @@ set to ``local``.
 To create differently named sim directories, you can use the ``sim_dir_suffix``
 option in :ref:`sim_specs<datastruct-sim-specs>`.
 
-
 **PETSc and MPI errors with "[unset]: write_line error; fd=-1 buf=:cmd=abort exitcode=59"**
 
 with ``python [test with PETSc].py --comms local --nworkers 4``
@@ -66,12 +60,9 @@ build of PETSc.
     This error may depend on how multiprocessing handles an existing MPI
     communicator in a particular platform.
 
-
-
 HPC Errors and Questions
 ------------------------
 
-
 **Why does libEnsemble hang on certain systems when running with MPI?**
 
 This may occur if matching probes, which mpi4py uses by default, are not supported
@@ -86,7 +77,6 @@ Add these two lines BEFORE ``from mpi4py import MPI``::
 
 Also see https://software.intel.com/en-us/articles/python-mpi4py-on-intel-true-scale-and-omni-path-clusters
 
-
 **can't open hfi unit: -1 (err=23)**
 **[13] MPI startup(): tmi fabric is not available and fallback fabric is not enabled**
 
@@ -104,7 +94,6 @@ variables::
 Alternatively, libEnsemble can be run in central mode where all workers run on dedicated
 nodes, while launching all sub-jobs onto other nodes.
 
-
 **What does "_pickle.UnpicklingError: invalid load key, '\x00'." indicate?**
 
 This has been observed with the OFA fabric, and usually indicates MPI messages
@@ -114,8 +103,6 @@ does libEnsemble hang on certain systems when running with MPI?"
 
 For more information see: https://bitbucket.org/mpi4py/mpi4py/issues/102/unpicklingerror-on-commrecv-after-iprobe
 
-
-
 libEnsemble-theory
 ------------------
 
@@ -135,18 +122,14 @@ to ``pdb``. How well this works varies by system::
     from libensemble.util.forkpdb import ForkablePdb
     ForkablePdb().set_trace()
 
-
 .. _xQuartz: https://www.xquartz.org/
 
-
 **Can I use the MPI Job Controller when running libEnsemble with multiprocessing?**
 
 Actually, yes! The job controller type only determines how launched jobs communicate
 with libEnsemble, and is independent of ``comms`` chosen for manager-worker
 communications.
 
-
-
 macOS-specific Errors
 ---------------------
 
@@ -156,7 +139,6 @@ Resolve this by appending ``127.0.0.1   [your hostname]`` to /etc/hosts.
 Unfortunately, ``127.0.0.1   localhost`` isn't satisfactory for preventing this
 error.
 
-
 **How do I stop the Firewall Security popups when running with the Job Controller?**
 
 There are several ways to address this nuisance, but all involve trial and error.
@@ -167,7 +149,6 @@ Job Controller executable. We've had limited success running ``sudo codesign --f
 on our Job Controller executables, then confirming the next alerts for the executable
 and ``mpiexec.hydra``.
 
-
 **Frozen PETSc installation following a failed wheel build with** ``pip install petsc petsc4py``
 
 Following a failed wheel build for PETSc, the installation process may freeze when
diff --git a/docs/data_structures/alloc_specs.rst b/docs/data_structures/alloc_specs.rst
index 4131d6c83..ec942f6e7 100644
--- a/docs/data_structures/alloc_specs.rst
+++ b/docs/data_structures/alloc_specs.rst
@@ -18,7 +18,6 @@ Allocation function specifications to be set in user calling script and passed t
         'out' [list of tuples] :
             Default: [('allocated',bool)]
 
-
 .. note::
 
   * The alloc_specs has the default keys as given above, but may be overidden by the user.
diff --git a/docs/data_structures/gen_specs.rst b/docs/data_structures/gen_specs.rst
index c2cfd8c8a..cfd99adf0 100644
--- a/docs/data_structures/gen_specs.rst
+++ b/docs/data_structures/gen_specs.rst
@@ -31,7 +31,6 @@ Generation function specifications to be set in user calling script and passed t
     :ref:`sim_specs example<sim-specs-exmple1>`, where 'x' is defined in the gen_specs 'out' field to give
     two positional floats.
 
-
 .. seealso::
 
   .. _gen-specs-exmple1:
diff --git a/docs/data_structures/history_array.rst b/docs/data_structures/history_array.rst
index ab0c7a1b5..04f5955eb 100644
--- a/docs/data_structures/history_array.rst
+++ b/docs/data_structures/history_array.rst
@@ -11,8 +11,6 @@ Fields in ``H`` include those specified in ``sim_specs['out']``,
 ``gen_specs['out']``, and ``alloc_specs['out']``. All values are initiated to
 0 for integers, 0.0 for floats, and False for booleans.
 
-
-
 Below are the protected fields used in ``H``
 
 ..  literalinclude:: ../../libensemble/libE_fields.py
diff --git a/docs/data_structures/sim_specs.rst b/docs/data_structures/sim_specs.rst
index 02fca0801..0e593eea6 100644
--- a/docs/data_structures/sim_specs.rst
+++ b/docs/data_structures/sim_specs.rst
@@ -5,7 +5,6 @@ sim_specs
 
 Simulation function specifications to be set in user calling script and passed to ``libE.libE()``::
 
-
     sim_specs: [dict]:
 
         Required keys :
@@ -17,7 +16,6 @@ Simulation function specifications to be set in user calling script and passed t
         'out' [list of tuples (field name, data type, [size])] :
             sim_f outputs that will be stored in the libEnsemble history
 
-
         Optional keys :
 
         'save_every_k' [int] :
@@ -38,7 +36,6 @@ Simulation function specifications to be set in user calling script and passed t
   * The tuples defined in the ``'out'`` list are entered into the master :ref:`history array<datastruct-history-array>`
   * The ``sim_dir_prefix`` option may be used to create simulation working directories in node local/scratch storage when workers are distributed. This may have a performance benefit with I/O heavy sim funcs.
 
-
 .. seealso::
 
   .. _sim-specs-exmple1:
@@ -49,7 +46,6 @@ Simulation function specifications to be set in user calling script and passed t
       :start-at: sim_specs
       :end-before: end_sim_specs_rst_tag
 
-
   The dimensions and type of the ``'in'`` field variable ``'x'`` is specified by the corresponding
   generator ``'out'`` field ``'x'`` (see :ref:`gen_specs example<gen-specs-exmple1>`).
   Only the variable name is then required in ``sim_specs['in']``.
diff --git a/docs/data_structures/work_dict.rst b/docs/data_structures/work_dict.rst
index 2863fbd6a..14730b2e5 100644
--- a/docs/data_structures/work_dict.rst
+++ b/docs/data_structures/work_dict.rst
@@ -6,7 +6,6 @@ work dictionary
 Dictionary with integer keys ``i`` and dictionary values to be given to worker ``i``.
 ``Work[i]`` has the following form::
 
-
     Work[i]: [dict]:
 
         Required keys :
@@ -20,7 +19,6 @@ Dictionary with integer keys ``i`` and dictionary values to be given to worker `
         'blocking' [list of ints]: Workers to be blocked by this calculation
         'persistent' [bool]: True if worker 'i' will enter persistent mode
 
-
 .. seealso::
   For allocation functions giving Work dictionaries using persistent workers, see `start_only_persistent.py`_ or `start_persistent_local_opt_gens.py`_.
   For a use case where the allocation and generator functions combine to do simulation evaluations with different resources (blocking some workers), see `test_6-hump_camel_with_different_nodes_uniform_sample.py`_.
diff --git a/docs/dev_guide/dev_API/developer_API.rst b/docs/dev_guide/dev_API/developer_API.rst
index be0798b55..622ecf80c 100644
--- a/docs/dev_guide/dev_API/developer_API.rst
+++ b/docs/dev_guide/dev_API/developer_API.rst
@@ -3,7 +3,6 @@ libEnsemble Internal Modules
 
 Internal modules of libEnsemble.
 
-
 .. toctree::
    :maxdepth: 1
    :caption: Modules:
diff --git a/docs/dev_guide/release_management/release_platforms/rel_pypi.rst b/docs/dev_guide/release_management/release_platforms/rel_pypi.rst
index 98f1b6f84..b7dca74f3 100644
--- a/docs/dev_guide/release_management/release_platforms/rel_pypi.rst
+++ b/docs/dev_guide/release_management/release_platforms/rel_pypi.rst
@@ -10,28 +10,22 @@ The package is stored on PyPI in the form of a source distribution (commonly
 known as a tarball). The tarball could be obtained from GitHub, though
 historically this has been created with a checkout of libEnsemble from git.
 
-
 You will need logon credentials for the libEnsemble PyPI. You will also need
 twine (which can be pip or conda installed).
 
-
 In the package directory on the master branch (the one containing setup.py) do
 the following:
 
-
 Create distribution::
 
     python setup.py sdist
 
-
 Upload (you will need username/password here)::
 
     twine upload dist/*
 
-
 If you now do "``pip install libensemble``" it should find the new version.
 
-
 It should also be visible here:
 
 https://pypi.org/project/libensemble/
diff --git a/docs/dev_guide/release_management/release_platforms/rel_spack.rst b/docs/dev_guide/release_management/release_platforms/rel_spack.rst
index da6c73f14..c2f941461 100644
--- a/docs/dev_guide/release_management/release_platforms/rel_spack.rst
+++ b/docs/dev_guide/release_management/release_platforms/rel_spack.rst
@@ -17,13 +17,11 @@ You now have a configuration like shown in answer at: https://stackoverflow.com/
 
 Upstream, in this case, is the official Spack repository on GitHub. Origin is your fork on GitHub and Local Machine is your local clone (from your fork).
 
-
 Make sure ``SPACK_ROOT`` is set and spack binary is in your path::
 
     export SPACK_ROOT=<PATH/TO/LOCAL/SPACK/REPO>
     export PATH=$SPACK_ROOT/bin:$PATH
 
-
 DO ONCE in your local checkout:
 
 To set upstream repo::
@@ -36,7 +34,6 @@ To set upstream repo::
     git remote set-url --push upstream no_push
     git remote -v # Check for line: `upstream no_push (push)`
 
-
 Now to update (the main develop branch)
 ---------------------------------------
 
@@ -71,7 +68,6 @@ This may requires a forced push::
 
     git push origin develop --force
 
-
 Making changes
 --------------
 
@@ -81,7 +77,6 @@ you have multiple packages, to make separate branches for each package.
 See the Spack [packaging](https://spack.readthedocs.io/en/latest/packaging_guide.html) and
 [contibution](https://spack.readthedocs.io/en/latest/contribution_guide.html) guides for more info.
 
-
 Quick example to update libEnsemble::
 
     git branch update_libensemble
@@ -93,7 +88,6 @@ This will open the libEnsemble ``package.py`` file in your editor (given by env
 
 Or just open it manually: var/spack/repos/builtin/packages/py-libensemble/package.py
 
-
 Now get checksum for new lines:
 
 Get the tarball (see PyPI instructions), for the new release and use::
@@ -115,7 +109,6 @@ If OK add, commit and push to origin (forked repo)::
 Once the branch is pushed to the forked repo - go to GitHub and do a pull request from this
 branch on the fork to the develop branch on the upstream.
 
-
 Express summary: Make fork identical to upstream
 ------------------------------------------------
 
diff --git a/docs/dev_guide/release_management/release_process.rst b/docs/dev_guide/release_management/release_process.rst
index 86274e1e9..54c062e94 100644
--- a/docs/dev_guide/release_management/release_process.rst
+++ b/docs/dev_guide/release_management/release_process.rst
@@ -31,12 +31,10 @@ Before release
 
   - Documentation must build and display correctly wherever hosted (currently readthedocs.com).
 
-
 - Pull request from either develop or release branch to master requesting reviewer/s (including at least one other administrator).
 
 - Reviewer will check tests have passed and approve merge.
 
-
 During release
 --------------
 
@@ -52,10 +50,8 @@ An administrator will take the following steps.
 
   - Spack package will be updated (:ref:`Spack release<rel-spack>`).
 
-
 - If the merge was made from a release branch (instead of develop), merge this branch into develop.
 
-
 After release
 -------------
 
diff --git a/docs/examples/examples_index.rst b/docs/examples/examples_index.rst
index d4a4dd89d..10b7003fa 100644
--- a/docs/examples/examples_index.rst
+++ b/docs/examples/examples_index.rst
@@ -3,7 +3,6 @@ Example User Funcs
 
 Example gen, sim and alloc functions for libEnsemble.
 
-
 .. toctree::
    :maxdepth: 2
    :caption: libEnsemble Example Functions:
diff --git a/docs/index.rst b/docs/index.rst
index f02175da7..440dc149c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,14 +14,12 @@
    release_notes
    FAQ
 
-
 .. toctree::
    :maxdepth: 1
    :caption: Tutorials:
 
    tutorials/local_sine_tutorial
 
-
 .. toctree::
    :maxdepth: 1
    :caption: Running on:
@@ -29,7 +27,6 @@
    platforms/bebop
    platforms/theta
 
-
 .. toctree::
    :maxdepth: 2
    :caption: User Guide:
@@ -41,7 +38,6 @@
    job_controller/jc_index
    logging
 
-
 .. toctree::
    :maxdepth: 2
    :caption: Developer Guide:
@@ -49,7 +45,6 @@
    dev_guide/release_management/release_index.rst
    dev_guide/dev_API/developer_API.rst
 
-
 Indices and tables
 ==================
 
diff --git a/docs/job_controller/job_controller.rst b/docs/job_controller/job_controller.rst
index 9b0a891b0..2e6b59e50 100644
--- a/docs/job_controller/job_controller.rst
+++ b/docs/job_controller/job_controller.rst
@@ -29,7 +29,6 @@ polled/killed (or through other job or job controller functions).
 ..  :member-order: bysource
 ..  :members: poll, kill, workdir_exists, file_exists_in_workdir, read_file_in_workdir, stdout_exists, read_stdout, stderr_exists, read_stderr
 
-
 Job Attributes
 --------------
 
diff --git a/docs/job_controller/mpi_controller.rst b/docs/job_controller/mpi_controller.rst
index 559a13a57..70385d42b 100644
--- a/docs/job_controller/mpi_controller.rst
+++ b/docs/job_controller/mpi_controller.rst
@@ -19,7 +19,6 @@ See the controller API below for optional arguments.
 ..  :member-order: bysource
 ..  :members: __init__, register_calc, launch, manager_poll
 
-
 Class specific attributes
 -------------------------
 
diff --git a/docs/latex_index.rst b/docs/latex_index.rst
index 7c801667a..742e29d17 100644
--- a/docs/latex_index.rst
+++ b/docs/latex_index.rst
@@ -21,7 +21,6 @@
    dev_guide/dev_API/developer_API.rst
    release_notes
 
-
 Indices and tables
 ==================
 
diff --git a/docs/logging.rst b/docs/logging.rst
index a5bdd53b6..c0a244e10 100644
--- a/docs/logging.rst
+++ b/docs/logging.rst
@@ -24,7 +24,6 @@ This boundary can be adjusted as follows::
 
 stderr displaying can be effectively disabled by setting the stderr level to CRITICAL.
 
-
 Logging API
 -----------
 
diff --git a/docs/platforms/bebop.rst b/docs/platforms/bebop.rst
index 5ff711620..2a42413a7 100644
--- a/docs/platforms/bebop.rst
+++ b/docs/platforms/bebop.rst
@@ -5,7 +5,6 @@ Bebop
 Bebop_ is the newest addition to the computational power of LCRC at Argonne
 National Laboratory, featuring both Intel Broadwell and Knights Landing nodes.
 
-
 Before Getting Started
 ----------------------
 
@@ -16,7 +15,6 @@ users can charge hours to a project or their personal allocation (default).
 Bebop consists primarily of login and compute nodes. Users start on the login
 nodes, and schedule work for execution on the compute nodes.
 
-
 Configuring Python
 ------------------
 
@@ -31,7 +29,6 @@ dependencies::
     conda create --name my_env intelpython3_core python=3
     source activate my_env
 
-
 Installing libEnsemble and Dependencies
 ---------------------------------------
 
@@ -45,14 +42,12 @@ following block:
     (my_env) user@beboplogin4:~$ CC=mpiicc MPICC=mpiicc pip install mpi4py --no-binary mpi4py
     (my_env) user@beboplogin4:~$ pip install libensemble
 
-
 Job Submission
 --------------
 
 Bebop uses Slurm_ for job submission and management. The two commands you'll likely use the most
 to run jobs are ``srun`` and ``sbatch`` for running interactively and batch, respectively.
 
-
 Interactive Runs
 ^^^^^^^^^^^^^^^^
 
@@ -60,12 +55,10 @@ You can allocate four Knights Landing nodes for thirty minutes through the follo
 
     salloc -N 4 -p knl -A [username OR project] -t 00:30:00
 
-
 With your nodes allocated, queue your job to start with five MPI ranks::
 
     srun -n 5 python calling.py
 
-
 ``mpirun`` should also work. This launches a worker on every node, on which every
 worker can perform stand-alone calculations or launch jobs through the job controller.
 
@@ -74,7 +67,6 @@ worker can perform stand-alone calculations or launch jobs through the job contr
     more MPI process than the number of allocated nodes. The Manager and first
     worker run together on a node.
 
-
 Batch Runs
 ^^^^^^^^^^
 
@@ -101,13 +93,11 @@ for a libEnsemble use-case running on Broadwell nodes resembles the following:
 
     srun --ntasks 5 python3 calling_script.py
 
-
 With this saved as ``myscript.sh``, allocating, configuring, and running libEnsemble
 on Bebop becomes::
 
     sbatch myscript.sh
 
-
 Debugging Strategies
 --------------------
 
@@ -122,13 +112,11 @@ a bash session on a Knights Landing node for thirty minutes with::
     You will need to re-activate your conda virtual environment and reload your
     modules! Configuring this routine to occur automatically is recommended.
 
-
 Additional Information
 ----------------------
 
 See the LCRC Bebop docs here_ for more information about Bebop.
 
-
 .. _Bebop: https://www.lcrc.anl.gov/systems/resources/bebop/
 .. _LCRC: https://www.lcrc.anl.gov
 .. _Anaconda: https://www.anaconda.com/distribution/
diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index c87fd2280..d266a347f 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -5,7 +5,6 @@ Theta
 Theta_ is a 11.69 petaflops system based on the second-generation Intel Xeon Phi
 processor, available within ALCF_ at Argonne National Laboratory.
 
-
 Before Getting Started
 ----------------------
 
@@ -21,7 +20,6 @@ user batch-scripts to run on the compute nodes.
 libEnsemble functions need to incorporate the libEnsemble
 :ref:`job controller<jobcontroller_index>` to perform calculations on Theta.
 
-
 Configuring Python
 ------------------
 
@@ -38,11 +36,9 @@ dependencies::
 
 More information_ on using Conda on Theta.
 
-
 Installing libEnsemble and Dependencies
 ---------------------------------------
 
-
 libEnsemble and mpi4py
 ^^^^^^^^^^^^^^^^^^^^^^
 
@@ -56,7 +52,6 @@ following block:
     (my_env) user@thetalogin6:~$ CC=mpiicc MPICC=mpiicc pip install mpi4py --no-binary mpi4py
     (my_env) user@thetalogin6:~$ pip install libensemble
 
-
 Balsam
 ^^^^^^
 
@@ -104,7 +99,6 @@ Theta features one default production queue, ``default``, and two debug queues,
 .. note::
     For the default queue, the minimum number of nodes to allocate at once is 128
 
-
 Interactive Runs
 ^^^^^^^^^^^^^^^^
 
@@ -163,13 +157,11 @@ for a libEnsemble use-case may resemble the following:
 
     python $EXE $COMMS $NWORKERS > out.txt 2>&1
 
-
 With this saved as ``myscript.sh``, allocating, configuring, and running libEnsemble
 on Theta becomes::
 
     $ qsub --mode script myscript.sh
 
-
 Balsam Runs
 ^^^^^^^^^^^
 
@@ -219,7 +211,6 @@ for execution. This is an example Balsam submission script:
     # Activate Balsam database
     . balsamactivate default
 
-
     # Currently need at least one DB connection per worker (for postgres).
     if [[ $NUM_WORKERS -gt 128 ]]
     then
@@ -250,7 +241,6 @@ for execution. This is an example Balsam submission script:
 
 See **Additional Information** for the Balsam docs.
 
-
 Debugging Strategies
 --------------------
 
@@ -266,7 +256,6 @@ queue interactively::
 
     $ qsub -A [project] -n 4 -q debug-flat-quad -t 60 -I
 
-
 Additional Information
 ----------------------
 
@@ -274,8 +263,6 @@ See the ALCF guides_ on XC40 systems for more information about Theta.
 
 Read the documentation for Balsam here_.
 
-
-
 .. _ALCF: https://www.alcf.anl.gov/
 .. _Theta: https://www.alcf.anl.gov/theta
 .. _Balsam: https://www.alcf.anl.gov/balsam
diff --git a/docs/sim_gen_alloc_funcs.rst b/docs/sim_gen_alloc_funcs.rst
index cfcaeba66..d1f627131 100644
--- a/docs/sim_gen_alloc_funcs.rst
+++ b/docs/sim_gen_alloc_funcs.rst
@@ -25,7 +25,6 @@ Parameters:
   **libE_info**: :obj:`dict`
   :doc:`(example)<data_structures/work_dict>`
 
-
 Returns:
 ********
 
@@ -51,7 +50,6 @@ The gen_f calculations will be called by libEnsemble with the following API::
 
     out = gen_f(H[gen_specs['in']][sim_ids_from_allocf], persis_info, gen_specs, libE_info)
 
-
 Parameters:
 ***********
 
@@ -67,7 +65,6 @@ Parameters:
   **libE_info**: :obj:`dict`
   :doc:`(example)<data_structures/work_dict>`
 
-
 Returns:
 ********
 
@@ -114,7 +111,6 @@ Parameters:
   **persis_info**: :obj:`dict`
   :doc:`(example)<data_structures/persis_info>`
 
-
 Returns:
 ********
 
diff --git a/docs/tutorials/local_sine_tutorial.rst b/docs/tutorials/local_sine_tutorial.rst
index ff9a7b8ce..aa71d28af 100644
--- a/docs/tutorials/local_sine_tutorial.rst
+++ b/docs/tutorials/local_sine_tutorial.rst
@@ -88,7 +88,6 @@ For now, create a new Python file named ``generator.py``. Write the following:
 
     import numpy as np
 
-
     def gen_random_sample(H, persis_info, gen_specs, _):
         # underscore parameter for internal/testing arguments
 
@@ -109,13 +108,11 @@ For now, create a new Python file named ``generator.py``. Write the following:
         # Send back our output and persis_info
         return out, persis_info
 
-
 Our function creates 'batch_size' random numbers uniformly distributed
 between the 'lower' and 'upper' bounds. A random stream
 from ``persis_info`` is used to generate these values. Finally, the values are placed
 into a NumPy array that meets the specifications from ``gen_specs['out']``.
 
-
 Simulator function
 ------------------
 
@@ -131,7 +128,6 @@ Create a new Python file named ``simulator.py``. Write the following:
 
     import numpy as np
 
-
     def sim_find_sine(H, persis_info, sim_specs, _):
         # underscore for internal/testing arguments
 
@@ -148,7 +144,6 @@ Our simulator function is called by a worker for every value in it's batch from
 generator function. This function calculates the sine of the passed value, then returns
 it so a worker can log it into ``H``.
 
-
 Calling Script
 --------------
 
@@ -193,7 +188,6 @@ inputs and outputs from those functions to expect.
                  'in': ['x'],                  # Input field names. 'x' from gen_f output
                  'out': [('y', float)]}        # sim_f output. 'y' = sine('x')
 
-
 Recall that each worker is assigned an entry in the :ref:`persis_info<datastruct-persis-info>`
 dictionary that, in this tutorial, contains  a ``RandomState()`` random stream for
 uniform random sampling. We populate that dictionary here. Finally, we specify the
@@ -264,7 +258,6 @@ and run ``python3 calling_script.py`` again
 .. code-block:: python
   :linenos:
 
-
   import matplotlib.pyplot as plt
   colors = ['b', 'g', 'r', 'y', 'm', 'c', 'k', 'w']
 
@@ -280,10 +273,8 @@ and run ``python3 calling_script.py`` again
   plt.legend(loc = 'lower right')
   plt.show()
 
-
 ---
 
-
 Next Steps
 ----------
 
diff --git a/docs/user_funcs.rst b/docs/user_funcs.rst
index 6c8d60211..f912ed73b 100644
--- a/docs/user_funcs.rst
+++ b/docs/user_funcs.rst
@@ -6,7 +6,6 @@ libEnsemble requires functions for generation, simulation and allocation.
 While libEnsemble provides a default allocation function, the sim and gen functions
 must be provided. The required API and examples are given here.
 
-
 .. toctree::
    :maxdepth: 2
    :caption: libEnsemble User Functions:
diff --git a/docs/user_guide.rst b/docs/user_guide.rst
index a9fc1b5b8..960fc7864 100644
--- a/docs/user_guide.rst
+++ b/docs/user_guide.rst
@@ -23,7 +23,6 @@ The default ``alloc_f`` tells each available worker to call ``sim_f`` with the
 highest priority unit of work from ``gen_f``. If a worker is idle and there is
 no ``gen_f`` output to give, the worker is told to call ``gen_f``.
 
-
 Expected use cases
 ------------------
 
@@ -64,12 +63,10 @@ to support) and plan to have examples of:
   point is ruled to be an optimum, a different ``gen_f`` can produce a
   collection of parameters necessary for sensitivity analysis of ``sim_f``.
 
-
 Naturally, combinations of these use cases are supported as well. An example of
 such a combination is using libEnsemble to solve an optimization problem that
 relies on simulations that fail frequently.
 
-
 The libEnsemble History Array
 -----------------------------
 
@@ -103,7 +100,6 @@ include the following fields:
 * ``returned`` [bool]: Has this worker completed the evaluation of this unit of
   work?
 
-
 libEnsemble Output
 ------------------
 
diff --git a/docs/welcome.rst b/docs/welcome.rst
index 160e69055..4979ea952 100644
--- a/docs/welcome.rst
+++ b/docs/welcome.rst
@@ -25,7 +25,6 @@ Welcome to libEnsemble's documentation!
 
 libEnsemble is a library to coordinate the concurrent evaluation of dynamic ensembles of calculations.
 
-
 * New to libEnsemble? Start :doc:`here<quickstart>`.
 * Try out libEnsemble with a :doc:`tutorial<tutorials/local_sine_tutorial>`.
 * Go in-depth by reading the :doc:`User Guide<user_guide>`.

From 3d4ee5a78ed084665fdca5e6aa814415ee20f899 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 7 Nov 2019 07:46:40 -0600
Subject: [PATCH 443/644] Removing multiple blank lines from rst files

---
 CHANGELOG.rst                             |  9 ---------
 README.rst                                |  7 -------
 libensemble/tests/balsam_tests/readme.rst | 15 ---------------
 postproc_scripts/readme.rst               |  1 -
 4 files changed, 32 deletions(-)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 78cfc6265..9d268c86a 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -2,7 +2,6 @@
 Release Notes
 =============
 
-
 Release 0.5.2
 -------------
 
@@ -27,7 +26,6 @@ Release 0.5.2
 
 * These are unchanged from v0.5.0
 
-
 Release 0.5.1
 -------------
 
@@ -46,7 +44,6 @@ Release 0.5.1
 
 * These are unchanged from v0.5.0
 
-
 Release 0.5.0
 -------------
 
@@ -80,20 +77,17 @@ Release 0.5.0
 * Remote detection of logical cores via LSB_HOSTS (e.g., Summit) returns number of physical cores as SMT info not available.
 * TCP mode does not support: 1) more than one libEnsemble call in a given script or 2) the auto-resources option to the job controller.
 
-
 Release 0.4.1
 -------------
 
 :Date: February 20, 2019
 
-
 * Logging no longer uses root logger (Also added option to change libEnsemble log level) (#105)
 * Added wait_on_run option for job controller launch to block until jobs have started (#111)
 * persis_info can be passed to sim as well as gen functions (#112)
 * Post-processing scripts added to create performance/utilization graphs (#102)
 * New scaling test added (not part of current CI test suite) (#114)
 
-
 Release 0.4.0
 -------------
 
@@ -111,7 +105,6 @@ Release 0.4.0
 
 * OpenMPI is not supported with direct MPI launches as nested MPI launches are not supported.
 
-
 Release 0.3.0
 -------------
 
@@ -133,7 +126,6 @@ Release 0.3.0
 
 * OpenMPI is not supported with direct MPI launches as nested MPI launches are not supported.
 
-
 Release 0.2.0
 -------------
 
@@ -150,7 +142,6 @@ Release 0.2.0
 * Killing MPI jobs does not work correctly on some systems (including Cray XC40 and CS400). In these cases, libEnsemble continues, but processes remain running.
 * OpenMPI does not work correctly with direct launches (and has not been tested with Balsam).
 
-
 Release 0.1.0
 -------------
 
diff --git a/README.rst b/README.rst
index 64ed05d3b..18a6bfdef 100644
--- a/README.rst
+++ b/README.rst
@@ -58,7 +58,6 @@ A visual overview is given in the libEnsemble poster_.
 
 .. _poster:  https://figshare.com/articles/LibEnsemble_PETSc_TAO-_Sustaining_a_library_for_dynamic_ensemble-based_computations/7765454
 
-
 Dependencies
 ------------
 
@@ -75,7 +74,6 @@ For libEnsemble running with the mpi4py parallelism:
 
 * mpi4py_ v2.0.0 or above
 
-
 Optional dependency:
 
 * Balsam_
@@ -98,7 +96,6 @@ PETSc and NLopt must be built with shared libraries enabled and present in
 should produce a file nlopt.py if Python is found on the system. NLopt may also
 require SWIG_ to be installed on certain systems.
 
-
 Installation
 ------------
 
@@ -119,7 +116,6 @@ If necessary, you may install all optional dependencies (listed above) at once w
 
 A `tarball <https://github.com/Libensemble/libensemble/releases/latest>`_ of the most recent release is also available.
 
-
 Testing
 ---------
 
@@ -163,7 +159,6 @@ available online at
     on Travis CI, Balsam integration with libEnsemble is now tested via
     ``test_balsam_hworld.py``.
 
-
 Basic Usage
 -----------
 
@@ -188,12 +183,10 @@ When specifying these options via command line options, one may use the
 ``parse_args`` function used in the regression tests, which can be found in
 ``libensemble/tests/regression_tests/common.py``
 
-
 See the
 `user-guide <https://libensemble.readthedocs.io/en/latest/user_guide.html>`_
 for more information.
 
-
 Documentation
 -------------
 
diff --git a/libensemble/tests/balsam_tests/readme.rst b/libensemble/tests/balsam_tests/readme.rst
index d2d1ac3e5..b809af293 100644
--- a/libensemble/tests/balsam_tests/readme.rst
+++ b/libensemble/tests/balsam_tests/readme.rst
@@ -48,7 +48,6 @@ To quickly reset the tests to run again use the reset (python) script:
 
 The file readme.balsam_tests.txt contains a brief explanation of the tests
 
-
 -------------
 General Usage
 -------------
@@ -91,8 +90,6 @@ To clean:
 
   balsam rm apps --all
 
-
-
 2 Register job/s
 ----------------
 
@@ -115,12 +112,10 @@ A log will also be created when run under hpc-edge-service/log/
 
 The standard output will go to file <jobname>.out. So in above case this will be job_balsam1.out which will be staged out to $WORKDIR
 
-
 In this case 4 ranks per node and 1 node are selected. This is for running on the parent application (e.g., libEnsemble). This does not constrain the running of sub-apps (eg. helloworld), which will use the full allocation available.
 
 Note that the user jobs (launched in a libEnsemble job) are registered from within the code. For staging out files, the output directory needs to somehow be accessible to the code. For the tests here, this is simply the directory of the test scripts (accessed via the __file__ variable in python). Search for dag.add_job in test scripts (eg. test_balsam_1__runjobs.py)
 
-
 To list jobs:
 
 .. code-block:: bash
@@ -133,7 +128,6 @@ To clean:
 
   balsam rm jobs --all
 
-
 3 Launch job/s
 --------------
 
@@ -151,7 +145,6 @@ For other launcher options:
 
   balsam launcher -h
 
-
 4 Reset jobs
 ------------
 
@@ -159,7 +152,6 @@ A script to reset the tests is available: reset_balsam_tests.py
 
 This script can be modified easily. However, to reset from the command line - without removing and re-adding jobs you can do the following.
 
-
 Note: After running tests the balsam job database will contain something like the following (job_ids abbreviated for space):
 
 .. code-block:: bash
@@ -178,15 +170,12 @@ Note: After running tests the balsam job database will contain something like th
      183c5f01-a8df-... | outfile_for_sim_id_1_ranks3.txt | libe_workflow  | helloworld     | [01-30-2018 18:56:10 JOB_FINISHED]
     ..................
 
-
 To remove only the generated jobs you can just use a sub-string of the job name eg:
 
 .. code-block:: bash
 
   balsam rm jobs --name outfile
 
-
-
 .. code-block:: bash
 
   $ balsam ls jobs
@@ -197,17 +186,14 @@ To remove only the generated jobs you can just use a sub-string of the job name
     -----------------------------------------------------------------------------------------------------------------------
      29add031-8e7c-... | job_balsam1      | libe_workflow   | test_balsam_1    | [01-30-2018 18:57:47 JOB_FINISHED]
 
-
 To run again - change status attribute to READY (you need to specify job_id - an abbreviation is ok) eg:
 
-
 .. code-block:: bash
 
   balsam modify jobs 29ad --attr state --value READY
 
 Now you are ready to re-run.
 
-
 Theta tip - Interactive sessions
 --------------------------------
 
@@ -225,7 +211,6 @@ At time of writing theta does not log you out of interactive sessions. But jobs
 
 To see time remaining:
 
-
 .. code-block:: bash
 
   qstat -fu <username>
diff --git a/postproc_scripts/readme.rst b/postproc_scripts/readme.rst
index ec861b81c..ce160f1e8 100644
--- a/postproc_scripts/readme.rst
+++ b/postproc_scripts/readme.rst
@@ -12,7 +12,6 @@ The following scripts must be run in the directory with the **libE_stats.txt** f
 
 * **plot_libE_histogram.py**: Create histogram showing the number of completed/killed/failed user calculations binned by run-time.
 
-
 ========================
 Results analysis scripts
 ========================

From 2fb02f89e103a427e187568588d8668bcff8826f Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 7 Nov 2019 11:31:19 -0600
Subject: [PATCH 444/644] adjust centralized diagrams, add xml source

---
 docs/images/centralized_Balsam_ThS.png | Bin 57918 -> 64098 bytes
 docs/images/centralized_Balsam_ThS.xml | 136 +++++++++++++++++++++++++
 docs/images/centralized_Bb.png         | Bin 35065 -> 39907 bytes
 docs/images/centralized_Bb.xml         | 112 ++++++++++++++++++++
 docs/images/distributed_Bb.xml         |  95 +++++++++++++++++
 5 files changed, 343 insertions(+)
 create mode 100644 docs/images/centralized_Balsam_ThS.xml
 create mode 100644 docs/images/centralized_Bb.xml
 create mode 100644 docs/images/distributed_Bb.xml

diff --git a/docs/images/centralized_Balsam_ThS.png b/docs/images/centralized_Balsam_ThS.png
index f6ff9451d904ea2450a687108b54599cf88123e6..8ab646c8afc72dd2f4dd67370c3a4744133a01d7 100644
GIT binary patch
literal 64098
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
A@&Et;

literal 57918
zcmaf52UwHK(ndtEfT$={5DQ?1kkG3ELg)}$C{h9;p_fpS&_ttHkfNwG0V$$@fHdi#
zqV%qSv{<N0?;ZXPo^!6}-gE!^JcgLfep_Z|XWw~eHh1)NkSzPT_tVkQv8b!5=+n{B
z*MZm3y^NrQ3Eg{&j&8r07sABLg@ki(wxbh(DgXMP02E^H=IJE>QxSkdiA16>mVhA&
zJGg;Q;42q5tOL%$4*TnCC`45HlBnn<h`1pXCIEv&B*7n1sIW8yYWAx>25;y3M_bx%
zz7EdL7y+oNxG)4Xbygc=>)`6;=4megQv#pWUA^p_!8<4he{~JO9~1Brg$Rp^|EfXo
z0nJN7gdyiZInvJ72@Fb=Rs;MK1x2b31UsA?2^7*Q{ThIs7Y6@purP0!sFIzT3lwGG
z?B?QOW2%n^Gonq($By9X;O6?P8W=wG&xgIp?smUQv35QVwsya&yMsx2{!y7$0z&}d
zVI44d0>%Zj=J1Db(E5Z+PFO1sM{QNChL(+)p_du_R|BpXmp_`-15I55L#H(&X-x96
z755ZF=!t<6Rd>8L%FV&V5#oZ8*2TC;ni#ogOXHl}h-6J)l#!#FxT&E4R0$?2ZD62c
zXK#SeL2CG#x}sfC25u^*;?mB}UdHZ{N-ol9ZwV=V69-TiG-@O!h0qp-`C=XQ#LO@@
z1a}u3Ur;P&jCUnEpwv-lEwY}i0m2rqDh-Oo!Al?RCaQ^rNvL_b7%4ewXo4vyVSLCC
zO%r<uRTA3B1?eV6Yuwq*RvLm)k`nbbwsX=T;9;J|N+vjhmb5gU?1Xh!Cxbf1pgn{d
z_z%fYS4vw)$HkZE?TpvN;ypc$usCJ1hM2CHHVlC=^3*jZc-c7N@mLL<hlZi655WTg
za}l*ipuB9Hm2`dd>}iYaBIRl(?Pl!b1i?Ak7^xdbDMRcWq)atc2qq*4U1M*kp{NlG
zf`+*vOc2J}>Ut&wh&Rp&=P8PHGV#%rva=<Nn|Z3*I(lpPN~znp*u!b+WDk^2N!<{k
zN0!8Ss^h^2Cy1sV5@@0-0%@r4q-5esMxgDSz!&zKCL~iN_(ECFg+vA;QbJ2<sF~P$
zxjC7-7@Bw}DWg2hTn(M1;l`#|q@9X5!c{`qMcv8W9i`(e?dytA)g(fV^u<W}4q93+
zqGV+WtcSQ1&H!#`hgZjV!?m@wL7PaZj~))ZJ1eOZ#3e;-h~ka}A_}IdZ|E(d3HGRx
zsv!#I0&~$cG%`_^Fw%7(YHQo$$Tl#tkDalBv6Q-<hK9J3rX3lj4%ZiRaCURUJGwY4
z*=U&>sM{*}BAiK%(l94|LkT@~ADpA1il`ml#tbb6cOj~xZ44ZpJdL0j2pr`I=IQAT
z#h~=j((0-zCaOdih_{ce1RetOB&gvubs$=XCQ>S(k`@U<f;nnn>}lfk#Oax#bk)R+
zoF&~6o<7FT8WK{rI^YX4cXcp!Lp|_ERLN6STg<>0M}~N7pmE}&5Dir+2^)2ksD?Vh
z)z{vP02EBs-rZT;(UfeYBVnlPLc)rfVLhEC?Y&8OsJ*wgp0=2phYM5+@2o^rR+92T
zBix9__DWJ1GmM9ss)n|THjeD7=LQ4qpwUQOvW5#z(^LZK>S$;rZlo`+rKjg?L{L#h
znwg496LrBZRuvW3vBfx&)V0*y43)&4u`U>-v4;uL9d4q8uyeBq=1tYWK;Ku~$P?yd
zA`Zh4l$CJ^bw^t#N2rn`-bTk%%ot%RCIzPFYmD<oxFGHI?N!{oh~65i9vHm1laZ$y
zOy3x#Zf1wklv2is<Mcs`BtrvdjE9{TcuHTJXev!2Xy|Esn_)!V^=vVsW{xgi`g+DF
zlBxzmQ%#wK0@X}N`jTb_CVE&n(#F=)&R$*2jI3!!AgJglxjP|H>SDA#r;SG`Iid_T
zaC%O967~r2n356+VJj`6u7R~hdw?2_B!nZJY^?0ypouUN1^Vxe)3;SKmeg<*H}SGl
zL!b#rRZU$tCjv^^MazSr@1$!4o<g`l;I=BBj;=~ZC}RUXqK=uilarXHfs(!_1Z`)6
zGga5J_fax-6|)tEq8%mOO?7?6&FoOlnohbBW=;|ixG#p_fx~ILyBT}BX%bakU0v1T
zHoycRu~3|<7eX0}mNGI%!+g-1s-QbjF;jbEC)$<-ask#%$wd!sf-qAidZA4buBxhr
z1`v!SP3iE)dT4K~iMFPOmb3xZNgwBdQt}ctfFLDBb)<bHTtp?6okcyR5RTq%2&|zF
zI4M+>MYTnB-SJ|eRW}c36>UwZt(uM!5{9=U!)WT@A?jfZ!J429+}*?^Tx<xS9@2;;
zEvaQE;bEdF>4R|*1IwZ6tO^=aGBdH!cSZZ?nV?BhTAG@wSRz`@*whWKj@DMfdy0Cy
zs^A@TOuSv)@hYae21Hi}T?bJuoV1CWkG{663Q0}U!`@xX9qM9eN0YL%p{g0iQ_Drn
z(?r?V*w9B)Lkz14%BA%kT#O)2c8+M;1e{&m#c@y#I~#i?Jc(e7H#WsXbyPGpU3E!f
zhIojCnUN#X5%1vXfHL-=)mL&iHq%E+L-9Cuq?ip{!-l4R#!gVYfvXWpN>^9eRFrIn
z_Og+%(?BVsL~UH9bbxSFCDldU>=5>*u3ktVqLYq0n5`#x*<&CsX1aC=eOID~F;UV^
zm5A~504*w!4eiu4^~BJ4DP4@Wv#PQaR??B6t0ZA6p{FF~Yv=@VwU=_zmJ-uZhxtIj
zS)u8oF5!jMgLxBmoY62BI02>Pqk`5@LTl@riMi<c8cU&+-0j6+s`hR;qzcr?Q(7M<
zh0!*1a5aTG<Dfc9Di}3gTVpL}LpNJzZ8s@>Q7{NC6bwZ(>+Yf^MrzI`x?l&Wic7md
z?Uc1N9i=c*UI=ZhsSS}f5u};1w<g-e$H_$>X>Tv(Xb9Ia(nK0V2_$iGccL+oBuy|t
zIygeHM68Vg6z}2#QzscIOS{^b>Y|+Sj(VnWA0L>hk{bbOY@(`fgD}GxlWf)CM&9;l
zf`R>xVIk`gl<d7U@rFKVyqcsg(n!nB#n?&B6bwoW;$vi}VMBB<@RHUy!m5h<n5v68
zdzfOBy|5%G7@mZ!F$rp?WUNfqHLw#GLu#PJ#lW_)F>#h~7q^38MNwYHUT9lsBvQvn
z*Tz&6;%cj}FRrHM3XXCmF=Km2jJ~U}2@2=p3r-VFNoi@gqa)5&jqIhN>WmZDl9Ysl
zUR0%&0H6Wye`1;)fCE1N0T5w`ZU3XXbaec5>MC$U(vyjJzbg-owrUeArl-5}`dpRL
z4I#Urdv^~)_@nM0MyTxZVwv90JX2?fi!gI@jxH&2cxFEG`q<;x$3C<A=PdQ$<(D;L
zarQ6Gp610G#x}cF4HV9=+e%e?@?4IN8GVAU99>*1Z-~K=q(%c;mgk?0`n6y<mmi(r
z3au&A7BmQ}$C^1qW7tPWN4t+6J^E>6csL$w%6{!Kp%DuWc#@cS6{4uPZLOoz^5Dsn
zCjx?z=R_0~sNtBrK<c>>Jnx#rt-yDXrf}&s)UEQop`js_+>7f`8yg$3;KdzTzYyB*
zqM4~B_)#*t9+Vh;e6HIK)9MvDLz=jY$T%>=AV<!lb9)nq)X>q<xol}^=@1wg7~0RW
zhkg;Uy1L5b>FK!*@&5TqFSvf~L~#A;GmGMUSsCdfieD&7f;*I$e{r2-ui#WvJ$5ba
z>C>-!;&r+cF&*1Qk+rU-scCe&Zz6>b%rKUdUk;6o;5d#R^%s5_ZP)lX>5}>Dr?i*B
zbDbpG3w(>s@43w1)7jrY@%4yjsdEn$#njr`x^2_-vcHGfVB<nCmv>Y}q#ufD^kLYW
zyy91{X4tb6SLa7lSa>9)e&$tFSS-DMW;8iD8Rpyn3bQ*_@oFWd`rW&C=7Nzw&Q%0{
z+U&S^SL)1GFbj!3LC!Qt@@uoLfQX2jKL&%jkWH7_dH4K<3n*=EmdlLE#-NoKX=#i`
z#>S^IJAaOS&BwP^$_4nghy`P=Rzn0&_z9uinK+K7w38$y5sp21c4HmSH1mq0I=p{$
z2v9@g>aj9e?btogJ0Ao4>c77zn}EUO4&JFW-JK95q|5%5g*2~LUtcepchN7xkEyGz
zjo(i>=<<{v=zUt}GZxAl1O4#u?ey1`_WK4YTHc`Qop<4<IYcb)>BP$j_?403!23;h
z@Y&=sf=nh$@&!t{G1%5E+I?>btc6GuiG=9+#xNnC_t3p^^&$eZpDcD!hoaCkIA}~4
z0e{cQ(Gi<NI#kD&k)Hmo`RwS>kPAC;21WFcS!w0m(<Df|Xj5_rZ}Ig<gukPk+h|Ko
z{}U-uNu%es>#$ka=EU*5s$9jMuLCa+AHxO-5mFfvN-w<Ok=DQHrkXPATE5a^liN?t
zvpW#PI44tBRFnc1nm^<Np-&;MiH~Jp40pr()&*M|jVV-9ygTy8=g<+J$95<?yJr)N
zta+Jvc}EnRi>2+`3_~pw{i<|om+;Ibl}kcA(eS+M%rh!!_QUCA^yT-@A!fTgn0&Zf
zxvQ0ABZ@LhN_s@&X!}L@wC$38R+rr6HJxak$fo8V^ViNX6W#~EA836atwq*`m-e4T
zp>FQt)~-}!i@TZ=|Mo}KR5>bAv5rm`8zQkYmmYlvH{R76N%yIPP27~rK42EIgpB?B
z_gBVCi4!xxz!XzND#JzdHdpfNkM{37u)i@cB<V}!1>vjtxLlE7&Yrdz?9xdlim1S{
z7bDl|>h6R(b{9EsbdY2oLf(ycg!5Z18y(l)_h>)AvO$l-jd}L(hOYmh4eS2>o4aN4
zkqF{D(#`CR_<r?o3b8l#TpIfMDcxWNHC%L_H;xng>IRDhJJS!ZXRK2Dpn0#D<l0Y~
zk$z^=xq00-qsnxgcfCAyaPOyzSL(uN&#p)W*ict)-$$I^iifQ8yroxw%9KVvh>Kf4
zE*G1s4BEWMl}4m^2`GP>?Q&m)IK4Vu_x{ml%hnl6)YKqqDM-jyWw-9Yv9F<gs9GLL
zVr^XWY_4r>+s5iVukYHA=kb9)1Et<!t(Q#m-k<I!&JC#>qEO%3etdi`Kj)WYRTbvw
z<ka5hRu!tSHg<Ypvgk_#)%eWq{F$#;UI|Nfc?i9<UGFmx9uuu6Eqyq)enUx-knL8v
z$~f7R&$RRUQdNci;sN&6`@D+{&CQ#myJIH~=T>LQc$bU&zsi+T%W17hywhCOT{-h?
z1x*;9FS#!CwN6_37V8PszSl0wLOM?_TV37sPOJ=Pq%CfopVxTTrG*}RV$whvF~z0t
zby7`DjRKxsua<|J^{&s8DB=7$h%@-x4+^V7#D+5tmo^AfP*C72sVt)Uh7etVK6#8!
zm-(+kHPqD)ckZi(*iZGBjFnASMpiTr9hH3EfVBzF9L)NbbVuN%qjx>UEQ=iU`Aj5-
z31`jh!rtaY#V-Pj^qX}hJ`<nct`Agf@|EinRaAQCE^AkwR6|40TugFyCqdUER3oQb
zISB!i(z7X3a|<aN=vjv2v))tv(pU)RncBgd2RM>Nsy6iR@95RC{r1+TT4txl+-q$8
z5wFcP@8S92W$D*uS(YwgE)qWu9${w>cBPh|TYK3dtLEgC`LX4ik)B?V>p&^6DD~+}
zOFp$z>^;(})3<73PAjo#DkUfH-)%2izcM=%%))a;U#KlSm1f>hi9a=Y^Dl-#Yw)~t
ztXz#5Ud}dp1qdFw0+X!v=-q{8^Fb~C3biR3;qIg76M|B7;uWv*r5k1l*ABjV^~$o=
z{Q;S#soCALgSBPYPz<LS=G_fT-3O?*JeCj9`ucOboreVn;GDs5k@A`A-QE#ko^ydw
z;o;#!69{kb!ih=2qS&}Nl)8F7>&3?8FS;%9@@HSGrKq3fJ|j_Iev_#<ztJKP3ypEK
zC@J2vhI$^xCx4ep8e}oFv<&n2_gC@m=$rl!Vj-xT;L$GPK5>HaMZVy8a8%8~yO%m{
z2tK|s2DTL>cXhb|a$pcjn*dj+DoTE3eLci74u%iw*x6{pT}594L%{Jus%mU)WxaXh
z#_gXYp^{WRVK=G5cah<o>W}jeejgm9WM3&E)bb7i?NDxRZXVlQ{({Uj&QhXjCUBAE
zW4$+jX6CegtG?A9#w)Am<TTFf9nlyilJfJX<3g9Y+v0irN>`S7`P=R<Urtz*`LOgj
zOBkA)H<mFzwzG4SJW>Eo)38aWIh`MocNdFOGCKuWp)#)(uX+okR_pj+b=0nKX9*q+
zP0euvds>lqKbLjd)u~MGil>Q!E;>Q4`OgV{IL`Z6PeRHDdp~1-M2o;4OiBnkT?Qmf
zuBx?$JOz5OFhKm01p2=7GfgtzmtmfEnp|n>13R2tHF_V(=P^{GxV<r7zI>5Aq@zZ}
zufDO7hc*3}{5U^z_0zn(JlUW8EG#S!h*z{~2cq+1x_KmB!Fh0ME#}iFLqk*39y=xn
zS681{*cF;O_7}IO_#TS=`sf0Bjyl?cTUl9AQ@B1S;bCwI3dPB1>z?l#^g3XJ9_?)m
zpQYy*LuOARCF0hZ34VUEmSb}{Z{92@uI))}8CSG_w{TLmvF+=MG%EH+G923cuJ|6X
z4B5+Ht|l($yH#yUOmFUE6P%$c5~rR#__eAd+V<~DB>AiYR|Tdk3JS!Yg<37?>*>u%
zH|7CAkk)E_4)N~bDgUN77UI1|Og+UOwo&lI<0YdBgPZ-$agqWjo=LM6QI1O!ROSu~
zqtnyV$9{HZ4s=!b7CMm?g(jN9<>vNIZ-#J)G*ErcfEH^KLY~C;g-r*OGd&0KYdx}M
z_TJf7-VP&~t2a2Oe=u*>6>iqy@^kKeDRhcb&TfFe?r{#QDBevE<w!S7;aCdcG)PlF
z54(-Sfb%r>OLR%RbkrQf@t#6lGdHz0V6I-MeECGc0*bm0RzTw$?c^-ERs>LBN<)JN
zko~!aafPc}a?`TSxcmoT=|p3+q_eLSW*^-rTL)}*GsSh{bMAl-O(R1tFD@@59UL4U
zgj_5puD`qX>N)QaP))U*?hq=6k9#mi4?wA+#aI5T1Zt~4I2p>9(b-q({kA{n+U6DU
zo_m++X<%@*%2=_9`$Xymt|Q<SL)^Qlk5FYl==C7{VmI?WBy(QT(&=;i@DJDZTZ;z_
zF+X$}7{ka-BK+P7S8tqix!n#u`g~<<v1GXqeZzL7e=WKrD|nC8k@4}ID)wf>t-%x9
zdi!ZdRrBt08t|y8Q3d;hy`9J>?`x<&7*+ALXOK#DIB)dsU>?4eZ=pj|WY)5;#1kLI
zi+y{2PkC!=v}pCL{UDh6F?oghmKLAO!V{OTZp|mQgT-xsrWvJ&K-~OzFwfzmAa$Hg
zP|JNtD_-7@9U$e|?835#u_d0PbCtSM$`@Zog8foY^+|n^l(Z}NVhDktWyQiA1JR5#
zJi>8YQRw{px?okrF-C~Y>nfFuo2TfR7gDB%4^oc5Xff#!J&<qxbm^OEJENykL^f7!
zrp?CN&=5lhAV+Iu&WpYi2Bn>^=#c*4*gbHJogEm*x7K<`{+Rc^`TpFl9IKpy*$@nY
zK%jS@^02z5ADb#u2MkuD-^IH{0UllO8{v8)R+UZbya4Hz%W7@pU)^5+LRNgPpRUp!
z6&riL2Yw@XY35sXdEx~Tk<p4O^8ASK_(>6woW?46^!4_EWpbRmFu{84_Oq?S(zeMg
zcA^xU5V4<_F6+RIJ%@LV2qi%3sGq}AhxjN@R#VSkwDqvIUOTb*u9h9~KI-5{p=0Bn
zvt2X7d<LbB{AILVS<>6vt5Q-63`S|G%rC$y_a+WTdD%UV($oyeBf(;{Jj*xVm&^X(
zmxyCALZjy`x5urv!AQXg_F?@=yZyrr`FGbQ0T8F1gyr3-G8-92nP+5g&#VKhPdaja
z^OJ$Dw<+tpC$C!-x1TIm&SaNnWN0kCKCQlTqXOl?dbLgDRKV*NlUPpK{*3B$c7`m*
z<!Ja)P2d@UWiITxt;UzzO%LjBeE+s0`ph?4+$5!bnfQ*!n~_T@&yDx&VsYSPZ=uE@
zZHtkEieUH_VEUl-Jb8E6gwEfUtbKg;l~m3s?|WQ+5-6FY8=Bg8PqvQ3%Kz>9s(PfL
z`WD|e+gvswou`ZA-Sd`yvmZDRibX(q>koDeT;o$RGBoruWo>+XX)vI&?D!C?;)Wh=
z<fL3`syZxogI<4>WpCW0b0sq9t=fl*IL?vh2~e8xPaR^X9GAhQZ;B3oMg+#*D~XjF
z-@6HMk_#_di3z+er$C$;(FX=U_eS`~*)NS*JbQMW1vxQSOu#}rviu=S@DINhS<!Nu
zzdDO}+vQ5^g2%?jKA|7ID_aM^)2wBr#x>J&QZAP1Fyp}7+???6#ERC%Z#LH|{Fdja
zA{Q<UR$Tq|Zck5N*qLvaoPon~?OM8~fAz<#!?Vw-XR_J9)lVqLA6UZ1BbJKcOKCvb
zM9!h0SF=|S8isGPS+ZpFI&j^YUs1Z}{KCv)?&+=9nsd>ZS=F$FfF;xRFR_mwkK|e0
z*gN!xY159ANCNvbnf9vMoODZG))r)&US5>Qx+O&=0C(2(F#<@@Q~j2HZ0S#+N>WkC
z&v570)KUI;Ir4*LPhi86$2HZ|A}09XxpV`qBq<VUc(GaXi`1t9)wy@I@)wL>eyw0#
z=O^ZX!}lccU6j5TOZxBb7+Js75`CLv!r{nW#=}Rja;^~-=_l0dvlykt24~;A$sPVy
z{}|O@z*nmjRh;+5<27e$FTWoT@||c5W+J56moUcgVF$`d&ImrCW2+%zgcpz}0#cc&
zCXX$e^4tlQZnAZSPTeZu95;AXq9I=f&UbOaaQt!2!Ii5cJgCYx05Zl`sFQs~A%P;U
z$Zw3_1taU*_W{s%M^HQVy<b(Cg;3?@k~#HDx_){a(6jr^I2uf5-xMzC3sw0RxmXk0
zn6Z!fxOq!FLeO3pWeV)^!s&A*__(5`=k%R1x`f^LBE;iumyc5U`VD!oZr|04E4uni
zJlpS|MxI$5j<Py`^ZC^NnGr_njr8N0=p3JN;>2gscJBqB>-VInZ}^w9D4(4r769V$
z>48sqop_&?CRp3LfB6KCb3H!wQ($oa!44`_xc9(EfT^^fNTKG;W^(Uas2A(C0{HXn
z`SXxUR`xOV5Zef+-Mee$MtCA56s_GcKM$qY*{d~8sMYTCn;V&{x1kAs->?ql9{M^f
zpR3N~Hw}06mwV(-uSf@w@2a^<KTZvlJ$h$A+(Yu*?G`0$ab#0CrTzAU$Vfy^+4rZ1
zY)GD+F~b^0x-xZH=0z&us2f5*yu7gj=y#`|RIUBY6lR;c`O4GH>jtc>C2;HOTZ()}
z2sqPaCZkPYxTfMkPih5X<>l%*gS4yHJTn<pbmJQWyix%;whJ^o7YAQ@9C+p-IO}qq
z3%ab;?@B!UAk|7n2g8>b!>IoA&3qP$j~iL?{D0{}sQJ5_EBgBBhVlxihx>sHiI=_|
zzTeWKnUj?@nFqvak@#V1dU|@HjOJ^lX~zk!#XNj?)X>17+7E0`m-58Tp-9~}a0Uxp
z#cOEnm$|yN!P|)hHudcEzD8$>GO=xKhwt3j{@HcJMxc*jau27=*^qsqFeEc@G3$@p
z_uE7yosf>2@dIbF{60vFv}a?o-VVqR@OS<ae<LL0+{n)6^XTt=g`s>L%+wZ)9E2SC
zaL;Omp<-lYM4_7DXG}|?Vz|##{~b&JS;WHD`gBUG!um^O2-M8XtZiwsul?~QbCvZ&
z#OFYa$>8Wr5_jr)3Lvo8kB(;wn=AlFz{`l!s!m-m;mB}4#25eh(1}HjQh-uvzVpvd
z6PZi$d>_yI8>Mi(C_tQ^wUG~uMYIeYabTYkb``Cgia4@%KeN*)=*O1oJr3(D-Y``;
z-8YAg<aW6+%=m0=kP8CVeQ0W#+}mr`{!aPBj4D)(KceGP$zk77c8RU_9yX8In=5CV
zzgv+>k_W!;W`5yU>3hU_C2msI^?i8@Kjp>ueI$cdw+C4+(_fQ&u0!eXS!HrOk$`Ax
z&pKp%_OaBPRK>R}kkW6@a;+oaN9P&J&zZcRW#qqhIf3m9e_wdVaZYi09^w`}7s2f@
zx;(b?l(8;7bGWE-b`JlW;x+X>Gb*`zhkolt=ob87{Hss*Zygt<zPytNs1D_>anI?f
z&r{882Q2yD=)I)w;Vg1Jw^t5zk)BLXJ$mswX?MhB{?>iVlI!a5rTmeA>RR)H)0a*!
zR==Eux3gz8A&ZoPl1$$3;rx2X@o*j6Oq%uKTAm;Vda{l`#o6iw$I<(y><Y<Z2>eBD
z=8i|q_sL0o44iinSAupWykNfuq`9BnqkI>T-01rgbSwB~rw0wp<-3*NBOR{883%S*
zF);jR%N>26>quSY#h3p}&pONGhvP5F9@prUb8jDjykYA+6(RIh`|YVPNxFRub5EXd
zWAEgT$g<=i!=D8IXC2*ZpSF6;Ut}d6xA1QbYRQ_1<1cXKd@Au)82j$W_^C@TtXI)b
zQ{qsP{E$PqtY{sdw3Fo(AiRs;=>gkR_@~612lxkyuY|W$rQ9Fb3p}N1`?k==MZVpK
zdX=e5V|U<7W2W=p>30R&9OkeN63RgE>%NJ*jyUc%#gLwr)Q^!9c0CC1b~+F-+0;1Z
z<HVxm5^9;=mnB~3Gh*je@tV$}|M>S8iB3WZ9<u&zd~-!eG^6R`{E-iP=$Sv95`IIc
zYZ!7lAxLshh!nMd&yntX7Fh}3I|W}}@boG4)xgWglX_jg!u=xJ`G9s!9rf77NJ=(i
znERz=BL^c~uVfRW@0klFJ{nkw$OiA;pQ2>>rj`97KJv+P(UpQ7a!?BBDf@ps=^i%T
z`SV;}9Ix38yl`t(iifmU8{betEiVsNIa`Di8*yQkp2D0Q{l|)+DL~pdWY`6{n&}eP
zqAn?db)RA%^JG%n62B|mA&$L}qal|ogM{w>C7^7^eWRt8IhP^^hT77`3-^pU3s5Rw
z#2uJ~2lcn}y=S5OCDl5P-_*akli#90A*jU|N|Rp?%R!gCcrsUf7PhT^k^57BKj`nx
z|I^<InO))Y(^rbjo!WXd7~@R`DH$0VS8N)d%GWuverKfHQMJ882S~{#f634>V&>=7
zl4h2ycZ+BvqnqG?HgFU_l|TCFzl@QE8ESfjJ5Tx6LAc-97xK4x=-%%vW`xMsJ2rpq
zElzCS88NJpk<p81&-U~xpPYpE)A0+_R^pofE?pq2KNkHBf26=U<*rYk7$%b<{@c{7
zBkCVKJeip@z3JfE#)mCr^4J};v#l8B_WW)GC|ZwGnN7XD#S3mJ^-_v=UEa}m`c?V_
z(Cr_a_!?YLQ$P4+M#ldCF)BzMb{})z21W3;<KNa54CV-!9Rs837Mx8*-0BV6hrjmi
z&NEO`ddkJ^r~8s)|6L*sj4>Cl!5?33V?Z_kzU-l1l#Tjp%`a?p64as;GahVgByzBa
zD3lE@j$$Rv2wZuxF5xG#k0V1)*pU~Py+7`v;<rBb2AywM@%G<rQfMb;S<2)zPJ0OU
z-K-w_u|HG!1iGpxvvi|M<Y)WatemG5b1OKK>i6jOe-m&j&rp$-WiV&(;U9}ey0;bl
z7C-UTx0-21VkIjJII*9)ZWqKJvfMOs@lROZdS2)j^3#OGHh0zP(>!%~b{4+v;4;=e
zT}80rn8t6vcE;rVBz!R!nX9~Y<G*!Sz>W2(VQ9yHu_`*koOhsi@J`9i^0myfje`|c
zKR!H5mI<_RJvj}l&FGq^CO%B)82mE5pR&>UeEq&94<qAh%K@5o=Kq`Q%~%MxH3Zfs
zltRF=ffnoha^`-vLJS-Iu3CD$ei8QZ0UIfi{H?yEe7SpT*rSMNh|NzTnRp>8<wJO0
zU2QGWEA&jkf6=UzPJS3OrE()RcDV-}{b9^=iXz8VPfT68l_9x(EMBpcchh}Xsx)Ag
zb8Twl<gLJB!jon4##)uR%*Q=jfmj}y;>BYhIES_iByKa0EGM4uE_c&vyZiHVZS5^I
zI<munG;QVBe@D;!^cqo<l5%j{d-nF=e0S@FvJp=ra@*BmtPrlFD=uYsa~Gxm<Bl=@
zo7o7Jpd4pUe$eE%IeN4DK_cc1^W1g-Dtv#w&|PN3438IQ1HM+rj~`d$NdCD&h5B&&
z77?U7ZuHE1i(^jS6|H-bby&MzYq(Rn`k<eDf2F?`_TKDvqGIX5>^umXl`p-?iPMfG
z<s|kN?R&-<EMvJ|`r~pGW6A1_@qMz@EQyN~+kNam?Oy>GHaquHQS9-=!L&Vln?<_$
zx67XG5)c|I6Vtzfu{|qR_nFgkJL?Q(V=Y67boGm;CLiKOvx0fcW*k_m<J*CwkB0Xa
ziYLz_i{=A;u1O<1_}5ofX6}i7424$);!fzNZy@Bp#*FJ8bXFCguADeD#J`+DJ8S=L
z6jGY`b2b|X!?tzXoQ@}&&yr#Wy^~4?xrbOpF8;`s#+5?ql+HEtAJBF*u02%-)Irt~
zrmc<~?rJHYUj5KR8-e7W{23-HS-pc_vpxpC1!SCjH1_4fLt$dgp_a3eZU4nkf>pUv
zHf%?IIY?6$nvm5read~Zr!3Sd8`X~nley{?n=dH6K5(o3sz|_XW081bE#vC_cU)u5
z98slmOyrLZ$K(n>9UptN*1^|rN_b*>MO3JDw%2M~E)gFcy3b6Vt*Kf3F|-aSP}_yp
zhbhb5St{EO$42>cEM;^beth!e>1Y5r$)f&oafX0V_%>Y2N1irX0D}oDH&j$qT*wJQ
zo?#*M)en?+vn_B_-$BnAbUuPp*M7o;*JW=8JC~fi_I$uJrb6GUHzoOE`111BW}U=C
z$B8D6>}~5yrFyNp&sTJvc8f5{!8+^Kb&}u-1`zE9znhGvXR`zu1~y*4?i**K^k@Eq
z4y#g{29%sX4BC}*4XXb*H@4myuE9OD#@aP!IXVKdt=RA)hqKW1I>(-Jr6}vc^0Mod
zO(811G%$MQacseuwxmfXlHz;^Ve8;gC5pfOdaSHOUD~-H@}+^0x{CAvdG^?g)v?HS
zNpH!Yyc84VS^l%WM2BUr3!V6_Lbx!1Q_?Qz$2)#cB2F&@&Yln)^+Db9>&O*Pj-SI?
z8XV0sM7xNa=8KE(X@()pD2s_Qk?_xx(oUKICUWB5J~`#Sk6c3~yde$6M@CM{!s?{H
zbXhR23P^-MuX&#M^U+!_pXv2}tC#O4?u51O)umR`H2jN@SY7{S>hyd5@j}el(y*;{
zgoPCi#r^$MYqyU;#my_jw}9m^plpPP$7v++{Fw`|DqVN-{4uwrZdP<yN|M>ua)VvO
zF!cldc;TavGvlkB$Bu=yPLMXG>sue@e&6^`<-}^6>~)kaF)w(NSN3rgc(?zwuR8f#
zqok%d-PT8%__y7Mi_eCWdT)p=cr3<^DQ)`HS1Xqf@E0Bba?&ACccN$PQ=84Cuk9mE
zW~k21p1ctU>Ntozjg6=62J<ohhxs^06jdy}tc&=z``i;QEMBqu5oj*uwQ76)4d&C9
zPtVHDP%xYe1FOoy;&qBwq=kJ6{DlV?IfoSfN!huv>86d#UD;z@w2?}kZ)hPn-oB~I
z%1k(IX5I3wvtBPtb%AS2;S;m1;%oDtWotGOC}4}-M`ciP@xbaa=Z)|G&jY7}WllC{
zhWO~K>w%H!R>^!9A>!#zg46)G<71EcFI)HYnU#6XAA(J<>a;y4HJz#eR22EdkUkr(
zqtoUW3RjqE(JYs_-*Cy&*!5cgt~1h8psMi{q)uPx+dj_^R)M8YmbdQRaVTE~=J3o_
zG%n*X^IZHt0L@e$EOGqSg<5icbhu)}oR-n}EH7UL-w~EP$pilcV5ry#H!Fo;CBySW
z)6=&$HaGQdYuwCE=p7_&&$E8vcxF;O2sxz74Smo@VY~)k>i<fbXtFCH7@UqRD?J#4
z?mBCHK~g+fx5a8PjBa=EO`1QITVB}3tFn0P0BW(xp+cc3h_MrWQN`tixG$3%=nfSp
zCGzM8NhLAHaVUOoErj`ewCFWoWmR9l2w_NF!am{JmMf13iha$dAoaj{Gse(x<b7J3
z5C15AKRe>WxT@7`e(LnaXGg2`>J6y&Fl=fO(+_&eL=0WN%|{Qcr76X@Jb;^5n#d+@
zwV89Olk_$i6!dNtxyod3(Cuc7p$+wZIqxN_ARoM4a?KohEYm`^eOZY6SUL~WQVJ-r
zCmIXNm{ne0EhoppRb4{IHrgkX2adi1@MmFY<5c|zTQP1ZcP|AC1fv!7Ha{bj!#OX`
zgg9PT5?5EA$JlIP@%*>0zL|D{h8taN2C{N|CRNJvp)>(Cj5hPIK)WUzYuh>v{Myn3
z;`AD4c?b9`v{Fu{q|2)v<;1o!a5_f}OXMUR+44Jf!uk!r!6ka~sRxq(Dr}9D<iQ>R
zvI2+_3}qMPW!t}|cnxlR*6lB#+5_8FW6nY_GCG!#lY<150}2P~YXKMVjvBSRlm9~C
z20ehzG$>A64G7gaBKOK+EN~Q<p)_oJiad{_yd0Ya9|5$bRrC{l69j+V`u?micuxZk
znaUZ^-7%R!8oK_~FPH(O&geyHsTp|}BQuod+nyrt2BZA<W~O-14D)}jIT-oa%CA|`
zT9Ri2bH5<=Z@rXor+PXC(0rT$*R1;k{cUN$<D~gl3KoNd(3!v7om~`WMlNRPZNr4y
zLoCdBO0^<rikF8Uy^MK1e_u?LoupJjJ<U&j{Qxf1?R15auYk$)m!o1G@s^(gXT0A4
z^krvA!;TTX+zsuZOADGy_w_HAF3dGy<bQNY^Bie?a7f;IW4kHaHrd7P<>9#(i~=C@
z3;%z&2P1%IPV?-&3VrWRsNP}+4)S&2AC3(co<Hmru!psm^5hrDhScp0T5T9CDv+7i
z27yUUQn*{zc>9aY>dOh-Ew2Iao>I9~Rm2VavLx?g!}i)e$D@LnCfk>n=qMAGV50W_
zQjA}1aHvTwF9OMCPsK5YFAI2;6*5{3NH(K%Z+*d`fJT{_SJGXQJo9uon4uue`CxAu
zQKaD3y~&e?R=*rDta#nd7D4}Oi;$;+=5{l4Vl#lNtTGqOG8nph-A*!RstaA_)4NS|
zh<vCRSi+W?DU{$79U2m++_p%$S+`Vw!P2D#INtnyLOD;znGW!Ra2{-FjZIgoNwiD$
z*s(S~XyL7gYlKumnsZop#M;<dCamd#Q(HrkZp!IV*9Nc&pVb_YD43i4NZYBGd>s;h
z8-`DT|E}KnM|Ze6T98(gz30mAct^P&{~S*H47P2%u;=}`S`m;<vb18nFl+XxniRCM
zM#{Ro%(-2m9oN>7>mWxdSGaU6KJW*^o|UUtSpx*Y8@TA+BOcRv0{dBeF|Wve@UeUY
zE5te?9eAUM>&=}8;5)_LPC4hVZV)8ZE?v6x0yw6;{btvIS_SK5cR$tbUa51vG1T$g
z$)CmnczMl>)ejs_)tWQ^;Q)+Pnx+=Cpf<kfmL7O^r#lH{T6YD&ATEp@V4}(OQ*zXj
zdaNyi5o|~r+j4t2t8j`RSUEbQ)+d5xWbaH-2@YC?FslT*^z7_xWKH!zZ-LDoH{8;*
zcl13u^)av10~LDeC?AgrmK06qdQZ|9OrdI$v~_u~IYPRb+1Wa#K<0-q_Cv1tlGI{4
z<-NN6A7)hcxDmonLjqCQh#ZSDLBDDvqjtN9%!~=al7@$uN-5)+>QgR$LGWy)?raN#
zt{r*+`w*~GC*`gkt!6t`UN0Z^W(9Gd78-t$p02)B1F*cLq-08txtX3eCZSOqggxeY
zt-^sT2h!|@cNi5_!4jJyZu-?z*M%Z%NXgeFOKOjBR-J{_NtjP-#auu{!bf67^|kVV
z@kB@4o?@c&IC<*Lr|#}X>PUjIl@Ib{w8$wE{kdSF^CZfw=E-t0cdAo&cKzc>Eebq4
zGc(fv-j`?UTT`;(1-B%*vG~cPXuvYu-U}g#rc3^4cyvKyC}eNK<-6bR?5A39=<jtS
zT>I3~aUH~!^a29p!S2XGa!068%8ApKhE`VLpuBW|_ic>2!fX_N9s9tqmyc>4F`X)Z
zRFv-afy28PVL$3;;liEW-DPKr4>fRz0?E8(6EA<e@{EqEMptjJ_Wey@Lhi;`j9s49
z$M}YL!4lbko`QrTgjr+4oxE-)ms2!y%7&g<?eO1dm-2mQ1URvA+6s}(j3v`MmHyL%
zqcS|uXU=OD3|D8Q^b-$Df+77U3UZ@YS7+?O<;M+C9-j)2!9wZ+IR2TQnHP+Bh>LKM
z;8`1KIQBnl+Jl;{|EoDiTBYd!(Wf)0v>f+8D!I}s#s2@5%HQ($IZwgrts~Zj{|lR@
z%})*i`r2>%;4S~M#eX6B;x5k#Qk?U>T^>}eFZIc8Df~Y&JE}IBSaFkf^n6%m9_yDm
zk<dOT7;ipG5w65vc3~NQv6)}gZ#n&?;EwiO<pkGQLwl8yU)?X4^psN&IVYRzlEwB(
zXwFMi>f`L~Llx-m32py+SCb%+XQ(3PhX3+8=%73lDR%DJQC?r{L7DX$#%ZpqewGfv
z0*`ITa`%KDN|)IVV+17ebeB$Jyn6Np9pz@X8+BX6$n(Ua9m1rJ-TI-kO{!LC)QmtT
zW>?zLT7U@8^>Au(+2wFn_3zU+S1ze0UFko5J-eHocJj7^Bk)EqcZEKnDtDM;Uzc5_
z#U&qKSjx`cGnbu~L}x#ZY&~<?udaW`xjv;C)D!rM3xLn3&m{tH_()nRH>0;R)jFSS
z?Y|V*?ArVKgxBWF6W9FfakPoi;D|Pl)sEr*X2WhVP`M}IYBK76Y2GS};r8uglPwJ@
z;CuAe%CK-m@yLqf;?W!lj73a-W~YJ7_>cD=UB}-5p79qO1dfs!t;7eR%-wCI_IrsF
zx@UGocgBshWKus8?et(kJVXod;dDQ0hJA0<7kkf{_Jp$jC<X7xfRe#kg#sq&U!Wq7
zfpa6;#5LvHxo=hI*<Grt6lSe+4*)ExPG=&-p>_9dSKK{O)xYaVi*%)#Ji;emIb^13
zc$Fw7eCyzE$Na-sE+xQCYl#~CiMtx&GU1Nf&iSWnkMRvI)A--x(yt~HU4obN?EMbW
z_AMutH8uuNwn-o^DX@dK(tbmK1aUQ~?nPghYZHREBmlm-4DiMRV&IBBEB#Q|pXh>5
z3`V1KY3GxSms-02HF#R|xgAjICSC`|eTAjt!{k!@5of&RV}OqYY0FGwp|9k?o13#u
zLzySx#(xfmt4Yhq=#eJQ<`>4)+QH@IGPv=?3IJL&No+Gx+b!MzYtX3g7;y#AYlA=<
zb1&uPpQC}saNTTK`PUdAb^Ce25RO=GiWHS385M6qyuhhKS<=({v(K2FKIiCZ$Rp<O
zXcW-dmDEQd%+UFZ%3+Mrhbf=6vW_^1y9>_CKd>Vpch&9d070&&sd?Zph8aL}N8H|F
z8dUx@jlU4AI#*uhnJN&9_@AvdM09p9Z;46Tv*!ImP5*DBAbM!edh?fZ0`&c<2^<WZ
z*t`EWrw34Mz%GCe|B~2$s?G0k9Re$e{&%(d{rgsi=x5{H5o9}-4C&2B6ROn%;Qbgd
zEARv8X@kI^`|bR;X<%Q1Oi>5B9idI?#q4Y}v_#cO05XcQodb8%HeT6&t%eg-znl#k
z!;YtKTB0=XKr%}|t#-kZkp;B<Y_Bb?M7}66XKwesdyHJLLg&GKh&U_}x`P_K3TC|v
zWG}FZ%gHcVP&d*h1iLIs%U88O&5RvipO}r*1Q_x+UxbTWZg7<4LF^9$Y|#DtLe~44
z^Mp*R^XsVm={+>uL*N<ugI`B|cp`VJ(pBcodec=i9zBF9-!u#mv1|d|KcCH)Zt&sr
zETrxwWWSQ35gkP5RA-KZDZ#wsZGKMZr)iYwr`wim5qp(KvL<H%JDyTAz@yh$Guqx$
zN^A$TuR!unxCCLWoWE(EpRC>du5<kie)TAiHFjiQH1K5A#a;X@+EvNuYwCm%lib0m
zenzfB@l$|06J;KxwM3r2YPK#h9RR3=u<k@Qu2WO%G#*7Ui$#8I6Rk7xeRJZ=<4Y5>
zg;xi>=$>)kx|<!2;VfvgQ34!^&LenQg}hnV^yM0cEUe!}-&DE);?^O~q3n=};2K=M
zG;h!&;SYN_l}Pkyzwp<<h*+NL8MiZ>Lqa3$bN94p(%94%5k3|ZPb*OHeCa4Zy$Q%V
z`K`?gaqJ|1=}uFs9-_yTMpPMcVa@sm8}3-BJ)4`(lYggVIF`t9kOKDs5!}l(f0h5-
zJ%F+z%bFdqp=wk$NF6Oifwy5+E-YUjJ%$gtr(;H-pN5IZNk=Vj^;XGE`6$00yHDSK
zG5yoTFyQ)LK<f%#BMH|ny)3r20+YK(*zvU10T}c4_ReEnN-(ythzI-qq}(op9Y7W&
zesf0kI(!QdlykGQ-(omjTV6c;u>k)2OhijV_glr)bPpjAz#RK>iDj&8{#F}tlr`z9
zh1~a*jYZh{&O%n1bNkxWxmqdIz^p*0V_jdy4>>xi02*<&GDk`%<UB>o*6)gAfBia_
z?RECe`F9u^x%y&cAgZj~7*bcRq!Q%d==dPu&2j<2eh)dU_kP<Kt<S7$IK%kz+zrVi
z%uvvp0n~sjn1-p9xpml%VT5sedo`txS8;l@+rhY6$uO+DIZeI1TX(YWhCXw=bhVWv
z?^s8K_zCKHXvhUV5w@7GotmT4@y+Ft8|I+B(8*l<M@OpDbe6^2b-z4@;ELgugOIw8
zo44s~^U2*8?_I!I?Hvx`OaQ0aj0%g}n^=0%=@0x>l|T0-TqC>Ir_dPisuMjUByBeK
z>mC2h%tx%!n0cO$p(o1%afxT27ef3_t$l0oSV-e%MMtZOT15oAgOE}NGt^}=_uEZ@
z^6nBGFKBnq$Z_hr`~cT(<~;vhKm`G#Al>$<v$F&{a?`r<_V<0!$q7Okq}^R-M?;TN
zE{Y*cc|%I6Sy!e=&0+$)kIc2huC`9s2^@><+&x`>#-T2Cs40Rb^oLKoZ)fjoW!N6R
zgCtE`IFkTV{nAn<e0fWVNy5M`!oev#dtq}FiMp-vVZA3VvGY3ov9QV>&O?iTL&<78
zu@Q%NGQ=Bi$jQe%=Z@!WF1F5-8JnY@J`%I&?>9cDEOAbLPsN;;wC~jcjfF&GkCt&@
zC{&~i>i79lmxT+WNz(`Lx2?=eZZ8Kmmx=83&58$+qUbT=_i+ZwMbrNzKktL!bHf}-
zbz~a(dUlEP4`%(U|8`;*<5BhwY1wGNqXj%~JKlUQx@*!oUC&JWwtY=5#4p)?Byzpd
zo!z_7sZ}2z;o!)6Za@lsp+O$U$;g{&#>&`3rX?HvJp!!y0G{1vTn~ftpttW7@i%tm
zUf8u<sNB~*6FBm0c!QVqMzEG+W8oBYjDtq$82*NIR=3XdaD~Vd_(&R8n+>g(B%O(#
zvn4`vaU#MMDKd2b6#Z0ZG$pNZ6PI+^*uSqFCt^%mQoY(Q;?cnqjk+1rpCd$%<cD40
zh?=EN3p1@Q1eOxO8nI@-u3Wn}Hczu~U%Sv##RuQ;H!9j+e=+iV1RIQB)#dwS@hcGS
zl2JG<_k%_A*&IheVq3&!8KV3}rckg}4$ENtZJ~bgBv*5RY1x~%917z5wd3Jw>GH3P
z_Z>Wo;baWeRv()cK4l$o@=e>nQS0|{5jWHKndD@@aQDa6j<>1@rrkR>n!i*N;qXpL
z4}?mRkqiAFzutJ>Tro3rg-YzGWCdD&vQrSGeBwEpOHxuQ-|{O5C7J#`E_J&37d!qM
z$nNtb^I*25amo9LZvn)jmt?brXg-me_33A<WWSXR!>u}>ZxCRYUU)1sQd^HTMf1m<
zoPWG@*(J36!!^(gA#-0q0X`+QQugXz<~*-|SmIdtW2g+MxxJp8u*~&s7aMc6T5Lik
zXC659I3_C^2fX1snP{wlt!9s3==!+F_Y61ItT#o-f$K`A>wSEm{69N9s>yJ6?$#u;
z&@mWW#{+Vry7<9I8`+hdP!KX!=r7U1X6pbuMGI`!)|Lr0pGNmY)+E!;NJom6vfo~O
zR2ds5_W3{L58Po~eIqL}+jP%Rcs!4AU>cUmApORK{o2XMhCN%LEpj4x^#_5v4iik9
zrRr+xxR(<_Bpl0`@kk8gxj${dW9z~l#+cxxLwx-mAeHO<TYlMppzx2dKttC?oLMpk
z=AgYZ?~Zucw5p=^(>F8r#O?Wi<NFgOZ*u{Ol96L_I|Hwy3>czgnQM1%zL-o=o!$$9
z@~~TLc*q@Y?8}8kwKr&o+E4wI0sM4|Nml=-+X~WGJ7sG`{>l}Yi22%KM%43({N_Nu
zlXQPESaV7uEq(`D7un*48(pu+Um`|hL5|b!BrUR$<0**5y~y?FTXXEzS=hXziuhS`
zZIf0&BeKFCi|FmZvfT!EX*}<rblBZrbXf98=C)BPx5(!<P|&yCrCs~zZ-|M3Q*O7<
z;G4i6mRn_uo!Rj;Vmu>3T6^_3w*{6{(3&A(`Kq4AZv%?$)O-WC7|}Z(5M{qjj*ilN
zuV1y=;N8_6kY2Wn(RAu{TFfuU;a_a_zx54)?PsC!WdDNSfI9x2p?1X4a5$h;N(sYv
zp*w8iFZ?@iOnJHT8^uhC@hFOUtN$Vi5Z-?{On}}#CjT2cguoJ@u*Jp2h68`^^0!$q
z<7y0WX@7Cq{|5Ab0nN8fq=u%2n-{MC-8cIkME^6$j?qdJ0olVKTa&Qw>}c28)BH!w
zr2}TC%Sw{8|48KtD6Ofrqvb(;<O6qYZrhoP*{UuTw(R1!6~*jgVun7$1=sDc|G&Jt
z9qJYuqs0Vrf}iWegJwC3glNrzY$8)1igFzA(Nt-iGNGd8k7hwNC2;AeKJs~yk6ncF
zVAEmih)0(ob#IQc{5IQRM@m0PETi$yG;fjdFK>~?OGaH|nuP24ExhMP@-*0x7<=lL
zY@>fvF;ZTF5CvnJz4gC*shs})ehx5a+Ksb)XMv}>GaA5&%XL-l2An>PDyNNCrnvCk
z9|Htc;b4HGws{9Nxv*JpAAkg$z!Z39%t<IMIuQFyqjuatkgL5lqyZR~o;Kh-)8Ycz
z#=7?h#@dpBe@}}V1e6;KT+hz=l~_h}j5vMz0Mm82aoQXH-3DTi9S4Jv(KKlg4SxDS
z0i<Dqd$7WkVc_1^{@mWlHJkV&*Q|SM*|@BqANY9fd?5K+84M64!N0!CJm>D|sN(<Q
zmA$g*JsB!DUqX|@(0l&v_s;-N`pakIq6KxDkJ5->9!~7dFss?w*}#?L-o8EyM&_0P
zc@P}PTu*yD7_g5f5A?FO=ckX~icHmEuK{;x&)U$JQc+QnKhG5IC(Q4>k+{2aaQo<?
z*xBOqHs4Rv(y?ht=nLu}d>trH78L=h=yv?GNLjmkQDtx8$E{_ZxYP|g<sh&uM?ZiN
z2d4Tn=`D>4E(&{6c8A8AKN&qps$O}tIA2~~E(0>bwY5VvlS+KQJKX9iE|zAnP&B#i
zoLK(7b7TS}{pAJB?Jo^{)pmcd_YqfS2BG<I7|8W|jRX|<D82mR4LflEBckN2Nu&{X
zf-~1MaIfcmYII8Vkp@O2xF_RKII@ds6A}Jc<T5QlHu!Fp7M8P<JU-O{A_KI~G~?52
zCp;HScRCIX8N{FN79NWWI}Pj&jm{qf!8ckEE`9boOP2q-7|kmUvFsgX8ANxrdJ+gD
zc^5;#9cYV#Ej@$g?X^xu2M2e39|r-H=i#%t0ER!6KkF6_t_^{EnB3xmPE~dMxA11w
z$cJfT_nzGW7cxuvDFRKH2wRP*SwMuE5!*xuM=$j*_GVHKSz}>fi*RCfbA5gz`KgdV
zyG?&^u{G&pBki6w!5w4+>w#zq&}Vwy0XY^LDUz5y3o<V2p8<ydY2>*0*w~1}gR;|V
z>9l+~%G}Z`vn<*^huAb}X1oGP>dHbFSq$+P_wD5@v%fraG}0&44qNc{$syW>qd#sa
zdV~9MZ0IG~VA0jH1AwaZQT7B;jf{jCwP&h-<^o7-`=op`X0sK3AO;0CHgA?e3&ao4
zIDrVP>IDg2WO${!p3nSG9a?xKRT{+NK5X2><ZTIo8!|WTOh2`?eI>a6{Q1)tE7zZu
z<;3ySI~;n@#kZG#UEKRQxZq;bOIcW(f4{hxChzWx@bQ__ek5ZnT{ZvQi1}XZ;}nq0
z`|<=Xl=bdwd*yr1_J7>{$@$1Xy3s*JKXQsFc@QU1lKO^DnL+o>!(aS;-xJj?wc$xT
zbL4zu3{3kb*kgMRuooYHOylLL?nXvKJaXqiW_4)v5`V>(oJT-~LpZ3w50qAaZsmL>
z{Pnc8=;cINX=oB@g_ck6zVYO&wo*HPVd)TDP-5Fs(4*IlD{TdB9Z{jYpBbVu!=Sap
z|Nrt#4XJ^Std$?CfH}>YGI@#5@6j_bh@1#TmcC`n0C%%pc#BI)Og$Dyr^d&%{oL{4
zyF0mb=jXzeVSKF2TH7hxZP&$swYni&MY~$FbEP-&2kk051-^7}CswhW`S70}>X0ju
z+w}CKqC_b8DFaU2Ckq%3t6N)Am)$?dk|~+i^yt*USC3&G&;CBzT>Htixq^F)$SDtJ
zn-PiHiQLoM#h%yrsBe{c-B?D6TTjZkKqE^E4I2-0L6!g`&nbGXfPjh#IkH*6Ko+B$
zKy*~pvOIiO@Lu5l?L=(e#1csBcQ!*lZbxB0e*tk7K8$I1!pquDkQ9n-R2LlhYGl;o
zd1c_f@wdA>WAF$FaA5T(P>1S2nos7}9$BsJb;uX<=sHZg#^=U#;B;S3{=6)6UKyo1
zoGW-W9sGbmUEW0*@1GAZ?qU=XTokk@Aw1Ld_5quvC5u5o$MOBHVB*7)Tg-X=e+nf?
ze0XNbHtjTP3`R@AAT1gS4h{hU0mWiZ_I$8e#Kpyv*4BIrfLRO|<G;h`HchQ~QCZ0c
z%1gY8_7e-3?ktY}9QQQx69ciM2M->c0MGZ1iN?i0Lo>Iv>V#{E@px?I+FnZtoBUGp
zAr47l`91KmEM2@H_QpLN+HF6#DewMJT9h`fuXnhqLE?5`Ts8M`sErFW9h#q;lPrUE
zDhcmIU_PK}5g02r?Nb$7Y9$J;jvuD;asH>o{f-}k_@JywH7QaRN{NOqS;2*b7q?6)
z-lZK(G8|*GuSxUK@RsK0fNOT91(<5ap1xzBU@o6u(JtF{z|xLK?T46A1k{Bo%yR8Q
zO0?|v^ZMj<(bH=A*5Ky^dU|?7!3Oyd!f~PIOr*_I`(r;Ak?$61cLqV(y#9q7`L$sK
z7n0L-J)Ng()N{U$p78U!#>dARC=;;eRZ-?sxT^$7Dth?p^Fm=V9jyP!-QCPBo}(x1
zrY!&7;bB^b;71uajzGo5WM$Wr%XB_RDxcvz8;kJWyzd^c^1hr4mY1{2^gM^4;P+(f
z)(p1s#qE_24DF`CNzwe%;`<O3+C^+H+C{;wTqFy$I(759T@Mc!zGjqgJ@xg|Y;Y_4
zS<4>b<J5_CIon1iR>|k8zg@DU{SblBuA0t!AfNcIH7%d`E|&TVKBbngwrv$$UlMmG
z@kdkyBv2m?zovaoFot0_B3~^>u_T8zZt(i`>(iaeAG>FpJjVWywyzGWs`<hdX+gU4
zfHX*VgMuO@ASf+z1d;Ae=|+$a14NYWlI~QbyTe0wb7y;hrGEe1KkoN@`|&v(_TDpV
z)~xqkYi3^jv(6_MCOealMLMB_iR(6BaAt@R;4CH|I4kW$gGcXbx{d@;bPwp141v}y
zbtiN~tt$iPK_SRU5Xn+=iF5UFTletbBZ++$iKECu*<*<DbNEA#FY^sKZm?tix}2!B
z)X(Gjj4|(+&Y%$1s(W7qaD(|G4SXt;a&mJsMW<w~kmYKi=H(ZB{W@h7c@nm}zC1cT
zCgz;KeUsK2lU6OcDNO>0r}!O3gvdj1H(vH*mwmP8?N6c)?14H7ZGTh8*UB4<dM>t#
z1_skdzKsj%TiD#^c_@x;11+O-TGZCrMD4N<E1)wFy!d_K3<UT0hLooyu7mn6BuPf<
z==WL~q|A7eE*0EWc-PRP9AXT-?eu7cR)o2@w%pT2v{aukJ;=kL(%q!h=jH*yRJcz9
z>Z$nX6ROM~ZzLO5!?qT-4CcO{8;g?&4>KexeawEbb@YHFp`OQ>MzYEC*<2-E7@75O
zWNCPdE+!i8Z7p;DW$839>rOJ8F3`wb=naXs!Os5s{5!)%PogrydR9j-v13znBb7Wj
z#Kewxr>B|-(X}geGAYFefS0+Ro`PdC)HRwtsYz#yTzRtaNIp_jw2xQcrC#3n5>gWR
zja-rNK%w;%I(q^I{D?LxGIDL<XesxeiLXtuXjR6_vcp%a2Ol;eJr)!i&DX5wFYMaF
z*Ub;dNaqYDjA<y}roGOFKueh|WWkd06F8?z^K`NrkI3cy{eQQ$ElF;9{e=<y3_9-%
zN26%x@hWQ7$nHDF-iobtL}-29?7A=Hk{JeYaq!nf1ShZFga2r^t%z$;U8(G$qp^N_
zk)F5OQfyzMP9F((JjKLPHK82<XI@tNX`-qX1NUz<3O|+dGx*SXg98X(XtA2($I+(_
z$AakX$?V<qwY)tZH@LTVk>)u~@)LrlnFrr)LH5*(gY0>if48kuuDp3D=_QY(&sqk*
zFL`ua${T?LmcEKooxD%w<ywbbn<4*hWXr+O@UW;!MAaFUy?tcsvP+Ng1^=4;^?8%1
zNDwN^6c}w~s$bLnbTM~%@l4@9gyB+0WL$lFtDD4=JU$s#Z-h50aHUd(u5*p**LjF&
z3bj4Z0BRt{%RrSzwH6i^yS153Bh<g9whS~^M5B0*{AJM6?-M--8}#GCOr}vvI;gP@
zA-xyiP{xU!FHNK;ADJ|8YdGwGdh_FB@3ENR4J;B4X>jhl__5bxfQT`i1Bm{#k;l5a
zh|z5Peu@PTV^gf%LXks_s1%{6pIC3PeYY6IEoo~9q_ZlA80e#Tuk;b?_tCi9F;>2?
z-tXwhoUE-Cr|esM6~L7~lB1FBBC<8L8BZY6%1}1qv_hir{zH%VJX)U*v#cDeY6E4K
z`gLo9i8|#g0b}?XL|?IEi5s!QGdi)!;#Wxdi#wi@X(XkkT?jbKR{_}<U{3<)1o`U5
zTl$$J8SDjMf>VQ^y$6(YI@}hJq~6h%9!qiKa1AzDW)9+Is<Y4XT&q$o{B&TJxd4*q
zvlj{I5(`&ZQ^(=L3Qae!I|mi=F#<o4^@tDogPloV>X;wG_+)pfu>TV}I9bNno*P!;
zSsqZ6b)3`QixteS6cNltO#+U;H3~h4gga;?yQo~~mEyp0Ej6aB9i}IRBSl{V=thKi
zi)~<pymYU3qB4Ayi><d=z8JYIFRxp~HnZ3xO;$UykAn+91wXh-EwIl2<ur)i0|6l+
zvC5WIJ2Bo7GG@l8f}i}YX>DZA7H6!kE)}6bx&X8U0s7SF6<9k(71YubiA|%E+g76`
ztj<o={$L@E-G$nK^A$(Y7iD#-1={XN%A>QR?LNU{%z?HDN@_=i@m?NfAll<RxBx!8
zs&axXua1^)dF~bz>6}j&-y2uN`2y~d>7;18UbayM1>f1uSX39}Y4PicaLHmwb>tJX
zKOZt-NhMQN#><{tYzH0BKio6jNELTIU6GBYt4P<6?%{hlk&pwgXG*^7c2RYD3e+^F
zMPDinU;5%38xSNvQ!u7V-f?;QR7dXV?5Le#@9_ZAX{|%5mT#|ZbR&Tv6b!Wz#6Jxs
zqjLlIuD+iaZG1>Zs&ch8NttH!@r<wM8@9>QNscz5@5wPSjy{wxq&L-|c)h@z%`d9u
z=6tkBFaCpqOi~Owi?-NT7rZy+>TX#RD>NGdWA$O4ji6_Z5eo5GoHyiwM3~H8XQNJ#
zZr<!hkfy4yQi^vCaJ^7UGMrtlVjEfw04I`F+n7x(D1<n_IQ1kdpl2&3UA8WE^67k3
z?XP0HcPqwf`#$N~!AJ@sh3D4UI7H%@p$?lU4bMTTHaM$Vs7WloDe}gxi8r6lDRDj$
zCnBN<oO|a<7dX_6Fqq9g@w9z<ydDQ(`*`N-%0wc2{t>EsKmy<{6c6Wt_5-@*p%6h1
zvE3q#*xHrwP*-|)J9oWzG`TRGfbU!40`2RT(?GIb3gxa6@`Vx{<#h3ddC(9kp(LfN
z*C|2ykDlm(^g>tzvQlE_emHA;^Rpi#qSqfh7J6~qDd%!ZdwpR{4Um?%FTzMlR_?Fa
zPR6-f@UZ;S0Aq<4dab=DIGstlVXI`<(m_wWAjK9z&fPP}C2Uk~9sGTrGFAO2sqi6g
z9g^7|IC~q94ulyvU@-d_&`HqIixBC9W2rHAroGOFZ<vb6O>I{qP{Lg$-$MO4k+>$!
z{H+rQrd6>JMcoJd2Nuz_+F*`<DZsTKGYj5G6M2|cgwjv8ppvH^VXz8L^?LgVvU7oH
zUCETw!`<?NoB|xlrzFzNY&0Xrv8Mv6O;c3%&Ur8s;4?cKnJs4Z&!6pWJx|PecZgb}
zP<054eYu%Uu@`J8{ZrgML-otUfae@IAT7i{bgUA=QBm?PS})VST|2^qg>vM|6E)9F
z3LT9{Honnjb~8S6(^(OJqikc-fktjO^G3JF&zKRDQWWNo_4f%iZp?PFyMBlfVB8zd
zQiu%ap!x)k^^y;@yfB#!4!XGW`pLa6xpoV?Y&DfDW9f!bIiz>wQO?Or;fzi{8hLuH
z)LV1k=~kh=Tp|3d>OSx`Qhte?af=Xm)&#=d%Q8{1hHf+UcAp-6>swk|rJ;-b+_ebS
zJLZK9YeCuzAArgNbV?HxN+L-YbAZx|Iy{nG-p+b|t=<HZ|Dc5pR(*-MSQZ{yU)}rs
z9m~d>^vKawgi}voVemEX6L_My)vY5m{RcRL!K-IZG(2IGl>CN6tEd-Ed^FT#8r(Qi
zRl(F&Ljgelhab>RdU=wZ&8HPavuikU{EVK>;1Q21U$(K%D#U-C_!=nWrmewgJ?Q~2
zQV?7`eF?%lBwqzdKrH(zVD>b`C0+Otnw+7LD|)=rcyN}}CO!}Oj~7zT-umoVuN@Q{
zepv`9iRwpqz|9cEqZsOo{BP1b6yI_bx}G!%DNM5tAPTrf+OIgpULE43R&`8={9wBd
z4t|@gI9XH`yxhND?=$FHH@7x?`SJ$}NFOu#;+b%GbOPt&LJR$i8zBKE{99p<B2iuS
zQ;g?~>8k*J7IuHMHaf&~M%O0gMbGy%u~Uj6#Bu+mq4eGbP*E7u$P@OQLcXYFM`ez5
z_3A|D(Ah-_>l!xko^~Z%RASioWTn~Q_{<%IzwqGE`1_b9X42#39^3G$^O`J{P-e|1
zr-V^;f)`jlk8GM&H6@I0xa>YrBeLEvTBfcQ;pwEtItsUtl5am8S$jZ>0ocn8z*LnQ
zn&nMqKdpN;vIaP<%4?sYX7v@NEPc0!8gzn|*?R;c$kQOa6qEcm@nz90O>s%ZE0TWc
z3xxwrtGiSfawP%uvHnY4<{xCBNtKVA@-(+-2?}g=zzco}6QD+>BYw@^Ipf=x@A#O;
zE8g-jKQ*QTQX~&R4vY&hMhmwD4Pu&KC6BxywwYuf-pjLvlbGVHB>S{c?pdQ%`)3=g
zXjg7yVLonGriF}0-*!+sp*X5t4~(}H9v<p!zn<?kEpRJ<OG&~Pxd%8*9KU6cj_o%>
zoK?F+ZzKJP+mCIZtdsJ5w2)pM%)x!R8~fqrvOlQ)DM30XFH%MPDD{qOvSueGv=7I%
zh*T9c+UvTOa$X#i#_I1fxQnY%0hJT5I(^H0x>c8yDe2-Sp@tnUq~ZopE6OzXRS?M+
z@}Zs=OfYkYD;e@17k+`HXMvf?)FvVz+#5TI*zD^C0izm0R&@>m3OXFg#0N|x(weu`
z(w2Ll*)yc_I3#99wjGE9TJKpe*<N-6X$dXbuG5~Pev}wj6<Ef<iVpYlHNrJT4P42F
zN?)f&!!A?X15Yf%p?a_knj%@cfYuj9nn92WlY8!XhSQCVT)qgth=@%xCg|ni^t<;a
zRo_z7FC55OzzAOxcA>z-P0&6r?qjJWZjkcVjtaTNp-RaWqf@FFIy=&C$^Sf#TbjI9
zvWQF~v8!_!&<A72rY8_mpxL~NEPB}R!FoG!;PMrdk~jBjYR+02ERbx3(<+MkVOduY
z8EmHaWT$=aj<uE^Kd&n2t%SkZSR|Lm#O6C+DY3?7Z-&yle25URUcC8=$;Wa~ADi!D
zM0iOSDE&d19pnxcaZs;%?wnMk^Z&Sqjo~hA@8dRq>`P}{f{qr|PmagWGy@tuBqW?Q
z2whg`MQw3acR%w)ainK?LSg@cb=!EYrb*?KD5WznBNPatzvPFJKo+i*wD3DaH6_Bq
zc+gLa$1iE^BWk|eP^b`#7T8Zg`u6ty0YFI2V;{^Hvf_XP=a?Z$)FGzfcYr!sQ|wp}
zlo;=yPM%S-63droT=bD{Y0111Y0K({-E#BGOwKn&3s<DYOBS_!`tY;|nq9}sPbT{%
znytV8G;8-qG6A#uL2~+G=;s9m5)vFHaW9@*G#ghr_8zb9X``V;^ix7Dl3s1e@tymq
z29jPs!5jw8@rNYMUu6g-t7g$jIlbRcslzADQ)JWq+Tw0zh@KXxixcOi53jP%hBzZn
z8<Dt(yN0v2?hfj|OBNE<-cy-IVM;pDHnmbkw*lIK5cet7*}ImOzmEjcE@426h@Qdk
zyuywz{3dLF7f4!k0JIi#s?;O}33DV+idcn&%0PsBW(FB$9~|8GR0Gtva6zG&KHpcg
zoUM>ae2n*HVUdMHiw%M-==E~uO`w2r6XeD3L54>4=7k_s94Oi9G*wwelzn3XIf3R#
zkn%Pt`F*l-F|#Or#~}~uE$xBA!d@ywf~~-xp9II;)CAE1szUFC^H>iHuWa^-8L|Oi
zCXfMzGj-Ky8}G;My3Kc<ncPELdk_eftwBcVW+mnPoObI0;nfpvHMRzh6Cb%KOV(o-
zsBw1(Qu%Wm+ls$KMfmZU_!zqgq)G!DeOuRX070m7x~1wuFZwd{f{$a}Wmw9@ApoRx
zZ+B=S*H~C4?f;3Xnw-h|Dm!uaI?(hR+?A&^pYEgVJD9a<n~Jgf&XW?p)gu}XaoGYu
zGs$?0?+ZYb6KKQ{fhsUHke<qc1o~{3gF)7t9Gy58)3{^*zVZgBxVqog?~I0l3lsyU
z^0REQPS75dNkO?$i}t-2_jKd~qga%oI>UP)OhcaZP@IaZc7A%T1*hWYw)5dy^$Tz~
zcq9nX92n&8d0btHPXlNRB&YH84i!{@22IGMF}aBYWv(xJd@Jwlh1)81N~D#v3D1ym
zvArFjT9{|(aFCRF=3wDX^#XEpNQ}=9L^fz80MZpyznGjl=k#E{LN@*7!)z`lhrbpx
zAY1m44d3L7aKzqBG!lwJo)n$mB?IzqiQVs4(QZmrt-9L8gh{cvvU%jceaoIsVqtRR
z54zK+WZN4GsMcFhb*6n*ihbaqw*wh=e_LL}ydec{VAsb5L@C9>?b^e6fee)@D6D(~
zdG})w=E6hSup0thff6GNe-Q%%xbDV2<Yxf_S2u`3ho>k}$vKRG7mZG5J4D&t9NZzj
z{sj`8fW{A!KLN>d6`$Ol@c4J9nLxH9E|QXjlF=F%aU~Q1QNFpp8$o1a4|_g<!Z2_h
zVGPRoPoJ8uoyEp@Ty=Cb`G!Ys^tUX}uv>;#QBN2}R;8sd+4pdtrz}J=-=CE1U)!Sg
zmCt7P^qCkLYR+x!JFOBsPCL$iAES?&$VgkbTI9T^`f@(^7F3I!)F!>)c29Q&wJlD_
z`x6MABaxfjzB3Tr901q+Zt$xcCTb3^h7V$~)Q>+zW`h-v+-G45y!t_3_EAf+pM9(p
z(iNWJWf_0pDqba)?}88D>az==i?b1i4C<VzWJ^H!XHNUMyrD-1P&REZ={|gOnS~1}
z4nE!Eh?6(QS&x8d7c}ZP;)GU96rb8OFWtcc)hUp&dw9WpX6$zU;#$GSmI=qXduxz%
z(xJqOoAYh{(EU?H_rXmdVQ5o;Yp4s#4L%UOm<*(ASPQj?Qcq-jC!Ja0ZjBV1O08*a
zdtx`7nB2FKd0$-S!CAm6rn=tP78ww9fS?pKtYRz43Rf7i)o7ke#jL)UH0vs!RL7!J
ztkgY1DQ0ph{b0dFLWgEWV;*J*@Q&7eYub^FrfghWI7IzIe^BzDFZ!*{%HC83Rk&~J
zNn)B7>McsQCsXSw_Zav&Tq-C%ZbjaFC6=^H4^7`~d3N&#%6bgnSnjS5o5fd+)Z2_I
zXSX422bBY!Ks`eyuaC5#ZCt?j`st`A3`gjI!t2|Lrl+)SS{gk94{7rbXNVzPH7Ha<
z34D{Y-ejijW<E-#(N{UBoRF{jfd}1g3r@{M<~$9guawS}q=M)oS*wDqL$j}{OYRsO
zb94!OoG<!DO~ecW+FPCzZtOEk14Gh7d(s12)8rE+t6Y|bTEm7bE@u*LZueYBiSW(P
z<dj0CkkaP5d!-ebsrZB9`x~)X^RA&FGpKy=W$lHkOB0{_XsL~LWuZ}Hw)qWZ<n6^6
zS$^x%613V7EN4OOCKl5R)okrHzV3DFb>bgJ$qQXxD-S_Lz#$*=`l=O#Bz2mA7jOPn
zrIx$!7gdYQAPm@hvLnl3k<R@H60zM<b2H2j5(IFXUn^;q-AXN#zwUfkGmfL;8d!P!
zI4zCb`GrL|b(+p+V~vrjv^dUm*qrpORm7y%=4Z*xyTrO!f+41cnV0o^q~!fD1PHXo
z>OJ3^ZX%%dUf$FBGZ)Z5qKe4s#iHZKQ<HDM<LL!2ui+LfnLOxURp2YLv7fW@`0?Bj
zrb+V3x^fUqvf>t!t@)f9Sq|&ar#D>)i8n2Z{nb>?P}}cfVB7B$tbauA=ReY1x2}BX
zeLU$Sp6;t7VZ-d4#iqj0em1uIwkf-Ed(*+DnN1T699BV81<SP+Nh2dBo)49T_F}wS
zDvw{bJuz!b)U9^$^FOO8ET}2YP~>U64D@t$^Zzks%zWi#q1f0Cl+J=b-7Vo6f2#5g
z2+kGBluL=mJxl5?VQxb)6@Ny;6Qn==HbyUaF~rDj)5}A5^PSk78K4ARPaX<O{44i-
zOKCtsNo4sQ4aBfl5v?+Z_xe)r_*1nZx$Hir^B1xP-D_@5Qd@3d=I<f9i~WIp5Ocq1
z1$`03x%Mxfk_~743u*k@*QsjN${^9;tKjCfdXf|d#{XO9G~%qv-4)&KCtGO)d*sOy
zX!f1wdW+c4s-i>GoNte(*MC1*58E5rO;5i-S3XaLE2}5b0s28mz$ZpPxd;Wnb5D^S
zY3r-BbVPzI%@414g_QjBE;`#LeXHr)w>&H_Kl*)zz!h2wfs_aTCA%2FT!JgoM*ICe
z!)#}B0N!-1F9=Y&{<B8MDA(+i`5sr!yRlDRTf1`i7;4a#MJ5Kz^1q-Hz~<ag+N1|{
zUc7q?og`9(d-eyY{+(Va$;v4gc$`g@A3&{Rn^ql0PyC{K4UunJ4&PhE%Nbi>-u4zV
zF-&)<m*ywjYj?&{2>_@Q^6xt7cM?lT;}Db`G~w_$>9%M@w{RrZ%I<s)&%1UGwmGy2
zjC3-lm4vX0m7x$90vrDmf?^@7%XMvNF+$YX?3q%ihz>|&Xe~H!pmMM&C<bhZGh$N`
z&nkSR=d*rbdeg;TtI}kyJ-pOt*>ClR?bE)KrI4W>rF7rZFa2jANO1$)LZN*I)`;z!
zUjjPj+b70}O~l0|Kl<qb$j_l=%b(8nNyNMB5p7SNR3i{pOO88ds0H?~0^{(VYB_oM
zVrz13(wX{1ucIeHx#ywf<?e;pO<u`eBHUA)k4t2vnNJ=O1o7^+oUa#Em?&5fkDBSE
zCXwf&reJ-BR?+W5Yc>G7sUg0g%z<eeE`#&K@1|nHGLnm(_YS}HbPvTg6N}WdYQdhq
z9((Hp4WP+>($2-p=Z|(HBe{9%2VQ}e^Ww)gpxrE~yC{663z`m!Rx2S0M5r2F|3lF*
z=Cc!3vcQv&=emb?=C9eCx~=OUI=B=+j{`VNfSNRV?!KW)RVYJpn_<V_t?R=;XuIn(
zpd=V&EkwP}u3^0L25vsT!T?1GNG=+pBpWp=g%@Jh13#`tyqZzP@zuqFP-Y=o?UW3D
za#;FxSLRb7k1Qo|^4LUlL^{pw`-%j#oa}KQbNU;F^;y>U#b1izWbGDeeO%-_k{;7A
zz(+MkMu@*WtmfL>T!EAf+oS3e>gx)AQJpUL&rj=sk^Ly)5cwygo|x%Wev{pfYHj-c
zmbgT@fY2DR`0dG-O)S;&@X%nc3-7~e@!TBqtuuqs@pPOg6KpziSY+2R3l%Vo?qi^Y
zmJg=rsN$v%zk7{$i=58QB9B<+%TT12Tt;kn`@i=Bl$N);qA?S#xVGW@11;;a?3K|o
zxAe2>%@w!wqxvJy;j?>Bj7*<Sj=`U=9989S(ehsEnU@?gvzr&Z$?M@^@6?^4-g-c0
zxE)PWnZD|Ggt+aWFHkvsF8x?`AO%|*Lt;$*6_fjoI9WBpWGZF_6*oGB#?%O9q<j9w
zGdBXqnMPTxjg1k*1EllW3iAV6^pA4R?#LqC$XuXk5w@ib&k!Qdvkh)n4!qrQao~)3
z+*V*b(}aA=H>J;xMd`scw<A!JkSn<I@r5OM(PumI4}z_(_3U#8vefy^)xPF8^DEvm
zVvC4fhD_gxLm+X&JsN|g10JCNnD#0iLEon}(!3dXGi{2S?dQQ`=+YBPM&{eD)#vMb
zOr5ynEqX>XRXl)u>Jp3Omr;m%u(jgkWci4i`?4VP^mX&Pz}r29$>gO=_MD3844-p*
z_`<G-Zk?=d{F`+1$HDx9X6kjU@|+csHgyLZhxsUas_&5X%%vMJ?&xDY0$+X9@U=@}
zwfp);6xMK+aT$1c_~EPMTiV2$3gNDii1&5{o6k<1x2|r>n3H(cYIyr!R1IkIN&Zkt
z7I7Rt9ngPsW_m7_K67R}6>h@x<5K5y+h-<SCZ2Es3M*bZnZyF}ub+|It^~ZZ=emWk
zw|JHiragACuPp;hSVay)PP4M!&~6M=oK(|bNwK9Zi+4@NkYt!C?_La7OgupuiQNXq
z!yucw5yvn=Lz(d$pV0U9eU1V@>8iJ1FJ2VjuA+;ZMtwPalbTYpb8#j8V9zF`WtR=I
z{*B@sx8;=_HiQ`KNu<KqR{T$Dgz2DbXz^V4z?f3xogW7}l9inp5ud-d>Ks*+M_lO_
z-K*cXoR}~sYr{)=D-hP@#oc4#-Ft81=8C%AIw7%fcc^;Vp>tS59OrIa0&YdWFjIH&
zOO4WUY}@f3xV&X(ENB>gmTP5{Gvln=4WwBe<m;FiL_#mDrN$A+E`bv6dR404PM48u
z3wX)A7+Kl|@!fg1$l55VQ;gz0Y8AZ)?a{Pz$}co|%5zy5XLuA&bjD`NVim(ouej}*
zwcU8?z1l2!v3{Ibk=VrIQ^4h|jb824vmeEKsPFH1hu_tXHN3kPXmmqvZ1tEUta2T_
znM&16;YWOZ+Go})%BpnrUFz6<MMd_NEjBYoLm{Khp8ArbQ77-m&$?hBf4p`bEnff@
z?IUgb>X!rfn0}_frX->HmXTC{FJWc9y~z}xx6Y@ujjppZ>sIWpG7o)(@=w-|_@Ct6
z0|Jql56U(Qa*}uJvtD*x#eXiYi+ydJk$5!Sb7Yd2QIz$wA^ghtyz2#X_D`Od8mUTJ
z6hlSXpZcGZNaJagRXnLFY&@QMgKokxm^X;+cvv7w^<30I7K~<6E`O+6%Di~i^G(6#
zvGDcc3TP}eG>4r#1hO7YTqft+Dt+VP>$`AqR@j@=4{TnK?b8eT<{(Ma7{=*)eS`w<
zh4kA>8TYgA2DA-)n(kp`pFD*KSDND&((in7;T~8G<PE1Q#*(?@=NS={yj8QF=MZ5m
zn_Par0si&lZP!YSGxz4>=@;Z&`I;1vWtgDzM#SW~UUdka-}={VmPxq3?9lYHyc{Nk
z++baMb%}S{)_oSDw#TBe@loZ7euky-nMcc`H^xRZ<ekQJL#oPmFm>7~l|EhwEIgKX
z4;_xDdr;OHQd&tXi;R0S=!Q)mk}n!cC}n8{?FI-%cbxdhSM@f((RIMlv~va8-1BA1
z2Yb#L=tfT6)Ky$%)blTTTl6N5Gxg3=6hxL#LtM*k!#|62DQL#u?k|FWTp1_cNgB=s
z?l8*Op|gO82bYn}XLdIGP7#D>7SdlF+-<ISIVbp~;_ITrvvkYU0t72~v}mlEw{m{b
z5=+Sj+w(|mR+W?_j$w+0uTebA*=|k6X?WLwqrCmEqj)z(+q>SWfu&?H`*9@b-iuD@
zIoD?l8WSQ%P~3T5Jf6zlU$MkorzIHg-&tB8527Tm2u_4}`|BjZ;bb=G=>wygm^vjL
zXNh(d7twP}gy)5sS+iz`xisp@LF`1&KM<Ch#H{pPr`;ILP|`}VPf|KFUq>jUTX(C1
zPqB}lk9AqpuxT#bC(IgOR4=>bTRZ!6)M;R)QO-sJleBW!$LIR>)|=xKQHQ73E_d)2
zZTsoq9=?<CxCc|8GCeeuTCF^9oiS-#=FJ%glyk5{)*BhMgKKN$=^1z1O2(OLW`nS9
zW}KG;h4!k(N);mqY7HDe4rvcX#g7Y&aaLq)+=2H4i{$%t3b>pT;>p`J1hmQu5DM>Z
zcR%<(&Kn1OCik-*liC;|c^NAw>kQF{M?d8qYiH@tieHubV}M~tLj9j%M;W_diWNAK
z;|<Gw7#ER0nkUs!*C|}b*QY!rJfIFD&hv78Iaw=C`T#~o&Z!m<;#p&iM{dfSQw{JS
zFE}moW7usk?36oy=gW6y1T%I~ZbV8j{>ju~?{t>bXMmQT`l>k;_jKIy_30q{Yl;yB
z7qS3D>+`vRFtWenhm|Qe+E9juLWIX+_3al(ZL2a1kuPAe{MaE-R}PB?p^NS31DwiU
z*hu{OEiFw>#r`sO(9bO1_FN@Ob7f`lv7;yKiFr74P&aot9RX{2LFLTT4s2|UVxR5G
z^o|+=YOd<&rsJ;EUQxm`x8(XSi`-S|18q7QodR<C*~d!e>K1|8^quAHuSs?7svJ?k
zTW#tnjXaPHYyznMuvl|-XY_NDfc|QQVtJv`_XhPdmS|O4E770UL*`49I>E3du?#Uq
zX};;6A5g|la#iTzi;Mx`nu$3f(xI2CW-)Q{>5X)Go5|8>8)~B{Jc`wI!`=5^^!0%8
z>?<h3*AY3-D(cieJ2A9mrH~ySFaWEq@3qDch*Oz4+?fi<+SVS{orc|RLjPlGj0%wt
zD`CehvcAG&qtVkYnCY(T>>1B22`g)J$r+Eq15g**U&^HL=<se#8xy15x|^=L!0o0g
zs{$9B_8y)X;|g<hE8a%js`Mv(?sxUZO^+V#%;J_K6vZ=_U;ySq_yu$BK38QJiF>qh
zAJ#PQR`kY-Y`91%sCJaTX}&sr7B%4)g0jFKPW}rqX+7@SHU6M}pNnhwuwbIOuJhd3
zI7IWcWfZY_#14q*Y``1tQl!LrzS_AcXQ-;GG>M!;yCp83&&*phveRU~$>~{?QaZRs
zK>%hY@NsabWAAbnWuRm2=s-}7p(>1n4g=yB*L>&EHa70LdrDt5q=y(yy%05tWj|W|
zIVO~ZE7-@)yiDHSVyfNpERRQ0u$hBSh^zvAS5MWWB;gT}M1V&(4+ySEYl^fZvG#!l
z&nm!a6f;(l2JYb(yYIvFRClyVcwB|v8(&%M`eaWirLP>I3=mLk+vU-L`A&1~-}Bw)
z@|EX@o#dFD@h^a|!Iv$DlRA_G0iv|%7>fh@#gw^2a2E4Y$KSq}M?`&mC6}k8h<k0<
z?enJ}$_H^I0D#y4@hK``-u3G~I`px!wr>_7uHJ7hLo+6wz4;$}KTY6X^ek~Dc=tY=
z?P%4hrWa=YJ>hkVl1IE;&nIPDI9l5o#m+d_;NJ3eAu^+Rgqz!SI{t5pIzJE27zw(+
zEb3zd27%Di>6n-@7-*_17cb!AL|P5{Q6|4>ZN;@Yg@e3vl8d58ONaBHS6&aAn27(1
z4<FHuv&vp_wG2WLivQ+!n@d$|kW}?BjwIl{1;6{4O25g$q)GJH`<}jQQYii`E~`Uj
z%d8!n*-KRhlg)0%4Ost~;wU5|${)pKnCMb|*3dF<jB^oLaleZ|$c?nSJ8o4ebk~uS
zQXx!~ioJBj$8?MnUutXc_7;DHCzrKx4;`j$O0-v#$5KhHGJ6%uTnz`MWJhJx<Q+$x
zh<%JosWAUJdLlN{&#YbOerm3#p>;&_YBGy*S_@ZFZ$!t`FE!3O)F?`S+D~cI+Gc=x
zmh!)iN>@SErZ1}PB7rNEOO&JgVGAXGW5Pa(CP`MWx>r$STyec1=z)=9(`@5PSsMww
zvK~qAzn(Wc$I`KgBr$So93A?tjrF$sgXx>47|!vbU-^Efnya=;j7Zi=AWyiXGQv8p
z75oR&VB0=0<Vyx@I)0y@<cn?>1}mHFt*_F+QXU?DCitrMKY-%Xfb55T9Lw$h%?Gt6
zyIu=WymG*pJ%%JN0=m9dhrMxs!1;I(QNS^(VORFvV5an~inpaq+NF-%*SZ|=dGK<F
z9r_)v(GT@^)vF#m$0(Al^G(_lev%0EWSQc|&iN<@1DVHOqjbLpOy>2gYj|*<$N%9p
zcrMb>NZztE=@hG}5du<CywqHDS+2rk+R}h7C_XxDsdON`Ll1Drn6HO`7YDF%9VYe&
zI~tg}pia(U#7{+{(Bkj37O6%~gr7w9U#aI%wgM!pniRdx+S?o>FEn^@_kKZM{cQC|
z+<$oQ{5W|lV+TY$KbzrW8wV?O3AJ(qdIw@ru%ZwT6ndcxa1aJ4*a4m!y)gsAhT5}q
zTP2Wr1S*<X4vbBqysWr{omBB^o5g_!EO}XoCMh^gOi<>VpI(zebNMea`l6$dZ!>eq
zaJp3M^P}I2uzF!<w{{;)(FY(1Mf7qjdi2s0DlnZf#3J$wAbw+-H<I9vVRy@&*2GS^
zhGA^O;eMjrN3wtD%7W;-?;>7G<o*L3TqOzGP%rKq$36fS1W5E63bB3=O|ej5dOtZ4
zz2!LglWN`E{WAY`GekH#Dkm<dZ!EBH8q==FDDwP+FMYi5Z+o9Do}kSDAO}v13^6J>
z5M}*?dEC*G6g@C^+r<v<LFj~UPv4nOcu^ZkCy$Je!5i@p?nW8)oFrF!(V@9;ad999
zey;E>S#F&t_-iIT2vxQbAXP$CwfJEa3tO7l0j?VJnHm#B*=fh{>H+b|DiUp497J>u
z8VdO=@qeco4IaE<rVu4bAS^r-{R4k@_kDrevLI=EN_Hm`B+Zc9yzYGPA(gMPFFMLL
zq9AC0d5cY?hXl?Wrqm`C&~$twm4KY+pBhWwp$Z$}u=~!Zq99o319@nkEye>O>^p$p
z15blqa$kj$dX0T?@2dhdpn*Jh0V^LcPpOzXl|MxGBX}dBmRY30ICl61jP+;Z^Az4-
zfy>4+W!k?D?a>gw=u7=te6#8>3+t8I@FJ;N^3wB60UQ~?e>1<|JTQOsgZ^Q)(P+?w
z1D}LRG;WMO|NRb8INsvh>wg)<hfACxiKBwWW0<vTc_nS6KTf8vs4at)Cj8;f)3`Mk
zvrWOYMtfR#aTuDr5Y`qsykZA8-|`=vb~cQAv24;W7y$1^_K?H^mGOBR4${?&Ae9x@
z*9LyW9M87i(gBZfhjnmYen-XNZD9WoU}K1bUS<?BCf)Ah&^~m&k-mwy-DJw{L^<tD
zy7(Gd;p8J(aWB=F4ks9UM>^<!^uO+x_MT<!x*I>{I?zuZ{P4R5v14^kx*tdE8+pbT
zz4QQiZn<;5f}vCYZO;qk#3<}pI#rl|`ngO0K5P2*R>@p{s{7ads2u(tYz+L7@s&Q5
z8z>^HNPo>-JT{QVXTzG0Ngw^goxl~1kT0;dZ~PbEa4~pckEGxF-`wZ=!yY~lk$edR
zzt#U4vSm?G9*jy~UH>CKWBflnT!H{zOdMYUQzc&{T6~|4hrugN3VYauc1rrcvju=s
z5><OQ$zqH60vQ0>QduL9R@Vq6^2G&;9Y=Kv1_wfxCOnL|Xx~dz7e;JfX<Of4Sv72X
z|9*6<j&bdXnK8xGL;q0pTl||M{-IY*)hg-I=Ty|#nA0e-i86n88W~Skm2*_enDmT^
z52~dUmsQv6)(fbV=dvcrKQrJn4)s*-tXZ1*dL`73dm3^z`bb^aRAVQFb~E+xv{qlE
zy>I5k>+(EpYlUl6;zHp5i;uaR5@;grSWcr{$)}2O|Mbe}C~`PPW<k#6hlvf3d+%n=
zOheOU`+|f+I7;M_RR3XQphmj%!S293m0PFD9WjzJoH@U;dJLc7G2@#QJQwzOz>5)A
z2-)O+f;uxc-9AbW?9Ta{E`YRgAn#c@by&daLl^1o7i%ZTFdsU34gcFaRBK=f9J%9<
z?ehPPx2W#>32aAkdIp8ri!c9$ufO5##lo-ZTB>38|HWE-0#WV4ew%*fhlgZ`?;M)B
zGm}Yt0p$lt&TEbMY;3zewwiL(Mcvo`U>qZicg(4tdi&V28fYM(1?yQ+(}DS<P`pu8
zL~arS5F;EwpzRtHljM(N2EeHS<E#adIVI7Qsu{3YP^bEAk5yUx{Xv!$(cNP;mM(ek
zLfgPG<%d5VZbCn6CZk`nLttd`<K6?FlFdSCXw%13)64J*hU|&-hc`OO$Rnru<>KBm
zi%*Cd5Z8OhLYW3iSP;p@hePElRRyN(buic8gM1g8p_JD=wr`V(rRD&ga4+2WH7Mr%
z3w#+t{tg=|#mHueO<J6<hk2<!MfrQC6{1ufbAiFV_ph20Xf9Mpgm^W`9QZ+pThis?
zLGlIC2?~Jvcxp_=*q9Lz+b<bLbW5OAsR4Sz2QZeQX2HcSfx%SSt7swE&cHP0pDg{!
z^NY|5C-Q$vHm{$Pz)7?rL|}8Lk1<x2VN$=VGW7~WEVF>ROcY)BA%sj&Qk(hmo-9Zr
z2{Kwm-%mPTzeTPKk~~<4^o-B%9vH;fA*U*G=H3MZK^+q?AM!Rl1%@Qhoo9eHL5Ufi
z9riP@*Osw^c59H<sJ>g8A;~EBJD@xe^XUsZ?9hSp<N3mnzoP#(GT$1nEmrkhC&rZr
z=u^(Xyp-~+<NJ^G=!ywY(!ggZh0<F$&LWtf((sqqvY#QYZ9JfU_X3Q$bH3bg&|WPL
z`JVypn&|cu6SZTDn%YVRZ2+AQ*&IJGfD8f}KzqS&<NzUW5G3y$L{I-J!uTnf#B?6N
ze@JF11AHS57g04#2R!I2>hJAD!iNuY@G8Fk!NCP+6$^yUfX;xl`z{2?hA|-Bhc&7G
z4bJ60@Vsi^)$G9a9mBaa(2Ckf@!)SOev84^+_s;DDKU(l*J{84w@_+VWa-`I9iRvT
z#1;dT;ACZmffWJSU2nFmP6B^VFQ{XBi~&x~i@`g4@2xkI0n)!S$!ijLGFAz2{%=(P
zOm{0+Qu(?x&_s+qkO;b1X_O53d#66~xoo~tDo2BFnaoMNvhY9xpnmN){CJC1&LHKh
zSJDZW2VUGK@FAdIR#svm-M+5oE$)9Hx!l-X8XEX)PN!QPwc*~dhkk#U>>k-JYZqKA
z34@QpL1UZ$Y$_mhD)49uwQ5ls%mpUNZh8`sP{Y|9Q1Y|~17LfCm%h@NB&&x1!``L2
z(%&n=fq)GiU79Zjv4o~tb_yt|@@ltFkHIr603+-F&5%B`u%3Hp(z25Og=0VZm?s9x
zpqxP$6cW9I3i$D@-(d0DH9x|UVV^Y28-Nt>{rOdb6>6(SG&0ZMO}loj5o^Ow*4^`(
z(C;H~4TY-|>jtP!PX0cLuHn^w<75G=88*njxz;u5ZP}W)-$42G=5Kxf|NepoTpNCV
z{{j~SRn;aLI%%KZn+x`5;(ImSQk8{Kfn=QGcqe^LWA>97?Aq@JuOrmbto7RdxtrJe
zrCaE69_Ngn=EkU<TbVH;>F4h4ikBwV&3N~%OS+2IoE%T$ONN$o`|{alYF}ucEX#fA
z5`1%RJWq<>XWPJss`_|v?W5a`(7VrEiGfp+|7MMEit!2gQ91(d#@c1Z-D}d_L=2_s
z`gKd|p}XVWkBAFGog=aO9<2-3ZZWYqGNQwa2R;F}Y5|o6K<v{&paN;2)bI4k?LK(Y
ze)4W!z3YSS$bQP5o!*3P=*o+A-hr;Py`!BE<?VR)3+z|UJx3hx=6|8i5OV7-Htue=
zwxBenhkML@pcYN5fgvb5PK}F($#B8n21fa9GOY$`E~U)mCzWkD(=#EKH=E8zQkzJR
zrdsMJPjAi2qGCpz+aYj0Y-f~fy?a?}tv2&<wA0I$qFTR58f^RmAc)n2M{|MX3MxJU
z68tZo&n8mkzyP9y9}Jo5cgB!b_}Qbx=|HMHm62XuS34?&Vhcqt4i<gSGHR#QQ^?lx
zxkP@_*PC31hc`{Ix}Y!!g>jI9!ayPnFylSQ?AibpVH-!F$)KJ8-lJ_9FpdZ7<O^YE
zR%m*`Fg(Mm$}J{?oh3F^8A+-Ht7k1{e6g+IS{P6c2Z`>}!H<;?r~<f7^V1V2`zzi&
zRRbQx?Rva9f$Mzk-7aM4_nZjtr~U4{nvjfv`dQQ!8<lQMEGUI1L#uV_mb)NjCj_9$
z0P15bZ>rTm9@fO#0fFDF8HykFKF#lr)3>{uS1eFcUK*`!?D7qVfJ4OopfUx<b!J3k
zpjo$;P~4eOpYguzIg5SI1GUe}oRA5C$)Vy9sIGs=?c}0|d(pg`uYVi4!`Kt$t@Rh#
zg{`<PB#%v8)|ea$*1GO^B?<(hXo{nrd{KV0A*OF}F+;mrSJY+Ckpxx90pXDc*xn7#
zQo9kbLk!_5ou^9;4EHX;-L2o|V1W3BUAQ@zK)`3Niv*(Ri=(<Whgff43S{ev>7N^)
z3LO&V-M*7qn0bFF(jO4*#7M^u$#ybtg}+E-0LWJ>x;lDxz`fTwMe*(%&a-x;sN^+7
zjnmXHR8@N*uF91!KMR93f-u0!K=H5$Ov9meUM%l^`d8AJl>ci}!wz+5#6$>0$rg_%
z=ek|u9aReKE-Vxq5G3ke)jQYv%e`h_&g9K(VY?_tjf;{l-m|2BeI8-CaN$>bvM^x3
zaRc~TG^l7PKxr+N=|}8&Gm^i6T$ZF*SFSKuWcqkRFdXlvCe9Ewmdn)C(w=Hv8*T6B
z2I!i}Kc<^KaCoCjsxvh{^61%3=!MlJi-uMgzCv8nQIPf6Ehw%3XW6;RBu3vnCM?~I
z);wMMGUhMhjHLi<2xjVy8zNqVOnNerAtAOyXKn^E4Tv?iMwX7K@zmE!Dl=zY>hAZG
zjJ2Q&2#7R`bxSD|>R8_Q|293<;=5XFsnG-PS7z)&sxpzm!3_^w<r75QkJTFxo1CzY
z$scJjsh95ITdDO?^%qY^uJXX-^!{XMh0n^t3N0e)yqt5h=GHCx_g;Xf{g#Gs`cBWk
zk~vwN;?ntJlhdUbYE_x?H}OZu?%rTLX1*S>*ST*zKJVU`(WjMiKPH$ivn?1Ixf(xL
z_4qmKT5I(j=-MBkPFES>*4gIo8JBxoUNYBtpW#E-W!Xtaew3l8?M>@*CrZgj&e$_G
zmtXp~HgaIG$-^TSZ4>4Qo9?Wd+QB=!Z<la?J<xT^$>Xwv`25rDO4Jjz31bhBJ;oJ|
z;<EApjxyLpUFXs;KA<?o86&s;a<2PDpFQ>_8p})l{KH@+jHU2u`~v+;iTKbgGCKdP
zXE_ri!yaF8f`Wq1^orlbvF|Jqj(qj1OO2_iGx3n2GdO6a80lxm#KmpT(DK?mO@F;6
zpHa^&E>5*#)?Qt=X@scXAq`77%VlO_Lfe{h`o?uoxYt{(X;3C7-!@y_d*-JTJ*Ifu
zMENqeYbBp#8WB_V4?{{Mu%zq#1&os6q%+^FIw6b9A(31;tUu9Ue4~1Kd)tPK^?By5
zRecoPv)APO(*{rae&3=>y*%sVYOlkVruSCf%eX_7A|rR^x%=04j?hwmjX&3BO$g+$
zhPp!M{Vdu!f|j`gWkHA-nP?={-#7+ca~Hr{fs%^3@vc)JtOzL-ZPv&0BIUSZ%DNiu
zr!UK4?tvI~7t0rtQVH4A2!Rx~Nc@`H`rC||b8~Y~SRbE8&tOBXGT`6RICnGf9XYB^
zf9%uCC<y&<y3py%$k9Dujo@I6f+#}?$5;&s;Pkp{j>9T-1mS+rFXiXuwnOhH51`Fg
z9eOgfR^=2h;RdfLYA>Uy;wtI*Ge(l~MvpCgZ0j2t7)YJod}h1WQpSnu+P1G=ySqm*
zLIFQ4M)Ai3E*O9~)8(9Mec&26v68^0Ka>+qqMYdOU9-mpy;ZXADm>v+@s*)|o(xHQ
z@Kl|1yW2`wilNn2q^b6lsoP3#&Z1ub;`<z{49Y7vx=XO0aJ-_6yEAU>g%=JJ5}3B_
zqn|LpGS76GKij2JWOA3_wG#^*H%C-VU%Sp|@w<&1cLxsC`pViJsMhgbfWNF@UAZ)%
zUod9YKjZyrGjU=>iA<_UgU+(bqkqF)Vkza~?Nd{~^Mx|Q$vV^AL&u5?*Oe|+gOYJQ
zL`b-Ub@s;}6_a&aAGC@6@IW+-+NrJ*v+Z5Ce8QAc$-tX)tXxc^4XqOyzML!nB4_<~
zn#aZPiE~DshJ$(e;8FA~dip~7ybb;e&Qd3~jw5R+yR$KLCn~42^VHocN%N;%WlszA
zO|Z=1cQZ$hltDX3{5;_O3S4WrxVX+?D=Srld**vmQ<5a)<O>I$=_UP*936}PU&*aK
z2e}z?Y(9dWF|7tKzw@9eleZZCLtyqT9E!{{^*flW?Lz@4^w)|^brgp4avjgcGH#z2
zPh>P3BsY+#i`+UotqTd*+SiHp%#+&W#MQZ6wU>CTI^}RS+S24)Ti0*@Q6dpFNj&#)
zmf@xG-9ZFxcyyhVuV+^}sHakZ1+#YmeC-nD(Ed!Y8#Ms_*Z}iYnjDtDofwb6mFau<
z`K#nsKRMhRbGK3d-eldq55x0zd+REE-J(IUFn7+e?a9kcwTXqdGs_Wa5Il6w$T{pE
z%iSTw+EDmhY*GA04l260BfER1|HB(gn(DM4^SM(_@3<N_$OUT29IjA+cNJ$BCYz3a
z^|CTW_uDU{>7U}UGPJNilk7)Fex)5vTPD#aCTZOQ&6N6;1S@I^&21z2`Ji(LvU~VA
z5i`h4<iL&;s^PyNHsc$nu4Y{o8<}d~9(IP`I_sMb<D`HBeU3W4-J7O#2f4i(JrV&2
zExslB{jPo7B^Blfa|z?J0(Z>q=3(!JdzO8-XX$UzqcV0Z!oL>RYo<j;(nv)~gh5Ha
zo_P$&V#S<GR}bp`nyAbU($VfL9W{cR2Rc94-|z~n#;zPl>nSOP8=6>v{v3){!a<n5
ze4&NvHMlJPy|08RLI=T!z@R&ConJ~tn2ox&AXen%?>f0{2R}rqs(mq+w7M#^f*Zkh
z%+2<0{{Uhvse*hWApO$<B^}U=Z4nYj=FUGO2D5`6?&_4NtI#a{oe~fp?P;#UJ%V9k
zAcDE{$0J+Kw97>+GinvgG^Q)iT)7!l2q<%K*!Aw)<(ZzsJ+tfE?d8QrQBQ_DYk-po
z){cU0>ufKZ{1Ov|Bq?G}r`^}7Z-cExQ?@8&2nPu~_%%Afa7_QbY?Seh97ZHFU29d7
zlKLja<Uk>Mh&&Bz7bF9f%LqrwiidYLy2&^*DmM=#);$9}^9&EgIg=&MJT6x?3$kvm
zXY2qRJRf^sAetBQb+DQCK-}U&DF66v*NW2aSaZVUPZ;whs^}%&BH5a*=J)Rbw73eV
z2qo=!&6Ll!nXRTev0w=(=BU|C!oURS&$uMZ1TDIyzI6sEi2<YBeb;Zh=#l`@^Yy=C
zdKbBf<j>U3AbbV9R}NbRAt?6vxI<s(Ro;r&lbUf0j@l557~#0W@vfOihrSgmI&j|9
zzarimv%3bNtfcdC@dUPj<=Pk6jEFbwNY8X&La*MDX?UrPk%NOw>$gOq<+cvxlSLzm
zqvs^8uiQmwK+^sjJIsi-y<vBzrR5t>hT&hZuL;e9&C#FAyNAs1Bsuucedi9|uu<%i
zyI{ct+QGDv-m$#mUX+6RXW<hw2`m~C!aDHYwM+Sl8}VqH@Tgx_9R1qPLRF&vzL?nw
zy36jxZ)qJNFRUXvI`|5u3bc4XW$#|sN2P@4+GU}W#rq&}hy_(Yuzzi=^Bo<m;~m!j
z=4z@PKCnBo^j`Rj$03S(i0Ihqa^BCo;)kN}EOnu-b|>qpw9n{&4Ts6K>oS4<(&uy?
zY6BHg5%INUENm~&{oaLGPb{94dw`87j9>>7sAzl8stzIl8OiAQuF>r?VDR2u-N}H7
z(GC(aD%&uCoj_V(V+;Xce^fMsf8PTZR53%2??fAC62{9bPG2&xUFLPIuI}s+>{%=%
zQU$ebG~fm7yfL65yZ%>m!J-xc0eDwz8b_*MY9?E^3fPPC2CRQU%On96Fz1TczXyUG
z4}SlC%axzrv8`<W!2ylc!SIj@$zL-TE*(urhi`zQjc~aGwnt^Yq%s35Q#?HV!XNKM
zyL*6LH-D72F~Nh=_l&z$E7#hHJ%0W)nzXS+&ljse+7jNoJ?-H}Y~a1CSi5<wUVAz!
zTRYz&e*S!cs&+kk%8^jtsUx!9BK6f{s-&RDw7S6~)P|uW8RrDnl3#B?cSBDR(wp>E
z)t3lQvC?aG*7d?UzDgM0Pk=Fl1;%wa*J58A<DW%y$a%av(kAkb^?qP_tg2H_+d5HS
zUbd{boWxXF$qr{|d%-z>eQr<M+J2|#`0MvpoXi_0Sfl53qZjz{6u?HUPn0r;0%6$y
zVEigvGfS&x=6tHA6xD(zL;k*>>RM8krSor?SLSFrJtCd;&PcYZ%8+PZj0NIWY_zp+
zZM0{5zie6Y7V+h}a3T@9@FJf%U7)Z!D<Q797z?$&u)PWW%<y!BL-MK{)8jN--s61Q
z%cIg#Nb+0pP3T!$mE|N?Hgop1yNlxIW*^GBb?PiqBPvq!+n5XZ=gXIAk*6as$m>wF
z<DU-|qmEthOB6KAN=M(p{okA~BN|C&Q^w2U1T&-Bjm%m^GXhwDfiYbXCuwKABy4-R
zn|(W7mvZ}i&DnMUdbZ78y;U{5qJH4KAmzB}mB#Vvl&4F7-c6SuZ-`xb$K+ggWMUsr
z8B(Xe0_|wbE}&_ZDnBRMc3S2GS@7?bDBvWEDt1?W*2k+$7cK|iA7qp?A^JQ+j|8pT
zNNG}=^1P?lobfjuX=WOskM7pi(APih%d3`O5KB5OUAxRWsPL(%uU{~f;neFOfy-HG
zy9xPC4jKFne!zpZT}KbCJx)$tYu5&ERFIEkMF^fxon*Nf?wNS-Jn^qgDZO+>H*~R~
z*fO6EuNSK);<7BQx~vbwP2T>f0kRPU>2`CuH+rq1pGveq^*hiVvEPb{bjW^_%X%8M
zN9QKzt#e~m1Z9Wo&phU*kz_DzRZS9AC&he5()HJitXy%XoxQNEEUmCyq`q@>fVx4O
zeza$#A_!aPzlSaVQrJwDC%U!xK}3r1ZS&FvYGreqA0NVe6Nay4t$mlP{c095k-PgI
z?bfu*OVm1hF=07!6mkr_-`hp_+V9+WPoj3|k$}PA!=Kegni)DikPkZ32%+meG*jqa
zn5ZnW6f$u9+%%+;!5=rDmu<cs)q8Y(Itp5qMMe7KdFp=Wg&VjYv-3FTn2O<#({me4
zy(9^2$g?ECzkZL?*YTEG(Up&9TlJ5PChD(G7eG%@!~Uah;jo!%SHc2e-hRhdr>CRn
z$D>o8NTmHwyNhbvcShPp%d2%=Gq2CoIf~6*VEJJ$&}RKsp!8R|kFh(~?XF+a1`QE#
zQQL_HJeTdr>{3aq#)AsMN~hD~%tn8(wT5=v3r!|)Crb9WJU~|do8S4{gAAAMwU;Bx
zX1z%P$3L6Dc^>!8RGn_q8+cZC4b|zYJYGQ0yTW#<2P+3eNdLP?OUUa-yjasKweWJ7
zj`pD9B{FB6tnyUvcw`WDl-7KPju)oO6}Tzx+8;L&ErRb_4a;aTzb;0TXVf|u-h1zS
zmQk@?(;B;-xmKrP!PeIOIbr_RV_bWJuBwb4$BUlk$CVcxI(FxqNVVV|u9w{NOF=91
z8M-tm=b~Vr2+OtqtvfTrQJ6b$H_s!#L~+`5?o=5@9zEI3m#PfJmzC&xUqE`G%``NQ
zJ<>lmP$)8MhbTxrTdGuiZ60~MsebxIVs-=>gBS1VAC`LPcdm=5-#%iNbe0HrUcUTp
zfN5ZjLQd!3&!2%NbJ&q|c26I7>%wLp>%8zyq~)x1wC}Y)twpdH7$%lh!$!r?n(g&+
zy=>C;1{lAHV~cKbkMbpKNtbs>-d{J_EBd*#i$+)at9B+FJ=UyNaFLyuJ9@n*+u94L
zn;&l(uBlB;T}T>M9hwtbog^H+W2vB-Y7wHHo@M9+k8R1Ia@eG>TYaYAP=JL8hxz>O
zGvQBBPTH5<U2I?3FWVXJ#Y={yWy6Fn?1m8LZ6u3TlGYauKTnT0yr-L%MNFv33D-_N
z;7SbX!mjlBW5w0?{5<AQZN<IjT`DLt?N~XB-psxtrI_@RSM{C=DBlwXg@^W*me~<3
z!}cM{$8*?adq<#}vC#Bh)?;IYNl(`>EXytjVQRL^4?3MBskl3>OPSWKhm)Km?1=mK
zyuC#xGwo&q=IqlJc9ovyJkQC6N_H8m%LTz{M+ascknwqXt;A60_tzU7yCrn<XjwiP
z%YqqJyW`)xEAMc6fsc=Gr6}rldZscXIkcgUpQW?5x4<)>C|U6wu|QHgpSkxmJ}+Af
z{T$l1as9ViuxbZ}Z1k4k)uJfI;^alTRNP1!?8Bk9Ryk4Zr!w;6zIt7oiHy8s4}?fX
zzw+&*P<AOpA99g}(<er1MhSl6TR&W_nyRhZMfDEkvL>)?TZ=;tt|SfpQrnYJO-+lv
ziYK=2V9Z$tl^<3~sLn{u6Zs)$Rc@F(1=;aGI1b)owLN937;|dQe5q5p5bj#9?rsd?
z%xm;Q!ekK}{O{Dm?(FF?J%F?JrYlST#_r<0^VDJrN6x6nQ@(TqQEFALw8;7=XL1GJ
z8QHKc5zVNHON&-!>vWs5W9II(8oSBMi}(}<@4aTB)NzNU&KtF#8iVVn&KNH@RAy;L
zk^j*+QeuxHNd?Guax!pEG^4SYh-NWknSNb<P1mVzMcSU#erTFIyg=vTuRIivXJ6Vh
z4@t^Lb=?>ikWA1dA|akvJ`+66tzfS2*8p`Xrcu5H^ge1E&s2%#|I^x+$5YvMZL26n
zkp^StA#;>ujv}*+k*Pv5XUc46D4AzMh6o{Ko@v51ZewPOjm-174d1$S-|zQ5@B9Aw
z{hr@`Zd-d_*Lj`iI@fuuwT@%i8<;hDH@N<z=H&E4?7kKf;FB8L{CCcQ3L3u#@t{PA
zJHVWawI>rY^q!w%s8PF@73*6nUhBiAl-x5JWbfoXyw|v(+;^PG_p|7oMd6eWf_0(X
zXb88g56L&<rziSCD#Y78NmteclI^XLV-b0NLCfKnyvgO~yywsT4{#TkLXK?+baYnr
zIp1fnS7?a8gVTp|s%>G+<~KpIX1Rx@>x_e5O%_%DP(fa!x8jejAu9{p&K^dZ^S}4M
zB)#}_5)jT{&RC;nSX1FSo}J&{$lF=24b^>v;Itls8A9*jWB=<-msEsFP73u@MmkB>
zt}R^_ecXl5d)kDE#chDVZ4A4JU(v5IFYLM7lN(vSfYBOuo(UUL<U2n+x+hMBzw;~c
z3Nm7pjs%HKe(rZR>UJ-Br~i>1l4AV>`TYhV<fF-llOM(ibP_Wg1`DV@UCH?>U(#hE
zNYrh40YPaNhJBUdTHvkw==8pqY?N4&R5`Mt=LLRTU{(6UW=+#Lt&90B6m73Z7wYdn
zv$2#W8HU*(kLpf$TX1%>x`L!+4<=t6(%w1iO^i?YpOEadtE7P|`pCda?#1r&p!Hc~
zXnc4_?2`-xtDd|lGo(9D*_lr7mee)PX*?YS518k@H(54Jurr%R)IL$SrMt2@C|q4r
zdM;VQjsSn)^#3}Y(hE4cv7NH5f~K0b;ITX>_CzF$*eqM%k$1&#Z^e5KXMO0|GWRP4
z{Z>{_cgts}5q;WeR<r~ofDWuRz}hd^Iy>J=(&TF?IU#N1ITkn7Ek=gD&?mAPx>-gq
zc!<lekT7OMZzOE_(2M*J))E5~p5%+s=jHP6B<!~Bm<}FqZEZj64i`TRN+7ZMwQsuh
z+fn4_Z=15*dN<|X2@8^VXPn3Wr7o4bVP$<kf4lXe2qYnWB>bPy1YBnA_R!2r1^ORO
z?GYC?MDcf;o2cml4@&(9J%P>G`4ZNzZEG2`L9qQb-Sq%}=L<1n_SCvgr}Xd{YP<U@
zt33Sci3KGWF+O+xm*cD&Lw{&ze6tpJ<(tHk+8SeX;5lKNTVsiaRL{@*Znry4#|qc~
zO2HAYj#{0P3<GY*x&MSe%RFe3gr(nZCBO4LH_EPFkVM?PQl0%+)A8}K8~dIWcNBpv
zB0<;lzqp_E7AoK#wuaQ*bpb2o75!B`<Boc)^W_!kc+wItm;D@5DgDy$XP}JY%m4Y$
z15mM!un^Mq64LN@m^=rcy(&RRz4|0}P~15iKLg$Rz-UOJZu0)W1>XCmfv@s)j8Sj+
zD}I;L;`?0T{z&LHedfj3OM16|^B6PXw?W@TQ}G2Vv{%c&=s65|Lb1sf57D0Z%2UkV
zlUy{v92a=CXiIYRxmkrp!|J@p?$*i6<{@Juzv4T`2C<?vP{hX<x{H)N)0d8?cb=67
zp_0_!`d`n+ZI-)l@Er#|5voY-ATQKNjU|dfEc7><K=|Hkzl6ljsR-?H-UQ<#^@bVo
zi~DW5$9V$Z$H0H}7V3U?+4VKTVuanfh-^1kE;QuordjU;1w+}3Un2DWiXo}giE#BZ
zCw=cHfpF5rLLh#8z>~~>vKI<L7eRxEh!+sOoAHnlWdl{)wby7*bI`b5uuHo8@lVzP
z88)e%aZ4sjjGzMiPjy}Toi6isF5eOET?VB(!v+D<%P*>Lnc1Rjk9!B5q$kDR#|PjR
z%|j5^dMyC1j1+@`7Q+f$84&1P1#!)5gfn`>By5e5)0s+$Wwwd5`L=IBQl-962ArXr
zv&$zC@(aR3f$A|rbcRdN!8of1Rm^BdNe~Ibapg{R!b^wg5-MGD4wqf@$L<cq(wFVe
z9Naw24A#<fD!M#&&=>qN@I!|k&QS3ANZZ2)67GY~>Km7?Ebk)LfF(ufAJIt4CfA~)
zYMy#3bgtv@S=Q;g;X>g(d3(og%@+@~{0z<DH}0lqD;+XV>RajuwwL8ePY?Y}vA445
z90+Tna>(1zT~E`+<w_q$7VEdnF0)3wJX$^hi;jv?fj`5OHXpWE1=aStLx>NG^anOR
z+44$PT$f~BZ7{GqmO78(W95}XM+CGF#<;hA!YB-{E)=lrM_jr$RdIT?L7fwj!@&^_
zPQH!~8=Y)42q5e^b^4j>)n@(E{7nP6d(YcuICxcGr<2#HbT7r${3xGt&@3a7j>zXW
z;2-6-H2Z`3Ld@Txg6tQv*Q8XxgnWo+^q-O6ADr{q=JT8#a!X)zV@4<X^XsGy_n&lQ
zbBb*!9kI3ua^q+yKEvNie`5a#LIFGO*fpP4?qZ^=3mcNV1xr;;HA>;zecfXYRX<XT
z^!65RAof4R^(Xb@w46IGq3lcRYI1uVVyk*=zY9#q1oa+{&edd?T`+ztd2;tOVyfT3
zF59{9<qv1e7$s=kt+73r^ZgcSD9cJ~7{Nc&5z*QNV(E-4+8?+_4Wo0%kXPBYdu1rw
z&GkEhn%(EPo8GxQ$jw&Wi{*gk1zE*^ewf;#n1pI?99&`W+mi_8j=n6A`)21gH)UC$
zui;45wJPJKR2n1w-u|x2S34P%*#+qvM7`IyxLV^1>Ns@kkPG`LXsDC$DtUy4BC6T<
z4Y|QF9~1`-RK3a`X#5)E>03)WW!mSgU_)X^Tu@)mW)W7^vVa=-5}aGL5)ipojX&Fx
zX1`pTLFK-A(D|~(95uN;a>7|x{p`W&ADaA4ZCg89Ys-<5>5ZX0o#~RC;Vy>>wcB0p
zRp2B3kRag+gWKde2kS`_Pg)Zt&+|}JU<b+o;v9e%VgNbB2GA=30T7Fj3P5Z`W@f2Y
zxF!jVV|j$D|5pxhCK`Sa234B<Y~WoH-J5y&L89?MNXSNWE5uG~^G6T7h~^*4`$x%^
zF8f%{AByNuxs@-)Or(JfR|Wl;!U7b8wu&eyexb%b7+|j9$c#{gg}geO0!4~3Pb@96
zzXn@X5iqowF45J)Pb=`u`RNzt<DT%S%`1eRC<!Ep1y(Q(!Vsu;9FMi9&Ig&EhA0K-
zA3#19G4F%W?-3;dLT6-bg3MdEEI%&A|Nfbs36UKF^+nc{92r`5Y)m>Q=oUf87uaO`
z?BZbICyijug@_J~gm<!6UEVW*XL+sWA$3m3tFR7#r;J+3^MVnIsL+(>;02Y9)x!n*
z7ja@al`CC#h)+naK}E^ivO4yTe5$AB<zCu6EGjV*;JxSQL+?ZHcNIBxoeAxJ7ZFk#
z-UfmnklDRySP>p~IuH-tGX(rw=|O{W7uW!|@dLP<-;;sYya1#ywix!OE@wW11X2!r
z9pr|Ikf_vp)>0TX@Io`YAv^|%AV0F3O==CE`O3ps2MjCg@GCNl8pX~V)e^)d4joo{
zVMZmqoyN9lZT`sc4=CIK2m52pQ2X_q_0RFjgpzHrBA&+^iYn55*Bh5;pYQL%iTE8n
z@2(!>Z-v*ew?dFF!}IxW<u2X+_b_l8RMF#fJ@Y=*l(ft5h^IGlE$A_EI1pu6PsxMK
zFbh$cod+ATL*t+Sct8B=Dr$ozrB6$mj_tTSHj+C9($Ef!DaI9N%<iE|kYh>c!w60x
z%#Gh|n3``<MRHN^Vd$@hpCir|-R64smCY7@#8gtVgM-CXf~AX#D|wI)r$-l>J4gJ>
z1$b$QSOgofP$=o5wjW3nn1C~=Mq#K5v_~j#B&ICfig|lQ<#7ZYMt4~5zE<W^SdD+L
z1fokd0WE>J_be?GSfQ9!jbJ7vAd<Z4e#(lh$fn$j1Is&bWSPr~_?I+nL#-n3X(*1d
z0hE&uDz=BrU^||NMB}k)T*H?0R`AjaK$%M4-s@tQ^fB&Eo>_C#bahU6$o$2!kRfBf
zos5jrucS5g5BoGh8p#ng7I?cKuGM}6MGc}#clpB!xnfqJ>9YW}CyW^mI4SNASE_$*
z=fQr1(uj~rcQ)&so0zGozk7s)0ji7%nLuPSM_9UXjd>3b%=1B8Km9Ps?E_Qa`+#8g
z7$X{lARx^KMLFUC%!2QLxZy33k-x%SA+awHRNw_pgrNJ;cP|-{noWx<6c$cm8?w<%
zh<+3(F$yqSFiDEjLAgxaP?V2GXM%21r9;^1O&CZ%_69<V``EByFJj@%_GM$tfD!5q
zAEDjz{{kwz1fe>xCwHF%pB*t9SqmEPzcLF7;27O${T}{pI{?OHyT}>dq;xxniKG$S
zQuw!s2*k^P9u-8@EN)L@fX7A#d}IVWAwx&ltyhEceKkCehrqYP-{}cQs7OA=(BjmC
zB*T0-ky&6kv(DSW``I*HjM-(_URf0sCWtlzNaP6hXx#ZU=<I=f8x}ZrxBU^(pSIa>
zKZK%;sAkoy>|h9tP`+r2Hvq_x49x5_(Ay%ie3(QE;GQw&+RDoIvh@^~iGcj{mwMRJ
zQo@fw3Xn=X_;=H!j4g*5-}rndDllm#%w%otN~fRSiwt5Z^!B&tXr^_`V>Knhdx%t1
z4oFOh8ta=u>95^8no5DU<3eIV6*|A?@?InP{)D9yGU{6VoyTipqdzF{h02e66MNI7
z!cn|`Cft}VRc}4YJ|9Tgw}%aH+{mTTX}#Pr)cgDF{C-+fQYXSW|A&Xmf)oJ4Fzi0>
zcyFCac03rq|54>5yK6?;LK|jlTFw<RtWcQvi)j8heG3EJt;0%5$iPb#aA;RVrDT7h
zqxbizh}FbQ(uSvRS&Zo(7v?<xGYXEH`i-z!)<PX%rYks{EB8YM@MkaBp#z&zO`$k)
zWR<)y-eXL}E-m~&EMC|A$r=)P#-V#V!Q$H%!U==w!5bPX#6=<`G*C=m2Wc?4_!KCG
z3y($cy1w4HCvOl&2uJDbV$5ydGf9xMd<ow6L^Y%k?@Lqsn0xg-l3U<eVdhJD=9mWv
zeI5Py3Lw~6sC?<Qkl(0$Pk4!B@ol2?2~|Jm*Wf<So}cvke3BBGOycF^>%4gP6)B|t
zoHjfze{kFXWrW0iL_Y?m_MGkyQId>4$+}do%Exkpcgr<_^(qOBEBToZ@N?;HL_2*s
z`;r@f=Bp6#N6%p<g4yB`6F7DVQ3Bq@?%bCrw@IP^<P$G>w~n5QBT=2w4SU7aP<t10
z(ZI^(gu~)C-w_--O*smrp@c0t*Mo~D;=p+;$m!qRFspWGIqQzyMU5vP?x6_cnEDPc
z@Q&D>(5({>7Nn^<gA9KgY8H4Y6oUlFjUb5Oce^|=mfD(0A30#e(88x1vGYzE7>$zW
zQ~?^id~yWaF7WR&0;#LoG<=_>+5HT^jw|UimxcVWLta9JUyZPP|L-SR(TQ!0_Loe+
zJm7y6hgU)Nf_L@xramJa@*me*crMR72m}s4P(8X!6g}Hy6!~X@fr@)ohXe!mdndfk
zZ~zhY<&$0Jl+PrEzrN$d(MdB+Ty{1{Mjl_N!}}dD5lJPrz<Gz6KfK#muCZL)SdJCC
zc^2u=5_h|xQ6m5Jang^E@bD?|u4X6z@96$5IbLS6&ynlGiP8prf`9KEL|-Q)!Jb)7
zuVdAY_<DqsIZ?#*1YtD-cilcjVQN~efdy00Byga4M7zC6c{mOqfNf6VO%nx31Fznf
z!8hrdzR#$MLSteH#_(1xvq{%`mcph}u^%&_Rcri<X9ebiUs<xV{9-d|o!sS`KOk5$
zX+OYaZhSR-B0(!f&{{LCpe(zyKSAJXT?JK5gMgsL{ew2DC{zwruvMO<!tku_1<#e`
zuAZ%PJgQ1o+7UYk2lWHp)G@}jDCFwM?e<lZ!|n|3@5<k>c9SL;1?Y&X(!;pXzSHk6
zq1jT40#Bz9X7Mx6PN6$kp~rNRO~4smx8{}(3k0S|zO@OVc>CY3jc(J)$Fy&EY@1{m
zO$lCaz5akwp36c$BRaQtzh<v$yzc)I<yy^BuQ@5w3EK4a6s$SbCQG2EaXUmWR8Ur5
z7iaRrQJ5hC$9ZqD*Y%cO@rDvc65qAcklo5J^u_bkS$vLXkSN6qSP}A3)b*UN4`RIg
zXr;GL?4k)N_7@p;oMmF<Tg*v9g%psnU`J}863&dMyO&bD=ucgOQ|mULIQ%t8B0@XD
zdKC{`cZMutX_8Mp6W@Ea(gp&=0CMi;?Xae<voC3nYzaaAk4{obS?zZ8Ni4N~A>rvo
z;1?19no~3l8K5Z;U`hhgl?VR{cl!VeVUg_)(9j)i^k=v21zdBjxP^x*FDKgQ`|u2B
zNs{ZDf8#Ctbgr&T?}}%MiKDYRR60vyW|u9vbG|1)6en1M+LKpM+MX1#=wNwZ-XUF=
zzHeIkNm`<S;3LFuhTOfs`{HxH=L<gYGpwtb-JvdfAcjh-5Z)8c3fDJOI9u7O;31{#
z=B9rj6TpjNs+U+m|B@Jr-d^1Dh&5wu_<U067J<vpX%_39&3>}kB8P68YIup}yqHbX
zDN(0u%S&8+-oDFT=TY7L-1LCQqh(KjcWBLN&PEHA#JnH74R!x2oDSqClOkH8-5g@c
z=Q|A_e!hpw0xeXkDSG-cyw4t1x2s4sK&8WLGR^9BG)xo&Xmc(?91!tWoHNUfRzK-Q
zuYMMpE#d+BXDRlaH`dmUnmok&Me1`QqNRVNOw35J8(B(JG2p=%zygSN7?G>MSsh@3
z#vqM(l5kv2&6nR(=P-u8xfl}#u!~#Tq9qK12xycOguDfOApq?nB4GfC@*hD%0EG7R
zkxifvoQYYCK9{Euf0as6W6~2i|K54i^i*lfvhvLJH;w0JN73MZK+6+nms)NKK+d@k
zqL4$^kJ<(nL{K%||AY1rfrW6C--*#A722c;^&l#=$Rs8;M)Lc30k#VzGh|qV^$aQ}
z5Sk)s28t4P<$qc`Ai)I^E`jKm%tbfU@-POD6$FzY8mR+$B*cN(Nf_dd_RFbroJ^q^
zzybiS-Baj#gdlhToh1+|sX-W$3EfxjMhq}6E$#Z!*xgy=mGta)Cjo+LyIBLU#PNlm
zd++@;ozESOG9NPRE{-{rZ7m9p1S$tKGm!`8?Tec{jyG>2`b<W-Bs(tXIH8CiCtHSa
z$3US3s@BO6ZXSI%ZXf#YBV#942qQ|eme4Rly4oO(EuvtFm<KldVN?9*<KhoDE^NCG
z?FhIa1lr{^CYid>67dwW2HD|_@2)p!2}DkGFlRLv#?ko606W7@zUaRYb7aE#0nVN=
zfirv`62Tzcffv>{&v%ON=nyET&&>X`WNaK;6P@B%{q<w>8U$TjP=v08IPo!Nx3Cf1
zu>Zaj1yI_N2m-9h7(?3#EFh%G1Ry?SW&xi@;S5@={g}P}c^c&^dUCPJJ)?x9PDxLB
zi-2c;Yx5Tu(AWLx!A-F1M)+T~Kf9v?Ms)Cl|5XCLq3$IQy(FV14OoT<=n2Do#!4q<
znv1`}%Q-;w!(1tw;3UBOq;}dZ4M2~QVJCRd(5}b?8F-Ys!58B}LnAwyc;IjOa2;C{
z;3;TS+1#FHN6*{7oqzPZ^i<&xdn$oST3%?;$>Sif#k;SJ%Tkh7ap5UK#LG?MU2!$J
zq;Air6+}fYVCNtdWdi9{*nsyt0QLp3I$;TfXj@EoviI=Fysb@rxdeVi;U-O~rw3KC
z^-liF7S1styM2j*jk)e}_&uQ=FQmihFGwmQZB#^b=WVl!3jDd7!JZ~~aW6^1aG}%G
zt!9U6?8-}8LjFYLK$~>tDtgq$m`VK_L4eGtPxBkknXwCq{s_AiHa1yu(xn$|ghXga
z`xxf9Pj{5z=tO$9AiYr_qQ|n{HJ?mVW{?4@rU^`UEkQ-jz(j3;EsAjUwb6s4!I^tR
zrm*awHx7Taln(y@G&FIxG0&TROCt<=GDQiMe)H9vn`<(+&$D;8`><i6x2k9N^)l;f
zO0q&oNdrUsfKmSBC3=<hW8TDgQQyfB(HRGA5NPh1U^^o5Genz+O94#QEJUxHCWmg^
zy8<u~QO+rQgg@JIm*oWyq8Y9m!vh_TIFJ@arTUW*6Pu2n##Xcy;mbNX9a2f}rgg(S
z+Gy=BO&pLKZ*tjP_01nJdVi)+%?fAn1b4^PE|~isn2I9IZh4SGl2IP00W_f>LIgnn
z;Yn?}#fxm(29iR^aV2y&Ectex4mQ>FT?EL<kiJw9>LXc6fWsh=^Zh3>>3V>ku3$wp
zE1(34hR#Ao$!t2qr7k%kqBJ=ivFX7j8Hleycv|2F+tfn<uZ$zYk&1B0Z*+}0p5gxB
zfhJ-U2OzcCZ}?=`5bP)76<2d~$+UBV(B&9<6}`(W9ys;FHeIAY71Hww=_3Vye+68_
z@CbsU90l4L5zz$<4sdY0K4-t(ynq|Aw<02xC&mBF;_}FkIn=FP=+|Wu8AQ8@$VGqN
z!iT6aOhzzj>mvYhXevNtSl@0;wA!Z0L=9@0CrIZaHElJdHBUEa8#aexk#H11!N^l>
zi1K#R7ays(RWX4*Cc}_J_qiMP+0oEz%1P1_7x{6!jH7AS2*`h&uwDTdV=h8AgcOpq
zIGR}3>o>#sZb3w0Ut_!SXgb~qq9;3Ii%_J;1s);Ue`xOuMIrx761jAdL<Z8~VE7I$
zJA^(7^bbNs@0KQA$ZS&#f$ly}G$;8tTMO25(VLDg5Pd@o*i^Bhy7KEFOG3MQba8?A
z%{JM;C6DT(AXb{xn=A424Pnpmh-Xc@fvKsiT=$`4*9G93AzlP&lLRdk9)rp!uaPAp
zX)jTk5*s8wEF^w`kH>jX$g|4#G=7``AQgI9!aD{n+;6Uui;jqMt^}=-6iRe4Oe%58
z{OR|0uM)2Is*$)ZWY=pUalg#b#rXBBVMY4HG7&QzyU*?#vluD1BPa}CNakVrHQ~w>
zMpcU)5;)@wkq%P-P}mUW)taq;kWvk0azK)8NQ-epKa0Gv4gs2P1or=J(yuYbrB{oL
zD<ssG9sHum#oeqX(OY5!ad6*((75?ivs8EWa9)Ldli|rDhKI3_h;a2C<<m!jo7hF{
z=Bf46G$M`&y9FDB7x)je4@sxP{=?D6zWEbTkR><~X;IoAOW{M)jbH|RhJOT%IEEAF
zIb3I7oQ<DlMdy4c2~$5nAEX$!FqaJ&mF?di8Flq_pq?h9)_!sfh*r4(-;)UoA^$}Q
zTLWnbhp2J3%CRh!BlY%NPeZ%u8@>Vq0}o&5u{eK9@+!X6pC;X$&Wok=f_=VAu}J48
zI2Y|c5+E&nPOSms(H|_avY+H)m&Z{N!qY|8CYFk}i|99@N*IxZax*)xEc6Qdr&}Ku
zI-+SqL_5+1y9PHDxlI-8^$XfR;Jp<8{g7njs8b}r(8+{%H>FRKf-5?bqS2H!`(Nuh
z_{=&sR6UYoVzoA93c<*^5JJr`6KEC2SjHs=S%q7M)zplM6J+P9%WO|KWOST3y6T13
zm84kM>_NPeuaEg&&--q4-0uFHWQYxgZZY1KWYw*9<VJtKr27WAk9fC}XSBi|<NXfy
zJa3GFdQ$*D<XV_7;tK&*0*Ns#;_Evg-ac`!j&L>Y=2#K>fD{4Wgb>i#y@5Cvxk5Po
zcQT^7ZW{$I+7d^xz*cD_j$i`5*5@C`mnF-*=PP_kVQ6?#V}11B@3`vyiS=9WpRvAN
z!J7)8i{^YP^4r^j<+M^uieVydgjbLc`?@k56^lv(2`txS_HWwEuRC0>5d8a%Z2Gn8
zHfrYWHDs|uw-l2>f(1n*P1wtLm8lAntS8<;R*4({JGhTeb17k<x4(7OchpD9J-u58
z>*#R-d5Aa5_;Fi4QuN=@NQnn&!sK`XTN!~=cr=hc8E`BWVkE#c@GK!PP$|xnTq=C^
zr_u2bs<_A3&|2q;XFA|;4iP}|`N(f-i%#lSs{8PiLLEl8FLlidsk4;);ral7=CHja
zS8|#M@Of-q_;~UQ<K^Uq<~-A2H}+<F^w;xUDn;VFwk>6iG53?x6Q+J4um3{lFBYQw
z?0>54Sp9c&4!wR7kPe=I0eDW8HnjAqJ!();8)2`BlW*5t>`s2=Yw&L0W;>i4y*6h$
z&$bj&s1g8$T)daT!0?xSlj(OfqYV2R)yCDj{atuozVaLpPJsiE1#R6wK~jX1Y!#_-
z;oVbsFG(4IH2uZ?Bqif72c|l)HYl~^Q7fkqkb*IIt>0LiBR-4p@gaeZ#7YR%g}e^1
z!ky6<@TA^AO$+a><hhZ({+9f@GIp{<*In4B=kGG?gWS-IV&z`}rGImhEE%9UM8>}e
ziuD4>%G|z+REeHj3%O2e2~Z6cGtLID8M0kW+LPj6*^Y>k^NTT77BAKoSop$dwQ`Vc
zxsSYRUkO$22Nq@09R=BPQ`j^GwK1_ujh!tcg>-2)@jx7P(@Ofv((USrpE3$+tXBCS
zzYKA5EZfA+xnO*XEUMGX{H`}!@-5~Ip!-4>8Zss9ex-Gf*53<YCA^8eNtmW~CdbDA
zt(TB(=<LXyHGo&U>sFgpeBEJV%sVF{L5nf!y04#$*C!&<uZzE1sc+Rm+B+(7K8<SE
zGr3xzL7k~<L9A{yHZ#hpn}c&3D65w~M7d4VUUrPzI;^4<v5JX%X?x%F`AO4T?vH6+
zfB*93c515sL)EIv#em-rrbJ~g>tqE!Gt&`^H`d~Klj22l7hmB%e?bpHTmQMiV|2Ps
z$#a8aCAh|=ip~7#wLQLJd$J&6O3KmvIoCtO>szhW+uH}8);KqmbC(#W#P-C6H>k$_
zeV*ZpJ@%oH>ddw!9(`k;mc#w=wiY^d^W4sEva{cc@A{<lJWMkYR={ptFos={Mp?_b
z%F`&%JfR&^`Ak%yHTh#FRw<zUVy4U=X@Wz3e_8GGBHW$yS0mc^s>|y8CVsSD^Cj}u
zp(1}kF9|fpM=>&{0qTDCf%WOHGd)*)D<t@6&q<1JsRm=}9n0-=nB(eHm|O#2@ta2C
zSc#MZCRd)-%oO}lY*CDEkI0i3WMO-%-3uf0Ry6g;>YiS%xlwuH`gc;=M0Vv#a)Ty^
z7}=$<>*A7A<gY&VKDnlFP3bwI-J%D$3>mg|>Jgf`u&1LK=qmU2g<Kdt)^CN)10L-I
z;{eTt@Xw4t_Z40#6yj**jGzBD?ElV!me|{A4f9`tOSlyzKD3|iuIR;dN<5688PlKM
z<3F^tNwd#MPWw5$(_>)iM^B;_Hc>Lgc4H>SMU`?&r+~eIxMVbjDxXs^tX@|`FJgyo
zx%o!Ua9^_152vvrcU^*5Bk4jRAgMB`pGjj}Ph}KVf0wN_#9F0Az~lDCqEP~$@};V8
zEIkHy)@b}z2KfmM4*NH1X7Oa{PNECcacUIxb=nu90eSjQsw>Dl)SF>x%AK9%4JjD9
zPa-XeOpxE5upNz!<OM77*nZtaRPhaUi$!<gN^BV^_UoC#_5)+Jcy2a%!&|x?gV$fJ
zON}_xu(0!e&klh_oZCMoTALtax}9X?5}`W7joxz#+6pE3%5}+i@AEO9go;SWRZ=*v
zkKBrKE1O7;j1l`1K}7e|f9C=LgM=b!tC~r?X8YmsX_b9Dp(zpOl{*ghhJ)W3&^~dr
zhh%)T%95KU)#n~;AM)bw#GbZOtQ6CgEfsGj5MpSd;q4ooa6TJ^l2}<{b(aWETHYGc
z4;w+%ZEv2D&SqzP`kFy6w^Zq=IbXlM&#OkqNn~{?ovt-X&{epiEobg1@}9g_Lh%Xg
zk_^A-hP+J_yPAI4?AaRvS{XW%=-}^$IfOMIDb7jOcCK$f{XyYPEV)@hZ_%bwt`gSk
zs+%qRJ?5%<LPph=yi42hF_pCI`%Q&7n^^ufTaix>tr9+|#oYn(Ayv@7F{+yXd^3~*
zjTfXgY<{`IN#wxXU=t7iA!%myc-%wc%f5Tp(z|X*!)zRM+=&{!8VLJj71<F?J|w8;
zSS_N}+uaj}Obw*QgoXJ8I+0IYMBgtl)Rb!!8ALwqHSY?hs`yDeeSn!-98<47Xl1I!
z<xQ@Lli1o4kOi~aM5u=(_C;Z;>GqBA@W_qJ*jKB^u9a>}A{(<i@E8{#DplU(+<6!T
z@?jV{<oV;P<<OXWFnwAaO6ud|XPC<#hSg*?-eEw-u)0jN`t5<f_q!r%*Gk974zEq}
z%wL<x1pSQ3X#dR8JkHGlw$_$^cIr5`U-9J<{1G+keXY|{o^RnckEte@6l2N%gc;es
z%W(^u;luk?$<7~(H6giHy3P=zw|xzUq*%rLhGj~{7(R>64}@>|2XhnFM0?MRi_yyS
zy{5kt=D~oDKod}>HxtaU1iUNpul%;dH?wIeX@Lpqi&G~nY+VU3wkIBw`NHN?P(bkB
zyo6$Y4kKchz`}=O?B+TB#Fg(0LxTdHol=Nc_NBc5GsI<G++r_`WyVyGF*J|gYKRg4
zp++8T+VqNqsgCh<#_2th5M6e3ELBn^%M)VB*Yr5$Fnf9Ch#iZFE=wU~BXcCOcvOx?
zFoRWM<z!e4d(*)Jw4WT@&1fMqcIA7?@|Jab&pvcmTn;RPp?>_99|d)zu;-E}YhxHJ
zjM2QX+*7BDyFy#yv0T)Rm4)-iuuluOB^!R&ayfQx>w=px*xrrt=fkJ;7M=H|5jwn-
z_2l<SKYEOQWQw5J<^7M`3bMRCW?&59E@Z;Z1Mb7piQ+yil40jCV&k~-L(jJAx}}V2
z98I15z}D@MV|XXNvQ*Hiw$}`;5EQN(VEdT2#QW%I8VbI<MAG8#Y@Wq;dG1X^E3~Ad
zX13YVNf}ciRk+dVoG2unaZ@RFhAW)!I`Qvzu~L{LH|3KRgtnAYVe@XoAGY&q$Ex_O
z>%8E(UY>ILJSQF3!jI8M=bt__V%icX<VPMsR&sIZ5kqvl3p?v~;d|g%G-oo5!Hmh@
zlV3s%cdD9In`U}8((bff0I7G-%9&&ed%o8+C-6>U&%LPOVyY8|6{(_VsWoLLT7CVL
zDf)*0dcDdBDRxLBjCZd`iA9MqSHgIiS5mpmv@wI?dd3{L-1*a-PcCI;5S9$yj05{}
zSXT%(s-Z2Vn%Epz+i=3O!`1I^ox{WP<a46G6Ct9L%p7VgIoeeiARm8McxdRfWUUgx
zj-?G7+^V?X>*772+Sb2yaC@Pbts|jtBNrd@j5Nwjt3oDHu*p$rxfO@AmaGcgkhpS}
zlok&Uuk1AVp3sfA;aq4NRB;G$&5eCq!c{8{G+UiTS_EtO&A!}K1xYQ_ezFRBA}LRb
z?n#2myweS|y728sANa-zT$WbKvOdUth)H^Q^u0F2pZDb=Wo>?b+TfH7=^}4`L5{sz
zgOn=Z8#3Zd24SHuZmPj2E@h7S(vM|$>v`^;<uD^NySJf>z+*hT;msgt$;CxGQM}FF
z&Qx7iG@Mpz71g7&dui!$$WhkGqH=a;t~{$=876cg3*qC!*S=U`-jHMI>h}B%ge>2~
z(1m$WH$FV+GqB8rW6ojm)$|M<cN=n=M59W}IxEPNkl(}cN7vQ2{3AUr<m~0(KAX?m
zpQ}fwry+5U48=yKntp3jFYUw?5#$-SBt~w0uya~Wqnf_xQv6}gxI3)&^^!+nI85B&
z?(f|>{EFJy&lt=(BtXE!8{K|IzxD2rDA$G~1;*39o<wCQXU$uRJiv~gfsM&v;KCiA
z#^inHE?Y_T`{RREreluY?%UtBl9R6>upSSudWA@GaiKy67ZR%~cf~I|5xk{`++9hH
zNZF+qQRlL-41&pp7f`8i`O$10r$m|uOWEm0e&Q=T6%Zc51>mpToX6(#xX;Zq3VNze
z+6&Pvn3dm`gNcj2NoBUQnC(fh)4F1voJ{@i4XKZAcqJJ%?@T}c{FtL2)!?bku&<dD
zUH96XTil{e_M2@t@*eK)4m*iUT>rad&Jz#3hllKg%|%`a<q25dRGZ$qA|6}c8PmQb
z^315{XntNi`u@^RPo0ndrZ!{<@bF%C`i-4l4K+N7E)~qpL`<!ue`Yuu<IWSD#$xKG
zBH~1AlcleuS!I6mBKE>P<(<7xN8iKipz~xy*NFA~;YHOdCd_H6f-&Wn<b6;dquZ(w
z-E|Y+&r7^nCX98qAF<acnfrcha{Eh?aHT_S-}E$~c$k!z2g?daPe~_G(m8j^@VV&K
z7v(P>y3M-tgdfB+8UF0r{T|Z3GFOsgHkNnd#L@GbTToFBL75$y(?36K2zI)546+Aw
zRdh+BgkP-O^e?WmCrUh=!HAQ~qvZN}i;CyE+uHk_=Df~oc=$Y&h8fEq8M+;dF<jZ%
zL84aJKJ<H9VQy}Ds(nqoS*{Pb7e2ZM%AXTrUhKWhd1YUr1~X~*A#;-V)J*T?oHfQU
zr!A|h_Y`aIBzh;-?4hF|GLYb9i@&SIov2Zh6SEn$l%eD(-EL+&u;SQbo7Fp=D%54S
zH>5Q<TKjWH*gBgtRczAjBuis*@w?3(m%qdKHC-ObcXMhXI$9#;l4fUL^8PP-%8E-n
zAAdV1f9UN9nH9_`?)-DHdZDrJiRmhRm+cJGpyx14Lwc~xpz8h<MvKEa<YyUfk7ihr
zCkYB9(wfB;kEX|vqxjs>Y;W_PlPrDkBI=T+s?*Q|aq<Y=aM-1s0(~@&&4aZgn(N7@
zeyTUUKmGt!Y9%0`|0#n=!f{7W#wJ#8J1a1rN2~j1X>WU97WV!ztNqVWn`fVk7@*AZ
z_TPB!t>%kMoDz&&EY1J;>0^NWTA5)*I6Wu8_am$PB0+KK$SP|O$2m%Vmbkppm3CpN
zQN<N19K_${5VK4XOSI|mZ%K2?9=4six*%TiN}hyT)F467{O5gXm&ug+a#$7kVkZeX
zYIO&P;v^6<c<}ZY0~$`wf_f6EBP$MXN(?IC8#>cc77er4=qBR9!(1j@9XZe5e5rWh
zi_Bohqm_%_LX*>W*Cu-$H$Gv~H?%V6W_7aXcrv-^a#x+t-n^mxY{=`u$JFX^a{m?C
zMVhMViJC+WEe+|I#y*e1WcnP37>A?X`O9#)iGsSQSF6CYn9$A!BOvTHF1j%0@tH0w
z=lvGv*n94hoU9L7Uz9EqJ+l}xA4E-EF~?1PHte~^v)3bSWhkh+5m#7y=GFA!Qp{lQ
z`a!MJ$q~NIT0*Q|Be^&#82}6dOpYe+k+D6Sk!5Sb&(*!cRF1*Aoi~_Q#^tNM14|!g
zZqL1pcu<iUP`ZQ)HZc3_rl{dkT2iCfYwC1=NU+V}cm9Yt`KaXS6+u6<!#F2Vk$P*F
z^ik!ZtvZ=#x07SMo66l@T1V~!h4SOT3DUiXJ2bcP|I}wg17_iSsQa)w@0w&*iOfBS
zw@#5_4<G#<(vRoJkcx;5iN<q2@i-Z7R74S*irXxu#s}<D%Nx452rYc{j4bV`o-a7|
z-D7-rw^Oq?EiG!(qc)g|cRp>?CSe9nN{^kg!0)VI4G$I=6KBMv7shU?PrUNb*x4Cc
zS8jB5-G3I|=i6W6KOQ_73ujV-hJk@+x0+r}i|sLV+{B1DO2Usnwkp3;tGbE2n#Eu5
zvud{9XM<F<4mIuCk7kJWS}Ah5l_ITs)_KttTM%e~y9sYZY$RxMw5APWZynW3iROP+
zE8Y@2)mAMVI*g;)g+FIn-{&vSd?FaFX@jhynMd0DF|$u@qkG#fu1i?X;=}nWjlLSc
za~`VF++qUjD}BKZ<3pE)U3MrO4>}}G^WJ4xm(|*D^%glyHJi=uz4uWz5SMAJvq}%G
zvxc*oN_buRQm^CE`+ZZV4mUQ#_k!Y{2d0N2Kk4{8z!WsJYF=$>%pYh<%^PI?c{cN5
ziDxesGuHUNJ?k}3-wD^|SNXyOI{c_$J#>k*>BFaIW?ohLa@o5Z%Rkm=CB9P*aQN?W
z!;~OGVRZOadvQdUdorgvAp7G=Vt7UVi>s?jeIyR^_Z#u{v0iF-E=^tn>${?%wJ%(=
z@mqLMugv_V+}g6SM;Zb+Qp?2k?wR!FcjIs`?o02CCd^(SiQ2Cs=_<H$WnC#2wb+gv
ziNQ<7>M)hu7<TI_<*>AA-88xqldO%>o*%?H4>OAH3KIx@y@AwL@bH54-g#GB&)k%T
z&x3gOmp$K#W9`hYmvX76jAOK)XY}30k)lxXkHd0H8g-I39_2{}BHGB&(wVWVxo*BM
z?+W%yO+8=y{;MLmy@x3DuY!aMa7cjWQo3ZAte#!#Za67Yqh^!&VD3RzMkOOWQ2=s{
zLzfia7jVrg4yUeBG2ClKZ=8buB!lq4Zk%BtAEtf$1hUWhve}$`@3o_(v$e}5vs>B2
zWvB8^`|mIC_Y$`R{flkcD5D_-k&UDVc--F>n2`KEMZ@Ki>5Bk!*4XI&9vy|9By5jO
z#Y|#fH0`L1ITY7=bZiizTD`;^;pfEm<k^)S9G~9rjR5W#l7mZmtpiw>HiylY_qKsC
zXCAs`u(oAKL&SgHRrNe%J&?eN2XrU-6Gcc$4)7Zp;6;)x{UGj|EyuM*Z^Sj!l(tWM
z+f_}j?r`?F%yS872;%g#{W#C|wjpoz#ZmRs`G?O<w+4kdII~m7Fzlj`3<a>o5MP~X
zq#i`sy%EC<7@O?_MFx9x20Mg)j7S*DH=%vx^RDs#_7-heF|ww?Z8kS^rfoc~`8qXc
zKh`<DpucWAaT-q5U-scwvT25gWa$KxQZPeRd*+%$yurA2?d;Zp`A!Kf?5Ak?=^Bcd
zVo}}nq7OOOE&Y)!41XI(-?LR#zJ&;S2(0k`KHp6b?{^*~M%S0dG?u?U8I`8B;vBQS
zi4t;)6Su%!zmjWnI1p`Hrf$wLJM+v##N+3t>F(_OpG!}+^cHJp=V_<gul0yzHntxW
z%pDV}{VD}MOvI)WFtaee%hY}d<|6fX8gF8uqp2iqKea(aPW@(Lv{dsQm6G7x*&~~T
zC3@f8*siME&DNu5-;+76S5@W}ZxNyfzi`;?7ZOHgn`(#}J6-=RI2}D@Q#byWcB@-L
zi+k56%+e!DB4xVZs}v*=SVQdHW8Qfq!7Lu$wQtLR7_OJjdj-Ev6oLbKeKC9g&}{|F
zlB^I|hXo+Bo4UriTU`?vB8ZabJ{78J-==CV+#&C`3GFW&ulGK<l2O@w$KkmRQ?Eu(
zx8EdB!NKS1BxDkPjml)_h~C}M^vil*8Fy~M=6%MATo`xM!*jH00NRdLseUGZ25ypk
zhzgC;6Ls+))h{_jwFG2e)!k}6@S45E5PxZHT&>M@RN{qrO6FxBea_M6Z8wl{N7&9W
zn2vpaYs&>D;hB^BL?Zh#`kB95$@nXY>K6rdGX;0~oq}%&XTIs<yfGsa4B4<W#iHh3
z^C4sKTC|*_fAJdOr1F$z(WA=hFM`}v804HDJsTWm{KLk+0>`m1((y+%cR7hxr0l^D
zZUd~|(v(*I@;u$dF)<jz7rOGir(YpGbdczoI4-c}HWs=`y-9j_u8z;f{%d=kUlY0I
z6=zq`rGbB4f8t|>AV@-Sf<4#QUy|)H=POS>fCw2bM)B3TmuqVObwN4_m|coQyURgV
z84>4!1T*DI<8z_Wr@V(w@?A@t&gcRNqcMxNqut&=lPL4AXEH<T(B177gmL~zkf=}E
zWpfDGAGl`FZBgr9Bg=skTwiZUrt|ylS<6V;f}gXMlNmWqIa4w0(aYYLL^3Ia?N`lx
zZk0zEWbnw}vnOU!Tr8v`@Qma&1x*fn^v1@S^-wsf@K9eY0z}t5#igHGYV{1aR(Dx#
z1{_MVQBuy>F45SOEbNr|(QuO2y6Trm2|GDz@2#>ufjwO9MgwWQOX-5mJuvkdeB$F3
zHOG<E4&ImKKW^HXqQKUkC)bSP;<5^e3|vP(uW^i7dtG{tmTjqzjD0u6ag%ZsXA}Cc
z-qB7J6|5n=RR6hrEC2#~RmehS%L$riuu$PM)L&B~ZSCss_r8yrDQMh;CZ2HpU#H5I
z!bfgC{8RrD`IpPts33xLDnTAz-0LMdaV;0BZewgIW^ysd;nV7kg+D{~dhvDp0gWeI
ztnIior=pfeZ6CEBzn-tPT+_&($ik20F(LW3`i>TIQyXWH2avFxW8|$V%U2(GP@+x$
z`0EUjj;!lw3(CDFa!b(ZGF?i0gLSe3srPy;{4m|q?|~_Bo8ER6N?KEUc@4uOXTT@I
z(+ho%5+Y2@yB#14l`AVC{R1pRw5oCMx2R=4+yrm$d_KF~*a<gCTU-xbIp2_^RTzdH
zD+nt#S?fx6F`8Iih%I-XH_*Lj8ltyeLCPR&6M84eDL>afz}D<wle5}JwBv+}UWiXr
zs2F)fF&7)$vG0RU$!VP_=PmPBkS?yc`C$0DEAf$++w=AOS<CGiHdBum-AwaM+nSiD
zm*+8q83w=UDTU|Ov#)NtTuX-%TmE(vA`3kO{lU8g{FY!y(ZbYKSu2SzLj6}Rx12g`
zPJH}vi`2*<>ps`;uMweh#L4<Jq8<a^`Y#&ERJTKWhDJC>eyiqo1RhHoF;e_%UX62J
zHMO~yVJjXjSHZQIS7s;-i_m@X?p;42&MljQdAk69%t2pBM?rHpvS^NF9?~OLhQE(V
zU^DE&XH5%@Pn#cF+(YArtqR<i^N&uHh$pcWYgq*oF`~7(PeubJn;Vmel4>m<LmC7#
zd5iI}^e54#k62yKcfDt(OS;_cUp21(-9Fn4?g7I#bULJ~-{0CjzCona<`|28xh%w~
znf)q1@2%l*wXMql$!M21eHnlH&QLxVz>Ppvv5N1y0k}&>((MnkZs1I^92RG9Klb9j
zyVfddkn_uqt6PULZCxe~GTy0wQ?4CnvoF1+MWQ}WWeE@CqY6Z|LIio!6_Uktu?zGV
z4#Fr*F+O_g;z>Ev{4*rU``#MDW$Rg7cS^*zRM;#-^B1nRp>U07TgDbgipOi}b{=Mg
zg~zoKh#VS#LCYgXfJ6)CF76|l6*>)-&v(4bzC{xmI+8!hytt*wUQXe6Z|c*8`ox#z
zfqKbr6EbG&0iO`08f`7FjOK5wYO&SR^J2bPN*`qwi!W5F^=4u>ODo0g$i<NDqMl)t
zB8;9=eADS~wY(fr%5^)bknx(7&ABMk0q+m?$!DXCC3vIT^|>K=CdU|8$12Kis_%@g
zmXM1k`YGaT;+dsU@Z5*l?yHO();oCdi4T3<jXjzQ-+qRAH5292NFMDRJhW5_Gj4}e
zbMZP-fncb)F9<0t`PR?bnXvy2a-KKaLh90wrphMw%Q^+jB}MM={Rkr?A}Pr2oBUS!
zQPgoSnK)3EJTW@3)~rw=YP#lXc&k2>D)y6Olby2vohQQ|C?%~q_GpBB`vtg@>Katj
zpZnY1c2Jgl^O@@&U;~S;PlL|-kG;7@Q`Ml1wC5!XIdB5Izd3{FOH78mO_kNRVbhQS
zI#Pv{yydDoJJ$^hxtF3Q(kY5IXJ9&xf1Cb99MSG^Q<i_O0-0^SnDnmsSeA$i3rNjc
zceQ>eI3;O)u`kY6@y&F;t)hRCVT}BAHTIUN{ex4lF+ArYT3varxh4r{S6IH6H<f!Z
zXO)FuB!jFsitIsZAL1FGz&a$7U`Mn=YRa_!qCnLjcoD-}zmg1yADQ!MLykP;pR!h@
zXqM^w>xUFzVb9;JDq6g>j2U5QDSAL4_f(AhYLln<HTM^`hK3a?@gvu#S@0=ujZW7y
zeE<Es$dC}(&&Vfah21p692SebI_<e12aHLaPb*2UpKE2;3z~fB_D;<rI0m38l!x@7
zR&bQ9=RR2_+^82KM%!$^bj8T^$b{6a>6^xH#XO4tLbk?s1`>(MtSym2@|SCwljQ77
zPpP!%&@i`LJ1Nu3FJhu|GqXcTKc?MaGRXL+y{K2j{Pg(`b+<77xPfq(*W2;>7fHoU
zO|<W}uXdo>?9)4Ubj)kGHKFW~4cJaE=n_<x;@ZiYG8^R6%>uyr@qtT)jJJbj4r$}r
zYeGoI7NRn~sR-jTW&W|q>TOAbiu*bBkC4&RzfISRLauOAz)(y_d+(VnHgfGwlnNJN
z@LOEt{T=UghC-nouhqDpw_Rem?<bkqqpxG$N#V~(6wM!79pIEQUR%9mOq6t5bxQmS
z)lQH4`%aXzV(P=BJh>usB%jPv&tGEZdiPs^wm6>_tY+%<`mBGeB1LNN$xqO@h3u4`
zK_kEo&pIfUxu{A{aB)MEhfMJTQu~8gOEt$T5==h0i`oQSECYBO81UOSzLyFLodY?b
z3Wn_H#<?>WdMHbO%(yC$g>sBUwWh%U&igj*TQ0AqLQSLr{v9yWS@I`<z8llEA!LF&
z=qrH5p>dB1!Lf&Ct#tXpU>M*JlfqsT-Sc8DYq{$@nQ9Z?TGix{%0;;I7$#UA0zhXd
z5M59s?uH^mI#f3`VDCV!qZLZ9q)?pH$}4HCxOdq`mEn!kFh&+0z2D6L<l~2_lJ}Vt
zjLJz7LqJaVxTn!b#1Bt4sd<KkPZ=tpO2IB;Z<qdAu}916-3kzmSi}#rH3LNga0cRD
zk-`u%4)9;TMD{Qeb(qzQkWz<ha!c`YR5PjYbASOAF#sf6SwjFKIA==o@$&NH{u74$
ztKXl13xS#!QUSz~8*OD3sE3R^sE~we1RmaU(YksC#qFp_BDyK{qg!ePes!;$@27c`
z@Cizu_AZ+tU^9e_gy&{9LcrsH!-S=sSR#E=0vCk%Ntyj;;ITZ8S7j7iA_9Lc?-%)m
ze#M`AQKq9yq~YQ^$`I{9A?8{Q#TN$`um7jc)c&#lk)t7$P6@rs{gTf%e8(sur5k;+
zAH@pZ@1)*6ivPu4A4unbcz44-fz4Wc{J*ZsFbH?!sEC4LX>l*)3bB_}NWQ^FE<Ug5
zZRUO5l@CucFAzs*D<P5<*dT(5_9KPbPDXvT{MY(^oy<Qr=6@rUFG>^QN{jcRik566
z$#@^%3~`htPQJl}Zu3oM@XXkb>i1Ba@8nywc|y#0l#C3!9(J{=sj%#tz1h?_^x&lS
z3>n5;M$R7+<_4sk1gU+sYN)#u#$KyZC~_-Yk_<D9IcV>6loD-Npm9~;`++!hyzkys
z?!!&H<WHT<WWwGD;V9R{QKUy--+m|3AN<ON-bE(t>y(UXGj0!AA-rKN=a%M2^^}sH
yJc7bVVFC}2DT4a+IqyBaqc{KG{*RdM@YK0us-8NsSC){A%1JBV&69fM{eJ*hui0<_

diff --git a/docs/images/centralized_Balsam_ThS.xml b/docs/images/centralized_Balsam_ThS.xml
new file mode 100644
index 000000000..c5256c2f8
--- /dev/null
+++ b/docs/images/centralized_Balsam_ThS.xml
@@ -0,0 +1,136 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<mxfile host="www.draw.io" modified="2019-11-07T17:12:36.581Z" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:70.0) Gecko/20100101 Firefox/70.0" etag="_4VHfeMgUqFtXh-SSbyW" version="12.2.2" type="device" pages="1">
+  <diagram id="RJgQPiBM3F0--PLLHpmw" name="Page-1">
+    <mxGraphModel dx="1482" dy="492" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
+      <root>
+        <mxCell id="0"/>
+        <mxCell id="1" parent="0"/>
+        <mxCell id="EG-plCSeABy2wCnL0sD--135" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;strokeWidth=2;fillColor=#e1d5e7;strokeColor=#9673a6;" vertex="1" parent="1">
+          <mxGeometry x="-540" y="250" width="120" height="120" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--109" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-690" y="100" width="110" height="150" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--110" value="&lt;b&gt;Node 0&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="-660" y="105" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--111" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shadow=1;endArrow=none;endFill=0;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;" edge="1" parent="1" source="EG-plCSeABy2wCnL0sD--114" target="EG-plCSeABy2wCnL0sD--118">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="-660" y="145"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--112" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shadow=1;endArrow=none;endFill=0;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;" edge="1" parent="1" source="EG-plCSeABy2wCnL0sD--114" target="EG-plCSeABy2wCnL0sD--126">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="-660" y="215"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--113" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shadow=1;endArrow=none;endFill=0;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;" edge="1" parent="1" source="EG-plCSeABy2wCnL0sD--114" target="EG-plCSeABy2wCnL0sD--122">
+          <mxGeometry relative="1" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--114" value="&lt;b&gt;Mgr&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-680" y="165" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--115" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-550" y="120" width="70" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--116" value="&lt;b&gt;Node 1&lt;br&gt;&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="-540" y="120" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--144" style="edgeStyle=orthogonalEdgeStyle;rounded=0;comic=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.25;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.3;entryDx=0;entryDy=0;shadow=0;endArrow=block;endFill=1;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;" edge="1" parent="1" source="EG-plCSeABy2wCnL0sD--118" target="EG-plCSeABy2wCnL0sD--140">
+          <mxGeometry relative="1" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--118" value="&lt;b&gt;Wrk0&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-630" y="130" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--119" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-460" y="120" width="70" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--120" value="&lt;b&gt;Node 2&lt;br&gt;&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="-450" y="120" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--145" style="edgeStyle=orthogonalEdgeStyle;rounded=0;comic=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shadow=0;endArrow=block;endFill=1;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;" edge="1" parent="1" source="EG-plCSeABy2wCnL0sD--122" target="EG-plCSeABy2wCnL0sD--140">
+          <mxGeometry relative="1" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--122" value="&lt;b&gt;Wrk1&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-630" y="165" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--123" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-370" y="120" width="70" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--124" value="&lt;b&gt;Node 2&lt;br&gt;&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="-360" y="120" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--146" style="edgeStyle=orthogonalEdgeStyle;rounded=0;comic=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.75;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.7;entryDx=0;entryDy=0;shadow=0;endArrow=block;endFill=1;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;" edge="1" parent="1" source="EG-plCSeABy2wCnL0sD--126" target="EG-plCSeABy2wCnL0sD--140">
+          <mxGeometry relative="1" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--126" value="&lt;b&gt;Wrk2&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-630" y="200" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--127" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-530" y="175" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--128" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-440" y="165" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--129" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-350" y="145" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--130" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-350" y="160" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--131" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-350" y="175" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--132" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-440" y="150" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--133" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-530" y="145" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--134" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-530" y="160" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--136" value="&lt;b&gt;MOM Node&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;shadow=1;glass=0;comic=0;" vertex="1" parent="1">
+          <mxGeometry x="-520" y="250" width="80" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--147" style="edgeStyle=orthogonalEdgeStyle;rounded=0;comic=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.3;exitDx=0;exitDy=0;entryX=0.614;entryY=0.988;entryDx=0;entryDy=0;entryPerimeter=0;shadow=0;endArrow=block;endFill=1;strokeWidth=3;fillColor=#d5e8d4;strokeColor=#82b366;" edge="1" parent="1" source="EG-plCSeABy2wCnL0sD--140" target="EG-plCSeABy2wCnL0sD--115">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="-440" y="298"/>
+              <mxPoint x="-440" y="230"/>
+              <mxPoint x="-507" y="230"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--148" style="edgeStyle=orthogonalEdgeStyle;rounded=0;comic=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;shadow=0;endArrow=block;endFill=1;strokeWidth=3;fillColor=#d5e8d4;strokeColor=#82b366;" edge="1" parent="1" source="EG-plCSeABy2wCnL0sD--140" target="EG-plCSeABy2wCnL0sD--119">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="-410" y="314"/>
+              <mxPoint x="-410" y="230"/>
+              <mxPoint x="-425" y="230"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--149" style="edgeStyle=orthogonalEdgeStyle;rounded=0;comic=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.7;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;shadow=0;endArrow=block;endFill=1;strokeWidth=3;fillColor=#d5e8d4;strokeColor=#82b366;" edge="1" parent="1" source="EG-plCSeABy2wCnL0sD--140" target="EG-plCSeABy2wCnL0sD--123">
+          <mxGeometry relative="1" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--140" value="" style="shape=cylinder;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;shadow=1;glass=0;comic=0;strokeWidth=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1">
+          <mxGeometry x="-510" y="274" width="60" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--141" value="&lt;b&gt;Balsam&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;shadow=1;glass=0;comic=0;" vertex="1" parent="1">
+          <mxGeometry x="-500" y="277" width="40" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--142" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-495" y="310" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--143" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-495" y="327" width="30" height="10" as="geometry"/>
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>
diff --git a/docs/images/centralized_Bb.png b/docs/images/centralized_Bb.png
index 0a9ffa175d08843193db2d716533d7b7b46a132f..fcb0d1ff9a28bc208612d44cc653ab9fcd152dba 100644
GIT binary patch
literal 39907
zcmaHT2OyR2+rNsET_KUAj2yCOiq1LqJUI5s-p(<P5$ae`nIW5yBOzpyGFplfAuHKC
zd-J~^^!@gG-{1RB2hY04bzkFieXjcvhEkKKBx58aA|j$xRFKgmB02^mB0BPj^f);4
zBmVm|5z&cOcUe7mCogL|M=K(BA>_et?1KEZ7&muzAsKc-K^zXpYw2o+<F&(pBXG$H
zV`*n?XJvVCS&&~q;;MkaRemwFfGE2VTtp0f6Bgwa7vVQJxZlji%K5M@Rg90FqoWzS
zpqvOVKWOTTs+onIvpdGkmR$$|juoBVtsKEma2kA9*8<=4z(;_eS3u<84p&dmycj<(
zKNmPJZ)M>C1|<jG0saesQ*w5$R@N9Va1y%dU;tL`W;O?d^|E%6brcYAaurm%swINK
zS~z<v9o*w-<?3dKaXz?BK#&)F9b9nt##$YmwY2iIv#>fiiv^Q%JG>b>BP0uiXK80<
z<7(yvMqzg-98Dz~4U`>1RY;Ei>Q$7AiUQUNchG>dnbTpjDA3eZFm$L9F&%d`OHoCf
z9Ex8+#e*LK$Jncw*-JR7qSc&zJRI%R9Xw?1lpN)SF^*mWC}#l&5iMDJFQksUjf<t6
zs~g73!cj$7P0-v^$-@TjgRm6y5W#xLVZ{}F6lCGzR?3z*HJqvt9GV3}6D*G$m^}g~
zCZnz*=Hp?YXeNts#PBQQa41ovsE#JMW~Xf~r>Z7^1>GQI)cIX(G4>8F`Z#@C9dj+D
zvw;rQQw?b*s_tQfLF>w>ifba}J#>Yj=bVuI-e#h3D=i5-(2a(YhMRz@ouHDghb~4J
z<0fO}E+?;~=I*Vb>46YLC?j<h3<UHPg=}?fWYOZ<j^bi&V%kcc*7AzlSfDKkC7hLy
zgoUt`gN&z=n47Z|KUi5gT^DzAVFMXK3lD2qd2s9i7xyqX&~wv)Yhwh>G`yh6$?3z<
zD*7s3>M}CQ7%y2d0|R>>Cw>)oH!W``TSZ+}2Td(KS509HePNult&*y!f|{Pbx~LLL
zP{dl5-^EH_*;(Eiv?8o1Bckl>U@s(wgp2E-&~nN)ZYTj=8&OS5GhLjpj=ZI}tQFEx
zRlyRcV{f3Yp={xSg}W)5sfh_WXo$)v2<Tz#46tV2o^W@ZwvxH3o~EXO1Kh<)7M!+r
zaMrZe7l*qk`QSWkENr|qz=REKQ0gMiUUvMN7S`(4XnP+kFEA}@B~ftARoKGC9w+K*
zqoX6Iq@{roKq_lvy^uDVNLdSUC#;OQlDCSkohsCdnShg*rh=@St-U-@V<g&AOB830
z;CFMyndusc%P4zjYHEwQ*yx&T+WQ!2YwIF)wN)IjaDFcpD>)r~cNKmseOE;-Hzj^Z
zzKVi!q8<)b^70N^SaAzQYkiCm5}X!yLSuo=BD_@f)WD&eH%3=N*##|b1@uQw#a2f`
zPDWHo-$O=F&rwdoQQb|E-_zDW#oR(x!`#(TM$ySkUReX9Dk`oBOdjDV=b&qAZO5-?
z>m-N9X=<Z=)Maf&_}yG&HBpL+>JIV_V0exWUJ?fKKKwW_q`jQAFz7}^+guzii_x{z
zQ@}dn^aNdSigvb+q5>)?lrY*>UddCz*}+`VRn-IO?CB)osW0z^vv#+2Rpa-O!0M`^
z%r!OK-MsX@fXO3d+^keR<aIrO-$BT^;M@hR-RvZ+^@SA$RjqZ@tq?92jsoUZvTBY>
zXcYk!B^6;SCszd<dp8FyO*<`BJqI@>xRZo{pq`GP2*O!gPQ^vn!yKXJ1_o(nE+?<&
zqKmclMyfk1+QS7@5MBldZy;KPgn^ifH&V_S<)#ge1nh)Ra##sDS4%HF8%r@kWeWje
zd!(X^r<0z8fR?MAj+z@<O%>x}sci2e=;;b{LQciaN>2_vD(oYo<07Pl^-}c^mDRAb
za#3~h(3f{t&@so#xQJ;xz%49PTvV|-np!AV9UyQyQ5|(3aS>gV3(ihl18M;)im|j8
z)50J<1uSGmu-<mg-a7oQHn#Hinz{&nZx1BG*~LRoTMwroBCKVtV}OvA(a=FC2n*S`
z$><>z6`<KTV1?jFl&6!bx*S4QK|>26qwlGO#OSM`BxEh*h2?OX@>n%3H!HLiQbSDu
zrGm3F!>C!peO$F&kun$wTNNu0O;>(9Gi98jxC<C0%2`fBR#;G2+s4cS3wK5!WzlvB
zOK~4tRSXu6vbIptw36Ysb3wWw;Xc;Rf{r@ix)TTt2s<I1f-KI$z{1{DS5;S24XG-q
z<%82x2A8ZP9Q3S}`E4}qaq<qrjv^XPSe%!$n2o5Gldz?dE&}dtF08HPA!8xLZ!LyI
z+91R%bl@@$j?T(54iZ|<z)%$UQ35hL$|6D{K<^QDa+($%7-bJfL2V%iH7h#@Rec{t
zerOOnvT(@NqSUpmFybmALShIDbp;JsXOxz(0oqx}KvUIK0MdPR97X`GX(b}$tYoQd
zZibQ2G}H4?krQ^Xa27N-18R;?cTo30@hgB(1KRr&ZT3SCI6e&BLbA_0G9M8UT_jSJ
zfup@rW>S5PXuJB~a@uW``z1Slle2rmc9-(>O{1QR;TNklPhNt*q_<c&%JTxQ=WHNr
zC%~cF{#Yl8pg7F_Rfaq4xQGT^R(9bi+`N{?oF?qf>DVaJkE>3qpS}0=Y<h%*jOaaa
zyj$1P+t!v8J#BP7$0U{{+dfIyFvwl+w`%U!*}l_AeT3#nA$7qG`&naB{6+9zVXXST
z+2fk0Dv7QE_V!a}^78T~KYaMWmz|wm8y6Gf$}b|aq80cC`|TD#4N=PL&yOBGBKN7=
zMS**J!B0MLf8xoLC$%_Lla^^3n|9RCeu|uXO({UiOG69?|6R3JR6gx7QiM!^Cv{_D
zW2f1^z)3Q6H8nM-G_|yJ+tP0MZgv-21T^!9Nei4=vB>{z&TLefNwPmW(wGeYCtcHS
z;BHvc9QNof>X?|A2zEBMtJaU-1-#`K*lXc;k)GwK#3IS}yQ5({(jONU#ou;|UpTD4
znE3UniIvT<?CcTRkg!dO#_T~0Dqcrh_^rFp+(~0nKywYTv9S)m(-T+qUfgl~@iJ_t
zzb4_lglkYoM@JO-S>CAlc>4B%0W}qlGelImb#<vPU%uQwpOnPtI`aNh32xq`#O@nM
zOmcFs!!1QcMG0w#cz;+U+dvC{>3mT9<GtDHmIiVjhSSF(dC-igd`^|@5)%>ez^JEI
z=cfB7Irf%6yuCS@`viwNGV!prRZUY@SH9e-S1$gl;dhH$ifU>S{8k_P1U_~5nI<Cd
zn{;|41e5Vp)*L-(kB6OuW6F1`scvVrH#;Xsb~%ER=vZb|RbnkTapQP=m0N7d<ESd<
zPZJNes*jTUhO*BEF!UK8NWe8>*=Of|zsHa7&-IZ>$;q<ww~pRY2fuun>ddd9<Sw<D
zHvMY<5Ltcn{?J)tWCIp=urTj4!^6Wji{IS3LO(^Q``tj!FhD}v24<s_<~vt47lMxy
zRH-${7ojq1h&i4d8uWR$%3EBo0;jt#cYMZO+s)<4wVdqi4y>e&ot>TK{6O6k+{GhU
z4&T)oR&e4dcVJH1IT8Cboh(Hc8+`k`je7`uZ0OeH+T-!Ui_dTFYgdoz!ootmFarf;
zpPIgo4!wli*n^2wIijYY%ah;OxVe>W&keWS9SV7O+fV31d7tsQvwJOtRowBJw@A4U
z)brREYRcn{iq1BUJtbC;d8m!jz;eIod;_FnXWeaN`ta>U-q-9(Ay&8k>JU8ZVZW4m
z#{-Ab`_#IDkUp$TcgfDP9lc0WXj;!J{#A;V)oSg<Pj}NjY~y7(T#;JPLeu}@i-X0o
zJOQT6bK0O&c_xCDNOL4k*JLO-ZrwYNyRJcSCuF+4?&z^n7IQFNu_CgN!-qQfJ|~M|
zVoZwm(zbrTjfkN7Dj7ti5Ix;h6g%3Ipao|KCc26VNJyGHn<QDA@B)8w^<Z*!Tmk}L
zIYmUuzEwAtVTTZl&1X&T4V)vs`SJEb^I6NGhTy&z=HZEEkH?r|M&~7^93HbjM>W3Y
z$-m1=I1sQ0Couii>a4i5G&Nq6+ABVsG(-|8Q&aV^w)D0{qjV!NYjd3pj6!_<XluAt
zYq&|Xel>&Hfr{MA4+;u8*XOd@+1dF7w@VathEpx&=V#r-bLmOYV;3bUc&=QTgmYLH
zCVNl*TK4@!9o%%A?!Yav_UCj>^XcIVzZV*F`{Ys+Ni0SNYzLCT!ooK5sZZpDc#&9N
zAES$(6f<wXT_zX%t2Kz7QdF9DaUtDhEdS!+@C7Iu**H1dMx{JnRaNOPQ?U@aW&^`m
zTi)c-vaVZv%q!%jr=a#4S}kayI~hYCr{9X)fE|brQ7tJUQT4T2YvsEkCTyVR*v;13
zjj?1jDp8Ct)9D_Enf=eE8G(VUbjG}sse6PX%-cre*l7V`ihb905BRKht-h1XU4_PH
z>atGUN!j>ypU>;ebmQfx7+;0h?c|J;lkk}lpO$aa8_3r*=zYs@bpi^KQa-0bM@JVn
z@FA8A2#<}AudP9uudZXZJXzGK#Bpt=wC&pH{MPz#q#_)CH`r~wRbq5-XLGvfL-b|&
z_rP<!muK;laqg>R-7Jo|WLV*xga6o9wNyyKC@SKFek{=8^D11&;e7kbZMqiNt;+m;
z-He*HhfLB%_ez71R&{r+w~!e_i22%FKfd?v+qVYg8hL27jjaK{HRCA^H!rW}L_Kcw
zBi-p!r{45(QZz=%-lvZSuIp=L;v-vU=dl8!v8NGU)<8&87S*3_&3{#YxO^^Q$VtEC
zu?YzUPWxc8#_Zsq9_~pzpDC};xSA3v37xdGbo<w@Z+dkm;W=QbY|9MZL^Z@DB`G-%
z)N*aQ#GWQ0Apt8O?lM&qD1Y6oL*+ds6SLX*QAmSXoV_eZ-oMN|dS=>1_dp2~I*fhl
zUcIkAQ|8nw`c=|X6LE#WPl41aGWiU3VKv#F(@~$JnWvzq$AB4p6c-of-<K_;p>c{1
z{VOfS&H9BrI;}>%;X%fNK5HYw^=Pffah8@QpFZsa_h~*S$UrgsJ(Zv?wIQ<{k@{$Y
zmq0+nTvw*F?R#Gl$3e~<Sc}y9&toO_ov;$OamcxM<<`&)-d>`V@ZT2iDYc2Tnw)rb
zJdRtpFsh_PaB;3?e$_$k1F-q9nwpx?K^Gj3)6{>1T_90q<bCwzj=@{}3^LNrn!mO;
zme43gC8f=TTpRb@TYHb6pJMG9?g?Aju7TB79V&5QruWj=!?L-Xqa!1?B94U4;mI2L
z*~G*Wew0^aXliTA*4EXL)VF;8T+l0dYIb&(O-LwqE%E((g%bar%?p7_etv!xZb~3h
zEBgBSrmr3odq7K1uQ@;Mer>9PobsWY_BBaKMc{hrbcBBp0w`ARePo(C%kr)!Uyx(8
zOYg{mE$DtX27z&@KvJDa)RCr6i&LZ$-rUv}xfw96UG75$Gc0$Uba6h>(!y7-;#ZiJ
z6-aiZ&WstYmLd*E!?YuN<>lm7?YO2MGKsB<*E+nxlXPr7eE9GQizHXEbN@A;G^G*D
z;M($oR+j6(!YHO|V9R8;eCWojV5A2^s0x~EpI&JJ-RI=wJi$$59~UD)L3e6fUS8g?
ze3qABROK3cmZ7h|UlEO_)yVIx{f!-JAZf7?bL{>y9@U^n5(jzUjEsu|TYVYL{1l4H
z%F`aw&-IG&n-sWvx6I5~SNuIZ$|l~aDb4hhhAutYtVE`zY3&MkUxu}P+sh*zAiD)Z
z2*cao<acvBk^BCI%LK>H$yx8*@BNHGps7PbLb2N0-5FWwGR-yVt-<jLBvw<yl;e3a
z%hQEyBCOtb0s(k6R-Zn7`rZdiDyF`ROAX|FQ6M0+x3?q6$jGWGVY0Ha9n;@()hj;b
zZ7hFN4@*vFTB#^6D_f~#p}%U-G0c2sP6|GeBjGwiN{3E+e693H<7Ll8gB#wHUtTv=
z-ZWmV6gX3Q6beR1kG5au&%3bi%XGi@`_%d8dW=tkxC#j{1cj<{89rX7!dGMDf`bRw
zWX}WrB?M#@6g;dRZt!3I)qKBWyu)5(e*XT02ecHhzFRKa>n>An8yg!PTl2L`YLQ#4
zz`4E~e9g@Gy?3pOk;QNMl+9>SPdZ`eDKA*djV#~SpU_TvV?i2bRarf`olBgZ7VBsC
zL0(~24HUGeTebZB>L!@4<+0MD0X*a4=FTz+Sn1Ry3H%7GCvVpMTI$bwA-_#``x+3{
zT_?V<PKji8zSJo&U}r#A4(4j+U3ore!4R@N$`>%{BF$q|8TDg#sZBa}V0=J>i;L^j
zPPbwhfPg4CyOh6k><_-NbLwq`qhg;sWRs#&u(LrAiXoqH`>mDN2@>`jSNONd^8*e*
z+39M-qAt^tx$9-+<>3RFv5fsBbg>^~tUo=5lN_1034Z|}T^w!c7`JIn;aZ;uuuY>k
zRmv}^7KEA(hoZVw#(B5q=4L!Rr{aW=E7z4P6E4!V>%Z=Itk!+j*!bN@Ei3J*`6MSN
zm<+Zw#{SZKQ*BE~a@#@Sg};3UuWyR(t+y79_-}rbL#BE=<oiq5)!q*<%TteW#hKO=
z+DR@#M`x!;??S~p=D1WzoMw@gmDPe&#qAB(HyNkt=w$2C($fbo*Wl*oT%@s_D=gyJ
zJ3i9DYxwN7=O{yl=d!cu0V9Cuy4U+nY*oT@y(>ziesAYq)XYNG<p){Y2)9r}oju0n
zE$)18n6&wy@OEV9b@gyi#w8VXc(diNwv}7r;OErd`M5~w-N&0L>FF%<^W>D2bU<T9
z@m07M;Pn*&u5!+-7$3)mW)>J##rUwaX-qOZ`wE?idu((4hQ+S9@GVcoYw;{+wBDR;
zdhy#+k8=+q8aFvShkBVF{c3wr*`DO8+(iPGvwW?5sw+jp4Oq}CvbI$9#R1=W{Z}{;
zq-z5bC}Djk;8QC;$_$ee6BmVSTC)e{o#G0a#GFy}S_L|>MfJN$k5xEafhrHwv#+|u
zUaHObCA8!1nf5X2&S0)B!nL6wfs2Yv$tUWhGUEg9L-&(JgWkM}0TUIB78~%&dY557
z?S`J3n&L?xm8uV_a<h@0@V@du8)fI<aCu;0pu^YM+1c{#gLC+RmWo0D-sx9A)d+z2
z<rEMQsGV<=@iD8M{oIK8L7w(XD}CknJ(IDg8&1{Mj^8oexg8FOap@l`*W;ReNz!uh
zH3uW$(vg-yO{Ri?1l-tS2+k#4rEMo|?g|f2w$$2ZvB70=fi$Mm&%xQcZ(sYzBQM<e
zk?Z%hySv-zrg@@}4HdBUkcoGy;iM<%mV!3Tc8m3YC?>|r1)oFK9TmE;^!?mz2w+>k
z&EEcT9?hS5;552U;gwjrORUH{Pw{bcpXr+e!Ry9x$O@i4d*+3c&;#zaW@iqPY16xR
zOHyY}oq~UCY02yIoa<BcTLsaL?b<bi--8eC-MdIhNhvxT`SdBrKrI7()>nmnFdz^M
zyFo&yzL!V76A;V%Mru8}e(~&uZBobrqozsWvTTfujPD2Pd_Mq-l7nLKVvkMw%C*FP
zOTo|};~LNCU%$);+*EwBii@Kk#mC1`GKoSF7<f~`j6p1j;U$<ssS>ls<F1P%impK6
zzpmwX43&$Ona-GA_siYsX|$R8W}p6;eRn7^(t%?n<Y5GV#3EVC@;BQDX(|~*N1kt!
z><=dYB%FkZ^U`^Ab^MhJQePQ*c1}0@#A&16d^9}>1qP%rBJpSd0w7HIidBC%K11-@
zu#_9>&FSX-JE}rx&_vivb;s$9=PdttML%T8_D&;Z<nQzxJbO4Rgq$^B?caA8_~3qL
z@MJ`4P4OA+JKrYrGVnu({b?TbM;v#@MK09?_0?9huLe&xKe>GPAlLp4r-%>Gc*d*!
z@wfY-!o1&JBM_^7y6{aI^#;ju(B;ehE_bM4W{QEQ4q+@iD}m^zjN?gIWJF?7W?=Zx
z**~#3{J#v47=D1(2p9zF$m_5_@O?!U8s`5P1wP{-mFf`N@8Zz0;5Rvl>4;KD@nriE
z0yP+varDj^IO+hVO(p-&PQ&lF_Y5e#dS)!ooA5U3zG3Icx0MIVZZ7#rM!XMMO*;!O
zr_L5o_0In#$ng7L!6OFwiywkjVP6~XqN`pg%7R1Y(|Ugo;_Q>sx;SCSu6q}VM-Yvk
z5BnR*{u<P;OYY?rzj&3TD_<yDb-nm|GL=LCer(LB(pBk*-hXW071R59H0b5`O16sR
zmasg}tI+A&s~pmwdX`%MqsgN$bw-!24XQR9xaONxOt8Z3`|P__lfuhtcRCH?FbNiS
z{}S1i^O>xs;MT9l?sg1?(D_mxLH;Eq+Samfd<!AILuyL%ppnl^$316fq>tae{`U-n
z-KvC><{T3~pT0r-KG?ykl;DSZdgYP3yF0~%*F{3ND()m!EQ$^Bj_e7EbjykLD%_j4
zMfjq>97;pHFH|DQzAO9!(Fh()i5V^WOi^FI=S~9|Ua7v*_|4W`I%(pVrcDM9-HXPm
zze{i5P2a$$kKP~Id64l0TN&G6?Crs4Sk-UT+8Y2;hY>&=?ND)(!bGPF0nBZlTG<>0
zaeMy*NGuk&waYYT>r4VT*x5&I0b>>2)YN1%{wYx?(Cmr7<0_1NDN9oCtb(%!y85Th
zIU?yb{okb&Q8nqO(6m$)Syw&BO`S<e01I{+0_{b^Z=5isu-lXF)xLl-Dg_Wktyul{
zty_R9yB+oD(Q@eP*RM}7aLnaW#IB#IzUgU5OLuu)U*dJ!@6wp4`}>XJ!!7Vi0ikzX
zdYSNK1>iwqFgoLzGvY7!0GYN~>#e9R@W7;*e{!vFVIj4_wkpZSn1;?pmeF5_<9F%$
zJEF>nf7?-1JPGP|GN|HMK&$2EJbmiVyLysIJRT5NPkTzW#`sl!)lmp-jT_5G*Trz^
z(O7Y=_lVp{zZ(<v?68qxypo592tJ(IlAmFB;M)fwKE6oDf!f5B8@}<-r=zRu{y-s-
zDu7v|>(GUf(a{w>nw8B*We-~U@0|nD-A$t-znbjHC|Md$kz8Zj;tBt`)7v}&BXc&y
zbisiczbZ3aXSxNFBTwL!65Ox#*FnpJ;QaXfIgh51k&1zVfeZ$j5dd*&z!}HH#j)#A
z#KvkVi6m9ZC;lO=xb8h~W1sg}*Y7!yW$eGhS5yr9{O%aM`8inGJ99dr`t|-dKo~t!
zH%qkj<@<NJ??tA3pv9ONsl@Bv19}DD#e+^JPFugii*1clEUmYFvdF$_lCb>c+<K44
zo%A6acGeTpmkC$S6VnmX<xRFe6R5rPI3Xd_>=@b8SFcR4@9&zV8?8-b)prpC!1taw
zXRvL8BJh*$eEYn>S!7GMt)l1LPn#}c|Km!CkNXNw3X%}b*e_T-plXI;spQb0pmY~S
zL3tt+;(Gwh=Fy#h+q_reK)CBJiThnTeN_4wJFE6T<KR*(>cY@6DqZxHJkly_OL&ta
z!IdnMxx~UOVE4)ZqQ^kstp-mEgQtbS0=Gvc9Y}}_AC7*Ml5$;jLMgS|iTGaNm$;h2
z8;LPOJmURb(tW=bP^k96ep;lb%1gpPX!?<Dibvs(wjooaLDQhKFU?)s_V)H>Q2W{N
zvaD?3t<3bwhXRu<!7>xGME^#QNfUPg%g}QQjeGmOYDULEy+&Mxk8b7XzF!PJt{D~U
zIMiF+*daP7q8p9xv$Rhxa-d#(<?wmwzVCM09KZ23H51tT66{mQ{Le!T?vvtqKT5-D
z>s{FMB&$=mD@KvTbkTqZI#X5OuYX1;KR;j5#3U^^!Ne!8*GbIjhh@(k2<RRk2iF$f
zvBcu>N6E)qQ{8@S3~jDVTY^jq`iy+ZM5;+kcXo9x{g5&0tF7NBjsQ`X0t*@b70@Gc
zSF2ByNLsnAt*gkC^IaqhrzCEUEmu9AW6*!=>NbURV;k9TA$)j4@k&Iv&af&&NHMBp
zlx}KAJ;E_-z=k1Y#(T@kK6%fmFnd5Z4?R*d_DqT-Fh5s0uWfg@ImeHRZty!ZM|AbA
zfx&nD6#7YdoP(w}f-^4RA!7hGU#&NsCWaaKwA47)Uqey>(%PKc(+}$B`*DLgyXC+p
za%Yoo_^zV%${EJ5%z4??nP3>DL|sZChz~8p?of!la1t#JuxN%|_CjIOW)llvewW_g
z+-L|UXXD{fS+A{k=h~RcFZyY-e$GF>cz=xw;G>DMcId_{?^T};@cGPon+$tfYcQ6n
zdVDbK*b=h1w0WLllL`I9o_Y~MpRjS#Wn?wZo|ukPxu|PgZ*L4(Z!Q%V4J^pt-#;6q
z>lFpuw1{|+V?F7#m!*a|IXTsaM%>u->N^hQNRY-r*@(PKQqctoK_`N@ok}^g-dm((
z8T0G5_60X2@)*duZ=|j5Y;ULd+}<B(dC{MNHf>>04=?fPDc9AD-?-a_ebRu;bJCHn
zxaSivJecn3h0-s-7>7G6fA-nvPQg1*r<*9365tSV`g_(k0|NYsLFBBB{FW<IowZJJ
zCZy_V*A;g++5%#>w{Jhu%=6lkdA@{paS^cbdNc13y57_*{j`PR0)5Pxp9Mne#KhU&
z{C7i6RKG<UhA@b)z=XGXn56;tG2oBI;l}IYV`Gm21^Hd7vLBxuDPcg-7q0Q|?QUm}
z`enA(E9E>1(f<4(EMowZ*Q2c9Kv~s^mc7Ol5#1VMF|x;~u2;TSy?T+WXORqC=q$=`
z-BJ<(d{3!;xAVwYGa16bL7_8EwPP)Z^DQeuT;p2moXH%<+0M?zo@t_x=Gi|?6K%tP
zXPV>zQ0|!?Tm%?DYWQ7bEYPH=u`z3N!Ie516To=@!Ydj#=$CMN`K$cM+lNe|^Y;k^
z!iA#mVIFDrc6LK$lwxfY(iG>U#H{}$SFeUkLr8%0>lSJHxsWcgbs&?juC8xqI~y7l
z3=NqkXJ*&{(NgR8t*7VYzIZ71#j{yD)%Cnv;h6?{w#V`$ao^j9U0mY_<M_6kDv#jf
z(wMSQk1T(VmCc?&S++~h0R>j!5$a0;TX~23jp+E8>*j4{2^>e>;F$}IGCQCBQuzWi
z1hFm&wVzsA+<YK;2vQ(j-Q4n=e7S?PwY8gi4ZZGV0s;i^0%x|Fe)RS#T3d6>3q?mq
zTkdSG+@NpR-1GtbCF?ro>C>k%tE;P0^W=F@g3@GY#$nlT21C6X*-Fu270Dzd!2N}r
z=NqOed&3@tkf!TRw^rLy{pc9|<0I0gL1Hmg+FS0FHIOdlcWq@inEdR4tz|+gtQLU(
z*qfi0$=KA=#><vn7GiY0_}gOA+qPtx;826zfURmefbyb3VrvL(yaF6#$LZpfWJwsG
zCS)vn%)+1Oe5<(m?X-2&d{NpZLy0Bp%Ep>S@y5==)c(kfU+4Sd0PZMRneVUlF8$U^
zR6(=3v7xbtsS8(D55~5{U%lbEsBhxGVKwE(%*>3hSgvWTrb!cbL16F2ivT%{{3vtq
z`*9X<%-JtrcHn8p2zo4>4n-iAGP^F_Gn$z@v)B91J@L&Sj@$OutyScw$B#_!W1+c6
zr2~HKrr#V$)jGBSPm(=Q^z0cv-R=#r2%ha3O?Ytcq`T~<kUHC3tL6II_o5fIPt)m;
zi>1r)du__<7lAO&GE!jzjQI(qUyV^4T{**S!U~OB$=#Bd0|Km%te9AIZgtG-FKwG|
z5@XkyiRs2CcmZH)+FS!w!|#)`X@;Z~piV}YFfn1<Qr=J3065g&WHB{0l40TDr&G3V
z{mSke-th^%8U$P{8ypU=U8@RCF=L2{kN;le*I3thX>6nF*|TtaCUq%^Ew?hC#di4R
zrz1YZ*^_ee4DuVnV^kGJWlX6q>9IwK#<tUILQq29Qd6=EDk%Vq2yOEqL71*&@SDwW
z*sjex)3Bzi9*s}2Y;h=h6(vt{)|jBf|3I%z_7oWmIMw&n^<%NrqI5CyNgHnH@7L=e
zi;c5i7rwVSkdx>$<u}J1D@LB6F`rOhK@V@1h_Phts}GR&-dX9&>sp=bS5|pCM?Mt8
zu1uH(5Z0n9Ct&z3<-m)(K|#dkf{FLfRiIvhIvnJVAvA@@<DJRP0Fk`{Sp9ETEy|^L
zmbIoLvXyeCx|H}e$zV2ZX*oaMKG!eh^Yu~N_;xFja2=N}A@uT$;9Dy44<~;Eww{^c
z@lF(}#nzBb*jC~W)3^4CPVUBrh6Cl!1Ilgm;FaeWa@W|r5SN7}wW)LLaW!Hw%5ls5
zMe|Ad_tJ5?S&<JrGzLFV!X)w*>IOa!J?Zp{jcAKNr7J2whC4O-RkE$|wzZ1wg+RLe
z+3!bj>4i(y4^gbOfLs)r2{WcDtwFqJzT^Qa4O4@*4h~s`6UFIuUJI92B+3jvZ*5(=
zJSk!3$ZGWRp2>~*^@ZV%@x`U3ytP5^apvT;hmY`NYeVL4V{EsFhECO}6r|O5+_)w8
z%o^d`JwZBr#goT9!z%ckeZRka`N?(tU;fTcPNNS;K}<)Z(Fd!m^=EZ;XR<k?ob;D$
zo@FNUGD9(3w$9V>tRMNx3f*$JabL!zmuM^oE-TF)vX;pHR>nS=uZ?+PAtHPQD@;rm
zI>{SiHWzPmXQJrOUVw%TSprRx3Wp}xH&nL^!ZR6t10ZKKfyG>V6A)^M0?_z<CNh-J
z6}0;1nRY%gIqTXM8b%kq;tQ%R^?<SzooC`Ap&ME?b3W^QA^LtnZ}9y3b2H;v^VPP3
zAHi86Ew6#XE`5mQBnjPc?5jNG9|G|0xvg{X=H>~96RBJ78{+vxx{T787SHczrq0;B
zMWt7HncGCdNAs7gL{HF#m?=PLz=kYgTyuU+RDQIN^^=ARp3Rh0mE%mJK-RQ#3J7m$
zq@U;;S`zrQ($gi}p8l+Fth*7gxoo%i-Eg^4-PCthWMDk}{(TZKdYBo8mX@}=7L$De
z4cHT@>7i3~jxT%`Pp@S(4IY2kMz+8hm$!1rC3*g0vs~A2@E@aUGz%zNd36_zeO*5d
zKx!9(%^z^i0ui)$F~?Q25G$s+*ctr}d)&a9OW?->j$OewekWmY1L>)gOUb&@%5|p2
zZZ}p^`$Ey>{<YNb<^^cG1B=4YcDokq^Zfkj?>4KI<`tkWGgSsq&A>Q>&GksDST9LS
z*UNj(4>&EoiuOk(uG&zi=c)Vp$c<AoOE@^Qgq#&Gu{a^E{G}~mt9Q_=UIYdU7Zw$5
zfPBJpBA_+TZQj4~+oEl`i6_Ior)^>4Cg<sepyC@RSIX@T&YhDmAo=#q1*w7drtj)C
z(hIvx9lrVLhBAJfX<3)TEj56YclFHQe&n7J-C;hq0}!rO`qI+U@Qz<*W@d*dQ2G~l
zOg<NumBnrL0k#_|LtkAUKXR*`8fNU&sJhg<47eTUtvkg-)$T>nm%oLyJFE&xn}2E~
zH!86hw+E8#H)B|`oOpG;k9uD<yw}gcN#Hq#NoupFuESFX>T|jzFXrqSStVpNNXh4T
zH7eJ}(n{Lx)?a1O<aQ)<&NTtR&RQUnZO!6$S|wGe|Eb@djCRb2r!@W>qY1S(oBSz=
z_o?DNz0U;Q#y+uf#D*Ew`=^STY}Bm{l-`~%G_LX5<259$qGtRyy%KNU_4O;<x;493
z%g!$E^OoEqyxC@RX{`K|HosSsa25v}XNqy@pp8)o4$4`MIyIge-W;+yxtUl)JM%>L
z{`;^qoW%d4TqyF=pnaNr==kCxXkLEmT9~`&`BDee#_kl?Kq>mUF6Hn(se1WaR)aSu
zt071GWdel)PUy5m{jv_E;oid!#k?+Dcz<oj!^0!Ktq|0D)?THjr~mZXdZ5kf=-@D1
zkUBp$CI={e*7b_pTeB6wAoEVpQP<n?y%^3oVQ238GFFhYcsS!K_1RLMz{xM=N2HZM
zwE-#<zh{D*>8&^r`?*d1({dj4q_FZ6bk0Pi-|fA6RU*l9%fmWI$o;#3`q&k)vdr~2
zIXt(ara#qgfP5uhs?LwrkL4FiI!KYm6?B4sk9|(A9Xi&>$>LU@D@jI9p4aBL^jYkN
zTI~qE$TTMli?n}jSAcqsW^|T(<f_Bq`^yBCEuk8Ur+b)^%SSzWhHC+l%S4|t$3zn~
z_6EvpAKc%|3FN#8qTbTd_X0z!AH{)?4ffDWD>o2YkHVW*GhDqScYd;GR&nx;eXG#c
zbs4+&!qOEV{>3PouXQG?Tz^YbYGpU&oclW%?0U!IKv&rbMZFilPjYgKq$S+}@CB>*
zl*YNIBzO^_ub=qSQ$FJSWHIoGW4TMNMNf(=Yie*?{iXpsB4Lq{<9-~MF5w>~Bxn`Q
z_Ep7h&TK4=E4sVC{8@hv(8hr0-K@h@4sx$b7*zVXt9CC_x83gZX?QAUv22+lbOhu*
zkJGCf{d|UB-#rE_ltQ}YOIr;8v(lTW;v0nb(bMViv6q`2K8$s?#eCbU_#N^Lpl#V0
zuAqpF%*?ychM?Nj9}Xjd)KVAI{Z{qUIg~|3M4}HF<i(Bg^xkERsHkX6d%Gq?7ehWB
zVm1b;SD$XJ3V2lI+I(W!X%u2%ITdrm-#y6Xk*V$6?^Cg3`DF&fG;XXN`RCU&u7m6>
zB;D%h_H!O-?(YP|vIybc4({5b*nQ?pBgX+fmNS7MJ&(i$W7lOYMxZ(i{7ie`Z9oBE
z4aT~^^-Dq6&d0_4w7DhpTL^X9e4{7lL3jopeEky6q&b>ASw=JE%IVN3$oYV*g?aX{
zT;8OpT;0(2+WMzW23yl&sq#5G-~veC&2|V@Vo?ia)*1f-|4^PuGU;Q<cL8xk10bvw
z8sbKX>2gm7({!ttl9|m@(`Aum*8MoKP2qSPB0hMeYaVGp_D6$G;h;s_658PkVpI+H
z)ny&Ifu>-VyvX=pM_8QWmtk=tn+lK+L3;k4Tv?Y07r~df>Xo3^)-!sfv;9*4=j@`f
zTY&fY{JQO?;=NIu1VI=cFr@hKZ$SuBN4bXCWB$iQj{#EUZpJTSXjp#+cG{Wcx6q4o
z>*ubV1j+54zr^)dgJ1|p{+jZGpx!?-1x9f4B7uLz)2(VEHJ}PxQ*|Dmvj>Up^3dv$
zLz#he^k^Xida9yYtG*Lmqq9tO@vKUjL!KYbI*SpWGymUj=S`5)s$Vha;rV*(j!`9G
zet+OZk^#HE$qNbeKgazu917XX#&_F9pS>>#>3<SRl;@UjCbr?275)SFZom+@WgMgf
z|6@|R6fi(?j~vZy?0<>m_MwTorYiZeLu$)1FnngPhWY;-8z{Bf6?`1u8GFiX(5HXu
zr%t1@iNc2a4W!zuGi~Htq_7)gKsEk{oGR^6la3g6%3hJ$!JQsCx++ipw8yPQZj+s_
zoy8K)eB1CC`SHeU0L$ljy6#IqEpgn1;QzgLMk0jADh<fjH|O2OM)I?>g8)!_|1|Ud
z#s4Cdk5IiWH15ae0kHXK6zu2JR8mq>07ZI7#%j_SZPw?7bqKQi_V1sF&^77l73x91
zZ-h8Jna7+fr`F#%r*Le&M@m@tJbN68vSLr4R|y}lPBEIEhrNKM^WLlaoH3gohRzF>
zJ}9s+Bl}fhNXl)_wA&>|aJtpQv6L{^#nkl+NTmac_K_;`EWCs(sIyF0hMJ~T?wOfv
z!z@zN|9JZm{|n-u>EvY(&H}>&`t(>qUjBpx_9szKJx)?$b>OIGsl?-y9s>Q1^Y=a{
zKD37p&--HFMMuC^p`i1iG7FgZeJS+NHpI#1-Yb5Q^1RP8BBk;Re5z<iH@d?}FgmWc
zH8H^9E7#YxnomDM9k(g6k8NMas*UlnZv8S>RNXaSRGl<goc|^gp1t#%RWr8!@yz}E
z?3_yp_g)R=jM(Tibee#X<pID{cA2;7Y4C%KI~%-JTDrQN`60Y`OD)o#8VZpFl_#Mm
z<=uWEP6*J)$I3c5rkjpZu=Pn<4%=L0{yBcPalpz}`nJL{|B&q~u72g!=H{4^s)Z->
zIIazSdbu)CBC@`A?V5tDED2soI*&k@=<25xU;?Y9$_jL{o3%mzMZNCK4sYoyE0grG
zNg`?L^P+@%%$HI~wtSlh<~0{fc^=sF(V(kuh2CK$bjt;V-VW>kA{*sM#)=PjkHT(6
zJxssrekc6|6*z?Kk`yLfKA`Wik|7u+$z?9)eu^y_G4Tuz$rY`m6O*r76z)%9`Q@Jp
z3_pXDjF0nvXdtW}g$JvHb%G@Ft)EVp5_W>>{6&Bij!|)O#AcHx)Uku6KEi`#Va=$&
z7Q65~8tX5rd@$SoZvgW!GBGKF=PGdeMqC7-&rwrT_U+x>wh4C{E)6wUL3rvC;c-!4
znBRG}fqzC4n1Np^{r2F;e-yEb&(Ad%*t=E<huqe#i2#MBYyDX93%|}&pFGR!t1KE!
z1J4QC-{SPYT55a<wRBM1@_Ky>XVjg2sX%)}?IaI){=&b{H$Uip2mb}>u4v*XYJsaf
z&sgt&N8j7UYRGHqp)dD@CN#9I9sxqK31uuhtb+|KJR%2XPesWM+G6>)Es|iAqJLpw
z-6fwpSW!(%?%zwV;ixwoJ!W#Vj+kccEq|<8>_=8Jl6OePcgTj|mI0s!GAKAJIwoD0
zKK0Vu2G<hTUJ2J<h|mdtH(H>4mZRlvV}l0nO3OP`(vruC=~B{}%{%4_`vO*<h8uAw
z%L2FiVRp<Fuxdt7ajgkm6Azu1@{MJ=FyqJ0@(y|JKYMzT?!cQUvzC-4;gT81K;H5J
zI18Yz>pcP&2|u@IXtK(o%A4<>%3G>to(u51cChb@tGW)_ulhd)53{BYv;MP;88i)T
zi@`f}=Kr+eh|40Q6tIVV4<9%Zcdf6rxGv=Uke9-=mqI1B#}N38!XL#*)}Zt_B7ArW
zV9~&;_doQRT~@9glC5+dl&oO%Tnb?}mfWH~PaVwsN4Q_KB|WbM{VqNIVpS+@q~JQp
zM}BUDu1t6zK9$5-mCDS!fBdI#=l+_Ssc9kV`$80UsH6gzvT>C~D1ubFg_%`anf>|e
zwqqxt1+8I<+xmS|Yu4baWQyw>Ai6mQ3_7-?q~wT4gv<48kLzqkl`~g+Xc6UE!%DG{
zZYEL>5Cp9B{aF!#!0>$O4~B~V){=9xq10g)E}j1@mgD=mUd*4PwN0m_Mx!b=%Gg_k
z>wgsX=FSiQEr}V|!eHJPDGo!aqecmJ{xrd;Opp$~iLH$r8IRpie*dacPqS1w^0rpB
zF7Pl{eo(Vq5>Z~-KW(29xl|f={sOvb&haB<W`qmy%fNCQ7f`SNo%O;IZ^Q7lEE-rx
z8z~Hw?6&)iTsmBJo3*d_Em5xbD3QWWXVpZw1cd(Q0&&DjfW+~dEPbIA%;z4Kt;Iz8
z3WKIm9S!WmVLOh3iH#pWY_n%OI@eCHHe?=Y7B}V3uB-+*3Y#2`c^K3efx+J!W?ec|
zm1i^tm(grSM~c^KntFk=evolgn)^eWQInMVFL3Z{ak)dFu(0s$Le$2=@KK~zA>CWX
z`-Ulpx|<$1V#8~m&glZB%icay3@nnK6z`B@2g;3LeRK*qD;mFg<yyb@Z^0lZy1DjS
z*ZrsUxwa2y-ysbSt-*=)`Sa(rb^H=cJmb&K17*5MxB?!)`g`602MQF#bar>4%&(jV
zz~V5I$0?K-qH_Pg_mwoiC@F~nvFqmYrBMYKH#fT$G5fxEgOC>chCXRZx^W8_+Ua9(
zS%Zs&Wy2EQpqu9pVoCY1iQ5M@AZuYxUUwP`Gl>u08~pfi#105*crvWQJBELTeh98W
zxF`Zk^dNXN8++(7%o;SHxY*z{&eL`Rfzo&iBEwD85voaszmyIJg=_^g4NCo&PZ7(Z
zg4bdio-n$;8cLejG7N#dAmqNP+fp8WL8>%MQT;C6u`Lu=f|19=cJD?)xM5me1OSRW
z5Z>UU+e0`7xSC)jH%lC;^Ik){`#`zxfWQ8-S`h=Yg<-@yh&mi4r|j_GDxc#o`;7an
zoqaK3pu)84!iZm2()ii6^&9<W)$S>^=qRfpm7eeZv+qD^%O;O|ei{034g??t|8ZaL
z%@L{S#_%9WeLng4SbgOx!LDe0ts7H_uk%OoXM+`d*Y-E^$T?A7;1|tL(KtM--S)e@
z&eOC0XL;gg;*(Gskko>-^Cct3zCO;;JJ@G0_HwV+Ry@<uJvXo$%M|34fbH8{-YQDt
z&5_!QJe#oUAbsKXn#h!Iw(CD$!ISVw=_~`Rbg>nc2tbO=;Jly%OUZ)J*<w!O`@!8?
z%>L!n0B%J2xfEw}1PE+Ab?4hyn`D%2_g|;U`(Ua9fdydY;5iWHp9hAUwF3FEIKpI5
z=Uy*(LA9$vGC)MG-8b<~tH7k|Kaz9OGG3%#+5PnRp46VdFL4}3N<s$z(w`LeOGz|1
zs_xn}@KR?B@_-$*JcsPSsELXK82-}DTl0c1S)|x}9%F?EAI-5t014nffSev}^Gs*_
zD$rRfH%`ivhdLIAXd8cW^6#4Sd}``HXL||1QTEB5ZC9TR46d)`GG9Qe%?~054D0bc
zrnVPhap7xXN~8byc1P4HNf~kS)wS@tL96djZ09vUaa;hq!s!jn{qL&~1cMm4_qyXP
z1Se#muqa7f0H~fy_0@zus#}8DiC5jf9k4=M<(HEL@f^Q*I<-1hXQnHXszZc~uNTLj
z?=Mzcg^$*Z!A#`$2Gi4D))tX>F0K{;25<H2r^lpIJMl?%P#wZhRXg5qE#M(1Pj7&+
zZ`32O;C=Sbrf{e*u(S62WeR*a!+so&rUFR_w0_q=F!{%q0$&D<FPsu=>ovS8F8#|i
zA%fhwk(4+NQc=5;LSD>26pZ;XUf)7}#q_1d3+6TljF8v8F*{^W7KGZSzpQ(=ND-pG
zGYWEx#%%6r`+ln50~JS;n`V18LnFK`<NbYogyGk(oIBdGO{9Ha+>;3+F*E^&f{ldd
z?5<Op+%wp4=f#H$L#XQ+Jb3oY&|UM7i~o$ySOf&XK6d@%bkldD({m~uZEiS*F(IA<
z#_%cZ^aaKai+A4{%d=W3VU9P8cLUgo<0^D-Aa@EA(v1}q@;3^jS1=FBsLQtZRz0{$
z0U<-liPK0oHdg^VTfw4|39InIN2h-T$`p8xZ``Sib=&<dnY~?CM$a!V>ka^1wJQq#
zPR-k&{;2w5Nc!lMjV={TTsoP(C8K0vUfpn4Qdq&F$9eQyReV=fs?&5viT6sW9~GAh
zH9YwKW&Fpd!NPrOPC0x5$HaJ=`V%Sk1~%#9yOvAM75sI&ZfDdk69Y)|UZ=I6(AaBw
zmI8)wKa1Y=m=wn-m>Q|bL~@6@%)bCxtTBKSq%a0p7TY0sh7gj~IdlYVQBL98z3Fxr
zsF`H~w#DHrY~Tz946xkIHG+HN%}ZgE?JkRh@zfuHAL>1irqBM&YG~>^!0Lu>B87o6
zPPJiEE1c`SVtMWA6uCDV`!(2}r19R05p8CMpb!WC`Idv!#w{(@jlx7}c`H!F^L8_7
zKn4=#Wl_=D0CAi`D=7d9XyOoC9^^%&KtwHq1faPQN%AhgcEsKT52-)KS6NjRz2|V9
zl>u!aJs@9qfiXLi15fVZ>PrTb99Yjc_Rs3TE5V%wS0wq;x)m>Z7%wTpa2U1(*rb^W
zD9>uR1)5*>=)k!KDyi9DpC24OPRDETP;7F2MxiJ`8XrEfuilgC32|sr5JzKAsxQWq
z9b!}ca(J`P$-X%CaZMb``mIb<K!Cp{KLI^Apit+0<6W@Ttn!8*6>P7{DDQoSCPX|-
zRy^Mj5{d2yR4E<Rxe!)RpU#k4+9dO7=5<C%lsg1|hH3^+)&K2zAK)&qVfNFT{S{(D
zKU;My+1>*yW3Tq{**Lui6WX(OL3hd{a}-k$DlBk=m~NV`;1NB#QavHEl+oYn#@Tm1
z2)|#S7zT_VrvU=mZt@lJA)gQJNAWxc-v{4sV{3DuG>``5B=JtD;tM~(n-KSaXNBo4
zuS9%&A{qO-V5n7Vl9%veN$?Q^8q}}p)SiRVjag5~7Mm}9*^ksUzrGCfo%4)_c%`WC
zk$tZ;9|97^{45O`1qrV_E0ELsKJ~VvG=u}8(4HJfW;eS#6tUOk^`tjrvH6@&M0kaP
zs_Lg*z{{R~o>Q;;DWf6Dy*ZrD68a3j@)H$^8eXs-5`43>_4eb@7Evf>Vv~)I1?(yY
z;KM-~^`(DpWCaldqh2GAI(4AqSAvulOY=Qvng-?p+Xql{Mguv_d-7y0mEit<b!dZ%
z*OJPwT={4rE5i>tAC2+UcOM~8-r%*U)C*{c0jFTiUBgU@>b-ch>lSB>CzBK|0t|S^
zG%)wuhByX5l3BgJNXURt9)Rd)eCxqB03nEV;v>x5Uc!K$w(h){!z<y^r%!_H5ZH)8
z^ZnqOJ49=59)bc6sQ-I{-2#w-1#-N!XTXPBg52|71|C6Rldf@nM@4-*D1DR)Pi9&|
z1w-gA4Gvb8bY(08w{Gc=FsgVH)Vtt0no-j9SYh`5t%8t>hbv1C3?ZywpUInfMg<h0
z<wqLplD*zd&Ahn;;2DT`GzV)g_l|1c2a!WflfrttzUE`~`5dO_)I!6*N3NY}|7cpK
zG%>X$x#x8ka<cK=sTb(fM0a=WAXlZ8zVqIm5bJ?DNlmGF8zoV@<6&<~`uT>pfOPB+
z>rS`(#P!^<XV5`uJZ-7Sm#aCqr*<TSo)Ffu8jvJ=1>FkF`0z?7o0pv1CksgbAq!Fx
zsP~cgME8*5fYNd)_f@K5zWwwdMi%8F4At9=`vZJ3?@o<~rvDgzSud*;J9z~EkqAhw
zvSfl5A{+pgdml#53~>+|ZXaaGDpD^)N#e{(;FTb<6|guU6=IV%jPEr`%H19<PZ*1a
zz($8S%eW19l@SVxonHB!P5u230rh+eQ<h{TSu?n}JI><&nrYK&KJ?nPQVX7yVO9^Y
zof{-N4O2h3<7;4r4e`Hr4m;R>4i@j%F%{*(+sFLNV_Hb)+CQe(zwSGSpk>O-N_*J~
z-W*94GXBnNA#t9XEAXIN0tjyah9_wCD>n%sJ&5M<-O0G6;IaZ~!ezqiHlWJjZ4Yh;
z96@YJC~4?%+Tq)8qJB;Jdw$5!G~DIoiy}RBik@eE*<Hfp!6^26HU*%I+4B*$4^h!r
z5?}<UF;J++lR@KiJGFH^YzgdW`eqA2Lj@V#eXy%3ttFXHyvNX)*`n$^bsioJER*IV
z#s8ImxI3HXadfrLae|6O^iwV0_p{uc;ZqDPvtA06#Bu)Q!6><XXurd|05LU}2^ki-
z`yCtYcia+~ap~&54Cxy_epLEO9$WgxweTY}Kzw-2_9u{Rc0mJdx`~Pgb&;KTM{+YQ
zt=Ng+4?RDRc>jOzV>P7U=H~uz_t*&;KFx^ik`hfpS=3=#1V?GaqzAv==qUpp;gSH@
z-v(%=diH4qX%l>(p#kZsS4_qFyQ6@_J_;uh&$f6l%vx}elO58hfItGS8Ol)3DV!jt
z`xzA>5E1$^A~XmheDV?9MlO#4MX0@ftQjN$G2bKYWd;WY9U<YTjXcbF!X}-pGInB-
zp1w0m)&V9HU|V>Z3s5NIOod_lj3O~z*xf&}p+)G<bSsKHSEz)*>GNFB??NQxt)Dp*
z-Merx<spFg=7ApppYc^P*>wnT(2ap)5uug;qyR4|;y#!@-_8`=xc>p<#;$?^VG~=%
z)==6qc4;-}Rxu6av{ubPZeY&C!^sWI1>{pvn+|*0Z2!ro@Ulzy_7heN`|~1F^E?YC
znANIoJu_CGtr24CJSMgA>p!yePJP{^+eV^dCd-FJo!co%{)<45kKL_nK|zTdz}1I|
z+kRTLbI^Q(a#mhze_4tC6P);H1NhnTD!=Fa^`EhP|4KL+@%}hnF*2z1RzMNRcMs>{
zd5h+lZa_>0P@TW8D*2b!Xw+X*Hx1qeL^#;ZeAOpcYYN&LE!9hSvf5v~Mo&@s*Anj&
zZ3-t&R#5k>Cz7X)P)fJ-fDE)9E&$H~RF=_C_uomLwzBhHN~wVOwomsffy=JWgQCRW
zI`IF6pP>w8Ww3OylT~)1^u;ynLx1)H=q{2}cD_jN;@UkR(fPcNg4}-XUur@EvY_kI
z<aar}8{1r0O1Vz}<o4P1o`z(vp<<&aWl`zce^BbVe^cteFL}0?f9c%XJx+I?dh#za
zkOXP<XykyI-KP^9AHal1NSD=c$OjNrE-SmIiwFD&7|J0r^nb!M$qoXjBxHM*R!pR-
zR(<&vw*~E)Ha33vFQ);qn9F<41)5};F^B9k1Uoz{HJGN`qGIQpV%0@|+WX^f1F3>K
z!k|TNC17DeNu6rltD~#)r`J8Ne{xA;I$FfO1+IJl+$Z9&S)T6hQO8bDMeX=j#9GW>
zy$FgW9{^YWRWi%m%{nWo!;y*u6hgi@gjQxZ)$-m3%xy&Ir^o}l{U`1oP|6VIN;U7O
zuD+IAxc!wmnO+bN3UMpJ;KbL+(7LsB?*B@N{tH?qn+agIRrZr7h~?HCBgwbmRbJ1k
zWWg`PcQXWk|HTGAKD8yTuus9<y!MA>%RLvz?8;_+LMwvV!k2QR<lVwe)VcM)R^ZdU
z|IGtyJ%p{M(p7mpnDyhd%6Qk<85n-!&?o)3xjA=$R|dh3cFvFeadX$+a_c<Lps7LL
z{`vX{I63|$sy%&p=o!2@?H^Ba$hsa<=VYyIPtKKrZAM^mVgOm4+iw-^iUM@~MQ9&c
zaq(BKBRSIV8sqTcS^o^;y=Px9HOuK6GU7=XrM090%(e<GB6t%xQLuzBnAeh&Ildx;
z{?M$7tu3K0Abvt@ezjqeCqRL;=6k8F8Ndu7W*d4%<7|bw_b=$Z4Ocsgjc1<Bpt$7G
z?VoU{sp^M?jnD1Zp~A-3#-J=vdAQfX^Z7EA&gZ#Ek!9}lMZllx9FWPHm9yso&5MM%
zLwnvtg`sjcP#01IbO{Z>2M3gY^Lf-ENB+~|4@XXQlIJw9(Q3RSnVDO&MvF0>Zszi5
zF%&7?)PZSf8T&RvEMm82Ed(^6h8j8pm27;u?Yaw3-5`A*95TyT6H0f;(SL!8R)FYG
zfG7uK5b{{K%c}!4AS`{%j!3#U6u=J4KYR`{=(7ImCL96-;|KL9SE$U^Z2V}SJud`>
zCWtuKW_>9)v!P+my6T_cwG~y6e%I@D+p7G`5?d?qa8%9Ofl4@>rj)OiY+>BzOHY54
zfs&>Kz>vHUU2YCsJ#;#~?gO>kYHjI$RpKvrutU)Vz>f4EzVS*SBN_<FyS^$<PuW>y
zhW-Yd!b3yK8bz(*_=<XP#R`;UXvi`jh+}`=0Rag_=W_q!zm7=vvJ|()i37ACP75lN
z2;?j92FsHZNAnsfxmOvFa_p1n<up1vI^lp}RJF3o`Ok*|Vc6DIB5WVv(wyPCPmr5b
z#<m|2<aZ&0yhjw&cX|=s9UW{wX0D>TMJ99y6zKQ1o7aEZYy~crPH*VP%gyqEaxJL8
zeoLJN!6=ld3R~bvUpC)L8%(u66nU`L<e48Vc|+pj;zq!Rf+uIW<Tds6xe_m30eHtj
z`k2d|bmn8NZH1#YJ&a}2mFB1+sZU@3E&WbrlxV1a{P^)Wt<FAYu74JB5n@yRDn)~m
zZt#|&@qc^S1sVW78S9I4AW*HJ>!twZa$<b=nVTpxnfdJ&%FGP#cLxyQ<wDC&NX-A`
zJ~*ma7d1Ig!w+fPv~!4=KLPxy1;f1ouz&k&FL4yd%E}75_puP?P)i}Sd4cwt=Wn42
z?){qmCbUI}Wce}y{4tlPw{PW=BSXoL$7Ox5Ujwf_KdCr*QMEPghH}|M&h(W2J}uVe
za}MWO5$~w{kNZKO3ZVj4_afnr|M58BH=uVy$jDe}o`Tl_+k&ys{^DmeQxt&=)~jt_
zi;rm@`OhaT-bM7>zHW4tz{bvAP`+CSHp|ifzv|vQoa_Gm8<!NJkgTMv2-&l2%9fFl
zJ>pGBWbZN)QXzX~Cp&wVz4r`dZ?d!R^QAtY>-ygJaooS(@6TVy;W}J+KVQ#rKF{-U
zKF;x~lt+7#@3e{f^i(eLvV(Ryz8T~<yy}Nc6;Zv@e1%>RZ!E@ycqF7(H#;?9CTcuh
z;Z$94TnS~>1g9T2YQFsGDMoN~m6tje{Z*P_v3bai5Y`S~<$i87qG)2b{L`dM{WL#f
z>(sx4xS{tdigebGii*l|^he-@=ohlGvN+XGe?QRqT7-wBi52)*-ILn+{hwMsBt^fB
z!CP4WTG#2!kP;mH@24|E6RjsGi-v?W4!O}2SlCL@aXZxgek{hJWQMf44EyzRje@2A
zs$RXVU(q|BX=`7EU4F~CX$l%Ppr8C|Yn1dh3ci7~KY)S;*T31x$(i^KM}6-o_<xga
zokLO^@{qVu0y@6RwZw8#-@P+PmmWjIN$RB^F=1i%M@B~OJtG&n3KbsjAdvA%M-D4q
zO^iq^c*wZ+@NvN*lvWa?w_fMH`;D&!a-chvu_R4K=YGDSIK<t@Kyo#%oI2RZ@Kmx?
zxVX5kHTrB{v`$tbAuV8>=LOdzD9P!kgN*!>l{?G+>V58c9_w3?#}#R7eI|keAHy&1
z#DB<$4ZZUO=}f`IHpQNkD<=%?ILJs%9bX_NM!wydG2O_{DIobBQeXesxrbPhH`wJy
z73Mnn)2uyQkZSOiv#)S=sSI`0m&zK1qrXe2eC>Mi`<}ei1IMo4pYd~)A~m1Iex;|R
zZ1=h#Q(c{jPj_6md`A*FWi;WlgCdL&GJy+%@TW$5VrLOb>(|pU1G8wLxTSzpDr|==
zCZ`{TvwQV|?g|bOkPFI6WTe6Ou&965YCXO+EE)9!r3?ik8&B$8rh#a^r)XWZYS`xS
zBe;#8zEUP<kXP$u=ceoj{Z}t>dIts?w4~{%s4{AM9TsJ6skm}(anjyeXnvQtKzO6q
z_`FN7yIC@w?Qzn}m&17M&_|{nva)VM7o(}u{r_q5^Rg5YWx`^-0u+`3X@gkv2lez_
z;XC<3&hZAM`Ex7bPNHA;-5{g9$~=4VAzO)aS?K<<u&(yVoMN}F86NO-P98U)JYv{W
zrDxa*SG3;A5N869jBc?JH^jYjd6>bbq}pR|W9DNq0p%q~^PDU6W1li~aNd95CcQ#(
zK(e&n85h^Rw|r0DKFIyYx<;+1=lknMVzXuJP<-}aap-F&n)~_Jk}{{;nuzf9{a;!C
zTXceTO5Fc%MJL&DEH}*x%k`xU);HBcfaQLZFe#v+_JRFm%zw8dI!&)}43iXZ#o4M+
zkR12?#=YgwSC9MeZstN={<GdfB;}5f`v}U<5B$ilFPM@0?{c(F33ED>!6lo894W}c
zI}5ksdd422%X}u0@{-ttTz%&4<H;=yU9?x&cqv61N2An>M?oGQBNL)XhW4&QX?gj&
zu2yK=3uH2M7E$!w?Z<bLIB}zRSr=Y)h4JHZDhff}i>LbH<m9aO7Z%TfR$XW3hC^$q
zn&scfc@{!qwR2EQ-zA&}yZulfywwxVeqyeQMbXW3Dtq<RNW~Xrx}xi#_I*h7?Jq5k
zo1)_SB7?+Na^mtWIDtrYu1-O*BIJ(RL!t!>J_)3h1h`Ox;bUN*lZ{%L;1{aZo-(rS
zx{I7;ip)q#{WOqWQhP4uE{9qKD%Th@C(c2UP{fu?L|$q2#%46T02S4Q&1%)7e4`6=
zR*Vr)6fquQ;`LQzwoUqXkK3a*MjNV_W9nVASid#G0Ko<!?nnx?U-J=rSL3b8#;dBx
z@OlZknVDKn^I?&ly~F@H#;~)ENUevBUZDvgGGT<xPm4cVgF1)X@eVdiWg!!DSw$89
zcS3(y?~AYV%25y#6n!*acp#s)12ndznoq8|;~7GZ!KceZ5x+}q=6I}kG5Pz@)Yn4A
zwX~vtDxw!*U7{eU{BTvdhQ;ZLU13LllpK^x_2qg(Md8*x`BSB?eh$*@!o08jp$Czu
zmm<Z%Dc=uOI*x{EGu%P(y#D_$NdJmEw;;fQkkjwlGviZqi!aFo+jpCtPI>Kn{(Dl-
zmKVl_xT#KdWGKke)6BBQ;<TL}{c+;HlO{&r1R6L0aU;^egW8!K{U`}qIxG+6dF|%1
zElptPs4vb_otq6aN<Dn?_N33}xVrg`e$IdsXa(BxWhfs;uVrnUil^XNCv`uMBp%<I
zo`$kZk|g2Hdy}hjz8(->X*J*1V5b$9eYST}!EYm6^qlVdjq&3$eMN$g<p~=(vW?QF
zZ+&-pw~cS+0h#?C2(UgAej$EH8x*is3wJs+Sytuujr?qI9V=GQ&3W`pB4Nt*TQ6p<
zqPL$uF+N`%y@M<KmJ$%d^k}I~GL%w4AFcaVSTDJk>*U-Cmai%&s43{)<zi!J(T`Cw
zaVxYeVHsm$V>?L9HaJ(Y-uY$~Gz2#0=}C-&nVK}*D)h=;U(!sCh#gdd@<FGSev*y!
zpC57hv3&`aN^gmY8l&VeG<FAFH@>EdZRl`%ylH`$#O7>;x8HfCAKxj8b5u5u<#*OV
z?|xcEm8h>Y%pSkKz$H+_MnD*mNM+L)7+pcf&b}TU_aIK>n3k5-?$L*mt=KY8icJe0
z48$HeAxYk3cVu%eG+)4j>K~k_x7W82d6%C*lw?+4x}Dh!3fO!75UF~+ncMkt2{g%R
zPJJaMZ{*@nJqWkmTP&LmLBawosy($8pnIv^$8{W7{{$Yy#UGft<~Z1tm~xN1mC^LL
zPhdT>gswcvWz)=1;v%bm`^y9g)YqCKy^I3=EIBxBUD2n6sO-cX+fbFdC#-o2Lp4=M
z>kSvN-(N1Ts+MK5clI8Ss$xJdj3y7~D0}5u+IH{J+#3Jk$G$$(7>+*1`+J}bFPt`}
zkg1L*gNl|tGYam{HDoL3?)KI{P1b|YSW$rfIW1*TU)ENz`}Lp5g^4Qj(%_qw5fQi9
zzqJm}Ee6j=d%bp7lgsfqSUA$ch|kF1E}VOc4Y_~zL?*Xw_XTytLFC!QZF?gU%kDX>
zT{zF%c_E-dKBkPDWp%gEFusPOxd0~#`MQ6?f30~9)t()XFO*ehGenpZk<(>IB(lR8
ziy(x4_lMyH>Wk+O8c|NZq}P!Q+GBPd6dQkXjf3j|o8FH=KcAd|JH`<JgimYD3{Oj~
zPb*VO6~c?F_!HMRiy+>YC}fSoU1Nd9BY*1~Qp3xsAz;Mx%mvKjo7G1qHd0{uGx^k4
zCf&`*4DmzVg=-JT{jBkhm^qEa-k0xU)atKEO;P4Blv>7xkob5D=0WGZ)n6eB9mlQ%
zpNGRuIv-Tf?OYhY9-3uKkEvD`aO^PTb;ss%mFq_Ha642Ol{>YBmP~z}N?psvr6}Qa
zeW8c8rk%1Gx&I|?E>t+9KP3FpPH_8kyaz$~ES^Xg2%#yC3ht{(X~s9nT8B(_%wl`L
z1LQhg=Izrmb!}X&y9;9CX`~GmBgEwwccpi3n-%h}9h8X9s1bT_xa$2UEYp6l%-G>Y
z2N9@lg2d^O;iIF|!wRp#_Zk*9kuVuGxsFGXgYpfGA5q1%YY^3acL!PIMYz3_3uK#;
zcmM~@sxw*zk;07y{*}(Ss=Q98eL0VDq!Gz=_g>vxp$Qo>@#PYa{5YA|yOx<L`nl?b
zw{vrP>+iATHr5NcQtsSYLLagVW0?*1f~A&V){zMu#lOyF@f3O-M8oyBo_T~LS;T~t
z)~c|hJCg<q$&h62+D_`<!zrHFB&+##GDei5Gwt7uJw+#i!p?nox>IqK|C6Wm{PAJP
zF$NK+>?cQ#H=f-h*?qDL84+H)yoXOU-smTYDiWxw5%MOvTL@mi%hvTvL_{PCGwDs7
z5reO8S>V@N>U>Nm3Fd3d1Yv2g<i&+MGYZ$QcenO|^hGPAvv)=WOvZk@b@olg{6L-a
zVi$ICt00keQN$x`Y*m%yOD@`}Lf=&n4H4Zz<Oo(@38^(|r+L2K^&;{Djd(Bp`NjOk
zbI>=VmRJ<<rwKsy#hRLBzX*}qvvQAm^f${6o%>_wgs^n7Y*5iiA^K@HIK@0tMbG&*
zp~u!NSRd<7rH5>egNV#YX$y;}kJ}rWb>DEu+R~~lev7@BZCZDz*m3_5=laDXfHL-C
zBfd%<p-X><nZVYR@Z*3)X!tg{6ur*IY0*H6YN~T=a1;9!J(#@b<tG^T<hmLDkzcka
z>851SEoa9%md#%vl%;(65dq14j%LpDTH1PKsSk!M7_NKPztK`mezQmF2!6<E^QgU+
zn9|>;N)r*5S%Ol>To1Vc{2$X#XvFdxF`=-BjOYXZh`CDY055H8e5Eo8l$9w`YGIV$
zQ2x1``JW^HRX_-)_@mYN%PQXJXtiw9!r@FAPfPGDjYuWfaB*qVk^F`=4aVh925w|5
zsP=c0g^<eenzQZ&i!bzAd5LT%(m;{4Gjb|2k-*=}*GI^>%6Zpu0J*VV0!hSWP7idE
zhFs5(q9YrFzz*Jc)2zr1`X>acR@3*3J4>q=J-SzH3iaAJXQ>Ev9+42cEBQ0xpX_3N
z6+GX)XSO|^f(S0s<IH9=ro!|s9b@B|NeAwqb}S8Dh`Mc%Ys22Ue$*$0I57x7TDJ16
zfkW1rin~~?|63fpu5ADG0wZ$GKLpqv+av*eeU)7#ir0>Wc%!9sa(_Bpq(#ypHYUd9
zE4r+A^a<81WuH-|ONot<)OM5YvWqV4A}y!*40~L;r?|fdufK|}!429UOE5@OD0PyT
zyCJZ=-u6eV<(nyz<MM0TIrs69E3NSh3Oi3v30m8QN=37ybR0Gt<D!W3yZ1lQ==>f+
zCydR3ljMlFk6!JMQ@&RIMsn-MdE|D$F#4|sagWYc6{NX9jihITi4W2Yh7){4Giapv
z0%-(U-0_nWyk{b)BS}O$XZD5NEyBvj!y`Oe{BxJ#N-yh!sks&N@_ZO1EUekBHV5oQ
z_VHxKY0>`HiHu30-ZI+z9~C4@eFsVtiAGOS$5T(k>X7KsC(j;pWP`F;%|Uvb(nzLW
zyoe>WNt!LYdljl!mN*CaJl7+V$T<%ENgb-^?}%5%NAT7$-5u5@z0rA9;5PMlZAu!O
zHo4|7+(iZ)M%}BUT{={^^(F>}>~6kESyDUH$J^{@IW2xxR?yHFUH(x|!(q~u+pKVL
zJ?eu%ow?=){*MxRzx_@ZYQ=Ct7E@QXCTMi{6KPh~2r_UDsUU|*7(TKpV|5AZ804Lr
zK#H(9;NWmbM5S@x5nTSG$vF=#O#bc$kvgVm{X{;a?{dUEf99#LNBDs&0?-TomC&sO
zC}z0^>)U`5Ii$Uo@Lg0D3Ta;%;ji%$>A5B0GxO$BOoZSp*vDT;*F~iG{<i2;fmj_%
z>t)A~4uO#q6YE_Mxkr}E5xJv7Ki7vJN-lB4k+QR!xBT*NkXlJ@lSY&k!lIZ$JEL=;
zw1TiXeP17ye>T|Vb-_iaM+GC7`L3y$a~D!VnNt(kh#(9Bm`ejImjj;`8q$ymshdX{
zWTZn!O*W+OU97=dC&St0_}xS-nG`7c|Et#Rw+du2iPX`+UATXK68caSMsB$vP4adY
zb$-Trl7b9PKvTy$DEle~xtfB0pL0m%3T*6TH~S_xQkQ(^HZA>&deAOvDo8IX>^8^c
z<*Tal&wPF*sS9?#888-L*9>3xKB;S)Cm?+O@es;z2EC`f3#NRAnRJnDL$0h*wcgeb
zC(I?cHNpLicSz5ob)c>$kY^#!gjN8*16zMxhut^K>C(Wa1S_^ao=r`<+iUqc;mUWk
z{~jeha+IgtLn2=ljNqE2p9yhf<%CvF(4T>vFx35|>D?3Yv(V!e8<AG%-!TGhIGU_<
z%ECKKaGxOxBdTjJ*m((8XaE-+MWTS+c=GrzEdrzA3R=czb#<Q^K2Y=VEb;bzVtPpy
zjCcacosXuls=G!fkZur$$2`QV#{=FS9x8-)Pn1qQG^p3l^HE4*ci!Je30y-;dZArv
zHgYlup#W`DQHc4kk}>)1<K*Ak=rO>}{*XBKuG-%-`c**T{kI{A5$%$pqlva{UvNA9
zw=I|3=d9uS!P(+#T|o+&g6QhUD$u2O#1W_P0C^akpFz-Gb7{w^!Lxzt@O@1zVdwtM
z<yZb14}F)O(;uAB@lzwN!F36J-K#y$ZERZFL+CU-qi!9<6^Kf2s}*naVFing2D?{n
zjP(_oAa|eZa=vw@&^hqhUAxbx)yPoVI(G(J^!@}=G1Mey!T#l{S&eRGz@FYF(Y4B!
z3f9lB4Z+MJhrkJaDdiORkC3lfW3G17!UifsYpeRC>Lqi6FI8r|+Tr{f{0ufdC&doO
zU!TUz#d;XGzGv2`W;nilli&&(I!3Oxe%>Sfb@Ma+p;G>#M$tuLQJ1B^nj1Rg;UpJ6
z=JzKo?$vg2=>3v6#`Sb=InE`vNZQ5Y%MN!{N8Ow*Mf?)i(`!ujbasa{y*4fs{bd;@
z&XwlY9=G-M&!F!cD52*bx}&N%_vo2IT<zoM4usY=t1QGqeuuJ1G<^A$`_@ETsouQ7
zXEq^IHz}$0Ky!~%^S;NNHyyw3!cDPkKdjR0)Ey2X)05*P(~`ybj|lbK8FlE1?XJ{u
zPLiz$I!XxWVX`sukOX1}%3zB5t=-Oa81Uw^k+cim>fza>DSJ;!SWqtY`Ac-2Ou6*E
zv4`(y9SUWh9b)el_+D5WRO_?oXVHmCV6y-E<tib^-8mw=YWl>ocB1@Iw8mz)FpS=B
z@p%#hKV0CGdoHvn2UWuOiX@)Bpl4ZhH7&X(QE1=ox_+C93edz6biSG!XngM1z!~_u
z{ag}yQqR{%>T8RaC+lWMlKHCo4-<N(r3j6fXx9?<3s~3q-Lo?7R8H188?UdM;7lc1
z->glueMcwuOvb^fa`CIa)y!5{OO-*Ce!AxNChz5==&ou4dDnsIVl$uYZrFiF{=dto
ziOV4%C5pz8I46-(o0mPVL1?I>ob3OOPBMy8D`h>)JMfv?X6E!vYNlP#aj{+hYDVJP
zxt{t9bg4IHX=w<^dcWx^?H<t9H(NKH`NmXv?|r$Mf*x>F1INql_fA;0){Nxci&*AA
zQz9!gsk0%kdp1}1pEVjnp|zn`vJ_#GDwp)Q1@q|fSX$E%y-rr9Mj^jN;JJG=L=Qet
z$3+nTO0`wLNzfouo+)i*Ci~R$34Q;G4x@jL&>pwU3;RH8IL+Y)$Rl`h|1PE;^+@>5
zw)8u*#{stFd9>5K9$|;YOxXiE^`BxD7%9kum?Gb*yeg}sZmrv_)y;9v<ss;yEn#dP
zwI}pAHV@l=hC0$3DNV@41R*IRgqd$forU1(*Yuk7p$L?8o^J8D(bL1socGJy*#jEt
zE1r_rl6=ilSY)v_bT~9GY4#HJ6_<F6iM#Ic<wbJoo-rrUS$*~;?sX{&nWjBD46941
zuVTSMN<<oF_sy5CY_xILcj4P$ldO8BrbAe!{cL+<N)rfp1;beVX25|z-w*kwZx3vK
zY<^owj>6K~u+j60I*JuxhPf5Qihu|Sv;URkmb+=gelXa99!+GSW>!J=2s`@`TYS%b
zlM;Me*?d3aaLml_IHCN^{%^D2jBUjqF=Axn)!DdQ(7y3%Zbw-Q9TwVOt$4C=T&$^k
z=<xb@=IGhi^cUvF;=TQMms+%GbY@RBW7B-A=2}f97rN*Kbx^jpPI@al=ym5GJ;d*<
zfurEZhl5!1s}@w;6mvT~$|)R0vwbaed^`w2ZI8V+{6OrI+s|CXq|7TdCAUXu2;&Xv
z3_mC=e3ZSNpPBaY(|>XSETwlGD;Gtnr=8nu_QUwqcSLD;YNB2^o`)SAjfAt%UONt-
z;%4pjJK2_Ny(p44Uwh)5I_t2zZ=*y?WTlZ^qUk`f-|<lV$0l5pGu=|_PkeS?m;Hzj
z!|Tr;X&=qIe8bk|3|c&C9cM1#tGNygiTc_7a$d7?^k>2aS%;m%`?VjUU)T={pUmU6
zB0qwm(|-Ks3dA;T3DVBW)GNeE?I#t)4w(u(d#`C*#g8Y?3^V)2-_gz?qcsK}ryi>5
zd_5Y!fuUuIF`~0}B$_+xurvG2g2`iZFQ+#BMe1l%f7!k&Kb?*YqSd4-rZcbkkSXor
z=YPqvG$mX=BSi4ZM4ukNGZrVX<!;xHiv6KaB#V{8SRV^|L{1Kqgtd*8-G415AGWNu
zWpgmFF}`@tskZbf)4uU~KHwOoh*tzwN0f0dK};NY*cg{YPJVa)2=&;qL-pfq?{I!^
zxpCZVu{Xu*{!}Oa{0{4yN9N%=d9~W{F9nqP)7|~AInm-<L1oCe8?%E=B&@DM6}A)R
z(<!Hyinm%u_xM=7*~4Q>y(!*pO})qsa^FXGgsXP@iiA&E>35Is7d$l9J$XHanRAps
z#hm%)TaWs6uQh>%l3%eoxRrazf7Y`+I*&itxriE@hNwHUf4MM#{&yqKOBlzdcN4SC
zx0n^pEcuY=-l{&_XdOIsc%hWXO#W)PrMlf>h4m>-UXSIQkONW)o05;O2b(jfgi-?9
z4TIz}<{o8~utg1!NcQeiGZB#tg*sbuWp);jJ^nz>iK13sSD{Q&=;<|%iMjgxJ`roJ
z=_MGYjq@O{5>1=;&(2fe!p`>yyKnK%tO?IqI<5a;DAT5&Ih_g=Lk}MEB2!`Vw?c(D
z<+qO7Usl@1@Y3}7DdpZ2c{@;>f#3~ldr!ZCuQj#L#zIDrq>a?%$z@#G{Ya~PM+Gip
zxr5{$c5`Z5&>e*b3F@&dUZiIRu_wufF4Wmzo=wW{*s8_J3D?_;9o~qpez_{cS-D64
zy(Q<cW7$}~1&6gl(S0t~A$xBZFUe5Ll4{#u@qM|cXjXjoP-z`C`FreclyxI2P(zKe
zBS@y<DCxbmFcZ<-P#}Bj4W3mT`heYg$&(BosaB)$%z>C8KDJVf_jC;3r7+otOMCO3
zC)8&8*B<ny$cDGDR{b{Ii|+KOJcP?&ySF{}ai-c8l|D0@(7)em;@grVOu~G!z$@f-
z-)jS!GKcCxhy4xs;NKal(SLhY=4bW%Mk@=R^W{%2kD55&u``d}J})jQv%BFJbnxxH
zJKgOCli#%sZizH0F0~)+i@7hnX$X_!%c!S$tmz0Ji1S`V4bO;vYj%_J)(;X9ILrUi
zaaCVmWgwA7yTqzqtm0kV5krq+{Io{wuZq?MX#W*I?|^L2ZGWo?d$CY{X|U=5590Jj
z*E(DLVw%6b0^K7|XrL)fL0ni~+dL^aVYD8Xn?6P%vy_&^@c8cAZu%@~wwT-ZwGH3d
z!9g8=c6|kPD1=mlk5^x+t$zM~Hs~H!HqjrEy#yjlu?XFPXTtT|OJ^h!#^ML%SV3y(
z7gJpi*#ln(X-Iq9KC*FTqQc={*g?-x7n~2dlE$e)`s4%F(R*j=D2`Mb5X^gwaj#PY
zpHwHu{gO_3{FTOs=Bp7^JJ@;!rV9RzpXu;{b?Mi=OR9M1y)>(x4%jPIaQ*SMN&a<W
zL}TbE`p4Fsfi3i78~4w_7VzM2uH|(LI6pVTp_2VBWoS=AFjt<{ocn~jjkw_~nOjdh
z!?j%#?8XH~3L4@9(3(EUVk%AZqhO6j-!ErKdrrC*J8jJXLi*9L9{#iJU%Q`|U0Bew
z+At|W9=5cQtoSv3h**|7`8!TS@nw$USb#w9rYCjb&;+VWsx_#M>I?@whDbM!za&)!
z+V{b?kHHK`hrg%Fz_)vD*2J{vP8WCM(zRy1^}|Vb_!w<z$)KF4&G*bqJJ4x5e{~ug
z=rrwc79B>t603<%WlSrUw=F}Jko4tN5|9SVkd5_5u#LWS-?XIVIkYuOX>j-f&53(!
zEA-xrV7VzdCFASA;1?O;?#PvGv=~B3(RPhOXI#=-JNQmaX>LK8vU&){LJ@i$R*BkQ
z^A-_=C-AFASQ95LfP}TE!qL~VibbbP1-XVT(6CywmqoUmJfP5Z9GbXmyRQ@uwm_Tj
zjwsSl=<HnLx;|NdH6*{J<hKVvfcqgvd^Ub}MD7&F0?LfO`AuIlh<!nsBjR?lSF>0Y
z?8aYo>Hp+R6b6&l1;doFS;pAsX?xEoFL-jFTgP3-m@E|^j%b}Z9?=wlej+Z+tWk+O
zDg`7%*_~SE$Pc(BW|oI-NHQgi_XD;i>Ir+%*%&D#bvS5?`*X&*1A49UuS`5FYf6@t
z1{<`&pp%@|2r87<idMLet@LI8K`hgSUp$_)SOdg=#oK5Kf;3D6lM4qByJ^L_n=aVD
z+VF8KsD=Dlh0<dcl*!sjLZs3Kdf9jV62_MNfijXJAqF~PTz-7f^-qlCaQu?RLKPOM
z<9q4>hJn#z)5+R&?)UOmcWw_Wi%M+U$9PqOW`5z12K38Q`Y>~1!5mk0wDPRDBEf6q
zAsq3@SbD`q3ll7DHFCH(dn8@zISD)`@8#zQuZjsc@=7&g?%v_P0tgcJ56tu<K8@F1
zm7PM;)*B#9;1;L{mwcxE3QvkaGr#y(*XFIi#Jv7n)qH&mUQbc<uSdCVM*sNC&PboS
zcJP2E>9QPg4;y3AxBM}E)WhC;q%0V<&C0a2L?1zLFVf2r0MbehhX%+jYncsSKSc)-
zVE#nC{DWF%Ed)G{4+&xGc0EpZwRF2gS2FB*iB~LDs*bmF21&ynH==Z_t|loTobgs#
zP&DPJ$kK>GfNC019G#d@)~_x5shW3(ifrlI(P>S$pB8A7`jVn$q5Tnqpy84)Uy?Ng
z()5mJ^eml3F$>d1#vXksSK8YMuhxF7lK<GDTA!OyJdQAUpJSx^g=zA)X5~7j#p8Y^
zZlWa5u&9oY&)=LB(uv(o*O2#aiDmM~M-hF&{&VU)s43`web0P7`N>EWMI-jGEOHFP
z>Dpzs88Mx6=7BA**tT)G8NK2bSosdqJff}=!F+>)ur*sK+Ej0fu{_4oZot1v_wCUW
z2d{frB20f2hvh?_%Nzv^;jKrpg)jC4s(%N3AhB0G$QTQ{&rcpEe6lH=!_EL%B_}RT
zF8gzsk`LUPCj_?(PM;F#^7`1qAO<c8SP+5Btb2?%L`aGFU);ljOL1yGqn|TTaYlE<
z3!i*0e6^qTV?XQPqyIQ;KRs53vE8w&NgR$F)+Rrb7lkbXt>3?U75HSL-$l<r<?c0F
zF$8`g!1jBn)`iGn+nwd%gU|Q-l7fXsHojdl6D};zGc`%t=n}{4Cnch?Ufe~ln#p<0
zU}2$}@dJ@xQWIG8WEZHCY&wh#ybZW8!9DCR7>1!q|L4$D#r1}HWBIpFLJHsRuLpaK
zZcJV>V?{<+PudvtI2z=pn?WSB`ch}J2QSz2jURjhX&#oQMvE8x9#3u_3=N+{T(gH|
z^V5BAwcZQfE*E&@;;%BpML-(Xan>In0L3ZN<(VNCYkKN^do&KTMxCad;O?jmGwZK}
z9c55k_S}ry->X)S`VNDAD|)LH1=r1y;WupDmXB-#AGMwDHEX*`tO2Syd(=KUV$66C
z?OVDnos>7SK?uq$W+=uN<GGw~b#QpN$2nkV=Hyg*_!aZUmx?B@5lKX7y3;ETR?BDL
z-}&!VpC#%m#8ZT+;|&R;uDr)qa+v<Aq#$Nz6Jz}XEHo*R*1wN4-%y2)hw$TQWb2G>
zF|mq*@R4n6z~gkcKF~iDK`kK)LK=^iXXiSP6#N|ae+=OD;5n~34*|02<yV<E4hF*$
z|7vs0`}Q)ekt@`)y$`D6Vq{~8J$IQ3Jb+V_{j`PI$T%VHZ3gpP2eZ6Z0Hel-)@Rj6
z_N_QZ>4L~(#sXWSpH*pOd&El&5uRl9$ZJF@uwyQCHrc+7yDqQo;`h3uwqiNYP^C+L
zLEtSGvLgsQ0Xcsg_R@KiE3tG1#5v~?PA03{f-E!Z+r%A3WZO9z6$IAr1xc4a+gavE
z@fvTt$_Q6G-T)iyDnk-GA=X8tT7jE%$1IpGdsGH5sV9<>03F6Xb%s(cC_mgG0$j6J
zb+G(yU-jo)yhqi{eU3h7M0n_vHY7c^Bs0qxSnM~1KacFpL>_;8J6D(Fl{b?Fd`d|m
zRS6B=n*rRO9HA&ui4;yzY7B6(PAyANURy@svztZ+b3HwKC(6Q)PAb>ja%Oxu`ZSTD
zNs>0k*4!QX(T;R>-4|CH#zOr&*Dl7Wc!5VeAG8JZz+hWiA8yaorLarq|0RGZ<AcFA
zy0W9C`EHvkXpjkQ{xm`M4@2UiTWCE;-(6&I%%qLugSBuw9nb(cII=g^Y;L%eDe=}%
zMC>nDb)DS>Oo&@4>@zMUe7CG3n3iN$4RgVIQr!=<%YW`ad4bshiGP^=4>t!(WiTV=
z%q3O7d{{$ICT<)j&Ya`yyNW!hP^r{$-Ec3j@p>jZL#g)aiPLb#+*P}W$PHdKd_XqP
zTjlE`FeROC2}n(fuQbPAC}p;e^?$om4TdUhz13J6L(+A7tC5kVodatH9vjW{TDolF
zSxRukYUE*hhxK~e+~My#Vw}g#lo!hx&Q4&iriyQgNz6%1-u$unR4+my@4~<C(wz^z
z)x?(cMo-B7(_H}7d!S|?dZ_5R3Lb6s&IAkXr_cCs+S(xIS5;yL6cQu!HtfxmYiWL1
zki%cmds1ZI8g9ok6FLi8t=sZ7f*SuQ22xzJquIQ=fv0)^1}^<e{@<iza^ww<s8Sgj
zP9Gn1>ZY@Pi*uax-|)NPKD04OR_0{p@VFa0X=B3gM)qCbM;~T3mY0ui@Wu3=RJpf?
z*YY26dU?^`aNv6*Jisd8*mE~pteoMR$+h&j9o2#roK1$<i~l@~qGmB$2B0{215^_(
z#3Upq*;S-2^ND^f!iN)hTDl_QyokcEEK+iUredvlf?HjTA&_ZN>OpEH@0QY#?D*g$
zrq*TA#7`o%dfrOTt*F(*IWlhRzR5!btB%GhlYLZQwa8z=kx1DT`A4eHnzCh5ud(5z
zl3^~8e3+eGJuz@oO1&ks*RQVk)QRBYm?MZqNu<OK{690(>-?5v*TsjM!emx)j``i%
zub(K>39ad;-nfeYJOu8Km@?HOE{P{7_hgP};KBN-_M>{Ma#u17{&kVW)0aNoa(G|2
z%mRD{RwNnKfuYG-rNhqm?fS^ututwH&YuoJ+KVe9d@W<ZYLDV3A+JCB5DyV^)pgd^
z=T0cpYWx0*?m%hi*RNB-cuo%lMo2V;1h1-dOe7Nr2R<=Ski&7j{HdHHx~C%A^Qqqd
z*k~~w_4*2RpGyOT9Q7e?c?FGcV)w`3;(27T_I(HsZ|xL1u-JQcvhz$!S4G@B2QUe5
zPrB>x3BMVWI44y9{Wtly!#lx@vP!;*+gG!*s(L4_5h-ghhXULj5fbQa_d@6oUOWTK
z`&7Un?>7(jjqo4)#{a79>;8I{Ee>hz^!cW*79W;Fh`&v=v9d5TA3aP8GnVgd`SH7f
zw}pgN*TTvAVpc4&2UtnZ0WEK=9gVMram$+z-M<6qNjUFtdQEpY8BSZ+an=>AtCR?r
zGGL3(T2*`<d?Ii^oqI@DQuSYrOZ-bmiYg}MJL5#~{eYU=18EPlD40MQX1(89>0Dc8
zP#IHS?qLt>k@8;jk3$sFm(ScO@uE&V%;IzZru*U4jqsD-!6zli`*BJ$L^U)u_Xm3&
z#&#vP8}=6TNH^k+_ZEM;W=Ri|^Q9<-Tn0NvpXOWfaW!Xn<7S7$VBD6E<?Hr;NnovM
z?m3H@D{R128;y(Z+(b!vIOnwzc~}`4Ez8F5_brMZI13*Bs+}>3cPlzP-0Te3b6!Z<
zSjwr^bzjOVZn@$5OSCn>D%~cizEEflUNJO-C-ghv5Z=xf25sWDH{cy<D(=U7bEgMe
z`><ls4z+XaptC&fk-qj(C74oZyTFzX(WDmYKaHBHTBg9Wq>#&G2ap0vn{)k;t=9BS
z%ZD6r)$yG$Q4cL}{&j1mydKuHIT39(P1^WLRolMaO8Zczy^gtC7Hrl%->s+j=+XW!
z8K3KYk!CyS-?yE%qvG`r%X6(J$+^!Prv!)<JKw436@GYUtkwE3ukz)?DDlw7vmf7m
zq(fX2Tb7jPE$YUtgFQuME)Top^YH%Bh7Oc=S~c_c-)>x@Zq}K#I{HRQMjD?R6_%aY
ztbq9q0=IE-P7C1boMiUbbAPc1MP*GB*fLx&ckFIvHml0YzpdRLqr!hn)l01W)~s4i
zV&daq+}vFus~1Xmy(_xgbSWI+@3lu|FBg<YS?r1N)(ibheiFGN)HTSm_1KvJR!Lp!
zW$205ylRy;Q)wx^^!z%rJ^!1Nt#KHz1ii6ZK*)VCz{bWz*p#Og-Od*gqWVo}3Vyr|
z8ui%daHvi80RBvkoo>8WSfQN$;>Fh{`#2~P<HZ7(%0}Vd&bUb9KfbUnoln#i4>h4W
zpxEC;g+@KBV$`Z)6L}{553*R*zlt{);uFh_GM-;$8xFt2|MNlXSVv&~AUDePqP%;V
z%dh!baq-6Mc6@Zgyj)!CIEIG%#f@~U?i0V)BZVsu;toz0s}5$}U3ZpCtM#<C4~4T>
z>JmFRiQ}i85abPbx3pT=X7<=&Evob+XsXdfmyA5#Nl7Z^c>jg@BGY!N_tlV3cQUwd
z*%BL@&JWS(952K#2FD23({VAx^i56}F-(Gfgr(RkoB7RU*)U`lxdJ(W`7iAdQ|1(=
zS@6yJdHi7Jb=r<ng8XNP7z^Rg$2w^CDp!;GS6hD8nOu7_6@2GfNIdy9f#cs@O<N?O
z_T#J^(>xjwmmmzi%VvMhRLPY2O5#A~Fpj`<?D4s~#Y+6u-6iDRx}D{L3>tSTGsk0a
zgXBEAM<<Q#6@7i*2=)j%ZcQBjY;*EE`O1Db_%cK_Sn`_Q)X53~3e_7=?kc@vv6s*O
zj}(4?L5HdzJul&y5)Q;KLIm-x;k<Ku%n6e$8J~%{tyF7h|0q>x$x6=E-Rjr$6ymFV
z=3yb;L@)G-y87~6$Vsa5FTIRk#p$tegH53kUh5APxH#x9HLf@AWRr%noNR4~Q1X(2
zml?)_o#u-`kJpU45Zz%9oc+01f0T?W5ARRbXECPu2O1a1o9e5nq131suY&?6rQ@w(
zi>eJ#9Gm`0_73-2d37syQN<ubMqjS&9Xj_<->sJuHG9Q^TGtyhoHDMGGHP;(WhoYr
zlql_*+pX*A{Vra0%H*dDl9%p}kaO=ad$4oqfom%AsmhmxW+zRP&4}+P&D>#(`_f(s
z)SQECej`1@gAY2_jUq<TCc?(exqva=LH{r0Ga>J;`TY5s&NZeLx=B|D@Lyek+K*4>
z8+*S@)lqtDL72U;le;vx$AF=WjMz-G3^Q1$!U1H-1-j=OMukrWt6mIL4T<-%ECSmL
zJ6ko3Gg^To9&ob28dY$O{s!;doskJAH5<c~4=VD_U0r#SSq(<@F{W;{yX_Y-i0LA2
z8Jg2<^TrdpSY+DOSg8iZX-hMm%La|*vC9~CF#a`BQFUkaw%6P9lPOPaEq#8;u!6yQ
zWbf1!-J_G8KDk}@1<jh}-tL~sn>CwwzVaSpcKLu!(>!z2jb0t`koZ;mYbQ@0qO7HY
z<aU2{`|ZNUoi}@l$eF8o*swoa@ro)xVZZ2R)Z__)nbh|=r_A!3sc%kf2fL=z%C#Tj
z?YNk%+WfY8+!y1Gup~?sArHmXyu?hDDs;CgVJ2Agy9Cx%-z(az4d~@s%Kib>CgeRo
z<H92Ov0}9}7P75kMjOG-kxAHeU227x0y*&pE}8QS;hHvz>sW0McAVDkj;+NC6?D4o
zkG?o4sTg!q`Mz|OGrcTEG9Z;swo88C^-GJg!cUgvx`n+4kuwQC)sH9BV23}5{+29{
zT=3i3S6I|}nSr@miXz?@bnq~%vH78MaA=}{d;W&hCW8(xghr0|E<i}k|Gqs?wlwSS
zJDHoWkBBCIuP`gS6_%wd`~8z7KJT>{Kj}Q)f8DMtnHm}2v5R_i0PxO3XGFcx&iqy{
zxMoct&Ts%JsrBG~f_3!{?6}|X#R`ZW?~oL%aCUDXlYEoKxFXaZtANXt7@cIL9ANYQ
zo#_s`<iiGAAX6u&e9C`2PGrAQ5g?K$>vfkFoCuL=JoF1<m$;1ry6rCIRfY!~m!Gaz
z$W4?$pb+Oe!!@!XCbGNchTJ!SVps;Zno}FA44frrLrr~J-Hq;5e+A{3flD&=2`Z4#
zZ>OZMJizd;#gLk*Ef#sUj~ZlO?|fQ(l^D<=5~)UDihKZXN_m8%`w;kb03CsbaR&g0
zi{sQl;bhf^e8DmqflKnXe9y-{J>91W%o(rCOQ2{us59t4GCUsPI=ARAA`!m@(JgSy
zmCxb>*^iKUz1W>;L{+hICRg*7?={WG^oKg$A6t_nmVkIU67n1mUHv%g4Uxb*9enx?
z1*7Whw+QTl?*u6SxSwIM{c$(BCiycI(*MVGExI#M8g_n+2;OUJ0KOEV^eQz(*Qchd
zy1Qo(F82oz(D}<7`bfM3VrzS}^$YR~ETBCR7(v*HSAKK&A*;H|x)`rop8$``%OlwE
zc$K@vP4giy1BITfICn)4FXZk4!7RYe{L}x*OEuwVK*d5t6|MkK&oSV&+=}JS;Jpd{
zZ#w$~s6ZkcB;FjemTkGNIi$gT>tgw>ZMt)5E?GDJnYJz_7aP-bk!CGNRsZdu(-gGq
z<pKBl1R+Xon&tzuhZwC1D63A^)j7T?v_>*a<c4u`sDYM!Vfh(dazh*<xm2K{qAP14
z#!e`p%s1Id+;BAfjc-imzWlk$hjkF$Q9S!oej!^;I5;E_Bb*%r<PsL4C~Ph!e_^bL
z2%IcnHT~Z%WkiI??0Q?Sf20V_V74o`)n0asjbZ6u7I2V2o$WTKL!Z6IG)3409H=*}
zM;1u;CyxPE3*%g%-?e7?=tE;WbwB8FZ<gxEcUM6=f$~8a?i<`)6XhrB!}wjWK?Q0!
zxuGDeGbz<iDA<3_Z^8N-ZU}k$!Uy0!fJ84glmiwyv)%u>Nq+*@a)N#)$v?={Db|3S
z=^}1x-E4oV@e{2eYY0(DLy!OtUj2&Ft_p3lPM3Vo>n9dF=*TU9CGlF`^m23;?cL3<
zX+-0Q*n&JGxAku4SL^3`<pRj9H&f<wj$s>XQGF~kO@RvJ;h?uY?{hUYRp*MW@&J7p
z%~(z-*1`mply^eAr~xK8?@qBjZMoVFU%HqLTVhquip%5L+T2{rwXcY(tO1sF2C@(E
zgRThr1Xy-&KtvZb1HyILP^&$+e#S4@`6nVG41o=E6Zv$8#D+Sv2ic~I>C#V7DxcAJ
zQf6;CkP_(=Dh{0i21R$SkNg8&s?SvtGu`x;c~PYEvrk;j`?)%vKHEX}1Jwe-b0Ee!
zfR+CT%pf-w3?67F1;>=)d^g6AtEHoxU=qjQ&t;WGyt^9WY$JA2rczqNSmiS+Wjt48
zNis}aBC0+E6o@Yj8i+lQZ%K7)`Gp(sLt;`Z*w4LaExB3LHVuimIl9^jxC5rNK=458
zTmx9{9DhM@aS#-ONj}>oM6AHTE83iyG``EV-7uFblr#IhVSiPcGfAvnrqUoIg7{NV
zSDC8ugPaVdi9QIo&r|+c>iJAllxDhhqM6;xyg1|GI9?mc0uoZsgr)Ge-KC&Df&2%(
z9nmjGL*U7S;X{FtVpbZ9yGwfQJlONIruDgU7M6BYn4<Q?@oJ8}38vN~+ezOE-(iW8
zdw#ow(2FHzS1(@G3-EtApi9nLTznnIR)>gUEno#{32N9s@YD2FM997V{P`ooY$L;j
zLXs7IZow=p<c}f9ryeVZnS?$<lCV$bkA_B=Abn3%<%&H*FP@oKOxJj+^fH0`mh+$j
zn}!s`&o80<nJ3!aP$pd!Owq3G0D03MQ|;#53-X3NDYV>-U^I+L+YxExCU{^0Ol3l0
zLhf0F;S#|t;7H@hi^QLK@IGSfJ|H?!ihxM0{qOTYtPeC0G6*1Xf&dL?99NiI`_XQS
z6ewaGvRKIZ8C>?lmm;A*eDCb3K$7~~)}VzogC2ch(py-I)C4{@e%m7{ZtkzusH4Ua
zHNT0ZVLUgJYMQ@RIrPqQ_mju7wmU?deXPZ_E&wv#0^E>pTjdCD^Hn;-jQO9HMYM=i
zYS1z-(;|8|@GOKsuY)~@BY+q;MCgKm2m_wb)-EC{4B|%+unTP^6@zV$cEg9cA>l+H
zqlM(Rw_^kU2`3)cHVnZo^$FW##YvtVKqSChfk^-(E37R*vfV{_enGb{`OyzDvzWav
z-|)aH!5sq{hZ1J+)+ctBpRd55lE8D|@3Es%w6%yFwb5;U6L-RdYez=M`!nRq8~_iS
z=Vq^3NzsA-)^zPY+Og$}xLz*PzwA|$hVxJ?-<BhEK*6tP{|S}G-Dda+*n<VgD?vyF
z%iugA8|HY)c06tt{4HtYpqtJL*n(qBlvgwK^WUbf;kc;-amjawn+u44*Y}eM@PsF~
zw@RfIeI^alx^S7wlmhM-!oPNXwV)(Q;;_M_viT0NKSEH;pf8%h6xNEx5pdjX1RM(i
zDVQW&^q%jF8E3E{WW<)$ps$j!{n0r|Y$`sAXsP@ggkD=oJ>jkxP<66_af1*xL|%mf
zsbEEZx2*CaO3F{H|8YLo{f`zSdvPiC`9}C2dUjjJKhb7jrpSml0s+_AM$5Y8DHK=z
z!7msVN1g*opVwY&QzWv3&~*KYxUQSbh$Fl;3}7Ra@*d-vmJ_{!ib$r&siOS*h&y%s
zg+BJGSUFqIW2|ey2(v>?&L7w(XY5!K$;a(&;A~p?shfY|a=<bS3~b{KFwF;GE#7cm
z!q;8MvVWLb)OWE5Zj{=~KbI4YLax0&I4m0*C{5bZ01!>El_n5(2b(B(p?~FrQ83dd
z$Jpj?Qk5`Vyn5e}JU`{|w^QU~wAG9t69`-PsdPQog1G$<84HFVxH1sP1e^n;3b+kv
zCs}YgeG&>)k{rH)-9R#aE`R#|$CH=_JC7JoT8BvSE$*=^cjM8M&^6Ct^CQt1G+Vw8
z+1RnF8thC2c6bEO1-~W?bh4G6fyLx5Z%_hxfrQB_4>k7Q0?dkX!zay)*uKHj;7YcV
z&YDDleET`obM=P<#PYwCY|^UiY6>8x((V1^7HoLX@pr0uiB}M-fg^@3ePQtYEIdI0
zg2KbniNF&?ds<?fV*b^t3AGtZpX4mEqrys8{(~}3O?TtyWxCySkP1?Xcw~Ubqb>VC
zN?vQ+s+E%ymNSt`&-hjM<pmJ3wll+Evz#G&Z^<oAnCZqxrr|G-yc43SAQuG=^)k3C
zb$gbOR}#U=00D41V?$0+-g95@{>r!h*~PXNxP3k`Bg*Wz?~RK>vKXS!z|3>MPIr-l
za5o$vSpRk*tSuqprFU5Xkl{=sE|Fornf7yZxAp*!j1b7Eik@=f&MCgqVEAJ|N{lC!
z+rpR_V^}v)4v}MoPLllza!=WR<VDJ3(4G52^54hvywxnof2UH$gi{=yS@lq>4QHXD
zIEvMx@<UPN{h@Cis2doYDzwZU5My>WLLfU|txv+A^o0V{$+1jgF{(3@fjGQKv@1v{
zY4@?~Qi~viL&REN9jeuy)l3;oMrMY^xhiD?^-^Ih9}3fF`YLF-7t{)rO&+0mRJrp?
z&GZ+I?e*cHsX^2PvQ-0mX<lWG1-DdQem`oQE!N79_0B<i)oF|F7n4x%?Pacjru8f)
z&NB{N$7GcA68=#kG9*4xp>WmD)wCz47F<d~w?GfXM&n5u&+V$aA0*4ES`^5AK-s0W
zx^Vx^fW~Ejw}=M|z-(4hbX-(DJz7u!QR)PTEuGQdb-5Y(EHo~XVvOOw`!3a=tk@q-
zgk=_{R<+3)9p&B#i{BPvzG9!yUg}emj;1fm)AywP^0msZ(c^s=lhCsiROMu8Hqk}1
zx>T9@Ap7nTy2Lp&D?6?8lwcz}KG?l%8g<rsT~bHA1fX7V=p_#Z{9XjB^fi?ny!kf0
zpdP}-9p}NCf4Qy?8u|+r8zb5aY&PT#$UMY?_&y<l_rR8w22$0ezu-9!pH(~~0k55H
zYQUy1bObULYzl-xv7~)&L9W|l*lIK)edKMn7Pp<7E&pS7|Mf8l-EjdA4P1DHErWE>
zYfuZ|d4dnB&b$oqI#_5SEEA1!R19m_lrC*O3%MnrPvCNu-5j2}9AE(=VfFr<K4Dbd
ztNPnu%U~$<kMCeQC8Z~&SNwt924)hXBvEeqh<(*lR`|8>?Mgh0+}_RYdz3mczyA0@
z=kL+n_Y*|44J3derq=&HF}w;`llgx)yC;^>HjJ|wdRy;xkR$Y|oYDfNN{*I<j+UNl
zsDk2&lr}S<2fYF|?-ytXP?^8KeEWlV&A>SUb&`^4)At#p*X%Y#{sGlM6kufe>{NIk
zVRtAyGp#H=m|P<yx$EY(H~5m9pm8LoWE#v~fYm}2K3H!!E7L;6@Q#OwDeMCOx!<0O
zBkHO-f#^wyHX)iBZhq6Zjxd)@9)kaF<LA*7jskxOQF=G=zXC!V^d6{WNl@vPv2oys
z$h+HCb5e99H|i>LAJo7`g@WnFP1){E{Nk=D_2I$B!Z#%84RQdKz<EghPB_oGaMQT2
zL<Hnx_TyVs6z_<@e+}&q^Zl$@4&R?(kiej9O1};PT?n2D59@O52*hJ8Z{AuKS$d&#
z22Ev1gi*qH_LA6aQOK(@deXjq4L~%YRAD(ZMz(JN1^|=>2V1TzbefjNfSUnwGm?0R
zYSZDtV~_gDiT00DQ1$RQ$VM^775$TR1TJy}pfWGWXan!fyX`5jjYxgEg{ieA`Vt8#
z5t_(3=Y^@Kvp89!(!krkdb@=9hlm5h+#CmH8UVt*VzRzy%(87tfON3=`b#7jqFwD_
z+vFBU61~sT!4Lxqum%PT>?V?Gge08qg~}*7e3y9u>&ikdpJL*3{>nS|?)+b@Y{4HZ
z3pX@6N8*Q3_#-1&Hz$A-#L0)Dt-*}^l6h7b%~6<Q`S!ZRxi8qK(>H@H9QglaWEuZY
zBb(gynDbvomdH-ntq5)*yp=kk!E8(3{ytF-m>B?$J8*!oolfr7!V_V-2#=2MCeQ2B
zkp`+j?F=IRUwc#&3mBPDH$SdYiDe_l2xzVb_-BOOBW)+(dw=6oIM}ES$jdIkLx3kh
z$q2-#LM9jTZGUptQ7@9}@Nav{48lIYVF)-J*c`Z2`Vpfdh|PfnI(y}G>5R72glP1U
zGsuoyw9^UmZ&xk&n==L>2*emQZAWN*JN4RgNPq`JY*ufU-qx!rz>1K+wIGMh%>dcr
z2?uElEjQ$|L6o}+{imjd5Tc-I8{fJr8pLN-u4Q!RlXT>eT$lWrm9wDW^@;3I#;A}z
zPlcx$q{P%~ltu>hfWWEqdRDLA?-QhjO?W?gA0oP`Y3^C0jfR38AqoqI-~sefbpph|
zKcx@;Yc4x;P8^UuZ)IXHZ(WXS;{SBs*eqZ#D1P{!zOsl5vcHe&&nug&@w}IDFosTb
z{ZGvToT!F=t8JcD%t?8Qx~x4kynOa?oJ>+ZFqYE6l$ZV_6d}o>ki3*VE-W9i)Wd^p
zri|H^+w~u1&lOrIW_jHV3yjN2xPf#{=vOKFsMidgSn)iS&ghTnb2Hib8lxVn5=Lj9
zPt`?XrVeA$fkV(f#Zkyt**!iYpAoa92RSz1)huPJlA`pH`J0n)(*ya;&9E)ugZ&~}
zy1nBPax$EY7jcfP6sLOR!k8bo3$bl|aB=pkwBxA<=K%8P!F$Qsdlz|X{jO<TB!u^m
z+dic(e)mZ_@e?l-ejj629~s!c0RqToaE>R3-Cqj7Xr~E6R4E!c9*Ua;uQRtTP-SNh
zYQw=O6jLw!c>y-8L@oQ1F%I(bcyI%58riadz6JQ=^@N)k(z}4GzZ>EMWejLFGbNMw
z*G}Jg-bGIY>J{-%!9f~0>x5V^b-2c03Op0YshuhD=*j#Mc92XQQC!;0r=}5<5ST_y
z0q`(@-u^>BU4grA1;z_ejrg|W_gI52(cwHno>mBG6q!`lMS|$A<nEI924K7Z-<YW&
zEE`*t7f?)}lt9vuhZ9>;d0TJ^Uz*ZFxD>c}aF-w(zwsvVFhbbT(tM@k@&_jqc*tRI
zy3^VRGi&G3gty&yfKiHp{Q}<~4js#L`TsCwIplvlNarV9FfhPAW8G(`cFedwz0HC{
z_%aSZ5Kt3*Q!k)A1yoWkfCCU=F!M;|2$)+PibT{+U`=NmGp<0=9s#6nA*;n0*5X=2
zQuX3i@5{d~L}3BfgJkWg{RXuPFg+SPQRHUj=i1C%FOo+fh`zxLOIW15x7<@I0HJ_b
zeVZ@-rmepNN^pK<E5?X+zR_=$H>K8kYe>{Nk&p-ovp<VU*>`<*UC<&9Y9)hI0ATbw
zzZ}2@qY6pcSN+3XLGn4|EMI^c0E^dl)d&@$5rO~;Ii9z#l_E>M-U9CaxO(Ayp*y0Z
zCif;_hER<$#o=26E*n_H5SE*Fnx!7eW3PPrbCz!_RpZw{gizc}1Dc5M2U7ur0fxX}
za?b!p!G*y9Z{u?mk9`&evnC#3PJ<>AEyC(n(Jt^*yfg&TSqZ2HYXQ_Bfs+Bs6)_^<
z>=rpKwPO{zo{GjkQP$Z-dEBgv$U4C1gTF%JMSl~AJJM7h9F{#zp?e83h%a`#xHnqd
z;-QwQIudjMJ`$W4eDKkN>tw57Ju1F)i+zhPg-$n2GYwVv_5be1p`l?>sU|&V%ClDm
zZvYfM_)>`02h6n(3@yM5pd3I{5eT_B0|BPffd|5)`Z4~W-7vIt{e@3m8ev2Q$R1G*
zA|5qRj6Z=$h4DE8XR#n{_w>qQa9@U$df3ou_#NnNBr_dc*@6%;c^PA#b7NP~M8p@%
z7(qFqAXOC6yof(HR}Lb}UhLiM242^nf%>GbLFnU8WfuqnoHx6P@@$d1d`le)oH4YY
z*nN>8dnhJ*GuirF2wML`T#BEHvyPhounubX-nbI?E$~pTK1LC~l!nWHj$A5BV_1rD
zEX?P7yJ~O-^Q@2DlvX?5#XqWK=H8NT1~ZB|&#F8nApc!o)D=V%J_J&)Be%`slNprD
z)SPMuSZNl?XYM*iFZ2-5T6CZ*xtaffDtru`08<KsEM|R0G_?4Li*{wFs)%x)@KaSb
g+W(*bSu~$uMz1F14=;Z_Le?RD|G~X%F@4Yf1%^xFsQ>@~

literal 35065
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

diff --git a/docs/images/centralized_Bb.xml b/docs/images/centralized_Bb.xml
new file mode 100644
index 000000000..b4dbc89e1
--- /dev/null
+++ b/docs/images/centralized_Bb.xml
@@ -0,0 +1,112 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<mxfile host="www.draw.io" modified="2019-11-07T16:58:12.074Z" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:70.0) Gecko/20100101 Firefox/70.0" etag="5gKdhbBFnhzMqdrUPAE6" version="12.2.2" type="device" pages="1">
+  <diagram id="RJgQPiBM3F0--PLLHpmw" name="Page-1">
+    <mxGraphModel dx="1750" dy="662" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
+      <root>
+        <mxCell id="0"/>
+        <mxCell id="1" parent="0"/>
+        <mxCell id="EG-plCSeABy2wCnL0sD--1" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-640" y="150" width="110" height="150" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--2" value="&lt;b&gt;Node 0&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="-610" y="155" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--47" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shadow=1;endArrow=none;endFill=0;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;" edge="1" parent="1" source="EG-plCSeABy2wCnL0sD--3" target="EG-plCSeABy2wCnL0sD--15">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="-610" y="195"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--48" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shadow=1;endArrow=none;endFill=0;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;" edge="1" parent="1" source="EG-plCSeABy2wCnL0sD--3" target="EG-plCSeABy2wCnL0sD--21">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="-610" y="265"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--49" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shadow=1;endArrow=none;endFill=0;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;" edge="1" parent="1" source="EG-plCSeABy2wCnL0sD--3" target="EG-plCSeABy2wCnL0sD--18">
+          <mxGeometry relative="1" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--3" value="&lt;b&gt;Mgr&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-630" y="215" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--13" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-500" y="185" width="70" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--14" value="&lt;b&gt;Node 1&lt;br&gt;&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="-490" y="185" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--57" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.25;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;shadow=0;endArrow=block;endFill=1;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;comic=0;" edge="1" parent="1" source="EG-plCSeABy2wCnL0sD--15" target="EG-plCSeABy2wCnL0sD--13">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="-570" y="310"/>
+              <mxPoint x="-465" y="310"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--15" value="&lt;b&gt;Wrk0&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-580" y="180" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--16" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-410" y="185" width="70" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--17" value="&lt;b&gt;Node 2&lt;br&gt;&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="-400" y="185" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--58" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;shadow=0;endArrow=block;endFill=1;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;comic=0;" edge="1" parent="1" source="EG-plCSeABy2wCnL0sD--18" target="EG-plCSeABy2wCnL0sD--16">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="-560" y="320"/>
+              <mxPoint x="-375" y="320"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--18" value="&lt;b&gt;Wrk1&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-580" y="215" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--19" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-320" y="185" width="70" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--20" value="&lt;b&gt;Node 2&lt;br&gt;&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="-310" y="185" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--59" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.75;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;shadow=0;endArrow=block;endFill=1;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;comic=0;" edge="1" parent="1" source="EG-plCSeABy2wCnL0sD--21" target="EG-plCSeABy2wCnL0sD--19">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="-550" y="330"/>
+              <mxPoint x="-285" y="330"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--21" value="&lt;b&gt;Wrk2&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-580" y="250" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--24" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-480" y="240" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--31" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-390" y="230" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--32" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-300" y="210" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--33" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-300" y="225" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--34" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-300" y="240" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--36" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-390" y="215" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--37" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-480" y="210" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--38" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-480" y="225" width="30" height="10" as="geometry"/>
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>
diff --git a/docs/images/distributed_Bb.xml b/docs/images/distributed_Bb.xml
new file mode 100644
index 000000000..57c73a0b5
--- /dev/null
+++ b/docs/images/distributed_Bb.xml
@@ -0,0 +1,95 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<mxfile host="www.draw.io" modified="2019-11-07T17:00:09.322Z" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:70.0) Gecko/20100101 Firefox/70.0" etag="bSJ_7pnv9lknAw35r4H6" version="12.2.2" type="device" pages="1">
+  <diagram id="RJgQPiBM3F0--PLLHpmw" name="Page-1">
+    <mxGraphModel dx="1750" dy="662" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
+      <root>
+        <mxCell id="0"/>
+        <mxCell id="1" parent="0"/>
+        <mxCell id="EG-plCSeABy2wCnL0sD--86" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-660" y="100" width="110" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--87" value="&lt;b&gt;Node 0&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="-630" y="100" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--88" value="&lt;b&gt;Mgr&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-625" y="130" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--89" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-540" y="100" width="110" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--90" value="&lt;b&gt;Node 1&lt;br&gt;&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="-510" y="100" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--91" value="&lt;b&gt;Wrk0&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-530" y="130" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--92" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-420" y="100" width="110" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--93" value="&lt;b&gt;Node 2&lt;br&gt;&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="-390" y="100" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--94" value="&lt;b&gt;Wrk1&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-410" y="130" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--95" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-300" y="100" width="110" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--96" value="&lt;b&gt;Node 2&lt;br&gt;&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="-270" y="100" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--97" value="&lt;b&gt;Wrk2&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="-290" y="130" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--98" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-475" y="155" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--99" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-355" y="155" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--100" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-235" y="125" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--101" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-235" y="140" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--102" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-235" y="155" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--103" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-355" y="140" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--104" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-475" y="125" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--105" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="-475" y="140" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--106" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.25;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;fillColor=#ffe6cc;strokeColor=#d79b00;strokeWidth=3;endArrow=none;endFill=0;" edge="1" parent="1" source="EG-plCSeABy2wCnL0sD--88" target="EG-plCSeABy2wCnL0sD--91">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="-615" y="190"/>
+              <mxPoint x="-510" y="190"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--107" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.75;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;endArrow=none;endFill=0;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;" edge="1" parent="1" source="EG-plCSeABy2wCnL0sD--88" target="EG-plCSeABy2wCnL0sD--97">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="-595" y="210"/>
+              <mxPoint x="-270" y="210"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="EG-plCSeABy2wCnL0sD--108" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;endArrow=none;endFill=0;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;" edge="1" parent="1" source="EG-plCSeABy2wCnL0sD--88" target="EG-plCSeABy2wCnL0sD--94">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="-605" y="200"/>
+              <mxPoint x="-390" y="200"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>

From cc5263e3aa6f3af52d5f8a345f177cb30ae1773b Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 7 Nov 2019 13:21:18 -0600
Subject: [PATCH 445/644] Moving tags

---
 README.rst                             | 6 +++---
 docs/data_structures/exit_criteria.rst | 3 +--
 docs/data_structures/gen_specs.rst     | 3 +--
 docs/latex_index.rst                   | 2 +-
 docs/quickstart.rst                    | 3 ---
 5 files changed, 6 insertions(+), 11 deletions(-)

diff --git a/README.rst b/README.rst
index 18a6bfdef..2e81b76a4 100644
--- a/README.rst
+++ b/README.rst
@@ -20,9 +20,9 @@
 |
 .. after_badges_rst_tag
 
-====================
-What is libEnsemble?
-====================
+===========================
+Introduction to libEnsemble
+===========================
 
 libEnsemble is a Python library to coordinate the concurrent evaluation of
 dynamic ensembles of calculations. The library is developed to use massively
diff --git a/docs/data_structures/exit_criteria.rst b/docs/data_structures/exit_criteria.rst
index a4a762ac4..6e4cc0b9c 100644
--- a/docs/data_structures/exit_criteria.rst
+++ b/docs/data_structures/exit_criteria.rst
@@ -1,7 +1,6 @@
-.. _datastruct-exit-criteria:
-
 exit_criteria
 =============
+.. _datastruct-exit-criteria:
 
 Exit criteria for libEnsemble::
 
diff --git a/docs/data_structures/gen_specs.rst b/docs/data_structures/gen_specs.rst
index 9cea34cd3..b6518627d 100644
--- a/docs/data_structures/gen_specs.rst
+++ b/docs/data_structures/gen_specs.rst
@@ -1,7 +1,6 @@
-.. _datastruct-gen-specs:
-
 gen_specs
 =========
+.. _datastruct-gen-specs:
 
 Generation function specifications to be set in user calling script and passed
 to main ``libE()`` routine::
diff --git a/docs/latex_index.rst b/docs/latex_index.rst
index 742e29d17..1cefce8b7 100644
--- a/docs/latex_index.rst
+++ b/docs/latex_index.rst
@@ -3,7 +3,7 @@
 .. include:: welcome.rst
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    Quickstart<quickstart>
    user_guide
diff --git a/docs/quickstart.rst b/docs/quickstart.rst
index a470df97f..0152356dc 100644
--- a/docs/quickstart.rst
+++ b/docs/quickstart.rst
@@ -1,5 +1,2 @@
-.. image:: images/libE_logo.png
-   :alt: libEnsemble
-
 .. include:: ../README.rst
     :start-after: after_badges_rst_tag

From 09e9b04829d30b2770357b799923a3bd45bb709c Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 7 Nov 2019 13:48:12 -0600
Subject: [PATCH 446/644] Starting a branch for reorganizing PDF


From e771a0c291213d53b11b60eddbd789bc323f87a7 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 7 Nov 2019 13:52:03 -0600
Subject: [PATCH 447/644] Renaming quickstart to introduction

---
 docs/index.rst                            | 2 +-
 docs/{quickstart.rst => introduction.rst} | 0
 docs/latex_index.rst                      | 2 +-
 docs/tutorials/local_sine_tutorial.rst    | 2 +-
 docs/welcome.rst                          | 2 +-
 5 files changed, 4 insertions(+), 4 deletions(-)
 rename docs/{quickstart.rst => introduction.rst} (100%)

diff --git a/docs/index.rst b/docs/index.rst
index 440dc149c..f0d169a0e 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -9,7 +9,7 @@
    :maxdepth: 2
    :caption: Getting Started:
 
-   Quickstart<quickstart>
+   Introduction<introduction>
    contributing
    release_notes
    FAQ
diff --git a/docs/quickstart.rst b/docs/introduction.rst
similarity index 100%
rename from docs/quickstart.rst
rename to docs/introduction.rst
diff --git a/docs/latex_index.rst b/docs/latex_index.rst
index 1cefce8b7..f1938e38a 100644
--- a/docs/latex_index.rst
+++ b/docs/latex_index.rst
@@ -5,7 +5,7 @@
 .. toctree::
    :maxdepth: 3
 
-   Quickstart<quickstart>
+   Introduction<introduction>
    user_guide
    tutorials/local_sine_tutorial
    platforms/bebop
diff --git a/docs/tutorials/local_sine_tutorial.rst b/docs/tutorials/local_sine_tutorial.rst
index aa71d28af..96498a735 100644
--- a/docs/tutorials/local_sine_tutorial.rst
+++ b/docs/tutorials/local_sine_tutorial.rst
@@ -3,7 +3,7 @@ Simple Local Sine Tutorial
 ==========================
 
 This introductory tutorial demonstrates the capability to perform ensembles of
-calculations in parallel using :doc:`libEnsemble<../quickstart>` with Python's Multiprocessing.
+calculations in parallel using :doc:`libEnsemble<../introduction>` with Python's Multiprocessing.
 
 The foundation of writing libEnsemble routines is accounting for four components:
 
diff --git a/docs/welcome.rst b/docs/welcome.rst
index 4979ea952..4dad228a2 100644
--- a/docs/welcome.rst
+++ b/docs/welcome.rst
@@ -25,7 +25,7 @@ Welcome to libEnsemble's documentation!
 
 libEnsemble is a library to coordinate the concurrent evaluation of dynamic ensembles of calculations.
 
-* New to libEnsemble? Start :doc:`here<quickstart>`.
+* New to libEnsemble? Start :doc:`here<introduction>`.
 * Try out libEnsemble with a :doc:`tutorial<tutorials/local_sine_tutorial>`.
 * Go in-depth by reading the :doc:`User Guide<user_guide>`.
 * Check the :doc:`FAQ<FAQ>` for common questions and answers, errors and resolutions.

From 4d3a867b3238d96c983872c9c9359c261f394469 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 7 Nov 2019 14:24:16 -0600
Subject: [PATCH 448/644] adjust platforms toctree, titles

---
 docs/index.rst                     | 3 +--
 docs/platforms/platforms_index.rst | 4 ++--
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index 440dc149c..09c27faa7 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -24,8 +24,7 @@
    :maxdepth: 1
    :caption: Running on:
 
-   platforms/bebop
-   platforms/theta
+   platforms/platforms_index.rst
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst
index 9092a9110..cd6f58f7f 100644
--- a/docs/platforms/platforms_index.rst
+++ b/docs/platforms/platforms_index.rst
@@ -4,8 +4,8 @@ distributions and macOS, from laptops to hundreds of compute-nodes. Although
 libEnsemble and most user functions are cross-platform compatible, there are
 platform-specific differences for installing and configuring libEnsemble.
 
-Local
-=====
+Personal Computers
+==================
 
 Users interested in installing and running libEnsemble on their personal machines
 are encouraged to read the Quickstart guide :doc:`here<../quickstart>`.

From 4164aa6465bdd44941a6ba14a858e71b0a4e8c0b Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 7 Nov 2019 15:46:15 -0600
Subject: [PATCH 449/644] One pass through the docs

---
 CONTRIBUTING.rst                              |   4 +-
 README.rst                                    | 170 ++++++++++++------
 docs/appendix.rst                             |  11 ++
 docs/data_structures/alloc_specs.rst          |  12 +-
 docs/data_structures/data_structures.rst      |   2 +-
 docs/data_structures/gen_specs.rst            |   2 -
 docs/data_structures/history_array.rst        |   8 +-
 docs/data_structures/sim_specs.rst            |   3 -
 docs/dev_info.rst                             |  10 ++
 docs/index.rst                                |   3 +-
 docs/latex_index.rst                          |  23 +--
 docs/libE_module.rst                          |   5 -
 docs/logging.rst                              |   3 -
 docs/programming_libE.rst                     |  36 ++++
 docs/sim_gen_alloc_funcs.rst                  |  48 ++++-
 docs/tutorials/local_sine_tutorial.rst        |   2 +-
 docs/tutorials/tutorials.rst                  |   8 +
 docs/user_funcs.rst                           |   5 -
 docs/user_guide.rst                           | 126 -------------
 docs/welcome.rst                              |   2 +-
 libensemble/libE.py                           |  20 +--
 ...uniform_sampling_one_residual_at_a_time.py |   6 +-
 22 files changed, 252 insertions(+), 257 deletions(-)
 create mode 100644 docs/appendix.rst
 create mode 100644 docs/dev_info.rst
 delete mode 100644 docs/libE_module.rst
 create mode 100644 docs/programming_libE.rst
 create mode 100644 docs/tutorials/tutorials.rst
 delete mode 100644 docs/user_guide.rst

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 46b5dcba6..b68b88a5d 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -8,7 +8,9 @@ Contributions may be made via GitHub pull request to:
 libEnsemble uses the Gitflow model. Contributors should branch from, and
 make pull requests to, the develop branch. The master branch is used only
 for releases. Code should pass flake8 tests, allowing for the exceptions
-given in the ``.flake8`` configuration file in the project directory.
+given in the ``.flake8`` file in the project directory:
+
+.. literalinclude:: ../.flake8
 
 Issues can be raised at:
 
diff --git a/README.rst b/README.rst
index 2e81b76a4..b8d3c1e79 100644
--- a/README.rst
+++ b/README.rst
@@ -7,13 +7,13 @@
 .. image:: https://img.shields.io/pypi/v/libensemble.svg?color=blue
    :target: https://pypi.org/project/libensemble
 
-.. image::  https://travis-ci.org/Libensemble/libensemble.svg?branch=master
+.. image:: https://travis-ci.org/Libensemble/libensemble.svg?branch=master
    :target: https://travis-ci.org/Libensemble/libensemble
 
 .. image:: https://coveralls.io/repos/github/Libensemble/libensemble/badge/?maxAge=2592000/?branch=master
    :target: https://coveralls.io/github/Libensemble/libensemble?branch=master
 
-.. image::  https://readthedocs.org/projects/libensemble/badge/?maxAge=2592000
+.. image:: https://readthedocs.org/projects/libensemble/badge/?maxAge=2592000
    :target: https://libensemble.readthedocs.org/en/latest/
    :alt: Documentation Status
 
@@ -54,12 +54,113 @@ are portable, resilient and flexible; it also enables automatic detection of
 the nodes and cores in a system and can split up jobs automatically if resource
 data isn't supplied.
 
-A visual overview is given in the libEnsemble poster_.
+Overview
+--------
+libEnsemble is a Python library to coordinate the concurrent evaluation of
+dynamic ensembles of calculations. libEnsemble uses a manager to allocate work to
+various workers. A libEnsemble worker is the smallest indivisible unit to
+perform some calculation. The work performed by libEnsemble is governed by
+three routines:
+
+* :ref:`gen_f<api_gen_f>`: Generates inputs to ``sim_f``.
+* :ref:`sim_f<api_sim_f>`: Evaluates a simulation or other evaluation at output from ``gen_f``.
+* :ref:`alloc_f<api_alloc_f>`: Decides whether ``sim_f`` or ``gen_f`` should be called (and with what input/resources) as workers become available.
+
+Example ``sim_f``, ``gen_f``, ``alloc_f``, and calling scripts
+be found in the ``examples/`` directory. To enable portability, a
+:doc:`job_controller<job_controller/overview>`
+interface is supplied for users to launch and monitor jobs in their
+user-provided ``sim_f`` and ``gen_f`` routines.
+
+The default ``alloc_f`` tells each available worker to call ``sim_f`` with the
+highest priority unit of work from ``gen_f``. If a worker is idle and there is
+no ``gen_f`` output to give, the worker is told to call ``gen_f``.
+
+
+Example Use Cases
+~~~~~~~~~~~~~~~~~
+Below are some expected libEnsemble use cases that we support (or are working
+to support) and plan to have examples of:
+
+* A user is looking to optimize a simulation calculation. The simulation may
+  already be using parallel resources, but not a large fraction of some
+  computer. libEnsemble can coordinate the concurrent evaluation of the
+  simulation ``sim_f`` at various parameter values and ``gen_f`` would return
+  candidate parameter values (possibly after each ``sim_f`` output).
+
+* A user has a ``gen_f`` that produces different meshes to be used within a
+  ``sim_f``. Given the ``sim_f`` output, ``gen_f`` will refine a mesh or
+  produce a new mesh. libEnsemble can ensure that the calculated meshes can be
+  used by multiple simulations without requiring movement of data.
+
+* A user is attempting to sample a simulation ``sim_f`` at some parameter
+  values, many of which will cause the simulation to fail. libEnsemble can stop
+  unresponsive evaluations, and recover computational resources for future
+  evaluations. ``gen_f`` can possibly update the sampling after discovering
+  regions where evaluations of ``sim_f`` fail.
+
+* A user has a simulation ``sim_f`` that requires calculating multiple
+  expensive quantities, some of which depend on other quantities. ``sim_f`` can
+  observe intermediate quantities in order to stop related calculations and
+  preempt future calculations associated with poor parameter values.
+
+* A user has a ``sim_f`` with multiple fidelities, with the higher-fidelity
+  evaluations requiring more computational resources, and a
+  ``gen_f``/``alloc_f`` that decides which parameters should be evaluated and
+  at what fidelity level. libEnsemble can coordinate these evaluations without
+  requiring the user know parallel programming.
+
+* A user wishes to identify multiple local optima for a ``sim_f``. Furthermore,
+  sensitivity analysis is desired at each identified optimum. libEnsemble can
+  use the points from the APOSMM ``gen_f`` to identify optima; and after a
+  point is ruled to be an optimum, a different ``gen_f`` can produce a
+  collection of parameters necessary for sensitivity analysis of ``sim_f``.
+
+Naturally, combinations of these use cases are supported as well. An example of
+such a combination is using libEnsemble to solve an optimization problem that
+relies on simulations that fail frequently.
+
+
+Resources
+~~~~~~~~~~~~~~~~~~
+
+**Support:**
+
+- Email questions to libensemble@lists.mcs.anl.gov 
+- Communicate (and establish a private channel, if desired) at https://libensemble.slack.com
+- Join the libEnsemble mailing list for updates about new releases at https://lists.mcs.anl.gov/mailman/listinfo/libensemble
+
+**Documentation:**
+
+- Provided by ReadtheDocs at http://libensemble.readthedocs.org/
+
+**Citation:**
+
+- Please use the following to cite libEnsemble in a publication:
+
+.. code-block:: bibtex
+
+  @techreport{libEnsemble,
+    author      = {Stephen Hudson and Jeffrey Larson and Stefan M. Wild and
+                   David Bindel and John-Luke Navarro},
+    title       = {{libEnsemble} Users Manual},
+    institution = {Argonne National Laboratory},
+    number      = {Revision 0.5.2},
+    year        = {2019},
+    url         = {https://buildmedia.readthedocs.org/media/pdf/libensemble/latest/libensemble.pdf}
+  }
 
-.. _poster:  https://figshare.com/articles/LibEnsemble_PETSc_TAO-_Sustaining_a_library_for_dynamic_ensemble-based_computations/7765454
+
+**Other:**
+
+- A visual overview of libEnsemble is given in this poster_.
+
+
+Quickstart
+----------
 
 Dependencies
-------------
+~~~~~~~~~~~~
 
 Required dependencies:
 
@@ -97,7 +198,7 @@ should produce a file nlopt.py if Python is found on the system. NLopt may also
 require SWIG_ to be installed on certain systems.
 
 Installation
-------------
+~~~~~~~~~~~~
 
 Use pip to install libEnsemble and its dependencies::
 
@@ -117,7 +218,7 @@ If necessary, you may install all optional dependencies (listed above) at once w
 A `tarball <https://github.com/Libensemble/libensemble/releases/latest>`_ of the most recent release is also available.
 
 Testing
----------
+~~~~~~~
 
 The provided test suite includes both unit and regression tests and is run
 regularly on:
@@ -160,7 +261,7 @@ available online at
     ``test_balsam_hworld.py``.
 
 Basic Usage
------------
+~~~~~~~~~~~
 
 The examples directory contains example libEnsemble calling scripts, sim
 functions, gen functions, alloc functions and job submission scripts.
@@ -187,52 +288,17 @@ See the
 `user-guide <https://libensemble.readthedocs.io/en/latest/user_guide.html>`_
 for more information.
 
-Documentation
--------------
-
-* http://libensemble.readthedocs.org/
-
-Citing libEnsemble
-------------------
-Please use the following to cite libEnsemble in a publication:
-
-.. code-block:: bibtex
-
-  @techreport{libEnsemble,
-    author      = {Stephen Hudson and Jeffrey Larson and Stefan M. Wild and
-                   David Bindel and John-Luke Navarro},
-    title       = {{libEnsemble} Users Manual},
-    institution = {Argonne National Laboratory},
-    number      = {Revision 0.5.2},
-    year        = {2019},
-    url         = {https://buildmedia.readthedocs.org/media/pdf/libensemble/latest/libensemble.pdf}
-  }
-
-Support
--------
-
-Join the libEnsemble mailing list at:
-
-* https://lists.mcs.anl.gov/mailman/listinfo/libensemble
-
-or email questions to:
-
-* libensemble@lists.mcs.anl.gov
-
-or communicate (and establish a private channel, if desired) at:
-
-* https://libensemble.slack.com
-
-.. _PETSc:  http://www.mcs.anl.gov/petsc
-.. _Python: http://www.python.org
-.. _nlopt: http://ab-initio.mit.edu/wiki/index.php/NLopt
-.. _NumPy:  http://www.numpy.org
-.. _SciPy:  http://www.scipy.org
-.. _mpi4py:  https://bitbucket.org/mpi4py/mpi4py
-.. _petsc4py:  https://bitbucket.org/petsc/petsc4py
 .. _Balsam: https://www.alcf.anl.gov/balsam
+.. _NumPy: http://www.numpy.org
+.. _PETSc: http://www.mcs.anl.gov/petsc
+.. _Python: http://www.python.org
 .. _SWIG: http://swig.org/
+.. _SciPy: http://www.scipy.org
 .. _mock: https://pypi.org/project/mock
-.. _pytest: https://pypi.org/project/pytest/
+.. _mpi4py: https://bitbucket.org/mpi4py/mpi4py
+.. _nlopt: http://ab-initio.mit.edu/wiki/index.php/NLopt
+.. _petsc4py: https://bitbucket.org/petsc/petsc4py
+.. _poster: https://figshare.com/articles/LibEnsemble_PETSc_TAO-_Sustaining_a_library_for_dynamic_ensemble-based_computations/7765454
 .. _pytest-cov: https://pypi.org/project/pytest-cov/
 .. _pytest-timeout: https://pypi.org/project/pytest-timeout/
+.. _pytest: https://pypi.org/project/pytest/
diff --git a/docs/appendix.rst b/docs/appendix.rst
new file mode 100644
index 000000000..a1561e2c4
--- /dev/null
+++ b/docs/appendix.rst
@@ -0,0 +1,11 @@
+Appendices
+==========
+
+.. toctree::
+   tutorials/tutorials
+   FAQ
+   release_notes
+   examples/examples_index
+
+Bibliography
+------------
diff --git a/docs/data_structures/alloc_specs.rst b/docs/data_structures/alloc_specs.rst
index 4ad76d96a..21d4752d2 100644
--- a/docs/data_structures/alloc_specs.rst
+++ b/docs/data_structures/alloc_specs.rst
@@ -9,18 +9,14 @@ to main ``libE()`` routine::
 
     alloc_specs: [dict, optional] :
 
-        Required keys :
-
         'alloc_f' [func] :
             Default: give_sim_work_first
-
-        Optional keys :
-
+        'in' [list of strings] :
+            Default: None
         'out' [list of tuples] :
             Default: [('allocated',bool)]
-
-        'batch_mode' [bool] :
-            Default: True
+        'user' [dict]
+            Default: {'batch_mode': True}
 
 .. note::
 
diff --git a/docs/data_structures/data_structures.rst b/docs/data_structures/data_structures.rst
index 71c2398db..258f96ae2 100644
--- a/docs/data_structures/data_structures.rst
+++ b/docs/data_structures/data_structures.rst
@@ -14,7 +14,7 @@ This section outlines the data structures used by libEnsemble.
     check_inputs(sim_specs=my-sim_specs, gen_specs=my-gen_specs, exit_criteria=ec)
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :caption: libEnsemble Data Structures:
 
    sim_specs
diff --git a/docs/data_structures/gen_specs.rst b/docs/data_structures/gen_specs.rst
index b6518627d..c3250e3ae 100644
--- a/docs/data_structures/gen_specs.rst
+++ b/docs/data_structures/gen_specs.rst
@@ -7,8 +7,6 @@ to main ``libE()`` routine::
 
     gen_specs: [dict]:
 
-        Required keys :
-
         'gen_f' [func] :
             generates inputs to sim_f
         'in' [list] :
diff --git a/docs/data_structures/history_array.rst b/docs/data_structures/history_array.rst
index 6fea28898..9f2271f66 100644
--- a/docs/data_structures/history_array.rst
+++ b/docs/data_structures/history_array.rst
@@ -1,11 +1,7 @@
-***********************************
-Internal libEnsemble data structure
-***********************************
-
-.. _datastruct-history-array:
-
 history array
 =============
+.. _datastruct-history-array:
+
 ::
 
     H: numpy structured array
diff --git a/docs/data_structures/sim_specs.rst b/docs/data_structures/sim_specs.rst
index b2076ad2f..ae7a81885 100644
--- a/docs/data_structures/sim_specs.rst
+++ b/docs/data_structures/sim_specs.rst
@@ -1,6 +1,3 @@
-*********************
-Input data structures
-*********************
 We first describe the dictionaries given to libEnsemble to specify the
 inputs/outputs of the ensemble of calculations to be performed.
 
diff --git a/docs/dev_info.rst b/docs/dev_info.rst
new file mode 100644
index 000000000..c4f8c3cc7
--- /dev/null
+++ b/docs/dev_info.rst
@@ -0,0 +1,10 @@
+Advanced libEnsemble
+====================
+
+
+.. toctree::
+
+   contributing
+   dev_guide/dev_API/developer_API.rst
+   dev_guide/release_management/release_index.rst
+
diff --git a/docs/index.rst b/docs/index.rst
index f0d169a0e..56786d7a7 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -31,8 +31,7 @@
    :maxdepth: 2
    :caption: User Guide:
 
-   user_guide
-   libE_module
+   programming_libE
    data_structures/data_structures
    user_funcs
    job_controller/jc_index
diff --git a/docs/latex_index.rst b/docs/latex_index.rst
index f1938e38a..72a4bbb5f 100644
--- a/docs/latex_index.rst
+++ b/docs/latex_index.rst
@@ -6,23 +6,8 @@
    :maxdepth: 3
 
    Introduction<introduction>
-   user_guide
-   tutorials/local_sine_tutorial
-   platforms/bebop
-   platforms/theta
-   contributing
-   FAQ
-   libE_module
-   data_structures/data_structures
-   user_funcs
-   job_controller/jc_index
-   logging
-   dev_guide/release_management/release_index.rst
-   dev_guide/dev_API/developer_API.rst
-   release_notes
+   programming_libE
+   platforms/platforms
+   dev_info
+   appendix
 
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
diff --git a/docs/libE_module.rst b/docs/libE_module.rst
deleted file mode 100644
index 029004981..000000000
--- a/docs/libE_module.rst
+++ /dev/null
@@ -1,5 +0,0 @@
-libE Module
-===========
-.. automodule:: libE
-  :members:
-  :no-undoc-members:
diff --git a/docs/logging.rst b/docs/logging.rst
index c0a244e10..6301600e8 100644
--- a/docs/logging.rst
+++ b/docs/logging.rst
@@ -24,9 +24,6 @@ This boundary can be adjusted as follows::
 
 stderr displaying can be effectively disabled by setting the stderr level to CRITICAL.
 
-Logging API
------------
-
 .. automodule:: libE_logger
   :members:
   :no-undoc-members:
diff --git a/docs/programming_libE.rst b/docs/programming_libE.rst
new file mode 100644
index 000000000..ad8be08f9
--- /dev/null
+++ b/docs/programming_libE.rst
@@ -0,0 +1,36 @@
+Programming with libEnsemble
+============================
+
+.. automodule:: libE
+  :members:
+  :no-undoc-members:
+
+**libEnsemble Output**
+
+The history array :ref:`H<datastruct-history-array>` and
+:ref:`persis_info<datastruct-persis-info>` dictionary are returned to the user
+by libEnsemble.  If libEnsemble aborts on an exception, these structures are
+dumped to the respective files,
+
+* ``libE_history_at_abort_<sim_count>.npy``
+* ``libE_history_at_abort_<sim_count>.pickle``
+
+where ``sim_count`` is the number of points evaluated.
+
+Other libEnsemble files produced by default are:
+
+* ``libE_stats.txt``: This contains a one-line summary of all user
+  calculations.  Each calculation summary is sent by workers to the manager and
+  printed as the run progresses.
+
+* ``ensemble.log``: This is the logging output from libEnsemble. The default
+  logging is at INFO level. To gain additional diagnostics logging level can be
+  set to DEBUG.  If this file is not removed, multiple runs will append output.
+  Messages at or above level MANAGER_WARNING are also copied to stderr to alert
+  the user promptly.  For more info, see :doc:`Logging<logging>`.
+
+.. toctree::
+   data_structures/data_structures
+   user_funcs
+   job_controller/jc_index
+   logging
diff --git a/docs/sim_gen_alloc_funcs.rst b/docs/sim_gen_alloc_funcs.rst
index d1f627131..dbacbe475 100644
--- a/docs/sim_gen_alloc_funcs.rst
+++ b/docs/sim_gen_alloc_funcs.rst
@@ -1,10 +1,42 @@
-Sim, Gen, and Alloc functions API
-=================================
+User function API
+-----------------
 
-.. _api_sim_f:
+**The libEnsemble History Array**
+
+libEnsemble uses a NumPy structured array :ref:`H<datastruct-history-array>` to
+store output from ``gen_f`` and corresponding ``sim_f`` output. Similarly,
+``gen_f`` and ``sim_f`` are expected to return output in NumPy structured
+arrays. The names of the fields to be given as input to ``gen_f`` and ``sim_f``
+must be an output from ``gen_f`` or ``sim_f``. In addition to the fields output
+from ``sim_f`` and ``gen_f``, the final history returned from libEnsemble will
+include the following fields:
+
+* ``sim_id`` [int]: Each unit of work output from ``gen_f`` must have an
+  associated ``sim_id``. The generator can assign this, but users must be
+  careful to ensure points are added in order. For example, ``if alloc_f``
+  allows for two ``gen_f`` instances to be running simultaneously, ``alloc_f``
+  should ensure that both don’t generate points with the same ``sim_id``.
+
+* ``given`` [bool]: Has this ``gen_f`` output been given to a libEnsemble
+  worker to be evaluated yet?
+
+* ``given_time`` [float]: At what time (since the epoch) was this ``gen_f``
+  output given to a worker?
+
+* ``sim_worker`` [int]: libEnsemble worker that it was given to be evaluated.
+
+* ``gen_worker`` [int]: libEnsemble worker that generated this ``sim_id``
+
+* ``gen_time`` [float]: At what time (since the epoch) was this entry (or
+  collection of entries) put into ``H`` by the manager
+
+* ``returned`` [bool]: Has this worker completed the evaluation of this unit of
+  work?
 
 sim_f API
----------
+~~~~~~~~~
+.. _api_sim_f:
+
 
 The sim_f function will be called by libEnsemble with the following API::
 
@@ -41,10 +73,10 @@ Returns:
 ..  literalinclude:: ../libensemble/message_numbers.py
     :end-before: last_message_number_rst_tag
 
+gen_f API
+~~~~~~~~~
 .. _api_gen_f:
 
-gen_f API
----------
 
 The gen_f calculations will be called by libEnsemble with the following API::
 
@@ -81,10 +113,10 @@ Returns:
 ..  literalinclude:: ../libensemble/message_numbers.py
     :end-before: last_message_number_rst_tag
 
+alloc_f API
+~~~~~~~~~~~
 .. _api_alloc_f:
 
-alloc_f API
------------
 
 The alloc_f calculations will be called by libEnsemble with the following API::
 
diff --git a/docs/tutorials/local_sine_tutorial.rst b/docs/tutorials/local_sine_tutorial.rst
index 96498a735..e437be618 100644
--- a/docs/tutorials/local_sine_tutorial.rst
+++ b/docs/tutorials/local_sine_tutorial.rst
@@ -205,7 +205,7 @@ circumstances where libEnsemble should stop execution in :ref:`exit_criteria<dat
 
     exit_criteria = {'sim_max': 80}           # Stop libEnsemble after 80 simulations
 
-Now we're ready to write our libEnsemble :doc:`libE<../libE_module>` function call.
+Now we're ready to write our libEnsemble :doc:`libE<../programming_libE>` function call.
 This :ref:`H<datastruct-history-array>` is the final version of the History array.
 'flag' should be zero if no errors occur.
 
diff --git a/docs/tutorials/tutorials.rst b/docs/tutorials/tutorials.rst
new file mode 100644
index 000000000..c1ab22b68
--- /dev/null
+++ b/docs/tutorials/tutorials.rst
@@ -0,0 +1,8 @@
+
+
+Tutorials
+---------
+
+.. toctree::
+
+   local_sine_tutorial
diff --git a/docs/user_funcs.rst b/docs/user_funcs.rst
index f912ed73b..45533e3c8 100644
--- a/docs/user_funcs.rst
+++ b/docs/user_funcs.rst
@@ -1,14 +1,9 @@
-User Functions
-==============
-
 libEnsemble requires functions for generation, simulation and allocation.
 
 While libEnsemble provides a default allocation function, the sim and gen functions
 must be provided. The required API and examples are given here.
 
 .. toctree::
-   :maxdepth: 2
    :caption: libEnsemble User Functions:
 
    sim_gen_alloc_funcs
-   examples/examples_index
diff --git a/docs/user_guide.rst b/docs/user_guide.rst
deleted file mode 100644
index 960fc7864..000000000
--- a/docs/user_guide.rst
+++ /dev/null
@@ -1,126 +0,0 @@
-Introduction
-============
-
-libEnsemble overview
---------------------
-libEnsemble is a Python library to coordinate the concurrent evaluation of
-dynamic ensembles of calculations. libEnsemble uses a manager to allocate work to
-various workers. A libEnsemble worker is the smallest indivisible unit to
-perform some calculation. The work performed by libEnsemble is governed by
-three routines:
-
-* :ref:`gen_f<api_gen_f>`: Generates inputs to ``sim_f``.
-* :ref:`sim_f<api_sim_f>`: Evaluates a simulation or other evaluation at output from ``gen_f``.
-* :ref:`alloc_f<api_alloc_f>`: Decides whether ``sim_f`` or ``gen_f`` should be called (and with what input/resources) as workers become available.
-
-Example ``sim_f``, ``gen_f``, ``alloc_f``, and calling scripts
-be found in the ``examples/`` directory. To enable portability, a
-:doc:`job_controller<job_controller/overview>`
-interface is supplied for users to launch and monitor jobs in their
-user-provided ``sim_f`` and ``gen_f`` routines.
-
-The default ``alloc_f`` tells each available worker to call ``sim_f`` with the
-highest priority unit of work from ``gen_f``. If a worker is idle and there is
-no ``gen_f`` output to give, the worker is told to call ``gen_f``.
-
-Expected use cases
-------------------
-
-Below are some expected libEnsemble use cases that we support (or are working
-to support) and plan to have examples of:
-
-* A user is looking to optimize a simulation calculation. The simulation may
-  already be using parallel resources, but not a large fraction of some
-  computer. libEnsemble can coordinate the concurrent evaluation of the
-  simulation ``sim_f`` at various parameter values and ``gen_f`` would return
-  candidate parameter values (possibly after each ``sim_f`` output).
-
-* A user has a ``gen_f`` that produces different meshes to be used within a
-  ``sim_f``. Given the ``sim_f`` output, ``gen_f`` will refine a mesh or
-  produce a new mesh. libEnsemble can ensure that the calculated meshes can be
-  used by multiple simulations without requiring movement of data.
-
-* A user is attempting to sample a simulation ``sim_f`` at some parameter
-  values, many of which will cause the simulation to fail. libEnsemble can stop
-  unresponsive evaluations, and recover computational resources for future
-  evaluations. ``gen_f`` can possibly update the sampling after discovering
-  regions where evaluations of ``sim_f`` fail.
-
-* A user has a simulation ``sim_f`` that requires calculating multiple
-  expensive quantities, some of which depend on other quantities. ``sim_f`` can
-  observe intermediate quantities in order to stop related calculations and
-  preempt future calculations associated with poor parameter values.
-
-* A user has a ``sim_f`` with multiple fidelities, with the higher-fidelity
-  evaluations requiring more computational resources, and a
-  ``gen_f``/``alloc_f`` that decides which parameters should be evaluated and
-  at what fidelity level. libEnsemble can coordinate these evaluations without
-  requiring the user know parallel programming.
-
-* A user wishes to identify multiple local optima for a ``sim_f``. Furthermore,
-  sensitivity analysis is desired at each identified optimum. libEnsemble can
-  use the points from the APOSMM ``gen_f`` to identify optima; and after a
-  point is ruled to be an optimum, a different ``gen_f`` can produce a
-  collection of parameters necessary for sensitivity analysis of ``sim_f``.
-
-Naturally, combinations of these use cases are supported as well. An example of
-such a combination is using libEnsemble to solve an optimization problem that
-relies on simulations that fail frequently.
-
-The libEnsemble History Array
------------------------------
-
-libEnsemble uses a NumPy structured array :ref:`H<datastruct-history-array>` to
-store output from ``gen_f`` and corresponding ``sim_f`` output. Similarly,
-``gen_f`` and ``sim_f`` are expected to return output in NumPy structured
-arrays. The names of the fields to be given as input to ``gen_f`` and ``sim_f``
-must be an output from ``gen_f`` or ``sim_f``. In addition to the fields output
-from ``sim_f`` and ``gen_f``, the final history returned from libEnsemble will
-include the following fields:
-
-* ``sim_id`` [int]: Each unit of work output from ``gen_f`` must have an
-  associated ``sim_id``. The generator can assign this, but users must be
-  careful to ensure points are added in order. For example, ``if alloc_f``
-  allows for two ``gen_f`` instances to be running simultaneously, ``alloc_f``
-  should ensure that both don’t generate points with the same ``sim_id``.
-
-* ``given`` [bool]: Has this ``gen_f`` output been given to a libEnsemble
-  worker to be evaluated yet?
-
-* ``given_time`` [float]: At what time (since the epoch) was this ``gen_f``
-  output given to a worker?
-
-* ``sim_worker`` [int]: libEnsemble worker that it was given to be evaluated.
-
-* ``gen_worker`` [int]: libEnsemble worker that generated this ``sim_id``
-
-* ``gen_time`` [float]: At what time (since the epoch) was this entry (or
-  collection of entries) put into ``H`` by the manager
-
-* ``returned`` [bool]: Has this worker completed the evaluation of this unit of
-  work?
-
-libEnsemble Output
-------------------
-
-The history array :ref:`H<datastruct-history-array>` and
-:ref:`persis_info<datastruct-persis-info>` dictionary are returned to the user
-by libEnsemble.  If libEnsemble aborts on an exception, these structures are
-dumped to the respective files,
-
-* ``libE_history_at_abort_<sim_count>.npy``
-* ``libE_history_at_abort_<sim_count>.pickle``
-
-where ``sim_count`` is the number of points evaluated.
-
-Other libEnsemble files produced by default are:
-
-* ``libE_stats.txt``: This contains a one-line summary of all user
-  calculations.  Each calculation summary is sent by workers to the manager and
-  printed as the run progresses.
-
-* ``ensemble.log``: This is the logging output from libEnsemble. The default
-  logging is at INFO level. To gain additional diagnostics logging level can be
-  set to DEBUG.  If this file is not removed, multiple runs will append output.
-  Messages at or above level MANAGER_WARNING are also copied to stderr to alert
-  the user promptly.  For more info, see :doc:`Logging<logging>`.
diff --git a/docs/welcome.rst b/docs/welcome.rst
index 4dad228a2..7decf8888 100644
--- a/docs/welcome.rst
+++ b/docs/welcome.rst
@@ -27,5 +27,5 @@ libEnsemble is a library to coordinate the concurrent evaluation of dynamic ense
 
 * New to libEnsemble? Start :doc:`here<introduction>`.
 * Try out libEnsemble with a :doc:`tutorial<tutorials/local_sine_tutorial>`.
-* Go in-depth by reading the :doc:`User Guide<user_guide>`.
+* Go in-depth by reading the :doc:`User Guide<programming_libE>`.
 * Check the :doc:`FAQ<FAQ>` for common questions and answers, errors and resolutions.
diff --git a/libensemble/libE.py b/libensemble/libE.py
index 089c87e07..83c55783c 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -1,7 +1,13 @@
 """
-Main libEnsemble routine
-============================================
+This is the outer libEnsemble routine.
 
+We dispatch to different types of worker teams depending on
+the contents of libE_specs.  If 'comm' is a field, we use MPI;
+if 'nthreads' is a field, we use threads; if 'nprocesses' is a
+field, we use multiprocessing.
+
+If an exception is encountered by the manager or workers, the
+history array is dumped to file and MPI abort is called.
 """
 
 __all__ = ['libE']
@@ -35,15 +41,7 @@ def libE(sim_specs, gen_specs, exit_criteria,
                       'user': {'batch_mode': True}},
          libE_specs={},
          H0=[]):
-    """This is the outer libEnsemble routine.
-
-    We dispatch to different types of worker teams depending on
-    the contents of libE_specs.  If 'comm' is a field, we use MPI;
-    if 'nthreads' is a field, we use threads; if 'nprocesses' is a
-    field, we use multiprocessing.
-
-    If an exception is encountered by the manager or workers, the
-    history array is dumped to file and MPI abort is called.
+    """
 
     Parameters
     ----------
diff --git a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
index 054a60224..1d64a2eee 100644
--- a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
+++ b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
@@ -66,9 +66,9 @@
 
 alloc_specs = {'alloc_f': alloc_f,              # Allocation function
                'out': [('allocated', bool)],    # Output fields (included in History)
-               'user': {'stop_on_NaNs': True,            # Should alloc_f preempt evals
-                        'batch_mode': True,
-                        'stop_partial_fvec_eval': True}  # Should alloc_f preempt evals
+               'user': {'stop_on_NaNs': True,   # Should alloc preempt evals
+                        'batch_mode': True,     # Wait until all sim evals are done
+                        'stop_partial_fvec_eval': True}  # Should alloc preempt evals
                }
 # end_alloc_specs_rst_tag
 

From a074ae742c4fa1cf04fae31031b59b3f7e085d29 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 7 Nov 2019 15:50:32 -0600
Subject: [PATCH 450/644] Whitespace management

---
 README.rst                               | 6 +-----
 docs/data_structures/alloc_specs.rst     | 1 -
 docs/data_structures/data_structures.rst | 1 -
 docs/dev_info.rst                        | 2 --
 docs/latex_index.rst                     | 1 -
 docs/sim_gen_alloc_funcs.rst             | 3 ---
 docs/tutorials/tutorials.rst             | 2 --
 7 files changed, 1 insertion(+), 15 deletions(-)

diff --git a/README.rst b/README.rst
index b8d3c1e79..686f6dd1a 100644
--- a/README.rst
+++ b/README.rst
@@ -76,7 +76,6 @@ The default ``alloc_f`` tells each available worker to call ``sim_f`` with the
 highest priority unit of work from ``gen_f``. If a worker is idle and there is
 no ``gen_f`` output to give, the worker is told to call ``gen_f``.
 
-
 Example Use Cases
 ~~~~~~~~~~~~~~~~~
 Below are some expected libEnsemble use cases that we support (or are working
@@ -120,13 +119,12 @@ Naturally, combinations of these use cases are supported as well. An example of
 such a combination is using libEnsemble to solve an optimization problem that
 relies on simulations that fail frequently.
 
-
 Resources
 ~~~~~~~~~~~~~~~~~~
 
 **Support:**
 
-- Email questions to libensemble@lists.mcs.anl.gov 
+- Email questions to libensemble@lists.mcs.anl.gov
 - Communicate (and establish a private channel, if desired) at https://libensemble.slack.com
 - Join the libEnsemble mailing list for updates about new releases at https://lists.mcs.anl.gov/mailman/listinfo/libensemble
 
@@ -150,12 +148,10 @@ Resources
     url         = {https://buildmedia.readthedocs.org/media/pdf/libensemble/latest/libensemble.pdf}
   }
 
-
 **Other:**
 
 - A visual overview of libEnsemble is given in this poster_.
 
-
 Quickstart
 ----------
 
diff --git a/docs/data_structures/alloc_specs.rst b/docs/data_structures/alloc_specs.rst
index 21d4752d2..61cfd54eb 100644
--- a/docs/data_structures/alloc_specs.rst
+++ b/docs/data_structures/alloc_specs.rst
@@ -1,4 +1,3 @@
-
 .. _datastruct-alloc-specs:
 
 alloc_specs
diff --git a/docs/data_structures/data_structures.rst b/docs/data_structures/data_structures.rst
index 258f96ae2..dbbbc81ac 100644
--- a/docs/data_structures/data_structures.rst
+++ b/docs/data_structures/data_structures.rst
@@ -24,7 +24,6 @@ This section outlines the data structures used by libEnsemble.
    persis_info
    exit_criteria
 
-
    history_array
    worker_array
    work_dict
diff --git a/docs/dev_info.rst b/docs/dev_info.rst
index c4f8c3cc7..5dac3013c 100644
--- a/docs/dev_info.rst
+++ b/docs/dev_info.rst
@@ -1,10 +1,8 @@
 Advanced libEnsemble
 ====================
 
-
 .. toctree::
 
    contributing
    dev_guide/dev_API/developer_API.rst
    dev_guide/release_management/release_index.rst
-
diff --git a/docs/latex_index.rst b/docs/latex_index.rst
index 72a4bbb5f..baaccf059 100644
--- a/docs/latex_index.rst
+++ b/docs/latex_index.rst
@@ -10,4 +10,3 @@
    platforms/platforms
    dev_info
    appendix
-
diff --git a/docs/sim_gen_alloc_funcs.rst b/docs/sim_gen_alloc_funcs.rst
index dbacbe475..fe2d4b96a 100644
--- a/docs/sim_gen_alloc_funcs.rst
+++ b/docs/sim_gen_alloc_funcs.rst
@@ -37,7 +37,6 @@ sim_f API
 ~~~~~~~~~
 .. _api_sim_f:
 
-
 The sim_f function will be called by libEnsemble with the following API::
 
     out = sim_f(H[sim_specs['in']][sim_ids_from_allocf], persis_info, sim_specs, libE_info)
@@ -77,7 +76,6 @@ gen_f API
 ~~~~~~~~~
 .. _api_gen_f:
 
-
 The gen_f calculations will be called by libEnsemble with the following API::
 
     out = gen_f(H[gen_specs['in']][sim_ids_from_allocf], persis_info, gen_specs, libE_info)
@@ -117,7 +115,6 @@ alloc_f API
 ~~~~~~~~~~~
 .. _api_alloc_f:
 
-
 The alloc_f calculations will be called by libEnsemble with the following API::
 
   Work, persis_info = alloc_f(W, H, sim_specs, gen_specs, alloc_specs, persis_info)
diff --git a/docs/tutorials/tutorials.rst b/docs/tutorials/tutorials.rst
index c1ab22b68..4d212ea44 100644
--- a/docs/tutorials/tutorials.rst
+++ b/docs/tutorials/tutorials.rst
@@ -1,5 +1,3 @@
-
-
 Tutorials
 ---------
 

From f36ee902fc40f282acac2dcc4d54b3d6e965bb6d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 7 Nov 2019 16:43:01 -0600
Subject: [PATCH 451/644] Trying to format the HTML similarly

---
 docs/dev_info.rst |  4 ++--
 docs/index.rst    | 32 +++++---------------------------
 2 files changed, 7 insertions(+), 29 deletions(-)

diff --git a/docs/dev_info.rst b/docs/dev_info.rst
index 5dac3013c..4c4fdab68 100644
--- a/docs/dev_info.rst
+++ b/docs/dev_info.rst
@@ -1,5 +1,5 @@
-Advanced libEnsemble
-====================
+Developer's Guide
+=================
 
 .. toctree::
 
diff --git a/docs/index.rst b/docs/index.rst
index 56786d7a7..2d7035654 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,39 +10,17 @@
    :caption: Getting Started:
 
    Introduction<introduction>
-   contributing
-   release_notes
-   FAQ
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Tutorials:
-
-   tutorials/local_sine_tutorial
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Running on:
+   programming_libE
 
-   platforms/bebop
-   platforms/theta
 
 .. toctree::
+   :caption: Further information:
    :maxdepth: 2
-   :caption: User Guide:
-
-   programming_libE
-   data_structures/data_structures
-   user_funcs
-   job_controller/jc_index
-   logging
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Developer Guide:
+   platforms/platforms
+   dev_info
+   tutorials/tutorials
 
-   dev_guide/release_management/release_index.rst
-   dev_guide/dev_API/developer_API.rst
 
 Indices and tables
 ==================

From c5fb9d3a3a6a50ce6cae52b8c42387f6d7aaa085 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 7 Nov 2019 17:51:43 -0600
Subject: [PATCH 452/644] Adding FAQ and release notes

---
 docs/index.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index 2d7035654..ad20caa98 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -12,16 +12,16 @@
    Introduction<introduction>
    programming_libE
 
-
 .. toctree::
    :caption: Further information:
    :maxdepth: 2
 
+   FAQ
+   release_notes
    platforms/platforms
    dev_info
    tutorials/tutorials
 
-
 Indices and tables
 ==================
 

From 1961cc403501ba7e8b42577f1b259ec0cffcd7a0 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 8 Nov 2019 09:29:01 -0600
Subject: [PATCH 453/644] Using a bibliography

---
 docs/appendix.rst               |  4 +---
 docs/bibliography.rst           |  5 +++++
 docs/conf.py                    |  2 +-
 docs/index.rst                  |  2 +-
 docs/platforms/platforms.rst    |  7 +++++++
 docs/references.bib             | 12 ++++++++++++
 libensemble/gen_funcs/aposmm.py |  3 +--
 tex/bibs/masterbib.bib          | 15 ---------------
 8 files changed, 28 insertions(+), 22 deletions(-)
 create mode 100644 docs/bibliography.rst
 create mode 100644 docs/platforms/platforms.rst
 create mode 100644 docs/references.bib

diff --git a/docs/appendix.rst b/docs/appendix.rst
index a1561e2c4..b1455d669 100644
--- a/docs/appendix.rst
+++ b/docs/appendix.rst
@@ -6,6 +6,4 @@ Appendices
    FAQ
    release_notes
    examples/examples_index
-
-Bibliography
-------------
+   bibliography
diff --git a/docs/bibliography.rst b/docs/bibliography.rst
new file mode 100644
index 000000000..8c87684c0
--- /dev/null
+++ b/docs/bibliography.rst
@@ -0,0 +1,5 @@
+Bibliography
+------------
+.. Note that you can't reference a bib file in a different directory
+
+.. bibliography:: references.bib 
diff --git a/docs/conf.py b/docs/conf.py
index 00aaf27d3..f6a8f9431 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -58,7 +58,7 @@ def __getattr__(cls, name):
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.imgconverter']
+extensions = ['sphinxcontrib.bibtex','sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.imgconverter']
 #extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'numpydoc']
 #extensions = ['sphinx.ext.autodoc', 'breathe']
 #breathe_projects = { "libEnsemble": "../code/src/xml/" }
diff --git a/docs/index.rst b/docs/index.rst
index ad20caa98..758f7b98e 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,7 +14,7 @@
 
 .. toctree::
    :caption: Further information:
-   :maxdepth: 2
+   :maxdepth: 1
 
    FAQ
    release_notes
diff --git a/docs/platforms/platforms.rst b/docs/platforms/platforms.rst
new file mode 100644
index 000000000..bb0295a50
--- /dev/null
+++ b/docs/platforms/platforms.rst
@@ -0,0 +1,7 @@
+Platforms
+---------
+
+.. toctree::
+
+   theta
+   bebop
diff --git a/docs/references.bib b/docs/references.bib
new file mode 100644
index 000000000..153d16cdf
--- /dev/null
+++ b/docs/references.bib
@@ -0,0 +1,12 @@
+@Article{LW16,
+  gurl = {https://scholar.google.com/scholar?cluster=16597238545742984308},
+  author  = {Jeffrey Larson and Stefan M. Wild},
+  title   = {Asynchronously Parallel Optimization Solver for Finding Multiple Minima},
+  journal = {Mathematical Programming Computation},
+  year    = {2018},
+  number  = {3},
+  volume  = {10},
+  pages   = {303--332},
+  anumber = {ANL/MCS-P5575-0316},
+  doi     = {10.1007/s12532-017-0131-4},
+}
diff --git a/libensemble/gen_funcs/aposmm.py b/libensemble/gen_funcs/aposmm.py
index 84b53c949..e1816a00e 100644
--- a/libensemble/gen_funcs/aposmm.py
+++ b/libensemble/gen_funcs/aposmm.py
@@ -1,8 +1,7 @@
 """
 This module contains methods used our implementation of the Asynchronously
 Parallel Optimization Solver for finding Multiple Minima (APOSMM) method
-described in detail in the paper
-`https://doi.org/10.1007/s12532-017-0131-4 <https://doi.org/10.1007/s12532-017-0131-4>`_
+described in detail in :cite:`LW16` 
 """
 __all__ = ['aposmm_logic', 'initialize_APOSMM',
            'decide_where_to_start_localopt', 'update_history_dist']
diff --git a/tex/bibs/masterbib.bib b/tex/bibs/masterbib.bib
index ac2095634..f5f638b52 100644
--- a/tex/bibs/masterbib.bib
+++ b/tex/bibs/masterbib.bib
@@ -289,13 +289,6 @@ @article{Amundson2006
   year = {2006}
 }
 
-@article{Amundson,
-  author = {Amundson, James and Lu, Qiming and Stern, Eric},
-  journal = {dlr.de},
-  title = {Synergia: Driving Massively Parallel Particle Accelerator Simulations with Python},
-  url = {http://www.dlr.de/sc/en/Portaldata/15/Resources/dokumente/PyHPC2013/submissions/pyhpc2013\_submission\_12.pdf}
-}
-
 @misc{Lusk,
   author = {Lusk, Ewing L. and Pieper, Steven C. and Butler, Ralph M.},
   title = {ADLB4 User's Guide},
@@ -399,14 +392,6 @@ @article{Amundson2009
   year = {2009}
 }
 
-@article{Wang,
-  author = {Wang, Yusong and Borland, Michael and Soliday, Robert},
-  journal = {aps.anl.gov},
-  pages = {1--7},
-  title = {User's Manual for latest Pelegant},
-  url = {http://www.aps.anl.gov/Accelerator\_Systems\_Division/Accelerator\_Operations\_Physics/publish/Pelegant\_manual/Pelegant.pdf}
-}
-
 @phdthesis{Wild2009,
   author = {Wild, S. M.},
   number = {January},

From efff0e85ae62092c378d2b414cf351081eea921d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 8 Nov 2019 09:37:34 -0600
Subject: [PATCH 454/644] Adding all appendices to html output

---
 docs/index.rst | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index 758f7b98e..4d02257fa 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -14,13 +14,11 @@
 
 .. toctree::
    :caption: Further information:
-   :maxdepth: 1
+   :maxdepth: 2
 
-   FAQ
-   release_notes
    platforms/platforms
    dev_info
-   tutorials/tutorials
+   In Depth<appendix>
 
 Indices and tables
 ==================

From a2e5db1d588bf7b0896deed569934f1bbe9ddf7d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 8 Nov 2019 09:50:56 -0600
Subject: [PATCH 455/644] Trying to install on Readthedocs

---
 .gitignore       | 1 +
 .readthedocs.yml | 1 +
 2 files changed, 2 insertions(+)

diff --git a/.gitignore b/.gitignore
index 135bf4670..28292b058 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,3 +8,4 @@ code/tests/regression_tests/output/
 .cache
 libensemble.egg-info
 docs/_build
+x.log
diff --git a/.readthedocs.yml b/.readthedocs.yml
index a8f801e04..7ba231848 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -5,3 +5,4 @@ python:
     version: 3.6
     pip_install: true
     setup_py_install: true
+    install: sphinxcontrib.bibtex

From 91dac1a788c4575d913664240ea45cbcf82fd214 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 8 Nov 2019 09:56:12 -0600
Subject: [PATCH 456/644] Trying to install in conda environment for
 readthedocs

---
 .readthedocs.yml      | 1 -
 conda/environment.yml | 3 +++
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index 7ba231848..a8f801e04 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -5,4 +5,3 @@ python:
     version: 3.6
     pip_install: true
     setup_py_install: true
-    install: sphinxcontrib.bibtex
diff --git a/conda/environment.yml b/conda/environment.yml
index 57e16c744..35956d3b8 100644
--- a/conda/environment.yml
+++ b/conda/environment.yml
@@ -1,2 +1,5 @@
 dependencies:
  - python>=3.6
+ - pip
+ - pip:
+   - sphinxcontrib.bibtex

From 0e7299c2100b3b50108c8d710bc2b27fd73fd3e5 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 8 Nov 2019 10:08:21 -0600
Subject: [PATCH 457/644] adjusts affinity info, clarifies distribution options
 and limitations

---
 docs/platforms/bebop.rst           | 13 +++++++++----
 docs/platforms/platforms_index.rst | 24 ++++++++++++++----------
 docs/platforms/theta.rst           |  4 ++--
 3 files changed, 25 insertions(+), 16 deletions(-)

diff --git a/docs/platforms/bebop.rst b/docs/platforms/bebop.rst
index 167b02914..3e64c2085 100644
--- a/docs/platforms/bebop.rst
+++ b/docs/platforms/bebop.rst
@@ -39,6 +39,10 @@ Bebop uses Slurm_ for job submission and management. The two commands you'll
 likely use the most to run jobs are ``srun`` and ``sbatch`` for running
 interactively and batch, respectively.
 
+libEnsemble node-worker affinity is especially flexible on Bebop. By adjusting
+``srun`` runtime options_ users may assign multiple libEnsemble  workers to each
+allocated node(oversubscription) or assign multiple nodes per worker.
+
 Interactive Runs
 ^^^^^^^^^^^^^^^^
 
@@ -48,10 +52,11 @@ You can allocate four Knights Landing nodes for thirty minutes through the follo
 
 With your nodes allocated, queue your job to start with five MPI ranks::
 
-    srun -n 5 python calling.py
+    srun -n 4 python calling.py
 
-``mpirun`` should also work. This launches a worker on every node, on which every
-worker can perform stand-alone calculations or launch jobs through the job controller.
+``mpirun`` should also work. This line launches libEnsemble with a manager and
+**three** workers to one allocated compute node, with three nodes available for
+the workers to launch calculations with the job-controller or a job-launch command.
 
 .. note::
     When performing an MPI libEnsemble run and not oversubscribing, specify one
@@ -69,7 +74,6 @@ for thirty minutes::
     You will need to re-activate your conda virtual environment and reload your
     modules! Configuring this routine to occur automatically is recommended.
 
-
 Batch Runs
 ^^^^^^^^^^
 
@@ -118,3 +122,4 @@ See the LCRC Bebop docs here_ for more information about Bebop.
 .. _mpi4py: https://mpi4py.readthedocs.io/en/stable/
 .. _Slurm: https://slurm.schedmd.com/
 .. _here: https://www.lcrc.anl.gov/for-users/using-lcrc/running-jobs/running-jobs-on-bebop/
+.. _options: https://slurm.schedmd.com/srun.html
diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst
index cd6f58f7f..3716ebf47 100644
--- a/docs/platforms/platforms_index.rst
+++ b/docs/platforms/platforms_index.rst
@@ -1,6 +1,6 @@
 
 libEnsemble has been largely developed, supported, and tested on Linux
-distributions and macOS, from laptops to hundreds of compute-nodes. Although
+distributions and macOS, from laptops to thousands of compute-nodes. Although
 libEnsemble and most user functions are cross-platform compatible, there are
 platform-specific differences for installing and configuring libEnsemble.
 
@@ -8,11 +8,15 @@ Personal Computers
 ==================
 
 Users interested in installing and running libEnsemble on their personal machines
-are encouraged to read the Quickstart guide :doc:`here<../quickstart>`.
+are encouraged to start by reading the Quickstart guide :doc:`here<../quickstart>`.
 
+We recommend installing libEnsemble and it's dependencies in a virtual environment,
+created either through ``conda create``, ``virtualenv``, or ``python -m venv``,
+depending on how Python is installed.
 
-High-Powered Systems
-====================
+
+HPC Systems
+===========
 
 libEnsemble's flexible architecture lends it best to two general modes of worker
 distributions across allocated compute nodes. The first mode we refer
@@ -38,15 +42,15 @@ other workers directly on one or more allocated nodes:
 
 .. note::
 
-    Certain machines (like Theta and Summit) that do not support child-process
-    launches also do not support libEnsemble in distributed mode.
+    Certain machines (like Theta and Summit) that can only submit MPI jobs from
+    specialized launch nodes do not support libEnsemble in distributed mode.
 
-Due to this factor, Theta and Summit approach centralized mode differently.
-On these machines, libEnsemble is run centralized on either a compute-node with
-the support of Balsam_ or on a frontend server called a MOM
+Due to this factor, libEnsemble on Theta and Summit approaches centralized mode
+differently. On these machines, libEnsemble is run centralized on either a
+compute-node with the support of Balsam_ or on a frontend server called a MOM
 (Machine-Oriented Mini-server) node.
 
-Read more about configuring and launching libEnsemble on some HPC machines:
+Read more about configuring and launching libEnsemble on some HPC systems:
 
 .. toctree::
     :maxdepth: 2
diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index 06e95a550..aa0286299 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -32,8 +32,8 @@ libEnsemble and mpi4py
 
 There should be an indication that the virtual environment is activated.
 Install mpi4py_ and libEnsemble in this environment, making sure to reference
-the pre-installed Intel MPI Compiler. Your prompt should be similar to the
-following block:
+the pre-installed Intel C Compiler (which should support MPI). Your prompt may
+be similar to the following block:
 
 .. code-block:: console
 

From 0ec86518ffb2800f18347d54da5b3679471279f1 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 8 Nov 2019 10:09:34 -0600
Subject: [PATCH 458/644] Trying to install in conda environment for
 readthedocs

---
 .readthedocs.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index a8f801e04..b4acdd5c0 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -5,3 +5,5 @@ python:
     version: 3.6
     pip_install: true
     setup_py_install: true
+    install: 
+     - sphinxcontrib.bibtex

From 3cc665be91adca7471aa4558a0524fa333fd8484 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 8 Nov 2019 10:19:16 -0600
Subject: [PATCH 459/644] Trying to install in conda environment for
 readthedocs

---
 setup.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/setup.py b/setup.py
index b6439cba8..cb55be1d2 100644
--- a/setup.py
+++ b/setup.py
@@ -61,7 +61,7 @@ def run_tests(self):
                    ],
 
     extras_require={
-        'extras': ['scipy', 'nlopt', 'mpi4py', 'petsc', 'petsc4py']},
+        'extras': ['scipy', 'nlopt', 'mpi4py', 'petsc', 'petsc4py', 'sphinxcontrib.bibtex']},
 
     classifiers=[
         'Development Status :: 4 - Beta',

From e7d92751ddedf8792c9e4b0123e3eb13d3b728ad Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 8 Nov 2019 10:49:42 -0600
Subject: [PATCH 460/644] Stefan comments

---
 CONTRIBUTING.rst                 |  4 ++--
 docs/FAQ.rst                     |  4 ++--
 docs/appendix.rst                |  2 +-
 docs/conf.py                     |  5 ++---
 docs/examples/examples_index.rst |  8 +++++---
 docs/index.rst                   | 11 ++++++++++-
 docs/platforms/bebop.rst         |  4 ++--
 docs/platforms/theta.rst         |  4 ++--
 docs/sim_gen_alloc_funcs.rst     |  2 +-
 9 files changed, 27 insertions(+), 17 deletions(-)

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index b68b88a5d..cb40685d2 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -1,5 +1,5 @@
-Contributing
-============
+Contributing to libEnsemble
+===========================
 
 Contributions may be made via GitHub pull request to:
 
diff --git a/docs/FAQ.rst b/docs/FAQ.rst
index 6a9a52aa6..5512df3f9 100644
--- a/docs/FAQ.rst
+++ b/docs/FAQ.rst
@@ -103,8 +103,8 @@ does libEnsemble hang on certain systems when running with MPI?"
 
 For more information see: https://bitbucket.org/mpi4py/mpi4py/issues/102/unpicklingerror-on-commrecv-after-iprobe
 
-libEnsemble-theory
-------------------
+libEnsemble Help 
+----------------
 
 **How can I debug specific libEnsemble processes?**
 
diff --git a/docs/appendix.rst b/docs/appendix.rst
index b1455d669..a99b081ef 100644
--- a/docs/appendix.rst
+++ b/docs/appendix.rst
@@ -4,6 +4,6 @@ Appendices
 .. toctree::
    tutorials/tutorials
    FAQ
-   release_notes
    examples/examples_index
+   release_notes
    bibliography
diff --git a/docs/conf.py b/docs/conf.py
index f6a8f9431..575bb506c 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -58,9 +58,8 @@ def __getattr__(cls, name):
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinxcontrib.bibtex','sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.imgconverter']
-#extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'numpydoc']
-#extensions = ['sphinx.ext.autodoc', 'breathe']
+# extensions = ['sphinxcontrib.bibtex','sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.imgconverter']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.imgconverter']
 #breathe_projects = { "libEnsemble": "../code/src/xml/" }
 #breathe_default_project = "libEnsemble"
 
diff --git a/docs/examples/examples_index.rst b/docs/examples/examples_index.rst
index 10b7003fa..b2cc588ab 100644
--- a/docs/examples/examples_index.rst
+++ b/docs/examples/examples_index.rst
@@ -1,7 +1,8 @@
-Example User Funcs
-==================
+Example User Functions and Calling Scripts
+==========================================
 
-Example gen, sim and alloc functions for libEnsemble.
+Example generation, simulation, and alloction functions for libEnsemble, as
+well as example calling scripts.
 
 .. toctree::
    :maxdepth: 2
@@ -10,3 +11,4 @@ Example gen, sim and alloc functions for libEnsemble.
    gen_funcs
    sim_funcs
    alloc_funcs
+   calling_scripts
diff --git a/docs/index.rst b/docs/index.rst
index 4d02257fa..6d2860a58 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,7 +18,16 @@
 
    platforms/platforms
    dev_info
-   In Depth<appendix>
+
+.. toctree::
+   :caption: In Depth:
+   :maxdepth: 2
+
+   tutorials/tutorials
+   FAQ
+   examples/examples_index
+   bibliography
+   release_notes
 
 Indices and tables
 ==================
diff --git a/docs/platforms/bebop.rst b/docs/platforms/bebop.rst
index 2a42413a7..31cfe5d6b 100644
--- a/docs/platforms/bebop.rst
+++ b/docs/platforms/bebop.rst
@@ -5,8 +5,8 @@ Bebop
 Bebop_ is the newest addition to the computational power of LCRC at Argonne
 National Laboratory, featuring both Intel Broadwell and Knights Landing nodes.
 
-Before Getting Started
-----------------------
+Prerequisites
+-------------
 
 An Argonne LCRC_ account is required to access Bebop. Interested users will need
 to apply for and be granted an account before continuing. To submit jobs to Bebop,
diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index d266a347f..ee6b86b23 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -5,8 +5,8 @@ Theta
 Theta_ is a 11.69 petaflops system based on the second-generation Intel Xeon Phi
 processor, available within ALCF_ at Argonne National Laboratory.
 
-Before Getting Started
-----------------------
+Prerequisites
+-------------
 
 An Argonne ALCF account is required to access Theta. Interested users will need
 to apply for and be granted an account before continuing. To submit jobs to Theta,
diff --git a/docs/sim_gen_alloc_funcs.rst b/docs/sim_gen_alloc_funcs.rst
index fe2d4b96a..cdabafa7e 100644
--- a/docs/sim_gen_alloc_funcs.rst
+++ b/docs/sim_gen_alloc_funcs.rst
@@ -1,4 +1,4 @@
-User function API
+User Function API
 -----------------
 
 **The libEnsemble History Array**

From 8558f47307b6007bcc00de9d1ddf2d79cd30648f Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 8 Nov 2019 10:51:11 -0600
Subject: [PATCH 461/644] Stefan comments

---
 docs/examples/calling_scripts.rst | 4 ++++
 1 file changed, 4 insertions(+)
 create mode 100644 docs/examples/calling_scripts.rst

diff --git a/docs/examples/calling_scripts.rst b/docs/examples/calling_scripts.rst
new file mode 100644
index 000000000..9a975ecb4
--- /dev/null
+++ b/docs/examples/calling_scripts.rst
@@ -0,0 +1,4 @@
+Calling Scripts
+===============
+
+Below are example calling scripts

From 1776f628e8da5142af922aa7cbc20f94e14e7fd3 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 8 Nov 2019 10:55:38 -0600
Subject: [PATCH 462/644] Trying requirements

---
 .readthedocs.yml      | 4 ++--
 README.rst            | 4 ++--
 docs/conf.py          | 4 ++--
 docs/requirements.txt | 1 +
 4 files changed, 7 insertions(+), 6 deletions(-)
 create mode 100644 docs/requirements.txt

diff --git a/.readthedocs.yml b/.readthedocs.yml
index b4acdd5c0..6c550b1b7 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -5,5 +5,5 @@ python:
     version: 3.6
     pip_install: true
     setup_py_install: true
-    install: 
-     - sphinxcontrib.bibtex
+    install:
+      - requirements: docs/requirements.txt
diff --git a/README.rst b/README.rst
index 686f6dd1a..dc00bbfcd 100644
--- a/README.rst
+++ b/README.rst
@@ -152,8 +152,8 @@ Resources
 
 - A visual overview of libEnsemble is given in this poster_.
 
-Quickstart
-----------
+Quickstart Guide
+----------------
 
 Dependencies
 ~~~~~~~~~~~~
diff --git a/docs/conf.py b/docs/conf.py
index 575bb506c..d4574a772 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -58,8 +58,8 @@ def __getattr__(cls, name):
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-# extensions = ['sphinxcontrib.bibtex','sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.imgconverter']
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.imgconverter']
+extensions = ['sphinxcontrib.bibtex','sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.imgconverter']
+# extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.imgconverter']
 #breathe_projects = { "libEnsemble": "../code/src/xml/" }
 #breathe_default_project = "libEnsemble"
 
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 000000000..c3e8a7601
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1 @@
+sphinxcontrib.bibtex

From ff3900017f301a358c749a7df7507b7d6114b553 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 8 Nov 2019 11:17:10 -0600
Subject: [PATCH 463/644] Reverting so everything builds

---
 docs/conf.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index d4574a772..575bb506c 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -58,8 +58,8 @@ def __getattr__(cls, name):
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinxcontrib.bibtex','sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.imgconverter']
-# extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.imgconverter']
+# extensions = ['sphinxcontrib.bibtex','sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.imgconverter']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.imgconverter']
 #breathe_projects = { "libEnsemble": "../code/src/xml/" }
 #breathe_default_project = "libEnsemble"
 

From 4d837ef8d71bfa510c4769334d6e7058c255e573 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 8 Nov 2019 13:47:22 -0600
Subject: [PATCH 464/644] Trying to do this on develop in case that is what is
 looked at

---
 .readthedocs.yml      | 10 ++++++++++
 docs/requirements.txt |  2 ++
 2 files changed, 12 insertions(+)
 create mode 100644 docs/requirements.txt

diff --git a/.readthedocs.yml b/.readthedocs.yml
index a8f801e04..c69fa2936 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -1,7 +1,17 @@
 conda:
     file: conda/environment.yml
+    environment: environment.yml
+
+build:
+    image: latest
 
 python:
     version: 3.6
     pip_install: true
     setup_py_install: true
+    install:
+      - method: pip
+      - sphinxcontrib.bibtex
+      - sphinxcontrib-bibtex
+      - requirements: docs/requirements.txt
+    system_packages: true
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 000000000..a8e61ba18
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,2 @@
+sphinxcontrib.bibtex
+sphinxcontrib-bibtex

From ed96185d6b469e1e92f439899a7722f33cd26d2e Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 8 Nov 2019 13:53:35 -0600
Subject: [PATCH 465/644] Trying to do this on develop in case that is what is
 looked at

---
 conda/environment.yml | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/conda/environment.yml b/conda/environment.yml
index 57e16c744..8d2d32006 100644
--- a/conda/environment.yml
+++ b/conda/environment.yml
@@ -1,2 +1,6 @@
 dependencies:
  - python>=3.6
+ - pip
+ - pip:
+   - sphinxcontrib.bibtex
+   - sphinxcontrib-bibtex

From 96554822547e0e28b32b9d4510bcddcc4954956f Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 8 Nov 2019 14:39:30 -0600
Subject: [PATCH 466/644] rework theta python, rework launch-modes, combine
 diagrams, other fixes

---
 docs/images/centralized_MOM_ThS.png | Bin 0 -> 42582 bytes
 docs/images/centralized_MOM_ThS.xml | 109 +++++++++++++
 docs/images/combined_ThS.png        | Bin 0 -> 118488 bytes
 docs/images/combined_ThS.xml        | 240 ++++++++++++++++++++++++++++
 docs/platforms/theta.rst            |  87 +++++-----
 5 files changed, 397 insertions(+), 39 deletions(-)
 create mode 100644 docs/images/centralized_MOM_ThS.png
 create mode 100644 docs/images/centralized_MOM_ThS.xml
 create mode 100644 docs/images/combined_ThS.png
 create mode 100644 docs/images/combined_ThS.xml

diff --git a/docs/images/centralized_MOM_ThS.png b/docs/images/centralized_MOM_ThS.png
new file mode 100644
index 0000000000000000000000000000000000000000..a3489071e0681e6f5df493d7abb19e64ba9ad914
GIT binary patch
literal 42582
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
RUOt82wlJ|Wer)7S`8RKaz{UUo

literal 0
HcmV?d00001

diff --git a/docs/images/centralized_MOM_ThS.xml b/docs/images/centralized_MOM_ThS.xml
new file mode 100644
index 000000000..297c1b0f8
--- /dev/null
+++ b/docs/images/centralized_MOM_ThS.xml
@@ -0,0 +1,109 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<mxfile host="www.draw.io" modified="2019-11-08T19:54:28.064Z" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:70.0) Gecko/20100101 Firefox/70.0" etag="32E-A2s7jGqyUMG02E-I" version="12.2.3" type="device" pages="1">
+  <diagram id="Ck9LrmPIcHI4nulA-FHf" name="Page-1">
+    <mxGraphModel dx="488" dy="457" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
+      <root>
+        <mxCell id="0"/>
+        <mxCell id="1" parent="0"/>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-1" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;strokeWidth=2;fillColor=#e1d5e7;strokeColor=#9673a6;" vertex="1" parent="1">
+          <mxGeometry x="495" y="470" width="120" height="130" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-4" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shadow=1;endArrow=none;endFill=0;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;" edge="1" parent="1" source="uerdhfQnPlBMxC_uqtUS-7" target="uerdhfQnPlBMxC_uqtUS-11">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="525" y="505"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-5" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shadow=1;endArrow=none;endFill=0;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;" edge="1" parent="1" source="uerdhfQnPlBMxC_uqtUS-7" target="uerdhfQnPlBMxC_uqtUS-19">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="525" y="575"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-6" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shadow=1;endArrow=none;endFill=0;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;" edge="1" parent="1" source="uerdhfQnPlBMxC_uqtUS-7" target="uerdhfQnPlBMxC_uqtUS-15">
+          <mxGeometry relative="1" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-7" value="&lt;b&gt;Mgr&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="505" y="525" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-8" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="430" y="350" width="70" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-9" value="&lt;b&gt;Node 0&lt;br&gt;&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="440" y="350" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-36" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;fillColor=#ffe6cc;strokeColor=#d79b00;strokeWidth=3;endArrow=block;endFill=1;" edge="1" parent="1" source="uerdhfQnPlBMxC_uqtUS-11" target="uerdhfQnPlBMxC_uqtUS-8">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="610" y="505"/>
+              <mxPoint x="610" y="460"/>
+              <mxPoint x="465" y="460"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-11" value="&lt;b&gt;Wrk0&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="555" y="490" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-12" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="520" y="350" width="70" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-13" value="&lt;b&gt;Node 1&lt;br&gt;&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="530" y="350" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-37" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;endArrow=block;endFill=1;" edge="1" parent="1" source="uerdhfQnPlBMxC_uqtUS-15" target="uerdhfQnPlBMxC_uqtUS-12">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="630" y="540"/>
+              <mxPoint x="630" y="450"/>
+              <mxPoint x="555" y="450"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-15" value="&lt;b&gt;Wrk1&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="555" y="525" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-16" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="610" y="350" width="70" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-17" value="&lt;b&gt;Node 2&lt;br&gt;&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="620" y="350" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-38" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;endArrow=block;endFill=1;" edge="1" parent="1" source="uerdhfQnPlBMxC_uqtUS-19" target="uerdhfQnPlBMxC_uqtUS-16">
+          <mxGeometry relative="1" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-19" value="&lt;b&gt;Wrk2&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="555" y="560" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-20" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="450" y="405" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-21" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="540" y="395" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-22" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="630" y="375" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-23" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="630" y="390" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-24" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="630" y="405" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-25" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="540" y="380" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-26" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="450" y="375" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-27" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="450" y="390" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="uerdhfQnPlBMxC_uqtUS-28" value="&lt;b&gt;MOM Node&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;shadow=1;glass=0;comic=0;" vertex="1" parent="1">
+          <mxGeometry x="515" y="470" width="80" height="20" as="geometry"/>
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>
diff --git a/docs/images/combined_ThS.png b/docs/images/combined_ThS.png
new file mode 100644
index 0000000000000000000000000000000000000000..651fc4d7ed5f5e41d6f479b3ef12732f4aa4159f
GIT binary patch
literal 118488
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%0Ao)W{VhT~jidudF}j6i%B^EZn%;
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
B&LRK+

literal 0
HcmV?d00001

diff --git a/docs/images/combined_ThS.xml b/docs/images/combined_ThS.xml
new file mode 100644
index 000000000..edf1aec9a
--- /dev/null
+++ b/docs/images/combined_ThS.xml
@@ -0,0 +1,240 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<mxfile host="www.draw.io" modified="2019-11-08T20:29:58.723Z" agent="Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:70.0) Gecko/20100101 Firefox/70.0" etag="toJDhaI1IGpgBDMQ1_EO" version="12.2.3" type="device" pages="1">
+  <diagram id="zDYsmKWfsvaye4iWCuEG" name="Page-1">
+    <mxGraphModel dx="1012" dy="779" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="850" pageHeight="1100" math="0" shadow="0">
+      <root>
+        <mxCell id="0"/>
+        <mxCell id="1" parent="0"/>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-1" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;strokeWidth=2;fillColor=#e1d5e7;strokeColor=#9673a6;" vertex="1" parent="1">
+          <mxGeometry x="235" y="400" width="120" height="130" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-2" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shadow=1;endArrow=none;endFill=0;strokeWidth=3;fillColor=#f8cecc;strokeColor=#b85450;" edge="1" parent="1" source="o_WBuMnBS2_K2GNVFPGi-5" target="o_WBuMnBS2_K2GNVFPGi-9">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="265" y="435"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-3" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shadow=1;endArrow=none;endFill=0;strokeWidth=3;fillColor=#f8cecc;strokeColor=#b85450;" edge="1" parent="1" source="o_WBuMnBS2_K2GNVFPGi-5" target="o_WBuMnBS2_K2GNVFPGi-17">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="265" y="505"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-4" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shadow=1;endArrow=none;endFill=0;strokeWidth=3;fillColor=#f8cecc;strokeColor=#b85450;" edge="1" parent="1" source="o_WBuMnBS2_K2GNVFPGi-5" target="o_WBuMnBS2_K2GNVFPGi-13">
+          <mxGeometry relative="1" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-5" value="&lt;b&gt;Mgr&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="245" y="455" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-6" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="170" y="270" width="70" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-7" value="&lt;b&gt;Node 0&lt;br&gt;&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="180" y="270" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-8" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;fillColor=#ffe6cc;strokeColor=#d79b00;strokeWidth=3;endArrow=block;endFill=1;" edge="1" parent="1" source="o_WBuMnBS2_K2GNVFPGi-9" target="o_WBuMnBS2_K2GNVFPGi-6">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="350" y="435"/>
+              <mxPoint x="350" y="380"/>
+              <mxPoint x="205" y="380"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-9" value="&lt;b&gt;Wrk0&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="295" y="420" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-10" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="260" y="270" width="70" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-11" value="&lt;b&gt;Node 1&lt;br&gt;&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="270" y="270" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-12" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;endArrow=block;endFill=1;" edge="1" parent="1" source="o_WBuMnBS2_K2GNVFPGi-13" target="o_WBuMnBS2_K2GNVFPGi-10">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="370" y="470"/>
+              <mxPoint x="370" y="370"/>
+              <mxPoint x="295" y="370"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-13" value="&lt;b&gt;Wrk1&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="295" y="455" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-14" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="350" y="270" width="70" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-15" value="&lt;b&gt;Node 2&lt;br&gt;&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="360" y="270" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-16" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;endArrow=block;endFill=1;" edge="1" parent="1" source="o_WBuMnBS2_K2GNVFPGi-17" target="o_WBuMnBS2_K2GNVFPGi-14">
+          <mxGeometry relative="1" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-17" value="&lt;b&gt;Wrk2&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="295" y="490" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-18" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="190" y="325" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-19" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="280" y="315" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-20" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="370" y="295" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-21" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="370" y="310" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-22" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="370" y="325" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-23" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="280" y="300" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-24" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="190" y="295" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-25" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="190" y="310" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-26" value="&lt;b&gt;MOM Node&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;shadow=1;glass=0;comic=0;" vertex="1" parent="1">
+          <mxGeometry x="255" y="400" width="80" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-27" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;strokeWidth=2;fillColor=#e1d5e7;strokeColor=#9673a6;" vertex="1" parent="1">
+          <mxGeometry x="670" y="400" width="120" height="130" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-28" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="520" y="250" width="110" height="150" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-29" value="&lt;b&gt;Node 0&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="550" y="255" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-30" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shadow=1;endArrow=none;endFill=0;strokeWidth=3;fillColor=#f8cecc;strokeColor=#b85450;" edge="1" parent="1" source="o_WBuMnBS2_K2GNVFPGi-33" target="o_WBuMnBS2_K2GNVFPGi-37">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="550" y="295"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-31" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shadow=1;endArrow=none;endFill=0;strokeWidth=3;fillColor=#f8cecc;strokeColor=#b85450;" edge="1" parent="1" source="o_WBuMnBS2_K2GNVFPGi-33" target="o_WBuMnBS2_K2GNVFPGi-45">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="550" y="365"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-32" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shadow=1;endArrow=none;endFill=0;strokeWidth=3;fillColor=#f8cecc;strokeColor=#b85450;" edge="1" parent="1" source="o_WBuMnBS2_K2GNVFPGi-33" target="o_WBuMnBS2_K2GNVFPGi-41">
+          <mxGeometry relative="1" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-33" value="&lt;b&gt;Mgr&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="530" y="315" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-34" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="660" y="270" width="70" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-35" value="&lt;b&gt;Node 1&lt;br&gt;&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="670" y="270" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-36" style="edgeStyle=orthogonalEdgeStyle;rounded=0;comic=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.25;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.3;entryDx=0;entryDy=0;shadow=0;endArrow=block;endFill=1;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;" edge="1" parent="1" source="o_WBuMnBS2_K2GNVFPGi-37" target="o_WBuMnBS2_K2GNVFPGi-58">
+          <mxGeometry relative="1" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-37" value="&lt;b&gt;Wrk0&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="580" y="280" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-38" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="750" y="270" width="70" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-39" value="&lt;b&gt;Node 2&lt;br&gt;&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="760" y="270" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-40" style="edgeStyle=orthogonalEdgeStyle;rounded=0;comic=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;shadow=0;endArrow=block;endFill=1;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;" edge="1" parent="1" source="o_WBuMnBS2_K2GNVFPGi-41" target="o_WBuMnBS2_K2GNVFPGi-58">
+          <mxGeometry relative="1" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-41" value="&lt;b&gt;Wrk1&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="580" y="315" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-42" value="" style="rounded=1;whiteSpace=wrap;html=1;rotation=0;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;shadow=1;glass=0;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="840" y="270" width="70" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-43" value="&lt;b&gt;Node 3&lt;br&gt;&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;" vertex="1" parent="1">
+          <mxGeometry x="850" y="270" width="50" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-44" style="edgeStyle=orthogonalEdgeStyle;rounded=0;comic=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.75;exitY=1;exitDx=0;exitDy=0;entryX=0;entryY=0.7;entryDx=0;entryDy=0;shadow=0;endArrow=block;endFill=1;strokeWidth=3;fillColor=#ffe6cc;strokeColor=#d79b00;" edge="1" parent="1" source="o_WBuMnBS2_K2GNVFPGi-45" target="o_WBuMnBS2_K2GNVFPGi-58">
+          <mxGeometry relative="1" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-45" value="&lt;b&gt;Wrk2&lt;/b&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;glass=0;comic=0;shadow=1;strokeWidth=2;" vertex="1" parent="1">
+          <mxGeometry x="580" y="350" width="40" height="30" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-46" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="680" y="325" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-47" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="770" y="315" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-48" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="860" y="295" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-49" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="860" y="310" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-50" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="860" y="325" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-51" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="770" y="300" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-52" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="680" y="295" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-53" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="680" y="310" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-54" value="&lt;b&gt;MOM Node&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;shadow=1;glass=0;comic=0;" vertex="1" parent="1">
+          <mxGeometry x="690" y="400" width="80" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-55" style="edgeStyle=orthogonalEdgeStyle;rounded=0;comic=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.3;exitDx=0;exitDy=0;entryX=0.614;entryY=0.988;entryDx=0;entryDy=0;entryPerimeter=0;shadow=0;endArrow=block;endFill=1;strokeWidth=3;fillColor=#d5e8d4;strokeColor=#82b366;" edge="1" parent="1" source="o_WBuMnBS2_K2GNVFPGi-58" target="o_WBuMnBS2_K2GNVFPGi-34">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="770" y="448"/>
+              <mxPoint x="770" y="380"/>
+              <mxPoint x="703" y="380"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-56" style="edgeStyle=orthogonalEdgeStyle;rounded=0;comic=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;shadow=0;endArrow=block;endFill=1;strokeWidth=3;fillColor=#d5e8d4;strokeColor=#82b366;" edge="1" parent="1" source="o_WBuMnBS2_K2GNVFPGi-58" target="o_WBuMnBS2_K2GNVFPGi-38">
+          <mxGeometry relative="1" as="geometry">
+            <Array as="points">
+              <mxPoint x="800" y="464"/>
+              <mxPoint x="800" y="380"/>
+              <mxPoint x="785" y="380"/>
+            </Array>
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-57" style="edgeStyle=orthogonalEdgeStyle;rounded=0;comic=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.7;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;shadow=0;endArrow=block;endFill=1;strokeWidth=3;fillColor=#d5e8d4;strokeColor=#82b366;" edge="1" parent="1" source="o_WBuMnBS2_K2GNVFPGi-58" target="o_WBuMnBS2_K2GNVFPGi-42">
+          <mxGeometry relative="1" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-58" value="" style="shape=cylinder;whiteSpace=wrap;html=1;boundedLbl=1;backgroundOutline=1;shadow=1;glass=0;comic=0;strokeWidth=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1">
+          <mxGeometry x="700" y="430" width="60" height="80" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-59" value="&lt;b&gt;Balsam&lt;/b&gt;" style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=0;shadow=1;glass=0;comic=0;" vertex="1" parent="1">
+          <mxGeometry x="710" y="435" width="40" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-60" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#f8cecc;strokeColor=#b85450;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="715" y="460" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-61" value="" style="rounded=1;whiteSpace=wrap;html=1;shadow=1;glass=0;comic=0;fillColor=#dae8fc;strokeColor=#6c8ebf;strokeWidth=1;perimeterSpacing=0;" vertex="1" parent="1">
+          <mxGeometry x="715" y="477" width="30" height="10" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-62" value="&lt;font style=&quot;font-size: 14px&quot;&gt;&lt;b&gt;libEnsemble on MOM Nodes&lt;/b&gt;&lt;/font&gt;" style="text;html=1;resizable=0;points=[];autosize=1;align=left;verticalAlign=top;spacingTop=-4;" vertex="1" parent="1">
+          <mxGeometry x="205" y="200" width="200" height="20" as="geometry"/>
+        </mxCell>
+        <mxCell id="o_WBuMnBS2_K2GNVFPGi-63" value="&lt;font style=&quot;font-size: 14px&quot;&gt;&lt;b&gt;libEnsemble on Compute Nodes&lt;/b&gt;&lt;/font&gt;" style="text;html=1;resizable=0;points=[];autosize=1;align=left;verticalAlign=top;spacingTop=-4;" vertex="1" parent="1">
+          <mxGeometry x="620" y="200" width="230" height="20" as="geometry"/>
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>
diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index aa0286299..7cadd7dfb 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -13,37 +13,43 @@ Configuring Python
 
 Begin by loading the Python 3 Miniconda_ module::
 
-    $ module load miniconda-3.6/conda-4.5.12
+    $ module load miniconda-3/latest
 
-Create a Conda_ virtual environment in which to install libEnsemble and all
-dependencies::
+Create a Conda virtual environment, cloning the base-environment. This
+environment will contain mpi4py_ and many other packages you may find useful::
 
-    $ conda config --add channels intel
-    $ conda create --name my_env intelpython3_core python=3
-    $ source activate my_env
+    $ conda create --name my_env --clone $MINICONDA_INSTALL_PATH
+
+.. note::
+    The "Executing transaction" step of creating your new environment may take a while!
+
+Following a successful environment-creation, the prompt will suggest activating
+your new environment immediately. A Conda error may result; follow the on-screen
+instructions to configure your shell with Conda.
+
+Activate your virtual environment with::
+
+    $ conda activate my_env
 
 More information_ on using Conda on Theta.
 
-Installing libEnsemble and Dependencies
----------------------------------------
+Installing libEnsemble and Balsam
+---------------------------------
 
-libEnsemble and mpi4py
-^^^^^^^^^^^^^^^^^^^^^^
+libEnsemble
+^^^^^^^^^^^
 
-There should be an indication that the virtual environment is activated.
-Install mpi4py_ and libEnsemble in this environment, making sure to reference
-the pre-installed Intel C Compiler (which should support MPI). Your prompt may
-be similar to the following block:
+There should be an indication that your virtual environment is activated.
+Obtaining libEnsemble is now as simple as ``pip install libensemble``.
+Your prompt should be similar to the following line:
 
 .. code-block:: console
 
-    (my_env) user@thetalogin6:~$ CC=mpiicc MPICC=mpiicc pip install mpi4py --no-binary mpi4py
     (my_env) user@thetalogin6:~$ pip install libensemble
 
 .. note::
     If you encounter pip errors, run ``python -m pip install --upgrade pip`` first
 
-
 Balsam (Optional)
 ^^^^^^^^^^^^^^^^^
 
@@ -52,19 +58,12 @@ computations on systems like Theta. Balsam can stage in tasks to a database host
 on a MOM node and submit these tasks dynamically to the compute nodes. libEnsemble
 can also be submitted to Balsam for centralized execution on a compute-node. At
 this point, libEnsemble can then submit tasks to Balsam through libEnsemble's
-Balsam job-controller for execution on additional allocated nodes:
-
-.. image:: ../images/centralized_Balsam_ThS.png
-    :alt: central_Balsam
-    :scale: 75
-    :align: center
-
+Balsam job-controller for execution on additional allocated nodes.
 
 Load the Balsam module with::
 
     $ module load balsam/0.3.5.1
 
-
 Initialize a new database similarly to the following (from the Balsam docs):
 
 .. code-block:: bash
@@ -76,8 +75,7 @@ Initialize a new database similarly to the following (from the Balsam docs):
     $ balsam submit-launch -A [project] -q default -t 5 -n 1 --job-mode=mpi
     $ watch balsam ls   #  follow status in realtime from command-line
 
-
-See **Additional Information** for Balsam's documentation.
+See Additional_ for Balsam's documentation.
 
 Job Submission
 --------------
@@ -86,16 +84,26 @@ Theta uses Cobalt_ for job management and submission. For libEnsemble, the most
 important command is ``qsub``, for submitting batch scripts from the login nodes
 to execute on the MOM nodes.
 
-On Theta, libEnsemble's communications are commonly configured to run in one of two ways:
+On Theta, libEnsemble itself can be launched to two locations:
+
+    1. **A MOM Node**: All of libEnsemble's manager and worker processes
+    run on a front-end MOM node. libEnsemble's MPI job-controller takes
+    responsibility for direct submissions of jobs to all allocated compute nodes.
+    libEnsemble must be configured to run with *multiprocessing* communications:
 
-    1. **Multiprocessing mode**, where libEnsemble's MPI job-controller takes
-    responsibility for direct submissions of jobs to compute nodes. In this mode,
-    libEnsemble itself, including all manager and worker processes, runs on the
-    MOM nodes.
+    2. **The Compute Nodes**: libEnsemble is submitted to Balsam and tasked to a
+    compute node. libEnsemble's Balsam job-controller interfaces with the Balsam
+    backend for dynamic task submission to the compute nodes.
 
-    2. **MPI mode**, with libEnsemble's Balsam job-controller interfacing with the
-    previously-mentioned Balsam backend for dynamic task submission. In this mode
-    libEnsemble has been submitted to Balsam and tasked to a compute-node.
+    .. image:: ../images/combined_ThS.png
+        :alt: central_MOM
+        :scale: 40
+        :align: center
+
+
+When considering on which nodes to run libEnsemble, consider if your worker functions
+will execute computationally expensive code, or code built for a specific
+architectures or nodes. Recall also that only the MOM nodes can launch MPI jobs.
 
 Theta features one default production queue, ``default``, and two debug queues,
 ``debug-cache-quad`` and ``debug-flat-quad``.
@@ -111,8 +119,8 @@ to the following::
 
     $ qsub -A [project] -n 128 -q default -t 120 -I
 
-This will place the user on a MOM node. If running in multiprocessing mode, launching
-jobs to the compute nodes is as simple as ``python calling_script.py``
+This will place the user on a MOM node. To launch MPI jobs to the compute nodes from
+the MOM nodes use ``aprun`` where you would use ``mpirun``.
 
 .. note::
     You will need to re-activate your conda virtual environment, re-activate your
@@ -170,8 +178,7 @@ on Theta becomes::
 Balsam Runs
 ^^^^^^^^^^^
 
-Balsam runs are Batch runs, except Balsam is responsible for submitting libEnsemble
-for execution. This is an example Balsam submission script:
+Here is an example Balsam submission script:
 
 .. code-block:: bash
 
@@ -244,7 +251,7 @@ for execution. This is an example Balsam submission script:
 
     . balsamdeactivate
 
-See **Additional Information** for the Balsam docs.
+See Additional_ for the Balsam docs.
 
 Debugging Strategies
 --------------------
@@ -257,6 +264,8 @@ queue interactively::
 
     $ qsub -A [project] -n 4 -q debug-flat-quad -t 60 -I
 
+.. _Additional:
+
 Additional Information
 ----------------------
 

From a897fb673d5d8e29e53e754fbc12434e11b33e46 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 8 Nov 2019 14:43:59 -0600
Subject: [PATCH 467/644] adjust references and headers

---
 docs/platforms/theta.rst | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index 7cadd7dfb..244eade6a 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -15,7 +15,7 @@ Begin by loading the Python 3 Miniconda_ module::
 
     $ module load miniconda-3/latest
 
-Create a Conda virtual environment, cloning the base-environment. This
+Create a Conda_ virtual environment, cloning the base-environment. This
 environment will contain mpi4py_ and many other packages you may find useful::
 
     $ conda create --name my_env --clone $MINICONDA_INSTALL_PATH
@@ -75,7 +75,7 @@ Initialize a new database similarly to the following (from the Balsam docs):
     $ balsam submit-launch -A [project] -q default -t 5 -n 1 --job-mode=mpi
     $ watch balsam ls   #  follow status in realtime from command-line
 
-See Additional_ for Balsam's documentation.
+Read Balsam's documentation here_.
 
 Job Submission
 --------------
@@ -251,8 +251,6 @@ Here is an example Balsam submission script:
 
     . balsamdeactivate
 
-See Additional_ for the Balsam docs.
-
 Debugging Strategies
 --------------------
 
@@ -264,8 +262,6 @@ queue interactively::
 
     $ qsub -A [project] -n 4 -q debug-flat-quad -t 60 -I
 
-.. _Additional:
-
 Additional Information
 ----------------------
 

From 5a1405a342059bedb8571ab956701ba79e7cae50 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 8 Nov 2019 15:18:25 -0600
Subject: [PATCH 468/644] more clarification and description, typos fixed

---
 docs/platforms/theta.rst | 71 ++++++++++++++++++++++------------------
 1 file changed, 40 insertions(+), 31 deletions(-)

diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index 244eade6a..95da5a6fd 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -2,11 +2,12 @@
 Theta
 =====
 
-Theta_ is a 11.69 petaflops Cray XC40 system based on the second-generation Intel
+Theta_ is a Cray XC40 system based on the second-generation Intel
 Xeon Phi processor, available within ALCF_ at Argonne National Laboratory.
 
 Theta features three tiers of nodes: login, MOM (Machine-Oriented Mini-server),
-and compute nodes. MOM nodes execute user batch-scripts to run on the compute nodes.
+and compute nodes. Users on login nodes submit batch runs to the MOM nodes.
+MOM nodes execute user batch-scripts to run on the compute nodes.
 
 Configuring Python
 ------------------
@@ -56,9 +57,9 @@ Balsam (Optional)
 Balsam_ is an ALCF Python utility for coordinating and executing workflows of
 computations on systems like Theta. Balsam can stage in tasks to a database hosted
 on a MOM node and submit these tasks dynamically to the compute nodes. libEnsemble
-can also be submitted to Balsam for centralized execution on a compute-node. At
-this point, libEnsemble can then submit tasks to Balsam through libEnsemble's
-Balsam job-controller for execution on additional allocated nodes.
+can also be submitted to Balsam for centralized execution on a compute-node.
+libEnsemble can then submit tasks to Balsam through libEnsemble's Balsam
+job-controller for execution on additional allocated nodes.
 
 Load the Balsam module with::
 
@@ -84,26 +85,27 @@ Theta uses Cobalt_ for job management and submission. For libEnsemble, the most
 important command is ``qsub``, for submitting batch scripts from the login nodes
 to execute on the MOM nodes.
 
-On Theta, libEnsemble itself can be launched to two locations:
+On Theta, libEnsemble can be launched to two locations:
 
     1. **A MOM Node**: All of libEnsemble's manager and worker processes
     run on a front-end MOM node. libEnsemble's MPI job-controller takes
-    responsibility for direct submissions of jobs to all allocated compute nodes.
-    libEnsemble must be configured to run with *multiprocessing* communications:
+    responsibility for direct job-submission to allocated compute nodes.
+    libEnsemble must be configured to run with *multiprocessing* communications,
+    since mpi4py isn't configured for use on the MOM nodes.
 
-    2. **The Compute Nodes**: libEnsemble is submitted to Balsam and tasked to a
-    compute node. libEnsemble's Balsam job-controller interfaces with the Balsam
-    backend for dynamic task submission to the compute nodes.
+    2. **The Compute Nodes**: libEnsemble is submitted to Balsam and all manager
+    and worker processes are tasked to a backend compute node. libEnsemble's
+    Balsam job-controller interfaces with Balsam running on a MOM node for dynamic
+    task submission to the compute nodes.
 
     .. image:: ../images/combined_ThS.png
         :alt: central_MOM
         :scale: 40
         :align: center
 
-
-When considering on which nodes to run libEnsemble, consider if your worker functions
-will execute computationally expensive code, or code built for a specific
-architectures or nodes. Recall also that only the MOM nodes can launch MPI jobs.
+When considering on which nodes to run libEnsemble, consider if your user
+functions execute computationally expensive code, or code built for specific
+architectures. Recall also that only the MOM nodes can launch MPI jobs.
 
 Theta features one default production queue, ``default``, and two debug queues,
 ``debug-cache-quad`` and ``debug-flat-quad``.
@@ -119,19 +121,21 @@ to the following::
 
     $ qsub -A [project] -n 128 -q default -t 120 -I
 
-This will place the user on a MOM node. To launch MPI jobs to the compute nodes from
-the MOM nodes use ``aprun`` where you would use ``mpirun``.
+This will place the user on a MOM node. Then, to launch MPI jobs to the compute
+nodes use ``aprun`` where you would use ``mpirun``.
 
 .. note::
     You will need to re-activate your conda virtual environment, re-activate your
-    Balsam database (if using Balsam), and reload your modules! Configuring this
+    Balsam database (if using Balsam), and reload your modules. Configuring this
     routine to occur automatically is recommended.
 
 Batch Runs
 ^^^^^^^^^^
 
-Batch scripts specify run-settings using ``#COBALT`` statements. A simple example
-for a libEnsemble use-case may resemble the following:
+Batch scripts specify run-settings using ``#COBALT`` statements. The following
+simple example depicts configuring and launching libEnsemble to a MOM node with
+multiprocessing. This script also assumes the user is using the ``parse_args()``
+convenience function within libEnsemble's ``/regression_tests/common.py``.
 
 .. code-block:: bash
 
@@ -142,7 +146,19 @@ for a libEnsemble use-case may resemble the following:
     #COBALT -A [project]
     #COBALT -O libE-project
 
-    module load miniconda-3.6/conda-4.5.12
+    # --- Prepare Python ---
+
+    # Load conda module
+    module load miniconda-3/latest
+
+    # Name of Conda environment
+    export CONDA_ENV_NAME=my_env
+
+    # Activate Conda environment
+    export PYTHONNOUSERSITE=1
+    source activate $CONDA_ENV_NAME
+
+    # --- Prepare libEnsemble ---
 
     # Name of calling script
     export EXE=calling_script.py
@@ -153,13 +169,6 @@ for a libEnsemble use-case may resemble the following:
     # Number of workers.
     export NWORKERS='--nworkers 128'
 
-    # Name of Conda environment
-    export CONDA_ENV_NAME=my_env
-
-    # Activate Conda environment
-    export PYTHONNOUSERSITE=1
-    source activate $CONDA_ENV_NAME
-
     # Conda location - theta specific
     export PATH=/home/user/path/to/packages/:$PATH
     export LD_LIBRARY_PATH=/home/user/path/to/packages/:$LD_LIBRARY_PATH
@@ -170,8 +179,8 @@ for a libEnsemble use-case may resemble the following:
 
     python $EXE $COMMS $NWORKERS > out.txt 2>&1
 
-With this saved as ``myscript.sh``, allocating, configuring, and running libEnsemble
-on Theta becomes::
+With this saved as ``myscript.sh``, allocating, configuring, and queueing
+libEnsemble on Theta becomes::
 
     $ qsub --mode script myscript.sh
 
@@ -256,7 +265,7 @@ Debugging Strategies
 
 View the status of your submitted jobs with ``qstat -fu [user]``.
 
-Theta features two debug queues with sixteen nodes apiece. Each user can allocate
+Theta features two debug queues each with sixteen nodes. Each user can allocate
 up to eight nodes at once for a maximum of one hour. Allocate nodes on a debug
 queue interactively::
 

From 287800cffbd491646bc3a8e27961423a62314925 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 8 Nov 2019 15:46:02 -0600
Subject: [PATCH 469/644] update tutorial examples for 'user'

---
 examples/tutorials/tutorial_calling.py     | 8 +++++---
 examples/tutorials/tutorial_calling_mpi.py | 8 +++++---
 examples/tutorials/tutorial_gen.py         | 9 ++++++---
 3 files changed, 16 insertions(+), 9 deletions(-)

diff --git a/examples/tutorials/tutorial_calling.py b/examples/tutorials/tutorial_calling.py
index 8db2e8609..38d87866f 100644
--- a/examples/tutorials/tutorial_calling.py
+++ b/examples/tutorials/tutorial_calling.py
@@ -9,9 +9,11 @@
 
 gen_specs = {'gen_f': gen_random_sample,        # Our generator function
              'out': [('x', float, (1,))],       # gen_f output (name, type, size).
-             'lower': np.array([-3]),           # lower boundary for random sampling.
-             'upper': np.array([3]),            # upper boundary for random sampling.
-             'gen_batch_size': 5}               # number of values gen_f will generate per call
+             'user': { 'lower': np.array([-3]), # random sampling lower bound
+                       'upper': np.array([3]),  # random sampling upper bound
+                       'gen_batch_size': 5      # number of values gen_f will generate per call
+                     }
+             }
 
 sim_specs = {'sim_f': sim_find_sine,            # Our simulator function
              'in': ['x'],                       # Input field names. 'x' from gen_f output
diff --git a/examples/tutorials/tutorial_calling_mpi.py b/examples/tutorials/tutorial_calling_mpi.py
index 2ba751353..99d5e628a 100644
--- a/examples/tutorials/tutorial_calling_mpi.py
+++ b/examples/tutorials/tutorial_calling_mpi.py
@@ -13,9 +13,11 @@
 
 gen_specs = {'gen_f': gen_random_sample,        # Our generator function
              'out': [('x', float, (1,))],       # gen_f output (name, type, size).
-             'lower': np.array([-3]),           # lower boundary for random sampling.
-             'upper': np.array([3]),            # upper boundary for random sampling.
-             'gen_batch_size': 5}               # number of values gen_f will generate per call
+             'user': { 'lower': np.array([-3]), # random sampling lower bound
+                       'upper': np.array([3]),  # random sampling upper bound
+                       'gen_batch_size': 5      # number of values gen_f will generate per call
+                     }
+             }
 
 sim_specs = {'sim_f': sim_find_sine,            # Our simulator function
              'in': ['x'],                       # Input field names. 'x' from gen_f output
diff --git a/examples/tutorials/tutorial_gen.py b/examples/tutorials/tutorial_gen.py
index 5a109059d..85bfedf12 100644
--- a/examples/tutorials/tutorial_gen.py
+++ b/examples/tutorials/tutorial_gen.py
@@ -4,13 +4,16 @@
 def gen_random_sample(H, persis_info, gen_specs, _):
     # underscore parameter for internal/testing arguments
 
+    # Pull out user parameters to perform calculations
+    user_specs = gen_specs['user']
+
     # Get lower and upper bounds from gen_specs
-    lower = gen_specs['lower']
-    upper = gen_specs['upper']
+    lower = user_specs['lower']
+    upper = user_specs['upper']
 
     # Determine how many values to generate
     num = len(lower)
-    batch_size = gen_specs['gen_batch_size']
+    batch_size = user_specs['gen_batch_size']
 
     # Create array of 'batch_size' zeros
     out = np.zeros(batch_size, dtype=gen_specs['out'])

From 679b974f0afc46a9aa3ae82e8b3f8697c4c62654 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 8 Nov 2019 16:02:52 -0600
Subject: [PATCH 470/644] README/Intro edits

---
 README.rst | 70 +++++++++++++++++++++++++-----------------------------
 1 file changed, 33 insertions(+), 37 deletions(-)

diff --git a/README.rst b/README.rst
index dc00bbfcd..a0dec080f 100644
--- a/README.rst
+++ b/README.rst
@@ -124,13 +124,14 @@ Resources
 
 **Support:**
 
-- Email questions to libensemble@lists.mcs.anl.gov
-- Communicate (and establish a private channel, if desired) at https://libensemble.slack.com
-- Join the libEnsemble mailing list for updates about new releases at https://lists.mcs.anl.gov/mailman/listinfo/libensemble
+- The best way to receive support is to email questions to ``libEnsemble@lists.mcs.anl.gov``.
+- Communicate (and establish a private channel, if desired) at the `libEnsemble Slack page`_.
+- Join the `libEnsemble mailing list`_ for updates about new releases.
 
-**Documentation:**
+**Further Information:**
 
-- Provided by ReadtheDocs at http://libensemble.readthedocs.org/
+- Documentation is provided by ReadtheDocs_.
+- A visual overview of libEnsemble is given in this poster_.
 
 **Citation:**
 
@@ -148,9 +149,6 @@ Resources
     url         = {https://buildmedia.readthedocs.org/media/pdf/libensemble/latest/libensemble.pdf}
   }
 
-**Other:**
-
-- A visual overview of libEnsemble is given in this poster_.
 
 Quickstart Guide
 ----------------
@@ -161,14 +159,11 @@ Dependencies
 Required dependencies:
 
 * Python_ 3.5 or above.
-
 * NumPy_
 
 For libEnsemble running with the mpi4py parallelism:
 
-* A functional MPI 1.x/2.x/3.x implementation such as `MPICH
-  <http://www.mpich.org/>`_  built with shared/dynamic libraries.
-
+* A functional MPI 1.x/2.x/3.x implementation, such as MPICH_, built with shared/dynamic libraries.
 * mpi4py_ v2.0.0 or above
 
 Optional dependency:
@@ -186,11 +181,11 @@ The example sim and gen functions and tests require the following dependencies:
 * SciPy_
 * petsc4py_
 * PETSc_ - This can optionally be installed by pip along with petsc4py
-* NLopt_ - Installed with `shared libraries enabled <http://ab-initio.mit.edu/wiki/index.php/NLopt_Installation#Shared_libraries>`_.
+* NLopt_ - Installed with `shared libraries enabled`_.
 
 PETSc and NLopt must be built with shared libraries enabled and present in
 ``sys.path`` (e.g., via setting the ``PYTHONPATH`` environment variable). NLopt
-should produce a file nlopt.py if Python is found on the system. NLopt may also
+should produce a file ``nlopt.py`` if Python is found on the system. NLopt may also
 require SWIG_ to be installed on certain systems.
 
 Installation
@@ -204,14 +199,12 @@ libEnsemble is also available in the Spack_ distribution. It can be installed fr
 
     spack install py-libensemble
 
-.. _Spack: https://spack.readthedocs.io/en/latest
-
-The tests and examples can be accessed in the `GitHub <https://github.com/Libensemble/libensemble>`_ repository.
+The tests and examples can be accessed in the GitHub_ repository.
 If necessary, you may install all optional dependencies (listed above) at once with::
 
     pip install libensemble[extras]
 
-A `tarball <https://github.com/Libensemble/libensemble/releases/latest>`_ of the most recent release is also available.
+A tarball_ of the most recent release is also available.
 
 Testing
 ~~~~~~~
@@ -219,7 +212,7 @@ Testing
 The provided test suite includes both unit and regression tests and is run
 regularly on:
 
-* `Travis CI <https://travis-ci.org/Libensemble/libensemble>`_
+* `Travis CI`_
 
 The test suite requires the mock_, pytest_, pytest-cov_, and pytest-timeout_
 packages to be installed and can be run from the libensemble/tests directory of
@@ -245,16 +238,9 @@ in the top-level directory containing the setup script.
 Coverage reports are produced separately for unit tests and regression tests
 under the relevant directories. For parallel tests, the union of all processors
 is taken. Furthermore, a combined coverage report is created at the top level,
-which can be viewed after running the tests via the HTML file
+which can be viewed after ``run_tests.sh`` is completed at 
 ``libensemble/tests/cov_merge/index.html``. The Travis CI coverage results are
-available online at
-`Coveralls <https://coveralls.io/github/Libensemble/libensemble?branch=master>`_.
-
-.. note::
-    The job_controller tests can be run using the direct-launch or
-    Balsam job controllers. Although only the direct-launch versions can be run
-    on Travis CI, Balsam integration with libEnsemble is now tested via
-    ``test_balsam_hworld.py``.
+available online at Coveralls_.
 
 Basic Usage
 ~~~~~~~~~~~
@@ -278,23 +264,33 @@ can then be run as a regular python script::
 
 When specifying these options via command line options, one may use the
 ``parse_args`` function used in the regression tests, which can be found in
-``libensemble/tests/regression_tests/common.py``
+`common.py`_ in the ``libensemble/tests/regression_tests`` directory.
 
-See the
-`user-guide <https://libensemble.readthedocs.io/en/latest/user_guide.html>`_
-for more information.
+See the `user guide`_ for more information.
 
 .. _Balsam: https://www.alcf.anl.gov/balsam
-.. _NumPy: http://www.numpy.org
-.. _PETSc: http://www.mcs.anl.gov/petsc
-.. _Python: http://www.python.org
-.. _SWIG: http://swig.org/
-.. _SciPy: http://www.scipy.org
+.. _common.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/common.py
+.. _Coveralls: https://coveralls.io/github/Libensemble/libensemble?branch=master
+.. _GitHub: https://github.com/Libensemble/libensemble
+.. _libEnsemble mailing list: https://lists.mcs.anl.gov/mailman/listinfo/libensemble
+.. _libEnsemble Slack page: https://libensemble.slack.com
 .. _mock: https://pypi.org/project/mock
 .. _mpi4py: https://bitbucket.org/mpi4py/mpi4py
+.. _MPICH: http://www.mpich.org/
 .. _nlopt: http://ab-initio.mit.edu/wiki/index.php/NLopt
+.. _NumPy: http://www.numpy.org
 .. _petsc4py: https://bitbucket.org/petsc/petsc4py
+.. _PETSc: http://www.mcs.anl.gov/petsc
 .. _poster: https://figshare.com/articles/LibEnsemble_PETSc_TAO-_Sustaining_a_library_for_dynamic_ensemble-based_computations/7765454
 .. _pytest-cov: https://pypi.org/project/pytest-cov/
 .. _pytest-timeout: https://pypi.org/project/pytest-timeout/
 .. _pytest: https://pypi.org/project/pytest/
+.. _Python: http://www.python.org
+.. _ReadtheDocs: http://libensemble.readthedocs.org/
+.. _SciPy: http://www.scipy.org
+.. _shared libraries enabled: http://ab-initio.mit.edu/wiki/index.php/NLopt_Installation#Shared_libraries
+.. _Spack: https://spack.readthedocs.io/en/latest
+.. _SWIG: http://swig.org/
+.. _tarball: https://github.com/Libensemble/libensemble/releases/latest
+.. _Travis CI: https://travis-ci.org/Libensemble/libensemble
+.. _user guide: https://libensemble.readthedocs.io/en/latest/user_guide.html

From 8de449d63f4a77297a168e2fd7f3c71a27651bbb Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 8 Nov 2019 16:16:58 -0600
Subject: [PATCH 471/644] Section 2 doc edits

---
 docs/FAQ.rst              |  2 +-
 docs/bibliography.rst     |  2 +-
 docs/programming_libE.rst |  6 +++---
 libensemble/libE.py       | 14 +++++++-------
 4 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/docs/FAQ.rst b/docs/FAQ.rst
index 5512df3f9..135b41e45 100644
--- a/docs/FAQ.rst
+++ b/docs/FAQ.rst
@@ -103,7 +103,7 @@ does libEnsemble hang on certain systems when running with MPI?"
 
 For more information see: https://bitbucket.org/mpi4py/mpi4py/issues/102/unpicklingerror-on-commrecv-after-iprobe
 
-libEnsemble Help 
+libEnsemble Help
 ----------------
 
 **How can I debug specific libEnsemble processes?**
diff --git a/docs/bibliography.rst b/docs/bibliography.rst
index 8c87684c0..33e326359 100644
--- a/docs/bibliography.rst
+++ b/docs/bibliography.rst
@@ -2,4 +2,4 @@ Bibliography
 ------------
 .. Note that you can't reference a bib file in a different directory
 
-.. bibliography:: references.bib 
+.. bibliography:: references.bib
diff --git a/docs/programming_libE.rst b/docs/programming_libE.rst
index ad8be08f9..012eea031 100644
--- a/docs/programming_libE.rst
+++ b/docs/programming_libE.rst
@@ -15,15 +15,15 @@ dumped to the respective files,
 * ``libE_history_at_abort_<sim_count>.npy``
 * ``libE_history_at_abort_<sim_count>.pickle``
 
-where ``sim_count`` is the number of points evaluated.
+where ``<sim_count>`` is the number of points evaluated.
 
 Other libEnsemble files produced by default are:
 
-* ``libE_stats.txt``: This contains a one-line summary of all user
+* ``libE_stats.txt``: Contains a one-line summary of all user
   calculations.  Each calculation summary is sent by workers to the manager and
   printed as the run progresses.
 
-* ``ensemble.log``: This is the logging output from libEnsemble. The default
+* ``ensemble.log``: The logging output from libEnsemble. The default
   logging is at INFO level. To gain additional diagnostics logging level can be
   set to DEBUG.  If this file is not removed, multiple runs will append output.
   Messages at or above level MANAGER_WARNING are also copied to stderr to alert
diff --git a/libensemble/libE.py b/libensemble/libE.py
index 83c55783c..a4468e1b3 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -1,10 +1,10 @@
 """
 This is the outer libEnsemble routine.
 
-We dispatch to different types of worker teams depending on
-the contents of libE_specs.  If 'comm' is a field, we use MPI;
-if 'nthreads' is a field, we use threads; if 'nprocesses' is a
-field, we use multiprocessing.
+We dispatch to different types of worker teams depending on the contents of
+``libE_specs``.  If ``'comm'`` is a field, MPI is used; if ``'nthreads'`` is a
+field, threads are used ; if ``'nprocesses'`` is a field, multiprocessing is
+used.
 
 If an exception is encountered by the manager or workers, the
 history array is dumped to file and MPI abort is called.
@@ -76,7 +76,7 @@ def libE(sim_specs, gen_specs, exit_criteria,
         Specifications for libEnsemble
         :doc:`(example)<data_structures/libE_specs>`
 
-    H0: :obj:`numpy structured array`, optional
+    H0: `NumPy structured array <https://docs.scipy.org/doc/numpy/user/basics.rec.html>`_, optional
 
         A previous libEnsemble history to be prepended to the history in the
         current libEnsemble run
@@ -85,7 +85,7 @@ def libE(sim_specs, gen_specs, exit_criteria,
     Returns
     -------
 
-    H: :obj:`numpy structured array`
+    H: `NumPy structured array <https://docs.scipy.org/doc/numpy/user/basics.rec.html>`_
 
         History array storing rows for each point.
         :doc:`(example)<data_structures/history_array>`
@@ -97,7 +97,7 @@ def libE(sim_specs, gen_specs, exit_criteria,
 
     exit_flag: :obj:`int`
 
-        Flag containing final job status:
+        Flag containing final job status::
 
         0 = No errors
         1 = Exception occured

From 60804b1f89e87c634c529d8aa3cd74939ab0c60b Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 8 Nov 2019 16:41:20 -0600
Subject: [PATCH 472/644] Further data structure edits

---
 docs/data_structures/data_structures.rst | 19 +++++++++++++++++-
 docs/data_structures/exit_criteria.rst   |  3 ++-
 docs/data_structures/gen_specs.rst       |  5 +++--
 docs/data_structures/history_array.rst   |  4 ++--
 docs/data_structures/sim_specs.rst       | 25 ++++++++++++------------
 5 files changed, 38 insertions(+), 18 deletions(-)

diff --git a/docs/data_structures/data_structures.rst b/docs/data_structures/data_structures.rst
index dbbbc81ac..f86c9042c 100644
--- a/docs/data_structures/data_structures.rst
+++ b/docs/data_structures/data_structures.rst
@@ -1,7 +1,24 @@
 Data Structures
 ===============
 
-This section outlines the data structures used by libEnsemble.
+This section outlines the data structures used by libEnsemble. We first discuss
+the dictionaries that are input to libEnsemble to declare the
+:ref:`simulation<datastruct-sim-specs>`,
+:ref:`generation<datastruct-gen-specs>`,
+and
+:ref:`allocation<datastruct-alloc-specs>`
+specifications, as well as specify
+:ref:`exit criteria<datastruct-exit-criteria>`,
+:ref:`persistent information<datastruct-persis-info>`, and other
+:ref:`libEnsemble<datastruct-libe-specs>`
+options.
+
+We then discuss internal libEnsemble, including the
+:ref:`history array<datastruct-history-array>`,
+:ref:`worker array<datastruct-history-array>`,
+and the
+:ref:`work<datastruct-history-array>` dictionary produced by the allocation
+function.
 
 .. note::
   Users can check the formatting and consistency of ``exit_criteria`` and each ``specs``
diff --git a/docs/data_structures/exit_criteria.rst b/docs/data_structures/exit_criteria.rst
index 6e4cc0b9c..a4a762ac4 100644
--- a/docs/data_structures/exit_criteria.rst
+++ b/docs/data_structures/exit_criteria.rst
@@ -1,6 +1,7 @@
+.. _datastruct-exit-criteria:
+
 exit_criteria
 =============
-.. _datastruct-exit-criteria:
 
 Exit criteria for libEnsemble::
 
diff --git a/docs/data_structures/gen_specs.rst b/docs/data_structures/gen_specs.rst
index c3250e3ae..bad2c34f6 100644
--- a/docs/data_structures/gen_specs.rst
+++ b/docs/data_structures/gen_specs.rst
@@ -1,6 +1,7 @@
+.. _datastruct-gen-specs:
+
 gen_specs
 =========
-.. _datastruct-gen-specs:
 
 Generation function specifications to be set in user calling script and passed
 to main ``libE()`` routine::
@@ -30,7 +31,7 @@ to main ``libE()`` routine::
 
   .. _gen-specs-exmple1:
 
-  From `test_6-hump_camel_uniform_sampling.py`_
+  From test_6-hump_camel_uniform_sampling.py_
 
   ..  literalinclude:: ../../libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
       :start-at: gen_specs
diff --git a/docs/data_structures/history_array.rst b/docs/data_structures/history_array.rst
index 9f2271f66..371362968 100644
--- a/docs/data_structures/history_array.rst
+++ b/docs/data_structures/history_array.rst
@@ -1,7 +1,7 @@
-history array
-=============
 .. _datastruct-history-array:
 
+history array
+=============
 ::
 
     H: numpy structured array
diff --git a/docs/data_structures/sim_specs.rst b/docs/data_structures/sim_specs.rst
index ae7a81885..e3e353b8a 100644
--- a/docs/data_structures/sim_specs.rst
+++ b/docs/data_structures/sim_specs.rst
@@ -1,10 +1,7 @@
-We first describe the dictionaries given to libEnsemble to specify the
-inputs/outputs of the ensemble of calculations to be performed.
+.. _datastruct-sim-specs:
 
 sim_specs
 =========
-.. _datastruct-sim-specs:
-
 Used to specify the simulation function, its inputs and outputs, and user data::
 
     sim_specs: [dict]:
@@ -34,21 +31,25 @@ Used to specify the simulation function, its inputs and outputs, and user data::
 
   .. _sim-specs-exmple1:
 
-  From: ``libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py``
+  - test_6-hump_camel_uniform_sampling.py_ has a ``sim_specs``  that declares
+    the name of the ``'in'`` field variable, ``'x'`` (as specified by the
+    corresponding generator ``'out'`` field ``'x'`` from the :ref:`gen_specs
+    example<gen-specs-exmple1>`).  Only the field name is required in
+    ``sim_specs['in']``.
 
   ..  literalinclude:: ../../libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
       :start-at: sim_specs
       :end-before: end_sim_specs_rst_tag
 
-  The dimensions and type of the ``'in'`` field variable ``'x'`` is specified by the corresponding
-  generator ``'out'`` field ``'x'`` (see :ref:`gen_specs example<gen-specs-exmple1>`).
-  Only the variable name is then required in ``sim_specs['in']``.
-
-  From: ``libensemble/tests/scaling_tests/forces/run_libe_forces.py``
+  - run_libe_forces.py_ has a longer ``sim_specs`` declaration with a number of
+    user-specific fields. These are given to the corresponding sim_f, which
+    can be found at forces_simf.py_
 
   ..  literalinclude:: ../../libensemble/tests/scaling_tests/forces/run_libe_forces.py
       :start-at: sim_f
       :end-before: end_sim_specs_rst_tag
 
-  This example uses a number of user specific fields, that will be dealt with in the corresponding sim f, which
-  can be found at ``libensemble/tests/scaling_tests/forces/forces_simf.py``
+
+.. _forces_simf.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/scaling_tests/forces/forces_simf.py
+.. _run_libe_forces.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/scaling_tests/forces/run_libe_forces.py
+.. _test_6-hump_camel_uniform_sampling.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py

From fa5e29eb00393580093ab266b700decaf9e0ad6b Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 8 Nov 2019 16:55:35 -0600
Subject: [PATCH 473/644] A pass through data structures

---
 docs/data_structures/alloc_specs.rst                 |  6 ++++--
 docs/data_structures/gen_specs.rst                   | 11 +++++------
 docs/data_structures/persis_info.rst                 |  4 +++-
 docs/sim_gen_alloc_funcs.rst                         |  5 +++++
 docs/user_funcs.rst                                  |  5 -----
 .../test_6-hump_camel_uniform_sampling.py            | 12 ++++++------
 ...hwirut_uniform_sampling_one_residual_at_a_time.py |  4 ++--
 7 files changed, 25 insertions(+), 22 deletions(-)

diff --git a/docs/data_structures/alloc_specs.rst b/docs/data_structures/alloc_specs.rst
index 61cfd54eb..8e6222fb8 100644
--- a/docs/data_structures/alloc_specs.rst
+++ b/docs/data_structures/alloc_specs.rst
@@ -23,11 +23,13 @@ to main ``libE()`` routine::
   * The tuples defined in the 'out' list are entered into the master :ref:`history array<datastruct-history-array>`
 
 .. seealso::
-  The script `test_chwirut_uniform_sampling_one_residual_at_a_time.py`_
-  specifies fields to be used by the allocation function.
+  - `test_chwirut_uniform_sampling_one_residual_at_a_time.py`_ specifies fields
+    to be used by the allocation function ``give_sim_work_first`` from
+    fast_alloc_and_pausing.py_.
 
   ..  literalinclude:: ../../libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
       :start-at: alloc_specs
       :end-before: end_alloc_specs_rst_tag
 
 .. _test_chwirut_uniform_sampling_one_residual_at_a_time.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
+.. _fast_alloc_and_pausing.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/fast_alloc_and_pausing.py
diff --git a/docs/data_structures/gen_specs.rst b/docs/data_structures/gen_specs.rst
index bad2c34f6..566cb5040 100644
--- a/docs/data_structures/gen_specs.rst
+++ b/docs/data_structures/gen_specs.rst
@@ -31,15 +31,14 @@ to main ``libE()`` routine::
 
   .. _gen-specs-exmple1:
 
-  From test_6-hump_camel_uniform_sampling.py_
+  - test_6-hump_camel_uniform_sampling.py_ declares In this example, the
+    generation function ``uniform_random_sample`` in sampling.py_ will generate 500 random
+    points uniformly over the 2D domain defined by ``gen_specs['ub']`` and
+    ``gen_specs['lb']``.  
 
   ..  literalinclude:: ../../libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
       :start-at: gen_specs
       :end-before: end_gen_specs_rst_tag
 
-  In this example, the generation function ``uniform_random_sample`` will generate 500 random points
-  uniformly over the 2D domain defined by ``gen_specs['ub']`` and ``gen_specs['lb']``.
-  The libEnsemble manager is set to dump the history array to file after every 300 generated points,
-  though in this case it will only happen after 500 points due to the batch size.
-
+.. _sampling.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/gen_funcs/sampling.py
 .. _test_6-hump_camel_uniform_sampling.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
diff --git a/docs/data_structures/persis_info.rst b/docs/data_structures/persis_info.rst
index 29fa51f8c..73761a7f9 100644
--- a/docs/data_structures/persis_info.rst
+++ b/docs/data_structures/persis_info.rst
@@ -17,8 +17,10 @@ from the allocation function.
 
 .. seealso::
 
-  From: ``libEnsemble/tests/regression_tests/support.py``
+  From: support.py_
 
   ..  literalinclude:: ../../libensemble/tests/regression_tests/support.py
       :start-at: persis_info_1
       :end-before: end_persis_info_rst_tag
+
+.. _support.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/support.py
diff --git a/docs/sim_gen_alloc_funcs.rst b/docs/sim_gen_alloc_funcs.rst
index cdabafa7e..09780d0ab 100644
--- a/docs/sim_gen_alloc_funcs.rst
+++ b/docs/sim_gen_alloc_funcs.rst
@@ -1,6 +1,11 @@
 User Function API
 -----------------
 
+libEnsemble requires functions for generation, simulation and allocation.
+
+While libEnsemble provides a default allocation function, the sim and gen functions
+must be provided. The required API and examples are given here.
+
 **The libEnsemble History Array**
 
 libEnsemble uses a NumPy structured array :ref:`H<datastruct-history-array>` to
diff --git a/docs/user_funcs.rst b/docs/user_funcs.rst
index 45533e3c8..65a516a45 100644
--- a/docs/user_funcs.rst
+++ b/docs/user_funcs.rst
@@ -1,8 +1,3 @@
-libEnsemble requires functions for generation, simulation and allocation.
-
-While libEnsemble provides a default allocation function, the sim and gen functions
-must be provided. The required API and examples are given here.
-
 .. toctree::
    :caption: libEnsemble User Functions:
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
index d6263f0dc..f43f35567 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
@@ -18,8 +18,8 @@
 
 # Import libEnsemble items for this test
 from libensemble.libE import libE
-from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
-from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
+from libensemble.sim_funcs.six_hump_camel import six_hump_camel
+from libensemble.gen_funcs.sampling import uniform_random_sample
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 
@@ -27,13 +27,13 @@
 libE_specs['save_every_k_sims'] = 400
 libE_specs['save_every_k_gens'] = 300
 
-sim_specs = {'sim_f': sim_f,         # Function whose output is being minimized
-             'in': ['x'],            # Keys to be given to sim_f
-             'out': [('f', float)],  # Name of the outputs from sim_f
+sim_specs = {'sim_f': six_hump_camel,  # Function whose output is being minimized
+             'in': ['x'],              # Keys to be given to sim_f
+             'out': [('f', float)],    # Name of the outputs from sim_f
              }
 # end_sim_specs_rst_tag
 
-gen_specs = {'gen_f': gen_f,                     # Function generating sim_f input
+gen_specs = {'gen_f': uniform_random_sample,     # Function generating sim_f input
              'out': [('x', float, (2,))],        # Tell libE gen_f output, type, size
              'user': {'gen_batch_size': 500,     # Used by this specific gen_f
                       'lb': np.array([-3, -2]),  # Used by this specific gen_f
diff --git a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
index 1d64a2eee..c7af67c49 100644
--- a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
+++ b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
@@ -25,7 +25,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.chwirut1 import chwirut_eval as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample_obj_components as gen_f
-from libensemble.alloc_funcs.fast_alloc_and_pausing import give_sim_work_first as alloc_f
+from libensemble.alloc_funcs.fast_alloc_and_pausing import give_sim_work_first
 from libensemble.tests.regression_tests.support import persis_info_3 as persis_info
 from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
 
@@ -64,7 +64,7 @@
                       'components': m}
              }
 
-alloc_specs = {'alloc_f': alloc_f,              # Allocation function
+alloc_specs = {'alloc_f': give_sim_work_first,  # Allocation function
                'out': [('allocated', bool)],    # Output fields (included in History)
                'user': {'stop_on_NaNs': True,   # Should alloc preempt evals
                         'batch_mode': True,     # Wait until all sim evals are done

From 339af2e5208c9b3eb61953e33ba24be3b72d3e82 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 8 Nov 2019 16:56:35 -0600
Subject: [PATCH 474/644] whitespace

---
 README.rst                         | 3 +--
 docs/data_structures/gen_specs.rst | 2 +-
 docs/data_structures/sim_specs.rst | 1 -
 libensemble/gen_funcs/aposmm.py    | 2 +-
 4 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/README.rst b/README.rst
index a0dec080f..8f530d2da 100644
--- a/README.rst
+++ b/README.rst
@@ -149,7 +149,6 @@ Resources
     url         = {https://buildmedia.readthedocs.org/media/pdf/libensemble/latest/libensemble.pdf}
   }
 
-
 Quickstart Guide
 ----------------
 
@@ -238,7 +237,7 @@ in the top-level directory containing the setup script.
 Coverage reports are produced separately for unit tests and regression tests
 under the relevant directories. For parallel tests, the union of all processors
 is taken. Furthermore, a combined coverage report is created at the top level,
-which can be viewed after ``run_tests.sh`` is completed at 
+which can be viewed after ``run_tests.sh`` is completed at
 ``libensemble/tests/cov_merge/index.html``. The Travis CI coverage results are
 available online at Coveralls_.
 
diff --git a/docs/data_structures/gen_specs.rst b/docs/data_structures/gen_specs.rst
index 566cb5040..6e5dec3ac 100644
--- a/docs/data_structures/gen_specs.rst
+++ b/docs/data_structures/gen_specs.rst
@@ -34,7 +34,7 @@ to main ``libE()`` routine::
   - test_6-hump_camel_uniform_sampling.py_ declares In this example, the
     generation function ``uniform_random_sample`` in sampling.py_ will generate 500 random
     points uniformly over the 2D domain defined by ``gen_specs['ub']`` and
-    ``gen_specs['lb']``.  
+    ``gen_specs['lb']``.
 
   ..  literalinclude:: ../../libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
       :start-at: gen_specs
diff --git a/docs/data_structures/sim_specs.rst b/docs/data_structures/sim_specs.rst
index e3e353b8a..9cc28969f 100644
--- a/docs/data_structures/sim_specs.rst
+++ b/docs/data_structures/sim_specs.rst
@@ -49,7 +49,6 @@ Used to specify the simulation function, its inputs and outputs, and user data::
       :start-at: sim_f
       :end-before: end_sim_specs_rst_tag
 
-
 .. _forces_simf.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/scaling_tests/forces/forces_simf.py
 .. _run_libe_forces.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/scaling_tests/forces/run_libe_forces.py
 .. _test_6-hump_camel_uniform_sampling.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
diff --git a/libensemble/gen_funcs/aposmm.py b/libensemble/gen_funcs/aposmm.py
index e1816a00e..009411429 100644
--- a/libensemble/gen_funcs/aposmm.py
+++ b/libensemble/gen_funcs/aposmm.py
@@ -1,7 +1,7 @@
 """
 This module contains methods used our implementation of the Asynchronously
 Parallel Optimization Solver for finding Multiple Minima (APOSMM) method
-described in detail in :cite:`LW16` 
+described in detail in :cite:`LW16`.
 """
 __all__ = ['aposmm_logic', 'initialize_APOSMM',
            'decide_where_to_start_localopt', 'update_history_dist']

From 4a49ad58c65821d7fb2690e2a0b85208b9f9603e Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 8 Nov 2019 17:03:04 -0600
Subject: [PATCH 475/644] Adding back note

---
 README.rst                             | 5 +++++
 docs/platforms/bebop.rst               | 1 -
 docs/platforms/example_scripts.rst     | 3 ---
 docs/platforms/platforms_index.rst     | 6 ------
 docs/platforms/theta.rst               | 1 -
 docs/tutorials/local_sine_tutorial.rst | 1 -
 6 files changed, 5 insertions(+), 12 deletions(-)

diff --git a/README.rst b/README.rst
index 8f530d2da..7da1c07a3 100644
--- a/README.rst
+++ b/README.rst
@@ -241,6 +241,11 @@ which can be viewed after ``run_tests.sh`` is completed at
 ``libensemble/tests/cov_merge/index.html``. The Travis CI coverage results are
 available online at Coveralls_.
 
+.. note::
+    The job_controller tests can be run using the direct-launch or
+    Balsam job controllers. Balsam integration with libEnsemble is now tested
+    via ``test_balsam_hworld.py``.
+
 Basic Usage
 ~~~~~~~~~~~
 
diff --git a/docs/platforms/bebop.rst b/docs/platforms/bebop.rst
index 71140c193..c72697025 100644
--- a/docs/platforms/bebop.rst
+++ b/docs/platforms/bebop.rst
@@ -73,7 +73,6 @@ the workers to launch calculations with the job-controller or a job-launch comma
     more MPI process than the number of allocated nodes. The Manager and first
     worker run together on a node.
 
-
 If you would like to interact directly with the compute nodes via a shell,
 the following showcases starting a bash session on a Knights Landing node
 for thirty minutes::
diff --git a/docs/platforms/example_scripts.rst b/docs/platforms/example_scripts.rst
index 9300b8abc..3c9fe8d1b 100644
--- a/docs/platforms/example_scripts.rst
+++ b/docs/platforms/example_scripts.rst
@@ -11,21 +11,18 @@ Bebop - Central Mode
 ..  literalinclude:: ../../examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
     :language: bash
 
-
 Bebop - Distributed Mode
 ------------------------
 
 ..  literalinclude:: ../../examples/job_submission_scripts/bebop_submit_slurm.sh
     :language: bash
 
-
 Blues
 -----
 
 ..  literalinclude:: ../../examples/job_submission_scripts/blues_script.pbs
     :language: bash
 
-
 Theta - Central Mode with Balsam
 --------------------------------
 
diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst
index 3716ebf47..d0ee1096a 100644
--- a/docs/platforms/platforms_index.rst
+++ b/docs/platforms/platforms_index.rst
@@ -1,4 +1,3 @@
-
 libEnsemble has been largely developed, supported, and tested on Linux
 distributions and macOS, from laptops to thousands of compute-nodes. Although
 libEnsemble and most user functions are cross-platform compatible, there are
@@ -14,7 +13,6 @@ We recommend installing libEnsemble and it's dependencies in a virtual environme
 created either through ``conda create``, ``virtualenv``, or ``python -m venv``,
 depending on how Python is installed.
 
-
 HPC Systems
 ===========
 
@@ -29,8 +27,6 @@ job-launch command can execute calculations on the other allocated nodes:
     :scale: 75
     :align: center
 
-
-
 Alternatively, in *distributed* mode, each worker process runs independently of
 other workers directly on one or more allocated nodes:
 
@@ -39,7 +35,6 @@ other workers directly on one or more allocated nodes:
     :scale: 75
     :align: center
 
-
 .. note::
 
     Certain machines (like Theta and Summit) that can only submit MPI jobs from
@@ -60,5 +55,4 @@ Read more about configuring and launching libEnsemble on some HPC systems:
     theta
     example_scripts
 
-
 .. _Balsam: https://balsam.readthedocs.io/en/latest/
diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index 957f9f87b..2c6cdfa33 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -24,7 +24,6 @@ Theta features three tiers of nodes: login, MOM (Machine-Oriented Mini-server),
 and compute nodes. Users on login nodes submit batch runs to the MOM nodes.
 MOM nodes execute user batch-scripts to run on the compute nodes.
 
-
 Configuring Python
 ------------------
 
diff --git a/docs/tutorials/local_sine_tutorial.rst b/docs/tutorials/local_sine_tutorial.rst
index 6cfcdaf80..f76a4d04b 100644
--- a/docs/tutorials/local_sine_tutorial.rst
+++ b/docs/tutorials/local_sine_tutorial.rst
@@ -193,7 +193,6 @@ inputs and outputs from those functions to expect.
                     }
                  }
 
-
     sim_specs = {'sim_f': sim_find_sine,       # Our simulator function
                  'in': ['x'],                  # Input field names. 'x' from gen_f output
                  'out': [('y', float)]}        # sim_f output. 'y' = sine('x')

From ec447c16b8a932f3cedea098d3d9584af2a54afb Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 13 Nov 2019 10:01:46 -0600
Subject: [PATCH 476/644] split README into quick-content and overview_usecases

---
 README.rst                 | 127 +++++++++----------------------------
 docs/latex_index.rst       |   1 +
 docs/overview_usecases.rst |  65 +++++++++++++++++++
 3 files changed, 97 insertions(+), 96 deletions(-)
 create mode 100644 docs/overview_usecases.rst

diff --git a/README.rst b/README.rst
index 7da1c07a3..d46ba2f6e 100644
--- a/README.rst
+++ b/README.rst
@@ -53,102 +53,6 @@ many-node simulations. A job controller interface is provided to ensure scripts
 are portable, resilient and flexible; it also enables automatic detection of
 the nodes and cores in a system and can split up jobs automatically if resource
 data isn't supplied.
-
-Overview
---------
-libEnsemble is a Python library to coordinate the concurrent evaluation of
-dynamic ensembles of calculations. libEnsemble uses a manager to allocate work to
-various workers. A libEnsemble worker is the smallest indivisible unit to
-perform some calculation. The work performed by libEnsemble is governed by
-three routines:
-
-* :ref:`gen_f<api_gen_f>`: Generates inputs to ``sim_f``.
-* :ref:`sim_f<api_sim_f>`: Evaluates a simulation or other evaluation at output from ``gen_f``.
-* :ref:`alloc_f<api_alloc_f>`: Decides whether ``sim_f`` or ``gen_f`` should be called (and with what input/resources) as workers become available.
-
-Example ``sim_f``, ``gen_f``, ``alloc_f``, and calling scripts
-be found in the ``examples/`` directory. To enable portability, a
-:doc:`job_controller<job_controller/overview>`
-interface is supplied for users to launch and monitor jobs in their
-user-provided ``sim_f`` and ``gen_f`` routines.
-
-The default ``alloc_f`` tells each available worker to call ``sim_f`` with the
-highest priority unit of work from ``gen_f``. If a worker is idle and there is
-no ``gen_f`` output to give, the worker is told to call ``gen_f``.
-
-Example Use Cases
-~~~~~~~~~~~~~~~~~
-Below are some expected libEnsemble use cases that we support (or are working
-to support) and plan to have examples of:
-
-* A user is looking to optimize a simulation calculation. The simulation may
-  already be using parallel resources, but not a large fraction of some
-  computer. libEnsemble can coordinate the concurrent evaluation of the
-  simulation ``sim_f`` at various parameter values and ``gen_f`` would return
-  candidate parameter values (possibly after each ``sim_f`` output).
-
-* A user has a ``gen_f`` that produces different meshes to be used within a
-  ``sim_f``. Given the ``sim_f`` output, ``gen_f`` will refine a mesh or
-  produce a new mesh. libEnsemble can ensure that the calculated meshes can be
-  used by multiple simulations without requiring movement of data.
-
-* A user is attempting to sample a simulation ``sim_f`` at some parameter
-  values, many of which will cause the simulation to fail. libEnsemble can stop
-  unresponsive evaluations, and recover computational resources for future
-  evaluations. ``gen_f`` can possibly update the sampling after discovering
-  regions where evaluations of ``sim_f`` fail.
-
-* A user has a simulation ``sim_f`` that requires calculating multiple
-  expensive quantities, some of which depend on other quantities. ``sim_f`` can
-  observe intermediate quantities in order to stop related calculations and
-  preempt future calculations associated with poor parameter values.
-
-* A user has a ``sim_f`` with multiple fidelities, with the higher-fidelity
-  evaluations requiring more computational resources, and a
-  ``gen_f``/``alloc_f`` that decides which parameters should be evaluated and
-  at what fidelity level. libEnsemble can coordinate these evaluations without
-  requiring the user know parallel programming.
-
-* A user wishes to identify multiple local optima for a ``sim_f``. Furthermore,
-  sensitivity analysis is desired at each identified optimum. libEnsemble can
-  use the points from the APOSMM ``gen_f`` to identify optima; and after a
-  point is ruled to be an optimum, a different ``gen_f`` can produce a
-  collection of parameters necessary for sensitivity analysis of ``sim_f``.
-
-Naturally, combinations of these use cases are supported as well. An example of
-such a combination is using libEnsemble to solve an optimization problem that
-relies on simulations that fail frequently.
-
-Resources
-~~~~~~~~~~~~~~~~~~
-
-**Support:**
-
-- The best way to receive support is to email questions to ``libEnsemble@lists.mcs.anl.gov``.
-- Communicate (and establish a private channel, if desired) at the `libEnsemble Slack page`_.
-- Join the `libEnsemble mailing list`_ for updates about new releases.
-
-**Further Information:**
-
-- Documentation is provided by ReadtheDocs_.
-- A visual overview of libEnsemble is given in this poster_.
-
-**Citation:**
-
-- Please use the following to cite libEnsemble in a publication:
-
-.. code-block:: bibtex
-
-  @techreport{libEnsemble,
-    author      = {Stephen Hudson and Jeffrey Larson and Stefan M. Wild and
-                   David Bindel and John-Luke Navarro},
-    title       = {{libEnsemble} Users Manual},
-    institution = {Argonne National Laboratory},
-    number      = {Revision 0.5.2},
-    year        = {2019},
-    url         = {https://buildmedia.readthedocs.org/media/pdf/libensemble/latest/libensemble.pdf}
-  }
-
 Quickstart Guide
 ----------------
 
@@ -272,6 +176,37 @@ When specifying these options via command line options, one may use the
 
 See the `user guide`_ for more information.
 
+
+Resources
+~~~~~~~~~~~~~~~~~~
+
+**Support:**
+
+- The best way to receive support is to email questions to ``libEnsemble@lists.mcs.anl.gov``.
+- Communicate (and establish a private channel, if desired) at the `libEnsemble Slack page`_.
+- Join the `libEnsemble mailing list`_ for updates about new releases.
+
+**Further Information:**
+
+- Documentation is provided by ReadtheDocs_.
+- A visual overview of libEnsemble is given in this poster_.
+
+**Citation:**
+
+- Please use the following to cite libEnsemble in a publication:
+
+.. code-block:: bibtex
+
+  @techreport{libEnsemble,
+    author      = {Stephen Hudson and Jeffrey Larson and Stefan M. Wild and
+                   David Bindel and John-Luke Navarro},
+    title       = {{libEnsemble} Users Manual},
+    institution = {Argonne National Laboratory},
+    number      = {Revision 0.5.2},
+    year        = {2019},
+    url         = {https://buildmedia.readthedocs.org/media/pdf/libensemble/latest/libensemble.pdf}
+  }
+
 .. _Balsam: https://www.alcf.anl.gov/balsam
 .. _common.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/common.py
 .. _Coveralls: https://coveralls.io/github/Libensemble/libensemble?branch=master
diff --git a/docs/latex_index.rst b/docs/latex_index.rst
index baaccf059..b5f713c5f 100644
--- a/docs/latex_index.rst
+++ b/docs/latex_index.rst
@@ -6,6 +6,7 @@
    :maxdepth: 3
 
    Introduction<introduction>
+   overview_usecases
    programming_libE
    platforms/platforms
    dev_info
diff --git a/docs/overview_usecases.rst b/docs/overview_usecases.rst
new file mode 100644
index 000000000..5c2bbbc80
--- /dev/null
+++ b/docs/overview_usecases.rst
@@ -0,0 +1,65 @@
+
+Overview
+--------
+libEnsemble is a Python library to coordinate the concurrent evaluation of
+dynamic ensembles of calculations. libEnsemble uses a manager to allocate work to
+various workers. A libEnsemble worker is the smallest indivisible unit to
+perform some calculation. The work performed by libEnsemble is governed by
+three routines:
+
+* :ref:`gen_f<api_gen_f>`: Generates inputs to ``sim_f``.
+* :ref:`sim_f<api_sim_f>`: Evaluates a simulation or other evaluation at output from ``gen_f``.
+* :ref:`alloc_f<api_alloc_f>`: Decides whether ``sim_f`` or ``gen_f`` should be called (and with what input/resources) as workers become available.
+
+Example ``sim_f``, ``gen_f``, ``alloc_f``, and calling scripts
+be found in the ``examples/`` directory. To enable portability, a
+:doc:`job_controller<job_controller/overview>`
+interface is supplied for users to launch and monitor jobs in their
+user-provided ``sim_f`` and ``gen_f`` routines.
+
+The default ``alloc_f`` tells each available worker to call ``sim_f`` with the
+highest priority unit of work from ``gen_f``. If a worker is idle and there is
+no ``gen_f`` output to give, the worker is told to call ``gen_f``.
+
+Example Use Cases
+~~~~~~~~~~~~~~~~~
+Below are some expected libEnsemble use cases that we support (or are working
+to support) and plan to have examples of:
+
+* A user is looking to optimize a simulation calculation. The simulation may
+  already be using parallel resources, but not a large fraction of some
+  computer. libEnsemble can coordinate the concurrent evaluation of the
+  simulation ``sim_f`` at various parameter values and ``gen_f`` would return
+  candidate parameter values (possibly after each ``sim_f`` output).
+
+* A user has a ``gen_f`` that produces different meshes to be used within a
+  ``sim_f``. Given the ``sim_f`` output, ``gen_f`` will refine a mesh or
+  produce a new mesh. libEnsemble can ensure that the calculated meshes can be
+  used by multiple simulations without requiring movement of data.
+
+* A user is attempting to sample a simulation ``sim_f`` at some parameter
+  values, many of which will cause the simulation to fail. libEnsemble can stop
+  unresponsive evaluations, and recover computational resources for future
+  evaluations. ``gen_f`` can possibly update the sampling after discovering
+  regions where evaluations of ``sim_f`` fail.
+
+* A user has a simulation ``sim_f`` that requires calculating multiple
+  expensive quantities, some of which depend on other quantities. ``sim_f`` can
+  observe intermediate quantities in order to stop related calculations and
+  preempt future calculations associated with poor parameter values.
+
+* A user has a ``sim_f`` with multiple fidelities, with the higher-fidelity
+  evaluations requiring more computational resources, and a
+  ``gen_f``/``alloc_f`` that decides which parameters should be evaluated and
+  at what fidelity level. libEnsemble can coordinate these evaluations without
+  requiring the user know parallel programming.
+
+* A user wishes to identify multiple local optima for a ``sim_f``. Furthermore,
+  sensitivity analysis is desired at each identified optimum. libEnsemble can
+  use the points from the APOSMM ``gen_f`` to identify optima; and after a
+  point is ruled to be an optimum, a different ``gen_f`` can produce a
+  collection of parameters necessary for sensitivity analysis of ``sim_f``.
+
+Naturally, combinations of these use cases are supported as well. An example of
+such a combination is using libEnsemble to solve an optimization problem that
+relies on simulations that fail frequently.

From 4bd4d63842dbc441cac8acfe2b455519c2932a21 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 13 Nov 2019 10:45:03 -0600
Subject: [PATCH 477/644] new HTML toctree structure, new files for issues and
 utilities, platforms added to introduction

---
 docs/index.rst                     | 30 +++++++++++++++++++-----------
 docs/introduction.rst              |  2 ++
 docs/known_issues.rst              | 12 ++++++++++++
 docs/overview_usecases.rst         |  4 ++--
 docs/platforms/platforms_index.rst | 15 ---------------
 docs/utilities.rst                 |  7 +++++++
 6 files changed, 42 insertions(+), 28 deletions(-)
 create mode 100644 docs/known_issues.rst
 create mode 100644 docs/utilities.rst

diff --git a/docs/index.rst b/docs/index.rst
index 6d2860a58..2abb5df85 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -7,27 +7,35 @@
 
 .. toctree::
    :maxdepth: 2
-   :caption: Getting Started:
-
+   :caption: User Guide:
    Introduction<introduction>
+   overview_usecases
    programming_libE
+   data_structures/data_structures
+   user_funcs
+   job_controller/jc_index
+   logging
+   utilities
 
 .. toctree::
-   :caption: Further information:
    :maxdepth: 2
-
-   platforms/platforms
-   dev_info
+   :caption: Tutorials:
+   tutorials/local_sine_tutorial
 
 .. toctree::
-   :caption: In Depth:
    :maxdepth: 2
-
-   tutorials/tutorials
+   :caption: Additional Reference:
    FAQ
-   examples/examples_index
-   bibliography
    release_notes
+   contributing
+   known_issues
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Developer Guide:
+   dev_guide/release_management/release_index
+   dev_guide/dev_API/developer_API
+
 
 Indices and tables
 ==================
diff --git a/docs/introduction.rst b/docs/introduction.rst
index 0152356dc..490299cb6 100644
--- a/docs/introduction.rst
+++ b/docs/introduction.rst
@@ -1,2 +1,4 @@
 .. include:: ../README.rst
     :start-after: after_badges_rst_tag
+
+.. include:: platforms/platforms_index
diff --git a/docs/known_issues.rst b/docs/known_issues.rst
new file mode 100644
index 000000000..ccad162ee
--- /dev/null
+++ b/docs/known_issues.rst
@@ -0,0 +1,12 @@
+Known Issues
+============
+
+The following selection describes known bugs, errors, or other difficulties that
+may occur when using libEnsemble.
+
+Coming soon.
+
+
+
+Platform-specific issues
+------------------------
diff --git a/docs/overview_usecases.rst b/docs/overview_usecases.rst
index 5c2bbbc80..e076dcb94 100644
--- a/docs/overview_usecases.rst
+++ b/docs/overview_usecases.rst
@@ -1,6 +1,6 @@
 
-Overview
---------
+Architecture Overview
+---------------------
 libEnsemble is a Python library to coordinate the concurrent evaluation of
 dynamic ensembles of calculations. libEnsemble uses a manager to allocate work to
 various workers. A libEnsemble worker is the smallest indivisible unit to
diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst
index d0ee1096a..24a6c98c8 100644
--- a/docs/platforms/platforms_index.rst
+++ b/docs/platforms/platforms_index.rst
@@ -1,18 +1,3 @@
-libEnsemble has been largely developed, supported, and tested on Linux
-distributions and macOS, from laptops to thousands of compute-nodes. Although
-libEnsemble and most user functions are cross-platform compatible, there are
-platform-specific differences for installing and configuring libEnsemble.
-
-Personal Computers
-==================
-
-Users interested in installing and running libEnsemble on their personal machines
-are encouraged to start by reading the Quickstart guide :doc:`here<../quickstart>`.
-
-We recommend installing libEnsemble and it's dependencies in a virtual environment,
-created either through ``conda create``, ``virtualenv``, or ``python -m venv``,
-depending on how Python is installed.
-
 HPC Systems
 ===========
 
diff --git a/docs/utilities.rst b/docs/utilities.rst
new file mode 100644
index 000000000..2285801ff
--- /dev/null
+++ b/docs/utilities.rst
@@ -0,0 +1,7 @@
+libEnsemble Utilities
+=====================
+
+libEnsemble features several scripts and tools to assist in writing consistent
+calling scripts and user functions.
+
+Coming soon.

From 42a66688b3ff32aa4a8a1c565a2eb2b7a1fecad6 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 13 Nov 2019 12:20:14 -0600
Subject: [PATCH 478/644] Moves HPC content, revises some headings

---
 README.rst                         |  7 ++++---
 docs/index.rst                     |  4 ++++
 docs/introduction.rst              | 16 +++++++++++++++-
 docs/platforms/platforms_index.rst | 10 ----------
 docs/utilities.rst                 |  4 ++--
 5 files changed, 25 insertions(+), 16 deletions(-)

diff --git a/README.rst b/README.rst
index d46ba2f6e..506a1bb72 100644
--- a/README.rst
+++ b/README.rst
@@ -53,8 +53,6 @@ many-node simulations. A job controller interface is provided to ensure scripts
 are portable, resilient and flexible; it also enables automatic detection of
 the nodes and cores in a system and can split up jobs automatically if resource
 data isn't supplied.
-Quickstart Guide
-----------------
 
 Dependencies
 ~~~~~~~~~~~~
@@ -178,7 +176,7 @@ See the `user guide`_ for more information.
 
 
 Resources
-~~~~~~~~~~~~~~~~~~
+~~~~~~~~~
 
 **Support:**
 
@@ -207,6 +205,9 @@ Resources
     url         = {https://buildmedia.readthedocs.org/media/pdf/libensemble/latest/libensemble.pdf}
   }
 
+
+
+
 .. _Balsam: https://www.alcf.anl.gov/balsam
 .. _common.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/common.py
 .. _Coveralls: https://coveralls.io/github/Libensemble/libensemble?branch=master
diff --git a/docs/index.rst b/docs/index.rst
index 2abb5df85..4887682da 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -8,6 +8,7 @@
 .. toctree::
    :maxdepth: 2
    :caption: User Guide:
+
    Introduction<introduction>
    overview_usecases
    programming_libE
@@ -20,11 +21,13 @@
 .. toctree::
    :maxdepth: 2
    :caption: Tutorials:
+
    tutorials/local_sine_tutorial
 
 .. toctree::
    :maxdepth: 2
    :caption: Additional Reference:
+
    FAQ
    release_notes
    contributing
@@ -33,6 +36,7 @@
 .. toctree::
    :maxdepth: 2
    :caption: Developer Guide:
+
    dev_guide/release_management/release_index
    dev_guide/dev_API/developer_API
 
diff --git a/docs/introduction.rst b/docs/introduction.rst
index 490299cb6..c45471a45 100644
--- a/docs/introduction.rst
+++ b/docs/introduction.rst
@@ -1,4 +1,18 @@
 .. include:: ../README.rst
     :start-after: after_badges_rst_tag
 
-.. include:: platforms/platforms_index
+Support for HPC
+~~~~~~~~~~~~~~~
+
+libEnsemble's flexible architecture was developed with HPC System support and
+scaling as a central focus, and can perform calculations on both laptops and
+thousands of compute-nodes.
+
+.. toctree::
+    :maxdepth: 1
+    :titlesonly:
+
+    platforms/platforms_index
+    platforms/bebop
+    platforms/theta
+    platforms/example_scripts
diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst
index 24a6c98c8..3b8ac53f3 100644
--- a/docs/platforms/platforms_index.rst
+++ b/docs/platforms/platforms_index.rst
@@ -30,14 +30,4 @@ differently. On these machines, libEnsemble is run centralized on either a
 compute-node with the support of Balsam_ or on a frontend server called a MOM
 (Machine-Oriented Mini-server) node.
 
-Read more about configuring and launching libEnsemble on some HPC systems:
-
-.. toctree::
-    :maxdepth: 2
-    :titlesonly:
-
-    bebop
-    theta
-    example_scripts
-
 .. _Balsam: https://balsam.readthedocs.io/en/latest/
diff --git a/docs/utilities.rst b/docs/utilities.rst
index 2285801ff..03ff9a5cc 100644
--- a/docs/utilities.rst
+++ b/docs/utilities.rst
@@ -1,5 +1,5 @@
-libEnsemble Utilities
-=====================
+Utilities
+=========
 
 libEnsemble features several scripts and tools to assist in writing consistent
 calling scripts and user functions.

From 89d164df5ca2a8e2f2eb39d7126a99dcc7d4ae89 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 13 Nov 2019 13:11:18 -0600
Subject: [PATCH 479/644] move check_inputs to utilities

---
 docs/data_structures/data_structures.rst |  9 ---------
 docs/utilities.rst                       | 14 ++++++++++++--
 2 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/docs/data_structures/data_structures.rst b/docs/data_structures/data_structures.rst
index f86c9042c..1ab157e17 100644
--- a/docs/data_structures/data_structures.rst
+++ b/docs/data_structures/data_structures.rst
@@ -20,15 +20,6 @@ and the
 :ref:`work<datastruct-history-array>` dictionary produced by the allocation
 function.
 
-.. note::
-  Users can check the formatting and consistency of ``exit_criteria`` and each ``specs``
-  dictionary with the ``check_inputs()`` function from the ``utils`` module.
-  Provide any combination of these data structures as keyword arguments.
-  For example::
-
-    from libensemble.libE import check_inputs
-
-    check_inputs(sim_specs=my-sim_specs, gen_specs=my-gen_specs, exit_criteria=ec)
 
 .. toctree::
    :maxdepth: 3
diff --git a/docs/utilities.rst b/docs/utilities.rst
index 03ff9a5cc..ce3dc5bad 100644
--- a/docs/utilities.rst
+++ b/docs/utilities.rst
@@ -1,7 +1,17 @@
 Utilities
 =========
 
-libEnsemble features several scripts and tools to assist in writing consistent
+libEnsemble features several modules and tools to assist in writing consistent
 calling scripts and user functions.
 
-Coming soon.
+libE input consistency
+----------------------
+
+Users can check the formatting and consistency of ``exit_criteria`` and each
+``specs`` dictionary with the ``check_inputs()`` function from the ``utils``
+module. Provide any combination of these data structures as keyword arguments.
+For example::
+
+  from libensemble.libE import check_inputs
+
+  check_inputs(sim_specs=my-sim_specs, gen_specs=my-gen_specs, exit_criteria=ec)

From 44353f0f478c8031e37762eabb5ba45be13cd9ad Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 13 Nov 2019 13:35:35 -0600
Subject: [PATCH 480/644] separate libe module, move known issues, header
 adjustments

---
 docs/index.rst             |  2 +-
 docs/known_issues.rst      | 11 +++++------
 docs/libe_module.rst       |  6 ++++++
 docs/overview_usecases.rst |  2 +-
 4 files changed, 13 insertions(+), 8 deletions(-)
 create mode 100644 docs/libe_module.rst

diff --git a/docs/index.rst b/docs/index.rst
index 4887682da..4e6c889ca 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -11,7 +11,7 @@
 
    Introduction<introduction>
    overview_usecases
-   programming_libE
+   libe_module
    data_structures/data_structures
    user_funcs
    job_controller/jc_index
diff --git a/docs/known_issues.rst b/docs/known_issues.rst
index ccad162ee..1d9c99087 100644
--- a/docs/known_issues.rst
+++ b/docs/known_issues.rst
@@ -4,9 +4,8 @@ Known Issues
 The following selection describes known bugs, errors, or other difficulties that
 may occur when using libEnsemble.
 
-Coming soon.
-
-
-
-Platform-specific issues
-------------------------
+* OpenMPI does not work with direct MPI job launches in mpi4py comms mode, as it does not support nested MPI launches
+  (Either use local mode or Balsam job controller).
+* Local comms mode (multiprocessing) may fail if MPI is initialized before forking processors. This is thought to be responsible for issues combining with PETSc.
+* Remote detection of logical cores via LSB_HOSTS (e.g., Summit) returns number of physical cores as SMT info not available.
+* TCP mode does not support: 1) more than one libEnsemble call in a given script or 2) the auto-resources option to the job controller.
diff --git a/docs/libe_module.rst b/docs/libe_module.rst
new file mode 100644
index 000000000..ddbacb128
--- /dev/null
+++ b/docs/libe_module.rst
@@ -0,0 +1,6 @@
+Main libEnsemble module
+=======================
+
+.. automodule:: libE
+  :members:
+  :no-undoc-members:
diff --git a/docs/overview_usecases.rst b/docs/overview_usecases.rst
index e076dcb94..c7973e198 100644
--- a/docs/overview_usecases.rst
+++ b/docs/overview_usecases.rst
@@ -1,5 +1,5 @@
 
-Architecture Overview
+Architecture overview
 ---------------------
 libEnsemble is a Python library to coordinate the concurrent evaluation of
 dynamic ensembles of calculations. libEnsemble uses a manager to allocate work to

From 91fbe4e5c299275a40d5ab121067c3279b330db2 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 13 Nov 2019 16:21:32 -0600
Subject: [PATCH 481/644] rename headings, re-add H and output info, update
 utilities and known issues, move HPC to own heading under user guide

---
 README.rst                         |  3 +-
 docs/index.rst                     |  3 +-
 docs/introduction.rst              | 19 ++--------
 docs/known_issues.rst              | 16 ++++++---
 docs/overview_usecases.rst         | 56 ++++++++++++++++++++++++++++++
 docs/platforms/platforms_index.rst | 15 ++++++++
 docs/utilities.rst                 | 35 +++++++++++++++++--
 docs/welcome.rst                   |  2 +-
 8 files changed, 123 insertions(+), 26 deletions(-)

diff --git a/README.rst b/README.rst
index 506a1bb72..ac574dfeb 100644
--- a/README.rst
+++ b/README.rst
@@ -18,12 +18,13 @@
    :alt: Documentation Status
 
 |
-.. after_badges_rst_tag
 
 ===========================
 Introduction to libEnsemble
 ===========================
 
+.. after_badges_rst_tag
+
 libEnsemble is a Python library to coordinate the concurrent evaluation of
 dynamic ensembles of calculations. The library is developed to use massively
 parallel resources to accelerate the solution of design, decision, and
diff --git a/docs/index.rst b/docs/index.rst
index 4e6c889ca..ce8078017 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -9,7 +9,7 @@
    :maxdepth: 2
    :caption: User Guide:
 
-   Introduction<introduction>
+   Quickstart<introduction>
    overview_usecases
    libe_module
    data_structures/data_structures
@@ -17,6 +17,7 @@
    job_controller/jc_index
    logging
    utilities
+   platforms/platforms_index
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/introduction.rst b/docs/introduction.rst
index c45471a45..e62652fa2 100644
--- a/docs/introduction.rst
+++ b/docs/introduction.rst
@@ -1,18 +1,5 @@
+Quickstart
+==========
+
 .. include:: ../README.rst
     :start-after: after_badges_rst_tag
-
-Support for HPC
-~~~~~~~~~~~~~~~
-
-libEnsemble's flexible architecture was developed with HPC System support and
-scaling as a central focus, and can perform calculations on both laptops and
-thousands of compute-nodes.
-
-.. toctree::
-    :maxdepth: 1
-    :titlesonly:
-
-    platforms/platforms_index
-    platforms/bebop
-    platforms/theta
-    platforms/example_scripts
diff --git a/docs/known_issues.rst b/docs/known_issues.rst
index 1d9c99087..01dfd1afc 100644
--- a/docs/known_issues.rst
+++ b/docs/known_issues.rst
@@ -4,8 +4,14 @@ Known Issues
 The following selection describes known bugs, errors, or other difficulties that
 may occur when using libEnsemble.
 
-* OpenMPI does not work with direct MPI job launches in mpi4py comms mode, as it does not support nested MPI launches
-  (Either use local mode or Balsam job controller).
-* Local comms mode (multiprocessing) may fail if MPI is initialized before forking processors. This is thought to be responsible for issues combining with PETSc.
-* Remote detection of logical cores via LSB_HOSTS (e.g., Summit) returns number of physical cores as SMT info not available.
-* TCP mode does not support: 1) more than one libEnsemble call in a given script or 2) the auto-resources option to the job controller.
+* OpenMPI does not work with direct MPI job launches in mpi4py comms mode, as it
+does not support nested MPI launches (Either use local mode or Balsam job controller).
+* Local comms mode (multiprocessing) may fail if MPI is initialized before forking
+processors. This is thought to be responsible for issues combining with PETSc.
+* Remote detection of logical cores via LSB_HOSTS (e.g., Summit) returns number
+of physical cores as SMT info not available.
+* TCP mode does not support: 1) more than one libEnsemble call in a given script
+or 2) the auto-resources option to the job controller.
+* libEnsemble may hang on systems with matching probes not enabled on
+ the native fabric, like on Intel's Truescale (TMI) fabric for
+  instance. See the :doc:`FAQ<FAQ>` for more information.
diff --git a/docs/overview_usecases.rst b/docs/overview_usecases.rst
index c7973e198..42d8fb71d 100644
--- a/docs/overview_usecases.rst
+++ b/docs/overview_usecases.rst
@@ -63,3 +63,59 @@ to support) and plan to have examples of:
 Naturally, combinations of these use cases are supported as well. An example of
 such a combination is using libEnsemble to solve an optimization problem that
 relies on simulations that fail frequently.
+
+The History Array
+~~~~~~~~~~~~~~~~~
+libEnsemble uses a NumPy structured array :ref:`H<datastruct-history-array>` to
+store output from ``gen_f`` and corresponding ``sim_f`` output. Similarly,
+``gen_f`` and ``sim_f`` are expected to return output in NumPy structured
+arrays. The names of the fields to be given as input to ``gen_f`` and ``sim_f``
+must be an output from ``gen_f`` or ``sim_f``. In addition to the fields output
+from ``sim_f`` and ``gen_f``, the final history returned from libEnsemble will
+include the following fields:
+
+* ``sim_id`` [int]: Each unit of work output from ``gen_f`` must have an
+  associated ``sim_id``. The generator can assign this, but users must be
+  careful to ensure points are added in order. For example, ``if alloc_f``
+  allows for two ``gen_f`` instances to be running simultaneously, ``alloc_f``
+  should ensure that both don’t generate points with the same ``sim_id``.
+
+* ``given`` [bool]: Has this ``gen_f`` output been given to a libEnsemble
+  worker to be evaluated yet?
+
+* ``given_time`` [float]: At what time (since the epoch) was this ``gen_f``
+  output given to a worker?
+
+* ``sim_worker`` [int]: libEnsemble worker that it was given to be evaluated.
+
+* ``gen_worker`` [int]: libEnsemble worker that generated this ``sim_id``
+
+* ``gen_time`` [float]: At what time (since the epoch) was this entry (or
+  collection of entries) put into ``H`` by the manager
+
+* ``returned`` [bool]: Has this worker completed the evaluation of this unit of
+  work?
+
+Output
+~~~~~~
+The history array :ref:`H<datastruct-history-array>` and
+:ref:`persis_info<datastruct-persis-info>` dictionary are returned to the user
+by libEnsemble.  If libEnsemble aborts on an exception, these structures are
+dumped to the respective files,
+
+* ``libE_history_at_abort_<sim_count>.npy``
+* ``libE_history_at_abort_<sim_count>.pickle``
+
+where ``sim_count`` is the number of points evaluated.
+
+Other libEnsemble files produced by default are:
+
+* ``libE_stats.txt``: This contains a one-line summary of all user
+  calculations.  Each calculation summary is sent by workers to the manager and
+  printed as the run progresses.
+
+* ``ensemble.log``: This is the logging output from libEnsemble. The default
+  logging is at INFO level. To gain additional diagnostics logging level can be
+  set to DEBUG.  If this file is not removed, multiple runs will append output.
+  Messages at or above level MANAGER_WARNING are also copied to stderr to alert
+  the user promptly.  For more info, see :doc:`Logging<logging>`.
diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst
index 3b8ac53f3..b0edc3968 100644
--- a/docs/platforms/platforms_index.rst
+++ b/docs/platforms/platforms_index.rst
@@ -1,6 +1,11 @@
 HPC Systems
 ===========
 
+libEnsemble has been developed, supported, and tested on systems of highly varying
+scales, from laptops to thousands of compute-nodes. libEnsemble's embarrassingly
+parallel  scaling capabilities are best exemplified on the resources available
+within high-performance machines.
+
 libEnsemble's flexible architecture lends it best to two general modes of worker
 distributions across allocated compute nodes. The first mode we refer
 to as *centralized* mode, where the libEnsemble manager and worker processes
@@ -30,4 +35,14 @@ differently. On these machines, libEnsemble is run centralized on either a
 compute-node with the support of Balsam_ or on a frontend server called a MOM
 (Machine-Oriented Mini-server) node.
 
+Read more about configuring and launching libEnsemble on some HPC systems:
+
+.. toctree::
+    :maxdepth: 2
+    :titlesonly:
+
+    bebop
+    theta
+    example_scripts
+
 .. _Balsam: https://balsam.readthedocs.io/en/latest/
diff --git a/docs/utilities.rst b/docs/utilities.rst
index ce3dc5bad..87d4734cc 100644
--- a/docs/utilities.rst
+++ b/docs/utilities.rst
@@ -4,8 +4,8 @@ Utilities
 libEnsemble features several modules and tools to assist in writing consistent
 calling scripts and user functions.
 
-libE input consistency
-----------------------
+Input consistency
+-----------------
 
 Users can check the formatting and consistency of ``exit_criteria`` and each
 ``specs`` dictionary with the ``check_inputs()`` function from the ``utils``
@@ -15,3 +15,34 @@ For example::
   from libensemble.libE import check_inputs
 
   check_inputs(sim_specs=my-sim_specs, gen_specs=my-gen_specs, exit_criteria=ec)
+
+Parameters as command-line arguments
+------------------------------------
+
+The ``parse_args()`` function can be used to pass common libEnsemble parameters as
+command-line arguments.
+
+In your calling script::
+
+    from libensemble.tests.regression_tests.common import parse_args
+    nworkers, is_master, libE_specs, misc_args = parse_args()
+
+From the shell, for example::
+
+    $ python calling_script --comms local --nworkers 4
+
+Usage:
+
+.. code-block:: bash
+
+    usage: test_... [-h] [--comms [{local,tcp,ssh,client,mpi}]]
+                    [--nworkers [NWORKERS]] [--workers WORKERS [WORKERS ...]]
+                    [--workerID [WORKERID]] [--server SERVER SERVER SERVER]
+                    [--pwd [PWD]] [--worker_pwd [WORKER_PWD]]
+                    [--worker_python [WORKER_PYTHON]]
+                    [--tester_args [TESTER_ARGS [TESTER_ARGS ...]]]
+
+.. note::
+    Since this utility was developed to support automatic testing, it currently
+    only accepts calling scripts prepended with ``test_`` and isn't necessarily
+    recommended for production purposes.
diff --git a/docs/welcome.rst b/docs/welcome.rst
index 7decf8888..47d45369e 100644
--- a/docs/welcome.rst
+++ b/docs/welcome.rst
@@ -27,5 +27,5 @@ libEnsemble is a library to coordinate the concurrent evaluation of dynamic ense
 
 * New to libEnsemble? Start :doc:`here<introduction>`.
 * Try out libEnsemble with a :doc:`tutorial<tutorials/local_sine_tutorial>`.
-* Go in-depth by reading the :doc:`User Guide<programming_libE>`.
+* Go in-depth by reading the :doc:`Overview<overview_usecases>`.
 * Check the :doc:`FAQ<FAQ>` for common questions and answers, errors and resolutions.

From 1d929ee907539282f88701cfee00b03237d1b92f Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 13 Nov 2019 16:41:22 -0600
Subject: [PATCH 482/644] How's this for html/pdf harmony

---
 README.rst                 | 180 +------------------------------------
 docs/latex_index.rst       |   3 +-
 docs/overview_usecases.rst |   4 +-
 3 files changed, 5 insertions(+), 182 deletions(-)

diff --git a/README.rst b/README.rst
index 506a1bb72..a8b092d75 100644
--- a/README.rst
+++ b/README.rst
@@ -54,183 +54,7 @@ are portable, resilient and flexible; it also enables automatic detection of
 the nodes and cores in a system and can split up jobs automatically if resource
 data isn't supplied.
 
-Dependencies
-~~~~~~~~~~~~
+.. only:: html
 
-Required dependencies:
+  .. include:: deps.rst
 
-* Python_ 3.5 or above.
-* NumPy_
-
-For libEnsemble running with the mpi4py parallelism:
-
-* A functional MPI 1.x/2.x/3.x implementation, such as MPICH_, built with shared/dynamic libraries.
-* mpi4py_ v2.0.0 or above
-
-Optional dependency:
-
-* Balsam_
-
-From v0.2.0, libEnsemble has the option of using the Balsam job manager. This
-is required for running libEnsemble on the compute nodes of some supercomputing
-platforms (e.g., Cray XC40); platforms that do not support launching jobs from
-compute nodes. Note that as of v0.5.0, libEnsemble can also be run on the
-launch nodes using multiprocessing.
-
-The example sim and gen functions and tests require the following dependencies:
-
-* SciPy_
-* petsc4py_
-* PETSc_ - This can optionally be installed by pip along with petsc4py
-* NLopt_ - Installed with `shared libraries enabled`_.
-
-PETSc and NLopt must be built with shared libraries enabled and present in
-``sys.path`` (e.g., via setting the ``PYTHONPATH`` environment variable). NLopt
-should produce a file ``nlopt.py`` if Python is found on the system. NLopt may also
-require SWIG_ to be installed on certain systems.
-
-Installation
-~~~~~~~~~~~~
-
-Use pip to install libEnsemble and its dependencies::
-
-    pip install libensemble
-
-libEnsemble is also available in the Spack_ distribution. It can be installed from Spack with::
-
-    spack install py-libensemble
-
-The tests and examples can be accessed in the GitHub_ repository.
-If necessary, you may install all optional dependencies (listed above) at once with::
-
-    pip install libensemble[extras]
-
-A tarball_ of the most recent release is also available.
-
-Testing
-~~~~~~~
-
-The provided test suite includes both unit and regression tests and is run
-regularly on:
-
-* `Travis CI`_
-
-The test suite requires the mock_, pytest_, pytest-cov_, and pytest-timeout_
-packages to be installed and can be run from the libensemble/tests directory of
-the source distribution by running::
-
-    ./run-tests.sh
-
-To clean the test repositories run::
-
-    ./run-tests.sh -c
-
-Further options are available. To see a complete list of options run::
-
-    ./run-tests.sh -h
-
-If you have the source distribution, you can download (but not install) the testing
-prerequisites and run the tests with::
-
-    python setup.py test
-
-in the top-level directory containing the setup script.
-
-Coverage reports are produced separately for unit tests and regression tests
-under the relevant directories. For parallel tests, the union of all processors
-is taken. Furthermore, a combined coverage report is created at the top level,
-which can be viewed after ``run_tests.sh`` is completed at
-``libensemble/tests/cov_merge/index.html``. The Travis CI coverage results are
-available online at Coveralls_.
-
-.. note::
-    The job_controller tests can be run using the direct-launch or
-    Balsam job controllers. Balsam integration with libEnsemble is now tested
-    via ``test_balsam_hworld.py``.
-
-Basic Usage
-~~~~~~~~~~~
-
-The examples directory contains example libEnsemble calling scripts, sim
-functions, gen functions, alloc functions and job submission scripts.
-
-The default manager/worker communications mode is MPI. The user script is
-launched as::
-
-    mpiexec -np N python myscript.py
-
-where ``N`` is the number of processors. This will launch one manager and
-``N-1`` workers.
-
-If running in local mode, which uses Python's multiprocessing module, the
-``local`` comms option and the number of workers must be specified. The script
-can then be run as a regular python script::
-
-    python myscript.py
-
-When specifying these options via command line options, one may use the
-``parse_args`` function used in the regression tests, which can be found in
-`common.py`_ in the ``libensemble/tests/regression_tests`` directory.
-
-See the `user guide`_ for more information.
-
-
-Resources
-~~~~~~~~~
-
-**Support:**
-
-- The best way to receive support is to email questions to ``libEnsemble@lists.mcs.anl.gov``.
-- Communicate (and establish a private channel, if desired) at the `libEnsemble Slack page`_.
-- Join the `libEnsemble mailing list`_ for updates about new releases.
-
-**Further Information:**
-
-- Documentation is provided by ReadtheDocs_.
-- A visual overview of libEnsemble is given in this poster_.
-
-**Citation:**
-
-- Please use the following to cite libEnsemble in a publication:
-
-.. code-block:: bibtex
-
-  @techreport{libEnsemble,
-    author      = {Stephen Hudson and Jeffrey Larson and Stefan M. Wild and
-                   David Bindel and John-Luke Navarro},
-    title       = {{libEnsemble} Users Manual},
-    institution = {Argonne National Laboratory},
-    number      = {Revision 0.5.2},
-    year        = {2019},
-    url         = {https://buildmedia.readthedocs.org/media/pdf/libensemble/latest/libensemble.pdf}
-  }
-
-
-
-
-.. _Balsam: https://www.alcf.anl.gov/balsam
-.. _common.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/common.py
-.. _Coveralls: https://coveralls.io/github/Libensemble/libensemble?branch=master
-.. _GitHub: https://github.com/Libensemble/libensemble
-.. _libEnsemble mailing list: https://lists.mcs.anl.gov/mailman/listinfo/libensemble
-.. _libEnsemble Slack page: https://libensemble.slack.com
-.. _mock: https://pypi.org/project/mock
-.. _mpi4py: https://bitbucket.org/mpi4py/mpi4py
-.. _MPICH: http://www.mpich.org/
-.. _nlopt: http://ab-initio.mit.edu/wiki/index.php/NLopt
-.. _NumPy: http://www.numpy.org
-.. _petsc4py: https://bitbucket.org/petsc/petsc4py
-.. _PETSc: http://www.mcs.anl.gov/petsc
-.. _poster: https://figshare.com/articles/LibEnsemble_PETSc_TAO-_Sustaining_a_library_for_dynamic_ensemble-based_computations/7765454
-.. _pytest-cov: https://pypi.org/project/pytest-cov/
-.. _pytest-timeout: https://pypi.org/project/pytest-timeout/
-.. _pytest: https://pypi.org/project/pytest/
-.. _Python: http://www.python.org
-.. _ReadtheDocs: http://libensemble.readthedocs.org/
-.. _SciPy: http://www.scipy.org
-.. _shared libraries enabled: http://ab-initio.mit.edu/wiki/index.php/NLopt_Installation#Shared_libraries
-.. _Spack: https://spack.readthedocs.io/en/latest
-.. _SWIG: http://swig.org/
-.. _tarball: https://github.com/Libensemble/libensemble/releases/latest
-.. _Travis CI: https://travis-ci.org/Libensemble/libensemble
-.. _user guide: https://libensemble.readthedocs.io/en/latest/user_guide.html
diff --git a/docs/latex_index.rst b/docs/latex_index.rst
index b5f713c5f..771299c70 100644
--- a/docs/latex_index.rst
+++ b/docs/latex_index.rst
@@ -5,8 +5,7 @@
 .. toctree::
    :maxdepth: 3
 
-   Introduction<introduction>
-   overview_usecases
+   Introduction<introduction_latex>
    programming_libE
    platforms/platforms
    dev_info
diff --git a/docs/overview_usecases.rst b/docs/overview_usecases.rst
index c7973e198..7ef8683ec 100644
--- a/docs/overview_usecases.rst
+++ b/docs/overview_usecases.rst
@@ -1,6 +1,6 @@
+Overview
+~~~~~~~~
 
-Architecture overview
----------------------
 libEnsemble is a Python library to coordinate the concurrent evaluation of
 dynamic ensembles of calculations. libEnsemble uses a manager to allocate work to
 various workers. A libEnsemble worker is the smallest indivisible unit to

From 0c6a3a6c0f98f0bea1f66c8da51b7c6a3933a76e Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 13 Nov 2019 16:43:54 -0600
Subject: [PATCH 483/644] removing table complaints

---
 README.rst                  |   3 +-
 docs/deps.rst               | 182 ++++++++++++++++++++++++++++++++++++
 docs/introduction_latex.rst |  22 +++++
 docs/known_issues.rst       |  24 +++--
 4 files changed, 219 insertions(+), 12 deletions(-)
 create mode 100644 docs/deps.rst
 create mode 100644 docs/introduction_latex.rst

diff --git a/README.rst b/README.rst
index c3232d617..a8b092d75 100644
--- a/README.rst
+++ b/README.rst
@@ -18,13 +18,12 @@
    :alt: Documentation Status
 
 |
+.. after_badges_rst_tag
 
 ===========================
 Introduction to libEnsemble
 ===========================
 
-.. after_badges_rst_tag
-
 libEnsemble is a Python library to coordinate the concurrent evaluation of
 dynamic ensembles of calculations. The library is developed to use massively
 parallel resources to accelerate the solution of design, decision, and
diff --git a/docs/deps.rst b/docs/deps.rst
new file mode 100644
index 000000000..cac04e759
--- /dev/null
+++ b/docs/deps.rst
@@ -0,0 +1,182 @@
+Dependencies
+~~~~~~~~~~~~
+
+Required dependencies:
+
+* Python_ 3.5 or above.
+* NumPy_
+
+For libEnsemble running with the mpi4py parallelism:
+
+* A functional MPI 1.x/2.x/3.x implementation, such as MPICH_, built with shared/dynamic libraries.
+* mpi4py_ v2.0.0 or above
+
+Optional dependency:
+
+* Balsam_
+
+From v0.2.0, libEnsemble has the option of using the Balsam job manager. This
+is required for running libEnsemble on the compute nodes of some supercomputing
+platforms (e.g., Cray XC40); platforms that do not support launching jobs from
+compute nodes. Note that as of v0.5.0, libEnsemble can also be run on the
+launch nodes using multiprocessing.
+
+The example sim and gen functions and tests require the following dependencies:
+
+* SciPy_
+* petsc4py_
+* PETSc_ - This can optionally be installed by pip along with petsc4py
+* NLopt_ - Installed with `shared libraries enabled`_.
+
+PETSc and NLopt must be built with shared libraries enabled and present in
+``sys.path`` (e.g., via setting the ``PYTHONPATH`` environment variable). NLopt
+should produce a file ``nlopt.py`` if Python is found on the system. NLopt may also
+require SWIG_ to be installed on certain systems.
+
+Installation
+~~~~~~~~~~~~
+
+Use pip to install libEnsemble and its dependencies::
+
+    pip install libensemble
+
+libEnsemble is also available in the Spack_ distribution. It can be installed from Spack with::
+
+    spack install py-libensemble
+
+The tests and examples can be accessed in the GitHub_ repository.
+If necessary, you may install all optional dependencies (listed above) at once with::
+
+    pip install libensemble[extras]
+
+A tarball_ of the most recent release is also available.
+
+Testing
+~~~~~~~
+
+The provided test suite includes both unit and regression tests and is run
+regularly on:
+
+* `Travis CI`_
+
+The test suite requires the mock_, pytest_, pytest-cov_, and pytest-timeout_
+packages to be installed and can be run from the libensemble/tests directory of
+the source distribution by running::
+
+    ./run-tests.sh
+
+To clean the test repositories run::
+
+    ./run-tests.sh -c
+
+Further options are available. To see a complete list of options run::
+
+    ./run-tests.sh -h
+
+If you have the source distribution, you can download (but not install) the testing
+prerequisites and run the tests with::
+
+    python setup.py test
+
+in the top-level directory containing the setup script.
+
+Coverage reports are produced separately for unit tests and regression tests
+under the relevant directories. For parallel tests, the union of all processors
+is taken. Furthermore, a combined coverage report is created at the top level,
+which can be viewed after ``run_tests.sh`` is completed at
+``libensemble/tests/cov_merge/index.html``. The Travis CI coverage results are
+available online at Coveralls_.
+
+.. note::
+    The job_controller tests can be run using the direct-launch or
+    Balsam job controllers. Balsam integration with libEnsemble is now tested
+    via ``test_balsam_hworld.py``.
+
+Basic Usage
+~~~~~~~~~~~
+
+The examples directory contains example libEnsemble calling scripts, sim
+functions, gen functions, alloc functions and job submission scripts.
+
+The default manager/worker communications mode is MPI. The user script is
+launched as::
+
+    mpiexec -np N python myscript.py
+
+where ``N`` is the number of processors. This will launch one manager and
+``N-1`` workers.
+
+If running in local mode, which uses Python's multiprocessing module, the
+``local`` comms option and the number of workers must be specified. The script
+can then be run as a regular python script::
+
+    python myscript.py
+
+When specifying these options via command line options, one may use the
+``parse_args`` function used in the regression tests, which can be found in
+`common.py`_ in the ``libensemble/tests/regression_tests`` directory.
+
+See the `user guide`_ for more information.
+
+
+Resources
+~~~~~~~~~
+
+**Support:**
+
+- The best way to receive support is to email questions to ``libEnsemble@lists.mcs.anl.gov``.
+- Communicate (and establish a private channel, if desired) at the `libEnsemble Slack page`_.
+- Join the `libEnsemble mailing list`_ for updates about new releases.
+
+**Further Information:**
+
+- Documentation is provided by ReadtheDocs_.
+- A visual overview of libEnsemble is given in this poster_.
+
+**Citation:**
+
+- Please use the following to cite libEnsemble in a publication:
+
+.. code-block:: bibtex
+
+  @techreport{libEnsemble,
+    author      = {Stephen Hudson and Jeffrey Larson and Stefan M. Wild and
+                   David Bindel and John-Luke Navarro},
+    title       = {{libEnsemble} Users Manual},
+    institution = {Argonne National Laboratory},
+    number      = {Revision 0.5.2},
+    year        = {2019},
+    url         = {https://buildmedia.readthedocs.org/media/pdf/libensemble/latest/libensemble.pdf}
+  }
+
+
+.. after_resources_rst_tag
+
+
+
+.. _Balsam: https://www.alcf.anl.gov/balsam
+.. _common.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/common.py
+.. _Coveralls: https://coveralls.io/github/Libensemble/libensemble?branch=master
+.. _GitHub: https://github.com/Libensemble/libensemble
+.. _libEnsemble mailing list: https://lists.mcs.anl.gov/mailman/listinfo/libensemble
+.. _libEnsemble Slack page: https://libensemble.slack.com
+.. _mock: https://pypi.org/project/mock
+.. _mpi4py: https://bitbucket.org/mpi4py/mpi4py
+.. _MPICH: http://www.mpich.org/
+.. _nlopt: http://ab-initio.mit.edu/wiki/index.php/NLopt
+.. _NumPy: http://www.numpy.org
+.. _petsc4py: https://bitbucket.org/petsc/petsc4py
+.. _PETSc: http://www.mcs.anl.gov/petsc
+.. _poster: https://figshare.com/articles/LibEnsemble_PETSc_TAO-_Sustaining_a_library_for_dynamic_ensemble-based_computations/7765454
+.. _pytest-cov: https://pypi.org/project/pytest-cov/
+.. _pytest-timeout: https://pypi.org/project/pytest-timeout/
+.. _pytest: https://pypi.org/project/pytest/
+.. _Python: http://www.python.org
+.. _ReadtheDocs: http://libensemble.readthedocs.org/
+.. _SciPy: http://www.scipy.org
+.. _shared libraries enabled: http://ab-initio.mit.edu/wiki/index.php/NLopt_Installation#Shared_libraries
+.. _Spack: https://spack.readthedocs.io/en/latest
+.. _SWIG: http://swig.org/
+.. _tarball: https://github.com/Libensemble/libensemble/releases/latest
+.. _Travis CI: https://travis-ci.org/Libensemble/libensemble
+.. _user guide: https://libensemble.readthedocs.io/en/latest/user_guide.html
diff --git a/docs/introduction_latex.rst b/docs/introduction_latex.rst
new file mode 100644
index 000000000..d8a0f0786
--- /dev/null
+++ b/docs/introduction_latex.rst
@@ -0,0 +1,22 @@
+.. include:: ../README.rst
+    :start-after: after_badges_rst_tag
+
+.. include:: overview_usecases.rst
+
+.. include:: deps.rst
+
+Support for HPC
+~~~~~~~~~~~~~~~
+
+libEnsemble's flexible architecture was developed with HPC System support and
+scaling as a central focus, and can perform calculations on both laptops and
+thousands of compute-nodes.
+
+.. toctree::
+    :maxdepth: 1
+    :titlesonly:
+
+    platforms/platforms_index
+    platforms/bebop
+    platforms/theta
+    platforms/example_scripts
diff --git a/docs/known_issues.rst b/docs/known_issues.rst
index 01dfd1afc..e93a8c936 100644
--- a/docs/known_issues.rst
+++ b/docs/known_issues.rst
@@ -4,14 +4,18 @@ Known Issues
 The following selection describes known bugs, errors, or other difficulties that
 may occur when using libEnsemble.
 
-* OpenMPI does not work with direct MPI job launches in mpi4py comms mode, as it
-does not support nested MPI launches (Either use local mode or Balsam job controller).
-* Local comms mode (multiprocessing) may fail if MPI is initialized before forking
-processors. This is thought to be responsible for issues combining with PETSc.
+* OpenMPI does not work with direct MPI job launches in mpi4py comms mode, as
+  it does not support nested MPI launches (Either use local mode or Balsam job
+  controller).
+* Local comms mode (multiprocessing) may fail if MPI is initialized before
+  forking processors. This is thought to be responsible for issues combining
+  with PETSc.
 * Remote detection of logical cores via LSB_HOSTS (e.g., Summit) returns number
-of physical cores as SMT info not available.
-* TCP mode does not support: 1) more than one libEnsemble call in a given script
-or 2) the auto-resources option to the job controller.
-* libEnsemble may hang on systems with matching probes not enabled on
- the native fabric, like on Intel's Truescale (TMI) fabric for
-  instance. See the :doc:`FAQ<FAQ>` for more information.
+  of physical cores as SMT info not available.
+* TCP mode does not support: 
+  1) more than one libEnsemble call in a given script or
+  2) the auto-resources option to the job controller.
+* libEnsemble may hang on systems with matching probes not enabled on the
+  native fabric, like on Intel's Truescale (TMI) fabric for instance. See the
+  :doc:`FAQ<FAQ>` for more information.
+

From fcf38b050333791c94632f6a16f818879149081e Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 13 Nov 2019 16:51:51 -0600
Subject: [PATCH 484/644] Revert "rename headings, re-add H and output info,
 update utilities and known issues, move HPC to own heading under user guide"

This reverts commit 91fbe4e5c299275a40d5ab121067c3279b330db2.
---
 docs/index.rst                     |  3 +-
 docs/introduction.rst              | 19 ++++++++--
 docs/known_issues.rst              |  8 +++++
 docs/overview_usecases.rst         | 56 ------------------------------
 docs/platforms/platforms_index.rst | 15 --------
 docs/utilities.rst                 | 35 ++-----------------
 docs/welcome.rst                   |  2 +-
 7 files changed, 28 insertions(+), 110 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index ce8078017..4e6c889ca 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -9,7 +9,7 @@
    :maxdepth: 2
    :caption: User Guide:
 
-   Quickstart<introduction>
+   Introduction<introduction>
    overview_usecases
    libe_module
    data_structures/data_structures
@@ -17,7 +17,6 @@
    job_controller/jc_index
    logging
    utilities
-   platforms/platforms_index
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/introduction.rst b/docs/introduction.rst
index e62652fa2..c45471a45 100644
--- a/docs/introduction.rst
+++ b/docs/introduction.rst
@@ -1,5 +1,18 @@
-Quickstart
-==========
-
 .. include:: ../README.rst
     :start-after: after_badges_rst_tag
+
+Support for HPC
+~~~~~~~~~~~~~~~
+
+libEnsemble's flexible architecture was developed with HPC System support and
+scaling as a central focus, and can perform calculations on both laptops and
+thousands of compute-nodes.
+
+.. toctree::
+    :maxdepth: 1
+    :titlesonly:
+
+    platforms/platforms_index
+    platforms/bebop
+    platforms/theta
+    platforms/example_scripts
diff --git a/docs/known_issues.rst b/docs/known_issues.rst
index e93a8c936..b308fce26 100644
--- a/docs/known_issues.rst
+++ b/docs/known_issues.rst
@@ -4,6 +4,7 @@ Known Issues
 The following selection describes known bugs, errors, or other difficulties that
 may occur when using libEnsemble.
 
+<<<<<<< HEAD
 * OpenMPI does not work with direct MPI job launches in mpi4py comms mode, as
   it does not support nested MPI launches (Either use local mode or Balsam job
   controller).
@@ -19,3 +20,10 @@ may occur when using libEnsemble.
   native fabric, like on Intel's Truescale (TMI) fabric for instance. See the
   :doc:`FAQ<FAQ>` for more information.
 
+=======
+* OpenMPI does not work with direct MPI job launches in mpi4py comms mode, as it does not support nested MPI launches
+  (Either use local mode or Balsam job controller).
+* Local comms mode (multiprocessing) may fail if MPI is initialized before forking processors. This is thought to be responsible for issues combining with PETSc.
+* Remote detection of logical cores via LSB_HOSTS (e.g., Summit) returns number of physical cores as SMT info not available.
+* TCP mode does not support: 1) more than one libEnsemble call in a given script or 2) the auto-resources option to the job controller.
+>>>>>>> parent of 91fbe4e... rename headings, re-add H and output info, update utilities and known issues, move HPC to own heading under user guide
diff --git a/docs/overview_usecases.rst b/docs/overview_usecases.rst
index 0945bd3a9..7ef8683ec 100644
--- a/docs/overview_usecases.rst
+++ b/docs/overview_usecases.rst
@@ -63,59 +63,3 @@ to support) and plan to have examples of:
 Naturally, combinations of these use cases are supported as well. An example of
 such a combination is using libEnsemble to solve an optimization problem that
 relies on simulations that fail frequently.
-
-The History Array
-~~~~~~~~~~~~~~~~~
-libEnsemble uses a NumPy structured array :ref:`H<datastruct-history-array>` to
-store output from ``gen_f`` and corresponding ``sim_f`` output. Similarly,
-``gen_f`` and ``sim_f`` are expected to return output in NumPy structured
-arrays. The names of the fields to be given as input to ``gen_f`` and ``sim_f``
-must be an output from ``gen_f`` or ``sim_f``. In addition to the fields output
-from ``sim_f`` and ``gen_f``, the final history returned from libEnsemble will
-include the following fields:
-
-* ``sim_id`` [int]: Each unit of work output from ``gen_f`` must have an
-  associated ``sim_id``. The generator can assign this, but users must be
-  careful to ensure points are added in order. For example, ``if alloc_f``
-  allows for two ``gen_f`` instances to be running simultaneously, ``alloc_f``
-  should ensure that both don’t generate points with the same ``sim_id``.
-
-* ``given`` [bool]: Has this ``gen_f`` output been given to a libEnsemble
-  worker to be evaluated yet?
-
-* ``given_time`` [float]: At what time (since the epoch) was this ``gen_f``
-  output given to a worker?
-
-* ``sim_worker`` [int]: libEnsemble worker that it was given to be evaluated.
-
-* ``gen_worker`` [int]: libEnsemble worker that generated this ``sim_id``
-
-* ``gen_time`` [float]: At what time (since the epoch) was this entry (or
-  collection of entries) put into ``H`` by the manager
-
-* ``returned`` [bool]: Has this worker completed the evaluation of this unit of
-  work?
-
-Output
-~~~~~~
-The history array :ref:`H<datastruct-history-array>` and
-:ref:`persis_info<datastruct-persis-info>` dictionary are returned to the user
-by libEnsemble.  If libEnsemble aborts on an exception, these structures are
-dumped to the respective files,
-
-* ``libE_history_at_abort_<sim_count>.npy``
-* ``libE_history_at_abort_<sim_count>.pickle``
-
-where ``sim_count`` is the number of points evaluated.
-
-Other libEnsemble files produced by default are:
-
-* ``libE_stats.txt``: This contains a one-line summary of all user
-  calculations.  Each calculation summary is sent by workers to the manager and
-  printed as the run progresses.
-
-* ``ensemble.log``: This is the logging output from libEnsemble. The default
-  logging is at INFO level. To gain additional diagnostics logging level can be
-  set to DEBUG.  If this file is not removed, multiple runs will append output.
-  Messages at or above level MANAGER_WARNING are also copied to stderr to alert
-  the user promptly.  For more info, see :doc:`Logging<logging>`.
diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst
index b0edc3968..3b8ac53f3 100644
--- a/docs/platforms/platforms_index.rst
+++ b/docs/platforms/platforms_index.rst
@@ -1,11 +1,6 @@
 HPC Systems
 ===========
 
-libEnsemble has been developed, supported, and tested on systems of highly varying
-scales, from laptops to thousands of compute-nodes. libEnsemble's embarrassingly
-parallel  scaling capabilities are best exemplified on the resources available
-within high-performance machines.
-
 libEnsemble's flexible architecture lends it best to two general modes of worker
 distributions across allocated compute nodes. The first mode we refer
 to as *centralized* mode, where the libEnsemble manager and worker processes
@@ -35,14 +30,4 @@ differently. On these machines, libEnsemble is run centralized on either a
 compute-node with the support of Balsam_ or on a frontend server called a MOM
 (Machine-Oriented Mini-server) node.
 
-Read more about configuring and launching libEnsemble on some HPC systems:
-
-.. toctree::
-    :maxdepth: 2
-    :titlesonly:
-
-    bebop
-    theta
-    example_scripts
-
 .. _Balsam: https://balsam.readthedocs.io/en/latest/
diff --git a/docs/utilities.rst b/docs/utilities.rst
index 87d4734cc..ce3dc5bad 100644
--- a/docs/utilities.rst
+++ b/docs/utilities.rst
@@ -4,8 +4,8 @@ Utilities
 libEnsemble features several modules and tools to assist in writing consistent
 calling scripts and user functions.
 
-Input consistency
------------------
+libE input consistency
+----------------------
 
 Users can check the formatting and consistency of ``exit_criteria`` and each
 ``specs`` dictionary with the ``check_inputs()`` function from the ``utils``
@@ -15,34 +15,3 @@ For example::
   from libensemble.libE import check_inputs
 
   check_inputs(sim_specs=my-sim_specs, gen_specs=my-gen_specs, exit_criteria=ec)
-
-Parameters as command-line arguments
-------------------------------------
-
-The ``parse_args()`` function can be used to pass common libEnsemble parameters as
-command-line arguments.
-
-In your calling script::
-
-    from libensemble.tests.regression_tests.common import parse_args
-    nworkers, is_master, libE_specs, misc_args = parse_args()
-
-From the shell, for example::
-
-    $ python calling_script --comms local --nworkers 4
-
-Usage:
-
-.. code-block:: bash
-
-    usage: test_... [-h] [--comms [{local,tcp,ssh,client,mpi}]]
-                    [--nworkers [NWORKERS]] [--workers WORKERS [WORKERS ...]]
-                    [--workerID [WORKERID]] [--server SERVER SERVER SERVER]
-                    [--pwd [PWD]] [--worker_pwd [WORKER_PWD]]
-                    [--worker_python [WORKER_PYTHON]]
-                    [--tester_args [TESTER_ARGS [TESTER_ARGS ...]]]
-
-.. note::
-    Since this utility was developed to support automatic testing, it currently
-    only accepts calling scripts prepended with ``test_`` and isn't necessarily
-    recommended for production purposes.
diff --git a/docs/welcome.rst b/docs/welcome.rst
index 47d45369e..7decf8888 100644
--- a/docs/welcome.rst
+++ b/docs/welcome.rst
@@ -27,5 +27,5 @@ libEnsemble is a library to coordinate the concurrent evaluation of dynamic ense
 
 * New to libEnsemble? Start :doc:`here<introduction>`.
 * Try out libEnsemble with a :doc:`tutorial<tutorials/local_sine_tutorial>`.
-* Go in-depth by reading the :doc:`Overview<overview_usecases>`.
+* Go in-depth by reading the :doc:`User Guide<programming_libE>`.
 * Check the :doc:`FAQ<FAQ>` for common questions and answers, errors and resolutions.

From c441f3a4573252c960b92ec6c87693e45c59a30c Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 13 Nov 2019 16:59:12 -0600
Subject: [PATCH 485/644] Leaving

---
 README.rst                  | 187 +++++++++++++++++++++++++++++++++++-
 docs/deps.rst               | 182 -----------------------------------
 docs/introduction_latex.rst |  41 +++++++-
 docs/overview_usecases.rst  |   3 -
 4 files changed, 224 insertions(+), 189 deletions(-)
 delete mode 100644 docs/deps.rst

diff --git a/README.rst b/README.rst
index a8b092d75..d5cdddde1 100644
--- a/README.rst
+++ b/README.rst
@@ -18,12 +18,13 @@
    :alt: Documentation Status
 
 |
-.. after_badges_rst_tag
 
 ===========================
 Introduction to libEnsemble
 ===========================
 
+.. after_badges_rst_tag
+
 libEnsemble is a Python library to coordinate the concurrent evaluation of
 dynamic ensembles of calculations. The library is developed to use massively
 parallel resources to accelerate the solution of design, decision, and
@@ -54,7 +55,187 @@ are portable, resilient and flexible; it also enables automatic detection of
 the nodes and cores in a system and can split up jobs automatically if resource
 data isn't supplied.
 
-.. only:: html
+.. before_dependencies_rst_tag
+
+Dependencies
+~~~~~~~~~~~~
+
+Required dependencies:
+
+* Python_ 3.5 or above.
+* NumPy_
+
+For libEnsemble running with the mpi4py parallelism:
+
+* A functional MPI 1.x/2.x/3.x implementation, such as MPICH_, built with shared/dynamic libraries.
+* mpi4py_ v2.0.0 or above
+
+Optional dependency:
+
+* Balsam_
+
+From v0.2.0, libEnsemble has the option of using the Balsam job manager. This
+is required for running libEnsemble on the compute nodes of some supercomputing
+platforms (e.g., Cray XC40); platforms that do not support launching jobs from
+compute nodes. Note that as of v0.5.0, libEnsemble can also be run on the
+launch nodes using multiprocessing.
+
+The example sim and gen functions and tests require the following dependencies:
+
+* SciPy_
+* petsc4py_
+* PETSc_ - This can optionally be installed by pip along with petsc4py
+* NLopt_ - Installed with `shared libraries enabled`_.
+
+PETSc and NLopt must be built with shared libraries enabled and present in
+``sys.path`` (e.g., via setting the ``PYTHONPATH`` environment variable). NLopt
+should produce a file ``nlopt.py`` if Python is found on the system. NLopt may also
+require SWIG_ to be installed on certain systems.
+
+Installation
+~~~~~~~~~~~~
+
+Use pip to install libEnsemble and its dependencies::
+
+    pip install libensemble
+
+libEnsemble is also available in the Spack_ distribution. It can be installed from Spack with::
+
+    spack install py-libensemble
+
+The tests and examples can be accessed in the GitHub_ repository.
+If necessary, you may install all optional dependencies (listed above) at once with::
+
+    pip install libensemble[extras]
+
+A tarball_ of the most recent release is also available.
+
+Testing
+~~~~~~~
+
+The provided test suite includes both unit and regression tests and is run
+regularly on:
+
+* `Travis CI`_
+
+The test suite requires the mock_, pytest_, pytest-cov_, and pytest-timeout_
+packages to be installed and can be run from the libensemble/tests directory of
+the source distribution by running::
+
+    ./run-tests.sh
+
+To clean the test repositories run::
+
+    ./run-tests.sh -c
+
+Further options are available. To see a complete list of options run::
+
+    ./run-tests.sh -h
+
+If you have the source distribution, you can download (but not install) the testing
+prerequisites and run the tests with::
+
+    python setup.py test
+
+in the top-level directory containing the setup script.
+
+Coverage reports are produced separately for unit tests and regression tests
+under the relevant directories. For parallel tests, the union of all processors
+is taken. Furthermore, a combined coverage report is created at the top level,
+which can be viewed after ``run_tests.sh`` is completed at
+``libensemble/tests/cov_merge/index.html``. The Travis CI coverage results are
+available online at Coveralls_.
+
+.. note::
+    The job_controller tests can be run using the direct-launch or
+    Balsam job controllers. Balsam integration with libEnsemble is now tested
+    via ``test_balsam_hworld.py``.
+
+Basic Usage
+~~~~~~~~~~~
+
+The examples directory contains example libEnsemble calling scripts, sim
+functions, gen functions, alloc functions and job submission scripts.
+
+The default manager/worker communications mode is MPI. The user script is
+launched as::
+
+    mpiexec -np N python myscript.py
+
+where ``N`` is the number of processors. This will launch one manager and
+``N-1`` workers.
+
+If running in local mode, which uses Python's multiprocessing module, the
+``local`` comms option and the number of workers must be specified. The script
+can then be run as a regular python script::
+
+    python myscript.py
+
+When specifying these options via command line options, one may use the
+``parse_args`` function used in the regression tests, which can be found in
+`common.py`_ in the ``libensemble/tests/regression_tests`` directory.
+
+See the `user guide`_ for more information.
+
+
+Resources
+~~~~~~~~~
+
+**Support:**
+
+- The best way to receive support is to email questions to ``libEnsemble@lists.mcs.anl.gov``.
+- Communicate (and establish a private channel, if desired) at the `libEnsemble Slack page`_.
+- Join the `libEnsemble mailing list`_ for updates about new releases.
+
+**Further Information:**
+
+- Documentation is provided by ReadtheDocs_.
+- A visual overview of libEnsemble is given in this poster_.
+
+**Citation:**
+
+- Please use the following to cite libEnsemble in a publication:
+
+.. code-block:: bibtex
+
+  @techreport{libEnsemble,
+    author      = {Stephen Hudson and Jeffrey Larson and Stefan M. Wild and
+                   David Bindel and John-Luke Navarro},
+    title       = {{libEnsemble} Users Manual},
+    institution = {Argonne National Laboratory},
+    number      = {Revision 0.5.2},
+    year        = {2019},
+    url         = {https://buildmedia.readthedocs.org/media/pdf/libensemble/latest/libensemble.pdf}
+  }
+
+
+.. after_resources_rst_tag
+
 
-  .. include:: deps.rst
 
+.. _Balsam: https://www.alcf.anl.gov/balsam
+.. _common.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/common.py
+.. _Coveralls: https://coveralls.io/github/Libensemble/libensemble?branch=master
+.. _GitHub: https://github.com/Libensemble/libensemble
+.. _libEnsemble mailing list: https://lists.mcs.anl.gov/mailman/listinfo/libensemble
+.. _libEnsemble Slack page: https://libensemble.slack.com
+.. _mock: https://pypi.org/project/mock
+.. _mpi4py: https://bitbucket.org/mpi4py/mpi4py
+.. _MPICH: http://www.mpich.org/
+.. _nlopt: http://ab-initio.mit.edu/wiki/index.php/NLopt
+.. _NumPy: http://www.numpy.org
+.. _petsc4py: https://bitbucket.org/petsc/petsc4py
+.. _PETSc: http://www.mcs.anl.gov/petsc
+.. _poster: https://figshare.com/articles/LibEnsemble_PETSc_TAO-_Sustaining_a_library_for_dynamic_ensemble-based_computations/7765454
+.. _pytest-cov: https://pypi.org/project/pytest-cov/
+.. _pytest-timeout: https://pypi.org/project/pytest-timeout/
+.. _pytest: https://pypi.org/project/pytest/
+.. _Python: http://www.python.org
+.. _ReadtheDocs: http://libensemble.readthedocs.org/
+.. _SciPy: http://www.scipy.org
+.. _shared libraries enabled: http://ab-initio.mit.edu/wiki/index.php/NLopt_Installation#Shared_libraries
+.. _Spack: https://spack.readthedocs.io/en/latest
+.. _SWIG: http://swig.org/
+.. _tarball: https://github.com/Libensemble/libensemble/releases/latest
+.. _Travis CI: https://travis-ci.org/Libensemble/libensemble
+.. _user guide: https://libensemble.readthedocs.io/en/latest/user_guide.html
diff --git a/docs/deps.rst b/docs/deps.rst
deleted file mode 100644
index cac04e759..000000000
--- a/docs/deps.rst
+++ /dev/null
@@ -1,182 +0,0 @@
-Dependencies
-~~~~~~~~~~~~
-
-Required dependencies:
-
-* Python_ 3.5 or above.
-* NumPy_
-
-For libEnsemble running with the mpi4py parallelism:
-
-* A functional MPI 1.x/2.x/3.x implementation, such as MPICH_, built with shared/dynamic libraries.
-* mpi4py_ v2.0.0 or above
-
-Optional dependency:
-
-* Balsam_
-
-From v0.2.0, libEnsemble has the option of using the Balsam job manager. This
-is required for running libEnsemble on the compute nodes of some supercomputing
-platforms (e.g., Cray XC40); platforms that do not support launching jobs from
-compute nodes. Note that as of v0.5.0, libEnsemble can also be run on the
-launch nodes using multiprocessing.
-
-The example sim and gen functions and tests require the following dependencies:
-
-* SciPy_
-* petsc4py_
-* PETSc_ - This can optionally be installed by pip along with petsc4py
-* NLopt_ - Installed with `shared libraries enabled`_.
-
-PETSc and NLopt must be built with shared libraries enabled and present in
-``sys.path`` (e.g., via setting the ``PYTHONPATH`` environment variable). NLopt
-should produce a file ``nlopt.py`` if Python is found on the system. NLopt may also
-require SWIG_ to be installed on certain systems.
-
-Installation
-~~~~~~~~~~~~
-
-Use pip to install libEnsemble and its dependencies::
-
-    pip install libensemble
-
-libEnsemble is also available in the Spack_ distribution. It can be installed from Spack with::
-
-    spack install py-libensemble
-
-The tests and examples can be accessed in the GitHub_ repository.
-If necessary, you may install all optional dependencies (listed above) at once with::
-
-    pip install libensemble[extras]
-
-A tarball_ of the most recent release is also available.
-
-Testing
-~~~~~~~
-
-The provided test suite includes both unit and regression tests and is run
-regularly on:
-
-* `Travis CI`_
-
-The test suite requires the mock_, pytest_, pytest-cov_, and pytest-timeout_
-packages to be installed and can be run from the libensemble/tests directory of
-the source distribution by running::
-
-    ./run-tests.sh
-
-To clean the test repositories run::
-
-    ./run-tests.sh -c
-
-Further options are available. To see a complete list of options run::
-
-    ./run-tests.sh -h
-
-If you have the source distribution, you can download (but not install) the testing
-prerequisites and run the tests with::
-
-    python setup.py test
-
-in the top-level directory containing the setup script.
-
-Coverage reports are produced separately for unit tests and regression tests
-under the relevant directories. For parallel tests, the union of all processors
-is taken. Furthermore, a combined coverage report is created at the top level,
-which can be viewed after ``run_tests.sh`` is completed at
-``libensemble/tests/cov_merge/index.html``. The Travis CI coverage results are
-available online at Coveralls_.
-
-.. note::
-    The job_controller tests can be run using the direct-launch or
-    Balsam job controllers. Balsam integration with libEnsemble is now tested
-    via ``test_balsam_hworld.py``.
-
-Basic Usage
-~~~~~~~~~~~
-
-The examples directory contains example libEnsemble calling scripts, sim
-functions, gen functions, alloc functions and job submission scripts.
-
-The default manager/worker communications mode is MPI. The user script is
-launched as::
-
-    mpiexec -np N python myscript.py
-
-where ``N`` is the number of processors. This will launch one manager and
-``N-1`` workers.
-
-If running in local mode, which uses Python's multiprocessing module, the
-``local`` comms option and the number of workers must be specified. The script
-can then be run as a regular python script::
-
-    python myscript.py
-
-When specifying these options via command line options, one may use the
-``parse_args`` function used in the regression tests, which can be found in
-`common.py`_ in the ``libensemble/tests/regression_tests`` directory.
-
-See the `user guide`_ for more information.
-
-
-Resources
-~~~~~~~~~
-
-**Support:**
-
-- The best way to receive support is to email questions to ``libEnsemble@lists.mcs.anl.gov``.
-- Communicate (and establish a private channel, if desired) at the `libEnsemble Slack page`_.
-- Join the `libEnsemble mailing list`_ for updates about new releases.
-
-**Further Information:**
-
-- Documentation is provided by ReadtheDocs_.
-- A visual overview of libEnsemble is given in this poster_.
-
-**Citation:**
-
-- Please use the following to cite libEnsemble in a publication:
-
-.. code-block:: bibtex
-
-  @techreport{libEnsemble,
-    author      = {Stephen Hudson and Jeffrey Larson and Stefan M. Wild and
-                   David Bindel and John-Luke Navarro},
-    title       = {{libEnsemble} Users Manual},
-    institution = {Argonne National Laboratory},
-    number      = {Revision 0.5.2},
-    year        = {2019},
-    url         = {https://buildmedia.readthedocs.org/media/pdf/libensemble/latest/libensemble.pdf}
-  }
-
-
-.. after_resources_rst_tag
-
-
-
-.. _Balsam: https://www.alcf.anl.gov/balsam
-.. _common.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/common.py
-.. _Coveralls: https://coveralls.io/github/Libensemble/libensemble?branch=master
-.. _GitHub: https://github.com/Libensemble/libensemble
-.. _libEnsemble mailing list: https://lists.mcs.anl.gov/mailman/listinfo/libensemble
-.. _libEnsemble Slack page: https://libensemble.slack.com
-.. _mock: https://pypi.org/project/mock
-.. _mpi4py: https://bitbucket.org/mpi4py/mpi4py
-.. _MPICH: http://www.mpich.org/
-.. _nlopt: http://ab-initio.mit.edu/wiki/index.php/NLopt
-.. _NumPy: http://www.numpy.org
-.. _petsc4py: https://bitbucket.org/petsc/petsc4py
-.. _PETSc: http://www.mcs.anl.gov/petsc
-.. _poster: https://figshare.com/articles/LibEnsemble_PETSc_TAO-_Sustaining_a_library_for_dynamic_ensemble-based_computations/7765454
-.. _pytest-cov: https://pypi.org/project/pytest-cov/
-.. _pytest-timeout: https://pypi.org/project/pytest-timeout/
-.. _pytest: https://pypi.org/project/pytest/
-.. _Python: http://www.python.org
-.. _ReadtheDocs: http://libensemble.readthedocs.org/
-.. _SciPy: http://www.scipy.org
-.. _shared libraries enabled: http://ab-initio.mit.edu/wiki/index.php/NLopt_Installation#Shared_libraries
-.. _Spack: https://spack.readthedocs.io/en/latest
-.. _SWIG: http://swig.org/
-.. _tarball: https://github.com/Libensemble/libensemble/releases/latest
-.. _Travis CI: https://travis-ci.org/Libensemble/libensemble
-.. _user guide: https://libensemble.readthedocs.io/en/latest/user_guide.html
diff --git a/docs/introduction_latex.rst b/docs/introduction_latex.rst
index d8a0f0786..18145a38b 100644
--- a/docs/introduction_latex.rst
+++ b/docs/introduction_latex.rst
@@ -1,9 +1,20 @@
+==========
+INTROLATEX
+==========
+
 .. include:: ../README.rst
     :start-after: after_badges_rst_tag
+    :end-before: before_dependencies_rst_tag
 
+Overview
+========
 .. include:: overview_usecases.rst
 
-.. include:: deps.rst
+Further
+=======
+.. include:: ../README.rst
+    :start-after: before_dependencies_rst_tag
+    :end-before: after_resources_rst_tag
 
 Support for HPC
 ~~~~~~~~~~~~~~~
@@ -20,3 +31,31 @@ thousands of compute-nodes.
     platforms/bebop
     platforms/theta
     platforms/example_scripts
+
+
+.. _Balsam: https://www.alcf.anl.gov/balsam
+.. _common.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/common.py
+.. _Coveralls: https://coveralls.io/github/Libensemble/libensemble?branch=master
+.. _GitHub: https://github.com/Libensemble/libensemble
+.. _libEnsemble mailing list: https://lists.mcs.anl.gov/mailman/listinfo/libensemble
+.. _libEnsemble Slack page: https://libensemble.slack.com
+.. _mock: https://pypi.org/project/mock
+.. _mpi4py: https://bitbucket.org/mpi4py/mpi4py
+.. _MPICH: http://www.mpich.org/
+.. _nlopt: http://ab-initio.mit.edu/wiki/index.php/NLopt
+.. _NumPy: http://www.numpy.org
+.. _petsc4py: https://bitbucket.org/petsc/petsc4py
+.. _PETSc: http://www.mcs.anl.gov/petsc
+.. _poster: https://figshare.com/articles/LibEnsemble_PETSc_TAO-_Sustaining_a_library_for_dynamic_ensemble-based_computations/7765454
+.. _pytest-cov: https://pypi.org/project/pytest-cov/
+.. _pytest-timeout: https://pypi.org/project/pytest-timeout/
+.. _pytest: https://pypi.org/project/pytest/
+.. _Python: http://www.python.org
+.. _ReadtheDocs: http://libensemble.readthedocs.org/
+.. _SciPy: http://www.scipy.org
+.. _shared libraries enabled: http://ab-initio.mit.edu/wiki/index.php/NLopt_Installation#Shared_libraries
+.. _Spack: https://spack.readthedocs.io/en/latest
+.. _SWIG: http://swig.org/
+.. _tarball: https://github.com/Libensemble/libensemble/releases/latest
+.. _Travis CI: https://travis-ci.org/Libensemble/libensemble
+.. _user guide: https://libensemble.readthedocs.io/en/latest/user_guide.html
diff --git a/docs/overview_usecases.rst b/docs/overview_usecases.rst
index 0945bd3a9..0af016346 100644
--- a/docs/overview_usecases.rst
+++ b/docs/overview_usecases.rst
@@ -1,6 +1,3 @@
-Overview
-~~~~~~~~
-
 libEnsemble is a Python library to coordinate the concurrent evaluation of
 dynamic ensembles of calculations. libEnsemble uses a manager to allocate work to
 various workers. A libEnsemble worker is the smallest indivisible unit to

From 1b2875854664409ee6bc3cb6c3e5a8a99be90e73 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 13 Nov 2019 19:31:52 -0600
Subject: [PATCH 486/644] Minor treaks to theta guide

---
 docs/platforms/theta.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index 95da5a6fd..b1689775c 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -6,8 +6,8 @@ Theta_ is a Cray XC40 system based on the second-generation Intel
 Xeon Phi processor, available within ALCF_ at Argonne National Laboratory.
 
 Theta features three tiers of nodes: login, MOM (Machine-Oriented Mini-server),
-and compute nodes. Users on login nodes submit batch runs to the MOM nodes.
-MOM nodes execute user batch-scripts to run on the compute nodes.
+and compute nodes. Users on login nodes submit batch jobs to the MOM nodes.
+MOM nodes execute user batch-scripts to run on the compute nodes via ``aprun``.
 
 Configuring Python
 ------------------
@@ -119,7 +119,7 @@ Interactive Runs
 Users can run interactively with ``qsub`` by specifying the ``-I`` flag, similarly
 to the following::
 
-    $ qsub -A [project] -n 128 -q default -t 120 -I
+    $ qsub -A [project] -n 8 -q debug-cache-quad -t 60 -I
 
 This will place the user on a MOM node. Then, to launch MPI jobs to the compute
 nodes use ``aprun`` where you would use ``mpirun``.
@@ -196,7 +196,7 @@ Here is an example Balsam submission script:
     #COBALT -O libE_test
     #COBALT -n 128
     #COBALT -q default
-    ##COBALT -A [project]
+    #COBALT -A [project]
 
     # Name of calling script
     export EXE=calling_script.py

From fbdbe7e2f982719b2f9ed8a762208a78cade8d6b Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 13 Nov 2019 19:37:03 -0600
Subject: [PATCH 487/644] Add Summit guide

---
 docs/platforms/platforms_index.rst |   1 +
 docs/platforms/summit.rst          | 138 +++++++++++++++++++++++++++++
 2 files changed, 139 insertions(+)
 create mode 100644 docs/platforms/summit.rst

diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst
index 3716ebf47..fccb66075 100644
--- a/docs/platforms/platforms_index.rst
+++ b/docs/platforms/platforms_index.rst
@@ -58,6 +58,7 @@ Read more about configuring and launching libEnsemble on some HPC systems:
 
     bebop
     theta
+    summit
     example_scripts
 
 
diff --git a/docs/platforms/summit.rst b/docs/platforms/summit.rst
new file mode 100644
index 000000000..6108b1c73
--- /dev/null
+++ b/docs/platforms/summit.rst
@@ -0,0 +1,138 @@
+======
+Summit
+======
+
+Summit_ is an IBM AC922 system located at the Oak Ridge Leadership Computing Facility. 
+Each of the approximately 4,600 compute nodes on Summit contains two IBM POWER9 processors and six NVIDIA Volta V100 accelerators.
+
+Summit features three tiers of nodes: login, launch, and compute nodes.
+Users on login nodes submit batch runs to the launch nodes.
+Launch nodes execute user batch-scripts to run on the compute nodes via ``jsrun``.
+
+Configuring Python
+------------------
+
+Begin by loading the Python 3 Anaconda module::
+
+    $ module load python
+
+You can now create your own custom Conda_ environment::
+
+    conda create --name myenv python=3.7
+    
+Now activate environment::
+
+    export PYTHONNOUSERSITE=1 # Make sure get python from conda env
+    . activate myenv
+  
+If you are installing any packages with extensions, ensure the correct compiler module
+is loaded. If using mpi4py_, this must be installed from source, referencing the compiler.
+At time of writing, mpi4py must be built with gcc::
+
+    module load gcc
+
+With your environment activated::
+
+    CC=mpicc MPICC=mpicc pip install mpi4py --no-binary mpi4py
+
+
+Installing libEnsemble
+----------------------
+
+Obtaining libEnsemble is now as simple as ``pip install libensemble``.
+Your prompt should be similar to the following line:
+
+.. code-block:: console
+
+    (my_env) user@login5:~$ pip install libensemble
+
+.. note::
+    If you encounter pip errors, run ``python -m pip install --upgrade pip`` first
+            
+
+Job Submission
+--------------
+
+Summit uses LSF_ for job management and submission. For libEnsemble, the most
+important command is ``bsub``, for submitting batch scripts from the login nodes
+to execute on the Launch nodes.
+
+It is recommended to run libEnsemble on the Launch nodes (assuming workers are submitting
+MPI jobs) using ``local`` comm mode (multiprocessing). In the future, Balsam may be used
+to run libEnsemble on compute nodes.
+
+Interactive Runs
+^^^^^^^^^^^^^^^^
+
+Users can run interactively with ``bsub`` by specifying the ``-Is`` flag, similarly
+to the following::
+
+    $ bsub -W 30 -P [project] -nnodes 8 -Is
+
+This will place the user on a launch node. Then, to launch MPI jobs to the compute
+nodes use ``jsrun`` where you would use ``mpirun``.
+
+.. note::
+    You will need to re-activate your conda virtual environment.
+
+Batch Runs
+^^^^^^^^^^
+
+Batch scripts specify run-settings using ``#BSUB`` statements. The following
+simple example depicts configuring and launching libEnsemble to a launch node with
+multiprocessing. This script also assumes the user is using the ``parse_args()``
+convenience function within libEnsemble's ``/regression_tests/common.py``.
+
+.. code-block:: bash
+
+    #!/bin/bash -x
+    #BSUB -P <project code>
+    #BSUB -J libe_mproc
+    #BSUB -W 60
+    #BSUB -nnodes 128
+    #BSUB -alloc_flags "smt1"
+
+    # --- Prepare Python ---
+
+    # Load conda module and gcc.
+    module load python
+    module load gcc
+
+    # Name of Conda environment
+    export CONDA_ENV_NAME=my_env
+
+    # Activate Conda environment
+    export PYTHONNOUSERSITE=1
+    source activate $CONDA_ENV_NAME
+
+    # --- Prepare libEnsemble ---
+
+    # Name of calling script
+    export EXE=calling_script.py
+
+    # Communication Method
+    export COMMS='--comms local'
+
+    # Number of workers.
+    export NWORKERS='--nworkers 128'    
+
+    hash -r # Check no commands hashed (pip/python...)
+
+    # Launch libE
+    python $EXE $COMMS $NWORKERS > out.txt 2>&1
+
+With this saved as ``myscript.sh``, allocating, configuring, and queueing
+libEnsemble on Summit becomes::
+
+    $ bsub script myscript.sh
+
+Additional Information
+----------------------
+
+See the OCLF guides_ on for more information about Summit.
+
+.. _Summit: https://www.olcf.ornl.gov/for-users/system-user-guides/summit/
+.. _LSF: https://www.olcf.ornl.gov/wp-content/uploads/2018/12/summit_workshop_fuson.pdf
+.. _guides: https://www.olcf.ornl.gov/for-users/system-user-guides/summit/
+.. _Conda: https://conda.io/en/latest/
+.. _mpi4py: https://mpi4py.readthedocs.io/en/stable/

From 2b7750d8fdc627981d6c7bb1b16874044c3a1ea7 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 14 Nov 2019 10:46:39 -0600
Subject: [PATCH 488/644] trying to re-add sections and features removed by
 recent merge

---
 README.rst                         |  4 +--
 docs/architecture_html.rst         |  7 ++++
 docs/history_output.rst            | 55 ++++++++++++++++++++++++++++++
 docs/index.rst                     |  8 +++--
 docs/introduction.rst              | 16 ---------
 docs/known_issues.rst              | 11 +-----
 docs/platforms/platforms_index.rst | 16 +++++++++
 docs/utilities.rst                 | 36 +++++++++++++++++--
 8 files changed, 119 insertions(+), 34 deletions(-)
 create mode 100644 docs/architecture_html.rst
 create mode 100644 docs/history_output.rst

diff --git a/README.rst b/README.rst
index d5cdddde1..3ddcf59ed 100644
--- a/README.rst
+++ b/README.rst
@@ -19,12 +19,12 @@
 
 |
 
+.. after_badges_rst_tag
+
 ===========================
 Introduction to libEnsemble
 ===========================
 
-.. after_badges_rst_tag
-
 libEnsemble is a Python library to coordinate the concurrent evaluation of
 dynamic ensembles of calculations. The library is developed to use massively
 parallel resources to accelerate the solution of design, decision, and
diff --git a/docs/architecture_html.rst b/docs/architecture_html.rst
new file mode 100644
index 000000000..929173303
--- /dev/null
+++ b/docs/architecture_html.rst
@@ -0,0 +1,7 @@
+
+Understanding libEnsemble
+=========================
+
+.. include:: overview_usecases.rst
+
+.. include:: history_output.rst
diff --git a/docs/history_output.rst b/docs/history_output.rst
new file mode 100644
index 000000000..d6146fda4
--- /dev/null
+++ b/docs/history_output.rst
@@ -0,0 +1,55 @@
+The History Array
+~~~~~~~~~~~~~~~~~
+libEnsemble uses a NumPy structured array :ref:`H<datastruct-history-array>` to
+store output from ``gen_f`` and corresponding ``sim_f`` output. Similarly,
+``gen_f`` and ``sim_f`` are expected to return output in NumPy structured
+arrays. The names of the fields to be given as input to ``gen_f`` and ``sim_f``
+must be an output from ``gen_f`` or ``sim_f``. In addition to the fields output
+from ``sim_f`` and ``gen_f``, the final history returned from libEnsemble will
+include the following fields:
+
+* ``sim_id`` [int]: Each unit of work output from ``gen_f`` must have an
+  associated ``sim_id``. The generator can assign this, but users must be
+  careful to ensure points are added in order. For example, ``if alloc_f``
+  allows for two ``gen_f`` instances to be running simultaneously, ``alloc_f``
+  should ensure that both don’t generate points with the same ``sim_id``.
+
+* ``given`` [bool]: Has this ``gen_f`` output been given to a libEnsemble
+  worker to be evaluated yet?
+
+* ``given_time`` [float]: At what time (since the epoch) was this ``gen_f``
+  output given to a worker?
+
+* ``sim_worker`` [int]: libEnsemble worker that it was given to be evaluated.
+
+* ``gen_worker`` [int]: libEnsemble worker that generated this ``sim_id``
+
+* ``gen_time`` [float]: At what time (since the epoch) was this entry (or
+  collection of entries) put into ``H`` by the manager
+
+* ``returned`` [bool]: Has this worker completed the evaluation of this unit of
+  work?
+
+Output
+~~~~~~
+The history array :ref:`H<datastruct-history-array>` and
+:ref:`persis_info<datastruct-persis-info>` dictionary are returned to the user
+by libEnsemble.  If libEnsemble aborts on an exception, these structures are
+dumped to the respective files,
+
+* ``libE_history_at_abort_<sim_count>.npy``
+* ``libE_history_at_abort_<sim_count>.pickle``
+
+where ``sim_count`` is the number of points evaluated.
+
+Other libEnsemble files produced by default are:
+
+* ``libE_stats.txt``: This contains a one-line summary of all user
+  calculations.  Each calculation summary is sent by workers to the manager and
+  printed as the run progresses.
+
+* ``ensemble.log``: This is the logging output from libEnsemble. The default
+  logging is at INFO level. To gain additional diagnostics logging level can be
+  set to DEBUG.  If this file is not removed, multiple runs will append output.
+  Messages at or above level MANAGER_WARNING are also copied to stderr to alert
+  the user promptly.  For more info, see :doc:`Logging<logging>`.
diff --git a/docs/index.rst b/docs/index.rst
index 4e6c889ca..bc747e79d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -9,14 +9,15 @@
    :maxdepth: 2
    :caption: User Guide:
 
-   Introduction<introduction>
-   overview_usecases
+   Quickstart<introduction>
+   architecture_html
    libe_module
    data_structures/data_structures
    user_funcs
    job_controller/jc_index
    logging
    utilities
+   platforms/platforms_index
 
 .. toctree::
    :maxdepth: 2
@@ -29,9 +30,10 @@
    :caption: Additional Reference:
 
    FAQ
+   known_issues
    release_notes
    contributing
-   known_issues
+
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/introduction.rst b/docs/introduction.rst
index c45471a45..0152356dc 100644
--- a/docs/introduction.rst
+++ b/docs/introduction.rst
@@ -1,18 +1,2 @@
 .. include:: ../README.rst
     :start-after: after_badges_rst_tag
-
-Support for HPC
-~~~~~~~~~~~~~~~
-
-libEnsemble's flexible architecture was developed with HPC System support and
-scaling as a central focus, and can perform calculations on both laptops and
-thousands of compute-nodes.
-
-.. toctree::
-    :maxdepth: 1
-    :titlesonly:
-
-    platforms/platforms_index
-    platforms/bebop
-    platforms/theta
-    platforms/example_scripts
diff --git a/docs/known_issues.rst b/docs/known_issues.rst
index b308fce26..caf187767 100644
--- a/docs/known_issues.rst
+++ b/docs/known_issues.rst
@@ -4,7 +4,6 @@ Known Issues
 The following selection describes known bugs, errors, or other difficulties that
 may occur when using libEnsemble.
 
-<<<<<<< HEAD
 * OpenMPI does not work with direct MPI job launches in mpi4py comms mode, as
   it does not support nested MPI launches (Either use local mode or Balsam job
   controller).
@@ -13,17 +12,9 @@ may occur when using libEnsemble.
   with PETSc.
 * Remote detection of logical cores via LSB_HOSTS (e.g., Summit) returns number
   of physical cores as SMT info not available.
-* TCP mode does not support: 
+* TCP mode does not support:
   1) more than one libEnsemble call in a given script or
   2) the auto-resources option to the job controller.
 * libEnsemble may hang on systems with matching probes not enabled on the
   native fabric, like on Intel's Truescale (TMI) fabric for instance. See the
   :doc:`FAQ<FAQ>` for more information.
-
-=======
-* OpenMPI does not work with direct MPI job launches in mpi4py comms mode, as it does not support nested MPI launches
-  (Either use local mode or Balsam job controller).
-* Local comms mode (multiprocessing) may fail if MPI is initialized before forking processors. This is thought to be responsible for issues combining with PETSc.
-* Remote detection of logical cores via LSB_HOSTS (e.g., Summit) returns number of physical cores as SMT info not available.
-* TCP mode does not support: 1) more than one libEnsemble call in a given script or 2) the auto-resources option to the job controller.
->>>>>>> parent of 91fbe4e... rename headings, re-add H and output info, update utilities and known issues, move HPC to own heading under user guide
diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst
index 3b8ac53f3..2cfd4bde6 100644
--- a/docs/platforms/platforms_index.rst
+++ b/docs/platforms/platforms_index.rst
@@ -1,6 +1,11 @@
 HPC Systems
 ===========
 
+libEnsemble has been developed, supported, and tested on systems of highly varying
+scales, from laptops to thousands of compute-nodes. libEnsemble's embarrassingly
+parallel  scaling capabilities are best exemplified on the resources available
+within high-performance machines.
+
 libEnsemble's flexible architecture lends it best to two general modes of worker
 distributions across allocated compute nodes. The first mode we refer
 to as *centralized* mode, where the libEnsemble manager and worker processes
@@ -30,4 +35,15 @@ differently. On these machines, libEnsemble is run centralized on either a
 compute-node with the support of Balsam_ or on a frontend server called a MOM
 (Machine-Oriented Mini-server) node.
 
+Read more about configuring and launching libEnsemble on some HPC systems:
+
+.. toctree::
+    :maxdepth: 2
+    :titlesonly:
+
+    bebop
+    theta
+    example_scripts
+
+
 .. _Balsam: https://balsam.readthedocs.io/en/latest/
diff --git a/docs/utilities.rst b/docs/utilities.rst
index ce3dc5bad..bd8a44529 100644
--- a/docs/utilities.rst
+++ b/docs/utilities.rst
@@ -4,8 +4,8 @@ Utilities
 libEnsemble features several modules and tools to assist in writing consistent
 calling scripts and user functions.
 
-libE input consistency
-----------------------
+Input consistency
+-----------------
 
 Users can check the formatting and consistency of ``exit_criteria`` and each
 ``specs`` dictionary with the ``check_inputs()`` function from the ``utils``
@@ -13,5 +13,35 @@ module. Provide any combination of these data structures as keyword arguments.
 For example::
 
   from libensemble.libE import check_inputs
-
   check_inputs(sim_specs=my-sim_specs, gen_specs=my-gen_specs, exit_criteria=ec)
+
+Parameters as command-line arguments
+------------------------------------
+
+The ``parse_args()`` function can be used to pass common libEnsemble parameters as
+command-line arguments.
+
+In your calling script::
+
+    from libensemble.tests.regression_tests.common import parse_args
+    nworkers, is_master, libE_specs, misc_args = parse_args()
+
+From the shell, for example::
+
+    $ python calling_script --comms local --nworkers 4
+
+Usage:
+
+.. code-block:: bash
+
+    usage: test_... [-h] [--comms [{local,tcp,ssh,client,mpi}]]
+                    [--nworkers [NWORKERS]] [--workers WORKERS [WORKERS ...]]
+                    [--workerID [WORKERID]] [--server SERVER SERVER SERVER]
+                    [--pwd [PWD]] [--worker_pwd [WORKER_PWD]]
+                    [--worker_python [WORKER_PYTHON]]
+                    [--tester_args [TESTER_ARGS [TESTER_ARGS ...]]]
+
+.. note::
+    Since this utility was developed to support automatic testing,
+    it currently only accepts calling scripts prepended with ``test_``
+    and isn't necessarily recommended for production purposes.

From b0083ea46fc9cdb44187899ce41bb32ee9364d26 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 14 Nov 2019 11:54:58 -0600
Subject: [PATCH 489/644] Harmony?

---
 docs/introduction_latex.rst  | 32 +++++++++-----------------------
 docs/latex_index.rst         |  2 +-
 docs/libe_module.rst         |  6 ------
 docs/overview_usecases.rst   |  6 ++++++
 docs/platforms/platforms.rst |  7 -------
 docs/programming_libE.rst    | 25 +------------------------
 6 files changed, 17 insertions(+), 61 deletions(-)
 delete mode 100644 docs/libe_module.rst
 delete mode 100644 docs/platforms/platforms.rst

diff --git a/docs/introduction_latex.rst b/docs/introduction_latex.rst
index 18145a38b..e4ad2f94b 100644
--- a/docs/introduction_latex.rst
+++ b/docs/introduction_latex.rst
@@ -1,7 +1,3 @@
-==========
-INTROLATEX
-==========
-
 .. include:: ../README.rst
     :start-after: after_badges_rst_tag
     :end-before: before_dependencies_rst_tag
@@ -9,30 +5,20 @@ INTROLATEX
 Overview
 ========
 .. include:: overview_usecases.rst
+    :start-after: begin_overview_rst_tag
+    :end-before: Example Use Cases 
+
+Example Use Cases
+=================
+.. include:: overview_usecases.rst
+    :start-after: begin_usecases_rst_tag
 
-Further
-=======
+Further Information
+===================
 .. include:: ../README.rst
     :start-after: before_dependencies_rst_tag
     :end-before: after_resources_rst_tag
 
-Support for HPC
-~~~~~~~~~~~~~~~
-
-libEnsemble's flexible architecture was developed with HPC System support and
-scaling as a central focus, and can perform calculations on both laptops and
-thousands of compute-nodes.
-
-.. toctree::
-    :maxdepth: 1
-    :titlesonly:
-
-    platforms/platforms_index
-    platforms/bebop
-    platforms/theta
-    platforms/example_scripts
-
-
 .. _Balsam: https://www.alcf.anl.gov/balsam
 .. _common.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/common.py
 .. _Coveralls: https://coveralls.io/github/Libensemble/libensemble?branch=master
diff --git a/docs/latex_index.rst b/docs/latex_index.rst
index 771299c70..8ca9be61b 100644
--- a/docs/latex_index.rst
+++ b/docs/latex_index.rst
@@ -7,6 +7,6 @@
 
    Introduction<introduction_latex>
    programming_libE
-   platforms/platforms
+   platforms/platforms_index
    dev_info
    appendix
diff --git a/docs/libe_module.rst b/docs/libe_module.rst
deleted file mode 100644
index ddbacb128..000000000
--- a/docs/libe_module.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-Main libEnsemble module
-=======================
-
-.. automodule:: libE
-  :members:
-  :no-undoc-members:
diff --git a/docs/overview_usecases.rst b/docs/overview_usecases.rst
index 6b6a04400..24ea1dfc2 100644
--- a/docs/overview_usecases.rst
+++ b/docs/overview_usecases.rst
@@ -1,3 +1,7 @@
+Overview
+~~~~~~~~
+.. begin_overview_rst_tag
+
 libEnsemble is a Python library to coordinate the concurrent evaluation of
 dynamic ensembles of calculations. libEnsemble uses a manager to allocate work to
 various workers. A libEnsemble worker is the smallest indivisible unit to
@@ -20,6 +24,8 @@ no ``gen_f`` output to give, the worker is told to call ``gen_f``.
 
 Example Use Cases
 ~~~~~~~~~~~~~~~~~
+.. begin_usecases_rst_tag
+
 Below are some expected libEnsemble use cases that we support (or are working
 to support) and plan to have examples of:
 
diff --git a/docs/platforms/platforms.rst b/docs/platforms/platforms.rst
deleted file mode 100644
index bb0295a50..000000000
--- a/docs/platforms/platforms.rst
+++ /dev/null
@@ -1,7 +0,0 @@
-Platforms
----------
-
-.. toctree::
-
-   theta
-   bebop
diff --git a/docs/programming_libE.rst b/docs/programming_libE.rst
index 012eea031..175d9bfee 100644
--- a/docs/programming_libE.rst
+++ b/docs/programming_libE.rst
@@ -5,31 +5,8 @@ Programming with libEnsemble
   :members:
   :no-undoc-members:
 
-**libEnsemble Output**
-
-The history array :ref:`H<datastruct-history-array>` and
-:ref:`persis_info<datastruct-persis-info>` dictionary are returned to the user
-by libEnsemble.  If libEnsemble aborts on an exception, these structures are
-dumped to the respective files,
-
-* ``libE_history_at_abort_<sim_count>.npy``
-* ``libE_history_at_abort_<sim_count>.pickle``
-
-where ``<sim_count>`` is the number of points evaluated.
-
-Other libEnsemble files produced by default are:
-
-* ``libE_stats.txt``: Contains a one-line summary of all user
-  calculations.  Each calculation summary is sent by workers to the manager and
-  printed as the run progresses.
-
-* ``ensemble.log``: The logging output from libEnsemble. The default
-  logging is at INFO level. To gain additional diagnostics logging level can be
-  set to DEBUG.  If this file is not removed, multiple runs will append output.
-  Messages at or above level MANAGER_WARNING are also copied to stderr to alert
-  the user promptly.  For more info, see :doc:`Logging<logging>`.
-
 .. toctree::
+   history_output
    data_structures/data_structures
    user_funcs
    job_controller/jc_index

From dbaf9fa6c7efc66a1dd3a98ec969f811173beed9 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 14 Nov 2019 11:59:43 -0600
Subject: [PATCH 490/644] preparing for merge

---
 docs/conf.py                       | 3 ++-
 docs/index.rst                     | 6 +-----
 docs/libe_module.rst               | 8 ++------
 docs/platforms/platforms_index.rst | 4 ++--
 docs/programming_libE.rst          | 2 ++
 5 files changed, 9 insertions(+), 14 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 575bb506c..1e10253f7 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -138,7 +138,8 @@ def __getattr__(cls, name):
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {'navigation_depth': 2,
+                      'collapse_navigation': False}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
diff --git a/docs/index.rst b/docs/index.rst
index bc747e79d..7b82d8177 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -11,11 +11,7 @@
 
    Quickstart<introduction>
    architecture_html
-   libe_module
-   data_structures/data_structures
-   user_funcs
-   job_controller/jc_index
-   logging
+   programming_libE
    utilities
    platforms/platforms_index
 
diff --git a/docs/libe_module.rst b/docs/libe_module.rst
index ddbacb128..a0c5c9e51 100644
--- a/docs/libe_module.rst
+++ b/docs/libe_module.rst
@@ -1,6 +1,2 @@
-Main libEnsemble module
-=======================
-
-.. automodule:: libE
-  :members:
-  :no-undoc-members:
+.. include:: programming_libE
+    :end-before: end-before-toctree_rst_tag
diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst
index 2cfd4bde6..e4d4bda23 100644
--- a/docs/platforms/platforms_index.rst
+++ b/docs/platforms/platforms_index.rst
@@ -1,5 +1,5 @@
-HPC Systems
-===========
+Running on HPC Systems
+======================
 
 libEnsemble has been developed, supported, and tested on systems of highly varying
 scales, from laptops to thousands of compute-nodes. libEnsemble's embarrassingly
diff --git a/docs/programming_libE.rst b/docs/programming_libE.rst
index 012eea031..d61415d35 100644
--- a/docs/programming_libE.rst
+++ b/docs/programming_libE.rst
@@ -29,6 +29,8 @@ Other libEnsemble files produced by default are:
   Messages at or above level MANAGER_WARNING are also copied to stderr to alert
   the user promptly.  For more info, see :doc:`Logging<logging>`.
 
+.. end-before-toctree_rst_tag
+
 .. toctree::
    data_structures/data_structures
    user_funcs

From a1275d41a92ffbd35523781e798e7b8a2b7ede8d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 14 Nov 2019 12:02:12 -0600
Subject: [PATCH 491/644] Flake8

---
 examples/tutorials/tutorial_calling.py     | 8 ++++----
 examples/tutorials/tutorial_calling_mpi.py | 8 ++++----
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/examples/tutorials/tutorial_calling.py b/examples/tutorials/tutorial_calling.py
index 38d87866f..6681f20db 100644
--- a/examples/tutorials/tutorial_calling.py
+++ b/examples/tutorials/tutorial_calling.py
@@ -9,10 +9,10 @@
 
 gen_specs = {'gen_f': gen_random_sample,        # Our generator function
              'out': [('x', float, (1,))],       # gen_f output (name, type, size).
-             'user': { 'lower': np.array([-3]), # random sampling lower bound
-                       'upper': np.array([3]),  # random sampling upper bound
-                       'gen_batch_size': 5      # number of values gen_f will generate per call
-                     }
+             'user': {'lower': np.array([-3]),  # random sampling lower bound
+                      'upper': np.array([3]),   # random sampling upper bound
+                      'gen_batch_size': 5       # number of values gen_f will generate per call
+                      }
              }
 
 sim_specs = {'sim_f': sim_find_sine,            # Our simulator function
diff --git a/examples/tutorials/tutorial_calling_mpi.py b/examples/tutorials/tutorial_calling_mpi.py
index 99d5e628a..82805aee6 100644
--- a/examples/tutorials/tutorial_calling_mpi.py
+++ b/examples/tutorials/tutorial_calling_mpi.py
@@ -13,10 +13,10 @@
 
 gen_specs = {'gen_f': gen_random_sample,        # Our generator function
              'out': [('x', float, (1,))],       # gen_f output (name, type, size).
-             'user': { 'lower': np.array([-3]), # random sampling lower bound
-                       'upper': np.array([3]),  # random sampling upper bound
-                       'gen_batch_size': 5      # number of values gen_f will generate per call
-                     }
+             'user': {'lower': np.array([-3]),  # random sampling lower bound
+                      'upper': np.array([3]),   # random sampling upper bound
+                      'gen_batch_size': 5       # number of values gen_f will generate per call
+                      }
              }
 
 sim_specs = {'sim_f': sim_find_sine,            # Our simulator function

From a4b75c6d6766cdee5de5fcbfff12a237c819f993 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 14 Nov 2019 12:03:09 -0600
Subject: [PATCH 492/644] Whitespace

---
 README.rst                               | 4 ----
 docs/data_structures/data_structures.rst | 1 -
 docs/index.rst                           | 2 --
 docs/platforms/platforms_index.rst       | 1 -
 4 files changed, 8 deletions(-)

diff --git a/README.rst b/README.rst
index 3ddcf59ed..9d16ae55d 100644
--- a/README.rst
+++ b/README.rst
@@ -177,7 +177,6 @@ When specifying these options via command line options, one may use the
 
 See the `user guide`_ for more information.
 
-
 Resources
 ~~~~~~~~~
 
@@ -208,11 +207,8 @@ Resources
     url         = {https://buildmedia.readthedocs.org/media/pdf/libensemble/latest/libensemble.pdf}
   }
 
-
 .. after_resources_rst_tag
 
-
-
 .. _Balsam: https://www.alcf.anl.gov/balsam
 .. _common.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/common.py
 .. _Coveralls: https://coveralls.io/github/Libensemble/libensemble?branch=master
diff --git a/docs/data_structures/data_structures.rst b/docs/data_structures/data_structures.rst
index 1ab157e17..fff56d816 100644
--- a/docs/data_structures/data_structures.rst
+++ b/docs/data_structures/data_structures.rst
@@ -20,7 +20,6 @@ and the
 :ref:`work<datastruct-history-array>` dictionary produced by the allocation
 function.
 
-
 .. toctree::
    :maxdepth: 3
    :caption: libEnsemble Data Structures:
diff --git a/docs/index.rst b/docs/index.rst
index 7b82d8177..755b15c98 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -30,7 +30,6 @@
    release_notes
    contributing
 
-
 .. toctree::
    :maxdepth: 2
    :caption: Developer Guide:
@@ -38,7 +37,6 @@
    dev_guide/release_management/release_index
    dev_guide/dev_API/developer_API
 
-
 Indices and tables
 ==================
 
diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst
index e4d4bda23..fb1b4fbac 100644
--- a/docs/platforms/platforms_index.rst
+++ b/docs/platforms/platforms_index.rst
@@ -45,5 +45,4 @@ Read more about configuring and launching libEnsemble on some HPC systems:
     theta
     example_scripts
 
-
 .. _Balsam: https://balsam.readthedocs.io/en/latest/

From af24e4776895ee0779866c07497e05f6bad7e42f Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 14 Nov 2019 12:03:22 -0600
Subject: [PATCH 493/644] Whitespace

---
 docs/architecture_html.rst | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/architecture_html.rst b/docs/architecture_html.rst
index 929173303..4809adeb7 100644
--- a/docs/architecture_html.rst
+++ b/docs/architecture_html.rst
@@ -1,4 +1,3 @@
-
 Understanding libEnsemble
 =========================
 

From 9302d21af6a052e0c71026d7ed0b5b8a2c9a4339 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 14 Nov 2019 12:04:37 -0600
Subject: [PATCH 494/644] Whitespace

---
 docs/introduction_latex.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/introduction_latex.rst b/docs/introduction_latex.rst
index e4ad2f94b..8a85f4686 100644
--- a/docs/introduction_latex.rst
+++ b/docs/introduction_latex.rst
@@ -6,7 +6,7 @@ Overview
 ========
 .. include:: overview_usecases.rst
     :start-after: begin_overview_rst_tag
-    :end-before: Example Use Cases 
+    :end-before: Example Use Cases
 
 Example Use Cases
 =================

From 8d285146bb7ca194071e973fec062fc82c33789c Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 14 Nov 2019 12:05:44 -0600
Subject: [PATCH 495/644] remove redundant info

---
 docs/architecture_html.rst | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/architecture_html.rst b/docs/architecture_html.rst
index 929173303..1192f7463 100644
--- a/docs/architecture_html.rst
+++ b/docs/architecture_html.rst
@@ -3,5 +3,3 @@ Understanding libEnsemble
 =========================
 
 .. include:: overview_usecases.rst
-
-.. include:: history_output.rst

From 16e10974ff7a9d4af85a48b2627e0560e77e6805 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 14 Nov 2019 12:07:22 -0600
Subject: [PATCH 496/644] Adding sphinxcontrib_bibtex as a dependency (for now)

---
 docs/conf.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index 1e10253f7..39ec59570 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -58,8 +58,8 @@ def __getattr__(cls, name):
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-# extensions = ['sphinxcontrib.bibtex','sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.imgconverter']
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.imgconverter']
+extensions = ['sphinxcontrib.bibtex','sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.imgconverter']
+# extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.imgconverter']
 #breathe_projects = { "libEnsemble": "../code/src/xml/" }
 #breathe_default_project = "libEnsemble"
 

From cc80ac0c0080d38bff3f48351dde9e2960073d88 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 14 Nov 2019 12:09:52 -0600
Subject: [PATCH 497/644] overview to toctree

---
 docs/architecture_html.rst | 4 ----
 docs/index.rst             | 2 +-
 docs/overview_usecases.rst | 3 +++
 3 files changed, 4 insertions(+), 5 deletions(-)
 delete mode 100644 docs/architecture_html.rst

diff --git a/docs/architecture_html.rst b/docs/architecture_html.rst
deleted file mode 100644
index 44719846d..000000000
--- a/docs/architecture_html.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-Understanding libEnsemble
-=========================
-
-.. include:: overview_usecases.rst
diff --git a/docs/index.rst b/docs/index.rst
index 755b15c98..48267e565 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -10,7 +10,7 @@
    :caption: User Guide:
 
    Quickstart<introduction>
-   architecture_html
+   overview_usecases
    programming_libE
    utilities
    platforms/platforms_index
diff --git a/docs/overview_usecases.rst b/docs/overview_usecases.rst
index 24ea1dfc2..6fdc1e69e 100644
--- a/docs/overview_usecases.rst
+++ b/docs/overview_usecases.rst
@@ -1,3 +1,6 @@
+Understanding libEnsemble
+=========================
+
 Overview
 ~~~~~~~~
 .. begin_overview_rst_tag

From 1a025edc863695dc05c82c11ca438643a1d0f5e8 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 14 Nov 2019 12:20:54 -0600
Subject: [PATCH 498/644] Adding examples to tutorials(?)

---
 docs/appendix.rst | 1 +
 docs/index.rst    | 1 +
 2 files changed, 2 insertions(+)

diff --git a/docs/appendix.rst b/docs/appendix.rst
index a99b081ef..c642ae13e 100644
--- a/docs/appendix.rst
+++ b/docs/appendix.rst
@@ -4,6 +4,7 @@ Appendices
 .. toctree::
    tutorials/tutorials
    FAQ
+   known_issues
    examples/examples_index
    release_notes
    bibliography
diff --git a/docs/index.rst b/docs/index.rst
index 48267e565..9d784d684 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -20,6 +20,7 @@
    :caption: Tutorials:
 
    tutorials/local_sine_tutorial
+   examples/examples_index
 
 .. toctree::
    :maxdepth: 2

From 28ee0fd926c0eb2684c29734df405640ef058ae9 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 14 Nov 2019 12:26:03 -0600
Subject: [PATCH 499/644] dont re-add already-gone content

---
 docs/platforms/bebop.rst | 10 ----------
 1 file changed, 10 deletions(-)

diff --git a/docs/platforms/bebop.rst b/docs/platforms/bebop.rst
index c72697025..75e1fb583 100644
--- a/docs/platforms/bebop.rst
+++ b/docs/platforms/bebop.rst
@@ -5,16 +5,6 @@ Bebop
 Bebop_ is a Cray CS400 cluster available within LCRC at Argonne National
 Laboratory, featuring both Intel Broadwell and Knights Landing compute nodes.
 
-Prerequisites
--------------
-
-An Argonne LCRC_ account is required to access Bebop. Interested users will need
-to apply for and be granted an account before continuing. To submit jobs to Bebop,
-users can charge hours to a project or their personal allocation (default).
-
-Bebop consists primarily of login and compute nodes. Users start on the login
-nodes, and schedule work for execution on the compute nodes.
-
 Configuring Python
 ------------------
 

From 24e0716ef8a135bc037d3d4e2841d28cdd112328 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 14 Nov 2019 12:39:22 -0600
Subject: [PATCH 500/644] ditto

---
 docs/platforms/theta.rst | 15 ---------------
 1 file changed, 15 deletions(-)

diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index 2c6cdfa33..95da5a6fd 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -5,21 +5,6 @@ Theta
 Theta_ is a Cray XC40 system based on the second-generation Intel
 Xeon Phi processor, available within ALCF_ at Argonne National Laboratory.
 
-Prerequisites
--------------
-
-An Argonne ALCF account is required to access Theta. Interested users will need
-to apply for and be granted an account before continuing. To submit jobs to Theta,
-users must charge their jobs to a project (specified while requesting an
-account).
-
-Theta contains numerous node-types, but libEnsemble users will mostly interact
-with login, Machine Oriented Mini-server (MOM) and compute nodes. MOM nodes execute
-user batch-scripts to run on the compute nodes.
-
-libEnsemble functions need to incorporate the libEnsemble
-:ref:`job controller<jobcontroller_index>` to perform calculations on Theta.
-
 Theta features three tiers of nodes: login, MOM (Machine-Oriented Mini-server),
 and compute nodes. Users on login nodes submit batch runs to the MOM nodes.
 MOM nodes execute user batch-scripts to run on the compute nodes.

From 3c83ad22e8ca56564d6cdbb484e5b4e40b30d1fc Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 14 Nov 2019 13:30:35 -0600
Subject: [PATCH 501/644] Debugging readthedocs

---
 .readthedocs.yml      | 16 +++++-----------
 docs/requirements.txt |  1 -
 2 files changed, 5 insertions(+), 12 deletions(-)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index f947fcee2..a3d25fee2 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -1,17 +1,11 @@
+version: 2
+
 conda:
     file: conda/environment.yml
-    environment: environment.yml
+
+sphinx:
+    configuration: docs/conf.py
 
 build:
     image: latest
 
-python:
-    version: 3.6
-    pip_install: true
-    setup_py_install: true
-    install:
-      - method: pip
-      - sphinxcontrib.bibtex
-      - sphinxcontrib-bibtex
-      - requirements: docs/requirements.txt
-    system_packages: true
\ No newline at end of file
diff --git a/docs/requirements.txt b/docs/requirements.txt
index ce15bceee..c3e8a7601 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,2 +1 @@
 sphinxcontrib.bibtex
-sphinxcontrib-bibtex
\ No newline at end of file

From 24245edb1e6eb0df7c1eae3a781b86f947e6b205 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 14 Nov 2019 13:31:48 -0600
Subject: [PATCH 502/644] Debugging readthedocs

---
 .readthedocs.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index a3d25fee2..f84aa8c26 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -1,7 +1,7 @@
 version: 2
 
 conda:
-    file: conda/environment.yml
+    environment: conda/environment.yml
 
 sphinx:
     configuration: docs/conf.py

From 4c1e46231daaf8053c006c525159fe9f49588aed Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 14 Nov 2019 13:35:58 -0600
Subject: [PATCH 503/644] Debugging readthedocs

---
 .readthedocs.yml      | 10 ++++++----
 docs/requirements.txt |  3 ++-
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index f84aa8c26..36218d02f 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -1,11 +1,13 @@
 version: 2
 
-conda:
-    environment: conda/environment.yml
-
 sphinx:
-    configuration: docs/conf.py
+  configuration: docs/conf.py
 
 build:
     image: latest
 
+python:
+    version: 3.6
+    install:
+      - requirements: docs/requirements.txt
+    system_packages: true
diff --git a/docs/requirements.txt b/docs/requirements.txt
index c3e8a7601..b6f35cbcb 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1 +1,2 @@
-sphinxcontrib.bibtex
+sphinxcontrib-bibtex
+libensemble 

From e347436452567d2865fe4228b41932a2cd91b372 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 14 Nov 2019 14:02:56 -0600
Subject: [PATCH 504/644] modify utilities docs for parse_args move

---
 docs/utilities.rst | 9 ++-------
 1 file changed, 2 insertions(+), 7 deletions(-)

diff --git a/docs/utilities.rst b/docs/utilities.rst
index bd8a44529..53f2ae749 100644
--- a/docs/utilities.rst
+++ b/docs/utilities.rst
@@ -12,7 +12,7 @@ Users can check the formatting and consistency of ``exit_criteria`` and each
 module. Provide any combination of these data structures as keyword arguments.
 For example::
 
-  from libensemble.libE import check_inputs
+  from libensemble.utils import check_inputs
   check_inputs(sim_specs=my-sim_specs, gen_specs=my-gen_specs, exit_criteria=ec)
 
 Parameters as command-line arguments
@@ -23,7 +23,7 @@ command-line arguments.
 
 In your calling script::
 
-    from libensemble.tests.regression_tests.common import parse_args
+    from libensemble.utils import parse_args
     nworkers, is_master, libE_specs, misc_args = parse_args()
 
 From the shell, for example::
@@ -40,8 +40,3 @@ Usage:
                     [--pwd [PWD]] [--worker_pwd [WORKER_PWD]]
                     [--worker_python [WORKER_PYTHON]]
                     [--tester_args [TESTER_ARGS [TESTER_ARGS ...]]]
-
-.. note::
-    Since this utility was developed to support automatic testing,
-    it currently only accepts calling scripts prepended with ``test_``
-    and isn't necessarily recommended for production purposes.

From 067ae5701a647ac8d4a3aa140a3d6dc07fc34cfe Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 14 Nov 2019 14:23:05 -0600
Subject: [PATCH 505/644] Not sure what this does, but maybe it helps

---
 libensemble/utils.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/libensemble/utils.py b/libensemble/utils.py
index 435ef1cd1..a9bced316 100644
--- a/libensemble/utils.py
+++ b/libensemble/utils.py
@@ -4,6 +4,8 @@
 
 """
 
+__all__ = ['check_inputs']
+
 import traceback
 import logging
 import numpy as np

From 469be8e04418b8ea5da59840da1194386575b41c Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 14 Nov 2019 14:39:14 -0600
Subject: [PATCH 506/644] Move many common utilities from
 regression_tests/common.py to libensemble/utils.py

---
 libensemble/tests/regression_tests/common.py  | 131 -----------------
 .../script_test_balsam_hworld.py              |   2 +-
 .../regression_tests/test_1d_sampling.py      |   2 +-
 .../test_1d_uniform_sampling_with_comm_dup.py |   2 +-
 ...mp_camel_active_persistent_worker_abort.py |   2 +-
 .../test_6-hump_camel_aposmm_LD_MMA.py        |   2 +-
 .../test_6-hump_camel_elapsed_time_abort.py   |   2 +-
 .../test_6-hump_camel_persistent_aposmm_1.py  |   2 +-
 .../test_6-hump_camel_persistent_aposmm_2.py  |   2 +-
 .../test_6-hump_camel_persistent_aposmm_3.py  |   2 +-
 .../test_6-hump_camel_persistent_aposmm_4.py  |   2 +-
 ...-hump_camel_persistent_uniform_sampling.py |   2 +-
 .../test_6-hump_camel_pregenerated_sample.py  |   2 +-
 .../test_6-hump_camel_uniform_sampling.py     |   2 +-
 ..._sampling_with_persistent_localopt_gens.py |   2 +-
 ...mel_with_different_nodes_uniform_sample.py |   2 +-
 ...test_branin_aposmm_nlopt_and_then_scipy.py |   2 +-
 .../regression_tests/test_calc_exception.py   |   2 +-
 ...t_chwirut_aposmm_one_residual_at_a_time.py |   2 +-
 .../regression_tests/test_chwirut_pounders.py |   2 +-
 .../test_chwirut_pounders_persistent.py       |   2 +-
 .../test_chwirut_pounders_splitcomm.py        |   2 +-
 .../test_chwirut_pounders_subcomm.py          |   2 +-
 ...uniform_sampling_one_residual_at_a_time.py |   2 +-
 .../tests/regression_tests/test_comms.py      |   2 +-
 .../tests/regression_tests/test_fast_alloc.py |   4 +-
 .../test_inverse_bayes_example.py             |   2 +-
 .../test_jobcontroller_hworld.py              |   2 +-
 .../tests/regression_tests/test_mpi_comms.py  |   2 +-
 .../regression_tests/test_nan_func_aposmm.py  |   2 +-
 .../test_worker_exceptions.py                 |   2 +-
 libensemble/utils.py                          | 136 ++++++++++++++++++
 32 files changed, 167 insertions(+), 162 deletions(-)

diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index 672fd362b..c5f490af9 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -5,40 +5,9 @@
 import sys
 import os
 import os.path
-import argparse
 import numpy as np
 import pickle
 
-parser = argparse.ArgumentParser(prog='test_...')
-parser.add_argument('--comms', type=str, nargs='?',
-                    choices=['local', 'tcp', 'ssh', 'client', 'mpi'],
-                    default='mpi', help='Type of communicator')
-parser.add_argument('--nworkers', type=int, nargs='?',
-                    help='Number of local forked processes')
-parser.add_argument('--workers', type=str, nargs='+',
-                    help='List of worker nodes')
-parser.add_argument('--workerID', type=int, nargs='?', help='Client worker ID')
-parser.add_argument('--server', type=str, nargs=3,
-                    help='Triple of (ip, port, authkey) used to reach manager')
-parser.add_argument('--pwd', type=str, nargs='?',
-                    help='Working directory to be used')
-parser.add_argument('--worker_pwd', type=str, nargs='?',
-                    help='Working directory on remote client')
-parser.add_argument('--worker_python', type=str, nargs='?',
-                    default=sys.executable,
-                    help='Python version on remote client')
-parser.add_argument('--tester_args', type=str, nargs='*',
-                    help='Additional arguments for use by specific testers')
-
-
-def mpi_parse_args(args):
-    "Parse arguments for MPI comms."
-    from mpi4py import MPI
-    nworkers = MPI.COMM_WORLD.Get_size()-1
-    is_master = MPI.COMM_WORLD.Get_rank() == 0
-    libE_specs = {'comm': MPI.COMM_WORLD, 'comms': 'mpi'}
-    return nworkers, is_master, libE_specs, args.tester_args
-
 
 def mpi_comm_excl(exc=[0], comm=None):
     "Exlude ranks from a communicator for MPI comms."
@@ -62,106 +31,6 @@ def mpi_comm_split(num_parts, comm=None):
     return sub_comm, sub_comm_number
 
 
-def local_parse_args(args):
-    "Parse arguments for forked processes using multiprocessing."
-    nworkers = args.nworkers or 4
-    libE_specs = {'nprocesses': nworkers, 'comms': 'local'}
-    return nworkers, True, libE_specs, args.tester_args
-
-
-def tcp_parse_args(args):
-    "Parse arguments for local TCP connections"
-    nworkers = args.nworkers or 4
-    cmd = [
-        sys.executable, sys.argv[0], "--comms", "client", "--server",
-        "{manager_ip}", "{manager_port}", "{authkey}", "--workerID",
-        "{workerID}", "--nworkers",
-        str(nworkers)]
-    libE_specs = {'nprocesses': nworkers, 'worker_cmd': cmd, 'comms': 'tcp'}
-    return nworkers, True, libE_specs, args.tester_args
-
-
-def ssh_parse_args(args):
-    "Parse arguments for SSH with reverse tunnel."
-    nworkers = len(args.workers)
-    worker_pwd = args.worker_pwd or os.getcwd()
-    script_dir, script_name = os.path.split(sys.argv[0])
-    worker_script_name = os.path.join(worker_pwd, script_name)
-    ssh = [
-        "ssh", "-R", "{tunnel_port}:localhost:{manager_port}", "{worker_ip}"]
-    cmd = [
-        args.worker_python, worker_script_name, "--comms", "client",
-        "--server", "localhost", "{tunnel_port}", "{authkey}", "--workerID",
-        "{workerID}", "--nworkers",
-        str(nworkers)]
-    cmd = " ".join(cmd)
-    cmd = "( cd {} ; {} )".format(worker_pwd, cmd)
-    ssh.append(cmd)
-    libE_specs = {'workers': args.workers,
-                  'worker_cmd': ssh,
-                  'ip': 'localhost',
-                  'comms': 'tcp'}
-    return nworkers, True, libE_specs, args.tester_args
-
-
-def client_parse_args(args):
-    "Parse arguments for a TCP client."
-    nworkers = args.nworkers or 4
-    ip, port, authkey = args.server
-    libE_specs = {'ip': ip,
-                  'port': int(port),
-                  'authkey': authkey.encode('utf-8'),
-                  'workerID': args.workerID,
-                  'nprocesses': nworkers,
-                  'comms': 'tcp'}
-    return nworkers, False, libE_specs, args.tester_args
-
-
-def parse_args():
-    "Unified parsing interface for regression test arguments"
-    args = parser.parse_args(sys.argv[1:])
-    front_ends = {
-        'mpi': mpi_parse_args,
-        'local': local_parse_args,
-        'tcp': tcp_parse_args,
-        'ssh': ssh_parse_args,
-        'client': client_parse_args}
-    if args.pwd is not None:
-        os.chdir(args.pwd)
-    return front_ends[args.comms or 'mpi'](args)
-
-
-def save_libE_output(H, persis_info, calling_file, nworkers):
-    script_name = os.path.splitext(os.path.basename(calling_file))[0]
-    short_name = script_name.split("test_", 1).pop()
-    filename = short_name + '_results_History_length=' + str(len(H)) \
-                          + '_evals=' + str(sum(H['returned'])) \
-                          + '_ranks=' + str(nworkers)
-
-    print("\n\n\nRun completed.\nSaving results to file: "+filename)
-    np.save(filename, H)
-
-    with open(filename + ".pickle", "wb") as f:
-        pickle.dump(persis_info, f)
-
-
-def per_worker_stream(persis_info, nworkers):
-    for i in range(nworkers):
-        if i in persis_info:
-            persis_info[i].update({
-                'rand_stream': np.random.RandomState(i),
-                'worker_num': i})
-        else:
-            persis_info[i] = {
-                'rand_stream': np.random.RandomState(i),
-                'worker_num': i}
-    return persis_info
-
-
-def eprint(*args, **kwargs):
-    print(*args, file=sys.stderr, **kwargs)
-
-
 def build_simfunc():
     import subprocess
 
diff --git a/libensemble/tests/regression_tests/script_test_balsam_hworld.py b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
index 6db317c1d..8f0e671b0 100644
--- a/libensemble/tests/regression_tests/script_test_balsam_hworld.py
+++ b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
@@ -11,7 +11,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.job_control_hworld import job_control_hworld as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
-from libensemble.tests.regression_tests.common import per_worker_stream
+from libensemble.util import per_worker_stream
 
 mpi4py.rc.recv_mprobe = False  # Disable matching probes
 
diff --git a/libensemble/tests/regression_tests/test_1d_sampling.py b/libensemble/tests/regression_tests/test_1d_sampling.py
index 626d08ed6..657c140bb 100644
--- a/libensemble/tests/regression_tests/test_1d_sampling.py
+++ b/libensemble/tests/regression_tests/test_1d_sampling.py
@@ -19,7 +19,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.one_d_func import one_d_example as sim_f
 from libensemble.gen_funcs.sampling import latin_hypercube_sample as gen_f
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.util import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 libE_specs['save_every_k_gens'] = 300
diff --git a/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py b/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
index 8e25f531c..f48687131 100644
--- a/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
+++ b/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
@@ -23,7 +23,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.one_d_func import one_d_example as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.util import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py b/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py
index 3b0252e99..51601673e 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py
@@ -22,7 +22,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.uniform_or_localopt import uniform_or_localopt as gen_f
 from libensemble.alloc_funcs.start_persistent_local_opt_gens import start_persistent_local_opt_gens as alloc_f
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.util import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import uniform_or_localopt_gen_out as gen_out
 
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
index 106dcd9e5..88c15d6a0 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
@@ -22,7 +22,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.alloc_funcs.fast_alloc_to_aposmm import give_sim_work_first as alloc_f
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.util import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import persis_info_1 as persis_info, aposmm_gen_out as gen_out, six_hump_camel_minima as minima
 
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py b/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
index 46e968542..28a965189 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
@@ -21,7 +21,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
 from libensemble.alloc_funcs.give_sim_work_first import give_sim_work_first
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream, eprint
+from libensemble.util import parse_args, save_libE_output, per_worker_stream, eprint
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
index b8e7a27ec..86e8a2f59 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
@@ -23,7 +23,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
 from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.util import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 from time import time
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
index f3c554ca9..365e98c12 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
@@ -23,7 +23,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
 from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.util import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 from time import time
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
index 87b46b2e4..912daf34b 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
@@ -23,7 +23,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
 from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.util import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 from time import time
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
index 6fd1b0d5b..549242cef 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
@@ -22,7 +22,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
 from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.util import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 from time import time
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py
index 769d0e10a..3e29a043e 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py
@@ -22,7 +22,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.persistent_uniform_sampling import persistent_uniform as gen_f
 from libensemble.alloc_funcs.start_only_persistent import only_persistent_gens as alloc_f
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.util import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_pregenerated_sample.py b/libensemble/tests/regression_tests/test_6-hump_camel_pregenerated_sample.py
index a1ab4f107..929aa147a 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_pregenerated_sample.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_pregenerated_sample.py
@@ -20,7 +20,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.alloc_funcs.give_pregenerated_work import give_pregenerated_sim_work as alloc_f
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output
+from libensemble.util import parse_args, save_libE_output
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
index d6263f0dc..c99edd32d 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
@@ -20,7 +20,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.util import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
index 0cfe45ca4..795d1f286 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
@@ -23,7 +23,7 @@
 from libensemble.gen_funcs.uniform_or_localopt import uniform_or_localopt as gen_f
 from libensemble.alloc_funcs.start_persistent_local_opt_gens import start_persistent_local_opt_gens as alloc_f
 from libensemble.tests.regression_tests.support import uniform_or_localopt_gen_out as gen_out
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.util import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py b/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
index de7890af4..0bab4daf2 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
@@ -22,7 +22,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel_with_different_ranks_and_nodes as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample_with_different_nodes_and_ranks as gen_f
 from libensemble.alloc_funcs.give_sim_work_first import give_sim_work_first
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.util import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py b/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
index 0de243fe7..fd7cec063 100644
--- a/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
+++ b/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
@@ -21,7 +21,7 @@
 from libensemble.sim_funcs.branin.branin_obj import call_branin as sim_f
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.tests.regression_tests.support import persis_info_2 as persis_info, aposmm_gen_out as gen_out, branin_vals_and_minima as M
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.util import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_calc_exception.py b/libensemble/tests/regression_tests/test_calc_exception.py
index 58247bb9c..fb2dfffe4 100644
--- a/libensemble/tests/regression_tests/test_calc_exception.py
+++ b/libensemble/tests/regression_tests/test_calc_exception.py
@@ -18,7 +18,7 @@
 from libensemble.libE import libE
 from libensemble.libE_manager import ManagerException
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
-from libensemble.tests.regression_tests.common import parse_args, per_worker_stream
+from libensemble.util import parse_args, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py b/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py
index 3df028cb0..44e5c71e1 100644
--- a/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py
+++ b/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py
@@ -20,7 +20,7 @@
 from libensemble.sim_funcs.chwirut1 import chwirut_eval as sim_f
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.alloc_funcs.fast_alloc_and_pausing import give_sim_work_first as alloc_f
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.util import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import persis_info_3 as persis_info, aposmm_gen_out as gen_out
 
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders.py b/libensemble/tests/regression_tests/test_chwirut_pounders.py
index d438ea63e..d724874da 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders.py
@@ -20,7 +20,7 @@
 from libensemble.sim_funcs.chwirut1 import chwirut_eval as sim_f
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.tests.regression_tests.support import persis_info_2 as persis_info, aposmm_gen_out as gen_out
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.util import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
index 2cfe788e6..943319409 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
@@ -23,7 +23,7 @@
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
 from libensemble.gen_funcs.sampling import lhs_sample
 from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.util import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py b/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
index 6abcf01ea..2db4612a2 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
@@ -21,7 +21,7 @@
 from libensemble.sim_funcs.chwirut1 import chwirut_eval as sim_f
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.tests.regression_tests.support import persis_info_2 as persis_info, aposmm_gen_out as gen_out
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream, mpi_comm_split
+from libensemble.util import parse_args, save_libE_output, per_worker_stream, mpi_comm_split
 
 num_comms = 2  # Must have atleast num_comms*2 processors
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py b/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
index 33f4b5d69..585faca30 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
@@ -20,7 +20,7 @@
 from libensemble.sim_funcs.chwirut1 import chwirut_eval as sim_f
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.tests.regression_tests.support import persis_info_2 as persis_info, aposmm_gen_out as gen_out
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream, mpi_comm_excl
+from libensemble.util import parse_args, save_libE_output, per_worker_stream, mpi_comm_excl
 
 nworkers, is_master, libE_specs, _ = parse_args()
 libE_specs['comm'], mpi_comm_null = mpi_comm_excl()
diff --git a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
index 054a60224..d973557f8 100644
--- a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
+++ b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
@@ -27,7 +27,7 @@
 from libensemble.gen_funcs.sampling import uniform_random_sample_obj_components as gen_f
 from libensemble.alloc_funcs.fast_alloc_and_pausing import give_sim_work_first as alloc_f
 from libensemble.tests.regression_tests.support import persis_info_3 as persis_info
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.util import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 if libE_specs['comms'] == 'tcp':
diff --git a/libensemble/tests/regression_tests/test_comms.py b/libensemble/tests/regression_tests/test_comms.py
index 619ae2d65..7187fb320 100644
--- a/libensemble/tests/regression_tests/test_comms.py
+++ b/libensemble/tests/regression_tests/test_comms.py
@@ -20,7 +20,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.comms_testing import float_x1000 as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.util import parse_args, save_libE_output, per_worker_stream
 from libensemble.mpi_controller import MPIJobController  # Only used to get workerID in float_x1000
 jobctrl = MPIJobController(auto_resources=False)
 
diff --git a/libensemble/tests/regression_tests/test_fast_alloc.py b/libensemble/tests/regression_tests/test_fast_alloc.py
index 012039a29..0120a64c7 100644
--- a/libensemble/tests/regression_tests/test_fast_alloc.py
+++ b/libensemble/tests/regression_tests/test_fast_alloc.py
@@ -18,10 +18,10 @@
 
 # Import libEnsemble items for this test
 from libensemble.libE import libE
-from libensemble.sim_funcs.six_hump_camel import six_hump_camel_simple as sim_f
+from libensemble.sim_funcs.six_hump_camel import six_hump_camel_simple as sim_fß
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
 from libensemble.alloc_funcs.fast_alloc import give_sim_work_first as alloc_f
-from libensemble.tests.regression_tests.common import parse_args, per_worker_stream
+from libensemble.util import parse_args, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_inverse_bayes_example.py b/libensemble/tests/regression_tests/test_inverse_bayes_example.py
index a117a83f9..bcd5278cb 100644
--- a/libensemble/tests/regression_tests/test_inverse_bayes_example.py
+++ b/libensemble/tests/regression_tests/test_inverse_bayes_example.py
@@ -24,7 +24,7 @@
 from libensemble.sim_funcs.inverse_bayes import likelihood_calculator as sim_f
 from libensemble.gen_funcs.persistent_inverse_bayes import persistent_updater_after_likelihood as gen_f
 from libensemble.alloc_funcs.inverse_bayes_allocf import only_persistent_gens_for_inverse_bayes as alloc_f
-from libensemble.tests.regression_tests.common import parse_args, per_worker_stream
+from libensemble.util import parse_args, per_worker_stream
 
 # Parse args for test code
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_jobcontroller_hworld.py b/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
index 73abc3748..e5f916344 100644
--- a/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
+++ b/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
@@ -21,7 +21,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.job_control_hworld import job_control_hworld as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
-from libensemble.tests.regression_tests.common import build_simfunc, parse_args, per_worker_stream
+from libensemble.util import build_simfunc, parse_args, per_worker_stream
 
 # Do not change these lines - they are parsed by run-tests.sh
 # TESTSUITE_COMMS: mpi local tcp
diff --git a/libensemble/tests/regression_tests/test_mpi_comms.py b/libensemble/tests/regression_tests/test_mpi_comms.py
index 11ae9964c..fc2c3cda2 100644
--- a/libensemble/tests/regression_tests/test_mpi_comms.py
+++ b/libensemble/tests/regression_tests/test_mpi_comms.py
@@ -10,7 +10,7 @@
 import sys
 from mpi4py import MPI
 from libensemble.comms.mpi import MPIComm, Timeout
-from libensemble.tests.regression_tests.common import parse_args
+from libensemble.util import parse_args
 
 # Do not change these lines - they are parsed by run-tests.sh
 # TESTSUITE_COMMS: mpi
diff --git a/libensemble/tests/regression_tests/test_nan_func_aposmm.py b/libensemble/tests/regression_tests/test_nan_func_aposmm.py
index d78e2424a..2cfff3de6 100644
--- a/libensemble/tests/regression_tests/test_nan_func_aposmm.py
+++ b/libensemble/tests/regression_tests/test_nan_func_aposmm.py
@@ -19,7 +19,7 @@
 from libensemble.libE import libE
 from support import nan_func as sim_f, aposmm_gen_out as gen_out
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.util import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 n = 2
diff --git a/libensemble/tests/regression_tests/test_worker_exceptions.py b/libensemble/tests/regression_tests/test_worker_exceptions.py
index 982ce2781..96e51ae79 100644
--- a/libensemble/tests/regression_tests/test_worker_exceptions.py
+++ b/libensemble/tests/regression_tests/test_worker_exceptions.py
@@ -19,7 +19,7 @@
 from libensemble.tests.regression_tests.support import nan_func as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
 from libensemble.libE_manager import ManagerException
-from libensemble.tests.regression_tests.common import parse_args, per_worker_stream
+from libensemble.util import parse_args, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 n = 2
diff --git a/libensemble/utils.py b/libensemble/utils.py
index 435ef1cd1..396366940 100644
--- a/libensemble/utils.py
+++ b/libensemble/utils.py
@@ -7,6 +7,7 @@
 import traceback
 import logging
 import numpy as np
+import argparse
 import pickle  # Only used when saving output on error
 
 logger = logging.getLogger(__name__)
@@ -234,3 +235,138 @@ def check_inputs(libE_specs=None, alloc_specs=None, sim_specs=None, gen_specs=No
         assert sim_specs is not None and alloc_specs is not None and gen_specs is not None, \
             "Can't check H0 without sim_specs, alloc_specs, gen_specs"
         check_H(H0, sim_specs, alloc_specs, gen_specs)
+
+# ==================== Command-line argument parsing ===========================
+
+parser = argparse.ArgumentParser(prog='test_...')
+parser.add_argument('--comms', type=str, nargs='?',
+                    choices=['local', 'tcp', 'ssh', 'client', 'mpi'],
+                    default='mpi', help='Type of communicator')
+parser.add_argument('--nworkers', type=int, nargs='?',
+                    help='Number of local forked processes')
+parser.add_argument('--workers', type=str, nargs='+',
+                    help='List of worker nodes')
+parser.add_argument('--workerID', type=int, nargs='?', help='Client worker ID')
+parser.add_argument('--server', type=str, nargs=3,
+                    help='Triple of (ip, port, authkey) used to reach manager')
+parser.add_argument('--pwd', type=str, nargs='?',
+                    help='Working directory to be used')
+parser.add_argument('--worker_pwd', type=str, nargs='?',
+                    help='Working directory on remote client')
+parser.add_argument('--worker_python', type=str, nargs='?',
+                    default=sys.executable,
+                    help='Python version on remote client')
+parser.add_argument('--tester_args', type=str, nargs='*',
+                    help='Additional arguments for use by specific testers')
+
+
+def mpi_parse_args(args):
+    "Parse arguments for MPI comms."
+    from mpi4py import MPI
+    nworkers = MPI.COMM_WORLD.Get_size()-1
+    is_master = MPI.COMM_WORLD.Get_rank() == 0
+    libE_specs = {'comm': MPI.COMM_WORLD, 'comms': 'mpi'}
+    return nworkers, is_master, libE_specs, args.tester_args
+
+
+def local_parse_args(args):
+    "Parse arguments for forked processes using multiprocessing."
+    nworkers = args.nworkers or 4
+    libE_specs = {'nprocesses': nworkers, 'comms': 'local'}
+    return nworkers, True, libE_specs, args.tester_args
+
+
+def tcp_parse_args(args):
+    "Parse arguments for local TCP connections"
+    nworkers = args.nworkers or 4
+    cmd = [
+        sys.executable, sys.argv[0], "--comms", "client", "--server",
+        "{manager_ip}", "{manager_port}", "{authkey}", "--workerID",
+        "{workerID}", "--nworkers",
+        str(nworkers)]
+    libE_specs = {'nprocesses': nworkers, 'worker_cmd': cmd, 'comms': 'tcp'}
+    return nworkers, True, libE_specs, args.tester_args
+
+
+def ssh_parse_args(args):
+    "Parse arguments for SSH with reverse tunnel."
+    nworkers = len(args.workers)
+    worker_pwd = args.worker_pwd or os.getcwd()
+    script_dir, script_name = os.path.split(sys.argv[0])
+    worker_script_name = os.path.join(worker_pwd, script_name)
+    ssh = [
+        "ssh", "-R", "{tunnel_port}:localhost:{manager_port}", "{worker_ip}"]
+    cmd = [
+        args.worker_python, worker_script_name, "--comms", "client",
+        "--server", "localhost", "{tunnel_port}", "{authkey}", "--workerID",
+        "{workerID}", "--nworkers",
+        str(nworkers)]
+    cmd = " ".join(cmd)
+    cmd = "( cd {} ; {} )".format(worker_pwd, cmd)
+    ssh.append(cmd)
+    libE_specs = {'workers': args.workers,
+                  'worker_cmd': ssh,
+                  'ip': 'localhost',
+                  'comms': 'tcp'}
+    return nworkers, True, libE_specs, args.tester_args
+
+
+def client_parse_args(args):
+    "Parse arguments for a TCP client."
+    nworkers = args.nworkers or 4
+    ip, port, authkey = args.server
+    libE_specs = {'ip': ip,
+                  'port': int(port),
+                  'authkey': authkey.encode('utf-8'),
+                  'workerID': args.workerID,
+                  'nprocesses': nworkers,
+                  'comms': 'tcp'}
+    return nworkers, False, libE_specs, args.tester_args
+
+
+def parse_args():
+    "Unified parsing interface for regression test arguments"
+    args = parser.parse_args(sys.argv[1:])
+    front_ends = {
+        'mpi': mpi_parse_args,
+        'local': local_parse_args,
+        'tcp': tcp_parse_args,
+        'ssh': ssh_parse_args,
+        'client': client_parse_args}
+    if args.pwd is not None:
+        os.chdir(args.pwd)
+    return front_ends[args.comms or 'mpi'](args)
+
+# =================== save libE output to pickle and np ========================
+
+def save_libE_output(H, persis_info, calling_file, nworkers):
+    script_name = os.path.splitext(os.path.basename(calling_file))[0]
+    short_name = script_name.split("test_", 1).pop()
+    filename = short_name + '_results_History_length=' + str(len(H)) \
+                          + '_evals=' + str(sum(H['returned'])) \
+                          + '_ranks=' + str(nworkers)
+
+    print("\n\n\nRun completed.\nSaving results to file: "+filename)
+    np.save(filename, H)
+
+    with open(filename + ".pickle", "wb") as f:
+        pickle.dump(persis_info, f)
+
+# ===================== per-worker numpy random-streams ========================
+
+def per_worker_stream(persis_info, nworkers):
+    for i in range(nworkers):
+        if i in persis_info:
+            persis_info[i].update({
+                'rand_stream': np.random.RandomState(i),
+                'worker_num': i})
+        else:
+            persis_info[i] = {
+                'rand_stream': np.random.RandomState(i),
+                'worker_num': i}
+    return persis_info
+
+
+
+def eprint(*args, **kwargs):
+    print(*args, file=sys.stderr, **kwargs)

From 8bbd9847d8d77cc506b4cd0c3f3623261938ac0d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 14 Nov 2019 14:49:51 -0600
Subject: [PATCH 507/644] Debugging readthedocs

---
 docs/requirements.txt | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/requirements.txt b/docs/requirements.txt
index b6f35cbcb..ef36addc6 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,2 +1 @@
 sphinxcontrib-bibtex
-libensemble 

From 59f0c86abd2b8a17130c51b7b78973e7a8a7fb63 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 14 Nov 2019 14:51:53 -0600
Subject: [PATCH 508/644] Debugging readthedocs

---
 .readthedocs.yml | 8 +-------
 1 file changed, 1 insertion(+), 7 deletions(-)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index 36218d02f..81da37806 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -1,13 +1,7 @@
 version: 2
 
 sphinx:
-  configuration: docs/conf.py
+    configuration: docs/conf.py
 
 build:
     image: latest
-
-python:
-    version: 3.6
-    install:
-      - requirements: docs/requirements.txt
-    system_packages: true

From d5602fbcd064c32b009a40bdaf4415144ca61f18 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 14 Nov 2019 14:53:18 -0600
Subject: [PATCH 509/644] Debugging readthedocs

---
 docs/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index 39ec59570..693833f64 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -53,7 +53,7 @@ def __getattr__(cls, name):
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-needs_sphinx = '2.0'
+# needs_sphinx = '2.0'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

From 8f716a73349fa218b16a33640e740d0834a43266 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 14 Nov 2019 14:55:02 -0600
Subject: [PATCH 510/644] Debugging readthedocs

---
 .readthedocs.yml      | 3 +++
 conda/environment.yml | 2 +-
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index 81da37806..1e71c897a 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -1,5 +1,8 @@
 version: 2
 
+conda:
+    environment: conda/environment.yml
+
 sphinx:
     configuration: docs/conf.py
 
diff --git a/conda/environment.yml b/conda/environment.yml
index 12c3875f2..8d2d32006 100644
--- a/conda/environment.yml
+++ b/conda/environment.yml
@@ -3,4 +3,4 @@ dependencies:
  - pip
  - pip:
    - sphinxcontrib.bibtex
-   - sphinxcontrib-bibtex
\ No newline at end of file
+   - sphinxcontrib-bibtex

From 3c89be66958c92d268eea4904916327f8a4d9b2d Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 14 Nov 2019 15:06:08 -0600
Subject: [PATCH 511/644] bump navigation depth

---
 docs/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index 693833f64..b45b78d79 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -138,7 +138,7 @@ def __getattr__(cls, name):
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-html_theme_options = {'navigation_depth': 2,
+html_theme_options = {'navigation_depth': 3,
                       'collapse_navigation': False}
 
 # Add any paths that contain custom static files (such as style sheets) here,

From f1030261cc2b5813aea749653a678e572628c68c Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Thu, 14 Nov 2019 15:06:46 -0600
Subject: [PATCH 512/644] Try going back to conda with dep

---
 .readthedocs.yml      | 9 +++------
 conda/environment.yml | 5 +----
 docs/requirements.txt | 2 +-
 3 files changed, 5 insertions(+), 11 deletions(-)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index 36218d02f..45ad794c7 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -1,13 +1,10 @@
 version: 2
 
+conda:
+    environment: conda/environment.yml
+
 sphinx:
   configuration: docs/conf.py
 
 build:
     image: latest
-
-python:
-    version: 3.6
-    install:
-      - requirements: docs/requirements.txt
-    system_packages: true
diff --git a/conda/environment.yml b/conda/environment.yml
index 12c3875f2..d28afbb1b 100644
--- a/conda/environment.yml
+++ b/conda/environment.yml
@@ -1,6 +1,3 @@
 dependencies:
  - python>=3.6
- - pip
- - pip:
-   - sphinxcontrib.bibtex
-   - sphinxcontrib-bibtex
\ No newline at end of file
+ - sphinxcontrib-bibtex
\ No newline at end of file
diff --git a/docs/requirements.txt b/docs/requirements.txt
index b6f35cbcb..063fc0e58 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,2 +1,2 @@
 sphinxcontrib-bibtex
-libensemble 
+

From ca7f75b68ac4631ff127574d8bf86c95c3320b36 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Thu, 14 Nov 2019 15:28:25 -0600
Subject: [PATCH 513/644] Explicit install line in environment.yaml

---
 conda/environment.yml | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/conda/environment.yml b/conda/environment.yml
index d28afbb1b..2a28ef215 100644
--- a/conda/environment.yml
+++ b/conda/environment.yml
@@ -1,3 +1,6 @@
+before_install:
+    conda install sphinxcontrib-bibtex
+
 dependencies:
  - python>=3.6
- - sphinxcontrib-bibtex
\ No newline at end of file
+ 
\ No newline at end of file

From 9782dbc0d06ec1d059b421089437242d1c7137d3 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Thu, 14 Nov 2019 15:50:14 -0600
Subject: [PATCH 514/644] Add channels to environment.yml

---
 conda/environment.yml | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/conda/environment.yml b/conda/environment.yml
index 2a28ef215..01fd94b91 100644
--- a/conda/environment.yml
+++ b/conda/environment.yml
@@ -1,6 +1,7 @@
-before_install:
-    conda install sphinxcontrib-bibtex
+channels:
+  - conda-forge
+  - defaults
 
 dependencies:
+ - sphinxcontrib-bibtex
  - python>=3.6
- 
\ No newline at end of file

From 361dde868540e8a421dffeebad0b67829d4e6ad5 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 14 Nov 2019 15:55:14 -0600
Subject: [PATCH 515/644] flake8

---
 examples/tutorials/tutorial_calling.py                | 8 ++++----
 examples/tutorials/tutorial_calling_mpi.py            | 8 ++++----
 libensemble/tests/regression_tests/common.py          | 3 ---
 libensemble/tests/regression_tests/test_fast_alloc.py | 2 +-
 libensemble/utils.py                                  | 7 ++++++-
 5 files changed, 15 insertions(+), 13 deletions(-)

diff --git a/examples/tutorials/tutorial_calling.py b/examples/tutorials/tutorial_calling.py
index 38d87866f..6681f20db 100644
--- a/examples/tutorials/tutorial_calling.py
+++ b/examples/tutorials/tutorial_calling.py
@@ -9,10 +9,10 @@
 
 gen_specs = {'gen_f': gen_random_sample,        # Our generator function
              'out': [('x', float, (1,))],       # gen_f output (name, type, size).
-             'user': { 'lower': np.array([-3]), # random sampling lower bound
-                       'upper': np.array([3]),  # random sampling upper bound
-                       'gen_batch_size': 5      # number of values gen_f will generate per call
-                     }
+             'user': {'lower': np.array([-3]),  # random sampling lower bound
+                      'upper': np.array([3]),   # random sampling upper bound
+                      'gen_batch_size': 5       # number of values gen_f will generate per call
+                      }
              }
 
 sim_specs = {'sim_f': sim_find_sine,            # Our simulator function
diff --git a/examples/tutorials/tutorial_calling_mpi.py b/examples/tutorials/tutorial_calling_mpi.py
index 99d5e628a..82805aee6 100644
--- a/examples/tutorials/tutorial_calling_mpi.py
+++ b/examples/tutorials/tutorial_calling_mpi.py
@@ -13,10 +13,10 @@
 
 gen_specs = {'gen_f': gen_random_sample,        # Our generator function
              'out': [('x', float, (1,))],       # gen_f output (name, type, size).
-             'user': { 'lower': np.array([-3]), # random sampling lower bound
-                       'upper': np.array([3]),  # random sampling upper bound
-                       'gen_batch_size': 5      # number of values gen_f will generate per call
-                     }
+             'user': {'lower': np.array([-3]),  # random sampling lower bound
+                      'upper': np.array([3]),   # random sampling upper bound
+                      'gen_batch_size': 5       # number of values gen_f will generate per call
+                      }
              }
 
 sim_specs = {'sim_f': sim_find_sine,            # Our simulator function
diff --git a/libensemble/tests/regression_tests/common.py b/libensemble/tests/regression_tests/common.py
index c5f490af9..a1883c4b7 100644
--- a/libensemble/tests/regression_tests/common.py
+++ b/libensemble/tests/regression_tests/common.py
@@ -2,11 +2,8 @@
 Common plumbing for regression tests
 """
 
-import sys
 import os
 import os.path
-import numpy as np
-import pickle
 
 
 def mpi_comm_excl(exc=[0], comm=None):
diff --git a/libensemble/tests/regression_tests/test_fast_alloc.py b/libensemble/tests/regression_tests/test_fast_alloc.py
index 0120a64c7..8764eaee1 100644
--- a/libensemble/tests/regression_tests/test_fast_alloc.py
+++ b/libensemble/tests/regression_tests/test_fast_alloc.py
@@ -18,7 +18,7 @@
 
 # Import libEnsemble items for this test
 from libensemble.libE import libE
-from libensemble.sim_funcs.six_hump_camel import six_hump_camel_simple as sim_fß
+from libensemble.sim_funcs.six_hump_camel import six_hump_camel_simple as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
 from libensemble.alloc_funcs.fast_alloc import give_sim_work_first as alloc_f
 from libensemble.util import parse_args, per_worker_stream
diff --git a/libensemble/utils.py b/libensemble/utils.py
index 396366940..30e9b5b2f 100644
--- a/libensemble/utils.py
+++ b/libensemble/utils.py
@@ -5,6 +5,8 @@
 """
 
 import traceback
+import os
+import sys
 import logging
 import numpy as np
 import argparse
@@ -238,7 +240,9 @@ def check_inputs(libE_specs=None, alloc_specs=None, sim_specs=None, gen_specs=No
 
 # ==================== Command-line argument parsing ===========================
 
+
 parser = argparse.ArgumentParser(prog='test_...')
+
 parser.add_argument('--comms', type=str, nargs='?',
                     choices=['local', 'tcp', 'ssh', 'client', 'mpi'],
                     default='mpi', help='Type of communicator')
@@ -339,6 +343,7 @@ def parse_args():
 
 # =================== save libE output to pickle and np ========================
 
+
 def save_libE_output(H, persis_info, calling_file, nworkers):
     script_name = os.path.splitext(os.path.basename(calling_file))[0]
     short_name = script_name.split("test_", 1).pop()
@@ -354,6 +359,7 @@ def save_libE_output(H, persis_info, calling_file, nworkers):
 
 # ===================== per-worker numpy random-streams ========================
 
+
 def per_worker_stream(persis_info, nworkers):
     for i in range(nworkers):
         if i in persis_info:
@@ -367,6 +373,5 @@ def per_worker_stream(persis_info, nworkers):
     return persis_info
 
 
-
 def eprint(*args, **kwargs):
     print(*args, file=sys.stderr, **kwargs)

From 5768f6b0ecb512681ecffcea10f538465a640bed Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Thu, 14 Nov 2019 16:01:11 -0600
Subject: [PATCH 516/644] Add python segment back into .readthedocs.yml

---
 .readthedocs.yml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index 45ad794c7..279fa2a21 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -8,3 +8,8 @@ sphinx:
 
 build:
     image: latest
+
+python:
+    version: 3.6
+    pip_install: true
+    setup_py_install: true    
\ No newline at end of file

From 16ff9959573bd4ae820682fb6a0aa888ab2d56f2 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Thu, 14 Nov 2019 16:08:58 -0600
Subject: [PATCH 517/644] Try pip install via environment.yml

---
 .readthedocs.yml      | 8 ++++----
 conda/environment.yml | 2 ++
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index 279fa2a21..9cca83e70 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -9,7 +9,7 @@ sphinx:
 build:
     image: latest
 
-python:
-    version: 3.6
-    pip_install: true
-    setup_py_install: true    
\ No newline at end of file
+#python:
+    #version: 3.6
+    #pip_install: true
+    #setup_py_install: true    
\ No newline at end of file
diff --git a/conda/environment.yml b/conda/environment.yml
index 01fd94b91..05403b9a9 100644
--- a/conda/environment.yml
+++ b/conda/environment.yml
@@ -5,3 +5,5 @@ channels:
 dependencies:
  - sphinxcontrib-bibtex
  - python>=3.6
+  - pip:
+    - .

From 345a60b87d766b6d01c5c4bb3252b0ba08b5b695 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Thu, 14 Nov 2019 16:12:41 -0600
Subject: [PATCH 518/644] Try pip install via environment.yml

---
 conda/environment.yml | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/conda/environment.yml b/conda/environment.yml
index 05403b9a9..3f8afb6e7 100644
--- a/conda/environment.yml
+++ b/conda/environment.yml
@@ -5,5 +5,4 @@ channels:
 dependencies:
  - sphinxcontrib-bibtex
  - python>=3.6
-  - pip:
-    - .
+

From fc62d225170b7832fbdfd15aabecc44b7d39559f Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 14 Nov 2019 16:27:03 -0600
Subject: [PATCH 519/644] silly typo

---
 .../tests/regression_tests/script_test_balsam_hworld.py        | 2 +-
 libensemble/tests/regression_tests/test_1d_sampling.py         | 2 +-
 .../regression_tests/test_1d_uniform_sampling_with_comm_dup.py | 2 +-
 .../test_6-hump_camel_active_persistent_worker_abort.py        | 2 +-
 .../tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py  | 2 +-
 .../regression_tests/test_6-hump_camel_elapsed_time_abort.py   | 2 +-
 .../regression_tests/test_6-hump_camel_persistent_aposmm_1.py  | 2 +-
 .../regression_tests/test_6-hump_camel_persistent_aposmm_2.py  | 2 +-
 .../regression_tests/test_6-hump_camel_persistent_aposmm_3.py  | 2 +-
 .../regression_tests/test_6-hump_camel_persistent_aposmm_4.py  | 2 +-
 .../test_6-hump_camel_persistent_uniform_sampling.py           | 2 +-
 .../regression_tests/test_6-hump_camel_pregenerated_sample.py  | 2 +-
 .../regression_tests/test_6-hump_camel_uniform_sampling.py     | 2 +-
 ...ump_camel_uniform_sampling_with_persistent_localopt_gens.py | 2 +-
 .../test_6-hump_camel_with_different_nodes_uniform_sample.py   | 2 +-
 .../test_branin_aposmm_nlopt_and_then_scipy.py                 | 2 +-
 libensemble/tests/regression_tests/test_calc_exception.py      | 2 +-
 .../test_chwirut_aposmm_one_residual_at_a_time.py              | 2 +-
 libensemble/tests/regression_tests/test_chwirut_pounders.py    | 2 +-
 .../tests/regression_tests/test_chwirut_pounders_persistent.py | 2 +-
 .../tests/regression_tests/test_chwirut_pounders_splitcomm.py  | 2 +-
 .../tests/regression_tests/test_chwirut_pounders_subcomm.py    | 2 +-
 .../test_chwirut_uniform_sampling_one_residual_at_a_time.py    | 2 +-
 libensemble/tests/regression_tests/test_comms.py               | 2 +-
 libensemble/tests/regression_tests/test_fast_alloc.py          | 2 +-
 .../tests/regression_tests/test_inverse_bayes_example.py       | 2 +-
 .../tests/regression_tests/test_jobcontroller_hworld.py        | 3 ++-
 libensemble/tests/regression_tests/test_mpi_comms.py           | 2 +-
 libensemble/tests/regression_tests/test_nan_func_aposmm.py     | 2 +-
 libensemble/tests/regression_tests/test_worker_exceptions.py   | 2 +-
 30 files changed, 31 insertions(+), 30 deletions(-)

diff --git a/libensemble/tests/regression_tests/script_test_balsam_hworld.py b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
index 8f0e671b0..4b02032c1 100644
--- a/libensemble/tests/regression_tests/script_test_balsam_hworld.py
+++ b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
@@ -11,7 +11,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.job_control_hworld import job_control_hworld as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
-from libensemble.util import per_worker_stream
+from libensemble.utils import per_worker_stream
 
 mpi4py.rc.recv_mprobe = False  # Disable matching probes
 
diff --git a/libensemble/tests/regression_tests/test_1d_sampling.py b/libensemble/tests/regression_tests/test_1d_sampling.py
index 657c140bb..beb826a62 100644
--- a/libensemble/tests/regression_tests/test_1d_sampling.py
+++ b/libensemble/tests/regression_tests/test_1d_sampling.py
@@ -19,7 +19,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.one_d_func import one_d_example as sim_f
 from libensemble.gen_funcs.sampling import latin_hypercube_sample as gen_f
-from libensemble.util import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 libE_specs['save_every_k_gens'] = 300
diff --git a/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py b/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
index f48687131..d677df940 100644
--- a/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
+++ b/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
@@ -23,7 +23,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.one_d_func import one_d_example as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
-from libensemble.util import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py b/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py
index 51601673e..7a48aeaa7 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py
@@ -22,7 +22,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.uniform_or_localopt import uniform_or_localopt as gen_f
 from libensemble.alloc_funcs.start_persistent_local_opt_gens import start_persistent_local_opt_gens as alloc_f
-from libensemble.util import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import uniform_or_localopt_gen_out as gen_out
 
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
index 88c15d6a0..52ad3004c 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
@@ -22,7 +22,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.alloc_funcs.fast_alloc_to_aposmm import give_sim_work_first as alloc_f
-from libensemble.util import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import persis_info_1 as persis_info, aposmm_gen_out as gen_out, six_hump_camel_minima as minima
 
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py b/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
index 28a965189..c4021df37 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
@@ -21,7 +21,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
 from libensemble.alloc_funcs.give_sim_work_first import give_sim_work_first
-from libensemble.util import parse_args, save_libE_output, per_worker_stream, eprint
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream, eprint
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
index 86e8a2f59..7c2b51f28 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
@@ -23,7 +23,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
 from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
-from libensemble.util import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 from time import time
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
index 365e98c12..53b3c19fd 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
@@ -23,7 +23,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
 from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
-from libensemble.util import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 from time import time
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
index 912daf34b..b016f7a1e 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
@@ -23,7 +23,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
 from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
-from libensemble.util import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 from time import time
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
index 549242cef..7d8b16eca 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
@@ -22,7 +22,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
 from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
-from libensemble.util import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 from time import time
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py
index 3e29a043e..3344eff6b 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py
@@ -22,7 +22,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.persistent_uniform_sampling import persistent_uniform as gen_f
 from libensemble.alloc_funcs.start_only_persistent import only_persistent_gens as alloc_f
-from libensemble.util import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_pregenerated_sample.py b/libensemble/tests/regression_tests/test_6-hump_camel_pregenerated_sample.py
index 929aa147a..a992d5123 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_pregenerated_sample.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_pregenerated_sample.py
@@ -20,7 +20,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.alloc_funcs.give_pregenerated_work import give_pregenerated_sim_work as alloc_f
-from libensemble.util import parse_args, save_libE_output
+from libensemble.utils import parse_args, save_libE_output
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
index c99edd32d..6c9948fa4 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
@@ -20,7 +20,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
-from libensemble.util import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
index 795d1f286..4d48ed7c2 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
@@ -23,7 +23,7 @@
 from libensemble.gen_funcs.uniform_or_localopt import uniform_or_localopt as gen_f
 from libensemble.alloc_funcs.start_persistent_local_opt_gens import start_persistent_local_opt_gens as alloc_f
 from libensemble.tests.regression_tests.support import uniform_or_localopt_gen_out as gen_out
-from libensemble.util import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py b/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
index 0bab4daf2..9b50710cb 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
@@ -22,7 +22,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel_with_different_ranks_and_nodes as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample_with_different_nodes_and_ranks as gen_f
 from libensemble.alloc_funcs.give_sim_work_first import give_sim_work_first
-from libensemble.util import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py b/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
index fd7cec063..71767a494 100644
--- a/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
+++ b/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
@@ -21,7 +21,7 @@
 from libensemble.sim_funcs.branin.branin_obj import call_branin as sim_f
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.tests.regression_tests.support import persis_info_2 as persis_info, aposmm_gen_out as gen_out, branin_vals_and_minima as M
-from libensemble.util import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_calc_exception.py b/libensemble/tests/regression_tests/test_calc_exception.py
index fb2dfffe4..f7cf98b19 100644
--- a/libensemble/tests/regression_tests/test_calc_exception.py
+++ b/libensemble/tests/regression_tests/test_calc_exception.py
@@ -18,7 +18,7 @@
 from libensemble.libE import libE
 from libensemble.libE_manager import ManagerException
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
-from libensemble.util import parse_args, per_worker_stream
+from libensemble.utils import parse_args, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py b/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py
index 44e5c71e1..fd59b09e6 100644
--- a/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py
+++ b/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py
@@ -20,7 +20,7 @@
 from libensemble.sim_funcs.chwirut1 import chwirut_eval as sim_f
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.alloc_funcs.fast_alloc_and_pausing import give_sim_work_first as alloc_f
-from libensemble.util import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import persis_info_3 as persis_info, aposmm_gen_out as gen_out
 
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders.py b/libensemble/tests/regression_tests/test_chwirut_pounders.py
index d724874da..aca432e06 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders.py
@@ -20,7 +20,7 @@
 from libensemble.sim_funcs.chwirut1 import chwirut_eval as sim_f
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.tests.regression_tests.support import persis_info_2 as persis_info, aposmm_gen_out as gen_out
-from libensemble.util import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
index 943319409..cb013ef0e 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
@@ -23,7 +23,7 @@
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
 from libensemble.gen_funcs.sampling import lhs_sample
 from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
-from libensemble.util import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py b/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
index 2db4612a2..53bc681a6 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
@@ -21,7 +21,7 @@
 from libensemble.sim_funcs.chwirut1 import chwirut_eval as sim_f
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.tests.regression_tests.support import persis_info_2 as persis_info, aposmm_gen_out as gen_out
-from libensemble.util import parse_args, save_libE_output, per_worker_stream, mpi_comm_split
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream, mpi_comm_split
 
 num_comms = 2  # Must have atleast num_comms*2 processors
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py b/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
index 585faca30..73f6a07d0 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
@@ -20,7 +20,7 @@
 from libensemble.sim_funcs.chwirut1 import chwirut_eval as sim_f
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.tests.regression_tests.support import persis_info_2 as persis_info, aposmm_gen_out as gen_out
-from libensemble.util import parse_args, save_libE_output, per_worker_stream, mpi_comm_excl
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream, mpi_comm_excl
 
 nworkers, is_master, libE_specs, _ = parse_args()
 libE_specs['comm'], mpi_comm_null = mpi_comm_excl()
diff --git a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
index d973557f8..83fb5e8a2 100644
--- a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
+++ b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
@@ -27,7 +27,7 @@
 from libensemble.gen_funcs.sampling import uniform_random_sample_obj_components as gen_f
 from libensemble.alloc_funcs.fast_alloc_and_pausing import give_sim_work_first as alloc_f
 from libensemble.tests.regression_tests.support import persis_info_3 as persis_info
-from libensemble.util import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 if libE_specs['comms'] == 'tcp':
diff --git a/libensemble/tests/regression_tests/test_comms.py b/libensemble/tests/regression_tests/test_comms.py
index 7187fb320..7161c6883 100644
--- a/libensemble/tests/regression_tests/test_comms.py
+++ b/libensemble/tests/regression_tests/test_comms.py
@@ -20,7 +20,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.comms_testing import float_x1000 as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
-from libensemble.util import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 from libensemble.mpi_controller import MPIJobController  # Only used to get workerID in float_x1000
 jobctrl = MPIJobController(auto_resources=False)
 
diff --git a/libensemble/tests/regression_tests/test_fast_alloc.py b/libensemble/tests/regression_tests/test_fast_alloc.py
index 8764eaee1..5a2043b0f 100644
--- a/libensemble/tests/regression_tests/test_fast_alloc.py
+++ b/libensemble/tests/regression_tests/test_fast_alloc.py
@@ -21,7 +21,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel_simple as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
 from libensemble.alloc_funcs.fast_alloc import give_sim_work_first as alloc_f
-from libensemble.util import parse_args, per_worker_stream
+from libensemble.utils import parse_args, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
diff --git a/libensemble/tests/regression_tests/test_inverse_bayes_example.py b/libensemble/tests/regression_tests/test_inverse_bayes_example.py
index bcd5278cb..f9b45b60e 100644
--- a/libensemble/tests/regression_tests/test_inverse_bayes_example.py
+++ b/libensemble/tests/regression_tests/test_inverse_bayes_example.py
@@ -24,7 +24,7 @@
 from libensemble.sim_funcs.inverse_bayes import likelihood_calculator as sim_f
 from libensemble.gen_funcs.persistent_inverse_bayes import persistent_updater_after_likelihood as gen_f
 from libensemble.alloc_funcs.inverse_bayes_allocf import only_persistent_gens_for_inverse_bayes as alloc_f
-from libensemble.util import parse_args, per_worker_stream
+from libensemble.utils import parse_args, per_worker_stream
 
 # Parse args for test code
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_jobcontroller_hworld.py b/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
index e5f916344..9c4d89e75 100644
--- a/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
+++ b/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
@@ -21,7 +21,8 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.job_control_hworld import job_control_hworld as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
-from libensemble.util import build_simfunc, parse_args, per_worker_stream
+from libensemble.util import parse_args, per_worker_stream
+from libensemble.tests.regression_tests.common import build_simfunc
 
 # Do not change these lines - they are parsed by run-tests.sh
 # TESTSUITE_COMMS: mpi local tcp
diff --git a/libensemble/tests/regression_tests/test_mpi_comms.py b/libensemble/tests/regression_tests/test_mpi_comms.py
index fc2c3cda2..1c29b3a26 100644
--- a/libensemble/tests/regression_tests/test_mpi_comms.py
+++ b/libensemble/tests/regression_tests/test_mpi_comms.py
@@ -10,7 +10,7 @@
 import sys
 from mpi4py import MPI
 from libensemble.comms.mpi import MPIComm, Timeout
-from libensemble.util import parse_args
+from libensemble.utils import parse_args
 
 # Do not change these lines - they are parsed by run-tests.sh
 # TESTSUITE_COMMS: mpi
diff --git a/libensemble/tests/regression_tests/test_nan_func_aposmm.py b/libensemble/tests/regression_tests/test_nan_func_aposmm.py
index 2cfff3de6..bb8d5f1dc 100644
--- a/libensemble/tests/regression_tests/test_nan_func_aposmm.py
+++ b/libensemble/tests/regression_tests/test_nan_func_aposmm.py
@@ -19,7 +19,7 @@
 from libensemble.libE import libE
 from support import nan_func as sim_f, aposmm_gen_out as gen_out
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
-from libensemble.util import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 n = 2
diff --git a/libensemble/tests/regression_tests/test_worker_exceptions.py b/libensemble/tests/regression_tests/test_worker_exceptions.py
index 96e51ae79..a8db08e2a 100644
--- a/libensemble/tests/regression_tests/test_worker_exceptions.py
+++ b/libensemble/tests/regression_tests/test_worker_exceptions.py
@@ -19,7 +19,7 @@
 from libensemble.tests.regression_tests.support import nan_func as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
 from libensemble.libE_manager import ManagerException
-from libensemble.util import parse_args, per_worker_stream
+from libensemble.utils import parse_args, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 n = 2

From 8fc6f20383b20532933ae21fce699c23a298d576 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Thu, 14 Nov 2019 16:33:00 -0600
Subject: [PATCH 520/644] Remove version2 - last try with conda

---
 .readthedocs.yml | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index 9cca83e70..52dec1e2d 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -1,4 +1,4 @@
-version: 2
+#version: 2
 
 conda:
     environment: conda/environment.yml
@@ -9,7 +9,7 @@ sphinx:
 build:
     image: latest
 
-#python:
-    #version: 3.6
-    #pip_install: true
-    #setup_py_install: true    
\ No newline at end of file
+python:
+    version: 3.6
+    pip_install: true
+    setup_py_install: true    
\ No newline at end of file

From 28d212d86627ae33c84cb790e60617006bed98fb Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Thu, 14 Nov 2019 16:37:33 -0600
Subject: [PATCH 521/644] Remove version2 - last try with conda

---
 .readthedocs.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index 52dec1e2d..fc115834f 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -1,7 +1,7 @@
 #version: 2
 
 conda:
-    environment: conda/environment.yml
+    file: conda/environment.yml
 
 sphinx:
   configuration: docs/conf.py

From 8179b197356392904383228b8d2762dc017f724b Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Thu, 14 Nov 2019 16:44:55 -0600
Subject: [PATCH 522/644] Last may have wrked on ver1. Try version 2

---
 .readthedocs.yml | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index fc115834f..56981be9d 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -1,4 +1,4 @@
-#version: 2
+version: 2
 
 conda:
     file: conda/environment.yml
@@ -10,6 +10,4 @@ build:
     image: latest
 
 python:
-    version: 3.6
-    pip_install: true
-    setup_py_install: true    
\ No newline at end of file
+    install: true
\ No newline at end of file

From ac602ea7afbc01149aaf07a8d2c0d1f3cf3d79fb Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Thu, 14 Nov 2019 16:45:45 -0600
Subject: [PATCH 523/644] Fix environemnt keyword. Try version 2

---
 .readthedocs.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index 56981be9d..df05b2ff7 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -1,7 +1,7 @@
 version: 2
 
 conda:
-    file: conda/environment.yml
+    environment: conda/environment.yml
 
 sphinx:
   configuration: docs/conf.py

From f00395432290b9abde47a1d97b2d27a60d1391e0 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Thu, 14 Nov 2019 16:49:52 -0600
Subject: [PATCH 524/644] python install give path. Try version 2

---
 .readthedocs.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index df05b2ff7..ab5b7e05f 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -10,4 +10,4 @@ build:
     image: latest
 
 python:
-    install: true
\ No newline at end of file
+    install: .
\ No newline at end of file

From cb6816c8de8daf546959d32fda2f1b49447badac Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Thu, 14 Nov 2019 16:54:23 -0600
Subject: [PATCH 525/644] Correct install section. Try version 2

---
 .readthedocs.yml      | 9 ++++++++-
 conda/environment.yml | 1 -
 setup.py              | 2 +-
 3 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index ab5b7e05f..e2f282634 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -10,4 +10,11 @@ build:
     image: latest
 
 python:
-    install: .
\ No newline at end of file
+    install:
+      - method: pip
+        path: .
+      #- method: setuptools        
+        #This would do pip install .[docs] - if have a 'docs' dep in setup.py
+        #extra_requirements:
+           #- docs
+  
\ No newline at end of file
diff --git a/conda/environment.yml b/conda/environment.yml
index 3f8afb6e7..01fd94b91 100644
--- a/conda/environment.yml
+++ b/conda/environment.yml
@@ -5,4 +5,3 @@ channels:
 dependencies:
  - sphinxcontrib-bibtex
  - python>=3.6
-
diff --git a/setup.py b/setup.py
index cb55be1d2..b6439cba8 100644
--- a/setup.py
+++ b/setup.py
@@ -61,7 +61,7 @@ def run_tests(self):
                    ],
 
     extras_require={
-        'extras': ['scipy', 'nlopt', 'mpi4py', 'petsc', 'petsc4py', 'sphinxcontrib.bibtex']},
+        'extras': ['scipy', 'nlopt', 'mpi4py', 'petsc', 'petsc4py']},
 
     classifiers=[
         'Development Status :: 4 - Beta',

From c61a63dbd8af723b9328b166d38148669d64fefa Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 14 Nov 2019 17:01:21 -0600
Subject: [PATCH 526/644] account for split/subcomm not being moved. forgot
 one.

---
 .../tests/regression_tests/test_chwirut_pounders_splitcomm.py  | 3 ++-
 .../tests/regression_tests/test_chwirut_pounders_subcomm.py    | 3 ++-
 .../tests/regression_tests/test_jobcontroller_hworld.py        | 2 +-
 3 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py b/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
index 53bc681a6..9cd7a7fb7 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
@@ -21,7 +21,8 @@
 from libensemble.sim_funcs.chwirut1 import chwirut_eval as sim_f
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.tests.regression_tests.support import persis_info_2 as persis_info, aposmm_gen_out as gen_out
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream, mpi_comm_split
+from libensemble.tests.regression_tests.common import mpi_comm_split
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 
 num_comms = 2  # Must have atleast num_comms*2 processors
 nworkers, is_master, libE_specs, _ = parse_args()
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py b/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
index 73f6a07d0..91664c4a6 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
@@ -20,7 +20,8 @@
 from libensemble.sim_funcs.chwirut1 import chwirut_eval as sim_f
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.tests.regression_tests.support import persis_info_2 as persis_info, aposmm_gen_out as gen_out
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream, mpi_comm_excl
+from libEnsemble.tests.regression_tests.common import mpi_comm_excl
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()
 libE_specs['comm'], mpi_comm_null = mpi_comm_excl()
diff --git a/libensemble/tests/regression_tests/test_jobcontroller_hworld.py b/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
index 9c4d89e75..95289cfe2 100644
--- a/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
+++ b/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
@@ -21,7 +21,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.job_control_hworld import job_control_hworld as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
-from libensemble.util import parse_args, per_worker_stream
+from libensemble.utils import parse_args, per_worker_stream
 from libensemble.tests.regression_tests.common import build_simfunc
 
 # Do not change these lines - they are parsed by run-tests.sh

From 8f95e595189d808397505bb4cc967bd926f9a1c1 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Thu, 14 Nov 2019 17:07:26 -0600
Subject: [PATCH 527/644] Add extras require docs. Try version 2

---
 .readthedocs.yml | 7 ++-----
 setup.py         | 1 +
 2 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index e2f282634..ec511c9a7 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -13,8 +13,5 @@ python:
     install:
       - method: pip
         path: .
-      #- method: setuptools        
-        #This would do pip install .[docs] - if have a 'docs' dep in setup.py
-        #extra_requirements:
-           #- docs
-  
\ No newline at end of file
+        extra_requirements:
+         - docs
diff --git a/setup.py b/setup.py
index b6439cba8..a6dd88a10 100644
--- a/setup.py
+++ b/setup.py
@@ -62,6 +62,7 @@ def run_tests(self):
 
     extras_require={
         'extras': ['scipy', 'nlopt', 'mpi4py', 'petsc', 'petsc4py']},
+        'docs': ['sphinxcontrib.bibtex']
 
     classifiers=[
         'Development Status :: 4 - Beta',

From 5900422195528ad3d4b7a1fda6b724c0f103f850 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Thu, 14 Nov 2019 17:20:24 -0600
Subject: [PATCH 528/644] Fix format extras require docs. Try version 2

---
 setup.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/setup.py b/setup.py
index a6dd88a10..e8c6236ef 100644
--- a/setup.py
+++ b/setup.py
@@ -61,8 +61,8 @@ def run_tests(self):
                    ],
 
     extras_require={
-        'extras': ['scipy', 'nlopt', 'mpi4py', 'petsc', 'petsc4py']},
-        'docs': ['sphinxcontrib.bibtex']
+        'extras': ['scipy', 'nlopt', 'mpi4py', 'petsc', 'petsc4py'],
+        'docs': ['sphinxcontrib.bibtex']},
 
     classifiers=[
         'Development Status :: 4 - Beta',

From 477432d7ca7b99502485066901226f9affe33fd0 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 14 Nov 2019 17:28:27 -0600
Subject: [PATCH 529/644] E -> e

---
 .../tests/regression_tests/test_chwirut_pounders_subcomm.py     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py b/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
index 91664c4a6..87ae4ead8 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
@@ -20,7 +20,7 @@
 from libensemble.sim_funcs.chwirut1 import chwirut_eval as sim_f
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.tests.regression_tests.support import persis_info_2 as persis_info, aposmm_gen_out as gen_out
-from libEnsemble.tests.regression_tests.common import mpi_comm_excl
+from libensemble.tests.regression_tests.common import mpi_comm_excl
 from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 
 nworkers, is_master, libE_specs, _ = parse_args()

From 2d8625d8315f3c55748979491fa8155e5922559b Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 14 Nov 2019 20:13:37 -0600
Subject: [PATCH 530/644] Debugging readthedocs

---
 .readthedocs.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/.readthedocs.yml b/.readthedocs.yml
index ec511c9a7..e942b9a2e 100644
--- a/.readthedocs.yml
+++ b/.readthedocs.yml
@@ -9,6 +9,9 @@ sphinx:
 build:
     image: latest
 
+formats:
+  - pdf
+
 python:
     install:
       - method: pip

From 2b94e32a15b17145d43d0c8e7e2d9f1257cdcc9f Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 15 Nov 2019 10:25:00 -0600
Subject: [PATCH 531/644] update parse_args detail in theta doc

---
 docs/platforms/theta.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index 95da5a6fd..d95482971 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -135,7 +135,7 @@ Batch Runs
 Batch scripts specify run-settings using ``#COBALT`` statements. The following
 simple example depicts configuring and launching libEnsemble to a MOM node with
 multiprocessing. This script also assumes the user is using the ``parse_args()``
-convenience function within libEnsemble's ``/regression_tests/common.py``.
+convenience function within libEnsemble's ``utils.py``.
 
 .. code-block:: bash
 

From 032bbdebfaaeb753d1c460414ffd8d0ca36830ee Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 15 Nov 2019 11:01:07 -0600
Subject: [PATCH 532/644] Removing user_funcs.rst

---
 docs/programming_libE.rst | 8 +++++++-
 docs/user_funcs.rst       | 4 ----
 2 files changed, 7 insertions(+), 5 deletions(-)
 delete mode 100644 docs/user_funcs.rst

diff --git a/docs/programming_libE.rst b/docs/programming_libE.rst
index 175d9bfee..2a4d42b0a 100644
--- a/docs/programming_libE.rst
+++ b/docs/programming_libE.rst
@@ -8,6 +8,12 @@ Programming with libEnsemble
 .. toctree::
    history_output
    data_structures/data_structures
-   user_funcs
+
+.. toctree::
+   :caption: libEnsemble User Functions:
+
+   sim_gen_alloc_funcs
+
+.. toctree::
    job_controller/jc_index
    logging
diff --git a/docs/user_funcs.rst b/docs/user_funcs.rst
deleted file mode 100644
index 65a516a45..000000000
--- a/docs/user_funcs.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-.. toctree::
-   :caption: libEnsemble User Functions:
-
-   sim_gen_alloc_funcs

From d7efa17f6bb2b3a03945089b23e9392aa8994866 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 15 Nov 2019 11:38:38 -0600
Subject: [PATCH 533/644] replace nprocesses instances with nworkers. #235

---
 docs/data_structures/libE_specs.rst                  |  2 +-
 docs/tutorials/local_sine_tutorial.rst               |  2 +-
 examples/tutorials/tutorial_calling.py               |  2 +-
 libensemble/libE.py                                  |  8 ++++----
 .../tests/scaling_tests/forces/run_libe_forces.py    |  2 +-
 libensemble/utils.py                                 | 12 ++++++------
 6 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/docs/data_structures/libE_specs.rst b/docs/data_structures/libE_specs.rst
index 5fbff8752..f68ce1c4f 100644
--- a/docs/data_structures/libE_specs.rst
+++ b/docs/data_structures/libE_specs.rst
@@ -9,7 +9,7 @@ Specifications for libEnsemble::
         'comms' [string] :
             Manager/Worker communications mode. Default: mpi
             Options are 'mpi', 'local', 'tcp'
-        'nprocesses' [int]:
+        'nworkers' [int]:
             Number of worker processes to spawn (in local/tcp modes)
         'comm' [MPI communicator] :
             libEnsemble communicator. Default: MPI.COMM_WORLD
diff --git a/docs/tutorials/local_sine_tutorial.rst b/docs/tutorials/local_sine_tutorial.rst
index 1ea6d3856..335fba391 100644
--- a/docs/tutorials/local_sine_tutorial.rst
+++ b/docs/tutorials/local_sine_tutorial.rst
@@ -173,7 +173,7 @@ use. Our communication method, ``'local'``, refers to Python's Multiprocessing.
     from simulator import sim_find_sine
 
     nworkers = 4
-    libE_specs = {'nprocesses': nworkers, 'comms': 'local'}
+    libE_specs = {'nworkers': nworkers, 'comms': 'local'}
 
 We configure the settings and specifications for our ``sim_f`` and ``gen_f``
 functions in the :ref:`gen_specs<datastruct-gen-specs>` and
diff --git a/examples/tutorials/tutorial_calling.py b/examples/tutorials/tutorial_calling.py
index 6681f20db..88757f53b 100644
--- a/examples/tutorials/tutorial_calling.py
+++ b/examples/tutorials/tutorial_calling.py
@@ -5,7 +5,7 @@
 from tutorial_sim import sim_find_sine
 
 nworkers = 4
-libE_specs = {'nprocesses': nworkers, 'comms': 'local'}
+libE_specs = {'nworkers': nworkers, 'comms': 'local'}
 
 gen_specs = {'gen_f': gen_random_sample,        # Our generator function
              'out': [('x', float, (1,))],       # gen_f output (name, type, size).
diff --git a/libensemble/libE.py b/libensemble/libE.py
index 089c87e07..0980e9d94 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -39,7 +39,7 @@ def libE(sim_specs, gen_specs, exit_criteria,
 
     We dispatch to different types of worker teams depending on
     the contents of libE_specs.  If 'comm' is a field, we use MPI;
-    if 'nthreads' is a field, we use threads; if 'nprocesses' is a
+    if 'nthreads' is a field, we use threads; if 'nworkers' is a
     field, we use multiprocessing.
 
     If an exception is encountered by the manager or workers, the
@@ -262,7 +262,7 @@ def libE_local(sim_specs, gen_specs, exit_criteria,
                persis_info, alloc_specs, libE_specs, H0):
     "Main routine for thread/process launch of libE."
 
-    nworkers = libE_specs['nprocesses']
+    nworkers = libE_specs['nworkers']
     check_inputs(libE_specs, alloc_specs, sim_specs, gen_specs, exit_criteria, H0)
 
     jobctl = JobController.controller
@@ -375,9 +375,9 @@ def libE_tcp_mgr(sim_specs, gen_specs, exit_criteria,
     launchf = libE_tcp_worker_launcher(libE_specs)
 
     # Get worker launch parameters and fill in defaults for TCP/IP conn
-    if 'nprocesses' in libE_specs:
+    if 'nworkers' in libE_specs:
         workers = None
-        nworkers = libE_specs['nprocesses']
+        nworkers = libE_specs['nworkers']
     elif 'workers' in libE_specs:
         workers = libE_specs['workers']
         nworkers = len(workers)
diff --git a/libensemble/tests/scaling_tests/forces/run_libe_forces.py b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
index d0ed23af8..27ab74cca 100644
--- a/libensemble/tests/scaling_tests/forces/run_libe_forces.py
+++ b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
@@ -30,7 +30,7 @@
         print("WARNING: nworkers not passed to script - defaulting to 4")
         nworkers = 4
     is_master = True  # processes are forked in libE
-    libE_specs = {'nprocesses': nworkers, 'comms': 'local'}
+    libE_specs = {'nworkers': nworkers, 'comms': 'local'}
 
 if is_master:
     print('\nRunning with {} workers\n'.format(nworkers))
diff --git a/libensemble/utils.py b/libensemble/utils.py
index 30e9b5b2f..b14a27491 100644
--- a/libensemble/utils.py
+++ b/libensemble/utils.py
@@ -51,7 +51,7 @@
                           'port',                #
                           'authkey',             #
                           'workerID',            #
-                          'nprocesses',          #
+                          'nworkers',          #
                           'worker_cmd',          #
                           'abort_on_exception',  #
                           'sim_dir',             #
@@ -107,10 +107,10 @@ def check_libE_specs(libE_specs, serial_check=False):
         if not serial_check:
             assert libE_specs['comm'].Get_size() > 1, "Manager only - must be at least one worker (2 MPI tasks)"
     elif comms_type in ['local']:
-        assert libE_specs['nprocesses'] >= 1, "Must specify at least one worker"
+        assert libE_specs['nworkers'] >= 1, "Must specify at least one worker"
     elif comms_type in ['tcp']:
         # TODO, differentiate and test SSH/Client
-        assert libE_specs['nprocesses'] >= 1, "Must specify at least one worker"
+        assert libE_specs['nworkers'] >= 1, "Must specify at least one worker"
 
     for k in libE_specs.keys():
         assert k in allowed_libE_spec_keys, "Key %s is not allowed in libE_specs. Supported keys are: %s " % (k, allowed_libE_spec_keys)
@@ -276,7 +276,7 @@ def mpi_parse_args(args):
 def local_parse_args(args):
     "Parse arguments for forked processes using multiprocessing."
     nworkers = args.nworkers or 4
-    libE_specs = {'nprocesses': nworkers, 'comms': 'local'}
+    libE_specs = {'nworkers': nworkers, 'comms': 'local'}
     return nworkers, True, libE_specs, args.tester_args
 
 
@@ -288,7 +288,7 @@ def tcp_parse_args(args):
         "{manager_ip}", "{manager_port}", "{authkey}", "--workerID",
         "{workerID}", "--nworkers",
         str(nworkers)]
-    libE_specs = {'nprocesses': nworkers, 'worker_cmd': cmd, 'comms': 'tcp'}
+    libE_specs = {'nworkers': nworkers, 'worker_cmd': cmd, 'comms': 'tcp'}
     return nworkers, True, libE_specs, args.tester_args
 
 
@@ -323,7 +323,7 @@ def client_parse_args(args):
                   'port': int(port),
                   'authkey': authkey.encode('utf-8'),
                   'workerID': args.workerID,
-                  'nprocesses': nworkers,
+                  'nworkers': nworkers,
                   'comms': 'tcp'}
     return nworkers, False, libE_specs, args.tester_args
 

From 35ada944a358c50fcc711dcb43f33b043bfcc78a Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 15 Nov 2019 12:36:09 -0600
Subject: [PATCH 534/644] Removing unnecessary files

---
 docs/appendix.rst    | 10 ----------
 docs/dev_info.rst    |  8 --------
 docs/latex_index.rst | 25 +++++++++++++++++++++++--
 3 files changed, 23 insertions(+), 20 deletions(-)
 delete mode 100644 docs/appendix.rst
 delete mode 100644 docs/dev_info.rst

diff --git a/docs/appendix.rst b/docs/appendix.rst
deleted file mode 100644
index c642ae13e..000000000
--- a/docs/appendix.rst
+++ /dev/null
@@ -1,10 +0,0 @@
-Appendices
-==========
-
-.. toctree::
-   tutorials/tutorials
-   FAQ
-   known_issues
-   examples/examples_index
-   release_notes
-   bibliography
diff --git a/docs/dev_info.rst b/docs/dev_info.rst
deleted file mode 100644
index 4c4fdab68..000000000
--- a/docs/dev_info.rst
+++ /dev/null
@@ -1,8 +0,0 @@
-Developer's Guide
-=================
-
-.. toctree::
-
-   contributing
-   dev_guide/dev_API/developer_API.rst
-   dev_guide/release_management/release_index.rst
diff --git a/docs/latex_index.rst b/docs/latex_index.rst
index 8ca9be61b..f8643b832 100644
--- a/docs/latex_index.rst
+++ b/docs/latex_index.rst
@@ -8,5 +8,26 @@
    Introduction<introduction_latex>
    programming_libE
    platforms/platforms_index
-   dev_info
-   appendix
+
+Developer's Guide
+=================
+
+.. toctree::
+   :maxdepth: 3
+
+   contributing
+   dev_guide/dev_API/developer_API.rst
+   dev_guide/release_management/release_index.rst
+
+Appendices
+==========
+
+.. toctree::
+   :maxdepth: 3
+
+   tutorials/tutorials
+   FAQ
+   known_issues
+   examples/examples_index
+   release_notes
+   bibliography

From eeef9bb4d34009ea21a5362eaf721cb68e859caf Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 15 Nov 2019 13:34:35 -0600
Subject: [PATCH 535/644] Slight renames, adding bibliography to html

---
 docs/index.rst              | 1 +
 docs/introduction_latex.rst | 4 ++--
 docs/latex_index.rst        | 3 ++-
 3 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index 9d784d684..a4e1e59eb 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -30,6 +30,7 @@
    known_issues
    release_notes
    contributing
+   bibliography
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/introduction_latex.rst b/docs/introduction_latex.rst
index 8a85f4686..e287bb7a7 100644
--- a/docs/introduction_latex.rst
+++ b/docs/introduction_latex.rst
@@ -13,8 +13,8 @@ Example Use Cases
 .. include:: overview_usecases.rst
     :start-after: begin_usecases_rst_tag
 
-Further Information
-===================
+Quickstart Guide
+================
 .. include:: ../README.rst
     :start-after: before_dependencies_rst_tag
     :end-before: after_resources_rst_tag
diff --git a/docs/latex_index.rst b/docs/latex_index.rst
index f8643b832..76e999e3b 100644
--- a/docs/latex_index.rst
+++ b/docs/latex_index.rst
@@ -30,4 +30,5 @@ Appendices
    known_issues
    examples/examples_index
    release_notes
-   bibliography
+
+.. bibliography:: references.bib

From aa16c8a6afd2136dd5414357edd2a66b54e1c550 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 15 Nov 2019 14:20:12 -0600
Subject: [PATCH 536/644] parse_args in __all__ for addition from other PR

---
 libensemble/utils.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/utils.py b/libensemble/utils.py
index a9bced316..7bb74e657 100644
--- a/libensemble/utils.py
+++ b/libensemble/utils.py
@@ -4,7 +4,7 @@
 
 """
 
-__all__ = ['check_inputs']
+__all__ = ['check_inputs', 'parse_args']
 
 import traceback
 import logging

From 9d99157a4ad6eea5d81dc0dcf7e3f5538ce92f10 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 15 Nov 2019 14:23:41 -0600
Subject: [PATCH 537/644] Update index.rst

---
 docs/index.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/index.rst b/docs/index.rst
index a4e1e59eb..fd47b94a3 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -24,7 +24,7 @@
 
 .. toctree::
    :maxdepth: 2
-   :caption: Additional Reference:
+   :caption: Additional References:
 
    FAQ
    known_issues

From 81065f87b2d6847edc8e2c0897bf95371751f32e Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 15 Nov 2019 14:32:28 -0600
Subject: [PATCH 538/644] Revert "parse_args in __all__ for addition from other
 PR"

This reverts commit aa16c8a6afd2136dd5414357edd2a66b54e1c550.
---
 libensemble/utils.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/utils.py b/libensemble/utils.py
index 7bb74e657..a9bced316 100644
--- a/libensemble/utils.py
+++ b/libensemble/utils.py
@@ -4,7 +4,7 @@
 
 """
 
-__all__ = ['check_inputs', 'parse_args']
+__all__ = ['check_inputs']
 
 import traceback
 import logging

From 257459d509f132b38197434dbe4579b60682d89b Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 15 Nov 2019 15:12:26 -0600
Subject: [PATCH 539/644] Main libE module with own heading under Programming

---
 docs/libe_module.rst      | 6 ++++++
 docs/programming_libE.rst | 5 +----
 2 files changed, 7 insertions(+), 4 deletions(-)
 create mode 100644 docs/libe_module.rst

diff --git a/docs/libe_module.rst b/docs/libe_module.rst
new file mode 100644
index 000000000..4b5f6c024
--- /dev/null
+++ b/docs/libe_module.rst
@@ -0,0 +1,6 @@
+The Main libE Module
+====================
+
+.. automodule:: libE
+   :members:
+   :no-undoc-members:
diff --git a/docs/programming_libE.rst b/docs/programming_libE.rst
index 2a4d42b0a..4c99ee5ba 100644
--- a/docs/programming_libE.rst
+++ b/docs/programming_libE.rst
@@ -1,11 +1,8 @@
 Programming with libEnsemble
 ============================
 
-.. automodule:: libE
-  :members:
-  :no-undoc-members:
-
 .. toctree::
+   libe_module
    history_output
    data_structures/data_structures
 

From 960c7035447fdac488a04d7a2732c5f077d7fddb Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 15 Nov 2019 15:15:46 -0600
Subject: [PATCH 540/644] small wording changes

---
 docs/overview_usecases.rst |  2 +-
 libensemble/libE.py        | 10 +++++-----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/overview_usecases.rst b/docs/overview_usecases.rst
index 6fdc1e69e..47a552a75 100644
--- a/docs/overview_usecases.rst
+++ b/docs/overview_usecases.rst
@@ -7,7 +7,7 @@ Overview
 
 libEnsemble is a Python library to coordinate the concurrent evaluation of
 dynamic ensembles of calculations. libEnsemble uses a manager to allocate work to
-various workers. A libEnsemble worker is the smallest indivisible unit to
+multiple workers. A libEnsemble worker is the smallest indivisible unit to
 perform some calculation. The work performed by libEnsemble is governed by
 three routines:
 
diff --git a/libensemble/libE.py b/libensemble/libE.py
index a4468e1b3..39c5022c4 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -1,13 +1,13 @@
 """
 This is the outer libEnsemble routine.
 
-We dispatch to different types of worker teams depending on the contents of
-``libE_specs``.  If ``'comm'`` is a field, MPI is used; if ``'nthreads'`` is a
-field, threads are used ; if ``'nprocesses'`` is a field, multiprocessing is
-used.
+libEnsemble dispatches to different types of worker teams depending on the
+contents of ``libE_specs``.  If ``'comm'`` is a field, MPI is used; if
+``'nthreads'`` is a field, threads are used ; if ``'nworkers'`` is a field,
+multiprocessing is used.
 
 If an exception is encountered by the manager or workers, the
-history array is dumped to file and MPI abort is called.
+History array is dumped to file and MPI abort is called.
 """
 
 __all__ = ['libE']

From 05e3d353ffcb2cb00f1b274a75d55adb81c70720 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 15 Nov 2019 15:40:04 -0600
Subject: [PATCH 541/644] reword libE module description

---
 libensemble/libE.py | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

diff --git a/libensemble/libE.py b/libensemble/libE.py
index 39c5022c4..141962ed5 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -1,13 +1,15 @@
 """
 This is the outer libEnsemble routine.
 
-libEnsemble dispatches to different types of worker teams depending on the
-contents of ``libE_specs``.  If ``'comm'`` is a field, MPI is used; if
-``'nthreads'`` is a field, threads are used ; if ``'nworkers'`` is a field,
-multiprocessing is used.
-
-If an exception is encountered by the manager or workers, the
-History array is dumped to file and MPI abort is called.
+This module sets up the manager and the team of workers, configured according
+to the contents of the 'libE_specs' dictionary. The Manager/Worker
+communications scheme used within libEnsemble is parsed from the 'comms' key
+if present, with valid values being 'MPI', 'local' (for multiprocessing), or
+'TCP'. MPI is the default. If no communication scheme or MPI communicator is
+specified, a duplicate of COMM_WORLD will be used.
+
+If an exception is encountered by the manager or workers, the history array
+is dumped to file and MPI abort is called.
 """
 
 __all__ = ['libE']

From 20b7bb9da289ef2907c7202871f85e8eb6d9a09e Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 15 Nov 2019 15:43:30 -0600
Subject: [PATCH 542/644] formatting

---
 libensemble/libE.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/libensemble/libE.py b/libensemble/libE.py
index 141962ed5..9d04db23d 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -2,10 +2,10 @@
 This is the outer libEnsemble routine.
 
 This module sets up the manager and the team of workers, configured according
-to the contents of the 'libE_specs' dictionary. The Manager/Worker
-communications scheme used within libEnsemble is parsed from the 'comms' key
-if present, with valid values being 'MPI', 'local' (for multiprocessing), or
-'TCP'. MPI is the default. If no communication scheme or MPI communicator is
+to the contents of the ``libE_specs`` dictionary. The Manager/Worker
+communications scheme used within libEnsemble is parsed from the ``comms`` key
+if present, with valid values being ``MPI``, ``local`` (for multiprocessing), or
+``TCP``. MPI is the default. If no communication scheme or MPI communicator is
 specified, a duplicate of COMM_WORLD will be used.
 
 If an exception is encountered by the manager or workers, the history array

From 100b295fd59497f160eaa07fc65072cb3d770679 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 15 Nov 2019 15:55:59 -0600
Subject: [PATCH 543/644] rewording comms statement

---
 libensemble/libE.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/libensemble/libE.py b/libensemble/libE.py
index 9d04db23d..c30c03361 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -5,8 +5,8 @@
 to the contents of the ``libE_specs`` dictionary. The Manager/Worker
 communications scheme used within libEnsemble is parsed from the ``comms`` key
 if present, with valid values being ``MPI``, ``local`` (for multiprocessing), or
-``TCP``. MPI is the default. If no communication scheme or MPI communicator is
-specified, a duplicate of COMM_WORLD will be used.
+``TCP``. MPI is the default; if no communicator is specified, a duplicate of
+COMM_WORLD will be used.
 
 If an exception is encountered by the manager or workers, the history array
 is dumped to file and MPI abort is called.

From 32fe9011966aae89514b759d73dc81f14419e3c1 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 15 Nov 2019 15:59:58 -0600
Subject: [PATCH 544/644] lowercase

---
 libensemble/libE.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/libensemble/libE.py b/libensemble/libE.py
index c30c03361..c63229e82 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -4,8 +4,8 @@
 This module sets up the manager and the team of workers, configured according
 to the contents of the ``libE_specs`` dictionary. The Manager/Worker
 communications scheme used within libEnsemble is parsed from the ``comms`` key
-if present, with valid values being ``MPI``, ``local`` (for multiprocessing), or
-``TCP``. MPI is the default; if no communicator is specified, a duplicate of
+if present, with valid values being ``mpi``, ``local`` (for multiprocessing), or
+``tcp``. MPI is the default; if no communicator is specified, a duplicate of
 COMM_WORLD will be used.
 
 If an exception is encountered by the manager or workers, the history array

From 1318f3fefe77cc9cb9f02678daf04916da9068d6 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Fri, 15 Nov 2019 17:06:08 -0600
Subject: [PATCH 545/644] fix single test

---
 .../regression_tests/test_6-hump_camel_uniform_sampling.py      | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
index f43f35567..f0d1bb809 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
@@ -20,7 +20,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel
 from libensemble.gen_funcs.sampling import uniform_random_sample
-from libensemble.tests.regression_tests.common import parse_args, save_libE_output, per_worker_stream
+from libensemble.tests.utils import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 
 nworkers, is_master, libE_specs, _ = parse_args()

From 511a9f8b28b52026229e11debde9da0fed7f972d Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Fri, 15 Nov 2019 17:50:25 -0600
Subject: [PATCH 546/644] Fix another single test

---
 .../regression_tests/test_6-hump_camel_uniform_sampling.py      | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
index f0d1bb809..e030d972c 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
@@ -20,7 +20,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel
 from libensemble.gen_funcs.sampling import uniform_random_sample
-from libensemble.tests.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, per_worker_stream
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 
 nworkers, is_master, libE_specs, _ = parse_args()

From d71b8f0098201a0e6ea7be020d01d06522cb5a37 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Mon, 18 Nov 2019 11:20:08 -0600
Subject: [PATCH 547/644] Renaming per_worker_streams, add a doc string, and
 changing an argument name

---
 .../tests/regression_tests/script_test_balsam_hworld.py     | 4 ++--
 libensemble/tests/regression_tests/test_1d_sampling.py      | 4 ++--
 .../test_1d_uniform_sampling_with_comm_dup.py               | 4 ++--
 .../test_6-hump_camel_active_persistent_worker_abort.py     | 4 ++--
 .../regression_tests/test_6-hump_camel_aposmm_LD_MMA.py     | 4 ++--
 .../test_6-hump_camel_elapsed_time_abort.py                 | 4 ++--
 .../test_6-hump_camel_persistent_aposmm_1.py                | 4 ++--
 .../test_6-hump_camel_persistent_aposmm_2.py                | 4 ++--
 .../test_6-hump_camel_persistent_aposmm_3.py                | 4 ++--
 .../test_6-hump_camel_persistent_aposmm_4.py                | 4 ++--
 .../test_6-hump_camel_persistent_uniform_sampling.py        | 4 ++--
 .../regression_tests/test_6-hump_camel_uniform_sampling.py  | 4 ++--
 ..._camel_uniform_sampling_with_persistent_localopt_gens.py | 4 ++--
 ...test_6-hump_camel_with_different_nodes_uniform_sample.py | 4 ++--
 .../test_branin_aposmm_nlopt_and_then_scipy.py              | 4 ++--
 libensemble/tests/regression_tests/test_calc_exception.py   | 4 ++--
 .../test_chwirut_aposmm_one_residual_at_a_time.py           | 4 ++--
 libensemble/tests/regression_tests/test_chwirut_pounders.py | 4 ++--
 .../regression_tests/test_chwirut_pounders_persistent.py    | 4 ++--
 .../regression_tests/test_chwirut_pounders_splitcomm.py     | 4 ++--
 .../tests/regression_tests/test_chwirut_pounders_subcomm.py | 4 ++--
 .../test_chwirut_uniform_sampling_one_residual_at_a_time.py | 4 ++--
 libensemble/tests/regression_tests/test_comms.py            | 4 ++--
 libensemble/tests/regression_tests/test_fast_alloc.py       | 4 ++--
 .../tests/regression_tests/test_inverse_bayes_example.py    | 4 ++--
 .../tests/regression_tests/test_jobcontroller_hworld.py     | 4 ++--
 libensemble/tests/regression_tests/test_nan_func_aposmm.py  | 4 ++--
 .../tests/regression_tests/test_worker_exceptions.py        | 4 ++--
 libensemble/utils.py                                        | 6 ++++--
 29 files changed, 60 insertions(+), 58 deletions(-)

diff --git a/libensemble/tests/regression_tests/script_test_balsam_hworld.py b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
index 4b02032c1..47bce6751 100644
--- a/libensemble/tests/regression_tests/script_test_balsam_hworld.py
+++ b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
@@ -11,7 +11,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.job_control_hworld import job_control_hworld as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
-from libensemble.utils import per_worker_stream
+from libensemble.utils import add_unique_random_streams
 
 mpi4py.rc.recv_mprobe = False  # Disable matching probes
 
@@ -56,7 +56,7 @@ def build_simfunc():
                       'num_active_gens': 1}
              }
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 exit_criteria = {'elapsed_wallclock_time': 35}
 
diff --git a/libensemble/tests/regression_tests/test_1d_sampling.py b/libensemble/tests/regression_tests/test_1d_sampling.py
index beb826a62..992e12b9c 100644
--- a/libensemble/tests/regression_tests/test_1d_sampling.py
+++ b/libensemble/tests/regression_tests/test_1d_sampling.py
@@ -19,7 +19,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.one_d_func import one_d_example as sim_f
 from libensemble.gen_funcs.sampling import latin_hypercube_sample as gen_f
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 
 nworkers, is_master, libE_specs, _ = parse_args()
 libE_specs['save_every_k_gens'] = 300
@@ -34,7 +34,7 @@
                       }
              }
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 exit_criteria = {'gen_max': 501}
 
diff --git a/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py b/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
index d677df940..139b4e622 100644
--- a/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
+++ b/libensemble/tests/regression_tests/test_1d_uniform_sampling_with_comm_dup.py
@@ -23,7 +23,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.one_d_func import one_d_example as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
@@ -51,7 +51,7 @@
                       }
              }
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 exit_criteria = {'gen_max': 501}
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py b/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py
index 7a48aeaa7..63cb9485f 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py
@@ -22,7 +22,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.uniform_or_localopt import uniform_or_localopt as gen_f
 from libensemble.alloc_funcs.start_persistent_local_opt_gens import start_persistent_local_opt_gens as alloc_f
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 from libensemble.tests.regression_tests.support import uniform_or_localopt_gen_out as gen_out
 
 nworkers, is_master, libE_specs, _ = parse_args()
@@ -46,7 +46,7 @@
 
 alloc_specs = {'alloc_f': alloc_f, 'out': gen_out, 'user': {'batch_mode': True}}
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 # Set sim_max small so persistent worker is quickly terminated
 exit_criteria = {'sim_max': 10, 'elapsed_wallclock_time': 300}
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
index 52ad3004c..8388189bb 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
@@ -22,7 +22,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.alloc_funcs.fast_alloc_to_aposmm import give_sim_work_first as alloc_f
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 from libensemble.tests.regression_tests.support import persis_info_1 as persis_info, aposmm_gen_out as gen_out, six_hump_camel_minima as minima
 
 nworkers, is_master, libE_specs, _ = parse_args()
@@ -51,7 +51,7 @@
 
 alloc_specs = {'alloc_f': alloc_f, 'out': [('allocated', bool)], 'user': {'batch_mode': True}}
 
-persis_info = per_worker_stream(persis_info, nworkers + 1)
+persis_info = add_unique_random_streams(persis_info, nworkers + 1)
 persis_info_safe = deepcopy(persis_info)
 
 exit_criteria = {'sim_max': 1000}
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py b/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
index c4021df37..0a4602523 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
@@ -21,7 +21,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
 from libensemble.alloc_funcs.give_sim_work_first import give_sim_work_first
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream, eprint
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams, eprint
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
@@ -44,7 +44,7 @@
                'out': [('allocated', bool)],
                'user': {'batch_mode': False}}
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 exit_criteria = {'elapsed_wallclock_time': 1}
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
index 7c2b51f28..2ac709b55 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
@@ -23,7 +23,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
 from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 from time import time
 
@@ -60,7 +60,7 @@
 
 alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)], 'user': {'batch_mode': True}}
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 exit_criteria = {'sim_max': 1000}
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
index 53b3c19fd..d238e2ae0 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_2.py
@@ -23,7 +23,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
 from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 from time import time
 
@@ -61,7 +61,7 @@
 
 alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)], 'user': {'batch_mode': True}}
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 exit_criteria = {'sim_max': 1000}
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
index b016f7a1e..dfb537f01 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_3.py
@@ -23,7 +23,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
 from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 from time import time
 
@@ -61,7 +61,7 @@
 
 alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)], 'user': {'batch_mode': True}}
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 exit_criteria = {'sim_max': 1000}
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
index 7d8b16eca..dff42efc3 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_4.py
@@ -22,7 +22,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
 from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 from time import time
 
@@ -61,7 +61,7 @@
 
 alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)], 'user': {'batch_mode': True}}
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 exit_criteria = {'sim_max': 2000}
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py
index 3344eff6b..1aaa1a6ac 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py
@@ -22,7 +22,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel as sim_f
 from libensemble.gen_funcs.persistent_uniform_sampling import persistent_uniform as gen_f
 from libensemble.alloc_funcs.start_only_persistent import only_persistent_gens as alloc_f
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
@@ -44,7 +44,7 @@
 
 alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)]}
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 exit_criteria = {'gen_max': 40, 'elapsed_wallclock_time': 300}
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
index e030d972c..c913d5945 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
@@ -20,7 +20,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel
 from libensemble.gen_funcs.sampling import uniform_random_sample
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 
 nworkers, is_master, libE_specs, _ = parse_args()
@@ -42,7 +42,7 @@
              }
 # end_gen_specs_rst_tag
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 exit_criteria = {'gen_max': 501, 'elapsed_wallclock_time': 300}
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
index 4d48ed7c2..edfc37371 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
@@ -23,7 +23,7 @@
 from libensemble.gen_funcs.uniform_or_localopt import uniform_or_localopt as gen_f
 from libensemble.alloc_funcs.start_persistent_local_opt_gens import start_persistent_local_opt_gens as alloc_f
 from libensemble.tests.regression_tests.support import uniform_or_localopt_gen_out as gen_out
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 
 nworkers, is_master, libE_specs, _ = parse_args()
@@ -51,7 +51,7 @@
 
 alloc_specs = {'alloc_f': alloc_f, 'out': gen_out, 'user': {'batch_mode': True}}
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 exit_criteria = {'sim_max': 1000, 'elapsed_wallclock_time': 300}
 
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py b/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
index 9b50710cb..a0575ba09 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
@@ -22,7 +22,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel_with_different_ranks_and_nodes as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample_with_different_nodes_and_ranks as gen_f
 from libensemble.alloc_funcs.give_sim_work_first import give_sim_work_first
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
@@ -70,7 +70,7 @@
                'out': [('allocated', bool)],
                'user': {'batch_mode': False}}
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 exit_criteria = {'sim_max': 10, 'elapsed_wallclock_time': 300}
 
diff --git a/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py b/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
index 71767a494..0d575297b 100644
--- a/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
+++ b/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
@@ -21,7 +21,7 @@
 from libensemble.sim_funcs.branin.branin_obj import call_branin as sim_f
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.tests.regression_tests.support import persis_info_2 as persis_info, aposmm_gen_out as gen_out, branin_vals_and_minima as M
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
@@ -60,7 +60,7 @@
                       'max_active_runs': 3}
              }
 
-persis_info = per_worker_stream(persis_info, nworkers + 1)
+persis_info = add_unique_random_streams(persis_info, nworkers + 1)
 persis_info_safe = deepcopy(persis_info)
 
 # Tell libEnsemble when to stop (stop_val key must be in H)
diff --git a/libensemble/tests/regression_tests/test_calc_exception.py b/libensemble/tests/regression_tests/test_calc_exception.py
index f7cf98b19..869fbc14a 100644
--- a/libensemble/tests/regression_tests/test_calc_exception.py
+++ b/libensemble/tests/regression_tests/test_calc_exception.py
@@ -18,7 +18,7 @@
 from libensemble.libE import libE
 from libensemble.libE_manager import ManagerException
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
-from libensemble.utils import parse_args, per_worker_stream
+from libensemble.utils import parse_args, add_unique_random_streams
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
@@ -38,7 +38,7 @@ def six_hump_camel_err(H, persis_info, sim_specs, _):
                       'gen_batch_size': 10}
              }
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 exit_criteria = {'elapsed_wallclock_time': 10}
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py b/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py
index fd59b09e6..024d67c72 100644
--- a/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py
+++ b/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py
@@ -20,7 +20,7 @@
 from libensemble.sim_funcs.chwirut1 import chwirut_eval as sim_f
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.alloc_funcs.fast_alloc_and_pausing import give_sim_work_first as alloc_f
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 from libensemble.tests.regression_tests.support import persis_info_3 as persis_info, aposmm_gen_out as gen_out
 
 nworkers, is_master, libE_specs, _ = parse_args()
@@ -64,7 +64,7 @@
                         'stop_partial_fvec_eval': True}
                }
 
-persis_info = per_worker_stream(persis_info, nworkers + 1)
+persis_info = add_unique_random_streams(persis_info, nworkers + 1)
 
 exit_criteria = {'sim_max': budget, 'elapsed_wallclock_time': 300}
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders.py b/libensemble/tests/regression_tests/test_chwirut_pounders.py
index aca432e06..c0bca13bf 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders.py
@@ -20,7 +20,7 @@
 from libensemble.sim_funcs.chwirut1 import chwirut_eval as sim_f
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.tests.regression_tests.support import persis_info_2 as persis_info, aposmm_gen_out as gen_out
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
@@ -52,7 +52,7 @@
 
 gen_specs['user'].update({'grtol': 1e-4, 'gatol': 1e-4, 'frtol': 1e-15, 'fatol': 1e-15})
 
-persis_info = per_worker_stream(persis_info, nworkers + 1)
+persis_info = add_unique_random_streams(persis_info, nworkers + 1)
 
 exit_criteria = {'sim_max': budget, 'elapsed_wallclock_time': 300}
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
index cb013ef0e..f78019c94 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_persistent.py
@@ -23,7 +23,7 @@
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
 from libensemble.gen_funcs.sampling import lhs_sample
 from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
@@ -63,7 +63,7 @@
 
 alloc_specs = {'alloc_f': alloc_f, 'out': [('given_back', bool)], 'user': {'batch_mode': True}}
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 exit_criteria = {'sim_max': 500}
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py b/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
index 9cd7a7fb7..1ddef0752 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_splitcomm.py
@@ -22,7 +22,7 @@
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.tests.regression_tests.support import persis_info_2 as persis_info, aposmm_gen_out as gen_out
 from libensemble.tests.regression_tests.common import mpi_comm_split
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 
 num_comms = 2  # Must have atleast num_comms*2 processors
 nworkers, is_master, libE_specs, _ = parse_args()
@@ -57,7 +57,7 @@
 
 gen_specs['user'].update({'grtol': 1e-4, 'gatol': 1e-4, 'frtol': 1e-15, 'fatol': 1e-15})
 
-persis_info = per_worker_stream(persis_info, nworkers + 1)
+persis_info = add_unique_random_streams(persis_info, nworkers + 1)
 
 exit_criteria = {'sim_max': budget, 'elapsed_wallclock_time': 300}
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py b/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
index 87ae4ead8..8678e25c8 100644
--- a/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
+++ b/libensemble/tests/regression_tests/test_chwirut_pounders_subcomm.py
@@ -21,7 +21,7 @@
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
 from libensemble.tests.regression_tests.support import persis_info_2 as persis_info, aposmm_gen_out as gen_out
 from libensemble.tests.regression_tests.common import mpi_comm_excl
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 
 nworkers, is_master, libE_specs, _ = parse_args()
 libE_specs['comm'], mpi_comm_null = mpi_comm_excl()
@@ -61,7 +61,7 @@
 
 gen_specs['user'].update({'grtol': 1e-4, 'gatol': 1e-4, 'frtol': 1e-15, 'fatol': 1e-15})
 
-persis_info = per_worker_stream(persis_info, nworkers + 1)
+persis_info = add_unique_random_streams(persis_info, nworkers + 1)
 
 exit_criteria = {'sim_max': budget, 'elapsed_wallclock_time': 300}
 
diff --git a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
index 1f9aad506..8d7c3d497 100644
--- a/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
+++ b/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
@@ -27,7 +27,7 @@
 from libensemble.gen_funcs.sampling import uniform_random_sample_obj_components as gen_f
 from libensemble.alloc_funcs.fast_alloc_and_pausing import give_sim_work_first
 from libensemble.tests.regression_tests.support import persis_info_3 as persis_info
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 
 nworkers, is_master, libE_specs, _ = parse_args()
 if libE_specs['comms'] == 'tcp':
@@ -72,7 +72,7 @@
                }
 # end_alloc_specs_rst_tag
 
-persis_info = per_worker_stream(persis_info, nworkers + 1)
+persis_info = add_unique_random_streams(persis_info, nworkers + 1)
 persis_info_safe = deepcopy(persis_info)
 
 exit_criteria = {'sim_max': budget, 'elapsed_wallclock_time': 300}
diff --git a/libensemble/tests/regression_tests/test_comms.py b/libensemble/tests/regression_tests/test_comms.py
index 7161c6883..9fe421f27 100644
--- a/libensemble/tests/regression_tests/test_comms.py
+++ b/libensemble/tests/regression_tests/test_comms.py
@@ -20,7 +20,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.comms_testing import float_x1000 as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 from libensemble.mpi_controller import MPIJobController  # Only used to get workerID in float_x1000
 jobctrl = MPIJobController(auto_resources=False)
 
@@ -43,7 +43,7 @@
                       'num_active_gens': 1}
              }
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 exit_criteria = {'sim_max': sim_max, 'elapsed_wallclock_time': 300}
 
diff --git a/libensemble/tests/regression_tests/test_fast_alloc.py b/libensemble/tests/regression_tests/test_fast_alloc.py
index 5a2043b0f..0f570e3bb 100644
--- a/libensemble/tests/regression_tests/test_fast_alloc.py
+++ b/libensemble/tests/regression_tests/test_fast_alloc.py
@@ -21,7 +21,7 @@
 from libensemble.sim_funcs.six_hump_camel import six_hump_camel_simple as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
 from libensemble.alloc_funcs.fast_alloc import give_sim_work_first as alloc_f
-from libensemble.utils import parse_args, per_worker_stream
+from libensemble.utils import parse_args, add_unique_random_streams
 
 nworkers, is_master, libE_specs, _ = parse_args()
 
@@ -40,7 +40,7 @@
 
 alloc_specs = {'alloc_f': alloc_f, 'out': [('allocated', bool)]}
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 exit_criteria = {'sim_max': num_pts, 'elapsed_wallclock_time': 300}
 
diff --git a/libensemble/tests/regression_tests/test_inverse_bayes_example.py b/libensemble/tests/regression_tests/test_inverse_bayes_example.py
index f9b45b60e..84009a37a 100644
--- a/libensemble/tests/regression_tests/test_inverse_bayes_example.py
+++ b/libensemble/tests/regression_tests/test_inverse_bayes_example.py
@@ -24,7 +24,7 @@
 from libensemble.sim_funcs.inverse_bayes import likelihood_calculator as sim_f
 from libensemble.gen_funcs.persistent_inverse_bayes import persistent_updater_after_likelihood as gen_f
 from libensemble.alloc_funcs.inverse_bayes_allocf import only_persistent_gens_for_inverse_bayes as alloc_f
-from libensemble.utils import parse_args, per_worker_stream
+from libensemble.utils import parse_args, add_unique_random_streams
 
 # Parse args for test code
 nworkers, is_master, libE_specs, _ = parse_args()
@@ -45,7 +45,7 @@
                       'num_batches': 10}
              }
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 # Tell libEnsemble when to stop
 exit_criteria = {
diff --git a/libensemble/tests/regression_tests/test_jobcontroller_hworld.py b/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
index 95289cfe2..ecbece153 100644
--- a/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
+++ b/libensemble/tests/regression_tests/test_jobcontroller_hworld.py
@@ -21,7 +21,7 @@
 from libensemble.libE import libE
 from libensemble.sim_funcs.job_control_hworld import job_control_hworld as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
-from libensemble.utils import parse_args, per_worker_stream
+from libensemble.utils import parse_args, add_unique_random_streams
 from libensemble.tests.regression_tests.common import build_simfunc
 
 # Do not change these lines - they are parsed by run-tests.sh
@@ -82,7 +82,7 @@
                       }
              }
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 exit_criteria = {'elapsed_wallclock_time': 10}
 
diff --git a/libensemble/tests/regression_tests/test_nan_func_aposmm.py b/libensemble/tests/regression_tests/test_nan_func_aposmm.py
index bb8d5f1dc..0f9afa640 100644
--- a/libensemble/tests/regression_tests/test_nan_func_aposmm.py
+++ b/libensemble/tests/regression_tests/test_nan_func_aposmm.py
@@ -19,7 +19,7 @@
 from libensemble.libE import libE
 from support import nan_func as sim_f, aposmm_gen_out as gen_out
 from libensemble.gen_funcs.aposmm import aposmm_logic as gen_f
-from libensemble.utils import parse_args, save_libE_output, per_worker_stream
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 
 nworkers, is_master, libE_specs, _ = parse_args()
 n = 2
@@ -44,7 +44,7 @@
     gen_specs['user']['components'] = 1
     gen_specs['user']['combine_component_func'] = np.linalg.norm
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 # Tell libEnsemble when to stop
 exit_criteria = {'sim_max': 100, 'elapsed_wallclock_time': 300}
diff --git a/libensemble/tests/regression_tests/test_worker_exceptions.py b/libensemble/tests/regression_tests/test_worker_exceptions.py
index a8db08e2a..8645c0ca2 100644
--- a/libensemble/tests/regression_tests/test_worker_exceptions.py
+++ b/libensemble/tests/regression_tests/test_worker_exceptions.py
@@ -19,7 +19,7 @@
 from libensemble.tests.regression_tests.support import nan_func as sim_f
 from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
 from libensemble.libE_manager import ManagerException
-from libensemble.utils import parse_args, per_worker_stream
+from libensemble.utils import parse_args, add_unique_random_streams
 
 nworkers, is_master, libE_specs, _ = parse_args()
 n = 2
@@ -35,7 +35,7 @@
                       'num_active_gens': 1}
              }
 
-persis_info = per_worker_stream({}, nworkers + 1)
+persis_info = add_unique_random_streams({}, nworkers + 1)
 
 libE_specs['abort_on_exception'] = False
 
diff --git a/libensemble/utils.py b/libensemble/utils.py
index 527852476..63c992cf0 100644
--- a/libensemble/utils.py
+++ b/libensemble/utils.py
@@ -362,8 +362,10 @@ def save_libE_output(H, persis_info, calling_file, nworkers):
 # ===================== per-worker numpy random-streams ========================
 
 
-def per_worker_stream(persis_info, nworkers):
-    for i in range(nworkers):
+def add_unique_random_streams(persis_info, size):
+    # Used to create a random number stream for the libE manager and workers
+    # (when size = 1 + num_workers). Stream i is initialized with seed=i. 
+    for i in range(size):
         if i in persis_info:
             persis_info[i].update({
                 'rand_stream': np.random.RandomState(i),

From 771e0a1de5d59037cef3589e72ba2c1df71b9e63 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Mon, 18 Nov 2019 11:30:45 -0600
Subject: [PATCH 548/644] one space removed

---
 libensemble/utils.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/utils.py b/libensemble/utils.py
index 63c992cf0..39cb72727 100644
--- a/libensemble/utils.py
+++ b/libensemble/utils.py
@@ -364,7 +364,7 @@ def save_libE_output(H, persis_info, calling_file, nworkers):
 
 def add_unique_random_streams(persis_info, size):
     # Used to create a random number stream for the libE manager and workers
-    # (when size = 1 + num_workers). Stream i is initialized with seed=i. 
+    # (when size = 1 + num_workers). Stream i is initialized with seed=i.
     for i in range(size):
         if i in persis_info:
             persis_info[i].update({

From 95d0f25f54ac84d31cc08f829096c36777c1f55f Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 18 Nov 2019 12:01:41 -0600
Subject: [PATCH 549/644] move manager exception back to libe

---
 libensemble/libE.py  | 31 ++++++++++++++++++++++++++++---
 libensemble/utils.py | 23 +----------------------
 2 files changed, 29 insertions(+), 25 deletions(-)

diff --git a/libensemble/libE.py b/libensemble/libE.py
index 12bed8b3e..0634bb2f5 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -18,6 +18,9 @@
 import logging
 import random
 import socket
+import traceback
+import numpy as np
+import pickle  # Only used when saving output on error
 
 import libensemble.util.launcher as launcher
 from libensemble.util.timer import Timer
@@ -29,7 +32,7 @@
 from libensemble.comms.logs import manager_logging_config
 from libensemble.comms.tcp_mgr import ServerQCommManager, ClientQCommManager
 from libensemble.controller import JobController
-from libensemble.utils import check_inputs, _USER_SIM_ID_WARNING, report_manager_exception
+from libensemble.utils import check_inputs, _USER_SIM_ID_WARNING
 
 logger = logging.getLogger(__name__)
 # To change logging level for just this module
@@ -136,12 +139,12 @@ def libE_manager(wcomms, sim_specs, gen_specs, exit_criteria, persis_info,
         logger.info("libE_manager total time: {}".format(elapsed_time))
 
     except ManagerException as e:
-        report_manager_exception(hist, persis_info, e)
+        _report_manager_exception(hist, persis_info, e)
         if libE_specs.get('abort_on_exception', True) and on_abort is not None:
             on_abort()
         raise
     except Exception:
-        report_manager_exception(hist, persis_info)
+        _report_manager_exception(hist, persis_info)
         if libE_specs.get('abort_on_exception', True) and on_abort is not None:
             on_abort()
         raise
@@ -421,3 +424,25 @@ def libE_tcp_worker(sim_specs, gen_specs, libE_specs):
         worker_main(comm, sim_specs, gen_specs, libE_specs,
                     workerID=workerID, log_comm=True)
         logger.debug("Worker {} exiting".format(workerID))
+
+
+# ==================== Additional Internal Functions ===========================
+
+
+def _report_manager_exception(hist, persis_info, mgr_exc=None):
+    "Write out exception manager exception to log."
+    if mgr_exc is not None:
+        from_line, msg, exc = mgr_exc.args
+        logger.error("---- {} ----".format(from_line))
+        logger.error("Message: {}".format(msg))
+        logger.error(exc)
+    else:
+        logger.error(traceback.format_exc())
+    logger.error("Manager exception raised .. aborting ensemble:")
+    logger.error("Dumping ensemble history with {} sims evaluated:".
+                 format(hist.sim_count))
+
+    filename = 'libE_history_at_abort_' + str(hist.sim_count)
+    np.save(filename + '.npy', hist.trim_H())
+    with open(filename + '.pickle', "wb") as f:
+        pickle.dump(persis_info, f)
diff --git a/libensemble/utils.py b/libensemble/utils.py
index 527852476..688d30faa 100644
--- a/libensemble/utils.py
+++ b/libensemble/utils.py
@@ -6,13 +6,12 @@
 
 __all__ = ['check_inputs']
 
-import traceback
 import os
 import sys
 import logging
 import numpy as np
 import argparse
-import pickle  # Only used when saving output on error
+import pickle
 
 logger = logging.getLogger(__name__)
 # To change logging level for just this module
@@ -64,26 +63,6 @@
                           'save_every_k_gens',   #
                           'profile_worker']      #
 
-
-def report_manager_exception(hist, persis_info, mgr_exc=None):
-    "Write out exception manager exception to log."
-    if mgr_exc is not None:
-        from_line, msg, exc = mgr_exc.args
-        logger.error("---- {} ----".format(from_line))
-        logger.error("Message: {}".format(msg))
-        logger.error(exc)
-    else:
-        logger.error(traceback.format_exc())
-    logger.error("Manager exception raised .. aborting ensemble:")
-    logger.error("Dumping ensemble history with {} sims evaluated:".
-                 format(hist.sim_count))
-
-    filename = 'libE_history_at_abort_' + str(hist.sim_count)
-    np.save(filename + '.npy', hist.trim_H())
-    with open(filename + '.pickle', "wb") as f:
-        pickle.dump(persis_info, f)
-
-
 # ==================== Common input checking =================================
 _USER_SIM_ID_WARNING = \
     ('\n' + 79*'*' + '\n' +

From d67782fd66c4291c4e18874ed371292c4893f9b9 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Mon, 18 Nov 2019 13:07:19 -0600
Subject: [PATCH 550/644] Changing stream docstring

---
 libensemble/utils.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/libensemble/utils.py b/libensemble/utils.py
index 39cb72727..a2deb082b 100644
--- a/libensemble/utils.py
+++ b/libensemble/utils.py
@@ -363,8 +363,8 @@ def save_libE_output(H, persis_info, calling_file, nworkers):
 
 
 def add_unique_random_streams(persis_info, size):
-    # Used to create a random number stream for the libE manager and workers
-    # (when size = 1 + num_workers). Stream i is initialized with seed=i.
+    # Creates size random number streams for the libE manager and workers when
+    # size is num_workers + 1. Stream i is initialized with seed i.
     for i in range(size):
         if i in persis_info:
             persis_info[i].update({

From b143637afb38b9bd71d8106b1bfce6c6b6cea157 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Mon, 18 Nov 2019 13:11:47 -0600
Subject: [PATCH 551/644] Fixing ==== line

---
 libensemble/libE_manager.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/libE_manager.py b/libensemble/libE_manager.py
index 0bbfc48d9..4915f0500 100644
--- a/libensemble/libE_manager.py
+++ b/libensemble/libE_manager.py
@@ -1,6 +1,6 @@
 """
 libEnsemble manager routines
-====================================================
+============================
 """
 
 import sys

From ab05816dc407cb4292bbb6fb82c73033843f04a5 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Mon, 18 Nov 2019 14:15:38 -0600
Subject: [PATCH 552/644] Update forces example

---
 libensemble/libE_worker.py                    |  4 +-
 .../tests/scaling_tests/forces/forces_simf.py | 20 ++----
 .../scaling_tests/forces/run_libe_forces.py   | 64 +++++++++----------
 3 files changed, 38 insertions(+), 50 deletions(-)

diff --git a/libensemble/libE_worker.py b/libensemble/libE_worker.py
index a133b6d1d..cddd0079b 100644
--- a/libensemble/libE_worker.py
+++ b/libensemble/libE_worker.py
@@ -250,13 +250,13 @@ def _handle_calc(self, Work, calc_in):
                            calc_type_strings[calc_type],
                            timer,
                            job.timer,
-                           calc_status_strings.get(calc_status, "Completed"))
+                           calc_status_strings.get(calc_status, "Not set"))
             else:
                 calc_msg = "Calc {:5d}: {} {} Status: {}".\
                     format(calc_id,
                            calc_type_strings[calc_type],
                            timer,
-                           calc_status_strings.get(calc_status, "Completed"))
+                           calc_status_strings.get(calc_status, "Not set"))
 
             logging.getLogger(LogConfig.config.stats_name).info(calc_msg)
 
diff --git a/libensemble/tests/scaling_tests/forces/forces_simf.py b/libensemble/tests/scaling_tests/forces/forces_simf.py
index 7988d031a..fcd9ff85e 100644
--- a/libensemble/tests/scaling_tests/forces/forces_simf.py
+++ b/libensemble/tests/scaling_tests/forces/forces_simf.py
@@ -37,16 +37,16 @@ def make_unique_simdir(simdir, count=0):
         return make_unique_simdir(".".join([simdir.split('.')[0], str(count)]), count)
 
 
-def run_forces(x, persis_info, sim_specs, libE_info):
+def run_forces(H, persis_info, sim_specs, libE_info):
     # Setting up variables needed for input and output
     # keys              = variable names
     # x                 = variable values
     # output            = what will be returned to libE
 
     calc_status = 0  # Returns to worker
-
+    
+    x = H['x']
     simdir_basename = sim_specs['user']['simdir_basename']
-    # cores           = sim_specs['user']['cores']
     keys = sim_specs['user']['keys']
     sim_particles = sim_specs['user']['sim_particles']
     sim_timesteps = sim_specs['user']['sim_timesteps']
@@ -58,15 +58,6 @@ def run_forces(x, persis_info, sim_specs, libE_info):
     particle_variance = sim_specs['user'].get('particle_variance', 0)
 
     # Composing variable names and x values to set up simulation
-    # arguments = []
-    # sim_dir   = [simdir_basename]
-    # for i,key in enumerate(keys):
-    #    variable = key+'='+str(x[i])
-    #    arguments.append(variable)
-    #    sim_dir.append('_'+variable)
-    # print(os.getcwd(), sim_dir)
-
-    # For one key
     seed = int(np.rint(x[0][0]))
 
     # This is to give a random variance of work-load
@@ -91,7 +82,7 @@ def run_forces(x, persis_info, sim_specs, libE_info):
         job = jobctl.launch(calc_type='sim', app_args=args, stdout='out.txt', stderr='err.txt', wait_on_run=True)  # Auto-partition
 
     # Stat file to check for bad runs
-    statfile = simdir_basename+'.stat'
+    statfile = 'forces.stat'
     filepath = os.path.join(job.workdir, statfile)
     line = None
 
@@ -112,6 +103,7 @@ def run_forces(x, persis_info, sim_specs, libE_info):
             print("Job {} completed".format(job.name))
             calc_status = WORKER_DONE
             if read_last_line(filepath) == "kill":
+                # Generally mark as complete if want results (completed after poll - before readline)
                 print("Warning: Job completed although marked as a bad run (kill flag set in forces.stat)")
         elif job.state == 'FAILED':
             print("Warning: Job {} failed: Error code {}".format(job.name, job.errcode))
@@ -130,7 +122,7 @@ def run_forces(x, persis_info, sim_specs, libE_info):
         # job.read_file_in_workdir(statfile)
         final_energy = data[-1]
     except Exception as e:
-        print('Caught:', e)
+        # print('Caught:', e)
         final_energy = np.nan
         # print('Warning - Energy Nan')
 
diff --git a/libensemble/tests/scaling_tests/forces/run_libe_forces.py b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
index 27ab74cca..663b57718 100644
--- a/libensemble/tests/scaling_tests/forces/run_libe_forces.py
+++ b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
@@ -7,30 +7,34 @@
 # Import libEnsemble modules
 from libensemble.libE import libE
 from libensemble.gen_funcs.sampling import uniform_random_sample
+from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
 
 from libensemble import libE_logger
-libE_logger.set_level('INFO')
+libE_logger.set_level('INFO')  # Info is now default - but shows usage.
 
 USE_BALSAM = False
-USE_MPI = False
-
-if USE_MPI:
-    # Run with MPI (Add a proc for manager): mpiexec -np <num_workers+1> python run_libe_forces.py
-    import mpi4py
-    mpi4py.rc.recv_mprobe = False  # Disable matching probes
-    from mpi4py import MPI
-    nworkers = MPI.COMM_WORLD.Get_size() - 1
-    is_master = (MPI.COMM_WORLD.Get_rank() == 0)
-    libE_specs = {}  # MPI is default comms, workers are decided at launch
-else:
-    # Run with multi-processing: python run_libe_forces.py <num_workers>
-    try:
-        nworkers = int(sys.argv[1])
-    except Exception:
-        print("WARNING: nworkers not passed to script - defaulting to 4")
-        nworkers = 4
-    is_master = True  # processes are forked in libE
-    libE_specs = {'nworkers': nworkers, 'comms': 'local'}
+#USE_MPI = False
+
+#if USE_MPI:
+    ## Run with MPI (Add a proc for manager): mpiexec -np <num_workers+1> python run_libe_forces.py
+    #import mpi4py
+    #mpi4py.rc.recv_mprobe = False  # Disable matching probes
+    #from mpi4py import MPI
+    #nworkers = MPI.COMM_WORLD.Get_size() - 1
+    #is_master = (MPI.COMM_WORLD.Get_rank() == 0)
+    #libE_specs = {}  # MPI is default comms, workers are decided at launch
+#else:
+    ## Run with multi-processing: python run_libe_forces.py <num_workers>
+    #try:
+        #nworkers = int(sys.argv[1])
+    #except Exception:
+        #print("WARNING: nworkers not passed to script - defaulting to 4")
+        #nworkers = 4
+    #is_master = True  # processes are forked in libE
+    #libE_specs = {'nworkers': nworkers, 'comms': 'local'}
+
+
+nworkers, is_master, libE_specs, _ = parse_args()
 
 if is_master:
     print('\nRunning with {} workers\n'.format(nworkers))
@@ -48,7 +52,7 @@
         subprocess.check_call(['./build_forces.sh'])
 
 # Normally the sim_dir will exist with common input which is copied for each worker. Here it starts empty.
-# Create if no ./sim dir. See sim_specs['sim_dir']
+# Create if no ./sim dir. See libE_specs['sim_dir']
 if not os.path.isdir('./sim'):
     os.mkdir('./sim')
 
@@ -61,16 +65,13 @@
     jobctrl = MPIJobController()  # Use auto_resources=False to oversubscribe
 jobctrl.register_calc(full_path=sim_app, calc_type='sim')
 
-
-# Todo - clarify difference sim 'in' and 'keys'
 # Note: Attributes such as kill_rate are to control forces tests, this would not be a typical parameter.
 
 # State the objective function, its arguments, output, and necessary parameters (and their sizes)
 sim_specs = {'sim_f': run_forces,         # Function whose output is being minimized
              'in': ['x'],                 # Name of input for sim_f
              'out': [('energy', float)],  # Name, type of output from sim_f
-             'user': {'sim_dir_suffix': 'test',
-                      'simdir_basename': 'force',
+             'user': {'simdir_basename': 'forces',
                       'keys': ['seed'],
                       'cores': 2,
                       'sim_particles': 1e3,
@@ -95,23 +96,18 @@
 
 libE_specs['save_every_k_gens'] = 1000  # Save every K steps
 libE_specs['sim_dir'] = './sim'         # Sim dir to be copied for each worker
-libE_specs['profile'] = False           # Don't have libE profile run
+libE_specs['profile_worker'] = False    # Whether to have libE profile on
 
 # Maximum number of simulations
 sim_max = 8
 exit_criteria = {'sim_max': sim_max}
 
-# Create a different random number stream for each worker (used by uniform_random_sample)
-np.random.seed(1)
+# Create a different random number stream for each worker and the manager
 persis_info = {}
-for i in range(1, nworkers+1):
-    persis_info[i] = {'rand_stream': np.random.RandomState(i)}
+persis_info = add_unique_random_streams(persis_info, nworkers + 1)
 
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info=persis_info, libE_specs=libE_specs)
 
 # Save results to numpy file
 if is_master:
-    short_name = script_name.split("test_", 1).pop()
-    filename = short_name + '_results_History_length=' + str(len(H)) + '_evals=' + str(sum(H['returned']))
-    print("\n\nRun completed.\nSaving results to file: " + filename)
-    np.save(filename, H)
+    save_libE_output(H, persis_info, __file__, nworkers)

From 16ea97bb62beadda164fdfd1f678348af70fde69 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Mon, 18 Nov 2019 14:39:20 -0600
Subject: [PATCH 553/644] Differentiate internal functions in utils.py

---
 libensemble/libE.py  |  4 +++-
 libensemble/utils.py | 26 +++++++++++++-------------
 2 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/libensemble/libE.py b/libensemble/libE.py
index 0634bb2f5..b87dd3fdb 100644
--- a/libensemble/libE.py
+++ b/libensemble/libE.py
@@ -241,7 +241,9 @@ def libE_mpi_worker(sim_specs, gen_specs, libE_specs):
     logger.debug("Worker {} exiting".format(libE_specs['comm'].Get_rank()))
 
 
-# ==================== Process version =================================
+# ==================== Local version ===============================
+
+
 def start_proc_team(nworkers, sim_specs, gen_specs, libE_specs, log_comm=True):
     "Launch a process worker team."
     wcomms = [QCommProcess(worker_main, sim_specs, gen_specs, libE_specs, w, log_comm)
diff --git a/libensemble/utils.py b/libensemble/utils.py
index 5e9debbc8..f24d7683c 100644
--- a/libensemble/utils.py
+++ b/libensemble/utils.py
@@ -4,7 +4,7 @@
 
 """
 
-__all__ = ['check_inputs']
+__all__ = ['check_inputs', 'parse_args', 'save_libE_output', 'add_unique_random_streams']
 
 import os
 import sys
@@ -73,7 +73,7 @@
      '\n' + 79*'*' + '\n\n')
 
 
-def check_consistent_field(name, field0, field1):
+def _check_consistent_field(name, field0, field1):
     "Check that new field (field1) is compatible with an old field (field0)."
     assert field0.ndim == field1.ndim, \
         "H0 and H have different ndim for field {}".format(name)
@@ -167,7 +167,7 @@ def check_H(H0, sim_specs, alloc_specs, gen_specs):
 
         # Check dimensional compatibility of fields
         for field in fields:
-            check_consistent_field(field, H0[field], Dummy_H[field])
+            _check_consistent_field(field, H0[field], Dummy_H[field])
 
 
 def check_inputs(libE_specs=None, alloc_specs=None, sim_specs=None, gen_specs=None, exit_criteria=None, H0=None, serial_check=False):
@@ -245,7 +245,7 @@ def check_inputs(libE_specs=None, alloc_specs=None, sim_specs=None, gen_specs=No
                     help='Additional arguments for use by specific testers')
 
 
-def mpi_parse_args(args):
+def _mpi_parse_args(args):
     "Parse arguments for MPI comms."
     from mpi4py import MPI
     nworkers = MPI.COMM_WORLD.Get_size()-1
@@ -254,14 +254,14 @@ def mpi_parse_args(args):
     return nworkers, is_master, libE_specs, args.tester_args
 
 
-def local_parse_args(args):
+def _local_parse_args(args):
     "Parse arguments for forked processes using multiprocessing."
     nworkers = args.nworkers or 4
     libE_specs = {'nworkers': nworkers, 'comms': 'local'}
     return nworkers, True, libE_specs, args.tester_args
 
 
-def tcp_parse_args(args):
+def _tcp_parse_args(args):
     "Parse arguments for local TCP connections"
     nworkers = args.nworkers or 4
     cmd = [
@@ -273,7 +273,7 @@ def tcp_parse_args(args):
     return nworkers, True, libE_specs, args.tester_args
 
 
-def ssh_parse_args(args):
+def _ssh_parse_args(args):
     "Parse arguments for SSH with reverse tunnel."
     nworkers = len(args.workers)
     worker_pwd = args.worker_pwd or os.getcwd()
@@ -296,7 +296,7 @@ def ssh_parse_args(args):
     return nworkers, True, libE_specs, args.tester_args
 
 
-def client_parse_args(args):
+def _client_parse_args(args):
     "Parse arguments for a TCP client."
     nworkers = args.nworkers or 4
     ip, port, authkey = args.server
@@ -313,11 +313,11 @@ def parse_args():
     "Unified parsing interface for regression test arguments"
     args = parser.parse_args(sys.argv[1:])
     front_ends = {
-        'mpi': mpi_parse_args,
-        'local': local_parse_args,
-        'tcp': tcp_parse_args,
-        'ssh': ssh_parse_args,
-        'client': client_parse_args}
+        'mpi': _mpi_parse_args,
+        'local': _local_parse_args,
+        'tcp': _tcp_parse_args,
+        'ssh': _ssh_parse_args,
+        'client': _client_parse_args}
     if args.pwd is not None:
         os.chdir(args.pwd)
     return front_ends[args.comms or 'mpi'](args)

From cccf946f0b186e8c7e7c16329157bb0c3d34298e Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Mon, 18 Nov 2019 14:47:21 -0600
Subject: [PATCH 554/644] Cleanup forces changes

---
 .../tests/scaling_tests/forces/forces_simf.py |  5 ++---
 .../scaling_tests/forces/run_libe_forces.py   | 21 -------------------
 2 files changed, 2 insertions(+), 24 deletions(-)

diff --git a/libensemble/tests/scaling_tests/forces/forces_simf.py b/libensemble/tests/scaling_tests/forces/forces_simf.py
index fcd9ff85e..e33a81896 100644
--- a/libensemble/tests/scaling_tests/forces/forces_simf.py
+++ b/libensemble/tests/scaling_tests/forces/forces_simf.py
@@ -44,7 +44,7 @@ def run_forces(H, persis_info, sim_specs, libE_info):
     # output            = what will be returned to libE
 
     calc_status = 0  # Returns to worker
-    
+
     x = H['x']
     simdir_basename = sim_specs['user']['simdir_basename']
     keys = sim_specs['user']['keys']
@@ -121,8 +121,7 @@ def run_forces(H, persis_info, sim_specs, libE_info):
         data = np.loadtxt(filepath)
         # job.read_file_in_workdir(statfile)
         final_energy = data[-1]
-    except Exception as e:
-        # print('Caught:', e)
+    except Exception:
         final_energy = np.nan
         # print('Warning - Energy Nan')
 
diff --git a/libensemble/tests/scaling_tests/forces/run_libe_forces.py b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
index 663b57718..578ff0051 100644
--- a/libensemble/tests/scaling_tests/forces/run_libe_forces.py
+++ b/libensemble/tests/scaling_tests/forces/run_libe_forces.py
@@ -1,5 +1,4 @@
 #!/usr/bin/env python
-import sys
 import os
 import numpy as np
 from forces_simf import run_forces  # Sim func from current dir
@@ -13,26 +12,6 @@
 libE_logger.set_level('INFO')  # Info is now default - but shows usage.
 
 USE_BALSAM = False
-#USE_MPI = False
-
-#if USE_MPI:
-    ## Run with MPI (Add a proc for manager): mpiexec -np <num_workers+1> python run_libe_forces.py
-    #import mpi4py
-    #mpi4py.rc.recv_mprobe = False  # Disable matching probes
-    #from mpi4py import MPI
-    #nworkers = MPI.COMM_WORLD.Get_size() - 1
-    #is_master = (MPI.COMM_WORLD.Get_rank() == 0)
-    #libE_specs = {}  # MPI is default comms, workers are decided at launch
-#else:
-    ## Run with multi-processing: python run_libe_forces.py <num_workers>
-    #try:
-        #nworkers = int(sys.argv[1])
-    #except Exception:
-        #print("WARNING: nworkers not passed to script - defaulting to 4")
-        #nworkers = 4
-    #is_master = True  # processes are forked in libE
-    #libE_specs = {'nworkers': nworkers, 'comms': 'local'}
-
 
 nworkers, is_master, libE_specs, _ = parse_args()
 

From 99b81425d865d6ef2dfd443b3791b5c907841350 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Mon, 18 Nov 2019 16:13:08 -0600
Subject: [PATCH 555/644] Add utilities API

---
 docs/utilities.rst   |  9 ++++++-
 libensemble/utils.py | 62 +++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 64 insertions(+), 7 deletions(-)

diff --git a/docs/utilities.rst b/docs/utilities.rst
index 53f2ae749..3a04cb524 100644
--- a/docs/utilities.rst
+++ b/docs/utilities.rst
@@ -1,7 +1,7 @@
 Utilities
 =========
 
-libEnsemble features several modules and tools to assist in writing consistent
+libEnsemble features a utilities module to assist in writing consistent
 calling scripts and user functions.
 
 Input consistency
@@ -40,3 +40,10 @@ Usage:
                     [--pwd [PWD]] [--worker_pwd [WORKER_PWD]]
                     [--worker_python [WORKER_PYTHON]]
                     [--tester_args [TESTER_ARGS [TESTER_ARGS ...]]]
+
+Utilities API
+-------------
+
+.. automodule:: utils
+   :members:
+   :no-undoc-members:
diff --git a/libensemble/utils.py b/libensemble/utils.py
index f24d7683c..59624aca7 100644
--- a/libensemble/utils.py
+++ b/libensemble/utils.py
@@ -1,6 +1,6 @@
 """
 libEnsemble utilities
-============================================
+=====================
 
 """
 
@@ -310,7 +310,11 @@ def _client_parse_args(args):
 
 
 def parse_args():
-    "Unified parsing interface for regression test arguments"
+    """Parses command line arguments.
+
+    :doc:`(See usage)<utilities>`
+
+    """
     args = parser.parse_args(sys.argv[1:])
     front_ends = {
         'mpi': _mpi_parse_args,
@@ -326,6 +330,35 @@ def parse_args():
 
 
 def save_libE_output(H, persis_info, calling_file, nworkers):
+    """
+    Writes out history array and persis_info to files.
+
+    Format: <user_script>_results_History_length=<history_length>_evals=<Completed evals>_ranks=<nworkers>
+
+    Parameters
+    ----------
+
+    H: `NumPy structured array <https://docs.scipy.org/doc/numpy/user/basics.rec.html>`_
+
+        History array storing rows for each point.
+        :doc:`(example)<data_structures/history_array>`
+
+    persis_info: :obj:`dict`
+
+        Persistent information dictionary
+        :doc:`(example)<data_structures/persis_info>`
+
+    calling_file  : :obj:`string`
+
+        Name of user calling script (or user chosen name) to prefix output files.
+        The convention is to send __file__ from user calling script.
+
+    nworkers: :obj:`int`
+
+        The number of workers in this ensemble. Added to output file names.
+
+    """
+
     script_name = os.path.splitext(os.path.basename(calling_file))[0]
     short_name = script_name.split("test_", 1).pop()
     filename = short_name + '_results_History_length=' + str(len(H)) \
@@ -341,10 +374,27 @@ def save_libE_output(H, persis_info, calling_file, nworkers):
 # ===================== per-worker numpy random-streams ========================
 
 
-def add_unique_random_streams(persis_info, size):
-    # Creates size random number streams for the libE manager and workers when
-    # size is num_workers + 1. Stream i is initialized with seed i.
-    for i in range(size):
+def add_unique_random_streams(persis_info, nstreams):
+    """Creates nstreams random number streams for the libE manager and workers
+    when nstreams is num_workers + 1. Stream i is initialized with seed i.
+
+    The entries are appended to the existing persis_info dictionary.
+
+    Parameters
+    ----------
+
+    persis_info: :obj:`dict`
+
+        Persistent information dictionary
+        :doc:`(example)<data_structures/persis_info>`
+
+    nstreams: :obj:`int`
+
+        Number of independent random number streams to produce
+
+    """
+
+    for i in range(nstreams):
         if i in persis_info:
             persis_info[i].update({
                 'rand_stream': np.random.RandomState(i),

From afd0bbe3839bc568bbeeaf18e05890d1c8104054 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Mon, 18 Nov 2019 16:38:55 -0600
Subject: [PATCH 556/644] Add output analysis

---
 docs/history_output.rst | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/docs/history_output.rst b/docs/history_output.rst
index d6146fda4..b863cc797 100644
--- a/docs/history_output.rst
+++ b/docs/history_output.rst
@@ -53,3 +53,13 @@ Other libEnsemble files produced by default are:
   set to DEBUG.  If this file is not removed, multiple runs will append output.
   Messages at or above level MANAGER_WARNING are also copied to stderr to alert
   the user promptly.  For more info, see :doc:`Logging<logging>`.
+
+Output Analysis
+^^^^^^^^^^^^^^^
+The ``postproc_scripts`` directory, in the libEnsemble project root directory,
+contains scripts to compare outputs and create plots based on the ensemble output.
+
+.. include:: ../postproc_scripts/readme.rst
+
+.. include:: ../postproc_scripts/balsam/readme.rst
+

From 5173d57ecef62224580f7bf6b24badcc619ab90f Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Mon, 18 Nov 2019 16:42:45 -0600
Subject: [PATCH 557/644] Slight mod to FAQ wording

---
 docs/FAQ.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/FAQ.rst b/docs/FAQ.rst
index 135b41e45..cf27eac86 100644
--- a/docs/FAQ.rst
+++ b/docs/FAQ.rst
@@ -126,9 +126,9 @@ to ``pdb``. How well this works varies by system::
 
 **Can I use the MPI Job Controller when running libEnsemble with multiprocessing?**
 
-Actually, yes! The job controller type only determines how launched jobs communicate
-with libEnsemble, and is independent of ``comms`` chosen for manager-worker
-communications.
+Actually, yes! The job controller type only determines how libEnsemble workers
+launch and interact with user applications, and is independent of ``comms`` chosen
+for manager-worker communications.
 
 macOS-specific Errors
 ---------------------

From 24c10296c96349003cc49c7b89cf1efe12044db1 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Mon, 18 Nov 2019 16:49:45 -0600
Subject: [PATCH 558/644] Update parse_args location in Summit guide

---
 docs/platforms/summit.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/platforms/summit.rst b/docs/platforms/summit.rst
index 6108b1c73..212aeb600 100644
--- a/docs/platforms/summit.rst
+++ b/docs/platforms/summit.rst
@@ -81,7 +81,7 @@ Batch Runs
 Batch scripts specify run-settings using ``#BSUB`` statements. The following
 simple example depicts configuring and launching libEnsemble to a launch node with
 multiprocessing. This script also assumes the user is using the ``parse_args()``
-convenience function within libEnsemble's ``/regression_tests/common.py``.
+convenience function within libEnsemble's ``utils.py``.
 
 .. code-block:: bash
 

From 4e9a1cf15a12a8c03832e195895d264d003fd4d9 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Mon, 18 Nov 2019 17:03:11 -0600
Subject: [PATCH 559/644] Update forces submission scripts to use parse_args
 cmd line

---
 .../tests/scaling_tests/forces/summit_submit_mproc.sh     | 8 +++++---
 .../tests/scaling_tests/forces/theta_submit_balsam.sh     | 3 ++-
 .../tests/scaling_tests/forces/theta_submit_mproc.sh      | 7 +++++--
 3 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/libensemble/tests/scaling_tests/forces/summit_submit_mproc.sh b/libensemble/tests/scaling_tests/forces/summit_submit_mproc.sh
index 2279b50dd..42e9da68c 100644
--- a/libensemble/tests/scaling_tests/forces/summit_submit_mproc.sh
+++ b/libensemble/tests/scaling_tests/forces/summit_submit_mproc.sh
@@ -15,8 +15,11 @@
 # Name of calling script-
 export EXE=run_libe_forces.py
 
+# Communication Method
+export COMMS="--comms local"
+
 # Number of workers.
-#export NUM_WORKERS=4 # Optional if pass to script
+export NWORKERS="--nworkers 4"
 
 # Wallclock for libE. Slightly smaller than job wallclock
 #export LIBE_WALLCLOCK=15 # Optional if pass to script
@@ -40,8 +43,7 @@ hash -r # Check no commands hashed (pip/python...)
 
 # Launch libE.
 #python $EXE $NUM_WORKERS $LIBE_WALLCLOCK > out.txt 2>&1
-#python $EXE $NUM_WORKERS > out.txt 2>&1
-python $EXE > out.txt 2>&1
+python $EXE $COMMS $NWORKERS > out.txt 2>&1
 
 if [[ $LIBE_PLOTS = "true" ]]; then
   python $PLOT_DIR/plot_libe_calcs_util_v_time.py
diff --git a/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh b/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh
index d51a5692f..3f071a9dc 100755
--- a/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh
+++ b/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh
@@ -25,7 +25,8 @@ export LIBE_WALLCLOCK=25
 export WORKFLOW_NAME=libe_workflow #sh - todo - may currently be hardcoded to this in libE - allow user to specify
 
 #Tell libE manager to stop workers, dump timing.dat and exit after this time. Script must be set up to receive as argument.
-export SCRIPT_ARGS=$(($LIBE_WALLCLOCK-5))
+export SCRIPT_ARGS="--comms mpi --nworkers $NUM_WORKERS"
+# export SCRIPT_ARGS=$(($LIBE_WALLCLOCK-5))
 # export SCRIPT_ARGS='' #Default No args
 
 # Name of Conda environment (Need to have set up: https://balsam.alcf.anl.gov/quick/quickstart.html)
diff --git a/libensemble/tests/scaling_tests/forces/theta_submit_mproc.sh b/libensemble/tests/scaling_tests/forces/theta_submit_mproc.sh
index 6454e4f7b..d46dc6a5d 100755
--- a/libensemble/tests/scaling_tests/forces/theta_submit_mproc.sh
+++ b/libensemble/tests/scaling_tests/forces/theta_submit_mproc.sh
@@ -14,8 +14,11 @@
 # Name of calling script
 export EXE=run_libe_forces.py
 
+# Communication Method
+export COMMS="--comms local"
+
 # Number of workers.
-#export NUM_WORKERS=4 # Optional if pass to script
+export NWORKERS="--nworkers 4"
 
 # Wallclock for libE (allow clean shutdown)
 #export LIBE_WALLCLOCK=25 # Optional if pass to script
@@ -43,7 +46,7 @@ export PYTHONNOUSERSITE=1
 # Launch libE
 #python $EXE $NUM_WORKERS $LIBE_WALLCLOCK > out.txt 2>&1
 #python $EXE $NUM_WORKERS > out.txt 2>&1
-python $EXE > out.txt 2>&1
+python $EXE $COMMS $NWORKERS > out.txt 2>&1
 
 if [[ $LIBE_PLOTS = "true" ]]; then
   python $PLOT_DIR/plot_libe_calcs_util_v_time.py

From 784b0e6df91c22bcafc374f60204b187bfe844c0 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 19 Nov 2019 07:41:28 -0600
Subject: [PATCH 560/644] Whitespace removal

---
 docs/history_output.rst   |  1 -
 docs/platforms/summit.rst | 10 ++++------
 2 files changed, 4 insertions(+), 7 deletions(-)

diff --git a/docs/history_output.rst b/docs/history_output.rst
index b863cc797..64cff7b55 100644
--- a/docs/history_output.rst
+++ b/docs/history_output.rst
@@ -62,4 +62,3 @@ contains scripts to compare outputs and create plots based on the ensemble outpu
 .. include:: ../postproc_scripts/readme.rst
 
 .. include:: ../postproc_scripts/balsam/readme.rst
-
diff --git a/docs/platforms/summit.rst b/docs/platforms/summit.rst
index 212aeb600..e2307bd3a 100644
--- a/docs/platforms/summit.rst
+++ b/docs/platforms/summit.rst
@@ -2,7 +2,7 @@
 Summit
 ======
 
-Summit_ is an IBM AC922 system located at the Oak Ridge Leadership Computing Facility. 
+Summit_ is an IBM AC922 system located at the Oak Ridge Leadership Computing Facility.
 Each of the approximately 4,600 compute nodes on Summit contains two IBM POWER9 processors and six NVIDIA Volta V100 accelerators.
 
 Summit features three tiers of nodes: login, launch, and compute nodes.
@@ -19,12 +19,12 @@ Begin by loading the Python 3 Anaconda module::
 You can now create your own custom Conda_ environment::
 
     conda create --name myenv python=3.7
-    
+
 Now activate environment::
 
     export PYTHONNOUSERSITE=1 # Make sure get python from conda env
     . activate myenv
-  
+
 If you are installing any packages with extensions, ensure the correct compiler module
 is loaded. If using mpi4py_, this must be installed from source, referencing the compiler.
 At time of writing, mpi4py must be built with gcc::
@@ -35,7 +35,6 @@ With your environment activated::
 
     CC=mpicc MPICC=mpicc pip install mpi4py --no-binary mpi4py
 
-
 Installing libEnsemble
 ----------------------
 
@@ -48,7 +47,6 @@ Your prompt should be similar to the following line:
 
 .. note::
     If you encounter pip errors, run ``python -m pip install --upgrade pip`` first
-            
 
 Job Submission
 --------------
@@ -114,7 +112,7 @@ convenience function within libEnsemble's ``utils.py``.
     export COMMS='--comms local'
 
     # Number of workers.
-    export NWORKERS='--nworkers 128'    
+    export NWORKERS='--nworkers 128'
 
     hash -r # Check no commands hashed (pip/python...)
 

From b21dfd9d43c712d05e8089e7feee3f7903d065e9 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 19 Nov 2019 10:02:36 -0600
Subject: [PATCH 561/644] Move API to top of utilities docs, examples beneath
 with redundant info removed

---
 docs/utilities.rst | 50 ++++++++++++++++++++++++++++------------------
 1 file changed, 31 insertions(+), 19 deletions(-)

diff --git a/docs/utilities.rst b/docs/utilities.rst
index 3a04cb524..ab06faf0b 100644
--- a/docs/utilities.rst
+++ b/docs/utilities.rst
@@ -4,29 +4,34 @@ Utilities
 libEnsemble features a utilities module to assist in writing consistent
 calling scripts and user functions.
 
-Input consistency
------------------
 
-Users can check the formatting and consistency of ``exit_criteria`` and each
-``specs`` dictionary with the ``check_inputs()`` function from the ``utils``
-module. Provide any combination of these data structures as keyword arguments.
-For example::
+Utilities API
+-------------
 
-  from libensemble.utils import check_inputs
-  check_inputs(sim_specs=my-sim_specs, gen_specs=my-gen_specs, exit_criteria=ec)
+.. automodule:: utils
+   :members:
+   :no-undoc-members:
 
-Parameters as command-line arguments
-------------------------------------
+Examples
+--------
 
-The ``parse_args()`` function can be used to pass common libEnsemble parameters as
-command-line arguments.
+Check inputs
+~~~~~~~~~~~~
 
-In your calling script::
+.. code-block:: python
+
+    from libensemble.utils import check_inputs
+    check_inputs(sim_specs=my_sim_specs, gen_specs=my_gen_specs, exit_criteria=ec)
+
+Parse Args
+~~~~~~~~~~
+
+.. code-block:: python
 
     from libensemble.utils import parse_args
     nworkers, is_master, libE_specs, misc_args = parse_args()
 
-From the shell, for example::
+From the shell::
 
     $ python calling_script --comms local --nworkers 4
 
@@ -41,9 +46,16 @@ Usage:
                     [--worker_python [WORKER_PYTHON]]
                     [--tester_args [TESTER_ARGS [TESTER_ARGS ...]]]
 
-Utilities API
--------------
+Save libE Output
+~~~~~~~~~~~~~~~~
 
-.. automodule:: utils
-   :members:
-   :no-undoc-members:
+.. code-block:: python
+
+    save_libE_output(H, persis_info, __file__, nworkers)
+
+Add Unique Random Streams
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    persis_info = add_unique_random_streams(old_persis_info, nworkers + 1)

From 0eeaef3a9fcb5e1f4c61e922fefa5b5b64182cab Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 19 Nov 2019 10:21:48 -0600
Subject: [PATCH 562/644] add returns info to parse_args

---
 libensemble/utils.py | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/libensemble/utils.py b/libensemble/utils.py
index 59624aca7..3e5beeef1 100644
--- a/libensemble/utils.py
+++ b/libensemble/utils.py
@@ -312,7 +312,18 @@ def _client_parse_args(args):
 def parse_args():
     """Parses command line arguments.
 
-    :doc:`(See usage)<utilities>`
+    Returns
+    -------
+
+    nworkers: :obj:`int`
+        Number of workers libEnsemble will inititate
+
+    is_master: :obj:`boolean`
+        Indicate if the current process is the manager process
+
+    libE_specs: :obj:`dict`
+        Settings and specifications for libEnsemble
+        :doc:`(example)<data_structures/libE_specs>`
 
     """
     args = parser.parse_args(sys.argv[1:])

From 22a17119523a3048992a40ba57543bf411aa35ac Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 19 Nov 2019 11:25:10 -0600
Subject: [PATCH 563/644] move utilities to programming

---
 docs/index.rst            | 1 -
 docs/programming_libE.rst | 3 +++
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/index.rst b/docs/index.rst
index fd47b94a3..ca3837201 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -12,7 +12,6 @@
    Quickstart<introduction>
    overview_usecases
    programming_libE
-   utilities
    platforms/platforms_index
 
 .. toctree::
diff --git a/docs/programming_libE.rst b/docs/programming_libE.rst
index 4c99ee5ba..3fd34e612 100644
--- a/docs/programming_libE.rst
+++ b/docs/programming_libE.rst
@@ -14,3 +14,6 @@ Programming with libEnsemble
 .. toctree::
    job_controller/jc_index
    logging
+
+.. toctree::
+    utilities

From 0b8af7da45d7bcb2d57db3ac5a7e3e6982545bb7 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 19 Nov 2019 11:38:21 -0600
Subject: [PATCH 564/644] moves examples under each autodoc section

---
 docs/utilities.rst   | 52 --------------------------------------------
 libensemble/utils.py | 45 +++++++++++++++++++++++++++++++-------
 2 files changed, 37 insertions(+), 60 deletions(-)

diff --git a/docs/utilities.rst b/docs/utilities.rst
index ab06faf0b..00f5fe519 100644
--- a/docs/utilities.rst
+++ b/docs/utilities.rst
@@ -4,58 +4,6 @@ Utilities
 libEnsemble features a utilities module to assist in writing consistent
 calling scripts and user functions.
 
-
-Utilities API
--------------
-
 .. automodule:: utils
    :members:
    :no-undoc-members:
-
-Examples
---------
-
-Check inputs
-~~~~~~~~~~~~
-
-.. code-block:: python
-
-    from libensemble.utils import check_inputs
-    check_inputs(sim_specs=my_sim_specs, gen_specs=my_gen_specs, exit_criteria=ec)
-
-Parse Args
-~~~~~~~~~~
-
-.. code-block:: python
-
-    from libensemble.utils import parse_args
-    nworkers, is_master, libE_specs, misc_args = parse_args()
-
-From the shell::
-
-    $ python calling_script --comms local --nworkers 4
-
-Usage:
-
-.. code-block:: bash
-
-    usage: test_... [-h] [--comms [{local,tcp,ssh,client,mpi}]]
-                    [--nworkers [NWORKERS]] [--workers WORKERS [WORKERS ...]]
-                    [--workerID [WORKERID]] [--server SERVER SERVER SERVER]
-                    [--pwd [PWD]] [--worker_pwd [WORKER_PWD]]
-                    [--worker_python [WORKER_PYTHON]]
-                    [--tester_args [TESTER_ARGS [TESTER_ARGS ...]]]
-
-Save libE Output
-~~~~~~~~~~~~~~~~
-
-.. code-block:: python
-
-    save_libE_output(H, persis_info, __file__, nworkers)
-
-Add Unique Random Streams
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code-block:: python
-
-    persis_info = add_unique_random_streams(old_persis_info, nworkers + 1)
diff --git a/libensemble/utils.py b/libensemble/utils.py
index 3e5beeef1..836cddec4 100644
--- a/libensemble/utils.py
+++ b/libensemble/utils.py
@@ -1,9 +1,3 @@
-"""
-libEnsemble utilities
-=====================
-
-"""
-
 __all__ = ['check_inputs', 'parse_args', 'save_libE_output', 'add_unique_random_streams']
 
 import os
@@ -176,6 +170,11 @@ def check_inputs(libE_specs=None, alloc_specs=None, sim_specs=None, gen_specs=No
     sufficient information to perform a run. There is no return value. An
     exception is raised if any of the checks fail.
 
+    .. code-block:: python
+
+        from libensemble.utils import check_inputs
+        check_inputs(sim_specs=my_sim_specs, gen_specs=my_gen_specs, exit_criteria=ec)
+
     Parameters
     ----------
 
@@ -310,7 +309,28 @@ def _client_parse_args(args):
 
 
 def parse_args():
-    """Parses command line arguments.
+    """
+    Parses command line arguments.
+
+    .. code-block:: python
+
+        from libensemble.utils import parse_args
+        nworkers, is_master, libE_specs, misc_args = parse_args()
+
+    From the shell::
+
+        $ python calling_script --comms local --nworkers 4
+
+    Usage:
+
+    .. code-block:: bash
+
+        usage: test_... [-h] [--comms [{local,tcp,ssh,client,mpi}]]
+                        [--nworkers [NWORKERS]] [--workers WORKERS [WORKERS ...]]
+                        [--workerID [WORKERID]] [--server SERVER SERVER SERVER]
+                        [--pwd [PWD]] [--worker_pwd [WORKER_PWD]]
+                        [--worker_python [WORKER_PYTHON]]
+                        [--tester_args [TESTER_ARGS [TESTER_ARGS ...]]]
 
     Returns
     -------
@@ -346,6 +366,10 @@ def save_libE_output(H, persis_info, calling_file, nworkers):
 
     Format: <user_script>_results_History_length=<history_length>_evals=<Completed evals>_ranks=<nworkers>
 
+    .. code-block:: python
+
+        save_libE_output(H, persis_info, __file__, nworkers)
+
     Parameters
     ----------
 
@@ -386,11 +410,16 @@ def save_libE_output(H, persis_info, calling_file, nworkers):
 
 
 def add_unique_random_streams(persis_info, nstreams):
-    """Creates nstreams random number streams for the libE manager and workers
+    """
+    Creates nstreams random number streams for the libE manager and workers
     when nstreams is num_workers + 1. Stream i is initialized with seed i.
 
     The entries are appended to the existing persis_info dictionary.
 
+    .. code-block:: python
+
+        persis_info = add_unique_random_streams(old_persis_info, nworkers + 1)
+
     Parameters
     ----------
 

From e07e3f0af28cbac78477464994f86aa6e6073eb6 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 19 Nov 2019 11:43:27 -0600
Subject: [PATCH 565/644] Adding image

---
 docs/images/libE_logo_only.png | Bin 0 -> 41030 bytes
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 docs/images/libE_logo_only.png

diff --git a/docs/images/libE_logo_only.png b/docs/images/libE_logo_only.png
new file mode 100644
index 0000000000000000000000000000000000000000..174935a1de36dbeac86d807eb6f64c25c5bcd473
GIT binary patch
literal 41030
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
P0r(i|o9PjCToV5S)L@04

literal 0
HcmV?d00001


From c91e42f51e0cc012bcfc018f2655df5d595d4891 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 19 Nov 2019 11:59:39 -0600
Subject: [PATCH 566/644] Using seealso declaration

---
 libensemble/alloc_funcs/fast_alloc.py                  |  2 +-
 libensemble/alloc_funcs/fast_alloc_and_pausing.py      |  2 +-
 libensemble/alloc_funcs/fast_alloc_to_aposmm.py        |  2 +-
 libensemble/alloc_funcs/give_pregenerated_work.py      |  2 +-
 libensemble/alloc_funcs/give_sim_work_first.py         |  2 +-
 libensemble/alloc_funcs/persistent_aposmm_alloc.py     |  2 +-
 libensemble/alloc_funcs/start_only_persistent.py       |  2 +-
 .../alloc_funcs/start_persistent_local_opt_gens.py     |  2 +-
 libensemble/gen_funcs/aposmm.py                        | 10 +++++-----
 libensemble/gen_funcs/persistent_aposmm.py             | 10 +++++-----
 libensemble/gen_funcs/persistent_uniform_sampling.py   |  2 +-
 libensemble/gen_funcs/sampling.py                      |  6 +++---
 libensemble/gen_funcs/uniform_or_localopt.py           |  2 +-
 libensemble/sim_funcs/chwirut1.py                      |  4 ++--
 libensemble/sim_funcs/one_d_func.py                    |  2 +-
 libensemble/sim_funcs/six_hump_camel.py                |  6 +++---
 16 files changed, 29 insertions(+), 29 deletions(-)

diff --git a/libensemble/alloc_funcs/fast_alloc.py b/libensemble/alloc_funcs/fast_alloc.py
index dd7322a57..6b8e0a720 100644
--- a/libensemble/alloc_funcs/fast_alloc.py
+++ b/libensemble/alloc_funcs/fast_alloc.py
@@ -9,7 +9,7 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     is told to call the generator function, provided this wouldn't result in
     more than ``gen_specs['user']['num_active_gen']`` active generators.
 
-    :See:
+    .. seealso::
         ``/libensemble/tests/regression_tests/test_fast_alloc.py``
     """
 
diff --git a/libensemble/alloc_funcs/fast_alloc_and_pausing.py b/libensemble/alloc_funcs/fast_alloc_and_pausing.py
index 6bcc9ffec..7f0700195 100644
--- a/libensemble/alloc_funcs/fast_alloc_and_pausing.py
+++ b/libensemble/alloc_funcs/fast_alloc_and_pausing.py
@@ -21,7 +21,7 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     alloc_specs['user']['stop_partial_fvec_eval']: True --- after the value returned from
         combine_component_func is larger than a known upper bound on the objective.
 
-    :See:
+    .. seealso::
         ``/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py``
     """
 
diff --git a/libensemble/alloc_funcs/fast_alloc_to_aposmm.py b/libensemble/alloc_funcs/fast_alloc_to_aposmm.py
index 3a260a6c0..3051b0db8 100644
--- a/libensemble/alloc_funcs/fast_alloc_to_aposmm.py
+++ b/libensemble/alloc_funcs/fast_alloc_to_aposmm.py
@@ -12,7 +12,7 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     more than ``gen_specs['user']['num_active_gen']`` active generators. Also allows
     for a 'batch_mode'.
 
-    :See:
+    .. seealso::
         ``/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py``
     """
 
diff --git a/libensemble/alloc_funcs/give_pregenerated_work.py b/libensemble/alloc_funcs/give_pregenerated_work.py
index c64a6609d..7d29473f3 100644
--- a/libensemble/alloc_funcs/give_pregenerated_work.py
+++ b/libensemble/alloc_funcs/give_pregenerated_work.py
@@ -6,7 +6,7 @@ def give_pregenerated_sim_work(W, H, sim_specs, gen_specs, alloc_specs, persis_i
     This allocation function gives (in order) entries in alloc_spec['x'] to
     idle workers. It is an example use case where no gen_func is used.
 
-    :See:
+    .. seealso::
         ``/libensemble/tests/regression_tests/test_fast_alloc.py``
     """
 
diff --git a/libensemble/alloc_funcs/give_sim_work_first.py b/libensemble/alloc_funcs/give_sim_work_first.py
index 8525706c1..2195bc67d 100644
--- a/libensemble/alloc_funcs/give_sim_work_first.py
+++ b/libensemble/alloc_funcs/give_sim_work_first.py
@@ -20,7 +20,7 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
 
     This is the default allocation function if one is not defined.
 
-    :See:
+    .. seealso::
         ``/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py``
     """
 
diff --git a/libensemble/alloc_funcs/persistent_aposmm_alloc.py b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
index df0586274..318c4ee5c 100644
--- a/libensemble/alloc_funcs/persistent_aposmm_alloc.py
+++ b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
@@ -13,7 +13,7 @@ def persistent_aposmm_alloc(W, H, sim_specs, gen_specs, alloc_specs, persis_info
     This function assumes that one persistent APOSMM will be started and never
     stopped (until some exit_criterion is satisfied).
 
-    :See:
+    .. seealso::
         ``/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py``
     """
 
diff --git a/libensemble/alloc_funcs/start_only_persistent.py b/libensemble/alloc_funcs/start_only_persistent.py
index 4b3543b60..a62d0e5a1 100644
--- a/libensemble/alloc_funcs/start_only_persistent.py
+++ b/libensemble/alloc_funcs/start_only_persistent.py
@@ -10,7 +10,7 @@ def only_persistent_gens(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     the persistent generator have been returned from the simulation evaluation,
     then this information is given back to the persistent generator.
 
-    :See:
+    .. seealso::
         ``/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py``
     """
 
diff --git a/libensemble/alloc_funcs/start_persistent_local_opt_gens.py b/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
index a56b49906..dcaf31ef1 100644
--- a/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
+++ b/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
@@ -20,7 +20,7 @@ def start_persistent_local_opt_gens(W, H, sim_specs, gen_specs, alloc_specs, per
       evaluated (oldest first).
     - If no points are left, call the generation function.
 
-    :See:
+    .. seealso::
         ``/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py``
     """
 
diff --git a/libensemble/gen_funcs/aposmm.py b/libensemble/gen_funcs/aposmm.py
index 009411429..cb9dcffcb 100644
--- a/libensemble/gen_funcs/aposmm.py
+++ b/libensemble/gen_funcs/aposmm.py
@@ -133,10 +133,10 @@ def aposmm_logic(H, persis_info, gen_specs, _):
         active runs, order of points in each run, etc. The allocation function
         must ensure it's always given.
 
-    :See:
+    .. seealso::
         ``libensemble/tests/regression_tests/test_branin_aposmm.py``
         for basic APOSMM usage.
-    :See:
+    .. seealso::
         ``libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py``
         for an example of APOSMM coordinating multiple local optimization runs
         for an objective with more than one component.
@@ -371,7 +371,7 @@ def update_history_dist(H, n, gen_specs, c_flag):
     """
     Updates distances/indices after new points that have been evaluated.
 
-    :See:
+    .. seealso::
         ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
     """
 
@@ -766,7 +766,7 @@ def decide_where_to_start_localopt(H, r_k, mu=0, nu=0, gamma_quantile=1):
         Indices where a local opt run should be started
 
 
-    :See:
+    .. seealso::
         ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
     """
 
@@ -890,7 +890,7 @@ def initialize_APOSMM(H, gen_specs):
     """
     Computes common values every time that APOSMM is reinvoked
 
-    :See:
+    .. seealso::
         ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
     """
 
diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 7b085afd9..292a3836c 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -141,10 +141,10 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         active runs, order of points in each run, etc. The allocation function
         must ensure it's always given.
 
-    :See:
+    .. seealso::
         ``libensemble/tests/regression_tests/test_branin_aposmm.py``
         for basic APOSMM usage.
-    :See:
+    .. seealso::
         ``libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py``
         for an example of APOSMM coordinating multiple local optimization runs
         for an objective with more than one component.
@@ -671,7 +671,7 @@ def update_history_dist(H, n):
     """
     Updates distances/indices after new points that have been evaluated.
 
-    :See:
+    .. seealso::
         ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
     """
 
@@ -803,7 +803,7 @@ def decide_where_to_start_localopt(H, n, n_s, rk_const, ld=0, mu=0, nu=0):
         Indices where a local opt run should be started
 
 
-    :See:
+    .. seealso::
         ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
     """
 
@@ -895,7 +895,7 @@ def initialize_APOSMM(H, user_specs, libE_info):
     """
     Computes common values every time that APOSMM is reinvoked
 
-    :See:
+    .. seealso::
         ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
     """
     n = len(user_specs['ub'])
diff --git a/libensemble/gen_funcs/persistent_uniform_sampling.py b/libensemble/gen_funcs/persistent_uniform_sampling.py
index ed51ec599..48fbdb524 100644
--- a/libensemble/gen_funcs/persistent_uniform_sampling.py
+++ b/libensemble/gen_funcs/persistent_uniform_sampling.py
@@ -9,7 +9,7 @@ def persistent_uniform(H, persis_info, gen_specs, libE_info):
     This generation function always enters into persistent mode and returns
     ``gen_specs['gen_batch_size']`` uniformly sampled points.
 
-    :See:
+    .. seealso::
         ``libensemble/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py``
     """
     ub = gen_specs['user']['ub']
diff --git a/libensemble/gen_funcs/sampling.py b/libensemble/gen_funcs/sampling.py
index bc045edbe..eae6c09e2 100644
--- a/libensemble/gen_funcs/sampling.py
+++ b/libensemble/gen_funcs/sampling.py
@@ -12,7 +12,7 @@ def uniform_random_sample_with_different_nodes_and_ranks(H, persis_info, gen_spe
     ``gen_specs['user']['lb']``. Also randomly requests a different ``number_of_nodes``
     and ``ranks_per_node`` to be used in the evaluation of the generated point.
 
-    :See:
+    .. seealso:: 
         ``libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py``
     """
     ub = gen_specs['user']['ub']
@@ -46,7 +46,7 @@ def uniform_random_sample_obj_components(H, persis_info, gen_specs, _):
     and ``gen_specs['user']['lb']`` but requests each ``obj_component`` be evaluated
     separately.
 
-    :See:
+    .. seealso:: 
         ``libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py``
     """
     ub = gen_specs['user']['ub']
@@ -74,7 +74,7 @@ def uniform_random_sample(H, persis_info, gen_specs, _):
     Generates ``gen_specs['user']['gen_batch_size']`` points uniformly over the domain
     defined by ``gen_specs['user']['ub']`` and ``gen_specs['user']['lb']``.
 
-    :See:
+    .. seealso:: 
         ``libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py``
     """
     ub = gen_specs['user']['ub']
diff --git a/libensemble/gen_funcs/uniform_or_localopt.py b/libensemble/gen_funcs/uniform_or_localopt.py
index 53342f15c..05da55ca2 100644
--- a/libensemble/gen_funcs/uniform_or_localopt.py
+++ b/libensemble/gen_funcs/uniform_or_localopt.py
@@ -15,7 +15,7 @@ def uniform_or_localopt(H, persis_info, gen_specs, libE_info):
     ``libE_info['persistent']`` isn't ``True``).  Otherwise, the generation
     function a persistent nlopt local optimization run.
 
-    :See:
+    .. seealso::
         ``libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py``
     """
 
diff --git a/libensemble/sim_funcs/chwirut1.py b/libensemble/sim_funcs/chwirut1.py
index 59c205b33..8fac5e50f 100644
--- a/libensemble/sim_funcs/chwirut1.py
+++ b/libensemble/sim_funcs/chwirut1.py
@@ -260,10 +260,10 @@ def chwirut_eval(H, persis_info, sim_specs, _):
     component of the objective will be evaluated. Otherwise, all 214 components
     are evaluated and returned in the ``'fvec'`` field.
 
-    :See:
+    .. seealso::
         ``/libensemble/tests/regression_tests/test_chwirut_pounders.py`` for an example where the entire fvec is computed.
 
-    :See:
+    .. seealso::
         ``/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py``
     """
 
diff --git a/libensemble/sim_funcs/one_d_func.py b/libensemble/sim_funcs/one_d_func.py
index 07201eb19..bf02ed027 100644
--- a/libensemble/sim_funcs/one_d_func.py
+++ b/libensemble/sim_funcs/one_d_func.py
@@ -10,7 +10,7 @@ def one_d_example(x, persis_info, sim_specs, _):
     """
     Evaluates the six hump camel function for a single point ``x``.
 
-    :See:
+    .. seealso::
         ``/libensemble/libensemble/tests/regression_tests/test_fast_alloc.py``
     """
 
diff --git a/libensemble/sim_funcs/six_hump_camel.py b/libensemble/sim_funcs/six_hump_camel.py
index 7f51e14d8..26d1b5b62 100644
--- a/libensemble/sim_funcs/six_hump_camel.py
+++ b/libensemble/sim_funcs/six_hump_camel.py
@@ -15,7 +15,7 @@ def six_hump_camel_with_different_ranks_and_nodes(H, persis_info, sim_specs, lib
     performs a system call with a given number of nodes and ranks per node
     using a machinefile (to show one way of evaluating a compiled simulation).
 
-    :See:
+    .. seealso::
         ``/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py``
     """
 
@@ -60,7 +60,7 @@ def six_hump_camel(H, persis_info, sim_specs, _):
     ``sim_specs['out']`` and pauses for ``sim_specs['user']['pause_time']]`` if
     defined.
 
-    :See:
+    .. seealso::
         ``/libensemble/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py``
     """
 
@@ -83,7 +83,7 @@ def six_hump_camel_simple(x, persis_info, sim_specs, _):
     """
     Evaluates the six hump camel function for a single point ``x``.
 
-    :See:
+    .. seealso::
         ``/libensemble/libensemble/tests/regression_tests/test_fast_alloc.py``
     """
 

From f6f5bbe843808a8df2c1e533a41809d770ab099b Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 19 Nov 2019 12:05:12 -0600
Subject: [PATCH 567/644] Using hyperlinks instead in APOSMM

---
 libensemble/gen_funcs/aposmm.py | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/libensemble/gen_funcs/aposmm.py b/libensemble/gen_funcs/aposmm.py
index cb9dcffcb..04a457195 100644
--- a/libensemble/gen_funcs/aposmm.py
+++ b/libensemble/gen_funcs/aposmm.py
@@ -134,10 +134,12 @@ def aposmm_logic(H, persis_info, gen_specs, _):
         must ensure it's always given.
 
     .. seealso::
-        ``libensemble/tests/regression_tests/test_branin_aposmm.py``
+        `test_branin_aposmm.py<https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_branin_aposmm.py`_
         for basic APOSMM usage.
+
     .. seealso::
-        ``libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py``
+        ``libensemble/tests/regression_tests/``
+        `test_chwirut_aposmm_one_residual_at_a_time.py<https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py`_
         for an example of APOSMM coordinating multiple local optimization runs
         for an objective with more than one component.
     """
@@ -372,7 +374,7 @@ def update_history_dist(H, n, gen_specs, c_flag):
     Updates distances/indices after new points that have been evaluated.
 
     .. seealso::
-        ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
+        `start_persistent_local_opt_gens.py<https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py`_
     """
 
     updated_inds = set()
@@ -767,7 +769,7 @@ def decide_where_to_start_localopt(H, r_k, mu=0, nu=0, gamma_quantile=1):
 
 
     .. seealso::
-        ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
+        `start_persistent_local_opt_gens.py<https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py`_
     """
 
     if nu > 0:
@@ -891,7 +893,7 @@ def initialize_APOSMM(H, gen_specs):
     Computes common values every time that APOSMM is reinvoked
 
     .. seealso::
-        ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
+        `start_persistent_local_opt_gens.py<https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py`_
     """
 
     user_specs = gen_specs['user']

From 866955e5313aa2a9c0aef368f7a4bbf3e81b5661 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 19 Nov 2019 12:13:38 -0600
Subject: [PATCH 568/644] Using hyperlinks instead in APOSMM

---
 libensemble/gen_funcs/aposmm.py | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/libensemble/gen_funcs/aposmm.py b/libensemble/gen_funcs/aposmm.py
index 04a457195..20c30d3f8 100644
--- a/libensemble/gen_funcs/aposmm.py
+++ b/libensemble/gen_funcs/aposmm.py
@@ -133,13 +133,14 @@ def aposmm_logic(H, persis_info, gen_specs, _):
         active runs, order of points in each run, etc. The allocation function
         must ensure it's always given.
 
+    `Python <http://www.python.org/>`_
+
     .. seealso::
-        `test_branin_aposmm.py<https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_branin_aposmm.py`_
+        `test_branin_aposmm_nlopt_and_then_scipy.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py>`_
         for basic APOSMM usage.
 
     .. seealso::
-        ``libensemble/tests/regression_tests/``
-        `test_chwirut_aposmm_one_residual_at_a_time.py<https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py`_
+        `test_chwirut_aposmm_one_residual_at_a_time.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py>`_
         for an example of APOSMM coordinating multiple local optimization runs
         for an objective with more than one component.
     """
@@ -374,7 +375,7 @@ def update_history_dist(H, n, gen_specs, c_flag):
     Updates distances/indices after new points that have been evaluated.
 
     .. seealso::
-        `start_persistent_local_opt_gens.py<https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py`_
+        `start_persistent_local_opt_gens.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py>`_
     """
 
     updated_inds = set()
@@ -769,7 +770,7 @@ def decide_where_to_start_localopt(H, r_k, mu=0, nu=0, gamma_quantile=1):
 
 
     .. seealso::
-        `start_persistent_local_opt_gens.py<https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py`_
+        `start_persistent_local_opt_gens.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py>`_
     """
 
     if nu > 0:
@@ -893,7 +894,7 @@ def initialize_APOSMM(H, gen_specs):
     Computes common values every time that APOSMM is reinvoked
 
     .. seealso::
-        `start_persistent_local_opt_gens.py<https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py`_
+        `start_persistent_local_opt_gens.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py>`_
     """
 
     user_specs = gen_specs['user']

From d85c9df6efc3cc0dbeca7719bc29dcae5cbe6015 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 19 Nov 2019 12:38:30 -0600
Subject: [PATCH 569/644] Using hyperlinks elsewhere

---
 libensemble/alloc_funcs/fast_alloc.py                 |  2 +-
 libensemble/alloc_funcs/fast_alloc_and_pausing.py     |  2 +-
 libensemble/alloc_funcs/fast_alloc_to_aposmm.py       |  2 +-
 libensemble/alloc_funcs/give_pregenerated_work.py     |  2 +-
 libensemble/alloc_funcs/give_sim_work_first.py        |  2 +-
 libensemble/alloc_funcs/persistent_aposmm_alloc.py    |  2 +-
 libensemble/alloc_funcs/start_only_persistent.py      |  2 +-
 .../alloc_funcs/start_persistent_local_opt_gens.py    |  2 +-
 libensemble/gen_funcs/aposmm.py                       |  2 --
 libensemble/gen_funcs/persistent_aposmm.py            | 11 ++++++-----
 libensemble/gen_funcs/persistent_uniform_sampling.py  |  2 +-
 libensemble/gen_funcs/sampling.py                     |  6 +++---
 libensemble/gen_funcs/uniform_or_localopt.py          |  2 +-
 libensemble/sim_funcs/chwirut1.py                     |  6 ++++--
 libensemble/sim_funcs/one_d_func.py                   |  2 +-
 libensemble/sim_funcs/six_hump_camel.py               |  6 +++---
 16 files changed, 27 insertions(+), 26 deletions(-)

diff --git a/libensemble/alloc_funcs/fast_alloc.py b/libensemble/alloc_funcs/fast_alloc.py
index 6b8e0a720..c8595207b 100644
--- a/libensemble/alloc_funcs/fast_alloc.py
+++ b/libensemble/alloc_funcs/fast_alloc.py
@@ -10,7 +10,7 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     more than ``gen_specs['user']['num_active_gen']`` active generators.
 
     .. seealso::
-        ``/libensemble/tests/regression_tests/test_fast_alloc.py``
+        `test_fast_alloc.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_fast_alloc.py>`_
     """
 
     Work = {}
diff --git a/libensemble/alloc_funcs/fast_alloc_and_pausing.py b/libensemble/alloc_funcs/fast_alloc_and_pausing.py
index 7f0700195..c4115f669 100644
--- a/libensemble/alloc_funcs/fast_alloc_and_pausing.py
+++ b/libensemble/alloc_funcs/fast_alloc_and_pausing.py
@@ -22,7 +22,7 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
         combine_component_func is larger than a known upper bound on the objective.
 
     .. seealso::
-        ``/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py``
+        `test_chwirut_uniform_sampling_one_residual_at_a_time.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py>`_
     """
 
     Work = {}
diff --git a/libensemble/alloc_funcs/fast_alloc_to_aposmm.py b/libensemble/alloc_funcs/fast_alloc_to_aposmm.py
index 3051b0db8..94ed90c79 100644
--- a/libensemble/alloc_funcs/fast_alloc_to_aposmm.py
+++ b/libensemble/alloc_funcs/fast_alloc_to_aposmm.py
@@ -13,7 +13,7 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     for a 'batch_mode'.
 
     .. seealso::
-        ``/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py``
+        `test_6-hump_camel_aposmm_LD_MMA.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py>`_
     """
 
     Work = {}
diff --git a/libensemble/alloc_funcs/give_pregenerated_work.py b/libensemble/alloc_funcs/give_pregenerated_work.py
index 7d29473f3..4da5edb72 100644
--- a/libensemble/alloc_funcs/give_pregenerated_work.py
+++ b/libensemble/alloc_funcs/give_pregenerated_work.py
@@ -7,7 +7,7 @@ def give_pregenerated_sim_work(W, H, sim_specs, gen_specs, alloc_specs, persis_i
     idle workers. It is an example use case where no gen_func is used.
 
     .. seealso::
-        ``/libensemble/tests/regression_tests/test_fast_alloc.py``
+        `test_fast_alloc.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_fast_alloc.py>`_
     """
 
     Work = {}
diff --git a/libensemble/alloc_funcs/give_sim_work_first.py b/libensemble/alloc_funcs/give_sim_work_first.py
index 2195bc67d..54a25aaa1 100644
--- a/libensemble/alloc_funcs/give_sim_work_first.py
+++ b/libensemble/alloc_funcs/give_sim_work_first.py
@@ -21,7 +21,7 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     This is the default allocation function if one is not defined.
 
     .. seealso::
-        ``/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py``
+        `test_6-hump_camel_uniform_sampling.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py>`_
     """
 
     Work = {}
diff --git a/libensemble/alloc_funcs/persistent_aposmm_alloc.py b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
index 318c4ee5c..5a87850c3 100644
--- a/libensemble/alloc_funcs/persistent_aposmm_alloc.py
+++ b/libensemble/alloc_funcs/persistent_aposmm_alloc.py
@@ -14,7 +14,7 @@ def persistent_aposmm_alloc(W, H, sim_specs, gen_specs, alloc_specs, persis_info
     stopped (until some exit_criterion is satisfied).
 
     .. seealso::
-        ``/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py``
+        `test_6-hump_camel_persistent_aposmm.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py>`_
     """
 
     Work = {}
diff --git a/libensemble/alloc_funcs/start_only_persistent.py b/libensemble/alloc_funcs/start_only_persistent.py
index a62d0e5a1..3d832de45 100644
--- a/libensemble/alloc_funcs/start_only_persistent.py
+++ b/libensemble/alloc_funcs/start_only_persistent.py
@@ -11,7 +11,7 @@ def only_persistent_gens(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     then this information is given back to the persistent generator.
 
     .. seealso::
-        ``/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py``
+        `test_6-hump_camel_persistent_uniform_sampling.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py>`_
     """
 
     Work = {}
diff --git a/libensemble/alloc_funcs/start_persistent_local_opt_gens.py b/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
index dcaf31ef1..698f158b9 100644
--- a/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
+++ b/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
@@ -21,7 +21,7 @@ def start_persistent_local_opt_gens(W, H, sim_specs, gen_specs, alloc_specs, per
     - If no points are left, call the generation function.
 
     .. seealso::
-        ``/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py``
+        `test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py>`_
     """
 
     Work = {}
diff --git a/libensemble/gen_funcs/aposmm.py b/libensemble/gen_funcs/aposmm.py
index 20c30d3f8..d83112f33 100644
--- a/libensemble/gen_funcs/aposmm.py
+++ b/libensemble/gen_funcs/aposmm.py
@@ -133,8 +133,6 @@ def aposmm_logic(H, persis_info, gen_specs, _):
         active runs, order of points in each run, etc. The allocation function
         must ensure it's always given.
 
-    `Python <http://www.python.org/>`_
-
     .. seealso::
         `test_branin_aposmm_nlopt_and_then_scipy.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py>`_
         for basic APOSMM usage.
diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index 292a3836c..fea4c2f7b 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -142,10 +142,11 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         must ensure it's always given.
 
     .. seealso::
-        ``libensemble/tests/regression_tests/test_branin_aposmm.py``
+        `test_branin_aposmm_nlopt_and_then_scipy.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py>`_
         for basic APOSMM usage.
+
     .. seealso::
-        ``libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py``
+        `test_chwirut_aposmm_one_residual_at_a_time.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py>`_
         for an example of APOSMM coordinating multiple local optimization runs
         for an objective with more than one component.
     """
@@ -672,7 +673,7 @@ def update_history_dist(H, n):
     Updates distances/indices after new points that have been evaluated.
 
     .. seealso::
-        ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
+        `start_persistent_local_opt_gens.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py>`_
     """
 
     new_inds = np.where(~H['known_to_aposmm'])[0]
@@ -804,7 +805,7 @@ def decide_where_to_start_localopt(H, n, n_s, rk_const, ld=0, mu=0, nu=0):
 
 
     .. seealso::
-        ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
+        `start_persistent_local_opt_gens.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py>`_
     """
 
     r_k = calc_rk(n, n_s, rk_const, ld)
@@ -896,7 +897,7 @@ def initialize_APOSMM(H, user_specs, libE_info):
     Computes common values every time that APOSMM is reinvoked
 
     .. seealso::
-        ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
+        `start_persistent_local_opt_gens.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py>`_
     """
     n = len(user_specs['ub'])
 
diff --git a/libensemble/gen_funcs/persistent_uniform_sampling.py b/libensemble/gen_funcs/persistent_uniform_sampling.py
index 48fbdb524..6f3a826ce 100644
--- a/libensemble/gen_funcs/persistent_uniform_sampling.py
+++ b/libensemble/gen_funcs/persistent_uniform_sampling.py
@@ -10,7 +10,7 @@ def persistent_uniform(H, persis_info, gen_specs, libE_info):
     ``gen_specs['gen_batch_size']`` uniformly sampled points.
 
     .. seealso::
-        ``libensemble/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py``
+        `test_6-hump_camel_persistent_uniform_sampling.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py>`_
     """
     ub = gen_specs['user']['ub']
     lb = gen_specs['user']['lb']
diff --git a/libensemble/gen_funcs/sampling.py b/libensemble/gen_funcs/sampling.py
index eae6c09e2..9dfe338aa 100644
--- a/libensemble/gen_funcs/sampling.py
+++ b/libensemble/gen_funcs/sampling.py
@@ -13,7 +13,7 @@ def uniform_random_sample_with_different_nodes_and_ranks(H, persis_info, gen_spe
     and ``ranks_per_node`` to be used in the evaluation of the generated point.
 
     .. seealso:: 
-        ``libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py``
+        `test_6-hump_camel_with_different_nodes_uniform_sample.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py>`_
     """
     ub = gen_specs['user']['ub']
     lb = gen_specs['user']['lb']
@@ -47,7 +47,7 @@ def uniform_random_sample_obj_components(H, persis_info, gen_specs, _):
     separately.
 
     .. seealso:: 
-        ``libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py``
+        `test_chwirut_uniform_sampling_one_residual_at_a_time.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py>`_
     """
     ub = gen_specs['user']['ub']
     lb = gen_specs['user']['lb']
@@ -75,7 +75,7 @@ def uniform_random_sample(H, persis_info, gen_specs, _):
     defined by ``gen_specs['user']['ub']`` and ``gen_specs['user']['lb']``.
 
     .. seealso:: 
-        ``libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py``
+        `test_6-hump_camel_uniform_sampling.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py>`_
     """
     ub = gen_specs['user']['ub']
     lb = gen_specs['user']['lb']
diff --git a/libensemble/gen_funcs/uniform_or_localopt.py b/libensemble/gen_funcs/uniform_or_localopt.py
index 05da55ca2..a2830832a 100644
--- a/libensemble/gen_funcs/uniform_or_localopt.py
+++ b/libensemble/gen_funcs/uniform_or_localopt.py
@@ -16,7 +16,7 @@ def uniform_or_localopt(H, persis_info, gen_specs, libE_info):
     function a persistent nlopt local optimization run.
 
     .. seealso::
-        ``libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py``
+        `test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py>`_
     """
 
     if libE_info.get('persistent'):
diff --git a/libensemble/sim_funcs/chwirut1.py b/libensemble/sim_funcs/chwirut1.py
index 8fac5e50f..856ebbaa0 100644
--- a/libensemble/sim_funcs/chwirut1.py
+++ b/libensemble/sim_funcs/chwirut1.py
@@ -261,10 +261,12 @@ def chwirut_eval(H, persis_info, sim_specs, _):
     are evaluated and returned in the ``'fvec'`` field.
 
     .. seealso::
-        ``/libensemble/tests/regression_tests/test_chwirut_pounders.py`` for an example where the entire fvec is computed.
+        `test_chwirut_pounders.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_chwirut_pounders.py>`_
+        for an example where the entire fvec is computed each call.
 
     .. seealso::
-        ``/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py``
+        `test_chwirut_aposmm_one_residual_at_a_time.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py>`_
+        for an example where one component of fvec is computed per call
     """
 
     batch = len(H['x'])
diff --git a/libensemble/sim_funcs/one_d_func.py b/libensemble/sim_funcs/one_d_func.py
index bf02ed027..f0dadb2ec 100644
--- a/libensemble/sim_funcs/one_d_func.py
+++ b/libensemble/sim_funcs/one_d_func.py
@@ -11,7 +11,7 @@ def one_d_example(x, persis_info, sim_specs, _):
     Evaluates the six hump camel function for a single point ``x``.
 
     .. seealso::
-        ``/libensemble/libensemble/tests/regression_tests/test_fast_alloc.py``
+        `test_fast_alloc.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_fast_alloc.py>`_
     """
 
     O = np.zeros(1, dtype=sim_specs['out'])
diff --git a/libensemble/sim_funcs/six_hump_camel.py b/libensemble/sim_funcs/six_hump_camel.py
index 26d1b5b62..69a44a3e1 100644
--- a/libensemble/sim_funcs/six_hump_camel.py
+++ b/libensemble/sim_funcs/six_hump_camel.py
@@ -16,7 +16,7 @@ def six_hump_camel_with_different_ranks_and_nodes(H, persis_info, sim_specs, lib
     using a machinefile (to show one way of evaluating a compiled simulation).
 
     .. seealso::
-        ``/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py``
+        `test_6-hump_camel_with_different_nodes_uniform_sample.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py>`_
     """
 
     from mpi4py import MPI
@@ -61,7 +61,7 @@ def six_hump_camel(H, persis_info, sim_specs, _):
     defined.
 
     .. seealso::
-        ``/libensemble/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py``
+        `test_6-hump_camel_aposmm_LD_MMA.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py>`_
     """
 
     batch = len(H['x'])
@@ -84,7 +84,7 @@ def six_hump_camel_simple(x, persis_info, sim_specs, _):
     Evaluates the six hump camel function for a single point ``x``.
 
     .. seealso::
-        ``/libensemble/libensemble/tests/regression_tests/test_fast_alloc.py``
+        `test_fast_alloc.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_fast_alloc.py>`_
     """
 
     O = np.zeros(1, dtype=sim_specs['out'])

From c929d538649f2320deb3a58f553fac5456b22dea Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 19 Nov 2019 12:44:24 -0600
Subject: [PATCH 570/644] Whitespace

---
 libensemble/gen_funcs/sampling.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/libensemble/gen_funcs/sampling.py b/libensemble/gen_funcs/sampling.py
index 9dfe338aa..06b35c118 100644
--- a/libensemble/gen_funcs/sampling.py
+++ b/libensemble/gen_funcs/sampling.py
@@ -12,7 +12,7 @@ def uniform_random_sample_with_different_nodes_and_ranks(H, persis_info, gen_spe
     ``gen_specs['user']['lb']``. Also randomly requests a different ``number_of_nodes``
     and ``ranks_per_node`` to be used in the evaluation of the generated point.
 
-    .. seealso:: 
+    .. seealso::
         `test_6-hump_camel_with_different_nodes_uniform_sample.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py>`_
     """
     ub = gen_specs['user']['ub']
@@ -46,7 +46,7 @@ def uniform_random_sample_obj_components(H, persis_info, gen_specs, _):
     and ``gen_specs['user']['lb']`` but requests each ``obj_component`` be evaluated
     separately.
 
-    .. seealso:: 
+    .. seealso::
         `test_chwirut_uniform_sampling_one_residual_at_a_time.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py>`_
     """
     ub = gen_specs['user']['ub']
@@ -74,7 +74,7 @@ def uniform_random_sample(H, persis_info, gen_specs, _):
     Generates ``gen_specs['user']['gen_batch_size']`` points uniformly over the domain
     defined by ``gen_specs['user']['ub']`` and ``gen_specs['user']['lb']``.
 
-    .. seealso:: 
+    .. seealso::
         `test_6-hump_camel_uniform_sampling.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py>`_
     """
     ub = gen_specs['user']['ub']

From 055188d20e1123dd7ad82b435d587103de9d3138 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Tue, 19 Nov 2019 13:21:06 -0600
Subject: [PATCH 571/644] Updates to Platforms

---
 docs/platforms/platforms_index.rst |  2 +-
 docs/platforms/summit.rst          | 36 ++++++++++++++++++++----------
 docs/platforms/theta.rst           |  2 +-
 3 files changed, 26 insertions(+), 14 deletions(-)

diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst
index 818c56671..8903175dd 100644
--- a/docs/platforms/platforms_index.rst
+++ b/docs/platforms/platforms_index.rst
@@ -6,7 +6,7 @@ scales, from laptops to thousands of compute-nodes. libEnsemble's embarrassingly
 parallel  scaling capabilities are best exemplified on the resources available
 within high-performance machines.
 
-libEnsemble's flexible architecture lends it best to two general modes of worker
+libEnsemble's flexible architecture lends itself best to two general modes of worker
 distributions across allocated compute nodes. The first mode we refer
 to as *centralized* mode, where the libEnsemble manager and worker processes
 are grouped on one or more nodes, but through the libEnsemble job-controller or a
diff --git a/docs/platforms/summit.rst b/docs/platforms/summit.rst
index e2307bd3a..5e20bd76a 100644
--- a/docs/platforms/summit.rst
+++ b/docs/platforms/summit.rst
@@ -3,11 +3,15 @@ Summit
 ======
 
 Summit_ is an IBM AC922 system located at the Oak Ridge Leadership Computing Facility.
-Each of the approximately 4,600 compute nodes on Summit contains two IBM POWER9 processors and six NVIDIA Volta V100 accelerators.
+Each of the approximately 4,600 compute nodes on Summit contains two IBM POWER9
+processors and six NVIDIA Volta V100 accelerators.
 
 Summit features three tiers of nodes: login, launch, and compute nodes.
+
 Users on login nodes submit batch runs to the launch nodes.
-Launch nodes execute user batch-scripts to run on the compute nodes via ``jsrun``.
+Batch scripts and interactive sessions run on the launch nodes. Only the launch nodes
+can submit MPI runs to the compute nodes via ``jsrun``.
+
 
 Configuring Python
 ------------------
@@ -16,12 +20,9 @@ Begin by loading the Python 3 Anaconda module::
 
     $ module load python
 
-You can now create your own custom Conda_ environment::
+You can now create and activate your own custom Conda_ environment::
 
     conda create --name myenv python=3.7
-
-Now activate environment::
-
     export PYTHONNOUSERSITE=1 # Make sure get python from conda env
     . activate myenv
 
@@ -56,8 +57,8 @@ important command is ``bsub``, for submitting batch scripts from the login nodes
 to execute on the Launch nodes.
 
 It is recommended to run libEnsemble on the Launch nodes (assuming workers are submitting
-MPI jobs) using ``local`` comm mode (multiprocessing). In the future, Balsam may be used
-to run libEnsemble on compute nodes.
+MPI jobs) using the ``local`` communications mode (multiprocessing).
+In the future, Balsam may be used to run libEnsemble on compute nodes.
 
 Interactive Runs
 ^^^^^^^^^^^^^^^^
@@ -67,8 +68,7 @@ to the following::
 
     $ bsub -W 30 -P [project] -nnodes 8 -Is
 
-This will place the user on a launch node. Then, to launch MPI jobs to the compute
-nodes use ``jsrun`` where you would use ``mpirun``.
+This will place the user on a launch node.
 
 .. note::
     You will need to re-activate your conda virtual environment.
@@ -79,7 +79,7 @@ Batch Runs
 Batch scripts specify run-settings using ``#BSUB`` statements. The following
 simple example depicts configuring and launching libEnsemble to a launch node with
 multiprocessing. This script also assumes the user is using the ``parse_args()``
-convenience function within libEnsemble's ``utils.py``.
+convenience function from libEnsemble's :doc:`utils module<../utilities>`.
 
 .. code-block:: bash
 
@@ -122,7 +122,19 @@ convenience function within libEnsemble's ``utils.py``.
 With this saved as ``myscript.sh``, allocating, configuring, and queueing
 libEnsemble on Summit becomes::
 
-    $ bsub script myscript.sh
+    $ bsub myscript.sh
+
+
+Launching user applications from libEnsemble Workers
+----------------------------------------------------
+
+Only the launch nodes can submit MPI runs to the compute nodes via ``jsrun``.
+This can be accomplished in user sim_f functions directly. However, it is highly
+recommended that the :doc:`job_controller<../job_controller/overview>` interface
+is used inside the sim_f (or gen_f), as this provides a portable interface
+with many advantages including automatic resource detection, portability,
+launch failure resilience, and ease of use.
+
 
 Additional Information
 ----------------------
diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index 094b69ea5..209f4a05c 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -135,7 +135,7 @@ Batch Runs
 Batch scripts specify run-settings using ``#COBALT`` statements. The following
 simple example depicts configuring and launching libEnsemble to a MOM node with
 multiprocessing. This script also assumes the user is using the ``parse_args()``
-convenience function within libEnsemble's ``utils.py``.
+convenience function from libEnsemble's :doc:`utils module<../utilities>`.
 
 .. code-block:: bash
 

From cf03733ba86c2fea79431d7a53efaada4f947941 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 19 Nov 2019 14:01:45 -0600
Subject: [PATCH 572/644] wrapping adjust

---
 docs/platforms/summit.rst | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/docs/platforms/summit.rst b/docs/platforms/summit.rst
index 5e20bd76a..081794d12 100644
--- a/docs/platforms/summit.rst
+++ b/docs/platforms/summit.rst
@@ -2,15 +2,15 @@
 Summit
 ======
 
-Summit_ is an IBM AC922 system located at the Oak Ridge Leadership Computing Facility.
-Each of the approximately 4,600 compute nodes on Summit contains two IBM POWER9
-processors and six NVIDIA Volta V100 accelerators.
+Summit_ is an IBM AC922 system located at the Oak Ridge Leadership Computing
+Facility. Each of the approximately 4,600 compute nodes on Summit contains two
+IBM POWER9 processors and six NVIDIA Volta V100 accelerators.
 
 Summit features three tiers of nodes: login, launch, and compute nodes.
 
 Users on login nodes submit batch runs to the launch nodes.
-Batch scripts and interactive sessions run on the launch nodes. Only the launch nodes
-can submit MPI runs to the compute nodes via ``jsrun``.
+Batch scripts and interactive sessions run on the launch nodes. Only the launch
+nodes can submit MPI runs to the compute nodes via ``jsrun``.
 
 
 Configuring Python
@@ -26,9 +26,9 @@ You can now create and activate your own custom Conda_ environment::
     export PYTHONNOUSERSITE=1 # Make sure get python from conda env
     . activate myenv
 
-If you are installing any packages with extensions, ensure the correct compiler module
-is loaded. If using mpi4py_, this must be installed from source, referencing the compiler.
-At time of writing, mpi4py must be built with gcc::
+If you are installing any packages with extensions, ensure the correct compiler
+module is loaded. If using mpi4py_, this must be installed from source,
+referencing the compiler. At time of writing, mpi4py must be built with gcc::
 
     module load gcc
 
@@ -56,15 +56,15 @@ Summit uses LSF_ for job management and submission. For libEnsemble, the most
 important command is ``bsub``, for submitting batch scripts from the login nodes
 to execute on the Launch nodes.
 
-It is recommended to run libEnsemble on the Launch nodes (assuming workers are submitting
-MPI jobs) using the ``local`` communications mode (multiprocessing).
+It is recommended to run libEnsemble on the Launch nodes (assuming workers are
+submitting MPI jobs) using the ``local`` communications mode (multiprocessing).
 In the future, Balsam may be used to run libEnsemble on compute nodes.
 
 Interactive Runs
 ^^^^^^^^^^^^^^^^
 
-Users can run interactively with ``bsub`` by specifying the ``-Is`` flag, similarly
-to the following::
+Users can run interactively with ``bsub`` by specifying the ``-Is`` flag,
+similarly to the following::
 
     $ bsub -W 30 -P [project] -nnodes 8 -Is
 

From c5bb8db6bd87636fdcd05d1f8c282a2cac62a4a7 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 19 Nov 2019 14:16:10 -0600
Subject: [PATCH 573/644] formatting, clarify advantages of job controller

---
 docs/platforms/summit.rst |  6 +++---
 docs/platforms/theta.rst  | 10 ++++++++--
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/docs/platforms/summit.rst b/docs/platforms/summit.rst
index 081794d12..1cdf7caec 100644
--- a/docs/platforms/summit.rst
+++ b/docs/platforms/summit.rst
@@ -129,11 +129,11 @@ Launching user applications from libEnsemble Workers
 ----------------------------------------------------
 
 Only the launch nodes can submit MPI runs to the compute nodes via ``jsrun``.
-This can be accomplished in user sim_f functions directly. However, it is highly
+This can be accomplished in user ``sim_f`` functions directly. However, it is highly
 recommended that the :doc:`job_controller<../job_controller/overview>` interface
-is used inside the sim_f (or gen_f), as this provides a portable interface
+is used inside the ``sim_f`` or ``gen_f``, as this provides a portable interface
 with many advantages including automatic resource detection, portability,
-launch failure resilience, and ease of use.
+launch failure resilience, and ease-of-use.
 
 
 Additional Information
diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index 209f4a05c..23d45e72d 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -89,14 +89,14 @@ On Theta, libEnsemble can be launched to two locations:
 
     1. **A MOM Node**: All of libEnsemble's manager and worker processes
     run on a front-end MOM node. libEnsemble's MPI job-controller takes
-    responsibility for direct job-submission to allocated compute nodes.
+    responsibility for direct user-application submission to allocated compute nodes.
     libEnsemble must be configured to run with *multiprocessing* communications,
     since mpi4py isn't configured for use on the MOM nodes.
 
     2. **The Compute Nodes**: libEnsemble is submitted to Balsam and all manager
     and worker processes are tasked to a backend compute node. libEnsemble's
     Balsam job-controller interfaces with Balsam running on a MOM node for dynamic
-    task submission to the compute nodes.
+    user-application submission to the compute nodes.
 
     .. image:: ../images/combined_ThS.png
         :alt: central_MOM
@@ -107,6 +107,12 @@ When considering on which nodes to run libEnsemble, consider if your user
 functions execute computationally expensive code, or code built for specific
 architectures. Recall also that only the MOM nodes can launch MPI jobs.
 
+Although libEnsemble workers on the MOM nodes can technically submit
+user-applications to the compute nodes via ``aprun`` within user functions, it
+is highly recommended that the aforementioned :doc:`job_controller<../job_controller/overview>`
+interface is used instead. The libEnsemble job-controller features advantages like
+automatic resource-detection, portability, launch failure resilience, and ease-of-use.
+
 Theta features one default production queue, ``default``, and two debug queues,
 ``debug-cache-quad`` and ``debug-flat-quad``.
 

From 4c72258bb78a0ba569eaaa9527b640be288fd302 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 19 Nov 2019 15:19:55 -0600
Subject: [PATCH 574/644] Trying to see if we can get bibliography to build on
 RTD

---
 docs/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index b45b78d79..990ddf338 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -53,7 +53,7 @@ def __getattr__(cls, name):
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-# needs_sphinx = '2.0'
+needs_sphinx = '3.0'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

From ef595b8961f6012dee778a17e1fdfd5ba23c7ccb Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 19 Nov 2019 15:20:22 -0600
Subject: [PATCH 575/644] rename welcome link

---
 docs/welcome.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/welcome.rst b/docs/welcome.rst
index 7decf8888..47d45369e 100644
--- a/docs/welcome.rst
+++ b/docs/welcome.rst
@@ -27,5 +27,5 @@ libEnsemble is a library to coordinate the concurrent evaluation of dynamic ense
 
 * New to libEnsemble? Start :doc:`here<introduction>`.
 * Try out libEnsemble with a :doc:`tutorial<tutorials/local_sine_tutorial>`.
-* Go in-depth by reading the :doc:`User Guide<programming_libE>`.
+* Go in-depth by reading the :doc:`Overview<overview_usecases>`.
 * Check the :doc:`FAQ<FAQ>` for common questions and answers, errors and resolutions.

From 228827cb7f2f381e86c872ec0674f4c93f6da645 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 19 Nov 2019 15:24:58 -0600
Subject: [PATCH 576/644] Making like to flake8 file

---
 CONTRIBUTING.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index cb40685d2..86d20f1fc 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -8,9 +8,7 @@ Contributions may be made via GitHub pull request to:
 libEnsemble uses the Gitflow model. Contributors should branch from, and
 make pull requests to, the develop branch. The master branch is used only
 for releases. Code should pass flake8 tests, allowing for the exceptions
-given in the ``.flake8`` file in the project directory:
-
-.. literalinclude:: ../.flake8
+given in the flake8_ file in the project directory.
 
 Issues can be raised at:
 
@@ -66,3 +64,5 @@ following:
       personal information I submit with it, including my sign-off) is
       maintained indefinitely and may be redistributed consistent with
       this project or the open source license(s) involved.
+
+.. _flake8: https://github.com/Libensemble/libensemble/blob/develop/.flake8

From 8f0aebdb51e5a1a01473bdc55815e4b0432f73cf Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 19 Nov 2019 15:31:35 -0600
Subject: [PATCH 577/644] Trying sphinx3

---
 conda/environment.yml | 3 ++-
 docs/conf.py          | 2 +-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/conda/environment.yml b/conda/environment.yml
index 0637adca0..e6d8c8c8b 100644
--- a/conda/environment.yml
+++ b/conda/environment.yml
@@ -4,4 +4,5 @@ channels:
 
 dependencies:
  - sphinxcontrib-bibtex
- - python>=3.6
\ No newline at end of file
+ - sphinx>=3
+ - python>=3.6
diff --git a/docs/conf.py b/docs/conf.py
index 990ddf338..fadab367f 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -53,7 +53,7 @@ def __getattr__(cls, name):
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
-needs_sphinx = '3.0'
+needs_sphinx = '2.0'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

From 14bd8bae3aec38e6acc3a6f1a35146be1d88e0b4 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 19 Nov 2019 15:34:34 -0600
Subject: [PATCH 578/644] Trying sphinx3

---
 conda/environment.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/conda/environment.yml b/conda/environment.yml
index e6d8c8c8b..f6716c846 100644
--- a/conda/environment.yml
+++ b/conda/environment.yml
@@ -4,5 +4,5 @@ channels:
 
 dependencies:
  - sphinxcontrib-bibtex
- - sphinx>=3
+ - sphinx-build>=3
  - python>=3.6

From d42981573ed1d25fdd1ceb5718858b7cd8e26d92 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 19 Nov 2019 15:37:10 -0600
Subject: [PATCH 579/644] Trying sphinx3

---
 conda/environment.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/conda/environment.yml b/conda/environment.yml
index f6716c846..01fd94b91 100644
--- a/conda/environment.yml
+++ b/conda/environment.yml
@@ -4,5 +4,4 @@ channels:
 
 dependencies:
  - sphinxcontrib-bibtex
- - sphinx-build>=3
  - python>=3.6

From 4bef803a6401fd7bc3dc8094d2b320450bf59c3c Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 19 Nov 2019 16:16:44 -0600
Subject: [PATCH 580/644] update tutorials with persis_info and random streams
 util

---
 docs/tutorials/local_sine_tutorial.rst     | 30 ++++++++++------------
 examples/tutorials/tutorial_calling.py     | 11 +++-----
 examples/tutorials/tutorial_calling_mpi.py | 17 +++++-------
 3 files changed, 25 insertions(+), 33 deletions(-)

diff --git a/docs/tutorials/local_sine_tutorial.rst b/docs/tutorials/local_sine_tutorial.rst
index 1c64bdb12..af92e7c15 100644
--- a/docs/tutorials/local_sine_tutorial.rst
+++ b/docs/tutorials/local_sine_tutorial.rst
@@ -3,7 +3,8 @@ Simple Local Sine Tutorial
 ==========================
 
 This introductory tutorial demonstrates the capability to perform ensembles of
-calculations in parallel using :doc:`libEnsemble<../introduction>` with Python's Multiprocessing.
+calculations in parallel using :doc:`libEnsemble<../introduction>` with Python's
+Multiprocessing.
 
 The foundation of writing libEnsemble routines is accounting for four components:
 
@@ -13,17 +14,18 @@ The foundation of writing libEnsemble routines is accounting for four components
     4. The calling script, which defines parameters and information about these functions and the libEnsemble task, then begins execution.
 
 libEnsemble initializes a *manager* process and as many *worker* processes as the
-user requests. The manager coordinates data-transfer between workers and assigns each
-units of work, consisting of a ``gen_f`` or ``sim_f`` function to run and
+user requests. The manager coordinates data-transfer between workers and assigns
+each units of work, consisting of a ``gen_f`` or ``sim_f`` function to run and
 accompanying data. These functions can perform their work in-line with Python or by
 launching and controlling user-applications with a :ref:`job controller<jobcontroller_index>`.
 Finally, workers pass results back to the manager.
 
-For this tutorial, we'll write our ``gen_f`` and ``sim_f`` entirely in Python without
-other applications. Our ``gen_f`` will produce uniform randomly-sampled
-values, and our ``sim_f`` will calculate the sine of each. By default we don't need to
-write a new allocation function. All generated and simulated values alongside other
-parameters are stored in :ref:`H<datastruct-history-array>`, the History array.
+For this tutorial, we'll write our ``gen_f`` and ``sim_f`` entirely in Python
+without other applications. Our ``gen_f`` will produce uniform randomly-sampled
+values, and our ``sim_f`` will calculate the sine of each. By default we don't
+need to write a new allocation function. All generated and simulated values
+alongside other parameters are stored in :ref:`H<datastruct-history-array>`,
+the History array.
 
 .. _libEnsemble: https://libensemble.readthedocs.io/en/latest/quickstart.html
 
@@ -199,18 +201,14 @@ inputs and outputs from those functions to expect.
 
 Recall that each worker is assigned an entry in the :ref:`persis_info<datastruct-persis-info>`
 dictionary that, in this tutorial, contains  a ``RandomState()`` random stream for
-uniform random sampling. We populate that dictionary here. Finally, we specify the
-circumstances where libEnsemble should stop execution in :ref:`exit_criteria<datastruct-exit-criteria>`.
+uniform random sampling. We populate that dictionary here using a utility from
+the :doc:`utils module<../utilities>`. Finally, we specify the circumstances
+where libEnsemble should stop execution in :ref:`exit_criteria<datastruct-exit-criteria>`.
 
 .. code-block:: python
     :linenos:
 
-    persis_info = {}
-
-    for i in range(1, nworkers+1):            # Worker numbers start at 1
-        persis_info[i] = {
-            'rand_stream': np.random.RandomState(i),
-            'worker_num': i}
+    persis_info = add_unique_random_streams({}, nworkers+1) # Worker numbers start at 1
 
     exit_criteria = {'sim_max': 80}           # Stop libEnsemble after 80 simulations
 
diff --git a/examples/tutorials/tutorial_calling.py b/examples/tutorials/tutorial_calling.py
index 88757f53b..ac8620502 100644
--- a/examples/tutorials/tutorial_calling.py
+++ b/examples/tutorials/tutorial_calling.py
@@ -1,6 +1,7 @@
 import numpy as np
 import matplotlib.pyplot as plt
 from libensemble.libE import libE
+from libensemble.utils import add_unique_random_streams
 from tutorial_gen import gen_random_sample
 from tutorial_sim import sim_find_sine
 
@@ -19,19 +20,15 @@
              'in': ['x'],                       # Input field names. 'x' from gen_f output
              'out': [('y', float)]}             # sim_f output. 'y' = sine('x')
 
-persis_info = {}
-
-for i in range(1, nworkers+1):                  # Worker numbers start at 1.
-    persis_info[i] = {
-        'rand_stream': np.random.RandomState(i),
-        'worker_num': i}
+persis_info = add_unique_random_streams({}, nworkers+1) # Worker numbers start at 1
 
 exit_criteria = {'sim_max': 80}                 # Stop libEnsemble after 80 simulations
 
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
                             libE_specs=libE_specs)
 
-print([i for i in H.dtype.fields])              # Some (optional) statements to visualize our History array
+# Some (optional) statements to visualize our History array
+print([i for i in H.dtype.fields])
 print(H)
 
 colors = ['b', 'g', 'r', 'y', 'm', 'c', 'k', 'w']
diff --git a/examples/tutorials/tutorial_calling_mpi.py b/examples/tutorials/tutorial_calling_mpi.py
index 82805aee6..4b71c4d50 100644
--- a/examples/tutorials/tutorial_calling_mpi.py
+++ b/examples/tutorials/tutorial_calling_mpi.py
@@ -1,14 +1,14 @@
 import numpy as np
 import matplotlib.pyplot as plt
 from libensemble.libE import libE
+from libensemble.utils import add_unique_random_streams
 from tutorial_gen import gen_random_sample
 from tutorial_sim import sim_find_sine
 from mpi4py import MPI
 
-# nworkers = 4                                  # nworkers will come from MPI
 libE_specs = {'comms': 'mpi'}                   # 'nworkers' removed, 'comms' now 'mpi'
 
-nworkers = MPI.COMM_WORLD.Get_size() - 1
+nworkers = MPI.COMM_WORLD.Get_size() - 1        # one process belongs to manager
 is_master = (MPI.COMM_WORLD.Get_rank() == 0)    # master process has MPI rank 0
 
 gen_specs = {'gen_f': gen_random_sample,        # Our generator function
@@ -23,20 +23,17 @@
              'in': ['x'],                       # Input field names. 'x' from gen_f output
              'out': [('y', float)]}             # sim_f output. 'y' = sine('x')
 
-persis_info = {}
-
-for i in range(1, nworkers+1):                  # Worker numbers start at 1.
-    persis_info[i] = {
-        'rand_stream': np.random.RandomState(i),
-        'worker_num': i}
+persis_info = add_unique_random_streams({}, nworkers+1) # Worker numbers start at 1
 
 exit_criteria = {'sim_max': 80}                 # Stop libEnsemble after 80 simulations
 
 H, persis_info, flag = libE(sim_specs, gen_specs, exit_criteria, persis_info,
                             libE_specs=libE_specs)
 
-if is_master:                                   # Only the master process should execute this
-    print([i for i in H.dtype.fields])          # Some (optional) statements to visualize our History array
+# Some (optional) statements to visualize our History array
+# Only the master process should execute this
+if is_master:
+    print([i for i in H.dtype.fields])
     print(H)
 
     colors = ['b', 'g', 'r', 'y', 'm', 'c', 'k', 'w']

From c9c4d76482215b1e84a7bab18996b7fb42ad211f Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Tue, 19 Nov 2019 17:20:44 -0600
Subject: [PATCH 581/644] Populate calling scripts, adjust calling script for
 clarity

---
 docs/examples/calling_scripts.rst             | 23 ++++++++++++++++++-
 .../script_test_balsam_hworld.py              |  8 +++----
 2 files changed, 26 insertions(+), 5 deletions(-)

diff --git a/docs/examples/calling_scripts.rst b/docs/examples/calling_scripts.rst
index 9a975ecb4..5efb5b7a7 100644
--- a/docs/examples/calling_scripts.rst
+++ b/docs/examples/calling_scripts.rst
@@ -1,4 +1,25 @@
 Calling Scripts
 ===============
 
-Below are example calling scripts
+Below are example calling scripts used to populate specifications for each user
+function and libEnsemble before initiating libEnsemble via the primary ``libE()``
+call.
+
+Local Sine Tutorial
+-------------------
+
+This example is from the Local Sine :doc:`Tutorial<../tutorials/local_sine_tutorial>`,
+meant to run with Python's multiprocessing as the primary ``comms`` method.
+
+..  literalinclude:: ../../examples/tutorials/tutorial_calling.py
+    :language: python
+
+Balsam Job Controller
+---------------------
+
+This example is from the regression tests. It configures MPI as the primary
+communication method, and demonstrates registering a user-application with the
+libEnsemble job controller to be launched by the job controller within the ``sim_f``.
+
+..  literalinclude:: ../../libensemble/tests/regression_tests/script_test_balsam_hworld.py
+    :language: python
diff --git a/libensemble/tests/regression_tests/script_test_balsam_hworld.py b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
index 47bce6751..fc621a2d9 100644
--- a/libensemble/tests/regression_tests/script_test_balsam_hworld.py
+++ b/libensemble/tests/regression_tests/script_test_balsam_hworld.py
@@ -9,8 +9,8 @@
 from libensemble.balsam_controller import BalsamJobController
 from libensemble.message_numbers import WORKER_DONE, WORKER_KILL_ON_ERR, WORKER_KILL_ON_TIMEOUT, JOB_FAILED
 from libensemble.libE import libE
-from libensemble.sim_funcs.job_control_hworld import job_control_hworld as sim_f
-from libensemble.gen_funcs.sampling import uniform_random_sample as gen_f
+from libensemble.sim_funcs.job_control_hworld import job_control_hworld
+from libensemble.gen_funcs.sampling import uniform_random_sample
 from libensemble.utils import add_unique_random_streams
 
 mpi4py.rc.recv_mprobe = False  # Disable matching probes
@@ -42,12 +42,12 @@ def build_simfunc():
 jobctrl = BalsamJobController(auto_resources=False)
 jobctrl.register_calc(full_path=sim_app, calc_type='sim')
 
-sim_specs = {'sim_f': sim_f,
+sim_specs = {'sim_f': job_control_hworld,
              'in': ['x'],
              'out': [('f', float), ('cstat', int)],
              'user': {'cores': cores_per_job}}
 
-gen_specs = {'gen_f': gen_f,
+gen_specs = {'gen_f': uniform_random_sample,
              'in': ['sim_id'],
              'out': [('x', float, (2,))],
              'user': {'lb': np.array([-3, -2]),

From 2adf1ec61df57ce7438395c5a5245940d15cf1a2 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Tue, 19 Nov 2019 19:12:33 -0600
Subject: [PATCH 582/644] Document calc_status

---
 docs/data_structures/calc_status.rst     | 74 ++++++++++++++++++++++++
 docs/data_structures/data_structures.rst |  1 +
 docs/sim_gen_alloc_funcs.rst             | 14 ++---
 libensemble/message_numbers.py           | 17 +++---
 4 files changed, 90 insertions(+), 16 deletions(-)
 create mode 100644 docs/data_structures/calc_status.rst

diff --git a/docs/data_structures/calc_status.rst b/docs/data_structures/calc_status.rst
new file mode 100644
index 000000000..76bec7fd2
--- /dev/null
+++ b/docs/data_structures/calc_status.rst
@@ -0,0 +1,74 @@
+.. _datastruct-calc-status:
+
+calc_status
+===========
+
+The ``calc_status`` is an integer attribute with a corresponding description that can be used in :ref:`sim_f<api_sim_f>` or :ref:`gen_f<api_gen_f>` functions to capture the status of a calcuation. This is returned to the manager and printed to the ``libE_stats.txt`` file. This is not currently used by the manager, but can still provide a useful summary in libE_stats.txt. The user determines the status of the calculation, as it could include multiple application runs. It can be added as a third return variable in sim_f or gen_f functions.
+The calc_status codes are in the ``libensemble.message_numbers`` module.
+
+Example of ``calc_status`` used along with :ref:`job controller<jobcontroller_index>` in sim_f:
+
+.. code-block:: python
+  :linenos:
+  :emphasize-lines: 4,16,19,22,30
+
+    from libensemble.message_numbers import WORKER_DONE, WORKER_KILL, JOB_FAILED
+
+    job = jobctl.launch(calc_type='sim', num_procs=cores, wait_on_run=True)
+    calc_status = UNSET_TAG
+    poll_interval = 1  # secs
+    while(not job.finished):
+        if job.runtime > time_limit:
+            job.kill()  # Timeout
+        else:
+            time.sleep(poll_interval)
+            job.poll()
+
+    if job.finished:
+        if job.state == 'FINISHED':
+            print("Job {} completed".format(job.name))
+            calc_status = WORKER_DONE
+        elif job.state == 'FAILED':
+            print("Warning: Job {} failed: Error code {}".format(job.name, job.errcode))
+            calc_status = JOB_FAILED
+        elif job.state == 'USER_KILLED':
+            print("Warning: Job {} has been killed".format(job.name))
+            calc_status = WORKER_KILL
+        else:
+            print("Warning: Job {} in unknown state {}. Error code {}".format(job.name, job.state, job.errcode))
+
+    outspecs = sim_specs['out']
+    output = np.zeros(1, dtype=outspecs)
+    output['energy'][0] = final_energy
+
+    return output, persis_info, calc_status
+
+See forces_simf.py_ for a complete example.
+
+Available values:
+
+..  literalinclude:: ../../libensemble/message_numbers.py
+    :start-after: first_calc_status_rst_tag
+    :end-before: last_calc_status_rst_tag
+
+The corresponding messages printed to the libE_stats.txt file are:
+
+..  literalinclude:: ../../libensemble/message_numbers.py
+    :start-at: calc_status_strings
+    :end-before: last_calc_status_string_rst_tag
+
+Example segment of libE_stats.txt:
+
+.. code-block:: console
+
+    Worker     1: Calc     0: gen Time: 0.00 Start: 2019-11-19 18:53:43 End: 2019-11-19 18:53:43 Status: Not set
+    Worker     1: Calc     1: sim Time: 4.41 Start: 2019-11-19 18:53:43 End: 2019-11-19 18:53:48 Status: Worker killed
+    Worker     2: Calc     0: sim Time: 5.42 Start: 2019-11-19 18:53:43 End: 2019-11-19 18:53:49 Status: Completed
+    Worker     1: Calc     2: sim Time: 2.41 Start: 2019-11-19 18:53:48 End: 2019-11-19 18:53:50 Status: Worker killed
+    Worker     2: Calc     1: sim Time: 2.41 Start: 2019-11-19 18:53:49 End: 2019-11-19 18:53:51 Status: Worker killed
+    Worker     1: Calc     3: sim Time: 4.41 Start: 2019-11-19 18:53:50 End: 2019-11-19 18:53:55 Status: Completed
+    Worker     2: Calc     2: sim Time: 4.41 Start: 2019-11-19 18:53:51 End: 2019-11-19 18:53:56 Status: Completed
+    Worker     1: Calc     4: sim Time: 4.41 Start: 2019-11-19 18:53:55 End: 2019-11-19 18:53:59 Status: Completed
+    Worker     2: Calc     3: sim Time: 4.41 Start: 2019-11-19 18:53:56 End: 2019-11-19 18:54:00 Status: Completed
+
+.. _forces_simf.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/scaling_tests/forces/forces_simf.py
diff --git a/docs/data_structures/data_structures.rst b/docs/data_structures/data_structures.rst
index fff56d816..4831393ab 100644
--- a/docs/data_structures/data_structures.rst
+++ b/docs/data_structures/data_structures.rst
@@ -34,3 +34,4 @@ function.
    history_array
    worker_array
    work_dict
+   calc_status
diff --git a/docs/sim_gen_alloc_funcs.rst b/docs/sim_gen_alloc_funcs.rst
index 09780d0ab..7a87ab3e4 100644
--- a/docs/sim_gen_alloc_funcs.rst
+++ b/docs/sim_gen_alloc_funcs.rst
@@ -71,11 +71,10 @@ Returns:
   **persis_info**: :obj:`dict`
   :doc:`(example)<data_structures/persis_info>`
 
-  **calc_tag**: :obj:`int`, optional
-  Used to tell manager why a persistent worker is stopping.
+  **calc_status**: :obj:`int`, optional.
+  Provides a job status to the Manager. Currently only used to output to libE_stats.txt file.
+  :doc:`(example)<data_structures/calc_status>`
 
-..  literalinclude:: ../libensemble/message_numbers.py
-    :end-before: last_message_number_rst_tag
 
 gen_f API
 ~~~~~~~~~
@@ -110,11 +109,10 @@ Returns:
   **persis_info**: :obj:`dict`
   :doc:`(example)<data_structures/persis_info>`
 
-  **calc_tag**: :obj:`int`, optional
-  Used to tell manager why a persistent worker is stopping.
+  **calc_status**: :obj:`int`, optional.
+  Provides a job status to the Manager. Currently only used to output to libE_stats.txt file.
+  :doc:`(example)<data_structures/calc_status>`
 
-..  literalinclude:: ../libensemble/message_numbers.py
-    :end-before: last_message_number_rst_tag
 
 alloc_f API
 ~~~~~~~~~~~
diff --git a/libensemble/message_numbers.py b/libensemble/message_numbers.py
index 59e747179..80c87cf0d 100644
--- a/libensemble/message_numbers.py
+++ b/libensemble/message_numbers.py
@@ -1,6 +1,6 @@
 # --- Tags
 
-UNSET_TAG = 0  # sh temp - this is a libE feature to be reviewed for best solution
+UNSET_TAG = 0
 EVAL_SIM_TAG = 1
 EVAL_GEN_TAG = 2
 STOP_TAG = 3
@@ -17,17 +17,17 @@
 
 
 # --- Signal flags (in message body vs tags)
-
-# CALC STATUS/SIGNAL FLAGS: In future these will be in a data structure
+# first_calc_status_rst_tag
+# CALC STATUS/SIGNAL FLAGS
 MAN_SIGNAL_FINISH = 20  # Kill jobs and shutdown worker
 MAN_SIGNAL_KILL = 21    # Kill running job - but don't stop worker
-
-WORKER_KILL = 30             # Worker kills not covered by a more specific case
+WORKER_KILL = 30        # Worker kills not covered by a more specific case
 WORKER_KILL_ON_ERR = 31
 WORKER_KILL_ON_TIMEOUT = 32
-JOB_FAILED = 33
-WORKER_DONE = 34
-CALC_EXCEPTION = 35
+JOB_FAILED = 33  # Calc had jobs that failed
+WORKER_DONE = 34  # Calculation was successful
+CALC_EXCEPTION = 35  # Reserved: Automatically used if gen_f or sim_f raised an exception.
+# last_calc_status_rst_tag
 
 calc_status_strings = {
     MAN_SIGNAL_FINISH: "Manager killed on finish",
@@ -40,3 +40,4 @@
     CALC_EXCEPTION: "Exception occurred",
     None: "Unknown Status"
 }
+# last_calc_status_string_rst_tag

From b3afda8f75de11159261fd7856b8c8259a371d7c Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 20 Nov 2019 10:11:02 -0600
Subject: [PATCH 583/644] add line numbers and line emphasis

---
 docs/examples/calling_scripts.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/examples/calling_scripts.rst b/docs/examples/calling_scripts.rst
index 5efb5b7a7..bf6ab5ec3 100644
--- a/docs/examples/calling_scripts.rst
+++ b/docs/examples/calling_scripts.rst
@@ -13,6 +13,8 @@ meant to run with Python's multiprocessing as the primary ``comms`` method.
 
 ..  literalinclude:: ../../examples/tutorials/tutorial_calling.py
     :language: python
+    :linenos:
+    :emphasize-lines: 8-28
 
 Balsam Job Controller
 ---------------------
@@ -23,3 +25,5 @@ libEnsemble job controller to be launched by the job controller within the ``sim
 
 ..  literalinclude:: ../../libensemble/tests/regression_tests/script_test_balsam_hworld.py
     :language: python
+    :linenos:
+    :emphasize-lines: 27-31, 33-34, 42-43, 45-57, 59-65

From 0d232e7a031a8d1fdaaf936a38b8ab4310dcbf87 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 20 Nov 2019 10:46:01 -0600
Subject: [PATCH 584/644] revise intro, add third script

---
 docs/examples/calling_scripts.rst | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/docs/examples/calling_scripts.rst b/docs/examples/calling_scripts.rst
index bf6ab5ec3..bebfb382e 100644
--- a/docs/examples/calling_scripts.rst
+++ b/docs/examples/calling_scripts.rst
@@ -3,7 +3,9 @@ Calling Scripts
 
 Below are example calling scripts used to populate specifications for each user
 function and libEnsemble before initiating libEnsemble via the primary ``libE()``
-call.
+call. The primary libEnsemble-relevant portions have been highlighted in each
+example. Non-highlighted portions may include setup routines, compilation steps
+for user-applications, or output processing.
 
 Local Sine Tutorial
 -------------------
@@ -26,4 +28,17 @@ libEnsemble job controller to be launched by the job controller within the ``sim
 ..  literalinclude:: ../../libensemble/tests/regression_tests/script_test_balsam_hworld.py
     :language: python
     :linenos:
-    :emphasize-lines: 27-31, 33-34, 42-43, 45-57, 59-65
+    :emphasize-lines: 27-34, 42-65
+
+6-Hump-Camel Persistent APOSMM
+------------------------------
+
+This example is also from the regression tests, and demonstrates configuring a
+persistent run via a custom allocation function. Note the use of the
+``parse_args()`` and ``save_libE_output()`` convenience functions from the
+:doc:`utilities<../utilities>`.
+
+..  literalinclude:: ../../libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
+    :language: python
+    :linenos:
+    :emphasize-lines: 30, 38-69

From b8628c09609d099656be3732507f555285e86483 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 20 Nov 2019 10:48:44 -0600
Subject: [PATCH 585/644] emphasize save()

---
 docs/examples/calling_scripts.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/examples/calling_scripts.rst b/docs/examples/calling_scripts.rst
index bebfb382e..6b45d754d 100644
--- a/docs/examples/calling_scripts.rst
+++ b/docs/examples/calling_scripts.rst
@@ -41,4 +41,4 @@ persistent run via a custom allocation function. Note the use of the
 ..  literalinclude:: ../../libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
     :language: python
     :linenos:
-    :emphasize-lines: 30, 38-69
+    :emphasize-lines: 30, 38-69, 82

From 73e9b63690f5722ccc45728f0948643d470cb0ca Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 20 Nov 2019 11:14:21 -0600
Subject: [PATCH 586/644] adds more captions throughout

---
 docs/examples/calling_scripts.rst      | 3 +++
 docs/platforms/example_scripts.rst     | 4 ++++
 docs/tutorials/local_sine_tutorial.rst | 2 ++
 3 files changed, 9 insertions(+)

diff --git a/docs/examples/calling_scripts.rst b/docs/examples/calling_scripts.rst
index 6b45d754d..edd19c717 100644
--- a/docs/examples/calling_scripts.rst
+++ b/docs/examples/calling_scripts.rst
@@ -15,6 +15,7 @@ meant to run with Python's multiprocessing as the primary ``comms`` method.
 
 ..  literalinclude:: ../../examples/tutorials/tutorial_calling.py
     :language: python
+    :caption: examples/tutorials/tutorial_calling.py
     :linenos:
     :emphasize-lines: 8-28
 
@@ -27,6 +28,7 @@ libEnsemble job controller to be launched by the job controller within the ``sim
 
 ..  literalinclude:: ../../libensemble/tests/regression_tests/script_test_balsam_hworld.py
     :language: python
+    :caption: tests/regression_tests/script_test_balsam_hworld.py
     :linenos:
     :emphasize-lines: 27-34, 42-65
 
@@ -40,5 +42,6 @@ persistent run via a custom allocation function. Note the use of the
 
 ..  literalinclude:: ../../libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
     :language: python
+    :caption: tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
     :linenos:
     :emphasize-lines: 30, 38-69, 82
diff --git a/docs/platforms/example_scripts.rst b/docs/platforms/example_scripts.rst
index 3c9fe8d1b..c6b300bb6 100644
--- a/docs/platforms/example_scripts.rst
+++ b/docs/platforms/example_scripts.rst
@@ -9,22 +9,26 @@ Bebop - Central Mode
 --------------------
 
 ..  literalinclude:: ../../examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
+    :caption: /examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
     :language: bash
 
 Bebop - Distributed Mode
 ------------------------
 
 ..  literalinclude:: ../../examples/job_submission_scripts/bebop_submit_slurm.sh
+    :caption: /examples/job_submission_scripts/bebop_submit_slurm.sh
     :language: bash
 
 Blues
 -----
 
 ..  literalinclude:: ../../examples/job_submission_scripts/blues_script.pbs
+    :caption: /examples/job_submission_scripts/blues_script.pbs
     :language: bash
 
 Theta - Central Mode with Balsam
 --------------------------------
 
 ..  literalinclude:: ../../examples/job_submission_scripts/theta_submit_balsam.sh
+    :caption: /examples/job_submission_scripts/theta_submit_balsam.sh
     :language: bash
diff --git a/docs/tutorials/local_sine_tutorial.rst b/docs/tutorials/local_sine_tutorial.rst
index af92e7c15..30a8beed6 100644
--- a/docs/tutorials/local_sine_tutorial.rst
+++ b/docs/tutorials/local_sine_tutorial.rst
@@ -90,6 +90,7 @@ For now, create a new Python file named ``generator.py``. Write the following:
 
 .. code-block:: python
     :linenos:
+    :caption: examples/tutorials/tutorial_gen.py
 
     import numpy as np
 
@@ -133,6 +134,7 @@ Create a new Python file named ``simulator.py``. Write the following:
 
 .. code-block:: python
     :linenos:
+    :caption: examples/tutorials/tutorial_sim.py
 
     import numpy as np
 

From 18fc1aacc09c6ec780e5e51e5523d750c8418be8 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 20 Nov 2019 11:48:18 -0600
Subject: [PATCH 587/644] Add cori user guide

---
 docs/data_structures/calc_status.rst |   2 +-
 docs/platforms/bebop.rst             |  20 +++--
 docs/platforms/cori.rst              | 125 +++++++++++++++++++++++++++
 docs/platforms/platforms_index.rst   |   5 +-
 4 files changed, 143 insertions(+), 9 deletions(-)
 create mode 100644 docs/platforms/cori.rst

diff --git a/docs/data_structures/calc_status.rst b/docs/data_structures/calc_status.rst
index 76bec7fd2..330d2d726 100644
--- a/docs/data_structures/calc_status.rst
+++ b/docs/data_structures/calc_status.rst
@@ -51,7 +51,7 @@ Available values:
     :start-after: first_calc_status_rst_tag
     :end-before: last_calc_status_rst_tag
 
-The corresponding messages printed to the libE_stats.txt file are:
+The corresponding messages printed to the ``libE_stats.txt`` file are:
 
 ..  literalinclude:: ../../libensemble/message_numbers.py
     :start-at: calc_status_strings
diff --git a/docs/platforms/bebop.rst b/docs/platforms/bebop.rst
index 75e1fb583..15c0fca8d 100644
--- a/docs/platforms/bebop.rst
+++ b/docs/platforms/bebop.rst
@@ -50,18 +50,21 @@ You can allocate four Knights Landing nodes for thirty minutes through the follo
 
     salloc -N 4 -p knl -A [username OR project] -t 00:30:00
 
-With your nodes allocated, queue your job to start with five MPI ranks::
+With your nodes allocated, queue your job to start with four MPI ranks::
 
     srun -n 4 python calling.py
 
 ``mpirun`` should also work. This line launches libEnsemble with a manager and
 **three** workers to one allocated compute node, with three nodes available for
 the workers to launch calculations with the job-controller or a job-launch command.
+This is an example of running in :doc:`centralized<platforms_index.rst>` mode and,
+if using the :doc:`job_controller<../job_controller/mpi_controller.rst>`, it should
+be intiated with ``central_mode=True``
 
 .. note::
-    When performing an MPI libEnsemble run and not oversubscribing, specify one
-    more MPI process than the number of allocated nodes. The Manager and first
-    worker run together on a node.
+    When performing a :doc:`distributed<platforms_index.rst>` MPI libEnsemble run
+    and not oversubscribing, specify one more MPI process than the number of
+    allocated nodes. The Manager and first worker run together on a node.
 
 If you would like to interact directly with the compute nodes via a shell,
 the following showcases starting a bash session on a Knights Landing node
@@ -77,7 +80,8 @@ Batch Runs
 ^^^^^^^^^^
 
 Batch scripts specify run-settings using ``#SBATCH`` statements. A simple example
-for a libEnsemble use-case running on Broadwell nodes resembles the following:
+for a libEnsemble use-case running in :doc:`distributed<platforms_index.rst>` MPI
+mode on Broadwell nodes resembles the following:
 
 .. code-block:: bash
     :linenos:
@@ -97,13 +101,16 @@ for a libEnsemble use-case running on Broadwell nodes resembles the following:
     cat node_list >> machinefile.$SLURM_JOBID
     export SLURM_HOSTFILE=machinefile.$SLURM_JOBID
 
-    srun --ntasks 5 python3 calling_script.py
+    srun --ntasks 5 python calling_script.py
 
 With this saved as ``myscript.sh``, allocating, configuring, and running libEnsemble
 on Bebop becomes::
 
     sbatch myscript.sh
 
+Example submission scripts for running on Bebop in distributed and centralized mode
+are also given in the examples_ directory.
+
 Debugging Strategies
 --------------------
 
@@ -122,3 +129,4 @@ See the LCRC Bebop docs here_ for more information about Bebop.
 .. _Slurm: https://slurm.schedmd.com/
 .. _here: https://www.lcrc.anl.gov/for-users/using-lcrc/running-jobs/running-jobs-on-bebop/
 .. _options: https://slurm.schedmd.com/srun.html
+.. _examples: https://github.com/Libensemble/libensemble/tree/develop/examples/job_submission_scripts
diff --git a/docs/platforms/cori.rst b/docs/platforms/cori.rst
new file mode 100644
index 000000000..65f7eae71
--- /dev/null
+++ b/docs/platforms/cori.rst
@@ -0,0 +1,125 @@
+====
+Cori
+====
+
+Cori_ is a Cray XC40 located at NERSC, featuring both Intel Haswell
+and Knights Landing compute nodes. It uses the SLURM schedular to submit
+jobs from login nodes to run on the compute nodes.
+
+Configuring Python
+------------------
+
+Begin by loading the Python 3 Anaconda_ module::
+
+    module load python
+
+Create a Conda_ virtual environment in which to install libEnsemble and all
+dependencies::
+
+    conda config --add channels intel
+    conda create --name my_env intelpython3_core python=3
+    source activate my_env
+
+Installing libEnsemble and Dependencies
+---------------------------------------
+
+You should have an indication that the virtual environment is activated.
+Install mpi4py_ and libEnsemble in this environment, making sure to reference
+the Cray compiler wrappers. Your prompt should be similar to the
+following block:
+
+.. code-block:: console
+
+    (my_env) user@cori07:~$ CC=cc MPICC=cc pip install mpi4py --no-binary mpi4py
+    (my_env) user@cori07:~$ pip install libensemble
+
+Job Submission
+--------------
+
+Cori uses Slurm_ for job submission and management. The two commands you'll
+likely use the most to run jobs are ``srun`` and ``sbatch`` for running
+interactively and batch, respectively. libEnsemble runs on the compute nodes
+only Cori using either ``multi-processing`` or ``mpi4py``.
+
+Interactive Runs
+^^^^^^^^^^^^^^^^
+
+You can allocate four Knights Landing nodes for thirty minutes through the following::
+
+    salloc -N 4 -C knl -q interactive -t 00:30:00
+
+With your nodes allocated, queue your job to start with four MPI ranks::
+
+    srun -n 4 python calling.py
+
+This line launches libEnsemble with a manager and **three** workers to one
+allocated compute node, with three nodes available for the workers to launch
+user applications with the job-controller or a job-launch command.
+
+This is an example of running in :doc:`centralized<platforms_index.rst>` mode and,
+if using the :doc:`job_controller<../job_controller/mpi_controller.rst>`, it should
+be intiated with ``central_mode=True``
+
+.. note::
+    When performing a :doc:`distributed<platforms_index.rst>` MPI libEnsemble run,
+    specify one more MPI process than the number of allocated nodes.
+    The Manager and first worker run together on a node.
+
+.. note::
+    You will need to re-activate your conda virtual environment and reload your
+    modules! Configuring this routine to occur automatically is recommended.
+
+Batch Runs
+^^^^^^^^^^
+
+Batch scripts specify run-settings using ``#SBATCH`` statements. A simple example
+for a libEnsemble use-case running in :doc:`distributed<platforms_index.rst>` MPI
+mode on KNL nodes resembles the following:
+
+.. code-block:: bash
+    :linenos:
+
+    #!/bin/bash
+    #SBATCH -J myjob
+    #SBATCH -N 4
+    #SBATCH -q debug
+    #SBATCH -A myproject
+    #SBATCH -o myjob.out
+    #SBATCH -e myjob.error
+    #SBATCH -t 00:15:00
+    #SBATCH -C knl
+
+    # These four lines construct a machinefile for the job controller and slurm
+    srun hostname | sort -u > node_list
+    head -n 1 node_list > machinefile.$SLURM_JOBID
+    cat node_list >> machinefile.$SLURM_JOBID
+    export SLURM_HOSTFILE=machinefile.$SLURM_JOBID
+
+    srun --ntasks 5 python calling_script.py
+
+With this saved as ``myscript.sh``, allocating, configuring, and running libEnsemble
+on Cori becomes::
+
+    sbatch myscript.sh
+
+Example submission scripts are also given in the examples_ directory.
+
+Debugging Strategies
+--------------------
+
+View the status of your submitted jobs with ``squeue`` and cancel jobs with
+``scancel [Job ID]``.
+
+Additional Information
+----------------------
+
+See the LCRC Bebop docs here_ for more information about Cori.
+
+.. _Cori: https://docs.nersc.gov/systems/cori/
+.. _Anaconda: https://www.anaconda.com/distribution/
+.. _Conda: https://conda.io/en/latest/
+.. _mpi4py: https://mpi4py.readthedocs.io/en/stable/
+.. _Slurm: https://slurm.schedmd.com/
+.. _here: https://docs.nersc.gov/jobs/
+.. _options: https://slurm.schedmd.com/srun.html
+.. _examples: https://github.com/Libensemble/libensemble/tree/develop/examples/job_submission_scripts
diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst
index 8903175dd..6abb5b76b 100644
--- a/docs/platforms/platforms_index.rst
+++ b/docs/platforms/platforms_index.rst
@@ -8,7 +8,7 @@ within high-performance machines.
 
 libEnsemble's flexible architecture lends itself best to two general modes of worker
 distributions across allocated compute nodes. The first mode we refer
-to as *centralized* mode, where the libEnsemble manager and worker processes
+to as **centralized** mode, where the libEnsemble manager and worker processes
 are grouped on one or more nodes, but through the libEnsemble job-controller or a
 job-launch command can execute calculations on the other allocated nodes:
 
@@ -17,7 +17,7 @@ job-launch command can execute calculations on the other allocated nodes:
     :scale: 75
     :align: center
 
-Alternatively, in *distributed* mode, each worker process runs independently of
+Alternatively, in **distributed** mode, each worker process runs independently of
 other workers directly on one or more allocated nodes:
 
 .. image:: ../images/distributed_Bb.png
@@ -42,6 +42,7 @@ Read more about configuring and launching libEnsemble on some HPC systems:
     :titlesonly:
 
     bebop
+    cori
     theta
     summit
     example_scripts

From 93bba0a0fb6c062f7cf5e3789293aecdcaec8b25 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 20 Nov 2019 12:40:31 -0600
Subject: [PATCH 588/644] Better note

---
 examples/tutorials/tutorial_calling.py     | 2 +-
 examples/tutorials/tutorial_calling_mpi.py | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/tutorials/tutorial_calling.py b/examples/tutorials/tutorial_calling.py
index ac8620502..682fae7e9 100644
--- a/examples/tutorials/tutorial_calling.py
+++ b/examples/tutorials/tutorial_calling.py
@@ -20,7 +20,7 @@
              'in': ['x'],                       # Input field names. 'x' from gen_f output
              'out': [('y', float)]}             # sim_f output. 'y' = sine('x')
 
-persis_info = add_unique_random_streams({}, nworkers+1) # Worker numbers start at 1
+persis_info = add_unique_random_streams({}, nworkers+1)  # Intitialize manager/workers random streams
 
 exit_criteria = {'sim_max': 80}                 # Stop libEnsemble after 80 simulations
 
diff --git a/examples/tutorials/tutorial_calling_mpi.py b/examples/tutorials/tutorial_calling_mpi.py
index 4b71c4d50..423f4b59a 100644
--- a/examples/tutorials/tutorial_calling_mpi.py
+++ b/examples/tutorials/tutorial_calling_mpi.py
@@ -23,7 +23,7 @@
              'in': ['x'],                       # Input field names. 'x' from gen_f output
              'out': [('y', float)]}             # sim_f output. 'y' = sine('x')
 
-persis_info = add_unique_random_streams({}, nworkers+1) # Worker numbers start at 1
+persis_info = add_unique_random_streams({}, nworkers+1)  # Intitialize manager/workers random streams
 
 exit_criteria = {'sim_max': 80}                 # Stop libEnsemble after 80 simulations
 

From f3e0fc6cfdc760348f122d99f5a5a90e716565b9 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 20 Nov 2019 13:18:15 -0600
Subject: [PATCH 589/644] Fix typos in links

---
 docs/platforms/bebop.rst | 8 ++++----
 docs/platforms/cori.rst  | 8 ++++----
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/platforms/bebop.rst b/docs/platforms/bebop.rst
index 15c0fca8d..07eea0a14 100644
--- a/docs/platforms/bebop.rst
+++ b/docs/platforms/bebop.rst
@@ -57,12 +57,12 @@ With your nodes allocated, queue your job to start with four MPI ranks::
 ``mpirun`` should also work. This line launches libEnsemble with a manager and
 **three** workers to one allocated compute node, with three nodes available for
 the workers to launch calculations with the job-controller or a job-launch command.
-This is an example of running in :doc:`centralized<platforms_index.rst>` mode and,
-if using the :doc:`job_controller<../job_controller/mpi_controller.rst>`, it should
+This is an example of running in :doc:`centralized<platforms_index>` mode and,
+if using the :doc:`job_controller<../job_controller/mpi_controller>`, it should
 be intiated with ``central_mode=True``
 
 .. note::
-    When performing a :doc:`distributed<platforms_index.rst>` MPI libEnsemble run
+    When performing a :doc:`distributed<platforms_index>` MPI libEnsemble run
     and not oversubscribing, specify one more MPI process than the number of
     allocated nodes. The Manager and first worker run together on a node.
 
@@ -80,7 +80,7 @@ Batch Runs
 ^^^^^^^^^^
 
 Batch scripts specify run-settings using ``#SBATCH`` statements. A simple example
-for a libEnsemble use-case running in :doc:`distributed<platforms_index.rst>` MPI
+for a libEnsemble use-case running in :doc:`distributed<platforms_index>` MPI
 mode on Broadwell nodes resembles the following:
 
 .. code-block:: bash
diff --git a/docs/platforms/cori.rst b/docs/platforms/cori.rst
index 65f7eae71..3281e2c73 100644
--- a/docs/platforms/cori.rst
+++ b/docs/platforms/cori.rst
@@ -56,12 +56,12 @@ This line launches libEnsemble with a manager and **three** workers to one
 allocated compute node, with three nodes available for the workers to launch
 user applications with the job-controller or a job-launch command.
 
-This is an example of running in :doc:`centralized<platforms_index.rst>` mode and,
-if using the :doc:`job_controller<../job_controller/mpi_controller.rst>`, it should
+This is an example of running in :doc:`centralized<platforms_index>` mode and,
+if using the :doc:`job_controller<../job_controller/mpi_controller>`, it should
 be intiated with ``central_mode=True``
 
 .. note::
-    When performing a :doc:`distributed<platforms_index.rst>` MPI libEnsemble run,
+    When performing a :doc:`distributed<platforms_index>` MPI libEnsemble run,
     specify one more MPI process than the number of allocated nodes.
     The Manager and first worker run together on a node.
 
@@ -73,7 +73,7 @@ Batch Runs
 ^^^^^^^^^^
 
 Batch scripts specify run-settings using ``#SBATCH`` statements. A simple example
-for a libEnsemble use-case running in :doc:`distributed<platforms_index.rst>` MPI
+for a libEnsemble use-case running in :doc:`distributed<platforms_index>` MPI
 mode on KNL nodes resembles the following:
 
 .. code-block:: bash

From 5d8e6201046464b6948fc4fdf4b65435fed7353e Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 20 Nov 2019 13:34:45 -0600
Subject: [PATCH 590/644] Updated calc_status documentation to show manager use

---
 docs/data_structures/calc_status.rst |  4 +++-
 docs/sim_gen_alloc_funcs.rst         |  4 ++--
 libensemble/message_numbers.py       | 24 ++++++++++++++----------
 3 files changed, 19 insertions(+), 13 deletions(-)

diff --git a/docs/data_structures/calc_status.rst b/docs/data_structures/calc_status.rst
index 330d2d726..2091f1246 100644
--- a/docs/data_structures/calc_status.rst
+++ b/docs/data_structures/calc_status.rst
@@ -3,7 +3,7 @@
 calc_status
 ===========
 
-The ``calc_status`` is an integer attribute with a corresponding description that can be used in :ref:`sim_f<api_sim_f>` or :ref:`gen_f<api_gen_f>` functions to capture the status of a calcuation. This is returned to the manager and printed to the ``libE_stats.txt`` file. This is not currently used by the manager, but can still provide a useful summary in libE_stats.txt. The user determines the status of the calculation, as it could include multiple application runs. It can be added as a third return variable in sim_f or gen_f functions.
+The ``calc_status`` is an integer attribute with named (enumerated) values and a corresponding description that can be used in :ref:`sim_f<api_sim_f>` or :ref:`gen_f<api_gen_f>` functions to capture the status of a calcuation. This is returned to the manager and printed to the ``libE_stats.txt`` file. Only the status values ``FINISHED_PERSISTENT_SIM_TAG`` and ``FINISHED_PERSISTENT_GEN_TAG`` are currently used by the manager,  but others can still provide a useful summary in libE_stats.txt. The user determines the status of the calculation, as it could include multiple application runs. It can be added as a third return variable in sim_f or gen_f functions.
 The calc_status codes are in the ``libensemble.message_numbers`` module.
 
 Example of ``calc_status`` used along with :ref:`job controller<jobcontroller_index>` in sim_f:
@@ -44,6 +44,7 @@ Example of ``calc_status`` used along with :ref:`job controller<jobcontroller_in
     return output, persis_info, calc_status
 
 See forces_simf.py_ for a complete example.
+See uniform_or_localopt.py_ for an example of using *FINISHED_PERSISTENT_GEN_TAG*
 
 Available values:
 
@@ -72,3 +73,4 @@ Example segment of libE_stats.txt:
     Worker     2: Calc     3: sim Time: 4.41 Start: 2019-11-19 18:53:56 End: 2019-11-19 18:54:00 Status: Completed
 
 .. _forces_simf.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/scaling_tests/forces/forces_simf.py
+.. _uniform_or_localopt.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/gen_funcs/uniform_or_localopt.py
diff --git a/docs/sim_gen_alloc_funcs.rst b/docs/sim_gen_alloc_funcs.rst
index 7a87ab3e4..77a253a2c 100644
--- a/docs/sim_gen_alloc_funcs.rst
+++ b/docs/sim_gen_alloc_funcs.rst
@@ -72,7 +72,7 @@ Returns:
   :doc:`(example)<data_structures/persis_info>`
 
   **calc_status**: :obj:`int`, optional.
-  Provides a job status to the Manager. Currently only used to output to libE_stats.txt file.
+  Provides a job status to the Manager and the libE_stats.txt file.
   :doc:`(example)<data_structures/calc_status>`
 
 
@@ -110,7 +110,7 @@ Returns:
   :doc:`(example)<data_structures/persis_info>`
 
   **calc_status**: :obj:`int`, optional.
-  Provides a job status to the Manager. Currently only used to output to libE_stats.txt file.
+  Provides a job status to the Manager and the libE_stats.txt file.
   :doc:`(example)<data_structures/calc_status>`
 
 
diff --git a/libensemble/message_numbers.py b/libensemble/message_numbers.py
index 80c87cf0d..27e498713 100644
--- a/libensemble/message_numbers.py
+++ b/libensemble/message_numbers.py
@@ -5,8 +5,7 @@
 EVAL_GEN_TAG = 2
 STOP_TAG = 3
 PERSIS_STOP = 4                     # manager tells persistent worker to desist
-FINISHED_PERSISTENT_SIM_TAG = 11    # tells manager sim_f done persistent mode
-FINISHED_PERSISTENT_GEN_TAG = 12    # tells manager gen_f done persistent mode
+
 # last_message_number_rst_tag
 
 calc_type_strings = {
@@ -17,19 +16,24 @@
 
 
 # --- Signal flags (in message body vs tags)
+
 # first_calc_status_rst_tag
 # CALC STATUS/SIGNAL FLAGS
-MAN_SIGNAL_FINISH = 20  # Kill jobs and shutdown worker
-MAN_SIGNAL_KILL = 21    # Kill running job - but don't stop worker
-WORKER_KILL = 30        # Worker kills not covered by a more specific case
-WORKER_KILL_ON_ERR = 31
-WORKER_KILL_ON_TIMEOUT = 32
-JOB_FAILED = 33  # Calc had jobs that failed
-WORKER_DONE = 34  # Calculation was successful
-CALC_EXCEPTION = 35  # Reserved: Automatically used if gen_f or sim_f raised an exception.
+FINISHED_PERSISTENT_SIM_TAG = 11  # tells manager sim_f done persistent mode
+FINISHED_PERSISTENT_GEN_TAG = 12  # tells manager gen_f done persistent mode
+MAN_SIGNAL_FINISH = 20            # Kill jobs and shutdown worker
+MAN_SIGNAL_KILL = 21              # Kill running job - but don't stop worker
+WORKER_KILL = 30                  # Worker kills not covered by a more specific case
+WORKER_KILL_ON_ERR = 31           # Worker killed due to an error in results
+WORKER_KILL_ON_TIMEOUT = 32       # Worker killed on timeout
+JOB_FAILED = 33                   # Calc had jobs that failed
+WORKER_DONE = 34                  # Calculation was successful
 # last_calc_status_rst_tag
+CALC_EXCEPTION = 35               # Reserved: Automatically used if gen_f or sim_f raised an exception.
 
 calc_status_strings = {
+    FINISHED_PERSISTENT_SIM_TAG: "Persis gen finished",
+    FINISHED_PERSISTENT_GEN_TAG: "Persis sim finished",
     MAN_SIGNAL_FINISH: "Manager killed on finish",
     MAN_SIGNAL_KILL: "Manager killed job",
     WORKER_KILL_ON_ERR: " Worker killed job on Error",

From ec6358db56e07bcce2c6fbeae45b372b98426cad Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 20 Nov 2019 14:03:13 -0600
Subject: [PATCH 591/644] Minor fix to Cori guide

---
 docs/platforms/cori.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/platforms/cori.rst b/docs/platforms/cori.rst
index 3281e2c73..f666f515b 100644
--- a/docs/platforms/cori.rst
+++ b/docs/platforms/cori.rst
@@ -113,7 +113,7 @@ View the status of your submitted jobs with ``squeue`` and cancel jobs with
 Additional Information
 ----------------------
 
-See the LCRC Bebop docs here_ for more information about Cori.
+See the NERSC Cori docs here_ for more information about Cori.
 
 .. _Cori: https://docs.nersc.gov/systems/cori/
 .. _Anaconda: https://www.anaconda.com/distribution/

From 99b68fbe1ebbf3908d84bfb80392ffe29cd2ce6c Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 20 Nov 2019 14:36:29 -0600
Subject: [PATCH 592/644] updates job controller example to use forces, removes
 support usage in 6HC paposmm 1

---
 docs/examples/calling_scripts.rst             | 27 ++++++++++---------
 .../test_6-hump_camel_persistent_aposmm_1.py  |  9 ++++---
 2 files changed, 20 insertions(+), 16 deletions(-)

diff --git a/docs/examples/calling_scripts.rst b/docs/examples/calling_scripts.rst
index edd19c717..c608047fe 100644
--- a/docs/examples/calling_scripts.rst
+++ b/docs/examples/calling_scripts.rst
@@ -5,7 +5,8 @@ Below are example calling scripts used to populate specifications for each user
 function and libEnsemble before initiating libEnsemble via the primary ``libE()``
 call. The primary libEnsemble-relevant portions have been highlighted in each
 example. Non-highlighted portions may include setup routines, compilation steps
-for user-applications, or output processing.
+for user-applications, or output processing. The first two scripts correspond to
+random sampling calculations, while the third corresponds to an optimization routine.
 
 Local Sine Tutorial
 -------------------
@@ -19,29 +20,29 @@ meant to run with Python's multiprocessing as the primary ``comms`` method.
     :linenos:
     :emphasize-lines: 8-28
 
-Balsam Job Controller
----------------------
+Electrostatic Forces with Job Controller
+----------------------------------------
 
-This example is from the regression tests. It configures MPI as the primary
-communication method, and demonstrates registering a user-application with the
-libEnsemble job controller to be launched by the job controller within the ``sim_f``.
+This example is from a test for evaluating the scaling capabilities of libEnsemble
+by calculating particle electrostatic forces through a user-application. This
+application is registered with either the MPI or Balsam job controller, then
+launched in the ``sim_f``. Note the use of the ``parse_args()`` and
+``save_libE_output()`` convenience functions from the :doc:`utilities<../utilities>`.
 
-..  literalinclude:: ../../libensemble/tests/regression_tests/script_test_balsam_hworld.py
+..  literalinclude:: ../../libensemble/tests/scaling_tests/forces/run_libe_forces.py
     :language: python
-    :caption: tests/regression_tests/script_test_balsam_hworld.py
+    :caption: tests/scaling_tests/forces/run_libe_forces.py
     :linenos:
-    :emphasize-lines: 27-34, 42-65
+    :emphasize-lines: 16, 39-92
 
 6-Hump-Camel Persistent APOSMM
 ------------------------------
 
 This example is also from the regression tests, and demonstrates configuring a
-persistent run via a custom allocation function. Note the use of the
-``parse_args()`` and ``save_libE_output()`` convenience functions from the
-:doc:`utilities<../utilities>`.
+persistent run via a custom allocation function.
 
 ..  literalinclude:: ../../libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
     :language: python
     :caption: tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
     :linenos:
-    :emphasize-lines: 30, 38-69, 82
+    :emphasize-lines: 29, 42-72, 85
diff --git a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
index 2ac709b55..1323c3d04 100644
--- a/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
+++ b/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
@@ -24,7 +24,6 @@
 from libensemble.gen_funcs.persistent_aposmm import aposmm as gen_f
 from libensemble.alloc_funcs.persistent_aposmm_alloc import persistent_aposmm_alloc as alloc_f
 from libensemble.utils import parse_args, save_libE_output, add_unique_random_streams
-from libensemble.tests.regression_tests.support import six_hump_camel_minima as minima
 from time import time
 
 nworkers, is_master, libE_specs, _ = parse_args()
@@ -35,6 +34,10 @@
 if nworkers < 2:
     sys.exit("Cannot run with a persistent worker if only one worker -- aborting...")
 
+six_hump_camel_minima = np.array([[-0.089842, 0.712656], [0.089842, -0.712656],
+                                  [-1.70361, 0.796084], [1.70361, -0.796084],
+                                  [-1.6071, -0.568651], [1.6071, 0.568651]])
+
 n = 2
 sim_specs = {'sim_f': sim_f,
              'in': ['x'],
@@ -47,7 +50,7 @@
              'in': [],
              'out': gen_out,
              'user': {'initial_sample_size': 100,
-                      'sample_points': np.round(minima, 1),
+                      'sample_points': np.round(six_hump_camel_minima, 1),
                       'localopt_method': 'LD_MMA',
                       'rk_const': 0.5*((gamma(1+(n/2))*5)**(1/n))/sqrt(pi),
                       'xtol_rel': 1e-6,
@@ -73,7 +76,7 @@
     print('[Manager]: Time taken =', time() - start_time, flush=True)
 
     tol = 1e-5
-    for m in minima:
+    for m in six_hump_camel_minima:
         # The minima are known on this test problem.
         # We use their values to test APOSMM has identified all minima
         print(np.min(np.sum((H[H['local_min']]['x'] - m)**2, 1)), flush=True)

From cb8379936025b32c6868ae82cca95654c186ba7c Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 20 Nov 2019 16:22:49 -0600
Subject: [PATCH 593/644] formatting changes, remove XC40 note and common.py
 reference, add utilities reference and xSDK info

---
 README.rst | 50 +++++++++++++++++++++++++++++---------------------
 1 file changed, 29 insertions(+), 21 deletions(-)

diff --git a/README.rst b/README.rst
index 9d16ae55d..a0248f2ba 100644
--- a/README.rst
+++ b/README.rst
@@ -42,8 +42,8 @@ libEnsemble aims for:
 The user selects or supplies a function that generates simulation
 input as well as a function that performs and monitors the
 simulations. For example, the generation function may contain an
-optimization routine to generate new simulation parameters on-the-fly based on the
-results of previous simulations. Examples and templates of such functions are
+optimization routine to generate new simulation parameters on-the-fly based on
+the results of previous simulations. Examples and templates of such functions are
 included in the library.
 
 libEnsemble employs a manager-worker scheme that can run on various
@@ -74,13 +74,12 @@ Optional dependency:
 
 * Balsam_
 
-From v0.2.0, libEnsemble has the option of using the Balsam job manager. This
-is required for running libEnsemble on the compute nodes of some supercomputing
-platforms (e.g., Cray XC40); platforms that do not support launching jobs from
-compute nodes. Note that as of v0.5.0, libEnsemble can also be run on the
-launch nodes using multiprocessing.
+From v0.2.0, libEnsemble has the option of using the Balsam job manager. Balsam
+is required to run libEnsemble on the compute nodes of some supercomputing
+platforms that do not support launching jobs from compute nodes. As of v0.5.0,
+libEnsemble can also be run on launch nodes using multiprocessing.
 
-The example sim and gen functions and tests require the following dependencies:
+The example simulation and generation functions and tests require the following:
 
 * SciPy_
 * petsc4py_
@@ -89,22 +88,32 @@ The example sim and gen functions and tests require the following dependencies:
 
 PETSc and NLopt must be built with shared libraries enabled and present in
 ``sys.path`` (e.g., via setting the ``PYTHONPATH`` environment variable). NLopt
-should produce a file ``nlopt.py`` if Python is found on the system. NLopt may also
-require SWIG_ to be installed on certain systems.
+should produce a file ``nlopt.py`` if Python is found on the system. NLopt may
+also require SWIG_ to be installed on certain systems.
 
 Installation
 ~~~~~~~~~~~~
 
+libEnsemble may be installed or accessed from a variety of sources.
+
 Use pip to install libEnsemble and its dependencies::
 
     pip install libensemble
 
-libEnsemble is also available in the Spack_ distribution. It can be installed from Spack with::
+libEnsemble is also available in the Spack_ distribution. It can be installed
+from Spack with::
 
     spack install py-libensemble
 
-The tests and examples can be accessed in the GitHub_ repository.
-If necessary, you may install all optional dependencies (listed above) at once with::
+libEnsemble is included in the `xSDK Extreme-scale Scientific Software Development Kit`_
+from version 0.5.0 onward. Install the xSDK and load the environment with::
+
+    spack install xsdk
+    spack load -r xsdk
+
+The codebase, tests and examples can be accessed in the GitHub_ repository.
+If necessary, you may install all optional dependencies (listed above) at once
+with::
 
     pip install libensemble[extras]
 
@@ -119,8 +128,8 @@ regularly on:
 * `Travis CI`_
 
 The test suite requires the mock_, pytest_, pytest-cov_, and pytest-timeout_
-packages to be installed and can be run from the libensemble/tests directory of
-the source distribution by running::
+packages to be installed and can be run from the ``libensemble/tests`` directory
+of the source distribution by running::
 
     ./run-tests.sh
 
@@ -154,8 +163,8 @@ available online at Coveralls_.
 Basic Usage
 ~~~~~~~~~~~
 
-The examples directory contains example libEnsemble calling scripts, sim
-functions, gen functions, alloc functions and job submission scripts.
+The examples directory contains example libEnsemble calling scripts, simulation
+functions, generation functions, allocation functions and job submission scripts.
 
 The default manager/worker communications mode is MPI. The user script is
 launched as::
@@ -171,9 +180,8 @@ can then be run as a regular python script::
 
     python myscript.py
 
-When specifying these options via command line options, one may use the
-``parse_args`` function used in the regression tests, which can be found in
-`common.py`_ in the ``libensemble/tests/regression_tests`` directory.
+These options may be specified via the command-line using the ``parse_args()``
+convenience function within ``libensemble/utils.py``.
 
 See the `user guide`_ for more information.
 
@@ -210,7 +218,6 @@ Resources
 .. after_resources_rst_tag
 
 .. _Balsam: https://www.alcf.anl.gov/balsam
-.. _common.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/common.py
 .. _Coveralls: https://coveralls.io/github/Libensemble/libensemble?branch=master
 .. _GitHub: https://github.com/Libensemble/libensemble
 .. _libEnsemble mailing list: https://lists.mcs.anl.gov/mailman/listinfo/libensemble
@@ -235,3 +242,4 @@ Resources
 .. _tarball: https://github.com/Libensemble/libensemble/releases/latest
 .. _Travis CI: https://travis-ci.org/Libensemble/libensemble
 .. _user guide: https://libensemble.readthedocs.io/en/latest/user_guide.html
+.. _xSDK Extreme-scale Scientific Software Development Kit: https://xsdk.info/

From 4cfd4128bf78c802e92ec0029632be52c4fd7466 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 20 Nov 2019 16:50:01 -0600
Subject: [PATCH 594/644] update libE_specs example

---
 docs/data_structures/libE_specs.rst | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/docs/data_structures/libE_specs.rst b/docs/data_structures/libE_specs.rst
index f68ce1c4f..35dcdbacc 100644
--- a/docs/data_structures/libE_specs.rst
+++ b/docs/data_structures/libE_specs.rst
@@ -32,6 +32,12 @@ Specifications for libEnsemble::
             Profile using cProfile. Default: False
 
 .. seealso::
-  Examples in `common.py`_
+  Example ``libE_specs`` from the forces_ scaling test, completely populated::
 
-.. _common.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/common.py
+      libE_specs = {'comm': MPI.COMM_WORLD,
+                    'comms': 'mpi',
+                    'save_every_k_gens': 1000,
+                    'sim_dir': './sim',
+                    'profile_worker': False}
+
+.. _forces: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/scaling_tests/forces/run_libe_forces.py

From f9034e01d27ef24e8dc20be66970e6f43c26f5ca Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 20 Nov 2019 17:00:17 -0600
Subject: [PATCH 595/644] update check inputs reference

---
 docs/data_structures/history_array.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/data_structures/history_array.rst b/docs/data_structures/history_array.rst
index 371362968..48b0a5c9f 100644
--- a/docs/data_structures/history_array.rst
+++ b/docs/data_structures/history_array.rst
@@ -26,6 +26,6 @@ Below are the protected fields used in ``H``
   ``check_inputs()`` and calling it with their ``gen_specs``, ``alloc_specs``,
   and ``sim_specs`` as keyword arguments::
 
-      from libensemble.libE import check_inputs
+      from libensemble.utils import check_inputs
 
       check_inputs(H0=my_H, sim_specs=sim_specs, alloc_specs=alloc_specs, gen_specs=gen_specs)

From ea072da1a6438dd32575e6796aba893d4c8aae66 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 20 Nov 2019 17:03:13 -0600
Subject: [PATCH 596/644] formatting

---
 docs/logging.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/logging.rst b/docs/logging.rst
index 6301600e8..7296cfd4f 100644
--- a/docs/logging.rst
+++ b/docs/logging.rst
@@ -6,7 +6,7 @@ plus one additional custom level (MANAGER_WARNING) between WARNING and ERROR.
 
 The default level is INFO, which includes information about how jobs are launched
 and when jobs are killed. To gain additional diagnostics, the logging level can be set
-to DEBUG. libEnsemble produces logging to the file ensemble.log by default. A log
+to DEBUG. libEnsemble produces logging to the file ``ensemble.log`` by default. A log
 file name can also be supplied.
 
 To change the logging level to DEBUG, provide the following in your the calling scripts::

From 04c1205068c07b6d6652e11ad8a8f7fb972b7c86 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 20 Nov 2019 22:59:11 -0600
Subject: [PATCH 597/644] Add theta multiprocessing MOM node example and make
 mods

---
 .../theta_submit_balsam.sh                    | 60 ++++++++++---------
 .../theta_submit_mproc.sh                     | 47 +++++++++++++++
 .../forces/theta_submit_balsam.sh             | 20 +++----
 .../forces/theta_submit_mproc.sh              |  8 +--
 4 files changed, 93 insertions(+), 42 deletions(-)
 create mode 100755 examples/job_submission_scripts/theta_submit_mproc.sh

diff --git a/examples/job_submission_scripts/theta_submit_balsam.sh b/examples/job_submission_scripts/theta_submit_balsam.sh
index a06c7a2ae..2751be89b 100644
--- a/examples/job_submission_scripts/theta_submit_balsam.sh
+++ b/examples/job_submission_scripts/theta_submit_balsam.sh
@@ -1,9 +1,9 @@
 #!/bin/bash -x
-#COBALT -t 60
-#COBALT -O libE_test
-#COBALT -n 5 #no. nodes
-#COBALT -q debug-flat-quad #For small runs only
-##COBALT -q default #For large jobs
+#COBALT -t 30
+#COBALT -O libE_MPI_balsam
+#COBALT -n 5 # No. nodes
+#COBALT -q debug-flat-quad # Up to 8 nodes only
+##COBALT -q default # For large jobs >=128 nodes
 ##COBALT -A <...project code...>
 
 # Script to launch libEnsemble using Balsam within Conda. Conda environment must be set up.
@@ -11,7 +11,7 @@
 # Requires Balsam is installed and a database initialized (this can be the default database).
 
 # To be run with central job management
-# - Manager and workers run on one node (or more if nec).
+# - Manager and workers run on one node (or a dedicated set of nodes).
 # - Workers submit jobs to the rest of the nodes in the pool.
 
 # Constaint: - As set up - only uses one node (up to 63 workers) for libE. To use more, modifiy "balsam job" line to use hyper-threading and/or more than one node.
@@ -20,43 +20,47 @@
 export EXE=libE_calling_script.py
 
 # Number of workers.
-export NUM_WORKERS=16
+export NUM_WORKERS=4
 
-# Wallclock for libE job (supplied to Balsam - make at least several mins smaller than wallclock for this submission to ensure job is launched)
-export LIBE_WALLCLOCK=45
+# Wallclock for libE job in minutes (supplied to Balsam - make at least several mins smaller than wallclock for this submission to ensure job is launched)
+export BALSAM_WALLCLOCK=25
 
 # Name of working directory where Balsam places running jobs/output (inside the database directory)
-export WORKFLOW_NAME=libe_workflow #sh - todo - may currently be hardcoded to this in libE - allow user to specify
+export WORKFLOW_NAME=libe_workflow
 
-#Tell libE manager to stop workers, dump timing.dat and exit after this time. Script must be set up to receive as argument.
-export SCRIPT_ARGS=$(($LIBE_WALLCLOCK-3))
-# export SCRIPT_ARGS='' #Default No args
+#Tell libE manager to stop workers, and exit after this time. Script must be set up to receive as argument.
+export LIBE_WALLCLOCK=$(($BALSAM_WALLCLOCK-3))
 
-# Name of Conda environment (Need to have set up: https://balsam.alcf.anl.gov/quick/quickstart.html)
-export CONDA_ENV_NAME=balsam
+# libEnsemble calling script arguments
+# export SCRIPT_ARGS='' # No args
+# export SCRIPT_ARGS='$LIBE_WALLCLOCK' # If calling script takes wall-clock as positional arg.
+
+# If script is using util.parse_args() and takes wall-clock as positional arg.
+export SCRIPT_ARGS="--comms mpi --nworkers $NUM_WORKERS $LIBE_WALLCLOCK"
+
+# Name of Conda environment (Need to have set up: https://balsam.readthedocs.io/en/latest/userguide/getting-started.html)
+export CONDA_ENV_NAME=<conda_env_name>
+
+# Name of database
+export DBASE_NAME=<dbase_name>  # default - to use default database.
 
 # Conda location - theta specific
-export PATH=/opt/intel/python/2017.0.035/intelpython35/bin:$PATH
-export LD_LIBRARY_PATH=~/.conda/envs/balsam/lib:$LD_LIBRARY_PATH
+# export PATH=/opt/intel/python/2017.0.035/intelpython35/bin:$PATH
+# export LD_LIBRARY_PATH=~/.conda/envs/$CONDA_ENV_NAME/lib:$LD_LIBRARY_PATH
 
-export PYTHONNOUSERSITE=1 #Ensure environment isolated
+export PYTHONNOUSERSITE=1 # Ensure environment isolated
 
 export PMI_NO_FORK=1 # Required for python kills on Theta
 
 # Activate conda environment
 . activate $CONDA_ENV_NAME
 
-# Unload Theta modules that may interfere with Balsam
+# Unload Theta modules that may interfere with job monitoring/kills
 module unload trackdeps
 module unload darshan
 module unload xalt
 
-#Location of sim func script (only required if not in sys.path already)
-# export PYTHONPATH=/home/shudson/opal_work/opal/emittance_minimization/code:$PYTHONPATH
-
-. balsamactivate default
-# . balsamactivate my_dbase
-
+. balsamactivate $DBASE_NAME
 
 # Currently need atleast one DB connection per worker (for postgres).
 if [[ $NUM_WORKERS -gt 128 ]]
@@ -79,15 +83,15 @@ SCRIPT_BASENAME=${EXE%.*}
 balsam app --name $SCRIPT_BASENAME.app --exec $EXE --desc "Run $SCRIPT_BASENAME"
 
 # Running libE on one node - one manager and upto 63 workers
-balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --args $SCRIPT_ARGS --wall-time-minutes $LIBE_WALLCLOCK --num-nodes 1 --ranks-per-node $((NUM_WORKERS+1)) --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
+balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --args $SCRIPT_ARGS --wall-time-minutes $BALSAM_WALLCLOCK --num-nodes 1 --ranks-per-node $((NUM_WORKERS+1)) --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
 
 # Hyper-thread libE (note this will not affect HT status of user calcs - only libE itself)
 # Running 255 workers and one manager on one libE node.
-# balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --args $SCRIPT_ARGS --wall-time-minutes $LIBE_WALLCLOCK  --num-nodes 1 --ranks-per-node 256 --threads-per-core 4 --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
+# balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --args $SCRIPT_ARGS --wall-time-minutes $BALSAM_WALLCLOCK  --num-nodes 1 --ranks-per-node 256 --threads-per-core 4 --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
 
 # Multiple nodes for libE
 # Running 127 workers and one manager - launch script on 129 nodes (if one node per worker)
-# balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --args $SCRIPT_ARGS --wall-time-minutes $LIBE_WALLCLOCK  --num-nodes 2 --ranks-per-node 64 --url-out="local:/$THIS_DIR"  --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
+# balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --args $SCRIPT_ARGS --wall-time-minutes $BALSAM_WALLCLOCK  --num-nodes 2 --ranks-per-node 64 --url-out="local:/$THIS_DIR"  --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
 
 #Run job
 balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1
diff --git a/examples/job_submission_scripts/theta_submit_mproc.sh b/examples/job_submission_scripts/theta_submit_mproc.sh
new file mode 100755
index 000000000..74718bfc3
--- /dev/null
+++ b/examples/job_submission_scripts/theta_submit_mproc.sh
@@ -0,0 +1,47 @@
+#!/bin/bash -x
+#COBALT -t 00:30:00
+#COBALT -n 4
+#COBALT -q debug-flat-quad # Up to 8 nodes only
+##COBALT -q default # For large jobs >=128 nodes
+##COBALT -A <...project code...>
+
+# Script to run libEnsemble using multiprocessing on launch nodes.
+# Assumes Conda environment is set up.
+
+# To be run with central job management
+# - Manager and workers run on launch node.
+# - Workers submit jobs to the compute nodes in the node allocation available.
+
+# Name of calling script
+export EXE=run_libe_forces.py
+
+# Communication Method
+export COMMS="--comms local"
+
+# Number of workers.
+export NWORKERS="--nworkers 4"
+
+# Wallclock for libE (allow clean shutdown)
+#export LIBE_WALLCLOCK=25 # Optional if pass to script
+
+# Name of Conda environment
+export CONDA_ENV_NAME=<conda_env_name>
+
+# Conda location - theta specific
+export PATH=/opt/intel/python/2017.0.035/intelpython35/bin:$PATH
+export LD_LIBRARY_PATH=~/.conda/envs/balsam/lib:$LD_LIBRARY_PATH
+export PMI_NO_FORK=1 # Required for python kills on Theta
+
+# Unload Theta modules that may interfere with job monitoring/kills
+module unload trackdeps
+module unload darshan
+module unload xalt
+
+# Activate conda environment
+export PYTHONNOUSERSITE=1
+. activate $CONDA_ENV_NAME
+
+# Launch libE
+#python $EXE $NUM_WORKERS > out.txt 2>&1 # No args
+#python $EXE $NUM_WORKERS $LIBE_WALLCLOCK > out.txt 2>&1  # If user script takes wall-clock as positional arg.
+python $EXE $COMMS $NWORKERS > out.txt 2>&1  # If script is using util.parse_args()
diff --git a/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh b/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh
index 3f071a9dc..e8d2f8306 100755
--- a/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh
+++ b/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh
@@ -18,24 +18,25 @@ export EXE=run_libe_forces.py
 # Number of workers.
 export NUM_WORKERS=127
 
-# Wallclock for libE job (supplied to Balsam - make at least several mins smaller than wallclock for this submission to ensure job is launched)
+# Wallclock for libE job in minutes (supplied to Balsam - make at least several mins smaller than wallclock for this submission to ensure job is launched)
 export LIBE_WALLCLOCK=25
 
 # Name of working directory where Balsam places running jobs/output (inside the database directory)
-export WORKFLOW_NAME=libe_workflow #sh - todo - may currently be hardcoded to this in libE - allow user to specify
+export WORKFLOW_NAME=libe_workflow
 
-#Tell libE manager to stop workers, dump timing.dat and exit after this time. Script must be set up to receive as argument.
-export SCRIPT_ARGS="--comms mpi --nworkers $NUM_WORKERS"
-# export SCRIPT_ARGS=$(($LIBE_WALLCLOCK-5))
 # export SCRIPT_ARGS='' #Default No args
+# export SCRIPT_ARGS=$(($LIBE_WALLCLOCK-5))
+export SCRIPT_ARGS="--comms mpi --nworkers $NUM_WORKERS"
 
-# Name of Conda environment (Need to have set up: https://balsam.alcf.anl.gov/quick/quickstart.html)
+# Name of Conda environment
 export CONDA_ENV_NAME=<conda_env_name>
+
+# Name of database
 export DBASE_NAME=<dbase_name>
 
 # Conda location - theta specific
-export PATH=/opt/intel/python/2017.0.035/intelpython35/bin:$PATH
-export LD_LIBRARY_PATH=~/.conda/envs/balsam/lib:$LD_LIBRARY_PATH
+# export PATH=/opt/intel/python/2017.0.035/intelpython35/bin:$PATH
+# export LD_LIBRARY_PATH=~/.conda/envs/$CONDA_ENV_NAME/lib:$LD_LIBRARY_PATH
 
 export PYTHONNOUSERSITE=1 #Ensure environment isolated
 
@@ -48,12 +49,11 @@ export PLOT_DIR=..
 # Activate conda environment
 . activate $CONDA_ENV_NAME
 
-# Unload Theta modules that may interfere with Balsam
+# Unload Theta modules that may interfere with job monitoring/kills
 module unload trackdeps
 module unload darshan
 module unload xalt
 
-
 . balsamactivate $DBASE_NAME
 
 # Make sure no existing apps/jobs
diff --git a/libensemble/tests/scaling_tests/forces/theta_submit_mproc.sh b/libensemble/tests/scaling_tests/forces/theta_submit_mproc.sh
index d46dc6a5d..c39b8f9e3 100755
--- a/libensemble/tests/scaling_tests/forces/theta_submit_mproc.sh
+++ b/libensemble/tests/scaling_tests/forces/theta_submit_mproc.sh
@@ -18,7 +18,7 @@ export EXE=run_libe_forces.py
 export COMMS="--comms local"
 
 # Number of workers.
-export NWORKERS="--nworkers 4"
+export NWORKERS="--nworkers 128"
 
 # Wallclock for libE (allow clean shutdown)
 #export LIBE_WALLCLOCK=25 # Optional if pass to script
@@ -27,14 +27,14 @@ export NWORKERS="--nworkers 4"
 export CONDA_ENV_NAME=<conda_env_name>
 
 # Conda location - theta specific
-export PATH=/opt/intel/python/2017.0.035/intelpython35/bin:$PATH
-export LD_LIBRARY_PATH=~/.conda/envs/balsam/lib:$LD_LIBRARY_PATH
+# export PATH=/opt/intel/python/2017.0.035/intelpython35/bin:$PATH
+# export LD_LIBRARY_PATH=~/.conda/envs/<conda_env_name>/lib:$LD_LIBRARY_PATH
 export PMI_NO_FORK=1 # Required for python kills on Theta
 
 export LIBE_PLOTS=true # Require plot scripts in $PLOT_DIR (see at end)
 export PLOT_DIR=..
 
-# Unload Theta modules that may interfere
+# Unload Theta modules that may interfere with job monitoring/kills
 module unload trackdeps
 module unload darshan
 module unload xalt

From e81ce567c38b826b2250576f31b53f9271a1bcd0 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 20 Nov 2019 23:08:24 -0600
Subject: [PATCH 598/644] Add summit submission script to examples and fix typo

---
 .../summit_submit_mproc.sh                    | 43 +++++++++++++++++++
 .../theta_submit_balsam.sh                    |  4 +-
 .../theta_submit_mproc.sh                     |  5 ++-
 3 files changed, 48 insertions(+), 4 deletions(-)
 create mode 100644 examples/job_submission_scripts/summit_submit_mproc.sh

diff --git a/examples/job_submission_scripts/summit_submit_mproc.sh b/examples/job_submission_scripts/summit_submit_mproc.sh
new file mode 100644
index 000000000..8872e1811
--- /dev/null
+++ b/examples/job_submission_scripts/summit_submit_mproc.sh
@@ -0,0 +1,43 @@
+#!/bin/bash -x
+#BSUB -P <project code>
+#BSUB -J libe_mproc
+#BSUB -W 30
+#BSUB -nnodes 4
+#BSUB -alloc_flags "smt1"
+
+# Script to run libEnsemble using multiprocessing on launch nodes.
+# Assumes Conda environment is set up.
+
+# To be run with central job management
+# - Manager and workers run on launch node.
+# - Workers submit jobs to the nodes in the job available.
+
+# Name of calling script-
+export EXE=run_libe_forces.py
+
+# Communication Method
+export COMMS="--comms local"
+
+# Number of workers.
+export NWORKERS="--nworkers 4"
+
+# Wallclock for libE.  (allow clean shutdown)
+#export LIBE_WALLCLOCK=25 # Optional if pass to script
+
+# Name of Conda environment
+export CONDA_ENV_NAME=<conda_env_name>
+
+# Need these if not already loaded
+# module load python
+# module load gcc/4.8.5
+
+# Activate conda environment
+export PYTHONNOUSERSITE=1
+. activate $CONDA_ENV_NAME
+
+# hash -d python # Check pick up python in conda env
+hash -r # Check no commands hashed (pip/python...)
+
+# Launch libE.
+#python $EXE $LIBE_WALLCLOCK > out.txt 2>&1  # If user script takes wall-clock as positional arg.
+python $EXE $COMMS $NWORKERS > out.txt 2>&1  # If script is using utils.parse_args()
diff --git a/examples/job_submission_scripts/theta_submit_balsam.sh b/examples/job_submission_scripts/theta_submit_balsam.sh
index 2751be89b..a80d2fba6 100644
--- a/examples/job_submission_scripts/theta_submit_balsam.sh
+++ b/examples/job_submission_scripts/theta_submit_balsam.sh
@@ -4,7 +4,7 @@
 #COBALT -n 5 # No. nodes
 #COBALT -q debug-flat-quad # Up to 8 nodes only
 ##COBALT -q default # For large jobs >=128 nodes
-##COBALT -A <...project code...>
+##COBALT -A <project code>
 
 # Script to launch libEnsemble using Balsam within Conda. Conda environment must be set up.
 
@@ -35,7 +35,7 @@ export LIBE_WALLCLOCK=$(($BALSAM_WALLCLOCK-3))
 # export SCRIPT_ARGS='' # No args
 # export SCRIPT_ARGS='$LIBE_WALLCLOCK' # If calling script takes wall-clock as positional arg.
 
-# If script is using util.parse_args() and takes wall-clock as positional arg.
+# If script is using utilsparse_args() and takes wall-clock as positional arg.
 export SCRIPT_ARGS="--comms mpi --nworkers $NUM_WORKERS $LIBE_WALLCLOCK"
 
 # Name of Conda environment (Need to have set up: https://balsam.readthedocs.io/en/latest/userguide/getting-started.html)
diff --git a/examples/job_submission_scripts/theta_submit_mproc.sh b/examples/job_submission_scripts/theta_submit_mproc.sh
index 74718bfc3..7c638a6a3 100755
--- a/examples/job_submission_scripts/theta_submit_mproc.sh
+++ b/examples/job_submission_scripts/theta_submit_mproc.sh
@@ -1,9 +1,10 @@
 #!/bin/bash -x
 #COBALT -t 00:30:00
+#COBALT -O libE_mproc_MOM
 #COBALT -n 4
 #COBALT -q debug-flat-quad # Up to 8 nodes only
 ##COBALT -q default # For large jobs >=128 nodes
-##COBALT -A <...project code...>
+##COBALT -A <project code>
 
 # Script to run libEnsemble using multiprocessing on launch nodes.
 # Assumes Conda environment is set up.
@@ -44,4 +45,4 @@ export PYTHONNOUSERSITE=1
 # Launch libE
 #python $EXE $NUM_WORKERS > out.txt 2>&1 # No args
 #python $EXE $NUM_WORKERS $LIBE_WALLCLOCK > out.txt 2>&1  # If user script takes wall-clock as positional arg.
-python $EXE $COMMS $NWORKERS > out.txt 2>&1  # If script is using util.parse_args()
+python $EXE $COMMS $NWORKERS > out.txt 2>&1  # If script is using utils.parse_args()

From 24c8333d7c522ce2facc4b35743adf10141340b0 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 21 Nov 2019 11:26:33 -0600
Subject: [PATCH 599/644] Trying to trigger RTD


From eb25c7a19b182ce33be91e580e9382dc477bed47 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Thu, 21 Nov 2019 11:31:56 -0600
Subject: [PATCH 600/644] adds symlinks for example calling scripts and
 regression tests dir

---
 examples/calling_scripts/regression_tests                        | 1 +
 examples/calling_scripts/run_libe_forces.py                      | 1 +
 .../calling_scripts/test_6-hump_camel_persistent_aposmm_1.py     | 1 +
 examples/calling_scripts/tutorial_calling.py                     | 1 +
 4 files changed, 4 insertions(+)
 create mode 120000 examples/calling_scripts/regression_tests
 create mode 120000 examples/calling_scripts/run_libe_forces.py
 create mode 120000 examples/calling_scripts/test_6-hump_camel_persistent_aposmm_1.py
 create mode 120000 examples/calling_scripts/tutorial_calling.py

diff --git a/examples/calling_scripts/regression_tests b/examples/calling_scripts/regression_tests
new file mode 120000
index 000000000..2db4760c5
--- /dev/null
+++ b/examples/calling_scripts/regression_tests
@@ -0,0 +1 @@
+../../libensemble/tests/regression_tests
\ No newline at end of file
diff --git a/examples/calling_scripts/run_libe_forces.py b/examples/calling_scripts/run_libe_forces.py
new file mode 120000
index 000000000..ec19d93cb
--- /dev/null
+++ b/examples/calling_scripts/run_libe_forces.py
@@ -0,0 +1 @@
+../../libensemble/tests/scaling_tests/forces/run_libe_forces.py
\ No newline at end of file
diff --git a/examples/calling_scripts/test_6-hump_camel_persistent_aposmm_1.py b/examples/calling_scripts/test_6-hump_camel_persistent_aposmm_1.py
new file mode 120000
index 000000000..a47e29bc9
--- /dev/null
+++ b/examples/calling_scripts/test_6-hump_camel_persistent_aposmm_1.py
@@ -0,0 +1 @@
+../../libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
\ No newline at end of file
diff --git a/examples/calling_scripts/tutorial_calling.py b/examples/calling_scripts/tutorial_calling.py
new file mode 120000
index 000000000..587851d0e
--- /dev/null
+++ b/examples/calling_scripts/tutorial_calling.py
@@ -0,0 +1 @@
+../tutorials/tutorial_calling.py
\ No newline at end of file

From 54a7c5955eb4c1b2190f4f15d66857a204ba37ad Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 21 Nov 2019 11:43:03 -0600
Subject: [PATCH 601/644] Removing Jeff from copyright

---
 docs/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index b45b78d79..975930867 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -91,7 +91,7 @@ def __getattr__(cls, name):
 
 # General information about the project.
 project = 'libEnsemble'
-copyright = '2019, Jeffrey Larson'
+copyright = '2019'
 author = 'Jeffrey Larson, Stephen Hudson, Stefan M. Wild, David Bindel and John-Luke Navarro'
 
 # The version info for the project you're documenting, acts as replacement for

From d72ff144dd89d5be81df5d7a957bd19806e0e4d3 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Thu, 21 Nov 2019 11:51:33 -0600
Subject: [PATCH 602/644] Removing bib from html, link should still work

---
 docs/index.rst | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/index.rst b/docs/index.rst
index ca3837201..78fc2af8c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -29,7 +29,6 @@
    known_issues
    release_notes
    contributing
-   bibliography
 
 .. toctree::
    :maxdepth: 2

From 15aed8769e4deacc76db0c7569e1655b2468d24d Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Mon, 25 Nov 2019 10:56:29 -0600
Subject: [PATCH 603/644] Make parse_args ignore unrecognized args and utils
 logger for I/O

---
 libensemble/utils.py | 41 ++++++++++++++++++++++++++++++++++-------
 1 file changed, 34 insertions(+), 7 deletions(-)

diff --git a/libensemble/utils.py b/libensemble/utils.py
index 836cddec4..1d4256912 100644
--- a/libensemble/utils.py
+++ b/libensemble/utils.py
@@ -7,9 +7,25 @@
 import argparse
 import pickle
 
+# Create logger
 logger = logging.getLogger(__name__)
-# To change logging level for just this module
-# logger.setLevel(logging.DEBUG)
+logger.propagate = False
+logger.setLevel(logging.INFO)
+
+# Set up format (Alt. Import LogConfig and base on that)
+utils_logformat = '%(name)s: %(message)s'
+formatter = logging.Formatter(utils_logformat)
+
+# Log to file
+# util_filename = 'util.log'
+# fh = logging.FileHandler(util_filename, mode='w')
+# fh.setFormatter(formatter)
+# logger.addHandler(fh)
+
+# Log to standard error
+sth = logging.StreamHandler(stream=sys.stderr)
+sth.setFormatter(formatter)
+logger.addHandler(sth)
 
 
 """
@@ -346,7 +362,8 @@ def parse_args():
         :doc:`(example)<data_structures/libE_specs>`
 
     """
-    args = parser.parse_args(sys.argv[1:])
+    #args = parser.parse_args(sys.argv[1:])
+    args, unknown = parser.parse_known_args(sys.argv[1:])
     front_ends = {
         'mpi': _mpi_parse_args,
         'local': _local_parse_args,
@@ -355,12 +372,15 @@ def parse_args():
         'client': _client_parse_args}
     if args.pwd is not None:
         os.chdir(args.pwd)
-    return front_ends[args.comms or 'mpi'](args)
+    nworkers, is_master, libE_specs, tester_args = front_ends[args.comms or 'mpi'](args)
+    if is_master and unknown:
+        logger.warning('parse_args ignoring unrecognized arguments: {}'.format(' '.join(unknown)))
+    return nworkers, is_master, libE_specs, tester_args
 
 # =================== save libE output to pickle and np ========================
 
 
-def save_libE_output(H, persis_info, calling_file, nworkers):
+def save_libE_output(H, persis_info, calling_file, nworkers, mess='Run completed'):
     """
     Writes out history array and persis_info to files.
 
@@ -392,6 +412,10 @@ def save_libE_output(H, persis_info, calling_file, nworkers):
 
         The number of workers in this ensemble. Added to output file names.
 
+    mess: :obj:`String`
+
+        A message to print/log when saving the file.
+
     """
 
     script_name = os.path.splitext(os.path.basename(calling_file))[0]
@@ -400,13 +424,14 @@ def save_libE_output(H, persis_info, calling_file, nworkers):
                           + '_evals=' + str(sum(H['returned'])) \
                           + '_ranks=' + str(nworkers)
 
-    print("\n\n\nRun completed.\nSaving results to file: "+filename)
+    status_mess = ' '.join(['------------------', mess, '-------------------'])
+    logger.info('{}\nSaving results to file: {}'.format(status_mess, filename))
     np.save(filename, H)
 
     with open(filename + ".pickle", "wb") as f:
         pickle.dump(persis_info, f)
 
-# ===================== per-worker numpy random-streams ========================
+# ===================== per-process numpy random-streams =======================
 
 
 def add_unique_random_streams(persis_info, nstreams):
@@ -446,5 +471,7 @@ def add_unique_random_streams(persis_info, nstreams):
     return persis_info
 
 
+# A very specific exception to using the logger.
 def eprint(*args, **kwargs):
+    """Prints a user message to standard error"""
     print(*args, file=sys.stderr, **kwargs)

From f561dc871b16b62e6983643a5a7f8b552b119db4 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Mon, 25 Nov 2019 11:34:28 -0600
Subject: [PATCH 604/644] Whitespace

---
 docs/platforms/summit.rst    | 3 ---
 docs/sim_gen_alloc_funcs.rst | 2 --
 2 files changed, 5 deletions(-)

diff --git a/docs/platforms/summit.rst b/docs/platforms/summit.rst
index 1cdf7caec..0877b809d 100644
--- a/docs/platforms/summit.rst
+++ b/docs/platforms/summit.rst
@@ -12,7 +12,6 @@ Users on login nodes submit batch runs to the launch nodes.
 Batch scripts and interactive sessions run on the launch nodes. Only the launch
 nodes can submit MPI runs to the compute nodes via ``jsrun``.
 
-
 Configuring Python
 ------------------
 
@@ -124,7 +123,6 @@ libEnsemble on Summit becomes::
 
     $ bsub myscript.sh
 
-
 Launching user applications from libEnsemble Workers
 ----------------------------------------------------
 
@@ -135,7 +133,6 @@ is used inside the ``sim_f`` or ``gen_f``, as this provides a portable interface
 with many advantages including automatic resource detection, portability,
 launch failure resilience, and ease-of-use.
 
-
 Additional Information
 ----------------------
 
diff --git a/docs/sim_gen_alloc_funcs.rst b/docs/sim_gen_alloc_funcs.rst
index 77a253a2c..137a1991c 100644
--- a/docs/sim_gen_alloc_funcs.rst
+++ b/docs/sim_gen_alloc_funcs.rst
@@ -75,7 +75,6 @@ Returns:
   Provides a job status to the Manager and the libE_stats.txt file.
   :doc:`(example)<data_structures/calc_status>`
 
-
 gen_f API
 ~~~~~~~~~
 .. _api_gen_f:
@@ -113,7 +112,6 @@ Returns:
   Provides a job status to the Manager and the libE_stats.txt file.
   :doc:`(example)<data_structures/calc_status>`
 
-
 alloc_f API
 ~~~~~~~~~~~
 .. _api_alloc_f:

From 424bf084906ff087fe85d8483425d2140e2b7924 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 25 Nov 2019 11:59:53 -0600
Subject: [PATCH 605/644] flake8

---
 libensemble/utils.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/utils.py b/libensemble/utils.py
index 1d4256912..f769c6365 100644
--- a/libensemble/utils.py
+++ b/libensemble/utils.py
@@ -362,7 +362,7 @@ def parse_args():
         :doc:`(example)<data_structures/libE_specs>`
 
     """
-    #args = parser.parse_args(sys.argv[1:])
+    # args = parser.parse_args(sys.argv[1:])
     args, unknown = parser.parse_known_args(sys.argv[1:])
     front_ends = {
         'mpi': _mpi_parse_args,

From c5f7ae152b8f7b71326402e1035046ef5eba1253 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Mon, 25 Nov 2019 10:56:29 -0600
Subject: [PATCH 606/644] Make parse_args ignore unrecognized args and utils
 logger for I/O

---
 libensemble/utils.py | 41 ++++++++++++++++++++++++++++++++++-------
 1 file changed, 34 insertions(+), 7 deletions(-)

diff --git a/libensemble/utils.py b/libensemble/utils.py
index 836cddec4..1d4256912 100644
--- a/libensemble/utils.py
+++ b/libensemble/utils.py
@@ -7,9 +7,25 @@
 import argparse
 import pickle
 
+# Create logger
 logger = logging.getLogger(__name__)
-# To change logging level for just this module
-# logger.setLevel(logging.DEBUG)
+logger.propagate = False
+logger.setLevel(logging.INFO)
+
+# Set up format (Alt. Import LogConfig and base on that)
+utils_logformat = '%(name)s: %(message)s'
+formatter = logging.Formatter(utils_logformat)
+
+# Log to file
+# util_filename = 'util.log'
+# fh = logging.FileHandler(util_filename, mode='w')
+# fh.setFormatter(formatter)
+# logger.addHandler(fh)
+
+# Log to standard error
+sth = logging.StreamHandler(stream=sys.stderr)
+sth.setFormatter(formatter)
+logger.addHandler(sth)
 
 
 """
@@ -346,7 +362,8 @@ def parse_args():
         :doc:`(example)<data_structures/libE_specs>`
 
     """
-    args = parser.parse_args(sys.argv[1:])
+    #args = parser.parse_args(sys.argv[1:])
+    args, unknown = parser.parse_known_args(sys.argv[1:])
     front_ends = {
         'mpi': _mpi_parse_args,
         'local': _local_parse_args,
@@ -355,12 +372,15 @@ def parse_args():
         'client': _client_parse_args}
     if args.pwd is not None:
         os.chdir(args.pwd)
-    return front_ends[args.comms or 'mpi'](args)
+    nworkers, is_master, libE_specs, tester_args = front_ends[args.comms or 'mpi'](args)
+    if is_master and unknown:
+        logger.warning('parse_args ignoring unrecognized arguments: {}'.format(' '.join(unknown)))
+    return nworkers, is_master, libE_specs, tester_args
 
 # =================== save libE output to pickle and np ========================
 
 
-def save_libE_output(H, persis_info, calling_file, nworkers):
+def save_libE_output(H, persis_info, calling_file, nworkers, mess='Run completed'):
     """
     Writes out history array and persis_info to files.
 
@@ -392,6 +412,10 @@ def save_libE_output(H, persis_info, calling_file, nworkers):
 
         The number of workers in this ensemble. Added to output file names.
 
+    mess: :obj:`String`
+
+        A message to print/log when saving the file.
+
     """
 
     script_name = os.path.splitext(os.path.basename(calling_file))[0]
@@ -400,13 +424,14 @@ def save_libE_output(H, persis_info, calling_file, nworkers):
                           + '_evals=' + str(sum(H['returned'])) \
                           + '_ranks=' + str(nworkers)
 
-    print("\n\n\nRun completed.\nSaving results to file: "+filename)
+    status_mess = ' '.join(['------------------', mess, '-------------------'])
+    logger.info('{}\nSaving results to file: {}'.format(status_mess, filename))
     np.save(filename, H)
 
     with open(filename + ".pickle", "wb") as f:
         pickle.dump(persis_info, f)
 
-# ===================== per-worker numpy random-streams ========================
+# ===================== per-process numpy random-streams =======================
 
 
 def add_unique_random_streams(persis_info, nstreams):
@@ -446,5 +471,7 @@ def add_unique_random_streams(persis_info, nstreams):
     return persis_info
 
 
+# A very specific exception to using the logger.
 def eprint(*args, **kwargs):
+    """Prints a user message to standard error"""
     print(*args, file=sys.stderr, **kwargs)

From 8f389b7edec7f3efa625d04ffc414357c6ef309a Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Tue, 26 Nov 2019 16:19:22 -0600
Subject: [PATCH 607/644] Change script plot_libE_histogram.py to
 plot_libe_histogram.py

---
 libensemble/tests/scaling_tests/forces/summit_submit_mproc.sh   | 2 +-
 libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh   | 2 +-
 libensemble/tests/scaling_tests/forces/theta_submit_mproc.sh    | 2 +-
 .../{plot_libE_histogram.py => plot_libe_histogram.py}          | 0
 postproc_scripts/readme.rst                                     | 2 +-
 5 files changed, 4 insertions(+), 4 deletions(-)
 rename postproc_scripts/{plot_libE_histogram.py => plot_libe_histogram.py} (100%)

diff --git a/libensemble/tests/scaling_tests/forces/summit_submit_mproc.sh b/libensemble/tests/scaling_tests/forces/summit_submit_mproc.sh
index 42e9da68c..0f34cd3a1 100644
--- a/libensemble/tests/scaling_tests/forces/summit_submit_mproc.sh
+++ b/libensemble/tests/scaling_tests/forces/summit_submit_mproc.sh
@@ -48,5 +48,5 @@ python $EXE $COMMS $NWORKERS > out.txt 2>&1
 if [[ $LIBE_PLOTS = "true" ]]; then
   python $PLOT_DIR/plot_libe_calcs_util_v_time.py
   python $PLOT_DIR/plot_libe_runs_util_v_time.py
-  python $PLOT_DIR/plot_libE_histogram.py
+  python $PLOT_DIR/plot_libe_histogram.py
 fi
diff --git a/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh b/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh
index e8d2f8306..f79e5e2a7 100755
--- a/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh
+++ b/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh
@@ -92,7 +92,7 @@ balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1
 if [[ $LIBE_PLOTS = "true" ]]; then
   python $PLOT_DIR/plot_libe_calcs_util_v_time.py
   python $PLOT_DIR/plot_libe_runs_util_v_time.py
-  python $PLOT_DIR/plot_libE_histogram.pyfi
+  python $PLOT_DIR/plot_libe_histogram.pyfi
 
 if [[ $BALSAM_PLOTS = "true" ]]; then
 #   export MPLBACKEND=TkAgg
diff --git a/libensemble/tests/scaling_tests/forces/theta_submit_mproc.sh b/libensemble/tests/scaling_tests/forces/theta_submit_mproc.sh
index c39b8f9e3..ddfeafb74 100755
--- a/libensemble/tests/scaling_tests/forces/theta_submit_mproc.sh
+++ b/libensemble/tests/scaling_tests/forces/theta_submit_mproc.sh
@@ -51,5 +51,5 @@ python $EXE $COMMS $NWORKERS > out.txt 2>&1
 if [[ $LIBE_PLOTS = "true" ]]; then
   python $PLOT_DIR/plot_libe_calcs_util_v_time.py
   python $PLOT_DIR/plot_libe_runs_util_v_time.py
-  python $PLOT_DIR/plot_libE_histogram.py
+  python $PLOT_DIR/plot_libe_histogram.py
 fi
diff --git a/postproc_scripts/plot_libE_histogram.py b/postproc_scripts/plot_libe_histogram.py
similarity index 100%
rename from postproc_scripts/plot_libE_histogram.py
rename to postproc_scripts/plot_libe_histogram.py
diff --git a/postproc_scripts/readme.rst b/postproc_scripts/readme.rst
index ce160f1e8..94d2d9ae1 100644
--- a/postproc_scripts/readme.rst
+++ b/postproc_scripts/readme.rst
@@ -10,7 +10,7 @@ The following scripts must be run in the directory with the **libE_stats.txt** f
 
 * **plot_libe_runs_util_v_time.py**: Extract launched job utilization v time plot (with one second sampling). Shows number of workers with active jobs, launched via the job controller, over time.
 
-* **plot_libE_histogram.py**: Create histogram showing the number of completed/killed/failed user calculations binned by run-time.
+* **plot_libe_histogram.py**: Create histogram showing the number of completed/killed/failed user calculations binned by run-time.
 
 ========================
 Results analysis scripts

From c296fab060eb3d5b50b36b376627707b659835b9 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Tue, 26 Nov 2019 17:34:48 -0600
Subject: [PATCH 608/644] Remove print in resources.py

---
 libensemble/resources.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/libensemble/resources.py b/libensemble/resources.py
index a5254499c..739194a51 100644
--- a/libensemble/resources.py
+++ b/libensemble/resources.py
@@ -159,7 +159,6 @@ def get_MPI_variant():
                 return 'mpich'
             return 'openmpi'
         except Exception as e:
-            print('Testing: Error on MPI command: {}'.format(e))
             pass
 
         try:

From 1a9f54790b25107c42dfc4404aadb6dd31e7f408 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Tue, 26 Nov 2019 21:07:49 -0600
Subject: [PATCH 609/644] Remove ref to common and fix xsdk link for pdf

---
 README.rst                  | 2 +-
 docs/introduction_latex.rst | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.rst b/README.rst
index a0248f2ba..bb473a6be 100644
--- a/README.rst
+++ b/README.rst
@@ -242,4 +242,4 @@ Resources
 .. _tarball: https://github.com/Libensemble/libensemble/releases/latest
 .. _Travis CI: https://travis-ci.org/Libensemble/libensemble
 .. _user guide: https://libensemble.readthedocs.io/en/latest/user_guide.html
-.. _xSDK Extreme-scale Scientific Software Development Kit: https://xsdk.info/
+.. _xSDK Extreme-scale Scientific Software Development Kit: https://xsdk.info
diff --git a/docs/introduction_latex.rst b/docs/introduction_latex.rst
index e287bb7a7..fd02676cb 100644
--- a/docs/introduction_latex.rst
+++ b/docs/introduction_latex.rst
@@ -20,7 +20,6 @@ Quickstart Guide
     :end-before: after_resources_rst_tag
 
 .. _Balsam: https://www.alcf.anl.gov/balsam
-.. _common.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/common.py
 .. _Coveralls: https://coveralls.io/github/Libensemble/libensemble?branch=master
 .. _GitHub: https://github.com/Libensemble/libensemble
 .. _libEnsemble mailing list: https://lists.mcs.anl.gov/mailman/listinfo/libensemble
@@ -45,3 +44,4 @@ Quickstart Guide
 .. _tarball: https://github.com/Libensemble/libensemble/releases/latest
 .. _Travis CI: https://travis-ci.org/Libensemble/libensemble
 .. _user guide: https://libensemble.readthedocs.io/en/latest/user_guide.html
+.. _xSDK Extreme-scale Scientific Software Development Kit: https://xsdk.info
\ No newline at end of file

From 4898abf4a2c9c1b6abb90eaab7d760efe9a63af8 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Tue, 26 Nov 2019 21:41:56 -0600
Subject: [PATCH 610/644] Copyright 2019 Argonne National Laboratory

---
 docs/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index 975930867..0798e55fa 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -91,7 +91,7 @@ def __getattr__(cls, name):
 
 # General information about the project.
 project = 'libEnsemble'
-copyright = '2019'
+copyright = '2019 Argonne National Laboratory'
 author = 'Jeffrey Larson, Stephen Hudson, Stefan M. Wild, David Bindel and John-Luke Navarro'
 
 # The version info for the project you're documenting, acts as replacement for

From c9d8844ff09208d4d9ad497a2d26d87489fb6859 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Tue, 26 Nov 2019 22:21:23 -0600
Subject: [PATCH 611/644] Update example submission scripts

---
 docs/platforms/example_scripts.rst                 | 14 ++++++++++++++
 examples/job_submission_scripts/blues_script.pbs   |  5 +----
 .../job_submission_scripts/summit_submit_mproc.sh  | 11 ++++++-----
 .../job_submission_scripts/theta_submit_balsam.sh  | 12 +++++-------
 .../job_submission_scripts/theta_submit_mproc.sh   | 12 ++++++------
 5 files changed, 32 insertions(+), 22 deletions(-)

diff --git a/docs/platforms/example_scripts.rst b/docs/platforms/example_scripts.rst
index c6b300bb6..7d6288edc 100644
--- a/docs/platforms/example_scripts.rst
+++ b/docs/platforms/example_scripts.rst
@@ -26,9 +26,23 @@ Blues
     :caption: /examples/job_submission_scripts/blues_script.pbs
     :language: bash
 
+Theta - On MOM with multiprocessing
+-----------------------------------
+
+..  literalinclude:: ../../examples/job_submission_scripts/theta_submit_mproc.sh
+    :caption: /examples/job_submission_scripts/theta_submit_mproc.sh
+    :language: bash
+
 Theta - Central Mode with Balsam
 --------------------------------
 
 ..  literalinclude:: ../../examples/job_submission_scripts/theta_submit_balsam.sh
     :caption: /examples/job_submission_scripts/theta_submit_balsam.sh
     :language: bash
+
+Summit - On Launch nodes with multiprocessing
+---------------------------------------------
+
+..  literalinclude:: ../../examples/job_submission_scripts/summit_submit_mproc.sh
+    :caption: /examples/job_submission_scripts/summit_submit_mproc.sh
+    :language: bash
diff --git a/examples/job_submission_scripts/blues_script.pbs b/examples/job_submission_scripts/blues_script.pbs
index 1afac76f1..843a86763 100644
--- a/examples/job_submission_scripts/blues_script.pbs
+++ b/examples/job_submission_scripts/blues_script.pbs
@@ -30,9 +30,6 @@
 ##PBS -q ivy
 #PBS -q shared
 
-export NLOPT_PYTHON_HOME="/home/jlarson/software/nlopt_install/lib/python2.7/site-packages"
-export PYTHONPATH="${PYTHONPATH}:${NLOPT_PYTHON_HOME}"
-
 cd $PBS_O_WORKDIR
 
 # A little useful information for the log file...
@@ -55,7 +52,7 @@ cat $PBS_NODEFILE | sort | uniq >> libE_machinefile
 echo Starting executation at: `date`
 
 pwd
-cmd="mpiexec -np 5 -machinefile libE_machinefile python2 libE_calling_script.py libE_machinefile"
+cmd="mpiexec -np 5 -machinefile libE_machinefile python libE_calling_script.py libE_machinefile"
 # This note that this command passes the libE_machinefile to both MPI and the
 # libE_calling_script, in the latter script, it can be parsed and given to the
 # alloc_func
diff --git a/examples/job_submission_scripts/summit_submit_mproc.sh b/examples/job_submission_scripts/summit_submit_mproc.sh
index 8872e1811..5a83ff106 100644
--- a/examples/job_submission_scripts/summit_submit_mproc.sh
+++ b/examples/job_submission_scripts/summit_submit_mproc.sh
@@ -13,7 +13,7 @@
 # - Workers submit jobs to the nodes in the job available.
 
 # Name of calling script-
-export EXE=run_libe_forces.py
+export EXE=libE_calling_script.py
 
 # Communication Method
 export COMMS="--comms local"
@@ -22,7 +22,7 @@ export COMMS="--comms local"
 export NWORKERS="--nworkers 4"
 
 # Wallclock for libE.  (allow clean shutdown)
-#export LIBE_WALLCLOCK=25 # Optional if pass to script
+export LIBE_WALLCLOCK=25 # Optional if pass to script
 
 # Name of Conda environment
 export CONDA_ENV_NAME=<conda_env_name>
@@ -38,6 +38,7 @@ export PYTHONNOUSERSITE=1
 # hash -d python # Check pick up python in conda env
 hash -r # Check no commands hashed (pip/python...)
 
-# Launch libE.
-#python $EXE $LIBE_WALLCLOCK > out.txt 2>&1  # If user script takes wall-clock as positional arg.
-python $EXE $COMMS $NWORKERS > out.txt 2>&1  # If script is using utils.parse_args()
+# Launch libE
+# python $EXE $NUM_WORKERS > out.txt 2>&1  # No args. All defined in calling script
+# python $EXE $COMMS $NWORKERS > out.txt 2>&1  # If calling script is using utils.parse_args()
+python $EXE $LIBE_WALLCLOCK $COMMS $NWORKERS > out.txt 2>&1 # If calling script takes wall-clock as positional arg.
\ No newline at end of file
diff --git a/examples/job_submission_scripts/theta_submit_balsam.sh b/examples/job_submission_scripts/theta_submit_balsam.sh
index a80d2fba6..1677b118a 100644
--- a/examples/job_submission_scripts/theta_submit_balsam.sh
+++ b/examples/job_submission_scripts/theta_submit_balsam.sh
@@ -32,11 +32,9 @@ export WORKFLOW_NAME=libe_workflow
 export LIBE_WALLCLOCK=$(($BALSAM_WALLCLOCK-3))
 
 # libEnsemble calling script arguments
-# export SCRIPT_ARGS='' # No args
-# export SCRIPT_ARGS='$LIBE_WALLCLOCK' # If calling script takes wall-clock as positional arg.
-
-# If script is using utilsparse_args() and takes wall-clock as positional arg.
-export SCRIPT_ARGS="--comms mpi --nworkers $NUM_WORKERS $LIBE_WALLCLOCK"
+# export SCRIPT_ARGS='' # No args. All defined in calling script
+# export SCRIPT_ARGS="--comms mpi --nworkers $NUM_WORKERS # If calling script is using utils.parse_args()
+export SCRIPT_ARGS="$LIBE_WALLCLOCK --comms mpi --nworkers $NUM_WORKERS"  # If calling script takes wall-clock as positional arg.
 
 # Name of Conda environment (Need to have set up: https://balsam.readthedocs.io/en/latest/userguide/getting-started.html)
 export CONDA_ENV_NAME=<conda_env_name>
@@ -45,8 +43,8 @@ export CONDA_ENV_NAME=<conda_env_name>
 export DBASE_NAME=<dbase_name>  # default - to use default database.
 
 # Conda location - theta specific
-# export PATH=/opt/intel/python/2017.0.035/intelpython35/bin:$PATH
-# export LD_LIBRARY_PATH=~/.conda/envs/$CONDA_ENV_NAME/lib:$LD_LIBRARY_PATH
+export PATH=/opt/intel/python/2017.0.035/intelpython35/bin:$PATH
+export LD_LIBRARY_PATH=~/.conda/envs/$CONDA_ENV_NAME/lib:$LD_LIBRARY_PATH
 
 export PYTHONNOUSERSITE=1 # Ensure environment isolated
 
diff --git a/examples/job_submission_scripts/theta_submit_mproc.sh b/examples/job_submission_scripts/theta_submit_mproc.sh
index 7c638a6a3..394091c72 100755
--- a/examples/job_submission_scripts/theta_submit_mproc.sh
+++ b/examples/job_submission_scripts/theta_submit_mproc.sh
@@ -14,7 +14,7 @@
 # - Workers submit jobs to the compute nodes in the node allocation available.
 
 # Name of calling script
-export EXE=run_libe_forces.py
+export EXE=libE_calling_script.py
 
 # Communication Method
 export COMMS="--comms local"
@@ -23,14 +23,14 @@ export COMMS="--comms local"
 export NWORKERS="--nworkers 4"
 
 # Wallclock for libE (allow clean shutdown)
-#export LIBE_WALLCLOCK=25 # Optional if pass to script
+export LIBE_WALLCLOCK=25 # Optional if pass to script
 
 # Name of Conda environment
 export CONDA_ENV_NAME=<conda_env_name>
 
 # Conda location - theta specific
 export PATH=/opt/intel/python/2017.0.035/intelpython35/bin:$PATH
-export LD_LIBRARY_PATH=~/.conda/envs/balsam/lib:$LD_LIBRARY_PATH
+export LD_LIBRARY_PATH=~/.conda/envs/$CONDA_ENV_NAME/lib:$LD_LIBRARY_PATH
 export PMI_NO_FORK=1 # Required for python kills on Theta
 
 # Unload Theta modules that may interfere with job monitoring/kills
@@ -43,6 +43,6 @@ export PYTHONNOUSERSITE=1
 . activate $CONDA_ENV_NAME
 
 # Launch libE
-#python $EXE $NUM_WORKERS > out.txt 2>&1 # No args
-#python $EXE $NUM_WORKERS $LIBE_WALLCLOCK > out.txt 2>&1  # If user script takes wall-clock as positional arg.
-python $EXE $COMMS $NWORKERS > out.txt 2>&1  # If script is using utils.parse_args()
+# python $EXE $NUM_WORKERS > out.txt 2>&1  # No args. All defined in calling script
+# python $EXE $COMMS $NWORKERS > out.txt 2>&1  # If calling script is using utils.parse_args()
+python $EXE $LIBE_WALLCLOCK $COMMS $NWORKERS > out.txt 2>&1 # If calling script takes wall-clock as positional arg.

From f5fe36d5acbedeb1f74b7772e142a6c09e75c3e7 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Tue, 26 Nov 2019 22:25:20 -0600
Subject: [PATCH 612/644] Remove individual links from example calling scripts
 to regression tests

---
 .../test_6-hump_camel_active_persistent_worker_abort.py          | 1 -
 examples/calling_scripts/test_6-hump_camel_aposmm_LD_MMA.py      | 1 -
 examples/calling_scripts/test_6-hump_camel_elapsed_time_abort.py | 1 -
 .../calling_scripts/test_6-hump_camel_persistent_aposmm_1.py     | 1 -
 .../test_6-hump_camel_persistent_uniform_sampling.py             | 1 -
 examples/calling_scripts/test_6-hump_camel_uniform_sampling.py   | 1 -
 ...-hump_camel_uniform_sampling_with_persistent_localopt_gens.py | 1 -
 .../test_6-hump_camel_with_different_nodes_uniform_sample.py     | 1 -
 .../calling_scripts/test_branin_aposmm_nlopt_and_then_scipy.py   | 1 -
 .../test_chwirut_aposmm_one_residual_at_a_time.py                | 1 -
 examples/calling_scripts/test_chwirut_pounders.py                | 1 -
 .../test_chwirut_uniform_sampling_one_residual_at_a_time.py      | 1 -
 examples/calling_scripts/test_fast_alloc.py                      | 1 -
 examples/calling_scripts/test_jobcontroller_hworld.py            | 1 -
 examples/calling_scripts/test_nan_func_aposmm.py                 | 1 -
 15 files changed, 15 deletions(-)
 delete mode 120000 examples/calling_scripts/test_6-hump_camel_active_persistent_worker_abort.py
 delete mode 120000 examples/calling_scripts/test_6-hump_camel_aposmm_LD_MMA.py
 delete mode 120000 examples/calling_scripts/test_6-hump_camel_elapsed_time_abort.py
 delete mode 120000 examples/calling_scripts/test_6-hump_camel_persistent_aposmm_1.py
 delete mode 120000 examples/calling_scripts/test_6-hump_camel_persistent_uniform_sampling.py
 delete mode 120000 examples/calling_scripts/test_6-hump_camel_uniform_sampling.py
 delete mode 120000 examples/calling_scripts/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
 delete mode 120000 examples/calling_scripts/test_6-hump_camel_with_different_nodes_uniform_sample.py
 delete mode 120000 examples/calling_scripts/test_branin_aposmm_nlopt_and_then_scipy.py
 delete mode 120000 examples/calling_scripts/test_chwirut_aposmm_one_residual_at_a_time.py
 delete mode 120000 examples/calling_scripts/test_chwirut_pounders.py
 delete mode 120000 examples/calling_scripts/test_chwirut_uniform_sampling_one_residual_at_a_time.py
 delete mode 120000 examples/calling_scripts/test_fast_alloc.py
 delete mode 120000 examples/calling_scripts/test_jobcontroller_hworld.py
 delete mode 120000 examples/calling_scripts/test_nan_func_aposmm.py

diff --git a/examples/calling_scripts/test_6-hump_camel_active_persistent_worker_abort.py b/examples/calling_scripts/test_6-hump_camel_active_persistent_worker_abort.py
deleted file mode 120000
index 70e23cd6b..000000000
--- a/examples/calling_scripts/test_6-hump_camel_active_persistent_worker_abort.py
+++ /dev/null
@@ -1 +0,0 @@
-../../libensemble/tests/regression_tests/test_6-hump_camel_active_persistent_worker_abort.py
\ No newline at end of file
diff --git a/examples/calling_scripts/test_6-hump_camel_aposmm_LD_MMA.py b/examples/calling_scripts/test_6-hump_camel_aposmm_LD_MMA.py
deleted file mode 120000
index a757eb29b..000000000
--- a/examples/calling_scripts/test_6-hump_camel_aposmm_LD_MMA.py
+++ /dev/null
@@ -1 +0,0 @@
-../../libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py
\ No newline at end of file
diff --git a/examples/calling_scripts/test_6-hump_camel_elapsed_time_abort.py b/examples/calling_scripts/test_6-hump_camel_elapsed_time_abort.py
deleted file mode 120000
index a70d98a27..000000000
--- a/examples/calling_scripts/test_6-hump_camel_elapsed_time_abort.py
+++ /dev/null
@@ -1 +0,0 @@
-../../libensemble/tests/regression_tests/test_6-hump_camel_elapsed_time_abort.py
\ No newline at end of file
diff --git a/examples/calling_scripts/test_6-hump_camel_persistent_aposmm_1.py b/examples/calling_scripts/test_6-hump_camel_persistent_aposmm_1.py
deleted file mode 120000
index a47e29bc9..000000000
--- a/examples/calling_scripts/test_6-hump_camel_persistent_aposmm_1.py
+++ /dev/null
@@ -1 +0,0 @@
-../../libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm_1.py
\ No newline at end of file
diff --git a/examples/calling_scripts/test_6-hump_camel_persistent_uniform_sampling.py b/examples/calling_scripts/test_6-hump_camel_persistent_uniform_sampling.py
deleted file mode 120000
index 0816635dc..000000000
--- a/examples/calling_scripts/test_6-hump_camel_persistent_uniform_sampling.py
+++ /dev/null
@@ -1 +0,0 @@
-../../libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py
\ No newline at end of file
diff --git a/examples/calling_scripts/test_6-hump_camel_uniform_sampling.py b/examples/calling_scripts/test_6-hump_camel_uniform_sampling.py
deleted file mode 120000
index e88d8bc54..000000000
--- a/examples/calling_scripts/test_6-hump_camel_uniform_sampling.py
+++ /dev/null
@@ -1 +0,0 @@
-../../libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py
\ No newline at end of file
diff --git a/examples/calling_scripts/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py b/examples/calling_scripts/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
deleted file mode 120000
index 1564553fc..000000000
--- a/examples/calling_scripts/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
+++ /dev/null
@@ -1 +0,0 @@
-../../libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py
\ No newline at end of file
diff --git a/examples/calling_scripts/test_6-hump_camel_with_different_nodes_uniform_sample.py b/examples/calling_scripts/test_6-hump_camel_with_different_nodes_uniform_sample.py
deleted file mode 120000
index 9403febdc..000000000
--- a/examples/calling_scripts/test_6-hump_camel_with_different_nodes_uniform_sample.py
+++ /dev/null
@@ -1 +0,0 @@
-../../libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py
\ No newline at end of file
diff --git a/examples/calling_scripts/test_branin_aposmm_nlopt_and_then_scipy.py b/examples/calling_scripts/test_branin_aposmm_nlopt_and_then_scipy.py
deleted file mode 120000
index 3868553e8..000000000
--- a/examples/calling_scripts/test_branin_aposmm_nlopt_and_then_scipy.py
+++ /dev/null
@@ -1 +0,0 @@
-../../libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py
\ No newline at end of file
diff --git a/examples/calling_scripts/test_chwirut_aposmm_one_residual_at_a_time.py b/examples/calling_scripts/test_chwirut_aposmm_one_residual_at_a_time.py
deleted file mode 120000
index 2ab47bd5b..000000000
--- a/examples/calling_scripts/test_chwirut_aposmm_one_residual_at_a_time.py
+++ /dev/null
@@ -1 +0,0 @@
-../../libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py
\ No newline at end of file
diff --git a/examples/calling_scripts/test_chwirut_pounders.py b/examples/calling_scripts/test_chwirut_pounders.py
deleted file mode 120000
index fe1d9884c..000000000
--- a/examples/calling_scripts/test_chwirut_pounders.py
+++ /dev/null
@@ -1 +0,0 @@
-../../libensemble/tests/regression_tests/test_chwirut_pounders.py
\ No newline at end of file
diff --git a/examples/calling_scripts/test_chwirut_uniform_sampling_one_residual_at_a_time.py b/examples/calling_scripts/test_chwirut_uniform_sampling_one_residual_at_a_time.py
deleted file mode 120000
index fc71f5fca..000000000
--- a/examples/calling_scripts/test_chwirut_uniform_sampling_one_residual_at_a_time.py
+++ /dev/null
@@ -1 +0,0 @@
-../../libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py
\ No newline at end of file
diff --git a/examples/calling_scripts/test_fast_alloc.py b/examples/calling_scripts/test_fast_alloc.py
deleted file mode 120000
index d81cdd12e..000000000
--- a/examples/calling_scripts/test_fast_alloc.py
+++ /dev/null
@@ -1 +0,0 @@
-../../libensemble/tests/regression_tests/test_fast_alloc.py
\ No newline at end of file
diff --git a/examples/calling_scripts/test_jobcontroller_hworld.py b/examples/calling_scripts/test_jobcontroller_hworld.py
deleted file mode 120000
index 3e864d5b0..000000000
--- a/examples/calling_scripts/test_jobcontroller_hworld.py
+++ /dev/null
@@ -1 +0,0 @@
-../../libensemble/tests/regression_tests/test_jobcontroller_hworld.py
\ No newline at end of file
diff --git a/examples/calling_scripts/test_nan_func_aposmm.py b/examples/calling_scripts/test_nan_func_aposmm.py
deleted file mode 120000
index 9ba82fce2..000000000
--- a/examples/calling_scripts/test_nan_func_aposmm.py
+++ /dev/null
@@ -1 +0,0 @@
-../../libensemble/tests/regression_tests/test_nan_func_aposmm.py
\ No newline at end of file

From c85de4cbcb48c23ab5f27e50b8ee17b42c17faba Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Tue, 26 Nov 2019 22:42:21 -0600
Subject: [PATCH 613/644] Update theta instructions

---
 docs/platforms/theta.rst | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index 23d45e72d..93e5acc1f 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -78,6 +78,11 @@ Initialize a new database similarly to the following (from the Balsam docs):
 
 Read Balsam's documentation here_.
 
+.. note::
+    Balsam will create the run directories inside the data sub-directory within the database
+    directory. From here files can be staged out to the user directory (see the example
+    batch script below).
+
 Job Submission
 --------------
 
@@ -108,7 +113,7 @@ functions execute computationally expensive code, or code built for specific
 architectures. Recall also that only the MOM nodes can launch MPI jobs.
 
 Although libEnsemble workers on the MOM nodes can technically submit
-user-applications to the compute nodes via ``aprun`` within user functions, it
+user-applications to the compute nodes directly via ``aprun`` within user functions, it
 is highly recommended that the aforementioned :doc:`job_controller<../job_controller/overview>`
 interface is used instead. The libEnsemble job-controller features advantages like
 automatic resource-detection, portability, launch failure resilience, and ease-of-use.
@@ -119,6 +124,20 @@ Theta features one default production queue, ``default``, and two debug queues,
 .. note::
     For the default queue, the minimum number of nodes to allocate at once is 128
 
+Module and environment variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To ensure proper functioning of libEnsemble, including the ability to kill running jobs, it
+recommended that the following environment variable is set::
+
+    export PMI_NO_FORK=1
+
+It is also recommended that the following environment modules are unloaded, if present::
+
+    module unload trackdeps
+    module unload darshan
+    module unload xalt
+
 Interactive Runs
 ^^^^^^^^^^^^^^^^
 
@@ -183,6 +202,11 @@ convenience function from libEnsemble's :doc:`utils module<../utilities>`.
     # Required for python kills on Theta
     export PMI_NO_FORK=1
 
+    # Unload Theta modules that may interfere with job monitoring/kills
+    module unload trackdeps
+    module unload darshan
+    module unload xalt
+
     python $EXE $COMMS $NWORKERS > out.txt 2>&1
 
 With this saved as ``myscript.sh``, allocating, configuring, and queueing
@@ -232,6 +256,11 @@ Here is an example Balsam submission script:
     # Required for python kills on Theta
     export PMI_NO_FORK=1
 
+    # Unload Theta modules that may interfere with job monitoring/kills
+    module unload trackdeps
+    module unload darshan
+    module unload xalt
+
     # Activate conda environment
     . activate $CONDA_ENV_NAME
 

From 53697c23fbee3e31bfd52d1be9c4926388782315 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Tue, 26 Nov 2019 22:47:09 -0600
Subject: [PATCH 614/644] Remove unused error variable

---
 libensemble/resources.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/resources.py b/libensemble/resources.py
index 739194a51..1910935ca 100644
--- a/libensemble/resources.py
+++ b/libensemble/resources.py
@@ -158,7 +158,7 @@ def get_MPI_variant():
             if 'unrecognized argument npernode' in stdout.decode():
                 return 'mpich'
             return 'openmpi'
-        except Exception as e:
+        except Exception:
             pass
 
         try:

From 608eb9fd577640cdfd38aa5c67144282986d2008 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 27 Nov 2019 07:49:41 -0600
Subject: [PATCH 615/644] Just casing

---
 docs/platforms/example_scripts.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/platforms/example_scripts.rst b/docs/platforms/example_scripts.rst
index 7d6288edc..8fa2f63ac 100644
--- a/docs/platforms/example_scripts.rst
+++ b/docs/platforms/example_scripts.rst
@@ -5,14 +5,14 @@ Below are some example job-submission scripts used to configure and launch libEn
 on a variety of high-powered systems. See :doc:`here<platforms_index>` for more
 information about the respective systems and configuration.
 
-Bebop - Central Mode
+Bebop - Central mode
 --------------------
 
 ..  literalinclude:: ../../examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
     :caption: /examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
     :language: bash
 
-Bebop - Distributed Mode
+Bebop - Distributed mode
 ------------------------
 
 ..  literalinclude:: ../../examples/job_submission_scripts/bebop_submit_slurm.sh
@@ -26,21 +26,21 @@ Blues
     :caption: /examples/job_submission_scripts/blues_script.pbs
     :language: bash
 
-Theta - On MOM with multiprocessing
+Theta - On MOM nodes with multiprocessing
 -----------------------------------
 
 ..  literalinclude:: ../../examples/job_submission_scripts/theta_submit_mproc.sh
     :caption: /examples/job_submission_scripts/theta_submit_mproc.sh
     :language: bash
 
-Theta - Central Mode with Balsam
+Theta - Central mode with Balsam
 --------------------------------
 
 ..  literalinclude:: ../../examples/job_submission_scripts/theta_submit_balsam.sh
     :caption: /examples/job_submission_scripts/theta_submit_balsam.sh
     :language: bash
 
-Summit - On Launch nodes with multiprocessing
+Summit - On launch nodes with multiprocessing
 ---------------------------------------------
 
 ..  literalinclude:: ../../examples/job_submission_scripts/summit_submit_mproc.sh

From bc70b6ee41b3b1ace8ccc384c871a1136be0e04c Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 27 Nov 2019 07:51:15 -0600
Subject: [PATCH 616/644] Comma

---
 docs/platforms/theta.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index 93e5acc1f..2d1ee4c7d 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -80,7 +80,7 @@ Read Balsam's documentation here_.
 
 .. note::
     Balsam will create the run directories inside the data sub-directory within the database
-    directory. From here files can be staged out to the user directory (see the example
+    directory. From here, files can be staged out to the user directory (see the example
     batch script below).
 
 Job Submission

From 99ab63de654806d838e91168e4b3e7f573b8db78 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 27 Nov 2019 07:56:19 -0600
Subject: [PATCH 617/644] Removing commented out line

---
 libensemble/utils.py | 1 -
 1 file changed, 1 deletion(-)

diff --git a/libensemble/utils.py b/libensemble/utils.py
index f769c6365..434904225 100644
--- a/libensemble/utils.py
+++ b/libensemble/utils.py
@@ -362,7 +362,6 @@ def parse_args():
         :doc:`(example)<data_structures/libE_specs>`
 
     """
-    # args = parser.parse_args(sys.argv[1:])
     args, unknown = parser.parse_known_args(sys.argv[1:])
     front_ends = {
         'mpi': _mpi_parse_args,

From 9550a69d464ba39670a65d59db1f51deb42df88c Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 27 Nov 2019 08:07:39 -0600
Subject: [PATCH 618/644] Having fast_alloc send back all of the history (by
 default)

---
 libensemble/alloc_funcs/fast_alloc.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libensemble/alloc_funcs/fast_alloc.py b/libensemble/alloc_funcs/fast_alloc.py
index c8595207b..8cce6131b 100644
--- a/libensemble/alloc_funcs/fast_alloc.py
+++ b/libensemble/alloc_funcs/fast_alloc.py
@@ -28,6 +28,6 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
             # Give gen work
             persis_info['total_gen_calls'] += 1
             gen_count += 1
-            gen_work(Work, i, gen_specs['in'], [], persis_info[i])
+            gen_work(Work, i, gen_specs['in'], range(len(H)), persis_info[i])
 
     return Work, persis_info

From 614fa570c000fddccf10feb208f8fd983b1d47ce Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 27 Nov 2019 11:18:37 -0600
Subject: [PATCH 619/644] Fixing typos

---
 docs/platforms/example_scripts.rst                            | 4 ++--
 libensemble/tests/scaling_tests/forces/summit_submit_mproc.sh | 0
 libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)
 mode change 100644 => 100755 libensemble/tests/scaling_tests/forces/summit_submit_mproc.sh

diff --git a/docs/platforms/example_scripts.rst b/docs/platforms/example_scripts.rst
index 8fa2f63ac..4af97bc74 100644
--- a/docs/platforms/example_scripts.rst
+++ b/docs/platforms/example_scripts.rst
@@ -26,8 +26,8 @@ Blues
     :caption: /examples/job_submission_scripts/blues_script.pbs
     :language: bash
 
-Theta - On MOM nodes with multiprocessing
------------------------------------
+Theta - On MOM node with multiprocessing
+----------------------------------------
 
 ..  literalinclude:: ../../examples/job_submission_scripts/theta_submit_mproc.sh
     :caption: /examples/job_submission_scripts/theta_submit_mproc.sh
diff --git a/libensemble/tests/scaling_tests/forces/summit_submit_mproc.sh b/libensemble/tests/scaling_tests/forces/summit_submit_mproc.sh
old mode 100644
new mode 100755
diff --git a/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh b/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh
index f79e5e2a7..c0d437cf0 100755
--- a/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh
+++ b/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh
@@ -92,7 +92,7 @@ balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1
 if [[ $LIBE_PLOTS = "true" ]]; then
   python $PLOT_DIR/plot_libe_calcs_util_v_time.py
   python $PLOT_DIR/plot_libe_runs_util_v_time.py
-  python $PLOT_DIR/plot_libe_histogram.pyfi
+  python $PLOT_DIR/plot_libe_histogram.py
 
 if [[ $BALSAM_PLOTS = "true" ]]; then
 #   export MPLBACKEND=TkAgg

From 6ae6059d5799ec95abd34497f9b8eb496a58d7ef Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 27 Nov 2019 12:27:59 -0600
Subject: [PATCH 620/644] Update CONTRIBUTING.rst to cover fork option

---
 CONTRIBUTING.rst | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 86d20f1fc..921745e9e 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -7,7 +7,10 @@ Contributions may be made via GitHub pull request to:
 
 libEnsemble uses the Gitflow model. Contributors should branch from, and
 make pull requests to, the develop branch. The master branch is used only
-for releases. Code should pass flake8 tests, allowing for the exceptions
+for releases. Pull requests may be made from a fork, for those without
+repository write access.
+
+Code should pass flake8 tests, allowing for the exceptions
 given in the flake8_ file in the project directory.
 
 Issues can be raised at:

From 5a0fe99a82feca68b9927663eb1a9141c6e0e642 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 27 Nov 2019 13:16:32 -0600
Subject: [PATCH 621/644] Add v0.6.0 release notes

---
 CHANGELOG.rst | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 9d268c86a..2f37a8433 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -2,6 +2,41 @@
 Release Notes
 =============
 
+
+Release 0.6.0
+-------------
+
+:Date: November 27, 2019
+
+API changes:
+
+* sim/gen/alloc_specs options that do not directly involve these routines are moved to libE_specs (see docs) (#266, #269)
+* sim/gen/alloc_specs now require user defined attributes to be added under a user field (see docs and examples) (#266, #269).
+* Addition of a utils module to help users create calling scripts. Includes an argument parser and utility functions (#308).
+* check_inputs() function is moved to the utils module (#308).
+* The libE_specs option ``nprocesses`` has been changed to ``nworkers`` (#235)
+
+New example functions:
+
+* Addition of a new persistent APOSMM generator function (#217).
+
+Other changes:
+
+* Overhaul of documentation, including HPC platform guides and a new pdf structure (inc. #232, #282)
+* Addition of OpenMP threading and GPU support to forces test (#250).
+* Balsam job_controller now tested on Travis (#47)
+
+:Note:
+
+* Tested platforms include: Linux, MacOS, Theta (Cray XC40/Cobalt), Summit (IBM Power9/LSF), Bebop (Cray CS400/Slurm), Cori (Cray XC40/Slurm).
+* Tested Python versions: (Cpython) 3.5, 3.6, 3.7
+
+:Known issues:
+
+* These are unchanged from v0.5.0
+* A known issues section has now been added to documentation.
+
+
 Release 0.5.2
 -------------
 
@@ -44,6 +79,7 @@ Release 0.5.1
 
 * These are unchanged from v0.5.0
 
+
 Release 0.5.0
 -------------
 

From 04e303cb0910751d54285618f8b973abfa865a60 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 27 Nov 2019 13:26:06 -0600
Subject: [PATCH 622/644] Update version number to v0.6.0

---
 README.rst              | 2 +-
 docs/conf.py            | 4 ++--
 libensemble/__init__.py | 2 +-
 setup.py                | 2 +-
 4 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/README.rst b/README.rst
index bb473a6be..6b88a43a3 100644
--- a/README.rst
+++ b/README.rst
@@ -210,7 +210,7 @@ Resources
                    David Bindel and John-Luke Navarro},
     title       = {{libEnsemble} Users Manual},
     institution = {Argonne National Laboratory},
-    number      = {Revision 0.5.2},
+    number      = {Revision 0.6.0},
     year        = {2019},
     url         = {https://buildmedia.readthedocs.org/media/pdf/libensemble/latest/libensemble.pdf}
   }
diff --git a/docs/conf.py b/docs/conf.py
index 32ba4367e..d1f26d8c4 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -99,9 +99,9 @@ def __getattr__(cls, name):
 # built documents.
 #
 # The short X.Y version.
-version = '0.5.2'
+version = '0.6.0'
 # The full version, including alpha/beta/rc tags.
-release = '0.5.2'
+release = '0.6.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/libensemble/__init__.py b/libensemble/__init__.py
index c4a9bdf34..317d863e4 100644
--- a/libensemble/__init__.py
+++ b/libensemble/__init__.py
@@ -4,7 +4,7 @@
 Library to coordinate the concurrent evaluation of dynamic ensembles of calculations.
 """
 
-__version__ = "0.5.2"
+__version__ = "0.6.0"
 __author__ = 'Jeffrey Larson, Stephen Hudson, Stefan M. Wild, David Bindel and John-Luke Navarro'
 __credits__ = 'Argonne National Laboratory'
 
diff --git a/setup.py b/setup.py
index e8c6236ef..a2087d11e 100644
--- a/setup.py
+++ b/setup.py
@@ -30,7 +30,7 @@ def run_tests(self):
 
 setup(
     name='libensemble',
-    version='0.5.2',
+    version='0.6.0',
     description='Library to coordinate the concurrent evaluation of dynamic ensembles of calculations',
     url='https://github.com/Libensemble/libensemble',
     author='Jeffrey Larson, Stephen Hudson, Stefan M. Wild, David Bindel and John-Luke Navarro',

From 3d614f1d91e365dd7577ed86807f182098d61d59 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 27 Nov 2019 15:11:18 -0600
Subject: [PATCH 623/644] Slight re-wording

---
 CHANGELOG.rst | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 2f37a8433..32bf21497 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -2,7 +2,6 @@
 Release Notes
 =============
 
-
 Release 0.6.0
 -------------
 
@@ -11,14 +10,14 @@ Release 0.6.0
 API changes:
 
 * sim/gen/alloc_specs options that do not directly involve these routines are moved to libE_specs (see docs) (#266, #269)
-* sim/gen/alloc_specs now require user defined attributes to be added under a user field (see docs and examples) (#266, #269).
+* sim/gen/alloc_specs now require user-defined attributes to be added under the 'user' field (see docs and examples) (#266, #269).
 * Addition of a utils module to help users create calling scripts. Includes an argument parser and utility functions (#308).
 * check_inputs() function is moved to the utils module (#308).
 * The libE_specs option ``nprocesses`` has been changed to ``nworkers`` (#235)
 
 New example functions:
 
-* Addition of a new persistent APOSMM generator function (#217).
+* Addition of a persistent APOSMM generator function (#217).
 
 Other changes:
 
@@ -34,8 +33,7 @@ Other changes:
 :Known issues:
 
 * These are unchanged from v0.5.0
-* A known issues section has now been added to documentation.
-
+* A known issues section has now been added to the documentation.
 
 Release 0.5.2
 -------------
@@ -79,7 +77,6 @@ Release 0.5.1
 
 * These are unchanged from v0.5.0
 
-
 Release 0.5.0
 -------------
 

From d606b26a405e313149ab28238fbd1b33aa393a2f Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 27 Nov 2019 17:18:48 -0600
Subject: [PATCH 624/644] Update link to user_guide

---
 README.rst                  | 2 +-
 docs/introduction_latex.rst | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.rst b/README.rst
index 6b88a43a3..ca282940f 100644
--- a/README.rst
+++ b/README.rst
@@ -241,5 +241,5 @@ Resources
 .. _SWIG: http://swig.org/
 .. _tarball: https://github.com/Libensemble/libensemble/releases/latest
 .. _Travis CI: https://travis-ci.org/Libensemble/libensemble
-.. _user guide: https://libensemble.readthedocs.io/en/latest/user_guide.html
+.. _user guide: https://libensemble.readthedocs.io/en/latest
 .. _xSDK Extreme-scale Scientific Software Development Kit: https://xsdk.info
diff --git a/docs/introduction_latex.rst b/docs/introduction_latex.rst
index fd02676cb..d82c1cac0 100644
--- a/docs/introduction_latex.rst
+++ b/docs/introduction_latex.rst
@@ -43,5 +43,5 @@ Quickstart Guide
 .. _SWIG: http://swig.org/
 .. _tarball: https://github.com/Libensemble/libensemble/releases/latest
 .. _Travis CI: https://travis-ci.org/Libensemble/libensemble
-.. _user guide: https://libensemble.readthedocs.io/en/latest/user_guide.html
+.. _user guide: https://libensemble.readthedocs.io/en/latest
 .. _xSDK Extreme-scale Scientific Software Development Kit: https://xsdk.info
\ No newline at end of file

From 4f0849cd1770f707090fb870484ec693bc641f0d Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 29 Nov 2019 15:21:39 -0600
Subject: [PATCH 625/644] Removing two flake8 checks

---
 .flake8                                                      | 4 ----
 libensemble/tests/balsam_tests/setup_balsam_tests.py         | 3 ++-
 libensemble/tests/balsam_tests/test_balsam_1__runjobs.py     | 3 ++-
 libensemble/tests/balsam_tests/test_balsam_2__workerkill.py  | 3 ++-
 libensemble/tests/balsam_tests/test_balsam_3__managerkill.py | 3 ++-
 5 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/.flake8 b/.flake8
index 6f4334ab3..e4c9b7033 100644
--- a/.flake8
+++ b/.flake8
@@ -20,12 +20,8 @@ exclude =
         # Keeping bad python format to match PETSc source code
         libensemble/sim_funcs/chwirut1.py
         examples/sim_funcs/chwirut1.py
-        # This is not implemented yet
-        controller_tests/test_jobcontroller_manager_poll.py
         # Not checking these scripts yet
         postproc_scripts
-        # Do not check these experimental tests
-        balsam_tests
 
 # Note that you can use wildcard exceptions with something such as
 # libensemble/libensemble/tests/regression_tests/*:F401
diff --git a/libensemble/tests/balsam_tests/setup_balsam_tests.py b/libensemble/tests/balsam_tests/setup_balsam_tests.py
index 2e90e66db..07e0ffd5b 100755
--- a/libensemble/tests/balsam_tests/setup_balsam_tests.py
+++ b/libensemble/tests/balsam_tests/setup_balsam_tests.py
@@ -35,7 +35,8 @@ def run_cmd(cmd, echo=False):
         print("\nRunning %s ...\n" % cmd)
     try:
         subprocess.run(cmd.split(), check=True)
-    except:
+    except Exception as e:
+        print(e)
         raise("Error: Command %s failed to run" % cmd)
 
 
diff --git a/libensemble/tests/balsam_tests/test_balsam_1__runjobs.py b/libensemble/tests/balsam_tests/test_balsam_1__runjobs.py
index 282e950ad..7cf4eaca0 100644
--- a/libensemble/tests/balsam_tests/test_balsam_1__runjobs.py
+++ b/libensemble/tests/balsam_tests/test_balsam_1__runjobs.py
@@ -30,7 +30,8 @@ def poll_until_state(job, state, timeout_sec=60.0, delay=2.0):
     if not os.path.isdir(sim_path):
         try:
             os.mkdir(sim_path)
-        except:
+        except Exception as e:
+            print(e)
             raise("Cannot make simulation directory %s" % sim_path)
 MPI.COMM_WORLD.Barrier()  # Ensure output dir created
 
diff --git a/libensemble/tests/balsam_tests/test_balsam_2__workerkill.py b/libensemble/tests/balsam_tests/test_balsam_2__workerkill.py
index 6eeea7ba5..97d0b1de3 100644
--- a/libensemble/tests/balsam_tests/test_balsam_2__workerkill.py
+++ b/libensemble/tests/balsam_tests/test_balsam_2__workerkill.py
@@ -32,7 +32,8 @@ def poll_until_state(job, state, timeout_sec=120.0, delay=2.0):
     if not os.path.isdir(sim_path):
         try:
             os.mkdir(sim_path)
-        except:
+        except Exception as e:
+            print(e)
             raise("Cannot make simulation directory %s" % sim_path)
 MPI.COMM_WORLD.Barrier()  # Ensure output dir created
 
diff --git a/libensemble/tests/balsam_tests/test_balsam_3__managerkill.py b/libensemble/tests/balsam_tests/test_balsam_3__managerkill.py
index 3fc887264..257ac6569 100644
--- a/libensemble/tests/balsam_tests/test_balsam_3__managerkill.py
+++ b/libensemble/tests/balsam_tests/test_balsam_3__managerkill.py
@@ -32,7 +32,8 @@ def poll_until_state(job, state, timeout_sec=120.0, delay=2.0):
     if not os.path.isdir(sim_path):
         try:
             os.mkdir(sim_path)
-        except:
+        except Exception as e:
+            print(e)
             raise("Cannot make simulation directory %s" % sim_path)
 MPI.COMM_WORLD.Barrier()  # Ensure output dir created
 

From b4bdff28b3668e460c2d796babd53cff37233187 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Fri, 29 Nov 2019 18:29:45 -0600
Subject: [PATCH 626/644] Having these tests be as close as possible. (Not sure
 why slight differences.)

---
 libensemble/tests/balsam_tests/test_balsam_2__workerkill.py  | 3 ---
 libensemble/tests/balsam_tests/test_balsam_3__managerkill.py | 2 --
 2 files changed, 5 deletions(-)

diff --git a/libensemble/tests/balsam_tests/test_balsam_2__workerkill.py b/libensemble/tests/balsam_tests/test_balsam_2__workerkill.py
index 97d0b1de3..e109ed0be 100644
--- a/libensemble/tests/balsam_tests/test_balsam_2__workerkill.py
+++ b/libensemble/tests/balsam_tests/test_balsam_2__workerkill.py
@@ -37,10 +37,8 @@ def poll_until_state(job, state, timeout_sec=120.0, delay=2.0):
             raise("Cannot make simulation directory %s" % sim_path)
 MPI.COMM_WORLD.Barrier()  # Ensure output dir created
 
-
 print("Host job rank is %d Output dir is %s" % (myrank, sim_dir))
 
-
 start = time.time()
 for sim_id in range(steps):
     jobname = 'outfile_t2_' + 'for_sim_id_' + str(sim_id) + '_ranks_' + str(myrank) + '.txt'
@@ -53,7 +51,6 @@ def poll_until_state(job, state, timeout_sec=120.0, delay=2.0):
                               ranks_per_node=8,
                               stage_out_url="local:" + sim_path,
                               stage_out_files=jobname + ".out")
-
     if sim_id == 1:
         dag.kill(current_job)
 
diff --git a/libensemble/tests/balsam_tests/test_balsam_3__managerkill.py b/libensemble/tests/balsam_tests/test_balsam_3__managerkill.py
index 257ac6569..8b3ed000e 100644
--- a/libensemble/tests/balsam_tests/test_balsam_3__managerkill.py
+++ b/libensemble/tests/balsam_tests/test_balsam_3__managerkill.py
@@ -39,7 +39,6 @@ def poll_until_state(job, state, timeout_sec=120.0, delay=2.0):
 
 print("Host job rank is %d Output dir is %s" % (myrank, sim_dir))
 
-
 start = time.time()
 for sim_id in range(steps):
     jobname = 'outfile_t3_' + 'for_sim_id_' + str(sim_id) + '_ranks_' + str(myrank) + '.txt'
@@ -81,6 +80,5 @@ def poll_until_state(job, state, timeout_sec=120.0, delay=2.0):
     else:
         print("Job not completed: %s rank=%d  time=%f Status" % (jobname, myrank, time.time()-start), current_job.state)
 
-
 end = time.time()
 print("Done: rank=%d  time=%f" % (myrank, end-start))

From 1bb3144700cb8c1fb5865308ec565a8886da65e2 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Sun, 1 Dec 2019 08:29:12 -0600
Subject: [PATCH 627/644] Whitespace adding 'Email mailing list' to release
 process

---
 .travis.yml                                        | 12 ------------
 conda/run_travis_locally/readme.md                 |  7 -------
 docs/conf.py                                       | 14 +++++++++-----
 .../release_management/release_process.rst         |  2 ++
 .../job_submission_scripts/bebop_submit_slurm.sh   |  1 -
 .../bebop_submit_slurm_centralmode.sh              |  1 -
 libensemble/tests/run-tests.sh                     |  8 --------
 libensemble/tests/scaling_tests/forces/readme.md   |  4 ----
 .../scaling_tests/forces/theta_submit_balsam.sh    |  1 -
 9 files changed, 11 insertions(+), 39 deletions(-)

diff --git a/.travis.yml b/.travis.yml
index 8f2a2f793..f9953b8f1 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -6,10 +6,8 @@ python:
   - 3.6
   - 3.7
 
-
 os: linux
 
-
 env:
   global:
     - HYDRA_LAUNCHER=fork
@@ -17,7 +15,6 @@ env:
   matrix:
     - MPI=mpich
 
-
 matrix:
   include:
     - os: osx
@@ -26,16 +23,13 @@ matrix:
       language: generic
       python: 3.7
 
-
 services:
     - postgresql
 
-
 cache:
   pip: true
   apt: true
 
-
 before_install:
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
       wget https://repo.continuum.io/miniconda/Miniconda3-4.7.10-MacOSX-x86_64.sh -O miniconda.sh;
@@ -55,7 +49,6 @@ before_install:
     fi
   - source activate condaenv
 
-
 install:
   - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then
         COMPILERS=clang_osx-64;
@@ -81,25 +74,20 @@ install:
   - mkdir ../balsam; tar xf 0.3.5.1.tar.gz -C ../balsam;
   - python conda/install-balsam.py
 
-
 before_script:
   - flake8 libensemble
   - echo "export BALSAM_DB_PATH=~/test-balsam" > setbalsampath.sh
   - source setbalsampath.sh # Imperfect method for env var persist after setup
   - ulimit -Sn 10000   # More concurrent file descriptors (for persis aposmm)
 
-
-
 # Run test (-z show output)
 script:
   - ./libensemble/tests/run-tests.sh -z
 
-
 # Track code coverage
 after_success:
   - mv libensemble/tests/.cov* .
   - coveralls
 
-
 after_failure:
 - cat libensemble/tests/regression_tests/log.err
diff --git a/conda/run_travis_locally/readme.md b/conda/run_travis_locally/readme.md
index c0476c606..23cb3c75e 100644
--- a/conda/run_travis_locally/readme.md
+++ b/conda/run_travis_locally/readme.md
@@ -33,7 +33,6 @@ Add user name to docker group so dont need sudo before docker:
     su - ${USER}
     id -nG # Confirm username added to docker users
 
-
 ### Install Travis Image for Python and create a container
 
 Name your new travis container:
@@ -52,7 +51,6 @@ $CONTAINER is the name you are assigning to the new container made from the imag
 
 Alternative travisCI docker images can be found [here](https://hub.docker.com/r/travisci/ci-garnet/tags/).
 
-
 ### Start a shell session in the container
 
 Then open a shell in running container:
@@ -61,7 +59,6 @@ Then open a shell in running container:
 
 Prompt should say travis@ rather than root@:
 
-
 ### Build and run libEnsemble for a given Python version
 
 You now want to copy the latest build script to the container and run it.
@@ -69,7 +66,6 @@ You now want to copy the latest build script to the container and run it.
 The default build script is build_mpich_libE.sh. If this is not up to date, check
 the installs against .travis.yml in the top level libEnsemble package directory.
 
-
 #### Copy build script from host system to the running container
 
 Run the following **from your host machine environment**. This copies the given file into an existing
@@ -82,7 +78,6 @@ On the docker side you may need to set ownership of the script:
 
     chown travis:travis /home/travis/build_mpich_libE.sh
 
-
 #### Run the libEnsemble build-and-run script
 
 Now, in the docker container, become user travis:
@@ -102,7 +97,6 @@ be left in the same environment for debugging. The script should stop running if
 
 If the conda output is too verbose, remove the "set -x" line in the script.
 
-
 ### Saving images from built containers and re-starting containers
 
 To exit the container session (client).
@@ -153,7 +147,6 @@ You can restart from your new image with docker run and docker exec or to run se
 
 where <user_name>/<image_name> is as used above to save (or from first column in "docker images" output).
 
-
 ### Notes
 
 The CPU cores available will be all those on your machine, not just what Travis supports.
diff --git a/docs/conf.py b/docs/conf.py
index d1f26d8c4..a56d6389a 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -180,11 +180,15 @@ def __getattr__(cls, name):
     \protected\def\sphinxcrossref#1{\texttt{#1}}
 
     \newsavebox\mytempbox
-\definecolor{sphinxnoteBgColor}{RGB}{221,233,239}
-\renewenvironment{sphinxnote}[1]
-   {\begin{lrbox}{\mytempbox}\begin{minipage}{\columnwidth}%
-    \begin{sphinxlightbox}\sphinxstrong{#1} }
-   {\end{sphinxlightbox}\end{minipage}\end{lrbox}%
+    \definecolor{sphinxnoteBgColor}{RGB}{221,233,239}
+    \renewenvironment{sphinxnote}[1]{%
+    \begin{lrbox}{\mytempbox}%
+    \begin{minipage}{\columnwidth}%
+    \begin{sphinxlightbox}%
+    \sphinxstrong{#1}}%
+    {\end{sphinxlightbox}%
+    \end{minipage}%
+    \end{lrbox}%
     \colorbox{sphinxnoteBgColor}{\usebox{\mytempbox}}}
                 ''',
     # The paper size ('letterpaper' or 'a4paper').
diff --git a/docs/dev_guide/release_management/release_process.rst b/docs/dev_guide/release_management/release_process.rst
index 54c062e94..6094953ed 100644
--- a/docs/dev_guide/release_management/release_process.rst
+++ b/docs/dev_guide/release_management/release_process.rst
@@ -56,3 +56,5 @@ After release
 -------------
 
 - Ensure all relevant GitHub issues are closed and moved to the *Done* column on the kanban project board (inc. the release checklist).
+
+- Email libEnsemble mailing list
diff --git a/examples/job_submission_scripts/bebop_submit_slurm.sh b/examples/job_submission_scripts/bebop_submit_slurm.sh
index fa2e07a18..c80c2ee07 100644
--- a/examples/job_submission_scripts/bebop_submit_slurm.sh
+++ b/examples/job_submission_scripts/bebop_submit_slurm.sh
@@ -20,7 +20,6 @@ unset I_MPI_FABRICS
 export I_MPI_FABRICS_LIST=tmi,tcp
 export I_MPI_FALLBACK=1
 
-
 #If using in calling script (After N mins manager kills workers and timing.dat created.)
 export LIBE_WALLCLOCK=55
 
diff --git a/examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh b/examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
index 700a8da06..58321c120 100644
--- a/examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
+++ b/examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
@@ -18,7 +18,6 @@
 
 #Currently requires even distribution - either multiple workers per node or nodes per worker
 
-
 #User to edit these variables
 export EXE=libE_calling_script.py
 export NUM_WORKERS=4
diff --git a/libensemble/tests/run-tests.sh b/libensemble/tests/run-tests.sh
index a481b6098..fd582fc1a 100755
--- a/libensemble/tests/run-tests.sh
+++ b/libensemble/tests/run-tests.sh
@@ -163,7 +163,6 @@ cleanup() {
 
 #-----------------------------------------------------------------------------------------
 
-
 #Parse Options
 #set -x
 
@@ -279,7 +278,6 @@ if [[ $root_found == "false" ]]; then
   done
 fi;
 
-
 if [ $CLEAN_ONLY = "true" ]; then
   if [ "$root_found" = true ]; then
     cleanup
@@ -329,8 +327,6 @@ if [ $RUN_COV_TESTS = "true" ]; then
    #COV_LINE_PARALLEL='-m coverage run --branch --parallel-mode'
 fi;
 
-
-
 if [ "$root_found" = true ]; then
 
   #Running without subdirs - delete any leftover output and coverage data files
@@ -368,7 +364,6 @@ if [ "$root_found" = true ]; then
   fi;
   cd $ROOT_DIR/
 
-
   # Run Regression Tests -----------------------------------------------------------------
 
   if [ "$RUN_REG_TESTS" = true ]; then
@@ -501,7 +496,6 @@ if [ "$root_found" = true ]; then
 
     # ********* End Loop over regression tests *********
 
-
     cd $ROOT_DIR/$REG_TEST_SUBDIR
 
     #Create Coverage Reports ----------------------------------------------
@@ -547,7 +541,6 @@ if [ "$root_found" = true ]; then
       fi;
     fi;
 
-
     #All reg tests - summary ----------------------------------------------
     if [ "$code" -eq "0" ]; then
       echo
@@ -585,7 +578,6 @@ if [ "$root_found" = true ]; then
 
   fi; #$RUN_REG_TESTS
 
-
   # Run Code standards Tests -----------------------------------------
   cd $ROOT_DIR
   if [ "$RUN_PEP_TESTS" = true ]; then
diff --git a/libensemble/tests/scaling_tests/forces/readme.md b/libensemble/tests/scaling_tests/forces/readme.md
index 2ab01d893..7cd166e32 100644
--- a/libensemble/tests/scaling_tests/forces/readme.md
+++ b/libensemble/tests/scaling_tests/forces/readme.md
@@ -5,7 +5,6 @@ Naive Electostatics Code Test
 This is designed only as an artificial, highly conifurable test
 code for a libEnsemble sim func.
 
-
 ### Forces Mini-App
 
 A system of charged particles is set up and simulated over a number of time-steps.
@@ -21,7 +20,6 @@ To run forces as a standalone executable on N procs:
 
     mpirun -np N ./forces.x <NUM_PARTICLES> <NUM_TIMESTEPS> <SEED>
 
-
 ### Running with libEnsemble.
 
 A random sample of seeds is taken and used as imput to the sim func (forces miniapp).
@@ -45,7 +43,6 @@ To remove output before the next run:
 
     ./cleanup.sh
 
-
 ### Running with Balsam
 
 To run with balsam, set `USE_MPI = True` and `USE_BALSAM = True` in `run_libe_forces.py`.
@@ -61,7 +58,6 @@ While the key output files will be copied back to the run dir at completion. Als
 the log in `<DIR>/log` if there are any issues. To run on batch systems, see the example
 scripts such as `theta_submit_balsam.sh`.
 
-
 ### Using batch scripts
 
 The scripts are set up assuming a conda environment. To use script directly you will need to replace the following templated values:
diff --git a/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh b/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh
index c0d437cf0..12531f5a5 100755
--- a/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh
+++ b/libensemble/tests/scaling_tests/forces/theta_submit_balsam.sh
@@ -77,7 +77,6 @@ RANKS_PER_NODE=64
 # All jobs
 OUT_FILES_TO_RETURN="*.out *.txt *.log"
 
-
 balsam app --name $SCRIPT_BASENAME.app --exec $EXE --desc "Run $SCRIPT_BASENAME"
 
 balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --args $SCRIPT_ARGS --wall-time-minutes $LIBE_WALLCLOCK --num-nodes $NUM_NODES --ranks-per-node $RANKS_PER_NODE --url-out="local:/$THIS_DIR" --stage-out-files="${OUT_FILES_TO_RETURN}" --url-in="local:/$THIS_DIR/*" --yes

From 34726dcd39902bb5188a2de3d70c52680a0ed43f Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Sun, 1 Dec 2019 20:05:14 -0600
Subject: [PATCH 628/644] Update rst_formatting_guidelines

---
 docs/rst_formatting_guidelines | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/docs/rst_formatting_guidelines b/docs/rst_formatting_guidelines
index bedb5707f..22ecd7a3d 100644
--- a/docs/rst_formatting_guidelines
+++ b/docs/rst_formatting_guidelines
@@ -14,8 +14,3 @@ Put breakout code snippets into a box using two colons ::
 No italics on text of links
 
 Use italics for emphasis
-
-
-* Unfortunately, the Sphinx crossrefs (e.g., :doc:`ref`) are different then
-* hrefs, and they are italicized in the pdf. I assume there is a way to change
-* this formatting, but I couldn't find it.

From dabca2e2632a81a319bb29ad21847154fe420492 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Sun, 1 Dec 2019 20:25:55 -0600
Subject: [PATCH 629/644] Trying this out

---
 docs/FAQ.rst                                  |  3 +-
 docs/data_structures/calc_status.rst          | 10 ++-
 docs/data_structures/work_dict.rst            |  7 +-
 .../release_platforms/rel_spack.rst           | 10 +--
 .../release_management/release_process.rst    | 12 ++--
 docs/job_controller/jc_index.rst              |  4 +-
 docs/job_controller/job_controller.rst        | 14 ++--
 docs/job_controller/mpi_controller.rst        |  8 ++-
 docs/rst_formatting_guidelines                |  1 -
 docs/tutorials/local_sine_tutorial.rst        | 12 ++--
 .../balsam_tests/readme.balsam_tests.txt      | 12 +++-
 libensemble/tests/balsam_tests/readme.rst     | 64 +++++++++++++------
 libensemble/tests/controller_tests/readme.txt |  9 ++-
 .../standalone_tests/comms_test/readme.txt    | 13 +++-
 .../kill_test/log.autotest.txt                |  4 +-
 postproc_scripts/readme.rst                   | 28 ++++++--
 16 files changed, 152 insertions(+), 59 deletions(-)

diff --git a/docs/FAQ.rst b/docs/FAQ.rst
index cf27eac86..d8408e690 100644
--- a/docs/FAQ.rst
+++ b/docs/FAQ.rst
@@ -145,7 +145,8 @@ There are several ways to address this nuisance, but all involve trial and error
 An easy (but insecure) solution is temporarily disabling the Firewall through
 System Preferences -> Security & Privacy -> Firewall -> Turn Off Firewall. Alternatively,
 adding a Firewall "Allow incoming connections" rule can be attempted for the offending
-Job Controller executable. We've had limited success running ``sudo codesign --force --deep --sign - /path/to/application.app``
+Job Controller executable. We've had limited success running 
+``sudo codesign --force --deep --sign - /path/to/application.app``
 on our Job Controller executables, then confirming the next alerts for the executable
 and ``mpiexec.hydra``.
 
diff --git a/docs/data_structures/calc_status.rst b/docs/data_structures/calc_status.rst
index 2091f1246..565ca9b93 100644
--- a/docs/data_structures/calc_status.rst
+++ b/docs/data_structures/calc_status.rst
@@ -3,7 +3,15 @@
 calc_status
 ===========
 
-The ``calc_status`` is an integer attribute with named (enumerated) values and a corresponding description that can be used in :ref:`sim_f<api_sim_f>` or :ref:`gen_f<api_gen_f>` functions to capture the status of a calcuation. This is returned to the manager and printed to the ``libE_stats.txt`` file. Only the status values ``FINISHED_PERSISTENT_SIM_TAG`` and ``FINISHED_PERSISTENT_GEN_TAG`` are currently used by the manager,  but others can still provide a useful summary in libE_stats.txt. The user determines the status of the calculation, as it could include multiple application runs. It can be added as a third return variable in sim_f or gen_f functions.
+The ``calc_status`` is an integer attribute with named (enumerated) values and
+a corresponding description that can be used in :ref:`sim_f<api_sim_f>` or
+:ref:`gen_f<api_gen_f>` functions to capture the status of a calcuation. This
+is returned to the manager and printed to the ``libE_stats.txt`` file. Only the
+status values ``FINISHED_PERSISTENT_SIM_TAG`` and
+``FINISHED_PERSISTENT_GEN_TAG`` are currently used by the manager,  but others
+can still provide a useful summary in libE_stats.txt. The user determines the
+status of the calculation, as it could include multiple application runs. It
+can be added as a third return variable in sim_f or gen_f functions.
 The calc_status codes are in the ``libensemble.message_numbers`` module.
 
 Example of ``calc_status`` used along with :ref:`job controller<jobcontroller_index>` in sim_f:
diff --git a/docs/data_structures/work_dict.rst b/docs/data_structures/work_dict.rst
index 14730b2e5..376992370 100644
--- a/docs/data_structures/work_dict.rst
+++ b/docs/data_structures/work_dict.rst
@@ -20,8 +20,11 @@ Dictionary with integer keys ``i`` and dictionary values to be given to worker `
         'persistent' [bool]: True if worker 'i' will enter persistent mode
 
 .. seealso::
-  For allocation functions giving Work dictionaries using persistent workers, see `start_only_persistent.py`_ or `start_persistent_local_opt_gens.py`_.
-  For a use case where the allocation and generator functions combine to do simulation evaluations with different resources (blocking some workers), see `test_6-hump_camel_with_different_nodes_uniform_sample.py`_.
+  For allocation functions giving Work dictionaries using persistent workers,
+  see `start_only_persistent.py`_ or `start_persistent_local_opt_gens.py`_.
+  For a use case where the allocation and generator functions combine to do
+  simulation evaluations with different resources (blocking some workers), see
+  `test_6-hump_camel_with_different_nodes_uniform_sample.py`_.
 
 .. _start_only_persistent.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_only_persistent.py
 .. _start_persistent_local_opt_gens.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py
diff --git a/docs/dev_guide/release_management/release_platforms/rel_spack.rst b/docs/dev_guide/release_management/release_platforms/rel_spack.rst
index c2f941461..598159b61 100644
--- a/docs/dev_guide/release_management/release_platforms/rel_spack.rst
+++ b/docs/dev_guide/release_management/release_platforms/rel_spack.rst
@@ -13,9 +13,11 @@ This assumes you have already:
 
 Details on how to create forks can be found at: https://help.github.com/articles/fork-a-repo
 
-You now have a configuration like shown in answer at: https://stackoverflow.com/questions/6286571/are-git-forks-actually-git-clones
+You now have a configuration like shown in answer at:
+https://stackoverflow.com/questions/6286571/are-git-forks-actually-git-clones
 
-Upstream, in this case, is the official Spack repository on GitHub. Origin is your fork on GitHub and Local Machine is your local clone (from your fork).
+Upstream, in this case, is the official Spack repository on GitHub. Origin is
+your fork on GitHub and Local Machine is your local clone (from your fork).
 
 Make sure ``SPACK_ROOT`` is set and spack binary is in your path::
 
@@ -37,8 +39,8 @@ To set upstream repo::
 Now to update (the main develop branch)
 ---------------------------------------
 
-You will now update your local machine from the upstream repo (if in doubt - make a copy of local repo
-in your filestystem before doing the following).
+You will now update your local machine from the upstream repo (if in doubt -
+make a copy of local repo in your filestystem before doing the following).
 
 Check upstream remote is present::
 
diff --git a/docs/dev_guide/release_management/release_process.rst b/docs/dev_guide/release_management/release_process.rst
index 6094953ed..71fb215b4 100644
--- a/docs/dev_guide/release_management/release_process.rst
+++ b/docs/dev_guide/release_management/release_process.rst
@@ -13,9 +13,11 @@ Before release
 
 - A release branch should be taken off develop (or develop pulls controlled).
 
-- Release notes for this version are added to the documentation with release date, including a list of supported (tested) platforms.
+- Release notes for this version are added to the documentation with release
+  date, including a list of supported (tested) platforms.
 
-- Version number is updated wherever it appears (in ``setup.py``, ``libensemble/__init__.py``, ``README.rst`` and twice in ``docs/conf.py``)
+- Version number is updated wherever it appears:
+  (in ``setup.py``, ``libensemble/__init__.py``, ``README.rst`` and twice in ``docs/conf.py``)
 
 - Check year is correct in ``README.rst`` under *Citing libEnsemble* and in ``docs/conf.py``.
 
@@ -31,7 +33,8 @@ Before release
 
   - Documentation must build and display correctly wherever hosted (currently readthedocs.com).
 
-- Pull request from either develop or release branch to master requesting reviewer/s (including at least one other administrator).
+- Pull request from either develop or release branch to master requesting
+  reviewer/s (including at least one other administrator).
 
 - Reviewer will check tests have passed and approve merge.
 
@@ -55,6 +58,7 @@ An administrator will take the following steps.
 After release
 -------------
 
-- Ensure all relevant GitHub issues are closed and moved to the *Done* column on the kanban project board (inc. the release checklist).
+- Ensure all relevant GitHub issues are closed and moved to the *Done* column
+  on the kanban project board (inc. the release checklist).
 
 - Email libEnsemble mailing list
diff --git a/docs/job_controller/jc_index.rst b/docs/job_controller/jc_index.rst
index 16bed80a8..28482b2da 100644
--- a/docs/job_controller/jc_index.rst
+++ b/docs/job_controller/jc_index.rst
@@ -3,7 +3,9 @@
 Job Controller
 ==============
 
-The job controller can be used within the simulator (and potentially generator) functions to provide a simple, portable interface for running and managing user jobs.
+The job controller can be used within the simulator (and potentially generator)
+functions to provide a simple, portable interface for running and managing user
+jobs.
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/job_controller/job_controller.rst b/docs/job_controller/job_controller.rst
index 2e6b59e50..113544498 100644
--- a/docs/job_controller/job_controller.rst
+++ b/docs/job_controller/job_controller.rst
@@ -18,9 +18,10 @@ See the controller APIs for optional arguments.
 Job Class
 ---------
 
-Jobs are created and returned though the job_controller launch function. Jobs can be polled and
-killed with the respective poll and kill functions. Job information can be queried through the job attributes
-below and the query functions. Note that the job attributes are only updated when they are
+Jobs are created and returned though the job_controller launch function. Jobs
+can be polled and killed with the respective poll and kill functions. Job
+information can be queried through the job attributes below and the query
+functions. Note that the job attributes are only updated when they are
 polled/killed (or through other job or job controller functions).
 
 .. autoclass:: Job
@@ -32,9 +33,12 @@ polled/killed (or through other job or job controller functions).
 Job Attributes
 --------------
 
-Following is a list of job status and configuration attributes that can be retrieved from a job.
+Following is a list of job status and configuration attributes that can be
+retrieved from a job.
 
-:NOTE: These should not be set directly. Jobs are launched by the job controller and job information can be queired through the job attributes below and the query functions.
+:NOTE: These should not be set directly. Jobs are launched by the job
+       controller and job information can be queired through the job attributes
+       below and the query functions.
 
 Job Status attributes include:
 
diff --git a/docs/job_controller/mpi_controller.rst b/docs/job_controller/mpi_controller.rst
index 70385d42b..fb1dd8670 100644
--- a/docs/job_controller/mpi_controller.rst
+++ b/docs/job_controller/mpi_controller.rst
@@ -22,7 +22,9 @@ See the controller API below for optional arguments.
 Class specific attributes
 -------------------------
 
-These attributes can be set directly to alter behaviour of the MPI job controller. However, they should be used with caution, as they may not be implemented in other job controllers.
+These attributes can be set directly to alter behaviour of the MPI job
+controller. However, they should be used with caution, as they may not be
+implemented in other job controllers.
 
 :max_launch_attempts: (int) Maximum number of launch attempts for a given job. *Default: 5*.
 :fail_time: (int) *Only if wait_on_run is set.* Maximum run-time to failure in seconds that results in re-launch. *Default: 2*.
@@ -33,4 +35,6 @@ Example. To increase resilience against launch failures::
     jobctrl.max_launch_attempts = 10
     jobctrl.fail_time = 5
 
-Note that an the re-try delay on launches starts at 5 seconds and increments by 5 seconds for each retry. So the 4th re-try will wait for 20 seconds before re-launching.
+Note that an the re-try delay on launches starts at 5 seconds and increments by
+5 seconds for each retry. So the 4th re-try will wait for 20 seconds before
+re-launching.
diff --git a/docs/rst_formatting_guidelines b/docs/rst_formatting_guidelines
index bedb5707f..862ae4556 100644
--- a/docs/rst_formatting_guidelines
+++ b/docs/rst_formatting_guidelines
@@ -1,4 +1,3 @@
-
 Put variables (e.g., gen_f or H) in between double ticks ``stuff here`` (no quotes)
 
 Put short code in between double ticks ``stuff here`` (no quotes)
diff --git a/docs/tutorials/local_sine_tutorial.rst b/docs/tutorials/local_sine_tutorial.rst
index 30a8beed6..a812a20bd 100644
--- a/docs/tutorials/local_sine_tutorial.rst
+++ b/docs/tutorials/local_sine_tutorial.rst
@@ -8,10 +8,14 @@ Multiprocessing.
 
 The foundation of writing libEnsemble routines is accounting for four components:
 
-    1. The generator function :ref:`gen_f<api_gen_f>`, which produces values for simulations.
-    2. The simulator function :ref:`sim_f<api_sim_f>`, which performs simulations based on values from ``gen_f``.
-    3. The allocation function :ref:`alloc_f<api_alloc_f>`, which decides which of the previous two functions should be called, when.
-    4. The calling script, which defines parameters and information about these functions and the libEnsemble task, then begins execution.
+    1. The generator function :ref:`gen_f<api_gen_f>`, which produces values
+           for simulations.
+    2. The simulator function :ref:`sim_f<api_sim_f>`, which performs
+           simulations based on values from ``gen_f``.
+    3. The allocation function :ref:`alloc_f<api_alloc_f>`, which decides which
+           of the previous two functions should be called, when.
+    4. The calling script, which defines parameters and information about these
+           functions and the libEnsemble task, then begins execution.
 
 libEnsemble initializes a *manager* process and as many *worker* processes as the
 user requests. The manager coordinates data-transfer between workers and assigns
diff --git a/libensemble/tests/balsam_tests/readme.balsam_tests.txt b/libensemble/tests/balsam_tests/readme.balsam_tests.txt
index fd19a9616..7e5b8b342 100644
--- a/libensemble/tests/balsam_tests/readme.balsam_tests.txt
+++ b/libensemble/tests/balsam_tests/readme.balsam_tests.txt
@@ -1,12 +1,18 @@
 List of balsam test jobs for libensemble.
 
 test_balsam_1__runjobs.py:
-Launches parallel parent job. Each task iterates over a loop launching sub-jobs and waiting for completion. Does 3 iterations by default.
+Launches parallel parent job. Each task iterates over a loop launching sub-jobs
+and waiting for completion. Does 3 iterations by default.
 
 test_balsam_2__workerkill.py:
 As first test but each top-level task kills its middle job.
 
 test_balsam_3__managerkill.py:
-Process 0 sends out a kill for jobs which include sim_id_1 in their name. This will kill any such jobs in the database at the time of the kill. Note that if a job has not yet been added to database at the time of the kill, it will still run.
+Process 0 sends out a kill for jobs which include sim_id_1 in their name. This
+will kill any such jobs in the database at the time of the kill. Note that if a
+job has not yet been added to database at the time of the kill, it will still
+run.
 
-Note that test3 exploits the fact that balsam is built on a django database, and all django functionality for manipulating the database can easily be exposed.
+Note that test3 exploits the fact that balsam is built on a django database,
+and all django functionality for manipulating the database can easily be
+exposed.
diff --git a/libensemble/tests/balsam_tests/readme.rst b/libensemble/tests/balsam_tests/readme.rst
index b809af293..4d60d668a 100644
--- a/libensemble/tests/balsam_tests/readme.rst
+++ b/libensemble/tests/balsam_tests/readme.rst
@@ -4,10 +4,14 @@ Using balsam
 
 Note: To set up balsam - see instructions on setting up in balsam docs.
 
-Currently this can be found in the docs/ subdirectory of the hpc-edge-service repo. The documentation is in Sphinx format.
+Currently this can be found in the docs/ subdirectory of the hpc-edge-service
+repo. The documentation is in Sphinx format.
 
 Theta:
-If the instructions are followed to set up a conda environment called balsam, then the script env_setup_theta.sh, under the balsam tests dir, can be sourced in future logins for theta. Or modified for other platforms. In some platforms you may need to only activate the balsam conda environment.
+If the instructions are followed to set up a conda environment called balsam,
+then the script env_setup_theta.sh, under the balsam tests dir, can be sourced
+in future logins for theta. Or modified for other platforms. In some platforms
+you may need to only activate the balsam conda environment.
 
 -----------------------------------------
 Quickstart - Balsam tests for libEnsemble
@@ -24,7 +28,8 @@ Go to balsam_tests dir run setup script:
   cd libensemble/code/tests/balsam_tests
   ./setup_balsam_tests.py
 
-This will register the applications and jobs in the database. If work_dir and sim_dir paths are ok in script, it can be run from anywhere.
+This will register the applications and jobs in the database. If work_dir and
+sim_dir paths are ok in script, it can be run from anywhere.
 
 **ii) Launch the jobs**
 
@@ -34,11 +39,14 @@ In an interactive session (or a batch script) run the launcher:
 
   balsam launcher --consume-all
 
-Note: You will need at least 2 nodes, one for parent job and one for user apps, if you are on a machine where the schedular does not split nodes. However, it is recommended that 5 nodes are used for good concurrency.
+Note: You will need at least 2 nodes, one for parent job and one for user apps,
+if you are on a machine where the schedular does not split nodes. However, it
+is recommended that 5 nodes are used for good concurrency.
 
 **iii) Output and reset**
 
-Output will go into test output dirs inside the balsam_tests dir - they will be created on first run.
+Output will go into test output dirs inside the balsam_tests dir - they will be
+created on first run.
 
 To quickly reset the tests to run again use the reset (python) script:
 
@@ -55,7 +63,8 @@ General Usage
 1. Register applications
 ------------------------
 
-You must register with balsam the parent application (eg. libEnsemble) and any user application (eg. sim funcs/gen funcs).
+You must register with balsam the parent application (eg. libEnsemble) and any
+user application (eg. sim funcs/gen funcs).
 This only need be done once - unless eg. name of application changes.
 
 Example (as used in tests) - run from within balsam_tests dir:
@@ -76,7 +85,8 @@ Register user application that will be called inside tests:
 
     balsam app --name helloworld --exec ../../examples/sim_funcs/helloworld.py  --desc "Run helloworld user app"
 
-Note: The --exec arg is the location of the script or exe, and can be absolute or relative path (the balsam app command will convert to fullpath).
+Note: The --exec arg is the location of the script or exe, and can be absolute
+or relative path (the balsam app command will convert to fullpath).
 
 To list apps:
 
@@ -93,7 +103,8 @@ To clean:
 2 Register job/s
 ----------------
 
-This is the job you intend to run. It will reference an application you have set up.
+This is the job you intend to run. It will reference an application you have
+set up.
 
 Eg. Set up job for test_balsam_1:
 
@@ -107,14 +118,25 @@ Where WORK_DIR is set to output dir for job.
                --wall-min 1 --num-nodes 1 --ranks-per-node 4
                --url-out="local:$WORK_DIR" --stage-out-files="job_test_balsam_1__runjobs*"
 
-A working directory is set up when the job is run - by default under the balsam space eg: hpc-edge-service/data/balsamjobs/ Under this directory a workflow directory is created (eg. libe_workflow in above case). From there, files to keep are staged out as specified by directory in --url-out (use local: for file directory). The files to stage out are specified by --stage-out-files.
+A working directory is set up when the job is run - by default under the balsam
+space eg: hpc-edge-service/data/balsamjobs/ Under this directory a workflow
+directory is created (eg. libe_workflow in above case). From there, files to
+keep are staged out as specified by directory in --url-out (use local: for file
+directory). The files to stage out are specified by --stage-out-files.
 A log will also be created when run under hpc-edge-service/log/
 
-The standard output will go to file <jobname>.out. So in above case this will be job_balsam1.out which will be staged out to $WORKDIR
+The standard output will go to file <jobname>.out. So in above case this will
+be job_balsam1.out which will be staged out to $WORKDIR
 
-In this case 4 ranks per node and 1 node are selected. This is for running on the parent application (e.g., libEnsemble). This does not constrain the running of sub-apps (eg. helloworld), which will use the full allocation available.
+In this case 4 ranks per node and 1 node are selected. This is for running on
+the parent application (e.g., libEnsemble). This does not constrain the running
+of sub-apps (eg. helloworld), which will use the full allocation available.
 
-Note that the user jobs (launched in a libEnsemble job) are registered from within the code. For staging out files, the output directory needs to somehow be accessible to the code. For the tests here, this is simply the directory of the test scripts (accessed via the __file__ variable in python). Search for dag.add_job in test scripts (eg. test_balsam_1__runjobs.py)
+Note that the user jobs (launched in a libEnsemble job) are registered from
+within the code. For staging out files, the output directory needs to somehow
+be accessible to the code. For the tests here, this is simply the directory of
+the test scripts (accessed via the __file__ variable in python). Search for
+dag.add_job in test scripts (eg. test_balsam_1__runjobs.py)
 
 To list jobs:
 
@@ -150,9 +172,11 @@ For other launcher options:
 
 A script to reset the tests is available: reset_balsam_tests.py
 
-This script can be modified easily. However, to reset from the command line - without removing and re-adding jobs you can do the following.
+This script can be modified easily. However, to reset from the command line -
+without removing and re-adding jobs you can do the following.
 
-Note: After running tests the balsam job database will contain something like the following (job_ids abbreviated for space):
+Note: After running tests the balsam job database will contain something like
+the following (job_ids abbreviated for space):
 
 .. code-block:: bash
 
@@ -186,7 +210,8 @@ To remove only the generated jobs you can just use a sub-string of the job name
     -----------------------------------------------------------------------------------------------------------------------
      29add031-8e7c-... | job_balsam1      | libe_workflow   | test_balsam_1    | [01-30-2018 18:57:47 JOB_FINISHED]
 
-To run again - change status attribute to READY (you need to specify job_id - an abbreviation is ok) eg:
+To run again - change status attribute to READY (you need to specify job_id -
+an abbreviation is ok) For example:
 
 .. code-block:: bash
 
@@ -203,11 +228,14 @@ Interactive sessions can be launched as:
 
   qsub -A <project_code> -n 5 -q debug-flat-quad -t 60 -I
 
-This would be a 60 minute interactive session with 5 nodes. You must have a project code.
+This would be a 60 minute interactive session with 5 nodes. You must have a
+project code.
 
-You will need to load the conda env in the interactive session - or source the script env_setup_theta.sh.
+You will need to load the conda env in the interactive session - or source the
+script env_setup_theta.sh.
 
-At time of writing theta does not log you out of interactive sessions. But jobs launched after time is up will not work.
+At time of writing theta does not log you out of interactive sessions. But jobs
+launched after time is up will not work.
 
 To see time remaining:
 
diff --git a/libensemble/tests/controller_tests/readme.txt b/libensemble/tests/controller_tests/readme.txt
index ef7459e8d..a043af374 100644
--- a/libensemble/tests/controller_tests/readme.txt
+++ b/libensemble/tests/controller_tests/readme.txt
@@ -24,7 +24,9 @@ For running with Balsam
 
 1. You must install Balsam (https://balsam.alcf.anl.gov/)
 
-2. For each time you start a new session: In this directory (controller_tests) initialise database and start the database server by sourcing script set.balsam.database.sh. You can modify the database location in the script.
+2. For each time you start a new session: In this directory (controller_tests)
+initialise database and start the database server by sourcing script
+set.balsam.database.sh. You can modify the database location in the script.
 
 > . set.balsam.database.sh
 
@@ -46,4 +48,7 @@ and:
 
 > balsam launcher --consume-all
 
-Note: On systems like Theta only one job can be launched per node. You will need at least 2 nodes. The first will run the parent script. The test test_jobcontroller_multi.py launches 3 sub-jobs which Balsam will launch as nodes become available. To run all 3 concurrently would require 4 nodes.
+Note: On systems like Theta only one job can be launched per node. You will
+need at least 2 nodes. The first will run the parent script. The test
+test_jobcontroller_multi.py launches 3 sub-jobs which Balsam will launch as
+nodes become available. To run all 3 concurrently would require 4 nodes.
diff --git a/libensemble/tests/standalone_tests/comms_test/readme.txt b/libensemble/tests/standalone_tests/comms_test/readme.txt
index 872667ae2..381009c89 100644
--- a/libensemble/tests/standalone_tests/comms_test/readme.txt
+++ b/libensemble/tests/standalone_tests/comms_test/readme.txt
@@ -1,13 +1,20 @@
 Comms test
 ==========
 
-This is a simplified standalone comms tests which is a very basic model of the communications in libensemble.
+This is a simplified standalone comms tests which is a very basic model of the
+communications in libensemble.
 
 The current test, only models the commuications from workers to manager.
 
-The test is easily configurable for size of data, rounds of communication, and can be run on any number of processors. The data is initailsed on each worker using the processor ID. The manager checks the correct values are received.
+The test is easily configurable for size of data, rounds of communication, and
+can be run on any number of processors. The data is initailsed on each worker
+using the processor ID. The manager checks the correct values are received.
 
-The data is a dictionary containing a scalar and numpy array. The size of the numpy array is given by <array_size>. The default is one million values. The variable <rounds> determines the number of messages sent from each worker. Two lines can be uncommented in the manager loop which gives the message count and size of the received message in bytes.
+The data is a dictionary containing a scalar and numpy array. The size of the
+numpy array is given by <array_size>. The default is one million values. The
+variable <rounds> determines the number of messages sent from each worker. Two
+lines can be uncommented in the manager loop which gives the message count and
+size of the received message in bytes.
 
 The test can also be used for benchmarking.
 
diff --git a/libensemble/tests/standalone_tests/kill_test/log.autotest.txt b/libensemble/tests/standalone_tests/kill_test/log.autotest.txt
index baeb7d0ab..5dc9c548f 100644
--- a/libensemble/tests/standalone_tests/kill_test/log.autotest.txt
+++ b/libensemble/tests/standalone_tests/kill_test/log.autotest.txt
@@ -3,7 +3,9 @@ Kill tests
 
 Launching MPI jobs which write at regular intervals to an output file (see sleep_and_print.c).
 
-This test launches a job, then kills after a few seconds, and then monitors file to see if output continues. If the first job is succesfully killed, a second is launched and the test repeated.
+This test launches a job, then kills after a few seconds, and then monitors
+file to see if output continues. If the first job is succesfully killed, a
+second is launched and the test repeated.
 
 Instructions
 ------------
diff --git a/postproc_scripts/readme.rst b/postproc_scripts/readme.rst
index 94d2d9ae1..3616bc8da 100644
--- a/postproc_scripts/readme.rst
+++ b/postproc_scripts/readme.rst
@@ -2,22 +2,36 @@
 Timing analysis scripts
 =======================
 
-Note that all plotting scripts produce a file rather than opening a plot interactively.
+Note that all plotting scripts produce a file rather than opening a plot
+interactively.
 
-The following scripts must be run in the directory with the **libE_stats.txt** file. They extract and plot information from that file.
+The following scripts must be run in the directory with the **libE_stats.txt**
+file. They extract and plot information from that file.
 
-* **plot_libe_calcs_util_v_time.py**: Extract worker utilization v time plot (with one second sampling). Shows number of workers running user sim or gen functions over time.
+* **plot_libe_calcs_util_v_time.py**: Extract worker utilization v time plot
+  (with one second sampling). Shows number of workers running user sim or gen
+  functions over time.
 
-* **plot_libe_runs_util_v_time.py**: Extract launched job utilization v time plot (with one second sampling). Shows number of workers with active jobs, launched via the job controller, over time.
+* **plot_libe_runs_util_v_time.py**: Extract launched job utilization v time
+  plot (with one second sampling). Shows number of workers with active jobs,
+  launched via the job controller, over time.
 
-* **plot_libe_histogram.py**: Create histogram showing the number of completed/killed/failed user calculations binned by run-time.
+* **plot_libe_histogram.py**: Create histogram showing the number of
+  completed/killed/failed user calculations binned by run-time.
 
 ========================
 Results analysis scripts
 ========================
 
-* **print_npy.py**: Prints to screen from a given ``*.npy`` file containing a numpy structured array. Use ``done`` to only print the lines containing *returned* points. Example::
+* **print_npy.py**: Prints to screen from a given ``*.npy`` file containing a
+  numpy structured array. Use ``done`` to only print the lines containing
+  *returned* points. Example::
 
     ./print_npy.py run_libe_forces_results_History_length=1000_evals=8.npy done
 
-* **compare_npy.py**: Compares either two provided ``*.npy`` files or one provided ``*.npy`` file with an expected results file (by default located at ../expected.npy). A tolerance is given on floating point results and NANs are compared as equal. Variable fields (such as those containing a time) are ignored. These fields may need to be modified depending on user's history array.
+* **compare_npy.py**: Compares either two provided ``*.npy`` files or one
+  provided ``*.npy`` file with an expected results file (by default located at
+  ../expected.npy). A tolerance is given on floating point results and NANs are
+  compared as equal. Variable fields (such as those containing a time) are
+  ignored. These fields may need to be modified depending on user's history
+  array.

From faf58001a081d532a005af098f847ef395f9d763 Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Mon, 2 Dec 2019 10:11:55 -0600
Subject: [PATCH 630/644] Again updating formatting guidelines

---
 docs/rst_formatting_guidelines | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/docs/rst_formatting_guidelines b/docs/rst_formatting_guidelines
index 22ecd7a3d..cc4b8c4a9 100644
--- a/docs/rst_formatting_guidelines
+++ b/docs/rst_formatting_guidelines
@@ -1,4 +1,3 @@
-
 Put variables (e.g., gen_f or H) in between double ticks ``stuff here`` (no quotes)
 
 Put short code in between double ticks ``stuff here`` (no quotes)
@@ -7,7 +6,7 @@ Put referenced file names in between double ticks ``stuff here`` (no quotes)
 
 Put environment variables in between double ticks ``stuff here`` (no quotes)
 
-Put warnings line: **WARNING:**
+Use .. note:: and .. warning:: directives
 
 Put breakout code snippets into a box using two colons ::
 

From 23d441163d8f0191b411c3ba260993ed6e6a07da Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 2 Dec 2019 12:15:37 -0600
Subject: [PATCH 631/644] First round of grammar adjustments

---
 docs/history_output.rst            | 11 +++--
 docs/job_controller/overview.rst   | 65 +++++++++++++++---------------
 docs/overview_usecases.rst         | 32 +++++++--------
 docs/platforms/platforms_index.rst | 14 +++----
 4 files changed, 60 insertions(+), 62 deletions(-)

diff --git a/docs/history_output.rst b/docs/history_output.rst
index 64cff7b55..3c4a57e92 100644
--- a/docs/history_output.rst
+++ b/docs/history_output.rst
@@ -1,12 +1,11 @@
 The History Array
 ~~~~~~~~~~~~~~~~~
 libEnsemble uses a NumPy structured array :ref:`H<datastruct-history-array>` to
-store output from ``gen_f`` and corresponding ``sim_f`` output. Similarly,
-``gen_f`` and ``sim_f`` are expected to return output in NumPy structured
-arrays. The names of the fields to be given as input to ``gen_f`` and ``sim_f``
-must be an output from ``gen_f`` or ``sim_f``. In addition to the fields output
-from ``sim_f`` and ``gen_f``, the final history returned from libEnsemble will
-include the following fields:
+store corresponding output from each ``gen_f`` and ``sim_f``. Similarly,
+``gen_f`` and ``sim_f`` are expected to return output as NumPy structured
+arrays. The names of the input fields for ``gen_f`` and ``sim_f``
+must be output from ``gen_f`` or ``sim_f``. In addition to the user-function output fields,
+the final history from libEnsemble will includes the following:
 
 * ``sim_id`` [int]: Each unit of work output from ``gen_f`` must have an
   associated ``sim_id``. The generator can assign this, but users must be
diff --git a/docs/job_controller/overview.rst b/docs/job_controller/overview.rst
index fa3c63748..c36e5bc97 100644
--- a/docs/job_controller/overview.rst
+++ b/docs/job_controller/overview.rst
@@ -1,38 +1,37 @@
 Job Controller Overview
 =======================
 
-Many users' will wish to launch an application to the system from a :ref:`sim_f<api_sim_f>`
-(or :ref:`gen_f<api_gen_f>`), running on a worker.
-
-An MPI job, for example, could be initialized with a subprocess call to ``mpirun``, or
-an alternative launcher such as ``aprun`` or ``jsrun``. The sim_f may then monitor this job,
-check output, and possibly kill the job. The word ``job`` is used here to represent
-a launch of an application to the system, where the system could be a supercomputer,
-cluster, or any other provision of compute resources.
-
-In order to remove the burden of system interaction from the user, and enable sim_f
-scripts that are portable between systems, a job_controller interface is provided by
-libEnsemble. The job_controller provides the key functions: ``launch()``, ``poll()`` and
-``kill()``. libEnsemble auto-detects a number of system criteria, such as the MPI launcher,
-along with correct mechanisms for polling and killing jobs, on supported systems. It also
-contains built in resilience, such as re-launching jobs that fail due to system factors.
-User scripts that employ the job_controller interface will be portable between supported
-systems. Job attributes can be queried to determine status after each poll. Functions are
-also provided to access and interrogate files in the job's working directory.
-
-The Job Controller module can be used to submit
-and manage jobs using a portable interface. Various back-end mechanisms may be
-used to implement this interface on the system, including a proxy launcher and
-job management system, such as Balsam. Currently, these job_controllers launch
-at the application level within an existing resource pool. However, submissions
-to a batch schedular may be supported in the future.
-
-At the top-level calling script, a job_controller is created and the executable
-gen or sim applications are registered to it (these are applications that will
-be runnable jobs). If an alternative job_controller, such as Balsam, is to be
-used, then these can be created as in the example. Once in the user-side worker
-code (sim/gen func), an MPI based job_controller can be retrieved without any
-need to specify the type.
+Users who wish to launch jobs to a system from a :ref:`sim_f<api_sim_f>`(or :ref:`gen_f<api_gen_f>`),
+running on a worker have several options.
+
+Typically, an MPI job could be initialized with a subprocess call to
+``mpirun`` or an alternative launcher such as ``aprun`` or ``jsrun``. The ``sim_f``
+may then monitor this job, check output, and possibly kill the job. We use "job"
+to represent an application launch to the system, which may be a supercomputer,
+cluster, or other provision of compute resources.
+
+A **job_controller** interface is provided by libEnsemble to remove the burden of
+system interaction from the user and ease writing portable ``sim_f`` scripts.
+The job_controller provides the key functions: ``launch()``, ``poll()`` and
+``kill()``. Job attributes can be queried to determine status after each poll.
+To implement these functions, libEnsemble auto-detects system criteria such as
+the MPI launcher and mechanisms to poll and kill jobs on supported systems.
+libEnsemble's job_controller is resilient, and can re-launch jobs that fail due
+to system factors.
+
+Functions are also provided to access and interrogate files in the job's working directory.
+
+Various back-end mechanisms may be used by the job_controller to best interact
+with each system, including proxy launchers or job management systems like
+Balsam_. Currently, these job_controllers launch at the application level within
+an existing resource pool. However, submissions to a batch scheduler may be
+supported in the future.
+
+In a calling script, a job_controller object is created and the executable
+generator or simulation applications are registered to it for launch. If an
+alternative job_controller, such as Balsam, is to be used, then these can be
+created as in the example. Once in the user-side worker code (sim/gen func),
+an MPI based job_controller can be retrieved without any need to specify the type.
 
 **Example usage (code runnable with or without a Balsam backend):**
 
@@ -92,3 +91,5 @@ For a more realistic example see:
 - libensemble/tests/scaling_tests/forces/
 
 which launches the forces.x application as an MPI job.
+
+.. _Balsam: https://balsam.readthedocs.io/en/latest/
diff --git a/docs/overview_usecases.rst b/docs/overview_usecases.rst
index 47a552a75..f96831e58 100644
--- a/docs/overview_usecases.rst
+++ b/docs/overview_usecases.rst
@@ -5,20 +5,18 @@ Overview
 ~~~~~~~~
 .. begin_overview_rst_tag
 
-libEnsemble is a Python library to coordinate the concurrent evaluation of
-dynamic ensembles of calculations. libEnsemble uses a manager to allocate work to
-multiple workers. A libEnsemble worker is the smallest indivisible unit to
-perform some calculation. The work performed by libEnsemble is governed by
-three routines:
+libEnsemble is a Python library for coordinating evaluation of dynamic ensembles
+of calculations in parallel. libEnsemble uses a manager process to allocate work to
+multiple worker processes. A libEnsemble worker is the smallest indivisible unit
+that can perform calculations. libEnsemble's work is governed by three routines:
 
 * :ref:`gen_f<api_gen_f>`: Generates inputs to ``sim_f``.
-* :ref:`sim_f<api_sim_f>`: Evaluates a simulation or other evaluation at output from ``gen_f``.
+* :ref:`sim_f<api_sim_f>`: Evaluates a simulation or other evaluation based on output from ``gen_f``.
 * :ref:`alloc_f<api_alloc_f>`: Decides whether ``sim_f`` or ``gen_f`` should be called (and with what input/resources) as workers become available.
 
-Example ``sim_f``, ``gen_f``, ``alloc_f``, and calling scripts
-be found in the ``examples/`` directory. To enable portability, a
-:doc:`job_controller<job_controller/overview>`
-interface is supplied for users to launch and monitor jobs in their
+Example ``sim_f``, ``gen_f``, ``alloc_f``, and calling scripts can be found in
+the ``examples/`` directory. To enable portability, a :doc:`job_controller<job_controller/overview>`
+interface is supplied for users to launch and monitor external scripts in their
 user-provided ``sim_f`` and ``gen_f`` routines.
 
 The default ``alloc_f`` tells each available worker to call ``sim_f`` with the
@@ -35,23 +33,23 @@ to support) and plan to have examples of:
 * A user is looking to optimize a simulation calculation. The simulation may
   already be using parallel resources, but not a large fraction of some
   computer. libEnsemble can coordinate the concurrent evaluation of the
-  simulation ``sim_f`` at various parameter values and ``gen_f`` would return
-  candidate parameter values (possibly after each ``sim_f`` output).
+  simulation ``sim_f`` at various parameter values based on candidate parameter
+  values from ``gen_f`` (possibly after each ``sim_f`` output).
 
-* A user has a ``gen_f`` that produces different meshes to be used within a
-  ``sim_f``. Given the ``sim_f`` output, ``gen_f`` will refine a mesh or
+* A user has a ``gen_f`` that produces meshes for a
+  ``sim_f``. Given the ``sim_f`` output, the ``gen_f`` can refine a mesh or
   produce a new mesh. libEnsemble can ensure that the calculated meshes can be
   used by multiple simulations without requiring movement of data.
 
 * A user is attempting to sample a simulation ``sim_f`` at some parameter
   values, many of which will cause the simulation to fail. libEnsemble can stop
   unresponsive evaluations, and recover computational resources for future
-  evaluations. ``gen_f`` can possibly update the sampling after discovering
+  evaluations. The ``gen_f`` can possibly update the sampling after discovering
   regions where evaluations of ``sim_f`` fail.
 
 * A user has a simulation ``sim_f`` that requires calculating multiple
-  expensive quantities, some of which depend on other quantities. ``sim_f`` can
-  observe intermediate quantities in order to stop related calculations and
+  expensive quantities, some of which depend on other quantities. The ``sim_f``
+  can observe intermediate quantities in order to stop related calculations and
   preempt future calculations associated with poor parameter values.
 
 * A user has a ``sim_f`` with multiple fidelities, with the higher-fidelity
diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst
index 6abb5b76b..cd27df1c8 100644
--- a/docs/platforms/platforms_index.rst
+++ b/docs/platforms/platforms_index.rst
@@ -2,12 +2,12 @@ Running on HPC Systems
 ======================
 
 libEnsemble has been developed, supported, and tested on systems of highly varying
-scales, from laptops to thousands of compute-nodes. libEnsemble's embarrassingly
-parallel  scaling capabilities are best exemplified on the resources available
-within high-performance machines.
+scales, from laptops to thousands of compute-nodes. libEnsemble's hugely parallel
+scaling capabilities are most productive with the resources available within
+high-performance machines.
 
-libEnsemble's flexible architecture lends itself best to two general modes of worker
-distributions across allocated compute nodes. The first mode we refer
+Across allocated compute nodes, libEnsemble's flexible architecture lends itself
+best to two general modes of worker distributions. The first mode we refer
 to as **centralized** mode, where the libEnsemble manager and worker processes
 are grouped on one or more nodes, but through the libEnsemble job-controller or a
 job-launch command can execute calculations on the other allocated nodes:
@@ -32,8 +32,8 @@ other workers directly on one or more allocated nodes:
 
 Due to this factor, libEnsemble on Theta and Summit approaches centralized mode
 differently. On these machines, libEnsemble is run centralized on either a
-compute-node with the support of Balsam_ or on a frontend server called a MOM
-(Machine-Oriented Mini-server) node.
+compute-node with the support of Balsam_, a frontend MOM
+(Machine-Oriented Mini-server) node on Theta, or a launch node on Summit.
 
 Read more about configuring and launching libEnsemble on some HPC systems:
 

From 5ac1945079c6fa8f03433246a65c37086eee4246 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 2 Dec 2019 12:24:02 -0600
Subject: [PATCH 632/644] second round of grammar adjustments

---
 docs/data_structures/worker_array.rst |  7 ++++---
 docs/history_output.rst               | 20 ++++++++++----------
 2 files changed, 14 insertions(+), 13 deletions(-)

diff --git a/docs/data_structures/worker_array.rst b/docs/data_structures/worker_array.rst
index 338096d3b..aa4cc4c7c 100644
--- a/docs/data_structures/worker_array.rst
+++ b/docs/data_structures/worker_array.rst
@@ -12,9 +12,10 @@ worker array
         'blocked' [int]:
             Is the worker's resources blocked by another calculation
 
-Since workers can be an a variety of states, the worker array ``W`` is contains
-information about each workers state. This can allow an allocation functions to
-determine what work should be performed.
+Since workers can be an a variety of states, the worker array ``W`` contains
+information about each worker's state. This can allow allocation functions to
+determine what work should be performed based on worker-statuses.
+
 We take the following convention:
 
 =========================================   =======  ============  =======
diff --git a/docs/history_output.rst b/docs/history_output.rst
index 3c4a57e92..50c61a6a7 100644
--- a/docs/history_output.rst
+++ b/docs/history_output.rst
@@ -9,7 +9,7 @@ the final history from libEnsemble will includes the following:
 
 * ``sim_id`` [int]: Each unit of work output from ``gen_f`` must have an
   associated ``sim_id``. The generator can assign this, but users must be
-  careful to ensure points are added in order. For example, ``if alloc_f``
+  careful to ensure points are added in order. For example, if ``alloc_f``
   allows for two ``gen_f`` instances to be running simultaneously, ``alloc_f``
   should ensure that both don’t generate points with the same ``sim_id``.
 
@@ -19,7 +19,7 @@ the final history from libEnsemble will includes the following:
 * ``given_time`` [float]: At what time (since the epoch) was this ``gen_f``
   output given to a worker?
 
-* ``sim_worker`` [int]: libEnsemble worker that it was given to be evaluated.
+* ``sim_worker`` [int]: libEnsemble worker that output was given to for evaluation
 
 * ``gen_worker`` [int]: libEnsemble worker that generated this ``sim_id``
 
@@ -43,15 +43,15 @@ where ``sim_count`` is the number of points evaluated.
 
 Other libEnsemble files produced by default are:
 
-* ``libE_stats.txt``: This contains a one-line summary of all user
-  calculations.  Each calculation summary is sent by workers to the manager and
-  printed as the run progresses.
+* ``libE_stats.txt``: This contains one-line summaries for each user
+  calculation. Each summary is sent by workers to the manager and
+  logged as the run progresses.
 
-* ``ensemble.log``: This is the logging output from libEnsemble. The default
-  logging is at INFO level. To gain additional diagnostics logging level can be
-  set to DEBUG.  If this file is not removed, multiple runs will append output.
-  Messages at or above level MANAGER_WARNING are also copied to stderr to alert
-  the user promptly.  For more info, see :doc:`Logging<logging>`.
+* ``ensemble.log``: This contains logging output from libEnsemble. The default
+  logging is INFO. To gain additional diagnostics, the logging level can be
+  set to DEBUG. If this file is not removed, multiple runs will append output.
+  Messages at or above MANAGER_WARNING are also copied to stderr to alert
+  the user promptly. For more info, see :doc:`Logging<logging>`.
 
 Output Analysis
 ^^^^^^^^^^^^^^^

From 7e958b57a84692ca6091dc35db552772c4cd0548 Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 2 Dec 2019 12:46:18 -0600
Subject: [PATCH 633/644] small-ish adjustments

---
 docs/data_structures/worker_array.rst |  2 +-
 docs/history_output.rst               |  2 +-
 docs/job_controller/overview.rst      | 14 +++++++-------
 docs/overview_usecases.rst            |  2 +-
 4 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/data_structures/worker_array.rst b/docs/data_structures/worker_array.rst
index aa4cc4c7c..84d4963ae 100644
--- a/docs/data_structures/worker_array.rst
+++ b/docs/data_structures/worker_array.rst
@@ -14,7 +14,7 @@ worker array
 
 Since workers can be an a variety of states, the worker array ``W`` contains
 information about each worker's state. This can allow allocation functions to
-determine what work should be performed based on worker-statuses.
+determine what work should be performed based on each worker's state.
 
 We take the following convention:
 
diff --git a/docs/history_output.rst b/docs/history_output.rst
index 50c61a6a7..9035d62c3 100644
--- a/docs/history_output.rst
+++ b/docs/history_output.rst
@@ -48,7 +48,7 @@ Other libEnsemble files produced by default are:
   logged as the run progresses.
 
 * ``ensemble.log``: This contains logging output from libEnsemble. The default
-  logging is INFO. To gain additional diagnostics, the logging level can be
+  logging level is INFO. To gain additional diagnostics, the logging level can be
   set to DEBUG. If this file is not removed, multiple runs will append output.
   Messages at or above MANAGER_WARNING are also copied to stderr to alert
   the user promptly. For more info, see :doc:`Logging<logging>`.
diff --git a/docs/job_controller/overview.rst b/docs/job_controller/overview.rst
index c36e5bc97..0254809d1 100644
--- a/docs/job_controller/overview.rst
+++ b/docs/job_controller/overview.rst
@@ -11,11 +11,11 @@ to represent an application launch to the system, which may be a supercomputer,
 cluster, or other provision of compute resources.
 
 A **job_controller** interface is provided by libEnsemble to remove the burden of
-system interaction from the user and ease writing portable ``sim_f`` scripts.
-The job_controller provides the key functions: ``launch()``, ``poll()`` and
-``kill()``. Job attributes can be queried to determine status after each poll.
-To implement these functions, libEnsemble auto-detects system criteria such as
-the MPI launcher and mechanisms to poll and kill jobs on supported systems.
+system interaction from the user and ease writing portable user scripts that
+launch applications. The job_controller provides the key functions: ``launch()``,
+``poll()`` and ``kill()``. Job attributes can be queried to determine status after
+each poll. To implement these functions, libEnsemble auto-detects system criteria
+such as the MPI launcher and mechanisms to poll and kill jobs on supported systems.
 libEnsemble's job_controller is resilient, and can re-launch jobs that fail due
 to system factors.
 
@@ -29,8 +29,8 @@ supported in the future.
 
 In a calling script, a job_controller object is created and the executable
 generator or simulation applications are registered to it for launch. If an
-alternative job_controller, such as Balsam, is to be used, then these can be
-created as in the example. Once in the user-side worker code (sim/gen func),
+alternative job_controller like Balsam will be used, then the applications can be
+registered like in the example below. Once in the user-side worker code (sim/gen func),
 an MPI based job_controller can be retrieved without any need to specify the type.
 
 **Example usage (code runnable with or without a Balsam backend):**
diff --git a/docs/overview_usecases.rst b/docs/overview_usecases.rst
index f96831e58..019cacb0f 100644
--- a/docs/overview_usecases.rst
+++ b/docs/overview_usecases.rst
@@ -5,7 +5,7 @@ Overview
 ~~~~~~~~
 .. begin_overview_rst_tag
 
-libEnsemble is a Python library for coordinating evaluation of dynamic ensembles
+libEnsemble is a Python library for coordinating the evaluation of dynamic ensembles
 of calculations in parallel. libEnsemble uses a manager process to allocate work to
 multiple worker processes. A libEnsemble worker is the smallest indivisible unit
 that can perform calculations. libEnsemble's work is governed by three routines:

From 4be063cfd89f435c10fcb5b8a421d8d0080b772c Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Mon, 2 Dec 2019 12:54:59 -0600
Subject: [PATCH 634/644] remove redundancy for worker state

---
 docs/data_structures/worker_array.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/data_structures/worker_array.rst b/docs/data_structures/worker_array.rst
index 84d4963ae..f0240494c 100644
--- a/docs/data_structures/worker_array.rst
+++ b/docs/data_structures/worker_array.rst
@@ -12,9 +12,9 @@ worker array
         'blocked' [int]:
             Is the worker's resources blocked by another calculation
 
-Since workers can be an a variety of states, the worker array ``W`` contains
-information about each worker's state. This can allow allocation functions to
-determine what work should be performed based on each worker's state.
+The worker array ``W`` contains information about each worker's state. This is
+useful information for allocation functions determining what work should be
+performed next.
 
 We take the following convention:
 

From fcf6f49f31ead8de761bffb8f16ad1bb1fb44560 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Mon, 2 Dec 2019 19:41:00 -0600
Subject: [PATCH 635/644] Update platform guides

---
 docs/platforms/cori.rst  | 97 +++++++++++++++++++++++-----------------
 docs/platforms/theta.rst |  2 +
 2 files changed, 58 insertions(+), 41 deletions(-)

diff --git a/docs/platforms/cori.rst b/docs/platforms/cori.rst
index f666f515b..5c925d650 100644
--- a/docs/platforms/cori.rst
+++ b/docs/platforms/cori.rst
@@ -6,40 +6,41 @@ Cori_ is a Cray XC40 located at NERSC, featuring both Intel Haswell
 and Knights Landing compute nodes. It uses the SLURM schedular to submit
 jobs from login nodes to run on the compute nodes.
 
-Configuring Python
-------------------
+Cori does not allow more than one MPI application per compute node.
 
-Begin by loading the Python 3 Anaconda_ module::
 
-    module load python
+Configuring Python and installation
+-----------------------------------
+
+Begin by loading the Python 3 Anaconda_ module::
 
-Create a Conda_ virtual environment in which to install libEnsemble and all
-dependencies::
+    module load python/3.7-anaconda-2019.07
 
-    conda config --add channels intel
-    conda create --name my_env intelpython3_core python=3
-    source activate my_env
+In many cases this may provide all the dependent packages you need (including
+mpi4py). Then libEnsemble can be installed locally::
 
-Installing libEnsemble and Dependencies
----------------------------------------
+    export PYTHONNOUSERSITE=0
+    pip install libensemble --user
 
-You should have an indication that the virtual environment is activated.
-Install mpi4py_ and libEnsemble in this environment, making sure to reference
-the Cray compiler wrappers. Your prompt should be similar to the
-following block:
+Alternatively, you can create your own Conda_ environment in which to install
+libEnsemble and all dependencies. If using ``mpi4py``, installation will need
+to be done using the `specific instructions from NERSC`_. libEnsemble can then
+be pip installed into the environment::
 
 .. code-block:: console
 
-    (my_env) user@cori07:~$ CC=cc MPICC=cc pip install mpi4py --no-binary mpi4py
     (my_env) user@cori07:~$ pip install libensemble
 
+If highly parallel runs experience long start-up delays consider the NERSC
+documentation on `scaling Python`_.
+
 Job Submission
 --------------
 
 Cori uses Slurm_ for job submission and management. The two commands you'll
 likely use the most to run jobs are ``srun`` and ``sbatch`` for running
 interactively and batch, respectively. libEnsemble runs on the compute nodes
-only Cori using either ``multi-processing`` or ``mpi4py``.
+on Cori using either ``multi-processing`` or ``mpi4py``.
 
 Interactive Runs
 ^^^^^^^^^^^^^^^^
@@ -50,7 +51,7 @@ You can allocate four Knights Landing nodes for thirty minutes through the follo
 
 With your nodes allocated, queue your job to start with four MPI ranks::
 
-    srun -n 4 python calling.py
+    srun --ntasks 4 --nodes=1 python calling.py
 
 This line launches libEnsemble with a manager and **three** workers to one
 allocated compute node, with three nodes available for the workers to launch
@@ -58,22 +59,15 @@ user applications with the job-controller or a job-launch command.
 
 This is an example of running in :doc:`centralized<platforms_index>` mode and,
 if using the :doc:`job_controller<../job_controller/mpi_controller>`, it should
-be intiated with ``central_mode=True``
-
-.. note::
-    When performing a :doc:`distributed<platforms_index>` MPI libEnsemble run,
-    specify one more MPI process than the number of allocated nodes.
-    The Manager and first worker run together on a node.
+be intiated with ``central_mode=True``. libEnsemble must be run in central mode
+on Cori as jobs cannot share nodes.
 
-.. note::
-    You will need to re-activate your conda virtual environment and reload your
-    modules! Configuring this routine to occur automatically is recommended.
 
 Batch Runs
 ^^^^^^^^^^
 
 Batch scripts specify run-settings using ``#SBATCH`` statements. A simple example
-for a libEnsemble use-case running in :doc:`distributed<platforms_index>` MPI
+for a libEnsemble use-case running in :doc:`centralized<platforms_index>` MPI
 mode on KNL nodes resembles the following:
 
 .. code-block:: bash
@@ -81,7 +75,7 @@ mode on KNL nodes resembles the following:
 
     #!/bin/bash
     #SBATCH -J myjob
-    #SBATCH -N 4
+    #SBATCH -N 5
     #SBATCH -q debug
     #SBATCH -A myproject
     #SBATCH -o myjob.out
@@ -89,26 +83,45 @@ mode on KNL nodes resembles the following:
     #SBATCH -t 00:15:00
     #SBATCH -C knl
 
-    # These four lines construct a machinefile for the job controller and slurm
-    srun hostname | sort -u > node_list
-    head -n 1 node_list > machinefile.$SLURM_JOBID
-    cat node_list >> machinefile.$SLURM_JOBID
-    export SLURM_HOSTFILE=machinefile.$SLURM_JOBID
-
-    srun --ntasks 5 python calling_script.py
+    # Run the libE (manager and 4 workers) on one node
+    # leaving 4 nodes for worker launched applications.
+    srun --ntasks 5 --nodes=1 python calling_script.py
 
 With this saved as ``myscript.sh``, allocating, configuring, and running libEnsemble
 on Cori becomes::
 
     sbatch myscript.sh
 
-Example submission scripts are also given in the examples_ directory.
+If you wish to run in multi-processing (local) mode instead of using mpi4py,
+and your calling script uses the :doc:`parse_args()<../utilities>` function,
+then the run line in the above script would be::
+
+    python calling_script.py --comms local --nworkers 4
+
+As a larger example, the following script would launch libEnsemble in MPI mode
+with one manager and 128 workers, where each worker will have two nodes for the
+user application. libEnsemble could be run on more than one node, but here the
+``overcommit`` option to srun is used on one node.
+
+.. code-block:: bash
+    :linenos:
+
+    #!/bin/bash
+    #SBATCH -J my_bigjob
+    #SBATCH -N 257
+    #SBATCH -q regular
+    #SBATCH -A myproject
+    #SBATCH -o myjob.out
+    #SBATCH -e myjob.error
+    #SBATCH -t 01:00:00
+    #SBATCH -C knl
 
-Debugging Strategies
---------------------
+    # Run the libE (manager and 128 workers) on one node
+    # leaving 256 nodes for worker launched applications.
+    srun --overcommit --ntasks 129 --nodes=1 python calling_script.py
+
+Example submission scripts are also given in the examples_ directory.
 
-View the status of your submitted jobs with ``squeue`` and cancel jobs with
-``scancel [Job ID]``.
 
 Additional Information
 ----------------------
@@ -123,3 +136,5 @@ See the NERSC Cori docs here_ for more information about Cori.
 .. _here: https://docs.nersc.gov/jobs/
 .. _options: https://slurm.schedmd.com/srun.html
 .. _examples: https://github.com/Libensemble/libensemble/tree/develop/examples/job_submission_scripts
+.. _specific instructions from NERSC: https://docs.nersc.gov/programming/high-level-environments/python/mpi4py/
+.. _scaling Python: https://docs.nersc.gov/programming/high-level-environments/python/scaling-up
\ No newline at end of file
diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
index 2d1ee4c7d..e3e1d912a 100644
--- a/docs/platforms/theta.rst
+++ b/docs/platforms/theta.rst
@@ -9,6 +9,8 @@ Theta features three tiers of nodes: login, MOM (Machine-Oriented Mini-server),
 and compute nodes. Users on login nodes submit batch jobs to the MOM nodes.
 MOM nodes execute user batch-scripts to run on the compute nodes via ``aprun``.
 
+Theta does not allow more than one MPI application per compute node.
+
 Configuring Python
 ------------------
 

From 47941ef90e81d25ee1041dcf242547b73c19514a Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Mon, 2 Dec 2019 19:43:25 -0600
Subject: [PATCH 636/644] Add space to docs

---
 docs/job_controller/overview.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/job_controller/overview.rst b/docs/job_controller/overview.rst
index 0254809d1..9b88ddd24 100644
--- a/docs/job_controller/overview.rst
+++ b/docs/job_controller/overview.rst
@@ -1,7 +1,7 @@
 Job Controller Overview
 =======================
 
-Users who wish to launch jobs to a system from a :ref:`sim_f<api_sim_f>`(or :ref:`gen_f<api_gen_f>`),
+Users who wish to launch jobs to a system from a :ref:`sim_f<api_sim_f>` (or :ref:`gen_f<api_gen_f>`),
 running on a worker have several options.
 
 Typically, an MPI job could be initialized with a subprocess call to

From 5a72660beab30208d5c0cc820439879cbc9214af Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Mon, 2 Dec 2019 19:55:30 -0600
Subject: [PATCH 637/644] Fix typos in Cori doc

---
 docs/platforms/cori.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/platforms/cori.rst b/docs/platforms/cori.rst
index 5c925d650..a8e4966ad 100644
--- a/docs/platforms/cori.rst
+++ b/docs/platforms/cori.rst
@@ -25,7 +25,7 @@ mpi4py). Then libEnsemble can be installed locally::
 Alternatively, you can create your own Conda_ environment in which to install
 libEnsemble and all dependencies. If using ``mpi4py``, installation will need
 to be done using the `specific instructions from NERSC`_. libEnsemble can then
-be pip installed into the environment::
+be pip installed into the environment.
 
 .. code-block:: console
 
@@ -83,7 +83,7 @@ mode on KNL nodes resembles the following:
     #SBATCH -t 00:15:00
     #SBATCH -C knl
 
-    # Run the libE (manager and 4 workers) on one node
+    # Run libEnsemble (manager and 4 workers) on one node
     # leaving 4 nodes for worker launched applications.
     srun --ntasks 5 --nodes=1 python calling_script.py
 
@@ -116,7 +116,7 @@ user application. libEnsemble could be run on more than one node, but here the
     #SBATCH -t 01:00:00
     #SBATCH -C knl
 
-    # Run the libE (manager and 128 workers) on one node
+    # Run libEnsemble (manager and 128 workers) on one node
     # leaving 256 nodes for worker launched applications.
     srun --overcommit --ntasks 129 --nodes=1 python calling_script.py
 

From d4c76dcb5d165b8ad8f7ff8f38fd4f3535b339ae Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Tue, 3 Dec 2019 00:58:47 -0600
Subject: [PATCH 638/644] Adding Kaushik to the persistent aposmm docstring

---
 libensemble/gen_funcs/persistent_aposmm.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
index fea4c2f7b..094fcee62 100644
--- a/libensemble/gen_funcs/persistent_aposmm.py
+++ b/libensemble/gen_funcs/persistent_aposmm.py
@@ -3,6 +3,9 @@
 Parallel Optimization Solver for finding Multiple Minima (APOSMM) method
 described in detail in the paper
 `https://doi.org/10.1007/s12532-017-0131-4 <https://doi.org/10.1007/s12532-017-0131-4>`_
+
+This implementation of APOSMM was developed by Kaushik Kulkarni and Jeffrey
+Larson in the summer of 2019.
 """
 __all__ = ['initialize_APOSMM', 'decide_where_to_start_localopt', 'update_history_dist']
 

From 2815becf107823c98daef875ee0b560281c4542c Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Tue, 3 Dec 2019 21:50:31 -0600
Subject: [PATCH 639/644] Add cori example batch script and tidy others

---
 docs/platforms/example_scripts.rst            | 19 ++++---
 .../bebop_submit_slurm_central.sh             | 24 +++++++++
 .../bebop_submit_slurm_centralmode.sh         | 51 -------------------
 ...slurm.sh => bebop_submit_slurm_distrib.sh} | 51 ++++++++++---------
 .../job_submission_scripts/cori_submit.sh     | 24 +++++++++
 .../theta_submit_balsam.sh                    | 51 +++++++++++++------
 6 files changed, 122 insertions(+), 98 deletions(-)
 create mode 100644 examples/job_submission_scripts/bebop_submit_slurm_central.sh
 delete mode 100644 examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
 rename examples/job_submission_scripts/{bebop_submit_slurm.sh => bebop_submit_slurm_distrib.sh} (58%)
 create mode 100644 examples/job_submission_scripts/cori_submit.sh

diff --git a/docs/platforms/example_scripts.rst b/docs/platforms/example_scripts.rst
index 4af97bc74..c492b4793 100644
--- a/docs/platforms/example_scripts.rst
+++ b/docs/platforms/example_scripts.rst
@@ -8,19 +8,26 @@ information about the respective systems and configuration.
 Bebop - Central mode
 --------------------
 
-..  literalinclude:: ../../examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
-    :caption: /examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
+..  literalinclude:: ../../examples/job_submission_scripts/bebop_submit_slurm_central.sh
+    :caption: /examples/job_submission_scripts/bebop_submit_slurm_central.sh
     :language: bash
 
 Bebop - Distributed mode
 ------------------------
 
-..  literalinclude:: ../../examples/job_submission_scripts/bebop_submit_slurm.sh
-    :caption: /examples/job_submission_scripts/bebop_submit_slurm.sh
+..  literalinclude:: ../../examples/job_submission_scripts/bebop_submit_slurm_distrib.sh
+    :caption: /examples/job_submission_scripts/bebop_submit_slurm_distrib.sh
     :language: bash
 
-Blues
------
+Cori - Central mode
+-------------------
+
+..  literalinclude:: ../../examples/job_submission_scripts/cori_submit.sh
+    :caption: /examples/job_submission_scripts/cori_submit.sh
+    :language: bash
+
+Blues (Blue Gene Q) - Distributed mode
+--------------------------------------
 
 ..  literalinclude:: ../../examples/job_submission_scripts/blues_script.pbs
     :caption: /examples/job_submission_scripts/blues_script.pbs
diff --git a/examples/job_submission_scripts/bebop_submit_slurm_central.sh b/examples/job_submission_scripts/bebop_submit_slurm_central.sh
new file mode 100644
index 000000000..adc536ab8
--- /dev/null
+++ b/examples/job_submission_scripts/bebop_submit_slurm_central.sh
@@ -0,0 +1,24 @@
+#!/bin/bash
+#SBATCH -J libE_test_central
+#SBATCH -N 5
+#SBATCH -p knlall
+#SBATCH -A <my_project>
+#SBATCH -o tlib.%j.%N.out
+#SBATCH -e tlib.%j.%N.error
+#SBATCH -t 01:00:00
+
+# Launch script for running in central mode with mpi4py.
+#   libEnsemble will run on a dedicated node (or nodes).
+#   The remaining nodes in the allocation will be dedicated to worker launched apps.
+#   Use job_controller with auto-resources=True and central_mode=True.
+
+# User to edit these variables
+export EXE=libE_calling_script.py
+export NUM_WORKERS=4
+export I_MPI_FABRICS=shm:tmi
+
+# Overcommit will allow ntasks up to the no. of contexts on one node (eg. 320 on Bebop)
+srun --overcommit --ntasks=$(($NUM_WORKERS+1)) --nodes=1 python $EXE
+
+# To use local mode instead of mpi4py (with utils.parse_args())
+# python calling_script.py --comms local --nworkers $NUM_WORKERS
diff --git a/examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh b/examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
deleted file mode 100644
index 58321c120..000000000
--- a/examples/job_submission_scripts/bebop_submit_slurm_centralmode.sh
+++ /dev/null
@@ -1,51 +0,0 @@
-#!/bin/bash
-#SBATCH -J libE_test_central
-#SBATCH -N 5
-#SBATCH -p knlall
-##SBATCH -A <my_project>
-#SBATCH -o tlib.%j.%N.out
-#SBATCH -e tlib.%j.%N.error
-#SBATCH -t 01:00:00
-
-#Launch script for running in central mode.
-#LibEnsemble will run on a dedicated node (or nodes).
-#The remaining nodes in the allocation will be dedicated to the jobs launched by the workers.
-
-#Requirements for running:
-# Must use job_controller with auto-resources=True and central_mode=True.
-# Note: Requires a schedular having an environment variable giving a global nodelist in a supported format (eg. SLURM/COBALT)
-#       Otherwise a worker_list file will be required.
-
-#Currently requires even distribution - either multiple workers per node or nodes per worker
-
-#User to edit these variables
-export EXE=libE_calling_script.py
-export NUM_WORKERS=4
-
-export I_MPI_FABRICS=shm:tmi
-
-#If using in calling script (After N mins manager kills workers and timing.dat created.)
-export LIBE_WALLCLOCK=55
-
-#---------------------------------------------------------------------------------------------
-#Test
-echo -e "Slurm job ID: $SLURM_JOBID"
-
-#cd $PBS_O_WORKDIR
-cd $SLURM_SUBMIT_DIR
-
-# A little useful information for the log file...
-echo -e "Master process running on: $HOSTNAME"
-echo -e "Directory is:  $PWD"
-
-#This will work for the number of contexts that will fit on one node (eg. 320 on Bebop) - increase libE nodes for more.
-cmd="srun --overcommit --ntasks=$(($NUM_WORKERS+1)) --nodes=1 python $EXE $LIBE_WALLCLOCK"
-
-echo The command is: $cmd
-echo End PBS script information.
-echo All further output is from the process being run and not the pbs script.\n\n $cmd # Print the date again -- when finished
-
-$cmd
-
-# Print the date again -- when finished
-echo Finished at: `date`
diff --git a/examples/job_submission_scripts/bebop_submit_slurm.sh b/examples/job_submission_scripts/bebop_submit_slurm_distrib.sh
similarity index 58%
rename from examples/job_submission_scripts/bebop_submit_slurm.sh
rename to examples/job_submission_scripts/bebop_submit_slurm_distrib.sh
index c80c2ee07..5ef013ab2 100644
--- a/examples/job_submission_scripts/bebop_submit_slurm.sh
+++ b/examples/job_submission_scripts/bebop_submit_slurm_distrib.sh
@@ -2,29 +2,32 @@
 #SBATCH -J libE_test
 #SBATCH -N 4
 #SBATCH -p knlall
-##SBATCH -A <my_project>
+#SBATCH -A <my_project>
 #SBATCH -o tlib.%j.%N.out
 #SBATCH -e tlib.%j.%N.error
 #SBATCH -t 01:00:00
 
-#Launch script that evenly spreads workers and adds manager to the first node.
-#Requires even distribution - either multiple workers per node or nodes per worker
-#Now option for manager to have a dedicated node.
+# Launch script that runs in distributed mode with mpi4py.
+#   Workers are evenly spread over nodes and manager added to the first node.
+#   Requires even distribution - either multiple workers per node or nodes per worker
+#   Option for manager to have a dedicated node.
+#   Use of job controller will ensure workers co-locate jobs with workers
 
-#User to edit these variables
+# User to edit these variables
 export EXE=libE_calling_script.py
 export NUM_WORKERS=4
-export MANAGER_NODE=false #true = Manager has a dedicated node (use one extra node for SBATCH -N)
+export MANAGER_NODE=false # true = Manager has a dedicated node (assign one extra)
 
+# As libE shares nodes with user applications allow fallback if contexts overrun.
 unset I_MPI_FABRICS
 export I_MPI_FABRICS_LIST=tmi,tcp
 export I_MPI_FALLBACK=1
 
-#If using in calling script (After N mins manager kills workers and timing.dat created.)
+# If using in calling script (After N mins manager kills workers and exits cleanly)
 export LIBE_WALLCLOCK=55
 
-#---------------------------------------------------------------------------------------------
-
+#-----------------------------------------------------------------------------
+# Work out distribution
 if [[ $MANAGER_NODE = "true" ]]; then
   WORKER_NODES=$(($SLURM_NNODES-1))
 else
@@ -38,49 +41,47 @@ else
   SUB_NODE_WORKERS=false
   NODES_PER_WORKER=$(($WORKER_NODES/$NUM_WORKERS))
 fi;
+#-----------------------------------------------------------------------------
 
-#---------------------------------------------------------------------------------------------
-#Test
-echo -e "Slurm job ID: $SLURM_JOBID"
-
-#cd $PBS_O_WORKDIR
-cd $SLURM_SUBMIT_DIR
-
-# A little useful information for the log file...
+# A little useful information
 echo -e "Master process running on: $HOSTNAME"
 echo -e "Directory is:  $PWD"
 
-#Generate a node list with 1 node per line:
+# Generate a node list with 1 node per line:
 srun hostname | sort -u > node_list
 
-#Generate list of nodes for workers
+# Generate list of nodes for workers
 if [[ $MANAGER_NODE = "true" ]]; then
   tail -n +2 node_list > worker_list
 else
   cp node_list worker_list
 fi
 
-#Add manager node to machinefile
+# Add manager node to machinefile
 head -n 1 node_list > machinefile.$SLURM_JOBID
 
-#Add worker nodes to machinefile
+# Add worker nodes to machinefile
 if [[ $SUB_NODE_WORKERS = "true" ]]; then
-  awk -v repeat=$WORKERS_PER_NODE '{for(i=0;i<repeat;i++)print}' worker_list >>machinefile.$SLURM_JOBID
+  awk -v repeat=$WORKERS_PER_NODE '{for(i=0;i<repeat;i++)print}' worker_list \
+  >>machinefile.$SLURM_JOBID
 else
-  awk -v patt="$NODES_PER_WORKER" 'NR % patt == 1' worker_list >> machinefile.$SLURM_JOBID
+  awk -v patt="$NODES_PER_WORKER" 'NR % patt == 1' worker_list \
+  >> machinefile.$SLURM_JOBID
 fi;
 
 # Put in a timestamp
 echo Starting executation at: `date`
 
-#To use srun
+# To use srun
 export SLURM_HOSTFILE=machinefile.$SLURM_JOBID
+
+# The "arbitrary" flag should ensure SLURM_HOSTFILE is picked up
 # cmd="srun --ntasks $(($NUM_WORKERS+1)) -m arbitrary python $EXE"
 cmd="srun --ntasks $(($NUM_WORKERS+1)) -m arbitrary python $EXE $LIBE_WALLCLOCK"
 
 echo The command is: $cmd
 echo End PBS script information.
-echo All further output is from the process being run and not the pbs script.\n\n $cmd # Print the date again -- when finished
+echo All further output is from the process being run and not the script.\n\n $cmd
 
 $cmd
 
diff --git a/examples/job_submission_scripts/cori_submit.sh b/examples/job_submission_scripts/cori_submit.sh
new file mode 100644
index 000000000..3b0e7d2d0
--- /dev/null
+++ b/examples/job_submission_scripts/cori_submit.sh
@@ -0,0 +1,24 @@
+#!/bin/bash
+#SBATCH -J libE_test_central
+#SBATCH -N 5
+#SBATCH -q debug
+#SBATCH -A <my_project>
+#SBATCH -o tlib.%j.%N.out
+#SBATCH -e tlib.%j.%N.error
+#SBATCH -t 01:00:00
+#SBATCH -C knl
+
+# Launch script for running in central mode with mpi4py.
+#   libEnsemble will run on a dedicated node (or nodes).
+#   The remaining nodes in the allocation will be dedicated to worker launched apps.
+#   Use job_controller with auto-resources=True and central_mode=True.
+
+# User to edit these variables
+export EXE=libE_calling_script.py
+export NUM_WORKERS=4
+
+# Overcommit will allow ntasks up to the no. of contexts on one node (eg. 320 on Bebop)
+srun --overcommit --ntasks=$(($NUM_WORKERS+1)) --nodes=1 python $EXE
+
+# To use local mode instead of mpi4py (with utils.parse_args())
+# python calling_script.py --comms local --nworkers $NUM_WORKERS
diff --git a/examples/job_submission_scripts/theta_submit_balsam.sh b/examples/job_submission_scripts/theta_submit_balsam.sh
index 1677b118a..41c383c64 100644
--- a/examples/job_submission_scripts/theta_submit_balsam.sh
+++ b/examples/job_submission_scripts/theta_submit_balsam.sh
@@ -6,15 +6,17 @@
 ##COBALT -q default # For large jobs >=128 nodes
 ##COBALT -A <project code>
 
-# Script to launch libEnsemble using Balsam within Conda. Conda environment must be set up.
-
-# Requires Balsam is installed and a database initialized (this can be the default database).
+# Script to launch libEnsemble using Balsam.
+#   Assumes Conda environment is set up.
+#   Requires Balsam is installed and a database initialized.
 
 # To be run with central job management
 # - Manager and workers run on one node (or a dedicated set of nodes).
 # - Workers submit jobs to the rest of the nodes in the pool.
 
-# Constaint: - As set up - only uses one node (up to 63 workers) for libE. To use more, modifiy "balsam job" line to use hyper-threading and/or more than one node.
+# Constaint: - As set up - only uses one node (up to 63 workers) for libE.
+#   To use more, modifiy "balsam job" line to use hyper-threading
+#   and/or more than one node for libE.
 
 # Name of calling script
 export EXE=libE_calling_script.py
@@ -22,21 +24,30 @@ export EXE=libE_calling_script.py
 # Number of workers.
 export NUM_WORKERS=4
 
-# Wallclock for libE job in minutes (supplied to Balsam - make at least several mins smaller than wallclock for this submission to ensure job is launched)
+# Balsam wall-clock in minutes - make few mins smaller than batch wallclock
 export BALSAM_WALLCLOCK=25
 
-# Name of working directory where Balsam places running jobs/output (inside the database directory)
+# Name of working directory within database where Balsam places running jobs/output
 export WORKFLOW_NAME=libe_workflow
 
-#Tell libE manager to stop workers, and exit after this time. Script must be set up to receive as argument.
+# Wall-clock in mins for libE (allow clean shutdown).
+# Script must be set up to receive as argument.
 export LIBE_WALLCLOCK=$(($BALSAM_WALLCLOCK-3))
 
-# libEnsemble calling script arguments
-# export SCRIPT_ARGS='' # No args. All defined in calling script
-# export SCRIPT_ARGS="--comms mpi --nworkers $NUM_WORKERS # If calling script is using utils.parse_args()
-export SCRIPT_ARGS="$LIBE_WALLCLOCK --comms mpi --nworkers $NUM_WORKERS"  # If calling script takes wall-clock as positional arg.
 
-# Name of Conda environment (Need to have set up: https://balsam.readthedocs.io/en/latest/userguide/getting-started.html)
+# libEnsemble calling script arguments (some alternatives shown)
+
+# No args. All defined in calling script
+# export SCRIPT_ARGS=''
+
+# If calling script is using utils.parse_args()
+# export SCRIPT_ARGS="--comms mpi --nworkers $NUM_WORKERS
+
+# If calling script takes wall-clock as positional arg and uses utils.parse_args()
+export SCRIPT_ARGS="$LIBE_WALLCLOCK --comms mpi --nworkers $NUM_WORKERS"
+
+
+# Name of Conda environment
 export CONDA_ENV_NAME=<conda_env_name>
 
 # Name of database
@@ -58,17 +69,19 @@ module unload trackdeps
 module unload darshan
 module unload xalt
 
+# Activate Balsam database
 . balsamactivate $DBASE_NAME
 
 # Currently need atleast one DB connection per worker (for postgres).
 if [[ $NUM_WORKERS -gt 128 ]]
 then
    #Add a margin
-   echo -e "max_connections=$(($NUM_WORKERS+10)) #Appended by submission script" >> $BALSAM_DB_PATH/balsamdb/postgresql.conf
+   echo -e "max_connections=$(($NUM_WORKERS+10)) #Appended by submission script" \
+   >> $BALSAM_DB_PATH/balsamdb/postgresql.conf
 fi
 wait
 
-# Make sure no existing apps/jobs
+# Make sure no existing apps/jobs registered to database
 balsam rm apps --all --force
 balsam rm jobs --all --force
 wait
@@ -81,7 +94,12 @@ SCRIPT_BASENAME=${EXE%.*}
 balsam app --name $SCRIPT_BASENAME.app --exec $EXE --desc "Run $SCRIPT_BASENAME"
 
 # Running libE on one node - one manager and upto 63 workers
-balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --args $SCRIPT_ARGS --wall-time-minutes $BALSAM_WALLCLOCK --num-nodes 1 --ranks-per-node $((NUM_WORKERS+1)) --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
+balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME \
+       --application $SCRIPT_BASENAME.app --args $SCRIPT_ARGS \
+       --wall-time-minutes $BALSAM_WALLCLOCK \
+       --num-nodes 1 --ranks-per-node $((NUM_WORKERS+1)) \
+       --url-out="local:/$THIS_DIR" --stage-out-files="*.out *.txt *.log" \
+       --url-in="local:/$THIS_DIR/*" --yes
 
 # Hyper-thread libE (note this will not affect HT status of user calcs - only libE itself)
 # Running 255 workers and one manager on one libE node.
@@ -91,7 +109,8 @@ balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $
 # Running 127 workers and one manager - launch script on 129 nodes (if one node per worker)
 # balsam job --name job_$SCRIPT_BASENAME --workflow $WORKFLOW_NAME --application $SCRIPT_BASENAME.app --args $SCRIPT_ARGS --wall-time-minutes $BALSAM_WALLCLOCK  --num-nodes 2 --ranks-per-node 64 --url-out="local:/$THIS_DIR"  --stage-out-files="*.out *.txt *.log" --url-in="local:/$THIS_DIR/*" --yes
 
-#Run job
+# Run job
 balsam launcher --consume-all --job-mode=mpi --num-transition-threads=1
 
+# Deactivate Balsam database
 . balsamdeactivate

From dedcee4c2cf5ebdc3a96a46d186aca3082b0da17 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Tue, 3 Dec 2019 21:55:31 -0600
Subject: [PATCH 640/644] Set release date for v0.6.0

---
 CHANGELOG.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 32bf21497..f5193f036 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -5,7 +5,7 @@ Release Notes
 Release 0.6.0
 -------------
 
-:Date: November 27, 2019
+:Date: December 4, 2019
 
 API changes:
 

From af5def375dfd9aa2693327b09d8d9c1ce9fba17b Mon Sep 17 00:00:00 2001
From: Jeffrey Larson <jmlarson@anl.gov>
Date: Wed, 4 Dec 2019 11:05:10 -0600
Subject: [PATCH 641/644] Whitespace

---
 docs/FAQ.rst                                           | 2 +-
 docs/platforms/cori.rst                                | 3 ---
 examples/job_submission_scripts/theta_submit_balsam.sh | 2 --
 3 files changed, 1 insertion(+), 6 deletions(-)

diff --git a/docs/FAQ.rst b/docs/FAQ.rst
index d8408e690..28edff017 100644
--- a/docs/FAQ.rst
+++ b/docs/FAQ.rst
@@ -145,7 +145,7 @@ There are several ways to address this nuisance, but all involve trial and error
 An easy (but insecure) solution is temporarily disabling the Firewall through
 System Preferences -> Security & Privacy -> Firewall -> Turn Off Firewall. Alternatively,
 adding a Firewall "Allow incoming connections" rule can be attempted for the offending
-Job Controller executable. We've had limited success running 
+Job Controller executable. We've had limited success running
 ``sudo codesign --force --deep --sign - /path/to/application.app``
 on our Job Controller executables, then confirming the next alerts for the executable
 and ``mpiexec.hydra``.
diff --git a/docs/platforms/cori.rst b/docs/platforms/cori.rst
index a8e4966ad..2e85a5ecb 100644
--- a/docs/platforms/cori.rst
+++ b/docs/platforms/cori.rst
@@ -8,7 +8,6 @@ jobs from login nodes to run on the compute nodes.
 
 Cori does not allow more than one MPI application per compute node.
 
-
 Configuring Python and installation
 -----------------------------------
 
@@ -62,7 +61,6 @@ if using the :doc:`job_controller<../job_controller/mpi_controller>`, it should
 be intiated with ``central_mode=True``. libEnsemble must be run in central mode
 on Cori as jobs cannot share nodes.
 
-
 Batch Runs
 ^^^^^^^^^^
 
@@ -122,7 +120,6 @@ user application. libEnsemble could be run on more than one node, but here the
 
 Example submission scripts are also given in the examples_ directory.
 
-
 Additional Information
 ----------------------
 
diff --git a/examples/job_submission_scripts/theta_submit_balsam.sh b/examples/job_submission_scripts/theta_submit_balsam.sh
index 41c383c64..6d66ec7bf 100644
--- a/examples/job_submission_scripts/theta_submit_balsam.sh
+++ b/examples/job_submission_scripts/theta_submit_balsam.sh
@@ -34,7 +34,6 @@ export WORKFLOW_NAME=libe_workflow
 # Script must be set up to receive as argument.
 export LIBE_WALLCLOCK=$(($BALSAM_WALLCLOCK-3))
 
-
 # libEnsemble calling script arguments (some alternatives shown)
 
 # No args. All defined in calling script
@@ -46,7 +45,6 @@ export LIBE_WALLCLOCK=$(($BALSAM_WALLCLOCK-3))
 # If calling script takes wall-clock as positional arg and uses utils.parse_args()
 export SCRIPT_ARGS="$LIBE_WALLCLOCK --comms mpi --nworkers $NUM_WORKERS"
 
-
 # Name of Conda environment
 export CONDA_ENV_NAME=<conda_env_name>
 

From 44a05434b44caa1b4ff47577fd35ec6defb2068c Mon Sep 17 00:00:00 2001
From: jlnav <jnavarro@anl.gov>
Date: Wed, 4 Dec 2019 12:15:11 -0600
Subject: [PATCH 642/644] fix tutorial formatting

---
 docs/tutorials/local_sine_tutorial.rst | 12 ++++--------
 1 file changed, 4 insertions(+), 8 deletions(-)

diff --git a/docs/tutorials/local_sine_tutorial.rst b/docs/tutorials/local_sine_tutorial.rst
index a812a20bd..30a8beed6 100644
--- a/docs/tutorials/local_sine_tutorial.rst
+++ b/docs/tutorials/local_sine_tutorial.rst
@@ -8,14 +8,10 @@ Multiprocessing.
 
 The foundation of writing libEnsemble routines is accounting for four components:
 
-    1. The generator function :ref:`gen_f<api_gen_f>`, which produces values
-           for simulations.
-    2. The simulator function :ref:`sim_f<api_sim_f>`, which performs
-           simulations based on values from ``gen_f``.
-    3. The allocation function :ref:`alloc_f<api_alloc_f>`, which decides which
-           of the previous two functions should be called, when.
-    4. The calling script, which defines parameters and information about these
-           functions and the libEnsemble task, then begins execution.
+    1. The generator function :ref:`gen_f<api_gen_f>`, which produces values for simulations.
+    2. The simulator function :ref:`sim_f<api_sim_f>`, which performs simulations based on values from ``gen_f``.
+    3. The allocation function :ref:`alloc_f<api_alloc_f>`, which decides which of the previous two functions should be called, when.
+    4. The calling script, which defines parameters and information about these functions and the libEnsemble task, then begins execution.
 
 libEnsemble initializes a *manager* process and as many *worker* processes as the
 user requests. The manager coordinates data-transfer between workers and assigns

From b4f99b275b775b61b4c407f42adf99ee056bfc16 Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 4 Dec 2019 12:30:10 -0600
Subject: [PATCH 643/644] Minor fixes in docs

---
 docs/known_issues.rst                                  | 2 +-
 examples/job_submission_scripts/summit_submit_mproc.sh | 2 +-
 examples/job_submission_scripts/theta_submit_mproc.sh  | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/known_issues.rst b/docs/known_issues.rst
index caf187767..af45b1505 100644
--- a/docs/known_issues.rst
+++ b/docs/known_issues.rst
@@ -9,7 +9,7 @@ may occur when using libEnsemble.
   controller).
 * Local comms mode (multiprocessing) may fail if MPI is initialized before
   forking processors. This is thought to be responsible for issues combining
-  with PETSc.
+  multiprocessing with PETSc on some platforms.
 * Remote detection of logical cores via LSB_HOSTS (e.g., Summit) returns number
   of physical cores as SMT info not available.
 * TCP mode does not support:
diff --git a/examples/job_submission_scripts/summit_submit_mproc.sh b/examples/job_submission_scripts/summit_submit_mproc.sh
index 5a83ff106..18ada1640 100644
--- a/examples/job_submission_scripts/summit_submit_mproc.sh
+++ b/examples/job_submission_scripts/summit_submit_mproc.sh
@@ -10,7 +10,7 @@
 
 # To be run with central job management
 # - Manager and workers run on launch node.
-# - Workers submit jobs to the nodes in the job available.
+# - Workers submit jobs to the compute nodes in the allocation.
 
 # Name of calling script-
 export EXE=libE_calling_script.py
diff --git a/examples/job_submission_scripts/theta_submit_mproc.sh b/examples/job_submission_scripts/theta_submit_mproc.sh
index 394091c72..3405179f5 100755
--- a/examples/job_submission_scripts/theta_submit_mproc.sh
+++ b/examples/job_submission_scripts/theta_submit_mproc.sh
@@ -11,7 +11,7 @@
 
 # To be run with central job management
 # - Manager and workers run on launch node.
-# - Workers submit jobs to the compute nodes in the node allocation available.
+# - Workers submit jobs to the compute nodes in the allocation.
 
 # Name of calling script
 export EXE=libE_calling_script.py

From 9a3d36a3eda9f70f975e6d6a83cba6ec52d06f4d Mon Sep 17 00:00:00 2001
From: shudson <shudson@anl.gov>
Date: Wed, 4 Dec 2019 12:38:20 -0600
Subject: [PATCH 644/644] Update user guide link in README

---
 README.rst                  | 2 +-
 docs/introduction_latex.rst | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.rst b/README.rst
index ca282940f..0a91c0363 100644
--- a/README.rst
+++ b/README.rst
@@ -241,5 +241,5 @@ Resources
 .. _SWIG: http://swig.org/
 .. _tarball: https://github.com/Libensemble/libensemble/releases/latest
 .. _Travis CI: https://travis-ci.org/Libensemble/libensemble
-.. _user guide: https://libensemble.readthedocs.io/en/latest
+.. _user guide: https://libensemble.readthedocs.io/en/latest/programming_libE.html
 .. _xSDK Extreme-scale Scientific Software Development Kit: https://xsdk.info
diff --git a/docs/introduction_latex.rst b/docs/introduction_latex.rst
index d82c1cac0..6135a6dbb 100644
--- a/docs/introduction_latex.rst
+++ b/docs/introduction_latex.rst
@@ -43,5 +43,5 @@ Quickstart Guide
 .. _SWIG: http://swig.org/
 .. _tarball: https://github.com/Libensemble/libensemble/releases/latest
 .. _Travis CI: https://travis-ci.org/Libensemble/libensemble
-.. _user guide: https://libensemble.readthedocs.io/en/latest
+.. _user guide: https://libensemble.readthedocs.io/en/latest/programming_libE.html
 .. _xSDK Extreme-scale Scientific Software Development Kit: https://xsdk.info
\ No newline at end of file