tutorial/westeros/westeros_multinode_energy_trade.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Westeros Tutorial - Trade in multi-node energy systems\n",
    "\n",
    "In this tutorial, we demonstrate how a multinode energy system can be built using the *MESSAGEix* framework. The aim of this tutorial is to show:\n",
    "\n",
    "- how new nodes can be added to a model and how data can be populated for those new nodes\n",
    "- how a trade hub can be represented\n",
    "- how bilateral trade can be modeled\n",
    "- the role of the `message_ix` index set \"mode\" in representing trade links\n",
    "\n",
    "\n",
    "**Pre-requisites for running this tutorial**\n",
    "- You have the *MESSAGEix* framework installed and working.\n",
    "- You have run Westeros baseline scenario (``westeros_baseline.ipynb``) and solved it successfully.\n",
    "\n",
    "This tutorial was presented by [Behnam Zakeri](https://iiasa.ac.at/staff/behnam-zakeri) at the **MESSAGEix Community Meeting** May 2022. Please feel free to suggest improvements through issues and pull-requests."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ixmp\n",
    "\n",
    "# Loading the modeling platform\n",
    "mp = ixmp.Platform()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Adding new nodes and populating input data for them\n",
    "\n",
    "First, we clone the existing scenario \"baseline\" as the basis for our multinode model. Next, we add two model regions called \"Essos\" and \"Stepstones\" as two neighboring regions of Westeros (for more details on the geography of the system we are discussing, please refer to [this Wiki](https://gameofthrones.fandom.com/wiki/Westeros)). Then, we solve the model for this three-node system and check the outcome. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "This Scenario has a solution, use `Scenario.remove_solution()` or `Scenario.clone(..., keep_solution=False)`\n"
     ]
    }
   ],
   "source": [
    "from message_ix import Scenario\n",
    "\n",
    "# Loading baseline scenario\n",
    "model = \"Westeros Electrified\"\n",
    "scenario = \"baseline\"\n",
    "base = Scenario(mp, model, scenario)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's make sure our \"baseline\" scenario has a solution. We will need this solution later, as we will compare the output of different scenarios. If your \"baseline\" does not have a solution, i.e., you get an output of `False` from the cell below, please run ``westeros_baseline.ipynb`` and solve it again."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Check if the \"baseline\" scenario has a solution\n",
    "base.has_solution()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Cloning \"baseline\" to a new scenario for our work\n",
    "new_scenario = \"multinode\"\n",
    "scen = base.clone(scenario=new_scenario, keep_solution=False)\n",
    "\n",
    "# Checking out the scenario for editing\n",
    "scen.check_out()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.1. Adding new nodes\n",
    "Adding new nodes to a *MESSAGEix* scenario is like adding elements to any other sets, i.e., by using the method `add_set()`. The framework does not assign any relationship between nodes being added though `add_set()`. This means no \"parent\" node or hirerarchy can be defined."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Adding new nodes to the set \"node\"\n",
    "nodes_new = [\"Essos\", \"Stepstones\"]\n",
    "scen.add_set(\"node\", nodes_new)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0         World\n",
       "1      Westeros\n",
       "2         Essos\n",
       "3    Stepstones\n",
       "dtype: object"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Let's check the set of \"node\"\n",
    "scen.set(\"node\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 1.2. Populating data for the new nodes\n",
    "By now, the model has no data related to these new nodes, e.g., no technology parameter is defined for them. Here, we can copy the data of \"Westeros\" to the new nodes. This way, we do not have to repeat all the steps for adding input data as we did for \"Westeros\" in ``westeros_baseline.ipynb`` for each new node. We can simply use `message_ix.rename()` feature and keep the original node (\"Westeros\") by using `keep=True`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Copying data from \"Westeros\" to the new nodes\n",
    "for node in nodes_new:\n",
    "    scen.rename(\"node\", {\"Westeros\": node}, keep=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's check and see if the new nodes are correctly added to parameters, e.g., in parameter `demand` in one of the model years."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "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>node</th>\n",
       "      <th>commodity</th>\n",
       "      <th>level</th>\n",
       "      <th>year</th>\n",
       "      <th>time</th>\n",
       "      <th>value</th>\n",
       "      <th>unit</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Westeros</td>\n",
       "      <td>light</td>\n",
       "      <td>useful</td>\n",
       "      <td>700</td>\n",
       "      <td>year</td>\n",
       "      <td>55.0</td>\n",
       "      <td>GWa</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Essos</td>\n",
       "      <td>light</td>\n",
       "      <td>useful</td>\n",
       "      <td>700</td>\n",
       "      <td>year</td>\n",
       "      <td>55.0</td>\n",
       "      <td>GWa</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Stepstones</td>\n",
       "      <td>light</td>\n",
       "      <td>useful</td>\n",
       "      <td>700</td>\n",
       "      <td>year</td>\n",
       "      <td>55.0</td>\n",
       "      <td>GWa</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "         node commodity   level  year  time  value unit\n",
       "0    Westeros     light  useful   700  year   55.0  GWa\n",
       "1       Essos     light  useful   700  year   55.0  GWa\n",
       "2  Stepstones     light  useful   700  year   55.0  GWa"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "scen.par(\"demand\", {\"year\": 700})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we can see from the DataFrame above, the data has been populated for the new nodes, with equal values to \"Westeros\". Now, let's commit changes and solve the scenario and see what happens..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Committing and solving\n",
    "scen.commit(\"new nodes added\")\n",
    "scen.solve()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Right! the scenario solved (hopefully for you too). As the input data were the same for the three nodes, we expect output results will be the same too. Let's check some output like \"activity\" (`ACT`) for a technology in a specific year:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "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>node_loc</th>\n",
       "      <th>technology</th>\n",
       "      <th>year_vtg</th>\n",
       "      <th>year_act</th>\n",
       "      <th>mode</th>\n",
       "      <th>time</th>\n",
       "      <th>lvl</th>\n",
       "      <th>mrg</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Westeros</td>\n",
       "      <td>wind_ppl</td>\n",
       "      <td>690</td>\n",
       "      <td>700</td>\n",
       "      <td>standard</td>\n",
       "      <td>year</td>\n",
       "      <td>12.176560</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Westeros</td>\n",
       "      <td>wind_ppl</td>\n",
       "      <td>700</td>\n",
       "      <td>700</td>\n",
       "      <td>standard</td>\n",
       "      <td>year</td>\n",
       "      <td>1.560259</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Essos</td>\n",
       "      <td>wind_ppl</td>\n",
       "      <td>690</td>\n",
       "      <td>700</td>\n",
       "      <td>standard</td>\n",
       "      <td>year</td>\n",
       "      <td>12.176560</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>Essos</td>\n",
       "      <td>wind_ppl</td>\n",
       "      <td>700</td>\n",
       "      <td>700</td>\n",
       "      <td>standard</td>\n",
       "      <td>year</td>\n",
       "      <td>1.560259</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>Stepstones</td>\n",
       "      <td>wind_ppl</td>\n",
       "      <td>690</td>\n",
       "      <td>700</td>\n",
       "      <td>standard</td>\n",
       "      <td>year</td>\n",
       "      <td>12.176560</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>Stepstones</td>\n",
       "      <td>wind_ppl</td>\n",
       "      <td>700</td>\n",
       "      <td>700</td>\n",
       "      <td>standard</td>\n",
       "      <td>year</td>\n",
       "      <td>1.560259</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "     node_loc technology  year_vtg  year_act      mode  time        lvl  mrg\n",
       "0    Westeros   wind_ppl       690       700  standard  year  12.176560  0.0\n",
       "1    Westeros   wind_ppl       700       700  standard  year   1.560259  0.0\n",
       "2       Essos   wind_ppl       690       700  standard  year  12.176560  0.0\n",
       "3       Essos   wind_ppl       700       700  standard  year   1.560259  0.0\n",
       "4  Stepstones   wind_ppl       690       700  standard  year  12.176560  0.0\n",
       "5  Stepstones   wind_ppl       700       700  standard  year   1.560259  0.0"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "scen.var(\"ACT\", {\"technology\": \"wind_ppl\", \"year_act\": 700})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You should see equal results for all nodes. Now, we have a three-node model, but as there is no link between the three nodes, and their input data is exactly the same, the output results are also the same. In the next section, we use this model to add trade links."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Representing  a trade hub in a multi-node model\n",
    "In this part, we model a trade hub. A trade hub is like a pool that each node can use to export energy commodities to, or import from. Examples can be a central electricity grid in a country, to which many cities and power plants are connected. Or this can be an energy market where bilateral trade is not important to track, but only buyers and sellers are relevant. The schematic below shows possible configurations of a trade hub. \n",
    "In a trade hub:\n",
    "- import to and export from the hub in each node may have capacity (size)\n",
    "- there is no bilateral trade between nodes\n",
    "- the hub may have capacity (size)\n",
    "\n",
    "<img src='_static/hub.JPG'>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "# We clone a new scenario and call it \"scen2\"\n",
    "scen2 = scen.clone(scenario=\"multinode_hub\", keep_solution=False)\n",
    "scen2.check_out()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.1. Adding information related to the trade hub\n",
    "We need to specify at a minimum the following information in the model for a simple trade hub:\n",
    "- a \"node\" name for the location of the trade hub: we add a new node called \"hub\"\n",
    "- a \"level\" name for importing/exporting energy commodity: we add a new level called \"trade\"\n",
    "- import and export technologies in each node\n",
    "\n",
    "Please note that we would need to add more detail, if we wanted to represent the size of the hub, i.e.:\n",
    "- a \"level\" name from which energy commodity is imported\n",
    "- a \"level\" name to which energy commodity is exported \n",
    "- a \"technology\" representing the trade size in the hub\n",
    "\n",
    "But for the sake of simplicity, we skip the trade size (capacity) parameters here."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Adding new set elements for the hub\n",
    "scen2.add_set(\"node\", \"hub\")\n",
    "scen2.add_set(\"level\", \"trade\")\n",
    "\n",
    "# Adding new electricity import and export technologies\n",
    "scen2.add_set(\"technology\", [\"elec_imp\", \"elec_exp\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.2. Linking import/export technologies to the hub\n",
    "Representing a network or trade link in *MESSAGEix* can be done through `input` and `output` parameters. This means there is no specific parameter related to trade. Both `input` and `output` parameters are defined with two indexes related to the location.\n",
    "\n",
    "For example, `input` of a technology can be defined with respect to where that technology is located (`node_loc`), and where the input commodity of that technology originates from (`node_origin`). For the `output` parameter, the destination of the output commodity can be defined by `node_dest`. You can check these index names by running the `Scenario.idx_names()` method (see below).\n",
    "\n",
    "For linking electricity import and export technologies to the hub, we use the level of \"secondary\" in the Westeros model, which is the point before the transmission and distribution (T&D) grid in each node."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['node_loc',\n",
       " 'technology',\n",
       " 'year_vtg',\n",
       " 'year_act',\n",
       " 'mode',\n",
       " 'node_origin',\n",
       " 'commodity',\n",
       " 'level',\n",
       " 'time',\n",
       " 'time_origin']"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Checking index names of a parameter (useful when adding data to that parameter)\n",
    "scen2.idx_names(\"input\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0    electricity\n",
       "1          light\n",
       "dtype: object"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "scen2.set(\"commodity\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 2.2.1. Parametrization of `input` and `output` for import technologies\n",
    "Here, we show the general parametrization of 'input' and 'output'. We will add a loss due to efficiency of the system in the next step."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "from message_ix import make_df\n",
    "\n",
    "# Parametrization of \"input\" for import technologies\n",
    "# The origin of import is the level of \"trade\" from hub\n",
    "model_years = list(scen2.set(\"year\"))\n",
    "base_input = {\n",
    "    \"node_origin\": \"hub\",\n",
    "    \"technology\": \"elec_imp\",\n",
    "    \"commodity\": \"electricity\",\n",
    "    \"level\": \"trade\",\n",
    "    \"year_vtg\": model_years,\n",
    "    \"year_act\": model_years,\n",
    "    \"mode\": \"standard\",\n",
    "    \"time\": \"year\",\n",
    "    \"time_origin\": \"year\",\n",
    "    \"value\": 1,\n",
    "    \"unit\": \"-\",\n",
    "}\n",
    "\n",
    "# We add this data for each node (other than \"hub\")\n",
    "for country in [\"Westeros\", \"Essos\", \"Stepstones\"]:\n",
    "    inp = make_df(\"input\", **base_input, node_loc=country)\n",
    "    scen2.add_par(\"input\", inp)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Parametrization of \"output\" for import technologies\n",
    "# The destination of import is the level of \"secondary\" in each country\n",
    "base_output = {\n",
    "    \"technology\": \"elec_imp\",\n",
    "    \"commodity\": \"electricity\",\n",
    "    \"level\": \"secondary\",\n",
    "    \"year_vtg\": model_years,\n",
    "    \"year_act\": model_years,\n",
    "    \"mode\": \"standard\",\n",
    "    \"time\": \"year\",\n",
    "    \"time_dest\": \"year\",\n",
    "    \"value\": 1,\n",
    "    \"unit\": \"-\",\n",
    "}\n",
    "\n",
    "# We add this data for each node (other than \"hub\")\n",
    "for country in [\"Westeros\", \"Essos\", \"Stepstones\"]:\n",
    "    out = make_df(\"output\", **base_output, node_loc=country, node_dest=country)\n",
    "    scen2.add_par(\"output\", out)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 2.2.2. Adding loss due to efficiency of the system\n",
    "We assume a 5% loss of electricity when trading in the hub for each node. This can be represented as 1.05 input value for each 1 output unit of electricity."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [],
   "source": [
    "# The origin of export is the level of \"secondary\" in each country\n",
    "for country in [\"Westeros\", \"Essos\", \"Stepstones\"]:\n",
    "    base_input.update(\n",
    "        dict(technology=\"elec_exp\", node_origin=country, level=\"secondary\", value=1.05)\n",
    "    )\n",
    "    inp = make_df(\"input\", **base_input, node_loc=country)\n",
    "    scen2.add_par(\"input\", inp)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "# The destination of export is the level of \"trade\" in the hub\n",
    "for country in [\"Westeros\", \"Essos\", \"Stepstones\"]:\n",
    "    base_output.update(dict(technology=\"elec_exp\", node_dest=\"hub\", level=\"trade\"))\n",
    "    out = make_df(\"output\", **base_output, node_loc=country)\n",
    "    scen2.add_par(\"output\", out)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.3. Modifying `demand` and solving\n",
    "We change the demand for \"light\", as such for electricity, in the nodes \"Essos\" and \"Stepstones\", by +15% and -50% relative to \"Westeros\", repsectively. This is for illustration purposes, but can be based on population, daylight time, etc. in these nodes. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Changing \"demand\" in Essos and Stepstones\n",
    "change = {\"Essos\": +0.15, \"Stepstones\": -0.5}\n",
    "for node, value in change.items():\n",
    "    # Loading data of \"demand\"\n",
    "    df = scen2.par(\"demand\", {\"node\": node})\n",
    "    # Multiplying by the value\n",
    "    df[\"value\"] *= 1 + value\n",
    "    # Adding new demand to the scenario\n",
    "    scen2.add_par(\"demand\", df)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Committing and solving\n",
    "scen2.commit(\"new nodes added\")\n",
    "scen2.solve()\n",
    "scen2.set_as_default()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Checking the results\n",
    "Let's check the output results to see if any trade has occured or not:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "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>node_loc</th>\n",
       "      <th>technology</th>\n",
       "      <th>year_vtg</th>\n",
       "      <th>year_act</th>\n",
       "      <th>mode</th>\n",
       "      <th>time</th>\n",
       "      <th>lvl</th>\n",
       "      <th>mrg</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Westeros</td>\n",
       "      <td>elec_imp</td>\n",
       "      <td>700</td>\n",
       "      <td>700</td>\n",
       "      <td>standard</td>\n",
       "      <td>year</td>\n",
       "      <td>1.560259</td>\n",
       "      <td>0.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Westeros</td>\n",
       "      <td>elec_exp</td>\n",
       "      <td>700</td>\n",
       "      <td>700</td>\n",
       "      <td>standard</td>\n",
       "      <td>year</td>\n",
       "      <td>0.000000</td>\n",
       "      <td>36.794377</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Essos</td>\n",
       "      <td>elec_imp</td>\n",
       "      <td>700</td>\n",
       "      <td>700</td>\n",
       "      <td>standard</td>\n",
       "      <td>year</td>\n",
       "      <td>10.726926</td>\n",
       "      <td>0.000000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>Essos</td>\n",
       "      <td>elec_exp</td>\n",
       "      <td>700</td>\n",
       "      <td>700</td>\n",
       "      <td>standard</td>\n",
       "      <td>year</td>\n",
       "      <td>0.000000</td>\n",
       "      <td>36.794377</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>Stepstones</td>\n",
       "      <td>elec_imp</td>\n",
       "      <td>700</td>\n",
       "      <td>700</td>\n",
       "      <td>standard</td>\n",
       "      <td>year</td>\n",
       "      <td>0.000000</td>\n",
       "      <td>35.042264</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>Stepstones</td>\n",
       "      <td>elec_exp</td>\n",
       "      <td>700</td>\n",
       "      <td>700</td>\n",
       "      <td>standard</td>\n",
       "      <td>year</td>\n",
       "      <td>12.287186</td>\n",
       "      <td>0.000000</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "     node_loc technology  year_vtg  year_act      mode  time        lvl  \\\n",
       "0    Westeros   elec_imp       700       700  standard  year   1.560259   \n",
       "1    Westeros   elec_exp       700       700  standard  year   0.000000   \n",
       "2       Essos   elec_imp       700       700  standard  year  10.726926   \n",
       "3       Essos   elec_exp       700       700  standard  year   0.000000   \n",
       "4  Stepstones   elec_imp       700       700  standard  year   0.000000   \n",
       "5  Stepstones   elec_exp       700       700  standard  year  12.287186   \n",
       "\n",
       "         mrg  \n",
       "0   0.000000  \n",
       "1  36.794377  \n",
       "2   0.000000  \n",
       "3  36.794377  \n",
       "4  35.042264  \n",
       "5   0.000000  "
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "scen2.var(\"ACT\", {\"technology\": [\"elec_imp\", \"elec_exp\"], \"year_act\": 700})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 2.4. Role of trade\n",
    "Looking at the results of activity (`ACT`), we can see that the electricity trade is balanced, i.e., the sum of imports equals the sume of exports in each year. \"Stepstones\" is the exporter as demand for lighting is the lowest in this node and extra electricity can be exported to the other two nodes with higher demand.\n",
    "\n",
    "> **Note:** In this example, we represented trade simply with activity. In more realistic examples, trade links can be modeled with capacity related parameters, i.e., lifetime, investment, capacity factor, etc.\n",
    "\n",
    "#### Questions:\n",
    "- Compare the price of electricity in \"Westeros\" before and after the trade? What is the role of trade? (Tip: you can use variable `PRICE_COMMODITY` to compare the prices between \"baseline\" and trade scenarios)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Solution:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "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>node</th>\n",
       "      <th>commodity</th>\n",
       "      <th>level</th>\n",
       "      <th>year</th>\n",
       "      <th>time</th>\n",
       "      <th>lvl</th>\n",
       "      <th>mrg</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Westeros</td>\n",
       "      <td>light</td>\n",
       "      <td>useful</td>\n",
       "      <td>700</td>\n",
       "      <td>year</td>\n",
       "      <td>511.028293</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Westeros</td>\n",
       "      <td>light</td>\n",
       "      <td>useful</td>\n",
       "      <td>710</td>\n",
       "      <td>year</td>\n",
       "      <td>162.039539</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Westeros</td>\n",
       "      <td>light</td>\n",
       "      <td>useful</td>\n",
       "      <td>720</td>\n",
       "      <td>year</td>\n",
       "      <td>161.002627</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "       node commodity   level  year  time         lvl  mrg\n",
       "0  Westeros     light  useful   700  year  511.028293  0.0\n",
       "1  Westeros     light  useful   710  year  162.039539  0.0\n",
       "2  Westeros     light  useful   720  year  161.002627  0.0"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "base.var(\"PRICE_COMMODITY\", {\"commodity\": \"light\"})"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "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>node</th>\n",
       "      <th>commodity</th>\n",
       "      <th>level</th>\n",
       "      <th>year</th>\n",
       "      <th>time</th>\n",
       "      <th>lvl</th>\n",
       "      <th>mrg</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Westeros</td>\n",
       "      <td>light</td>\n",
       "      <td>useful</td>\n",
       "      <td>700</td>\n",
       "      <td>year</td>\n",
       "      <td>166.445336</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Westeros</td>\n",
       "      <td>light</td>\n",
       "      <td>useful</td>\n",
       "      <td>710</td>\n",
       "      <td>year</td>\n",
       "      <td>162.039539</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Westeros</td>\n",
       "      <td>light</td>\n",
       "      <td>useful</td>\n",
       "      <td>720</td>\n",
       "      <td>year</td>\n",
       "      <td>161.002627</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>Essos</td>\n",
       "      <td>light</td>\n",
       "      <td>useful</td>\n",
       "      <td>700</td>\n",
       "      <td>year</td>\n",
       "      <td>166.445336</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>Essos</td>\n",
       "      <td>light</td>\n",
       "      <td>useful</td>\n",
       "      <td>710</td>\n",
       "      <td>year</td>\n",
       "      <td>162.039539</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>Essos</td>\n",
       "      <td>light</td>\n",
       "      <td>useful</td>\n",
       "      <td>720</td>\n",
       "      <td>year</td>\n",
       "      <td>161.002627</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>Stepstones</td>\n",
       "      <td>light</td>\n",
       "      <td>useful</td>\n",
       "      <td>700</td>\n",
       "      <td>year</td>\n",
       "      <td>161.402965</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>7</th>\n",
       "      <td>Stepstones</td>\n",
       "      <td>light</td>\n",
       "      <td>useful</td>\n",
       "      <td>710</td>\n",
       "      <td>year</td>\n",
       "      <td>162.039539</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>8</th>\n",
       "      <td>Stepstones</td>\n",
       "      <td>light</td>\n",
       "      <td>useful</td>\n",
       "      <td>720</td>\n",
       "      <td>year</td>\n",
       "      <td>161.002627</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "         node commodity   level  year  time         lvl  mrg\n",
       "0    Westeros     light  useful   700  year  166.445336  0.0\n",
       "1    Westeros     light  useful   710  year  162.039539  0.0\n",
       "2    Westeros     light  useful   720  year  161.002627  0.0\n",
       "3       Essos     light  useful   700  year  166.445336  0.0\n",
       "4       Essos     light  useful   710  year  162.039539  0.0\n",
       "5       Essos     light  useful   720  year  161.002627  0.0\n",
       "6  Stepstones     light  useful   700  year  161.402965  0.0\n",
       "7  Stepstones     light  useful   710  year  162.039539  0.0\n",
       "8  Stepstones     light  useful   720  year  161.002627  0.0"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "scen2.var(\"PRICE_COMMODITY\", {\"commodity\": \"light\"})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Bilateral trade\n",
    "In this part, we model bilateral trade links, i.e., direct trade between two nodes. A bilateral trade representation is useful when it is important to link importer and exporter nodes via an infrastructure that cannot be shared with other nodes. Bilateral trade in a multi-node model can form a \"meshed\" network of capacitated lines. Therefore, nodes can trade commodities, if an economic trade route subject to possible losses exists between exporting and importing nodes.\n",
    "\n",
    "For the bilateral trade, again, we use `input` and `output` parameters to link trading nodes directly. Bilateral trade can exist in one direction (one-way), such as the flow of water from one node to another, or bi-directional (two-way), such as an electricity transmission line.\n",
    "\n",
    "<img src='_static/bilateral.JPG'>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [],
   "source": [
    "# We clone a new scenario and call it \"scen3\"\n",
    "scen3 = scen2.clone(scenario=\"multinode_bilateral\", keep_solution=False)\n",
    "scen3.check_out()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [],
   "source": [
    "# We remove previous trade links\n",
    "for tec in [\"elec_exp\", \"elec_imp\"]:\n",
    "    scen3.remove_set(\"technology\", tec)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.1. Bilateral trade and \"mode\" of operation\n",
    "We can represent bilateral trade similar to the Part (2) above, i.e., with two distinct import and export technologies. Alternatively, we can only use one technology for the trade link, but with two \"mode\"s of operation, i.e., import and export.\n",
    "\n",
    "Using \"mode\" of operation is useful when the import and export links are a single technology, like electricity interconnectors. When using \"mode\", the \"capacity\" related parameters are the same for the technology, but \"activity\" related parameters should be defined per \"mode\".\n",
    "\n",
    "We need to specify the following information in the model for a direct bilateral bi-dimensional trade link:\n",
    "- a \"node\" name for the location of the trade link: we use the \"hub\" node.\n",
    "- a single trade technology: we add \"elec_trade\"\n",
    "- two \"mode\"s of operation for the trade link."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Adding new electricity trade technology\n",
    "scen3.add_set(\"technology\", [\"elec_trade\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 3.2. Linking two nodes\n",
    "For linking two nodes through a single electricity trade technology, we should decide where the location of this technology is. The trade link can be located in either of the nodes, and so, will have the investment and costs related to that node.\n",
    "\n",
    "In this case, we choose the node \"hub\" as the location of the trade link between two nodes of \"Westeros\" and \"Stepstones\". However, the user can decide to set the location of a trade link in the node of origin or destination based on their case study. In this example, this does not change anything in the results. But if the trade link had `inv_cost`, a node that is the location of the trade link would bear that investment.\n",
    "\n",
    "We directly link the two nodes at the level of \"secondary\", which is the point before the transmission and distribution (T&D) grid in each node."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Adding modes for the bilateral trade\n",
    "# We add \"W-to-S\" for Westeros --> Stepstone; and \"S-to-W\" for the opposite direction\n",
    "scen3.add_set(\"mode\", [\"W-to-S\", \"S-to-W\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 3.2.1. Parametrization of `input` and `output` for the bilateral two-way trade link\n",
    "Similar to the Part 2, we parametrize `input` and `output` parameters for the trade link. We assume a 5% loss of electricity in each direction. This can be represented as 1.05 input value for each 1 output unit of electricity."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Parametrization of \"input\" for the trade link in the first direction\n",
    "# We assign the \"mode\" of \"W-to-S\" for the direction of trade\n",
    "# from Westeros --> Stepstones\n",
    "base_input = {\n",
    "    \"node_origin\": \"Westeros\",\n",
    "    \"technology\": \"elec_trade\",\n",
    "    \"commodity\": \"electricity\",\n",
    "    \"level\": \"secondary\",\n",
    "    \"year_vtg\": model_years,\n",
    "    \"year_act\": model_years,\n",
    "    \"mode\": \"W-to-S\",\n",
    "    \"time\": \"year\",\n",
    "    \"time_origin\": \"year\",\n",
    "    \"value\": 1.05,\n",
    "    \"unit\": \"-\",\n",
    "}\n",
    "\n",
    "# We add this data to the model\n",
    "inp = make_df(\"input\", **base_input, node_loc=\"hub\")\n",
    "scen3.add_par(\"input\", inp)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Parametrization of \"output\" for the trade link in the first direction\n",
    "# We assign the \"mode\" of \"W-to-S\" for the direction of trade\n",
    "# from Westeros --> Stepstones\n",
    "base_output = {\n",
    "    \"node_dest\": \"Stepstones\",\n",
    "    \"technology\": \"elec_trade\",\n",
    "    \"commodity\": \"electricity\",\n",
    "    \"level\": \"secondary\",\n",
    "    \"year_vtg\": model_years,\n",
    "    \"year_act\": model_years,\n",
    "    \"mode\": \"W-to-S\",\n",
    "    \"time\": \"year\",\n",
    "    \"time_dest\": \"year\",\n",
    "    \"value\": 1,\n",
    "    \"unit\": \"-\",\n",
    "}\n",
    "\n",
    "# We add this data to the scenario\n",
    "out = make_df(\"output\", **base_output, node_loc=\"hub\")\n",
    "scen3.add_par(\"output\", out)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Parametrization of \"input\" for the trade link in the second direction\n",
    "# We assign the \"mode\" of \"S-to-W\" for the direction of trade\n",
    "# from Stepstones --> Westeros\n",
    "base_input.update(dict(node_origin=\"Stepstones\", mode=\"S-to-W\"))\n",
    "inp = make_df(\"input\", **base_input, node_loc=\"hub\")\n",
    "scen3.add_par(\"input\", inp)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Parametrization of \"output\" for the trade link in the second direction\n",
    "# We assign the \"mode\" of \"S-to-W\" for the direction of trade\n",
    "# from Stepstones --> Westeros\n",
    "base_output.update(dict(node_dest=\"Westeros\", mode=\"S-to-W\"))\n",
    "out = make_df(\"output\", **base_output, node_loc=\"hub\")\n",
    "scen3.add_par(\"output\", out)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### 3.2.2. Parametrization of bilateral trade but only in one direction\n",
    "For illustration, we make an electricity transmission link between nodes \"Westeros\" and \"Essos\", but only in one direction, from \"Westeros\". The difference here is that we do not need to add a second \"mode\" of operation to the trade link. We use a new technology \"elec_export\" for this trade link. We assume a 5% loss of electricity in each direction. This can be represented as 1.05 input value for each 1 output unit of electricity."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Parametrization of \"input\" for the one-way trade link\n",
    "# Origin is Westeros\n",
    "# We assign the \"mode\" of \"standard\" as there is only one direction\n",
    "scen3.add_set(\"technology\", \"elec_export\")\n",
    "base_input.update(\n",
    "    dict(node_origin=\"Westeros\", technology=\"elec_export\", mode=\"standard\")\n",
    ")\n",
    "inp = make_df(\"input\", **base_input, node_loc=\"hub\")\n",
    "scen3.add_par(\"input\", inp)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Parametrization of \"output\" for the one-way trade link\n",
    "# Destination is Essos\n",
    "base_output.update(dict(node_dest=\"Essos\", technology=\"elec_export\", mode=\"standard\"))\n",
    "out = make_df(\"output\", **base_output, node_loc=\"hub\")\n",
    "scen3.add_par(\"output\", out)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Committing and solving\n",
    "scen3.commit(\"new nodes added\")\n",
    "scen3.solve()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's check the output results to see if any trade has occured between the nodes or not:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "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>node_loc</th>\n",
       "      <th>technology</th>\n",
       "      <th>year_vtg</th>\n",
       "      <th>year_act</th>\n",
       "      <th>mode</th>\n",
       "      <th>time</th>\n",
       "      <th>lvl</th>\n",
       "      <th>mrg</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>hub</td>\n",
       "      <td>elec_trade</td>\n",
       "      <td>700</td>\n",
       "      <td>700</td>\n",
       "      <td>W-to-S</td>\n",
       "      <td>year</td>\n",
       "      <td>0.000000</td>\n",
       "      <td>71.83664</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>hub</td>\n",
       "      <td>elec_trade</td>\n",
       "      <td>700</td>\n",
       "      <td>700</td>\n",
       "      <td>S-to-W</td>\n",
       "      <td>year</td>\n",
       "      <td>12.823532</td>\n",
       "      <td>0.00000</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>hub</td>\n",
       "      <td>elec_export</td>\n",
       "      <td>700</td>\n",
       "      <td>700</td>\n",
       "      <td>standard</td>\n",
       "      <td>year</td>\n",
       "      <td>10.726926</td>\n",
       "      <td>0.00000</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "  node_loc   technology  year_vtg  year_act      mode  time        lvl  \\\n",
       "0      hub   elec_trade       700       700    W-to-S  year   0.000000   \n",
       "1      hub   elec_trade       700       700    S-to-W  year  12.823532   \n",
       "2      hub  elec_export       700       700  standard  year  10.726926   \n",
       "\n",
       "        mrg  \n",
       "0  71.83664  \n",
       "1   0.00000  \n",
       "2   0.00000  "
      ]
     },
     "execution_count": 36,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "scen3.var(\"ACT\", {\"technology\": [\"elec_trade\", \"elec_export\"], \"year_act\": 700})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "###  3.3. Role of trade\n",
    "The results of activity (`ACT`) show that the electricity trade is in the mode of \"S-to-W\", i.e., from Stepstones to Westeros, in the bi-directional line. Stepstones is the exporter as demand for lighting is the lowest in this node, while the potential supply technologies are the same. Hence, the relatively cheaper electricity can be exported to Westeros with higher demand. Further, Westeros exports to Essos, as the latter has the highest demand for electricity. Here, Westeros is acting as an intermediate node in the trade network to pass electricity from Stepstones to Essos, of course with additional losses. Because there is no trade possibilities between Stepstones and Essos directly.\n",
    "\n",
    "#### Questions:\n",
    "- Why is the price of \"light\" higher in Essos than Westeros in year 700? (Compare this with Part 2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "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>node</th>\n",
       "      <th>commodity</th>\n",
       "      <th>level</th>\n",
       "      <th>year</th>\n",
       "      <th>time</th>\n",
       "      <th>lvl</th>\n",
       "      <th>mrg</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Westeros</td>\n",
       "      <td>light</td>\n",
       "      <td>useful</td>\n",
       "      <td>700</td>\n",
       "      <td>year</td>\n",
       "      <td>166.445336</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Essos</td>\n",
       "      <td>light</td>\n",
       "      <td>useful</td>\n",
       "      <td>700</td>\n",
       "      <td>year</td>\n",
       "      <td>171.739825</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Stepstones</td>\n",
       "      <td>light</td>\n",
       "      <td>useful</td>\n",
       "      <td>700</td>\n",
       "      <td>year</td>\n",
       "      <td>161.402965</td>\n",
       "      <td>0.0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "         node commodity   level  year  time         lvl  mrg\n",
       "0    Westeros     light  useful   700  year  166.445336  0.0\n",
       "1       Essos     light  useful   700  year  171.739825  0.0\n",
       "2  Stepstones     light  useful   700  year  161.402965  0.0"
      ]
     },
     "execution_count": 37,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "scen3.var(\"PRICE_COMMODITY\", {\"commodity\": \"light\", \"year\": 700})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exercise: Trade with an external market/system\n",
    "We demonstrated the possibilites for a hub-based and bilateral trade representation in MESSAGEix. In some case studies, a trade link needs to be facilitated with an external market or system, e.g., to neighbouring nodes or to the world outside of the boundary of the modeled nodes. This is very common, as it is not possible or desirable to model all neighbouring regions or the external system, and a model needs to be limited to a certain boundary. Hence, each node individually and/or the hub can be linked to an external market (e.g., to global commodity markets represented at \"World\").\n",
    "\n",
    "<img src='_static\\external.JPG'>\n",
    "\n",
    "In this exercise, you should establish trade with an external market in the Westeros multi-node model. This trade link can be through a hub or directly from a node. You can specify the price of electricity ($/kWa) in the external market as follows: {690: 100, 700: 97, 710: 93, 720: 87}."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<details>\n",
    "  <summary><font size=\"3\" color=\"darkgreen\"><b>Click for hints</b></font></summary>\n",
    "       \n",
    "   * We can model this by adding an electricity importing technology that imports electricity to the node \"hub\". This technology, however, has no `input` parameter (because we do not model the commodity balance outside of the boundary of our model).\n",
    "    However, we can define `var_cost` for this trade link to represent the price of commodity in the external market.\n",
    "    \n",
    "<details>\n",
    "   <summary><font size=\"3\" color=\"darkblue\"><b>Click for the code</b></font></summary>\n",
    "\n",
    "```python\n",
    "# We clone a new scenario from the scenario with a central hub.\n",
    "scen2 = message_ix.Scenario(mp, model, \"multinode_hub\")\n",
    "scen4 = scen2.clone(scenario=\"multinode_hub_external_trade\", keep_solution=False)\n",
    "scen4.check_out()\n",
    "# We link the central hub to an external electricity market.\n",
    "# First, we add a new technology:\n",
    "scen4.add_set(\"technology\", \"elec_external_imp\")\n",
    "# Then, we define parameter \"output\" for importing electricity to \"hub\"\n",
    "# Here, we don't need to define \"input\", as this is considered outside the boundary\n",
    "# conditions of our model\n",
    "base_output = {\n",
    "    \"node_dest\": \"hub\",\n",
    "    \"node_loc\": \"hub\",\n",
    "    \"technology\": \"elec_external_imp\",\n",
    "    \"commodity\": \"electricity\",\n",
    "    \"level\": \"trade\",\n",
    "    \"year_vtg\": model_years,\n",
    "    \"year_act\": model_years,\n",
    "    \"mode\": \"standard\",\n",
    "    \"time\": \"year\",\n",
    "    \"time_dest\": \"year\",\n",
    "    \"value\": 1,\n",
    "    \"unit\": \"-\",\n",
    "}\n",
    "# We add this data to the scenario\n",
    "scen4.add_par(\"output\", make_df(\"output\", **base_output))\n",
    "# At this stage, imported electricity has no cost. We define variable cost for that as\n",
    "# asked in the question.\n",
    "base_output.update({\"value\": [100, 97, 93, 87], \"unit\": \"USD/kWa\"})\n",
    "scen4.add_par(\"var_cost\", make_df(\"var_cost\", **base_output))\n",
    "scen4.commit(\"\")\n",
    "# Finally, we can solve the scenario\n",
    "scen4.solve()\n",
    "# Let's check the price of electricity\n",
    "print(\n",
    "    \"Price of electricity:\\n\",\n",
    "    scen4.var(\"PRICE_COMMODITY\", {\"commodity\": \"electricity\", \"node\": \"hub\"}),\n",
    ")\n",
    "# We observe that the price of electricity in years 710 and 720 is set by the cost of\n",
    "# importing electricity. But in 700 the cost of trading electricity at the internal hub\n",
    "# is lower than the cost of importing. Hence, if we check the activity of the import\n",
    "# technology, it should not show any import in 700 (see column \"lvl\"):\n",
    "print(\n",
    "    \"Activity of the electricity importing technology:\\n\",\n",
    "    scen4.var(\"ACT\", {\"technology\": \"elec_external_imp\"}),\n",
    ")\n",
    "```\n",
    "\n",
    "</details>\n",
    "</details>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Close the connection to the database at the end\n",
    "mp.close_db()"
   ]
  }
 ],
 "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.12.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}