Alice 0.2.2

Alice 0.2.2 — XTRG: Specific Heat and Cache Isolation

Release Date: August 14, 2026

Version 0.2.2 fixes the sign of XTRG's specific heat, which was reported negative for
every physical Hamiltonian, and isolates XTRG's environment disk cache per run so that
concurrent jobs sharing one env_cache_dir no longer overwrite each other's blocks —
the same scheme DMRG adopted in v0.1.5. The remainder of the release is a
consistency pass over the whole codebase: American English spelling, "index" in place
of "leg", modern lowercase type annotations, and role-based einsum index names. No
breaking changes.

🔬 Specific Heat Sign Fix

• Bug fixed: _compute_observables computed c_V[n] = β_n Δu / ln 2, dropping the
  minus sign in c_V = ∂u/∂T = −β² ∂u/∂β = −β ∂u/∂(ln β). Since u increases with
  temperature (decreases with β), the reported specific heat was negative wherever the
  true value is positive — that is, for every physical Hamiltonian.
• Both the interior stencil and the trailing one-sided stencil at the last β point now
  carry the correct sign, and the derivation is spelled out in a comment above the loop
  so the chain rule from ∂u/∂T to Δu / ln 2 is auditable in place.
• free_energies, energies, and entropies are unaffected; a v0.2.1 thermal.ckpt
  remains loadable, but its specific_heats entries must be negated to be correct.

💾 XTRG Environment Cache Isolation

• xtrg.run() now creates a unique subdirectory (first 8 hex characters of a UUID4,
  e.g. {env_cache_dir}/a1b2c3d4/) inside env_cache_dir per invocation. Previously,
  concurrent runs sharing the same env_cache_dir all wrote to the same xtrg_left/
  and xtrg_right/ paths and could corrupt each other's cached blocks.
• The unique subdirectory is reused by every squaring step of the run and removed in a
  finally block on return or exception, leaving no stale files behind; removal ignores
  errors so a partially written directory cannot mask the real exception from the
  cooling loop.
• Cache-directory resolution moves from _fit_mpo up to run(). _fit_mpo gains a
  cache_dir parameter carrying the already-unique path, and ignores
  opts.env_cache_dir entirely — making the caller responsible for collision freedom.
• Options.env_cache_dir docstring updated to document the subdirectory scheme, the
  xtrg_left/{i:05d}.pt / xtrg_right/{i:05d}.pt layout, and the automatic cleanup.
  The resolved path is logged in run()'s startup banner.

🧹 Consistency Pass

• Spelling: all comments, docstrings, and documentation pages converted to American
  English (initialize, normalize, minimize, recognized, discretization).
  run()'s ValueError and NotImplementedError messages for unknown schemes now read
  "recognized values are: …".
• Terminology: "leg" is gone from comments and docstrings. Tensor ranks are described
  as "2nd-order" / "6th-order", and connector or physical legs are now connector or
  physical indices, matching the vocabulary used throughout Nicole.
• Type annotations: XTRG's Options, Summary, Artifact, and helpers drop
  typing.Dict / typing.List for builtin dict / list; deserialize return
  annotations are unquoted forward references. sweep.forward_sweep, backward_sweep,
  and _unpack_opts gain a real Options annotation under TYPE_CHECKING, replacing
  the previously untyped opts parameter.
• einsum naming: _observe_mps's transfer-matrix contraction is rewritten from
  einsum('ace,abg,cdgh,efh->bdf', …) to einsum('aob,acr,oprs,bds->cpd', …), so
  a–d are MPS bonds, o/p are MPO bonds, and r/s are physical indices, per
  the project's index-naming convention. The Notes block documenting the letters was
  updated in step.
• Environment._submit's synchronous fallback in both DMRG and XTRG avoids the
  intermediate result variable, per the naming convention.

🧪 Tests

• New TestComputeObservables class with a specific-heat sign test built on a two-level
  system (E = 0, 1), whose internal energy decreases monotonically with β and therefore
  must give a positive c_V at every grid point.
• New TestEnvCache class covering the caching scheme end to end: the unique
  subdirectory is created inside env_cache_dir and removed on success, two successive
  runs pick distinct subdirectories and leave no files behind, a cached run reproduces
  the in-memory run's thermodynamics, and env_cache_dir survives a TOML round trip.
• test_scheme_1s's idempotency test gains a _mixed_canonical_envs helper that builds
  the environments surrounding the center in the compressed MPO's canonical frame, which
  is the frame in which the 1-site update is a true variational optimum; the test now
  checks the converged fit against that instead of an unmixed frame.
• Unused imports and unused variable assignments removed across the test suite.

📖 Documentation

• New Environment caching for large chains section in the XTRG free-fermion example,
  explaining why XTRG exhausts RAM at shorter chains than DMRG (three networks live at
  once per squaring step) and how env_cache_dir, env_window, and env_async_io
  interact.
• The DMRG Hubbard example's environment-caching note now describes the per-run
  subdirectory and its automatic removal.

📊 Statistics

• 937 tests across 29 test modules (up from 930 / 29 modules in v0.2.1).
• 44 commits since v0.2.1.
• 48 files changed, 528 insertions, 313 deletions.
• 28 source modules in four subpackages: alice.network, alice.physics,
  alice.algorithm.dmrg, alice.algorithm.xtrg (unchanged from v0.2.1).

✅ Compatibility

Breaking Changes:

• None — fully backward compatible with v0.2.1. Note, however, that the
  specific_heats values produced by v0.2.1 (and v0.2.0) have the wrong sign; a
  checkpoint from those versions still loads, but its specific_heats entries must be
  negated before use.

Requirements:

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

📝 Notes

Both fixes in this release are about trusting XTRG's output. The specific-heat sign error
was invisible in the convergence diagnostics — log_z and the discarded weights were
always correct, and c_V had a plausible magnitude and peak position, only the wrong
sign — which is exactly the class of bug that survives until someone plots the curve
against a known reference. The cache collision was similarly quiet: two runs launched on
the same node with a shared env_cache_dir would each read blocks the other had written,
producing a silently wrong compression rather than an error. Isolating the cache per run
brings XTRG in line with what DMRG has done since v0.1.5, so neither algorithm now
requires the caller to hand-partition the cache root across jobs.