saealib.CORSDistance

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

ベースクラス: 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.

パラメータ:

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

参照

[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)

パラメータ:

• delta (float | None)

• search_pattern (Sequence[float])

• weights (ndarray | None)

• direction (ndarray | None)

CORSDistance.compute_reference(archive, rng=None)

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.

パラメータ:

• archive (Archive)

• rng (np.random.Generator | None)

戻り値の型:

CORSReference

CORSDistance.contract()

Return the pointwise acquisition contract.

戻り値の型:

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.

パラメータ:

• candidates_x (np.ndarray)

• prediction (SurrogatePrediction | None)

• archive (Archive)

• ctx (OptimizationState | None)

• prepared (Any)

戻り値の型:

AcquisitionResult

CORSDistance.prepare(archive, ctx=None)

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.

例外:

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.

パラメータ:

• archive (Archive)

• ctx (OptimizationState | None)

戻り値の型:

CORSReference

CORSDistance.score(prediction, reference, rng=None)

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

パラメータ:

• 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)

戻り値:

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.

戻り値の型:

np.ndarray

例外:

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

• ValidationError -- If reference is not a CORSReference.