flixopt.flow_system ¶

This module contains the FlowSystem class, which is used to collect instances of many other classes by the end User.

Attributes¶

Classes¶

FlowSystem ¶

Python

FlowSystem(timesteps: DatetimeIndex, periods: Index | None = None, scenarios: Index | None = None, hours_of_last_timestep: float | None = None, hours_of_previous_timesteps: int | float | ndarray | None = None, weights: PeriodicDataUser | None = None, scenario_independent_sizes: bool | list[str] = True, scenario_independent_flow_rates: bool | list[str] = False)

Bases: Interface

A FlowSystem organizes the high level Elements (Components, Buses & Effects).

This is the main container class that users work with to build and manage their System.

Parameters:

Name	Type	Description	Default
`timesteps`	`DatetimeIndex`	The timesteps of the model.	required
`periods`	`Index \| None`	The periods of the model.	`None`
`scenarios`	`Index \| None`	The scenarios of the model.	`None`
`hours_of_last_timestep`	`float \| None`	The duration of the last time step. Uses the last time interval if not specified	`None`
`hours_of_previous_timesteps`	`int \| float \| ndarray \| None`	The duration of previous timesteps. 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!	`None`
`weights`	`PeriodicDataUser \| None`	The weights of each period and scenario. If None, all scenarios have the same weight (normalized to 1). Its recommended to normalize the weights to sum up to 1.	`None`
`scenario_independent_sizes`	`bool \| list[str]`	Controls whether investment sizes are equalized across scenarios. - True: All sizes are shared/equalized across scenarios - False: All sizes are optimized separately per scenario - list[str]: Only specified components (by label_full) are equalized across scenarios	`True`
`scenario_independent_flow_rates`	`bool \| list[str]`	Controls whether flow rates are equalized across scenarios. - True: All flow rates are shared/equalized across scenarios - False: All flow rates are optimized separately per scenario - list[str]: Only specified flows (by label_full) are equalized across scenarios	`False`

Notes

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.

Attributes¶

scenario_independent_sizes `property` `writable` ¶

Python

scenario_independent_sizes: bool | list[str]

Controls whether investment sizes are equalized across scenarios.

Returns:

Type	Description
`bool \| list[str]`	bool or list[str]: Configuration for scenario-independent sizing

scenario_independent_flow_rates `property` `writable` ¶

Python

scenario_independent_flow_rates: bool | list[str]

Controls whether flow rates are equalized across scenarios.

Returns:

Type	Description
`bool \| list[str]`	bool or list[str]: Configuration for scenario-independent flow rates

Functions¶

calculate_hours_per_timestep `staticmethod` ¶

Python

calculate_hours_per_timestep(timesteps_extra: DatetimeIndex) -> xr.DataArray

Calculate duration of each timestep as a 1D DataArray.

to_dataset ¶

Python

to_dataset() -> xr.Dataset

Convert the FlowSystem to an xarray Dataset. Ensures FlowSystem is connected before serialization.

Returns:

Type	Description
`Dataset`	xr.Dataset: Dataset containing all DataArrays with structure in attributes

from_dataset `classmethod` ¶

Python

from_dataset(ds: Dataset) -> FlowSystem

Create a FlowSystem from an xarray Dataset. Handles FlowSystem-specific reconstruction logic.

Parameters:

Name	Type	Description	Default
`ds`	`Dataset`	Dataset containing the FlowSystem data	required

Returns:

Type	Description
`FlowSystem`	FlowSystem instance

to_netcdf ¶

Python

to_netcdf(path: str | Path, compression: int = 0)

Save the FlowSystem to a NetCDF file. Ensures FlowSystem is connected before saving.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	The path to the netCDF file.	required
`compression`	`int`	The compression level to use when saving the file.	`0`

get_structure ¶

Python

get_structure(clean: bool = False, stats: bool = False) -> dict

Get FlowSystem structure. Ensures FlowSystem is connected before getting structure.

Parameters:

Name	Type	Description	Default
`clean`	`bool`	If True, remove None and empty dicts and lists.	`False`
`stats`	`bool`	If True, replace DataArray references with statistics	`False`

