More docstring formatting

shakenbreak/analysis.py

@@ -63,7 +63,7 @@ def _read_distortion_metadata(output_path: str) -> dict:
 
     Args:
         output_path (:obj:`str`):
-            Path to directory containing ``distortion_metadata.json`
+            Path to directory containing ``distortion_metadata.json``
             (Default: '.', current directory)
 
     Returns:
@@ -155,14 +155,14 @@ def get_gs_distortion(defect_energies_dict: dict) -> tuple:
     """
     Calculate energy difference between ``Unperturbed`` structure and
     lowest energy distortion. Returns the energy (in eV) and bond
-    distortion of the ground-state relative to ``Unperturbed`. If
+    distortion of the ground-state relative to ``Unperturbed``. If
     ``Unperturbed`` not present, returns (None, ground-state bond
     distortion).
 
     Args:
         defect_energies_dict (:obj:`dict`):
             Dictionary matching distortion to final energy, as
-            produced by ``get_energies()`` or ``_sort_data`.
+            produced by ``get_energies()`` or ``_sort_data``.
 
     Returns:
         :obj:`tuple`:
@@ -211,7 +211,7 @@ def _sort_data(energies_file: str, verbose: bool = True, min_e_diff: float = 0.0
         energies_file (:obj:`str`):
             Path to ``yaml`` file with bond distortions and final energies
             (in eV), obtained using the CLI command ``snb-parse`` or the
-            function ``parse_energies()`.
+            function ``parse_energies()``.
         verbose (:obj:`bool`):
             Whether to print information about energy lowering
             distortions, if found.
