src/measure/OSRunner.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 MEASURE_OSRUNNER_HPP | ||
| 7 | #define MEASURE_OSRUNNER_HPP | ||
| 8 | |||
| 9 | #include "MeasureAPI.hpp" | ||
| 10 | |||
| 11 | #include "../model/Model.hpp" | ||
| 12 | |||
| 13 | #include "../utilities/filetypes/WorkflowStepResult.hpp" | ||
| 14 | #include "../utilities/idf/Workspace.hpp" | ||
| 15 | #include "../utilities/sql/SqlFile.hpp" | ||
| 16 | #include "../utilities/filetypes/EpwFile.hpp" | ||
| 17 | #include "../utilities/filetypes/WorkflowJSON.hpp" | ||
| 18 | #include "../alfalfa/AlfalfaJSON.hpp" | ||
| 19 | #include "../utilities/core/Logger.hpp" | ||
| 20 | #include "../measure/ModelicaParameters.hpp" | ||
| 21 | |||
| 22 | namespace openstudio { | ||
| 23 | |||
| 24 | class OSWorkflow; | ||
| 25 | class Workspace; | ||
| 26 | class WorkspaceObject; | ||
| 27 | |||
| 28 | namespace model { | ||
| 29 | class ModelObject; | ||
| 30 | } | ||
| 31 | |||
| 32 | namespace measure { | ||
| 33 | |||
| 34 | class OSArgument; | ||
| 35 | class OSMeasure; | ||
| 36 | |||
| 37 | /** OSRunner is a concrete base class for application-specific classes that run \link OSMeasure | ||
| 38 | * OSMeasures\endlink. */ | ||
| 39 | class MEASURE_API OSRunner | ||
| 40 | { | ||
| 41 | public: | ||
| 42 | /** @name Constructors and Destructors */ | ||
| 43 | //@{ | ||
| 44 | |||
| 45 | OSRunner(const WorkflowJSON& workflow); | ||
| 46 | |||
| 47 | virtual ~OSRunner(); | ||
| 48 | |||
| 49 | //@} | ||
| 50 | /** @name Getters and Queries */ | ||
| 51 | //@{ | ||
| 52 | |||
| 53 | /** Returns a clone of the workflow currently being run. New in OS 2.0. */ | ||
| 54 | WorkflowJSON workflow() const; | ||
| 55 | |||
| 56 | /** Returns the alfalfa json contrainer */ | ||
| 57 | alfalfa::AlfalfaJSON alfalfa() const; | ||
| 58 | |||
| 59 | /** Returns Modelica Parameters. | ||
| 60 | * This is a key/value store of parameters that will be set on a Modelica simulation */ | ||
| 61 | ModelicaParameters modelicaParameters() const; | ||
| 62 | |||
| 63 | /** Returns preferred unit system, either 'IP' or 'SI'. New in OS 2.0. */ | ||
| 64 | std::string unitsPreference() const; | ||
| 65 | |||
| 66 | /** Returns preferred language, e.g. 'en' or 'fr'. New in OS 2.0. */ | ||
| 67 | std::string languagePreference() const; | ||
| 68 | |||
| 69 | /** Returns the result for the current/last OSMeasure run by this OSRunner. (prepareForMeasureRun | ||
| 70 | * should be called prior to each run to ensure that result() corresponds to a single script, and | ||
| 71 | * is not instead a running result over multiple scripts. One way to ensure that this happens is | ||
| 72 | * to call the default version of run in ModelMeasure, etc. at the beginning of any particular | ||
| 73 | * run method.) */ | ||
| 74 | WorkflowStepResult result() const; | ||
| 75 | |||
| 76 | /** Returns true if the simulation has been halted. */ | ||
| 77 | bool halted() const; | ||
| 78 | |||
| 79 | /** Returns a copy of the last Model generated in the workflow if available. */ | ||
| 80 | boost::optional<openstudio::model::Model> lastOpenStudioModel() const; | ||
| 81 | |||
| 82 | /** Returns a copy of the last EnergyPlus Workspace generated in the workflow if available. */ | ||
| 83 | boost::optional<openstudio::Workspace> lastEnergyPlusWorkspace() const; | ||
| 84 | |||
| 85 | /** Returns a copy of the last EnergyPlus SqlFile generated in the workflow if available. */ | ||
| 86 | boost::optional<openstudio::SqlFile> lastEnergyPlusSqlFile() const; | ||
| 87 | |||
| 88 | /** Returns the path to the last Modelica result file generated in the workflow if available. */ | ||
| 89 | boost::optional<openstudio::path> lastModelicaResultPath() const; | ||
| 90 | |||
| 91 | /** Returns a copy of the last EpwFile generated in the workflow if available. */ | ||
| 92 | boost::optional<openstudio::EpwFile> lastEpwFile() const; | ||
| 93 | |||
| 94 | /** Returns a path to the last EpwFile generated in the workflow if available. */ | ||
| 95 | boost::optional<openstudio::path> lastEpwFilePath() const; | ||
| 96 | |||
| 97 | /** Tests if the given ModelObject is in the application's current selection. Base class | ||
| 98 | * implementation always returns true. */ | ||
| 99 | virtual bool inSelection(const openstudio::model::ModelObject& modelObject) const; | ||
| 100 | |||
| 101 | //@} | ||
| 102 | /** @name Actions */ | ||
| 103 | //@{ | ||
| 104 | |||
| 105 | /** Gets user input using dialog boxes, etc. Result is map of name to argument. Result is empty | ||
| 106 | * if user cancels or user did not provide values for all required arguments. Base class | ||
| 107 | * implementation simply creates a map, with no information added, from arguments. */ | ||
| 108 | virtual std::map<std::string, OSArgument> getUserInput(std::vector<OSArgument>& arguments) const; | ||
| 109 | |||
| 110 | /** Initializes OSRunner for capturing data on a particular measure. Replaces result | ||
| 111 | * with a default-constructed result, and keeps the measure name for use in log messages. | ||
| 112 | * Should be called at the beginning of every OSMeasure. Is called by the OSMeasure C++ | ||
| 113 | * classes' run methods. */ | ||
| 114 | virtual void prepareForMeasureRun(const OSMeasure& measure); | ||
| 115 | |||
| 116 | /** Registers error message with result, and sets result value to "Fail". OSMeasures | ||
| 117 | * should return false after calling this method. Workflow completed status will be set to "Fail".*/ | ||
| 118 | virtual void registerError(const std::string& message); | ||
| 119 | |||
| 120 | /** Registers warning message with result. Base class returns true. Derived classes | ||
| 121 | * may choose to present a prompt to the user. The OSMeasure should exit (return false) if | ||
| 122 | * false is returned. */ | ||
| 123 | virtual bool registerWarning(const std::string& message); | ||
| 124 | |||
| 125 | /** Registers info message with result. Base class returns true. Derived classes | ||
| 126 | * may choose to present a prompt to the user. The OSMeasure should exit (return false) if | ||
| 127 | * false is returned. */ | ||
| 128 | virtual bool registerInfo(const std::string& message); | ||
| 129 | |||
| 130 | /** Sets result value to "NA", and registers a corresponding info message. In most circumstances, | ||
| 131 | * OSMeasures should return true after calling this method. Does not affect workflow completed status.*/ | ||
| 132 | virtual void registerAsNotApplicable(const std::string& message); | ||
| 133 | |||
| 134 | /** Sets the result initial condition to message. */ | ||
| 135 | virtual void registerInitialCondition(const std::string& message); | ||
| 136 | |||
| 137 | /** Sets the result final condition to message. */ | ||
| 138 | virtual void registerFinalCondition(const std::string& message); | ||
| 139 | |||
| 140 | /** \overload Shortcut method for registering boolean attribute. */ | ||
| 141 | virtual void registerValue(const std::string& name, bool value); | ||
| 142 | /** \overload Shortcut method for registering boolean attribute. */ | ||
| 143 | virtual void registerValue(const std::string& name, const std::string& displayName, bool value); | ||
| 144 | |||
| 145 | /** \overload Shortcut method for registering double attribute. */ | ||
| 146 | virtual void registerValue(const std::string& name, double value); | ||
| 147 | /** \overload Shortcut method for registering double attribute. */ | ||
| 148 | virtual void registerValue(const std::string& name, double value, const std::string& units); | ||
| 149 | /** \overload Shortcut method for registering double attribute. */ | ||
| 150 | virtual void registerValue(const std::string& name, const std::string& displayName, double value); | ||
| 151 | /** \overload Shortcut method for registering double attribute. */ | ||
| 152 | virtual void registerValue(const std::string& name, const std::string& displayName, double value, const std::string& units); | ||
| 153 | |||
| 154 | /** \overload Shortcut method for registering int attribute */ | ||
| 155 | virtual void registerValue(const std::string& name, int value); | ||
| 156 | /** \overload Shortcut method for registering int attribute */ | ||
| 157 | virtual void registerValue(const std::string& name, int value, const std::string& units); | ||
| 158 | /** \overload Shortcut method for registering int attribute */ | ||
| 159 | virtual void registerValue(const std::string& name, const std::string& displayName, int value); | ||
| 160 | /** \overload Shortcut method for registering int attribute */ | ||
| 161 | virtual void registerValue(const std::string& name, const std::string& displayName, int value, const std::string& units); | ||
| 162 | |||
| 163 | /** \overload Shortcut method for registering string attribute */ | ||
| 164 | virtual void registerValue(const std::string& name, const std::string& value); | ||
| 165 | /** \overload Shortcut method for registering string attribute */ | ||
| 166 | virtual void registerValue(const std::string& name, const std::string& displayName, const std::string& value); | ||
| 167 | |||
| 168 | /** Halts the simulation with the provided completed status, does not set the current measure's step result. | ||
| 169 | * Measure writers can call this with "Success" if all required results have been generated. | ||
| 170 | * Measure writers should not call this with "Fail", runner.registerError should be used instead. | ||
| 171 | * Measure writers can call this with "Invalid" if the workflow requests parameter combinations that are not valid. | ||
| 172 | * Measure writers should not call this with "Cancel", this is reserved for external cancel operations. | ||
| 173 | */ | ||
| 174 | virtual void haltWorkflow(const std::string& completedStatus = "Invalid"); | ||
| 175 | |||
| 176 | /** Creates a progress bar with the text label. Base class implementation does nothing. */ | ||
| 177 | virtual void createProgressBar(const std::string& text) const; | ||
| 178 | |||
| 179 | /** Updates the progress bar to value (between 0 and 100). Base class implementation does | ||
| 180 | * nothing. */ | ||
| 181 | virtual void updateProgress(double value) const; | ||
| 182 | |||
| 183 | /** Destroys the progress bar. Base class implementation does nothing. */ | ||
| 184 | virtual void destroyProgressBar() const; | ||
| 185 | |||
| 186 | //@} | ||
| 187 | /** @name Common Error Checking Functions */ | ||
| 188 | //@{ | ||
| 189 | |||
| 190 | /** Returns true, logs no messages, and registers a value | ||
| 191 | * for each argument with a value or default value if all script_arguments are in | ||
| 192 | * user_arguments, and if all required script_arguments have been set or have defaults | ||
| 193 | * in user_arguments. Otherwise, returns false and \link registerError registers an | ||
| 194 | * error\endlink if there are any type mismatches, or if any required or defaulted | ||
| 195 | * arguments are missing (entirely, or their values are not set). All other discrepancies | ||
| 196 | * are \link registerWarning logged as warnings\endlink. */ | ||
| 197 | bool validateUserArguments(const std::vector<OSArgument>& script_arguments, const std::map<std::string, OSArgument>& user_arguments); | ||
| 198 | |||
| 199 | /** Call this method to retrieve the value of an OSArgument of type boolean that is either | ||
| 200 | * required or has a default. */ | ||
| 201 | bool getBoolArgumentValue(const std::string& argument_name, const std::map<std::string, OSArgument>& user_arguments); | ||
| 202 | |||
| 203 | /** Call this method to retrieve the value of an OSArgument of type boolean that is optional | ||
| 204 | * (not required and does not have a default). */ | ||
| 205 | boost::optional<bool> getOptionalBoolArgumentValue(const std::string& argument_name, const std::map<std::string, OSArgument>& user_arguments); | ||
| 206 | |||
| 207 | /** Call this method to retrieve the value of an OSArgument of type double that is either | ||
| 208 | * required or has a default. */ | ||
| 209 | double getDoubleArgumentValue(const std::string& argument_name, const std::map<std::string, OSArgument>& user_arguments); | ||
| 210 | |||
| 211 | /** Call this method to retrieve the value of an OSArgument of type double that is optional | ||
| 212 | * (not required and does not have a default). */ | ||
| 213 | boost::optional<double> getOptionalDoubleArgumentValue(const std::string& argument_name, const std::map<std::string, OSArgument>& user_arguments); | ||
| 214 | |||
| 215 | /** Call this method to retrieve the value of an OSArgument of type integer that is either | ||
| 216 | * required or has a default. */ | ||
| 217 | int getIntegerArgumentValue(const std::string& argument_name, const std::map<std::string, OSArgument>& user_arguments); | ||
| 218 | |||
| 219 | /** Call this method to retrieve the value of an OSArgument of type integer that is optional | ||
| 220 | * (not required and does not have a default). */ | ||
| 221 | boost::optional<int> getOptionalIntegerArgumentValue(const std::string& argument_name, const std::map<std::string, OSArgument>& user_arguments); | ||
| 222 | |||
| 223 | /** Call this method to retrieve the value of an OSArgument of type string, choice, or path | ||
| 224 | * that is either required or has a default. */ | ||
| 225 | std::string getStringArgumentValue(const std::string& argument_name, const std::map<std::string, OSArgument>& user_arguments); | ||
| 226 | |||
| 227 | /** Call this method to retrieve the value of an OSArgument of type string, choice, or path | ||
| 228 | * that is optional (not required and does not have a default). */ | ||
| 229 | boost::optional<std::string> getOptionalStringArgumentValue(const std::string& argument_name, | ||
| 230 | const std::map<std::string, OSArgument>& user_arguments); | ||
| 231 | |||
| 232 | /** Call this method to retrieve the value of an OSArgument of type path that is either | ||
| 233 | * required or has a default. */ | ||
| 234 | openstudio::path getPathArgumentValue(const std::string& argument_name, const std::map<std::string, OSArgument>& user_arguments); | ||
| 235 | |||
| 236 | /** Call this method to retrieve the value of an OSArgument of type path that is optional | ||
| 237 | * (not required and does not have a default). */ | ||
| 238 | boost::optional<openstudio::path> getOptionalPathArgumentValue(const std::string& argument_name, | ||
| 239 | const std::map<std::string, OSArgument>& user_arguments); | ||
| 240 | |||
| 241 | /** Call this method to retrieve the value of an OSArgument that was created by | ||
| 242 | * makeChoiceArgumentOfWorkspaceObjects. */ | ||
| 243 | boost::optional<openstudio::WorkspaceObject> getOptionalWorkspaceObjectChoiceValue(const std::string& argument_name, | ||
| 244 | const std::map<std::string, OSArgument>& user_arguments, | ||
| 245 | const openstudio::Workspace& workspace); | ||
| 246 | |||
| 247 | /** Call this method to retrieve the values of OSArguments of all types. | ||
| 248 | * It will call validateUserArguments for you and throw if that fails */ | ||
| 249 | Json::Value getArgumentValues(std::vector<OSArgument>& script_arguments, const std::map<std::string, OSArgument>& user_arguments); | ||
| 250 | |||
| 251 | /** Call this method to retrieve the values of all workflow steps for a given measure name. | ||
| 252 | * measureName can be: the WorkflowStep's measureDirName or name, or the WorkflowStepResult's measureName */ | ||
| 253 | Json::Value getPastStepValuesForMeasure(const std::string& measureName) const; | ||
| 254 | |||
| 255 | /** Call this method to retrieve the values of all workflow steps for a given step value name. */ | ||
| 256 | Json::Value getPastStepValuesForName(const std::string& stepName) const; | ||
| 257 | |||
| 258 | //@} | ||
| 259 | |||
| 260 | // reset the runner to re-run the workflow | ||
| 261 | void reset(); | ||
| 262 | |||
| 263 | // increments step to run next, returns true if there is another step | ||
| 264 | // should be called immediately after the last step completes | ||
| 265 | bool incrementStep(); | ||
| 266 | |||
| 267 | // supports in-memory job chaining | ||
| 268 | void setLastOpenStudioModel(const openstudio::model::Model& lastOpenStudioModel); | ||
| 269 | void resetLastOpenStudioModel(); | ||
| 270 | |||
| 271 | // clears m_lastOpenStudioModel | ||
| 272 | void setLastOpenStudioModelPath(const openstudio::path& lastOpenStudioModelPath); | ||
| 273 | void resetLastOpenStudioModelPath(); | ||
| 274 | |||
| 275 | // supports in-memory job chaining | ||
| 276 | void setLastEnergyPlusWorkspace(const openstudio::Workspace& lastEnergyPlusWorkspace); | ||
| 277 | void resetLastEnergyPlusWorkspace(); | ||
| 278 | |||
| 279 | // clears m_lastEnergyPlusWorkspace | ||
| 280 | void setLastEnergyPlusWorkspacePath(const openstudio::path& lastEnergyPlusWorkspacePath); | ||
| 281 | void resetLastEnergyPlusWorkspacePath(); | ||
| 282 | |||
| 283 | // clears m_lastEnergyPlusSqlFile | ||
| 284 | void setLastEnergyPlusSqlFilePath(const openstudio::path& lastEnergyPlusSqlFilePath); | ||
| 285 | void resetLastEnergyPlusSqlFilePath(); | ||
| 286 | |||
| 287 | void setLastModelicaResultPath(const openstudio::path& lastModelicaResultPath); | ||
| 288 | void resetLastModelicaResultPath(); | ||
| 289 | |||
| 290 | // clears m_lastEpwFilePath | ||
| 291 | void setLastEpwFilePath(const openstudio::path& lastEpwFilePath); | ||
| 292 | void resetLastEpwFilePath(); | ||
| 293 | |||
| 294 | /** Sets preferred unit system, either 'IP' or 'SI'. New in OS 2.0. */ | ||
| 295 | bool setUnitsPreference(const std::string& unitsPreference); | ||
| 296 | |||
| 297 | void resetUnitsPreference(); | ||
| 298 | |||
| 299 | /** Sets preferred language, e.g. 'en' or 'fr'. New in OS 2.0. */ | ||
| 300 | bool setLanguagePreference(const std::string& languagePreference); | ||
| 301 | |||
| 302 | void resetLanguagePreference(); | ||
| 303 | |||
| 304 | /** Whether registerInfo, registerWarning, registerError, registerInitialCondition, registerFinalCondition and registerAsNotApplicable | ||
| 305 | * also LOG an actual message */ | ||
| 306 | bool registerMsgAlsoLogs() const; | ||
| 307 | void setRegisterMsgAlsoLogs(bool registerMsgAlsoLogs); | ||
| 308 | |||
| 309 | protected: | ||
| 310 | friend class openstudio::OSWorkflow; | ||
| 311 | // prepareForMeasureRun(OSMeasure) actually doesn't use the OSMeasure, but it's a check that an OSMeasure is there. | ||
| 312 | // This is the actual implementation though, and it's protected by OSWorkflow is friended so it can call it before SKIPPING a step without the | ||
| 313 | // performance penatly of actually loading and resolving the measure just to skip it | ||
| 314 | void prepareForMeasureRun(); | ||
| 315 | |||
| 316 | private: | ||
| 317 | − | REGISTER_LOGGER("openstudio.measure.OSRunner"); | |
| 318 | |||
| 319 | static std::string cleanValueName(const std::string& name); | ||
| 320 | |||
| 321 | void captureStreams(); | ||
| 322 | void restoreStreams(); | ||
| 323 | |||
| 324 | WorkflowJSON m_workflow; | ||
| 325 | bool m_startedStep; | ||
| 326 | bool m_streamsCaptured; | ||
| 327 | std::string m_unitsPreference; | ||
| 328 | std::string m_languagePreference; | ||
| 329 | |||
| 330 | bool m_halted; | ||
| 331 | |||
| 332 | bool m_registerMsgAlsoLogs = false; | ||
| 333 | |||
| 334 | // current data | ||
| 335 | WorkflowStepResult m_result; | ||
| 336 | |||
| 337 | mutable boost::optional<openstudio::model::Model> m_lastOpenStudioModel; | ||
| 338 | boost::optional<openstudio::path> m_lastOpenStudioModelPath; | ||
| 339 | mutable boost::optional<openstudio::Workspace> m_lastEnergyPlusWorkspace; | ||
| 340 | boost::optional<openstudio::path> m_lastEnergyPlusWorkspacePath; | ||
| 341 | mutable boost::optional<openstudio::SqlFile> m_lastEnergyPlusSqlFile; | ||
| 342 | boost::optional<openstudio::path> m_lastEnergyPlusSqlFilePath; | ||
| 343 | boost::optional<openstudio::path> m_lastModelicaResultPath; | ||
| 344 | mutable boost::optional<openstudio::EpwFile> m_lastEpwFile; | ||
| 345 | boost::optional<openstudio::path> m_lastEpwFilePath; | ||
| 346 | |||
| 347 | std::streambuf* m_originalStdOut; | ||
| 348 | std::streambuf* m_originalStdErr; | ||
| 349 | std::stringstream m_bufferStdOut; | ||
| 350 | std::stringstream m_bufferStdErr; | ||
| 351 | |||
| 352 | boost::optional<openstudio::path> m_currentDir; | ||
| 353 | std::set<openstudio::path> m_currentDirFiles; | ||
| 354 | |||
| 355 | openstudio::alfalfa::AlfalfaJSON m_alfalfa; | ||
| 356 | openstudio::measure::ModelicaParameters m_modelicaParameters; | ||
| 357 | }; | ||
| 358 | |||
| 359 | } // namespace measure | ||
| 360 | } // namespace openstudio | ||
| 361 | |||
| 362 | #endif // MEASURE_OSRUNNER_HPP | ||
| 363 |