flixopt.commons

This module makes the commonly used classes and functions available in the flixopt framework.

Classes

AggregationParameters

AggregationParameters(hours_per_period: float, nr_of_periods: int, fix_storage_flows: bool, aggregate_data_and_fix_non_binary_vars: bool, percentage_of_period_freedom: float = 0, penalty_of_period_freedom: float = 0, time_series_for_high_peaks: List[TimeSeriesData] = None, time_series_for_low_peaks: List[TimeSeriesData] = None)

Initializes aggregation parameters for time series data

Parameters:

Name	Type	Description	Default
hours_per_period	float	Duration of each period in hours.	required
nr_of_periods	int	Number of typical periods to use in the aggregation.	required
fix_storage_flows	bool	Whether to aggregate storage flows (load/unload); if other flows are fixed, fixing storage flows is usually not required.	required
aggregate_data_and_fix_non_binary_vars	bool	Whether to aggregate all time series data, which allows to fix all time series variables (like flow_rate), or only fix binary variables. If False non time_series data is changed!! If True, the mathematical Problem is simplified even further.	required
percentage_of_period_freedom	float	Specifies the maximum percentage (0–100) of binary values within each period that can deviate as "free variables", chosen by the solver (default is 0). This allows binary variables to be 'partly equated' between aggregated periods.	0
penalty_of_period_freedom	float	The penalty associated with each "free variable"; defaults to 0. Added to Penalty	0
time_series_for_high_peaks	List[TimeSeriesData]	List of TimeSeriesData to use for explicitly selecting periods with high values.	None
time_series_for_low_peaks	List[TimeSeriesData]	List of TimeSeriesData to use for explicitly selecting periods with low values.	None

Functions

AggregatedCalculation

AggregatedCalculation(name: str, flow_system: FlowSystem, aggregation_parameters: AggregationParameters, components_to_clusterize: Optional[List[Component]] = None, active_timesteps: Optional[DatetimeIndex] = None, folder: Optional[Path] = None)

Bases: FullCalculation

class for defined way of solving a flow_system optimization

Class for Optimizing the FlowSystem including: 1. Aggregating TimeSeriesData via typical periods using tsam. 2. Equalizing variables of typical periods. Args: name: name of calculation flow_system: flow_system which should be calculated aggregation_parameters: Parameters for aggregation. See documentation of AggregationParameters class. components_to_clusterize: List of Components to perform aggregation on. If None, then all components are aggregated. This means, teh variables in the components are equalized to each other, according to the typical periods computed in the DataAggregation active_timesteps: pd.DatetimeIndex or None list with indices, which should be used for calculation. If None, then all timesteps are used. folder: folder where results should be saved. If None, then the current working directory is used.

Functions

FullCalculation

FullCalculation(name: str, flow_system: FlowSystem, active_timesteps: Optional[DatetimeIndex] = None, folder: Optional[Path] = None)

Bases: Calculation

class for defined way of solving a flow_system optimization

Parameters:

Name	Type	Description	Default
name	str	name of calculation	required
flow_system	FlowSystem	flow_system which should be calculated	required
active_timesteps	Optional[DatetimeIndex]	list with indices, which should be used for calculation. If None, then all timesteps are used.	None
folder	Optional[Path]	folder where results should be saved. If None, then the current working directory is used.	None

Functions

SegmentedCalculation

SegmentedCalculation(name: str, flow_system: FlowSystem, timesteps_per_segment: int, overlap_timesteps: int, nr_of_previous_values: int = 1, folder: Optional[Path] = None)

Bases: Calculation

Dividing and Modeling the problem in (overlapping) segments. The final values of each Segment are recognized by the following segment, effectively coupling charge_states and flow_rates between segments. Because of this intersection, both modeling and solving is done in one step

Take care: Parameters like InvestParameters, sum_of_flow_hours and other restrictions over the total time_series don't really work in this Calculation. Lower bounds to such SUMS can lead to weird results. This is NOT yet explicitly checked for...

Parameters:

Name	Type	Description	Default
name	str	name of calculation	required
flow_system	FlowSystem	flow_system which should be calculated	required
timesteps_per_segment	int	The number of time_steps per individual segment (without the overlap)	required
overlap_timesteps	int	The number of time_steps that are added to each individual model. Used for better results of storages)	required
folder	Optional[Path]	folder where results should be saved. If None, then the current working directory is used.	None

Attributes

start_values_of_segments property

start_values_of_segments: Dict[int, Dict[str, Any]]

Gives an overview of the start values of all Segments

Functions

LinearConverter

LinearConverter(label: str, inputs: List[Flow], outputs: List[Flow], on_off_parameters: OnOffParameters = None, conversion_factors: List[Dict[str, NumericDataTS]] = None, piecewise_conversion: Optional[PiecewiseConversion] = None, meta_data: Optional[Dict] = None)

Bases: Component

Converts input-Flows into output-Flows via linear conversion factors

Parameters:

Name	Type	Description	Default
label	str	The label of the Element. Used to identify it in the FlowSystem	required
inputs	List[Flow]	The input Flows	required
outputs	List[Flow]	The output Flows	required
on_off_parameters	OnOffParameters	Information about on and off states. See class OnOffParameters.	None
conversion_factors	List[Dict[str, NumericDataTS]]	linear relation between flows. Either 'conversion_factors' or 'piecewise_conversion' can be used!	None
piecewise_conversion	Optional[PiecewiseConversion]	Define a piecewise linear relation between flow rates of different flows. Either 'conversion_factors' or 'piecewise_conversion' can be used!	None
meta_data	Optional[Dict]	used to store more information about the Element. Is not used internally, but saved in the results. Only use python native types.	None

Functions

to_json

to_json(path: Union[str, Path])

Saves the element to a json file. This not meant to be reloaded and recreate the object, but rather used to document or compare the object.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	The path to the json file.	required

to_dict

to_dict() -> Dict

Convert the object to a dictionary representation.

from_dict classmethod

from_dict(data: Dict) -> Interface

Create an instance from a dictionary representation.

Parameters:

Name	Type	Description	Default
data	Dict	Dictionary containing the data for the object.	required

Sink

Sink(label: str, sink: Flow, meta_data: Optional[Dict] = None)

Bases: Component

Parameters:

Name	Type	Description	Default
label	str	The label of the Element. Used to identify it in the FlowSystem	required
meta_data	Optional[Dict]	used to store more information about the element. Is not used internally, but saved in the results	None
sink	Flow	input-flow of sink	required

Functions

to_json

to_json(path: Union[str, Path])

Saves the element to a json file. This not meant to be reloaded and recreate the object, but rather used to document or compare the object.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	The path to the json file.	required

to_dict

to_dict() -> Dict

Convert the object to a dictionary representation.

from_dict classmethod

from_dict(data: Dict) -> Interface

Create an instance from a dictionary representation.

Parameters:

Name	Type	Description	Default
data	Dict	Dictionary containing the data for the object.	required

Source

Source(label: str, source: Flow, meta_data: Optional[Dict] = None)

Bases: Component

Parameters:

Name	Type	Description	Default
label	str	The label of the Element. Used to identify it in the FlowSystem	required
source	Flow	output-flow of source	required
meta_data	Optional[Dict]	used to store more information about the Element. Is not used internally, but saved in the results. Only use python native types.	None

Functions

to_json

to_json(path: Union[str, Path])

Saves the element to a json file. This not meant to be reloaded and recreate the object, but rather used to document or compare the object.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	The path to the json file.	required

to_dict

to_dict() -> Dict

Convert the object to a dictionary representation.

from_dict classmethod

from_dict(data: Dict) -> Interface

Create an instance from a dictionary representation.

Parameters:

Name	Type	Description	Default
data	Dict	Dictionary containing the data for the object.	required

SourceAndSink

SourceAndSink(label: str, source: Flow, sink: Flow, prevent_simultaneous_sink_and_source: bool = True, meta_data: Optional[Dict] = None)

Bases: Component

class for source (output-flow) and sink (input-flow) in one commponent

Parameters:

Name	Type	Description	Default
label	str	The label of the Element. Used to identify it in the FlowSystem	required
source	Flow	output-flow of this component	required
sink	Flow	input-flow of this component	required
prevent_simultaneous_sink_and_source	bool	If True, inflow and outflow can not be active simultaniously.	True
meta_data	Optional[Dict]	used to store more information about the Element. Is not used internally, but saved in the results. Only use python native types.	None

Functions

to_json

to_json(path: Union[str, Path])

Saves the element to a json file. This not meant to be reloaded and recreate the object, but rather used to document or compare the object.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	The path to the json file.	required

to_dict

to_dict() -> Dict

Convert the object to a dictionary representation.

from_dict classmethod

from_dict(data: Dict) -> Interface

Create an instance from a dictionary representation.

Parameters:

Name	Type	Description	Default
data	Dict	Dictionary containing the data for the object.	required

Storage

Storage(label: str, charging: Flow, discharging: Flow, capacity_in_flow_hours: Union[Scalar, InvestParameters], relative_minimum_charge_state: NumericData = 0, relative_maximum_charge_state: NumericData = 1, initial_charge_state: Union[Scalar, Literal['lastValueOfSim']] = 0, minimal_final_charge_state: Optional[Scalar] = None, maximal_final_charge_state: Optional[Scalar] = None, eta_charge: NumericData = 1, eta_discharge: NumericData = 1, relative_loss_per_hour: NumericData = 0, prevent_simultaneous_charge_and_discharge: bool = True, meta_data: Optional[Dict] = None)

Bases: Component

Used to model the storage of energy or material.

Storages have one incoming and one outgoing Flow each with an efficiency. Further, storages have a size and a charge_state. Similarly to the flow-rate of a Flow, the size combined with a relative upper and lower bound limits the charge_state of the storage.

For mathematical details take a look at our online documentation

Parameters:

Name	Type	Description	Default
label	str	The label of the Element. Used to identify it in the FlowSystem	required
charging	Flow	ingoing flow.	required
discharging	Flow	outgoing flow.	required
capacity_in_flow_hours	Union[Scalar, InvestParameters]	nominal capacity/size of the storage	required
relative_minimum_charge_state	NumericData	minimum relative charge state. The default is 0.	0
relative_maximum_charge_state	NumericData	maximum relative charge state. The default is 1.	1
initial_charge_state	Union[Scalar, Literal['lastValueOfSim']]	storage charge_state at the beginning. The default is 0.	0
minimal_final_charge_state	Optional[Scalar]	minimal value of chargeState at the end of timeseries.	None
maximal_final_charge_state	Optional[Scalar]	maximal value of chargeState at the end of timeseries.	None
eta_charge	NumericData	efficiency factor of charging/loading. The default is 1.	1
eta_discharge	NumericData	efficiency factor of uncharging/unloading. The default is 1.	1
relative_loss_per_hour	NumericData	loss per chargeState-Unit per hour. The default is 0.	0
prevent_simultaneous_charge_and_discharge	bool	If True, loading and unloading at the same time is not possible. Increases the number of binary variables, but is recommended for easier evaluation. The default is True.	True
meta_data	Optional[Dict]	used to store more information about the Element. Is not used internally, but saved in the results. Only use python native types.	None

Functions

to_json

to_json(path: Union[str, Path])

Saves the element to a json file. This not meant to be reloaded and recreate the object, but rather used to document or compare the object.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	The path to the json file.	required

to_dict

to_dict() -> Dict

Convert the object to a dictionary representation.

from_dict classmethod

from_dict(data: Dict) -> Interface

Create an instance from a dictionary representation.

Parameters:

Name	Type	Description	Default
data	Dict	Dictionary containing the data for the object.	required

Transmission

Transmission(label: str, in1: Flow, out1: Flow, in2: Optional[Flow] = None, out2: Optional[Flow] = None, relative_losses: Optional[NumericDataTS] = None, absolute_losses: Optional[NumericDataTS] = None, on_off_parameters: OnOffParameters = None, prevent_simultaneous_flows_in_both_directions: bool = True, meta_data: Optional[Dict] = None)

Bases: Component

Initializes a Transmission component (Pipe, cable, ...) that models the flows between two sides with potential losses.

Parameters:

Name	Type	Description	Default
label	str	The label of the Element. Used to identify it in the FlowSystem	required
in1	Flow	The inflow at side A. Pass InvestmentParameters here.	required
out1	Flow	The outflow at side B.	required
in2	Optional[Flow]	The optional inflow at side B. If in1 got InvestParameters, the size of this Flow will be equal to in1 (with no extra effects!)	None
out2	Optional[Flow]	The optional outflow at side A.	None
relative_losses	Optional[NumericDataTS]	The relative loss between inflow and outflow, e.g., 0.02 for 2% loss.	None
absolute_losses	Optional[NumericDataTS]	The absolute loss, occur only when the Flow is on. Induces the creation of the ON-Variable	None
on_off_parameters	OnOffParameters	Parameters defining the on/off behavior of the component.	None
prevent_simultaneous_flows_in_both_directions	bool	If True, inflow and outflow are not allowed to be both non-zero at same timestep.	True
meta_data	Optional[Dict]	used to store more information about the Element. Is not used internally, but saved in the results. Only use python native types.	None

Functions

to_json

to_json(path: Union[str, Path])

Saves the element to a json file. This not meant to be reloaded and recreate the object, but rather used to document or compare the object.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	The path to the json file.	required

to_dict

to_dict() -> Dict

Convert the object to a dictionary representation.

from_dict classmethod

from_dict(data: Dict) -> Interface

Create an instance from a dictionary representation.

Parameters:

Name	Type	Description	Default
data	Dict	Dictionary containing the data for the object.	required

CONFIG

A configuration class that stores global configuration values as class attributes.

Functions

load_config classmethod

load_config(user_config_file: Optional[str] = None)

Initialize configuration using defaults or user-specified file.

to_dict classmethod

to_dict()

Convert the configuration class into a dictionary for JSON serialization. Handles dataclasses and simple types like str, int, etc.

TimeSeriesData

TimeSeriesData(data: NumericData, agg_group: Optional[str] = None, agg_weight: Optional[float] = None)

timeseries class for transmit timeseries AND special characteristics of timeseries, i.g. to define weights needed in calculation_type 'aggregated' EXAMPLE solar: you have several solar timeseries. These should not be overweighted compared to the remaining timeseries (i.g. heat load, price)! fixed_relative_profile_solar1 = TimeSeriesData(sol_array_1, type = 'solar') fixed_relative_profile_solar2 = TimeSeriesData(sol_array_2, type = 'solar') fixed_relative_profile_solar3 = TimeSeriesData(sol_array_3, type = 'solar') --> this 3 series of same type share one weight, i.e. internally assigned each weight = 1/3 (instead of standard weight = 1)

