English | 简体中文
Run machine-learned interatomic potentials — MACE, DPA, GRACE, UMA and NEP — from one
command line, one terminal UI and one Python API. Give it a structure and a
checkpoint; it relaxes, runs molecular dynamics, finds NEB barriers, searches adsorbate
configurations on a slab or analyzes a trajectory, and writes the files a VASP user expects: OUTCAR, OSZICAR,
CONTCAR, XDATCAR.
mliport is a workflow layer, not a model and not a DFT code. The files are VASP-shaped, but there is no SCF and no POTCAR, and whether a potential is right for your chemistry depends on the checkpoint you choose.
What you get:
- The same workflow on every backend. Single point, fixed- and variable-cell
relaxation, NVE/NVT MD (Langevin, Bussi, Nosé–Hoover chain), and ASE-only isotropic MTK NPT (UMA/MACE/GRACE/DPA), NEB and CI-NEB,
MD-based configuration search for an adsorbate on a slab, batch sweeps and a job
queue, from the CLI, an INCAR-style file, the TUI or Python. NEP's native
gpumdruntime covers only single point, relaxation and MD (see NEP). - No silent guessing. There is no default backend, and a misspelled option, or one that belongs to another backend, stops the run. Configuration errors fail closed.
- A paper trail. Every run records the model file and its SHA-256, the requested and the actual device, the resolved configuration and the mliport version.
- Analysis that says when the data is too short. Trajectory validation, thermodynamics, RDF, RMSD/RMSF, MSD, VACF, spectra, mobile-ion density, kinisi transport, GEMDAT electrolyte analysis and Arrhenius fits.
The full documentation is at https://hydrogen1222.github.io/mliport/ (English and
中文); the same pages are in docs/ and read fine on GitHub.
| I want to … | Read |
|---|---|
| run my first calculation | Quickstart |
| check a model on a system with a known answer | Test systems |
| install one or more backends, on GPU or CPU | Installation |
| understand what MACE, DPA, GRACE, UMA and NEP are and pick one | Backends, Models |
set options through the CLI, an INCAR-style file or settings.ini |
Configuration |
| look up any INCAR key, its default and the values it accepts | INCAR key reference |
| single point, relaxation, MD, NEB, configuration search, batch, queue | Workflows |
| MSD, diffusion, conductivity, RDF, spectra, Arrhenius | Analysis |
| know what each output file contains | Output files |
| fix an error | Troubleshooting |
| cite mliport and the models | Citations |
Linux and WSL2. You need git and uv; the installer
makes one Python environment per backend and a launcher for each under bin/.
curl -LsSf https://astral.sh/uv/install.sh | sh # if you do not have uv yet
git clone https://github.com/hydrogen1222/mliport
cd mliport
# NVIDIA GPU (needs a working CUDA driver)
./scripts/install_mliport.sh --engines mace dpa grace uma --device auto
# or CPU only
./scripts/install_mliport.sh --engines mace dpa grace uma --device cpu
# NEP is opt-in (add it explicitly, alone or with the others)
./scripts/install_mliport.sh --engines nep --device cpuThe installer pins the upstream backend versions, installs the analysis extras and
runs mliport doctor for each engine. Python 3.12 is the default for the
four-engine install; the package supports Python 3.10-3.13, and if you pass
--python, every backend you request must accept it (UMA needs 3.11 or newer). The
install was verified on a V100 with driver 580.173.02; older and newer GPU families
use other wheel routes, listed in docs/installation.md,
together with CPU, offline and proxy setups and uninstalling.
| Engine | Environment | Launcher |
|---|---|---|
| MACE | .venv-mace |
bin/mliport-mace |
| DPA | .venv-dpa |
bin/mliport-dpa |
| GRACE | .venv-grace |
bin/mliport-grace |
| UMA | .venv |
bin/mliport-uma |
| NEP | .venv-nep |
bin/mliport-nep |
NEP is not part of the default engine list. The installer puts the pinned calorine
and an editable mliport into .venv-nep, which is enough for the CPU ASE runtime
(CPUNEP, float64). The native runtime and GPUNEP also need a gpumd executable,
which the installer does not build (it needs your CUDA toolkit and a matching
-arch=sm_XX). On a GPU host, --device auto|cuda makes the closing doctor demand gpumd, so
use --device cpu until you have built it; see docs/backends/nep.md for the build and for
mliport doctor --engine nep.
Run mliport from the environment of the backend you want, or through its launcher:
.venv-mace/bin/mliport doctor --engine mace --device auto
./bin/mliport-mace --helpA good result ends with Environment checks passed for MACE on CUDA. On Windows each
environment has Scripts\mliport.exe and the installer writes bin\mliport-*.cmd
launchers. mliport doctor --json gives the same checks for scripts.
mliport does not download checkpoints. Fetch one with the upstream tool and pass its
path with --model; a local directory works offline.
| Engine | Checkpoint | Where from |
|---|---|---|
| MACE | mace-omat-0-medium.model |
mace-foundations release |
| 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 |
| NEP | your own nep.txt |
trained for your elements and conditions; mliport ships and downloads none |
The hashes the validation suite uses are pinned in
validation/science/model_manifest.json.
Licenses belong to the upstream projects; UMA's checkpoint is under a non-commercial
research license. Hugging Face mirrors and SOCKS proxies are covered in
docs/models.md.
The repository carries a 50-atom Li10GeP2S12 (LGPS) cell, small enough for a CPU smoke test:
.venv-mace/bin/mliport sp examples/structures/li10gep2s12_primitive.vasp \
--model /path/to/mace-omat-0-medium.model \
--model-type mace --task bulk --device cuda \
--output runs/lgps-mace-spIn runs/lgps-mace-sp/ you get mliport_results.json (energy, forces, stress,
timing), resolved_config.json (what was really used), OUTCAR, CONTCAR,
run.log and, for a relaxation or MD run, OSZICAR. A run refuses an output
directory that already holds results and locks it while it works; --overwrite
replaces them on purpose. The device in the result is the one the backend reported,
not the one you asked for.
The backend comes from --model-type or a configured alias. Without one the run
fails; mliport never falls back to another model on its own.
.venv-mace/bin/mliport sp LGPS.vasp --model mace-omat-0-medium.model --model-type mace --task bulk --device cuda
.venv-dpa/bin/mliport sp LGPS.vasp --model DPA-3.1-3M.pt --model-type dpa --task bulk --head Omat24 --device cuda
.venv-grace/bin/mliport sp LGPS.vasp --model GRACE-2L-OMAT-medium-base --model-type grace --task bulk --device cuda
.venv/bin/mliport sp LGPS.vasp --model uma-s-1p2.pt --model-type uma --task omat --device cuda
.venv-nep/bin/mliport sp LGPS.vasp --model nep.txt --model-type nep --nep-runtime ase --device cpu| Engine | --model-type |
Task / head | Good to know |
|---|---|---|---|
| MACE | mace |
bulk |
float64 by default; --dtype float32 is faster, less precise |
| DPA | dpa |
bulk, --head Omat24 |
multitask checkpoint; a missing head is an error, not a guess |
| GRACE | grace |
bulk |
TensorFlow runtime, CPU and GPU |
| UMA | uma (fairchem is an alias) |
omat |
--task omol for molecules; non-commercial research license |
| NEP | nep + required --nep-runtime ase|gpumd |
bulk (PBC only) |
runtime is never inferred; ase = Calorine (cpu float64, cuda float32 via one gpumd process per call), gpumd = one native process per run (float32) |
DPA and GRACE cannot change GPU after their framework has loaded, so when
CUDA_VISIBLE_DEVICES is unset the CLI restarts the command in a fresh process with
the right GPU visible. From Python, set CUDA_VISIBLE_DEVICES before you import
them. More in docs/backends/index.md.
Relaxation. --fmax and --max-steps set convergence; --cell-opt relaxes the
cell with the ions.
.venv-mace/bin/mliport opt LGPS.vasp --model model.model --model-type mace \
--fmax 0.05 --max-steps 200 --cell-opt --device cuda --output runs/lgps-optMolecular dynamics. --ensemble is NVE, NVT, or (ASE UMA/MACE/GRACE/DPA only) isotropic NPT. With NVT, --thermostat is LANGEVIN,
BUSSI or NHC. A run can continue from a saved frame that has velocities with
--velocity-policy preserve --no-pre-relax. With NHC the default --com-policy auto
zeroes the center-of-mass momentum once, so the cell does not drift and bias
MSD-based transport. For NPT use --pressure-gpa, --npt-tdamp, and --npt-pdamp; the variable-cell trajectory is not qualified for direct fixed-cell MSD. See MD workflow.
.venv-mace/bin/mliport md LGPS.vasp --model model.model --model-type mace \
--ensemble NVT --thermostat LANGEVIN --temp 800 --timestep 1.0 \
--steps 10000 --save-interval 100 --device cuda --output runs/lgps-mdNEB and CI-NEB. The two endpoint files define the band, --images sets how many
intermediates, --climb turns on the climbing image. Before the first step mliport
checks, on your own band, whether the model's forces are the gradient of its energy
(noise-aware finite differences) and refuses to go on if they are not; a model whose
predictor reports direct (non-gradient) forces is always refused. The measurement is saved as
gradient_preflight. It is a spot check of consistency, not a statement about
accuracy.
.venv-mace/bin/mliport neb --initial initial.vasp --final final.vasp \
--images 5 --climb \
--model model.model --model-type mace --device cuda --output runs/lgps-nebResume with --resume runs/lgps-neb --output runs/lgps-neb. The step budgets are
part of the run's identity, so changing --max-steps while resuming is rejected.
Advanced explicit atom mapping/image-shift control is available through API/direct
CLI/TUI only.
Configuration search. confsearch looks for low-energy configurations of one
adsorbate on one side of a periodic slab: many independent starts (your structures,
or random placements with --slab/--molecule), each run through heat–hold–cool
Langevin cycles at fixed cell, with every snapshot quenched, classified (molecules
whose covalent skeleton broke are set aside) and deduplicated. The result is a ranked
list of the lowest minima found, with saturation evidence and POSCAR/CP2K files for
DFT re-ranking — never a claim of a global minimum. --dry-run checks the inputs
and the budget without loading a model.
.venv-mace/bin/mliport confsearch run --slab slab.vasp --molecule conformers.xyz \
--n-starts 20 --cycles 5 \
--model model.model --model-type mace --task bulk --device cuda --output runs/adsInterrupted runs continue with confsearch resume, finished ones grow with
confsearch extend --cycles N, and comparable runs combine with confsearch merge.
Details, defaults and limits: docs/workflows/confsearch.md.
Batch, INCAR-style runs, queue, TUI, Python.
.venv-mace/bin/mliport batch structures/ --pattern "*.vasp" --calc-type sp \
--model model.model --model-type mace --device cuda --output runs/batch
.venv-mace/bin/mliport template sp --output INCAR.mliport # edit MODEL_PATH, MODEL_TYPE, ...
.venv-mace/bin/mliport run -i INCAR.mliport -s LGPS.vasp -o runs/incar-sp
.venv-mace/bin/mliport queue submit tasks.json # then: queue start, jobs, queue stopmliport tui opens the interactive application (it needs a terminal). From Python:
from mliport.api import calculate_energy, run_single_point
energy = calculate_energy("LGPS.vasp", "model.model", model_type="mace", device="cuda")
result = run_single_point("LGPS.vasp", "model.model", model_type="mace", device="cuda")analyze takes an mliport run directory or an ASE trajectory:
.venv-mace/bin/mliport analyze runs/lgps-md validate
.venv-mace/bin/mliport analyze runs/lgps-md thermo
.venv-mace/bin/mliport analyze runs/lgps-md msd --mobile Li
.venv-mace/bin/mliport analyze runs/lgps-md rdf --center Li --neighbor S
.venv-mace/bin/mliport analyze runs/lgps-md rmsd
.venv-mace/bin/mliport analyze runs/lgps-md vacf
.venv-mace/bin/mliport analyze runs/lgps-md spectrum
.venv-mace/bin/mliport analyze runs/lgps-md density --mobile Li
.venv-mace/bin/mliport analyze runs/lgps-md transport --mobile Li --charge 1 --fit-start-ps 100
.venv-mace/bin/mliport analyze runs/lgps-md electrolyte --mobile Li --discover-sites-from-densityResults go to runs/lgps-md/analysis/<task>/<id>/ as JSON, CSV and, where it makes
sense, PNG and SVG; plots render headlessly. A short trajectory is accepted but not
over-read: msd and transport return an explicit insufficient-sampling status
instead of a diffusion coefficient, and arrhenius fits only the points you give it.
Options for each task are in docs/analysis/index.md.
The backend is always explicit (--model-type mace|dpa|grace|uma|nep plus --model,
or an alias; nep also needs --nep-runtime). Configuration is strict: unknown and cross-backend keys are errors, and
--lenient-config downgrades them for exploratory runs. mliport config inspects
settings; a project settings.ini can define aliases, and --settings PATH wins
over the user and project files. Each run writes resolved_config.json with the
source of every value.
This is a beta candidate (2.0.0b4). It has been installed from these instructions on a clean V100 machine and run through the LGPS workflow and analysis matrix; the block below is generated from the validation reports.
INCAR-style input covers the common controls, not every interface. Which option each
entry point (API, direct CLI, INCAR, TUI) can express is recorded in
validation/science/capability_matrix.json; a no or partial there means that
entry point cannot say it, and nothing is translated silently.
NEP limits: you supply the nep.txt, and mliport cannot say whether it fits your
material. The native gpumd runtime has no CPU path and refuses NEB, batch and
confsearch instead of switching to the ASE runtime; DFT-D3 is rejected; qNEP,
TNEP and nep4-vdw models are unsupported; partial PBC is refused. NEP is not part
of the validation campaign summarised below: its real-hardware evidence is a V100 with
GPUMD 5.9.1 and CUDA 12.9, and other GPUs and toolkits are unverified. Details:
docs/backends/nep.md.
Model accuracy belongs to the upstream checkpoint. Short MD runs check the workflow, not equilibration. NEB's pre-flight shows the forces match the energy, which says nothing about how accurate the barrier is. Transport analyses fail closed with an insufficient-sampling status instead of returning a number.
The configuration search (confsearch) is new: it is covered by synthetic-model
tests in CI but has not yet been through a real-model GPU validation campaign, and
its deduplication tolerances are calibrated on synthetic geometries only. Treat its
ranking as a screening for DFT, not as a result.
Status: beta validation completed at software commit 5f8d91d4e5fbe8d8d0aacce39470757a72d5c74c (campaign 20260913-current-head-5f8d91d).
Scientific campaign target: commit 5f8d91d4e5fbe8d8d0aacce39470757a72d5c74c (campaign 20260913-current-head-5f8d91d).
LGPS fresh-install acceptance target: commit 51d2a78 (acceptance report).
Current release: 2.0.0b4 (package metadata; the release tag records the exact commit).
Validated hardware: NVIDIA V100-SXM2-16GB (Volta, 16 GiB), driver 580.173.02, Rocky Linux 9.8. CPU installs are smoke-tested on the same host.
Current status: 2.0.0b4 beta. The four backends are installed and exercised on an LGPS structure through single point, relaxation, MD, NEB, batch, INCAR-style runs, queue, TUI, the Python API and the analysis modules.
- Full beta validation report: BETA_VALIDATION.md
- LGPS fresh-install acceptance: LGPS_ACCEPTANCE_REPORT.md
- Model identities: model_manifest.json
Per-workload tables, tier scopes and limitations live in the reports; the README keeps only this status summary.
See docs/citations.md and CITATION.cff. If you
use a backend model, cite the upstream model and respect its license.
The mliport package is under the license in LICENSE.md. Model
checkpoints and the upstream frameworks keep their own licenses.