# Installation

ACEMD targets GPUs. Best performance comes from NVIDIA CUDA; OpenCL is supported for portability, and a CPU backend exists for debugging.

ACEMD ships for two CUDA major versions: **12** and **13**. Pick the one matching your driver.

## 1. Detect your CUDA version

```bash
nvidia-smi
```

The top-right of the output lists the driver's CUDA version. Use the matching ACEMD extra below.

## 2. Install with pip

The pip path gives you precise control over the CUDA build and is the recommended option.

```bash
# Classical MD only (CUDA 12 / CUDA 13)
pip install "acemd[cu12]"
pip install "acemd[cu13]"

# With NNP support (also pulls the matching PyTorch wheel)
pip install "acemd[nnp-cu12]" --extra-index-url https://download.pytorch.org/whl/cu126
pip install "acemd[nnp-cu13]" --extra-index-url https://download.pytorch.org/whl/cu130
```

`--extra-index-url` is needed for the NNP variants so pip resolves the right CUDA-tagged PyTorch wheel.

### Resolving CUDA driver/runtime mismatches

The CUDA runtime ships as a set of `nvidia-*-cu12` (or `-cu13`) wheels on PyPI. pip resolves these to the **latest** release within the major series, which may target a CUDA toolkit version newer than your driver supports — simulations then fail to start with a CUDA initialization or "no kernel image available" error.

**Diagnose.** Compare your driver's CUDA version (top-right of `nvidia-smi`) with the installed runtime:

```bash
nvidia-smi | head -3
pip show nvidia-cuda-runtime-cu12 | grep -E '^(Name|Version)'
```

If the installed `nvidia-cuda-runtime-cu12` major.minor is higher than your driver's CUDA version, downgrade the toolkit wheels to match. For a driver supporting up to CUDA 12.6:

```bash
pip install --force-reinstall \
  "nvidia-cuda-runtime-cu12==12.6.*" \
  "nvidia-cuda-nvrtc-cu12==12.6.*" \
  "nvidia-cuda-cupti-cu12==12.6.*" \
  "nvidia-cuda-nvcc-cu12==12.6.*" \
  "nvidia-cublas-cu12==12.6.*" \
  "nvidia-nvjitlink-cu12==12.6.*" \
  "nvidia-nvtx-cu12==12.6.*"
```

Substitute `12.6.*` with the major.minor matching your driver — `12.4.*`, `12.5.*`, etc. For the CUDA 13 install path, the same packages use the `-cu13` suffix.

The version-coupled libraries that travel with the toolkit (`cufft`, `curand`, `cusolver`, `cusparse`, `cusparselt`, `cudnn`, `nccl`) follow their own version schemes and rarely need pinning — only the toolkit/runtime wheels above are tied to the driver's CUDA version.

## 3. Install with conda (alternative)

Conda autodetects CUDA, which doesn't always pick correctly — pip is the more reliable path. If you do prefer conda, [Miniforge](https://github.com/conda-forge/miniforge) is recommended:

```bash
conda create -n acemd -y
conda activate acemd
conda install acemd cuda-version=12 -c acellera -c conda-forge   # or cuda-version=13
```

To add ACEMD to an existing environment, activate it and run the last line on its own.

### Minimal conda install

`acemd-base` ships only the dependencies needed for classical MD — no PyTorch, no PLUMED. Use it when you don't need NNP/MM or PLUMED. The package raises a clear error if you try to use a feature whose runtime is missing.

```bash
conda install acemd-base cuda-version=12 -c acellera -c conda-forge
```

## Register (non-commercial users)

Non-commercial users see a 5-second license banner on every `acemd` run until they register. Silence it once with the bundled `acemd_register` script:

```bash
acemd_register
```

The tool prompts for full name, institutional email, institution, city, and country, then sends them to Acellera's registration server. After approval, the banner disappears and future runs start immediately.

Registration is optional — ACEMD runs without it. It just stops the boot-time delay.

## Licensing (commercial users)

ACEMD is free for non-commercial use. Commercial use requires a license — see [License options](explanation/license-options.md) for the comparison, and [Install a node-locked license](how-to/install-a-node-locked-license.md) / [Deploy a floating license server](how-to/deploy-a-floating-license-server.md) for the procedures.