ASK/TELL DEVELOP

.codecov.yml

@@ -4,3 +4,4 @@ ignore:
   - "libensemble/tools/live_data/*"
   - "libensemble/sim_funcs/executor_hworld.py"
   - "libensemble/gen_funcs/persistent_tasmanian.py"
+  - "libensemble/gen_classes/gpCAM.py"

.flake8

@@ -38,6 +38,7 @@ per-file-ignores =
 
         # Need to set something before the APOSMM import
         libensemble/tests/regression_tests/test_persistent_aposmm*:E402
+        libensemble/tests/regression_tests/test_asktell_aposmm_nlopt.py:E402
         libensemble/tests/regression_tests/test_persistent_gp_multitask_ax.py:E402
         libensemble/tests/functionality_tests/test_uniform_sampling_then_persistent_localopt_runs.py:E402
         libensemble/tests/functionality_tests/test_stats_output.py:E402

.github/workflows/extra.yml

@@ -101,18 +101,23 @@ jobs:
             pip install -r install/misc_feature_requirements.txt
             source install/install_ibcdfo.sh
             conda install numpy scipy
-
-        - name: Install libEnsemble, flake8, lock environment
-          run: |
-            pip install -e .
-            flake8 libensemble
+            conda install -c conda-forge pytorch-cpu
+            pip install --upgrade-strategy=only-if-needed git+https://github.com/xopt-org/xopt.git@generator_standard
+            pip install --no-deps git+https://github.com/optimas-org/optimas.git@main
 
         - name: Remove test using octave, gpcam on Python 3.13
           if: matrix.python-version >= '3.13'
           run: |
             rm ./libensemble/tests/regression_tests/test_persistent_fd_param_finder.py # needs octave, which doesn't yet support 3.13
             rm ./libensemble/tests/regression_tests/test_persistent_aposmm_external_localopt.py # needs octave, which doesn't yet support 3.13
             rm ./libensemble/tests/regression_tests/test_gpCAM.py # needs gpcam, which doesn't build on 3.13
+            rm ./libensemble/tests/regression_tests/test_asktell_gpCAM.py # needs gpcam, which doesn't build on 3.13
+
+        - name: Install libEnsemble, flake8
+          run: |
+            pip install git+https://github.com/campa-consortium/gest-api@main
+            pip install -e .
+            flake8 libensemble
 
         - name: Install redis/proxystore
           run: |

docs/function_guides/ask_tell_generator.rst

@@ -0,0 +1,21 @@
+
+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/gest-api
+
+libEnsemble is in the process of supporting generator objects that implement the following interface:
+
+.. automodule:: generators
+  :members: Generator LibensembleGenerator
+  :undoc-members:
+
+.. autoclass:: Generator
+  :member-order: bysource
+  :members:

docs/function_guides/function_guide_index.rst

@@ -13,6 +13,7 @@ These guides describe common development patterns and optional components:
    :caption: Writing User Functions
 
    generator
+   ask_tell_generator
    simulator
    allocator
    sim_gen_alloc_api

docs/index.rst

@@ -26,6 +26,7 @@
    tutorials/gpcam_tutorial
    tutorials/aposmm_tutorial
    tutorials/calib_cancel_tutorial
+   tutorials/xopt_bayesian_gen
 
 .. toctree::
    :maxdepth: 1

docs/tutorials/tutorials.rst

@@ -9,3 +9,4 @@ Tutorials
    gpcam_tutorial
    aposmm_tutorial
    calib_cancel_tutorial
+   xopt_bayesian_gen

docs/tutorials/xopt_bayesian_gen.rst

