atlas_q.truncation#

Adaptive Truncation Policy for MPS

Implements energy-based rank selection with per-bond caps and budget enforcement.

Mathematical foundation: - Keep smallest k such that Σ_{i≤k} σ_i² ≥ (1-ε²) Σ_i σ_i² - Local error: ε_local² = Σ_{i>k} σ_i² - Entropy: S = -Σ_i p_i log(p_i) where p_i = σ_i² / Σ_j σ_j²

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

atlas_q.truncation.choose_rank_from_sigma(S, eps_bond, chi_cap, budget_ok=<function <lambda>>)[source]#

Adaptive rank selection from singular values

Args:: S: Singular values (sorted descending) eps_bond: Energy tolerance (truncation threshold) chi_cap: Maximum allowed rank for this bond budget_ok: Function that checks if rank k is within memory budget
Returns:: k: Selected rank eps_local: Local truncation error entropy: Entanglement entropy at this bond condS: Condition number (σ_max / σ_k)

Strategy: 1. Find k_tol from energy criterion: cumulative energy ≥ (1-ε²) * total 2. Cap by chi_max_per_bond 3. Reduce if budget violation 4. Compute diagnostics (entropy, condition number, error)

atlas_q.truncation.compute_global_error_bound(local_errors)[source]#

Compute global error bound from local truncation errors

Using simple Frobenius norm bound: ε_global ≤ sqrt(Σ_b ε²_local,b)

Args:: local_errors: List of local truncation errors from each bond
Returns:: Upper bound on global state error

atlas_q.truncation.check_entropy_sanity(entropy, chi_left, chi_right)[source]#

Verify entropy is within physical bounds

For a bond with dimensions χ_L and χ_R, maximum entropy is: S_max = log₂(min(χ_L · 2, 2 · χ_R))

Args:: entropy: Measured entanglement entropy chi_left: Left bond dimension chi_right: Right bond dimension
Returns:: True if entropy is physically reasonable

atlas_q.truncation.analyze_truncation_regime(S, site_index=0, decoherence_rate=0.05, initial_coherence=1.0)[source]#

Analyze regime BEFORE truncation decision (IR-correct approach).

This implements the key IR insight: regime determines representation, not the other way around. We diagnose first, then choose truncation.

Args:: S: Singular values (sorted descending) site_index: Distance from preparation (for L5 decoherence) decoherence_rate: Decay rate α in R̄(D) = R₀ e^(-αD) initial_coherence: Initial coherence R₀
Returns:: RegimeAnalysis from ir_enhanced.regime_analyzer

atlas_q.truncation.choose_rank_with_regime(S, eps_bond, chi_cap, site_index=0, decoherence_rate=0.05, initial_coherence=1.0, budget_ok=<function <lambda>>)[source]#

IR-correct rank selection: Diagnose regime FIRST, then truncate.

This is the proper IR approach: 1. Analyze regime using L5 decoherence model 2. Select epsilon based on regime (not the other way around) 3. Truncate with regime-appropriate tolerance

Args:: S: Singular values (sorted descending) eps_bond: Base energy tolerance chi_cap: Maximum allowed rank site_index: Distance from preparation site decoherence_rate: Decay rate α initial_coherence: Initial coherence R₀ budget_ok: Budget constraint function
Returns:: (k, eps_local, entropy, condS, regime_analysis)

atlas_q.truncation.choose_rank_with_coherence(S, eps_bond, chi_cap, coherence, budget_ok=<function <lambda>>, e2_threshold=0.135)[source]#

IR-enhanced rank selection incorporating coherence metrics.

Implements IR Law L5 (Exponential Decoherence) insight: - High coherence (R̄ > e^-2): Structure is observable, preserve it - Low coherence (R̄ < e^-2): Structure is hidden, aggressive truncation OK

Args:: S: Singular values (sorted descending) eps_bond: Energy tolerance (truncation threshold) chi_cap: Maximum allowed rank for this bond coherence: Current coherence metric R̄ (0-1) budget_ok: Function that checks if rank k is within memory budget e2_threshold: e^-2 threshold (default: 0.135)
Returns:: k: Selected rank eps_local: Local truncation error entropy: Entanglement entropy at this bond condS: Condition number (σ_max / σ_k) coherence_adjusted: Whether coherence influenced the decision

