OpenStudio:measure
 All Classes Namespaces Functions Typedefs Enumerations Enumerator Pages
Public Member Functions | Protected Member Functions | List of all members
openstudio::measure::OSRunner Class Reference

#include <OSRunner.hpp>

Public Member Functions

bool incrementStep ()
 
bool registerMsgAlsoLogs () const
 Whether registerInfo, registerWarning, registerError, registerInitialCondition, registerFinalCondition and registerAsNotApplicable also LOG an actual message. More...
 
void reset ()
 
void resetLanguagePreference ()
 
void resetLastEnergyPlusSqlFilePath ()
 
void resetLastEnergyPlusWorkspace ()
 
void resetLastEnergyPlusWorkspacePath ()
 
void resetLastEpwFilePath ()
 
void resetLastOpenStudioModel ()
 
void resetLastOpenStudioModelPath ()
 
void resetUnitsPreference ()
 
bool setLanguagePreference (const std::string &languagePreference)
 Sets preferred language, e.g. More...
 
void setLastEnergyPlusSqlFilePath (const openstudio::path &lastEnergyPlusSqlFilePath)
 
void setLastEnergyPlusWorkspace (const openstudio::Workspace &lastEnergyPlusWorkspace)
 
void setLastEnergyPlusWorkspacePath (const openstudio::path &lastEnergyPlusWorkspacePath)
 
void setLastEpwFilePath (const openstudio::path &lastEpwFilePath)
 
void setLastOpenStudioModel (const openstudio::model::Model &lastOpenStudioModel)
 
void setLastOpenStudioModelPath (const openstudio::path &lastOpenStudioModelPath)
 
void setRegisterMsgAlsoLogs (bool registerMsgAlsoLogs)
 
bool setUnitsPreference (const std::string &unitsPreference)
 Sets preferred unit system, either 'IP' or 'SI'. More...
 
Constructors and Destructors
 OSRunner (const WorkflowJSON &workflow)
 
virtual ~OSRunner ()
 
Getters and Queries
WorkflowJSON workflow () const
 Returns a clone of the workflow currently being run. More...
 
std::string unitsPreference () const
 Returns preferred unit system, either 'IP' or 'SI'. More...
 
std::string languagePreference () const
 Returns preferred language, e.g. More...
 
WorkflowStepResult result () const
 Returns the result for the current/last OSMeasure run by this OSRunner. More...
 
bool halted () const
 Returns true if the simulation has been halted. More...
 
boost::optional
< openstudio::model::Model > 
lastOpenStudioModel () const
 Returns a copy of the last Model generated in the workflow if available. More...
 
boost::optional
< openstudio::Workspace > 
lastEnergyPlusWorkspace () const
 Returns a copy of the last EnergyPlus Workspace generated in the workflow if available. More...
 
boost::optional
< openstudio::SqlFile > 
lastEnergyPlusSqlFile () const
 Returns a copy of the last EnergyPlus SqlFile generated in the workflow if available. More...
 
boost::optional
< openstudio::EpwFile > 
lastEpwFile () const
 Returns a copy of the last EpwFile generated in the workflow if available. More...
 
boost::optional< openstudio::path > lastEpwFilePath () const
 Returns a path to the last EpwFile generated in the workflow if available. More...
 
virtual bool inSelection (const openstudio::model::ModelObject &modelObject) const
 Tests if the given ModelObject is in the application's current selection. More...
 
Actions
virtual std::map< std::string,
OSArgument
getUserInput (std::vector< OSArgument > &arguments) const
 Gets user input using dialog boxes, etc. More...
 
virtual void prepareForMeasureRun (const OSMeasure &measure)
 Initializes OSRunner for capturing data on a particular measure. More...
 
virtual void registerError (const std::string &message)
 Registers error message with result, and sets result value to "Fail". More...
 
virtual bool registerWarning (const std::string &message)
 Registers warning message with result. More...
 
virtual bool registerInfo (const std::string &message)
 Registers info message with result. More...
 
virtual void registerAsNotApplicable (const std::string &message)
 Sets result value to "NA", and registers a corresponding info message. More...
 
virtual void registerInitialCondition (const std::string &message)
 Sets the result initial condition to message. More...
 
virtual void registerFinalCondition (const std::string &message)
 Sets the result final condition to message. More...
 
virtual void registerValue (const std::string &name, bool value)
 
virtual void registerValue (const std::string &name, const std::string &displayName, bool value)
 
virtual void registerValue (const std::string &name, double value)
 
virtual void registerValue (const std::string &name, double value, const std::string &units)
 
virtual void registerValue (const std::string &name, const std::string &displayName, double value)
 
virtual void registerValue (const std::string &name, const std::string &displayName, double value, const std::string &units)
 
virtual void registerValue (const std::string &name, int value)
 
virtual void registerValue (const std::string &name, int value, const std::string &units)
 
virtual void registerValue (const std::string &name, const std::string &displayName, int value)
 
virtual void registerValue (const std::string &name, const std::string &displayName, int value, const std::string &units)
 
virtual void registerValue (const std::string &name, const std::string &value)
 
virtual void registerValue (const std::string &name, const std::string &displayName, const std::string &value)
 
virtual void haltWorkflow (const std::string &completedStatus="Invalid")
 Halts the simulation with the provided completed status, does not set the current measure's step result. More...
 
virtual void createProgressBar (const std::string &text) const
 Creates a progress bar with the text label. More...
 
virtual void updateProgress (double value) const
 Updates the progress bar to value (between 0 and 100). More...
 
virtual void destroyProgressBar () const
 Destroys the progress bar. More...
 
Common Error Checking Functions
bool validateUserArguments (const std::vector< OSArgument > &script_arguments, const std::map< std::string, OSArgument > &user_arguments)
 Returns true, logs no messages, and registers a value for each argument with a value or default value if all script_arguments are in user_arguments, and if all required script_arguments have been set or have defaults in user_arguments. More...
 
bool getBoolArgumentValue (const std::string &argument_name, const std::map< std::string, OSArgument > &user_arguments)
 Call this method to retrieve the value of an OSArgument of type boolean that is either required or has a default. More...
 
boost::optional< bool > getOptionalBoolArgumentValue (const std::string &argument_name, const std::map< std::string, OSArgument > &user_arguments)
 Call this method to retrieve the value of an OSArgument of type boolean that is optional (not required and does not have a default). More...
 
double getDoubleArgumentValue (const std::string &argument_name, const std::map< std::string, OSArgument > &user_arguments)
 Call this method to retrieve the value of an OSArgument of type double that is either required or has a default. More...
 
boost::optional< double > getOptionalDoubleArgumentValue (const std::string &argument_name, const std::map< std::string, OSArgument > &user_arguments)
 Call this method to retrieve the value of an OSArgument of type double that is optional (not required and does not have a default). More...
 
int getIntegerArgumentValue (const std::string &argument_name, const std::map< std::string, OSArgument > &user_arguments)
 Call this method to retrieve the value of an OSArgument of type integer that is either required or has a default. More...
 
boost::optional< int > getOptionalIntegerArgumentValue (const std::string &argument_name, const std::map< std::string, OSArgument > &user_arguments)
 Call this method to retrieve the value of an OSArgument of type integer that is optional (not required and does not have a default). More...
 
std::string getStringArgumentValue (const std::string &argument_name, const std::map< std::string, OSArgument > &user_arguments)
 Call this method to retrieve the value of an OSArgument of type string, choice, or path that is either required or has a default. More...
 
boost::optional< std::string > getOptionalStringArgumentValue (const std::string &argument_name, const std::map< std::string, OSArgument > &user_arguments)
 Call this method to retrieve the value of an OSArgument of type string, choice, or path that is optional (not required and does not have a default). More...
 
openstudio::path getPathArgumentValue (const std::string &argument_name, const std::map< std::string, OSArgument > &user_arguments)
 Call this method to retrieve the value of an OSArgument of type path that is either required or has a default. More...
 
boost::optional< openstudio::path > getOptionalPathArgumentValue (const std::string &argument_name, const std::map< std::string, OSArgument > &user_arguments)
 Call this method to retrieve the value of an OSArgument of type path that is optional (not required and does not have a default). More...
 
boost::optional
< openstudio::WorkspaceObject > 
getOptionalWorkspaceObjectChoiceValue (const std::string &argument_name, const std::map< std::string, OSArgument > &user_arguments, const openstudio::Workspace &workspace)
 Call this method to retrieve the value of an OSArgument that was created by makeChoiceArgumentOfWorkspaceObjects. More...
 
Json::Value getArgumentValues (std::vector< OSArgument > &script_arguments, const std::map< std::string, OSArgument > &user_arguments)
 Call this method to retrieve the values of OSArguments of all types. More...
 
Json::Value getPastStepValuesForMeasure (const std::string &measureName) const
 Call this method to retrieve the values of all workflow steps for a given measure name. More...
 
Json::Value getPastStepValuesForName (const std::string &stepName) const
 Call this method to retrieve the values of all workflow steps for a given step value name. More...
 

Protected Member Functions

void prepareForMeasureRun ()
 

Detailed Description

OSRunner is a concrete base class for application-specific classes that run OSMeasures.

Constructor & Destructor Documentation

openstudio::measure::OSRunner::OSRunner ( const WorkflowJSON &  workflow)
virtual openstudio::measure::OSRunner::~OSRunner ( )
virtual

Member Function Documentation

virtual void openstudio::measure::OSRunner::createProgressBar ( const std::string &  text) const
virtual

Creates a progress bar with the text label.

Base class implementation does nothing.

virtual void openstudio::measure::OSRunner::destroyProgressBar ( ) const
virtual

Destroys the progress bar.

Base class implementation does nothing.

Json::Value openstudio::measure::OSRunner::getArgumentValues ( std::vector< OSArgument > &  script_arguments,
const std::map< std::string, OSArgument > &  user_arguments 
)

Call this method to retrieve the values of OSArguments of all types.

It will call validateUserArguments for you and throw if that fails

bool openstudio::measure::OSRunner::getBoolArgumentValue ( const std::string &  argument_name,
const std::map< std::string, OSArgument > &  user_arguments 
)

Call this method to retrieve the value of an OSArgument of type boolean that is either required or has a default.

double openstudio::measure::OSRunner::getDoubleArgumentValue ( const std::string &  argument_name,
const std::map< std::string, OSArgument > &  user_arguments 
)

Call this method to retrieve the value of an OSArgument of type double that is either required or has a default.

int openstudio::measure::OSRunner::getIntegerArgumentValue ( const std::string &  argument_name,
const std::map< std::string, OSArgument > &  user_arguments 
)

Call this method to retrieve the value of an OSArgument of type integer that is either required or has a default.

boost::optional<bool> openstudio::measure::OSRunner::getOptionalBoolArgumentValue ( const std::string &  argument_name,
const std::map< std::string, OSArgument > &  user_arguments 
)

Call this method to retrieve the value of an OSArgument of type boolean that is optional (not required and does not have a default).

boost::optional<double> openstudio::measure::OSRunner::getOptionalDoubleArgumentValue ( const std::string &  argument_name,
const std::map< std::string, OSArgument > &  user_arguments 
)

Call this method to retrieve the value of an OSArgument of type double that is optional (not required and does not have a default).

boost::optional<int> openstudio::measure::OSRunner::getOptionalIntegerArgumentValue ( const std::string &  argument_name,
const std::map< std::string, OSArgument > &  user_arguments 
)

Call this method to retrieve the value of an OSArgument of type integer that is optional (not required and does not have a default).

boost::optional<openstudio::path> openstudio::measure::OSRunner::getOptionalPathArgumentValue ( const std::string &  argument_name,
const std::map< std::string, OSArgument > &  user_arguments 
)

Call this method to retrieve the value of an OSArgument of type path that is optional (not required and does not have a default).

boost::optional<std::string> openstudio::measure::OSRunner::getOptionalStringArgumentValue ( const std::string &  argument_name,
const std::map< std::string, OSArgument > &  user_arguments 
)

Call this method to retrieve the value of an OSArgument of type string, choice, or path that is optional (not required and does not have a default).

boost::optional<openstudio::WorkspaceObject> openstudio::measure::OSRunner::getOptionalWorkspaceObjectChoiceValue ( const std::string &  argument_name,
const std::map< std::string, OSArgument > &  user_arguments,
const openstudio::Workspace &  workspace 
)

Call this method to retrieve the value of an OSArgument that was created by makeChoiceArgumentOfWorkspaceObjects.

Json::Value openstudio::measure::OSRunner::getPastStepValuesForMeasure ( const std::string &  measureName) const

Call this method to retrieve the values of all workflow steps for a given measure name.

measureName can be: the WorkflowStep's measureDirName or name, or the WorkflowStepResult's measureName

Json::Value openstudio::measure::OSRunner::getPastStepValuesForName ( const std::string &  stepName) const

Call this method to retrieve the values of all workflow steps for a given step value name.

openstudio::path openstudio::measure::OSRunner::getPathArgumentValue ( const std::string &  argument_name,
const std::map< std::string, OSArgument > &  user_arguments 
)

Call this method to retrieve the value of an OSArgument of type path that is either required or has a default.

std::string openstudio::measure::OSRunner::getStringArgumentValue ( const std::string &  argument_name,
const std::map< std::string, OSArgument > &  user_arguments 
)

Call this method to retrieve the value of an OSArgument of type string, choice, or path that is either required or has a default.

virtual std::map<std::string, OSArgument> openstudio::measure::OSRunner::getUserInput ( std::vector< OSArgument > &  arguments) const
virtual

Gets user input using dialog boxes, etc.

Result is map of name to argument. Result is empty if user cancels or user did not provide values for all required arguments. Base class implementation simply creates a map, with no information added, from arguments.

bool openstudio::measure::OSRunner::halted ( ) const

Returns true if the simulation has been halted.

virtual void openstudio::measure::OSRunner::haltWorkflow ( const std::string &  completedStatus = "Invalid")
virtual

Halts the simulation with the provided completed status, does not set the current measure's step result.

Measure writers can call this with "Success" if all required results have been generated. Measure writers should not call this with "Fail", runner.registerError should be used instead. Measure writers can call this with "Invalid" if the workflow requests parameter combinations that are not valid. Measure writers should not call this with "Cancel", this is reserved for external cancel operations.

bool openstudio::measure::OSRunner::incrementStep ( )
virtual bool openstudio::measure::OSRunner::inSelection ( const openstudio::model::ModelObject &  modelObject) const
virtual

Tests if the given ModelObject is in the application's current selection.

Base class implementation always returns true.

std::string openstudio::measure::OSRunner::languagePreference ( ) const

Returns preferred language, e.g.

'en' or 'fr'. New in OS 2.0.

boost::optional<openstudio::SqlFile> openstudio::measure::OSRunner::lastEnergyPlusSqlFile ( ) const

Returns a copy of the last EnergyPlus SqlFile generated in the workflow if available.

boost::optional<openstudio::Workspace> openstudio::measure::OSRunner::lastEnergyPlusWorkspace ( ) const

Returns a copy of the last EnergyPlus Workspace generated in the workflow if available.

boost::optional<openstudio::EpwFile> openstudio::measure::OSRunner::lastEpwFile ( ) const

Returns a copy of the last EpwFile generated in the workflow if available.

boost::optional<openstudio::path> openstudio::measure::OSRunner::lastEpwFilePath ( ) const

Returns a path to the last EpwFile generated in the workflow if available.

boost::optional<openstudio::model::Model> openstudio::measure::OSRunner::lastOpenStudioModel ( ) const

Returns a copy of the last Model generated in the workflow if available.

virtual void openstudio::measure::OSRunner::prepareForMeasureRun ( const OSMeasure measure)
virtual

Initializes OSRunner for capturing data on a particular measure.

Replaces result with a default-constructed result, and keeps the measure name for use in log messages. Should be called at the beginning of every OSMeasure. Is called by the OSMeasure C++ classes' run methods.

void openstudio::measure::OSRunner::prepareForMeasureRun ( )
protected
virtual void openstudio::measure::OSRunner::registerAsNotApplicable ( const std::string &  message)
virtual

Sets result value to "NA", and registers a corresponding info message.

In most circumstances, OSMeasures should return true after calling this method. Does not affect workflow completed status.

virtual void openstudio::measure::OSRunner::registerError ( const std::string &  message)
virtual

Registers error message with result, and sets result value to "Fail".

OSMeasures should return false after calling this method. Workflow completed status will be set to "Fail".

virtual void openstudio::measure::OSRunner::registerFinalCondition ( const std::string &  message)
virtual

Sets the result final condition to message.

virtual bool openstudio::measure::OSRunner::registerInfo ( const std::string &  message)
virtual

Registers info message with result.

Base class returns true. Derived classes may choose to present a prompt to the user. The OSMeasure should exit (return false) if false is returned.

virtual void openstudio::measure::OSRunner::registerInitialCondition ( const std::string &  message)
virtual

Sets the result initial condition to message.

bool openstudio::measure::OSRunner::registerMsgAlsoLogs ( ) const

Whether registerInfo, registerWarning, registerError, registerInitialCondition, registerFinalCondition and registerAsNotApplicable also LOG an actual message.

virtual void openstudio::measure::OSRunner::registerValue ( const std::string &  name,
bool  value 
)
virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

virtual void openstudio::measure::OSRunner::registerValue ( const std::string &  name,
const std::string &  displayName,
bool  value 
)
virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

virtual void openstudio::measure::OSRunner::registerValue ( const std::string &  name,
double  value 
)
virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

virtual void openstudio::measure::OSRunner::registerValue ( const std::string &  name,
double  value,
const std::string &  units 
)
virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

virtual void openstudio::measure::OSRunner::registerValue ( const std::string &  name,
const std::string &  displayName,
double  value 
)
virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

virtual void openstudio::measure::OSRunner::registerValue ( const std::string &  name,
const std::string &  displayName,
double  value,
const std::string &  units 
)
virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

virtual void openstudio::measure::OSRunner::registerValue ( const std::string &  name,
int  value 
)
virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

virtual void openstudio::measure::OSRunner::registerValue ( const std::string &  name,
int  value,
const std::string &  units 
)
virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

virtual void openstudio::measure::OSRunner::registerValue ( const std::string &  name,
const std::string &  displayName,
int  value 
)
virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

virtual void openstudio::measure::OSRunner::registerValue ( const std::string &  name,
const std::string &  displayName,
int  value,
const std::string &  units 
)
virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

virtual void openstudio::measure::OSRunner::registerValue ( const std::string &  name,
const std::string &  value 
)
virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

virtual void openstudio::measure::OSRunner::registerValue ( const std::string &  name,
const std::string &  displayName,
const std::string &  value 
)
virtual

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

virtual bool openstudio::measure::OSRunner::registerWarning ( const std::string &  message)
virtual

Registers warning message with result.

Base class returns true. Derived classes may choose to present a prompt to the user. The OSMeasure should exit (return false) if false is returned.

void openstudio::measure::OSRunner::reset ( )
void openstudio::measure::OSRunner::resetLanguagePreference ( )
void openstudio::measure::OSRunner::resetLastEnergyPlusSqlFilePath ( )
void openstudio::measure::OSRunner::resetLastEnergyPlusWorkspace ( )
void openstudio::measure::OSRunner::resetLastEnergyPlusWorkspacePath ( )
void openstudio::measure::OSRunner::resetLastEpwFilePath ( )
void openstudio::measure::OSRunner::resetLastOpenStudioModel ( )
void openstudio::measure::OSRunner::resetLastOpenStudioModelPath ( )
void openstudio::measure::OSRunner::resetUnitsPreference ( )
WorkflowStepResult openstudio::measure::OSRunner::result ( ) const

Returns the result for the current/last OSMeasure run by this OSRunner.

(prepareForMeasureRun should be called prior to each run to ensure that result() corresponds to a single script, and is not instead a running result over multiple scripts. One way to ensure that this happens is to call the default version of run in ModelMeasure, etc. at the beginning of any particular run method.)

bool openstudio::measure::OSRunner::setLanguagePreference ( const std::string &  languagePreference)

Sets preferred language, e.g.

'en' or 'fr'. New in OS 2.0.

void openstudio::measure::OSRunner::setLastEnergyPlusSqlFilePath ( const openstudio::path &  lastEnergyPlusSqlFilePath)
void openstudio::measure::OSRunner::setLastEnergyPlusWorkspace ( const openstudio::Workspace &  lastEnergyPlusWorkspace)
void openstudio::measure::OSRunner::setLastEnergyPlusWorkspacePath ( const openstudio::path &  lastEnergyPlusWorkspacePath)
void openstudio::measure::OSRunner::setLastEpwFilePath ( const openstudio::path &  lastEpwFilePath)
void openstudio::measure::OSRunner::setLastOpenStudioModel ( const openstudio::model::Model &  lastOpenStudioModel)
void openstudio::measure::OSRunner::setLastOpenStudioModelPath ( const openstudio::path &  lastOpenStudioModelPath)
void openstudio::measure::OSRunner::setRegisterMsgAlsoLogs ( bool  registerMsgAlsoLogs)
bool openstudio::measure::OSRunner::setUnitsPreference ( const std::string &  unitsPreference)

Sets preferred unit system, either 'IP' or 'SI'.

New in OS 2.0.

std::string openstudio::measure::OSRunner::unitsPreference ( ) const

Returns preferred unit system, either 'IP' or 'SI'.

New in OS 2.0.

virtual void openstudio::measure::OSRunner::updateProgress ( double  value) const
virtual

Updates the progress bar to value (between 0 and 100).

Base class implementation does nothing.

bool openstudio::measure::OSRunner::validateUserArguments ( const std::vector< OSArgument > &  script_arguments,
const std::map< std::string, OSArgument > &  user_arguments 
)

Returns true, logs no messages, and registers a value for each argument with a value or default value if all script_arguments are in user_arguments, and if all required script_arguments have been set or have defaults in user_arguments.

Otherwise, returns false and registers an error if there are any type mismatches, or if any required or defaulted arguments are missing (entirely, or their values are not set). All other discrepancies are logged as warnings.

WorkflowJSON openstudio::measure::OSRunner::workflow ( ) const

Returns a clone of the workflow currently being run.

New in OS 2.0.