Add ResStock Technical Reference Guide

.github/pull_request_template.md

@@ -10,7 +10,7 @@
 ## Checklist
 
 #### Required:
-- [ ] [Technical reference documentation](https://github.com/NREL/resstock/tree/develop/docs/read_the_docs) has been updated
+- [ ] [Technical reference guide](https://github.com/NREL/resstock/tree/develop/docs/technical_reference_guide) has been updated
 - [ ] Add to the [changelog_dev.rst file](https://github.com/NREL/resstock/tree/develop/docs/read_the_docs/source/changelog/changelog_dev.rst)
 - [ ] No unexpected regression test changes on CI (comparison artifacts have been checked)
 
@@ -21,4 +21,5 @@
   - [ ] [source report](https://github.com/NREL/resstock/tree/develop/project_national/resources/source_report.csv)
   - [ ] [options saturation](https://github.com/NREL/resstock/tree/develop/project_national/resources/options_saturations.csv)
   - [ ] [options_lookup](https://github.com/NREL/resstock/blob/develop/resources/options_lookup.tsv)
-- [ ] `openstudio tasks.rb update_measures` has been run
+- [ ] `openstudio tasks.rb update_measures` has been run
+- [ ] Update [read_the_docs](https://github.com/NREL/resstock/tree/develop/docs/read_the_docs)

.github/workflows/config.yml

@@ -349,20 +349,26 @@ jobs:
           path: test/tests_yml_files
           name: precomputed_buildstocks
 
-      - name: Build documentation
+      - name: Build Read The Docs
         run: |
           sudo gem install oga
           ruby docs/read_the_docs/source/workflow_inputs/create_characteristics_rst.rb
           ruby docs/read_the_docs/source/workflow_outputs/csv_tables.rb
           cd docs/read_the_docs
           pip install changelog
           make html SPHINXOPTS="-W --keep-going -n"
-
-      - name: Save Docs
+      
+      - name: Save Read The Docs
         uses: actions/upload-artifact@v4
         with:
           name: documentation
           path: docs/read_the_docs/_build/html/
+
+      - name: Build technical reference guide
+        uses: dante-ev/latex-action@2023-A
+        with:
+          working_directory: docs/technical_reference_guide
+          root_file: ResStockTechnicalReferenceGuide.tex
 
       - name: Commit latest results
         shell: bash        

.gitignore

@@ -1,4 +1,18 @@
 /docs/read_the_docs/_build
+/docs/technical_reference_guide/ResStockTechnicalReferenceGuide.aux
+/docs/technical_reference_guide/ResStockTechnicalReferenceGuide.bcf
+/docs/technical_reference_guide/ResStockTechnicalReferenceGuide.lof
+/docs/technical_reference_guide/ResStockTechnicalReferenceGuide.log
+/docs/technical_reference_guide/ResStockTechnicalReferenceGuide.lot
+/docs/technical_reference_guide/ResStockTechnicalReferenceGuide.out
+/docs/technical_reference_guide/ResStockTechnicalReferenceGuide.run.xml
+/docs/technical_reference_guide/ResStockTechnicalReferenceGuide.toc
+/docs/technical_reference_guide/ResStockTechnicalReferenceGuide.upa
+/docs/technical_reference_guide/ResStockTechnicalReferenceGuide.bbl
+/docs/technical_reference_guide/ResStockTechnicalReferenceGuide.blg
+/docs/technical_reference_guide/ResStockTechnicalReferenceGuide.fdb_latexmk
+/docs/technical_reference_guide/ResStockTechnicalReferenceGuide.fls
+/docs/technical_reference_guide/ResStockTechnicalReferenceGuide.upb
 /lib
 /measures/UpgradeCosts/tests/in*
 /measures/UpgradeCosts/tests/*.xml

docs/read_the_docs/source/changelog/changelog_dev.rst

@@ -10,7 +10,25 @@ Development Changelog
         :pullreq: 1325
         :tickets: resstock-estimation 437
 
-        **Date**: 2024-11-19
+        **Date**: 2025-1-11
+
+        Title:
+        Add ResStock Technical Reference Guide
+
+        Description:
+        Add the ResStock Technical Reference Guide to the repository and compile it on github actions to keep the pdf up to date.
+
+        Assignees: Anthony Fontanini
+
+        :tags: ci, docs, technical reference guide
+        :pullreq: 1338
+
+    .. change::
+        :tags: feature, characteristics
+        :pullreq: 1325
+        :tickets: resstock-estimation 437
+
+        **Date**: 2024-12-30
 
         Title:
         Well pump distribution using AHS

docs/technical_reference_guide/1_Introduction.tex

@@ -0,0 +1,37 @@
+\chapter{Introduction}
+
+ResStock\textsuperscript{TM} is the foundational national residential building stock energy model for the United States. ResStock is a highly granular, bottom-up, physics-based model that uses best-available data sources on American housing, statistical sampling methods, and advanced building energy simulations in EnergyPlus\textsuperscript{\textregistered} to model the annual subhourly energy consumption of the residential building stock across the United States with high spatial granularity. ResStock's companion model, ComStock, covers the commercial building stock of the United States.
+
+Many of the internal workings of these models are distinct, but the results and types of analyses that can be done with them are similar. Documentation for ComStock can be found on the \href{https://nrel.github.io/ComStock.github.io/}{ComStock website}.
+
+ResStock represents all types of housing units, including single-family, multifamily, and manufactured or mobile homes. The definition of the residential sector follows the U.S.~Energy Information Administration's (EIA) definition of \textit{housing unit} and therefore does not include dormitories, prisons, assisted care facilities, and other congregate housing situations, but does include high-rise multifamily buildings that are sometimes considered commercial buildings for the purpose of building codes~\citep{eia_recs2024}.
+
+This report serves as the primary documentation of the methodology and assumptions of ResStock. It is updated with each ResStock software release or ResStock standard data release.
+
+\section{Overview and Primary Use Applications}
+
+ResStock answers two primary questions: (1) How and when is energy used in the U.S.~residential building stock? and (2) What are the impacts of technological and behavioral changes in U.S.~homes? Specifically, ResStock quantifies energy use across geographical locations, demographic groups, building types, fuels, end uses, and time of day. Additionally, it details the impact of efficiency, fuel changes, or flexibility measures: total changes in the amount of energy used by measure; where or in what use cases efficiency or technology change measures save energy; when or at what times of day savings occur; and which building stock or demographic segments have the biggest savings potential.
+
+This type of building stock energy model can be conducted using a range of approaches, varying on a spectrum from simple representation and fast execution or complex representation and slow execution. Each approach has benefits and trade-offs. The National Energy Modeling System used by the EIA is an example of a simple, fast method. This system models the entire U.S.~energy system at the census region level, and its results for the building stock have low spatial, temporal, and subsector granularity. On the other hand, modeling each individual building within the building stock is an example of a complex, slow method. This approach is impossible to implement in practice due to the lack of building-level data necessary to develop the model, and can lead to false confidence in results if not underpinned by appropriate data. Additionally, if appropriate data did exist and the model could be developed, this approach would offer a high granularity of results, but gives more detail than is needed for most applications and is highly impractical to update or run frequently.
+
+The ResStock approach is positioned between these two extremes, providing highly granular housing stock data to capture the diversity of housing and occupants while maintaining a usable execution speed. Three advantages of the ResStock approach are: (1) subhourly detail; (2) modeling of upgrade measure interaction, controls, and demand flexibility; and (3) the ability to post-process the data to slice results (e.g., by location, household income, fuel types, building size) and extract a wide array of insights from the simulations, including distributional impacts---how costs and benefits are distributed across different groups of households. This approach strikes a balance by presenting enough information to answer its two driving questions while remaining computationally tractable.  
+
+Professionals and researchers have several pathways for using ResStock data and insights. They can review published fact sheets and reports based upon ResStock data, query a web-based visualization platform to view annual and timeseries results, or use a simple spreadsheet-type analysis to investigate annual energy consumption results and aggregated timeseries load profiles. If users want to go deeper, they can use the raw simulation results dataset, which requires comfort dealing with large datasets and potentially cloud or high-performance computing assets. All of these approaches to using ResStock are supported by the ResStock team, which can be contacted at \\
+\href{mailto:[email protected]}{[email protected]}. Because all ResStock inputs are publicly available, it is also theoretically possible for users to run ResStock themselves using their own computing resources and weather files. However, the ResStock team is not able to provide support for external users running ResStock software because of the significant burden it would impose on staff time and budget. We encourage users to use the publicly released datasets, visualizations, and analysis products that receive rigorous review for quality assurance and control.
+
+\section{ResStock Calibration and Validation}
+Calibration and validation have been core components of ResStock since its inception. In 2014, initial validation efforts focused on comparing estimates of average annual electricity and gas use per home to EIA Residential Energy Consumption Survey (RECS) 2009 microdata for cohorts of single-family detached homes grouped by combinations of region, vintage, and fuel type (see Section 2.6 in \cite{Wilson2017}). Visual comparisons of cumulative distribution functions for energy use, along with Kolmogorov–Smirnov tests for goodness of fit, were used to validate heterogeneity in model outputs. In 2015, the initial year-long calibration effort involved 12 rounds of model structure and input modifications to improve agreement with RECS 2009 data. Examples of these modifications include: adding new data sources for probability distributions, changing dependencies for housing characteristic probability distributions, changing the number of probability distribution options, and reducing the number of weather locations (to allow additional granularity in other areas). 
+
+Calibration and validation efforts expanded to include hourly timeseries outputs in 2019--2022. As part of a three-year U.S. Department of Energy (DOE)-funded project, we compared ResStock results to data from a wide range of sources such as utility load research data, advanced metering infrastructure data, and end-use submetered data to inform modeling improvements, and validated the updated model. ComStock also went through this process as part of the same project. These data sources, as well as the comparison plots and accompanying discussion, are described in detail in that project’s final report \citep{Wilson2022}. Since the publication of that report, additional modifications have been made to ResStock. These ongoing modifications are documented in this report.
+
+% Validation of individual technology models, e.g., ASHPs
+
+\section{ResStock Data Access}
+
+Access to ResStock data is provided in multiple formats. The current state of data access changes periodically and is maintained at the National Renewable Energy Laboratory (NREL) \href{https://resstock.nrel.gov/datasets}{ResStock website}.
+
+
+% PRIORITY B: \section{ResStock history (brief)}
+% Talk about previous versions
+
+% PRIORITY C: \section{Previous releases, timeline with links}