Merge pull request #1254 from NREL/hvac-seasons

Heating and Cooling Unavailable Days

docs/read_the_docs/source/changelog/changelog_dev.rst

@@ -84,3 +84,19 @@ Development Changelog
  OpenStudio-HPXML: `pull request 1690 <https://github.com/NREL/OpenStudio-HPXML/pull/1690>`_, `pull request 1775 <https://github.com/NREL/OpenStudio-HPXML/pull/1775>`_
 
  Assignees: Joe Robertson
+
+
+ .. change::
+ :tags: workflow, hvac, feature
+ :pullreq: 1254
+
+ **Date**: 2024-09-218
+
+ Title:
+ Heating and Cooling Unavailable Days
+
+ Description:
+ The purpose of this PR is to account for dwelling units whose HVAC system (heating/cooling) is unavailable for some number of days during the year (per RECS 2020).
+ Specifically, this PR modifies HVAC heating/cooling seasons using number of unavailable days and BAHSP definition for heating/cooling months.
+
+ Assignees: Joe Robertson

docs/read_the_docs/source/workflow_inputs/characteristics.rst

@@ -6149,6 +6149,89 @@ From ``project_national`` the list of options, option stock sturation, and optio
  - 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
  - 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
 
+.. _cooling_unavailable_days:
+
+Cooling Unavailable Days
+------------------------
+
+Description
+***********
+
+Number of days in a year the cooling system is unavailable.
+
+Created by
+**********
+
+``sources/recs/recs2020/tsv_maker.py``
+
+Source
+******
+
+- \U.S. EIA 2020 Residential Energy Consumption Survey (RECS) microdata.
+
+
+Arguments
+*********
+
+.. list-table::
+ :header-rows: 1
+ :stub-columns: 1
+
+ * - Name
+ - Required
+ - Units
+ - Type
+ - Choices
+ - Description
+ * - ``schedules_space_cooling_unavailable_days``
+ - false
+ - 
+ - Integer
+ -
+ - Number of days space cooling equipment is unavailable.
+
+Options
+*******
+
+From ``project_national`` the list of options, option stock sturation, and option arguments for the **Cooling Unavailable Days** characteristic.
+
+.. list-table::
+ :header-rows: 1
+ :stub-columns: 1
+ :widths: auto
+
+ * - Option name
+ - Stock saturation
+ - ``schedules_space_cooling_unavailable_days``
+
+ * - 1 day
+ - 0.64%
+ - 1
+ * - 1 month
+ - 0.95%
+ - 30
+ * - 1 week
+ - 0.87%
+ - 7
+ * - 2 weeks
+ - 0.74%
+ - 14
+ * - 3 days
+ - 1.1%
+ - 3
+ * - 3 months
+ - 0.61%
+ - 90
+ * - Never
+ - 95%
+ - 0
+ * - Year round
+ - 0.23%
+ - 365
+ * - Void
+ - 0%
+ - 
+
 .. _corridor:
 
 Corridor
@@ -42078,6 +42161,102 @@ From ``project_national`` the list of options, option stock sturation, and optio
  - 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
  - 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
 
+.. _heating_unavailable_days:
+
+Heating Unavailable Days
+------------------------
+
+Description
+***********
+
+Number of days in a year the heating system is unavailable
+
+Created by
+**********
+
+``sources/recs/recs2020/tsv_maker.py``
+
+Source
+******
+
+- \U.S. EIA 2020 Residential Energy Consumption Survey (RECS) microdata.
+
+
+Assumption
+**********
+
+- \Where samples are less than 10, the data is aggregated in the following order until there are no rows with less than 10 samples:
+
+- \1. The Federal Poverty Level dependency is aggregated every 100%
+
+- \2. The Federal Poverty Level dependency is aggregated every 200%
+
+- \3. The Geometry Building Type RECS dependency is aggregated into SF, MF, and MH bins.
+
+- \4. The Cooling Unavailable Days dependency is aggregated into Days, Weeks, Month, and All Year bins.
+
+- \5. The Cooling Unavailable Days dependancy is removed.
+
+
+Arguments
+*********
+
+.. list-table::
+ :header-rows: 1
+ :stub-columns: 1
+
+ * - Name
+ - Required
+ - Units
+ - Type
+ - Choices
+ - Description
+ * - ``schedules_space_heating_unavailable_days``
+ - false
+ - 
+ - Integer
+ -
+ - Number of days space heating equipment is unavailable.
+
+Options
+*******
+
+From ``project_national`` the list of options, option stock sturation, and option arguments for the **Heating Unavailable Days** characteristic.
+
+.. list-table::
+ :header-rows: 1
+ :stub-columns: 1
+ :widths: auto
+
+ * - Option name
+ - Stock saturation
+ - ``schedules_space_heating_unavailable_days``
+
+ * - 1 day
+ - 0.82%
+ - 0
+ * - 1 month
+ - 0.35%
+ - 30
+ * - 1 week
+ - 0.62%
+ - 7
+ * - 2 weeks
+ - 0.43%
+ - 14
+ * - 3 days
+ - 1.1%
+ - 3
+ * - 3 months
+ - 0.36%
+ - 90
+ * - Never
+ - 96%
+ - 0
+ * - Year round
+ - 0.24%
+ - 365
+
 .. _holiday_lighting:
 
 Holiday Lighting

