IR Module (Informational Relativity)#

The IR module provides Informational Relativity integration for quantum simulation, enabling pre-computation regime diagnosis and coherence-based optimization.

Version: 1.1.0

Overview#

The IR module implements the key insight from Informational Relativity: regime determines representation, not the other way around. Before running quantum algorithms, analyze the problem structure to:

Determine if the structure is observable (IR regime) or hidden (AIR regime)
Decide if grouping/optimization will help
Choose appropriate representation and algorithm parameters

Key Concepts#

Observability Regimes#

The module classifies problems into three regimes based on coherence R̄:

IR (Informational Relativity): R̄ > e^-2 ≈ 0.135 - Structure is observable
TRANSITION: R̄ ≈ e^-2 - Near the GO/NO-GO boundary
AIR (Anti-IR): R̄ < e^-2 - Structure is globally hidden

GO/NO-GO Classification#

The physics-derived e^-2 threshold (≈0.135) provides a universal boundary:

GO: Coherence above threshold → Quantum methods likely effective
NO-GO: Coherence below threshold → Classical methods may be better

Regime Analyzer#

Pre-computation diagnosis for quantum problems.

atlas_q.ir_enhanced.analyze_state_regime(amplitudes)[source]#

Analyze quantum state observability regime.

For quantum states, the response field IS the amplitude structure: - χ_i = |ψ_i| (amplitude magnitude) - θ_i = arg(ψ_i) (amplitude phase)

Args:: amplitudes: Complex quantum state amplitudes
Returns:: RegimeAnalysis for the quantum state

atlas_q.ir_enhanced.analyze_hamiltonian_regime(coefficients, pauli_strings=None, gradient_magnitudes=None, gradient_phases=None)[source]#

Analyze Hamiltonian observability regime BEFORE running VQE.

This is the key function for pre-computation regime diagnosis.

IR L8 (Placement Principle): We compute coherence on the RESPONSE FIELD, not on the Hamiltonian coefficients or measurement outcomes.

For VQE, the response field is the parameter gradient landscape: - χ_i = |∂E/∂θ_i| (gradient magnitude) - θ_i = arg(∂E/∂θ_i) (gradient phase/direction)

If gradients not available, we estimate from Hamiltonian structure.

Args:

coefficients: Hamiltonian term coefficients pauli_strings: Pauli strings for structure analysis gradient_magnitudes: Optional actual gradient magnitudes (preferred) gradient_phases: Optional actual gradient phases (preferred)

Returns:

RegimeAnalysis with complete regime classification

Example:

>>> coeffs = np.array([1.0, 0.5, -0.3, 0.2])
>>> analysis = analyze_hamiltonian_regime(coeffs)
>>> if analysis.regime == ObservabilityRegime.AIR:
...     print("Warning: Structure globally hidden")
...     print(f"Recommended: {analysis.recommended_representation.value}")

atlas_q.ir_enhanced.analyze_mps_bond_regime(singular_values, site_index=0, decoherence_rate=0.05, initial_coherence=1.0)[source]#

Analyze MPS bond observability regime for truncation decisions.

Uses IR L5 (Exponential Decoherence): R̄(D) = R₀ e^(-αD)

Args:: singular_values: SVD singular values at this bond site_index: Distance from preparation (D in L5) decoherence_rate: Decay rate α initial_coherence: Initial coherence R₀
Returns:: RegimeAnalysis for truncation decision

atlas_q.ir_enhanced.predict_quantum_advantage(analysis, n_qubits, classical_hardware_factor=1000000000.0)[source]#

Predict whether quantum advantage exists for this problem.

Uses IR insight: If structure is in AIR regime and problem is large, quantum may have advantage. If in IR regime, classical simulation works.

Args:: analysis: Pre-computed regime analysis n_qubits: Problem size classical_hardware_factor: Classical computation speed
Returns:: (quantum_advantage_exists, explanation)

atlas_q.ir_enhanced.should_use_ir_grouping(analysis)[source]#

Determine if IR measurement grouping will help based on regime analysis.

Args:: analysis: Pre-computed regime analysis
Returns:: (should_use, reason): Whether to use IR grouping and why

Classes#

class atlas_q.ir_enhanced.regime_analyzer.ObservabilityRegime(value)[source]#

Bases: Enum

IR observability regime classification.

IR = 'ir'#

TRANSITION = 'transition'#

AIR = 'air'#

class atlas_q.ir_enhanced.regime_analyzer.RegimeAnalysis(regime, coherence, variance, recommended_representation, representation_cost, is_classically_tractable, structure_observable, spectral_gap=None, dominant_modes=None, warning=None)[source]#

Bases: object

Complete IR regime analysis result.

This should be computed BEFORE running any quantum algorithm. It determines whether the problem is tractable and which representation to use.