Strategy: 1. Start with standard energy criterion 2. If coherence > e^-2: be conservative (preserve structure) 3. If coherence < e^-2: allow aggressive truncation (structure hidden anyway) 4. Apply caps and budget constraints

atlas_q.truncation.choose_rank_with_decoherence(S, eps_bond, chi_cap, decoherence_rate, site_index, initial_coherence=1.0, budget_ok=<function <lambda>>, e2_threshold=0.135)[source]#

IR L5-based rank selection with exponential decoherence model.

Implements IR Law L5: R̄(D) = R₀ e^(-αD) Coherence decays exponentially under perturbation/distance.

Args:

S: Singular values (sorted descending) eps_bond: Energy tolerance (truncation threshold) chi_cap: Maximum allowed rank for this bond decoherence_rate: Decay rate α (higher = faster decay) site_index: Distance from preparation site D initial_coherence: Initial coherence R₀ (default: 1.0) budget_ok: Function that checks if rank k is within memory budget e2_threshold: e^-2 threshold (default: 0.135)

Returns:

k: Selected rank eps_local: Local truncation error entropy: Entanglement entropy condS: Condition number estimated_coherence: Estimated coherence at this site

References:

IR Paper Section 4.5: “L5: Exponential Decoherence Law”
Formula: R̄(D) = R₀ e^(-αD)

atlas_q.truncation.compute_spectral_coherence(S)[source]#

Compute spectral coherence from singular value distribution.

High spectral coherence = power concentrated in dominant modes Low spectral coherence = power spread across many modes

This can be used as a proxy for response field coherence when direct amplitude access is not available.

Args:: S: Singular values (sorted descending)
Returns:: Spectral coherence R̄ ∈ [0, 1]

atlas_q.truncation.adaptive_chi_from_coherence(coherence_history, current_chi, chi_min=2, chi_max=256, e2_threshold=0.135, growth_rate=1.2, shrink_rate=0.8)[source]#

Four-layer hierarchy feedback: Observable → Structure adaptation.

Adjusts bond dimension based on measured coherence to optimize the representation cost according to IR principles.

IR insight: - Low coherence at observable layer → representation cost too high - Reduce χ to save resources (structure is hidden anyway) - High coherence → structure is valuable, allow χ growth

Args:

coherence_history: Recent coherence measurements (R̄ values) current_chi: Current bond dimension chi_min: Minimum allowed bond dimension chi_max: Maximum allowed bond dimension e2_threshold: e^-2 threshold growth_rate: Multiplier for chi growth (default: 1.2) shrink_rate: Multiplier for chi shrinkage (default: 0.8)

Returns:

Adjusted bond dimension

References:

IR Paper Section 2: “The Four-Layer Framework”
Observable layer feeds back to Structure layer

atlas_q.truncation.coherence_aware_truncation_policy(site_coherences, base_eps=1e-06, base_chi=64, e2_threshold=0.135)[source]#

Generate per-site truncation policy based on coherence distribution.

Sites with high coherence get tighter truncation (preserve structure). Sites with low coherence get looser truncation (save resources).

Args:: site_coherences: Coherence R̄ at each site base_eps: Base truncation tolerance base_chi: Base bond dimension e2_threshold: e^-2 threshold
Returns:: eps_per_site: Truncation tolerance for each site chi_per_site: Bond dimension cap for each site

Overview#

The truncation module implements adaptive rank selection for Matrix Product States based on energy-based criteria. Key features include:

Energy-based truncation with configurable tolerance
Per-bond dimension caps (chi_max_per_bond)
Global memory budget enforcement
Entropy and condition number diagnostics
Local and global error bound computation

Mathematical Foundation#

The module implements truncation based on energy retention:

\[\text{Keep smallest } k \text{ such that } \sum_{i \leq k} \sigma_i^2 \geq (1 - \varepsilon^2) \sum_i \sigma_i^2\]

Local truncation error:

\[\varepsilon_{\text{local}}^2 = \sum_{i > k} \sigma_i^2\]

Global error bound (Frobenius norm):

