spotoptim 1.0.2__tar.gz → 2.0.0__tar.gz

{spotoptim-1.0.2 → spotoptim-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: spotoptim
-Version: 1.0.2
+Version: 2.0.0
 Summary: Sequential Parameter Optimization Toolbox
 Author: bartzbeielstein
 Author-email: bartzbeielstein <32470350+bartzbeielstein@users.noreply.github.com>

{spotoptim-1.0.2 → spotoptim-2.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spotoptim"
-version = "1.0.2"
+version = "2.0.0"
 description = "Sequential Parameter Optimization Toolbox"
 readme = "README.md"
 license = { text = "AGPL-3.0-or-later" }
@@ -104,7 +104,7 @@ filterwarnings = [
 ]
 
 [build-system]
-requires = ["uv_build>=0.9.18,<1"]
+requires = ["uv_build>=0.9.18"]
 build-backend = "uv_build"
 
 [tool.uv]

{spotoptim-1.0.2 → spotoptim-2.0.0}/src/spotoptim/SpotOptim.py

@@ -29,6 +29,7 @@ from spotoptim.utils import dimreduction as _dimred
 from spotoptim.optimizer import acquisition as _acq
 from spotoptim.core import storage as _storage
 from spotoptim.optimizer.wrapper import gpr_minimize_wrapper
+from spotoptim.surrogate import Kriging
 
 
 @dataclass
@@ -58,7 +59,14 @@ class SpotOptimConfig:
         verbose (bool): Whether to print verbose output.
         warnings_filter (Literal["default", "error", "ignore"]): Filter for warnings.
         n_infill_points (int): Number of infill points.
-        max_surrogate_points (Optional[Union[int, List[int]]]): Maximum number of surrogate points. Defaults to 30.
+        max_surrogate_points (Optional[Union[int, List[int]]]): Maximum number of
+            points used to fit the surrogate. Defaults to ``300`` -- large enough
+            that typical Bayesian-optimization budgets (a few hundred evaluations)
+            are fit on all points (full surrogate quality), while bounding the
+            O(n^3) GP-fit cost on very long runs. Once the evaluation count exceeds
+            the cap the training set is subsampled via ``selection_method``. Pass
+            ``None`` to always fit on all points, or a smaller int to bound cost
+            further.
         selection_method (str): Method for selecting infill points.
         acquisition_failure_strategy (str): Strategy for handling acquisition function failures.
         penalty (bool): Whether to use penalty.
@@ -81,6 +89,10 @@ class SpotOptimConfig:
         acquisition_optimizer_kwargs (Optional[Dict[str, Any]]): Keyword arguments for the acquisition function optimizer.
         args (Tuple): Arguments for the objective function.
         kwargs (Optional[Dict[str, Any]]): Keyword arguments for the objective function.
+        metric_factorial (str): Distance metric used by a factor-aware Kriging surrogate for
+            nominal (categorical) variables.  ``"hamming"`` (default) treats all distinct
+            factor levels as equidistant, which is correct for unordered factors.
+            Any scipy pairwise distance metric string is accepted.
 
 
     Examples:
@@ -116,7 +128,7 @@ class SpotOptimConfig:
              verbose=False,
              warnings_filter="ignore",
              n_infill_points=1,
-             max_surrogate_points=30,
+             max_surrogate_points=300,
              selection_method="distant",
              acquisition_failure_strategy="random",
              penalty=False,
@@ -161,7 +173,7 @@ class SpotOptimConfig:
     verbose: bool = False
     warnings_filter: Literal["default", "error", "ignore"] = "ignore"
     n_infill_points: int = 1
-    max_surrogate_points: Optional[Union[int, List[int]]] = 30
+    max_surrogate_points: Optional[Union[int, List[int]]] = 300
     selection_method: str = "distant"
     acquisition_failure_strategy: str = "random"
     penalty: bool = False
@@ -181,6 +193,7 @@ class SpotOptimConfig:
     acquisition_optimizer_kwargs: Optional[Dict[str, Any]] = None
     args: Tuple = ()
     kwargs: Optional[Dict[str, Any]] = None
+    metric_factorial: str = "hamming"
 
     def __post_init__(self):
         if self.kwargs is None:
@@ -351,7 +364,8 @@ class SpotOptim(BaseEstimator):
         max_surrogate_points (int, optional):
             Maximum number of points to use for surrogate model fitting.
             If None, all points are used. If the number of evaluated points exceeds this limit,
-            a subset is selected using the selection method. Defaults to 30.
+            a subset is selected using the selection method. Defaults to 300 (covers
+            typical budgets at full quality while bounding GP-fit cost; pass None for all points).
         selection_method (str, optional):
             Method for selecting points when max_surrogate_points is exceeded.
             Options: 'distant' (Select points that are distant from each other via K-means clustering) or
@@ -428,6 +442,13 @@ class SpotOptim(BaseEstimator):
                 * "cosine": Cosine distance.
                 * "correlation": Correlation distance.
                 * "canberra", "braycurtis", "sqeuclidean", etc.
+        metric_factorial (str, optional):
+            Distance metric used for nominal (factor) variables by a factor-aware
+            Kriging surrogate. ``"hamming"`` (default) treats all distinct factor
+            levels as equidistant, which is correct for unordered factors; any
+            scipy pairwise distance metric string is accepted. Only takes effect
+            when factor variables are present and ``surrogate`` is left as ``None``
+            (an order-agnostic Kriging is then built automatically).
 
     Attributes:
         X_ (ndarray): All evaluated points, shape (n_samples, n_features).
@@ -733,7 +754,7 @@ class SpotOptim(BaseEstimator):
         verbose: bool = False,
         warnings_filter: Literal["default", "error", "ignore"] = "ignore",
         n_infill_points: int = 1,
-        max_surrogate_points: Optional[Union[int, List[int]]] = 30,
+        max_surrogate_points: Optional[Union[int, List[int]]] = 300,
         selection_method: str = "distant",
         acquisition_failure_strategy: str = "random",
         penalty: bool = False,
@@ -753,6 +774,7 @@ class SpotOptim(BaseEstimator):
         acquisition_optimizer_kwargs: Optional[Dict[str, Any]] = None,
         args: Tuple = (),
         kwargs: Optional[Dict[str, Any]] = None,
+        metric_factorial: str = "hamming",
     ):
         warnings.filterwarnings(warnings_filter)
 
@@ -831,6 +853,7 @@ class SpotOptim(BaseEstimator):
             acquisition_optimizer_kwargs=acquisition_optimizer_kwargs,
             args=args,
             kwargs=kwargs,
+            metric_factorial=metric_factorial,
         )
 
         # Initialize State
