examples/Example-pipeline.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Simurgh project \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Simurgh is a set of open source tools and infrastructure that supports developing and evaluating algorithms (AI agents) for automated air traffic control (ATC).\n",
    "\n",
    "For a full overview of the Simurch project (with install instructions), please read the project [README](https://github.com/alan-turing-institute/simurgh/blob/master/README.md).\n",
    "\n",
    "This notebook runs through the full pipeline offered by Simurgh to train agents for ATC (using Python).\n",
    "\n",
    "## Contents:\n",
    "\n",
    "* [1. Getting started](#first-section)\n",
    "* [2. Load sector and scenario](#second-section)\n",
    "* [3. Example usage](#third-section)\n",
    "* [4. Example OpenAI interface](#fourth-section)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Getting started <a class=\"anchor\" id=\"first-section\"></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.1 Launch simulator (`BlueSky`) and the `BlueBird` interface layer\n",
    "\n",
    "If you have not already started the BlueSky simulator and BlueBird, you can launch them using the command below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Starting bluesky ... \n",
      "\u001b[1BRecreating bluebird ... ne\u001b[0m\n",
      "\u001b[1Beating bluebird ... \u001b[32mdone\u001b[0mRecreating twitcher ... \n",
      "\u001b[1Beating twitcher ... \u001b[32mdone\u001b[0m"
     ]
    }
   ],
   "source": [
    "!docker-compose --file ../docker-compose.yml up --detach"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.2 Import `pydodo`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We will be using the `pydodo` package to communicate with BlueBird (and BlueSky). Assuming one has already installed it, we can import it here:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pydodo"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can check the url PyDodo is using to communicate with BlueBird:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "http://localhost:5001/api/v2\n"
     ]
    }
   ],
   "source": [
    "print(pydodo.bluebird_connect.get_bluebird_url())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If this is not correct (e.g., BlueBird is in fact being run on a different host), then we can change the url by using the `pydodo.bluebird_config` function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function bluebird_config in module pydodo.bluebird_connect:\n",
      "\n",
      "bluebird_config(host='localhost', port='5001', version='v2')\n",
      "    Set BlueBird host, port and version parameters.\n",
      "    Default values are taken from the config file.\n",
      "    \n",
      "    Parameters\n",
      "    ----------\n",
      "    host : str\n",
      "        BlueBird host (e.g., 'localhost' or '0.0.0.0').\n",
      "    port : int\n",
      "        BlueBird port (e.g., 5001).\n",
      "    version : str\n",
      "        BlueBird version (e.g., 'v1' or 'v2')\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(pydodo.bluebird_config)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can check whether `pydodo` can succesfully communicate with BlueBird by querying aircraft positions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>aircraft_type</th>\n",
       "      <th>ground_speed</th>\n",
       "      <th>latitude</th>\n",
       "      <th>longitude</th>\n",
       "      <th>vertical_speed</th>\n",
       "      <th>heading</th>\n",
       "      <th>current_flight_level</th>\n",
       "      <th>requested_flight_level</th>\n",
       "      <th>cleared_flight_level</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "Empty DataFrame\n",
       "Columns: [aircraft_type, ground_speed, latitude, longitude, vertical_speed, heading, current_flight_level, requested_flight_level, cleared_flight_level]\n",
       "Index: []"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pydodo.all_positions()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "_Success!_"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What do you mean success?! What we are seeing here is that `pydodo` is able to query positions of aircraft inside the simulator. The fact we do not see any is only becuase we have not defined a \"Sector\" and a \"Scenario\" yet."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Load sector and scenario <a class=\"anchor\" id=\"second-section\"></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.1 Overview\n",
    "\n",
    "To start, we need to upload a **sector** and a **scenario** (in that order). \n",
    "\n",
    "A sector defines the area the ATCO is controling. The scenario defines the episode: that is a sequence of aircraft whose route passes through the sector.\n",
    "\n",
    "You can use the [Aviary](https://github.com/alan-turing-institute/aviary/tree/develop) package to create sector and scenario files (see the README for more information and file formats).\n",
    "\n",
    "We can check whether a sector or a scenario has been defined already (see whether `sector_name` and `scenario_name` below are not `None`):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'dt': 0.05,\n",
       " 'mode': 'Agent',\n",
       " 'scenario_name': None,\n",
       " 'scenario_time': 0.0,\n",
       " 'sector_name': None,\n",
       " 'seed': None,\n",
       " 'sim_type': 'BlueSky',\n",
       " 'speed': 1.0,\n",
       " 'state': 'INIT',\n",
       " 'utc_datetime': '2020-06-11 00:00:00',\n",
       " 'aircraft_ids': []}"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pydodo.simulation_info()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Nothing has been loaded yet.\n",
    "\n",
    "There is an example sector and scenario included with this example that we load below:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.2 Load sector and scenario into `bluesky` using `bluebird`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pydodo.upload_sector('test-sector.geojson', 'test_sector')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pydodo.upload_scenario('test-scenario.json', 'test_scenario')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'dt': 0.05,\n",
       " 'mode': 'Agent',\n",
       " 'scenario_name': 'test_scenario',\n",
       " 'scenario_time': 2.6,\n",
       " 'sector_name': 'test_sector',\n",
       " 'seed': None,\n",
       " 'sim_type': 'BlueSky',\n",
       " 'speed': 1,\n",
       " 'state': 'RUN',\n",
       " 'utc_datetime': '2020-06-11 00:00:02',\n",
       " 'aircraft_ids': ['VJ159', 'VJ405']}"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pydodo.simulation_info()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2.3 Viewing the simulation\n",
    "\n",
    "You can also have a look at the sector and scenario in the simulation through `twitcher` by going to <a href=\"http://localhost:8080/\" target=\"_blank\">localhost:8080</a>.\n",
    "\n",
    "Depending on the sector loaded, you should see something similar to the image below:\n",
    "\n",
    "![Twitcher sector visualisation](twitcher.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Example usage <a class=\"anchor\" id=\"third-section\"></a>\n",
    "\n",
    "See the Dodo [Specification document](https://github.com/alan-turing-institute/dodo/blob/master/Specification.md) for a detailed overview of the supported commands.\n",
    "\n",
    "Below we show some of them."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.1 Query aircraft positions, again"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>aircraft_type</th>\n",
       "      <th>cleared_flight_level</th>\n",
       "      <th>current_flight_level</th>\n",
       "      <th>ground_speed</th>\n",
       "      <th>heading</th>\n",
       "      <th>latitude</th>\n",
       "      <th>longitude</th>\n",
       "      <th>requested_flight_level</th>\n",
       "      <th>vertical_speed</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <td>VJ159</td>\n",
       "      <td>A346</td>\n",
       "      <td>400</td>\n",
       "      <td>39990.7375</td>\n",
       "      <td>199</td>\n",
       "      <td>0</td>\n",
       "      <td>49.394783</td>\n",
       "      <td>-0.1275</td>\n",
       "      <td>400</td>\n",
       "      <td>-570</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <td>VJ405</td>\n",
       "      <td>B77W</td>\n",
       "      <td>200</td>\n",
       "      <td>20000.0000</td>\n",
       "      <td>140</td>\n",
       "      <td>180</td>\n",
       "      <td>53.572395</td>\n",
       "      <td>-0.1275</td>\n",
       "      <td>400</td>\n",
       "      <td>0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "      aircraft_type  cleared_flight_level  current_flight_level  ground_speed  \\\n",
       "VJ159          A346                   400            39990.7375           199   \n",
       "VJ405          B77W                   200            20000.0000           140   \n",
       "\n",
       "       heading   latitude  longitude  requested_flight_level  vertical_speed  \n",
       "VJ159        0  49.394783    -0.1275                     400            -570  \n",
       "VJ405      180  53.572395    -0.1275                     400               0  "
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pydodo.all_positions()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.2 Check aircraft route"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'next_waypoint': 'FIYRE',\n",
       " 'route_name': 'ASCENSION',\n",
       " 'route_waypoints': ['FIYRE', 'EARTH', 'WATER', 'AIR', 'SPIRT'],\n",
       " 'aircraft_id': 'VJ159'}"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pydodo.list_route('VJ159')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.3 Step through the simulation\n",
    "\n",
    "By default, the simulation is in a paused state. To advance it, we need to call the `simulation_step` function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pydodo.simulation_step()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This should result in the aircraft positions changing:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>aircraft_type</th>\n",
       "      <th>cleared_flight_level</th>\n",
       "      <th>current_flight_level</th>\n",
       "      <th>ground_speed</th>\n",
       "      <th>heading</th>\n",
       "      <th>latitude</th>\n",
       "      <th>longitude</th>\n",
       "      <th>requested_flight_level</th>\n",
       "      <th>vertical_speed</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <td>VJ159</td>\n",
       "      <td>A346</td>\n",
       "      <td>400</td>\n",
       "      <td>37314.5</td>\n",
       "      <td>215</td>\n",
       "      <td>0</td>\n",
       "      <td>49.601878</td>\n",
       "      <td>-0.1275</td>\n",
       "      <td>400</td>\n",
       "      <td>-1500</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <td>VJ405</td>\n",
       "      <td>B77W</td>\n",
       "      <td>200</td>\n",
       "      <td>20000.0</td>\n",
       "      <td>187</td>\n",
       "      <td>180</td>\n",
       "      <td>53.410675</td>\n",
       "      <td>-0.1275</td>\n",
       "      <td>400</td>\n",
       "      <td>0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "      aircraft_type  cleared_flight_level  current_flight_level  ground_speed  \\\n",
       "VJ159          A346                   400               37314.5           215   \n",
       "VJ405          B77W                   200               20000.0           187   \n",
       "\n",
       "       heading   latitude  longitude  requested_flight_level  vertical_speed  \n",
       "VJ159        0  49.601878    -0.1275                     400           -1500  \n",
       "VJ405      180  53.410675    -0.1275                     400               0  "
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pydodo.all_positions()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.4 Change altitude\n",
    "\n",
    "We can also instruct the aircraft to change their path (e.g., heading or altitude).\n",
    "\n",
    "Below we instruct aircraft VJ405 to start climbing. This is followed by a step through the simulation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pydodo.change_altitude(\"VJ405\", flight_level = 300)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pydodo.simulation_step()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Checking aircraft positions now, we should see a change in the `current_flight_level` as the aircraft starts climbing:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>aircraft_type</th>\n",
       "      <th>cleared_flight_level</th>\n",
       "      <th>current_flight_level</th>\n",
       "      <th>ground_speed</th>\n",
       "      <th>heading</th>\n",
       "      <th>latitude</th>\n",
       "      <th>longitude</th>\n",
       "      <th>requested_flight_level</th>\n",
       "      <th>vertical_speed</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <td>VJ405</td>\n",
       "      <td>B77W</td>\n",
       "      <td>30000</td>\n",
       "      <td>20430.5</td>\n",
       "      <td>196</td>\n",
       "      <td>180</td>\n",
       "      <td>53.376168</td>\n",
       "      <td>-0.1275</td>\n",
       "      <td>400</td>\n",
       "      <td>1500</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "      aircraft_type  cleared_flight_level  current_flight_level  ground_speed  \\\n",
       "VJ405          B77W                 30000               20430.5           196   \n",
       "\n",
       "       heading   latitude  longitude  requested_flight_level  vertical_speed  \n",
       "VJ405      180  53.376168    -0.1275                     400            1500  "
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pydodo.aircraft_position(\"VJ405\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Example OpenAI interface <a class=\"anchor\" id=\"fourth-section\"></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## TO DO!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 5. Shut down the simulator"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Stopping twitcher ... \n",
      "Stopping bluebird ... \n",
      "Stopping bluesky  ... \n",
      "\u001b[1Bping bluesky  ... \u001b[32mdone\u001b[0m\u001b[2A\u001b[2K\u001b[1A\u001b[2KRemoving twitcher ... \n",
      "Removing bluebird ... \n",
      "Removing bluesky  ... \n",
      "\u001b[2BRemoving network simurgh_default[1A\u001b[2K\n"
     ]
    }
   ],
   "source": [
    "!docker-compose down"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}