Attributes:: regime: IR/Transition/AIR classification coherence: Response field coherence R̄ variance: Circular variance V_φ recommended_representation: Which R to use representation_cost: Estimated cost scaling is_classically_tractable: Whether classical simulation is feasible structure_observable: Whether structure can be observed warning: Any warnings about the analysis

Attributes:

dominant_modes
spectral_gap
warning

regime: ObservabilityRegime#

coherence: float#

variance: float#

recommended_representation: RepresentationType#

representation_cost: str#

is_classically_tractable: bool#

structure_observable: bool#

spectral_gap: float | None = None#

dominant_modes: int | None = None#

warning: str | None = None#

class atlas_q.ir_enhanced.regime_analyzer.RepresentationType(value)[source]#

Bases: Enum

Representation strategy based on regime.

DIRECT = 'direct'#

SPECTRAL_LIFTING = 'spectral_lifting'#

EXPENSIVE = 'expensive'#

Spectral Lifting#

Full M_ij relational matrix analysis for structure detection.

atlas_q.ir_enhanced.compute_relational_matrix(responses, phases)[source]#

Compute IR relational spectral lifting matrix.

M_ij = χ_i * χ_j * cos(θ_i - θ_j)

This matrix encodes pairwise phase relationships weighted by response magnitudes. The dominant eigenvector localizes at structurally coherent regions, enabling identification of hidden global structure.

Args:

responses: Response field magnitudes χ_i (n-dimensional array) phases: Response field phases θ_i (n-dimensional array, radians)

Returns:

M: n×n relational spectral lifting matrix

Example:

>>> # Coherent system: all phases aligned
>>> responses = np.array([1.0, 0.9, 0.8, 0.7])
>>> phases = np.array([0.0, 0.1, 0.05, 0.02])  # Nearly aligned
>>> M = compute_relational_matrix(responses, phases)
>>> # M will have high values (positive correlation)

References:

IR Paper Equation 7

atlas_q.ir_enhanced.compute_relational_matrix_from_amplitudes(amplitudes)[source]#

Compute relational matrix directly from complex amplitudes.

Convenience function that extracts magnitudes and phases from complex amplitudes and builds the relational matrix.

Args:: amplitudes: Complex amplitude array
Returns:: M: Relational spectral lifting matrix

atlas_q.ir_enhanced.extract_structure_modes(M, top_k=5, localization_threshold=0.1)[source]#

Extract dominant eigenmodes encoding global structure.

The dominant eigenvector of M localizes at structurally coherent regions, enabling identification of hidden structure invisible to pointwise statistics.

Args:

M: Relational spectral lifting matrix (n×n) top_k: Number of dominant modes to extract localization_threshold: Threshold for structure localization (|v_i|² > threshold)

Returns:

eigenvalues: Top-k eigenvalues (descending order) eigenvectors: Top-k eigenvectors (columns) structure_indices: Indices where dominant eigenvector localizes

Example:

>>> M = compute_relational_matrix(responses, phases)
>>> eigenvalues, eigenvectors, structure_idx = extract_structure_modes(M, top_k=3)
>>> print(f"Dominant eigenvalue: {eigenvalues[0]:.4f}")
>>> print(f"Structure localized at indices: {structure_idx}")

atlas_q.ir_enhanced.spectral_grouping(items, responses, phases, n_groups=5, min_group_size=1)[source]#

Group items by spectral coherence structure.

Uses the dominant eigenvectors of the relational matrix to identify coherent clusters for optimal grouping.

Algorithm:

Compute relational matrix M
Extract dominant eigenvectors
Cluster items by eigenvector components (k-means in eigenvector space)

Args:

items: List of items to group (e.g., Pauli strings, parameters) responses: Response field magnitudes for each item phases: Response field phases for each item n_groups: Target number of groups min_group_size: Minimum items per group

Returns:

List of groups, where each group is a list of indices into items

atlas_q.ir_enhanced.spectral_lifting_analysis(responses, phases, top_k=5, localization_threshold=0.1)[source]#

Complete spectral lifting analysis for coherence structure identification.

Combines matrix construction, eigendecomposition, and structure identification into a single analysis pipeline.

Args:: responses: Response field magnitudes χ_i phases: Response field phases θ_i (radians) top_k: Number of dominant modes to extract localization_threshold: Threshold for structure localization
Returns:: SpectralLiftingResult with full analysis

atlas_q.ir_enhanced.spectral_lifting_from_amplitudes(amplitudes, top_k=5, localization_threshold=0.1)[source]#

Spectral lifting analysis directly from complex amplitudes.

Convenience function for quantum states represented as amplitude vectors.

Args:: amplitudes: Complex quantum state amplitudes top_k: Number of dominant modes to extract localization_threshold: Threshold for structure localization
Returns:: SpectralLiftingResult with full analysis

atlas_q.ir_enhanced.coherent_structure_score(responses, phases, e2_threshold=0.135)[source]#

Compute a coherent structure score and regime classification.

Uses spectral lifting to determine: - IR regime (R̄ > e^-2): Structure directly observable - AIR regime (R̄ < e^-2): Structure locally detectable but globally hidden

