spsa

Estimate gradients of parameterized quantum circuits using SPSA with Qiskit estimator and sampler primitives.

18|3|Updated Aug 14, 2026
One-click install
npx skills add https://github.com/unitarylab/quantum-practices --skill spsa-unitarylab
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: spsa
Source: https://github.com/unitarylab/quantum-practices/tree/main/algorithms/gradients/spsa
Command: npx skills add https://github.com/unitarylab/quantum-practices --skill spsa-unitarylab

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires numpy, qiskit, qiskit_algorithms, and includes scripts (resource) components.

What problem does it solve? Computing gradients of parameterized quantum circuits with many parameters is expensive when each parameter requires separate circuit evaluations. This Skill explains and demonstrates the SPSA (Simultaneous Perturbation Stochastic Approximation) method, which estimates full gradients using only 2 times batch_size circuit evaluations regardless of parameter count. ## Core Features & Use Cases - Estimator Gradients: Use Qiskit's SPSAEstimatorGradient to differentiate expectation values of observables with configurable epsilon, batch_size, and seed. - Sampler Gradients: Apply SPSASamplerGradient to compute gradients of output probability distributions per bitstring. - Manual Reference Implementation: A NumPy-based spsa_gradient function and solver class show the core perturbation logic for validation and reimplementation. - Use Case: When training a variational quantum algorithm with 50 parameters, use SPSA to estimate the full gradient vector with a fixed small number of circuit evaluations instead of 100+ parameter-shift evaluations. ## Quick Start Ask the assistant to explain or run the SPSA gradient estimation example on a two-qubit RY-CX circuit with the ZZ observable using Qiskit.

Frequently Asked Questions about spsa

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I compute quantum circuit gradients with SPSA in Qiskit?

Use SPSAEstimatorGradient with an estimator primitive, epsilon, batch_size, and seed, then call run with circuits, observables, parameter_values, and parameters. The result contains a gradients list with one NumPy array per circuit.

What is the difference between SPSAEstimatorGradient and SPSASamplerGradient?

SPSAEstimatorGradient differentiates expectation values of observables and returns gradient arrays, while SPSASamplerGradient works on sampled output distributions and returns per-bitstring gradient dictionaries. Both use the same random perturbation scheme.

How many circuit evaluations does SPSA need per gradient?

SPSA needs only 2 times batch_size circuit evaluations per gradient estimate, independent of the number of parameters. This makes it efficient for circuits with many parameters compared to parameter-shift rules.

How do epsilon and batch_size affect SPSA gradient accuracy?

Smaller epsilon reduces finite-difference bias but can let noise dominate, while larger batch_size reduces variance at the cost of more evaluations. Epsilon must be positive or a ValueError is raised.

Why does my SPSA gradient result vary between runs?

SPSA is stochastic because it samples random sign perturbation vectors. Set the seed parameter for reproducibility, and increase batch_size to reduce variance between estimates.