Alice 0.1.1

Alice 0.1.1 — Documentation Website

Release Date: May 6, 2026

Version 0.1.1 introduces the complete documentation website for Alice: a Material-themed MkDocs site with a full API reference, worked DMRG examples, and comprehensive getting-started guides covering installation through advanced extensions. The Alice project itself is unchanged; this is a documentation-only update fully backward compatible with v0.1.0. The PyPI distribution is also renamed from alice to alice-net in this release.

📚 Documentation Infrastructure

MkDocs Configuration with Material Theme

• Professional documentation site built with mkdocs-material
• Custom alice color scheme with logo (alice-font-awesome.png) and favicon
• Three-tab navigation: Getting Started, API Reference, Examples
• Responsive layout with dark/light/system-preference theme switching
• Search with suggestions, result highlighting, and shareable links
• Content features: code copy, inline code annotations, tabbed content, in-page edit and view actions
• Custom home page template (docs/overrides/home.html) with hero image and feature cards
• Custom stylesheet (docs/stylesheets/extra.css) for the landing page and the alice color palette

Documentation Plugins and Extensions

• mkdocstrings: automatic API documentation from NumPy-style Python docstrings
• markdown-exec: infrastructure for future live code execution in examples (configured but not yet used)
• git-revision-date-localized: last-modified timestamps displayed on each page
• git-committers: contributor tracking and author information per page
• pymdownx.arithmatex: LaTeX math rendering via MathJax
• pymdownx.superfences: enhanced code blocks with Mermaid diagram support
• pymdownx.tabbed: tabbed content blocks for alternative implementations
• pymdownx.emoji: icon support with Material Design and FontAwesome icon sets

🚀 Getting Started Guide (7 pages)

• What is Alice: philosophy, relationship with Nicole, target audience, and overview of supported symmetry groups and algorithms
• Installation: pip install alice-net / uv add alice-net, development setup with optional dependency groups
• Core Concepts: MPS/MPO block-sparse structure, symmetry sectors, and DMRG sweep logic
• Quick Start: end-to-end Heisenberg DMRG example from site definition through energy output
• Contributing: branch model, coding conventions, and test requirements
• Git Control: tagging, branching, and release workflow for the Alice project
• Changelog: version history beginning with v0.1.0

📖 API Reference Documentation (30 pages)

Network

• Network, MPS, MPO: class references covering construction, canonicalization, norm, serialization, SVD compression, and norm redistribution
• observe: expectation-value sweep with SU(2) Bridge weight support

Interaction

• Interaction, Interaction1Site, Interaction2Site: dataclass field references
• build_interaction: TOML-configured interaction map builder with plugin section documentation

Geometry

• generate_snake_order, intrcmap_1dchain, intrcmap_square, build_geometry: full function references with parameter tables and usage notes

Local Space

• build_bosonic, build_fermionic, build_conductor: site Hilbert space constructors with symmetry-mode tables

Hamiltonian

• build_hamiltonian: MPO assembler reference
• build_heisenberg, build_free_fermion, build_hubbard: model-specific builder references

DMRG

• dmrg.Options: complete parameter reference with TOML key mapping
• dmrg.Summary: output dataclass fields and serialization interface
• dmrg.run: sweep logic, update schemes (1s, 2s, 1sp), and convergence criteria

Logging

• configure_logging: handler configuration, log levels, and output file naming convention

💡 Example Documentation (8 pages)

DMRG Examples

• Heisenberg chain: ground-state energy of a spin-1/2 chain, U(1) and SU(2) symmetry comparison
• Free fermion: tight-binding chain benchmark against exact diagonalization
• Hubbard model: charge and spin sector targeting in a single-band system

AutoMPO from TOML

• Complete walk-through of the TOML interaction-map format: [[interaction]] tables, [plugin] sections for user-defined models, and built-in presets

Extension Examples

• Custom geometry: implementing a user-defined lattice traversal and registering it with build_geometry
• Custom local space: defining a new site Hilbert space outside the built-in build_bosonic, build_fermionic, and build_conductor presets
• Custom model: wrapping a user-defined Hamiltonian function as an Alice-compatible builder

⚙️ Packaging

Distribution Renamed to alice-net

• PyPI distribution name changed from alice to alice-net to avoid conflicts with existing packages
• pyproject.toml updated: added [tool.hatch.build.targets.wheel] pointing to src/alice, expanded project URLs (homepage, documentation, repository, issues)
• README badge links and the logging startup banner updated to reflect the new package name
• Install: pip install alice-net or uv add alice-net; the Python import namespace alice is unchanged

📊 Statistics

• 45 documentation pages across Getting Started, API Reference, and Examples
• 39 commits since v0.1.0
• 112 files changed, 3,161 insertions, 63 deletions
• All public classes, functions, and parameters documented with NumPy-style docstrings
• Professional visual identity: custom alice color palette, logo, hero image, and FontAwesome icon

✅ Compatibility

Breaking Changes: None — fully backward compatible with v0.1.0. All import paths, function signatures, and TOML configuration formats are unchanged. The only user-visible change outside the documentation is the PyPI distribution name.

Requirements:

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

📝 Notes

MkDocs with the Material theme and mkdocstrings was chosen for consistency with Nicole, which uses the same stack and establishes the documentation conventions Alice inherits (NumPy-style docstrings, navigation structure, plugin suite). Building the documentation alongside the first public release of the API makes the site immediately accurate and avoids the drift that accumulates when documentation is written separately from implementation.