openstudio-standards 0.4.0 → 0.5.0.rc1

data/lib/openstudio-standards/btap/spaceloads.rb

@@ -63,7 +63,7 @@
 #
 #         #This method will scale people loads.
 #         #@author phylroy.lopez@nrcan.gc.ca
-#         #@param model [OpenStudio::model::Model] A model object
+#         #@param model [OpenStudio::Model::Model] A model object
 #         #@param factor [Float]
 #         def self.scale_people_loads( model, factor )
 #           model.getPeoples.sort.each do |item|
@@ -73,7 +73,7 @@
 #
 #         #This method will scale people loads schedule.
 #         #@author phylroy.lopez@nrcan.gc.ca
-#         #@param model [OpenStudio::model::Model] A model object
+#         #@param model [OpenStudio::Model::Model] A model object
 #         #@param a_coef [Float]
 #         #@param b_coef [Float]
 #         #@param c_coef [Float]
@@ -88,7 +88,7 @@
 #
 #         #This method will scale lighting loads.
 #         #@author phylroy.lopez@nrcan.gc.ca
-#         #@param model [OpenStudio::model::Model] A model object
+#         #@param model [OpenStudio::Model::Model] A model object
 #         #@param factor [Float]
 #         def self.scale_lighting_loads( model, factor )
 #           model.getLightss.sort.each do |item|
@@ -98,7 +98,7 @@
 #
 #         #This method will scale lighting loads schedule.
 #         #@author phylroy.lopez@nrcan.gc.ca
-#         #@param model [OpenStudio::model::Model] A model object
+#         #@param model [OpenStudio::Model::Model] A model object
 #         #@param a_coef [Float]
 #         #@param b_coef [Float]
 #         #@param c_coef [Float]
@@ -113,7 +113,7 @@
 #
 #         #This method will scale electrical loads.
 #         #@author phylroy.lopez@nrcan.gc.ca
-#         #@param model [OpenStudio::model::Model] A model object
+#         #@param model [OpenStudio::Model::Model] A model object
 #         #@param factor [Float]
 #         def self.scale_electrical_loads( model, factor )
 #           model.getElectricEquipments.sort.each do |item|
@@ -123,7 +123,7 @@
 #
 #         #This method will scale electrical loads schedule.
 #         #@author phylroy.lopez@nrcan.gc.ca
-#         #@param model [OpenStudio::model::Model] A model object
+#         #@param model [OpenStudio::Model::Model] A model object
 #         #@param a_coef [Float]
 #         #@param b_coef [Float]
 #         #@param c_coef [Float]
@@ -137,7 +137,7 @@
 #
 #         #This method will scale hotwater loads.
 #         #@author phylroy.lopez@nrcan.gc.ca
-#         #@param model [OpenStudio::model::Model] A model object
+#         #@param model [OpenStudio::Model::Model] A model object
 #         #@param factor [Float]
 #         def self.scale_hot_water_loads( model, factor )
 #           model.getHotWaterEquipments.sort.each do |item|
@@ -147,7 +147,7 @@
 #
 #         #This method will scale Outdoor Air loads.
 #         #@author phylroy.lopez@nrcan.gc.ca
-#         #@param model [OpenStudio::model::Model] A model object
+#         #@param model [OpenStudio::Model::Model] A model object
 #         #@param factor [Float]
 #         def self.scale_oa_loads( model, factor )
 #           model.getDesignSpecificationOutdoorAirs.sort.each do |oa_def|
@@ -160,7 +160,7 @@
 #
 #         #This method will scale infiltration loads.
 #         #@author phylroy.lopez@nrcan.gc.ca
-#         #@param model [OpenStudio::model::Model] A model object
+#         #@param model [OpenStudio::Model::Model] A model object
 #         #@param factor [Float]
 #         def self.scale_inflitration_loads( model, factor )
 #           model.getSpaceInfiltrationDesignFlowRates.sort.each do |infiltration_load|
@@ -173,7 +173,7 @@
 #
 #         #This method will set the infiltration magnitude.
 #         #@author phylroy.lopez@nrcan.gc.ca
-#         #@param model [OpenStudio::model::Model] A model object
+#         #@param model [OpenStudio::Model::Model] A model object
 #         #@param setDesignFlowRate [Float]
 #         #@param setFlowperSpaceFloorArea [Float]
 #         #@param setFlowperExteriorSurfaceArea [Float]
@@ -202,7 +202,7 @@
 #
 #       #This method removes people loads from the model.
 #       #@author phylroy.lopez@nrcan.gc.ca
-#       #@param model [OpenStudio::model::Model] A model object
+#       #@param model [OpenStudio::Model::Model] A model object
 #       def self.remove_all_people_loads(model)
 #         model.getPeoples.sort.each {|people| people.remove}
 #         model.getPeopleDefinitions.sort.each {|people| people.remove}
@@ -211,7 +211,7 @@
 #
 #       #This method created people loads from the model.
 #       #@author phylroy.lopez@nrcan.gc.ca
-#       #@param model [OpenStudio::model::Model] A model object
+#       #@param model [OpenStudio::Model::Model] A model object
 #       #@param people_name [String]
 #       #@param floor_area_per_person [Float]
 #       #@param multiplier [Float]
@@ -239,7 +239,7 @@
 #
 #       #This method removes light loads from model.
 #       #@author phylroy.lopez@nrcan.gc.ca
-#       #@param model [OpenStudio::model::Model] A model object
+#       #@param model [OpenStudio::Model::Model] A model object
 #       def self.remove_all_light_loads(model)
 #         model.getLightss.sort.each {|item| item.remove}
 #         model.getLightsDefinitions.sort.each {|item| item.remove}
@@ -247,7 +247,7 @@
 #
 #       #This method created people loads from the model.
 #       #@author phylroy.lopez@nrcan.gc.ca
-#       #@param model [OpenStudio::model::Model] A model object
+#       #@param model [OpenStudio::Model::Model] A model object
 #       #@param light_name [String]
 #       #@param light_watts_per_floor_area [Float]
 #       #@param multiplier [Float]
@@ -268,7 +268,7 @@
 #
 #       #This method removes elec loads from model.
 #       #@author phylroy.lopez@nrcan.gc.ca
-#       #@param model [OpenStudio::model::Model] A model object
+#       #@param model [OpenStudio::Model::Model] A model object
 #       def self.remove_all_electric_loads(model)
 #         model.getElectricEquipments.sort.each {|item| item.remove}
 #         model.getElectricEquipmentDefinitions.sort.each {|item| item.remove}
@@ -277,7 +277,7 @@
 #
 #       #This method created people loads from the model.
 #       #@author phylroy.lopez@nrcan.gc.ca
-#       #@param model [OpenStudio::model::Model] A model object
+#       #@param model [OpenStudio::Model::Model] A model object
 #       #@param elec_name [String]
 #       #@param elec_watts_per_floor_area [Float]
 #       #@param multiplier [Float]
@@ -297,7 +297,7 @@
 #
 #       #This method removes hot water loads from model.
 #       #@author phylroy.lopez@nrcan.gc.ca
-#       #@param model [OpenStudio::model::Model] A model object
+#       #@param model [OpenStudio::Model::Model] A model object
 #       def self.remove_all_hot_water_loads(model)
 #         model.getHotWaterEquipments.sort.each {|item| item.remove}
 #         model.getHotWaterEquipmentDefinitions.sort.each {|item| item.remove}
@@ -305,7 +305,7 @@
 #
 #       #This method creats hot water load.
 #       #@author phylroy.lopez@nrcan.gc.ca
-#       #@param model [OpenStudio::model::Model] A model object
+#       #@param model [OpenStudio::Model::Model] A model object
 #       #@param hot_water_name [String]
 #       #@param hot_water_watts_per_floor_area [Float]
 #       #@param multiplier [Float]
@@ -326,7 +326,7 @@
 #
 #       #This method removes all design specification OA from model.
 #       #@author phylroy.lopez@nrcan.gc.ca
-#       #@param model [OpenStudio::model::Model] A model object
+#       #@param model [OpenStudio::Model::Model] A model object
 #       def self.remove_all_DesignSpecificationOutdoorAir(model)
 #         model.getDesignSpecificationOutdoorAirs.sort.each { |item| item.remove }
 #       end
@@ -334,7 +334,7 @@
 #
 #       #This method removes all space infiltration design flow rate OA from model.
 #       #@author phylroy.lopez@nrcan.gc.ca
-#       #@param model [OpenStudio::model::Model] A model object
+#       #@param model [OpenStudio::Model::Model] A model object
 #       def self.remove_all_SpaceInfiltrationDesignFlowRate(model)
 #         OpenStudio::Model::SpaceInfiltrationDesignFlowRate
 #         model.getSpaceInfiltrationDesignFlowRates.sort.each { |item| item.remove }
@@ -342,7 +342,7 @@
 #
 #       #This method creats hot water load.
 #       #@author phylroy.lopez@nrcan.gc.ca
-#       #@param model [OpenStudio::model::Model] A model object
+#       #@param model [OpenStudio::Model::Model] A model object
 #       #@param oa_name [String]
 #       #@param oa_person [Fixnum]
 #       #@param oa_area [Fixnum]
@@ -350,7 +350,7 @@
 #       #@param oa_flowrate [Fixnum]
 #       #@param method [String]
 #       #@param schedule [Float]
-#       #@return [OpenStudio::model::Model] oa_def
+#       #@return [OpenStudio::Model::Model] oa_def
 #       def self.create_oa_load(model,oa_name,oa_person = 0 ,oa_area = 0, oa_ach = 0, oa_flowrate = 0, method = "Maximum",schedule = nil)
 #         raise("DesignSpecificationOutdoorAir #{name} already exists. Please use a different name") unless model.getDesignSpecificationOutdoorAirByName( oa_name ).empty?
 #         #units are in m3/s for flow and m2 for area.
@@ -373,7 +373,7 @@
 #
 #       #This method removes infiltration from model..
 #       #@author phylroy.lopez@nrcan.gc.ca
-#       #@param model [OpenStudio::model::Model] A model object
+#       #@param model [OpenStudio::Model::Model] A model object
 #       def self.remove_all_SpaceInfiltrationDesignFlowRates(model)
 #         model.getSpaceInfiltrationDesignFlowRates.sort.each { |item| item.remove }
 #       end
@@ -381,7 +381,7 @@
 #       #This method creates infiltration load.
 #       #NECB infiltration rate is 0.25L/s/m2  or 0.00025 m3/s/m2
 #       #@author phylroy.lopez@nrcan.gc.ca
-#       #@param model [OpenStudio::model::Model] A model object
+#       #@param model [OpenStudio::Model::Model] A model object
 #       #@return [String] infiltration_load
 #       def self.create_infiltration_load(model,
 #           infil_name,
@@ -419,7 +419,7 @@
 #
 #       #This method removes all loads from model.
 #       #@author phylroy.lopez@nrcan.gc.ca
-#       #@param model [OpenStudio::model::Model] A model object
+#       #@param model [OpenStudio::Model::Model] A model object
 #       def self.remove_all_casual_loads(model)
 #         self.remove_all_people_loads(model)
 #         self.remove_all_light_loads(model)
@@ -429,7 +429,7 @@
 #
 #       #This method removes all space loads from model.
 #       #@author phylroy.lopez@nrcan.gc.ca
-#       #@param model [OpenStudio::model::Model] A model object
+#       #@param model [OpenStudio::Model::Model] A model object
 #       def self.remove_all_SpaceLoads(model)
 #         model.getSpaceLoads.sort.each { |item| item.remove }
 #         model.getSpaceLoadDefinitions.sort.each { |item| item.remove }

data/lib/openstudio-standards/btap/utilities.rb

@@ -49,9 +49,9 @@
 #   #argument model(s). This is handy for quickly viewing changes to the file during
 #   #runtime for debugging and QA.
 #   #@author phylroy.lopez@nrcan.gc.ca
