From fe383fb30489cec937bd0be5cf6e3160e0ed103d Mon Sep 17 00:00:00 2001 From: jlnav Date: Fri, 13 Sep 2024 11:54:32 -0500 Subject: [PATCH] start ask/tell generators example docs, some tiny adjustments --- docs/conf.py | 3 ++ docs/examples/asktell/aposmm.rst | 17 +++++++++++ docs/examples/asktell/gpCAM.rst | 8 +++++ docs/examples/asktell/sampling.rst | 10 +++++++ docs/examples/asktell/surmise.rst | 6 ++++ docs/examples/examples_index.rst | 1 + docs/examples/gen_classes.rst | 33 +++++++++++++++++++++ docs/examples/gen_funcs.rst | 4 +-- docs/function_guides/ask_tell_generator.rst | 2 ++ docs/index.rst | 1 + libensemble/gen_classes/sampling.py | 14 +++++++-- 11 files changed, 95 insertions(+), 4 deletions(-) create mode 100644 docs/examples/asktell/aposmm.rst create mode 100644 docs/examples/asktell/gpCAM.rst create mode 100644 docs/examples/asktell/sampling.rst create mode 100644 docs/examples/asktell/surmise.rst create mode 100644 docs/examples/gen_classes.rst diff --git a/docs/conf.py b/docs/conf.py index bad6e4246..926d59e05 100644 --- 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 new file mode 100644 index 000000000..26bc0ef16 --- /dev/null +++ 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 new file mode 100644 index 000000000..35dc2ab4c --- /dev/null +++ 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 new file mode 100644 index 000000000..79eb91a52 --- /dev/null +++ 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 new file mode 100644 index 000000000..280508d26 --- /dev/null +++ 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 index 88a2df7a5..e9db321c6 100644 --- 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 new file mode 100644 index 000000000..7ae7c81ab --- /dev/null +++ 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 index 8e5af973b..68870d5a0 100644 --- 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 index 6212b24f5..0137d529e 100644 --- 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 index 3cfa749e9..d63953ab1 100644 --- 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 index 166286482..016026169 100644 --- 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.