GCC Code Coverage Report


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

src/utilities/filetypes/WorkflowJSON.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_FILETYPES_WORKFLOWJSON_HPP
7 #define UTILITIES_FILETYPES_WORKFLOWJSON_HPP
8
9 #include "../UtilitiesAPI.hpp"
10
11 #include "../core/Logger.hpp"
12 #include "../core/Path.hpp"
13 #include "../bcl/BCLMeasure.hpp"
14
15 #include <json/json.h>
16
17 class Filetypes_WorkflowJSON_Signals_Test;
18
19 namespace openstudio {
20
21 class WorkflowStep;
22 class RunOptions;
23 class MeasureStep;
24 class DateTime;
25 class OSDocument;
26
27 namespace detail {
28 class WorkflowJSON_Impl;
29 }
30
31 /** Class for accessing the OpenStudio Workflow (OSW) JSON format. */
32 class UTILITIES_API WorkflowJSON
33 {
34 public:
35 /** Create a new, empty workflow. */
36 WorkflowJSON();
37
38 /** Constructor with string, will throw if string is incorrect. */
39 WorkflowJSON(const std::string& s);
40
41 /** Constructor with path, will throw if path does not exist or file is incorrect. */
42 WorkflowJSON(const openstudio::path& p);
43
44 /** Clones this WorkflowJSON into a separate one. */
45 WorkflowJSON clone() const;
46
47 /** Attempt to load a WorkflowJSON from string */
48 static boost::optional<WorkflowJSON> load(const std::string& s);
49
50 /** Attempt to load a WorkflowJSON from path */
51 static boost::optional<WorkflowJSON> load(const openstudio::path& p);
52
53 Json::Value toJSON(bool includeHash = true) const;
54
55 /** Get the workflow as a string. */
56 std::string string(bool includeHash = true) const;
57
58 /** Get a stored hash of the workflow. */
59 std::string hash() const;
60
61 /** Compute the current hash of the workflow. */
62 std::string computeHash() const;
63
64 /** Check for updates and return true if there are any, updates value of the stored hash. */
65 bool checkForUpdates() const;
66
67 /** Saves this file to the current location. */
68 bool save() const;
69
70 /** Saves this file to a new location. Updates the OSW path. */
71 bool saveAs(const openstudio::path& p) const;
72
73 /** Reset to re-run the workflow, does not delete steps. */
74 void reset() const;
75
76 /** Sets the started at time. */
77 void start() const;
78
79 /** Get the zero based index of the current step.
80 * If a simulation completes normally, current step index will be one higher than index of the last step.
81 * If a simulation is halted, current step index will point to the step after the last run step.
82 */
83 unsigned currentStepIndex() const;
84
85 /** Get the current step.*/
86 boost::optional<WorkflowStep> currentStep() const;
87
88 /** Increments current step, returns true if there is another step. */
89 bool incrementStep() const;
90
91 /** Returns the completion status, "Success", "Fail", "Invalid", or "Cancel".
92 * "Success" will be set automatically if all steps in the workflow complete successfully.
93 * "Fail" will be set automatically if any step in the workflow reports an error.
94 * "Invalid" can be set by a measure if the workflow requests parameter combinations that are not valid.
95 * "Cancel" will be set automatically if a workflow is cancelled externally during execution.
96 */
97 boost::optional<std::string> completedStatus() const;
98
99 /** Sets the completion status, "Success", "Fail", "Invalid", or "Cancel".
100 * Measure writers can call this with "Success" if all required results have been generated.
101 * Measure writers should not call this with "Fail", runner.registerError should be used instead.
102 * Measure writers can call this with "Invalid" if the workflow requests parameter combinations that are not valid.
103 * Measure writers should not call this with "Cancel", this is reserved for external cancel operations.
104 */
105 void setCompletedStatus(const std::string& status) const;
106
107 /** Returns the time this WorkflowJSON was created at. */
108 boost::optional<DateTime> createdAt() const;
109
110 /** Returns the time this WorkflowJSON was started at. */
111 boost::optional<DateTime> startedAt() const;
112
113 /** Returns the time this WorkflowJSON was updated at. */
114 boost::optional<DateTime> updatedAt() const;
115
116 /** Returns the time this WorkflowJSON was completed at. */
117 boost::optional<DateTime> completedAt() const;
118
119 /** Returns the content of eplusout.err file. */
120 boost::optional<std::string> eplusoutErr() const;
121
122 /** Sets the content of eplusout.err file. */
123 void setEplusoutErr(const std::string& eplusoutErr) const;
124
125 /** Returns the absolute path this workflow was loaded from or saved to, empty for new WorkflowJSON. */
126 boost::optional<openstudio::path> oswPath() const;
127
128 /** Sets the absolute path for this workflow. */
129 bool setOswPath(const openstudio::path& path) const;
130
131 /** Returns the absolute path to the directory this workflow was loaded from or saved to. Returns current working dir for new WorkflowJSON. */
132 openstudio::path oswDir() const;
133
134 /** Sets the oswDir. If oswPath is empty this does not set it. If oswPath is set, this changes directories but preserves file name. */
135 bool setOswDir(const openstudio::path& path) const;
136
137 /** Returns the root directory, default value is '.'. Evaluated relative to oswDir if not absolute. */
138 openstudio::path rootDir() const;
139 openstudio::path absoluteRootDir() const;
140
141 /** Sets the rootDir */
142 bool setRootDir(const openstudio::path& path) const;
143
144 /** Returns the run directory, default value is './run'. Evaluated relative to rootDir if not absolute. */
145 openstudio::path runDir() const;
146 openstudio::path absoluteRunDir() const;
147
148 /** Sets the runDir */
149 bool setRunDir(const openstudio::path& path) const;
150
151 /** Returns the path to write output OSW, default value is 'out.osw'. Evaluated relative to oswDir to ensure relative paths remain valid. */
152 openstudio::path outPath() const;
153 openstudio::path absoluteOutPath() const;
154
155 /** Returns the paths that will be searched in order for files, default value is './files/'. Evaluated relative to rootDir if not absolute. */
156 std::vector<openstudio::path> filePaths() const;
157 std::vector<openstudio::path> absoluteFilePaths() const;
158
159 /** Add a path to the paths searched for files. */
160 bool addFilePath(const openstudio::path& path) const;
161
162 /** Clear paths searched for files. */
163 void resetFilePaths() const;
164
165 /** Attempts to find a file by path.
166 * If file is relative, searches through filePaths in order and returns first match that exists.
167 * If file is absolute, does not search for file in filePaths, only returns true it file exists.
168 */
169 boost::optional<openstudio::path> findFile(const openstudio::path& file) const;
170 boost::optional<openstudio::path> findFile(const std::string& fileName) const;
171
172 /** Returns the paths that will be searched in order for measures, default value is './measures/'. Evaluated relative to rootDir if not absolute. */
173 std::vector<openstudio::path> measurePaths() const;
174 std::vector<openstudio::path> absoluteMeasurePaths() const;
175
176 /** Add a path to the paths searched for measures. */
177 bool addMeasurePath(const openstudio::path& path) const;
178
179 /** Clear paths searched for measures. */
180 void resetMeasurePaths() const;
181
182 /** Attempts to find a measure by path.
183 * If measureDir is relative, searches through measurePaths in order and returns first match that exists.
184 * If measureDir is absolute, does not search for measureDir in measurePaths, only returns true it measureDir exists.
185 */
186 boost::optional<openstudio::path> findMeasure(const openstudio::path& measureDir) const;
187 boost::optional<openstudio::path> findMeasure(const std::string& measureDirName) const;
188
189 /** Returns the seed file path. Evaluated relative to filePaths if not absolute. */
190 boost::optional<openstudio::path> seedFile() const;
191
192 /** Sets the seed file path. */
193 bool setSeedFile(const openstudio::path& seedFile) const;
194
195 /** Resets the seed file path. */
196 void resetSeedFile() const;
197
198 /** Returns the seed Modelica file path.
199 * Evaluated relative to filePaths if not absolute.
200 * This can be a single .mo file or a package.mo.*/
201 boost::optional<openstudio::path> seedModelicaFile() const;
202
203 /** Returns name of the seed Modelica model.
204 * This will be the model that is simulated. */
205 boost::optional<std::string> seedModelicaModel() const;
206
207 /** Sets the seed Modelica file path. */
208 bool setSeedModelicaFile(const openstudio::path& modelicaSeedFile) const;
209
210 /** Resets the seed Modelica file path. */
211 void resetSeedModelicaFile() const;
212
213 /** Returns additional Modelica packages to load prior to simulation.
214 * Each entry is evaluated relative to filePaths if not absolute. */
215 std::vector<openstudio::path> modelicaPackages() const;
216
217 /** Sets additional Modelica packages to load. */
218 bool setModelicaPackages(const std::vector<openstudio::path>& packages) const;
219
220 /** Clears any additional Modelica packages. */
221 void resetModelicaPackages() const;
222
223 /** Returns the weather file path. Evaluated relative to filePaths if not absolute. */
224 boost::optional<openstudio::path> weatherFile() const;
225
226 /** Sets the weather file path. */
227 bool setWeatherFile(const openstudio::path& weatherFile) const;
228
229 /** Resets the weather file path. */
230 void resetWeatherFile() const;
231
232 /** Returns the workflow steps. */
233 std::vector<WorkflowStep> workflowSteps() const;
234
235 /** Assigns the workflow steps. */
236 bool setWorkflowSteps(const std::vector<WorkflowStep>& steps) const;
237
238 /** Resets the workflow steps. */
239 void resetWorkflowSteps() const;
240
241 /** Gets measure steps by measure type. */
242 std::vector<MeasureStep> getMeasureSteps(const MeasureType& measureType) const;
243
244 std::vector<std::pair<unsigned, MeasureStep>> getMeasureStepsWithIndex(const MeasureType& measureType) const;
245
246 /** Sets measure steps of a given type. Does not change other measure steps. */
247 bool setMeasureSteps(const MeasureType& measureType, const std::vector<MeasureStep>& steps) const;
248
249 /** Attempts to find the BCLMeasure for a given MeasureStep. */
250 boost::optional<BCLMeasure> getBCLMeasure(const MeasureStep& step) const;
251
252 /** Checks BCLMeasure for each MeasureStep attempting to find by id, does not check measures that are not in the workflow. */
253 boost::optional<BCLMeasure> getBCLMeasureByUUID(const UUID& id) const;
254
255 /** Add a measure to the measure dir, replaces existing measure with same id, does not add a step to the workflow. */
256 boost::optional<BCLMeasure> addMeasure(const BCLMeasure& bclMeasure) const;
257
258 /** Get RunOptions for this workflow. */
259 boost::optional<RunOptions> runOptions() const;
260
261 /** Set RunOptions for this workflow. */
262 bool setRunOptions(const RunOptions& options) const;
263
264 /** Reset RunOptions for this workflow. */
265 void resetRunOptions() const;
266
267 /** Checks that all measures in the Workflow can be found, and are in the correct order (ModelMeasure > EnergyPlusMeasure > ReportingMeasure) */
268 bool validateMeasures() const;
269
270 protected:
271 // get the impl
272 template <typename T>
273 2489 std::shared_ptr<T> getImpl() const {
274 2489 return std::dynamic_pointer_cast<T>(m_impl);
275 }
276
277 friend class OSDocument;
278 friend class detail::WorkflowJSON_Impl;
279 friend class ::Filetypes_WorkflowJSON_Signals_Test; // for testing
280
281 /** Protected constructor from impl. */
282 WorkflowJSON(std::shared_ptr<detail::WorkflowJSON_Impl> impl);
283
284 private:
285 // configure logging
286 REGISTER_LOGGER("openstudio.WorkflowJSON");
287
288 // pointer to implementation
289 std::shared_ptr<detail::WorkflowJSON_Impl> m_impl;
290 };
291
292 UTILITIES_API std::ostream& operator<<(std::ostream& os, const WorkflowJSON& workflowJSON);
293
294 } // namespace openstudio
295
296 #endif //UTILITIES_FILETYPES_WORKFLOWJSON_HPP
297