Docs/generator section refactor

.github/dependabot.yml

@@ -36,4 +36,3 @@ updates:
       submodule-updates:
         patterns:
           - "*"
-

README.rst

@@ -10,7 +10,8 @@
 libEnsemble: A complete toolkit for dynamic ensembles of calculations
 =====================================================================
 
-Adaptive, portable, and scalable software for connecting "deciders" to experiments or simulations.
+libEnsemble empowers model-driven ensembles to solve design, decision,
+and inference problems on the world's leading supercomputers such as Frontier, Aurora, and Perlmutter.
 
 • **Dynamic ensembles**: Generate parallel tasks on-the-fly based on previous computations.
 • **Extreme portability and scaling**: Run on or across laptops, clusters, and leadership-class machines.
@@ -19,8 +20,6 @@ Adaptive, portable, and scalable software for connecting "deciders" to experimen
 • **Data-flow between tasks**: Running ensemble members can send and receive data.
 • **Low start-up cost**: No additional background services or processes required.
 
-libEnsemble is effective at solving design, decision, and inference problems on parallel resources.
-
 `Quickstart`_
 
 Installation
@@ -97,7 +96,7 @@ Try some other examples live in Colab.
 | Optimization example that finds multiple minima.              | |Optimization example|              |
 +---------------------------------------------------------------+-------------------------------------+
 
-There are many more examples in the `regression tests`_.
+There are many more examples in the `Community Examples repository`_ and `regression tests`_.
 
 Resources
 =========

docs/conf.py

@@ -30,6 +30,7 @@ class Mock(MagicMock):
     def __getattr__(cls, name):
         return MagicMock()
 
+
 autodoc_mock_imports = ["ax", "balsam", "gpcam", "IPython", "matplotlib", "pandas", "scipy", "surmise"]
 
 MOCK_MODULES = [
@@ -42,11 +43,22 @@ def __getattr__(cls, name):
     "PETSc",
     "petsc4py",
     "psutil",
+    "pyre_extensions",
     "Tasmanian",
+    "torch",
 ]
 
 sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
 
+
+class AxParameterWarning(Warning):  # Ensure it's a real warning subclass
+    pass
+
+
+# Fix only `AxParameterWarning` while keeping `ax` mocked
+sys.modules["ax.exceptions.core"] = MagicMock()
+sys.modules["ax.exceptions.core"].AxParameterWarning = AxParameterWarning
+
 # from libensemble import *
 # from libensemble.alloc_funcs import *
 # from libensemble.gen_funcs import *
@@ -65,6 +77,7 @@ def __getattr__(cls, name):
 sys.path.append(os.path.abspath("../libensemble/tools/live_data"))
 sys.path.append(os.path.abspath("../libensemble/executors"))
 sys.path.append(os.path.abspath("../libensemble/resources"))
+sys.path.append(os.path.abspath("../libensemble/tests/scaling_tests/forces"))
 # print(sys.path)
 
 # -- General configuration ------------------------------------------------
@@ -216,8 +229,14 @@ def __getattr__(cls, name):
 # html_static_path = []
 
 
+def remove_noqa(app, what, name, obj, options, lines):
+    for i, line in enumerate(lines):
+        lines[i] = line.replace("# noqa", "")
+
+
 def setup(app):
     app.add_css_file("my_theme.css")
+    app.connect("autodoc-process-docstring", remove_noqa)
 
 
 # Custom sidebar templates, must be a dictionary that maps document names

docs/examples/alloc_funcs.rst

@@ -5,11 +5,15 @@ Allocation Functions
 
 Below are example allocation functions available in libEnsemble.
 
+Many users use these unmodified.
+
 .. IMPORTANT::
   See the API for allocation functions :ref:`here<api_alloc_f>`.
 
 .. note::
