openstudio-standards 0.2.14 → 0.2.15.pre.rc1

data/lib/openstudio-standards/prototypes/common/buildings/Prototype.TallBuilding.rb

@@ -1,12 +1,18 @@
 # Custom changes for the TallBuilding prototype.
-# These are changes that are inconsistent with other prototype
-# building types.
+# These are changes that are inconsistent with other prototype building types.
 module TallBuilding
-  def model_custom_hvac_tweaks(building_type, climate_zone, prototype_input, model)
+  # hvac adjustments specific to the prototype model
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param building_type [string] the building type
+  # @param climate_zone [String] ASHRAE climate zone, e.g. 'ASHRAE 169-2013-4A'
+  # @param prototype_input [Hash] hash of prototype inputs
+  # @return [Bool] returns true if successful, false if not
+  def model_custom_hvac_tweaks(model, building_type, climate_zone, prototype_input)
     OpenStudio.logFree(OpenStudio::Info, 'openstudio.model.Model', 'Started building type specific adjustments')
 
-    # TODO: make additional parameters mutable by the user
-    # the number of floors for each function type is defined in additional_params
+    # @todomake additional parameters mutable by the user
+    #   the number of floors for each function type is defined in additional_params
     additional_params = {
       num_of_floor_retail: 2,
       num_of_floor_office: 18,
@@ -20,9 +26,9 @@ module TallBuilding
     # for tall and super tall buildings, add main (multiple) and booster swh here instead of model_add_swh
     add_swh_tall_bldg(model, prototype_input, additional_params)
 
-    # # update the infiltration coefficients of tall buildings based on Lisa Ng's research (from NIST)
-    # # The set of coefficients are not quite appropriate for tall buildings, leading to super high infiltration rate
-    # # TODO: further infiltration research is needed
+    # update the infiltration coefficients of tall buildings based on Lisa Ng's research (from NIST)
+    # The set of coefficients are not quite appropriate for tall buildings, leading to super high infiltration rate
+    # @todo further infiltration research is needed
     # update_infil_coeff(model)
 
     # apply vertical weather variations to tall buildings
@@ -36,12 +42,15 @@ module TallBuilding
     return true
   end
 
-  # Add elevators to elevator machine room
-  # schedules:
+  # Add elevators to elevator machine room schedules:
   # Large Office BLDG ELEVATORS, OfficeLarge ELEV_LIGHT_FAN_SCH_ADD_DF
   # HotelLarge BLDG_ELEVATORS, HotelLarge ELEV_LIGHT_FAN_SCH_ADD_DF
   # ApartmentMidRise BLDG_ELEVATORS, ApartmentMidRise ELEV_LIGHT_FAN_SCH_24_7
   # Retail elevator schedule developed
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param additional_params [Hash] hash of additional parameters
+  # @return [Bool] returns true if successful, false if not
   def add_elevator_system_loads(model, additional_params)
     # get the elevator machine room space from the model
     if model.getSpaceTypeByName('Elevator Machine Room').empty?
@@ -84,8 +93,20 @@ module TallBuilding
                        'ApartmentMidRise BLDG_ELEVATORS', 'ApartmentHighRise ELEV_LIGHT_FAN_SCH_24_7')
     add_elevator_equip(model, elev_mc_room, num_elev_hotel, 'Hotel', motor_power_per_elev, fan_light_power_per_elev,
                        'HotelLarge BLDG_ELEVATORS', 'HotelLarge ELEV_LIGHT_FAN_SCH_24_7')
+    return true
   end
 
+  # adds elevator equipment to space
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param space [OpenStudio::Model::Space] OpenStudio space object
+  # @param num_of_elev [Double] number of elevators
+  # @param function_type [String] function type
+  # @param motor_power_per_elev [Double] elevator motor power in watts
+  # @param fan_light_power_per_elev [Double] elevator fan power in watts
+  # @param elev_power_sch_name [String] schedule to use for the elevator motor
+  # @param elev_fan_light_sch_name [String] schedule to use for the elevator fan
+  # @return [Bool] returns true if successful, false if not
   def add_elevator_equip(model, space, num_of_elev, function_type, motor_power_per_elev, fan_light_power_per_elev,
                          elev_power_sch_name, elev_fan_light_sch_name)
     motor_equip_frac_loss = 0.85
