Execution Guide¶
FlexAssist supports multiple execution modes:
- Selecting from a set of candidate DR response strategies.
- Generating predictions of baseline demand (without implementation of DR strategies).
- Generating new models of building demand/services under DR and baseline conditions.
- Updating existing models of building demand/services given new data.
Guidance on preparing inputs, running the model, and interpreting output for each of these execution modes is provided below.
Selecting from set of DR response strategies¶
Given a set of candidate DR strategies and day-ahead DR event conditions as an input, this model execution mode will determine which candidate strategy is most likely to maximize operator utility and provide that information as an output. Selection likelihoods are generated based on the predicted change in demand and building services under each of the candidate DR strategies and DR event conditions, and considering operator valuations of various service loss risks.
Required input files¶
The input file for this execution mode is found in ./data/test_predict.csv.. Table 1 outlines the columns that must be present in this file.
| Column name | Description |
|---|---|
| Name | Name of the DR strategy |
| Hr | Hours into the DR event, starting from 1 |
| OAT | Outdoor air temperature (ºF) |
| RH | Outdoor relative humidity (%) |
| Lt_Nat | Outdoor natural illuminance (lux) |
| Lt_Base | Indoor lighting schedule fraction |
| Occ_Frac | Occupant schedule fraction |
| Delt_Price_kWh | Utility incentive for DR |
| h_DR_Start | Hours into the DR window |
| h_DR_End | Hours since DR window ended |
| h_PCool_Start | Hours since pre-cooling started |
| h_PCool_End | Hours since pre-cooling ended |
| Delt_CoolSP | Change in temperature set point (ºF) |
| Delt_LgtPct | Reduction in lighting power (%) |
| Delt_OAVent_Pct | Reduction in outdoor air fraction |
| Delt_PL_Pct | Reduction in plug load power (%) |
| Delt_CoolSP_Lag | Change in temperature set point since previous hour (ºF) |
| Delt_LgtPct_Lag | Change in lighting power since previous hour (%) |
| Delt_OAVent_Pct-Lag | Change in outdoor air fraction since previous hour (%) |
| Delt_PL_Pct_Lag | Change in plugload power since previous hour (%) |
| Pcool_Mag | Magnitude of pre-cooling before event started (ºF temperature decrease) |
| Pcool_Dur | Duration of precooling before DR event started |
An example of this input file is available that reflects the candidate DR strategies shown in Table Table 2.
Note
Plug load reduction strategies are currently only supported when running simulations for office building types; when running simulations for retail buildings, all settings in ./data/test_predict.csv. related to plug loads should be set to zero.
| DR strategy name | Description | Magnitude |
|---|---|---|
| GTA-Low | Global temperature adjustment | +2ºF |
| GTA-Moderate | Global temperature adjustment | +3ºF |
| GTA-High | Global temperature adjustment | +5ºF |
| Precool-Low | Global temp. adjustment Precooling temperature change |
+2ºF -2ºF |
| Precool-Moderate | Global temp. adjustment Precooling temperature change |
+3ºF -5ºF |
| Precool-High | Global temp. adjustment Precooling temperature change |
+5ºF -5ºF |
| Dimming-Low | Lighting dimming | -20% |
| Dimming-Moderate | Lighting dimming | -40% |
| Dimming-High | Lighting dimming | -60% |
| Plug Load-Low | Plug load reduction | -10% |
| Plug Load-Moderate | Plug load reduction | -30% |
| Plug Load-High | Plug load reduction | -50% |
| Package-Low | Global temp. adjustment Lighting dimming Plug load reduction |
+2ºF -10% -10% |
| Package-Moderate | Global temp. adjustment Lighting dimming Plug load reduction |
+4ºF -30% -30% |
| Package-High | Global temp. adjustment Lighting dimming Plug load reduction |
+6ºF -30% -30% |
| Package-Low-Precool | Global temp. adjustment Lighting dimming Plug load reduction Precooling temperature change |
+2ºF -20% -10% -2ºF |
| Package-Moderate-Precool | Global temp. adjustment Lighting dimming Plug load reduction Precooling temperature change |
+3ºF -40% -30% -5ºF |
| Package-High-Precool | Global temp. adjustment Lighting dimming Plug load reduction Precooling temperature change |
+5ºF -60% -50% -5ºF |
Running the model¶
DR strategy recommendations and associated predictions are generated with the following command line/Terminal inputs on Windows and MacOS, respectively:
Windows
cd Documents\projects\flex-bldgs
py -3 flex.py --bldg_type <insert building type/vintage name> --bldg_sf <insert square footage> <additional options>
Mac
cd Documents/projects/flex-bldgs
python3 flex.py --bldg_type <insert buildling type/vintage name> --bldg_sf <insert square footage> <additional options>
Where --bldg_type options include mediumofficenew (~50K square foot medium office post-2004), mediumofficeold (~50K square foot medium office pre-2004, stdaloneretailnew (~25K standalone retail building post-2004), stdaloneretailold (~25K standalone retail building pre-2004), largeofficenew (~500K square foot large office pre-2004), largeofficeold (~500K square foot large office post-2004), largeofficenew_elec (all-electric version of largeofficenew using water-source heat pump and dedicated outdoor air system (DOAS)), largeofficeold_elec (all-electric version of largeofficeold), and bigboxretail (~100K square foot big box retail building, 2004 vintage). Values for --bldg_sf should be entered as-is (e.g., 50,000 for a 50K square foot building)
Additional run options (represented in the command above by <additional options>) include --null_strategy, which will include the option of taking no actions in the candidate strategies; --dmd_thres <insert value>, which will impose a threshold on maximum during-event hourly demand reduction (in W) across strategies and remove strategies that do not meet the threshold from consideration on an event-by-event basis; and --daylt_pct <insert value> which will adjust the standard 30% daylit floorspace assumed in making predictions to the user-specified value (in %).
The model will load the input data and begin predicting the changes in demand and indoor services during each of the event hours reflected in the input file, drawing upon previously initialized models of building demand and services (see Selecting from set of DR response strategies).
Interpretation of outputs¶
Outputs from execution of this mode are stored in the file ./data/recommendations.json. The file has the following structure:
{
"notes": <notes about the contents of the file>,
"predictions": {
"DR strategy name 1": <Percentage of simulations in which DR strategy 1 was selected>, ...
"DR strategy name N": <Percentage of simulations in which DR strategy N was selected>, ...
},
"input output data": {
"demand": {
"DR strategy name 1": [<All sampled maximum hourly demand reduction values (W/sf) for DR strategy name 1>],
"DR strategy name N": [<All sampled maximum hourly demand reduction values (W/sf) for DR strategy name N>]},
"demand precool": {
"DR strategy name 1": [<All sampled maximum hourly demand increase from precooling values (W/sf) for DR strategy name 1>],
"DR strategy name N": [<All sampled maximum hourly demand increase from precooling values (W/sf) for DR strategy name N>]},
"cost": {
"DR strategy name 1": [<All sampled total economic benefit values ($) for DR strategy name 1>],
"DR strategy name N": [<All sampled total economic benefit values ($) for DR strategy name N>]},
"cost precool": {
"DR strategy name 1": [<All sampled total economic loss from precooling values ($) for DR strategy name 1>],
"DR strategy name N": [<All sampled total economic loss from precooling values ($) for DR strategy name N>]},
"temperature": {
"DR strategy name 1": [<All sampled maximum hourly temperature increase values (ºF) for DR strategy name 1>],
"DR strategy name N": [<All sampled maximum hourly temperature increase values (ºF) for DR strategy name N>]},
"lighting": {
"DR strategy name 1": [<Input lighting reduction fraction for DR strategy name 1>],
"DR strategy name N": [<Input lighting reduction fraction for DR strategy name N>]},
"plug loads": {
"DR strategy name 1": [<Input plug load reduction fraction for DR strategy name 1>],
"DR strategy name N": [<Input plug load reduction fraction for DR strategy name N>]}
}
}
Generating baseline demand predictions¶
One of the functions of FlexAssist is to generate the baseline demand value given certain conditions, such as weather and occupancy, and building characteristics such as type and vintage. Models of baseline demand follow the same approach as those that were fit to predict the changes in demand and building servies under candidate DR strategies, which are used in Generating new models.
Required input files¶
The input file for this execution mode is found in ./data/test_predict_bl.csv. Table 3 outlines the columns that must be present in this file.
| Column name | Description |
|---|---|
| Hr | Hour into the DR event, starting from 1 |
| Vintage | Four vintages are considered within the scope: 1980, 1980-2004, 2004, 2010 |
| Hour_number | Actual time based on 24-hour military time |
| Climate | Climate zone where the building is located, followed by IECC climate zone map |
| OAT | Outdoor air temperature (ºF) |
| RH | Outdoor relative humidity (%) |
| Occ_Frac | Occupancy schedule fraction |
| V1980 … V19802004 | Binary check box |
| CZ.2A … CZ.7A | Binary check box |
Running the model¶
Baseline demand predictions are generated using the --base_pred option as below:
Windows
cd Documents\projects\flex-bldgs
py -3 flex.py --base_pred --bldg_type <insert bldg name> --bldg_sf <insert sf>
Mac
cd Documents/projects/flex-bldgs
python3 flex.py --base_pred --bldg_type <insert bldg name> --bldg_sf <insert sf>
The model will automatically load in the input data and start calculating the hourly baseline demand values given the input information.
Interpretation of outputs¶
Predicted hourly baseline demand values are reported in ./data/base_predict_summary.csv. For each predicted hour, there will be 1) mean value (W/sf), and 2) standard deviation together indicating the predicted results. By default, the sample number for generating these results is set to 1000.
Generating new models¶
Users can use this mode to initialize/re-initialize all the models of building demand/services and operator utility that underly FlexAssist’s predictions, given input CSV data that follows a certain data structure. The model list includes the following 6 regression models:
- Baseline demand value
- Thermally-driven demand changes during the DR period (for strategies involving temperature adjustment)
- Non thermally-driven demand changes during the DR period (for strategies not involving temperature adjustment)
- Demand changes during the pre-cooling period
- Indoor temperature changes during the DR period (relevant only to strategies involving temperature adjustment)
- Operator utility
Required input files¶
Input files for this execution mode are found in the ./data directory. Current CSV files underlying the models of building demand and services were generated from a batch of simulations in EnergyPlus, where four scenarios of building types and vintages were considered. Another file with training data for the operator choice model was developed from discrete choice experiments with building operators. If users want to re-initialize the models using their own data, the format of their CSV files must be consistent with these current files. Table Table 4 shows example CSV file names underlying demand and service models sfor the medium office new vintage (post-2004); these example CSVs may serve as useful references for formatting and content.
| Input file | Regression model |
|---|---|
| MO_B.csv | Baseline demand prediction |
| MO_Thermal_Demand_new.csv | Thermally-driven demand changes during the DR period |
| MO_Nonthermal_Demand_new.csv | Non thermally-driven demand changes during the DR period |
| MO_PC_Demand_new.csv | Demand changes during the pre-cooling period |
| MO_Temperature_new.csv | Indoor temperature changes during DR |
Running the model¶
New model initialization is executed using the --mod_init option as below:
Windows
cd Documents\projects\flex-bldgs
py -3 flex.py --mod_init --bldg_type <insert bldg name>
Mac
cd Documents/projects/flex-bldgs
python3 flex.py --mod_init --bldg_type <insert bldg name>
The model will start loading input data and initializing the variables for each regression model.
Interpretation of outputs¶
Model coefficient samples from the Bayesian inference framework are saved as pickled files (.pkl ) to the ./model_stored directory. For example, for the medium office building type and new vintage (post-2004), each file represents specific model(s) as shown in Table 5.
| Output file | Regression model |
|---|---|
| dmd_mo_b.pkl | Baseline demand prediction |
| dmd_therm_mo_n.pkl | Thermally-driven demand changes during the DR event period |
| dmd_ntherm_mo_n.pkl | Non thermally-driven demand changes during the DR period |
| pc_dmd_mo_n.pkl | Demand changes during the pre-cooling period |
| tmp_mo_n.pkl | Indoor temperature changes during DR |
| dce.pkl | Operator utility |
These stored moddel coefficient data are then drawn from in the other execution modes.
Updating existing models¶
FlexAssist enables updating of previously initialized models of change in building demand and services based on new data observations. Existing models are stored in .pkl files in the ./model_stored folder, as outlined in Table 5.
Required input files¶
The input file for this execution mode is found in ./data/test_update.csv for updating the models of demand/services under DR strategies, and in ./data/test_update_bl.csv for updating the models of baseline demand. Table 6 outlines the columns that must be present in the formert file; example files are found here for models of demand/services and here for models of baseline demand.
| Column name | Description |
|---|---|
| Vintage | Four vintages are considered within the scope: 1980, 1980-2004, 2004, 2010 |
| Climate.zone | Climate zone where the building is located, followed by IECC climate zone map |
| Hour.number | Actual time based on 24-hour military time |
| Outdoor.Temp.F | Outdoor air temperature (ºF) |
| Outdoor.Humid. | Outdoor relative humidity (%) |
| Occ.Fraction. | Occupancy schedule fraction (<=1) |
| Demand.Power.Diff.sf. | Whole building reduction in electricity demand from baseline (W/sf) |
| Indoor.Temp.Diff.F. | Indoor temperature difference from baseline (ºF) |
| Indoor.Humid.Diff.F. | Indoor RH difference from baseline (ºF) |
| Lighting.Power.Diff.pct. | Reduction in lighting power (%) |
| MELs.Diff.pct. | Reduction in plug load power (%) |
| Cooling.Setpoint.Diff. | Change in temperature set point (ºF) |
| Cooling.Setpoint.Diff. One.Step. | Change in temperature set point since previous hour (ºF) |
| Since.DR.Started | Hours into the DR window |
| Since.DR.Ended | Hours since DR window ended |
| Pre.cooling.Temp. Increase. | Magnitude of pre-cooling before event started (ºF temperature decrease) |
| Pre.cooling.Duration | Duration of precooling before DR event started |
| Since.Pre.cooling. Started. | Hours since pre-cooling started |
| Since.Pre.cooling.Ended. | Hours since pre-cooling ended |
Running the model¶
Model updates are executed using the --mod_est option as below:
Windows
cd Documents\projects\flex-bldgs
py -3 flex.py --mod_est --bldg_type <insert bldg name>
Mac
cd Documents/projects/flex-bldgs
python3 flex.py --mod_est --bldg_type <insert bldg name>
The model will automatically load in the input data and start updating the previously initialized models.