start ask/tell generators example docs, some tiny adjustments

Libensemble · Sep 13, 2024 · fe383fb · fe383fb
1 parent c7d1cb1
commit fe383fb
Show file tree

Hide file tree

Showing 11 changed files with 95 additions and 4 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -32,8 +32,10 @@ def __getattr__(cls, name):
 
 
 MOCK_MODULES = [
+    "ax",
     "argparse",
     "dfols",
+    "gpcam",
     "IPython",
     "IPython.display",
     "IPython.core",
@@ -71,6 +73,7 @@ def __getattr__(cls, name):
 ##sys.path.append(os.path.abspath('../libensemble'))
 sys.path.append(os.path.abspath("../libensemble/alloc_funcs"))
 sys.path.append(os.path.abspath("../libensemble/gen_funcs"))
+sys.path.append(os.path.abspath("../libensemble/gen_classes"))
 sys.path.append(os.path.abspath("../libensemble/sim_funcs"))
 sys.path.append(os.path.abspath("../libensemble/comms"))
 sys.path.append(os.path.abspath("../libensemble/utils"))

diff --git a/docs/examples/asktell/aposmm.rst b/docs/examples/asktell/aposmm.rst
@@ -0,0 +1,17 @@
+APOSMM
+------
+
+Asynchronously Parallel Optimization Solver for finding Multiple Minima
+(APOSMM) coordinates concurrent local optimization runs in order to identify
+many local minima.
+
+This version has been created to adhere to the CAMPA
+generator standard: https://github.com/campa-consortium/generator_standard
+and *can be used outside of libEnsemble*.
+
+See :doc:`the APOSMM docs<../aposmm>` for implementation, configuration, and more information.
+
+.. automodule:: gen_classes.aposmm
+  :members:
+  :undoc-members:
+  :inherited-members:
diff --git a/docs/examples/asktell/gpCAM.rst b/docs/examples/asktell/gpCAM.rst
@@ -0,0 +1,8 @@
+gpCAM
+-----
+
+.. automodule:: gen_classes.gpCAM
+  :members: GP_CAM, GP_CAM_Covar
+  :undoc-members:
+  :inherited-members:
+  :exclude-members: ask_updates
diff --git a/docs/examples/asktell/sampling.rst b/docs/examples/asktell/sampling.rst
@@ -0,0 +1,10 @@
+sampling
+--------
+
+.. automodule:: gen_classes.sampling
+
+.. autoclass:: UniformSample
+  :members: ask_numpy, tell_numpy
+
+.. autoclass:: UniformSampleDicts
+  :members: ask, tell
diff --git a/docs/examples/asktell/surmise.rst b/docs/examples/asktell/surmise.rst
@@ -0,0 +1,6 @@
+Surmise
+-------
+
+.. automodule:: gen_classes.surmise
+  :members:
+  :inherited-members:
diff --git a/docs/examples/examples_index.rst b/docs/examples/examples_index.rst
@@ -12,6 +12,7 @@ the `libEnsemble Community Repository`_, with corresponding generator documentat
    :maxdepth: 2
    :caption: libEnsemble Example Functions:
 
+   gen_classes
    gen_funcs
    sim_funcs
    alloc_funcs

diff --git a/docs/examples/gen_classes.rst b/docs/examples/gen_classes.rst
@@ -0,0 +1,33 @@
+ask/tell Generators
+===================
+
+**BETA - SUBJECT TO CHANGE**
+
+These generators, implementations, methods, and subclasses are in BETA, and
+may change in future releases.
+
+The Generator interface is expected to roughly correspond with CAMPA's standard:
+https://github.com/campa-consortium/generator_standard
+
+.. role:: underline
+    :class: underline
+
+
+.. dropdown:: :underline:`Generator interface`
+
+   .. automodule:: generators
+      :members: Generator LibensembleGenerator
+      :undoc-members:
+
+   .. autoclass:: Generator
+      :member-order: bysource
+      :members:
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Documented ask/tell Generators
+
+   asktell/sampling
+   asktell/aposmm
+   asktell/surmise
+   asktell/gpCAM
diff --git a/docs/examples/gen_funcs.rst b/docs/examples/gen_funcs.rst
@@ -1,5 +1,5 @@
-Generator Functions
-===================
+[Legacy] Generator Functions
+============================
 
 .. include:: ../introduction.rst
     :start-after: example_packages

diff --git a/docs/function_guides/ask_tell_generator.rst b/docs/function_guides/ask_tell_generator.rst
@@ -15,7 +15,9 @@ libEnsemble is in the process of supporting generator objects that implement the
 .. automodule:: generators
   :members: Generator LibensembleGenerator
   :undoc-members:
+  :no-index:
 
 .. autoclass:: Generator
   :member-order: bysource
   :members:
+  :no-index:
diff --git a/docs/index.rst b/docs/index.rst
@@ -30,6 +30,7 @@
    :maxdepth: 1
    :caption: Examples:
 
+   examples/gen_classes
    examples/gen_funcs
    examples/sim_funcs
    examples/alloc_funcs

diff --git a/libensemble/gen_classes/sampling.py b/libensemble/gen_classes/sampling.py
@@ -25,7 +25,17 @@ def _get_user_params(self, user_specs):
 
 class UniformSample(SampleBase):
     """
-    This generator returns ``gen_specs["initial_batch_size"]`` uniformly
+
+    .. code-block:: python
+        :linenos:
+
+            import numpy as np
+            from libensemble.gen_classes import UniformSample
+
+            my_sampler = UniformSample(lb=np.array([0.0, 0.0]), ub=np.array([1.0, 1.0]))
+            sample = my_sampler.ask(5)
+
+    When used with libEnsemble, returns ``gen_specs["initial_batch_size"]`` uniformly
     sampled points the first time it is called. Afterwards, it returns the
     number of points given. This can be used in either a batch or asynchronous
     mode by adjusting the allocation function.
@@ -49,7 +59,7 @@ def tell_numpy(self, calc_in):
 # to the classes above. This is for testing a function written directly with that interface.
 class UniformSampleDicts(Generator):
     """
-    This generator returns ``gen_specs["initial_batch_size"]`` uniformly
+    When used with libEnsemble, returns ``gen_specs["initial_batch_size"]`` uniformly
     sampled points the first time it is called. Afterwards, it returns the
     number of points given. This can be used in either a batch or asynchronous
     mode by adjusting the allocation function.