-#   #@param model1 [OpenStudio::model::Model] A model object.
-#   #@param model2 [OpenStudio::model::Model] A model object.
-#   #@param model3 [OpenStudio::model::Model] A model object.
+#   #@param model1 [OpenStudio::Model::Model] A model object.
+#   #@param model2 [OpenStudio::Model::Model] A model object.
+#   #@param model3 [OpenStudio::Model::Model] A model object.
 #   def self.kdiff3_model_osm(model1, model2, model3 = "")
 #     Dir::mkdir("C:\\kdiff_test") unless File.exists?("C:\\kdiff_test")
 #     model1.save(OpenStudio::Path.new("c:\\kdiff_test\\diffA.osm"))
@@ -71,9 +71,9 @@
 #   #argument model(s). This is handy for quickly viewing changes to the file during
 #   #runtime for debugging and QA.
 #   #@author phylroy.lopez@nrcan.gc.ca
-#   #@param model1 [OpenStudio::model::Model] A model object.
-#   #@param model2 [OpenStudio::model::Model] A model object.
-#   #@param model3 [OpenStudio::model::Model] A model object.
+#   #@param model1 [OpenStudio::Model::Model] A model object.
+#   #@param model2 [OpenStudio::Model::Model] A model object.
+#   #@param model3 [OpenStudio::Model::Model] A model object.
 #   def self.kdiff3_model_idf(model1, model2, model3 = "")
 #     Dir::mkdir("C:\\kdiff_test") unless File.exists?("C:\\kdiff_test")
 #

data/lib/openstudio-standards/btap/vintagizer.rb

@@ -24,7 +24,7 @@ class Vintagizer
   
   #This method loads Vintage database information.
   #@author phylroy.lopez@nrcan.gc.ca
-  #@param model [OpenStudio::model::Model] A model object
+  #@param model [OpenStudio::Model::Model] A model object
   #@param file [String] 
   #@param selectionHash [???] 
   def initialize(model,file,selectionHash)

data/lib/openstudio-standards/constructions/information.rb

