flixopt 1.0.12__py3-none-any.whl → 2.0.1__py3-none-any.whl

flixOpt/flow_system.py

@@ -1,351 +0,0 @@
-"""
-This module contains the FlowSystem class, which is used to collect instances of many other classes by the end User.
-"""
-
-import json
-import logging
-import pathlib
-from typing import TYPE_CHECKING, Dict, List, Literal, Optional, Tuple, Union
-
-import numpy as np
-
-from . import utils
-from .core import TimeSeries
-from .effects import Effect, EffectCollection
-from .elements import Bus, Component, Flow
-from .structure import Element, SystemModel, get_compact_representation, get_str_representation
-
-if TYPE_CHECKING:
-    import pyvis
-
-logger = logging.getLogger('flixOpt')
-
-
-class FlowSystem:
-    """
-    A FlowSystem organizes the high level Elements (Components & Effects).
-    """
-
-    def __init__(
-        self,
-        time_series: np.ndarray[np.datetime64],
-        last_time_step_hours: Optional[Union[int, float]] = None,
-        previous_dt_in_hours: Optional[Union[int, float, np.ndarray]] = None,
-    ):
-        """
-        Parameters
-        ----------
-        time_series : np.ndarray of datetime64
-            timeseries of the data. Must be in datetime64 format. Don't use precisions below 'us'. !np.datetime64[ns]!
-        last_time_step_hours :
-            The duration of last time step.
-            Storages needs this time-duration for calculation of charge state
-            after last time step.
-            If None, then last time increment of time_series is used.
-        previous_dt_in_hours : Union[int, float, np.ndarray]
-            The duration of previous time steps.
-            If None, the first time increment of time_series is used.
-            This is needed to calculate previous durations (for example consecutive_on_hours).
-            If you use an array, take care that its long enough to cover all previous values!
-        """
-        self.time_series = time_series if isinstance(time_series, np.ndarray) else np.array(time_series)
-        if self.time_series.dtype == np.dtype('datetime64[ns]'):
-            self.time_series = self.time_series.astype('datetime64[us]')
-
-        self.last_time_step_hours = (
-            self.time_series[-1] - self.time_series[-2] if last_time_step_hours is None else last_time_step_hours
-        )
-        self.time_series_with_end = np.append(self.time_series, self.time_series[-1] + self.last_time_step_hours)
-        self.previous_dt_in_hours: Union[int, float, np.ndarray] = (
-            ((self.time_series[1] - self.time_series[0]) / np.timedelta64(1, 'h'))
-            if previous_dt_in_hours is None
-            else previous_dt_in_hours
-        )
-
-        utils.check_time_series('time series of FlowSystem', self.time_series_with_end)
-
-        # defaults:
-        self.components: Dict[str, Component] = {}
-        self.effect_collection: EffectCollection = EffectCollection('Effects')  # Organizes Effects, Penalty & Objective
-        self.model: Optional[SystemModel] = None
-
-    def add_effects(self, *args: Effect) -> None:
-        for new_effect in list(args):
-            logger.info(f'Registered new Effect: {new_effect.label}')
-            self.effect_collection.add_effect(new_effect)
-
-    def add_components(self, *args: Component) -> None:
-        # Komponenten registrieren:
-        new_components = list(args)
-        for new_component in new_components:
-            logger.info(f'Registered new Component: {new_component.label}')
-            self._check_if_element_is_unique(new_component)  # check if already exists:
-            new_component.register_component_in_flows()  # Komponente in Flow registrieren
-            new_component.register_flows_in_bus()  # Flows in Bus registrieren:
-            self.components[new_component.label] = new_component  # Add to existing components
-
-    def add_elements(self, *args: Element) -> None:
-        """
-        add all modeling elements, like storages, boilers, heatpumps, buses, ...
-
-        Parameters
-        ----------
-        *args : childs of  Element like Boiler, HeatPump, Bus,...
-            modeling Elements
-
-        """
-        for new_element in list(args):
-            if isinstance(new_element, Component):
-                self.add_components(new_element)
-            elif isinstance(new_element, Effect):
-                self.add_effects(new_element)
-            else:
-                raise Exception('argument is not instance of a modeling Element (Element)')
-
-    def transform_data(self):
-        for element in self.all_elements.values():
-            element.transform_data()
-
-    def network_infos(self) -> Tuple[Dict[str, Dict[str, str]], Dict[str, Dict[str, str]]]:
-        nodes = {
-            node.label_full: {
-                'label': node.label,
-                'class': 'Bus' if isinstance(node, Bus) else 'Component',
-                'infos': node.__str__(),
-            }
-            for node in list(self.components.values()) + list(self.buses.values())
-        }
-
-        edges = {
-            flow.label_full: {
-                'label': flow.label,
-                'start': flow.bus.label_full if flow.is_input_in_comp else flow.comp.label_full,
-                'end': flow.comp.label_full if flow.is_input_in_comp else flow.bus.label_full,
-                'infos': flow.__str__(),
-            }
-            for flow in self.flows.values()
-        }
-
-        return nodes, edges
-
-    def infos(self, use_numpy=True, use_element_label=False) -> Dict:
-        infos = {
-            'Components': {
-                comp.label: comp.infos(use_numpy, use_element_label)
-                for comp in sorted(self.components.values(), key=lambda component: component.label.upper())
-            },
-            'Buses': {
-                bus.label: bus.infos(use_numpy, use_element_label)
-                for bus in sorted(self.buses.values(), key=lambda bus: bus.label.upper())
-            },
-            'Effects': {
-                effect.label: effect.infos(use_numpy, use_element_label)
-                for effect in sorted(self.effect_collection.effects.values(), key=lambda effect: effect.label.upper())
-            },
-        }
-        return infos
-
-    def to_json(self, path: Union[str, pathlib.Path]):
-        """
-        Saves the flow system to a json file.
-        This not meant to be reloaded and recreate the object, but rather used to document or compare the object.
-
-        Parameters:
-        -----------
-        path : Union[str, pathlib.Path]
-            The path to the json file.
-        """
-        data = get_compact_representation(self.infos(use_numpy=True, use_element_label=True))
-        with open(path, 'w', encoding='utf-8') as f:
-            json.dump(data, f, indent=4, ensure_ascii=False)
-
-    def visualize_network(
-        self,
-        path: Union[bool, str, pathlib.Path] = 'flow_system.html',
-        controls: Union[
-            bool,
-            List[
-                Literal['nodes', 'edges', 'layout', 'interaction', 'manipulation', 'physics', 'selection', 'renderer']
-            ],
-        ] = True,
-        show: bool = True,
-    ) -> Optional['pyvis.network.Network']:
-        """
-        Visualizes the network structure of a FlowSystem using PyVis, saving it as an interactive HTML file.
-
-        Parameters:
-        - path (Union[bool, str, pathlib.Path], default='flow_system.html'):
-          Path to save the HTML visualization.
-            - `False`: Visualization is created but not saved.
-            - `str` or `Path`: Specifies file path (default: 'flow_system.html').
-
-        - controls (Union[bool, List[str]], default=True):
-          UI controls to add to the visualization.
-            - `True`: Enables all available controls.
-            - `List`: Specify controls, e.g., ['nodes', 'layout'].
-            - Options: 'nodes', 'edges', 'layout', 'interaction', 'manipulation', 'physics', 'selection', 'renderer'.
-
-        - show (bool, default=True):
-          Whether to open the visualization in the web browser.
-
-        Returns:
-        - Optional[pyvis.network.Network]: The `Network` instance representing the visualization, or `None` if `pyvis` is not installed.
-
-        Usage:
-        - Visualize and open the network with default options:
-          >>> self.visualize_network()
-
-        - Save the visualization without opening:
-          >>> self.visualize_network(show=False)
-
-        - Visualize with custom controls and path:
-          >>> self.visualize_network(path='output/custom_network.html', controls=['nodes', 'layout'])
-
-        Notes:
-        - This function requires `pyvis`. If not installed, the function prints a warning and returns `None`.
-        - Nodes are styled based on type (e.g., circles for buses, boxes for components) and annotated with node information.
-        """
-        from . import plotting
-
-        node_infos, edge_infos = self.network_infos()
-        return plotting.visualize_network(node_infos, edge_infos, path, controls, show)
-
-    def _check_if_element_is_unique(self, element: Element) -> None:
-        """
-        checks if element or label of element already exists in list
-
-        Parameters
-        ----------
-        element : Element
-            new element to check
-        """
-        if element in self.all_elements:
-            raise Exception(f'Element {element.label} already added to FlowSystem!')
-        # check if name is already used:
-        if element.label_full in self.all_elements:
-            raise Exception(f'Label of Element {element.label} already used in another element!')
-
-    def get_time_data_from_indices(
-        self, time_indices: Optional[Union[List[int], range]] = None
-    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.float64]:
-        """
-        Computes time series data based on the provided time indices.
-
-        Args:
-            time_indices: A list of indices or a range object indicating which time steps to extract.
-                          If None, the entire time series is used.
-
-        Returns:
-            A tuple containing:
-            - Extracted time series
-            - Time series with the "end time" appended
-            - Differences between consecutive timestamps in hours
-            - Total time in hours
-        """
-        # If time_indices is None, use the full time series range
-        if time_indices is None:
-            time_indices = range(len(self.time_series))
-
-        # Extract the time series for the provided indices
-        time_series = self.time_series[time_indices]
-
-        # Ensure the next timestamp for end time is within bounds
-        last_index = time_indices[-1]
-        if last_index + 1 < len(self.time_series_with_end):
-            end_time = self.time_series_with_end[last_index + 1]
-        else:
-            raise IndexError(f"Index {last_index + 1} out of bounds for 'self.time_series_with_end'.")
-
-        # Append end time to the time series
-        time_series_with_end = np.append(time_series, end_time)
-
-        # Calculate time differences (time deltas) in hours
-        time_deltas = time_series_with_end[1:] - time_series_with_end[:-1]
-        dt_in_hours = time_deltas / np.timedelta64(1, 'h')
-
-        # Calculate the total time in hours
-        dt_in_hours_total = np.sum(dt_in_hours)
-
-        return time_series, time_series_with_end, dt_in_hours, dt_in_hours_total
-
-    def __repr__(self):
-        return f'<{self.__class__.__name__} with {len(self.components)} components and {len(self.effect_collection.effects)} effects>'
-
-    def __str__(self):
-        return get_str_representation(self.infos(use_numpy=True, use_element_label=True))
-
-    @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}
-
-    @property
-    def buses(self) -> Dict[str, Bus]:
-        return {flow.bus.label: flow.bus for flow in self.flows.values()}
-
-    @property
-    def all_elements(self) -> Dict[str, Element]:
-        return {**self.components, **self.effect_collection.effects, **self.flows, **self.buses}
-
-    @property
-    def all_time_series(self) -> List[TimeSeries]:
-        return [ts for element in self.all_elements.values() for ts in element.used_time_series]
-
-
-def create_datetime_array(
-    start: str, steps: Optional[int] = None, freq: str = '1h', end: Optional[str] = None
-) -> np.ndarray[np.datetime64]:
-    """
-    Create a NumPy array with datetime64 values.
-
-    Parameters
-    ----------
-    start : str
-        Start date in 'YYYY-MM-DD' format or a full timestamp (e.g., 'YYYY-MM-DD HH:MM').
-    steps : int, optional
-        Number of steps in the datetime array. If `end` is provided, `steps` is ignored.
-    freq : str, optional
-        Frequency for the datetime64 array. Supports flexible intervals:
-        - 'Y', 'M', 'W', 'D', 'h', 'm', 's' (e.g., '1h', '15m', '2h').
-        Defaults to 'h' (hourly).
-    end : str, optional
-        End date in 'YYYY-MM-DD' format or a full timestamp (e.g., 'YYYY-MM-DD HH:MM').
-        If provided, the function generates an array from `start` to `end` using `freq`.
-
-    Returns
-    -------
-    np.ndarray
-        NumPy array of datetime64 values.
-
-    Examples
-    --------
-    Create an array with 15-minute intervals:
-    >>> create_datetime_array('2023-01-01', steps=5, freq='15m')
-    array(['2023-01-01T00:00', '2023-01-01T00:15', '2023-01-01T00:30', ...], dtype='datetime64[m]')
-
-    Create 2-hour intervals:
-    >>> create_datetime_array('2023-01-01T00', steps=4, freq='2h')
-    array(['2023-01-01T00', '2023-01-01T02', '2023-01-01T04', ...], dtype='datetime64[h]')
-
-    Generate minute intervals until a specified end time:
-    >>> create_datetime_array('2023-01-01T00:00', end='2023-01-01T01:00', freq='m')
-    array(['2023-01-01T00:00', '2023-01-01T00:01', ..., '2023-01-01T00:59'], dtype='datetime64[m]')
-    """
-    # Parse the frequency and interval
-    unit = freq[-1]  # Get the time unit (e.g., 'h', 'm', 's')
-    interval = int(freq[:-1]) if freq[:-1].isdigit() else 1  # Default to interval=1 if not specified
-    step_size = np.timedelta64(interval, unit)  # Create the timedelta step size
-
-    # Convert the start time to a datetime64 object
-    start_dt = np.datetime64(start)
-
-    # Generate the array based on the parameters
-    if end:  # If `end` is specified, create a range from start to end
-        end_dt = np.datetime64(end)
-        return np.arange(start_dt, end_dt, step_size)
-
-    elif steps:  # If `steps` is specified, create a range with the given number of steps
-        return np.array([start_dt + i * step_size for i in range(steps)], dtype='datetime64')
-
-    else:  # If neither `steps` nor `end` is provided, raise an error
-        raise ValueError('Either `steps` or `end` must be provided.')

