openstudio-standards 0.4.0 → 0.5.0

data/lib/openstudio-standards/qaqc/reporting.rb

@@ -0,0 +1,141 @@
+# Module to apply QAQC checks to a model
+module OpenstudioStandards
+  module QAQC
+    # @!group QAQC HTML reporting
+
+    # Cleanup and prepare HTML
+    # measures calling this must add the following require calls:
+    # require 'json'
+    # require 'erb'
+    #
+    # @param html_in_path [String] HTML input path
+    # @param sections [Array] sections from create_sections_from_check_attributes
+    # @param name [String] the name that a user will see
+    # @return [String] HTML output path
+    def self.create_qaqc_html(html_in_path, sections, name)
+      # read in template
+      if File.exist?(html_in_path)
+        html_in_path = html_in_path
+      else
+        html_in_path = "#{File.dirname(__FILE__)}/report.html.erb"
+      end
+      html_in = ''
+      File.open(html_in_path, 'r') do |file|
+        html_in = file.read
+      end
+
+      # configure template with variable values
+      # instance variables for erb
+      @sections = sections
+      @name = name
+      renderer = ERB.new(html_in)
+      html_out = renderer.result(binding)
+
+      # write html file
+      html_out_path = './report.html'
+      File.open(html_out_path, 'w') do |file|
+        file << html_out
+        # make sure data is written to the disk one way or the other
+        begin
+          file.fsync
+        rescue StandardError
+          file.flush
+        end
+      end
+
+      return html_out_path
+    end
+
+    # Make HTML sections from a collection of QAQC checks
+    #
+    # @param check_elems [OpenStudio::AttributeVector.new] vector of check elements
+    # @return [Array] Array of HTML sections
+    def self.create_sections_from_check_attributes(check_elems)
+      # developer notes
+      # method below is custom version of standard OpenStudio results methods. It passes an array of sections vs. a single section.
+      # It doesn't use the model or SQL file. It just gets data form OpenStudio attributes passed in
+      # It doesn't have a name_only section since it doesn't populate user arguments
+
+      # inspecting check attributes
+      # make single table with checks.
+      # make second table with flag description (with column for where it came from)
+
+      # array to hold sections
+      sections = []
+
+      # gather data for section
+      qaqc_check_summary = {}
+      qaqc_check_summary[:title] = 'List of Checks in Measure'
+      qaqc_check_summary[:header] = ['Name', 'Category', 'Flags', 'Description']
+      qaqc_check_summary[:data] = []
+      qaqc_check_summary[:data_color] = []
+      @qaqc_check_section = {}
+      @qaqc_check_section[:title] = 'QAQC Check Summary'
+      @qaqc_check_section[:tables] = [qaqc_check_summary]
+
+      # add sections to array
+      sections << @qaqc_check_section
+
+      # counter for flags thrown
+      num_flags = 0
+
+      check_elems.each do |check|
+        # gather data for section
+        qaqc_flag_details = {}
+        qaqc_flag_details[:title] = "List of Flags Triggered for #{check.valueAsAttributeVector.first.valueAsString}."
+        qaqc_flag_details[:header] = ['Flag Detail']
+        qaqc_flag_details[:data] = []
+        @qaqc_flag_section = {}
+        @qaqc_flag_section[:title] = check.valueAsAttributeVector.first.valueAsString.to_s
+        @qaqc_flag_section[:tables] = [qaqc_flag_details]
+
+        check_name = nil
+        check_cat = nil
+        check_desc = nil
+        flags = []
+        # loop through attributes (name,category,description,then optionally one or more flag attributes)
+        check.valueAsAttributeVector.each_with_index do |value, index|
+          if index == 0
+            check_name = value.valueAsString
+          elsif index == 1
+            check_cat = value.valueAsString
+          elsif index == 2
+            check_desc = value.valueAsString
+          else # should be flag
+            flags << value.valueAsString
+            qaqc_flag_details[:data] << [value.valueAsString]
+            OpenStudio.logFree(OpenStudio::Warn, 'openstudio.standards.QAQC', "#{check_name} - #{value.valueAsString}")
+            num_flags += 1
+          end
+        end
+
+        # add row to table for this check
+        qaqc_check_summary[:data] << [check_name, check_cat, flags.size, check_desc]
+
+        # add info message for check if no flags found (this way user still knows what ran)
+        if check.valueAsAttributeVector.size < 4
+          OpenStudio.logFree(OpenStudio::Info, 'openstudio.standards.QAQC', "#{check_name} - no flags.")
+        end
+
+        # color cells based and add logging messages based on flag status
+        if !flags.empty?
+          qaqc_check_summary[:data_color] << ['', '', 'indianred', '']
+          OpenStudio.logFree(OpenStudio::Info, 'openstudio.standards.QAQC', "#{check_name.downcase.tr(' ', '_')} #{flags.size} flags")
+        else
+          qaqc_check_summary[:data_color] << ['', '', 'lightgreen', '']
+          OpenStudio.logFree(OpenStudio::Info, 'openstudio.standards.QAQC', "#{check_name.downcase.tr(' ', '_')} #{flags.size} flags")
+        end
+
+        # add table for this check if there are flags
+        if !qaqc_flag_details[:data].empty?
+          sections << @qaqc_flag_section
+        end
+      end
+
+      # add total flags registerValue
+      OpenStudio.logFree(OpenStudio::Info, 'openstudio.standards.QAQC', "total flags: #{num_flags}")
+
+      return sections
+    end
+  end
+end

