Link Search Menu Expand Document


Advanced developers may choose to customize the URBANopt REopt Gem. For example, more attributes are returned from the REopt Lite API and saved to disk than currently can be recorded in a Feature or Scenario Report. In these cases, developers will want to clone the URBANopt REopt Gem and possibly the URBANopt Reporting Gem and make modifications to these codebases. Such changes can be made accessible through CLI commands (installed from a cloned URBANopt CLI repo) or a local project. See Developer Resources for more information about setting up local gems and installing them through modifications to your project’s Gemfile.

Adding additional REopt Lite Responses to your Feature and Scenario Reports

To include additional REopt Lite API responses to your Feature and Scenario Reports follow the steps we outline below for adding optimal lifecycle costs from a REopt Lite API response to Feature and Scenario Reports.

  1. We’ll need to update the Feature and Scenario Report schema to allow for new attributes, so clone URBANopt Reporting Gem to your local machine.

    $ git clone
  2. Later we’ll need to also update the URBANopt REopt Gem to parse these additional attributes from the REopt Lite API response, so clone this now in the same directory as the URBANopt Scenario Gem repository with:

    $ git clone
  3. Let’s first update the URBANopt Reporting Gem. The distributed_generation schema used by Feature and Scenario Reports is defined in this repository and needs to handle new attibutes.

    We’ll add lcc_us_dollars here as an example.

    First, open urbanopt-reporting-gem/lib/urbanopt/reporting/default_reports/distributed_generation.rb

    Next, in the DistributedGeneration class add a new attribute accessor:

    module URBANopt
        module Reporting
          module DefaultReports
          # Onsite distributed generation system (i.e. SolarPV, Wind, Storage, Generator) design attributes and financial metrics.
          class DistributedGeneration
            # _Float_ - Lifecycle costs for the complete distributed generation system in US Dollars
            attr_accessor :lcc_us_dollars

    Then, within the initialize function parse the attribute when the object is instantiated:

            def initialize(hash = {})
              hash.delete_if { |k, v| v.nil? }
              @lcc_us_dollars = hash[:lcc_us_dollars]

    Also, within the to_hash function, make sure the attribute will be exported when the report is saved:

            def to_hash
              result = {}
              result[:lcc_us_dollars] = @lcc_us_dollars if @lcc_us_dollars

    Finally, within the merge_distributed_generation function, make sure the attribute will be added when two reports are combined:

            def self.merge_distributed_generation(existing_dgen, new_dgen)
               existing_dgen.lcc_us_dollars = add_values(existing_dgen.lcc_us_dollars, new_dgen.lcc_us_dollars)

    You’re now all set updating the distributed_generation schema.

  4. Let’s next update URBANopt REopt Gem to load lifecycle costs from the REopt Lite API responses into the Feature and Scenario Report distributed_generation schema’s lcc_us_dollars attribute.

    First, in urbanopt-reopt-gem/Gemfile make sure that the urbanopt-reporting gem is loaded as follows:

        gem 'urbanopt-reporting', path: '../urbanopt-reporting-gem'

    This will ensure that the urbanopt-sceanrio gem that the urbanopt-reopt gem uses includes the schema we just modified.

    Note: You can alternatively specify a gem from a branch on github as follows:

        gem 'urbanopt-reporting', github: '<repo address>', branch: '<branch name>''

    Next, in urbanopt-reopt-gem/lib/reopt/feature_report_adapter.rb in the update_feature_report function, parse the REopt Lite API response:

        # Update distributed generation sizing and financials
        feature_report.distributed_generation.lcc_us_dollars = reopt_output['outputs']['Scenario']['Site']['Financial']['lcc_us_dollars'] || 0

    For an example of a REopt Lite API response refer to this file. Also, the REopt API ouput schema is documented here.

    Finally, in urbanopt-reopt-gem/lib/reopt/scenario_report_adapter.rb in the update_scenario_report function, parse the lifecycle cost from the REopt Lite API response:

        # Update distributed generation sizing and financials
        scenario_report.distributed_generation.lcc_us_dollars = reopt_output['outputs']['Scenario']['Site']['Financial']['lcc_us_dollars'] || 0

    You are now ready to navigate to the urbanopt-reopt-gem folder and run:

    $ bundle install
    $ bundle update
  5. Now, when you reference this modified urbanopt-reopt implementation you can access the lifecycle costs from feature_report.distributed_generation.lcc_us_dollars or scenario_report.distributed_generation.lcc_us_dollars. The lifecycle costs will also be included when a Feature or Scenario Report is saved.

URBANopt, Copyright (c) 2019-2020, Alliance for Sustainable Energy, LLC, and other contributors. All rights reserved.