dpdata.plugins package

Submodules

dpdata.plugins.3dmol module

class dpdata.plugins.3dmol.Py3DMolFormat

Bases: Format

Interactive py3Dmol visualization for one System frame.

py3Dmol is a Jupyter/Python wrapper for 3Dmol.js for interactive 3D molecular visualization.

This write-only in-memory adapter returns a configured py3Dmol viewer for use in Jupyter notebooks. It does not serialize a data format. The optional py3Dmol dependency is required.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data[, f_idx, size, style])	Show 3D structure of a frame in jupyter.

to_system(data: dict, f_idx: int = 0, size: tuple[int] = (300, 300), style: dict = {'sphere': {'radius': 0.4}, 'stick': {}}, **kwargs)

Show 3D structure of a frame in jupyter.

Parameters:

datadict

system data

f_idxint

frame index to show

sizetuple[int]

(width, height) of the widget

styledict

style of 3DMol. Read 3DMol documentation for details.

**kwargsdict

other parameters

Examples

>>> system.to_3dmol()

dpdata.plugins.abacus module

class dpdata.plugins.abacus.AbacusMDFormat

Bases: Format

ABACUS molecular-dynamics calculation directory.

ABACUS is an open-source DFT package. This format reads the trajectory and labels emitted by an ABACUS MD run, including optional force, virial, movement, and magnetic data.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Load frames from an ABACUS MD calculation.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name, **kwargs)

Load frames from an ABACUS MD calculation.

Parameters:

file_namestr or os.PathLike

Calculation directory containing INPUT, STRU, and OUT.<suffix> MD output files.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Labeled trajectory data.

class dpdata.plugins.abacus.AbacusRelaxFormat

Bases: Format

ABACUS ionic- or cell-relaxation calculation directory.

ABACUS is an open-source DFT package. The reader reconstructs relaxation frames from the ABACUS log and saved STRU_ION*_D structures and attaches the available energies, forces, virials, movement flags, and magnetic data.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Load an ABACUS relaxation trajectory.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name, **kwargs)

Load an ABACUS relaxation trajectory.

Parameters:

file_namestr or os.PathLike

Calculation directory containing the ABACUS input and relaxation output files.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Labeled relaxation frames.

class dpdata.plugins.abacus.AbacusSCFFormat

Bases: Format

ABACUS self-consistent-field calculation directory.

ABACUS is an open-source DFT package. The reader combines the calculation’s INPUT and STRU files with the corresponding OUT.<suffix>/running_scf.log output and returns the final labeled configuration.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Load an ABACUS SCF calculation.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name, **kwargs)

Load an ABACUS SCF calculation.

Parameters:

file_namestr or os.PathLike

Calculation directory containing INPUT, STRU, and the ABACUS output directory.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Labeled system data with energy and any available forces, virial, movement flags, or magnetic fields.

class dpdata.plugins.abacus.AbacusSTRUFormat

Bases: Format

ABACUS structure file.

ABACUS (Atomic-orbital Based Ab-initio Computation at UStc) is an open-source DFT package based on LCAO and plane-wave basis sets.

STRU stores the cell, species, coordinates, pseudopotential/orbital references, and optional movement or magnetic-moment fields for one ABACUS configuration. This format reads and writes unlabeled dpdata.System objects.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Load one ABACUS STRU file.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, file_name[, frame_idx])	Dump the system into ABACUS STRU format file.

from_system(file_name, **kwargs)

Load one ABACUS STRU file.

Parameters:

file_namestr or os.PathLike

Input STRU file.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

System data, including optional move and magnetic fields when present in the file.

to_system(data, file_name: FileType, frame_idx=0, **kwargs)

Dump the system into ABACUS STRU format file.

Parameters:

datadict

System data

file_namestr

The output file name

frame_idxint

The index of the frame to dump

**kwargsdict

Additional STRU fields described below.

Other Parameters:

pp_filelist[str] or dict[str, str], optional

Pseudopotential file for each atom type.

numerical_orbitallist[str] or dict[str, str], optional

Numerical orbital file for each atom type.

numerical_descriptorstr, optional

Numerical descriptor file used by ABACUS.

masslist[float], optional

Atomic mass for each atom type.

movearray-like, optional

Per-frame, per-atom Cartesian movement flags.

velocityarray-like, optional

Initial Cartesian velocity for each atom.

magarray-like, optional

Scalar or vector magnetic moment for each atom.

angle1, angle2array-like, optional

Polar and azimuthal magnetic-moment angles for noncollinear spins.

scarray-like, optional

Spin-constraint flags.

lambda_array-like, optional

Spin-constraint lambda values.

link_filebool, default=False

Write basenames and create symbolic links for referenced files.

dpdata.plugins.abacus.register_mag_data(data)

dpdata.plugins.abacus.register_move_data(data)

dpdata.plugins.amber module

class dpdata.plugins.amber.AmberMDFormat

Bases: Format

AMBER molecular-dynamics trajectory and label files.

AMBER is a suite of biomolecular simulation programs for molecular dynamics simulations and analysis.

Coordinates and topology are read from .nc and .parm7 files. Labeled loading additionally requires the .mdfrc force trajectory and takes energies from either the .mden or the .mdout file. The parmed optional dependency is required.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system([file_name, parm7_file, ...])	Load a labeled AMBER trajectory.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system([file_name, parm7_file, ...])	Load an unlabeled AMBER trajectory.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name=None, parm7_file=None, nc_file=None, mdfrc_file=None, mden_file=None, mdout_file=None, use_element_symbols=None, **kwargs)

Load a labeled AMBER trajectory.

Parameters:

file_namestr, optional

Common prefix used to infer the AMBER file names.

parm7_filestr, optional

Explicit AMBER topology file.

nc_filestr, optional

Explicit NetCDF coordinate trajectory.

mdfrc_filestr, optional

Explicit force trajectory. Required for labeled loading; inferred from file_name when not given.

mden_filestr, optional

Explicit energy file. Used when present, otherwise mdout_file supplies the energies.

mdout_filestr, optional

Explicit AMBER text output. Fallback energy source when mden_file is absent.

use_element_symbolslist[int] or str, optional

Atoms whose element symbols are used instead of AMBER atom types, given either as a list of atom indexes or as an AMBER mask string selecting them.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Labeled trajectory data assembled from the supplied files.

from_system(file_name=None, parm7_file=None, nc_file=None, use_element_symbols=None, **kwargs)

Load an unlabeled AMBER trajectory.

Parameters:

file_namestr, optional

Common prefix used to infer <prefix>.parm7 and <prefix>.nc.

parm7_filestr, optional

Explicit AMBER topology file. Overrides the inferred path.

nc_filestr, optional

Explicit NetCDF trajectory file. Overrides the inferred path.

use_element_symbolslist[int] or str, optional

Atoms whose element symbols are used instead of AMBER atom types, given either as a list of atom indexes or as an AMBER mask string selecting them.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Unlabeled trajectory data.

class dpdata.plugins.amber.SQMDriver(sqm_exec: str = 'sqm', **kwargs)

Bases: Driver

AMBER sqm program driver.

Parameters:

sqm_execstr, default=sqm

path to sqm program

**kwargsdict

other arguments to make input files. See SQMINFormat

Attributes:

ase_calculator

Returns an ase calculator based on this driver.

Methods

get_driver(key)	Get a driver plugin.
get_drivers()	Get all driver plugins.
label(data)	Label a system data.
register(key)	Register a driver plugin.

Examples

Use DFTB3 method to calculate potential energy:

>>> labeled_system = system.predict(theory="DFTB3", driver="sqm")
>>> labeled_system['energies'][0]
-15.41111246

label(data: dict) → dict

Label a system data. Returns new data with energy, forces, and virials.

Parameters:

datadict

data with coordinates and atom types

Returns:

dict

labeled data with energies and forces

class dpdata.plugins.amber.SQMINFormat

Bases: Format

AmberTools SQM input for semiempirical calculations.

AmberTools provides the SQM module for semiempirical QM calculations.

This write-only format serializes one nonperiodic System frame with its charge, multiplicity, semiempirical method, and minimization-cycle limit. Setting maxcyc=0 requests a single-point calculation; positive values request geometry minimization.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data[, fname, frame_idx])	Generate input files for semi-emperical calculation in sqm software.

to_system(data, fname=None, frame_idx=0, **kwargs)

Generate input files for semi-emperical calculation in sqm software.

Parameters:

datadict

system data

fnamestr

output file name

frame_idxint, default=0

index of frame to write

**kwargsdict

other parameters

Other Parameters:

**kwargsdict

valid parameters are:

qm_theorystr, default=dftb3

level of theory. Options includes AM1, RM1, MNDO, PM3-PDDG, MNDO-PDDG, PM3-CARB1, MNDO/d, AM1/d, PM6, DFTB2, DFTB3

chargeint, default=0

total charge in electron units

