Set Up the Analysis Project

At the top level of the ResStock repository you just downloaded, you will see two analysis project folders:

  • project_resstock_national
  • project_resstock_multifamily
  • project_resstock_testing

Open PAT, select “Open Existing Project”, and choose the project_resstock_national directory. You may be asked if you want “mongod” to accept incoming connections. Select “Allow”.

You will leave dropdown options for Algorithmic Method, Default Seed Model, and Default Weather File alone. Additionally, you will leave the settings in Algorithm Settings, Additional Analysis Files, and Server Scripts alone for most analyses.


The number of simulations per upgrade scenario is set in Build Existing Model.

Additional Analysis Files

Ensure that you have the following directories included to be uploaded to the server:


Server Scripts

Although you will leave these settings alone for most analyses, you do have the ability to change arguments for initialization and finalization scripts that are run on the remote server. In the case you do NOT want to run savings calculations for upgrades or include additional outputs, see Server Finalization Script. In the case you want to change the set of epw weather files used for your project, see Worker Initialization Script.


Server Initialization Script

Ignore this for now.

Server Finalization Script

After all datapoints have been simulated, this script calls a method for calculating the incremental cost and savings for upgrades. You can specify one or more reference scenarios for the cost and energy subtraction by entering "reference", "upgrade" (each enclosed in double quotation marks and separated by a comma) pair(s) (one argument for each pair) in the Script Arguments section (see image above).

upgrade indicates the upgrade scenario for calculating savings, and should exactly match the “Upgrade Name” string for one of the upgrade measures (see Apply Upgrade).

reference indicates the upgrade scenario to be used as the reference. Enter “BASE” to use the “as is” existing housing stock baseline as the reference (typical for envelope upgrades; see example above). Enter an “Upgrade Name” string for one of the upgrade measures to use an upgrade scenario as the reference savings and costs to be subtracted from the upgrade scenario to calculate incremental savings and costs (typical for equipment upgrades where there exists a minimum efficiency standard).

An example of this latter situation is when an old SEER 8 AC is replaced at wear out, and a user wishes to calculate the incremental savings and cost of upgrading it to SEER 18 compared to a SEER 14 AC (U.S. federal minimum efficiency in southern states).

Entering no pairs will default to calculating savings for all upgrades relative to the baseline building. Note that if you specify one scenario in this way, then you must explicitly define all scenario pairs, even cases where the reference is the baseline (using “BASE”, “upgrade”).

Savings are calculated as follows:;Energy&space;=&space;Energy_{upgrade}&space;-&space;Energy_{reference};InitialCost&space;=&space;InitialCost_{upgrade}&space;-&space;InitialCost_{reference}


By default this script also attaches additional outputs to the results.csv file, including:

  • reportable domain (according to RECS 2009)
  • source energy (using conversion factors from BSR/ASHRAE Standard 105-2013)
  • eGRID subregion (see the entire eGRID subregion map)
  • utility bill calculations (for now using simple average flat rates for each state)
  • simple payback
  • net present value
  • savings-to-investment ratio

A new csv file, results_savings.csv, containing upgrade savings and additional outputs is produced. You can retrieve this file by downloading the Seed Zip File from the OpenStudio Cloud Management Console analysis page:


Worker Initialization Script

Something you might want to change is the set of weather files used with your project. To update the argument for the path to the zip file containing epw weather files, open the Server Scripts box on the Measures Selection tab.

Look for the Script Arguments box corresponding to the Worker Initialization Script. By default, this argument value points to the set of weather files corresponding to the specific project (i.e., set of housing_characteristics) you are working with. For example, the project_resstock_national project folder will by default use the set of weather files with national geographic coverage. In the illustration above, the argument value path points to a zipped file stored in the epwweatherfiles bucket on Amazon S3. You should have read-only access to objects in this bucket.

You can control what set of weather files are unpacked and accessible on the remote server by changing the argument value for this initialization script. If you wish to change this argument value to point to a different file in the S3 bucket, replace the path’s basename with the path of the new file. If the desired file does not exist in the S3 bucket, you will need to zip up a set of weather files and upload it to some location of your choice (e.g., your own S3 bucket). Be sure to change the entire argument value path to point to this chosen file location.

To zip and upload new weather files:

  • First ensure that the weather files you will be using do not already exist in the S3 bucket. If they do, just point to the appropriate zip that already contains your desired weather files.
  • If they do not, on your local computer highlight all the new epw weather files and compress them into a single zip file. (Your zip should contain only files with either the “.epw” or “.ddy” extension.)
  • Upload your newly zipped file that contains the weather files to your new location.
  • Go back to your project and update the argument value to the path of the newly uploaded file.


Changing this path from the default will most likely require additional changes to your project. Any weather file names in your housing_characteristics folder’s tsv files will need to be updated to reflect those in the S3 bucket file. Any simulation on the remote server that points to an invalid weather file path will fail.

Worker Finalization Script

Ignore this for now.

OpenStudio Measures

Continuing on the Measures Selection tab, scroll down to the OpenStudio Measures section. This section is where you will define the parameters of the analysis including the baseline case and any upgrade scenarios.

Simulation Controls

Using this measure you can set the simulation timesteps per hour, as well as the run period begin month/day and end month/day. By default the simulations use a 10-min timestep (i.e., the number of timesteps per hour is 6), start on January 1, and end on December 31.


Build Existing Model

This measure creates the baseline scenario. It incrementally applies OpenStudio measures (located in the resources directory, which should be at the same level as your project directory) to create residential building models. Set the following inputs:

Building ID – Max
This sets the number of simulations to run in the baseline and each upgrade case. For this tutorial I am going to set this to 1000. Most analyses will require more, but we’re going to keep the total number small for simulation time and cost.
Number of Buildings Represented
The total number of buildings this sampling is meant to represent. This sets the weighting factors. For the U.S. single-family detached housing stock, this is 80 million homes.
Sample Weight of Simulation
The number of buildings each simulation represents. Total number of buildings / Number of simulations. This argument is optional (it is only needed for running simulations on NREL HPC), so you can leave it blank.
Downselect Logic
Logic that specifies the subset of the building stock to be considered in the analysis. Specify one or more parameter|option as found in the resources/options_lookup.tsv. (This uses the same syntax as the Apply Upgrade measure.) For example, if you wanted to only simulate California homes you could enter Location Region|CR11 in this field (CR refers to “Custom Region”, which is based on RECS 2009 reportable domains aggregated into groups with similar climates; see the entire custom region map).


Manual Sampling: To run the sampling script yourself, from the command line execute, e.g. ruby resources/run_sampling.rb -p project_resstock_national -n 10000 -o buildstock.csv, and a file buildstock.csv will be created in the resources directory.

If a custom buildstock.csv file is located in a project’s housing_characteristics directory when you run the PAT project, it will automatically be used to generate simulations. If it’s not found, the run_sampling.rb script will be run automatically on OpenStudio-Server to create one. You’ll also want to make sure that the number of buildings in the sampling csv file matches the max value for the Building ID argument in the Build Existing Model, as that tells OpenStudio how many datapoints to run. (For each datapoint, the measure will then look up its building description from the sampling csv.)

You can use this manual sampling process to downselect which simulations you want to run. For example, you can use the command above to generate a buildstock.csv for the entire U.S. and then open up this file in Excel and delete all of the rows that you don’t want to simulate (e.g., all rows that aren’t in New York). Keep in mind that if you do this, you will need to re-enumerate the “Building” column as “1” through the number of rows.

Apply Upgrade

Each “Apply Upgrade” measure defines an upgrade scenario. An upgrade scenario is a collection of options exercised with some logic and costs applied. In the simplest case, we apply the new option to all houses. The available upgrade options are in resources/options_lookup.tsv in your git repository.

For this example, we will upgrade all windows by applying the Windows|Low-E, Triple, Non-metal, Air, L-Gain option to all houses across the country. We do this by entering that in the Option 1 box on the Apply Upgrade measure. Also, we’ll give the upgrade scenario a name: “Triple-Pane Windows” and a cost of $40/ft2 of window area by entering the number in Option 1 Cost Value and selecting “Window Area (ft^2)” for Option 1 Cost Multiplier.


For a full explanation of how to set up the options and logic surrounding them, see Upgrade Scenario Configuration.

Measures can be skipped in an analysis without losing their configuration. For this tutorial we will skip the second measure of applying wall insulation. To do so, select the Apply Upgrade 2 measure, open it, and check the box Skip this measure.


Reporting Measures

Scroll down to the bottom on the Measures Selection tab, and you will see the Reporting Measures section. This section is where you can request timeseries data and utility bills for the analysis. In general, reporting measures process data after the simulation has finished and produced results. As a note, make sure that the Timeseries CSV Export and Utility Bill Calculations measures are placed before the Server Directory Cleanup measure.

Building Charactertistics Report

Leave this alone.

Simulation Output Report

Leave this alone.

Timeseries CSV Export

If you do not need the timeseries data for your simulations, you can skip this measure to save disk space. Otherwise, one csv file per datapoint will be written containing end use timeseries data for their model. After downloading all datapoints to your project’s localResults folder, each datapoint’s enduse_timeseries.csv file will be contained in a zipped file along with all other simulation input and output files.


End uses include:

  • heating [electric/gas/propane/oil] [kWh/kBtu/kBtu/kBtu]
  • cooling [kWh]
  • interior lights [kWh]
  • exterior lights [kWh]
  • interior equipment [electric/gas/propane/oil] [kWh/kBtu/kBtu/kBtu]
  • fans [kWh]
  • pumps [kWh]
  • water heating [electric/gas/propane/oil] [kWh/kBtu/kBtu/kBtu]
  • water [gal]
  • pv [kWh]
Reporting Frequency

The timeseries data will be reported at hourly intervals unless otherwise specified. Alternative reporting frequencies include:

  • timestep
  • daily
  • monthly
  • run period

Setting the reporting frequency to “timestep” will give you interval output equal to the zone timestep set by the “Simulation Controls” measure. Thus, this measure will produce 10-min interval output when you select “timestep” and leave the “Simulation Controls” measure at its default settings. Setting the reporting frequency to “detailed” will give you interval output equal to the calculation step (i.e., either zone timestep or HVAC system timestep).

Include End Use Subcategories

Select this to include end use subcategories. The default is to not include end use subcategories. End use subcategories include:

  • refrigerator [kWh]
  • dishwasher [kWh]
  • cooking range [electric/gas/propane] [kWh/kBtu/kBtu]
  • clothes washer [kWh]
  • clothes dryer [electric/gas/propane] [kWh/kBtu/kBtu]
  • ceiling fan [kWh]
  • mech vent house fan [kWh]
  • mech vent range fan [kWh]
  • mech vent bath fan [kWh]
  • heating supply fan [kWh]
  • cooling supply fan [kWh]
  • misc plug loads [kWh]
  • extra refrigerator [kWh]
  • freezer [kWh]
  • pool heater [electric/gas] [kWh/kBtu]
  • pool pump [kWh]
  • hot tub heater [electric/gas] [kWh/kBtu]
  • hot tub pump [kWh]
  • well pump [kWh]
  • gas fireplace [kBtu]
  • gas grill [kBtu]
  • gas lighting [kBtu]
Output Variables
If you choose to report any output variables (e.g., “Zone Air Temperature” or “Site Outdoor Air Humidity Ratio”), enter a comma-separated list of output variable names. A list of available output variables can be viewed in EnergyPlus’s .rdd file. One csv file, appropriately called “output_variables.csv”, will be downloaded alongside the “enduse_timeseries.csv” file.

Utility Bill Calculations

This measure is currently under construction. Do not include it in your PAT analysis.