qrunch.tools.minimizers

The Classical minimizers used in the VQE algorithms.

All minimizers from external packages are wrapped in a facade so that they follow the Minimizer protocol.

Module Attributes

DEFAULT_SEQUENTIAL_MINIMIZER

The default sequential minimizer first optimizes the parameters one by one using the FFT minimizer, and then it optimizes a subset of the 10 largest parameters (by absolute value).

Classes

`CyclerMinimizerCreator`	Creator for creating CyclerMinimizers.
`FftMinimizerCreator`	Creator for creating FftMinimizers.
`LastNParameterMinimizerCreator`	Creator for creating LastNParameterMinimizers.
`MinimizerCreator`	Creator for creating minimizers.
`MinimizerSubCreator`	Creator for setting a minimizer on a parent creator.
`ReMinimizerSubCreator`	Creator for setting a reminimizer on a parent creator.
`ScipyMinimizerCreator`	Creator for creating ScipyMinimizers.
`SequentialMinimizerCreator`	Creator for creating SequentialMinimizers.
`SubsetMinimizerCreator`	Creator for creating SubsetMinimizers.

class CyclerMinimizerCreator

Bases: object

Creator for creating CyclerMinimizers.

__init__() → None

Initialize the CyclerMinimizerCreator.

Return type:: None

create() → CyclerMinimizer

Create the CyclerMinimizer.

Cycles variables in fixed-size blocks, optimizing each using the given minimizer.

Return type:: CyclerMinimizer

with_minimizer(minimizer: Minimizer | None) → Self

Set the minimizer to use for each block.

Parameters:: minimizer (Minimizer | None)
Return type:: Self

with_options(options: CyclerMinimizerOptions | None) → Self

Set options for the CyclerMinimizer.

Parameters:: options (CyclerMinimizerOptions | None) – Options for the minimizer.
Return type:: Self

with_parameter_sorting_strategy(parameter_sorting_strategy: Literal['DescendingAbsoluteValueSortingStrategy', 'OperatorCommutativitySortingStrategy', 'RandomSortingStrategy', 'IdentitySortingStrategy'] | None) → Self

Set the parameter sorting strategy to use at each VQE-iteration.

Strategy

Sort indices by absolute parameter size (descending).
Partition into contiguous blocks of size k.
Prune indices/block whose improvement falls below the threshold and repeat.

Parameters:: parameter_sorting_strategy (Literal['DescendingAbsoluteValueSortingStrategy', 'OperatorCommutativitySortingStrategy', 'RandomSortingStrategy', 'IdentitySortingStrategy'] | None) – Strategy to sort the targeted parameters at each VQE-iteration.
Return type:: Self

DEFAULT_SEQUENTIAL_MINIMIZER = <qrunch.tools.minimizers.sequential.SequentialMinimizer object>: The default sequential minimizer first optimizes the parameters one by one using the FFT minimizer, and then it optimizes a subset of the 10 largest parameters (by absolute value).

class FftMinimizerCreator

Bases: object

Creator for creating FftMinimizers.

__init__() → None

Initialize the FftMinimizerCreator.

Return type:: None

create() → FftMinimizer

Create the FftMinimizer.

The FFTMinimizer minimize trigonometric polynomials using the fast Fourier transform (FFT). It is based on the fact that a unitary evolution with a parametrized gate can be written as a complex trigonometric polynomial.

This minimizer is efficient for few-parameter optimization problems where the objective function can be expanded as 5^k terms, where k is the number of parameters. This is often the case in VQE algorithms where only a few parameters are added at a time.

Return type:: FftMinimizer

with_options(options: FftMinimizerOptions) → Self

Set options for the FftMinimizer.

Parameters:: options (FftMinimizerOptions) – Options for the FftMinimizer.
Return type:: Self

class LastNParameterMinimizerCreator

Bases: object

Creator for creating LastNParameterMinimizers.

__init__() → None

Initialize the LastNParameterMinimizerCreator.

Return type:: None

create() → LastNParameterMinimizer

Create the LastNParameterMinimizer.

The minimizer optimizes the last N (most recently appended) parameters. Earlier parameters are held fixed. This pattern is useful in adaptive VQEs where new parameters are appended over time and, at certain stages, only the freshly introduced subset should be relaxed without disturbing the previously converged portion of the state.

Return type:: LastNParameterMinimizer