Args:: responses: Response field magnitudes phases: Response field phases e2_threshold: e^-2 threshold (default: 0.135)
Returns:: score: Spectral coherence score (0-1) is_ir_regime: True if in IR regime (structure observable) regime_description: Human-readable regime description

class atlas_q.ir_enhanced.SpectralLiftingResult(M, eigenvalues, eigenvectors, spectral_coherence, structure_indices, spectral_gap)[source]#

Bases: object

Result of spectral lifting analysis.

Attributes:: M: Relational spectral lifting matrix M_ij eigenvalues: Eigenvalues sorted in descending order eigenvectors: Corresponding eigenvectors (columns) spectral_coherence: Coherence from dominant eigenmode concentration structure_indices: Indices of structurally coherent elements spectral_gap: Gap ratio between first and second eigenvalues

M: ndarray#

eigenvalues: ndarray#

eigenvectors: ndarray#

spectral_coherence: float#

structure_indices: ndarray#

spectral_gap: float#

VQE Grouping#

Coherence-based Pauli term grouping for VQE (4× circuit reduction).

atlas_q.ir_enhanced.ir_hamiltonian_grouping(coefficients, pauli_strings=None, total_shots=10000, max_group_size=5, gradient_magnitudes=None, gradient_phases=None)[source]#

Complete IR-enhanced Hamiltonian grouping for VQE.

Main entry point for ATLAS-Q integration.

NEW IN v0.8.0: Regime analysis BEFORE grouping decision. If structure is in AIR regime (R̄ < e^-2), grouping won’t help because the structure is globally hidden.

Parameters:

coefficients (np.ndarray) – Hamiltonian term coefficients
pauli_strings (List[str], optional) – Pauli strings (e.g., [“XYZI”, “IZXY”, …])
total_shots (int, optional) – Total measurement budget (default: 10000)
max_group_size (int, optional) – Maximum terms per group (default: 5)
gradient_magnitudes (np.ndarray, optional) – Actual gradient magnitudes for L8-correct coherence (preferred)
gradient_phases (np.ndarray, optional) – Actual gradient phases for L8-correct coherence (preferred)

Returns:

Complete grouping result with variance reduction and regime info

Return type:

GroupingResult

Examples

>>> # Simple usage with coefficient array
>>> coeffs = np.array([1.5, -0.8, 0.3, -0.2, 0.1])
>>> result = ir_hamiltonian_grouping(coeffs, total_shots=1000)
>>> print(f"Variance reduction: {result.variance_reduction:.1f}×")
>>> print(f"Method: {result.method}")  # Now includes regime info

atlas_q.ir_enhanced.estimate_pauli_coherence_matrix(coefficients, pauli_strings=None, method='exponential')[source]#

Estimate coherence matrix for Pauli terms.

Uses heuristic based on Pauli string structure: - Terms with overlapping support are correlated - Terms with many shared qubits have higher correlation

Parameters:

coefficients (np.ndarray) – Hamiltonian term coefficients
pauli_strings (List[str], optional) – Pauli strings like “XXYZI” (if None, uses coefficient-based estimate)
method (str, optional) – ‘exponential’ or ‘simple’

Returns:

Estimated correlation matrix Σ of shape (n_terms, n_terms)

Return type:

np.ndarray

Notes

This is a simplified heuristic for ATLAS-Q integration. Full IR uses modular sequence analysis (see IR T6-C1).

atlas_q.ir_enhanced.group_by_variance_minimization(Sigma, coefficients, max_group_size=5, pauli_strings=None, check_commutativity=True)[source]#

Group Hamiltonian terms to minimize measurement variance.

Uses greedy algorithm from IR experiment T6-C1: 1. Start with highest-magnitude term 2. Greedily add COMMUTING terms that minimize Q_GLS increase 3. Repeat until all terms grouped

Enhancement: Commutativity-aware grouping (10-50× additional improvement)

Parameters:

Sigma (np.ndarray) – Coherence/correlation matrix (n_terms × n_terms)
coefficients (np.ndarray) – Hamiltonian coefficients
max_group_size (int, optional) – Maximum terms per group (default: 5)
pauli_strings (Optional[List[str]], optional) – Pauli strings for commutativity checking (if None, no checking)
check_commutativity (bool, optional) – Whether to enforce commutativity constraints (default: True)

Returns:

List of groups, where each group is a list of term indices

Return type:

List[List[int]]

Notes

Validated in IR T6-C1: achieves 2350× variance reduction With commutativity: 10-50× additional improvement expected

atlas_q.ir_enhanced.allocate_shots_neyman(Sigma, coefficients, groups, total_shots)[source]#

Allocate measurement shots using Neyman allocation.

Neyman allocation minimizes total variance under fixed budget: m_g ∝ sqrt(Q_g) where Q_g is the variance of group g

Parameters:

Sigma (np.ndarray) – Coherence matrix
coefficients (np.ndarray) – Hamiltonian coefficients
groups (List[List[int]]) – Term groupings
total_shots (int) – Total measurement budget

Returns:

Shots allocated to each group

Return type:

np.ndarray

atlas_q.ir_enhanced.compute_Q_GLS(Sigma_g, c_g)[source]#

Compute Q_GLS = (c’Σ^(-1)c)^(-1) for a group.

This is the variance constant for GLS (Generalized Least Squares) estimation. Lower Q_GLS = lower variance for that group.

Parameters:

Sigma_g (np.ndarray) – Correlation matrix for group (size: len(group) × len(group))
c_g (np.ndarray) – Coefficients for group

Returns:

Q_GLS variance constant

Return type:

float

atlas_q.ir_enhanced.pauli_commutes(pauli1, pauli2)[source]#

Check if two Pauli strings commute.

Two Pauli operators commute if they anti-commute at an even number of positions.

Anti-commuting pairs: (X,Y), (Y,Z), (Z,X) and their reverses Commuting pairs: (I,*), (X,X), (Y,Y), (Z,Z)

Parameters:

pauli1 (str) – First Pauli string (e.g., “XXYZI”)
pauli2 (str) – Second Pauli string (e.g., “IXYZZ”)

Returns:

True if the Pauli operators commute, False otherwise

Return type:

bool

Examples

>>> pauli_commutes("XX", "XX")
True
>>> pauli_commutes("XY", "YX")
False
>>> pauli_commutes("XI", "IX")
True
>>> pauli_commutes("XY", "ZI")
True  # Anti-commute at 1 position (odd) → don't commute... wait, let me recalculate

Notes

The commutativity rule for Pauli operators: - [P, Q] = 0 (commute) if anti-commute count is even - {P, Q} = 0 (anti-commute) if anti-commute count is odd

This is critical for simultaneous measurement - only commuting Pauli operators can be measured in the same quantum circuit.

atlas_q.ir_enhanced.check_group_commutativity(group, pauli_strings)[source]#

Check if all Pauli operators in a group mutually commute.

Parameters:

group (List[int]) – Indices of Pauli terms in the group
pauli_strings (List[str]) – All Pauli strings

Returns:

True if all pairs in the group commute

Return type:

bool

Examples

>>> paulis = ["XX", "YY", "ZZ", "XI"]
>>> check_group_commutativity([0, 3], paulis)  # XX and XI
True
>>> check_group_commutativity([0, 1], paulis)  # XX and YY
False

class atlas_q.ir_enhanced.GroupingResult(groups, shots_per_group, variance_reduction, method)[source]#

Bases: object

Result from IR Hamiltonian grouping.

groups#

List of term groups (indices into Hamiltonian)

Type:: List[List[int]]

shots_per_group#

Optimal shot allocation for each group

Type:: np.ndarray

variance_reduction#

Variance reduction factor vs naive grouping

Type:: float

method#

Grouping method used

Type:: str

groups: List[List[int]]#

shots_per_group: ndarray#

variance_reduction: float#

method: str#

Period Finding Enhancement#

IR preprocessing for quantum period estimation (42% shot reduction).

atlas_q.ir_enhanced.ir_enhanced_period_finding(a, N, ir_confidence_threshold=0.8, qpe_shots_baseline=1000, shot_reduction_factor=0.35, **ir_kwargs)[source]#

Hybrid IR-QPE period finding with shot reduction.

Uses IR classical preprocessing to reduce quantum measurements. Falls back to QPE if IR confidence is insufficient.

Parameters:

a (int) – Base for period finding
N (int) – Modulus
ir_confidence_threshold (float, optional) – Confidence threshold to accept IR result (default: 0.8) Higher = more conservative, more QPE usage
qpe_shots_baseline (int, optional) – Baseline QPE shots if no IR preprocessing (default: 1000)
shot_reduction_factor (float, optional) – Expected shot reduction (default: 0.35 = 35%) IR demonstrated 29-42%, using conservative 35%
**ir_kwargs – Additional arguments for ir_preprocess_period

Returns:

Complete result with period, confidence, and diagnostic info

Return type:

IRPeriodResult

Examples

>>> result = ir_enhanced_period_finding(7, 15)
>>> print(f"Period: {result.period}, Shots saved: {result.shots_saved}")
Period: 4, Shots saved: 350

Notes

Validated performance (IR T6-A2): - Mean reduction: 12.7 → 9.0 shots (29%) - Median reduction: 12.0 → 7.0 shots (42%) - Valid regime: N ≲ 50

atlas_q.ir_enhanced.ir_preprocess_period(a, N, length=4096, num_bases=16, zp=16, top_k=5)[source]#

IR classical preprocessing for period finding.

Uses coherent averaging across multiple bases to identify period candidates without quantum measurements.

Parameters:

a (int) – Base for period finding (a^r ≡ 1 mod N)
N (int) – Modulus
length (int, optional) – Sequence length (default: 4096) IR achieves +5.87 dB/doubling
num_bases (int, optional) – Number of bases to average (default: 16) IR achieves +3.0 dB/doubling
zp (int, optional) – Zero-padding factor (default: 16)
top_k (int, optional) – Number of top candidates (default: 5)

Returns:

candidates (List[Tuple[int, float]]) – List of (period, confidence) sorted by confidence
coherence (float) – IR coherence metric

Return type:

Tuple[List[Tuple[int, float]], float]

Notes

IR regime validity: - Works best for N ≲ 50 (validated range) - 29-42% shot reduction demonstrated - Professional-grade SNR: 36-58 dB

atlas_q.ir_enhanced.estimate_shot_reduction(N, coherence, num_candidates)[source]#

Estimate expected quantum shot reduction from IR preprocessing.

Based on validated IR experiment T6-A2.

Parameters:

N (int) – Modulus size
coherence (float) – IR coherence metric
num_candidates (int) – Number of IR candidates

Returns:

Expected shot reduction factor (0.29-0.42 validated)

Return type:

float

Notes

Reduction depends on: - N size: Better for N ≲ 50 - Coherence: Higher C → better reduction - Candidate quality: Fewer candidates → more confident

Core Functions#

atlas_q.ir_enhanced.multiplicative_order(a, N, max_iter=10000)[source]#

Compute multiplicative order of a modulo N.

Finds smallest r > 0 such that a^r ≡ 1 (mod N).

Parameters:

a (int) – Base element
N (int) – Modulus
max_iter (int, optional) – Maximum iterations (default: 10000)

Returns:

Order r, or None if gcd(a, N) != 1

Return type:

int or None

Examples

>>> multiplicative_order(7, 15)
4
>>> multiplicative_order(2, 15)
4

atlas_q.ir_enhanced.compute_averaged_spectrum(N, bases, x0, length, zp=16, window='hann')[source]#

Compute coherently averaged power spectrum across multiple bases.

CRITICAL: Performs coherent averaging by summing complex FFTs before squaring. This preserves phase relationships and enables SNR scaling.

Coherent: |Σ U_m / M|² → SNR scales as √M (validated) Incoherent: Σ|U_m|²/M → No SNR gain

Parameters:

N (int) – Modulus
bases (List[int]) – List of M bases with same multiplicative order
x0 (int) – Starting seed (typically 1)
length (int) – Sequence length before zero-padding
zp (int, optional) – Zero-padding factor (default: 16)
window (str, optional) – Window function: ‘hann’, ‘hamming’, ‘blackman’, ‘none’ (default: ‘hann’)

Returns:

Coherently averaged power spectrum of shape (length * zp,)

Return type:

np.ndarray

Notes

IR achieves: - +5.87 dB per doubling of length L (validated in E16) - +3.0 dB per doubling of bases M (limited by phase incoherence) - Professional-grade SNR: 36-58 dB

atlas_q.ir_enhanced.find_period_candidates(spectrum, N, top_k=10, min_snr_db=10.0)[source]#

Extract period candidates from IR spectrum.

Identifies harmonic peaks in the spectrum and infers potential periods. Uses CFAR detection with validated threshold α=4.0.

Parameters:

spectrum (np.ndarray) – Power spectrum from compute_averaged_spectrum
N (int) – Modulus (upper bound on period)
top_k (int, optional) – Number of top candidates to return (default: 10)
min_snr_db (float, optional) – Minimum SNR threshold in dB (default: 10.0)

Returns:

List of (period, confidence) tuples, sorted by confidence

Return type:

List[Tuple[int, float]]

Notes

Uses CFAR (Constant False Alarm Rate) detection validated in IR: - Optimal α=4.0 (99.9% precision, 100% recall) - Sub-bin accuracy: μ=0.28 bins - False alarm rate: P_FA ≤ 0.01

QAOA Grouping#

Edge-based cost operator grouping for QAOA.

atlas_q.ir_enhanced.ir_qaoa_grouping(weights, edges, total_shots=10000, max_group_size=10, coherence_method='exponential')[source]#

IR-enhanced grouping for QAOA MaxCut Hamiltonians.

Automatically groups commuting edges and allocates shots optimally.

Parameters:

weights (np.ndarray) – Edge weights from MaxCut Hamiltonian
edges (List[Tuple[int, int]]) – Graph edges (node pairs)
total_shots (int) – Total measurement budget
max_group_size (int) – Maximum edges per group
coherence_method (str) – “exponential” or “geometric”

Returns:

Grouping strategy with shot allocation and variance reduction

Return type:

QAOAGroupingResult

Examples

>>> # Triangle graph
>>> weights = np.array([1.0, 1.0, 1.0])
>>> edges = [(0, 1), (1, 2), (0, 2)]
>>> result = ir_qaoa_grouping(weights, edges, total_shots=10000)
>>> print(f"Groups: {result.groups}")
>>> print(f"Variance reduction: {result.variance_reduction:.2f}×")

