text improve, minor code / comment fixes

Author: fs446

doc/examples/wfs-referencing.ipynb

@@ -6,9 +6,12 @@
    "source": [
     "# 2.5D WFS Referencing Schemes\n",
     "\n",
-    "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."
+    "This notebook illustrates the usage of the SFS toolbox for the simulation of different 2.5D WFS referencing schemes.\n",
+    "A dedicated referencing scheme allows correct amplitude alongside a reference contour within the listening area.\n",
+    "For the theory please check\n",
+    "Ch 3.1-3.3 in <cite data-cite=\"Start1997\">(Start1997)</cite>,\n",
+    "Ch. 4.1.3 in <cite data-cite=\"Firtha2019\">(Firtha2019)</cite> and\n",
+    "<cite data-cite=\"Firtha2017\">(Firtha2017)</cite>."
    ]
   },
   {
@@ -35,11 +38,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "R = 1.5  # Radius of circular loudspeaker array, in m\n",
+    "R = 1.5  # radius [m] of circular loudspeaker array\n",
     "array = sfs.array.circular(N=64, R=R)  # with N loudspeakers\n",
     "grid = sfs.util.xyz_grid([-2, 2], [-2, 2], 0, spacing=0.02)\n",
     "\n",
-    "xs = -4, 0, 0  # point source on negative x-axis\n",
+    "xs = -4, 0, 0  # virtual point source on negative x-axis\n",
     "wavelength = 1 / 4  # m"
    ]
   },
@@ -74,8 +77,8 @@
    "outputs": [],
    "source": [
     "xs = sfs.util.asarray_of_rows(xs)\n",
-    "f = sfs.default.c / wavelength  # Hz\n",
-    "omega = 2 * np.pi * f  # rad/s\n",
+    "frequency = sfs.default.c / wavelength  # Hz\n",
+    "omega = 2 * np.pi * frequency  # rad/s\n",
     "normalize_gain = 4 * np.pi * np.linalg.norm(xs)"
    ]
   },
@@ -94,7 +97,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# reference contour is a straight line\n",
+    "# reference contour is a straight line on y-axis\n",
     "xref_line = 0\n",
     "# calc reference contour xref(x0), cf. [Firtha2017, eq. (24), (31), (52)]\n",
     "# this code assumes virtual point source on x-axis\n",
@@ -112,7 +115,10 @@
    "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 (orange-like dots) due to diffraction artifacts, which cannot really be compensated."
+    "The level plot includes a white 0 dB isobar curve.\n",
+    "The orange-like dots represent the stationary phase points at which amplitude correct synthesis is to be expected.\n",
+    "These dots shape the line reference contour.\n",
+    "Note that the isobar curve is not perfectly aligned along line reference contour due to diffraction artifacts."
    ]
   },
   {
@@ -121,7 +127,7 @@
    "source": [
     "### Circle as reference contour\n",
     "\n",
-    "This reference contour is a circle with origin xs and a radius, such that the origin is on this circle. This contour is obtained with straightforward vector calculus."
+    "This reference contour is a circle with its origin at xs and a radius |xs|. This contour is obtained with more straightforward vector calculus than the previous example."
    ]
   },
   {
@@ -130,7 +136,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# reference contour is a circle with origin xs\n",
+    "# reference contour is a circle with origin xs and radius |xs|\n",
     "xref_dist = np.linalg.norm(xs)\n",
     "# calc reference contour xref(x0), cf. [Firtha19, eq. (24), (31)]\n",
     "x0xs = array.x - xs\n",
@@ -148,7 +154,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The (complex-valued) difference between the two sound fields tells us about the difference of both approaches in terms of amplitude."
+    "The (complex-valued) difference between the two sound fields (linear vs. circular reference contour) tells us about the difference of both approaches in terms of amplitude."
    ]
   },
   {
@@ -166,7 +172,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 overlaid as contour plot."
+    "The (complex-valued) ratio between the two sound fields (linear vs. circular reference contour) 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."
    ]
   },
   {
@@ -195,11 +201,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 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",
+    "uses just a reference point xref, and more specifically this default point is the origin of the coordinate system.\n",
+    "This single point xref, the virtual source position xs and the loudspeaker array geometry together 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 exactly the same."
+    "In the example it looks similar to the line reference contour, but is in general not exactly the same."
    ]
   },
   {
@@ -212,21 +218,20 @@
     "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)"
+    "p_point = sound_field(d * normalize_gain, np.array([xref]*array.x.shape[0]),\n",
+    "                      selection, secondary_source, array, grid)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "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."
+    "The example below shows a point xref that does not meet any ray (gray lines) alongside the stationary phase holds with its corresponding loudspeaker.\n",
+    "The obtained level at the xref point however closely matches the desired reference level, because the white 0 dB isobar curve is very close to it.\n",
+    "So, in practice this single point reference scheme will likely work with sufficient precision once the position of xref is appropriately chosen (i.e. not too close, not too far, not to off-center etc.)."
    ]
   },
   {
@@ -241,10 +246,10 @@
     "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)\n",
+    "p_point = sound_field(d * normalize_gain, np.array([xref]*array.x.shape[0]),\n",
+    "                      selection, secondary_source, array, grid)\n",
     "\n",
-    "spa_unit_path = array.x - xs  # path along the stationary phase holds\n",
+    "spa_unit_path = array.x - xs  # path along which 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",
@@ -256,7 +261,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "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."
+    "A plane wave like sound field, e.g. by setting `xs = -100, 0, 0`, for all above examples reveals some further interesting implications of the different referencing schemes."
    ]
   }
  ],