10614570495

Committed 29 Aug 2024 11:59AM UTC coverage: 95.732% (+7.1%) from 88.63%

Build # 10614570495

Build Type

Pull #1120

github

Committed by

p-snft

Commit Message

Add v0.5.5 release date

Pull Request Pull Request #1120: Merge revision/include v0 5 fixes

Run Details

1354 of 1436 branches covered (94.29%)

Branch coverage included in aggregate %.

54 of 54 new or added lines in 6 files covered. (100.0%)

19 existing lines in 5 files now uncovered.

2683 of 2781 relevant lines covered (96.48%)

2.89 hits per line

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

97.37

/src/oemof/solph/_energy_system.py

# -*- coding: utf-8 -*-

"""
solph version of oemof.network.energy_system

SPDX-FileCopyrightText: Uwe Krien <krien@uni-bremen.de>
SPDX-FileCopyrightText: Simon Hilpert
SPDX-FileCopyrightText: Cord Kaldemeyer
SPDX-FileCopyrightText: Stephan Günther
SPDX-FileCopyrightText: Birgit Schachler
SPDX-FileCopyrightText: Johannes Kochems

SPDX-License-Identifier: MIT

"""

import calendar
import datetime
import warnings

import numpy as np
import pandas as pd
from oemof.network import energy_system as es
from oemof.tools import debugging


