Some docstring reformatting

Author: mgeier

sfs/array.py

@@ -184,24 +184,24 @@ def rounded_edge(Nxy, Nr, dx, center=[0, 0, 0], n0=None):
 
     Parameters
     ----------
-    Nxy : integer
+    Nxy : int
         Number of secondary sources along x- and y-axis.
-    Nr : integer
-        Number of secondary sources in rounded edge. Radius of edge is
+    Nr : int
+        Number of secondary sources in rounded edge.  Radius of edge is
         adjusted to equdistant sampling along entire array.
-    center : triple of floats
+    center : (3,) array_like, optional
         Position of edge.
-    n0 : triple of floats
-        Normal vector of array. Default orientation is along xy-axis.
+    n0 : (3,) array_like, optional
+        Normal vector of array.  Default orientation is along xy-axis.
 
     Returns
     -------
-    positions : list of triplets of floats
-        positions of secondary sources
-    directions : list of triplets of floats
-        orientations (normal vectors) of secondary sources
-    weights : list of floats
-        integration weights of secondary sources
+    positions : (N, 3) numpy.ndarray
+        Positions of secondary sources
+    directions : (N, 3) numpy.ndarray
+        Orientations (normal vectors) of secondary sources
+    weights : (N,) numpy.ndarray
+        Integration weights of secondary sources
 
     Example
     -------
@@ -338,8 +338,9 @@ def cube(Nx, dx, Ny, dy, Nz, dz, center=[0, 0, 0], n0=None):
 def sphere_load(fname, radius, center=[0, 0, 0]):
     """Spherical secondary source distribution loaded from datafile.
 
-    ASCII Format (see MATLAB SFS Toolbox) with 4 numbers (3 position, 1 weight)
-    per secondary source located on the unit circle.
+    ASCII Format (see MATLAB SFS Toolbox) with 4 numbers (3 position, 1
+    weight) per secondary source located on the unit circle.
+
     """
     x0 = np.loadtxt(fname)
     weights = x0[:, 3]
@@ -352,8 +353,9 @@ def sphere_load(fname, radius, center=[0, 0, 0]):
 def load(fname, center=[0, 0, 0], n0=None):
     """Load secondary source positions from datafile.
 
-       Comma Seperated Values (CSV) format with 7 values
-       (3 positions, 3 directions, 1 weight) per secondary source
+    Comma Seperated Values (CSV) format with 7 values
+    (3 positions, 3 directions, 1 weight) per secondary source.
+
     """
     data = np.loadtxt(fname, delimiter=',')
     positions = data[:, [0, 1, 2]]
@@ -372,7 +374,8 @@ def load(fname, center=[0, 0, 0], n0=None):
 def weights_linear(positions):
     """Calculate loudspeaker weights for a linear array.
 
-       The linear array has to be parallel to the y-axis.
+    The linear array has to be parallel to the y-axis.
+
     """
     N = len(positions)
     weights = np.zeros(N)
@@ -388,9 +391,10 @@ def weights_linear(positions):
 def weights_closed(positions):
     """Calculate loudspeaker weights for a simply connected array.
 
-    The weights are calculated according to the midpoint rule
+    The weights are calculated according to the midpoint rule.
 
-    Note: The loudspeaker positions have to be ordered on the closed contour
+    Note: The loudspeaker positions have to be ordered on the closed
+    contour.
 
     """
     positions = np.asarray(positions)

sfs/defs.py

@@ -1,4 +1,4 @@
-"""Definition of constants"""
+"""Definition of constants."""
 
 # speed of sound
 c = 343

sfs/mono/drivingfunction.py

@@ -13,9 +13,7 @@ def wfs_2d_line(omega, x0, n0, xs, c=None):
 
     ::
 
