Skip to content

Nicole 0.2.1

Choose a tag to compare

View all tags
@Phy-David-Zhang Phy-David-Zhang released this 08 Feb 00:12
· 522 commits to stable since this release
v0.2.1
90a79ea

Nicole 0.2.1 - QR Decomposition and Documentation Enhancement

Release Date: February 8, 2026

Version 0.2.1 introduces QR decomposition for orthogonal tensor factorization, API improvements for more flexible tensor operations, and comprehensive documentation enhancements covering the PyTorch backend transition.

✨ QR Decomposition

Core Functionality

  • qr() function: Symmetry-preserving QR decomposition in decomp module
  • Orthogonal factorization: Separates tensors into Q (orthogonal) and R (upper triangular)
  • Block-wise decomposition: Preserves symmetry structure across charge sectors
  • No truncation: Useful for canonical forms without compression

Integration with decomp()

  • New "QR" mode: Alongside existing SVD, UR, and LV modes
  • Consistent API: Same interface as other decomposition modes
  • Custom bond tags: Control via itag parameter
  • Flow direction control: Configure arrow directions with flow parameter
  • Flexible axis specification: Integer positions or string itags

Testing

  • Comprehensive test coverage: New test_factorize.py module
  • Validation tests: Orthogonality (Q†Q = I) and reconstruction accuracy
  • Stress tests: High-order tensors with complex symmetry structures
  • Test organization: Refactored into test_decomp.py (high-level) and test_factorize.py (low-level)

🎨 API Enhancements

oplus Function Improvements

  • Single integer support: axes=0 now works (not just axes=[0])
  • Single string support: axes='i' now works (not just axes=['i'])
  • Improved ergonomics: Simpler syntax for common single-axis direct sum operations
  • Better validation: Error messages for non-existent itags

Operator Labeling

  • label="Operator": All operator tensors in load_space() now properly labeled
  • Enhanced identification: Operators for spin systems, fermions, and band structures
  • Better debugging: Improved clarity in tensor network diagrams and summaries

Display Improvements

  • Consistent formatting: Refined tensor summary output alignment
  • Enhanced readability: Better charge and value representations
  • Improved spacing: Comma placement and info line formatting

📖 Documentation Infrastructure

Comprehensive PyTorch Transition Documentation

  • Updated code examples: All examples now use PyTorch syntax (from NumPy)
  • GPU acceleration guide: Comprehensive coverage of CUDA and MPS (Apple Silicon)
  • Autograd documentation: Complete guide for gradient tracking in tensor networks
  • Installation guide: Updated with PyTorch dependency requirements
  • API reference updates: Device management and autograd features documented

QR Decomposition Documentation

  • Complete API reference: New qr.md and eig.md pages with examples
  • Updated decomp() docs: Includes QR mode details and usage patterns
  • Working examples: QR section in decomposition examples with executable code
  • Cross-references: Links between SVD, QR, and eigenvalue decomposition
  • Usage patterns: Orthogonal factorization without truncation

MkDocs Hooks for Enhanced Rendering

  • Custom post-processing hook: Automatic bullet list conversion in parameter tables
  • Markdown to HTML conversion: Converts markdown bullets to proper <ul>/<li> tags
  • Multi-line support: Handles continuation lines in bullet items
  • Inline HTML support: Preserves code formatting, emphasis, and links within bullets
  • Debug logging: NICOLE_HOOKS_DEBUG=1 mode for troubleshooting
  • Detailed logs: Stored in .logging/hooks.log with transformation tracking

Documentation Quality Improvements

  • Fixed bullet rendering: Proper list display in parameter tables across API docs
  • Enhanced navigation: Clear decomposition method organization
  • "linalg" labels: Added to low-level functions (svd, qr, eig)
  • Cross-referencing: Improved links between related functions
  • Performance guidance: Updated CPU vs GPU recommendations for tensor networks

🧪 Code Quality and Maintenance

Test Organization

  • Refactored structure: Decomposition tests split into focused modules
    • test_decomp.py: High-level decomp() API tests
    • test_factorize.py: Low-level SVD, QR, EIG function tests
  • Enhanced clarity: Descriptive test names and documentation
  • Consistent naming: Renamed "flip" tests to "invert"

Project Hygiene

  • Cleaned .gitignore: Better project management
  • Added .logging/ directory: For hook debug logs
  • Improved formatting: Code consistency in tensor summary outputs

📊 Statistics

Code Changes

  • 27 commits: QR decomposition, API enhancements, and documentation
  • New function: qr() in decomp.py (~200 lines)
  • Enhanced functions: decomp() with QR mode, oplus() with flexible axes
  • New test file: test_factorize.py with comprehensive factorization tests
  • Total changes: 39 files, 4,704 insertions, 1,455 deletions

Documentation Expansion

  • 3 new pages: qr.md, eig.md, hooks implementation
  • 15+ updated pages: PyTorch transition across existing documentation
  • 2 comprehensive guides: GPU acceleration and autograd
  • Enhanced organization: Clearer API index categorization

Test Coverage

  • 10+ new tests: QR decomposition validation
  • 5+ enhanced tests: oplus functionality
  • 100% pass rate: Across CPU, CUDA, and MPS devices
  • Stress tests: High-order tensor correctness validation

🎓 Target Users

Researchers in quantum many-body physics and tensor network methods requiring:

  • Orthogonal decompositions: For canonical forms in DMRG, TEBD, PEPS
  • Improved API ergonomics: Simpler syntax for common operations
  • Comprehensive documentation: For PyTorch-based workflows with GPU and autograd

💡 Use Cases

Canonical Forms

  • QR decomposition for left/right-canonical MPS forms
  • Orthogonal factorization without singular value truncation
  • Gauge fixing in tensor network algorithms
  • Canonical tensor network states

Direct Sum Operations

  • Simplified axis specification with single int/string
  • Building symmetry-adapted basis sets
  • Combining Hilbert spaces with different quantum numbers
  • Fock space construction

Documentation-Driven Development

  • Professional-quality API documentation with proper rendering
  • Multi-line parameter descriptions with inline code formatting
  • Executable examples demonstrating PyTorch features
  • Comprehensive guides for GPU acceleration and autograd

✅ Compatibility

Breaking Changes: None - fully backward compatible with v0.2.0 API

Requirements:

  • Python ≥ 3.11
  • PyTorch ≥ 2.5
  • Optional: CUDA or MPS for GPU acceleration
Assets 2
Loading