ScheduleDay: new timeseries method and interpolation options

[joseph-robertson]

Pull request overview

• Fixes #5001.

A new timeSeries() method for returning vectors of times and values given the number of timesteps per hour integer from the Timestep object.

Align the OS and E+ IDDs. The "Interpolate to Timestep" field is now "No", "Average", or "Linear" (i.e., a Breaking Change). The behavior of:

• "Linear" is unchanged (i.e., still LinearInterp)
• "No" is HoldNextInterp, and
• "Average" is a new AverageInterp interpolation on schedule values given the simulation timestep

Update the FT to write the correct method, not just "Average" as it was before.

Pull Request Author

• [x] Model API Changes / Additions
• [x] Any new or modified fields have been implemented in the EnergyPlus ForwardTranslator (and ReverseTranslator as appropriate)
• [x] Model API methods are tested (in src/model/test)
• [ ] EnergyPlus ForwardTranslator Tests (in src/energyplus/Test)
• [ ] If a new object or method, added a test in NREL/OpenStudio-resources: Add Link
• [ ] If needed, added VersionTranslation rules for the objects (src/osversion/VersionTranslator.cpp)
• [ ] Verified that C# bindings built fine on Windows, partial classes used as needed, etc.
• [ ] All new and existing tests passes
• [ ] If methods have been deprecated, update rest of code to use the new methods

Labels:

• [x] If change to an IDD file, add the label IDDChange
• [x] If breaking existing API, add the label APIChange
• [x] If deemed ready, add label Pull Request - Ready for CI so that CI builds your PR

Review Checklist

This will not be exhaustively relevant to every PR.

• [ ] Perform a Code Review on GitHub
• [ ] Code Style, strip trailing whitespace, etc.
• [ ] All related changes have been implemented: model changes, model tests, FT changes, FT tests, VersionTranslation, OS App
• [ ] Labeling is ok
• [ ] If defect, verify by running develop branch and reproducing defect, then running PR and reproducing fix
• [ ] If feature, test running new feature, try creative ways to break it
• [ ] CI status: all green or justified

[eringold]

Although this PR contains an API breaking change, I believe the negative impacts should be fairly minimal. The primary API changes are:

• what ScheduleDay::getValue returns when ScheduleDay::setInterpolateToTimestep is true (which acted the same as 'Linear' in EnergyPlus, although FT would set the option to 'Average')
• change ScheduleDay::setInterpolateToTimestep to take the appropriate options to instead of a boolean

In openstudio-standards, ComStock and a few measure repos I've looked at, there are many uses of ScheduleDay::getValue, but the only uses of ScheduleDay::setInterpolateToTimestep are to set as false (with one exception, which is the use in openstudio-standards from which I identified this issue, but which I removed because it was not needed). Since the default ScheduleDay interpolation method is 'none', all the existing uses of getValue would be unaffected by these changes.

Adding the appropriate options to setInterpolateToTimestep and the Average interpolation calculation is an improvement in that it aligns the OpenStudio user experience with how EnergyPlus interprets that input, and the addition of the ScheduleDay::timeSeries method adds further utility to users in processing of schedules, such as in equivalent full-load hour calculations and parametric schedule modifications.

In short, these are good and necessary changes. Thanks @joseph-robertson!

[jmarrec]

@joseph-robertson Thanks for addressing some of the review comments.

I'm still not happy about getValue, and maybe we should open a ticket to revisit the getValue and avoid recomputing the entire day, but maybe not.

Anyways, if CI is happy with this, we can merge.

[jmarrec]

/srv/jenkins/openstudio/docker-volumes/ubuntu-2004/Openstudio/src/utilities/data/Vector.cpp:103:7: error: ‘OS_ASSERT’ was not declared in this scope; did you mean ‘BOOST_ASSERT’?

fixed in 012f076b8476fb752e849672bc1b2f1bb08f6843

[ci-commercialbuildings]

CI Results for 7493115cf7e447813cf444592b7a284837bb1a0a:

• Ubuntu 20.04:

  • OpenStudio-3.8.0-beta+7493115cf7-Ubuntu-20.04-x86_64.deb
  • OpenStudio-3.8.0-beta+7493115cf7-Ubuntu-20.04-x86_64.tar.gz

• Ubuntu 22.04:

  • OpenStudio-3.8.0-beta+7493115cf7-Ubuntu-22.04-x86_64.deb
  • OpenStudio-3.8.0-beta+7493115cf7-Ubuntu-22.04-x86_64.tar.gz

• Darwin:

  • OpenStudio-3.8.0-beta+7493115cf7-Darwin-x86_64.dmg
  • OpenStudio-3.8.0-beta+7493115cf7-Darwin-x86_64.tar.gz

• Windows:

• Code Coverage: