Merge pull request #1548 from Libensemble/examples/aposmm_nb_animation

Replace flashing live animation with clean post-run version

Author: shuds13

examples/tutorials/aposmm/aposmm_tutorial_notebook.ipynb

@@ -6,7 +6,7 @@
    "source": [
     "# Parallel Optimization with APOSMM\n",
     "\n",
-    "This tutorial demonstrates libEnsemble’s capability to identify multiple minima of simulation output using the built-in APOSMM (Asynchronously Parallel Optimization Solver for finding Multiple Minima) generator function (`gen_f`). In this tutorial, we’ll create a simple simulation function (`sim_f`) that defines a function with multiple minima, then write a libEnsemble calling script that imports APOSMM and parameterizes it to check for minima over a domain of outputs from our `sim_f`.\n",
+    "This tutorial demonstrates libEnsemble’s capability to identify multiple minima from simulation outputs using the built-in APOSMM (Asynchronously Parallel Optimization Solver for finding Multiple Minima) generator function (`gen_f`). In this tutorial, we’ll create a simple simulation function (`sim_f`) that defines a function with multiple minima, then write a libEnsemble calling script that imports APOSMM and parameterizes it to check for minima over a domain of outputs from our `sim_f`.\n",
     "\n",
     "Besides libEnsemble and NumPy, SciPy and mpmath are also required dependencies.\n",
     "\n",
@@ -43,7 +43,6 @@
    "outputs": [],
    "source": [
     "# Define our simulation function\n",
-    "\n",
     "import numpy as np\n",
     "\n",
     "\n",
@@ -122,9 +121,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This allocation function starts a single Persistent APOSMM routine and provides ``sim_f`` output for points requested by APOSMM. Points can be sampled points or points from local optimization runs.\n",
+    "This allocation function starts a single Persistent APOSMM generator to generate points (simulation input parameters), and returns the resulting values from each simulation (run in parallel). Points can be sampled points or points from the parallel local optimization runs.\n",
     "\n",
-    "APOSMM supports a wide variety of external optimizers. The following statements set optimizer settings to ``'scipy'`` to indicate to APOSMM which optimization method to use, and help prevent unnecessary imports or package installations:"
+    "APOSMM supports a wide variety of external optimizers. The following statement sets the optimizer settings to ``'scipy'`` to indicate to APOSMM which optimization method to use, so it is imported at global scope:"
    ]
   },
   {
@@ -142,6 +141,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "This script uses the dictionary interface to configure the run (the newer object interface is equally valid).\n",
     "Set up ``nworkers``, ``libE_specs``, ``sim_specs``, ``gen_specs``, and ``alloc_specs``:"
    ]
   },
@@ -226,28 +226,7 @@
    "source": [
     "## Run the Ensemble\n",
     "\n",
-    "Optionally run the next cell to set up a live graphic of the optimization progress during execution.\n",
-    "\n",
-    "**WARNING**: The graphic may flicker when the ensemble is running."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "# Configure to view live progress\n",
-    "from libensemble.tools.live_data.plot2n import Plot2N\n",
-    "\n",
-    "libE_specs[\"live_data\"] = Plot2N(plot_type=\"2d\")  # Alt: '3d'"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Finally, set `persis_info` (to provide random seeds to workers) and run the ensemble:"
+    "Finally, set persis_info (to provide random seeds to workers) and run the ensemble."
    ]
   },
   {
@@ -290,29 +269,110 @@
     "     \n",
     "The first six values correspond to the local minima for the Six-Hump Camel simulation function.\n",
     "\n",
-    "The 7th value is a repeat minimum, as APOSMM will continue to start local optimization runs.\n",
+    "The 7th value is a repeat minimum, as APOSMM will continue to start local optimization runs."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Viewing Animation\n",
     "\n",
-    "Please see the [API reference](https://libensemble.readthedocs.io/en/main/examples/aposmm.html) for more APOSMM configuration options and other information.\n",
+    "The following cell produces a 3D animation showing the random sampling points, \n",
+    "the points produced by the optimization runs, and the local Minima.\n",
     "\n",
+    "This may take up to about 30 seconds to produce the 3D animation, depending on system."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "import matplotlib.pyplot as plt\n",
+    "import matplotlib.animation as animation\n",
+    "from IPython.display import HTML\n",
+    "from matplotlib.lines import Line2D\n",
+    "\n",
+    "def animate_aposmm_3d(H, batch_size):\n",
+    "    x_vals = np.linspace(-2, 2, 50)\n",
+    "    y_vals = np.linspace(-1, 1.1, 50)\n",
+    "    X, Y = np.meshgrid(x_vals, y_vals)\n",
+    "    Z = np.array([six_hump_camel_func(np.array([x, y])) for x, y in zip(X.ravel(), Y.ravel())]).reshape(X.shape)\n",
+    "    fig = plt.figure(figsize=(10, 8))\n",
+    "    ax = fig.add_subplot(111, projection=\"3d\")\n",
+    "    ax.plot_surface(X, Y, Z, cmap=\"winter\", edgecolor='k', linewidth=0.1, antialiased=True, alpha=0.5) \n",
+    "    sc_normal = ax.scatter3D([], [], [], s=6, color=\"black\", marker=\"o\", label=\"Point\")\n",
+    "    sc_localp = ax.scatter3D([], [], [], s=40, color=\"red\", marker=\"^\", label=\"Optimization point\")\n",
+    "    custom_M_marker = Line2D([0], [0], linestyle='None', marker='$\\\\mathrm{M}$',\n",
+    "                             markersize=8, markerfacecolor='black', markeredgecolor='black', color='white')\n",
+    "    ax.legend([sc_normal, sc_localp, custom_M_marker], [\"Point\", \"Optimization point\", \"Local minimum\"],loc=\"upper left\")\n",
+    "    fig.tight_layout()\n",
+    "    annotations = []\n",
+    "\n",
+    "    def update(frame):\n",
+    "        for ann in annotations:\n",
+    "            ann.remove()\n",
+    "        annotations.clear()\n",
+    "        end = min((frame + 1) * batch_size, len(H))\n",
+    "        H_sub = H[:end]\n",
+    "        masks = [~H_sub[\"local_pt\"] & ~H_sub[\"local_min\"], H_sub[\"local_pt\"], H_sub[\"local_min\"]]\n",
+    "        (x_n, y_n, f_n), (x_lp, y_lp, f_lp), (x_lm, y_lm, f_lm) = [\n",
+    "            (H_sub[\"x\"][m, 0], H_sub[\"x\"][m, 1], H_sub[\"f\"][m]) for m in masks\n",
+    "        ]\n",
+    "        sc_normal._offsets3d = (x_n, y_n, f_n)\n",
+    "        sc_localp._offsets3d = (x_lp, y_lp, f_lp)\n",
+    "        for i in range(len(x_lm)):\n",
+    "            annotations.append(ax.text(x_lm[i], y_lm[i], f_lm[i], \"M\", color=\"white\", fontsize=12,\n",
+    "                bbox=dict(facecolor=\"black\", alpha=0.7, pad=2), zorder=999\n",
+    "            ))\n",
+    "        return sc_normal, sc_localp\n",
+    "    total_frames = (len(H) + batch_size - 1) // batch_size\n",
+    "    ani = animation.FuncAnimation(fig, update, frames=total_frames, interval=500, blit=False, repeat=False)\n",
+    "    plt.close(fig)\n",
+    "    return HTML(ani.to_jshtml())\n",
+    "\n",
+    "# Reduce batch_size for more refined steps\n",
+    "animate_aposmm_3d(H, batch_size=50)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
     "## Applications\n",
     "\n",
     "APOSMM is not limited to evaluating minima from pure Python simulation functions.\n",
     "Many common libEnsemble use-cases involve using libEnsemble's Executor to launch user\n",
     "applications with parameters requested by APOSMM, then evaluate their output using\n",
     "APOSMM, and repeat until minima are identified. A currently supported example\n",
-    "can be found in libEnsemble's [WarpX Scaling Test](https://github.com/Libensemble/libensemble/tree/main/libensemble/tests/scaling_tests/warpx)"
+    "can be found in libEnsemble's [WarpX Scaling Test](https://github.com/Libensemble/libensemble/tree/main/libensemble/tests/scaling_tests/warpx)\n",
+    "\n",
+    "Please see the [API reference](https://libensemble.readthedocs.io/en/main/examples/aposmm.html) for more APOSMM configuration options and other information."
    ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
    "name": "python3"
   },
   "language_info": {
-   "name": "python"
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.1"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 2
+ "nbformat_minor": 4
 }