with_minimizer(minimizer: Minimizer | None) → Self

Set the minimizer to use for the last N parameters.

Parameters:: minimizer (Minimizer | None) – The minimizer to use for the last parameters.
Return type:: Self

with_options(options: LastNParameterMinimizerOptions | None) → Self

Set options for the LastNParameterMinimizer.

Parameters:: options (LastNParameterMinimizerOptions | None) – Options for the minimizer.
Return type:: Self

class MinimizerCreator

Bases: object

Creator for creating minimizers.

static cycler() → CyclerMinimizerCreator

Narrow the minimizer to a CyclerMinimizer.

Cycles variables in fixed-size blocks, optimizing each using the given minimizer.

Return type:: CyclerMinimizerCreator

static every_nth_reminimizer() → EveryNthReminimizerMinimizerCreator

Narrow the minimizer to a EveryNthReminimizerMinimizer.

This is a minimizer that conditionally delegates to one of two sub-minimizers based on the iteration number.

This minimizer acts as a switch. For most iterations, it uses a standard minimizer. However, at a specified frequency (every_nth_iteration), it switches to a reminimizer. This is useful for implementing complex optimization schedules, such as performing a more thorough or different style of optimization periodically. For example, one might use a fast local optimizer for most steps and a more global or exhaustive optimizer every N steps to escape local minima.

The default is doing the reminimizer step every 10th iteration.

The default reminimizer is a CyclerMinimizer with FftMinimizer as minimizer, optimizing one variable at a time for one cycle.

Return type:: EveryNthReminimizerMinimizerCreator

static fft() → FftMinimizerCreator

Narrow the minimizer to a FftMinimizer.

The FFTMinimizer minimize trigonometric polynomials using the fast Fourier transform (FFT). It is based on the fact that a unitary evolution with a parametrized gate can be written as a complex trigonometric polynomial.

This minimizer is efficient for few-parameter optimization problems where the objective function can be expanded as 5^k terms, where k is the number of parameters. This is often the case in VQE algorithms where only a few parameters are added at a time.

Return type:: FftMinimizerCreator

static last_n_variable() → LastNParameterMinimizerCreator

Narrow the minimizer to a LastNParameterMinimizer.

The minimizer optimizes the last N (most recently appended) parameters. Earlier parameters are held fixed. Default is N=1.

The default minimizer is the FftMinimizer.

This pattern is useful in adaptive VQEs where new parameters are appended over time and, at certain stages, only the freshly introduced subset should be relaxed without disturbing the previously converged portion of the state.

Return type:: LastNParameterMinimizerCreator

static scipy() → ScipyMinimizerCreator

Narrow the minimizer to a ScipyMinimizer.

This minimizer is a facade around the minimize function from the Scipy.minimizer package with the specified method.

If only for single-parameter optimization (e.g. when only adding a single gate at a time in FAST-VQE), the FftMinimizer is often more efficient.

Return type:: ScipyMinimizerCreator

static sequential() → SequentialMinimizerCreator

Narrow the minimizer to a SequentialMinimizer.

Minimizes a function sequentially using a list of minimizers; the output of one minimizer is used as the input to the next minimizer.

Return type:: SequentialMinimizerCreator

static subset() → SubsetMinimizerCreator

Narrow the minimizer to a SubsetMinimizer.

This minimizer focuses on a subset of parameters while keeping the remaining parameters fixed.

Return type:: SubsetMinimizerCreator

class MinimizerSubCreator

Bases: Generic[T]

Creator for setting a minimizer on a parent creator.

__init__(parent: T, field_name: str) → None

Initialize the minimizer creator.

Parameters:

parent (T) – The parent creator to which the minimizer will be assigned.
field_name (str) – The name of the field in the parent creator.

Return type:

None

balanced_default() → T

Set the minimizer identical to quick_default, but reminimizes every 10th iteration.

Uses an FftMinimizer (1D) optimizing only the last variable during normal iterations. Every 10th iteration, the reminimizer optimizes the last 10 variables using a ScipyMinimizer.

Return type:: T

cycler(minimizer: Minimizer | None = None, options: CyclerMinimizerOptions | None = None, parameter_sorting_strategy: Literal['DescendingAbsoluteValueSortingStrategy', 'OperatorCommutativitySortingStrategy', 'RandomSortingStrategy', 'IdentitySortingStrategy'] | None = None) → T

