Installation

Requirements

IACTrace requires Python 3.11 or later.

For GPU acceleration, you will also need:

  • NVIDIA GPU with CUDA support

  • CUDA toolkit (version 11.8 or 12.x recommended)

  • cuDNN

Basic Installation

Install directly from the git repository:

pip install git+https://github.com/GerritRo/iactrace.git

Development Installation

For development or to access example notebooks, clone the repository:

git clone https://github.com/GerritRo/iactrace.git
cd iactrace
pip install -e ".[dev]"

This installs additional development dependencies:

  • pytest for running tests

  • jupyter for example notebooks

  • mypy for type checking

  • ruff for code linting

GPU Support

By default, JAX installs with CPU-only support. For GPU acceleration, install the appropriate JAX version for your CUDA installation:

# For CUDA 12
pip install --upgrade "jax[cuda12]"

# For CUDA 11
pip install --upgrade "jax[cuda11_local]"

See the JAX installation guide for detailed instructions and troubleshooting.

Verify your installation:

import jax
print(jax.devices())  # Should show GPU device if available

Building Documentation

To build this documentation locally:

pip install -e ".[docs]"
cd docs
make html

The built documentation will be in docs/_build/html/.

Dependencies

IACTrace depends on:

Package

Version

Purpose

JAX

>= 0.4.20

Numerical computing and automatic differentiation

Equinox

>= 0.11.0

PyTree-based neural network library for JAX

NumPy

>= 1.22.0

Array operations and interoperability

Matplotlib

>= 3.5.0

2D plotting and visualization

Pandas

>= 1.4.0

Configuration file handling

Trimesh

>= 3.15.0

3D geometry and visualization

PyYAML

>= 6.0

YAML configuration parsing

Troubleshooting

JAX not finding GPU

Ensure CUDA is properly installed and visible:

nvidia-smi  # Should show GPU info

If JAX still uses CPU, check that you installed the correct JAX version for your CUDA version.

Memory errors with large telescopes

For telescopes with many facets or high n_samples, you may encounter memory issues. Solutions:

  • Reduce n_samples for initial testing

  • Process in chunks with different random keys

Slow first execution

JAX compiles functions on first call. This is normal and subsequent calls will be fast. To avoid recompilation, structure your code to reuse compiled functions.