Improve example fpr callback to notebook

Author: FBumann

docs/notebooks/04-operational-constraints.ipynb

@@ -422,9 +422,9 @@
     "\n",
     "Sometimes you need constraints beyond what's built into the components. The `before_solve` callback lets you add custom constraints directly to the optimization model.\n",
     "\n",
-    "### Example: Limit Main Boiler Startups\n",
+    "### Example: Ramp Rate Limits\n",
     "\n",
-    "Let's limit the main boiler to a maximum of 3 startups:"
+    "Large boilers can't change output instantly—thermal stress limits how fast they can ramp up or down. Let's add a constraint limiting the main boiler to ±50 kW change per timestep:"
    ]
   },
   {
@@ -434,19 +434,24 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Build a fresh system with status tracking on both boilers\n",
-    "fs_custom = flow_system.copy()\n",
-    "fs_custom.reset()\n",
+    "fs_ramp = flow_system.copy()\n",
     "\n",
     "\n",
-    "def limit_main_boiler_startups(fs):\n",
-    "    \"\"\"Custom constraint: Main boiler can start at most 3 times.\"\"\"\n",
+    "def add_ramp_rate_limit(fs, max_ramp: float = 10):\n",
+    "    \"\"\"Limit ramp rate when boiler stays on. Uses Big-M to allow on/off jumps.\"\"\"\n",
     "    model = fs.model\n",
-    "    main_startups = model.variables['MainBoiler|startup']\n",
-    "    model.add_constraints(main_startups.sum() <= 3, name='max_main_startups')\n",
+    "    flow = model.variables['MainBoiler(Steam)|flow_rate']\n",
+    "    status = model.variables['MainBoiler|status']\n",
     "\n",
+    "    ramp = flow - flow.shift(time=1)\n",
+    "    both_on = status + status.shift(time=1)  # =2 when both on, <2 otherwise\n",
     "\n",
-    "fs_custom.optimize(fx.solvers.HighsSolver(mip_gap=0.01), before_solve=limit_main_boiler_startups);"
+    "    big_m = 500  # Big-M (larger than max flow)\n",
+    "    model.add_constraints(ramp <= max_ramp + big_m * (2 - both_on), name='ramp_up')\n",
+    "    model.add_constraints(ramp >= -max_ramp - big_m * (2 - both_on), name='ramp_down')\n",
+    "\n",
+    "\n",
+    "fs_ramp.optimize(fx.solvers.HighsSolver(mip_gap=0.01), before_solve=add_ramp_rate_limit);"
    ]
   },
   {
@@ -456,16 +461,14 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Verify: Main boiler startups are limited\n",
-    "main_startups = int(fs_custom.solution['MainBoiler|startup'].sum().item())\n",
-    "print(f'MainBoiler startups: {main_startups} (limit: 3)')\n",
-    "\n",
-    "# Compare with unconstrained (which had more startups)\n",
-    "print(f'Original system startups: {total_startups}')\n",
-    "\n",
-    "# Show startup events\n",
-    "startup_ds = xr.Dataset({'MainBoiler startup': fs_custom.solution['MainBoiler|startup']})\n",
-    "startup_ds.plotly.line(x='time', title='Main Boiler Startup Events', height=250)"
+    "# Compare: with vs without ramp rate limits\n",
+    "comparison_ds = xr.Dataset(\n",
+    "    {\n",
+    "        'Without ramp limit': flow_system.solution['MainBoiler(Steam)|flow_rate'],\n",
+    "        'With ramp limit (±10 kW)': fs_ramp.solution['MainBoiler(Steam)|flow_rate'],\n",
+    "    }\n",
+    ")\n",
+    "comparison_ds.plotly.line(x='time', title='Main Boiler Output: Effect of Ramp Rate Limits', height=350)"
    ]
   },
   {
@@ -484,16 +487,53 @@
    "id": "32",
    "metadata": {},
    "outputs": [],
+   "source": [
+    "# Calculate actual ramp rates (change between timesteps)\n",
+    "flow_original = flow_system.solution['MainBoiler(Steam)|flow_rate']\n",
+    "flow_ramp = fs_ramp.solution['MainBoiler(Steam)|flow_rate']\n",
+    "\n",
+    "ramp_original = flow_original.diff('time')\n",
+    "ramp_limited = flow_ramp.diff('time')\n",
+    "\n",
+    "print(f'Without ramp limit: max ramp = {abs(ramp_original).max().item():.1f} kW/step')\n",
+    "print(f'With ramp limit:    max ramp = {abs(ramp_limited).max().item():.1f} kW/step (limit: 50 kW)')\n",
+    "\n",
+    "# Show the ramp rates over time\n",
+    "ramp_ds = xr.Dataset(\n",
+    "    {\n",
+    "        'Original ramp rate': ramp_original,\n",
+    "        'Limited ramp rate': ramp_limited,\n",
+    "    }\n",
+    ")\n",
+    "ramp_ds.plotly.line(x='time', title='Ramp Rates (kW change per timestep)', height=300)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "33",
+   "metadata": {},
+   "source": [
+    "### Finding Available Variables\n",
+    "\n",
+    "To discover what variables you can use in custom constraints, inspect the model after building:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "34",
+   "metadata": {},
+   "outputs": [],
    "source": [
     "# List all variables in the model\n",
     "print('Available variables:')\n",
-    "for name in fs_custom.model.variables:\n",
+    "for name in fs_ramp.model.variables:\n",
     "    print(f'  {name}')"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "33",
+   "id": "35",
    "metadata": {},
    "source": [
     "## Key Concepts\n",