# Select GPU devices

**You will learn:** how to pick which GPU(s) ACEMD uses on a multi-GPU host.

**Prerequisites:**

- ACEMD installed (see [Installation](../installation.md)).
- A working `input.yaml` in the current directory.

## List your GPUs

```bash
nvidia-smi
```

The leftmost column of each row in the bottom table is the **device index** ACEMD expects.

## Pick a single GPU

```bash
acemd --device 0
```

By default ACEMD runs on device 0 — pass `--device` to override.

## Run on multiple GPUs

Two ways to use multiple GPUs:

```bash
acemd --device 0 2          # space-separated list of GPU indices
acemd --ngpus 2             # auto-pick GPUs 0..N-1
```

If both flags are passed, `--ngpus` wins — it rewrites `--device` to `[0, ..., ngpus-1]`. Use `--device` if you need specific cards.

## When multi-GPU helps — and when it doesn't

Running a **single** simulation across multiple GPUs does **not** generally improve speed. ACEMD partitions the system across devices, but inter-GPU communication overhead typically cancels — or exceeds — the gain from the extra compute.

Use multiple GPUs for a single simulation when the system **does not fit in a single GPU's VRAM**. Splitting across devices is what makes those runs possible at all.

For **throughput**, run independent simulations on separate GPUs instead: e.g. `acemd --device 0` and `acemd --device 1` in parallel (or one job per GPU under your scheduler).

## From Python

```python
from acemd import acemd

acemd(".", device=[0, 2])
```

`device` is the only GPU-selection keyword accepted by {py:func}`~acemd.acemd.acemd` — `ngpus` is a CLI-only flag and won't be recognised here.

## Run ACEMD with different platforms

ACEMD supports three OpenMM platforms via `--platform`:

- **`CUDA`** (default) — NVIDIA GPUs.
- **`OpenCL`** — non-NVIDIA GPUs (AMD, Intel, etc.) at reduced performance.
- **`CPU`** — testing and debugging without GPU hardware. Orders of magnitude slower than GPU; not for production runs.

```bash
acemd --platform CUDA --device 0
acemd --platform OpenCL --device 0
acemd --platform CPU
```

## Gotchas

- **`CUDA_VISIBLE_DEVICES` renumbers the indices ACEMD sees.** When the env var is set, the CUDA runtime exposes only the listed physical GPUs and presents them as `0..N-1`. Inside that view, `--device` indices are relative to the visible set, not the `nvidia-smi` numbering. For example, `CUDA_VISIBLE_DEVICES=2,3 acemd --device 0` runs on **physical GPU 2**, not GPU 0. If you don't set the env var, `--device` indices match `nvidia-smi` directly.
- A restart checkpoint (`restart.chk`) is tied to the GPU model that wrote it. You can't resume a run started on an RTX 4090 on a different GPU.

## See also

- [Command-line arguments](../reference/cli.md)
- [Run a simulation from Python](run-from-python.md)