dpdata CLI
dpdata is a tool for manipulating multiple atomic simulation data formats. This skill enables format conversion between various DFT/MD software outputs via command line.
Quick Start
Run dpdata via uvx:
uvx dpdata <from_file> [options]
Command Line Usage
dpdata: Manipulating multiple atomic simulation data formats
usage: dpdata [-h] [--to_file TO_FILE] [--from_format FROM_FORMAT]
[--to_format TO_FORMAT] [--no-labeled] [--multi]
[--type-map TYPE_MAP [TYPE_MAP ...]] [--version]
from_file
Arguments
| Argument |
Description |
from_file |
Read data from a file (positional) |
--to_file, -O |
Dump data to a file |
--from_format, -i |
Format of from_file (default: "auto") |
--to_format, -o |
Format of to_file |
--no-labeled, -n |
Labels aren't provided (default: False) |
--multi, -m |
System contains multiple directories (default: False) |
--type-map, -t |
Type map for atom types |
--version |
Show dpdata version and exit |
Common Examples
Convert VASP OUTCAR to deepmd format
uvx dpdata OUTCAR -i vasp/outcar -O deepmd_data -o deepmd/raw
Convert LAMMPS dump to VASP POSCAR
uvx dpdata dump.lammps -i lammps/dump -O POSCAR -o vasp/poscar
Convert with type map
uvx dpdata OUTCAR -i vasp/outcar -O deepmd_data -o deepmd/raw -t C H O N
Convert multiple systems
uvx dpdata data_dir -i vasp/outcar -O output_dir -o deepmd/comp --multi
Convert to deepmd/npy (compressed format)
uvx dpdata OUTCAR -i vasp/outcar -O deepmd_npy -o deepmd/npy
Convert to deepmd/hdf5
uvx dpdata OUTCAR -i vasp/outcar -O data.h5 -o deepmd/hdf5
Supported Formats
Formats may be updated. For the complete and latest list, see:
DeePMD-kit Formats
| Format Name |
Description |
deepmd/raw |
DeePMD-kit raw text format |
deepmd/comp / deepmd/npy |
DeePMD-kit compressed numpy format |
deepmd/npy/mixed |
DeePMD-kit mixed type format |
deepmd/hdf5 |
DeePMD-kit HDF5 format |
VASP Formats
| Format Name |
Description |
vasp/poscar / vasp/contcar / poscar / contcar |
VASP structure files |
vasp/outcar / outcar |
VASP OUTCAR output |
vasp/xml / xml |
VASP XML output |
vasp/string |
VASP string format |
LAMMPS Formats
| Format Name |
Description |
lammps/lmp / lmp |
LAMMPS data file |
lammps/dump / dump |
LAMMPS dump file |
ABACUS Formats
| Format Name |
Description |
stru / abacus/stru |
ABACUS structure file |
abacus/lcao/scf / abacus/pw/scf / abacus/scf |
ABACUS SCF output |
abacus/lcao/md / abacus/pw/md / abacus/md |
ABACUS MD output |
abacus/lcao/relax / abacus/pw/relax / abacus/relax |
ABACUS relax output |
Quantum ESPRESSO Formats
| Format Name |
Description |
qe/cp/traj |
QE CP trajectory |
qe/pw/scf |
QE PWscf output |
CP2K Formats
| Format Name |
Description |
cp2k/output |
CP2K output |
cp2k/aimd_output |
CP2K AIMD output |
Gaussian Formats
| Format Name |
Description |
gaussian/log |
Gaussian log file |
gaussian/fchk |
Gaussian formatted checkpoint |
gaussian/md |
Gaussian MD output |
gaussian/gjf |
Gaussian input file |
Other Formats
| Format Name |
Description |
xyz |
XYZ format |
mace/xyz / nequip/xyz / gpumd/xyz / extxyz / quip/gap/xyz |
Extended XYZ variants |
ase/structure |
ASE structure format |
ase/traj |
ASE trajectory |
pymatgen/structure |
pymatgen structure |
pymatgen/molecule |
pymatgen molecule |
gromacs/gro / gro |
GROMACS gro file |
siesta/output |
SIESTA output |
siesta/aimd_output |
SIESTA AIMD output |
pwmat/output / pwmat/mlmd / pwmat/movement |
PWmat output |
pwmat/final.config / pwmat/atom.config |
PWmat config |
orca/spout |
ORCA output |
psi4/out |
PSI4 output |
dftbplus |
DFTB+ output |
fhi_aims/output / fhi_aims/md |
FHI-aims output |
amber/md |
AMBER MD |
n2p2 |
n2p2 format |
mol_file / mol |
MOL file |
sdf_file / sdf |
SDF file |
openmx/md |
OpenMX MD |
sqm/out |
SQM output |
sqm/in |
SQM input |
list |
List format |
3dmol |
3Dmol visualization |
Extended XYZ (extxyz) Format Details
The following format names are all equivalent and invoke the same reader/writer:
extxyz — general-purpose extended XYZquip/gap/xyz / quip/gap/xyz_file — QUIP/GAP framework datasetsmace/xyz — MACE model training datanequip/xyz — NequIP model training datagpumd/xyz — GPUMD simulation data
Important: Plain xyz is a different, simpler format that stores atom species and coordinates but does not provide per-frame properties such as energies, forces, cell information, or periodic boundary conditions. Do not confuse xyz with extxyz.
CLI Examples for extxyz
# Multi-frame extxyz trajectory → deepmd/npy (--multi preserves all frames)
uvx dpdata data.xyz -i extxyz -O deepmd_data -o deepmd/npy --multi
# Heterogeneous extxyz (mixed compositions) → deepmd/npy/mixed
uvx dpdata data.xyz -i extxyz -O deepmd_data -o deepmd/npy/mixed --multi
# Convert extxyz to VASP POSCAR (single-frame input only)
uvx dpdata data.xyz -i extxyz -O POSCAR -o vasp/poscar
# Convert a single-frame extxyz with explicit type map
uvx dpdata data.xyz -i extxyz -O deepmd_data -o deepmd/npy -t H C N O
Tips for extxyz
- Use
-i extxyz explicitly when working with .xyz files that contain extended XYZ data. Using -i xyz retains only atom species and coordinates, omitting per-frame properties such as energies, forces, and cell information.
- Use
--multi for any multi-frame extxyz file. Without --multi, the CLI constructs a LabeledSystem that keeps only the first frame. This applies to all multi-frame trajectories, not just heterogeneous (mixed-composition) files. dpdata groups frames by chemical formula internally.
- All alias names behave identically —
-i mace/xyz, -i nequip/xyz, -i gpumd/xyz, -i quip/gap/xyz, -i quip/gap/xyz_file, and -i extxyz produce the same result.
Tips
- Auto-detection: Use
-i auto (default) to let dpdata detect format automatically
- Type mapping: Use
-t to specify atom type order for deepmd formats
- Multi-system: Use
--multi for directories containing multiple systems
- Compressed output: Use
deepmd/npy or deepmd/hdf5 for smaller file sizes
References
gabrielmoreira