Alice 0.1.3

Alice 0.1.3 — MPS Init and DMRG Checkpointing

Release Date: May 13, 2026

Version 0.1.3 introduces a universal MPS initializer (init_mps) that replaces the
per-example _random_mps helpers with a single particle-type–agnostic function, adds
atomic per-sweep checkpointing to DMRG, and exposes Network.bond_states for
non-Abelian state counts. No breaking changes.

🔧 Universal MPS Initializer

init_mps

• New alice.network.automps module implementing init_mps: a single entry point for
  constructing an initial MPS for DMRG from any (Spc, Op) pair returned by
  load_space.
• Supports bosonic, fermionic, and conductor sites without a separate particle_type=
  argument; the (Spc, Op) pair encodes all symmetry information.
• Two modes controlled by bond_dim:
  • bond_dim=1 — deterministic product state with exact charge targeting.
    Every bond carries a single sector determined by the per-site configuration.
    Best used with CBE (scheme='1sp') or 2-site (scheme='2s') DMRG, which
    expand bond dimension during the first sweep.
  • bond_dim>1 — random MPS with group-derived bond sectors. Reachable
    charges are selected by BFS from the center-bond charge to depth 2, keeping
    the sector count independent of chain length.
• Auto-balanced site configuration (config=None): alternating high/low sectors for
  2-sector spaces, single neutral-charge sector for 3-sector spaces, alternating
  neutral-pair for 4-sector spaces, and the SU(2) dimer path for pure-SU(2) spaces.
  Explicit config lists override the auto-selection for unusual fillings or odd L.
• Charge conventions follow the Nicole standard (particle-hole symmetric): center-bond
  charge is always in {0, (0,0), (0,...)} for auto-balanced even-L chains.
• init_mps is exported from the alice top-level namespace and from alice.network.

DMRG Examples Updated

• dmrg_heisenberg.py, dmrg_freefermion.py, and dmrg_conductor.py updated to
  accept an init parameter ('iter_diag' or 'random'), using init_mps for the
  random-initialization path; the per-example _random_mps helpers are removed.

💾 DMRG Checkpointing

dmrg.Options.checkpoint_dir

• New checkpoint_dir option in dmrg.Options: after every completed sweep, the
  current state is serialized atomically to dmrg.ckpt in the specified directory.
• Write strategy: data is first written to dmrg_lock.ckpt, then renamed to
  dmrg.ckpt. On POSIX systems the rename is atomic, so a crash during
  serialization cannot corrupt the previous checkpoint.
• The checkpoint file is in PyTorch format and loadable via dmrg.Summary.load.
• checkpoint_dir defaults to None, which resolves to the current working directory
  at run() call time (matching .logging). Stored as str for TOML compatibility.

📐 Network.bond_states

• New bond_states property on Network (and hence MPS and MPO): returns the
  number of physical states per internal bond (length L - 1).
• Entry i is index.num_states for the right bond of site i, which equals the
  left bond of site i+1.
• For Abelian symmetry groups (U(1), Z(2)) bond_states is identical to bond_dims.
  For non-Abelian groups (e.g. SU(2)) it is larger: each multiplet of spin j
  contributes 2j+1 states, making bond_states the physically relevant measure
  of truncation in SU(2) simulations.

📖 Documentation

New API Page

• init_mps: full function reference with parameter table, charge-convention notes,
  mode descriptions, and runnable examples for Heisenberg and free-fermion cases.

Updated Pages

• Network class reference: bond_states property added.
• Quick-start guide updated to use init_mps for MPS construction and the standard
  Summary.save / Summary.load checkpoint interface.
• Navigation (mkdocs.yml): init-mps.md added under the Network section.

📊 Statistics

• ~700 tests across 22 test modules (up from ~650 / 21 modules in v0.1.2)
• 16 commits since v0.1.2
• 17 files changed, 1,319 insertions, 187 deletions
• 21 source modules in three subpackages: alice.network, alice.physics,
  alice.algorithm.dmrg

✅ Compatibility

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

Requirements:

• Python ≥ 3.11
• PyTorch ≥ 2.5
• Nicole ≥ 0.3.6

📝 Notes

init_mps was introduced because every DMRG example script was reimplementing its own
_random_mps helper with hardcoded charge heuristics that only worked for one particle
type. The helpers were redundant, hard to maintain, and accumulated subtle differences
over time. init_mps centralizes that logic once: the (Spc, Op) pair from
load_space already encodes the group structure, so no separate particle_type=
argument is needed, and the auto-balanced _auto_config heuristic covers all standard
even-L half-filled cases without user input.

The checkpointing mechanism was the last missing piece of the DMRG restart workflow.
Summary.load / Summary.save already existed for post-run storage; checkpoint_dir
extends them to in-run checkpointing so that a long simulation interrupted by a wall-time
limit or hardware fault can be resumed from the last completed sweep.