# HPFRACC development environment (summary)

This file mirrors the **canonical** setup in [`config/environment.yml`](https://github.com/dave2k77/hpfracc/blob/main/config/environment.yml) and [CONTRIBUTING.md](https://github.com/dave2k77/hpfracc/blob/main/CONTRIBUTING.md). Prefer those sources if anything conflicts.

## Overview

- **Conda env name:** `hpfracc` (legacy names `hpfracc-env` / `fracnn` may still exist on older machines)
- **Python:** **3.11** (recommended; CI smoke / full pytest / RTD use 3.11; main test workflow also runs 3.10 and 3.12)
- **Install:** editable checkout with dev extras

## Quick start

```bash
conda env create -f config/environment.yml   # or: conda env update -f config/environment.yml
conda activate hpfracc
pip install -e ".[dev]"
```

Optional shell helpers (from repo root):

```bash
source tools/activate_env.sh
```

## Core stack (from `config/environment.yml`)

Versions drift over time; the YAML is authoritative. In general the env includes NumPy, SciPy, Matplotlib, Pandas, SymPy, JAX/jaxlib, Numba, PyTorch (via pip), Optax, pytest stack, Sphinx, Black, Flake8, Mypy, and pre-commit.

## Testing

```bash
conda activate hpfracc
python -c "import hpfracc; print(hpfracc.__version__)"
python -m pytest tests/ -c pytest.ini --tb=short
```

## Managing the environment

```bash
conda env list
# Recreate from repo spec (do not overwrite environment.yml with conda export unless you intend to pin everything):
conda env remove -n hpfracc   # only if you need a clean rebuild
conda env create -f config/environment.yml
```

## Troubleshooting

- **CUDA / GPU:** match driver and optional `jax[cuda12]` / PyTorch CUDA builds to your hardware (see README).
- **Import errors:** confirm `conda activate hpfracc` and that `pip install -e ".[dev]"` was run from the repository root.

## Performance

GPU memory and throughput depend on your hardware; use `nvidia-smi` (NVIDIA) or smaller batch sizes if you hit OOM during ML workloads.