Alice 0.2.5

Alice 0.2.5 — Independent Artifact Storage for DMRG and XTRG

Release Date: August 19, 2026

Version 0.2.5 decouples archived-artifact storage from the checkpoint directory in
both dmrg.run() and xtrg.run(), via a new Options.artifacts_dir. DMRG gains
final-state archiving to match XTRG's existing per-step archiving: on success, the
final Summary is written to state.ckpt under artifacts_dir and the now-redundant
per-sweep dmrg.ckpt is removed. XTRG's mid-run Artifact file is renamed from
progress.ckpt to xtrg.ckpt. Two breaking changes, both to on-disk file names.

📦 artifacts_dir: Decoupled from checkpoint_dir

• New Options.artifacts_dir on both dmrg.Options and xtrg.Options (default
  None, resolving to artifacts/ under checkpoint_dir). Passing an explicit path
  archives artifacts elsewhere — e.g. faster or larger storage — independent of where
  per-sweep/per-step checkpoints themselves live.
• XTRG's save_artifacts/save_artifacts_since now write step_XX.ckpt files under
  artifacts_dir instead of always under checkpoint_dir/artifacts.
• Both run()s log the resolved artifacts directory in their startup banner.
• artifacts_dir round-trips through to_toml/load_toml like every other option.

💾 DMRG Final-State Archiving

• Breaking: dmrg.run() now archives its final Summary as state.ckpt (atomic
  write via state_lock.ckpt → rename) under artifacts_dir on success, then removes
  the per-sweep dmrg.ckpt/dmrg_lock.ckpt from checkpoint_dir, since they are
  redundant with the archived artifact. Previously dmrg.ckpt was left on disk after a
  successful run; callers that read dmrg.ckpt post-run must switch to
  artifacts_dir/state.ckpt.
• Unlike the per-sweep checkpoint, the archived Summary carries the correct
  converged flag, since it is built after the sweep loop exits rather than while
  still in progress.
• New _save_final_artifact helper mirrors XTRG's _save_artifact_file pattern.

🏷️ XTRG xtrg.ckpt Rename

• Breaking: the mid-run Artifact checkpoint is renamed from progress.ckpt to
  xtrg.ckpt (and its lock file from progress_lock.ckpt to xtrg_lock.ckpt),
  aligning the name with DMRG's dmrg.ckpt as each algorithm's own per-run checkpoint
  file. Behavior is unchanged: written every step, removed on successful completion.
• run()'s docstring, module docstring, and the resumption example now reference
  xtrg.ckpt throughout.

🧪 Tests

• New TestArtifact class in test_dmrg.py: state.ckpt creation, lock-file cleanup,
  round-trip loading (including a correct converged flag on a converged run), default
  placement under checkpoint_dir/artifacts, and an artifacts_dir decoupled from
  checkpoint_dir.
• TestCheckpoint in test_dmrg.py updated: dmrg.ckpt is now asserted absent after a
  successful run rather than present.
• New test_artifacts_dir_defaults_to_none/test_artifacts_dir_toml_round_trip in both
  test_dmrg.py and test_xtrg.py; new
  test_artifacts_dir_decoupled_from_checkpoint_dir in test_xtrg.py.
• test_progress_removed_after_success renamed to test_checkpoint_removed_after_success
  and updated for xtrg.ckpt.

📚 Documentation

• artifact.md's on-disk layout diagram gains the artifacts_dir directory and the
  progress.ckpt → xtrg.ckpt rename; Options cross-link updated to mention
  artifacts_dir.
• index.md's resumption example and both example scripts' docstrings/CLI help updated
  from progress.ckpt to xtrg.ckpt.

📊 Statistics

• 954 tests across 29 test modules (up from 946 / 29 modules in v0.2.4).
• 11 commits since v0.2.4.
• 9 files changed, 214 insertions, 69 deletions.
• 28 source modules in four subpackages: alice.network, alice.physics,
  alice.algorithm.dmrg, alice.algorithm.xtrg (unchanged from v0.2.4).

✅ Compatibility

Breaking Changes:

• dmrg.run() no longer leaves dmrg.ckpt on disk after a successful run; the final
  Summary must instead be read from artifacts_dir/state.ckpt (default
  checkpoint_dir/artifacts/state.ckpt). Mid-run, dmrg.ckpt is unaffected.
• XTRG's mid-run progress.ckpt is renamed to xtrg.ckpt; callers resuming from a
  file loaded by path (rather than via Options.checkpoint_dir auto-discovery) must
  update the filename. Checkpoints written by v0.2.4 or earlier as progress.ckpt
  still load — the Artifact.load call itself is unaffected — but run() will not
  find them under the new name for auto-recovery of thermal.ckpt history.

Requirements:

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

📝 Notes

DMRG and XTRG previously diverged in how they treated their working checkpoint versus
a durable result: XTRG already separated thermal.ckpt (thermodynamic history, kept)
from progress.ckpt (working state, discarded on success) and archived per-step
Artifacts, while DMRG only ever wrote one file, dmrg.ckpt, and left it behind
regardless of outcome — indistinguishable from a crash checkpoint. Giving DMRG the same
archived-final-state pattern removes that ambiguity, and factoring artifacts_dir out
of checkpoint_dir in both algorithms lets long-running jobs keep small, frequently
overwritten checkpoints on fast local storage while sending durable artifacts to
larger, possibly network-backed storage, without the two being forced to colocate.