deepmd package

DeePMD-kit is a package written in Python/C++, designed to minimize the effort required to build deep learning-based model of interatomic potential energy and force field and to perform molecular dynamics (MD).

The top module (deepmd.__init__) should not import any third-party modules for performance.

deepmd.DeepPotential(*args, **kwargs)[source]

Factory function that forwards to DeepEval (for compatbility and performance).

Parameters
*args

positional arguments

**kwargs

keyword arguments

Returns
DeepEval

potentials

Subpackages

Submodules

deepmd.calculator module

ASE calculator interface module.

class deepmd.calculator.DP(model: Union[str, Path], label: str = 'DP', type_dict: Optional[Dict[str, int]] = None, neighbor_list=None, **kwargs)[source]

Bases: Calculator

Implementation of ASE deepmd calculator.

Implemented propertie are energy, forces and stress

Parameters
modelUnion[str, Path]

path to the model

labelstr, optional

calculator label, by default “DP”

type_dictDict[str, int], optional

mapping of element types and their numbers, best left None and the calculator will infer this information from model, by default None

neighbor_listase.neighborlist.NeighborList, optional

The neighbor list object. If None, then build the native neighbor list.

Examples

Compute potential energy

>>> from ase import Atoms
>>> from deepmd.tf.calculator import DP
>>> water = Atoms('H2O',
>>>             positions=[(0.7601, 1.9270, 1),
>>>                        (1.9575, 1, 1),
>>>                        (1., 1., 1.)],
>>>             cell=[100, 100, 100],
>>>             calculator=DP(model="frozen_model.pb"))
>>> print(water.get_potential_energy())
>>> print(water.get_forces())

Run BFGS structure optimization

>>> from ase.optimize import BFGS
>>> dyn = BFGS(water)
>>> dyn.run(fmax=1e-6)
>>> print(water.get_positions())
Attributes
directory
label

Methods

band_structure()

Create band-structure object for plotting.

calculate([atoms, properties, system_changes])

Run calculation with deepmd model.

calculate_numerical_forces(atoms[, d])

Calculate numerical forces using finite difference.

calculate_numerical_stress(atoms[, d, voigt])

Calculate numerical stress using finite difference.

calculate_properties(atoms, properties)

This method is experimental; currently for internal use.

check_state(atoms[, tol])

Check for any system changes since last calculation.

get_magnetic_moments([atoms])

Calculate magnetic moments projected onto atoms.

get_property(name[, atoms, allow_calculation])

Get the named property.

get_stresses([atoms])

the calculator should return intensive stresses, i.e., such that stresses.sum(axis=0) == stress

read(label)

Read atoms, parameters and calculated properties from output file.

reset()

Clear all information from old calculation.

set(**kwargs)

Set parameters like set(key1=value1, key2=value2, ...).

set_label(label)

Set label and convert label to directory and prefix.

calculation_required

export_properties

get_atoms

get_charges

get_default_parameters

get_dipole_moment

get_forces

get_magnetic_moment

get_potential_energies

get_potential_energy

get_stress

read_atoms

todict
calculate(atoms: Optional[Atoms] = None, properties: List[str] = ['energy', 'forces', 'virial'], system_changes: List[str] = ['positions', 'numbers', 'cell', 'pbc', 'initial_charges', 'initial_magmoms'])[source]

Run calculation with deepmd model.

Parameters
atomsOptional[Atoms], optional

atoms object to run the calculation on, by default None

propertiesList[str], optional

unused, only for function signature compatibility, by default [“energy”, “forces”, “stress”]

system_changesList[str], optional

unused, only for function signature compatibility, by default all_changes

implemented_properties: ClassVar[List[str]] = ['energy', 'free_energy', 'forces', 'virial', 'stress']

Properties calculator can handle (energy, forces, …)

name = 'DP'

deepmd.common module

deepmd.common.add_data_requirement(key: str, ndof: int, atomic: bool = False, must: bool = False, high_prec: bool = False, type_sel: Optional[bool] = None, repeat: int = 1, default: float = 0.0, dtype: Optional[dtype] = None, output_natoms_for_type_sel: bool = False)[source]

Specify data requirements for training.

Parameters
keystr

type of data stored in corresponding *.npy file e.g. forces or energy

ndofint

number of the degrees of freedom, this is tied to atomic parameter e.g. forces have atomic=True and ndof=3

atomicbool, optional

specifies whwther the ndof keyworrd applies to per atom quantity or not, by default False

mustbool, optional

