architecture.rst

Architecture

The key ResStock workflow components are described below.

Projects

At the top level of the ResStock repository you just downloaded, you will see two analysis project folders:

• project_national
• project_testing

The national project contains inputs describing the existing residential building stock. The testing project contains inputs to test our OpenStudio workflows. Within each project folder are sample "baseline" and "upgrades" input files that may serve as examples for how to set up different types of ResStock analyses. The contents of the input file ultimately determines the set of workflow steps (i.e., OpenStudio measures) for each ResStock sample. See run_project for more information about running ResStock analyses.

Sampling

To run the sampling script yourself, from the command line execute, e.g. ruby resources/run_sampling.rb -p project_national -n 10000 -o buildstock.csv, and a file buildstock.csv will be created in the resources directory.

If a custom buildstock.csv file is located in a project's housing_characteristics directory when you run the project, it will automatically be used to generate simulations. If it’s not found, the sampling will be run automatically to create one. For each datapoint, the measure will then look up its building description from the sampled csv.

You can use this manual sampling process to downselect which simulations you want to run. For example, you can use the command above to generate a buildstock.csv for the entire U.S. and then open up this file in Excel and delete all of the rows that you don't want to simulate (e.g., all rows that aren't in New York). Keep in mind that if you do this, you will need to re-enumerate the "Building" column as "1" through the number of rows.

Measures

ResStock uses a mixture of both OpenStudio Model and Reporting measures in its workflow. The following depicts the order in which workflow measure steps are applied:

Index	Measure	Measure Type	Optional	Notes	Source
1	BuildExistingModel	Model	No	Meta measure	ResStock
2 3 4 5 6 7 8 9 10	ApplyUpgrade HPXMLtoOpenStudio Other Model Measures ReportSimulationOutput ReportHPXMLOutput ReportUtilityBills UpgradeCosts Other Reporting Measures ServerDirectoryCleanup	Model Model Model Reporting Reporting Reporting Reporting Reporting Reporting	Yes No Yes No No No No Yes No	Meta measure	ResStock OS-HPXML Any OS-HPXML ResStock OS-HPXML ResStock Any ResStock

The BuildExistingModel and ApplyUpgrade meta measures call the following model measures:

Index	Measure	Measure Type	Optional	Notes	Source
1 2 3	ResStockArguments BuildResidentialHPXML BuildResidentialScheduleFile	Model Model Model	No No No		ResStock OS-HPXML OS-HPXML

Model Measures

Model measures are applied before the simulation is run. They contribute to the generation of the model.

BuildExistingModel

BuildExistingModel is a meta measure; meaning, it incrementally applies other measures (i.e., ResStockArguments, BuildResidentialHPXML, and BuildResidentialScheduleFile) to create "baseline" residential models.

ResStockArguments

BuildResidentialHPXML

BuildResidentialScheduleFile

ApplyUpgrade

This measure can be optionally applied to the workflow. Like the BuildExistingModel measure, ApplyUpgrade is a meta measure; it, too, incrementally applies other measures (i.e., ResStockArguments, BuildResidentialHPXML, and BuildResidentialScheduleFile) to create "upgraded" residential models.

Each instance of the ApplyUpgrade measure defines an upgrade scenario. An upgrade scenario is a collection of options exercised with some logic and costs applied. In the simplest case, we apply the new option to all housing units. The available upgrade options are in resources/options_lookup.tsv in your git repository. For this example, we will upgrade all windows by applying the Windows|Triple, Low-E, Non-metal, Air, L-Gain option to all houses across the country. We do this by entering that in the Option 1 box on the Apply Upgrade measure. Also, we'll give the upgrade scenario a name: "Triple-Pane Windows" and a cost of $40/ft² of window area by entering the number in Option 1 Cost Value and selecting "Window Area (ft^2)" for Option 1 Cost Multiplier. Like the downselect logic, excluded datapoints (i.e., datapoints for which the upgrade does not apply) will result in "completed invalid workflow". Note that using no downselect logic will apply the option to all housing units. For a full explanation of how to set up the options and logic surrounding them, see ../upgrade_scenario_config.

HPXMLtoOpenStudio

See also OpenStudio-HPXML Workflow Inputs for documentation on workflow inputs.

Other Model Measures

Additional model measures can be optionally applied to the workflow. They are applied following generation of the model, but before any reporting measures.

Reporting Measures

Reporting measures are applied after the simulation is run. They process and report simulation output.

ReportSimulationOutput

ReportHPXMLOutput

ReportUtilityBills

UpgradeCosts

Other Reporting Measures

Additional reporting measures (e.g., QOIReport) can be optionally applied to the workflow. They are applied following all standard reporting measures, but before the ServerDirectoryCleanup measure.

ServerDirectoryCleanup