flixopt 3.2.1__py3-none-any.whl → 3.4.0__py3-none-any.whl

flixopt/elements.py

@@ -11,6 +11,7 @@ from typing import TYPE_CHECKING
 import numpy as np
 import xarray as xr
 
+from . import io as fx_io
 from .config import CONFIG
 from .core import PlausibilityError, Scalar, TemporalData, TemporalDataUser
 from .features import InvestmentModel, OnOffModel
@@ -86,10 +87,12 @@ class Component(Element):
         super().__init__(label, meta_data=meta_data)
         self.inputs: list[Flow] = inputs or []
         self.outputs: list[Flow] = outputs or []
-        self._check_unique_flow_labels()
         self.on_off_parameters = on_off_parameters
         self.prevent_simultaneous_flows: list[Flow] = prevent_simultaneous_flows or []
 
+        self._check_unique_flow_labels()
+        self._connect_flows()
+
         self.flows: dict[str, Flow] = {flow.label: flow for flow in self.inputs + self.outputs}
 
     def create_model(self, model: FlowSystemModel) -> ComponentModel:
@@ -115,6 +118,48 @@ class Component(Element):
     def _plausibility_checks(self) -> None:
         self._check_unique_flow_labels()
 
+    def _connect_flows(self):
+        # Inputs
+        for flow in self.inputs:
+            if flow.component not in ('UnknownComponent', self.label_full):
+                raise ValueError(
+                    f'Flow "{flow.label}" already assigned to component "{flow.component}". '
+                    f'Cannot attach to "{self.label_full}".'
+                )
+            flow.component = self.label_full
+            flow.is_input_in_component = True
+        # Outputs
+        for flow in self.outputs:
+            if flow.component not in ('UnknownComponent', self.label_full):
+                raise ValueError(
+                    f'Flow "{flow.label}" already assigned to component "{flow.component}". '
+                    f'Cannot attach to "{self.label_full}".'
+                )
+            flow.component = self.label_full
+            flow.is_input_in_component = False
+
+        # Validate prevent_simultaneous_flows: only allow local flows
+        if self.prevent_simultaneous_flows:
+            # Deduplicate while preserving order
+            seen = set()
+            self.prevent_simultaneous_flows = [
+                f for f in self.prevent_simultaneous_flows if id(f) not in seen and not seen.add(id(f))
+            ]
+            local = set(self.inputs + self.outputs)
+            foreign = [f for f in self.prevent_simultaneous_flows if f not in local]
+            if foreign:
+                names = ', '.join(f.label_full for f in foreign)
+                raise ValueError(
+                    f'prevent_simultaneous_flows for "{self.label_full}" must reference its own flows. '
+                    f'Foreign flows detected: {names}'
+                )
+
+    def __repr__(self) -> str:
+        """Return string representation with flow information."""
+        return fx_io.build_repr_from_init(
+            self, excluded_params={'self', 'label', 'inputs', 'outputs', 'kwargs'}, skip_default_size=True
+        ) + fx_io.format_flow_details(self)
+
 
 @register_class_for_io
 class Bus(Element):
@@ -178,6 +223,8 @@ class Bus(Element):
         by the FlowSystem during system setup.
     """
 
+    submodel: BusModel | None
+
     def __init__(
         self,
         label: str,
@@ -216,6 +263,10 @@ class Bus(Element):
     def with_excess(self) -> bool:
         return False if self.excess_penalty_per_flow_hour is None else True
 
+    def __repr__(self) -> str:
+        """Return string representation."""
+        return super().__repr__() + fx_io.format_flow_details(self)
+
 
 @register_class_for_io
 class Connection:
@@ -362,6 +413,8 @@ class Flow(Element):
 
     """
 
