Amplitude amplification tooling for Python
Build, inspect, profile, and validate quantum amplification workflows.
ampamp packages Grover search, fixed-point schedules, oracle construction,
variable-time models, QSVT/QSP helpers, diagnostics, transpilation profiling, and
backend validation behind a compact research API.
python3 -m pip install ampamp
from ampamp import GroverEngine
engine = GroverEngine(
n_qubits=6,
marked_indices=[10, 25],
)
qc = engine.construct_circuit(
iterations=engine.k_optimal,
)What Is In The Library
-
Grover Search
Standard amplitude-amplification circuits with phase oracles, diffusion operators, optimal-iteration estimates, and analytic success probabilities.
-
Oracle Construction
Build phase, bit-flip, or direct unitary oracle circuits from marked states, Boolean expression strings, or user-supplied unitary matrices.
-
Fixed-Point AA
Chebyshev-style fixed-point schedules and circuit synthesis for monotone amplification behavior.
-
Oblivious / FOQA
Ancilla preparation, block-encoding scaffolds, reflection helpers, fixed-point oblivious schedules, and recurrence simulation.
-
Distributed AA
Prefix/suffix partitioning for distributed search targets and symbolic local-oracle synthesis for node-local subproblems.
-
Variable-Time AA
Branch records, stopping-time statistics, success-mass calculations, asymptotic estimates, and staged-state examples.
-
QSVT / QSP
SU(2) QSP sequence evaluation and Chebyshev helpers for Jacobi-Anger and matrix-inverse polynomial synthesis.
-
Diagnostics
Auditors for subspace rotation, fixed-point schedules, block-encoding structure, distributed partitions, VTAA branches, and QSVT parity checks.
-
Transpilation
Staged compile metrics, routing statistics, basis translation, timing models, batch profiling, and hardware-cost scoring.
-
Backend Validation
Ideal/noisy simulator comparisons, total-variation-distance checks, noise presets, and optional JSONL validation logs.
-
Entanglement Count
Light and hard active-entangled-qubit profiling for Qiskit circuits.
Quick Start
Build and profile a Grover circuit:
from ampamp import GroverEngine, TranspilationProfiler, TranspilationProfileConfig
engine = GroverEngine(n_qubits=6, marked_indices=[10, 25])
qc = engine.construct_circuit(iterations=engine.k_optimal)
config = TranspilationProfileConfig(
coupling_map_edges=[[0, 1], [1, 2], [2, 3], [3, 4], [4, 5]],
)
metrics = TranspilationProfiler(config).profile_circuit(qc)
print(engine.k_optimal)
print(metrics["post_optimization_depth"])
print(metrics["final_cnots"])
Oracle Quick Start
ampamp supports the two oracle-entry modes used by most amplitude-amplification workflows:
- The user supplies a Boolean function or expression string, and the library constructs the oracle circuit.
- The user supplies a unitary matrix directly, and the library validates and wraps it as an oracle circuit.
import numpy as np
from ampamp import OracleBuilder, build_phase_oracle, build_unitary_oracle
formula_oracle = build_phase_oracle(
num_qubits=4,
formula_text="v0 & (v2 | v3)",
)
builder_oracle = OracleBuilder.from_formula(
num_qubits=4,
formula_text="v0 & (v2 | v3)",
).phase_oracle()
unitary_matrix = np.diag([1, 1, -1, 1])
matrix_oracle = build_unitary_oracle(unitary_matrix)
Repository Scope
This repository now focuses on the installable ampamp package, tests, and documentation. The previous implementation-comparison folders were moved out because they are scenario workflows rather than core library code:
Testing
Focused checks:
PYTHONPATH=src pytest tests/test_oracles.py
PYTHONPATH=src pytest tests/test_transpilation_module.py tests/test_transpilation_validation.py
Documentation
Serve this site locally:
Build it: