Getting Started

So, you learned that buildstockbatch can be used to run ResStock simulations, but you have no idea where to start and what are all the things required for that. Great news, this page is written just for you!

First of all, let's familiarize ourselves with some terminology.

• EnergyPlus: This is the core building energy simulation engine.
• OpenStudio: OpenStudio is the building energy modeling and simulation application suite, that makes use of and comes bundled with EnergyPlus to run the actual simulation. It has range of tools, such as a sketchup plugin, model viewer, Parametric Analysis Tool (PAT), etc. to help model and simulate buildings.
• ResStock: ResStock is an OpenStudio project that leverages large public and private data sources to generate statistically representative building models covering the U.S. residential building stock. It is basically a collection of sampling tools, configuration files, weather files, and ResStock-specific OpenStudio measures. In GitHub, it's called OpenStudio-BuildStock. ResStock simulations are run either directly from OpenStudio, or using Buildstockbatch.
• Buildstockbatch: Before Buildstockbatch, ResStock simulations were run using OpenStudio PAT which would allow running thousands of OpenStudio simulations in parallel in the cloud. Buildstockbatch allows us to do the same using the command line. In addition, Buildstockbatch allows running parallel simulations in AWS, or on a local computer using Docker containers, or in NREL's supercomputer, Eagle. It handles generating sampling, allocating each processor/node to run a subset of simulations, aggregating the simulation results and copying them to a user-accessible location, and even uploading them to Amazon s3, and creating Amazon Athena tables so the simulation results can be queried.

In order to run ResStock simulations using buildstockbatch, you would need the current buildstockbatch repo and the ResStock repo (OpenStudio-BuildStock). Buildstockbatch will take care of downloading the correct version of OpenStudio inside a container and running the simulations so there is no need to download and install OpenStudio unless you want to run simulations directly using OpenStudio.

Installing Buildstockbatch

After you have cloned both of the repositories, you can follow the documentation here to continue with installing buildstockbatch on various platform.

Project definition file

Buildstockbatch requires that a project definition file be supplied for running the simulation. An example yaml project definition file is available here. The details on how to modify the yaml project definition file, and what different sections mean, is available in the documentation here. Specific help for running this file on Eagle is in this wiki.

Running the simulation

Now that the project definition file is ready, the simulation can be run. The details for how to run the simulation on various platform is explained in the documentation here.

Accessing the simulation results

If you have used AWS configuration in the project definition file, after the simulation is completed, the results will be available in Athena. TODO: Add how to query the data in Athena using smart_query or typing query in the console. TODO: Add how to navigate the output data folder structure in various platforms.