sampling.mm.mm_corrected_improvement

sampling.mm.mm_corrected_improvement(
    x,
    X_base,
    phi_base=None,
    J_base=None,
    d_base=None,
    q=2,
    p=2,
    normalize_flag=False,
    verbose=False,
    exponential=True,
)

Calculates the corrected Morris-Mitchell improvement for a candidate point.

Measures how much the corrected criterion :math:\hat{\Phi}_q improves (decreases) when x is added to the existing design X_base.

The improvement is defined as:

.. math::

\Delta\hat{\Phi}(x) =
\begin{cases}
    \exp\bigl(\hat{\Phi}_q(X_{\text{base}}) -
               \hat{\Phi}_q(X_{\text{base}} \cup \{x\})\bigr)
        & \text{if } \texttt{exponential=True} \\
    \hat{\Phi}_q(X_{\text{base}}) -
        \hat{\Phi}_q(X_{\text{base}} \cup \{x\})
        & \text{otherwise}
\end{cases}

A positive value indicates that adding x improves the design (lowers :math:\hat{\Phi}_q). The exponential form maps the improvement to :math:(0, \infty) and is convenient as a desirability-function input.

The cached (phi_base, J_base, d_base) triple can be supplied to avoid recomputing the base criterion when calling this function repeatedly for many candidates. If omitted, the base criterion is computed from scratch.

Parameters

Name Type Description Default
x np.ndarray Candidate point, shape (k,) or (1, k). required
X_base np.ndarray Existing design points, shape (n, k). required
phi_base float Pre-computed :math:\hat{\Phi}_q for X_base. Computed internally if not provided. None
J_base np.ndarray Pre-computed multiplicity array for X_base. Computed internally if not provided. None
d_base np.ndarray Pre-computed unique-distance array for X_base. Computed internally if not provided. None
q float Exponent for the corrected Morris-Mitchell criterion. Defaults to 2. 2
p float Distance norm (p=1 Manhattan, p=2 Euclidean). Defaults to 2. 2
normalize_flag bool If True, normalizes X_base and x to [0, 1] before computing distances. Defaults to False. False
verbose bool If True, prints the base criterion, new criterion, and improvement. Defaults to False. False
exponential bool If True, returns :math:\exp(\hat{\Phi}_{\text{base}} - \hat{\Phi}_{\text{new}}). If False, returns the raw difference. Defaults to True. True

Returns

Name Type Description
float float The corrected Morris-Mitchell improvement score.

Examples

>>> import numpy as np
>>> from spotoptim.sampling.mm import mm_corrected_improvement
>>> X_base = np.array([[0.1, 0.2], [0.4, 0.5], [0.7, 0.8]])
>>> x = np.array([0.0, 1.0])
>>> score = mm_corrected_improvement(x, X_base, q=2, p=2)
>>> print(score)