The OpenStudio Analysis Spreadsheet is a front-end for the OpenStudio Server, allowing for users to create large-scale cloud analyses using OpenStudio measures.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
post_processing typos and cleanup Jan 25, 2015
projects update spreadsheets to enforce measure order by type Apr 6, 2017
worker_scripts update to new images with energyplus 8.2 Jan 6, 2015
.gitignore update dependencies May 6, 2015
.rubocop.yml update to new images with energyplus 8.2 Jan 6, 2015
Gemfile.lock Merging in updates. Apr 12, 2017
Rakefile Merge branch 'dockerize' of… Feb 17, 2017

Analysis Examples

Dependency Status

The OpenStudio Analysis Spreadsheet uses OpenStudio's Analysis & AWS gem to setup and run simulations on an Amazon OpenStudio Cluster. Example analyses are:

  • Monthly Utility Data Calibration

    alt tag

  • Timeseries Calibration

    alt tag alt tag

  • Optimization

    alt tag

  • Design of Experiments

    alt tag

  • Uncertainty Quantification

    alt tag

Available Algorithms

  • NSGA2 (Nondominated Sorting Genetic Algorithm 2) multi-objective optimization
  • SPEA2 (Strength Pareto Evolutionary Algorithm 2) multi-objective optimization
  • RGenoud (R version of GENetic Optimization Using Derivaties) single-objective optimization
  • PSO (Particle Swarm Optimization) single-objective optimization
  • Optim (Gradient based) single-objective optimization
  • Latin Hypercube Sampling (LHS)
  • Full Factorial Design of Experiments
  • Parallel Batch Running
  • Preflight [min/median/max] test
  • Single Run
  • Repeat Run

What is OpenStudio Server?

The analysis spreadsheet submits jobs/problems to the OpenStudio Server The architecture of the OS-Server:

alt tag

Spreadsheet User Guide


List of OpenStudio Server Amazon AMIs Versions


Analysis Spreadsheet Project Layout

  • Analysis - These are the exported files that are uploaded to the cloud server to run.
  • Projects - List of projects in the form of analysis spreadsheets. These are the file that you should edit and copy.
  • Seeds - Example seed OSM models.
  • Weather - Where to dump other weather files of interest.
  • Measures- Local cache of BCL measures.


Currently the execution of this project requires command line (terminal) access.

  • Make sure to have Ruby 2.0 installed and the bundler gem. Check your version of Ruby by running ruby --version.
  • Does not currently work with Ruby 2.2.
  • Note that if you are a Windows user, install the 32-bit version of Ruby from here:
  • If you are behind a proxy then make sure to export the environment variables. For windows you can add them to your environment or at the command line using. Similar for Mac/Linux except use export.
set  ( e.g. or )
set HTTP_PROXY_PASS=password


  • Verify Ruby version and install RubyGem's Bundler. In a command line call the method below.

    ruby --version
    gem install bundler

    Note Mac 10.9 users using system Ruby 2.0 will need to run sudo bundle if you are using system's Ruby.


  • Using Git

    • Checkout

      git clone
      cd <path to download>
      bundle exec rake run

      Note Mac 10.9 users using system Ruby 2.0 will need to run sudo bundle if you are using system's Ruby.

    • Update

      git pull

      Note Mac 10.9 users using system Ruby 2.0 will need to run sudo bundle if you are using system's Ruby.

  • Direct Download

Running Analyses

  • Creating and Running on the Cluster

    • New cluster

      cd <path_to_downloaded_directory>
      bundle exec rake run
    • Pre-configured cluster from Spreadsheet

      If the cluster has already been created using the spreadsheet and the cluster is still running, then by rerunning the command below will result in the submission of more analyses to the existing cluster.

      bundle exec rake run
    • Pre-configured cluster from external source

      If the cluster has been created using other provisioners (e.g. docker, Chef, HPC ) and the IP address is known, then run the following command to submit the analysis.

      bundle exec rake run_custom[http://<ip-address>:8080]
  • Select the appropriate analysis/project from the list provided after running the above command.

    Note the first time you run this you will need to add in your AWS credentials in your <home-dir>/aws_config.yml file. The file should only be readable by you as it contains your AWS secret key for access. The YML file needs to look like:

    access_key_id: YOUR_ACCESS_KEY_ID
    secret_access_key: YOUR_SECRET_ACCESS_KEY

    After this has been added, then rerun the correct "Running the Analysis" methods from above.

  • To add a new project (spreadsheet)

    Copy and rename one of the templates in the projects directory.

  • Reset analysis (removes the server files)

    NOTE: this does not kill AWS instances. You must do that manually via the AWS console Note: this has been disabled.

    bundle exec rake clean

Windows Specific Installation Steps

If you have any issues getting gem dependencies installed, it may be helpful to remove all your gems and start over.
To do this run the command below (note that you will need to reinstall bundler after removing all gems).

ruby -e "`gem list`.split(/$/).each { |line| puts `gem uninstall -Iax #{line.split(' ')[0]}` unless line.empty? }"

If you are using XML (via the BCL gem) then by default the path to the libxml DLLs is not included. You will need to add the path by hand. To do this find where the DLLs are by going to your Ruby installation directory and making sure they exist. Typically the installation will be something like:


Add this path to your environment variables.



If you just created your Amazon Web Service account and try to run the analysis, you may notice an error regarding verification of the account (see below).

Aws::EC2::Errors::PendingVerification: Your account is currently being verified. 
Verification normally takes less than 2 hours. Until your account is verified, 
you may not be able to launch additional instances or create additional volumes. 
If you are still receiving this message after more than 2 hours, please let us 
know by writing to We appreciate your patience.

If this happens, wait a couple hours and try again. You can also contact Amazon to check if they have verified your account.

Sudo Rights and Mac/Linux

Make sure that you do not run the bundle exec rake run command as sudo. If you do then you will see a permission error on writing to either the .pem or .log files. If this happens then do the following:

  • Run sudo rake clean
  • Remove the ~/.aws.log from your home directory. sudo rm -f ~/.aws.log

Access Errors

If you experience issues accessing,, or, make sure that the path to these sites are not blocked. Some more information can be found in this issue.