some cleanup, including replacing some single-quotes with double-quotes, removing some out-of-date commented-out code, fixing some links. adds 3 tentative categories on the Generator functions example page

jlnav · jlnav · commit dfeb9a06982f · 2025-01-07T14:40:10.000-06:00
diff --git a/docs/examples/gen_funcs.rst b/docs/examples/gen_funcs.rst
@@ -10,15 +10,25 @@ Here we list many generator functions included with libEnsemble.
   See the API for generator functions :ref:`here<api_gen_f>`.
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Documented Example Generator Functions:
-
-   sampling
-   aposmm
-   uniform_or_localopt
-   tasmanian
-   fd_param_finder
-   surmise
-   ax_multitask
+  :maxdepth: 2
+  :caption: Sampling
+
+  sampling
+
+.. toctree::
+  :maxdepth: 2
+  :caption: Optimization
+
+  aposmm
+  uniform_or_localopt
+  ax_multitask
+
+.. toctree::
+  :maxdepth: 2
+  :caption: Modeling and Approximation
+
+  tasmanian
+  fd_param_finder
+  surmise
 
 .. _libEnsemble Community Repository: https://github.com/Libensemble/libe-community-examples
diff --git a/docs/examples/sampling.rst b/docs/examples/sampling.rst
@@ -5,7 +5,7 @@ sampling
     :class: underline
 
 .. automodule:: sampling
-  :members: uniform_random_sample latin_hypercube_sample
+  :members: uniform_random_sample, latin_hypercube_sample
   :undoc-members:
 
 .. dropdown:: :underline:`sampling.py`
@@ -17,7 +17,7 @@ sampling
 persistent_sampling
 -------------------
 .. automodule:: persistent_sampling
-  :members: persistent_uniform persistent_uniform_final_update persistent_request_shutdown
+  :members: persistent_uniform, persistent_request_shutdown, persistent_uniform_with_cancellations
   :undoc-members:
 
 .. dropdown:: :underline:`persistent_sampling.py`
diff --git a/docs/examples/sim_funcs.rst b/docs/examples/sim_funcs.rst
@@ -16,7 +16,7 @@ function launching tasks, see the
 six_hump_camel
 --------------
 .. automodule:: six_hump_camel
-  :members:
+  :members: six_hump_camel_simple, persistent_six_hump_camel
   :undoc-members:
 
 .. dropdown:: :underline:`six_hump_camel.py`
@@ -25,12 +25,6 @@ six_hump_camel
       :language: python
       :linenos:
 
-chwirut
--------
-.. automodule:: chwirut1
-  :members:
-  :undoc-members:
-
 noisy_vector_mapping
 --------------------
 .. automodule:: noisy_vector_mapping
@@ -43,12 +37,6 @@ noisy_vector_mapping
       :language: python
       :linenos:
 
-periodic_func
--------------
-.. automodule:: periodic_func
-  :members:
-  :undoc-members:
-
 borehole
 --------
 .. automodule:: borehole
diff --git a/docs/examples/surmise.rst b/docs/examples/surmise.rst
@@ -1,7 +1,8 @@
 persistent_surmise
 ------------------
 
-Required: Surmise_
+Required: Surmise_.
+
 The :doc:`Borehole Calibration tutorial<../tutorials/calib_cancel_tutorial>` uses this generator as an
 example of the capability to cancel pending simulations.
 
diff --git a/docs/examples/tasmanian.rst b/docs/examples/tasmanian.rst
@@ -9,7 +9,7 @@ use either *venv* or *--user* install.
 ``E.g: pip install scikit-build packaging Tasmanian --user``
 
 .. automodule:: persistent_tasmanian
-  :members:
+  :members: sparse_grid_batched, sparse_grid_async
   :undoc-members:
 
 .. role:: underline
@@ -23,4 +23,3 @@ use either *venv* or *--user* install.
 
 .. _pypackaging: https://pypi.org/project/pypackaging/
 .. _scikit-build: https://scikit-build.readthedocs.io/en/latest/index.html
-.. _Tasmanian: https://tasmanian.ornl.gov/
diff --git a/docs/introduction.rst b/docs/introduction.rst
@@ -49,7 +49,7 @@ See the `user guide`_ for more information.
 .. _PETSc/TAO: http://www.mcs.anl.gov/petsc
 .. _scipy.optimize: https://docs.scipy.org/doc/scipy/reference/optimize.html
 .. _Surmise: https://surmise.readthedocs.io/en/latest/index.html
