Alice 0.2.0

Alice 0.2.0 — XTRG: Finite-Temperature Thermodynamics

Release Date: August 1, 2026

Version 0.2.0 introduces XTRG (eXponential Tensor Renormalization Group), Alice's
second algorithm alongside DMRG: a finite-temperature solver that computes the thermal
density matrix ρ(β) = e^{-βH} by repeated squaring, with the same three update schemes
(1s, 2s, 1sp) available in DMRG. Supporting this, NormalMPO is upgraded to track
its physical magnitude in log form, and observe is updated to compute thermal
expectation-value ratios in log-space, so both remain numerically stable arbitrarily deep
into a cooling run. Documentation is reorganized around an Algorithms section covering
DMRG and XTRG side by side. No breaking changes to the DMRG or AutoMPO public APIs.

🌡️ XTRG Algorithm

Exponential Cooling

• New alice.algorithm.xtrg package exporting Options, Summary, and run, mirroring
  the alice.algorithm.dmrg interface.
• xtrg.run(H, spc, opts) initializes ρ(τ₀) ≈ Σ_n (-τ₀)^n/n! H^n via thermal_mpo,
  then repeatedly squares it — ρ(2β) ≈ compress(ρ(β) ⊗ ρ(β)) — to reach
  β_max = 2^n_steps × τ₀, sampling an exponentially spaced β grid.
• Each squaring step is a variational MPO-MPO compression C ≈ A · B, minimizing
  ‖C − A·B‖²_F over opts.n_sweeps full forward-backward sweeps, built on a dedicated
  Environment/sweep kernel analogous to DMRG's but for the linear (non-eigenvalue)
  fitting problem.

Update Schemes

• 1-site (1s): single-tensor local update; preserves bond dimension exactly.
• 2-site (2s): two-tensor update with SVD truncation; drives automatic bond growth
  toward opts.max_bond.
• 1-site-plus (1sp): controlled bond expansion (CBE) adapted from DMRG's '1sp'
  scheme to the linear fitting problem — two independent single-tensor SVDs (one per
  factor-MPO connector bond) rather than a single joint SVD of the combined 2-site
  tensor.
• All three schemes accept scheme aliases (e.g. '2-site', 'two-site') resolved by
  Options.__post_init__, matching DMRG's convention.

Thermodynamic Observables

• Summary reports betas, log_z, free_energies, energies, specific_heats, and
  entropies at every cooling step, plus per-step discarded_weights.
• Internal energy u(β), specific heat c_V(β), and entropy S(β) are derived from
  log_z via log-β finite differences, giving uniform O((ln 2)²) discretization error
  across the exponential β grid — rather than the highly non-uniform error a linear-β
  finite difference would produce.
• Summary.serialize() / Summary.deserialize() round-trip the full thermodynamic
  history plus the density matrix through torch.save-compatible dicts.

Options and Checkpointing

• Options exposes scheme, tau_0, n_steps, taylor_order, max_bond,
  trunc_thresh, n_sweeps, env_cache_dir/env_async_io/env_window (disk-spilling
  environment cache, shared design with DMRG), expand_k/expand_alpha (CBE-only), and
  checkpoint_dir.
