Installation

Installation

CheckAMG requires Python 3.11 or 3.12. PyTorch, the PyG torch_scatter extension, and FAISS must be installed before CheckAMG, in the order below. torch_scatter must be source-built against your installed torch.

Pick the block matching your hardware and run it top to bottom. Then download the databases.

CPU only

conda create -y -n CheckAMG python=3.11
conda activate CheckAMG
python -m ensurepip --upgrade
python -m pip install --upgrade pip setuptools wheel packaging uv

uv pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cpu
uv pip install torch_geometric
uv cache clean torch_scatter
uv pip install torch_scatter --no-build-isolation --no-binary torch_scatter --refresh
uv pip install faiss-cpu

uv pip install checkamg

GPU (Ampere / Ada / Hopper: A100, A40, RTX 30/40-series, H100, H200)

H100/H200 require cu126 or newer. Use cu128 instead of cu126 if your driver toolkit needs CUDA 12.8.

conda create -y -n CheckAMG python=3.11
conda activate CheckAMG
python -m ensurepip --upgrade
python -m pip install --upgrade pip setuptools wheel packaging uv

uv pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cu126
uv pip install torch_geometric
uv cache clean torch_scatter
uv pip install torch_scatter --no-build-isolation --no-binary torch_scatter --refresh
uv pip install faiss-gpu-cu12

uv pip install checkamg

GPU (Pascal / Volta / Turing: P100, V100, T4, RTX 20-series)

conda create -y -n CheckAMG python=3.11
conda activate CheckAMG
python -m ensurepip --upgrade
python -m pip install --upgrade pip setuptools wheel packaging uv

uv pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cu118
uv pip install torch_geometric
uv cache clean torch_scatter
uv pip install torch_scatter --no-build-isolation --no-binary torch_scatter --refresh
uv pip install faiss-gpu-cu11

uv pip install checkamg

Download the databases

About 116 GB of free disk space is required during download (~97 GB after, with --rm-hmm).

checkamg download -d /path/to/db/destination --rm-hmm

If you do not plan on running checkamg de-novo or checkamg end-to-end, you will not need the de novo database, and can skip downloading it to save an additional 76 GB of disk space:

checkamg download -d /path/to/db/destination --no-download-denovo-db --rm-hmm

Verify (optional, but recommended before you run CheckAMG)

python - <<'PY'
import torch, torch_scatter, torch_geometric, faiss, pst, pyhmmer
print("torch:", torch.__version__, "| cuda available:", torch.cuda.is_available())
print("torch_scatter:", torch_scatter.__version__)
print("faiss:", faiss.__version__)
PY

checkamg --version

Troubleshooting

Most failures are a precompiled torch_scatter wheel being used instead of a source build (segfault, GLIBC_2.XX not found, undefined symbol: _ZN3c10..., or std::length_error / Aborted (core dumped) on checkamg -h). Fix:

uv pip uninstall torch_scatter
uv cache clean torch_scatter
uv pip install torch_scatter --no-build-isolation --no-binary torch_scatter --refresh

• checkamg reinstalled the wrong torch — Step order matters. Install torch before checkamg, or pip pulls the default PyPI torch. Recreate the env and run a block above in order.
• torch.cuda.is_available() is False on a GPU node — your torch CUDA build does not match the driver. Reinstall with a different cuXXX build (the torch_scatter step rebuilds automatically).
• torch_scatter build fails with command 'gcc' failed — install a compiler, then re-run the torch_scatter line: conda install -c conda-forge gxx_linux-64.
• faiss-gpu-cu1X aborts on import — install via conda instead: conda install -n CheckAMG -c conda-forge "faiss-gpu=*=*py311*".

Pack the env for another machine (optional)

Can be useful if you need to package the conda environment for transferring across notes on a computing cluster:

conda install -y -n base -c conda-forge conda-pack
conda activate CheckAMG
for pkg in pip setuptools wheel packaging; do
    rm -f "$CONDA_PREFIX/conda-meta/${pkg}-"*.json
done
conda pack -n CheckAMG -o checkamg_env.tar.gz

The rm loop is required: pip replaced these conda-managed packages during install, and conda pack refuses to package the env until conda's stale records for them are removed. If conda pack names another package, add a matching rm and re-pack.