flixopt.structure

This module contains the core structure of the flixopt framework. These classes are not directly used by the end user, but are used by other modules.

Attributes

Classes

SystemModel

SystemModel(flow_system: FlowSystem)

Bases: Model

The SystemModel is the linopy Model that is used to create the mathematical model of the flow_system. It is used to create and store the variables and constraints for the flow_system.

Parameters:

Name	Type	Description	Default
flow_system	FlowSystem	The flow_system that is used to create the model.	required

Functions

Interface

This class is used to collect arguments about a Model. Its the base class for all Elements and Models in flixopt.

Functions

transform_data

transform_data(flow_system: FlowSystem)

Transforms the data of the interface to match the FlowSystem's dimensions

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

Element

Element(label: str, meta_data: Dict = None)

Bases: Interface

This class is the basic Element of flixopt. Every Element has a label

Parameters:

Name	Type	Description	Default
label	str	The label of the element	required
meta_data	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

transform_data

transform_data(flow_system: FlowSystem)

Transforms the data of the interface to match the FlowSystem's dimensions

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

Model

Model(model: SystemModel, label_of_element: str, label: Optional[str] = None, label_full: Optional[str] = None)

Stores Variables and Constraints.

Parameters:

Name	Type	Description	Default
model	SystemModel	The SystemModel that is used to create the model.	required
label_of_element	str	The label of the parent (Element). Used to construct the full label of the model.	required
label	Optional[str]	The label of the model. Used to construct the full label of the model.	None
label_full	Optional[str]	The full label of the model. Can overwrite the full label constructed from the other labels.	None

Attributes

label_full property

label_full: str

Used to construct the names of variables and constraints

Functions

add

add(item: Union[Variable, Constraint, Model], short_name: Optional[str] = None) -> Union[linopy.Variable, linopy.Constraint, Model]

Add a variable, constraint or sub-model to the model

Parameters:

Name	Type	Description	Default
item	Union[Variable, Constraint, Model]	The variable, constraint or sub-model to add to the model	required
short_name	Optional[str]	The short name of the variable, constraint or sub-model. If not provided, the full name is used.	None

ElementModel

ElementModel(model: SystemModel, element: Element)

Bases: Model

Stores the mathematical Variables and Constraints for Elements

Parameters:

Name	Type	Description	Default
model	SystemModel	The SystemModel that is used to create the model.	required
element	Element	The element this model is created for.	required

Attributes

label_full property

label_full: str

Used to construct the names of variables and constraints

Functions

add

add(item: Union[Variable, Constraint, Model], short_name: Optional[str] = None) -> Union[linopy.Variable, linopy.Constraint, Model]

Add a variable, constraint or sub-model to the model

Parameters:

Name	Type	Description	Default
item	Union[Variable, Constraint, Model]	The variable, constraint or sub-model to add to the model	required
short_name	Optional[str]	The short name of the variable, constraint or sub-model. If not provided, the full name is used.	None

Functions

register_class_for_io

register_class_for_io(cls)

Register a class for serialization/deserialization.

copy_and_convert_datatypes

copy_and_convert_datatypes(data: Any, use_numpy: bool = True, use_element_label: bool = False) -> Any

Converts values in a nested data structure into JSON-compatible types while preserving or transforming numpy arrays and custom Element objects based on the specified options.

The function handles various data types and transforms them into a consistent, readable format: - Primitive types (int, float, str, bool, None) are returned as-is. - Numpy scalars are converted to their corresponding Python scalar types. - Collections (list, tuple, set, dict) are recursively processed to ensure all elements are compatible. - Numpy arrays are preserved or converted to lists, depending on use_numpy. - Custom Element objects can be represented either by their label or their initialization parameters as a dictionary. - Timestamps (datetime) are converted to ISO 8601 strings.

Parameters:

Name	Type	Description	Default
data	Any	The input data to process, which may be deeply nested and contain a mix of types.	required
use_numpy	bool	If True, numeric numpy arrays (np.ndarray) are preserved as-is. If False, they are converted to lists. Default is True.	True
use_element_label	bool	If True, Element objects are represented by their label. If False, they are converted into a dictionary based on their initialization parameters. Default is False.	False

Returns:

Type	Description
Any	A transformed version of the input data, containing only JSON-compatible types:
Any	int, float, str, bool, None
Any	list, dict
Any	np.ndarray (if use_numpy=True. This is NOT JSON-compatible)

Raises:

Type	Description
TypeError	If the data cannot be converted to the specified types.

Examples:

>>> copy_and_convert_datatypes({'a': np.array([1, 2, 3]), 'b': Element(label='example')})
{'a': array([1, 2, 3]), 'b': {'class': 'Element', 'label': 'example'}}

>>> copy_and_convert_datatypes({'a': np.array([1, 2, 3]), 'b': Element(label='example')}, use_numpy=False)
{'a': [1, 2, 3], 'b': {'class': 'Element', 'label': 'example'}}

Notes

• The function gracefully handles unexpected types by issuing a warning and returning a deep copy of the data.
• Empty collections (lists, dictionaries) and default parameter values in Element objects are omitted from the output.
• Numpy arrays with non-numeric data types are automatically converted to lists.

get_compact_representation

get_compact_representation(data: Any, array_threshold: int = 50, decimals: int = 2) -> Dict

Generate a compact json serializable representation of deeply nested data. Numpy arrays are statistically described if they exceed a threshold and converted to lists.

Parameters:

Name	Type	Description	Default
data	Any	The data to format and represent.	required
array_threshold	int	Maximum length of NumPy arrays to display. Longer arrays are statistically described.	50
decimals	int	Number of decimal places in which to describe the arrays.	2

Returns:

Name	Type	Description
Dict	Dict	A dictionary representation of the data

get_str_representation

get_str_representation(data: Any, array_threshold: int = 50, decimals: int = 2) -> str

Generate a string representation of deeply nested data using rich.print. NumPy arrays are shortened to the specified length and converted to strings.

Parameters:

Name	Type	Description	Default
data	Any	The data to format and represent.	required
array_threshold	int	Maximum length of NumPy arrays to display. Longer arrays are statistically described.	50
decimals	int	Number of decimal places in which to describe the arrays.	2

Returns:

Name	Type	Description
str	str	The formatted string representation of the data.