openstudio-standards 0.4.0 → 0.5.0

data/lib/openstudio-standards/prototypes/common/objects/Prototype.refrigeration.rb

@@ -521,7 +521,7 @@ class Standard
   #
   # @param model [OpenStudio::Model::Model] OpenStudio model object
   # @param building_type [String] building type
-  # @return [Bool] returns true if successful, false if not
+  # @return [Boolean] returns true if successful, false if not
   def model_add_typical_refrigeration(model, building_type)
     # Define system category and scaling factor
     floor_area_ft2 = OpenStudio.convert(model.getBuilding.floorArea, 'm^2', 'ft^2').get
@@ -839,7 +839,7 @@ class Standard
   # @todo Should probably use the model_add_refrigeration_walkin and lookups from the spreadsheet instead of hard-coded values
   #
   # @param model [OpenStudio::Model::Model] OpenStudio model object
-  # @return [Bool] returns true if successful, false if not
+  # @return [Boolean] returns true if successful, false if not
   def model_walkin_freezer_latent_case_credit_curve(model)
     latent_case_credit_curve_name = 'Single Shelf Horizontal Latent Energy Multiplier_After2004'
     return latent_case_credit_curve_name
@@ -856,7 +856,7 @@ class Standard
   # @param walkins [Array<Hashs>] an array of walkins with keys:
   #   walkin_type, space_names, and number_of_walkins
   # @param thermal_zone [OpenStudio::Model::ThermalZone] the thermal zone where the refrigeration piping is located
