OpenStudio Command Line Interface

The OpenStudio Command Line Interface (CLI) is a self-contained executable which includes everything needed to apply OpenStudio Measures to an OpenStudio Model and run an EnergyPlus simulation. The CLI is only avaiable in OpenStudio version 2.0 and higher. The CLI contains a full OpenStudio Ruby environment, the list of Ruby Gems available in each version of OpenStudio can be found here.

This document provides an overview of the most important features of the CLI, it is not meant to be an exhaustive reference. For an exhaustive list of features available in the CLI please refer to the command line output of the --help command. For a complete list of the properties available in the OSW file format please refer to the OSW JSON schema. For a complete description of the WorkflowJSON class please refer to the documentation.

Command Overview

The CLI is executed by calling the OpenStudio executable from the command line with a set of command line arguments. Calling the CLI with no arguments (such as when double-clicking the executable) causes the CLI to print a help message and then exit. Several switches which control program behavior may be passed immediately following the OpenStudio executable. Switches often have both a short form and a long form for convienence. Multiple program level switches may be combined. Program level switches include:

The -h or --help switches print the help message:

openstudio.exe --include /path/to/add/ --include /another/path/to/add

The -I or --include switches can be used to add additional directories to the Ruby $LOAD_PATH (this switch may be used more than once):

openstudio.exe --include /path/to/add/ --include /another/path/to/add

The --gem_path switch can be used to load gems from a location on the user's disk (this switch may be used more than once):

openstudio.exe --gem_path /home/gems1 --include /home/gems2

The --gem_home switch can be used to set the directory to install gems to (note that the gem_install command does not yet work):

openstudio.exe --gem_home /home/gems

The --verbose switch can be used to print additional information for debugging:

openstudio.exe --verbose

Program level switches (if any) are followed by a subcommand which directs the program to perform a particular function. These subcommands are explained in further detail below.

Measure Subcommand

The measure subcommand is used to query OpenStudio Measures on disk. The following arguments may be passed to the measure subcommand.

The -h switch prints help specific to the measure subcommand:

openstudio.exe measure -h

The -t or --update_all switches process all measures in a given directory and updates their measure.xml files if updates to their content are detected. Information about the measures is printed to standard out in JSON format:

openstudio.exe measure --update_all /path/to/measures/

The -u or --update switches process a single measure in a given directory and updates its measure.xml file if updates to the content are detected. Information about the measure is printed to standard out in JSON format:

openstudio.exe measure --update /path/to/measure/

The -a or --compute_arguments switches process a single measure in a given directory and updates its measure.xml file if updates to the content are detected. Information about the measure, including model specific arguments, is printed to standard out in JSON format:

openstudio.exe measure --compute_arguments /path/to/model.osm /path/to/measure/

or for an EnergyPlus Measure:

openstudio.exe measure --compute_arguments /path/to/model.idf /path/to/measure/

Run Subcommand

The run subcommand is used to load an OpenStudio Model, apply a series of OpenStudio Model Measures, translate to EnergyPlus IDF, apply a series of OpenStudio EnergyPlus Measures, run an EnergyPlus simulation on the resulting model, and finally apply a series of OpenStudio Reporting Measures. The OpenStudio Workflow (OSW) file format is used to describe which OpenStudio Measures to apply to the model and what arguments to pass to each measure. The OSW format is explained in the following section.

The -h switch prints help specific to the run subcommand:

openstudio.exe run -h

The -w or --workflow switches run the complete simulation workflow as described in an OSW file:

openstudio.exe run --workflow /path/to/workflow.osw

The --debug switch can be used to include additional outputs for debugging failing workflows and does not clean up the run directory:

openstudio.exe run --debug --workflow /path/to/workflow.osw

The -m or --measures_only switches run only the OpenStudio Model and EnergyPlus Measures but do not run the EnergyPlus simulation or OpenStudio Reporting Measures in an OSW file:

openstudio.exe run --measures_only /path/to/workflow.osw

The -p or --postprocess_only switches do not run the OpenStudio Modelm EnergyPlus Measures, or EnergyPlus simulation in an OSW file. Existing simulation results are loaded and only OpenStudio Reporting Measures are run, this is useful for generating new reports without re-running simulations:

openstudio.exe run --postprocess_only /path/to/workflow.osw

OSW Structure

The OpenStudio Workflow (OSW) format is a JSON file format that describes a simulation workflow. In an OpenStudio Workflow, a seed OpenStudio Model is loaded. OpenStudio Model Measures are applied to the seed model. After these measures, the OpenStudio Model is translated to EnergyPlus IDF format. Once in EnergyPlus IDF format, OpenStudio EnergyPlus Measures are applied. After these measures, the EnergyPlus simulation is executed. Once the EnergyPlus simulation is complete, OpenStudio Reporting Measures are applied which generate reports. An error at any point in the workflow will halt the workflow. Once the workflow is completed (successfully or unsuccessfully) an output OSW file is written which contains output related to running the workflow.

An example OSW project is included in the OpenStudio installer under './Examples/compact_osw'. To run this example, copy it to a user writable location and then:

/path/to/openstudio.exe run -w /path/to/compact.osw

The OSW file format is described in JSON schema format here.

The OpenStudio API includes the class WorkflowJSON which is able read, modify, and write the OSW file format. The WorkflowJSON class also includes features for finding measures and files associated with a simulation workflow.

The WorkflowJSON associated with an OpenStudio Model can be accessed using model.workflowJSON. The WorkflowJSON object can also be accessed from the OSRunner object within a measure using runner.workflow. Within the context of a measure, the WorkflowJSON object can be used to find files and measures associated with the simulation. It can also be used to tell which OpenStudio Measures will be run during the workflow, what arguments they will be passed, and capture output from previously run measures. However, during the course of a simulation workflow the OSW associated with an OpenStudio Model or OSRunner cannot be altered.

An example OSW is shown below, the meaning of key terms is explained in more detail later in this section:

{
  "seed_file": "baseline.osm",
  "weather_file": "USA_CO_Golden-NREL.724666_TMY3.epw",
  "steps": [
    {
      "measure_dir_name": "IncreaseWallRValue",
      "arguments": {}
    },
    {
      "measure_dir_name": "IncreaseRoofRValue",
      "arguments": {
        "r_value": 45
      }
    },
    {
      "measure_dir_name": "SetEplusInfiltration",
      "arguments": {
        "flowPerZoneFloorArea": 10.76
      }
    },
    {
      "measure_dir_name": "DencityReports",
      "arguments": {
        "output_format": "CSV"
      }
    }
  ]
}

Seed File

The seed file is the file name of the OpenStudio Model to be loaded at the beginning of the simulation workflow. The seed model may be empty or the memeber may be missing, in this case a newly constructed OpenStudio Model is passed to the first OpenStudio Model Measure. The seed model is found using the logic documented for WorkflowJSON::findFile.

Weather File

The weather file is the file name of the EnergyPlus Weather (EPW) file loaded at the beginning of the simulation workflow. The weather file may be empty or the memeber may be missing. The weather file is found using the logic documented for WorkflowJSON::findFile. The following logic applies to the weather file during a simulation workflow:

  1. If a weather file is specified in the OSW, that file replaces any weather file specified in the seed OpenStudio Model before measure processing begins.
  2. During OpenStudio Model Measure processing, the weather file may be changed by altering the WeatherFile object in the OpenStudio Model.
  3. On translation to EnergyPlus, the weather file referenced in the OSM is found using WorkflowJSON.findFile and copied to in.epw in the run directory. EnergyPlus measures may change the weather file by copying files on top of in.epw.

Workflow Steps