@@ -225,7 +225,7 @@ def _sort_data(energies_file: str, verbose: bool = True, min_e_diff: float = 0.0
     Returns:
         defect_energies_dict (:obj:`dict`):
             Dictionary matching distortion to final energy, as
-            produced by ``_organize_data()`
+            produced by ``_organize_data()``
         energy_diff (:obj:`float`):
             Energy difference between minimum energy structure and
             ``Unperturbed`` (in eV).
@@ -271,7 +271,7 @@ def analyse_defect_site(
     site_num: Optional[int] = None,
     vac_site: Optional[list] = None,
 ) -> tuple:
-    """
+    r"""
     Analyse coordination environment and bond distances to nearest
     neighbours of defect site.
 
@@ -290,7 +290,7 @@ def analyse_defect_site(
 
     Returns:
         :obj:`tuple`:
-            Tuple of coordination analysis and bond length DataFrames,
+            Tuple of coordination analysis and bond length ``DataFrame``\s,
             respectively.
     """
     # get defect site
@@ -338,24 +338,24 @@ def analyse_structure(
     structure: Structure,
     output_path: str = ".",
 ) -> tuple:
-    """
+    r"""
     Analyse the local distortion of the input defect structure. Requires
     access to the ``distortion_metadata.json`` file generated with
     ShakeNBreak to read info about defect site. If lacking this,
-    can alternatively use ``analyse_defect_site()`.
+    can alternatively use ``analyse_defect_site()``.
 
     Args:
         defect_species (:obj:`str`):
             Defect name including charge (e.g. 'vac_1_Cd_0')
         structure (:obj:`~pymatgen.core.structure.Structure`):
             Defect structure to analyse
         output_path (:obj:`str`):
-            Path to directory containing ``distortion_metadata.json`
+            Path to directory containing ``distortion_metadata.json``
             (Default: '.', current directory)
 
     Returns:
         :obj:`tuple`:
-            Tuple of coordination analysis and bond length DataFrames,
+            Tuple of coordination analysis and bond length ``DataFrame``\s,
             respectively.
     """
     defect_name_without_charge = defect_species.rsplit("_", 1)[0]
@@ -391,14 +391,14 @@ def get_structures(
     store them in a dictionary matching the bond distortion to the final
     structure. By default, will read the structures from the distortion
     subdirectories present in each defect folder. If only certain
-    distortions should be parsed, use the argument ``bond_distortions`
+    distortions should be parsed, use the argument ``bond_distortions``
     to specify them.
 
     Args:
         defect_species (:obj:`str`):
             Defect name including charge (e.g. 'vac_1_Cd_0')
         output_path (:obj:`str`):
-            Path to top-level directory containing ``defect_species`
+            Path to top-level directory containing ``defect_species``
             subdirectories.
             (Default: current directory.
         bond_distortions (:obj:`list`, optional):
@@ -489,7 +489,7 @@ def get_energies(
         defect_species (:obj:`str`):
             Defect name including charge (e.g. 'vac_1_Cd_0')
         output_path (:obj:`str`):
-            Path to top-level directory containing ``defect_species`
+            Path to top-level directory containing ``defect_species``
             subdirectories.
             (Default: current directory)
         distortion_increment (:obj:`float`):
@@ -581,8 +581,8 @@ def calculate_struct_comparison(
     """
     Calculate either the summed atomic displacement, with metric = "disp",
     or the maximum distance between matched atoms, with metric = "max_dist",
-    (default) between each distorted structure in ``defect_struct_dict`,
-    and either 'Unperturbed' or a specified structure (`ref_structure`).
+    (default) between each distorted structure in ``defect_struct_dict``,
+    and either 'Unperturbed' or a specified structure (``ref_structure``).
     For metric = "disp", atomic displacements below ``min_dist`` (in Å,
     default 0.1 Å) are considered noise and omitted from the sum,
     to reduce supercell size dependence.
@@ -704,7 +704,7 @@ def compare_structures(
 ) -> Union[None, pd.DataFrame]:
     """
     Compare final bond-distorted structures with either 'Unperturbed' or
-    a specified structure (`ref_structure`), and calculate the summed
+    a specified structure (``ref_structure``), and calculate the summed
     atomic displacement (in Å), and maximum distance between matched
     atomic sites (in Å).
 
@@ -713,7 +713,7 @@ def compare_structures(
             Dictionary mapping bond distortion to (relaxed) structure
         defect_energies_dict (:obj:`dict`):
             Dictionary matching distortion to final energy (eV), as
-            produced by ``_organize_data()`.
+            produced by ``_organize_data()``.
         ref_structure (:obj:`str`` or :obj:`float`` or :obj:`Structure`):
             Structure to use as a reference for comparison (to compute
             atomic displacements). Either as a key from
@@ -723,7 +723,7 @@ def compare_structures(
             (Default: "Unperturbed")
         units (:obj:`str`):
             Energy units label for outputs (either 'eV' or 'meV').
-            Should be the same as the units in ``defect_energies_dict`,
+            Should be the same as the units in ``defect_energies_dict``,
             as this does not modify the supplied values.
             (Default: "eV")
         min_dist (:obj:`float`):
@@ -1005,7 +1005,7 @@ def get_site_magnetizations(
             List of distortions to analyse (e.g. ['Unperturbed', 0.1,
             -0.2])
         output_path (:obj:`str`):
-            Path to top-level directory containing ``defect_species`
+            Path to top-level directory containing ``defect_species``
             subdirectories.
             (Default: current directory)
         threshold (:obj:`float`, optional):

shakenbreak/cli.py

@@ -242,7 +242,7 @@ def generate(
     defect_struct = Structure.from_file(defect)
     bulk_struct = Structure.from_file(bulk)
 
-    # Note that here the Defect.defect_structure is the defect ``supercell`
+    # Note that here the Defect.defect_structure is the defect ``supercell``
     # structure, not the defect ``primitive`` structure.
     defect_object = input.identify_defect(
         defect_structure=defect_struct,
@@ -926,7 +926,7 @@ def parse(defect, path, code, verbose):
 def analyse(defect, path, code, ref_struct, verbose):
     """
     Generate ``csv`` file mapping each distortion to its final energy (in eV) and its
-    mean displacement (in Angstrom and relative to ``ref_struct`).
+    mean displacement (in Angstrom and relative to ``ref_struct``).
 
     Can be run within a single defect folder, or in the top-level directory (either
     specifying ``defect`` or looping through all defect folders).
@@ -1406,10 +1406,10 @@ def groundstate(
 ):
     """
     Generate folders with the identified ground state structures. A folder (named
-    ``directory`) is created with the ground state structure (named
-    ``groundstate_filename`) for each defect present in the specified path (if ``path`` is
+    ``directory``) is created with the ground state structure (named
+    ``groundstate_filename``) for each defect present in the specified path (if ``path`` is
     the top-level directory) or for the current defect if run within a defect folder.
-    If the name of the structure/output files is not specified, the code assumes ``CONTCAR`
+    If the name of the structure/output files is not specified, the code assumes ``CONTCAR``
     (e.g. geometry optimisations performed with VASP). If using a different code,
     please specify the name of the structure/output files.
     """

shakenbreak/distortions.py

@@ -406,7 +406,7 @@ def rattle(
     """
     Given a pymatgen Structure object, apply random displacements to all atomic
     positions, with the displacement distances randomly drawn from a Gaussian
-    distribution of standard deviation ``stdev`.
+    distribution of standard deviation ``stdev``.
 
     Args:
         structure (:obj:`~pymatgen.core.structure.Structure`):
@@ -587,7 +587,7 @@ def _local_mc_rattle_displacements(
 
     Returns:
         :obj:`numpy.ndarray`:
-            atomic displacements (`Nx3`)
+            atomic displacements (Nx3)
     """
 
     def scale_stdev(disp, r_min, r):
@@ -685,7 +685,7 @@ def _generate_local_mc_rattled_structures(
 
     This process is repeated for each atom a number of times meaning
     the magnitude of the final displacements is not *directly*
-    connected to ``rattle_std`.
+    connected to ``rattle_std``.
 
     This function has been adapted from https://gitlab.com/materials-modeling/hiphive
 
@@ -721,7 +721,7 @@ def _generate_local_mc_rattled_structures(
         n_iter (:obj:`int`):
             Number of Monte Carlo cycles
         **kwargs:
-            Additional keyword arguments to be passed to ``mc_rattle`
+            Additional keyword arguments to be passed to ``mc_rattle``
 
     Returns:
         :obj:`list`:
@@ -758,7 +758,7 @@ def local_mc_rattle(
     """
     Given a pymatgen Structure object, apply random displacements to all atomic
     positions, with the displacement distances randomly drawn from a Gaussian
-    distribution of standard deviation ``stdev`. The random displacements
+    distribution of standard deviation ``stdev``. The random displacements
     tail off as we move away from the defect site.
 
     Args:

shakenbreak/energy_lowering_distortions.py

@@ -104,9 +104,9 @@ def _compare_distortion(
     **sm_kwargs,
 ) -> dict:
     """
-    Compare the ground state distortion (`gs_distortion`) to the other
-    favourable distortions stored in ``low_energy_defects`. If different,
-    add distortion as separate entry to ``low_energy_defects`.
+    Compare the ground state distortion (``gs_distortion``) to the other
+    favourable distortions stored in ``low_energy_defects``. If different,
+    add distortion as separate entry to ``low_energy_defects``.
     If same, store together with the other similar distortions.
 
     Args:
@@ -645,7 +645,7 @@ def compare_struct_to_distortions(
 ) -> tuple:
     """
     Compares the ground-state structure found for a certain defect charge
-    state with all relaxed bond-distorted structures for ``defect_species`,
+    state with all relaxed bond-distorted structures for ``defect_species``,
     to avoid redundant work (testing this distorted structure for other
     charge states when it has already been found for them).
 
@@ -683,7 +683,7 @@ def compare_struct_to_distortions(
             matching structure compared to its unperturbed reference, bond
             distortion of the matching structure). True if a match is found
             between the input structure and the relaxed bond-distorted
-            structures for ``defect_species`, False if no match, None if no
+            structures for ``defect_species``, False if no match, None if no
             converged structures found for defect_species.
     """
     try:
@@ -693,7 +693,7 @@ def compare_struct_to_distortions(
             code=code,
             structure_filename=structure_filename,
         )
-    except FileNotFoundError:  # catch exception raised by ``analysis.get_structures()`
+    except FileNotFoundError:  # catch exception raised by ``analysis.get_structures()``
         return None, None, None, None
     defect_energies_dict = analysis.get_energies(
         defect_species=defect_species, output_path=output_path, verbose=False
@@ -811,14 +811,14 @@ def write_retest_inputs(
     """
     Create folders with relaxation input files for testing the low-energy
     distorted defect structures found for other charge states of that
-    defect, as identified with ``get_energy_lowering_distortions()`.
+    defect, as identified with ``get_energy_lowering_distortions()``.
 
     Args:
         low_energy_defects (:obj:`dict`):
             Dictionary of defects for which bond distortion found an
             energy-lowering distortion which is missed with normal
             unperturbed relaxation), generated by
-            ``get_energy_lowering_distortions()`. Has the form
+            ``get_energy_lowering_distortions()``. Has the form
             {defect: [list of distortion dictionaries (with
             corresponding charge states, energy lowering, distortion
             factors, structures and charge states for which these
@@ -833,7 +833,7 @@ def write_retest_inputs(
             (case-insensitive).
             (Default: "vasp")
         input_filename (:obj:`str`):
-            Name of the code input file if different from ``ShakeNBreak`
+            Name of the code input file if different from ``ShakeNBreak``
             default. Only applies to CP2K, Quantum Espresso, CASTEP and
             FHI-aims. If not specified, ``ShakeNBreak`` default name is
             assumed, that is: for Quantum Espresso: "espresso.pwi",
@@ -1195,19 +1195,19 @@ def write_groundstate_structure(
     verbose: bool = False,
 ) -> None:
     """
-    Writes the groundstate structure of each defect (if ``all=True`, default)
+    Writes the groundstate structure of each defect (if ``all=True``, default)
     to the corresponding defect folder, with an optional name
     (default "groundstate_POSCAR"), to then run continuation calculations.
 
     Args:
         all (:obj:`bool`):
             Write groundstate structures for all defect folders in the
-            (top-level) directory, specified by ``output_path`. If False,
+            (top-level) directory, specified by ``output_path``. If False,
             ``output_path`` should be a single defect folder, for which the
             groundstate structure will be written.
         output_path (:obj:`str`):
             Path to top-level directory with your distorted defect
-            calculation folders (if ``all=True`, else path to single defect
+            calculation folders (if ``all=True``, else path to single defect
             folder)(need CONTCAR files for structure matching) and
             distortion_metadata.json.
             (Default: current directory = "./")