Update wfs-referencing.ipynb

- added mgeier comments, such as bibtex entries also as cite text
- 2.5D WFS in headline
- bib Start1997 added for theory
- text mods to correct and improve the story
- correct normalizing for xref

Author: fs446

doc/examples/wfs-referencing.ipynb

@@ -4,9 +4,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# WFS Referencing Schemes\n",
+    "# 2.5D WFS Referencing Schemes\n",
     "\n",
-    "Illustrates the usage of the SFS toolbox for the simulation of different 2.5D WFS referencing schemes for contours within the listening area that exhibit amplitude correct synthesis, cf. Ch. 4.1.3 in <cite data-cite=\"Firtha2019\">[Firtha19]</cite> and <cite data-cite=\"Firtha2017\">(FFSS17)</cite>."
+    "Illustrates the usage of the SFS toolbox for the simulation of different 2.5D WFS referencing schemes.\n",
+    "This so called referencing controls contours alongside correct amplitude is obtained within the listening area,\n",
+    "cf. Ch 3.1-3.3 in <cite data-cite=\"Start1997\">(Start1997)</cite>, Ch. 4.1.3 in <cite data-cite=\"Firtha2019\">(Firtha2019)</cite> and <cite data-cite=\"Firtha2017\">(Firtha2017)</cite> for the theory."
    ]
   },
   {
@@ -83,7 +85,7 @@
    "source": [
     "### Line as reference contour\n",
     "\n",
-    "The reference contour is calculated according to <cite data-cite=\"Firtha2017\">(FFSS17)</cite> for a virtual point source on x-axis."
+    "The reference contour is calculated according to <cite data-cite=\"Firtha2017\">(Firtha2017)</cite> for a virtual point source on x-axis."
    ]
   },
   {
@@ -94,7 +96,7 @@
    "source": [
     "# reference contour is a straight line\n",
     "xref_line = 0\n",
-    "# calc reference contour xref(x0), cf. [FFSS17, eq. (24), (31), (52)]\n",
+    "# calc reference contour xref(x0), cf. [Firtha2017, eq. (24), (31), (52)]\n",
     "# this code assumes virtual point source on x-axis\n",
     "cosbeta = (array.n @ [1, 0, 0]).reshape(-1, 1)\n",
     "xref = array.x + \\\n",
@@ -110,7 +112,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The level plot includes a white 0 dB isobar curve, which nicely demonstrates the intended amplitude correct synthesis. Note that this isobar is not perfectly aligned along the intended reference contour (gray points) due to diffraction artifacts, which cannot really be compensated."
+    "The level plot includes a white 0 dB isobar curve, which nicely demonstrates the intended amplitude correct synthesis. Note that this isobar is not perfectly aligned along the intended reference contour (orange-like dots) due to diffraction artifacts, which cannot really be compensated."
    ]
   },
   {
@@ -130,7 +132,7 @@
    "source": [
     "# reference contour is a circle with origin xs\n",
     "xref_dist = np.linalg.norm(xs)\n",
-    "# calc reference contour xref(x0), cf. [Fir19, eq. (24), (31)]\n",
+    "# calc reference contour xref(x0), cf. [Firtha19, eq. (24), (31)]\n",
     "x0xs = array.x - xs\n",
     "x0xs_length = np.linalg.norm(x0xs, axis=1, keepdims=True)\n",
     "x0xs_unit = x0xs / x0xs_length  # unit vec\n",
@@ -164,7 +166,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The (complex-valued) ratio between the two sound fields tells us about the difference of both approaches in terms of dB. Note that again a white 0 dB isobar curve is added as contour plot."
+    "The (complex-valued) ratio between the two sound fields tells us about the difference of both approaches in terms of dB. Note, that again a white 0 dB isobar curve is overlaid as contour plot."
    ]
   },
   {
@@ -193,10 +195,11 @@
    "source": [
     "The default handling in\n",
     "`point_25d(omega, x0, n0, xs, xref=[0, 0, 0], c=None, omalias=None)`\n",
-    "uses just a reference point, and more specifically the origin, from which the reference contour is determined.\n",
+    "uses just a reference point xref, and more specifically this point is in the origin.\n",
+    "This single point, the virtual source position and the loudspeaker array then determine the reference contour without further user access to it.\n",
     "This handling is chosen due to convenience and practical relevance using circular loudspeaker arrays.\n",
     "The example below shows the resulting reference contour for the default case.\n",
-    "In the example it looks similar to the line referencing contour, but is in general not the same!"
+    "In the example it looks similar to the line referencing contour, but is in general not exactly the same."
    ]
   },
   {
@@ -206,6 +209,7 @@
    "outputs": [],
    "source": [
     "xref = [0, 0, 0]\n",
+    "normalize_gain = 4 * np.pi * np.linalg.norm(xs - np.array(xref))\n",
     "d, selection, secondary_source = sfs.fd.wfs.point_25d(\n",
     "    omega, array.x, array.n, xs, xref=xref)\n",
     "p_circ = sound_field(d * normalize_gain, np.array([xref]*array.x.shape[0]),\n",
@@ -216,9 +220,13 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The reference point handling might (and indeed mostly will) fail for other reference point locations, as can be seen below.\n",
-    "The 0 dB isobar curve does not meet the intended xref point.\n",
-    "Hence, be very careful with this referencing in non-default scenarios."
+    "From an academic viewpoint, the reference point handling in most cases will fail, as it is rather unlikely to set up the loudspeaker array and the virtual source and the reference point, such that the latter exactly fulfills the stationary phase requirement with one of the active loudspeakers.\n",
+    "\n",
+    "In the example above this worked, but only because it was intentionally chosen to do so.\n",
+    "\n",
+    "The example below shows the failing case. The point xref does not match any ray (gray lines) alongside the stationary phase holds with its corresponding loudspeaker. \n",
+    "The obtained reference level at xref point is however close to 0 dB, as the reference contour (white 0 dB isobar) is very very close to it.\n",
+    "So, in practice this handling will likely work with sufficient precision."
    ]
   },
   {
@@ -227,18 +235,28 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "xref = [-0.5, 0, 0]\n",
+    "xref = [0, 0.1175, 0]  # intentionally no stationary phase point\n",
+    "#  we don't forget to normalize the point source's amplitude\n",
+    "# to this new reference point:\n",
+    "normalize_gain = 4 * np.pi * np.linalg.norm(xs - np.array(xref))\n",
     "d, selection, secondary_source = sfs.fd.wfs.point_25d(\n",
     "    omega, array.x, array.n, xs, xref=xref)\n",
     "p_circ = sound_field(d * normalize_gain, np.array([xref]*array.x.shape[0]),\n",
-    "                     selection, secondary_source, array, grid)"
+    "                     selection, secondary_source, array, grid)\n",
+    "\n",
+    "spa_unit_path = array.x - xs  # path along the stationary phase holds\n",
+    "spa_unit_path /= np.linalg.norm(spa_unit_path, axis=1, keepdims=1)\n",
+    "spa = array.x + R * spa_unit_path\n",
+    "for spa1, spa2 in zip(array.x[selection, :2], spa[selection, :2]):\n",
+    "    plt.plot([spa1[0], spa2[0]],\n",
+    "             [spa1[1], spa2[1]], 'dimgray')"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "A plane wave like sound field, by setting `xs = -1000, 0, 0`, for all above examples reveals some more implications of the different referencing schemes."
+    "A plane wave like sound field, e.g. by setting `xs = -100, 0, 0`, for all above examples reveals some more implications of the different referencing schemes."
    ]
   }
  ],