Merge pull request #1771 from NREL/ruby-docs

More ruby documentation

Author: shorowit

Diff for: BuildResidentialHPXML/measure.rb

@@ -2366,18 +2366,18 @@ def arguments(model) # rubocop:disable Lint/UnusedMethodArgument
 
     solar_thermal_system_type_choices = OpenStudio::StringVector.new
     solar_thermal_system_type_choices << 'none'
-    solar_thermal_system_type_choices << HPXML::SolarThermalSystemType
+    solar_thermal_system_type_choices << HPXML::SolarThermalSystemTypeHotWater
 
     solar_thermal_collector_loop_type_choices = OpenStudio::StringVector.new
     solar_thermal_collector_loop_type_choices << HPXML::SolarThermalLoopTypeDirect
     solar_thermal_collector_loop_type_choices << HPXML::SolarThermalLoopTypeIndirect
     solar_thermal_collector_loop_type_choices << HPXML::SolarThermalLoopTypeThermosyphon
 
     solar_thermal_collector_type_choices = OpenStudio::StringVector.new
-    solar_thermal_collector_type_choices << HPXML::SolarThermalTypeEvacuatedTube
-    solar_thermal_collector_type_choices << HPXML::SolarThermalTypeSingleGlazing
-    solar_thermal_collector_type_choices << HPXML::SolarThermalTypeDoubleGlazing
-    solar_thermal_collector_type_choices << HPXML::SolarThermalTypeICS
+    solar_thermal_collector_type_choices << HPXML::SolarThermalCollectorTypeEvacuatedTube
+    solar_thermal_collector_type_choices << HPXML::SolarThermalCollectorTypeSingleGlazing
+    solar_thermal_collector_type_choices << HPXML::SolarThermalCollectorTypeDoubleGlazing
+    solar_thermal_collector_type_choices << HPXML::SolarThermalCollectorTypeICS
 
     arg = OpenStudio::Measure::OSArgument::makeChoiceArgument('solar_thermal_system_type', solar_thermal_system_type_choices, true)
     arg.setDisplayName('Solar Thermal: System Type')
@@ -2401,7 +2401,7 @@ def arguments(model) # rubocop:disable Lint/UnusedMethodArgument
     arg = OpenStudio::Measure::OSArgument::makeChoiceArgument('solar_thermal_collector_type', solar_thermal_collector_type_choices, true)
     arg.setDisplayName('Solar Thermal: Collector Type')
     arg.setDescription('The collector type of the solar thermal system.')
-    arg.setDefaultValue(HPXML::SolarThermalTypeEvacuatedTube)
+    arg.setDefaultValue(HPXML::SolarThermalCollectorTypeEvacuatedTube)
     args << arg
 
     arg = OpenStudio::Measure::OSArgument::makeDoubleArgument('solar_thermal_collector_azimuth', true)
@@ -3471,7 +3471,7 @@ def arguments(model) # rubocop:disable Lint/UnusedMethodArgument
   # Define what happens when the measure is run.
   #
   # @param model [OpenStudio::Model::Model] OpenStudio Model object
-  # @param runner [OpenStudio::Measure::OSRunner] OpenStudio Runner object
+  # @param runner [OpenStudio::Measure::OSRunner] Object typically used to display warnings
   # @param user_arguments [OpenStudio::Measure::OSArgumentMap] OpenStudio measure arguments
   # @return [Boolean] true if successful
   def run(model, runner, user_arguments)
@@ -3794,7 +3794,7 @@ def argument_errors(args)
 module HPXMLFile
   # Create the closed-form geometry, and then call individual set_xxx methods
   #
-  # @param runner [OpenStudio::Measure::OSRunner] OpenStudio Runner object
+  # @param runner [OpenStudio::Measure::OSRunner] Object typically used to display warnings
   # @param model [OpenStudio::Model::Model] OpenStudio Model object
   # @param args [Hash] Map of :argument_name => value
   # @param epw_path [String] Path to the EPW weather file
@@ -3923,7 +3923,7 @@ def self.need_weather_based_on_args(args)
 
   # Check for errors in hpxml, and validate hpxml_doc against hpxml_path
   #
-  # @param runner [OpenStudio::Measure::OSRunner] OpenStudio Runner object
+  # @param runner [OpenStudio::Measure::OSRunner] Object typically used to display warnings
   # @param hpxml [HPXML] HPXML object
   # @param hpxml_doc [Oga::XML::Element] Root XML element of the HPXML document
   # @param hpxml_path [TODO] TODO
@@ -3964,7 +3964,7 @@ def self.validate_hpxml(runner, hpxml, hpxml_doc, hpxml_path)
 
   # Create 3D geometry (surface, subsurfaces) for a given unit type
   #
-  # @param runner [OpenStudio::Measure::OSRunner] OpenStudio Runner object
+  # @param runner [OpenStudio::Measure::OSRunner] Object typically used to display warnings
   # @param model [OpenStudio::Model::Model] OpenStudio Model object
   # @param args [Hash] Map of :argument_name => value
   # @return [Boolean] True if successful
@@ -4058,7 +4058,7 @@ def self.unavailable_period_exists(hpxml, column_name, begin_month, begin_day, b
   # - emissions scenarios
   # - utility bill scenarios
   #
-  # @param runner [OpenStudio::Measure::OSRunner] OpenStudio Runner object
+  # @param runner [OpenStudio::Measure::OSRunner] Object typically used to display warnings
   # @param hpxml [HPXML] HPXML object
   # @param args [Hash] Map of :argument_name => value
   # @return [Boolean] true if no errors, otherwise false
@@ -6571,7 +6571,7 @@ def self.set_hot_water_distribution(hpxml_bldg, args)
       standard_piping_length = args[:hot_water_distribution_standard_piping_length]
     else
       recirculation_control_type = args[:hot_water_distribution_recirc_control_type]
-      recirculation_piping_length = args[:hot_water_distribution_recirc_piping_length]
+      recirculation_piping_loop_length = args[:hot_water_distribution_recirc_piping_length]
       recirculation_branch_piping_length = args[:hot_water_distribution_recirc_branch_piping_length]
       recirculation_pump_power = args[:hot_water_distribution_recirc_pump_power]
     end
@@ -6580,7 +6580,7 @@ def self.set_hot_water_distribution(hpxml_bldg, args)
                                            system_type: args[:hot_water_distribution_system_type],
                                            standard_piping_length: standard_piping_length,
                                            recirculation_control_type: recirculation_control_type,
-                                           recirculation_piping_length: recirculation_piping_length,
+                                           recirculation_piping_loop_length: recirculation_piping_loop_length,
                                            recirculation_branch_piping_length: recirculation_branch_piping_length,
                                            recirculation_pump_power: recirculation_pump_power,
                                            pipe_r_value: args[:hot_water_distribution_pipe_r],
@@ -6632,8 +6632,8 @@ def self.set_solar_thermal(hpxml_bldg, args, weather)
       collector_azimuth = args[:solar_thermal_collector_azimuth]
       latitude = HPXMLDefaults.get_default_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_frta = args[:solar_thermal_collector_rated_optical_efficiency]
-      collector_frul = args[:solar_thermal_collector_rated_thermal_losses]
+      collector_rated_optical_efficiency = args[:solar_thermal_collector_rated_optical_efficiency]
+      collector_rated_thermal_losses = args[:solar_thermal_collector_rated_thermal_losses]
       storage_volume = args[:solar_thermal_storage_volume]
     end
 
@@ -6648,8 +6648,8 @@ def self.set_solar_thermal(hpxml_bldg, args, weather)
                                          collector_type: collector_type,
                                          collector_azimuth: collector_azimuth,
                                          collector_tilt: collector_tilt,
-                                         collector_frta: collector_frta,
-                                         collector_frul: collector_frul,
+                                         collector_rated_optical_efficiency: collector_rated_optical_efficiency,
+                                         collector_rated_thermal_losses: collector_rated_thermal_losses,
                                          storage_volume: storage_volume,
                                          water_heating_system_idref: hpxml_bldg.water_heating_systems[0].id,
                                          solar_fraction: solar_fraction)

