Copy page

• View as Markdown
• Open in Claude
• Open in ChatGPT
• Connect via MCP

iqae

eigenkit.algorithms.iqae

IQAE

Bases: BaseQuantumSolver

Iterative Quantum Amplitude Estimation (IQAE).

Estimates a = |⟨ψ₁|A|0⟩|² to an additive precision epsilon, with a failure probability of at most alpha. It uses the Grover operator Q = A S₀ A† S_ψ₁, built from the oracle A that you provide.

The oracle can be given in two forms:

• A PennyLane callable oracle(wires), which applies the circuit A in place. The last wire (wires[-1]) must be the ancilla qubit:

def my_oracle(wires):
    qml.RY(theta, wires=wires[0])
    qml.CNOT(wires=[wires[0], wires[-1]])

The matrix of the circuit is extracted internally with qml.matrix, so this form requires provider="pennylane" and the pennylane extra.

• A CircuitSpec, which works on any backend that supports the QubitUnitary, X, MCZ and Z gates. With a provider other than PennyLane, pass shot_mode="synthetic" or shot_mode="auto", because shot_mode="provider" works only with PennyLane.

Parameters:

Name	Type	Description	Default
epsilon	float	The additive precision to reach, that is, the half-width of the final confidence interval for a. It must be in (0, π/8).	required
alpha	float	The total failure probability. The algorithm applies a Bonferroni correction, so the confidence interval of each round is valid at level alpha / T, where T = ceil(log2(π / (8 * epsilon))) is the maximum number of rounds. It must be in (0, 1).	required
n_qubits	int	The total number of qubits, including the ancilla.	required
provider	ProviderSpec	The backend to use: a registered name ("numpy", "pennylane", "qiskit" and so on), a config instance, or a backend object. The default is "numpy", the built-in simulator.	'numpy'
n_shots	int	The number of measurement shots per round. With shot_mode="synthetic", which is used on analytic backends, it sets the size of a seeded binomial draw on top of the exact probability of the ancilla. With shot_mode="provider" or "auto", it is the number of samples per round on the hardware or simulator, unless the provider config sets its own shots, which takes precedence. For example, a device configured for 50 shots samples 50 times, whatever the value of n_shots. To control sampling on those backends, set shots on the provider config. The default is 100.	100
shot_mode	ShotMode	How the ancilla measurements are obtained. With "auto", the default, the provider's shot count is used when the backend config sets a finite shots, and synthetic binomial noise is used otherwise. "provider" always samples from the backend. "synthetic" always uses exact expectation values plus seeded binomial noise.	'auto'
min_ratio	float	The minimum ratio K_{i+1} / K_i between the Grover powers of consecutive rounds. It must be greater than 1.	2.0
random_state	int | None	The seed of the random number generator used for the shot noise. An integer gives reproducible results, and None uses a non-deterministic seed.	42

Example

import numpy as np
from eigenkit import CircuitBuilder
from eigenkit.algorithms import IQAE

# RY(pi/3) on the ancilla prepares an amplitude of sin^2(pi/6) = 0.25.
qc = CircuitBuilder(n_qubits=2)
qc.ry(np.pi / 3, qubit=1)
oracle = qc.build()

iqae = IQAE(epsilon=0.02, alpha=0.05, n_qubits=2, random_state=0)
result = iqae.solve(oracle)

print(result.estimation)           # 0.246
print(result.confidence_interval)  # (0.2407, 0.2513), which contains 0.25
print(result.n_oracle_calls)       # 2600

solve(oracle)

Estimate the amplitude a = |⟨ψ₁|A|0⟩|².

Parameters:

Name	Type	Description	Default
oracle	Callable | CircuitSpec	Either a PennyLane callable oracle(wires) that builds the state-preparation circuit A, or a CircuitSpec produced by CircuitBuilder. In both cases, the last qubit is treated as the ancilla.	required

Returns:

Type	Description
IQAEResult	An IQAEResult with the point estimate, the confidence interval and the resource counts.

Raises:

Type	Description
ValueError	If the selected provider does not support the gates that IQAE needs (QubitUnitary, X, MCZ and Z).

IQAEResult dataclass

Bases: ValueEquality

Outcome of a completed Iterative Quantum Amplitude Estimation (IQAE) run.

The result is read-only. Assigning to a field raises FrozenInstanceError, so a mistyped = (instead of ==) cannot change a result. This type holds no arrays, so nothing else needs protecting.

Results compare by value. They are not hashable, so that all result types behave in the same way: the types that hold arrays cannot be hashed both correctly and efficiently.

Attributes:

Name	Type	Description
estimation	float	The point estimate of the amplitude a.
confidence_interval	tuple[float, float]	The (lower, upper) Clopper-Pearson interval at the requested confidence level 1 - alpha.
n_rounds	int	The number of rounds that the run executed. It can also be read as n_iterations, the name that the other result types use.
n_oracle_calls	int	The total number of oracle calls over all rounds.
success	bool	Whether the interval reached the requested precision. This is the same test that ends the loop over rounds, and the one reported by the warning that the run did not converge. False means that the run stopped at max_rounds with an interval still wider than 2 * epsilon.

n_iterations property

The number of rounds, under the name that the other results use.

n_rounds is the name that IQAE uses, and it stays available. This property lets one loop read the number of iterations from any result.

Returns:

Type	Description
int	The number of rounds that the run executed.