Installation Guide

This guide provides detailed installation instructions for schr and its dependencies.

Requirements

System Requirements

  • Operating System: Linux, macOS, or Windows

  • Python: >= 3.11

  • RAM: Minimum 8 GB (16+ GB recommended for large simulations)

  • Storage: ~2 GB for package and dependencies

For GPU Acceleration

  • GPU: NVIDIA GPU with CUDA Compute Capability >= 3.5

  • CUDA Toolkit: >= 11.8 (CUDA 12 recommended)

  • GPU Memory: 4+ GB (8+ GB recommended)

Quick Install

Using pip

If you prefer traditional pip:

# Clone the repository
git clone https://github.com/sql-hkr/schr.git
cd schr

# Install in editable mode
pip install -e .

GPU Support

JAX with CUDA

For NVIDIA GPUs, install JAX with CUDA support after syncing:

CUDA 12.x:

uv sync
uv pip install "jax[cuda12]"

CUDA 11.x:

uv sync
uv pip install "jax[cuda11]"

Verify GPU Installation:

import jax
print(f"JAX version: {jax.__version__}")
print(f"Available devices: {jax.devices()}")
print(f"Default backend: {jax.default_backend()}")

Expected output with GPU:

JAX version: 0.8.0
Available devices: [GpuDevice(id=0, process_index=0)]
Default backend: gpu

Development Installation

For Contributing

Install all dependencies including development tools:

# Clone with all branches
git clone https://github.com/sql-hkr/schr.git
cd schr

# Sync all dependencies including dev tools (recommended)
uv sync --all-extras

This includes:

  • pytest for testing

  • ruff for linting

  • sphinx for documentation

  • pytest-cov for coverage

Running Tests

Verify your installation:

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=schr

# Run specific test file
uv run pytest tests/test_qm.py

Building Documentation

cd docs
make html

# Open in browser (macOS)
open _build/html/index.html

# Open in browser (Linux)
xdg-open _build/html/index.html

Docker Installation

Using the Provided Dockerfile

# Build the image
docker build -t schr:latest .

# Run container
docker run --gpus all -it schr:latest

# Run with mounted volume
docker run --gpus all -v $(pwd):/workspace -it schr:latest

Docker Compose

# Start services
docker-compose up -d

# Run example
docker-compose exec schr python examples/double_slit.py

Platform-Specific Notes

macOS

Apple Silicon:

JAX supports Apple Silicon via the Metal backend:

# Install JAX for Apple Silicon
uv add jax-metal

# Verify
uv run python -c "import jax; print(jax.devices())"

Intel Macs:

Use CPU-only installation. GPU support requires NVIDIA GPUs.

Verifying Installation

Complete Verification Script

Save as verify_install.py:

import sys
import jax
import jax.numpy as jnp
import matplotlib

try:
    from schr.qm.hamiltonian import ParticleInPotential
    from schr.qm.solvers import SplitStepFourier
    from schr.qm.wavefunction import gaussian_wavepacket
    from schr.utils.grid import create_grid_1d
except ImportError as e:
    print(f"Error importing schr: {e}")
    sys.exit(1)

print("✓ schr imported successfully")
print(f"✓ Python {sys.version}")
print(f"✓ JAX {jax.__version__}")
print(f"✓ Backend: {jax.default_backend()}")
print(f"✓ Devices: {jax.devices()}")

# Quick test
x, dx = create_grid_1d(-10, 10, 256)
psi = gaussian_wavepacket(x, x0=0.0, p0=1.0, sigma=1.0)

def potential(psi, t):
    return jnp.zeros_like(psi, dtype=jnp.float32)

hamiltonian = ParticleInPotential(
    potential=potential,
    grid_shape=(256,),
    dx=dx
)

solver = SplitStepFourier(hamiltonian)
psi_new = solver.step(psi, 0.0, 0.01)

print(f"✓ Evolution test passed (norm = {jnp.sum(jnp.abs(psi_new)**2) * dx:.6f})")
print("\n✅ All checks passed! Installation successful.")

Run:

uv run verify_install.py

Uninstallation

If you used uv:

# Remove the virtual environment
rm -rf .venv

If you used pip:

pip uninstall schr

# To also remove dependencies
pip uninstall schr jax jaxlib matplotlib tqdm

Next Steps