module BTAP::Resources::Envelope::Constructions

This module contains methods dealing with the creation and modification of constructions.

Public Class Methods

adjust_opaque_construction(construction:, req_conductance:) click to toggle source

This removes construction layers if the required conductance for a construction is higher than the maximum conductance that construction can have. Otherwise it modifies existing layers to set their thickness or resistance values (depending on what is in the layer) to achieve the required conductance. @author Chris Kirney <chris.kirney@canada.ca> @param construction <String> the construction we are modifying @param req_conductance [Fixnum] the conductance we are trying to reach @return [<String]OpenStudio::Model::getConstructionByName] the final construction after modification

# File lib/openstudio-standards/btap/envelope.rb, line 189
def self.adjust_opaque_construction(construction:, req_conductance:)
  layer_comp = []
  # Extract the thickness, conductivity, resistance of each layer of the construction.  If the material is
  # "No Mass", or "Air gap" set the conductivity (how well the material conducts heat) and conductance (how well
  # the material with a given thickness conducts heat) to the inverse of the resistance.  This is because
  # No Mass and Air gap materials do not have a thickness value.  Also, include which layer index the material
  # has and the material object itself.
  construction.layers.each_with_index do |layer, layer_index|
    mat_type = layer.iddObjectType.valueName.to_s
    case mat_type
    when "OS_Material"
      mat_layer = layer.to_StandardOpaqueMaterial.get
      layer_comp << {
          thickness_m: mat_layer.thickness.to_f,
          conductivity_SI: mat_layer.conductivity.to_f,
          conductance_SI: (mat_layer.conductivity.to_f / mat_layer.thickness.to_f),
          resistance_SI: (mat_layer.thickness.to_f / mat_layer.conductivity.to_f),
          construction_index: layer_index,
          layer_object: mat_layer
      }
    when "OS_Material_NoMass"
      mat_layer = layer.to_MasslessOpaqueMaterial.get
      layer_comp << {
          thickness_m: 0,
          conductivity_SI: 1.0 / mat_layer.thermalResistance.to_f,
          conductance_SI: 1.0 / mat_layer.thermalResistance.to_f,
          resistance_SI: mat_layer.thermalResistance.to_f,
          construction_index: layer_index,
          layer_object: mat_layer
      }
    when "OS_Material_AirGap"
      mat_layer = layer.to_AirGap.get
      layer_comp << {
          thickness_m: 0,
          conductivity_SI: 1.0 / mat_layer.thermalResistance.to_f,
          conductance_SI: 1.0 / mat_layer.thermalResistance.to_f,
          resistance_SI: mat_layer.thermalResistance.to_f,
          construction_index: layer_index,
          layer_object: mat_layer
      }
    end
  end
  # Sort the above layers by the conductivity of the layers.  The lowest conductivity layers first followed by
  # layers with progressively higher conductivities.
  sorted_layers = layer_comp.sort { |a, b| b[:conductivity_SI] <=> a[:conductivity_SI] }
  index = 0
  total_conductance = construction.thermalConductance.to_f
  # The following loop steps through the array of layers, sorted form highest conductivity to lowest.  It
  # deletes a layer in the construction if the conductance for the layer is not enough to reach the total
  # conductance for the construction that we are trying to reach.  If modifies the thickness or resistance
  # (depending on the layer material type) of a layer if doing so will reach the overall construction
  # conductance target. The total conductance of the construction is rounded because the conductance never seems
  # to be set precisely enough.

  while total_conductance.round(4) < req_conductance
    # There are too indicies that are tracked:
    # index:  The index of the element in the sorted array of layers that we are currently considering
    # const_index:  The index of the layer we are currently considering in the construction
    # Note that both the construction array and sorted array contain the same elements.  However these elements
    # may be in a different order.  Thus, the index and const_index may be different.  They will both indicate
    # the same layer.  However, they may differ because the sorted array is sorted by conductivity while the
    # construction array is ordered with the first layer outside (a given space) and the final layer inside (a
    # given space).
    const_index = sorted_layers[index][:construction_index]
    # Check if modifying the resistance of the currently layer will be enough to reach our total construction
    # conductance goal.  If it will, modify the layer.  If it will not, delete the layer.
    if sorted_layers[index][:resistance_SI] > ((1.0 / total_conductance) - (1.0 / req_conductance))
      # If the current layer is a NoMass or AirGap material its thickness is zero so we set the resistance.
      if sorted_layers[index][:thickness_m] == 0
        # Determine the resistance we want to set the layer to.
        res_mod = sorted_layers[index][:resistance_SI] - ((1.0 / total_conductance) - (1.0 / req_conductance))
        # Find out if the layer is an AirGap or NoMass and set the resistance for the layer with the right
        # command systax.
        mat_type = construction.layers[const_index].iddObjectType.valueName.to_s
        case mat_type
        when "OS_Material_NoMass"
          construction.layers[const_index].to_MasslessOpaqueMaterial.get.setThermalResistance(res_mod)
        when "OS_Material_AirGap"
          construction.layers[const_index].to_AirGap.get.setThermalResistance(res_mod)
        end
      else
        # The the current layer is a regular opaque material it has a thickness so we set that to reach the
        # desired resistance for that layer.
        # Determine the thickness we want to set the layer.
        thick_mod = (sorted_layers[index][:resistance_SI] - ((1.0 / total_conductance) - (1.0 / req_conductance))) * (sorted_layers[index][:conductivity_SI])
        # Set the thickness of the layer.
        construction.layers[const_index].to_StandardOpaqueMaterial.get.setThickness(thick_mod)
      end
      # Step the index of the sorted array forward by 1.  We should be able to leave the loop now because the
      # construction should have the conductance we want now.  But you never know.
      index += 1
    else
      # There the layer could not be adjusted to reach the desired conductance for the construction so get rid
      # of the layer.
      # If this is the only layer then we cannot get rid of it so throw an error.  This should never happen but
      # you never know.
      if sorted_layers.size == 1
        raise ("Could not set conductance of construction #{construction.name.to_s} to #{req_conductance} because existing layers make this impossible. Could not automatically change the constructions. Change the construction to allow for this conductance to be set.")
        return construction
      end
      # Delete the layer from the construction.
      construction.eraseLayer(const_index)
      # Delete the layer from the sorted set of layers (so that both the construction array and sorted array
      # continue to contain the same layers).
      sorted_layers.delete_at(index)
      # Go through the sorted array and change the construction indicies so that they continue to point to the
      # correct layers of the construction array. Note that index is not increased.  This is because the element
      # we were looking at just got removed so its index will be the same as that of what would have been the
      # next element.
      sorted_layers.each do |sorted_layer|
        if sorted_layer[:construction_index] > (const_index - 1)
          sorted_layer[:construction_index] -= 1
        end
      end
    end
    # Get the revised conductance for the construction now that it has been modified (by either removing or
    # modifying layers).
    total_conductance = construction.thermalConductance.to_f
    # Check if we have anything left to modify.  If yes, then keep going.  If not, then if we have done enough
    # we can stop and return the revised construction, otherwise throw an error.
    if construction.layers.size < index + 1
      if total_conductance.round(4) >= req_conductance
        return construction
      else
        raise ("Could not set conductance of construction #{construction.name.to_s} from the current conductance of #{total_conductance} to #{req_conductance} because existing layers make this impossible. Change the construction to allow for this conductance to be set.")
        return construction
      end
    end
  end
  # We have achieved our goal, return the revised construction.
  return construction
