Merge pull request #1754 from NREL/stochastic_occupancy_paper

Adds link to stochastic occupancy methodology paper to docs/READMEs

Author: shorowit

BuildResidentialScheduleFile/README.md

@@ -4,9 +4,9 @@
 # Schedule File Builder
 
 ## Description
-Builds a residential schedule file.
+Builds a residential stochastic occupancy schedule file.
 
-Generates a CSV of schedules at the specified file path, and inserts the CSV schedule file path into the output HPXML file (or overwrites it if one already exists). Stochastic schedules are generated using time-inhomogeneous Markov chains derived from American Time Use Survey data, and supplemented with sampling duration and power level from NEEA RBSA data as well as DHW draw duration and flow rate from Aquacraft/AWWA data.
+Generates a CSV of schedules at the specified file path, and inserts the CSV schedule file path into the output HPXML file (or overwrites it if one already exists). Stochastic schedules are generated using time-inhomogeneous Markov chains derived from American Time Use Survey data, and supplemented with sampling duration and power level from NEEA RBSA data as well as DHW draw duration and flow rate from Aquacraft/AWWA data. See <a href='https://www.sciencedirect.com/science/article/pii/S0306261922011540'>Stochastic simulation of occupant-driven energy use in a bottom-up residential building stock model</a> for a more complete description of the methodology.
 
 ## Arguments
 

BuildResidentialScheduleFile/measure.rb

@@ -24,12 +24,12 @@ def name
 
   # human readable description
   def description
-    return 'Builds a residential schedule file.'
+    return 'Builds a residential stochastic occupancy schedule file.'
   end
 
   # human readable description of modeling approach
   def modeler_description
-    return 'Generates a CSV of schedules at the specified file path, and inserts the CSV schedule file path into the output HPXML file (or overwrites it if one already exists). Stochastic schedules are generated using time-inhomogeneous Markov chains derived from American Time Use Survey data, and supplemented with sampling duration and power level from NEEA RBSA data as well as DHW draw duration and flow rate from Aquacraft/AWWA data.'
+    return "Generates a CSV of schedules at the specified file path, and inserts the CSV schedule file path into the output HPXML file (or overwrites it if one already exists). Stochastic schedules are generated using time-inhomogeneous Markov chains derived from American Time Use Survey data, and supplemented with sampling duration and power level from NEEA RBSA data as well as DHW draw duration and flow rate from Aquacraft/AWWA data. See <a href='https://www.sciencedirect.com/science/article/pii/S0306261922011540'>Stochastic simulation of occupant-driven energy use in a bottom-up residential building stock model</a> for a more complete description of the methodology."
   end
 
   # Define the arguments that the user will input.

BuildResidentialScheduleFile/measure.xml

@@ -3,13 +3,13 @@
   <schema_version>3.1</schema_version>
   <name>build_residential_schedule_file</name>
   <uid>f770b2db-1a9f-4e99-99a7-7f3161a594b1</uid>
-  <version_id>3e97c1ce-c81f-4ab9-a086-b4f94510389e</version_id>
-  <version_modified>2024-06-20T15:11:49Z</version_modified>
+  <version_id>f3ee0ac4-9f12-4b23-8a57-ff5e2bfa2130</version_id>
+  <version_modified>2024-06-21T00:37:39Z</version_modified>
   <xml_checksum>03F02484</xml_checksum>
   <class_name>BuildResidentialScheduleFile</class_name>
   <display_name>Schedule File Builder</display_name>
-  <description>Builds a residential schedule file.</description>
-  <modeler_description>Generates a CSV of schedules at the specified file path, and inserts the CSV schedule file path into the output HPXML file (or overwrites it if one already exists). Stochastic schedules are generated using time-inhomogeneous Markov chains derived from American Time Use Survey data, and supplemented with sampling duration and power level from NEEA RBSA data as well as DHW draw duration and flow rate from Aquacraft/AWWA data.</modeler_description>
+  <description>Builds a residential stochastic occupancy schedule file.</description>
+  <modeler_description>Generates a CSV of schedules at the specified file path, and inserts the CSV schedule file path into the output HPXML file (or overwrites it if one already exists). Stochastic schedules are generated using time-inhomogeneous Markov chains derived from American Time Use Survey data, and supplemented with sampling duration and power level from NEEA RBSA data as well as DHW draw duration and flow rate from Aquacraft/AWWA data. See &lt;a href='https://www.sciencedirect.com/science/article/pii/S0306261922011540'&gt;Stochastic simulation of occupant-driven energy use in a bottom-up residential building stock model&lt;/a&gt; for a more complete description of the methodology.</modeler_description>
   <arguments>
     <argument>
       <name>hpxml_path</name>
@@ -116,7 +116,7 @@
       <filename>README.md</filename>
       <filetype>md</filetype>
       <usage_type>readme</usage_type>
-      <checksum>5852D2EF</checksum>
+      <checksum>EB56CA85</checksum>
     </file>
     <file>
       <filename>README.md.erb</filename>
@@ -133,13 +133,13 @@
       <filename>measure.rb</filename>
       <filetype>rb</filetype>
       <usage_type>script</usage_type>
-      <checksum>A2F3618B</checksum>
+      <checksum>A981343F</checksum>
     </file>
     <file>
       <filename>README.md</filename>
       <filetype>md</filetype>
       <usage_type>resource</usage_type>
-      <checksum>A8A141BE</checksum>
+      <checksum>C8528AAA</checksum>
     </file>
     <file>
       <filename>clothes_dryer_consumption_dist.csv</filename>

BuildResidentialScheduleFile/resources/README.md

@@ -1,6 +1,7 @@
 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.
 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).
 The schedule CSV file contains the following columns:
@@ -17,9 +18,7 @@ The schedule CSV file contains the following columns:
 * `hot_water_dishwasher`
 * `hot_water_clothes_washer`
 * `hot_water_fixtures`
-* `sleep`*
-
-*Column `sleep` is optionally exported only when "debug" mode is enabled.
+* `sleep` (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`.
 

docs/source/workflow_inputs.rst

@@ -692,6 +692,7 @@ Frequency of schedule values do not need to match the simulation timestep.
 For example, hourly schedules can be used with a 10-minute simulation timestep, or 10-minute schedules can be used with an hourly simulation timestep.
 
 A detailed stochastic occupancy schedule CSV file can also be automatically generated for you (see "Can Be Stochastically Generated" above for applicable columns); see the :ref:`usage_instructions` for the commands.
+The stochastic occupancy schedules are generated using the methodology described in `Stochastic simulation of occupant-driven energy use in a bottom-up residential building stock model <https://www.sciencedirect.com/science/article/pii/S0306261922011540>`_.
 Inputs for the stochastic schedule generator are entered in:
 
 - ``/HPXML/Building/BuildingDetails/BuildingSummary/BuildingOccupancy/NumberofResidents``