9399721029

Committed 06 Jun 2024 11:01AM UTC coverage: 96.258% (-0.1%) from 96.371%

Build # 9399721029

Build Type

Pull #1068

github

Committed by

web-flow

Commit Message

Merge 09a9286b0 into a848e7bd3

Pull Request Pull Request #1068: Enforce nonconvex for OffsetConverter on a single flow instead of outputs

Run Details

1333 of 1414 branches covered (94.27%)

Branch coverage included in aggregate %.

89 of 93 new or added lines in 2 files covered. (95.7%)

1 existing line in 1 file now uncovered.

2654 of 2728 relevant lines covered (97.29%)

2.92 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

92.82

/src/oemof/solph/components/_offset_converter.py

# -*- coding: utf-8 -

"""
OffsetConverter and associated individual constraints (blocks) and groupings.

SPDX-FileCopyrightText: Uwe Krien <krien@uni-bremen.de>
SPDX-FileCopyrightText: Simon Hilpert
SPDX-FileCopyrightText: Cord Kaldemeyer
SPDX-FileCopyrightText: Patrik Schönfeldt
SPDX-FileCopyrightText: FranziPl
SPDX-FileCopyrightText: jnnr
SPDX-FileCopyrightText: Stephan Günther
SPDX-FileCopyrightText: FabianTU
SPDX-FileCopyrightText: Johannes Röder
SPDX-FileCopyrightText: Saeed Sayadi
SPDX-FileCopyrightText: Johannes Kochems

SPDX-License-Identifier: MIT

"""

from warnings import warn

from oemof.network import Node
from pyomo.core import BuildAction
from pyomo.core.base.block import ScalarBlock
from pyomo.environ import Constraint
from pyomo.environ import Set

from oemof.solph._plumbing import sequence


