API Reference¶

Welcome to the Nicole API Reference. This comprehensive documentation covers all functions, classes, and methods available in Nicole, organized by functionality for quick access.

What you'll find here:

Complete function signatures with all parameters and return types
Detailed descriptions of behavior and algorithms
Usage examples demonstrating each function
Cross-references to related functions and examples

The API is organized into logical categories: Core concepts (Tensor, Index, Sector), Operations (contraction, decomposition, manipulation), Symmetry groups (U(1), Z(2), ProductGroup), and Utilities. Each page provides both high-level understanding and technical details needed for advanced usage.

Core Classes¶

The fundamental building blocks:

Class	Description
Tensor	Block-sparse tensor with symmetry
Index	Tensor index with charge structure
Sector	Charge-dimension pair
Direction	Index orientation (IN/OUT)

Creating Tensors¶

Functions to create new tensors:

Function	Description
zeros	Zero-filled tensor
random	Random-filled tensor
identity	2-index identity tensor
isometry	2-to-1 fusion isometry
isometry_n	N-to-1 fusion isometry

Manipulation¶

Transform and rearrange tensors:

Function	Description
conj	Conjugate + flip directions
permute	Permute axes
transpose	Transpose axes
capcup	Invert bond direction
retag	Change index tags
filter_blocks	Extract block subset
merge_axes	Merge multiple axes into one

Arithmetic¶

Mathematical operations:

Topic	Description
Basic Operations	+, -, *, /, negation
oplus	Direct sum
diag	Create diagonal tensor
inv	Matrix inversion

Contraction¶

Contract and trace tensors:

Function	Description
contract	General tensor contraction
trace	Trace over index pairs
einsum	Einstein summation notation

Decomposition¶

SVD, QR, eigenvalue decomposition, and related operations:

Function	Description
decomp	High-level decomposition (SVD/QR)
svd	Low-level SVD
qr	Low-level QR
eig	Eigenvalue decomposition

Symmetry Groups¶

Define and use symmetries:

Group	Description
Overview	Symmetry system introduction
U1Group	Integer charge symmetry
Z2Group	Binary symmetry
SU2Group	SU(2) non-Abelian spin symmetry
ProductGroup	Multiple symmetries

Utilities¶

Supporting functionality:

Topic	Description
Display	Pretty-printing tensors
Blocks	Block structure utilities
load_space	Load physical spaces and operators
serialize	Convert a Tensor to a serializable dict
deserialize	Reconstruct a Tensor from a serialized dict

Usage Patterns¶

For practical examples and complete working code, see:

Quick Links by Task¶

I want to...¶

Create a tensor → zeros, random, identity

Contract tensors → contract, trace, einsum

Decompose a tensor → decomp, svd, qr, eig

Merge tensor axes → merge_axes, isometry_n

Use multiple symmetries → ProductGroup

Build quantum operators → load_space

Save and load tensors → serialize, deserialize

See working examples → Examples

API Design¶

Nicole follows these principles:

Functional operations return new tensors (e.g., conj())
In-place methods modify existing tensors (e.g., Tensor.conj())
Charge conservation enforced automatically
Array-style API with familiar syntax (similar to NumPy/PyTorch)
Device management for CPU and GPU computation
Autograd control for optional gradient tracking