maxcycint, default=0

maximum number of minimization cycles to allow. 0 represents a single-point calculation

multint, default=1

multiplicity. Only 1 is allowed.

class dpdata.plugins.amber.SQMMinimizer(maxcyc=1000, *args, **kwargs)

Bases: Minimizer

SQM minimizer.

Parameters:

maxcycint, default=1000

maximun cycle to minimize

Methods

get_minimizer(key)	Get a minimizer plugin.
get_minimizers()	Get all minimizer plugins.
minimize(data)	Minimize the geometry.
register(key)	Register a minimizer plugin.

minimize(data: dict) → dict

Minimize the geometry.

Parameters:

datadict

data with coordinates and atom types

Returns:

dict

labeled data with minimized coordinates, energies, and forces

class dpdata.plugins.amber.SQMOutFormat

Bases: Format

AmberTools SQM output from a semiempirical calculation.

AmberTools is a collection of complementary tools for AMBER simulations. SQM implements semiempirical quantum-mechanical methods.

The same file can be loaded as an unlabeled system, or as a labeled system when the output contains gradients that can be converted to forces.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(fname, **kwargs)	Read coordinates, energy, and forces from sqm.out.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(fname, **kwargs)	Read coordinates from an AmberTools sqm.out file.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(fname, **kwargs)

Read coordinates, energy, and forces from sqm.out.

Parameters:

fnamestr or os.PathLike

SQM output file containing gradients.

**kwargsdict

Additional format arguments accepted for API compatibility.

from_system(fname, **kwargs)

Read coordinates from an AmberTools sqm.out file.

Parameters:

fnamestr or os.PathLike

SQM output file.

**kwargsdict

Additional format arguments accepted for API compatibility.

dpdata.plugins.ase module

class dpdata.plugins.ase.ASEDriver(calculator: ase.calculators.calculator.Calculator)

Bases: Driver

ASE Driver.

Parameters:

calculatorase.calculators.calculator.Calculato

ASE calculator

Attributes:

ase_calculator

Returns an ase calculator based on this driver.

Methods

get_driver(key)	Get a driver plugin.
get_drivers()	Get all driver plugins.
label(data)	Label a system data.
register(key)	Register a driver plugin.

label(data: dict) → dict

Label a system data. Returns new data with energy, forces, and virials.

Parameters:

datadict

data with coordinates and atom types

Returns:

dict

labeled data with energies and forces

class dpdata.plugins.ase.ASEMinimizer(driver: Driver, optimizer: type[Optimizer] | None = None, fmax: float = 0.005, max_steps: int | None = None, optimizer_kwargs: dict = {})

Bases: Minimizer

ASE minimizer.

Parameters:

driverDriver

dpdata driver

optimizertype, optional

ase optimizer class

fmaxfloat, optional, default=5e-3

force convergence criterion

max_stepsint, optional

max steps to optimize

optimizer_kwargsdict, optional

other parameters for optimizer

Methods

get_minimizer(key)	Get a minimizer plugin.
get_minimizers()	Get all minimizer plugins.
minimize(data)	Minimize the geometry.
register(key)	Register a minimizer plugin.

minimize(data: dict) → dict

Minimize the geometry.

Parameters:

datadict

data with coordinates and atom types

Returns:

dict

labeled data with minimized coordinates, energies, and forces

class dpdata.plugins.ase.ASEStructureFormat

Bases: Format

In-memory Atomic Simulation Environment (ASE) Atoms objects.

This adapter converts between dpdata systems and ASE objects without writing a file. It can also use ASE’s I/O support to load multi-frame files; pass ase_fmt when ASE cannot infer the underlying file format. Labeled conversion reads or attaches an ASE calculator’s energy, forces, and stress. The optional ase dependency is required.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(atoms, **kwargs)	Convert ASE Atoms to a LabeledSystem.
from_multi_systems(file_name[, begin, end, ...])	Convert a ASE supported file to ASE Atoms.
from_system(atoms, **kwargs)	Convert ase.Atoms to a System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Convert labeled frames to ASE objects with single-point calculators.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, **kwargs)	Convert every System frame to an ASE Atoms object.

from_labeled_system(atoms: ase.Atoms, **kwargs) → dict

Convert ASE Atoms to a LabeledSystem.

Energies and forces are calculated by the attached calculator.

Note that this method will try to load virials from either virial field or converted from stress tensor.

Parameters:

atomsase.Atoms

an ASE Atoms, containing a structure

**kwargsdict

other parameters

Returns:

dict

data dict

Raises:

RuntimeError

ASE will raise RuntimeError if the atoms does not have a calculator

from_multi_systems(file_name: str, begin: int | None = None, end: int | None = None, step: int | None = None, ase_fmt: str | None = None, **kwargs) → Generator[ase.Atoms, None, None]

Convert a ASE supported file to ASE Atoms.

It will finally be converted to MultiSystems.

Parameters:

file_namestr

path to file

beginint, optional

begin frame index

endint, optional

end frame index

stepint, optional

frame index step

ase_fmtstr, optional

ASE format. See the ASE documentation about supported formats

**kwargsdict

other parameters

Yields:

ase.Atoms

ASE atoms in the file

from_system(atoms: ase.Atoms, **kwargs) → dict

Convert ase.Atoms to a System.

Parameters:

atomsase.Atoms

an ASE Atoms, containing a structure

**kwargsdict

other parameters

Returns:

dict

data dict

to_labeled_system(data, *args, **kwargs) → list[ase.Atoms]

Convert labeled frames to ASE objects with single-point calculators.

Parameters:

datadict

LabeledSystem data containing energies and optional forces or virials.

*argslist

Additional positional arguments accepted for API compatibility.

**kwargsdict

Additional keyword arguments accepted for API compatibility.

Returns:

list[ase.Atoms]

One ASE object per frame with labels stored in a SinglePointCalculator.

to_system(data, **kwargs) → list[ase.Atoms]

Convert every System frame to an ASE Atoms object.

Parameters:

datadict

System data to convert.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

list[ase.Atoms]

One ASE object per frame.

class dpdata.plugins.ase.ASETrajFormat

Bases: Format

ASE binary trajectory (.traj) file.

An ASE trajectory stores a sequence of Atoms objects and can retain calculator results. dpdata supports frame slicing on read and writes all frames to a new trajectory. The optional ase dependency is required.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name[, begin, end, ...])	Read ASE's trajectory file to System of multiple frames.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name[, begin, end, step])	Read ASE's trajectory file to System of multiple frames.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data[, file_name])	Write labeled frames to an ASE trajectory.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data[, file_name])	Write System frames to an ASE trajectory.

from_labeled_system(file_name: str, begin: int | None = 0, end: int | None = None, step: int | None = 1, **kwargs) → dict

Read ASE’s trajectory file to System of multiple frames.

Parameters:

file_namestr

ASE’s trajectory file

beginint, optional

begin frame index

endint, optional

end frame index

stepint, optional

frame index step

**kwargsdict

other parameters

Returns:

dict_frames: dict

a dictionary containing data of multiple frames

from_system(file_name: str, begin: int | None = 0, end: int | None = None, step: int | None = 1, **kwargs) → dict

Read ASE’s trajectory file to System of multiple frames.

Parameters:

file_namestr

ASE’s trajectory file

beginint, optional

begin frame index

endint, optional

end frame index

stepint, optional

frame index step

**kwargsdict

other parameters

Returns:

dict_frames: dict

a dictionary containing data of multiple frames

to_labeled_system(data, file_name: str = 'labeled_confs.traj', *args, **kwargs) → None

Write labeled frames to an ASE trajectory.

Parameters:

datadict

LabeledSystem data to write.

file_namestr

Destination trajectory path.

*argslist

Positional options forwarded to the in-memory ASE converter.

**kwargsdict

Keyword options forwarded to the in-memory ASE converter.

to_system(data, file_name: str = 'confs.traj', **kwargs) → None

Write System frames to an ASE trajectory.

Parameters:

datadict

System data to write.

file_namestr

Destination trajectory path.

**kwargsdict

Options forwarded to the in-memory ASE structure converter.

dpdata.plugins.cp2k module

class dpdata.plugins.cp2k.CP2KAIMDOutputFormat

Bases: Format

CP2K AIMD calculation directory.

CP2K is a quantum chemistry and solid state physics software package that can perform atomistic simulations.

The reader pairs the first *pos*.xyz trajectory with the first CP2K .log file in the directory and extracts coordinates, cells, energies, forces, and virials where available.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name[, restart])	Load a labeled CP2K AIMD trajectory.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name, restart=False, **kwargs)

Load a labeled CP2K AIMD trajectory.

Parameters:

file_namestr or os.PathLike

Directory containing CP2K position and log files.

restartbool, default=False

Whether the trajectory is from a restarted CP2K calculation.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

tuple[dict, …]

One or more labeled system-data dictionaries parsed from the run.

