VPMDK

VPMDK (Vasp-Protocol Machine-learning Dynamics Kit, aka “VasP-MoDoKi”) is a lightweight engine that reads and writes VASP-style inputs/outputs and performs molecular dynamics and structure relaxations using machine-learning interatomic potentials. Keep familiar VASP workflows and artifacts while computations run through ASE-compatible ML calculators. The vpmdk command (and legacy vpmdk.py wrapper) are provided.

Supported calculators (via ASE): CHGNet, SevenNet, MatterSim, MACE, Matlantis, NequIP, Allegro, ORB, MatGL (via the M3GNet model), FAIRChem (including eSEN checkpoints), GRACE (TensorPotential foundation models or checkpoints), and DeePMD-kit. Availability depends on the corresponding Python packages being installed.

Not affiliated with, endorsed by, or a replacement for VASP; “VASP” is a trademark of its respective owner. VPMDK only mimics VASP I/O conventions for compatibility.

Installation

Install the package from PyPI (or from a checkout):

pip install vpmdk

Usage

1. Prepare a directory containing at least POSCAR. Optional files are INCAR, POTCAR, and BCAR. KPOINTS, WAVECAR, and CHGCAR are recognised but ignored (a note is printed if they are present).

2. Install requirements: ase, pymatgen and, depending on the potential you wish to use, chgnet, mattersim, mace-torch or matgl.

3. Run:

   vpmdk [--dir PATH_TO_INPUT]

If --dir is omitted, the current directory (.) is used.

When running directly from a repository checkout, the legacy wrapper still works:

python vpmdk.py [--dir PATH_TO_INPUT]

Input files

Calculation directories may contain the following files:

• POSCAR (required) – atomic positions and cell.
• INCAR – VASP-style run parameters; only a subset of tags is supported.
• BCAR – simple key=value file selecting the machine-learning potential.
• POTCAR – accepted for compatibility but ignored except for aligning species names.

Supported INCAR tags

The script reads a subset of common VASP INCAR settings. Other tags are ignored with a warning.

