ResStock-HPXML: detailed bill calcs

buildstockbatch/workflow_generator/residential_hpxml.py

@@ -79,6 +79,7 @@ def validate(cls, cfg):
         utility-bill-scenario-spec:
             scenario_name: str(required=True)
             simple_filepath: str(required=False)
+            detailed_filepath: str(required=False)
             elec_fixed_charge: num(required=False)
             elec_marginal_rate: num(required=False)
             gas_fixed_charge: num(required=False)
@@ -300,6 +301,7 @@ def create_osw(self, sim_id, building_id, upgrade_idx):
             utility_bills_map = [
                 ['utility_bill_scenario_names', 'scenario_name'],
                 ['utility_bill_simple_filepaths', 'simple_filepath'],
+                ['utility_bill_detailed_filepaths', 'detailed_filepath'],
                 ['utility_bill_electricity_fixed_charges', 'elec_fixed_charge'],
                 ['utility_bill_electricity_marginal_rates', 'elec_marginal_rate'],
                 ['utility_bill_natural_gas_fixed_charges', 'gas_fixed_charge'],

docs/changelog/changelog_dev.rst

@@ -30,6 +30,14 @@ Development Changelog
         No longer automatically downloads the appropriate singularity image from
         S3. Also added validation to ensure the image is in the correct location.
 
+    .. change::
+        :tags: general, feature
+        :pullreq: 382
+
+        For the Residential HPXML Workflow Generator, add a new ``detailed_filepath`` argument
+        for pointing to user-specified TSV file of electricity tariff file paths. The TSV file can contain
+        utility rates mapped by State, or any other parameter.
+
     .. change::
         :tags: general, feature
         :pullreq: 383

docs/workflow_generators/residential_hpxml.rst

@@ -20,6 +20,7 @@ Configuration Example
 
         utility_bills:
           - scenario_name: Bills1
+            gas_marginal_rate: 1.05
             pv_compensation_type: NetMetering
 
         simulation_output_report:
@@ -59,7 +60,7 @@ Arguments
 
   - ``scenario_name``: Name of the emissions scenario.
   - ``type``: Type of emission (e.g., CO2e, NOx, etc.).
-  - ``elec_folder``: Folder of schedule files with hourly electricity emissions factors values. Units are kg/MWh. Path is relative to buildstock_directory's resources folder. File names must contain GEA region names.
+  - ``elec_folder``: Folder of schedule files with hourly electricity emissions factors values. Units are kg/MWh. Folder path is relative to buildstock_directory's `resources`_ folder. File names must contain GEA region names.
   - ``gas_value``: Annual emissions factor for natural gas. Units are lb/MBtu (million Btu).
   - ``propane_value``: Annual emissions factor for propane. Units are lb/MBtu (million Btu).
   - ``oil_value``: Annual emissions factor for fuel oil. Units are lb/MBtu (million Btu).
@@ -68,7 +69,8 @@ Arguments
 - ``utility_bills`` (optional): Add these arguments to the `BuildExistingModel`_ measure for performing utility bill calculations.
 
   - ``scenario_name``: Name of the utility bills scenario.
-  - ``simple_filepath``: File with all fixed charges / marginal rates for each option of a chosen parameter (e.g., State).
+  - ``simple_filepath``: TSV file with all fixed charge / marginal rate / PV argument values for each option of a chosen parameter (e.g., State). These will override any fixed charge / marginal rate / PV argument values specified in the YML file. Any blank fields will be defaulted. File path is relative to buildstock_directory's `resources`_ folder.
+  - ``detailed_filepath``: TSV file with electricity tariff path for each option of a chosen parameter (e.g., County). File may also contain all fixed charge / marginal rate / PV argument values. These will override any fixed charge / marginal rate / PV argument values specified in the YML file. Any blank fields will be defaulted. File path is relative to buildstock_directory's `resources`_ folder. Electricity tariff paths are relative to the parent folder of the ``detailed_filepath`` file.
   - ``elec_fixed_charge``: Monthly fixed charge for electricity.
   - ``elec_marginal_rate``: Marginal rate for electricity. Units are $/kWh.
   - ``gas_fixed_charge``: Monthly fixed charge for natural gas.
@@ -137,6 +139,7 @@ Arguments
 .. _BuildExistingModel: https://github.com/NREL/resstock/blob/develop/measures/BuildExistingModel/measure.xml
 .. _ReportSimulationOutput: https://github.com/NREL/resstock/blob/develop/resources/hpxml-measures/ReportSimulationOutput/measure.xml
 .. _ServerDirectoryCleanup: https://github.com/NREL/resstock/blob/develop/measures/ServerDirectoryCleanup/measure.xml
+.. _resources: https://github.com/NREL/resstock/blob/develop/resources
 
 .. _hpxml-build-existing-model-defaults: