qarp.optimizers

Classical optimizers for variational loops. Public depth: flat. Submodules are private.

class qarp.optimizers.AdaGradOptimizer(options=None)[source]

Bases: GradientDescentOptimizer

compute_update(params, grads, step)[source]

Compute the AdaGrad parameter update.

AdaGrad update rule for parameters:

accum = accum + (gradient ** 2) x_{k+1} = x_k - lr * gradient / (sqrt(accum) + eps)

Parameters:

  • params (np.ndarray) – Current parameter vector.

  • grads (np.ndarray) – Gradient vector evaluated at the current parameters.

  • step (int) – Current optimization step (unused for AdaGrad).

Returns:

The AdaGrad update to be added to the parameters.

Return type:

np.ndarray

class qarp.optimizers.AdamOptimizer(options=None)[source]

Bases: GradientDescentOptimizer

compute_update(params, grads, step)[source]

Compute the Adam parameter update.

Adam update rule for parameters:

m = beta1 * m + (1 - beta1) * gradient v = beta2 * v + (1 - beta2) * (gradient ** 2) m_hat = m / (1 - beta1 ** t) v_hat = v / (1 - beta2 ** t) x_{k+1} = x_k - lr * m_hat / (sqrt(v_hat) + eps)

This applies the Adam optimization rule using exponential moving averages of the first and second moments of the gradients. Bias‑corrected moment estimates are used to form the adaptive learning rate update.

Parameters:

  • params (np.ndarray) – Current parameter vector.

  • grads (np.ndarray) – Gradient vector evaluated at the current parameters.

  • step (int) – Current optimization step (0 indexed), used for bias correction.

Returns:

The Adam update to be added to the parameters.

Return type:

np.ndarray

class qarp.optimizers.AdamaxOptimizer(options=None)[source]

Bases: GradientDescentOptimizer

compute_update(params, grads, step)[source]

Compute the Adamax parameter update.

Adamax update rule for parameters:

m = beta1 * m + (1 - beta1) * gradient u = max(beta2 * u, abs(gradient)) m_hat = m / (1 - beta1 ** t) x_{k+1} = x_k - lr * m_hat / (u + eps)

This applies the Adamax update rule using: - first moment accumulation for gradients, - an exponentially decayed infinity norm for the second moment, - bias corrected first moment estimates.

Parameters:

  • params (np.ndarray) – Current parameter vector.

  • grads (np.ndarray) – Gradient vector evaluated at the current parameters.

  • step (int) – Current optimization step (0 indexed).

Returns:

The Adamax update to be added to the parameters.

Return type:

np.ndarray

class qarp.optimizers.EarlyStopper(objective_fn: Callable, initial_params: List[float] | ndarray, es_tol: float = 1e-06, patience: int = 10, ema_beta: float = 1.0)[source]

Bases: object

class qarp.optimizers.GradientDescentOptimizer(options: dict | None = None)[source]

Bases: Optimizer

compute_update(params: List[float] | ndarray, grads: List[float] | ndarray, step: int) → ndarray[source]
minimize(objective_function: Callable, initial_parameters: List[float] | ndarray, callback: Callable[[ndarray], None] | None = None, gradient: Callable | None = None, tol: float | None = None, bounds: Iterable | None = None) → OptimizeResult[source]

Run a unified gradient-based optimization loop.

This builds a gradient function (user-provided or estimated), iteratively updates the parameters via the child-implemented compute_update, and optionally performs early stopping with an EMA-smoothed objective. If early stopping is enabled, the final parameters can be snapped to the best seen.

Parameters:

  • objective_function – Function mapping a parameter vector to a scalar objective value.

  • initial_parameters (List, np.ndarray) – Starting parameter vector. Will be converted to a numpy array.

  • callback – Optional function called after each parameter update with the current parameters.

  • gradient – Optional user-provided gradient function. If not provided, a gradient estimator is selected based on options (e.g., finite differences or SPSA-based gradient estimator).

  • tol – Must be None — convergence is controlled by the maxiter / early_stopping options.

  • bounds – Must be None — the update rules are unconstrained.