class dpdata.plugins.cp2k.CP2KOutputFormat

Bases: Format

Single CP2K output file containing coordinates and calculation labels.

CP2K is a quantum chemistry and solid state physics software package. This legacy reader targets standard CP2K text output. For newer or unsupported CP2K layouts, use the separately maintained cp2kdata plugin referenced by the warning raised on parse failure.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name[, restart])	Load frames from a CP2K text output.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name, restart=False, **kwargs)

Load frames from a CP2K text output.

Parameters:

file_namestr or os.PathLike

CP2K output file.

restartbool, default=False

Reserved for compatibility with the AIMD reader.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Labeled system data.

dpdata.plugins.deepmd module

class dpdata.plugins.deepmd.DPDriver(dp: str)

Bases: Driver

DeePMD-kit driver.

Parameters:

dpdeepmd.DeepPot or str

The deepmd-kit potential class or the filename of the model.

Attributes:

ase_calculator

Returns an ase calculator based on this driver.

Methods

get_driver(key)	Get a driver plugin.
get_drivers()	Get all driver plugins.
label(data)	Label a system data by deepmd-kit.
register(key)	Register a driver plugin.

Examples

>>> DPDriver("frozen_model.pb")

label(data: dict) → dict

Label a system data by deepmd-kit. Returns new data with energy, forces, and virials.

Parameters:

datadict

data with coordinates and atom types

Returns:

dict

labeled data with energies and forces

class dpdata.plugins.deepmd.DeePMDCompFormat

Bases: Format

DeePMD-kit NumPy dataset directory.

DeePMD-kit is a deep learning package for training interatomic potentials. Commonly called deepmd/npy, this layout keeps type metadata as raw files and splits frame arrays among set.000, set.001, … directories containing .npy files. It is the standard efficient on-disk format for DeePMD-kit training data.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name[, type_map])	Load a labeled DeePMD NumPy dataset.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name[, type_map])	Load an unlabeled DeePMD NumPy dataset.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, file_name[, set_size, prec])	Dump the system in deepmd compressed format (numpy binary) to folder.

MultiMode = 1

from_labeled_system(file_name, type_map=None, **kwargs)

Load a labeled DeePMD NumPy dataset.

Parameters:

file_namestr or os.PathLike

DeePMD NumPy dataset directory.

type_maplist[str], optional

Element names or requested type ordering used while loading.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Labeled system data with all available registered fields.

from_system(file_name, type_map=None, **kwargs)

Load an unlabeled DeePMD NumPy dataset.

Parameters:

file_namestr or os.PathLike

DeePMD NumPy dataset directory.

type_maplist[str], optional

Element names or requested type ordering used while loading.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Unlabeled system data.

to_system(data, file_name, set_size=5000, prec=<class 'numpy.float64'>, **kwargs)

Dump the system in deepmd compressed format (numpy binary) to folder.

The frames are firstly split to sets, then dumped to seperated subfolders named as folder/set.000, folder/set.001, ….

Each set contains set_size frames. The last set may have less frames than set_size.

Parameters:

datadict

System data

file_namestr

The output folder

set_sizeint

The size of each set.

prec{numpy.float32, numpy.float64}

The floating point precision of the compressed data

**kwargsdict

other parameters

class dpdata.plugins.deepmd.DeePMDHDF5Format

Bases: Format

HDF5 format for DeePMD-kit.

DeePMD-kit is a deep learning package for training interatomic potentials. The layout stores the same type metadata and frame arrays as deepmd/npy inside one HDF5 file. It supports unlabeled and labeled systems, and top-level groups can hold multiple formulas for dpdata.MultiSystems. Inputs may be file paths, open HDF5 objects, or strings such as "data.hdf5#group/path" that select a nested group.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name[, type_map])	Convert HDF5 file to LabeledSystem data.
from_multi_systems(directory, **kwargs)	Generate HDF5 groups from a HDF5 file.
from_system(file_name[, type_map])	Convert HDF5 file to System data.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Generate HDF5 groups, which will be passed to to_system.
to_system(data, file_name, set_size, ...)	Convert System data to HDF5 file.

Examples

Dump a MultiSystems to a HDF5 file:

>>> import dpdata
>>> dpdata.MultiSystems().from_deepmd_npy("data").to_deepmd_hdf5("data.hdf5")

from_labeled_system(file_name: str | h5py.Group | h5py.File, type_map: list[str] | None = None, **kwargs) → dict

Convert HDF5 file to LabeledSystem data.

Parameters:

file_namestr or h5py.Group or h5py.File

file name of the HDF5 file or HDF5 object. If it is a string, hashtag is used to split path to the HDF5 file and the HDF5 group

type_maplist[str], optional

Element names used to map stored atom-type indices.

**kwargsdict

other parameters

Returns:

dict

LabeledSystem data

Raises:

TypeError

file_name is not str or h5py.Group or h5py.File

from_multi_systems(directory: str, **kwargs) → h5py.Group

Generate HDF5 groups from a HDF5 file.

Each group is passed to from_labeled_system(), or to from_system() when the caller loads with labeled=False.

Parameters:

directorystr

HDF5 file name

**kwargsdict

other parameters

Yields:

h5py.Group

a HDF5 group in the HDF5 file

from_system(file_name: str | h5py.Group | h5py.File, type_map: list[str] | None = None, **kwargs) → dict

Convert HDF5 file to System data.

Parameters:

file_namestr or h5py.Group or h5py.File

file name of the HDF5 file or HDF5 object. If it is a string, hashtag is used to split path to the HDF5 file and the HDF5 group

type_maplist[str], optional

Element names used to map stored atom-type indices.

**kwargsdict

other parameters

Returns:

dict

System data

Raises:

TypeError

file_name is not str or h5py.Group or h5py.File

to_multi_systems(formulas: list[str], directory: str, **kwargs) → h5py.Group

Generate HDF5 groups, which will be passed to to_system.

Parameters:

formulaslist[str]

formulas of MultiSystems

directorystr

HDF5 file name

**kwargsdict

other parameters

Yields:

h5py.Group

a HDF5 group with the name of formula

to_system(data: dict, file_name: str | h5py.Group | h5py.File, set_size: int = 5000, comp_prec: np.dtype = <class 'numpy.float64'>, **kwargs)

Convert System data to HDF5 file.

Parameters:

datadict

data dict

file_namestr or h5py.Group or h5py.File

file name of the HDF5 file or HDF5 object. If it is a string, hashtag is used to split path to the HDF5 file and the HDF5 group

set_sizeint, default=5000

set size

comp_precnp.dtype

data precision

**kwargsdict

other parameters

class dpdata.plugins.deepmd.DeePMDHDF5MixedFormat

Bases: DeePMDMixedFormat

Mixed type HDF5 format for DeePMD-kit.

DeePMD-kit is a deep learning package for training interatomic potentials.

Mixed type data stores frames with the same atom count in one dataset even when their formulas differ. The placeholder type.raw contains only the mixed token type, while set.*/real_atom_types.npy stores the real atom type layout for each frame. Loading reconstructs regular Systems by splitting frames with different real_atom_types rows.

The HDF5 layout mirrors deepmd/npy/mixed inside HDF5 groups. For dpdata.MultiSystems, each top-level mixed group is keyed by the number of atoms after optional padding, such as "4" or "8". A string path may include "#group/path" to read or write mixed data under a nested HDF5 group.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_labeled_system_mix(file_name[, type_map])	Load labeled mixed HDF5 data and split it into LabeledSystems.
from_multi_systems(directory, **kwargs)	Generate mixed HDF5 groups for MultiSystems loading.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
from_system_mix(file_name[, type_map])	Load unlabeled mixed HDF5 data and split it into Systems.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map[, atom_numb_pad])	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Generate HDF5 groups for MultiSystems mixed dumping.
to_system(data, file_name, set_size[, prec, ...])	Dump a System data dict in mixed HDF5 format.

Examples

Dump a dpdata.MultiSystems object to a mixed HDF5 file:

>>> systems.to_deepmd_hdf5_mixed("mixed.hdf5")

Dump with atom-count padding:

>>> systems.to_deepmd_hdf5_mixed("mixed.hdf5", atom_numb_pad=8)

Load a mixed HDF5 file into dpdata.MultiSystems:

>>> dpdata.MultiSystems().from_deepmd_hdf5_mixed("mixed.hdf5")

from_labeled_system_mix(file_name, type_map=None, **kwargs)

Load labeled mixed HDF5 data and split it into LabeledSystems.

Parameters:

file_namestr or h5py.Group or h5py.File

HDF5 file, HDF5 group, or string in "file.hdf5#group" form.

type_maplist[str], optional

Type map used to remap real atom types while loading.

**kwargsdict

Additional keyword arguments accepted for format API compatibility.

Returns:

list[dict]

LabeledSystem data dicts reconstructed from the mixed data.

from_multi_systems(directory, **kwargs)

Generate mixed HDF5 groups for MultiSystems loading.

Parameters:

directorystr or h5py.Group or h5py.File

HDF5 file, HDF5 group, or string in "file.hdf5#group" form. The selected object may be either one mixed system group or a container of mixed groups.

**kwargsdict

Additional keyword arguments accepted for format API compatibility.

Yields:

h5py.Group or h5py.File

Mixed HDF5 groups that will be passed to from_system_mix.

Raises:

TypeError

If directory is not a string, HDF5 group, or HDF5 file.

from_system_mix(file_name, type_map=None, **kwargs)

Load unlabeled mixed HDF5 data and split it into Systems.

Parameters:

file_namestr or h5py.Group or h5py.File

HDF5 file, HDF5 group, or string in "file.hdf5#group" form.

type_maplist[str], optional

Type map used to remap real atom types while loading.

**kwargsdict

Additional keyword arguments accepted for format API compatibility.

Returns:

list[dict]

Unlabeled System data dicts reconstructed from the mixed data.

to_multi_systems(formulas, directory, **kwargs)

Generate HDF5 groups for MultiSystems mixed dumping.

Parameters:

formulaslist[str]

Mixed group names produced by mix_system. For mixed HDF5 these names are atom counts after optional padding.

directorystr or h5py.Group or h5py.File

HDF5 file, HDF5 group, or string in "file.hdf5#group" form. Strings open the target file in write mode.

**kwargsdict

Additional keyword arguments accepted for format API compatibility.

Yields:

h5py.Group

Destination groups that will be passed to to_system.

Raises:

TypeError

If directory is not a string, HDF5 group, or HDF5 file.

to_system(data, file_name, set_size: int = 2000, prec=<class 'numpy.float64'>, comp_prec=None, **kwargs)

Dump a System data dict in mixed HDF5 format.

Parameters:

datadict

System or LabeledSystem data dict. If it is not already in mixed type form, it is copied and converted before dumping.

file_namestr or h5py.Group or h5py.File

HDF5 file, HDF5 group, or string in "file.hdf5#group" form. Strings open the target file in write mode. HDF5 objects are written in place.

set_sizeint, default=2000

Maximum number of frames per set.* group.

precnumpy.dtype, default=numpy.float64

Floating point precision for dumped frame data. Kept for consistency with deepmd/npy/mixed.

comp_precnumpy.dtype, optional

Explicit floating point precision. When provided, this overrides prec.

**kwargsdict

Additional keyword arguments accepted for format API compatibility.

Raises:

TypeError

If file_name is not a string, HDF5 group, or HDF5 file.

class dpdata.plugins.deepmd.DeePMDMixedFormat

Bases: Format

Mixed-type NumPy dataset for DeePMD-kit.

DeePMD-kit is a deep learning package for training interatomic potentials. Unlike regular deepmd/npy, this layout can combine frames that have the same atom count but different formulas. Per-frame real atom types keep each composition recoverable for models that use type embeddings. Optional atom-count padding can reduce the number of output groups when a dpdata.MultiSystems contains many system sizes.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_multi_systems(directory, **kwargs)	Find mixed-type DeePMD NumPy systems below a directory.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map[, atom_numb_pad])	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, file_name, set_size[, prec])	Dump the system in deepmd mixed type format (numpy binary) to folder.

from_labeled_system_mix
from_system_mix

Examples

Dump a MultiSystems into a mixed type numpy directory:

>>> import dpdata
>>> dpdata.MultiSystems(*systems).to_deepmd_npy_mixed("mixed_dir")

Dump with atom_numb_pad to reduce the number of subdirectories. Systems are padded with virtual atoms (type -1) so that atom counts are rounded up to the nearest multiple of the given number:

>>> dpdata.MultiSystems(*systems).to_deepmd_npy_mixed("mixed_dir", atom_numb_pad=8)

Load a mixed type data into a MultiSystems:

>>> import dpdata
>>> dpdata.MultiSystems().load_systems_from_file("mixed_dir", fmt="deepmd/npy/mixed")

MultiMode = 1

from_labeled_system_mix(file_name, type_map=None, **kwargs)

from_multi_systems(directory, **kwargs)

Find mixed-type DeePMD NumPy systems below a directory.

Parameters:

directorystr or os.PathLike

Root directory containing one or more mixed datasets.

**kwargsdict

Additional format arguments forwarded when each dataset is read.

Returns:

list[str]

Directories containing type_map.raw and mixed-type data.

from_system_mix(file_name, type_map=None, **kwargs)

mix_system(*system, type_map, atom_numb_pad=None, **kwargs)

Mix the systems into mixed_type ones according to the unified given type_map.

Parameters:

*systemSystem

The systems to mix

type_maplist of str

Maps atom type to name

atom_numb_padint, optional

If provided, pad atom counts to the next multiple of this number using virtual atoms (type -1 in real_atom_types). This reduces the number of subdirectories when systems have many different atom counts. For example, atom_numb_pad=8 groups systems into multiples of 8: a 5-atom system is padded to 8, a 9-atom system is padded to 16, etc. Virtual atoms are transparently removed when loading the data back.

**kwargsdict

other parameters

Returns:

mixed_systems: dict

dict of mixed system with key ‘atom_numbs’

Examples

Dump with padding so that atom counts are rounded up to multiples of 8:

>>> import dpdata
>>> dpdata.MultiSystems(*systems).to_deepmd_npy_mixed("mixed_dir", atom_numb_pad=8)

to_system(data, file_name, set_size: int = 2000, prec=<class 'numpy.float64'>, **kwargs)

Dump the system in deepmd mixed type format (numpy binary) to folder.

The frames were already split to different systems, so these frames can be dumped to one single subfolders

named as folder/set.000, containing less than set_size frames.

Parameters:

datadict

System data

file_namestr

The output folder

set_sizeint, default=2000

set size

prec{numpy.float32, numpy.float64}

The floating point precision of the compressed data

**kwargsdict

other parameters

class dpdata.plugins.deepmd.DeePMDRawFormat

Bases: Format

DeePMD-kit raw text dataset directory.

DeePMD-kit is a deep learning package for training interatomic potentials. A raw dataset stores atom types in type.raw and frame properties in text files such as coord.raw, box.raw, energy.raw, and force.raw. It is human-readable and convenient for inspection, but deepmd/npy is usually smaller and faster for training.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name[, type_map])	Load a labeled DeePMD raw dataset.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name[, type_map])	Load an unlabeled DeePMD raw dataset.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, file_name, **kwargs)	Write a System or LabeledSystem as DeePMD raw text files.

MultiMode = 1

from_labeled_system(file_name, type_map=None, **kwargs)

Load a labeled DeePMD raw dataset.

Parameters:

file_namestr or os.PathLike

DeePMD raw dataset directory.

type_maplist[str], optional

Element names or requested type ordering used while loading.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Labeled system data with all available registered fields.

from_system(file_name, type_map=None, **kwargs)

Load an unlabeled DeePMD raw dataset.

Parameters:

file_namestr or os.PathLike

DeePMD raw dataset directory.

type_maplist[str], optional

Element names used when type_map.raw is absent, or a requested ordering used to remap the stored atom types.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Unlabeled system data.

to_system(data, file_name, **kwargs)

Write a System or LabeledSystem as DeePMD raw text files.

Parameters:

datadict

System or labeled-system data.

file_namestr or os.PathLike

Destination dataset directory.

**kwargsdict

Additional format arguments accepted for API compatibility.

dpdata.plugins.deepmd.register_spin()

dpdata.plugins.dftbplus module

class dpdata.plugins.dftbplus.DFTBplusFormat

Bases: Format

DFTB+ input/output pair for one labeled molecular configuration.

Pass a tuple containing the DFTB+ input geometry file and output result file. The reader combines symbols and coordinates from the input with the energy and forces from the output. See the DFTB+ documentation for the underlying file formats.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_paths, **kwargs)	Reads system information from the given DFTB+ file paths.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_paths, **kwargs)

Reads system information from the given DFTB+ file paths.

Parameters:

file_pathstuple

A tuple containing the input and output file paths. - Input file (file_in): Contains information about symbols and coord. - Output file (file_out): Contains information about energy and force.

**kwargsdict

other parameters

dpdata.plugins.fhi_aims module

class dpdata.plugins.fhi_aims.FhiMDFormat

Bases: Format

FHI-aims molecular-dynamics or multi-step output.

FHI-aims is an all-electron electronic structure code based on numeric atom-centered orbitals.

The text-output reader extracts geometries, energies, forces, and optional virials from converged FHI-aims calculation steps.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name[, md, begin, ...])	Load labeled frames from FHI-aims output.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name, md=True, begin=0, step=1, convergence_check=True, **kwargs)

Load labeled frames from FHI-aims output.

Parameters:

file_namestr or os.PathLike

FHI-aims output file.

mdbool, default=True

Parse the output as a multi-step molecular-dynamics calculation.

beginint, default=0

Index of the first frame to load.

stepint, default=1

Load every step-th frame.

convergence_checkbool, default=True

Exclude unconverged calculation steps when enabled.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Labeled trajectory data.

class dpdata.plugins.fhi_aims.FhiSCFFormat

Bases: Format

FHI-aims single-point self-consistent-field output.

FHI-aims is an all-electron electronic structure code. The text reader loads the calculation geometry, total energy, forces, and an optional virial into one dpdata.LabeledSystem frame. Use fhi_aims/output for molecular-dynamics or other multi-step output.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Load the first labeled frame from FHI-aims SCF output.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name, **kwargs)

Load the first labeled frame from FHI-aims SCF output.

Parameters:

file_namestr or os.PathLike

FHI-aims output file.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Labeled system data with energy, forces, and optional virial.

dpdata.plugins.gaussian module

class dpdata.plugins.gaussian.GaussiaGJFFormat

Bases: Format

Gaussian input (.gjf/.com) file.

Gaussian is a general-purpose electronic structure package. The reader extracts the molecular geometry from an input deck. The writer creates a Gaussian job for the supplied frames using keyword arguments documented by dpdata.formats.gaussian.gjf.make_gaussian_input().

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Read Gaussian input file.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, file_name, **kwargs)	Generate Gaussian input file.

from_system(file_name: FileType, **kwargs)

Read Gaussian input file.

Parameters:

file_namestr

file name

**kwargsdict

keyword arguments

to_system(data: dict, file_name: FileType, **kwargs)

Generate Gaussian input file.

Parameters:

datadict

system data

file_namestr

file name

**kwargsdict

Other parameters to make input files. See dpdata.formats.gaussian.gjf.make_gaussian_input()

class dpdata.plugins.gaussian.GaussianDriver(gaussian_exec: str = 'g16', **kwargs)

Bases: Driver

Gaussian driver.

Note that “force” keyword must be added. If the number of atoms is large, “Geom=PrintInputOrient” should be added.

Parameters:

gaussian_execstr, default=g16

path to gaussian program

**kwargsdict

other arguments to make input files. See dpdata.formats.gaussian.gjf.make_gaussian_input()

Attributes:

ase_calculator

Returns an ase calculator based on this driver.

Methods

get_driver(key)	Get a driver plugin.
get_drivers()	Get all driver plugins.
label(data)	Label a system data.
register(key)	Register a driver plugin.

Examples

Use B3LYP method to calculate potential energy of a methane molecule:

>>> labeled_system = system.predict(keywords="force b3lyp/6-31g**", driver="gaussian")
>>> labeled_system['energies'][0]
-1102.714590995794

label(data: dict) → dict

Label a system data. Returns new data with energy, forces, and virials.

Parameters:

datadict

data with coordinates and atom types

Returns:

dict

labeled data with energies and forces

class dpdata.plugins.gaussian.GaussianFChkFormat

Bases: Format

Gaussian formatted checkpoint (.fchk) file.

Gaussian is a general-purpose electronic structure package. Formatted checkpoint files provide molecular geometry and energy and may also contain gradients and Cartesian force constants (the Hessian).

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name[, has_forces, ...])	Load a Gaussian formatted checkpoint file.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name: FileType, has_forces=True, has_hessian=True, **kwargs)

Load a Gaussian formatted checkpoint file.

Parameters:

file_namestr or os.PathLike or file-like object

Gaussian .fchk file.

has_forcesbool, default=True

Expect and parse Cartesian gradients as forces.

has_hessianbool, default=True

Expect and parse Cartesian force constants as a Hessian.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Labeled molecular data and, when requested, Hessian data.

class dpdata.plugins.gaussian.GaussianLogFormat

Bases: Format

Gaussian text output containing energies, coordinates, and forces.

Gaussian is a general-purpose electronic structure package for molecules.

Standard single-point or optimization output is read by default. Set md=True when the file contains a Gaussian molecular-dynamics run.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name[, md])	Load labeled frames from a Gaussian log file.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name: FileType, md=False, **kwargs)

Load labeled frames from a Gaussian log file.

Parameters:

file_namestr or os.PathLike or file-like object

Gaussian output file.

mdbool, default=False

Parse multiple molecular-dynamics frames instead of the standard calculation layout.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Labeled molecular data, or empty label arrays when parsing fails.

class dpdata.plugins.gaussian.GaussianMDFormat

Bases: Format

Gaussian molecular-dynamics text output.

Gaussian is a general-purpose electronic structure package. This alias uses the Gaussian log reader with multi-frame MD parsing enabled.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Load a Gaussian molecular-dynamics trajectory.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name: FileType, **kwargs)

Load a Gaussian molecular-dynamics trajectory.

Parameters:

file_namestr or os.PathLike or file-like object

Gaussian MD log file.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Labeled molecular-dynamics frames.

dpdata.plugins.gaussian.register_hessian_data(data)

dpdata.plugins.gromacs module

class dpdata.plugins.gromacs.GromacsGroFormat

Bases: Format

GROMACS .gro structure or trajectory file.

GROMACS is a versatile package for molecular dynamics simulations.

GRO stores atom names, Cartesian coordinates, an optional velocity block, and a periodic box. dpdata reads one or more concatenated frames and can write either a selected frame or the complete trajectory.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name[, format_atom_name])	Load gromacs .gro file.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data[, file_name, frame_idx])	Dump the system in gromacs .gro format.

from_system(file_name, format_atom_name=True, **kwargs)

Load gromacs .gro file.

Parameters:

file_namestr

The input file name

format_atom_namebool

Whether to format the atom name

**kwargsdict

Additional format arguments accepted for API compatibility.

to_system(data, file_name: FileType | None = None, frame_idx=-1, **kwargs)

Dump the system in gromacs .gro format.

Parameters:

datadict

System data

file_namestr or None

The output file name. If None, return the file content as a string

frame_idxint

The index of the frame to dump

**kwargsdict

Additional writer options described below.

Other Parameters:

resnamestr, default=”MOL”

Residue name written for every atom.

shiftint, default=0

Offset added to the one-based atom serial numbers.

dpdata.plugins.lammps module

class dpdata.plugins.lammps.LAMMPSDumpFormat

Bases: Format

LAMMPS text dump trajectory.

LAMMPS (Large-scale Atomic/Molecular Massively Parallel Simulator) is a classical molecular dynamics code.

The reader handles scaled, unscaled, wrapped, and image-flag coordinates, supports frame subsampling, and can use a LAMMPS input file to resolve additional atom-style information. Numeric atom types can be mapped to elements with type_map.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name[, type_map, begin, ...])	Read the data from a lammps dump file.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, file_name[, frame_idx, timestep])	Dump the system in LAMMPS dump format.

from_system(file_name: str, type_map: list[str] = None, begin: int = 0, step: int = 1, unwrap: bool = False, input_file: str = None, f_idx: int | list[int] | ndarray | None = None, **kwargs)

Read the data from a lammps dump file.

Parameters:

file_namestr

The dump file name

type_mapList[str], optional

The atom type list

beginint, optional

The begin step

stepint, optional

The step

unwrapbool, optional

Whether to unwrap the coordinates

input_filestr, optional

The input file name

f_idxint or array-like of int, optional

Specific non-negative frame indices to load. The requested order and duplicate indices are preserved. Cannot be combined with non-default begin or step values.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

The system data

to_system(data, file_name: FileType, frame_idx=0, timestep=0, **kwargs)

Dump the system in LAMMPS dump format.

Parameters:

datadict

System data

file_namestr

The output file name

frame_idxint

The index of the frame to dump

timestepint

The timestep number for the dump

**kwargsdict

other parameters

class dpdata.plugins.lammps.LAMMPSLmpFormat

Bases: Format

LAMMPS data file describing one simulation snapshot.

LAMMPS (Large-scale Atomic/Molecular Massively Parallel Simulator) is a classical molecular dynamics code.

The reader supports common Atoms styles, including atomic, charge, full, molecular, dipole, and sphere layouts. A type_map is usually needed because LAMMPS data files store numeric atom types rather than element symbols.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name[, type_map, atom_style])	Load LAMMPS data file to system data format.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, file_name[, frame_idx])	Dump the system in lammps data format.

from_system(file_name: FileType, type_map=None, atom_style='auto', **kwargs)

Load LAMMPS data file to system data format.

This method supports multiple LAMMPS atom styles with automatic charge extraction and maintains backward compatibility. The parser can automatically detect the atom style from the LAMMPS data file header when possible.

Parameters:

file_namestr or Path

Path to LAMMPS data file

type_maplist, optional

Mapping from atom types to element names

atom_stylestr, optional

The LAMMPS atom style. Default is “auto” which attempts to detect the style automatically from the file. Can also be explicitly set to: atomic, full, charge, bond, angle, molecular, dipole, sphere, spin

