saealib.LowerConfidenceBound#

class saealib.LowerConfidenceBound(kappa=2.0, obj_idx=0, beta_schedule=None, direction=None)[source]#

Bases: PointwiseAcquisition

Lower Confidence Bound (LCB) acquisition function.

LCB trades off exploitation (low predicted mean) and exploration (high predicted uncertainty):

LCB(x) = mu(x) - kappa * sigma(x)

For minimization, lower LCB values are better. This class returns the negated LCB so that higher scores indicate more promising candidates, consistent with the convention used by other acquisition functions.

Requires a surrogate that provides uncertainty estimates (std).

Parameters:

  • kappa (float) – Exploration-exploitation trade-off parameter used when beta_schedule is None. Higher values encourage more exploration. Default: 2.0.

  • obj_idx (int) – Index of the objective to optimize. Used for multi-objective problems where LCB is applied to a single objective. Default: 0.

  • beta_schedule (callable or None) – Optional beta_t schedule schedule(t) -> float (kappa corresponds to sqrt(beta_t) in the cited bound). When set, t = ctx.decision_count + 1 – the number of genuinely new evaluation plans the runtime has confirmed so far (synchronous or async), plus one for the decision about to be made – and kappa_t = sqrt(schedule(t)) replaces the fixed kappa. This makes t one full round in the cited paper’s sense only under synchronous, single-point-per-decision execution; see gp_ucb_beta_schedule(). None (default) keeps kappa fixed.

  • direction (np.ndarray or None) – Per-objective optimization direction (+1 = maximize, -1 = minimize). shape: (n_obj,). The predicted mean is converted to minimize-space via direction_to_minimize_sign before the (minimize-only) LCB formula above runs. None (default) means already-minimize; when unset, it is auto-injected from problem.direction at run start.

References

[25]: Srinivas, N., Krause, A., Kakade, S. M., & Seeger, M. W. (2012). Information-theoretic regret bounds for Gaussian process optimization in the bandit setting. IEEE Transactions on Information Theory, 58(5), 3250-3265.

Methods

__init__

compute_reference

LowerConfidenceBound uses no reference value; always returns None.

contract

Return the pointwise acquisition contract.

evaluate

Reject prediction is None, resolve the reference, then score().

prepare

Resolve the beta_schedule-driven kappa for this decision, if set.

score

Compute negated LCB scores (higher is better).

Method Details

LowerConfidenceBound.__init__(kappa=2.0, obj_idx=0, beta_schedule=None, direction=None)[source]#
Parameters:

  • kappa (float)

  • obj_idx (int)

  • beta_schedule (Callable[[int], float] | None)

  • direction (ndarray | None)

LowerConfidenceBound.compute_reference(archive, rng=None)[source]#

LowerConfidenceBound uses no reference value; always returns None.

Parameters:

  • archive (Archive)

  • rng (np.random.Generator | None)

Return type:

Any

LowerConfidenceBound.contract()#

Return the pointwise acquisition contract.

Return type:

ComponentContract

LowerConfidenceBound.evaluate(candidates_x, prediction, archive, ctx=None, *, prepared=<object object>)#

Reject prediction is None, resolve the reference, then score().

See AcquisitionFunction.evaluate() for the shared parameter contract, including the _UNSET vs. explicit prepared=None distinction.

Parameters:

  • candidates_x (np.ndarray)

  • prediction (SurrogatePrediction | None)

  • archive (Archive)

  • ctx (OptimizationState | None)

  • prepared (Any)

Return type:

AcquisitionResult

LowerConfidenceBound.prepare(archive, ctx=None)[source]#

Resolve the beta_schedule-driven kappa for this decision, if set.

Overrides PointwiseAcquisition.prepare() (rather than only compute_reference()) because resolving beta_schedule needs ctx.decision_count, which compute_reference() has no access to. When beta_schedule is None, delegates to compute_reference() unchanged.

Returns:

None when beta_schedule is unset; otherwise the resolved kappa_t float, passed to score() as reference.

Return type:

Any

Raises:

ValidationError – If beta_schedule is set but ctx is None (t has no source). Call via evaluate() with a real ctx, not score() directly. If beta_schedule returns a non-finite or negative value.

Parameters:

  • archive (Archive)

  • ctx (OptimizationState | None)

LowerConfidenceBound.score(prediction, reference=None, rng=None)[source]#

Compute negated LCB scores (higher is better).

Parameters:

  • prediction (SurrogatePrediction) – Surrogate predictions. Must have std (has_uncertainty == True).

  • reference (Any) – The kappa_t resolved by prepare() when beta_schedule is set (None otherwise). Passing None here while beta_schedule is set is a caller error (see raises below); it never silently falls back to the fixed kappa.

  • rng (Generator | None)

Returns:

Negated LCB scores. shape: (n_samples,)

Return type:

np.ndarray

Raises:

  • TypeError – If prediction does not contain uncertainty estimates.

  • ValidationError – If beta_schedule is set but reference is None (i.e. score() was called directly, bypassing prepare()).