Returns:

An object containing:

  • x: Final parameter vector (possibly early-stopped to the best seen).

  • fun: Objective value at the final parameters.

  • nit: Number of iterations performed.

  • nfev: Number of objective evaluations.

  • success: Boolean indicating successful completion.

Return type:

OptimizeResult

reset_state() → None[source]

Clear per-run accumulator state so one instance can be reused.

Covers the moment/accumulator attributes of the shipped subclasses; a subclass carrying extra per-run state overrides this and calls super().reset_state().

supports_bounds: bool = False
class qarp.optimizers.NadamOptimizer(options=None)[source]

Bases: GradientDescentOptimizer

compute_update(params, grads, step)[source]

Compute the Nadam parameter update.

Nadam update rule for parameters:

m = beta1 * m + (1 - beta1) * gradient
v = beta2 * v + (1 - beta2) * (gradient ** 2)
m_hat = m / (1 - beta1 ** t)
v_hat = v / (1 - beta2 ** t)
nesterov_term = (
    beta1 * m_hat + (1 - beta1) * gradient / (1 - beta1 ** t)
)
x_{k+1} = x_k - lr * nesterov_term / (sqrt(v_hat) + eps)

This applies the Nadam update rule using: - exponential moving averages of first and second moments, - bias‑corrected moment estimates, - Nesterov momentum applied on the predicted gradient direction.

Parameters:

  • params (np.ndarray) – Current parameter vector.

  • grads (np.ndarray) – Gradient vector evaluated at the current parameters.

  • step (int) – Current optimization step (0 indexed), used for bias corrections.

Returns:

The Nadam update to be added to the parameters.

Return type:

np.ndarray

class qarp.optimizers.Optimizer[source]

Bases: ABC

Base Optimizer class.

abstractmethod minimize(objective_function: Callable, initial_parameters: List | ndarray, callback: Callable | None = None, gradient: Callable | None = None, tol: float | None = None, bounds: Iterable | None = None) → Any[source]
supports_bounds: bool = True
class qarp.optimizers.RMSPropOptimizer(options=None)[source]

Bases: GradientDescentOptimizer

compute_update(params, grads, step)[source]

Compute the RMSProp parameter update.

RMSProp update rule for parameters:

avg_sq = beta * avg_sq + (1 - beta) * (gradient ** 2) x_{k+1} = x_k - lr * gradient / (sqrt(avg_sq) + eps)

Parameters:

  • params (np.ndarray) – Current parameter vector.

  • grads (np.ndarray) – Gradient vector evaluated at the current parameters.

  • step (int) – Current optimization step (unused for RMSProp).

Returns:

The RMSProp update to be added to the parameters.

Return type:

np.ndarray

class qarp.optimizers.RotosolveOptimizer(maxiter=100, tol=1e-07, lr=1, schedule=None, gamma=0.99, power=2, verbose=False, flat_tol=1e-10, max_restarts=3, kick_size=0.1)[source]

Bases: Optimizer

Rotosolve optimizer. See Ostaszewski et al., arXiv: 1905.09692 (2021) This optimizer is designed for optimizing parameters in variational circuits and assumes that the objective function is periodic, with a period of 2*pi, with respect to each parameter. :param maxiter: maximum number of Rotosolve macroiterations :param tol: convergence criterion :param verbose: print verbose output every macroiteration and every microiteration

minimize(objective_function: Callable, initial_parameters: List | ndarray, callback: Callable | None = None, gradient: Callable | None = None, tol: float | None = None, bounds: Iterable | None = None) → Any[source]

Minimize the objective function provided, starting at the initial parameters. :param objective_function: Function to minimize. :param initial_parameters: Initial values of parameters. It is usually best to start from a zero vector. :param callback: An optional callable to call with the parameters after each update (as in scipy optimizers). :param gradient: Must be None. :param tol: Must be None — the convergence criterion is the constructor’s tol. :param bounds: Must be None — the update rule assumes an unbounded 2π-periodic domain.

