saealib.Optimizer

class saealib.Optimizer(problem, seed=None)

Bases: object

Optimizer class for evolutionary algorithms.

Integrates problem definition, evolutionary algorithm, surrogate model, model manager, and termination condition, and manages the optimization process.

Parameters:

• problem (Problem)

• seed (int | None)

problem

The optimization problem.

Type:

Problem

algorithm

The evolutionary algorithm.

Type:

Algorithm

surrogate

The surrogate model.

Type:

Surrogate

strategy

The optimization strategy.

Type:

OptimizationStrategy

termination

The termination condition.

Type:

Termination

archive

The archive of evaluated solutions.

Type:

Archive

popsize

The population size.

Type:

int

seed

The master random seed. None means non-deterministic.

Type:

int or None

fe

The current number of function evaluations.

Type:

int

gen

The current generation number.

Type:

int

cbmanager

The callback event manager.

Type:

CallbackManager

instance_name

The name of the optimizer instance.

Type:

str

Methods

__init__	Initialize the Optimizer.
contract_diagnostics	Return diagnostics for the currently configured component graph.
describe	Describe the most recently compiled plan, if one exists.
dispatch	Dispatch an event to the callback manager.
from_problem_file	Build an Optimizer from a Python file defining a problem.
iterate	Iterate the optimization process.
iterate_from	Resume iteration from an existing context (e.g. loaded from checkpoint).
load_pickle	Load an optimizer and context from a pickle checkpoint.
resolve_defaults	Fill unset components with library defaults (Registry + presets file).
run	Run the optimization process.
run_from	Resume and run to completion from an existing context.
save_pickle	Save the optimizer and context together as a pickle checkpoint.
save_preset	Save the currently configured components as a reusable preset file.
set_acquisition	Set the independent acquisition component.
set_algorithm	Set the evolutionary algorithm.
set_async_evaluation_scheduler	Configure asynchronous evaluation for built-in strategies.
set_evaluation_planner	Set the evaluation planner.
set_evaluator	Set the evaluator.
set_feedback_builder	Set the feedback builder.
set_history	Set execution history channels and return self.
set_initializer	Set the initializer.
set_instance_name	Set the instance name.
set_preset	Set a user-defined preset.
set_seed	Set the master random seed.
set_strategy	Set the optimization strategy.
set_surrogate	Wrap a raw Surrogate in a LocalSurrogateManager.
set_surrogate_manager	Set the surrogate manager.
set_termination	Set the termination condition.
validate	Check configuration consistency.

Method Details

Optimizer.__init__(problem, seed=None)

Initialize the Optimizer.

Parameters:

• problem (Problem) – The optimization problem.

• seed (int or None, optional) – Master random seed propagated to the initializer. None (default) means non-deterministic.

Optimizer.contract_diagnostics()

Return diagnostics for the currently configured component graph.

Return type:

DiagnosticBag

Optimizer.describe()

Describe the most recently compiled plan, if one exists.

Return type:

str

Optimizer.dispatch(event)

Dispatch an event to the callback manager.

Parameters:

event (Event)

Return type:

None

classmethod Optimizer.from_problem_file(problem_path, preset=None)

Build an Optimizer from a Python file defining a problem.

The file at problem_path is executed as a standalone module (it is not registered in sys.modules) and must define a top-level problem variable holding a Problem instance. If preset is given, it is applied first via set_preset(); any of the top-level variables algorithm, strategy, surrogate_manager, termination defined in the file are then applied via the corresponding set_*() method, so the file can override individual components of the preset. A top-level seed variable, if present, is passed to the Optimizer constructor.

Parameters:

• problem_path (str or Path) – Path to a .py file defining a top-level problem variable.

• preset (str, Path, dict, or None, optional) – Preset applied before the file’s own component definitions, so that the file can override individual components. See set_preset().

Returns:

A configured, not-yet-run Optimizer instance. Call run() or iterate() on it.

Return type:

Optimizer

Raises:

• ValidationError – If the file does not define a top-level problem variable, or it is not a Problem instance. Also raised if a top-level algorithm, strategy, surrogate_manager, termination, or seed variable is defined but is not an instance of its expected type.

• FileNotFoundError – If problem_path does not exist.

Examples

>>> # problem.py:
>>> #     problem = Problem(func=..., dim=2, n_obj=1, direction=[-1])
>>> #     seed = 42
>>> opt = Optimizer.from_problem_file("problem.py", preset="preset.yaml")
>>> ctx = opt.run()

Optimizer.iterate(checkpoint_path=None, checkpoint_interval=1, checkpoint_format='npz', checkpoint_delete_on_success=False)

Iterate the optimization process.

Parameters:

• checkpoint_path (str, Path, or None, optional) – If provided, checkpoints are saved to this directory every checkpoint_interval generations.

• checkpoint_interval (int, optional) – Generations between checkpoints. Default: 1.

• checkpoint_format ({'npz', 'pickle', 'both'}, optional) – Checkpoint format. Default: 'npz'.

• checkpoint_delete_on_success (bool, optional) – Delete checkpoints on normal termination. Default: False.

Returns:

Generator of OptimizationState.

Return type:

Generator[OptimizationState]

Optimizer.iterate_from(ctx, checkpoint_path=None, checkpoint_interval=1, checkpoint_format='npz', checkpoint_delete_on_success=False)

Resume iteration from an existing context (e.g. loaded from checkpoint).

Does not call the initializer; all other components must be configured.

Parameters:

• ctx (OptimizationState) – Context to resume from.

• checkpoint_path (str, Path, or None, optional) – If provided, checkpoints are saved to this directory every checkpoint_interval generations.

• checkpoint_interval (int, optional) – Generations between checkpoints. Default: 1.

• checkpoint_format ({'npz', 'pickle', 'both'}, optional) – Checkpoint format. Default: 'npz'.

• checkpoint_delete_on_success (bool, optional) – Delete checkpoints on normal termination. Default: False.

Return type:

Generator[OptimizationState, None, None]

classmethod Optimizer.load_pickle(path)

Load an optimizer and context from a pickle checkpoint.

The returned context has resumed=True. Call run_from() or iterate_from() on the returned optimizer to continue the optimization.

Warning

Pickle files are tied to specific Python and library versions.

Parameters:

path (str or Path) – Path to the .pkl file. The extension is added if absent.

Return type:

tuple[Optimizer, OptimizationState]

Optimizer.resolve_defaults()

Fill unset components with library defaults (Registry + presets file).

Components already set via set_*() are never overwritten. Gaps are filled first from a user preset (set_preset()), if any, then from a bundled preset selected by (1) the algorithm’s registered name if algorithm is set, else (2) a Problem-shape rule, else (3) the universal fallback preset. initializer is computed from semantic defaults and is not part of any preset; termination falls back to the resolved maximum-evaluations default (200 * problem.dim unless a provider recommends another value) only if neither set_*() nor a preset supplies one.

Return type:

None

Optimizer.run(checkpoint_path=None, checkpoint_interval=1, checkpoint_format='npz', checkpoint_delete_on_success=False)

Run the optimization process.

Parameters:

• checkpoint_path (str, Path, or None, optional) – If provided, checkpoints are saved to this directory every checkpoint_interval generations.

• checkpoint_interval (int, optional) – Generations between checkpoints. Default: 1.

• checkpoint_format ({'npz', 'pickle', 'both'}, optional) – Checkpoint format. Default: 'npz'.

• checkpoint_delete_on_success (bool, optional) – Delete checkpoints on normal termination. Default: False.

Returns:

The optimization context.

Return type:

OptimizationState

Optimizer.run_from(ctx, checkpoint_path=None, checkpoint_interval=1, checkpoint_format='npz', checkpoint_delete_on_success=False)

Resume and run to completion from an existing context.

Parameters:

• ctx (OptimizationState) – Context to resume from.

• checkpoint_path (str, Path, or None, optional) – If provided, checkpoints are saved to this directory every checkpoint_interval generations.

• checkpoint_interval (int, optional) – Generations between checkpoints. Default: 1.

• checkpoint_format ({'npz', 'pickle', 'both'}, optional) – Checkpoint format. Default: 'npz'.

• checkpoint_delete_on_success (bool, optional) – Delete checkpoints on normal termination. Default: False.

Returns:

The final optimization context.

Return type:

OptimizationState

Optimizer.save_pickle(ctx, path)

Save the optimizer and context together as a pickle checkpoint.

This preserves fitted surrogate state and all component objects, offering complete reproducibility within the same environment.

Warning

Pickle files are tied to specific Python and library versions. Use OptimizationState.save() for a more portable format.

Parameters:

• ctx (OptimizationState) – Current optimization context.

• path (str or Path) – Destination file path. The .pkl extension is added if absent.

Return type:

None

Optimizer.save_preset(path)

Save the currently configured components as a reusable preset file.

Serializes algorithm, surrogate_manager, strategy, and termination (whichever are set via set_*()) into a preset dict and writes it as YAML. Problem-owned parameters (dim, direction) are stripped so the preset can be reused across problems of different dimensionality.

Parameters:

path (str or Path) – Destination file path. The .yaml extension is added if absent.

Returns:

The path the preset was written to.

Return type:

Path

Raises:

ValidationError – If no components are configured, or a configured component cannot be serialized (e.g. holds a raw lambda).

Optimizer.set_acquisition(acquisition)

Set the independent acquisition component.

Return type:

Self

Optimizer.set_algorithm(algorithm)

Set the evolutionary algorithm. Returns self.

Parameters:

algorithm (Algorithm)

Return type:

Self

Optimizer.set_async_evaluation_scheduler(scheduler)

Configure asynchronous evaluation for built-in strategies.

Parameters:

scheduler (AsyncEvaluationScheduler | None)

Return type:

Self

Optimizer.set_evaluation_planner(planner)

Set the evaluation planner.

Parameters:

planner (EvaluationPlanner)

Return type:

Self

Optimizer.set_evaluator(evaluator)

Set the evaluator. Returns self.

Parameters:

evaluator (Evaluator)

Return type:

Self

Optimizer.set_feedback_builder(builder)

Set the feedback builder.

Parameters:

builder (FeedbackBuilder)

Return type:

Self

Optimizer.set_history(channels)

Set execution history channels and return self.

On resume, the checkpoint’s channels take precedence unless this method was called; calling it with a different set fails validation. Assigning to history_channels directly does not count as calling it.

Parameters:

channels (Sequence[str])

Return type:

Self

Optimizer.set_initializer(initializer)

Set the initializer. Returns self.

Parameters:

initializer (Initializer)

Return type:

Self

Optimizer.set_instance_name(name)

Set the instance name. Returns self.

Parameters:

name (str)

Return type:

Self

Optimizer.set_preset(preset)

Set a user-defined preset. Returns self.

The preset fills components that are not already configured via set_*(); explicitly set components take precedence.

Parameters:

preset (str | Path | dict)

Return type:

Self

Optimizer.set_seed(seed)

Set the master random seed. Returns self.

Parameters:

seed (int | None)

Return type:

Self

Optimizer.set_strategy(strategy)

Set the optimization strategy. Returns self.

Parameters:

strategy (OptimizationStrategy)

Return type:

Self

Optimizer.set_surrogate(surrogate, n_neighbors=50)

Wrap a raw Surrogate in a LocalSurrogateManager. Returns self.

Equivalent to set_surrogate_manager(LocalSurrogateManager(surrogate, ...)).

Parameters:

• surrogate (Surrogate)

• n_neighbors (int)

Return type:

Self

Optimizer.set_surrogate_manager(manager)

Set the surrogate manager. Returns self.

Parameters:

manager (SurrogateManager)

Return type:

Self

Optimizer.set_termination(termination)

Set the termination condition. Returns self.

Parameters:

termination (Termination)

Return type:

Self

Optimizer.validate(*, require_initializer=True)

Check configuration consistency. Returns list of issues.

Call resolve_defaults() first when validation results should reflect the components that will be used for execution.

Parameters:

require_initializer (bool, optional) – When False, skip the initializer presence check. Use this when resuming from a checkpoint where initialization is not needed.

Return type:

list[str]