openstudio-standards 0.2.14 → 0.2.15.pre.rc1

data/lib/openstudio-standards/standards/Standards.SpaceType.rb

@@ -3,6 +3,7 @@ class Standard
 
   # Returns standards data for selected space type and template
   #
+  # @param space_type [OpenStudio::Model::SpaceType] space type object
   # @return [hash] hash of internal loads for different load types
   def space_type_get_standards_data(space_type)
     standards_building_type = if space_type.standardsBuildingType.is_initialized
@@ -30,10 +31,10 @@ class Standard
     return space_type_properties
   end
 
-  # Sets the color for the space types as shown
-  # in the SketchUp plugin using render by space type.
+  # Sets the color for the space types as shown in the SketchUp plugin using render by space type.
   #
-  # @return [Bool] returns true if successful, false if not.
+  # @param space_type [OpenStudio::Model::SpaceType] space type object
+  # @return [Bool] returns true if successful, false if not
   def space_type_apply_rendering_color(space_type)
     # Get the standards data
     space_type_properties = space_type_get_standards_data(space_type)
@@ -65,11 +66,12 @@ class Standard
   # to have the specified values. This method does not alter any
   # loads directly assigned to spaces.  This method skips plenums.
   #
+  # @param space_type [OpenStudio::Model::SpaceType] space type object
   # @param set_people [Bool] if true, set the people density.
-  # Also, assign reasonable clothing, air velocity, and work efficiency inputs
-  # to allow reasonable thermal comfort metrics to be calculated.
+  #   Also, assign reasonable clothing, air velocity, and work efficiency inputs
+  #   to allow reasonable thermal comfort metrics to be calculated.
   # @param set_lights [Bool] if true, set the lighting density, lighting fraction
-  # to return air, fraction radiant, and fraction visible.
+  #   to return air, fraction radiant, and fraction visible.
   # @param set_electric_equipment [Bool] if true, set the electric equipment density
   # @param set_gas_equipment [Bool] if true, set the gas equipment density
   # @param set_ventilation [Bool] if true, set the ventilation rates (per-person and per-area)
@@ -456,14 +458,15 @@ class Standard
   # This method does not alter any schedules of any internal loads that
   # does not inherit from the default schedule set.
   #
+  # @param space_type [OpenStudio::Model::SpaceType] space type object
   # @param set_people [Bool] if true, set the occupancy and activity schedules
   # @param set_lights [Bool] if true, set the lighting schedule
   # @param set_electric_equipment [Bool] if true, set the electric schedule schedule
   # @param set_gas_equipment [Bool] if true, set the gas equipment density
   # @param set_infiltration [Bool] if true, set the infiltration schedule
   # @param make_thermostat [Bool] if true, makes a thermostat for this space type from the
-  # schedules listed for the space type.  This thermostat is not hooked to any zone by this method,
-  # but may be found and used later.
+  #   schedules listed for the space type.  This thermostat is not hooked to any zone by this method,
+  #   but may be found and used later.
   # @return [Bool] returns true if successful, false if not
   def space_type_apply_internal_load_schedules(space_type, set_people, set_lights, set_electric_equipment, set_gas_equipment, set_ventilation, set_infiltration, make_thermostat)
     # Get the standards data
@@ -551,16 +554,24 @@ class Standard
     return true
   end
 
+  # applies a lighting schedule to a space type
+  #
+  # @param space_type [OpenStudio::Model::SpaceType] space type object
+  # @param space_type_properties [Hash] hash of space type properties
+  # @param default_sch_set [OpenStudio::Model::DefaultScheduleSet] default schedule set
+  # @return [Bool] returns true if successful, false if not
   def apply_lighting_schedule(space_type, space_type_properties, default_sch_set)
     lighting_sch = space_type_properties['lighting_schedule']