to_json ¶

Python

to_json(path: str | Path)

Save the flow system to a JSON file. Ensures FlowSystem is connected before saving.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	The path to the JSON file.	required

fit_to_model_coords ¶

Python

fit_to_model_coords(name: str, data: TemporalDataUser | PeriodicDataUser | None, dims: Collection[FlowSystemDimensions] | None = None) -> TemporalData | PeriodicData | None

Fit data to model coordinate system (currently time, but extensible).

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the data	required
`data`	`TemporalDataUser \| PeriodicDataUser \| None`	Data to fit to model coordinates	required
`dims`	`Collection[FlowSystemDimensions] \| None`	Collection of dimension names to use for fitting. If None, all dimensions are used.	`None`

Returns:

Type	Description
`TemporalData \| PeriodicData \| None`	xr.DataArray aligned to model coordinate system. If data is None, returns None.

fit_effects_to_model_coords ¶

Python

fit_effects_to_model_coords(label_prefix: str | None, effect_values: TemporalEffectsUser | PeriodicEffectsUser | None, label_suffix: str | None = None, dims: Collection[FlowSystemDimensions] | None = None, delimiter: str = '|') -> TemporalEffects | PeriodicEffects | None

Transform EffectValues from the user to Internal Datatypes aligned with model coordinates.

connect_and_transform ¶

Python

connect_and_transform()

Transform data for all elements using the new simplified approach.

add_elements ¶

Python

add_elements(*elements: Element) -> None

Add Components(Storages, Boilers, Heatpumps, ...), Buses or Effects to the FlowSystem

Parameters:

Name	Type	Description	Default
`*elements`	`Element`	childs of Element like Boiler, HeatPump, Bus,... modeling Elements	`()`

create_model ¶

Python

create_model(normalize_weights: bool = True) -> FlowSystemModel

Create a linopy model from the FlowSystem.

Parameters:

Name	Type	Description	Default
`normalize_weights`	`bool`	Whether to automatically normalize the weights (periods and scenarios) to sum up to 1 when solving.	`True`

plot_network ¶

Python

plot_network(path: bool | str | Path = 'flow_system.html', controls: bool | list[Literal['nodes', 'edges', 'layout', 'interaction', 'manipulation', 'physics', 'selection', 'renderer']] = True, show: bool = False) -> pyvis.network.Network | None

Visualizes the network structure of a FlowSystem using PyVis, saving it as an interactive HTML file.

Parameters:

Name	Type	Description	Default
`path`	`bool \| str \| Path`	Path to save the HTML visualization. - `False`: Visualization is created but not saved. - `str` or `Path`: Specifies file path (default: 'flow_system.html').	`'flow_system.html'`
`controls`	`bool \| list[Literal['nodes', 'edges', 'layout', 'interaction', 'manipulation', 'physics', 'selection', 'renderer']]`	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'.	`True`
`show`	`bool`	Whether to open the visualization in the web browser.	`False`

Returns: - 'pyvis.network.Network' | None: The Network instance representing the visualization, or None if pyvis is not installed.

Examples:

Python Console Session

>>> flow_system.plot_network()
>>> flow_system.plot_network(show=False)
>>> flow_system.plot_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.

start_network_app ¶

Python

start_network_app()

Visualizes the network structure of a FlowSystem using Dash, Cytoscape, and networkx. Requires optional dependencies: dash, dash-cytoscape, dash-daq, networkx, flask, werkzeug.

stop_network_app ¶

Python

stop_network_app()

Stop the network visualization server.

sel ¶

Python

sel(time: str | slice | list[str] | Timestamp | DatetimeIndex | None = None, period: int | slice | list[int] | Index | None = None, scenario: str | slice | list[str] | Index | None = None) -> FlowSystem

Select a subset of the flowsystem by the time coordinate.

Parameters:

Name	Type	Description	Default
`time`	`str \| slice \| list[str] \| Timestamp \| DatetimeIndex \| None`	Time selection (e.g., slice('2023-01-01', '2023-12-31'), '2023-06-15', or list of times)	`None`
`period`	`int \| slice \| list[int] \| Index \| None`	Period selection (e.g., slice(2023, 2024), or list of periods)	`None`
`scenario`	`str \| slice \| list[str] \| Index \| None`	Scenario selection (e.g., slice('scenario1', 'scenario2'), or list of scenarios)	`None`

