qrunch.tools.minimizers.fft

Utilities for FFT-based minimization.

Module Attributes

DEFAULT_OPTIONS

Default options for the FFT minimizer.

Functions

newton_refine_1d(*, function, gradient, ...)

Refine a 1D minimum using Newton-Raphson iteration.

Classes

FftMinimizer

FFT-based minimizer for multivariable functions.

FftMinimizerOptions

Options controlling FftMinimizer (FFT-based 1D/2D trigonometric polynomial minimizer).

NewtonRefinementResult

Result of a 1D Newton-Raphson refinement.
DEFAULT_OPTIONS = FftMinimizerOptions(fft_padded_size_1d=16384, fft_padded_size_2d=2048, improve_on_fft_min=True, maximum_iterations=100, x_value_tolerance=1e-08, grad_tolerance=1e-12)

Default options for the FFT minimizer.

class FftMinimizer

Bases: Minimizer

FFT-based minimizer for multivariable functions.

__init__(options: FftMinimizerOptions | None = None) → None

Initialize the minimizer.

Parameters:

options (FftMinimizerOptions | None) – Options to pass to the minimizer.

Return type:

None

minimize(function: Callable[[list[ndarray[tuple[Any, ...], dtype[float64]]]], list[float]], initial_guess: ndarray[tuple[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

Optimize the given function.

Parameters:

  • function (Callable[[list[ndarray[tuple[Any, ...], dtype[float64]]]], list[float]]) – The function to minimize.

  • initial_guess (ndarray[tuple[Any, ...], dtype[float64]]) – Used for determining input size.

  • iteration (int | None) – Ignored.

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

  • circuit (Circuit | None) – The parameterized circuit to be minimized.

  • operator (HermitianPauliSum | None) – The operator used in the expectation value.

Return type:

MinimizerResult

objective_values: list[float]
class FftMinimizerOptions

Bases: DataclassPublicAPI

Options controlling FftMinimizer (FFT-based 1D/2D trigonometric polynomial minimizer).

Parameters:

  • fft_padded_size_1d – int, default=2**14 FFT zero-padded size for dense interpolation in the 1D case (power of two).

  • fft_padded_size_2d – int, default=2**11 FFT zero-padded size per dimension for dense interpolation in the 2D case (power of two).

  • improve_on_fft_min – bool, default=True If True refine the FFT-seeded minimum with a local continuous optimizer (analytic model in 2D / bounded scalar search in 1D).

  • maximum_iterations – int, default=100 Maximum iterations for the local refinement stage when improve_on_fft_min is enabled.

  • x_value_tolerance – float, default=1e-8 Convergence tolerance on the refined solution value (mapped to SciPy xatol / ftol depending on context).

  • grad_tolerance – float, default=1e-12

__init__(*, fft_padded_size_1d: int = 16384, fft_padded_size_2d: int = 2048, improve_on_fft_min: bool = True, maximum_iterations: int = 100, x_value_tolerance: float = 1e-08, grad_tolerance: float = 1e-12) → None
Parameters:

  • fft_padded_size_1d (int)

  • fft_padded_size_2d (int)

  • improve_on_fft_min (bool)

  • maximum_iterations (int)

  • x_value_tolerance (float)

  • grad_tolerance (float)

Return type:

None

fft_padded_size_1d: int = 16384
fft_padded_size_2d: int = 2048
grad_tolerance: float = 1e-12
improve_on_fft_min: bool = True
maximum_iterations: int = 100
x_value_tolerance: float = 1e-08
class NewtonRefinementResult

Bases: object

Result of a 1D Newton-Raphson refinement.

Parameters:

  • x – The refined x value at the minimum.

  • value – The function value at the refined minimum.

  • converged – Whether the iteration converged within tolerances.

  • iterations – Number of Newton iterations performed.

  • gradient_norm – Absolute gradient at the final x.

__init__(x: float, value: float, converged: bool, iterations: int, gradient_norm: float) → None
Parameters:

  • x (float)

  • value (float)

  • converged (bool)

  • iterations (int)

  • gradient_norm (float)

Return type:

None

converged: bool
gradient_norm: float
iterations: int
value: float
x: float
newton_refine_1d(*, function: Callable[[float], float], gradient: Callable[[float], float], hessian: Callable[[float], float], x0: float, maximum_iterations: int, grad_tolerance: float, x_value_tolerance: float, hessian_zero_threshold: float = 1e-15) → NewtonRefinementResult

Refine a 1D minimum using Newton-Raphson iteration.

Performs the iteration \(x_{n+1} = x_n - f'(x_n) / f''(x_n)\) until convergence. For a low-degree trigonometric polynomial with exact gradient and Hessian, this converges quadratically to machine precision in a few iterations.

Parameters:

  • function (Callable[[float], float]) – Scalar function f(x) to minimize.

  • gradient (Callable[[float], float]) – First derivative f’(x).

  • hessian (Callable[[float], float]) – Second derivative f’’(x).

  • x0 (float) – Initial guess for the minimum.

  • maximum_iterations (int) – Maximum number of Newton steps.

  • grad_tolerance (float) – Convergence threshold on gradient.

  • x_value_tolerance (float) – Convergence threshold on the step size.

  • hessian_zero_threshold (float) – Threshold below which the Hessian is considered zero.

Return type:

NewtonRefinementResult