Alice 0.1.6

Alice 0.1.6 — MPS Initialization for Odd Chains

Release Date: June 10, 2026

Version 0.1.6 extends init_mps with explicit quantum-number targeting, fixes a silent
zero-MPS bug for odd-L random initializations, and upgrades the warning system to use
Python's standard logging module. No breaking changes.

🔢 init_mps: target_qn Parameter

• New keyword argument target_qn on init_mps: specifies the desired right-boundary
  charge Q[L] — the total quantum number of the chain. When None (default) the target
  is Q_vac (half-filling), preserving existing behavior for even-L even-filling cases.
• Both modes honor target_qn:
  • Product state (bond_dim=1): _auto_config targets target_qn; the resulting
    bond charge path Q[0..L] must end at target_qn. The right boundary is always
    Q[L] (rigid, determined by the charge path).
  • Random MPS (bond_dim>1): _auto_config targets target_qn to obtain a
    physically appropriate center-bond charge; the right boundary index is then pinned
    explicitly to target_qn, decoupling the boundary from the path.
• When an explicit target_qn is given and the auto-config cannot reach it (e.g.
  target_qn=0 for odd-L spin-½), init_mps raises a ValueError in both modes
  rather than silently constructing an MPS in the wrong sector.

🔧 Odd-L Random MPS Fix

• Bug fixed: for odd chain lengths with the default target_qn=None, _random_mps
  previously pinned both boundary indices to Op['vac'] (charge Q_vac). Because no
  site configuration can return the bond charge to Q_vac in an odd number of fusion
  steps, every charge block of the last tensor was forbidden, and the MPS canonicalized
  to zero.
• The right boundary index is now constructed with effective_right = Q[L] (the actual
  charge at the end of the auto-config path) when target_qn was not given explicitly.
  For even L this is still Q_vac; for odd L it is the correct non-vacuum charge,
  producing a non-zero MPS with the expected sector.
• The Op parameter of _random_mps has been removed (internal cleanup); the left
  boundary is now built from Q[0] and the right boundary from target_qn or
  effective_right.

🔔 Warning System Upgrade

• init_mps no longer calls warnings.warn(UserWarning) when the auto-config cannot
  close to Q_vac (e.g. odd L). The message is now emitted via
  logging.getLogger(__name__).warning(...), consistent with Alice's structured logging
  infrastructure. The message text recommends passing target_qn explicitly.
• The module-level import warnings is replaced by import logging and a
  logger = logging.getLogger(__name__) instance.

♻️ _auto_config Generalization

• _auto_config(L, Spc, group, Q_vac, target_qn) — the function now accepts a
  target_qn parameter (previously hardcoded to Q_vac). All three internal strategies
  (single-sector fill, period-2 alternation, greedy fallback) target target_qn rather
  than Q_vac.
• The period-2 alternation strategy no longer applies a per-period shortcut; the full
  length-L path is checked against target_qn for correctness with any target, not just
  Q_vac.
• The greedy fallback minimizes _charge_dist(Q_next, target_qn) instead of
  _charge_dist(Q_next, Q_vac). For Abelian 2-sector spaces this reaches target_qn
  exactly when it is achievable.
• _auto_config is now a pure helper with no side effects; the single warning site is
  init_mps.

📖 Documentation

• docs/api/network/init-mps.md gains three new sections:
  • Logic Overview — ASCII decision diagram showing how target_qn, config,
    Q[L], and bond_dim interact inside init_mps.
  • Odd-chain lengths — explains the default WARNING behavior, the target_qn
    fix path, and the ValueError guard; includes a runnable spin-½ example.
  • Updated Bond Sectors in Random Mode — clarifies that BFS is seeded from the
    center-bond charge Q_c = Q[L//2] of the targeted auto-config, not from Q_vac.
• The Charge Conventions section is updated to note that the center-bond charge is
  zero only for even L with a balanced auto-config.

📊 Statistics

• 814 tests across 23 test modules (up from ~795 / 23 modules in v0.1.5)
• 5 commits since v0.1.5
• 4 files changed, 423 insertions, 89 deletions
• 22 source modules in three subpackages: alice.network, alice.physics,
  alice.algorithm.dmrg

✅ Compatibility

Breaking Changes: None — fully backward compatible with v0.1.5. All import paths,
function signatures (except the internal _random_mps and _auto_config), TOML
configuration keys, and geometry APIs are unchanged. Existing calls to init_mps
without target_qn behave identically to v0.1.5 for even-L chains; odd-L chains no
longer silently produce a zero random MPS.

Requirements:

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

📝 Notes

The zero-MPS bug for odd-L random initialization was a silent correctness issue: no
exception was raised, DMRG would accept the zero state, and all energies would be
numerically zero or NaN after the first sweep. The fix is unconditional — the right
boundary is always set to the charge that the auto-config actually reaches.

The target_qn parameter also matters for even-L systems with non-half-filling targets
(e.g. a doped chain) or any case where the desired sector differs from Q_vac. Before
this release, such cases required passing an explicit config; target_qn now provides
a higher-level interface that delegates sector arithmetic to _auto_config.