Diff for: 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>635a8ab6-45f1-4969-b2c5-f308519438f8</version_id>
-  <version_modified>2024-07-11T16:09:59Z</version_modified>
+  <version_id>c4dd5a2c-b6ac-467e-b914-ad2f0d59cf23</version_id>
+  <version_modified>2024-07-17T17:04:58Z</version_modified>
   <xml_checksum>2C38F48B</xml_checksum>
   <class_name>BuildResidentialHPXML</class_name>
   <display_name>HPXML Builder</display_name>
@@ -7406,19 +7406,19 @@
       <filename>measure.rb</filename>
       <filetype>rb</filetype>
       <usage_type>script</usage_type>
-      <checksum>F41033B3</checksum>
+      <checksum>09586CC1</checksum>
     </file>
     <file>
       <filename>geometry.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>8E4E4C7F</checksum>
+      <checksum>3BCF34D6</checksum>
     </file>
     <file>
       <filename>test_build_residential_hpxml.rb</filename>
       <filetype>rb</filetype>
       <usage_type>test</usage_type>
-      <checksum>C0AF4CE1</checksum>
+      <checksum>4924B90F</checksum>
     </file>
   </files>
 </measure>

Diff for: BuildResidentialHPXML/resources/geometry.rb

@@ -4,7 +4,7 @@
 module Geometry
   # Create a 3D representation of a single-family detached home using the following arguments.
   #
-  # @param runner [OpenStudio::Measure::OSRunner] OpenStudio Runner object
+  # @param runner [OpenStudio::Measure::OSRunner] Object typically used to display warnings
   # @param model [OpenStudio::Model::Model] OpenStudio Model object
   # @param geometry_unit_cfa [Double] conditioned floor area (ft2)
   # @param geometry_average_ceiling_height [Double] average ceiling height (ft)
