Alice 0.2.1

Alice 0.2.1 — XTRG: Density-Matrix Artifacts

Release Date: August 7, 2026

Version 0.2.1 splits XTRG's density matrix out of Summary into a new Artifact
dataclass, and reworks checkpointing around that split: thermal.ckpt tracks the
thermodynamic history alone, progress.ckpt protects the latest density matrix against a
mid-run crash, and an optional artifacts/ archive keeps a caller-chosen range of
per-step density matrices on disk for computing additional observables later without
rerunning the cooling schedule. xtrg.run() now returns (Summary, Artifact). Breaking
change to xtrg.run()'s return signature and Summary's fields.

💾 Artifact and Checkpointing

Artifact

• New Artifact(AlgorithmSummary) dataclass: a single density-matrix snapshot holding
  rho (NormalMPO), beta, and step. Step 0 is after Taylor init (ρ(τ₀)); step
  k is after the k-th squaring.
• Own serialize() / deserialize() (version 1, torch.save-compatible), matching the
  pattern used by Summary and dmrg.Summary.
• Exported from alice.algorithm.xtrg alongside Options, Summary, and run.

Summary Is Now Density-Matrix Free

• Summary drops its rho and rho_log_scale fields entirely, keeping only the
  thermodynamic history (betas, log_z, free_energies, energies,
  specific_heats, entropies, discarded_weights).
• serialize() / deserialize() bump to version 2 and reject version-1 (rho-carrying)
  payloads with a ValueError, so a stale checkpoint from v0.2.0 fails loudly rather
  than silently losing the density matrix.

Checkpoint Files

• thermal.ckpt replaces xtrg.ckpt: written after every squaring step and once more
  at the end, holding the latest rho-free Summary.
• progress.ckpt is new: holds the latest Artifact while a run is in flight, and is
  deleted (along with its lock file) once run() finishes successfully, so a completed
  run leaves no stale mid-run state behind. A crash leaves it on disk for inspection or
  manual recovery.
• checkpoint_dir now defaults to the current working directory (resolved when run()
  is called) rather than disabling checkpointing when unset, matching the convention
  already used by .logging.

Artifact Archive

• New Options.save_artifacts (default True) and Options.save_artifacts_since
  (default 0, must be non-negative) control an artifacts/ subdirectory under
  checkpoint_dir, where every step from save_artifacts_since onward is written to
  its own zero-padded step_XX.ckpt file via Artifact.
• This lets a caller keep exactly the temperature range they expect to need for later
  analysis, without paying to permanently archive every step by default.

📚 Examples

• xtrg_spinless and xtrg_spinful now return (Summary, Artifact) and accept
  save_artifacts / save_artifacts_since keyword arguments, threaded through to
  Options.
• New --no-save-artifacts and --save-artifacts-since K CLI flags;
  --checkpoint-dir help text updated to describe the new thermal.ckpt /
  progress.ckpt / artifacts/ layout.

📖 Documentation

• New docs/algorithms/xtrg/artifact.md documenting Artifact, the on-disk checkpoint
  directory layout, and a load-from-disk example; added to the Algorithms navigation
  between Summary and Launch.
• index.md, options.md, summary.md, and run.md cross-links updated for the
  Summary/Artifact split and the (Summary, Artifact) return tuple.
• Free-fermion and Hubbard worked examples updated to unpack both the summary and the
  artifact from xtrg.run(...).

📊 Statistics

• 930 tests across 29 test modules (up from 916 / 29 modules in v0.2.0).
• 19 commits since v0.2.0.
• 14 files changed, 545 insertions, 142 deletions.
• 26 source modules in four subpackages: alice.network, alice.physics,
  alice.algorithm.dmrg, alice.algorithm.xtrg (unchanged from v0.2.0 — this release
  restructures xtrg.py rather than adding new modules).

✅ Compatibility

Breaking Changes:

• xtrg.run() now returns (Summary, Artifact) instead of a single Summary; call
  sites that previously wrote summary = xtrg.run(...) must switch to
  summary, artifact = xtrg.run(...).
• Summary no longer has rho or rho_log_scale fields; the density matrix is now
  reached via the separately returned Artifact.rho, or via Artifact.load(...) from
  an archived artifacts/step_XX.ckpt file.
• Checkpoint file names changed: xtrg.ckpt is replaced by thermal.ckpt (rho-free
  Summary) and the new progress.ckpt (latest Artifact); a v0.2.0 xtrg.ckpt file
  is not loadable by Summary.load() in this version (see version-1 rejection above).

Requirements:

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

📝 Notes

The motivation for this split is that a caller generally needs many
intermediate-temperature density matrices — not just the final one — to compute
additional observables later without rerunning the whole cooling schedule. Archiving
rho at every step unconditionally would be wasteful, since most steps are never
revisited; separating Artifact out of Summary is what makes the choice of which
steps to keep possible in the first place. thermal.ckpt stays cheap and is always
written in full, since it never carries rho, while permanent archiving of rho is
opted into per step through save_artifacts_since. progress.ckpt sits outside that
policy entirely: it tracks only the single most recent Artifact, so a crash mid-run
does not lose the current density matrix regardless of which steps the caller chose to
archive.