{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Standard Type Library"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Pandapower provides a standard type library that allows the comfortable managing of type data for lines and transformers.\n",
    "\n",
    "The following examples are all based on lines, but can be equally used for the transformer database by specifying element=\"trafo\" instead of element=\"line\" in all standard type functions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Basic Pandapower Standard Types"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Pandapower comes with generic standard types that you can use to build generic networks:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "import pandapower as pp\n",
    "net = pp.create_empty_network()\n",
    "pp.available_std_types(net, element=\"line\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you create a line with the create_line function, the element parameters are taken from this library:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "b1 = pp.create_bus(net, vn_kv=.4)\n",
    "b2 = pp.create_bus(net, vn_kv=.4)\n",
    "lid = pp.create_line(net, from_bus=b1, to_bus=b2, length_km=0.1, std_type=\"NAYY 4x50 SE\", name=\"test_line\")\n",
    "net.line.loc[lid]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create Individual Standard Types"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Additionally to the basic pandapower standard types, you can define individual standard types for you pandapower network.\n",
    "\n",
    "To create a new standard type you need at least the following parameters:\n",
    "\n",
    "**For Lines**:\n",
    "- r_ohm_per_km\n",
    "- x_ohm_per_km\n",
    "- c_nf_per_km\n",
    "- max_i_ka\n",
    "\n",
    "**For Transformers:**\n",
    "- sn_mva\n",
    "- vn_hv_kv\n",
    "- vn_lv_kv\n",
    "- vk_percent\n",
    "- vkr_percent\n",
    "- i0_percent\n",
    "- pfe_kw\n",
    "- shift_degree\n",
    "\n",
    "To define the parameters, create a dictionary with the style {\"parameter1\": parameter_value1, \"parameter2\": paramter_value2,...} and save the standard type to your network with the create_std_type function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "net = pp.create_empty_network()\n",
    "test_type = {\"r_ohm_per_km\": 0.01, \"x_ohm_per_km\": 0.02, \"c_nf_per_km\": 10, \"max_i_ka\": 0.4, \"type\": \"cs\"}\n",
    "pp.create_std_type(net, name=\"test_type\", data=test_type, element=\"line\")\n",
    "pp.available_std_types(net, element=\"line\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see the test_type is now available in the standard type library, and you can use it to create a line:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "b1 = pp.create_bus(net, vn_kv=.4)\n",
    "b2 = pp.create_bus(net, vn_kv=.4)\n",
    "lid = pp.create_line(net, from_bus=b1, to_bus=b2, length_km=0.1, std_type=\"test_type\", name=\"test_line\")\n",
    "print(net.line.loc[lid])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Local Standard Type Libraries"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Standard tpyes are saved with the network if you use the pp.to_json function and are therefore still available if you load the network again.\n",
    "\n",
    "If you have a set of standard types that you want to save locally and apply to multiple networks, you can create a set of standard type parameters as a dictionary in the style {\"std_type1: {\"r_ohm_per_km\": r_ohm_per_km,...}, \"std_type2\": {\"r_ohm_per_km\": r_ohm_per_km,...},...} and add it to the network with the create_std_types function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "net = pp.create_empty_network()\n",
    "linetypes = {\"typ1\": {\"r_ohm_per_km\": 0.01, \"x_ohm_per_km\": 0.02, \"c_nf_per_km\": 10, \"max_i_ka\": 0.4, \"type\": \"cs\"},\n",
    "             \"typ2\": {\"r_ohm_per_km\": 0.015, \"x_ohm_per_km\": 0.01, \"c_nf_per_km\": 30, \"max_i_ka\": 0.3, \"type\": \"cs\"}}\n",
    "pp.create_std_types(net, data=linetypes, element=\"line\")\n",
    "pp.available_std_types(net)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The linetypes dictionary can be easily saved in a local project folder (e.g. using pickle or jsonpickle) and reloaded once it is needed. \n",
    "\n",
    "Another possibility is to copy the standard type library of an existing network:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "new_net = pp.create_empty_network()\n",
    "pp.copy_std_types(from_net=net, to_net=new_net, element=\"line\")\n",
    "pp.available_std_types(new_net)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Add Additional Parameters"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "You can define additional parameters in the standard type library and load them into pandapower. For example, if you want to run a reliability analysis for which you need a hazard rate for each line, you will want to add the hazard rate \"h_per_km\" for your individual standard type:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandapower as pp\n",
    "net = pp.create_empty_network()\n",
    "test_type = {\"r_ohm_per_km\": 0.01, \"x_ohm_per_km\": 0.02, \"c_nf_per_km\": 10, \"max_i_ka\": 0.4, \"type\": \"cs\", \"h_per_km\": 0.01}\n",
    "pp.create_std_type(net, name=\"test_type\", data=test_type, element=\"line\")\n",
    "pp.available_std_types(net, element=\"line\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can see that the parameter \"h_per_km\" is stored in the standard type database for the new standard type.\n",
    "\n",
    "We now create two lines, one of the new \"test_type\" and one with a standard type that does not have the parameter \"h_per_km\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "b1 = pp.create_bus(net, vn_kv=.4)\n",
    "b2 = pp.create_bus(net, vn_kv=.4)\n",
    "l1 = pp.create_line(net, from_bus=b1, to_bus=b2, length_km=0.1, std_type=\"test_type\", name=\"test_line1\")\n",
    "l2 = pp.create_line(net, from_bus=b1, to_bus=b2, length_km=0.1, std_type=\"NAYY 4x50 SE\", name=\"test_line2\")\n",
    "net.line"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The parameter \"h_per_km\" ist not in the line table, since it is not a pandapower standard parameter. You can however load the parameter from the database with the parameter_from_std_type function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pp.parameter_from_std_type(net, parameter=\"h_per_km\")\n",
    "net.line"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Pandapower adds the parameter to the linetable where it is available. The second line does not have a value for h_per_km, since it is not specified in the standard type database. You can however define a fallback (fill) value for lines that do not have a standard type or that have a standard type for which the desired parameter is not available:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pp.parameter_from_std_type(net, parameter=\"h_per_km\", fill=0.02)\n",
    "net.line"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Change Standard Type"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The change_std_type function allows changing the standard type of an element."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "net = pp.create_empty_network()\n",
    "b1 = pp.create_bus(net, vn_kv=.4)\n",
    "b2 = pp.create_bus(net, vn_kv=.4)\n",
    "l2 = pp.create_line(net, from_bus=b1, to_bus=b2, length_km=0.1, std_type=\"NAYY 4x50 SE\", name=\"test_line\")\n",
    "net.line"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pp.change_std_type(net, l2, \"NAYY 4x150 SE\", element=\"line\")\n",
    "net.line"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Find Standard Type"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "It is possible to search for a standard type given a set of parameters:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pp.find_std_type_by_parameter(net, data={\"r_ohm_per_km\": 0.1188, \"x_ohm_per_km\": 0.39})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "You can also define a tolerance epsilon to find types with similar parameters:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "pp.find_std_type_by_parameter(net, data={\"r_ohm_per_km\": 0.12, \"x_ohm_per_km\": 0.40}, epsilon=.05)"
   ]
  }
 ],
 "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.9.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}