-   The default allocation function is ``give_sim_work_first``.
+   The default allocation function (for non-persistent generators) is :ref:`give_sim_work_first<gswf_label>`.
+
+   The most commonly used (for persistent generators) is :ref:`start_only_persistent<start_only_persistent_label>`.
 
 .. role:: underline
     :class: underline
@@ -59,3 +63,39 @@ start_persistent_local_opt_gens
 .. automodule:: start_persistent_local_opt_gens
   :members:
   :undoc-members:
+
+fast_alloc_and_pausing
+----------------------
+.. automodule:: fast_alloc_and_pausing
+   :members:
+   :undoc-members:
+
+only_one_gen_alloc
+------------------
+.. automodule:: only_one_gen_alloc
+   :members:
+   :undoc-members:
+
+start_fd_persistent
+-------------------
+.. automodule:: start_fd_persistent
+   :members:
+   :undoc-members:
+
+persistent_aposmm_alloc
+-----------------------
+.. automodule:: persistent_aposmm_alloc
+   :members:
+   :undoc-members:
+
+give_pregenerated_work
+----------------------
+.. automodule:: give_pregenerated_work
+   :members:
+   :undoc-members:
+
+inverse_bayes_allocf
+--------------------
+.. automodule:: inverse_bayes_allocf
+   :members:
+   :undoc-members:

docs/examples/aposmm.rst

@@ -2,8 +2,16 @@ APOSMM
 ------
 
 Asynchronously Parallel Optimization Solver for finding Multiple Minima
-(APOSMM) coordinates concurrent local optimization runs in order to identify
-many local minima.
+(APOSMM) coordinates concurrent local optimization runs to identify
+many local minima faster on parallel hardware.
+
+Supported local optimization routines include:
+
+  - DFO-LS_ Derivative-free solver for (bound constrained) nonlinear least-squares minimization
+  - NLopt_ Library for nonlinear optimization, providing a common interface for various methods
+  - `scipy.optimize`_ Open-source solvers for nonlinear problems, linear programming,
+    constrained and nonlinear least-squares, root finding, and curve fitting.
+  - `PETSc/TAO`_ Routines for the scalable (parallel) solution of scientific applications
 
 Required: mpmath_, SciPy_
 
@@ -12,32 +20,26 @@ Optional (see below): petsc4py_, nlopt_, DFO-LS_
 Configuring APOSMM
 ^^^^^^^^^^^^^^^^^^
 
-APOSMM works with a choice of optimizers, some requiring external packages. To
-import the optimization packages (and their dependencies) at a global level
-(recommended), add the following lines in the calling script before importing
-APOSMM::
+APOSMM works with a choice of optimizers, some requiring external packages. Specify
+them on a global level before importing APOSMM::
 
     import libensemble.gen_funcs
     libensemble.gen_funcs.rc.aposmm_optimizers = <optimizers>
 
-where ``optimizers`` is a string (or list of strings) from the available options:
+where ``optimizers`` is a string (or list-of-strings) from:
 
 ``"petsc"``, ``"nlopt"``, ``"dfols"``, ``"scipy"``, ``"external"``
 
-.. dropdown:: Issues with ensemble hanging or failed simulations?
-
-    Note that if using **mpi4py** comms, PETSc must be imported at the global
-    level or the ensemble may hang.
+.. dropdown:: Issues with ensemble hanging or failed simulations with PETSc?
 
-    Exception: In the case that you are using the MPIExecutor or other MPI inside
-    a user function and you are using Open MPI, then you must:
+    If using the MPIExecutor or other MPI routines
+    and your MPI backend is Open MPI, then you must:
 
-    - Use ``local`` comms for libEnsemble (not ``mpi4py``)
-    - Must **NOT** include the *rc* line above
+    - Use ``local`` comms for libEnsemble (no ``mpirun``, ``mpiexec``, ``aprun``, etc.).
+    - Must **NOT** include the *aposmm_optimizers* line above.
 