\[\varepsilon_{\text{global}} \leq \sqrt{\sum_b \varepsilon_{\text{local},b}^2}\]

Entanglement entropy at a bond:

\[S = -\sum_i p_i \log(p_i) \quad \text{where} \quad p_i = \frac{\sigma_i^2}{\sum_j \sigma_j^2}\]

Functions#

`choose_rank_from_sigma`	Adaptive rank selection from singular values
`compute_global_error_bound`	Compute global error bound from local truncation errors
`check_entropy_sanity`	Verify entropy is within physical bounds

choose_rank_from_sigma#

atlas_q.truncation.choose_rank_from_sigma(S, eps_bond, chi_cap, budget_ok=<function <lambda>>)[source]#

Adaptive rank selection from singular values

Args:: S: Singular values (sorted descending) eps_bond: Energy tolerance (truncation threshold) chi_cap: Maximum allowed rank for this bond budget_ok: Function that checks if rank k is within memory budget
Returns:: k: Selected rank eps_local: Local truncation error entropy: Entanglement entropy at this bond condS: Condition number (σ_max / σ_k)

Core adaptive truncation function that selects bond dimension from singular values. Applies multiple constraints in sequence:

Energy criterion: retain (1-ε²) of total energy
Per-bond cap: enforce chi_max_per_bond
Memory budget: reduce rank if global memory exceeded
Compute diagnostics: local error, entropy, condition number

Returns selected rank k along with diagnostic information.

compute_global_error_bound#

atlas_q.truncation.compute_global_error_bound(local_errors)[source]#

Compute global error bound from local truncation errors

Using simple Frobenius norm bound: ε_global ≤ sqrt(Σ_b ε²_local,b)

Args:: local_errors: List of local truncation errors from each bond
Returns:: Upper bound on global state error

Computes upper bound on global state error from local truncation errors using Frobenius norm. This provides a certificate that the MPS approximation is within specified tolerance of the exact state.

check_entropy_sanity#

atlas_q.truncation.check_entropy_sanity(entropy, chi_left, chi_right)[source]#

Verify entropy is within physical bounds

For a bond with dimensions χ_L and χ_R, maximum entropy is: S_max = log₂(min(χ_L · 2, 2 · χ_R))

Args:: entropy: Measured entanglement entropy chi_left: Left bond dimension chi_right: Right bond dimension
Returns:: True if entropy is physically reasonable

Validates that computed entanglement entropy is physically reasonable. Maximum entropy at a bond is bounded by the smaller Hilbert space dimension. This function checks if measured entropy exceeds theoretical maximum, which would indicate numerical issues.

Examples#

Basic truncation decision:

import torch
from atlas_q.truncation import choose_rank_from_sigma

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

# Choose rank with ε=1e-3 tolerance, max χ=4
k, eps_local, entropy, condS = choose_rank_from_sigma(
    S,
    eps_bond=1e-3,
    chi_cap=4
)

print(f"Selected rank: {k}")
print(f"Local error: {eps_local:.2e}")
print(f"Entropy: {entropy:.3f}")
print(f"Condition number: {condS:.2e}")

Truncation with memory budget:

from atlas_q.truncation import choose_rank_from_sigma

current_memory = 2000  # MB
budget = 4096  # MB

def budget_ok(k):
    # Estimate memory for rank k
    estimated_memory = current_memory + k * k * 16  # bytes per element
    return estimated_memory < budget * 1024 * 1024

k, eps_local, entropy, condS = choose_rank_from_sigma(
    S,
    eps_bond=1e-6,
    chi_cap=128,
    budget_ok=budget_ok
)

print(f"Selected rank respecting budget: {k}")

Computing global error:

from atlas_q.truncation import compute_global_error_bound

# Local errors from multiple truncations
local_errors = [1e-6, 2e-6, 1.5e-6, 3e-6, 1e-6]

global_error = compute_global_error_bound(local_errors)
print(f"Global error bound: {global_error:.2e}")

# Check if within tolerance
target_error = 1e-5
if global_error < target_error:
    print("Simulation within target accuracy")

Entropy validation:

from atlas_q.truncation import check_entropy_sanity

# Bond with dimensions χ_L=32, χ_R=64
entropy = 8.5
is_valid = check_entropy_sanity(entropy, chi_left=32, chi_right=64)