data/lib/openstudio-standards/qaqc/schedules.rb

@@ -0,0 +1,129 @@
+# Module to apply QAQC checks to a model
+module OpenstudioStandards
+  module QAQC
+    # @!group Schedules
+
+    # Check that the lighting, equipment, and HVAC setpoint schedules coordinate with the occupancy schedules.
+    # This is defined as having start and end times within the specified number of hours away from the occupancy schedule.
+    #
+    # @param category [String] category to bin this check into
+    # @param target_standard [String] standard template, e.g. '90.1-2013'
+    # @param max_hrs [Double] threshold for throwing an error for schedule coordination
+    # @param name_only [Boolean] If true, only return the name of this check
+    # @return [OpenStudio::Attribute] OpenStudio Attribute object containing check results
+    def self.check_schedule_coordination(category, target_standard, max_hrs: 2.0, name_only: false)
+      # summary of the check
+      check_elems = OpenStudio::AttributeVector.new
+      check_elems << OpenStudio::Attribute.new('name', 'Schedule Coordination')
+      check_elems << OpenStudio::Attribute.new('category', category)
+      check_elems << OpenStudio::Attribute.new('description', 'Check that lighting, equipment, and HVAC schedules coordinate with occupancy.')
+
+      # stop here if only name is requested this is used to populate display name for arguments
+      if name_only == true
+        results = []
+        check_elems.each do |elem|
+          results << elem.valueAsString
+        end
+        return results
+      end
+
+      std = Standard.build(target_standard)
+
+      begin
+        # Convert max hr limit to OpenStudio Time
+        max_hrs = OpenStudio::Time.new(0, max_hrs.to_i, 0, 0)
+
+        # Check schedules in each space
+        @model.getSpaces.sort.each do |space|
+          # Occupancy, Lighting, and Equipment Schedules
+          coord_schs = []
+          occ_schs = []
+          # Get the space type (optional)
+          space_type = space.spaceType
+
+          # Occupancy
+          occs = []
+          occs += space.people # From space directly
+          occs += space_type.get.people if space_type.is_initialized # Inherited from space type
+          occs.each do |occ|
+            occ_schs << occ.numberofPeopleSchedule.get if occ.numberofPeopleSchedule.is_initialized
+          end
+
+          # Lights
+          lts = []
+          lts += space.lights # From space directly
+          lts += space_type.get.lights if space_type.is_initialized # Inherited from space type
+          lts.each do |lt|
+            coord_schs << lt.schedule.get if lt.schedule.is_initialized
+          end
+
+          # Equip
+          plugs = []
+          plugs += space.electricEquipment # From space directly
+          plugs += space_type.get.electricEquipment if space_type.is_initialized # Inherited from space type
+          plugs.each do |plug|
+            coord_schs << plug.schedule.get if plug.schedule.is_initialized
+          end
+
+          # HVAC Schedule (airloop-served zones only)
+          if space.thermalZone.is_initialized
+            zone = space.thermalZone.get
+            if zone.airLoopHVAC.is_initialized
+              coord_schs << zone.airLoopHVAC.get.availabilitySchedule
+            end
+          end
+
+          # Cannot check spaces with no occupancy schedule to compare against
+          next if occ_schs.empty?
+
+          # Get start and end occupancy times from the first occupancy schedule
+          times = OpenstudioStandards::Schedules.schedule_ruleset_get_start_and_end_times(occ_schs[0])
+          occ_start_time = times['start_time']
+          occ_end_time = times['end_time']
+
+          # Cannot check a space where the occupancy start time or end time cannot be determined
+          next if occ_start_time.nil? || occ_end_time.nil?
+
+          # Check all schedules against occupancy
+
+          # Lights should have a start and end within X hrs of the occupancy start and end
+          coord_schs.each do |coord_sch|
+            # Get start and end time of load/HVAC schedule
+            times = OpenstudioStandards::Schedules.schedule_ruleset_get_start_and_end_times(coord_sch)
+            start_time = times['start_time']
+            end_time = times['end_time]']
+
+            if start_time.nil?
+              check_elems << OpenStudio::Attribute.new('flag', "Could not determine start time of a schedule called #{coord_sch.name}, cannot determine if schedule coordinates with occupancy schedule.")
+              next
+            elsif end_time.nil?
+              check_elems << OpenStudio::Attribute.new('flag', "Could not determine end time of a schedule called #{coord_sch.name}, cannot determine if schedule coordinates with occupancy schedule.")
+              next
+            end
+
+            # Check start time
+            if (occ_start_time - start_time) > max_hrs || (start_time - occ_start_time) > max_hrs
+              check_elems << OpenStudio::Attribute.new('flag', "The start time of #{coord_sch.name} is #{start_time}, which is more than #{max_hrs} away from the occupancy schedule start time of #{occ_start_time} for #{occ_schs[0].name} in #{space.name}.  Schedules do not coordinate.")
+            end
+
+            # Check end time
+            if (occ_end_time - end_time) > max_hrs || (end_time - occ_end_time) > max_hrs
+              check_elems << OpenStudio::Attribute.new('flag', "The end time of #{coord_sch.name} is #{end_time}, which is more than #{max_hrs} away from the occupancy schedule end time of #{occ_end_time} for #{occ_schs[0].name} in #{space.name}.  Schedules do not coordinate.")
+            end
+          end
+        end
+      rescue StandardError => e
+        # brief description of ruby error
+        check_elems << OpenStudio::Attribute.new('flag', "Error prevented QAQC check from running (#{e}).")
+
+        # backtrace of ruby error for diagnostic use
+        if @error_backtrace then check_elems << OpenStudio::Attribute.new('flag', e.backtrace.join("\n").to_s) end
+      end
+
+      # add check_elms to new attribute
+      check_elem = OpenStudio::Attribute.new('check', check_elems)
+
+      return check_elem
+    end
+  end
+end