-    This is because PETSc imports MPI, and a global import of PETSc would result
-    in nested MPI (which is not supported by Open MPI). When the above line is
-    not used, an import local to the optimization function will happen.
+    This is because PETSc imports MPI, and a global import of PETSc results
+    in nested MPI (which is not supported by Open MPI).
 
 To see the optimization algorithms supported, see `LocalOptInterfacer`_.
 
@@ -49,17 +51,19 @@ Persistent APOSMM
 ^^^^^^^^^^^^^^^^^
 
 .. automodule:: persistent_aposmm
-  :members:
+  :members: aposmm
   :undoc-members:
 
 LocalOptInterfacer
 ^^^^^^^^^^^^^^^^^^
 .. automodule:: aposmm_localopt_support
-  :members:
+  :members: LocalOptInterfacer
   :undoc-members:
 
 .. _DFO-LS: https://github.com/numericalalgorithmsgroup/dfols
 .. _mpmath: https://pypi.org/project/mpmath
 .. _nlopt: https://nlopt.readthedocs.io/en/latest/
 .. _petsc4py: https://bitbucket.org/petsc/petsc4py
 .. _SciPy: https://pypi.org/project/scipy
+.. _PETSc/TAO: http://www.mcs.anl.gov/petsc
+.. _scipy.optimize: https://docs.scipy.org/doc/scipy/reference/optimize.html

docs/examples/ax_multitask.rst

@@ -1,16 +1,18 @@
 persistent_ax_multitask
 -----------------------
 
-Required: Ax_ version <=0.4.0
+Required: `ax-platform`_>=0.5.0
+
+Example usage: gp_multitask_ax_
 
 To install::
 
-    pip install "ax-platform<=0.4.0"
+    pip install ax-platform
 
 An example of the Ax multitask GP.
 
 .. automodule:: persistent_ax_multitask
   :members:
-  :no-undoc-members:
 
-.. _Ax: https://github.com/facebook/Ax
+.. _`ax-platform`: https://github.com/facebook/Ax
+.. _gp_multitask_ax: https://github.com/Libensemble/libensemble/blob/main/libensemble/tests/regression_tests/test_persistent_gp_multitask_ax.py

docs/examples/calling_scripts.rst

@@ -27,17 +27,22 @@ Electrostatic Forces with Executor
 
 These examples are 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 Executor, then submitted
-for execution in the ``sim_f``. Note the use of the ``parse_args()`` and
-``save_libE_output()`` convenience functions from the :doc:`tools<../utilities>` module
-in the first calling script.
+application is registered with the MPIExecutor, then submitted
+for execution in the ``sim_f``. Note the use of the ``parse_args=True`` which allows
+reading arguments such as the number of workers from the command line.
 
 Traditional Version
 ~~~~~~~~~~~~~~~~~~~
 
-..  literalinclude:: ../../libensemble/tests/scaling_tests/forces/forces_adv/run_libe_forces.py
+Run using five workers with::
+
+    python run_libe_forces.py -n 5
+
+One worker runs a persistent generator and the other four run the forces simulations.
+
+..  literalinclude:: ../../libensemble/tests/scaling_tests/forces/forces_simple/run_libe_forces.py
     :language: python
-    :caption: tests/scaling_tests/forces/forces_adv/run_libe_forces.py
+    :caption: tests/scaling_tests/forces/forces_simple/run_libe_forces.py
     :linenos:
 
 Object + yaml Version

docs/examples/examples_index.rst

@@ -1,12 +1,10 @@
-Example User Functions and Calling Scripts
-==========================================
+Overview of Examples
+====================
 
 Here we give example generation, simulation, and allocation functions for
 libEnsemble, as well as example calling scripts.
 
-Additional examples from libEnsemble's users are available in
-the `libEnsemble Community Repository`_, with corresponding generator documentation available
-:doc:`here<community:index>`.
+The examples come from the libEnsemble repository and the `libEnsemble Community Repository`_.
 
 .. toctree::
    :maxdepth: 2