Set the minimizer to a CyclerMinimizer.

Cycles variables in fixed-size blocks, optimizing each using the given minimizer.

Strategy - Sort indices by absolute parameter size (descending). - Partition into contiguous blocks of size k. - Prune indices/block whose improvement falls below the threshold and repeat.

Parameters:

minimizer (Minimizer | None) – Minimizer to use in cycle. If None, the default is FftMinimizer().
options (CyclerMinimizerOptions | None) – Options for the minimizer. If None, default options CyclerMinimizerOptions are used.
parameter_sorting_strategy (Literal['DescendingAbsoluteValueSortingStrategy', 'OperatorCommutativitySortingStrategy', 'RandomSortingStrategy', 'IdentitySortingStrategy'] | None) – Strategy to sort the targeted parameters at each VQE-iteration.

Return type:

T

every_nth_reminimizer(minimizer: Minimizer | None = None, reminimizer: Minimizer | None = None, options: EveryNthReminimizerMinimizerOptions | None = None) → T

Create an EveryIthReminimizerMinimizer.

The minimizer optimizes the parameters using a standard minimizer during normal VQE iterations, and uses a different reminimizer during every n’th VQE iteration. Default is every 10th iteration.

Parameters:

minimizer (Minimizer | None) – The minimizer to use for the normal VQE iterations. If None, the default is FftMinimizer().
reminimizer (Minimizer | None) – The minimizer to use for the every n’th VQE iteration. If None, the default is CyclerMinimizer.
options (EveryNthReminimizerMinimizerOptions | None) – Options for the minimizer.

Return type:

T

last_n_variable(minimizer: Minimizer | None = None, options: LastNParameterMinimizerOptions | None = None) → T

Set the minimizer to a LastNParameterMinimizer.

The minimizer optimizes the last N (most recently appended) parameters. Earlier parameters are held fixed. Default is N=1.

This pattern is useful in adaptive VQEs where new parameters are appended over time and, at certain stages, only the freshly introduced subset should be relaxed without disturbing the previously converged portion of the state.

Parameters:

minimizer (Minimizer | None) – The minimizer to use for the optimization. If None, the default is FftMinimizer().
options (LastNParameterMinimizerOptions | None) – Options for the minimizer.

Return type:

T

last_variable_fft(options: FftMinimizerOptions | None = None) → T

Set the minimizer to an FftMinimizer optimizing only the last variable.

The FFTMinimizer minimize trigonometric polynomials using the fast Fourier transform (FFT). It is based on the fact that a unitary evolution with a parametrized gate can be written as a complex trigonometric polynomial.

This minimizer is efficient for few-parameter optimization problems where in the 1-parameter case, the objective function can be expanded as 5 terms, thus requiring only 5 function evaluations for an exact minimization.

Parameters:: options (FftMinimizerOptions | None) – Options for the minimizer.
Return type:: T

precise_default() → T

Set the minimizer to an FftMinimizer (1D) optimizing only the last variable.

Then reminimizes every 10th iteration. The reminimizer is a CyclerMinimizer that optimizes all the variables in a single cycle of 2-variable optimizations using the FftMinimizer (2D). The CyclerMinimizer uses a parameter sorting strategy based on operator commutativity.

Return type:: T

quick_default() → T

Set the minimizer to a greedy setting, with the FftMinimizer optimizing only the last variable.

The FFTMinimizer minimize trigonometric polynomials using the fast Fourier transform (FFT). It is based on the fact that a unitary evolution with a parametrized gate can be written as a complex trigonometric polynomial.

This minimizer is efficient for few-parameter optimization problems where in the 1-parameter case, the objective function can be expanded as 5 terms, thus requiring only 5 function evaluations for an exact minimization.

Return type:: T

scipy(method: Literal['Nelder-Mead', 'Powell', 'CG', 'BFGS', 'L-BFGS-B', 'TNC', 'COBYLA', 'COBYQA', 'SLSQP'] | ScipyMinimizerMethods | None = None, options: ScipyMinimizerOptions | None = None) → T

Set the minimizer to a ScipyMinimizer.

This minimizer is a facade around the minimize function from the Scipy.minimizer package with the specified method.

If only for single-parameter optimization (e.g. when only adding a single gate at a time in FAST-VQE), the FftMinimizer is often more efficient.

Parameters:

method (Literal['Nelder-Mead', 'Powell', 'CG', 'BFGS', 'L-BFGS-B', 'TNC', 'COBYLA', 'COBYQA', 'SLSQP'] | ~qrunch.tools.minimizers.scipy_minimizer.ScipyMinimizerMethods | None) – The minimization method to use. If None, the default method ‘COBYLA’ is used.
options (ScipyMinimizerOptions | None) – Options for the Scipy minimizer. If None, default options ScipyMinimizerOptions are used.

Return type:

T

sequential(minimizers: list[Minimizer] | None = None) → T

Set the minimizer to a SequentialMinimizer.

Minimizes a function sequentially using a list of minimizers; the output of one minimizer is used as the input to the next minimizer.

Parameters:: minimizers (list[Minimizer] | None) – A list of multivariable minimizers to use in sequence. If None, it uses a default sequential minimizer that first optimizes the parameters one by one using the FFT minimizer, and then it optimizes a subset of the 10 largest parameters (by absolute value) using the default ScipyMinimizer.
Return type:: T

very_precise_default() → T

Set the minimizer to an FftMinimizer (2D) optimizing only the last two variables.

Then reminimizes every 10th iteration. The reminimizer is a CyclerMinimizer that optimizes all the variables in blocks of 10 using the ScipyMinimizer. The CyclerMinimizer uses a parameter sorting strategy based on operator commutativity.

Return type:: T

class ReMinimizerSubCreator

Bases: Generic[T]

Creator for setting a reminimizer on a parent creator.

__init__(parent: T, field_name: str) → None

Initialize the minimizer creator.

Parameters:

parent (T) – The parent creator to which the minimizer will be assigned.
field_name (str) – The name of the field in the parent creator.

Return type:

None

cycler(minimizer: Minimizer | None = None, options: CyclerMinimizerOptions | None = None, parameter_sorting_strategy: Literal['DescendingAbsoluteValueSortingStrategy', 'OperatorCommutativitySortingStrategy', 'RandomSortingStrategy', 'IdentitySortingStrategy'] | None = None) → T

Set the reminimizer to a CyclerMinimizer.

Cycles variables in fixed-size blocks, optimizing each using the given minimizer.

Strategy - Sort indices by absolute parameter size (descending). - Partition into contiguous blocks of size k. - Prune indices/block whose improvement falls below the threshold and repeat.

Parameters:

minimizer (Minimizer | None) – Minimizer to use in cycle. If None, the default is FftMinimizer().
options (CyclerMinimizerOptions | None) – Options for the minimizer. If None, default options CyclerMinimizerOptions are used.
parameter_sorting_strategy (Literal['DescendingAbsoluteValueSortingStrategy', 'OperatorCommutativitySortingStrategy', 'RandomSortingStrategy', 'IdentitySortingStrategy'] | None) – Strategy to sort the targeted parameters at each VQE-iteration.

Return type:

T

scipy(method: Literal['Nelder-Mead', 'Powell', 'CG', 'BFGS', 'L-BFGS-B', 'TNC', 'COBYLA', 'COBYQA', 'SLSQP'] | ScipyMinimizerMethods | None = None, options: ScipyMinimizerOptions | None = None) → T

Set the reminimizer to a ScipyMinimizer.

This reminimizer is a facade around the minimize function from the Scipy.minimizer package with the specified method.

Parameters:

method (Literal['Nelder-Mead', 'Powell', 'CG', 'BFGS', 'L-BFGS-B', 'TNC', 'COBYLA', 'COBYQA', 'SLSQP'] | ~qrunch.tools.minimizers.scipy_minimizer.ScipyMinimizerMethods | None) – The minimization method to use. If None, the default method ‘SLSQP’ is used.
options (ScipyMinimizerOptions | None) – Options for the Scipy minimizer. If None, default options ScipyMinimizerOptions are used.

Return type:

T

sequential(minimizers: list[Minimizer] | None = None) → T

Set the reminimizer to a SequentialMinimizer.

Minimizes a function sequentially using a list of minimizers; the output of one minimizer is used as the input to the next minimizer.

Parameters:: minimizers (list[Minimizer] | None) – A list of multivariable minimizers to use in sequence. If None, it uses a default sequential minimizer that first optimizes the parameters one by one using the FFT minimizer, and then it optimizes a subset of the 20% largest parameters at once using the default ScipyMinimizer.
Return type:: T

