Running NetLogo simulations with pyNetLogo.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "2b49fd1b",
   "metadata": {},
   "source": [
    "# Downloads\n",
    "Before we can run either NetLogo or use pyNetLogo, we will first need to download them.\n",
    "## NetLogo\n",
    "NetLogo can be downloaded from here: https://ccl.northwestern.edu/netlogo/6.3.0/. Make sure to take note of the install location. On Windows it should default to being installed at **C:/Program Files/NetLogo 6.3.0/**. On Linux, you can just decompress the file and place it in a location of your choosing.\n",
    "## pyNetLogo\n",
    "The easiest way to install pyNetLogo is by running **pip install pynetlogo**. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "91577bab",
   "metadata": {},
   "source": [
    "# Setup\n",
    "We begin by first importing pyNetLogo."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "865f5203",
   "metadata": {},
   "outputs": [],
   "source": [
    "import pynetlogo"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cb3f316b",
   "metadata": {},
   "source": [
    "If you are on Windows, you will also want to import os and use it to set your java path variable. Linux users will likely already have this set by default. The path to your java install should look something like **C:/Program Files/Java/jdk-20**. You may need to change jdk-20 to something different if you have a different version of java installed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "438dff70",
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "os.environ[\"JAVA_HOME\"] = 'C:\\\\Program Files\\\\Java\\\\jdk-20'"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a4d2bb45",
   "metadata": {},
   "source": [
    "# Creating a link\n",
    "Next, we need to tell pyNetLogo where our copy NetLogo is. We do this using the **NetLogoLink** command. It returns an object we can use to communicate with NetLogo. The **netlogo_home** argument should be set to wherever you installed NetLogo to. As I am using Windows, it is found at **C:/Program Files/NetLogo 6.3.0/**. Additionally, we will typically set **gui = False** because we would like to run NetLogo headless from python."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "28cd48e4",
   "metadata": {},
   "outputs": [],
   "source": [
    "netlogo_path = \"C:/Program Files/NetLogo 6.3.0/\"\n",
    "nl = pynetlogo.NetLogoLink(netlogo_home=netlogo_path, gui = False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0248f893",
   "metadata": {},
   "source": [
    "# Loading a model\n",
    "Here, we use the **load_model** command to load a .nlogo file of our choice into NetLogo. For simplicity, let's use the **Ants** model that comes with NetLogo to demonstrate this. I encourage you to play with the model in NetLogo a bit before continuing on."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "14b71940",
   "metadata": {},
   "outputs": [],
   "source": [
    "nl.load_model(netlogo_path + \"models\\Sample Models\\Biology\\Ants.nlogo\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ed25979b",
   "metadata": {},
   "source": [
    "# Setting model parameters\n",
    "Having loaded the model, we can now set parameters by passing commands to our NetLogo instantiation using the **command** method. The **Ants** model has 3 parameters for us to set: **population**, **diffusion-rate**, and **evaporation-rate**. It will be convenient to put these in a dictionary and then use a loop to set them all, as seen below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "id": "2f22ee86",
   "metadata": {},
   "outputs": [],
   "source": [
    "parameters = {\n",
    "    \"population\" : 150,\n",
    "    \"diffusion-rate\": 25,\n",
    "    \"evaporation-rate\": 10\n",
    "}\n",
    "#Loop through the parameters and send them to NetLogo\n",
    "for key, value in parameters.items():\n",
    "    nl.command(f\"set {key} {value}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "51e4293b",
   "metadata": {},
   "source": [
    "The **set \\<parameter> \\<value>** command in NetLogo allows us to set parameter values. For reproducibility, it is also a good idea to set the seed that the random number generator in NetLogo starts from, which can be done using the NetLogo command **random-seed \\<seed>**."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "f3277910",
   "metadata": {},
   "outputs": [],
   "source": [
    "seed = 8335\n",
    "nl.command(f\"random-seed {seed}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c46d043a",
   "metadata": {},
   "source": [
    "Finally, we must tell NetLogo to set up the simulation using our provided parameters using the NetLogo **setup** command."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "id": "d47695d0",
   "metadata": {},
   "outputs": [],
   "source": [
    "nl.command(f\"setup\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0f83b7c6",
   "metadata": {},
   "source": [
    "# Running the model\n",
    "There are a few different ways to run models, but the simplest (and usually fastest) way to run a model is by repeatedly running the NetLogo **go** command. You can do this by using the **repeat_command** method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "id": "c8e6a601",
   "metadata": {},
   "outputs": [],
   "source": [
    "run_time = 200\n",
    "nl.repeat_command(\"go\", run_time)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "15c55924",
   "metadata": {},
   "source": [
    "# Checking on the model\n",
    "Obviously, we would like to be able to see what is going on in the simulation. To do this, we can utilize the **report** method, which takes in a NetLogo reporter, queries NetLogo, and returns it. Let's use it to check how much food is left in each food pile."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "id": "a5ed1d96",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Color cyan\n",
      "0.0\n",
      "Color sky\n",
      "96.0\n",
      "Color blue\n",
      "101.0\n"
     ]
    }
   ],
   "source": [
    "food_colors = [\"cyan\", \"sky\", \"blue\"]\n",
    "for c in food_colors:\n",
    "    print(f\"Color {c}\")\n",
    "    print(nl.report(f\"sum [food] of patches with [pcolor = {c}]\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "77005e23",
   "metadata": {},
   "source": [
    "Note that we asked to report a number and were returned a number. If we had instead asked for a list or string we would have been returned a list or string."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "924c6f1d",
   "metadata": {},
   "source": [
    "# Wrapping up\n",
    "Finally, we disconnect from NetLogo and kill it using the **kill_workspace** method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "id": "a42b8da8",
   "metadata": {},
   "outputs": [],
   "source": [
    "nl.kill_workspace()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "118a684f",
   "metadata": {},
   "source": [
    "# More Resources\n",
    "For more information on using NetLogo, a great place to look is the NetLogo User Manual found here: https://ccl.northwestern.edu/netlogo/docs/. \n",
    "\n",
    "For more information regarding pyNetLogo, the official documentation (although somewhat scant) can be found here: https://pynetlogo.readthedocs.io/en/latest/index.html."
   ]
  }
 ],
 "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.9.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}