Models¶
mliport is not a model. It loads other people's potentials through adapters, runs your workflow with them, and writes down exactly which model did the work. That division of labour is worth keeping in mind when you read a result.
| mliport takes care of | The checkpoint and you are responsible for |
|---|---|
| loading and selecting the model | the weights and the data they were trained on |
| the resolved configuration and the provenance record | the reference state the energies belong to |
| refusing options the backend cannot express | how accurate the potential is |
| checking that the backend runtime can really run | the absolute energy scale and conventions |
Five backends, no favorite¶
mace, dpa, grace, uma and nep are five runtime adapters of equal
standing; fairchem is accepted as another name for uma. There is no
implicit default. A run that names no backend, directly or through a model
alias or profile, stops with an error.
| Backend | Adapter | Framework | Typical checkpoint |
|---|---|---|---|
| MACE | mace-torch |
PyTorch | .model |
| DPA | deepmd-kit |
PyTorch | .pt / .pth |
| GRACE | tensorpotential |
TensorFlow | SavedModel directory |
| UMA | fairchem-core |
PyTorch | .pt |
| NEP | calorine (ASE) / native gpumd |
Python / GPUMD | nep.txt |
Pinned profiles, precision, head semantics and known limits are on the
per-backend pages: MACE, DPA,
GRACE, UMA, NEP.
NEP is opt-in and needs an explicit NEP_RUNTIME; the other rows of this
table need nothing beyond the backend environment.
Model support status¶
verified in the two device columns means mliport called the model
correctly: it loaded, returned finite energies, forces and (where the
checkpoint defines one) stress, a short MD and a small NEB finished, and the
recorded model hash, head, dtype and device matched what was requested. It is
not a statement about accuracy: how well a potential describes your chemistry
is a separate question that this table does not answer.
| Status | Meaning |
|---|---|
verified |
Every callable check passed on that device, in the backend's own environment; the evidence is recorded. |
untested |
The adapter should load it; no evidence yet. |
needs_runtime_upgrade |
A pinned runtime version has to change before the model can be tried. |
unsupported |
Known not to load or run on that device, or the adapter cannot express what the model computes; mliport fails closed instead of running it. |
| Label | Engine | Artifact | Head / task | dtype | CPU | GPU | Evidence |
|---|---|---|---|---|---|---|---|
uma_omat |
uma | uma-s-1p2.pt |
omat |
model-defined | verified |
verified |
re-check record |
mace_omat |
mace | mace-omat-0-medium.model |
default | float64 |
verified |
verified |
runs, CPU–GPU deltas |
mace_omat_float32 |
mace | mace-omat-0-medium.model |
default | float32 |
verified |
verified |
runs, CPU–GPU deltas |
dpa_omat |
dpa | DPA-3.1-3M.pt |
Omat24 |
model-defined | verified |
verified |
runs, CPU–GPU deltas |
grace_omat |
grace | GRACE-2L-OMAT-medium-base |
default | model-defined | verified |
verified |
runs, CPU–GPU deltas |
grace_omat_fp64 |
grace | GRACE-2L-OMAT-medium-base-fp64 |
default | float64 |
verified |
verified |
runs, CPU–GPU deltas |
grace_3l_omat_large_ft_am |
grace | GRACE-3L-OMAT-large-ft-AM |
default | model-defined | verified |
verified |
runs, CPU–GPU deltas |
grace_2l_smax_omat_large |
grace | GRACE-2L-SMAX-OMAT-large |
default | model-defined | verified |
verified |
runs, CPU–GPU deltas |
dpa31_sse_pbe |
dpa | DPA-3.1-3M.pt |
Domains_SSE_PBE |
model-defined | verified |
verified |
runs, CPU–GPU deltas |
dpa31_sse_pbesol |
dpa | DPA-3.1-3M.pt |
Domains_SSE_PBESol |
model-defined | verified |
verified |
runs, CPU–GPU deltas |
dpa4_neo_omat |
dpa | DPA4-Neo-OMat24-v20260805.pt |
single task | model-defined | verified |
verified |
runs, CPU–GPU deltas |
dpa4_air_omat |
dpa | DPA4-Air-OMat24-v20260805.pt |
single task | model-defined | verified |
verified |
runs, CPU–GPU deltas |
dpa4_plus_omat |
dpa | DPA4-Plus-OMat24-v20260805.pt |
single task | model-defined | verified |
verified |
runs, CPU–GPU deltas |
mace_matpes_r2scan |
mace | MACE-MATPES-r2SCAN-0 medium |
single head (default) |
float64 |
verified |
verified |
runs, CPU–GPU deltas |
mace_mh1_omat_pbe |
mace | MACE-MH-1 |
omat_pbe |
float64 |
verified |
verified |
runs, CPU–GPU deltas |
mace_mh1_matpes_r2scan |
mace | MACE-MH-1 |
matpes_r2scan |
float64 |
verified |
verified |
runs, CPU–GPU deltas |
uma_s_1p2p1_omat |
uma | uma-s-1p2p1.pt |
omat |
model-defined | verified |
verified |
UMA record |
uma_s_1p2p1_ft_r2scan_omat |
uma | uma-s-1p2p1-ft-r2scan.pt |
omat |
model-defined | verified |
verified |
SP, forces and MD verified; NEB refused by the gradient preflight — UMA record |
nep89_gpumd |
nep | NEP89 nep.txt |
— | model-defined | unsupported |
verified |
native GPU runtime evidence |
dpa_sse |
dpa | SSE-VASP-dpa2.pt (converted) |
Default (DPA-2) |
float64 | verified |
verified |
legacy runtime, DPA_RUNTIME=legacy — callable check, reference values |
The checks behind these cells ran on 2026-11-14 on one Tesla
V100-SXM2-16GB (driver 580.173.02), in the environments the installer builds:
mace-torch 0.3.16 on torch 2.8.0, deepmd-kit 3.2.1.dev63 on torch 2.11.0,
tensorpotential 0.6.0 on TensorFlow 2.20.0, fairchem-core 2.25.0 on torch
2.13.0. Every verified model loaded, gave finite energy, forces and stress on
the 50-atom li10gep2s12_primitive.vasp cell, matched its recorded identity and
completed the bounded probe (shared calculator, central-difference forces, 10
NVE steps, a five-image NEB) on both devices. Across all profiles the largest
CPU–GPU difference on that cell was 6.1e-7 eV/atom and 7.5e-6 eV/Å, both
from mace_omat_float32; the float64 models agree at the 1e-14 level. The UMA
runs record inference_preset: batch with nitro_enabled: false, and
--inference-mode turbo records multigpu with nitro_enabled: false. One
exception is stated in the table: the r²SCAN fine-tune is refused by the NEB
gradient preflight, because its energy scale does not resolve the derivative in
float32. Records, hashes, deltas and verbatim failures are in
pull request #75.
One row deserves a note: NEP89 is verified only on the native GPU runtime,
because the Calorine ASE runtime cannot parse that model format, so NEP89 on
CPU is unsupported rather than merely untested.
The archived uma-s-1.pt is deliberately not in this table. It is an
archived upstream release with a known extensivity bug; mliport has not checked
it and does not recommend it, and unsupported would be the wrong word because
unsupported means mliport refuses the model — nothing refuses this one.
The hex hashes, source URLs and licenses of the pinned profiles live in the model manifest; the callable checks behind each status are described in Validation.
Comparing results honestly¶
Some habits keep a calculation scientifically defensible, and mliport records what you need to follow them:
- Energies from different models are not comparable. A formation energy or a barrier must come from one model, one head and one set of reference states. Mixing models silently is an error in the science, not a feature.
- A passing workflow says nothing about accuracy. That the adapter ran your NEB to the end tells you the plumbing works, not that the potential describes your chemistry.
- Benchmark numbers do not travel. OMat24 results characterise the pinned model on that benchmark and do not extend to every material.
- Task and head are part of the model. UMA task families (
omat,omol, …) and DPA or MACE heads change what the model computes. mliport records the task and head actually used and refuses to guess a multi-task branch. - Precision is part of the model too. MACE
float32andfloat64are separate profiles; say so whenever you compare their energies.
Choosing a backend for a run¶
The quickest way is a flag:
For models you use often, define an alias in settings.ini (an alias must say
which engine it is for):
--model also accepts an alias name. How aliases, profiles and flags combine
is explained in Configuration.
What gets recorded about the model¶
Every run stores the effective model_type, model_path, task, head and dtype,
the backend and framework versions, the requested and the actual device, and the
mliport commit. Two results are comparable only if these match. The fields are
described in Output files.
Where to get the checkpoints¶
| Engine | Checkpoint | Source |
|---|---|---|
| MACE | mace-omat-0-medium.model |
mace-foundations release mace_omat_0 |
| DPA | DPA-3.1-3M.pt |
deepmodelingcommunity/DPA-3.1-3M |
| GRACE | GRACE-2L-OMAT-medium-base |
AMS-ICAMS-RUB/grace-foundation-models |
| UMA | uma-s-1p2.pt |
facebook/UMA |
These are the artifacts the validation suite is pinned to. Their SHA-256 values describe the distributed files (local paths are never written into the manifest):
| Profile | Artifact | SHA-256 (prefix) |
|---|---|---|
mace_omat |
mace-omat-0-medium.model |
d4b14be9afa2... |
dpa_omat |
DPA-3.1-3M.pt |
86dd3a804d78... |
grace_omat |
GRACE-2L-OMAT-medium-base |
directory SavedModel |
uma_omat |
uma-s-1p2.pt |
ba5c0d912efa... |
The full hashes are in
validation/science/model_manifest.json.
What was and was not downloaded during acceptance
The MACE release asset was downloaded in an isolated cache during the LGPS acceptance and matched the pinned hash. The Hugging Face cold-download path was not validated over the network on the acceptance host: its SOCKS/httpx setup rejects the Hugging Face client's default proxy configuration, so the acceptance used hash-verified local copies of all four artifacts. If your network needs a proxy, see the recipe below.
Checkpoint licenses belong to the upstream projects. In particular, UMA's is a non-commercial research license.
Proxies and offline use¶
Hugging Face downloads go through httpx inside huggingface_hub. Behind a
SOCKS proxy (ALL_PROXY=socks5...), install the socks extra in the environment
you download with:
Some proxy setups also put bracketed entries like [::1] into NO_PROXY, which
httpx rejects with Invalid port. Keep the list to plain host names:
NO_PROXY=localhost,127.0.0.1 HF_ENDPOINT=https://hf-mirror.com \
.venv/bin/python -c "from huggingface_hub import hf_hub_download; print(hf_hub_download('deepmodelingcommunity/DPA-3.1-3M', 'DPA-3.1-3M.pt'))"
A model on local disk needs no network at all: pass its path to --model, and
use --source offline when the installer is involved.