updates due to mgeier's review and comments

- we temporarily hard code normalize_rows from PR194 to see if it improves the code (IMO it does)
- sound_field and sfs.fd.synthesize arguments consistent
- some code comments are better as markdown text
- completely removed the p_line - p_circ difference plots, they don't add to the story, story now is more compelling: line, circ, point referencing
- improve default case for point referencing -> indeed use default function call
- some minor text changes to avoid misconceptions or make things more clear
- spa_uni_path plotting taken from mgeier proposal via mail

Author: fs446

doc/examples/wfs-referencing.ipynb

@@ -25,6 +25,21 @@
     "import sfs"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# we test the usage of\n",
+    "# https://github.com/sfstoolbox/sfs-python/pull/194\n",
+    "def normalize_rows(x):\n",
+    "    \"\"\"Normalize a list of vectors.\"\"\"\n",
+    "    x = sfs.util.asarray_of_rows(x)\n",
+    "    return x / np.linalg.norm(x, axis=1, keepdims=True)\n",
+    "# to be removed once this is merged"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -52,10 +67,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "def sound_field(d, xref, selection, secondary_source, array, grid):\n",
-    "\n",
+    "def sound_field(d, selection, array, secondary_source, grid, xref):\n",
     "    p = sfs.fd.synthesize(d, selection, array, secondary_source, grid=grid)\n",
-    "\n",
     "    fig, [ax_amp, ax_lvl] = plt.subplots(2, 1, sharex=True)\n",
     "    fig.set_figheight(fig.get_figwidth() * 3/2)\n",
     "    sfs.plot2d.amplitude(p, grid, vmax=2, vmin=-2, ax=ax_amp)\n",
@@ -88,7 +101,9 @@
    "source": [
     "### Line as reference contour\n",
     "\n",
-    "The reference contour is calculated according to <cite data-cite=\"Firtha2017\">(Firtha2017)</cite> for a virtual point source on x-axis."
+    "The reference contour is calculated according to eqs. (24), (31), (52) in <cite data-cite=\"Firtha2017\">(Firtha2017)</cite>. \n",
+    "The code assumes a virtual point source on x-axis.\n",
+    "The reference contour is a straight line on y-axis."
    ]
   },
   {
@@ -97,18 +112,15 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# 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",
     "cosbeta = (array.n @ [1, 0, 0]).reshape(-1, 1)\n",
     "xref = array.x + \\\n",
     "    (xs - array.x) * (xref_line + R * cosbeta) / (xs[0, 0] + R * cosbeta)\n",
     "\n",
     "d, selection, secondary_source = sfs.fd.wfs.point_25d(\n",
     "    omega, array.x, array.n, xs, xref=xref)\n",
-    "p_line = sound_field(d * normalize_gain, xref, selection, secondary_source,\n",
-    "                     array, grid)"
+    "p_line = sound_field(\n",
+    "    d * normalize_gain, selection, array, secondary_source, grid, xref)"
    ]
   },
   {
@@ -139,53 +151,11 @@
     "# 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",
-    "x0xs_length = np.linalg.norm(x0xs, axis=1, keepdims=True)\n",
-    "x0xs_unit = x0xs / x0xs_length  # unit vec\n",
-    "xref = xs + xref_dist * x0xs_unit\n",
-    "\n",
+    "xref = xs + xref_dist * normalize_rows(array.x - xs)\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, xref, selection, secondary_source,\n",
-    "                     array, grid)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "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."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "sfs.plot2d.amplitude(p_line - p_circ, grid, vmax=1e-1, vmin=-1e-1)\n",
-    "sfs.plot2d.loudspeakers(array.x, array.n, selection, size=0.125)\n",
-    "plt.tight_layout()"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "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."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "sfs.plot2d.level(p_line / p_circ, grid, vmax=1, vmin=-1,\n",
-    "                 colorbar_kwargs={'label': 'dB'})\n",
-    "sfs.plot2d.level_contour(p_line / p_circ, grid, levels=[0], colors='w')\n",
-    "sfs.plot2d.loudspeakers(array.x, array.n, selection, size=0.125)\n",
-    "plt.tight_layout()"
+    "   omega, array.x, array.n, xs, xref=xref)\n",
+    "p_circ = sound_field(\n",
+    "    d * normalize_gain, selection, array, secondary_source, grid, xref)"
    ]
   },
   {
@@ -203,9 +173,11 @@
     "`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 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",
+    "This handling is chosen due to convenience and practical relevance when working with circular loudspeaker arrays.\n",
+    "\n",
     "The example below shows the resulting reference contour for the default case.\n",
-    "In the example it looks similar to the line reference 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.\n",
+    "For example, please try a virtual point source that is far away from the array."
    ]
   },
   {
@@ -214,24 +186,24 @@
    "metadata": {},
    "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_point = sound_field(d * normalize_gain, np.array([xref]*array.x.shape[0]),\n",
-    "                      selection, secondary_source, array, grid)"
+    "    omega, array.x, array.n, xs)\n",
+    "p_point = sound_field(\n",
+    "    d * normalize_gain, selection, array, secondary_source,\n",
+    "    grid, np.array([[0, 0, 0]]*array.x.shape[0]))"
    ]
   },
   {
    "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",
-    "In the example above this worked, but only because it was intentionally chosen to do so.\n",
+    "In the example above this worked, but because it was intentionally chosen to do so.\n",
+    "\n",
+    "The example below shows a point xref that does not meet any ray (the gray lines in the level plot) alongside the stationary phase holds with its corresponding loudspeaker.\n",
     "\n",
-    "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.)."
+    "Hence, 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 from the active loudspeakers etc.)."
    ]
   },
   {
@@ -246,15 +218,19 @@
     "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_point = sound_field(d * normalize_gain, np.array([xref]*array.x.shape[0]),\n",
-    "                      selection, secondary_source, array, grid)\n",
+    "p_point = sound_field(\n",
+    "    d * normalize_gain, selection, array, secondary_source,\n",
+    "    grid, np.array([xref]*array.x.shape[0]))\n",
     "\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",
-    "    plt.plot([spa1[0], spa2[0]],\n",
-    "             [spa1[1], spa2[1]], 'dimgray')"
+    "spa_unit_path = normalize_rows(spa_unit_path)\n",
+    "spa = array.x + R * spa_unit_path  # length of all pathes is R\n",
+    "# such that the horizontal path exactly meets the origin\n",
+    "# of the coordinate system, this is very close to xref\n",
+    "plt.plot(\n",
+    "   np.vstack((array.x[selection, 0], spa[selection, 0])),\n",
+    "   np.vstack((array.x[selection, 1], spa[selection, 1])),\n",
+    "   color='dimgray');"
    ]
   },
   {