tentatively rename allow_oversubscribe, document

libensemble/executors/mpi_executor.py

@@ -28,10 +28,6 @@ class MPIExecutor(Executor):
     """The MPI executor can create, poll and kill runnable MPI tasks
     """
 
-    # SH TODO: Whether to still be custom_info or separate variables as now quite limited.
-    #          only reason not to is prob that it may make people use them unnecesarily.
-    #          I think allow_oversubscribe should stay as MPIExecutor variable
-    #  __init__(self, allow_oversubscribe=True, custom_info={}):
     def __init__(self, custom_info={}):
         """Instantiate a new MPIExecutor instance.
 

libensemble/resources/mpi_resources.py

@@ -185,7 +185,7 @@ def get_resources(resources, num_procs=None, num_nodes=None,
             "Requested {}. Only {} available".
             format(num_nodes, local_node_count))
 
-    if not gresources.allow_oversubscribe:
+    if gresources.enforce_worker_core_bounds:
         rassert(ranks_per_node <= cores_avail_per_node,
                 "Not enough processors on a node to honor arguments. "
                 "Requested {}. Only {} available".

libensemble/resources/resources.py

@@ -134,6 +134,12 @@ def __init__(self, libE_specs, top_level_dir=None):
             If supplied gives (physical cores, logical cores) for the nodes. If not supplied,
             this will be auto-detected.
 
+        enforce_worker_core_bounds: boolean, optional
+            If True, then libEnsemble's executor will raise an exception on detecting that
+            the worker has been instructed to launch tasks with the number of requested processes
+            being excessive to the number of cores allocated to that worker, or not enough
+            processes were requested to satisfy allocated cores.
+
         node_file: String, optional
             If supplied, give the name of a file in the run directory to use as a node-list
             for use by libEnsemble. Defaults to a file named 'node_list'. If the file does
@@ -162,7 +168,7 @@ def __init__(self, libE_specs, top_level_dir=None):
         self.num_resource_sets = libE_specs.get('num_resource_sets', None)
 
         # SH TODO: Where to set this - put back here for now as easier than passing via executor.
-        self.allow_oversubscribe = libE_specs.get('allow_oversubscribe', True)
+        self.enforce_worker_core_bounds = libE_specs.get('enforce_worker_core_bounds', True)
 
         if self.central_mode:
             logger.debug('Running in central mode')

libensemble/tests/regression_tests/test_mpi_runners.py

@@ -31,7 +31,7 @@
 comms = libE_specs['comms']
 
 libE_specs['central_mode'] = True
-libE_specs['allow_oversubscribe'] = False
+libE_specs['enforce_worker_core_bounds'] = False
 
 # To allow visual checking - log file not used in test
 log_file = 'ensemble_mpi_runners_comms_' + str(comms) + '_wrks_' + str(nworkers) + '.log'

libensemble/tests/regression_tests/test_mpi_runners_subnode.py

@@ -35,7 +35,7 @@
 comms = libE_specs['comms']
 
 libE_specs['central_mode'] = True
-libE_specs['allow_oversubscribe'] = False
+libE_specs['enforce_worker_core_bounds'] = False
 
 # To allow visual checking - log file not used in test
 log_file = 'ensemble_mpi_runners_subnode_comms_' + str(comms) + '_wrks_' + str(nworkers) + '.log'

libensemble/tests/regression_tests/test_mpi_runners_subnode_uneven.py

@@ -63,7 +63,7 @@
                     'node_file': node_file}      # Name of file containing a node-list
 
 libE_specs['central_mode'] = True
-libE_specs['allow_oversubscribe'] = False
+libE_specs['enforce_worker_core_bounds'] = False
 libE_specs['resource_info'] = custom_resources
 
 # Create executor and register sim to it.

libensemble/tests/regression_tests/test_mpi_runners_supernode_uneven.py

@@ -31,7 +31,7 @@
 comms = libE_specs['comms']
 
 libE_specs['central_mode'] = True
-libE_specs['allow_oversubscribe'] = False
+libE_specs['enforce_worker_core_bounds'] = False
 
 # To allow visual checking - log file not used in test
 log_file = 'ensemble_mpi_runners_supernode_uneven_comms_' + str(comms) + '_wrks_' + str(nworkers) + '.log'

libensemble/tests/regression_tests/test_mpi_runners_zrw_subnode_uneven.py

@@ -35,7 +35,7 @@
 
 libE_specs['zero_resource_workers'] = [1]
 libE_specs['central_mode'] = True
-libE_specs['allow_oversubscribe'] = False
+libE_specs['enforce_worker_core_bounds'] = False
 
 # To allow visual checking - log file not used in test
 log_file = 'ensemble_mpi_runners_zrw_subnode_uneven_comms_' + str(comms) + '_wrks_' + str(nworkers) + '.log'

libensemble/tests/regression_tests/test_mpi_runners_zrw_supernode_uneven.py

@@ -33,7 +33,7 @@
 
 libE_specs['zero_resource_workers'] = [1]
 libE_specs['central_mode'] = True
-libE_specs['allow_oversubscribe'] = False
+libE_specs['enforce_worker_core_bounds'] = False
 
 # To allow visual checking - log file not used in test
 log_file = 'ensemble_mpi_runners_zrw_supernode_uneven_comms_' + str(comms) + '_wrks_' + str(nworkers) + '.log'

libensemble/tests/regression_tests/test_zero_resource_workers.py

@@ -35,7 +35,7 @@
 
 libE_specs['zero_resource_workers'] = [1]
 libE_specs['central_mode'] = True
-libE_specs['allow_oversubscribe'] = False
+libE_specs['enforce_worker_core_bounds'] = False
 
 # To allow visual checking - log file not used in test
 log_file = 'ensemble_zrw_comms_' + str(comms) + '_wrks_' + str(nworkers) + '.log'

libensemble/tests/regression_tests/test_zero_resource_workers_subnode.py

@@ -35,7 +35,7 @@
 
 libE_specs['zero_resource_workers'] = [1]
 libE_specs['central_mode'] = True
-libE_specs['allow_oversubscribe'] = False
+libE_specs['enforce_worker_core_bounds'] = False
 
 # To allow visual checking - log file not used in test
 log_file = 'ensemble_zrw_subnode_comms_' + str(comms) + '_wrks_' + str(nworkers) + '.log'

libensemble/tests/scaling_tests/forces/run_libe_forces.py

@@ -39,10 +39,10 @@
 # Create executor and register sim to it.
 if USE_BALSAM:
     from libensemble.executors.balsam_executor import BalsamMPIExecutor
-    exctr = BalsamMPIExecutor()  # Use allow_oversubscribe=False to prevent oversubscription
+    exctr = BalsamMPIExecutor()
 else:
     from libensemble.executors.mpi_executor import MPIExecutor
-    exctr = MPIExecutor()  # Use allow_oversubscribe=False to prevent oversubscription
+    exctr = MPIExecutor()
 exctr.register_calc(full_path=sim_app, calc_type='sim')
 
 # Note: Attributes such as kill_rate are to control forces tests, this would not be a typical parameter.

libensemble/tools/fields_keys.py

@@ -62,7 +62,7 @@
     libE_spec_gen_dir_keys
 
 allowed_libE_spec_keys = ['abort_on_exception',             #
-                          'allow_oversubscribe',            #
+                          'enforce_worker_core_bounds',     #
                           'authkey',                        #
                           'disable_resource_manager',       #
                           'central_mode',                   #