atlas_q.mpo_ops.MPOBuilder

class atlas_q.mpo_ops.MPOBuilder

Bases: object

Helper class to build common MPOs

Methods

from_local_terms(n_sites, local_terms[, ...])	Build Hamiltonian from local interaction terms
heisenberg_hamiltonian(n_sites[, Jx, Jy, ...])	Heisenberg Hamiltonian: H = Σᵢ (Jₓ XᵢXᵢ₊₁ + Jᵧ YᵢYᵢ₊₁ + Jᵧ ZᵢZᵢ₊₁)
identity_mpo(n_sites[, device, dtype])	Create identity MPO (wrapper for MPO.identity)
ising_hamiltonian(n_sites[, J, h, device, dtype])	Transverse-field Ising Hamiltonian: H = -J Σᵢ ZᵢZᵢ₊₁ - h Σᵢ Xᵢ
local_operator(op, site, n_sites[, device, ...])	Create MPO for a single-site operator at specified site
maxcut_hamiltonian(edges[, weights, ...])	MaxCut QAOA Hamiltonian for graph optimization: H = Σ_{(i,j)∈E} w_{ij} (1 - ZᵢZⱼ) / 2
molecular_hamiltonian_from_specs([molecule, ...])	Build molecular Hamiltonian from molecular specifications using PySCF.
sum_local_operators(n_sites, local_ops[, ...])	Create MPO for sum of local operators: Σᵢ Oᵢ

__init__(*args, **kwargs)

Methods

__init__(*args, **kwargs)
from_local_terms(n_sites, local_terms[, ...])	Build Hamiltonian from local interaction terms
heisenberg_hamiltonian(n_sites[, Jx, Jy, ...])	Heisenberg Hamiltonian: H = Σᵢ (Jₓ XᵢXᵢ₊₁ + Jᵧ YᵢYᵢ₊₁ + Jᵧ ZᵢZᵢ₊₁)
identity_mpo(n_sites[, device, dtype])	Create identity MPO (wrapper for MPO.identity)
ising_hamiltonian(n_sites[, J, h, device, dtype])	Transverse-field Ising Hamiltonian: H = -J Σᵢ ZᵢZᵢ₊₁ - h Σᵢ Xᵢ
local_operator(op, site, n_sites[, device, ...])	Create MPO for a single-site operator at specified site
maxcut_hamiltonian(edges[, weights, ...])	MaxCut QAOA Hamiltonian for graph optimization: H = Σ_{(i,j)∈E} w_{ij} (1 - ZᵢZⱼ) / 2
molecular_hamiltonian_from_specs([molecule, ...])	Build molecular Hamiltonian from molecular specifications using PySCF.
sum_local_operators(n_sites, local_ops[, ...])	Create MPO for sum of local operators: Σᵢ Oᵢ

static identity_mpo(n_sites, device='cuda', dtype=torch.complex64)

Create identity MPO (wrapper for MPO.identity)

static local_operator(op, site, n_sites, device='cuda', dtype=torch.complex64)

Create MPO for a single-site operator at specified site

Args:

op: 2x2 operator matrix site: Site index (0-indexed) n_sites: Total number of sites device: torch device dtype: data type

Returns:

MPO representing I ⊗ … ⊗ op ⊗ … ⊗ I

static sum_local_operators(n_sites, local_ops, device='cuda', dtype=torch.complex64)

Create MPO for sum of local operators: Σᵢ Oᵢ

Args:

n_sites: Total number of sites local_ops: List of (site, operator) tuples device: torch device dtype: data type

Returns:

MPO representing sum of all operators

Example:

# Build total magnetization Mz = Σ Zᵢ Z = torch.tensor([[1, 0], [0, -1]]) ops = [(i, Z) for i in range(n_sites)] Mz = MPOBuilder.sum_local_operators(n_sites, ops)

static ising_hamiltonian(n_sites, J=1.0, h=0.5, device='cuda', dtype=torch.complex64)

Transverse-field Ising Hamiltonian: H = -J Σᵢ ZᵢZᵢ₊₁ - h Σᵢ Xᵢ

