{
 "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": 1,
   "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, gid, 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.gid = gid  # index of the controlled storage\n",
    "        self.bus = net.storage.at[gid, \"bus\"]\n",
    "        self.p_mw = net.storage.at[gid, \"p_mw\"]\n",
    "        self.q_mvar = net.storage.at[gid, \"q_mvar\"]\n",
    "        self.sn_mva = net.storage.at[gid, \"sn_mva\"]\n",
    "        self.name = net.storage.at[gid, \"name\"]\n",
    "        self.gen_type = net.storage.at[gid, \"type\"]\n",
    "        self.in_service = net.storage.at[gid, \"in_service\"]\n",
    "        self.applied = False\n",
    "\n",
    "        # specific attributes\n",
    "        self.max_e_mwh = net.storage.at[gid, \"max_e_mwh\"]\n",
    "        self.soc_percent = net.storage.at[gid, \"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.gid, \"p_mw\"] = self.p_mw\n",
    "        net.storage.at[self.gid, \"q_mvar\"] = self.q_mvar\n",
    "        net.storage.at[self.gid, \"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": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "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, gid=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": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "100%|████████████████████████████████████████████████████████████████████████████████████| 6/6 [00:00<00:00, 12.18it/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": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<matplotlib.legend.Legend at 0x19c51aa2220>"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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\n",
      "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 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}