**kwargsdict

Other parameters

Returns:

dict

System data dictionary with additional data based on atom style: - charges: For styles with charge information (full, charge, dipole) - molecule_ids: For styles with molecule information (full, bond, angle, molecular) - spins: For spin style with spin vectors

Notes

Atom Style Column Layouts: - atomic: atom-ID atom-type x y z (default) - full: atom-ID molecule-ID atom-type charge x y z - charge: atom-ID atom-type charge x y z - bond: atom-ID molecule-ID atom-type x y z - angle: atom-ID molecule-ID atom-type x y z - molecular: atom-ID molecule-ID atom-type x y z - dipole: atom-ID atom-type charge x y z mux muy muz - sphere: atom-ID atom-type diameter density x y z - spin: atom-ID atom-type x y z spx spy spz sp

Examples

Load LAMMPS data with automatic detection:

>>> system = dpdata.System("data.lmp", type_map=["O", "H"])

Load with specific atom styles:

>>> # Full style with charges and molecule IDs
>>> system = dpdata.System("data.lmp", type_map=["O", "H"], atom_style="full")
>>> print(system["charges"])  # Access extracted charges

>>> # Charge style with charges only
>>> system = dpdata.System("data.lmp", type_map=["O", "H"], atom_style="charge")

>>> # Bond/molecular styles with molecule IDs
>>> system = dpdata.System("data.lmp", type_map=["O", "H"], atom_style="bond")

to_system(data, file_name: FileType, frame_idx=0, **kwargs)

Dump the system in lammps data format.

Parameters:

datadict

System data

file_namestr

The output file name

frame_idxint

The index of the frame to dump

**kwargsdict

other parameters

dpdata.plugins.lammps.register_charge(data: dict) → None

dpdata.plugins.lammps.register_spin(data)

dpdata.plugins.list module

class dpdata.plugins.list.ListFormat

Bases: Format

In-memory list of one-frame System objects.

This write-only convenience format splits a multi-frame System or LabeledSystem into independent one-frame objects; it does not create an on-disk file.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, **kwargs)	Split system data into a list of one-frame systems.

to_system(data, **kwargs)

Split system data into a list of one-frame systems.

Parameters:

datadict

System or labeled-system data.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

list[System] or list[LabeledSystem]

Empty for zero frames; otherwise one object per frame.

dpdata.plugins.lmdb module

dpdata.plugins.n2p2 module

class dpdata.plugins.n2p2.N2P2Format

Bases: Format

n2p2 input.data neural-network training dataset.

Each begin/end block stores a periodic configuration with energy and forces in atomic units. dpdata converts units on read and write. See the n2p2 configuration-file specification.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Read from n2p2 format.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, file_name, **kwargs)	Write n2p2 format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name: FileType, **kwargs)

Read from n2p2 format.

Parameters:

file_namestr

file name, i.e. the first argument

**kwargsdict

keyword arguments that will be passed from the method

Returns:

datadict

system data, whose keys are defined in LabeledSystem.DTYPES

to_labeled_system(data, file_name: FileType, **kwargs)

Write n2p2 format.

By default, LabeledSystem.to will fallback to System.to.

Parameters:

datadict

system data, whose keys are defined in LabeledSystem.DTYPES

file_namestr

file name, where the data will be written

*argslist

arguments that will be passed from the method

**kwargsdict

keyword arguments that will be passed from the method

dpdata.plugins.n2p2.match_indices(atype1, atype2)

dpdata.plugins.openmx module

class dpdata.plugins.openmx.OPENMXFormat

Bases: Format

Output pair from OpenMX.

OpenMX (Open source package for Material eXplorer) is a nano-scale material simulation package based on DFT, norm-conserving pseudopotentials, and pseudo-atomic localized basis functions.

Note that two output files, System.Name.dat and System.Name.md, are required.

Use the openmx/md alias and pass the shared System.Name prefix; dpdata appends .dat and .md automatically.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Read from OpenMX output.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Read from OpenMX output.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name: str, **kwargs) → dict

Read from OpenMX output.

Parameters:

file_namestr

file name, which is specified by a input file, i.e. System.Name.dat

**kwargsdict

other parameters

Returns:

dict

data dict

from_system(file_name: str, **kwargs) → dict

Read from OpenMX output.

Parameters:

file_namestr

file name, which is specified by a input file, i.e. System.Name.dat

**kwargsdict

other parameters

Returns:

dict

data dict

dpdata.plugins.orca module

class dpdata.plugins.orca.ORCASPOutFormat

Bases: Format

ORCA single-point energy and gradient output.

ORCA is an ab initio quantum chemistry program package for molecular calculations.

The reader creates one nonperiodic dpdata.LabeledSystem frame containing atomic coordinates, the total energy, and forces converted from the Cartesian gradient. Both energy and gradient sections must be present in the text output.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Read from ORCA single point energy output.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name: FileType, **kwargs) → dict

Read from ORCA single point energy output.

Parameters:

file_nameFileType

file name

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

system data

dpdata.plugins.psi4 module

class dpdata.plugins.psi4.PSI4InputFormat

Bases: Format

Psi4 input file for a single molecular configuration.

Psi4 is an open-source quantum chemistry program.

The writer emits the molecule, charge, multiplicity, requested electronic- structure method, and basis set. Psi4 input is write-only in dpdata; use psi4/out to load calculated energies and gradients.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, file_name, method, basis[, ...])	Write PSI4 input.

to_system(data: dict, file_name: FileType, method: str, basis: str, charge: int = 0, multiplicity: int = 1, frame_idx=0, **kwargs)

Write PSI4 input.

Parameters:

datadict

system data

file_namestr

file name

methodstr

computational method

basisstr

basis set; see https://psicode.org/psi4manual/master/basissets_tables.html

chargeint, default=0

charge of system

multiplicityint, default=1

multiplicity of system

frame_idxint, default=0

The index of the frame to dump

**kwargsdict

Additional format arguments accepted for API compatibility.

class dpdata.plugins.psi4.PSI4OutFormat

Bases: Format

Psi4 energy and gradient output.

Psi4 is an open-source quantum chemistry program package.

The reader creates one nonperiodic dpdata.LabeledSystem frame containing atomic coordinates, the total energy, and forces converted from the Cartesian gradient. Both energy and gradient sections must be present in the text output.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Read from Psi4 output.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name: FileType, **kwargs) → dict

Read from Psi4 output.

Parameters:

file_nameFileType

file name

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

system data

dpdata.plugins.pwmat module

class dpdata.plugins.pwmat.PwmatAtomconfigFormat

Bases: Format

PWmat atom.config or final.config structure file.

PWmat is a plane-wave DFT software using GPU acceleration.

The format stores a cell and one atomic configuration. Reading normalizes the cell to dpdata’s lower-triangular convention.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Load one PWmat configuration.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, file_name[, frame_idx])	Dump the system in pwmat atom.config format.

from_system(file_name: FileType, **kwargs)

Load one PWmat configuration.

Parameters:

file_namestr or os.PathLike or file-like object

atom.config or final.config input.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

System data for one configuration.

to_system(data, file_name: FileType, frame_idx=0, *args, **kwargs)

Dump the system in pwmat atom.config format.

Parameters:

datadict

The system data

file_namestr

The output file name

frame_idxint

The index of the frame to dump

*argslist

other parameters

**kwargsdict

other parameters

class dpdata.plugins.pwmat.PwmatOutputFormat

Bases: Format

PWmat MOVEMENT/OUT.MLMD labeled trajectory.

PWmat is a plane-wave based DFT electronic-structure calculation software using GPU acceleration.

These output files contain a sequence of cells and coordinates together with energies and optional force or virial labels. The reader supports frame subsampling and convergence filtering.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name[, begin, ...])	Load a labeled PWmat trajectory.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name, begin=0, step=1, convergence_check=True, **kwargs)

Load a labeled PWmat trajectory.

Parameters:

file_namestr or os.PathLike

PWmat MOVEMENT or OUT.MLMD file.

beginint, default=0

Index of the first frame to load.

stepint, default=1

Load every step-th frame.

convergence_checkbool, default=True

Exclude frames marked as unconverged when enabled.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Labeled trajectory data.

dpdata.plugins.pymatgen module

class dpdata.plugins.pymatgen.PyMatgenCSEFormat

Bases: Format

In-memory pymatgen ComputedStructureEntry objects.

pymatgen (Python Materials Genomics) is a robust, open-source Python library for materials analysis.

This write-only labeled adapter creates one entry per frame and places forces and virials in the entry’s data mapping. The optional pymatgen dependency is required.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Convert labeled frames to pymatgen ComputedStructureEntry objects.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

to_labeled_system(data, *args, **kwargs)

Convert labeled frames to pymatgen ComputedStructureEntry objects.