@@ -0,0 +1,83 @@
+# Methods to create typical models
+module OpenstudioStandards
+  module Constructions
+    # @!group Information
+
+    # Returns the solar reflectance index of an exposed surface.
+    # On a scale of 0 to 100, standard black is 0, and standard white is 100.
+    # The calculation derived from ASTM E1980 assuming medium wind speed.
+    #
+    # @param construction [OpenStudio::Model::Construction] OpenStudio Construction object
+    # @return [Double] The solar reflectance value
+    def self.construction_get_solar_reflectance_index(construction)
+      exposed_material = construction.to_LayeredConstruction.get.getLayer(0)
+      solar_absorptance = exposed_material.to_OpaqueMaterial.get.solarAbsorptance
+      thermal_emissivity = exposed_material.to_OpaqueMaterial.get.thermalAbsorptance
+      x = (20.797 * solar_absorptance - 0.603 * thermal_emissivity) / (9.5205 * thermal_emissivity + 12.0)
+      sri = 123.97 - 141.35 * x + 9.6555 * x * x
+
+      return sri
+    end
+
+    # report names of constructions in a construction set
+    #
+    # @param default_construction_set [OpenStudio::Model::Defaultdefault_construction_set] OpenStudio Defaultdefault_construction_set object
+    # @return [Array<OpenStudio::Model::Construction>] Array of OpenStudio Construction objects
+    def self.construction_set_get_constructions(default_construction_set)
+      construction_array = []
+
+      # populate exterior surfaces
+      if default_construction_set.defaultExteriorSurfaceConstructions.is_initialized
+        default_surface_constructions = default_construction_set.defaultExteriorSurfaceConstructions.get
+        construction_array << default_surface_constructions.floorConstruction.get if default_surface_constructions.floorConstruction.is_initialized
+        construction_array << default_surface_constructions.wallConstruction.get if default_surface_constructions.wallConstruction.is_initialized
+        construction_array << default_surface_constructions.roofCeilingConstruction.get if default_surface_constructions.roofCeilingConstruction.is_initialized
+      end
+      # populate interior surfaces
+      if default_construction_set.defaultInteriorSurfaceConstructions.is_initialized
+        default_surface_constructions = default_construction_set.defaultInteriorSurfaceConstructions.get
+        construction_array << default_surface_constructions.floorConstruction.get if default_surface_constructions.floorConstruction.is_initialized
+        construction_array << default_surface_constructions.wallConstruction.get if default_surface_constructions.wallConstruction.is_initialized
+        construction_array << default_surface_constructions.roofCeilingConstruction.get if default_surface_constructions.roofCeilingConstruction.is_initialized
+      end
+      # populate ground surfaces
+      if default_construction_set.defaultGroundContactSurfaceConstructions.is_initialized
+        default_surface_constructions = default_construction_set.defaultGroundContactSurfaceConstructions.get
+        construction_array << default_surface_constructions.floorConstruction.get if default_surface_constructions.floorConstruction.is_initialized
+        construction_array << default_surface_constructions.wallConstruction.get if default_surface_constructions.wallConstruction.is_initialized
+        construction_array << default_surface_constructions.roofCeilingConstruction.get if default_surface_constructions.roofCeilingConstruction.is_initialized
+      end
+      # populate exterior sub-surfaces
+      if default_construction_set.defaultExteriorSubSurfaceConstructions.is_initialized
+        default_subsurface_constructions = default_construction_set.defaultExteriorSubSurfaceConstructions.get
+        construction_array << default_subsurface_constructions.fixedWindowConstruction.get if default_subsurface_constructions.fixedWindowConstruction.is_initialized
+        construction_array << default_subsurface_constructions.operableWindowConstruction.get if default_subsurface_constructions.operableWindowConstruction.is_initialized
+        construction_array << default_subsurface_constructions.doorConstruction.get if default_subsurface_constructions.doorConstruction.is_initialized
+        construction_array << default_subsurface_constructions.glassDoorConstruction.get if default_subsurface_constructions.glassDoorConstruction.is_initialized
+        construction_array << default_subsurface_constructions.overheadDoorConstruction.get if default_subsurface_constructions.overheadDoorConstruction.is_initialized
+        construction_array << default_subsurface_constructions.skylightConstruction.get if default_subsurface_constructions.skylightConstruction.is_initialized
+        construction_array << default_subsurface_constructions.tubularDaylightDomeConstruction.get if default_subsurface_constructions.tubularDaylightDomeConstruction.is_initialized
+        construction_array << default_subsurface_constructions.tubularDaylightDiffuserConstruction.get if default_subsurface_constructions.tubularDaylightDiffuserConstruction.is_initialized
+      end
+      # populate interior sub-surfaces
+      if default_construction_set.defaultInteriorSubSurfaceConstructions.is_initialized
+        default_subsurface_constructions = default_construction_set.defaultInteriorSubSurfaceConstructions.get
+        construction_array << default_subsurface_constructions.fixedWindowConstruction.get if default_subsurface_constructions.fixedWindowConstruction.is_initialized
+        construction_array << default_subsurface_constructions.operableWindowConstruction.get if default_subsurface_constructions.operableWindowConstruction.is_initialized
+        construction_array << default_subsurface_constructions.doorConstruction.get if default_subsurface_constructions.doorConstruction.is_initialized
+        construction_array << default_subsurface_constructions.glassDoorConstruction.get if default_subsurface_constructions.glassDoorConstruction.is_initialized
+        construction_array << default_subsurface_constructions.overheadDoorConstruction.get if default_subsurface_constructions.overheadDoorConstruction.is_initialized
+        construction_array << default_subsurface_constructions.skylightConstruction.get if default_subsurface_constructions.skylightConstruction.is_initialized
+        construction_array << default_subsurface_constructions.tubularDaylightDomeConstruction.get if default_subsurface_constructions.tubularDaylightDomeConstruction.is_initialized
+        construction_array << default_subsurface_constructions.tubularDaylightDiffuserConstruction.get if default_subsurface_constructions.tubularDaylightDiffuserConstruction.is_initialized
+      end
+      # populate misc surfaces
+      construction_array << default_construction_set.interiorPartitionConstruction.get if default_construction_set.interiorPartitionConstruction.is_initialized
+      construction_array << default_construction_set.spaceShadingConstruction.get if default_construction_set.spaceShadingConstruction.is_initialized
+      construction_array << default_construction_set.buildingShadingConstruction.get if default_construction_set.buildingShadingConstruction.is_initialized
+      construction_array << default_construction_set.siteShadingConstruction.get if default_construction_set.siteShadingConstruction.is_initialized
+
+      return construction_array
+    end
+  end
+end

