System and LabeledSystem#

This section gives some examples on how dpdata works. Firstly one needs to import the module in a python 3.x compatible code.

import dpdata

The typicall workflow of dpdata is

  1. Load data from vasp or lammps or deepmd-kit data files.

  2. Manipulate data

  3. Dump data to in a desired format

Load data#

d_poscar = dpdata.System("POSCAR", fmt="vasp/poscar")

or let dpdata infer the format (vasp/poscar) of the file from the file name extension

d_poscar = dpdata.System("my.POSCAR")

The number of atoms, atom types, coordinates are loaded from the POSCAR and stored to a data System called d_poscar. A data System (a concept used by deepmd-kit) contains frames that has the same number of atoms of the same type. The order of the atoms should be consistent among the frames in one System. It is noted that POSCAR only contains one frame. If the multiple frames stored in, for example, a OUTCAR is wanted,

d_outcar = dpdata.LabeledSystem("OUTCAR")

The labels provided in the OUTCAR, i.e. energies, forces and virials (if any), are loaded by LabeledSystem. It is noted that the forces of atoms are always assumed to exist. LabeledSystem is a derived class of System.

The System or LabeledSystem can be constructed from the supported file formats with the format key in the table passed to argument fmt.

Access data#

These properties stored in System and LabeledSystem can be accessed by operator [] with the key of the property supplied, for example

coords = d_outcar["coords"]

Available properties are (nframe: number of frames in the system, natoms: total number of atoms in the system)

key

type

dimension

are labels

description

‘atom_names’

list of str

ntypes

False

The name of each atom type

‘atom_numbs’

list of int

ntypes

False

The number of atoms of each atom type

‘atom_types’

np.ndarray

natoms

False

Array assigning type to each atom

‘cells’

np.ndarray

nframes x 3 x 3

False

The cell tensor of each frame

‘coords’

np.ndarray

nframes x natoms x 3

False

The atom coordinates

‘energies’

np.ndarray

nframes

True

The frame energies

‘forces’

np.ndarray

nframes x natoms x 3

True

The atom forces

‘virials’

np.ndarray

nframes x 3 x 3

True

The virial tensor of each frame

Dump data#

The data stored in System or LabeledSystem can be dumped in ‘lammps/lmp’ or ‘vasp/poscar’ format, for example:

d_outcar.to("lammps/lmp", "conf.lmp", frame_idx=0)

The first frames of d_outcar will be dumped to ‘conf.lmp’

d_outcar.to("vasp/poscar", "POSCAR", frame_idx=-1)

The last frames of d_outcar will be dumped to ‘POSCAR’.

The data stored in LabeledSystem can be dumped to deepmd-kit raw format, for example

d_outcar.to("deepmd/raw", "dpmd_raw")

Or a simpler command:

dpdata.LabeledSystem("OUTCAR").to("deepmd/raw", "dpmd_raw")

Frame selection can be implemented by

dpdata.LabeledSystem("OUTCAR").sub_system([0, -1]).to("deepmd/raw", "dpmd_raw")

by which only the first and last frames are dumped to dpmd_raw.

replicate#

dpdata will create a super cell of the current atom configuration.

dpdata.System("./POSCAR").replicate(
    (
        1,
        2,
        3,
    )
)

tuple(1,2,3) means don’t copy atom configuration in x direction, make 2 copys in y direction, make 3 copys in z direction.

perturb#

By the following example, each frame of the original system (dpdata.System('./POSCAR')) is perturbed to generate three new frames. For each frame, the cell is perturbed by 5% and the atom positions are perturbed by 0.6 Angstrom. atom_pert_style indicates that the perturbation to the atom positions is subject to normal distribution. Other available options to atom_pert_style areuniform (uniform in a ball), and const (uniform on a sphere).

perturbed_system = dpdata.System("./POSCAR").perturb(
    pert_num=3,
    cell_pert_fraction=0.05,
    atom_pert_distance=0.6,
    atom_pert_style="normal",
)
print(perturbed_system.data)

replace#

By the following example, Random 8 Hf atoms in the system will be replaced by Zr atoms with the atom postion unchanged.

s = dpdata.System("tests/poscars/POSCAR.P42nmc", fmt="vasp/poscar")
s.replace("Hf", "Zr", 8)
s.to_vasp_poscar("POSCAR.P42nmc.replace")