PGM-DS workshop: Improve descriptions in advanced notebook

Author: svenvdvoort

power-grid-model-ds/advanced.ipynb

@@ -25,20 +25,18 @@
    "id": "d5e1958f",
    "metadata": {},
    "source": [
-    "# ⚡ Advanced Power Grid Workshop: Solving an Overload Scenario\n",
+    "# ⚡ Advanced PGM-DS Workshop: Solving an Overload Scenario\n",
     "\n",
-    "You're a senior grid analyst at GridNova Utilities, overseeing a legacy radial distribution network in a semi-rural region. Recently, customer load growth has increased dramatically, particularly in areas served by a single long feeder. This has pushed some branches past their capacity, triggering repeated overloads.\n",
+    "You're a senior grid analyst at GridNova Utilities, responsible for operating a legacy distribution grid in a rural area. The grid is radially operated, with some cables inactive as back-up in case failures. Recently, customer load growth has increased dramatically, particularly in areas served by several long feeders. This has pushed some branches past their capacity, triggering repeated overloads.\n",
     "\n",
-    "Your task: augment the grid by adding a second substation and relieving the overloaded feeder through targeted switching.\n",
+    "Your task: upgrade the grid by adding a second substation and relieving the overloaded feeder through new connections to the new substation.\n",
     "\n",
-    "This hands-on simulation walks you through each step of diagnosing, planning, and solving this overload using the Power Grid Model DS library.\n",
+    "This hands-on simulation walks you through each step of diagnosing, planning, and solving this overload using the Power Grid Model Data Science library.\n",
     "\n",
     "## 🎯 Workshop Goals\n",
-    "- Detect a line overload after load increase.\n",
-    "- Find a suitable node to connect a new substation.\n",
-    "- Trace the overloaded route.\n",
-    "- Strategically open a line to reroute power and relieve the feeder.\n",
-    "\n"
+    "- Detect a line overload using PGM load flow calculations.\n",
+    "- Find a suitable node to create a connection to the new substation.\n",
+    "- Strategically open a line to reroute power and relieve the feeder.\n"
    ]
   },
   {
@@ -63,9 +61,9 @@
    "metadata": {},
    "source": [
     "# 🧪 Step 1: Extend the Data Model\n",
-    "Goal: Add coordinate fields and tracking for simulated voltages and line currents.\n",
+    "Goal: Add coordinate fields to nodes and fields for tracking simulated voltages and line currents.\n",
     "\n",
-    "You’ll subclass NodeArray and LineArray to add:\n",
+    "We subclass NodeArray and LineArray to add:\n",
     "\n",
     "- x, y coordinates for spatial logic and plotting\n",
     "- u for node voltage results\n",
@@ -119,11 +117,13 @@
     "# 🏗️ Step 2: Load and Prepare the Grid\n",
     "Goal: Load a synthetic medium-voltage grid from the provided data.\n",
     "\n",
-    "You'll use pandas to load the data from included CSV files and then:\n",
+    "We use pandas to load the data from included CSV files and then:\n",
     "- Create an empty Grid object using your custom MyGrid class\n",
     "- Create and fill NodeArray, LineArray and LoadArray objects with data from the CSV files and append them to your Grid\n",
     "- Using a SourceArray, add a voltage source to each substation in the Grid\n",
-    "- You’ll then compute a power flow on the synthetic grid to get realistic line currents"
+    "- You’ll then compute a power flow on the synthetic grid to get realistic line currents\n",
+    "\n",
+    "(Code is already given in helper.py file, please take a look to see how the grid data is loaded!)"
    ]
   },
   {
@@ -152,14 +152,13 @@
    "metadata": {},
    "source": [
     "# 🧯 Step 3: Detect the Overload\n",
-    "Goal: Identify which line(s) are exceeding their rated current.\n",
+    "Goal: Identify which line(s) are exceeding their rated current (the `i_n` property).\n",
     "\n",
-    "You’ll:\n",
+    "You can do this step by step (don't forget to check the PGM-DS documentation):\n",
     "\n",
-    "- Use the .is_overloaded property to find the problem\n",
-    "- Isolate the feeder route to the affected line\n",
-    "\n",
-    "This gives a clear target for where you need to intervene."
+    "1. Use the PowerGridModelInterface to calculate power flow\n",
+    "2. Update the Grid object with the calculated values\n",
+    "3. Return the lines (LineArray) that are overloaded"
    ]
   },
   {
@@ -177,11 +176,6 @@
     }
    ],
    "source": [
-    "# Check the grid for capacity issues\n",
-    "# 1. Use the PowerGridModelInterface to calculate power flow\n",
-    "# 2. Update the grid with the calculated values\n",
-    "# 3. Return the lines (LineArray) that are overloaded\n",
-    "\n",
     "# Hint: You can use the `is_overloaded` property of the `MyLineArray` class to check for overloaded lines.\n",
     "# Hint: https://power-grid-model-ds.readthedocs.io/en/stable/quick_start.html#performing-power-flow-calculations\n",
     "\n",
@@ -211,14 +205,15 @@
    "metadata": {},
    "source": [
     "# 🧭 Step 4: Plan a Relief Strategy\n",
+    "\n",
+    "If you visualize the grid and highlight the overloaded cables, this is what you will see:\n",
+    "\n",
     "![input_network_with_overload.png](input_network_with_overload.png)\n",
     "\n",
-    "Goal: Place a second substation near the overloaded path.\n",
+    "Goal: Place a second substation near the overloaded path. In the next steps we will use this substation to relieve overloaded cables.\n",
     "\n",
     "You’ll:\n",
-    "- Add a new substation at a specified location\n",
-    "- Connect it to the closest node in the network\n",
-    "- Visually inspect the grid with visualize()\n",
+    "- Create a new substations using the NodeArrayobject at the correct location.\n",
     "\n",
     "This substation will act as a new injection point for rerouting load.\n"
    ]
@@ -245,15 +240,13 @@
    "id": "8f2b17e3",
    "metadata": {},
    "source": [
-    "# 🔗 Step 5: Trace and Analyze the Overloaded Route\n",
-    "Goal: Identify a switchable line along the route from the new node to the old substation.\n",
+    "# 🔗 Step 5: Analyze and Connect the Overloaded Route\n",
+    "Goal: Identify the best way to connect the new substation to the overloaded routes.\n",
     "\n",
     "You’ll:\n",
-    "- Use the graph interface to trace the shortest path from the new substation to the original\n",
-    "- Calculate cumulative load along the path\n",
-    "- Find a cut point where the remaining load toward the old substation is < 2 MW\n",
-    "\n",
-    "This ensures you relieve the feeder while maintaining supply continuity."
+    "- Compute which routes (/feeders) are overloaded to see where we need to invervene.\n",
+    "- Find which node on an overloaded route is geographically closed to the new substation.\n",
+    "- Create a new cable to connect the closest node to the new substation."
    ]
   },
   {
@@ -267,7 +260,7 @@
     "# Hint: The arrays in the grid have a filter option, https://power-grid-model-ds.readthedocs.io/en/stable/examples/model/array_examples.html#using-filters\n",
     "\n",
     "def get_all_congested_routes(grid: Grid) -> list[NodeArray]:\n",
-    "    \"\"\"Get all routes that originate from a given substation node.\"\"\"\n",
+    "    \"\"\"Get all nodes on routes that contain an overloaded line.\"\"\"\n",
     "\n",
     "# %load solutions/advanced_5_1_get_all_congested_routes.py"
    ]
@@ -302,7 +295,9 @@
    "id": "a75e9b73",
    "metadata": {},
    "source": [
-    "Finally we build a function that creates a new line between the connection point and the new substation. We will first create it with an open connection and optimize the opening in the next step."
+    "Finally we build a function that creates a new line between the connection point and the new substation.\n",
+    "\n",
+    "❗ IMPORTANT ❗ The new line should first be created with an open connection; we will optimize the location of the line opening in the next step."
    ]
   },
   {
@@ -326,15 +321,16 @@
    "id": "4a9ef582",
    "metadata": {},
    "source": [
-    "# ✂️ Step 6: Open the Right Line\n",
-    "Goal: Deactivate a line to offload the original feeder.\n",
+    "# 🔌 Step 6: Open the Right Line\n",
+    "Goal: Find the optimal line to open to relieve the original overloaded feeder.\n",
     "\n",
     "You’ll:\n",
-    "- Identify and deactivate the line between two nodes on the critical path\n",
-    "- Rerun power flow after the switch\n",
+    "- Trace a path from the newly created cable to the old substation\n",
+    "- Evaluate each line on the path by running `check_for_capacity_issues()` and find the optimal line to open\n",
+    "- Open the correct line\n",
     "- Confirm the overload is resolved\n",
     "\n",
-    "This final step demonstrates how network topology and load can be managed dynamically with switching and distributed generation.\n",
+    "This final step demonstrates how network topology can be programmatically optimized using the Power Grid Model Data Science toolkit!\n",
     "\n"
    ]
   },
@@ -346,7 +342,7 @@
    "outputs": [],
    "source": [
     "def optimize_route_transfer(grid: Grid, connection_point: NodeArray, new_substation: NodeArray) -> None:\n",
-    "    \"\"\"Attempt to optimize the route transfer moving the naturally open point (NOP) upstream towards the old substation.\n",
+    "    \"\"\"Attempt to optimize the route transfer moving the normally open point (NOP) upstream towards the old substation.\n",
     "    This way, the new substation will take over more nodes of the original route.\n",
     "    \"\"\"\n",
     "    # Get the path from the connection point to the old substation\n",
@@ -448,17 +444,17 @@
     "# ✅ Wrap-Up\n",
     "You’ve just:\n",
     "\n",
-    "Diagnosed a power system constraint\n",
-    "- Planned and executed a grid topology change\n",
-    "- Verified success with power flow simulations\n",
+    "- Loaded a grid topology and grid loads from a file\n",
+    "- Analyse grid components that are or will soon be overloaded using load flow analysis\n",
+    "- Automatically optimize a solution to relieve (future) congestions on the energy grid\n",
     "\n",
     "We hope you enjoyed working with Power Grid Model DS and would love to hear your feedback"
    ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": ".venv",
+   "display_name": "power-grid-model-workshop",
    "language": "python",
    "name": "python3"
   },
@@ -472,7 +468,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.6"
+   "version": "undefined.undefined.undefined"
   }
  },
  "nbformat": 4,

power-grid-model-ds/solutions/advanced_5_1_get_all_congested_routes.py

@@ -1,5 +1,5 @@
 def get_all_congested_routes(grid: Grid) -> list[NodeArray]:
-    """Get all routes that originate from a given substation node."""
+    """Get all nodes on routes that contain an overloaded line."""
     grid.set_feeder_ids()
     lines_with_congestion = check_for_capacity_issues(grid)
     feeder_branch_ids_with_congestion = np.unique(lines_with_congestion['feeder_branch_id'])