-    unless lighting_sch.nil?
-      default_sch_set.setLightingSchedule(model_add_schedule(space_type.model, lighting_sch))
-      OpenStudio.logFree(OpenStudio::Info, 'openstudio.standards.SpaceType', "#{space_type.name} set lighting schedule to #{lighting_sch}.")
-    end
+    return false if lighting_sch.nil?
+
+    default_sch_set.setLightingSchedule(model_add_schedule(space_type.model, lighting_sch))
+    OpenStudio.logFree(OpenStudio::Info, 'openstudio.standards.SpaceType', "#{space_type.name} set lighting schedule to #{lighting_sch}.")
+    return true
   end
 
   # Returns standards data for selected construction
   #
+  # @param space_type [OpenStudio::Model::SpaceType] space type object
   # @param intended_surface_type [string] the type of surface
   # @param standards_construction_type [string] the type of construction
   # @return [hash] hash of construction properties

data/lib/openstudio-standards/standards/Standards.SubSurface.rb

@@ -3,9 +3,9 @@ class Standard
 
   # Determine the component infiltration rate for this surface
   #
+  # @param sub_surface [OpenStudio::Model::SubSurface] sub surface object
   # @param type [String] choices are 'baseline' and 'advanced'
-  # @return [Double] infiltration rate
-  #   @units cubic meters per second (m^3/s)
+  # @return [Double] infiltration rate in m^3/s
   def sub_surface_component_infiltration_rate(sub_surface, type)
     comp_infil_rate_m3_per_s = 0.0
 
@@ -73,12 +73,12 @@ class Standard
     return comp_infil_rate_m3_per_s
   end
 
-  # Reduce the area of the subsurface by shrinking it
-  # toward the centroid.
+  # Reduce the area of the subsurface by shrinking it toward the centroid.
   # @author Julien Marrec
   #
-  # @param percent_reduction [Double] the fractional amount
-  # to reduce the area.
+  # @param sub_surface [OpenStudio::Model::SubSurface] sub surface object
+  # @param percent_reduction [Double] the fractional amount to reduce the area
+  # @return [Bool] returns true if successful, false if not
   def sub_surface_reduce_area_by_percent_by_shrinking_toward_centroid(sub_surface, percent_reduction)
     mult = 1 - percent_reduction
     scale_factor = mult**0.5
@@ -108,11 +108,11 @@ class Standard
     sub_surface.setVertices(new_vertices)
   end
 
-  # Reduce the area of the subsurface by raising the
-  # sill height.
+  # Reduce the area of the subsurface by raising the sill height.
   #
-  # @param percent_reduction [Double] the fractional amount
-  # to reduce the area.
+  # @param sub_surface [OpenStudio::Model::SubSurface] sub surface object
+  # @param percent_reduction [Double] the fractional amount to reduce the area.
+  # @return [Bool] returns true if successful, false if not
   def sub_surface_reduce_area_by_percent_by_raising_sill(sub_surface, percent_reduction)
     mult = 1 - percent_reduction
 
@@ -159,6 +159,9 @@ class Standard
 
   # Determine if the sub surface is a vertical rectangle,
   # meaning a rectangle where the bottom is parallel to the ground.
+  #
+  # @param sub_surface [OpenStudio::Model::SubSurface] sub surface object
+  # @return [Bool] returns true if the surface is a vertical rectangle, false if not
   def sub_surface_vertical_rectangle?(sub_surface)
     # Get the vertices once
     verts = sub_surface.vertices
@@ -183,14 +186,18 @@ class Standard
     # If here, we have a rectangle
     return true
   end
+
   # This method adds a subsurface (a window or a skylight depending on the surface) to the centroid of a surface.  The
   # shape of the subsurface is the same as the surface but is scaled so the area of the subsurface is the defined
   # fraction of the surface (set by area_fraction).  Note that this only works for surfaces that do not fold into
   # themselves (like an 'L' or a 'V').
-
-  def sub_surface_create_centered_subsurface_from_scaled_surface(surface, area_fraction, model)
+  #
+  # @param surface [OpenStudio::Model::Surface] surface object
+  # @param area_fraction [Double] fraction of area of the larger surface
+  # @return [Bool] returns true if successful, false if not
+  def sub_surface_create_centered_subsurface_from_scaled_surface(surface, area_fraction)
     # Get rid of all existing subsurfaces.
-    remove_All_Subsurfaces(surface: surface)
+    remove_all_subsurfaces(surface: surface)
     # What is the centroid of the surface.
     surf_cent = surface.centroid
     scale_factor = Math.sqrt(area_fraction)
@@ -213,8 +220,9 @@ class Standard
       # Add the new vertices to an array of vertices.
       new_vertices << new_vertex
     end
+
     # Create a new subsurface with the vertices determined above.
-    new_sub_surface = OpenStudio::Model::SubSurface.new(new_vertices, model)
+    new_sub_surface = OpenStudio::Model::SubSurface.new(new_vertices, surface.model)
     # Put this sub-surface on the surface.
     new_sub_surface.setSurface(surface)
     # Set the name of the subsurface to be the surface name plus the subsurface type (likely either 'fixedwindow' or
@@ -223,6 +231,7 @@ class Standard
     new_sub_surface.setName(new_name)
     # There is now only one surface on the subsurface.  Enforce this
     new_sub_surface.setMultiplier(1)
+    return true
   end
 
   # This method adds a subsurface (a window or a skylight depending on the surface) to the centroid of a surface.  The
@@ -231,20 +240,23 @@ class Standard
   # 'sub_surface_create_centered_subsurface_from_scaled_surface' method because it can handle concave surfaces.
   # However, it takes longer because it uses BTAP::Geometry::Surfaces.make_convex_surfaces which includes many nested
   # loops that cycle through the verticies in a surface.
-  def sub_surface_create_scaled_subsurfaces_from_surface(surface:, area_fraction:, model:, consturction:)
+  #
+  # @param surface [OpenStudio::Model::Surface] surface object
+  # @param area_fraction [Double] fraction of area of the larger surface
+  # @param construction [OpenStudio::Model::Construction] construction to use for the new surface
+  # @return [Bool] returns true if successful, false if not
+  def sub_surface_create_scaled_subsurfaces_from_surface(surface:, area_fraction:, construction:)
     # Set geometry tolerences:
     geometry_tolerence = 12
     # Get rid of all existing subsurfaces.
-    remove_All_Subsurfaces(surface: surface)
+    remove_all_subsurfaces(surface: surface)
     # Return vertices of smaller surfaces that fit inside this surface.  This is done in case the surface is
     # concave.
 
     # Throw an error if the roof is not flat.
     surface.vertices.each do |surf_vert|
       surface.vertices.each do |surf_vert_2|
-        unless surf_vert_2.z.to_f.round(geometry_tolerence) == surf_vert.z.to_f.round(geometry_tolerence)
-          OpenStudio.logFree(OpenStudio::Error, 'openstudio.model.Model', 'Currently skylights can only be added to buildings with non-plenum flat roofs.')
-        end
+        return OpenStudio.logFree(OpenStudio::Warn, 'openstudio.model.Model', "Currently skylights can only be added to buildings with non-plenum flat roofs.  No skylight added to surface #{surface.name}") if surf_vert_2.z.to_f.round(geometry_tolerence) != surf_vert.z.to_f.round(geometry_tolerence)
       end
     end
     new_surfaces = BTAP::Geometry::Surfaces.make_convex_surfaces(surface: surface, tol: geometry_tolerence)
@@ -287,8 +299,15 @@ class Standard
         # Add the new vertices to an array of vertices.
         new_vertices << new_vertex
       end
+      # Check if the new surface/subsurface is too small to model.  If it is then skip it.
+      new_area = BTAP::Geometry::Surfaces.getSurfaceAreafromVertices(vertices: new_vertices)
+      if new_area < 0.0001
+        OpenStudio.logFree(OpenStudio::Warn, 'openstudio.model.Model', "Attempting to create a subsurface in surface #{surface.name} with an area of #{new_area}m2.  This subsurface is too small so will be skipped")
+        next
+      end
+
       # Create a new subsurface with the vertices determined above.