• checkpoint_dir atomically serializes ρ, the β/log Z history, and discarded weights
  to xtrg.ckpt after every completed cooling step (write-then-rename, same pattern as
  DMRG's dmrg.ckpt).
• A defensive _ensure_positive_trace guard raises RuntimeError if Tr[ρ(β)]'s sign
  ever drifts away from +1.0, surfacing numerical breakdown immediately rather than
  propagating a nonsensical log_z entry.

📏 NormalMPO: Log-Scale Representation

• NormalMPO.__init__ now takes log_scale (default 0.0) instead of scale
  (default 1.0); the new log_scale property is the primary, overflow-safe
  representation, and scale is now a derived getter (exp(log_scale), returning inf
  on overflow rather than raising).
• New log_trace() method returns (log|Tr[ρ]|, sign) without ever materializing the
  raw trace, which can reach ~10^500 deep into an XTRG run. trace() is now a thin
  wrapper over log_trace() for callers that only need a raw (possibly ±inf) float.
• New scale_by(log_scale_delta): in-place multiplicative update by combining
  log-magnitudes additively, used by XTRG's _fit_mpo to fold pre-computed physical
  scales into an already-compacted result.
• __matmul__, __add__, and __mul__ all combine log_scale by addition/subtraction
  rather than multiplying raw floats. The sign of the physical operator now lives
  directly in the tensor data (folded into site 0 via a -1.0 multiply when needed),
  since canonicalization is an exact gauge transform that cannot alter the value of a
  fully-contracted quantity such as Tr[ρ].

📈 observe: Log-Space Thermal Ratios

• _observe_thermal now computes Tr[ρ O] / Tr[ρ] by calling log_trace() on both the
  numerator and denominator and combining them as
  (sign_num · sign_den) × exp(log_num − log_den), rather than dividing two raw
  trace() calls. The ratio itself is a well-behaved O(1) number even when either
  trace individually overflows float64, so this keeps observe correct at arbitrarily
  low temperature.

📖 Documentation

• New docs/algorithms/ section (replacing algorithm pages formerly under docs/api/)
  with a top-level algorithms/index.md overview and per-algorithm subdirectories
  (algorithms/dmrg/, algorithms/xtrg/) each documenting Options, Summary, and
  run.
• New docs/examples/xtrg/ pages for the free-fermion and Hubbard worked examples,
  validating log_z, free energy, internal energy, and entropy against exact
  grand-canonical solutions.
• docs/api/network/normal-mpo.md and thermal-mpo.md updated for the log_scale API;
  mkdocs.yml navigation restructured around the new Algorithms section.
• README's Algorithms section gains an XTRG subsection alongside the existing DMRG one,
  plus a new Upcoming list (tanTRG, TDVP, TaSK) inviting contributions.

📚 Examples

• examples/examples_xtrg/xtrg_spinless.py: XTRG for the 1D spinless free-fermion chain,
  validated against the exact grand-canonical log Z, free energy, internal energy, and
  entropy at every cooling step.
• examples/examples_xtrg/xtrg_spinful.py: XTRG for the 1D spinful Hubbard chain.

📊 Statistics

• 916 tests across 29 test modules (up from 814 / 23 modules in v0.1.6).
• 66 commits since v0.1.6.
• 49 files changed, 6,172 insertions, 92 deletions.
• 28 source modules in four subpackages: alice.network, alice.physics,
  alice.algorithm.dmrg, alice.algorithm.xtrg.

✅ Compatibility

Breaking Changes:

• NormalMPO.__init__ keyword argument renamed from scale to log_scale
  (log_scale = log(scale)); code constructing NormalMPO directly with scale=
  must switch to log_scale=math.log(scale). NormalMPO.from_mpo(), thermal_mpo(),
  and the scale read-only property are unaffected.

Requirements:

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

📝 Notes

XTRG follows the same overall shape as DMRG wherever the two algorithms are conceptually
alike: Options/Summary follow AlgorithmOptions/AlgorithmSummary, the 1s/2s/1sp
scheme names and aliases are identical, and the disk-spilling Environment cache reuses
DMRG's sliding-window-plus-async-I/O design. This consistency makes the two algorithms
easy to learn together. Underneath, though, XTRG solves a different mathematical problem:
its inner loop is a linear least-squares fit (C ≈ A·B) rather than an eigenvalue
problem, with its own environment contractions and local updates living in dedicated
environ.py/sweep.py modules within alice.algorithm.xtrg.

The log-scale rework of NormalMPO was driven directly by XTRG: Tr[ρ] is squared at
every cooling step, so a chain that starts near Tr[ρ(τ₀)] ≈ L (small β) can reach
Tr[ρ(β_max)] ≈ 10^500 or beyond after twenty doubling steps, far outside float64 range.
Tracking log_scale and only ever combining it by addition/subtraction — never by
exponentiating an intermediate magnitude — is what keeps log Z, and therefore every
derived thermodynamic observable, finite and accurate across the full temperature range.