Returns:

Name	Type	Description
`FlowSystem`	`FlowSystem`	New FlowSystem with selected data

isel ¶

Python

isel(time: int | slice | list[int] | None = None, period: int | slice | list[int] | None = None, scenario: int | slice | list[int] | None = None) -> FlowSystem

Select a subset of the flowsystem by integer indices.

Parameters:

Name	Type	Description	Default
`time`	`int \| slice \| list[int] \| None`	Time selection by integer index (e.g., slice(0, 100), 50, or [0, 5, 10])	`None`
`period`	`int \| slice \| list[int] \| None`	Period selection by integer index (e.g., slice(0, 100), 50, or [0, 5, 10])	`None`
`scenario`	`int \| slice \| list[int] \| None`	Scenario selection by integer index (e.g., slice(0, 3), 50, or [0, 5, 10])	`None`

Returns:

Name	Type	Description
`FlowSystem`	`FlowSystem`	New FlowSystem with selected data

resample ¶

Python

resample(time: str, method: Literal['mean', 'sum', 'max', 'min', 'first', 'last', 'std', 'var', 'median', 'count'] = 'mean', **kwargs: Any) -> FlowSystem

Create a resampled FlowSystem by resampling data along the time dimension (like xr.Dataset.resample()). Only resamples data variables that have a time dimension.

Parameters:

Name	Type	Description	Default
`time`	`str`	Resampling frequency (e.g., '3h', '2D', '1M')	required
`method`	`Literal['mean', 'sum', 'max', 'min', 'first', 'last', 'std', 'var', 'median', 'count']`	Resampling method. Recommended: 'mean', 'first', 'last', 'max', 'min'	`'mean'`
`**kwargs`	`Any`	Additional arguments passed to xarray.resample()	`{}`

Returns:

Name	Type	Description
`FlowSystem`	`FlowSystem`	New FlowSystem with resampled data

transform_data ¶

Python

transform_data(flow_system: FlowSystem, name_prefix: str = '') -> None

Transform the data of the interface to match the FlowSystem's dimensions.

Parameters:

Name	Type	Description	Default
`flow_system`	`FlowSystem`	The FlowSystem containing timing and dimensional information	required
`name_prefix`	`str`	The prefix to use for the names of the variables. Defaults to '', which results in no prefix.	`''`

Raises:

Type	Description
`NotImplementedError`	Must be implemented by subclasses

from_netcdf `classmethod` ¶

Python

from_netcdf(path: str | Path) -> Interface

Load an instance from a NetCDF file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to the NetCDF file	required

Returns:

Type	Description
`Interface`	Interface instance

Raises:

Type	Description
`IOError`	If file cannot be read
`ValueError`	If file format is invalid

copy ¶

Python

copy() -> Interface

Create a copy of the Interface object.

Uses the existing serialization infrastructure to ensure proper copying of all DataArrays and nested objects.

Returns:

Type	Description
`Interface`	A new instance of the same class with copied data.

flixopt.flow_system ¶

Attributes¶

Classes¶

FlowSystem ¶

Attributes¶

scenario_independent_sizes property writable ¶

scenario_independent_flow_rates property writable ¶

Functions¶

calculate_hours_per_timestep staticmethod ¶

to_dataset ¶

from_dataset classmethod ¶

to_netcdf ¶

get_structure ¶

to_json ¶

fit_to_model_coords ¶

fit_effects_to_model_coords ¶

connect_and_transform ¶

add_elements ¶

create_model ¶

plot_network ¶

start_network_app ¶

stop_network_app ¶

sel ¶

isel ¶

resample ¶

transform_data ¶

from_netcdf classmethod ¶

copy ¶

scenario_independent_sizes `property` `writable` ¶

scenario_independent_flow_rates `property` `writable` ¶

calculate_hours_per_timestep `staticmethod` ¶

from_dataset `classmethod` ¶

from_netcdf `classmethod` ¶