flixopt.linear_converters

This Module contains high-level classes to easily model a FlowSystem.

Attributes

Classes

Boiler

Boiler(label: str, eta: TemporalDataUser, Q_fu: Flow, Q_th: Flow, on_off_parameters: OnOffParameters | None = None, meta_data: dict | None = None)

Bases: LinearConverter

A specialized LinearConverter representing a fuel-fired boiler for thermal energy generation.

Boilers convert fuel input into thermal energy with a specified efficiency factor. This is a simplified wrapper around LinearConverter with predefined conversion relationships for thermal generation applications.

Parameters:

Name	Type	Description	Default
label	str	The label of the Element. Used to identify it in the FlowSystem.	required
eta	TemporalDataUser	Thermal efficiency factor (0-1 range). Defines the ratio of thermal output to fuel input energy content.	required
Q_fu	Flow	Fuel input-flow representing fuel consumption.	required
Q_th	Flow	Thermal output-flow representing heat generation.	required
on_off_parameters	OnOffParameters | None	Parameters defining binary operation constraints and costs.	None
meta_data	dict | None	Used to store additional information. Not used internally but saved in results. Only use Python native types.	None

Examples:

Natural gas boiler:

gas_boiler = Boiler(
    label='natural_gas_boiler',
    eta=0.85,  # 85% thermal efficiency
    Q_fu=natural_gas_flow,
    Q_th=hot_water_flow,
)

Biomass boiler with seasonal efficiency variation:

biomass_boiler = Boiler(
    label='wood_chip_boiler',
    eta=seasonal_efficiency_profile,  # Time-varying efficiency
    Q_fu=biomass_flow,
    Q_th=district_heat_flow,
    on_off_parameters=OnOffParameters(
        consecutive_on_hours_min=4,  # Minimum 4-hour operation
        effects_per_switch_on={'startup_fuel': 50},  # Startup fuel penalty
    ),
)

Note

The conversion relationship is: Q_th = Q_fu × eta

Efficiency should be between 0 and 1, where 1 represents perfect conversion (100% of fuel energy converted to useful thermal output).

Functions

to_dataset

to_dataset() -> xr.Dataset

Convert the object to an xarray Dataset representation. All DataArrays become dataset variables, everything else goes to attrs.

Its recommended to only call this method on Interfaces with all numeric data stored as xr.DataArrays. Interfaces inside a FlowSystem are automatically converted this form after connecting and transforming the FlowSystem.

Returns:

Type	Description
Dataset	xr.Dataset: Dataset containing all DataArrays with basic objects only in attributes

Raises:

Type	Description
ValueError	If serialization fails due to naming conflicts or invalid data

to_netcdf

to_netcdf(path: str | Path, compression: int = 0)

Save the object to a NetCDF file.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to save the NetCDF file	required
compression	int	Compression level (0-9)	0

Raises:

Type	Description
ValueError	If serialization fails
IOError	If file cannot be written

from_dataset classmethod

from_dataset(ds: Dataset) -> Interface

Create an instance from an xarray Dataset.

Parameters:

Name	Type	Description	Default
ds	Dataset	Dataset containing the object data	required

Returns:

Type	Description
Interface	Interface instance

Raises:

Type	Description
ValueError	If dataset format is invalid or class mismatch

from_netcdf classmethod

from_netcdf(path: str | Path) -> Interface

Load an instance from a NetCDF file.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the NetCDF file	required

Returns:

Type	Description
Interface	Interface instance

Raises:

Type	Description
IOError	If file cannot be read
ValueError	If file format is invalid

get_structure

get_structure(clean: bool = False, stats: bool = False) -> dict

Get object structure as a dictionary.

Parameters:

Name	Type	Description	Default
clean	bool	If True, remove None and empty dicts and lists.	False
stats	bool	If True, replace DataArray references with statistics	False

Returns:

Type	Description
dict	Dictionary representation of the object structure

to_json

to_json(path: str | Path)

Save the object to a JSON file. This is meant for documentation and comparison, not for reloading.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the JSON file.	required

