Installation

Pip Installation

Install NF2 from PyPI:

pip install nf2

Install the current development version from GitHub:

pip install git+https://github.com/RobertJaro/NF2

PyTorch And CUDA

NF2 depends on compatible torch and torchvision releases. Pip installs both from NF2 metadata. For custom GPU-enabled PyTorch installs, use the official PyTorch selector at pytorch.org/get-started/locally. Select your operating system, package manager, Python version, and CUDA version, then run the generated command before installing or running NF2.

If Colab raises RuntimeError: operator torchvision::nms does not exist, reinstall torch and torchvision together from the same PyTorch wheel index, restart the runtime, then install NF2:

pip uninstall -y torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126
pip install git+https://github.com/RobertJaro/NF2

For CUDA 12.6:

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126

For the most recent default PyTorch build:

pip3 install torch torchvision torchaudio

Conda Installation

Install NF2 with conda:

conda install nf2

Create a fresh environment if you prefer to isolate NF2:

conda create -n nf2 python=3.11 nf2
conda activate nf2

If your conda setup does not already use conda-forge, add it or pass -c conda-forge.

Local Installation

Create the recommended conda environment from a local source checkout:

conda env create -f environment.yml
conda activate nf2

Install NF2 from the checkout:

python -m pip install -e .

Install the documentation, test, lint, and packaging tools used by this repository:

python -m pip install -r requirements.txt

NF2 targets Python 3.11/3.12 with current PyTorch, Lightning, and W&B releases.

Verify the installation:

python - <<'PY'
import torch
import lightning
import nf2

print("NF2:", nf2.__version__)
print("Torch:", torch.__version__)
print("Lightning:", lightning.__version__)
print("CUDA:", torch.cuda.is_available())
print("CUDA device count:", torch.cuda.device_count())
for idx in range(torch.cuda.device_count()):
    print(f"CUDA device {idx}:", torch.cuda.get_device_name(idx))
PY

Development Installation

Fork the repository on GitHub, then clone your fork:

git clone https://github.com/<your-user>/NF2.git
cd NF2
git remote add upstream https://github.com/RobertJaro/NF2.git

Create the development environment and install the package in editable mode:

conda env create -f environment.yml
conda activate nf2
python -m pip install -r requirements.txt

Keep your fork current with upstream:

git fetch upstream
git checkout main
git merge upstream/main

Create a feature branch for changes:

git checkout -b my-docs-or-feature-change

Build the documentation locally before opening a pull request:

LC_ALL=C LANG=C SUNPY_CONFIGDIR=/tmp/sunpy MPLCONFIGDIR=/tmp/matplotlib sphinx-build -b html docs docs/_build/html

Packaging

Build a source distribution and wheel:

python -m pip install build
python -m build

When using conda for packaging tools, install the conda-forge package name:

conda install -c conda-forge python-build twine
python -m build

For conda packaging, use the project dependencies from pyproject.toml and the environment pins in environment.yml as the source of truth. A minimal user-facing conda environment can be created with:

conda env create -f environment.yml

Render or build the conda package recipe:

CONDA_BLD_PATH=/tmp/conda-bld conda render conda-recipe
CONDA_BLD_PATH=/tmp/conda-bld conda build conda-recipe