NatLabRockies · shorowit · Mar 31, 2026 · Mar 31, 2026 · Mar 31, 2026 · Mar 31, 2026
diff --git a/Changelog.md b/Changelog.md
@@ -8,6 +8,7 @@ __New Features__
   - Compressor lockout temperatures for Rated Home defaults and Reference Home updated from 0F (single/two stage) and -20F (variable speed) to 5F and -10F, respectively.
   - Dual-fuel heat pumps now have the HP sized using the greater of the heating design temperature and 25F.
   - Pan heaters no longer operate when the outdoor temperature is below the compressor lockout temperature.
+- Utility bill scenarios can now be defined for the Rated/Reference Homes; see [the documentation](https://openstudio-eri.readthedocs.io/en/latest/workflow_inputs.html#hpxml-utility-bill-scenarios) for more information.
 - The `Battery/NominalCapacity` input is no longer used.
 - Output updates:
   - **Breaking change**: Annual peak load outputs for heating and cooling now use units of Btu/h instead of kBtu/h for consistency with other outputs.

diff --git a/docs/source/workflow_inputs.rst b/docs/source/workflow_inputs.rst
@@ -83,6 +83,125 @@ The OpenStudio-ERI calculation(s) to be performed are entered in ``/HPXML/Softwa
   For example, it does not check that the home meets all ENERGY STAR and DOE Efficient New Homes Mandatory Requirements.
   It is the software tool's responsibility to perform these additional steps.
 
+.. _hpxml_utility_bill_scenarios:
+
+HPXML Utility Bill Scenarios
+****************************
+
+One or more utility bill scenarios can be entered as an ``/HPXML/SoftwareInfo/extension/UtilityBillScenarios/UtilityBillScenario``.
+If not entered, utility bills will not be calculated.
+
+  ================================  ========  =====  ===========  ========  ========  ========================================================
+  Element                           Type      Units  Constraints  Required  Default   Notes
+  ================================  ========  =====  ===========  ========  ========  ========================================================
+  ``Name``                          string                        Yes                 Name of the scenario (which shows up in the output file)
+  ``UtilityRate``                   element                       No                  Utility rate(s) for a given fuel type; multiple are allowed
+  ``PVCompensation``                element                       No                  PV compensation information
+  ================================  ========  =====  ===========  ========  ========  ========================================================
+
+See :ref:`bill_outputs` for a description of how the calculated utility bills appear in the output files.
+
+.. _electricity_rates:
+
+Electricity Rates
+~~~~~~~~~~~~~~~~~
+
+For each scenario, electricity rates can be optionally entered as an ``/HPXML/SoftwareInfo/extension/UtilityBillScenarios/UtilityBillScenario/UtilityRate``.
+Electricity rates can be entered using Simple inputs or Detailed inputs.
+
+**Simple**
+
+For simple utility rate structures, inputs can be entered using a fixed charge and a marginal rate.
+
+  ================================  ========  =======  ===========  ========  ========  ====================
+  Element                           Type      Units    Constraints  Required  Default   Notes
+  ================================  ========  =======  ===========  ========  ========  ====================
+  ``FuelType``                      string             electricity  Yes                 Fuel type
+  ``FixedCharge``                   double    $/month  >= 0         No        12.0      Monthly fixed charge
+  ``MarginalRate``                  double    $/kWh    >= 0         No        See [#]_  Marginal flat rate
+  ================================  ========  =======  ===========  ========  ========  ====================
+
+  .. [#] If MarginalRate not provided, it defaults to state-level value based on EIA SEDS data, available at ``hpxml-measures/ReportUtilityBills/resources/simple_rates/pr_all_update.csv``.
+
+**Detailed**
+
+For detailed utility rate structures, inputs can be entered using a tariff JSON file.
+
+  ================================  ========  =======  ===========  ========  ========  =============================
+  Element                           Type      Units    Constraints  Required  Default   Notes
+  ================================  ========  =======  ===========  ========  ========  =============================
+  ``FuelType``                      string             electricity  Yes                 Fuel type
+  ``TariffFilePath``                string                          Yes                 Path to tariff JSON file [#]_
+  ================================  ========  =======  ===========  ========  ========  =============================
+
+  .. [#] TariffFilePath must point to a JSON file with utility rate structure information.
+         Tariff files can describe flat, tiered, time-of-use, tiered time-of-use, or real-time pricing rates.
+         Sources of tariff files include `OpenEI's U.S. Utility Rate Database (URDB) <https://openei.org/wiki/Utility_Rate_Database>`_;
+         a large set of residential OpenEI URDB rates for U.S. utilities are included at ``hpxml-measures/ReportUtilityBills/resources/detailed_rates/openei_rates.zip``.
+         Additional sample tariff files can be found in ``hpxml-measures/ReportUtilityBills/resources/detailed_rates``.
+         Tariff files are formatted based on `OpenEI API version 7 <https://openei.org/services/doc/rest/util_rates/?version=7#response-fields>`_.
+
+Fuel Rates
+~~~~~~~~~~
+
+For each scenario, fuel rates can be optionally entered as an ``/HPXML/SoftwareInfo/extension/UtilityBillScenarios/UtilityBillScenario/UtilityRate``.
+
+  ================================  ========  ========  ===========  ========  ========  ====================
+  Element                           Type      Units     Constraints  Required  Default   Notes
+  ================================  ========  ========  ===========  ========  ========  ====================
+  ``FuelType``                      string              See [#]_     Yes                 Fuel type
+  ``FixedCharge``                   double    $/month   >= 0         No        See [#]_  Monthly fixed charge
+  ``MarginalRate``                  double    See [#]_  >= 0         No        See [#]_  Marginal flat rate
+  ================================  ========  ========  ===========  ========  ========  ====================
+
+  .. [#] FuelType choices are "natural gas", "propane", "fuel oil", "coal", "wood", and "wood pellets".
+  .. [#] FixedCharge defaults to $12/month for natural gas and $0/month for other fuels.
+  .. [#] MarginalRate units are $/therm for natural gas, $/gallon for propane and fuel oil, and $/kBtu for other fuels.
+  .. [#] If MarginalRate not provided, it defaults to state-level value based on EIA SEDS data, available at ``hpxml-measures/ReportUtilityBills/resources/simple_rates/pr_all_update.csv``.
+
+PV Compensation
+~~~~~~~~~~~~~~~
+
+For each scenario, PV compensation information can be optionally entered in ``/HPXML/SoftwareInfo/extension/UtilityBillScenarios/UtilityBillScenario/PVCompensation``.
+
+  =============================================================  ========  =======  ===========  ========  ==============  ==============================
+  Element                                                        Type      Units    Constraints  Required  Default         Notes
+  =============================================================  ========  =======  ===========  ========  ==============  ==============================
+  ``CompensationType[NetMetering | FeedInTariff]``               element                         No        NetMetering     PV compensation type
+  ``MonthlyGridConnectionFee[Units="$/kW" or Units="$"]/Value``  double                          No        0               PV monthly grid connection fee
+  =============================================================  ========  =======  ===========  ========  ==============  ==============================
+
+**Net-Metering**
+
+If the PV compensation type is net-metering, additional information can be entered in ``/HPXML/SoftwareInfo/extension/UtilityBillScenarios/UtilityBillScenario/PVCompensation/CompensationType/NetMetering``.
+
+  ================================  ========  =======  ===========  ========  ==============  =============================================================
+  Element                           Type      Units    Constraints  Required  Default         Notes
+  ================================  ========  =======  ===========  ========  ==============  =============================================================
+  ``AnnualExcessSellbackRateType``  string             See [#]_     No        User-Specified  Net metering annual excess sellback rate type [#]_
+  ``AnnualExcessSellbackRate``      double    $/kWh    >= 0         No [#]_   0.03            User-specified net metering annual excess sellback rate [#]_
+  ================================  ========  =======  ===========  ========  ==============  =============================================================
+
+  .. [#] AnnualExcessSellbackRateType choices are "User-Specified" and "Retail Electricity Cost".
+  .. [#] When annual PV production exceeds the annual building electricity consumption, this rate, which is often significantly below the retail rate, determines the value of the excess electricity sold back to the utility.
+         This may happen to offset gas consumption, for example.
+  .. [#] AnnualExcessSellbackRate is only used when AnnualExcessSellbackRateType="User-Specified".
+  .. [#] Since modeled electricity consumption will not change from one year to the next, "indefinite rollover" of annual excess generation credit is best approximated by setting "User-Specified" and entering a rate of zero.
+
+**Feed-in Tariff**
+
+If the PV compensation type is feed-in tariff, additional information can be entered in ``/HPXML/SoftwareInfo/extension/UtilityBillScenarios/UtilityBillScenario/PVCompensation/CompensationType/FeedInTariff``.
+
+  ============================  ========  =======  ===========  ========  ==============  ========================
+  Element                       Type      Units    Constraints  Required  Default         Notes
+  ============================  ========  =======  ===========  ========  ==============  ========================
+  ``FeedInTariffRate``          double    $/kWh    >= 0         No        0.12            Feed-in tariff rate [#]_
+  ============================  ========  =======  ===========  ========  ==============  ========================
+
+  .. [#] FeedInTariffRate applies to full (not excess) PV production.
+         Some utilities/regions may have a feed-in tariff policy where compensation occurs for *excess* PV production (i.e., PV-generated electricity sent to the grid that is not immediately consumed by the building), rather than *full* PV production.
+         OpenStudio-ERI is currently unable to calculate utility bills for such a feed-in tariff policy.
+
 HPXML Building Site
 -------------------
 
@@ -167,7 +286,7 @@ Weather information is entered in ``/HPXML/Building/BuildingDetails/ClimateandRi
 
   .. [#] If EPWFilePath not provided, defaults based on the U.S. TMY3 weather station closest to the zip code centroid.
          The mapping can be found at ``hpxml-measures/HPXMLtoOpenStudio/resources/data/zipcode_weather_stations.csv``.
-  .. [#] A full set of U.S. TMY3 weather files can be `downloaded here <https://data.nrel.gov/system/files/128/tmy3s-cache-csv.zip>`_.
+  .. [#] The full set of U.S. TMY3 weather files can be `downloaded here <https://data.nlr.gov/system/files/128/1774980365-USA-TMY3-EPW.zip>`_.
 
 HPXML Climate Zones
 -------------------

diff --git a/docs/source/workflow_outputs.rst b/docs/source/workflow_outputs.rst
@@ -13,6 +13,7 @@ Upon completing an OpenStudio-ERI run, a variety of summary output files and sim
 - :ref:`home_timeseries_outputs_csv`
 - :ref:`home_configurations_hpxml`
 - :ref:`home_energyplus_files`
+- :ref:`bill_outputs`
 - :ref:`hers_diagnostic_output`
 
 Output directories will reflect the requested :ref:`hpxml_calculations`:
@@ -344,8 +345,8 @@ So the sum of all end uses for a given fuel (e.g., sum of all "End Use: Natural
   End Use: Wood Pellets: Lighting (MBtu)                            Not used by OS-ERI
   End Use: Wood Pellets: Fireplace (MBtu)                           Not used by OS-ERI
   End Use: Wood Pellets: Generator (MBtu)                           Positive value for any fuel consumed
-  End Use: Coal: Heating (MBtu)                                     Excludes heat pump backup
-  End Use: Coal: Heating Heat Pump Backup (MBtu)
+  End Use: Coal: Heating (MBtu)                                     Not used by OS-ERI
+  End Use: Coal: Heating Heat Pump Backup (MBtu)                    Not used by OS-ERI
   End Use: Coal: Hot Water (MBtu)                                   Not used by OS-ERI
   End Use: Coal: Clothes Dryer (MBtu)                               Not used by OS-ERI
   End Use: Coal: Range/Oven (MBtu)                                  Not used by OS-ERI
@@ -701,6 +702,55 @@ In addition, raw EnergyPlus simulation input/output files are available for each
   The EnergyPlus input/output files are made available for inspection, but the outputs for certain situations can be misleading if one does not know how the model was created.
   If there are additional outputs of interest that are not available in the annual/timeseries output files, please send us a request.
 
+.. _bill_outputs:
+
+Home Utility Bills (CSV)
+------------------------
+
+OpenStudio-ERI can optionally generate annual/monthly utility bill output files (e.g., ``RatedHome_AnnualBills.csv`` and ``RatedHome_MonthlyBills.csv`` for the Rated Home).
+
+**Note**: These output files are only available when utility bill scenarios are specified.
+When no utility bill scenarios are specified, utility bill output files are not generated.
+See :ref:`hpxml_utility_bill_scenarios` for more information about specifying utility bill scenarios.
+
+Annual Bills by Fuel Use
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Annual results for each utility bill scenario defined in the HPXML file are listed as shown below.
+
+  =================================================  ====================
+  Type                                               Notes
+  =================================================  ====================
+  <ScenarioName>: Total (USD)                        Scenario annual total charges.
+  <ScenarioName>: Electricity: Fixed (USD)           Scenario annual fixed charges for electricity.
+  <ScenarioName>: Electricity: Energy (USD)          Scenario annual energy charges for electricity.
+  <ScenarioName>: Electricity: PV Credit (USD)       Scenario annual production credit (negative value) for PV.
+  <ScenarioName>: Electricity: Total (USD)           Scenario annual total charges for electricity.
+  <ScenarioName>: Natural Gas: Fixed (USD)           Scenario annual fixed charges for natural gas.
+  <ScenarioName>: Natural Gas: Energy (USD)          Scenario annual energy charges for natural gas.
+  <ScenarioName>: Natural Gas: Total (USD)           Scenario annual total charges for natural gas.
+  <ScenarioName>: Fuel Oil: Fixed (USD)              Scenario annual fixed charges for fuel oil.
+  <ScenarioName>: Fuel Oil: Energy (USD)             Scenario annual energy charges for fuel oil.
+  <ScenarioName>: Fuel Oil: Total (USD)              Scenario annual total charges for fuel oil.
+  <ScenarioName>: Propane: Fixed (USD)               Scenario annual fixed charges for propane.
+  <ScenarioName>: Propane: Energy (USD)              Scenario annual energy charges for propane.
+  <ScenarioName>: Propane: Total (USD)               Scenario annual total charges for propane.
+  <ScenarioName>: Wood Cord: Fixed (USD)             Scenario annual fixed charges for wood cord.
+  <ScenarioName>: Wood Cord: Energy (USD)            Scenario annual energy charges for wood cord.
+  <ScenarioName>: Wood Cord: Total (USD)             Scenario annual total charges for wood cord.
+  <ScenarioName>: Wood Pellets: Fixed (USD)          Scenario annual fixed charges for wood pellets.
+  <ScenarioName>: Wood Pellets: Energy (USD)         Scenario annual energy charges for wood pellets.
+  <ScenarioName>: Wood Pellets: Total (USD)          Scenario annual total charges for wood pellets.
+  <ScenarioName>: Coal: Fixed (USD)                  Not used by OS-ERI
+  <ScenarioName>: Coal: Energy (USD)                 Not used by OS-ERI
+  <ScenarioName>: Coal: Total (USD)                  Not used by OS-ERI
+  =================================================  ====================
+
+Monthly Bills by Fuel Use
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Monthly results for each utility bill scenario defined in the HPXML file are listed as rows corresponding to Month, and columns corresponding to Type.
+
 .. _hers_diagnostic_output:
 
 HERS Diagnostic Output

diff --git a/hpxml-measures/BuildResidentialHPXML/measure.rb b/hpxml-measures/BuildResidentialHPXML/measure.rb
@@ -2278,25 +2278,21 @@ def set_attics(hpxml_bldg, args)
                  'walls' => { 'surfaces' => hpxml_bldg.walls, 'ids' => [] },
                  'floors' => { 'surfaces' => hpxml_bldg.floors, 'ids' => [] } }
 
-    attic_locations = [HPXML::LocationAtticUnconditioned, HPXML::LocationAtticUnvented, HPXML::LocationAtticVented]
-    surf_ids.values.each do |surf_hash|
+    attic_locations = [HPXML::LocationAtticUnconditioned,
+                       HPXML::LocationAtticUnvented,
+                       HPXML::LocationAtticVented]
+
+    surf_ids.each do |surf_type, surf_hash|
       surf_hash['surfaces'].each do |surface|
-        next if (not attic_locations.include? surface.interior_adjacent_to) &&
-                (not attic_locations.include? surface.exterior_adjacent_to)
+        next unless (attic_locations.include? surface.interior_adjacent_to) ||
+                    (attic_locations.include? surface.exterior_adjacent_to) ||
+                    (surf_type == 'roofs' && [surface.interior_adjacent_to, surface.exterior_adjacent_to].include?(HPXML::LocationConditionedSpace)) ||
+                    (surf_type == 'floors' && surface.exterior_adjacent_to == HPXML::LocationOtherHousingUnit && surface.floor_or_ceiling == HPXML::FloorOrCeilingCeiling)
 
         surf_hash['ids'] << surface.id
       end
     end
 
-    # Add attached roofs for cathedral ceiling
-    conditioned_space = HPXML::LocationConditionedSpace
-    surf_ids['roofs']['surfaces'].each do |surface|
-      next if (conditioned_space != surface.interior_adjacent_to) &&
-              (conditioned_space != surface.exterior_adjacent_to)
-
-      surf_ids['roofs']['ids'] << surface.id
-    end
-
     hpxml_bldg.attics.add(id: "Attic#{hpxml_bldg.attics.size + 1}",
                           attic_type: args[:geometry_attic_type_attic_type],
                           attached_to_roof_idrefs: surf_ids['roofs']['ids'],
@@ -2327,7 +2323,8 @@ def set_foundations(hpxml_bldg, args)
         next unless (foundation_locations.include? surface.interior_adjacent_to) ||
                     (foundation_locations.include? surface.exterior_adjacent_to) ||
                     (surf_type == 'slabs' && surface.interior_adjacent_to == HPXML::LocationConditionedSpace) ||
-                    (surf_type == 'floors' && [HPXML::LocationOutside, HPXML::LocationManufacturedHomeUnderBelly].include?(surface.exterior_adjacent_to))
+                    (surf_type == 'floors' && [HPXML::LocationOutside, HPXML::LocationManufacturedHomeUnderBelly].include?(surface.exterior_adjacent_to)) ||
+                    (surf_type == 'floors' && surface.exterior_adjacent_to == HPXML::LocationOtherHousingUnit && surface.floor_or_ceiling == HPXML::FloorOrCeilingFloor)
 
         surf_hash['ids'] << surface.id
       end