More ruby documentation

BuildResidentialHPXML/README.md

@@ -2777,7 +2777,7 @@ Pipe diameter of the geothermal loop. Only applies to ground-to-air heat pump ty
 
 **Heating System 2: Type**
 
-The type of the second heating system.
+The type of the second heating system. If a heat pump is specified and the backup type is 'separate', this heating system represents 'separate' backup heating. For ducted heat pumps where the backup heating system is a 'Furnace', the backup would typically be characterized as 'integrated' in that the furnace and heat pump share the same distribution system and blower fan; a 'Furnace' as 'separate' backup to a ducted heat pump is not supported.
 
 - **Name:** ``heating_system_2_type``
 - **Type:** ``Choice``

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>8d558b94-90a7-4f68-86a0-8f80b41ddbb5</version_id>
-  <version_modified>2024-08-06T22:34:22Z</version_modified>
+  <version_id>ffacf8b9-4562-4319-ab8a-f4a63fc0126f</version_id>
+  <version_modified>2024-08-16T19:31:29Z</version_modified>
   <xml_checksum>2C38F48B</xml_checksum>
   <class_name>BuildResidentialHPXML</class_name>
   <display_name>HPXML Builder</display_name>
@@ -3359,7 +3359,7 @@
     <argument>
       <name>heating_system_2_type</name>
       <display_name>Heating System 2: Type</display_name>
-      <description>The type of the second heating system.</description>
+      <description>The type of the second heating system. If a heat pump is specified and the backup type is 'separate', this heating system represents 'separate' backup heating. For ducted heat pumps where the backup heating system is a 'Furnace', the backup would typically be characterized as 'integrated' in that the furnace and heat pump share the same distribution system and blower fan; a 'Furnace' as 'separate' backup to a ducted heat pump is not supported.</description>
       <type>Choice</type>
       <required>true</required>
       <model_dependent>false</model_dependent>
@@ -7389,7 +7389,7 @@
       <filename>README.md</filename>
       <filetype>md</filetype>
       <usage_type>readme</usage_type>
-      <checksum>B702F428</checksum>
+      <checksum>FCAE28E2</checksum>
     </file>
     <file>
       <filename>README.md.erb</filename>
@@ -7406,13 +7406,13 @@
       <filename>measure.rb</filename>
       <filetype>rb</filetype>
       <usage_type>script</usage_type>
-      <checksum>0472491B</checksum>
+      <checksum>3E87E8F5</checksum>
     </file>
     <file>
       <filename>geometry.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>2764D675</checksum>
+      <checksum>523DF705</checksum>
     </file>
     <file>
       <filename>test_build_residential_hpxml.rb</filename>

BuildResidentialHPXML/resources/geometry.rb

@@ -1919,7 +1919,7 @@ def self.get_abs_azimuth(relative_azimuth:,
   # @param space [OpenStudio::Model::Space] the foundation space adjacent to the rim joist
   # @param rim_joist_height [Double] height of the rim joists (ft)
   # @param z [Double] z coordinate of the bottom of the rim joists
-  # @return [void]
+  # @return [nil]
   def self.add_rim_joist(model:,
                          polygon:,
                          space:,
@@ -1963,7 +1963,7 @@ def self.add_rim_joist(model:,
   # @param model [OpenStudio::Model::Model] OpenStudio Model object
   # @param footprint_polygon [OpenStudio::Point3dVector] an OpenStudio::Point3dVector object
   # @param space [OpenStudio::Model::Space] an OpenStudio::Model::Space object
-  # @return [void]
+  # @return [nil]
   def self.assign_indexes(model:,
                           footprint_polygon:,
                           space:)
@@ -2010,7 +2010,7 @@ def self.assign_indexes(model:,
   # We can't deterministically assign indexes to these surfaces.
   #
   # @param model [OpenStudio::Model::Model] OpenStudio Model object
-  # @return [void]
+  # @return [nil]
   def self.assign_remaining_surface_indexes(model:)
     model.getSurfaces.each do |surface|
       next if surface.additionalProperties.getFeatureAsInteger('Index').is_initialized
@@ -2273,7 +2273,7 @@ def self.add_windows_to_wall(surface:,
   # @param win_num [Integer] The window number for the current surface
   # @param facade [String] front, back, left, or right
   # @param model [OpenStudio::Model::Model] OpenStudio Model object
-  # @return [void]
+  # @return [nil]
   def self.add_window_to_wall(surface:,
                               win_width:,
                               win_height:,
@@ -2535,7 +2535,7 @@ def self.get_attic_space(model:,
   # @param model [OpenStudio::Model::Model] OpenStudio Model object
   # @param foundation_type [String] HPXML location for foundation type
   # @param foundation_height [Double] height of the foundation (m)
-  # @return [void]
+  # @return [nil]
   def self.apply_ambient_foundation_shift(model:,
                                           foundation_type:,
                                           foundation_height:)

BuildResidentialScheduleFile/measure.rb

@@ -178,8 +178,8 @@ def run(model, runner, user_arguments)
   #
   # @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
+  # @param hpxml_path [String] Path to the HPXML file
+  # @param hpxml_output_path [String] Path to the output HPXML file
   # @param schedules_filepaths [Array<String>] array of SchedulesFilePath strings in the input HPXML file
   # @param args [Hash] Map of :argument_name => value
   def write_modified_hpxml(runner, doc, hpxml_path, hpxml_output_path, schedules_filepaths, args)

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>82cc5cf7-51fc-435c-9ea1-429bf4b72080</version_id>
-  <version_modified>2024-07-15T21:48:21Z</version_modified>
+  <version_id>c82306e3-de8f-4659-b356-4e9cd05205e1</version_id>
+  <version_modified>2024-08-16T19:20:19Z</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>D2B0EB5F</checksum>
+      <checksum>038D2D11</checksum>
     </file>
     <file>
       <filename>README.md</filename>
       <filetype>md</filetype>
       <usage_type>resource</usage_type>
-      <checksum>08194138</checksum>
+      <checksum>7060BE69</checksum>
     </file>
     <file>
       <filename>clothes_dryer_consumption_dist.csv</filename>
@@ -169,7 +169,7 @@
       <filename>constants.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>B2B70AD9</checksum>
+      <checksum>962DC751</checksum>
     </file>
     <file>
       <filename>cooking_consumption_dist.csv</filename>
@@ -220,16 +220,16 @@
       <checksum>419E598E</checksum>
     </file>
     <file>
-      <filename>schedules.rb</filename>
-      <filetype>rb</filetype>
+      <filename>schedules.csv</filename>
+      <filetype>csv</filetype>
       <usage_type>resource</usage_type>
-      <checksum>A0CC250C</checksum>
+      <checksum>7B6640FE</checksum>
     </file>
     <file>
-      <filename>schedules_config.md</filename>
-      <filetype>md</filetype>
+      <filename>schedules.rb</filename>
+      <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>916BF4C3</checksum>
+      <checksum>25A966F4</checksum>
     </file>
     <file>
       <filename>shower_cluster_size_probability.csv</filename>

BuildResidentialScheduleFile/resources/README.md

@@ -1,9 +1,16 @@
-Stochastic Occupancy Modeling introduces major changes to most occupant-related schedules.
-Occupant activities are now generated on-the-fly and saved to CSV files used by `OpenStudio` Schedule:File objects.
+# Stochastic Occupancy Modeling
+
+The `BuildResidentialScheduleFile` measure introduces major changes to most occupant-related schedules.
+
+## Overview
+
+Occupant activities are now generated on-the-fly and saved to CSV files used by OpenStudio/EnergyPlus `Schedule:File` objects.
 Schedules are generated using time-inhomogenous Markov chains derived from American Time Use Survey data, supplemented with sampling duration and power level from NEEA RBSA data, as well as DHW draw duration and flow rate data from Aquacraft/AWWA data.
 See [Stochastic simulation of occupant-driven energy use in a bottom-up residential building stock model](https://www.sciencedirect.com/science/article/pii/S0306261922011540) for a more complete description of the methodology.
 
-The `BuildResidentialScheduleFile` measure outputs a schedule CSV file (available inside the `run` folder of each building simulation output).
+## Outputs
+
+The `BuildResidentialScheduleFile` measure outputs schedule CSV files (available inside the `run` folder of each building simulation output).
 The schedule CSV file contains the following columns:
 * `occupants`
 * `lighting_interior`
@@ -27,42 +34,108 @@ The `sleeping` column represents the fractional percent of the total number of o
 
 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]).
 
-The `ScheduleGenerator` class uses Markov chain based simulation to generate the schedule.csv.
+## The `ScheduleGenerator`
+
+This class uses Markov chain based simulation to generate the schedule CSV files.
 To support that, several pre-generated set of files are used, contained in the following folders:
 * `weekday`
 * `weekend`
 
-These two folders contain the Markov chain initial probability, Markov chain transition and also appliance duration probabilities csv files.
+These two folders contain the Markov chain initial probability, Markov chain transition and also appliance duration probabilities CSV files.
 The appliance duration probabilities here are used during the Markov chain simulation to determine duration of various appliances.
 The files are divided into four clusters (cluster0 to cluster3), for 4 occupant behavior types.
 
-`<enduse>_consumption_dist.csv`
+The following sections describe the remaining files found in the schedule generator resources folder.
+
+### `<enduse>_consumption_dist.csv`
 
 These files contain the 15-min power consumption kWh samples for the given end use, obtained from RBSA (average 15-min end use kWh for each submetered home; N=number of homes with that end use).
 The schedule generator randomly picks one of these values to determine the power level of the appliance schedule.
 
-`<enduse>_duration_dist.csv`
+Here, `<enduse>` may be:
+* `clothes_dryer`
+* `clothes_washer`
+* `cooking`
+* `dishwasher`
+
+### `<enduse>_duration_dist.csv`
 
 These files contain the samples of runtime duration of different end uses, in 15-min increments, generated from the RBSA dataset.
 So, a value of 3 means 45 minutes.
 Each row is for one household, and each column is the duration of one instance of the appliance running.
 
-For the above `<enduse>_consumption_dist.csv` and `<enduse>_duration_dist.csv` files, `<enduse>` may be:
+Again, `<enduse>` may be:
 * `clothes_dryer`
 * `clothes_washer`
 * `cooking`
 * `dishwasher`
 
-`<enduse>_cluster_size_probability.csv`
+### `<enduse>_cluster_size_probability.csv`
 
 These files contain the probability distribution of the event cluster size for different domestic hot water end uses, obtained from the HotWaterEventScheduleGenerator Excel file.
 The first row is the probability of a cluster size of 1 event, second row for probability of cluster size of 2 events and so on.
 
-For the above `<enduse>_cluster_size_probability.csv` files, `<enduse>` may be:
+Here, `<enduse>` may be:
 * `hot_water_clothes_washer`
 * `hot_water_dishwasher`
 * `shower`
 
-`constants.rb`
+### `<enduse>_event_duration_probability.csv`
+
+TODO
+
+Again, `<enduse>` may be:
+* `hot_water_clothes_washer`
+* `hot_water_dishwasher`
+* `shower`
+
+### `constants.rb` and `schedules.csv`
+
+These files contain various miscellaneous configurations for the schedule generator.
+Their meanings and sources are defined below.
+
+#### Occupancy Types
+
+Occupancy cluster types: Mostly Home, Early Regular Worker, Mostly Away, Regular Worker.
+Probabilities are derived from ATUS using the k-modes algorithm.
+
+#### Plug Loads
+
+This is the baseline schedule for misc plugload, lighting and ceiling fan.
+It will be modified based on occupancy.
+Television plugload uses the same schedule as misc plugload.
+
+#### Lighting
+
+Indoor lighting schedule is generated on the fly.
+Garage lighting uses the same schedule as indoor lighting.
+
+#### Cooking
+
+Monthly energy use multipliers for cooking stove/oven/range from average of multiple end-use submetering datasets (HEMS, RBSAM, ELCAP, Mass Res 1, Pecan St.).
+Power draw distribution is based on csv files.
+
+#### Clothes Dryer
+
+Monthly energy use multipliers for clothes dryer from average of multiple end-use submetering datasets (HEMS, RBSAM, ELCAP, Mass Res 1, Pecan St., FSEC).
+Power draw distribution is based on csv files.
+
+#### Clothes Washer
+
+Monthly energy use multipliers for clothes washer and dishwasher from average of multiple end-use submetering datasets (generally HEMS, RBSAM, ELCAP, Mass Res 1, and Pecan St.).
+Power draw distribution is based on csv files.
+
+#### Dishwasher
+
+Monthly energy use multipliers for clothes washer and dishwasher from average of multiple end-use submetering datasets (generally HEMS, RBSAM, ELCAP, Mass Res 1, Pecan St., and FSEC).
+Power draw distribution is based on csv files.
+
+#### Water Draw Events
+
+Probabilities for all water draw events are extracted from DHW event generators.
+The onset, duration, events_per_cluster_probs, flow rate mean and std could all refer to the DHW event generator excel sheet ('event characteristics' and 'Start Times' sheet).
+
+#### Sink
 
-This file contains various miscellaneous configurations for the schedule generator, and their meanings and sources are defined within the file.
+avg_sink_clusters_per_hh -> Average sink cluster per house hold. Set to 6657 for U.S. average of 2.53 occupants per household, based on relationship of 6885 clusters for 25 gpd, from Building America DHW Event Schedule Generator,
+Set to 6657 for U.S. average of 2.53 occupants per household, based on relationship of 6885 clusters for 25 gpd, from Building America DHW Event Schedule Generator.