add level_contour(), revisit code, add reference point scheme

Author: fs446

doc/examples/wfs-referencing.ipynb

@@ -47,26 +47,22 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "def sound_field(\n",
-    "        d, xref, selection, secondary_source, array, grid):\n",
+    "def sound_field(d, xref, selection, secondary_source, array, grid):\n",
     "\n",
-    "    p = sfs.fd.synthesize(\n",
-    "        d, selection, array, secondary_source, grid=grid)\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",
-    "    sfs.plot2d.level(\n",
-    "        p, grid, vmax=6, vmin=-6, ax=ax_lvl, cmap='seismic',\n",
-    "        colorbar_kwargs={'label': 'dB'})\n",
+    "    sfs.plot2d.level(p, grid, vmax=6, vmin=-6, ax=ax_lvl,\n",
+    "                     colorbar_kwargs={'label': 'dB'})\n",
+    "    sfs.plot2d.level_contour(p, grid, levels=[0], colors='w', ax=ax_lvl)\n",
     "    for ax in ax_amp, ax_lvl:\n",
-    "        sfs.plot2d.loudspeakers(\n",
-    "            array.x, array.n, selection, size=0.125, ax=ax)\n",
-    "        ax.scatter(*xref[selection, :2].T, s=20, c='dimgray',\n",
+    "        sfs.plot2d.loudspeakers(array.x, array.n, selection, size=0.125, ax=ax)\n",
+    "    ax_lvl.scatter(*xref[selection, :2].T, marker='o', s=20, c='lightsalmon',\n",
     "                   zorder=3)\n",
-    "        ax.grid(True)\n",
     "    plt.tight_layout()\n",
-    "    return p\n"
+    "    return p"
    ]
   },
   {
@@ -75,7 +71,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "xs = sfs.util.asarray_of_rows((-4, 0, 0))\n",
+    "xs = sfs.util.asarray_of_rows(xs)\n",
     "f = sfs.default.c / wavelength  # Hz\n",
     "omega = 2 * np.pi * f  # rad/s\n",
     "normalize_gain = 4 * np.pi * np.linalg.norm(xs)"
@@ -106,9 +102,15 @@
     "\n",
     "d, selection, secondary_source = sfs.fd.wfs.point_25d(\n",
     "    omega, array.x, array.n, xs, xref=xref)\n",
-    "p_line = sound_field(\n",
-    "    d * normalize_gain, xref, selection,\n",
-    "    secondary_source, array, grid)"
+    "p_line = sound_field(d * normalize_gain, xref, selection, secondary_source,\n",
+    "                     array, grid)"
+   ]
+  },
+  {
+   "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."
    ]
   },
   {
@@ -136,9 +138,15 @@
     "\n",
     "d, selection, secondary_source = sfs.fd.wfs.point_25d(\n",
     "    omega, array.x, array.n, xs, xref=xref)\n",
-    "p_circ = sound_field(\n",
-    "    d * normalize_gain, xref, selection,\n",
-    "    secondary_source, array, grid)"
+    "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 tells us about the difference of both approaches in terms of amplitude."
    ]
   },
   {
@@ -147,30 +155,91 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# (complex-valued) ratio between the two soundfields tells\n",
-    "# us about the difference of both approaches in terms of dB\n",
-    "sfs.plot2d.level(\n",
-    "    p_line / p_circ, grid, vmax=1, vmin=-1, cmap='seismic',\n",
-    "    colorbar_kwargs={'label': 'dB'})\n",
+    "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.grid(True)\n",
     "plt.tight_layout()"
    ]
   },
+  {
+   "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."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "# (complex-valued) difference between the two soundfields tells\n",
-    "# us about the difference of both approaches in terms of magnitude\n",
-    "sfs.plot2d.amplitude(\n",
-    "    p_line - p_circ, grid, vmax=1e-1, vmin=-1e-1)\n",
+    "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.grid(True)\n",
     "plt.tight_layout()"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Reference point"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "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",
+    "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!"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "xref = [0, 0, 0]\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)"
+   ]
+  },
+  {
+   "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."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "xref = [-0.5, 0, 0]\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)"
+   ]
+  },
+  {
+   "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."
+   ]
   }
  ],
  "metadata": {