Roof Savings Calculator Web Service

Description

The Roof Savings Calculator now offers a web-service, which removes the need for manual inputs in a website and allows file-based integration with existing software systems, such as a business's quotation system, to automatically invoke simulations and estimate a customer's energy savings with different products or services. The web service is backed by an intelligent caching mechanism that can provide results in 3 seconds, rather than 2 minutes to run a simulation, by storing all previous simulations in a database and retrieving the result if the current request inputs match a stored result.

Web service Application Programming Interface (API)

  • Simulate: Simulate runs requested simulations or retrieves them from the database immediately if available. The simulate function takes a SOAP model, which can be constructed from an example XML model (see definitions for allowable values), and returns SOAP results that contains monthly energy usage for heating (electrical/gas), cooling, and fan.
  • Test: Test operates like the simulate function, but bypasses the database cache and provides additional information. The test function takes a SOAP model and returns a base-64-encoded string that is the contents of zip file. Decoding and writing that string to a file will give you a zip file containing the input model, full DOE-2 output file of simulation information, and the reduced-size readout table of monthly energy use.
  • Download: Download allows retrieval of previous results. The download function takes a scenario id and a version number and returns a structure containing the SOAP model and SOAP results. If the scenario id doesn't exist (or fails for some other reason), the function returns empty model/results.
  • Upload: Upload allows database storage of bulk simulations run on machines with a standalone RSC engine (which did not use the web service). The upload function takes a SOAP model and SOAP results and returns the scenario id after inserting the model and results into the database. This function only works if the server is set to allow updates.
See web-service-example.zip for more detail with runnable examples in Python and PHP. The excerpted line may be altered to use only a subset of the web service's capabilities: test_type = ['simulate', 'test', 'upload', 'download']


How to get started

  1. Download and install Python 2.7.6. Note that the RSC web service and required tools are not compatible with changes made in Python 3.3.3.
    1. Linux
      1. python -V to see if you have the correct version of Python already installed. Many of the current Linux distributions come with either Python 2.7 or Python 2.6 out of the box. If it replies "Python 2.7.6", the correct version of Python is installed.
      2. sudo [apt-get,yum] install python2.7 to download Python via Linux's package manager. If your package manager or other software on the machine requires other Python versions, see how to maintain two version of Python.
      3. Add Python to your system path.
    2. Windows
      1. Start=>"cmd"=>Enter to open a command prompt.
      2. python -V to see if already installed. If it replies "Python 2.7.6", the correct version of Python is installed and you can skip to step 2.
      3. Download Windows x86 MSI Installer (2.7.6)
      4. Run and follow on-screen instructions.
      5. Add Python to your system path.
  2. Download and install SOAP suds
    1. Follow instructions for Setuptools. It is recommended Windows users download ez_setup.py to C:\Python27\Scripts (or appropriate Python 2.7 path).
    2. Open a command prompt.
    3. cd Python27
    4. python Scripts/ez_setup.py
    5. cd Scripts
    6. easy_install pip
    7. pip install suds
      Pip can be used to easily download and install most recognized Python libraries.
      Suds allows python to consume web services.
  3. Test to make sure it works with the sample client
    1. Download web-service-example.zip. This contains an example input XML file with all 18 modifiable inputs and an XML output. It also contains example Python and PHP scripts for invoking and retrieving results using all methods available through the RSC web service.
    2. Unzip to any location
    3. Rename rscdemo.ba_ to rscdemo.bat
    4. Double-click rscdemo.bat and follow on-screen instructions.
      Note: you may also run python client_test.py
    Description: The sample client contains a building description in an example XML model with all 18 input fields that can be modified; see the definitions for allowable values. It also contains a Python script for invoking and retrieving results from the web service, but any modern programming language can be used.


Feedback

Please give us feedback with any issues, ideas, or suggestions for improvement regarding this service. Contact toutonln@ornl.gov if you require a response.

Brought to you by:

Department of Energy logo Environmental Protection Agency logo Oak Ridge National Lab logo Lawrence Berkley National Lab logo White Box Technologies logo California Energy Commission logo