saealib.CORSDistance#

class saealib.CORSDistance(delta=None, search_pattern=(0.95, 0.25, 0.05, 0.03, 0.0), weights=None, direction=None)[source]#

Bases: PointwiseAcquisition

CORS distance-constrained predicted-mean acquisition function.

Implements the auxiliary problem (CORS-AP) of the Constrained Optimization using Response Surfaces (CORS) method: the predicted-mean score used to rank candidates for the next costly evaluation is overridden to the worst possible value (-np.inf) for any candidate that violates the distance constraint:

||x - x_j|| >= beta_i * Delta_i,  j = 1, ..., k + i - 1

i.e. whose minimum distance to every previously evaluated point falls below the current iteration’s threshold beta_i * Delta_i. beta_i cycles through search_pattern: the parameters are set by performing cycles of N + 1 iterations, with beta_i = beta_{i + N + 1} for all i >= 1 and 1 >= beta_1 >= ... >= beta_{N+1} = 0 in the cited work. saealib accepts any non-empty finite sequence of beta values in [0, 1]; the paper’s ordering and terminal-zero conditions are not required. prepare() resolves the entry of search_pattern selected by ctx.decision_count; the first decision uses search_pattern[0]. The decision count is supplied by the runtime so repeated preparation caused by archive changes cannot skip a CORS phase. compute_reference() remains available for context-free direct use and returns the first phase.

Regis & Shoemaker (2005) define Delta_i as the maximin distance over the feasible domain D from the previously evaluated points:

Delta_i = max_{x_tilde in D} min_j ||x_tilde - x_j||

The exact domain-wide maximum is not available to an acquisition function, so when delta is None this implementation approximates it with the candidate pool in prediction.x as the cover points: max_c min_j ||candidate_c - evaluated_j||. This approximation can underestimate Delta_i when a later candidate pool is concentrated in a promising region and therefore covers less of D than the full domain. Since beta <= 1 guarantees that a maximin candidate in a non-empty pool is executable (equality is allowed), the approximation cannot silently leave no executable candidate and force an arbitrary choice. Passing a numeric delta opts into the legacy fixed distance scale.

Because neither prediction.value nor the archive-derived reference carries candidate coordinates, this class reads the candidate design vectors from prediction.x; the surrogate’s predict() must populate that field.

Parameters:

  • delta (float or None, optional) – Fixed distance scale for the current threshold beta_i * delta. When None (the default), compute the paper’s Delta_i at each score call from the candidate pool as an approximation. A numeric value preserves the legacy fixed-scale behavior.

  • search_pattern (Sequence[float]) – The beta cycling sequence. Any non-empty sequence of finite values in [0, 1] is accepted. Defaults to the paper’s own SP1 = <0.95, 0.25, 0.05, 0.03, 0>; reported as the stronger of the two search patterns the paper tested on the Dixon-Szego benchmark suite.

  • weights (np.ndarray or None) – Weights for magnitude-aware scalarization of multi-objective predicted means. shape: (n_obj,). See MeanPrediction.

  • direction (np.ndarray or None) – Per-objective optimization direction (+1 = maximize, -1 = minimize). See MeanPrediction. When unset, it is auto-injected from problem.direction at run start.

References

[17]: Regis, R. G., & Shoemaker, C. A. (2005). Constrained global optimization of expensive black box functions using radial basis functions. Journal of Global Optimization, 31(1), 153-171.

Methods

__init__

compute_reference

Return the archive reference using the first beta phase.

contract

Return the pointwise acquisition contract.

evaluate

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

prepare

Resolve the CORS reference for the current runtime decision.

score

Compute predicted-mean scores, excluding distance-constraint violators.

Method Details

CORSDistance.__init__(delta=None, search_pattern=(0.95, 0.25, 0.05, 0.03, 0.0), weights=None, direction=None)[source]#
Parameters:

  • delta (float | None)

  • search_pattern (Sequence[float])

  • weights (ndarray | None)

  • direction (ndarray | None)

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

Return the archive reference using the first beta phase.

The runtime calls prepare() with an OptimizationState so that the beta phase is derived from ctx.decision_count. Direct calls to this context-free hook use the first phase and do not retain mutable cycle state.

Parameters:

  • archive (Archive)

  • rng (np.random.Generator | None)

Return type:

CORSReference

CORSDistance.contract()#

Return the pointwise acquisition contract.

Return type:

ComponentContract

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

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

Resolve the CORS reference for the current runtime decision.

ctx.decision_count counts confirmed evaluation plans, so it is unchanged by repeated preparation within a decision and advances by one for each new synchronous or asynchronous decision.

Raises:

ValidationError – If no runtime context is supplied. The phase has no reliable source without ctx.decision_count; use compute_reference for context-free direct access to the first phase.

Parameters:

  • archive (Archive)

  • ctx (OptimizationState | None)

Return type:

CORSReference

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

Compute predicted-mean scores, excluding distance-constraint violators.

Parameters:

  • prediction (SurrogatePrediction) – Surrogate predictions. prediction.value shape: (n_samples, n_obj). prediction.x must hold the candidate design vectors, shape: (n_samples, n_features), aligned row-for-row with prediction.value.

  • reference (CORSReference) – The reference returned by prepare() or compute_reference(), including the current beta constraint.

  • rng (Generator | None)

Returns:

Scores. shape: (n_samples,). Candidates whose minimum distance to every evaluated point in reference is below the current beta_i * Delta_i threshold receive -np.inf. With delta=None, Delta_i is the candidate-pool maximin distance; with an explicit delta, it is that fixed value.

Return type:

np.ndarray

Raises:

  • ValueError – If prediction.x is missing or its row count does not match prediction.value.

  • ValidationError – If reference is not a CORSReference.