ScheduleDay: new timeseries method and interpolation options

developer/doc/ReleaseNotes/OpenStudio_Release_Notes_3_8_0_TBD.md

@@ -86,6 +86,10 @@ For a list of deprecated and removed methods, please refer to [deprecated_method
     * A number of methods have been renamed (and the old ones deprecated) to conform to the API for other `SpaceLoadInstance` / `SpaceLoadDefinition` objects
     * Mostly `getWattsperUnit` is changed to `getDesignLevel` and `getWattsperZoneFloorArea` is changed to `getPowerPerFloorArea`
     * Refer to [deprecated_methods.csv](../../ruby/deprecated_methods.csv) for the complete list
+* [#5111](https://github.com/NREL/OpenStudio/pull/5111) - ScheduleDay: new timeseries method and interpolation options
+    * The `ScheduleDay` has API-breaking changes related to setters and getters for its `Interpolate To Timestep` field. They now use `string` rather than `bool` to conform to the IDD type `\choice`
+    * The forward translator for `ScheduleDay` replaces always setting "Average" with the interpolation method stored in `Interpolate to Timestep` field
+    * A new `timeseries()` method is introduced for returning vectors of times and (interpolated) values for the given number of timesteps per hour established by the `Timestep` object; `getValue` references this vector for an interpolated value at a given time
 
 ## Minor changes and bug fixes
 

resources/model/OpenStudio.idd

@@ -4594,12 +4594,13 @@ OS:Schedule:Day,
        \type object-list
        \object-list ScheduleTypeLimitsNames
   A4, \field Interpolate to Timestep
-       \note when the interval does not match the user specified timestep a Yes choice will average between the intervals request (to
-       \note timestep resolution.  a No choice will use the interval value at the simulation timestep without regard to if it matches
-       \note the boundary or not.
+       \note when the interval does not match the user specified timestep a Average choice will average between the intervals request (to
+       \note timestep resolution. A No choice will use the interval value at the simulation timestep without regard to if it matches
+       \note the boundary or not. A Linear choice will interpolate linearly between successive values.
        \type choice
        \default No
-       \key Yes
+       \key Average
+       \key Linear
        \key No
   N1, \field Hour
        \type integer

src/energyplus/ForwardTranslator/ForwardTranslateScheduleDay.cpp

@@ -39,11 +39,7 @@ namespace energyplus {
       }
     }
 
-    if (modelObject.interpolatetoTimestep()) {
-      scheduleDay.setString(Schedule_Day_IntervalFields::InterpolatetoTimestep, "Average");
-    } else {
-      scheduleDay.setString(Schedule_Day_IntervalFields::InterpolatetoTimestep, "No");
-    }
+    scheduleDay.setString(Schedule_Day_IntervalFields::InterpolatetoTimestep, modelObject.interpolatetoTimestep());
 
     std::vector<double> values = modelObject.values();
     std::vector<openstudio::Time> times = modelObject.times();

src/energyplus/ReverseTranslator/ReverseTranslateScheduleDayInterval.cpp

@@ -50,13 +50,7 @@ namespace energyplus {
 
     s = workspaceObject.getString(Schedule_Day_IntervalFields::InterpolatetoTimestep);
     if (s) {
-      if (openstudio::istringEqual(*s, "No")) {
-        scheduleDay.setInterpolatetoTimestep(false);
-      } else if (openstudio::istringEqual(*s, "Linear")) {
-        scheduleDay.setInterpolatetoTimestep(true);
-      } else if (openstudio::istringEqual(*s, "Average")) {
-        scheduleDay.setInterpolatetoTimestep(true);
-      }
+      scheduleDay.setInterpolatetoTimestep(*s);
     }
 
     //get extensible groups

src/energyplus/Test/ScheduleRuleset_GTest.cpp

@@ -698,7 +698,7 @@ TEST_F(EnergyPlusFixture, ReverseTranslator_ScheduleYearWeekDailyToRulesetSimple
   EXPECT_EQ(0, scheduleRule.ruleIndex());
   ScheduleDay daySchedule = scheduleRule.daySchedule();
   EXPECT_EQ(daySchedule.nameString(), "occupants schedule allday1 1");
-  EXPECT_FALSE(daySchedule.interpolatetoTimestep());
+  EXPECT_EQ("No", daySchedule.interpolatetoTimestep());
   EXPECT_EQ(8u, daySchedule.values().size());
   EXPECT_TRUE(scheduleRule.applySunday());
   EXPECT_TRUE(scheduleRule.applyMonday());
@@ -864,7 +864,7 @@ TEST_F(EnergyPlusFixture, ReverseTranslator_ScheduleYearWeekDailyToRulesetComple
   EXPECT_EQ(2, scheduleRule1.ruleIndex());
   ScheduleDay daySchedule1 = scheduleRule1.daySchedule();
   EXPECT_EQ(daySchedule1.nameString(), "occupants schedule allday1 1");
-  EXPECT_FALSE(daySchedule1.interpolatetoTimestep());
+  EXPECT_EQ("No", daySchedule1.interpolatetoTimestep());
   EXPECT_EQ(8u, daySchedule1.values().size());
   EXPECT_TRUE(scheduleRule1.applySunday());
   EXPECT_TRUE(scheduleRule1.applyMonday());
@@ -888,7 +888,7 @@ TEST_F(EnergyPlusFixture, ReverseTranslator_ScheduleYearWeekDailyToRulesetComple
   EXPECT_EQ(1, scheduleRule2.ruleIndex());
   ScheduleDay daySchedule2 = scheduleRule2.daySchedule();
   EXPECT_EQ(daySchedule2.nameString(), "occupants schedule allday1 2");
-  EXPECT_FALSE(daySchedule2.interpolatetoTimestep());
+  EXPECT_EQ("No", daySchedule2.interpolatetoTimestep());
   EXPECT_EQ(8u, daySchedule2.values().size());
   EXPECT_TRUE(scheduleRule2.applySunday());
   EXPECT_TRUE(scheduleRule2.applyMonday());
@@ -912,7 +912,7 @@ TEST_F(EnergyPlusFixture, ReverseTranslator_ScheduleYearWeekDailyToRulesetComple
   EXPECT_EQ(0, scheduleRule3.ruleIndex());
   ScheduleDay daySchedule3 = scheduleRule3.daySchedule();
   EXPECT_EQ(daySchedule3.nameString(), "occupants schedule allday2 1");
-  EXPECT_FALSE(daySchedule3.interpolatetoTimestep());
+  EXPECT_EQ("No", daySchedule3.interpolatetoTimestep());
   EXPECT_EQ(8u, daySchedule3.values().size());
   EXPECT_FALSE(scheduleRule3.applySunday());
   EXPECT_FALSE(scheduleRule3.applyMonday());
@@ -1220,7 +1220,7 @@ TEST_F(EnergyPlusFixture, ReverseTranslator_ScheduleYearWeekCompactToRulesetComp
   EXPECT_EQ(2, scheduleRule1.ruleIndex());
   ScheduleDay daySchedule1 = scheduleRule1.daySchedule();
   EXPECT_EQ(daySchedule1.nameString(), "occupants schedule allday1 1");
-  EXPECT_FALSE(daySchedule1.interpolatetoTimestep());
+  EXPECT_EQ("No", daySchedule1.interpolatetoTimestep());
   EXPECT_EQ(8u, daySchedule1.values().size());
   EXPECT_TRUE(scheduleRule1.applySunday());
   EXPECT_TRUE(scheduleRule1.applyMonday());
@@ -1244,7 +1244,7 @@ TEST_F(EnergyPlusFixture, ReverseTranslator_ScheduleYearWeekCompactToRulesetComp
   EXPECT_EQ(1, scheduleRule2.ruleIndex());
   ScheduleDay daySchedule2 = scheduleRule2.daySchedule();
   EXPECT_EQ(daySchedule2.nameString(), "occupants schedule allday1 2");
-  EXPECT_FALSE(daySchedule2.interpolatetoTimestep());
+  EXPECT_EQ("No", daySchedule2.interpolatetoTimestep());
   EXPECT_EQ(8u, daySchedule2.values().size());
   EXPECT_TRUE(scheduleRule2.applySunday());
   EXPECT_TRUE(scheduleRule2.applyMonday());
@@ -1268,7 +1268,7 @@ TEST_F(EnergyPlusFixture, ReverseTranslator_ScheduleYearWeekCompactToRulesetComp
   EXPECT_EQ(0, scheduleRule3.ruleIndex());
   ScheduleDay daySchedule3 = scheduleRule3.daySchedule();
   EXPECT_EQ(daySchedule3.nameString(), "occupants schedule allday2 1");
-  EXPECT_FALSE(daySchedule3.interpolatetoTimestep());
+  EXPECT_EQ("No", daySchedule3.interpolatetoTimestep());
   EXPECT_EQ(8u, daySchedule3.values().size());
   EXPECT_FALSE(scheduleRule3.applySunday());
   EXPECT_FALSE(scheduleRule3.applyMonday());

src/model/ScheduleDay.cpp

@@ -16,6 +16,8 @@
 #include "ScheduleRuleset_Impl.hpp"
 #include "ScheduleRule.hpp"
 #include "ScheduleRule_Impl.hpp"
+#include "Timestep.hpp"
+#include "Timestep_Impl.hpp"
 
 #include "../utilities/idf/IdfExtensibleGroup.hpp"
 #include <utilities/idd/OS_Schedule_Day_FieldEnums.hxx>
@@ -25,6 +27,7 @@
 #include "../utilities/core/Assert.hpp"
 
 #include "../utilities/time/Time.hpp"
+#include "../utilities/data/TimeSeries.hpp"
 #include "../utilities/data/Vector.hpp"
 
 namespace openstudio {
@@ -115,8 +118,10 @@ namespace model {
       return !getObject<ScheduleDay>().getModelObjectTarget<ScheduleTypeLimits>(OS_Schedule_DayFields::ScheduleTypeLimitsName);
     }
 
-    bool ScheduleDay_Impl::interpolatetoTimestep() const {
-      return getBooleanFieldValue(OS_Schedule_DayFields::InterpolatetoTimestep);
+    std::string ScheduleDay_Impl::interpolatetoTimestep() const {
+      boost::optional<std::string> value = getString(OS_Schedule_DayFields::InterpolatetoTimestep, true);
+      OS_ASSERT(value);
+      return value.get();
     }
 
     bool ScheduleDay_Impl::isInterpolatetoTimestepDefaulted() const {
@@ -176,42 +181,128 @@ namespace model {
         return 0.0;
       }
 
-      std::vector<double> values = this->values();          // these are already sorted
-      std::vector<openstudio::Time> times = this->times();  // these are already sorted
+      // We'll calculate the entire day when we request a single value but that's on purpose:
+      // * We're talking about max 60 timesteps * 24 hours = 1440 points,
+      //   but realistically more often than not you'll have a timestep of 6 (our default) or 4 so 96 to 144 points. So not a lot of points
+      // * We cache the timeSeries, and,
+      // * More often than not, the use case is to do it for the entire day anyways (eg: openstudio-standards to determine occupancy schedules)
+      TimeSeries ts = this->timeSeries();
 
-      unsigned N = times.size();
+      DateTimeVector dateTimes = ts.dateTimes();
+      Vector values = ts.values();
+
+      const unsigned N = dateTimes.size();
       OS_ASSERT(values.size() == N);
 
       if (N == 0) {
         return 0.0;
       }
 
-      openstudio::Vector x(N + 2);
-      openstudio::Vector y(N + 2);
-
-      x[0] = -0.000001;
-      y[0] = 0.0;
+      Vector x(N + 2);
+      Vector y(N + 2);
+
+      x[0] = 0.0;
+      std::string interpolatetoTimestep = this->interpolatetoTimestep();
+      if (istringEqual("No", interpolatetoTimestep)) {
+        y[0] = values[0];
+      } else if (istringEqual("Average", interpolatetoTimestep)) {
+        y[0] = values[0];
+      } else if (istringEqual("Linear", interpolatetoTimestep)) {
+        y[0] = 0.0;
+      }
 
       for (unsigned i = 0; i < N; ++i) {
-        x[i + 1] = times[i].totalDays();
+        openstudio::Time t = dateTimes[i].time();
+        if (t.totalDays() == 0.0) {  // this is 00:00:00 from the next day
+          t = openstudio::Time(0, 24, 0);
+        }
+
+        x[i + 1] = t.totalDays();
         y[i + 1] = values[i];
       }
 
-      x[N + 1] = 1.000001;
-      y[N + 1] = 0.0;
+      x[N + 1] = 1.0;
+      y[N + 1] = values[N - 1];
 
-      InterpMethod interpMethod;
-      if (this->interpolatetoTimestep()) {
-        interpMethod = LinearInterp;
-      } else {
-        interpMethod = HoldNextInterp;
-      }
-
-      double result = interp(x, y, time.totalDays(), interpMethod, NoneExtrap);
+      double result = interp(x, y, time.totalDays(), HoldNextInterp, NoneExtrap);
 
       return result;
     }
 
+    openstudio::TimeSeries ScheduleDay_Impl::timeSeries() const {
+      if (!m_cachedTimeSeries) {
+
+        auto timestep = this->model().getUniqueModelObject<Timestep>();
+        int numberOfTimestepsPerHour = timestep.numberOfTimestepsPerHour();
+
+        Date startDate(Date(MonthOfYear(MonthOfYear::Jan), 1));  // this is arbitrary
+        int minutes = 60 / numberOfTimestepsPerHour;
+        DateTime startDateTime(startDate, Time(0, 0, 0));
+
+        DateTimeVector tsDateTimes;
+        for (size_t hour = 0; hour < 24; ++hour) {
+          for (size_t minute = minutes; minute <= 60; minute += minutes) {
+            if (minute == 60) {
+              openstudio::Time t(0, hour + 1, 0);
+              tsDateTimes.push_back(startDateTime + t);
+            } else {
+              openstudio::Time t(0, hour, minute);
+              tsDateTimes.push_back(startDateTime + t);
+            }
+          }
+        }
+
+        std::vector<double> values = this->values();          // these are already sorted
+        std::vector<openstudio::Time> times = this->times();  // these are already sorted
+
+        const unsigned N = times.size();
+        OS_ASSERT(values.size() == N);
+
+        TimeSeries result;
+        if (N == 0) {
+          return result;
+        }
+
+        Vector x(N + 2);
+        Vector y(N + 2);
+
+        x[0] = -0.000001;
+        y[0] = 0.0;
+
+        for (unsigned i = 0; i < N; ++i) {
+          x[i + 1] = times[i].totalSeconds();
+          y[i + 1] = values[i];
+        }
+
+        x[N + 1] = 86400.000001;
+        y[N + 1] = 0.0;
+
+        std::string interpolatetoTimestep = this->interpolatetoTimestep();
+        Vector tsValues(tsDateTimes.size());
+        for (unsigned j = 0; j < tsDateTimes.size(); ++j) {
+          openstudio::Time t = tsDateTimes[j].time();
+          if (t.totalDays() == 0.0) {  // this is 00:00:00 from the next day
+            t = openstudio::Time(0, 24, 0);
+          }
+
+          if (istringEqual("No", interpolatetoTimestep)) {
+            tsValues[j] = interp(x, y, t.totalSeconds(), HoldNextInterp, NoneExtrap);
+          } else if (istringEqual("Average", interpolatetoTimestep)) {
+            double minutes = 60.0 / numberOfTimestepsPerHour;
+            double ti = minutes * 60.0;  // total seconds of the timestep interval
+            tsValues[j] = interp(x, y, t.totalSeconds(), AverageInterp, NoneExtrap, ti);
+          } else if (istringEqual("Linear", interpolatetoTimestep)) {
+            tsValues[j] = interp(x, y, t.totalSeconds(), LinearInterp, NoneExtrap);
+          }
+        }
+
+        result = TimeSeries(tsDateTimes, tsValues, "");
+        m_cachedTimeSeries = result;
+      }
+
+      return m_cachedTimeSeries.get();
+    }
+
     bool ScheduleDay_Impl::setScheduleTypeLimits(const ScheduleTypeLimits& scheduleTypeLimits) {
       if (scheduleTypeLimits.model() != model()) {
         return false;
@@ -229,9 +320,8 @@ namespace model {
       return false;
     }
 
-    bool ScheduleDay_Impl::setInterpolatetoTimestep(bool interpolatetoTimestep) {
-      return setBooleanFieldValue(OS_Schedule_DayFields::InterpolatetoTimestep, interpolatetoTimestep);
-      ;
+    bool ScheduleDay_Impl::setInterpolatetoTimestep(const std::string& interpolatetoTimestep) {
+      return setString(OS_Schedule_DayFields::InterpolatetoTimestep, interpolatetoTimestep);
     }
 
     void ScheduleDay_Impl::resetInterpolatetoTimestep() {
@@ -369,6 +459,11 @@ namespace model {
     void ScheduleDay_Impl::clearCachedVariables() {
       m_cachedTimes.reset();
       m_cachedValues.reset();
+      m_cachedTimeSeries.reset();
+    }
+
+    void ScheduleDay_Impl::clearCachedTimeSeries() {
+      m_cachedTimeSeries.reset();
     }
 
   }  // namespace detail
@@ -394,7 +489,7 @@ namespace model {
     return getImpl<detail::ScheduleDay_Impl>()->isScheduleTypeLimitsDefaulted();
   }
 
-  bool ScheduleDay::interpolatetoTimestep() const {
+  std::string ScheduleDay::interpolatetoTimestep() const {
     return getImpl<detail::ScheduleDay_Impl>()->interpolatetoTimestep();
   }
 
@@ -414,7 +509,11 @@ namespace model {
     return getImpl<detail::ScheduleDay_Impl>()->getValue(time);
   }
 
-  bool ScheduleDay::setInterpolatetoTimestep(bool interpolatetoTimestep) {
+  openstudio::TimeSeries ScheduleDay::timeSeries() const {
+    return getImpl<detail::ScheduleDay_Impl>()->timeSeries();
+  }
+
+  bool ScheduleDay::setInterpolatetoTimestep(const std::string& interpolatetoTimestep) {
     return getImpl<detail::ScheduleDay_Impl>()->setInterpolatetoTimestep(interpolatetoTimestep);
   }
 

src/model/ScheduleDay.hpp

@@ -54,7 +54,7 @@ namespace model {
    *  inherits one from a Schedule. */
     bool isScheduleTypeLimitsDefaulted() const;
 
-    bool interpolatetoTimestep() const;
+    std::string interpolatetoTimestep() const;
 
     bool isInterpolatetoTimestepDefaulted() const;
 
@@ -66,14 +66,18 @@ namespace model {
     /// Returns a vector of values in the same order and with the same number of elements as times.
     std::vector<double> values() const;
 
-    /// Returns the value in effect at the given time.  If time is less than 0 days or greater than 1 day, 0 is returned.
+    /// Returns the value in effect at the given time.
+    /// If time is less than 0 days or greater than 1 day, 0 is returned.
     double getValue(const openstudio::Time& time) const;
 
+    /// Returns the timeseries corresponding to simulation timestep and chosen interpolation method.
+    openstudio::TimeSeries timeSeries() const;
+
     //@}
     /** @name Setters */
     //@{
 
-    bool setInterpolatetoTimestep(bool interpolatetoTimestep);
+    bool setInterpolatetoTimestep(const std::string& interpolatetoTimestep);
 
     void resetInterpolatetoTimestep();