# Nicole 0.1.1 - Comprehensive Documentation and Developer Experience

**Release Date:** February 1, 2026

Version 0.1.1 introduces complete documentation infrastructure with live code execution, comprehensive API references, extensive examples, and enhanced developer experience for tensor network computations with Abelian symmetries.

## 📚 Documentation Infrastructure

### MkDocs Configuration with Material Theme
- Professional documentation site with modern Material Design
- Hierarchical navigation structure (Getting Started, Examples, API Reference)
- Custom branding with Nicole logo
- Responsive design for desktop and mobile viewing
- Search functionality with indexed content
- Dark/light theme switching with system preference support

### Live Code Execution (markdown-exec)
- All code examples execute automatically during documentation build
- Real-time output generation ensures documentation accuracy
- Session-based execution for shared imports across code blocks
- Source code and console output displayed side-by-side
- ANSI color support for enhanced terminal output visualization
- Pyodide integration for future web-based interactive examples

### Documentation Plugins and Extensions
- **mkdocstrings**: Automatic API documentation from Python docstrings with NumPy style
- **git-revision-date-localized**: Last modified timestamps on each page
- **git-committers**: Contributor tracking and author information
- **pymdownx.arithmatex**: LaTeX math rendering via MathJax
- **pymdownx.superfences**: Enhanced code blocks with syntax highlighting
- **pymdownx.tabbed**: Tabbed content for alternative implementations
- **pymdownx.emoji**: Icon support with Material Design and FontAwesome

## 📖 API Reference Documentation (45+ pages)

### Core Concepts
- **Tensor**: Primary class for block-sparse tensors with symmetries
- **Index**: Quantum number indices with direction and sector structure
- **Sector**: Charge-dimension pairs defining symmetry blocks
- **Direction**: IN/OUT flow for quantum number conservation

### Symmetry Groups
- **U1Group**: U(1) continuous symmetry (particle number, magnetization)
- **Z2Group**: Z(2) discrete symmetry (fermion parity, spin parity)
- **ProductGroup**: Direct products of Abelian groups (charge × spin)
- Mathematical foundations and group operation properties

### Operations
- `contract`: Generalized tensor contraction with flexible axes specification
- `trace`: Partial and full trace operations with exclusion support
- `decomp`: High-level decomposition (SVD, UR, LV modes) with truncation
- `svd`: Direct singular value decomposition interface
- `permute`, `transpose`, `conjugate`: Tensor manipulation operations

### Arithmetic
- Addition and subtraction with automatic sector union
- Scalar multiplication and division
- `oplus`: Direct sum operation for selective axis merging
- `diag`: Diagonal matrix construction from vectors
- `inv`: Tensor inversion with charge-conserving structure

### Creation Functions
- `identity`: Identity tensors with automatic sector matching
- `isometry`: Two-index fusion isometries
- `isometry_n`: Multi-index fusion with arbitrary index counts
- `random`: Random tensor generation with symmetry constraints
- `zeros`: Zero tensor initialization

### Manipulation
- `retag`: Index tag modification for flexible contractions
- `subsector`: Extract specific charge sectors
- `merge_axes`: Combine multiple axes into single index
- `flip`: Reverse index direction

### Utilities
- `load_space`: Generate physical Hilbert spaces (Spin, Ferm, Band systems)
- `blocks`: Iterator for block access and manipulation
- `display`: Tensor summary with customizable block formatting

## 💡 Example Documentation (20+ pages)

### Basic Examples
- **Creating Your First Tensor**: Introduction to Index, Sector, block structure
- **Arithmetic Operations**: Addition, subtraction, norms with symmetries
- **Indexing**: Block access, sector filtering, index properties, trivial indices

### Symmetry Examples
- **U(1) Examples**: Particle number conservation, multi-particle states, Fock space
- **Z(2) Examples**: Fermion parity, parity operators, Jordan-Wigner strings
- **Product Group Examples**: Charge-spin systems, SU(2) via U(1)⊗U(1), multi-quantum numbers

### Operations Examples
- **Contraction Examples**: Matrix multiplication, multi-index contractions, MPS-like patterns, trace operations
- **Decomposition Examples**: SVD for entanglement, truncation strategies, UR/LV decompositions
- **Manipulation Examples**: Index reordering, axis merging, conjugation, retag workflows

### Advanced Examples
- **Build Operators**: Custom operator construction (identity, number, ladder, spin)
- **Load Space**: Physical system presets with spherical tensor conventions
- **Performance Tips**: Memory optimization, computational efficiency, profiling strategies

## 🚀 Getting Started Guide (7 pages)

- **What is Nicole**: Philosophy, design principles, target audience
- **Installation**: pip installation, development setup, dependency management
- **Core Concepts**: Symmetries, sectors, blocks, charge conservation explained
- **Quick Examples**: Complete workflows from tensor creation to decomposition
- **Contributing**: Guidelines for community contributions and development practices
- **Changelog**: Version history and release notes

## ⚙️ Build System

### Migration to Hatchling
- Migrated from setuptools to Hatchling for modern Python packaging
- Simplified build configuration with cleaner `pyproject.toml` structure
- Added project URLs: homepage, documentation, repository, issues
- Removed setuptools-specific configuration sections

### Documentation Dependencies
- `mkdocs>=1.5`, `mkdocs-material>=9.5`: Core documentation framework
- `mkdocstrings[python]>=0.24`: API documentation generator
- `markdown-exec[ansi]>=1.12`: Live code execution with ANSI support
- `mkdocs-git-revision-date-localized-plugin>=1.2`: Date tracking
- `mkdocs-git-committers-plugin-2>=2.0`: Contributor information

## 📊 Statistics

- **45+ documentation pages** across Getting Started, Examples, API Reference
- **100+ code examples** with live execution
- **57 files changed**, 4,663 lines added
- All core classes, operations, and utilities documented
- Professional visual identity with custom branding

## 🎓 Target Users

Researchers and students in quantum many-body physics who need comprehensive documentation, practical examples, and clear explanations to effectively use Nicole for tensor network computations with Abelian symmetries.

## ✅ Compatibility

**Breaking Changes:** None - fully backward compatible with v0.1
