Nicole is a Python library for symmetry-aware tensor computations, specifically designed for quantum many-body physics and tensor network algorithms. It provides efficient block-sparse tensor operations that respect both Abelian (U(1), Z₂) and non-Abelian (SU(2)) symmetries, enabling memory-efficient and computationally optimized tensor network calculations with exact quantum number conservation.

With the assistance of various AI coding agents, Nicole reimagines the block-symmetric tensor approach with a Python-native API built upon 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: Memory-efficient representation of tensors with conserved quantum numbers
• Abelian Symmetries: Built-in support for U(1) (particle number, magnetization) and Z₂ (parity), etc.
• Non-Abelian SU(2): Full SU(2) spin symmetry via Clebsch-Gordan intertwiners powered by Yuzuha
• Charge Conservation: Automatic enforcement of selection rules through symmetry-aware indices
• PyTorch Backend: Python implementation using PyTorch for high-performance dense block operations
• GPU Acceleration: Optional GPU support (CUDA/MPS) for accelerated computations on large tensors
• Autograd Control: Optional automatic gradient tracking for efficient optimization tasks
• Tensor Operations: Essential operations including contraction, decompositions, and more
• Type-Safe API: Modern Python with type hints for better IDE/AI support and fewer runtime errors
• Extensible Design: Clean abstractions for adding custom symmetry groups (following Yuzuha protocol)

Contributing

We welcome contributions from the community! Whether you're fixing bugs, adding features, implementing new symmetry groups, or improving documentation, your help is appreciated. You can also contribute by requesting new features or reporting performance bottlenecks.

Ways to contribute:

• Report issues and request features via GitHub Issues
• Submit pull requests with bug fixes or enhancements
• Improve documentation and add examples
• Share your use cases and provide constructive feedback

Development guidelines:

• Ensure all contributions include appropriate tests
• Follow the existing code style (enforced by ruff)
• Add type hints for new functions and classes
• Update documentation for user-facing changes

Authors and Maintainers:

Nicole is created and maintained by Changkai Zhang as part of the Ideogenesis-AI effort in studying quantum many-body systems. If you have questions about contributing to the project or are interested in collaboration opportunities, please feel free to open an issue on GitHub or contact the maintainer directly.

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 supporting both Abelian (U(1), Z₂) and non-Abelian (SU(2)) 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. See the LICENSE file for the full license text. For more information about GPL-3.0, visit https://www.gnu.org/licenses/gpl-3.0.html