Struct VariationalQuantumOptimizer 

pub struct VariationalQuantumOptimizer<A: Float + ScalarOperand + Debug> { /* private fields */ }

Variational Quantum Optimizer.

VariationalQuantumOptimizer implements a SPSA optimizer with a quantum-inspired ansatz update rule. SPSA approximates the gradient with

    g_i(k) ≈ (L(θ + c_k * Δ) - L(θ - c_k * Δ)) / (2 * c_k * Δ_i)

where Δ ∈ {-1, +1}^d is sampled uniformly at every iteration. The gain sequences follow the canonical Spall (1998) recipe:

    a_k = a / (k + 1 + A)^α
    c_k = c / (k + 1)^γ

The “quantum ansatz” applies a rotation-gate-inspired factor cos²(θ_i / 2) to the SPSA update, smoothing updates near θ_i = 0 (mimicking how a rotation gate has unit effect near identity) and vanishing near θ_i = π.

Examples

use optirs_core::quantum_inspired::VariationalQuantumOptimizer;
use scirs2_core::ndarray::Array1;

let mut optimizer: VariationalQuantumOptimizer<f64> =
    VariationalQuantumOptimizer::new(0.1)
        .with_perturbation(0.05)
        .with_seed(7);

let params = Array1::from_vec(vec![0.5, -0.3, 1.2]);
let loss_fn = |theta: &Array1<f64>| theta.iter().map(|x| x * x).sum::<f64>();
let next = optimizer.step_from_loss(&params, loss_fn).expect("step failed");
assert_eq!(next.len(), 3);

Implementations

impl<A> VariationalQuantumOptimizer<A>

where A: Float + ScalarOperand + Debug + Send + Sync,

pub fn with_default_gain() -> Self

Create a VQE-inspired SPSA optimizer with the canonical SPSA gain a = 0.1, matching the defaults already used for c, α, γ and A.

Examples

use optirs_core::quantum_inspired::VariationalQuantumOptimizer;

let optimizer = VariationalQuantumOptimizer::<f64>::with_default_gain();
assert!((optimizer.learning_rate() - 0.1).abs() < 1e-12);

pub fn new(learning_rate: A) -> Self

Create a new VQE-inspired SPSA optimizer with the given learning rate.

pub fn with_perturbation(self, c: A) -> Self

Configure the SPSA perturbation magnitude c.

pub fn with_gain_decay(self, alpha: A, gamma: A) -> Self

Configure the SPSA decay exponents α (gain) and γ (perturbation).

pub fn with_stability(self, big_a: A) -> Self

Configure the SPSA stability offset A.

pub fn with_seed(self, seed: u64) -> Self

Seed the optimizer’s RNG.

pub fn alpha(&self) -> A

Returns the SPSA α exponent.

pub fn gamma(&self) -> A

Returns the SPSA γ exponent.

pub fn big_a(&self) -> A

Returns the SPSA stability offset A.

pub fn c(&self) -> A

Returns the SPSA perturbation numerator c.

pub fn step_count(&self) -> usize

Returns the current step counter k.

pub fn last_loss(&self) -> Option<A>

Returns the most recently observed loss value, if any.

pub fn seed(&self) -> u64

Returns the seed.

pub fn learning_rate(&self) -> A

Returns the learning rate. Inherent helper that mirrors the trait method Optimizer::get_learning_rate so callers do not need to disambiguate the dimension type.

pub fn set_lr(&mut self, learning_rate: A)

Set the learning rate. Inherent helper that mirrors the trait method.

pub fn a_k(&self, k: usize) -> A

SPSA gain a_k.

pub fn c_k(&self, k: usize) -> A

SPSA perturbation c_k.

pub fn reset(&mut self)

Reset the step counter and re-seed the RNG.

pub fn ansatz_factor(theta: A) -> A

Quantum-inspired ansatz factor cos²(θ_i / 2). Public for testing.

pub fn spsa_gradient<F>( &mut self, params: &Array1<A>, loss_fn: F, k: usize, ) -> Result<(Array1<A>, A, Array1<A>)>

where F: Fn(&Array1<A>) -> A,

Compute an SPSA gradient estimate using the supplied loss function.

Returns (gradient, c_k, delta).

pub fn step_from_loss<F>( &mut self, params: &Array1<A>, loss_fn: F, ) -> Result<Array1<A>>

where F: Fn(&Array1<A>) -> A,

Perform a loss-driven SPSA step.

This is the canonical VQE-style update that uses a closed-form loss rather than relying on user-provided gradients.

Trait Implementations

impl<A: Debug + Float + ScalarOperand + Debug> Debug for VariationalQuantumOptimizer<A>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<A, D> Optimizer<A, D> for VariationalQuantumOptimizer<A>

where A: Float + ScalarOperand + Debug + Send + Sync, D: Dimension,

fn step( &mut self, params: &Array<A, D>, gradients: &Array<A, D>, ) -> Result<Array<A, D>>

Updates parameters using the given gradients

fn get_learning_rate(&self) -> A

Gets the current learning rate

fn set_learning_rate(&mut self, learning_rate: A)

Sets a new learning rate

fn step_list( &mut self, params_list: &[&Array<A, D>], gradients_list: &[&Array<A, D>], ) -> Result<Vec<Array<A, D>>>

Updates multiple parameter arrays at once