diff --git a/docs/examples/Generic Branch Example.ipynb b/docs/examples/Generic Branch Example.ipynb index e3af6bcec..c50256e72 100644 --- a/docs/examples/Generic Branch Example.ipynb +++ b/docs/examples/Generic Branch Example.ipynb @@ -18,7 +18,7 @@ }, { "cell_type": "code", - "execution_count": 6, + "execution_count": 1, "metadata": {}, "outputs": [ { @@ -51,21 +51,19 @@ " ----> 6, Load \n", "\n", "\n", - "\n", - "\n", "========================================\n", " Input Data\n", "========================================\n", "\n", "node data\n", "---------\n", - " id Name Voltage [V]\n", - " 1 HV 200.0\n", - " 2 MV 150.0\n", - " 3 LV 30.0\n", - " 4 AUX 200.0\n", - " 11 Station1 150.0\n", - " 14 Source 200.0\n", + " id Name Voltage [kV]\n", + " 1 HV 200.0\n", + " 2 MV 150.0\n", + " 3 LV 30.0\n", + " 4 AUX 200.0\n", + " 11 Station1 150.0\n", + " 14 Source 200.0\n", "\n", "\n", "\n", @@ -80,9 +78,9 @@ "\n", "load data\n", "---------\n", - " id Name node status type P [W] Q [Var]\n", - " 6 L1 11 1 0 30.0 5.00\n", - " 7 L2 3 1 0 1.5 0.15\n", + " id Name node status type P [MW] Q [MVar]\n", + " 6 L1 11 1 0 30.0 5.00\n", + " 7 L2 3 1 0 1.5 0.15\n", "\n", "source data\n", "-----------\n", @@ -125,7 +123,7 @@ "(np.float64(0.1524792857302799), np.float64(0.5505383338017147))" ] }, - "execution_count": 6, + "execution_count": 1, "metadata": {}, "output_type": "execute_result" } @@ -170,38 +168,30 @@ " |\n", " ----> 6, Load \n", "\n", - "\n", - "\n", "\"\"\"\n", - "\n", - "\n", "# Voltage levels of the transformer\n", "u_rated = {\"HV\": 200e3, \"MV\": 150e3, \"LV\": 30.2e3, \"AUX\": 200e3, \"Station1\": 150e3, \"Source\": 200e3}\n", "\n", - "# Injected power (200 kV) on the 380 kV side\n", + "# Injected power on the HV side\n", "source_voltage = u_rated[\"Source\"] # 200 kV\n", - "source_power = 1e40 # hohe Kurzschlussleistung -> v_pu = 1.0\n", + "source_power = 1e40 # High short-circuit power -> v_pu = 1.0\n", "\n", "# Loads\n", "load_MV = {\"P\": 30e6, \"Q\": 5e6}\n", - "load_LV = {\"P\": 1.5e6, \"Q\": 0.15e6} # Eigenbedarf\n", + "load_LV = {\"P\": 1.5e6, \"Q\": 0.15e6} # Self-consumption\n", "\n", "# Assignment of node numbers\n", "nodes = {\"HV\": 1, \"MV\": 2, \"LV\": 3, \"AUX\": 4, \"Station1\": 11, \"Source\": 14}\n", "non = len(nodes) # number of nodes\n", - "# tap-changer\n", + "\n", + "# Tap-changer\n", "v_tap = 6.0e3\n", "\n", - "# generated nodes\n", + "# Generate nodes\n", "node_data = initialize_array(DatasetType.input, ComponentType.node, non)\n", "node_data[\"id\"] = list(nodes.values())\n", "node_data[\"u_rated\"] = list(u_rated.values())\n", "\n", - "\n", - "# node_data[\"id\"] = [nodes['HV'], nodes['MV'], nodes['LV'], nodes['AUX'], nodes['Station1'],nodes['Source'] ]\n", - "\n", - "# node_data[\"u_rated\"] = [u_rated['HV'], u_rated['MV'], u_rated['LV'], u_rated['AUX'],u_rated['Station1'] ]\n", - "\n", "# Slack\n", "source_data = initialize_array(DatasetType.input, ComponentType.source, 1)\n", "source_data[\"id\"] = [5]\n", @@ -222,17 +212,14 @@ "node_name = [\"HV\", \"MV\", \"LV\", \"AUX\", \"Station1\", \"Source\"]\n", "branch_name = [\"BHV\", \"BMV\", \"BLV\", \"BLine2\", \"BLine1\"]\n", "\n", - "\n", "branch_data = initialize_array(DatasetType.input, ComponentType.generic_branch, 5)\n", - "\n", - "\n", "branch_data[\"id\"] = [8, 9, 10, 12, 13]\n", "branch_data[\"from_node\"] = [nodes[\"HV\"], nodes[\"AUX\"], nodes[\"AUX\"], nodes[\"MV\"], nodes[\"Source\"]]\n", "branch_data[\"to_node\"] = [nodes[\"AUX\"], nodes[\"MV\"], nodes[\"LV\"], nodes[\"Station1\"], nodes[\"HV\"]]\n", "branch_data[\"from_status\"] = [1, 1, 1, 1, 1]\n", "branch_data[\"to_status\"] = [1, 1, 1, 1, 1]\n", "\n", - "# T1 T2 T3 Line2 Line 1\n", + "# T1 T2 T3 Line2 Line 1\n", "branch_data[\"r1\"] = [0.129059, 0.039528, 0.013811, 0.5, 0.5]\n", "branch_data[\"x1\"] = [16.385859, -0.889632, 0.757320, 2.0, 2.0]\n", "branch_data[\"g1\"] = [8.692e-7, 0.000002, 0.000038, 0.0, 0.0]\n", @@ -248,10 +235,8 @@ " ComponentType.generic_branch: branch_data,\n", "}\n", "\n", - "\n", "assert_valid_input_data(input_data=input_data, calculation_type=CalculationType.power_flow)\n", "\n", - "\n", "model = PowerGridModel(input_data)\n", "output_data = model.calculate_power_flow(\n", " symmetric=True, error_tolerance=1e-8, max_iterations=20, calculation_method=CalculationMethod.newton_raphson\n", @@ -267,7 +252,7 @@ " df = pd.DataFrame(node_in)\n", " df.insert(1, \"Name\", node_name)\n", "\n", - " map_column(df, \"u_rated\", rename_to=\"Voltage [V]\", unit_fn=e3, round_dec=0)\n", + " map_column(df, \"u_rated\", rename_to=\"Voltage [kV]\", unit_fn=e3, round_dec=0)\n", "\n", " print(\"\\nnode data\")\n", " print(\"---------\")\n", @@ -296,8 +281,8 @@ " df = pd.DataFrame(sym_load_in)\n", " df.insert(1, \"Name\", [\"L1\", \"L2\"])\n", "\n", - " map_column(df, \"p_specified\", rename_to=\"P [W]\", unit_fn=e6, round_dec=3)\n", - " map_column(df, \"q_specified\", rename_to=\"Q [Var]\", unit_fn=e6, round_dec=3)\n", + " map_column(df, \"p_specified\", rename_to=\"P [MW]\", unit_fn=e6, round_dec=3)\n", + " map_column(df, \"q_specified\", rename_to=\"Q [MVar]\", unit_fn=e6, round_dec=3)\n", "\n", " print(\"\\nload data\")\n", " print(\"---------\")\n", @@ -407,12 +392,12 @@ "source": [ "## Generic Branch Representation for Line, Transformer and PST\n", "\n", - "In this example, the Generic Branch is used as a Phase Shifting Transformer (PST) to optimize the loading of cable L34. Depending on the shift angle \\( \\theta \\), the loading of the cable can be adjusted. With a shift angle of -0.1 rad, the cable loading is approximately 80%, while at a shift angle of 0.0 rad, it drops to just 53%." + "In this example, the Generic Branch is used as a Phase Shifting Transformer (PST) to optimize the loading of cable L34. Depending on the shift angle $\\theta$, the loading of the cable can be adjusted. With a shift angle of $-0.1$ rad, the cable loading is approximately $81$%, while at a shift angle of $0.0$ rad, it drops to just $53$%." ] }, { "cell_type": "code", - "execution_count": 7, + "execution_count": 2, "metadata": {}, "outputs": [ { @@ -423,17 +408,17 @@ "Network:\n", "\n", "\n", - " (100km) (100km) B5,230kV\n", - " L 100MW <-|----L46------------| |-----------L45---------------|-> L 100 MW\n", - " B6,230kV ----- B4 |-\n", + " (100km) (100km) B5,230kV\n", + " L 100MW <-|----L46-----------| |-----------L45---------------|-> L 100 MW\n", + " B6,230kV ----- B4 |-\n", " | |\n", " L34 (cheap kabel, 40km) |\n", " | L57 (100km)\n", " ----- B3 |\n", " | |\n", - " (100km) PST23 (100km) |-\n", - " L 200MW <-|-----L28-----------| | |----------L27---------------|-> L 200 MW\n", - " B8,230kV ------ B2,230kV B7,230kV\n", + " (100km) PST23 (100km) |-\n", + " L 200MW <-|----L28--------| | |----------L27-------------|-> L 200 MW\n", + " B8,230kV --------- B2,230kV B7,230kV\n", " |\n", " T12 Transformer\n", " |\n", @@ -449,15 +434,15 @@ "\n", "node data\n", "---------\n", - " id Name Voltage [V]\n", - " 1 B1 16.0\n", - " 2 B2 230.0\n", - " 3 B3 230.0\n", - " 4 B4 230.0\n", - " 5 B5 230.0\n", - " 6 B6 230.0\n", - " 7 B7 230.0\n", - " 8 B8 230.0\n", + " id Name Voltage [kV]\n", + " 1 B1 16.0\n", + " 2 B2 230.0\n", + " 3 B3 230.0\n", + " 4 B4 230.0\n", + " 5 B5 230.0\n", + " 6 B6 230.0\n", + " 7 B7 230.0\n", + " 8 B8 230.0\n", "\n", "\n", "\n", @@ -475,11 +460,11 @@ "\n", "load data\n", "---------\n", - " id Name node status type P [W] Q [Var]\n", - " 9 L1 5 1 0 100.0 0.0\n", - " 10 L2 6 1 0 100.0 0.0\n", - " 11 L3 7 1 0 200.0 0.0\n", - " 12 L4 8 1 0 200.0 0.0\n", + " id Name node status type P [MW] Q [MVar]\n", + " 9 L1 5 1 0 100.0 0.0\n", + " 10 L2 6 1 0 100.0 0.0\n", + " 11 L3 7 1 0 200.0 0.0\n", + " 12 L4 8 1 0 200.0 0.0\n", "\n", "source data\n", "-----------\n", @@ -527,7 +512,7 @@ "(np.float64(19.347916682930418), np.float64(-160.46709070282753))" ] }, - "execution_count": 7, + "execution_count": 2, "metadata": {}, "output_type": "execute_result" } @@ -551,17 +536,17 @@ "# network\n", "network = \"\"\"\n", "\n", - " (100km) (100km) B5,230kV\n", - " L 100MW <-|----L46------------| |-----------L45---------------|-> L 100 MW\n", - " B6,230kV ----- B4 |-\n", + " (100km) (100km) B5,230kV\n", + " L 100MW <-|----L46-----------| |-----------L45---------------|-> L 100 MW\n", + " B6,230kV ----- B4 |-\n", " | |\n", " L34 (cheap kabel, 40km) |\n", " | L57 (100km)\n", " ----- B3 |\n", " | |\n", - " (100km) PST23 (100km) |-\n", - " L 200MW <-|-----L28-----------| | |----------L27---------------|-> L 200 MW\n", - " B8,230kV ------ B2,230kV B7,230kV\n", + " (100km) PST23 (100km) |-\n", + " L 200MW <-|----L28--------| | |----------L27-------------|-> L 200 MW\n", + " B8,230kV --------- B2,230kV B7,230kV\n", " |\n", " T12 Transformer\n", " |\n", @@ -596,12 +581,10 @@ "source[\"u_ref\"] = [1.0]\n", "source[\"sk\"] = [1e40]\n", "\n", - "# ZBase T12 = 13.5^2/1000 -> Z =\n", - "# ZBase = 230*230/1000 = 52.9\n", "# generic_branch\n", - "theta_pst = -0.1\n", + "theta_pst = -0.1 # shift angle of PST\n", "gb = initialize_array(DatasetType.input, ComponentType.generic_branch, 8)\n", - "# L27 L28 L45 L46 L57 L34 T12 P23\n", + "# L27 L28 L45 L46 L57 L34 T12 P23\n", "gb[\"id\"] = [14, 15, 16, 17, 18, 19, 20, 21]\n", "gb[\"from_node\"] = [2, 2, 4, 4, 5, 3, 1, 2]\n", "gb[\"to_node\"] = [7, 8, 5, 6, 7, 4, 2, 3]\n", @@ -648,7 +631,7 @@ " df = pd.DataFrame(node_in)\n", " df.insert(1, \"Name\", node_name)\n", "\n", - " map_column(df, \"u_rated\", rename_to=\"Voltage [V]\", unit_fn=e3, round_dec=0)\n", + " map_column(df, \"u_rated\", rename_to=\"Voltage [kV]\", unit_fn=e3, round_dec=0)\n", "\n", " print(\"\\nnode data\")\n", " print(\"---------\")\n", @@ -677,8 +660,8 @@ " df = pd.DataFrame(sym_load_in)\n", " df.insert(1, \"Name\", [\"L1\", \"L2\", \"L3\", \"L4\"])\n", "\n", - " map_column(df, \"p_specified\", rename_to=\"P [W]\", unit_fn=e6, round_dec=3)\n", - " map_column(df, \"q_specified\", rename_to=\"Q [Var]\", unit_fn=e6, round_dec=3)\n", + " map_column(df, \"p_specified\", rename_to=\"P [MW]\", unit_fn=e6, round_dec=3)\n", + " map_column(df, \"q_specified\", rename_to=\"Q [MVar]\", unit_fn=e6, round_dec=3)\n", "\n", " print(\"\\nload data\")\n", " print(\"---------\")\n", @@ -796,7 +779,7 @@ "This chapter provides a guide on how to use the Generic Branch to import data from CIM/CGMES network datasets and integrate it into a PGM model.\n", "\n", "\n", - "> Note: The PhaseAngleClock of transformers is not used in this document because the generic branch in this context is only applied to symmetrically loaded phases. The rated power of transformes is only used to calculate the relative loading.\n" + "> Note: The PhaseAngleClock of transformers is not used in this document because the generic branch in this context is only applied to symmetrically loaded phases. The rated power of transformers is only used to calculate the relative loading.\n" ] }, { @@ -830,7 +813,7 @@ "\n", "**EquivalentBranches** which connect different voltage levels should be modeled as `generic_branch`.\n", "\n", - "The conversion factors for impedance $z_{\\text{conv}}$ and admittance $y_{\\text{conv}}$ are calculated as follows:\n" + "The conversion factors for impedance $z_{\\text{conv}}$ is calculated as follows:\n" ] }, { @@ -856,7 +839,7 @@ "source": [ "### Two-winding Power Transformers\n", "\n", - "**Two-winding PowerTransformers** are characterized by only two PowerTransformerEnds. The Generic Branch can be used to model these transformers. On the high-voltage side, non-zero values for $r$, $x$, $b$$ and $g$ are provided in the cim datasets, while on the low-voltage side, these values are set to zero.\n" + "**Two-winding PowerTransformers** are characterized by only two PowerTransformerEnds. The Generic Branch can be used to model these transformers. On the high-voltage side, non-zero values for $r$, $x$, $b$ and $g$ are provided in the cim datasets, while on the low-voltage side, these values are set to zero.\n" ] }, { @@ -932,7 +915,7 @@ "metadata": {}, "source": [ "#### Pseudo Function `get_side_from_tap_changer()`\n", - "Purpose: Returns the side of the tap changer. If the tap changer is on the high voltage side, the side is 1. If the tap changer is on the low voltage side, the side is 2. If there is no tap changer, the side is 0.\n", + "Purpose: Returns the side of the tap changer. If the tap changer is on the high voltage side, the side is $1$. If the tap changer is on the low voltage side, the side is $2$. If there is no tap changer, the side is $0$.\n", "\n", "#### Pseudo Function `get_ratio()`\n", "Purpose: Returns the ratio of the current step position of the tap changer from the CIM-File (CIM:RatioTapChangerTable). Returns None if the ratio is not given in the CIM file.\n", @@ -947,7 +930,7 @@ "source": [ "### Three-winding Power Transformers\n", "\n", - "For **Three-winding PowerTransformers**, the three PowerTransformerEnds represent a star-equivalent circuit, with each leg in the star defined by its $r$, $x$, $g$ and $b$ values. This configuration requires three separate Generic Branches and an additional auxiliary node to connect them.\n", + "For **Three-winding PowerTransformers**, the three PowerTransformerEnds represent a star-equivalent circuit, with each leg in the star defined by its $r$, $x$, $g$ and $b$ values. This configuration requires three separate Generic Branches and an additional auxiliary node to connect them ([see also Example for Three-Winding Transformer](#generic-branch-representation-of-a-three-winding-transformer)).\n", "\n", "```\n", " GB_HV\n", @@ -967,7 +950,7 @@ "- Parameters $r$, $x$, $b$, $g$\n", "- Optional: Tap changer side, position, neutral position and voltage step increment.\n", "\n", - "The voltage on the auxiliary node is the nominal voltage of the high-voltage side. The tap changer's position must be determined to adjust the ratio for the regulated side, while the ratios for the other sides are set to $1.0$. For the generic branch on the regulated side, the ratio k should be calculated as described in section [2-Winding Power Transformers](##2-Winding-Power-Transformers). The electrical paramaters $r$, $x$, $b$, and $g$ can be used as given in the CIM-File without any further conversion. In contrast to 2-winding transformers, for 3-winding transformers the the parameters $r$, $x$, $b$, and $g$ are given for each TransformerEnd in the CIM-Dataset.\n" + "The voltage on the auxiliary node is the nominal voltage of the high-voltage side. The tap changer's position must be determined to adjust the ratio for the regulated side, while the ratios for the other sides are set to $1.0$. For the generic branch on the regulated side, the ratio k should be calculated as described in section [Two-Winding Power Transformers](#two-winding-power-transformers). The electrical parameters $r$, $x$, $b$, and $g$ can be used as given in the CIM-File without any further conversion. In contrast to Two-winding transformers, for Three-winding transformers the the parameters $r$, $x$, $b$, and $g$ are given for each TransformerEnd in the CIM-Dataset.\n" ] }, { @@ -982,7 +965,7 @@ "metadata": {}, "source": [ "#### Asymmetrical Phase Shifting Transformers\n", - "For a **3-Winding Transformer with Phase Shift**, the configuration mirrors the star-equivalent model described in section [3-Winding Power Transformers](3-Winding-Power-Transformers). However, one leg must account for the phase shift.\n", + "For a **Three-Winding Transformer with phase shift**, the configuration mirrors the star-equivalent model described in section [Three-Winding Power Transformers](#three-winding-power-transformers). However, one leg must account for the phase shift.\n", "\n", "```\n", " GB_HV\n", @@ -995,7 +978,7 @@ "- **\\***: Auxiliary node with voltage = HV nominal voltage\n", "- **--//--**: Phase shift angle\n", "\n", - "In the PI model of the Generic Branch, the controller (ratio + shift) is located on the **input side**, requiring adjustments for the phase shift angle as it is specified in CIM datasets on the **output side**.\n", + "In the PI model of the Generic Branch, the controller (ratio + shift angle) is located on the **input side**, requiring adjustments to the phase shift angle if the controller is located on the **output side** (e.g., when the tap changer is on the high-voltage side of the transformer).\n", "```\n", "u1 o---- -----Z_ser------------o u2\n", " | | . .\n", @@ -1008,7 +991,7 @@ "```\n", "$k = \\text{ratio} \\cdot e^{j \\cdot \\theta}$\n", "\n", - "If the tap changer is located on the MV side, the phase shift angle must be multiplied by \\(-1.0\\) and alyways converted to radians. \n", + "If the tap changer is located on the MV side, the phase shift angle must be multiplied by $-1.0$ and always converted to radians. \n", "```python\n", "if regulate_side == 2:\n", " deg_to_rad = math.pi / 180.0\n", @@ -1036,13 +1019,13 @@ "- The nominal voltages on both sides are identical.\n", "- The tap changer influences the total shift of the transformer.\n", "\n", - "The ratio is set to \\(1.0\\), and the phase angle shift is either provided in the CIM file or calculated using the formulas from *Phase Shift Transformers Modelling* ([ENTSOE_CGMES_v2.4_28May2014_PSTmodelling.pdf](https://eepublicdownloads.entsoe.eu/clean-documents/CIM_documents/Grid_Model_CIM/ENTSOE_CGMES_v2.4_28May2014_PSTmodelling.pdf)). Similar to the asymmetrical case, the angle is converted to radians and multiplied by \\(-1.0\\) depending on the tap changer's location for proper modeling.\n" + "The ratio is set to $1.0$, and the phase angle shift is either provided in the CIM file or calculated using the formulas from *Phase Shift Transformers Modelling* ([ENTSOE_CGMES_v2.4_28May2014_PSTmodelling.pdf](https://eepublicdownloads.entsoe.eu/clean-documents/CIM_documents/Grid_Model_CIM/ENTSOE_CGMES_v2.4_28May2014_PSTmodelling.pdf)). Similar to the asymmetrical case, the angle is converted to radians and multiplied by $-1.0$ depending on the tap changer's location for proper modeling.\n" ] } ], "metadata": { "kernelspec": { - "display_name": ".venv", + "display_name": "venv", "language": "python", "name": "python3" }, @@ -1056,7 +1039,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.10.12" + "version": "3.13.0" } }, "nbformat": 4,