Analysis Examples

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

  

• Timeseries Calibration

  

• Optimization

  

• Design of Experiments

  

• Uncertainty Quantification

  

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 https://github.com/NREL/OpenStudio-server. The architecture of the OS-Server:

Spreadsheet User Guide

See https://github.com/NREL/OpenStudio-analysis-spreadsheet/blob/develop/documentation/spreadsheet_userguide_prerelease.pdf

List of OpenStudio Server Amazon AMIs Versions

See http://s3.amazonaws.com/openstudio-resources/server/api/v2/amis.json

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.

Instructions

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: http://dl.bintray.com/oneclick/rubyinstaller/rubyinstaller-2.0.0-p353.exe?direct
• 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 HTTP_PROXY=proxy.a.com:port  ( e.g. 192.168.0.1:2782 or a.b.com:8080 )
set HTTP_PROXY_USER=user 
set HTTP_PROXY_PASS=password

Installation

• 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.

Downloading

• Using Git

  • Checkout

    git clone https://github.com/NREL/OpenStudio-analysis-spreadsheet.git
    cd <path to download>
    bundle 
    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
    bundle
    

    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

  • Download the latest release from https://github.com/NREL/OpenStudio-analysis-spreadsheet/releases
  • Unzip into a directory
  • Go to unzipped directory in a command/terminal window

Running Analyses

• Creating and Running on the Cluster

  • New cluster

    cd <path_to_downloaded_directory>
    bundle
    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:

C:\Ruby<RUBY_VERSION>\lib\ruby\gems\<RUBY_VERSION>\gems\libxml-ruby-<GEM_VERSION>\lib\libs

Add this path to your environment variables.

Troubleshooting

AWS

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 [email protected]. 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 github.com, rubygems.org, or aws.amazon.com, make sure that the path to these sites are not blocked. Some more information can be found in this issue.