driving function 2.5D point WFS WIP docu added

sfs/mono/drivingfunction.py

@@ -140,10 +140,62 @@ def wfs_25d_point(omega, x0, n0, xs, xref=[0, 0, 0], c=None, omalias=None):
 
 def wfs_25d_point_Unified_WIP(omega, x0, n0, xs, xref=[0, 0, 0], c=None,
                               omalias=None):
-    """Point source by 2.5-dimensional WFS.
+    r"""Driving function for 2.5-dimensional WFS of a virtual point source.
 
-	Eq. (2.137) from Schultz,F. (2016): https://doi.org/10.18453/rosdok_id00001765
-	"""
+    Parameters
+    ----------
+    omega : float
+        Angular frequency of point source.
+    x0 : (N, 3) array_like
+        Sequence of secondary source positions.
+    n0 : (N, 3) array_like
+        Sequence of normal vectors of secondary sources.
+    xs : (3,) array_like
+        Position of virtual point source.
+    xref : (3,) array_like, optional
+        Reference point xref or contour xref(x0) for amplitude correct synthesis.
+    c : float, optional
+        Speed of sound in m/s.
+    omalias : float, optional
+        Cut angular frequency for prefilter.
+
+    Returns
+    -------
+    d : (N,) numpy.ndarray
+        Complex weights of secondary sources.
+    selection : (N,) numpy.ndarray
+        Boolean array containing ``True`` or ``False`` depending on
+        whether the corresponding secondary source is "active" or not.
+    secondary_source_function : callable
+        A function that can be used to create the sound field of a
+        single secondary source.  See `sfs.mono.synthesize()`.
+
+    Notes
+    -----
+    Eq. (3.10), (3.11) Start, E.W. (1997): "Direct sound enhancement by wave
+    field synthesis", doctoral thesis, TU Delft
+
+    Eq. (2.137) from Schultz, F. (2016): https://doi.org/10.18453/rosdok_id00001765
+
+    .. math::
+
+        D(\x_0,\w) = \sqrt{8 \pi \, \i\wc}
+            \sqrt{\frac{|\x_\text{ref}-\x_0| \cdot
+            |\x_0-\x_\text{s}|}{|\x_\text{ref}-\x_0| + |\x_0-\x_\text{s}|}}
+            \scalarprod{\frac{\x_0-\x_\text{s}}{|\x_0-\x_\text{s}|}}{\n_0}
+            \frac{\e{-\i\wc |\x_0-\x_\text{s}|}}{4\pi\,|\x_0-\x_\text{s}|}
+
+    Examples
+    --------
+    .. plot::
+        :context: close-figs
+
+        d, selection, secondary_source = (
+            sfs.mono.drivingfunction.wfs_25d_point_Unified_WIP(
+                omega, array.x, array.n, xs))
+        plot(4*np.pi*np.linalg.norm(xs) * d, selection, secondary_source)
+
+    """
     x0 = util.asarray_of_rows(x0)
     n0 = util.asarray_of_rows(n0)
     xs = util.asarray_1d(xs)