@@ -117,9 +138,15 @@ module TallBuilding
     elevator_fan_sch = model_add_schedule(model, elev_fan_light_sch_name)
     elevator_fan_equipment.setSchedule(elevator_fan_sch)
     elevator_fan_equipment.setSpace(space)
+    return true
   end
 
   # for tall and super tall buildings, add main (multiple) and booster swh in model_custom_hvac_tweaks
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param prototype_input [Hash] hash of prototype inputs
+  # @param additional_params [Hash] hash of additional parameters
+  # @return [Bool] returns true if successful, false if not
   def add_swh_tall_bldg(model, prototype_input, additional_params)
     # get all building stories and rank based on Z-origin
     story_info = {}
@@ -261,9 +288,13 @@ module TallBuilding
                              OpenStudio.convert(prototype_input['laundry_water_use_temperature'], 'F', 'C').get,
                              nil)
     end
+    return true
   end
 
   # update the infiltration coefficients of tall buildings based on Lisa Ng's research (from NIST)
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @return [Bool] returns true if successful, false if not
   def update_infil_coeff(model)
     #       System On  | System Off
     #  A: -0.03973203 | 0
@@ -324,22 +355,30 @@ module TallBuilding
         infiltration_hvac_off.setVelocitySquaredTermCoefficient(coeff_d_off)
       end
     end
+    return true
   end
 
   # apply vertical weather variations to tall buildings
   # current method is using the E+ default variation trend by specifying the height of outdoor air nodes
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @return [Bool] returns true if successful, false if not
   def apply_vertical_weather_variation(model)
-    # OA node height is not implemented OpenStudio yet.
-    # Temporary fix to be done via adding EnergyPlus measure.
+    # @todo OA node height is not implemented OpenStudio yet.
+    # @todo Temporary fix to be done via adding EnergyPlus measure.
     # model.getAirLoopHVACOutdoorAirSystems.each do |oa_system|
     #   # get the outdoor air system outdoor air node
     #   oa_node = oa_system.outdoorAirModelObject.get.to_Node.get
     #   # get the height of the plenum if any, assign to outdoor air node
     #
     # end
+    return true
   end
 
   # HighriseApartment doesn't apply thermostat to corridor spaces
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @return [Bool] returns true if successful, false if not
   def add_thermostat_to_corridor(model)
     thermostat = OpenStudio::Model::ThermostatSetpointDualSetpoint.new(model)
     thermostat.setName('HighriseApartment Corridor Thermostat')
@@ -356,18 +395,32 @@ module TallBuilding
         end
       end
     end
+    return true
   end
 
+  # swh adjustments specific to the prototype model
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param building_type [string] the building type
+  # @param climate_zone [String] ASHRAE climate zone, e.g. 'ASHRAE 169-2013-4A'
+  # @param prototype_input [Hash] hash of prototype inputs
+  # @return [Bool] returns true if successful, false if not
   def model_custom_swh_tweaks(model, building_type, climate_zone, prototype_input)
     # customized swh system is not added here, but in model_custom_hvac_tweaks instead
     # because model_custom_swh_tweaks is performed in Prototype.Model after efficiency assignment. If swh added here, efficiency can't be updated.
     # this can't be moved upwards in Prototype.Model as it will affect other building types (e.g. SmallOfficeDetailed, LargeOfficeDetailed).
-
     return true
   end
 
