Lec21.RayActors.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "4f1e237d-109d-49ff-a675-f00cdff87838",
   "metadata": {},
   "source": [
    "## Lecture 21: Ray Actors\n",
    "\n",
    "Actors are stateful workers in Ray. The Ray docoumentation refers to these as \"service centers\".\n",
    "We will use actors to reimplement the Game of Life program (that we did in Dask). This will be a BSP-like program with two (implicit) barriers. They are implicit becaue there is no class/object that is the barrier. The barrier is achieved by waiting on all functions to complete in all Ray actors before submitting the next functions.  The pseuocode is something like:\n",
    "  1. Startup\n",
    "        * create a 2x2 array of remote actors and intialize local grids (8x8) plus overlapping ghost cells on each actor.\n",
    "            * place a glider in the (0,0) actor\n",
    "        * having created actors, initialize the neighbors (ray oids) in each actor.\n",
    "  2. Launch remote asynchronous functions on each actor to update the local gird\n",
    "  3. Await computation to complete (barrier)\n",
    "  4. Update ghost cells in neighbors (corners and sides)\n",
    "  5. Await updates to complete (barrier)\n",
    "  6. Iterate at 2. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c9a47a48-bf8f-45e1-8b38-834238b8c3f9",
   "metadata": {},
   "source": [
    "### Actors: The Code\n",
    "\n",
    "An actor is associated with a decorated `@ray.remote` class. When you define an actor, you get a runtime handle (object identifier) to the actor. That handle provides access to all methods and state within the class. \n",
    "\n",
    "All of the methods within the class are `remote()`. You should think of this as\n",
    "  * the actor is assigned to a compute resource \n",
    "  * function calls package arguments (and other needed state) and ships it to the remote resource\n",
    "\n",
    "When working with actors, you should try to have your remote calls be as minimal as possible and keep state within the actor at all times. I.e., try not to send a lot of state across actors.\n",
    "  \n",
    "So here is the class.  \n",
    "\n",
    "NB--I implemented this in PyCharm and moved it over. It's too complicated a piece of code for Jupyter. I needed a lot of debugging support.\n",
    "\n",
    "\n",
    "#### Define the actor class"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "58610070-4cd9-44db-b714-3af6ac215bab",
   "metadata": {},
   "outputs": [],
   "source": [
    "import ray\n",
    "import numpy as np\n",
    "\n",
    "@ray.remote\n",
    "class RoLSubGrid(object):\n",
    "    \"\"\"\n",
    "    class RoLSubGrid: Rules of life implemented in Ray.\n",
    "\n",
    "        This class updates local paritions and then pulls data from\n",
    "        adjacent partitions. It implements the ghost cell pattern with\n",
    "        one cell of overlap.\n",
    "\n",
    "        The class should be invoked with two barriers per iteration.\n",
    "            * update all local partitions\n",
    "            * barrier\n",
    "            * swap data between partitions\n",
    "            * barrier\n",
    "    \"\"\"\n",
    "    # Create an actor each with its own data\n",
    "    def __init__(self, dim, has_glider=False):\n",
    "        \"\"\"We actually have this hard wired for 8x8 cells in later functions.\n",
    "            This needs to be fixed, but won't be ready for class.\n",
    "        \"\"\"\n",
    "        self.local_grid = np.zeros(shape=[dim + 2, dim + 2], dtype=np.uint8)\n",
    "        if has_glider == True:\n",
    "            glider = np.array([[0, 1, 0], [0, 0, 1], [1, 1, 1]], dtype=np.uint8)\n",
    "            self.local_grid[1:glider.shape[0] + 1, 1:glider.shape[1] + 1] = glider\n",
    "\n",
    "    # neighbors for 2-d GoL gride\n",
    "    def set_neighbors(self, top, bottom, left, right, tl, tr, bl, br):\n",
    "        self.tl = tl\n",
    "        self.bl = bl\n",
    "        self.tr = tr\n",
    "        self.br = br\n",
    "        self.left = left\n",
    "        self.right = right\n",
    "        self.top = top\n",
    "        self.bottom = bottom\n",
    "\n",
    "    def get_neighbors(self):\n",
    "        return self.top, self.bottom, self.left, self.right, self.tl, self.bl, self.tr, self.br\n",
    "\n",
    "    def get_grid(self):\n",
    "        return self.local_grid\n",
    "\n",
    "    def step(self):\n",
    "        \"\"\"Evaluate the rules of life on a 2-d subarray.\n",
    "        The array should have an overlap of 1 cell in all dimension\n",
    "        and on the corner.\n",
    "\n",
    "        Args:\n",
    "\n",
    "        Returns:\n",
    "            outgrid (ndarray): Array updated by rules of life\n",
    "        \"\"\"\n",
    "        # we will receive an array with 1 dimension of padding\n",
    "        xdim, ydim = self.local_grid.shape\n",
    "\n",
    "        # output array to keep updates\n",
    "        outgrid = np.zeros(shape=self.local_grid.shape, dtype=self.local_grid.dtype)\n",
    "\n",
    "        # update only in center (non-overlapping) regaion\n",
    "        for x in range(1, xdim - 1):\n",
    "            for y in range(1, ydim - 1):\n",
    "                sum = self.local_grid[x - 1, y - 1] + self.local_grid[x, y - 1] + self.local_grid[x + 1, y - 1] + \\\n",
    "                      self.local_grid[x - 1, y] + self.local_grid[x + 1, y] + \\\n",
    "                      self.local_grid[x - 1, y + 1] + self.local_grid[x, y + 1] + self.local_grid[x + 1, y + 1]\n",
    "                # three neighbors birth\n",
    "                if (sum == 3):\n",
    "                    outgrid[x, y] = 1\n",
    "                # two neighbors no change\n",
    "                elif (sum == 2):\n",
    "                    outgrid[x, y] = self.local_grid[x, y]\n",
    "                    # <2 or >3 death\n",
    "                else:\n",
    "                    outgrid[x, y] = 0\n",
    "\n",
    "        self.local_grid = outgrid\n",
    "\n",
    "    def cut(self, xl, xh, yl, yh):\n",
    "        \"\"\"Return a slice of the local array\"\"\"\n",
    "        return self.local_grid[xl+1:xh+1, yl+1:yh+1]\n",
    "\n",
    "    def exchange(self):\n",
    "        \"\"\"Transfer data from neighbors. Corners and sides.\"\"\"\n",
    "        tloid = self.tl.cut.remote(7, 8, 7, 8)  # tl cuts br\n",
    "        troid = self.tr.cut.remote(7, 8, 0, 1)  # tr cuts bl\n",
    "        bloid = self.bl.cut.remote(0, 1, 7, 8)  # bl cuts tr\n",
    "        broid = self.br.cut.remote(0, 1, 0, 1)  # br cuts tl\n",
    "        toid = self.top.cut.remote(7, 8, 0, 8)  # top\n",
    "        boid = self.bottom.cut.remote(0, 1, 0, 8)  # bottom\n",
    "        loid = self.left.cut.remote(0, 8, 7, 8)  # left\n",
    "        roid = self.right.cut.remote(0, 8, 0, 1)  # right\n",
    "        \n",
    "        \n",
    "        #RBTODO -- implement this in a ray.wait pattern to be more efficient?\n",
    "\n",
    "        self.local_grid[0, 0] = ray.get(tloid)  # tl cuts br\n",
    "        self.local_grid[0, 9] = ray.get(troid)  # tr cuts bl\n",
    "        self.local_grid[9, 0] = ray.get(bloid)  # bl cuts tr\n",
    "        self.local_grid[9, 9] = ray.get(broid)  # br cuts tl\n",
    "        self.local_grid[0:1, 1:9] = ray.get(toid)  # top\n",
    "        self.local_grid[9:10, 1:9] = ray.get(boid)  # bottom\n",
    "        self.local_grid[1:9, 0:1] = ray.get(loid)  # left\n",
    "        self.local_grid[1:9, 9:10] = ray.get(roid)  # right"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c517a0ce-852d-436c-b478-1df8e7d5d8e1",
   "metadata": {},
   "source": [
    "You should recognize the `exchange` function as implementing the ghost cell pattern from Activity 4a in which data are exchanged from the boundaries of adjacent cells. The `cut` function is a remote invocation that returns data from the object. This is a _pull_ pattern in which data are pulled from a remote object.\n",
    "\n",
    "<img src=\"https://www.olcf.ornl.gov/wp-content/uploads/2013/09/domainWithGhostZones.png\" width=256/>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "664d2a8c-1338-41d5-b7d9-beceeed8bbd1",
   "metadata": {},
   "source": [
    "### Driver script \n",
    "\n",
    "Create and manipulate actors to run the simulation. Let's setup a cluster and define actors."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "ed68561b-7473-4d3c-bd19-5460f8120fc4",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "2022-11-28 18:10:15,003\tINFO worker.py:1528 -- Started a local Ray instance.\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(0,0) Actor(RoLSubGrid, b00b1e32f38a51a11c90ed7c01000000)\n",
      "(0,1) Actor(RoLSubGrid, 43fa70966218a937efc2c8d001000000)\n",
      "(1,0) Actor(RoLSubGrid, b661b8d61131dcc87871046501000000)\n",
      "(1,1) Actor(RoLSubGrid, 58b8eee9b7e2ffa360bfb41b01000000)\n",
      "(Actor(RoLSubGrid, b661b8d61131dcc87871046501000000), Actor(RoLSubGrid, b661b8d61131dcc87871046501000000), Actor(RoLSubGrid, 43fa70966218a937efc2c8d001000000), Actor(RoLSubGrid, 43fa70966218a937efc2c8d001000000), Actor(RoLSubGrid, 58b8eee9b7e2ffa360bfb41b01000000), Actor(RoLSubGrid, 58b8eee9b7e2ffa360bfb41b01000000), Actor(RoLSubGrid, 58b8eee9b7e2ffa360bfb41b01000000), Actor(RoLSubGrid, 58b8eee9b7e2ffa360bfb41b01000000))\n",
      "(Actor(RoLSubGrid, 58b8eee9b7e2ffa360bfb41b01000000), Actor(RoLSubGrid, 58b8eee9b7e2ffa360bfb41b01000000), Actor(RoLSubGrid, b00b1e32f38a51a11c90ed7c01000000), Actor(RoLSubGrid, b00b1e32f38a51a11c90ed7c01000000), Actor(RoLSubGrid, b661b8d61131dcc87871046501000000), Actor(RoLSubGrid, b661b8d61131dcc87871046501000000), Actor(RoLSubGrid, b661b8d61131dcc87871046501000000), Actor(RoLSubGrid, b661b8d61131dcc87871046501000000))\n",
      "(Actor(RoLSubGrid, b00b1e32f38a51a11c90ed7c01000000), Actor(RoLSubGrid, b00b1e32f38a51a11c90ed7c01000000), Actor(RoLSubGrid, 58b8eee9b7e2ffa360bfb41b01000000), Actor(RoLSubGrid, 58b8eee9b7e2ffa360bfb41b01000000), Actor(RoLSubGrid, 43fa70966218a937efc2c8d001000000), Actor(RoLSubGrid, 43fa70966218a937efc2c8d001000000), Actor(RoLSubGrid, 43fa70966218a937efc2c8d001000000), Actor(RoLSubGrid, 43fa70966218a937efc2c8d001000000))\n",
      "(Actor(RoLSubGrid, 43fa70966218a937efc2c8d001000000), Actor(RoLSubGrid, 43fa70966218a937efc2c8d001000000), Actor(RoLSubGrid, b661b8d61131dcc87871046501000000), Actor(RoLSubGrid, b661b8d61131dcc87871046501000000), Actor(RoLSubGrid, b00b1e32f38a51a11c90ed7c01000000), Actor(RoLSubGrid, b00b1e32f38a51a11c90ed7c01000000), Actor(RoLSubGrid, b00b1e32f38a51a11c90ed7c01000000), Actor(RoLSubGrid, b00b1e32f38a51a11c90ed7c01000000))\n",
      "[[0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 1 0 0 0 0 0 0 0]\n",
      " [0 0 0 1 0 0 0 0 0 0]\n",
      " [0 1 1 1 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]]\n",
      "[[0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]]\n"
     ]
    }
   ],
   "source": [
    "# script to drive parallel program\n",
    "ray.init(num_cpus=4, ignore_reinit_error=True)\n",
    "\n",
    "# 2x2 array of partitions\n",
    "dim = 2\n",
    "\n",
    "# ray objects for actors\n",
    "oids = np.empty([dim,dim], dtype=object)\n",
    "\n",
    "# this list will be used to implement barriers, i.e. wait for the completion of a set of jobs\n",
    "roids = []\n",
    "\n",
    "# create grids\n",
    "for ix in range(dim):\n",
    "    for iy in range(dim):\n",
    "        if ix == 0 and iy == 0:\n",
    "            oids[ix, iy] = RoLSubGrid.remote(8, True)\n",
    "        else:\n",
    "            oids[ix, iy] = RoLSubGrid.remote(8, False)\n",
    "        print(f\"({ix},{iy}) {oids[ix,iy]}\")\n",
    "\n",
    "# set neighbors T B L R TL TR BL BR\n",
    "for ix in range(dim):\n",
    "    for iy in range(dim):\n",
    "        roids.append(oids[ix, iy].set_neighbors.remote(\n",
    "            oids[(ix - 1) % dim, iy], oids[(ix + 1) % dim, iy], oids[ix, (iy - 1) % dim], oids[ix, (iy + 1) % dim],\n",
    "            oids[(ix - 1) % dim, (iy - 1) % dim], oids[(ix - 1) % dim, (iy + 1) % dim],\n",
    "            oids[(ix + 1) % dim, (iy - 1) % dim], oids[(ix + 1) % dim, (iy + 1) % dim]))\n",
    "\n",
    "# await the initialization of all neighbors\n",
    "# this is a barrier.\n",
    "[ray.get(oid) for oid in roids]\n",
    "\n",
    "# let's look at the neighbor list\n",
    "for ix in range(dim):\n",
    "    for iy in range(dim):\n",
    "        print(ray.get(oids[ix,iy].get_neighbors.remote()))\n",
    "        \n",
    "# and the grid\n",
    "print(ray.get(oids[0, 0].get_grid.remote()))\n",
    "print(ray.get(oids[1, 1].get_grid.remote()))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ffe3cc37-e7c6-4788-a4a7-c02ad245b232",
   "metadata": {},
   "source": [
    "#### Comments on the program setup\n",
    "\n",
    "Before executions we have:\n",
    "* Ray actors: one for each 8x8 data partition\n",
    "* Local grids (data partitions) in each actor, with a glider in the 0,0 partition\n",
    "* Ghost cells in the partition and a topology to link ghost cells to other ndoes\n",
    "    \n",
    "Object identifiers: Everything is an `oid` in ray\n",
    "* remote functions that are running asnychronously\n",
    "* actors that have been created, but are idle waiting for remote invocation of functions.\n",
    "* data items in the key value store\n",
    "\n",
    "Actors are stateful, service centers:\n",
    "* Actors are created (remotely) and wait for functions to be invoked on them\n",
    "* Functions can alter the state of the actor\n",
    "* Subsequent functions see the updated state\n",
    "\n",
    "Parallelism and completion:\n",
    "* `.remote()` launches the computation and returns an oid\n",
    "* `.get()` awaits completion and copies the return value \n",
    "    * recall that values are stored in the object store\n",
    "    * gets are repeatable (we learned this last class)\n",
    "    \n",
    "Anti-pattern (things not to do):\n",
    "* `ray.get(actor.function.remote())` makes a synchronous call (not parallel)\n",
    "\n",
    "\n",
    "#### Driver\n",
    "The Ray program (the driver script) is the coordinator of remote computation. The way to get parallelism is to call `remote()` on many actors to launch asynchronous computation. In this, and many Ray programs, actors call remote functions on actors directly."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "905821cb-2e5e-4a85-a4a5-c306b07e2ee8",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Step 0\n",
      "[[0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 1 0 0 0 0 0 0 0]\n",
      " [0 0 0 1 0 0 0 0 0 0]\n",
      " [0 1 1 1 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]]\n",
      "[[0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]\n",
      " [0 0 0 0 0 0 0 0 0 0]]\n"
     ]
    }
   ],
   "source": [
    "# 64 iterations will return the glider home.\n",
    "for it in range(64):\n",
    "    \n",
    "    # this is printing only. not part of the program \n",
    "    if (it % 4 == 0):\n",
    "        # Glider only lives in top left and bottom right really\n",
    "        print(f\"Step {it}\")\n",
    "        print(ray.get(oids[0, 0].get_grid.remote()))\n",
    "        print(ray.get(oids[1, 1].get_grid.remote()))\n",
    "\n",
    "    # asychronously update the local grids\n",
    "    roids = []\n",
    "    for ix in range(dim):\n",
    "        for iy in range(dim):\n",
    "            roids.append(oids[ix, iy].step.remote())\n",
    "    # first barrier awaiting local updates\n",
    "    [ray.get(oid) for oid in roids]\n",
    "    \n",
    "    # exchange data among sides and corners.\n",
    "    roids = []\n",
    "    for ix in range(dim):\n",
    "        for iy in range(dim):     \n",
    "    # what we really want to do is, but it deadlocks\n",
    "    #      roids.append(oids[ix, iy].exchange.remote())\n",
    "    #\n",
    "    #[ray.get(oid) for oid in roids]\n",
    "            ray.get(oids[ix,iy].exchange.remote())\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ee93d17b-79bd-49af-8b92-32b525b3b4ed",
   "metadata": {},
   "source": [
    "#### Comments on the Driver\n",
    "\n",
    "##### Barriers:\n",
    "\n",
    "It is necessary to have barriers because the GoL updates must be finished before the data exchange and the data exchange must be finished before the next updates.\n",
    "* `ray.get()` awaits completion\n",
    "* calling get on all oids implements a barrier\n",
    "* __CAUTION__ do not use `ray.wait()` it returns ready and not ready jobs\n",
    "    * it is useful for control flow in complex programs\n",
    "\n",
    "##### BSP:\n",
    "\n",
    "* This is not strictly BSP, because we have a barrier before communication.\n",
    "* This type of double barrier is typical of many algorithms, e.g. most implementations of parallel k-means does this. \n",
    "* This could be turned into a full BSP algorithm with queues or asynchronous messaging\n",
    "    * finish computing\n",
    "    * push udpates into queues\n",
    "    * get updates from queues\n",
    "* In fact, the entire last barrier can be removed by making the program depend entirely on point-to-point data exchanges\n",
    "    * That is how the MPI implementation of this program works.\n",
    "    "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "42af5954-3cbb-4b0d-8b80-b905b7b60ab8",
   "metadata": {},
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f2af4ee8-e962-40df-bb0a-a04c581d26a5",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "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.10.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}