Skip to content

Nicole: A Symmetry-Aware Tensor Library

Welcome to the documentation for Nicole, a Python library for symmetry-aware tensor computations, specifically designed for quantum many-body physics and tensor network algorithms.

What is Nicole?

Nicole provides efficient block-sparse tensor operations that respect Abelian and non-Abelian symmetries (U(1), Z₂, SU(2), and their combinations), enabling memory-efficient and computationally optimized tensor network calculations. Created as part of the Ideogenesis-AI effort in studying quantum many-body systems, Nicole reimagines the block-symmetric tensor approach with a Python-native API built on PyTorch, making it accessible to the broader scientific Python ecosystem while maintaining the mathematical rigor needed for quantum physics applications.

Key Features

  • Block-Sparse Tensors: Efficient representation of tensors with conserved quantum numbers
  • Abelian Symmetries: Built-in support for U(1), Z₂, and their product groups
  • Non-Abelian Symmetries: SU(2) with intertwiner-based reduced tensor algebra
  • Charge Conservation: Enforcement of selection rules through symmetry-aware indices
  • PyTorch Backend: Implementation using PyTorch for high-performance dense operations
  • GPU Acceleration: Optional GPU support (CUDA/MPS) for accelerated computations
  • Autograd Control: Optional gradient tracking for efficient optimization tasks
  • Tensor Network Operations: Essential operations including contraction, trace, SVD, and more
  • Type-Safe API: Modern Python with type hints for better IDE support
  • Extensible Design: Clean abstractions for adding custom symmetry groups

Getting Started

New to Nicole? Follow these steps:

  1. Installation: Install Nicole via pip or from source
  2. Core Concepts: Understand symmetries, charges, sectors, and indices
  3. Quick Examples: Create your first tensors and learn basic operations

Documentation Structure

This documentation is organized into three main sections:

  • Getting Started (this section): Learn the basics and concepts of Nicole library
  • API Reference: Comprehensive documentation for all classes and functions
  • Examples: Practical examples and use cases organized by topic

Use Cases

Nicole is designed for researchers and developers working on:

  • Tensor Network Algorithms: DMRG, TEBD, PEPS, and other tensor network methods
  • Quantum Many-Body Physics: Systems with conserved quantum numbers
  • Condensed Matter Theory: Strongly correlated electron systems
  • Quantum Chemistry: Fermionic and bosonic systems with symmetries

Acknowledgments

Nicole is inspired by the QSpace tensor library developed for MATLAB. While QSpace excels in complex symmetries (e.g. SU(N), Sp(N), SO(N)) with a C++ backend, Nicole focuses on providing a Python implementation for Abelian and SU(2) non-Abelian symmetries, with an emphasis on clarity, extensibility, and integration with the scientific Python ecosystem.

License

Nicole is licensed under the GNU General Public License v3.0 (GPL-3.0). This means you are free to use, modify, and distribute this software under the terms of the GPL-3.0 license. We encourage you to share any improvements you make back to the community, helping Nicole grow and benefit all users. For more information about GPL-3.0, visit https://www.gnu.org/licenses/gpl-3.0.html