Getting Started

Setup

To get started:

1. Download OpenStudio 2.9.1 and install the Command Line Interface/EnergyPlus components, or use the nrel/openstudio docker image.
2. Download the latest release for these OpenStudio measures.

Running

To programatically run simulations, it’s recommended to use the OpenStudio Command Line Interface. Two general approaches (basic and advanced) for running via the CLI are described below. The OpenStudio measures can also be run from user interfaces (e.g., the OpenStudio Application or Parametric Analysis Tool).

Note

If the openstudio command is not found, it’s because the executable is not in your PATH. Either add the executable to your PATH or point directly to the executable found in the openstudio-X.X.X/bin directory.

Basic Run

The simplest and fastest method is to call the OpenStudio CLI with the provided workflow/run_simulation.rb script.

For example: openstudio workflow/run_simulation.rb -x workflow/sample_files/base.xml

This will create a “run” directory with all input/output files. By default it will be found at the same location as the input HPXML file.

Run openstudio workflow/run_simulation.rb -h to see all available commands/arguments.

Advanced Run

If additional flexibility is desired (e.g., specifying individual measure arguments, including additional OpenStudio measures to run alongside this measure in a workflow, etc.), create an OpenStudio Workflow (OSW) file. The OSW is a JSON file that will specify all the OpenStudio measures (and their arguments) to be run sequentially. A template OSW that simply runs the HPXMLtoOpenStudio and SimulationOutputReport measures on the workflow/sample_files/base.xml file can be found at workflow/template.osw.

For example: openstudio run -w workflow/template.osw

This will create a “run” directory with all input/output files. By default it will be found at the same location as the OSW file.

Outputs

In addition to the standard EnergyPlus outputs found in the run directory, a variety of high-level annual outputs are conveniently reported in the resulting run/results_annual.csv file.

Timeseries outputs can also be requested using either the Basic or Advanced approaches. When requested, timeseries outputs will be found in the run/results_timeseries.csv file.

See the SimulationOutputReport Measure section for a description of all available outputs available.