class OffsetConverter(Node):
    """An object with one input and multiple outputs and two coefficients
    per output to model part load behaviour.
    The output must contain a NonConvex object.

    Parameters
    ----------
    conversion_factors : dict, (:math:`C_1(t)`)
        Dict containing the respective bus as key and as value the parameter
        :math:`C_1(t)`. It represents the slope of a linear equation with
        respect to the `NonConvex` flow. The value can either be a scalar or a
        sequence with length of time horizon for simulation.

    normed_offsets : dict, (:math:`C_0(t)`)
        Dict containing the respective bus as key and as value the parameter
        :math:`C_0(t)`. It represents the y-intercept with respect to the
        `NonConvex` flow divided by the `nominal_value` of the `NonConvex` flow
        (this is for internal purposes). The value can either be a scalar or a
        sequence with length of time horizon for simulation.
    Notes
    -----
    **C_1 and C_0 can be calculated as follows:**

    .. _OffsetConverterCoefficients-equations:

    .. math::

        C_1 = \\frac{(l_{max}/\\eta_{max}-l_{min}/\\eta_{min}}{l_{max}-l_{min}}

        C_0 = \\frac{1}{\\eta_{max}} - C_1

    Where :math:`l_{max}` and :math:`l_{min}` are the maximum and minimum
    partload share (e.g. 1.0 and 0.5) with reference to the `NonConvex` flow
    and :math:`\\eta_{max}` and :math:`\\eta_{min}` are the respective
    efficiencies/conversion factors at these partloads.

    The sets, variables, constraints and objective parts are created
     * :py:class:`~oemof.solph.components._offset_converter.OffsetConverterBlock`

    Examples
    --------
    >>> from oemof import solph
    >>> bel = solph.buses.Bus(label='bel')
    >>> bth = solph.buses.Bus(label='bth')
    >>> l_nominal = 60
    >>> l_max = 1
    >>> l_min = 0.5
    >>> eta_max = 0.5
    >>> eta_min = 0.3
    >>> c1 = (l_max / eta_max - l_min / eta_min) / (l_max - l_min)
    >>> c0 = 1 / eta_max - c1
    >>> ostf = solph.components.OffsetConverter(
    ...    label='ostf',
    ...    inputs={bel: solph.flows.Flow()},
    ...    outputs={bth: solph.flows.Flow(
    ...         nominal_value=l_nominal, min=l_min, max=l_max,
    ...         nonconvex=solph.NonConvex())},
    ...    conversion_factors={bel: c1},
    ...    normed_offsets={bel: c0},
    ... )
    >>> type(ostf)
    <class 'oemof.solph.components._offset_converter.OffsetConverter'>

    The input required to operate at minimum load, can be computed from the
    slope and offset:

    >>> input_at_min = ostf.conversion_factors[bel][0] * l_min + ostf.normed_offsets[bel][0] * l_max
    >>> input_at_min * l_nominal
    100.0

    The same can be done for the input at nominal load:

    >>> input_at_max = l_max * (ostf.conversion_factors[bel][0] + ostf.normed_offsets[bel][0])
    >>> input_at_max * l_nominal
    120.0

    """  # noqa: E501

    def __init__(
        self,
        inputs,
        outputs,
        label=None,
        conversion_factors=None,
        normed_offsets=None,
        coefficients=None,
        custom_attributes=None,
    ):
        if custom_attributes is None:
            custom_attributes = {}

        super().__init__(
            inputs=inputs,
            outputs=outputs,
            label=label,
            custom_properties=custom_attributes,
        )

        # this part is used for the transition phase from the old
        # OffsetConverter API to the new one. It calcualtes the
        # conversion_factors and normed_offsets from the coefficients and the
        # outputs information on min and max.
        if (
            coefficients is not None
            and conversion_factors is None
            and normed_offsets is None
        ):
            normed_offsets, conversion_factors = (
                self.normed_offset_and_conversion_factors_from_coefficients(
                    coefficients
                )
            )

        elif coefficients is not None and (
            conversion_factors is not None or normed_offsets is not None
        ):
            msg = ""
            raise TypeError(msg)

        _reference_flow = [v for v in self.inputs.values() if v.nonconvex]
        _reference_flow += [v for v in self.outputs.values() if v.nonconvex]
        if len(_reference_flow) != 1:
            raise ValueError(
                "Exactly one flow of the `OffsetConverter` must have the "
                "`NonConvex` attribute."
            )

        if _reference_flow[0] in self.inputs.values():
            self._reference_node_at_input = True
            self._reference_node = _reference_flow[0].input
        else:
            self._reference_node_at_input = False
            self._reference_node = _reference_flow[0].output

        _investment_node = [
            v.input for v in self.inputs.values() if v.investment
        ]
        _investment_node += [
            v.output for v in self.outputs.values() if v.investment
        ]

        if len(_investment_node) > 0:
            if (
                len(_investment_node) > 1
                or self._reference_node != _investment_node[0]
            ):
                raise TypeError(
                    "`Investment` attribute must be defined only for the "
                    "NonConvex flow!"
                )

        if conversion_factors is None:
            conversion_factors = {}

        if self._reference_node in conversion_factors:
            raise ValueError(
                "Conversion factors cannot be specified for the `NonConvex` "
                "flow."
            )

        self.conversion_factors = {
            k: sequence(v) for k, v in conversion_factors.items()
        }

        missing_conversion_factor_keys = (
            set(self.outputs) | set(self.inputs)
        ) - set(self.conversion_factors)

        for cf in missing_conversion_factor_keys:
            self.conversion_factors[cf] = sequence(1)

        if normed_offsets is None:
            normed_offsets = {}

        if self._reference_node in normed_offsets:
            raise ValueError(
                "Normed offsets cannot be specified for the `NonConvex` flow."
            )

        self.normed_offsets = {
            k: sequence(v) for k, v in normed_offsets.items()
        }

        missing_normed_offsets_keys = (
            set(self.outputs) | set(self.inputs)
        ) - set(self.normed_offsets)

        for cf in missing_normed_offsets_keys:
            self.normed_offsets[cf] = sequence(0)

    def constraint_group(self):
        return OffsetConverterBlock

    def normed_offset_and_conversion_factors_from_coefficients(
        self, coefficients
    ):
        """
        Calculate slope and offset for new API from the old API coefficients.

        Parameters
        ----------
        coefficients : tuple
            tuple holding the coefficients (offset, slope) for the old style
            OffsetConverter.

        Returns
        -------
        tuple
            A tuple holding the slope and the offset for the new
            OffsetConverter API.
        """
        coefficients = tuple([sequence(i) for i in coefficients])
        if len(coefficients) != 2:
            raise ValueError(
                "Two coefficients or coefficient series have to be given."
            )

        input_bus = list(self.inputs.values())[0].input
        for flow in self.outputs.values():

            max_len = max(
                len(flow.max),
                len(flow.min),
                len(coefficients[0]),
                len(coefficients[1]),
            )

            # this could by vectorized, but since it is an API compatibility
            # fix I will not do this here
            eta_at_max = sequence(0)
            eta_at_min = sequence(0)
            slope = []
            offset = []
            for i in range(max_len):
                eta_at_max = (
                    flow.max[i]
                    * coefficients[1][i]
                    / (flow.max[i] - coefficients[0][i])
                )
                eta_at_min = (
                    flow.min[i]
                    * coefficients[1][i]
                    / (flow.min[i] - coefficients[0][i])
                )

                c0, c1 = slope_offset_from_nonconvex_output(
                    flow.max[i], flow.min[i], eta_at_max, eta_at_min
                )
                slope += [c0]
                offset += [c1]

            # apparently, when coefficients are given as a list, it is assumed,
            # that the list identical in length to the timeindex
            # There should be a general check, if lenghts match then!
            if max_len == 1:
                slope = sequence(slope[0])
                offset = sequence(offset[0])

            conversion_factors = {input_bus: slope}
            normed_offsets = {input_bus: offset}
            msg = (
                "The usage of coefficients is depricated, use "
                "conversion_factors and normed_offsets instead."
            )
            warn(msg, DeprecationWarning)

        return normed_offsets, conversion_factors


# --- BEGIN: To be removed for versions >= v0.6 ---
class OffsetTransformer(OffsetConverter):
    def __init__(
        self,
        inputs,
        outputs,
        label=None,
        conversion_factors=None,
        normed_offsets=None,
        custom_attributes=None,
    ):
        super().__init__(
            label=label,
            inputs=inputs,
            outputs=outputs,
            conversion_factors=conversion_factors,
            normed_offsets=normed_offsets,
            custom_attributes=custom_attributes,
        )
        warn(
            "solph.components.OffsetTransformer has been renamed to"
            " solph.components.OffsetConverter. The transitional wrapper"
            " will be deleted in the future.",
            FutureWarning,
        )


# --- END ---


