Skip to content

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 

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 
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 
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 
calculate_hours_per_timestep(timesteps_extra: DatetimeIndex) -> xr.DataArray

Calculate duration of each timestep as a 1D DataArray.

to_dataset 
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 
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 
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 
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 
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 
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 
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 
connect_and_transform()

Transform data for all elements using the new simplified approach.

add_elements 
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 
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 
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:

>>> 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 
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 
stop_network_app()

Stop the network visualization server.

sel 
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 
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 
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 
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 
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 
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.