Installation¶

pdb2reaction is intended for Linux environments (local workstations or HPC clusters), and production runs normally use a CUDA-capable GPU. Prebuilt PyTorch wheels include their CUDA runtime libraries: they need a compatible NVIDIA driver, but not a local CUDA toolkit.

Quick install¶

nvidia-smi shows CUDA Version at its top right: the newest CUDA the driver supports. Choose a PyTorch wheel at or below it (cu126, cu130, or cu132). The commands below use the recommended cu130.

Required¶

# 1) Create and activate a Python 3.12 environment (conda here; venv also works)
# 2) Install a CUDA-enabled PyTorch build
# 3) Install pdb2reaction
# 4) Install headless Chrome for Plotly static image export (PNG)
#    Downloads a Chromium binary; requires internet access.

conda create -n p2r -c conda-forge --override-channels python=3.12 -y
conda activate p2r

pip install 'torch==2.13.0' --index-url https://download.pytorch.org/whl/cu130  # recommended; for cu126 / cu132, change the end
pip install pdb2reaction

plotly_get_chrome -y

Finally, log in to Hugging Face Hub so that UMA models can be downloaded. This needs a free HF account with a read-only token, and you may need to accept the license on the UMA model page:

hf auth login
# or, with an access token in scripts:
hf auth login --token '<YOUR_ACCESS_TOKEN>' --add-to-git-credential

You only need to do this once per machine / environment.

Check the installation with pdb2reaction --version, which prints the installed version.

Optional¶

For DMF (--mep-mode dmf) or --solvent (xTB), create the environment instead with cyipopt, xTB, and PyTorch from conda-forge, then install pdb2reaction:

conda create -n p2r -c conda-forge --override-channels python=3.12 cyipopt xtb "pytorch=2.13.0=cuda130*" cuda-nvcc -y
conda activate p2r
pip install pdb2reaction
plotly_get_chrome -y

If the CUDA Version of nvidia-smi is below 13.0, replace cuda130 with cuda129. ORB, AIMNet2, MACE, and DFT are installed in step 7 of Step-by-step installation.

Step-by-step installation¶

If you prefer to build the environment piece by piece:

Load a CUDA toolkit only when the site/build requires one

A prebuilt PyTorch wheel does not require nvcc. If a dependency must be built from source, use module avail cuda and load the compiler/toolkit combination documented by the cluster:
```
module load cuda/<your-version>   # e.g. cuda/12.6 or cuda/12.9
```

Create and activate a conda environment

conda create -n <your-env> -c conda-forge --override-channels python=3.12 -y
conda activate <your-env>

Install cyipopt, xTB, and PyTorch from conda-forge Required if you want to use the DMF method (--mep-mode dmf) in MEP search or the xTB solvent correction (--solvent); this step also installs PyTorch, so skip step 4. You can skip this step if you only use GSM without --solvent. If --mep-mode dmf still stops with an import error, see Installation / environment.
```
conda install -c conda-forge --override-channels cyipopt xtb "pytorch=2.13.0=cuda130*" cuda-nvcc -y   # cuda129 if nvidia-smi shows CUDA below 13.0
```
Install PyTorch with the right CUDA build

Skip this step if you installed PyTorch in step 3. Recommended example (cu130):
```
pip install 'torch==2.13.0' --index-url https://download.pytorch.org/whl/cu130
```
The official 2.13.0 matrix also provides cu126, cu132, and cpu. Choose the wheel with the nvidia-smi rule in the Quick install above, then check GPU access in step 8. See PyTorch’s version matrix.
Install pdb2reaction itself and Chrome for visualization
```
pip install pdb2reaction
plotly_get_chrome -y
```
On aarch64, the warp-lang 1.18.0 wheel, which UMA loads through fairchem-core, needs glibc 2.35 and stops the import with GLIBC_2.35' not found on older systems (ldd --version); there, install warp-lang==1.17.0 (nvalchemi-toolkit-ops needs 1.13.0 or newer).
Log in to Hugging Face Hub (UMA model)
```
hf auth login
```
For license requirements and non-interactive login, see the Required section above.

Refer to the upstream projects for additional details:
- fairchem / UMA: https://github.com/facebookresearch/fairchem, https://huggingface.co/facebook/UMA
- Hugging Face token & security: https://huggingface.co/docs/hub/security-tokens
(Optional) Install additional MLIP backends

pdb2reaction uses UMA by default. For another backend, install its extra and select it with -b/--backend (for example, -b orb):

ORB (requires Python 3.11 or 3.12; 3.12 recommended):
```
pip install "pdb2reaction[orb]"
```
AIMNet2:
```
pip install "pdb2reaction[aimnet]"
```
MACE: mace-torch pins e3nn==0.4.4, which conflicts with UMA’s fairchem-core, so install it in a separate conda environment. You may rename the environment mace-env. Pick the PyTorch wheel as in step 4.
```
conda create -n mace-env -c conda-forge --override-channels python=3.11 -y
conda activate mace-env
pip install 'torch==2.13.0' --index-url https://download.pytorch.org/whl/cu130
pip install pdb2reaction
pip uninstall -y fairchem-core
pip install 'mace-torch>=0.3.8'
```
DFT (-b dft, --dft, pdb2reaction dft): [dft] installs the CUDA 13 GPU4PySCF build on Linux x86_64, for the cu130 / cu132 PyTorch wheels of step 4 and the cuda130 build of step 3; with the cu126 wheel or the cuda129 build, install [dft-cuda12] instead. On aarch64, build GPU4PySCF from source. Without a GPU, [dft] still installs PySCF; run DFT with --dft-engine cpu.
```
pip install "pdb2reaction[dft]"
```
For when to use DFT and how to check an MLIP TS with it, see Refine an MLIP TS with DFT.
Verify installation
```
pdb2reaction --version
hf auth whoami
```
The first line should display the installed version, and the second your Hugging Face user name (the login that UMA downloads use). To verify GPU access:
```
python -c "import torch; print('CUDA:', torch.cuda.is_available(), torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'N/A')"
```
If CUDA: False, inspect the installed wheel, scheduler GPU visibility, driver, and environment libraries before changing versions:
```
python -m torch.utils.collect_env
python -m pip check
```

System requirements¶

OS. Linux, or WSL on Windows.

GPU / CUDA. An NVIDIA GPU whose driver supports the chosen wheel (see Quick install); newer GPU architectures may need a newer wheel. CPU-only execution works but is usually much slower.

VRAM, RAM, and disk. Memory grows with the model, the atom count, and the Hessian mode, and the disk holds the environment, the model weights, and the trajectories and Hessians. As a rough guide for a Hessian with the default UMA model, the default finite-difference Hessian (FiniteDifference) fits about 900 atoms in 8 GB, 2,000 in 16 GB, 3,000 in 24 GB, and 10,000 in 96 GB of VRAM, and an analytical Hessian (Analytical) about 200, 400, 600, and 1,500 atoms. Even when the model fits in VRAM, above about 1,000 atoms each Hessian takes an hour or more, and a full mechanism study takes longer. For a very large system, run one representative calculation on the target node and watch the peak use.

Next steps¶

Getting Started — the shortest run, and which page to read next
Quickstart: pdb2reaction all — build an MEP from R and P
Quickstart: pdb2reaction all --scan-lists — build a path from one structure
Quickstart: TS-only mode — optimize and check a TS candidate
Refine an MLIP TS with DFT — refine and check the TS with DFT
Common options and selectors — shared options, and how to give residues and atoms
HPC example — job script that spreads UMA workers over several GPU nodes
Troubleshooting — common errors and what to try