CI: Update docs for v1.25.1 (a85f8fb9452ba14752943ce1587436f8394f6174)

Author: github-actions[bot]

convergence.svg

@@ -95,7 +95,7 @@ <h2 class="section-title" id="header-functions">Functions</h2>
 <details class="source">
 <summary>
 <span>Expand source code</span>
-<a href="https://github.com/sambo-optimization/sambo/blob/ec7433286915d71bb7bb8f4e38758eca5c7171f6/sambo/_minimize.py#L12-L231" class="git-link" target="_blank">Browse git</a>
+<a href="https://github.com/sambo-optimization/sambo/blob/a85f8fb9452ba14752943ce1587436f8394f6174/sambo/_minimize.py#L12-L231" class="git-link" target="_blank">Browse git</a>
 </summary>
 <pre><code class="python">def minimize(
         fun: Callable[[np.ndarray], float],
@@ -481,7 +481,7 @@ <h2 class="section-title" id="header-classes">Classes</h2>
 <details class="source">
 <summary>
 <span>Expand source code</span>
-<a href="https://github.com/sambo-optimization/sambo/blob/ec7433286915d71bb7bb8f4e38758eca5c7171f6/sambo/_util.py#L91-L104" class="git-link" target="_blank">Browse git</a>
+<a href="https://github.com/sambo-optimization/sambo/blob/a85f8fb9452ba14752943ce1587436f8394f6174/sambo/_util.py#L91-L104" class="git-link" target="_blank">Browse git</a>
 </summary>
 <pre><code class="python">class OptimizeResult(_OptimizeResult):
     &#34;&#34;&#34;
@@ -554,7 +554,7 @@ <h3>Class variables</h3>
 <details class="source">
 <summary>
 <span>Expand source code</span>
-<a href="https://github.com/sambo-optimization/sambo/blob/ec7433286915d71bb7bb8f4e38758eca5c7171f6/sambo/_smbo.py#L21-L549" class="git-link" target="_blank">Browse git</a>
+<a href="https://github.com/sambo-optimization/sambo/blob/a85f8fb9452ba14752943ce1587436f8394f6174/sambo/_smbo.py#L21-L555" class="git-link" target="_blank">Browse git</a>
 </summary>
 <pre><code class="python">class Optimizer:
     &#34;&#34;&#34;
@@ -809,21 +809,22 @@ <h3>Class variables</h3>
 
     #: Acquisition functions for selecting the best candidates from the sample.
     #: Currently defined keys:
-    #:     &#34;UCB&#34; for upper confidence bound (`mean - kappa * std`).
+    #: `&#34;LCB&#34;` — **lower confidence bound** (an inverse analog of &#34;UCB&#34;)
+    #: which orders candidates by `mean - kappa * std`.
     #: [//]: # (No blank line here! bug in pdoc)
     #: .. note::
     #:      To make any use of the `kappa` parameter, it is important for the
     #:      estimator&#39;s `predict()` method to implement `return_std=` behavior.
     #:      All built-in estimators (`&#34;gp&#34;`, `&#34;et&#34;`, `&#34;gb&#34;`) do so.
     ACQ_FUNCS: dict = {
-        &#39;UCB&#39;: _UCB,
+        &#39;LCB&#39;: _LCB,
     }
 
     def ask(
             self,
             n_candidates: Optional[int] = None,
             *,
-            acq_func: Optional[Callable] = ACQ_FUNCS[&#39;UCB&#39;],
+            acq_func: Optional[Callable] = ACQ_FUNCS[&#39;LCB&#39;],
             kappa: float | list[float] = 0,
     ) -&gt; np.ndarray:
         &#34;&#34;&#34;
@@ -836,20 +837,20 @@ <h3>Class variables</h3>
             Number of candidate solutions to propose.
             If not specified, the default value set during initialization is used.
 
-        acq_func : Callable, default ACQ_FUNCS[&#39;UCB&#39;]
+        acq_func : Callable, default ACQ_FUNCS[&#39;LCB&#39;]
             Acquisition function used to guide the selection of candidate solutions.
-            By default, upper confidence bound (i.e. `mean - kappa * std` where `mean`
+            By default, lower confidence bound (i.e. `mean - kappa * std` where `mean`
             and `std` are surrogate models&#39; predicted results).
 
             .. tip::
-                [See the source][_ghs] for how `ACQ_FUNCS[&#39;UCB&#39;]` is implemeted.
+                [See the source][_ghs] for how `ACQ_FUNCS[&#39;LCB&#39;]` is implemeted.
                 The passed parameters are open to extension to accommodate
                 alternative acquisition functions.
 
                 [_ghs]: https://github.com/search?q=repo%3Asambo-optimization%2Fsambo%20ACQ_FUNCS&amp;type=code
 
         kappa : float or list[float], default 0
-            The upper/lower-confidence-bound parameter, used by `acq_func`, that
+            The lower-confidence-bound parameter, used by `acq_func`, that
             balances exploration (&lt;0) vs exploitation (&gt;0).
 
             Can also be an array of values to use sequentially for `n_cadidates`.
@@ -902,7 +903,12 @@ <h3>Class variables</h3>
         self._X_ask.extend(map(tuple, X))
         return X
 
+    #: In `Optimizer.ask()`, sample this many points (per dimension) and
+    #: use the estimator to _predict_ the objective values.
     POINTS_PER_DIM = 20_000
+
+    #: In `Optimizer.ask()`, sample _at most_ this many points. This increases
+    #: computation time, but may also improve precision and convergence significantly.
     MAX_POINTS_PER_ITER = 80_000
 
     def tell(self, y: float | list[float],
@@ -1162,7 +1168,8 @@ <h3>Class variables</h3>
 <dd>
 <div class="desc"><p>Acquisition functions for selecting the best candidates from the sample.
 Currently defined keys:
-"UCB" for upper confidence bound (<code>mean - kappa * std</code>).</p>
+<code>"LCB"</code> — <strong>lower confidence bound</strong> (an inverse analog of "UCB")
+which orders candidates by <code>mean - kappa * std</code>.</p>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
 <p>To make any use of the <code>kappa</code> parameter, it is important for the
@@ -1172,29 +1179,31 @@ <h3>Class variables</h3>
 </dd>
 <dt id="sambo.Optimizer.MAX_POINTS_PER_ITER"><code class="name">var <span class="ident">MAX_POINTS_PER_ITER</span></code></dt>
 <dd>
-<div class="desc"></div>
+<div class="desc"><p>In <code><a title="sambo.Optimizer.ask" href="#sambo.Optimizer.ask">Optimizer.ask()</a></code>, sample <em>at most</em> this many points. This increases
+computation time, but may also improve precision and convergence significantly.</p></div>
 </dd>
 <dt id="sambo.Optimizer.POINTS_PER_DIM"><code class="name">var <span class="ident">POINTS_PER_DIM</span></code></dt>
 <dd>
-<div class="desc"></div>
+<div class="desc"><p>In <code><a title="sambo.Optimizer.ask" href="#sambo.Optimizer.ask">Optimizer.ask()</a></code>, sample this many points (per dimension) and
+use the estimator to <em>predict</em> the objective values.</p></div>
 </dd>
 </dl>
 <h3>Methods</h3>
 <dl>
 <dt id="sambo.Optimizer.ask"><code class="name flex">
-<span>def <span class="ident">ask</span></span>(<span>self,<br>n_candidates: int | None = None,<br>*,<br>acq_func: Callable | None = &lt;function _UCB&gt;,<br>kappa: float | list[float] = 0) ‑> numpy.ndarray</span>
+<span>def <span class="ident">ask</span></span>(<span>self,<br>n_candidates: int | None = None,<br>*,<br>acq_func: Callable | None = &lt;function _LCB&gt;,<br>kappa: float | list[float] = 0) ‑> numpy.ndarray</span>
 </code></dt>
 <dd>
 <details class="source">
 <summary>
 <span>Expand source code</span>
-<a href="https://github.com/sambo-optimization/sambo/blob/ec7433286915d71bb7bb8f4e38758eca5c7171f6/sambo/_smbo.py#L284-L365" class="git-link" target="_blank">Browse git</a>
+<a href="https://github.com/sambo-optimization/sambo/blob/a85f8fb9452ba14752943ce1587436f8394f6174/sambo/_smbo.py#L285-L366" class="git-link" target="_blank">Browse git</a>
 </summary>
 <pre><code class="python">def ask(
         self,
         n_candidates: Optional[int] = None,
         *,
-        acq_func: Optional[Callable] = ACQ_FUNCS[&#39;UCB&#39;],
+        acq_func: Optional[Callable] = ACQ_FUNCS[&#39;LCB&#39;],
         kappa: float | list[float] = 0,
 ) -&gt; np.ndarray:
     &#34;&#34;&#34;
@@ -1207,20 +1216,20 @@ <h3>Methods</h3>
         Number of candidate solutions to propose.
         If not specified, the default value set during initialization is used.
 
-    acq_func : Callable, default ACQ_FUNCS[&#39;UCB&#39;]
+    acq_func : Callable, default ACQ_FUNCS[&#39;LCB&#39;]
         Acquisition function used to guide the selection of candidate solutions.
-        By default, upper confidence bound (i.e. `mean - kappa * std` where `mean`
+        By default, lower confidence bound (i.e. `mean - kappa * std` where `mean`
         and `std` are surrogate models&#39; predicted results).
 
         .. tip::
-            [See the source][_ghs] for how `ACQ_FUNCS[&#39;UCB&#39;]` is implemeted.
+            [See the source][_ghs] for how `ACQ_FUNCS[&#39;LCB&#39;]` is implemeted.
             The passed parameters are open to extension to accommodate
             alternative acquisition functions.
 
             [_ghs]: https://github.com/search?q=repo%3Asambo-optimization%2Fsambo%20ACQ_FUNCS&amp;type=code
 
     kappa : float or list[float], default 0
-        The upper/lower-confidence-bound parameter, used by `acq_func`, that
+        The lower-confidence-bound parameter, used by `acq_func`, that
         balances exploration (&lt;0) vs exploitation (&gt;0).
 
         Can also be an array of values to use sequentially for `n_cadidates`.
@@ -1280,21 +1289,21 @@ <h2 id="parameters">Parameters</h2>
 <dt><strong><code>n_candidates</code></strong> :&ensp;<code>int</code>, optional</dt>
 <dd>Number of candidate solutions to propose.
 If not specified, the default value set during initialization is used.</dd>
-<dt><strong><code>acq_func</code></strong> :&ensp;<code>Callable</code>, default <code>ACQ_FUNCS['UCB']</code></dt>
+<dt><strong><code>acq_func</code></strong> :&ensp;<code>Callable</code>, default <code>ACQ_FUNCS['LCB']</code></dt>
 <dd>
 <p>Acquisition function used to guide the selection of candidate solutions.
-By default, upper confidence bound (i.e. <code>mean - kappa * std</code> where <code>mean</code>
+By default, lower confidence bound (i.e. <code>mean - kappa * std</code> where <code>mean</code>
 and <code>std</code> are surrogate models' predicted results).</p>
 <div class="admonition tip">
 <p class="admonition-title">Tip</p>
-<p><a href="https://github.com/search?q=repo%3Asambo-optimization%2Fsambo%20ACQ_FUNCS&amp;type=code">See the source</a> for how <code>ACQ_FUNCS['UCB']</code> is implemeted.
+<p><a href="https://github.com/search?q=repo%3Asambo-optimization%2Fsambo%20ACQ_FUNCS&amp;type=code">See the source</a> for how <code>ACQ_FUNCS['LCB']</code> is implemeted.
 The passed parameters are open to extension to accommodate
 alternative acquisition functions.</p>
 </div>
 </dd>
 <dt><strong><code>kappa</code></strong> :&ensp;<code>float</code> or <code>list[float]</code>, default <code>0</code></dt>
 <dd>
-<p>The upper/lower-confidence-bound parameter, used by <code>acq_func</code>, that
+<p>The lower-confidence-bound parameter, used by <code>acq_func</code>, that
 balances exploration (&lt;0) vs exploitation (&gt;0).</p>
 <p>Can also be an array of values to use sequentially for <code>n_cadidates</code>.</p>
 </dd>
@@ -1321,7 +1330,7 @@ <h2 id="examples">Examples</h2>
 <details class="source">
 <summary>
 <span>Expand source code</span>
-<a href="https://github.com/sambo-optimization/sambo/blob/ec7433286915d71bb7bb8f4e38758eca5c7171f6/sambo/_smbo.py#L422-L519" class="git-link" target="_blank">Browse git</a>
+<a href="https://github.com/sambo-optimization/sambo/blob/a85f8fb9452ba14752943ce1587436f8394f6174/sambo/_smbo.py#L428-L525" class="git-link" target="_blank">Browse git</a>
 </summary>
 <pre><code class="python">def run(self, *,
         max_iter: Optional[int] = None,
@@ -1459,7 +1468,7 @@ <h2 id="examples">Examples</h2>
 <details class="source">
 <summary>
 <span>Expand source code</span>
-<a href="https://github.com/sambo-optimization/sambo/blob/ec7433286915d71bb7bb8f4e38758eca5c7171f6/sambo/_smbo.py#L370-L420" class="git-link" target="_blank">Browse git</a>
+<a href="https://github.com/sambo-optimization/sambo/blob/a85f8fb9452ba14752943ce1587436f8394f6174/sambo/_smbo.py#L376-L426" class="git-link" target="_blank">Browse git</a>
 </summary>
 <pre><code class="python">def tell(self, y: float | list[float],
          x: Optional[float | tuple[float] | list[tuple[float]]] = None):
@@ -1546,7 +1555,7 @@ <h2 id="examples">Examples</h2>
 <details class="source">
 <summary>
 <span>Expand source code</span>
-<a href="https://github.com/sambo-optimization/sambo/blob/ec7433286915d71bb7bb8f4e38758eca5c7171f6/sambo/_smbo.py#L521-L549" class="git-link" target="_blank">Browse git</a>
+<a href="https://github.com/sambo-optimization/sambo/blob/a85f8fb9452ba14752943ce1587436f8394f6174/sambo/_smbo.py#L527-L555" class="git-link" target="_blank">Browse git</a>
 </summary>
 <pre><code class="python">def top_k(self, k: int = 1):
     &#34;&#34;&#34;
@@ -1610,14 +1619,15 @@ <h2 id="examples">Examples</h2>
 <details class="source">
 <summary>
 <span>Expand source code</span>
-<a href="https://github.com/sambo-optimization/sambo/blob/ec7433286915d71bb7bb8f4e38758eca5c7171f6/sambo/_estimators.py#L112-L199" class="git-link" target="_blank">Browse git</a>
+<a href="https://github.com/sambo-optimization/sambo/blob/a85f8fb9452ba14752943ce1587436f8394f6174/sambo/_estimators.py#L112-L200" class="git-link" target="_blank">Browse git</a>
 </summary>
 <pre><code class="python">class SamboSearchCV(BaseSearchCV):
     &#34;&#34;&#34;
     SAMBO hyper-parameter search with cross-validation that can be
     used to **optimize hyperparameters of machine learning estimator pipelines**
     like those of scikit-learn.
-    Similar to `GridSearchCV` from scikit-learn,
+    **Similar to `BayesSearchCV`** from _scikit-optimize_ or
+    `GridSearchCV` from _scikit-learn_,
     but hopefully **much faster for large parameter spaces**.
 
     Parameters
@@ -1704,7 +1714,8 @@ <h2 id="examples">Examples</h2>
 <div class="desc"><p>SAMBO hyper-parameter search with cross-validation that can be
 used to <strong>optimize hyperparameters of machine learning estimator pipelines</strong>
 like those of scikit-learn.
-Similar to <code>GridSearchCV</code> from scikit-learn,
+<strong>Similar to <code>BayesSearchCV</code></strong> from <em>scikit-optimize</em> or
+<code>GridSearchCV</code> from <em>scikit-learn</em>,
 but hopefully <strong>much faster for large parameter spaces</strong>.</p>
 <h2 id="parameters">Parameters</h2>
 <dl>

convergence2.svg

@@ -71,7 +71,7 @@ <h2 class="section-title" id="header-functions">Functions</h2>
 <details class="source">
 <summary>
 <span>Expand source code</span>
-<a href="https://github.com/sambo-optimization/sambo/blob/ec7433286915d71bb7bb8f4e38758eca5c7171f6/sambo/plot.py#L38-L103" class="git-link" target="_blank">Browse git</a>
+<a href="https://github.com/sambo-optimization/sambo/blob/a85f8fb9452ba14752943ce1587436f8394f6174/sambo/plot.py#L38-L103" class="git-link" target="_blank">Browse git</a>
 </summary>
 <pre><code class="python">def plot_convergence(
         *results: OptimizeResult | tuple[str, OptimizeResult],
@@ -168,7 +168,7 @@ <h2 id="example">Example</h2>
 <details class="source">
 <summary>
 <span>Expand source code</span>
-<a href="https://github.com/sambo-optimization/sambo/blob/ec7433286915d71bb7bb8f4e38758eca5c7171f6/sambo/plot.py#L656-L757" class="git-link" target="_blank">Browse git</a>
+<a href="https://github.com/sambo-optimization/sambo/blob/a85f8fb9452ba14752943ce1587436f8394f6174/sambo/plot.py#L656-L757" class="git-link" target="_blank">Browse git</a>
 </summary>
 <pre><code class="python">def plot_evaluations(
         result: OptimizeResult,
@@ -323,7 +323,7 @@ <h2 id="example">Example</h2>
 <details class="source">
 <summary>
 <span>Expand source code</span>
-<a href="https://github.com/sambo-optimization/sambo/blob/ec7433286915d71bb7bb8f4e38758eca5c7171f6/sambo/plot.py#L471-L653" class="git-link" target="_blank">Browse git</a>
+<a href="https://github.com/sambo-optimization/sambo/blob/a85f8fb9452ba14752943ce1587436f8394f6174/sambo/plot.py#L471-L653" class="git-link" target="_blank">Browse git</a>
 </summary>
 <pre><code class="python">def plot_objective(
         result: OptimizeResult,
@@ -589,7 +589,7 @@ <h2 id="example">Example</h2>
 <details class="source">
 <summary>
 <span>Expand source code</span>
-<a href="https://github.com/sambo-optimization/sambo/blob/ec7433286915d71bb7bb8f4e38758eca5c7171f6/sambo/plot.py#L128-L203" class="git-link" target="_blank">Browse git</a>
+<a href="https://github.com/sambo-optimization/sambo/blob/a85f8fb9452ba14752943ce1587436f8394f6174/sambo/plot.py#L128-L203" class="git-link" target="_blank">Browse git</a>
 </summary>
 <pre><code class="python">def plot_regret(
         *results: OptimizeResult | tuple[str, OptimizeResult],