jinzhezenggroup/computational-chemistry-agent-skills/dpdata-cli

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

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:

• Formats Reference (stable)

DeePMD-kit Formats

VASP Formats

LAMMPS Formats

ABACUS Formats

Quantum ESPRESSO Formats

CP2K Formats

Gaussian Formats

Other Formats

Extended XYZ (extxyz) Format Details

The following format names are all equivalent and invoke the same reader/writer:

• extxyz — general-purpose extended XYZ
• quip/gap/xyz / quip/gap/xyz_file — QUIP/GAP framework datasets
• mace/xyz — MACE model training data
• nequip/xyz — NequIP model training data
• gpumd/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

1. 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.
2. 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.
3. 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

1. Auto-detection: Use -i auto (default) to let dpdata detect format automatically
2. Type mapping: Use -t to specify atom type order for deepmd formats
3. Multi-system: Use --multi for directories containing multiple systems
4. Compressed output: Use deepmd/npy or deepmd/hdf5 for smaller file sizes

References

• dpdata Documentation
• CLI Reference
• Formats Reference
• GitHub Repository