Merge 456b537 into d4a2607

Libensemble · Apr 27, 2021 · ab5e08e · ab5e08e
2 parents d4a2607 + 456b537
commit ab5e08e
Show file tree

Hide file tree

Showing 15 changed files with 60 additions and 24 deletions.
diff --git a/.github/workflows/libE-ci.yml b/.github/workflows/libE-ci.yml
@@ -83,6 +83,7 @@ jobs:
             pip install DFO-LS
             pip install mpmath
             pip install deap
+            pip install Cython --install-option="--no-cython-compile"
             python -m pip install --upgrade git+https://github.com/mosesyhc/surmise.git
             pip install flake8
             pip install coverage

diff --git a/README.rst b/README.rst
@@ -10,7 +10,7 @@
 .. image:: https://travis-ci.org/Libensemble/libensemble.svg?branch=master
    :target: https://travis-ci.org/Libensemble/libensemble
 
-.. image:: https://github.com/Libensemble/libensemble/workflows/init-libEnsemble-CI/badge.svg?branch=develop
+.. image:: https://github.com/Libensemble/libensemble/workflows/libEnsemble-CI/badge.svg?branch=master
    :target: https://github.com/Libensemble/libensemble/actions
 
 .. image:: https://coveralls.io/repos/github/Libensemble/libensemble/badge.svg?branch=master
@@ -42,10 +42,10 @@ libEnsemble aims for the following:
 • Portability and flexibility
 • Exploitation of persistent data/control flow
 
-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 user selects or supplies a *generator function* that produces simulation
+input and a *simulator function* that performs and monitors
+simulations. For example, the generator 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.
 

diff --git a/docs/function_guides/allocator.rst b/docs/function_guides/allocator.rst
@@ -2,7 +2,7 @@ Allocation Functions
 ====================
 
 Although the included allocation functions, or ``alloc_f``'s are sufficient for
-most users, those who want to fine-tune how data is passed to their ``gen_f``
+most users, those who want to fine-tune how data or resources are allocated to their ``gen_f``
 and ``sim_f`` can write their own. The ``alloc_f`` is unique since it is called
 by the libEnsemble's manager instead of a worker.
 
@@ -94,9 +94,16 @@ In practice, the structure of many allocation functions resemble::
 
     return Work, persis_info
 
-The Work dictionary is returned to the manager with ``persis_info``. If ``1``
+The Work dictionary is returned to the manager alongside ``persis_info``. If ``1``
 is returned as third value, this instructs the run to stop.
 
+For allocation functions, as with the user functions, the level of complexity can
+vary widely. Various scheduling and work distribution features are available in
+the existing allocation functions, including prioritization of simulations,
+returning evaluation outputs to the generator immediately or in batch, assigning
+varying resource sets to evaluations, and other methods of fine-tuned control over
+the data available to other user functions.
+
 .. note:: An error occurs when the ``alloc_f`` returns nothing while
           all workers are idle
 

diff --git a/docs/function_guides/function_guide_index.rst b/docs/function_guides/function_guide_index.rst
@@ -2,15 +2,25 @@
 Writing User Functions
 ======================
 
-libEnsemble coordinates ensembles of calculations performed by three main
-functions: a :ref:`Generator Function<api_gen_f>`, a :ref:`Simulator Function<api_sim_f>`,
-and an :ref:`Allocation Function<api_alloc_f>`, or ``gen_f``, ``sim_f``, and
-``alloc_f`` respectively. These are all referred to as User Functions. Although
-libEnsemble includes several ready-to-use User Functions like
-:doc:`APOSMM<../examples/aposmm>`, it's expected many users will write their own or
-adjust included functions for their own use-cases.
-These guides describe common development patterns and optional components for
-each kind of User Function.
+An early part of libEnsemble's design was the decision to divide ensemble steps into
+generator and simulator routines as an intuitive way to express problems and their inherent
+dependencies.
+
+libEnsemble was consequently developed to coordinate ensemble computations defined by
+
+• a *generator function* that produces simulation inputs,
+• a *simulator function* that performs and monitors simulations, and
+• an *allocation function* that determines when (and with what resources) the other two functions should be invoked.
+
+Since each of these functions is supplied or selected by libEnsemble's users, they are
+typically referred to as *user functions*. User functions need not be written only in
+Python: they can (and often do) depend on routines from other
+languages. The only restriction for user functions is that their inputs and outputs conform
+to the :ref:`user function APIs<user_api>`. Therefore, the level of computation and complexity of any user function
+can vary dramatically based on the user's needs.
+
+These guides describe common development
+patterns and optional components for each kind of User Function:
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/function_guides/generator.rst b/docs/function_guides/generator.rst
@@ -36,6 +36,11 @@ alongside ``persis_info``::
 
         return local_H_out, persis_info
 
+Between the output array definition and the function returning, any level and complexity
+of computation can be performed. Users are encouraged to use the :doc:`executor<../executor/overview>`
+to submit applications to parallel resources if necessary, or plug in components from
+any other libraries to serve their needs.
+
 .. note::
 
     State ``gen_f`` information like checkpointing should be
