Installation
BuildStockBatch installations depend on the ResStock or ComStock
repository. Either git clone
it or download a copy of it or your fork or
branch of it with your projects.
Local
This method works for running the simulations locally. BuildStockBatch simulations are computationally intensive. Local use is only recommended for small testing runs.
OpenStudio Installation
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 .tar.gz
package
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.gz
extension. For OpenStudio 3.5.1 that isOpenStudio-3.5.1+22e1db7be5-Windows.tar.gz
.Extract it to a folder that you know.
Set the
OPENSTUDIO_EXE
environment variable to the path.C:\path\to\OpenStudio-3.5.1+22e1db7be5-Windows/bin/openstudio.exe
Here’s how to set a Windows environment Variable.
BuildStockBatch Python Library
Install Python 3.8 or greater for your platform.
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 conda. Make sure you configure your virtual environment to use Python 3.8 or greater. Then activate your environment.
Standard Install
If you are just going to be using buildstockbatch, not working on it, install like so:
cd /path/to/buildstockbatch
python -m pip install -e .
Developer Install
If you are going to be working on and contributing back to buildstockbatch, install as follows after cloning the repository and creating and activating a new python or conda environment.
cd /path/to/buildstockbatch
python -m pip install -e ".[dev]"
pre-commit install
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.
Install the AWS CLI version 2
Configure the AWS CLI. (Don’t type the
$
in the example.)You may need to change the Athena Engine version for your query workgroup to v2 or v3.
Kestrel
The most common way to run buildstockbatch on Kestrel will be to use a pre-built python environment. This is done as follows:
module load python
source /kfs2/shared-projects/buildstock/envs/buildstock-20XX.XX.X/bin/activate
You can get a list of installed environments by looking in the envs directory
ls /kfs2/shared-projects/buildstock/envs
Developer Installation
For those doing development work on buildstockbatch (not most users), a new python environment that includes buildstockbatch is created with the bash script create_kestrel_env.sh in the git repo that will need to be cloned onto Kestrel. The script is called as follows:
module load git
git clone git@github.com:NREL/buildstockbatch.git
cd buildstockbatch
bash create_kestrel_env.sh env-name
This will create a directory /kfs2/shared-projects/buildstock/envs/env-name
that contains the python environment with buildstockbatch installed. This
environment can then be used by any user.
If you pass the -d
flag to that script, it will install the buildstockbatch
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.
The -d
and -e
flags can also be combined if desired
bash create_kestrel_env.sh -d -e /projects/enduse/envs mydevenv
Amazon Web Services (Beta)
Warning
The AWS version of buildstockbatch is in active development. Use at your own risk. It’s provided as-is with no promise of support.
Docker
Install either Docker Desktop of Docker Engine for your platform.
BuildStockBatch Python Library
Install the buildstockbatch python library as described in BuildStockBatch Python Library for
the local installation. You’ll need to install with the aws
extra as follows.
For a standard installation
cd /path/to/buildstockbatch
python -m pip install -e ".[aws]"
For developer installation
cd /path/to/buildstockbatch
python -m pip install -e ".[dev,aws]"
pre-commit install
AWS User Configuration
Follow the instructions for AWS User Configuration on the local install. Your AWS user account or role needs to have pretty expansive permissions to create IAM roles, VPCs, compute resources, etc.
Todo
Define permission set needed.
For NREL users, the typical resbldg-user
or developers
role in the
nrel-aws-resbldg account is probably insufficient.
Google Cloud Platform
Per-user setup
One-time setup that each user needs to do on the workstation from which they’ll launch and manage BuildStockBatch runs.
Install Docker. This is needed by the script to manage Docker images (pull, push, etc).
Get BuildStockBatch and set up a Python environment for it using the BuildStockBatch Python Library instructions above. (i.e., create a Python virtual environment, activate the venv, and install buildstockbatch with the command below.)
Install with the
[gcp]
option to include GCP-specific dependencies:
cd /path/to/buildstockbatch python -m pip install -e ".[gcp]"
Download/Clone ResStock or ComStock.
Set up GCP authentication.
Option 1: Create and download a Service Account Key.
Add the location of the key file as an environment variable; e.g.,
export GOOGLE_APPLICATION_CREDENTIALS="~/path/to/service-account-key.json"
. This can be done at the command line (in which case it will need to be done for every shell session that will run BuildStockBatch, and it will only be in effect for only that session), or added to a shell startup script (in which case it will be available to all shell sessions).
Option 2: Install the Google Cloud CLI and run the following:
gcloud config set project PROJECT gcloud auth application-default login gcloud auth login gcloud auth configure-docker REGION-docker.pkg.dev