Parameters:

Name	Type	Description	Default
data	NumericData	The timeseries data, which can be a scalar, array, or numpy array.	required
agg_group	Optional[str]	The group this TimeSeriesData is a part of. agg_weight is split between members of a group. Default is None.	None
agg_weight	Optional[float]	The weight for calculation_type 'aggregated', should be between 0 and 1. Default is None.	None

Raises:

Type	Description
Exception	If both agg_group and agg_weight are set, an exception is raised.

Functions

Effect

Effect(label: str, unit: str, description: str, meta_data: Optional[Dict] = None, is_standard: bool = False, is_objective: bool = False, specific_share_to_other_effects_operation: Optional[EffectValuesUser] = None, specific_share_to_other_effects_invest: Optional[EffectValuesUser] = None, minimum_operation: Optional[Scalar] = None, maximum_operation: Optional[Scalar] = None, minimum_invest: Optional[Scalar] = None, maximum_invest: Optional[Scalar] = None, minimum_operation_per_hour: Optional[NumericDataTS] = None, maximum_operation_per_hour: Optional[NumericDataTS] = None, minimum_total: Optional[Scalar] = None, maximum_total: Optional[Scalar] = None)

Bases: Element

Effect, i.g. costs, CO2 emissions, area, ... Components, FLows, and so on can contribute to an Effect. One Effect is chosen as the Objective of the Optimization

Parameters:

Name	Type	Description	Default
label	str	The label of the Element. Used to identify it in the FlowSystem	required
unit	str	The unit of effect, i.g. €, kg_CO2, kWh_primaryEnergy	required
description	str	The long name	required
is_standard	bool	true, if Standard-Effect (for direct input of value without effect (alternatively to dict)) , else false	False
is_objective	bool	true, if optimization target	False
specific_share_to_other_effects_operation	Optional[EffectValuesUser]	{effectType: TS, ...}, i.g. 180 €/t_CO2, input as {costs: 180}, optional share to other effects (only operation)	None
specific_share_to_other_effects_invest	Optional[EffectValuesUser]	{effectType: TS, ...}, i.g. 180 €/t_CO2, input as {costs: 180}, optional share to other effects (only invest).	None
minimum_operation	Optional[Scalar]	minimal sum (only operation) of the effect.	None
maximum_operation	Optional[Scalar]	maximal sum (nur operation) of the effect.	None
minimum_operation_per_hour	Optional[NumericDataTS]	max. value per hour (only operation) of effect (=sum of all effect-shares) for each timestep!	None
maximum_operation_per_hour	Optional[NumericDataTS]	min. value per hour (only operation) of effect (=sum of all effect-shares) for each timestep!	None
minimum_invest	Optional[Scalar]	minimal sum (only invest) of the effect	None
maximum_invest	Optional[Scalar]	maximal sum (only invest) of the effect	None
minimum_total	Optional[Scalar]	min sum of effect (invest+operation).	None
maximum_total	Optional[Scalar]	max sum of effect (invest+operation).	None
meta_data	Optional[Dict]	used to store more information about the Element. Is not used internally, but saved in the results. Only use python native types.	None

Functions

infos

infos(use_numpy: bool = True, use_element_label: bool = False) -> Dict

Generate a dictionary representation of the object's constructor arguments. Excludes default values and empty dictionaries and lists. Converts data to be compatible with JSON.

Parameters:

Name	Type	Description	Default
use_numpy	bool	Whether to convert NumPy arrays to lists. Defaults to True. If True, numeric numpy arrays (np.ndarray) are preserved as-is. If False, they are converted to lists.	True
use_element_label	bool	Whether to use the element label instead of the infos of the element. Defaults to False. Note that Elements used as keys in dictionaries are always converted to their labels.	False

Returns:

Type	Description
Dict	A dictionary representation of the object's constructor arguments.

to_json

to_json(path: Union[str, Path])

Saves the element to a json file. This not meant to be reloaded and recreate the object, but rather used to document or compare the object.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	The path to the json file.	required

to_dict

to_dict() -> Dict

Convert the object to a dictionary representation.

from_dict classmethod

from_dict(data: Dict) -> Interface

Create an instance from a dictionary representation.

Parameters:

Name	Type	Description	Default
data	Dict	Dictionary containing the data for the object.	required

Bus

Bus(label: str, excess_penalty_per_flow_hour: Optional[NumericDataTS] = 100000.0, meta_data: Optional[Dict] = None)

Bases: Element

A Bus represents a nodal balance between the flow rates of its incoming and outgoing Flows.

Parameters:

Name	Type	Description	Default
label	str	The label of the Element. Used to identify it in the FlowSystem	required
excess_penalty_per_flow_hour	Optional[NumericDataTS]	excess costs / penalty costs (bus balance compensation) (none/ 0 -> no penalty). The default is 1e5. (Take care: if you use a timeseries (no scalar), timeseries is aggregated if calculation_type = aggregated!)	100000.0
meta_data	Optional[Dict]	used to store more information about the Element. Is not used internally, but saved in the results. Only use python native types.	None

Functions

infos

infos(use_numpy: bool = True, use_element_label: bool = False) -> Dict

Generate a dictionary representation of the object's constructor arguments. Excludes default values and empty dictionaries and lists. Converts data to be compatible with JSON.

Parameters:

Name	Type	Description	Default
use_numpy	bool	Whether to convert NumPy arrays to lists. Defaults to True. If True, numeric numpy arrays (np.ndarray) are preserved as-is. If False, they are converted to lists.	True
use_element_label	bool	Whether to use the element label instead of the infos of the element. Defaults to False. Note that Elements used as keys in dictionaries are always converted to their labels.	False

Returns:

Type	Description
Dict	A dictionary representation of the object's constructor arguments.

to_json

to_json(path: Union[str, Path])

Saves the element to a json file. This not meant to be reloaded and recreate the object, but rather used to document or compare the object.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	The path to the json file.	required

to_dict

to_dict() -> Dict

Convert the object to a dictionary representation.

from_dict classmethod

from_dict(data: Dict) -> Interface

Create an instance from a dictionary representation.

Parameters:

Name	Type	Description	Default
data	Dict	Dictionary containing the data for the object.	required

Flow

Flow(label: str, bus: str, size: Union[Scalar, InvestParameters] = None, fixed_relative_profile: Optional[NumericDataTS] = None, relative_minimum: NumericDataTS = 0, relative_maximum: NumericDataTS = 1, effects_per_flow_hour: Optional[EffectValuesUser] = None, on_off_parameters: Optional[OnOffParameters] = None, flow_hours_total_max: Optional[Scalar] = None, flow_hours_total_min: Optional[Scalar] = None, load_factor_min: Optional[Scalar] = None, load_factor_max: Optional[Scalar] = None, previous_flow_rate: Optional[NumericData] = None, meta_data: Optional[Dict] = None)

Bases: Element

A Flow moves energy (or material) between a Bus and a Component in a predefined direction. The flow-rate is the main optimization variable of the Flow.

Parameters:

Name	Type	Description	Default
label	str	The label of the FLow. Used to identify it in the FlowSystem. Its full_label consists of the label of the Component and the label of the Flow.	required
bus	str	blabel of the bus the flow is connected to.	required
size	Union[Scalar, InvestParameters]	size of the flow. If InvestmentParameters is used, size is optimized. If size is None, a default value is used.	None
relative_minimum	NumericDataTS	min value is relative_minimum multiplied by size	0
relative_maximum	NumericDataTS	max value is relative_maximum multiplied by size. If size = max then relative_maximum=1	1
load_factor_min	Optional[Scalar]	minimal load factor general: avg Flow per nominalVal/investSize (e.g. boiler, kW/kWh=h; solarthermal: kW/m²; def: :math:load\_factor:= sumFlowHours/ (nominal\_val \cdot \Delta t_{tot})	None
load_factor_max	Optional[Scalar]	maximal load factor (see minimal load factor)	None
effects_per_flow_hour	Optional[EffectValuesUser]	operational costs, costs per flow-"work"	None
on_off_parameters	Optional[OnOffParameters]	If present, flow can be "off", i.e. be zero (only relevant if relative_minimum > 0) Therefore a binary var "on" is used. Further, several other restrictions and effects can be modeled through this On/Off State (See OnOffParameters)	None
flow_hours_total_max	Optional[Scalar]	maximum flow-hours ("flow-work") (if size is not const, maybe load_factor_max is the better choice!)	None
flow_hours_total_min	Optional[Scalar]	minimum flow-hours ("flow-work") (if size is not predefined, maybe load_factor_min is the better choice!)	None
fixed_relative_profile	Optional[NumericDataTS]	fixed relative values for flow (if given). flow_rate(t) := fixed_relative_profile(t) * size(t) With this value, the flow_rate is no optimization-variable anymore. (relative_minimum and relative_maximum are ignored) used for fixed load or supply profiles, i.g. heat demand, wind-power, solarthermal If the load-profile is just an upper limit, use relative_maximum instead.	None
previous_flow_rate	Optional[NumericData]	previous flow rate of the component.	None
meta_data	Optional[Dict]	used to store more information about the Element. Is not used internally, but saved in the results. Only use python native types.	None

Functions

to_json

to_json(path: Union[str, Path])

Saves the element to a json file. This not meant to be reloaded and recreate the object, but rather used to document or compare the object.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	The path to the json file.	required

from_dict classmethod

from_dict(data: Dict) -> Interface

Create an instance from a dictionary representation.

Parameters:

Name	Type	Description	Default
data	Dict	Dictionary containing the data for the object.	required

FlowSystem

FlowSystem(timesteps: DatetimeIndex, hours_of_last_timestep: Optional[float] = None, hours_of_previous_timesteps: Optional[Union[int, float, ndarray]] = None)

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

Parameters:

Name	Type	Description	Default
timesteps	DatetimeIndex	The timesteps of the model.	required
hours_of_last_timestep	Optional[float]	The duration of the last time step. Uses the last time interval if not specified	None
hours_of_previous_timesteps	Optional[Union[int, float, ndarray]]	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

Functions

from_dict classmethod

from_dict(data: Dict) -> FlowSystem

Load a FlowSystem from a dictionary.

Parameters:

Name	Type	Description	Default
data	Dict	Dictionary containing the FlowSystem data.	required

from_netcdf classmethod

from_netcdf(path: Union[str, Path])

Load a FlowSystem from a netcdf file

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

to_json

to_json(path: Union[str, 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 flow_system to others.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	The path to the json file.	required

as_dict

as_dict(data_mode: Literal['data', 'name', 'stats'] = 'data') -> Dict

Convert the object to a dictionary representation.

as_dataset

as_dataset(constants_in_dataset: bool = False) -> xr.Dataset

Convert the FlowSystem to a xarray Dataset.

Parameters:

Name	Type	Description	Default
constants_in_dataset	bool	If True, constants are included as Dataset variables.	False

to_netcdf

to_netcdf(path: Union[str, Path], compression: int = 0, constants_in_dataset: bool = True)

Saves the FlowSystem to a netCDF file. Args: path: The path to the netCDF file. compression: The compression level to use when saving the file. constants_in_dataset: If True, constants are included as Dataset variables.

plot_network

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

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

Parameters:

Name	Type	Description	Default
path	Union[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	Union[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: - Optional[pyvis.network.Network]: 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.

create_time_series

create_time_series(name: str, data: Optional[Union[NumericData, TimeSeriesData, TimeSeries]], needs_extra_timestep: bool = False) -> Optional[TimeSeries]

Tries to create a TimeSeries from NumericData Data and adds it to the time_series_collection If the data already is a TimeSeries, nothing happens and the TimeSeries gets reset and returned If the data is a TimeSeriesData, it is converted to a TimeSeries, and the aggregation weights are applied. If the data is None, nothing happens.

create_effect_time_series

create_effect_time_series(label_prefix: Optional[str], effect_values: EffectValuesUser, label_suffix: Optional[str] = None) -> Optional[EffectTimeSeries]

Transform EffectValues to EffectTimeSeries. Creates a TimeSeries for each key in the nested_values dictionary, using the value as the data.

The resulting label of the TimeSeries is the label of the parent_element, followed by the label of the Effect in the nested_values and the label_suffix. If the key in the EffectValues is None, the alias 'Standard_Effect' is used

InvestParameters

InvestParameters(fixed_size: Optional[Union[int, float]] = None, minimum_size: Union[int, float] = 0, maximum_size: Optional[Union[int, float]] = None, optional: bool = True, fix_effects: Optional[EffectValuesUserScalar] = None, specific_effects: Optional[EffectValuesUserScalar] = None, piecewise_effects: Optional[PiecewiseEffects] = None, divest_effects: Optional[EffectValuesUserScalar] = None)

Bases: Interface

collects arguments for invest-stuff

Parameters:

Name	Type	Description	Default
fix_effects	Optional[EffectValuesUserScalar]	Fixed investment costs if invested. (Attention: Annualize costs to chosen period!)	None
divest_effects	Optional[EffectValuesUserScalar]	Fixed divestment costs (if not invested, e.g., demolition costs or contractual penalty).	None
fixed_size	Optional[Union[int, float]]	Determines if the investment size is fixed.	None
optional	bool	If True, investment is not forced.	True
specific_effects	Optional[EffectValuesUserScalar]	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!)	None
piecewise_effects	Optional[PiecewiseEffects]	Linear piecewise relation [invest_pieces, cost_pieces]. 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 Investsizepieces)	None
minimum_size	Union[int, float]	Min nominal value (only if: size_is_fixed = False).	0
maximum_size	Optional[Union[int, float]]	Max nominal value (only if: size_is_fixed = False).	None

Functions

infos

infos(use_numpy: bool = True, use_element_label: bool = False) -> Dict

Generate a dictionary representation of the object's constructor arguments. Excludes default values and empty dictionaries and lists. Converts data to be compatible with JSON.

Parameters:

Name	Type	Description	Default
use_numpy	bool	Whether to convert NumPy arrays to lists. Defaults to True. If True, numeric numpy arrays (np.ndarray) are preserved as-is. If False, they are converted to lists.	True
use_element_label	bool	Whether to use the element label instead of the infos of the element. Defaults to False. Note that Elements used as keys in dictionaries are always converted to their labels.	False

Returns:

Type	Description
Dict	A dictionary representation of the object's constructor arguments.

to_json

to_json(path: Union[str, Path])

Saves the element to a json file. This not meant to be reloaded and recreate the object, but rather used to document or compare the object.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	The path to the json file.	required

to_dict

to_dict() -> Dict

Convert the object to a dictionary representation.

from_dict classmethod

from_dict(data: Dict) -> Interface

Create an instance from a dictionary representation.

Parameters:

Name	Type	Description	Default
data	Dict	Dictionary containing the data for the object.	required

OnOffParameters

OnOffParameters(effects_per_switch_on: Optional[EffectValuesUser] = None, effects_per_running_hour: Optional[EffectValuesUser] = None, on_hours_total_min: Optional[int] = None, on_hours_total_max: Optional[int] = None, consecutive_on_hours_min: Optional[NumericData] = None, consecutive_on_hours_max: Optional[NumericData] = None, consecutive_off_hours_min: Optional[NumericData] = None, consecutive_off_hours_max: Optional[NumericData] = None, switch_on_total_max: Optional[int] = None, force_switch_on: bool = False)

Bases: Interface

Bundles information about the 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:

Name	Type	Description	Default
effects_per_switch_on	Optional[EffectValuesUser]	cost of one switch from off (var_on=0) to on (var_on=1), unit i.g. in Euro	None
effects_per_running_hour	Optional[EffectValuesUser]	costs for operating, i.g. in € per hour	None
on_hours_total_min	Optional[int]	min. overall sum of operating hours.	None
on_hours_total_max	Optional[int]	max. overall sum of operating hours.	None
consecutive_on_hours_min	Optional[NumericData]	min sum of operating hours in one piece (last on-time period of timeseries is not checked and can be shorter)	None
consecutive_on_hours_max	Optional[NumericData]	max sum of operating hours in one piece	None
consecutive_off_hours_min	Optional[NumericData]	min sum of non-operating hours in one piece (last off-time period of timeseries is not checked and can be shorter)	None
consecutive_off_hours_max	Optional[NumericData]	max sum of non-operating hours in one piece	None
switch_on_total_max	Optional[int]	max nr of switchOn operations	None
force_switch_on	bool	force creation of switch on variable, even if there is no switch_on_total_max	False

Attributes

use_off property

use_off: bool

Determines wether the OFF Variable is needed or not

use_consecutive_on_hours property

use_consecutive_on_hours: bool

Determines wether a Variable for consecutive off hours is needed or not

use_consecutive_off_hours property

use_consecutive_off_hours: bool

Determines wether a Variable for consecutive off hours is needed or not

use_switch_on property

use_switch_on: bool

Determines wether a Variable for SWITCH-ON is needed or not

Functions

infos

infos(use_numpy: bool = True, use_element_label: bool = False) -> Dict

Generate a dictionary representation of the object's constructor arguments. Excludes default values and empty dictionaries and lists. Converts data to be compatible with JSON.

Parameters:

Name	Type	Description	Default
use_numpy	bool	Whether to convert NumPy arrays to lists. Defaults to True. If True, numeric numpy arrays (np.ndarray) are preserved as-is. If False, they are converted to lists.	True
use_element_label	bool	Whether to use the element label instead of the infos of the element. Defaults to False. Note that Elements used as keys in dictionaries are always converted to their labels.	False

Returns:

Type	Description
Dict	A dictionary representation of the object's constructor arguments.

to_json

to_json(path: Union[str, Path])

Saves the element to a json file. This not meant to be reloaded and recreate the object, but rather used to document or compare the object.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	The path to the json file.	required

to_dict

to_dict() -> Dict

Convert the object to a dictionary representation.

from_dict classmethod

from_dict(data: Dict) -> Interface

Create an instance from a dictionary representation.

Parameters:

Name	Type	Description	Default
data	Dict	Dictionary containing the data for the object.	required

Piece

Piece(start: NumericData, end: NumericData)

Bases: Interface

Define a Piece, which is part of a Piecewise object.

Parameters:

Name	Type	Description	Default
start	NumericData	The x-values of the piece.	required
end	NumericData	The end of the piece.	required

Functions

infos

infos(use_numpy: bool = True, use_element_label: bool = False) -> Dict

Generate a dictionary representation of the object's constructor arguments. Excludes default values and empty dictionaries and lists. Converts data to be compatible with JSON.

Parameters:

Name	Type	Description	Default
use_numpy	bool	Whether to convert NumPy arrays to lists. Defaults to True. If True, numeric numpy arrays (np.ndarray) are preserved as-is. If False, they are converted to lists.	True
use_element_label	bool	Whether to use the element label instead of the infos of the element. Defaults to False. Note that Elements used as keys in dictionaries are always converted to their labels.	False

Returns:

Type	Description
Dict	A dictionary representation of the object's constructor arguments.

to_json

to_json(path: Union[str, Path])

Saves the element to a json file. This not meant to be reloaded and recreate the object, but rather used to document or compare the object.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	The path to the json file.	required

to_dict

to_dict() -> Dict

Convert the object to a dictionary representation.

from_dict classmethod

from_dict(data: Dict) -> Interface

Create an instance from a dictionary representation.

Parameters:

Name	Type	Description	Default
data	Dict	Dictionary containing the data for the object.	required

Piecewise

Piecewise(pieces: List[Piece])

Bases: Interface

Define a Piecewise, consisting of a list of Pieces.

Parameters:

Name	Type	Description	Default
pieces	List[Piece]	The pieces of the piecewise.	required

Functions

infos

infos(use_numpy: bool = True, use_element_label: bool = False) -> Dict

Generate a dictionary representation of the object's constructor arguments. Excludes default values and empty dictionaries and lists. Converts data to be compatible with JSON.

Parameters:

Name	Type	Description	Default
use_numpy	bool	Whether to convert NumPy arrays to lists. Defaults to True. If True, numeric numpy arrays (np.ndarray) are preserved as-is. If False, they are converted to lists.	True
use_element_label	bool	Whether to use the element label instead of the infos of the element. Defaults to False. Note that Elements used as keys in dictionaries are always converted to their labels.	False

Returns:

Type	Description
Dict	A dictionary representation of the object's constructor arguments.

to_json

to_json(path: Union[str, Path])

Saves the element to a json file. This not meant to be reloaded and recreate the object, but rather used to document or compare the object.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	The path to the json file.	required

to_dict

to_dict() -> Dict

Convert the object to a dictionary representation.

from_dict classmethod

from_dict(data: Dict) -> Interface

Create an instance from a dictionary representation.

Parameters:

Name	Type	Description	Default
data	Dict	Dictionary containing the data for the object.	required

PiecewiseConversion

PiecewiseConversion(piecewises: Dict[str, Piecewise])

Bases: Interface

Define a piecewise conversion between multiple Flows. --> "gaps" can be expressed by a piece not starting at the end of the prior piece: [(1,3), (4,5)] --> "points" can expressed as piece with same begin and end: [(3,3), (4,4)]

Parameters:

Name	Type	Description	Default
piecewises	Dict[str, Piecewise]	Dict of Piecewises defining the conversion factors. flow labels as keys, piecewise as values	required

Functions

infos

infos(use_numpy: bool = True, use_element_label: bool = False) -> Dict

Generate a dictionary representation of the object's constructor arguments. Excludes default values and empty dictionaries and lists. Converts data to be compatible with JSON.

Parameters:

Name	Type	Description	Default
use_numpy	bool	Whether to convert NumPy arrays to lists. Defaults to True. If True, numeric numpy arrays (np.ndarray) are preserved as-is. If False, they are converted to lists.	True
use_element_label	bool	Whether to use the element label instead of the infos of the element. Defaults to False. Note that Elements used as keys in dictionaries are always converted to their labels.	False

Returns:

Type	Description
Dict	A dictionary representation of the object's constructor arguments.

to_json

to_json(path: Union[str, Path])

Saves the element to a json file. This not meant to be reloaded and recreate the object, but rather used to document or compare the object.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	The path to the json file.	required

to_dict

to_dict() -> Dict

Convert the object to a dictionary representation.

from_dict classmethod

from_dict(data: Dict) -> Interface

Create an instance from a dictionary representation.

Parameters:

Name	Type	Description	Default
data	Dict	Dictionary containing the data for the object.	required

PiecewiseEffects

PiecewiseEffects(piecewise_origin: Piecewise, piecewise_shares: Dict[str, Piecewise])

Bases: Interface

Define piecewise effects related to a variable.

Parameters:

Name	Type	Description	Default
piecewise_origin	Piecewise	Piecewise of the related variable	required
piecewise_shares	Dict[str, Piecewise]	Piecewise defining the shares to different Effects	required

Functions

infos

infos(use_numpy: bool = True, use_element_label: bool = False) -> Dict

Generate a dictionary representation of the object's constructor arguments. Excludes default values and empty dictionaries and lists. Converts data to be compatible with JSON.

Parameters:

Name	Type	Description	Default
use_numpy	bool	Whether to convert NumPy arrays to lists. Defaults to True. If True, numeric numpy arrays (np.ndarray) are preserved as-is. If False, they are converted to lists.	True
use_element_label	bool	Whether to use the element label instead of the infos of the element. Defaults to False. Note that Elements used as keys in dictionaries are always converted to their labels.	False

Returns:

Type	Description
Dict	A dictionary representation of the object's constructor arguments.

to_json

to_json(path: Union[str, Path])

Saves the element to a json file. This not meant to be reloaded and recreate the object, but rather used to document or compare the object.

Parameters:

Name	Type	Description	Default
path	Union[str, Path]	The path to the json file.	required

to_dict

to_dict() -> Dict

Convert the object to a dictionary representation.

from_dict classmethod

from_dict(data: Dict) -> Interface

Create an instance from a dictionary representation.

Parameters:

Name	Type	Description	Default
data	Dict	Dictionary containing the data for the object.	required