specifi if the *.npy data file must exist, by default False

high_precbool, optional

if true load data to np.float64 else np.float32, by default False

type_selbool, optional

select only certain type of atoms, by default None

repeatint, optional

if specify repaeat data repeat times, by default 1

defaultfloat, optional, default=0.

default value of data

dtypenp.dtype, optional

the dtype of data, overwrites high_prec if provided

output_natoms_for_type_selbool, optional

if True and type_sel is True, the atomic dimension will be natoms instead of nsel

deepmd.common.expand_sys_str(root_dir: Union[str, Path]) → List[str][source]

Recursively iterate over directories taking those that contain type.raw file.

Parameters
root_dirUnion[str, Path]

starting directory

Returns
List[str]

list of string pointing to system directories

deepmd.common.get_np_precision(precision: _PRECISION) → dtype[source]

Get numpy precision constant from string.

Parameters
precision_PRECISION

string name of numpy constant or default

Returns
np.dtype

numpy presicion constant

Raises
RuntimeError

if string is invalid

deepmd.common.j_loader(filename: Union[str, Path]) → Dict[str, Any][source]

Load yaml or json settings file.

Parameters
filenameUnion[str, Path]

path to file

Returns
Dict[str, Any]

loaded dictionary

Raises
TypeError

if the supplied file is of unsupported type

deepmd.common.j_must_have(jdata: Dict[str, _DICT_VAL], key: str, deprecated_key: List[str] = []) → _DICT_VAL[source]

Assert that supplied dictionary conaines specified key.

Returns
_DICT_VAL

value that was store unde supplied key

Raises
RuntimeError

if the key is not present

deepmd.common.make_default_mesh(pbc: bool, mixed_type: bool) → ndarray[source]

Make mesh.

Only the size of mesh matters, not the values: * 6 for PBC, no mixed types * 0 for no PBC, no mixed types * 7 for PBC, mixed types * 1 for no PBC, mixed types

Parameters
pbcbool

if True, the mesh will be made for periodic boundary conditions

mixed_typebool

if True, the mesh will be made for mixed types

Returns
np.ndarray

mesh

deepmd.common.select_idx_map(atom_types: ndarray, select_types: ndarray) → ndarray[source]

Build map of indices for element supplied element types from all atoms list.

Parameters
atom_typesnp.ndarray

array specifing type for each atoms as integer

select_typesnp.ndarray

types of atoms you want to find indices for

Returns
np.ndarray

indices of types of atoms defined by select_types in atom_types array

Warning

select_types array will be sorted before finding indices in atom_types

deepmd.driver module

deepmd.env module

deepmd.env.GLOBAL_ENER_FLOAT_PRECISION

alias of float64

deepmd.env.GLOBAL_NP_FLOAT_PRECISION

alias of float64

deepmd.main module

The entry points for DeePMD-kit.

If only printing the help message, this module does not call the main DeePMD-kit module to avoid the slow import of TensorFlow.

class deepmd.main.BackendOption(option_strings, dest, nargs=None, const=None, default=None, type=None, choices=None, required=False, help=None, metavar=None)[source]

Bases: Action

Map backend alias to unique name.

Methods

__call__(parser, namespace, values[, ...])

Call self as a function.

format_usage
class deepmd.main.RawTextArgumentDefaultsHelpFormatter(prog, indent_increment=2, max_help_position=24, width=None)[source]

Bases: RawTextHelpFormatter, ArgumentDefaultsHelpFormatter

This formatter is used to print multile-line help message with default value.

Methods

format_help()

start_section(heading)

add_argument

add_arguments

add_text

add_usage

end_section
deepmd.main.get_ll(log_level: str) → int[source]

Convert string to python logging level.

Parameters
log_levelstr

allowed input values are: DEBUG, INFO, WARNING, ERROR, 3, 2, 1, 0

Returns
int

one of python logging module log levels - 10, 20, 30 or 40

deepmd.main.main()[source]

DeePMD-kit new entry point.

Raises
RuntimeError

if no command was input

deepmd.main.main_parser() → ArgumentParser[source]

DeePMD-Kit commandline options argument parser.

Returns
argparse.ArgumentParser

main parser of DeePMD-kit

deepmd.main.parse_args(args: Optional[List[str]] = None) → Namespace[source]

Parse arguments and convert argument strings to objects.

Parameters
argsList[str]

list of command line arguments, main purpose is testing default option None takes arguments from sys.argv

Returns
argparse.Namespace

the populated namespace