Skip to content

Alice 0.1.0

Choose a tag to compare

View all tags
@Phy-David-Zhang Phy-David-Zhang released this 04 May 09:23
· 214 commits to stable since this release
v0.1.0
a6bc551

Alice 0.1.0 - Initial Stable Release

Release Date: May 4, 2026

Alice is an open-source project for 1D tensor network algorithms, built on the Nicole symmetry-aware tensor library. This initial release delivers a production-quality DMRG implementation with full support for Abelian and non-Abelian (SU(2)) symmetries, a flexible TOML-driven Hamiltonian builder, and a comprehensive physics infrastructure for 1D and quasi-1D quantum lattice systems.

🎯 Core Features

Tensor Network Infrastructure

  • MPS/MPO classes: block-sparse matrix product states and operators, inheriting Nicole's exact symmetry engine with full support for U(1), Z(2), SU(2), and product symmetry groups
  • Network class: base tensor-train container with left- and right-canonicalization routines, norm computation, and bond-consistency validation
  • observe: expectation-value computation via MPS–MPO–MPS contraction, accepting both pure MPS and mixed MPS/MPO states

AutoMPO Construction

  • build_interaction: TOML-configured interaction map builder with built-in Heisenberg, free-fermion, and Hubbard model presets and support for user-defined model functions
  • build_hamiltonian: term-by-term MPO assembler that accumulates interactions via Nicole's oplus, then compresses the result with two canonical sweeps; handles arbitrary symmetry groups including non-Abelian SU(2)
  • Incremental compaction: optional compact_every parameter limits bond dimension growth during large Hamiltonian builds by interleaving compression passes
  • Data types: Interaction, Interaction1Site, Interaction2Site for unambiguous representation of on-site and two-site coupling terms

Lattice Geometries

  • 1D chain: straight nearest-neighbor traversal for standard spin and fermion chains
  • 2D snake traversal: boustrophedon (snake-like) MPS ordering for rectangular lattices, supporting quasi-1D cylinders and ladders
  • 2D square lattice: full nearest-neighbor interaction map for square lattices traversed by the snake ordering, including both horizontal and vertical bonds
  • Custom geometry support: user-defined geometry functions via the build_geometry dispatch mechanism

Physical Spaces

Three space builders in alice.physics.system construct the physical Hilbert space and MPO operator templates for a site:

  • build_bosonic: spin-s site; calls Nicole's load_space('Spin', ...) and derives leading- and terminal-site templates for the spherical spin operator S; supports U(1) and SU(2)
  • build_fermionic: spinless-fermion site; calls load_space('Ferm', ...) and derives Jordan-Wigner-dressed hopping templates and the number operator; supports U(1) and Z(2)
  • build_conductor: spinful-fermion site; calls load_space('Band', ...) and derives JW-dressed hopping templates, spin operators, and double-occupancy operator; supports U(1)×U(1), Z(2)×U(1), U(1)×SU(2), and Z(2)×SU(2)

Each builder can be replaced via the space_fn hook accepted by every model builder, enabling custom physical spaces without modifying the model layer.

Physics Models

Three parameterized Hamiltonian models in alice.physics.models are dispatched by name from build_interaction:

  • Heisenberg: spin-s Heisenberg chain with NN coupling J and optional NNN coupling J'; built on build_bosonic; supports U(1) and SU(2) symmetry sectors
  • Free fermion: spinless tight-binding chain with NN hopping t, optional NNN hopping t', and optional chemical potential µ; built on build_fermionic; supports U(1) and Z(2) symmetry sectors
  • Hubbard: spinful Hubbard chain with NN hopping t, on-site interaction U, optional NNN hopping t', and chemical potential µ referenced to half-filling; built on build_conductor; supports U(1)×U(1), Z(2)×U(1), U(1)×SU(2), and Z(2)×SU(2) symmetry sectors

DMRG Algorithm

Ground-state search via alternating sweep optimization with three update schemes:

  • 1-site (1s): single-tensor update; preserves bond dimension exactly, suitable for post-optimization refinement
  • 2-site (2s): two-tensor update with SVD truncation; drives automatic bond growth toward the target dimension chi
  • 1-site-plus (1sp): controlled bond expansion via a complement isometry projected from the 2-site residual; combines the stability of 1-site updates with the bond-dimension flexibility of 2-site

All schemes share:

  • Davidson eigensolver: iterative eigensolver with thick restart operating directly in the symmetry-block-sparse space; uses the plain residual as the correction vector (no preconditioning)
  • Energy-based convergence: sweep terminates when the relative energy change falls below a configurable threshold
  • TOML-driven options: dmrg.Options.from_toml parses scheme, bond dimension, truncation threshold, number of sweeps, and all solver parameters from a TOML config block

Environment Caching

The Environment class provides optional disk-spilling of environment blocks for long chains where all environments do not fit in RAM:

  • Sliding in-memory window: only a configurable window of environments is kept in memory; the rest are serialized to disk via torch.save
  • Asynchronous I/O: eviction and prefetch run on a background thread to overlap disk I/O with computation
  • Transparent API: the DMRG sweep code fetches environments through a unified interface regardless of whether they reside in memory or on disk

Systematic Logging

  • configure_logging: one-call setup of Alice's logging hierarchy with configurable level and format, backed by Python's standard logging module
  • Sweep-by-sweep diagnostics: each forward and backward half-sweep logs site index, energy, bond dimensions, and discarded weight
  • Geometry and interaction-map summaries logged as ASCII diagrams at construction time

📊 Statistics

  • 538 tests across 19 test modules
  • 196 commits across 10+ feature branches
  • 64 files, ~16,000 lines of code
  • 16 source modules organized into three subpackages: alice.network, alice.physics, alice.algorithm.dmrg

🎓 Target Users

Researchers and students in quantum many-body physics, condensed matter theory, and quantum information who need efficient, symmetry-aware DMRG calculations for 1D and quasi-1D systems. Alice is designed to be accessible on a personal workstation while remaining capable of large-scale runs on HPC clusters, with a TOML-driven configuration that provides user-friendly setup.

📚 API Surface

Data types: Interaction, Interaction1Site, Interaction2Site
Hamiltonian builder: build_interaction, build_hamiltonian
Tensor network: MPS, MPO, Network
Measurement: observe
Algorithm: dmrg.run, dmrg.Options, dmrg.Summary
Logging: configure_logging

Assets 2
Loading