tbd 3.1.1 → 3.2.0

data/lib/measures/tbd/tests/tbd_tests.rb

@@ -1,6 +1,6 @@
 # MIT License
 #
-# Copyright (c) 2020-2022 Denis Bourgeois & Dan Macumber
+# Copyright (c) 2020-2023 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
@@ -36,187 +36,217 @@ class TBDTest < Minitest::Test
   # end
 
   def test_number_of_arguments_and_argument_names
-    # create an instance of the measure
     measure = TBDMeasure.new
-    # make an empty model
     model = OpenStudio::Model::Model.new
-
-    # get arguments and test that they are what we are expecting
     arguments = measure.arguments(model)
-    assert_equal(14, arguments.size)
+    assert_equal(15, arguments.size)
   end
 
   def test_no_load_tbd_json
-    # create an instance of the measure
     measure = TBDMeasure.new
 
-    # Output dirs
-    seed_dir = File.join(__dir__, 'output/no_load_tbd_json/')
+    # Output directories.
+    seed_dir = File.join(__dir__, "output/no_load_tbd_json/")
     FileUtils.mkdir_p(seed_dir)
-    seed_path = File.join(seed_dir, 'in.osm')
+    seed_path = File.join(seed_dir, "in.osm")
 
-    # create runner with empty OSW
+    # Create runner with empty OSW, and example test model.
     osw = OpenStudio::WorkflowJSON.new
     osw.setSeedFile(seed_path)
     runner = OpenStudio::Measure::OSRunner.new(osw)
-
-    # create example test model
     model = OpenStudio::Model::exampleModel
     model.save(seed_path, true)
 
-    # get arguments
+    # Get measure arguments.
     arguments = measure.arguments(model)
     argument_map = OpenStudio::Measure.convertOSArgumentVectorToMap(arguments)
 
-    # Create hash of argument values. If the argument has a default that you
-    # want to use, you don't need it in the hash.
-    args_hash                   = {}
-    args_hash["option"        ] = "efficient (BETBG)"
-    args_hash["write_tbd_json"] = true
-    args_hash["gen_UA_report" ] = true
-    args_hash["wall_option"   ] = "ALL wall constructions"
-    args_hash["wall_ut"       ] = 0.5
-    # using defaults values from measure.rb for other arguments
-
-    # populate argument with specified hash value if specified
+    # Hash of argument values (defaults from measure.rb for other arguments).
+    argh                   = {}
+    argh["option"        ] = "efficient (BETBG)"
+    argh["write_tbd_json"] = true
+    argh["gen_UA_report" ] = true
+    argh["wall_option"   ] = "ALL wall constructions"
+    argh["wall_ut"       ] = 0.5
+
+    # Populate arguments with specified hash value if specified.
     arguments.each do |arg|
       temp_arg_var = arg.clone
-      gotit = args_hash.key?(arg.name)
-      assert(temp_arg_var.setValue(args_hash[arg.name])) if gotit
+      assert(temp_arg_var.setValue(argh[arg.name])) if argh.key?(arg.name)
       argument_map[arg.name] = temp_arg_var
     end
 
-    # run the measure
+    # Run the measure and assert that it ran correctly.
     Dir.chdir(seed_dir)
     measure.run(model, runner, argument_map)
     result = runner.result
-
-    # show the output
     show_output(result)
-
-    # assert that it ran correctly
-    assert_equal('Success', result.value.valueName)
+    assert_equal("Success", result.value.valueName)
     assert(result.warnings.empty?)
+    assert(result.errors.empty?)
 
-    # save the model to test output directory
-    #output_file_path = "#{File.dirname(__FILE__)}//output/test_output.osm"
-    #model.save(output_file_path, true)
+    # Save the model to test output directory.
+    output_path = File.join(seed_dir, "out.osm")
+    model.save(output_path, true)
   end
 
   def test_load_tbd_json
-    # create an instance of the measure
     measure = TBDMeasure.new
 
-    # Output dirs
+    # Output directories.
     seed_dir = File.join(__dir__, "output/load_tbd_json/")
     FileUtils.mkdir_p(seed_dir)
     seed_path = File.join(seed_dir, "in.osm")
 
-    # create runner with empty OSW
+    # Create runner with empty OSW, and example test model.
     osw = OpenStudio::WorkflowJSON.new
     osw.setSeedFile(seed_path)
     runner = OpenStudio::Measure::OSRunner.new(osw)
-
-    # create example test model
     model = OpenStudio::Model::exampleModel
     model.save(seed_path, true)
 
-    # copy tdb.json next to seed
+    # Copy tdb.json next to seed.
     origin_pth = File.join(__dir__, "tbd_full_PSI.json")
     target_pth = File.join(seed_dir, "tbd.json")
     FileUtils.cp(origin_pth, target_pth)
 
-    # get arguments
+    # Get measure arguments.
     arguments = measure.arguments(model)
     argument_map = OpenStudio::Measure.convertOSArgumentVectorToMap(arguments)
 
-    # Create hash of argument values. If the argument has a default that you
-    # want to use, you don't need it in the hash.
-    args_hash = {"load_tbd_json" => true}
-    # using defaults values from measure.rb for other arguments
+    # Hash of argument values (defaults from measure.rb for other arguments).
+    argh                   = {}
+    argh["load_tbd_json" ] = true
 
-    # populate argument with specified hash value if specified
+    # Populate arguments with specified hash value if specified.
     arguments.each do |arg|
       temp_arg_var = arg.clone
-      if args_hash.key?(arg.name)
-        assert(temp_arg_var.setValue(args_hash[arg.name]))
-      end
+      assert(temp_arg_var.setValue(argh[arg.name])) if argh.key?(arg.name)
       argument_map[arg.name] = temp_arg_var
     end
 
-    # run the measure
+    # Run the measure and assert that it ran correctly.
     Dir.chdir(seed_dir)
     measure.run(model, runner, argument_map)
     result = runner.result
-
-    # show the output
     show_output(result)
-
-    # assert that it ran correctly
-    assert_equal('Success', result.value.valueName)
+    assert_equal("Success", result.value.valueName)
     assert(result.warnings.empty?)
+    assert(result.errors.empty?)
 
-    # save the model to test output directory
-    #output_file_path = "#{File.dirname(__FILE__)}//output/test_output.osm"
-    #model.save(output_file_path, true)
+    # Save the model to test output directory.
+    output_path = File.join(seed_dir, "out.osm")
+    model.save(output_path, true)
   end
 
   def test_load_tbd_json_error
-    # create an instance of the measure
     measure = TBDMeasure.new
 
-    # Output dirs
+    # Output directories.
     seed_dir = File.join(__dir__, "output/load_tbd_json_error/")
     FileUtils.mkdir_p(seed_dir)
     seed_path = File.join(seed_dir, "in.osm")
 
-    # create runner with empty OSW
+    # Create runner with empty OSW, and example test model.
     osw = OpenStudio::WorkflowJSON.new
     osw.setSeedFile(seed_path)
     runner = OpenStudio::Measure::OSRunner.new(osw)
-
-    # create example test model
     model = OpenStudio::Model::exampleModel
     model.save(seed_path, true)
 
-    # do not copy tdb.json next to seed
+    # POSTULATED USER ERROR: Do not copy tdb.json next to seed.
 
-    # get arguments
+    # Get measure arguments.
     arguments = measure.arguments(model)
     argument_map = OpenStudio::Measure.convertOSArgumentVectorToMap(arguments)
 
-    # Create hash of argument values. If the argument has a default that you
-    # want to use, you don't need it in the hash.
-    args_hash = {"load_tbd_json" => true}
-    # using defaults values from measure.rb for other arguments
+    # Hash of argument values (defaults from measure.rb for other arguments).
+    argh                   = {}
+    argh["load_tbd_json" ] = true
 
-    # populate argument with specified hash value if specified
+    # Populate argument with specified hash value if specified.
     arguments.each do |arg|
       temp_arg_var = arg.clone
-      if args_hash.key?(arg.name)
-        assert(temp_arg_var.setValue(args_hash[arg.name]))
-      end
+      assert(temp_arg_var.setValue(argh[arg.name])) if argh.key?(arg.name)
       argument_map[arg.name] = temp_arg_var
     end
 
-    # run the measure
+    # Run the measure, assert that it did not run correctly.
     Dir.chdir(seed_dir)
     measure.run(model, runner, argument_map)
     result = runner.result
-
-    # show the output
     show_output(result)
+    assert_equal("Fail", result.value.valueName)
 
-    # assert that it ran correctly
-    assert_equal('Fail', result.value.valueName)
-    assert(result.errors.size == 1)
     assert(result.warnings.size == 1)
-    puts result.warnings[0].logMessage
-    log_message = "Can't find 'tbd.json' - simulation halted"
-    assert(result.warnings[0].logMessage == log_message)
+    message = result.warnings[0].logMessage
+    puts message
+    assert(message.include?("Can't find 'tbd.json' - simulation halted"))
+
+    assert(result.errors.size == 1)
+    message = result.errors[0].logMessage
+    puts message
+    assert(message.include?("Halting all TBD processes, "))
+    assert(message.include?("and halting OpenStudio - see 'tbd.out.json'"))
+
+    # Save the model to test output directory.
+    output_path = File.join(seed_dir, "out.osm")
+    model.save(output_path, true)
+  end
+
+  def test_tbd_kiva_massless_error
+    measure = TBDMeasure.new
+
+    # Output directories.
+    seed_dir = File.join(__dir__, "output/tbd_kiva_massless_error/")
+    FileUtils.mkdir_p(seed_dir)
+    seed_path = File.join(seed_dir, "in.osm")
+
+    # Create runner with empty OSW, and example test model.
+    osw = OpenStudio::WorkflowJSON.new
+    osw.setSeedFile(seed_path)
+    runner = OpenStudio::Measure::OSRunner.new(osw)
+    model = OpenStudio::Model::exampleModel
+    model.save(seed_path, true)
+
+    # Copy tdb.json next to seed.
+    origin_pth = File.join(__dir__, "tbd_full_PSI.json")
+    target_pth = File.join(seed_dir, "tbd.json")
+    FileUtils.cp(origin_pth, target_pth)
+
+    # Get measure arguments.
+    arguments = measure.arguments(model)
+    argument_map = OpenStudio::Measure.convertOSArgumentVectorToMap(arguments)
+
+    # Hash of argument values (defaults from measure.rb for other arguments).
+    argh                   = {}
+    argh["gen_kiva_force"] = true
+
+    # POSTULATED USER ERROR : Slab on grade construction holds a massless layer.
+
+    # Populate argument with specified hash value if specified.
+    arguments.each do |arg|
+      temp_arg_var = arg.clone
+      assert(temp_arg_var.setValue(argh[arg.name])) if argh.key?(arg.name)
+      argument_map[arg.name] = temp_arg_var
+    end
+
+    # Run the measure, assert that it did not run correctly.
+    Dir.chdir(seed_dir)
+    measure.run(model, runner, argument_map)
+    result = runner.result
+    show_output(result)
+    assert_equal("Fail", result.value.valueName)
+    assert(result.warnings.empty?)
+    assert(result.errors.size == 4)
+
+    result.errors.each do |error|
+      assert(error.logMessage.include?("KIVA requires standard materials ("))
+    end
 
-    # save the model to test output directory
-    #output_file_path = "#{File.dirname(__FILE__)}//output/test_output.osm"
-    #model.save(output_file_path, true)
+    # Save the model to test output directory. There should be neither instance
+    # of KIVA objects nor TBD derated materials/constructions.
+    output_path = File.join(seed_dir, "out.osm")
+    model.save(output_path, true)
   end
 end

data/lib/tbd/geo.rb

@@ -1,6 +1,6 @@
 # MIT License
 #
-# Copyright (c) 2020-2022 Denis Bourgeois & Dan Macumber
+# Copyright (c) 2020-2023 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
@@ -22,24 +22,27 @@
 
 module TBD
   ##
-  # Check for matching Topolys vertex pairs between edges (within TOL).
+  # Check for matching Topolys vertex pairs between edges.
   #
   # @param e1 [Hash] first edge
   # @param e2 [Hash] second edge
