tbd 3.4.4 → 3.5.0

data/lib/measures/tbd/resources/oslog.rb

@@ -1,6 +1,6 @@
 # BSD 3-Clause License
 #
-# Copyright (c) 2022-2024, Denis Bourgeois
+# Copyright (c) 2022-2025, Denis Bourgeois
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -102,9 +102,9 @@ module OSlg
   end
 
   ##
-  # Returns whether current status is WARN.
+  # Returns whether current status is WARNING.
   #
-  # @return [Bool] whether current log status is WARN
+  # @return [Bool] whether current log status is WARNING
   def warn?
     @@status == WARN
   end
@@ -159,19 +159,20 @@ module OSlg
   end
 
   ##
-  # Converts object to String and trims if necessary.
+  # Converts object to String, trims if requested.
   #
   # @param txt [#to_s] a stringable object
-  # @param length [#to_i] maximum return string length
+  # @param len [Numeric] requested maximum string length (optional)
   #
-  # @return [String] a trimmed message string (empty unless stringable)
-  def trim(txt = "", length = 60)
-    length = 60 unless length.respond_to?(:to_i)
-    length = length.to_i if length.respond_to?(:to_i)
+  # @return [String] a (trimmed) string (empty unless stringable)
+  def trim(txt = "", len = nil)
     return "" unless txt.respond_to?(:to_s)
 
     txt = txt.to_s.strip
-    txt = txt[0...length] + " ..." if txt.length > length
+
+    if len.is_a?(Numeric)
+      txt = txt[0...len.to_i] + " ..." if txt.length > len.to_i
+    end
 
     txt
   end
@@ -193,21 +194,28 @@ module OSlg
   end
 
   ##
-  # Logs a new entry, if provided arguments are valid.
+  # Logs a new entry. Overall log status is raised if new level is greater
+  # than current level (e.g. FATAL > ERROR). Candidate log entry is ignored and
+  # status remains unchanged if the new level cannot be converted to an integer,
+  # if not an OSlg constant (once converted), or if new level is below the
+  # current log level. Relies on OSlg method 'trim()': candidate log message is
+  # ignored and status unchanged if message is not a valid string.
   #
   # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL
   # @param message [#to_s] user-provided log message
+  # @param len [Numeric] maximum log message length (optional)
   #
   # @example A user warning
   #   log(WARN, "Surface area < 100cm2")
   #
   # @return [DEBUG, INFO, WARN, ERROR, FATAL] updated/current status
-  def log(lvl = DEBUG, message = "")
+  def log(lvl = DEBUG, message = "", len = nil)
     return @@status unless lvl.respond_to?(:to_i)
     return @@status unless message.respond_to?(:to_s)
 
     lvl = lvl.to_i
-    message = message.to_s
+    message = trim(message, len)
+    return @@status if message.empty?
     return @@status if lvl < DEBUG
     return @@status if lvl > FATAL
     return @@status if lvl < @@level
@@ -220,19 +228,24 @@ module OSlg
 
   ##
   # Logs template 'invalid object' message, if provided arguments are valid.
+  # Relies on OSlg method 'log()': first check out its own operation, exit
+  # conditions and module side effects. Candidate log entry is ignored and
+  # status remains unchanged if 'ord' cannot be converted to an integer.
+  # Argument 'ord' is ignored unless > 0.
   #
   # @param id [#to_s] 'invalid object' identifier
   # @param mth [#to_s] calling method identifier
   # @param ord [#to_i] calling method argument order number of obj (optional)
   # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL (optional)
   # @param res what to return (optional)
+  # @param len [Numeric] maximum log message length (optional)
   #
   # @example An invalid argument, logging a FATAL error, returning FALSE
   #   return invalid("area", "sum", 0, FATAL, false) if area > 1000000
   #
   # @return user-provided object
   # @return [nil] if user hasn't provided an object to return
-  def invalid(id = "", mth = "", ord = 0, lvl = DEBUG, res = nil)
+  def invalid(id = "", mth = "", ord = 0, lvl = DEBUG, res = nil, len = nil)
     return res unless id.respond_to?(:to_s)
     return res unless mth.respond_to?(:to_s)
     return res unless ord.respond_to?(:to_i)
@@ -250,7 +263,7 @@ module OSlg
     msg = "Invalid '#{id}' "
     msg += "arg ##{ord} " if ord > 0
     msg += "(#{mth})"
-    log(lvl, msg)
+    log(lvl, msg, len)
 
     res
   end
@@ -266,13 +279,14 @@ module OSlg
   # @param mth [#to_s] calling method identifier (optional)
   # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL (optional)
   # @param res what to return (optional)
+  # @param len [Numeric] maximum log message length (optional)
   #
   # @example A mismatched argument instance/class
   #   mismatch("area", area, Float, "sum") unless area.is_a?(Numeric)
   #
   # @return user-provided object
   # @return [nil] if user hasn't provided an object to return
-  def mismatch(id = "", obj = nil, cl = nil, mth = "", lvl = DEBUG, res = nil)
+  def mismatch(id = "", obj = nil, cl = nil, mth = "", lvl = DEBUG, res = nil, len = nil)
     return res unless id.respond_to?(:to_s)
     return res unless mth.respond_to?(:to_s)
     return res unless cl.is_a?(Class)
@@ -287,7 +301,7 @@ module OSlg
     return res if lvl < DEBUG
     return res if lvl > FATAL
 
-    log(lvl, "'#{id}' #{obj.class}? expecting #{cl} (#{mth})")
+    log(lvl, "'#{id}' #{obj.class}? expecting #{cl} (#{mth})", len)
 
     res
   end
@@ -302,13 +316,14 @@ module OSlg
   # @param mth [#to_s] calling method identifier
   # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL (optional)
   # @param res what to return (optional)
+  # @param len [Numeric] maximum log message length (optional)
   #
   # @example A missing Hash key
   #   hashkey("floor area", floor, :area, "sum") unless floor.key?(:area)
   #
   # @return user-provided object
   # @return [nil] if user hasn't provided an object to return
-  def hashkey(id = "", hsh = {}, key = "", mth = "", lvl = DEBUG, res = nil)
+  def hashkey(id = "", hsh = {}, key = "", mth = "", lvl = DEBUG, res = nil, len = nil)
     return res unless id.respond_to?(:to_s)
     return res unless hsh.is_a?(Hash)
     return res if hsh.key?(key)
@@ -323,7 +338,7 @@ module OSlg
     return res if lvl < DEBUG
     return res if lvl > FATAL
 
-    log(lvl, "Missing '#{key}' key in '#{id}' Hash (#{mth})")
+    log(lvl, "Missing '#{key}' key in '#{id}' Hash (#{mth})", len)
 
     res
   end
@@ -335,13 +350,14 @@ module OSlg
   # @param mth [#to_s] calling method identifier
   # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL (optional)
   # @param res what to return (optional)
+  # @param len [Numeric] maximum log message length (optional)
   #
   # @example An uninitialized variable, logging an ERROR, returning FALSE
   #   empty("zone", "conditioned?", FATAL, false) if space.thermalZone.empty?
   #
   # @return user-provided object
   # @return [nil] if user hasn't provided an object to return
-  def empty(id = "", mth = "", lvl = DEBUG, res = nil)
+  def empty(id = "", mth = "", lvl = DEBUG, res = nil, len = nil)
     return res unless id.respond_to?(:to_s)
     return res unless mth.respond_to?(:to_s)
     return res unless lvl.respond_to?(:to_i)
@@ -354,7 +370,7 @@ module OSlg
     return res if lvl < DEBUG
     return res if lvl > FATAL
 
-    log(lvl, "Empty '#{id}' (#{mth})")
+    log(lvl, "Empty '#{id}' (#{mth})", len)
 
     res
   end
@@ -366,13 +382,14 @@ module OSlg
   # @param mth [#to_s] calling method identifier
   # @param lvl [#to_i] DEBUG, INFO, WARN, ERROR or FATAL (optional)
   # @param res what to return (optional)
+  # @param len [Numeric] maximum log message length (optional)
   #
   # @example A near-zero variable
   #   zero("floor area", "sum") if floor[:area].abs < TOL
   #
   # @return user-provided object
   # @return [nil] if user hasn't provided an object to return
-  def zero(id = "", mth = "", lvl = DEBUG, res = nil)
+  def zero(id = "", mth = "", lvl = DEBUG, res = nil, len = nil)
     return res unless id.respond_to?(:to_s)
     return res unless mth.respond_to?(:to_s)
     return res unless lvl.respond_to?(:to_i)
@@ -386,7 +403,7 @@ module OSlg
     return res if lvl < DEBUG
     return res if lvl > FATAL
 
-    log(lvl, "Zero '#{id}' (#{mth})")
+    log(lvl, "Zero '#{id}' (#{mth})", len)
 
     res
   end
@@ -398,13 +415,14 @@ module OSlg
   # @param mth [String] calling method identifier
   # @param lvl [Integer] DEBUG, INFO, WARN, ERROR or FATAL (optional)
   # @param res [Object] what to return (optional)
+  # @param len [Numeric] maximum log message length (optional)
   #
   # @example A negative variable
   #   negative("floor area", "sum") if floor[:area] < 0
   #
   # @return user-provided object
   # @return [nil] if user hasn't provided an object to return
-  def negative(id = "", mth = "", lvl = DEBUG, res = nil)
+  def negative(id = "", mth = "", lvl = DEBUG, res = nil, len = nil)
     return res unless id.respond_to?(:to_s)
     return res unless mth.respond_to?(:to_s)
     return res unless lvl.respond_to?(:to_i)
@@ -417,7 +435,7 @@ module OSlg
     return res if lvl < DEBUG
     return res if lvl > FATAL
 
-    log(lvl, "Negative '#{id}' (#{mth})")
+    log(lvl, "Negative '#{id}' (#{mth})", len)
 
     res
   end

data/lib/measures/tbd/resources/psi.rb

@@ -1,6 +1,6 @@
 # MIT License
 #
-# Copyright (c) 2020-2024 Denis Bourgeois & Dan Macumber
+# Copyright (c) 2020-2025 Denis Bourgeois & Dan Macumber
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -1355,103 +1355,103 @@ module TBD
   ##
   # Thermally derates insulating material within construction.
   #
-  # @param id [#to_s] surface identifier
+  # @param id [#to_sym] surface identifier
   # @param [Hash] s TBD surface parameters
-  # @option s [#to_f] :heatloss heat loss from major thermal bridging, in W/K
-  # @option s [#to_f] :net surface net area, in m2
+  # @option s [Numeric] :heatloss heat loss from major thermal bridging, in W/K
+  # @option s [Numeric] :net surface net area, in m2
   # @option s [:massless, :standard] :ltype indexed layer type
-  # @option s [#to_i] :index deratable construction layer index
-  # @option s [#to_f] :r deratable layer Rsi-factor, in m2•K/W
+  # @option s [Integer] :index deratable construction layer index
+  # @option s [Numeric] :r deratable layer Rsi-factor, in m2•K/W
   # @param lc [OpenStudio::Model::LayeredConstruction] a layered construction
   #
-  # @return [OpenStudio::Model::Material] derated (cloned) material
+  # @return [OpenStudio::Model::OpaqueMaterial] derated (cloned) material
   # @return [nil] if invalid input (see logs)
   def derate(id = "", s = {}, lc = nil)
     mth = "TBD::#{__callee__}"
     m   = nil
-    id  = trim(id)
     kys = [:heatloss, :net, :ltype, :index, :r]
-    ck1 = s.is_a?(Hash)
-    ck2 = lc.is_a?(OpenStudio::Model::LayeredConstruction)
-    return mismatch("id"                , id, cl6, mth)     if id.empty?
-    return mismatch("#{id} surface"     , s , cl1, mth) unless ck1
-    return mismatch("#{id} construction", lc, cl2, mth) unless ck2
+    cl  = OpenStudio::Model::LayeredConstruction
+    return mismatch("lc", lc, cl, mth) unless lc.respond_to?(NS)
+    return mismatch("id", id, String, mth) unless id.respond_to?(:to_sym)
+
+    id  = trim(id)
+    nom = lc.nameString
+    return invalid("id", mth, 1) if id.empty?
+    return mismatch(nom, lc, cl, mth) unless lc.is_a?(cl)
+    return mismatch("#{nom} surface", s, Hash, mth) unless s.is_a?(Hash)
+
+    if nom.downcase.include?(" tbd")
+      log(WRN, "Won't derate '#{nom}': tagged as derated (#{mth})")
+      return m
+    end
 
     kys.each do |k|
       tag = "#{id} #{k}"
-      return hashkey(tag, s, k, mth, ERR) unless s.key?(k)
+      return hashkey(tag, s, k, mth) unless s.key?(k)
 
       case k
-      when :heatloss
-        return mismatch(tag, s[k], Numeric, mth) unless s[k].respond_to?(:to_f)
-        return zero(tag, mth, WRN)                   if s[k].to_f.abs < 0.001
-      when :net, :r
-        return mismatch(tag, s[k], Numeric, mth) unless s[k].respond_to?(:to_f)
-        return negative(tag, mth, 2, ERR)            if s[k].to_f < 0
-        return zero(tag, mth, WRN)                   if s[k].to_f.abs < 0.001
-      when :index
-        return mismatch(tag, s[k], Numeric, mth) unless s[k].respond_to?(:to_i)
-        return negative(tag, mth, 2, ERR)            if s[k].to_f < 0
-      else # :ltype
+      when :ltype
         next if [:massless, :standard].include?(s[k])
-        return invalid(tag, mth, 2, ERR)
-      end
-    end
+        return invalid(tag, mth, 2)
+      when :index
+        return mismatch(tag, s[k], Integer, mth) unless s[k].is_a?(Integer)
+        return invalid(tag, mth, 2) unless s[k].between?(0, lc.numLayers - 1)
+      else
+        return mismatch(tag, s[k], Numeric, mth) unless s[k].is_a?(Numeric)
+        next if k == :heatloss
 
-    if lc.nameString.downcase.include?(" tbd")
-      log(WRN, "Won't derate '#{id}': tagged as derated (#{mth})")
-      return m
+        return negative(tag, mth, 2) if s[k] < 0
+        return zero(tag, mth) if s[k].abs < 0.001
+      end
     end
 
     model = lc.model
-    ltype = s[:ltype   ]
-    index = s[:index   ].to_i
-    net   = s[:net     ].to_f
-    r     = s[:r       ].to_f
-    u     = s[:heatloss].to_f / net
+    ltype = s[:ltype]
+    index = s[:index]
+    net   = s[:net]
+    r     = s[:r]
+    u     = s[:heatloss] / net
     loss  = 0
-    de_u  = 1 / r + u # derated U
-    de_r  = 1 / de_u  # derated R
+    de_u  = 1 / r + u # derated insulating material U
+    de_r  = 1 / de_u  # derated insulating material R
 
     if ltype == :massless
-      m    = lc.getLayer(index).to_MasslessOpaqueMaterial
+      m = lc.getLayer(index).to_MasslessOpaqueMaterial
       return invalid("#{id} massless layer?", mth, 0) if m.empty?
-      m    = m.get
-      up   = ""
-      up   = "uprated " if m.nameString.downcase.include?(" uprated")
-      m    = m.clone(model).to_MasslessOpaqueMaterial.get
-             m.setName("#{id} #{up}m tbd")
-      de_r = 0.001                   unless de_r > 0.001
-      loss = (de_u - 1 / de_r) * net unless de_r > 0.001
-             m.setThermalResistance(de_r)
+
+      m  = m.get
+      up = m.nameString.downcase.include?(" uprated") ? "uprated " : ""
+      m  = m.clone(model).to_MasslessOpaqueMaterial.get
+      m.setName("#{id} #{up}m tbd")
+
+      de_r = RMIN                    unless de_r > RMIN
+      loss = (de_u - 1 / de_r) * net unless de_r > RMIN
+
+      unless m.setThermalResistance(de_r)
+        return invalid("Can't derate #{id}: RSi#{de_r.round(2)}", mth)
+      end
     else
-      m    = lc.getLayer(index).to_StandardOpaqueMaterial
+      m = lc.getLayer(index).to_StandardOpaqueMaterial
       return invalid("#{id} standard layer?", mth, 0) if m.empty?
-      m    = m.get
-      up   = ""
-      up   = "uprated " if m.nameString.downcase.include?(" uprated")
-      m    = m.clone(model).to_StandardOpaqueMaterial.get
-             m.setName("#{id} #{up}m tbd")
-      k    = m.thermalConductivity
-
-      if de_r > 0.001
-        d  = de_r * k
-
-        unless d > 0.003
-          d    = 0.003
-          k    = d / de_r
-          k    = 3                    unless k < 3
-          loss = (de_u - k / d) * net unless k < 3
-        end
-      else # de_r < 0.001 m2•K/W
-        d    = 0.001 * k
-        d    = 0.003                  unless d > 0.003
-        k    = d / 0.001              unless d > 0.003
-        loss = (de_u - k / d) * net
+
+      m  = m.get
+      up = m.nameString.downcase.include?(" uprated") ? "uprated " : ""
+      m  = m.clone(model).to_StandardOpaqueMaterial.get
+      m.setName("#{id} #{up}m tbd")
+
+      d  = m.thickness
+      k  = (d / de_r).clamp(KMIN, KMAX)
+      d  = (k * de_r).clamp(DMIN, DMAX)
+
+      loss = (de_u - k / d) * net unless d / k > RMIN
+
+      unless m.setThermalConductivity(k)
+        return invalid("Can't derate #{id}: K#{k.round(3)}", mth)
       end
 
-      m.setThickness(d)
-      m.setThermalConductivity(k)
+      unless m.setThickness(d)
+        return invalid("Can't derate #{id}: #{(d*1000).to_i}mm", mth)
+      end
     end
 
     if m && loss > TOL
@@ -1941,14 +1941,38 @@ module TBD
             ids = windows.keys + doors.keys + skylights.keys
           end
 
-          unless ids.include?(i)
-            log(ERR, "Orphaned subsurface #{i} (mth)")
+          adj = nil
+
+          unless ids.include?(i) # adjacent sub surface?
+            sb = model.getSubSurfaceByName(i)
+
+            if sb.empty?
+              log(DBG, "Orphaned subsurface #{i} (#{mth})?")
+            else
+              sb  = sb.get
+              adj = sb.adjacentSubSurface
+
+              if adj.empty?
+                log(DBG, "Orphaned sub #{i} (#{mth})?")
+              end
+            end
+
             next
           end
 
-          window   =   windows.key?(i) ?   windows[i] : {}
-          door     =     doors.key?(i) ?     doors[i] : {}
-          skylight = skylights.key?(i) ? skylights[i] : {}
+          if adj
+            window   =   windows.key?(i) ?   windows[i] : {}
+            door     =     doors.key?(i) ?     doors[i] : {}
+            skylight = skylights.key?(i) ? skylights[i] : {}
+          else
+            window   =   windows.key?(i) ?   windows[i] : {}
+            door     =     doors.key?(i) ?     doors[i] : {}
+            skylight = skylights.key?(i) ? skylights[i] : {}
+          end
+
+          # window   =   windows.key?(i) ?   windows[i] : {}
+          # door     =     doors.key?(i) ?     doors[i] : {}
+          # skylight = skylights.key?(i) ? skylights[i] : {}
 
           sub = window   unless window.empty?
           sub = door     unless door.empty?
@@ -2939,12 +2963,12 @@ module TBD
     up = argh[:uprate_walls] || argh[:uprate_roofs] || argh[:uprate_floors]
     uprate(model, tbd[:surfaces], argh) if up
 
-    # Derated (cloned) constructions are unique to each deratable surface.
-    # Unique construction names are prefixed with the surface name,
-    # and suffixed with " tbd", indicating that the construction is
-    # henceforth thermally derated. The " tbd" expression is also key in
-    # avoiding inadvertent derating - TBD will not derate constructions
-    # (or rather layered materials) having " tbd" in their OpenStudio name.
+    # A derated (cloned) construction and (cloned) insulating layer are unique
+    # to each deratable surface. Unique construction and material names are
+    # prefixed with the surface name, and suffixed with " tbd", indicating that
+    # the construction is henceforth thermally derated. The " tbd" expression
+    # is also key in avoiding inadvertent sequential derating - TBD will not
+    # derate a construction/material pair having " tbd" in their OpenStudio name.
     tbd[:surfaces].each do |id, surface|
       next unless surface.key?(:construction)
       next unless surface.key?(:index)
@@ -3138,9 +3162,9 @@ module TBD
     argh[:uprate_walls ] = false unless argh.key?(:uprate_walls )
     argh[:uprate_roofs ] = false unless argh.key?(:uprate_roofs )
     argh[:uprate_floors] = false unless argh.key?(:uprate_floors)
-    argh[:wall_ut      ] = 5.678 unless argh.key?(:wall_ut      )
-    argh[:roof_ut      ] = 5.678 unless argh.key?(:roof_ut      )
-    argh[:floor_ut     ] = 5.678 unless argh.key?(:floor_ut     )
+    argh[:wall_ut      ] = UMAX  unless argh.key?(:wall_ut      )
+    argh[:roof_ut      ] = UMAX  unless argh.key?(:roof_ut      )
+    argh[:floor_ut     ] = UMAX  unless argh.key?(:floor_ut     )
     argh[:wall_option  ] = ""    unless argh.key?(:wall_option  )
     argh[:roof_option  ] = ""    unless argh.key?(:roof_option  )
     argh[:floor_option ] = ""    unless argh.key?(:floor_option )

data/lib/measures/tbd/resources/tbd.rb

@@ -1,6 +1,6 @@
 # MIT License
 #
-# Copyright (c) 2020-2024 Denis Bourgeois & Dan Macumber
+# Copyright (c) 2020-2025 Denis Bourgeois & Dan Macumber
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal