[WIP] Docs for ask/tell gens

README.rst

@@ -44,46 +44,52 @@ and an exit condition. Run the following four-worker example via ``python this_f
 
     import numpy as np
 
+    from gest_api.vocs import VOCS
+
     from libensemble import Ensemble
-    from libensemble.gen_funcs.sampling import uniform_random_sample
+    from libensemble.gen_classes.sampling import UniformSample
     from libensemble.sim_funcs.six_hump_camel import six_hump_camel
     from libensemble.specs import ExitCriteria, GenSpecs, LibeSpecs, SimSpecs
 
     if __name__ == "__main__":
 
         libE_specs = LibeSpecs(nworkers=4)
 
+        variables_objectives = VOCS(
+            variables={
+                "x0": [-3, 3],
+                "x1": [-2, 2],
+            },
+            objectives={"f": "EXPLORE"},
+        )
+
+        generator = UniformSample(vocs=variables_objectives)
+
         sim_specs = SimSpecs(
             sim_f=six_hump_camel,
-            inputs=["x"],
-            outputs=[("f", float)],
+            vocs=variables_objectives,
         )
 
         gen_specs = GenSpecs(
-            gen_f=uniform_random_sample,
-            outputs=[("x", float, 2)],
-            user={
-                "gen_batch_size": 50,
-                "lb": np.array([-3, -2]),
-                "ub": np.array([3, 2]),
-            },
+            generator=generator,
+            vocs=variables_objectives,
         )
 
         exit_criteria = ExitCriteria(sim_max=100)
 
