GCC Code Coverage Report


Directory: ./
Coverage: low: ≥ 0% medium: ≥ 75.0% high: ≥ 90.0%
Coverage Exec / Excl / Total
Lines: 100.0% 2 / 1 / 3
Functions: 100.0% 2 / 1 / 3
Branches: -% 0 / 1 / 1

src/utilities/data/TimeSeries.hpp
Line Branch Exec Source
1 /***********************************************************************************************************************
2 * OpenStudio(R), Copyright (c) Alliance for Energy Innovation, LLC.
3 * See also https://openstudio.net/license
4 ***********************************************************************************************************************/
5
6 #ifndef UTILITIES_DATA_TIMESERIES_HPP
7 #define UTILITIES_DATA_TIMESERIES_HPP
8
9 #include "../UtilitiesAPI.hpp"
10
11 #include "Vector.hpp"
12 #include "../time/Date.hpp"
13 #include "../time/Time.hpp"
14 #include "../time/DateTime.hpp"
15
16 #include <boost/optional.hpp>
17 #include <boost/function.hpp>
18
19 #include <vector>
20
21 namespace openstudio {
22
23 namespace detail {
24
25 class UTILITIES_API TimeSeries_Impl
26 {
27 public:
28 TimeSeries_Impl();
29
30 TimeSeries_Impl(const Date& startDate, const Time& intervalLength, const Vector& values, const std::string& units);
31
32 TimeSeries_Impl(const DateTime& firstReportDateTime, const Time& intervalLength, const Vector& values, const std::string& units);
33
34 TimeSeries_Impl(const DateTime& firstReportDateTime, const Vector& timeInDays, const Vector& values, const std::string& units);
35
36 TimeSeries_Impl(const DateTime& firstReportDateTime, const std::vector<double>& timeInDays, const std::vector<double>& values,
37 const std::string& units);
38
39 TimeSeries_Impl(const DateTimeVector& inDateTimes, const Vector& values, const std::string& units);
40
41 TimeSeries_Impl(const DateTime& firstReportDateTime, const std::vector<long>& timeInSeconds, const Vector& values, const std::string& units);
42
43 5222 ~TimeSeries_Impl() = default;
44
45 openstudio::OptionalTime intervalLength() const;
46
47 openstudio::DateTime firstReportDateTime() const;
48
49 openstudio::DateTime startDateTime() const;
50
51 DateTimeVector dateTimes() const;
52
53 openstudio::Vector daysFromFirstReport() const;
54
55 double daysFromFirstReport(unsigned int i) const;
56
57 std::vector<long> secondsFromFirstReport() const;
58
59 long secondsFromFirstReport(unsigned int i) const;
60
61 openstudio::Vector values() const;
62
63 double values(unsigned int i) const;
64
65 const std::string units() const;
66
67 double valueAtSecondsFromFirstReport(long secondsFromFirstReport) const;
68
69 double value(double daysFromFirstReport) const;
70
71 double value(const Time& timeFromFirstReport) const;
72
73 double value(const DateTime& dateTime) const;
74
75 Vector values(const DateTime& startDateTime, const DateTime& endDateTime) const;
76
77 double outOfRangeValue() const;
78
79 void setOutOfRangeValue(double value);
80
81 std::shared_ptr<TimeSeries_Impl> operator+(const TimeSeries_Impl& other) const;
82
83 std::shared_ptr<TimeSeries_Impl> operator-(const TimeSeries_Impl& other) const;
84
85 std::shared_ptr<TimeSeries_Impl> operator*(double d) const;
86
87 double integrate() const;
88
89 double averageValue() const;
90
91 private:
92 − REGISTER_LOGGER("utilities.TimeSeries_Impl");
93 // fully qualified first report date
94 DateTime m_firstReportDateTime;
95
96 // start date and time of time series
97 DateTime m_startDateTime;
98
99 // integer seconds from first report date time, used for quick interpolation
100 std::vector<long> m_secondsFromFirstReport;
101 Vector m_secondsFromFirstReportAsVector; // same as m_secondsFromFirstReport but stored as Vector
102 std::vector<long> m_secondsFromStart;
103
104 // values reported at m_dateTimes
105 Vector m_values;
106
107 // units of the values
108 std::string m_units;
109
110 // length of the reporting interval if known, can be used to speed up interpolation
111 OptionalTime m_intervalLength;
112
113 // value used for out of range data
114 double m_outOfRangeValue;
115
116 // true if the time series should support wrap around dates, e.g. 4/11-4/10 without specific year
117 bool m_wrapAround;
118 };
119 } // namespace detail
120
121 /** TimeSeries is a series of values each reported at a single time. We follow the EnergyPlus
122 * convention that the time reported for each value is at the end of the reporting interval. For example, if a value
123 * is measured over the interval from hour 1 (non-inclusive) to hour 2 (inclusive), that is 1 < t <= 2, and the reported
124 * value (either the average, median, min, max, etc) is determined to be 7, then the value 7 is reported at hour 2. One
125 * of the primary tasks of the TimeSeries class is to get the value of the series at an arbitrary time. For the example above,
126 * any time in the interval 1 < t <= 2 will return 7. We refer to the beginning of the first reporting interval as the
127 * startDateTime. The end of the first interval is referred to as the firstReportDateTime.
128 *
129 * Todo: add method to mark TimeSeries that represent point in time measurements rather than interval measurements
130 *
131 * Todo: add calendar to deal with Daylight Savings
132 **/
133 class UTILITIES_API TimeSeries
134 {
135 public:
136 /** @name Constructors */
137 //@{
138
139 /// Default constructor with no data.
140 TimeSeries();
141
142 /** Constructor from start date, interval length, values, and units.
143 * First reporting interval starts at 0 hours on startDate and ends at startDate + intervalLength. */
144 TimeSeries(const Date& startDate, const Time& intervalLength, const Vector& values, const std::string& units);
145
146 /** Constructor from first report date and time, interval length, values, and units.
147 * First reporting interval starts at firstReportDateTime - intervalLength and ends at firstReportDateTime. */
148 TimeSeries(const DateTime& firstReportDateTime, const Time& intervalLength, const Vector& values, const std::string& units);
149
150 /** Constructor from first report date and time, time in days, values, and units.
151 * The treatment of the time vector depends upon the value of the first element:
152 * - If timeInDays[0] == 0 then the first reporting interval starts at 0 hours on the firstReportDateTime's date and ends at firstReportDateTime.
153 * - If timeInDays[0] > 0 then the first reporting interval starts at firstReportDateTime - timeInDays[0] and ends at firstReportDateTime.
154 *
155 * An exception is thrown if:
156 * - timeInDays.size != values.size
157 * - timeInDays is not monotonically increasing
158 * - the start date and time of first reporting interval cannot be determined */
159 TimeSeries(const DateTime& firstReportDateTime, const Vector& timeInDays, const Vector& values, const std::string& units);
160
161 /** Constructor from first report date and time, time in days, values, and units.
162 * The treatment of the time vector depends upon the value of the first element:
163 * - If timeInDays[0] == 0 then the first reporting interval starts at 0 hours on the firstReportDateTime's date and ends at firstReportDateTime.
164 * - If timeInDays[0] > 0 then the first reporting interval starts at firstReportDateTime - timeInDays[0] and ends at firstReportDateTime.
165 *
166 * An exception is thrown if:
167 * - timeInDays.size != values.size
168 * - timeInDays is not monotonically increasing
169 * - the start date and time of first reporting interval cannot be determined */
170 TimeSeries(const DateTime& firstReportDateTime, const std::vector<double>& timeInDays, const std::vector<double>& values, const std::string& units);
171
172 /** Constructor from date times, values, and units.
173 * The size of the dateTimes vector determines how it is handled:
174 * - If dateTimes.size == values.size then the first reporting interval starts at 0 hours on dateTimes[0]'s date and ends at dateTimes[0].
175 * - If dateTimes.size == values.size + 1 then the first reporting interval starts at dateTimes[0] and ends at dateTimes[1].
176 *
177 * An exception is thrown if:
178 * - (timeInDays.size != values.size) and (timeInDays.size != values.size + 1)
179 * - the start date and time of first reporting interval cannot be determined */
180 // DLM: this is the constructor that would be used for point in time measurements
181 TimeSeries(const DateTimeVector& dateTimes, const Vector& values, const std::string& units);
182
183 /** Constructor from first report date and time, time in seconds, values, and units.
184 * The treatment of the time vector depends upon the value of the first element:
185 * - If timeInSeconds[0] == 0 then the first reporting interval starts at 0 hours on the firstReportDateTime's date and ends at firstReportDateTime.
186 * - If timeInSeconds[0] > 0 then the first reporting interval starts at firstReportDateTime - timeInSeconds[0] and ends at firstReportDateTime.
187 *
188 * An exception is thrown if:
189 * - timeInSeconds.size != values.size
190 * - timeInSeconds is not monotonically increasing
191 * - start date and time of first reporting interval cannot be determined */
192 TimeSeries(const DateTime& firstReportDateTime, const std::vector<long>& timeInSeconds, const Vector& values, const std::string& units);
193
194 /// Virtual destructor
195 11759 ~TimeSeries() = default;
196
197 //@}
198 /** @name Getters */
199 //@{
200
201 /// Returns the interval length if any
202 openstudio::OptionalTime intervalLength() const;
203
204 /// Returns the date and times at which values are reported, these are the end of each reporting interval
205 openstudio::DateTimeVector dateTimes() const;
206
207 /// Returns the date and time of first report value
208 openstudio::DateTime firstReportDateTime() const;
209
210 /// Returns the date and time of start value
211 openstudio::DateTime startDateTime() const;
212
213 /// Returns the vector of time in days from end of the first reporting interval
214 openstudio::Vector daysFromFirstReport() const;
215
216 /// Returns the time in days from end of the first reporting interval at index i to prevent implicit vector copy for single value
217 double daysFromFirstReport(unsigned int i) const;
218
219 /// Returns the time in seconds from end of the first reporting interval
220 std::vector<long> secondsFromFirstReport() const;
221
222 /// Return the time in seconds from end of the first reporting interval at index i to prevent implicit vector copy for single value
223 long secondsFromFirstReport(unsigned int i) const;
224
225 /// Returns the values vector
226 openstudio::Vector values() const;
227
228 /// Returns the value at index i to prevent implicit vector copy for single value
229 double values(unsigned int i) const;
230
231 /// Returns the series units as a standard string
232 const std::string units() const;
233
234 /// Get value at number of days from first report date and time
235 double value(double daysFromFirstReport) const;
236
237 /// Get value at time from first report date and time
238 double value(const Time& timeFromFirstReport) const;
239
240 /// Get value at date and time
241 double value(const DateTime& dateTime) const;
242
243 /// Get values between start and end date times
244 Vector values(const DateTime& startDateTime, const DateTime& endDateTime) const;
245
246 /// Get the value used for out of range data
247 double outOfRangeValue() const;
248
249 //@}
250 /** @name Setters */
251 //@{
252
253 /// Set the value used for out of range data, defaults to 0
254 void setOutOfRangeValue(double value);
255
256 //@}
257 /** @name Operators */
258 //@{
259
260 /// Add timeseries
261 TimeSeries operator+(const TimeSeries& other) const;
262
263 /// Subtract timeseries
264 TimeSeries operator-(const TimeSeries& other) const;
265
266 /** TimeSeries * double */
267 TimeSeries operator*(double d) const;
268
269 /** TimeSeries / double */
270 TimeSeries operator/(double d) const;
271
272 //@}
273 /** @name Analysis Functions */
274 //@{
275
276 /** Integrate the time series */
277 double integrate() const;
278
279 /** Compute the time series average value */
280 double averageValue() const;
281
282 //@}
283 private:
284 REGISTER_LOGGER("utilities.TimeSeries");
285 // constructor from impl
286 TimeSeries(std::shared_ptr<detail::TimeSeries_Impl> impl);
287
288 // pointer to impl
289 std::shared_ptr<detail::TimeSeries_Impl> m_impl;
290 };
291
292 // optional TimeSeries
293 using OptionalTimeSeries = boost::optional<TimeSeries>;
294
295 // vector of TimeSeries
296 using TimeSeriesVector = std::vector<TimeSeries>;
297
298 /** double * TimeSeries */
299 UTILITIES_API TimeSeries operator*(double d, const TimeSeries& series);
300
301 // ETH@20100910 No implementation of double/TimeSeries yet because that would change the units.
302 // We should be able to tackle double/TimeSeries after adding get/setQuantity to
303 // IdfObject.
304
305 // Helper function to add up all the TimeSeries in timeSeriesVector.
306 UTILITIES_API TimeSeries sum(const std::vector<TimeSeries>& timeSeriesVector);
307
308 /** Returns std::function pointer to sum(const std::vector<TimeSeries>&). */
309 UTILITIES_API boost::function1<TimeSeries, const std::vector<TimeSeries>&> sumTimeSeriesFunctor();
310
311 /** Evaluates functor(timeSeriesVector). For use in SWIG bindings. */
312 UTILITIES_API TimeSeries evaluateTimeSeriesFromTimeSeriesVectorFunctor(const boost::function1<TimeSeries, const std::vector<TimeSeries>&>& functor,
313 const std::vector<TimeSeries>& timeSeriesVector);
314
315 } // namespace openstudio
316
317 #endif // UTILITIES_DATA_TIMESERIES_HPP
318