Skip to content

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

FlowSystemDimensions module-attribute

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

Possible dimensions of a FlowSystem.

Classes

PlausibilityError

Bases: Exception

Error for a failing Plausibility check.

ConversionError

Bases: Exception

Base exception for data conversion errors.

TimeSeriesData

Python
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
Python
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
Python
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
Python
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
Python
to_dataarray(data: NumericOrBool, 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 NumericOrBool

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
Python Console Session
>>> 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
Python Console Session
>>> 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
Python Console Session
>>> 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

Python
get_dataarray_stats(arr: DataArray) -> dict

Generate statistical summary of a DataArray.

drop_constant_arrays

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