Merge pull request #1840 from NREL/ruby-docs

More ruby documentation; prototype general model.rb add methods
NREL · Sep 30, 2024 · 54ca3ac · 54ca3ac
2 parents 69b9cb7 + f0f502e
commit 54ca3ac
Show file tree

Hide file tree

Showing 48 changed files with 5,735 additions and 4,205 deletions.
diff --git a/BuildResidentialHPXML/README.md b/BuildResidentialHPXML/README.md
@@ -3732,7 +3732,7 @@ The location of water heater. If not provided, the OS-HPXML default (see <a href
 
 **Water Heater: Tank Volume**
 
-Nominal volume of water heater tank. Only applies to storage water heater, heat pump water heater, and space-heating boiler with storage tank. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#conventional-storage'>Conventional Storage</a>, <a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#heat-pump'>Heat Pump</a>, <a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#combi-boiler-w-storage'>Combi Boiler w/ Storage</a>) is used.
+Nominal volume of water heater tank. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#conventional-storage'>Conventional Storage</a>, <a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#heat-pump'>Heat Pump</a>, <a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#combi-boiler-w-storage'>Combi Boiler w/ Storage</a>) is used.
 
 - **Name:** ``water_heater_tank_volume``
 - **Type:** ``Double``

diff --git a/BuildResidentialHPXML/measure.rb b/BuildResidentialHPXML/measure.rb
@@ -2244,7 +2244,7 @@ def arguments(model) # rubocop:disable Lint/UnusedMethodArgument
 
     arg = OpenStudio::Measure::OSArgument::makeDoubleArgument('water_heater_tank_volume', false)
     arg.setDisplayName('Water Heater: Tank Volume')
-    arg.setDescription("Nominal volume of water heater tank. Only applies to #{HPXML::WaterHeaterTypeStorage}, #{HPXML::WaterHeaterTypeHeatPump}, and #{HPXML::WaterHeaterTypeCombiStorage}. If not provided, the OS-HPXML default (see <a href='#{docs_base_url}#conventional-storage'>Conventional Storage</a>, <a href='#{docs_base_url}#heat-pump'>Heat Pump</a>, <a href='#{docs_base_url}#combi-boiler-w-storage'>Combi Boiler w/ Storage</a>) is used.")
+    arg.setDescription("Nominal volume of water heater tank. If not provided, the OS-HPXML default (see <a href='#{docs_base_url}#conventional-storage'>Conventional Storage</a>, <a href='#{docs_base_url}#heat-pump'>Heat Pump</a>, <a href='#{docs_base_url}#combi-boiler-w-storage'>Combi Boiler w/ Storage</a>) is used.")
     arg.setUnits('gal')
     args << arg
 
@@ -3541,7 +3541,7 @@ def run(model, runner, user_arguments)
       return false
     end
 
-    Model.tear_down(model: model, runner: runner)
+    Model.reset(model, runner)
 
     Version.check_openstudio_version()
 
@@ -3569,7 +3569,7 @@ def run(model, runner, user_arguments)
     epw_path = args[:weather_station_epw_filepath]
     if epw_path.nil?
       # Get EPW path from zip code
-      epw_path = HPXMLDefaults.lookup_weather_data_from_zipcode(args[:site_zip_code])[:station_filename]
+      epw_path = Defaults.lookup_weather_data_from_zipcode(args[:site_zip_code])[:station_filename]
     end
 
     # Create EpwFile object
@@ -3967,7 +3967,7 @@ def self.create(runner, model, args, epw_path, hpxml_path, existing_hpxml_path)
         return false
       end
 
-      HPXMLDefaults.apply(runner, hpxml, hpxml_bldg, weather)
+      Defaults.apply(runner, hpxml, hpxml_bldg, weather)
       hpxml_doc = hpxml.to_doc()
       hpxml.set_unique_hpxml_ids(hpxml_doc, true) if hpxml.buildings.size > 1
       XMLHelper.write_file(hpxml_doc, hpxml_path)
@@ -4096,17 +4096,17 @@ def self.create_geometry_envelope(runner, model, args)
     return true
   end
 
-  # Check if unavailable period already exists for given begin/end times
+  # Check if unavailable period already exists for given name and begin/end times.
   #
   # @param hpxml [HPXML] HPXML object
-  # @param column_name [TODO] TODO
-  # @param begin_month [TODO] TODO
-  # @param begin_day [TODO] TODO
-  # @param begin_hour [TODO] TODO
-  # @param end_month [TODO] TODO
-  # @param end_day [TODO] TODO
-  # @param end_hour [TODO] TODO
-  # @param natvent_availability [TODO] TODO
+  # @param column_name [String] Column name associated with unavailable_periods.csv
+  # @param begin_month [Integer] Unavailable period begin month
+  # @param begin_day [Integer] Unavailable period begin day
+  # @param begin_hour [Integer] Unavailable period begin hour
+  # @param end_month [Integer] Unavailable period end month
+  # @param end_day [Integer] Unavailable period end day
+  # @param end_hour [Integer] Unavailable period end hour
+  # @param natvent_availability [String] Natural ventilation availability (HXPML::ScheduleXXX)
   # @return [Boolean] True if the unavailability period already exists
   def self.unavailable_period_exists(hpxml, column_name, begin_month, begin_day, begin_hour, end_month, end_day, end_hour, natvent_availability = nil)
     natvent_availability = HPXML::ScheduleUnavailable if natvent_availability.nil?
@@ -6185,7 +6185,7 @@ def self.set_ducts(hpxml_bldg, args, hvac_distribution)
       if ducts_supply_location == HPXML::LocationConditionedSpace
         args[:ducts_supply_surface_area_fraction] = 1.0
       else
-        args[:ducts_supply_surface_area_fraction] = HVAC.get_default_duct_fraction_outside_conditioned_space(args[:geometry_unit_num_floors_above_grade])
+        args[:ducts_supply_surface_area_fraction] = Defaults.get_duct_outside_fraction(args[:geometry_unit_num_floors_above_grade])
       end
     end
 
@@ -6194,7 +6194,7 @@ def self.set_ducts(hpxml_bldg, args, hvac_distribution)
       if ducts_return_location == HPXML::LocationConditionedSpace
         args[:ducts_return_surface_area_fraction] = 1.0
       else
-        args[:ducts_return_surface_area_fraction] = HVAC.get_default_duct_fraction_outside_conditioned_space(args[:geometry_unit_num_floors_above_grade])
+        args[:ducts_return_surface_area_fraction] = Defaults.get_duct_outside_fraction(args[:geometry_unit_num_floors_above_grade])
       end
     end
 
@@ -6286,7 +6286,7 @@ def self.set_ducts(hpxml_bldg, args, hvac_distribution)
   def self.set_hvac_control(hpxml, hpxml_bldg, args, weather)
     return if (args[:heating_system_type] == Constants::None) && (args[:cooling_system_type] == Constants::None) && (args[:heat_pump_type] == Constants::None)
 
-    latitude = HPXMLDefaults.get_default_latitude(args[:site_latitude], weather) unless weather.nil?
+    latitude = Defaults.get_latitude(args[:site_latitude], weather) unless weather.nil?
 
     # Heating
     if hpxml_bldg.total_fraction_heat_load_served > 0
@@ -6303,7 +6303,7 @@ def self.set_hvac_control(hpxml, hpxml_bldg, args, weather)
       if not args[:hvac_control_heating_season_period].nil?
         hvac_control_heating_season_period = args[:hvac_control_heating_season_period]
         if hvac_control_heating_season_period == Constants::BuildingAmerica
-          heating_months, _cooling_months = HVAC.get_default_heating_and_cooling_seasons(weather, latitude)
+          heating_months, _cooling_months = HVAC.get_building_america_hvac_seasons(weather, latitude)
           sim_calendar_year = Location.get_sim_calendar_year(hpxml.header.sim_calendar_year, weather)
           begin_month, begin_day, end_month, end_day = Calendar.get_begin_and_end_dates_from_monthly_array(heating_months, sim_calendar_year)
         else
@@ -6332,7 +6332,7 @@ def self.set_hvac_control(hpxml, hpxml_bldg, args, weather)
       if not args[:hvac_control_cooling_season_period].nil?
         hvac_control_cooling_season_period = args[:hvac_control_cooling_season_period]
         if hvac_control_cooling_season_period == Constants::BuildingAmerica
-          _heating_months, cooling_months = HVAC.get_default_heating_and_cooling_seasons(weather, latitude)
+          _heating_months, cooling_months = HVAC.get_building_america_hvac_seasons(weather, latitude)
           sim_calendar_year = Location.get_sim_calendar_year(hpxml.header.sim_calendar_year, weather)
           begin_month, begin_day, end_month, end_day = Calendar.get_begin_and_end_dates_from_monthly_array(cooling_months, sim_calendar_year)
         else
@@ -6716,7 +6716,7 @@ def self.set_solar_thermal(hpxml_bldg, args, weather)
       collector_loop_type = args[:solar_thermal_collector_loop_type]
       collector_type = args[:solar_thermal_collector_type]
       collector_azimuth = args[:solar_thermal_collector_azimuth]
-      latitude = HPXMLDefaults.get_default_latitude(args[:site_latitude], weather) unless weather.nil?
+      latitude = Defaults.get_latitude(args[:site_latitude], weather) unless weather.nil?
       collector_tilt = Geometry.get_absolute_tilt(tilt_str: args[:solar_thermal_collector_tilt], roof_pitch: args[:geometry_roof_pitch], latitude: latitude)
       collector_rated_optical_efficiency = args[:solar_thermal_collector_rated_optical_efficiency]
       collector_rated_thermal_losses = args[:solar_thermal_collector_rated_thermal_losses]
@@ -6766,7 +6766,7 @@ def self.set_pv_systems(hpxml_bldg, args, weather)
       end
     end
 
-    latitude = HPXMLDefaults.get_default_latitude(args[:site_latitude], weather) unless weather.nil?
+    latitude = Defaults.get_latitude(args[:site_latitude], weather) unless weather.nil?
 
     hpxml_bldg.pv_systems.add(id: "PVSystem#{hpxml_bldg.pv_systems.size + 1}",
                               location: args[:pv_system_location],

diff --git a/BuildResidentialHPXML/measure.xml b/BuildResidentialHPXML/measure.xml
@@ -3,8 +3,8 @@
   <schema_version>3.1</schema_version>
   <name>build_residential_hpxml</name>
   <uid>a13a8983-2b01-4930-8af2-42030b6e4233</uid>
-  <version_id>73cdd978-05a9-42cb-9497-b54a64ac8de4</version_id>
-  <version_modified>2024-09-24T01:38:37Z</version_modified>
+  <version_id>cfc9ffd6-53f3-4fcb-b952-7f47ceb5773b</version_id>
+  <version_modified>2024-09-29T23:08:08Z</version_modified>
   <xml_checksum>2C38F48B</xml_checksum>
   <class_name>BuildResidentialHPXML</class_name>
   <display_name>HPXML Builder</display_name>
@@ -4624,7 +4624,7 @@
     <argument>
       <name>water_heater_tank_volume</name>
       <display_name>Water Heater: Tank Volume</display_name>
-      <description>Nominal volume of water heater tank. Only applies to storage water heater, heat pump water heater, and space-heating boiler with storage tank. If not provided, the OS-HPXML default (see &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#conventional-storage'&gt;Conventional Storage&lt;/a&gt;, &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#heat-pump'&gt;Heat Pump&lt;/a&gt;, &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#combi-boiler-w-storage'&gt;Combi Boiler w/ Storage&lt;/a&gt;) is used.</description>
+      <description>Nominal volume of water heater tank. If not provided, the OS-HPXML default (see &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#conventional-storage'&gt;Conventional Storage&lt;/a&gt;, &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#heat-pump'&gt;Heat Pump&lt;/a&gt;, &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.8.1/workflow_inputs.html#combi-boiler-w-storage'&gt;Combi Boiler w/ Storage&lt;/a&gt;) is used.</description>
       <type>Double</type>
       <units>gal</units>
       <required>false</required>
@@ -7518,7 +7518,7 @@
       <filename>README.md</filename>
       <filetype>md</filetype>
       <usage_type>readme</usage_type>
-      <checksum>CA7DF69B</checksum>
+      <checksum>9F5858F9</checksum>
     </file>
     <file>
       <filename>README.md.erb</filename>
@@ -7535,7 +7535,7 @@
       <filename>measure.rb</filename>
       <filetype>rb</filetype>
       <usage_type>script</usage_type>
-      <checksum>B0FD0124</checksum>
+      <checksum>9F12F6CA</checksum>
     </file>
     <file>
       <filename>constants.rb</filename>
@@ -7547,49 +7547,7 @@
       <filename>geometry.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>F80359E3</checksum>
-    </file>
-    <file>
-      <filename>extra_files/base-mf.xml</filename>
-      <filetype>xml</filetype>
-      <usage_type>test</usage_type>
-      <checksum>06C3D0DD</checksum>
-    </file>
-    <file>
-      <filename>extra_files/base-mf2.xml</filename>
-      <filetype>xml</filetype>
-      <usage_type>test</usage_type>
-      <checksum>04582640</checksum>
-    </file>
-    <file>
-      <filename>extra_files/base-sfa.xml</filename>
-      <filetype>xml</filetype>
-      <usage_type>test</usage_type>
-      <checksum>16ED9F15</checksum>
-    </file>
-    <file>
-      <filename>extra_files/base-sfa2.xml</filename>
-      <filetype>xml</filetype>
-      <usage_type>test</usage_type>
-      <checksum>1B60C132</checksum>
-    </file>
-    <file>
-      <filename>extra_files/base-sfa3.xml</filename>
-      <filetype>xml</filetype>
-      <usage_type>test</usage_type>
-      <checksum>DD9CD517</checksum>
-    </file>
-    <file>
-      <filename>extra_files/base-sfd.xml</filename>
-      <filetype>xml</filetype>
-      <usage_type>test</usage_type>
-      <checksum>79463062</checksum>
-    </file>
-    <file>
-      <filename>extra_files/base-sfd2.xml</filename>
-      <filetype>xml</filetype>
-      <usage_type>test</usage_type>
-      <checksum>9FC7FBA9</checksum>
+      <checksum>E50F00EB</checksum>
     </file>
     <file>
       <filename>test_build_residential_hpxml.rb</filename>

diff --git a/BuildResidentialHPXML/resources/geometry.rb b/BuildResidentialHPXML/resources/geometry.rb
@@ -230,7 +230,7 @@ def self.create_single_family_detached(runner:,
       assign_indexes(model: model, footprint_polygon: conditioned_polygon, space: conditioned_space)
 
       if floor > 0
-        conditioned_space_name = "#{HPXML::LocationConditionedSpace}|story #{floor + 1}"
+        conditioned_space_name = "#{HPXML::LocationConditionedSpace} story #{floor + 1}"
       else
         conditioned_space_name = HPXML::LocationConditionedSpace
       end
@@ -578,7 +578,7 @@ def self.create_single_family_detached(runner:,
         garage_attic_space.remove
 
         # remove other unused surfaces
-        # TODO: remove this once geometry methods are fixed in openstudio 3.x
+        # FUTURE: remove this once geometry methods are fixed in openstudio 3.x
         attic_space.surfaces.each do |surface1|
           next if surface1.surfaceType != EPlus::SurfaceTypeRoofCeiling
 

diff --git a/BuildResidentialScheduleFile/measure.rb b/BuildResidentialScheduleFile/measure.rb
@@ -259,7 +259,7 @@ def get_simulation_parameters(hpxml, weather, args)
   # @param weather [WeatherFile] Weather object containing EPW information
   # @param args [Hash] Map of :argument_name => value
   def get_generator_inputs(hpxml_bldg, weather, args)
-    state_code = HPXMLDefaults.get_default_state_code(hpxml_bldg.state_code, weather)
+    state_code = Defaults.get_state_code(hpxml_bldg.state_code, weather)
     if Constants::StateCodesMap.keys.include?(state_code)
       args[:state] = state_code
     else
@@ -275,9 +275,9 @@ def get_generator_inputs(hpxml_bldg, weather, args)
     end
     args[:geometry_num_occupants] = Float(Integer(args[:geometry_num_occupants]))
 
-    args[:time_zone_utc_offset] = HPXMLDefaults.get_default_time_zone(hpxml_bldg.time_zone_utc_offset, weather)
-    args[:latitude] = HPXMLDefaults.get_default_latitude(hpxml_bldg.latitude, weather)
-    args[:longitude] = HPXMLDefaults.get_default_longitude(hpxml_bldg.longitude, weather)
+    args[:time_zone_utc_offset] = Defaults.get_time_zone(hpxml_bldg.time_zone_utc_offset, weather)
+    args[:latitude] = Defaults.get_latitude(hpxml_bldg.latitude, weather)
+    args[:longitude] = Defaults.get_longitude(hpxml_bldg.longitude, weather)
   end
 end
 

diff --git a/BuildResidentialScheduleFile/measure.xml b/BuildResidentialScheduleFile/measure.xml
@@ -3,8 +3,8 @@
   <schema_version>3.1</schema_version>
   <name>build_residential_schedule_file</name>
   <uid>f770b2db-1a9f-4e99-99a7-7f3161a594b1</uid>
-  <version_id>1fc75fd9-df4c-4ba6-8eff-2366ba375060</version_id>
-  <version_modified>2024-09-26T04:58:59Z</version_modified>
+  <version_id>fac68af6-8045-433e-8eca-df53c8274e61</version_id>
+  <version_modified>2024-09-29T23:07:27Z</version_modified>
   <xml_checksum>03F02484</xml_checksum>
   <class_name>BuildResidentialScheduleFile</class_name>
   <display_name>Schedule File Builder</display_name>
@@ -133,7 +133,7 @@
       <filename>measure.rb</filename>
       <filetype>rb</filetype>
       <usage_type>script</usage_type>
-      <checksum>19F7FF66</checksum>
+      <checksum>655C4010</checksum>
     </file>
     <file>
       <filename>README.md</filename>
@@ -229,7 +229,7 @@
       <filename>schedules.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>85B9A7B9</checksum>
+      <checksum>F53FB2CB</checksum>
     </file>
     <file>
       <filename>shower_cluster_size_probability.csv</filename>

diff --git a/BuildResidentialScheduleFile/resources/schedules.rb b/BuildResidentialScheduleFile/resources/schedules.rb
@@ -92,7 +92,7 @@ def create(args:,
   # @return [Boolean] true if successful
   def create_stochastic_schedules(args:,
                                   weather:)
-    default_schedules_csv_data = HPXMLDefaults.get_default_schedules_csv_data()
+    default_schedules_csv_data = Defaults.get_schedules_csv_data()
     schedules_csv_data = get_schedules_csv_data()
 
     # initialize a random number generator
@@ -176,7 +176,7 @@ def create_stochastic_schedules(args:,
     plugload_tv_monthly_multiplier = Schedule.validate_values(schedules_csv_data[SchedulesFile::Columns[:PlugLoadsTV].name]['PlugLoadsTVMonthlyMultipliers'], 12, 'monthly') # American Time Use Survey
     ceiling_fan_weekday_sch = Schedule.validate_values(default_schedules_csv_data[SchedulesFile::Columns[:CeilingFan].name]['WeekdayScheduleFractions'], 24, 'weekday') # Table C.3(5) of ANSI/RESNET/ICC 301-2022 Addendum C
     ceiling_fan_weekend_sch = Schedule.validate_values(default_schedules_csv_data[SchedulesFile::Columns[:CeilingFan].name]['WeekendScheduleFractions'], 24, 'weekend') # Table C.3(5) of ANSI/RESNET/ICC 301-2022 Addendum C
-    ceiling_fan_monthly_multiplier = Schedule.validate_values(HVAC.get_default_ceiling_fan_months(weather).join(', '), 12, 'monthly') # based on monthly average outdoor temperatures per ANSI/RESNET/ICC 301-2019
+    ceiling_fan_monthly_multiplier = Schedule.validate_values(Defaults.get_ceiling_fan_months(weather).join(', '), 12, 'monthly') # based on monthly average outdoor temperatures per ANSI/RESNET/ICC 301-2019
 
     sch = get_building_america_lighting_schedule(args[:time_zone_utc_offset], args[:latitude], args[:longitude], schedules_csv_data)
     interior_lighting_schedule = []

diff --git a/HPXMLtoOpenStudio/measure.rb b/HPXMLtoOpenStudio/measure.rb
@@ -109,7 +109,7 @@ def run(model, runner, user_arguments)
     end
 
     Version.check_openstudio_version()
-    Model.tear_down(model: model, runner: runner)
+    Model.reset(model, runner)
 
     args = runner.getArgumentValues(arguments(model), user_arguments)
     set_file_paths(args)
@@ -291,7 +291,7 @@ def process_defaults_schedules_emissions_files(runner, weather, hpxml, args)
       hpxml_sch_map[hpxml_bldg] = schedules_file
 
       # HPXML defaults
-      all_zone_loads, all_space_loads = HPXMLDefaults.apply(runner, hpxml, hpxml_bldg, weather, schedules_file: schedules_file)
+      all_zone_loads, all_space_loads = Defaults.apply(runner, hpxml, hpxml_bldg, weather, schedules_file: schedules_file)
       hpxml_all_zone_loads[hpxml_bldg] = all_zone_loads
       hpxml_all_space_loads[hpxml_bldg] = all_space_loads
     end