Returns:

A SciPy Result object.

supports_bounds: bool = False
class qarp.optimizers.SGDOptimizer(options=None)[source]

Bases: GradientDescentOptimizer

compute_update(params, grads, step)[source]

Compute the SGD parameter update.

SGD update rule for parameters:

x_{k+1} = x_k - lr * gradient_estimate
Parameters:

  • params (np.ndarray) – Current parameter vector.

  • grads (np.ndarray) – Gradient vector evaluated at the current parameters.

  • step (int) – Current optimization step (unused for SGD).

Returns:

The SGD update to be added to the parameters.

Return type:

np.ndarray

class qarp.optimizers.SPSAOptimizer(options=None)[source]

Bases: GradientDescentOptimizer

compute_update(params, grads, step)[source]

Compute the SPSA parameter update. Below parameters for optimizer are keys of options dictionary.

SPSA update rule for parameters:

a_k = a0 / (k + 1 + A) ** alpha x_{k+1} = x_k - a_k * gradient_estimate

Parameters:

  • params (np.ndarray) – Current parameter vector.

  • grads (np.ndarray) – SPSA gradient estimate at the current parameters.

  • step (int) – Current optimization step (0‑indexed), used in the decay rule.

Returns:

The SPSA update to be added to the parameters.

Return type:

np.ndarray

class qarp.optimizers.ScipyOptimizer(method: str, options: dict | None = None)[source]

Bases: Optimizer

minimize(objective_function: Callable, initial_parameters: List | ndarray, callback: Callable | None = None, gradient: Callable | None = None, tol: float | None = None, bounds: Iterable[float] | None = None) → Any[source]

Minimize the objective function provided, starting at the initial parameters.

Parameters:

  • objective_function – The objective function to minimize.

  • initial_parameters – The parameters from which to begin the optimization.

  • callback – An optional callable to call with the parameters after each update.

  • gradient – A function which returns the gradient as an array in coincidence with the parameters provided.

Returns:

A SciPy Result object.

qarp.optimizers.compute_fd_gradients(objective: Callable, params: List[float] | ndarray, step: int = 0, fd_eps: float = 1e-05) → ndarray[source]

Compute gradients using forward finite differences.

Approximates the gradient of a scalar objective function using forward finite differences:

g_i ≈ (f(x + ε e_i) - f(x)) / ε

The step argument is currently unused, but is included for compatibility with optimizers that support iteration-dependent behavior (e.g., learning-rate decay).

Parameters:

  • objective (Callable) – Objective function to differentiate. Must accept a NumPy array of parameters and return a scalar value.

  • params (List, np.ndarray) – Point at which to evaluate the gradient. Will be converted to a numpy array for compatibility.

  • step (int, optional) – Optimization step or iteration index. Not used in this implementation. Default is 0.

  • fd_eps (float, optional) – Finite-difference step size epsilon. Defaults is 1e-5.

Returns:

Numpy array containing the forward finite-difference gradient with respect to each parameter.

Return type:

np.ndarray

qarp.optimizers.compute_spsa_gradients(objective: Callable, params: List[float] | ndarray, ck: float = 0.01, num_perturbations: int = 1, seed: int | None = None) → ndarray[source]

Estimate the gradient using the SPSA estimator.

This computes a Simultaneous Perturbation Stochastic Approximation (SPSA) gradient estimate by sampling random +/-1 perturbation vectors and using a two term finite difference.

Parameters:

  • objective – Function that maps a parameter vector to a scalar.

  • params (List, np.ndarray) – Point at which to evaluate the gradient. Will be converted to a numpy array for compatibility.

  • ck – Perturbation size used in finite differences/SPSA algorithm.

  • num_perturbations – Number of perturbation samples to average.

  • seed – Optional random seed.

Returns:

A numpy array containing the SPSA gradient estimate.