presentations/03-Streaming_MDAnalysis_Functionality-Woods.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# IMDClient package architecture\n",
    "\n",
    "### 1. Use imdclient outside of MDAnalysis\n",
    "### 2. Client is \"batteries included\"\n",
    "### 3. Strive for full MDAnalysis compatibility\n",
    "\n",
    "(Code cells to be used alongside `streaming-101/imd-mda/run.sh` and the simulation files in `streaming-101/imd-mda/sample_simulation`)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "![image](../streaming-101/imd-mda/imd-mda_1.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## IMDClient API Methods\n",
    "\n",
    "### 1. `get_imdsessioninfo()`\n",
    "### 2. `get_imdframe()`\n",
    "### 3. `stop()` *(handled by context manager)*"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "import imdclient\n",
    "\n",
    "with imdclient.IMDClient(\"localhost\", 8889, n_atoms=50786) as client:\n",
    "    info = client.get_imdsessioninfo()\n",
    "    print(info)\n",
    "\n",
    "    frame = client.get_imdframe()\n",
    "    print(f\"Simulation integration step: {frame.step}\")\n",
    "    print(f\"Simulation time (fs): {frame.time}\")\n",
    "    print(f\"First atom's position (angstroms): {frame.positions[0]}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Iterating through a trajectory\n",
    "\n",
    "### Call `get_imdframe()` until EOFError is raised\n",
    "### Slicing isn't possible"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "import imdclient\n",
    "\n",
    "with imdclient.IMDClient(\"localhost\", 8889, n_atoms=50786) as client:\n",
    "    while True:\n",
    "        try:\n",
    "            frame = client.get_imdframe()\n",
    "            # Do something with the frame\n",
    "        except EOFError:\n",
    "            break"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Options\n",
    "\n",
    "### Configurable timeout for high latency\n",
    "### Configurable buffer size for fast simulations"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "import imdclient\n",
    "\n",
    "client = imdclient.IMDClient(\"localhost\", 8889,\n",
    "                              n_atoms=50786, \n",
    "                              # Wait up to 10 seconds for a simulation frame\n",
    "                              timeout=10,\n",
    "                              # 1 MB\n",
    "                              buffer_size=1024 ** 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Software architecture\n",
    "\n",
    "![img2](../streaming-101/imd-mda/imd-mda_2.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "![img4](../streaming-101/imd-mda/imd-mda_3.jpg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Automatic pausing and resuming\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The position of the first atom is: [43.99073  29.392868 30.756462]\r"
     ]
    }
   ],
   "source": [
    "import imdclient\n",
    "\n",
    "# 2MB Buffer\n",
    "with imdclient.IMDClient(\"localhost\", 8889, n_atoms=50786, buffer_size=2 * 1024**2) as client:\n",
    "    while True:\n",
    "        try:\n",
    "            frame = client.get_imdframe()\n",
    "            print(f\"The position of the first atom is: {frame.positions[0]}\", end=\"\\r\")\n",
    "        except EOFError:\n",
    "            break"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Reader wraps client, handles its limitations\n",
    "\n",
    "### The imdclient can't be sliced, so the reader can't either\n",
    "### The imdclient only moves forward, so the reader does too"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "## API interactions\n",
    "\n",
    "![img4](../streaming-101/imd-mda/imd-mda_4.jpg)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "A stream is not a file!\n"
     ]
    }
   ],
   "source": [
    "from imdclient.IMD import IMDReader\n",
    "import MDAnalysis as mda\n",
    "\n",
    "u = mda.Universe(\"sample_simulation/imdgroup.gro\", \"imd://localhost:8889\")\n",
    "\n",
    "for ts in u.trajectory[:]:\n",
    "    pass\n",
    "\n",
    "try:\n",
    "    for ts in u.trajectory[:]:\n",
    "        pass\n",
    "except RuntimeError:\n",
    "    print(\"A stream is not a file!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Compatible ✅\n",
    "```python\n",
    "for ts in u.trajectory[::10]:\n",
    "    pass\n",
    "\n",
    "for ts in u.trajectory:\n",
    "    pass\n",
    "\n",
    "for ts in u.trajectory[:]:\n",
    "    pass\n",
    "```\n",
    "\n",
    "### Incompatible (raises `RuntimeError`) ❌\n",
    "\n",
    "```python\n",
    "for ts in u.trajectory[:10]:\n",
    "    pass\n",
    "\n",
    "for ts in u.trajectory[10:]:\n",
    "    pass\n",
    "\n",
    "for ts in u.trajectory[::-1]:\n",
    "    pass\n",
    "\n",
    "len(u.trajectory)\n",
    "\n",
    "u.trajectory.n_frames\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## The client works out of the box with some MDAnalysis analysis classes\n",
    "\n",
    "### Caveats:\n",
    "\n",
    "- The analysis class must be able to handle a trajectory without a known length\n",
    "- The analysis base class is patched automatically on importing imdclient"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "from imdclient.IMD import IMDReader\n",
    "import MDAnalysis as mda\n",
    "from MDAnalysis.analysis.rms import RMSF\n",
    "\n",
    "u = mda.Universe(\"sample_simulation/imdgroup.gro\", \"imd://localhost:8889\")\n",
    "\n",
    "imd_rmsf = RMSF(u.atoms).run()\n",
    "\n",
    "print(imd_rmsf.rmsf)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Running multiple analysis classes on the same stream\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "from imdclient.IMD import IMDReader\n",
    "import MDAnalysis as mda\n",
    "from MDAnalysis.analysis.rms import RMSF\n",
    "\n",
    "u = mda.Universe(\"sample_simulation/imdgroup.gro\", \"imd://localhost:8889\")\n",
    "\n",
    "r1 = RMSF(u.atoms)\n",
    "r2 = RMSF(u.atoms)\n",
    "imdclient.StackableAnalysis(u.trajectory, [r1, r2]).run()"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}