tauopt.engine.strategies.ucb_cl

GP-UCB with constant-liar fill – the fast, sturdy middle rung of the ladder.

The SigOpt-lineage role: when LogEI is too slow or too fragile for the moment, UCB on a conditioned model gives a good-enough exploratory point cheaply (“always have something ready”, computed on demand). Open suggestions and batch fill (n > 1) both enter as constant-liar conditioning on the once-fitted model – hyperparameters are never refit inside an ask (see _gp_common).

Scope note: ucb_cl models the OBJECTIVE only. Linear parameter constraints are enforced (they are validity), but outcome-constraint metrics are NOT modeled here – this is a fallback rung; feasibility of a black-box metric is unknowable pre- observation, so a feasibility-blind fallback point is honest, and the primary path (gp_ei/gp_nehvi) carries the constraint models. Multimetric states are refused (the ladder routes them to gp_nehvi -> sobol).

params: beta float, default 2.0 – exploration weight, finite, in [0, 1e6] timebox_s float, default 10.0, ceiling 300 timebox_mode “budget” (default) | “off” | “caps” – see gp_ei.py: “off” removes the wall budget entirely (no timeout machinery, TimeboxExceeded unreachable, clock reads cannot influence the suggestion); refuses combined with an explicit timebox_s. “caps” (TOP-LEVEL ONLY – the params form refuses with a pointer): off’s clock structure plus deterministic work ceilings; an ask-level max_wait_s is enforced by the ask boundary alone (AskDeadlineExceeded), never by injection. num_restarts int, default 4, in [1, 64] raw_samples int, default 64, in [restarts, 4096] fit_maxiter int, in [1, 10000] – caps-mode ONLY (set outside caps refuses): the GP fit’s L-BFGS iteration cap; unset => the version-pinned stratum default (the field ceiling until calibrated) acq_maxiter int, in [1, 10000] – caps-mode ONLY: per-fill acqf optimizer iteration cap (optimize_acqf options.maxiter); same defaults law

Module Contents

Classes

UcbClParams	ucb_cl’s resolved params for one cfg: what read_params returns and suggest executes.
UcbClStrategy	GP-UCB with constant-liar batch fill (the module docstring carries the role and params contract). The single-objective never-fail ladder’s middle rung, reached when gp_ei times out or fails (pin P6) or by explicit config; multimetric states are refused. Requires tauopt[botorch] (torch/botorch/gpytorch).

Data

DEFAULT_NUM_RESTARTS
DEFAULT_RAW_SAMPLES

API

tauopt.engine.strategies.ucb_cl.DEFAULT_NUM_RESTARTS

4

tauopt.engine.strategies.ucb_cl.DEFAULT_RAW_SAMPLES

64

class tauopt.engine.strategies.ucb_cl.UcbClParams

Bases: typing.NamedTuple

ucb_cl’s resolved params for one cfg: what read_params returns and suggest executes.

beta: float

None

box_mode: str

None

timebox_s: float

None

num_restarts: int

None

raw_samples: int

None

fit_cap: int | None

None

acq_cap: int | None

None

class tauopt.engine.strategies.ucb_cl.UcbClStrategy

GP-UCB with constant-liar batch fill (the module docstring carries the role and params contract). The single-objective never-fail ladder’s middle rung, reached when gp_ei times out or fails (pin P6) or by explicit config; multimetric states are refused. Requires tauopt[botorch] (torch/botorch/gpytorch).

name

‘ucb_cl’

requires: tuple[str, ...]

(‘botorch’,)

accepted_params: frozenset[str]

‘frozenset(…)’

read_params(state: tauopt.engine.state.ExperimentState, cfg: tauopt.engine.config.OptimizerConfig) → tauopt.engine.strategies.ucb_cl.UcbClParams

The ONE reading of cfg.params for this strategy (see gp_ei): the typed readers, their ranges, the timebox two-writer refusals, and the caps posture. The ask boundary runs it for the intended strategy before any rung and answers a ValueError raised here as the caller’s 400; suggest executes what it returns. Pure; no math imports. state is unused here (no space-dependent defaults) and kept for the one shared signature.

suggest(state: tauopt.engine.state.ExperimentState, cfg: tauopt.engine.config.OptimizerConfig, n: int = 1) → list[tauopt.engine.strategies.base.SuggestionDraft]

Fit the objective GP once on aggregated scored observations, enter open suggestions as pessimistic constant-liar conditioning on the once-fitted model, then fill the n slots one UpperConfidenceBound optimization at a time, conditioning each filled slot’s lie before the next. Returns the n decoded drafts. Pure in (state, cfg) (pin P4): explicit derived seeds under torch fork_rng, single-thread compute. Raises ValueError on a multimetric state or zero scored observations, and TimeboxExceeded on wall overrun; the ask boundary catches both and descends the ladder (pin P6). Bad config never reaches here for the intended strategy: read_params refused it at the boundary first.

suggest_unique(state: tauopt.engine.state.ExperimentState, cfg: tauopt.engine.config.OptimizerConfig, n: int = 1, exclude: frozenset[str] = frozenset()) → list[tauopt.engine.strategies.base.SuggestionDraft]

Dedup repair path: per CL-fill slot, next eligible queue entry from that slot’s restart pool (zero extra optimizer work), then <= PER_SLOT_REOPT_ALLOWANCE bounded re-optimize attempts. The between-slot lie conditioning applies to the SELECTED (post-repair) row – its existing per-slot law.

suggest_selected(state: tauopt.engine.state.ExperimentState, cfg: tauopt.engine.config.OptimizerConfig, n: int = 1, exclude: frozenset[str] = frozenset(), select=None) → list[tauopt.engine.strategies.base.SuggestionDraft]

Queue-selection per-slot handshake: each CL-fill slot’s restart pool becomes its capped ranked queue; the boundary’s selector picks; slot k+1’s model conditions on the SELECTED point’s lie (the existing between-slot law applied to the selection result). No eligible entry => the dedup owner-repair path fills the slot (recorded, no draw).