strategies.OptunaStrategy

strategies.OptunaStrategy(
    n_trials=100,
    direction='minimize',
    sampler='tpe',
    objective=None,
    _objective_fn=None,
)

Bayesian optimization using Optuna.

Uses Optuna’s intelligent sampling to efficiently explore the parameter space, learning from previous results to focus on promising regions.

This is an adaptive strategy - it requires incremental execution where each trial’s results inform the next suggestion. Use run_adaptive_sweep() instead of the standard expand() method, or use SweepManager which handles this automatically.

Attributes

Name	Type	Description
n_trials	int	Maximum number of trials to run.
direction	str	Optimization direction (“minimize” or “maximize”).
sampler	str	Sampling algorithm (“tpe”, “gp”, “cmaes”, “random”).
objective	ObjectiveFn | str | None	Objective function (callable or “module:function” path).

Examples

>>> # Define objective function
>>> def stability_metric(registry, run_hash, job):
...     df = queries.get_timeseries("population", run_hash=run_hash)
...     return df["value"].std() / df["value"].mean()  # CV

>>> strategy = OptunaStrategy(
...     n_trials=50,
...     direction="minimize",
...     objective=stability_metric,
... )

>>> # Or specify via YAML path
>>> strategy = OptunaStrategy(
...     n_trials=50,
...     direction="minimize",
...     objective="my_project.objectives:stability_metric",
... )

Methods

Name	Description
create_study	Create an Optuna study with configured sampler.
expand	Not supported for adaptive strategies, because, during a given run,
from_dict	Create from dict (YAML/JSON deserialization).
get_objective	Get the resolved objective function.
to_dict	Convert to dict for serialization.

create_study

strategies.OptunaStrategy.create_study()

Create an Optuna study with configured sampler.

Returns

Name	Type	Description
	Any	optuna.Study configured with this strategy’s settings.

Raises

Name	Type	Description
	ImportError	If optuna is not installed.

expand

strategies.OptunaStrategy.expand(
    config_params,
    file_params,
    compound_params=None,
)

Not supported for adaptive strategies, because, during a given run, the next parameters depend on the results of previous runs.

Raises

Name	Type	Description
	RuntimeError	Always - use run_adaptive_sweep() instead.

from_dict

strategies.OptunaStrategy.from_dict(data)

Create from dict (YAML/JSON deserialization).

get_objective

strategies.OptunaStrategy.get_objective()

Get the resolved objective function.

Resolves string path objectives on first call (lazy loading).

Returns

Name	Type	Description
	ObjectiveFn	The objective function callable.

Raises

Name	Type	Description
	ValueError	If no objective function is configured.
	ImportError	If string path references non-existent module.

to_dict

strategies.OptunaStrategy.to_dict()

Convert to dict for serialization.

Note: Callable objectives cannot be serialized - only string paths.