Update: doc

README.md

@@ -12,7 +12,7 @@
   </a>
 
   <h3 align="center">
-    Optimization at scale, powered by 
+    Optimization at scale, powered by
     <a href="https://libensemble.readthedocs.io/"><strong>libEnsemble</strong></a>
   </h3>
 

doc/make.bat

@@ -5,7 +5,7 @@ pushd %~dp0
 REM Command file for Sphinx documentation
 
 if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
+    set SPHINXBUILD=sphinx-build
 )
 set SOURCEDIR=source
 set BUILDDIR=build
@@ -14,15 +14,15 @@ if "%1" == "" goto help
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.https://www.sphinx-doc.org/
-	exit /b 1
+    echo.
+    echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+    echo.installed, then set the SPHINXBUILD environment variable to point
+    echo.to the full path of the 'sphinx-build' executable. Alternatively you
+    echo.may add the Sphinx directory to PATH.
+    echo.
+    echo.If you don't have Sphinx installed, grab it from
+    echo.https://www.sphinx-doc.org/
+    exit /b 1
 )
 
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

doc/requirements.txt

@@ -1,7 +1,7 @@
+ax-platform >= 0.2.9
+libensemble >= 0.9.2
+matplotlib
+numpydoc
 pydata-sphinx-theme
 sphinx-design
 sphinx-gallery
-numpydoc
-matplotlib
-libensemble >= 0.9.2
-ax-platform >= 0.2.9

doc/source/_templates/autosummary/base.rst

@@ -2,4 +2,4 @@
 
 .. currentmodule:: {{ module }}
 
-.. auto{{ objtype }}:: {{ objname }}
+.. auto{{ objtype }}:: {{ objname }}

doc/source/_templates/autosummary/class.rst

@@ -31,4 +31,4 @@
       {% endif %}
    {%- endfor %}
    {% endif %}
-   {% endblock %}
+   {% endblock %}

doc/source/conf.py

@@ -13,17 +13,18 @@
 import os
 import sys
 from datetime import date
-sys.path.insert(0, os.path.abspath('../..'))
+
+sys.path.insert(0, os.path.abspath("../.."))
 
 
 # -- Import version ----------------------------------------------------------
 from optimas import __version__  # noqa: E402
 
 
 # -- Project information -----------------------------------------------------
-project = 'optimas'
-project_copyright = '2023-%s, the optimas collaborators' % date.today().year
-author = 'The optimas collaborators'
+project = "optimas"
+project_copyright = "2023-%s, the optimas collaborators" % date.today().year
+author = "The optimas collaborators"
 
 # The full version, including alpha/beta/rc tags
 release = __version__
@@ -35,18 +36,18 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.autosummary',
-    'sphinx.ext.coverage',
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.coverage",
     # 'sphinx.ext.intersphinx',
-    'sphinx_design',
+    "sphinx_design",
     # 'sphinx_gallery.gen_gallery',
-    'numpydoc',
+    "numpydoc",
     "matplotlib.sphinxext.plot_directive",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -59,12 +60,12 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'pydata_sphinx_theme'  # "sphinx_rtd_theme"
+html_theme = "pydata_sphinx_theme"  # "sphinx_rtd_theme"
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
 # Logo
 html_logo = "_static/logo.png"
@@ -87,7 +88,7 @@
     "pygment_light_style": "default",
     "pygment_dark_style": "monokai",
     "use_edit_page_button": True,
-    "navigation_depth": 2
+    "navigation_depth": 2,
 }
 
 html_context = {
@@ -98,7 +99,7 @@
 }
 
 # Do not show type hints.
-autodoc_typehints = 'none'
+autodoc_typehints = "none"
 
 # Do  not use numpydoc to generate autosummary.
 numpydoc_show_class_members = False

doc/source/examples/bo_basic.rst

@@ -10,7 +10,7 @@ Description
 This example illustrates how to run a generic Bayesian optimization with
 simulations. This typically requires:
 
-- An `optimas` script for defining and running the optimization.
+- An *optimas* script for defining and running the optimization.
 - A template simulation script.
 - A function to analyze the simulation output.
 

doc/source/examples/bo_multitask_fbpic_waket.rst

@@ -30,9 +30,9 @@ Scripts
 Files included:
 
 - :download:`run_opt.py <../../../examples/multitask_lpa_fbpic_waket/run_opt.py>`:
-  defines and launches the optimization with `optimas`.
+  defines and launches the optimization with *optimas*.
 - :download:`template_simulation_script.py <../../../examples/multitask_lpa_fbpic_waket/template_simulation_script.py>`:
-  template used by `optimas` to generate the FBPIC and Wake-T simulation
+  template used by *optimas* to generate the FBPIC and Wake-T simulation
   scripts.
 - :download:`analysis_script.py <../../../examples/multitask_lpa_fbpic_waket/analysis_script.py>`:
   defines how the simulation data is analyzed to yield the value of the

doc/source/examples/ps_grid_sampling.rst

@@ -50,12 +50,12 @@ where :math:`l_b=0` and :math:`u_b=15`, the grid of sample looks like:
            break
    x0 = np.zeros(len(all_trials))
    x1 = np.zeros(len(all_trials))
-   
+
    for i, trial in enumerate(all_trials):
        trial_params = trial.parameters_as_dict()
        x0[i] = trial_params['x0']
        x1[i] = trial_params['x1']
-       
+
    fig, ax = plt.subplots()
    ax.scatter(x0, x1, s=3, label='generated evaluations')
    ax.set(
@@ -89,4 +89,4 @@ The example is executed by running
 
 .. literalinclude:: ../../../examples/dummy_grid_sampling/template_simulation_script.py
    :language: python
-   :caption: template_simulation_script.py (:download:`download <../../../examples/dummy_grid_sampling/template_simulation_script.py>`)
+   :caption: template_simulation_script.py (:download:`download <../../../examples/dummy_grid_sampling/template_simulation_script.py>`)

doc/source/examples/ps_line_sampling.rst

@@ -53,12 +53,12 @@ where :math:`x_0` and :math:`x_1` have a default values of :math:`5` and
            break
    x0 = np.zeros(len(all_trials))
    x1 = np.zeros(len(all_trials))
-   
+
    for i, trial in enumerate(all_trials):
        trial_params = trial.parameters_as_dict()
        x0[i] = trial_params['x0']
        x1[i] = trial_params['x1']
-       
+
    fig, ax = plt.subplots()
    ax.scatter(x0, x1, s=3, label='generated evaluations')
    ax.set(
@@ -94,4 +94,4 @@ You can find both example scripts below.
 
 .. literalinclude:: ../../../examples/dummy_line_sampling/template_simulation_script.py
    :language: python
-   :caption: template_simulation_script.py (:download:`download <../../../examples/dummy_line_sampling/template_simulation_script.py>`)
+   :caption: template_simulation_script.py (:download:`download <../../../examples/dummy_line_sampling/template_simulation_script.py>`)

doc/source/examples/ps_random_sampling.rst

@@ -25,7 +25,7 @@ analysis function. See see :ref:`optimas-with-simulations` for more details.
 
 The :class:`~optimas.generators.RandomSamplingGenerator` draws samples from
 a ``'normal'`` distribution that, for each parameter, is centered at
-:math:`c = l_b - u_b` with standard deviation :math:`\\sigma = u_b - c`, 
+:math:`c = l_b - u_b` with standard deviation :math:`\\sigma = u_b - c`,
 where :math:`l_b` and :math:`u_b` are, respectively, the lower and upper
 bounds of the parameter. Other distributions are also available. In this case,
 where :math:`l_b=0` and :math:`u_b=15`, the drawn samples result in a
@@ -52,12 +52,12 @@ distribution such as:
            break
    x0 = np.zeros(len(all_trials))
    x1 = np.zeros(len(all_trials))
-   
+
    for i, trial in enumerate(all_trials):
        trial_params = trial.parameters_as_dict()
        x0[i] = trial_params['x0']
        x1[i] = trial_params['x1']
-       
+
    fig, ax = plt.subplots()
    ax.scatter(x0, x1, s=3, label='generated evaluations')
    ax.set(
@@ -101,4 +101,4 @@ You can find both example scripts below.
 
 .. literalinclude:: ../../../examples/dummy_random/template_simulation_script.py
    :language: python
-   :caption: template_simulation_script.py (:download:`download <../../../examples/dummy_random/template_simulation_script.py>`)
+   :caption: template_simulation_script.py (:download:`download <../../../examples/dummy_random/template_simulation_script.py>`)

doc/source/index.rst

@@ -9,7 +9,7 @@ optimas documentation
 ``optimas`` is an `open-source <https://github.com/optimas-org/optimas>`_
 Python library that enables highly scalable
 parallel optimization, from a typical laptop to exascale HPC systems. It is
-built on top of 
+built on top of
 `libEnsemble <https://libensemble.readthedocs.io/>`_.
 
 .. grid:: 1 1 3 3
@@ -20,7 +20,7 @@ built on top of
 
         :octicon:`book;3em`
 
-        Instructions for getting the code up and running and basic information 
+        Instructions for getting the code up and running and basic information
         about optimas.
 
         +++
@@ -35,7 +35,7 @@ built on top of
 
     .. grid-item-card:: Examples
         :text-align: center
-        
+
         :octicon:`light-bulb;3em`
 
         Quick examples showcasing how to use the code.
@@ -51,7 +51,7 @@ built on top of
 
     .. grid-item-card:: API reference
         :text-align: center
-        
+
         :octicon:`code;3em`
 
         Detailed documentation of the optimas API.
@@ -100,7 +100,7 @@ Contributing institutions
     :height: 30px
     :target: https://www.anl.gov/
     :class: only-light
-        
+
 .. |pic3b| image:: https://www.alcf.anl.gov/sites/default/files/styles/large/public/2020-01/Argonne_wireframe_white_vector.png?itok=mXUvxazY
     :height: 30px
     :target: https://www.anl.gov/
@@ -114,6 +114,3 @@ Contributing institutions
    user_guide/index
    examples/index
    api/index
-
-
-

doc/source/user_guide/basic_usage/analyze_output.rst

@@ -98,5 +98,3 @@ corresponds an optimas run using an
            ├── ax_client_at_eval_5.json
           ...
            └── ax_client_at_eval_100.json
-
-

doc/source/user_guide/basic_usage/basic_setup.rst

@@ -28,8 +28,8 @@ parameters named ``x0`` and ``x1`` that can vary in the ranges [0, 15] and
 
     from optimas.core import VaryingParameter
 
-    var_1 = VaryingParameter('x0', 0., 15.)
-    var_2 = VaryingParameter('x1', -5., 5.)
+    var_1 = VaryingParameter("x0", 0.0, 15.0)
+    var_2 = VaryingParameter("x1", -5.0, 5.0)
 
 
 Objectives and other analyzed parameters
@@ -50,9 +50,9 @@ also be calculated for each evaluation.
 
     from optimas.core import Objective, Parameter
 
-    obj = Objective('f', minimize=True)
-    diag_1 = Parameter('diag_1')
-    diag_2 = Parameter('diag_2')
+    obj = Objective("f", minimize=True)
+    diag_1 = Parameter("diag_1")
+    diag_2 = Parameter("diag_2")
 
 
 Generator
@@ -77,7 +77,7 @@ Bayesian optimization loop is started (see
         varying_parameters=[var_1, var_2],
         objectives=[obj],
         analyzed_parameters=[diag_1, diag_2],
-        n_init=4
+        n_init=4,
     )
 
 
@@ -117,7 +117,7 @@ changed by specifying the ``n_procs`` and ``n_gpus`` attributes.
     from optimas.evaluators import TemplateEvaluator
 
     ev = TemplateEvaluator(
-        sim_template='template_simulation_script.py',
+        sim_template="template_simulation_script.py",
         analysis_func=analyze_simulation,
         # n_procs=2,
         # n_gpus=2
@@ -139,19 +139,14 @@ parallel at any time.
 
     from optimas.explorations import Exploration
 
-    exp = Exploration(
-        generator=gen,
-        evaluator=ev,
-        max_evals=100,
-        sim_workers=4
-    )
+    exp = Exploration(generator=gen, evaluator=ev, max_evals=100, sim_workers=4)
 
 The exploration is started by executing ``exp.run()`` inside a
 ``if __name__ == '__main__':`` block:
 
 .. code-block:: python
 
-    if __name__ == '__main__':
+    if __name__ == "__main__":
         exp.run()
 
 This is needed in order to safely execute the exploration in systems using the

doc/source/user_guide/basic_usage/running_with_simulations.rst

@@ -20,6 +20,9 @@ would look something like
 
     from optimas.evaluators import TemplateEvaluator
 
+    def analyze_simulation(simulation_directory, output_params):
+        pass
+
     ev = TemplateEvaluator(
         sim_template='template_simulation_script.py',
         analysis_func=analyze_simulation
@@ -36,7 +39,7 @@ is, using the double-bracket notation ``{{var_name}}``, where ``var_name`` is
 the name of the :class:`~optimas.core.VaryingParameter`.
 
 As a basic example, a template for a Python script that takes in two
-:class:`~optimas.core.VaryingParameter`\s called ``'x'`` and ``'y'``, 
+:class:`~optimas.core.VaryingParameter`\s called ``'x'`` and ``'y'``,
 computes ``x + y``, and stores the result in a text file would look like:
 
 .. code-block:: python
@@ -103,7 +106,7 @@ Assigning computational resources
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Optimas executes the simulations using MPI with the amount of resources
-(number of MPI processes and GPUs) specified by the 
+(number of MPI processes and GPUs) specified by the
 ``n_procs`` and ``n_gpus`` attributes of the
 :class:`~optimas.evaluators.TemplateEvaluator`. By default: