flixopt.linear_converters ¶

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

Attributes¶

Classes¶

Boiler ¶

Python

Boiler(label: str, thermal_efficiency: Numeric_TPS | None = None, fuel_flow: Flow | None = None, thermal_flow: Flow | None = None, on_off_parameters: OnOffParameters | None = None, meta_data: dict | None = None, **kwargs)

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
`thermal_efficiency`	`Numeric_TPS \| None`	Thermal efficiency factor (0-1 range). Defines the ratio of thermal output to fuel input energy content.	`None`
`fuel_flow`	`Flow \| None`	Fuel input-flow representing fuel consumption.	`None`
`thermal_flow`	`Flow \| None`	Thermal output-flow representing heat generation.	`None`
`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`
`eta`		Deprecated. Use `thermal_efficiency` instead.	required
`Q_fu`		Deprecated. Use `fuel_flow` instead.	required
`Q_th`		Deprecated. Use `thermal_flow` instead.	required

Examples:

Natural gas boiler:

Python

gas_boiler = Boiler(
    label='natural_gas_boiler',
    thermal_efficiency=0.85,  # 85% thermal efficiency
    fuel_flow=natural_gas_flow,
    thermal_flow=hot_water_flow,
)

Biomass boiler with seasonal efficiency variation:

Python

biomass_boiler = Boiler(
    label='wood_chip_boiler',
    thermal_efficiency=seasonal_efficiency_profile,  # Time-varying efficiency
    fuel_flow=biomass_flow,
    thermal_flow=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: thermal_flow = fuel_flow × thermal_efficiency

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

Attributes¶

flow_system `property` ¶

Python

flow_system: FlowSystem

Access the FlowSystem this interface is linked to.

Returns:

Type	Description
`FlowSystem`	The FlowSystem instance this interface belongs to.

Raises:

Type	Description
`RuntimeError`	If interface has not been linked to a FlowSystem yet.

Note

For Elements, this is set during add_elements(). For parameter classes, this is set recursively when the parent Element is registered.

Functions¶

to_dataset ¶

Python

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 ¶

Python

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` ¶

Python

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` ¶

Python

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 ¶

Python

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 ¶

Python

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 ¶

Python

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 ¶

Python

Power2Heat(label: str, thermal_efficiency: Numeric_TPS | None = None, electrical_flow: Flow | None = None, thermal_flow: Flow | None = None, on_off_parameters: OnOffParameters | None = None, meta_data: dict | None = None, **kwargs)

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
`thermal_efficiency`	`Numeric_TPS \| None`	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.	`None`
`electrical_flow`	`Flow \| None`	Electrical input-flow representing electricity consumption.	`None`
`thermal_flow`	`Flow \| None`	Thermal output-flow representing heat generation.	`None`
`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`
`eta`		Deprecated. Use `thermal_efficiency` instead.	required
`P_el`		Deprecated. Use `electrical_flow` instead.	required
`Q_th`		Deprecated. Use `thermal_flow` instead.	required

Examples:

Electric resistance heater:

Python

electric_heater = Power2Heat(
    label='resistance_heater',
    thermal_efficiency=0.98,  # 98% efficiency (small losses)
    electrical_flow=electricity_flow,
    thermal_flow=space_heating_flow,
)

Electrode boiler for industrial steam:

Python

electrode_boiler = Power2Heat(
    label='electrode_steam_boiler',
    thermal_efficiency=0.95,  # 95% efficiency including boiler losses
    electrical_flow=industrial_electricity,
    thermal_flow=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: thermal_flow = electrical_flow × thermal_efficiency

Unlike heat pumps, Power2Heat systems cannot exceed 100% efficiency (thermal_efficiency ≤ 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.

Attributes¶

flow_system `property` ¶

Python

flow_system: FlowSystem

Access the FlowSystem this interface is linked to.

Returns:

Type	Description
`FlowSystem`	The FlowSystem instance this interface belongs to.

Raises:

Type	Description
`RuntimeError`	If interface has not been linked to a FlowSystem yet.

Note

For Elements, this is set during add_elements(). For parameter classes, this is set recursively when the parent Element is registered.

Functions¶

to_dataset ¶

Python

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 ¶

Python

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` ¶

Python

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` ¶

Python

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 ¶

Python

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 ¶

Python

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 ¶

Python

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 ¶

Python

HeatPump(label: str, cop: Numeric_TPS | None = None, electrical_flow: Flow | None = None, thermal_flow: Flow | None = None, on_off_parameters: OnOffParameters | None = None, meta_data: dict | None = None, **kwargs)

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`	`Numeric_TPS \| None`	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.	`None`
`electrical_flow`	`Flow \| None`	Electrical input-flow representing electricity consumption.	`None`
`thermal_flow`	`Flow \| None`	Thermal output-flow representing heat generation.	`None`
`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`
`COP`		Deprecated. Use `cop` instead.	required
`P_el`		Deprecated. Use `electrical_flow` instead.	required
`Q_th`		Deprecated. Use `thermal_flow` instead.	required

Examples:

Air-source heat pump with constant COP:

Python

air_hp = HeatPump(
    label='air_source_heat_pump',
    cop=3.5,  # COP of 3.5 (350% efficiency)
    electrical_flow=electricity_flow,
    thermal_flow=heating_flow,
)

Ground-source heat pump with temperature-dependent COP:

Python

ground_hp = HeatPump(
    label='geothermal_heat_pump',
    cop=temperature_dependent_cop,  # Time-varying COP based on ground temp
    electrical_flow=electricity_flow,
    thermal_flow=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: thermal_flow = electrical_flow × 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.

Attributes¶

flow_system `property` ¶

Python

flow_system: FlowSystem

Access the FlowSystem this interface is linked to.

Returns:

Type	Description
`FlowSystem`	The FlowSystem instance this interface belongs to.

Raises:

Type	Description
`RuntimeError`	If interface has not been linked to a FlowSystem yet.

Note

For Elements, this is set during add_elements(). For parameter classes, this is set recursively when the parent Element is registered.

Functions¶

to_dataset ¶

Python

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 ¶

Python

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` ¶

Python

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` ¶

Python

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 ¶

Python

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 ¶

Python

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 ¶

Python

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 ¶

Python

CoolingTower(label: str, specific_electricity_demand: Numeric_TPS, electrical_flow: Flow | None = None, thermal_flow: Flow | None = None, on_off_parameters: OnOffParameters | None = None, meta_data: dict | None = None, **kwargs)

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`	`Numeric_TPS`	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
`electrical_flow`	`Flow \| None`	Electrical input-flow representing electricity consumption for fans/pumps.	`None`
`thermal_flow`	`Flow \| None`	Thermal input-flow representing waste heat to be rejected to environment.	`None`
`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`
`P_el`		Deprecated. Use `electrical_flow` instead.	required
`Q_th`		Deprecated. Use `thermal_flow` instead.	required

Examples:

Industrial cooling tower:

Python

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

Power plant condenser cooling:

Python

condenser_cooling = CoolingTower(
    label='power_plant_cooling',
    specific_electricity_demand=0.015,  # 1.5% auxiliary power
    electrical_flow=auxiliary_electricity,
    thermal_flow=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: electrical_flow = thermal_flow × 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.

Attributes¶

flow_system `property` ¶

Python

flow_system: FlowSystem

Access the FlowSystem this interface is linked to.

Returns:

Type	Description
`FlowSystem`	The FlowSystem instance this interface belongs to.

Raises:

Type	Description
`RuntimeError`	If interface has not been linked to a FlowSystem yet.

Note

For Elements, this is set during add_elements(). For parameter classes, this is set recursively when the parent Element is registered.

Functions¶

to_dataset ¶

Python

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 ¶

Python

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` ¶

Python

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` ¶

Python

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 ¶

Python

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 ¶

Python

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 ¶

Python

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 ¶

Python

CHP(label: str, thermal_efficiency: Numeric_TPS | None = None, electrical_efficiency: Numeric_TPS | None = None, fuel_flow: Flow | None = None, electrical_flow: Flow | None = None, thermal_flow: Flow | None = None, on_off_parameters: OnOffParameters | None = None, meta_data: dict | None = None, **kwargs)

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
`thermal_efficiency`	`Numeric_TPS \| None`	Thermal efficiency factor (0-1 range). Defines the fraction of fuel energy converted to useful thermal output.	`None`
`electrical_efficiency`	`Numeric_TPS \| None`	Electrical efficiency factor (0-1 range). Defines the fraction of fuel energy converted to electrical output.	`None`
`fuel_flow`	`Flow \| None`	Fuel input-flow representing fuel consumption.	`None`
`electrical_flow`	`Flow \| None`	Electrical output-flow representing electricity generation.	`None`
`thermal_flow`	`Flow \| None`	Thermal output-flow representing heat generation.	`None`
`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`
`eta_th`		Deprecated. Use `thermal_efficiency` instead.	required
`eta_el`		Deprecated. Use `electrical_efficiency` instead.	required
`Q_fu`		Deprecated. Use `fuel_flow` instead.	required
`P_el`		Deprecated. Use `electrical_flow` instead.	required
`Q_th`		Deprecated. Use `thermal_flow` instead.	required

Examples:

Natural gas CHP unit:

Python

gas_chp = CHP(
    label='natural_gas_chp',
    thermal_efficiency=0.45,  # 45% thermal efficiency
    electrical_efficiency=0.35,  # 35% electrical efficiency (80% total)
    fuel_flow=natural_gas_flow,
    electrical_flow=electricity_flow,
    thermal_flow=district_heat_flow,
)

Industrial CHP with operational constraints:

Python

industrial_chp = CHP(
    label='industrial_chp',
    thermal_efficiency=0.40,
    electrical_efficiency=0.38,
    fuel_flow=fuel_gas_flow,
    electrical_flow=plant_electricity,
    thermal_flow=process_steam,
    on_off_parameters=OnOffParameters(
        consecutive_on_hours_min=8,  # Minimum 8-hour operation
        effects_per_switch_on={'startup_cost': 5000},
        on_hours_max=6000,  # Annual operating limit
    ),
)

Note

The conversion relationships are: - thermal_flow = fuel_flow × thermal_efficiency (thermal output) - electrical_flow = fuel_flow × electrical_efficiency (electrical output)

Total efficiency (thermal_efficiency + electrical_efficiency) 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.

Attributes¶

flow_system `property` ¶

Python

flow_system: FlowSystem

Access the FlowSystem this interface is linked to.

Returns:

Type	Description
`FlowSystem`	The FlowSystem instance this interface belongs to.

Raises:

Type	Description
`RuntimeError`	If interface has not been linked to a FlowSystem yet.

Note

For Elements, this is set during add_elements(). For parameter classes, this is set recursively when the parent Element is registered.

Functions¶

to_dataset ¶

Python

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 ¶

Python

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` ¶

Python

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` ¶

Python

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 ¶

Python

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 ¶

Python

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 ¶

Python

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 ¶

Python

HeatPumpWithSource(label: str, cop: Numeric_TPS | None = None, electrical_flow: Flow | None = None, heat_source_flow: Flow | None = None, thermal_flow: Flow | None = None, on_off_parameters: OnOffParameters | None = None, meta_data: dict | None = None, **kwargs)

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`	`Numeric_TPS \| None`	Coefficient of Performance (typically 1-20 range). Defines the ratio of thermal output to electrical input. The heat source extraction is automatically calculated as heat_source_flow = thermal_flow × (COP-1)/COP.	`None`
`electrical_flow`	`Flow \| None`	Electrical input-flow representing electricity consumption for compressor.	`None`
`heat_source_flow`	`Flow \| None`	Heat source input-flow representing thermal energy extracted from environment (ground, air, water source).	`None`
`thermal_flow`	`Flow \| None`	Thermal output-flow representing useful heat delivered to the application.	`None`
`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`
`COP`		Deprecated. Use `cop` instead.	required
`P_el`		Deprecated. Use `electrical_flow` instead.	required
`Q_ab`		Deprecated. Use `heat_source_flow` instead.	required
`Q_th`		Deprecated. Use `thermal_flow` instead.	required

Examples:

Ground-source heat pump with explicit ground coupling:

Python

ground_source_hp = HeatPumpWithSource(
    label='geothermal_heat_pump',
    cop=4.5,  # High COP due to stable ground temperature
    electrical_flow=electricity_flow,
    heat_source_flow=ground_heat_extraction,  # Heat extracted from ground loop
    thermal_flow=building_heating_flow,
)

Air-source heat pump with temperature-dependent performance:

Python

waste_heat_pump = HeatPumpWithSource(
    label='waste_heat_pump',
    cop=temperature_dependent_cop,  # Varies with temperature of heat source
    electrical_flow=electricity_consumption,
    heat_source_flow=industrial_heat_extraction,  # Heat extracted from a industrial process or waste water
    thermal_flow=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: - thermal_flow = electrical_flow × COP (thermal output from electrical input) - heat_source_flow = thermal_flow × (COP-1)/COP (heat source extraction) - Energy balance: thermal_flow = electrical_flow + heat_source_flow

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.

Attributes¶

flow_system `property` ¶

Python

flow_system: FlowSystem

Access the FlowSystem this interface is linked to.

Returns:

Type	Description
`FlowSystem`	The FlowSystem instance this interface belongs to.

Raises:

Type	Description
`RuntimeError`	If interface has not been linked to a FlowSystem yet.

Note

For Elements, this is set during add_elements(). For parameter classes, this is set recursively when the parent Element is registered.

Functions¶

to_dataset ¶

Python

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 ¶

Python

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` ¶

Python

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` ¶

Python

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 ¶

Python

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 ¶

Python

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 ¶

Python

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 ¶

Python

check_bounds(value: Numeric_TPS, parameter_label: str, element_label: str, lower_bound: Numeric_TPS, upper_bound: Numeric_TPS) -> 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.

flixopt.linear_converters ¶

Attributes¶

Classes¶

Boiler ¶

Attributes¶

flow_system property ¶

Functions¶

to_dataset ¶

to_netcdf ¶

from_dataset classmethod ¶

from_netcdf classmethod ¶

get_structure ¶

to_json ¶

copy ¶

Power2Heat ¶

Attributes¶

flow_system property ¶

Functions¶

to_dataset ¶

to_netcdf ¶

from_dataset classmethod ¶

from_netcdf classmethod ¶

get_structure ¶

to_json ¶

copy ¶

HeatPump ¶

Attributes¶

flow_system property ¶

Functions¶

to_dataset ¶

to_netcdf ¶

from_dataset classmethod ¶

from_netcdf classmethod ¶

get_structure ¶

to_json ¶

copy ¶

CoolingTower ¶

Attributes¶

flow_system property ¶

Functions¶

to_dataset ¶

to_netcdf ¶

from_dataset classmethod ¶

from_netcdf classmethod ¶

get_structure ¶

to_json ¶

copy ¶

CHP ¶

Attributes¶

flow_system property ¶

Functions¶

to_dataset ¶

to_netcdf ¶

from_dataset classmethod ¶

from_netcdf classmethod ¶

get_structure ¶

to_json ¶

copy ¶

HeatPumpWithSource ¶

Attributes¶

flow_system property ¶

Functions¶

to_dataset ¶

to_netcdf ¶

from_dataset classmethod ¶

from_netcdf classmethod ¶

get_structure ¶

to_json ¶

copy ¶

Functions¶

check_bounds ¶

flow_system `property` ¶

from_dataset `classmethod` ¶

from_netcdf `classmethod` ¶

flow_system `property` ¶

from_dataset `classmethod` ¶

from_netcdf `classmethod` ¶

flow_system `property` ¶

from_dataset `classmethod` ¶

from_netcdf `classmethod` ¶

flow_system `property` ¶

from_dataset `classmethod` ¶

from_netcdf `classmethod` ¶

flow_system `property` ¶

from_dataset `classmethod` ¶

from_netcdf `classmethod` ¶

flow_system `property` ¶

from_dataset `classmethod` ¶

from_netcdf `classmethod` ¶