atlas_q.diagnostics#

Diagnostics and Monitoring Utilities for MPS

Provides entropy calculations, statistics tracking, and observability tools.

Author: ATLAS-Q Contributors Date: October 2025 License: MIT

atlas_q.diagnostics.bond_entropy_from_S(S)[source]#

Compute entanglement entropy from singular values

S = -Σ_i p_i log(p_i) where p_i = σ_i² / Σ_j σ_j²

Args:

S: Singular values (sorted descending)

Returns:

Entanglement entropy in bits (log base 2)

atlas_q.diagnostics.effective_rank(S, threshold=0.99)[source]#

Compute effective rank: smallest k where cumulative energy ≥ threshold

Args:

S: Singular values threshold: Energy retention threshold (default 99%)

Returns:

Effective rank

atlas_q.diagnostics.spectral_gap(S, k)[source]#

Compute spectral gap σ_k / σ_{k+1}

Large gaps indicate safe truncation points.

Args:

S: Singular values k: Truncation point

Returns:

Spectral gap ratio (or inf if k+1 doesn’t exist or is zero)

class atlas_q.diagnostics.MPSStatistics[source]#

Bases: object

Track and aggregate MPS operation statistics

Maintains per-operation logs and rolling aggregates for: - Bond dimensions (χ) - Truncation errors (ε_local) - Entanglement entropies (S) - SVD driver usage - Computation times

Methods

global_error_bound()

Compute global error upper bound

record(**kwargs)

Record a single operation

reset()

Clear all logs

summary()

Compute summary statistics
record(**kwargs)[source]#

Record a single operation

summary()[source]#

Compute summary statistics

global_error_bound()[source]#

Compute global error upper bound

reset()[source]#

Clear all logs

Overview#

The diagnostics module provides comprehensive monitoring and analysis tools for Matrix Product State simulations. It enables tracking of entanglement structure, truncation errors, and computational efficiency throughout MPS operations.

Entanglement Diagnostics

Entanglement entropy quantifies the entanglement between two subsystems in a quantum state. For an MPS, the entanglement entropy at bond i is computed from the Schmidt decomposition:

\[|\psi\rangle = \sum_{\alpha=1}^{\chi} \sigma_\alpha |\phi_\alpha^L\rangle |\phi_\alpha^R\rangle\]

where \(\sigma_\alpha\) are Schmidt coefficients (singular values from SVD). The von Neumann entropy is:

\[S = -\sum_{\alpha=1}^{\chi} p_\alpha \log_2(p_\alpha), \quad p_\alpha = \frac{\sigma_\alpha^2}{\sum_\beta \sigma_\beta^2}\]

Physical Interpretation

  • S = 0: Product state (no entanglement)

  • S = log₂(χ): Maximally entangled across bond (χ Schmidt states equally weighted)

  • S ≈ log₂(χ_eff): Effective rank χ_eff < χ indicates redundant bond dimension

Truncation Error Analysis

When truncating from χ to χ’ < χ, the local truncation error is:

\[\epsilon_{\text{local}} = \sqrt{\sum_{\alpha > \chi'} \sigma_\alpha^2}\]

The global error accumulates via the Vidal bound [Vidal03]:

\[\|\psi_{\text{exact}} - \psi_{\text{truncated}}\| \leq \sum_{i=1}^{N} \epsilon_i\]

where ε_i is the truncation error at bond i.

Key Metrics

  • Entanglement entropy: Measure of bipartite entanglement

  • Effective rank: Number of significant Schmidt values (captures 99% of weight)

  • Spectral gap: Ratio σ_k / σ_{k+1} indicating safe truncation points

  • Bond dimension evolution: Track χ growth during simulation

  • Truncation error bounds: Global error estimates from local errors

Functions#

bond_entropy_from_S

Compute entanglement entropy from singular values

effective_rank

Compute effective rank: smallest k where cumulative energy ≥ threshold

spectral_gap

Compute spectral gap σ_k / σ_{k+1}

Classes#

MPSStatistics

Track and aggregate MPS operation statistics

bond_entropy_from_S#

atlas_q.diagnostics.bond_entropy_from_S(S)[source]#

Compute entanglement entropy from singular values

S = -Σ_i p_i log(p_i) where p_i = σ_i² / Σ_j σ_j²

Args:

S: Singular values (sorted descending)

Returns:

Entanglement entropy in bits (log base 2)

Computes entanglement entropy from singular values using the formula:

\[S = -\sum_i p_i \log_2(p_i)\]

where \(p_i = \sigma_i^2 / \sum_j \sigma_j^2\).

effective_rank#

atlas_q.diagnostics.effective_rank(S, threshold=0.99)[source]#

Compute effective rank: smallest k where cumulative energy ≥ threshold

Args:

S: Singular values threshold: Energy retention threshold (default 99%)

Returns:

Effective rank

Computes the effective rank as the smallest k where cumulative energy retention exceeds a threshold (default 99%). Useful for determining how many singular values contain most of the energy.

spectral_gap#

atlas_q.diagnostics.spectral_gap(S, k)[source]#

Compute spectral gap σ_k / σ_{k+1}

Large gaps indicate safe truncation points.

Args:

S: Singular values k: Truncation point

Returns:

Spectral gap ratio (or inf if k+1 doesn’t exist or is zero)

Computes the spectral gap \(\sigma_k / \sigma_{k+1}\). Large gaps indicate safe truncation points where discarding smaller singular values introduces minimal error.

MPSStatistics#

class atlas_q.diagnostics.MPSStatistics[source]#

Bases: object

Track and aggregate MPS operation statistics

Maintains per-operation logs and rolling aggregates for: - Bond dimensions (χ) - Truncation errors (ε_local) - Entanglement entropies (S) - SVD driver usage - Computation times

Methods

global_error_bound()

Compute global error upper bound

record(**kwargs)

Record a single operation

reset()

Clear all logs

summary()

Compute summary statistics

Comprehensive statistics tracker for MPS operations.

Tracked Metrics

For each operation (gate application, canonicalization, etc.):

  • step: Operation index

  • bond: Bond index where operation occurred

  • chi_before: Bond dimension before operation

  • chi_after: Bond dimension after truncation

  • eps_local: Local truncation error \(\sqrt{\sum_{\alpha > \chi} \sigma_\alpha^2}\)

  • entropy: Entanglement entropy \(-\sum p_\alpha \log_2(p_\alpha)\)

  • svd_driver: Which SVD implementation used (‘torch_cuda’, ‘torch_cpu’, ‘numpy’)

  • time_ms: Operation duration in milliseconds

Aggregate Statistics

The summary() method computes:

  • max_chi: Maximum bond dimension encountered

  • mean_chi: Average bond dimension across all operations

  • max_entropy: Maximum entanglement entropy

  • mean_entropy: Average entanglement entropy

  • total_operations: Number of recorded operations

  • cuda_svd_pct: Percentage of SVDs on GPU

  • total_time_s: Total computation time in seconds

Global Error Bound

Computes cumulative truncation error via Vidal bound:

\[\epsilon_{\text{global}} = \sum_{i=1}^{M} \epsilon_i\]

where M is the number of truncation operations.

Methods

Methods

__init__()

record(**kwargs)

Record a single operation

summary()

Compute summary statistics

global_error_bound()

Compute global error upper bound

reset()

Clear all logs
__init__()[source]#

Initialize empty statistics tracker.

record(step, bond, chi_before, chi_after, eps_local, entropy, svd_driver='torch_cuda', time_ms=0.0)[source]#

Record statistics for a single operation.

Parameters:

  • step (int) – Operation index

  • bond (int) – Bond index

  • chi_before (int) – Bond dimension before

  • chi_after (int) – Bond dimension after

  • eps_local (float) – Local truncation error

  • entropy (float) – Entanglement entropy

  • svd_driver (str) – SVD implementation used

  • time_ms (float) – Operation time in milliseconds

summary()[source]#

Compute aggregate statistics.

Returns:

Dictionary of summary statistics

Return type:

dict

global_error_bound()[source]#

Compute global truncation error bound.

Returns:

Sum of all local truncation errors

Return type:

float

reset()[source]#

Clear all recorded statistics.

plot_entropies(save_path=None)#

Plot entanglement entropy evolution.

Parameters:

save_path (str) – Optional path to save figure

Returns:

matplotlib Figure object

Return type:

matplotlib.figure.Figure

plot_bond_dims(save_path=None)#

Plot bond dimension evolution.

Parameters:

save_path (str) – Optional path to save figure

Returns:

matplotlib Figure object

Return type:

matplotlib.figure.Figure

record(**kwargs)[source]#

Record a single operation

summary()[source]#

Compute summary statistics

global_error_bound()[source]#

Compute global error upper bound

reset()[source]#

Clear all logs

Examples#

Computing entanglement entropy:

import torch
from atlas_q.diagnostics import bond_entropy_from_S

# Singular values from SVD
S = torch.tensor([2.0, 1.0, 0.5, 0.1])

entropy = bond_entropy_from_S(S)
print(f"Entanglement entropy: {entropy:.3f} bits")

Analyzing effective rank:

from atlas_q.diagnostics import effective_rank

# Check how many singular values capture 99% of energy
k_eff = effective_rank(S, threshold=0.99)
print(f"Effective rank: {k_eff} / {len(S)}")

Tracking MPS statistics:

from atlas_q.diagnostics import MPSStatistics

stats = MPSStatistics()

# Record operations
stats.record(
    step=0,
    bond=5,
    chi_before=32,
    chi_after=28,
    eps_local=1e-6,
    entropy=3.2,
    svd_driver='torch_cuda'
)

# Get summary
summary = stats.summary()
print(f"Max χ: {summary['max_chi']}")
print(f"Global error bound: {stats.global_error_bound():.2e}")
print(f"GPU utilization: {summary['cuda_svd_pct']:.1f}%")

Advanced usage with AdaptiveMPS:

from atlas_q.adaptive_mps import AdaptiveMPS

mps = AdaptiveMPS(num_qubits=20, bond_dim=16, device='cuda')

# Apply gates...

# Access statistics
stats = mps.stats_summary()
print(f"Total operations: {stats['total_operations']}")
print(f"Mean χ: {stats['mean_chi']:.1f}")
print(f"Mean entropy: {stats['mean_entropy']:.2f}")

# Check global error
global_error = mps.global_error_bound()
print(f"Global truncation error: {global_error:.2e}")

Example 4: Visualizing Entanglement Structure

import matplotlib.pyplot as plt
from atlas_q.adaptive_mps import AdaptiveMPS
from atlas_q.diagnostics import bond_entropy_from_S

mps = AdaptiveMPS(num_qubits=30, bond_dim=32, device='cuda')

# Apply deep circuit
import torch
H = torch.tensor([[1, 1], [1, -1]], dtype=torch.complex64, device='cuda') / (2**0.5)
CNOT = torch.eye(4, dtype=torch.complex64, device='cuda')
CNOT[2:, 2:] = torch.tensor([[0, 1], [1, 0]], dtype=torch.complex64, device='cuda')

for layer in range(10):
    for i in range(30):
        mps.apply_single_qubit_gate(i, H)
    for i in range(29):
        mps.apply_two_qubit_gate(i, CNOT)

# Compute entropies at all bonds
entropies = []
for bond_idx in range(29):
    # Get singular values at bond
    S = mps.get_singular_values(bond_idx)
    entropy = bond_entropy_from_S(S)
    entropies.append(entropy)

# Plot entanglement profile
plt.figure(figsize=(10, 4))
plt.plot(entropies, 'o-')
plt.xlabel('Bond Index')
plt.ylabel('Entanglement Entropy (bits)')
plt.title('Entanglement Profile After 10 Layers')
plt.grid(True)
plt.savefig('entanglement_profile.png')

# Identify bottleneck bonds (high entanglement)
max_entropy_bond = entropies.index(max(entropies))
print(f"Maximum entanglement at bond {max_entropy_bond}: {max(entropies):.2f} bits")

Example 5: Analyzing Truncation Quality

from atlas_q.diagnostics import effective_rank, spectral_gap
import torch

# Get singular values from some bond
S = mps.get_singular_values(bond_idx=15)

# Compute effective rank (99% threshold)
k_eff = effective_rank(S, threshold=0.99)
print(f"Effective rank: {k_eff} / {len(S)} (ratio: {k_eff/len(S):.2f})")

# If ratio < 0.5, bond dimension is overprovisioned
if k_eff / len(S) < 0.5:
    print(f"Bond {bond_idx} has redundancy, could reduce χ")

# Check spectral gap
if k_eff < len(S):
    gap = spectral_gap(S, k=k_eff)
    print(f"Spectral gap at truncation point: {gap:.2e}")

    # Large gap (> 10) indicates safe truncation
    if gap > 10:
        print("Safe to truncate at this point")
    else:
        print("Warning: Small spectral gap, truncation may introduce error")

Performance Notes#

Entropy Computation Cost

  • bond_entropy_from_S: O(χ) for χ singular values

  • Dominated by log₂ evaluations, negligible compared to SVD cost

  • Can compute for all N bonds in < 1 ms for typical χ ≤ 64

Memory Overhead

MPSStatistics storage:

  • Per operation: ~100 bytes (8 floats + metadata)

  • 10000 operations: ~1 MB

  • Negligible compared to MPS tensors (MBs to GBs)

Typical Statistics Collection Cost

For 10000-gate circuit on 30 qubits:

  • Without statistics: 12.3s

  • With statistics: 12.5s

  • Overhead: ~1.6% (acceptable for diagnostics)

Best Practices

  1. Enable statistics during development/debugging, disable in production if microseconds matter

  2. Monitor global error bound to ensure simulation accuracy

  3. Plot entropy profiles to identify entanglement bottlenecks

  4. Check effective rank to detect over-provisioned bond dimensions

  5. Track GPU utilization via svd_driver statistics

Interpreting Statistics

Entanglement Entropy Interpretation#

Entropy Range

State Type

Implications

S = 0

Product state

No entanglement, MPS exact with χ=1

S = 1-3 bits

Weakly entangled

Small χ (4-8) sufficient

S = 4-6 bits

Moderately entangled

χ = 16-64 needed

S = 6-10 bits

Highly entangled

χ = 64-512 required

S > 10 bits

Volume-law entanglement

MPS may be inefficient

Troubleshooting

  • Global error > 0.01: Increase χ_max or use tighter truncation threshold

  • Entropy saturates at log₂(χ): Bond dimension limiting entanglement, increase χ

  • Many CPU fallbacks: GPU memory insufficient, reduce batch size or χ

  • Entropy decreases unexpectedly: Possible numerical instability, check condition numbers

Use Cases#

Research Applications

  • Studying entanglement growth in quantum circuits

  • Benchmarking truncation strategies

  • Identifying optimal bond dimension schedules

  • Analyzing quantum advantage demonstrations

Production Monitoring

  • Real-time error estimation during simulation

  • Performance profiling (GPU vs CPU SVD usage)

  • Quality assurance for simulation results

  • Automated alerts for excessive truncation errors

Algorithm Development

  • Comparing different MPS algorithms (TDVP, TEBD, etc.)

  • Optimizing circuit compilation for MPS

  • Developing adaptive χ strategies

  • Testing new truncation heuristics

See Also#

References#

[Vidal03]

  1. Vidal, “Efficient classical simulation of slightly entangled quantum computations,” Physical Review Letters 91, 147902 (2003).

[Schollwock11]

  1. Schollwöck, “The density-matrix renormalization group in the age of matrix product states,” Annals of Physics 326, 96 (2011).

[Eisert10]

  1. Eisert, M. Cramer, & M. B. Plenio, “Area laws for the entanglement entropy,” Reviews of Modern Physics 82, 277 (2010).

[Plenio05]

    1. Plenio & S. Virmani, “An introduction to entanglement measures,” Quantum Information and Computation 7, 1 (2007).