GCC Code Coverage Report


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

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