end
create_construction(model, name, materials, insulationLayer = nil) click to toggle source

This will create construction model @author Phylroy A. Lopez <plopez@nrcan.gc.ca> @param model [OpenStudio::Model::Model] @param name <String> @param materials <Material> @param insulationLayer = nil @return [String] construction

# File lib/openstudio-standards/btap/envelope.rb, line 350
def self.create_construction(model, name, materials, insulationLayer = nil)
  construction = OpenStudio::Model::Construction.new(model)
  construction.setName(name)
  #check to see if they are all Fenestation or Opaque. Can't mix and match.
  is_fenestration = false
  is_opaque = false
  #check to see if materials are all the same type.
  materials.each do |material|
    is_fenestration = true unless material.to_FenestrationMaterial.empty?
    is_opaque = true unless material.to_OpaqueMaterial.empty?
  end
  raise ("Materials Passed are not valid. Either they are mixed Opaque/Fenestration or invalid materials") if (is_fenestration and is_opaque) or (not is_fenestration and not is_opaque)
  construction.setLayers(materials)
  construction.setInsulation(insulationLayer) unless nil == insulationLayer or is_fenestration
  return construction
end
customize_fenestration_construction( model, construction, conductance = nil, solarTransmittanceatNormalIncidence = nil, visibleTransmittance = nil, at_temperature_c = 0.0) click to toggle source

