fluxopt.components

Classes:

Name	Description
Port	System boundary that imports from or exports to buses.
Converter	Conversion between input and output flows.

Port dataclass

Port(
    id: str,
    imports: list[Flow] | IdList[Flow] = list(),
    exports: list[Flow] | IdList[Flow] = list(),
)

System boundary that imports from or exports to buses.

Methods:

Name	Description
__post_init__	Qualify flow ids with the port id.

__post_init__

__post_init__() -> None

Qualify flow ids with the port id.

Source code in src/fluxopt/components.py

def __post_init__(self) -> None:
    """Qualify flow ids with the port id."""
    self.imports = _qualify_flows(self.id, list(self.imports))
    self.exports = _qualify_flows(self.id, list(self.exports))

Converter dataclass

Converter(
    id: str,
    inputs: list[Flow] | IdList[Flow],
    outputs: list[Flow] | IdList[Flow],
    conversion_factors: list[dict[str, Variate]] = list(),
    conversion: PiecewiseConversion | None = None,
)

Conversion between input and output flows.

Two mutually exclusive modes:

• Linear — conversion_factors=[{flow_short_id: a_f}, ...], one dict per equation; constraint sum_f(a_f * P_{f,t}) = 0.
• Piecewise — conversion=PiecewiseConversion(...); the solver interpolates between breakpoints, optionally with on/off via PiecewiseConversion.status.

Parameters:

Name	Type	Description	Default
id	str	Converter id.	required
inputs	list[Flow] | IdList[Flow]	Input flows.	required
outputs	list[Flow] | IdList[Flow]	Output flows.	required
conversion_factors	list[dict[str, Variate]]	Linear-mode equations. Empty when conversion is set.	list()
conversion	PiecewiseConversion | None	Piecewise-mode curve. None for linear mode.	None

Methods:

Name	Description
__post_init__	Qualify flow ids and validate mode exclusivity.
boiler	Create a boiler converter: fuel * eta = thermal.
heat_pump	Create a heat pump converter with source heat.
power2heat	Create an electric resistance heater: electrical * eta = thermal.
chp	Create a CHP converter with separate electrical and thermal outputs.

__post_init__

__post_init__() -> None

Qualify flow ids and validate mode exclusivity.

Source code in src/fluxopt/components.py

def __post_init__(self) -> None:
    """Qualify flow ids and validate mode exclusivity."""
    self.inputs = _qualify_flows(self.id, list(self.inputs))
    self.outputs = _qualify_flows(self.id, list(self.outputs))
    self._short_to_id = {f.short_id: f.id for f in (*self.inputs, *self.outputs)}

    if self.conversion is not None:
        if self.conversion_factors:
            msg = (
                f'Converter {self.id!r}: cannot set both conversion_factors and conversion '
                f'(they are mutually exclusive linear vs piecewise modes)'
            )
            raise ValueError(msg)
        curve_flows = {flow for flow, _, _ in self.conversion._iter_normalized()}
        unknown = curve_flows - set(self._short_to_id)
        if unknown:
            msg = (
                f'Converter {self.id!r}: PiecewiseConversion references unknown flow short_ids '
                f'{sorted(unknown)}; known: {sorted(self._short_to_id)}'
            )
            raise ValueError(msg)
        if self.conversion.status is not None:
            for f in (*self.inputs, *self.outputs):
                if f.status is not None:
                    msg = (
                        f'Converter {self.id!r}: flow {f.short_id!r} cannot have flow-level '
                        f'status when PiecewiseConversion.status is set'
                    )
                    raise ValueError(msg)

boiler classmethod

boiler(
    id: str, thermal_efficiency: Variate, fuel_flow: Flow, thermal_flow: Flow
) -> Converter

Create a boiler converter: fuel * eta = thermal.

Parameters:

Name	Type	Description	Default
id	str	Converter id.	required
thermal_efficiency	Variate	Thermal efficiency eta.	required
fuel_flow	Flow	Input fuel flow.	required
thermal_flow	Flow	Output thermal flow.	required

Source code in src/fluxopt/components.py