docs/read_the_docs/source/workflow_outputs/csv_tables/characteristics.csv

@@ -21,6 +21,7 @@ build_existing_model.clothes_washer_presence,:ref:`clothes_washer_presence`
 build_existing_model.clothes_washer_usage_level,:ref:`clothes_washer_usage_level`
 build_existing_model.cooking_range,:ref:`cooking_range`
 build_existing_model.cooking_range_usage_level,:ref:`cooking_range_usage_level`
+build_existing_model.cooling_unavailable_days,:ref:`cooling_unavailable_days`
 build_existing_model.cooling_setpoint,:ref:`cooling_setpoint`
 build_existing_model.cooling_setpoint_has_offset,:ref:`cooling_setpoint_has_offset`
 build_existing_model.cooling_setpoint_offset_magnitude,:ref:`cooling_setpoint_offset_magnitude`
@@ -64,6 +65,7 @@ build_existing_model.geometry_wall_type,:ref:`geometry_wall_type`
 build_existing_model.ground_thermal_conductivity,:ref:`ground_thermal_conductivity`
 build_existing_model.has_pv,:ref:`has_pv`
 build_existing_model.heating_fuel,:ref:`heating_fuel`
+build_existing_model.heating_unavailable_days,:ref:`heating_unavailable_days`
 build_existing_model.heating_setpoint,:ref:`heating_setpoint`
 build_existing_model.heating_setpoint_has_offset,:ref:`heating_setpoint_has_offset`
 build_existing_model.heating_setpoint_offset_magnitude,:ref:`heating_setpoint_offset_magnitude`

docs/read_the_docs/source/workflow_outputs/csv_tables/other_outputs.csv

@@ -48,6 +48,8 @@ build_existing_model.utility_bill_wood_marginal_rates,"Wood utility bill margina
 build_existing_model.weather_file_city,City from the EPW weather file.
 build_existing_model.weather_file_latitude,Latitude from the EPW weather file.
 build_existing_model.weather_file_longitude,Longitude from the EPW weather file.
+build_existing_model.heating_unavailable_period,Heating unavailable period.
+build_existing_model.cooling_unavailable_period,Cooling unavailable period.
 apply_upgrade.applicable,The measure was applied to the workflow.
 apply_upgrade.upgrade_name,User-specificed name that describes the upgrade.
 apply_upgrade.reference_scenario,The upgrade_name which should act as a reference to this upgrade to calculate savings.

measures/ApplyUpgrade/measure.rb

@@ -296,6 +296,7 @@ def run(model, runner, user_arguments)
  end
 
  # Run the ResStockArguments measure
+ measures['ResStockArguments'][0]['building_id'] = values['building_id']
  if not apply_measures(measures_dir, { 'ResStockArguments' => measures['ResStockArguments'] }, resstock_arguments_runner, model, true, 'OpenStudio::Measure::ModelMeasure', 'upgraded.osw')
  register_logs(runner, resstock_arguments_runner)
  return false
@@ -334,7 +335,7 @@ def run(model, runner, user_arguments)
  # Assign ResStockArgument's runner arguments to BuildResidentialHPXML
  resstock_arguments_runner.result.stepValues.each do |step_value|
  value = get_value_from_workflow_step_value(step_value)
- next if value == ''
+ next if value == '' || Constants::ArgumentsToExclude.include?(step_value.name)
 
  measures['BuildResidentialHPXML'][0][step_value.name] = value
  end

measures/ApplyUpgrade/measure.xml

@@ -3,8 +3,8 @@
  <schema_version>3.1</schema_version>
  <name>apply_upgrade</name>
  <uid>33f1654c-f734-43d1-b35d-9d2856e41b5a</uid>
- <version_id>8fe95f7c-bc5a-4a5b-aa24-1611990427b9</version_id>
- <version_modified>2024-09-03T16:10:53Z</version_modified>
+ <version_id>e0b6d3af-6941-45e2-8627-9d8f568ebe1a</version_id>
+ <version_modified>2024-09-04T23:38:38Z</version_modified>
  <xml_checksum>9339BE01</xml_checksum>
  <class_name>ApplyUpgrade</class_name>
  <display_name>Apply Upgrade</display_name>
@@ -6342,7 +6342,7 @@
  <filename>measure.rb</filename>
  <filetype>rb</filetype>
  <usage_type>script</usage_type>
- <checksum>4AF2BD8F</checksum>
+ <checksum>8E47BE40</checksum>
  </file>
  <file>
  <filename>constants.rb</filename>

measures/BuildExistingModel/measure.rb

@@ -329,6 +329,7 @@ def run(model, runner, user_arguments)
 
  # Run the ResStockArguments measure
  resstock_arguments_runner = OpenStudio::Measure::OSRunner.new(OpenStudio::WorkflowJSON.new) # we want only ResStockArguments registered argument values
+ measures['ResStockArguments'][0]['building_id'] = args[:building_id]
  if not apply_measures(measures_dir, { 'ResStockArguments' => measures['ResStockArguments'] }, resstock_arguments_runner, model, true, 'OpenStudio::Measure::ModelMeasure', 'existing.osw')
  register_logs(runner, resstock_arguments_runner)
  return false
@@ -364,7 +365,7 @@ def run(model, runner, user_arguments)
  resstock_arguments_runner.result.stepValues.each do |step_value|
  value = get_value_from_workflow_step_value(step_value)
  register_value(runner, step_value.name, value) if Constants::ArgumentsToRegister.include?(step_value.name)
- next if value == ''
+ next if value == '' || Constants::ArgumentsToExclude.include?(step_value.name)
 
  measures['BuildResidentialHPXML'][0][step_value.name] = value
  end

measures/BuildExistingModel/measure.xml

@@ -3,8 +3,8 @@
  <schema_version>3.1</schema_version>
  <name>build_existing_model</name>
  <uid>dedf59bb-3b88-4f16-8755-2c1ff5519cbf</uid>
- <version_id>3aadffec-f1e9-43bd-8b0b-d7eb3d573c50</version_id>
- <version_modified>2024-09-04T15:18:43Z</version_modified>
+ <version_id>be99be23-ddd9-49c4-804a-cb9853764e3e</version_id>
+ <version_modified>2024-09-04T21:01:10Z</version_modified>
  <xml_checksum>2C38F48B</xml_checksum>
  <class_name>BuildExistingModel</class_name>
  <display_name>Build Existing Model</display_name>
@@ -349,7 +349,7 @@
  <filename>measure.rb</filename>
  <filetype>rb</filetype>
  <usage_type>script</usage_type>
- <checksum>9C118034</checksum>
+ <checksum>18614B0C</checksum>
  </file>
  </files>
 </measure>

measures/ResStockArguments/README.md

@@ -5167,6 +5167,17 @@ Multiplier on the permanent spa heater energy usage that can reflect, e.g., high
 
 <br/>
 
+**Building Unit ID**
+
+The building unit number (between 1 and the number of samples).
+
+- **Name:** ``building_id``
+- **Type:** ``Integer``
+
+- **Required:** ``false``
+
+<br/>
+
 **Schedules: Vacancy Periods**
 
 Specifies the vacancy periods. Enter a date like "Dec 15 - Jan 15". Optionally, can enter hour of the day like "Dec 15 2 - Jan 15 20" (start hour can be 0 through 23 and end hour can be 1 through 24). If multiple periods, use a comma-separated list.
@@ -5200,6 +5211,28 @@ The availability of the natural ventilation schedule during the power outage per
 
 <br/>
 
+**Schedules: Space Heating Unavailability**
+
+Number of days space heating equipment is unavailable.
+
+- **Name:** ``schedules_space_heating_unavailable_days``
+- **Type:** ``Integer``
+
+- **Required:** ``false``
+
+<br/>
+
+**Schedules: Space Cooling Unavailability**
+
+Number of days space cooling equipment is unavailable.
+
+- **Name:** ``schedules_space_cooling_unavailable_days``
+- **Type:** ``Integer``
+
+- **Required:** ``false``
+
+<br/>
+
 **Geometry: Unit Conditioned Floor Area Bin**
 
 E.g., '2000-2499'.