cotengra.hyperoptimizers.hyper_sbplx

Hyper optimization using the Sbplx method (Rowan, 1990).

Attributes

_SBPLX_OMEGA

Classes

HyperSbplxSampler	Sbplx optimizer in raw [-1, 1] parameter space.
SbplxOptLib	Hyper-optimization backend using the 'Sbplx' method adapted from the

Module Contents

cotengra.hyperoptimizers.hyper_sbplx._SBPLX_OMEGA = 0.1

class cotengra.hyperoptimizers.hyper_sbplx.HyperSbplxSampler(space, seed=None, adaptive=False, alpha=1.0, gamma=2.0, rho=0.5, sigma=0.5, initial_scale=0.6, nsmin=2, nsmax=5, partition='greedy', psi=0.25, convergence_tol=0.01, filler_scale=0.3, n_initial=None, restart_patience='auto', explore_prob=0.05, inject_diameter_fraction=1.5, inject_restart_fraction=0.5, exponential_param_power=None)

Sbplx optimizer in raw [-1, 1] parameter space.

This is derived from Subplex (Rowan, 1990) which decomposes the full parameter space into low-dimensional subspaces (i.e. subsets of parameters) and runs Nelder-Mead (NM) on each in sequence. After all subspaces in a cycle are optimized, the overall convergence is checked; if the total displacement is negligible the search restarts with a jittered center. This is generally more robust that vanilla Nelder-Mead especially in higher dimensions.

Parameters:

• space (dict[str, dict]) – The search space for a single contraction method.

• seed (None or int, optional) – Random seed.

• adaptive (bool, optional) – Whether to use the adaptive NM coefficients recommended by Gao and Han (2010), which scale with problem dimension. If True then alpha, gamma, rho, and sigma are ignored.

• alpha (float, optional) – Reflection coefficient for each sub-NM.

• gamma (float, optional) – Expansion coefficient for each sub-NM.

• rho (float, optional) – Contraction coefficient for each sub-NM.

• sigma (float, optional) – Shrink coefficient for each sub-NM.

• initial_scale (float, optional) – Initial step size in each dimension.

• nsmin (int or None, optional) – Minimum subspace size. Defaults to min(2, ndim).

• nsmax (int or None, optional) – Maximum subspace size. Defaults to min(5, ndim).

• psi (float, optional) – Step reduction factor applied when a subspace shows no movement, and used to scale the jitter on restart.

• partition (str, optional) – Subspace partitioning strategy. "greedy" takes equal chunks of up to nsmax dimensions, shrinking only to avoid a remainder smaller than nsmin. "goodness" uses Rowan’s heuristic, favoring splits where average step magnitude drops sharply. Default "greedy".

• convergence_tol (float, optional) – Relative convergence threshold for the overall cycle check. It is also passed as the absolute simplex diameter fallback for the inner Nelder-Mead cores.

• filler_scale (float, optional) – Standard deviation of the gaussian noise used for filler points issued while the sub-NM is blocked.

• n_initial (int or None, optional) – Number of Latin Hypercube Sampled (LHS) warm-up points to evaluate before starting subplex cycling. The best result seeds the starting point. Default None means 2 * ndim. Set to 0 to disable.

• restart_patience (int or "auto", optional) – Number of completed cycles without a new best score before triggering a restart. When "auto" it is chosen from the number of expected subspaces, with a minimum of 3.

• explore_prob (float, optional) – Probability of issuing a uniform random point instead of the NM-directed point during normal cycling. Maintains diversity throughout the search.

• inject_diameter_fraction (float, optional) – Passed to each sub-_NMCore — controls the maximum allowed simplex diameter inflation when injecting an external vertex.

• exponential_param_power (float, optional) – Passed through to the shared parameter mapping.

rng

params = []

ndim

adaptive = False

alpha = 1.0

gamma = 2.0

rho = 0.5

sigma = 0.5

initial_scale = 0.6

psi = 0.25

convergence_tol = 0.01

filler_scale = 0.3

explore_prob = 0.05

inject_diameter_fraction = 1.5

inject_restart_fraction = 0.5

nsmin

nsmax

partition = 'greedy'

n_initial = None

restart_patience = 'auto'

_trial_counter = 0

_best_x = None

_best_score

_trial_map

_x

_step

_cycles_since_improvement = 0

_restart_count = 0

_stagnant_restart_count = 0

_subspaces = None

_sub_idx = 0

_sub_dims = None

_sub_nm = None

_sub_nm_id = None

_next_sub_nm_id = 0

_x_at_cycle_start = None

_step_at_cycle_start = None

_best_score_at_cycle_start

_partition_dims()

Partition dimensions into subspaces.

Dimensions are first sorted by abs(step[d]) descending. The partition strategy is selected by self.partition:

• "greedy": equal chunks of up to nsmax, shrinking only to avoid a remainder smaller than nsmin.

• "goodness": Rowan’s heuristic, favoring splits where the average step magnitude drops sharply.

_partition_greedy(order)

Equal-chunk partitioning.

_partition_goodness(order, magnitudes)

Rowan’s goodness heuristic partitioning.

_clamp_scale_factor(factor)

_start_cycle()

Snapshot the current point and begin a new cycle.

_start_sub_nm()

Create a _NMCore for the current subspace.

_cycle_converged()

_embed_sub_vector(sub_x)

Embed a subspace vector into a full-dimensional point, keeping non-subspace dimensions at their current values in _x.

_ask_filler()

_rescale_step(step, factor, minimum=0.0)

_reset_cycle_state()

_restart(mode)

Restart the search either locally around the best point or by re-expanding globally.

Parameters:

mode ({"local", "global"}) – Restart mode. Local restarts jitter near the best known point while preserving step geometry. Global restarts jump to a random point and reset step sizes to initial_scale.

ask()

Return the next candidate setting. During the LHS warm-up phase, pre-generated Latin Hypercube points are issued one at a time. Once all warm-up results have been collected, normal subplex cycling begins from the best warm-up point. During cycling, with probability explore_prob a uniform random point is returned to maintain diversity. If the active sub-NM is blocked waiting for results, a filler point is returned instead.

tell(trial_number, score)

Record a completed trial result.

_finish_subspace()

Extract the sub-NM result, update the full point and step vector, then advance to the next subspace or finish the cycle.

_update_steps_after_cycle()

_finish_cycle()

Check overall convergence across all subspaces.

Following the NLopt Sbplx logic, convergence is based on a relative per-dimension test using both the cycle displacement and the current step size. Repeated non-improving cycles still trigger restarts to preserve the asynchrcoonous wrapper behavior.

class cotengra.hyperoptimizers.hyper_sbplx.SbplxOptLib

Bases: cotengra.hyperoptimizers.hyper.HyperOptLib

Hyper-optimization backend using the ‘Sbplx’ method adapted from the Subplex method (Rowan, 1990).

setup(methods, space, optimizer=None, adaptive=False, alpha=1.0, gamma=2.0, rho=0.5, sigma=0.5, initial_scale=0.6, nsmin=2, nsmax=5, partition='greedy', psi=0.25, convergence_tol=0.01, filler_scale=0.3, n_initial=None, restart_patience='auto', explore_prob=0.05, inject_diameter_fraction=1.5, inject_restart_fraction=0.5, method_exploration=1.0, method_temperature=1.0, exponential_param_power=None, seed=None, **kwargs)

Initialize Sbplx optimizers for each method.

Parameters:

• methods (list[str]) – The contraction methods to optimize over.

• space (dict[str, dict[str, dict]]) – The per-method hyperparameter search space.

• optimizer (HyperOptimizer, optional) – The parent optimizer.

• adaptive (bool, optional) – Whether to use the adaptive NM coefficients recommended by Gao and Han (2010), which scale with problem dimension. If True then alpha, gamma, rho, and sigma are ignored.

• alpha (float, optional) – Reflection coefficient for each sub-NM.

• gamma (float, optional) – Expansion coefficient for each sub-NM.

• rho (float, optional) – Contraction coefficient for each sub-NM.

• sigma (float, optional) – Shrink coefficient for each sub-NM.

• initial_scale (float, optional) – Scale of the initial simplex.

• nsmin (int or None, optional) – Minimum subspace size.

• nsmax (int or None, optional) – Maximum subspace size.

• partition (str, optional) – Subspace partitioning strategy. "greedy" or "goodness". Default "greedy".

• psi (float, optional) – Step reduction factor.

• convergence_tol (float, optional) – Convergence threshold for sub-NM and cycle check.

• filler_scale (float, optional) – Gaussian noise scale for filler points.

• n_initial (int or None, optional) – Number of LHS warm-up points per method. Default None means 2 * ndim. Set to 0 to disable.

• restart_patience (int or "auto", optional) – Number of completed non-improving cycles before restarting. When "auto" it is chosen from the expected number of subspaces, with a minimum of 3.

• explore_prob (float, optional) – Probability of issuing a uniform random exploration point during normal cycling.

• inject_diameter_fraction (float, optional) – Passed to each sub-_NMCore — controls the maximum allowed simplex diameter inflation when injecting an external vertex.

• inject_restart_fraction (float, optional) – Passed to each sub-_NMCore — controls th XXX

• method_exploration (float, optional) – Exploration strength for the LCB method chooser.

• method_temperature (float, optional) – Noise temperature for the LCB method chooser.

• exponential_param_power (float, optional) – Passed to the shared parameter mapping.

• seed (None or int, optional) – Random seed.

get_setting()

Choose a method, then request its next setting.

report_result(setting, trial, score)

Report a completed trial back to the method chooser and the per-method Sbplx sampler.