Parameters:

datadict

LabeledSystem data containing energy, forces, and virials.

*argslist

Additional positional arguments accepted for API compatibility.

**kwargsdict

Additional keyword arguments accepted for API compatibility.

Returns:

list[pymatgen.entries.computed_entries.ComputedStructureEntry]

One computed entry per frame.

class dpdata.plugins.pymatgen.PyMatgenMoleculeFormat

Bases: Format

In-memory pymatgen Molecule objects for nonperiodic systems.

pymatgen (Python Materials Genomics) is a robust, open-source Python library for materials analysis.

Periodic boundary conditions are removed during conversion. The optional pymatgen dependency is required, and writing returns one Molecule object per frame.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Convert a pymatgen Molecule into System data.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, **kwargs)	Convert System frames to pymatgen Molecule objects.

from_system(file_name, **kwargs)

Convert a pymatgen Molecule into System data.

Parameters:

file_namepymatgen.core.Molecule

In-memory molecule to convert.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Nonperiodic system data.

to_system(data, **kwargs)

Convert System frames to pymatgen Molecule objects.

Parameters:

datadict

System data. Periodic boundary conditions are removed.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

list[pymatgen.core.Molecule]

One molecule per frame.

class dpdata.plugins.pymatgen.PyMatgenStructureFormat

Bases: Format

In-memory pymatgen Structure objects for periodic systems.

pymatgen (Python Materials Genomics) is a robust, open-source Python library for materials analysis.

This adapter converts without writing a file and requires the optional pymatgen dependency. Writing a multi-frame System returns one Structure object per frame.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(structure, **kwargs)	Convert pymatgen.core.Structure to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, **kwargs)	Convert System frames to pymatgen Structure objects.

from_system(structure, **kwargs) → dict

Convert pymatgen.core.Structure to System.

Parameters:

structurepymatgen.core.Structure

a Pymatgen Structure, containing a structure

**kwargsdict

other parameters

Returns:

dict

data dict

to_system(data, **kwargs)

Convert System frames to pymatgen Structure objects.

Parameters:

datadict

Periodic System data.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

list[pymatgen.core.Structure]

One structure per frame.

dpdata.plugins.qe module

class dpdata.plugins.qe.QECPPWSCFFormat

Bases: Format

Quantum ESPRESSO PWscf self-consistent-field output.

Quantum ESPRESSO is an integrated suite of open-source codes for DFT calculations.

The reader extracts the final cell, coordinates, total energy, forces, and optional stress/virial from a pw.x text output.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Load a labeled Quantum ESPRESSO PWscf calculation.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name, **kwargs)

Load a labeled Quantum ESPRESSO PWscf calculation.

Parameters:

file_namestr or list[str]

Quantum ESPRESSO pw.x output file. The matching input file is inferred by replacing out with in in the base name; pass [input_file, output_file] to give both paths explicitly.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Labeled system data for the calculation.

class dpdata.plugins.qe.QECPTrajFormat

Bases: Format

Quantum ESPRESSO CP trajectory files sharing a common prefix.

Quantum ESPRESSO is an integrated suite of open-source codes for electronic-structure calculations based on DFT, plane waves, and pseudopotentials.

Given file_name='run', dpdata reads run.in together with the CP trajectory files rooted at run. Loading as a labeled system also reads the matching energy and force records.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name[, begin, step])	Load a labeled Quantum ESPRESSO CP trajectory.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name[, begin, step])	Load coordinates and cells from a Quantum ESPRESSO CP trajectory.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name, begin=0, step=1, **kwargs)

Load a labeled Quantum ESPRESSO CP trajectory.

Parameters:

file_namestr

Common prefix of the CP input, trajectory, energy, and force files.

beginint, default=0

Index of the first frame to load.

stepint, default=1

Load every step-th frame.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Coordinates, cells, energies, and forces for the selected frames.

from_system(file_name, begin=0, step=1, **kwargs)

Load coordinates and cells from a Quantum ESPRESSO CP trajectory.

Parameters:

file_namestr

Common prefix of the CP input and trajectory files.

beginint, default=0

Index of the first frame to load.

stepint, default=1

Load every step-th frame.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Unlabeled trajectory data.

dpdata.plugins.rdkit module

class dpdata.plugins.rdkit.MolFormat

Bases: Format

MDL Molfile containing one molecular graph and its conformers.

RDKit is a collection of cheminformatics and machine-learning tools.

Reading and writing requires RDKit. Bond orders and formal charges are preserved through dpdata.BondOrderSystem rather than the regular System classes.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Load an MDL Molfile as an RDKit molecule.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, mol, file_name[, ...])	Write one conformer to an MDL Molfile.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_bond_order_system(file_name, **kwargs)

Load an MDL Molfile as an RDKit molecule.

Parameters:

file_namestr or os.PathLike

Input .mol file.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

rdkit.Chem.Mol

Molecule with explicit hydrogens retained and sanitization deferred to dpdata.BondOrderSystem.

to_bond_order_system(data, mol, file_name, frame_idx=0, **kwargs)

Write one conformer to an MDL Molfile.

Parameters:

datadict

BondOrderSystem data.

molrdkit.Chem.Mol

RDKit molecule carrying the bond graph and conformers.

file_namestr or os.PathLike

Destination .mol file.

frame_idxint, default=0

Conformer/frame index to write.

**kwargsdict

Additional format arguments accepted for API compatibility.

class dpdata.plugins.rdkit.SdfFormat

Bases: Format

Structure-data file (SDF) containing one or more conformers.

RDKit provides cheminformatics capabilities for SDF reading and writing.

All records must describe the same molecular topology so they can be represented as conformers of one dpdata.BondOrderSystem. Reading and writing requires RDKit.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Load same-topology SDF records as one RDKit molecule.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, mol, file_name[, ...])	Write conformers to an SDF file.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_bond_order_system(file_name, **kwargs)

Load same-topology SDF records as one RDKit molecule.

Parameters:

file_namestr or os.PathLike

Input .sdf file. All records must share a topology.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

rdkit.Chem.Mol

Molecule whose conformers correspond to the SDF records.

to_bond_order_system(data, mol, file_name, frame_idx=-1, **kwargs)

Write conformers to an SDF file.

Parameters:

datadict

BondOrderSystem data.

molrdkit.Chem.Mol

RDKit molecule carrying the bond graph and conformers.

file_namestr or os.PathLike

Destination .sdf file.

frame_idxint, default=-1

Conformer to write. -1 writes every conformer as a separate SDF record.

**kwargsdict

Additional format arguments accepted for API compatibility.

dpdata.plugins.siesta module

class dpdata.plugins.siesta.SiestaAIMDOutputFormat

Bases: Format

SIESTA ab initio molecular-dynamics output.

SIESTA (Spanish Initiative for Electronic Simulations with Thousands of Atoms) is an open-source DFT package based on LCAO basis sets.

This reader handles the multi-frame layout emitted by SIESTA AIMD runs and can return either the trajectory geometry alone or all available labels.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Load geometry and labels from a SIESTA AIMD output.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Load geometry from a SIESTA AIMD output.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name, **kwargs)

Load geometry and labels from a SIESTA AIMD output.

Parameters:

file_namestr or os.PathLike

SIESTA AIMD output file.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Labeled trajectory data with energies, forces, and virials.

from_system(file_name, **kwargs)

Load geometry from a SIESTA AIMD output.

Parameters:

file_namestr or os.PathLike

SIESTA AIMD output file.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Unlabeled trajectory data.

class dpdata.plugins.siesta.SiestaOutputFormat

Bases: Format

SIESTA single-step text output.

SIESTA (Spanish Initiative for Electronic Simulations with Thousands of Atoms) is an open-source DFT package based on linear-scaling methods and LCAO basis sets.

The format can be loaded as an unlabeled structure or as a labeled system containing the energy, forces, and virial reported by SIESTA.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Load geometry and labels from a SIESTA output file.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Load geometry from a SIESTA output file.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name, **kwargs)

Load geometry and labels from a SIESTA output file.

Parameters:

file_namestr or os.PathLike

SIESTA text output.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Labeled system data with energy, forces, and virial.

from_system(file_name, **kwargs)

Load geometry from a SIESTA output file.

Parameters:

file_namestr or os.PathLike

SIESTA text output.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Unlabeled system data.

dpdata.plugins.vasp module

class dpdata.plugins.vasp.VASPOutcarFormat

Bases: Format

VASP OUTCAR labeled trajectory.

VASP (Vienna Ab initio Simulation Package) is a computer program for atomic scale materials modelling.

The reader extracts ionic-step cells, coordinates, energies, forces, and virials. It supports frame subsampling, convergence filtering, and recursive loading of conventionally named OUTCAR files into dpdata.MultiSystems.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name[, begin, ...])	Load labeled ionic steps from a VASP OUTCAR.
from_multi_systems(directory, **kwargs)	Find conventionally named OUTCAR files below directory.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name, begin=0, step=1, convergence_check=True, **kwargs)

