What’s new in buildstockbatch 0.20?

About this Document

This document describes changes between buildstockbatch version 0.19 and buildstockbatch version 0.20

Introduction

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.

General

Schema Version 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.

Sampler Specification

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.

Here are a few examples for common scenarios:

Residential Quota Sampling

See Residential Quota Sampler.

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

Residential Quota with Downselecting

Downselecting is no longer a separate config item, it is implemented in a different sampler type. See Residential Quota Downselect Sampler.

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

Precomputed Sampling

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 Precomputed Sampler.

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

Workflow Generator Specification

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.

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_hpxml
  args:
    timeseries_csv_export:
      reporting_frequency: Hourly
      include_enduse_subcategories: true

Reporting Measures in Workflows

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

Commercial Workflow Generator Hard-Coded Measures

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

AWS EMR Configuration Name Changes

In an effort to use more appropriate language, in the AWS Configuration, 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

Keep Individual Timeseries

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