From 3a9ec1c8abfb8e7d48def4505050c72990c639a2 Mon Sep 17 00:00:00 2001 From: Jinzhe Zeng Date: Sat, 21 Aug 2021 17:42:36 -0400 Subject: [PATCH] move parameters docstring from constructor method to class itself Otherwise it won't be shown in the document. Also contains other cleanups. --- deepmd/descriptor/hybrid.py | 17 ++++---- deepmd/descriptor/loc_frame.py | 48 +++++++++++---------- deepmd/descriptor/se_a.py | 71 ++++++++++++++++--------------- deepmd/descriptor/se_a_ebd.py | 76 +++++++++++++++++----------------- deepmd/descriptor/se_a_ef.py | 68 +++++++++++++++--------------- deepmd/descriptor/se_r.py | 62 ++++++++++++++------------- deepmd/descriptor/se_t.py | 57 +++++++++++++------------ deepmd/fit/dipole.py | 40 +++++++++--------- deepmd/fit/ener.py | 66 +++++++++++++++-------------- deepmd/fit/polar.py | 55 ++++++++++++------------ deepmd/fit/wfc.py | 5 ++- deepmd/infer/data_modifier.py | 28 +++++++------ deepmd/infer/deep_tensor.py | 3 +- deepmd/infer/model_devi.py | 1 - deepmd/model/ener.py | 46 ++++++++++---------- deepmd/model/tensor.py | 34 ++++++++------- deepmd/utils/data.py | 36 +++++++++------- deepmd/utils/data_system.py | 6 ++- deepmd/utils/learning_rate.py | 35 +++++++++------- deepmd/utils/neighbor_stat.py | 15 +++---- deepmd/utils/pair_tab.py | 24 ++++++----- deepmd/utils/tabulate.py | 21 +++++----- deepmd/utils/type_embed.py | 38 +++++++++-------- doc/conf.py | 1 + 24 files changed, 455 insertions(+), 398 deletions(-) diff --git a/deepmd/descriptor/hybrid.py b/deepmd/descriptor/hybrid.py index 592b5e6c2c..013ee9f753 100644 --- a/deepmd/descriptor/hybrid.py +++ b/deepmd/descriptor/hybrid.py @@ -21,16 +21,18 @@ from .loc_frame import DescrptLocFrame class DescrptHybrid (): + """Concate a list of descriptors to form a new descriptor. + + Parameters + ---------- + descrpt_list : list + Build a descriptor from the concatenation of the list of descriptors. + """ def __init__ (self, descrpt_list : list ) -> None : """ Constructor - - Parameters - ---------- - descrpt_list : list - Build a descriptor from the concatenation of the list of descriptors. """ if descrpt_list == [] or descrpt_list is None: raise RuntimeError('cannot build descriptor from an empty list of descriptors.') @@ -72,11 +74,12 @@ def get_dim_out (self) -> int: def get_nlist_i(self, ii : int ) -> Tuple[tf.Tensor, tf.Tensor, List[int], List[int]]: - """ + """Get the neighbor information of the ii-th descriptor + Parameters ---------- ii : int - Get the neighbor information of the ii-th descriptor + The index of the descriptor Returns ------- diff --git a/deepmd/descriptor/loc_frame.py b/deepmd/descriptor/loc_frame.py index 51bc044cfc..2f778b2049 100644 --- a/deepmd/descriptor/loc_frame.py +++ b/deepmd/descriptor/loc_frame.py @@ -9,6 +9,31 @@ from deepmd.utils.sess import run_sess class DescrptLocFrame () : + """Defines a local frame at each atom, and the compute the descriptor as local + coordinates under this frame. + + Parameters + ---------- + rcut + The cut-off radius + sel_a : list[str] + The length of the list should be the same as the number of atom types in the system. + `sel_a[i]` gives the selected number of type-i neighbors. + The full relative coordinates of the neighbors are used by the descriptor. + sel_r : list[str] + The length of the list should be the same as the number of atom types in the system. + `sel_r[i]` gives the selected number of type-i neighbors. + Only relative distance of the neighbors are used by the descriptor. + sel_a[i] + sel_r[i] is recommended to be larger than the maximally possible number of type-i neighbors in the cut-off radius. + axis_rule: list[int] + The length should be 6 times of the number of types. + - axis_rule[i*6+0]: class of the atom defining the first axis of type-i atom. 0 for neighbors with full coordinates and 1 for neighbors only with relative distance.\n\n\ + - axis_rule[i*6+1]: type of the atom defining the first axis of type-i atom.\n\n\ + - axis_rule[i*6+2]: index of the axis atom defining the first axis. Note that the neighbors with the same class and type are sorted according to their relative distance.\n\n\ + - axis_rule[i*6+3]: class of the atom defining the first axis of type-i atom. 0 for neighbors with full coordinates and 1 for neighbors only with relative distance.\n\n\ + - axis_rule[i*6+4]: type of the atom defining the second axis of type-i atom.\n\n\ + - axis_rule[i*6+5]: class of the atom defining the second axis of type-i atom. 0 for neighbors with full coordinates and 1 for neighbors only with relative distance. + """ def __init__(self, rcut: float, sel_a : List[int], @@ -16,28 +41,7 @@ def __init__(self, axis_rule : List[int] ) -> None: """ - Constructor - - Parameters - rcut - The cut-off radius - sel_a : list[str] - The length of the list should be the same as the number of atom types in the system. - `sel_a[i]` gives the selected number of type-i neighbors. - The full relative coordinates of the neighbors are used by the descriptor. - sel_r : list[str] - The length of the list should be the same as the number of atom types in the system. - `sel_r[i]` gives the selected number of type-i neighbors. - Only relative distance of the neighbors are used by the descriptor. - sel_a[i] + sel_r[i] is recommended to be larger than the maximally possible number of type-i neighbors in the cut-off radius. - axis_rule: list[int] - The length should be 6 times of the number of types. - - axis_rule[i*6+0]: class of the atom defining the first axis of type-i atom. 0 for neighbors with full coordinates and 1 for neighbors only with relative distance.\n\n\ - - axis_rule[i*6+1]: type of the atom defining the first axis of type-i atom.\n\n\ - - axis_rule[i*6+2]: index of the axis atom defining the first axis. Note that the neighbors with the same class and type are sorted according to their relative distance.\n\n\ - - axis_rule[i*6+3]: class of the atom defining the first axis of type-i atom. 0 for neighbors with full coordinates and 1 for neighbors only with relative distance.\n\n\ - - axis_rule[i*6+4]: type of the atom defining the second axis of type-i atom.\n\n\ - - axis_rule[i*6+5]: class of the atom defining the second axis of type-i atom. 0 for neighbors with full coordinates and 1 for neighbors only with relative distance. + Constructor """ # args = ClassArg()\ # .add('sel_a', list, must = True) \ diff --git a/deepmd/descriptor/se_a.py b/deepmd/descriptor/se_a.py index a690bbef4a..d7410fa910 100644 --- a/deepmd/descriptor/se_a.py +++ b/deepmd/descriptor/se_a.py @@ -15,6 +15,44 @@ from deepmd.utils.sess import run_sess class DescrptSeA (): + """DeepPot-SE constructed from all information (both angular and radial) of + atomic configurations. + + The embedding takes the distance between atoms as input. + + Parameters + ---------- + rcut + The cut-off radius + rcut_smth + From where the environment matrix should be smoothed + sel : list[str] + sel[i] specifies the maxmum number of type i atoms in the cut-off radius + neuron : list[int] + Number of neurons in each hidden layers of the embedding net + axis_neuron + Number of the axis neuron (number of columns of the sub-matrix of the embedding matrix) + resnet_dt + Time-step `dt` in the resnet construction: + y = x + dt * \phi (Wx + b) + trainable + If the weights of embedding net are trainable. + seed + Random seed for initializing the network parameters. + type_one_side + Try to build N_types embedding nets. Otherwise, building N_types^2 embedding nets + exclude_types : List[List[int]] + The excluded pairs of types which have no interaction with each other. + For example, `[[0, 1]]` means no interaction between type 0 and type 1. + set_davg_zero + Set the shift of embedding net input to zero. + activation_function + The activation function in the embedding net. Supported options are {0} + precision + The precision of the embedding net parameters. Supported options are {1} + uniform_seed + Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed + """ @docstring_parameter(list_to_doc(ACTIVATION_FN_DICT.keys()), list_to_doc(PRECISION_DICT.keys())) def __init__ (self, rcut: float, @@ -34,39 +72,6 @@ def __init__ (self, ) -> None: """ Constructor - - Parameters - ---------- - rcut - The cut-off radius - rcut_smth - From where the environment matrix should be smoothed - sel : list[str] - sel[i] specifies the maxmum number of type i atoms in the cut-off radius - neuron : list[int] - Number of neurons in each hidden layers of the embedding net - axis_neuron - Number of the axis neuron (number of columns of the sub-matrix of the embedding matrix) - resnet_dt - Time-step `dt` in the resnet construction: - y = x + dt * \phi (Wx + b) - trainable - If the weights of embedding net are trainable. - seed - Random seed for initializing the network parameters. - type_one_side - Try to build N_types embedding nets. Otherwise, building N_types^2 embedding nets - exclude_types : List[List[int]] - The excluded pairs of types which have no interaction with each other. - For example, `[[0, 1]]` means no interaction between type 0 and type 1. - set_davg_zero - Set the shift of embedding net input to zero. - activation_function - The activation function in the embedding net. Supported options are {0} - precision - The precision of the embedding net parameters. Supported options are {1} - uniform_seed - Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed """ self.sel_a = sel self.rcut_r = rcut diff --git a/deepmd/descriptor/se_a_ebd.py b/deepmd/descriptor/se_a_ebd.py index 9376646149..b30501963f 100644 --- a/deepmd/descriptor/se_a_ebd.py +++ b/deepmd/descriptor/se_a_ebd.py @@ -12,6 +12,45 @@ from .se_a import DescrptSeA class DescrptSeAEbd (DescrptSeA): + """DeepPot-SE descriptor with type embedding approach. + + Parameters + ---------- + rcut + The cut-off radius + rcut_smth + From where the environment matrix should be smoothed + sel : list[str] + sel[i] specifies the maxmum number of type i atoms in the cut-off radius + neuron : list[int] + Number of neurons in each hidden layers of the embedding net + axis_neuron + Number of the axis neuron (number of columns of the sub-matrix of the embedding matrix) + resnet_dt + Time-step `dt` in the resnet construction: + y = x + dt * \phi (Wx + b) + trainable + If the weights of embedding net are trainable. + seed + Random seed for initializing the network parameters. + type_one_side + Try to build N_types embedding nets. Otherwise, building N_types^2 embedding nets + type_nchanl + Number of channels for type representation + type_nlayer + Number of hidden layers for the type embedding net (skip connected). + numb_aparam + Number of atomic parameters. If >0 it will be embedded with atom types. + set_davg_zero + Set the shift of embedding net input to zero. + activation_function + The activation function in the embedding net. Supported options are {0} + precision + The precision of the embedding net parameters. Supported options are {1} + exclude_types : List[List[int]] + The excluded pairs of types which have no interaction with each other. + For example, `[[0, 1]]` means no interaction between type 0 and type 1. + """ def __init__ (self, rcut: float, rcut_smth: float, @@ -32,43 +71,6 @@ def __init__ (self, ) -> None: """ Constructor - - Parameters - ---------- - rcut - The cut-off radius - rcut_smth - From where the environment matrix should be smoothed - sel : list[str] - sel[i] specifies the maxmum number of type i atoms in the cut-off radius - neuron : list[int] - Number of neurons in each hidden layers of the embedding net - axis_neuron - Number of the axis neuron (number of columns of the sub-matrix of the embedding matrix) - resnet_dt - Time-step `dt` in the resnet construction: - y = x + dt * \phi (Wx + b) - trainable - If the weights of embedding net are trainable. - seed - Random seed for initializing the network parameters. - type_one_side - Try to build N_types embedding nets. Otherwise, building N_types^2 embedding nets - type_nchanl - Number of channels for type representation - type_nlayer - Number of hidden layers for the type embedding net (skip connected). - numb_aparam - Number of atomic parameters. If >0 it will be embedded with atom types. - set_davg_zero - Set the shift of embedding net input to zero. - activation_function - The activation function in the embedding net. Supported options are {0} - precision - The precision of the embedding net parameters. Supported options are {1} - exclude_types : List[List[int]] - The excluded pairs of types which have no interaction with each other. - For example, `[[0, 1]]` means no interaction between type 0 and type 1. """ # args = ClassArg()\ # .add('type_nchanl', int, default = 4) \ diff --git a/deepmd/descriptor/se_a_ef.py b/deepmd/descriptor/se_a_ef.py index c3ad7ae47b..597a4ac8d4 100644 --- a/deepmd/descriptor/se_a_ef.py +++ b/deepmd/descriptor/se_a_ef.py @@ -12,6 +12,41 @@ from .se_a import DescrptSeA class DescrptSeAEf (): + """ + + Parameters + ---------- + rcut + The cut-off radius + rcut_smth + From where the environment matrix should be smoothed + sel : list[str] + sel[i] specifies the maxmum number of type i atoms in the cut-off radius + neuron : list[int] + Number of neurons in each hidden layers of the embedding net + axis_neuron + Number of the axis neuron (number of columns of the sub-matrix of the embedding matrix) + resnet_dt + Time-step `dt` in the resnet construction: + y = x + dt * \phi (Wx + b) + trainable + If the weights of embedding net are trainable. + seed + Random seed for initializing the network parameters. + type_one_side + Try to build N_types embedding nets. Otherwise, building N_types^2 embedding nets + exclude_types : List[List[int]] + The excluded pairs of types which have no interaction with each other. + For example, `[[0, 1]]` means no interaction between type 0 and type 1. + set_davg_zero + Set the shift of embedding net input to zero. + activation_function + The activation function in the embedding net. Supported options are {0} + precision + The precision of the embedding net parameters. Supported options are {1} + uniform_seed + Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed + """ @docstring_parameter(list_to_doc(ACTIVATION_FN_DICT.keys()), list_to_doc(PRECISION_DICT.keys())) def __init__(self, rcut: float, @@ -31,39 +66,6 @@ def __init__(self, ) -> None: """ Constructor - - Parameters - ---------- - rcut - The cut-off radius - rcut_smth - From where the environment matrix should be smoothed - sel : list[str] - sel[i] specifies the maxmum number of type i atoms in the cut-off radius - neuron : list[int] - Number of neurons in each hidden layers of the embedding net - axis_neuron - Number of the axis neuron (number of columns of the sub-matrix of the embedding matrix) - resnet_dt - Time-step `dt` in the resnet construction: - y = x + dt * \phi (Wx + b) - trainable - If the weights of embedding net are trainable. - seed - Random seed for initializing the network parameters. - type_one_side - Try to build N_types embedding nets. Otherwise, building N_types^2 embedding nets - exclude_types : List[List[int]] - The excluded pairs of types which have no interaction with each other. - For example, `[[0, 1]]` means no interaction between type 0 and type 1. - set_davg_zero - Set the shift of embedding net input to zero. - activation_function - The activation function in the embedding net. Supported options are {0} - precision - The precision of the embedding net parameters. Supported options are {1} - uniform_seed - Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed """ self.descrpt_para = DescrptSeAEfLower( op_module.descrpt_se_a_ef_para, diff --git a/deepmd/descriptor/se_r.py b/deepmd/descriptor/se_r.py index 4e336c0f5f..de013921d7 100644 --- a/deepmd/descriptor/se_r.py +++ b/deepmd/descriptor/se_r.py @@ -12,6 +12,39 @@ from deepmd.utils.sess import run_sess class DescrptSeR (): + """DeepPot-SE constructed from radial information of atomic configurations. + + The embedding takes the distance between atoms as input. + + Parameters + ---------- + rcut + The cut-off radius + rcut_smth + From where the environment matrix should be smoothed + sel : list[str] + sel[i] specifies the maxmum number of type i atoms in the cut-off radius + neuron : list[int] + Number of neurons in each hidden layers of the embedding net + resnet_dt + Time-step `dt` in the resnet construction: + y = x + dt * \phi (Wx + b) + trainable + If the weights of embedding net are trainable. + seed + Random seed for initializing the network parameters. + type_one_side + Try to build N_types embedding nets. Otherwise, building N_types^2 embedding nets + exclude_types : List[List[int]] + The excluded pairs of types which have no interaction with each other. + For example, `[[0, 1]]` means no interaction between type 0 and type 1. + activation_function + The activation function in the embedding net. Supported options are {0} + precision + The precision of the embedding net parameters. Supported options are {1} + uniform_seed + Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed + """ @docstring_parameter(list_to_doc(ACTIVATION_FN_DICT.keys()), list_to_doc(PRECISION_DICT.keys())) def __init__ (self, rcut: float, @@ -30,35 +63,6 @@ def __init__ (self, ) -> None: """ Constructor - - Parameters - ---------- - rcut - The cut-off radius - rcut_smth - From where the environment matrix should be smoothed - sel : list[str] - sel[i] specifies the maxmum number of type i atoms in the cut-off radius - neuron : list[int] - Number of neurons in each hidden layers of the embedding net - resnet_dt - Time-step `dt` in the resnet construction: - y = x + dt * \phi (Wx + b) - trainable - If the weights of embedding net are trainable. - seed - Random seed for initializing the network parameters. - type_one_side - Try to build N_types embedding nets. Otherwise, building N_types^2 embedding nets - exclude_types : List[List[int]] - The excluded pairs of types which have no interaction with each other. - For example, `[[0, 1]]` means no interaction between type 0 and type 1. - activation_function - The activation function in the embedding net. Supported options are {0} - precision - The precision of the embedding net parameters. Supported options are {1} - uniform_seed - Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed """ # args = ClassArg()\ # .add('sel', list, must = True) \ diff --git a/deepmd/descriptor/se_t.py b/deepmd/descriptor/se_t.py index 97a9019ffa..a611acd5fd 100644 --- a/deepmd/descriptor/se_t.py +++ b/deepmd/descriptor/se_t.py @@ -12,6 +12,37 @@ from deepmd.utils.sess import run_sess class DescrptSeT (): + """DeepPot-SE constructed from all information (both angular and radial) of atomic + configurations. + + The embedding takes angles between two neighboring atoms as input. + + Parameters + ---------- + rcut + The cut-off radius + rcut_smth + From where the environment matrix should be smoothed + sel : list[str] + sel[i] specifies the maxmum number of type i atoms in the cut-off radius + neuron : list[int] + Number of neurons in each hidden layers of the embedding net + resnet_dt + Time-step `dt` in the resnet construction: + y = x + dt * \phi (Wx + b) + trainable + If the weights of embedding net are trainable. + seed + Random seed for initializing the network parameters. + set_davg_zero + Set the shift of embedding net input to zero. + activation_function + The activation function in the embedding net. Supported options are {0} + precision + The precision of the embedding net parameters. Supported options are {1} + uniform_seed + Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed + """ @docstring_parameter(list_to_doc(ACTIVATION_FN_DICT.keys()), list_to_doc(PRECISION_DICT.keys())) def __init__ (self, rcut: float, @@ -28,32 +59,6 @@ def __init__ (self, ) -> None: """ Constructor - - Parameters - ---------- - rcut - The cut-off radius - rcut_smth - From where the environment matrix should be smoothed - sel : list[str] - sel[i] specifies the maxmum number of type i atoms in the cut-off radius - neuron : list[int] - Number of neurons in each hidden layers of the embedding net - resnet_dt - Time-step `dt` in the resnet construction: - y = x + dt * \phi (Wx + b) - trainable - If the weights of embedding net are trainable. - seed - Random seed for initializing the network parameters. - set_davg_zero - Set the shift of embedding net input to zero. - activation_function - The activation function in the embedding net. Supported options are {0} - precision - The precision of the embedding net parameters. Supported options are {1} - uniform_seed - Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed """ self.sel_a = sel self.rcut_r = rcut diff --git a/deepmd/fit/dipole.py b/deepmd/fit/dipole.py index 0241fc8111..81c26db9c9 100644 --- a/deepmd/fit/dipole.py +++ b/deepmd/fit/dipole.py @@ -14,6 +14,26 @@ class DipoleFittingSeA () : """ Fit the atomic dipole with descriptor se_a + + Parameters + ---------- + descrpt : tf.Tensor + The descrptor + neuron : List[int] + Number of neurons in each hidden layer of the fitting net + resnet_dt : bool + Time-step `dt` in the resnet construction: + y = x + dt * \phi (Wx + b) + sel_type : List[int] + The atom types selected to have an atomic dipole prediction. If is None, all atoms are selected. + seed : int + Random seed for initializing the network parameters. + activation_function : str + The activation function in the embedding net. Supported options are {0} + precision : str + The precision of the embedding net parameters. Supported options are {1} + uniform_seed + Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed """ @docstring_parameter(list_to_doc(ACTIVATION_FN_DICT.keys()), list_to_doc(PRECISION_DICT.keys())) def __init__ (self, @@ -28,26 +48,6 @@ def __init__ (self, ) -> None: """ Constructor - - Parameters - ---------- - descrpt : tf.Tensor - The descrptor - neuron : List[int] - Number of neurons in each hidden layer of the fitting net - resnet_dt : bool - Time-step `dt` in the resnet construction: - y = x + dt * \phi (Wx + b) - sel_type : List[int] - The atom types selected to have an atomic dipole prediction. If is None, all atoms are selected. - seed : int - Random seed for initializing the network parameters. - activation_function : str - The activation function in the embedding net. Supported options are {0} - precision : str - The precision of the embedding net parameters. Supported options are {1} - uniform_seed - Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed """ if not isinstance(descrpt, DescrptSeA) : raise RuntimeError('DipoleFittingSeA only supports DescrptSeA') diff --git a/deepmd/fit/ener.py b/deepmd/fit/ener.py index 138c461f3e..c24df42e7e 100644 --- a/deepmd/fit/ener.py +++ b/deepmd/fit/ener.py @@ -14,6 +14,40 @@ from deepmd.env import GLOBAL_TF_FLOAT_PRECISION class EnerFitting (): + """Fitting the energy of the system. The force and the virial can also be trained. + + Parameters + ---------- + descrpt + The descrptor + neuron + Number of neurons in each hidden layer of the fitting net + resnet_dt + Time-step `dt` in the resnet construction: + y = x + dt * \phi (Wx + b) + numb_fparam + Number of frame parameter + numb_aparam + Number of atomic parameter + rcond + The condition number for the regression of atomic energy. + tot_ener_zero + Force the total energy to zero. Useful for the charge fitting. + trainable + If the weights of fitting net are trainable. + Suppose that we have N_l hidden layers in the fitting net, + this list is of length N_l + 1, specifying if the hidden layers and the output layer are trainable. + seed + Random seed for initializing the network parameters. + atom_ener + Specifying atomic energy contribution in vacuum. The `set_davg_zero` key in the descrptor should be set. + activation_function + The activation function in the embedding net. Supported options are {0} + precision + The precision of the embedding net parameters. Supported options are {1} + uniform_seed + Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed + """ @docstring_parameter(list_to_doc(ACTIVATION_FN_DICT.keys()), list_to_doc(PRECISION_DICT.keys())) def __init__ (self, descrpt : tf.Tensor, @@ -32,38 +66,6 @@ def __init__ (self, ) -> None: """ Constructor - - Parameters - ---------- - descrpt - The descrptor - neuron - Number of neurons in each hidden layer of the fitting net - resnet_dt - Time-step `dt` in the resnet construction: - y = x + dt * \phi (Wx + b) - numb_fparam - Number of frame parameter - numb_aparam - Number of atomic parameter - rcond - The condition number for the regression of atomic energy. - tot_ener_zero - Force the total energy to zero. Useful for the charge fitting. - trainable - If the weights of fitting net are trainable. - Suppose that we have N_l hidden layers in the fitting net, - this list is of length N_l + 1, specifying if the hidden layers and the output layer are trainable. - seed - Random seed for initializing the network parameters. - atom_ener - Specifying atomic energy contribution in vacuum. The `set_davg_zero` key in the descrptor should be set. - activation_function - The activation function in the embedding net. Supported options are {0} - precision - The precision of the embedding net parameters. Supported options are {1} - uniform_seed - Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed """ # model param self.ntypes = descrpt.get_ntypes() diff --git a/deepmd/fit/polar.py b/deepmd/fit/polar.py index 6bb5c75e34..c82e08f214 100644 --- a/deepmd/fit/polar.py +++ b/deepmd/fit/polar.py @@ -15,7 +15,10 @@ class PolarFittingLocFrame () : """ - Fitting polarizability with local frame descriptor. not supported anymore. + Fitting polarizability with local frame descriptor. + + .. deprecated:: 2.0.0 + This class is not supported any more. """ def __init__ (self, jdata, descrpt) : if not isinstance(descrpt, DescrptLocFrame) : @@ -372,6 +375,30 @@ def build (self, class GlobalPolarFittingSeA () : """ Fit the system polarizability with descriptor se_a + + Parameters + ---------- + descrpt : tf.Tensor + The descrptor + neuron : List[int] + Number of neurons in each hidden layer of the fitting net + resnet_dt : bool + Time-step `dt` in the resnet construction: + y = x + dt * \phi (Wx + b) + sel_type : List[int] + The atom types selected to have an atomic polarizability prediction + fit_diag : bool + Fit the diagonal part of the rotational invariant polarizability matrix, which will be converted to normal polarizability matrix by contracting with the rotation matrix. + scale : List[float] + The output of the fitting net (polarizability matrix) for type i atom will be scaled by scale[i] + diag_shift : List[float] + The diagonal part of the polarizability matrix of type i will be shifted by diag_shift[i]. The shift operation is carried out after scale. + seed : int + Random seed for initializing the network parameters. + activation_function : str + The activation function in the embedding net. Supported options are {0} + precision : str + The precision of the embedding net parameters. Supported options are {1} """ @docstring_parameter(list_to_doc(ACTIVATION_FN_DICT.keys()), list_to_doc(PRECISION_DICT.keys())) def __init__ (self, @@ -387,31 +414,7 @@ def __init__ (self, precision : str = 'default' ) -> None: """ - Constructor - - Parameters - ---------- - descrpt : tf.Tensor - The descrptor - neuron : List[int] - Number of neurons in each hidden layer of the fitting net - resnet_dt : bool - Time-step `dt` in the resnet construction: - y = x + dt * \phi (Wx + b) - sel_type : List[int] - The atom types selected to have an atomic polarizability prediction - fit_diag : bool - Fit the diagonal part of the rotational invariant polarizability matrix, which will be converted to normal polarizability matrix by contracting with the rotation matrix. - scale : List[float] - The output of the fitting net (polarizability matrix) for type i atom will be scaled by scale[i] - diag_shift : List[float] - The diagonal part of the polarizability matrix of type i will be shifted by diag_shift[i]. The shift operation is carried out after scale. - seed : int - Random seed for initializing the network parameters. - activation_function : str - The activation function in the embedding net. Supported options are {0} - precision : str - The precision of the embedding net parameters. Supported options are {1} + Constructor """ if not isinstance(descrpt, DescrptSeA) : raise RuntimeError('GlobalPolarFittingSeA only supports DescrptSeA') diff --git a/deepmd/fit/wfc.py b/deepmd/fit/wfc.py index fce82bd04b..9b6b217432 100644 --- a/deepmd/fit/wfc.py +++ b/deepmd/fit/wfc.py @@ -13,7 +13,10 @@ class WFCFitting () : """ - Fitting Wannier function centers (WFCs) with local frame descriptor. Not supported anymore. + Fitting Wannier function centers (WFCs) with local frame descriptor. + + .. deprecated:: 2.0.0 + This class is not supported any more. """ def __init__ (self, jdata, descrpt): if not isinstance(descrpt, DescrptLocFrame) : diff --git a/deepmd/infer/data_modifier.py b/deepmd/infer/data_modifier.py index 5c8a966cfb..6b473e93e6 100644 --- a/deepmd/infer/data_modifier.py +++ b/deepmd/infer/data_modifier.py @@ -16,6 +16,21 @@ class DipoleChargeModifier(DeepDipole): + """ + + Parameters + ---------- + model_name + The model file for the DeepDipole model + model_charge_map + Gives the amount of charge for the wfcc + sys_charge_map + Gives the amount of charge for the real atoms + ewald_h + Grid spacing of the reciprocal part of Ewald sum. Unit: A + ewald_beta + Splitting parameter of the Ewald sum. Unit: A^{-1} + """ def __init__(self, model_name : str, model_charge_map : List[float], @@ -25,19 +40,6 @@ def __init__(self, ) -> None: """ Constructor - - Parameters - ---------- - model_name - The model file for the DeepDipole model - model_charge_map - Gives the amount of charge for the wfcc - sys_charge_map - Gives the amount of charge for the real atoms - ewald_h - Grid spacing of the reciprocal part of Ewald sum. Unit: A - ewald_beta - Splitting parameter of the Ewald sum. Unit: A^{-1} """ # the dipole model is loaded with prefix 'dipole_charge' self.modifier_prefix = 'dipole_charge' diff --git a/deepmd/infer/deep_tensor.py b/deepmd/infer/deep_tensor.py index b6a541f83b..3512879580 100644 --- a/deepmd/infer/deep_tensor.py +++ b/deepmd/infer/deep_tensor.py @@ -13,8 +13,6 @@ class DeepTensor(DeepEval): """Evaluates a tensor model. - Constructor - Parameters ---------- model_file: str @@ -47,6 +45,7 @@ def __init__( load_prefix: str = 'load', default_tf_graph: bool = False ) -> None: + """Constructor""" DeepEval.__init__( self, model_file, diff --git a/deepmd/infer/model_devi.py b/deepmd/infer/model_devi.py index 2f8ea83335..7dc42589a0 100644 --- a/deepmd/infer/model_devi.py +++ b/deepmd/infer/model_devi.py @@ -150,7 +150,6 @@ def make_model_devi( Parameters ---------- - models: list A list of paths of models to use for making model deviation system: str diff --git a/deepmd/model/ener.py b/deepmd/model/ener.py index 0f4865ce7c..dec6ca66f4 100644 --- a/deepmd/model/ener.py +++ b/deepmd/model/ener.py @@ -10,6 +10,30 @@ from .model_stat import make_stat_input, merge_sys_stat class EnerModel() : + """Energy model. + + Parameters + ---------- + descrpt + Descriptor + fitting + Fitting net + type_map + Mapping atom type to the name (str) of the type. + For example `type_map[1]` gives the name of the type 1. + data_stat_nbatch + Number of frames used for data statistic + data_stat_protect + Protect parameter for atomic energy regression + use_srtab + The table for the short-range pairwise interaction added on top of DP. The table is a text data file with (N_t + 1) * N_t / 2 + 1 columes. The first colume is the distance between atoms. The second to the last columes are energies for pairs of certain types. For example we have two atom types, 0 and 1. The columes from 2nd to 4th are for 0-0, 0-1 and 1-1 correspondingly. + smin_alpha + The short-range tabulated interaction will be swithed according to the distance of the nearest neighbor. This distance is calculated by softmin. This parameter is the decaying parameter in the softmin. It is only required when `use_srtab` is provided. + sw_rmin + The lower boundary of the interpolation between short-range tabulated interaction and DP. It is only required when `use_srtab` is provided. + sw_rmin + The upper boundary of the interpolation between short-range tabulated interaction and DP. It is only required when `use_srtab` is provided. + """ model_type = 'ener' def __init__ ( @@ -27,28 +51,6 @@ def __init__ ( ) -> None: """ Constructor - - Parameters - ---------- - descrpt - Descriptor - fitting - Fitting net - type_map - Mapping atom type to the name (str) of the type. - For example `type_map[1]` gives the name of the type 1. - data_stat_nbatch - Number of frames used for data statistic - data_stat_protect - Protect parameter for atomic energy regression - use_srtab - The table for the short-range pairwise interaction added on top of DP. The table is a text data file with (N_t + 1) * N_t / 2 + 1 columes. The first colume is the distance between atoms. The second to the last columes are energies for pairs of certain types. For example we have two atom types, 0 and 1. The columes from 2nd to 4th are for 0-0, 0-1 and 1-1 correspondingly. - smin_alpha - The short-range tabulated interaction will be swithed according to the distance of the nearest neighbor. This distance is calculated by softmin. This parameter is the decaying parameter in the softmin. It is only required when `use_srtab` is provided. - sw_rmin - The lower boundary of the interpolation between short-range tabulated interaction and DP. It is only required when `use_srtab` is provided. - sw_rmin - The upper boundary of the interpolation between short-range tabulated interaction and DP. It is only required when `use_srtab` is provided. """ # descriptor self.descrpt = descrpt diff --git a/deepmd/model/tensor.py b/deepmd/model/tensor.py index 3b94dff601..5c996ec38d 100644 --- a/deepmd/model/tensor.py +++ b/deepmd/model/tensor.py @@ -9,6 +9,24 @@ from .model_stat import make_stat_input, merge_sys_stat class TensorModel() : + """Tensor model. + + Parameters + ---------- + tensor_name + Name of the tensor. + descrpt + Descriptor + fitting + Fitting net + type_map + Mapping atom type to the name (str) of the type. + For example `type_map[1]` gives the name of the type 1. + data_stat_nbatch + Number of frames used for data statistic + data_stat_protect + Protect parameter for atomic energy regression + """ def __init__ ( self, tensor_name : str, @@ -20,22 +38,6 @@ def __init__ ( )->None: """ Constructor - - Parameters - ---------- - tensor_name - Name of the tensor. - descrpt - Descriptor - fitting - Fitting net - type_map - Mapping atom type to the name (str) of the type. - For example `type_map[1]` gives the name of the type 1. - data_stat_nbatch - Number of frames used for data statistic - data_stat_protect - Protect parameter for atomic energy regression """ self.model_type = tensor_name # descriptor diff --git a/deepmd/utils/data.py b/deepmd/utils/data.py index 903190fb54..6c8b64a852 100644 --- a/deepmd/utils/data.py +++ b/deepmd/utils/data.py @@ -15,7 +15,23 @@ class DeepmdData() : """ Class for a data system. + It loads data from hard disk, and mantains the data as a `data_dict` + + Parameters + ---------- + sys_path + Path to the data system + set_prefix + Prefix for the directories of different sets + shuffle_test + If the test data are shuffled + type_map + Gives the name of different atom types + modifier + Data modifier that has the method `modify_data` + trn_all_set + Use all sets as training dataset. Otherwise, if the number of sets is more than 1, the last set is left for test. """ def __init__ (self, sys_path : str, @@ -26,21 +42,6 @@ def __init__ (self, trn_all_set : bool = False) : """ Constructor - - Parameters - ---------- - sys_path - Path to the data system - set_prefix - Prefix for the directories of different sets - shuffle_test - If the test data are shuffled - type_map - Gives the name of different atom types - modifier - Data modifier that has the method `modify_data` - trn_all_set - Use all sets as training dataset. Otherwise, if the number of sets is more than 1, the last set is left for test. """ self.dirs = glob.glob (os.path.join(sys_path, set_prefix + ".*")) self.dirs.sort() @@ -516,7 +517,10 @@ def _check_pbc(self, sys_path): class DataSets (object): """ - Outdated class for one data system. Not maintained anymore. + Outdated class for one data system. + + .. deprecated:: 2.0.0 + This class is not maintained any more. """ def __init__ (self, sys_path, diff --git a/deepmd/utils/data_system.py b/deepmd/utils/data_system.py index 8b84319eb2..c0bc6c1a86 100644 --- a/deepmd/utils/data_system.py +++ b/deepmd/utils/data_system.py @@ -16,6 +16,7 @@ class DeepmdDataSystem() : """ Class for manipulating many data systems. + It is implemented with the help of DeepmdData """ def __init__ (self, @@ -512,7 +513,10 @@ def _prob_sys_size_ext(self, keywords): class DataSystem (object) : """ - Outdated class for the data systems. Not maintained anymore. + Outdated class for the data systems. + + .. deprecated:: 2.0.0 + This class is not maintained any more. """ def __init__ (self, systems, diff --git a/deepmd/utils/learning_rate.py b/deepmd/utils/learning_rate.py index 572f317a92..8019e1b2bd 100644 --- a/deepmd/utils/learning_rate.py +++ b/deepmd/utils/learning_rate.py @@ -3,12 +3,29 @@ from deepmd.common import ClassArg class LearningRateExp (object) : - """ + r""" The exponentially decaying learning rate. - The learning rate at step t is given by + The learning rate at step :math:`t` is given by + + .. math:: + + \alpha(t) = \alpha_0 \lambda ^ { t / \tau } + + where :math:`\alpha` is the learning rate, :math:`\alpha_0` is the starting learning rate, + :math:`\lambda` is the decay rate, and :math:`\tau` is the decay steps. - lr(t) = start_lr * decay_rate ^ ( t / decay_steps ) + Parameters + ---------- + start_lr + Starting learning rate :math:`\alpha_0` + stop_lr + Stop learning rate :math:`\alpha_1` + decay_steps + Learning rate decay every this number of steps :math:`\tau` + decay_rate + The decay rate :math:`\lambda`. + If `stop_step` is provided in `build`, then it will be determined automatically and overwritten. """ def __init__ (self, start_lr : float, @@ -18,18 +35,6 @@ def __init__ (self, ) -> None : """ Constructor - - Parameters - ---------- - start_lr - Starting learning rate - stop_lr - Stop learning rate - decay_steps - Learning rate decay every this number of steps - decay_rate - The decay rate. - If `stop_step` is provided in `build`, then it will be determined automatically and overwritten. """ # args = ClassArg()\ # .add('decay_steps', int, must = False)\ diff --git a/deepmd/utils/neighbor_stat.py b/deepmd/utils/neighbor_stat.py index 9b867fe85b..fe582311cf 100644 --- a/deepmd/utils/neighbor_stat.py +++ b/deepmd/utils/neighbor_stat.py @@ -14,20 +14,21 @@ class NeighborStat(): """ Class for getting training data information. + It loads data from DeepmdData object, and measures the data info, including neareest nbor distance between atoms, max nbor size of atoms and the output data range of the environment matrix. + + Parameters + ---------- + ntypes + The num of atom types + rcut + The cut-off radius """ def __init__(self, ntypes : int, rcut: float) -> None: """ Constructor - - Parameters - ---------- - ntypes - The num of atom types - rcut - The cut-off radius """ self.rcut = rcut self.ntypes = ntypes diff --git a/deepmd/utils/pair_tab.py b/deepmd/utils/pair_tab.py index 4e22033a3b..a0063ac476 100644 --- a/deepmd/utils/pair_tab.py +++ b/deepmd/utils/pair_tab.py @@ -6,21 +6,23 @@ from scipy.interpolate import CubicSpline class PairTab (object): + """ + + Parameters + ---------- + filename + File name for the short-range tabulated potential. + The table is a text data file with (N_t + 1) * N_t / 2 + 1 columes. + The first colume is the distance between atoms. + The second to the last columes are energies for pairs of certain types. + For example we have two atom types, 0 and 1. + The columes from 2nd to 4th are for 0-0, 0-1 and 1-1 correspondingly. + """ def __init__(self, filename : str ) -> None: """ - Constructor - - Parameters - ---------- - filename - File name for the short-range tabulated potential. - The table is a text data file with (N_t + 1) * N_t / 2 + 1 columes. - The first colume is the distance between atoms. - The second to the last columes are energies for pairs of certain types. - For example we have two atom types, 0 and 1. - The columes from 2nd to 4th are for 0-0, 0-1 and 1-1 correspondingly. + Constructor """ self.reinit(filename) diff --git a/deepmd/utils/tabulate.py b/deepmd/utils/tabulate.py index f45a5243b5..719697dc87 100644 --- a/deepmd/utils/tabulate.py +++ b/deepmd/utils/tabulate.py @@ -16,9 +16,20 @@ class DPTabulate(): """ Class for tabulation. + Compress a model, which including tabulating the embedding-net. The table is composed of fifth-order polynomial coefficients and is assembled from two sub-tables. The first table takes the stride(parameter) as it\'s uniform stride, while the second table takes 10 * stride as it\s uniform stride The range of the first table is automatically detected by deepmd-kit, while the second table ranges from the first table\'s upper boundary(upper) to the extrapolate(parameter) * upper. + + Parameters + ---------- + model_file + The frozen model + type_one_side + Try to build N_types tables. Otherwise, building N_types^2 tables + exclude_types : List[List[int]] + The excluded pairs of types which have no interaction with each other. + For example, `[[0, 1]]` means no interaction between type 0 and type 1. """ def __init__(self, model_file : str, @@ -26,16 +37,6 @@ def __init__(self, exclude_types : List[List[int]] = []) -> None: """ Constructor - - Parameters - ---------- - model_file - The frozen model - type_one_side - Try to build N_types tables. Otherwise, building N_types^2 tables - exclude_types : List[List[int]] - The excluded pairs of types which have no interaction with each other. - For example, `[[0, 1]]` means no interaction between type 0 and type 1. """ self.model_file = model_file diff --git a/deepmd/utils/type_embed.py b/deepmd/utils/type_embed.py index e6a9f4834c..1bc09855ce 100644 --- a/deepmd/utils/type_embed.py +++ b/deepmd/utils/type_embed.py @@ -54,6 +54,26 @@ def embed_atom_type( class TypeEmbedNet(): + """ + + Parameters + ---------- + neuron : list[int] + Number of neurons in each hidden layers of the embedding net + resnet_dt + Time-step `dt` in the resnet construction: + y = x + dt * \phi (Wx + b) + activation_function + The activation function in the embedding net. Supported options are {0} + precision + The precision of the embedding net parameters. Supported options are {1} + trainable + If the weights of embedding net are trainable. + seed + Random seed for initializing the network parameters. + uniform_seed + Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed + """ @docstring_parameter(list_to_doc(ACTIVATION_FN_DICT.keys()), list_to_doc(PRECISION_DICT.keys())) def __init__( self, @@ -67,24 +87,6 @@ def __init__( )->None: """ Constructor - - Parameters - ---------- - neuron : list[int] - Number of neurons in each hidden layers of the embedding net - resnet_dt - Time-step `dt` in the resnet construction: - y = x + dt * \phi (Wx + b) - activation_function - The activation function in the embedding net. Supported options are {0} - precision - The precision of the embedding net parameters. Supported options are {1} - trainable - If the weights of embedding net are trainable. - seed - Random seed for initializing the network parameters. - uniform_seed - Only for the purpose of backward compatibility, retrieves the old behavior of using the random seed """ self.neuron = neuron self.seed = seed diff --git a/doc/conf.py b/doc/conf.py index f7515cb7b3..02610d172b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -165,6 +165,7 @@ def setup(app): "sphinx_rtd_theme", 'myst_parser', 'sphinx.ext.autosummary', + 'sphinx.ext.mathjax', 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx', 'numpydoc',