7934972669

# -*- 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
    ----------
    coefficients : dict of tuples, (:math:`C_0(t)`, :math:`C_1(t)`)
        Dict of tuples containing the respective output bus as key and
        as value a tuple with the parameters :math:`C_0(t)` and :math:`C_1(t)`.
        Here, :math:`C_1(t)` represents the slope of a linear equation and
        :math:`C_0(t)` is the y-intercept devided by the `nominal_value` of the
        output flow (this is for internal purposes).

        The tuple values 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 = (l_{max}-l_{min})/(l_{max}/\eta_{max}-l_{min}/\eta_{min})

        C_0 = l_{min} \cdot (1-C_1/\eta_{min})

    Where :math:`l_{max}` and :math:`l_{min}` are the maximum and minimum
    partload share (e.g. 1.0 and 0.3) and :math:`\eta_{max}` and
    :math:`\eta_{min}` are the 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_max = 1
    >>> l_min = 0.5
    >>> eta_max = 0.5
    >>> eta_min = 0.3
    >>> c1 = (l_max-l_min)/(l_max/eta_max-l_min/eta_min)
    >>> c0 = l_min*(1-c1/eta_min)
    >>> ostf = solph.components.OffsetConverter(
    ...    label='ostf',
    ...    inputs={bel: solph.flows.Flow()},
    ...    outputs={bth: solph.flows.Flow(
    ...         nominal_value=60, min=l_min, max=l_max,
    ...         nonconvex=solph.NonConvex())},
    ...    coefficients={bth: (c0, c1)}
    ... )
    >>> type(ostf)
    <class 'oemof.solph.components._offset_converter.OffsetConverter'>
    """  # noqa: E501

    def __init__(
        self,
        inputs,
        outputs,
        label=None,
        coefficients=None,
        custom_attributes=None,
    ):
        if custom_attributes is None:
            custom_attributes = {}
        super().__init__(
            inputs=inputs,
            outputs=outputs,
            label=label,
            **custom_attributes,
        )

        if coefficients is not None:
            self.coefficients = dict()
            if isinstance(coefficients, tuple):
                # TODO: add the correct version in the message
                msg = (
                    "Passing a tuple to the keyword `coefficients` will be deprecated"
                    " in a later version. Please use a dict to specify the"
                    " corresponding output flow. The first output flow will be assumed"
                    " as target by default."
                )
                warn(msg, DeprecationWarning)
                if len(coefficients) != 2:
                    raise ValueError(
                        "Two coefficients or coefficient series have to be given."
                    )
                self.coefficients.update(
                    {
                        [k for k in self.outputs.keys()][0]: tuple(
                            [sequence(i) for i in coefficients]
                        )
                    }
                )
            elif isinstance(coefficients, dict):
                for k, v in coefficients.items():
                    if len(v) != 2:
                        raise ValueError(
                            "Two coefficients or coefficient series have to be given."
                        )
                    self.coefficients.update(
                        {k: (sequence(v[0]), sequence(v[1]))}
                    )
            else:
                raise TypeError(
                    "`coefficiencts` needs to be either dict or tuple (deprecated)."
                )

        # `OffsetConverter` always needs the `NonConvex` attribute, but the
        # `Investment` attribute is optional. If it is used, the
        # `InvestNonConvexFlow` will be used in the definition of constraints,
        # otherwise, the `NonConvexFlow` will be used.
        if len(self.outputs):
            for v in self.outputs.values():
                if not v.nonconvex:
                    raise TypeError(
                        "Output flow must have the `NonConvex` attribute!"
                    )

        # `Investment` and `NonConvex` attributes cannot be defined for the
        # input flow.
        if len(self.inputs):
            for v in self.inputs.values():
                if v.investment:
                    raise TypeError(
                        "`Investment` attribute must be defined only for the "
                        + "output flow!"
                    )
                if v.nonconvex:
                    raise TypeError(
                        "`NonConvex` attribute must be defined only for the "
                        + "output flow!"
                    )

        if len(self.inputs) > 1:
            raise ValueError(
                "Component `OffsetConverter` must not have more than 1 input!"
            )

    def constraint_group(self):
        return OffsetConverterBlock


# --- BEGIN: To be removed for versions >= v0.6 ---
class OffsetTransformer(OffsetConverter):
    def __init__(
        self,
        inputs,
        outputs,
        label=None,
        coefficients=None,
        custom_attributes=None,
    ):
        super().__init__(
            label=label,
            inputs=inputs,
            outputs=outputs,
            coefficients=coefficients,
            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])

        in_flows = {n: [i for i in n.inputs.keys()] for n in group}
        out_flows = {n: [o for o in n.outputs.keys()] for n in group}

        self.relation = Constraint(
            [
                (n, i, o, p, t)
                for p, t in m.TIMEINDEX
                for n in group
                for o in out_flows[n]
                for i in in_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:
                    for o in out_flows[n]:
                        for i in in_flows[n]:
                            expr = 0
                            expr += -m.flow[n, o, p, t]
                            expr += (
                                m.flow[i, n, p, t] * n.coefficients[o][1][t]
                            )
                            # `Y(t)` in the last term of the constraint
                            # (":math:`C_0(t) \cdot Y(t)`") is different for
                            # different cases. If both `Investment` and
                            # `NonConvex` attributes are used for the
                            # `OffsetConverter`, `Y(t)` would represent the
                            # `status_nominal[n,o,t]` in the
                            # `InvestNonConvexFlow`. But if only the
                            # `NonConvex` attribute is defined for the
                            # `OffsetConverter`, `Y(t)` would correspond to
                            # the `status_nominal[n,o,t]` in the
                            # `NonConvexFlow`.
                            try:
                                expr += (
                                    m.InvestNonConvexFlowBlock.status_nominal[
                                        n, o, t
                                    ]
                                    * n.coefficients[o][0][t]
                                )
                            # `KeyError` occurs when more than one
                            # `OffsetConverter` is defined, and in some of
                            # them only the `NonConvex` attribute is
                            # considered, while in others both `NonConvex`
                            # and `Investment` attributes are defined.
                            # `AttributeError` only occurs when the
                            # `OffsetConverter` has only the `NonConvex`
                            # attribute, and therefore,
                            # `m.InvestNonConvexFlowBlock.status_nominal`
                            # (inside the `try` block) does not exist.
                            except (KeyError, AttributeError):
                                expr += (
                                    m.NonConvexFlowBlock.status_nominal[
                                        n, o, t
                                    ]
                                    * n.coefficients[o][0][t]
                                )
                            block.relation.add((n, i, o, p, t), (expr == 0))

        self.relation_build = BuildAction(rule=_relation_rule)

1	# -*- coding: utf-8 -
2
3	"""	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	coefficients : dict of tuples, (:math:`C_0(t)`, :math:`C_1(t)`)
41	Dict of tuples containing the respective output bus as key and
42	as value a tuple with the parameters :math:`C_0(t)` and :math:`C_1(t)`.
43	Here, :math:`C_1(t)` represents the slope of a linear equation and
44	:math:`C_0(t)` is the y-intercept devided by the `nominal_value` of the
45	output flow (this is for internal purposes).
46
47	The tuple values can either be a scalar or a sequence with length
48	of time horizon for simulation.
49
50	Notes
51	-----
52	C_1 and C_0 can be calculated as follows:
53
54	.. _OffsetConverterCoefficients-equations:
55
56	.. math::
57
58	C_1 = (l_{max}-l_{min})/(l_{max}/\eta_{max}-l_{min}/\eta_{min})
59
60	C_0 = l_{min} \cdot (1-C_1/\eta_{min})
61
62	Where :math:`l_{max}` and :math:`l_{min}` are the maximum and minimum
63	partload share (e.g. 1.0 and 0.3) and :math:`\eta_{max}` and
64	:math:`\eta_{min}` are the efficiencies/conversion factors at these
65	partloads.
66
67	The sets, variables, constraints and objective parts are created
68	* :py:class:`~oemof.solph.components._offset_converter.OffsetConverterBlock`
69
70	Examples
71	--------
72	>>> from oemof import solph
73	>>> bel = solph.buses.Bus(label='bel')
74	>>> bth = solph.buses.Bus(label='bth')
75	>>> l_max = 1
76	>>> l_min = 0.5
77	>>> eta_max = 0.5
78	>>> eta_min = 0.3
79	>>> c1 = (l_max-l_min)/(l_max/eta_max-l_min/eta_min)
80	>>> c0 = l_min*(1-c1/eta_min)
81	>>> ostf = solph.components.OffsetConverter(
82	... label='ostf',
83	... inputs={bel: solph.flows.Flow()},
84	... outputs={bth: solph.flows.Flow(
85	... nominal_value=60, min=l_min, max=l_max,
86	... nonconvex=solph.NonConvex())},
87	... coefficients={bth: (c0, c1)}
88	... )
89	>>> type(ostf)
90	<class 'oemof.solph.components._offset_converter.OffsetConverter'>
91	""" # noqa: E501
92
93	def __init__(	3✔
94	self,
95	inputs,
96	outputs,
97	label=None,
98	coefficients=None,
99	custom_attributes=None,
100	):
101	if custom_attributes is None:	3!
102	custom_attributes = {}	3✔
103	super().__init__(	3✔
104	inputs=inputs,
105	outputs=outputs,
106	label=label,
107	**custom_attributes,
108	)
109
110	if coefficients is not None:	3✔
111	self.coefficients = dict()	3✔
112	if isinstance(coefficients, tuple):	3✔
113	# TODO: add the correct version in the message
114	msg = (	3✔
115	"Passing a tuple to the keyword `coefficients` will be deprecated"
116	" in a later version. Please use a dict to specify the"
117	" corresponding output flow. The first output flow will be assumed"
118	" as target by default."
119	)
120	warn(msg, DeprecationWarning)	3✔
121	if len(coefficients) != 2:	3!
NEW 122	raise ValueError(	×
123	"Two coefficients or coefficient series have to be given."
124	)
125	self.coefficients.update(	3✔
126	{
127	[k for k in self.outputs.keys()][0]: tuple(
128	[sequence(i) for i in coefficients]
129	)
130	}
131	)
132	elif isinstance(coefficients, dict):	3!
133	for k, v in coefficients.items():	3✔
134	if len(v) != 2:	3✔
135	raise ValueError(	3✔
136	"Two coefficients or coefficient series have to be given."
137	)
138	self.coefficients.update(	3✔
139	{k: (sequence(v[0]), sequence(v[1]))}
140	)
141	else:
NEW 142	raise TypeError(	×
143	"`coefficiencts` needs to be either dict or tuple (deprecated)."
144	)
145
146	# `OffsetConverter` always needs the `NonConvex` attribute, but the
147	# `Investment` attribute is optional. If it is used, the
148	# `InvestNonConvexFlow` will be used in the definition of constraints,
149	# otherwise, the `NonConvexFlow` will be used.
150	if len(self.outputs):	3✔
151	for v in self.outputs.values():	3✔
152	if not v.nonconvex:	3✔
153	raise TypeError(	3✔
154	"Output flow must have the `NonConvex` attribute!"
155	)
156
157	# `Investment` and `NonConvex` attributes cannot be defined for the
158	# input flow.
159	if len(self.inputs):	3✔
160	for v in self.inputs.values():	3✔
161	if v.investment:	3✔
162	raise TypeError(	3✔
163	"`Investment` attribute must be defined only for the "
164	+ "output flow!"
165	)
166	if v.nonconvex:	3✔
167	raise TypeError(	3✔
168	"`NonConvex` attribute must be defined only for the "
169	+ "output flow!"
170	)
171
172	if len(self.inputs) > 1:	3✔
173	raise ValueError(	3✔
174	"Component `OffsetConverter` must not have more than 1 input!"
175	)
176
177	def constraint_group(self):	3✔
178	return OffsetConverterBlock	3✔
179
180
181	# --- BEGIN: To be removed for versions >= v0.6 ---
182	class OffsetTransformer(OffsetConverter):	3✔
183	def __init__(	3✔
184	self,
185	inputs,
186	outputs,
187	label=None,
188	coefficients=None,
189	custom_attributes=None,
190	):
191	super().__init__(	3✔
192	label=label,
193	inputs=inputs,
194	outputs=outputs,
195	coefficients=coefficients,
196	custom_attributes=custom_attributes,
197	)
198	warn(	3✔
199	"solph.components.OffsetTransformer has been renamed to"
200	" solph.components.OffsetConverter. The transitional wrapper"
201	" will be deleted in the future.",
202	FutureWarning,
203	)
204
205
206	# --- END ---
207
208
209	class OffsetConverterBlock(ScalarBlock):	3✔
210	r"""Block for the relation of nodes with type
211	:class:`~oemof.solph.components._offset_converter.OffsetConverter`
212
213	The following constraints are created:
214
215	.. _OffsetConverter-equations:
216
217	.. math::
218	&
219	P_{out}(p, t) = P_{in}(p, t) \cdot C_1(t) + P_nom(p) \cdot Y(t) \cdot C_0(t) \\
220
221
222	The symbols used are defined as follows (with Variables (V) and Parameters (P)):
223
224	+--------------------+---------------------------+------+--------------------------------------------------+
225	\| symbol \| attribute \| type \| explanation \|
226	+====================+===========================+======+==================================================+
227	\| :math:`P_{out}(t)` \| `flow[n,o,p,t]` \| V \| Outflow of converter \|
228	+--------------------+---------------------------+------+--------------------------------------------------+
229	\| :math:`P_{in}(t)` \| `flow[i,n,p,t]` \| V \| Inflow of converter \|
230	+--------------------+---------------------------+------+--------------------------------------------------+
231	\| :math:`Y(t)` \| \| V \| Binary status variable of nonconvex outflow \|
232	+--------------------+---------------------------+------+--------------------------------------------------+
233	\| :math:`P_{nom}(t)` \| \| V \| Nominal value (max. capacity) of the outflow \|
234	+--------------------+---------------------------+------+--------------------------------------------------+
235	\| :math:`C_1(t)` \| `coefficients[o][1][n,t]` \| P \| Linear coefficient 1 (slope) \|
236	+--------------------+---------------------------+------+--------------------------------------------------+
237	\| :math:`C_0(t)` \| `coefficients[o][0][n,t]` \| P \| Linear coefficient 0 (y-intersection)/P_{nom}(t) \|
238	+--------------------+---------------------------+------+--------------------------------------------------+
239
240	Note that :math:`P_{nom}(t) \cdot Y(t)` is merged into one variable,
241	called `status_nominal[n, o, p, t]`.
242	""" # noqa: E501
243
244	CONSTRAINT_GROUP = True	3✔
245
246	def __init__(self, args, *kwargs):	3✔
247	super().__init__(args, *kwargs)	3✔
248
249	def _create(self, group=None):	3✔
250	"""Creates the relation for the class:`OffsetConverter`.
251
252	Parameters
253	----------
254	group : list
255	List of oemof.solph.experimental.OffsetConverter objects for
256	which the relation of inputs and outputs is created
257	e.g. group = [ostf1, ostf2, ostf3, ...]. The components inside
258	the list need to hold an attribute `coefficients` of type dict
259	containing the conversion factors for all inputs to outputs.
260	"""
261	if group is None:	3!
UNCOV 262	return None	×
263
264	m = self.parent_block()	3✔
265
266	self.OFFSETCONVERTERS = Set(initialize=[n for n in group])	3✔
267
268	in_flows = {n: [i for i in n.inputs.keys()] for n in group}	3✔
269	out_flows = {n: [o for o in n.outputs.keys()] for n in group}	3✔
270
271	self.relation = Constraint(	3✔
272	[
273	(n, i, o, p, t)
274	for p, t in m.TIMEINDEX
275	for n in group
276	for o in out_flows[n]
277	for i in in_flows[n]
278	],
279	noruleinit=True,
280	)
281
282	def _relation_rule(block):	3✔
283	"""Link binary input and output flow to component outflow."""
284	for p, t in m.TIMEINDEX:	3✔
285	for n in group:	3✔
286	for o in out_flows[n]:	3✔
287	for i in in_flows[n]:	3✔
288	expr = 0	3✔
289	expr += -m.flow[n, o, p, t]	3✔
290	expr += (	3✔
291	m.flow[i, n, p, t] * n.coefficients[o][1][t]
292	)
293	# `Y(t)` in the last term of the constraint
294	# (":math:`C_0(t) \cdot Y(t)`") is different for
295	# different cases. If both `Investment` and
296	# `NonConvex` attributes are used for the
297	# `OffsetConverter`, `Y(t)` would represent the
298	# `status_nominal[n,o,t]` in the
299	# `InvestNonConvexFlow`. But if only the
300	# `NonConvex` attribute is defined for the
301	# `OffsetConverter`, `Y(t)` would correspond to
302	# the `status_nominal[n,o,t]` in the
303	# `NonConvexFlow`.
304	try:	3✔
305	expr += (	3✔
306	m.InvestNonConvexFlowBlock.status_nominal[
307	n, o, t
308	]
309	* n.coefficients[o][0][t]
310	)
311	# `KeyError` occurs when more than one
312	# `OffsetConverter` is defined, and in some of
313	# them only the `NonConvex` attribute is
314	# considered, while in others both `NonConvex`
315	# and `Investment` attributes are defined.
316	# `AttributeError` only occurs when the
317	# `OffsetConverter` has only the `NonConvex`
318	# attribute, and therefore,
319	# `m.InvestNonConvexFlowBlock.status_nominal`
320	# (inside the `try` block) does not exist.
321	except (KeyError, AttributeError):	3✔
322	expr += (	3✔
323	m.NonConvexFlowBlock.status_nominal[
324	n, o, t
325	]
326	* n.coefficients[o][0][t]
327	)
328	block.relation.add((n, i, o, p, t), (expr == 0))	3✔
329
330	self.relation_build = BuildAction(rule=_relation_rule)	3✔

oemof / oemof-solph / 7934972669

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