Add utility bill calculations

build/.gitattributes

@@ -0,0 +1 @@
+build_singularity.sh eol=lf

build/Dockerfile

@@ -41,8 +41,25 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
             libpng-dev \
             libgdbm-dev \
             libgomp1 \
+            libgl-dev \
+            libglib2.0-dev \
+            wget \
+            build-essential \
     && rm -rf /var/lib/apt/lists/*
 
+RUN wget https://www.python.org/ftp/python/3.8.8/Python-3.8.8.tgz --no-check-certificate && \
+    tar xzf Python-3.8.8.tgz && \
+    cd Python-3.8.8 && \
+    ./configure --enable-optimizations && \
+    make altinstall && \
+    rm -rf Python-3.8.8 && \
+    rm -rf Python-3.8.8.tgz
+
+RUN python3.8 -m pip install GHEDesigner==1.0
+RUN python3.8 -m pip install NREL-PySAM==4.2.0
+
+RUN ghedesigner --help
+
 # link executable from /usr/local/bin
 RUN ln -s /usr/local/openstudio-${OPENSTUDIO_VERSION}${OPENSTUDIO_VERSION_EXT}/bin/openstudio /usr/local/bin/openstudio
 ENV LC_ALL=C
@@ -51,4 +68,4 @@ VOLUME /var/simdata/openstudio
 WORKDIR /var/simdata/openstudio
 
 # Ensure that openstudio can load the custom gems
-RUN openstudio --verbose --bundle /var/oscli/Gemfile --bundle_path /var/oscli/gems --bundle_without native_ext gem_list
+RUN openstudio --verbose --bundle /var/oscli/Gemfile --bundle_path /var/oscli/gems --bundle_without native_ext gem_list

build/README.md

@@ -43,8 +43,6 @@
 
 * Launch the Container (in privileged mode with docker.sock mounted in the container)
 
-    __*Windows: change the line endings in your `C:\path\to\comstock\build\singularity\build_singularity.sh` file from Windows (CR LF) to Unix (LF).  You can do this with Notepad++ using Edit > EOL Conversion or VSCode using the Change End of Line Sequence command.  If you don't, you will get the error `: No such file or directory` in the next step*__
-
     ```bash
     cd C:\path\to\comstock\build
     ```

documentation/reference_doc/.gitignore

@@ -13,4 +13,5 @@
 *.toc
 *.upa
 *.bbl
+*.bcf
 *.blg

documentation/reference_doc/0_3_acronyms.tex

@@ -49,7 +49,7 @@ \chapter{List of Acronyms}
     \acro  {EPD}  {equipment power density}
     \acro  {ERV}  {energy recovery ventilator}
     \acro{EST}{Eastern Standard Time}
-    \acro  {EUI}  {energy use intensity} 
+    \acro  {EUI}  {energy use intensity}
     \acro{EUL}{effective useful life}
     \acro{EULP}{end-use load profiles}
     \acro{FIPS}{Federal Information Processing Standard}
@@ -82,6 +82,7 @@ \chapter{List of Acronyms}
     \acro{NHGIS}{National Historical Geographic Information System}
     \acro  {NREL} {National Renewable Energy Laboratory}
     \acro{OEDI}{Open Energy Data Initiative}
+    \acro  {PADD} {Petroleum Administration for Defense District}
     \acro  {PFP} {parallel fan-powered}
     \acro  {PLR} {part load ratio}
     \acro{PPL}{plug and process load}
@@ -106,6 +107,7 @@ \chapter{List of Acronyms}
     \acro{TMY3}{typical meteorological year}
     \acro{Tstat}{thermostat}
     \acro{UTC}{Coordinated Universal Time}
+    \acro{URDB}{Utility Rate Database}
     \acro  {VAV}  {variable air volume}
     \acro{VLT}{visible light transmittance}
     \acro{VRF}{variable refrigerant flow}

documentation/reference_doc/5_outputs.tex

@@ -65,4 +65,44 @@ \subsection{On Site Fossil Fuel Emissions}
 Natural gas, propane, and fuel oil emissions use the emission factors in \textit{Table 5.1.2(1) National Average Emission Factors for Household Fuels} defined in \textit{ANSI/RESNET/ICCC 301 Standard for the Calculation and Labeling of the Energy Performance of Dwelling and Sleeping Units using an Energy Rating Index}. Natural gas emissions include both combustion and pre-combustion emissions (e.g., methane leakage for natural gas).
 
 \subsection{District Energy Emissions}
-ComStock currently does not model emissions from district energy systems, as there is considerable variation by location and type of district system.
+ComStock currently does not model emissions from district energy systems, as there is considerable variation by location and type of district system.
+
+\section{Utility Bills}
+ComStock estimates utility bills for several of the primary fuels consumed in buildings.
+Although the rest of ComStock represents the building stock circa 2018, the utility bill estimates reflect utility rates
+circa 2022, which was the most recent year of data available from EIA at the time of implementation. We made this choice
+because most users of the data were assumed to prefer bills that most closely reflect the present for decision making.
+
+\subsection{Electric Bills}
+The primary resource for the electric utility rates is the Utility Rate Database (URDB) \citep{urdb}. This database contains machine-readable descriptions of electric rate structures which have been compiled by manually processing utility rate documentation published by utilities.
+
+\subsubsection{Rate Selection}
+URDB contains electric rates that span all sectors (residential, commercial, industrial, etc.), so we limited the rates to those applicable to commercial buildings. First, we filtered down to rates identified as serving the commercial sector and not supplied at transmission voltage. Second, we processed the utility rate names to eliminate rates serving non-building loads based on certain keywords. The list of keywords included Agriculture, Irrigation, Farming, Pump, Snow, Vehicle, Oil, Cotton Gin, Outdoor Light, Security Light, Street, Wholesale, Recreation, Heating (typically found in names of heating-only rates), Substation, and Electric Motor Standby. We downloaded the detailed rate structure data in JSON format for the selected 13,923 rates.
+
+Next, we fed each utility rate and an 8,760-hour electric consumption profile from a Small Hotel building energy model to NREL PySAM \citep{pysam} to calculate an annual electric bill. We eliminated rates with an annual average blended price below \$0.01/kWh. Upon reading the names and comments included with these rates, we found that they were mostly fixed rates for individual pieces of equipment such as cable or internet infrastructure that are not metered. We also eliminated rates with an annual average blended price above \$0.45/kWh, except in the case of AK or HI, which legitimately have high rates. Some of the high rates appeared to be data entry errors. We also removed rates where PySam could not calculate an annual bill based on the rate data. Overall, this process resulted in 10,623 remaining rates spread across 2,658 utilities. 90\% of the utilities have 8 or fewer rates. The remainder have more rates, with the most (~200) belonging to Southern California Edison. These rates cover 85\% of the buildings and 85\% of the floor area in ComStock. Rates are stored in machine-readable JSON format and organized by EIA Utility Identifier.
+
+A distribution of blended rates calculated using URDB was compared to a distribution of the blended rates calculated using data from EIA \citep{eia_electricity}. The median blended price in the URDB rates was about \$0.08/kWh, while the median blended price reported to EIA in 2022 was \$0.12/kWh, which is about 50\% higher than URDB. An analysis of the start date fields for the rates selected from URDB showed a median start date of 2013, which is more than ten years old at the time of writing.
+
+In order to understand the change in rates between 2013 and 2022, a pairwise analysis of the utilities reporting to EIA \citep{eia_electricity} in both years was performed, and a state-wide average annual change was calculated. The median increase was 1-3\% per year. Thus in many cases the rates have increased by (2\%/yr * (2022-2013)) = 18\% or more between 2013 and 2022.
+
+\subsubsection{Electric Utility Assignment}
+To assign an electric rate to a building in ComStock, we need to know which electric utility serves it. We joined the U.S. DOE Electric Utility Companies and Rates Look-up by Zipcode \citep{zip_to_util} with the U.S. HUD USPS ZIP Code Crosswalk Files \citep{tract_to_zip} to create a mapping between census tracts and utilities. This was done using both 2010 and 2020 census tracts, because ComStock uses a mix of both.
+As previously described, rates are assigned to 85\% of the buildings in ComStock, and cover 85\% of the weighted floor area. There are approximately 37,734 ZIP Codes in the United States. The dataset does not have an electric utility assignment for 738 of these ZIP Codes, which are spread across many states. There are 3,946 census tracts covered by these ZIP Codes which therefore do not have an electric utility assigned. Manually filling these missing mappings could be done in future work.
+
+\subsubsection{Bill Calculation}
+At runtime, an 8,670-hour electric load profile is extracted from the building energy model. The annual min and max demand (kW) and annual energy consumption (kWh) are calculated. Based on the census tract, the electric utility EIA identifier is looked up. If rates are found for this utility, the rates are downselected based on the observed load profile any min/max demand or energy consumption qualifiers the rate may have. For example, some rates only apply to buildings with a minimum annual peak demand of 500 kW.
+For each of the remaining applicable rates, the annual bill is calculated using the 8,760 load profile and the PySAM utility rate calculation engine. This engine accounts for complex rate structures with demand charges, lookback periods, time-of-use rates, etc. To adjust for the lag in the rates on the URDB, the start date for rate is collected and the number of years between the start date and 2022 is calculated. The average annual price increase for the state where the building is located, which was calculated from Form EIA-861 data as previously described, is looked up. The annual bill is multiplied by this increase to estimate an adjustment to current 2022 rates.
+
+A median bill is calculated from all applicable rates. Any bill that is lower than 25\% of the median or higher than 200\% of the median is eliminated to avoid extreme bills. Although uncommon, in testing these extreme bills were found to be associated with rates whose names indicate they are likely not applicable to the building. For example, a ``large secondary general'' rate which has a high minimum demand charge is not likely applicable to a small retail customer. This step typically only affects the mean bill for a building +/- 10\%, so the other applicability criteria appear to be downselecting appropriate rates effectively. For each applicable rate, the name of the rate and the adjusted annual bill are reported. The minimum, maximum, mean, median, and count of all applicable bills is also reported.
+For buildings with no electric utility assigned, or for buildings where none of the stored rates are applicable, the annual bill is estimated using the 2022 EIA Form-861 \citep{eia_electricity} average prices based on the state the building is located in. While this method does not reflect the detailed rate structures and demand charges, it is a fallback for the 15\% of buildings in ComStock with no utility assigned.
+
+\subsection{Natural Gas Bills}
+For natural gas rates, no detailed database of rates was found. Therefore, instead of using detailed rates, natural gas pricing is assumed to be volumetric. 2022 U.S. EIA Natural Gas Prices - Commercial Price and U.S. EIA Heat Content of Natural Gas Delivered to Consumers \citep{eia_natural_gas} were used to create an energy price in dollars per kBtu. State-level prices range from \$0.007/kBtu in ID to \$0.048/kBtu in HI, with a mean of \$0.012/kBtu nationally.
+
+\subsection{Propane and Fuel Oil Bills}
+For propane and fuel oil, no detailed database of rates was found. Therefore, instead of using detailed rates, pricing for these fuels is assumed to be volumetric. These fuels are typically delivered in batches, so in any given year the number of deliveries could vary. Minimum charges per delivery are assumed to be included in the volumetric price. 2022 U.S. EIA residential No. 2 Distillate Prices by Sales Type and U.S. EIA residential Weekly Heating Oil and Propane Prices (October - March) \citep{eia_fuel_oil_and_propane} were downloaded, along with the EIA assumed heat content for these fuels. Residential prices were used because commercial prices are only available at the national scale. Additionally, most commercial buildings using these fuels are assumed to be smaller buildings where a residential rate is likely realistic. These data were used to create an energy price in dollars per kBtu for both fuels.
+
+For states where state-level pricing was available, these prices are used directly. For other states, Petroleum Administration for Defense District (PADD)-average pricing was used. For states where PADD-level pricing was not available, national average pricing was used. For propane, prices ranged from \$0.022/kBtu in ND to \$0.052 in FL, with a mean of \$0.032/kBtu nationally. For fuel oil, prices ranged from \$0.027/kBtu in NE to \$0.036 in DE, with a mean of \$0.033/kBtu nationally. The mean national price for both fuels is roughly three times the mean national price of natural gas.
+
+\subsection{District Heating and District Cooling Bills}
+No resources with utility rates for district heating and cooling were identified. Because there are several hundred district systems across the U.S., many of which are university or healthcare campuses, gathering individual rates manually was deemed impractical. Therefore, utility bills for these fuels are not calculated.

documentation/reference_doc/bibliography.bib

@@ -662,3 +662,47 @@ @article{heinemeier2014free
   journal      = {ACEEE Summer Study Energy Efficiency Build},
   year         = 2014
 }
+
+@misc{pysam,
+  title        = {NREL-PySAM Documentation},
+  author       = {{NREL}},
+  year         = 2023,
+  url          = {https://nrel-pysam.readthedocs.io/en/main/}
+}
+
+@techreport{urdb,
+  title        = {National Utility Rate Database: Preprint},
+  author       = {Ong, Sean and McKeel, Ryan},
+  institution  = {National Renewable Energy Laboratory},
+  doi          = {10.2172/1050105},
+  url          = {https://www.osti.gov/biblio/1050105},
+  year         = 2012,
+  month        = 1
+}
+
+@misc{zip_to_util,
+  author       = {Huggins, Jay},
+  institution  = {National Renewable Energy Laboratory},
+  title        = {U.S. Electric Utility Companies and Rates: Look-up by Zipcode (2021)},
+  year         = 2021,
+  url          = {https://catalog.data.gov/dataset/u-s-electric-utility-companies-and-rates-look-up-by-zipcode-2021},
+  note         = {Accessed: 2024-01-08}
+}
+
+@misc{tract_to_zip,
+  author       = {{HUD PD&R}},
+  institution  = {U.S. Department of Housing and Urban Development Office of Policy Development and Research},
+  title        = {HUD USPS ZIP CODE CROSSWALK FILES},
+  year         = 2023,
+  url          = {https://www.huduser.gov/portal/datasets/usps_crosswalk.html},
+  note         = {Accessed: 2024-01-08}
+}
+
+@misc{eia_fuel_oil_and_propane,
+  author       = {{U.S. Energy Information Administration}},
+  shortauthor  = {EIA},
+  title        = {Petroleum and Other Liquids},
+  year         = 2023,
+  url          = {https://www.eia.gov/dnav/pet/pet_pri_dist_a_epd2_prt_dpgal_a.htm},
+  note         = {Accessed: 2023-12-20}
+}