Machine-learning interatomic potentials (MACE)¶

vibe-qc can run ACEsuit MACE, a pre-trained E(3)-equivariant graph-neural-network interatomic potential, as a first-class method:

from vibeqc import Molecule
from vibeqc.runner import run_job

mol = Molecule.from_xyz("h2o.xyz")
run_job(mol, method="mace", output="h2o_mace")

MACE predicts energy, forces, and stress on a DFT-fitted potential-energy surface — it does not solve the Schrödinger equation and builds no wavefunction. vibe-qc drives MACE’s pre-trained forward pass and attributes it as an external pre-trained model (see CLAUDE.md § 10); the energy is MACE’s, not a vibe-qc ab-initio total. Within its trained domain MACE is far more accurate than vibe-qc’s semiempirical methods, but it gives no electronic structure (no orbitals / charges / gap) and only covers its trained elements.

Installation — the `[mace]` extra (Python ≤ 3.13)¶

MACE is an optional dependency (a heavy PyTorch + e3nn stack), not part of the default install:

pip install 'vibe-qc[mace]'

Python ≤ 3.13 only. MACE’s matscipy dependency has no Python 3.14 wheel yet, so the [mace] extra is marked python_version < "3.14" and the runtime import is gated. On Python 3.14, method="mace" raises a clear error telling you to use a ≤ 3.13 environment.

The foundation-model weights are fetched on demand into the XDG cache (~/.cache/mace/) on first use — vibe-qc bundles none of them.

Selecting a model — `MLIPOptions`¶

The default is the MIT-licensed MACE-MPA-0 (materials). Pass an MLIPOptions to choose another model, the device, or the dtype:

from vibeqc.mlip import MLIPOptions

run_job(mol, method="mace",
        mlip_options=MLIPOptions(model="off23-medium",
                                 accept_academic_license=True,
                                 device="cpu", dtype="float64"),
        output="h2o_off")

Model key	Family	Domain	License
`medium-mpa-0` (default), `small`, `medium`, `large`	MACE-MP / MPA	materials (89 elements)	MIT
`off23-small`, `off23-medium`, `off23-large`	MACE-OFF23	organic (H, C, N, O, F, P, S, Cl, Br, I)	ASL

Aliases (mpa-0, off23, …) resolve to the canonical keys; see vibeqc.mlip.MACE_MODELS. An unrecognised model name is treated as academic-only (gated) so it can never silently bypass the license gate.

The ASL license gate¶

MACE’s code is MIT, but the foundation-model weights are licensed separately. The materials line (MP-0 / MPA-0) is MIT — free for commercial and academic use. The organic MACE-OFF23 model (and the newer OMAT / MATPES / multi-head models) are under the Academic Software License (ASL) — academic, non-commercial use only.

Selecting an ASL model raises PermissionError unless you acknowledge the academic license — MLIPOptions(accept_academic_license=True) or the environment variable VIBEQC_ACCEPT_ASL=1. MIT models are never gated. This prevents a commercial workflow from silently pulling academic-only weights. Full licensing detail: license.md.

Energy-scale caveat¶

A method="mace" energy is on a model-specific reference scale (each model subtracts its own per-element atomic energies), not a vibe-qc total electronic energy, and not comparable across models. For H₂O:

	energy
MACE-MPA-0 (materials)	≈ −0.51 Ha (heavily reference-shifted)
MACE-OFF23 (organic)	≈ −76.5 Ha (near its ωB97M total)
ab-initio HF/DFT total	≈ −76 Ha

Use MACE energies for relative energetics (geometry optimization, reaction energies at fixed composition + model, MD) — not as absolute totals, and never mixed with vibe-qc SCF energies. The .out prints a provenance block naming the model, its license, and this caveat.

macOS note¶

On macOS, vibe-qc’s native core and PyTorch each link an OpenMP runtime; to avoid an abort (OMP Error #15) vibe-qc auto-sets KMP_DUPLICATE_LIB_OK=TRUE for the MACE run, with a one-time warning. The MACE forward pass is verified to produce identical energies with it set. Pre-set the variable yourself to override.

Citations¶

Every method="mace" run auto-emits the MACE method paper (Batatia et al. 2022) and the foundation-model paper for the model used (MACE-MP → Batatia et al. 2024; MACE-OFF23 → Kovács et al. 2023) to the .bibtex / .references siblings. Cite them in published work. PyTorch / e3nn are infrastructure (their versions appear in the banner + .system manifest), not cited.

Visualization¶

A method="mace" run writes the same structural output as any vibe-qc job, so the geometry — and, for optimize=True, the relaxation trajectory — visualize out of the box:

MolTUI (terminal viewer; the [viewer] extra) renders the .xyz geometry: moltui output-h2o-mace.xyz.
vibe-view (GPU 3D viewer; the [viewer-gpu] extra) opens the .qvf archive written with output_qvf=True, which carries the structure, the optimization-trajectory animation, and the citations: vibe-view open output.qvf.

There is no orbital / density / band visualization — MACE produces no wavefunction (it is a learned potential, not an SCF), so the .molden file is correctly skipped for method="mace".

Status + limitations¶

Molecular single-point energies + forces and geometry optimization (optimize=True) work today.

Periodic energy / forces / stress and variable-cell relaxation (the MIT MP / MPA materials models are built for this), via a direct driver — following the periodic-semiempirical precedent (run_pm6_gamma):

from vibeqc.mlip.mace import run_periodic_mace, optimize_periodic_mace_cell

res = run_periodic_mace(system)        # .energy (Ha), .gradient() (Ha/bohr),
                                       # .stress() (Ha/bohr³, 3×3)
relaxed = optimize_periodic_mace_cell(system, fmax=0.05)   # variable-cell

(method="mace" is not yet wired into run_periodic_job; use these drivers directly.)

No electronic structure (orbitals / charges / gap).
Trained-domain only — fails out-of-distribution.

Examples¶

Runnable scripts (require the [mace] extra, Python ≤ 3.13) live in examples/mlip/:

01_water_mace.py — molecular single-point + geometry optimization on H₂O.
02_periodic_mace_silicon.py — periodic energy/forces/stress + variable-cell relaxation on bulk Si.
03_neb_mace.py — NH₃ umbrella-inversion reaction path via run_neb(method="mace") (climbing-image NEB on the MACE potential).
04_surface_adsorption.py — H₂O + NH₃ adsorption energies on MgO, CaO, Al₂O₃, TiO₂, Pt, and Cu slabs with MACE-MPA-0 (a fast oxide/metal surface screen).

MACE also drives reaction-path searches: run_neb(..., method="mace") runs a Nudged Elastic Band on the MACE potential — analytic forces, no SCF, and (for periodic bands) no finite-difference gradient. See neb.md § MACE backend.

See also: ase_integration.md, external_codes.md, and the roadmap § MACE MLIP interface.