mlmm-install-backends

name: mlmm-install-backends description: Install recipes for mlmm-toolkit core + MLIP (UMA / MACE / Orb / AIMNet2) / DFT / xTB / AmberTools backends, with CUDA / PyTorch / e3nn / aarch64 quirks. TRIGGER on install / setup / pip install / conda env / ImportError / CUDA-version mismatch / "GPU not detected" / huggingface auth / e3nn version conflict / AmberTools / tleap not-found questions. SKIP when mlmm imports cleanly and the user is invoking subcommands — the CLI skill covers usage.

mlmm — Install and Backends

Purpose

mlmm-toolkit is a Python package that depends on:

• a recent PyTorch wheel matching your CUDA driver,
• one or more MLIP backends (UMA / Orb / MACE / AIMNet2),
• optional PySCF / GPU4PySCF for DFT single points,
• AmberTools for MM parameterization (mlmm mm-parm).

Bundled and installed automatically with the package: pysisyphus (a GPU-tensor fork), thermoanalysis. They must not be installed separately.

This skill directory contains ten files; read them in this order:

Install order

1. Check the env — see mlmm-env-detect/SKILL.md to discover driver / scheduler / CUDA / conda before doing anything.
2. CUDA + torch — env-cuda.md decides which torch wheel to pull.
3. mlmm-toolkit core — core.md.
4. At least one MLIP backend — start with UMA (uma.md); add others only as you need them.
5. DFT (optional) — dft.md. Skip if you only need MLIP energies.
6. xtb (optional) — xtb.md. Skip unless you need the --embedcharge xTB point-charge embedding correction.

Decision tree: which backend?

Need TS + IRC validation on a known organic + 1st-row metal cluster?
    └── start with UMA-s-1.1 (uma.md)
        └── if accuracy is borderline, also install MACE-OMOL-0 (mace.md, separate env)

Need a fast screen across many candidates?
    └── Orb-v3 (orb.md)

Working on small organic molecules, no metals?
    └── AIMNet2 (aimnet2.md) — limited element coverage, but light

Need DFT//MLIP refinement?
    └── add dft.md regardless of MLIP choice

Why two envs for MACE

fairchem-core (UMA) and mace-torch pin different e3nn versions which cannot coexist. Solution: keep UMA in your default env (<env_a>) and put MACE in a second env (<env_b>). Other backends (Orb, AIMNet2, DFT, xTB) can sit in either.

mlmm-toolkit itself is the same code in both envs; only the calculator plugin set differs.

Conda env templates

Replace <...> with the values you discovered in env-detect. The templates assume python=3.11; mlmm-toolkit requires Python ≥ 3.11.

env_mlmm.yml (UMA / Orb / AIMNet2 / DFT / xTB):

name: <your_mlmm_env>
channels: [conda-forge, nvidia]
dependencies:
  - python=3.11
  - pip
  - pip:
      - --extra-index-url https://download.pytorch.org/whl/<cu_index>
      - torch
      - mlmm-toolkit[orb,aimnet,dft]   # extras: see core.md / per-backend md
  # xtb (optional, for --embedcharge): install separately via `conda install -c conda-forge xtb`
  # since xtb is shipped as a binary, not a PyPI wheel.

env_mlmm_mace.yml (MACE only, separate env):

name: <your_mace_mlmm_env>
channels: [conda-forge]
dependencies:
  - python=3.11
  - pip
  - pip:
      - --extra-index-url https://download.pytorch.org/whl/<cu_index>
      - torch
      - mace-torch
      - mlmm-toolkit  # without [orb,aimnet] to avoid fairchem deps

<cu_index> is one of cpu, cu118, cu121, cu126, cu129 — see env-cuda.md for the driver version → index mapping.

Verify the install

mlmm --version
mlmm --help                     # subcommand list
python -c "import mlmm.core.defaults as d; print(sorted(n for n in dir(d) if not n.startswith('_')))"

# backend smoke checks (only those you installed)
mlmm tsopt --help >/dev/null && echo "mlmm + uma backend OK"
mlmm tsopt --help >/dev/null && echo "mlmm + orb backend OK"
mlmm tsopt --help >/dev/null && echo "mlmm + mace backend OK"   # only in MACE env
mlmm tsopt --help >/dev/null && echo "mlmm + aimnet2 backend OK"

If any of these fails with ImportError, the corresponding backend's md page lists missing dependencies. If a CUDA-related error appears, go back to env-cuda.md.

Common failure → fix

See also

pyproject.toml lists the canonical extras and version pins. To inspect without opening the file:

python -c "import importlib.metadata as m; print(m.metadata('mlmm-toolkit').get_all('Provides-Extra'))"
python -c "import importlib.metadata as m; print(m.requires('mlmm-toolkit'))"