Alice 0.1.4

Alice 0.1.4 — Thermal Density Matrix

Release Date: May 31, 2026

Version 0.1.4 introduces thermal density matrix support via a Taylor-series MPO
expansion. The new NormalMPO class and thermal_mpo function allow computing
finite-temperature expectation values directly within the existing observe workflow.
No breaking changes.

🌡️ Thermal Density Matrix

NormalMPO

• New NormalMPO class in alice.network.thermal: an MPO subclass that represents an
  operator as scale × mpo_unit, where the internal MPO satisfies norm() ≈ 1 and the
  true physical magnitude is carried in a separate _scale attribute.
• Arithmetic operations preserve the unit-norm convention analytically:
  • __matmul__ (@) — MPO–MPO product via site-by-site tensor contraction and
    left/right bond fusion using merge_axes; scale updated as the product of the two
    _scale values.
  • __add__ (+) — MPO–MPO sum; relative weight other._scale / self._scale is
    distributed uniformly across sites as weight^(1/L) per site via oplus, following
    the same bond-axis convention as build_hamiltonian.
  • __mul__ / __rmul__ (*) — scalar multiplication; only _scale is
    updated, site tensors are not touched.
• compact(trunc=None) performs two-sweep SVD compression and folds the extracted norm
  into _scale; bond arrow directions are restored by capcup after the sweeps so that
  subsequent trace() and observe() calls work correctly.
• Class method NormalMPO.from_mpo(mpo) constructs a NormalMPO from any plain MPO:
  clones the tensors, canonicalizes to site 0, and uses the Frobenius norm as _scale.
• scale property (read-only) exposes _scale.
• Exported from alice.network and the alice top-level namespace.

thermal_mpo

• New function thermal_mpo(H, beta, order, spc, trunc, coeff_thresh) in
  alice.network.thermal: approximates ρ(β) = exp(−βH) via the truncated Taylor
  series

  $$\rho(\beta) \approx \sum_{n=0}^{N} \frac{(-\beta)^n}{n!} H^n$$

  where H^0 = I is an L-site identity MPO built from spc.

• Bond dimensions are controlled by calling compact() after every addition and every
  power step; early exit when the Taylor coefficient |β^n / n!| drops below
  coeff_thresh (default 1e-15).

• The returned NormalMPO carries _scale ≈ Z = Tr[ρ] (up to the MPO norm), so a
  single trace suffices to extract the partition function.

• Exported from alice.network and the alice top-level namespace.

observe updated for NormalMPO

• alice.network.observe.observe now accepts a NormalMPO as the state argument in
  addition to the existing MPS and MPO types.
• When a NormalMPO is passed, observe forms the MPO product ρ @ O, compresses it
  with compact(), and returns Tr[ρ O] / Tr[ρ] — the normalized thermal expectation
  value.

📖 Documentation

New API Pages

• NormalMPO: class reference with parameter table, arithmetic-operation descriptions,
  and notes on the unit-norm convention.
• thermal_mpo: function reference with parameter table, Taylor-series formula, and
  notes on early stopping and bond growth.

Updated Pages

• alice.network index page: NormalMPO and thermal_mpo added to the module summary
  and navigation entry.
• observe reference: NormalMPO added to the accepted state types.
• Navigation (mkdocs.yml): normal-mpo.md and thermal-mpo.md added under the
  Network section.

📊 Statistics

• ~740 tests across 23 test modules (up from ~700 / 22 modules in v0.1.3)
• 13 commits since v0.1.3
• 9 files changed, 1,192 insertions, 10 deletions
• 22 source modules in three subpackages: alice.network, alice.physics,
  alice.algorithm.dmrg

✅ Compatibility

Breaking Changes: None — fully backward compatible with v0.1.3. All import paths,
function signatures, TOML configuration keys, and geometry APIs are unchanged.

Requirements:

• Python ≥ 3.11
• PyTorch ≥ 2.5
• Nicole ≥ 0.3.7

📝 Notes

NormalMPO addresses a numerical stability problem intrinsic to MPO arithmetic: repeated
matrix products cause the Frobenius norm to grow or shrink exponentially with chain length
and expansion order. Keeping the internal tensors at unit norm and tracking the physical
magnitude in a scalar decouples the truncation from the scale, so compact() can safely
apply an SVD threshold relative to the largest singular value without being misled by an
overall factor that differs by many orders of magnitude.

thermal_mpo uses this representation throughout the Taylor accumulation loop: both
H_pow (the running power H^n) and rho (the partial sum) are kept as NormalMPO
instances and compressed after every update. The early-stopping condition on the Taylor
coefficient provides an automatic check that the series has converged to double-precision
accuracy, independent of the value of order.