tutorials/building_a_controller.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Building a Controller"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The following documents the development of a new controller.\n",
    "In this case we are going to implement an arbitrary controllable storage unit. This\n",
    "may be a battery, an electrically powered car or some sort of reservoir storage."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Modelling a Battery\n",
    "\n",
    "In order to simulate a storage system we use the storage element of pandapower. The power of a storage can be positive or negative. To overcome this issue, a storage element can be created. \n",
    "\n",
    "For storage elements the signing is based on the consumer viewpoint (positive active power means power consumption and therefore charging of the battery).\n",
    "\n",
    "As pandapower is not a time dependend simulation tool and there is no time domain parameter in default power flow calculations, the state of charge (SoC) is not updated during any power flow calculation. \n",
    "In Order to update the SoC we build our own storage controller and keep track of the SoC.\n",
    "\n",
    "State of charge (SoC [\\%]) is the level of charge of an electric battery relative to its capacity.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Controller init\n",
    "First we start by creating a new file *control/storage_control.py*, containing our new class."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Import and inherit from the parent class `Controller` and override methods you would like to use. Next we write the actual code for the methods."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandapower as pp\n",
    "from pandapower import control\n",
    "import pandas as pd\n",
    "from pandapower import timeseries as ts\n",
    "\n",
    "# importing a grid from the library\n",
    "from pandapower.networks import mv_oberrhein\n",
    "\n",
    "\n",
    "class Storage(control.basic_controller.Controller):\n",
    "    \"\"\"\n",
    "        Example class of a Storage-Controller. Models an abstract energy storage.\n",
    "    \"\"\"\n",
    "    def __init__(self, net, element_index, data_source=None, p_profile=None, in_service=True,\n",
    "                 recycle=False, order=0, level=0, **kwargs):\n",
    "        super().__init__(net, in_service=in_service, recycle=recycle, order=order, level=level,\n",
    "                    initial_powerflow = True, **kwargs)\n",
    "        \n",
    "        # read generator attributes from net\n",
    "        self.element_index = element_index  # index of the controlled storage\n",
    "        self.bus = net.storage.at[element_index, \"bus\"]\n",
    "        self.p_mw = net.storage.at[element_index, \"p_mw\"]\n",
    "        self.q_mvar = net.storage.at[element_index, \"q_mvar\"]\n",
    "        self.sn_mva = net.storage.at[element_index, \"sn_mva\"]\n",
    "        self.name = net.storage.at[element_index, \"name\"]\n",
    "        self.gen_type = net.storage.at[element_index, \"type\"]\n",
    "        self.in_service = net.storage.at[element_index, \"in_service\"]\n",
    "        self.applied = False\n",
    "\n",
    "        # specific attributes\n",
    "        self.max_e_mwh = net.storage.at[element_index, \"max_e_mwh\"]\n",
    "        self.soc_percent = net.storage.at[element_index, \"soc_percent\"] = 0\n",
    "        \n",
    "        # profile attributes\n",
    "        self.data_source = data_source\n",
    "        self.p_profile = p_profile\n",
    "        self.last_time_step = None\n",
    "        \n",
    "    # We choose to represent the storage-unit as a storage element in pandapower. \n",
    "    # We start with a function calculating the amout of stored energy:    \n",
    "    def get_stored_ernergy(self):\n",
    "        # calculating the stored energy\n",
    "        return self.max_e_mwh * self.soc_percent / 100        \n",
    "    \n",
    "    # convergence check\n",
    "    # Also remember that 'is_converged()' returns the boolean value of convergence:\n",
    "    def is_converged(self, net):\n",
    "        # check if controller already was applied\n",
    "        return self.applied\n",
    "    \n",
    "    # Also a first step we want our controller to be able to write its P and Q and state of charge values back to the\n",
    "    # data structure net.\n",
    "    def write_to_net(self, net):\n",
    "        # write p, q and soc_percent to bus within the net\n",
    "        net.storage.at[self.element_index, \"p_mw\"] = self.p_mw\n",
    "        net.storage.at[self.element_index, \"q_mvar\"] = self.q_mvar\n",
    "        net.storage.at[self.element_index, \"soc_percent\"]= self.soc_percent\n",
    "        \n",
    "    # In case the controller is not yet converged, the control step is executed. In the example it simply\n",
    "    # adopts a new value according to the previously calculated target and writes back to the net.\n",
    "    def control_step(self, net):\n",
    "        # Call write_to_net and set the applied variable True\n",
    "        self.write_to_net(net)\n",
    "        self.applied = True\n",
    "        \n",
    "    # In a time-series simulation the battery should read new power values from a profile and keep track\n",
    "    # of its state of charge as depicted below.\n",
    "    def time_step(self, net, time):\n",
    "        # keep track of the soc (assuming time is given in 15min values)\n",
    "        if self.last_time_step is not None:\n",
    "            # The amount of Energy produce or consumed in the last timestep is added relative to the \n",
    "            # maximum of the possible stored energy\n",
    "            self.soc_percent += (self.p_mw * (time-self.last_time_step) * 15 / 60) / self.max_e_mwh * 100\n",
    "        self.last_time_step = time\n",
    "\n",
    "        # read new values from a profile\n",
    "        if self.data_source:\n",
    "            if self.p_profile is not None:\n",
    "                self.p_mw = self.data_source.get_time_step_value(time_step=time,\n",
    "                                                                profile_name=self.p_profile)\n",
    "                \n",
    "        self.applied = False # reset applied variable"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We are now ready to create objects of our newly implemented class and simulate with it!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "hp.pandapower.io_utils - WARNING: pandapowerNet-version (3.0.0) is newer than your pandapower version (2.15.0). Please update pandapower `pip install --upgrade pandapower`.\n",
      "hp.pandapower.control.util.auxiliary - INFO: Creating controller 0 of type <class '__main__.Storage'> \n"
     ]
    }
   ],
   "source": [
    "# importing a grid from the library\n",
    "from pandapower.networks import mv_oberrhein\n",
    "\n",
    "# loading the network with the usecase 'generation'\n",
    "net = mv_oberrhein()\n",
    "pp.runpp(net)\n",
    "\n",
    "# creating a simple time series\n",
    "framedata = pd.DataFrame([0.1, .05, 0.1, .005, -0.2, 0], columns=['P'])\n",
    "datasource = ts.DFData(framedata)\n",
    "\n",
    "# creating storage unit in the grid, which will be controlled by our controller\n",
    "store_el = pp.create_storage(net, 30, p_mw = .1, q_mvar = 0, max_e_mwh = 0.1, )\n",
    "\n",
    "# creating an Object of our new build storage controller, controlling the storage unit\n",
    "ctrl = Storage(net=net, element_index=store_el, data_source=datasource,p_profile='P')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we run a small time-series-simulation and track the results using the outputwriter:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "100%|██████████| 6/6 [00:00<00:00, 20.77it/s]\n"
     ]
    }
   ],
   "source": [
    "# defining an OutputWriter to track certain variables\n",
    "ow = ts.OutputWriter(net)\n",
    "\n",
    "ow.log_variable(\"res_storage\", \"p_mw\")\n",
    "ow.log_variable(\"storage\", \"soc_percent\")\n",
    "\n",
    "# starting time series simulation\n",
    "ts.run_timeseries(net, time_steps=range(0, 6))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To visualize the results we plot directly with the dataframe:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<matplotlib.legend.Legend at 0x1da18e3b6d0>"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "# plotting the state of charge\n",
    "ow.output['storage.soc_percent'].columns = ['Battery']\n",
    "ax = ow.output['storage.soc_percent'].plot()\n",
    "ax.set_xlabel('Time in 15min Steps')\n",
    "ax.set_ylabel('State of Charge in %')\n",
    "ax.legend()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The state of charge grows until a certain point and drops in the end following the give values from the timeseries. The time windows between each timestep and the reactive power values define the amount of stored or consumed energy.\n",
    "\n",
    "In the shown case a SoC of more than 100\\% would be possible, because the SoC just gets summed up.\n",
    "To make the controller more realistic you could implement tresholds for the SoC and different initial SoC-values. Try to experiment!"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.10.11 ('base')",
   "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.10.11"
  },
  "vscode": {
   "interpreter": {
    "hash": "19d1d53a962d236aa061289c2ac16dc8e6d9648c89fe79f459ae9a3493bc67b4"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}