Merge pull request #91 from BuildingSync/DA_Update_RefSched_CZ

Enable reading of climate zone (and other parameters) at the building level in addition to the site level

README.md

@@ -20,15 +20,41 @@ Or install it yourself as:
 
 ## Usage
 
-To be filled out later. 
+The BuildingSync-Gem 
+- converts your BuildingSync.xml file into 
+  - an OpenStudio Baseline model
+  - an OpenStudio workflow for each scenario defined in the XML file
+- enables simulation of the baseline model and all workflows and 
+- inserts simulation results back into the xml file. 
+
+All these features are driven by the translator class.
+
+```ruby
+# initializing the translator 
+translator = BuildingSync::Translator.new(building_sync_xml_file_path, out_path)
+# generating the OpenStudio Model and writing the osm file  
+translator.write_osm
+# generating the OpenStudio workflows and writing the osw files
+translator.write_osws
+# running the baseline simulations
+translator.run_osm
+# running all simulations
+translator.run_osws
+# gather the results and save them to an BuildingSync.XML
+translator.gather_results(out_path)
+```
+## Testing
+
+Check out the repository and then execute:
+```ruby
+$ bundle install
+$ bundle update    
+$ bundle exec rake
+```
 
 ## TODO
 
-- [ ] Add initial BuildingSync class (can use [BRICR](https://github.com/NREL/bricr/blob/develop/lib/bricr/building_sync.rb) class as example). Use REXML for reading and writing BSync.
-- [ ] Add ForwardTranslator class (following [other OpenStudio conventions](https://github.com/NREL/OpenStudio/blob/develop/openstudiocore/src/gbxml/ForwardTranslator.hpp)) that translates BuildingSync to OpenStudio (using pure Ruby)
 - [ ] Move BuildingSync specific measures into this gem. See list from [here](https://docs.google.com/spreadsheets/d/1PCB4nZoLQ1cWhnlrlnHwo9kI4G8ChOeblU3L4uZu7bc/edit#gid=1482405742) 
-- [ ] Add example on how to use some code from ```openstudio-standards``` or ```openstudio-model-articulation``` during the translation
-- [ ] Add unit test for BuildingSync -> OSM translation
 - [ ] Add ability to perform validation using https://selectiontool.buildingsync.net. Return which use cases existing BuildingSync XML is valid for.
 
 

lib/buildingsync/extension.rb

@@ -52,6 +52,7 @@ class Extension < OpenStudio::Extension::Extension
     # number of parallel BuildingSync files to run
     NUM_BUILDINGS_PARALLEL = 2
 
+    ##
     # Override the base class
     # The Extension class contains both the instance of the BuildingSync file (in XML) and the
     # helper methods from the OpenStudio::Extension gem to support managing measures that are related
@@ -62,33 +63,5 @@ def initialize
       super
       @root_dir = File.absolute_path(File.join(File.dirname(__FILE__), '..', '..'))
     end
-
-    # Read in an existing buildingsync file
-    #
-    # @param buildingsync_file [string]: path to BuildingSync XML
-    def self.from_file(buildingsync_file)
-      bsync = Extension.new
-      bsync.read_from_xml(buildingsync_file)
-      return bsync
-    end
-
-    # read the XML from file
-    def read_from_xml(buildingsync_file)
-      return nil
-    end
-
-    # write OSW file
-    # This method will write a single OSW from the BuildingSync file. The OSW will not include any of the scenarios
-    # other than the baseline.
-    def to_osw
-      return nil
-    end
-
-    # write multiple OSW files
-    # This method will write out multiple OSW files from the BuildingSync file. The OSWs will be constructed based
-    # on the various scenarios that are in the BuildingSync file
-    def to_osws
-      return nil
-    end
   end
 end

lib/buildingsync/generator.rb

@@ -37,6 +37,15 @@
 module BuildingSync
   class Generator
 
+    ##
+    # creates a minimum building sync snippet
+    ##
+    # @param occupancy_classification [string]
+    # @param year_of_const [int]
+    # @param floor_area_type [string]
+    # @param floor_area_value [float]
+    # @param ns [string]
+    # @return REXML::Document
     def create_minimum_snippet(occupancy_classification, year_of_const, floor_area_type, floor_area_value, ns = 'auc')
       xml_path = File.expand_path('./../../spec/files/building_151_Blank.xml', File.dirname(__FILE__))
 
@@ -72,6 +81,14 @@ def create_minimum_snippet(occupancy_classification, year_of_const, floor_area_t
       return doc
     end
 
+    ##
+    # creates a minimum facility
+    ##
+    # @param occupancy_classification [string]
+    # @param year_of_const [int]
+    # @param floor_area_type [string]
+    # @param floor_area_value [float]
+    # @return BuildingSync::Facility
     def create_minimum_facility(occupancy_classification, year_of_const, floor_area_type, floor_area_value)
       xml_snippet = create_minimum_snippet(occupancy_classification, year_of_const, floor_area_type, floor_area_value)
       ns = 'auc'

lib/buildingsync/helpers/helper.rb

@@ -36,20 +36,32 @@
 # *******************************************************************************
 module BuildingSync
   class Helper
+    ##
+    # get text value from xml element
+    # @param xml_element [REXML::Element]
+    # @return string
     def self.get_text_value(xml_element)
       if xml_element
         return xml_element.text
       end
       return nil
     end
 
+    ##
+    # get date value from xml element
+    # @param xml_element [REXML::Element]
+    # @return string
     def self.get_date_value(xml_element)
       if xml_element
         return Date.parse(xml_element.text)
       end
       return nil
     end
 
+    ##
+    # get zone name list
+    # @param zones [array<OpenStudio::Model::ThermalZone>]
+    # @return array
     def self.get_zone_name_list(zones)
       names = []
       zones.each do |zone|
@@ -58,10 +70,14 @@ def self.get_zone_name_list(zones)
       return names
     end
 
+    ##
+    # read xml file document
+    # @param xml_file_path [string]
+    # @return REXML::Document
     def self.read_xml_file_document(xml_file_path)
       doc = nil
       File.open(xml_file_path, 'r') do |file_content|
-        doc = REXML::Document.new(file_content,  { :ignore_whitespace_nodes => :all })
+        doc = REXML::Document.new(file_content, :ignore_whitespace_nodes => :all)
       end
       return doc
     end

lib/buildingsync/model_articulation/building.rb

@@ -35,13 +35,14 @@
 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 # *******************************************************************************
 require_relative 'building_section'
+require_relative 'location_element'
 require_relative '../../../lib/buildingsync/get_bcl_weather_file'
 require 'date'
 require 'openstudio/extension/core/os_lib_helper_methods'
 require 'openstudio/extension/core/os_lib_model_generation'
 
 module BuildingSync
-  class Building < SpatialElement
+  class Building < LocationElement
     include OsLib_HelperMethods
     include EnergyPlus
     include OsLib_ModelGeneration
@@ -95,8 +96,9 @@ def read_xml(build_element, site_occupancy_type, site_total_floor_area, ns)
       if build_element.attributes['ID']
         @id = build_element.attributes['ID']
       end
-      # city and state
-      read_city_and_state_name(build_element, ns)
+
+      # read location specific values
+      read_location_values(build_element, ns)
       # floor areas
       read_floor_areas(build_element, site_total_floor_area, ns)
       # standard template
@@ -230,6 +232,16 @@ def get_building_type
       end
     end
 
+    def get_climate_zone(standard_to_be_used = nil)
+      if standard_to_be_used == ASHRAE90_1
+        return @climate_zone_ashrae
+      elsif standard_to_be_used == CA_TITLE24
+        return @climate_zone_ca_t24
+      else
+        return @climate_zone
+      end
+    end
+
     def set_building_form_defaults
       # if aspect ratio, story height or wwr have argument value of 0 then use smart building type defaults
       building_form_defaults = building_form_defaults(get_building_type)
@@ -1044,15 +1056,15 @@ def write_parameters_to_xml(ns, building)
       add_user_defined_field_to_xml_file(building, ns, 'PartyWallFraction', @party_wall_fraction)
       add_user_defined_field_to_xml_file(building, ns, 'FractionArea', @fraction_area)
 
-      write_parameters_to_xml_for_spatial_element(ns, building)
+      write_parameters_to_xml_for_spatial_element(building, ns)
     end
 
     def get_space_types
       return @model.getSpaceTypes
     end
 
     def get_peak_occupancy
-      peak_occupancy = Hash.new
+      peak_occupancy = {}
       if @occupant_quantity
         peak_occupancy[@id] = @occupant_quantity.to_f
         return peak_occupancy

lib/buildingsync/model_articulation/building_section.rb

@@ -245,7 +245,7 @@ def write_parameters_to_xml(ns, building_section)
       add_user_defined_field_to_xml_file(building_section, ns, 'BuildingType', @bldg_type)
       add_user_defined_field_to_xml_file(building_section, ns, 'FractionArea', @fraction_area)
 
-      write_parameters_to_xml_for_spatial_element(ns, building_section)
+      write_parameters_to_xml_for_spatial_element(building_section, ns)
     end
 
     def set_bldg_and_system_type