9396502420

Committed 06 Jun 2024 07:00AM UTC coverage: 96.261% (-0.1%) from 96.371%

Build # 9396502420

Build Type

Pull #1068

github

Committed by

web-flow

Commit Message

Merge 9d51d5151 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 %.

93 of 97 new or added lines in 2 files covered. (95.88%)

1 existing line in 1 file now uncovered.

2658 of 2732 relevant lines covered (97.29%)

2.92 hits per line

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

92.96

/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]),
            )
            flow.max[max_len - 1]
            flow.min[max_len - 1]
            coefficients[0][max_len - 1]
            coefficients[1][max_len - 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!
UNCOV 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!
NEW 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	flow.max[max_len - 1]	3✔
260	flow.min[max_len - 1]	3✔
261	coefficients[0][max_len - 1]	3✔
262	coefficients[1][max_len - 1]	3✔
263
264	# this could by vectorized, but since it is an API compatibility
265	# fix I will not do this here
266	eta_at_max = sequence(0)	3✔
267	eta_at_min = sequence(0)	3✔
268	slope = []	3✔
269	offset = []	3✔
270	for i in range(max_len):	3✔
271	eta_at_max = (	3✔
272	flow.max[i]
273	* coefficients[1][i]
274	/ (flow.max[i] - coefficients[0][i])
275	)
276	eta_at_min = (	3✔
277	flow.min[i]
278	* coefficients[1][i]
279	/ (flow.min[i] - coefficients[0][i])
280	)
281
282	c0, c1 = slope_offset_from_nonconvex_output(	3✔
283	flow.max[i], flow.min[i], eta_at_max, eta_at_min
284	)
285	slope += [c0]	3✔
286	offset += [c1]	3✔
287
288	# apparently, when coefficients are given as a list, it is assumed,
289	# that the list identical in length to the timeindex
290	# There should be a general check, if lenghts match then!
291	if max_len == 1:	3!
292	slope = sequence(slope[0])	3✔
293	offset = sequence(offset[0])	3✔
294
295	conversion_factors = {input_bus: slope}	3✔
296	normed_offsets = {input_bus: offset}	3✔
297	msg = (	3✔
298	"The usage of coefficients is depricated, use "
299	"conversion_factors and normed_offsets instead."
300	)
301	warn(msg, DeprecationWarning)	3✔
302
303	return normed_offsets, conversion_factors	3✔
304
305
306	# --- BEGIN: To be removed for versions >= v0.6 ---
307	class OffsetTransformer(OffsetConverter):	3✔
308	def __init__(	3✔
309	self,
310	inputs,
311	outputs,
312	label=None,
313	conversion_factors=None,
314	normed_offsets=None,
315	custom_attributes=None,
316	):
317	super().__init__(	3✔
318	label=label,
319	inputs=inputs,
320	outputs=outputs,
321	conversion_factors=conversion_factors,
322	normed_offsets=normed_offsets,
323	custom_attributes=custom_attributes,
324	)
325	warn(	3✔
326	"solph.components.OffsetTransformer has been renamed to"
327	" solph.components.OffsetConverter. The transitional wrapper"
328	" will be deleted in the future.",
329	FutureWarning,
330	)
331
332
333	# --- END ---
334
335
336	class OffsetConverterBlock(ScalarBlock):	3✔
337	r"""Block for the relation of nodes with type
338	:class:`~oemof.solph.components._offset_converter.OffsetConverter`
339
340	The following constraints are created:
341
342	.. _OffsetConverter-equations:
343
344	.. math::
345	&
346	P_{out}(p, t) = P_{in}(p, t) \cdot C_1(t) + P_nom(p) \cdot Y(t) \cdot C_0(t) \\
347
348
349	The symbols used are defined as follows (with Variables (V) and Parameters (P)):
350
351	+--------------------+---------------------------+------+--------------------------------------------------+
352	\| symbol \| attribute \| type \| explanation \|
353	+====================+===========================+======+==================================================+
354	\| :math:`P_{out}(t)` \| `flow[n,o,p,t]` \| V \| Outflow of converter \|
355	+--------------------+---------------------------+------+--------------------------------------------------+
356	\| :math:`P_{in}(t)` \| `flow[i,n,p,t]` \| V \| Inflow of converter \|
357	+--------------------+---------------------------+------+--------------------------------------------------+
358	\| :math:`Y(t)` \| \| V \| Binary status variable of nonconvex outflow \|
359	+--------------------+---------------------------+------+--------------------------------------------------+
360	\| :math:`P_{nom}(t)` \| \| V \| Nominal value (max. capacity) of the outflow \|
361	+--------------------+---------------------------+------+--------------------------------------------------+
362	\| :math:`C_1(t)` \| `coefficients[o][1][n,t]` \| P \| Linear coefficient 1 (slope) \|
363	+--------------------+---------------------------+------+--------------------------------------------------+
364	\| :math:`C_0(t)` \| `coefficients[o][0][n,t]` \| P \| Linear coefficient 0 (y-intersection)/P_{nom}(t) \|
365	+--------------------+---------------------------+------+--------------------------------------------------+
366
367	Note that :math:`P_{nom}(t) \cdot Y(t)` is merged into one variable,
368	called `status_nominal[n, o, p, t]`.
369	""" # noqa: E501
370
371	CONSTRAINT_GROUP = True	3✔
372
373	def __init__(self, args, *kwargs):	3✔
374	super().__init__(args, *kwargs)	3✔
375
376	def _create(self, group=None):	3✔
377	"""Creates the relation for the class:`OffsetConverter`.
378
379	Parameters
380	----------
381	group : list
382	List of oemof.solph.experimental.OffsetConverter objects for
383	which the relation of inputs and outputs is created
384	e.g. group = [ostf1, ostf2, ostf3, ...]. The components inside
385	the list need to hold an attribute `coefficients` of type dict
386	containing the conversion factors for all inputs to outputs.
387	"""
388	if group is None:	3!
389	return None	×
390
391	m = self.parent_block()	3✔
392
393	self.OFFSETCONVERTERS = Set(initialize=[n for n in group])	3✔
394
395	reference_node = {n: n._reference_node for n in group}	3✔
396	reference_node_at_input = {	3✔
397	n: n._reference_node_at_input for n in group
398	}
399	in_flows = {	3✔
400	n: [i for i in n.inputs.keys() if i != n._reference_node]
401	for n in group
402	}
403	out_flows = {	3✔
404	n: [o for o in n.outputs.keys() if o != n._reference_node]
405	for n in group
406	}
407
408	self.relation = Constraint(	3✔
409	[
410	(n, reference_node[n], f, p, t)
411	for p, t in m.TIMEINDEX
412	for n in group
413	for f in in_flows[n] + out_flows[n]
414	],
415	noruleinit=True,
416	)
417
418	def _relation_rule(block):	3✔
419	"""Link binary input and output flow to component outflow."""
420	for p, t in m.TIMEINDEX:	3✔
421	for n in group:	3✔
422
423	if reference_node_at_input[n]:	3✔
424	ref_flow = m.flow[reference_node[n], n, p, t]	3✔
425	status_nominal_idx = reference_node[n], n, t	3✔
426	else:
427	ref_flow = m.flow[n, reference_node[n], p, t]	3✔
428	status_nominal_idx = n, reference_node[n], t	3✔
429
430	if hasattr(m.NonConvexFlowBlock, "status_nominal"):	3✔
431	status_nominal = m.NonConvexFlowBlock.status_nominal	3✔
432
433	if hasattr(m, "InvestNonConvexFlowBlock"):	3!
434	if hasattr(	3✔
435	m.InvestNonConvexFlowBlock, "status_nominal"
436	):
437	if (	3!
438	status_nominal_idx
439	in m.InvestNonConvexFlowBlock.status_nominal
440	):
441	status_nominal = (	3✔
442	m.InvestNonConvexFlowBlock.status_nominal
443	)
444
445	ref_status_nominal = status_nominal[status_nominal_idx]	3✔
446
447	for f in in_flows[n] + out_flows[n]:	3✔
448	rhs = 0	3✔
449	if f in in_flows[n]:	3✔
450	rhs += m.flow[f, n, p, t]	3✔
451	else:
452	rhs += m.flow[n, f, p, t]	3✔
453
454	lhs = 0	3✔
455	lhs += ref_flow * n.conversion_factors[f][t]	3✔
456	lhs += ref_status_nominal * n.normed_offsets[f][t]	3✔
457	block.relation.add(	3✔
458	(n, reference_node[n], f, p, t), (lhs == rhs)
459	)
460
461	self.relation_build = BuildAction(rule=_relation_rule)	3✔
462
463
464	def slope_offset_from_nonconvex_input(	3✔
465	max_load, min_load, eta_at_max, eta_at_min
466	):
467	r"""Calculate the slope and the offset with max and min given for input
468
469	The reference is the input flow here. That means, the `NonConvex` flow
470	is specified at one of the input flows. The `max_load` and the `min_load`
471	are the `max` and the `min` specifications for the `NonConvex` flow.
472	`eta_at_max` and `eta_at_min` are the efficiency values of a different
473	flow, e.g. an output, with respect to the `max_load` and `min_load`
474	operation points.
475
476	.. math::
477
478	\text{slope} =
479	\frac{
480	\text{max} \cdot \eta_\text{at max}
481	- \text{min} \cdot \eta_\text{at min}
482	}{\text{max} - \text{min}}\\
483
484	\text{offset} = \eta_\text{at,max} - \text{slope}
485
486	Parameters
487	----------
488	max_load : float
489	Maximum load value, e.g. 1
490	min_load : float
491	Minimum load value, e.g. 0.5
492	eta_at_max : float
493	Efficiency at maximum load.
494	eta_at_min : float
495	Efficiency at minimum load.
496
497	Returns
498	-------
499	tuple
500	slope and offset
501
502	Example
503	-------
504	>>> from oemof import solph
505	>>> max_load = 1
506	>>> min_load = 0.5
507	>>> eta_at_min = 0.4
508	>>> eta_at_max = 0.3
509
510	With the input load being at 100 %, in this example, the efficiency should
511	be 30 %. With the input load being at 50 %, it should be 40 %. We can
512	calcualte slope and the offset which is normed to the nominal value of
513	the referenced flow (in this case the input flow) always.
514
515	>>> slope, offset = solph.components.slope_offset_from_nonconvex_input(
516	... max_load, min_load, eta_at_max, eta_at_min
517	... )
518	>>> input_flow = 10
519	>>> input_flow_nominal = 10
520	>>> output_flow = slope * input_flow + offset * input_flow_nominal
521
522	We can then calculate with the `OffsetConverter` input output relation,
523	what the resulting efficiency is. At max operating conditions it should be
524	identical to the efficiency we put in initially. Analogously, we apply this
525	to the minimal load point.
526
527	>>> round(output_flow / input_flow, 3) == eta_at_max
528	True
529	>>> input_flow = 5
530	>>> output_flow = slope * input_flow + offset * input_flow_nominal
531	>>> round(output_flow / input_flow, 3) == eta_at_min
532	True
533	"""
534	slope = (	3✔
535	(max_load * eta_at_max - min_load * eta_at_min) / (max_load - min_load)
536	)
537	offset = eta_at_max - slope	3✔
538	return slope, offset	3✔
539
540
541	def slope_offset_from_nonconvex_output(	3✔
542	max_load, min_load, eta_at_max, eta_at_min
543	):
544	r"""Calculate the slope and the offset with max and min given for output.
545
546	The reference is the output flow here. That means, the `NonConvex` flow
547	is specified at one of the output flows. The `max_load` and the `min_load`
548	are the `max` and the `min` specifications for the `NonConvex` flow.
549	`eta_at_max` and `eta_at_min` are the efficiency values of a different
550	flow, e.g. an input, with respect to the `max_load` and `min_load`
551	operation points.
552
553	.. math::
554
555	\text{slope} =
556	\frac{
557	\frac{\text{max}}{\eta_\text{at max}}
558	- \frac{\text{min}}{\eta_\text{at min}}
559	}{\text{max} - \text{min}}\\
560
561	\text{offset} = \frac{1}{\eta_\text{at,max}} - \text{slope}
562
563	Parameters
564	----------
565	max_load : float
566	Maximum load value, e.g. 1
567	min_load : float
568	Minimum load value, e.g. 0.5
569	eta_at_max : float
570	Efficiency at maximum load.
571	eta_at_min : float
572	Efficiency at minimum load.
573
574	Returns
575	-------
576	tuple
577	slope and offset
578
579	Example
580	-------
581	>>> from oemof import solph
582	>>> max_load = 1
583	>>> min_load = 0.5
584	>>> eta_at_min = 0.7
585	>>> eta_at_max = 0.8
586
587	With the output load being at 100 %, in this example, the efficiency should
588	be 80 %. With the input load being at 50 %, it should be 70 %. We can
589	calcualte slope and the offset, which is normed to the nominal value of
590	the referenced flow (in this case the output flow) always.
591
592	>>> slope, offset = solph.components.slope_offset_from_nonconvex_output(
593	... max_load, min_load, eta_at_max, eta_at_min
594	... )
595	>>> output_flow = 10
596	>>> output_flow_nominal = 10
597	>>> input_flow = slope * output_flow + offset * output_flow_nominal
598
599	We can then calculate with the `OffsetConverter` input output relation,
600	what the resulting efficiency is. At max operating conditions it should be
601	identical to the efficiency we put in initially. Analogously, we apply this
602	to the minimal load point.
603
604	>>> round(output_flow / input_flow, 3) == eta_at_max
605	True
606	>>> output_flow = 5
607	>>> input_flow = slope * output_flow + offset * output_flow_nominal
608	>>> round(output_flow / input_flow, 3) == eta_at_min
609	True
610	"""
611	slope = (	3✔
612	(max_load / eta_at_max - min_load / eta_at_min) / (max_load - min_load)
613	)
614	offset = 1 / eta_at_max - slope	3✔
615	return slope, offset	3✔

oemof / oemof-solph / 9396502420

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