dpdata

1.0.1 verified Fri May 01 auth: no python

A Python library for manipulating data formats of DeePMD-kit, VASP, QE, PWmat, LAMMPS, ABACUS, and other computational chemistry/DFT codes. It provides a unified interface to read, write, convert, and process atomic simulation data including coordinates, forces, energies, and stress tensors. Current version: 1.0.1, with a stable API after the 1.0.0 release. Release cadence: approximately 1-2 months per minor/patch version.

pip install dpdata

Common errors

error ModuleNotFoundError: No module named 'dpdata' ↓

cause dpdata is not installed.

fix

Run: pip install dpdata

error AttributeError: module 'dpdata' has no attribute 'System' ↓

cause Importing dpdata but not using submodule; may have old version or incorrect import.

fix

Use: from dpdata import System

error ValueError: Unknown format: 'outcar' ↓

cause Format string mismatch: dpdata expects 'vasp/outcar' not just 'outcar'.

fix

Use fmt='vasp/outcar' when reading VASP OUTCAR files.

Warnings

gotcha dpdata uses 0-based atomic type indices, while some formats (e.g., LAMMPS) use 1-based. Always check atom_type_map after loading. ↓

fix Access sys.atom_type_map to get mapping from index to species name.

gotcha When converting to deepmd/npy, the 'set_size' during writing can produce multiple subdirectories (set.001, set.002, ...). Ensure consistency in number of frames per set if you intend to use multiple sets for training. ↓

fix Specify set_size in the DeepmdNativeFormat or use to_deepmd_npy(set_size=...) to control splitting.

breaking Python 3.7 support was dropped in v0.2.22. Python 3.8+ is required. ↓

fix Upgrade Python to 3.8 or later.

deprecated The 'label' kwarg in to_deepmd_npy is deprecated in favor of 'set_size'. ↓

fix Use set_size instead of label.

gotcha Writing to LAMMPS data file may lose information if the System contains multiple atom types with different masses; you must manually set mass_map. ↓

fix Before writing, assign sys.data['atom_mass'] = [...] or use sys.set_masses(mass_map).

Imports

System
wrong
```
from dpdata.system import System
```
correct
```
from dpdata import System
```
dpdata previously allowed deep imports, but requires top-level import since v0.2.20

MultiSystems

wrong

from dpdata.multisystems import MultiSystems

correct

from dpdata import MultiSystems

similar to System, top-level import is recommended

Quickstart

Read a VASP OUTCAR file, print number of atoms and first frame energy, convert to ASE Atoms.

from dpdata import System
import numpy as np

sys = System('path/to/OUTCAR', fmt='vasp/outcar')
print('Number of atoms per frame:', sys['atom_numbs'])
print('First frame energies:', sys['energies'][0])
# Convert ASE Atoms back
atoms = sys.to_ase_atoms()
print(atoms)