Alice 0.2.8

Alice 0.2.8 — N-Site Terms as Verbatim Windows

Release Date: September 22, 2026

Version 0.2.8 adds InteractionNSite, a third Interaction subclass for Hamiltonian
terms carrying more than two operators. Unlike Interaction1Site and Interaction2Site,
which name their sites and let build_hamiltonian synthesize the operator string in
between, an InteractionNSite supplies the entire contiguous window verbatim — one
tensor per site from min(sites) to max(sites), including the identity and
Jordan-Wigner string tensors on sites carrying no operator. build_hamiltonian accepts
the new subclass and now rejects unrecognized Interaction subclasses instead of
silently adding a bare identity term. No breaking API changes.

🧩 InteractionNSite

• New dataclass in alice.network.interaction, exported from alice.network and the
  top-level alice namespace. It adds two fields to Interaction: sites, the operator
  site indices in operator order (e.g. [m, n, k, l] for c†_m c†_n c_k c_l), and
  tnsrs, the contiguous list of 4-index MPO tensors covering the window.
• sites is metadata for the model builder; placement depends only on the span it
  covers, so any permutation of the window is accepted and build_hamiltonian reads only
  min(sites) and max(sites).
• tnsrs[offset] goes at site min(sites) + offset, with axes
  (L_bond_IN, R_bond_OUT, bra_OUT, ket_IN). The two outer bonds of the window must be
  trivial (dim-1, charge-neutral) so the term composes with the identity tensors on the
  remaining sites.
• A term whose operators are not contiguous is expressed by padding the gaps with
  identity or string tensors, not by splitting the term.

🔧 build_hamiltonian

• Handles InteractionNSite in both the validation pass and the accumulation loop,
  cloning and retagging each window tensor onto its site before the oplus merge.
• The coupling is applied to the last window tensor only, matching the existing rule
  for Interaction1Site (on-site tensor) and Interaction2Site (terminal tensor). The
  docstring now states explicitly that cpl must not be baked into the tensors by the
  model builder — the previous wording said tensor fields were used verbatim "including
  any coupling constants", which contradicted the code.
• New validation errors, each naming the offending index and sites: an empty sites
  list, tnsrs=None, and a tnsrs whose length does not equal
  max(sites) - min(sites) + 1.
• An active interaction that is none of the three supported subclasses now raises
  TypeError. Previously such an object fell through the accumulation loop and
  contributed a bare identity term, shifting the spectrum by a constant with no
  diagnostic.

🧪 Tests

• New tests/network/test_autompo.py, the first dedicated test module for the AutoMPO
  layer, built on build_fermionic('U1') and a dense Jordan-Wigner reference
  implementation.
• TestInteractionNSiteValidation covers the three new error paths: tnsrs=None, a
  wrong-length window, and an unsupported Interaction subclass.
• TestFourOperatorMPO pins the channel signs for concatenated four-fermion terms:
  test_dmrg_energy_matches_jw builds c†_m c†_n c_k c_l plus its Hermitian conjugate
  on an L = 4 chain for two site orderings and checks the DMRG ground-state energy
  against the exact two-particle sector eigenvalue of the dense JW matrix.
• The remaining cases check the structural and limiting behavior: an identity-padded gap
  between two disjoint one-body factors, the p = 0 density-density term n_m n_n
  evaluated against every two-particle occupation configuration, and a single hopping
  channel built from InteractionNSite windows matching the G4/G4dag
Interaction2Site construction of the same term.

📚 Documentation

• New docs/api/interaction/interaction-nsite.md, describing the verbatim-window
  contract, the meaning of sites, and the coupling rule; linked from the API index, the
  interaction index, and the Interaction, Interaction1Site, and Interaction2Site
  pages, and added to the mkdocs.yml navigation.
• core-concepts.md now describes four interaction dataclasses instead of three.

📊 Statistics

• 979 tests across 30 test modules (up from 971 / 29 modules in v0.2.7).
• 13 commits since v0.2.7.
• 14 files changed, 477 insertions, 11 deletions.
• 28 source modules in four subpackages: alice.network, alice.physics,
  alice.algorithm.dmrg, alice.algorithm.xtrg (unchanged from v0.2.7).

✅ Compatibility

Breaking Changes: none.

Behavioral Changes:

• build_hamiltonian raises TypeError on an active interaction that is not an
  Interaction1Site, Interaction2Site, or InteractionNSite. Code passing a custom
  Interaction subclass previously got an MPO with a spurious identity term; it now
  fails at the validation pass.

Requirements:

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

📝 Notes

The two-site interaction is defined by its endpoints plus a single intermid_tnsr
repeated across the gap, which is exactly right for a hopping or exchange term and
useless for anything longer. A four-fermion term c†_m c†_n c_k c_l — the basic
two-body scattering interaction — has no such uniform interior: between the four
operator sites sit Jordan-Wigner strings on some stretches and plain identities on
others, and which is which depends on how the four indices interleave. Rather than grow
the synthesis rules to cover those cases, InteractionNSite hands the whole window to
the model builder, which already knows the operator ordering and the fermion signs it
implies. build_hamiltonian keeps only what it can determine locally — where the window
sits, and where the coupling goes.