pdmlabs.optimization

PdMLabs optimizer abstraction layer.

Optimizer Registry

OPTIMIZER_REGISTRY is a plain dict mapping string identifiers to adapter classes. Adding a new backend requires only inserting a new entry.

Supported identifiers

"mango"

Built-in Mango Bayesian optimizer (Gaussian Process surrogate). Default.

"mango_random"

Mango in pure random-search mode (optimizer='Random' in conf_dict).

"smac"

SMAC3 HyperparameterOptimizationFacade. Requires pip install pdmlabs[smac].

"gpyopt"

GPyOpt BayesianOptimization. Requires pip install pdmlabs[gpyopt].

"hyperopt"

Hyperopt fmin with TPE (Tree-structured Parzen Estimator). Requires pip install pdmlabs[hyperopt]. Sequential only — emits UserWarning when n_jobs > 1.

"optuna"

Optuna 5 TPESampler with multivariate=True and constant_liar=True (both now the Optuna 5.0 defaults). Multi-process parallelism via joblib.Parallel + JournalStorage(JournalFileBackend). Requires pip install pdmlabs[optuna] (optuna>=5.0.0).

Functions

get_optimizer(name)

Instantiate and return the optimizer adapter for name.

class pdmlabs.optimization.BaseOptimizerAdapter

Bases: ABC

Abstract base for optimizer adapters.

Subclasses translate the PdMLabs native param space (dict of str -> list | rv_frozen) into their backend’s representation and expose a unified maximize / minimize API.

The raw objective function passed to adapters has the signature:

def optimization_objective(**params) -> float

Each adapter is responsible for wrapping it into whatever calling convention its backend requires (batch list, single config, etc.).

A single float is the whole contract: anything else a trial produces (its threshold, its fitted pipeline) travels back to the main process through pdmlabs.optimization.trial_sink.TrialSink, which the objective closure carries into the workers. Adapters neither see nor forward it, so they need no changes to support it.

abstract maximize(param_space: dict, objective_fn, n_iterations: int, n_jobs: int, initial_random: int, constraint_fn=None) → dict

Run optimization maximizing objective_fn over param_space.

Parameters:

• param_space – PdMLabs native space — str -> list or rv_frozen.

• objective_fn – Raw callable (**params) -> float (single config, single score). Adapters wrap this into whatever their backend expects.

• n_iterations – Number of optimizer iterations / trials.

• n_jobs – Degree of parallelism (adapter-specific meaning).

• initial_random – Number of random warm-up evaluations (Mango only; ignored by SMAC).

• constraint_fn – Optional constraint predicate on parameter dicts (Mango only).

Returns:

Keys: best_params (dict), best_objective (float), params_tried (list[dict]), objective_values (list[float]).

Return type:

dict

minimize(param_space: dict, objective_fn, n_iterations: int, n_jobs: int, initial_random: int, constraint_fn=None) → dict

Minimize by negating objective_fn and delegating to maximize.

supports_categorical: bool = True

pdmlabs.optimization.get_optimizer(name: str) → BaseOptimizerAdapter

Instantiate and return the optimizer adapter for name.

Parameters:

name – One of the keys in OPTIMIZER_REGISTRY.

Returns:

A fresh adapter instance ready to call maximize() or minimize().

Return type:

BaseOptimizerAdapter

Raises:

ValueError – If name is not a registered optimizer identifier.

Modules

base	Abstract base class for all PdMLabs optimizer adapters.
gpyopt_adapter	GPyOpt Bayesian Optimization adapter for PdMLabs.
hyperopt_adapter	Hyperopt TPE optimizer adapter for PdMLabs.
mango_adapter	Mango optimizer adapters for PdMLabs.
optuna_adapter	Optuna 5 TPE optimizer adapter for PdMLabs.
smac_adapter	SMAC3 optimizer adapter for PdMLabs.
trial_sink	Cross-process best-trial spool for PdMLabs experiments.