saealib.EHVIAcquisition#

class saealib.EHVIAcquisition(n_samples=256, reference_point=None, rng=None, direction=None)[source]#

Bases: PointwiseAcquisition

Expected Hypervolume Improvement (EHVI) acquisition function.

Estimates EHVI via Monte Carlo sampling. The exact EHVI and HVI concepts follow Hupkens (2015) and Daulton et al. (2020); the sample average below is the approximation used by this implementation:

EHVI(x) = (1/S) * sum_s HVI(y_s, P, r)
y_s ~ N(mu(x), diag(sigma^2(x)))   [independent objectives]

where HVI(y, P, r) = HV(P u {y}, r) - HV(P, r).

archive.f, reference_point, and the predicted mean are internally converted to minimisation convention via direction_to_minimize_sign (see direction below) before the formula above runs.

Parameters:

n_samples (int) – Number of MC samples per candidate. Default: 256.
reference_point (array-like or None) – Hypervolume reference point, given in raw objective space (i.e. in the same convention as problem.direction, not necessarily minimisation). If None, auto-computed from the archive nadir with a 10 % margin.
rng (np.random.Generator or None) – Random number generator for MC sampling.
direction (np.ndarray or None) – Per-objective optimization direction (+1 = maximize, -1 = minimize). shape: (n_obj,). None (default) means already-minimize, so behaviour for existing minimize-only callers is unchanged; when unset, it is auto-injected from problem.direction at run start.

Methods

`__init__`
`compute_reference`	Extract the Pareto front and (if needed) compute the reference point.
`contract`	Return the expected-hypervolume-improvement contract.
`evaluate`	Reject `prediction is None`, resolve the reference, then `score()`.
`prepare`	Delegate to `compute_reference(archive, rng=ctx.rng if ctx else None)`.
`score`	Estimate EHVI via Monte Carlo sampling.

Method Details

EHVIAcquisition.__init__(n_samples=256, reference_point=None, rng=None, direction=None)[source]#

Parameters:

n_samples (int)
reference_point (ArrayLike | None)
rng (Generator | None)
direction (ndarray | None)

Return type:

None

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

Extract the Pareto front and (if needed) compute the reference point.

Parameters:

archive (Archive) – Archive of evaluated solutions.
rng (np.random.Generator | None)

Returns:

(pareto_f, ref_point, base_hv) — non-dominated objective matrix, hypervolume reference point, and current hypervolume.

Return type:

tuple

EHVIAcquisition.contract()[source]#

Return the expected-hypervolume-improvement contract.

Return type:: ComponentContract

EHVIAcquisition.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

EHVIAcquisition.prepare(archive, ctx=None)#

Delegate to compute_reference(archive, rng=ctx.rng if ctx else None).

Parameters:

archive (Archive)
ctx (OptimizationState | None)

Return type:

Any

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

Estimate EHVI via Monte Carlo sampling.

Parameters:

prediction (SurrogatePrediction) – Surrogate predictions. Must have std (has_uncertainty == True).
reference (tuple) – (pareto_f, ref_point, base_hv) from compute_reference.
rng (np.random.Generator or None, optional) – Random number generator. When provided (e.g. ctx.rng), it is used instead of the instance-level _rng so all randomness flows through the master RNG.

Returns:

EHVI scores. shape: (n_samples,). Higher is better.

Return type:

np.ndarray

Raises:

TypeError – If prediction does not contain uncertainty estimates.