About this Document
This document describes changes between buildstockbatch version 0.19 and buildstockbatch version 0.20
This guide introduces what's new in buildstockbatch version 0.20 and also documents changes which affect users migrating their analyses from 0.19.
Please carefully review the section on schema changes as the minimum schema version has been updated to the new version, 0.3, and there are non-backwards-compatible changes in the schema update.
The input schema has been updated to version 0.3. Project configuration files will need to be upgraded to use the new format. The schema_version
key now needs to be a string, so put some quotes around the version number.
schema_version: '0.3'
There are no more stock_type
, sampling_algorithm
, or downselect
keys. This information is defined in the new sampler
and workflow
keys.
The sampler now has its own section in the configuration file. In it, you specify which kind of sampler to use and the arguments to pass to it. These arguments used to be scattered all around the project configuration file and it caused some confusion when arguments would only apply to some kinds of samplers. They are now consolidated under the sampler
key and each sampler type specifies its own options. Complete documentation of the available samplers and their arguments is at ../samplers/index
.
Here are a few examples for common scenarios:
See ../samplers/residential_quota
.
Old Spec:
schema_version: 0.2
stock_type: residential
baseline:
sampling_algorithm: quota
n_datapoints: 350000
New Spec:
schema_version: '0.3'
sampler:
type: residential_quota
args:
n_datapoints: 350000
Downselecting is no longer a separate config item, it is implemented in a different sampler type. See ../samplers/residential_quota_downselect
.
Old Spec:
schema_version: 0.2
stock_type: residential
baseline:
sampling_algorithm: quota
n_datapoints: 350000
downselect:
logic:
- Geometry Building Type RECS|Single-Family Detached
- Vacancy Status|Occupied
resample: false
New Spec:
schema_version: '0.3'
sampler:
type: residential_quota_downselect
args:
n_datapoints: 350000
logic:
- Geometry Building Type RECS|Single-Family Detached
- Vacancy Status|Occupied
resample: false
The baseline.precomputed_sample
key has been removed and the precomputed sampling is its own sampler type. Downselecting is no longer permitted with a precomputed sample. If you want to downselect, please modify your buildstock.csv file to only include the buildings you want in your sample. See ../samplers/precomputed
.
Old Spec:
schema_version: 0.2
stock_type: residential
baseline:
precomputed_sample: path/to/buildstock.csv
n_datapoints: 350000
New Spec:
schema_version: '0.3'
sampler:
type: precomputed
args:
sample_file: path/to/buildstock.csv # n_datapoints determined from csv file
The workflow generator has changed as well. Many inputs to the workflow were previously at the top level in the project configuration file. This was again confusing because different config entries only applied to certain workflow generators. In previous versions, the appropriate workflow generator was inferred based on the stock_type
key. Now it is explicitly defined and the arguments to be passed to it are defined under the workflow_generator
key. See ../workflow_generators/index
.
Old Spec:
schema_version: 0.2
stock_type: residential
timeseries_csv_export:
reporting_frequency: Hourly
include_enduse_subcategories: true
New Spec:
schema_version: '0.3'
workflow_generator:
type: residential_default
args:
timeseries_csv_export:
reporting_frequency: Hourly
include_enduse_subcategories: true
The reporting_measures
configuration key that now resides under workflow_generator.args
allows measure arguments to be passed to reporting measures.
Old Spec:
schema_version: 0.2
stock_type: residential
reporting_measures:
- ReportingMeasure1
- ReportingMeasure2
New Spec:
schema_version: '0.3'
workflow_generator:
type: residential_default
args:
reporting_measures:
- measure_dir_name: ReportingMeasure1
arguments:
arg1: value
- measure_dir_name: ReportingMeasure2
The commercial workflow generator has changed to remove most of the hard-coded reporting measures, allowing them to be added to the config file as-needed. This should avoid the need to create custom BuildStockBatch environments for each project that needs to add/remove/modify reporting measures.
Old hard-coded reporting measures:
SimulationOutputReport
- OpenStudio Results (measure_dir_name:
f8e23017-894d-4bdf-977f-37e3961e6f42
) TimeseriesCSVExport
comstock_sensitivity_reports
qoi_report
la_100_qaqc
(if include_qaqc = true in config)simulation_settings_check
(if include_qaqc = true in config)
New hard-coded reporting measures:
SimulationOutputReport
(reports annual totals in results.csv)TimeseriesCSVExport
(generates timeseries results at Timestep frequency)
Two other hard-coded model measures were removed from the workflow. These will be added to the workflow via the options-lookup.tsv in ComStock instead.
Removed hard-coded model measures:
add_blinds_to_selected_windows
set_space_type_load_subcategories
In an effort to use more appropriate language, in the aws-config
, we renamed the following keys under aws.emr
:
Old Name | New Name |
---|---|
master_instance_type | manager_instance_type |
slave_instance_type | worker_instance_type |
slave_instance_count | worker_instance_count |
For some applications it is helpful to keep the timeseries parquet files for each simulation. Normally, they are aggregated into fewer, larger files. There was a key introduced in v0.19.1 that enabled this. We moved it to a new home place in the config file.
Old Spec:
schema_version: 0.2
eagle:
postprocessing:
keep_intermediate_files: true # default false if omitted
New Spec:
schema_version: '0.3'
postprocessing:
keep_individual_timeseries: true # default false if omitted