openstudio-standards 0.2.14 → 0.2.15.pre.rc1

data/lib/openstudio-standards/prototypes/common/objects/Prototype.HeatExchangerAirToAirSensibleAndLatent.rb

@@ -2,12 +2,16 @@ class Standard
   # @!group HeatExchangerAirToAirSensibleAndLatent
 
   # Default fan efficiency assumption for the prm added fan power
+  #
+  # @return [Double] default fan efficiency
   def heat_exchanger_air_to_air_sensible_and_latent_prototype_default_fan_efficiency
     default_fan_efficiency = 0.5
     return default_fan_efficiency
   end
 
   # Sets the motor power to account for the extra fan energy from the increase in fan total static pressure
+  #
+  # @return [Bool] returns true if successful, false if not
   def heat_exchanger_air_to_air_sensible_and_latent_apply_prototype_nominal_electric_power(heat_exchanger_air_to_air_sensible_and_latent)
     # Get the nominal supply air flow rate
     supply_air_flow_m3_per_s = nil
@@ -69,9 +73,11 @@ class Standard
     return true
   end
 
-  # Sets the minimum effectiveness of the heat exchanger per
-  # the DOE prototype assumptions, which assume that an enthalpy wheel is used, which exceeds
-  # the 50% effectiveness minimum actually defined by 90.1.
+  # Sets the minimum effectiveness of the heat exchanger per the DOE prototype assumptions,
+  # which assume that an enthalpy wheel is used, which exceeds the 50% effectiveness minimum actually defined by 90.1.
+  #
+  # @param heat_exchanger_air_to_air_sensible_and_latent [OpenStudio::Model::HeatExchangerAirToAirSensibleAndLatent] hx
+  # @return [Bool] returns true if successful, false if not
   def heat_exchanger_air_to_air_sensible_and_latent_apply_prototype_efficiency(heat_exchanger_air_to_air_sensible_and_latent)
     heat_exchanger_air_to_air_sensible_and_latent.setSensibleEffectivenessat100HeatingAirFlow(0.7)
     heat_exchanger_air_to_air_sensible_and_latent.setLatentEffectivenessat100HeatingAirFlow(0.6)
@@ -86,4 +92,41 @@ class Standard
 
     return true
   end