@@ -0,0 +1,171 @@
+Bayesian Optimization with Xopt
+===============================
+
+**Requires**: libensemble, xopt, gest-api
+
+This tutorial demonstrates using Xopt's Bayesian **ExpectedImprovementGenerator** with libEnsemble.
+
+We'll show two approaches:
+
+1. Using an xopt-style simulator (callable function)
+2. Using a libEnsemble-style simulator function
+
+|Open in Colab|
+
+Imports
+-------
+
+.. code-block:: python
+
+    import numpy as np
+    from gest_api.vocs import VOCS
+    from xopt.generators.bayesian.expected_improvement import ExpectedImprovementGenerator
+
+    from libensemble import Ensemble
+    from libensemble.alloc_funcs.start_only_persistent import only_persistent_gens as alloc_f
+    from libensemble.specs import AllocSpecs, ExitCriteria, GenSpecs, LibeSpecs, SimSpecs
+
+Simulator Function
+------------------
+
+First, we define the xopt-style simulator function.
+
+This is a basic function just to show how it works.
+
+.. code-block:: python
+
+    def test_callable(input_dict: dict) -> dict:
+        """Single-objective callable test function"""
+        assert isinstance(input_dict, dict)
+        x1 = input_dict["x1"]
+        x2 = input_dict["x2"]
+        y1 = x2
+        c1 = x1
+        return {"y1": y1, "c1": c1}
+
+Setup
+-----
+
+Define the VOCS specification and set up the generator.
+
+.. code-block:: python
+
+    libE_specs = LibeSpecs(gen_on_manager=True, nworkers=4)
+
+    vocs = VOCS(
+        variables={"x1": [0, 1.0], "x2": [0, 10.0]},
+        objectives={"y1": "MINIMIZE"},
+        constraints={"c1": ["GREATER_THAN", 0.5]},
+        constants={"constant1": 1.0},
+    )
+
+    gen = ExpectedImprovementGenerator(vocs=vocs)
+
+    # Create 4 initial points and ingest them
+    initial_points = [
+        {"x1": 0.2, "x2": 2.0, "y1": 2.0, "c1": 0.2},
+        {"x1": 0.5, "x2": 5.0, "y1": 5.0, "c1": 0.5},
+        {"x1": 0.7, "x2": 7.0, "y1": 7.0, "c1": 0.7},
+        {"x1": 0.9, "x2": 9.0, "y1": 9.0, "c1": 0.9},
+    ]
+    gen.ingest(initial_points)
+
+Define libEnsemble specifications. Note the gen_specs and sim_specs are set using vocs.
+
+Approach 1: Using Xopt-style Simulator (Callable Function)
+-----------------------------------------------------------
+
+The simulator is a simple callable function that takes a dictionary of inputs and returns a dictionary of outputs.
+
+.. code-block:: python
+
+    gen_specs = GenSpecs(
+        generator=gen,
+        vocs=vocs,
+    )
+
+    # Note: using 'simulator' parameter for xopt-style callable
+    sim_specs = SimSpecs(
+        simulator=test_callable,
+        vocs=vocs,
+    )
+
+    alloc_specs = AllocSpecs(alloc_f=alloc_f)
+    exit_criteria = ExitCriteria(sim_max=12)
+
+    workflow = Ensemble(
+        libE_specs=libE_specs,
+        sim_specs=sim_specs,
+        alloc_specs=alloc_specs,
+        gen_specs=gen_specs,
+        exit_criteria=exit_criteria,
+    )
+
+    H, _, _ = workflow.run()
+
+    if workflow.is_manager:
+        print(f"Completed {len(H)} simulations")
+        print(H[["x1", "x2", "y1", "c1"]])
+        assert np.array_equal(H["y1"], H["x2"])
+        assert np.array_equal(H["c1"], H["x1"])
+
+Approach 2: Using libEnsemble-style Simulator Function
+-------------------------------------------------------
+
+Now we define the libEnsemble-style simulator function and use it in the workflow.
+
+.. code-block:: python
+
+    def test_sim(H, persis_info, sim_specs, _):
+        """
+        Simple sim function that takes x1, x2, constant1 from H and returns y1, c1.
+        Logic: y1 = x2, c1 = x1
+        """
+        batch = len(H)
+        H_o = np.zeros(batch, dtype=sim_specs["out"])
+
+        for i in range(batch):
+            x1 = H["x1"][i]
+            x2 = H["x2"][i]
+            H_o["y1"][i] = x2
+            H_o["c1"][i] = x1
+
+        return H_o, persis_info
+
+Reset generator and change to libEnsemble-style simulator:
+
+.. code-block:: python
+
+    # Reset generator and change to libEnsemble-style simulator
+    gen = ExpectedImprovementGenerator(vocs=vocs)
+    gen.ingest(initial_points)
+
+    gen_specs = GenSpecs(
+        generator=gen,
+        vocs=vocs,
+    )
+
+    # Note: using 'sim_f' parameter for libEnsemble-style function
+    sim_specs = SimSpecs(
+        sim_f=test_sim,
+        vocs=vocs,
+    )
+
+    workflow = Ensemble(
+        libE_specs=libE_specs,
+        sim_specs=sim_specs,
+        alloc_specs=alloc_specs,
+        gen_specs=gen_specs,
+        exit_criteria=exit_criteria,
+    )
+
+    H, _, _ = workflow.run()
+
+    if workflow.is_manager:
+        print(f"Completed {len(H)} simulations")
+        print(H[["x1", "x2", "y1", "c1"]])
+        assert np.array_equal(H["y1"], H["x2"])
+        assert np.array_equal(H["c1"], H["x1"])
+
+.. |Open in Colab| image:: https://colab.research.google.com/assets/colab-badge.svg
+  :target:  http://colab.research.google.com/github/Libensemble/libensemble/blob/examples/xopt_generators/examples/tutorials/xopt_bayesian_gen/xopt_EI_example.ipynb