uniqc.algorithmics.circuits.amplitude_estimation module#

Quantum Amplitude Estimation (QAE) circuit.

uniqc.algorithmics.circuits.amplitude_estimation.amplitude_estimation_circuit(circuit, oracle, qubits, eval_qubits)[source]#

Apply Quantum Amplitude Estimation (QAE).

Estimates the probability a that a measurement of the state prepared by A|0⟩ yields a “good” outcome (as defined by the oracle).

Uses the canonical QPE-based construction:

  1. Prepare evaluation register in uniform superposition (H^{⊗m}).

  2. For each evaluation qubit at position i (LSB-first), apply 2^i controlled-Grover iterations on the search register.

  3. Apply inverse QFT on the evaluation register.

  4. Measure the evaluation register.

The search register is initialised with H^{⊗n} (uniform superposition) before the controlled-Grover operations.

Parameters:

  • circuit (Circuit) – Quantum circuit to operate on (mutated in-place).

  • oracle (Circuit) – Oracle circuit implementing the phase flip on marked states.

  • qubits (List[int]) – Qubit indices for the search register.

  • eval_qubits (List[int]) – Qubit indices for the evaluation (precision) register, in LSB-first order (eval_qubits[0] controls 2^0 = 1 Grover iteration, eval_qubits[1] controls 2^1 = 2, …).

Raises:

ValueError – Invalid parameters.

Return type:

None

Example

>>> from uniqc.circuit_builder import Circuit
>>> from uniqc.algorithmics.circuits import amplitude_estimation_circuit
>>> oracle = Circuit()
>>> oracle.z(0)
>>> c = Circuit()
>>> amplitude_estimation_circuit(
...     c, oracle, qubits=[3, 4], eval_qubits=[0, 1, 2]
... )
uniqc.algorithmics.circuits.amplitude_estimation.amplitude_estimation_result(counts, n_eval_qubits)[source]#

Estimate probability a from QAE measurement results.

Converts the most-frequent measurement outcome to an angle θ and computes a = sin²(θ).

The QAE phase relation is theta = pi * m / 2^(M+1) where m is the integer outcome and M = n_eval_qubits. The extra factor of two compared to the bare QPE formula comes from the fact that the Grover operator’s eigenphase is 2 theta rather than theta.

Parameters:

  • counts (dict) – Dictionary mapping measurement outcomes (bit-strings or integers) to frequencies/counts.

  • n_eval_qubits (int) – Number of evaluation qubits used in QAE.

Returns:

Estimated probability a ∈ [0, 1].

Return type:

float

uniqc.algorithmics.circuits.amplitude_estimation.grover_operator(circuit, oracle, qubits)[source]#

Apply one Grover iteration G = A · S₀ · A† · S_f.

Where:

  • S_f is the oracle (phase flip on marked states)

  • A† is the inverse of the state preparation

  • S₀ is the reflection about |0⟩

  • A is the state preparation

In the standard QAE formulation, A = H^{⊗n} (uniform superposition), and S_f is provided by the oracle circuit.

Parameters:

  • circuit (Circuit) – Quantum circuit to operate on (mutated in-place).

  • oracle (Circuit) – Oracle circuit implementing phase flip on target states. Must use the same qubit indices as qubits.

  • qubits (List[int]) – Qubit indices for the search register.

Return type:

None