@@ -1237,7 +1237,7 @@ def self.create_apartment(model:,
 
   # Place a door subsurface on an exterior wall surface (with enough area) prioritized by front, then back, then left, then right, and lowest story.
   #
-  # @param runner [OpenStudio::Measure::OSRunner] OpenStudio Runner object
+  # @param runner [OpenStudio::Measure::OSRunner] Object typically used to display warnings
   # @param model [OpenStudio::Model::Model] OpenStudio Model object
   # @param door_area [Double] the area of the opaque door(s) (ft2)
   # @return [Boolean] true if successful
@@ -1373,7 +1373,7 @@ def self.create_doors(runner:,
 
   # Place window subsurfaces on exterior wall surfaces (or skylight subsurfaces on roof surfaces) using target facade areas based on either window to wall area ratios or window areas.
   #
-  # @param runner [OpenStudio::Measure::OSRunner] OpenStudio Runner object
+  # @param runner [OpenStudio::Measure::OSRunner] Object typically used to display warnings
   # @param model [OpenStudio::Model::Model] OpenStudio Model object
   # @param window_front_wwr [Double] ratio of window to wall area for the unit's front facade (frac)
   # @param window_back_wwr [Double] ratio of window to wall area for the unit's back facade (frac)
@@ -2279,7 +2279,7 @@ def self.get_wall_area_for_windows(surface:,
   # @param max_single_window_area [Double] maximum area for a single window (ft2)
   # @param facade [String] front, back, left, or right
   # @param model [OpenStudio::Model::Model] OpenStudio Model object
-  # @param runner [OpenStudio::Measure::OSRunner] OpenStudio Runner object
+  # @param runner [OpenStudio::Measure::OSRunner] Object typically used to display warnings
   # @return [Boolean] true if successful
   def self.add_windows_to_wall(surface:,
                                window_area:,

Diff for: BuildResidentialHPXML/tests/test_build_residential_hpxml.rb

@@ -579,7 +579,7 @@ def _set_measure_argument_values(hpxml_file, args)
       args['solar_thermal_system_type'] = 'none'
       args['solar_thermal_collector_area'] = 40.0
       args['solar_thermal_collector_loop_type'] = HPXML::SolarThermalLoopTypeDirect
-      args['solar_thermal_collector_type'] = HPXML::SolarThermalTypeEvacuatedTube
+      args['solar_thermal_collector_type'] = HPXML::SolarThermalCollectorTypeEvacuatedTube
       args['solar_thermal_collector_azimuth'] = 180
       args['solar_thermal_collector_tilt'] = 20
       args['solar_thermal_collector_rated_optical_efficiency'] = 0.5
@@ -764,7 +764,7 @@ def _set_measure_argument_values(hpxml_file, args)
       args['pv_system_array_tilt'] = 'roofpitch'
       args['pv_system_2_array_tilt'] = 'roofpitch+15'
     elsif ['extra-dhw-solar-latitude.xml'].include? hpxml_file
-      args['solar_thermal_system_type'] = HPXML::SolarThermalSystemType
+      args['solar_thermal_system_type'] = HPXML::SolarThermalSystemTypeHotWater
       args['solar_thermal_collector_tilt'] = 'Latitude-15'
     elsif ['extra-second-refrigerator.xml'].include? hpxml_file
       args['extra_refrigerator_location'] = HPXML::LocationConditionedSpace

Diff for: BuildResidentialScheduleFile/measure.rb

@@ -88,7 +88,7 @@ def arguments(model) # rubocop:disable Lint/UnusedMethodArgument
   # Define what happens when the measure is run.
   #
   # @param model [OpenStudio::Model::Model] OpenStudio Model object
-  # @param runner [OpenStudio::Measure::OSRunner] OpenStudio Runner object
+  # @param runner [OpenStudio::Measure::OSRunner] Object typically used to display warnings
   # @param user_arguments [OpenStudio::Measure::OSArgumentMap] OpenStudio measure arguments
   # @return [Boolean] true if successful
   def run(model, runner, user_arguments)
@@ -176,7 +176,7 @@ def run(model, runner, user_arguments)
 
   # Write out the HPXML file with the output CSV path containing occupancy schedules.
   #
-  # @param runner [OpenStudio::Measure::OSRunner] OpenStudio Runner object
+  # @param runner [OpenStudio::Measure::OSRunner] Object typically used to display warnings
   # @param doc [Oga::XML::Document] Oga XML Document object
   # @param hpxml_path [String] path of the input HPXML file
   # @param hpxml_output_path [String] path of the output HPXML file
@@ -192,7 +192,7 @@ def write_modified_hpxml(runner, doc, hpxml_path, hpxml_output_path, schedules_f
 
   # Create and export the occupancy schedules.
   #
-  # @param runner [OpenStudio::Measure::OSRunner] OpenStudio Runner object
+  # @param runner [OpenStudio::Measure::OSRunner] Object typically used to display warnings
   # @param hpxml [HPXML] HPXML object
   # @param hpxml_bldg [HPXML::Building] HPXML Building object representing an individual dwelling unit
   # @param weather [WeatherFile] Weather object containing EPW information

Diff for: 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>b471ba87-0ebb-4a48-a305-9a4f6a16e1c5</version_id>
-  <version_modified>2024-07-11T02:46:37Z</version_modified>
+  <version_id>82cc5cf7-51fc-435c-9ea1-429bf4b72080</version_id>
+  <version_modified>2024-07-15T21:48:21Z</version_modified>
   <xml_checksum>03F02484</xml_checksum>
   <class_name>BuildResidentialScheduleFile</class_name>
   <display_name>Schedule File Builder</display_name>
@@ -133,13 +133,13 @@
       <filename>measure.rb</filename>
       <filetype>rb</filetype>
       <usage_type>script</usage_type>
-      <checksum>3ECB9FB5</checksum>
+      <checksum>D2B0EB5F</checksum>
     </file>
     <file>
       <filename>README.md</filename>
       <filetype>md</filetype>
       <usage_type>resource</usage_type>
-      <checksum>C8528AAA</checksum>
+      <checksum>08194138</checksum>
     </file>
     <file>
       <filename>clothes_dryer_consumption_dist.csv</filename>
@@ -223,7 +223,7 @@
       <filename>schedules.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>BBF55F85</checksum>
+      <checksum>A0CC250C</checksum>
     </file>
     <file>
       <filename>schedules_config.md</filename>

Diff for: BuildResidentialScheduleFile/resources/README.md

@@ -18,12 +18,12 @@ The schedule CSV file contains the following columns:
 * `hot_water_dishwasher`
 * `hot_water_clothes_washer`
 * `hot_water_fixtures`
-* `sleep` (exported only when "debug" mode is enabled)
+* `sleeping` (exported only when "debug" mode is enabled)
 
 Each of the columns, except `occupants`, represent schedule values (kW for power schedules, and gallons per minute for water schedules) normalized using universal maximum values found in `constants.rb`.
 
 The `occupants` column represents the fractional percent of occupants present out of the total number of occupants assigned to the unit.
-The `sleep` column represents the fractional percent of the total number of occupants who are sleeping.
+The `sleeping` column represents the fractional percent of the total number of occupants who are sleeping.
 
 There are the same number of rows as the total simulation time-step (e.g., 35040 if 15-min, 8760 if hourly [8784, if leap year]).
 

Diff for: BuildResidentialScheduleFile/resources/schedules.rb

@@ -3,21 +3,21 @@
 require 'csv'
 require 'matrix'
 
-# TODO
+# Collection of methods related to the generation of stochastic occupancy schedules.
 class ScheduleGenerator
-  # @param runner [OpenStudio::Measure::OSRunner] OpenStudio Runner object
-  # @param state [TODO] TODO
-  # @param column_names [TODO] TODO
-  # @param random_seed [TODO] TODO
-  # @param minutes_per_step [TODO] TODO
-  # @param steps_in_day [TODO] TODO
-  # @param mkc_ts_per_day [TODO] TODO
-  # @param mkc_ts_per_hour [TODO] TODO
-  # @param total_days_in_year [TODO] TODO
-  # @param sim_year [TODO] TODO
-  # @param sim_start_day [TODO] TODO
-  # @param debug [TODO] TODO
-  # @param append_output [TODO] TODO
+  # @param runner [OpenStudio::Measure::OSRunner] Object typically used to display warnings
+  # @param state [String] State code from the HPXML file
+  # @param column_names [Array<String>] list of the schedule column names to generate
+  # @param random_seed [Integer] the seed for the random number generator
+  # @param minutes_per_step [Integer] the simulation timestep (minutes)
+  # @param steps_in_day [Integer] the number of steps in a 24-hour day
+  # @param mkc_ts_per_day [Integer] Markov chain timesteps per day
+  # @param mkc_ts_per_hour [Integer] Markov chain timesteps per hour
+  # @param total_days_in_year [Integer] number of days in the calendar year
+  # @param sim_year [Integer] the calendar year
+  # @param sim_start_day [DateTime] the DateTime object corresponding to Jan 1 of the calendar year
+  # @param debug [Boolean] If true, writes extra column(s) (e.g., sleeping) for informational purposes.
+  # @param append_output [Boolean] If true and the output CSV file already exists, appends columns to the file rather than overwriting it. The existing output CSV file must have the same number of rows (i.e., timeseries frequency) as the new columns being appended.
   def initialize(runner:,
                  state:,
                  column_names: nil,
@@ -49,18 +49,18 @@ def initialize(runner:,
 
   attr_accessor(:schedules)
 
-  # TODO
+  # Get the subset of schedule column names that the stochastic schedule generator supports.
   #
-  # @return [TODO] TODO
+  # @return [Array<String>] list of all schedule column names whose schedules can be stochastically generated
   def self.export_columns
     return SchedulesFile::Columns.values.select { |c| c.can_be_stochastic }.map { |c| c.name }
   end
 
-  # TODO
+  # The top-level method for initializing the schedules hash just before calling the main stochastic schedules method.
   #
-  # @param args [TODO] TODO
+  # @param args [Hash] Map of :argument_name => value
   # @param weather [WeatherFile] Weather object containing EPW information
-  # @return [TODO] TODO
+  # @return [Boolean] true if successful
   def create(args:,
              weather:)
     @schedules = {}
@@ -85,11 +85,11 @@ def create(args:,
     return true
   end
 
-  # TODO
+  # The main method for creating stochastic schedules.
   #
-  # @param args [TODO] TODO
+  # @param args [Hash] Map of :argument_name => value
   # @param weather [WeatherFile] Weather object containing EPW information
-  # @return [TODO] TODO
+  # @return [Boolean] true if successful
   def create_stochastic_schedules(args:,
                                   weather:)
     # initialize a random number generator