atlas_q.adaptive_mps.AdaptiveMPS#

class atlas_q.adaptive_mps.AdaptiveMPS(num_qubits, bond_dim=8, *, eps_bond=1e-06, chi_max_per_bond=256, budget_global_mb=None, dtype_policy=DTypePolicy(default=torch.complex64, promote_if_cond_gt=1000000.0), device='cuda', dtype=None)[source]#

Bases: MatrixProductStatePyTorch

Adaptive MPS for moderate-to-high entanglement simulation

Key features: - Variable per-bond dimensions with adaptive truncation - Energy-based rank selection: keep k such that Σ_{i≤k} σ_i² ≥ (1-ε²) Σ_i σ_i² - Per-bond χ caps and global memory budget enforcement - Mixed precision with automatic promotion on numerical instability - Two-site gate application (TEBD-style) - Comprehensive statistics and error tracking

Example:
>>> mps = AdaptiveMPS(16, bond_dim=8, eps_bond=1e-6, chi_max_per_bond=64)
>>> H = torch.tensor([[1,1],[1,-1]], dtype=torch.complex64)/torch.sqrt(torch.tensor(2.0))
>>> for q in range(16):
>>>     mps.apply_single_qubit_gate(q, H)
>>> CZ = torch.diag(torch.tensor([1,1,1,-1], dtype=torch.complex64))
>>> for i in range(0, 15, 2):
>>>     mps.apply_two_site_gate(i, CZ)
>>> print(mps.stats_summary())

Methods

apply_single_qubit_gate(q, U2)

Apply single-qubit gate (fast path, no truncation needed)

apply_two_qubit_gate(qubit1, qubit2, gate)

Apply two-qubit gate to adjacent qubits in MPS

apply_two_site_gate(i, U4)

Apply two-qubit gate with adaptive SVD truncation

canonicalize_left_to_right()

Alias for to_left_canonical() for compatibility

canonicalize_right_to_left()

Bring MPS into right-canonical form using QR decomposition

cnot(control, target)

CNOT gate (uses Triton-optimized two-site gate)

cx(control, target)

Alias for CNOT

cy(control, target)

Controlled-Y gate

cz(q0, q1)

Controlled-Z gate

from_numpy_mps(numpy_mps_dict[, device])

Create PyTorch MPS from NumPy MPS dictionary

get_amplitude(basis_state)

Contract MPS to get amplitude - O(n × χ²)

get_memory_usage()

Get total memory usage in bytes

get_probability(basis_state)

Get measurement probability for a basis state

global_error_bound()

Get global error upper bound

h(qubit)

Hadamard gate

load_snapshot(path[, device])

Load MPS from checkpoint file

measure([num_shots])

Simulate measurement with accurate MPS sampling

memory_usage()

Memory usage in bytes

reset_stats()

Reset statistics tracking

rx(qubit, theta)

Rotation around X axis

ry(qubit, theta)

Rotation around Y axis

rz(qubit, theta)

Rotation around Z axis

s(qubit)

Phase gate (S gate)

sample([num_shots])

Sample measurement outcomes - delegates to parent class

sdg(qubit)

S dagger gate

snapshot(path)

Save MPS to file for checkpointing

stats_summary()

Get summary statistics

swap(q0, q1)

SWAP gate

sweep_sample([num_shots])

Accurate MPS sampling using conditional probabilities sweep

t(qubit)

T gate

tdg(qubit)

T dagger gate

to_left_canonical()

Bring MPS into left-canonical form using QR

to_mixed_canonical(center)

Bring MPS into mixed-canonical form with center at specified site

to_numpy_mps()

Convert to NumPy MPS for compatibility

to_statevector()

Convert MPS to full statevector (ONLY for small systems!)

x(qubit)

Pauli X gate

y(qubit)

Pauli Y gate

z(qubit)

Pauli Z gate
__init__(num_qubits, bond_dim=8, *, eps_bond=1e-06, chi_max_per_bond=256, budget_global_mb=None, dtype_policy=DTypePolicy(default=torch.complex64, promote_if_cond_gt=1000000.0), device='cuda', dtype=None)[source]#

Initialize Adaptive MPS

Args:

num_qubits: Number of qubits bond_dim: Initial bond dimension eps_bond: Energy tolerance for truncation (default 1e-6) chi_max_per_bond: Max χ per bond (int or list of ints) budget_global_mb: Global memory budget in MB (None = unlimited) dtype_policy: Mixed precision policy device: ‘cuda’ or ‘cpu’ dtype: Explicit dtype (overrides dtype_policy.default if provided)

Methods

__init__(num_qubits[, bond_dim, eps_bond, ...])

Initialize Adaptive MPS

apply_single_qubit_gate(q, U2)

Apply single-qubit gate (fast path, no truncation needed)

apply_two_qubit_gate(qubit1, qubit2, gate)

Apply two-qubit gate to adjacent qubits in MPS

apply_two_site_gate(i, U4)

Apply two-qubit gate with adaptive SVD truncation

canonicalize_left_to_right()

Alias for to_left_canonical() for compatibility

canonicalize_right_to_left()

Bring MPS into right-canonical form using QR decomposition

cnot(control, target)

CNOT gate (uses Triton-optimized two-site gate)

cx(control, target)

Alias for CNOT

cy(control, target)

Controlled-Y gate

cz(q0, q1)

Controlled-Z gate

from_numpy_mps(numpy_mps_dict[, device])

Create PyTorch MPS from NumPy MPS dictionary

get_amplitude(basis_state)

Contract MPS to get amplitude - O(n × χ²)

get_memory_usage()

Get total memory usage in bytes

get_probability(basis_state)

Get measurement probability for a basis state

global_error_bound()

Get global error upper bound

h(qubit)

Hadamard gate

load_snapshot(path[, device])

Load MPS from checkpoint file

measure([num_shots])

Simulate measurement with accurate MPS sampling

memory_usage()

Memory usage in bytes

reset_stats()

Reset statistics tracking

rx(qubit, theta)

Rotation around X axis

ry(qubit, theta)

Rotation around Y axis

rz(qubit, theta)

Rotation around Z axis

s(qubit)

Phase gate (S gate)

sample([num_shots])

Sample measurement outcomes - delegates to parent class

sdg(qubit)

S dagger gate

snapshot(path)

Save MPS to file for checkpointing

stats_summary()

Get summary statistics

swap(q0, q1)

SWAP gate

sweep_sample([num_shots])

Accurate MPS sampling using conditional probabilities sweep

t(qubit)

T gate

tdg(qubit)

T dagger gate

to_left_canonical()

Bring MPS into left-canonical form using QR

to_mixed_canonical(center)

Bring MPS into mixed-canonical form with center at specified site

to_numpy_mps()

Convert to NumPy MPS for compatibility

to_statevector()

Convert MPS to full statevector (ONLY for small systems!)

x(qubit)

Pauli X gate

y(qubit)

Pauli Y gate

z(qubit)

Pauli Z gate
__init__(num_qubits, bond_dim=8, *, eps_bond=1e-06, chi_max_per_bond=256, budget_global_mb=None, dtype_policy=DTypePolicy(default=torch.complex64, promote_if_cond_gt=1000000.0), device='cuda', dtype=None)[source]#

Initialize Adaptive MPS

Args:

num_qubits: Number of qubits bond_dim: Initial bond dimension eps_bond: Energy tolerance for truncation (default 1e-6) chi_max_per_bond: Max χ per bond (int or list of ints) budget_global_mb: Global memory budget in MB (None = unlimited) dtype_policy: Mixed precision policy device: ‘cuda’ or ‘cpu’ dtype: Explicit dtype (overrides dtype_policy.default if provided)

stats_summary()[source]#

Get summary statistics

global_error_bound()[source]#

Get global error upper bound

reset_stats()[source]#

Reset statistics tracking

apply_single_qubit_gate(q, U2)[source]#

Apply single-qubit gate (fast path, no truncation needed)

Args:

q: Qubit index U2: 2x2 unitary gate

Complexity: O(χ²)

apply_two_site_gate(i, U4)[source]#

Apply two-qubit gate with adaptive SVD truncation

This is the core TEBD operation for moderate entanglement.

Args:

i: Bond index (applies to qubits i and i+1) U4: 4x4 unitary gate (or 2x2x2x2 tensor)

Steps: 1. Merge tensors at sites (i, i+1) into Θ 2. Apply gate U 3. SVD: Θ = U S V† 4. Adaptively select rank k by energy criterion + caps 5. Split back into two cores with updated χ

Complexity: O(χ³) for SVD

to_left_canonical()[source]#

Bring MPS into left-canonical form using QR

After this, each tensor A^[i] satisfies: Σ_s (A^[i]_s)† A^[i]_s = I

Complexity: O(n · χ³)

canonicalize_left_to_right()[source]#

Alias for to_left_canonical() for compatibility

to_mixed_canonical(center)[source]#

Bring MPS into mixed-canonical form with center at specified site

Sites 0..center-1 are left-canonical Sites center+1..n-1 are right-canonical Site center holds the normalization

Args:

center: Center site index

Complexity: O(n · χ³)

snapshot(path)[source]#

Save MPS to file for checkpointing

Args:

path: File path to save to

static load_snapshot(path, device='cuda')[source]#

Load MPS from checkpoint file

Args:

path: File path to load from device: Device to place tensors on

Returns:

Loaded AdaptiveMPS instance

get_memory_usage()[source]#

Get total memory usage in bytes

Returns:

Total bytes used by all tensors

to_statevector()[source]#

Convert MPS to full statevector (ONLY for small systems!)

Returns:

Full statevector of size 2^n

Warning:

This scales as O(2^n) and should ONLY be used for testing small systems (n ≤ 20). For larger systems, use get_amplitude().

h(qubit)[source]#

Hadamard gate

x(qubit)[source]#

Pauli X gate

y(qubit)[source]#

Pauli Y gate

z(qubit)[source]#

Pauli Z gate

s(qubit)[source]#

Phase gate (S gate)

sdg(qubit)[source]#

S dagger gate

t(qubit)[source]#

T gate

tdg(qubit)[source]#

T dagger gate

rx(qubit, theta)[source]#

Rotation around X axis

ry(qubit, theta)[source]#

Rotation around Y axis

rz(qubit, theta)[source]#

Rotation around Z axis

cnot(control, target)[source]#

CNOT gate (uses Triton-optimized two-site gate)

cx(control, target)[source]#

Alias for CNOT

cz(q0, q1)[source]#

Controlled-Z gate

cy(control, target)[source]#

Controlled-Y gate

swap(q0, q1)[source]#

SWAP gate

sample(num_shots=1)[source]#

Sample measurement outcomes - delegates to parent class