Make docs a bit more nice: add links to classes imported from elsewhere, updated docstrings

Author: till-m

bayes_opt/__init__.py

@@ -9,13 +9,15 @@
 from bayes_opt.constraint import ConstraintModel
 from bayes_opt.domain_reduction import SequentialDomainReductionTransformer
 from bayes_opt.logger import JSONLogger, ScreenLogger
+from bayes_opt.target_space import TargetSpace
 
 __version__ = importlib.metadata.version("bayesian-optimization")
 
 
 __all__ = [
     "acquisition",
     "BayesianOptimization",
+    "TargetSpace",
     "ConstraintModel",
     "Events",
     "ScreenLogger",

bayes_opt/acquisition.py

@@ -1,4 +1,22 @@
-"""Acquisition functions for Bayesian Optimization."""
+"""Acquisition functions for Bayesian Optimization.
+
+The acquisition functions in this module can be grouped the following way:
+
+- One of the base acquisition functions
+  (:py:class:`UpperConfidenceBound<bayes_opt.acquisition.UpperConfidenceBound>`,
+  :py:class:`ProbabilityOfImprovement<bayes_opt.acquisition.ProbabilityOfImprovement>` and
+  :py:class:`ExpectedImprovement<bayes_opt.acquisition.ExpectedImprovement>`) is always dictating the basic
+  behavior of the suggestion step. They can be used alone or combined with a meta acquisition function.
+- :py:class:`GPHedge<bayes_opt.acquisition.GPHedge>` is a meta acquisition function that combines multiple
+  base acquisition functions and determines the most suitable one for a particular problem.
+- :py:class:`ConstantLiar<bayes_opt.acquisition.ConstantLiar>` is a meta acquisition function that can be
+  used for parallelized optimization and discourages sampling near a previously suggested, but not yet
+  evaluated, point.
+- :py:class:`AcquisitionFunction<bayes_opt.acquisition.AcquisitionFunction>` is the base class for all
+  acquisition functions. You can implement your own acquisition function by subclassing it. See the
+  `Acquisition Functions notebook <../acquisition.html>`__ to understand the many ways this class can be
+  modified.
+"""
 
 from __future__ import annotations
 
@@ -373,6 +391,11 @@ def decay_exploration(self) -> None:
         """Decay kappa by a constant rate.
 
         Adjust exploration/exploitation trade-off by reducing kappa.
+
+        Note
+        ----
+
+        This method is called automatically at the end of each ``suggest()`` call.
         """
         if self.exploration_decay is not None and (
             self.exploration_decay_delay is None or self.exploration_decay_delay <= self.i
@@ -495,6 +518,11 @@ def decay_exploration(self) -> None:
         r"""Decay xi by a constant rate.
 
         Adjust exploration/exploitation trade-off by reducing xi.
+
+        Note
+        ----
+
+        This method is called automatically at the end of each ``suggest()`` call.
         """
         if self.exploration_decay is not None and (
             self.exploration_decay_delay is None or self.exploration_decay_delay <= self.i
@@ -625,6 +653,11 @@ def decay_exploration(self) -> None:
         r"""Decay xi by a constant rate.
 
         Adjust exploration/exploitation trade-off by reducing xi.
+
+        Note
+        ----
+
+        This method is called automatically at the end of each ``suggest()`` call.
         """
         if self.exploration_decay is not None and (
             self.exploration_decay_delay is None or self.exploration_decay_delay <= self.i

bayes_opt/bayesian_optimization.py

@@ -93,8 +93,9 @@ class BayesianOptimization(Observable):
         Dictionary with parameters names as keys and a tuple with minimum
         and maximum values.
 
-    constraint: A ConstraintModel. Note that the names of arguments of the
-        constraint function and of f need to be the same.
+    constraint: ConstraintModel.
+        Note that the names of arguments of the constraint function and of
+        f need to be the same.
 
     random_state: int or numpy.random.RandomState, optional(default=None)
         If the value is an integer, it is used as the seed for creating a
@@ -112,19 +113,6 @@ class BayesianOptimization(Observable):
         This behavior may be desired in high noise situations where repeatedly probing
         the same point will give different answers. In other situations, the acquisition
         may occasionally generate a duplicate point.
-
-    Methods
-    -------
-    probe()
-        Evaluates the function on the given points.
-        Can be used to guide the optimizer.
-
-    maximize()
-        Tries to find the parameters that yield the maximum value for the
-        given function.
-
-    set_bounds()
-        Allows changing the lower and upper searching bounds
     """
 
     def __init__(
@@ -303,12 +291,20 @@ def maximize(self, init_points=5, n_iter=25):
         Parameters
         ----------
         init_points : int, optional(default=5)
-            Number of iterations before the explorations starts the exploration
-            for the maximum.
+            Number of random points to probe before starting the optimization.
 
         n_iter: int, optional(default=25)
             Number of iterations where the method attempts to find the maximum
             value.
+
+        Warning
+        -------
+            The maximize loop only fits the GP when suggesting a new point to
+            probe based on the acquisition function. This means that the GP may
+            not be fitted on all points registered to the target space when the
+            method completes. If you intend to use the GP model after the
+            optimization routine, make sure to fit it manually, e.g. by calling
+            ``optimizer._gp.fit(optimizer.space.params, optimizer.space.target)``.
         """
         self._prime_subscriptions()
         self.dispatch(Events.OPTIMIZATION_START)

bayes_opt/constraint.py

@@ -33,12 +33,11 @@ class ConstraintModel:
     random_state : np.random.RandomState or int or None, default=None
         Random state to use.
 
-    Notes
-    -----
+    Note
+    ----
     In case of multiple constraints, this model assumes conditional
-    independence. This means that for each constraint, the probability of
-    fulfillment is the cdf of a univariate Gaussian. The overall probability
-    is a simply the product of the individual probabilities.
+    independence. This means that the overall probability of fulfillment is a
+    simply the product of the individual probabilities.
     """
 
     def __init__(self, fun, lb, ub, random_state=None):
@@ -112,9 +111,9 @@ def fit(self, X, Y):
 
         Parameters
         ----------
-        X :
+        X : np.ndarray of shape (n_samples, n_features)
             Parameters of the constraint function.
-        Y :
+        Y : np.ndarray of shape (n_samples, n_constraints)
             Values of the constraint function.
 
 
@@ -146,6 +145,9 @@ def predict(self, X):
         :math:`c^{\text{up}}` the lower and upper bounds of the constraint
         respectively.
 
+        Note
+        ----
+
         In case of multiple constraints, we assume conditional independence.
         This means we calculate the probability of constraint fulfilment
         individually, with the joint probability given as their product.

docsrc/code_docs.rst

@@ -12,6 +12,7 @@
 #
 import os
 import sys
+import time
 import shutil
 from glob import glob
 from pathlib import Path
@@ -44,7 +45,8 @@
     'IPython.sphinxext.ipython_console_highlighting',
     'sphinx.ext.mathjax',
     "sphinx.ext.napoleon",
-    'sphinx_immaterial'
+    'sphinx.ext.intersphinx',
+    'sphinx_immaterial',
 ]
 
 source_suffix = {
@@ -58,6 +60,16 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
 
+# Link types to the corresponding documentations
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
+    'sklearn': ('https://scikit-learn.org/stable/', None),
+}
+
+
+napoleon_use_rtype = False
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -67,7 +79,7 @@
 
 html_title = "Bayesian Optimization"
 html_theme = "sphinx_immaterial"
-copyright = 'Fernando Nogueira and the bayesian-optimization developers'
+copyright = f"{time.strftime('%Y')}, Fernando Nogueira and the bayesian-optimization developers"
 
 # material theme options (see theme.conf for more information)
 html_theme_options = {
@@ -122,6 +134,7 @@
     "version_dropdown": True,
     "version_json": '../versions.json',
     # END: version_dropdown
+    "scope": "/", # share preferences across subsites
     "toc_title_is_page_title": True,
     # BEGIN: social icons
     "social": [

docsrc/conf.py

@@ -1,11 +1,32 @@
 .. toctree::
    :hidden:
-   :maxdepth: 3
-   :caption: Contents:
 
    Quickstart <self>
-   Example Notebooks </examples>
-   /code_docs
+
+.. toctree::
+   :hidden:
+   :maxdepth: 3
+   :caption: Example Notebooks:
+
+   Basic Tour </basic-tour>
+   Advanced Tour </advanced-tour>
+   Constrained Bayesian Optimization </constraints>
+   Sequential Domain Reduction </domain_reduction>
+   Acquisition Functions </acquisition_functions>
+   Exploration vs. Exploitation </exploitation_vs_exploration>
+   Visualization of a 1D-Optimization </visualization>
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+   :caption: API reference:
+
+   reference/bayes_opt
+   reference/acquisition
+   reference/constraint
+   reference/domain_reduction
+   reference/target_space
+   reference/other
 
 .. raw:: html
 

docsrc/examples.rst

@@ -0,0 +1,14 @@
+:py:mod:`bayes_opt.acquisition`
+-------------------------------
+
+.. automodule:: bayes_opt.acquisition
+   :members: AcquisitionFunction
+
+.. toctree::
+   :hidden:
+
+   acquisition/UpperConfidenceBound
+   acquisition/ProbabilityOfImprovement
+   acquisition/ExpectedImprovement
+   acquisition/GPHedge
+   acquisition/ConstantLiar

docsrc/index.rst

@@ -0,0 +1,5 @@
+:py:class:`bayes_opt.acquisition.ConstantLiar`
+----------------------------------------------
+
+.. autoclass:: bayes_opt.acquisition.ConstantLiar
+   :members:

docsrc/reference/acquisition.rst

@@ -0,0 +1,5 @@
+:py:class:`bayes_opt.acquisition.ExpectedImprovement`
+-----------------------------------------------------
+
+.. autoclass:: bayes_opt.acquisition.ExpectedImprovement
+   :members:

docsrc/reference/acquisition/ConstantLiar.rst

@@ -0,0 +1,5 @@
+:py:class:`bayes_opt.acquisition.GPHedge`
+-----------------------------------------
+
+.. autoclass:: bayes_opt.acquisition.GPHedge
+   :members:

docsrc/reference/acquisition/ExpectedImprovement.rst

@@ -0,0 +1,5 @@
+:py:class:`bayes_opt.acquisition.ProbabilityOfImprovement`
+----------------------------------------------------------
+
+.. autoclass:: bayes_opt.acquisition.ProbabilityOfImprovement
+   :members:

docsrc/reference/acquisition/GPHedge.rst

@@ -0,0 +1,5 @@
+:py:class:`bayes_opt.acquisition.UpperConfidenceBound`
+------------------------------------------------------
+
+.. autoclass:: bayes_opt.acquisition.UpperConfidenceBound
+   :members:

docsrc/reference/acquisition/ProbabilityOfImprovement.rst

@@ -0,0 +1,5 @@
+:py:class:`bayes_opt.BayesianOptimization`
+------------------------------------------
+
+.. autoclass:: bayes_opt.BayesianOptimization
+   :members:

docsrc/reference/acquisition/UpperConfidenceBound.rst

@@ -0,0 +1,7 @@
+:py:class:`bayes_opt.ConstraintModel`
+------------------------------------------------
+
+See the `Constrained Optimization notebook <../constraints.html#2.-Advanced-Constrained-Optimization>`__ for a complete example.
+
+.. autoclass:: bayes_opt.constraint.ConstraintModel
+   :members:

docsrc/reference/bayes_opt.rst

@@ -0,0 +1,7 @@
+:py:class:`bayes_opt.SequentialDomainReductionTransformer`
+----------------------------------------------------------
+
+See the `Sequential Domain Reduction notebook <../domain_reduction.html>`__ for a complete example.
+
+.. autoclass:: bayes_opt.SequentialDomainReductionTransformer
+   :members:

docsrc/reference/constraint.rst

@@ -0,0 +1,11 @@
+Other
+-----
+
+.. autoclass:: bayes_opt.ScreenLogger
+    :members:
+
+.. autoclass:: bayes_opt.JSONLogger
+    :members:
+
+.. autoclass:: bayes_opt.Events
+    :members:

docsrc/reference/domain_reduction.rst

@@ -0,0 +1,5 @@
+:py:class:`bayes_opt.TargetSpace`
+---------------------------------
+
+.. autoclass:: bayes_opt.TargetSpace
+   :members: