docs/tutorials/facade-usage.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using oemof.tabular.facades\n",
    "\n",
    "This ipython-notebook is designed to describe the usage and functionality of the facades that are based on the [oemof.solph](https://oemof.readthedocs.io/en/stable/oemof_solph.html) package. If you are scripting and writing your own model you can easily use the classes provided by solph. The main potential of the facades is to provide \n",
    "an easy interface when defining the energy system in a input datapackage or any other tabular source. To see how you can do this have a look at the `model-from-tabular-data.ipynb` example. \n",
    "\n",
    "\n",
    "**NOTE**: Numeric values in this example are not representative for any energy system and just randomly selected. Also this model is not necessarily a feasible optimization problem. It is **only** designed for illustration of class usage. \n",
    "\n",
    "\n",
    "\n",
    "Author:\n",
    "\n",
    "Simon.Hilpert (@uni-flensburg.de), Europa Universitaet Flensburg, March 2019"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Python Imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "\n",
    "from oemof.solph import EnergySystem, Model, Bus\n",
    "import oemof.tabular.facades as fc\n",
    "\n",
    "# for simplicity we just use 3 timesteps\n",
    "es = EnergySystem(timeindex=pd.date_range('2018', periods=3, freq='H'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Bus\n",
    "\n",
    "First we will create the required buses for this example. As these objects will be used when instantiating the components, we assign them to python variables and add these to the energy system object `es` using ist `.add()` method. The `balanced` (default: True) argument can be used to relax the energy balance for a bus, i.e. all inputs do not have to sum with all output flows to zero any longer.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "elec_bus = Bus(label=\"elec_bus\")\n",
    "elec_bus_1 = Bus(label=\"elec_bus_1\")\n",
    "heat_bus = Bus(label=\"heat_bus\")\n",
    "fuel_bus = Bus(label=\"fuel_bus\", balanced=True)\n",
    "\n",
    "es.add(elec_bus, elec_bus_1, heat_bus, fuel_bus)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Volatile\n",
    "\n",
    "This class can be used to model PV oder Wind power plants. The equations for this component are:\n",
    "\n",
    "$$x_{wind}^{flow} = c_{wind}^{capacity} \\cdot c_{wind}^{profile}(t) \\qquad \\forall t \\in T$$\n",
    "\n",
    "Where $x_{wind}^{flow}$ denotes the production (endogenous variable) of the volatile object to the bus. \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "es.add(\n",
    "    fc.Volatile(\n",
    "        label=\"wind\",\n",
    "        carrier=\"wind\",\n",
    "        tech=\"onshore\",\n",
    "        capacity=150,\n",
    "        bus=elec_bus,\n",
    "        profile=[0.2, 0.3, 0.25],\n",
    "    )\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Volatile component investment \n",
    "If the investment mode is used, i.e. `capacity_cost` attribute not None and `capacity` attribute set to None \n",
    "the right hand side of the equation changes as the exogenous variable $c^{capacity}$ is now replaced by an endognous variable.  \n",
    "\n",
    "$$x^{f,ow}_{wind} \\leq x^{capacity}_{wind} \\cdot c^{profile}_{wind}(t) \\qquad \\forall t \\in T$$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "es.add(\n",
    "    fc.Volatile(\n",
    "        label=\"wind_invest\",\n",
    "        carrier=\"wind\",\n",
    "        tech=\"onshore\",\n",
    "        capacity_cost=200,\n",
    "        exapandable=True,\n",
    "        bus=elec_bus,\n",
    "        profile=[0.2, 0.3, 0.25],\n",
    "    )\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Dispatchable\n",
    "\n",
    "The `Dispatchble` component works very similar to the volatile component. The only difference here is the $\\leq$ \n",
    "sign in the constraint, which allows to dispatch the power within the limit of the lower and upper bounds.\n",
    "\n",
    "$$x_{flow}^{elec\\_bus} \\leq c_{ccgt}^{capacity} \\cdot c_{ccgt}^{profile}(t) \\qquad \\forall t \\in T$$\n",
    "\n",
    "**NOTE**: \n",
    "\n",
    "You can also set the parameters for the output of this component by using the argument `output_parameters`. To see all options see: [oemof Flow](https://oemof.readthedocs.io/en/stable/api/oemof.solph.html#oemof.solph.network.Flow)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "es.add(\n",
    "    fc.Dispatchable(\n",
    "        bus=elec_bus,\n",
    "        label=\"ccgt\",\n",
    "        carrier=\"gas\",\n",
    "        tech=\"ccgt\",\n",
    "        capacity=100,\n",
    "        marginal_cost=25,\n",
    "        output_parameters={\n",
    "            'summed_min': 1000,\n",
    "            'summed_max': 2000}\n",
    "    )\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Reservoir\n",
    "\n",
    "The reservoir component inherit from the [GenericStorage](https://oemof.readthedocs.io/en/stable/api/oemof.solph.html#oemof.solph.components.GenericStorage). However the input of the reservoir is not taken from the bus but defined as an absolute inflow to the reservoir from a source. This source object is created under the hood interanally when a `Reservoir` object is instantiated. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "es.add(\n",
    "    fc.Reservoir(\n",
    "        bus=elec_bus,\n",
    "        label=\"rsv\",\n",
    "        carrier=\"hydro\",\n",
    "        tech=\"reservoir\",\n",
    "        capacity=150,\n",
    "        storage_capacity=1500,\n",
    "        efficiency=0.9,\n",
    "        profile=[10, 5, 3],\n",
    "        initial_storage_level=1, # oemof.solph arguments\n",
    "        balanced=False # oemof.solph argument\n",
    "    )\n",
    ")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Storage\n",
    "\n",
    "The Storage component is based on the [GenericStorage](https://oemof.readthedocs.io/en/stable/api/oemof.solph.html#oemof.solph.components.GenericStorage) class of `oemof.solph`. Therefore you may use all arguments that exist for the parent class in addition to the ones defined for the component itself."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "es.add(\n",
    "    fc.Storage(\n",
    "        label=\"storage\",\n",
    "        bus=elec_bus,\n",
    "        carrier=\"lithium\",\n",
    "        tech=\"battery\",\n",
    "        capacity_cost=10,\n",
    "        expandable=True,\n",
    "        invest_relation_output_capacity=1/6, # oemof.solph\n",
    "        marginal_cost=5,\n",
    "        balanced=True, # oemof.solph argument\n",
    "        initial_storage_level=1, # oemof.solph argument\n",
    "        max_storage_level=[0.9, 0.95, 0.8], # oemof.solph argument\n",
    "    )\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Extraction and Backpressure Turbine \n",
    "\n",
    "The extraction turbine facade directly inherit from the [ExtractionTurbineCHP](https://oemof.readthedocs.io/en/stable/api/oemof.solph.html#oemof.solph.components.ExtractionTurbineCHP) class where as the backpressure facade directly inherit from the [Transformer](https://oemof.readthedocs.io/en/stable/api/oemof.solph.html#oemof.solph.network.Transformer) class.\n",
    "\n",
    "Both components may also be used in the investment mode by setting the capacity costs. The capacity cost are related to the electrical output of the component, i.e. Euro/MWhel.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "es.add(\n",
    "    fc.ExtractionTurbine(\n",
    "        label=\"ext\",\n",
    "        electricity_bus=elec_bus,\n",
    "        heat_bus=heat_bus,\n",
    "        fuel_bus=fuel_bus,\n",
    "        carrier='gas',\n",
    "        tech='ext',\n",
    "        capacity=10,\n",
    "        condensing_efficiency=0.5,\n",
    "        electric_efficiency=0.4,\n",
    "        thermal_efficiency=0.3\n",
    "    )\n",
    ")\n",
    "\n",
    "es.add(\n",
    "    fc.BackpressureTurbine(\n",
    "        label=\"bp\",\n",
    "        electricity_bus=elec_bus,\n",
    "        heat_bus=heat_bus,\n",
    "        fuel_bus=fuel_bus,\n",
    "        carrier='gas',\n",
    "        tech='bp',\n",
    "        capacity=10,\n",
    "        electric_efficiency=0.4,\n",
    "        thermal_efficiency=0.3\n",
    "    )\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Conversion \n",
    "\n",
    "The conversion component is a simplified interface to the [Transformer](https://oemof.readthedocs.io/en/stable/api/oemof.solph.html#oemof.solph.network.Transformer) class with the **restriction of 1 input and 1 output**. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "es.add(\n",
    "    fc.Conversion(\n",
    "        label='pth',\n",
    "        from_bus=elec_bus,\n",
    "        to_bus=heat_bus,\n",
    "        carrier='electricity',\n",
    "        tech='hp',\n",
    "        capacity=10,\n",
    "        capacity_cost=54,\n",
    "        expandable=True,\n",
    "        capacity_potential=20,\n",
    "        efficiency=0.9,\n",
    "        thermal_efficiency=0.3\n",
    "    )\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Commodity\n",
    "\n",
    "A commodity can be used to model a limited source for the complete time horizon of the problem.\n",
    "\n",
    "$$\\sum_t x^{flow}_{fuel}(t) \\leq c^{amount}_{fuel} $$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "es.add(\n",
    "    fc.Commodity(\n",
    "        label='fuel',\n",
    "        bus=fuel_bus,\n",
    "        amount=1000000,\n",
    "        carrier='fuel',\n",
    "        tech='commodity',\n",
    "        marginal_cost=0.5\n",
    "    )\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Link\n",
    "\n",
    "This component also just provides an simpliefied interface for the [Link](https://oemof.readthedocs.io/en/stable/api/oemof.solph.html#oemof.solph.custom.Link) of the oemof solph package. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "es.add(\n",
    "    fc.Link(\n",
    "        label='link',\n",
    "        from_bus=elec_bus,\n",
    "        to_bus=elec_bus_1,\n",
    "        loss=0.05,\n",
    "        capacity=100\n",
    "    )\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Load \n",
    "\n",
    "The load is similar to the `Volatile` component, except that it acts as a sink (1-input). Therefore you may also use the argument `input_parameters` to adapt its behaviour. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "es.add(\n",
    "    fc.Load(\n",
    "        label=\"elec_load\", \n",
    "        bus=elec_bus, \n",
    "        amount=500e3, \n",
    "        profile=[0.4, 0.1, 0.5]))\n",
    "\n",
    "es.add(\n",
    "    fc.Load(\n",
    "        label=\"heat_load\", \n",
    "        bus=heat_bus, \n",
    "        amount=200e3, \n",
    "        profile=[0.1, 0.23, 0.7]))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Adding Other oemof.solph Components\n",
    "\n",
    "As the energy system and all components are solph based objects you may add any other oemof.solph object to your energy system. This is straight forward when you are scripting. The full levearge of the facades is however gained when using the datapackage reader. For this datapackage reader **only** facades are working in a proper way. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Create Model and Inspect"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "m = Model(es)\n",
    "\n",
    "# uncommet to get lp-file (path will be of this file)\n",
    "# m.write(io_options={'symbolic_solver_labels': True})\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "m.InvestmentFlow.pprint()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "m.Flow.pprint()"
   ]
  }
 ],
 "metadata": {
  "@webio": {
   "lastCommId": null,
   "lastKernelId": null
  },
  "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.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}