This will customize fenestration construction @author Phylroy A. Lopez <plopez@nrcan.gc.ca> @param model [OpenStudio::Model::Model] @param construction <String> @param conductance <String> = nil @param solarTransmittanceatNormalIncidence [Float] = nil @param visibleTransmittance [Float] = nil @param at_temperature_c [Float] = 0.0 @return [String] create_construction

# File lib/openstudio-standards/btap/envelope.rb, line 376
def self.customize_fenestration_construction(
    model,
    construction,
    conductance = nil,
    solarTransmittanceatNormalIncidence = nil,
    visibleTransmittance = nil,
    at_temperature_c = 0.0)
  construction = OpenStudio::Model::getConstructionByName(model, construction.name.to_s).get
  raise ("This is not a fenestration!") unless construction.isFenestration
  #get equivilant values for tsol, tvis, and conductances.
  #TSol in this case is SHGC
  solarTransmittanceatNormalIncidence = OpenstudioStandards::Constructions.construction_get_solar_transmittance(construction) if solarTransmittanceatNormalIncidence.nil?
  visibleTransmittance = OpenstudioStandards::Constructions.construction_get_visible_transmittance(construction) if visibleTransmittance.nil?
  conductance = OpenstudioStandards::Constructions.construction_get_conductance(construction) if conductance.nil?
  frontSideSolarReflectanceatNormalIncidence = 1.0 - solarTransmittanceatNormalIncidence
  backSideSolarReflectanceatNormalIncidence = 1.0 - solarTransmittanceatNormalIncidence
  frontSideVisibleReflectanceatNormalIncidence = 0.081000
  backSideVisibleReflectanceatNormalIncidence = 0.081000
  infraredTransmittanceatNormalIncidence = 0.0
  frontSideInfraredHemisphericalEmissivity = 0.84
  backSideInfraredHemisphericalEmissivity = 0.84
  #store part of fenestation in array bins.
  glazing_array = Array.new()
  shading_material_array = Array.new()
  gas_array = Array.new()
  construction.layers.each do |material|
    glazing_array << material unless material.to_Glazing.empty?
    shading_material_array << material unless material.to_ShadingMaterial.empty?
    gas_array << material unless material.to_GasLayer.empty?
  end

  #set value of fictious glazing based on the fenestrations front and back if available
  unless glazing_array.first.to_StandardGlazing.empty?
    frontSideSolarReflectanceatNormalIncidence = glazing_array.first.to_StandardGlazing.get.frontSideSolarReflectanceatNormalIncidence
    frontSideVisibleReflectanceatNormalIncidence = glazing_array.first.to_StandardGlazing.get.frontSideVisibleReflectanceatNormalIncidence
    frontSideInfraredHemisphericalEmissivity = glazing_array.first.to_StandardGlazing.get.frontSideInfraredHemisphericalEmissivity
  end

  unless glazing_array.last.to_StandardGlazing.empty?
    backSideSolarReflectanceatNormalIncidence = glazing_array.last.to_StandardGlazing.get.backSideSolarReflectanceatNormalIncidence
    backSideVisibleReflectanceatNormalIncidence = glazing_array.last.to_StandardGlazing.get.backSideVisibleReflectanceatNormalIncidence
    backSideInfraredHemisphericalEmissivity = glazing_array.last.to_StandardGlazing.get.backSideInfraredHemisphericalEmissivity
  end
  #create fictious glazing.
  #assume a thickness of 0.10m
  thickness = 0.10
  #calculate conductivity
  conductivity = conductance * thickness
  data_name_suffix = "U=#{("%.3f" % conductivity).to_s} SHGC=#{("%.3f" % solarTransmittanceatNormalIncidence).to_s}"
  base_cons_name = construction.name.to_s
  if match = construction.name.to_s.match(/(.*)?:(.*)?/)
    base_cons_name = match.captures[0]
  end
  cons_name = "#{base_cons_name}:" + data_name_suffix
  glazing_name = "SimpleGlazing:" + data_name_suffix
  #Search to prevent the massive duplication that may ensue.
  return model.getConstructionByName(cons_name).get unless model.getConstructionByName(cons_name).empty?

  #fix for Simple glazing
  glazing_name = "SimpleGlazing:" + data_name_suffix
  glazing = nil
  if model.getSimpleGlazingByName(glazing_name).empty?
    glazing_name = "SimpleGlazing:" + data_name_suffix
    glazing = OpenStudio::Model::SimpleGlazing.new(construction.model)
    glazing.setSolarHeatGainCoefficient(solarTransmittanceatNormalIncidence)
    glazing.setUFactor(conductance)
    glazing.setThickness(0.21)
    glazing.setVisibleTransmittance(visibleTransmittance)
    glazing.setName(glazing_name)
  else
    glazing = model.getSimpleGlazingByName(glazing_name).get
  end

  #add the glazing and any shading materials to the array and create construction based on this.
  new_materials_array = Array.new()
  new_materials_array << glazing
  new_materials_array.concat(shading_material_array) unless shading_material_array.empty?
  #puts new_materials_array.size
  return self.create_construction(construction.model, cons_name, new_materials_array)
end
customize_opaque_construction(model, construction, conductance) click to toggle source

This method will create a new construction based on self and a new conductance value. It will check to see if a similar construction has already been created by this method if so it will return the existing construction. If you wish to keep some of the properties, enter the string “default” instead of a numerical value. @author Phylroy A. Lopez <plopez@nrcan.gc.ca> @param model [OpenStudio::Model::Model] @param construction <String> @param conductance [Fixnum] @return [<String]OpenStudio::Model::getConstructionByName] new_construction

# File lib/openstudio-standards/btap/envelope.rb, line 134
def self.customize_opaque_construction(model, construction, conductance)
  #Will convert from a string identifier to an object if required.
  construction = BTAP::Common::validate_array(model, construction, "Construction").first
  #If it is Opaque
  raise ("This construction is not opaque :#{construction.name}") unless (construction.isOpaque)
  minimum_resistance = 0
  base_cons_name = construction.name.to_s
  if match = construction.name.to_s.match(/(.*)?:(.*)?/)
    base_cons_name = match.captures[0]
  end
  name_prefix = "#{base_cons_name}:U-#{conductance}"

  #Check to see if we already made one like this.
  existing_construction = OpenStudio::Model::getConstructionByName(construction.model, name_prefix)
  if not existing_construction.empty?
    # if so, return existing construction
    return existing_construction.get
  end

  #create a copy
  new_construction = OpenstudioStandards::Constructions.construction_deep_copy(construction)

  #Change Construction name in clone
  new_construction.setName(name_prefix)

  if conductance.kind_of?(Float)
    #re-find insulation layer
    OpenstudioStandards::Constructions.construction_find_and_set_insulation_layer(new_construction)

    #Determine how low the resistance can be set. Subtract exisiting insulation
    #Values from the total resistance to see how low we can go.
    minimum_resistance = (1 / new_construction.thermalConductance.to_f) - (1.0 / new_construction.insulation.get.thermalConductance.to_f)

    #Check if the requested resistance is smaller than the minimum
    # resistance. If so, revise the construction layers.
    if minimum_resistance > (1 / conductance)
      # Changing the insulation layer will not be enough so either start removing layers or modify them to get
      # to the required conductance.
      new_construction = adjust_opaque_construction(construction: new_construction, req_conductance: conductance.to_f)
    else
      unless new_construction.setConductance(conductance)
        raise("could not set conductance of construction #{new_construction.name.to_s}")
      end
    end
  end
  return new_construction
end
should_modify_layer(mat_resistance:, total_conductance:, req_conductance:) click to toggle source

This checks if the construction layer can be modified to set thermal resistance of the whole construction to be less than the required resistance @author Chris Kirney <chris.kirney@canada.ca> @param mat_resistance <Fixnum> @param total_conductance <Fixnum> @param req_conductance <Fixnum> @return [<Fixnum>] layer resistance needed to meet construction material resistance, -999 if this is not enough

# File lib/openstudio-standards/btap/envelope.rb, line 329
def self.should_modify_layer(mat_resistance:, total_conductance:, req_conductance:)
  # Determine if the amount of resistance you can modify in this layer is greater than the amount of resistance
  # you have to change.
  if mat_resistance > ((1.0 / total_conductance) - (1.0 / req_conductance))
    # If yes, determine what the resistance for this layer should be to meet the required resistance of the
    # entire assembly.  Then return the new resistance value.
    target_res = mat_resistance - ((1.0 / total_conductance) - (1.0 / req_conductance))
    return target_res
  else
    # If no, then return an unambiguous no.
    return -999
  end
end