[WIP] Pre-Commit: Docformatter

.pre-commit-config.yaml

@@ -88,6 +88,16 @@ repos:
 #    exclude: ^(docs/.*|tools/.*)$
 # Alternatively: use autopep8?
 
+# Docstring formatting according to numpy style
+- repo: https://github.com/PyCQA/docformatter
+  rev: v1.5.1
+  hooks:
+    - id: docformatter
+      args: [
+        --in-place,
+        --config=./pyproject.toml,
+      ]
+
 # Python Formatting
 - repo: https://github.com/psf/black
   rev: 23.1.0 # Keep in sync with blacken-docs

lasy/laser.py

@@ -13,9 +13,8 @@
 
 
 class Laser:
-    """
-    Top-level class that can evaluate a laser profile on a grid,
-    propagate it, and write it to a file.
+    """Top-level class that can evaluate a laser profile on a grid, propagate
+    it, and write it to a file.
 
     Parameters
     ----------
@@ -116,8 +115,8 @@ def __init__(self, dim, lo, hi, npoints, profile, n_azimuthal_modes=1):
             self.field.field[...] = np.fft.ifft(envelope, axis=0)
 
     def normalize(self, value, kind="energy"):
-        """
-        Normalize the pulse either to the energy, peak field amplitude or peak intensity
+        """Normalize the pulse either to the energy, peak field amplitude or
+        peak intensity.
 
         Parameters
         ----------
@@ -138,8 +137,7 @@ def normalize(self, value, kind="energy"):
             raise ValueError(f'kind "{kind}" not recognized')
 
     def propagate(self, distance, nr_boundary=None, backend="NP"):
-        """
-        Propagate the laser pulse by the distance specified
+        """Propagate the laser pulse by the distance specified.
 
         Parameters
         ----------
@@ -247,8 +245,7 @@ def propagate(self, distance, nr_boundary=None, backend="NP"):
         self.field.field *= np.exp(1j * self.profile.omega0 * distance / scc.c)
 
     def write_to_file(self, file_prefix="laser", file_format="h5"):
-        """
-        Write the laser profile + metadata to file.
+        """Write the laser profile + metadata to file.
 
         Parameters
         ----------
@@ -268,8 +265,8 @@ def write_to_file(self, file_prefix="laser", file_format="h5"):
         )
 
     def get_full_field(self, theta=0, slice=0, slice_axis="x"):
-        """
-        Reconstruct the laser pulse with carrier frequency on the default grid
+        """Reconstruct the laser pulse with carrier frequency on the default
+        grid.
 
         Parameters
         ----------

lasy/profiles/combined_profile.py

@@ -2,8 +2,7 @@
 
 
 class CombinedLongitudinalTransverseProfile(Profile):
-    """
-    Class that combines a longitudinal and transverse laser profile
+    """Class that combines a longitudinal and transverse laser profile.
 
     The combined profile is defined as the product of the longitudinal and transverse
     profile.
@@ -53,8 +52,7 @@ def __init__(self, wavelength, pol, laser_energy, long_profile, trans_profile):
         self.trans_profile = trans_profile
 
     def evaluate(self, x, y, t):
-        """
-        Returns the envelope field of the laser
+        """Returns the envelope field of the laser.
 
         Parameters
         ----------

lasy/profiles/gaussian_profile.py

@@ -4,8 +4,7 @@
 
 
 class GaussianProfile(CombinedLongitudinalTransverseProfile):
-    """
-    Derived class for the analytic profile of a Gaussian laser pulse.
+    """Derived class for the analytic profile of a Gaussian laser pulse.
 
     More precisely, the electric field corresponds to:
 

lasy/profiles/longitudinal/gaussian_profile.py

@@ -4,8 +4,8 @@
 
 
 class GaussianLongitudinalProfile(LongitudinalProfile):
-    """
-    Derived class for the analytic profile of a longitudinally-Gaussian laser pulse.
+    """Derived class for the analytic profile of a longitudinally-Gaussian
+    laser pulse.
 
     More precisely, the longitudinal envelope
     (to be used in the :class:CombinedLongitudinalTransverseProfile class)
@@ -41,8 +41,7 @@ def __init__(self, wavelength, tau, t_peak, cep_phase=0):
         self.cep_phase = cep_phase
 
     def evaluate(self, t):
-        """
-        Returns the longitudinal envelope
+        """Returns the longitudinal envelope.
 
         Parameters
         ----------

lasy/profiles/longitudinal/longitudinal_profile.py

@@ -3,20 +3,19 @@
 
 
 class LongitudinalProfile(object):
-    """
-    Base class for longitudinal profiles of laser pulses.
+    """Base class for longitudinal profiles of laser pulses.
 
-    Any new longitudinal profile should inherit from this class, and define
-    its own `evaluate` method, using the same signature as the method below.
+    Any new longitudinal profile should inherit from this class, and
+    define its own `evaluate` method, using the same signature as the
+    method below.
     """
 
     def __init__(self, wavelength):
         self.lambda0 = wavelength
         self.omega0 = 2 * scc.pi * scc.c / self.lambda0
 
     def evaluate(self, t):
-        """
-        Returns the longitudinal envelope
+        """Returns the longitudinal envelope.
 
         Parameters
         ----------

lasy/profiles/profile.py

@@ -3,8 +3,7 @@
 
 
 class Profile(object):
-    """
-    Base class for all laser profiles.
+    """Base class for all laser profiles.
 
     Any new laser profile should inherit from this class, and define its own
     `evaluate` method, using the same signature as the method below.
@@ -24,7 +23,6 @@ class Profile(object):
         - Linear polarization in y: pol = (0,1)
         - Circular polarization: pol = (1,j)/sqrt(2) (j is the imaginary number)
         The polarization vector is normalized to have a unitary magnitude.
-
     """
 
     def __init__(self, wavelength, pol):
@@ -35,8 +33,7 @@ def __init__(self, wavelength, pol):
         self.omega0 = 2 * np.pi * c / self.lambda0
 
     def evaluate(self, x, y, t):
-        """
-        Returns the envelope field of the laser
+        """Returns the envelope field of the laser.
 
         Parameters
         ----------
@@ -68,8 +65,7 @@ def __rmul__(self, factor):
 
 
 class SummedProfile(Profile):
-    """
-    Base class for profiles that are the sum of several other profiles.
+    """Base class for profiles that are the sum of several other profiles.
 
     Profile class that represents the sum of multiple profiles.
 
@@ -109,8 +105,7 @@ def evaluate(self, x, y, t):
 
 
 class ScaledProfile(Profile):
-    """
-    Base class for profiles that are scaled by a factor.
+    """Base class for profiles that are scaled by a factor.
 
     Profile class that represents scaled profiles.
 

lasy/profiles/transverse/gaussian_profile.py

@@ -4,8 +4,7 @@
 
 
 class GaussianTransverseProfile(TransverseProfile):
-    """
-    Derived class for the analytic profile of a Gaussian laser pulse.
+    """Derived class for the analytic profile of a Gaussian laser pulse.
 
     More precisely, the transverse envelope
     (to be used in the :class:CombinedLongitudinalTransverseLaser class)
@@ -26,8 +25,7 @@ def __init__(self, w0):
         self.w0 = w0
 
     def _evaluate(self, x, y):
-        """
-        Returns the transverse envelope
+        """Returns the transverse envelope.
 
         Parameters
         ----------

lasy/profiles/transverse/hermite_gaussian_profile.py

@@ -5,9 +5,8 @@
 
 
 class HermiteGaussianTransverseProfile(TransverseProfile):
-    """
-    Derived class for an analytic profile of a high-order Gaussian
-    laser pulse expressed in the Hermite-Gaussian formalism.
+    """Derived class for an analytic profile of a high-order Gaussian laser
+    pulse expressed in the Hermite-Gaussian formalism.
 
     More precisely, the transverse envelope
     (to be used in the :class:CombinedLongitudinalTransverseLaser class)
@@ -38,8 +37,7 @@ def __init__(self, w0, n_x, n_y):
         self.n_y = n_y
 
     def _evaluate(self, x, y):
-        """
-        Returns the transverse envelope
+        """Returns the transverse envelope.
 
         Parameters
         ----------

lasy/profiles/transverse/laguerre_gaussian_profile.py

@@ -5,9 +5,8 @@
 
 
 class LaguerreGaussianTransverseProfile(TransverseProfile):