Each step listed in the OSW file describes an OpenStudio Measure to apply. Measures are applied in order and must progress from OpenStudio Model Measures to OpenStudio EnergyPlus Measures to OpenStudio Reporting Measures. Each step lists a measure_dir_name which is the directory name of an OpenStudio Measure to apply. Measures are found at run time according to logic in WorkflowJSON::findMeasure. Each step specifies arguments to be passed to the measure, the measure argument's name is the key and the value to pass is the measure. Optional arguments may be ommitted, default values will be used in this case. The value passed to choice arguments may be either a valid choice value or a valid choice value display name.

Environment Variables

The OpenStudio Command Line Interface can be configured with several environment variables. In cases where a value can be configured with either a command line switch or an environment variable, the command line switch will take precedence. Custom environment variables configurations do not impact local or remote PAT runs.

The ENERGYPLUS_EXE_PATH environment variable can be used to configure the CLI to use a different version of the EnergyPlus engine than the one OpenStudio is installed with:

Windows

set ENERGYPLUS_EXE_PATH=/path/to/EnergyPlus.exe

Unix

export ENERGYPLUS_EXE_PATH=/path/to/energyplus

The RUBYLIB environment variable can be used to configure the CLI to require Ruby files from locations on the user's disk. Locations passed using the --include switch take precedence over the paths found in this environment variable:

Windows

set RUBYLIB=/home/git/project;/home/git/project/app/helpers

Unix

export RUBYLIB=/home/git/project:/home/git/project/app/helpers

The GEM_PATH environment variable can be used to configure the CLI to load gems from a location on the user's disk. Locations passed using the --gem_path switch take precedence over the paths found in this environment variable:

Windows

set GEM_PATH=/home/gems1;/home/gems2

Unix

export GEM_PATH=/home/gems1:/home/gems2

The GEM_HOME environment variable can be used to configure the CLI to install gems to a location on the user's disk. The location passed using the --gem_home switch takes precedence over the path found in this environment variable (note that the gem_install command does not yet work):

Windows

set GEM_HOME=/home/gems

Unix

export GEM_HOME=/home/gems

These same environment variables apply when requiring openstudio.rb from system ruby. Note, that requiring openstudio.rb from system ruby does not bring in any of the default gems that are embedded inside the CLI (i.e. the openstudio-standards gem). You must install these gems separately to ensure they are available when using system ruby. The standard way to do this is with Bundler. A Gemfile is included in the Ruby directory of the OpenStudio installation, this can be used as a reference when setting up your own Gemfile to ensure that gems are compatible with the version of OpenStudio.

Loading Custom Gems

Developers commonly need to be able to override the version of a gem embedded in the OpenStudio CLI with one that they are working on. Additionally, measure writers may wish to use gems that are not distributed with the OpenStudio CLI. Neither of these use cases are an issue when using system ruby as the OpenStudio ruby bindings (i.e. openstudio.rb) do not have embedded gems, bundler can be used to specify gem versions in this case. When using the CLI there are two ways to override an embedded gem or provide access to another gem. The first is to use the --include switch to add the directory containing the primary gem file (e.g. the directory containing openstudio-standards.rb) to the ruby load path. The second is to install the gem to your system location, then use the --gem_path switch to include this location (e.g. C:\ruby-2.2.4-x64-mingw32\lib\ruby\gems\2.2.0\). Note that the gem path directory should have specifications, gems, and other subdirectories in it. Also, note that when using this second approach, a system gem will only override the embedded gem if the version is equal or greater to the embedded gem. It can be useful to use the --verbose and -e switches to print some information that can verify the correct version of the gem is being loaded:

openstudio --verbose -I \openstudio-standards\openstudio-standards\lib\ -e "require 'openstudio-standards'" -e "puts OpenstudioStandards::VERSION"
openstudio --verbose --gem_path C:\ruby-2.2.4-x64-mingw32\lib\ruby\gems\2.2.0\ -e "require 'openstudio-standards'" -e "puts OpenstudioStandards::VERSION"