follow the numpydoc style guide

.pre-commit-config.yaml

@@ -26,6 +26,12 @@ repos:
     hooks:
     - id: isort
     files: \.py$
+# numpydoc
+-   repo: https://github.com/Carreau/velin
+    rev: 0.0.12
+    hooks:
+    - id: velin
+      args: ["--write"]
 # Python inside docs
 -   repo: https://github.com/asottile/blacken-docs
     rev: 1.13.0

dpdata/amber/mask.py

@@ -10,12 +10,12 @@ def pick_by_amber_mask(param, maskstr, coords=None):
 
     Parameters
     ----------
-    param: str or parmed.Structure
-      filename of Amber param file or parmed.Structure
-    maskstr: str
-      Amber masks
-    coords: np.ndarray (optional)
-      frame coordinates, shape: N*3
+    param : str or parmed.Structure
+        filename of Amber param file or parmed.Structure
+    maskstr : str
+        Amber masks
+    coords : np.ndarray (optional)
+        frame coordinates, shape: N*3
     """
     parm = load_param_file(param)
     if coords is not None:

dpdata/amber/md.py

@@ -35,12 +35,12 @@ def read_amber_traj(
     Parameters
     ----------
     parm7_file, nc_file, mdfrc_file, mden_file, mdout_file:
-      filenames
-    use_element_symbols: None or list or str
-      If use_element_symbols is a list of atom indexes, these atoms will use element symbols
-      instead of amber types. For example, a ligand will use C, H, O, N, and so on
-      instead of h1, hc, o, os, and so on.
-      IF use_element_symbols is str, it will be considered as Amber mask.
+        filenames
+    use_element_symbols : None or list or str
+        If use_element_symbols is a list of atom indexes, these atoms will use element symbols
+        instead of amber types. For example, a ligand will use C, H, O, N, and so on
+        instead of h1, hc, o, os, and so on.
+        IF use_element_symbols is str, it will be considered as Amber mask.
     """
 
     flag_atom_type = False

dpdata/driver.py

@@ -23,9 +23,9 @@ class Driver(ABC):
     def register(key: str) -> Callable:
         """Register a driver plugin. Used as decorators.
 
-        Parameter
-        ---------
-        key: str
+        Parameters
+        ----------
+        key : str
             key of the plugin.
 
         Returns
@@ -45,9 +45,9 @@ def register(key: str) -> Callable:
     def get_driver(key: str) -> "Driver":
         """Get a driver plugin.
 
-        Parameter
-        ---------
-        key: str
+        Parameters
+        ----------
+        key : str
             key of the plugin.
 
         Returns
@@ -176,9 +176,9 @@ class Minimizer(ABC):
     def register(key: str) -> Callable:
         """Register a minimizer plugin. Used as decorators.
 
-        Parameter
-        ---------
-        key: str
+        Parameters
+        ----------
+        key : str
             key of the plugin.
 
         Returns
@@ -198,9 +198,9 @@ def register(key: str) -> Callable:
     def get_minimizer(key: str) -> "Minimizer":
         """Get a minimizer plugin.
 
-        Parameter
-        ---------
-        key: str
+        Parameters
+        ----------
+        key : str
             key of the plugin.
 
         Returns

dpdata/format.py

@@ -51,7 +51,7 @@ def from_system(self, file_name, **kwargs):
 
         Parameters
         ----------
-        file_name: str
+        file_name : str
             file name
 
         Returns
@@ -68,7 +68,7 @@ def to_system(self, data, *args, **kwargs):
 
         Parameters
         ----------
-        data: dict
+        data : dict
             system data
         """
         raise NotImplementedError(
@@ -107,7 +107,7 @@ def from_multi_systems(self, directory, **kwargs):
 
         Parameters
         ----------
-        directory: str
+        directory : str
             directory of system
 
         Returns

dpdata/md/rdf.py

@@ -9,15 +9,15 @@ def rdf(sys, sel_type=[None, None], max_r=5, nbins=100):
     ----------
     sys : System or LabeledSystem
         The dpdata system
-    sel_type: list
+    sel_type : list
         List of size 2. The first element specifies the type of the first atom,
         while the second element specifies the type of the second atom.
         Both elements can be ints or list of ints.
         If the element is None, all types are specified.
         Examples are sel_type = [0, 0], sel_type = [0, [0, 1]] or sel_type = [0, None]
-    max_r: float
+    max_r : float
         Maximal range of rdf calculation
-    nbins: int
+    nbins : int
         Number of bins for rdf calculation
 
     Returns

dpdata/plugin.py

@@ -19,9 +19,9 @@ def __init__(self):
     def register(self, key):
         """Register a plugin.
 
-        Parameter
-        ---------
-        key: str
+        Parameters
+        ----------
+        key : str
             Key of the plugin.
         """
 

dpdata/plugins/abacus.py

@@ -20,13 +20,13 @@ def to_system(self, data, file_name, frame_idx=0, **kwargs):
             The output file name
         frame_idx : int
             The index of the frame to dump
-        pp_file: list of string, optional
+        pp_file : list of string, optional
             List of pseudo potential files
-        numerical_orbital: list of string, optional
+        numerical_orbital : list of string, optional
             List of orbital files
-        mass: list of float, optional
+        mass : list of float, optional
             List of atomic masses
-        numerical_descriptor: str, optional
+        numerical_descriptor : str, optional
             numerical descriptor file
         """
 

dpdata/plugins/deepmd.py

@@ -50,13 +50,13 @@ def to_system(self, data, file_name, set_size=5000, prec=np.float64, **kwargs):
 
         Parameters
         ----------
-        data: dict
+        data : dict
             System data
         file_name : str
             The output folder
         set_size : int
             The size of each set.