-.. _Tasmanian: https://tasmanian.ornl.gov/
+.. _Tasmanian: https://github.com/ORNL/Tasmanian
 .. _user guide: https://libensemble.readthedocs.io/en/latest/programming_libE.html
 .. _VTMOP: https://github.com/Libensemble/libe-community-examples#vtmop
 .. _WarpX: https://warpx.readthedocs.io/en/latest/
diff --git a/docs/introduction_latex.rst b/docs/introduction_latex.rst
@@ -50,7 +50,7 @@
 .. _Surmise: https://surmise.readthedocs.io/en/latest/index.html
 .. _SWIG: http://swig.org/
 .. _tarball: https://github.com/Libensemble/libensemble/releases/latest
-.. _Tasmanian: https://tasmanian.ornl.gov/
+.. _Tasmanian: https://github.com/ORNL/Tasmanian
 .. _tomli: https://pypi.org/project/tomli/
 .. _tqdm: https://tqdm.github.io/
 .. _user guide: https://libensemble.readthedocs.io/en/latest/programming_libE.html
diff --git a/docs/nitpicky b/docs/nitpicky
@@ -37,6 +37,7 @@ py:class <class 'int'>
 py:class +ScalarType
 py:class +_ScalarType_co
 py:class collections.abc.Sequence
+py:class pathlib._local.Path
 
 # Internal paths that are verified importable but Sphinx can't find
 py:class libensemble.resources.platforms.Aurora
diff --git a/libensemble/gen_funcs/aposmm_localopt_support.py b/libensemble/gen_funcs/aposmm_localopt_support.py
@@ -75,11 +75,11 @@ class LocalOptInterfacer(object):
 
     Currently supported routines are
 
-    - NLopt routines ['LN_SBPLX', 'LN_BOBYQA', 'LN_COBYLA', 'LN_NEWUOA', 'LN_NELDERMEAD', 'LD_MMA']
-    - PETSc/TAO routines ['pounders', 'blmvm', 'nm']
-    - SciPy routines ['scipy_Nelder-Mead', 'scipy_COBYLA', 'scipy_BFGS']
-    - DFOLS ['dfols']
-    - External local optimizer ['external_localopt'] (which use files to pass/receive x/f values)
+    - NLopt [``'LN_SBPLX'``, ``LN_BOBYQA'``, ``'LN_COBYLA'``, ``'LN_NEWUOA'``, ``'LN_NELDERMEAD'``, ``'LD_MMA'``]
+    - PETSc/TAO [``'pounders'``, ``'blmvm'``, ``'nm'``]
+    - SciPy [``'scipy_Nelder-Mead'``, ``'scipy_COBYLA'``, ``'scipy_BFGS'``]
+    - DFOLS [``'dfols'``]
+    - External local optimizer [``'external_localopt'``] (which use files to pass/receive ``x/f`` values)
     """
 
     def __init__(self, user_specs, x0, f0, grad0=None):
diff --git a/libensemble/gen_funcs/persistent_aposmm.py b/libensemble/gen_funcs/persistent_aposmm.py
@@ -37,81 +37,76 @@ def cdist(XA, XB, metric="euclidean"):
 
 def aposmm(H, persis_info, gen_specs, libE_info):
     """
-    APOSMM coordinates multiple local optimization runs, dramatically reducing time-to-solution
-    on parallel systems for discovering multiple minima. APOSMM tracks these fields:
-
-    - ``'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
+    APOSMM coordinates multiple local optimization runs, dramatically reducing time for
+    discovering multiple minima on parallel systems. APOSMM tracks these fields:
+
+    - ``"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
+    - ``"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
 
-    - ``'fvec' [m floats]``: All objective components (if performing a least-squares calculation)
-    - ``'grad' [n floats]``: The gradient (if available) of the objective with respect to `x`.
+    - ``"fvec" [m floats]``: All objective components (if performing a least-squares calculation)
+    - ``"grad" [n floats]``: The gradient (if available) of the objective with respect to `x`.
 
     Note:
 
     - If any of the above fields are desired after a libEnsemble run, name
-      them in ``gen_specs['out']``.
+      them in ``gen_specs["out"]``.
     - If intitializing APOSMM with past function values, make sure to include
-      ``'x'``, ``'x_on_cube'``, ``'f'``, ``'local_pt'``, etc. in
-      ``gen_specs['in']`` (and, of course, include them in the H0 array given
+      ``"x"``, ``"x_on_cube"``, ``"f"``, ``"local_pt"``, etc. in
+      ``gen_specs["in"]`` (and, of course, include them in the H0 array given
       to libensemble).
 
-    Necessary quantities in ``gen_specs['user']`` are:
+    Necessary quantities in ``gen_specs["user"]`` are:
 
-    - ``'lb' [n floats]``: Lower bound on search domain
-    - ``'ub' [n floats]``: Upper bound on search domain
-    - ``'localopt_method' [str]``: Name of an NLopt, PETSc/TAO, or SciPy method
-      (see 'advance_local_run' below for supported methods). When using a SciPy
-      method, must supply ``'opt_return_codes'``, a list of integers that will
+    - ``"lb" [n floats]``: Lower bound on search domain
+    - ``"ub" [n floats]``: Upper bound on search domain
+    - ``"localopt_method" [str]``: Name of an NLopt, PETSc/TAO, or SciPy method
+      (see "advance_local_run" below for supported methods). When using a SciPy
+      method, must supply ``"opt_return_codes"``, a list of integers that will
       be used to determine if the x produced by the localopt method should be
-      ruled a local minimum. (For example, SciPy's COBYLA has a 'status' of 1 if
-      at an optimum, but SciPy's Nelder-Mead and BFGS have a 'status' of 0 if at
+      ruled a local minimum. (For example, SciPy's COBYLA has a "status" of ``1`` if
+      at an optimum, but SciPy's Nelder-Mead and BFGS have a "status" of ``0`` if at
       an optimum.)
-    - ``'initial_sample_size' [int]``: Number of uniformly sampled points
+    - ``"initial_sample_size" [int]``: Number of uniformly sampled points
       to be evaluated before starting the localopt runs. Can be
       zero if no additional sampling is desired, but if zero there must be past
       sim_f values given to libEnsemble in H0.
 
-    Optional ``gen_specs['user']`` entries are:
+    Optional ``gen_specs["user"]`` entries are:
 
-    - ``'sample_points' [numpy array]``: Points to be sampled (original domain).
+    - ``"max_active_runs" [int]``: Bound on number of runs APOSMM is advancing
+    - ``"sample_points" [numpy array]``: Points to be sampled (original domain).
       If more sample points are needed by APOSMM during the course of the
       optimization, points will be drawn uniformly over the domain
-    - ``'components' [int]``: Number of objective components
-    - ``'dist_to_bound_multiple' [float in (0, 1]]``: What fraction of the
+    - ``"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
-    - ``'lhs_divisions' [int]``: Number of Latin hypercube sampling partitions
+    - ``"lhs_divisions" [int]``: Number of Latin hypercube sampling partitions
       (0 or 1 results in uniform sampling)
-    - ``'mu' [float]``: Distance from the boundary that all localopt starting
+    - ``"mu" [float]``: Distance from the boundary that all localopt starting
       points must satisfy
-    - ``'nu' [float]``: Distance from identified minima that all starting
+    - ``"nu" [float]``: Distance from identified minima that all starting
       points must satisfy
-    - ``'rk_const' [float]``: Multiplier in front of the r_k value
-    - ``'max_active_runs' [int]``: Bound on number of runs APOSMM is advancing
-    - ``'stop_after_k_minima' [int]``: Tell APOSMM to stop after this many
+    - ``"rk_const" [float]``: Multiplier in front of the ``r_k`` value
+    - ``"stop_after_k_minima" [int]``: Tell APOSMM to stop after this many
       local minima have been identified by a local optimization run.
-    - ``'stop_after_k_runs' [int]``: Tell APOSMM to stop after this many runs
+    - ``"stop_after_k_runs" [int]``: Tell APOSMM to stop after this many runs
       have ended. (The number of ended runs may be less than the number of
       minima if, for example, a local optimization run ends due to a evaluation
       constraint, but not convergence criteria.)
 
     If the rules in ``decide_where_to_start_localopt`` produces more than
-    ``'max_active_runs'`` in some iteration, then existing runs are prioritized.
+    ``"max_active_runs"`` in some iteration, then existing runs are prioritized.
 
-    And ``gen_specs['user']`` must also contain fields for the given
+    And ``gen_specs["user"]`` must also contain fields for the given
     localopt_method's convergence tolerances (e.g., ``gatol/grtol`` for PETSC/TAO
     or ``ftol_rel`` for NLopt)
 
diff --git a/libensemble/gen_funcs/persistent_fd_param_finder.py b/libensemble/gen_funcs/persistent_fd_param_finder.py
@@ -35,7 +35,7 @@ def build_H0(x_f_pairs, gen_specs, noise_h_mat):
 def fd_param_finder(H, persis_info, gen_specs, libE_info):
     """
     This generation function loops through a set of suitable finite difference
-    parameters for a mapping F from R^n to R^m.
+    parameters for a mapping ``F`` from ``R^n`` to ``R^m``.
 
     .. seealso::
         `test_persistent_fd_param_finder.py` <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_persistent_fd_param_finder.py>`_ # noqa
@@ -56,16 +56,8 @@ def fd_param_finder(H, persis_info, gen_specs, libE_info):
     tag = None
 
     # # Request evaluations of the base point x0 at all p f_inds
-    # H0 = np.zeros(p, dtype=gen_specs["out"])
-    # for j in range(p):
-    #     H0["x"][j] = x0
-    #     H0["x_ind"][j] = -1  # Marking these to know they are the basepoint
-    #     H0["f_ind"][j] = j
-    #     H0["n_ind"][j] = nf/2
-    # tag, Work, calc_in = sendrecv_mgr_worker_msg(comm, H0)
     for i in range(n):
         for j in range(p):
-            # Fhist0[i, j, nf//2] = calc_in["f_val"][calc_in["f_ind"]==j]
             Fhist0[i, j, nf // 2] = U["f0"][j]
 
     x_f_pairs = np.array(np.meshgrid(range(n), range(p))).T.reshape(-1, n)
@@ -75,9 +67,6 @@ def fd_param_finder(H, persis_info, gen_specs, libE_info):
 
     tag, Work, calc_in = ps.send_recv(H0)
 
-    # import matlab.engine
-    # eng = matlab.engine.start_matlab()
-
     # Send nf points for each (x_ind, f_ind) pair
     while tag not in [STOP_TAG, PERSIS_STOP]:
         x_f_pairs = np.unique(calc_in[["x_ind", "f_ind"]])
@@ -90,13 +79,6 @@ def fd_param_finder(H, persis_info, gen_specs, libE_info):
                     logical_conds = (calc_in["x_ind"] == i, calc_in["f_ind"] == j, calc_in["n_ind"] == k)
                     Fhist0[i, j, k] = calc_in["f_val"][np.logical_and.reduce(logical_conds)][0]
 
-            # Compute noise for (i, j):
-            # [Fnoise(i, j), ~, inform(i, j)] = ECnoise(nf-1, Fhist0(i, j, 2:nf));
-            # t = eng.ECnoise(nf+1, matlab.double(Fhist0[i, j, :nf+1]), nargout=3)
-            # # Optional: check to see what would get with 2 fewer evals (requires nf>=4):
-            # [Fnoise2(i, j), ~, inform2(i, j)] = ECnoise(nf-1, Fhist0(i, j, 2:nf));
-
-            # cmd = ["/home/jlarson/software/MATLAB/R2019a/bin/matlab", "-batch",
             cmd = [
                 "octave",
                 "--no-window-system",
diff --git a/libensemble/gen_funcs/persistent_tasmanian.py b/libensemble/gen_funcs/persistent_tasmanian.py
@@ -1,6 +1,6 @@
 """
 A persistent generator using the uncertainty quantification capabilities in
-`Tasmanian <https://tasmanian.ornl.gov/>`_.
+`Tasmanian <https://github.com/ORNL/Tasmanian>`_.
 """
 
 import numpy as np
diff --git a/pyproject.toml b/pyproject.toml
@@ -81,6 +81,7 @@ pre-commit = ">=4.0.1,<5"
 nlopt = ">=2.9.0,<3"
 scipy = ">=1.14.1,<2"
 enchant = ">=2.8.2,<3"  # required for sphinxcontrib-spelling
+ax-platform = "<=0.4.0"
 
 [tool.pixi.dependencies]
 python = ">=3.9,<3.14"