class OffsetConverterBlock(ScalarBlock):
    r"""Block for the relation of nodes with type
    :class:`~oemof.solph.components._offset_converter.OffsetConverter`

    **The following constraints are created:**

    .. _OffsetConverter-equations:

    .. math::
        &
        P_{out}(p, t) = P_{in}(p, t) \cdot C_1(t) + P_nom(p) \cdot Y(t) \cdot C_0(t) \\


    The symbols used are defined as follows (with Variables (V) and Parameters (P)):

    +--------------------+---------------------------+------+--------------------------------------------------+
    | symbol             | attribute                 | type | explanation                                      |
    +====================+===========================+======+==================================================+
    | :math:`P_{out}(t)` | `flow[n,o,p,t]`           | V    | Outflow of converter                             |
    +--------------------+---------------------------+------+--------------------------------------------------+
    | :math:`P_{in}(t)`  | `flow[i,n,p,t]`           | V    | Inflow of converter                              |
    +--------------------+---------------------------+------+--------------------------------------------------+
    | :math:`Y(t)`       |                           | V    | Binary status variable of nonconvex outflow      |
    +--------------------+---------------------------+------+--------------------------------------------------+
    | :math:`P_{nom}(t)` |                           | V    | Nominal value (max. capacity) of the outflow     |
    +--------------------+---------------------------+------+--------------------------------------------------+
    | :math:`C_1(t)`     | `coefficients[o][1][n,t]` | P    | Linear coefficient 1 (slope)                     |
    +--------------------+---------------------------+------+--------------------------------------------------+
    | :math:`C_0(t)`     | `coefficients[o][0][n,t]` | P    | Linear coefficient 0 (y-intersection)/P_{nom}(t) |
    +--------------------+---------------------------+------+--------------------------------------------------+

    Note that :math:`P_{nom}(t) \cdot Y(t)` is merged into one variable,
    called `status_nominal[n, o, p, t]`.
    """  # noqa: E501

    CONSTRAINT_GROUP = True

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

    def _create(self, group=None):
        """Creates the relation for the class:`OffsetConverter`.

        Parameters
        ----------
        group : list
            List of oemof.solph.experimental.OffsetConverter objects for
            which the relation of inputs and outputs is created
            e.g. group = [ostf1, ostf2, ostf3, ...]. The components inside
            the list need to hold an attribute `coefficients` of type dict
            containing the conversion factors for all inputs to outputs.
        """
        if group is None:
            return None

        m = self.parent_block()

        self.OFFSETCONVERTERS = Set(initialize=[n for n in group])

        reference_node = {n: n._reference_node for n in group}
        reference_node_at_input = {
            n: n._reference_node_at_input for n in group
        }
        in_flows = {
            n: [i for i in n.inputs.keys() if i != n._reference_node]
            for n in group
        }
        out_flows = {
            n: [o for o in n.outputs.keys() if o != n._reference_node]
            for n in group
        }

        self.relation = Constraint(
            [
                (n, reference_node[n], f, p, t)
                for p, t in m.TIMEINDEX
                for n in group
                for f in in_flows[n] + out_flows[n]
            ],
            noruleinit=True,
        )

        def _relation_rule(block):
            """Link binary input and output flow to component outflow."""
            for p, t in m.TIMEINDEX:
                for n in group:

                    if reference_node_at_input[n]:
                        ref_flow = m.flow[reference_node[n], n, p, t]
                        status_nominal_idx = reference_node[n], n, t
                    else:
                        ref_flow = m.flow[n, reference_node[n], p, t]
                        status_nominal_idx = n, reference_node[n], t

                    if hasattr(m.NonConvexFlowBlock, "status_nominal"):
                        status_nominal = m.NonConvexFlowBlock.status_nominal

                    if hasattr(m, "InvestNonConvexFlowBlock"):
                        if hasattr(
                            m.InvestNonConvexFlowBlock, "status_nominal"
                        ):
                            if (
                                status_nominal_idx
                                in m.InvestNonConvexFlowBlock.status_nominal
                            ):
                                status_nominal = (
                                    m.InvestNonConvexFlowBlock.status_nominal
                                )

                    ref_status_nominal = status_nominal[status_nominal_idx]

                    for f in in_flows[n] + out_flows[n]:
                        rhs = 0
                        if f in in_flows[n]:
                            rhs += m.flow[f, n, p, t]
                        else:
                            rhs += m.flow[n, f, p, t]

                        lhs = 0
                        lhs += ref_flow * n.conversion_factors[f][t]
                        lhs += ref_status_nominal * n.normed_offsets[f][t]
                        block.relation.add(
                            (n, reference_node[n], f, p, t), (lhs == rhs)
                        )

        self.relation_build = BuildAction(rule=_relation_rule)