-  # @return [Bool] returns true if successful, false if not
+  # @return [Boolean] returns true if successful, false if not
   def model_add_refrigeration_system(model,
                                      compressor_type,
                                      system_name,

data/lib/openstudio-standards/prototypes/common/objects/Prototype.utilities.rb

@@ -589,7 +589,7 @@ class Standard
   # @param max_x [Double] the maximum value of independent variable X that will be used
   # @param min_out [Double] the minimum value of dependent variable Z
   # @param max_out [Double] the maximum value of dependent variable Z
-  # @param is_dimensionless [Bool] if true, the X independent variable is considered unitless
+  # @param is_dimensionless [Boolean] if true, the X independent variable is considered unitless
   #   and the resulting output dependent variable is considered unitless
   # @return [OpenStudio::Model::CurveQuadratic] a quadratic curve
   def create_curve_quadratic(model, coeffs, crv_name, min_x, max_x, min_out, max_out, is_dimensionless = false)
@@ -670,8 +670,8 @@ class Standard
   #   'ExteriorRoof', 'Skylight', 'TubularDaylightDome', 'TubularDaylightDiffuser', 'ExteriorFloor',
   #   'ExteriorWall', 'ExteriorWindow', 'ExteriorDoor', 'GlassDoor', 'OverheadDoor', 'GroundContactFloor',
   #   'GroundContactWall', 'GroundContactRoof'
-  # @param int_film [Bool] if true, interior film coefficient will be included in result
-  # @param ext_film [Bool] if true, exterior film coefficient will be included in result
+  # @param int_film [Boolean] if true, interior film coefficient will be included in result
+  # @param ext_film [Boolean] if true, exterior film coefficient will be included in result
   # @return [Double] Returns the R-Value of the film coefficients [m^2*K/W]
   def film_coefficients_r_value(intended_surface_type, int_film, ext_film)
     # Return zero if both interior and exterior are false

data/lib/openstudio-standards/prototypes/common/prototype_metaprogramming.rb

@@ -127,7 +127,7 @@ end
   # update exhuast fan efficiency
   #
   # @param model [OpenStudio::Model::Model] OpenStudio model object
-  # @return [Bool] returns true if successful, false if not
+  # @return [Boolean] returns true if successful, false if not
   def model_update_exhaust_fan_efficiency(model)
     return true
   end
@@ -168,10 +168,10 @@ end
   # daylighting adjustments specific to the prototype model
   #
   # @param model [OpenStudio::Model::Model] OpenStudio model object
-  # @param building_type [string] the building type
+  # @param building_type [String] the building type
   # @param climate_zone [String] ASHRAE climate zone, e.g. 'ASHRAE 169-2013-4A'
   # @param prototype_input [Hash] hash of prototype inputs
-  # @return [Bool] returns true if successful, false if not
+  # @return [Boolean] returns true if successful, false if not
   def model_custom_daylighting_tweaks(model, building_type, climate_zone, prototype_input)
     return true
   end
@@ -270,7 +270,7 @@ end
   # update exhuast fan efficiency
   #
   # @param model [OpenStudio::Model::Model] OpenStudio model object
-  # @return [Bool] returns true if successful, false if not
+  # @return [Boolean] returns true if successful, false if not
   def model_update_exhaust_fan_efficiency(model)
     return true
   end
@@ -629,7 +629,7 @@ end
   # update exhuast fan efficiency
   #
   # @param model [OpenStudio::Model::Model] OpenStudio model object
-  # @return [Bool] returns true if successful, false if not
+  # @return [Boolean] returns true if successful, false if not
   def model_update_exhaust_fan_efficiency(model)
     return true
   end
@@ -650,10 +650,10 @@ end
   # hvac adjustments specific to the prototype model
   #
   # @param model [OpenStudio::Model::Model] OpenStudio model object
-  # @param building_type [string] the building type
+  # @param building_type [String] the building type
   # @param climate_zone [String] ASHRAE climate zone, e.g. 'ASHRAE 169-2013-4A'
   # @param prototype_input [Hash] hash of prototype inputs
-  # @return [Bool] returns true if successful, false if not
+  # @return [Boolean] returns true if successful, false if not
   def model_custom_hvac_tweaks(model, building_type, climate_zone, prototype_input)
     return true
   end
@@ -661,10 +661,10 @@ end
   # swh adjustments specific to the prototype model
   #
   # @param model [OpenStudio::Model::Model] OpenStudio model object
-  # @param building_type [string] the building type
+  # @param building_type [String] the building type
   # @param climate_zone [String] ASHRAE climate zone, e.g. 'ASHRAE 169-2013-4A'
   # @param prototype_input [Hash] hash of prototype inputs
-  # @return [Bool] returns true if successful, false if not
+  # @return [Boolean] returns true if successful, false if not
   def model_custom_swh_tweaks(model, building_type, climate_zone, prototype_input)
     return true
   end
@@ -672,10 +672,10 @@ end
   # geometry adjustments specific to the prototype model
   #
   # @param model [OpenStudio::Model::Model] OpenStudio model object
-  # @param building_type [string] the building type
+  # @param building_type [String] the building type
   # @param climate_zone [String] ASHRAE climate zone, e.g. 'ASHRAE 169-2013-4A'
   # @param prototype_input [Hash] hash of prototype inputs
-  # @return [Bool] returns true if successful, false if not
+  # @return [Boolean] returns true if successful, false if not
   def model_custom_geometry_tweaks(model, building_type, climate_zone, prototype_input)
     return true
   end
@@ -683,10 +683,10 @@ end
   # daylighting adjustments specific to the prototype model
   #
   # @param model [OpenStudio::Model::Model] OpenStudio model object
-  # @param building_type [string] the building type
+  # @param building_type [String] the building type
   # @param climate_zone [String] ASHRAE climate zone, e.g. 'ASHRAE 169-2013-4A'
   # @param prototype_input [Hash] hash of prototype inputs
-  # @return [Bool] returns true if successful, false if not
+  # @return [Boolean] returns true if successful, false if not
   def model_custom_daylighting_tweaks(model, building_type, climate_zone, prototype_input)
     return true
   end
@@ -801,7 +801,7 @@ end
   # update exhuast fan efficiency
   #
   # @param model [OpenStudio::Model::Model] OpenStudio model object
-  # @return [Bool] returns true if successful, false if not
+  # @return [Boolean] returns true if successful, false if not
   def model_update_exhaust_fan_efficiency(model)
     return true
   end
@@ -839,10 +839,10 @@ end
   # hvac adjustments specific to the prototype model
   #
   # @param model [OpenStudio::Model::Model] OpenStudio model object
-  # @param building_type [string] the building type
+  # @param building_type [String] the building type
   # @param climate_zone [String] ASHRAE climate zone, e.g. 'ASHRAE 169-2013-4A'
   # @param prototype_input [Hash] hash of prototype inputs
-  # @return [Bool] returns true if successful, false if not
+  # @return [Boolean] returns true if successful, false if not
   def model_custom_hvac_tweaks(model, building_type, climate_zone, prototype_input)
     return true
   end
@@ -850,10 +850,10 @@ end
   # swh adjustments specific to the prototype model
   #
   # @param model [OpenStudio::Model::Model] OpenStudio model object
-  # @param building_type [string] the building type
+  # @param building_type [String] the building type
   # @param climate_zone [String] ASHRAE climate zone, e.g. 'ASHRAE 169-2013-4A'
   # @param prototype_input [Hash] hash of prototype inputs
-  # @return [Bool] returns true if successful, false if not
+  # @return [Boolean] returns true if successful, false if not
   def model_custom_swh_tweaks(model, building_type, climate_zone, prototype_input)
     return true
   end
@@ -861,10 +861,10 @@ end
   # geometry adjustments specific to the prototype model
   #
   # @param model [OpenStudio::Model::Model] OpenStudio model object
-  # @param building_type [string] the building type
+  # @param building_type [String] the building type
   # @param climate_zone [String] ASHRAE climate zone, e.g. 'ASHRAE 169-2013-4A'
   # @param prototype_input [Hash] hash of prototype inputs
-  # @return [Bool] returns true if successful, false if not
+  # @return [Boolean] returns true if successful, false if not
   def model_custom_geometry_tweaks(model, building_type, climate_zone, prototype_input)
     return true
   end
@@ -872,10 +872,10 @@ end
   # daylighting adjustments specific to the prototype model
   #
   # @param model [OpenStudio::Model::Model] OpenStudio model object
-  # @param building_type [string] the building type
+  # @param building_type [String] the building type
   # @param climate_zone [String] ASHRAE climate zone, e.g. 'ASHRAE 169-2013-4A'
   # @param prototype_input [Hash] hash of prototype inputs
-  # @return [Bool] returns true if successful, false if not
+  # @return [Boolean] returns true if successful, false if not
   def model_custom_daylighting_tweaks(model, building_type, climate_zone, prototype_input)
     return true
   end

data/lib/openstudio-standards/prototypes/deer/deer.Model.rb

@@ -5,7 +5,7 @@ class DEER
   # Based on the MASControl rules, it appears that
   # only FixedDryBulb economizers are used.
   #
-  # @param model [OpenStudio::Model::Model] the model
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
   # @param climate_zone [String] DEER climate zone
   # @return [String] the economizer type.  Possible values are:
   # 'NoEconomizer'

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

@@ -0,0 +1,131 @@
+# Module to apply QAQC checks to a model
+module OpenstudioStandards
+  module QAQC
+    # @!group Calibration
+
+    # Check the calibration against utility bills
+    #
+    # @param category [String] category to bin this check into
+    # @param target_standard [String] standard template, e.g. '90.1-2013'
+    # @param max_nmbe [Double] maximum allowable normalized mean bias error (NMBE), default 5.0%
+    # @param max_cvrmse [Double] maximum allowable coefficient of variation of the root mean square error (CVRMSE), default 15.0%
+    # @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_calibration(category, target_standard, max_nmbe: 5.0, max_cvrmse: 15.0, name_only: false)
+      # summary of the check
+      check_elems = OpenStudio::AttributeVector.new
+      check_elems << OpenStudio::Attribute.new('name', 'Calibration')
+      check_elems << OpenStudio::Attribute.new('category', category)
+      check_elems << OpenStudio::Attribute.new('description', 'Check that the model is calibrated to the utility bills.')
+
+      # 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
+        # Check that there are utility bills in the model
+        if @model.getUtilityBills.empty?
+          check_elems << OpenStudio::Attribute.new('flag', 'Model contains no utility bills, cannot check calibration.')
+        end
+
+        # Check the calibration for each utility bill
+        @model.getUtilityBills.each do |bill|
+          bill_name = bill.name.get
+          fuel = bill.fuelType.valueDescription
+
+          # Consumption
+
+          # NMBE
+          if bill.NMBE.is_initialized
+            nmbe = bill.NMBE.get
+            if nmbe > max_nmbe || nmbe < -1.0 * max_nmbe
+              check_elems << OpenStudio::Attribute.new('flag', "For the #{fuel} bill called #{bill_name}, the consumption NMBE of #{nmbe.round(1)}% is outside the limit of +/- #{max_nmbe}%, so the model is not calibrated.")
+            end
+          end
+
+          # CVRMSE
+          if bill.CVRMSE.is_initialized
+            cvrmse = bill.CVRMSE.get
+            if cvrmse > max_cvrmse
+              check_elems << OpenStudio::Attribute.new('flag', "For the #{fuel} bill called #{bill_name}, the consumption CVRMSE of #{cvrmse.round(1)}% is above the limit of #{max_cvrmse}%, so the model is not calibrated.")
+            end
+          end
+
+          # Peak Demand (for some fuels)
+          if bill.peakDemandUnitConversionFactor.is_initialized
+            peak_conversion = bill.peakDemandUnitConversionFactor.get
+
+            # Get modeled and actual values
+            actual_vals = []
+            modeled_vals = []
+            bill.billingPeriods.each do |billing_period|
+              actual_peak = billing_period.peakDemand
+              if actual_peak.is_initialized
+                actual_vals << actual_peak.get
+              end
+
+              modeled_peak = billing_period.modelPeakDemand
+              if modeled_peak.is_initialized
+                modeled_vals << modeled_peak.get
+              end
+            end
+
+            # Check that both arrays are the same size
+            unless actual_vals.size == modeled_vals.size
+              check_elems << OpenStudio::Attribute.new('flag', "For the #{fuel} bill called #{bill_name}, cannot get the same number of modeled and actual peak demand values, cannot check peak demand calibration.")
+            end
+
+            # NMBE and CMRMSE
+            ysum = 0
+            sum_err = 0
+            squared_err = 0
+            n = actual_vals.size
+
+            actual_vals.each_with_index do |actual, i|
+              modeled = modeled_vals[i]
+              actual *= peak_conversion # Convert actual demand to model units
+              ysum += actual
+              sum_err += (actual - modeled)
+              squared_err += (actual - modeled)**2
+            end
+
+            if n > 1
+              ybar = ysum / n
+
+              # NMBE
+              demand_nmbe = 100.0 * (sum_err / (n - 1)) / ybar
+              if demand_nmbe > max_nmbe || demand_nmbe < -1.0 * max_nmbe
+                check_elems << OpenStudio::Attribute.new('flag', "For the #{fuel} bill called #{bill_name}, the peak demand NMBE of #{demand_nmbe.round(1)}% is outside the limit of +/- #{max_nmbe}%, so the model is not calibrated.")
+              end
+
+              # CVRMSE
+              demand_cvrmse = 100.0 * (squared_err / (n - 1))**0.5 / ybar
+              if demand_cvrmse > max_cvrmse
+                check_elems << OpenStudio::Attribute.new('flag', "For the #{fuel} bill called #{bill_name}, the peak demand CVRMSE of #{demand_cvrmse.round(1)}% is above the limit of #{max_cvrmse}%, so the model is not calibrated.")
+              end
+            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