subset(number_of_parameters_in_subset: int, minimizer: Minimizer | None = None) → T

Set the reminimizer to a SubsetMinimizer.

This reminimizer focuses on a subset of parameters while keeping the remaining parameters fixed.

Parameters:

number_of_parameters_in_subset (int) – The number of parameters to optimize.
minimizer (Minimizer | None) – The minimizer to use for the optimization. If None, the default is ScipyMinimizer().

Return type:

T

class ScipyMinimizerCreator

Bases: object

Creator for creating ScipyMinimizers.

__init__() → None

Initialize the ScipyMinimizerCreator.

Return type:: None

create() → ScipyMinimizer

Create the ScipyMinimizer.

This minimizer is a facade around the minimize function from the Scipy.minimizer package with the specified method.

If only for single-parameter optimization (e.g. when only adding a single gate at a time in FAST-VQE), the FftMinimizer is often more efficient.

Return type:: ScipyMinimizer

with_method(method: Literal['Nelder-Mead', 'Powell', 'CG', 'BFGS', 'L-BFGS-B', 'TNC', 'COBYLA', 'COBYQA', 'SLSQP'] | ScipyMinimizerMethods | None) → Self

Set the minimization method to use.

Parameters:: method (Literal['Nelder-Mead', 'Powell', 'CG', 'BFGS', 'L-BFGS-B', 'TNC', 'COBYLA', 'COBYQA', 'SLSQP'] | ~qrunch.tools.minimizers.scipy_minimizer.ScipyMinimizerMethods | None) – The minimization method to use. If None, the default method ‘COBYLA’ is used.
Return type:: Self

with_options(options: ScipyMinimizerOptions | None) → Self

Set options for the ScipyMinimizer.

Parameters:: options (ScipyMinimizerOptions | None) – Options for the Scipy minimizer.
Return type:: Self

class SequentialMinimizerCreator

Bases: object

Creator for creating SequentialMinimizers.

__init__() → None

Initialize the SequentialMinimizerCreator.

Return type:: None

create() → SequentialMinimizer

Create the SequentialMinimizer.

Minimizes a function sequentially using a list of minimizers; the output of one minimizer is used as the input to the next minimizer.

Return type:: SequentialMinimizer

with_minimizers(minimizers: list[Minimizer] | None) → Self

Specify a list of minimizers.

Parameters:: minimizers (list[Minimizer] | None) – A list of multivariable minimizers to use in sequence. If None, it uses a default sequential minimizer that first optimizes the parameters one by one using the FFT minimizer, and then it optimizes a subset of the 10 largest parameters (by absolute value) using the default ScipyMinimizer.
Return type:: Self

class SubsetMinimizerCreator

Bases: object

Creator for creating SubsetMinimizers.

__init__() → None

Initialize the SubsetMinimizerCreator.

Return type:: None

create() → SubsetMinimizer

Create the SubsetMinimizer.

This minimizer focuses on a subset of parameters while keeping the remaining parameters fixed.

Return type:: SubsetMinimizer

with_minimizer(minimizer: Minimizer | None) → Self

Set the minimizer to use for the subset of parameters.

Parameters:: minimizer (Minimizer | None) – The minimizer to use for the optimization.
Return type:: Self

with_number_of_parameters_in_subset(number_of_parameters_in_subset: int) → Self

Set the number of parameters to optimize.

Parameters:: number_of_parameters_in_subset (int) – The number of parameters to optimize (default 10).
Return type:: Self

minimizer_creator() → MinimizerCreator

Begin creating a minimizer.

Return type:: MinimizerCreator

Modules

`cycler_minimizer`	Optimizer that cycles through parameters optimizing each of them independently.
`every_nth_reminimizer`	A minimizer that uses a 'reminimizer' every nth iteration and a standard 'minimizer' for all other iterations.
`fft`	Utilities for FFT-based minimization.
`fft_utils`	Utilities for 2D Fourier coefficient recovery and optimization.
`last_n_parameter_minimizer`	Last-N parameter wrapper minimizer.
`minimizers_protocols`	Contains the interface for the minimizers.
`parameter_sorting_strategy`	Parameter sorting strategies.
`scipy_minimizer`	Wrapper around the minimizer from the Scipy package.
`sequential`	Sequential minimizer class that optimizes parameters with a given list of minimizers.
`subset`	Optimizer for a subset of parameters.