data/lib/openstudio-standards/constructions/materials/modify.rb

@@ -0,0 +1,72 @@
+# Methods to modify material properties
+module OpenstudioStandards
+  module Constructions
+    module Materials
+      # @!group Modify
+
+      # change thermal resistance of opaque materials by increasing material thickness,
+      # or setting thermal resistance directly for massless or airgap materials.
+      #
+      # @param opaque_material [OpenStudio::Model::OpaqueMaterial] OpenStudio OpaqueMaterial object
+      # @param thermal_resistance [Double] Target thermal resistance of the material in m^2*K/W
+      # @return [OpenStudio::Model::OpaqueMaterial] OpenStudio OpaqueMaterial object
+      def self.opaque_material_set_thermal_resistance(opaque_material, thermal_resistance)
+        unless opaque_material.to_OpaqueMaterial.is_initialized
+          OpenStudio.logFree(OpenStudio::Error, 'openstudio.standards.constructions.materials', "Object #{opaque_material} cannot be cast as an OpaqueMaterial object.")
+          return false
+        end
+
+        # edit insulation material
+        material = opaque_material.to_OpaqueMaterial.get
+        if material.to_MasslessOpaqueMaterial.is_initialized
+          material = material.to_MasslessOpaqueMaterial.get
+          material.setThermalResistance(thermal_resistance)
+        elsif material.to_AirGap.is_initialized
+          material = material.to_AirGap.get
+          material.setThermalResistance(thermal_resistance)
+        else
+          starting_thickness = material.thickness
+          target_thickness = starting_thickness * thermal_resistance / material.thermalResistance
+          material.setThickness(target_thickness)
+        end
+
+        return material.to_OpaqueMaterial.get
+      end
+
+      # set material surface properties
+      #
+      # @param opaque_material [OpenStudio::Model::OpaqueMaterial] OpenStudio OpaqueMaterial object
+      # @param roughness [String] surface roughness. Options are 'VeryRough', 'Rough', 'MediumRough',
+      #   'MediumSmooth', 'Smooth', and 'VerySmooth'
+      # @param thermal_absorptance [Double] target thermal absorptance
+      # @param solar_absorptance [Double] target solar absorptance
+      # @param visible_absorptance [Double] target visible absorptance
+      # @return [OpenStudio::Model::OpaqueMaterial] OpenStudio OpaqueMaterial object
+      def self.opaque_material_set_surface_properties(opaque_material,
+                                                      roughness: nil,
+                                                      thermal_absorptance: nil,
+                                                      solar_absorptance: nil,
+                                                      visible_absorptance: nil)
+        unless opaque_material.to_OpaqueMaterial.is_initialized
+          OpenStudio.logFree(OpenStudio::Error, 'openstudio.standards.constructions.materials', "Object #{opaque_material} cannot be cast as an OpaqueMaterial object.")
+          return false
+        end
+
+        # set requested material properties
+        material = opaque_material.to_OpaqueMaterial.get
+        if material.to_StandardOpaqueMaterial.is_initialized
+          material = material.to_StandardOpaqueMaterial.get
+          material.setRoughness(roughness) unless roughness.nil?
+        elsif material.to_MasslessOpaqueMaterial.is_initialized
+          material = material.to_MasslessOpaqueMaterial.get
+          material.setRoughness(roughness) unless roughness.nil?
+        end
+        material.setThermalAbsorptance(thermal_absorptance) unless thermal_absorptance.nil?
+        material.setSolarAbsorptance(solar_absorptance) unless solar_absorptance.nil?
+        material.setVisibleAbsorptance(visible_absorptance) unless visible_absorptance.nil?
+
+        return material.to_OpaqueMaterial.get
+      end
+    end
+  end
+end

