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 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 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.
Note: OS-HPXML default values can be found in the OS-HPXML 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 theWindows|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/ft2 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.