Optimizer

class Optimizer

Bases: ABC

Abstract base class for all optimizers.

Warning

Thread Safety: Optimizer instances are not thread-safe. They maintain internal state (e.g., current population, iteration count, RNG state) that changes during optimization.

Do not share a single Optimizer instance across multiple QuantumProgram instances or threads running in parallel. Doing so will lead to race conditions, corrupted state, and potential crashes.

If you need to use the same optimizer configuration for multiple programs, create a separate instance for each program. You can use the helper function copy_optimizer() to create a fresh copy with the same configuration.

Attributes Summary

n_param_sets

Returns the number of parameter sets the optimizer can handle per optimization run.

Methods Summary

get_config()	Get optimizer configuration for checkpoint reconstruction.
load_state(checkpoint_dir)	Load the optimizer's internal state from a checkpoint directory.
optimize(cost_fn[, initial_params, callback_fn])	Optimize the given cost function starting from initial parameters.
reset()	Reset the optimizer's internal state to allow fresh optimization runs.
save_state(checkpoint_dir)	Save the optimizer's internal state to a checkpoint directory.

Attributes Documentation

n_param_sets

Returns the number of parameter sets the optimizer can handle per optimization run. :returns: Number of parameter sets. :rtype: int

Methods Documentation

abstractmethod get_config()

Get optimizer configuration for checkpoint reconstruction.

Returns:

Dictionary containing optimizer type and configuration parameters.

Return type:

dict[str, Any]

Raises:

NotImplementedError – If the optimizer does not support checkpointing.

abstractmethod classmethod load_state(checkpoint_dir)

Load the optimizer’s internal state from a checkpoint directory.

Creates a new optimizer instance with the state restored from the checkpoint.

Parameters:

checkpoint_dir (Path | str) – Directory path where the optimizer state is saved.

Returns:

A new optimizer instance with restored state.

Return type:

Optimizer

abstractmethod optimize(cost_fn, initial_params=None, callback_fn=None, **kwargs)

Optimize the given cost function starting from initial parameters.

Parameters:

• cost_fn (Callable[[ndarray[tuple[Any, ...], dtype[double]]], float | ndarray[tuple[Any, ...], dtype[double]]]) – The cost function to minimize.

• initial_params (ndarray[tuple[Any, ...], dtype[double]] | None) – Initial parameters for the optimization.

• callback_fn (Callable[[OptimizeResult], Any] | None) – Function called after each iteration with an OptimizeResult object.

• **kwargs –

  Additional keyword arguments for the optimizer:

  • max_iterations (int, optional): Total desired number of iterations. When resuming from a checkpoint, this represents the total iterations desired across all runs. The optimizer will automatically calculate and run only the remaining iterations needed. Defaults vary by optimizer (e.g., 5 for population-based optimizers, None for some scipy methods).

  • rng (np.random.Generator, optional): Random number generator for stochastic optimizers (PymooOptimizer, MonteCarloOptimizer). Defaults to a new generator if not provided.

  • jac (Callable, optional): Gradient/Jacobian function for gradient-based optimizers (only used by ScipyOptimizer with L_BFGS_B method). Defaults to None.

Return type:

OptimizeResult

Returns:

Optimized parameters.

abstractmethod reset()

Reset the optimizer’s internal state to allow fresh optimization runs.

Clears any state accumulated during previous optimization runs, allowing the optimizer to be reused for new optimization problems without creating a new instance.

Return type:

None

abstractmethod save_state(checkpoint_dir)

Save the optimizer’s internal state to a checkpoint directory.

Parameters:

checkpoint_dir (Path | str) – Directory path where the optimizer state will be saved.

Return type:

None