Raises:

Type	Description
IOError	If file cannot be written

copy

copy() -> Interface

Create a copy of the Interface object.

Uses the existing serialization infrastructure to ensure proper copying of all DataArrays and nested objects.

Returns:

Type	Description
Interface	A new instance of the same class with copied data.

Power2Heat

Power2Heat(label: str, eta: TemporalDataUser, P_el: Flow, Q_th: Flow, on_off_parameters: OnOffParameters | None = None, meta_data: dict | None = None)

Bases: LinearConverter

A specialized LinearConverter representing electric resistance heating or power-to-heat conversion.

Power2Heat components convert electrical energy directly into thermal energy through resistance heating elements, electrode boilers, or other direct electric heating technologies. This is a simplified wrapper around LinearConverter with predefined conversion relationships for electric heating applications.

Parameters:

Name	Type	Description	Default
label	str	The label of the Element. Used to identify it in the FlowSystem.	required
eta	TemporalDataUser	Thermal efficiency factor (0-1 range). For resistance heating this is typically close to 1.0 (nearly 100% efficiency), but may be lower for electrode boilers or systems with distribution losses.	required
P_el	Flow	Electrical input-flow representing electricity consumption.	required
Q_th	Flow	Thermal output-flow representing heat generation.	required
on_off_parameters	OnOffParameters | None	Parameters defining binary operation constraints and costs.	None
meta_data	dict | None	Used to store additional information. Not used internally but saved in results. Only use Python native types.	None

Examples:

Electric resistance heater:

electric_heater = Power2Heat(
    label='resistance_heater',
    eta=0.98,  # 98% efficiency (small losses)
    P_el=electricity_flow,
    Q_th=space_heating_flow,
)

Electrode boiler for industrial steam:

electrode_boiler = Power2Heat(
    label='electrode_steam_boiler',
    eta=0.95,  # 95% efficiency including boiler losses
    P_el=industrial_electricity,
    Q_th=process_steam_flow,
    on_off_parameters=OnOffParameters(
        consecutive_on_hours_min=1,  # Minimum 1-hour operation
        effects_per_switch_on={'startup_cost': 100},
    ),
)

Note

The conversion relationship is: Q_th = P_el × eta

Unlike heat pumps, Power2Heat systems cannot exceed 100% efficiency (eta ≤ 1.0) as they only convert electrical energy without extracting additional energy from the environment. However, they provide fast response times and precise temperature control.

Functions

to_dataset

to_dataset() -> xr.Dataset

Convert the object to an xarray Dataset representation. All DataArrays become dataset variables, everything else goes to attrs.

Its recommended to only call this method on Interfaces with all numeric data stored as xr.DataArrays. Interfaces inside a FlowSystem are automatically converted this form after connecting and transforming the FlowSystem.

Returns:

Type	Description
Dataset	xr.Dataset: Dataset containing all DataArrays with basic objects only in attributes

Raises:

Type	Description
ValueError	If serialization fails due to naming conflicts or invalid data

to_netcdf

to_netcdf(path: str | Path, compression: int = 0)

Save the object to a NetCDF file.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to save the NetCDF file	required
compression	int	Compression level (0-9)	0

Raises:

Type	Description
ValueError	If serialization fails
IOError	If file cannot be written

from_dataset classmethod

from_dataset(ds: Dataset) -> Interface

Create an instance from an xarray Dataset.

Parameters:

Name	Type	Description	Default
ds	Dataset	Dataset containing the object data	required

Returns:

Type	Description
Interface	Interface instance

Raises:

Type	Description
ValueError	If dataset format is invalid or class mismatch

from_netcdf classmethod

from_netcdf(path: str | Path) -> Interface

Load an instance from a NetCDF file.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the NetCDF file	required

Returns:

Type	Description
Interface	Interface instance

Raises:

Type	Description
IOError	If file cannot be read
ValueError	If file format is invalid

get_structure

get_structure(clean: bool = False, stats: bool = False) -> dict

Get object structure as a dictionary.

Parameters:

Name	Type	Description	Default
clean	bool	If True, remove None and empty dicts and lists.	False
stats	bool	If True, replace DataArray references with statistics	False

Returns:

Type	Description
dict	Dictionary representation of the object structure

to_json

to_json(path: str | Path)

Save the object to a JSON file. This is meant for documentation and comparison, not for reloading.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the JSON file.	required

Raises:

Type	Description
IOError	If file cannot be written

copy

copy() -> Interface

Create a copy of the Interface object.

Uses the existing serialization infrastructure to ensure proper copying of all DataArrays and nested objects.

Returns:

Type	Description
Interface	A new instance of the same class with copied data.

HeatPump

HeatPump(label: str, COP: TemporalDataUser, P_el: Flow, Q_th: Flow, on_off_parameters: OnOffParameters | None = None, meta_data: dict | None = None)

Bases: LinearConverter

A specialized LinearConverter representing an electric heat pump for thermal energy generation.

Heat pumps convert electrical energy into thermal energy with a Coefficient of Performance (COP) greater than 1, making them more efficient than direct electric heating. This is a simplified wrapper around LinearConverter with predefined conversion relationships for heat pump applications.

Parameters:

Name	Type	Description	Default
label	str	The label of the Element. Used to identify it in the FlowSystem.	required
COP	TemporalDataUser	Coefficient of Performance (typically 1-20 range). Defines the ratio of thermal output to electrical input. COP > 1 indicates the heat pump extracts additional energy from the environment.	required
P_el	Flow	Electrical input-flow representing electricity consumption.	required
Q_th	Flow	Thermal output-flow representing heat generation.	required
on_off_parameters	OnOffParameters | None	Parameters defining binary operation constraints and costs.	None
meta_data	dict | None	Used to store additional information. Not used internally but saved in results. Only use Python native types.	None

Examples:

Air-source heat pump with constant COP:

air_hp = HeatPump(
    label='air_source_heat_pump',
    COP=3.5,  # COP of 3.5 (350% efficiency)
    P_el=electricity_flow,
    Q_th=heating_flow,
)

Ground-source heat pump with temperature-dependent COP:

ground_hp = HeatPump(
    label='geothermal_heat_pump',
    COP=temperature_dependent_cop,  # Time-varying COP based on ground temp
    P_el=electricity_flow,
    Q_th=radiant_heating_flow,
    on_off_parameters=OnOffParameters(
        consecutive_on_hours_min=2,  # Avoid frequent cycling
        effects_per_running_hour={'maintenance': 0.5},
    ),
)

Note

The conversion relationship is: Q_th = P_el × COP

COP should be greater than 1 for realistic heat pump operation, with typical values ranging from 2-6 depending on technology and operating conditions. Higher COP values indicate more efficient heat extraction from the environment.

Functions

to_dataset

to_dataset() -> xr.Dataset

Convert the object to an xarray Dataset representation. All DataArrays become dataset variables, everything else goes to attrs.

Its recommended to only call this method on Interfaces with all numeric data stored as xr.DataArrays. Interfaces inside a FlowSystem are automatically converted this form after connecting and transforming the FlowSystem.

Returns:

Type	Description
Dataset	xr.Dataset: Dataset containing all DataArrays with basic objects only in attributes

Raises:

Type	Description
ValueError	If serialization fails due to naming conflicts or invalid data

to_netcdf

to_netcdf(path: str | Path, compression: int = 0)

Save the object to a NetCDF file.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to save the NetCDF file	required
compression	int	Compression level (0-9)	0

Raises:

Type	Description
ValueError	If serialization fails
IOError	If file cannot be written

from_dataset classmethod

from_dataset(ds: Dataset) -> Interface

Create an instance from an xarray Dataset.

Parameters:

Name	Type	Description	Default
ds	Dataset	Dataset containing the object data	required

Returns:

Type	Description
Interface	Interface instance

Raises:

Type	Description
ValueError	If dataset format is invalid or class mismatch

from_netcdf classmethod

from_netcdf(path: str | Path) -> Interface

Load an instance from a NetCDF file.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the NetCDF file	required

Returns:

Type	Description
Interface	Interface instance

Raises:

Type	Description
IOError	If file cannot be read
ValueError	If file format is invalid

get_structure

get_structure(clean: bool = False, stats: bool = False) -> dict

Get object structure as a dictionary.

Parameters:

Name	Type	Description	Default
clean	bool	If True, remove None and empty dicts and lists.	False
stats	bool	If True, replace DataArray references with statistics	False

Returns:

Type	Description
dict	Dictionary representation of the object structure

to_json

to_json(path: str | Path)

Save the object to a JSON file. This is meant for documentation and comparison, not for reloading.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the JSON file.	required

Raises:

Type	Description
IOError	If file cannot be written

copy

copy() -> Interface

Create a copy of the Interface object.

Uses the existing serialization infrastructure to ensure proper copying of all DataArrays and nested objects.

Returns:

Type	Description
Interface	A new instance of the same class with copied data.

CoolingTower

CoolingTower(label: str, specific_electricity_demand: TemporalDataUser, P_el: Flow, Q_th: Flow, on_off_parameters: OnOffParameters | None = None, meta_data: dict | None = None)

Bases: LinearConverter

A specialized LinearConverter representing a cooling tower for waste heat rejection.

Cooling towers consume electrical energy (for fans, pumps) to reject thermal energy to the environment through evaporation and heat transfer. The electricity demand is typically a small fraction of the thermal load being rejected. This component has no thermal outputs as the heat is rejected to the environment.

Parameters:

Name	Type	Description	Default
label	str	The label of the Element. Used to identify it in the FlowSystem.	required
specific_electricity_demand	TemporalDataUser	Auxiliary electricity demand per unit of cooling power (dimensionless, typically 0.01-0.05 range). Represents the fraction of thermal power that must be supplied as electricity for fans and pumps.	required
P_el	Flow	Electrical input-flow representing electricity consumption for fans/pumps.	required
Q_th	Flow	Thermal input-flow representing waste heat to be rejected to environment.	required
on_off_parameters	OnOffParameters | None	Parameters defining binary operation constraints and costs.	None
meta_data	dict | None	Used to store additional information. Not used internally but saved in results. Only use Python native types.	None

Examples:

Industrial cooling tower:

cooling_tower = CoolingTower(
    label='process_cooling_tower',
    specific_electricity_demand=0.025,  # 2.5% auxiliary power
    P_el=cooling_electricity,
    Q_th=waste_heat_flow,
)

Power plant condenser cooling:

condenser_cooling = CoolingTower(
    label='power_plant_cooling',
    specific_electricity_demand=0.015,  # 1.5% auxiliary power
    P_el=auxiliary_electricity,
    Q_th=condenser_waste_heat,
    on_off_parameters=OnOffParameters(
        consecutive_on_hours_min=4,  # Minimum operation time
        effects_per_running_hour={'water_consumption': 2.5},  # m³/h
    ),
)

Note

The conversion relationship is: P_el = Q_th × specific_electricity_demand

The cooling tower consumes electrical power proportional to the thermal load. No thermal energy is produced - all thermal input is rejected to the environment.

Typical specific electricity demands range from 1-5% of the thermal cooling load, depending on tower design, climate conditions, and operational requirements.

Functions

to_dataset

to_dataset() -> xr.Dataset

Convert the object to an xarray Dataset representation. All DataArrays become dataset variables, everything else goes to attrs.

Its recommended to only call this method on Interfaces with all numeric data stored as xr.DataArrays. Interfaces inside a FlowSystem are automatically converted this form after connecting and transforming the FlowSystem.

Returns:

Type	Description
Dataset	xr.Dataset: Dataset containing all DataArrays with basic objects only in attributes

Raises:

Type	Description
ValueError	If serialization fails due to naming conflicts or invalid data

to_netcdf

to_netcdf(path: str | Path, compression: int = 0)

Save the object to a NetCDF file.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to save the NetCDF file	required
compression	int	Compression level (0-9)	0

Raises:

Type	Description
ValueError	If serialization fails
IOError	If file cannot be written

from_dataset classmethod

from_dataset(ds: Dataset) -> Interface

Create an instance from an xarray Dataset.

Parameters:

Name	Type	Description	Default
ds	Dataset	Dataset containing the object data	required

Returns:

Type	Description
Interface	Interface instance

Raises:

Type	Description
ValueError	If dataset format is invalid or class mismatch

from_netcdf classmethod

from_netcdf(path: str | Path) -> Interface

Load an instance from a NetCDF file.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the NetCDF file	required

Returns:

Type	Description
Interface	Interface instance

Raises:

Type	Description
IOError	If file cannot be read
ValueError	If file format is invalid

get_structure

get_structure(clean: bool = False, stats: bool = False) -> dict

Get object structure as a dictionary.

Parameters:

Name	Type	Description	Default
clean	bool	If True, remove None and empty dicts and lists.	False
stats	bool	If True, replace DataArray references with statistics	False

Returns:

Type	Description
dict	Dictionary representation of the object structure

to_json

to_json(path: str | Path)

Save the object to a JSON file. This is meant for documentation and comparison, not for reloading.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the JSON file.	required

Raises:

Type	Description
IOError	If file cannot be written

copy

copy() -> Interface

Create a copy of the Interface object.

Uses the existing serialization infrastructure to ensure proper copying of all DataArrays and nested objects.

Returns:

Type	Description
Interface	A new instance of the same class with copied data.

CHP

CHP(label: str, eta_th: TemporalDataUser, eta_el: TemporalDataUser, Q_fu: Flow, P_el: Flow, Q_th: Flow, on_off_parameters: OnOffParameters | None = None, meta_data: dict | None = None)

Bases: LinearConverter

A specialized LinearConverter representing a Combined Heat and Power (CHP) unit.

CHP units simultaneously generate both electrical and thermal energy from a single fuel input, providing higher overall efficiency than separate generation. This is a wrapper around LinearConverter with predefined conversion relationships for cogeneration applications.

Parameters:

Name	Type	Description	Default
label	str	The label of the Element. Used to identify it in the FlowSystem.	required
eta_th	TemporalDataUser	Thermal efficiency factor (0-1 range). Defines the fraction of fuel energy converted to useful thermal output.	required
eta_el	TemporalDataUser	Electrical efficiency factor (0-1 range). Defines the fraction of fuel energy converted to electrical output.	required
Q_fu	Flow	Fuel input-flow representing fuel consumption.	required
P_el	Flow	Electrical output-flow representing electricity generation.	required
Q_th	Flow	Thermal output-flow representing heat generation.	required
on_off_parameters	OnOffParameters | None	Parameters defining binary operation constraints and costs.	None
meta_data	dict | None	Used to store additional information. Not used internally but saved in results. Only use Python native types.	None

Examples:

Natural gas CHP unit:

gas_chp = CHP(
    label='natural_gas_chp',
    eta_th=0.45,  # 45% thermal efficiency
    eta_el=0.35,  # 35% electrical efficiency (80% total)
    Q_fu=natural_gas_flow,
    P_el=electricity_flow,
    Q_th=district_heat_flow,
)

Industrial CHP with operational constraints:

industrial_chp = CHP(
    label='industrial_chp',
    eta_th=0.40,
    eta_el=0.38,
    Q_fu=fuel_gas_flow,
    P_el=plant_electricity,
    Q_th=process_steam,
    on_off_parameters=OnOffParameters(
        consecutive_on_hours_min=8,  # Minimum 8-hour operation
        effects_per_switch_on={'startup_cost': 5000},
        on_hours_total_max=6000,  # Annual operating limit
    ),
)

Note

The conversion relationships are: - Q_th = Q_fu × eta_th (thermal output) - P_el = Q_fu × eta_el (electrical output)

Total efficiency (eta_th + eta_el) should be ≤ 1.0, with typical combined efficiencies of 80-90% for modern CHP units. This provides significant efficiency gains compared to separate heat and power generation.

Functions

to_dataset

to_dataset() -> xr.Dataset

Convert the object to an xarray Dataset representation. All DataArrays become dataset variables, everything else goes to attrs.

Its recommended to only call this method on Interfaces with all numeric data stored as xr.DataArrays. Interfaces inside a FlowSystem are automatically converted this form after connecting and transforming the FlowSystem.

Returns:

Type	Description
Dataset	xr.Dataset: Dataset containing all DataArrays with basic objects only in attributes

Raises:

Type	Description
ValueError	If serialization fails due to naming conflicts or invalid data

to_netcdf

to_netcdf(path: str | Path, compression: int = 0)

Save the object to a NetCDF file.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to save the NetCDF file	required
compression	int	Compression level (0-9)	0

Raises:

Type	Description
ValueError	If serialization fails
IOError	If file cannot be written

from_dataset classmethod

from_dataset(ds: Dataset) -> Interface

Create an instance from an xarray Dataset.

Parameters:

Name	Type	Description	Default
ds	Dataset	Dataset containing the object data	required

Returns:

Type	Description
Interface	Interface instance

Raises:

Type	Description
ValueError	If dataset format is invalid or class mismatch

from_netcdf classmethod

from_netcdf(path: str | Path) -> Interface

Load an instance from a NetCDF file.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the NetCDF file	required

Returns:

Type	Description
Interface	Interface instance

Raises:

Type	Description
IOError	If file cannot be read
ValueError	If file format is invalid

get_structure

get_structure(clean: bool = False, stats: bool = False) -> dict

Get object structure as a dictionary.

Parameters:

Name	Type	Description	Default
clean	bool	If True, remove None and empty dicts and lists.	False
stats	bool	If True, replace DataArray references with statistics	False

Returns:

Type	Description
dict	Dictionary representation of the object structure

to_json

to_json(path: str | Path)

Save the object to a JSON file. This is meant for documentation and comparison, not for reloading.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the JSON file.	required

Raises:

Type	Description
IOError	If file cannot be written

copy

copy() -> Interface

Create a copy of the Interface object.

Uses the existing serialization infrastructure to ensure proper copying of all DataArrays and nested objects.

Returns:

Type	Description
Interface	A new instance of the same class with copied data.

HeatPumpWithSource

HeatPumpWithSource(label: str, COP: TemporalDataUser, P_el: Flow, Q_ab: Flow, Q_th: Flow, on_off_parameters: OnOffParameters | None = None, meta_data: dict | None = None)

Bases: LinearConverter

A specialized LinearConverter representing a heat pump with explicit heat source modeling.

This component models a heat pump that extracts thermal energy from a heat source (ground, air, water) and upgrades it using electrical energy to provide higher-grade thermal output. Unlike the simple HeatPump class, this explicitly models both the heat source extraction and electrical consumption with their interdependent relationships.

Parameters:

Name	Type	Description	Default
label	str	The label of the Element. Used to identify it in the FlowSystem.	required
COP	TemporalDataUser	Coefficient of Performance (typically 1-20 range). Defines the ratio of thermal output to electrical input. The heat source extraction is automatically calculated as Q_ab = Q_th × (COP-1)/COP.	required
P_el	Flow	Electrical input-flow representing electricity consumption for compressor.	required
Q_ab	Flow	Heat source input-flow representing thermal energy extracted from environment (ground, air, water source).	required
Q_th	Flow	Thermal output-flow representing useful heat delivered to the application.	required
on_off_parameters	OnOffParameters | None	Parameters defining binary operation constraints and costs.	None
meta_data	dict | None	Used to store additional information. Not used internally but saved in results. Only use Python native types.	None

Examples:

Ground-source heat pump with explicit ground coupling:

ground_source_hp = HeatPumpWithSource(
    label='geothermal_heat_pump',
    COP=4.5,  # High COP due to stable ground temperature
    P_el=electricity_flow,
    Q_ab=ground_heat_extraction,  # Heat extracted from ground loop
    Q_th=building_heating_flow,
)

Air-source heat pump with temperature-dependent performance:

waste_heat_pump = HeatPumpWithSource(
    label='waste_heat_pump',
    COP=temperature_dependent_cop,  # Varies with temperature of heat source
    P_el=electricity_consumption,
    Q_ab=industrial_heat_extraction,  # Heat extracted from a industrial process or waste water
    Q_th=heat_supply,
    on_off_parameters=OnOffParameters(
        consecutive_on_hours_min=0.5,  # 30-minute minimum runtime
        effects_per_switch_on={'costs': 1000},
    ),
)

Note

The conversion relationships are: - Q_th = P_el × COP (thermal output from electrical input) - Q_ab = Q_th × (COP-1)/COP (heat source extraction) - Energy balance: Q_th = P_el + Q_ab

This formulation explicitly tracks the heat source, which is important for systems where the source capacity or temperature is limited, or where the impact of heat extraction must be considered.

COP should be > 1 for thermodynamically valid operation, with typical values of 2-6 depending on source and sink temperatures.

Functions

to_dataset

to_dataset() -> xr.Dataset

Convert the object to an xarray Dataset representation. All DataArrays become dataset variables, everything else goes to attrs.

Its recommended to only call this method on Interfaces with all numeric data stored as xr.DataArrays. Interfaces inside a FlowSystem are automatically converted this form after connecting and transforming the FlowSystem.

Returns:

Type	Description
Dataset	xr.Dataset: Dataset containing all DataArrays with basic objects only in attributes

Raises:

Type	Description
ValueError	If serialization fails due to naming conflicts or invalid data

to_netcdf

to_netcdf(path: str | Path, compression: int = 0)

Save the object to a NetCDF file.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to save the NetCDF file	required
compression	int	Compression level (0-9)	0

Raises:

Type	Description
ValueError	If serialization fails
IOError	If file cannot be written

from_dataset classmethod

from_dataset(ds: Dataset) -> Interface

Create an instance from an xarray Dataset.

Parameters:

Name	Type	Description	Default
ds	Dataset	Dataset containing the object data	required

Returns:

Type	Description
Interface	Interface instance

Raises:

Type	Description
ValueError	If dataset format is invalid or class mismatch

from_netcdf classmethod

from_netcdf(path: str | Path) -> Interface

Load an instance from a NetCDF file.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to the NetCDF file	required

Returns:

Type	Description
Interface	Interface instance

Raises:

Type	Description
IOError	If file cannot be read
ValueError	If file format is invalid

get_structure

get_structure(clean: bool = False, stats: bool = False) -> dict

Get object structure as a dictionary.

Parameters:

Name	Type	Description	Default
clean	bool	If True, remove None and empty dicts and lists.	False
stats	bool	If True, replace DataArray references with statistics	False

Returns:

Type	Description
dict	Dictionary representation of the object structure

to_json

to_json(path: str | Path)

Save the object to a JSON file. This is meant for documentation and comparison, not for reloading.

Parameters:

Name	Type	Description	Default
path	str | Path	The path to the JSON file.	required

Raises:

Type	Description
IOError	If file cannot be written

copy

copy() -> Interface

Create a copy of the Interface object.

Uses the existing serialization infrastructure to ensure proper copying of all DataArrays and nested objects.

Returns:

Type	Description
Interface	A new instance of the same class with copied data.

Functions

check_bounds

check_bounds(value: TemporalDataUser, parameter_label: str, element_label: str, lower_bound: TemporalDataUser, upper_bound: TemporalDataUser) -> None

Check if the value is within the bounds. The bounds are exclusive. If not, log a warning. Args: value: The value to check. parameter_label: The label of the value. element_label: The label of the element. lower_bound: The lower bound. upper_bound: The upper bound.