-  def model_custom_geometry_tweaks(building_type, climate_zone, prototype_input, model)
-    # TODO: make additional parameters mutable by the user
+  # geometry adjustments specific to the prototype model
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param building_type [string] the building type
+  # @param climate_zone [String] ASHRAE climate zone, e.g. 'ASHRAE 169-2013-4A'
+  # @param prototype_input [Hash] hash of prototype inputs
+  # @return [Bool] returns true if successful, false if not
+  def model_custom_geometry_tweaks(model, building_type, climate_zone, prototype_input)
+    # @todo make additional parameters mutable by the user
     # the number of floors for each function type is defined in additional_params
     additional_params = {
       num_of_floor_retail: 2,
@@ -800,6 +853,11 @@ module TallBuilding
     return true
   end
 
+  # generate input json based on input parameters
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param additional_params [Hash] hash of additional parameters
+  # @return [Json] json file
   def generate_new_json(model, additional_params)
     new_json = []
 
@@ -947,6 +1005,10 @@ module TallBuilding
     return JSON.pretty_generate(new_json)
   end
 
+  # generate multipler list from number of floors
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @return [Array<Double>] mutiplier list
   def get_multiplier_list(num_floors)
     a = (num_floors.to_f / 10).ceil #  a = (25.0/10).ceil => 3
     return num_floors if a == 1
@@ -968,6 +1030,12 @@ module TallBuilding
     return multiplier_list
   end
 
+  # adjust space boundary conditions to adiabatic
+  #
+  # @param space [OpenStudio::Model::Space] OpenStudio space object
+  # @param if_top_story_floor_adiabatic [Bool] flag if top floor is adiabatic
+  # @param if_ground_story_plenum_adiabatic [Bool] flag if ground story plenum is adiabatic
+  # @return [Bool] returns true if successful, false if not
   def update_space_outside_boundary_to_adiabatic(space, if_top_story_floor_adiabatic: false, if_ground_story_plenum_adiabatic: false)
     if (space.name.to_s.include? 'Plenum') && !if_top_story_floor_adiabatic
       space.surfaces.each do |surface|
@@ -997,8 +1065,21 @@ module TallBuilding
         end
       end
     end
+    return true
   end
 
+  # copies a building story
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param original_story [OpenStudio::Model::BuildingStory] OpenStudio building story object
+  # @param multiplier [Double] multipler for number of stories
+  # @param new_z_origin [Double] new z origin height in meters
+  # @param f_to_c_height [Double] floor to ceiling height in meters
+  # @param f_to_f_height [Double] floor to floor height in meters
+  # @param current_story [OpenStudio::Model::BuildingStory] OpenStudio building story object
+  # @param if_top_story_floor_adiabatic [Bool] flag if top floor is adiabatic
+  # @param if_ground_story_plenum_adiabatic [Bool] flag if ground story plenum is adiabatic
+  # @return [Bool] returns true if successful, false if not
   def deep_copy_story(model, original_story, multiplier, new_z_origin, f_to_c_height, f_to_f_height, current_story, if_top_story_floor_adiabatic: false, if_ground_story_plenum_adiabatic: false)
     # clone the story
     new_story = original_story.clone(model).to_BuildingStory.get
@@ -1043,5 +1124,6 @@ module TallBuilding
         update_space_outside_boundary_to_adiabatic(new_space, if_top_story_floor_adiabatic: if_top_story_floor_adiabatic, if_ground_story_plenum_adiabatic: if_ground_story_plenum_adiabatic)
       end
     end
+    return true
   end
 end

data/lib/openstudio-standards/prototypes/common/buildings/Prototype.Warehouse.rb

@@ -1,182 +1,40 @@
 # Custom changes for the Warehouse prototype
-
-# These are changes that are inconsistent with other prototype
-# building types.
+# These are changes that are inconsistent with other prototype building types.
 module Warehouse
-  def model_custom_hvac_tweaks(building_type, climate_zone, prototype_input, model)
+  # hvac adjustments specific to the prototype model
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param building_type [string] the building type
+  # @param climate_zone [String] ASHRAE climate zone, e.g. 'ASHRAE 169-2013-4A'
+  # @param prototype_input [Hash] hash of prototype inputs
+  # @return [Bool] returns true if successful, false if not
+  def model_custom_hvac_tweaks(model, building_type, climate_zone, prototype_input)
     return true
   end
 
+  # swh adjustments specific to the prototype model
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param building_type [string] the building type
+  # @param climate_zone [String] ASHRAE climate zone, e.g. 'ASHRAE 169-2013-4A'
+  # @param prototype_input [Hash] hash of prototype inputs
+  # @return [Bool] returns true if successful, false if not
   def model_custom_swh_tweaks(model, building_type, climate_zone, prototype_input)
     return true
   end
 
   def model_custom_daylighting_tweaks(building_type, climate_zone, prototype_input, model)
-    OpenStudio.logFree(OpenStudio::Info, 'openstudio.model.Model', 'Adjusting daylight sensor positions and fractions')
-
-    adjustments = case climate_zone
-    when 'ASHRAE 169-2006-6A',
-'ASHRAE 169-2006-6B',
-'ASHRAE 169-2006-7A',
-'ASHRAE 169-2006-8A',
-'ASHRAE 169-2013-6A',
-'ASHRAE 169-2013-6B',
-'ASHRAE 169-2013-7A',
-'ASHRAE 169-2013-8A'
-      [
-        { '90.1-2010' => { 'Zone3 Bulk Storage' => { 'sensor_1_frac' => 0.116,
-                                                     'sensor_1_xyz' => [6.096, 45.718514, 0] },
-                           'Zone1 Office' => { 'sensor_1_frac' => 0.11,
-                                               'sensor_2_frac' => 0.11,
-                                               'sensor_1_xyz' => [2.4384, 2.4384, 0.762],
-                                               'sensor_2_xyz' => [20.4216, 1.6154, 0.762] } },
-          '90.1-2013' => { 'Zone3 Bulk Storage' => { 'sensor_1_frac' => 0.116,
-                                                     'sensor_1_xyz' => [6.096, 45.718514, 0] },
-                           'Zone1 Office' => { 'sensor_1_frac' => 0.29,
-                                               'sensor_2_frac' => 0.1,
-                                               'sensor_1_xyz' => [3.2675, 4.5718, 0.762],
-                                               'sensor_2_xyz' => [20.4216, 4.5718, 0.762] } },
-          '90.1-2016' => { 'Zone3 Bulk Storage' => { 'sensor_1_frac' => 0.116,
-                                                     'sensor_1_xyz' => [6.096, 45.718514, 0] },
-                           'Zone1 Office' => { 'sensor_1_frac' => 0.29,
-                                               'sensor_2_frac' => 0.1,
-                                               'sensor_1_xyz' => [3.2675, 4.5718, 0.762],
-                                               'sensor_2_xyz' => [20.4216, 4.5718, 0.762] } },
-          '90.1-2019' => { 'Zone3 Bulk Storage' => { 'sensor_1_frac' => 0.116,
-                                                     'sensor_1_xyz' => [6.096, 45.718514, 0] },
-                           'Zone1 Office' => { 'sensor_1_frac' => 0.29,
-                                               'sensor_2_frac' => 0.1,
-                                               'sensor_1_xyz' => [3.2675, 4.5718, 0.762],
-                                               'sensor_2_xyz' => [20.4216, 4.5718, 0.762] } } }
-      ]
-    else
-      [
-        { '90.1-2010' => { 'Zone3 Bulk Storage' => { 'sensor_1_frac' => 0.25,
-                                                     'sensor_2_frac' => 0.25,
-                                                     'sensor_1_xyz' => [22.9, 48, 0],
-                                                     'sensor_2_xyz' => [22.9, 34.7, 0] },
-                           'Zone2 Fine Storage' => { 'sensor_1_frac' => 0.25,
-                                                     'sensor_2_frac' => 0.25,
-                                                     'sensor_1_xyz' => [27.8892, 24.9936, 0.762],
-                                                     'sensor_2_xyz' => [3.81, 24.9936, 0.762] } },
-          '90.1-2013' => { 'Zone1 Office' => { 'sensor_1_frac' => 0.29,
-                                               'sensor_2_frac' => 0.1,
-                                               'sensor_1_xyz' => [3.2675, 4.5718, 0.762],
-                                               'sensor_2_xyz' => [20.4216, 4.5718, 0.762] },
-                           'Zone3 Bulk Storage' => { 'sensor_1_frac' => 0.25,
-                                                     'sensor_2_frac' => 0.25,
-                                                     'sensor_1_xyz' => [22.9, 48, 0],
-                                                     'sensor_2_xyz' => [22.9, 34.7, 0] },
-                           'Zone2 Fine Storage' => { 'sensor_1_frac' => 0.25,
-                                                     'sensor_2_frac' => 0.25,
-                                                     'sensor_1_xyz' => [27.8892, 24.9936, 0.762],
-                                                     'sensor_2_xyz' => [3.81, 24.9936, 0.762] } },
-          '90.1-2016' => { 'Zone1 Office' => { 'sensor_1_frac' => 0.29,
-                                               'sensor_2_frac' => 0.1,
-                                               'sensor_1_xyz' => [3.2675, 4.5718, 0.762],
-                                               'sensor_2_xyz' => [20.4216, 4.5718, 0.762] },
-                           'Zone3 Bulk Storage' => { 'sensor_1_frac' => 0.25,
-                                                     'sensor_2_frac' => 0.25,
-                                                     'sensor_1_xyz' => [22.9, 48, 0],
-                                                     'sensor_2_xyz' => [22.9, 34.7, 0] },
-                           'Zone2 Fine Storage' => { 'sensor_1_frac' => 0.25,
-                                                     'sensor_2_frac' => 0.25,
-                                                     'sensor_1_xyz' => [27.8892, 24.9936, 0.762],
-                                                     'sensor_2_xyz' => [3.81, 24.9936, 0.762] } },
-          '90.1-2019' => { 'Zone1 Office' => { 'sensor_1_frac' => 0.29,
-                                               'sensor_2_frac' => 0.1,
-                                               'sensor_1_xyz' => [3.2675, 4.5718, 0.762],
-                                               'sensor_2_xyz' => [20.4216, 4.5718, 0.762] },
-                           'Zone3 Bulk Storage' => { 'sensor_1_frac' => 0.25,
-                                                     'sensor_2_frac' => 0.25,
-                                                     'sensor_1_xyz' => [22.9, 48, 0],
-                                                     'sensor_2_xyz' => [22.9, 34.7, 0] },
-                           'Zone2 Fine Storage' => { 'sensor_1_frac' => 0.25,
-                                                     'sensor_2_frac' => 0.25,
-                                                     'sensor_1_xyz' => [27.8892, 24.9936, 0.762],
-                                                     'sensor_2_xyz' => [3.81, 24.9936, 0.762] } } }
-      ]
-end
-
-    # Adjust daylight sensors in each space
-    model.getSpaces.each do |space|
-      if adjustments[0].keys.include? template
-        if adjustments[0][template].keys.include? space.name.to_s
-          adj = adjustments[0][template][space.name.to_s]
-          next if space.thermalZone.empty?
-
-          zone = space.thermalZone.get
-          next if space.spaceType.empty?
-
-          spc_type = space.spaceType.get
-          next if spc_type.standardsSpaceType.empty?
-
-          stds_spc_type = spc_type.standardsSpaceType.get
-          # Adjust the primary sensor
-          if adj['sensor_1_frac']
-            # Create primary sensor if it doesn't exist
-            if !zone.primaryDaylightingControl.is_initialized
-              puts zone
-              sensor_1 = OpenStudio::Model::DaylightingControl.new(space.model)
-              sensor_1.setName("#{space.name} Daylt Sensor 2")
-              sensor_1.setSpace(space)
-              sensor_1.setIlluminanceSetpoint(375)
-              sensor_1.setLightingControlType('Stepped')
-              sensor_1.setNumberofSteppedControlSteps(3) # all sensors 3-step per design
-              sensor_1.setMinimumInputPowerFractionforContinuousDimmingControl(0.3)
-              sensor_1.setMinimumLightOutputFractionforContinuousDimmingControl(0.2)
-              sensor_1.setProbabilityLightingwillbeResetWhenNeededinManualSteppedControl(1.0)
-              sensor_1.setMaximumAllowableDiscomfortGlareIndex(22.0)
-              zone.setPrimaryDaylightingControl(sensor_1)
-            end
-            OpenStudio.logFree(OpenStudio::Info, 'openstudio.model.Model', "For #{zone.name}: Adjusting primary daylight sensor to control #{adj['sensor_1_frac']} of the lighting.")
-            zone.setFractionofZoneControlledbyPrimaryDaylightingControl(adj['sensor_1_frac'])
-            pri_ctrl = zone.primaryDaylightingControl.get
-            if adj['sensor_1_xyz']
-              x = adj['sensor_1_xyz'][0]
-              y = adj['sensor_1_xyz'][1]
-              z = adj['sensor_1_xyz'][2]
-              OpenStudio.logFree(OpenStudio::Info, 'openstudio.model.Model', "For #{zone.name}: Adjusting primary daylight sensor position to [#{x}, #{y}, #{z}].")
-              pri_ctrl.setPositionXCoordinate(x)
-              pri_ctrl.setPositionYCoordinate(y)
-              pri_ctrl.setPositionZCoordinate(z)
-            end
-          end
-          # Adjust the secondary sensor
-          if adj['sensor_2_frac']
-            # Create second sensor if it doesn't exist
-            if !zone.secondaryDaylightingControl.is_initialized
-              sensor_2 = OpenStudio::Model::DaylightingControl.new(space.model)
-              sensor_2.setName("#{space.name} Daylt Sensor 2")
-              sensor_2.setSpace(space)
-              sensor_2.setIlluminanceSetpoint(375)
-              sensor_2.setLightingControlType('Stepped')
-              sensor_2.setNumberofSteppedControlSteps(3) # all sensors 3-step per design
-              sensor_2.setMinimumInputPowerFractionforContinuousDimmingControl(0.3)
-              sensor_2.setMinimumLightOutputFractionforContinuousDimmingControl(0.2)
-              sensor_2.setProbabilityLightingwillbeResetWhenNeededinManualSteppedControl(1.0)
-              sensor_2.setMaximumAllowableDiscomfortGlareIndex(22.0)
-              zone.setSecondaryDaylightingControl(sensor_2)
-            end
-            OpenStudio.logFree(OpenStudio::Info, 'openstudio.model.Model', "For #{zone.name}: Adjusting secondary daylight sensor to control #{adj['sensor_2_frac']} of the lighting.")
-            zone.setFractionofZoneControlledbySecondaryDaylightingControl(adj['sensor_2_frac'])
-            sec_ctrl = zone.secondaryDaylightingControl.get
-            if adj['sensor_2_xyz']
-              x = adj['sensor_2_xyz'][0]
-              y = adj['sensor_2_xyz'][1]
-              z = adj['sensor_2_xyz'][2]
-              OpenStudio.logFree(OpenStudio::Info, 'openstudio.model.Model', "For #{zone.name}: Adjusting secondary daylight sensor position to [#{x}, #{y}, #{z}].")
-              sec_ctrl.setPositionXCoordinate(x)
-              sec_ctrl.setPositionYCoordinate(y)
-              sec_ctrl.setPositionZCoordinate(z)
-            end
-          end
-        end
-      end
-    end
+    return true
   end
 
-  def model_custom_geometry_tweaks(building_type, climate_zone, prototype_input, model)
+  # geometry adjustments specific to the prototype model
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param building_type [string] the building type
+  # @param climate_zone [String] ASHRAE climate zone, e.g. 'ASHRAE 169-2013-4A'
+  # @param prototype_input [Hash] hash of prototype inputs
+  # @return [Bool] returns true if successful, false if not
+  def model_custom_geometry_tweaks(model, building_type, climate_zone, prototype_input)
     # Set original building North axis
     model_set_building_north_axis(model, 90.0)
 
@@ -220,6 +78,7 @@ end
 
   # Get building door information to update infiltration
   #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
   # return [Hash] Door infiltration information
   def get_building_door_info(model)
     # Get Bulk storage space infiltration schedule name