data/lib/openstudio-standards/qaqc/service_water_heating.rb

@@ -0,0 +1,273 @@
+# Module to apply QAQC checks to a model
+module OpenstudioStandards
+  module QAQC
+    # @!group Service Water Heating
+
+    # Checks the hot water use in a model for typical values
+    #
+    # @param category [String] category to bin this check into
+    # @param target_standard [String] standard template, e.g. '90.1-2013'
+    # @param min_pass_pct [Double] threshold for throwing an error for percent difference
+    # @param max_pass_pct [Double] threshold for throwing an error for percent difference
+    # @param name_only [Boolean] If true, only return the name of this check
+    # @return [OpenStudio::Attribute] OpenStudio Attribute object containing check results
+    def self.check_service_hot_water(category, target_standard, min_pass_pct: 0.25, max_pass_pct: 0.25, name_only: false)
+      # @todo could expose meal turnover and people per unit for res and hotel into arguments
+
+      # summary of the check
+      check_elems = OpenStudio::AttributeVector.new
+      check_elems << OpenStudio::Attribute.new('name', 'Domestic Hot Water')
+      check_elems << OpenStudio::Attribute.new('category', category)
+      if target_standard == 'ICC IECC 2015'
+        check_elems << OpenStudio::Attribute.new('description', 'Check service water heating consumption against Table R405.5.2(1) in ICC IECC 2015 Residential Provisions.')
+      else
+        check_elems << OpenStudio::Attribute.new('description', 'Check against the 2011 ASHRAE Handbook - HVAC Applications, Table 7 section 50.14.')
+      end
+
+      # stop here if only name is requested this is used to populate display name for arguments
+      if name_only == true
+        results = []
+        check_elems.each do |elem|
+          results << elem.valueAsString
+        end
+        return results
+      end
+
+      std = Standard.build(target_standard)
+
+      begin
+        # loop through water_use_equipment
+        service_water_consumption_daily_avg_gal = 0.0
+        @model.getWaterUseEquipments.each do |water_use_equipment|
+          # get peak flow rate from def
+          peak_flow_rate_si = water_use_equipment.waterUseEquipmentDefinition.peakFlowRate
+          source_units = 'm^3/s'
+          target_units = 'gal/min'
+          peak_flow_rate_ip = OpenStudio.convert(peak_flow_rate_si, source_units, target_units).get
+
+          # get value from flow rate schedule
+          if water_use_equipment.flowRateFractionSchedule.is_initialized
+            # get annual equiv for model schedule
+            schedule_inst = water_use_equipment.flowRateFractionSchedule.get
+            if schedule_inst.to_ScheduleRuleset.is_initialized
+              annual_equiv_flow_rate = std.schedule_ruleset_annual_equivalent_full_load_hrs(schedule_inst.to_ScheduleRuleset.get)
+            elsif schedule_inst.to_ScheduleConstant.is_initialized
+              annual_equiv_flow_rate = std.schedule_constant_annual_equivalent_full_load_hrs(schedule_inst.to_ScheduleConstant.get)
+            else
+              check_elems << OpenStudio::Attribute.new('flag', "#{schedule_inst.name} isn't a Ruleset or Constant schedule. Can't calculate annual equivalent full load hours.")
+              next
+            end
+          else
+            # issue flag
+            check_elems << OpenStudio::Attribute.new('flag', "#{water_use_equipment.name} doesn't have a schedule. Can't identify hot water consumption.")
+            next
+          end
+
+          # add to global service water consumpiton value
+          service_water_consumption_daily_avg_gal += 60.0 * peak_flow_rate_ip * annual_equiv_flow_rate / 365.0
+        end
+
+        if target_standard == 'ICC IECC 2015'
+
+          num_people = 0.0
+          @model.getSpaceTypes.each do |space_type|
+            next if !space_type.standardsSpaceType.is_initialized
+            next if space_type.standardsSpaceType.get != 'Apartment' # currently only supports midrise apt space type
+
+            space_type_floor_area = space_type.floorArea
+            space_type_num_people = space_type.getNumberOfPeople(space_type_floor_area)
+            num_people += space_type_num_people
+          end
+
+          # lookup target gal/day for the building
+          bedrooms_per_unit = 2.0 # assumption
+          num_units = num_people / 2.5 # Avg 2.5 units per person.
+          target_consumption = std.model_find_icc_iecc_2015_hot_water_demand(@model, num_units, bedrooms_per_unit)
+        else
+          # only other path for now is 90.1-2013
+
+          # get building type
+          building_type = ''
+          if @model.getBuilding.standardsBuildingType.is_initialized
+            building_type = @model.getBuilding.standardsBuildingType.get
+          end
+
+          # lookup data from standards
+          ashrae_hot_water_demand = std.model_find_ashrae_hot_water_demand(@model)
+
+          # building type specific logic for water consumption
+          # todo - update test to exercise various building types
+          if !ashrae_hot_water_demand.empty?
+
+            if building_type == 'FullServiceRestaurant'
+              num_people_hours = 0.0
+              @model.getSpaceTypes.each do |space_type|
+                next if !space_type.standardsSpaceType.is_initialized
+                next if space_type.standardsSpaceType.get != 'Dining'
+
+                space_type_floor_area = space_type.floorArea
+
+                space_type_num_people_hours = 0.0
+                # loop through peole instances
+                space_type.peoples.each do |inst|
+                  inst_num_people = inst.getNumberOfPeople(space_type_floor_area)
+                  inst_schedule = inst.numberofPeopleSchedule.get # sim will fail prior to this if doesn't have it
+
+                  if inst_schedule.to_ScheduleRuleset.is_initialized
+                    annual_equiv_flow_rate = std.schedule_ruleset_annual_equivalent_full_load_hrs(inst_schedule.to_ScheduleRuleset.get)
+                  elsif inst_schedule.to_ScheduleConstant.is_initialized
+                    annual_equiv_flow_rate = std.schedule_constant_annual_equivalent_full_load_hrs(inst_schedule.to_ScheduleConstant.get)
+                  else
+                    check_elems << OpenStudio::Attribute.new('flag', "#{inst_schedule.name} isn't a Ruleset or Constant schedule. Can't calculate annual equivalent full load hours.")
+                    annual_equiv_flow_rate = 0.0
+                  end
+
+                  inst_num_people_horus = annual_equiv_flow_rate * inst_num_people
+                  space_type_num_people_hours += inst_num_people_horus
+                end
+
+                num_people_hours += space_type_num_people_hours
+              end
+              num_meals = num_people_hours / 365.0 * 1.5 # 90 minute meal
+              target_consumption = num_meals * ashrae_hot_water_demand.first[:avg_day_unit]
+
+            elsif ['LargeHotel', 'SmallHotel'].include? building_type
+              num_people = 0.0
+              @model.getSpaceTypes.each do |space_type|
+                next if !space_type.standardsSpaceType.is_initialized
+                next if space_type.standardsSpaceType.get != 'GuestRoom'
+
+                space_type_floor_area = space_type.floorArea
+                space_type_num_people = space_type.getNumberOfPeople(space_type_floor_area)
+                num_people += space_type_num_people
+              end
+
+              # find best fit from returned results
+              num_units = num_people / 2.0 # 2 people per room design load, not typical occupancy
+              avg_day_unit = nil
+              fit = nil
+              ashrae_hot_water_demand.each do |block|
+                if fit.nil?
+                  avg_day_unit = block[:avg_day_unit]
+                  fit = (avg_day_unit - block[:block]).abs
+                elsif (avg_day_unit - block[:block]).abs - fit
+                  avg_day_unit = block[:avg_day_unit]
+                  fit = (avg_day_unit - block[:block]).abs
+                end
+              end
+              target_consumption = num_units * avg_day_unit
+
+            elsif building_type == 'MidriseApartment'
+              num_people = 0.0
+              @model.getSpaceTypes.each do |space_type|
+                next if !space_type.standardsSpaceType.is_initialized
+                next if space_type.standardsSpaceType.get != 'Apartment'
+
+                space_type_floor_area = space_type.floorArea
+                space_type_num_people = space_type.getNumberOfPeople(space_type_floor_area)
+                num_people += space_type_num_people
+              end
+
+              # find best fit from returned results
+              num_units = num_people / 2.5 # Avg 2.5 units per person.
+              avg_day_unit = nil
+              fit = nil
+              ashrae_hot_water_demand.each do |block|
+                if fit.nil?
+                  avg_day_unit = block[:avg_day_unit]
+                  fit = (avg_day_unit - block[:block]).abs
+                elsif (avg_day_unit - block[:block]).abs - fit
+                  avg_day_unit = block[:avg_day_unit]
+                  fit = (avg_day_unit - block[:block]).abs
+                end
+              end
+              target_consumption = num_units * avg_day_unit
+
+            elsif ['Office', 'LargeOffice', 'MediumOffice', 'SmallOffice'].include? building_type
+              num_people = @model.getBuilding.numberOfPeople
+              target_consumption = num_people * ashrae_hot_water_demand.first[:avg_day_unit]
+            elsif building_type == 'PrimarySchool'
+              num_people = 0.0
+              @model.getSpaceTypes.each do |space_type|
+                next if !space_type.standardsSpaceType.is_initialized
+                next if space_type.standardsSpaceType.get != 'Classroom'
+
+                space_type_floor_area = space_type.floorArea
+                space_type_num_people = space_type.getNumberOfPeople(space_type_floor_area)
+                num_people += space_type_num_people
+              end
+              target_consumption = num_people * ashrae_hot_water_demand.first[:avg_day_unit]
+            elsif building_type == 'QuickServiceRestaurant'
+              num_people_hours = 0.0
+              @model.getSpaceTypes.each do |space_type|
+                next if !space_type.standardsSpaceType.is_initialized
+                next if space_type.standardsSpaceType.get != 'Dining'
+
+                space_type_floor_area = space_type.floorArea
+
+                space_type_num_people_hours = 0.0
+                # loop through peole instances
+                space_type.peoples.each do |inst|
+                  inst_num_people = inst.getNumberOfPeople(space_type_floor_area)
+                  inst_schedule = inst.numberofPeopleSchedule.get # sim will fail prior to this if doesn't have it
+
+                  if inst_schedule.to_ScheduleRuleset.is_initialized
+                    annual_equiv_flow_rate = std.schedule_ruleset_annual_equivalent_full_load_hrs(inst_schedule.to_ScheduleRuleset.get)
+                  elsif inst_schedule.to_ScheduleConstant.is_initialized
+                    annual_equiv_flow_rate = std.schedule_constant_annual_equivalent_full_load_hrs(inst_schedule.to_ScheduleConstant.get)
+                  else
+                    check_elems << OpenStudio::Attribute.new('flag', "#{inst_schedule.name} isn't a Ruleset or Constant schedule. Can't calculate annual equivalent full load hours.")
+                    annual_equiv_flow_rate = 0.0
+                  end
+
+                  inst_num_people_horus = annual_equiv_flow_rate * inst_num_people
+                  space_type_num_people_hours += inst_num_people_horus
+                end
+
+                num_people_hours += space_type_num_people_hours
+              end
+              num_meals = num_people_hours / 365.0 * 0.5 # 30 minute leal
+              # todo - add logic to address drive through traffic
+              target_consumption = num_meals * ashrae_hot_water_demand.first[:avg_day_unit]
+
+            elsif building_type == 'SecondarySchool'
+              num_people = 0.0
+              @model.getSpaceTypes.each do |space_type|
+                next if !space_type.standardsSpaceType.is_initialized
+                next if space_type.standardsSpaceType.get != 'Classroom'
+
+                space_type_floor_area = space_type.floorArea
+                space_type_num_people = space_type.getNumberOfPeople(space_type_floor_area)
+                num_people += space_type_num_people
+              end
+              target_consumption = num_people * ashrae_hot_water_demand.first[:avg_day_unit]
+            else
+              check_elems << OpenStudio::Attribute.new('flag', "No rule of thumb values exist for  #{building_type}. Hot water consumption was not checked.")
+            end
+
+          else
+            check_elems << OpenStudio::Attribute.new('flag', "No rule of thumb values exist for  #{building_type}. Hot water consumption was not checked.")
+          end
+        end
+
+        # check actual against target
+        if service_water_consumption_daily_avg_gal < target_consumption * (1.0 - min_pass_pct)
+          check_elems <<  OpenStudio::Attribute.new('flag', "Annual average of #{service_water_consumption_daily_avg_gal.round} gallons per day of hot water is more than #{min_pass_pct * 100} % below the expected value of #{target_consumption.round} gallons per day.")
+        elsif service_water_consumption_daily_avg_gal > target_consumption * (1.0 + max_pass_pct)
+          check_elems <<  OpenStudio::Attribute.new('flag', "Annual average of #{service_water_consumption_daily_avg_gal.round} gallons per day of hot water is more than #{max_pass_pct * 100} % above the expected value of #{target_consumption.round} gallons per day.")
+        end
+      rescue StandardError => e
+        # brief description of ruby error
+        check_elems << OpenStudio::Attribute.new('flag', "Error prevented QAQC check from running (#{e}).")
+
+        # backtrace of ruby error for diagnostic use
+        if @error_backtrace then check_elems << OpenStudio::Attribute.new('flag', e.backtrace.join("\n").to_s) end
+      end
+
+      # add check_elms to new attribute
+      check_elem = OpenStudio::Attribute.new('check', check_elems)
+
+      return check_elem
+    end
+  end
+end