def slope_offset_from_nonconvex_input(
    max_load, min_load, eta_at_max, eta_at_min
):
    r"""Calculate the slope and the offset with max and min given for input

    The reference is the input flow here. That means, the `NonConvex` flow
    is specified at one of the input flows. The `max_load` and the `min_load`
    are the `max` and the `min` specifications for the `NonConvex` flow.
    `eta_at_max` and `eta_at_min` are the efficiency values of a different
    flow, e.g. an output, with respect to the `max_load` and `min_load`
    operation points.

    .. math::

        \text{slope} =
        \frac{
            \text{max} \cdot \eta_\text{at max}
            - \text{min} \cdot \eta_\text{at min}
        }{\text{max} - \text{min}}\\

        \text{offset} = \eta_\text{at,max} - \text{slope}

    Parameters
    ----------
    max_load : float
        Maximum load value, e.g. 1
    min_load : float
        Minimum load value, e.g. 0.5
    eta_at_max : float
        Efficiency at maximum load.
    eta_at_min : float
        Efficiency at minimum load.

    Returns
    -------
    tuple
        slope and offset

    Example
    -------
    >>> from oemof import solph
    >>> max_load = 1
    >>> min_load = 0.5
    >>> eta_at_min = 0.4
    >>> eta_at_max = 0.3

    With the input load being at 100 %, in this example, the efficiency should
    be 30 %. With the input load being at 50 %, it should be 40 %. We can
    calcualte slope and the offset which is normed to the nominal value of
    the referenced flow (in this case the input flow) always.

    >>> slope, offset = solph.components.slope_offset_from_nonconvex_input(
    ...     max_load, min_load, eta_at_max, eta_at_min
    ... )
    >>> input_flow = 10
    >>> input_flow_nominal = 10
    >>> output_flow = slope * input_flow + offset * input_flow_nominal

    We can then calculate with the `OffsetConverter` input output relation,
    what the resulting efficiency is. At max operating conditions it should be
    identical to the efficiency we put in initially. Analogously, we apply this
    to the minimal load point.

    >>> round(output_flow / input_flow, 3) == eta_at_max
    True
    >>> input_flow = 5
    >>> output_flow = slope * input_flow + offset * input_flow_nominal
    >>> round(output_flow / input_flow, 3) == eta_at_min
    True
    """
    slope = (max_load * eta_at_max - min_load * eta_at_min) / (
        max_load - min_load
    )
    offset = eta_at_max - slope
    return slope, offset


def slope_offset_from_nonconvex_output(
    max_load, min_load, eta_at_max, eta_at_min
):
    r"""Calculate the slope and the offset with max and min given for output.

    The reference is the output flow here. That means, the `NonConvex` flow
    is specified at one of the output flows. The `max_load` and the `min_load`
    are the `max` and the `min` specifications for the `NonConvex` flow.
    `eta_at_max` and `eta_at_min` are the efficiency values of a different
    flow, e.g. an input, with respect to the `max_load` and `min_load`
    operation points.

    .. math::

        \text{slope} =
        \frac{
            \frac{\text{max}}{\eta_\text{at max}}
            - \frac{\text{min}}{\eta_\text{at min}}
        }{\text{max} - \text{min}}\\

        \text{offset} = \frac{1}{\eta_\text{at,max}} - \text{slope}

    Parameters
    ----------
    max_load : float
        Maximum load value, e.g. 1
    min_load : float
        Minimum load value, e.g. 0.5
    eta_at_max : float
        Efficiency at maximum load.
    eta_at_min : float
        Efficiency at minimum load.

    Returns
    -------
    tuple
        slope and offset

    Example
    -------
    >>> from oemof import solph
    >>> max_load = 1
    >>> min_load = 0.5
    >>> eta_at_min = 0.7
    >>> eta_at_max = 0.8

    With the output load being at 100 %, in this example, the efficiency should
    be 80 %. With the input load being at 50 %, it should be 70 %. We can
    calcualte slope and the offset, which is normed to the nominal value of
    the referenced flow (in this case the output flow) always.

    >>> slope, offset = solph.components.slope_offset_from_nonconvex_output(
    ...     max_load, min_load, eta_at_max, eta_at_min
    ... )
    >>> output_flow = 10
    >>> output_flow_nominal = 10
    >>> input_flow = slope * output_flow + offset * output_flow_nominal

    We can then calculate with the `OffsetConverter` input output relation,
    what the resulting efficiency is. At max operating conditions it should be
    identical to the efficiency we put in initially. Analogously, we apply this
    to the minimal load point.

    >>> round(output_flow / input_flow, 3) == eta_at_max
    True
    >>> output_flow = 5
    >>> input_flow = slope * output_flow + offset * output_flow_nominal
    >>> round(output_flow / input_flow, 3) == eta_at_min
    True
    """
    slope = (max_load / eta_at_max - min_load / eta_at_min) / (
        max_load - min_load
    )
    offset = 1 / eta_at_max - slope
    return slope, offset

