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 = int | float

A single number, either integer or float.

PeriodicDataUser module-attribute

PeriodicDataUser = int | float | integer | floating | ndarray | Series | DataFrame | DataArray

User data which has no time dimension. Internally converted to a Scalar or an xr.DataArray without a time dimension.

PeriodicData module-attribute

PeriodicData = DataArray

Internally used datatypes for periodic data.

FlowSystemDimensions module-attribute

FlowSystemDimensions = Literal['time', 'period', 'scenario']

Possible dimensions of a FlowSystem.

TemporalDataUser module-attribute

TemporalDataUser = int | float | integer | floating | ndarray | Series | DataFrame | DataArray | TimeSeriesData

User data which might have a time dimension. Internally converted to an xr.DataArray with time dimension.

TemporalData module-attribute

TemporalData = DataArray | TimeSeriesData

Internally used datatypes for temporal data (data with a time dimension).

Classes

PlausibilityError

Bases: Exception

Error for a failing Plausibility check.

ConversionError

Bases: Exception

Base exception for data conversion errors.

TimeSeriesData

TimeSeriesData(*args: Any, aggregation_group: str | None = None, aggregation_weight: float | None = None, agg_group: str | None = None, agg_weight: float | None = None, **kwargs: Any)

Bases: DataArray

Minimal TimeSeriesData that inherits from xr.DataArray with aggregation metadata.

Parameters:

Name	Type	Description	Default
*args	Any	Arguments passed to DataArray	()
aggregation_group	str | None	Aggregation group name	None
aggregation_weight	float | None	Aggregation weight (0-1)	None
agg_group	str | None	Deprecated, use aggregation_group instead	None
agg_weight	float | None	Deprecated, use aggregation_weight instead	None
**kwargs	Any	Additional arguments passed to DataArray	{}

Functions

fit_to_coords

fit_to_coords(coords: dict[str, Index], name: str | None = None) -> TimeSeriesData

Fit the data to the given coordinates. Returns a new TimeSeriesData object if the current coords are different.

from_dataarray classmethod

from_dataarray(da: DataArray, aggregation_group: str | None = None, aggregation_weight: float | None = None)

Create TimeSeriesData from DataArray, extracting metadata from attrs.

is_timeseries_data classmethod

is_timeseries_data(obj) -> bool

Check if an object is TimeSeriesData.

DataConverter

Converts various data types into xarray.DataArray with specified target coordinates.

This converter handles intelligent dimension matching and broadcasting to ensure the output DataArray always conforms to the specified coordinate structure.

Supported input types: - Scalars: int, float, np.number (broadcast to all target dimensions) - 1D data: np.ndarray, pd.Series, single-column DataFrame (matched by length/index) - Multi-dimensional arrays: np.ndarray, DataFrame (matched by shape) - xr.DataArray: validated and potentially broadcast to target dimensions

The converter uses smart matching strategies: - Series: matched by exact index comparison - 1D arrays: matched by length to target coordinates - Multi-dimensional arrays: matched by shape permutation analysis - DataArrays: validated for compatibility and broadcast as needed

Functions

to_dataarray classmethod

to_dataarray(data: int | float | bool | integer | floating | bool_ | ndarray | Series | DataFrame | DataArray, coords: dict[str, Index] | None = None) -> xr.DataArray

Convert various data types to xarray.DataArray with specified target coordinates.

This is the main conversion method that intelligently handles different input types and ensures the result conforms to the specified coordinate structure through smart dimension matching and broadcasting.

Parameters:

Name	Type	Description	Default
data	int | float | bool | integer | floating | bool_ | ndarray | Series | DataFrame | DataArray	Input data to convert. Supported types: - Scalars: int, float, bool, np.integer, np.floating, np.bool_ - Arrays: np.ndarray (1D and multi-dimensional) - Pandas: pd.Series, pd.DataFrame - xarray: xr.DataArray	required
coords	dict[str, Index] | None	Target coordinate specification as {dimension_name: coordinate_index}. All coordinate indices must be pandas.Index objects.	None

Returns:

Type	Description
DataArray	DataArray conforming to the target coordinate specification,
DataArray	with input data appropriately matched and broadcast

Raises:

Type	Description
ConversionError	If data type is unsupported, conversion fails, or broadcasting to target coordinates is impossible

Examples:

Scalar broadcasting

>>> coords = {'x': pd.Index([1, 2, 3]), 'y': pd.Index(['a', 'b'])}
>>> converter.to_dataarray(42, coords)
# Returns: DataArray with shape (3, 2), all values = 42

Series index matching

>>> series = pd.Series([10, 20, 30], index=[1, 2, 3])
>>> converter.to_dataarray(series, coords)
# Returns: DataArray matched to 'x' dimension, broadcast to 'y'

Array shape matching

>>> array = np.array([[1, 2], [3, 4], [5, 6]])  # Shape (3, 2)
>>> converter.to_dataarray(array, coords)
# Returns: DataArray with dimensions ('x', 'y') based on shape

Functions

get_dataarray_stats

get_dataarray_stats(arr: DataArray) -> dict

Generate statistical summary of a DataArray.

drop_constant_arrays

drop_constant_arrays(ds: Dataset, dim: str = 'time', drop_arrays_without_dim: bool = True) -> xr.Dataset

Drop variables with constant values along a dimension.

Parameters:

Name	Type	Description	Default
ds	Dataset	Input dataset to filter.	required
dim	str	Dimension along which to check for constant values.	'time'
drop_arrays_without_dim	bool	If True, also drop variables that don't have the specified dimension.	True

Returns:

Type	Description
Dataset	Dataset with constant variables removed.