-
-      D(x0,k) = j k (x0-xs) n0 / |x0-xs| * H1(k |x0-xs|)
-
+        D(x0,k) = j k (x0-xs) n0 / |x0-xs| * H1(k |x0-xs|)
 
     """
     x0 = np.asarray(x0)
@@ -32,9 +30,9 @@ def _wfs_point(omega, x0, n0, xs, c=None):
 
     ::
 
-                     (x0-xs) n0
-      D(x0,k) = j k ------------- e^(-j k |x0-xs|)
-                    |x0-xs|^(3/2)
+                       (x0-xs) n0
+        D(x0,k) = j k ------------- e^(-j k |x0-xs|)
+                      |x0-xs|^(3/2)
 
     """
     x0 = np.asarray(x0)
@@ -54,9 +52,9 @@ def wfs_25d_point(omega, x0, n0, xs, xref=[0, 0, 0], c=None, omalias=None):
 
     ::
 
-                  ____________   (x0-xs) n0
-      D(x0,k) = \|j k |xref-x0| ------------- e^(-j k |x0-xs|)
-                                |x0-xs|^(3/2)
+                    ____________   (x0-xs) n0
+        D(x0,k) = \|j k |xref-x0| ------------- e^(-j k |x0-xs|)
+                                  |x0-xs|^(3/2)
 
     """
     x0 = np.asarray(x0)
@@ -80,7 +78,7 @@ def _wfs_plane(omega, x0, n0, n=[0, 1, 0], c=None):
 
     Eq.(17) from [Spors et al, 2008]::
 
-      D(x0,k) =  j k n n0  e^(-j k n x0)
+        D(x0,k) =  j k n n0  e^(-j k n x0)
 
     """
     x0 = np.asarray(x0)
