Foundations

ampamp.foundations

Foundations for Quantum Amplitude Amplification.

This module provides basic classes and fundamental operations for standard Grover search and amplitude amplification algorithms.

GroverEngine

The core algebraic and circuit engine for Grover's Search.

Focuses on state synthesis and geometric calculations to amplify amplitudes of marked solution states optimally.

__init__(n_qubits, marked_indices)

Initializes the GroverEngine.

Parameters:

Name	Type	Description	Default
n_qubits	int	The number of qubits representing the problem space (\(N = 2^n\)).	required
marked_indices	list[int]	List indicating the integers representing the marked states in the problem subspace.	required

compute_success_prob(lambda_val, k) staticmethod

Analytic success probability calculation.

Computes the success probability \(P(k)\) after \(k\) Grover iterations given the solution density \(\lambda\). The probability formula is defined geometrically as \(P(k) = \sin^2((2k + 1) \theta / 2)\), where \(\theta = 2 \arcsin(\sqrt{\lambda})\).

Parameters:

Name	Type	Description	Default
lambda_val	float	The solution density fraction, \(M/N\).	required
k	int	The number of Grover iterations applied.	required

Returns:

Name	Type	Description
float	float	The probability of measuring a marked state.

Raises:

Type	Description
ValueError	If lambda_val is not within the inclusive bound [0, 1].

construct_circuit(iterations)

Synthesizes the full Grover circuit.

Links the oracle operator and diffusion operator for \(k\) iterations starting from the full uniformly mixed amplitude distribution \(|s\rangle\).

Parameters:

Name	Type	Description	Default
iterations	int	The amount of generalized Grover operator iterations to sequentially run \(Q = -A S_0 A^{-1} S_f\).	required

Returns:

Name	Type	Description
QuantumCircuit	QuantumCircuit	The synthesized Grover standard algorithm sequence.

get_diffusion()

Generates the Grover Diffusion operator (Inversion about mean).

Returns:

Name	Type	Description
QuantumCircuit	QuantumCircuit	An n-qubit circuit corresponding to \(2 |s\rangle\langle s| - I\),
	QuantumCircuit	where \(|s\rangle\) is the equal superposition state.

get_oracle()

Generates a Phase Oracle for the marked states.

Constructs a standard quantum phase oracle gate circuit that flips the sign of the marked states while leaving orthogonal unmarked states alone.

Returns:

Name	Type	Description
QuantumCircuit	QuantumCircuit	An n-qubit oracle circuit flipping the phase of marked states.