-        prec: {numpy.float32, numpy.float64}
+        prec : {numpy.float32, numpy.float64}
             The floating point precision of the compressed data
         """
         dpdata.deepmd.comp.dump(file_name, data, set_size=set_size, comp_prec=prec)

dpdata/plugins/lammps.py

@@ -18,7 +18,7 @@ def to_system(self, data, file_name, frame_idx=0, **kwargs):
 
         Parameters
         ----------
-        data: dict
+        data : dict
             System data
         file_name : str
             The output file name

dpdata/system.py

@@ -397,7 +397,7 @@ def map_atom_types(self, type_map=None) -> np.ndarray:
 
         Parameters
         ----------
-        type_map :
+        type_map
             dict :  {"H":0,"O":1}
             or list  ["H","C","O","N"]
             The map between elements and index
@@ -673,7 +673,7 @@ def remove_pbc(self, protect_layer=9):
         Parameters
         ----------
         protect_layer : the protect layer between the atoms and the cell
-                        boundary
+            boundary
         """
         assert protect_layer >= 0, "the protect_layer should be no less than 0"
         remove_pbc(self.data, protect_layer)
@@ -726,7 +726,7 @@ def replicate(self, ncopy):
 
         Parameters
         ----------
-        ncopy :
+        ncopy
             list: [4,2,3]
             or tuple: (4,2,3,)
             make `ncopy[0]` copys in x dimensions,
@@ -846,7 +846,7 @@ def perturb(
             The cell of each frame is deformed by a symmetric matrix perturbed from identity.
             The perturbation to the diagonal part is subject to a uniform distribution in [-cell_pert_fraction, cell_pert_fraction),
             and the perturbation to the off-diagonal part is subject to a uniform distribution in [-0.5*cell_pert_fraction, 0.5*cell_pert_fraction).
-        atom_pert_distance: float
+        atom_pert_distance : float
             unit: Angstrom. A distance determines how far atoms will move.
             Atoms will move about `atom_pert_distance` in random direction.
             The distribution of the distance atoms move is determined by atom_pert_style
@@ -964,9 +964,9 @@ def pick_atom_idx(self, idx, nopbc=None):
 
         Parameters
         ----------
-        idx: int or list or slice
+        idx : int or list or slice
             atom index
-        nopbc: Boolen (default: None)
+        nopbc : Boolen (default: None)
             If nopbc is True or False, set nopbc
 
         Returns
@@ -1026,16 +1026,16 @@ def pick_by_amber_mask(self, param, maskstr, pass_coords=False, nopbc=None):
 
         Parameters
         ----------
-        param: str or parmed.Structure
-          filename of Amber param file or parmed.Structure
-        maskstr: str
-          Amber masks
-        pass_coords: Boolen (default: False)
+        param : str or parmed.Structure
+            filename of Amber param file or parmed.Structure
+        maskstr : str
+            Amber masks
+        pass_coords : Boolen (default: False)
             If pass_coords is true, the function will pass coordinates and
             return a MultiSystem. Otherwise, the result is
             coordinate-independent, and the function will return System or
             LabeledSystem.
-        nopbc: Boolen (default: None)
+        nopbc : Boolen (default: None)
             If nopbc is True or False, set nopbc
         """
         parm = load_param_file(param)
@@ -1221,11 +1221,11 @@ def correction(self, hl_sys):
 
         Parameters
         ----------
-        hl_sys: LabeledSystem
+        hl_sys : LabeledSystem
             high-level LabeledSystem
 
         Returns
-        ----------
+        -------
         corrected_sys: LabeledSystem
             Corrected LabeledSystem
         """
@@ -1248,7 +1248,7 @@ def __init__(self, *systems, type_map=None):
         """
         Parameters
         ----------
-        systems : System
+        *systems : System
             The systems contained
         type_map : list of str
             Maps atom type to name
@@ -1461,9 +1461,9 @@ def pick_atom_idx(self, idx, nopbc=None):
 
         Parameters
         ----------
-        idx: int or list or slice
+        idx : int or list or slice
             atom index
-        nopbc: Boolen (default: None)
+        nopbc : Boolen (default: None)
             If nopbc is True or False, set nopbc
 
         Returns

dpdata/unit.py

@@ -48,9 +48,9 @@ def __init__(self, unitA, unitB, check=True):
 
         Parameters
         ----------
-            unitA : str, unit to be converted
-            unitB : str, unit which unitA is converted to, i.e. `1 unitA = self._value unitB`
-            check : bool, whether to check unit validity
+        unitA : str, unit to be converted
+        unitB : str, unit which unitA is converted to, i.e. `1 unitA = self._value unitB`
+        check : bool, whether to check unit validity
 
         Examples
         --------
@@ -118,7 +118,7 @@ def __init__(self, unitA, unitB):
 
         Parameters
         ----------
-            unitA, unitB : str, in format of "energy_unit/length_unit"
+        unitA, unitB : str, in format of "energy_unit/length_unit"
 
         Examples
         --------
@@ -139,7 +139,7 @@ def __init__(self, unitA, unitB):
 
         Parameters
         ----------
-            unitA, unitB : str, in format of "energy_unit/length_unit^3", or in `["Pa", "pa", "kPa", "kpa", "bar", "kbar"]`
+        unitA, unitB : str, in format of "energy_unit/length_unit^3", or in `["Pa", "pa", "kPa", "kpa", "bar", "kbar"]`
 
         Examples
         --------

dpdata/xyz/xyz.py

@@ -8,9 +8,9 @@ def coord_to_xyz(coord: np.ndarray, types: list) -> str:
 
     Parameters
     ----------
-    coord: np.ndarray
+    coord : np.ndarray
         coordinates, Nx3 array
-    types: list
+    types : list
         list of types
 
     Returns