Molecular dynamics¶
mliport md runs NVE, NVT or NPT dynamics with the backend you pick and records a
trajectory that the analysis tools can read back.
.venv-mace/bin/mliport md structure.cif \
--model mace-omat-0-medium.model --model-type mace \
--ensemble NVT --temp 300 --timestep 1.0 --steps 1000 \
--equilibration-steps 500 --save-interval 10 \
--output runs/md
You need a periodic structure, a model and an explicit backend. MD on a
molecule needs a molecular task (omol / molecule) and sensible charge and
spin.
Isotropic NPT cell equilibration (ASE-only)¶
For UMA/MACE/GRACE/DPA, --ensemble NPT uses ASE's isotropic Martyna–Tobias–Klein (MTK) thermostat/barostat, not Langevin/Bussi/NHC. Example:
mliport md structure.cif --model model.pt --model-type mace \
--ensemble NPT --temp 800 --pressure-gpa 0 \
--npt-tdamp 100 --npt-pdamp 1000 \
--timestep 0.5 --steps 50000 --save-interval 10 \
--no-pre-relax --output runs/npt-800K
In INCAR-style files and settings.ini the same options are ENSEMBLE (or MD_ENSEMBLE) = NPT, PRESSURE_GPA (alias PRESSURE), NPT_TDAMP, NPT_PDAMP, NPT_TCHAIN, NPT_PCHAIN, NPT_TLOOP and NPT_PLOOP; the NPT-only keys are rejected unless the ensemble is NPT.
The parameters --npt-tchain/--npt-pchain default to 3 and --npt-tloop/--npt-ploop to 1. Times are in fs. Positive pressure is compressive (GPa); the conversion to ASE eV/ų is recorded. Thermostat and barostat damping are not equilibration time guarantees. The NPT run uses 3D PBC, a finite positive-volume cell, and model stress. It rejects all atomic/COM constraints, partial PBC, zero T, and unsupported backends (including NEP/GPUMD). Automatic COM handling zeroes initial COM momentum once; the recorded MTK thermostat set point accounts for the 3 missing kinetic degrees of freedom.
Standard XDATCAR represents fixed-cell MD only: NPT disables XDATCAR with a logged reason, while raw/trajectory.traj preserves each frame's cell and momenta. The md.csv file records instantaneous total pressure including the kinetic term, and volume per saved frame. NPT trajectory metadata is marked variable-cell / transport-ineligible: do not calculate conventional fixed-cell MSD, Einstein–Helfand conductivity or diffusion from it. For solid electrolytes, equilibrate volume/cell at the target T and pressure, extract the equilibrated-window mean cell with an independent statistical check, then start a separate fixed-cell NVT/NVE run. The last NPT frame is not automatically an average cell. NPT frame restarts do not preserve hidden MTK chain/barostat state and are not exact trajectory continuation. Near a phase transition or an anisotropic crystal, an isotropic cell-only barostat may be insufficient.
Options you will use¶
| Option | Meaning |
|---|---|
--ensemble |
NVT (default), NVE, or isotropic NPT (UMA/MACE/GRACE/DPA ASE only) |
--temp |
target temperature in K (default 300) |
--pressure-gpa |
NPT external hydrostatic pressure in GPa (+ compressive; default 0) |
--npt-tdamp, --npt-pdamp |
NPT MTK thermostat/barostat damping times in fs |
--npt-tchain, --npt-pchain, --npt-tloop, --npt-ploop |
NPT MTK chain lengths and integration substeps |
--timestep |
integration step in fs (default 1.0) |
--steps |
production steps (default 1000) |
--equilibration-steps |
equilibration in the same ensemble before production (default 0) |
--thermostat |
LANGEVIN (default), BUSSI or NHC |
--friction, --bussi-tau, --nhc-tdamp, --nhc-tchain, --nhc-tloop |
thermostat parameters |
--save-interval |
write a frame every N steps (default 10) |
--seed |
random seed; generated and recorded when omitted |
--velocity-policy, --com-policy |
how velocities and the center-of-mass motion are handled |
--pre-relax, --pre-relax-steps, --pre-relax-fmax |
a short positions-only relaxation before MD (default on for NVT, off for NVE and NPT; 50 steps, 0.1 eV/Å) |
--fmax-abort |
abort when a force exceeds this many eV/Å (default 20) |
--write-outcar, --write-xdatcar, --write-trajectory |
which outputs to write |
Pre-relaxation is a gate, not a suggestion¶
If the pre-relaxation does not reach --pre-relax-fmax within
--pre-relax-steps, the run stops before production MD. Starting dynamics
from a structure that is still far from a minimum is rarely what anyone wants,
and a silent "good enough" would hide it. The error tells you what to do: raise
the step budget, loosen the threshold if you can justify it scientifically, or
turn pre-relaxation off explicitly. The outcome of a pre-relaxation that did
finish is recorded in md_provenance.pre_relax.
Timestep, save interval and what analysis sees¶
--timestep is how the equations of motion are integrated; --save-interval
is how often a frame is written. With a 1 fs timestep and --save-interval 10
you get a frame every 10 fs, and it is this saved spacing, not the integration
step, that transport analysis needs.
Keep equilibration out of your statistics: use --equilibration-steps and
analyze only the production segment. Keep the ensembles apart, too. NVE and NVT
are different dynamics and their trajectories should never be averaged together.
Thermostats and center-of-mass motion¶
--thermostat chooses how NVT temperature is controlled. Langevin is
stochastic; Bussi and NHC are deterministic. Transport coefficients depend on the
choice, so state it when you report a diffusion coefficient.
NHC deserves a note. It cannot run together with a FixCom (or any other)
constraint. With the default --com-policy auto (the same as initialize_only)
mliport zeroes the center-of-mass momentum once after initializing velocities,
which NHC then conserves. The run therefore has 3N-3 kinetic degrees of
freedom, and the thermostat set point is scaled by (3N-3)/3N (recorded as
nhc_set_temperature_K). With --com-policy none the random center-of-mass
momentum stays, the whole cell drifts ballistically, and that drift dominates the
MSD of the mobile ions unless the analysis removes it.
Constraints and fixed atoms are applied through the calculator and runners; state them when you report diffusion.
Continuing a run¶
md has no --resume flag. To continue, read a saved frame that carries
momenta and start a new run from it:
.venv-mace/bin/mliport md last_frame.traj --model mace-omat-0-medium.model \
--model-type mace --velocity-policy preserve --no-pre-relax --output runs/md-part2
The new run keeps the supplied positions and velocities and does not draw a fresh Maxwell–Boltzmann distribution. It is a separate run directory with its own record, and its first frame equals the last frame of the previous leg (the acceptance suite checks exactly that).
What can stop a run¶
A force above --fmax-abort or a NaN aborts the run rather than writing corrupt
frames. A failure while writing output aborts it too, instead of silently
dropping frames. A missing model or structure, or an option combination that is
not supported, fails before the dynamics start.
The acceptance matrix runs 5-step NVE and 5-step Langevin, Bussi and NHC smoke tests in all four backend environments. Those runs check the workflow and the thermostat plumbing, not that the temperature has equilibrated.
A production-style example¶
.venv/bin/mliport md structure.cif --model uma.pt --model-type uma --task omat \
--ensemble NVT --temp 800 --timestep 1.0 \
--equilibration-steps 5000 --steps 50000 --save-interval 10 \
--thermostat NHC \
--output runs/md-800K
The files this produces are described in Output files: the
canonical trajectory and md.csv under raw/, the VASP-style files under
vasp/, and artifacts.json listing them with units and hashes.