-    """
-    Derived class for an analytic profile of a high-order Gaussian
-    laser pulse expressed in the Laguerre-Gaussian formalism.
+    """Derived class for an analytic profile of a high-order Gaussian laser
+    pulse expressed in the Laguerre-Gaussian formalism.
 
     More precisely, the transverse envelope
     (to be used in the :class:CombinedLongitudinalTransverseLaser class)
@@ -41,8 +40,7 @@ def __init__(self, w0, p, m):
         self.m = m
 
     def _evaluate(self, x, y):
-        """
-        Returns the transverse envelope
+        """Returns the transverse envelope.
 
         Parameters
         ----------

lasy/profiles/transverse/super_gaussian_profile.py

@@ -4,8 +4,7 @@
 
 
 class SuperGaussianTransverseProfile(TransverseProfile):
-    """
-    Derived class for the analytic profile of a super-Gaussian laser pulse.
+    """Derived class for the analytic profile of a super-Gaussian laser pulse.
 
     More precisely, the transverse envelope corresponds to:
 
@@ -30,8 +29,7 @@ def __init__(self, w0, n_order):
         self.n_order = n_order
 
     def _evaluate(self, x, y):
-        """
-        Returns the transverse envelope
+        """Returns the transverse envelope.
 
         Parameters
         ----------

lasy/profiles/transverse/transverse_profile.py

@@ -2,11 +2,11 @@
 
 
 class TransverseProfile(object):
-    """
-    Base class for all transverse profiles.
+    """Base class for all transverse profiles.
 
-    Any new transverse profile should inherit from this class, and define its own
-    `evaluate` method, using the same signature as the method below.
+    Any new transverse profile should inherit from this class, and
+    define its own `evaluate` method, using the same signature as the
+    method below.
     """
 
     def __init__(self):
@@ -15,8 +15,7 @@ def __init__(self):
         self.y_offset = 0
 
     def _evaluate(self, x, y):
-        """
-        Returns the transverse envelope
+        """Returns the transverse envelope.
 
         Parameters
         ----------
@@ -35,9 +34,9 @@ def _evaluate(self, x, y):
         return np.zeros(x.shape, dtype="complex128")
 
     def evaluate(self, x, y):
-        """
-        Returns the transverse envelope modified by any spatial offsets.
-        This is the public facing evaluate method, it calls the _evaluate function of the derived class.
+        """Returns the transverse envelope modified by any spatial offsets.
+        This is the public facing evaluate method, it calls the _evaluate
+        function of the derived class.
 
         Parameters
         ----------
@@ -55,19 +54,15 @@ def evaluate(self, x, y):
         return self._evaluate(x + self.x_offset, y + self.y_offset)
 
     def set_offset(self, x_offset, y_offset):
-        """
-        Populates the x and y spatial offsets of the profile
-        The profile will be shifted by these according to
-        x+x_offset and y+y_offset prior to execution of
-        _evaluate
-
+        """Populates the x and y spatial offsets of the profile The profile
+        will be shifted by these according to x+x_offset and y+y_offset prior
+        to execution of _evaluate.
 
         Parameters
         ----------
         x_offset, y_offset: floats (m)
             Define spatial offsets to the beam. That is, how much
             to shift the beam by transversely
-
         """
 
         self.x_offset = x_offset

lasy/profiles/transverse/transverse_profile_from_data.py

@@ -5,16 +5,12 @@
 
 
 class TransverseProfileFromData(TransverseProfile):
-    """
-    Derived class for transverse laser profile created using
-    data from an experimental measurement or from the output
-    of another code.
-    """
+    """Derived class for transverse laser profile created using data from an
+    experimental measurement or from the output of another code."""
 
     def __init__(self, intensity_data, lo, hi):
-        """
-        Uses user supplied data to define the transverse profile
-        of the laser pulse.
+        """Uses user supplied data to define the transverse profile of the
+        laser pulse.
 
         The data must be supplied as a 2D numpy array of intensity
         values (for example an imported cameran image from an
@@ -60,8 +56,7 @@ def __init__(self, intensity_data, lo, hi):
         )
 
     def _evaluate(self, x, y):
-        """
-        Returns the transverse envelope
+        """Returns the transverse envelope.
 
         Parameters
         ----------

lasy/utils/box.py

@@ -2,9 +2,8 @@
 
 
 class Box:
-    """
-    Contain metadata on index and physical space for an array,
-    as well as handy methods.
+    """Contain metadata on index and physical space for an array, as well as
+    handy methods.
 
     Parameters
     ----------