Prep v0.7.0

.github/workflows/nightly_ci_build.yml

@@ -0,0 +1,51 @@
+
+name: RNM-gem CI
+
+on:
+  # push:
+  schedule:
+    # https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule
+    # 5:23 am UTC (11:23pm MDT the day before) every weekday night in MDT
+    - cron: '23 5 * * 2-6'
+  pull_request:
+    types: [review_requested]
+
+env:
+  # This env var should enforce develop branch of all dependencies
+  FAVOR_LOCAL_GEMS: true
+  GEM_DEVELOPER_KEY: ${{ secrets.GEM_DEVELOPER_KEY }}
+
+jobs:
+  weeknight-tests:
+    runs-on: ubuntu-latest
+    container:
+      image: docker://nrel/openstudio:3.7.0
+    steps:
+      - uses: actions/checkout@v4
+      - name: set git config options
+        shell: bash
+        run: |
+          git config --global --add safe.directory '*'
+      - name: Update gems
+        run: |
+          ruby --version
+          bundle update
+          bundle exec certified-update
+      - name: Run Rspec
+        run: bundle exec rspec
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        # Only upload if rspec fails
+        if: ${{ failure() }}
+        with:
+          name: rspec_results
+          path: |
+            spec/test*/**
+            # coverage/
+          retention-days: 7 # save for 1 week before deleting
+      # coveralls action docs: https://github.com/marketplace/actions/coveralls-github-action
+      - name: Coveralls GitHub Action
+        uses: coverallsapp/github-action@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          path-to-lcov: "./coverage/lcov/urbanopt-rnm-us-gem.lcov"

.gitignore

@@ -29,4 +29,6 @@ runner.conf
 # ignore template files for now
 /template_inputs/*
 test_opendss_catalog.json
-*.sql
+*.sql
+
+*__pycache__

CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## Version 0.7.0
+Date Range 06/30/23 - 01/09/24
+
+* remove Jenkinsfile by @vtnate in https://github.com/urbanopt/urbanopt-rnm-us-gem/pull/34
+* also run CI when a PR gets a review request by @vtnate in https://github.com/urbanopt/urbanopt-rnm-us-gem/pull/35
+* Support OpenStudio 3.7 by @vtnate in https://github.com/urbanopt/urbanopt-rnm-us-gem/pull/36
+
+**Full Changelog**: https://github.com/urbanopt/urbanopt-rnm-us-gem/compare/v0.6.0...v0.7.0
+
+## Version 0.6.0
+Date Range: 6/7/23 - 6/30/23
+
+- Update dependencies & CI for OpenStudio 3.6.1
+- Update license and references to the license file
+- Remove unnecessary dev dependency on rubocop as rubocop comes in from other dependencies
+- Reactivate GitHub Actions for CI
+
+## Version 0.5.1
+Date Range 12/9/22 - 6/7/23
+
+- Fix to handle buildings with courtyard without creating additional erroneous buildings
+
+## Version 0.5.0
+Date Range 9/30/22 - 12/8/22
+
+- Update dependencies for Extension Gem 0.6.0 and OpenStudio 3.5.0
+
+## Version 0.4.0
+Date Range 05/10/22 - 9/30/22
+
+- Breaking changes to electrical catalog used and compatible RNM-US executable.
+- Update API to version 2. API v1 still working for older URBANopt SDK releases but no longer working for future versions.
+
+## Version 0.3.0
+Date Range 11/23/21 - 05/10/22
+
+- Update copyrights
+
+## Version 0.2.0
+
+Date Range 11/09/21 - 11/22/21
+
+- Updated dependencies for OpenStudio 3.3
+
 ## Version 0.1.3
 
 Date Range 11/02/21 - 11/08/21

Gemfile

@@ -6,5 +6,16 @@ gemspec
 # if you want to use local gems during development, use this environment variable to enable them
 allow_local = ENV['FAVOR_LOCAL_GEMS']
 
+# pin this dependency to avoid unicode_normalize error
+gem 'addressable', '2.8.1'
+# pin this dependency to avoid using racc dependency (which has native extensions)
+gem 'parser', '3.2.2.2'
+
 # Below is an example of how to configure the gemfile for developing with local gems
 # modify as appropriate
+
+# if allow_local && File.exists?('../urbanopt-geojson-gem')
+  # gem 'urbanopt-geojson', path: '../urbanopt-geojson-gem'
+# elsif allow_local
+#  gem 'urbanopt-geojson', github: 'URBANopt/urbanopt-geojson-gem', branch: 'os37'
+# end

LICENSE.md

@@ -1,4 +1,4 @@
-URBANopt (tm), Copyright (c) 2019-2021, Alliance for Sustainable Energy, LLC, and other
+URBANopt (tm), Copyright (c) 2019-2023, Alliance for Sustainable Energy, LLC, and other
 contributors. All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,
@@ -25,14 +25,18 @@ refer to any modified version of this software or any modified version of the
 underlying software originally provided by Alliance without the prior written
 consent of Alliance.
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
-IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
-INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
-BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
-LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
-OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
-OF THE POSSIBILITY OF SUCH DAMAGE.
-*********************************************************************************
+The name of the copyright holder(s), any contributors, the United States Government,
+the United States Department of Energy, or any of their employees may not be used to
+endorse or promote products derived from this software without specific prior written
+permission from the respective party.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) AND ANY CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
+THE COPYRIGHT HOLDER(S), ANY CONTRIBUTORS, THE UNITED STATES GOVERNMENT, OR THE UNITED
+STATES DEPARTMENT OF ENERGY, NOR ANY OF THEIR EMPLOYEES, BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
+WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,6 +1,9 @@
+[![Coverage Status](https://coveralls.io/repos/github/urbanopt/urbanopt-rnm-us-gem/badge.svg?branch=develop)](https://coveralls.io/github/urbanopt/urbanopt-rnm-us-gem?branch=develop)
+[![RNM-gem CI](https://github.com/urbanopt/urbanopt-rnm-us-gem/actions/workflows/nightly_ci_build.yml/badge.svg)](https://github.com/urbanopt/urbanopt-rnm-us-gem/actions/workflows/nightly_ci_build.yml)
+
 # URBANopt RNM-US Gem
 
-The URBANopt<sup>&trade;</sup> RNM-US Gem includes functionalities to interface the URBANopt SDK to the RNM-US Gem for the development of a synthetic optimum distribution network in the considered district, given data related to the buildings energy consumption/DER energy generation and location, modeled by the other URBANopt modules. 
+The URBANopt<sup>&trade;</sup> RNM-US Gem includes functionalities to interface the URBANopt SDK to the RNM-US Gem for the development of a synthetic optimum distribution network in the considered district, given data related to the buildings energy consumption/DER energy generation and location, modeled by the other URBANopt modules.
 The RNM-US Gem is used to collect required data for the execution of RNM-US, which has been modeled in the other URBANopt modules, translating information provided
 in .json and .csv format into .txt files
 
@@ -15,7 +18,7 @@ The OpenDSS format presents results for power system analysis and simulations.
 The current functionalities of the RNM-US Gem include the creation of a streetmap text file, the substation txt file and multiple txt files related to the consumers peak loads and profiles and DERs peak generation and profiles.
 The streetmap text file is developed from coordinates information provided by geoJSON feature file input. The customers and generators text files, which define all the network consumers and DG included in the project, are created from their peak electricity demand/generation, and building location, provided by csv and json feature_report files modeled by the URBANopt Scenario Gem.
 The profiles txt files are divided among the consumers hourly profiles of active and reactive power and the DG hourly profiles of active and reactive power for the 2 most "extreme" days of maximum net demand and maximum net generation for the district .
-Finally, the extended profiles txt files provide the active and reactive profiles for each consumer/DG for the whole year. 
+Finally, the extended profiles txt files provide the active and reactive profiles for each consumer/DG for the whole year.
 
 
 ## Generate input files
@@ -42,8 +45,29 @@ An OpenDSS-formatted catalog can be generated from the extended catalog with the
 bundle exec rake create_opendss_catalog[/desired/path/to/opendss_catalog.json]
 ```
 
+## RNM-US API compatibility
+
+| API Version | RNM-US Gem Version | RNM-US exe Version |
+| ----------- | ------------------ | ------------------ |
+| v1          | 0.3.0 and earlier  | RNM-US_20220819    |
+| v2          | 0.4.0              | RNM-US_20221018    |
+
+
+## Validation Functionality
+
+The validation and results visualization functionality is written in python. Follow these steps if you would like to use it.
+
+1. Install python (>=3.10) if you do not already have it installed
+1. Clone the repo to your computer
+1. cd into the repo directory
+1. run `bundle install` to install the required ruby dependencies
+1. run `pip install -r requirements.txt` to install the required python dependencies for the validation module
+1. create input files and run the simulation as usual
+1. run `bundle exec rake run_validation[/path/to/scenario/csv]` to run the validation
+
+
 ## Testing
 
 ```bash
 bundle exec rspec
-```
+```

Rakefile

@@ -1,41 +1,6 @@
 # *********************************************************************************
-# URBANopt (tm), Copyright (c) 2019-2021, Alliance for Sustainable Energy, LLC, and other
-# contributors. All rights reserved.
-
-# Redistribution and use in source and binary forms, with or without modification,
-# are permitted provided that the following conditions are met:
-
-# Redistributions of source code must retain the above copyright notice, this list
-# of conditions and the following disclaimer.
-
-# Redistributions in binary form must reproduce the above copyright notice, this
-# list of conditions and the following disclaimer in the documentation and/or other
-# materials provided with the distribution.
-
-# Neither the name of the copyright holder nor the names of its contributors may be
-# used to endorse or promote products derived from this software without specific
-# prior written permission.
-
-# Redistribution of this software, without modification, must refer to the software
-# by the same designation. Redistribution of a modified version of this software
-# (i) may not refer to the modified version by the same designation, or by any
-# confusingly similar designation, and (ii) must refer to the underlying software
-# originally provided by Alliance as "URBANopt". Except to comply with the foregoing,
-# the term "URBANopt", or any confusingly similar designation may not be used to
-# refer to any modified version of this software or any modified version of the
-# underlying software originally provided by Alliance without the prior written
-# consent of Alliance.
-
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
-# IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
-# INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
-# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
-# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
-# OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
-# OF THE POSSIBILITY OF SUCH DAMAGE.
+# URBANopt™, Copyright © Alliance for Sustainable Energy, LLC.
+# See also https://github.com/urbanopt/urbanopt-rnm-us-gem/blob/develop/LICENSE.md
 # *********************************************************************************
 
 require 'bundler/gem_tasks'
@@ -94,7 +59,7 @@ end
 desc 'Create input files with defaults'
 task :create_inputs_default, [:scenario_csv_path, :feature_file_path] do |t, args|
   puts 'Creating input files with defaulted settings'
- # if no path passed in, use default:
+  # if no path passed in, use default:
   scenario_csv_path = args[:scenario_csv_path] || 'spec/test/example_project/baseline_scenario.csv'
   root_dir, scenario_file_name = File.split(File.expand_path(scenario_csv_path))
   scenario_name = File.basename(scenario_file_name, File.extname(scenario_file_name))
@@ -148,6 +113,29 @@ task :run_simulation, [:scenario_csv_path, :reopt, :use_localhost] do |t, args|
   puts '...done!'
 end
 
+# Full Runner workflow (mimics UO CLI functionality)
+# pass in the path to the scenario csv, geojson path, whether this is a reopt analysis (true/false), and whether to use localhost RNM API (true/false)
+desc 'Full Runner workflow'
+task :full_runner_workflow, [:scenario_csv_path, :geojson_path, :reopt, :use_localhost] do |t, args|
+  # todo: could allow passing in extended catalog, average peak catalog, and opendss_catalog flags too
+  # if no path passed in, use default:
+  scenario_csv = args[:scenario_csv_path] || 'spec/test/example_project/run/baseline_scenario'
+  geojson_path = args[:geojson_path] || 'spec/test/example_project/example_project_with_network_and_streets'
+  root_dir, scenario_file_name = File.split(File.expand_path(scenario_csv))
+  scenario_name = File.basename(scenario_file_name, File.extname(scenario_file_name))
+  run_dir = File.join(root_dir, 'run', scenario_name.downcase)
+  reopt = args[:reopt] || false
+  reopt = reopt == 'true'
+  use_local =  args[:use_localhost] || false
+
+  runner = URBANopt::RNM::Runner.new(scenario_name, run_dir, scenario_csv, geojson_path, reopt: reopt)
+  runner.create_simulation_files
+  runner.run(use_local)
+  runner.post_process
+
+  puts '...done!'
+end
+
 # Create opendss catalog from extended catalog
 # pass in the path and filename where the OpenDSS catalog should be saved
 desc 'Create OpenDSS catalog'
@@ -164,3 +152,36 @@ task :create_opendss_catalog, [:save_path] do |t, args|
   puts "Catalog saved to #{save_path}"
   puts '....done!'
 end
+
+
+# run validation
+# pass in the path to the scenario csv
+desc 'Run Validation'
+task :run_validation, [:scenario_csv_path, :use_numeric_ids] do |t, args|
+  #Exammple to run validation
+  #bundle exec rake run_validation[D:/.../urbanopt-rnm-us-gem/spec/files/example_project/baseline_scenario.csv,true]
+
+  puts 'Running OpenDSS validation'
+
+  # if no path passed in, use default:
+  scenario_csv = args[:scenario_csv_path] || 'spec/test/example_project/run/baseline_scenario'
+  root_dir, scenario_file_name = File.split(File.expand_path(scenario_csv))
+  scenario_name = File.basename(scenario_file_name, File.extname(scenario_file_name))
+  run_dir = File.join(root_dir, 'run', scenario_name.downcase)
+  rnm_dir = File.join(run_dir, 'rnm-us')
+
+  #Use numeric ids (for the hierarchical plot of the network)
+  use_numeric_ids = args[:use_numeric_ids] || false
+  use_numeric_ids = use_numeric_ids == 'true'
+
+  if !File.exist?(rnm_dir)
+    puts rnm_dir
+    raise 'No rnm-us directory found for this scenario...run the create_inputs rake task first.'
+  end
+
+  puts "run dir path: #{run_dir}"
+  validation = URBANopt::RNM::Validation.new(rnm_dir,use_numeric_ids)
+  validation.run_validation()
+
+  puts '...done!'
+end