@@ -57,13 +62,15 @@ empty.
 Many users prefer persistent generators since they do not need to be
 re-initialized every time their past work is completed and evaluated by a
 simulation, and an can evaluate returned simulation results over the course of
-an entire libEnsemble routine as a single function instance.
+an entire libEnsemble routine as a single function instance. The :doc:`APOSMM<../examples/aposmm>`
+optimization generator function included with libEnsemble is persistent so it can
+maintain multiple local optimization subprocesses based on results from complete simulations.
 
 Functions for a persistent generator to communicate directly with the manager
 are available in the :ref:`libensemble.tools.gen_support<p_gen_routines>` module.
 Additional necessary resources are the status tags ``STOP_TAG``, ``PERSIS_STOP``, and
-``FINISHED_PERSISTENT_GEN_TAG`` from ``libensemble.message_numbers``, with return
-values from the ``gen_support`` functions compared to these tags to determine when
+``FINISHED_PERSISTENT_GEN_TAG`` from ``libensemble.message_numbers``. Return
+values from the ``gen_support`` functions are compared to these tags to determine when
 the generator should break its loop and return.
 
 Implementing the above functions is relatively simple:

diff --git a/docs/function_guides/simulator.rst b/docs/function_guides/simulator.rst
@@ -25,6 +25,11 @@ with ``persis_info`` should be familiar::
 
     return local_H_out, persis_info
 
+Between the output array definition and the function returning, any level and complexity
+of computation can be performed. Users are encouraged to use the :doc:`executor<../executor/overview>`
+to submit applications to parallel resources if necessary, or plug in components from
+other libraries to serve their needs.
+
 Simulator functions can also return a :doc:`calc_status<../data_structures/calc_status>`
 integer attribute from the ``libensemble.message_numbers`` module to be logged.
 

diff --git a/docs/images/centralized_new_detailed.png b/docs/images/centralized_new_detailed.png
diff --git a/docs/images/centralized_new_detailed_balsam.png b/docs/images/centralized_new_detailed_balsam.png
diff --git a/docs/images/diagram_with_persis.png b/docs/images/diagram_with_persis.png
diff --git a/docs/images/distributed_new_detailed.png b/docs/images/distributed_new_detailed.png
diff --git a/docs/images/numparam.png b/docs/images/numparam.png
diff --git a/docs/overview_usecases.rst b/docs/overview_usecases.rst
@@ -24,6 +24,11 @@ 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``.
 
+.. image:: images/diagram_with_persis.png
+ :alt: libE component diagram
+ :align: center
+ :scale: 40
+
 Example Use Cases
 ~~~~~~~~~~~~~~~~~
 .. begin_usecases_rst_tag

diff --git a/docs/platforms/platforms_index.rst b/docs/platforms/platforms_index.rst
@@ -13,7 +13,7 @@ The first mode we refer to as **central** mode, where the libEnsemble manager an
 are grouped on to one or more dedicated nodes. Workers' launch applications on to
 the remaining allocated nodes:
 
-.. image:: ../images/centralized_new.png
+.. image:: ../images/centralized_new_detailed.png
     :alt: centralized
     :scale: 30
     :align: center
@@ -22,7 +22,7 @@ Alternatively, in **distributed** mode, libEnsemble is launched with the process
 spread across nodes. The worker processes will share nodes with the applications
 they launch. There may be multiple nodes per worker, or multiple workers per node:
 
-.. image:: ../images/distributed_new.png
+.. image:: ../images/distributed_new_detailed.png
     :alt: distributed
     :scale: 30
     :align: center
@@ -96,7 +96,7 @@ launch nodes and launches tasks submitted by workers. Running libEnsemble on the
 nodes is potentially more scalable and will better manage ``sim_f`` and ``gen_f`` functions
 that contain considerable computational work or I/O.
 
-    .. image:: ../images/central_balsam.png
+    .. image:: ../images/centralized_new_detailed_balsam.png
         :alt: central_balsam
         :scale: 40
         :align: center

diff --git a/docs/platforms/theta.rst b/docs/platforms/theta.rst
@@ -125,7 +125,7 @@ On Theta, libEnsemble can be launched to two locations:
     Balsam Executor interfaces with Balsam running on a MOM node for dynamic
     user-application submission to the compute nodes.
 
-    .. image:: ../images/central_balsam.png
+    .. image:: ../images/centralized_new_detailed_balsam.png
         :alt: central_Balsam
         :scale: 40
         :align: center

diff --git a/docs/sim_gen_alloc_funcs.rst b/docs/sim_gen_alloc_funcs.rst
@@ -1,7 +1,8 @@
 User Function API
 -----------------
+.. _user_api:
 
-libEnsemble requires functions for generation, simulation and allocation.
+libEnsemble requires functions for generation, simulation, and allocation.
 
 While libEnsemble provides a default allocation function, the sim and gen functions
 must be specified. The required API and example arguments are given here.