What’s new in buildstockbatch 0.18?¶
About this Document
This document describes changes between buildstockbatch version 0.17 and buildstockbatch version 0.18
Introduction¶
This guide introduces what’s new in buildstockbatch version 0.18 and also documents changes which affect users migrating their analyses from 0.17.
Please carefully review the section on schema changes as the minimum schema version has been updated to the new version, 0.2, and there are non-backwards-compatible changes in the schema update.
General¶
Changelog and Migration Documentation¶
We have added in changelogs and migration guides to assist folks updating from one version of buildstockbatch to the next! Please review these as they will significantly minimize annoyance and churn. All new pull requests will additionally need to add a changelog entry to the changelog_dev.rst file (a template exists in said file) so that upon release of the next version we can drag and drop in the relevant updates and create a migration guide.
Schema Version Update¶
Schema version 0.2 has been release and is required for version 0.18. There are several non-backwards-compatible changes that have been implemented. Happily these do not require significant changes in configuration yamls! So, what changes were made?
The
schema_version
key, previously not required, is now required. This is important since we now have more than a single schema version to keep track of.The
n_datapoints
key in thebaseline
section, previously not required, is now required.The minimum version for the
schema_version
key for this release (0.18) has been updated to0.2
which will force all project yamls to be updated.The precomputed sampling interface has been overhauled and the desired sampler now must be specified. When trying to use a precomputed buildstock.csv file use the
precomputed
sampler; for the default residential quota sampler usequota
; for commercial dynamic sampling (please don’t do this here btw ~Ry) usesobol
.
All users should fall into one of two camps at this point: running the residential quota sampler or specifying the buildstock.csv file to be executed. Three before and afters are presented:
Using the quota sampler¶
The relevant before section should look something like:
baseline:
n_datapoints: 1234
This needs to be updated to include the schema_version
key, and the sampling_algorithm
key. The new schema would
now look like:
baseline:
sampling_algorithm: quota
n_datapoints: 1234
schema_version: 0.2
Using a precomputed sample - Residential¶
The relevant before section should look something like:
baseline:
buildstock_csv: /path/to/buildstock.csv
This needs to be updated to include the schema_version
key, the sampling_algorithm
key, the n_datapoints
key, and buildstock_csv
needs to be changed to precomputed_sample
. The new schema would now look like:
baseline:
sampling_algorithm: precomputed
precomputed_sample: /path/to/buildstock.csv
n_datapoints: 1234
schema_version: 0.2
Using a precomputed sample - Commercial¶
The relevant before section should look something like:
baseline:
sampling_algorithm: precomputed
precomputed_sample: /path/to/buildstock.csv
This needs to be updated to include the schema_version
key and the n_datapoints
key. The new schema would now
look like:
baseline:
sampling_algorithm: precomputed
precomputed_sample: /path/to/buildstock.csv
n_datapoints: 1234
schema_version: 0.2
Samplers - Precomputed and Quota¶
Previously the file specified by the buildstock_csv
key was dealt with by the
run_sampling()
function in the base BuildStockBatchBase
class. This is no longer
the case, but the associated functionality has been retained, now in the PrecomputedSampler
class
which inherits from the BuildStockSampler
class. This cleans up some structural inconsistencies and
allows for a more standard interface.
New Features and Improvements¶
ComStock¶
Release 0.18 merges in the long-running ComStock support branch, allowing (finally) for ComStock runs to be performed using the major release packages. At this time ComStock is still in a Beta stage and not nearly as ‘fire-and-forget’ as ResStock and is not currently supported AT ALL outside of the ComStock team. Additional documentation is being built out in the ComStock repo - please review and update as issues and resolutions and common mistakes are determined. As we continue to uncover issues we will delegate them to either the ComStock repo or the repo on an ad-hoc basis.
No specific actions are required for using release 0.18 with ComStock, except for the need to (as always) correctly set up your YAML configuration file!