if not is_valid:
    print("Warning: Entropy exceeds physical bound")

Integration with AdaptiveMPS:

from atlas_q.adaptive_mps import AdaptiveMPS

# AdaptiveMPS uses truncation module internally
mps = AdaptiveMPS(
    num_qubits=30,
    bond_dim=16,
    eps_bond=1e-6,              # Truncation tolerance
    chi_max_per_bond=128,       # Per-bond cap
    budget_global_mb=4096,      # Memory budget
    device='cuda'
)

# Apply gates - truncation automatically applied
# ...

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

# Access per-operation truncation data
for step, eps in enumerate(mps.statistics.logs['eps_local']):
    bond = mps.statistics.logs['bond'][step]
    print(f"Bond {bond}: ε_local = {eps:.2e}")

Advanced Usage: Custom Truncation Strategy#

Implement custom budget function for adaptive memory management:

from atlas_q.truncation import choose_rank_from_sigma
import torch

class AdaptiveBudget:
    def __init__(self, total_bonds, budget_mb):
        self.total_bonds = total_bonds
        self.budget_mb = budget_mb
        self.current_usage = [0] * total_bonds

    def budget_ok_for_bond(self, bond_idx):
        def checker(k):
            # Estimate if setting bond to rank k fits budget
            new_usage = self.current_usage.copy()
            new_usage[bond_idx] = k * k * 16  # bytes
            return sum(new_usage) < self.budget_mb * 1024 * 1024
        return checker

budget = AdaptiveBudget(total_bonds=20, budget_mb=4096)

# Per-bond truncation decisions
for bond in range(20):
    S = torch.randn(128).abs()  # Mock singular values
    S = S.sort(descending=True)[0]

    k, eps, entropy, cond = choose_rank_from_sigma(
        S,
        eps_bond=1e-6,
        chi_cap=128,
        budget_ok=budget.budget_ok_for_bond(bond)
    )

    budget.current_usage[bond] = k * k * 16
    print(f"Bond {bond}: χ={k}, ε={eps:.2e}")

Performance Notes#

Computational Cost

Truncation itself is O(χ):

Sorting singular values: O(χ log χ)
Computing cumulative sum: O(χ)
Entropy calculation: O(χ)

Total cost negligible compared to SVD (O(χ³)).

Memory-Efficient Strategies

For large systems, use per-bond caps to limit peak memory:

# Vary χ by position in chain
chi_max_per_bond = [32] * 10 + [64] * 10 + [32] * 10  # Higher in middle

This reduces memory by 2-4× for 1D chains with localized entanglement.

Adaptive vs. Fixed

Fixed χ: Predictable memory, may over/under-provision
Adaptive with ε: Minimal χ for given accuracy, variable memory
Hybrid: Per-bond caps + energy threshold (recommended)

Best Practices#

Choosing ε_bond

ε = 10⁻⁸: High accuracy, larger χ
ε = 10⁻⁶: Balanced (recommended)
ε = 10⁻⁴: Fast but less accurate

Monitor global error; if > 0.01, decrease ε or increase χ_max.

Per-Bond Optimization

Analyze entropy profile to set per-bond budgets:

entropies = [mps.get_entropy(i) for i in range(N-1)]
chi_max_per_bond = [min(64, int(2**S)) for S in entropies]

Allocates χ proportional to local entanglement.

Troubleshooting

χ always hits cap: Increase χ_max or use 2-site algorithm
High global error: Decrease ε_bond or check circuit structure
Memory overflow: Use per-bond caps or reduce χ_max

Use Cases#

Adaptive Truncation

Essential for:

Unknown entanglement structure (exploratory simulations)
Variable entanglement (quantum quenches, time evolution)
Memory-constrained environments

Fixed Truncation

Sufficient for:

Known entanglement (e.g., ground states of local Hamiltonians)
Benchmarking (reproducible χ)
Real-time applications (predictable performance)

References#

[Vidal03]

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

[White92]

1. White, “Density matrix formulation for quantum renormalization groups,” Physical Review Letters 69, 2863 (1992).

[Orus14]

Orús, “A practical introduction to tensor networks,” Annals of Physics 349, 117 (2014).