tutorials/topology.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Topological Searches in pandapower"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is an introduction into the pandapower module topology. The topology module provides topoligical searches and analyses for pandapower networks based on the NetworkX library. This tutorial will show you how to get started and demonstrate a few use cases of the module. For a full documentation of the topology functions, see the pandapower documentation.\n",
    "\n",
    "To demonstrate the usage of the topology module we will use the medium voltage open ring from the simple pandapower test networks:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandapower.networks as nw\n",
    "net = nw.simple_mv_open_ring_net()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating MultiGraphs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The pandapower topology package provides a function to translate a pandapower network into an [networkx multigraph](https://networkx.github.io/documentation/networkx-1.9.1/reference/classes.multigraph.html):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandapower.topology as top\n",
    "mg = top.create_nxgraph(net) # converts example network into a MultiGraph "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This picture visualises the conversion: On the left hand side you can see what our example network looks like, on the right hand side how it gets converted into a MultiGraph.\n",
    "\n",
    "<img src=\"pics/multigraph_example.png\">\n",
    "    \n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Algorithms from the NetworkX package\n",
    "\n",
    "The bus numbers in the networkx graph are the same as the bus indices in pandapower. You can now use all [networkx algorithms](https://networkx.github.io/documentation/networkx-1.9.1/reference/algorithms.html) to perform graph searches on the network."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### shortest path"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To find the [shortest path](https://networkx.github.io/documentation/networkx-1.9.1/reference/algorithms.shortest_paths.html) between nodes bus0 and bus5:\n",
    "\n",
    "<img src=\"pics/nx_shortest_path.png\">"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[0, 1, 6, 5]"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import networkx as nx\n",
    "path = nx.shortest_path(mg, 0, 5)\n",
    "path"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This will algorithm will find the shortest path in terms of number of visited buses. The length of the lines is encoded in the weight parameter of the edges. If we want to find the shortest path in terms of shortest line length, we have to pass the weight parameter to the search:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[0, 1, 6, 5]"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "path = nx.shortest_path(mg, 0, 5, weight=\"weight\")\n",
    "path"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this case the search of course yields the same path, since there is only one path from bus0 to bus5.\n",
    "\n",
    "Since the bus indices in the graph and in the pandapower network are the same, we can use the path to directly access buses in pandapower:"
   ]
  },
  {
   "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>name</th>\n",
       "      <th>vn_kv</th>\n",
       "      <th>type</th>\n",
       "      <th>zone</th>\n",
       "      <th>in_service</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>110 kV bar</td>\n",
       "      <td>110.0</td>\n",
       "      <td>b</td>\n",
       "      <td>None</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>20 kV bar</td>\n",
       "      <td>20.0</td>\n",
       "      <td>b</td>\n",
       "      <td>None</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>6</th>\n",
       "      <td>bus 6</td>\n",
       "      <td>20.0</td>\n",
       "      <td>b</td>\n",
       "      <td>None</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>bus 5</td>\n",
       "      <td>20.0</td>\n",
       "      <td>b</td>\n",
       "      <td>None</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "         name  vn_kv type  zone  in_service\n",
       "0  110 kV bar  110.0    b  None        True\n",
       "1   20 kV bar   20.0    b  None        True\n",
       "6       bus 6   20.0    b  None        True\n",
       "5       bus 5   20.0    b  None        True"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "net.bus.loc[path]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "gives us all buses on the shortest path between bus0 and bus5. We can also use the bus indices to find branch elements directly in pandapower. For example, to find all lines on the path:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "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>name</th>\n",
       "      <th>std_type</th>\n",
       "      <th>from_bus</th>\n",
       "      <th>to_bus</th>\n",
       "      <th>length_km</th>\n",
       "      <th>r_ohm_per_km</th>\n",
       "      <th>x_ohm_per_km</th>\n",
       "      <th>c_nf_per_km</th>\n",
       "      <th>g_us_per_km</th>\n",
       "      <th>max_i_ka</th>\n",
       "      <th>df</th>\n",
       "      <th>parallel</th>\n",
       "      <th>type</th>\n",
       "      <th>in_service</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>line 5</td>\n",
       "      <td>NA2XS2Y 1x185 RM/25 12/20 kV</td>\n",
       "      <td>6</td>\n",
       "      <td>1</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.161</td>\n",
       "      <td>0.117</td>\n",
       "      <td>273.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.362</td>\n",
       "      <td>1.0</td>\n",
       "      <td>1</td>\n",
       "      <td>cs</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>line 4</td>\n",
       "      <td>NA2XS2Y 1x185 RM/25 12/20 kV</td>\n",
       "      <td>5</td>\n",
       "      <td>6</td>\n",
       "      <td>1.0</td>\n",
       "      <td>0.161</td>\n",
       "      <td>0.117</td>\n",
       "      <td>273.0</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0.362</td>\n",
       "      <td>1.0</td>\n",
       "      <td>1</td>\n",
       "      <td>cs</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "     name                      std_type  from_bus  to_bus  length_km  \\\n",
       "5  line 5  NA2XS2Y 1x185 RM/25 12/20 kV         6       1        1.0   \n",
       "4  line 4  NA2XS2Y 1x185 RM/25 12/20 kV         5       6        1.0   \n",
       "\n",
       "   r_ohm_per_km  x_ohm_per_km  c_nf_per_km  g_us_per_km  max_i_ka   df  \\\n",
       "5         0.161         0.117        273.0          0.0     0.362  1.0   \n",
       "4         0.161         0.117        273.0          0.0     0.362  1.0   \n",
       "\n",
       "   parallel type  in_service  \n",
       "5         1   cs        True  \n",
       "4         1   cs        True  "
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "net.line.loc[top.elements_on_path(mg, path, \"line\")]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or all transformers on this path:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "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>name</th>\n",
       "      <th>std_type</th>\n",
       "      <th>hv_bus</th>\n",
       "      <th>lv_bus</th>\n",
       "      <th>sn_mva</th>\n",
       "      <th>vn_hv_kv</th>\n",
       "      <th>vn_lv_kv</th>\n",
       "      <th>vk_percent</th>\n",
       "      <th>vkr_percent</th>\n",
       "      <th>pfe_kw</th>\n",
       "      <th>...</th>\n",
       "      <th>tap_neutral</th>\n",
       "      <th>tap_min</th>\n",
       "      <th>tap_max</th>\n",
       "      <th>tap_step_percent</th>\n",
       "      <th>tap_step_degree</th>\n",
       "      <th>tap_pos</th>\n",
       "      <th>tap_phase_shifter</th>\n",
       "      <th>parallel</th>\n",
       "      <th>df</th>\n",
       "      <th>in_service</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>None</td>\n",
       "      <td>25 MVA 110/20 kV</td>\n",
       "      <td>0</td>\n",
       "      <td>1</td>\n",
       "      <td>25.0</td>\n",
       "      <td>110.0</td>\n",
       "      <td>20.0</td>\n",
       "      <td>12.0</td>\n",
       "      <td>0.41</td>\n",
       "      <td>14.0</td>\n",
       "      <td>...</td>\n",
       "      <td>0</td>\n",
       "      <td>-9</td>\n",
       "      <td>9</td>\n",
       "      <td>1.5</td>\n",
       "      <td>0.0</td>\n",
       "      <td>0</td>\n",
       "      <td>False</td>\n",
       "      <td>1</td>\n",
       "      <td>1.0</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "<p>1 rows × 23 columns</p>\n",
       "</div>"
      ],
      "text/plain": [
       "   name          std_type  hv_bus  lv_bus  sn_mva  vn_hv_kv  vn_lv_kv  \\\n",
       "0  None  25 MVA 110/20 kV       0       1    25.0     110.0      20.0   \n",
       "\n",
       "   vk_percent  vkr_percent  pfe_kw     ...      tap_neutral  tap_min tap_max  \\\n",
       "0        12.0         0.41    14.0     ...                0       -9       9   \n",
       "\n",
       "   tap_step_percent  tap_step_degree  tap_pos  tap_phase_shifter  parallel  \\\n",
       "0               1.5              0.0        0              False         1   \n",
       "\n",
       "    df  in_service  \n",
       "0  1.0        True  \n",
       "\n",
       "[1 rows x 23 columns]"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "net.trafo.loc[top.elements_on_path(mg, path, \"trafo\")]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### customizing graph conversion"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now suppose we want to find the shortest path distance between bus2 and bus6 without going through the transformer substation, but allowing to go over open switches. The path we are looking for is therefore bus6 --> bus5 --> bus4 --> bus3 --> bus2.\n",
    "\n",
    "This is not a path in the graph above though, since there is no edge between bus4 and bus5. We translate the graph with respect_switches=False to include the line with an open switch in the graph:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "mg = top.create_nxgraph(net, respect_switches=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"pics/multigraph_example_respect_switches.png\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we still have the problem that the shortest path algorithm will find the path over the substation (bus1) as the shortest path:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[6, 1, 2]"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nx.shortest_path(mg, 6, 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To prevent this, we can specify bus1 as a nogobus in the conversion, which means it will not be translated to the networkx graph:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "mg = top.create_nxgraph(net, respect_switches=False, nogobuses={1})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we get the path that we were looking for:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[6, 5, 4, 3, 2]"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "nx.shortest_path(mg, 6, 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### cycles\n",
    "\n",
    "We can also use the [cycle algorithms](https://networkx.github.io/documentation/networkx-1.9.1/reference/algorithms.cycles.html) to find cycles in the network. Cycle algorithms only work on undirected graphs, which is why we need to specify multi=False in the graph conversion:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[]"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mg = top.create_nxgraph(net, multi=False)\n",
    "nx.cycle_basis(mg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are no cycles in the network, which confirms the radiality of the network. If we do not respect the switches, we will find the ring as a cycle:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[[2, 3, 4, 5, 6, 1]]"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mg = top.create_nxgraph(net, respect_switches=False, multi=False)\n",
    "nx.cycle_basis(mg)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Algorithms in the topology package"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Besides from using networkx algorithms, there are some custom algorithms in the pandapower.topology package. For a full list with explanation see the pandapower documentation. Here, we only cover the two most important ones: connected_component and connected_components."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Connected component"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The connected component function returns all buses that are connected to a bus in the networkx graph. Suppose we want to find all buses that are on the same feeder as bus 2. We set bus1 as a nogobus and search for all buses connected to bus 2:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "mg = top.create_nxgraph(net, nogobuses={1})\n",
    "area = top.connected_component(mg, 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This generator contains all buses connected to bus2:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{2, 3, 4}"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "set(area)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We get the buses 2,3 and 4, but not bus1, since it was defined as a nogobus. If we want to get bus1 as connected to bus2, but still not go over bus2, we can define bus1 as a notravbus instead of a nogobus. This means that search algorithms will find the bus as connected, but not traverse it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{1, 2, 3, 4}"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mg = top.create_nxgraph(net, notravbuses={1})\n",
    "set(top.connected_component(mg, 2))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Connected components"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we don't want to find the area connected to one specific bus, but rather all areas that are connected, we can use the connected_components function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{2, 3, 4}\n",
      "{5, 6}\n"
     ]
    }
   ],
   "source": [
    "mg = top.create_nxgraph(net, nogobuses={0, 1})\n",
    "for area in top.connected_components(mg):\n",
    "    print(area)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once again, we can alternatively use notravbuses to get the substation bus in the areas:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{1}\n",
      "{1, 2, 3, 4}\n",
      "{1, 5, 6}\n"
     ]
    }
   ],
   "source": [
    "mg = top.create_nxgraph(net, nogobuses={0}, notravbuses={1})\n",
    "for area in top.connected_components(mg):\n",
    "    print(area)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we want to avoid getting the notravbus as an own area, we can alternatively pass the notravbuses argument directly to the connected_components search instead of to the graph conversion:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{1, 2, 3, 4}\n",
      "{1, 5, 6}\n"
     ]
    }
   ],
   "source": [
    "mg = top.create_nxgraph(net, nogobuses={0})\n",
    "for area in top.connected_components(mg, notravbuses={1}):\n",
    "    print(area)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For more examples of topological searches in pandapower, see the documentation of the topology package."
   ]
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "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.6.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}