-      new_sub_surface = OpenStudio::Model::SubSurface.new(new_vertices, model)
+      new_sub_surface = OpenStudio::Model::SubSurface.new(new_vertices, surface.model)
       # Put this sub-surface on the surface.
       new_sub_surface.setSurface(surface)
       # Set the name of the subsurface to be the surface name plus the subsurface type (likely either 'fixedwindow' or
@@ -300,16 +319,22 @@ class Standard
       # Set the skylight type to 'Skylight'
       new_sub_surface.setSubSurfaceType('Skylight')
       # Set the skylight construction to whatever was passed (should be the default skylight construction)
-      new_sub_surface.setConstruction(consturction)
+      new_sub_surface.setConstruction(construction)
       new_sub_surface.setName(new_name)
       # There is now only one surface on the subsurface.  Enforce this
       new_sub_surface.setMultiplier(1)
     end
+    return true
   end
 
   # This just uses applies 'setWindowToWallRatio' method from the OpenStudio SDK.  The only addition is that it changes
   # the name of the window to be the surface name plus the subsurface type (always 'fixedwindow').
-  def set_Window_To_Wall_Ratio_set_name(surface:, area_fraction:, construction:)
+  #
+  # @param surface [OpenStudio::Model::Surface] surface object
+  # @param area_fraction [Double] fraction of area of the larger surface
+  # @param construction [OpenStudio::Model::Construction] construction to use for the new surface
+  # @return [Bool] returns true if successful, false if not
+  def set_window_to_wall_ratio_set_name(surface:, area_fraction:, construction:)
     surface.setWindowToWallRatio(area_fraction)
     surface.subSurfaces.sort.each do |sub_surf|
       sub_surf.setSubSurfaceType('FixedWindow')
@@ -317,11 +342,16 @@ class Standard
       new_name = surface.name.to_s + '_' + sub_surf.subSurfaceType.to_s
       sub_surf.setName(new_name)
     end
+    return true
   end
 
-  # This removes all of the subsurfaces from a surface.  Is a preparation for replaceing windows or clearing doors
-  # before adding windows.
-  def remove_All_Subsurfaces(surface:)
+  # This removes all of the subsurfaces from a surface.
+  # Is a preparation for replaceing windows or clearing doors before adding windows.
+  #
+  # @param surface [OpenStudio::Model::Surface] surface object
+  # @return [Bool] returns true if successful, false if not
+  def remove_all_subsurfaces(surface:)
     surface.subSurfaces.sort.each(&:remove)
+    return true
   end
 end

data/lib/openstudio-standards/standards/Standards.Surface.rb

@@ -3,9 +3,9 @@ class Standard
 
   # Determine the component infiltration rate for this surface
   #
+  # @param surface [OpenStudio::Model::Surface] surface object
   # @param type [String] choices are 'baseline' and 'advanced'
-  # @return [Double] infiltration rate
-  #   @units cubic meters per second (m^3/s)
+  # @return [Double] infiltration rate in cubic meters per second, m^3/s
   # @todo handle floors over unconditioned spaces
   def surface_component_infiltration_rate(surface, type)
     comp_infil_rate_m3_per_s = 0.0
@@ -75,11 +75,21 @@ class Standard
     return comp_infil_rate_m3_per_s
   end
 
-  # Chris Kirney 2018-05-17:  Not complete-do not call.  Start of method meant to help implement NECB2015 8.4.4.5.(5).
-  # The method starts by finding exterior surfaces which help enclose conditioned spaces.  It then removes the
-  # subsurfaces.  Though not implemented yet it was supposed to then put a window centered in the surface with a sill
-  # height and window height defined passed via sill_heght_m and window_height_m (0.9 m, and 1.8 m respectively for
-  # NECB2015).  The width of the window was to be set so that the fdwr matched whatever code said (passed by fdwr).
+  # Start of method meant to help implement NECB2015 8.4.4.5.(5).
+  # The method starts by finding exterior surfaces which help enclose conditioned spaces.
+  # It then removes the subsurfaces.
+  # Though not implemented yet it was supposed to then put a window centered in the surface with a sill
+  # height and window height defined passed via sill_heght_m and window_height_m
+  # (0.9 m, and 1.8 m respectively for NECB2015).
+  # The width of the window was to be set so that the fdwr matched whatever code said (passed by fdwr).
+  # @author Chris Kirney
+  # @note 2018-05-17 not complete-do not call.
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param sill_height_m [Double] sill height in meters
+  # @param window_height_m [Double] window height in meters
+  # @param fdwr [Double] fdwr
+  # @return [Bool] returns true if successful, false if not
   def surface_replace_existing_subsurfaces_with_centered_subsurface(model, sill_height_m, window_height_m, fdwr)
     vertical_surfaces = find_exposed_conditioned_vertical_surfaces(model)
     vertical_surfaces.each do |vertical_surface|
@@ -105,14 +115,22 @@ class Standard
       surface_centroid = vertical_surface.centroid
       surface_normal = vertical_surface.outwardNormal
     end
+    return true
   end
 
-  # Chris Kirney 2018-09-12:  This method searches through a model a returns vertical exterior surfaces which help
+  # This method searches through a model a returns vertical exterior surfaces which help
   # enclose a conditioned space.  It distinguishes between walls adjacent to plenums and wall adjacent to other
   # conditioned spaces (as attics in OpenStudio are considered plenums and conditioned spaces though many would
   # not agree).  It returns a hash of the total exposed wall area adjacent to conditioned spaces (including plenums), the
   # total exposed plenum wall area, the total exposed non-plenum area (adjacent to conditioned spaces), the exposed
   # plenum walls and the exposed non-plenum walls (adjacent to conditioned spaces).
+  # @author Chris Kirney
+  # @note 2018-09-12
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param max_angle [Double] maximum angle to consider surface
+  # @param min_angle [Double] minimum angle to consider surface
+  # @return [Hash] hash of exposed surface information
   def find_exposed_conditioned_vertical_surfaces(model, max_angle: 91, min_angle: 89)
     exposed_surfaces = []
     plenum_surfaces = []
@@ -192,6 +210,9 @@ class Standard
 
   # This method is similar to the 'find_exposed_conditioned_vertical_surfaces' above only it is for roofs.  Again, it
   # distinguishes between plenum and non plenum roof area but collects and returns both.
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @return [Hash] hash of exposed roof information
   def find_exposed_conditioned_roof_surfaces(model)
     exposed_surfaces = []
     plenum_surfaces = []
@@ -264,19 +285,21 @@ class Standard
 
   # This method finds the centroid of the highest roof(s).  It cycles through each space and finds which surfaces are
   # described as roofceiling whose outside boundary condition is outdoors.  Of those surfaces that do it looks for the
-  # highest one(s) and finds the centroid of those.  It returns the following hash:
-  # roof_cent = {
-  #   top_spaces:  array of spaces which contain the highest roofs,
-  #   roof_centroid:  global x, y, and z coords of the centroid of the highest roof surfaces,
-  #   roof_area:  area of the highst roof surfaces}
+  # highest one(s) and finds the centroid of those.
   #
-  # Each element of the top_spaces is a hash containing the following:
-  # top_space = {
-  #   space:  OpenStudio space containing the surface,
-  #   x:  global x coord of the centroid of roof surface(s),
-  #   y:  global y coord of the centroid of roof surface(s),
-  #   z:  global z coord of the centroid of roof surface(s),
-  #   area_m2:  area of the roof surface(s)}
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @return [Hash] It returns the following hash:
+  #   roof_cent = {
+  #     top_spaces:  array of spaces which contain the highest roofs,
+  #     roof_centroid:  global x, y, and z coords of the centroid of the highest roof surfaces,
+  #     roof_area:  area of the highst roof surfaces}
+  #   Each element of the top_spaces is a hash containing the following:
+  #     top_space = {
+  #       space:  OpenStudio space containing the surface,
+  #       x:  global x coord of the centroid of roof surface(s),
+  #       y:  global y coord of the centroid of roof surface(s),
+  #       z:  global z coord of the centroid of roof surface(s),
+  #       area_m2:  area of the roof surface(s)}
   def find_highest_roof_centre(model)
     # Initialize some variables
     tol = 6
@@ -303,7 +326,7 @@ class Standard
       # If no outdoor roofceiling go to the next space.
       next if outdoor_roof == false
 
-      z_Origin = space.zOrigin.to_f
+      z_origin = space.zOrigin.to_f
       ceiling_centroid = [0, 0, 0]
 
       # Go through the surfaces and look for ones that are the highest.  Any that are the highest get added to the
@@ -325,12 +348,12 @@ class Standard
         space: space,
         x: ceiling_centroid[0] + space.xOrigin.to_f,
         y: ceiling_centroid[1] + space.yOrigin.to_f,
-        z: max_surf.centroid.z.to_f + z_Origin,
+        z: max_surf.centroid.z.to_f + z_origin,
         area_m2: ceiling_centroid[2]
       }
       # This is to determine which are the global highest outdoor roofceilings
-      if max_height.round(tol) < (max_surf.centroid.z.to_f + z_Origin).round(tol)
-        max_height = (max_surf.centroid.z.to_f + z_Origin).round(tol)
+      if max_height.round(tol) < (max_surf.centroid.z.to_f + z_origin).round(tol)
+        max_height = (max_surf.centroid.z.to_f + z_origin).round(tol)
       end
     end
     # Go through the roofceilings and find the highest one(s) and calculate the centroid.
@@ -359,8 +382,8 @@ class Standard
   # Calculate a surface's absolute azimuth
   # source: https://github.com/NREL/openstudio-extension-gem/blob/e354355054b83ffc26e3b69befa20d6baf5ef242/lib/openstudio/extension/core/os_lib_geometry.rb#L913
   #
-  # @param surface [OpenStudio::Model:Surface] OpenStudio Surface object
-  # @return [Float] Surface absolute azimuth
+  # @param surface [OpenStudio::Model::Surface] surface object
+  # @return [Double] surface absolute azimuth
   def surface_absolute_azimuth(surface)
     # Get associated space
     space = surface.space.get
@@ -370,9 +393,9 @@ class Standard
 
     # Calculate azimuth
     surface_azimuth_rel_space = OpenStudio.convert(surface.azimuth, 'rad', 'deg').get
-    space_dir_rel_N = space.directionofRelativeNorth
-    building_dir_rel_N = model.getBuilding.northAxis
-    surface_abs_azimuth = surface_azimuth_rel_space + space_dir_rel_N + building_dir_rel_N
+    space_dir_rel_north = space.directionofRelativeNorth
+    building_dir_rel_north = model.getBuilding.northAxis
+    surface_abs_azimuth = surface_azimuth_rel_space + space_dir_rel_north + building_dir_rel_north
     surface_abs_azimuth -= 360.0 until surface_abs_azimuth < 360.0
 
     return surface_abs_azimuth
@@ -380,14 +403,16 @@ class Standard
 
   # Determine a surface absolute cardinal direction
   #
-  # @param surface [OpenStudio::Model::Surface] OpenStudio Surface object
-  # @return [String] Surface absolute cardinal
+  # @param surface [OpenStudio::Model::Surface] surface object
+  # @return [String] surface absolute cardinal direction
   def surface_cardinal_direction(surface)
     # Get the surface's absolute azimuth
     surface_abs_azimuth = surface_absolute_azimuth(surface)
 
     # Determine the surface's cardinal direction
-    if (surface_abs_azimuth >= 0 && surface_abs_azimuth <= 45) || (surface_abs_azimuth > 315 && surface_abs_azimuth <= 360)
+    if surface_abs_azimuth >= 0 && surface_abs_azimuth <= 45
+      return 'N'
+    elsif surface_abs_azimuth > 315 && surface_abs_azimuth <= 360
       return 'N'
     elsif surface_abs_azimuth > 45 && surface_abs_azimuth <= 135
       return 'E'