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 the Project for more information about running ResStock analyses.

Sampling

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

If a custom buildstock.csv file is referenced using the precomputed sampler when you run the project, it will be used as the basis for generating simulation datapoints. Alternatively by using other (non-precomputed) quota-based samplers, the sampling will be run automatically to create a buildstock.csv file. For each simulation datapoint, the workflow will then look up its building description from the sampled buildstock.csv file.

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	ApplyUpgrade	Model	Yes [1]	Meta measure	ResStock
3	HPXMLtoOpenStudio	Model	No		OS-HPXML [2]
4	Other Model Measures	Model	Yes		Any [3]
5	ReportSimulationOutput	Reporting	No		OS-HPXML
6	ReportHPXMLOutput	Reporting	No		ResStock
7	ReportUtilityBills	Reporting	No		OS-HPXML
8	UpgradeCosts	Reporting	No		ResStock
9	Other Reporting Measures	Reporting	Yes		Any [4]
10	ServerDirectoryCleanup	Reporting	No		ResStock

[1]

Baseline models with no upgrades do not have the ApplyUpgrade measure applied.

[2]

OS-HPXML refers to the OpenStudio-HPXML repository.

[3]

Other Model Measures do not need to originate from ResStock, but it is up to the user to ensure they work within the ResStock workflow.

[4]

Other Reporting Measures do not need to originate from ResStock, but it is up to the user to ensure they work within the ResStock workflow.

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

Index	Measure	Measure Type	Optional	Notes	Source
1	ResStockArguments	Model	No		ResStock
2	BuildResidentialHPXML	Model	No		OS-HPXML
3	BuildResidentialScheduleFile	Model	No		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.

Builds the OpenStudio Model for an existing building.

Builds the OpenStudio Model using the sampling csv file, which contains the specified parameters for each existing building. Based on the supplied building number, those parameters are used to run the OpenStudio measures with appropriate arguments and build up the OpenStudio model.

ResStockArguments

Measure that pre-processes the arguments passed to the BuildResidentialHPXML and BuildResidentialScheduleFile measures.

Passes in all arguments from the options lookup, processes them, and then registers values to the runner to be used by other measures.

BuildResidentialHPXML

Builds a residential HPXML file.

The measure handles geometry by 1) translating high-level geometry inputs (conditioned floor area, number of stories, etc.) to 3D closed-form geometry in an OpenStudio model and then 2) mapping the OpenStudio surfaces to HPXML surfaces (using surface type, boundary condition, area, orientation, etc.). Like surfaces are collapsed into a single surface with aggregate surface area. Note: OS-HPXML default values can be found in the documentation or can be seen by using the ‘apply_defaults’ argument.

BuildResidentialScheduleFile

Builds a residential schedule file.

Generates a CSV of schedules at the specified file path, and inserts the CSV schedule file path into the output HPXML file (or overwrites it if one already exists). Stochastic schedules are generated using time-inhomogeneous Markov chains derived from American Time Use Survey data, and supplemented with sampling duration and power level from NEEA RBSA data as well as DHW draw duration and flow rate from Aquacraft/AWWA data.

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.

Measure that applies an upgrade (one or more child measures) to a building model based on the specified logic.

Determines if the upgrade should apply to a given building model. If so, calls one or more child measures with the appropriate arguments.

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 Configuration.

HPXMLtoOpenStudio

Translates HPXML file to OpenStudio Model

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

Reports simulation outputs for residential HPXML-based models.

Processes EnergyPlus simulation outputs in order to generate an annual output file and an optional timeseries output file.

ReportHPXMLOutput

Reports HPXML outputs for residential HPXML-based models.

Parses the HPXML file and reports pre-defined outputs.

ReportUtilityBills

Calculates and reports utility bills for residential HPXML-based models.

Calculate electric/gas utility bills based on monthly fixed charges and marginal rates. Calculate other utility bills based on marginal rates for oil, propane, wood cord, wood pellets, and coal. User can specify PV compensation types of ‘Net-Metering’ or ‘Feed-In Tariff’, along with corresponding rates and connection fees.

UpgradeCosts

Measure that calculates upgrade costs.

Multiplies cost value by cost multiplier.

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

Optionally removes a significant portion of the saved results from each run, helping to alleviate memory problems.