NEP (Calorine / native GPUMD)¶
NEP (neuroevolution potential) is a potential family, not one model. You
supply a nep.txt trained for your elements and conditions; mliport does not
ship, download or train one, and it cannot tell you whether a given nep.txt
is accurate for your material. Everything below assumes you have such a file.
Unlike the other four backends, NEP has two execution runtimes. You must choose one:
NEP_RUNTIME |
Device | Implementation | Numeric precision | One GPU call = |
|---|---|---|---|---|
ase |
cpu |
calorine.calculators.CPUNEP |
float64 | one in-process evaluation |
ase |
cuda[:N] |
calorine.calculators.GPUNEP |
float32 | one spawned gpumd process |
gpumd |
cuda[:N] |
native gpumd process |
float32 | the whole run |
mliport never infers the runtime, never derives it from the device, and never falls back from one to the other. They differ in precision, in cost model and in which workflows they can perform, so a silent switch would make two runs that look identically configured non-comparable.
NEP_RUNTIME=gpumd with DEVICE=cpu is rejected: there is no CPU native path
in this implementation, and downgrading the request to CPUNEP would change
the precision behind your back.
Installation¶
| Environment | Python | Runtime stack |
|---|---|---|
.venv-nep |
3.10, 3.11, 3.12, 3.13 | calorine==4.1 (NumPy/ASE, resolved by the installer; gpumd built with CUDA Toolkit 12.9) |
Pinned profiles¶
| Profile | Identity | dtype | task | head | model SHA-256 |
|---|---|---|---|---|---|
NEP lives in its own environment because Calorine is a compiled extension. The
installer above creates it with the pinned calorine and an editable
mliport, so .venv-nep/bin/mliport exists. By hand, the equivalent is one
resolver run from the repository root (an environment without mliport has no
mliport command and cannot run doctor):
uv venv .venv-nep --python 3.12
uv pip install --python .venv-nep/bin/python -e './mliport[analysis-all]' calorine==4.1
The native runtime additionally needs the gpumd executable, which is not
installed by the mliport installer (it needs a CUDA toolkit and a matching
-arch=sm_XX for your GPU):
git clone https://github.com/brucefan1983/GPUMD.git
cd GPUMD/src
source /path/to/cuda/env.sh # provides nvcc + libcublas/libcusolver/libcufft
make CUDA_ARCH="-arch=sm_70" -j16 # sm_70 = V100; pick your own architecture
mliport was verified with GPUMD 5.9.1 and CUDA 12.9 on a V100 (sm_70); other
GPUs and toolkits are unverified (see the table of -arch values in the
installer's compatibility registry). Then point mliport at the binary with
NEP_GPUMD_COMMAND / --gpumd-command, or put it on PATH. mliport doctor
looks for gpumd on PATH or in the MLIPORT_GPUMD_COMMAND environment
variable (it does not read NEP_GPUMD_COMMAND). Verify both runtimes at once:
Without gpumd, --device cpu still passes (Calorine CPUNEP needs none) and
--device cuda fails with a message that names the missing executable.
doctor --engine nep reports the Calorine/ASE versions, the resolved gpumd
path and SHA-256, and the first lines of its version banner. It does not
load a model: a NEP run additionally needs your nep.txt.
Configuration¶
.venv-nep/bin/mliport sp structure.vasp \
--model-type nep \
--model /path/to/nep.txt \
--nep-runtime ase \
--device cpu
MODEL_TYPE = NEP
MODEL_PATH = /path/to/nep.txt
NEP_RUNTIME = gpumd # ase | gpumd (required)
NEP_GPUMD_COMMAND = /opt/gpumd/src/gpumd
DEVICE = cuda:0
TASK = bulk # PBC semantic only; NEP has no task families
The same two keys reach every entry point: --nep-runtime / --gpumd-command
on the CLI, nep_runtime= / nep_gpumd_command= in the Python API,
NEP_RUNTIME / NEP_GPUMD_COMMAND in the INCAR and settings.ini, the
runtime selector in the TUI, and the same flags in queue task files. All of
them resolve to one normalised configuration object that reports the value
and its source; they cannot drift.
MODEL_PATH must be a single file. A directory is rejected: a folder of models
has no single identity.
What each runtime can do¶
| Workflow | NEP_RUNTIME=ase |
NEP_RUNTIME=gpumd |
|---|---|---|
single point (sp) |
yes | yes |
fixed-cell optimisation (opt) |
yes | yes, minimize fire\|sd |
| cell/box optimisation | only through the existing ASE contract | minimize fire ... 1 |
MD NVE |
yes (ASE integrator) | yes (native, recommended) |
MD NVT |
yes (ASE integrators) | yes, thermostat-mapped (see below) |
NEB / CI-NEB |
yes | rejected |
batch, confsearch |
yes | rejected |
The native runtime refuses neb, batch and confsearch with an error that
names NEP_RUNTIME=ase. It does not reroute them. A NEB band driven by the
native process would need its own scheduler, and quietly switching runtimes
would mix two potentials' absolute energies inside one ranking.
DFT-D3 is rejected for NEP in both runtimes. A NEP model may already carry a
van der Waals term (nep4-vdw), and mliport has no evidence that adding D3 on
top avoids double-counting dispersion. The option is refused, not silently
dropped.
Precision and what "the same numbers" means¶
CPUNEP computes in float64; GPUNEP and native gpumd compute in float32.
The precision double option in a GPUMD input file only widens the text
output — it does not make the inference double precision. Comparing the two
runtimes on one structure therefore needs a measured float32 noise floor, not a
bit-for-bit expectation.
Nothing in mliport's output claims otherwise: model.manifest.json /
resolved_config.json record numeric_precision (float64 or float32),
per_call_subprocess, the gpumd path/SHA-256/version and the actual GPU UUID.
Cost model — do not mix these up¶
NEP_RUNTIME=ase on a CUDA device runs Calorine GPUNEP, which writes inputs,
launches gpumd and reads outputs on every ASE evaluation. Every MD step or
optimiser step pays process startup and file I/O. mliport warns about this at
calculator construction and records per_call_subprocess: true.
Native NEP_RUNTIME=gpumd launches one process for the entire run. Any
steps-per-second comparison between the two is a statement about the adapter,
not about NEP. Never quote a GPUNEP ASE-MD throughput as native GPUMD
performance.
Native MD: thermostats, velocities, and what is not ASE¶
GPUMD's ensemble nvt_* coupling constant is T_coup = tau_T / dt, a
dimensionless number, and mliport converts your ASE-style time parameters
exactly:
mliport THERMOSTAT |
GPUMD ensemble | tau_T used |
|---|---|---|
LANGEVIN |
nvt_lan |
1 / friction (friction in 1/fs) |
BUSSI |
nvt_bdp |
bussi_tau (fs) |
NHC |
nvt_nhc |
nhc_tdamp (fs) |
T_coup = round(tau_T / dt) and must be >= 1; anything smaller is rejected
because GPUMD would silently reinterpret it. The chosen mapping, tau_T and
T_coup are recorded in the run manifest.
velocity <T> seed <N> is not a Maxwell–Boltzmann draw and it zeroes the
total linear and angular momentum. Do not treat a GPUMD-initialised NVT run as
equivalent to an ASE-Maxwell initialised one; the manifest records the method
and the seed so the difference stays traceable.
Velocities written into model.xyz are in Å/fs. ASE momenta are in
amu·Å/(ASE internal time unit), so the conversion is
momentum / mass * ase.units.fs; a literal p/m would be off by ~10x.
Native output layout¶
<out>/native/model.xyz extended XYZ: species, positions, lattice, pbc, velocities
<out>/native/run.in the exact input file that was executed
<out>/native/thermo.out raw GPUMD thermo (append semantics preserved)
<out>/native/traj.xyz raw dump_xyz output, untouched
<out>/native/stdout.log
<out>/native/stderr.log
<out>/native/restart.xyz only when dump_restart was requested
<out>/native/provenance.json
<out>/trajectory.extxyz normalised frames (step, time, cell, pbc, unwrapped)
<out>/manifest.json terminal status + identity + verified frame schedule
Raw GPUMD files are written before any normalisation and never deleted, on
success or failure. A gpumd exit status of 0 with a missing or unparseable
required output is reported as failed, never completed.
When is an MD run completed?¶
Exit status 0 only says that the process ended. An MD run is completed only
if its dump is the complete product of the run.in that was executed:
- the number of frames equals
steps // dump_interval(GPUMD writes one frame perdump_intervalcompleted steps, so a request that is not a multiple of the interval ends with a partial interval that writes no frame; 20 steps at interval 10 gave 2 frames and 200 at 20 gave 10 on a V100); - every frame carries a recorded
Time=(never inferred), the times are strictly increasing and uniformly spaced bydump_interval * dt, sit on the integration-step grid, and the last frame lies inside the final dump interval of the requested run; - every frame has the input species in the input order, full 3-D PBC, the input cell (the native NVE/NVT ensembles are fixed-cell) and the same columns as frame 0;
thermo.outhas exactly one row per frame and, when its header states them, the samedump_thermo,dt_outputandnum_atomsasrun.in/the input.
A run that fails any of these is failed with the reason in the manifest and in
the result. The normalised trajectory.extxyz is written to a .partial file
and published only after every check passed, so a failed run never leaves
something that looks like a result; the raw native/ files stay as evidence.
The manifest also records the verified schedule (trajectory.schedule: frame
count, first/last step and time, interval, position convention) and the
trajectory's SHA-256.
The offset of the first frame inside its dump interval is a GPUMD detail that is not asserted here; count, spacing and coverage of the requested window fix the run length without it. The steps after the last dump of a request that is not a multiple of the interval leave no output, so for them the exit status is the only evidence.
The conversion is a single streaming pass (one frame in memory), so the post-processing cost of a long run is bounded by the frame size, not the run length.
Loading a native run for analysis¶
TrajectoryDataset.load(<out>) (and therefore every mliport analyze
task) accepts a native GPUMD run directory. The manifest is authoritative: the
run must be an MD run with status completed, trajectory.extxyz must be
byte-identical to the SHA-256 the runner recorded, and the frames must agree
with the manifest (count, atoms, PBC, position convention, recorded times and
steps). Otherwise the loader raises InvalidTrajectoryError instead of
producing a dataset. The dataset carries the GPUMD-recorded time axis and steps,
the dump interval and dt, 3-D PBC, GPUMD's own per-atom masses, the target
temperature from run.in, and the position convention actually dumped
(unwrapped with unwrapped_position, otherwise wrapped). Explicit
positions_convention, md_timestep_fs, frame_stride_steps or
frame_interval_fs that contradict the manifest are refused. The native dump
holds no velocities (dump_xyz is run without vel), so VACF-type analyses are
unavailable for it.
Units and signs¶
GPUMD writes virial (eV, nine row-major components) and a stress field that
is virial / volume in eV/ų. ASE's stress convention is the opposite sign:
thermo.out columns are T KE PE sxx syy szz syz sxz sxy ax..cz, with the
stress components in GPa. Note the difference between the two files: the
dump_xyz virial/stress fields are the potential (virial) part only,
while thermo.out sxx..sxy is the total stress including the kinetic
contribution, so the two do not agree at finite temperature even after unit
conversion. mliport reports the potential-only stress (the quantity that is the
derivative of the potential energy, and the one comparable with the ASE
calculators of the other backends) and keeps thermo.out raw for inspection.
Both conventions are checked by a finite-difference known-answer test against
CPUNEP, not by trusting the header.
Unwrapped positions and transport analysis¶
dump_xyz ... unwrapped_position gives the unfolded trajectory, which is what
tracer MSD, collective charge displacement and Haven ratios need. When that
column is unavailable, the manifest sets msd_eligible: false with a reason and
mliport refuses to derive bulk transport from sparse wrapped positions. Variable
cell runs have no single displacement reference and are not used for transport
in this release.
restart.xyz is an overwrite-only file with no RNG state; a single existing
file is not a reproducible MD checkpoint, and it is recorded as such.
Versioned GPUMD model files (including NEP89)¶
New GPUMD models can use an element list on the first line followed by
format_version 1 and model nep instead of the legacy nep4 token:
Both NEP runtimes now recognize this format and keep the declared element
order, model family, format version, ZBL, energy references and per-element
cutoffs in their scientific identity. Native provenance also retains the
original model's SHA-256. Only the standard energy model (model nep)
is accepted: spin/temperature, qNEP, dipole, polarizability and learned-vdW
variants are intentionally rejected. The parser validates metadata but does
not verify the complete parameter block. You still need a GPUMD binary
that understands the file version. Calorine support for this newer model
layout has not been verified; use the native runtime for its first real test.
Known limits of this release¶
- No
qNEP/TNEP/nep4-vdwsupport: those model types change the meaning of the energy (free energy, dipoles) and must not be used as a plain potential. They are outside this release's verified scope. - Partial PBC (
T T F) is rejected for the native runtime instead of being promoted toT T T. - Variable-cell optimisation is exposed only through the ASE runtime contract.
- Native checkpoint/restart equivalence is not claimed.
- Accuracy of any particular
nep.txtfor a particular material is a model question, not a mliport question.runtime_supportedis notphysically_validated_on_target.