1	# -*- coding: utf-8 -
2
3	"""
4	OffsetConverter and associated individual constraints (blocks) and groupings.
5
6	SPDX-FileCopyrightText: Uwe Krien <krien@uni-bremen.de>
7	SPDX-FileCopyrightText: Simon Hilpert
8	SPDX-FileCopyrightText: Cord Kaldemeyer
9	SPDX-FileCopyrightText: Patrik Schönfeldt
10	SPDX-FileCopyrightText: FranziPl
11	SPDX-FileCopyrightText: jnnr
12	SPDX-FileCopyrightText: Stephan Günther
13	SPDX-FileCopyrightText: FabianTU
14	SPDX-FileCopyrightText: Johannes Röder
15	SPDX-FileCopyrightText: Saeed Sayadi
16	SPDX-FileCopyrightText: Johannes Kochems
17
18	SPDX-License-Identifier: MIT
19
20	"""
21
22	from warnings import warn	3✔
23
24	from oemof.network import Node	3✔
25	from pyomo.core import BuildAction	3✔
26	from pyomo.core.base.block import ScalarBlock	3✔
27	from pyomo.environ import Constraint	3✔
28	from pyomo.environ import Set	3✔
29
30	from oemof.solph._plumbing import sequence	3✔
31
32
33	class OffsetConverter(Node):	3✔
34	"""An object with one input and multiple outputs and two coefficients
35	per output to model part load behaviour.
36	The output must contain a NonConvex object.
37
38	Parameters
39	----------
40	conversion_factors : dict, (:math:`C_1(t)`)
41	Dict containing the respective bus as key and as value the parameter
42	:math:`C_1(t)`. It represents the slope of a linear equation with
43	respect to the `NonConvex` flow. The value can either be a scalar or a
44	sequence with length of time horizon for simulation.
45
46	normed_offsets : dict, (:math:`C_0(t)`)
47	Dict containing the respective bus as key and as value the parameter
48	:math:`C_0(t)`. It represents the y-intercept with respect to the
49	`NonConvex` flow divided by the `nominal_value` of the `NonConvex` flow
50	(this is for internal purposes). The value can either be a scalar or a
51	sequence with length of time horizon for simulation.
52	Notes
53	-----
54	C_1 and C_0 can be calculated as follows:
55
56	.. _OffsetConverterCoefficients-equations:
57
58	.. math::
59
60	C_1 = \\frac{(l_{max}/\\eta_{max}-l_{min}/\\eta_{min}}{l_{max}-l_{min}}
61
62	C_0 = \\frac{1}{\\eta_{max}} - C_1
63
64	Where :math:`l_{max}` and :math:`l_{min}` are the maximum and minimum
65	partload share (e.g. 1.0 and 0.5) with reference to the `NonConvex` flow
66	and :math:`\\eta_{max}` and :math:`\\eta_{min}` are the respective
67	efficiencies/conversion factors at these partloads.
68
69	The sets, variables, constraints and objective parts are created
70	* :py:class:`~oemof.solph.components._offset_converter.OffsetConverterBlock`
71
72	Examples
73	--------
74	>>> from oemof import solph
75	>>> bel = solph.buses.Bus(label='bel')
76	>>> bth = solph.buses.Bus(label='bth')
77	>>> l_nominal = 60
78	>>> l_max = 1
79	>>> l_min = 0.5
80	>>> eta_max = 0.5
81	>>> eta_min = 0.3
82	>>> c1 = (l_max / eta_max - l_min / eta_min) / (l_max - l_min)
83	>>> c0 = 1 / eta_max - c1
84	>>> ostf = solph.components.OffsetConverter(
85	... label='ostf',
86	... inputs={bel: solph.flows.Flow()},
87	... outputs={bth: solph.flows.Flow(
88	... nominal_value=l_nominal, min=l_min, max=l_max,
89	... nonconvex=solph.NonConvex())},
90	... conversion_factors={bel: c1},
91	... normed_offsets={bel: c0},
92	... )
93	>>> type(ostf)
94	<class 'oemof.solph.components._offset_converter.OffsetConverter'>
95
96	The input required to operate at minimum load, can be computed from the
97	slope and offset:
98
99	>>> input_at_min = ostf.conversion_factors[bel][0] * l_min + ostf.normed_offsets[bel][0] * l_max
100	>>> input_at_min * l_nominal
101	100.0
102
103	The same can be done for the input at nominal load:
104
105	>>> input_at_max = l_max * (ostf.conversion_factors[bel][0] + ostf.normed_offsets[bel][0])
106	>>> input_at_max * l_nominal
107	120.0
108
109	""" # noqa: E501
110
111	def __init__(	3✔
112	self,
113	inputs,
114	outputs,
115	label=None,
116	conversion_factors=None,
117	normed_offsets=None,
118	coefficients=None,
119	custom_attributes=None,
120	):
121	if custom_attributes is None:	3!
122	custom_attributes = {}	3✔
123
124	super().__init__(	3✔
125	inputs=inputs,
126	outputs=outputs,
127	label=label,
128	custom_properties=custom_attributes,
129	)
130
131	# this part is used for the transition phase from the old
132	# OffsetConverter API to the new one. It calcualtes the
133	# conversion_factors and normed_offsets from the coefficients and the
134	# outputs information on min and max.
135	if (	3✔
136	coefficients is not None
137	and conversion_factors is None
138	and normed_offsets is None
139	):
140	normed_offsets, conversion_factors = (	3✔
141	self.normed_offset_and_conversion_factors_from_coefficients(
142	coefficients
143	)
144	)
145
146	elif coefficients is not None and (	3!
147	conversion_factors is not None or normed_offsets is not None
148	):
NEW 149	msg = ""	×
NEW 150	raise TypeError(msg)	×
151
152	_reference_flow = [v for v in self.inputs.values() if v.nonconvex]	3✔
153	_reference_flow += [v for v in self.outputs.values() if v.nonconvex]	3✔
154	if len(_reference_flow) != 1:	3✔
155	raise ValueError(	3✔
156	"Exactly one flow of the `OffsetConverter` must have the "
157	"`NonConvex` attribute."
158	)
159
160	if _reference_flow[0] in self.inputs.values():	3✔
161	self._reference_node_at_input = True	3✔
162	self._reference_node = _reference_flow[0].input	3✔
163	else:
164	self._reference_node_at_input = False	3✔
165	self._reference_node = _reference_flow[0].output	3✔
166
167	_investment_node = [	3✔
168	v.input for v in self.inputs.values() if v.investment
169	]
170	_investment_node += [	3✔
171	v.output for v in self.outputs.values() if v.investment
172	]
173
174	if len(_investment_node) > 0:	3✔
175	if (	3✔
176	len(_investment_node) > 1
177	or self._reference_node != _investment_node[0]
178	):
179	raise TypeError(	3✔
180	"`Investment` attribute must be defined only for the "
181	"NonConvex flow!"
182	)
183
184	if conversion_factors is None:	3✔
185	conversion_factors = {}	3✔
186
187	if self._reference_node in conversion_factors:	3!
NEW 188	raise ValueError(	×
189	"Conversion factors cannot be specified for the `NonConvex` "
190	"flow."
191	)
192
193	self.conversion_factors = {	3✔
194	k: sequence(v) for k, v in conversion_factors.items()
195	}
196
197	missing_conversion_factor_keys = (	3✔
198	set(self.outputs) \| set(self.inputs)
199	) - set(self.conversion_factors)
200
201	for cf in missing_conversion_factor_keys:	3✔
202	self.conversion_factors[cf] = sequence(1)	3✔
203
204	if normed_offsets is None:	3✔
205	normed_offsets = {}	3✔
206
207	if self._reference_node in normed_offsets:	3!
UNCOV 208	raise ValueError(	×
209	"Normed offsets cannot be specified for the `NonConvex` flow."
210	)
211
212	self.normed_offsets = {	3✔
213	k: sequence(v) for k, v in normed_offsets.items()
214	}
215
216	missing_normed_offsets_keys = (	3✔
217	set(self.outputs) \| set(self.inputs)
218	) - set(self.normed_offsets)
219
220	for cf in missing_normed_offsets_keys:	3✔
221	self.normed_offsets[cf] = sequence(0)	3✔
222
223	def constraint_group(self):	3✔
224	return OffsetConverterBlock	3✔
225
226	def normed_offset_and_conversion_factors_from_coefficients(	3✔
227	self, coefficients
228	):
229	"""
230	Calculate slope and offset for new API from the old API coefficients.
231
232	Parameters
233	----------
234	coefficients : tuple
235	tuple holding the coefficients (offset, slope) for the old style
236	OffsetConverter.
237
238	Returns
239	-------
240	tuple
241	A tuple holding the slope and the offset for the new
242	OffsetConverter API.
243	"""
244	coefficients = tuple([sequence(i) for i in coefficients])	3✔
245	if len(coefficients) != 2:	3!
NEW 246	raise ValueError(	×
247	"Two coefficients or coefficient series have to be given."
248	)
249
250	input_bus = list(self.inputs.values())[0].input	3✔
251	for flow in self.outputs.values():	3✔
252
253	max_len = max(	3✔
254	len(flow.max),
255	len(flow.min),
256	len(coefficients[0]),
257	len(coefficients[1]),
258	)
259
260	# this could by vectorized, but since it is an API compatibility
261	# fix I will not do this here
262	eta_at_max = sequence(0)	3✔
263	eta_at_min = sequence(0)	3✔
264	slope = []	3✔
265	offset = []	3✔
266	for i in range(max_len):	3✔
267	eta_at_max = (	3✔
268	flow.max[i]
269	* coefficients[1][i]
270	/ (flow.max[i] - coefficients[0][i])
271	)
272	eta_at_min = (	3✔
273	flow.min[i]
274	* coefficients[1][i]
275	/ (flow.min[i] - coefficients[0][i])
276	)
277
278	c0, c1 = slope_offset_from_nonconvex_output(	3✔
279	flow.max[i], flow.min[i], eta_at_max, eta_at_min
280	)
281	slope += [c0]	3✔
282	offset += [c1]	3✔
283
284	# apparently, when coefficients are given as a list, it is assumed,
285	# that the list identical in length to the timeindex
286	# There should be a general check, if lenghts match then!
287	if max_len == 1:	3!
288	slope = sequence(slope[0])	3✔
289	offset = sequence(offset[0])	3✔
290
291	conversion_factors = {input_bus: slope}	3✔
292	normed_offsets = {input_bus: offset}	3✔
293	msg = (	3✔
294	"The usage of coefficients is depricated, use "
295	"conversion_factors and normed_offsets instead."
296	)
297	warn(msg, DeprecationWarning)	3✔
298
299	return normed_offsets, conversion_factors	3✔
300
301
302	# --- BEGIN: To be removed for versions >= v0.6 ---
303	class OffsetTransformer(OffsetConverter):	3✔
304	def __init__(	3✔
305	self,
306	inputs,
307	outputs,
308	label=None,
309	conversion_factors=None,
310	normed_offsets=None,
311	custom_attributes=None,
312	):
313	super().__init__(	3✔
314	label=label,
315	inputs=inputs,
316	outputs=outputs,
317	conversion_factors=conversion_factors,
318	normed_offsets=normed_offsets,
319	custom_attributes=custom_attributes,
320	)
321	warn(	3✔
322	"solph.components.OffsetTransformer has been renamed to"
323	" solph.components.OffsetConverter. The transitional wrapper"
324	" will be deleted in the future.",
325	FutureWarning,
326	)
327
328
329	# --- END ---
330
331
332	class OffsetConverterBlock(ScalarBlock):	3✔
333	r"""Block for the relation of nodes with type
334	:class:`~oemof.solph.components._offset_converter.OffsetConverter`
335
336	The following constraints are created:
337
338	.. _OffsetConverter-equations:
339
340	.. math::
341	&
342	P_{out}(p, t) = P_{in}(p, t) \cdot C_1(t) + P_nom(p) \cdot Y(t) \cdot C_0(t) \\
343
344
345	The symbols used are defined as follows (with Variables (V) and Parameters (P)):
346
347	+--------------------+---------------------------+------+--------------------------------------------------+
348	\| symbol \| attribute \| type \| explanation \|
349	+====================+===========================+======+==================================================+
350	\| :math:`P_{out}(t)` \| `flow[n,o,p,t]` \| V \| Outflow of converter \|
351	+--------------------+---------------------------+------+--------------------------------------------------+
352	\| :math:`P_{in}(t)` \| `flow[i,n,p,t]` \| V \| Inflow of converter \|
353	+--------------------+---------------------------+------+--------------------------------------------------+
354	\| :math:`Y(t)` \| \| V \| Binary status variable of nonconvex outflow \|
355	+--------------------+---------------------------+------+--------------------------------------------------+
356	\| :math:`P_{nom}(t)` \| \| V \| Nominal value (max. capacity) of the outflow \|
357	+--------------------+---------------------------+------+--------------------------------------------------+
358	\| :math:`C_1(t)` \| `coefficients[o][1][n,t]` \| P \| Linear coefficient 1 (slope) \|
359	+--------------------+---------------------------+------+--------------------------------------------------+
360	\| :math:`C_0(t)` \| `coefficients[o][0][n,t]` \| P \| Linear coefficient 0 (y-intersection)/P_{nom}(t) \|
361	+--------------------+---------------------------+------+--------------------------------------------------+
362
363	Note that :math:`P_{nom}(t) \cdot Y(t)` is merged into one variable,
364	called `status_nominal[n, o, p, t]`.
365	""" # noqa: E501
366
367	CONSTRAINT_GROUP = True	3✔
368
369	def __init__(self, args, *kwargs):	3✔
370	super().__init__(args, *kwargs)	3✔
371
372	def _create(self, group=None):	3✔
373	"""Creates the relation for the class:`OffsetConverter`.
374
375	Parameters
376	----------
377	group : list
378	List of oemof.solph.experimental.OffsetConverter objects for
379	which the relation of inputs and outputs is created
380	e.g. group = [ostf1, ostf2, ostf3, ...]. The components inside
381	the list need to hold an attribute `coefficients` of type dict
382	containing the conversion factors for all inputs to outputs.
383	"""
384	if group is None:	3!
385	return None	×
386
387	m = self.parent_block()	3✔
388
389	self.OFFSETCONVERTERS = Set(initialize=[n for n in group])	3✔
390
391	reference_node = {n: n._reference_node for n in group}	3✔
392	reference_node_at_input = {	3✔
393	n: n._reference_node_at_input for n in group
394	}
395	in_flows = {	3✔
396	n: [i for i in n.inputs.keys() if i != n._reference_node]
397	for n in group
398	}
399	out_flows = {	3✔
400	n: [o for o in n.outputs.keys() if o != n._reference_node]
401	for n in group
402	}
403
404	self.relation = Constraint(	3✔
405	[
406	(n, reference_node[n], f, p, t)
407	for p, t in m.TIMEINDEX
408	for n in group
409	for f in in_flows[n] + out_flows[n]
410	],
411	noruleinit=True,
412	)
413
414	def _relation_rule(block):	3✔
415	"""Link binary input and output flow to component outflow."""
416	for p, t in m.TIMEINDEX:	3✔
417	for n in group:	3✔
418
419	if reference_node_at_input[n]:	3✔
420	ref_flow = m.flow[reference_node[n], n, p, t]	3✔
421	status_nominal_idx = reference_node[n], n, t	3✔
422	else:
423	ref_flow = m.flow[n, reference_node[n], p, t]	3✔
424	status_nominal_idx = n, reference_node[n], t	3✔
425
426	if hasattr(m.NonConvexFlowBlock, "status_nominal"):	3✔
427	status_nominal = m.NonConvexFlowBlock.status_nominal	3✔
428
429	if hasattr(m, "InvestNonConvexFlowBlock"):	3!
430	if hasattr(	3✔
431	m.InvestNonConvexFlowBlock, "status_nominal"
432	):
433	if (	3!
434	status_nominal_idx
435	in m.InvestNonConvexFlowBlock.status_nominal
436	):
437	status_nominal = (	3✔
438	m.InvestNonConvexFlowBlock.status_nominal
439	)
440
441	ref_status_nominal = status_nominal[status_nominal_idx]	3✔
442
443	for f in in_flows[n] + out_flows[n]:	3✔
444	rhs = 0	3✔
445	if f in in_flows[n]:	3✔
446	rhs += m.flow[f, n, p, t]	3✔
447	else:
448	rhs += m.flow[n, f, p, t]	3✔
449
450	lhs = 0	3✔
451	lhs += ref_flow * n.conversion_factors[f][t]	3✔
452	lhs += ref_status_nominal * n.normed_offsets[f][t]	3✔
453	block.relation.add(	3✔
454	(n, reference_node[n], f, p, t), (lhs == rhs)
455	)
456
457	self.relation_build = BuildAction(rule=_relation_rule)	3✔
458
459
460	def slope_offset_from_nonconvex_input(	3✔
461	max_load, min_load, eta_at_max, eta_at_min
462	):
463	r"""Calculate the slope and the offset with max and min given for input
464
465	The reference is the input flow here. That means, the `NonConvex` flow
466	is specified at one of the input flows. The `max_load` and the `min_load`
467	are the `max` and the `min` specifications for the `NonConvex` flow.
468	`eta_at_max` and `eta_at_min` are the efficiency values of a different
469	flow, e.g. an output, with respect to the `max_load` and `min_load`
470	operation points.
471
472	.. math::
473
474	\text{slope} =
475	\frac{
476	\text{max} \cdot \eta_\text{at max}
477	- \text{min} \cdot \eta_\text{at min}
478	}{\text{max} - \text{min}}\\
479
480	\text{offset} = \eta_\text{at,max} - \text{slope}
481
482	Parameters
483	----------
484	max_load : float
485	Maximum load value, e.g. 1
486	min_load : float
487	Minimum load value, e.g. 0.5
488	eta_at_max : float
489	Efficiency at maximum load.
490	eta_at_min : float
491	Efficiency at minimum load.
492
493	Returns
494	-------
495	tuple
496	slope and offset
497
498	Example
499	-------
500	>>> from oemof import solph
501	>>> max_load = 1
502	>>> min_load = 0.5
503	>>> eta_at_min = 0.4
504	>>> eta_at_max = 0.3
505
506	With the input load being at 100 %, in this example, the efficiency should
507	be 30 %. With the input load being at 50 %, it should be 40 %. We can
508	calcualte slope and the offset which is normed to the nominal value of
509	the referenced flow (in this case the input flow) always.
510
511	>>> slope, offset = solph.components.slope_offset_from_nonconvex_input(
512	... max_load, min_load, eta_at_max, eta_at_min
513	... )
514	>>> input_flow = 10
515	>>> input_flow_nominal = 10
516	>>> output_flow = slope * input_flow + offset * input_flow_nominal
517
518	We can then calculate with the `OffsetConverter` input output relation,
519	what the resulting efficiency is. At max operating conditions it should be
520	identical to the efficiency we put in initially. Analogously, we apply this
521	to the minimal load point.
522
523	>>> round(output_flow / input_flow, 3) == eta_at_max
524	True
525	>>> input_flow = 5
526	>>> output_flow = slope * input_flow + offset * input_flow_nominal
527	>>> round(output_flow / input_flow, 3) == eta_at_min
528	True
529	"""
530	slope = (max_load * eta_at_max - min_load * eta_at_min) / (	3✔
531	max_load - min_load
532	)
533	offset = eta_at_max - slope	3✔
534	return slope, offset	3✔
535
536
537	def slope_offset_from_nonconvex_output(	3✔
538	max_load, min_load, eta_at_max, eta_at_min
539	):
540	r"""Calculate the slope and the offset with max and min given for output.
541
542	The reference is the output flow here. That means, the `NonConvex` flow
543	is specified at one of the output flows. The `max_load` and the `min_load`
544	are the `max` and the `min` specifications for the `NonConvex` flow.
545	`eta_at_max` and `eta_at_min` are the efficiency values of a different
546	flow, e.g. an input, with respect to the `max_load` and `min_load`
547	operation points.
548
549	.. math::
550
551	\text{slope} =
552	\frac{
553	\frac{\text{max}}{\eta_\text{at max}}
554	- \frac{\text{min}}{\eta_\text{at min}}
555	}{\text{max} - \text{min}}\\
556
557	\text{offset} = \frac{1}{\eta_\text{at,max}} - \text{slope}
558
559	Parameters
560	----------
561	max_load : float
562	Maximum load value, e.g. 1
563	min_load : float
564	Minimum load value, e.g. 0.5
565	eta_at_max : float
566	Efficiency at maximum load.
567	eta_at_min : float
568	Efficiency at minimum load.
569
570	Returns
571	-------
572	tuple
573	slope and offset
574
575	Example
576	-------
577	>>> from oemof import solph
578	>>> max_load = 1
579	>>> min_load = 0.5
580	>>> eta_at_min = 0.7
581	>>> eta_at_max = 0.8
582
583	With the output load being at 100 %, in this example, the efficiency should
584	be 80 %. With the input load being at 50 %, it should be 70 %. We can
585	calcualte slope and the offset, which is normed to the nominal value of
586	the referenced flow (in this case the output flow) always.
587
588	>>> slope, offset = solph.components.slope_offset_from_nonconvex_output(
589	... max_load, min_load, eta_at_max, eta_at_min
590	... )
591	>>> output_flow = 10
592	>>> output_flow_nominal = 10
593	>>> input_flow = slope * output_flow + offset * output_flow_nominal
594
595	We can then calculate with the `OffsetConverter` input output relation,
596	what the resulting efficiency is. At max operating conditions it should be
597	identical to the efficiency we put in initially. Analogously, we apply this
598	to the minimal load point.
599
600	>>> round(output_flow / input_flow, 3) == eta_at_max
601	True
602	>>> output_flow = 5
603	>>> input_flow = slope * output_flow + offset * output_flow_nominal
604	>>> round(output_flow / input_flow, 3) == eta_at_min
605	True
606	"""
607	slope = (max_load / eta_at_max - min_load / eta_at_min) / (	3✔
608	max_load - min_load
609	)
610	offset = 1 / eta_at_max - slope	3✔
611	return slope, offset	3✔

oemof / oemof-solph / 9399721029

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous