calibrated-bo 0.2.0__tar.gz

calibrated_bo-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shifa Zhong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

calibrated_bo-0.2.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: calibrated-bo
+Version: 0.2.0
+Summary: Calibrated Bayesian optimization with composable conformal prediction (Weighted + Localized + Adaptive) on top of bayesian-gp-cvloss.
+Author-email: Shifa Zhong <sfzhong@tongji.edu.cn>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/Shifa-Zhong/calibrated-bo
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bayesian-gp-cvloss>=0.3.1
+Requires-Dist: numpy>=1.18.0
+Requires-Dist: scipy>=1.5.0
+Requires-Dist: scikit-learn>=0.23.0
+Dynamic: license-file
+
+# calibrated-bo
+
+Calibrated Bayesian optimization with composable conformal prediction, built
+on top of [`bayesian-gp-cvloss`](https://github.com/Shifa-Zhong/bayesian-gp-cvloss).
+
+**Phase 1 (this release)** — core single-objective stack:
+
+- `CompositeConformalCalibrator` with three orthogonal switches:
+  - `localized=True` — pick only x*'s k-NN from the calibration set
+  - `weighted=True` — RBF weights against x* on the surviving subset
+  - `adaptive=True` — ACI controller updates α from rolling coverage
+- `CalibratedUCB`, `CalibratedEI` — drop-in calibrated acquisitions
+- `CalibratedBOLoop` — single-objective loop (`suggest()` / `observe()`)
+- Platform adapter (`create_bo_session(config)`)
+
+All three calibrator switches are independent: turn them all off and the
+calibrator is numerically equivalent to standard split CP.
+
+**Phase 2 (planned)** — multi-objective EHVI, q-batch with fantasies,
+diagnostics dashboard, native gp-cv platform integration.
+
+## Install
+
+```bash
+pip install -e D:/mypackage/calibrated-bo
+```
+
+Requires `bayesian-gp-cvloss>=0.3.1`.
+
+## Quickstart
+
+```python
+import numpy as np
+from calibrated_bo import CalibratedBOLoop
+
+# 2D toy: minimise (x-0.3)^2 + (y-0.7)^2
+def f(x):
+    return np.sum((x - np.array([0.3, 0.7]))**2)
+
+bo = CalibratedBOLoop(
+    bounds=[(0.0, 1.0), (0.0, 1.0)],
+    objective="minimize",
+    calibrator_config={
+        "alpha": 0.1,
+        "localized": True, "k": 20,
+        "weighted": True,
+        "adaptive": True, "gamma": 0.05,
+    },
+    acquisition="cUCB",
+    acquisition_kwargs={"beta": 2.0},
+    batch_size=1,
+    initial_random=5,
+    gp_max_evals=30,
+)
+
+for step in range(20):
+    X_next = bo.suggest()
+    y_next = np.array([f(x) for x in X_next])
+    bo.observe(X_next, y_next)
+
+print("best so far:", bo.best)
+print("diagnostics:", bo.diagnostics())
+```
+
+## Calibrator-only usage
+
+If you only want the calibrator (no BO loop), drop it on top of any fitted
+`GPCrossValidatedOptimizer`:
+
+```python
+from bayesian_gp_cvloss import GPCrossValidatedOptimizer
+from calibrated_bo import CompositeConformalCalibrator
+
+opt = GPCrossValidatedOptimizer(X_train, y_train, scoring="cv_rmse")
+opt.optimize(max_evals=50)
+
+cal = CompositeConformalCalibrator(
+    alpha=0.1, localized=True, weighted=True, adaptive=False
+).fit_cv(opt)
+
+mean, lower, upper = cal.predict_interval(X_new)
+```
+
+## Design
+
+See the project spec (calibrated-bo design doc) for the math behind
+Localized + Weighted + Adaptive coordination and the joint half-width
+formula.

calibrated_bo-0.2.0/README.md

@@ -0,0 +1,88 @@
+# calibrated-bo
+
+Calibrated Bayesian optimization with composable conformal prediction, built
+on top of [`bayesian-gp-cvloss`](https://github.com/Shifa-Zhong/bayesian-gp-cvloss).
+
+**Phase 1 (this release)** — core single-objective stack:
+
+- `CompositeConformalCalibrator` with three orthogonal switches:
+  - `localized=True` — pick only x*'s k-NN from the calibration set
+  - `weighted=True` — RBF weights against x* on the surviving subset
+  - `adaptive=True` — ACI controller updates α from rolling coverage
+- `CalibratedUCB`, `CalibratedEI` — drop-in calibrated acquisitions
+- `CalibratedBOLoop` — single-objective loop (`suggest()` / `observe()`)
+- Platform adapter (`create_bo_session(config)`)
+
+All three calibrator switches are independent: turn them all off and the
+calibrator is numerically equivalent to standard split CP.
+
+**Phase 2 (planned)** — multi-objective EHVI, q-batch with fantasies,
+diagnostics dashboard, native gp-cv platform integration.
+
+## Install
+
+```bash
+pip install -e D:/mypackage/calibrated-bo
+```
+
+Requires `bayesian-gp-cvloss>=0.3.1`.
+
+## Quickstart
+
+```python
+import numpy as np
+from calibrated_bo import CalibratedBOLoop
+
+# 2D toy: minimise (x-0.3)^2 + (y-0.7)^2
+def f(x):
+    return np.sum((x - np.array([0.3, 0.7]))**2)
+
+bo = CalibratedBOLoop(
+    bounds=[(0.0, 1.0), (0.0, 1.0)],
+    objective="minimize",
+    calibrator_config={
+        "alpha": 0.1,
+        "localized": True, "k": 20,
+        "weighted": True,
+        "adaptive": True, "gamma": 0.05,
+    },
+    acquisition="cUCB",
+    acquisition_kwargs={"beta": 2.0},
+    batch_size=1,
+    initial_random=5,
+    gp_max_evals=30,
+)
+
+for step in range(20):
+    X_next = bo.suggest()
+    y_next = np.array([f(x) for x in X_next])
+    bo.observe(X_next, y_next)
+
+print("best so far:", bo.best)
+print("diagnostics:", bo.diagnostics())
+```
+
+## Calibrator-only usage
+
+If you only want the calibrator (no BO loop), drop it on top of any fitted
+`GPCrossValidatedOptimizer`:
+
+```python
+from bayesian_gp_cvloss import GPCrossValidatedOptimizer
+from calibrated_bo import CompositeConformalCalibrator
+
+opt = GPCrossValidatedOptimizer(X_train, y_train, scoring="cv_rmse")
+opt.optimize(max_evals=50)
+
+cal = CompositeConformalCalibrator(
+    alpha=0.1, localized=True, weighted=True, adaptive=False
+).fit_cv(opt)
+
+mean, lower, upper = cal.predict_interval(X_new)
+```
+
+## Design
+
+See the project spec (calibrated-bo design doc) for the math behind
+Localized + Weighted + Adaptive coordination and the joint half-width
+formula.

calibrated_bo-0.2.0/calibrated_bo/__init__.py

@@ -0,0 +1,50 @@
+"""
+calibrated-bo: Composable conformal calibration + calibrated acquisition + BO loop
+on top of bayesian-gp-cvloss.
+
+Quick imports:
+    from calibrated_bo import (
+        CompositeConformalCalibrator,
+        AdaptiveAlphaController,
+        CalibratedUCB,
+        CalibratedEI,
+        CalibratedBOLoop,
+    )
+"""
+from .calibration.base import BaseConformalCalibrator
+from .calibration.adaptive import AdaptiveAlphaController
+from .calibration.composite import CompositeConformalCalibrator
+from .calibration.multi_output import MultiOutputCalibrator
+from .calibration.presets import (
+    AdaptiveConformalCalibrator,
+    LocalizedConformalCalibrator,
+    WeightedConformalCalibrator,
+)
+from .acquisition.single_obj import CalibratedAcquisition, CalibratedUCB, CalibratedEI
+from .acquisition.multi_obj import CalibratedMultiAcquisition, CalibratedEHVI
+from .acquisition.batch import greedy_q_batch
+from .loop.bo_loop import CalibratedBOLoop
+from .platform.adapter import create_bo_session
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # Calibration
+    "BaseConformalCalibrator",
+    "AdaptiveAlphaController",
+    "CompositeConformalCalibrator",
+    "MultiOutputCalibrator",
+    "WeightedConformalCalibrator",
+    "LocalizedConformalCalibrator",
+    "AdaptiveConformalCalibrator",
+    # Acquisition
+    "CalibratedAcquisition",
+    "CalibratedUCB",
+    "CalibratedEI",
+    "CalibratedMultiAcquisition",
+    "CalibratedEHVI",
+    "greedy_q_batch",
+    # Loop
+    "CalibratedBOLoop",
+    "create_bo_session",
+]

calibrated_bo-0.2.0/calibrated_bo/acquisition/__init__.py

@@ -0,0 +1,12 @@
+from .single_obj import CalibratedAcquisition, CalibratedUCB, CalibratedEI
+from .multi_obj import CalibratedMultiAcquisition, CalibratedEHVI
+from .batch import greedy_q_batch
+
+__all__ = [
+    "CalibratedAcquisition",
+    "CalibratedUCB",
+    "CalibratedEI",
+    "CalibratedMultiAcquisition",
+    "CalibratedEHVI",
+    "greedy_q_batch",
+]

calibrated_bo-0.2.0/calibrated_bo/acquisition/_pareto.py

@@ -0,0 +1,149 @@
+"""Pareto and hypervolume helpers (multi-objective).
+
+Convention used everywhere in this package:
+- Internal multi-objective vectors are oriented for MAXIMISATION on every
+  component. The BO loop flips signs externally for any minimisation
+  objective so the acquisition / Pareto / HV code can stay sign-agnostic.
+
+Only depends on numpy. Two algorithms inside:
+- ``pareto_front_mask(Y)``: O(N^2) non-dominance scan -- fine for the small N
+  typical in materials / chemistry BO (N < a few thousand).
+- ``dominated_hypervolume(Y, ref)``: 2D closed form + 3D/higher inclusion-
+  exclusion via WFG-style decomposition is overkill here -- we use a simple
+  recursive box-difference scheme that is O(N^M) but exact, plus a fast 2D
+  case. Adequate for M <= 3 with N < 200.
+
+For the typical calibrated-BO settings (M = 2 or 3, |Pareto| < 30), this is
+fast enough; if we ever need M >= 4 with large fronts, swap in pymoo's WFG.
+"""
+from typing import Tuple
+
+import numpy as np
+
+
+def pareto_front_mask(Y: np.ndarray) -> np.ndarray:
+    """Boolean mask of non-dominated rows under MAXIMISATION on all columns.
+
+    Y: (N, M). Returns: (N,) bool.
+    A point is non-dominated if no other point strictly dominates it.
+    """
+    Y = np.atleast_2d(np.asarray(Y, dtype=float))
+    n = Y.shape[0]
+    keep = np.ones(n, dtype=bool)
+    for i in range(n):
+        if not keep[i]:
+            continue
+        # Any other point j weakly >= Y[i] on all coords AND strictly > on at least one.
+        dominates_i = np.all(Y >= Y[i], axis=1) & np.any(Y > Y[i], axis=1)
+        dominates_i[i] = False
+        if dominates_i.any():
+            keep[i] = False
+    return keep
+
+
+def pareto_front(Y: np.ndarray) -> np.ndarray:
+    """Return the non-dominated subset of rows (maximisation)."""
+    return Y[pareto_front_mask(Y)]
+
+
+def infer_reference_point(Y: np.ndarray, margin: float = 0.1) -> np.ndarray:
+    """Reference point for hypervolume: a bit *below* the worst observed value
+    on each objective (maximisation convention). ``margin`` is fraction of
+    objective range.
+    """
+    Y = np.atleast_2d(np.asarray(Y, dtype=float))
+    lo = Y.min(axis=0)
+    hi = Y.max(axis=0)
+    span = np.where(hi > lo, hi - lo, 1.0)
+    return lo - margin * span
+
+
+def dominated_hypervolume(Y: np.ndarray, ref: np.ndarray) -> float:
+    """Hypervolume of the region dominated by Y w.r.t. ref point (maximisation).
+
+    Supports any M >= 1, but optimised for M=2 (closed form). M=1 returns
+    ``max(0, max(Y) - ref)``. M=3+ uses inclusion-exclusion in axis-aligned
+    boxes -- correct but O(N^M); fine for the small-N small-M cases this
+    library targets.
+    """
+    Y = np.atleast_2d(np.asarray(Y, dtype=float))
+    ref = np.asarray(ref, dtype=float).flatten()
+    if Y.shape[1] != ref.size:
+        raise ValueError(f"Y has {Y.shape[1]} cols but ref has {ref.size}")
+    # Clip to ref: only the > ref portion contributes.
+    Y_clip = np.maximum(Y, ref[None, :])
+    # Keep only non-dominated points (everything else contributes nothing new).
+    mask = pareto_front_mask(Y_clip)
+    P = Y_clip[mask]
+    if P.size == 0:
+        return 0.0
+    M = P.shape[1]
+    if M == 1:
+        return float(P[:, 0].max() - ref[0])
+    if M == 2:
+        return _hv_2d(P, ref)
+    return _hv_recursive(P, ref)
+
+
+def _hv_2d(P: np.ndarray, ref: np.ndarray) -> float:
+    """2D hypervolume (maximisation). P is already non-dominated."""
+    # Sort by first objective descending; second objective then strictly increases.
+    order = np.argsort(-P[:, 0], kind="mergesort")
+    P_sorted = P[order]
+    hv = 0.0
+    prev_y2 = ref[1]
+    with np.errstate(over="ignore", invalid="ignore"):
+        for x1, x2 in P_sorted:
+            if x2 <= prev_y2:
+                continue  # dominated under maximisation (shouldn't happen if filtered)
+            hv += float((x1 - ref[0]) * (x2 - prev_y2))
+            prev_y2 = x2
+    return float(hv)
+
+
+def _hv_recursive(P: np.ndarray, ref: np.ndarray) -> float:
+    """Generic M-dim hypervolume via inclusion-exclusion. O(2^N) worst case
+    but the calls in EHVI happen on the current Pareto front (typically
+    |P| <= 30) so this stays cheap."""
+    n = P.shape[0]
+    if n == 0:
+        return 0.0
+    if n == 1:
+        return float(np.prod(P[0] - ref))
+    total = 0.0
+    # Use Walking-Box / inclusion-exclusion: HV(P) = sum_{S subset, S nonempty}
+    # (-1)^(|S|+1) * prod(min_{i in S}(P_i) - ref).
+    # Practical only for n up to ~20. For larger n, fall back to a greedy
+    # decomposition: project on last axis, recurse on slices.
+    if n > 18:
+        return _hv_slice(P, ref)
+    for mask in range(1, 1 << n):
+        bits = bin(mask).count("1")
+        rows = []
+        for i in range(n):
+            if mask & (1 << i):
+                rows.append(P[i])
+        sub = np.array(rows)
+        mins = sub.min(axis=0)
+        box = np.prod(np.maximum(mins - ref, 0.0))
+        total += ((-1) ** (bits + 1)) * box
+    return float(total)
+
+
+def _hv_slice(P: np.ndarray, ref: np.ndarray) -> float:
+    """Slice-based HV for larger fronts: project onto the last axis, recurse."""
+    M = P.shape[1]
+    order = np.argsort(P[:, -1], kind="mergesort")
+    P_sorted = P[order]
+    hv = 0.0
+    prev = ref[-1]
+    for i, row in enumerate(P_sorted):
+        if row[-1] <= prev:
+            continue
+        upper_slice = P_sorted[i:, :-1]
+        # Only non-dominated points in the slice contribute to the slab volume.
+        keep = pareto_front_mask(upper_slice)
+        slab = dominated_hypervolume(upper_slice[keep], ref[:-1])
+        hv += slab * (row[-1] - prev)
+        prev = row[-1]
+    return float(hv)

calibrated_bo-0.2.0/calibrated_bo/acquisition/batch.py

@@ -0,0 +1,91 @@
+"""q-batch acquisition via sequential greedy + kriging-believer fantasies.
+
+Strategy: pick the candidate that maximises the acquisition, "pretend" we
+observed it at the calibrator's predicted mean (kriging believer), rebuild
+the acquisition on the augmented Pareto / y_best, and repeat ``q`` times.
+
+Why not the closed-form q-EI / q-EHVI? Because those require differentiable
+MC samplers (BoTorch territory). Greedy + kriging-believer is the standard
+practitioner shortcut, gives ~80-90% of the gain with a fraction of the
+code, and is the recommended Phase 2 default per the spec.
+
+This module is intentionally generic: it works with any callable acquisition
+``acq(X) -> scores`` and a *rebuild* function that the loop knows how to
+write (because it knows whether single-obj y_best or multi-obj Pareto is
+the relevant state).
+"""
+from typing import Callable, Iterable, List, Optional
+
+import numpy as np
+
+
+def greedy_q_batch(
+    candidate_pool: np.ndarray,
+    acq_fn: Callable[[np.ndarray], np.ndarray],
+    q: int,
+    rebuild_after_pick: Optional[Callable[[np.ndarray, np.ndarray], Callable]] = None,
+    predict_fn: Optional[Callable[[np.ndarray], np.ndarray]] = None,
+    dedupe_round: int = 8,
+) -> np.ndarray:
+    """Pick ``q`` distinct candidates by sequential greedy on ``acq_fn``.
+
+    Parameters
+    ----------
+    candidate_pool : (N, d) ndarray
+    acq_fn : callable
+        Initial acquisition. Returns shape (N,).
+    q : int
+        Batch size.
+    rebuild_after_pick : optional callable (x_picked, y_fantasy) -> new acq_fn
+        If provided, after each pick the acquisition is rebuilt with the
+        fantasy point appended to the calibrator's observed set. If None,
+        we just blacklist picked points and use the original acq_fn.
+    predict_fn : optional callable (X (1, d)) -> y (M,) ndarray of *means*
+        Required when ``rebuild_after_pick`` is provided. Produces the fantasy
+        y at the just-picked x.
+    dedupe_round : int
+        Round candidate coords to this many decimals when building the
+        already-picked set (handles float identity issues).
+
+    Returns
+    -------
+    picks : (q_actual, d) ndarray
+    """
+    if q < 1:
+        raise ValueError("q must be >= 1")
+    pool = np.atleast_2d(np.asarray(candidate_pool, dtype=float))
+    if pool.shape[0] == 0:
+        return np.empty((0, pool.shape[1] if pool.ndim == 2 else 0))
+
+    picked: List[np.ndarray] = []
+    chosen_keys: set = set()
+    current_acq = acq_fn
+
+    while len(picked) < q:
+        scores = current_acq(pool)
+        # Mask out already picked rows.
+        scores = np.asarray(scores, dtype=float).copy()
+        if np.all(~np.isfinite(scores)):
+            break
+        order = np.argsort(scores)[::-1]
+        chosen = None
+        for idx in order:
+            x = pool[idx]
+            key = tuple(np.round(x, dedupe_round).tolist())
+            if key in chosen_keys:
+                continue
+            chosen = x
+            chosen_keys.add(key)
+            break
+        if chosen is None:
+            break
+        picked.append(chosen)
+        if rebuild_after_pick is None or len(picked) >= q:
+            continue
+        if predict_fn is None:
+            raise ValueError("predict_fn must be provided when rebuild_after_pick is set")
+        # Build the fantasy y_hat at the just-picked x.
+        y_fantasy = predict_fn(chosen[None, :])
+        current_acq = rebuild_after_pick(chosen[None, :], y_fantasy)
+
+    return np.asarray(picked)

calibrated_bo-0.2.0/calibrated_bo/acquisition/multi_obj.py

@@ -0,0 +1,107 @@
+"""Multi-objective calibrated acquisitions.
+
+Currently exposes:
+
+* ``CalibratedEHVI`` -- MC-based Expected Hypervolume Improvement using
+  calibrated (mean, sigma_cal) per objective.
+
+Convention
+----------
+Internally all objectives are oriented for MAXIMISATION (the BO loop flips
+signs externally for any minimisation direction so the multi-objective code
+stays sign-agnostic).
+"""
+from typing import Optional
+
+import numpy as np
+
+from ..calibration.multi_output import MultiOutputCalibrator
+from ._pareto import (
+    dominated_hypervolume,
+    infer_reference_point,
+    pareto_front_mask,
+)
+
+
+class CalibratedMultiAcquisition:
+    """Abstract base for multi-objective acquisitions over MultiOutputCalibrator."""
+
+    def __init__(self, calibrator: MultiOutputCalibrator):
+        if not isinstance(calibrator, MultiOutputCalibrator):
+            raise TypeError("calibrator must be a MultiOutputCalibrator")
+        self.calibrator = calibrator
+
+    def __call__(self, X: np.ndarray) -> np.ndarray:
+        raise NotImplementedError
+
+
+class CalibratedEHVI(CalibratedMultiAcquisition):
+    """MC EHVI with calibrated per-objective uncertainty.
+
+    Treats the calibrated half-width ``sigma_cal`` as a Gaussian std-dev
+    (deliberate approximation -- see Phase 1 cUCB/cEI for the same trade).
+    Samples ``n_samples`` from the per-objective independent normals, computes
+    HV improvement vs the current Pareto front for each MC sample, returns
+    the mean.
+
+    Parameters
+    ----------
+    calibrator : MultiOutputCalibrator
+    Y_observed : (n_obs, M) ndarray
+        Already in maximisation orientation. The loop transforms before passing.
+    ref_point : (M,) ndarray, optional
+        Hypervolume reference point. If None, inferred from Y_observed.
+    n_samples : int
+        MC sample count.
+    random_state : int
+        Seed for the MC draws (reseeded each call so acquisition is
+        deterministic given the data state).
+    """
+
+    def __init__(
+        self,
+        calibrator: MultiOutputCalibrator,
+        Y_observed: np.ndarray,
+        ref_point: Optional[np.ndarray] = None,
+        n_samples: int = 64,
+        random_state: int = 0,
+    ):
+        super().__init__(calibrator)
+        Y_observed = np.atleast_2d(np.asarray(Y_observed, dtype=float))
+        if Y_observed.shape[1] != calibrator.n_objectives:
+            raise ValueError(
+                f"Y_observed has {Y_observed.shape[1]} cols but calibrator has "
+                f"{calibrator.n_objectives} objectives"
+            )
+        self.Y_observed = Y_observed
+        self.ref_point = (np.asarray(ref_point, dtype=float).flatten()
+                          if ref_point is not None
+                          else infer_reference_point(Y_observed))
+        self.n_samples = int(n_samples)
+        self.random_state = int(random_state)
+        # Precompute current Pareto + current HV.
+        self._pareto = Y_observed[pareto_front_mask(Y_observed)]
+        self._hv_baseline = dominated_hypervolume(self._pareto, self.ref_point)
+
+    def __call__(self, X: np.ndarray) -> np.ndarray:
+        X = np.atleast_2d(np.asarray(X, dtype=float))
+        means, sigmas = self.calibrator.predict_calibrated(X)
+        # means / sigmas: (n_candidates, M)
+        rng = np.random.default_rng(self.random_state)
+        n, M = means.shape
+        # Draw (n_samples, n, M) Gaussian samples.
+        z = rng.standard_normal((self.n_samples, n, M))
+        samples = means[None, :, :] + sigmas[None, :, :] * z  # broadcast OK
+        # For each candidate i, compute mean HV improvement over MC samples.
+        out = np.zeros(n)
+        for i in range(n):
+            improvements = np.empty(self.n_samples)
+            for s in range(self.n_samples):
+                y_new = samples[s, i, :]
+                # Append y_new to Pareto, recompute non-dominated set, then HV.
+                combined = np.vstack([self._pareto, y_new[None, :]])
+                pf = combined[pareto_front_mask(combined)]
+                hv_new = dominated_hypervolume(pf, self.ref_point)
+                improvements[s] = max(0.0, hv_new - self._hv_baseline)
+            out[i] = float(np.mean(improvements))
+        return out