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 aws-verification@amazon.com. 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.

ClaireGyn / OpenStudio-analysis-spreadsheet