+  # @param tol [Float] user-set tolerance (> TOL) in m
   #
   # @return [Bool] true if edges share vertex pairs
   # @return [Bool] false if invalid input
-  def matches?(e1 = {}, e2 = {})
+  def matches?(e1 = {}, e2 = {}, tol = TOL)
     mth = "TBD::#{__callee__}"
     cl  = Topolys::Point3D
     a   = false
 
     return mismatch("e1", e1, Hash, mth, DBG, a)        unless e1.is_a?(Hash)
     return mismatch("e2", e2, Hash, mth, DBG, a)        unless e2.is_a?(Hash)
+
     return hashkey("e1", e1, :v0, mth, DBG, a)          unless e1.key?(:v0)
     return hashkey("e1", e1, :v1, mth, DBG, a)          unless e1.key?(:v1)
     return hashkey("e2", e2, :v0, mth, DBG, a)          unless e2.key?(:v0)
     return hashkey("e2", e2, :v1, mth, DBG, a)          unless e2.key?(:v1)
+
     return mismatch("e1 :v0", e1[:v0], cl, mth, DBG, a) unless e1[:v0].is_a?(cl)
     return mismatch("e1 :v1", e1[:v1], cl, mth, DBG, a) unless e1[:v1].is_a?(cl)
     return mismatch("e2 :v0", e2[:v0], cl, mth, DBG, a) unless e2[:v0].is_a?(cl)
@@ -51,26 +54,29 @@ module TBD
     return zero("e1", mth, DBG, a) if e1_vector.magnitude < TOL
     return zero("e2", mth, DBG, a) if e2_vector.magnitude < TOL
 
+    return mismatch("e1", e1, Hash, mth, DBG, a)       unless tol.is_a?(Numeric)
+    return zero("tol", mth, DBG, a)                        if tol < TOL
+
     return true if
     (
       (
-        ( (e1[:v0].x - e2[:v0].x).abs < TOL &&
-          (e1[:v0].y - e2[:v0].y).abs < TOL &&
-          (e1[:v0].z - e2[:v0].z).abs < TOL
+        ( (e1[:v0].x - e2[:v0].x).abs < tol &&
+          (e1[:v0].y - e2[:v0].y).abs < tol &&
+          (e1[:v0].z - e2[:v0].z).abs < tol
         ) ||
-        ( (e1[:v0].x - e2[:v1].x).abs < TOL &&
-          (e1[:v0].y - e2[:v1].y).abs < TOL &&
-          (e1[:v0].z - e2[:v1].z).abs < TOL
+        ( (e1[:v0].x - e2[:v1].x).abs < tol &&
+          (e1[:v0].y - e2[:v1].y).abs < tol &&
+          (e1[:v0].z - e2[:v1].z).abs < tol
         )
       ) &&
       (
-        ( (e1[:v1].x - e2[:v0].x).abs < TOL &&
-          (e1[:v1].y - e2[:v0].y).abs < TOL &&
-          (e1[:v1].z - e2[:v0].z).abs < TOL
+        ( (e1[:v1].x - e2[:v0].x).abs < tol &&
+          (e1[:v1].y - e2[:v0].y).abs < tol &&
+          (e1[:v1].z - e2[:v0].z).abs < tol
         ) ||
-        ( (e1[:v1].x - e2[:v1].x).abs < TOL &&
-          (e1[:v1].y - e2[:v1].y).abs < TOL &&
-          (e1[:v1].z - e2[:v1].z).abs < TOL
+        ( (e1[:v1].x - e2[:v1].x).abs < tol &&
+          (e1[:v1].y - e2[:v1].y).abs < tol &&
+          (e1[:v1].z - e2[:v1].z).abs < tol
         )
       )
     )
@@ -354,6 +360,7 @@ module TBD
       next                                                          unless valid
       vec      = s.vertices
       area     = s.grossArea
+      mult     = s.multiplier
       typ      = s.subSurfaceType.downcase
       type     = :skylight
       type     = :window       if typ.include?("window" )
@@ -442,6 +449,7 @@ module TBD
               n:        n,
               gross:    s.grossArea,
               area:     area,
+              mult:     mult,
               type:     type,
               u:        u,
               unhinged: unhinged }
@@ -478,7 +486,9 @@ module TBD
     end
 
     subarea = 0
-    subs.values.each { |sub| subarea += sub[:area] }
+
+    subs.values.each { |sub| subarea += sub[:area] * sub[:mult] }
+
     surf[:net] = surf[:gross] - subarea
 
     # Tranform final Point 3D sets, and store.
@@ -604,6 +614,36 @@ module TBD
     return mismatch("floors", floors, cl2, mth, DBG, a) unless floors.is_a?(cl2)
     return mismatch("edges", edges, cl2, mth, DBG, a)   unless edges.is_a?(cl2)
 
+    kva = true
+
+    # Pre-validate foundation-facing constructions.
+    model.getSurfaces.each do |s|
+      id = s.nameString
+      construction = s.construction
+      next unless s.outsideBoundaryCondition.downcase == "foundation"
+
+      if construction.empty?
+        log(ERR, "Invalid construction for KIVA (see #{id})")
+        kva = false if kva
+      else
+        construction = construction.get.to_LayeredConstruction
+
+        if construction.empty?
+          log(ERR, "KIVA requires layered constructions (see #{id})")
+          kva = false if kva
+        else
+          construction = construction.get
+
+          unless standardOpaqueLayers?(construction)
+            log(ERR, "KIVA requires standard materials (see #{id})")
+            kva = false if kva
+          end
+        end
+      end
+    end
+
+    return a unless kva
+
     # Strictly relying on Kiva's total exposed perimeter approach.
     arg = "TotalExposedPerimeter"
     kiva = true

data/lib/tbd/psi.rb

@@ -1,6 +1,6 @@
 # MIT License
 #
-# Copyright (c) 2020-2022 Denis Bourgeois & Dan Macumber
+# Copyright (c) 2020-2023 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
@@ -913,6 +913,7 @@ module TBD
     return mismatch("argh", argh, Hash, mth, DBG, tbd) unless argh.is_a?(Hash)
 
     argh                 = {}                       if argh.empty?
+    argh[:sub_tol      ] = TBD::TOL             unless argh.key?(:sub_tol      )
     argh[:option       ] = ""                   unless argh.key?(:option       )
     argh[:io_path      ] = nil                  unless argh.key?(:io_path      )
     argh[:schema_path  ] = nil                  unless argh.key?(:schema_path  )
@@ -1174,9 +1175,6 @@ module TBD
             farthest_V = origin_point_V if farther
           end
 
-          puts "ADDITION!!"                      if id == "ADDITION"
-          puts "#{reference_V} vs #{farthest_V}" if id == "ADDITION"
-
           angle = reference_V.angle(farthest_V)
           invalid("#{id} polar angle", mth, 0, ERROR, 0) if angle.nil?
           angle = 0                                      if angle.nil?
@@ -1771,13 +1769,120 @@ module TBD
       end
     end
 
+    # Fetch edge multipliers for subsurfaces, if applicable.
+    edges.values.each do |edge|
+      next     if edge.key?(:mult)                    # skip if already assigned
+      next unless edge.key?(:surfaces)
+      next unless edge.key?(:psi)
+      ok = false
+
+      edge[:psi].keys.each do |k|
+        break if ok
+
+        jamb = k.to_s.include?("jamb")
+        sill = k.to_s.include?("sill")
+        head = k.to_s.include?("head")
+        ok   = jamb || sill || head
+      end
+
+      next unless ok     # if OK, edge links subsurface(s) ... yet which one(s)?
+
+      edge[:surfaces].each do |id, surface|
+        next unless tbd[:surfaces].key?(id)    # look up parent (opaque) surface
+
+        [:windows, :doors, :skylights].each do |subtypes|
+          next unless tbd[:surfaces][id].key?(subtypes)
+
+          tbd[:surfaces][id][subtypes].each do |nom, sub|
+            next unless edge[:surfaces].key?(nom)
+            next unless sub[:mult] > 1
+
+            # An edge may be tagged with (potentially conflicting) multipliers.
+            # This is only possible if the edge links 2 subsurfaces, e.g. a
+            # shared jamb between window & door. By default, TBD tags common
+            # subsurface edges as (mild) "transitions" (i.e. PSI 0 W/K.m), so
+            # there would be no point in assigning an edge multiplier. Users
+            # can however reset an edge type via a TBD JSON input file (e.g.
+            # "joint" instead of "transition"). It would be a very odd choice,
+            # but TBD doesn't prohibit it. If linked subsurfaces have different
+            # multipliers (e.g. 2 vs 3), TBD tracks the highest value.
+            edge[:mult] = sub[:mult] unless edge.key?(:mult)
+            edge[:mult] = sub[:mult]     if sub[:mult] > edge[:mult]
+          end
+        end
+      end
+    end
+
+    # Unless a user has set the thermal bridge type of an individual edge via
+    # JSON input, reset any subsurface's head, sill or jamb edges as (mild)
+    # transitions when in close proximity to another subsurface edge. Both
+    # edges' origin and terminal vertices must be in close proximity. Edges
+    # of unhinged subsurfaces are ignored.
+    edges.each do |id, edge|
+      nb    = 0                            # linked subsurfaces (i.e. "holes")
+      match = false
+      next if edge.key?(:io_type)          # skip if set in JSON
+      next unless edge.key?(:v0)
+      next unless edge.key?(:v1)
+      next unless edge.key?(:psi)
+      next unless edge.key?(:surfaces)
+
+      edge[:surfaces].keys.each do |identifier|
+        break    if match
+        next unless holes.key?(identifier)
+
+        if holes[identifier].attributes.key?(:unhinged)
+          nb = 0 if holes[identifier].attributes[:unhinged]
+          break  if holes[identifier].attributes[:unhinged]
+        end
+
+        nb += 1
+        match = true if nb > 1
+      end
+
+      if nb == 1 # linking 1x subsurface, search for 1x other.
+        e1 = { v0: edge[:v0].point, v1: edge[:v1].point }
+
+        edges.each do |nom, e|
+          nb = 0
+          break    if match
+          next     if nom == id
+          next     if e.key?(:io_type)
+          next unless e.key?(:psi)
+          next unless e.key?(:surfaces)
+
+          e[:surfaces].keys.each do |identifier|
+            next unless holes.key?(identifier)
+
+            if holes[identifier].attributes.key?(:unhinged)
+              nb = 0 if holes[identifier].attributes[:unhinged]
+              break  if holes[identifier].attributes[:unhinged]
+            end
+
+            nb += 1
+          end
+
+          next unless nb == 1 # only process edge if linking 1x subsurface
+
+          e2 = { v0: e[:v0].point, v1: e[:v1].point }
+          match = matches?(e1, e2, argh[:sub_tol])
+        end
+      end
+
+      next unless match
+
+      edge[:psi] = { transition: 0.000 }
+      edge[:set] = json[:io][:building][:psi]
+    end
+
     # Loop through each edge and assign heat loss to linked surfaces.
     edges.each do |identifier, edge|
       next unless  edge.key?(:psi)
       rsi        = 0
-      max        = edge[:psi].values.max
-      type       = edge[:psi].key(max)
+      max        = edge[:psi   ].values.max
+      type       = edge[:psi   ].key(max)
       length     = edge[:length]
+      length    *= edge[:mult  ] if edge.key?(:mult)
       bridge     = { psi: max, type: type, length: length }
       deratables = {}
       apertures  = {}
@@ -1869,7 +1974,7 @@ module TBD
     # ... first 'uprate' targeted insulation layers (see ua.rb) before derating.
     # Check for new argh keys [:wall_uo], [:roof_uo] and/or [:floor_uo].
     up = argh[:uprate_walls] || argh[:uprate_roofs] || argh[:uprate_floors]
-    uprate(model, tbd[:surfaces], argh)                                    if up
+    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,
@@ -1975,6 +2080,7 @@ module TBD
       set        = e[:set]
       t          = e[:psi].key(v)
       l          = e[:length]
+      l         *= e[:mult] if e.key?(:mult)
       edge       = { psi: set, type: t, length: l, surfaces: e[:surfaces].keys }
       edge[:v0x] = e[:v0].point.x
       edge[:v0y] = e[:v0].point.y