Installation¶

Nicole is a Python library for symmetry-aware tensor computations. This guide covers installation options for both users and developers.

Installing from PyPI¶

The recommended way to install Nicole is via pip:

pip install nicole

This will install Nicole and its required dependencies (PyTorch 2.5+, NumPy 2.0+, and Yuzuha 0.1.4+).

Optional Dependencies¶

Install with additional dependencies for specific use cases:

# For testing
pip install nicole[test]

# For documentation
pip install nicole[docs]

# For linting and development tools
pip install nicole[lint]

# Install all optional dependencies
pip install nicole[test,docs,lint]

Requirements¶

Python: 3.11 or higher
PyTorch: 2.5 or higher

Installing from Source (Development)¶

If you want to contribute to Nicole or need the latest development version:

# Clone the repository
git clone https://github.com/Ideogenesis-AI/Nicole.git
cd Nicole

# Install in development mode
pip install -e .

# Optional: Install with all development dependencies
pip install -e ".[test,docs,lint]"

Development Setup¶

For active development, install the development dependencies:

# Install in editable mode with all dependencies
pip install -e ".[test,docs,lint]"

# Run tests
pytest

# Build documentation
mkdocs serve

# Run linter
ruff check src/

Verifying Installation¶

To verify that Nicole is installed correctly:

import nicole
import torch

print(f"Nicole version: {nicole.__version__}")
print(f"PyTorch version: {torch.__version__}")
print(f"Default device: {torch.get_default_device()}")

# Create a simple tensor to test
from nicole import Tensor, Index, Sector, Direction, U1Group

group = U1Group()
index = Index(Direction.OUT, group, sectors=(Sector(0, 2),))
tensor = Tensor.random([index, index.flip()], itags=["i", "j"], seed=42)
print(f"Successfully created tensor with {len(tensor.data)} blocks")
print(f"Tensor device: {tensor.device}")

Troubleshooting¶

PyTorch Installation¶

Nicole requires PyTorch 2.5 or higher. If you encounter issues:

# Upgrade PyTorch
pip install --upgrade torch

# Verify PyTorch version
python -c "import torch; print(torch.__version__)"

GPU Support¶

Nicole supports GPU acceleration through PyTorch on NVIDIA GPUs (CUDA) and Apple Silicon (MPS).

NVIDIA GPU (CUDA):

# Install PyTorch with CUDA support (example for CUDA 12.4)
pip install torch --index-url https://download.pytorch.org/whl/cu124

# Verify CUDA availability
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"

Apple Silicon (MPS):

# PyTorch with MPS support is included in the standard installation
# Verify MPS availability
python -c "import torch; print(f'MPS available: {torch.backends.mps.is_available()}')"

For detailed GPU usage and optimization, see the GPU Acceleration guide.

Python Version¶

Ensure you're using Python 3.11 or higher:

python --version

If your system has multiple Python versions, you may need to use python3.11 or python3.12 explicitly.

Next Steps¶

Once installed, continue with:

Core Concepts: Understand the fundamentals of symmetry-aware tensors
Quick Examples: Create your first tensors and learn basic operations