Mesa_Tutorial.ipynb

{
  "nbformat": 4,
  "nbformat_minor": 0,
  "metadata": {
    "colab": {
      "provenance": [],
      "private_outputs": true
    },
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3"
    },
    "language_info": {
      "name": "python"
    }
  },
  "cells": [
    {
      "cell_type": "markdown",
      "source": [
        "# Mesa Tutorial"
      ],
      "metadata": {
        "id": "F47lGxH4knja"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "Welcome! There are a few slides accompanying this workshop. You can find them [here](https://docs.google.com/presentation/d/1HdxIk6XM6W-3IvTpLS_XOvetDfMACZKnFQlNKKXnMsA/edit?usp=sharing)."
      ],
      "metadata": {
        "id": "m7OSseirSOaN"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Introduction"
      ],
      "metadata": {
        "id": "Pucl84mcTE7A"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Imports"
      ],
      "metadata": {
        "id": "QwuHfjrekts8"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "Let's start by importing the packages we need.\n",
        "* Note we must install Mesa, since Colab does not have it by default.\n",
        "* If you are using your own computer, make sure you create a new environment. Install Mesa in your new environment and activate the environment."
      ],
      "metadata": {
        "id": "QmhOyPugU4tA"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "install_mesa = input(\"Do you want me to install mesa? [yes/no]\")\n",
        "if install_mesa.lower() == \"yes\":\n",
        "  %pip install --quiet mesa\n",
        "else:\n",
        "  print(\"OK then.\")"
      ],
      "metadata": {
        "id": "Nzp9drnulkzH"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "rnUpJvZnG6N8"
      },
      "outputs": [],
      "source": [
        "import mesa\n",
        "import numpy as np\n",
        "import matplotlib.pyplot as plt"
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Random Generator"
      ],
      "metadata": {
        "id": "pZWnXNz2rfie"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "Throughout the workshop we will use some random numbers.\n",
        "* Mesa has its own random number generator. To avoid dealing with an extra new thing today, we'll use Numpy's.\n",
        "* As per Numpy's suggestion, we will create a random number generator."
      ],
      "metadata": {
        "id": "IcVaTT3AVVxp"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "rng = np.random.default_rng()"
      ],
      "metadata": {
        "id": "8dP_K4cPrblH"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Quick Class review"
      ],
      "metadata": {
        "id": "aw6b66K6k7Mk"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "Let's review quickly how to declare classes in python, and how to create instances of your class."
      ],
      "metadata": {
        "id": "hVpRQPMWYvhg"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "class  Greeter:\n",
        "  def __init__(self, some_name):\n",
        "    self.name = some_name\n",
        "\n",
        "  def greet(self):\n",
        "    print(f\"Hello world. My name is {self.name}.\")"
      ],
      "metadata": {
        "id": "Zk9_x0AKmsDc"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "alice = Greeter(\"Alice\")"
      ],
      "metadata": {
        "id": "vLNJQ7lN6T5q"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "alice.greet()"
      ],
      "metadata": {
        "id": "W5sHIuyu6cyc"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "This is how you define a subclass:"
      ],
      "metadata": {
        "id": "igGkhpX1Y9J8"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "class EarlyRiser(Greeter):\n",
        "  preference = \"Morning\"\n",
        "  def __init__(self, some_name, some_time):\n",
        "    super().__init__(some_name)\n",
        "    self.wakeup_time = some_time\n",
        "\n",
        "  def awake_time(self):\n",
        "    print(f\"I'm usually awake by {self.wakeup_time}\")"
      ],
      "metadata": {
        "id": "uaU_88jGATw2"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "alice2 = EarlyRiser(\"Alice 2\", \"5 AM\")"
      ],
      "metadata": {
        "id": "Jm8cRigbBpaF"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "alice2.name"
      ],
      "metadata": {
        "id": "3AqaiNbXBx_a"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "alice2.greet()"
      ],
      "metadata": {
        "id": "fR9BPkWQB3Gv"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "alice2.awake_time()"
      ],
      "metadata": {
        "id": "HjhDPDx4B58e"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "alice2.preference"
      ],
      "metadata": {
        "id": "lg8A8oOWB8c6"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "Notice that while we didn't explicitly indicate the `name` aatribute and the `greet()` method in `EarlyRiser`, alice2 inherited those from `Greeter`."
      ],
      "metadata": {
        "id": "sldwpEYRZFFw"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "#### **EXERCISE**\n",
        "Create a `GrumpyRiser` greeter with a method `coffee_intake()` which reports how much coffee your instance drinks to get energized. `GrumpyRiser` should be a subclass of `Greeter`."
      ],
      "metadata": {
        "id": "SMJgNH8cZXvJ"
      }
    },
    {
      "cell_type": "code",
      "source": [],
      "metadata": {
        "id": "2pCs_PUXCBvY"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "<br><br><br><br><br><br>"
      ],
      "metadata": {
        "id": "09IO6bxbaKJj"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Mesa Classes"
      ],
      "metadata": {
        "id": "OAVDfGsV_XxH"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "Mesa has some pre-established classes with handy methods. The must important ones are:\n",
        "*   The Model class\n",
        "*   The Agent class\n",
        "*   Space related classes\n",
        "*   Time related classes\n",
        "*   Data Collection related classes\n",
        "\n",
        "Usually, you will use the time, space, and data collection classes as they come. However, you will write your own model and agent classes that inherit from the base Mesa model and agent classes."
      ],
      "metadata": {
        "id": "naB96CWtaUsv"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Model Classes"
      ],
      "metadata": {
        "id": "C-023N4saRsi"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "Let's create a subclass of `mesa.Model`."
      ],
      "metadata": {
        "id": "-fzdD7dabG7H"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "class GreetModelV0(mesa.Model):          # <-- Indicates the parent class\n",
        "  def __init__(self, model_name):\n",
        "    super().__init__()                # <-- Initializes using the parent class\n",
        "    self.name = model_name"
      ],
      "metadata": {
        "id": "bFvvxPnc_bwz"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "**Note:** `mesa.Model()` does not require any initial arguments. You can create a model without a model_name. `TestModel` adds the required model_name parameter."
      ],
      "metadata": {
        "id": "cW7qBuq7DKXe"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "model_0 = GreetModelV0(\"First Mesa Model\")"
      ],
      "metadata": {
        "id": "Uh25egyL_6_4"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "model_0.name"
      ],
      "metadata": {
        "id": "5Z5BJXeSAJLV"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "Cool! But our model doesn't doa nything interesting. For that, we'll have to create agents."
      ],
      "metadata": {
        "id": "aWGcVsYwbj1L"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Agent classes in Mesa"
      ],
      "metadata": {
        "id": "ihyVNhX16hiB"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "class GreeterV1(mesa.Agent):\n",
        "  def __init__(self, unique_id, model):\n",
        "    super().__init__(unique_id, model)      # <-- Note mesa.Agent requires two arguments: unique_id and a mesa.Model\n",
        "\n",
        "  def greet(self):\n",
        "    print(f\"Hello world. My name is {self.unique_id}.\")"
      ],
      "metadata": {
        "id": "eBvwIOLy6raB"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "Note: Here, `mesa.Agent()` does require two parameters: a `unique_id` (to identify agents), and a `model` (the \"system\" agents are part of)."
      ],
      "metadata": {
        "id": "Wi6Um70bDbwp"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "mesa_greeter = GreeterV1(1, model_0)"
      ],
      "metadata": {
        "id": "hDJjKOBF_HLx"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "mesa_greeter.unique_id"
      ],
      "metadata": {
        "id": "LwiHnOkHCtlx"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "mesa_greeter.model"
      ],
      "metadata": {
        "id": "XG3lR5EgEAba"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Creating Agents inside the Model"
      ],
      "metadata": {
        "id": "HSa361iOcNX5"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "The idea behind Mesa is that we should only worry about bird's eye view.\n",
        "\n",
        "Hence, instead of creating agents ourselves, and individually asking them to perform tasks, we use the model for that."
      ],
      "metadata": {
        "id": "KuH6E8sCUOlN"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "class GreetModelV1(mesa.Model):\n",
        "  def __init__(self, N):\n",
        "    super().__init__()\n",
        "    self.number_agents = N\n",
        "    self.greeters = []\n",
        "    for n in range(self.number_agents):\n",
        "      g = GreeterV1(unique_id = n,model = self) # <-- Note the input for require model argument\n",
        "      self.greeters.append(g)"
      ],
      "metadata": {
        "id": "pghhh6SmEJcA"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "N = 10\n",
        "model_1 = GreetModelV1(N)"
      ],
      "metadata": {
        "id": "9pb_KRjgWmi0"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "model_1.greeters"
      ],
      "metadata": {
        "id": "vcAPnOHPWtUn"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "**Note:**\n",
        "\n",
        "Inside GreetModelV1, we explicitly wrote the agent class. This may become cumbersome or limiting. From now on I will use the agent class as an input for our models. For example:"
      ],
      "metadata": {
        "id": "X2z9A1BKcygW"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "class GreetModelV1b(mesa.Model):\n",
        "  def __init__(self, N, agent_class):\n",
        "    super().__init__()\n",
        "    self.number_agents = N\n",
        "    self.greeters = []\n",
        "    for n in range(self.number_agents):\n",
        "      g = agent_class(n,self)\n",
        "      self.greeters.append(g)"
      ],
      "metadata": {
        "id": "WtyLYM4NdWop"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "N = 3\n",
        "model_1b = GreetModelV1b(N, GreeterV1) # <-- input a reference to the class GreeterV1\n",
        "model_1b.greeters"
      ],
      "metadata": {
        "id": "qKbL9uXVddt9"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "OK cool. But...\n",
        "\n",
        "Making a list of agents is already looking like a lot of micro-managing. We don't want this.\n",
        "\n",
        "This is were Mesa becomes quite handy! It manages our agents through a **scheduler**."
      ],
      "metadata": {
        "id": "2UNkmdJvd24X"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "## The Scheduler"
      ],
      "metadata": {
        "id": "4ievMA37XUyy"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "In a usual run of an agent-based model, we see two units of time:\n",
        "*  Time at the agent level\n",
        "*  Time at the model level\n",
        "\n",
        "At each time step at the model level, a subset (or all) of the agents move and perform some actions.\n",
        "\n",
        "At each time step at the agent level, only one agent moves and initiates actions.\n",
        "\n",
        "Both Mesa models and agents use a `step()` method, indicating what to do at a given step. The scheduler manages who goes next."
      ],
      "metadata": {
        "id": "Jw_76NEdZgQ6"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "class GreeterV2(mesa.Agent):\n",
        "  def __init__(self, unique_id, model, some_name):    # <-- Adding a name argument for fun.\n",
        "    super().__init__(unique_id, model)\n",
        "    self.name = some_name\n",
        "\n",
        "  def greet(self):\n",
        "    print(f\"Hello world. My name is {self.name}.\")\n",
        "\n",
        "  def step(self):                 # <-- Adding step() method\n",
        "    self.greet()"
      ],
      "metadata": {
        "id": "TaYmgT9NZXIT"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "class GreetModelV2(mesa.Model):\n",
        "  def __init__(self, N, agent_class):\n",
        "    super().__init__()\n",
        "    self.number_agents = N\n",
        "\n",
        "    # Create a scheduler!\n",
        "    self.schedule = mesa.time.RandomActivation(self)                    # <-- Schedule\n",
        "\n",
        "    # When you create agents, add them to the scheduler\n",
        "    for n in range(self.number_agents):\n",
        "      g = agent_class(n,self, f\"{n}\")\n",
        "      self.schedule.add(g)      # <--  Add to schedule\n",
        "\n",
        "  def step(self):\n",
        "    self.schedule.step()        # <--  Tell schedule to step"
      ],
      "metadata": {
        "id": "LgwgcVioXIy_"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "**Note:**\n",
        "\n",
        "There are different types of schedulers. We will use `RandomActivation`, which calls agents at a random order at each model level step."
      ],
      "metadata": {
        "id": "l4WHSstki4fB"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "N = 10\n",
        "model_2 = GreetModelV2(N, GreeterV2) # <-- You may get a warning when first running this about AgentSet. Ignore it."
      ],
      "metadata": {
        "id": "NiOy4qFhaHp1"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "model_2.step()"
      ],
      "metadata": {
        "id": "vXX6tJm7aP7h"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "Note how for 1 step of the model, each agent took their own agent-level step!"
      ],
      "metadata": {
        "id": "9ZIcoC1BhKAM"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "### RECAP\n",
        "\n",
        "Agents\n",
        "*   Need to be connected to a given model\n",
        "*   Need a step() method\n",
        "\n",
        "Models\n",
        "* In charge of creating agents\n",
        "* In charge of creating a schedule\n",
        "* In charge of adding agents to the schedule\n",
        "* Need a step() method calling the schedule's own step.\n",
        "\n"
      ],
      "metadata": {
        "id": "hXzAXojgc1Lg"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "#### **EXERCISE**\n",
        "\n",
        "Create a Mesa model `MoveModel` and agents in this model `Movers` that move in the unit square at random at each step and output their coordinates. Use a scheduler. Run it for 3 agents and a few steps.\n",
        "\n",
        "Hint: you can select a random coordinate in the unit square with the following code: `(cx, cy) = rng.random(2)`"
      ],
      "metadata": {
        "id": "9Jk1XOkLJJ_K"
      }
    },
    {
      "cell_type": "code",
      "source": [],
      "metadata": {
        "id": "vlb2BF9_JKjO"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "<br><br><br><br><br><br>"
      ],
      "metadata": {
        "id": "QYJcmYitI_fw"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Space"
      ],
      "metadata": {
        "id": "tHm6GZA6c39D"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "Another handy Mesa benefit is the pre-made space classes. For now it can only deal with square grids and 2-d continuous space consistently. Seems like other grid shapes (hexagonal, networks, etc.) are in development."
      ],
      "metadata": {
        "id": "Di4BjU-LjSrk"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Creating space and placing agents in space"
      ],
      "metadata": {
        "id": "IIsBCyjLoN68"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "class GreetModelV3(mesa.Model):\n",
        "  def __init__(self, N, agent_class, grid_side):\n",
        "    super().__init__()\n",
        "    self.number_agents = N\n",
        "    self.schedule = mesa.time.RandomActivation(self)\n",
        "\n",
        "    # Create grid!\n",
        "    self.grid = mesa.space.MultiGrid(width = grid_side, height = grid_side, torus = True)\n",
        "\n",
        "    # When you create agents, add them to the scheduler AND to the grid\n",
        "    for n in range(self.number_agents):\n",
        "      g = agent_class(n,self,f\"{n}\")\n",
        "      self.schedule.add(g)\n",
        "\n",
        "      [i,j] = rng.integers(grid_side,size=2)\n",
        "      self.grid.place_agent(g, (i,j))        # <-- Add agent to the grid\n",
        "\n",
        "  def step(self):\n",
        "    self.schedule.step()"
      ],
      "metadata": {
        "id": "p93Nc9ticRpP"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "We will get back to the code above, but first let's visualize our grid."
      ],
      "metadata": {
        "id": "O5eb4k4rujVO"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "model_3 = GreetModelV3(N = 10, agent_class = GreeterV2, grid_side =3)"
      ],
      "metadata": {
        "id": "gxfPcyWLtsPJ"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "model_3.grid"
      ],
      "metadata": {
        "id": "BmJyiMSru0T2"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "Let's make a table with agent number per grid cell"
      ],
      "metadata": {
        "id": "QHTFF3fRwXWw"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# Recover grid dimensions\n",
        "grid_side = model_3.grid.width\n",
        "\n",
        "# Create numpy 2d array with grid dimensions\n",
        "count_table = np.zeros((grid_side,grid_side))\n",
        "\n",
        "# Get contents of each cell\n",
        "for cell_content, (i,j) in model_3.grid.coord_iter():         # <--- coordinates iterator!\n",
        "  n_agents = len(cell_content)\n",
        "  count_table[i][j] = n_agents"
      ],
      "metadata": {
        "id": "AcDVtyf0vPma"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "count_table"
      ],
      "metadata": {
        "id": "_BDDBHmOoC6-"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "plt.imshow(count_table, cmap = \"Purples\")"
      ],
      "metadata": {
        "id": "egLj-vptxIE-"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "**MultiGrid:** The \"multi\" comes from the fact that many agents are allowed to live inside one cell. You could enforce one agent per cell, but we won't do that here.\n",
        "\n",
        "**Grid Dimensions:** Notce MultGrid requires obth width and height. Since we are only interested in a square grid now we'll use a single grid_side parameter.\n",
        "\n",
        "**Torus:** A torus is just a donut. This is the space you get when you have a square and allow the left side to \"teleport\" to the right side and the bottom to teleport to the top. Similar to the game Pac-Man. If set to False the agent just goes out of bounds (I don't think they have a way to enforce hard boundaries yet).\n",
        "\n",
        "**Note on coordiantes:** Notice I've labeled the random coordiantes $i$ and $j$. That's because grids work like matrices, the first coordinate is the row (starting from the top) and the second the column (starting from the left). We are used to index matrices with $i$ and $j$. If we were dealing with continuous space, I would have labeled them $x$ and $y$.\n",
        "\n"
      ],
      "metadata": {
        "id": "qjwXKMPZk4-N"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Moving agents in space"
      ],
      "metadata": {
        "id": "YOzxTzX4y2Cr"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "Often, agents interact only with those who are close to them. This is, live in the same neighborhood. For grids, there are two common types of neighborhoods:\n",
        "\n",
        "*   Moore: Includes all 8 surrounding cells.\n",
        "*   Von Neumann: Excludes diagonal neighboring cells.\n",
        "\n",
        "We will use the Moore neighborhood."
      ],
      "metadata": {
        "id": "ZCjmpMvCpNfv"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "Let's move our agents at each step to one of their neighboring cells:"
      ],
      "metadata": {
        "id": "6pgJSJ0QME5K"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "class GreeterV3(mesa.Agent):\n",
        "  def __init__(self, unique_id, model, some_name):\n",
        "    super().__init__(unique_id, model)\n",
        "    self.name = some_name\n",
        "\n",
        "  def step(self):\n",
        "    self.move()\n",
        "    self.greet()\n",
        "\n",
        "  def greet(self):\n",
        "    print(f\"Hello world. My name is {self.name}. I am at {self.pos}\")\n",
        "\n",
        "  def move(self):         # <--- Adding move() method\n",
        "    neighborhood = self.model.grid.get_neighborhood(self.pos, moore=True, include_center=False)       # <-- get a moore neighborhood\n",
        "    [ci,cj] = rng.choice(neighborhood)\n",
        "    self.model.grid.move_agent(self, (ci,cj))       # <-- move to new position in the grid!"
      ],
      "metadata": {
        "id": "DOyb4UWxxQp0"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "model_4 = GreetModelV3(10, GreeterV3, 3)"
      ],
      "metadata": {
        "id": "KM5JrJE62gzh"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "model_4.step()"
      ],
      "metadata": {
        "id": "T9I0YT2V3uLu"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "### Recap\n",
        "Mesa provides us with two types of space:\n",
        "\n",
        "*   Grids\n",
        "*   Flat Continuous (2-d)\n",
        "\n",
        "Don't forget to add your agents to space when you create them.\n",
        "\n",
        "Notice that Mesa has some limitations, for example, it doesn't have the sphere as a possible space, but it would be the natural space for many real-life applications."
      ],
      "metadata": {
        "id": "0nCmPugVMVsm"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Interacting Agents"
      ],
      "metadata": {
        "id": "SB4_By-b_OVN"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "We are finally ready to make our agents interact! We will do this by obtaining the cell contents of the grid.\n",
        "\n",
        "Let's do the following: Every time they are in a cell with other agents, the agent adds them to a list of acquaintances. For now, we will re-count agents they already met."
      ],
      "metadata": {
        "id": "CqYUzBI7q4Dx"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "class UltimateGreeter(mesa.Agent):\n",
        "  def __init__(self, unique_id, model, some_name):\n",
        "    super().__init__(unique_id, model)\n",
        "    self.name = some_name\n",
        "\n",
        "    # -- New property --\n",
        "    self.acquaintances = []\n",
        "    self.n_acqs = len(self.acquaintances)\n",
        "\n",
        "  def step(self):\n",
        "    self.move()\n",
        "    self.greet_neighbor()\n",
        "    self.greet()\n",
        "\n",
        "  def greet(self):\n",
        "    print(f\"Hello world. My name is {self.name}. I am at {self.pos}. Today I met: {self.acquaintances}.\")\n",
        "    return ;\n",
        "\n",
        "  def move(self):\n",
        "    neighborhood = self.model.grid.get_neighborhood(self.pos, moore=True, include_center=False)\n",
        "    [ci,cj] = rng.choice(neighborhood)\n",
        "    self.model.grid.move_agent(self, (ci,cj))\n",
        "\n",
        "  # -- New method --\n",
        "\n",
        "  def greet_neighbor(self):\n",
        "    neighbors = self.model.grid.get_cell_list_contents(self.pos)      # Obtain contents of cell\n",
        "    for neigh in neighbors:\n",
        "      if neigh.unique_id != self.unique_id:\n",
        "        self.acquaintances.append(neigh.unique_id)\n",
        "    self.n_acqs = len(self.acquaintances)\n",
        "\n"
      ],
      "metadata": {
        "id": "dCslmo2P_QSR"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "model_5 = GreetModelV3(10, UltimateGreeter, 3)"
      ],
      "metadata": {
        "id": "OMvGm2IkB7z7"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "model_5.step()"
      ],
      "metadata": {
        "id": "pQrvjUZBCB7V"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "<h4>\n",
        "<font color = \"red\">\n",
        "<b>NOTE</b>\n",
        "</font>\n",
        "</h4>\n",
        "\n",
        "Next, we will take many model level steps, hence, go to your `UltimateGreeter` class and comment out the `greet()` method within `step()` or the `print()` statement."
      ],
      "metadata": {
        "id": "E7CdR5cIsWZp"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Observer"
      ],
      "metadata": {
        "id": "hIh-UoT3Ct7j"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "Finally, Mesa has observer classes which they call `DataCollector`. The data collector has two types of reporters:\n",
        "* Model level reporters: report on properties of the model at each step. Can also report on model-wide functions (statistics, etc.).\n",
        "* Agent level reporters: report on individual agent properties or functions of agents.\n",
        "\n",
        "We will only see agent reporters here."
      ],
      "metadata": {
        "id": "wuVdOc-etv4C"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "class UltimateGreetingModel(mesa.Model):\n",
        "  def __init__(self, N, agent_class, grid_side):\n",
        "    super().__init__()\n",
        "    self.number_agents = N\n",
        "    self.schedule = mesa.time.RandomActivation(self)\n",
        "    self.grid = mesa.space.MultiGrid(width = grid_side, height = grid_side, torus = True)\n",
        "    self.initialize_agents(agent_class) # <-- added this to clean things up\n",
        "\n",
        "    # -- Create Observer --\n",
        "    self.data_collector = mesa.DataCollector(\n",
        "        agent_reporters={\"Acquaintances\": \"n_acqs\"}\n",
        "    )\n",
        "\n",
        "  def step(self):\n",
        "    self.data_collector.collect(self)       # <-- Call the observer!!\n",
        "    self.schedule.step()\n",
        "\n",
        "  def initialize_agents(self, agent_class):\n",
        "      for n in range(self.number_agents):\n",
        "        g = agent_class(unique_id = n,model = self, some_name = f\"{n}\")\n",
        "        self.schedule.add(g)\n",
        "        [ci,cj] = rng.integers(grid_side,size=2)\n",
        "        self.grid.place_agent(g, (ci,cj))"
      ],
      "metadata": {
        "id": "S6o0_1U4CEFJ"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "The reporter requires a dictionary as argument. Your dictionary can have many key-value pairs. The key is just the name you give to a specific report. The value is the important part here. It can be the name of an agent attribute (as in our case). It can also be a functions you have declared or lambda functions. See Mesa general documentation and also the comments [here](https://github.com/projectmesa/mesa/blob/main/mesa/datacollection.py)."
      ],
      "metadata": {
        "id": "X0PvfJZ5zS4M"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "model_6 = UltimateGreetingModel(3, UltimateGreeter, 3)"
      ],
      "metadata": {
        "id": "6vqa-H7jtfDT"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "The data collector returns the data in the form of a pandas data frame:"
      ],
      "metadata": {
        "id": "WZk5M2ZL0wVX"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "model_6.data_collector.get_agent_vars_dataframe()"
      ],
      "metadata": {
        "id": "-DVFiHVWtnV0"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "model_6.step()"
      ],
      "metadata": {
        "id": "autnJFDF06BD"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "model_6.data_collector.get_agent_vars_dataframe()"
      ],
      "metadata": {
        "id": "2r1tKS8StqHu"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "Let's run the model for 50 steps and then plot the number of acquaintances per agent!"
      ],
      "metadata": {
        "id": "kH3p5FwY0c5q"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "model_6b = UltimateGreetingModel(3, UltimateGreeter, 3)\n",
        "\n",
        "for k in range(50):\n",
        "  model_6b.step()\n",
        "\n",
        "df1 = model_6b.data_collector.get_agent_vars_dataframe()\n",
        "df1.head(5)"
      ],
      "metadata": {
        "id": "rbLRUidbELrK"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "df1.reset_index().pivot(index = \"Step\", columns = \"AgentID\", values = \"Acquaintances\").plot(ylabel = \"Number of Acquaintances\")\n",
        "# my pandas know-how is not the best, feel free to improve the line above."
      ],
      "metadata": {
        "id": "ac54XlAhlYgN"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "#### **EXERCISE**\n",
        "Below I've pasted copies of `UltimateGreeter` and `UltimateGreetingModel`. Modify them to achieve the following:\n",
        "\n",
        "1. Agents don't double count acquaintances.\n",
        "\n",
        "2. Add a \"Percentage Met\" report on the percentage of total agents an agent has met. You can do this by creating a property of the agent, like `n_acqs` above, or through a lambda function as the value in the dictionary (the input to the lambda function represents the agent)."
      ],
      "metadata": {
        "id": "0FnEkxC6PPh9"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "class UltimateGreeterV2(mesa.Agent):\n",
        "  def __init__(self, unique_id, model, some_name):\n",
        "    super().__init__(unique_id, model)\n",
        "    self.name = some_name\n",
        "    self.acquaintances = []\n",
        "    self.n_acqs = len(self.acquaintances)\n",
        "\n",
        "\n",
        "  def step(self):\n",
        "    self.move()\n",
        "    self.greet_neighbor()\n",
        "    self.get_percentage()\n",
        "\n",
        "  def move(self):\n",
        "    neighborhood = self.model.grid.get_neighborhood(self.pos, moore=True, include_center=False)\n",
        "    [ci,cj] = rng.choice(neighborhood)\n",
        "    self.model.grid.move_agent(self, (ci,cj))\n",
        "\n",
        "  def greet_neighbor(self):\n",
        "    neighbors = self.model.grid.get_cell_list_contents(self.pos)      # Obtain contents of cell\n",
        "    for neigh in neighbors:\n",
        "      if neigh.unique_id != self.unique_id:\n",
        "        self.acquaintances.append(neigh.unique_id)\n",
        "    self.n_acqs = len(self.acquaintances)"
      ],
      "metadata": {
        "id": "ioDH9qRiQr_c"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "class UltimateGreetingModelV2(mesa.Model):\n",
        "  def __init__(self, N, agent_class, grid_side):\n",
        "    super().__init__()\n",
        "    self.number_agents = N\n",
        "    self.schedule = mesa.time.RandomActivation(self)\n",
        "    self.grid = mesa.space.MultiGrid(width = grid_side, height = grid_side, torus = True)\n",
        "    self.initialize_agents(agent_class) # <-- added this to clean things up\n",
        "\n",
        "    # -- Create Observer --\n",
        "    self.data_collector = mesa.DataCollector(\n",
        "        agent_reporters={\"Acquaintances\": \"n_acqs\"}\n",
        "    )\n",
        "\n",
        "  def step(self):\n",
        "    self.data_collector.collect(self)       # <-- Call the observer!!\n",
        "    self.schedule.step()\n",
        "\n",
        "  def initialize_agents(self, agent_class):\n",
        "      for n in range(self.number_agents):\n",
        "        g = agent_class(unique_id = n,model = self, some_name = f\"{n}\")\n",
        "        self.schedule.add(g)\n",
        "        [ci,cj] = rng.integers(grid_side,size=2)\n",
        "        self.grid.place_agent(g, (ci,cj))"
      ],
      "metadata": {
        "id": "9AU8VMrBRpnL"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "model_7 = UltimateGreetingModelV2(3, UltimateGreeterV2, 3)\n",
        "for k in range(10):\n",
        "  model_7.step()\n",
        "\n",
        "df_ex = model_7.data_collector.get_agent_vars_dataframe()\n",
        "df_ex.reset_index().pivot(index = \"Step\", columns = \"AgentID\", values = \"Percentage Met\").plot(ylabel = \"Percentage of Agents Met\")"
      ],
      "metadata": {
        "id": "snqHCSJ-R0Mm"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "<br><br><br><br><br><br>"
      ],
      "metadata": {
        "id": "qGONbkPJTFw_"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Parameter Sweep"
      ],
      "metadata": {
        "id": "CYkL43tLmFTt"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "Finally, Mesa comes in very handy with their `batch_run()` function. This is basically a parameter sweep. We won't have time for that in this workshop but I wanted to make you aware of it, since it is an integral part of simulation. You can learn more about it in Mesa's tutorial [here](https://mesa.readthedocs.io/en/stable/tutorials/intro_tutorial.html#batch-run).\n",
        "\n",
        "In the slides for this workshop I have added a table illustrating how the output of a batch run would look."
      ],
      "metadata": {
        "id": "yioA5mNM1Bot"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Conclusion"
      ],
      "metadata": {
        "id": "fhoxsNzr3n1a"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "See last slide in workshop slides for recap of Mesa's classes and relationships."
      ],
      "metadata": {
        "id": "Jq609mfn3p7L"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "And with that we come to and end. For further information, check out Mesa's own documentaion [here](https://mesa.readthedocs.io/en/stable/overview.html)."
      ],
      "metadata": {
        "id": "6ACZTou01w_U"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "<br><br><br><br><br><br>\n",
        "\n"
      ],
      "metadata": {
        "id": "UyOcOfn111Or"
      }
    }
  ]
}