Update linting and formatting

.github/workflows/linting.yml

@@ -47,7 +47,7 @@ jobs:
       - name: check docstrings
         run:  |
           pydocstyle --version
-          pydocstyle -e --count --convention=google
+          pydocstyle -e --count --convention=google --add-ignore=D400,D415,D200,D212,D205,D417,D107
       - name: black
         run:  |
           black --version

.pre-commit-config.yaml

@@ -1,4 +1,10 @@
 repos:
+  # Lint and format, isort, docstrings...
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: v0.0.270
+    hooks:
+      - id: ruff
+        args: [ --fix ]
   - repo: https://github.com/timothycrosley/isort
     rev: "5.12.0"
     hooks:
@@ -25,3 +31,10 @@ repos:
     hooks:
       - id: ruff
         args: [--fix]
+  # format docstring length:
+  - repo: https://github.com/PyCQA/docformatter
+    rev: v1.7.1
+    hooks:
+      - id: docformatter
+        additional_dependencies: [ tomli ]
+        args: [ --in-place,--config,./pyproject.toml ]

docs/source/conf.py

@@ -119,7 +119,9 @@
 
 
 def setup(app):
-    """Add configuration for MyST parser."""
+    """
+    Add configuration for MyST parser.
+    """
     app.add_config_value(
         "myst_parser_config",
         {

pyproject.toml

@@ -54,4 +54,11 @@ ignore = [
 
 [tool.ruff.per-file-ignores]
 "tests/*" = ["D102", "D103"]
-"docs/*" = ["D100"]
+"docs/*" = ["D100"]
+
+[tool.docformatter]
+recursive = true
+pre-summary-newline = true
+make-summary-multi-line = true
+wrap-summaries = 79
+wrap-descriptions = 79

pytaser/__init__.py

@@ -1,3 +1,4 @@
-"""PyTASER is a package for the generation, analysis and plotting of Transient Absorption Spectra of bulk
-materials.
+"""
+PyTASER is a package for the generation, analysis and plotting of Transient
+Absorption Spectra of bulk materials.
 """

pytaser/das_generator.py

@@ -1,4 +1,5 @@
-"""Created on Thu Aug  3 16:42:36 2023.
+"""
+Created on Thu Aug  3 16:42:36 2023.
 
 @author: lucasverga
 """
@@ -15,8 +16,9 @@
 
 
 class DASGenerator:
-    """Class to generate a DAS spectrum (decomposed and cumulative) from a bandstructure and
-    dos object.
+    """
+    Class to generate a DAS spectrum (decomposed and cumulative) from a
+    bandstructure and dos object.
 
     Args:
         new_system: Internal_Abs object from internal_abs_generator for the new system
@@ -48,7 +50,8 @@ def from_vasp_outputs(
         waveder_file_new_system=None,
         waveder_file_ref=None,
     ):
-        """Create a DASGenerator object from VASP output files.
+        """
+        Create a DASGenerator object from VASP output files.
 
         The user should provide the vasprun files for the new system and the reference system,
         followed by the waveder files for the new system and the reference system.
@@ -82,8 +85,9 @@ def from_mpid(
         mpr=None,
         mpr_ref=None,
     ):
-        """Import the desired bandstructure and dos objects from the legacy Materials Project
-        database.
+        """
+        Import the desired bandstructure and dos objects from the legacy
+        Materials Project database.
 
         Args:
             mpid: The Materials Project ID of the new system.

pytaser/generator.py

@@ -1,5 +1,6 @@
 """
-This module contains the TASGenerator class, which is used to generate TAS spectra.
+This module contains the TASGenerator class, which is used to generate TAS
+spectra.
 """
 
 import warnings
@@ -23,8 +24,7 @@
 
 def gaussian(x, width, center=0.0, height=None):
     """
-    Returns Gaussian curve(s) centred at point(s)
-    x, where x is array-like.
+    Returns Gaussian curve(s) centred at point(s) x, where x is array-like.
 
     Args:
         x: Input array.
@@ -40,8 +40,9 @@ def gaussian(x, width, center=0.0, height=None):
 
 
 def set_bandgap(bandstructure, dos, bandgap):
-    """Shifts all bands of a material to correct the DFT-underestimated bandgap according to
-    the input experimental bandgap.
+    """
+    Shifts all bands of a material to correct the DFT-underestimated bandgap
+    according to the input experimental bandgap.
 
     Args:
         bandstructure: PMG bandstructure object
@@ -90,7 +91,11 @@ def set_bandgap(bandstructure, dos, bandgap):
 
 
 def jdos(bs, f, i, occs, energies, kweights, gaussian_width, spin=Spin.up):
-    """Args:
+    """
+    Obtains the cumulative JDOS value for a specific i->f transition, with
+    consideration of partial occupancy and spin polarisation.
+
+    Args:
         bs: bandstructure object
         f: final band
         i: initial band
@@ -118,7 +123,9 @@ def jdos(bs, f, i, occs, energies, kweights, gaussian_width, spin=Spin.up):
 
 
 def _calculate_oscillator_strength(args):
-    """Calculates the oscillator strength of a single band-band transition."""
+    """
+    Calculates the oscillator strength of a single band-band transition.
+    """
     if len(args) == 9:  # shared memory arrays
         ib, jb, ik, rspin, spin, sigma, nedos, deltae, ismear = args
 
@@ -190,7 +197,9 @@ def get_nonzero_band_transitions(
     max_band,
     nk,
 ):
-    """Helper function to filter band transitions before (multi)processing."""
+    """
+    Helper function to filter band transitions before (multi)processing.
+    """
     ispin_idx = 0 if spin == Spin.up else 1
 
     ib_vals, jb_vals, ik_vals = np.meshgrid(
@@ -250,8 +259,9 @@ def occ_dependent_alpha(
     processes=None,
     energy_max=6,
 ):
-    """Calculate the expected optical absorption given the groundstate orbital derivatives and
-    eigenvalues (via dfc) and specified band occupancies.
+    """
+    Calculate the expected optical absorption given the groundstate orbital
+    derivatives and eigenvalues (via dfc) and specified band occupancies.
     Templated from pymatgen.io.vasp.optics.epsilon_imag().
 
     Args:
@@ -384,7 +394,8 @@ def occ_dependent_alpha(
 
 
 def get_cbm_vbm_index(bs):
-    """Args:
+    """
+    Args:
         bs: bandstructure object.
 
     Returns:
@@ -400,8 +411,8 @@ def get_cbm_vbm_index(bs):
 
 class TASGenerator:
     """
-    Class to generate a TAS spectrum (decomposed and cumulative) from
-    a bandstructure and dos object.
+    Class to generate a TAS spectrum (decomposed and cumulative) from a
+    bandstructure and dos object.
     """
 
     def __init__(self, bs, kpoint_weights, dos, dfc=None):
@@ -435,7 +446,8 @@ def __init__(self, bs, kpoint_weights, dos, dfc=None):
 
     @classmethod
     def from_vasp_outputs(cls, vasprun_file, waveder_file=None, bg=None):
-        """Create a TASGenerator object from VASP output files.
+        """
+        Create a TASGenerator object from VASP output files.
 
         Args:
             vasprun_file: Path to vasprun.xml file (to generate bandstructure object).
@@ -489,7 +501,8 @@ def from_vasp_outputs(cls, vasprun_file, waveder_file=None, bg=None):
         )
 
     def band_occupancies(self, temp, conc, dark=True):
-        """Gives band occupancies.
+        """
+        Gives band occupancies.
 
         Args:
             temp: Temperature of material we wish to investigate (affects the FD
@@ -548,12 +561,14 @@ def generate_tas(
         dark_occs=None,
         processes=None,
     ):
-        """Generates TAS spectra based on inputted occupancies, and a specified energy mesh. If the
-        TASGenerator has not been generated from VASP outputs (and thus does not have a dfc
-        attribute), then the output TAS is generated using the change in joint density of states
-        (JDOS) under illumination, with no consideration of oscillator strengths.
-        Otherwise, the output TAS is generated considering all contributions to the predicted TAS
-        spectrum.
+        """
+        Generates TAS spectra based on inputted occupancies, and a specified
+        energy mesh. If the TASGenerator has not been generated from VASP
+        outputs (and thus does not have a dfc attribute), then the output TAS
+        is generated using the change in joint density of states (JDOS) under
+        illumination, with no consideration of oscillator strengths. Otherwise,
+        the output TAS is generated considering all contributions to the
+        predicted TAS spectrum.
 
         Args:
             temp: Temperature (K) of material we wish to investigate (affects the FD distribution)
@@ -771,13 +786,13 @@ def generate_tas(
     @classmethod
     def from_mpid(cls, mpid, bg=None, api_key=None, mpr=None):
         """
-        Import the desired bandstructure and dos objects from the
-        legacy Materials Project database.
+        Import the desired bandstructure and dos objects from the legacy
+        Materials Project database.
 
         Args:
             mpid: The Materials Project ID of the desired material.
-            bg: The experimental bandgap (eV) of the material. If None, the band gap
-                of the MP calculation will be used.
+            bg: The experimental bandgap (eV) of the material. If None,
+                the band gap of the MP calculation will be used.
             api_key: The user's Materials Project API key.
             mpr: An MPRester object if already generated by user.
 

pytaser/internal_abs_generator.py

@@ -1,6 +1,7 @@
 """
-This module contains the Internal_Abs class, which is used to generate an absorption spectrum
-(decomposed and cumulative) from a bandstructure and dos object.
+This module contains the Internal_Abs class, which is used to generate an
+absorption spectrum (decomposed and cumulative) from a bandstructure and dos
+object.
 """
 
 import warnings
@@ -21,8 +22,8 @@
 
 class Internal_Abs:
     """
-    Class to generate an absorption spectrum (decomposed and cumulative)
-    from a bandstructure and dos object.
+    Class to generate an absorption spectrum (decomposed and cumulative) from a
+    bandstructure and dos object.
     """
 
     def __init__(self, bs, kpoint_weights, dos, dfc=None):
@@ -58,7 +59,9 @@ def __init__(self, bs, kpoint_weights, dos, dfc=None):
 
     @classmethod
     def internal_from_vasp(cls, vasprun_file, waveder_file=None):
-        """Create an Internal_Abs object from VASP output files."""
+        """
+        Create an Internal_Abs object from VASP output files.
+        """
         warnings.filterwarnings("ignore", category=UnknownPotcarWarning)
         warnings.filterwarnings("ignore", message="No POTCAR file with matching TITEL fields")
         vr = Vasprun(vasprun_file, parse_potcar_file=False, parse_projected_eigen=False)
@@ -90,7 +93,8 @@ def internal_from_vasp(cls, vasprun_file, waveder_file=None):
 
     @classmethod
     def internal_from_mpid(cls, mpid, bg=None, api_key=None, mpr=None):
-        """Create an Internal_Abs object from a Materials Project ID.
+        """
+        Create an Internal_Abs object from a Materials Project ID.
 
         Args:
             mpid: The Materials Project ID of the desired material.
@@ -113,7 +117,8 @@ def internal_from_mpid(cls, mpid, bg=None, api_key=None, mpr=None):
         return cls(mp_bs, kweights, mp_dos, None)
 
     def band_occupancies(self, temp):
-        """Gives band occupancies.
+        """
+        Gives band occupancies.
 
         Returns:
             A dictionary of {Spin: occ} for all bands across all k-points.
@@ -146,7 +151,9 @@ def generate_abs(
         occs=None,
         processes=None,
     ):
-        """Generates absorption spectra based on inputted occupancies, and a specified energy mesh.
+        """
+        Generates absorption spectra based on inputted occupancies, and a
+        specified energy mesh.
 
         Args:
             temp: Temperature (K) of material we wish to investigate (affects the FD distribution)

pytaser/kpoints.py

@@ -1,6 +1,8 @@
 """
-This module generates kpoint-weights for uniform-mesh non-magnetic materials. This is vital when using
-the Materials Project database to generate spectra in PyTASER.
+This module generates kpoint-weights for uniform-mesh non-magnetic materials.
+
+This is vital when using the Materials Project database to generate spectra in
+PyTASER.
 """
 
 import numpy as np
@@ -9,7 +11,9 @@
 
 
 def get_kpoint_weights(bandstructure, time_reversal=True, symprec=0.1):
-    """Function to calculate the kpoint_weights for non-magnetic materials (non-metals).
+    """
+    Function to calculate the kpoint_weights for non-magnetic materials (non-
+    metals).
 
     Args:
         bandstructure: PMG bandstructure object
@@ -40,7 +44,8 @@ def get_kpoint_weights(bandstructure, time_reversal=True, symprec=0.1):
 
 
 def get_kpoints_from_bandstructure(bandstructure, cartesian=False):
-    """Function to pull the kpoint from the bandstructure.
+    """
+    Function to pull the kpoint from the bandstructure.
 
     Args:
         bandstructure: PMG bandstructure object
@@ -64,7 +69,8 @@ def expand_kpoints(
     return_mapping=False,
     time_reversal=True,
 ):
-    """Function to expand the kpoints.
+    """
+    Function to expand the kpoints.
 
     Args:
         structure: PMG structure object
@@ -134,7 +140,8 @@ def expand_kpoints(
 
 
 def get_mesh_from_kpoint_diff(kpoints, ktol=1e-5):
-    """Function to get the uniform mesh from kpoint differences.
+    """
+    Function to get the uniform mesh from kpoint differences.
 
     Args:
         kpoints: uniform mesh kpoints array.
@@ -183,7 +190,8 @@ def get_reciprocal_point_group_operations(
     symprec: float = 0.01,
     time_reversal: bool = True,
 ):
-    """Function to get the reciprocal point group operations.
+    """
+    Function to get the reciprocal point group operations.
 
     Args:
         structure: PMG structure object