Diagnostics

ampamp.diagnostics

Amplitude Amplification Diagnostics module.

Provides an extensive suite of auditors for verifying, benchmarking, and isolating quantum amplitude amplification boundaries, realistic hardware limits, and algorithms.

DistributedAuditor

Diagnostic suite for DQAA network stats, noise, and hardware compilation.

__init__(engine)

Initializes the DistributedAuditor.

Parameters:

Name	Type	Description	Default
engine	DQAAEngine	An instance of distributed.DQAAEngine.	required

audit_entanglement_obstruction(target_global)

Negative proof for external state decoherence.

Validates that cross-register entanglement destroys the local FPAA trajectory using DensityMatrix partial traces.

Parameters:

Name	Type	Description	Default
target_global	str	Global target mapping block identifier to entangle.	required

benchmark_nisq_noise(noise_model, shots=4096)

Compares Monolithic vs Distributed execution under hardware noise.

Parameters:

Name	Type	Description	Default
noise_model	object	Custom hardware noise proxy map simulation object.	required
shots	int	Sample pool bound for quantum measuring. Defaults to 4096.	4096

simulate_network_sifting(shots_per_node, sigma=4.0)

End-to-end classical master-node statistical sifting simulation.

Parameters:

Name	Type	Description	Default
shots_per_node	int	Local shots isolated per classical processing node.	required
sigma	float	Threshold variance tracking confidence check scalar. Defaults to 4.0.	4.0

verify_lucky_node_theorem(num_marked, trials=2000)

Runs Monte Carlo simulations to empirically verify the convexity guarantee.

Evaluates the property: \(\max_k a_k \ge a\).

Parameters:

Name	Type	Description	Default
num_marked	int	Number of active targets.	required
trials	int	Amount of iterations for stochastic averaging. Defaults to 2000.	2000

FOQAAuditor

Diagnostic laboratory for FOQA recurrence limits and boundaries.

__init__(engine)

Initializes the FOQAAuditor.

Parameters:

Name	Type	Description	Default
engine	FOQAEngine	A FOQAEngine instance.	required

audit_asymptotic_complexity(target_success=0.99)

Module 4: Runs \(\lambda\) sweeps to verify the -0.5 log-log slope.

Parameters:

Name	Type	Description	Default
target_success	float	Desired probability threshold bounds. Defaults to 0.99.	0.99

audit_damping_regimes(iterations=120, mizel_c=1.4)

Module 2: Sweeps under/over/critical damping behaviors.

Parameters:

Name	Type	Description	Default
iterations	int	Steps in the dynamic simulation. Defaults to 120.	120
mizel_c	float	Critical tuning parameter. Defaults to 1.4.	1.4

Returns:

Name	Type	Description
dict	dict	The simulated recurrence array maps for each damping regime.

audit_empty_database_paradox(iterations=50)

Module 6: Verifies strict suppression of false positives at \(\theta=0\).

Parameters:

Name	Type	Description	Default
iterations	int	Maximum depth to trace suppression guarantees. Defaults to 50.	50

Returns:

Type	Description
ndarray	np.ndarray: The array history of false positive suppression probabilities.

FPAAAuditor

Diagnostic suite for FPAA robustness and resource costs.

__init__(engine)

Initializes the FPAAAuditor.

Parameters:

Name	Type	Description	Default
engine	FixedPointEngine	An instance of the fixed_point.FixedPointEngine.	required

audit_passband(lambda_range=None)

Analyzes the 'Plateau' behavior where success prob stays near 1.

Parameters:

Name	Type	Description	Default
lambda_range	ndarray	Range of lambda values to sweep. Defaults to None.	None

estimate_ftqc_cost(synthesis_epsilon=0.001)

Calculates T-gate overhead for Clifford+T fault-tolerant architectures.

Parameters:

Name	Type	Description	Default
synthesis_epsilon	float	The target synthesis error bound. Defaults to 1e-3.	0.001

FundamentalLimitsAuditor

Diagnostic suite for hardware realism and theoretical algorithms limits.

Investigates subspace boundaries and open-system trajectories across all quantum amplitude amplification algorithms.

audit_ftqc_diffusion_scaling(n_min, n_max)

Compiles MCX diffusion to Clifford+T to record scaling metrics.

Parameters:

Name	Type	Description	Default
n_min	int	The minimum dimension complexity of the multi-control operation sweep limits.	required
n_max	int	The maximum dimension complexity of the target MCX operation boundaries.	required

audit_open_system_trajectory(n, k_max, phase_damp_1q, phase_damp_2q)

Simulates AA via Density Matrix and tracks trace-distance to the 2D plane.

Parameters:

Name	Type	Description	Default
n	int	System size configuration parameter.	required
k_max	int	Trajectory steps simulation iterations constraint.	required
phase_damp_1q	float	Simulated decoherence limit noise mapped as scaling 1-qubit error maps.	required
phase_damp_2q	float	Entanglement correlation scaling maps on two-qubit operators.	required

audit_phase_leakage(eps_oracle_deg, eps_diff_deg)

Tracks rank-growth under phase mismatch and analog control skew.

Parameters:

Name	Type	Description	Default
eps_oracle_deg	float	The angle mapping scale bounds defining skewed oracle boundaries.	required
eps_diff_deg	float	Extrema angular mappings limiting deviation within bounds.	required

audit_subspace_svd(n, k_max, rank_threshold=1e-12)

Constructs history matrix \(H\) and SVD-audits empirical rank.

Parameters:

Name	Type	Description	Default
n	int	The number of qubits mapping space size limits.	required
k_max	int	The limits defining maximum matrix trace width blocks.	required
rank_threshold	float	Precision defining limits to detect zero eigenvalue mappings. Defaults to 1e-12.	1e-12

GroverAuditor

Diagnostic suite for Grover's Algorithm.

Handles the 'Soufflé' problem, cloning barriers, and subspace verification.

__init__(engine)

Initializes the GroverAuditor.

Parameters:

Name	Type	Description	Default
engine	GroverEngine	An instance of the foundations.GroverEngine.	required

generate_souffle_heatmap(k_max, lambda_max, res=200) staticmethod

Vectorized analytic heatmap of the Soufflé Problem.

Parameters:

Name	Type	Description	Default
k_max	int	The maximum iteration depth.	required
lambda_max	float	The maximum solution density.	required
res	int	Resolution of the sweeping steps. Defaults to 200.	200

Returns:

Name	Type	Description
tuple	tuple	Output meshes \((K, L, Z)\) plotting the amplitude space.

run_cloning_test(max_k)

Empirical proof of the No-Cloning Theorem.

Measures purity collapse after a naive CNOT copy attempt.

Parameters:

Name	Type	Description	Default
max_k	int	Maximum number of iterations to apply the copying schema against.	required

Returns:

Name	Type	Description
tuple	tuple	Contains lists (purity_original, purity_cloned).

verify_subspace_rotation(max_k)

Audits the Invariant Subspace Theorem.

Verifies that \(|a|^2 + |b|^2 = 1.0\) throughout the rotation.

Parameters:

Name	Type	Description	Default
max_k	int	Maximum number of iterations to track.	required

Returns:

Name	Type	Description
dict	dict	Lists mapping standard amplitudes, purity, and success probability per step.

ObliviousAuditor

Diagnostic suite for verifying OAA and LCU block-encodings.

__init__(engine)

Initializes the ObliviousAuditor.

Parameters:

Name	Type	Description	Default
engine	ObliviousEngine	An instance of the oblivious.ObliviousEngine.	required

run_acid_test(num_states=10)

Verifies the 'Equivalence Theorem'.

Checks that OAA success probability is practically independent of the input state.

Parameters:

Name	Type	Description	Default
num_states	int	The number of independent initial states to test against. Defaults to 10.	10

verify_lcu_distance(actual_matrix, target_hamiltonian, alpha)

Measures \(||M_{TL} - H/\alpha||_F\) to verify Linear Combination of Unitaries accuracy.

Parameters:

Name	Type	Description	Default
actual_matrix	ndarray	The measured upper left unitary block matrix.	required
target_hamiltonian	ndarray	The intended target Hamiltonian representing scaling.	required
alpha	float	The linear normalization factor from LCU embedding.	required

Returns:

Name	Type	Description
float	float	The Frobenius norm separating the actual from the target operator.

QSVTAuditor

Diagnostic suite for QSVT hardware limits.

Tracks adversarial edge cases, robustness mapping bounds, and general operator calculus.

__init__(engine)

Expects an SU2QSPEngine instance.

Parameters:

Name	Type	Description	Default
engine	SU2QSPEngine	SU2QSPEngine mapping operator definitions.	required

audit_gibbs_catastrophe(degree)

Phase V: Exposes unitarity violations when fitting discontinuous targets.

Parameters:

Name	Type	Description	Default
degree	int	Expansion truncation bounds limit constraints.	required

audit_parity_scramble(dim)

Phase V: Demonstrates mixed-parity failure on non-Hermitian inputs.

Parameters:

Name	Type	Description	Default
dim	int	Evaluation subspace tracking map indices dimensions boundary configuration matrices.	required

audit_phase_quantization(degree, bit_depth)

Phase V: Simulates finite DAC bit-depth and tracks fidelity collapse.

Parameters:

Name	Type	Description	Default
degree	int	Series limits configuration variables space tracking limits.	required
bit_depth	int	Numeric constraints defining DAC step simulation maps.	required

audit_subnormalization_hubris(dim, target_sigma_max=2.5)

Phase V: Proves that artificially shrinking the block-encoding.

Shrinking factor \(\alpha\) creates non-PSD defect matrices, breaking unitary dilation.

Parameters:

Name	Type	Description	Default
dim	int	Bounding size definitions configuring tracking arrays space mapping operators.	required
target_sigma_max	float	Peak tolerance. Defaults to 2.5.	2.5

audit_unitarity_and_parity(phases, tolerance=1e-10)

Phase I: Validates \(P(x)\) against strict mathematical bounds.

Parameters:

Name	Type	Description	Default
phases	ndarray	Phase rotation map angles block defining polynomials.	required
tolerance	float	Maximum gap bounds allowed. Defaults to 1e-10.	1e-10

Returns:

Name	Type	Description
tuple	tuple	Two Boolean flags signaling if unitary constraints and parity constraints are met.

VTAAAuditor

Diagnostic suite for Variable-Time Amplitude Amplification.

__init__(engine)

Initializes the VTAAAuditor.

Parameters:

Name	Type	Description	Default
engine	VTAAEngine	An instance of variable_time.VTAAEngine.	required

sweep_cost_ratios(total_ps, t1, t2, t3)

Sweeps early-success ratio and compares VTAA to worst-case AA.

Parameters:

Name	Type	Description	Default
total_ps	float	Global targeted algorithmic success bounding ratio.	required
t1	float	Time threshold index mark 1.	required
t2	float	Time threshold index mark 2.	required
t3	float	Time threshold index mark 3.	required