dpdata-cli · v1.0 · 2026-08-19 · sha256 3f845813722dac51
dpdata-cli v1.0A
Immutable. This exact content is served forever at /api/v1/blob/3f845813722dac51.
---
name: dpdata-cli
description: Convert and manipulate atomic simulation data formats using dpdata CLI. Use when converting between DFT/MD output formats or preparing DeePMD-kit training data. Supports 50+ formats including deepmd, xyz or extxyz, ABACUS, VASP, LAMMPS, CP2K, etc.
compatibility: Requires uvx (uv) for running dpdata
metadata:
author: njzjz-bot
version: '1.0'
repository: https://github.com/deepmodeling/dpdata
---
# 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:
```bash
uvx dpdata <from_file> [options]
```
## Command Line Usage
```text
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
```bash
uvx dpdata OUTCAR -i vasp/outcar -O deepmd_data -o deepmd/raw
```
### Convert LAMMPS dump to VASP POSCAR
```bash
uvx dpdata dump.lammps -i lammps/dump -O POSCAR -o vasp/poscar
```
### Convert with type map
```bash
uvx dpdata OUTCAR -i vasp/outcar -O deepmd_data -o deepmd/raw -t C H O N
```
### Convert multiple systems
```bash
uvx dpdata data_dir -i vasp/outcar -O output_dir -o deepmd/comp --multi
```
### Convert to deepmd/npy (compressed format)
```bash
uvx dpdata OUTCAR -i vasp/outcar -O deepmd_npy -o deepmd/npy
```
### Convert to deepmd/hdf5
```bash
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)](https://docs.deepmodeling.com/projects/dpdata/en/stable/formats.html)
### 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 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
```bash
# 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.
1. **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.
1. **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
1. **Type mapping**: Use `-t` to specify atom type order for deepmd formats
1. **Multi-system**: Use `--multi` for directories containing multiple systems
1. **Compressed output**: Use `deepmd/npy` or `deepmd/hdf5` for smaller file sizes
## References
- [dpdata Documentation](https://docs.deepmodeling.com/projects/dpdata/)
- [CLI Reference](https://docs.deepmodeling.com/projects/dpdata/en/stable/cli.html)
- [Formats Reference](https://docs.deepmodeling.com/projects/dpdata/en/stable/formats.html)
- [GitHub Repository](https://github.com/deepmodeling/dpdata)