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 uv (Recommended)
~~~~~~~~~~~~~~~~~~~~~~

`uv <https://github.com/astral-sh/uv>`_ is a fast Python package and project manager:

.. code-block:: bash

   # Install uv if you don't have it
   curl -LsSf https://astral.sh/uv/install.sh | sh

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

   # Sync dependencies and install schr
   uv sync

This will:

* Create a virtual environment (if needed)
* Install all dependencies from ``pyproject.toml``
* Install schr in editable mode
* Lock dependencies for reproducibility

Using pip
~~~~~~~~~

If you prefer traditional pip:

.. code-block:: bash

   # 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:**

.. code-block:: bash

   uv sync
   uv pip install "jax[cuda12]"

**CUDA 11.x:**

.. code-block:: bash

   uv sync
   uv pip install "jax[cuda11]"

**Verify GPU Installation:**

.. code-block:: python

   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:

.. code-block:: text

   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:

.. code-block:: bash

   # 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:

.. code-block:: bash

   # 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
~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash

   # 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
~~~~~~~~~~~~~~

.. code-block:: bash

   # 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:

.. code-block:: bash

   # 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``:

.. code-block:: python

   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:

.. code-block:: bash

   uv run verify_install.py

Uninstallation
--------------

If you used uv:

.. code-block:: bash

   # Remove the virtual environment
   rm -rf .venv

If you used pip:

.. code-block:: bash

   pip uninstall schr

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

Next Steps
----------

* Explore :doc:`examples` for complete working code
* Read the :doc:`theory` for mathematical background