+
+  # Set sensible and latent effectiveness at 100 and 75 heating and cooling airflow;
+  # The values are calculated by using ERR, which is introduced in 90.1-2016 Addendum CE
+  #
+  # This function is only used for nontransient dwelling units (Mid-rise and High-rise Apartment)
+  # @param heat_exchanger_air_to_air_sensible_and_latent [OpenStudio::Model::HeatExchangerAirToAirSensibleAndLatent] heat exchanger air to air sensible and latent
+  # @param enthalpy_recovery_ratio [String] enthalpy recovery ratio
+  # @param design_conditions [String] enthalpy recovery ratio design conditions: 'heating' or 'cooling'
+  # @param climate_zone [String] climate zone
+  def heat_exchanger_air_to_air_sensible_and_latent_apply_prototype_efficiency_enthalpy_recovery_ratio(heat_exchanger_air_to_air_sensible_and_latent, enthalpy_recovery_ratio, design_conditions, climate_zone)
+    # Assumed to be sensible and latent at all flow
+    if enthalpy_recovery_ratio.nil?
+      full_htg_sens_eff = 0.0
+      full_htg_lat_eff = 0.0
+      part_htg_sens_eff = 0.0
+      part_htg_lat_eff = 0.0
+      full_cool_sens_eff = 0.0
+      full_cool_lat_eff = 0.0
+      part_cool_sens_eff = 0.0
+      part_cool_lat_eff = 0.0
+    else
+      enthalpy_recovery_ratio = enthalpy_recovery_ratio_design_to_typical_adjustment(enthalpy_recovery_ratio, climate_zone)
+      full_htg_sens_eff, full_htg_lat_eff, part_htg_sens_eff, part_htg_lat_eff, full_cool_sens_eff, full_cool_lat_eff, part_cool_sens_eff, part_cool_lat_eff = heat_exchanger_air_to_air_sensible_and_latent_enthalpy_recovery_ratio_to_effectiveness(enthalpy_recovery_ratio, design_conditions)
+    end
+
+    heat_exchanger_air_to_air_sensible_and_latent.setSensibleEffectivenessat100HeatingAirFlow(full_htg_sens_eff)
+    heat_exchanger_air_to_air_sensible_and_latent.setLatentEffectivenessat100HeatingAirFlow(full_htg_lat_eff)
+    heat_exchanger_air_to_air_sensible_and_latent.setSensibleEffectivenessat75HeatingAirFlow(part_htg_sens_eff)
+    heat_exchanger_air_to_air_sensible_and_latent.setLatentEffectivenessat75HeatingAirFlow(part_htg_lat_eff)
+    heat_exchanger_air_to_air_sensible_and_latent.setSensibleEffectivenessat100CoolingAirFlow(full_cool_sens_eff)
+    heat_exchanger_air_to_air_sensible_and_latent.setLatentEffectivenessat100CoolingAirFlow(full_cool_lat_eff)
+    heat_exchanger_air_to_air_sensible_and_latent.setSensibleEffectivenessat75CoolingAirFlow(part_cool_sens_eff)
+    heat_exchanger_air_to_air_sensible_and_latent.setLatentEffectivenessat75CoolingAirFlow(part_cool_lat_eff)
+
+    OpenStudio.logFree(OpenStudio::Info, 'openstudio.standards.HeatExchangerSensLat', "For #{heat_exchanger_air_to_air_sensible_and_latent.name}: Set sensible and latent effectiveness calculated by using ERR.")
+    return true
+  end
 end

data/lib/openstudio-standards/prototypes/common/objects/Prototype.Model.elevators.rb

@@ -1,11 +1,10 @@
 class Standard
   # Add an elevator the the specified space
   #
-  # @param space [OpenStudio::Model::Space] the space
-  # to assign the elevators to.
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param space [OpenStudio::Model::Space] the space that contains the elevators
   # @param number_of_elevators [Integer] the number of elevators
-  # @param elevator_type [String] valid choices are
-  # Traction, Hydraulic
+  # @param elevator_type [String] valid choices are Traction, Hydraulic
   # @param elevator_schedule [String] the name of the elevator schedule
   # @param elevator_fan_schedule [String] the name of the elevator fan schedule
   # @param elevator_lights_schedule [String] the name of the elevator lights schedule
@@ -99,11 +98,13 @@ class Standard
     return elevator_equipment
   end
 
-  # Determines the power required by an individual elevator
-  # of a given type.  Defaults to the values used by the DOE
-  # prototype buildings.
-  # @param elevator_type [String] valid choices are
-  # Traction, Hydraulic
+  # Determines the power required by an individual elevator of a given type.
+  # Defaults to the values used by the DOE prototype buildings.
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param elevator_type [String] valid choices are Traction, Hydraulic
+  # @param building_type [String] the building type
+  # @return [Double] lift power in watts
   def model_elevator_lift_power(model, elevator_type, building_type)
     lift_pwr_w = 0
     if elevator_type == 'Traction'
@@ -118,19 +119,23 @@ class Standard
     return lift_pwr_w
   end
 
-  # Determines the percentage of the elevator cab
-  # lighting that is incandescent.  The remainder
-  # is assumed to be LED.  Defaults to 70% incandescent,
-  # representing older elevators.
+  # Determines the percentage of the elevator cab lighting that is incandescent.
+  # The remainder is assumed to be LED.
+  # Defaults to 70% incandescent, representing older elevators.
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @return [Double] incandescent lighting percentage
   def model_elevator_lighting_pct_incandescent(model)
     pct_incandescent = 0.7
     return pct_incandescent
   end
 
   # Determines the power of the elevator ventilation fan.
-  # Defaults to 90.1-2010, which had no requirement
-  # for ventilation fan efficiency.
-  # @return [Double] the ventilation fan power (W)
+  # Defaults to 90.1-2010, which had no requirement for ventilation fan efficiency.
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param vent_rate_cfm [Double] the ventilation rate in ft^3/min
+  # @return [Double] the ventilation fan power in watts
   def model_elevator_fan_pwr(model, vent_rate_cfm)
     vent_pwr_per_flow_w_per_cfm = 0.33
     vent_pwr_w = vent_pwr_per_flow_w_per_cfm * vent_rate_cfm
@@ -138,17 +143,17 @@ class Standard
     return vent_pwr_w
   end
 
-  # Add elevators to the model based on the building size,
-  # number of stories, and building type.  Logic was derived
-  # from the DOE prototype buildings.
+  # Add elevators to the model based on the building size, number of stories, and building type.
+  # Logic was derived from the DOE prototype buildings.
   #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
   # @return [OpenStudio::Model::ElectricEquipment] the resulting elevator
   def model_add_elevators(model)
     # determine effective number of stories
     effective_num_stories = model_effective_num_stories(model)
 
     # determine elevator type
-    # todo - add logic here or upstream to have some multi-story buildings without elevators (e.g. small multi-family and small hotels)
+    # todo add logic here or upstream to have some multi-story buildings without elevators (e.g. small multi-family and small hotels)
     if effective_num_stories[:below_grade] + effective_num_stories[:above_grade] < 2
       OpenStudio.logFree(OpenStudio::Info, 'openstudio.prototype.elevators', 'The building only has 1 story, no elevators will be added.')
       return nil # don't add elevators
@@ -395,10 +400,10 @@ class Standard
     end
     elevator_fan_schedule = fan_sch.name.to_s
 
-    # TODO: - currently add elevator doesn't allow me to choose the size of the elevator?
+    # @todo currently add elevator doesn't allow me to choose the size of the elevator?
     # ref bldg pdf has formula for motor hp based on weight, speed, counterweight fraction and mech eff (in 5.1.4)
 