+    submodel: FlowModel | None
+
     def __init__(
         self,
         label: str,
@@ -493,6 +546,10 @@ class Flow(Element):
         # Wenn kein InvestParameters existiert --> True; Wenn Investparameter, den Wert davon nehmen
         return False if (isinstance(self.size, InvestParameters) and self.size.fixed_size is None) else True
 
+    def _format_invest_params(self, params: InvestParameters) -> str:
+        """Format InvestParameters for display."""
+        return f'size: {params.format_for_repr()}'
+
 
 class FlowModel(ElementModel):
     element: Flow  # Type hint

flixopt/flow_system.py

@@ -6,12 +6,14 @@ from __future__ import annotations
 
 import logging
 import warnings
+from itertools import chain
 from typing import TYPE_CHECKING, Any, Literal, Optional
 
 import numpy as np
 import pandas as pd
 import xarray as xr
 
+from . import io as fx_io
 from .config import CONFIG
 from .core import (
     ConversionError,
@@ -32,7 +34,7 @@ from .effects import (
     TemporalEffectsUser,
 )
 from .elements import Bus, Component, Flow
-from .structure import Element, FlowSystemModel, Interface
+from .structure import CompositeContainerMixin, Element, ElementContainer, FlowSystemModel, Interface
 
 if TYPE_CHECKING:
     import pathlib
@@ -43,11 +45,13 @@ if TYPE_CHECKING:
 logger = logging.getLogger('flixopt')
 
 
-class FlowSystem(Interface):
+class FlowSystem(Interface, CompositeContainerMixin[Element]):
     """
-    A FlowSystem organizes the high level Elements (Components, Buses & Effects).
+    A FlowSystem organizes the high level Elements (Components, Buses, Effects & Flows).
 
-    This is the main container class that users work with to build and manage their System.
+    This is the main container class that users work with to build and manage their energy or material flow system.
+    FlowSystem provides both direct container access (via .components, .buses, .effects, .flows) and a unified
+    dict-like interface for accessing any element by label across all container types.
 
     Args:
         timesteps: The timesteps of the model.
@@ -69,12 +73,78 @@ class FlowSystem(Interface):
             - False: All flow rates are optimized separately per scenario
             - list[str]: Only specified flows (by label_full) are equalized across scenarios
 
+    Examples:
+        Creating a FlowSystem and accessing elements:
+
+        >>> import flixopt as fx
+        >>> import pandas as pd
+        >>> timesteps = pd.date_range('2023-01-01', periods=24, freq='h')
+        >>> flow_system = fx.FlowSystem(timesteps)
+        >>>
+        >>> # Add elements to the system
+        >>> boiler = fx.Component('Boiler', inputs=[heat_flow], on_off_parameters=...)
+        >>> heat_bus = fx.Bus('Heat', excess_penalty_per_flow_hour=1e4)
+        >>> costs = fx.Effect('costs', is_objective=True, is_standard=True)
+        >>> flow_system.add_elements(boiler, heat_bus, costs)
+
+        Unified dict-like access (recommended for most cases):
+
+        >>> # Access any element by label, regardless of type
+        >>> boiler = flow_system['Boiler']  # Returns Component
+        >>> heat_bus = flow_system['Heat']  # Returns Bus
+        >>> costs = flow_system['costs']  # Returns Effect
+        >>>
+        >>> # Check if element exists
+        >>> if 'Boiler' in flow_system:
+        ...     print('Boiler found in system')
+        >>>
+        >>> # Iterate over all elements
+        >>> for label in flow_system.keys():
+        ...     element = flow_system[label]
+        ...     print(f'{label}: {type(element).__name__}')
+        >>>
+        >>> # Get all element labels and objects
+        >>> all_labels = list(flow_system.keys())
+        >>> all_elements = list(flow_system.values())
+        >>> for label, element in flow_system.items():
+        ...     print(f'{label}: {element}')
+
+        Direct container access for type-specific operations:
+
+        >>> # Access specific container when you need type filtering
+        >>> for component in flow_system.components.values():
+        ...     print(f'{component.label}: {len(component.inputs)} inputs')
+        >>>
+        >>> # Access buses directly
+        >>> for bus in flow_system.buses.values():
+        ...     print(f'{bus.label}')
+        >>>
+        >>> # Flows are automatically collected from all components
+        >>> for flow in flow_system.flows.values():
+        ...     print(f'{flow.label_full}: {flow.size}')
+        >>>
+        >>> # Access effects
+        >>> for effect in flow_system.effects.values():
+        ...     print(f'{effect.label}')
+
     Notes:
+        - The dict-like interface (`flow_system['element']`) searches across all containers
+          (components, buses, effects, flows) to find the element with the matching label.
+        - Element labels must be unique across all container types. Attempting to add
+          elements with duplicate labels will raise an error, ensuring each label maps to exactly one element.
+        - The `.all_elements` property is deprecated. Use the dict-like interface instead:
+          `flow_system['element']`, `'element' in flow_system`, `flow_system.keys()`,
+          `flow_system.values()`, or `flow_system.items()`.
+        - Direct container access (`.components`, `.buses`, `.effects`, `.flows`) is useful
+          when you need type-specific filtering or operations.
+        - The `.flows` container is automatically populated from all component inputs and outputs.
         - Creates an empty registry for components and buses, an empty EffectCollection, and a placeholder for a SystemModel.
         - The instance starts disconnected (self._connected_and_transformed == False) and will be
-        connected_and_transformed automatically when trying to solve a calculation.
+          connected_and_transformed automatically when trying to solve a calculation.
     """
 
+    model: FlowSystemModel | None
+
     def __init__(
         self,
         timesteps: pd.DatetimeIndex,
@@ -104,8 +174,8 @@ class FlowSystem(Interface):
         self.hours_per_timestep = self.fit_to_model_coords('hours_per_timestep', hours_per_timestep)
 
         # Element collections
-        self.components: dict[str, Component] = {}
-        self.buses: dict[str, Bus] = {}
+        self.components: ElementContainer[Component] = ElementContainer(element_type_name='components')
+        self.buses: ElementContainer[Bus] = ElementContainer(element_type_name='buses')
         self.effects: EffectCollection = EffectCollection()
         self.model: FlowSystemModel | None = None
 
@@ -113,6 +183,7 @@ class FlowSystem(Interface):
         self._used_in_calculation = False
 
         self._network_app = None
+        self._flows_cache: ElementContainer[Flow] | None = None
 
         # Use properties to validate and store scenario dimension settings
         self.scenario_independent_sizes = scenario_independent_sizes
@@ -232,7 +303,7 @@ class FlowSystem(Interface):
 
         # Extract from effects
         effects_structure = {}
-        for effect in self.effects:
+        for effect in self.effects.values():
             effect_structure, effect_arrays = effect._create_reference_structure()
             all_extracted_arrays.update(effect_arrays)
             effects_structure[effect.label] = effect_structure
@@ -433,7 +504,7 @@ class FlowSystem(Interface):
         self.weights = self.fit_to_model_coords('weights', self.weights, dims=['period', 'scenario'])
 
         self._connect_network()
-        for element in list(self.components.values()) + list(self.effects.effects.values()) + list(self.buses.values()):
+        for element in chain(self.components.values(), self.effects.values(), self.buses.values()):
             element.transform_data(self)
         self._connected_and_transformed = True
 
@@ -581,7 +652,7 @@ class FlowSystem(Interface):
                 'class': 'Bus' if isinstance(node, Bus) else 'Component',
                 'infos': node.__str__(),
             }
-            for node in list(self.components.values()) + list(self.buses.values())
+            for node in chain(self.components.values(), self.buses.values())
         }
 
         edges = {
@@ -603,10 +674,8 @@ class FlowSystem(Interface):
         Args:
             element: new element to check
         """
-        if element in self.all_elements.values():
-            raise ValueError(f'Element {element.label_full} already added to FlowSystem!')
         # check if name is already used:
-        if element.label_full in self.all_elements:
+        if element.label_full in self:
             raise ValueError(f'Label of Element {element.label_full} already used in another element!')
 
     def _add_effects(self, *args: Effect) -> None:
@@ -616,13 +685,15 @@ class FlowSystem(Interface):
         for new_component in list(components):
             logger.info(f'Registered new Component: {new_component.label_full}')
             self._check_if_element_is_unique(new_component)  # check if already exists:
-            self.components[new_component.label_full] = new_component  # Add to existing components
+            self.components.add(new_component)  # Add to existing components
+            self._flows_cache = None  # Invalidate flows cache
 
     def _add_buses(self, *buses: Bus):
         for new_bus in list(buses):
             logger.info(f'Registered new Bus: {new_bus.label_full}')
             self._check_if_element_is_unique(new_bus)  # check if already exists:
-            self.buses[new_bus.label_full] = new_bus  # Add to existing components
+            self.buses.add(new_bus)  # Add to existing buses
+            self._flows_cache = None  # Invalidate flows cache
 
     def _connect_network(self):
         """Connects the network of components and buses. Can be rerun without changes if no elements were added"""
@@ -632,7 +703,7 @@ class FlowSystem(Interface):
                 flow.is_input_in_component = True if flow in component.inputs else False
 
                 # Add Bus if not already added (deprecated)
-                if flow._bus_object is not None and flow._bus_object not in self.buses.values():
+                if flow._bus_object is not None and flow._bus_object.label_full not in self.buses:
                     warnings.warn(
                         f'The Bus {flow._bus_object.label_full} was added to the FlowSystem from {flow.label_full}.'
                         f'This is deprecated and will be removed in the future. '
@@ -659,62 +730,40 @@ class FlowSystem(Interface):
         )
 
     def __repr__(self) -> str:
-        """Compact representation for debugging."""
-        status = '✓' if self.connected_and_transformed else '⚠'
-
-        # Build dimension info
-        dims = f'{len(self.timesteps)} timesteps [{self.timesteps[0].strftime("%Y-%m-%d")} to {self.timesteps[-1].strftime("%Y-%m-%d")}]'
-        if self.periods is not None:
-            dims += f', {len(self.periods)} periods'
-        if self.scenarios is not None:
-            dims += f', {len(self.scenarios)} scenarios'
-
-        return f'FlowSystem({dims}, {len(self.components)} Components,  {len(self.buses)} Buses, {len(self.effects)} Effects, {status})'
-
-    def __str__(self) -> str:
-        """Structured summary for users."""
-
-        def format_elements(element_names: list, label: str, alignment: int = 12):
-            name_list = ', '.join(element_names[:3])
-            if len(element_names) > 3:
-                name_list += f' ... (+{len(element_names) - 3} more)'
+        """Return a detailed string representation showing all containers."""
+        r = fx_io.format_title_with_underline('FlowSystem', '=')
 
-            suffix = f' ({name_list})' if element_names else ''
-            padding = alignment - len(label) - 1  # -1 for the colon
-            return f'{label}:{"":<{padding}} {len(element_names)}{suffix}'
-
-        time_period = f'Time period: {self.timesteps[0].date()} to {self.timesteps[-1].date()}'
+        # Timestep info
+        time_period = f'{self.timesteps[0].date()} to {self.timesteps[-1].date()}'
         freq_str = str(self.timesteps.freq).replace('<', '').replace('>', '') if self.timesteps.freq else 'irregular'
-
-        lines = [
-            f'Timesteps:   {len(self.timesteps)} ({freq_str}) [{time_period}]',
-        ]
+        r += f'Timesteps: {len(self.timesteps)} ({freq_str}) [{time_period}]\n'
 
         # Add periods if present
         if self.periods is not None:
             period_names = ', '.join(str(p) for p in self.periods[:3])
             if len(self.periods) > 3:
                 period_names += f' ... (+{len(self.periods) - 3} more)'
-            lines.append(f'Periods:     {len(self.periods)} ({period_names})')
+            r += f'Periods: {len(self.periods)} ({period_names})\n'
+        else:
+            r += 'Periods: None\n'
 
         # Add scenarios if present
         if self.scenarios is not None:
             scenario_names = ', '.join(str(s) for s in self.scenarios[:3])
             if len(self.scenarios) > 3:
                 scenario_names += f' ... (+{len(self.scenarios) - 3} more)'
-            lines.append(f'Scenarios:   {len(self.scenarios)} ({scenario_names})')
-
-        lines.extend(
-            [
-                format_elements(list(self.components.keys()), 'Components'),
-                format_elements(list(self.buses.keys()), 'Buses'),
-                format_elements(list(self.effects.effects.keys()), 'Effects'),
-                f'Status:      {"Connected & Transformed" if self.connected_and_transformed else "Not connected"}',
-            ]
-        )
-        lines = ['FlowSystem:', f'{"─" * max(len(line) for line in lines)}'] + lines
+            r += f'Scenarios: {len(self.scenarios)} ({scenario_names})\n'
+        else:
+            r += 'Scenarios: None\n'
+
+        # Add status
+        status = '✓' if self.connected_and_transformed else '⚠'
+        r += f'Status: {status}\n'
+
+        # Add grouped container view
+        r += '\n' + self._format_grouped_containers()
 
-        return '\n'.join(lines)
+        return r
 
     def __eq__(self, other: FlowSystem):
         """Check if two FlowSystems are equal by comparing their dataset representations."""
@@ -734,38 +783,46 @@ class FlowSystem(Interface):
 
         return True
 
-    def __getitem__(self, item) -> Element:
-        """Get element by exact label with helpful error messages."""
-        if item in self.all_elements:
-            return self.all_elements[item]
-
-        # Provide helpful error with suggestions
-        from difflib import get_close_matches
-
-        suggestions = get_close_matches(item, self.all_elements.keys(), n=3, cutoff=0.6)
-
-        if suggestions:
-            suggestion_str = ', '.join(f"'{s}'" for s in suggestions)
-            raise KeyError(f"Element '{item}' not found. Did you mean: {suggestion_str}?")
-        else:
-            raise KeyError(f"Element '{item}' not found in FlowSystem")
-
-    def __contains__(self, item: str) -> bool:
-        """Check if element exists in the FlowSystem."""
-        return item in self.all_elements
-
-    def __iter__(self):
-        """Iterate over element labels."""
-        return iter(self.all_elements.keys())
+    def _get_container_groups(self) -> dict[str, ElementContainer]:
+        """Return ordered container groups for CompositeContainerMixin."""
+        return {
+            'Components': self.components,
+            'Buses': self.buses,
+            'Effects': self.effects,
+            'Flows': self.flows,
+        }
 
     @property
-    def flows(self) -> dict[str, Flow]:
-        set_of_flows = {flow for comp in self.components.values() for flow in comp.inputs + comp.outputs}
-        return {flow.label_full: flow for flow in set_of_flows}
+    def flows(self) -> ElementContainer[Flow]:
+        if self._flows_cache is None:
+            flows = [f for c in self.components.values() for f in c.inputs + c.outputs]
+            # Deduplicate by id and sort for reproducibility
+            flows = sorted({id(f): f for f in flows}.values(), key=lambda f: f.label_full.lower())
+            self._flows_cache = ElementContainer(flows, element_type_name='flows')
+        return self._flows_cache
 
     @property
     def all_elements(self) -> dict[str, Element]:
-        return {**self.components, **self.effects.effects, **self.flows, **self.buses}
+        """
+        Get all elements as a dictionary.
+
+        .. deprecated:: 3.2.0
+            Use dict-like interface instead: `flow_system['element']`, `'element' in flow_system`,
+            `flow_system.keys()`, `flow_system.values()`, or `flow_system.items()`.
+            This property will be removed in v4.0.0.
+
+        Returns:
+            Dictionary mapping element labels to element objects.
+        """
+        warnings.warn(
+            "The 'all_elements' property is deprecated. Use dict-like interface instead: "
+            "flow_system['element'], 'element' in flow_system, flow_system.keys(), "
+            'flow_system.values(), or flow_system.items(). '
+            'This property will be removed in v4.0.0.',
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return {**self.components, **self.effects, **self.flows, **self.buses}
 
     @property
     def coords(self) -> dict[FlowSystemDimensions, pd.Index]:

flixopt/interface.py

@@ -7,7 +7,7 @@ from __future__ import annotations
 
 import logging
 import warnings
-from typing import TYPE_CHECKING, Literal, Optional
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
 import pandas as pd
@@ -1051,6 +1051,27 @@ class InvestParameters(Interface):
     def maximum_or_fixed_size(self) -> PeriodicData:
         return self.fixed_size if self.fixed_size is not None else self.maximum_size
 
+    def format_for_repr(self) -> str:
+        """Format InvestParameters for display in repr methods.
+
+        Returns:
+            Formatted string showing size information
+        """
+        from .io import numeric_to_str_for_repr
+
+        if self.fixed_size is not None:
+            val = numeric_to_str_for_repr(self.fixed_size)
+            status = 'mandatory' if self.mandatory else 'optional'
+            return f'{val} ({status})'
+
+        # Show range if available
+        parts = []
+        if self.minimum_size is not None:
+            parts.append(f'min: {numeric_to_str_for_repr(self.minimum_size)}')
+        if self.maximum_size is not None:
+            parts.append(f'max: {numeric_to_str_for_repr(self.maximum_size)}')
+        return ', '.join(parts) if parts else 'invest'
+
     @staticmethod
     def compute_linked_periods(first_period: int, last_period: int, periods: pd.Index | list[int]) -> xr.DataArray:
         return xr.DataArray(
@@ -1324,7 +1345,7 @@ class OnOffParameters(Interface):
             return True
 
         return any(
-            param is not None and param != {}
+            self._has_value(param)
             for param in [
                 self.effects_per_switch_on,
                 self.switch_on_total_max,