@@ -99,8 +97,8 @@ def wfs_25d_plane(omega, x0, n0, n=[0, 1, 0], xref=[0, 0, 0], c=None,
 
     ::
 
-                       ____________
-      D_2.5D(x0,w) = \|j k |xref-x0| n n0 e^(-j k n x0)
+                         ____________
+        D_2.5D(x0,w) = \|j k |xref-x0| n n0 e^(-j k n x0)
 
     """
     x0 = np.asarray(x0)
@@ -117,7 +115,7 @@ def wfs_25d_plane(omega, x0, n0, n=[0, 1, 0], xref=[0, 0, 0], c=None,
 
 
 def wfs_25d_preeq(omega, omalias, c):
-    """Preqeualization for 2.5D WFS"""
+    """Preqeualization for 2.5D WFS."""
     if omalias is None:
         return np.sqrt(1j * util.wavenumber(omega, c))
     else:
@@ -186,11 +184,11 @@ def nfchoa_25d_point(omega, x0, r0, xs, c=None):
 
     ::
 
-                              __      (2)
-                       1     \       h|m| (w/c r)
-         D(phi0,w) = -----   /__    ------------- e^(i m (phi0-phi))
-                      2pi r0 m=-N..N  (2)
-                                     h|m| (w/c r0)
+                             __      (2)
+                      1     \       h|m| (w/c r)
+        D(phi0,w) = -----   /__    ------------- e^(i m (phi0-phi))
+                     2pi r0 m=-N..N  (2)
+                                    h|m| (w/c r0)
 
     """
     x0 = np.asarray(x0)
@@ -218,6 +216,7 @@ def nfchoa_25d_plane(omega, x0, r0, n=[0, 1, 0], c=None):
         D_25D(phi0,w) = --  /__    ------------------ e^(i m (phi0-phi_pw) )
                         r0 m=-N..N       (2)
                                     w/c h|m| (w/c r0)
+
     """
     x0 = np.asarray(x0)
     k = util.wavenumber(omega, c)
@@ -238,11 +237,10 @@ def nfchoa_25d_plane(omega, x0, r0, n=[0, 1, 0], c=None):
 def sdm_2d_line(omega, x0, n0, xs, c=None):
     """Line source by two-dimensional SDM.
 
-        The secondary sources have to be located on the x-axis (y0=0).
-        Derived from [Spors 2009, 126th AES Convention], Eq.(9), Eq.(4)
-    ::
+    The secondary sources have to be located on the x-axis (y0=0).
+    Derived from [Spors 2009, 126th AES Convention], Eq.(9), Eq.(4)::
 
-      D(x0,k) =
+        D(x0,k) =
 
     """
     x0 = np.asarray(x0)
@@ -257,11 +255,10 @@ def sdm_2d_line(omega, x0, n0, xs, c=None):
 def sdm_2d_plane(omega, x0, n0, n=[0, 1, 0], c=None):
     """Plane wave by two-dimensional SDM.
 
-        The secondary sources have to be located on the x-axis (y0=0).
-        Derived from [Ahrens 2011, Springer], Eq.(3.73), Eq.(C.5), Eq.(C.11)
-    ::
+    The secondary sources have to be located on the x-axis (y0=0).
+    Derived from [Ahrens 2011, Springer], Eq.(3.73), Eq.(C.5), Eq.(C.11)::
 
-      D(x0,k) = kpw,y * e^(-j*kpw,x*x)
+        D(x0,k) = kpw,y * e^(-j*kpw,x*x)
 
     """
     x0 = np.asarray(x0)
@@ -274,11 +271,10 @@ def sdm_2d_plane(omega, x0, n0, n=[0, 1, 0], c=None):
 def sdm_25d_plane(omega, x0, n0, n=[0, 1, 0], xref=[0, 0, 0], c=None):
     """Plane wave by 2.5-dimensional SDM.
 
-        The secondary sources have to be located on the x-axis (y0=0).
-        Eq.(3.79) from [Ahrens 2011, Springer].
-    ::
+    The secondary sources have to be located on the x-axis (y0=0).
+    Eq.(3.79) from [Ahrens 2011, Springer]::
 
-      D_2.5D(x0,w) =
+        D_2.5D(x0,w) =
 
     """
     x0 = np.asarray(x0)
@@ -293,13 +289,10 @@ def sdm_25d_plane(omega, x0, n0, n=[0, 1, 0], xref=[0, 0, 0], c=None):
 def sdm_25d_point(omega, x0, n0, xs, xref=[0, 0, 0], c=None):
     """Point source by 2.5-dimensional SDM.
 
-        The secondary sources have to be located on the x-axis (y0=0).
-        Driving funcnction from [Spors 2010, 128th AES Covention], Eq.(24)
-
-    ::
-
-      D(x0,k) =
+    The secondary sources have to be located on the x-axis (y0=0).
+    Driving funcnction from [Spors 2010, 128th AES Covention], Eq.(24)::
 
+        D(x0,k) =
 
     """
     x0 = np.asarray(x0)

sfs/mono/soundfigure.py

@@ -9,7 +9,8 @@ def wfs_3d_pw(omega, x0, n0, figure, npw=[0, 0, 1], c=None):
     """Compute driving function for a 2D sound figure.
 
     Based on
-    [Hewani et al., The Synthesis of Sound Figures, MSSP, 2013]
+    [Helwani et al., The Synthesis of Sound Figures, MSSP, 2013]
+
     """
 
     x0 = np.asarray(x0)

sfs/mono/source.py

@@ -27,9 +27,9 @@ def point(omega, x0, n0, grid, c=None):
 
     ::
 
-                    1  e^(-j w/c |x-x0|)
-      G(x-x0, w) = --- -----------------
-                   4pi      |x-x0|
+                      1  e^(-j w/c |x-x0|)
+        G(x-x0, w) = --- -----------------
+                     4pi      |x-x0|
 
     Examples
     --------
@@ -65,28 +65,30 @@ def point_modal(omega, x0, n0, grid, L, N=None, deltan=0, c=None):
     ----------
     omega : float
         Frequency of source.
-    x0 : triple of floats
+    x0 : (3,) array_like
         Position of source.
-    n0 : triple of floats
-        Normal vector (direction) of source (only required for compatibility).
-    grid : list of numpy.ndarrays
+    n0 : (3,) array_like
+        Normal vector (direction) of source (only required for
+        compatibility).
+    grid : triple of numpy.ndarray
         The grid that is used for the sound field calculations.
-    L : triple of floats
+    L : (3,) array_like
         Dimensionons of the rectangular room.
-    N : triple of integers or integer
+    N : (3,) array_like or int, optional
         Combination of modal orders in the three-spatial dimensions to
-        calculate the sound field for or maximum order for all dimensions.
-        If not given, the maximum modal order is approximately determined and
-        the sound field is computed up to this maximum order.
-    deltan : float
+        calculate the sound field for or maximum order for all
+        dimensions.  If not given, the maximum modal order is
+        approximately determined and the sound field is computed up to
+        this maximum order.
+    deltan : float, optional
         Absorption coefficient of the walls.
-    c : float
+    c : float, optional
         Speed of sound.
 
     Returns
     -------
-    p : array of floats
-        Sound pressure at positions given by grid
+    numpy.ndarray
+        Sound pressure at positions given by `grid`.
 
     """
     k = util.wavenumber(omega, c)
@@ -134,8 +136,8 @@ def line(omega, x0, n0, grid, c=None):
 
     ::
 
-                         (2)
-      G(x-x0, w) = -j/4 H0  (w/c |x-x0|)
+                           (2)
+        G(x-x0, w) = -j/4 H0  (w/c |x-x0|)
 
     Examples
     --------
@@ -174,8 +176,8 @@ def line_dipole(omega, x0, n0, grid, c=None):
 
     ::
 
-                         (2)
-      G(x-x0, w) = jk/4 H1  (w/c |x-x0|) cos(phi)
+                           (2)
+        G(x-x0, w) = jk/4 H1  (w/c |x-x0|) cos(phi)
 
 
     """
@@ -196,7 +198,7 @@ def plane(omega, x0, n0, grid, c=None):
 
     ::
 
-      G(x, w) = e^(-i w/c n x)
+        G(x, w) = e^(-i w/c n x)
 
     Example
     -------
@@ -219,7 +221,7 @@ def plane(omega, x0, n0, grid, c=None):
 
 
 def _duplicate_zdirection(p, grid):
-    """If necessary, duplicate field in z-direction"""
+    """If necessary, duplicate field in z-direction."""
     gridshape = np.broadcast(*grid).shape
     if len(gridshape) > 2:
         return np.tile(p, [1, 1, gridshape[2]])

sfs/mono/synthesized.py

@@ -5,7 +5,7 @@
 
 
 def generic(omega, x0, n0, d, grid, c=None, source=point):
-    """Compute sound field for a generic driving function"""
+    """Compute sound field for a generic driving function."""
     d = np.squeeze(np.asarray(d))
     if len(d) != len(x0):
         raise ValueError("length mismatch")

sfs/plot.py

@@ -1,4 +1,4 @@
-"""Plot sound fields etc"""
+"""Plot sound fields etc."""
 
 import matplotlib.pyplot as plt
 from matplotlib.patches import Polygon
@@ -44,7 +44,7 @@ def virtualsource_2d(xs, ns=None, type='point', ax=None):
 
 
 def reference_2d(xref, size=0.1, ax=None):
-    """Draw reference/normalization point"""
+    """Draw reference/normalization point."""
     xref = np.asarray(xref)
     if ax is None:
         ax = plt.axes()
@@ -126,7 +126,7 @@ def loudspeaker_2d(x0, n0, a0=None, w=0.08, h=0.08, index=False, grid=None):
 
 
 def _visible_secondarysources_2d(x0, n0, grid):
-    """Determines secondary sources which lie within grid"""
+    """Determine secondary sources which lie within `grid`."""
     grid = util.asarray_of_arrays(grid)
     x, y = grid[:2]
     idx = np.where((x0[:, 0] > x.min()) & (x0[:, 0] < x.max()) &
@@ -137,8 +137,7 @@ def _visible_secondarysources_2d(x0, n0, grid):
 
 
 def loudspeaker_3d(x0, n0, a0=None, w=0.08, h=0.08):
-    """Plot positions and normal vectors of a 3D secondary source
-    distribution."""
+    """Plot positions and normals of a 3D secondary source distribution."""
     fig = plt.figure(figsize=(15, 15))
     ax = fig.add_subplot(111, projection='3d')
     ax.quiver(x0[:, 0], x0[:, 1], x0[:, 2], n0[:, 0],