data/lib/openstudio-standards/constructions/modify.rb

@@ -0,0 +1,80 @@
+# Methods to modify construction properties
+module OpenstudioStandards
+  module Constructions
+    # @!group Modify
+
+    # add new material layer to a construction
+    #
+    # @param construction [OpenStudio::Model::Construction] OpenStudio Construction object
+    # @param layer_index [Integer] the layer index, default is 0
+    # @param name [String] name of the new material layer
+    # @param roughness [String] surface roughness of the new material layer.
+    #   Options are 'VeryRough', 'Rough', 'MediumRough', 'MediumSmooth', 'Smooth', and 'VerySmooth'
+    # @param thickness [Double] thickness of the new material layer in meters
+    # @param conductivity [Double] conductivity of new material layer in W/m*K
+    # @param density [Double] density of the new material layer in kg/m^3
+    # @param specific_heat [Double] specific heat of the new material layer in J/kg*K
+    # @param thermal_absorptance [Double] target thermal absorptance
+    # @param solar_absorptance [Double] target solar absorptance
+    # @param visible_absorptance [Double] target visible absorptance
+    # @return [OpenStudio::Model::StandardOpaqueMaterial] The new material layer, a OpenStudio StandardOpaqueMaterial object
+    def self.construction_add_new_opaque_material(construction,
+                                                  layer_index: 0,
+                                                  name: nil,
+                                                  roughness: nil,
+                                                  thickness: nil,
+                                                  conductivity: nil,
+                                                  density: nil,
+                                                  specific_heat: nil,
+                                                  thermal_absorptance: nil,
+                                                  solar_absorptance: nil,
+                                                  visible_absorptance: nil)
+
+      # make new material
+      new_material = OpenStudio::Model::StandardOpaqueMaterial.new(construction.model)
+      if name.nil?
+        new_material.setName("#{construction.name} New Material")
+      else
+        new_material.setName(name)
+      end
+
+      # set requested material properties
+      new_material.setRoughness(roughness) unless roughness.nil?
+      new_material.setThickness(thickness) unless thickness.nil?
+      new_material.setConductivity(conductivity) unless conductivity.nil?
+      new_material.setDensity(density) unless density.nil?
+      new_material.setSpecificHeat(specific_heat) unless specific_heat.nil?
+      new_material.setThermalAbsorptance(thermal_absorptance) unless thermal_absorptance.nil?
+      new_material.setSolarAbsorptance(solar_absorptance) unless solar_absorptance.nil?
+      new_material.setVisibleAbsorptance(visible_absorptance) unless visible_absorptance.nil?
+
+      # add material to construction
+      construction.insertLayer(layer_index, new_material)
+
+      return new_material
+    end
+
+    # set construction surface properties
+    #
+    # @param construction [OpenStudio::Model::Construction] OpenStudio Construction object
+    # @param roughness [String] surface roughness
+    # @param thermal_absorptance [Double] target thermal absorptance
+    # @param solar_absorptance [Double] target solar absorptance
+    # @param visible_absorptance [Double] target visible absorptance
+    # @return [OpenStudio::Model::OpaqueMaterial] OpenStudio OpaqueMaterial object
+    def self.construction_set_surface_properties(construction,
+                                                 roughness: nil,
+                                                 thermal_absorptance: nil,
+                                                 solar_absorptance: nil,
+                                                 visible_absorptance: nil)
+
+      surface_material = construction.to_LayeredConstruction.get.getLayer(0)
+      new_material = OpenstudioStandards::Constructions::Materials.opaque_material_set_surface_properties(surface_material,
+                                                                                                          roughness: roughness,
+                                                                                                          thermal_absorptance: thermal_absorptance,
+                                                                                                          solar_absorptance: solar_absorptance,
+                                                                                                          visible_absorptance: visible_absorptance)
+      return new_material
+    end
+  end
+end