class EnergySystem(es.EnergySystem):
    """A variant of the class EnergySystem from
    <oemof.network.network.energy_system.EnergySystem> specially tailored to
    solph.

    In order to work in tandem with solph, instances of this class always use
    solph.GROUPINGS <oemof.solph.GROUPINGS>. If custom groupings are
    supplied via the `groupings` keyword argument, solph.GROUPINGS
    <oemof.solph.GROUPINGS> is prepended to those.

    If you know what you are doing and want to use solph without
    solph.GROUPINGS <oemof.solph.GROUPINGS>, you can just use
    EnergySystem <oemof.network.network.energy_system.EnergySystem>` of
    oemof.network directly.

    Parameters
    ----------
    timeindex : pandas.DatetimeIndex

    timeincrement : iterable

    infer_last_interval : bool
        Add an interval to the last time point. The end time of this interval
        is unknown so it does only work for an equidistant DatetimeIndex with
        a 'freq' attribute that is not None. The parameter has no effect on the
        timeincrement parameter.

    periods : list or None
        The periods of a multi-period model.
        If this is explicitly specified, it leads to creating a multi-period
        model, providing a respective user warning as a feedback.

        list of pd.date_range objects carrying the timeindex for the
        respective period;

        For a standard model, periods are not (to be) declared, i.e. None.
        A list with one entry is derived, i.e. [0].

    use_remaining_value : bool
        If True, compare the remaining value of an investment to the
        original value (only applicable for multi-period models)

    kwargs
    """

    def __init__(
        self,
        timeindex=None,
        timeincrement=None,
        infer_last_interval=None,
        periods=None,
        use_remaining_value=False,
        groupings=None,
    ):
        # Doing imports at runtime is generally frowned upon, but should work
        # for now. See the TODO in :func:`constraint_grouping
        # <oemof.solph.groupings.constraint_grouping>` for more information.
        from oemof.solph import GROUPINGS

        if groupings is None:
            groupings = []
        groupings = GROUPINGS + groupings

        if not (
            isinstance(timeindex, pd.DatetimeIndex)
            or isinstance(timeindex, type(None))
        ):
            msg = (
                "Parameter 'timeindex' has to be of type "
                "pandas.DatetimeIndex or NoneType and not of type {0}"
            )
            raise TypeError(msg.format(type(timeindex)))

        if infer_last_interval is None and timeindex is not None:
            msg = (
                "The default behaviour will change in future versions.\n"
                "At the moment the last interval of an equidistant time "
                "index is added implicitly by default. Set "
                "'infer_last_interval' explicitly 'True' or 'False' to avoid "
                "this warning. In future versions 'False' will be the default"
                "behaviour"
            )
            warnings.warn(msg, FutureWarning)
            infer_last_interval = True

        if infer_last_interval is True and timeindex is not None:
            # Add one time interval to the timeindex by adding one time point.
            if timeindex.freq is None:
                msg = (
                    "You cannot infer the last interval if the 'freq' "
                    "attribute of your DatetimeIndex is None. Set "
                    " 'infer_last_interval=False' or specify a DatetimeIndex "
                    "with a valid frequency."
                )
                raise AttributeError(msg)

            timeindex = timeindex.union(
                pd.date_range(
                    timeindex[-1] + timeindex.freq,
                    periods=1,
                    freq=timeindex.freq,
                )
            )

        # catch wrong combinations and infer timeincrement from timeindex.
        if timeincrement is not None and timeindex is not None:
            if periods is None:
                msg = (
                    "Specifying the timeincrement and the timeindex parameter "
                    "at the same time is not allowed since these might be "
                    "conflicting to each other."
                )
                raise AttributeError(msg)
            else:
                msg = (
                    "Ensure that your timeindex and timeincrement are "
                    "consistent."
                )
                warnings.warn(msg, debugging.ExperimentalFeatureWarning)

        elif timeindex is not None and timeincrement is None:
            df = pd.DataFrame(timeindex)
            timedelta = df.diff()
            timeincrement = timedelta / np.timedelta64(1, "h")

            # we want a series (squeeze)
            # without the first item (no delta defined for first entry)
            # but starting with index 0 (reset)
            timeincrement = timeincrement.squeeze()[1:].reset_index(drop=True)

        if timeincrement is not None and (pd.Series(timeincrement) <= 0).any():
            msg = (
                "The time increment is inconsistent. Negative values and zero "
                "are not allowed.\nThis is caused by a inconsistent "
                "timeincrement parameter or an incorrect timeindex."
            )
            raise TypeError(msg)

        super().__init__(
            groupings=groupings,
            timeindex=timeindex,
            timeincrement=timeincrement,
        )

        self.periods = periods
        if self.periods is not None:
            msg = (
                "CAUTION! You specified the 'periods' attribute for your "
                "energy system.\n This will lead to creating "
                "a multi-period optimization modeling which can be "
                "used e.g. for long-term investment modeling.\n"
                "Please be aware that the feature is experimental as of "
                "now. If you find anything suspicious or any bugs, "
                "please report them."
            )
            warnings.warn(msg, debugging.ExperimentalFeatureWarning)
            self._extract_periods_years()
            self._extract_periods_matrix()
            self._extract_end_year_of_optimization()
            self.use_remaining_value = use_remaining_value

    def _extract_periods_years(self):
        """Map years in optimization to respective period based on time indices

        Attribute `periods_years` of type list is set. It contains
        the year of the start of each period, relative to the
        start of the optimization run and starting with 0.
        """
        periods_years = [0]
        start_year = self.periods[0].min().year
        for k, v in enumerate(self.periods):
            if k >= 1:
                periods_years.append(v.min().year - start_year)

        self.periods_years = periods_years

    def _extract_periods_matrix(self):
        """Determines a matrix describing the temporal distance to each period.

        Attribute `periods_matrix` of type list np.array is set.
        Rows represent investment/commissioning periods, columns represent
        decommissioning periods. The values describe the temporal distance
        between each investment period to each decommissioning period.
        """
        periods_matrix = []
        period_years = np.array(self.periods_years)
        for v in period_years:
            row = period_years - v
            row = np.where(row < 0, 0, row)
            periods_matrix.append(row)
        self.periods_matrix = np.array(periods_matrix)

    def _extract_end_year_of_optimization(self):
        """Extract the end of the optimization in years

        Attribute `end_year_of_optimization` of int is set.
        """
        duration_last_period = self.get_period_duration(-1)
        self.end_year_of_optimization = (
            self.periods_years[-1] + duration_last_period
        )

    def get_period_duration(self, period):
        """Get duration of a period in full years

        Parameters
        ----------
        period : int
            Period for which the duration in years shall be obtained

        Returns
        -------
        int
            Duration of the period
        """
        return (
            self.periods[period].max().year
            - self.periods[period].min().year
            + 1
        )


def create_time_index(
    year: int = None,
    interval: float = 1,
    number: int = None,
    start: datetime.datetime or datetime.date = None,
):
    """
    Create a datetime index for one year.

    Notes
    -----
    To create 8760 hourly intervals for a non leap year a datetime index with
    8761 time points need to be created. So the number of time steps is always
    the number of intervals plus one.

    Parameters
    ----------
    year : int, datetime
        The year of the index. If number and start is set the year parameter is
        ignored.
    interval : float
        The time interval in hours e.g. 0.5 for 30min or 2 for a two hour
        interval (default: 1).
    number : int
        The number of time intervals. By default number is calculated to create
        an index of one year. For a shorter or longer period the number of
        intervals can be set by the user.
    start : datetime.datetime or datetime.date
        Optional start time. If start is not set, 00:00 of the first day of
        the given year is the start time.

    Examples
    --------
    >>> len(create_time_index(2014))
    8761
    >>> len(create_time_index(2012))  # leap year
    8785
    >>> len(create_time_index(2014, interval=0.5))
    17521
    >>> len(create_time_index(2014, interval=0.5, number=10))
    11
    >>> len(create_time_index(2014, number=10))
    11
    >>> str(create_time_index(2014, interval=0.5, number=10)[-1])
    '2014-01-01 05:00:00'
    >>> str(create_time_index(2014, interval=2, number=10)[-1])
    '2014-01-01 20:00:00'
    """
    if number is None:
        if calendar.isleap(year):
            hoy = 8784
        else:
            hoy = 8760
        number = round(hoy / interval)
    if start is None:
        start = f"1/1/{year}"
    try:
        time_index = pd.date_range(
            start, periods=number + 1, freq=f"{interval}h"
        )
    except ValueError:
        # Pandas <2.2 compatibility
        time_index = pd.date_range(
            start, periods=number + 1, freq=f"{interval}H"
        )
    return time_index

1	# -- coding: utf-8 --
2
3	"""
4	solph version of oemof.network.energy_system
5
6	SPDX-FileCopyrightText: Uwe Krien <krien@uni-bremen.de>
7	SPDX-FileCopyrightText: Simon Hilpert
8	SPDX-FileCopyrightText: Cord Kaldemeyer
9	SPDX-FileCopyrightText: Stephan Günther
10	SPDX-FileCopyrightText: Birgit Schachler
11	SPDX-FileCopyrightText: Johannes Kochems
12
13	SPDX-License-Identifier: MIT
14
15	"""
16
17	import calendar	3✔
18	import datetime	3✔
19	import warnings	3✔
20
21	import numpy as np	3✔
22	import pandas as pd	3✔
23	from oemof.network import energy_system as es	3✔
24	from oemof.tools import debugging	3✔
25
26
27	class EnergySystem(es.EnergySystem):	3✔
28	"""A variant of the class EnergySystem from
29	<oemof.network.network.energy_system.EnergySystem> specially tailored to
30	solph.
31
32	In order to work in tandem with solph, instances of this class always use
33	solph.GROUPINGS <oemof.solph.GROUPINGS>. If custom groupings are
34	supplied via the `groupings` keyword argument, solph.GROUPINGS
35	<oemof.solph.GROUPINGS> is prepended to those.
36
37	If you know what you are doing and want to use solph without
38	solph.GROUPINGS <oemof.solph.GROUPINGS>, you can just use
39	EnergySystem <oemof.network.network.energy_system.EnergySystem>` of
40	oemof.network directly.
41
42	Parameters
43	----------
44	timeindex : pandas.DatetimeIndex
45
46	timeincrement : iterable
47
48	infer_last_interval : bool
49	Add an interval to the last time point. The end time of this interval
50	is unknown so it does only work for an equidistant DatetimeIndex with
51	a 'freq' attribute that is not None. The parameter has no effect on the
52	timeincrement parameter.
53
54	periods : list or None
55	The periods of a multi-period model.
56	If this is explicitly specified, it leads to creating a multi-period
57	model, providing a respective user warning as a feedback.
58
59	list of pd.date_range objects carrying the timeindex for the
60	respective period;
61
62	For a standard model, periods are not (to be) declared, i.e. None.
63	A list with one entry is derived, i.e. [0].
64
65	use_remaining_value : bool
66	If True, compare the remaining value of an investment to the
67	original value (only applicable for multi-period models)
68
69	kwargs
70	"""
71
72	def __init__(	3✔
73	self,
74	timeindex=None,
75	timeincrement=None,
76	infer_last_interval=None,
77	periods=None,
78	use_remaining_value=False,
79	groupings=None,
80	):
81	# Doing imports at runtime is generally frowned upon, but should work
82	# for now. See the TODO in :func:`constraint_grouping
83	# <oemof.solph.groupings.constraint_grouping>` for more information.
84	from oemof.solph import GROUPINGS	3✔
85
86	if groupings is None:	3✔
87	groupings = []	3✔
88	groupings = GROUPINGS + groupings	3✔
89
90	if not (	3✔
91	isinstance(timeindex, pd.DatetimeIndex)
92	or isinstance(timeindex, type(None))
93	):
94	msg = (	3✔
95	"Parameter 'timeindex' has to be of type "
96	"pandas.DatetimeIndex or NoneType and not of type {0}"
97	)
98	raise TypeError(msg.format(type(timeindex)))	3✔
99
100	if infer_last_interval is None and timeindex is not None:	3✔
101	msg = (	3✔
102	"The default behaviour will change in future versions.\n"
103	"At the moment the last interval of an equidistant time "
104	"index is added implicitly by default. Set "
105	"'infer_last_interval' explicitly 'True' or 'False' to avoid "
106	"this warning. In future versions 'False' will be the default"
107	"behaviour"
108	)
109	warnings.warn(msg, FutureWarning)	3✔
110	infer_last_interval = True	3✔
111
112	if infer_last_interval is True and timeindex is not None:	3✔
113	# Add one time interval to the timeindex by adding one time point.
114	if timeindex.freq is None:	3✔
115	msg = (	3✔
116	"You cannot infer the last interval if the 'freq' "
117	"attribute of your DatetimeIndex is None. Set "
118	" 'infer_last_interval=False' or specify a DatetimeIndex "
119	"with a valid frequency."
120	)
121	raise AttributeError(msg)	3✔
122
123	timeindex = timeindex.union(	3✔
124	pd.date_range(
125	timeindex[-1] + timeindex.freq,
126	periods=1,
127	freq=timeindex.freq,
128	)
129	)
130
131	# catch wrong combinations and infer timeincrement from timeindex.
132	if timeincrement is not None and timeindex is not None:	3✔
133	if periods is None:	3✔
134	msg = (	3✔
135	"Specifying the timeincrement and the timeindex parameter "
136	"at the same time is not allowed since these might be "
137	"conflicting to each other."
138	)
139	raise AttributeError(msg)	3✔
140	else:
141	msg = (	3✔
142	"Ensure that your timeindex and timeincrement are "
143	"consistent."
144	)
145	warnings.warn(msg, debugging.ExperimentalFeatureWarning)	3✔
146
147	elif timeindex is not None and timeincrement is None:	3✔
148	df = pd.DataFrame(timeindex)	3✔
149	timedelta = df.diff()	3✔
150	timeincrement = timedelta / np.timedelta64(1, "h")	3✔
151
152	# we want a series (squeeze)
153	# without the first item (no delta defined for first entry)
154	# but starting with index 0 (reset)
155	timeincrement = timeincrement.squeeze()[1:].reset_index(drop=True)	3✔
156
157	if timeincrement is not None and (pd.Series(timeincrement) <= 0).any():	3✔
158	msg = (	3✔
159	"The time increment is inconsistent. Negative values and zero "
160	"are not allowed.\nThis is caused by a inconsistent "
161	"timeincrement parameter or an incorrect timeindex."
162	)
163	raise TypeError(msg)	3✔
164
165	super().__init__(	3✔
166	groupings=groupings,
167	timeindex=timeindex,
168	timeincrement=timeincrement,
169	)
170
171	self.periods = periods	3✔
172	if self.periods is not None:	3✔
173	msg = (	3✔
174	"CAUTION! You specified the 'periods' attribute for your "
175	"energy system.\n This will lead to creating "
176	"a multi-period optimization modeling which can be "
177	"used e.g. for long-term investment modeling.\n"
178	"Please be aware that the feature is experimental as of "
179	"now. If you find anything suspicious or any bugs, "
180	"please report them."
181	)
182	warnings.warn(msg, debugging.ExperimentalFeatureWarning)	3✔
183	self._extract_periods_years()	3✔
184	self._extract_periods_matrix()	3✔
185	self._extract_end_year_of_optimization()	3✔
186	self.use_remaining_value = use_remaining_value	3✔
187
188	def _extract_periods_years(self):	3✔
189	"""Map years in optimization to respective period based on time indices
190
191	Attribute `periods_years` of type list is set. It contains
192	the year of the start of each period, relative to the
193	start of the optimization run and starting with 0.
194	"""
195	periods_years = [0]	3✔
196	start_year = self.periods[0].min().year	3✔
197	for k, v in enumerate(self.periods):	3✔
198	if k >= 1:	3✔
199	periods_years.append(v.min().year - start_year)	3✔
200
201	self.periods_years = periods_years	3✔
202
203	def _extract_periods_matrix(self):	3✔
204	"""Determines a matrix describing the temporal distance to each period.
205
206	Attribute `periods_matrix` of type list np.array is set.
207	Rows represent investment/commissioning periods, columns represent
208	decommissioning periods. The values describe the temporal distance
209	between each investment period to each decommissioning period.
210	"""
211	periods_matrix = []	3✔
212	period_years = np.array(self.periods_years)	3✔
213	for v in period_years:	3✔
214	row = period_years - v	3✔
215	row = np.where(row < 0, 0, row)	3✔
216	periods_matrix.append(row)	3✔
217	self.periods_matrix = np.array(periods_matrix)	3✔
218
219	def _extract_end_year_of_optimization(self):	3✔
220	"""Extract the end of the optimization in years
221
222	Attribute `end_year_of_optimization` of int is set.
223	"""
224	duration_last_period = self.get_period_duration(-1)	3✔
225	self.end_year_of_optimization = (	3✔
226	self.periods_years[-1] + duration_last_period
227	)
228
229	def get_period_duration(self, period):	3✔
230	"""Get duration of a period in full years
231
232	Parameters
233	----------
234	period : int
235	Period for which the duration in years shall be obtained
236
237	Returns
238	-------
239	int
240	Duration of the period
241	"""
242	return (	3✔
243	self.periods[period].max().year
244	- self.periods[period].min().year
245	+ 1
246	)
247
248
249	def create_time_index(	3✔
250	year: int = None,
251	interval: float = 1,
252	number: int = None,
253	start: datetime.datetime or datetime.date = None,
254	):
255	"""
256	Create a datetime index for one year.
257
258	Notes
259	-----
260	To create 8760 hourly intervals for a non leap year a datetime index with
261	8761 time points need to be created. So the number of time steps is always
262	the number of intervals plus one.
263
264	Parameters
265	----------
266	year : int, datetime
267	The year of the index. If number and start is set the year parameter is
268	ignored.
269	interval : float
270	The time interval in hours e.g. 0.5 for 30min or 2 for a two hour
271	interval (default: 1).
272	number : int
273	The number of time intervals. By default number is calculated to create
274	an index of one year. For a shorter or longer period the number of
275	intervals can be set by the user.
276	start : datetime.datetime or datetime.date
277	Optional start time. If start is not set, 00:00 of the first day of
278	the given year is the start time.
279
280	Examples
281	--------
282	>>> len(create_time_index(2014))
283	8761
284	>>> len(create_time_index(2012)) # leap year
285	8785
286	>>> len(create_time_index(2014, interval=0.5))
287	17521
288	>>> len(create_time_index(2014, interval=0.5, number=10))
289	11
290	>>> len(create_time_index(2014, number=10))
291	11
292	>>> str(create_time_index(2014, interval=0.5, number=10)[-1])
293	'2014-01-01 05:00:00'
294	>>> str(create_time_index(2014, interval=2, number=10)[-1])
295	'2014-01-01 20:00:00'
296	"""
297	if number is None:	3✔
298	if calendar.isleap(year):	3✔
299	hoy = 8784	3✔
300	else:
301	hoy = 8760	3✔
302	number = round(hoy / interval)	3✔
303	if start is None:	3!
304	start = f"1/1/{year}"	3✔
305	try:	3✔
306	time_index = pd.date_range(	3✔
307	start, periods=number + 1, freq=f"{interval}h"
308	)
UNCOV 309	except ValueError:	×
310	# Pandas <2.2 compatibility
UNCOV 311	time_index = pd.date_range(	×
312	start, periods=number + 1, freq=f"{interval}H"
313	)
314	return time_index	3✔

oemof / oemof-solph / 10614570495

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