-    # TODO: - should schedules change based on traction vs. hydraulic vs. just taking what is in prototype.
+    # @todo should schedules change based on traction vs. hydraulic vs. just taking what is in prototype.
 
     # call add_elevator in Prototype.hvac_systems.rb to create elevator objects
     elevator = model_add_elevator(model,

data/lib/openstudio-standards/prototypes/common/objects/Prototype.Model.exterior_lights.rb

@@ -1,9 +1,13 @@
 class Standard
   # Add exterior lighting to the model
   #
-  # @param exterior_lighting_zone_number [Integer] Valid choices are
-  # @return [Hash] the resulting exterior lights
-  # @todo - would be nice to add argument for some building types (SmallHotel, MidriseApartment, PrimarySchool, SecondarySchool, RetailStripmall) if it has interior or exterior circulation.
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param exterior_lighting_zone_number [Integer] exterior lighting zone number, 0-4
+  # @param onsite_parking_fraction [Double] onsite parking fraction, 0-1
+  # @param add_base_site_allowance [Bool] whether to include the base site allowance
+  # @param use_model_for_entries_and_canopies [Bool] use building geometry for number of entries and canopy size
+  # @return [Hash] a hash of OpenStudio::Model::ExteriorLights objects
+  # @todo would be nice to add argument for some building types (SmallHotel, MidriseApartment, PrimarySchool, SecondarySchool, RetailStripmall) if it has interior or exterior circulation.
   def model_add_typical_exterior_lights(model, exterior_lighting_zone_number, onsite_parking_fraction = 1.0, add_base_site_allowance = false, use_model_for_entries_and_canopies = false)
     exterior_lights = {}
     installed_power = 0.0
@@ -243,7 +247,7 @@ class Standard
       installed_power += power * multiplier
     end
 
-    # TODO: - add_base_site_lighting_allowance (non landscaping tradable lighting)
+    # @todo - add_base_site_lighting_allowance (non landscaping tradable lighting)
     # add exterior lights for drive through windows
     if add_base_site_allowance
 
@@ -278,11 +282,14 @@ class Standard
     return exterior_lights
   end
 
-  # get exterior lighting area's, distances, and counts
+  # get exterior lighting areas, distances, and counts
   #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param space_type_hash [Hash] hash of space types
+  # @param use_model_for_entries_and_canopies [Bool] use building geometry for number of entries and canopy size
   # @return [hash] hash of exterior lighting value types and building type and model specific values
-  # @todo - add code in to determine number of entries and canopy area from model geoemtry
-  # @todo - come up with better logic for entry widths
+  # @todo add code in to determine number of entries and canopy area from model geoemtry
+  # @todo come up with better logic for entry widths
   def model_create_exterior_lighting_area_length_count_hash(model, space_type_hash, use_model_for_entries_and_canopies)
     # populate building_type_hashes from space_type_hash
     building_type_hashes = {}
@@ -365,7 +372,7 @@ class Standard
 
       # calculate door, window, and canopy length properties for exterior lighting
       if use_model_for_entries_and_canopies
-        # TODO: - get number of entries and canopy size from model geometry
+        # @todo get number of entries and canopy size from model geometry
       else
 
         # main entries

data/lib/openstudio-standards/prototypes/common/objects/Prototype.Model.hvac.rb

@@ -1,5 +1,12 @@
 class Standard
-  def model_add_hvac(model, building_type, climate_zone, prototype_input, epw_file)
+  # Adds the prototype HVAC system to the 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_add_hvac(model, building_type, climate_zone, prototype_input)
     OpenStudio.logFree(OpenStudio::Info, 'openstudio.model.Model', 'Started Adding HVAC')
 
     # Get the list of HVAC systems, as defined for each building in the Prototype.building_name files
@@ -132,9 +139,9 @@ class Standard
         # Special logic to make a heat pump loop if necessary
         heat_pump_loop = nil
         if system['heating_type'] == 'Water To Air Heat Pump'
-          # @code_sections [90.1-2016_6.5.5.2.1]
+          # @note code_sections [90.1-2016_6.5.5.2.1]
           # change highrise apartment heat rejection fan (< 5hp) from single speed to two speed evaporative fluid cooler
-          # TODO: this is temporary fix, it should be applied to all heat rejection devices smaller than 5hp.
+          # @todo this is temporary fix, it should be applied to all heat rejection devices smaller than 5hp.
           if system['heat_pump_loop_cooling_type'].nil?
             hp_loop_cooling_type = 'EvaporativeFluidCooler'
           else
@@ -486,8 +493,9 @@ class Standard
     return true
   end
 
-  # Determine the typical system type given the inputs.
+  # Determine the typical system type given the inputs
   #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
   # @param area_type [String] Valid choices are residential and nonresidential
   # @param delivery_type [String] Conditioning delivery type. Valid choices are air and hydronic
   # @param heating_source [String] Valid choices are Electricity, NaturalGas, DistrictHeating, DistrictAmbient
@@ -553,6 +561,11 @@ class Standard
 
   private
 
+  # returns the thermal zones served by the system
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param system [Hash] hash of system inputs
+  # @return [Array<OpenStudio::Model::ThermalZone>] system thermal zones
   def model_get_zones_from_spaces_on_system(model, system)
     # Find all zones associated with these spaces
     thermal_zones = []
@@ -574,6 +587,11 @@ class Standard
     return thermal_zones
   end
 
+  # returns the thermal zone that serves as the return plenum
+  #
+  # @param model [OpenStudio::Model::Model] OpenStudio model object
+  # @param system [Hash] hash of system inputs
+  # @return [OpenStudio::Model::ThermalZone] the return plenum thermal zone
   def model_get_return_plenum_from_system(model, system)
     # Find the zone associated with the return plenum space name
     return_plenum = nil