atlas_q.ir_enhanced.edges_commute(edge1, edge2)[source]#

Check if two ZiZj terms commute.

Two ZiZj terms commute if they don’t share any qubits.

Parameters:

edge1 (Tuple[int, int]) – First edge (i, j)
edge2 (Tuple[int, int]) – Second edge (k, l)

Returns:

True if edges can be measured simultaneously

Return type:

bool

Examples

>>> edges_commute((0, 1), (2, 3))  # No shared qubits
True
>>> edges_commute((0, 1), (1, 2))  # Share qubit 1
False
>>> edges_commute((0, 1), (0, 2))  # Share qubit 0
False

atlas_q.ir_enhanced.check_group_commutativity_edges(group, edges)[source]#

Check if all edges in a group mutually commute.

Parameters:

group (List[int]) – Indices of edges to check
edges (List[Tuple[int, int]]) – List of all edges

Returns:

True if all pairs in group commute

Return type:

bool

atlas_q.ir_enhanced.estimate_edge_coherence_matrix(weights, edges, method='exponential')[source]#

Estimate coherence matrix for graph edges.

Coherence captures correlation between edge measurements based on: - Shared vertices (higher correlation if edges share qubits) - Weight similarity (similar weights → similar variance)

Parameters:

weights (np.ndarray) – Edge weights (MaxCut coefficients)
edges (List[Tuple[int, int]]) – Graph edges
method (str) – “exponential” (weight-based) or “geometric” (topology-based)

Returns:

Sigma – Coherence/correlation matrix

Return type:

np.ndarray, shape (n_edges, n_edges)

atlas_q.ir_enhanced.group_edges_by_commutativity(Sigma, weights, edges, max_group_size=10)[source]#

Group edges by commutativity constraint with variance minimization.

Greedy algorithm: 1. Start with highest-weight edge 2. Add commuting edges that minimize Q_GLS increase 3. Repeat until all edges grouped

Parameters:

Sigma (np.ndarray) – Coherence matrix
weights (np.ndarray) – Edge weights
max_group_size (int) – Maximum edges per group
edges (List[Tuple[int, int]]) – Graph edges

Returns:

groups – Edge groupings

Return type:

List[List[int]]

class atlas_q.ir_enhanced.QAOAGroupingResult(groups, shots_per_group, variance_reduction, method, n_edges, n_groups)[source]#

Bases: object

Result of QAOA Hamiltonian grouping

groups: List[List[int]]#

shots_per_group: ndarray#

variance_reduction: float#

method: str#

n_edges: int#

n_groups: int#

Gradient Grouping#

Parameter shift optimization with coherence.

atlas_q.ir_enhanced.ir_gradient_grouping(gradient_estimates=None, n_params=None, total_shots=10000, max_group_size=10, coherence_method='empirical')[source]#

IR-enhanced grouping for gradient estimation in variational algorithms.

Automatically groups parameters with correlated gradients and allocates shots optimally.

Parameters:

gradient_estimates (np.ndarray, optional, shape (n_samples, n_params)) – Initial gradient samples for coherence estimation If None, uses local structure assumption
n_params (int, optional) – Number of parameters (required if gradient_estimates is None)
total_shots (int) – Total measurement budget for gradient computation
max_group_size (int) – Maximum parameters per group
coherence_method (str) – “empirical” (data-driven) or “local” (circuit structure)

Returns:

Grouping strategy with shot allocation and variance reduction

Return type:

GradientGroupingResult

Examples

>>> # With initial gradient samples
>>> gradients = np.random.randn(100, 50)  # 100 samples, 50 parameters
>>> result = ir_gradient_grouping(gradients, total_shots=10000)
>>> print(f"Groups: {result.groups}")
>>> print(f"Variance reduction: {result.variance_reduction:.2f}×")

>>> # Without samples (local structure)
>>> result = ir_gradient_grouping(n_params=50, total_shots=10000, coherence_method="local")

atlas_q.ir_enhanced.parameter_shift_gradient_ir(cost_function, params, grouping=None, shift=0.7853981633974483, auto_group=True)[source]#

Compute gradient using parameter-shift rule with IR grouping.

Standard parameter-shift:: ∂E/∂θᵢ = [E(θ + sᵢ) - E(θ - sᵢ)] / 2

IR enhancement: - Groups parameters with correlated gradients - Allocates shots optimally per group - Reduces total measurements

Parameters:

cost_function (Callable) – Function to differentiate: θ → E(θ)
params (np.ndarray) – Current parameter values
grouping (GradientGroupingResult, optional) – Pre-computed grouping (if None, auto-compute)
shift (float) – Parameter shift amount (default: π/4)
auto_group (bool) – Automatically compute grouping if not provided

Returns:

gradient (np.ndarray) – Gradient vector ∂E/∂θ
grouping (GradientGroupingResult, optional) – Grouping used (for reuse in subsequent iterations)

Return type:

Tuple[ndarray, GradientGroupingResult | None]

Examples

>>> def cost_fn(theta):
...     # Your VQE/QAOA cost function
...     return compute_energy(theta)
>>>
>>> theta = np.random.randn(50)
>>> grad, grouping = parameter_shift_gradient_ir(cost_fn, theta)
>>>
>>> # Reuse grouping for next iteration
>>> theta_new = theta - 0.01 * grad
>>> grad_new, _ = parameter_shift_gradient_ir(cost_fn, theta_new, grouping=grouping)

atlas_q.ir_enhanced.estimate_gradient_coherence_matrix(gradient_estimates, method='empirical')[source]#

Estimate coherence matrix for gradient parameters.

Uses empirical correlation from gradient samples or analytical structure.

Parameters:

gradient_estimates (np.ndarray, shape (n_samples, n_params)) – Gradient samples from initial measurements
method (str) – “empirical” (data-driven) or “local” (circuit structure)

Returns:

Sigma – Coherence/correlation matrix

Return type:

np.ndarray, shape (n_params, n_params)

atlas_q.ir_enhanced.group_parameters_by_variance(Sigma, gradient_magnitudes, max_group_size=10)[source]#

Group parameters by gradient variance minimization.

Greedy algorithm: 1. Start with highest-magnitude gradient 2. Add correlated parameters that minimize variance increase 3. Repeat until all parameters grouped

Parameters:

Sigma (np.ndarray) – Coherence matrix
gradient_magnitudes (np.ndarray) – Estimated gradient magnitudes (for prioritization)
max_group_size (int) – Maximum parameters per group

Returns:

groups – Parameter groupings

Return type:

List[List[int]]

class atlas_q.ir_enhanced.GradientGroupingResult(groups, shots_per_group, variance_reduction, method, n_params, n_groups)[source]#

Bases: object

Result of gradient parameter grouping

groups: List[List[int]]#

shots_per_group: ndarray#

variance_reduction: float#

method: str#

n_params: int#

n_groups: int#

TDVP Observables#

Real-time coherence tracking for time evolution.

atlas_q.ir_enhanced.ir_tdvp_observable_grouping(observable_paulis, observable_coeffs, total_shots=10000, max_group_size=10)[source]#

IR-enhanced grouping for TDVP observable measurements.

Groups commuting observables and allocates shots optimally.

Parameters:

observable_paulis (List[str]) – Pauli strings for each observable
observable_coeffs (np.ndarray) – Coefficients/weights for each observable
total_shots (int) – Total measurement budget per timestep
max_group_size (int) – Maximum observables per group

Returns:

Grouping strategy with shot allocation

Return type:

TDVPObservableGroupingResult

Examples

>>> # Energy + correlation measurements
>>> paulis = ["ZZ", "XX", "YY", "ZI", "IZ"]
>>> coeffs = np.array([1.0, 0.5, 0.5, 0.3, 0.3])
>>> result = ir_tdvp_observable_grouping(paulis, coeffs)
>>> print(f"Variance reduction: {result.variance_reduction:.2f}×")

class atlas_q.ir_enhanced.TDVPObservableGroupingResult(groups, shots_per_group, variance_reduction, method, n_observables, n_groups)[source]#

Bases: object

Result of TDVP observable grouping

groups: List[List[int]]#

shots_per_group: ndarray#

variance_reduction: float#

method: str#

n_observables: int#

n_groups: int#

Shadow Tomography#

Adaptive classical shadows with IR.

atlas_q.ir_enhanced.ir_shadow_sampling(target_observables, observable_coeffs, n_samples=1000, bias_strength=0.5)[source]#

IR-enhanced sampling strategy for classical shadows.

Biases random Pauli sampling toward observables with high coherence.

Parameters:

target_observables (List[str]) – Pauli observables we want to estimate
observable_coeffs (np.ndarray) – Importance weights for each observable
n_samples (int) – Total measurement samples
bias_strength (float) – 0 = uniform (standard shadows), 1 = fully biased

Returns:

Sampling strategy

Return type:

ShadowSamplingResult

Examples

>>> # Estimate energy observables
>>> observables = ["ZZ", "XX", "YY", "ZI"]
>>> coeffs = np.array([1.0, 0.5, 0.5, 0.3])
>>> result = ir_shadow_sampling(observables, coeffs, n_samples=1000)
>>> print(f"Sampling probs: {result.measurement_probs}")

class atlas_q.ir_enhanced.ShadowSamplingResult(pauli_basis, measurement_probs, n_samples, expected_variance, method)[source]#

Bases: object

Result of IR shadow sampling strategy

pauli_basis: List[str]#

measurement_probs: ndarray#

n_samples: int#

expected_variance: float#

method: str#

State Tomography#

IR-enhanced state reconstruction.

atlas_q.ir_enhanced.ir_state_tomography(n_qubits, max_weight=2, target_measurements=None, adaptive=True)[source]#

IR-enhanced state tomography measurement planning.

Generates optimal measurement strategy for quantum state reconstruction.

Parameters:

n_qubits (int) – Number of qubits to reconstruct
max_weight (int) – Maximum Pauli weight (reduces measurement count)
target_measurements (int, optional) – Target number of measurements (if None, uses all up to max_weight)
adaptive (bool) – Use adaptive measurement selection

Returns:

Measurement plan with grouping and prioritization

Return type:

TomographyStrategy

Examples

>>> # 4-qubit tomography with weight-2 Paulis
>>> strategy = ir_state_tomography(n_qubits=4, max_weight=2)
>>> print(f"Measurements: {strategy.n_measurements}")
>>> print(f"Compression: {strategy.compression_factor:.1f}×")

atlas_q.ir_enhanced.generate_pauli_basis(n_qubits, max_weight=None)[source]#

Generate Pauli basis for n qubits.

Parameters:

n_qubits (int) – Number of qubits
max_weight (int, optional) – Maximum Pauli weight (Hamming weight) If None, generates full basis (4^n terms)

Returns:

Pauli strings

Return type:

List[str]

atlas_q.ir_enhanced.tomography_measurement_groups(strategy)[source]#

Get measurement groups from tomography strategy.

Parameters:: strategy (TomographyStrategy) – Tomography plan
Returns:: Grouped Pauli measurements
Return type:: List[List[str]]

Examples

>>> strategy = ir_state_tomography(n_qubits=3, max_weight=2)
>>> groups = tomography_measurement_groups(strategy)
>>> for i, group in enumerate(groups[:3]):
...     print(f"Group {i}: {group}")

class atlas_q.ir_enhanced.TomographyStrategy(measurement_basis, measurement_order, grouping, n_measurements, compression_factor, method)[source]#

Bases: object

Result of IR tomography planning

measurement_basis: List[str]#

measurement_order: List[int]#

grouping: List[List[int]]#

n_measurements: int#

compression_factor: float#

method: str#

Usage Examples#

Pre-Computation Regime Analysis#

from atlas_q.ir_enhanced import (
    analyze_state_regime,
    predict_quantum_advantage,
    ObservabilityRegime,
)
import numpy as np

# Analyze state amplitudes
amplitudes = np.array([0.5, 0.3, 0.1, 0.05, 0.03, 0.02])
phases = np.array([0.0, 0.2, 0.4, 0.6, 0.8, 1.0])

regime = analyze_state_regime(amplitudes, phases)

print(f"Regime: {regime.regime.value}")  # 'ir', 'transition', or 'air'
print(f"Coherence R̄: {regime.coherence:.4f}")
print(f"Structure Observable: {regime.structure_observable}")

if regime.regime == ObservabilityRegime.IR:
    print("GO: Quantum methods will be effective")
elif regime.regime == ObservabilityRegime.AIR:
    print("NO-GO: Consider classical methods")

VQE with IR Grouping#

from atlas_q.ir_enhanced import ir_hamiltonian_grouping
import numpy as np

# Hamiltonian coefficients and Pauli strings
coefficients = np.array([1.5, -0.8, 0.3, -0.2, 0.1, -0.05])
pauli_strings = ["ZZII", "IZZI", "IIZZ", "XXII", "IXXI", "IIXX"]

# Get optimal grouping
result = ir_hamiltonian_grouping(
    coefficients=coefficients,
    pauli_strings=pauli_strings,
    total_shots=10000,
    max_group_size=3,
)

print(f"Number of groups: {len(result.groups)}")
print(f"Variance reduction: {result.variance_reduction:.1f}×")
print(f"Method: {result.method}")  # Includes regime info

Period Finding with IR#

from atlas_q.ir_enhanced import (
    ir_enhanced_period_finding,
    estimate_shot_reduction,
)

# Estimate shot reduction
reduction = estimate_shot_reduction(N=15, coherence=0.8, num_candidates=3)
print(f"Expected shot reduction: {(1-reduction)*100:.0f}%")

# Run IR-enhanced period finding
result = ir_enhanced_period_finding(a=7, N=15)
print(f"Period: {result.period}")

Performance Numbers#

Feature	Improvement
VQE Grouping	4× circuit reduction
Period Finding	42% shot reduction
Variance Reduction	2-60× (VQE)
MPS Scalability	100 qubits in 1.56s
Memory Compression	10^25× (100 qubits)

IR Module (Informational Relativity)#

Overview#

Key Concepts#

Observability Regimes#

GO/NO-GO Classification#

Regime Analyzer#

Classes#

Spectral Lifting#

VQE Grouping#

Period Finding Enhancement#

Core Functions#

QAOA Grouping#

Gradient Grouping#

TDVP Observables#

Shadow Tomography#

State Tomography#

Usage Examples#

Pre-Computation Regime Analysis#

VQE with IR Grouping#

Period Finding with IR#

Performance Numbers#

See Also#