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 |