# Nicole 0.1.0 - Initial Stable Release

**Release Date:** January 26, 2026

Nicole is a Python library for block-sparse tensor computations with Abelian symmetries, designed for tensor network algorithms in quantum many-body physics.

## 🎯 Core Features

### Symmetry-Aware Tensor Framework
- Automatic block-sparse structure for Abelian symmetries
- Support for **U(1)** and **Z(2)** symmetry groups with automatic charge conservation
- **ProductGroup** implementation for direct products of multiple Abelian symmetries
- Index class with directional quantum number flow (IN/OUT)
- Flexible index tagging system (itags) for intuitive tensor operations

### Tensor Operations
- **Contraction**: `np.tensordot`-style interface with automatic index pairing
  - Flexible axes specification with exclusion support
  - Automatic ambiguity detection and validation
  - Full support for scalar tensors (0D)
- **Trace**: Automatic pairing with exclusion options
- **Arithmetic**: Element-wise addition, subtraction with sector union
- **Manipulation**: `permute`, `transpose`, `conjugate`, `retag`, `merge_axes`, `flip`
- **Block access**: Efficient block extraction with `getsub`/`subsector`

### Tensor Decomposition
- **SVD** with symmetry preservation and truncation support
  - Bond dimension (chi) and singular value (tol) truncation
  - Automatic index direction handling
- **Eigenvalue decomposition** for symmetric tensors
- High-level `decomp` function with customizable truncation
- Multi-axis decomposition support

### Tensor Construction
- `identity`: Identity tensors with automatic sector matching
- `isometry`/`isometry_n`: Isometry for single and multi-index fusion
- `random`: Random tensor generation with symmetry constraints
- `zeros`: Zero tensors for initialization
- `oplus`: Direct sum operation for selective axis merging

### Specialized Operators
- `diag`: Diagonal matrix tensor construction
- `inv`: Tensor inversion with automatic index flipping
- Operator arithmetic for quantum systems

### Quantum Many-Body Systems (`load_space`)
Preset-based Hilbert space construction with physical operators:
- **Ferm**: Spinless fermions with U(1) charge conservation
- **Band**: Hardcore bosons with U(1)⊗U(1) or Z(2)⊗U(1) symmetries
- **Spin**: Spin-1/2 chains with U(1) or Z(2) symmetries
- Automatic operator generation (creation, annihilation, number, spin)
- Vacuum sector support for open boundary conditions

## 📊 Statistics

- **662 comprehensive tests** covering all functionality
- ~18,000 lines of code
- 119 commits across 8 feature branches
- Pure Python implementation with NumPy backend
- Full type hints for IDE support

## 🎓 Target Users

Researchers and students in quantum many-body physics, condensed matter theory, and quantum information who work with tensor network methods (DMRG, TEBD, PEPS) and require efficient handling of Abelian symmetries.

## 📚 API Surface

**Core:** `Tensor`, `Index`, `Direction`  
**Symmetry:** `U1Group`, `Z2Group`, `ProductGroup`, `AbelianGroup`  
**Operations:** `contract`, `trace`, `decomp`, `svd`, `eig`  
**Manipulation:** `permute`, `transpose`, `conjugate`, `retag`, `merge_axes`, `flip`  
**Construction:** `identity`, `isometry`, `isometry_n`, `random`, `zeros`  
**Operators:** `diag`, `inv`, `oplus`  
**Utilities:** `load_space`, `blocks`, `tensor_summary`, `index_summary`, `subsector`  