@@ -900,6 +923,8 @@ class SpotOptim(BaseEstimator):
 
         # Initialize surrogate model(s)
         self.init_surrogate()
+        # Warn if factor variables are being modelled with a factor-blind surrogate
+        self._validate_factor_surrogate_compat()
 
         # Design generator (from scipy.stats.qmc)
         self.lhs_sampler = LatinHypercube(d=self.n_dim, rng=self.seed)
@@ -1637,24 +1662,89 @@ class SpotOptim(BaseEstimator):
             self._max_surrogate_points_list = None
             self._active_max_surrogate_points = self.config.max_surrogate_points
 
-            kernel = ConstantKernel(1.0, (1e-2, 1e12)) * Matern(
-                length_scale=1.0, length_scale_bounds=(1e-4, 1e2), nu=2.5
-            )
+            if self._factor_maps:
+                # Factor variables are present: use a nominal (order-agnostic) Kriging
+                # surrogate so the kernel treats factor levels as equidistant.
+                # var_type is already the reduced var_type (after setup_dimension_reduction).
+                self.surrogate = Kriging(
+                    var_type=list(self.var_type),
+                    metric_factorial=self.config.metric_factorial,
+                    seed=self.seed if self.seed is not None else 124,
+                )
+            else:
+                # No factor variables: use the standard GaussianProcessRegressor.
+                kernel = ConstantKernel(1.0, (1e-2, 1e12)) * Matern(
+                    length_scale=1.0, length_scale_bounds=(1e-4, 1e2), nu=2.5
+                )
 
-            # Determine optimizer for GPR
-            optimizer = "fmin_l_bfgs_b"  # Default used by sklearn
-            if self.config.acquisition_optimizer_kwargs is not None:
-                optimizer = partial(
-                    gpr_minimize_wrapper, **self.config.acquisition_optimizer_kwargs
+                # Determine optimizer for GPR
+                optimizer = "fmin_l_bfgs_b"  # Default used by sklearn
+                if self.config.acquisition_optimizer_kwargs is not None:
+                    optimizer = partial(
+                        gpr_minimize_wrapper, **self.config.acquisition_optimizer_kwargs
+                    )
+
+                self.surrogate = GaussianProcessRegressor(
+                    kernel=kernel,
+                    n_restarts_optimizer=100,
+                    normalize_y=True,
+                    random_state=self.seed,
+                    optimizer=optimizer,
                 )
 
-            self.surrogate = GaussianProcessRegressor(
-                kernel=kernel,
-                n_restarts_optimizer=100,
-                normalize_y=True,
-                random_state=self.seed,
-                optimizer=optimizer,
-            )
+    def _validate_factor_surrogate_compat(self) -> None:
+        """Warn when factor variables are present but the surrogate is factor-blind.
+
+        Called once after ``init_surrogate`` — at that point ``self._factor_maps``
+        is fully populated and the surrogate is set.  Fires only when there is at
+        least one factor dimension.  Issues a ``UserWarning`` (not an exception) so
+        that users can still proceed but are informed of the mismatch.
+
+        Warns in two situations:
+
+        * The surrogate is not a :class:`~spotoptim.surrogate.Kriging` at all
+          (e.g. sklearn GPR, ``SimpleKriging``, ``RandomForestRegressor``).  Such
+          surrogates treat factor integer codes as ordinal numbers, which is
+          incorrect for unordered categorical variables.
+
+        * The surrogate IS a :class:`~spotoptim.surrogate.Kriging` but its
+          ``metric_factorial`` is ``"canberra"``, which is order-dependent and
+          singles out level index 0.
+
+        Returns:
+            None
+        """
+        if not self._factor_maps:
+            return  # No factor variables → nothing to validate
+
+        # Use a nested catch_warnings context to ensure this one-time configuration
+        # warning is always visible to the caller, even when the SpotOptim instance
+        # was created with warnings_filter="ignore" (the default).  Users who want to
+        # silence it permanently can use warnings.filterwarnings("ignore", ...) before
+        # calling SpotOptim.
+        with warnings.catch_warnings():
+            warnings.simplefilter("always")
+            if not isinstance(self.surrogate, Kriging):
+                warnings.warn(
+                    f"Factor variables detected (original bounds dimensions: "
+                    f"{sorted(self._factor_maps.keys())}) "
+                    f"but the active surrogate ({type(self.surrogate).__name__}) does not "
+                    f"support nominal (order-agnostic) factor metrics. Factor integer codes "
+                    f"will be treated as ordinal numbers, which may mislead the surrogate. "
+                    f"Consider using a factor-aware Kriging surrogate: "
+                    f"Kriging(metric_factorial='hamming').",
+                    UserWarning,
+                    stacklevel=3,
+                )
+            elif self.surrogate.metric_factorial == "canberra":
+                warnings.warn(
+                    "Factor variables detected but the Kriging surrogate uses "
+                    "metric_factorial='canberra', which is order-dependent and singles "
+                    "out factor level index 0. Use metric_factorial='hamming' for "
+                    "unordered (nominal) factor variables.",
+                    UserWarning,
+                    stacklevel=3,
+                )
 
     def get_initial_design(self, X0: Optional[np.ndarray] = None) -> np.ndarray:
         """Generate or process initial design points. Ensures that design points are in
@@ -2046,6 +2136,18 @@ class SpotOptim(BaseEstimator):
                 )
             X_fit, y_fit = self.fit_selection_dispatcher(X, y)
 
+        # B3: Propagate the reduced var_type to the surrogate before fitting.
+        # This activates the factor kernel mask on a user-provided Kriging whose
+        # var_type is still at its constructor default (None → ["float"]).
+        # self.var_type is already the reduced var_type here (dimension reduction
+        # runs in setup_dimension_reduction before fitting, and the fit selection
+        # only drops rows). The length guard is a defensive check against an
+        # externally-supplied X whose column count does not match the active space.
+        if hasattr(self.surrogate, "var_type") and len(self.var_type) == X_fit.shape[1]:
+            surrogate_vt = getattr(self.surrogate, "var_type", None)
+            if surrogate_vt is None or surrogate_vt == ["float"]:
+                self.surrogate.var_type = list(self.var_type)
+
         self.surrogate.fit(X_fit, y_fit)
 
     def fit_scheduler(self) -> None:

{spotoptim-1.0.2 → spotoptim-2.0.0}/src/spotoptim/function/__init__.py

@@ -16,6 +16,8 @@ from .so import (
     lennard_jones,
     robot_arm_obstacle,
     wingwt,
+    factor_quadratic,
+    FACTOR_QUADRATIC_LEVELS,
 )
 from .mo import (
     activity_pred,
@@ -46,6 +48,8 @@ __all__ = [
     "lennard_jones",
     "robot_arm_obstacle",
     "wingwt",
+    "factor_quadratic",
+    "FACTOR_QUADRATIC_LEVELS",
     "mo_conv2_min",
     "fonseca_fleming",
     "kursawe",

{spotoptim-1.0.2 → spotoptim-2.0.0}/src/spotoptim/function/so.py

@@ -8,6 +8,8 @@ Analytical single-objective test functions for optimization benchmarking.
 This module provides well-known analytical test functions commonly used for evaluating and benchmarking optimization algorithms.
 """
 
+from functools import lru_cache
+
 import numpy as np
 
 
@@ -623,6 +625,106 @@ def robot_arm_obstacle(X: np.ndarray) -> np.ndarray:
     return dist_sq + penalty
 
 
+#: Default factor levels for :func:`factor_quadratic` — 16 unordered nominal levels.
+FACTOR_QUADRATIC_LEVELS = tuple(f"c{i:02d}" for i in range(16))
+
+
+@lru_cache(maxsize=None)
+def _factor_quadratic_offsets(n_levels: int) -> np.ndarray:
+    """Fixed, index-scrambled per-level offsets in ``[0, 1]``.
+
+    Built from a deterministic permutation (fixed seed) so that adjacency in the
+    integer level index carries *no* information about the objective value — the
+    defining property that makes an ordinal/continuous encoding of the factor
+    misleading.  Deterministic across calls and processes; the result is cached
+    and returned read-only (callers must not mutate it).
+
+    Args:
+        n_levels (int): Number of factor levels.
+
+    Returns:
+        np.ndarray: Offsets of shape ``(n_levels,)``; exactly one entry is ``0.0``
+        (the optimal level) and one is ``1.0`` (the worst).
+    """
+    perm = np.random.default_rng(0).permutation(n_levels)
+    offsets = perm.astype(float) / (n_levels - 1)
+    offsets.setflags(write=False)  # cached array — prevent accidental mutation
+    return offsets
+
+
+def factor_quadratic(X, levels=FACTOR_QUADRATIC_LEVELS, amp: float = 8.0) -> np.ndarray:
+    """Mixed continuous + nominal-factor benchmark with index-scrambled level structure.
+
+    A deliberately adversarial test function with 1 continuous dimension and 1
+    *nominal* (unordered) factor with many levels (16 by default).  The continuous
+    part is a simple bowl shared by all levels; each level adds a vertical offset
+    drawn from a fixed index-scrambled permutation, so that **adjacency in the
+    integer level index carries no information about the objective value**.
+
+    A surrogate that treats the factor as an ordinal/continuous integer (Euclidean
+    or Canberra distance on the codes) wrongly assumes neighbouring indices behave
+    similarly and is systematically misled — most strongly in the data-sparse
+    regime typical of expensive black-box optimization, where most levels are
+    observed only a few times.  A nominal (Hamming) kernel treats all distinct
+    levels as equidistant and learns each level's contribution independently, so it
+    builds a more accurate surrogate from the same budget.
+
+    Mathematical definition (with ``n = len(levels)``)::
+
+        offset = perm / (n - 1)          # perm = fixed permutation of {0, .., n-1}
+        f(x, c) = x**2 + amp * offset[idx(c)]
+
+    where ``idx`` maps a factor label to its integer index.
+
+    Args:
+        X (array-like): Input array of shape ``(n_samples, 2)`` or ``(2,)``.
+            Column 0 is the continuous variable ``x ∈ [-3, 3]``.
+            Column 1 is the factor column, accepted as either string labels (the
+            entries of ``levels``) or numeric indices ``0 .. n-1`` — enabling both
+            standalone unit testing and direct use by SpotOptim (which passes the
+            factor column as string labels).
+        levels (tuple of str, optional): Ordered sequence of factor labels. Its
+            length sets the number of levels. Defaults to
+            :data:`FACTOR_QUADRATIC_LEVELS` (16 levels ``"c00" .. "c15"``).
+        amp (float, optional): Scale of the per-level offset term. Defaults to ``8.0``.
+
+    Returns:
+        np.ndarray: Function values of shape ``(n_samples,)`` with dtype ``float``.
+
+    Note:
+        **Global optimum** (default 16 levels): ``f(x=0, c="c04") = 0.0``. The
+        optimal level is the index where the scrambled offset is ``0``.
+
+        **Why ordinal encoding fails**: with the default levels the optimum
+        (index 4) is flanked in index space by a *bad* level (index 3, offset
+        ``≈0.67``).  An ordinal kernel interpolates between adjacent indices and
+        therefore under-ranks the optimal level; a Hamming kernel does not.  The
+        benefit of the nominal kernel is largest when the number of levels is large
+        relative to the evaluation budget — see ``scripts/factor_kernel_benchmark.py``.
+
+    Examples:
+        ```{python}
+        import numpy as np
+        from spotoptim.function import factor_quadratic
+        # global optimum: x=0 at level "c04"
+        print(factor_quadratic(np.array([[0.0, "c04"]], dtype=object)))
+        # a different level is worse
+        print(factor_quadratic(np.array([[0.0, "c15"]], dtype=object)))
+        ```
+
+    """
+    X = np.atleast_2d(X)
+    x = X[:, 0].astype(float)  # continuous column
+    col = X[:, 1]  # factor column: string labels or numeric indices
+    lut = {lab: i for i, lab in enumerate(levels)}
+    idx = np.array(
+        [lut[v] if isinstance(v, str) else int(round(float(v))) for v in col],
+        dtype=int,
+    )
+    offset = _factor_quadratic_offsets(len(levels))
+    return x**2 + amp * offset[idx]
+
+
 def robot_arm_hard(X: np.ndarray) -> np.ndarray:
     """10-Link Robot Arm with Maze-Like Hard Constraints.
 

{spotoptim-1.0.2 → spotoptim-2.0.0}/src/spotoptim/surrogate/kernels.py

@@ -68,7 +68,7 @@ class SpotOptimKernel(Kernel):
 
     where:
     D_ordered = sum_j theta_j * |x_ij - y_lj|^p  (for ordered variables)
-    D_factor  = sum_j theta_j * d(x_ij, y_lj)    (for factor variables, d is metric like Canberra)
+    D_factor  = sum_j theta_j * d(x_ij, y_lj)    (for factor variables, d is metric like Hamming)
 
     Args:
         theta (np.ndarray): The correlation parameters (weights).
@@ -77,7 +77,9 @@ class SpotOptimKernel(Kernel):
         var_type (list of str): List of variable types, e.g. ['float', 'int', 'factor'].
         p_val (float, optional): Power parameter for ordered distance. Defaults to 2.0.
         metric_factorial (str, optional): Metric for factor distance (passed to cdist/pdist).
-            Defaults to 'canberra'.
+            Defaults to 'hamming'. Hamming is a true nominal (order-agnostic) metric;
+            canberra distance on integer level indices is order-dependent and singles out
+            index 0. Any scipy distance metric remains selectable via this kwarg.
     """
 
     def __init__(
@@ -85,7 +87,7 @@ class SpotOptimKernel(Kernel):
         theta,
         var_type,
         p_val=2.0,
-        metric_factorial="canberra",
+        metric_factorial="hamming",
     ):
         self.theta = np.asanyarray(theta)
         self.var_type = var_type

{spotoptim-1.0.2 → spotoptim-2.0.0}/src/spotoptim/surrogate/kriging.py

@@ -78,7 +78,9 @@ class Kriging(BaseEstimator, RegressorMixin):
         min_Lambda (float, optional): Minimum log10(Lambda) bound. Defaults to -9.0.
         max_Lambda (float, optional): Maximum log10(Lambda) bound. Defaults to 0.0.
         metric_factorial (str, optional): Distance metric for factor variables.
-            Defaults to "canberra".
+            Defaults to ``"hamming"``. Hamming is a true nominal (order-agnostic) metric;
+            canberra distance on integer level indices is order-dependent and singles out
+            index 0. Any scipy distance metric remains selectable via this kwarg.
         isotropic (bool, optional): Use single theta for all dimensions. Defaults to False.
         theta (np.ndarray, optional): Initial theta values (log10 scale). Defaults to None.
 
@@ -163,7 +165,7 @@ class Kriging(BaseEstimator, RegressorMixin):
         optim_p: bool = False,
         min_Lambda: float = -9.0,
         max_Lambda: float = 0.0,
-        metric_factorial: str = "canberra",
+        metric_factorial: str = "hamming",
         isotropic: bool = False,
         theta: Optional[np.ndarray] = None,
         **kwargs,