Module: TBD

#concave?(s1 = nil, s2 = nil) ⇒ `Bool`, `false`

Validates whether edge surfaces form a concave angle, as seen from outside.

Parameters:

s1 (Hash) (defaults to: nil) —

first TBD surface
s2 (Hash) (defaults to: nil) —

second TBD surface

Options Hash (s1):

:normal (Topolys::Vector3D) —

surface normal vector
:polar (Topolys::Vector3D) —

vector around edge
:angle (Numeric) —

polar angle vs reference (e.g. North, Zenith)

Returns:

(Bool) —

true if angle between surfaces is concave
(false) —

if invalid input (see logs)

# File 'lib/tbd/geo.rb', line 622

def concave?(s1 = nil, s2 = nil)
  mth = "TBD::#{__callee__}"
  return mismatch("s1", s1, Hash, mth, DBG, false) unless s1.is_a?(Hash)
  return mismatch("s2", s2, Hash, mth, DBG, false) unless s2.is_a?(Hash)
  return false if s1 == s2

  return hashkey("s1", s1,  :angle, mth, DBG, false) unless s1.key?(:angle)
  return hashkey("s2", s2,  :angle, mth, DBG, false) unless s2.key?(:angle)
  return hashkey("s1", s1, :normal, mth, DBG, false) unless s1.key?(:normal)
  return hashkey("s2", s2, :normal, mth, DBG, false) unless s2.key?(:normal)
  return hashkey("s1", s1,  :polar, mth, DBG, false) unless s1.key?(:polar)
  return hashkey("s2", s2,  :polar, mth, DBG, false) unless s2.key?(:polar)

  valid1 = s1[:angle].is_a?(Numeric)
  valid2 = s2[:angle].is_a?(Numeric)
  return mismatch("s1 angle", s1[:angle], Numeric, DBG, false) unless valid1
  return mismatch("s1 angle", s1[:angle], Numeric, DBG, false) unless valid2

  angle = 0
  angle = s2[:angle] - s1[:angle] if s2[:angle] > s1[:angle]
  angle = s1[:angle] - s2[:angle] if s1[:angle] > s2[:angle]
  return false if angle < TOL
  return false unless (2 * Math::PI - angle).abs > TOL
  return false if angle > 3 * Math::PI / 4 && angle < 5 * Math::PI / 4

  n1_d_p2 = s1[:normal].dot(s2[:polar])
  p1_d_n2 = s1[:polar].dot(s2[:normal])
  return true if n1_d_p2 > 0 && p1_d_n2 > 0

  false
end

#convex?(s1 = nil, s2 = nil) ⇒ `Bool`, `false`

Validates whether edge surfaces form a convex angle, as seen from outside.

Parameters:

s1 (Hash) (defaults to: nil) —

first TBD surface
s2 (Hash) (defaults to: nil) —

second TBD surface

Options Hash (s1):

:normal (Topolys::Vector3D) —

surface normal vector
:polar (Topolys::Vector3D) —

vector around edge
:angle (Numeric) —

polar angle vs reference (e.g. North, Zenith)

Returns:

(Bool) —

true if angle between surfaces is convex
(false) —

if invalid input (see logs)

# File 'lib/tbd/geo.rb', line 665

def convex?(s1 = nil, s2 = nil)
  mth = "TBD::#{__callee__}"
  return mismatch("s1", s1, Hash, mth, DBG, false) unless s1.is_a?(Hash)
  return mismatch("s2", s2, Hash, mth, DBG, false) unless s2.is_a?(Hash)
  return false if s1 == s2

  return hashkey("s1", s1,  :angle, mth, DBG, false) unless s1.key?(:angle)
  return hashkey("s2", s2,  :angle, mth, DBG, false) unless s2.key?(:angle)
  return hashkey("s1", s1, :normal, mth, DBG, false) unless s1.key?(:normal)
  return hashkey("s2", s2, :normal, mth, DBG, false) unless s2.key?(:normal)
  return hashkey("s1", s1,  :polar, mth, DBG, false) unless s1.key?(:polar)
  return hashkey("s2", s2,  :polar, mth, DBG, false) unless s2.key?(:polar)

  valid1 = s1[:angle].is_a?(Numeric)
  valid2 = s2[:angle].is_a?(Numeric)
  return mismatch("s1 angle", s1[:angle], Numeric, DBG, false) unless valid1
  return mismatch("s1 angle", s1[:angle], Numeric, DBG, false) unless valid2

  angle = 0
  angle = s2[:angle] - s1[:angle] if s2[:angle] > s1[:angle]
  angle = s1[:angle] - s2[:angle] if s1[:angle] > s2[:angle]
  return false if angle < TOL
  return false unless (2 * Math::PI - angle).abs > TOL
  return false if angle > 3 * Math::PI / 4 && angle < 5 * Math::PI / 4

  n1_d_p2 = s1[:normal].dot(s2[:polar])
  p1_d_n2 = s1[:polar].dot(s2[:normal])
  return true if n1_d_p2 < 0 && p1_d_n2 < 0

  false
end

#dads(model = nil, pops = {}) ⇒ `Hash`

Adds a collection of bases surfaces (‘dads’) to a Topolys model, including vertices, wires, holes & faces. Also populates the model with sub surfaces (‘kids’).

Parameters:

model (Topolys::Model) (defaults to: nil) —

a model
pops (Hash) (defaults to: {}) —

base surfaces

Options Hash (pops):

:points (OpenStudio::Point3dVector) —

base surface 3D points
:windows (Hash) —

incorporated windows (see kids)
:doors (Hash) —

incorporated doors (see kids)
:skylights (Hash) —

incorporated skylights (see kids)
:n (OpenStudio::Vector3D) —

outward normal

Returns:

(Hash) —

3D Topolys wires of ‘holes’ (made by kids)

# File 'lib/tbd/geo.rb', line 168

def dads(model = nil, pops = {})
  mth   = "TBD::#{__callee__}"
  cl1   = Topolys::Model
  cl2   = Hash
  holes = {}
  return mismatch("model", model, cl2, mth, DBG, {}) unless model.is_a?(cl1)
  return mismatch("pops",   pops, cl2, mth, DBG, {}) unless pops.is_a?(cl2)

  pops.each do |id, props|
    hols   = []
    hinged = []
    obj    = objects(model, props[:points])
    next unless obj[:vx] && obj[:w]

    hols += kids(model, props[:windows  ]) if props.key?(:windows)
    hols += kids(model, props[:doors    ]) if props.key?(:doors)
    hols += kids(model, props[:skylights]) if props.key?(:skylights)

    hols.each { |hol| hinged << hol unless hol.attributes[:unhinged] }

    face = model.get_face(obj[:w], hinged)
    msg  = "Unable to retrieve valid 'dad' (#{mth})"
    log(DBG, msg) unless face
    next          unless face

    face.attributes[:id] = id
    face.attributes[:n ] = props[:n] if props.key?(:n)

    props[:face] = face

    hols.each { |hol| holes[hol.attributes[:id]] = hol }
  end

  holes
end

#derate(id = "", s = {}, lc = nil) ⇒ `OpenStudio::Model::Material`^?

Thermally derates insulating material within construction.

Parameters:

id (#to_s) (defaults to: "") —

surface identifier
s (Hash) (defaults to: {}) —

TBD surface parameters
lc (OpenStudio::Model::LayeredConstruction) (defaults to: nil) —

a layered construction

Options Hash (s):

:heatloss (#to_f) —

heat loss from major thermal bridging, in W/K
:net (#to_f) —

surface net area, in m2
:ltype (:massless, :standard) —

indexed layer type
:index (#to_i) —

deratable construction layer index
:r (#to_f) —

deratable layer Rsi-factor, in m2•K/W

Returns:

(OpenStudio::Model::Material) —

derated (cloned) material
(nil) —

if invalid input (see logs)

# File 'lib/tbd/psi.rb', line 1369

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

  kys.each do |k|
    tag = "#{id} #{k}"
    return hashkey(tag, s, k, mth, ERR) 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
      next if [:massless, :standard].include?(s[k])
      return invalid(tag, mth, 2, ERR)
    end
  end

  if lc.nameString.downcase.include?(" tbd")
    log(WRN, "Won't derate '#{id}': tagged as derated (#{mth})")
    return m
  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
  loss  = 0
  de_u  = 1 / r + u # derated U
  de_r  = 1 / de_u  # derated R

  if ltype == :massless
    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)
  else
    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
    end

    m.setThickness(d)
    m.setThermalConductivity(k)
  end

  if m && loss > TOL
    s[:r_heatloss] = loss
    hl = format "%.3f", s[:r_heatloss]
    log(WRN, "Won't assign #{hl} W/K to '#{id}': too conductive (#{mth})")
  end

  m
end

#exit(runner = nil, argh = {}) ⇒ `Bool`

Exits TBD Measures. Writes out TBD model content and results if requested. Always writes out minimal logs (see “tbd.out.json” file).

Parameters:

runner (Runner) (defaults to: nil) —

OpenStudio Measure runner
argh (Hash) (defaults to: {}) —

TBD arguments

Options Hash (argh):

:io (Hash) —

TBD input/output variables (see TBD JSON schema)
:surfaces (Hash) —

TBD surfaces (keys: Openstudio surface names)
:seed (#to_s) —

OpenStudio file, e.g. “school23.osm”
:version (#to_s) —

:version OpenStudio SDK, e.g. “3.6.1”
:gen_ua (Bool) —

whether to generate a UA’ report
:ua_ref (#to_s) —

selected UA’ ruleset
:setpoints (Bool) —

whether OpenStudio model holds setpoints
:write_tbd (Bool) —

whether to output a JSON file
:uprate_walls (Bool) —

whether to uprate walls
:uprate_roofs (Bool) —

whether to uprate roofs
:uprate_floors (Bool) —

whether to uprate floors
:wall_ut (#to_f) —

uprated wall Ut target in W/m2•K
:roof_ut (#to_f) —

uprated roof Ut target in W/m2•K
:floor_ut (#to_f) —

uprated floor Ut target in W/m2•K
:wall_option (#to_s) —

wall construction to uprate (or “all”)
:roof_option (#to_s) —

roof construction to uprate (or “all”)
:floor_option (#to_s) —

floor construction to uprate (or “all”)
:wall_uo (#to_f) —

required wall Uo to achieve Ut in W/m2•K
:roof_uo (#to_f) —

required roof Uo to achieve Ut in W/m2•K
:floor_uo (#to_f) —

required floor Uo to achieve Ut in W/m2•K

Returns:

(Bool) —

whether TBD Measure is successful (see logs)

# File 'lib/tbd/psi.rb', line 3115

def exit(runner = nil, argh = {})
  # Generated files target a design context ( >= WARN ) ... change TBD log
  # level for debugging purposes. By default, log status is set < DBG
  # while log level is set @INF.
  groups = { wall: {}, roof: {}, floor: {} }
  state  = msg(status)
  state  = msg(INF)         if status.zero?
  argh            = {}  unless argh.is_a?(Hash)
  argh[:io      ] = nil unless argh.key?(:io)
  argh[:surfaces] = nil unless argh.key?(:surfaces)

  unless argh[:io] && argh[:surfaces]
    state = "Halting all TBD processes, yet running OpenStudio"
    state = "Halting all TBD processes, and halting OpenStudio" if fatal?
  end

  argh[:io           ] = {}    unless argh[:io]
  argh[:seed         ] = ""    unless argh.key?(:seed         )
  argh[:version      ] = ""    unless argh.key?(:version      )
  argh[:gen_ua       ] = false unless argh.key?(:gen_ua       )
  argh[:ua_ref       ] = ""    unless argh.key?(:ua_ref       )
  argh[:setpoints    ] = false unless argh.key?(:setpoints    )
  argh[:write_tbd    ] = false unless argh.key?(:write_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_option  ] = ""    unless argh.key?(:wall_option  )
  argh[:roof_option  ] = ""    unless argh.key?(:roof_option  )
  argh[:floor_option ] = ""    unless argh.key?(:floor_option )
  argh[:wall_uo      ] = nil   unless argh.key?(:wall_ut      )
  argh[:roof_uo      ] = nil   unless argh.key?(:roof_ut      )
  argh[:floor_uo     ] = nil   unless argh.key?(:floor_ut     )

  groups[:wall ][:up] = argh[:uprate_walls ]
  groups[:roof ][:up] = argh[:uprate_roofs ]
  groups[:floor][:up] = argh[:uprate_floors]
  groups[:wall ][:ut] = argh[:wall_ut      ]
  groups[:roof ][:ut] = argh[:roof_ut      ]
  groups[:floor][:ut] = argh[:floor_ut     ]
  groups[:wall ][:op] = argh[:wall_option  ]
  groups[:roof ][:op] = argh[:roof_option  ]
  groups[:floor][:op] = argh[:floor_option ]
  groups[:wall ][:uo] = argh[:wall_uo      ]
  groups[:roof ][:uo] = argh[:roof_uo      ]
  groups[:floor][:uo] = argh[:floor_uo     ]

  io               = argh[:io       ]
  out              = argh[:write_tbd]
  descr            = ""
  descr            = argh[:seed] unless argh[:seed].empty?
  io[:description] = descr       unless io.key?(:description)
  descr            = io[:description]

  schema_pth  = "https://github.com/rd2/tbd/blob/master/tbd.schema.json"
  io[:schema] = schema_pth unless io.key?(:schema)
  tbd_log     = { date: Time.now, status: state }
  u_t         = []

  groups.each do |label, g|
    next     if fatal?
    next unless g[:uo]
    next unless g[:uo].is_a?(Numeric)

    uo     = format("%.3f", g[:uo])
    ut     = format("%.3f", g[:ut])
    output = "An initial #{label.to_s} Uo of #{uo} W/m2•K is required to " \
             "achieve an overall Ut of #{ut} W/m2•K for #{g[:op]}"
    u_t << output
    runner.registerInfo(output)
  end

  tbd_log[:ut] = u_t unless u_t.empty?
  ua_md_en     = nil
  ua_md_fr     = nil
  ua           = nil
  ok           = argh[:surfaces] && argh[:gen_ua]
  ua           = ua_summary(tbd_log[:date], argh) if ok

  unless fatal? || ua.nil? || ua.empty?
    if ua.key?(:en)
      if ua[:en].key?(:b1) || ua[:en].key?(:b2)
        tbd_log[:ua] = {}
        runner.registerInfo("-")
        runner.registerInfo(ua[:model])
        ua_md_en = ua_md(ua, :en)
        ua_md_fr = ua_md(ua, :fr)
      end

      if ua[:en].key?(:b1) && ua[:en][:b1].key?(:summary)
        runner.registerInfo(" - #{ua[:en][:b1][:summary]}")

        ua[:en][:b1].each do |k, v|
          runner.registerInfo(" --- #{v}") unless k == :summary
        end

        tbd_log[:ua][:bloc1] = ua[:en][:b1]
      end

      if ua[:en].key?(:b2) && ua[:en][:b2].key?(:summary)
        runner.registerInfo(" - #{ua[:en][:b2][:summary]}")

        ua[:en][:b2].each do |k, v|
          runner.registerInfo(" --- #{v}") unless k == :summary
        end

        tbd_log[:ua][:bloc2] = ua[:en][:b2]
      end
    end

    runner.registerInfo(" -")
  end

  results = []

  if argh[:surfaces]
    argh[:surfaces].each do |id, surface|
      next     if fatal?
      next unless surface.key?(:ratio)

      ratio  = format("%4.1f", surface[:ratio])
      output = "RSi derated by #{ratio}% : #{id}"
      results << output
      runner.registerInfo(output)
    end
  end

  tbd_log[:results] = results unless results.empty?
  tbd_msgs = []

  logs.each do |l|
    tbd_msgs << { level: tag(l[:level]), message: l[:message] }

    runner.registerWarning(l[:message]) if l[:level] >  INF
    runner.registerInfo(l[:message])    if l[:level] <= INF
  end

  tbd_log[:messages] = tbd_msgs unless tbd_msgs.empty?
  io[:log]           = tbd_log

  # User's may not be requesting detailed output - delete non-essential items.
  io.delete(:psis      ) unless out
  io.delete(:khis      ) unless out
  io.delete(:building  ) unless out
  io.delete(:stories   ) unless out
  io.delete(:spacetypes) unless out
  io.delete(:spaces    ) unless out
  io.delete(:surfaces  ) unless out
  io.delete(:edges     ) unless out

  # Deterministic sorting
  io[:schema     ] = io.delete(:schema     ) if io.key?(:schema     )
  io[:description] = io.delete(:description) if io.key?(:description)
  io[:log        ] = io.delete(:log        ) if io.key?(:log        )
  io[:psis       ] = io.delete(:psis       ) if io.key?(:psis       )
  io[:khis       ] = io.delete(:khis       ) if io.key?(:khis       )
  io[:building   ] = io.delete(:building   ) if io.key?(:building   )
  io[:stories    ] = io.delete(:stories    ) if io.key?(:stories    )
  io[:spacetypes ] = io.delete(:spacetypes ) if io.key?(:spacetypes )
  io[:spaces     ] = io.delete(:spaces     ) if io.key?(:spaces     )
  io[:surfaces   ] = io.delete(:surfaces   ) if io.key?(:surfaces   )
  io[:edges      ] = io.delete(:edges      ) if io.key?(:edges      )

  out_dir = '.'
  file_paths = runner.workflow.absoluteFilePaths

  # 'Apply Measure Now' won't cp files from 1st path back to generated_files.
  match1 = /WorkingFiles/.match(file_paths[1].to_s.strip)
  match2 = /files/.match(file_paths[1].to_s.strip)
  match  = match1 || match2

  if file_paths.size >= 2 && File.exist?(file_paths[1].to_s.strip) && match
    out_dir = file_paths[1].to_s.strip
  elsif !file_paths.empty? && File.exist?(file_paths.first.to_s.strip)
    out_dir = file_paths.first.to_s.strip
  end

  out_path = File.join(out_dir, "tbd.out.json")

  File.open(out_path, 'w') do |file|
    file.puts JSON::pretty_generate(io)
    # Make sure data is written to the disk one way or the other.
    begin
      file.fsync
    rescue StandardError
      file.flush
    end
  end

  unless fatal? || ua.nil? || ua.empty?
    unless ua_md_en.nil? || ua_md_en.empty?
      ua_path = File.join(out_dir, "ua_en.md")

      File.open(ua_path, 'w') do |file|
        file.puts ua_md_en

        begin
          file.fsync
        rescue StandardError
          file.flush
        end
      end
    end

    unless ua_md_fr.nil? || ua_md_fr.empty?
      ua_path = File.join(out_dir, "ua_fr.md")

      File.open(ua_path, 'w') do |file|
        file.puts ua_md_fr

        begin
          file.fsync
        rescue StandardError
          file.flush
        end
      end
    end
  end

  if fatal?
    runner.registerError("#{state} - see 'tbd.out.json'")
    return false
  elsif error? || warn?
    runner.registerWarning("#{state} - see 'tbd.out.json'")
    return true
  else
    runner.registerInfo("#{state} - see 'tbd.out.json'")
    return true
  end
end

#faces(s = {}, e = {}) ⇒ `Bool`, `false`

Populates TBD edges with linked Topolys faces.

Parameters:

s (Hash) (defaults to: {}) —

TBD surfaces
e (Hash) (defaults to: {}) —

TBD edges

Options Hash (s):

:face (Topolys::Face) —

a Topolys face

Options Hash (e):

:length (Numeric) —

edge length
:v0 (Topolys::Vertex) —

edge origin vertex
:v1 (Topolys::Vertex) —

edge terminal vertex

Returns:

(Bool) —

whether successful in populating faces
(false) —

if invalid input (see logs)

# File 'lib/tbd/geo.rb', line 216

def faces(s = {}, e = {})
  mth = "TBD::#{__callee__}"
  return mismatch("surfaces", s, Hash, mth, DBG, false) unless s.is_a?(Hash)
  return mismatch("edges",    e, Hash, mth, DBG, false) unless e.is_a?(Hash)

  s.each do |id, props|
    unless props.key?(:face)
      log(DBG, "Missing Topolys face '#{id}' (#{mth})")
      next
    end

    props[:face].wires.each do |wire|
      wire.edges.each do |edge|
        unless e.key?(edge.id)
          e[edge.id] = { length: edge.length,
                             v0: edge.v0,
                             v1: edge.v1,
                       surfaces: {} }
        end

        unless e[edge.id][:surfaces].key?(id)
          e[edge.id][:surfaces][id] = { wire: wire.id }
        end
      end
    end
  end

  true
end

#inputs(s = {}, e = {}, argh = {}) ⇒ `Hash`

Processes TBD JSON inputs, after TBD has preprocessed OpenStudio model variables and retrieved corresponding Topolys model surface/edge properties. TBD user inputs allow customization of default assumptions and inferred values. If successful, “edges” (input) may inherit additional properties, e.g.: edge-specific PSI set (defined in TBD JSON file), edge-specific PSI type (e.g. “corner”, defined in TBD JSON file), project-wide PSI set (if absent from TBD JSON file).

Parameters:

s (Hash) (defaults to: {}) —

TBD surfaces (keys: Openstudio surface names)
e (Hash) (defaults to: {}) —

TBD edges (keys: Topolys edge identifiers)
argh (Hash) (defaults to: {}) —

TBD arguments

Options Hash (s):

:windows (Hash) —

TBD surface-specific windows e.g. s[]
:doors (Hash) —

TBD surface-specific doors
:skylights (Hash) —

TBD surface-specific skylights
:story (OpenStudio::Model::BuildingStory) —

OpenStudio story
:stype ("Wall", "RoofCeiling", "Floor") —

OpenStudio surface type
:space (OpenStudio::Model::Space) —

OpenStudio space

Options Hash (e):

:surfaces (Hash) —

linked TBD surfaces e.g. e[]
:length (#to_f) —

edge length in m
:v0 (Topolys::Point3D) —

origin vertex
:v1 (Topolys::Point3D) —

terminal vertex

Options Hash (argh):

:option (#to_s) —

selected PSI set
:io_path (#to_s) —

tbd.json input file path
:schema_path (#to_s) —

TBD JSON schema file path

Returns:

(Hash) —

io: (Hash), psi:/khi: enriched sets (see logs if empty)

# File 'lib/tbd/psi.rb', line 1124

def inputs(s = {}, e = {}, argh = {})
  mth = "TBD::#{__callee__}"
  opt = :option
  ipt = { io: {}, psi: PSI.new, khi: KHI.new }
  io  = {}
  return mismatch("s"   , s   , Hash, mth, DBG, ipt) unless s.is_a?(Hash)
  return mismatch("e"   , e   , Hash, mth, DBG, ipt) unless e.is_a?(Hash)
  return mismatch("argh", argh, Hash, mth, DBG, ipt) unless argh.is_a?(Hash)
  return hashkey("argh" , argh, opt , mth, DBG, ipt) unless argh.key?(opt)

  argh[:io_path    ] = nil unless argh.key?(:io_path)
  argh[:schema_path] = nil unless argh.key?(:schema_path)

  pth = argh[:io_path    ]
  sch = argh[:schema_path]

  if pth && (pth.is_a?(String) || pth.is_a?(Hash))
    if pth.is_a?(Hash)
      io = pth
    else
      return empty("JSON file", mth, FTL, ipt) unless File.size?(pth)

      io = File.read(pth)
      io = JSON.parse(io, symbolize_names: true)
      return mismatch("io", io, Hash, mth, FTL, ipt) unless io.is_a?(Hash)
    end

    # Schema validation is not yet supported in the OpenStudio Application.
    # It is nonetheless recommended that users rely on the json-schema gem,
    # or an online linter, prior to using TBD. The following checks focus on
    # content - ignoring bad JSON input otherwise caught via JSON validation.
    #
    # A side note: JSON validation relies on case-senitive string comparisons
    # (e.g. OpenStudio space or surface names, vs corresponding TBD JSON
    # identifiers). So "Space-1" doesn't match "SPACE-1" ... head's up!
    if sch
      require "json-schema"
      return invalid("JSON schema", mth, 3, FTL, ipt) unless File.exist?(sch)
      return empty("JSON schema"  , mth,    FTL, ipt)     if File.zero?(sch)

      schema = File.read(sch)
      schema = JSON.parse(schema, symbolize_names: true)
      valid  = JSON::Validator.validate!(schema, io)
      return invalid("JSON schema validation", mth, 3, FTL, ipt) unless valid
    end

    # Append JSON entries to library of linear & point thermal bridges.
    io[:psis].each { |psi| ipt[:psi].append(psi) } if io.key?(:psis)
    io[:khis].each { |khi| ipt[:khi].append(khi) } if io.key?(:khis)

    # JSON-defined or user-selected, building PSI set must be complete/valid.
    io[:building] = { psi: argh[opt] } unless io.key?(:building)
    bdg = io[:building]
    ok  = bdg.key?(:psi)
    return hashkey("Building PSI", bdg, :psi, mth, FTL, ipt)  unless ok

    ok = ipt[:psi].complete?(bdg[:psi])
    return invalid("Complete building PSI", mth, 3, FTL, ipt) unless ok

    # Validate remaining (optional) JSON entries.
    [:stories, :spacetypes, :spaces].each do |types|
      key = :story
      key = :stype if types == :spacetypes
      key = :space if types == :spaces

      if io.key?(types)
        io[types].each do |type|
          next unless type.key?(:psi)
          next unless type.key?(:id )

          s1 = "JSON/OSM '#{type[:id]}' (#{mth})"
          s2 = "JSON/PSI '#{type[:id]}' set (#{mth})"
          match = false

          s.values.each do |props| # TBD surface linked to type?
            break    if match
            next unless props.key?(key)

            match = type[:id] == props[key].nameString
          end

          log(ERR, s1) unless match
          log(ERR, s2) unless ipt[:psi].set.key?(type[:psi])
        end
      end
    end

    if io.key?(:surfaces)
      io[:surfaces].each do |surface|
        next unless surface.key?(:id)

        s1 = "JSON/OSM surface '#{surface[:id]}' (#{mth})"
        log(ERR, s1) unless s.key?(surface[:id])

        # surfaces can OPTIONALLY hold custom PSI sets and/or KHI data
        if surface.key?(:psi)
          s2 = "JSON/OSM surface/set '#{surface[:id]}' (#{mth})"
          log(ERR, s2) unless ipt[:psi].set.key?(surface[:psi])
        end

        if surface.key?(:khis)
          surface[:khis].each do |khi|
            next unless khi.key?(:id)

            s3 = "JSON/KHI surface '#{surface[:id]}' '#{khi[:id]}' (#{mth})"
            log(ERR, s3) unless ipt[:khi].point.key?(khi[:id])
          end
        end
      end
    end

    if io.key?(:subsurfaces)
      io[:subsurfaces].each do |sub|
        next unless sub.key?(:id)
        next unless sub.key?(:usi)

        match = false

        s.each do |id, surface|
          break if match

          [:windows, :doors, :skylights].each do |holes|
            if surface.key?(holes)
              surface[holes].keys.each do |id|
                break if match

                match = sub[:id] == id
              end
            end
          end
        end

        log(ERR, "JSON/OSM subsurface '#{sub[:id]}' (#{mth})") unless match
      end
    end

    if io.key?(:edges)
      io[:edges].each do |edge|
        next unless edge.key?(:type)
        next unless edge.key?(:surfaces)

        surfaces = edge[:surfaces]
        type     = edge[:type].to_sym
        safer    = ipt[:psi].safe(bdg[:psi], type) # fallback
        log(ERR, "Skipping invalid edge PSI '#{type}' (#{mth})") unless safer
        next unless safer

        valid = true

        surfaces.each do |surface|         #   TBD edge's surfaces on file
          e.values.each do |ee|            #           TBD edges in memory
            break unless valid             #  if previous anomaly detected
            next      if ee.key?(:io_type) #  validated from previous loop
            next  unless ee.key?(:surfaces)

            surfs      = ee[:surfaces]
            next  unless surfs.key?(surface)

            # An edge on file is valid if ALL of its listed surfaces together
            # connect at least 1 or more TBD/Topolys model edges in memory.
            # Each of the latter may connect e.g. 3 TBD/Topolys surfaces,
            # but the list of surfaces on file may be shorter, e.g. only 2.
            match = true
            surfaces.each { |id| match = false unless surfs.key?(id) }
            next unless match

            if edge.key?(:length) # optional
              next unless (ee[:length] - edge[:length]).abs < TOL
            end

            # Optionally, edge coordinates may narrow down potential matches.
            if edge.key?(:v0x) || edge.key?(:v0y) || edge.key?(:v0z) ||
               edge.key?(:v1x) || edge.key?(:v1y) || edge.key?(:v1z)

              unless edge.key?(:v0x) && edge.key?(:v0y) && edge.key?(:v0z) &&
                     edge.key?(:v1x) && edge.key?(:v1y) && edge.key?(:v1z)
                log(ERR, "Mismatch '#{surface}' edge vertices (#{mth})")
                valid = false
                next
              end

              e1 = {}
              e2 = {}
              e1[:v0] = Topolys::Point3D.new(edge[:v0x].to_f,
                                             edge[:v0y].to_f,
                                             edge[:v0z].to_f)
              e1[:v1] = Topolys::Point3D.new(edge[:v1x].to_f,
                                             edge[:v1y].to_f,
                                             edge[:v1z].to_f)
              e2[:v0] = ee[:v0].point
              e2[:v1] = ee[:v1].point
              next unless matches?(e1, e2)
            end

            if edge.key?(:psi) # optional
              set = edge[:psi]

              if ipt[:psi].set.key?(set)
                saferr       = ipt[:psi].safe(set, type)
                ee[:io_set ] = set                               if saferr
                ee[:io_type] = type                              if saferr
                log(ERR, "Invalid #{set}: #{type} (#{mth})") unless saferr
                valid = false                                unless saferr
              else
                log(ERR, "Missing edge PSI #{set} (#{mth})")
                valid = false
              end
            else
              ee[:io_type] = type # success: matching edge - setting edge type
            end
          end
        end
      end
    end
  else
    # No (optional) user-defined TBD JSON input file. In such cases, provided
    # argh[:option] must refer to a valid PSI set. If valid, all edges inherit
    # a default PSI set (without KHI entries).
    msg = "Incomplete building PSI set '#{argh[opt]}' (#{mth})"
    ok  = ipt[:psi].complete?(argh[opt])

    io[:building] = { psi: argh[opt] } if ok
    log(FTL, msg)                  unless ok
    return ipt                     unless ok
  end

  ipt[:io] = io

  ipt
end

#kids(model = nil, boys = {}) ⇒ `Array<Topolys::Wire>`

Adds a collection of TBD sub surfaces (‘kids’) to a Topolys model, including vertices, wires & holes. A sub surface is typically ‘hinged’, i.e. along the same 3D plane as its base surface (or ‘dad’). In rare cases such as domes of tubular daylighting devices (TDDs), a sub surface may be ‘unhinged’.

Parameters:

model (Topolys::Model) (defaults to: nil) —

a model
boys (Hash) (defaults to: {}) —

a collection of TBD subsurfaces

Options Hash (boys):

:points (Array<Topolys::Point3D>) —

sub surface 3D points
:unhinged (Bool) —

whether same 3D plane as base surface
:n (OpenStudio::Vector3d) —

outward normal

Returns:

(Array<Topolys::Wire>) —

holes cut out by kids (see logs if empty)

# File 'lib/tbd/geo.rb', line 131

def kids(model = nil, boys = {})
  mth   = "TBD::#{__callee__}"
  cl1   = Topolys::Model
  cl2   = Hash
  holes = []
  return mismatch("model", model, cl1, mth, DBG, {}) unless model.is_a?(cl1)
  return mismatch("boys",   boys, cl2, mth, DBG, {}) unless boys.is_a?(cl2)

  boys.each do |id, props|
    obj = objects(model, props[:points])
    next unless obj[:w]

    obj[:w].attributes[:id      ] = id
    obj[:w].attributes[:unhinged] = props[:unhinged] if props.key?(:unhinged)
    obj[:w].attributes[:n       ] = props[:n       ] if props.key?(:n)

    props[:hole] = obj[:w]
    holes << obj[:w]
  end

  holes
end

#kiva(model = nil, walls = {}, floors = {}, edges = {}) ⇒ `Bool`, `false`

Generates Kiva settings and objects if model surfaces have ‘foundation’ boundary conditions.

Parameters:

model (OpenStudio::Model::Model) (defaults to: nil) —

a model
floors (Hash) (defaults to: {}) —

TBD floors
walls (Hash) (defaults to: {}) —

TBD walls
edges (Hash) (defaults to: {}) —

TBD edges (many linking floors & walls

Returns:

(Bool) —

true if Kiva foundations are successfully generated
(false) —

if invalid input (see logs)

# File 'lib/tbd/geo.rb', line 765

def kiva(model = nil, walls = {}, floors = {}, edges = {})
  mth = "TBD::#{__callee__}"
  cl1 = OpenStudio::Model::Model
  cl2 = Hash
  a   = false
  return mismatch("model" ,  model, cl1, mth, DBG, a) unless model.is_a?(cl1)
  return mismatch("walls" ,  walls, cl2, mth, DBG, a) unless walls.is_a?(cl2)
  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)

  # Check for existing KIVA objects.
  kva = false
  kva = true unless model.getSurfacePropertyExposedFoundationPerimeters.empty?
  kva = true unless model.getFoundationKivas.empty?

  if kva
    log(ERR, "Exiting - KIVA objects in model (#{mth})")
    return a
  else
    kva = true
  end

  # 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 #{id} (#{mth})")
      kva = false
    else
      construction = construction.get.to_LayeredConstruction

      if construction.empty?
        log(ERR, "Invalid layered constructions for #{id} (#{mth})")
        kva = false
      else
        construction = construction.get

        unless standardOpaqueLayers?(construction)
          log(ERR, "Non-standard materials for #{id} (#{mth})")
          kva = false
        end
      end
    end
  end

  return a unless kva

  # Strictly relying on Kiva's total exposed perimeter approach.
  arg  = "TotalExposedPerimeter"
  kiva = true
  # The following is loosely adapted from:
  #
  #   github.com/NREL/OpenStudio-resources/blob/develop/model/
  #   simulationtests/foundation_kiva.rb ... thanks.
  #
  # Access to KIVA settings. This is usually not required (the default KIVA
  # settings are fine), but its explicit inclusion in the model does offer
  # users easy access to further tweak settings, e.g. soil properties if
  # required. Initial tests show slight differences in simulation results
  # w/w/o explcit inclusion of the KIVA settings template in the model.
  settings = model.getFoundationKivaSettings

  k = settings.soilConductivity
  settings.setSoilConductivity(k)

  # Tag foundation-facing floors, then walls.
  edges.each do |code1, edge|
    edge[:surfaces].keys.each do |id|
      next unless floors.key?(id)
      next unless floors[id][:boundary].downcase == "foundation"
      next     if floors[id].key?(:kiva)

      floors[id][:kiva   ] = :slab # initially slabs-on-grade
      floors[id][:exposed] = 0.0   # slab-on-grade or walkout perimeter

      # Loop around current edge.
      edge[:surfaces].keys.each do |i|
        next     if i == id
        next unless walls.key?(i)
        next unless walls[i][:boundary].downcase == "foundation"
        next     if walls[i].key?(:kiva)

        floors[id][:kiva] = :basement
        walls[i  ][:kiva] = id
      end

      # Loop around current edge.
      edge[:surfaces].keys.each do |i|
        next     if i == id
        next unless walls.key?(i)
        next unless walls[i][:boundary].downcase == "outdoors"

        floors[id][:exposed] += edge[:length]
      end

      # Loop around other floor edges.
      edges.each do |code2, e|
        next if code1 == code2 #  skip - same edge

        e[:surfaces].keys.each do |i|
          next unless i == id # good - same floor

          e[:surfaces].keys.each do |ii|
            next     if i == ii
            next unless walls.key?(ii)
            next unless walls[ii][:boundary].downcase == "foundation"
            next     if walls[ii].key?(:kiva)

            floors[id][:kiva] = :basement
            walls[ii ][:kiva] = id
          end

          e[:surfaces].keys.each do |ii|
            next    if i == ii
            next unless walls.key?(ii)
            next unless walls[ii][:boundary].downcase == "outdoors"

            floors[id][:exposed] += e[:length]
          end
        end
      end

      foundation = OpenStudio::Model::FoundationKiva.new(model)
      foundation.setName("KIVA Foundation Floor #{id}")
      floor = model.getSurfaceByName(id)
      kiva  = false if floor.empty?
      next          if floor.empty?

      floor          = floor.get
      construction   = floor.construction
      kiva = false  if construction.empty?
      next          if construction.empty?

      construction   = construction.get
      floor.setAdjacentFoundation(foundation)
      floor.setConstruction(construction)
      ep   = floors[id][:exposed]
      per  = floor.createSurfacePropertyExposedFoundationPerimeter(arg, ep)
      kiva = false  if per.empty?
      next          if per.empty?

      per            = per.get
      perimeter      = per.totalExposedPerimeter
      kiva = false  if perimeter.empty?
      next          if perimeter.empty?

      perimeter      = perimeter.get

      if ep < 0.001
        ok   = per.setTotalExposedPerimeter(0.000)
        ok   = per.setTotalExposedPerimeter(0.001) unless ok
        kiva = false                               unless ok
      elsif (perimeter - ep).abs < TOL
        xps25 = model.getStandardOpaqueMaterialByName("XPS 25mm")

        if xps25.empty?
          xps25 = OpenStudio::Model::StandardOpaqueMaterial.new(model)
          xps25.setName("XPS 25mm")
          xps25.setRoughness("Rough")
          xps25.setThickness(0.0254)
          xps25.setConductivity(0.029)
          xps25.setDensity(28)
          xps25.setSpecificHeat(1450)
          xps25.setThermalAbsorptance(0.9)
          xps25.setSolarAbsorptance(0.7)
        else
          xps25 = xps25.get
        end

        foundation.setInteriorHorizontalInsulationMaterial(xps25)
        foundation.setInteriorHorizontalInsulationWidth(0.6)
      end

      floors[id][:foundation] = foundation
    end
  end

  walls.each do |i, wall|
    next unless wall.key?(:kiva)

    id = walls[i][:kiva]
    next unless floors.key?(id)
    next unless floors[id].key?(:foundation)

    mur = model.getSurfaceByName(i) # locate OpenStudio wall
    kiva = false if mur.empty?
    next         if mur.empty?

    mur           = mur.get
    construction  = mur.construction
    kiva = false if construction.empty?
    next         if construction.empty?

    construction  = construction.get
    mur.setAdjacentFoundation(floors[id][:foundation])
    mur.setConstruction(construction)
  end

  kiva
end

#matches?(e1 = {}, e2 = {}, tol = TOL) ⇒ `Bool`, `false`

Checks whether 2 edges share Topolys vertex pairs.

Parameters:

e1 (Hash) (defaults to: {}) —

first edge
e2 (Hash) (defaults to: {}) —

second edge
tol (Numeric) (defaults to: TOL) —

tolerance (OSut::TOL) in m

Options Hash (e1):

:v0 (Topolys::Point3D) —

origin vertex
:v1 (Topolys::Point3D) —

terminal vertex

Returns:

(Bool) —

whether edges share vertex pairs
(false) —

if invalid input (see logs)

# File 'lib/tbd/geo.rb', line 35

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 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)
  return mismatch("e2:v1", e2[:v1], cl, mth, DBG, a) unless e2[:v1].is_a?(cl)

  e1_vector = e1[:v1] - e1[:v0]
  e2_vector = e2[:v1] - e2[:v0]

  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[: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[:v1].x).abs < tol &&
        (e1[:v1].y - e2[:v1].y).abs < tol &&
        (e1[:v1].z - e2[:v1].z).abs < tol
      )
    )
  )

  false
end

#objects(model = nil, pts = []) ⇒ `Hash`

Returns Topolys vertices and a Topolys wire from Topolys points. If missing, it populates the Topolys model with the vertices and wire.

Parameters:

model (Topolys::Model) (defaults to: nil) —

a model
pts (Array<Topolys::Point3D>) (defaults to: []) —

3D points

Returns:

(Hash) —

vx: (Array<Topolys::Vertex>); w: (Topolys::Wire)
(Hash) —

vx: nil, w: nil if invalid input (see logs)

# File 'lib/tbd/geo.rb', line 98

def objects(model = nil, pts = [])
  mth = "TBD::#{__callee__}"
  cl1 = Topolys::Model
  cl2 = Array
  cl3 = Topolys::Point3D
  obj = { vx: nil, w: nil }
  return mismatch("model", model, cl1, mth, DBG, obj) unless model.is_a?(cl1)
  return mismatch("points",  pts, cl2, mth, DBG, obj) unless pts.is_a?(cl2)

  pts.each do |pt|
    return mismatch("point", pt, cl3, mth, DBG, obj) unless pt.is_a?(cl3)
  end

  obj[:vx] = model.get_vertices(pts)
  obj[:w ] = model.get_wire(obj[:vx])

  obj
end

#process(model = nil, argh = {}) ⇒ `Hash`

Processes TBD objects, based on an OpenStudio and generated Topolys model, and derates admissible envelope surfaces by substituting insulating materials with derated clones, within surface multilayered constructions. Returns a Hash holding 2 key:value pairs; io: objects for JSON serialization, and surfaces: derated TBD surfaces (see exit method).

Parameters:

model (OpenStudio::Model::Model) (defaults to: nil) —

a model
argh (Hash) (defaults to: {}) —

TBD arguments

Options Hash (argh):

:option (#to_s) —

selected PSI set
:io_path (#to_s) —

tbd.json input file path
:schema_path (#to_s) —

TBD JSON schema file path
:parapet (Bool) — default: true —

wall-roof edge as parapet
:uprate_walls (Bool) —

whether to uprate walls
:uprate_roofs (Bool) —

whether to uprate roofs
:uprate_floors (Bool) —

whether to uprate floors
:wall_ut (Bool) —

uprated wall Ut target in W/m2•K
:roof_ut (Bool) —

uprated roof Ut target in W/m2•K
:floor_ut (Bool) —

uprated floor Ut target in W/m2•K
:wall_option (#to_s) —

wall construction to uprate (or “all”)
:roof_option (#to_s) —

roof construction to uprate (or “all”)
:floor_option (#to_s) —

floor construction to uprate (or “all”)
:gen_ua (Bool) —

whether to generate a UA’ report
:ua_ref (#to_s) —

selected UA’ ruleset
:gen_kiva (Bool) —

whether to generate KIVA inputs
:sub_tol (#to_f) —

proximity tolerance between edges in m

Returns:

(Hash) —

io: (Hash), surfaces: (Hash)
(Hash) —

io: nil, surfaces: nil if invalid input (see logs)

# File 'lib/tbd/psi.rb', line 1495

def process(model = nil, argh = {})
  mth = "TBD::#{__callee__}"
  cl  = OpenStudio::Model::Model
  tbd = { io: nil, surfaces: {} }
  return mismatch("model", model, cl, mth, DBG, tbd) unless model.is_a?(cl)
  return mismatch("argh", argh, Hash, mth, DBG, tbd) unless argh.is_a?(Hash)

  argh                 = {}           if argh.empty?
  argh[:option       ] = ""       unless argh.key?(:option)
  argh[:io_path      ] = nil      unless argh.key?(:io_path)
  argh[:schema_path  ] = nil      unless argh.key?(:schema_path)
  argh[:parapet      ] = true     unless argh.key?(:parapet)
  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      ] = 0        unless argh.key?(:wall_ut)
  argh[:roof_ut      ] = 0        unless argh.key?(:roof_ut)
  argh[:floor_ut     ] = 0        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)
  argh[:gen_ua       ] = false    unless argh.key?(:gen_ua)
  argh[:ua_ref       ] = ""       unless argh.key?(:ua_ref)
  argh[:gen_kiva     ] = false    unless argh.key?(:gen_kiva)
  argh[:reset_kiva   ] = false    unless argh.key?(:reset_kiva)
  argh[:sub_tol      ] = TBD::TOL unless argh.key?(:sub_tol)

  # Ensure true or false: whether to generate KIVA inputs.
  unless [true, false].include?(argh[:gen_kiva])
    return invalid("generate KIVA option", mth, 0, DBG, tbd)
  end

  # Ensure true or false: whether to first purge (existing) KIVA inputs.
  unless [true, false].include?(argh[:reset_kiva])
    return invalid("reset KIVA option", mth, 0, DBG, tbd)
  end

  # Create the Topolys Model.
  t_model = Topolys::Model.new

  # "true" if any space/zone holds valid setpoint temperatures. With invalid
  # inputs, these 2x methods return "false", ignoring any
  # setpoint-based logic, e.g. semi-heated spaces (DEBUG errors are logged).
  heated = heatingTemperatureSetpoints?(model)
  cooled = coolingTemperatureSetpoints?(model)
  argh[:setpoints] = heated || cooled

  model.getSurfaces.sort_by { |s| s.nameString }.each do |s|
    # Fetch key attributes of opaque surfaces (and any linked sub surfaces).
    # Method returns nil with invalid input (see logs); TBD ignores them.
    surface = properties(s, argh)
    tbd[:surfaces][s.nameString] = surface unless surface.nil?
  end

  return empty("TBD surfaces", mth, ERR, tbd) if tbd[:surfaces].empty?

  # TBD only derates constructions of opaque surfaces in CONDITIONED spaces,
  # ... if facing outdoors or facing UNENCLOSED/UNCONDITIONED spaces.
  tbd[:surfaces].each do |id, surface|
    surface[:deratable] = false
    next unless surface[:conditioned]
    next     if surface[:ground     ]

    unless surface[:boundary].downcase == "outdoors"
      next unless tbd[:surfaces].key?(surface[:boundary])
      next     if tbd[:surfaces][surface[:boundary]][:conditioned]
    end

    if surface.key?(:index)
      surface[:deratable] = true
    else
      log(ERR, "Skipping '#{id}': insulating layer? (#{mth})")
    end
  end

  # Sort subsurfaces before processing.
  [:windows, :doors, :skylights].each do |holes|
    tbd[:surfaces].values.each do |surface|
      next unless surface.key?(holes)

      surface[holes] = surface[holes].sort_by { |_, s| s[:minz] }.to_h
    end
  end

  # Split "surfaces" hash into "floors", "ceilings" and "walls" hashes.
  floors   = tbd[:surfaces].select { |_, s| s[:type] == :floor   }
  ceilings = tbd[:surfaces].select { |_, s| s[:type] == :ceiling }
  walls    = tbd[:surfaces].select { |_, s| s[:type] == :wall    }

  floors   = floors.sort_by   { |_, s| [s[:minz], s[:space]] }.to_h
  ceilings = ceilings.sort_by { |_, s| [s[:minz], s[:space]] }.to_h
  walls    = walls.sort_by    { |_, s| [s[:minz], s[:space]] }.to_h

  # Fetch OpenStudio shading surfaces & key attributes.
  shades = {}

  model.getShadingSurfaces.each do |s|
    id    = s.nameString
    group = s.shadingSurfaceGroup
    log(ERR, "Can't process '#{id}' transformation (#{mth})") if group.empty?
    next                                                      if group.empty?

    group   = group.get
    tr      = transforms(group)
    t       = tr[:t] if tr[:t] && tr[:r]

    log(ERR, "Can't process '#{id}' transformation (#{mth})") unless t
    next                                                      unless t

    space   = group.space
    tr[:r] += space.get.directionofRelativeNorth unless space.empty?
    n       = truNormal(s, tr[:r])
    log(ERR, "Can't process '#{id}' true normal (#{mth})") unless n
    next                                                   unless n

    points = (t * s.vertices).map { |v| Topolys::Point3D.new(v.x, v.y, v.z) }

    minz = ( points.map { |p| p.z } ).min

    shades[id] = { group: group, points: points, minz: minz, n: n }
  end

  # Mutually populate TBD & Topolys surfaces. Keep track of created "holes".
  holes         = {}
  floor_holes   = dads(t_model, floors)
  ceiling_holes = dads(t_model, ceilings)
  wall_holes    = dads(t_model, walls)

  holes.merge!(floor_holes)
  holes.merge!(ceiling_holes)
  holes.merge!(wall_holes)
  dads(t_model, shades)

  # Loop through Topolys edges and populate TBD edge hash. Initially, there
  # should be a one-to-one correspondence between Topolys and TBD edge
  # objects. Use Topolys-generated identifiers as unique edge hash keys.
  edges = {}

  # Start with hole edges.
  holes.each do |id, wire|
    wire.edges.each do |e|
      i  = e.id
      l  = e.length
      ex = edges.key?(i)

      edges[i] = { length: l, v0: e.v0, v1: e.v1, surfaces: {} } unless ex

      next if edges[i][:surfaces].key?(wire.attributes[:id])

      edges[i][:surfaces][wire.attributes[:id]] = { wire: wire.id }
    end
  end

  # Next, floors, ceilings & walls; then shades.
  faces(floors  , edges)
  faces(ceilings, edges)
  faces(walls   , edges)
  faces(shades  , edges)

  # Purge existing KIVA objects from model.
  if argh[:reset_kiva]
    kva = false
    kva = true unless model.getSurfacePropertyExposedFoundationPerimeters.empty?
    kva = true unless model.getFoundationKivas.empty?

    if kva
      if argh[:gen_kiva]
        resetKIVA(model, "Foundation")
      else
        resetKIVA(model, "Ground")
      end
    end
  end

  # Generate OSM Kiva settings and objects if foundation-facing floors.
  # Returns false if partial failure (log failure eventually).
  kiva(model, walls, floors, edges) if argh[:gen_kiva]

  # Thermal bridging characteristics of edges are determined - in part - by
  # relative polar position of linked surfaces (or wires) around each edge.
  # This attribute is key in distinguishing concave from convex edges.
  #
  # For each linked surface (or rather surface wires), set polar position
  # around edge with respect to a reference vector (perpendicular to the
  # edge), +clockwise as one is looking in the opposite position of the edge
  # vector. For instance, a vertical edge has a reference vector pointing
  # North - surfaces eastward of the edge are (0°,180°], while surfaces
  # westward of the edge are (180°,360°].
  #
  # Much of the following code is of a topological nature, and should ideally
  # (or eventually) become available functionality offered by Topolys. Topolys
  # "wrappers" like TBD are good, short-term test beds to identify desired
  # features for future Topolys enhancements.
  zenith = Topolys::Vector3D.new(0, 0, 1).freeze
  north  = Topolys::Vector3D.new(0, 1, 0).freeze
  east   = Topolys::Vector3D.new(1, 0, 0).freeze

  edges.values.each do |edge|
    origin     = edge[:v0].point
    terminal   = edge[:v1].point
    dx         = (origin.x - terminal.x).abs
    dy         = (origin.y - terminal.y).abs
    dz         = (origin.z - terminal.z).abs
    horizontal = dz < TOL
    vertical   = dx < TOL && dy < TOL
    edge_V     = terminal - origin
    next if edge_V.magnitude < TOL

    edge_plane = Topolys::Plane3D.new(origin, edge_V)

    if vertical
      reference_V = north.dup
    elsif horizontal
      reference_V = zenith.dup
    else # project zenith vector unto edge plane
      reference = edge_plane.project(origin + zenith)
      reference_V = reference - origin
    end

    edge[:surfaces].each do |id, surface|
      # Loop through each linked wire and determine farthest point from
      # edge while ensuring candidate point is not aligned with edge.
      t_model.wires.each do |wire|
        next unless surface[:wire] == wire.id # should be a unique match

        normal       = tbd[:surfaces][id][:n]   if tbd[:surfaces].key?(id)
        normal       = holes[id].attributes[:n] if holes.key?(id)
        normal       = shades[id][:n]           if shades.key?(id)
        farthest     = Topolys::Point3D.new(origin.x, origin.y, origin.z)
        farthest_V   = farthest - origin # zero magnitude, initially
        farthest_mag = 0

        wire.points.each do |point|
          next if point == origin
          next if point == terminal

          point_on_plane = edge_plane.project(point)
          origin_point_V = point_on_plane - origin
          point_V_mag    = origin_point_V.magnitude
          next unless point_V_mag > TOL
          next unless point_V_mag > farthest_mag

          farthest    = point
          farthest_V  = origin_point_V
          fathest_mag = point_V_mag
        end

        angle  = reference_V.angle(farthest_V)
        angle  = 0 if angle.nil?
        adjust = false # adjust angle [180°, 360°] if necessary

        if vertical
          adjust = true if east.dot(farthest_V) < -TOL
        else
          dN  = north.dot(farthest_V)
          dN1 = north.dot(farthest_V).abs - 1

          if dN.abs < TOL || dN1.abs < TOL
            adjust = true if east.dot(farthest_V) < -TOL
          else
            adjust = true if dN < -TOL
          end
        end

        angle  = 2 * Math::PI - angle if adjust
        angle -= 2 * Math::PI         if (angle - 2 * Math::PI).abs < TOL
        surface[:angle ] = angle
        farthest_V.normalize!
        surface[:polar ] = farthest_V
        surface[:normal] = normal
      end # end of edge-linked, surface-to-wire loop
    end # end of edge-linked surface loop

    edge[:horizontal] = horizontal
    edge[:vertical  ] = vertical
    edge[:surfaces  ] = edge[:surfaces].sort_by{ |_, p| p[:angle] }.to_h
  end # end of edge loop

  # Topolys edges may constitute thermal bridges (and therefore thermally
  # derate linked OpenStudio opaque surfaces), depending on a number of
  # factors such as surface type, space conditioning and boundary conditions.
  # Thermal bridging attributes (type & PSI-value pairs) are grouped into PSI
  # sets, normally accessed through the :option user argument (in the
  # OpenStudio Measure interface).
  #
  # Process user-defined TBD JSON file inputs if file exists & valid:
  #   :io holds valid TBD JSON file entries
  #   :psi holds TBD PSI sets (built-in defaults + those on file)
  #   :khi holds TBD KHI points (built-in defaults + those on file)
  #
  # Without an input JSON file, a valid 'json' Hash simply holds:
  #   :io[:building][:psi] ... a single valid, default PSI set for all edges
  #   :psi                 ... built-in TBD PSI sets
  #   :khi                 ... built-in TBD KHI points
  json = inputs(tbd[:surfaces], edges, argh)

  # A user-defined TBD JSON input file can hold a number of anomalies that
  # won't affect results, such as custom PSI sets that aren't referenced
  # elsewhere (similar to OpenStudio materials on file that aren't referenced
  # by any OpenStudio construction). This may trigger 'warnings' in the log
  # file, but they're in principle benign.
  #
  # A user-defined JSON input file can instead hold a number of more serious
  # anomalies that risk generating erroneous or unintended results. They're
  # logged as well, yet it remains up to the user to decide how serious a risk
  # this may be. If a custom edge is defined on file (e.g., "expansion joint"
  # thermal bridge instead of a "transition") yet TBD is unable to match
  # it against OpenStudio and/or Topolys edges (or surfaces), then TBD
  # will log this as an error while simply 'skipping' the anomaly (TBD will
  # otherwise ignore the requested change and pursue its processes).
  #
  # There are 2 types of errors that are considered FATAL when processing
  # user-defined TBD JSON input files:
  #   - incorrect JSON formatting of the input file (can't parse)
  #   - TBD is unable to identify a 'complete' building-level PSI set
  #     (either a bad argument from the Measure, or bad input on file).
  #
  # ... in such circumstances, TBD will halt all processes and exit while
  # signaling to OpenStudio to halt its own processes (e.g., not launch an
  # EnergyPlus simulation). This is similar to accessing an invalid .osm file.
  return tbd if fatal?

  psi    = json[:io][:building][:psi] # default building PSI on file
  shorts = json[:psi].shorthands(psi)

  if shorts[:has].empty? || shorts[:val].empty?
    log(FTL, "Invalid or incomplete building PSI set (#{mth})")
    return tbd
  end

  edges.values.each do |edge|
    next unless edge.key?(:surfaces)

    deratables = []
    set        = {}

    edge[:surfaces].keys.each do |id|
      next unless tbd[:surfaces].key?(id)

      deratables << id if tbd[:surfaces][id][:deratable]
    end

    next if deratables.empty?

    if edge.key?(:io_type)
      bdg = json[:psi].safe(psi, edge[:io_type]) # building safe type fallback
      edge[:sets] = {} unless edge.key?(:sets)
      edge[:sets][edge[:io_type]] = shorts[:val][bdg] # building safe fallback
      set[edge[:io_type]] = shorts[:val][bdg]
      edge[:psi] = set

      if edge.key?(:io_set) && json[:psi].set.key?(edge[:io_set])
        type = json[:psi].safe(edge[:io_set], edge[:io_type])
        edge[:set] = edge[:io_set] if type
      end

      match = true
    end

    edge[:surfaces].keys.each do |id|
      break    if match
      next unless tbd[:surfaces].key?(id)
      next unless deratables.include?(id)

      # Evaluate current set content before processing a new linked surface.
      is                    = {}
      is[:doorhead        ] = set.keys.to_s.include?("doorhead")
      is[:doorsill        ] = set.keys.to_s.include?("doorsill")
      is[:doorjamb        ] = set.keys.to_s.include?("doorjamb")
      is[:skylighthead    ] = set.keys.to_s.include?("skylighthead")
      is[:skylightsill    ] = set.keys.to_s.include?("skylightsill")
      is[:skylightjamb    ] = set.keys.to_s.include?("skylightjamb")
      is[:spandrel        ] = set.keys.to_s.include?("spandrel")
      is[:corner          ] = set.keys.to_s.include?("corner")
      is[:parapet         ] = set.keys.to_s.include?("parapet")
      is[:roof            ] = set.keys.to_s.include?("roof")
      is[:ceiling         ] = set.keys.to_s.include?("ceiling")
      is[:party           ] = set.keys.to_s.include?("party")
      is[:grade           ] = set.keys.to_s.include?("grade")
      is[:balcony         ] = set.keys.to_s.include?("balcony")
      is[:balconysill     ] = set.keys.to_s.include?("balconysill")
      is[:balconydoorsill ] = set.keys.to_s.include?("balconydoorsill")
      is[:rimjoist        ] = set.keys.to_s.include?("rimjoist")

      if is.empty?
        is[:head] = set.keys.to_s.include?("head")
        is[:sill] = set.keys.to_s.include?("sill")
        is[:jamb] = set.keys.to_s.include?("jamb")
      end

      # Label edge as ...
      #         :head,         :sill,         :jamb (vertical fenestration)
      #     :doorhead,     :doorsill,     :doorjamb (opaque door)
      # :skylighthead, :skylightsill, :skylightjamb (all other cases)
      #
      # ... if linked to:
      #   1x subsurface (vertical or non-vertical)
      edge[:surfaces].keys.each do |i|
        break    if is[:head        ]
        break    if is[:sill        ]
        break    if is[:jamb        ]
        break    if is[:doorhead    ]
        break    if is[:doorsill    ]
        break    if is[:doorjamb    ]
        break    if is[:skylighthead]
        break    if is[:skylightsill]
        break    if is[:skylightjamb]
        next     if deratables.include?(i)
        next unless holes.key?(i)

        # In most cases, subsurface edges simply delineate the rough opening
        # of its base surface (here, a "gardian"). Door sills, corner windows,
        # as well as a subsurface header aligned with a plenum "floor"
        # (ceiling tiles), are common instances where a subsurface edge links
        # 2x (opaque) surfaces. Deratable surface "id" may not be the gardian
        # of subsurface "i" - the latter may be a neighbour. The single
        # surface to derate is not the gardian in such cases.
        gardian = deratables.size == 1 ? id : ""
        target  = gardian

        # Retrieve base surface's subsurfaces.
        windows   = tbd[:surfaces][id].key?(:windows)
        doors     = tbd[:surfaces][id].key?(:doors)
        skylights = tbd[:surfaces][id].key?(:skylights)

        windows   =   windows ? tbd[:surfaces][id][:windows  ] : {}
        doors     =     doors ? tbd[:surfaces][id][:doors    ] : {}
        skylights = skylights ? tbd[:surfaces][id][:skylights] : {}

        # The gardian is "id" if subsurface "ids" holds "i".
        ids = windows.keys + doors.keys + skylights.keys

        if gardian.empty?
          other = deratables.first == id ? deratables.last : deratables.first

          gardian = ids.include?(i) ? id : other
          target  = ids.include?(i) ? other : id

          windows   = tbd[:surfaces][gardian].key?(:windows)
          doors     = tbd[:surfaces][gardian].key?(:doors)
          skylights = tbd[:surfaces][gardian].key?(:skylights)

          windows   =   windows ? tbd[:surfaces][gardian][:windows  ] : {}
          doors     =     doors ? tbd[:surfaces][gardian][:doors    ] : {}
          skylights = skylights ? tbd[:surfaces][gardian][:skylights] : {}

          ids = windows.keys + doors.keys + skylights.keys
        end

        unless ids.include?(i)
          log(ERR, "Orphaned subsurface #{i} (mth)")
          next
        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?
        sub = skylight unless skylight.empty?

        window = sub[:type] == :window
        door   = sub[:type] == :door
        glazed = door && sub.key?(:glazed) && sub[:glazed]

        s1      = edge[:surfaces][target]
        s2      = edge[:surfaces][i      ]
        concave = concave?(s1, s2)
        convex  = convex?(s1, s2)
        flat    = !concave && !convex

        # Subsurface edges are tagged as head, sill or jamb, regardless of
        # building PSI set subsurface-related tags. If the latter is simply
        # :fenestration, then its single PSI factor is systematically
        # assigned to e.g. a window's :head, :sill & :jamb edges.
        #
        # Additionally, concave or convex variants also inherit from the base
        # type if undefined in the PSI set.
        #
        # If a subsurface is not horizontal, TBD tags any horizontal edge as
        # either :head or :sill based on the polar angle of the subsurface
        # around the edge vs sky zenith. Otherwise, all other subsurface edges
        # are tagged as :jamb.
        if ((s2[:normal].dot(zenith)).abs - 1).abs < TOL # horizontal surface
          if glazed || window
            set[:jamb       ] = shorts[:val][:jamb       ] if flat
            set[:jambconcave] = shorts[:val][:jambconcave] if concave
            set[:jambconvex ] = shorts[:val][:jambconvex ] if convex
             is[:jamb       ] = true
          elsif door
            set[:doorjamb       ] = shorts[:val][:doorjamb       ] if flat
            set[:doorjambconcave] = shorts[:val][:doorjambconcave] if concave
            set[:doorjambconvex ] = shorts[:val][:doorjambconvex ] if convex
             is[:doorjamb       ] = true
          else
            set[:skylightjamb       ] = shorts[:val][:skylightjamb       ] if flat
            set[:skylightjambconcave] = shorts[:val][:skylightjambconcave] if concave
            set[:skylightjambconvex ] = shorts[:val][:skylightjambconvex ] if convex
             is[:skylightjamb       ] = true
          end
        else
          if glazed || window
            if edge[:horizontal]
              if s2[:polar].dot(zenith) < 0
                set[:head       ] = shorts[:val][:head       ] if flat
                set[:headconcave] = shorts[:val][:headconcave] if concave
                set[:headconvex ] = shorts[:val][:headconvex ] if convex
                 is[:head       ] = true
              else
                set[:sill       ] = shorts[:val][:sill       ] if flat
                set[:sillconcave] = shorts[:val][:sillconcave] if concave
                set[:sillconvex ] = shorts[:val][:sillconvex ] if convex
                 is[:sill       ] = true
              end
            else
              set[:jamb       ] = shorts[:val][:jamb       ] if flat
              set[:jambconcave] = shorts[:val][:jambconcave] if concave
              set[:jambconvex ] = shorts[:val][:jambconvex ] if convex
               is[:jamb       ] = true
            end
          elsif door
            if edge[:horizontal]
              if s2[:polar].dot(zenith) < 0

                set[:doorhead       ] = shorts[:val][:doorhead       ] if flat
                set[:doorheadconcave] = shorts[:val][:doorheadconcave] if concave
                set[:doorheadconvex ] = shorts[:val][:doorheadconvex ] if convex
                 is[:doorhead       ] = true
              else
                set[:doorsill       ] = shorts[:val][:doorsill       ] if flat
                set[:doorsillconcave] = shorts[:val][:doorsillconcave] if concave
                set[:doorsillconvex ] = shorts[:val][:doorsillconvex ] if convex
                 is[:doorsill       ] = true
              end
            else
              set[:doorjamb       ] = shorts[:val][:doorjamb       ] if flat
              set[:doorjambconcave] = shorts[:val][:doorjambconcave] if concave
              set[:doorjambconvex ] = shorts[:val][:doorjambconvex ] if convex
               is[:doorjamb       ] = true
            end
          else
            if edge[:horizontal]
              if s2[:polar].dot(zenith) < 0
                set[:skylighthead       ] = shorts[:val][:skylighthead       ] if flat
                set[:skylightheadconcave] = shorts[:val][:skylightheadconcave] if concave
                set[:skylightheadconvex ] = shorts[:val][:skylightheadconvex ] if convex
                 is[:skylighthead       ] = true
              else
                set[:skylightsill       ] = shorts[:val][:skylightsill       ] if flat
                set[:skylightsillconcave] = shorts[:val][:skylightsillconcave] if concave
                set[:skylightsillconvex ] = shorts[:val][:skylightsillconvex ] if convex
                 is[:skylightsill       ] = true
              end
            else
              set[:skylightjamb       ] = shorts[:val][:skylightjamb       ] if flat
              set[:skylightjambconcave] = shorts[:val][:skylightjambconcave] if concave
              set[:skylightjambconvex ] = shorts[:val][:skylightjambconvex ] if convex
               is[:skylightjamb       ] = true
            end
          end
        end
      end

      # Label edge as :spandrel if linked to:
      #   1x deratable, non-spandrel wall
      #   1x deratable, spandrel wall
      edge[:surfaces].keys.each do |i|
        break     if is[:spandrel]
        break unless deratables.size == 2
        break unless walls.key?(id)
        break unless walls[id][:spandrel]
        next      if i == id
        next  unless deratables.include?(i)
        next  unless walls.key?(i)
        next      if walls[i][:spandrel]

        s1      = edge[:surfaces][id]
        s2      = edge[:surfaces][i ]
        concave = concave?(s1, s2)
        convex  = convex?(s1, s2)
        flat    = !concave && !convex

        set[:spandrel       ] = shorts[:val][:spandrel       ] if flat
        set[:spandrelconcave] = shorts[:val][:spandrelconcave] if concave
        set[:spandrelconvex ] = shorts[:val][:spandrelconvex ] if convex
         is[:spandrel       ] = true
      end

      # Label edge as :cornerconcave or :cornerconvex if linked to:
      #   2x deratable walls & f(relative polar wall vectors around edge)
      edge[:surfaces].keys.each do |i|
        break     if is[:corner]
        break unless deratables.size == 2
        break unless walls.key?(id)
        next      if i == id
        next  unless deratables.include?(i)
        next  unless walls.key?(i)

        s1      = edge[:surfaces][id]
        s2      = edge[:surfaces][i]
        concave = concave?(s1, s2)
        convex  = convex?(s1, s2)

        set[:cornerconcave] = shorts[:val][:cornerconcave] if concave
        set[:cornerconvex ] = shorts[:val][:cornerconvex ] if convex
         is[:corner       ] = true
      end

      # Label edge as :ceiling if linked to:
      #   +1 deratable surface(s)
      #   1x underatable CONDITIONED floor linked to an unoccupied space
      #   1x adjacent CONDITIONED ceiling linked to an occupied space
      edge[:surfaces].keys.each do |i|
        break     if is[:ceiling]
        break unless deratables.size > 0
        break     if floors.key?(id)
        next      if i == id
        next  unless floors.key?(i)
        next      if floors[i][:ground     ]
        next  unless floors[i][:conditioned]
        next      if floors[i][:occupied   ]

        ceiling = floors[i][:boundary]
        next unless ceilings.key?(ceiling)
        next unless ceilings[ceiling][:conditioned]
        next unless ceilings[ceiling][:occupied   ]

        other = deratables.first unless deratables.first == id
        other = deratables.last  unless deratables.last  == id
        other = id                   if deratables.size  == 1

        s1      = edge[:surfaces][id]
        s2      = edge[:surfaces][other]
        concave = concave?(s1, s2)
        convex  = convex?(s1, s2)
        flat    = !concave && !convex

        set[:ceiling       ] = shorts[:val][:ceiling       ] if flat
        set[:ceilingconcave] = shorts[:val][:ceilingconcave] if concave
        set[:ceilingconvex ] = shorts[:val][:ceilingconvex ] if convex
         is[:ceiling       ] = true
      end

      # Label edge as :parapet/:roof if linked to:
      #   1x deratable wall
      #   1x deratable ceiling
      edge[:surfaces].keys.each do |i|
        break     if is[:parapet]
        break     if is[:roof   ]
        break unless deratables.size == 2
        break unless ceilings.key?(id)
        next      if i == id
        next  unless deratables.include?(i)
        next  unless walls.key?(i)

        s1      = edge[:surfaces][id]
        s2      = edge[:surfaces][i ]
        concave = concave?(s1, s2)
        convex  = convex?(s1, s2)
        flat    = !concave && !convex

        if argh[:parapet]
          set[:parapet       ] = shorts[:val][:parapet       ] if flat
          set[:parapetconcave] = shorts[:val][:parapetconcave] if concave
          set[:parapetconvex ] = shorts[:val][:parapetconvex ] if convex
           is[:parapet       ] = true
        else
          set[:roof       ] = shorts[:val][:roof       ] if flat
          set[:roofconcave] = shorts[:val][:roofconcave] if concave
          set[:roofconvex ] = shorts[:val][:roofconvex ] if convex
           is[:roof       ] = true
        end
      end

      # Label edge as :party if linked to:
      #   1x OtherSideCoefficients surface
      #   1x (only) deratable surface
      edge[:surfaces].keys.each do |i|
        break     if is[:party]
        break unless deratables.size == 1
        next      if i == id
        next  unless tbd[:surfaces].key?(i)
        next      if holes.key?(i)
        next      if shades.key?(i)

        facing = tbd[:surfaces][i][:boundary].downcase
        next unless facing == "othersidecoefficients"

        s1      = edge[:surfaces][id]
        s2      = edge[:surfaces][i ]
        concave = concave?(s1, s2)
        convex  = convex?(s1, s2)
        flat    = !concave && !convex

        set[:party       ] = shorts[:val][:party       ] if flat
        set[:partyconcave] = shorts[:val][:partyconcave] if concave
        set[:partyconvex ] = shorts[:val][:partyconvex ] if convex
         is[:party       ] = true
      end

      # Label edge as :grade if linked to:
      #   1x surface (e.g. slab or wall) facing ground
      #   1x surface (i.e. wall) facing outdoors
      edge[:surfaces].keys.each do |i|
        break     if is[:grade]
        break unless deratables.size == 1
        next      if i == id
        next  unless tbd[:surfaces].key?(i)
        next  unless tbd[:surfaces][i].key?(:ground)
        next  unless tbd[:surfaces][i][:ground]

        s1      = edge[:surfaces][id]
        s2      = edge[:surfaces][i]
        concave = concave?(s1, s2)
        convex  = convex?(s1, s2)
        flat    = !concave && !convex

        set[:grade       ] = shorts[:val][:grade       ] if flat
        set[:gradeconcave] = shorts[:val][:gradeconcave] if concave
        set[:gradeconvex ] = shorts[:val][:gradeconvex ] if convex
         is[:grade       ] = true
      end

      # Label edge as :rimjoist, :balcony, :balconysill or :balconydoorsill,
      # if linked to:
      #   1x deratable surface
      #   1x CONDITIONED floor
      #   1x shade (optional)
      #   1x subsurface (optional)
      balcony         = false
      balconysill     = false # vertical fenestration
      balconydoorsill = false # opaque door

      # Despite referring to 'sill' or 'doorsill', a 'balconysill' or
      # 'balconydoorsill' edge may instead link (rarer) cases of balcony and a
      # fenestration/door head. ASHRAE 90.1 2022 does not make the distinction
      # between sill vs head when intermediate floor, balcony and vertical
      # fenestration meet. 'Sills' are simply the most common occurrence.
      edge[:surfaces].keys.each do |i|
        break if is[:ceiling]
        break if balcony
        next  if i == id

        balcony = shades.key?(i)
      end

      edge[:surfaces].keys.each do |i|
        break unless balcony
        break     if balconysill
        break     if balconydoorsill
        next      if i == id
        next  unless holes.key?(i)

        # Deratable surface "id" may not be the gardian of "i" (see sills).
        gardian = deratables.size == 1 ? id : ""
        target  = gardian

        # Retrieve base surface's subsurfaces.
        windows   = tbd[:surfaces][id].key?(:windows)
        doors     = tbd[:surfaces][id].key?(:doors)
        skylights = tbd[:surfaces][id].key?(:skylights)

        windows   =   windows ? tbd[:surfaces][id][:windows  ] : {}
        doors     =     doors ? tbd[:surfaces][id][:doors    ] : {}
        skylights = skylights ? tbd[:surfaces][id][:skylights] : {}

        # The gardian is "id" if subsurface "ids" holds "i".
        ids = windows.keys + doors.keys + skylights.keys

        if gardian.empty?
          other = deratables.first == id ? deratables.last : deratables.first

          gardian = ids.include?(i) ? id : other
          target  = ids.include?(i) ? other : id

          windows   = tbd[:surfaces][gardian].key?(:windows)
          doors     = tbd[:surfaces][gardian].key?(:doors)
          skylights = tbd[:surfaces][gardian].key?(:skylights)

          windows   =   windows ? tbd[:surfaces][gardian][:windows  ] : {}
          doors     =     doors ? tbd[:surfaces][gardian][:doors    ] : {}
          skylights = skylights ? tbd[:surfaces][gardian][:skylights] : {}

          ids = windows.keys + doors.keys + skylights.keys
        end

        unless ids.include?(i)
          log(ERR, "Balcony sill: orphaned subsurface #{i} (mth)")
          next
        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?
        sub = skylight unless skylight.empty?

        window = sub[:type] == :window
        door   = sub[:type] == :door
        glazed = door && sub.key?(:glazed) && sub[:glazed]

        if window || glazed
          balconysill = true
        elsif door
          balconydoorsill = true
        end
      end

      edge[:surfaces].keys.each do |i|
        break     if is[:ceiling        ]
        break     if is[:rimjoist       ]
        break     if is[:balcony        ]
        break     if is[:balconysill    ]
        break     if is[:balconydoorsill]
        break unless deratables.size > 0
        break     if floors.key?(id)
        next      if i == id
        next  unless floors.key?(i)
        next      if floors[i][:ground     ]
        next  unless floors[i][:conditioned]

        other = deratables.first unless deratables.first == id
        other = deratables.last  unless deratables.last  == id
        other = id                   if deratables.size  == 1

        s1      = edge[:surfaces][id]
        s2      = edge[:surfaces][other]
        concave = concave?(s1, s2)
        convex  = convex?(s1, s2)
        flat    = !concave && !convex

        if balconydoorsill
          set[:balconydoorsill       ] = shorts[:val][:balconydoorsill       ] if flat
          set[:balconydoorsillconcave] = shorts[:val][:balconydoorsillconcave] if concave
          set[:balconydoorsillconvex ] = shorts[:val][:balconydoorsillconvex ] if convex
           is[:balconydoorsill       ] = true
        elsif balconysill
          set[:balconysill           ] = shorts[:val][:balconysill           ] if flat
          set[:balconysillconcave    ] = shorts[:val][:balconysillconcave    ] if concave
          set[:balconysillconvex     ] = shorts[:val][:balconysillconvex     ] if convex
           is[:balconysill           ] = true
        elsif balcony
          set[:balcony               ] = shorts[:val][:balcony               ] if flat
          set[:balconyconcave        ] = shorts[:val][:balconyconcave        ] if concave
          set[:balconyconvex         ] = shorts[:val][:balconyconvex         ] if convex
           is[:balcony               ] = true
        else
          set[:rimjoist              ] = shorts[:val][:rimjoist              ] if flat
          set[:rimjoistconcave       ] = shorts[:val][:rimjoistconcave       ] if concave
          set[:rimjoistconvex        ] = shorts[:val][:rimjoistconvex        ] if convex
           is[:rimjoist              ] = true
        end
      end
    end # edge's surfaces loop

    edge[:psi] = set unless set.empty?
    edge[:set] = psi unless set.empty?
  end # edge loop

  # Tracking (mild) transitions between deratable surfaces around edges that
  # have not been previously tagged.
  edges.values.each do |edge|
    deratable = false
    next     if edge.key?(:psi)
    next unless edge.key?(:surfaces)

    edge[:surfaces].keys.each do |id|
      next unless tbd[:surfaces].key?(id)
      next unless tbd[:surfaces][id][:deratable]

      deratable = tbd[:surfaces][id][:deratable]
    end

    next unless deratable

    edge[:psi] = { transition: 0.000 }
    edge[:set] = json[:io][:building][:psi]
  end

  # 'Unhinged' subsurfaces, like Tubular Daylight Device (TDD) domes,
  # usually don't share edges with parent surfaces, e.g. floating 300mm above
  # parent roof surface. Add parent surface ID to unhinged edges.
  edges.values.each do |edge|
    next     if edge.key?(:psi)
    next unless edge.key?(:surfaces)
    next unless edge[:surfaces].size == 1

    id        = edge[:surfaces].first.first
    next unless holes.key?(id)
    next unless holes[id].attributes.key?(:unhinged)
    next unless holes[id].attributes[:unhinged]

    subsurface = model.getSubSurfaceByName(id)
    next      if subsurface.empty?

    subsurface = subsurface.get
    surface    = subsurface.surface
    next      if surface.empty?

    nom        = surface.get.nameString
    next  unless tbd[:surfaces].key?(nom)
    next  unless tbd[:surfaces][nom].key?(:conditioned)
    next  unless tbd[:surfaces][nom][:conditioned]

    edge[:surfaces][nom] = {}

    set        = {}
    set[:jamb] = shorts[:val][:jamb]
    edge[:psi] = set
    edge[:set] = json[:io][:building][:psi]
  end

  if json[:io]
    # Reset subsurface U-factors (if on file).
    if json[:io].key?(:subsurfaces)
      json[:io][:subsurfaces].each do |sub|
        match = false
        next unless sub.key?(:id)
        next unless sub.key?(:usi)

        tbd[:surfaces].values.each do |surface|
          break if match

          [:windows, :doors, :skylights].each do |types|
            break    if match
            next unless surface.key?(types)

            surface[types].each do |id, opening|
              break    if match
              next unless opening.key?(:u)
              next unless sub[:id] == id

              opening[:u] = sub[:usi]
              match       = true
            end
          end
        end
      end
    end

    # Reset wall-to-roof intersection type (if on file) ... per group.
    [:stories, :spacetypes, :spaces].each do |groups|
      key = :story
      key = :stype if groups == :spacetypes
      key = :space if groups == :spaces
      next unless json[:io].key?(groups)

      json[:io][groups].each do |group|
        next unless group.key?(:id)
        next unless group.key?(:parapet)

        edges.values.each do |edge|
          match = false
          next unless edge.key?(:psi)
          next unless edge.key?(:surfaces)
          next     if edge.key?(:io_type)

          edge[:surfaces].keys.each do |id|
            break    if match
            next unless tbd[:surfaces].key?(id)
            next unless tbd[:surfaces][id].key?(key)

            match = group[:id] == tbd[:surfaces][id][key].nameString
          end

          next unless match

          parapets = edge[:psi].keys.select {|ty| ty.to_s.include?("parapet")}
          roofs    = edge[:psi].keys.select {|ty| ty.to_s.include?("roof")}

          if group[:parapet]
            next unless parapets.empty?
            next     if roofs.empty?

            type = :parapet
            type = :parapetconcave if roofs.first.to_s.include?("concave")
            type = :parapetconvex  if roofs.first.to_s.include?("convex")

            edge[:psi][type] = shorts[:val][type]
            roofs.each {|ty| edge[:psi].delete(ty)}
          else
            next unless roofs.empty?
            next     if parapets.empty?

            type = :roof
            type = :roofconcave if parapets.first.to_s.include?("concave")
            type = :roofconvex  if parapets.first.to_s.include?("convex")

            edge[:psi][type] = shorts[:val][type]

            parapets.each { |ty| edge[:psi].delete(ty) }
          end
        end
      end
    end

    # Reset wall-to-roof intersection type (if on file) - individual surfaces.
    if json[:io].key?(:surfaces)
      json[:io][:surfaces].each do |surface|
        next unless surface.key?(:parapet)
        next unless surface.key?(:id)

        edges.values.each do |edge|
          next     if edge.key?(:io_type)
          next unless edge.key?(:psi)
          next unless edge.key?(:surfaces)
          next unless edge[:surfaces].keys.include?(surface[:id])

          parapets = edge[:psi].keys.select {|ty| ty.to_s.include?("parapet")}
          roofs    = edge[:psi].keys.select {|ty| ty.to_s.include?("roof")}


          if surface[:parapet]
            next unless parapets.empty?
            next     if roofs.empty?

            type = :parapet
            type = :parapetconcave if roofs.first.to_s.include?("concave")
            type = :parapetconvex  if roofs.first.to_s.include?("convex")

            edge[:psi][type] = shorts[:val][type]
            roofs.each {|ty| edge[:psi].delete(ty)}
          else
            next unless roofs.empty?
            next     if parapets.empty?

            type = :roof
            type = :roofconcave if parapets.first.to_s.include?("concave")
            type = :roofconvex  if parapets.first.to_s.include?("convex")

            edge[:psi][type] = shorts[:val][type]
            parapets.each {|ty| edge[:psi].delete(ty)}
          end
        end
      end
    end

    # A priori, TBD applies (default) :building PSI types and values to
    # individual edges. If a TBD JSON input file holds custom PSI sets for:
    #   :stories
    #   :spacetypes
    #   :surfaces
    #   :edges
    # ... that may apply to individual edges, then the default :building PSI
    # types and/or values are overridden, as follows:
    #   custom :stories    PSI sets trump :building PSI sets
    #   custom :spacetypes PSI sets trump aforementioned PSI sets
    #   custom :spaces     PSI sets trump aforementioned PSI sets
    #   custom :surfaces   PSI sets trump aforementioned PSI sets
    #   custom :edges      PSI sets trump aforementioned PSI sets
    [:stories, :spacetypes, :spaces].each do |groups|
      key = :story
      key = :stype if groups == :spacetypes
      key = :space if groups == :spaces
      next unless json[:io].key?(groups)

      json[:io][groups].each do |group|
        next unless group.key?(:id)
        next unless group.key?(:psi)
        next unless json[:psi].set.key?(group[:psi])

        sh = json[:psi].shorthands(group[:psi])
        next if sh[:val].empty?

        edges.values.each do |edge|
          match = false
          next unless edge.key?(:psi)
          next unless edge.key?(:surfaces)
          next     if edge.key?(:io_set)

          edge[:surfaces].keys.each do |id|
            break    if match
            next unless tbd[:surfaces].key?(id)
            next unless tbd[:surfaces][id].key?(key)

            match = group[:id] == tbd[:surfaces][id][key].nameString
          end

          next unless match

          set                       = {}
          edge[groups]              = {} unless edge.key?(groups)
          edge[groups][group[:psi]] = {}

          if edge.key?(:io_type)
            safer = json[:psi].safe(group[:psi], edge[:io_type])
            set[edge[:io_type]] = sh[:val][safer] if safer
          else
            edge[:psi].keys.each do |type|
              safer = json[:psi].safe(group[:psi], type)
              set[type] = sh[:val][safer] if safer
            end
          end

          edge[groups][group[:psi]] = set unless set.empty?
        end
      end

      # TBD/Topolys edges will generally be linked to more than one surface
      # and hence to more than one group. It is possible for a TBD JSON file
      # to hold 2x group PSI sets that end up targetting one or more edges
      # common to both groups. In such cases, TBD retains the most conductive
      # PSI type/value from either group PSI set.
      edges.values.each do |edge|
        next unless edge.key?(:psi)
        next unless edge.key?(groups)

        edge[:psi].keys.each do |type|
          vals = {}

          edge[groups].keys.each do |set|
            sh = json[:psi].shorthands(set)
            next if sh[:val].empty?

            safer     = json[:psi].safe(set, type)
            vals[set] = sh[:val][safer] if safer
          end

          next if vals.empty?

          edge[:psi ][type] = vals.values.max
          edge[:sets]       = {} unless edge.key?(:sets)
          edge[:sets][type] = vals.key(vals.values.max)
        end
      end
    end

    if json[:io].key?(:surfaces)
      json[:io][:surfaces].each do |surface|
        next unless surface.key?(:psi)
        next unless surface.key?(:id)
        next unless tbd[:surfaces].key?(surface[:id ])
        next unless json[:psi].set.key?(surface[:psi])

        sh = json[:psi].shorthands(surface[:psi])
        next if sh[:val].empty?

        edges.values.each do |edge|
          next     if edge.key?(:io_set)
          next unless edge.key?(:psi)
          next unless edge.key?(:surfaces)
          next unless edge[:surfaces].keys.include?(surface[:id])

          s   = edge[:surfaces][surface[:id]]
          set = {}

          if edge.key?(:io_type)
            safer = json[:psi].safe(surface[:psi], edge[:io_type])
            set[:io_type] = sh[:val][safer] if safer
          else
            edge[:psi].keys.each do |type|
              safer = json[:psi].safe(surface[:psi], type)
              set[type] = sh[:val][safer] if safer
            end
          end

          next if set.empty?

          s[:psi] = set
          s[:set] = surface[:psi]
        end
      end

      # TBD/Topolys edges will generally be linked to more than one surface. A
      # TBD JSON file may hold 2x surface PSI sets that target a shared edge.
      # TBD retains the most conductive PSI type/value from either set.
      edges.values.each do |edge|
        next unless edge.key?(:psi)
        next unless edge.key?(:surfaces)

        edge[:psi].keys.each do |type|
          vals = {}

          edge[:surfaces].each do |id, s|
            next unless s.key?(:psi)
            next unless s.key?(:set)
            next     if s[:set].empty?

            sh = json[:psi].shorthands(s[:set])
            next if sh[:val].empty?

            safer         = json[:psi].safe(s[:set], type)
            vals[s[:set]] = sh[:val][safer] if safer
          end

          next if vals.empty?

          edge[:psi ][type] = vals.values.max
          edge[:sets]       = {} unless edge.key?(:sets)
          edge[:sets][type] = vals.key(vals.values.max)
        end
      end
    end

    # Loop through all customized edges on file w/w/o a custom PSI set.
    edges.values.each do |edge|
      next unless edge.key?(:psi)
      next unless edge.key?(:io_type)
      next unless edge.key?(:surfaces)

      if edge.key?(:io_set)
        next unless json[:psi].set.key?(edge[:io_set])

        set = edge[:io_set]
      else
        next unless edge[:sets].key?(edge[:io_type])
        next unless json[:psi].set.key?(edge[:sets][edge[:io_type]])

        set = edge[:sets][edge[:io_type]]
      end

      sh = json[:psi].shorthands(set)
      next if sh[:val].empty?

      safer = json[:psi].safe(set, edge[:io_type])
      next unless safer

      if edge.key?(:io_set)
        edge[:psi] = {}
        edge[:set] = edge[:io_set]
      else
        edge[:sets] = {} unless edge.key?(:sets)
        edge[:sets][edge[:io_type]] = sh[:val][safer]
      end

      edge[:psi][edge[:io_type]] = sh[:val][safer]
    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)
    length     = edge[:length]
    length    *= edge[:mult  ] if edge.key?(:mult)
    bridge     = { psi: max, type: type, length: length }
    deratables = {}
    apertures  = {}

    if edge.key?(:sets) && edge[:sets].key?(type)
      edge[:set] = edge[:sets][type] unless edge.key?(:io_set)
    end

    # Retrieve valid linked surfaces as deratables.
    edge[:surfaces].each do |id, s|
      next unless tbd[:surfaces].key?(id)
      next unless tbd[:surfaces][id][:deratable]

      deratables[id] = s
    end

    edge[:surfaces].each { |id, s| apertures[id] = s if holes.key?(id) }
    next if apertures.size > 1 # edge links 2x openings

    # Prune dad if edge links an opening, its dad and an uncle.
    if deratables.size > 1 && apertures.size > 0
      deratables.each do |id, deratable|
        [:windows, :doors, :skylights].each do |types|
          next unless tbd[:surfaces][id].key?(types)

          tbd[:surfaces][id][types].keys.each do |sub|
            deratables.delete(id) if apertures.key?(sub)
          end
        end
      end
    end

    next if deratables.empty?

    # Sum RSI of targeted insulating layer from each deratable surface.
    deratables.each do |id, deratable|
      next unless tbd[:surfaces][id].key?(:r)

      rsi += tbd[:surfaces][id][:r]
    end

    # Assign heat loss from thermal bridges to surfaces, in proportion to
    # insulating layer thermal resistance.
    deratables.each do |id, deratable|
      ratio = 0
      ratio = tbd[:surfaces][id][:r] / rsi if rsi > 0.001
      loss  = bridge[:psi] * ratio
      b     = { psi: loss, type: bridge[:type], length: length, ratio: ratio }
      tbd[:surfaces][id][:edges] = {} unless tbd[:surfaces][id].key?(:edges)
      tbd[:surfaces][id][:edges][identifier] = b
    end
  end

  # Assign thermal bridging heat loss [in W/K] to each deratable surface.
  tbd[:surfaces].each do |id, surface|
    next unless surface.key?(:edges)

    surface[:heatloss] = 0
    e = surface[:edges].values

    e.each { |edge| surface[:heatloss] += edge[:psi] * edge[:length] }
  end

  # Add point conductances (W/K x count), in TBD JSON file (under surfaces).
  tbd[:surfaces].each do |id, s|
    next unless s[:deratable]
    next unless json[:io]
    next unless json[:io].key?(:surfaces)

    json[:io][:surfaces].each do |surface|
      next unless surface.key?(:khis)
      next unless surface.key?(:id)
      next unless surface[:id] == id

      surface[:khis].each do |k|
        next unless k.key?(:id)
        next unless k.key?(:count)
        next unless json[:khi].point.key?(k[:id])
        next unless json[:khi].point[k[:id]] > 0.001

        s[:heatloss]  = 0 unless s.key?(:heatloss)
        s[:heatloss] += json[:khi].point[k[:id]] * k[:count]
        s[:pts     ]  = {} unless s.key?(:pts)

        s[:pts][k[:id]] = { val: json[:khi].point[k[:id]], n: k[:count] }
      end
    end
  end

  # If user has selected a Ut to meet, e.g. argh'ments:
  #   :uprate_walls
  #   :wall_ut
  #   :wall_option ... (same triple arguments for roofs and exposed floors)
  #
  # ... 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

  # 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.
  tbd[:surfaces].each do |id, surface|
    next unless surface.key?(:construction)
    next unless surface.key?(:index)
    next unless surface.key?(:ltype)
    next unless surface.key?(:r)
    next unless surface.key?(:edges)
    next unless surface.key?(:heatloss)
    next unless surface[:heatloss].abs > TOL

    s = model.getSurfaceByName(id)
    next if s.empty?

    s = s.get

    index     = surface[:index       ]
    current_c = surface[:construction]
    c         = current_c.clone(model).to_LayeredConstruction.get
    m         = nil
    m         = derate(id, surface, c) if index
    # m may be nilled simply because the targeted construction has already
    # been derated, i.e. holds " tbd" in its name. Names of cloned/derated
    # constructions (due to TBD) include the surface name (since derated
    # constructions are now unique to each surface) and the suffix " c tbd".
    if m
      c.setLayer(index, m)
      c.setName("#{id} c tbd")
      current_R = rsi(current_c, s.filmResistance)

      # In principle, the derated "ratio" could be calculated simply by
      # accessing a surface's uFactor. Yet air layers within constructions
      # (not air films) are ignored in OpenStudio's uFactor calculation.
      # An example would be 25mm-50mm pressure-equalized air gaps behind
      # brick veneer. This is not always compliant to some energy codes.
      # TBD currently factors-in air gap (and exterior cladding) R-values.
      #
      # If one comments out the following loop (3 lines), tested surfaces
      # with air layers will generate discrepencies between the calculed RSi
      # value above and the inverse of the uFactor. All other surface
      # constructions pass the test.
      #
      # if ((1/current_R) - s.uFactor.to_f).abs > 0.005
      #   puts "#{s.nameString} - Usi:#{1/current_R} UFactor: #{s.uFactor}"
      # end
      s.setConstruction(c)

      # If the derated surface construction separates CONDITIONED space from
      # UNCONDITIONED or UNENCLOSED space, then derate the adjacent surface
      # construction as well (unless defaulted).
      if s.outsideBoundaryCondition.downcase == "surface"
        unless s.adjacentSurface.empty?
          adjacent = s.adjacentSurface.get
          nom      = adjacent.nameString
          default  = adjacent.isConstructionDefaulted == false

          if default  && tbd[:surfaces].key?(nom)
            current_cc = tbd[:surfaces][nom][:construction]
            cc         = current_cc.clone(model).to_LayeredConstruction.get
            cc.setLayer(tbd[:surfaces][nom][:index], m)
            cc.setName("#{nom} c tbd")
            adjacent.setConstruction(cc)
          end
        end
      end

      # Compute updated RSi value from layers.
      updated_c = s.construction.get.to_LayeredConstruction.get
      updated_R = rsi(updated_c, s.filmResistance)
      ratio     = -(current_R - updated_R) * 100 / current_R

      surface[:ratio] = ratio if ratio.abs > TOL
      surface[:u    ] = 1 / current_R # un-derated U-factors (for UA')
    end
  end

  # Ensure deratable surfaces have U-factors (even if NOT derated).
  tbd[:surfaces].each do |id, surface|
    next unless surface[:deratable]
    next unless surface.key?(:construction)
    next     if surface.key?(:u)

    s   = model.getSurfaceByName(id)
    msg = "Skipping missing surface '#{id}' (#{mth})"
    log(ERR, msg) if s.empty?
    next          if s.empty?

    surface[:u] = 1.0 / rsi(surface[:construction], s.get.filmResistance)
  end

  json[:io][:edges] = []
  # Enrich io with TBD/Topolys edge info before returning:
  #   1. edge custom PSI set, if on file
  #   2. edge PSI type
  #   3. edge length (m)
  #   4. edge origin & end vertices
  #   5. array of linked outside- or ground-facing surfaces
  edges.values.each do |e|
    next unless e.key?(:psi)
    next unless e.key?(:set)

    v    = e[:psi].values.max
    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
    edge[:v0z] = e[:v0].point.z
    edge[:v1x] = e[:v1].point.x
    edge[:v1y] = e[:v1].point.y
    edge[:v1z] = e[:v1].point.z

    json[:io][:edges] << edge
  end

  if json[:io][:edges].empty?
    json[:io].delete(:edges)
  else
    json[:io][:edges].sort_by { |e| [ e[:v0x], e[:v0y], e[:v0z],
                                      e[:v1x], e[:v1y], e[:v1z] ] }
  end

  # Populate UA' trade-off reference values (optional).
  if argh[:gen_ua] && argh[:ua_ref]
    case argh[:ua_ref]
    when "code (Quebec)"
      qc33(tbd[:surfaces], json[:psi], argh[:setpoints])
    end
  end

  tbd[:io       ] = json[:io     ]
  argh[:io      ] = tbd[:io      ]
  argh[:surfaces] = tbd[:surfaces]
  argh[:version ] = model.getVersion.versionIdentifier

  tbd
end

#properties(surface = nil, argh = {}) ⇒ `Hash`^?

Fetches OpenStudio surface properties, including opening areas & vertices.

Parameters:

surface (OpenStudio::Model::Surface) (defaults to: nil) —

a surface
argh (Hash) (defaults to: {}) —

TBD arguments

Options Hash (argh):

:setpoints (Bool) —

whether model holds thermal zone setpoints

Returns:

(Hash) —

TBD surface with key attributes (see )
(nil) —

if invalid input (see logs)

# File 'lib/tbd/geo.rb', line 276

def properties(surface = nil, argh = {})
  mth = "TBD::#{__callee__}"
  cl1 = OpenStudio::Model::Surface
  cl2 = OpenStudio::Model::LayeredConstruction
  cl3 = Hash
  return mismatch("surface", surface, cl1, mth) unless surface.is_a?(cl1)
  return mismatch("argh"   , argh   , cl3, mth) unless argh.is_a?(cl3)

  nom    = surface.nameString
  surf   = {}
  subs   = {}
  fd     = false
  return invalid("#{nom}",     mth, 1, ERR) if poly(surface).empty?
  return empty("#{nom} space", mth,    ERR) if surface.space.empty?

  space  = surface.space.get
  stype  = space.spaceType
  story  = space.buildingStory
  tr     = transforms(space)
  return   invalid("#{nom} transform", mth, 0, ERR) unless tr[:t] && tr[:r]

  t      = tr[:t]
  n      = truNormal(surface, tr[:r])
  return   invalid("#{nom} normal", mth, 0, ERR) unless n

  type   = surface.surfaceType.downcase
  facing = surface.outsideBoundaryCondition
  setpts = setpoints(space)

  if facing.downcase == "surface"
    empty = surface.adjacentSurface.empty?
    return invalid("#{nom}: adjacent surface", mth, 0, ERR) if empty

    facing = surface.adjacentSurface.get.nameString
  end

  unless surface.construction.empty?
    construction = surface.construction.get.to_LayeredConstruction

    unless construction.empty?
      construction = construction.get
      lyr          = insulatingLayer(construction)
      lyr[:index]  = nil unless lyr[:index].is_a?(Numeric)
      lyr[:index]  = nil unless lyr[:index] >= 0
      lyr[:index]  = nil unless lyr[:index] < construction.layers.size

      if lyr[:index]
        surf[:construction] = construction
        # index: ... of layer/material (to derate) within construction
        # ltype: either :massless (RSi) or :standard (k + d)
        # r    : initial RSi value of the indexed layer to derate
        surf[:index] = lyr[:index]
        surf[:ltype] = lyr[:type ]
        surf[:r    ] = lyr[:r    ]
      end
    end
  end

  unless argh.key?(:setpoints)
    heat = heatingTemperatureSetpoints?(model)
    cool = coolingTemperatureSetpoints?(model)
    argh[:setpoints] = heat || cool
  end

  if argh[:setpoints]
    surf[:heating] = setpts[:heating] unless setpts[:heating].nil?
    surf[:cooling] = setpts[:cooling] unless setpts[:cooling].nil?
  else
    surf[:heating] = 21.0
    surf[:cooling] = 24.0
  end

  surf[:conditioned] = surf.key?(:heating) || surf.key?(:cooling)
  surf[:space      ] = space
  surf[:occupied   ] = space.partofTotalFloorArea
  surf[:boundary   ] = facing
  surf[:ground     ] = surface.isGroundSurface
  surf[:type       ] = :floor
  surf[:type       ] = :ceiling      if type.include?("ceiling")
  surf[:type       ] = :wall         if type.include?("wall"   )
  surf[:stype      ] = stype.get unless stype.empty?
  surf[:story      ] = story.get unless story.empty?
  surf[:n          ] = n
  surf[:gross      ] = surface.grossArea
  surf[:filmRSI    ] = surface.filmResistance
  surf[:spandrel   ] = spandrel?(surface)

  surface.subSurfaces.sort_by { |s| s.nameString }.each do |s|
    next if poly(s).empty?

    id  = s.nameString
    typ = surface.surfaceType.downcase

    unless (3..4).cover?(s.vertices.size)
      log(ERR, "Skipping '#{id}': vertex # 3 or 4 (#{mth})")
      next
    end

    vec  = s.vertices
    area = s.grossArea
    mult = s.multiplier

    # An OpenStudio subsurface has a "type" (string), either defaulted during
    # initialization or explicitely set by the user (from a built-in list):
    #
    #   OpenStudio::Model::SubSurface.validSubSurfaceTypeValues
    #   - "FixedWindow"
    #   - "OperableWindow"
    #   - "Door"
    #   - "GlassDoor"
    #   - "OverheadDoor"
    #   - "Skylight"
    #   - "TubularDaylightDome"
    #   - "TubularDaylightDiffuser"
    typ = s.subSurfaceType.downcase

    # An OpenStudio default subsurface construction set can hold unique
    # constructions assigned for each of these admissible types. In addition,
    # type assignment determines whether frame/divider attributes can be
    # linked to a subsurface (this shortlist has evolved between OpenStudio
    # releases). Type assignment is relied upon when calculating (admissible)
    # fenestration areas. TBD also relies on OpenStudio subsurface type
    # assignment, with resulting TBD tags being a bit more concise, e.g.:
    #
    #   - :window includes "FixedWindow" and "OperableWindow"
    #   - :door includes "Door", "OverheadWindow" and "GlassDoor"
    #     ... a (roof) access roof hatch should be assigned as a "Door"
    #   - :skylight includes "Skylight", "TubularDaylightDome", etc.
    #
    type = :skylight
    type = :window if typ.include?("window") # operable or not
    type = :door   if typ.include?("door")   # fenestrated or not

    # In fact, ANY subsurface other than :window or :door is tagged as
    # :skylight, e.g. a glazed floor opening (CN, Calgary, Tokyo towers). This
    # happens to reflect OpenStudio default initialization behaviour. For
    # instance, a subsurface added to an exposed (horizontal) floor in
    # OpenStudio is automatically assigned a "Skylight" type. This is similar
    # to the auto-assignment of (opaque) walls, roof/ceilings and floors
    # (based on surface tilt) in OpenStudio.
    #
    # When it comes to major thermal bridging, ASHRAE 90.1 (2022) makes a
    # clear distinction between "vertical fenestration" (a defined term) and
    # all other subsurfaces. "Vertical fenestration" would include both
    # instances of "Window", as well as "GlassDoor". It would exclude however
    # a non-fenestrated "door" (another defined term), like "Door" &
    # "OverheadDoor", as well as skylights. TBD tracks relevant subsurface
    # attributes via a handful of boolean variables:
    glazed   = type == :door && typ.include?("glass")   # fenestrated door
    tubular  =                  typ.include?("tubular") # dome or diffuser
    domed    =                  typ.include?("dome")    # (tubular) dome
    unhinged = false                                    # (tubular) dome

    # It would be tempting (and simple) to have TBD further validate whether a
    # "GlassDoor" is actually integrated within a (vertical) wall. The
    # automated type assignment in OpenStudio is very simple and reliable (as
    # discussed in the preceding paragraphs), yet users can nonetheless reset
    # this explicitly. For instance, while a vertical surface may indeed be
    # auto-assigned "Wall", a modeller can just as easily reset its type as
    # "Floor". Although OpenStudio supports 90.1 rules by default, it's not
    # enforced. TBD retains the same approach: for whatever osbcur reason a
    # modeller may decide (and hopefully the "authority having jurisdiction"
    # may authorize) to reset a wall as a "Floor" or a roof skylight as a
    # "GlassDoor", TBD maintains the same OpenStudio policy. Either OpenStudio
    # (and consequently EnergyPlus) sub/surface type assignment is reliable,
    # or it is not.

    # Determine if TDD dome subsurface is 'unhinged', i.e. unconnected to its
    # base surface (not same 3D plane).
    if domed
      unhinged = true unless s.plane.equal(surface.plane)
      n = s.outwardNormal if unhinged
    end

    if area < TOL
      log(ERR, "Skipping '#{id}': gross area ~zero (#{mth})")
      next
    end

    c = s.construction

    if c.empty?
      log(ERR, "Skipping '#{id}': missing construction (#{mth})")
      next
    end

    c = c.get.to_LayeredConstruction

    if c.empty?
      log(WRN, "Skipping '#{id}': subs limited to #{cl2} (#{mth})")
      next
    end

    c = c.get

    # A subsurface may have an overall U-factor set by the user - a less
    # accurate option, yet easier to process (and often the only option
    # available). With EnergyPlus' "simple window" model, a subsurface's
    # construction has a single SimpleGlazing material/layer holding the
    # whole product U-factor.
    #
    #   https://bigladdersoftware.com/epx/docs/9-6/engineering-reference/
    #   window-calculation-module.html#simple-window-model
    #
    # TBD will instead rely on Tubular Daylighting Device (TDD) effective
    # dome-to-diffuser RSi-factors (if valid).
    #
    #   https://bigladdersoftware.com/epx/docs/9-6/engineering-reference/
    #   daylighting-devices.html#tubular-daylighting-devices
    #
    # In other cases, TBD will recover an 'additional property' tagged
    # "uFactor", assigned either to the individual subsurface itself, or else
    # assigned to its referenced construction (a more generic fallback).
    #
    # If all else fails, TBD will calculate an approximate whole product
    # U-factor by adding up the subsurface's layered construction material
    # thermal resistances (as well as the subsurface's parent surface film
    # resistances). This is the least reliable option, especially if
    # subsurfaces have Frame & Divider objects, or irregular geometry.
    u = s.uFactor
    u = u.get unless u.empty?

    if tubular & s.respond_to?(:daylightingDeviceTubular) # OSM > v3.3.0
      unless s.daylightingDeviceTubular.empty?
        r = s.daylightingDeviceTubular.get.effectiveThermalResistance
        u = 1 / r if r > TOL
      end
    end

    unless u.is_a?(Numeric)
      u = s.additionalProperties.getFeatureAsDouble("uFactor")
    end

    unless u.is_a?(Numeric)
      r = rsi(c, surface.filmResistance)

      if r < TOL
        log(ERR, "Skipping '#{id}': U-factor unavailable (#{mth})")
        next
      end

      u = 1 / r
    end

    frame = s.allowWindowPropertyFrameAndDivider
    frame = false if s.windowPropertyFrameAndDivider.empty?

    if frame
      fd    = true
      width = s.windowPropertyFrameAndDivider.get.frameWidth
      vec   = offset(vec, width, 300)
      area  = OpenStudio.getArea(vec)

      if area.empty?
        log(ERR, "Skipping '#{id}': invalid offset (#{mth})")
        next
      end

      area = area.get
    end

    sub = { v:        s.vertices,
            points:   vec,
            n:        n,
            gross:    s.grossArea,
            area:     area,
            mult:     mult,
            type:     type,
            u:        u,
            unhinged: unhinged }

    sub[:glazed] = true if glazed
    subs[id    ] = sub
  end

  valid = true
  # Test for conflicts (with fits?, overlaps?) between sub/surfaces to
  # determine whether to keep original points or switch to std::vector of
  # revised coordinates, offset by Frame & Divider frame width. This will
  # also inadvertently catch pre-existing (yet nonetheless invalid)
  # OpenStudio inputs (without Frame & Dividers).
  subs.each do |id, sub|
    break unless fd
    break unless valid

    valid = fits?(sub[:points], surface.vertices)
    log(ERR, "Skipping '#{id}': can't fit in '#{nom}' (#{mth})") unless valid

    subs.each do |i, sb|
      break unless valid
      next      if i == id

      if overlaps?(sb[:points], sub[:points])
        log(ERR, "Skipping '#{id}': overlaps sibling '#{i}' (#{mth})")
        valid = false
      end
    end
  end

  if fd
    subs.values.each { |sub| sub[:gross ] = sub[:area ] }     if valid
    subs.values.each { |sub| sub[:points] = sub[:v    ] } unless valid
    subs.values.each { |sub| sub[:area  ] = sub[:gross] } unless valid
  end

  subarea = 0

  subs.values.each { |sub| subarea += sub[:area] * sub[:mult] }

  surf[:net] = surf[:gross] - subarea

  # Tranform final Point 3D sets, and store.
  pts = (t * surface.vertices).map { |v| Topolys::Point3D.new(v.x, v.y, v.z) }

  surf[:points] = pts
  surf[:minz  ] = ( pts.map { |pt| pt.z } ).min

  subs.each do |id, sub|
    pts = (t * sub[:points]).map { |v| Topolys::Point3D.new(v.x, v.y, v.z) }

    sub[:points] = pts
    sub[:minz  ] = ( pts.map { |p| p.z } ).min

    [:windows, :doors, :skylights].each do |types|
      type = types.slice(0..-2).to_sym
      next unless sub[:type] == type

      surf[types]     = {} unless surf.key?(types)
      surf[types][id] = sub
    end
  end

  surf
end

#qc33(s = {}, sets = nil, spts = true) ⇒ `Bool`, `false`

Sets reference values for points, edges & surfaces (& subsurfaces) to compute Quebec energy code (Section 3.3) UA’ comparison (2021).

Parameters:

s (Hash) (defaults to: {}) —

TBD surfaces (keys: Openstudio surface names)
sets (TBD::PSI) (defaults to: nil) —

a TBD model’s PSI sets
spts (Bool) (defaults to: true) —

whether OpenStudio model holds heating/cooling setpoints

Options Hash (s):

:deratable (Bool) —

whether surface is deratable, s[]
:type (:wall, :ceiling, :floor) —

TBD surface type
:heating (#to_f) —

applicable heating setpoint temperature in °C
:cooling (#to_f) —

applicable cooling setpoint temperature in °C
:windows (Hash) —

TBD surface-specific windows e.g. s[]
:doors (Hash) —

TBD surface-specific doors
:skylights (Hash) —

TBD surface-specific skylights
:pts (Hash) —

point thermal bridges, e.g. s[] see KHI class
:edges (Hash) —

TBD edges (keys: Topolys edge identifiers)

Returns:

(Bool) —

whether successful in generating UA’ reference values
(false) —

if invalid inputs (see logs)

# File 'lib/tbd/ua.rb', line 437

def qc33(s = {}, sets = nil, spts = true)
  mth = "TBD::#{__callee__}"
  cl1 = Hash
  cl2 = TBD::PSI
  return mismatch("surfaces", s, cl1, mth, DBG, false) unless s.is_a?(cl1)
  return mismatch("sets",  sets, cl1, mth, DBG, false) unless sets.is_a?(cl2)

  shorts = sets.shorthands("code (Quebec)")
  empty  = shorts[:has].empty? || shorts[:val].empty?
  log(DBG, "Missing QC PSI set for 3.3 UA' tradeoff (#{mth})") if empty
  return false                                                 if empty

  ok = [true, false].include?(spts)
  log(DBG, "setpoints must be true or false for 3.3 UA' tradeoff") unless ok
  return false                                                     unless ok

  s.each do |id, surface|
    next unless surface.key?(:deratable)
    next unless surface[:deratable]
    next unless surface.key?(:type)

    heating = -50     if spts
    cooling =  50     if spts
    heating =  21 unless spts
    cooling =  24 unless spts
    heating = surface[:heating] if surface.key?(:heating)
    cooling = surface[:cooling] if surface.key?(:cooling)

    # Start with surface U-factors.
    ref = 1 / 5.46
    ref = 1 / 3.60 if surface[:type] == :wall

    # Adjust for lower heating setpoint (assumes -25°C design conditions).
    ref *= 43 / (heating + 25) if heating < 18 && cooling > 40

    surface[:ref] = ref

    if surface.key?(:skylights) # loop through subsurfaces
      ref = 2.85
      ref *= 43 / (heating + 25) if heating < 18 && cooling > 40

      surface[:skylights].values.map { |skylight| skylight[:ref] = ref }
    end

    if surface.key?(:windows)
      ref = 2.0
      ref *= 43 / (heating + 25) if heating < 18 && cooling > 40

      surface[:windows].values.map { |window| window[:ref] = ref }
    end

    if surface.key?(:doors)
      surface[:doors].each do |i, door|
        ref = 0.9
        ref = 2.0 if door.key?(:glazed) && door[:glazed]
        ref *= 43 / (heating + 25) if heating < 18 && cooling > 40
        door[:ref] = ref
      end
    end

    # Loop through point thermal bridges.
    surface[:pts].map { |i, pt| pt[:ref] = 0.5 } if surface.key?(:pts)

    # Loop through linear thermal bridges.
    if surface.key?(:edges)
      surface[:edges].values.each do |edge|
        next unless edge.key?(:type)
        next unless edge.key?(:ratio)

        safe = sets.safe("code (Quebec)", edge[:type])
        edge[:ref] = shorts[:val][safe] * edge[:ratio] if safe
      end
    end
  end

  true
end

#resetKIVA(model = nil, boundary = "Foundation") ⇒ `Bool`, `false`

Purge existing KIVA-related objects in an OpenStudio model. Resets ground- facing surface outside boundary condition to “Ground” or “Foundation”.

Parameters:

model (OpenStudio::Model::Model) (defaults to: nil) —

a model
boundary ("Ground", "Foundation") (defaults to: "Foundation") —

new outside boundary condition

Returns:

(Bool) —

true if model is free of KIVA-related objects
(false) —

if invalid input (see logs)

# File 'lib/tbd/geo.rb', line 706

def resetKIVA(model = nil, boundary = "Foundation")
  mth = "TBD::#{__callee__}"
  cl  = OpenStudio::Model::Model
  ck1 = model.is_a?(cl)
  ck2 = boundary.respond_to?(:to_s)
  kva = false
  b   = ["Ground", "Foundation"]
  return mismatch("model"   , model   , cl    , mth, DBG, kva) unless ck1
  return mismatch("boundary", boundary, String, mth, DBG, kva) unless ck2

  boundary.capitalize!
  return invalid("boundary", mth, 2, DBG, kva) unless b.include?(boundary)

  # Reset surface KIVA-related objects.
  model.getSurfaces.each do |surface|
    kva = true unless surface.adjacentFoundation.empty?
    kva = true unless surface.surfacePropertyExposedFoundationPerimeter.empty?
    surface.resetAdjacentFoundation
    surface.resetSurfacePropertyExposedFoundationPerimeter
    next unless surface.isGroundSurface
    next     if surface.outsideBoundaryCondition.capitalize == boundary

    lc = surface.construction.empty? ? nil : surface.construction.get
    surface.setOutsideBoundaryCondition(boundary)
    next if boundary == "Ground"
    next if lc.nil?

    surface.setConstruction(lc) if surface.construction.empty?
  end

  perimeters = model.getSurfacePropertyExposedFoundationPerimeters

  kva = true unless perimeters.empty?

  # Remove KIVA exposed perimeters.
  perimeters.each { |perimeter| perimeter.remove }

  # Remove KIVA custom blocks, & foundations.
  model.getFoundationKivas.each do |kiva|
    kiva.removeAllCustomBlocks
    kiva.remove
  end

  log(INF, "Purged KIVA objects from model (#{mth})") if kva

  true
end

#truNormal(s = nil, r = 0) ⇒ `Topolys::Vector3D`^?

Returns site (or true) Topolys normal vector of OpenStudio surface.

Parameters:

s (OpenStudio::Model::PlanarSurface) (defaults to: nil) —

a planar surface
r (#to_f) (defaults to: 0) —

a group/site rotation angle [0,2PI) radians

Returns:

(Topolys::Vector3D) —

true normal vector of s
(nil) —

if invalid input (see logs)

# File 'lib/tbd/geo.rb', line 254

def truNormal(s = nil, r = 0)
  mth = "TBD::#{__callee__}"
  cl  = OpenStudio::Model::PlanarSurface
  return mismatch("surface", s, cl, mth)   unless s.is_a?(cl)
  return invalid("rotation angle", mth, 2) unless r.respond_to?(:to_f)

  r = -r.to_f * Math::PI / 180.0
  vx = s.outwardNormal.x * Math.cos(r) - s.outwardNormal.y * Math.sin(r)
  vy = s.outwardNormal.x * Math.sin(r) + s.outwardNormal.y * Math.cos(r)
  vz = s.outwardNormal.z
  Topolys::Vector3D.new(vx, vy, vz)
end

#ua_md(ua = {}, lang = :en) ⇒ `Array<String>`

Generates MD-formatted, UA’ summary file.

option ua [#to_s] :objective ua[:objective] = “COMPLIANCE […]” option ua [#&] :details ua[:details] = “QC Energy Code […]” option ua [#to_s] :model “∑U•A + ∑PSI•L + ∑KHI•n […]” option ua [#key?] :b1 TB block of CONDITIONED spaces, ua[:b1] option ua [#key?] :b2 TB block of SEMIHEATED spaces, ua[:b2] option ua [#to_s] :descr user-provided project/summary description option ua [#to_s] :file OpenStudio file, e.g. “school23.osm” option ua [#to_s] :version OpenStudio SDK, e.g. “3.6.1” option ua [Time] :date time signature option ua [#to_s] :notes advisory info, ua[:notes] option ua [#key?] :areas binned areas (String), ua[:areas]

Parameters:

ua (#key?) (defaults to: {}) —

preprocessed collection of UA-related strings
lang (#to_sym) (defaults to: :en) —

selected language, :en or :fr

Returns:

(Array<String>) —

MD-formatted strings (see logs if empty)

# File 'lib/tbd/ua.rb', line 934

def ua_md(ua = {}, lang = :en)
  mth    = "TBD::#{__callee__}"
  report = []
  ck1    = ua.respond_to?(:key?)
  ck2    = lang.respond_to?(:to_sym)
  return mismatch(  "ua",   ua,   Hash, mth, DBG, report) unless ck1
  return mismatch("lang", lang, Symbol, mth, DBG, report) unless ck2

  lang = lang.to_sym
  return hashkey("language", ua, lang, mth, DBG, report) unless ua.key?(lang)
  return empty("ua"                  , mth, DBG, report)     if ua.empty?

  if ua[lang].key?(:objective) && ua[lang][:objective].respond_to?(:to_s)
    report << "# #{ua[lang][:objective].to_s}   "
    report << "   "
  end

  if ua[lang].key?(:details) && ua[lang][:details].respond_to?(:&)
    ua[lang][:details].each do |d|
      report << "#{d.to_s}   " if d.respond_to?(:to_s)
    end

    report << "   "
  end

  if ua.key?(:model) && ua[:model].respond_to?(:to_s)
    report << "##### SUMMARY   "   if lang == :en
    report << "##### SOMMAIRE   "  if lang == :fr
    report << "   "
    report << "#{ua[:model].to_s}   "
    report << "   "
  end

  if ua[lang].key?(:b1) && ua[lang][:b1].key?(:summary)
    last = ua[lang][:b1].keys.to_a.last
    report << "* #{ua[lang][:b1][:summary]}"

    ua[lang][:b1].each do |k, v|
      next                     if k == :summary
      report << "  * #{v}" unless k == last
      report << "  * #{v}   "  if k == last
      report << "   "          if k == last
    end
    report << "   "
  end

  if ua[lang].key?(:b2) && ua[lang][:b2].key?(:summary)
    last = ua[lang][:b2].keys.to_a.last
    report << "* #{ua[lang][:b2][:summary]}"

    ua[lang][:b2].each do |k, v|
      next                      if k == :summary
      report << "  * #{v}"  unless k == last
      report << "  * #{v}   "   if k == last
      report << "   "           if k == last
    end
    report << "   "
  end

  if ua.key?(:date)
    report << "##### DESCRIPTION   "
    report << "   "
    report << "* project : #{ua[:descr]}" if ua.key?(:descr) && lang == :en
    report << "* projet : #{ua[:descr]}"  if ua.key?(:descr) && lang == :fr
    model  = ""
    model  = "* model : #{ua[:file]}"     if ua.key?(:file)  && lang == :en
    model  = "* modèle : #{ua[:file]}"    if ua.key?(:file)  && lang == :fr
    model += " (v#{ua[:version]})"        if ua.key?(:version)
    report << model                   unless model.empty?
    report << "* TBD : v3.4.3"
    report << "* date : #{ua[:date]}"

    if lang == :en
      report << "* status : #{msg(status)}" unless status.zero?
      report << "* status : success !"          if status.zero?
    elsif lang == :fr
      report << "* statut : #{msg(status)}" unless status.zero?
      report << "* statut : succès !"           if status.zero?
    end
    report << "   "
  end

  if ua[lang].key?(:areas)
    report << "##### AREAS   " if lang == :en
    report << "##### AIRES   " if lang == :fr
    report << "   "
    ok = ua[lang][:areas].key?(:walls)
    report << "* #{ua[lang][:areas][:walls]}"  if ok
    ok = ua[lang][:areas].key?(:roofs)
    report << "* #{ua[lang][:areas][:roofs]}"  if ok
    ok = ua[lang][:areas].key?(:floors)
    report << "* #{ua[lang][:areas][:floors]}" if ok
    report << "   "
  end

  if ua[lang].key?(:notes)
    report << "##### NOTES   "
    report << "   "
    report << "#{ua[lang][:notes]}   "
    report << "   "
  end

  report
end

#ua_summary(date = Time.now, argh = {}) ⇒ `Hash`

Generates multilingual UA’ summary.

Parameters:

date (Time) (defaults to: Time.now) —

Time stamp
argh (Hash) (defaults to: {}) —

TBD arguments

Options Hash (argh):

:seed (#to_s) —

OpenStudio file, e.g. “school23.osm”
:ua_ref (#to_s) —

reference ruleset e.g. “code (Quebec)”
:surfaces (Hash) —

set of TBD surfaces (see )
:version (#to_s) —

OpenStudio SDK, e.g. “3.6.1”
:io (Hash) —

TBD input/output variables (see TBD JSON schema)

Returns:

(Hash) —

binned values for UA’ (see logs if empty)

# File 'lib/tbd/ua.rb', line 527

def ua_summary(date = Time.now, argh = {})
  mth = "TBD::#{__callee__}"
  cl1 = Time
  cl2 = String
  cl3 = Hash
  ua  = {}
  return mismatch("date", date, cl1, mth, DBG, ua) unless date.is_a?(cl1)
  return mismatch("argh", argh, cl3, mth, DBG, ua) unless argh.is_a?(cl3)

  argh[:seed    ] = ""  unless argh.key?(:seed)
  argh[:ua_ref  ] = ""  unless argh.key?(:ua_ref)
  argh[:surfaces] = nil unless argh.key?(:surfaces)
  argh[:version ] = ""  unless argh.key?(:version)
  argh[:io      ] = {}  unless argh.key?(:io)

  file = argh[:seed    ]
  ref  = argh[:ua_ref  ]
  s    = argh[:surfaces]
  v    = argh[:version ]
  io   = argh[:io      ]
  return mismatch(    "seed", file, cl2, mth, DBG, ua) unless file.is_a?(cl2)
  return mismatch( "UA' ref",  ref, cl2, mth, DBG, ua) unless ref.is_a?(cl2)
  return mismatch( "version",    v, cl2, mth, DBG, ua) unless v.is_a?(cl2)
  return mismatch("surfaces",    s, cl3, mth, DBG, ua) unless s.is_a?(cl3)
  return mismatch(      "io",   io, cl3, mth, DBG, ua) unless io.is_a?(cl3)
  return empty(   "surfaces",            mth, WRN, ua)     if s.empty?

  argh[:io][:description] = ""  unless argh[:io].key?(:description)
  descr = argh[:io][:description]

  ua[:descr  ] = ""
  ua[:file   ] = ""
  ua[:version] = ""
  ua[:model  ] = "∑U•A + ∑PSI•L + ∑KHI•n"
  ua[:date   ] = date
  ua[:descr  ] = descr unless descr.nil? || descr.empty?
  ua[:file   ] = file  unless file.nil?  || file.empty?
  ua[:version] = v     unless v.nil?     || v.empty?

  [:en, :fr].each { |lang| ua[lang] = {} }

  ua[:en][:notes] = "Automated assessment from the OpenStudio Measure, "\
    "Thermal Bridging and Derating (TBD). Open source and MIT-licensed, "\
    "TBD is provided as is (without warranty). Procedures are documented "\
    "in the source code: https://github.com/rd2/tbd. "

  ua[:fr][:notes] = "Analyse automatisée à partir de la measure "\
    "OpenStudio, 'Thermal Bridging and Derating' (ou TBD). Distribuée "\
    "librement (licence MIT), TBD est offerte telle quelle (sans "\
    "garantie). L'approche est documentée au sein du code source : "\
    "https://github.com/rd2/tbd."

  walls  = { net: 0, gross: 0, subs: 0 }
  roofs  = { net: 0, gross: 0, subs: 0 }
  floors = { net: 0, gross: 0, subs: 0 }
  areas  = { walls: walls, roofs: roofs, floors: floors }
  has    = {}
  val    = {}
  psi    = PSI.new

  unless ref.empty?
    shorts = psi.shorthands(ref)
    empty  = shorts[:has].empty? && shorts[:val].empty?
    has    = shorts[:has]                      unless empty
    val    = shorts[:val]                      unless empty
    log(ERR, "Invalid UA' reference set (#{mth})") if empty

    unless empty
      ua[:model] += " : Design vs '#{ref}'"

      case ref
      when "code (Quebec)"
        ua[:en][:objective] = "COMPLIANCE ASSESSMENT"
        ua[:en][:details  ] = []
        ua[:en][:details  ] << "Quebec Construction Code, Chapter I.1"
        ua[:en][:details  ] << "NECB 2015, modified version (2020)"
        ua[:en][:details  ] << "Division B, Section 3.3"
        ua[:en][:details  ] << "Building Envelope Trade-off Path"

        ua[:en][:notes] << " Calculations comply with Section 3.3 "\
          "requirements. Results are based on user input not subject to "\
          "prior validation (see DESCRIPTION), and as such the assessment "\
          "shall not be considered as a certification of compliance."

        ua[:fr][:objective] = "ANALYSE DE CONFORMITÉ"
        ua[:fr][:details  ] = []
        ua[:fr][:details  ] << "Code de construction du Québec, Chapitre I.1"
        ua[:fr][:details  ] << "CNÉB 2015, version modifiée (2020)"
        ua[:fr][:details  ] << "Division B, Section 3.3"
        ua[:fr][:details  ] << "Méthode des solutions de remplacement"

        ua[:fr][:notes] << " Les calculs sont conformes aux dispositions "\
          "de la Section 3.3. Les résultats sont tributaires d'intrants "\
          "fournis par l'utilisateur, sans validation préalable (voir "\
          "DESCRIPTION). Ce document ne peut constituer une attestation de "\
          "conformité."
      else
        ua[:en][:objective] = "UA'"
        ua[:fr][:objective] = "UA'"
      end
    end
  end

  # Set up 2x heating setpoint (HSTP) "blocks" (or bins):
  #   bloc1: spaces/zones with HSTP >= 18°C
  #   bloc2: spaces/zones with HSTP < 18°C
  #   (ref: 2021 Quebec energy code 3.3. UA' trade-off methodology)
  #   (... can be extended in the future to cover other standards)
  #
  # Determine UA' compliance separately for (i) bloc1 & (ii) bloc2.
  #
  # Each block's UA' = ∑ U•area + ∑ PSI•length + ∑ KHI•count
  blc = { walls:   0, roofs:     0, floors:    0, doors:     0,
          windows: 0, skylights: 0, rimjoists: 0, parapets:  0,
          trim:    0, corners:   0, balconies: 0, grade:     0,
          other:   0 } # party edges, expansion joints, spandrel edges, etc.

  b1       = {}
  b2       = {}
  b1[:pro] = blc       #  proposed design
  b1[:ref] = blc.clone #        reference
  b2[:pro] = blc.clone #  proposed design
  b2[:ref] = blc.clone #        reference

  # Loop through surfaces, subsurfaces and edges and populate bloc1 & bloc2.
  s.each do |id, surface|
    next unless surface.key?(:deratable)
    next unless surface[:deratable]
    next unless surface.key?(:type)

    type = surface[:type]
    next unless [:wall, :ceiling, :floor].include?(type)
    next unless surface.key?(:net)
    next unless surface[:net] > TOL
    next unless surface.key?(:u)
    next unless surface[:u] > TOL

    heating   = 21.0
    heating   = surface[:heating] if surface.key?(:heating)
    bloc      = b1
    bloc      = b2 if heating < 18
    reference = surface.key?(:ref)

    if type == :wall
      areas[:walls][:net ] += surface[:net]
      bloc[:pro][:walls  ] += surface[:net] * surface[:u  ]
      bloc[:ref][:walls  ] += surface[:net] * surface[:ref]     if reference
      bloc[:ref][:walls  ] += surface[:net] * surface[:u  ] unless reference
    elsif type == :ceiling
      areas[:roofs][:net ] += surface[:net]
      bloc[:pro][:roofs  ] += surface[:net] * surface[:u  ]
      bloc[:ref][:roofs  ] += surface[:net] * surface[:ref]     if reference
      bloc[:ref][:roofs  ] += surface[:net] * surface[:u  ] unless reference
    else
      areas[:floors][:net] += surface[:net]
      bloc[:pro][:floors ] += surface[:net] * surface[:u  ]
      bloc[:ref][:floors ] += surface[:net] * surface[:ref]     if reference
      bloc[:ref][:floors ] += surface[:net] * surface[:u  ] unless reference
    end

    [:doors, :windows, :skylights].each do |subs|
      next unless surface.key?(subs)

      surface[subs].values.each do |sub|
        next unless sub.key?(:gross)
        next unless sub.key?(:u    )
        next unless sub[:gross] > TOL
        next unless sub[:u    ] > TOL

        gross  = sub[:gross]
        gross *= sub[:mult ]                           if sub.key?(:mult)
        areas[:walls ][:subs] += gross                 if type == :wall
        areas[:roofs ][:subs] += gross                 if type == :ceiling
        areas[:floors][:subs] += gross                 if type == :floor
        bloc[:pro    ][subs ] += gross * sub[:u  ]
        bloc[:ref    ][subs ] += gross * sub[:ref]     if sub.key?(:ref)
        bloc[:ref    ][subs ] += gross * sub[:u  ] unless sub.key?(:ref)
      end
    end

    if surface.key?(:edges)
      surface[:edges].values.each do |edge|
        next unless edge.key?(:type)
        next unless edge.key?(:length)
        next unless edge[:length] > TOL
        next unless edge.key?(:psi)

        loss = edge[:length] * edge[:psi]
        type = edge[:type].to_s.downcase

        if edge[:type].to_s.downcase.include?("balcony")
          bloc[:pro][:balconies] += loss
        elsif edge[:type].to_s.downcase.include?("door")
          bloc[:pro][:trim     ] += loss
        elsif edge[:type].to_s.downcase.include?("skylight")
          bloc[:pro][:trim     ] += loss
        elsif edge[:type].to_s.downcase.include?("fenestration")
          bloc[:pro][:trim     ] += loss
        elsif edge[:type].to_s.downcase.include?("head")
          bloc[:pro][:trim     ] += loss
        elsif edge[:type].to_s.downcase.include?("sill")
          bloc[:pro][:trim     ] += loss
        elsif edge[:type].to_s.downcase.include?("jamb")
          bloc[:pro][:trim     ] += loss
        elsif edge[:type].to_s.downcase.include?("rimjoist")
          bloc[:pro][:rimjoists] += loss
        elsif edge[:type].to_s.downcase.include?("parapet")
          bloc[:pro][:parapets ] += loss
        elsif edge[:type].to_s.downcase.include?("roof")
          bloc[:pro][:parapets ] += loss
        elsif edge[:type].to_s.downcase.include?("corner")
          bloc[:pro][:corners  ] += loss
        elsif edge[:type].to_s.downcase.include?("grade")
          bloc[:pro][:grade    ] += loss
        else
          bloc[:pro][:other    ] += loss
        end

        next if val.empty?
        next if ref.empty?

        safer = psi.safe(ref, edge[:type])
        ok    = edge.key?(:ref)
        loss  = edge[:length] * edge[:ref]                    if ok
        loss  = edge[:length] * val[safer] * edge[:ratio] unless ok

        if edge[:type].to_s.downcase.include?("balcony")
          bloc[:ref][:balconies] += loss
        elsif edge[:type].to_s.downcase.include?("door")
          bloc[:ref][:trim     ] += loss
        elsif edge[:type].to_s.downcase.include?("skylight")
          bloc[:ref][:trim     ] += loss
        elsif edge[:type].to_s.downcase.include?("fenestration")
          bloc[:ref][:trim     ] += loss
        elsif edge[:type].to_s.downcase.include?("head")
          bloc[:ref][:trim     ] += loss
        elsif edge[:type].to_s.downcase.include?("sill")
          bloc[:ref][:trim     ] += loss
        elsif edge[:type].to_s.downcase.include?("jamb")
          bloc[:ref][:trim     ] += loss
        elsif edge[:type].to_s.downcase.include?("rimjoist")
          bloc[:ref][:rimjoists] += loss
        elsif edge[:type].to_s.downcase.include?("parapet")
          bloc[:ref][:parapets ] += loss
        elsif edge[:type].to_s.downcase.include?("roof")
          bloc[:ref][:parapets ] += loss
        elsif edge[:type].to_s.downcase.include?("corner")
          bloc[:ref][:corners  ] += loss
        elsif edge[:type].to_s.downcase.include?("grade")
          bloc[:ref][:grade    ] += loss
        else
          bloc[:ref][:other    ] += loss
        end
      end
    end

    if surface.key?(:pts)
      surface[:pts].values.each do |pts|
        next unless pts.key?(:val)
        next unless pts.key?(:n)

        bloc[:pro][:other] += pts[:val] * pts[:n]
        next unless pts.key?(:ref)

        bloc[:ref][:other] += pts[:ref] * pts[:n]
      end
    end
  end

  [:en, :fr].each do |lang|
    blc = [:b1, :b2]

    blc.each do |b|
      bloc    = b1
      bloc    = b2 if b == :b2
      pro_sum = bloc[:pro].values.sum
      ref_sum = bloc[:ref].values.sum

      if pro_sum > TOL || ref_sum > TOL
        ratio = nil
        ratio = (100.0 * (pro_sum - ref_sum) / ref_sum).abs if ref_sum > TOL
        str   = format("%.1f W/K (vs %.1f W/K)", pro_sum, ref_sum)
        str  += format(" +%.1f%%", ratio) if ratio && pro_sum > ref_sum # **
        str  += format(" -%.1f%%", ratio) if ratio && pro_sum < ref_sum
        ua[lang][b] = {}

        if b == :b1
          ua[:en][b][:summary] = "heated : #{str}"       if lang == :en
          ua[:fr][b][:summary] = "chauffé : #{str}"      if lang == :fr
        else
          ua[:en][b][:summary] = "semi-heated : #{str}"  if lang == :en
          ua[:fr][b][:summary] = "semi-chauffé : #{str}" if lang == :fr
        end

        bloc[:pro].each do |k, v|
          rf = bloc[:ref][k]
          next if v < TOL && rf < TOL
          ratio = nil
          ratio = (100.0 * (v - rf) / rf).abs            if rf > TOL
          str   = format("%.1f W/K (vs %.1f W/K)", v, rf)
          str  += format(" +%.1f%%", ratio)              if ratio && v > rf
          str  += format(" -%.1f%%", ratio)              if ratio && v < rf

          case k
          when :walls
            ua[:en][b][k] = "walls : #{str}"             if lang == :en
            ua[:fr][b][k] = "murs : #{str}"              if lang == :fr
          when :roofs
            ua[:en][b][k] = "roofs : #{str}"             if lang == :en
            ua[:fr][b][k] = "toits : #{str}"             if lang == :fr
          when :floors
            ua[:en][b][k] = "floors : #{str}"            if lang == :en
            ua[:fr][b][k] = "planchers : #{str}"         if lang == :fr
          when :doors
            ua[:en][b][k] = "doors : #{str}"             if lang == :en
            ua[:fr][b][k] = "portes : #{str}"            if lang == :fr
          when :windows
            ua[:en][b][k] = "windows : #{str}"           if lang == :en
            ua[:fr][b][k] = "fenêtres : #{str}"          if lang == :fr
          when :skylights
            ua[:en][b][k] = "skylights : #{str}"         if lang == :en
            ua[:fr][b][k] = "lanterneaux : #{str}"       if lang == :fr
          when :rimjoists
            ua[:en][b][k] = "rimjoists : #{str}"         if lang == :en
            ua[:fr][b][k] = "rives : #{str}"             if lang == :fr
          when :parapets
            ua[:en][b][k] = "parapets : #{str}"          if lang == :en
            ua[:fr][b][k] = "parapets : #{str}"          if lang == :fr
          when :trim
            ua[:en][b][k] = "trim : #{str}"              if lang == :en
            ua[:fr][b][k] = "chassis : #{str}"           if lang == :fr
          when :corners
            ua[:en][b][k] = "corners : #{str}"           if lang == :en
            ua[:fr][b][k] = "coins : #{str}"             if lang == :fr
          when :balconies
            ua[:en][b][k] = "balconies : #{str}"         if lang == :en
            ua[:fr][b][k] = "balcons : #{str}"           if lang == :fr
          when :grade
            ua[:en][b][k] = "grade : #{str}"             if lang == :en
            ua[:fr][b][k] = "tracé : #{str}"             if lang == :fr
          else
            ua[:en][b][k] = "other : #{str}"             if lang == :en
            ua[:fr][b][k] = "autres : #{str}"            if lang == :fr
          end
        end

        # Deterministic sorting.
        ua[lang][b][:summary] = ua[lang][b].delete(:summary)

        ua[lang][b].keys.each { |k| ua[lang][b][k] = ua[lang][b].delete(k) }
      end
    end
  end

  # Areas (m2).
  areas[:walls ][:gross] = areas[:walls ][:net] + areas[:walls ][:subs]
  areas[:roofs ][:gross] = areas[:roofs ][:net] + areas[:roofs ][:subs]
  areas[:floors][:gross] = areas[:floors][:net] + areas[:floors][:subs]

  ua[:en][:areas] = {}
  ua[:fr][:areas] = {}

  str  = format("walls : %.1f m2 (net)", areas[:walls][:net])
  str += format(", %.1f m2 (gross)", areas[:walls][:gross])
  ua[:en][:areas][:walls]  = str unless areas[:walls ][:gross] < TOL

  str  = format("roofs : %.1f m2 (net)", areas[:roofs][:net])
  str += format(", %.1f m2 (gross)", areas[:roofs][:gross])
  ua[:en][:areas][:roofs]  = str unless areas[:roofs ][:gross] < TOL

  str  = format("floors : %.1f m2 (net)", areas[:floors][:net])
  str += format(", %.1f m2 (gross)", areas[:floors][:gross])
  ua[:en][:areas][:floors] = str unless areas[:floors][:gross] < TOL

  str  = format("murs : %.1f m2 (net)", areas[:walls][:net])
  str += format(", %.1f m2 (brut)", areas[:walls][:gross])
  ua[:fr][:areas][:walls]  = str unless areas[:walls ][:gross] < TOL

  str  = format("toits : %.1f m2 (net)", areas[:roofs][:net])
  str += format(", %.1f m2 (brut)", areas[:roofs][:gross])
  ua[:fr][:areas][:roofs]  = str unless areas[:roofs ][:gross] < TOL

  str  = format("planchers : %.1f m2 (net)", areas[:floors][:net])
  str += format(", %.1f m2 (brut)", areas[:floors][:gross])
  ua[:fr][:areas][:floors] = str unless areas[:floors][:gross] < TOL

  ua
end

#uo(model = nil, lc = nil, id = "", hloss = 0.0, film = 0.0, ut = 0.0) ⇒ `Hash`

Calculates construction Uo (including surface film resistances) to meet Ut.

Parameters:

model (OpenStudio::Model::Model) (defaults to: nil) —

a model
lc (OpenStudio::Model::LayeredConstruction) (defaults to: nil) —

a layered construction
id (#to_s) (defaults to: "") —

layered construction identifier
hloss (Numeric) (defaults to: 0.0) —

heat loss from major thermal bridging, in W/K
film (Numeric) (defaults to: 0.0) —

target surface film resistance, in m2•K/W
ut (Numeric) (defaults to: 0.0) —

target overall Ut for lc, in W/m2•K

Returns:

(Hash) —

uo: lc Uo [W/m2•K] to meet Ut, m: uprated lc layer
(Hash) —

uo: (nil), m: (nil) if invalid input (see logs)

# File 'lib/tbd/ua.rb', line 36

def uo(model = nil, lc = nil, id = "", hloss = 0.0, film = 0.0, ut = 0.0)
  mth = "TBD::#{__callee__}"
  res = { uo: nil, m: nil }
  cl1 = OpenStudio::Model::Model
  cl2 = OpenStudio::Model::LayeredConstruction
  cl3 = Numeric
  cl4 = String
  id  = trim(id)
  return mismatch("model", model, cl1, mth, DBG, res) unless model.is_a?(cl1)
  return mismatch("id"   ,    id, cl4, mth, DBG, res)     if id.empty?
  return mismatch("lc"   ,    lc, cl2, mth, DBG, res) unless lc.is_a?(cl2)
  return mismatch("hloss", hloss, cl3, mth, DBG, res) unless hloss.is_a?(cl3)
  return mismatch("film" ,  film, cl3, mth, DBG, res) unless film.is_a?(cl3)
  return mismatch("Ut"   ,    ut, cl3, mth, DBG, res) unless ut.is_a?(cl3)

  loss        = 0.0 # residual heatloss (not assigned) [W/K]
  area        = lc.getNetArea
  lyr         = insulatingLayer(lc)
  lyr[:index] = nil unless lyr[:index].is_a?(Numeric)
  lyr[:index] = nil unless lyr[:index] >= 0
  lyr[:index] = nil unless lyr[:index] < lc.layers.size
  return invalid("#{id} layer index", mth, 3, ERR, res) unless lyr[:index]
  return zero("#{id}: heatloss"     , mth,    WRN, res) unless hloss > TOL
  return zero("#{id}: films"        , mth,    WRN, res) unless film  > TOL
  return zero("#{id}: Ut"           , mth,    WRN, res) unless ut    > TOL
  return invalid("#{id}: Ut"        , mth, 6, WRN, res) unless ut    < 5.678
  return zero("#{id}: net area (m2)", mth,    ERR, res) unless area  > TOL

  # First, calculate initial layer RSi to initially meet Ut target.
  rt     = 1 / ut              # target construction Rt
  ro     = rsi(lc, film)       # current construction Ro
  new_r  = lyr[:r] + (rt - ro) # new, un-derated layer RSi
  new_u  = 1 / new_r

  # Then, uprate (if possible) to counter expected thermal bridging effects.
  u_psi  = hloss / area        # from psi+khi
  new_u -= u_psi               # uprated layer USi to counter psi+khi
  new_r  = 1 / new_u           # uprated layer RSi to counter psi+khi
  return zero("#{id}: new Rsi", mth, ERR, res) unless new_r > 0.001

  if lyr[:type] == :massless
    m     = lc.getLayer(lyr[:index]).to_MasslessOpaqueMaterial
    return  invalid("#{id} massless layer?", mth, 0, DBG, res) if m.empty?

    m     = m.get.clone(model).to_MasslessOpaqueMaterial.get
            m.setName("#{id} uprated")
    new_r = 0.001                      unless new_r > 0.001
    loss  = (new_u - 1 / new_r) * area unless new_r > 0.001
            m.setThermalResistance(new_r)
  else # type == :standard
    m     = lc.getLayer(lyr[:index]).to_StandardOpaqueMaterial
    return  invalid("#{id} standard layer?", mth, 0, DBG, res) if m.empty?

    m     = m.get.clone(model).to_StandardOpaqueMaterial.get
            m.setName("#{id} uprated")
    k     = m.thermalConductivity

    if new_r > 0.001
      d   = new_r * k

      unless d > 0.003
        d    = 0.003
        k    = d / new_r
        k    = 3.0                    unless k < 3.0
        loss = (new_u - k / d) * area unless k < 3.0
      end
    else # new_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 = (new_u - k / d) * area
    end

    if m.setThickness(d)
      m.setThermalConductivity(k)
    else
      return invalid("Can't uprate #{id}: #{d} > 3m", mth, 0, ERR, res)
    end
  end

  return invalid("Can't ID insulating layer", mth, 0, ERR, res) unless m

  lc.setLayer(lyr[:index], m)
  uo = 1 / rsi(lc, film)

  if loss > TOL
    h_loss = format "%.3f", loss
    return invalid("Can't assign #{h_loss} W/K to #{id}", mth, 0, ERR, res)
  end

  res[:uo] = uo
  res[:m ] = m

  res
end

#uprate(model = nil, s = {}, argh = {}) ⇒ `Bool`, `false`

Uprates insulation layer of construction, based on user-selected Ut (argh).

Parameters:

model (OpenStudio::Model::Model) (defaults to: nil) —

a model
s (Hash) (defaults to: {}) —

preprocessed collection of TBD surfaces
argh (Hash) (defaults to: {}) —

TBD arguments

Options Hash (s):

:type (:wall, :ceiling, :floor) —

surface type
:deratable (Bool) —

whether surface can be thermally bridged
:construction (OpenStudio::LayeredConstruction) —

construction
:index (#to_i) —

deratable construction layer index
:ltype (:massless, :standard) —

indexed layer type
:filmRSI (#to_f) —

air film resistances (optional)
:r (#to_f) —

thermal resistance (RSI) of indexed layer

Options Hash (argh):

:uprate_walls (Bool) — default: false —

whether to uprate walls
:uprate_roofs (Bool) — default: false —

whether to uprate roofs
:uprate_floors (Bool) — default: false —

whether to uprate floors
:wall_ut (#to_f) — default: 5.678 —

uprated wall Usi-factor target
:roof_ut (#to_f) — default: 5.678 —

uprated roof Usi-factor target
:floor_ut (#to_f) — default: 5.678 —

uprated floor Usi-factor target
:wall_option (#to_s) — default: "") construction to uprate (or "all"
:roof_option (#to_s) — default: "") construction to uprate (or "all"
:floor_option (#to_s) — default: "") construction to uprate (or "all"

Returns:

(Bool) —

whether successfully uprated
(false) —

if invalid input (see logs)

# File 'lib/tbd/ua.rb', line 157

def uprate(model = nil, s = {}, argh = {})
  mth    = "TBD::#{__callee__}"
  cl1    = OpenStudio::Model::Model
  cl2    = Hash
  cl3    = OpenStudio::Model::LayeredConstruction
  tout   = []
  tout  << "all wall constructions"
  tout  << "all roof constructions"
  tout  << "all floor constructions"
  a      = false
  groups = { wall: {}, roof: {}, floor: {} }
  return mismatch("model"   , model, cl1, mth, DBG, a) unless model.is_a?(cl1)
  return mismatch("surfaces",     s, cl2, mth, DBG, a) unless s.is_a?(cl2)
  return mismatch("argh"    , model, cl1, mth, DBG, a) unless argh.is_a?(cl2)

  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_option  ] = ""    unless argh.key?(:wall_option)
  argh[:roof_option  ] = ""    unless argh.key?(:roof_option)
  argh[:floor_option ] = ""    unless argh.key?(:floor_option)

  argh[:wall_option  ] = trim(argh[:wall_option ])
  argh[:roof_option  ] = trim(argh[:roof_option ])
  argh[:floor_option ] = trim(argh[:floor_option])

  groups[:wall ][:up] = argh[:uprate_walls ]
  groups[:roof ][:up] = argh[:uprate_roofs ]
  groups[:floor][:up] = argh[:uprate_floors]
  groups[:wall ][:ut] = argh[:wall_ut      ]
  groups[:roof ][:ut] = argh[:roof_ut      ]
  groups[:floor][:ut] = argh[:floor_ut     ]

  groups[:wall ][:op] = trim(argh[:wall_option  ])
  groups[:roof ][:op] = trim(argh[:roof_option  ])
  groups[:floor][:op] = trim(argh[:floor_option ])

  groups.each do |type, g|
    next unless g[:up]
    next unless g[:ut].is_a?(Numeric)
    next unless g[:ut] < 5.678
    next     if g[:ut] < 0

    typ  = type
    typ  = :ceiling if typ == :roof
    coll = {}
    area = 0
    film = 100000000000000
    lc   = nil
    id   = ""
    op   = g[:op].downcase
    all  = tout.include?(op)

    if g[:op].empty?
      log(ERR, "Construction (#{type}) to uprate? (#{mth})")
    elsif all
      s.each do |nom, surface|
        next unless surface.key?(:deratable   )
        next unless surface.key?(:type        )
        next unless surface.key?(:construction)
        next unless surface.key?(:filmRSI     )
        next unless surface.key?(:index       )
        next unless surface.key?(:ltype       )
        next unless surface.key?(:r           )
        next unless surface[:deratable   ]
        next unless surface[:type        ] == typ
        next unless surface[:construction].is_a?(cl3)
        next     if surface[:index       ].nil?

        # Retain lowest surface film resistance (e.g. tilted surfaces).
        c    = surface[:construction]
        i    = c.nameString
        aire = c.getNetArea
        film = surface[:filmRSI] if surface[:filmRSI] < film

        # Retain construction covering largest area. The following conditional
        # is reliable UNLESS linked to other deratable surface types e.g. both
        # floors AND walls (see "elsif lc" corrections below).
        if aire > area
          lc   = c
          area = aire
          id   = i
        end

        coll[i] = { area: aire, lc: c, s: {} }  unless coll.key?(i)
        coll[i][:s][nom] = { a: surface[:net] } unless coll[i][:s].key?(nom)
      end
    else
      id = g[:op]
      lc = model.getConstructionByName(id)
      log(ERR, "Construction '#{id}'? (#{mth})")         if lc.empty?
      next                                               if lc.empty?

      lc = lc.get.to_LayeredConstruction
      log(ERR, "'#{id}' layered construction? (#{mth})") if lc.empty?
      next                                               if lc.empty?

      lc       = lc.get
      area     = lc.getNetArea
      coll[id] = { area: area, lc: lc, s: {} }

      s.each do |nom, surface|
        next unless surface.key?(:deratable   )
        next unless surface.key?(:type        )
        next unless surface.key?(:construction)
        next unless surface.key?(:filmRSI     )
        next unless surface.key?(:index       )
        next unless surface.key?(:ltype       )
        next unless surface.key?(:r           )
        next unless surface[:deratable   ]
        next unless surface[:type        ] == typ
        next unless surface[:construction].is_a?(cl3)
        next     if surface[:index       ].nil?

        i = surface[:construction].nameString
        next unless i == id

        # Retain lowest surface film resistance (e.g. tilted surfaces).
        film = surface[:filmRSI] if surface[:filmRSI] < film

        coll[i][:s][nom] = { a: surface[:net] } unless coll[i][:s].key?(nom)
      end
    end

    if coll.empty?
      log(ERR, "No #{type} construction to uprate - skipping (#{mth})")
      next
    elsif lc
      # Valid layered construction - good to uprate!
      lyr         = insulatingLayer(lc)
      lyr[:index] = nil unless lyr[:index].is_a?(Numeric)
      lyr[:index] = nil unless lyr[:index] >= 0
      lyr[:index] = nil unless lyr[:index] < lc.layers.size

      log(ERR, "Insulation index for '#{id}'? (#{mth})") unless lyr[:index]
      next                                               unless lyr[:index]

      # Ensure lc is exclusively linked to deratable surfaces of right type.
      # If not, assign new lc clone to non-targeted surfaces.
      s.each do |nom, surface|
        next unless surface.key?(:type        )
        next unless surface.key?(:deratable   )
        next unless surface.key?(:construction)
        next unless surface[:construction].is_a?(cl3)
        next unless surface[:construction] == lc

        ok = true
        ok = false unless surface[:type     ] == typ
        ok = false unless surface[:deratable]
        ok = false unless coll.key?(id)
        ok = false unless coll[id][:s].key?(nom)

        unless ok
          log(WRN, "Cloning '#{nom}' construction - not '#{id}' (#{mth})")
          sss = model.getSurfaceByName(nom)
          next if sss.empty?

          sss    = sss.get
          cloned = lc.clone(model).to_LayeredConstruction.get
          cloned.setName("#{nom} - cloned")
          sss.setConstruction(cloned)
          surface[:construction] = cloned
          coll[id][:s].delete(nom)
        end
      end

      hloss = 0 # sum of applicable psi+khi-related losses [W/K]

      # Tally applicable psi+khi losses. Possible construction reassignment.
      coll.each do |i, col|
        col[:s].keys.each do |nom|
          next unless s.key?(nom)
          next unless s[nom].key?(:construction)
          next unless s[nom].key?(:index)
          next unless s[nom].key?(:ltype)
          next unless s[nom].key?(:r)

          # Tally applicable psi+khi.
          hloss += s[nom][:heatloss    ] if s[nom].key?(:heatloss)
          next  if s[nom][:construction] == lc

          # Reassign construction unless referencing lc.
          sss = model.getSurfaceByName(nom)
          next if sss.empty?

          sss = sss.get

          if sss.isConstructionDefaulted
            set = defaultConstructionSet(sss) # building? story?
            constructions = set.defaultExteriorSurfaceConstructions

            unless constructions.empty?
              constructions = constructions.get
              constructions.setWallConstruction(lc)        if typ == :wall
              constructions.setFloorConstruction(lc)       if typ == :floor
              constructions.setRoofCeilingConstruction(lc) if typ == :ceiling
            end
          else
            sss.setConstruction(lc)
          end

          s[nom][:construction] = lc          # reset TBD attributes
          s[nom][:index       ] = lyr[:index]
          s[nom][:ltype       ] = lyr[:type ]
          s[nom][:r           ] = lyr[:r    ] # temporary
        end
      end

      # Merge to ensure a single entry for coll Hash.
      coll.each do |i, col|
        next if i == id

        col[:s].each do |nom, sss|
          coll[id][:s][nom] = sss unless coll[id][:s].key?(nom)
        end
      end

      coll.delete_if { |i, _| i != id }

      unless coll.size == 1
        log(DBG, "Collection == 1? for '#{id}' (#{mth})")
        next
      end

      coll[id][:area] = lc.getNetArea
      res = uo(model, lc, id, hloss, film, g[:ut])

      unless res[:uo] && res[:m]
        log(ERR, "Unable to uprate '#{id}' (#{mth})")
        next
      end

      lyr = insulatingLayer(lc)

      # Loop through coll :s, and reset :r - likely modified by uo().
      coll.values.first[:s].keys.each do |nom|
        next unless s.key?(nom)
        next unless s[nom].key?(:index)
        next unless s[nom].key?(:ltype)
        next unless s[nom].key?(:r    )
        next unless s[nom][:index] == lyr[:index]
        next unless s[nom][:ltype] == lyr[:type ]

        s[nom][:r] = lyr[:r] # uprated insulating RSi factor, before derating
      end

      argh[:wall_uo ] = res[:uo] if typ == :wall
      argh[:roof_uo ] = res[:uo] if typ == :ceiling
      argh[:floor_uo] = res[:uo] if typ == :floor
    else
      log(ERR, "Nilled construction to uprate - (#{mth})")
      return false
    end
  end

  true
end

Overview

Defined Under Namespace

Constant Summary collapse

Instance Method Summary collapse

Instance Method Details

#concave?(s1 = nil, s2 = nil) ⇒ `Bool`, `false`

#convex?(s1 = nil, s2 = nil) ⇒ `Bool`, `false`

#dads(model = nil, pops = {}) ⇒ `Hash`

#derate(id = "", s = {}, lc = nil) ⇒ `OpenStudio::Model::Material`^?

#exit(runner = nil, argh = {}) ⇒ `Bool`

#faces(s = {}, e = {}) ⇒ `Bool`, `false`

#inputs(s = {}, e = {}, argh = {}) ⇒ `Hash`

#kids(model = nil, boys = {}) ⇒ `Array<Topolys::Wire>`

#kiva(model = nil, walls = {}, floors = {}, edges = {}) ⇒ `Bool`, `false`

#matches?(e1 = {}, e2 = {}, tol = TOL) ⇒ `Bool`, `false`

#objects(model = nil, pts = []) ⇒ `Hash`

#process(model = nil, argh = {}) ⇒ `Hash`

#properties(surface = nil, argh = {}) ⇒ `Hash`^?

#qc33(s = {}, sets = nil, spts = true) ⇒ `Bool`, `false`

#resetKIVA(model = nil, boundary = "Foundation") ⇒ `Bool`, `false`

#truNormal(s = nil, r = 0) ⇒ `Topolys::Vector3D`^?

#ua_md(ua = {}, lang = :en) ⇒ `Array<String>`

#ua_summary(date = Time.now, argh = {}) ⇒ `Hash`

#uo(model = nil, lc = nil, id = "", hloss = 0.0, film = 0.0, ut = 0.0) ⇒ `Hash`

#uprate(model = nil, s = {}, argh = {}) ⇒ `Bool`, `false`

Module: TBD

Overview

Defined Under Namespace

Constant Summary collapse

Instance Method Summary collapse

Instance Method Details

#concave?(s1 = nil, s2 = nil) ⇒ Bool, false

#convex?(s1 = nil, s2 = nil) ⇒ Bool, false

#dads(model = nil, pops = {}) ⇒ Hash

#derate(id = "", s = {}, lc = nil) ⇒ OpenStudio::Model::Material?

#exit(runner = nil, argh = {}) ⇒ Bool

#faces(s = {}, e = {}) ⇒ Bool, false

#inputs(s = {}, e = {}, argh = {}) ⇒ Hash

#kids(model = nil, boys = {}) ⇒ Array<Topolys::Wire>

#kiva(model = nil, walls = {}, floors = {}, edges = {}) ⇒ Bool, false

#matches?(e1 = {}, e2 = {}, tol = TOL) ⇒ Bool, false

#objects(model = nil, pts = []) ⇒ Hash

#process(model = nil, argh = {}) ⇒ Hash

#properties(surface = nil, argh = {}) ⇒ Hash?

#qc33(s = {}, sets = nil, spts = true) ⇒ Bool, false

#resetKIVA(model = nil, boundary = "Foundation") ⇒ Bool, false

#truNormal(s = nil, r = 0) ⇒ Topolys::Vector3D?

#ua_md(ua = {}, lang = :en) ⇒ Array<String>

#ua_summary(date = Time.now, argh = {}) ⇒ Hash

#uo(model = nil, lc = nil, id = "", hloss = 0.0, film = 0.0, ut = 0.0) ⇒ Hash

#uprate(model = nil, s = {}, argh = {}) ⇒ Bool, false

#concave?(s1 = nil, s2 = nil) ⇒ `Bool`, `false`

#convex?(s1 = nil, s2 = nil) ⇒ `Bool`, `false`

#dads(model = nil, pops = {}) ⇒ `Hash`

#derate(id = "", s = {}, lc = nil) ⇒ `OpenStudio::Model::Material`^?

#exit(runner = nil, argh = {}) ⇒ `Bool`

#faces(s = {}, e = {}) ⇒ `Bool`, `false`

#inputs(s = {}, e = {}, argh = {}) ⇒ `Hash`

#kids(model = nil, boys = {}) ⇒ `Array<Topolys::Wire>`

#kiva(model = nil, walls = {}, floors = {}, edges = {}) ⇒ `Bool`, `false`

#matches?(e1 = {}, e2 = {}, tol = TOL) ⇒ `Bool`, `false`

#objects(model = nil, pts = []) ⇒ `Hash`

#process(model = nil, argh = {}) ⇒ `Hash`

#properties(surface = nil, argh = {}) ⇒ `Hash`^?

#qc33(s = {}, sets = nil, spts = true) ⇒ `Bool`, `false`

#resetKIVA(model = nil, boundary = "Foundation") ⇒ `Bool`, `false`

#truNormal(s = nil, r = 0) ⇒ `Topolys::Vector3D`^?

#ua_md(ua = {}, lang = :en) ⇒ `Array<String>`

#ua_summary(date = Time.now, argh = {}) ⇒ `Hash`

#uo(model = nil, lc = nil, id = "", hloss = 0.0, film = 0.0, ut = 0.0) ⇒ `Hash`

#uprate(model = nil, s = {}, argh = {}) ⇒ `Bool`, `false`