Merge pull request #461 from NREL/bill-outputs3

ResStock-HPXML: optional utility bill reporting arguments, try 3

.github/workflows/ci.yml

@@ -16,15 +16,15 @@ jobs:
         python-version: ['3.8', '3.9', '3.10', '3.11']
     name: Tests - Python ${{ matrix.python-version }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           path: buildstockbatch
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           repository: NREL/resstock
           path: resstock
           ref: develop
-      - uses: actions/setup-python@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Download weather
@@ -63,13 +63,13 @@ jobs:
           check_name: Testing Report
           fail_on_failure: true
       - name: Save Coverage Report
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         if: ${{ matrix.python-version == '3.11' }}
         with:
           name: coverage-report-html
           path: buildstockbatch/coverage/htmlreport/
       - name: Save Coverage Report XML
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         if: ${{ matrix.python-version == '3.11' }}
         with:
           name: coverage-report-xml
@@ -80,7 +80,7 @@ jobs:
           cd buildstockbatch/docs
           make html SPHINXOPTS="-W --keep-going -n"
       - name: Save Docs
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         if: ${{ matrix.python-version == '3.11' }}
         with:
           name: documentation
@@ -90,12 +90,12 @@ jobs:
     strategy:
       fail-fast: false
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           repository: NREL/resstock
           path: resstock
           ref: develop
-      - uses: actions/setup-python@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: 3.11
       - name: Download weather

.github/workflows/coverage.yml

@@ -13,7 +13,7 @@ jobs:
     if: ${{ github.event.workflow_run.event == 'pull_request' }}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
           ref: ${{ github.event.workflow_run.head_commit.id }}

buildstockbatch/workflow_generator/__init__.py

@@ -8,12 +8,17 @@
     ResidentialHpxmlWorkflowGenerator as v2024_07_18_ResidentialHpxmlWorkflowGenerator,
 )  # noqa F401
 from .residential import v2024_07_18 as residential_v2024_07_18  # noqa F401
+from .residential.v2024_07_19.residential_hpxml import (
+    ResidentialHpxmlWorkflowGenerator as v2024_07_19_ResidentialHpxmlWorkflowGenerator,
+)  # noqa F401
+from .residential import v2024_07_19 as residential_v2024_07_19  # noqa F401
 
 version2GeneratorClass = {
     "commercial_default": {"latest": latestComRenerator, commercial_latest.__version__: latestComRenerator},
     "residential_hpxml": {
         "latest": latestResGenerator,
         residential_latest.__version__: latestResGenerator,
+        residential_v2024_07_19.__version__: v2024_07_19_ResidentialHpxmlWorkflowGenerator,
         residential_v2024_07_18.__version__: v2024_07_18_ResidentialHpxmlWorkflowGenerator,
     },
 }
@@ -25,6 +30,7 @@
     "residential_hpxml": {
         "latest": residential_latest.version_info,
         residential_latest.__version__: residential_latest.version_info,
+        residential_v2024_07_19.__version__: residential_v2024_07_19.version_info,
         residential_v2024_07_18.__version__: residential_v2024_07_18.version_info,
     },
 }

buildstockbatch/workflow_generator/residential/latest/__init__.py

@@ -1,8 +1,9 @@
-__version__ = "2024.07.19"
+__version__ = "2024.07.20"
 version_info = {
     "version": __version__,
     "version_description": """
-In this version, the UpgradeCosts measure is converted to a regular measure
-and is run early in the workflow. ReportHPXMLOutput measure is no longer used.
+In this version, optional include_annual_bills and
+include_monthly bills arguments are exposed for reporting
+annual and monthly utility bill outputs.
 """,
 }

buildstockbatch/workflow_generator/residential/latest/residential_hpxml_arg_mapping.py

@@ -64,4 +64,10 @@
             "output_variables": "user_output_variables",
         },
     },
+    "ReportUtilityBills": {
+        "simulation_output_report": {
+            "include_annual_bills": "register_annual_bills",
+            "include_monthly_bills": "register_monthly_bills",
+        },
+    },
 }

buildstockbatch/workflow_generator/residential/latest/residential_hpxml_defaults.py

@@ -66,7 +66,12 @@
         "timeseries_num_decimal_places": 3,
         "user_output_variables": "",
     },
-    "ReportUtilityBills": {"include_annual_bills": True, "include_monthly_bills": False},
+    "ReportUtilityBills": {
+        "include_annual_bills": False,
+        "include_monthly_bills": False,
+        "register_annual_bills": True,
+        "register_monthly_bills": False,
+    },
     "UpgradeCosts": {"debug": False},
     "ServerDirectoryCleanup": {
         "retain_in_osm": False,

buildstockbatch/workflow_generator/residential/latest/residential_hpxml_schema.yml

@@ -64,6 +64,8 @@ sim-output-report-spec:
     add_timeseries_dst_column: bool(required=False)
     add_timeseries_utc_column: bool(required=False)
     output_variables: list(include('output-var-spec'), required=False)
+    include_annual_bills: bool(required=False)
+    include_monthly_bills: bool(required=False)
 output-var-spec:
     name: str(required=True)
 measure-spec:

buildstockbatch/workflow_generator/residential/latest/tests/test_residential_workflow_generator.py

@@ -62,6 +62,7 @@
                     {"name": "Zone Mean Air Temperature"},
                     {"name": "Zone People Occupant Count"},
                 ],
+                "include_monthly_bills": True,
             },
             "server_directory_cleanup": {"retain_in_osm": True, "retain_eplusout_msgpack": True},
             "reporting_measures": [
@@ -302,8 +303,11 @@ def test_residential_hpxml(upgrade, dynamic_cfg):
 
     utility_bills_step = osw["steps"][index]
     assert utility_bills_step["measure_dir_name"] == "ReportUtilityBills"
-    assert utility_bills_step["arguments"]["include_annual_bills"] is True
+    assert utility_bills_step["arguments"]["include_annual_bills"] is False
     assert utility_bills_step["arguments"]["include_monthly_bills"] is False
+    assert utility_bills_step["arguments"]["register_annual_bills"] is True
+    if "simulation_output_report" in workflow_args:
+        assert utility_bills_step["arguments"]["register_monthly_bills"] is True
     index += 1
 
     if "reporting_measures" in workflow_args:
@@ -375,9 +379,17 @@ def test_hpmxl_schema_defaults_and_mapping():
     schema_yaml = os.path.join(os.path.dirname(__file__), "..", "residential_hpxml_schema.yml")
     schema_obj = yamale.make_schema(schema_yaml, parser="ruamel")
 
+    def get_mapped_away_yaml_keys(yaml_block_name):
+        mapped_keys = set()
+        for measure_dir_name, measure_arg_maps in ARG_MAP.items():
+            for block_name, measure_arg_map in measure_arg_maps.items():
+                if block_name == yaml_block_name:
+                    mapped_keys.update(measure_arg_map.keys())
+        return mapped_keys
+
     def assert_valid_mapped_keys(measure_dir_name, valid_args):
-        for yaml_block_name, measure_arg_map in ARG_MAP.items():
-            for measure_arg in measure_arg_map.get(measure_dir_name, {}).values():
+        for yaml_block_name, measure_arg_map in ARG_MAP.get(measure_dir_name, {}).items():
+            for measure_arg in measure_arg_map.values():
                 assert measure_arg in valid_args, f"{measure_arg} in ARG_MAP[{yaml_block_name}] not available"
                 f"as input to {measure_dir_name} measure"
 
@@ -391,21 +403,22 @@ def assert_valid_default_keys(measure_dir_name, valid_keys, exclude_keys):
         for key in default_keys - exclude_keys:
             assert key in valid_keys, f"{key} in defaults not available in {measure_dir_name} measure"
 
-    def assert_valid_keys(measure_dir_name, yaml_block_name, exclude_keys):
-        avilable_measure_input = ResidentialHpxmlWorkflowGenerator.get_measure_arguments_from_xml(
+    def assert_valid_keys(measure_dir_name, yaml_block_name):
+        available_measure_input = ResidentialHpxmlWorkflowGenerator.get_measure_arguments_from_xml(
             resstock_directory, measure_dir_name
         )
-        assert_valid_default_keys(measure_dir_name, avilable_measure_input, exclude_keys)
-        assert_valid_mapped_keys(measure_dir_name, avilable_measure_input)
+        exclude_keys = get_mapped_away_yaml_keys(yaml_block_name)  # Keys that are mapped away to other measures
+        assert_valid_default_keys(measure_dir_name, available_measure_input, exclude_keys)
+        assert_valid_mapped_keys(measure_dir_name, available_measure_input)
         if yaml_block_name:  # Not all measures have input defined/allowed in the schema
-            assert_valid_schema_keys(yaml_block_name, avilable_measure_input, exclude_keys)
-
-    assert_valid_keys("BuildExistingModel", "build_existing_model", {"add_component_loads"})
-    assert_valid_keys("HPXMLtoOpenStudio", None, set())
-    assert_valid_keys("UpgradeCosts", None, set())
-    assert_valid_keys("ReportSimulationOutput", "simulation_output_report", {"output_variables"})
-    assert_valid_keys("ReportUtilityBills", None, set())
-    assert_valid_keys("ServerDirectoryCleanup", "server_directory_cleanup", set())
+            assert_valid_schema_keys(yaml_block_name, available_measure_input, exclude_keys)
+
+    assert_valid_keys("BuildExistingModel", "build_existing_model")
+    assert_valid_keys("HPXMLtoOpenStudio", None)
+    assert_valid_keys("UpgradeCosts", None)
+    assert_valid_keys("ReportSimulationOutput", "simulation_output_report")
+    assert_valid_keys("ReportUtilityBills", None)
+    assert_valid_keys("ServerDirectoryCleanup", "server_directory_cleanup")
 
 
 def test_block_compression_and_argmap():

buildstockbatch/workflow_generator/residential/latest/tests/testing_resstock_data/measures/ReportUtilityBills/measure.xml

@@ -3,8 +3,8 @@
   <schema_version>3.1</schema_version>
   <name>report_utility_bills</name>
   <uid>ca88a425-e59a-4bc4-af51-c7e7d1e960fe</uid>
-  <version_id>23d2e18e-c2ac-4c68-a5c4-fd4372203a39</version_id>
-  <version_modified>2024-05-18T14:35:04Z</version_modified>
+  <version_id>2d6b4393-2fe5-429a-a130-da41a8cb36f0</version_id>
+  <version_modified>2024-05-29T18:54:32Z</version_modified>
   <xml_checksum>15BF4E57</xml_checksum>
   <class_name>ReportUtilityBills</class_name>
   <display_name>Utility Bills Report</display_name>
@@ -37,7 +37,7 @@
     <argument>
       <name>include_annual_bills</name>
       <display_name>Generate Annual Utility Bills</display_name>
-      <description>Generates annual utility bills.</description>
+      <description>Generates output file containing annual utility bills.</description>
       <type>Boolean</type>
       <required>false</required>
       <model_dependent>false</model_dependent>
@@ -56,7 +56,7 @@
     <argument>
       <name>include_monthly_bills</name>
       <display_name>Generate Monthly Utility Bills</display_name>
-      <description>Generates monthly utility bills.</description>
+      <description>Generates output file containing monthly utility bills.</description>
       <type>Boolean</type>
       <required>false</required>
       <model_dependent>false</model_dependent>
@@ -107,6 +107,44 @@
       <required>false</required>
       <model_dependent>false</model_dependent>
     </argument>
+    <argument>
+      <name>register_annual_bills</name>
+      <display_name>Register Annual Utility Bills</display_name>
+      <description>Registers annual utility bills with the OpenStudio runner for downstream processing.</description>
+      <type>Boolean</type>
+      <required>false</required>
+      <model_dependent>false</model_dependent>
+      <default_value>true</default_value>
+      <choices>
+        <choice>
+          <value>true</value>
+          <display_name>true</display_name>
+        </choice>
+        <choice>
+          <value>false</value>
+          <display_name>false</display_name>
+        </choice>
+      </choices>
+    </argument>
+    <argument>
+      <name>register_monthly_bills</name>
+      <display_name>Register Monthly Utility Bills</display_name>
+      <description>Registers monthly utility bills with the OpenStudio runner for downstream processing.</description>
+      <type>Boolean</type>
+      <required>false</required>
+      <model_dependent>false</model_dependent>
+      <default_value>false</default_value>
+      <choices>
+        <choice>
+          <value>true</value>
+          <display_name>true</display_name>
+        </choice>
+        <choice>
+          <value>false</value>
+          <display_name>false</display_name>
+        </choice>
+      </choices>
+    </argument>
   </arguments>
   <outputs />
   <provenances />
@@ -125,7 +163,7 @@
       <filename>README.md</filename>
       <filetype>md</filetype>
       <usage_type>readme</usage_type>
-      <checksum>E137125B</checksum>
+      <checksum>13D965BE</checksum>
     </file>
     <file>
       <filename>README.md.erb</filename>
@@ -142,7 +180,7 @@
       <filename>measure.rb</filename>
       <filetype>rb</filetype>
       <usage_type>script</usage_type>
-      <checksum>22A6665F</checksum>
+      <checksum>99961E51</checksum>
     </file>
     <file>
       <filename>detailed_rates/Sample Flat Rate Min Annual Charge.json</filename>
@@ -240,47 +278,29 @@
       <usage_type>resource</usage_type>
       <checksum>56DDA6EC</checksum>
     </file>
-    <file>
-      <filename>simple_rates/Average_retail_price_of_electricity.csv</filename>
-      <filetype>csv</filetype>
-      <usage_type>resource</usage_type>
-      <checksum>02EEEF39</checksum>
-    </file>
     <file>
       <filename>simple_rates/HouseholdConsumption.csv</filename>
       <filetype>csv</filetype>
       <usage_type>resource</usage_type>
       <checksum>0BEECB93</checksum>
     </file>
     <file>
-      <filename>simple_rates/NG_PRI_SUM_A_EPG0_PRS_DMCF_A.csv</filename>
-      <filetype>csv</filetype>
-      <usage_type>resource</usage_type>
-      <checksum>C5FFF659</checksum>
-    </file>
-    <file>
-      <filename>simple_rates/PET_PRI_WFR_A_EPD2F_PRS_DPGAL_W.csv</filename>
-      <filetype>csv</filetype>
+      <filename>simple_rates/README.md</filename>
+      <filetype>md</filetype>
       <usage_type>resource</usage_type>
-      <checksum>8C00508D</checksum>
+      <checksum>C7E1E1CB</checksum>
     </file>
     <file>
-      <filename>simple_rates/PET_PRI_WFR_A_EPLLPA_PRS_DPGAL_W.csv</filename>
+      <filename>simple_rates/pr_all_update.csv</filename>
       <filetype>csv</filetype>
       <usage_type>resource</usage_type>
-      <checksum>614B155F</checksum>
-    </file>
-    <file>
-      <filename>simple_rates/README.md</filename>
-      <filetype>md</filetype>
-      <usage_type>resource</usage_type>
-      <checksum>7832E08F</checksum>
+      <checksum>CF6409BD</checksum>
     </file>
     <file>
       <filename>util.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>70347ABF</checksum>
+      <checksum>CD3334FF</checksum>
     </file>
     <file>
       <filename>Contains Demand Charges.json</filename>
@@ -322,7 +342,7 @@
       <filename>test_report_utility_bills.rb</filename>
       <filetype>rb</filetype>
       <usage_type>test</usage_type>
-      <checksum>3C2DECE9</checksum>
+      <checksum>CDF8B24F</checksum>
     </file>
   </files>
 </measure>

buildstockbatch/workflow_generator/residential/v2024_07_19/__init__.py

@@ -0,0 +1,8 @@
+__version__ = "2024.07.19"
+version_info = {
+    "version": __version__,
+    "version_description": """
+In this version, the UpgradeCosts measure is converted to a regular measure
+and is run early in the workflow. ReportHPXMLOutput measure is no longer used.
+""",
+}