docs(notebook): redraw shell-zoom diagram for clarity

Original diagram failed to communicate the message:
- The inner-zone circle was tiny and visually dominated by the ligand
  bulk inside the shell band, which made the diagram look like
  "shell band covers the whole ligand → no benefit."
- The "guaranteed bulk - skipped" label sat over the ligand body
  rather than inside the inner circle, suggesting the wrong region
  was being skipped.
- Did not show that ligand bulk inside the shell band is what gets
  SAS-rejected (different mechanism than the shell envelope itself).

Redrawn:
- Larger, clearly elongated ligand (R_max=15, R_min=5, ratio 3:1)
  at honest scale where R_min is meaningful.
- Ligand bulk shown in dark red INSIDE the shell band, with explicit
  "SAS-rejected within shell band" callout (separates the two
  rejection mechanisms).
- Inner zone is small, dark, and clearly inside the bulk — its
  callout explicitly says shell preemptively skips just that tiny
  deep-interior zone.
- Three green surface-point markers along short/diagonal/long axes
  with distance-from-COM labels — each visibly inside the shell
  band, demonstrating no surface direction is missed.

Author: siddharth7113

notebooks/maws/space_analysis.ipynb

@@ -542,104 +542,135 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "import math as _math\n",
+    "\n",
     "from matplotlib.patches import Circle, Ellipse\n",
     "\n",
-    "# Elongated ligand: long axis along x.\n",
-    "R_long = 6.0  # tip-of-blob distance from COM (R_max)\n",
-    "R_short = 2.0  # short-axis blob distance from COM (R_min)\n",
-    "buffer = 1.0  # smaller than real 5 Å for visual clarity\n",
-    "reach = 2.0\n",
+    "# Elongated ligand. Half-axes large enough that R_min is a meaningful\n",
+    "# fraction of R_max (~ a 3:1 cigar) — typical of an elongated protein.\n",
+    "R_long = 15.0  # x half-axis = R_max (long-axis surface distance)\n",
+    "R_short = 5.0  # y half-axis = R_min (short-axis surface distance)\n",
+    "buffer = 4.0  # close to the real 5 Å SHELL_INNER_BUFFER\n",
+    "reach = 4.0  # smaller than real 10 Å for a tight figure\n",
     "\n",
-    "inner = max(0.0, R_short - buffer)\n",
-    "outer = R_long + reach\n",
+    "inner = max(0.0, R_short - buffer)  # = 1.0\n",
+    "outer = R_long + reach  # = 19.0\n",
     "\n",
-    "fig, ax = plt.subplots(figsize=(10, 6))\n",
+    "fig, ax = plt.subplots(figsize=(12, 7))\n",
     "\n",
-    "# Outside (not sampled) — light blue background\n",
-    "ax.add_patch(Circle((0, 0), 12, facecolor=\"#e8f4ff\", edgecolor=\"none\", zorder=0))\n",
-    "# Shell band (sampled, SAS decides) — light green\n",
-    "ax.add_patch(\n",
-    "    Circle((0, 0), outer, facecolor=\"#d8f5d8\", edgecolor=\"green\", lw=2, zorder=1)\n",
-    ")\n",
-    "# Inner zone (guaranteed bulk, not sampled) — light gray\n",
-    "ax.add_patch(\n",
-    "    Circle(\n",
-    "        (0, 0), inner, facecolor=\"#cccccc\", edgecolor=\"orange\", lw=2, ls=\"--\", zorder=2\n",
-    "    )\n",
-    ")\n",
-    "# Ligand blob: elongated ellipse along x\n",
+    "# Background tiers (drawn back-to-front).\n",
+    "# Outside the envelope — solvent we don't sample.\n",
+    "ax.add_patch(Circle((0, 0), 24, facecolor=\"#e8f4ff\", edgecolor=\"none\"))\n",
+    "# Shell band [inner, outer] — sampling region.\n",
+    "ax.add_patch(Circle((0, 0), outer, facecolor=\"#d8f5d8\", edgecolor=\"green\", lw=2.5))\n",
+    "# Ligand bulk (will be SAS-rejected within the shell band).\n",
     "ax.add_patch(\n",
     "    Ellipse(\n",
     "        (0, 0),\n",
     "        2 * R_long,\n",
     "        2 * R_short,\n",
-    "        facecolor=\"dimgray\",\n",
-    "        edgecolor=\"black\",\n",
+    "        facecolor=\"#c98a8a\",\n",
+    "        edgecolor=\"darkred\",\n",
     "        lw=1.5,\n",
-    "        alpha=0.85,\n",
-    "        zorder=3,\n",
+    "        alpha=0.9,\n",
     "    )\n",
     ")\n",
-    "# COM\n",
-    "ax.plot(0, 0, marker=\"*\", color=\"magenta\", markersize=18, zorder=4)\n",
-    "\n",
-    "# Direction arrows showing where the surface is\n",
-    "# Short-axis surface point (top)\n",
-    "ax.plot(0, R_short, marker=\"o\", color=\"red\", markersize=8, zorder=5)\n",
-    "ax.annotate(\n",
-    "    \"surface point on short axis\\n(distance = R_min)\",\n",
-    "    xy=(0, R_short),\n",
-    "    xytext=(3, 4.5),\n",
-    "    arrowprops={\"arrowstyle\": \"->\", \"color\": \"red\", \"lw\": 1},\n",
-    "    fontsize=9,\n",
-    "    color=\"red\",\n",
-    ")\n",
-    "# Long-axis surface point (right)\n",
-    "ax.plot(R_long, 0, marker=\"o\", color=\"red\", markersize=8, zorder=5)\n",
-    "ax.annotate(\n",
-    "    \"surface point on long axis\\n(distance = R_max)\",\n",
-    "    xy=(R_long, 0),\n",
-    "    xytext=(R_long + 1.5, -3),\n",
-    "    arrowprops={\"arrowstyle\": \"->\", \"color\": \"red\", \"lw\": 1},\n",
-    "    fontsize=9,\n",
-    "    color=\"red\",\n",
+    "# Inner zone — preemptively skipped by the shell envelope.\n",
+    "ax.add_patch(\n",
+    "    Circle((0, 0), inner, facecolor=\"#5a5a5a\", edgecolor=\"orange\", lw=2, ls=\"--\")\n",
     ")\n",
+    "# COM marker.\n",
+    "ax.plot(0, 0, marker=\"*\", color=\"magenta\", markersize=18, zorder=10)\n",
+    "\n",
+    "\n",
+    "# --- Surface points at different directions on the ligand boundary ---\n",
+    "# Top: short axis. Right tip: long axis. Diagonal: in between.\n",
+    "def ellipse_point(theta):\n",
+    "    return (R_long * _math.cos(theta), R_short * _math.sin(theta))\n",
     "\n",
-    "# Annotations for the three regions\n",
+    "\n",
+    "surface_pts = [\n",
+    "    (ellipse_point(_math.pi / 2), \"short-axis surface\\n|r| = R_min\", (5, 9)),\n",
+    "    (ellipse_point(0), \"long-axis surface\\n|r| = R_max\", (R_long + 2, 4.5)),\n",
+    "    (ellipse_point(_math.pi / 4), \"diagonal surface\\n|r| ≈ 9.5\", (R_long + 2, -3)),\n",
+    "]\n",
+    "for (px, py), label, (lx, ly) in surface_pts:\n",
+    "    ax.plot(\n",
+    "        px,\n",
+    "        py,\n",
+    "        marker=\"o\",\n",
+    "        color=\"darkgreen\",\n",
+    "        markersize=10,\n",
+    "        zorder=11,\n",
+    "        markeredgecolor=\"white\",\n",
+    "        markeredgewidth=1.5,\n",
+    "    )\n",
+    "    ax.annotate(\n",
+    "        label,\n",
+    "        xy=(px, py),\n",
+    "        xytext=(lx, ly),\n",
+    "        fontsize=10,\n",
+    "        color=\"darkgreen\",\n",
+    "        arrowprops={\"arrowstyle\": \"->\", \"color\": \"darkgreen\", \"lw\": 1.2},\n",
+    "    )\n",
+    "\n",
+    "# --- Region legend boxes ---\n",
     "ax.text(\n",
     "    0,\n",
-    "    -1.2,\n",
-    "    \"guaranteed bulk\\n(< R_min − buffer)\\n← skipped →\",\n",
+    "    -10,\n",
+    "    \"shell band — sampled\\n(SAS rejects ligand bulk inside,\\n accepts surface layer)\",\n",
     "    ha=\"center\",\n",
-    "    va=\"top\",\n",
-    "    fontsize=9,\n",
-    "    color=\"black\",\n",
-    "    bbox={\"facecolor\": \"white\", \"edgecolor\": \"orange\", \"boxstyle\": \"round\"},\n",
+    "    fontsize=10,\n",
+    "    color=\"darkgreen\",\n",
+    "    bbox={\"facecolor\": \"white\", \"edgecolor\": \"darkgreen\", \"boxstyle\": \"round,pad=0.4\"},\n",
     ")\n",
     "ax.text(\n",
     "    0,\n",
-    "    outer + 0.3,\n",
-    "    \"shell band [inner, outer] — sampled; SAS rejects bulk-side, accepts surface-side\",\n",
+    "    22,\n",
+    "    \"outside envelope (|r| > R_max + reach) — not sampled\",\n",
+    "    ha=\"center\",\n",
+    "    fontsize=10,\n",
+    "    color=\"steelblue\",\n",
+    "    bbox={\"facecolor\": \"white\", \"edgecolor\": \"steelblue\", \"boxstyle\": \"round,pad=0.4\"},\n",
+    ")\n",
+    "ax.text(\n",
+    "    -12,\n",
+    "    13,\n",
+    "    \"ligand bulk\\n(SAS-rejected\\nwithin shell band)\",\n",
     "    ha=\"center\",\n",
     "    fontsize=9,\n",
-    "    color=\"green\",\n",
-    "    bbox={\"facecolor\": \"white\", \"edgecolor\": \"green\", \"boxstyle\": \"round\"},\n",
+    "    color=\"darkred\",\n",
+    "    bbox={\"facecolor\": \"white\", \"edgecolor\": \"darkred\", \"boxstyle\": \"round,pad=0.3\"},\n",
+    ")\n",
+    "ax.annotate(\n",
+    "    \"\",\n",
+    "    xy=(-6, 2.5),\n",
+    "    xytext=(-11, 11),\n",
+    "    arrowprops={\"arrowstyle\": \"->\", \"color\": \"darkred\", \"lw\": 1.2},\n",
     ")\n",
     "ax.text(\n",
-    "    0,\n",
-    "    11.2,\n",
-    "    \"outside the envelope (> R_max + reach) — not sampled\",\n",
+    "    8,\n",
+    "    13,\n",
+    "    \"shell skips this tiny\\ndeep-interior zone\\n(|r| < R_min − buffer)\",\n",
     "    ha=\"center\",\n",
     "    fontsize=9,\n",
-    "    color=\"steelblue\",\n",
-    "    bbox={\"facecolor\": \"white\", \"edgecolor\": \"steelblue\", \"boxstyle\": \"round\"},\n",
+    "    color=\"darkorange\",\n",
+    "    bbox={\"facecolor\": \"white\", \"edgecolor\": \"darkorange\", \"boxstyle\": \"round,pad=0.3\"},\n",
+    ")\n",
+    "ax.annotate(\n",
+    "    \"\",\n",
+    "    xy=(0.5, 0.5),\n",
+    "    xytext=(7, 11),\n",
+    "    arrowprops={\"arrowstyle\": \"->\", \"color\": \"darkorange\", \"lw\": 1.2},\n",
     ")\n",
     "\n",
-    "ax.set_xlim(-12, 12)\n",
-    "ax.set_ylim(-8, 12)\n",
+    "ax.set_xlim(-24, 24)\n",
+    "ax.set_ylim(-13, 24)\n",
     "ax.set_aspect(\"equal\")\n",
     "ax.set_title(\n",
-    "    \"Why Shell with `inner = R_min − buffer` doesn't miss surface points\", fontsize=11\n",
+    "    \"Shell-band coverage on an elongated ligand\\n\"\n",
+    "    \"(green dots = surface points; all sit inside the shell band)\",\n",
+    "    fontsize=12,\n",
     ")\n",
     "ax.grid(True, alpha=0.3)\n",
     "ax.axhline(0, color=\"lightgray\", lw=0.5)\n",