Alice 0.1.2

Alice 0.1.2 — Geometry Expansion and Refactor

Release Date: May 11, 2026

Version 0.1.2 adds Kagome lattice support, refactors the geometry subsystem around a
Geometry dataclass, unifies traversal-order naming across all lattices, introduces
ASCII text diagrams for MPS and MPO chains, and adds Sp4/Sm4 operator templates
to the physical-space builders. Several breaking changes to the geometry and
build_interaction APIs are detailed in the Compatibility section.

🗺️ Kagome Lattice

intrcmap_kagome

• New alice.physics.kagome module implementing nearest-neighbor bond generation
  for Kagome lattices with a three-site unit cell (sublattices A=0, B=1, C=2).
• Two bond families, independently enabled via n2u and n2d config keys:
  • N2U — upward-triangle bonds: A–B, A–C, B–C within each unit cell.
  • N2D — downward-triangle bonds: B↔A_right (bond 4), C↔A_below (bond 5),
    C↔B_below-left (bond 6), connecting adjacent unit cells.
• Supports OBC and PBC along both axes; PBC bonds carry the 'PBC' label.
• intrcmap_kagome is exported from alice.physics at the same level as
  intrcmap_1dchain and intrcmap_square.

Traversal Orders for Kagome

• 'sequential' (default): column-major, all columns fill rows top→bottom.
• 'serpentine': column-major with alternating direction (even columns
  top→bottom, odd columns bottom→top).
• Both traversals are registered in the _TRAVERSALS dict in kagome.py
  and accepted by build_geometry via traverse: in the TOML [geometry] block.

🔧 Geometry Module Refactor

Geometry Dataclass

• build_geometry now returns a Geometry instance (previously returned
  List[Interaction2Site] directly).
• Geometry carries cfg, ord_map, and latt as a single typed object, plus
  derived properties lattice, traverse, lx, ly, and L.
• Helper methods to_1d(coord) and to_2d(site) convert between coordinate
  tuples and 1D MPS site indices.
• All intrcmap_* functions now take a Geometry as input (previously a plain dict);
  their return type List[Interaction2Site] is unchanged.
• build_interaction now returns (interactions, spc, geo) — the third element
  changed from an int (site count) to the Geometry instance.
• A new intrcmap_fn override parameter was added to build_interaction with
  signature (geo: Geometry) -> List[Interaction2Site]; the existing geometry_fn
  signature changed from (geo: dict) -> List[Interaction2Site] to
  (geo_cfg: dict) -> Geometry.

build_intrcmap

• New dispatcher build_intrcmap(geo) reconstructs the bond list from any Geometry
  instance by looking up the registered intrcmap_* builder for geo.lattice.
• Useful for inspecting bonds after geometry construction without re-running the
  full traversal.

Module Separation and build_traversal

• 1D chain, square lattice, and Kagome geometry code separated into their own modules
  (chain.py, square.py, kagome.py), each exposing a build_traversal dispatcher.
• build_traversal validates the traverse key, selects the correct generator, and
  returns (ord_map, latt), which build_geometry wraps into a Geometry.

Coordinate Tuples in ord_map

• ord_map keys changed from integer flat indices to coordinate tuples:
  (row, col) for chain and square, (row, col, u) for Kagome (sublattice u).
• latt[site] returns the corresponding coordinate tuple for any site index.
• Key length is lattice-dependent; the Geometry docstring documents both conventions.

🔤 Traversal Order Naming

• 'snake' is renamed to 'serpentine' (same behavior: columns alternate
  direction, even columns top → bottom, odd columns bottom→top).
• 'sequential' is a new order (all columns top → bottom, no reversal) and is
  now the default for square and Kagome lattices.
• All documentation, example TOML configs, and tests updated to the new naming.

🖥️ MPS/MPO Text Display

alice.network.display

• New module with network_summary: renders a three-block Unicode ASCII diagram
  (title, chain row with tensor nodes and bond-dimension labels, info block with
  length and center/norm summary) for any MPS or MPO instance.
• The center tensor is highlighted with ⊙; non-center MPS sites with ○ and MPO
  sites with □/⊡.

__repr__ on MPS and MPO

• MPS.__repr__ and MPO.__repr__ delegate to network_summary, providing
  readable representations in REPLs, Jupyter notebooks, and log output.

⚛️ New Operator Templates

• build_bosonic gains Sp4/Sp4dag and Sm4/Sm4dag 4th-order templates
  (U(1)-only): same leading/terminal layout as S4/S4dag but for the raising
  (Sp) and lowering (Sm) channels individually, useful when the two channels
  must be handled separately (e.g. anisotropic couplings or single-channel models).
• build_conductor gains the same Sp4/Sp4dag/Sm4/Sm4dag templates for
  spinful-fermion sites (Abelian symmetry groups only).

📖 Documentation

New API Pages

• intrcmap_kagome: full function reference with parameter table, bond-family
  description, and label convention.
• build_intrcmap: dispatcher reference with usage example showing the two-stage
  geometry-then-bonds workflow.

Updated Geometry Pages

• intrcmap_1dchain, intrcmap_square, build_geometry: updated to document the
  Geometry return type, build_traversal, and the revised traversal-order names.
• Geometry section restructured to reflect the two-stage pipeline:
  build_geometry → build_intrcmap → build_interaction.

Heading Standardization

• All documentation page headings standardized to title case throughout the
  Getting Started, API Reference, and Examples sections.

📊 Statistics

• ~650 tests across 21 test modules (up from 538 / 19 modules in v0.1.0)
• 119 commits since v0.1.1
• 65 files changed, 3,380 insertions, 824 deletions
• 20 source modules in three subpackages: alice.network, alice.physics,
  alice.algorithm.dmrg

✅ Compatibility

Breaking Changes:

• build_geometry return type changed from List[Interaction2Site] to Geometry.
• All intrcmap_* functions now take a Geometry as input instead of a plain dict;
  return type List[Interaction2Site] is unchanged.
• build_interaction third return value changed from int (site count) to Geometry.
• geometry_fn callable override signature changed from
  (geo: dict) -> List[Interaction2Site] to (geo_cfg: dict) -> Geometry; a new
  intrcmap_fn override was added with signature
  (geo: Geometry) -> List[Interaction2Site].
• The public function generate_snake_order is removed; its traversal logic is now
  internal to build_geometry.
• The TOML key traverse: 'snake' is deprecated; 'snake' was renamed to
  'serpentine', and 'sequential' is the new default order.

Requirements:

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

📝 Notes

The Geometry dataclass was introduced to make the geometry pipeline universal and
extensible. Previously, build_geometry merged traversal and bond generation into one
step and returned the interaction list directly. Adding a new lattice type meant
reimplementing that entire combined step. The new design separates concerns cleanly:
build_geometry produces a Geometry struct (traversal only), and each lattice
module implements intrcmap_* against that struct. The same Geometry can then be
passed to different intrcmap_* builders — for example, to compare bond sets on the
same lattice — without rerunning the traversal.

The coordinate-tuple keys in ord_map serve the same goal: previously, ord_map was
a 2D list accessed as ord_map[row][col], which does not generalise to a
three-sublattice lattice where each site also has a sublattice index. Using a dict
keyed by (row, col) or (row, col, u) handles both cases with the same interface.