flixopt.core

This module contains the core functionality of the flixopt framework. It provides Datatypes, logging functionality, and some functions to transform data structures.

Attributes

Scalar module-attribute

Scalar = Union[int, float]

A type representing a single number, either integer or float.

NumericData module-attribute

NumericData = Union[int, float, integer, floating, ndarray, Series, DataFrame, DataArray]

Represents any form of numeric data, from simple scalars to complex data structures.

NumericDataTS module-attribute

NumericDataTS = Union[NumericData, 'TimeSeriesData']

Represents either standard numeric data or TimeSeriesData.

Classes

PlausibilityError

Bases: Exception

Error for a failing Plausibility check.

ConversionError

Bases: Exception

Base exception for data conversion errors.

DataConverter

Converts various data types into xarray.DataArray with a timesteps index.

Supports: scalars, arrays, Series, DataFrames, and DataArrays.

Functions

as_dataarray staticmethod

as_dataarray(data: NumericData, timesteps: DatetimeIndex) -> xr.DataArray

Convert data to xarray.DataArray with specified timesteps index.

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

TimeSeries

TimeSeries(data: DataArray, name: str, aggregation_weight: Optional[float] = None, aggregation_group: Optional[str] = None, needs_extra_timestep: bool = False)

A class representing time series data with active and stored states.

TimeSeries provides a way to store time-indexed data and work with temporal subsets. It supports arithmetic operations, aggregation, and JSON serialization.

Attributes:

Name	Type	Description
name	str	The name of the time series
aggregation_weight	Optional[float]	Weight used for aggregation
aggregation_group	Optional[str]	Group name for shared aggregation weighting
needs_extra_timestep	bool	Whether this series needs an extra timestep

Initialize a TimeSeries with a DataArray.

Parameters:

Name	Type	Description	Default
data	DataArray	The DataArray containing time series data	required
name	str	The name of the TimeSeries	required
aggregation_weight	Optional[float]	The weight in aggregation calculations	None
aggregation_group	Optional[str]	Group this TimeSeries belongs to for weight sharing	None
needs_extra_timestep	bool	Whether this series requires an extra timestep	False

Raises:

Type	Description
ValueError	If data doesn't have a 'time' index or has more than 1 dimension

Attributes

stats property

stats: str

Return a statistical summary of the active data.

Returns:

Type	Description
str	String representation of data statistics

all_equal property

all_equal: bool

Check if all values in the series are equal.

active_timesteps property writable

active_timesteps: DatetimeIndex

Get the current active timesteps.

active_data property

active_data: DataArray

Get a view of stored_data based on active_timesteps.

stored_data property writable

stored_data: DataArray

Get a copy of the full stored data.

Functions

from_datasource classmethod

from_datasource(data: NumericData, name: str, timesteps: DatetimeIndex, aggregation_weight: Optional[float] = None, aggregation_group: Optional[str] = None, needs_extra_timestep: bool = False) -> TimeSeries

Initialize the TimeSeries from multiple data sources.

Parameters:

Name	Type	Description	Default
data	NumericData	The time series data	required
name	str	The name of the TimeSeries	required
timesteps	DatetimeIndex	The timesteps of the TimeSeries	required
aggregation_weight	Optional[float]	The weight in aggregation calculations	None
aggregation_group	Optional[str]	Group this TimeSeries belongs to for aggregation weight sharing	None
needs_extra_timestep	bool	Whether this series requires an extra timestep	False

Returns:

Type	Description
TimeSeries	A new TimeSeries instance

from_json classmethod

from_json(data: Optional[Dict[str, Any]] = None, path: Optional[str] = None) -> TimeSeries

Load a TimeSeries from a dictionary or json file.

Parameters:

Name	Type	Description	Default
data	Optional[Dict[str, Any]]	Dictionary containing TimeSeries data	None
path	Optional[str]	Path to a JSON file containing TimeSeries data	None

Returns:

Type	Description
TimeSeries	A new TimeSeries instance

Raises:

Type	Description
ValueError	If both path and data are provided or neither is provided

reset

reset()

Reset active timesteps to the full set of stored timesteps.

restore_data

restore_data()

Restore stored_data from the backup and reset active timesteps.

to_json

to_json(path: Optional[Path] = None) -> Dict[str, Any]

Save the TimeSeries to a dictionary or JSON file.

Parameters:

Name	Type	Description	Default
path	Optional[Path]	Optional path to save JSON file	None

Returns:

Type	Description
Dict[str, Any]	Dictionary representation of the TimeSeries

TimeSeriesCollection

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

Collection of TimeSeries objects with shared timestep management.

TimeSeriesCollection handles multiple TimeSeries objects with synchronized timesteps, provides operations on collections, and manages extra timesteps.

Parameters:

Name	Type	Description	Default
timesteps	DatetimeIndex	The timesteps of the Collection.	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[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

Attributes

non_constants property

non_constants: List[TimeSeries]

Get time series with varying values.

constants property

constants: List[TimeSeries]

Get time series with constant values.

timesteps property

timesteps: DatetimeIndex

Get the active timesteps.

timesteps_extra property

timesteps_extra: DatetimeIndex

Get the active timesteps with extra step.

hours_per_timestep property

hours_per_timestep: DataArray

Get the duration of each active timestep.

hours_of_last_timestep property

hours_of_last_timestep: float

Get the duration of the last timestep.

Functions

with_uniform_timesteps classmethod

with_uniform_timesteps(start_time: Timestamp, periods: int, freq: str, hours_per_step: Optional[float] = None) -> TimeSeriesCollection

Create a collection with uniform timesteps.

create_time_series

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

Creates a TimeSeries from the given data and adds it to the collection.

Parameters:

Name	Type	Description	Default
data	Union[NumericData, TimeSeriesData]	The data to create the TimeSeries from.	required
name	str	The name of the TimeSeries.	required
needs_extra_timestep	bool	Whether to create an additional timestep at the end of the timesteps.	False

Returns:

Type	Description
TimeSeries	The created TimeSeries.

calculate_aggregation_weights

calculate_aggregation_weights() -> Dict[str, float]

Calculate and return aggregation weights for all time series.

activate_timesteps

activate_timesteps(active_timesteps: Optional[DatetimeIndex] = None)

Update active timesteps for the collection and all time series. If no arguments are provided, the active timesteps are reset.

Parameters:

Name	Type	Description	Default
active_timesteps	Optional[DatetimeIndex]	The active timesteps of the model. If None, the all timesteps of the TimeSeriesCollection are taken.	None

reset

reset()

Reset active timesteps to defaults for all time series.

restore_data

restore_data()

Restore original data for all time series.

add_time_series

add_time_series(time_series: TimeSeries)

Add an existing TimeSeries to the collection.

insert_new_data

insert_new_data(data: DataFrame, include_extra_timestep: bool = False)

Update time series with new data from a DataFrame.

Parameters:

Name	Type	Description	Default
data	DataFrame	DataFrame containing new data with timestamps as index	required
include_extra_timestep	bool	Whether the provided data already includes the extra timestep, by default False	False

to_dataframe

to_dataframe(filtered: Literal['all', 'constant', 'non_constant'] = 'non_constant', include_extra_timestep: bool = True) -> pd.DataFrame

Convert collection to DataFrame with optional filtering and timestep control.

Parameters:

Name	Type	Description	Default
filtered	Literal['all', 'constant', 'non_constant']	Filter time series by variability, by default 'non_constant'	'non_constant'
include_extra_timestep	bool	Whether to include the extra timestep in the result, by default True	True

Returns:

Type	Description
DataFrame	DataFrame representation of the collection

to_dataset

to_dataset(include_constants: bool = True) -> xr.Dataset

Combine all time series into a single Dataset with all timesteps.

Parameters:

Name	Type	Description	Default
include_constants	bool	Whether to include time series with constant values, by default True	True

Returns:

Type	Description
Dataset	Dataset containing all selected time series with all timesteps

calculate_hours_per_timestep staticmethod

calculate_hours_per_timestep(timesteps_extra: DatetimeIndex) -> xr.DataArray

Calculate duration of each timestep.

Functions

get_numeric_stats

get_numeric_stats(data: DataArray, decimals: int = 2, padd: int = 10) -> str

Calculates the mean, median, min, max, and standard deviation of a numeric DataArray.