Alice 0.2.3

Alice 0.2.3 — XTRG: Convergence-Based Early Termination

Release Date: August 17, 2026

Version 0.2.3 lets XTRG's variational compression terminate before exhausting its sweep
budget once it has converged, via a new Options.z_tol tolerance on ‖C‖ between
sweeps. Summary.converged is renamed to Summary.finished to say what it actually
means: whether the summary comes from a completed run() call or a mid-run checkpoint,
not whether the fit converged. One breaking change to Summary's fields.

🎯 Early-Termination Compression Fit

• New Options.z_tol (default 1e-10): _fit_mpo now terminates sweeping once
  |‖C‖ − ‖C_prev‖| < z_tol, where ‖C‖ is the Frobenius norm of the compressed
  density matrix read from the orthogonality-center tensor after each full sweep.
  n_sweeps becomes a maximum rather than a fixed count.
• The criterion is exact, not heuristic: because each local update is a least-squares
  projection, ⟨C, A·B⟩ = ‖C‖² at the optimum, so ‖C − A·B‖²_F = ‖A·B‖² − ‖C‖² with
  ‖A·B‖ fixed across sweeps — convergence of ‖C‖ is equivalent to convergence of the
  fit residual, and norm() reads it from the already-isometric center tensor with no
  extra contraction.
• z_tol=0.0 restores the previous fixed-sweep-count behavior exactly, since a norm
  difference can never be negative. run()'s startup banner now logs the configured
  fit convergence threshold alongside sweeps-per-step.
• Options.max_bond's docstring is expanded to clarify that the option is meaningful
  for both 2-site and 1-site-plus (SVD-truncation-controlled growth), and a no-op for
  1-site beyond the initial compaction.

🏷️ Summary.finished Rename

• Breaking: Summary.converged is renamed to Summary.finished. The field never
  reflected fit convergence — it was True for the summary returned by a completed
  run() call and False only for mid-run thermal.ckpt snapshots written after an
  interruption. finished names that meaning directly and avoids confusion with the
  new, unrelated z_tol fit-convergence criterion.
• serialize()/deserialize() updated in step; the serialization version stays at 2.
  A v0.2.2 thermal.ckpt still loads, but its converged key is not read — reloaded
  summaries always report finished=True regardless of whether the original run
  completed, since deserialize has no converged key to fall back to.

🧪 Tests

• New TestFitMpoZTol class: a loose z_tol stops well short of n_sweeps, z_tol=0.0
  always runs the full sweep budget, and an early-terminated fit reproduces the log_z
  trajectory of an equivalent full-sweep run to high precision.
• Existing Summary and checkpoint round-trip tests updated for the finished rename.

📊 Statistics

• 940 tests across 29 test modules (up from 937 / 29 modules in v0.2.2).
• 10 commits since v0.2.2.
• 3 files changed, 119 insertions, 20 deletions.
• 28 source modules in four subpackages: alice.network, alice.physics,
  alice.algorithm.dmrg, alice.algorithm.xtrg (unchanged from v0.2.2).

✅ Compatibility

Breaking Changes:

• Summary.converged is renamed to Summary.finished; any caller reading
  summary.converged directly must switch to summary.finished. A thermal.ckpt
  written by v0.2.2 or earlier still loads, but reloads as finished=True
  unconditionally, since the old converged key is no longer consulted.

Requirements:

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

📝 Notes

A fixed n_sweeps forces every squaring step to pay for the hardest step in the run,
even though how many sweeps a given step actually needs to converge varies — ρ's
entanglement, and therefore the difficulty of the variational fit, changes as β grows
over the course of a cooling run. z_tol lets each step stop as soon as its own fit has
actually converged, so n_sweeps can be set generously as a safety ceiling without
paying its full cost on every step. The finished rename is purely clarifying — no
runtime behavior changes — but was worth doing now, before z_tol introduced a second,
genuinely convergence-related field that could easily be confused with it.