dpdata#
Turn atomistic simulation outputs into interoperable, machine-learning-ready datasets.
Important
One data model, many atomistic formats. Load structures, trajectories, energies, forces, and virials from simulation codes, manipulate them through dpdata.System, dpdata.LabeledSystem, and dpdata.MultiSystems, then export the data in the format your next tool expects.
dpdata connects electronic-structure codes, molecular-dynamics engines, and atomistic machine-learning workflows. Use the command line for one-off conversion, or the Python API to build reproducible data-processing pipelines that preserve atomistic structures and labels.
Choose your path#
Move structures or labeled trajectories between registered formats from the command line.
Load coordinates, cells, energies, forces, virials, and other registered fields into a common Python data model.
Organize data with different compositions or atom counts using MultiSystems.
Store frames from one or more systems in a single DeePMD-compatible LMDB database.
Find the registered readers and writers for electronic structure, molecular dynamics, atomistic ML, chemistry, and analysis tools.
Open an interactive browser session without installing dpdata locally.
Why dpdata#
Read and write atomistic formats through the same System and LabeledSystem interfaces instead of maintaining one converter per code pair.
Keep structures together with energies, forces, virials, and registered extra fields while converting or selecting frames.
Work with multiple compositions and atom counts as a collection rather than forcing every frame into one homogeneous system.
Export DeePMD NumPy data or use LMDB when a single database is a better fit for heterogeneous atomistic data.
Select frames, build supercells, perturb structures, replace species, and compose transformations in Python.
Add new formats as installable Python packages through the dpdata.plugins entry point.
From calculation output to training data#
A typical dpdata workflow has four steps:
Load structures or labeled trajectories from a supported simulation format.
Manipulate frames, structures, species, or dataset partitions in Python.
Organize homogeneous data in
System/LabeledSystemor heterogeneous data inMultiSystems.Export to the format expected by the next simulation, analysis, or machine-learning tool.
The same registry powers both the command-line interface and Python API, so a one-line conversion can grow into a larger data pipeline without changing the underlying format model.
Start in minutes#
dpdata requires Python 3.10 or later. The fastest installation path is:
python -m pip install dpdata
dpdata --version
Conda-forge and source installation are covered in the installation guide.
Convert from the command line#
Convert a VASP OUTCAR directly to a DeePMD NumPy dataset:
dpdata OUTCAR -i vasp/outcar -o deepmd/npy -O deepmd_data
See the full command-line reference for input and output options.
Build a labeled dataset in Python#
import dpdata
# OUTCAR is recognized as a labeled VASP trajectory.
data = dpdata.LabeledSystem("OUTCAR")
# Keep selected frames and write a DeePMD NumPy dataset.
data.sub_system([0, -1]).to("deepmd/npy", "deepmd_data")
dpdata.LabeledSystem keeps structures together with energies, forces, and virials when they are available. Continue with System and LabeledSystem for data access, frame selection, replication, perturbation, and species replacement.
Combine many systems and scale out#
import dpdata
systems = dpdata.MultiSystems.from_dir(
"./calculations",
file_name="OUTCAR",
fmt="vasp/outcar",
)
systems.to("deepmd/lmdb", "training.lmdb")
MultiSystems groups heterogeneous structures by composition, while deepmd/lmdb stores frames from one or more systems in a single database. See MultiSystems and LMDB datasets.
Core data model#
Object | Use it for |
|---|---|
Structures and trajectories: atom types, coordinates, cells, and other non-label fields. | |
Reference data for atomistic ML: a | |
Collections containing multiple systems, compositions, or atom counts. |
Specialized representations, including bond-order and mixed-type systems, are available in the Systems guide.
Scientific ecosystem#
dpdata is designed to sit between the tools already used in computational chemistry and materials science.
Area | Representative built-in integrations |
|---|---|
Electronic structure and quantum chemistry | VASP, ABACUS, Quantum ESPRESSO, Gaussian, CP2K, ORCA, FHI-aims, SIESTA, OpenMX, and DFTB+ |
Molecular dynamics | LAMMPS and GROMACS |
Atomistic ML and data | DeePMD-kit formats, LMDB datasets, ASE, and pymatgen-compatible structures |
Chemistry and visualization | RDKit and 3Dmol.js |
The supported-formats table is generated from dpdata’s format registry and is the source of truth for available readers and writers.
Documentation map#
Get started: Installation · Try dpdata online · Command line.
Work with data: Systems · Supported formats · Drivers · Minimizers.
Extend dpdata: Plugin guide · Python API.
Citation#
If dpdata contributes to published work, please cite:
Jinzhe Zeng, Xingliang Peng, Yong-Bin Zhuang, Haidi Wang, Fengbo Yuan, Duo Zhang, Renxi Liu, Yingze Wang, Ping Tuo, Yuzhi Zhang, Yixiao Chen, Yifan Li, Cao Thang Nguyen, Jiameng Huang, Anyang Peng, Marián Rynik, Wei-Hong Xu, Zezhong Zhang, Xu-Yuan Zhou, Tao Chen, Jiahao Fan, Wanrun Jiang, Bowen Li, Denan Li, Haoxi Li, Wenshuo Liang, Ruihao Liao, Liping Liu, Chenxing Luo, Logan Ward, Kaiwei Wan, Junjie Wang, Pan Xiang, Chengqian Zhang, Jinchao Zhang, Rui Zhou, Jia-Xin Zhu, Linfeng Zhang, and Han Wang. “dpdata: A Scalable Python Toolkit for Atomistic Machine Learning Data Sets.” Journal of Chemical Information and Modeling 65 (21), 11497–11504 (2025). DOI: 10.1021/acs.jcim.5c01767.