Merge branch 'develop' into docs-updates

NREL · Jan 22, 2025 · 7673aeb · 7673aeb
2 parents ab1a6c0 + cb024c5
commit 7673aeb
Show file tree

Hide file tree

Showing 95 changed files with 37,620 additions and 25 deletions.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -10,9 +10,11 @@
 ## Checklist
 
 #### Required:
-- [ ] [Technical reference documentation](https://github.com/NREL/resstock/tree/develop/docs/read_the_docs) 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)
+- [ ] Update documentation (one is required)
+     - [ ] [Technical reference guide](https://github.com/NREL/resstock/tree/develop/docs/technical_reference_guide)
+     - [ ] [Technical development guide](https://github.com/NREL/resstock/tree/develop/docs/technical_development_guide)
 
 #### Optional (not all items may apply):
 - [ ] Tests (and test files) have been updated

diff --git a/.github/workflows/config.yml b/.github/workflows/config.yml
@@ -349,20 +349,28 @@ jobs:
           path: test/tests_yml_files
           name: precomputed_buildstocks
 
-      - name: Build documentation
+      - name: Build technical development guide
         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
+          ruby docs/technical_development_guide/source/workflow_inputs/create_characteristics_rst.rb
+          ruby docs/technical_development_guide/source/workflow_outputs/csv_tables.rb
+          cd docs/technical_development_guide
           pip install changelog
           make html SPHINXOPTS="-W --keep-going -n"
+      
+      - name: Build technical reference guide
+        uses: dante-ev/latex-action@2023-A
+        with:
+          working_directory: docs/technical_reference_guide
+          root_file: ResStockTechnicalReferenceGuide.tex
 
-      - name: Save Docs
+      - name: Save documentation
         uses: actions/upload-artifact@v4
         with:
           name: documentation
-          path: docs/read_the_docs/_build/html/
+          path: |
+            docs/technical_development_guide/_build/html/
+            docs/technical_reference_guide/ResStockTechnicalReferenceGuide.pdf
 
       - name: Commit latest results
         shell: bash        

diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,19 @@
-/docs/read_the_docs/_build
+/docs/technical_development_guide/_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.pdf
+/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

diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -1,7 +1,7 @@
 version: 2
 
 sphinx:
-  configuration: docs/read_the_docs/source/conf.py
+  configuration: docs/technical_development_guide/source/conf.py
 
 build:
   os: "ubuntu-22.04"
@@ -10,4 +10,4 @@ build:
 
 python:
   install:
-    - requirements: docs/read_the_docs/requirements.txt
+    - requirements: docs/technical_development_guide/requirements.txt
diff --git a/docs/read_the_docs/source/advanced_tutorial/.gemrc b/docs/read_the_docs/source/advanced_tutorial/.gemrc
diff --git a/docs/read_the_docs/Makefile → docs/technical_development_guide/Makefile b/docs/read_the_docs/Makefile → docs/technical_development_guide/Makefile
diff --git a/docs/technical_development_guide/README.md b/docs/technical_development_guide/README.md
@@ -0,0 +1,53 @@
+# ResStock Technical Development Guide
+
+This folder contains the Read The Docs project for the ResStock Technical Development Guide.
+
+## GitHub Actions
+In the `.github/workflows/config.yml` file, the `updates-results` job `Build technical development guide` task compiles the project into the `_build/html` folder.
+This folder is then uploaded in the `Save technical development guide` task.
+These actions will help keep the document up to date with any changes and fail in the tests if the document does not compile.
+
+## Building Technical Development Guide Locally
+
+### Windows
+
+1. With the terminal/command prompt navigate to the resstock repository technical development guide directory.
+
+```
+cd <RESSTOCK_DIR>/docs/technical_development_guide
+```
+
+2. Install sphinx Read The Docs theme
+
+```
+pip install sphinx_rtd_theme
+```
+
+3. Build the documentation. HTML files will be created in the `docs/technical_development_guide/_build` directory
+
+```
+./make.bat html SPHINXOPTS="-W --keep-going -n"
+```
+
+### Mac
+
+1. With the terminal/command prompt navigate to the resstock repository technical development guide directory.
+
+```
+cd <RESSTOCK_DIR>/docs/technical_development_guide
+```
+
+2. Install sphinx Read The Docs theme and Sphinx Auto-build
+
+```
+pip install sphinx_rtd_theme
+pip install sphinx-autobuild
+```
+
+3. Build the documentation. HTML files will be created in the `docs/technical_development_guide/_build` directory. 
+
+```
+sphinx-autobuild source _build source/index.rst
+```
+
+4. The previous step will connect a server which can be opened in a browser. This server might look something like `http://127.0.0.1:8000`. Copy the address into your browser and the built documentation will show up. The `sphinx-autobuild` command will continue to check for changes to the documentation. So after future changes, the page in the browser should automatically reload to see changes to the source files.
diff --git a/docs/read_the_docs/make.bat → docs/technical_development_guide/make.bat b/docs/read_the_docs/make.bat → docs/technical_development_guide/make.bat
diff --git a/docs/read_the_docs/requirements.txt → ...hnical_development_guide/requirements.txt b/docs/read_the_docs/requirements.txt → ...hnical_development_guide/requirements.txt
diff --git a/.../advanced_tutorial/heat_pump_upgrades.rst → .../advanced_tutorial/heat_pump_upgrades.rst b/.../advanced_tutorial/heat_pump_upgrades.rst → .../advanced_tutorial/heat_pump_upgrades.rst
diff --git a/...d_tutorial/increasing_upgrade_options.rst → ...d_tutorial/increasing_upgrade_options.rst b/...d_tutorial/increasing_upgrade_options.rst → ...d_tutorial/increasing_upgrade_options.rst
diff --git a/...e_docs/source/advanced_tutorial/index.rst → ..._guide/source/advanced_tutorial/index.rst b/...e_docs/source/advanced_tutorial/index.rst → ..._guide/source/advanced_tutorial/index.rst
diff --git a/...ce/advanced_tutorial/openstudio_hpxml.rst → ...ce/advanced_tutorial/openstudio_hpxml.rst b/...ce/advanced_tutorial/openstudio_hpxml.rst → ...ce/advanced_tutorial/openstudio_hpxml.rst
diff --git a/...urce/advanced_tutorial/options_lookup.rst → ...urce/advanced_tutorial/options_lookup.rst b/...urce/advanced_tutorial/options_lookup.rst → ...urce/advanced_tutorial/options_lookup.rst
diff --git a/...ource/advanced_tutorial/running_tasks.rst → ...ource/advanced_tutorial/running_tasks.rst b/...ource/advanced_tutorial/running_tasks.rst → ...ource/advanced_tutorial/running_tasks.rst
diff --git a/...nced_tutorial/upgrade_scenario_config.rst → ...nced_tutorial/upgrade_scenario_config.rst b/...nced_tutorial/upgrade_scenario_config.rst → ...nced_tutorial/upgrade_scenario_config.rst
diff --git a/...cs/source/basic_tutorial/architecture.rst → ...de/source/basic_tutorial/architecture.rst b/...cs/source/basic_tutorial/architecture.rst → ...de/source/basic_tutorial/architecture.rst
diff --git a/..._the_docs/source/basic_tutorial/index.rst → ...ent_guide/source/basic_tutorial/index.rst b/..._the_docs/source/basic_tutorial/index.rst → ...ent_guide/source/basic_tutorial/index.rst
diff --git a/...cs/source/basic_tutorial/installation.rst → ...de/source/basic_tutorial/installation.rst b/...cs/source/basic_tutorial/installation.rst → ...de/source/basic_tutorial/installation.rst
diff --git a/...ocs/source/basic_tutorial/run_project.rst → ...ide/source/basic_tutorial/run_project.rst b/...ocs/source/basic_tutorial/run_project.rst → ...ide/source/basic_tutorial/run_project.rst
diff --git a/...docs/source/changelog/changelog_1_0_0.rst → ...uide/source/changelog/changelog_1_0_0.rst b/...docs/source/changelog/changelog_1_0_0.rst → ...uide/source/changelog/changelog_1_0_0.rst
diff --git a/...docs/source/changelog/changelog_2_0_0.rst → ...uide/source/changelog/changelog_2_0_0.rst b/...docs/source/changelog/changelog_2_0_0.rst → ...uide/source/changelog/changelog_2_0_0.rst
diff --git a/...docs/source/changelog/changelog_2_1_0.rst → ...uide/source/changelog/changelog_2_1_0.rst b/...docs/source/changelog/changelog_2_1_0.rst → ...uide/source/changelog/changelog_2_1_0.rst
diff --git a/...docs/source/changelog/changelog_2_2_0.rst → ...uide/source/changelog/changelog_2_2_0.rst b/...docs/source/changelog/changelog_2_2_0.rst → ...uide/source/changelog/changelog_2_2_0.rst
diff --git a/...docs/source/changelog/changelog_2_2_1.rst → ...uide/source/changelog/changelog_2_2_1.rst b/...docs/source/changelog/changelog_2_2_1.rst → ...uide/source/changelog/changelog_2_2_1.rst
diff --git a/...docs/source/changelog/changelog_2_2_2.rst → ...uide/source/changelog/changelog_2_2_2.rst b/...docs/source/changelog/changelog_2_2_2.rst → ...uide/source/changelog/changelog_2_2_2.rst
diff --git a/...docs/source/changelog/changelog_2_2_3.rst → ...uide/source/changelog/changelog_2_2_3.rst b/...docs/source/changelog/changelog_2_2_3.rst → ...uide/source/changelog/changelog_2_2_3.rst
diff --git a/...docs/source/changelog/changelog_2_2_4.rst → ...uide/source/changelog/changelog_2_2_4.rst b/...docs/source/changelog/changelog_2_2_4.rst → ...uide/source/changelog/changelog_2_2_4.rst
diff --git a/...docs/source/changelog/changelog_2_2_5.rst → ...uide/source/changelog/changelog_2_2_5.rst b/...docs/source/changelog/changelog_2_2_5.rst → ...uide/source/changelog/changelog_2_2_5.rst
diff --git a/...docs/source/changelog/changelog_2_3_0.rst → ...uide/source/changelog/changelog_2_3_0.rst b/...docs/source/changelog/changelog_2_3_0.rst → ...uide/source/changelog/changelog_2_3_0.rst
diff --git a/...docs/source/changelog/changelog_2_4_0.rst → ...uide/source/changelog/changelog_2_4_0.rst b/...docs/source/changelog/changelog_2_4_0.rst → ...uide/source/changelog/changelog_2_4_0.rst
diff --git a/...docs/source/changelog/changelog_2_5_0.rst → ...uide/source/changelog/changelog_2_5_0.rst b/...docs/source/changelog/changelog_2_5_0.rst → ...uide/source/changelog/changelog_2_5_0.rst
diff --git a/...docs/source/changelog/changelog_3_0_0.rst → ...uide/source/changelog/changelog_3_0_0.rst b/...docs/source/changelog/changelog_3_0_0.rst → ...uide/source/changelog/changelog_3_0_0.rst
diff --git a/...docs/source/changelog/changelog_3_1_0.rst → ...uide/source/changelog/changelog_3_1_0.rst b/...docs/source/changelog/changelog_3_1_0.rst → ...uide/source/changelog/changelog_3_1_0.rst
diff --git a/...docs/source/changelog/changelog_3_1_1.rst → ...uide/source/changelog/changelog_3_1_1.rst b/...docs/source/changelog/changelog_3_1_1.rst → ...uide/source/changelog/changelog_3_1_1.rst
diff --git a/...docs/source/changelog/changelog_3_2_0.rst → ...uide/source/changelog/changelog_3_2_0.rst b/...docs/source/changelog/changelog_3_2_0.rst → ...uide/source/changelog/changelog_3_2_0.rst
diff --git a/...docs/source/changelog/changelog_3_3_0.rst → ...uide/source/changelog/changelog_3_3_0.rst b/...docs/source/changelog/changelog_3_3_0.rst → ...uide/source/changelog/changelog_3_3_0.rst
diff --git a/...docs/source/changelog/changelog_3_4_0.rst → ...uide/source/changelog/changelog_3_4_0.rst b/...docs/source/changelog/changelog_3_4_0.rst → ...uide/source/changelog/changelog_3_4_0.rst
diff --git a/...e_docs/source/changelog/changelog_dev.rst → ..._guide/source/changelog/changelog_dev.rst b/...e_docs/source/changelog/changelog_dev.rst → ..._guide/source/changelog/changelog_dev.rst
@@ -5,12 +5,27 @@ Development Changelog
     :version: v3.5.0
     :released: pending
 
+    .. change::
+        :tags: ci, docs, technical reference guide, technical development guide
+        :pullreq: 1338
+        :tickets: resstock-estimation 437
+
+        **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
+
     .. change::
         :tags: feature, characteristics
         :pullreq: 1325
         :tickets: resstock-estimation 437
 
-        **Date**: 2024-11-19
+        **Date**: 2024-12-30
 
         Title:
         Well pump distribution using AHS
@@ -22,6 +37,7 @@ Development Changelog
 
         Assignees: Lixi Liu
 
+    .. change::
         :tags: characteristics, pool heater
         :pullreq: 1324
 

diff --git a/.../read_the_docs/source/changelog/index.rst → ...elopment_guide/source/changelog/index.rst b/.../read_the_docs/source/changelog/index.rst → ...elopment_guide/source/changelog/index.rst
diff --git a/docs/read_the_docs/source/conf.py → ...echnical_development_guide/source/conf.py b/docs/read_the_docs/source/conf.py → ...echnical_development_guide/source/conf.py
@@ -154,7 +154,7 @@ def setup(app):
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'ResStock.tex', u'ResStock Documentation',
+    (master_doc, 'ResStock.tex', u'ResStock Technical Development Guide',
      u'NREL', 'manual'),
 ]
 
@@ -164,7 +164,7 @@ def setup(app):
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'resstock', u'ResStock Documentation',
+    (master_doc, 'resstock', u'ResStock Technical Development Guide',
      [author], 1)
 ]
 
@@ -175,7 +175,7 @@ def setup(app):
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'ResStock', u'ResStock Documentation',
+    (master_doc, 'ResStock', u'ResStock Technical Development Guide',
      author, 'ResStock', 'One line description of project.',
      'Miscellaneous'),
 ]

diff --git a/docs/read_the_docs/source/images/logo.jpg → ..._development_guide/source/images/logo.jpg b/docs/read_the_docs/source/images/logo.jpg → ..._development_guide/source/images/logo.jpg
diff --git a/docs/read_the_docs/source/index.rst → ...hnical_development_guide/source/index.rst b/docs/read_the_docs/source/index.rst → ...hnical_development_guide/source/index.rst
@@ -3,8 +3,8 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-ResStock Documentation
-======================
+ResStock Technical Development Guide
+====================================
 
 .. note::
   Most people who use ResStock for analysis do so by using the datasets published to the `ResStock Data Viewer <https://resstock.nrel.gov>`_.

diff --git a/...ad_the_docs/source/nstatic/stylesheet.css → ...pment_guide/source/nstatic/stylesheet.css b/...ad_the_docs/source/nstatic/stylesheet.css → ...pment_guide/source/nstatic/stylesheet.css
diff --git a/...ource/workflow_inputs/characteristics.rst → ...ource/workflow_inputs/characteristics.rst b/...ource/workflow_inputs/characteristics.rst → ...ource/workflow_inputs/characteristics.rst
diff --git a/...flow_inputs/create_characteristics_rst.rb → ...flow_inputs/create_characteristics_rst.rb b/...flow_inputs/create_characteristics_rst.rb → ...flow_inputs/create_characteristics_rst.rb
diff --git a/...the_docs/source/workflow_inputs/index.rst → ...nt_guide/source/workflow_inputs/index.rst b/...the_docs/source/workflow_inputs/index.rst → ...nt_guide/source/workflow_inputs/index.rst
diff --git a/...s/modifying_probability_distributions.rst → ...s/modifying_probability_distributions.rst b/...s/modifying_probability_distributions.rst → ...s/modifying_probability_distributions.rst
diff --git a/...nputs/writing_housing_characteristics.rst → ...nputs/writing_housing_characteristics.rst b/...nputs/writing_housing_characteristics.rst → ...nputs/writing_housing_characteristics.rst
diff --git a/...ocs/source/workflow_outputs/csv_tables.rb → ...ide/source/workflow_outputs/csv_tables.rb b/...ocs/source/workflow_outputs/csv_tables.rb → ...ide/source/workflow_outputs/csv_tables.rb
diff --git a/...ow_outputs/csv_tables/characteristics.csv → ...ow_outputs/csv_tables/characteristics.csv b/...ow_outputs/csv_tables/characteristics.csv → ...ow_outputs/csv_tables/characteristics.csv
diff --git a/...ow_outputs/csv_tables/component_loads.csv → ...ow_outputs/csv_tables/component_loads.csv b/...ow_outputs/csv_tables/component_loads.csv → ...ow_outputs/csv_tables/component_loads.csv
diff --git a/...w_outputs/csv_tables/cost_multipliers.csv → ...w_outputs/csv_tables/cost_multipliers.csv b/...w_outputs/csv_tables/cost_multipliers.csv → ...w_outputs/csv_tables/cost_multipliers.csv
diff --git a/...workflow_outputs/csv_tables/emissions.csv → ...workflow_outputs/csv_tables/emissions.csv b/...workflow_outputs/csv_tables/emissions.csv → ...workflow_outputs/csv_tables/emissions.csv
diff --git a/...flow_outputs/csv_tables/other_outputs.csv → ...flow_outputs/csv_tables/other_outputs.csv b/...flow_outputs/csv_tables/other_outputs.csv → ...flow_outputs/csv_tables/other_outputs.csv
diff --git a/...w_outputs/csv_tables/other_timeseries.csv → ...w_outputs/csv_tables/other_timeseries.csv b/...w_outputs/csv_tables/other_timeseries.csv → ...w_outputs/csv_tables/other_timeseries.csv
diff --git a/...orkflow_outputs/csv_tables/qoi_report.csv → ...orkflow_outputs/csv_tables/qoi_report.csv b/...orkflow_outputs/csv_tables/qoi_report.csv → ...orkflow_outputs/csv_tables/qoi_report.csv
diff --git a/...outputs/csv_tables/simulation_outputs.csv → ...outputs/csv_tables/simulation_outputs.csv b/...outputs/csv_tables/simulation_outputs.csv → ...outputs/csv_tables/simulation_outputs.csv
diff --git a/...flow_outputs/csv_tables/utility_bills.csv → ...flow_outputs/csv_tables/utility_bills.csv b/...flow_outputs/csv_tables/utility_bills.csv → ...flow_outputs/csv_tables/utility_bills.csv
diff --git a/...urce/workflow_outputs/default_outputs.rst → ...urce/workflow_outputs/default_outputs.rst b/...urce/workflow_outputs/default_outputs.rst → ...urce/workflow_outputs/default_outputs.rst
diff --git a/...he_docs/source/workflow_outputs/index.rst → ...t_guide/source/workflow_outputs/index.rst b/...he_docs/source/workflow_outputs/index.rst → ...t_guide/source/workflow_outputs/index.rst
diff --git a/...rce/workflow_outputs/optional_outputs.rst → ...rce/workflow_outputs/optional_outputs.rst b/...rce/workflow_outputs/optional_outputs.rst → ...rce/workflow_outputs/optional_outputs.rst
diff --git a/docs/technical_reference_guide/1_Introduction.tex b/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}