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:

File	When to consult
SKILL.md (this file)	Orientation, decision tree, install order
env-cuda.md	After confirming you have GPU + driver, before installing torch
core.md	Installing mlmm-toolkit itself
uma.md	Installing UMA (default backend; HuggingFace auth required)
orb.md	Installing Orb-v3
mace.md	Installing MACE — separate environment required
aimnet2.md	Installing AIMNet2
ambertools.md	AmberTools (tleap / antechamber) for mm-parm
dft.md	PySCF + GPU4PySCF (handled separately per [dft] extra)
xtb.md	xTB point-charge embedding correction (--embedcharge)

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

Need a non-MLIP engine for the ML region (GFN-xTB / DFTB+ / ORCA / any ASE calc)?
    └── --calc-file my_calc.py (custom backend, see below)

Custom backend — any ASE Calculator (--calc-file)

To drive the ML region with an engine that is not a built-in MLIP (GFN-xTB, DFTB+, ORCA, Psi4, …), write a Python file exposing a get_calculator() factory that returns an ASE Calculator, and pass it with --calc-file (selects the custom ML backend, overriding -b):

# my_calc.py:
#   from ase.calculators.emt import EMT
#   def get_calculator(charge=0, spin=1, device="auto", **kwargs):
#       return EMT()              # swap for tblite.ase.TBLite(...) etc.
mlmm sp -i complex.pdb --parm system.parm7 --calc-file my_calc.py -q 0 -m 1

• The custom calculator drives the ML region only; the MM side keeps its usual hessian_ff / OpenMM backend and the ONIOM coupling is unchanged.
• Works on every subcommand (sp / opt / tsopt / freq / irc / scan{,2d,3d} / path-opt / path-search) and the all pipeline (propagated via the args-YAML calc section). Rename the factory with --calc-factory NAME. Hessians use the finite-difference path. Full guide: docs/backends.md (Custom backend section).

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  # fairchem-core is a CORE dep (installs anyway); see the note below

Note: fairchem-core is a core dependency of mlmm-toolkit, so it installs regardless of extras. After creating this env, run pip uninstall -y fairchem-core — mace-torch pins e3nn==0.4.4, which conflicts with fairchem-core's e3nn>=0.5.

<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) — import the backend module itself
# (`mlmm tsopt --help` only loads the CLI and does NOT import any MLIP backend)
python -c "import fairchem"   && echo "mlmm + uma backend OK"
python -c "import orb_models" && echo "mlmm + orb backend OK"
python -c "import mace"       && echo "mlmm + mace backend OK"   # only in MACE env
python -c "import aimnet"     && 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

Symptom	Likely cause	Where to look
import torch fails with libcudart.so.12 not found	Torch wheel CUDA index mismatches the driver	env-cuda.md (driver → cu index table)
e3nn version conflict on pip install	UMA + MACE in the same env	Use a separate env for MACE (this file, mace.md)
gpu4pyscf import fails on aarch64	gpu4pyscf-cuda12x is x86_64 only	dft.md — fall back to CPU PySCF
huggingface_hub.errors.GatedRepoError on UMA load	UMA model is gated, not authenticated	uma.md — huggingface-cli login
OSError: libcusolver.so.11 not found	torch's bundled CUDA libs missing or shadowed	env-cuda.md — LD_LIBRARY_PATH order
RuntimeError: CUDA out of memory during freq	Analytical Hessian too memory-heavy	set hessian_calc_mode: FiniteDifference (or use uma-s-1p1 / return_partial_hessian) to cut Hessian memory

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'))"