-        sampling = Ensemble(
+        ensemble = Ensemble(
             libE_specs=libE_specs,
             sim_specs=sim_specs,
             gen_specs=gen_specs,
             exit_criteria=exit_criteria,
         )
 
-        sampling.add_random_streams()
-        sampling.run()
+        ensemble.add_random_streams()
+        ensemble.run()
 
-        if sampling.is_manager:
-            sampling.save_output(__file__)
-            print("Some output data:\n", sampling.H[["x", "f"]][:10])
+        if ensemble.is_manager:
+            ensemble.save_output(__file__)
+            print("Some output data:\n", ensemble.H[["x", "f"]][:10])
 
 |Inline Example|
 

docs/advanced_installation.rst

@@ -1,23 +1,19 @@
 Advanced Installation
 =====================
 
-libEnsemble can be installed from ``pip``, ``Conda``, or ``Spack``.
+libEnsemble can be installed from ``pip``, ``uv``, ``Conda``, or ``Spack``.
 
 libEnsemble requires the following dependencies, which are typically
 automatically installed alongside libEnsemble:
 
 * Python_       ``>= 3.10``
 * NumPy_        ``>= 1.21``
 * psutil_       ``>= 5.9.4``
-* `pydantic`_   ``>= 1.10.12``
+* `pydantic`_   ``>= 2``
 * pyyaml_       ``>= v6.0``
 * tomli_        ``>= 1.2.1``
 
-Given libEnsemble's compiled dependencies, the following installation
-methods each offer a trade-off between convenience and the ability
-to customize builds, including platform-specific optimizations.
-
-We always recommend installing in a virtual environment from Conda or another source.
+We recommend installing in a virtual environment from ``uv``, ``conda`` or another source.
 
 Further recommendations for selected HPC systems are given in the
 :ref:`HPC platform guides<platform-index>`.
@@ -53,6 +49,12 @@ Further recommendations for selected HPC systems are given in the
 
             CC=mpicc MPICC=mpicc pip install mpi4py --no-binary mpi4py
 
+    .. tab-item:: uv
+
+        To install the latest PyPI_ release via uv_::
+
+            uv pip install libensemble
+
     .. tab-item:: conda
 
         Install libEnsemble with Conda_ from the conda-forge channel::
@@ -192,3 +194,4 @@ The following packages may be installed separately to enable additional features
 .. _spack_libe: https://github.com/Libensemble/spack_libe
 .. _tomli: https://pypi.org/project/tomli/
 .. _tqdm: https://tqdm.github.io/
+.. _uv: https://docs.astral.sh/uv/

docs/conf.py

@@ -67,9 +67,9 @@ class AxParameterWarning(Warning):  # Ensure it's a real warning subclass
 
 # sys.path.insert(0, os.path.abspath('.'))
 sys.path.append(os.path.abspath("../libensemble"))
-##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"))

docs/data_structures/gen_specs.rst

@@ -3,89 +3,36 @@
 Generator Specs
 ===============
 
-Used to specify the generator function, its inputs and outputs, and user data.
-
-Can be constructed and passed to libEnsemble as a Python class or a dictionary.
-
-.. tab-set::
-
-  .. tab-item:: class
-
-    .. code-block:: python
-        :linenos:
-
-        ...
-        import numpy as np
-        from libensemble import GenSpecs
-        from generator import gen_random_sample
-
-        ...
-
-        gen_specs = GenSpecs(
-            gen_f=gen_random_sample,
-            outputs=[("x", float, (1,))],
-            user={
-                "lower": np.array([-3]),
-                "upper": np.array([3]),
-                "gen_batch_size": 5,
-            },
-        )
-        ...
-
-    .. autopydantic_model:: libensemble.specs.GenSpecs
-      :model-show-json: False
-      :model-show-config-member: False
-      :model-show-config-summary: False
-      :model-show-validator-members: False
-      :model-show-validator-summary: False
-      :field-list-validators: False
-
-  .. tab-item:: dict
-
-    .. code-block:: python
-        :linenos:
-
-        ...
-        import numpy as np
-        from generator import gen_random_sample
-
-        ...
-
-        gen_specs = {
-            "gen_f": gen_random_sample,
-            "out": [("x", float, (1,))],
-            "user": {
-                "lower": np.array([-3]),
-                "upper": np.array([3]),
-                "gen_batch_size": 5,
-            },
-        }
-
-    .. seealso::
-
-      .. _gen-specs-example1:
-
-      - test_uniform_sampling.py_:
-        the generator function ``uniform_random_sample`` in sampling.py_ will generate 500 random
-        points uniformly over the 2D domain defined by ``gen_specs["ub"]`` and
-        ``gen_specs["lb"]``.
-
-      ..  literalinclude:: ../../libensemble/tests/functionality_tests/test_uniform_sampling.py
-          :start-at: gen_specs
-          :end-before: end_gen_specs_rst_tag
-
-    .. seealso::
-
-        - test_persistent_aposmm_nlopt.py_ shows an example where ``gen_specs["in"]`` is empty, but
-          ``gen_specs["persis_in"]`` specifies values to return to the persistent generator.
-
-        - test_persistent_aposmm_with_grad.py_ shows a similar example where an ``H0`` is used to
-          provide points from a previous run. In this case, ``gen_specs["in"]`` is populated to provide
-          the generator with data for the initial points.
-
-        - In some cases you might be able to give different (perhaps fewer) fields in ``"persis_in"``
-          than ``"in"``; you may not need to give ``x`` for example, as the persistent generator
-          already has ``x`` for those points. See `more example uses`_ of ``persis_in``.
+Used to specify the generator, its inputs and outputs, and user data.
+
+.. code-block:: python
+    :linenos:
+
+    ...
+    import numpy as np
+    from libensemble import GenSpecs
+    from generator import gen_random_sample
+
+    ...
+
+    gen_specs = GenSpecs(
+        gen_f=gen_random_sample,
+        outputs=[("x", float, (1,))],
+        user={
+            "lower": np.array([-3]),
+            "upper": np.array([3]),
+            "gen_batch_size": 5,
+        },
+    )
+    ...
+
+.. autopydantic_model:: libensemble.specs.GenSpecs
+  :model-show-json: False
+  :model-show-config-member: False
+  :model-show-config-summary: False
+  :model-show-validator-members: False
+  :model-show-validator-summary: False
+  :field-list-validators: False
 
 .. note::
 

docs/data_structures/libE_specs.rst

@@ -3,18 +3,13 @@
 LibE Specs
 ==========
 
-libEnsemble is primarily customized by setting options within a ``LibeSpecs`` class or dictionary.
+libEnsemble is primarily customized by setting options within a ``LibeSpecs`` instance.
 
 .. code-block:: python
 
     from libensemble.specs import LibeSpecs
 
-    specs = LibeSpecs(
-        gen_on_manager=True,
-        save_every_k_gens=100,
-        sim_dirs_make=True,
-        nworkers=4
-    )
+    specs = LibeSpecs(gen_on_manager=True, save_every_k_gens=100, sim_dirs_make=True, nworkers=4)
 
 .. dropdown:: Settings by Category
     :open:

docs/data_structures/sim_specs.rst

@@ -3,75 +3,32 @@
 Simulation Specs
 ================
 
-Used to specify the simulation function, its inputs and outputs, and user data.
+Used to specify the simulation, its inputs and outputs, and user data.
 
-Can be constructed and passed to libEnsemble as a Python class or a dictionary.
+.. code-block:: python
+  :linenos:
 
-.. tab-set::
+  ...
+  from libensemble import SimSpecs
+  from simulator import sim_find_sine
 
-  .. tab-item:: class
+  ...
 
-    .. code-block:: python
-        :linenos:
+  sim_specs = SimSpecs(
+      sim_f=sim_find_sine,
+      inputs=["x"],
+      outputs=[("y", float)],
+      user={"batch": 1234},
+  )
+  ...
 
-        ...
-        from libensemble import SimSpecs
-        from simulator import sim_find_sine
+.. autopydantic_model:: libensemble.specs.SimSpecs
+  :model-show-json: False
+  :model-show-config-member: False
+  :model-show-config-summary: False
+  :model-show-validator-members: False
+  :model-show-validator-summary: False
+  :field-list-validators: False
 
-        ...
 
-        sim_specs = SimSpecs(
-            sim_f=sim_find_sine,
-            inputs=["x"],
-            outputs=[("y", float)],
-            user={"batch": 1234},
-        )
-        ...
-
-    .. autopydantic_model:: libensemble.specs.SimSpecs
-      :model-show-json: False
-      :model-show-config-member: False
-      :model-show-config-summary: False
-      :model-show-validator-members: False
-      :model-show-validator-summary: False
-      :field-list-validators: False
-
-  .. tab-item:: dict
-
-    .. code-block:: python
-        :linenos:
-
-        ...
-        from simulator import six_hump_camel
-
-        ...
-
-        sim_specs = {
-            "sim_f": six_hump_camel,
-            "in": ["x"],
-            "out": [("y", float)],
-            "user": {"batch": 1234},
-        }
-        ...
-
-    - test_uniform_sampling.py_ has a :class:`sim_specs<libensemble.specs.SimSpecs>`  that declares
-      the name of the ``"in"`` field variable, ``"x"`` (as specified by the
-      corresponding generator ``"out"`` field ``"x"`` from the :ref:`gen_specs
-      example<gen-specs-example1>`).  Only the field name is required in
-      ``sim_specs["in"]``.
-
-    ..  literalinclude:: ../../libensemble/tests/functionality_tests/test_uniform_sampling.py
-        :start-at: sim_specs
-        :end-before: end_sim_specs_rst_tag
-
-    - run_libe_forces.py_ has a longer :class:`sim_specs<libensemble.specs.SimSpecs>` declaration with a number of
-      user-specific fields. These are given to the corresponding sim_f, which
-      can be found at forces_simf.py_.
-
-    ..  literalinclude:: ../../libensemble/tests/scaling_tests/forces/forces_adv/run_libe_forces.py
-        :start-at: sim_f
-        :end-before: end_sim_specs_rst_tag
-
-.. _forces_simf.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/scaling_tests/forces/forces_simple/forces_simf.py
-.. _run_libe_forces.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/scaling_tests/forces/forces_simple/run_libe_forces.py
 .. _test_uniform_sampling.py: https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/functionality_tests/test_uniform_sampling.py