@classmethod
def boiler(cls, id: str, thermal_efficiency: Variate, fuel_flow: Flow, thermal_flow: Flow) -> Converter:
    """Create a boiler converter: fuel * eta = thermal.

    Args:
        id: Converter id.
        thermal_efficiency: Thermal efficiency eta.
        fuel_flow: Input fuel flow.
        thermal_flow: Output thermal flow.
    """
    return cls._single_io(id, thermal_efficiency, fuel_flow, thermal_flow)

heat_pump classmethod

heat_pump(
    id: str,
    cop: Variate,
    electrical_flow: Flow,
    source_flow: Flow,
    thermal_flow: Flow,
) -> Converter

Create a heat pump converter with source heat.

Two conversion equations

electrical * COP = thermal electrical + source = thermal

Parameters:

Name	Type	Description	Default
id	str	Converter id.	required
cop	Variate	Coefficient of performance.	required
electrical_flow	Flow	Input electrical flow.	required
source_flow	Flow	Input environmental heat flow (air, ground, water).	required
thermal_flow	Flow	Output thermal flow.	required

Source code in src/fluxopt/components.py

@classmethod
def heat_pump(
    cls,
    id: str,
    cop: Variate,
    electrical_flow: Flow,
    source_flow: Flow,
    thermal_flow: Flow,
) -> Converter:
    """Create a heat pump converter with source heat.

    Two conversion equations:
        electrical * COP = thermal
        electrical + source = thermal

    Args:
        id: Converter id.
        cop: Coefficient of performance.
        electrical_flow: Input electrical flow.
        source_flow: Input environmental heat flow (air, ground, water).
        thermal_flow: Output thermal flow.
    """
    return cls(
        id,
        inputs=[electrical_flow, source_flow],
        outputs=[thermal_flow],
        conversion_factors=[
            {electrical_flow.short_id: cop, thermal_flow.short_id: -1},
            {electrical_flow.short_id: 1, source_flow.short_id: 1, thermal_flow.short_id: -1},
        ],
    )

power2heat classmethod

power2heat(
    id: str, efficiency: Variate, electrical_flow: Flow, thermal_flow: Flow
) -> Converter

Create an electric resistance heater: electrical * eta = thermal.

Parameters:

Name	Type	Description	Default
id	str	Converter id.	required
efficiency	Variate	Electrical-to-thermal efficiency.	required
electrical_flow	Flow	Input electrical flow.	required
thermal_flow	Flow	Output thermal flow.	required

Source code in src/fluxopt/components.py

@classmethod
def power2heat(cls, id: str, efficiency: Variate, electrical_flow: Flow, thermal_flow: Flow) -> Converter:
    """Create an electric resistance heater: electrical * eta = thermal.

    Args:
        id: Converter id.
        efficiency: Electrical-to-thermal efficiency.
        electrical_flow: Input electrical flow.
        thermal_flow: Output thermal flow.
    """
    return cls._single_io(id, efficiency, electrical_flow, thermal_flow)

chp classmethod

chp(
    id: str,
    eta_el: Variate,
    eta_th: Variate,
    fuel_flow: Flow,
    electrical_flow: Flow,
    thermal_flow: Flow,
) -> Converter

Create a CHP converter with separate electrical and thermal outputs.

Parameters:

Name	Type	Description	Default
id	str	Converter id.	required
eta_el	Variate	Electrical efficiency.	required
eta_th	Variate	Thermal efficiency.	required
fuel_flow	Flow	Input fuel flow.	required
electrical_flow	Flow	Output electrical flow.	required
thermal_flow	Flow	Output thermal flow.	required

Source code in src/fluxopt/components.py

@classmethod
def chp(
    cls,
    id: str,
    eta_el: Variate,
    eta_th: Variate,
    fuel_flow: Flow,
    electrical_flow: Flow,
    thermal_flow: Flow,
) -> Converter:
    """Create a CHP converter with separate electrical and thermal outputs.

    Args:
        id: Converter id.
        eta_el: Electrical efficiency.
        eta_th: Thermal efficiency.
        fuel_flow: Input fuel flow.
        electrical_flow: Output electrical flow.
        thermal_flow: Output thermal flow.
    """
    return cls(
        id,
        inputs=[fuel_flow],
        outputs=[electrical_flow, thermal_flow],
        conversion_factors=[
            {fuel_flow.short_id: eta_el, electrical_flow.short_id: -1},
            {fuel_flow.short_id: eta_th, thermal_flow.short_id: -1},
        ],
    )