Args:

n_sites: Number of sites J: Coupling strength h: Transverse field

Virtual bond structure (D=3): - 0→0: identity track - 0→1: emit Z (open ZZ term) - 1→2: close with -J Z - 2→2: identity tail - 0→2: local field -h X

static heisenberg_hamiltonian(n_sites, Jx=1.0, Jy=1.0, Jz=1.0, device='cuda', dtype=torch.complex64)

Heisenberg Hamiltonian: H = Σᵢ (Jₓ XᵢXᵢ₊₁ + Jᵧ YᵢYᵢ₊₁ + Jᵧ ZᵢZᵢ₊₁)

static maxcut_hamiltonian(edges, weights=None, n_sites=None, device='cuda', dtype=torch.complex64)

MaxCut QAOA Hamiltonian for graph optimization: H = Σ_{(i,j)∈E} w_{ij} (1 - ZᵢZⱼ) / 2

This Hamiltonian encodes the MaxCut problem where we want to maximize the number of edges between two sets (minimize edges within sets).

Args:

edges: List of (i, j) tuples representing graph edges weights: Optional edge weights (default: all 1.0) n_sites: Number of nodes (inferred from edges if not provided) device: ‘cuda’ or ‘cpu’ dtype: torch dtype

Returns:

MPO representation of MaxCut Hamiltonian

Example:

```python # Triangle graph (nodes 0, 1, 2) edges = [(0,1), (1,2), (0,2)] H = MPOBuilder.maxcut_hamiltonian(edges, device=’cuda’)

# Use with QAOA from atlas_q import get_vqe_qaoa qaoa = get_vqe_qaoa() config = qaoa[‘QAOAConfig’](p=2, max_iter=100) solver = qaoa[‘QAOA’](H, config) energy, params = solver.run() ```

static from_local_terms(n_sites, local_terms, device='cuda', dtype=torch.complex64)

Build Hamiltonian from local interaction terms

Args:

n_sites: Number of sites local_terms: List of (site1, site2, operator) tuples

operator should be a 4x4 tensor for two-site interactions

device: torch device dtype: data type

Returns:

MPO representing sum of local terms

Example:

# Build ZZ interaction Hamiltonian Z = torch.tensor([[1, 0], [0, -1]], dtype=torch.complex64) local_terms = [(i, i+1, torch.kron(Z, Z)) for i in range(n_sites-1)] H = MPOBuilder.from_local_terms(n_sites, local_terms)

static molecular_hamiltonian_from_specs(molecule='H2', basis='sto-3g', charge=0, spin=0, mapping='jordan_wigner', device='cuda', dtype=torch.complex64)

Build molecular Hamiltonian from molecular specifications using PySCF.

This function computes the electronic Hamiltonian for a molecule and converts it to an MPO suitable for VQE or other quantum algorithms.

Args:

molecule: Molecular formula or geometry string

Examples: ‘H2’, ‘LiH’, ‘H2O’, or geometry string

basis: Gaussian basis set (sto-3g, 6-31g, cc-pvdz, etc.) charge: Total molecular charge spin: Spin multiplicity (2S, where S is total spin) mapping: Fermion-to-qubit mapping (‘jordan_wigner’, ‘bravyi_kitaev’, ‘parity’) device: ‘cuda’ or ‘cpu’ dtype: torch dtype

Returns:

MPO representation of molecular Hamiltonian

Example:

```python from atlas_q import get_mpo_ops, get_vqe_qaoa

# H2 molecule mpo_mod = get_mpo_ops() H = mpo_mod[‘MPOBuilder’].molecular_hamiltonian_from_specs(

molecule=’H2’, basis=’sto-3g’, device=’cuda’

)

# Run VQE vqe_mod = get_vqe_qaoa() config = vqe_mod[‘VQEConfig’](n_layers=2, max_iter=100) vqe = vqe_mod[‘VQE’](H, config) energy, params = vqe.run() print(f”Ground state energy: {energy:.6f} Ha”) ```

Note:

Requires pyscf package: pip install pyscf