OpenStudio::Workflow
Run an EnergyPlus simulation using a file-based workflow that is read from a Local or MongoDB adapter.
Installation
The OpenStudio Workflow Gem has the following dependencies:
- Ruby 2.0
- OpenStudio with Ruby 2.0 bindings
- EnergyPlus 8.2 (assuming OpenStudio >= 1.5.4)
- MongoDB if using MongoDB Adapter (or when running rspec)
OpenStudio needs to be installed
and in your path. On Mac/Linux it is easiest to add the following to your .bash_profile or /etc/profile.d/
export OPENSTUDIO_ROOT=/usr/local
export RUBYLIB=$OPENSTUDIO_ROOT/lib/ruby/site_ruby/2.0.0
Add this line to your application's Gemfile:
gem 'OpenStudio-workflow'
Use this line if you want the bleeding edge:
gem 'OpenStudio-workflow', github: 'NREL/OpenStudio-workflow-gem', branch: 'EnergyPlus-8.2.0'
And then execute:
Mac/Linux:
$ bundle
Windows (avoids native extensions):
$ bundle install --without xml profile
Or install it yourself as:
$ gem install OpenStudio-workflow
Usage
Note that the branches of the Workflow Gem depict which version of EnergyPlus is in use. The develop branch at the moment should not be used.
There are currently two adapters to run OpenStudio workflow. The first is a simple Local adapter allowing the user to pass in the directory to simulation. The directory must have an analysis/problem JSON file and a datapoint JSON file. The workflow manager will use these data (and the measures, seed model, and weather data) to assemble and execute the standard workflow of (preflight->openstudio measures->energyplus->postprocess).
r = OpenStudio::Workflow.load 'Local', '/home/user/a_directory',
r.run
The workflow manager can also use MongoDB to receive instructions on the workflow to run and the data point values.
Caveats and Todos
Caveats
- There are currently several hard coded workflow options
- Must use OpenStudio with Ruby 2.0 support
- Using MongoDB as the Adapter requires a command line zip (gnuzip) utility
Todos
- Read the analysis.json file to determine the states that are going to run instead of (or in addition to) passing them into the constructor
- Implement better error handling with custom exception classes
- ~Implement a different measure directory, seed model directory, and weather file directory option~
- ~Dynamically add other "states" to the workflow~
- ~~Create and change into a unique directory when running measures~~
- ~~Implement Error State~~
- ~~Implement MongoDB Adapter~~
- ~~Implement remaining Adapter states (i.e. communicate success, communicate failure etc~~
- Add a results adapter to return a string as the last call based on the source of the call. (e.g. R, command line, C++, etc).
- Implement a logger in the Adapters, right now they are unable to log
- Hook up the measure groups based workflows
- ~~Add xml workflow item~~
Testing and Development
Depending on what adapter is being tested it may be preferable to skip installing various gems. This can be done by calling
bundle install --without mongo
On Windows it is recommended to bundle without mongo nor ci as they may require native extensions.
bundle install --without mongo ci
Testing
Run rspec
or rake
to execute the tests.
Contributing
- Fork it ( https://github.com/NREL/OpenStudio-workflow/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
Development
If you are testing changes to OpenStudio source code and want to test these on the Vagrant machine you can use the source configuration. This creates a new virtual machine which can be accessed by adding the name 'source' to the end of standard Vagrant commands. To set up this machine, build a custom version of OpenStudio, and install that version for testing follow these steps:
- vagrant up source
- vagrant ssh source
- sudo apt-get install dpkg-dev git cmake-curses-gui qt5-default libqt5webkit5-dev libboost1.55-all-dev swig ruby2.0 libssl-dev libxt-dev doxygen graphviz
- sudo ln -s /usr/lib/x86_64-linux-gnu/libruby-2.0.so.2.0.0 /usr/lib/x86_64-linux-gnu/libruby.so.2.0 ** Install clang (OPTIONAL): ** wget -O - http://llvm.org/apt/llvm-snapshot.gpg.key|sudo apt-key add - ** sudo apt-add-repository 'deb http://llvm.org/apt/trusty/ llvm-toolchain-trusty-3.5 main' ** sudo apt-get update ** sudo apt-get install clang-3.5 ** echo 'export CC=/usr/bin/clang-3.5' >> ~/.bashrc ** echo 'export CXX=/usr/bin/clang++-3.5' >> ~/.bashrc ** source ~/.bashrc
- cd /home/vagrant
- git clone https://github.com/NREL/OpenStudio.git openstudio
- cd openstudio
- git checkout your_branch_name
- mkdir build
- cd build
- cmake .. -DBUILD_PACKAGE=TRUE -DCMAKE_INSTALL_PREFIX=$OPENSTUDIO_ROOT -DRUBY_EXECUTABLE=/usr/local/rbenv/versions/2.0.0-p481/bin/ruby
- make -j4
To install do either:
- cd OpenStudioCore-prefix/src/OpenStudioCore-build/
- sudo make install
or:
- make package
- sudo ./OpenStudio-1.5.1.02b7131b4c-Linux.sh --prefix=/usr/local --exclude-subdir --skip-license
Next you have to do this:
- export RUBYLIB=/usr/local/Ruby
- export LD_LIBRARY_PATH=/usr/local/lib
Then you can test that you are using your build by comparing the output of these two commands:
- ruby -e "require 'openstudio'" -e "puts OpenStudio::openStudioLongVersion"
- git rev-parse --short HEAD