BcaEnv functions

(in progress, storing content just for now, need to udpate)

Runtime Data Acquisition Functions

BcaEnv.get_ems_data(ems_metric_list: list, time_rev_index: list=[0]) -> list

• This method will return an ordered nested list of ordered data points for then given EMS metrics and timing index(s), or entire EMS type ToC
• Its intended use is to return updated state information at each timestep, it can be called as many times as need in a actuation function.
• This method must be used during runtime from an actuation function
• ems_metric_list pass one or more EMS metrics (of any type) OR ONLY a single EMS type (var, intvar, meter, actuator, weather) in a list. Passing an EMS type will utilize and return data for that entire EMS ToC
• time_rev_index indicates the time index of the data you want to return, indexing backwards from the most recent timestep at 0. Leaving this list empty [ ] will return the entire data list collected thus far in the simulation for each given EMS metric. Note that data will only be returned once the number of simulation timesteps has surpassed the maximum prior-time index given

BcaEnv.get_weather_forecast(when: str, weather_metrics: list, hour: int, zone_ts: int) -> list

• This method is used to fetch and return an ordered list of future weather data, resembling weather forecasts. Weather events that have already occurred in simulation can be gathered using BcaEnv.get_ems_data
• This method must be used during runtime from an actuation function
• weather_metrics is the list of user-defined weather variable names, defined in the weather ToC, you want to fetch data for
• when either 'today' or 'tomorrow' dictates which day is in question, relative to current simulation time
• hour the hour of the day to collect the weather forecast data
• zone_ts the timestep within the given hour you want to collect weather forecast data for

Note : If you wish to use callback functions just for defualt data collection pass None as the actuation function. If you wish to use the callback functions for custom data collection and/or other actions other than any actuation/control at a specific calling point, implement an actuation function that returns None as the actuation dict.

Also, if there is a need to update specific EMS metrics at a certain calling point separately from the rest (all EMS ToCs), you can use the method below within an actuation function to update specific EMS metrics. However, this does not also exclude them from the state_update that updates ALL EMS metrics.

BcaEnv.update_ems_data(ems_metric_list: list, return_data: bool) -> list

• This method will update the given EMS metrics, or entire EMS type ToC and optionally return an ordered list of the updated data
• Its intended use is if you want to update specific EMS data (or types) at a unique calling point, separate from the default state update of all EMS ToCs at another calling point.
• This method must be used during runtime from an actuation function
• ems_metric_list pass one or more EMS metrics (of any type) OR ONLY a single EMS type (var, intvar, meter, actuator, weather) in a list. Passing an EMS type will utilize that entire EMS ToC
• return_data if True, this will automatically return the ordered list of data from Bca.Env.get_ems_data

Warning : EMS data (and actuation) can be 'updated' by the user (but not necessarily internally by the simulation) for each calling point (and actuation function) assigned within a single timestep. You likely want to avoid this and manually only implement one state update state_update=True per timestep. Otherwise, you will screw up zone timestep increments (with current software design) and may accidentally be collecting data and actuating multiple times per timestep. Just because you want to update data/actuation does not necessary mean it will be implmented at all or how you intended. An understanding of calling points and when to collect data or actuate is crucial - Please see the EMS Application Guide for more information on calling points.

TIPS:

• (in progress)

CAUTION:

• Make sure your hourly timestep matches that of your EnergyPlus .idf model
• EMS data (and actuation) can be 'updated' by the user (but not necessarily internally by the simulation) for each calling point (and actuation function) assigned within a single timestep. You likely want to avoid this and manually only implement one state update state_update=True per timestep. Otherwise, you will screw up zone timestep increments (with current software design) and may accidentally be collecting data and actuating multiple times per timestep. Just because you want to update data/actuation does not necessary mean it will be implmented at all or how you intended. An understanding of calling points and when to collect data or actuate is crucial - Please see the EMS Application Guide for more information on calling points.

Future Planned Functionality & Repo Improvements:

• EmsPy improvements
  • more automatic user oversight to verify that user's have not violated logical errors in calling points, callback functions, and/or EMS updates
  • verify that given model timestep matches the .idf file, OR have it overwrite the model if not (say using openstudio somehow)
  • assist users in understanding actuator input ranges
  • further detailed documentation
• Data Dashboard class to automatically compile E+ performance and RL learning data into subplots via Matplotlib
• Openstudio wrapper class to assist in simple modifications of the .idf/.osm that impact simulation experiments (timesteps, start-end dates, etc.)
• Provide tips to documentation on how to construct and/or modify building models to be linked with EmsPy
• A handful of various building models already set up with EmsPy so that user's can just focus on control algorithms given readily available state and action space, and pre-linked calling points.

Creating an E+ Building Energy Model:

• TOOD

Setting up a E+ Model for EMS API Usage:

• TODO

Linking EMS Metrics to Your EmsPy Script:

• TODO