qrunch.tools.minimizers.minimizers_protocols

Contains the interface for the minimizers.

Classes

AdaptiveIterationCallback

Protocol for a callback that can be called at each iteration of the adaptive minimizer.

Minimizer

ABC for a multivariable minimizer.

MinimizerResult

Dataclass for the minimized result.
class AdaptiveIterationCallback

Bases: Protocol

Protocol for a callback that can be called at each iteration of the adaptive minimizer.

__init__(*args, **kwargs)
record_adaptive_iteration(adaptive_iteration: int, unoptimized_circuit: Circuit, minimized_parameters: dict[Parameter, float], expectation_value: ExpectationValue, n_estimator_shots: int, operator: FermionHermitianSumProtocol | PairedHardcoreBosonHermitianSumProtocol | None = None) → None

Call the callback function with the indicated parameters from the finished adaptive iteration.

Note that the adaptive_iteration integer starts at 0 and is incremented with 1 each iteration, except for when reminimizing, then a special value of -1 is given.

Parameters:
Return type:

None

class Minimizer

Bases: ABC

ABC for a multivariable minimizer.

abstractmethod minimize(function: Callable[[list[ndarray[Any, dtype[float64]]]], list[float]], initial_guess: ndarray[Any, dtype[float64]], iteration: int | None, bounds: tuple[float, float] | list[tuple[float, float]] | None = None, circuit: Circuit | None = None, operator: HermitianPauliSum | None = None) → MinimizerResult

Minimize a real-valued objective \(f: \\mathbb{R}^p \\to \\mathbb{R}\), where \(p\) is the number of optimization parameters.

Batching

The objective function is batch-oriented: it receives a list of candidate parameter vectors and must return a list of scalar values of the same length.

  • Input: [theta_0, theta_1, ..., theta_{n-1}] where each theta_i is

    a 1-D numpy array with shape (p,).

  • Output: [f(theta_0), f(theta_1), ..., f(theta_{n-1})] in the same

    order.

Why batching?

  • On quantum backends (and some simulators) it is often more efficient to

    evaluate many parameter settings at once (circuit batching, shared shots, etc.).

  • Many optimization strategies require multiple evaluations per iteration.

Initial guess

  • initial_guess is a single parameter vector of length p used as the

    starting point for the optimization algorithm.

  • There is intentionally not a list of initial guesses; the batch dimension

    is only for evaluating multiple candidate points per iteration derived from, or around, this single starting point.

Bounds

  • Either a single tuple (low, high) applied to all parameters or a list

    of (low, high) tuples of length p. Bounds apply to every candidate evaluated in a batch.

param function:

Batch objective. Takes a list of parameter vectors (each of shape (p,)) and returns a list of floats of the same length with their objective values.

param initial_guess:

Single starting point R^p (shape (p,)).

param iteration:

If applicable, the current iteration. This can be used by some minimizers to adjust their behavior based on the iteration.

param bounds:

Either a single (low, high) tuple broadcast to all parameters, or a list of (low, high) tuples of length p.

param circuit:

Optional; The parameterized circuit to be minimized. In some minimizers circuit information may be used to improve the minimization.

param operator:

Optional; The operator used in the expectation value. In some minimizers operator information may be used to improve the minimization.

returns:

The final optimal parameters (shape (p,)) and the corresponding scalar function value. Even though evaluations may be batched for efficiency, the problem is single-objective and yields one result.

rtype:

MinimizerResult

Parameters:

  • function (Callable[[list[ndarray[Any, dtype[float64]]]], list[float]])

  • initial_guess (ndarray[Any, dtype[float64]])

  • iteration (int | None)

  • bounds (tuple[float, float] | list[tuple[float, float]] | None)

  • circuit (Circuit | None)

  • operator (HermitianPauliSum | None)

Return type:

MinimizerResult

class MinimizerResult

Bases: object

Dataclass for the minimized result.

All fields are immutable (frozen=True) so an instance can be safely reused.

Parameters:

  • parameters – Minimized parameters

  • function_value – Minimized function value

__init__(parameters: ndarray[Any, dtype[float64]], function_value: float) → None
Parameters:

  • parameters (ndarray[Any, dtype[float64]])

  • function_value (float)

Return type:

None

function_value: float
parameters: ndarray[Any, dtype[float64]]