flixOpt/interface.py

@@ -1,203 +0,0 @@
-"""
-This module contains classes to collect Parameters for the Investment and OnOff decisions.
-These are tightly connected to features.py
-"""
-
-import logging
-from typing import TYPE_CHECKING, Dict, List, Optional, Tuple, Union
-
-from .config import CONFIG
-from .core import Numeric, Numeric_TS, Skalar
-from .structure import Element, Interface
-
-if TYPE_CHECKING:
-    from .effects import Effect, EffectTimeSeries, EffectValues, EffectValuesInvest
-
-logger = logging.getLogger('flixOpt')
-
-
-class InvestParameters(Interface):
-    """
-    collects arguments for invest-stuff
-    """
-
-    def __init__(
-        self,
-        fixed_size: Optional[Union[int, float]] = None,
-        minimum_size: Union[int, float] = 0,  # TODO: Use EPSILON?
-        maximum_size: Optional[Union[int, float]] = None,
-        optional: bool = True,  # Investition ist weglassbar
-        fix_effects: Union[Dict, int, float] = None,
-        specific_effects: Union[Dict, int, float] = None,  # costs per Flow-Unit/Storage-Size/...
-        effects_in_segments: Optional[
-            Tuple[List[Tuple[Skalar, Skalar]], Dict['Effect', List[Tuple[Skalar, Skalar]]]]
-        ] = None,
-        divest_effects: Union[Dict, int, float] = None,
-    ):
-        """
-        Parameters
-        ----------
-        fix_effects : None or scalar, optional
-            Fixed investment costs if invested.
-            (Attention: Annualize costs to chosen period!)
-        divest_effects : None or scalar, optional
-            Fixed divestment costs (if not invested, e.g., demolition costs or contractual penalty).
-        fixed_size : int, float, optional
-            Determines if the investment size is fixed.
-        optional : bool, optional
-            If True, investment is not forced.
-        specific_effects : scalar or Dict[Effect: Union[int, float, np.ndarray], optional
-            Specific costs, e.g., in €/kW_nominal or €/m²_nominal.
-            Example: {costs: 3, CO2: 0.3} with costs and CO2 representing an Object of class Effect
-            (Attention: Annualize costs to chosen period!)
-        effects_in_segments : list or List[ List[Union[int,float]], Dict[cEffecType: Union[List[Union[int,float]], optional
-            Linear relation in segments [invest_segments, cost_segments].
-            Example 1:
-                [           [5, 25, 25, 100],       # size in kW
-                 {costs:    [50,250,250,800],       # €
-                  PE:       [5, 25, 25, 100]        # kWh_PrimaryEnergy
-                  }
-                ]
-            Example 2 (if only standard-effect):
-                [   [5, 25, 25, 100],  # kW # size in kW
-                    [50,250,250,800]        # value for standart effect, typically €
-                 ]  # €
-            (Attention: Annualize costs to chosen period!)
-            (Args 'specific_effects' and 'fix_effects' can be used in parallel to InvestsizeSegments)
-        minimum_size : scalar
-            Min nominal value (only if: size_is_fixed = False).
-        maximum_size : scalar, Optional
-            Max nominal value (only if: size_is_fixed = False).
-        """
-        self.fix_effects: EffectValuesInvest = fix_effects or {}
-        self.divest_effects: EffectValuesInvest = divest_effects or {}
-        self.fixed_size = fixed_size
-        self.optional = optional
-        self.specific_effects: EffectValuesInvest = specific_effects or {}
-        self.effects_in_segments = effects_in_segments
-        self._minimum_size = minimum_size
-        self._maximum_size = maximum_size or CONFIG.modeling.BIG  # default maximum
-
-    def transform_data(self):
-        from .effects import as_effect_dict
-
-        self.fix_effects = as_effect_dict(self.fix_effects)
-        self.divest_effects = as_effect_dict(self.divest_effects)
-        self.specific_effects = as_effect_dict(self.specific_effects)
-
-    @property
-    def minimum_size(self):
-        return self.fixed_size or self._minimum_size
-
-    @property
-    def maximum_size(self):
-        return self.fixed_size or self._maximum_size
-
-
-class OnOffParameters(Interface):
-    def __init__(
-        self,
-        effects_per_switch_on: Union[Dict, Numeric] = None,
-        effects_per_running_hour: Union[Dict, Numeric] = None,
-        on_hours_total_min: Optional[int] = None,
-        on_hours_total_max: Optional[int] = None,
-        consecutive_on_hours_min: Optional[Numeric] = None,
-        consecutive_on_hours_max: Optional[Numeric] = None,
-        consecutive_off_hours_min: Optional[Numeric] = None,
-        consecutive_off_hours_max: Optional[Numeric] = None,
-        switch_on_total_max: Optional[int] = None,
-        force_switch_on: bool = False,
-    ):
-        """
-        on_off_parameters class for modeling on and off state of an Element.
-        If no parameters are given, the default is to create a binary variable for the on state
-        without further constraints or effects and a variable for the total on hours.
-
-        Parameters
-        ----------
-        effects_per_switch_on : scalar, array, TimeSeriesData, optional
-            cost of one switch from off (var_on=0) to on (var_on=1),
-            unit i.g. in Euro
-        effects_per_running_hour : scalar or TS, optional
-            costs for operating, i.g. in € per hour
-        on_hours_total_min : scalar, optional
-            min. overall sum of operating hours.
-        on_hours_total_max : scalar, optional
-            max. overall sum of operating hours.
-        consecutive_on_hours_min : scalar, optional
-            min sum of operating hours in one piece
-            (last on-time period of timeseries is not checked and can be shorter)
-        consecutive_on_hours_max : scalar, optional
-            max sum of operating hours in one piece
-        consecutive_off_hours_min : scalar, optional
-            min sum of non-operating hours in one piece
-            (last off-time period of timeseries is not checked and can be shorter)
-        consecutive_off_hours_max : scalar, optional
-            max sum of non-operating hours in one piece
-        switch_on_total_max : integer, optional
-            max nr of switchOn operations
-        force_switch_on : bool
-            force creation of switch on variable, even if there is no switch_on_total_max
-        """
-        self.effects_per_switch_on: Union[EffectValues, EffectTimeSeries] = effects_per_switch_on or {}
-        self.effects_per_running_hour: Union[EffectValues, EffectTimeSeries] = effects_per_running_hour or {}
-        self.on_hours_total_min: Skalar = on_hours_total_min
-        self.on_hours_total_max: Skalar = on_hours_total_max
-        self.consecutive_on_hours_min: Numeric_TS = consecutive_on_hours_min
-        self.consecutive_on_hours_max: Numeric_TS = consecutive_on_hours_max
-        self.consecutive_off_hours_min: Numeric_TS = consecutive_off_hours_min
-        self.consecutive_off_hours_max: Numeric_TS = consecutive_off_hours_max
-        self.switch_on_total_max: Skalar = switch_on_total_max
-        self.force_switch_on: bool = force_switch_on
-
-    def transform_data(self, owner: 'Element'):
-        from .effects import effect_values_to_time_series
-        from .structure import _create_time_series
-
-        self.effects_per_switch_on = effect_values_to_time_series('per_switch_on', self.effects_per_switch_on, owner)
-        self.effects_per_running_hour = effect_values_to_time_series(
-            'per_running_hour', self.effects_per_running_hour, owner
-        )
-        self.consecutive_on_hours_min = _create_time_series(
-            'consecutive_on_hours_min', self.consecutive_on_hours_min, owner
-        )
-        self.consecutive_on_hours_max = _create_time_series(
-            'consecutive_on_hours_max', self.consecutive_on_hours_max, owner
-        )
-        self.consecutive_off_hours_min = _create_time_series(
-            'consecutive_off_hours_min', self.consecutive_off_hours_min, owner
-        )
-        self.consecutive_off_hours_max = _create_time_series(
-            'consecutive_off_hours_max', self.consecutive_off_hours_max, owner
-        )
-
-    @property
-    def use_off(self) -> bool:
-        """Determines wether the OFF Variable is needed or not"""
-        return self.use_consecutive_off_hours
-
-    @property
-    def use_consecutive_on_hours(self) -> bool:
-        """Determines wether a Variable for consecutive off hours is needed or not"""
-        return any(param is not None for param in [self.consecutive_on_hours_min, self.consecutive_on_hours_max])
-
-    @property
-    def use_consecutive_off_hours(self) -> bool:
-        """Determines wether a Variable for consecutive off hours is needed or not"""
-        return any(param is not None for param in [self.consecutive_off_hours_min, self.consecutive_off_hours_max])
-
-    @property
-    def use_switch_on(self) -> bool:
-        """Determines wether a Variable for SWITCH-ON is needed or not"""
-        return (
-            any(
-                param not in (None, {})
-                for param in [
-                    self.effects_per_switch_on,
-                    self.switch_on_total_max,
-                    self.on_hours_total_min,
-                    self.on_hours_total_max,
-                ]
-            )
-            or self.force_switch_on
-        )