Load labeled ionic steps from a VASP OUTCAR.

Parameters:

file_namestr or os.PathLike

VASP OUTCAR file.

beginint, default=0

Index of the first ionic step to load.

stepint, default=1

Load every step-th ionic step.

convergence_checkbool, default=True

Exclude unconverged electronic or ionic steps when enabled.

**kwargsdict

Additional options. ml=True reads labels from VASP’s machine- learning force-field output blocks.

Returns:

dict

Labeled trajectory data. Forces or virials are omitted when the corresponding records are unavailable.

from_multi_systems(directory, **kwargs)

Find conventionally named OUTCAR files below directory.

VASP calculations are commonly stored one calculation per directory, so the objects consumed by from_labeled_system() are the OUTCAR files themselves rather than the calculation directories. Searching recursively also supports grouping calculations below intermediate directories such as workflow stages or temperatures.

Parameters:

directorystr or os.PathLike

Root directory containing VASP calculation directories.

**kwargsdict

Additional format options. They are consumed later when each discovered OUTCAR is loaded.

Returns:

list[str]

Deterministically ordered paths to files named OUTCAR.

class dpdata.plugins.vasp.VASPPoscarFormat

Bases: Format

VASP POSCAR or CONTCAR structure file.

VASP (Vienna Ab initio Simulation Package) is a computer program for atomic scale materials modelling.

POSCAR/CONTCAR stores one periodic configuration and optional selective dynamics flags. It does not contain energies or forces, so it maps to dpdata.System rather than dpdata.LabeledSystem.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Load a VASP POSCAR or CONTCAR file.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, file_name[, frame_idx])	Dump the system in vasp POSCAR format.

from_system(file_name: FileType, **kwargs)

Load a VASP POSCAR or CONTCAR file.

Parameters:

file_namestr or os.PathLike or file-like object

POSCAR/CONTCAR input.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

System data, including move selective-dynamics flags when present.

to_system(data, file_name: FileType, frame_idx=0, **kwargs)

Dump the system in vasp POSCAR format.

Parameters:

datadict

The system data

file_namestr

The output file name

frame_idxint

The index of the frame to dump

**kwargsdict

other parameters

class dpdata.plugins.vasp.VASPStringFormat

Bases: Format

In-memory VASP POSCAR text representation.

VASP (Vienna Ab initio Simulation Package) is a computer program for atomic scale materials modelling.

Unlike vasp/poscar, this write-only helper returns the POSCAR content as a string instead of writing it to a file.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data[, frame_idx])	Dump the system in vasp POSCAR format string.

to_system(data, frame_idx=0, **kwargs)

Dump the system in vasp POSCAR format string.

Parameters:

datadict

The system data

frame_idxint

The index of the frame to dump

**kwargsdict

other parameters

class dpdata.plugins.vasp.VASPXMLFormat

Bases: Format

VASP vasprun.xml labeled trajectory.

VASP (Vienna Ab initio Simulation Package) is a computer program for atomic scale materials modelling.

XML output contains structured ionic-step cells, coordinates, energies, forces, and stresses and is useful when text OUTCAR parsing is not desired.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name[, begin, ...])	Load labeled ionic steps from vasprun.xml.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(file_name, begin=0, step=1, convergence_check=True, **kwargs)

Load labeled ionic steps from vasprun.xml.

Parameters:

file_namestr or os.PathLike

VASP XML output file.

beginint, default=0

Index of the first ionic step to load.

stepint, default=1

Load every step-th ionic step.

convergence_checkbool, default=True

Exclude unconverged calculations when enabled.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Labeled trajectory data.

dpdata.plugins.vasp.register_move_data(data)

dpdata.plugins.xyz module

class dpdata.plugins.xyz.QuipGapXYZFormat

Bases: Format

Extended XYZ used by QUIP/GAP and atomistic ML tools.

QUIP/GAP provides a Gaussian Approximation Potential framework, while MACE, NequIP, and GPUMD are modern machine-learning interatomic potential packages.

The comment-line Lattice and Properties metadata can store cells, energies, forces, virials, and per-atom fields. A single file may contain multiple frames and formulas, so the format supports dpdata.MultiSystems. The aliases extxyz, mace/xyz, nequip/xyz, and gpumd/xyz share this implementation.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(data, **kwargs)	Load the first labeled frame from an extended XYZ source.
from_multi_systems(file_name, **kwargs)	Iterate over all frames and formulas in an extended XYZ file.
from_system(file_name, **kwargs)	Implement System.from that converts from this format to System.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, file_name, **kwargs)	Write LabeledSystem data to QUIP/GAP XYZ format file.
to_multi_systems(formulas, directory, **kwargs)	Return single filename for all systems in QUIP/GAP XYZ format.
to_system(data, *args, **kwargs)	Implement System.to that converts from System to this format.

from_labeled_system(data, **kwargs)

Load the first labeled frame from an extended XYZ source.

Parameters:

datastr, os.PathLike, or dict

Input extended XYZ file, or an already parsed frame supplied by from_multi_systems().

**kwargsdict

Extended-XYZ parsing options described below.

Returns:

dict

Labeled data for the first frame.

Other Parameters:

stress_signint, default=-1

Sign in virial = stress_sign * volume * stress. The default follows ASE’s virial = -V * stress convention.

from_multi_systems(file_name, **kwargs)

Iterate over all frames and formulas in an extended XYZ file.

Parameters:

file_namestr or os.PathLike

Input extended XYZ file.

**kwargsdict

Extended-XYZ parsing options described below.

Returns:

collections.abc.Iterable[dict]

Parsed labeled frame dictionaries.

Other Parameters:

stress_signint, default=-1

Sign in virial = stress_sign * volume * stress. The default follows ASE’s virial = -V * stress convention.

to_labeled_system(data, file_name: FileType, **kwargs)

Write LabeledSystem data to QUIP/GAP XYZ format file.

Parameters:

datadict

system data

file_nameFileType

output file name or file handler

**kwargsdict

additional arguments

to_multi_systems(formulas, directory, **kwargs)

Return single filename for all systems in QUIP/GAP XYZ format.

For QUIP/GAP XYZ format, all systems are written to a single file.

Parameters:

formulaslist[str]

list of system names/formulas

directorystr

output filename

**kwargsdict

additional arguments

Yields:

file handler

file handler for all systems

class dpdata.plugins.xyz.XYZFormat

Bases: Format

Plain XYZ molecular structure file.

Plain XYZ stores element symbols and Cartesian coordinates but no cell or labels. dpdata therefore treats it as nonperiodic and assigns a placeholder cell. Use extxyz when energies, forces, virials, or multiple chemical formulas must be preserved.

Methods

MultiModes()	File mode for MultiSystems.
from_bond_order_system(file_name, **kwargs)	Implement BondOrderSystem.from that converts from this format to BondOrderSystem.
from_labeled_system(file_name, **kwargs)	Implement LabeledSystem.from that converts from this format to LabeledSystem.
from_multi_systems(directory, **kwargs)	Implement MultiSystems.from that converts from this format to MultiSystems.
from_system(file_name, **kwargs)	Load the first structure from a plain XYZ file.
get_formats()	Get all registered formats.
get_from_methods()	Get all registered from methods.
get_to_methods()	Get all registered to methods.
mix_system(*system, type_map, **kwargs)	Mix the systems into mixed_type ones according to the unified given type_map.
post(func_name)	Register a post function for from method.
register(key)	Register a format plugin.
register_from(key)	Register a from method if the target method name is not default.
register_to(key)	Register a to method if the target method name is not default.
to_bond_order_system(data, rdkit_mol, *args, ...)	Implement BondOrderSystem.to that converts from BondOrderSystem to this format.
to_labeled_system(data, *args, **kwargs)	Implement LabeledSystem.to that converts from LabeledSystem to this format.
to_multi_systems(formulas, directory, **kwargs)	Implement MultiSystems.to that converts from MultiSystems to this format.
to_system(data, file_name, **kwargs)	Write all frames as concatenated plain XYZ records.

Examples

>>> import dpdata
>>> system = dpdata.System("POSCAR", fmt="vasp/poscar")
>>> system.to("xyz", "a.xyz")

from_system(file_name: FileType, **kwargs)

Load the first structure from a plain XYZ file.

Parameters:

file_namestr or os.PathLike or file-like object

Input XYZ file.

**kwargsdict

Additional format arguments accepted for API compatibility.

Returns:

dict

Nonperiodic System data with a placeholder cell.

to_system(data, file_name: FileType, **kwargs)

Write all frames as concatenated plain XYZ records.

Parameters:

datadict

System data. Cell and label fields are not written.

file_namestr or os.PathLike or file-like object

Destination XYZ file.

**kwargsdict

Additional format arguments accepted for API compatibility.