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 |