BuildStockBatch installations depend on the ResStock or ComStock repository. Either
clone it or download a copy of it or your fork or branch of it with your
This method works for running the simulations locally. BuildStockBatch simulations are computationally intensive. Local use is only recommended for small testing runs.
Download and install the OpenStudio release that corresponds to your operating system and the release of ResStock or ComStock you are using.
It’s common to need a couple different versions of OpenStudio available for
different analyses. This is best achieved by downloading the
for your operating system and unzipping it into a folder rather than installing
it. To let BuildStockBatch know which OpenStudio to use, pass the path as the
OPENSTUDIO_EXE environment variable.
For example to get OpenStudio 3.5.1 on an Apple Silicon Mac
# Make a directory for your openstudio installations to live in mkdir ~/openstudio cd ~/openstudio # Download the .tar.gz version for your operating system, x86_64 for an Intel mac # This can also done using a browser from the OpenStudio releases page curl -O -L https://github.com/NREL/OpenStudio/releases/download/v3.5.1/OpenStudio-3.5.1+22e1db7be5-Darwin-arm64.tar.gz # Extract it tar xvzf OpenStudio-3.5.1+22e1db7be5-Darwin-arm64.tar.gz # Optionally remove the tar file rm OpenStudio-3.5.1+22e1db7be5-Darwin-arm64.tar.gz # Set your environment variable to point to the correct version # This will only work for the current terminal session # You can also set this in ~/.zshrc to make it work for every terminal session export OPENSTUDIO_EXE="~/openstudio/OpenStudio-3.5.1+22e1db7be5-Darwin-arm64/bin/openstudio"
For Windows, the process is similar.
Download the Windows OpenStudio release for windows with the
.tar.gzextension. For OpenStudio 3.5.1 that is
Extract it to a folder that you know.
OPENSTUDIO_EXEenvironment variable to the path.
C:\path\to\OpenStudio-3.5.1+22e1db7be5-Windows/bin/openstudio.exeHere’s how to set a Windows environment Variable.
BuildStockBatch Python Library
Install Python 3.8 or greater for your platform. Either the official distribution from python.org or the Anaconda distribution (recommended).
Get a copy of BuildStockBatch either by downloading the zip file from GitHub or cloning the repository.
Optional, but highly recommended, is to create a new python virtual environment if you’re using python from python.org, or to create a new conda environment if you’re using Anaconda. Make sure you configure your virtual environment to use Python 3.8 or greater. Then activate your environment.
Install the library by doing the following:
cd /path/to/buildstockbatch python -m pip install -e . --user
AWS User Configuration
To upload BuildStockBatch data to AWS at the end of your run and send results to AWS Athena, you’ll need to configure your user account with your AWS credentials. This setup only needs to be done once.
BuildStock Batch is preinstalled on Eagle. To use it, ssh into Eagle, activate the appropriate conda environment:
module load conda source activate /shared-projects/buildstock/envs/buildstock-X.X
You can get a list of installed environments by looking in the envs directory
AWS User Configuration
To use the automatic upload of processed results to AWS Athena, you’ll need to configure your user account with your AWS credentials. This setup only needs to be done once.
First, ssh into Eagle, then issue the following commands
module load conda source activate /shared-projects/buildstock/envs/awscli aws configure
Follow the on screen instructions to enter your AWS credentials. When you are done:
For those doing development work on BuildStock Batch (not most users), a new conda environment that includes buildstock batch is created with the bash script create_eagle_env.sh in the git repo that will need to be cloned onto Eagle. The script is called as follows:
bash create_eagle_env.sh envname
This will create a directory
contains the conda environment with BuildStock Batch installed. This environment
can then be used by any user.
If you pass the
-d flag to that script, it will install the buildstock-batch
package in development mode meaning that any changes you make in your cloned
repo will immediately be available to that environment. However, it means that
only the user who installed the environment can use it.
If you pass the flag
-e /projects/someproject/envs, it will install the
environment there instead of the default location. This is useful if you need a
specific installation for a particular project.
-e flags can also be combined if desired
bash create_eagle_env.sh -d -e /projects/enduse/envs mydevenv
Amazon Web Services (Beta)
The AWS version of buildstockbatch is currently broken. A remedy is in progress. Thanks for your patience.
The installation instructions are the same as the Local
installation. You will need to use an AWS account with appropriate permissions.
The first time you run
buildstock_aws it may take several minutes,
especially over a slower internet connection as it is downloading and building a docker image.