More ruby documentation

.github/workflows/config.yml

@@ -61,6 +61,7 @@ jobs:
       - name: Build documentation
         run: |
           cd docs
+          ruby source/data/create_default_schedules_csv_tables.rb
           make html SPHINXOPTS="-W --keep-going -n"
 
       - name: Check 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. A 'Furnace' as 'separate' backup to a ducted heat pump is not supported.
 
 - **Name:** ``heating_system_2_type``
 - **Type:** ``Choice``

BuildResidentialHPXML/measure.rb

@@ -1674,7 +1674,7 @@ def arguments(model) # rubocop:disable Lint/UnusedMethodArgument
 
     arg = OpenStudio::Measure::OSArgument::makeChoiceArgument('heating_system_2_type', heating_system_2_type_choices, true)
     arg.setDisplayName('Heating System 2: Type')
-    arg.setDescription('The type of the second heating system.')
+    arg.setDescription("The type of the second heating system. If a heat pump is specified and the backup type is '#{HPXML::HeatPumpBackupTypeSeparate}', this heating system represents '#{HPXML::HeatPumpBackupTypeSeparate}' backup heating. A '#{HPXML::HVACTypeFurnace}' as '#{HPXML::HeatPumpBackupTypeSeparate}' backup to a ducted heat pump is not supported.")
     arg.setDefaultValue('none')
     args << arg
 
@@ -3798,8 +3798,8 @@ module HPXMLFile
   # @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
-  # @param hpxml_path [TODO] TODO
-  # @param existing_hpxml_path [TODO] TODO
+  # @param hpxml_path [String] Path to the created HPXML file
+  # @param existing_hpxml_path [String] Path to the existing HPXML file
   # @return [Oga::XML::Element] Root XML element of the updated HPXML document
   def self.create(runner, model, args, epw_path, hpxml_path, existing_hpxml_path)
     if need_weather_based_on_args(args)
@@ -3926,7 +3926,7 @@ def self.need_weather_based_on_args(args)
   # @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
+  # @param hpxml_path [String] Path to the created HPXML file
   # @return [Boolean] True if the HPXML is valid
   def self.validate_hpxml(runner, hpxml, hpxml_doc, hpxml_path)
     # Check for errors in the HPXML object

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>4df2c890-62c5-441d-bb0e-f4d7e48317d2</version_id>
+  <version_modified>2024-08-08T18:16:04Z</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. 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>AB6941B1</checksum>
     </file>
     <file>
       <filename>README.md.erb</filename>
@@ -7406,7 +7406,7 @@
       <filename>measure.rb</filename>
       <filetype>rb</filetype>
       <usage_type>script</usage_type>
-      <checksum>0472491B</checksum>
+      <checksum>B7F49CEF</checksum>
     </file>
     <file>
       <filename>geometry.rb</filename>

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>2d9397bb-1241-4b01-8f2c-af55c69b041c</version_id>
+  <version_modified>2024-08-08T17:47:45Z</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>F48302F1</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.