Feature/comparison

CHANGELOG.md

@@ -60,6 +60,33 @@ Until here -->
 
 ### ✨ Added
 
+**FlowSystem Comparison**: New `Comparison` class for comparing multiple FlowSystems side-by-side:
+
+```python
+# Compare systems (uses FlowSystem.name by default)
+comp = fx.Comparison([fs_base, fs_modified])
+
+# Or with custom names
+comp = fx.Comparison([fs1, fs2, fs3], names=['baseline', 'low_cost', 'high_eff'])
+
+# Side-by-side plots (auto-facets by 'case' dimension)
+comp.statistics.plot.balance('Heat')
+comp.statistics.flow_rates.fxplot.line()
+
+# Access combined data with 'case' dimension
+comp.solution  # xr.Dataset
+comp.statistics.flow_rates  # xr.Dataset
+
+# Compute differences relative to a reference case
+comp.diff()  # vs first case
+comp.diff('baseline')  # vs named case
+```
+
+- Concatenates solutions and statistics from multiple FlowSystems with a `'case'` dimension
+- Mirrors all `StatisticsAccessor` properties (`flow_rates`, `flow_hours`, `sizes`, `charge_states`, `temporal_effects`, `periodic_effects`, `total_effects`)
+- Mirrors all `StatisticsPlotAccessor` methods (`balance`, `carrier_balance`, `flows`, `sizes`, `duration_curve`, `effects`, `charge_states`, `heatmap`, `storage`)
+- Existing plotting infrastructure automatically handles faceting by `'case'`
+
 **Time-Series Clustering**: Reduce large time series to representative typical periods for faster investment optimization, then expand results back to full resolution.
 
 ```python

docs/notebooks/02-heat-system.ipynb

@@ -32,6 +32,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "import pandas as pd\n",
     "import xarray as xr\n",
     "\n",
     "import flixopt as fx\n",
@@ -281,12 +282,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "total_costs = flow_system.solution['costs'].item()\n",
     "total_heat = heat_demand.sum()\n",
     "\n",
-    "print(f'Total operating costs: {total_costs:.2f} €')\n",
-    "print(f'Total heat delivered: {total_heat:.0f} kWh')\n",
-    "print(f'Average cost: {total_costs / total_heat * 100:.2f} ct/kWh')"
+    "pd.DataFrame(\n",
+    "    {\n",
+    "        'Total operating costs [EUR]': flow_system.solution['costs'].item(),\n",
+    "        'Total heat delivered [kWh]': total_heat,\n",
+    "        'Average cost [ct/kWh]': flow_system.solution['costs'].item() / total_heat * 100,\n",
+    "    },\n",
+    "    index=['Value'],\n",
+    ").T"
    ]
   },
   {
@@ -370,25 +375,7 @@
    ]
   }
  ],
- "metadata": {
-  "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.11.11"
-  }
- },
+ "metadata": {},
  "nbformat": 4,
  "nbformat_minor": 5
 }

docs/notebooks/03-investment-optimization.ipynb

@@ -32,6 +32,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "import pandas as pd\n",
     "import xarray as xr\n",
     "\n",
     "import flixopt as fx\n",
@@ -229,9 +230,14 @@
     "solar_size = flow_system.statistics.sizes['SolarCollectors(Heat)'].item()\n",
     "tank_size = flow_system.statistics.sizes['BufferTank'].item()\n",
     "\n",
-    "print(\n",
-    "    f'Optimal sizes: Solar {solar_size:.0f} kW, Tank {tank_size:.0f} kWh (ratio: {tank_size / solar_size:.1f} kWh/kW)'\n",
-    ")"
+    "pd.DataFrame(\n",
+    "    {\n",
+    "        'Solar [kW]': solar_size,\n",
+    "        'Tank [kWh]': tank_size,\n",
+    "        'Ratio [kWh/kW]': tank_size / solar_size,\n",
+    "    },\n",
+    "    index=['Optimal Size'],\n",
+    ").T"
    ]
   },
   {
@@ -274,8 +280,13 @@
     "tank_invest = tank_size * TANK_COST_WEEKLY\n",
     "gas_costs = total_costs - solar_invest - tank_invest\n",
     "\n",
-    "print(\n",
-    "    f'Weekly costs: Solar {solar_invest:.1f}€ ({solar_invest / total_costs * 100:.0f}%) + Tank {tank_invest:.1f}€ ({tank_invest / total_costs * 100:.0f}%) + Gas {gas_costs:.1f}€ ({gas_costs / total_costs * 100:.0f}%) = {total_costs:.1f}€'\n",
+    "pd.DataFrame(\n",
+    "    {\n",
+    "        'Solar Investment': {'EUR': solar_invest, '%': solar_invest / total_costs * 100},\n",
+    "        'Tank Investment': {'EUR': tank_invest, '%': tank_invest / total_costs * 100},\n",
+    "        'Gas Costs': {'EUR': gas_costs, '%': gas_costs / total_costs * 100},\n",
+    "        'Total': {'EUR': total_costs, '%': 100.0},\n",
+    "    }\n",
     ")"
    ]
   },
@@ -334,14 +345,21 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Gas-only scenario\n",
+    "# Gas-only scenario for comparison\n",
     "total_demand = pool_demand.sum()\n",
     "gas_only_cost = total_demand / 0.92 * GAS_PRICE  # All heat from gas boiler\n",
-    "\n",
     "savings = gas_only_cost - total_costs\n",
-    "print(\n",
-    "    f'Solar saves {savings:.1f}€/week ({savings / gas_only_cost * 100:.0f}%) vs gas-only ({gas_only_cost:.1f}€) → {savings * 52:.0f}€/year'\n",
-    ")"
+    "\n",
+    "pd.DataFrame(\n",
+    "    {\n",
+    "        'Gas-only [EUR/week]': gas_only_cost,\n",
+    "        'With Solar [EUR/week]': total_costs,\n",
+    "        'Savings [EUR/week]': savings,\n",
+    "        'Savings [%]': savings / gas_only_cost * 100,\n",
+    "        'Savings [EUR/year]': savings * 52,\n",
+    "    },\n",
+    "    index=['Value'],\n",
+    ").T"
    ]
   },
   {
@@ -406,25 +424,7 @@
    ]
   }
  ],
- "metadata": {
-  "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.11.11"
-  }
- },
+ "metadata": {},
  "nbformat": 4,
  "nbformat_minor": 5
 }

docs/notebooks/04-operational-constraints.ipynb

@@ -32,6 +32,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "import pandas as pd\n",
     "import xarray as xr\n",
     "\n",
     "import flixopt as fx\n",
@@ -84,8 +85,12 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Visualize demand with fxplot\n",
-    "demand_ds = xr.Dataset({'Steam Demand': xr.DataArray(steam_demand, dims=['time'], coords={'time': timesteps})})\n",
+    "# Visualize the demand with fxplot\n",
+    "demand_ds = xr.Dataset(\n",
+    "    {\n",
+    "        'Steam Demand [kW]': xr.DataArray(steam_demand, dims=['time'], coords={'time': timesteps}),\n",
+    "    }\n",
+    ")\n",
     "demand_ds.fxplot.line(title='Factory Steam Demand')"
    ]
   },
@@ -104,7 +109,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "flow_system = fx.FlowSystem(timesteps)\n",
+    "flow_system = fx.FlowSystem(timesteps, name='Constrained')\n",
     "\n",
     "# Define and register custom carriers\n",
     "flow_system.add_carriers(\n",
@@ -268,8 +273,12 @@
     "startup_costs = total_startups * 50\n",
     "gas_costs = total_costs - startup_costs\n",
     "\n",
-    "print(\n",
-    "    f'{total_startups} startups × 50€ = {startup_costs:.0f}€ startup + {gas_costs:.0f}€ gas = {total_costs:.0f}€ total'\n",
+    "pd.DataFrame(\n",
+    "    {\n",
+    "        'Startups': {'Count': total_startups, 'EUR': startup_costs},\n",
+    "        'Gas': {'Count': '-', 'EUR': gas_costs},\n",
+    "        'Total': {'Count': '-', 'EUR': total_costs},\n",
+    "    }\n",
     ")"
    ]
   },
@@ -321,7 +330,7 @@
    "outputs": [],
    "source": [
     "# Build unconstrained system\n",
-    "fs_unconstrained = fx.FlowSystem(timesteps)\n",
+    "fs_unconstrained = fx.FlowSystem(timesteps, name='Unconstrained')\n",
     "fs_unconstrained.add_carriers(\n",
     "    fx.Carrier('gas', '#3498db', 'kW'),\n",
     "    fx.Carrier('steam', '#87CEEB', 'kW_th', 'Process steam'),\n",
@@ -351,14 +360,43 @@
     "fs_unconstrained.optimize(fx.solvers.HighsSolver())\n",
     "unconstrained_costs = fs_unconstrained.solution['costs'].item()\n",
     "\n",
-    "constraint_overhead = (total_costs - unconstrained_costs) / unconstrained_costs * 100\n",
-    "print(f'Constraints add {constraint_overhead:.1f}% cost: {unconstrained_costs:.0f}€ → {total_costs:.0f}€')"
+    "pd.DataFrame(\n",
+    "    {\n",
+    "        'Without Constraints': {'Cost [EUR]': unconstrained_costs},\n",
+    "        'With Constraints': {'Cost [EUR]': total_costs},\n",
+    "        'Overhead': {\n",
+    "            'Cost [EUR]': total_costs - unconstrained_costs,\n",
+    "            '%': (total_costs - unconstrained_costs) / unconstrained_costs * 100,\n",
+    "        },\n",
+    "    }\n",
+    ")"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "24",
    "metadata": {},
+   "source": [
+    "### Side-by-Side Comparison\n",
+    "\n",
+    "Use the `Comparison` class to visualize both systems together:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "25",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "comp = fx.Comparison([fs_unconstrained, flow_system])\n",
+    "comp.statistics.plot.effects()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "26",
+   "metadata": {},
    "source": [
     "### Energy Flow Sankey\n",
     "\n",
@@ -368,7 +406,7 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "25",
+   "id": "27",
    "metadata": {},
    "outputs": [],
    "source": [
@@ -377,7 +415,7 @@
   },
   {
    "cell_type": "markdown",
-   "id": "26",
+   "id": "28",
    "metadata": {},
    "source": [
     "## Key Concepts\n",
@@ -430,17 +468,10 @@
   }
  ],
  "metadata": {
-  "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.11.11"
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
   }
  },
  "nbformat": 4,