Link Search Menu Expand Document


URBANopt can now run optimization and sensitivity analysis algorithms by using the OpenStudio® Analysis Framework (OSAF). This is facilitated by using the OpenStudio Meta CLI from the Parametric Analysis Tool (PAT).

Example Optimization

An example file is available to demonstrate the optimization capability. In this example, electricity consumption was optimized over two variables: Reduce Electric Equipment Loads by Percentage and Lighting Power Reduction (%).

Follow the steps below to install the necessary dependencies and run the file with the openstudio_meta.

Installation and Usage

  1. Install PAT to have access to the openstudio_meta CLI and all gems necessary to run it. (it is assumed the install directory is c:/ParametricAnalysisTool-3.1.0)

  2. Start an OSAF server cluster on AWS, Google or Microsoft using the Helm charts. Note the server IP address; you will need it to submit the jobs.

  3. Once the cluster is up and running, open a terminal prompt or powershell in the directory with the URBANopt example files:

  4. The command to run the analysis is as follows. You will need to replace the values in angle brackets (< >) with your values.

         <path/to/PAT/ruby> <path/to/openstudio-meta> run_analysis --debug --verbose <path/of/URBANopt_NSGA.json> <Server IP address> -a nsga_nrel

    For example:

     C:\ParametricAnalysisTool-3.1.0\pat\ruby\bin\ruby.exe  C:\ParametricAnalysisTool-3.1.0\pat\OpenStudio-server\bin\openstudio_meta run_analysis --debug --verbose C:\PATProject\URBANopt_NSGA.json -a nsga_nrel

Once the job is submitted, you should be able to see the analysis on the Server Web Interface:

OSAF server output 1 OSAF server output 2 OSAF server output 3


The URBANopt analysis is defined using the OpenStudio OSA file. This allows you to define the names of the feature file and scenario file as well as the variables.


The following variables must be added to the OSA to perform and URBANopt analysis:

  • urbanopt (set to true)
  • feature_file (the feature file JSON to use)
  • scenario_file (the scenario file CSV to use)
  • urbanopt_variables (array of variable definitions)

Here is a snippet of the OSA: OSA variables for URBANopt analysis

And an example URBANopt variable definition: OSA URBANopt_variables definition

Objective Functions

A report key should be added to each objective function to specify whether it is operating at the feature level or the scenario level:

OSA objective functions

PAT can be used to generate a template OSA that can then be manually adjusted for an URBANopt analysis.

URBANopt, Copyright (c) 2019-2021, Alliance for Sustainable Energy, LLC, and other contributors. All rights reserved.