Tag	Meaning	Default / Notes
NSW	Number of ionic steps.	0 (single-point calculation).
IBRION	Ionic movement algorithm.	<0 performs a single-point calculation without moving ions, 0 runs molecular dynamics, positive values trigger a BFGS geometry optimisation with a fixed cell. Defaults to -1.
ISIF	Controls whether the cell changes during relaxations.	2 keeps the cell fixed (default). 3 relaxes ions and the full cell, 4 keeps the volume constant while optimising ions and the cell shape, 5 optimises the cell shape at constant volume with fixed ions, 6 changes only the cell, 7 enables isotropic cell changes with fixed ions, and 8 couples ionic relaxations to isotropic volume changes. Stress output follows VASP-style semantics: ISIF<=0 omits stress blocks, ISIF=1 writes trace-only pressure information, and ISIF>=2 writes the full stress tensor block. Unsupported values fall back to 2 behavior with a warning.
EDIFFG	Convergence criterion for relaxations.	<0: force criterion using abs(EDIFFG) in eV/Å (default -0.02). >0: energy criterion using EDIFFG in eV (`
TEBEG	Initial temperature in kelvin for molecular dynamics (IBRION=0).	300.
TEEND	Final temperature in kelvin when ramping MD runs.	Same as TEBEG. Temperature is linearly ramped between TEBEG and TEEND over the MD steps.
POTIM	Time step in femtoseconds for molecular dynamics (IBRION=0).	2.
MDALGO	Selects the MD integrator / thermostat.	0 (NVE). When left at 0, SMASS>0 falls back to Nose–Hoover (MDALGO=2) and SMASS<0 falls back to Langevin (MDALGO=3). See MD algorithms for details.
SMASS	Thermostat-specific mass parameter.	Used for Nose–Hoover time constant (abs(SMASS) fs) or as a fallback to set LANGEVIN_GAMMA when negative.
ANDERSEN_PROB	Collision probability for the Andersen thermostat.	0.1. Only used with MDALGO=1.
LANGEVIN_GAMMA	Friction coefficient (1/ps) for Langevin dynamics.	1.0. Only used with MDALGO=3; falls back to abs(SMASS) when SMASS<0.
CSVR_PERIOD	Relaxation time (fs) for the canonical sampling velocity rescaling thermostat.	max(100×POTIM, POTIM). Only used with MDALGO=5.
NHC_NCHAINS	Nose–Hoover chain length.	1 for MDALGO=2, 3 for MDALGO=4.
PSTRESS	External pressure in kBar applied during relaxations.	Converts to scalar pressure in the ASE optimiser when ISIF allows cell changes.
MAGMOM	Initial magnetic moments.	Parsed like VASP; supports shorthand such as 2*1.0.
IMAGES	Number of NEB images.	Enables NEB mode detection. When numbered image directories (00, 01, ...) exist, VPMDK runs them sequentially and emits NEB-style projection lines in each image OUTCAR.
LCLIMB	Climbing-image switch for NEB.	Used as a compatibility hint for VTST post-processing outputs.
SPRING	Spring constant for NEB.	Used as a compatibility hint for VTST post-processing outputs.

MD algorithms

MDALGO selects between different ASE molecular dynamics drivers. Some options require optional ASE modules; if they are missing VPMDK falls back to plain velocity-Verlet (NVE) integration and prints a warning.

MDALGO	Integrator	Notes
0	Velocity-Verlet (NVE)	No thermostat.
1	Andersen thermostat	Controlled by ANDERSEN_PROB.
2	Nose–Hoover chain (single thermostat)	Uses SMASS/NHC_NCHAINS to configure the chain.
3	Langevin thermostat	Uses LANGEVIN_GAMMA (or abs(SMASS) if negative).
4	Nose–Hoover chain (three thermostats)	Chain length defaults to 3 unless overridden.
5	Bussi (canonical sampling velocity rescaling) thermostat	Uses CSVR_PERIOD.

BCAR tags

BCAR is a concise key=value file that selects the backend, its weights, and a handful of quality-of-life options. A minimal file looks like:

MLP=CHGNET            # Potential backend
MODEL=/path/to/model  # Optional path to weights (varies by backend)
DEVICE=cuda           # Optional device override when the backend supports it

Core selection.

Tag	Meaning	Default
MLP	Backend name (CHGNET, MACE, MATGL, MATLANTIS, MATTERSIM, NEQUIP, ALLEGRO, ORB, FAIRCHEM, FAIRCHEM_V2, FAIRCHEM_V1, GRACE, DEEPMD, SEVENNET)	CHGNET
MODEL	Path to a trained parameter set (ORB accepts checkpoints; FAIRChem also accepts model names such as esen-sm-direct-all-oc25)	Backend default or bundled weights
DEVICE	Device hint for backends that support it (cpu, cuda, cuda:N)	Auto-detects GPU when available

NNP is accepted as a backward-compatible alias of MLP.

Output and workflow aids.

Tag	Meaning	Default
WRITE_ENERGY_CSV	Write energy.csv during relaxation (1 to enable)	0
WRITE_LAMMPS_TRAJ	Write a LAMMPS trajectory during MD (1 to enable)	0
LAMMPS_TRAJ_INTERVAL	MD steps between trajectory frames (only when WRITE_LAMMPS_TRAJ=1)	1
WRITE_OSZICAR_PSEUDO_SCF	Add pseudo electronic-step (DAV:) lines to OSZICAR (1 to enable)	0 (OFF)
DEEPMD_TYPE_MAP	Comma/space-separated species list mapped to the DeePMD graph	Inferred from POSCAR order
DEEPMD_HEAD	Select a DeePMD model head by name (when supported by the checkpoint)	Unset

WRITE_PSEUDO_SCF is accepted as a compatibility alias of WRITE_OSZICAR_PSEUDO_SCF.

Backend-specific knobs. Only relevant when the corresponding backend is chosen.

Tag	Applies to	Meaning	Default
MATLANTIS_MODEL_VERSION	Matlantis	Estimator version identifier	v8.0.0
MATLANTIS_PRIORITY	Matlantis	Job priority forwarded to the estimator	50
MATLANTIS_CALC_MODE	Matlantis	Calculation mode (CRYSTAL, MOLECULE, …)	PBE
ORB_MODEL	ORB	Pretrained architecture key recognised by orb_models	orb-v3-conservative-20-omat
ORB_PRECISION	ORB	Floating-point precision string forwarded to orb-models loaders	float32-high
ORB_COMPILE	ORB	Whether to torch.compile the ORB model (0/1, true/false, …)	Library default
FAIRCHEM_TASK	FAIRChem v2 (FAIRCHEM/FAIRCHEM_V2)	Task head to use (e.g. omol)	Auto-detected when possible
FAIRCHEM_INFERENCE_SETTINGS	FAIRChem v2 (FAIRCHEM/FAIRCHEM_V2)	Inference profile forwarded to FAIRChem	default
FAIRCHEM_CONFIG	FAIRChem v1 (FAIRCHEM_V1)	Path to the YAML config used with the checkpoint	Required for most checkpoints
FAIRCHEM_V1_PREDICTOR	FAIRChem v1 (FAIRCHEM_V1)	Use the predictor directly instead of the OCPCalculator (1 to enable)	0
GRACE_PAD_NEIGHBORS_FRACTION	GRACE	Fake-neighbour padding fraction forwarded to TensorPotential	Library default (typically 0.05)
GRACE_PAD_ATOMS_NUMBER	GRACE	Number of fake atoms for padding	Library default (typically 10)
GRACE_MAX_RECOMPILATION	GRACE	Max recompilations triggered by padding reduction	Library default (typically 2)
GRACE_MIN_DIST	GRACE	Minimum allowed interatomic distance	Unset (no extra validation)
GRACE_FLOAT_DTYPE	GRACE	Floating-point dtype passed to TensorPotential	float64

Matlantis calculations rely on the Matlantis API via pfp-api-client; ensure your environment is configured with the required API credentials before running VPMDK with MLP=MATLANTIS.

ORB calculations rely on the orb-models package. When MODEL is omitted, VPMDK downloads the pretrained weights specified by ORB_MODEL using orb-models; set MODEL=/path/to/checkpoint.ckpt to run with local weights.

FAIRChem 2.x and 1.x are incompatible. Select MLP=FAIRCHEM (or MLP=FAIRCHEM_V2) to use FAIRChem v2 checkpoints via FAIRChemCalculator.from_model_checkpoint, and MLP=FAIRCHEM_V1 when running legacy OCP/FAIRChem v1 checkpoints with OCPCalculator. Switching conda environments per checkpoint version is supported by selecting the appropriate tag.

Output files

Depending on the calculation type, VPMDK produces the following files in VASP format:

File	When produced	Contents
CONTCAR	Always	Final atomic positions and cell.
OUTCAR	Always	VASP-like step blocks plus a simplified timing/memory footer at the end of each run.
OSZICAR	Always	VASP-like ionic-step energy summary (F, E0, dE; and MD thermostat terms) with VASP-like aligned scientific notation. Optional pseudo electronic-step (DAV:) lines are added only when WRITE_OSZICAR_PSEUDO_SCF=1; these are compatibility placeholders, not real electronic SCF iterations.
vasprun.xml	Always	Minimal VASP-like XML containing initial/final structures, per-step energies, and forces.
XDATCAR	MD only (IBRION=0)	Atomic positions at each MD step (trajectory).
lammps.lammpstrj	MD with WRITE_LAMMPS_TRAJ=1	LAMMPS text dump of atomic positions at the requested interval.
energy.csv	Relaxations with WRITE_ENERGY_CSV=1	Potential energy at each relaxation step.

Relaxation convergence follows VASP-like EDIFFG sign semantics:

• EDIFFG < 0: converged when the maximum force is below abs(EDIFFG) (eV/Å).
• EDIFFG > 0: converged when |ΔE| between ionic steps is below EDIFFG (eV).

When INCAR contains NEB-style tags (for example IMAGES, LCLIMB, or SPRING) and numbered image directories are present, VPMDK iterates over those directories (00, 01, ...) and runs each image. For compatibility with VTST post-processing scripts, each image OUTCAR includes a NEB: projections ... line in every ionic block. This runner performs independent per-image calculations and does not apply spring-coupled NEB forces between images.

The NEB CHAIN block values are approximate: VPMDK estimates the local tangent from neighboring image position differences (next-prev, or one-sided at endpoints), then projects the per-atom force onto that tangent to populate tangential force, TANGENT/CHAIN-FORCE, and CHAIN + TOTAL.

For NEB-style directory runs, VPMDK also writes parent-level aggregate OUTCAR, OSZICAR, and vasprun.xml files in the top NEB directory using the final state from each numbered image.

Initial magnetic moments from MAGMOM are propagated to ASE when the value can be matched with the number of atoms or species counts in the POSCAR.

Final energies are also printed to the console for single-point calculations.

Required Python modules

ase and pymatgen are always required. Additional modules depend on the selected potential or thermostat:

Feature	Module to install	Notes
CHGNet potential	chgnet (uses PyTorch)	Bundled with a default model; specify MODEL to use another
SevenNet potential	sevennet (uses PyTorch)	Bundled with a default model; specify MODEL to use another
NequIP potential	nequip (uses PyTorch)	MODEL should point to a deployed model file; compiled/TorchScript models are also accepted when supported by the NequIP version (from_compiled_model)
Allegro potential	allegro (uses PyTorch and depends on nequip)	MODEL should point to a deployed model file; compiled/TorchScript models are also accepted when supported by the NequIP version (from_compiled_model)
MatGL (M3GNet) potential	matgl (uses PyTorch + DGL or JAX, depending on install)	Bundled with a default model; specify MODEL to use another. MatGL 1.x commonly expects a model directory passed through matgl.load_model.
MACE potential	mace-torch (PyTorch)	Set MODEL to a trained .model file
DeePMD-kit potential	deepmd-kit	Set MODEL to the frozen graph (.pb) or a PyTorch checkpoint (.pt), depending on the DeePMD backend, and optionally DEEPMD_TYPE_MAP/DEEPMD_HEAD
Matlantis potential	pfp-api-client (plus matlantis-features)	Uses the Matlantis estimator service; configure with MATLANTIS_* BCAR tags
ORB potential	orb-models (PyTorch)	Downloads pretrained weights unless MODEL points to a checkpoint
MatterSim potential	mattersim (PyTorch)	Set MODEL to the trained parameters
GRACE potential	grace-tensorpotential (TensorFlow)	Uses TensorPotential checkpoints (MODEL=/path/to/model) or foundation models when available
Andersen thermostat	ase.md.andersen (part of ASE extras)	Install ASE with MD extras to enable
Langevin thermostat	ase.md.langevin	Ships with ASE; ensure ASE is up to date
Bussi thermostat	ase.md.bussi	Included in ASE >= 3.22
Nose–Hoover chain thermostat	ase.md.nose_hoover_chain	Included in ASE >= 3.22

Install each module using pip install MODULE_NAME. Install the GPU-enabled version of PyTorch or JAX if you want to use GPUs.

Where to place parameter files

The model file is loaded from the path given by MODEL in BCAR. Typically the file is located within the calculation directory or specified via an absolute path. CHGNet and MatGL ship with default models; omitting MODEL uses those defaults automatically.

GPU usage

This script does not directly manage GPU settings. Each potential selects a device on its own. CHGNet, MatGL/M3GNet, MACE, ORB, and FAIRChem honour DEVICE in BCAR (e.g. DEVICE=cpu to force a CPU run). With CUDA devices you can choose which GPU to use with CUDA_VISIBLE_DEVICES. MatGL GPU tuning is backend-dependent (PyTorch+DGL vs JAX), so environment variables differ between installations. A GPU with at least 8 GB of memory is recommended, though running on a CPU also works.

Example directory layout

calc_dir/
├── POSCAR      # required
├── INCAR       # optional
├── POTCAR      # optional
└── BCAR        # optional, specify potential and model path

Example command:

vpmdk --dir calc_dir

License

VPMDK is distributed under the BSD 3-Clause License. See LICENSE for details.