Feature/element data classes+id+dataclasses+data

CHANGELOG.md

@@ -1090,7 +1090,7 @@ If upgrading from v2.x, see the [v3.0.0 release notes](https://github.com/flixOp
 
 - **Penalty as first-class Effect**: Users can now add Penalty contributions anywhere effects are used:
   ```python
-  fx.Flow('Q', 'Bus', effects_per_flow_hour={'Penalty': 2.5})
+  fx.Flow(bus='Bus', flow_id='Q', effects_per_flow_hour={'Penalty': 2.5})
   fx.InvestParameters(..., effects_of_investment={'Penalty': 100})
   ```
 - **User-definable Penalty**: Optionally define custom Penalty with constraints (auto-created if not defined):

benchmarks/benchmark_model_build.py

@@ -246,7 +246,7 @@ def create_large_system(
     fs.add_elements(
         fx.Source(
             'GasGrid',
-            outputs=[fx.Flow('Gas', bus='Gas', size=5000, effects_per_flow_hour={'costs': gas_price, 'CO2': 0.2})],
+            outputs=[fx.Flow(bus='Gas', size=5000, effects_per_flow_hour={'costs': gas_price, 'CO2': 0.2})],
         )
     )
 
@@ -255,19 +255,25 @@ def create_large_system(
         fx.Source(
             'ElecBuy',
             outputs=[
-                fx.Flow('El', bus='Electricity', size=2000, effects_per_flow_hour={'costs': elec_price, 'CO2': 0.4})
+                fx.Flow(
+                    bus='Electricity', flow_id='El', size=2000, effects_per_flow_hour={'costs': elec_price, 'CO2': 0.4}
+                )
             ],
         ),
         fx.Sink(
             'ElecSell',
-            inputs=[fx.Flow('El', bus='Electricity', size=1000, effects_per_flow_hour={'costs': -elec_price * 0.8})],
+            inputs=[
+                fx.Flow(bus='Electricity', flow_id='El', size=1000, effects_per_flow_hour={'costs': -elec_price * 0.8})
+            ],
         ),
     )
 
     # Demands
     fs.add_elements(
-        fx.Sink('HeatDemand', inputs=[fx.Flow('Heat', bus='Heat', size=1, fixed_relative_profile=heat_profile)]),
-        fx.Sink('ElecDemand', inputs=[fx.Flow('El', bus='Electricity', size=1, fixed_relative_profile=elec_profile)]),
+        fx.Sink('HeatDemand', inputs=[fx.Flow(bus='Heat', size=1, fixed_relative_profile=heat_profile)]),
+        fx.Sink(
+            'ElecDemand', inputs=[fx.Flow(bus='Electricity', flow_id='El', size=1, fixed_relative_profile=elec_profile)]
+        ),
     )
 
     # Converters (CHPs and Boilers)
@@ -294,10 +300,10 @@ def create_large_system(
                 fs.add_elements(
                     fx.LinearConverter(
                         f'CHP_{i}',
-                        inputs=[fx.Flow('Gas', bus='Gas', size=300)],
+                        inputs=[fx.Flow(bus='Gas', size=300)],
                         outputs=[
-                            fx.Flow('El', bus='Electricity', size=100),
-                            fx.Flow('Heat', bus='Heat', size=size_param, status_parameters=status_param),
+                            fx.Flow(bus='Electricity', flow_id='El', size=100),
+                            fx.Flow(bus='Heat', size=size_param, status_parameters=status_param),
                         ],
                         piecewise_conversion=fx.PiecewiseConversion(
                             {
@@ -314,9 +320,9 @@ def create_large_system(
                         f'CHP_{i}',
                         thermal_efficiency=0.50,
                         electrical_efficiency=0.35,
-                        thermal_flow=fx.Flow('Heat', bus='Heat', size=size_param, status_parameters=status_param),
-                        electrical_flow=fx.Flow('El', bus='Electricity', size=100),
-                        fuel_flow=fx.Flow('Gas', bus='Gas'),
+                        thermal_flow=fx.Flow(bus='Heat', size=size_param, status_parameters=status_param),
+                        electrical_flow=fx.Flow(bus='Electricity', flow_id='El', size=100),
+                        fuel_flow=fx.Flow(bus='Gas'),
                     )
                 )
         else:
@@ -326,13 +332,12 @@ def create_large_system(
                     f'Boiler_{i}',
                     thermal_efficiency=0.90,
                     thermal_flow=fx.Flow(
-                        'Heat',
                         bus='Heat',
                         size=size_param,
                         relative_minimum=0.2,
                         status_parameters=status_param,
                     ),
-                    fuel_flow=fx.Flow('Gas', bus='Gas'),
+                    fuel_flow=fx.Flow(bus='Gas'),
                 )
             )
 
@@ -356,8 +361,8 @@ def create_large_system(
                 eta_charge=0.95,
                 eta_discharge=0.95,
                 relative_loss_per_hour=0.001,
-                charging=fx.Flow('Charge', bus='Heat', size=100),
-                discharging=fx.Flow('Discharge', bus='Heat', size=100),
+                charging=fx.Flow(bus='Heat', size=100),
+                discharging=fx.Flow(bus='Heat', size=100),
             )
         )
 

docs/home/quick-start.md

@@ -51,10 +51,9 @@ solar_profile = np.array([0, 0, 0, 0, 0, 0, 0.2, 0.5, 0.8, 1.0,
                           1.0, 0.9, 0.8, 0.7, 0.5, 0.3, 0.1, 0,
                           0, 0, 0, 0, 0, 0])
 
-solar = fx.Source(
+solar = fx.Port(
     'solar',
-    outputs=[fx.Flow(
-        'power',
+    imports=[fx.Flow(
         bus='electricity',
         size=100,  # 100 kW capacity
         relative_maximum=solar_profile
@@ -66,18 +65,17 @@ demand_profile = np.array([30, 25, 20, 20, 25, 35, 50, 70, 80, 75,
                            70, 65, 60, 65, 70, 80, 90, 95, 85, 70,
                            60, 50, 40, 35])
 
-demand = fx.Sink('demand', inputs=[
-    fx.Flow('consumption',
-            bus='electricity',
+demand = fx.Port('demand', exports=[
+    fx.Flow(bus='electricity',
             size=1,
             fixed_relative_profile=demand_profile)
 ])
 
 # Battery storage
 battery = fx.Storage(
     'battery',
-    charging=fx.Flow('charge', bus='electricity', size=50),
-    discharging=fx.Flow('discharge', bus='electricity', size=50),
+    charging=fx.Flow(bus='electricity', size=50),
+    discharging=fx.Flow(bus='electricity', size=50),
     capacity_in_flow_hours=100,  # 100 kWh capacity
     initial_charge_state=50,  # Start at 50%
     eta_charge=0.95,

docs/notebooks/01-quickstart.ipynb

@@ -14,7 +14,7 @@
     "- **FlowSystem**: The container for your energy system model\n",
     "- **Bus**: Balance nodes where energy flows meet\n",
     "- **Effect**: Quantities to track and optimize (costs, emissions)\n",
-    "- **Components**: Equipment like boilers, sources, and sinks\n",
+    "- **Components**: Equipment like boilers and ports\n",
     "- **Flow**: Connections between components and buses"
    ]
   },
@@ -125,21 +125,21 @@
     "    # === Effect: What we want to minimize ===\n",
     "    fx.Effect('costs', '€', 'Total Costs', is_standard=True, is_objective=True),\n",
     "    # === Gas Supply: Unlimited gas at 0.08 €/kWh ===\n",
-    "    fx.Source(\n",
+    "    fx.Port(\n",
     "        'GasGrid',\n",
-    "        outputs=[fx.Flow('Gas', bus='Gas', size=1000, effects_per_flow_hour=0.08)],\n",
+    "        imports=[fx.Flow(bus='Gas', size=1000, effects_per_flow_hour=0.08)],\n",
     "    ),\n",
     "    # === Boiler: Converts gas to heat at 90% efficiency ===\n",
-    "    fx.linear_converters.Boiler(\n",
+    "    fx.Converter.boiler(\n",
     "        'Boiler',\n",
     "        thermal_efficiency=0.9,\n",
-    "        thermal_flow=fx.Flow('Heat', bus='Heat', size=100),  # 100 kW capacity\n",
-    "        fuel_flow=fx.Flow('Gas', bus='Gas'),\n",
+    "        thermal_flow=fx.Flow(bus='Heat', size=100),  # 100 kW capacity\n",
+    "        fuel_flow=fx.Flow(bus='Gas'),\n",
     "    ),\n",
     "    # === Workshop: Heat demand that must be met ===\n",
-    "    fx.Sink(\n",
+    "    fx.Port(\n",
     "        'Workshop',\n",
-    "        inputs=[fx.Flow('Heat', bus='Heat', size=1, fixed_relative_profile=heat_demand.values)],\n",
+    "        exports=[fx.Flow(bus='Heat', size=1, fixed_relative_profile=heat_demand.values)],\n",
     "    ),\n",
     ")"
    ]

docs/notebooks/02-heat-system.ipynb

@@ -146,16 +146,16 @@
     "    # === Effect ===\n",
     "    fx.Effect('costs', '€', 'Operating Costs', is_standard=True, is_objective=True),\n",
     "    # === Gas Supply with time-varying price ===\n",
-    "    fx.Source(\n",
+    "    fx.Port(\n",
     "        'GasGrid',\n",
-    "        outputs=[fx.Flow('Gas', bus='Gas', size=500, effects_per_flow_hour=gas_price)],\n",
+    "        imports=[fx.Flow(bus='Gas', size=500, effects_per_flow_hour=gas_price)],\n",
     "    ),\n",
     "    # === Gas Boiler: 150 kW, 92% efficiency ===\n",
-    "    fx.linear_converters.Boiler(\n",
+    "    fx.Converter.boiler(\n",
     "        'Boiler',\n",
     "        thermal_efficiency=0.92,\n",
-    "        thermal_flow=fx.Flow('Heat', bus='Heat', size=150),\n",
-    "        fuel_flow=fx.Flow('Gas', bus='Gas'),\n",
+    "        thermal_flow=fx.Flow(bus='Heat', size=150),\n",
+    "        fuel_flow=fx.Flow(bus='Gas'),\n",
     "    ),\n",
     "    # === Thermal Storage: 500 kWh tank ===\n",
     "    fx.Storage(\n",
@@ -166,13 +166,13 @@
     "        eta_charge=0.98,  # 98% charging efficiency\n",
     "        eta_discharge=0.98,  # 98% discharging efficiency\n",
     "        relative_loss_per_hour=0.005,  # 0.5% heat loss per hour\n",
-    "        charging=fx.Flow('Charge', bus='Heat', size=100),  # Max 100 kW charging\n",
-    "        discharging=fx.Flow('Discharge', bus='Heat', size=100),  # Max 100 kW discharging\n",
+    "        charging=fx.Flow(bus='Heat', size=100),  # Max 100 kW charging\n",
+    "        discharging=fx.Flow(bus='Heat', size=100),  # Max 100 kW discharging\n",
     "    ),\n",
     "    # === Office Heat Demand ===\n",
-    "    fx.Sink(\n",
+    "    fx.Port(\n",
     "        'Office',\n",
-    "        inputs=[fx.Flow('Heat', bus='Heat', size=1, fixed_relative_profile=heat_demand)],\n",
+    "        exports=[fx.Flow(bus='Heat', size=1, fixed_relative_profile=heat_demand)],\n",
     "    ),\n",
     ")"
    ]

docs/notebooks/03-investment-optimization.ipynb

@@ -139,23 +139,22 @@
     "    # === Effects ===\n",
     "    fx.Effect('costs', '€', 'Total Costs', is_standard=True, is_objective=True),\n",
     "    # === Gas Supply ===\n",
-    "    fx.Source(\n",
+    "    fx.Port(\n",
     "        'GasGrid',\n",
-    "        outputs=[fx.Flow('Gas', bus='Gas', size=500, effects_per_flow_hour=GAS_PRICE)],\n",
+    "        imports=[fx.Flow(bus='Gas', size=500, effects_per_flow_hour=GAS_PRICE)],\n",
     "    ),\n",
     "    # === Gas Boiler (existing, fixed size) ===\n",
-    "    fx.linear_converters.Boiler(\n",
+    "    fx.Converter.boiler(\n",
     "        'GasBoiler',\n",
     "        thermal_efficiency=0.92,\n",
-    "        thermal_flow=fx.Flow('Heat', bus='Heat', size=200),  # 200 kW existing\n",
-    "        fuel_flow=fx.Flow('Gas', bus='Gas'),\n",
+    "        thermal_flow=fx.Flow(bus='Heat', size=200),  # 200 kW existing\n",
+    "        fuel_flow=fx.Flow(bus='Gas'),\n",
     "    ),\n",
     "    # === Solar Collectors (size to be optimized) ===\n",
-    "    fx.Source(\n",
+    "    fx.Port(\n",
     "        'SolarCollectors',\n",
-    "        outputs=[\n",
+    "        imports=[\n",
     "            fx.Flow(\n",
-    "                'Heat',\n",
     "                bus='Heat',\n",
     "                # Investment optimization: find optimal size between 0-500 kW\n",
     "                size=fx.InvestParameters(\n",
@@ -181,13 +180,13 @@
     "        eta_charge=0.95,\n",
     "        eta_discharge=0.95,\n",
     "        relative_loss_per_hour=0.01,  # 1% loss per hour\n",
-    "        charging=fx.Flow('Charge', bus='Heat', size=200),\n",
-    "        discharging=fx.Flow('Discharge', bus='Heat', size=200),\n",
+    "        charging=fx.Flow(bus='Heat', size=200),\n",
+    "        discharging=fx.Flow(bus='Heat', size=200),\n",
     "    ),\n",
     "    # === Pool Heat Demand ===\n",
-    "    fx.Sink(\n",
+    "    fx.Port(\n",
     "        'Pool',\n",
-    "        inputs=[fx.Flow('Heat', bus='Heat', size=1, fixed_relative_profile=pool_demand)],\n",
+    "        exports=[fx.Flow(bus='Heat', size=1, fixed_relative_profile=pool_demand)],\n",
     "    ),\n",
     ")"
    ]
@@ -404,7 +403,7 @@
     "\n",
     "### Where to Use InvestParameters\n",
     "\n",
-    "- **Flow.size**: Optimize converter/source/sink capacity\n",
+    "- **Flow.size**: Optimize converter/port capacity\n",
     "- **Storage.capacity_in_flow_hours**: Optimize storage capacity\n",
     "\n",
     "## Summary\n",

docs/notebooks/04-operational-constraints.ipynb

@@ -124,12 +124,12 @@
     "    # === Effect ===\n",
     "    fx.Effect('costs', '€', 'Operating Costs', is_standard=True, is_objective=True),\n",
     "    # === Gas Supply ===\n",
-    "    fx.Source(\n",
+    "    fx.Port(\n",
     "        'GasGrid',\n",
-    "        outputs=[fx.Flow('Gas', bus='Gas', size=1000, effects_per_flow_hour=0.06)],\n",
+    "        imports=[fx.Flow(bus='Gas', size=1000, effects_per_flow_hour=0.06)],\n",
     "    ),\n",
     "    # === Main Industrial Boiler (with operational constraints) ===\n",
-    "    fx.linear_converters.Boiler(\n",
+    "    fx.Converter.boiler(\n",
     "        'MainBoiler',\n",
     "        thermal_efficiency=0.94,  # High efficiency\n",
     "        # StatusParameters define on/off behavior\n",
@@ -144,20 +144,20 @@
     "            size=500,\n",
     "            relative_minimum=0.3,  # Minimum load: 30% = 150 kW\n",
     "        ),\n",
-    "        fuel_flow=fx.Flow('Gas', bus='Gas', size=600),  # Size required for status_parameters\n",
+    "        fuel_flow=fx.Flow(bus='Gas', size=600),  # Size required for status_parameters\n",
     "    ),\n",
     "    # === Backup Boiler (flexible, but less efficient) ===\n",
-    "    fx.linear_converters.Boiler(\n",
+    "    fx.Converter.boiler(\n",
     "        'BackupBoiler',\n",
     "        thermal_efficiency=0.85,  # Lower efficiency\n",
     "        # No status parameters = can turn on/off freely\n",
-    "        thermal_flow=fx.Flow('Steam', bus='Steam', size=150),\n",
-    "        fuel_flow=fx.Flow('Gas', bus='Gas'),\n",
+    "        thermal_flow=fx.Flow(bus='Steam', size=150),\n",
+    "        fuel_flow=fx.Flow(bus='Gas'),\n",
     "    ),\n",
     "    # === Factory Steam Demand ===\n",
-    "    fx.Sink(\n",
+    "    fx.Port(\n",
     "        'Factory',\n",
-    "        inputs=[fx.Flow('Steam', bus='Steam', size=1, fixed_relative_profile=steam_demand)],\n",
+    "        exports=[fx.Flow(bus='Steam', size=1, fixed_relative_profile=steam_demand)],\n",
     "    ),\n",
     ")"
    ]
@@ -340,21 +340,21 @@
     "    fx.Bus('Gas', carrier='gas'),\n",
     "    fx.Bus('Steam', carrier='steam'),\n",
     "    fx.Effect('costs', '€', 'Operating Costs', is_standard=True, is_objective=True),\n",
-    "    fx.Source('GasGrid', outputs=[fx.Flow('Gas', bus='Gas', size=1000, effects_per_flow_hour=0.06)]),\n",
+    "    fx.Port('GasGrid', imports=[fx.Flow(bus='Gas', size=1000, effects_per_flow_hour=0.06)]),\n",
     "    # Main boiler WITHOUT status parameters\n",
-    "    fx.linear_converters.Boiler(\n",
+    "    fx.Converter.boiler(\n",
     "        'MainBoiler',\n",
     "        thermal_efficiency=0.94,\n",
-    "        thermal_flow=fx.Flow('Steam', bus='Steam', size=500),\n",
-    "        fuel_flow=fx.Flow('Gas', bus='Gas'),\n",
+    "        thermal_flow=fx.Flow(bus='Steam', size=500),\n",
+    "        fuel_flow=fx.Flow(bus='Gas'),\n",
     "    ),\n",
-    "    fx.linear_converters.Boiler(\n",
+    "    fx.Converter.boiler(\n",
     "        'BackupBoiler',\n",
     "        thermal_efficiency=0.85,\n",
-    "        thermal_flow=fx.Flow('Steam', bus='Steam', size=150),\n",
-    "        fuel_flow=fx.Flow('Gas', bus='Gas'),\n",
+    "        thermal_flow=fx.Flow(bus='Steam', size=150),\n",
+    "        fuel_flow=fx.Flow(bus='Gas'),\n",
     "    ),\n",
-    "    fx.Sink('Factory', inputs=[fx.Flow('Steam', bus='Steam', size=1, fixed_relative_profile=steam_demand)]),\n",
+    "    fx.Port('Factory', exports=[fx.Flow(bus='Steam', size=1, fixed_relative_profile=steam_demand)]),\n",
     ")\n",
     "\n",
     "fs_unconstrained.optimize(fx.solvers.HighsSolver())\n",
@@ -559,7 +559,7 @@
     "\n",
     "Set via `Flow.relative_minimum`:\n",
     "```python\n",
-    "fx.Flow('Steam', bus='Steam', size=500, relative_minimum=0.3)  # Min 30% load\n",
+    "fx.Flow(bus='Steam', size=500, relative_minimum=0.3)  # Min 30% load\n",
     "```\n",
     "\n",
     "### When Status is Active\n",