dr_simulator package

Submodules

dr_simulator.costs module

This module contains the cost functions used in the demand response simulator.

dr_simulator.costs.calculate_dr_payment(dr_period_details, capacity_bid, capacity_price, payment_functions, output_data, electricity_purchase_varnames, datetime_varname, day_of_adj_details=None)[source]

Calculate the payment expression from a demand response event

Parameters:

  • dr_period_details (dict) – Dictionary with the details of the demand response event period and baseline_days

  • capacity_bid (float) – The capacity bid for the demand response event

  • capacity_price (float) – The price for the capacity bid

  • payment_functions (list) – List of dictionaries with the keys “domain”, “slope”, and “intercept” that define the payment function

  • output_data (pandas.DataFrame) – The output data for baseline calculation

  • electricity_purchase_varnames (list) – List of electricity purchase variable names

  • datetime_varname (str) – Name of the datetime variable in the output data

  • day_of_adj_details (dict) – Dictionary with the details of the day-of-adjustment calculation (default is {

    “maximum”: 0.4, “hours before”: 4, “duration”: 3

    }) for PG&E’s CBP DR

Returns:

Dictionary with keys “payment”, “ratio”, “reduction”, and “baseline”

Return type:

dict

dr_simulator.costs.calculate_dr_payment_region(ratio, domains)[source]

Calculate the payment multiplier for a single demand response event for CBP.

Paremeters

ratiofloat

The ratio of baseline consumption to actual consumption

domainslist

list of tuples of the form (lower, upper) that define the regions of the payment function

returns:

The domain index the ratio corresponds to

rtype:

int

dr_simulator.data module

This module contains the data structures used in the demand response simulator.

dr_simulator.dr_events module

This module contains the DemandResponseEvents class which is used to generate demand response events for a given time period based on user’s inputs.

class dr_simulator.dr_events.DemandResponseEvents(start_dt, end_dt, name='DR Program', time_step=60)[source]

Bases: object

This class is intended to be used to generate demand response events for a given time period based on user’s inputs.

Follow the steps below to generate demand response events:

  1. Create an instance of the class

  2. Set the program parameters using the set_program_parameters function

  3. Sample the ndays of the events using the set_ndays function

  4. Sample the start times of the events using the set_start_times function

  5. Sample the event duration of the events using the set_event_duration function

  6. Sample the probability of each day being selected using the get_pdates function this is uniform now, but you can provide a distribution with the same length as the number of days between the start and end dates

  7. Sample the event dates of the events using the set_event_dates function

  8. Set the notification time of the events using the set_notification_time function

  9. Generate the event dictionary using the generate_event_dict function

Parameters:

  • start_dt (datetime.datetime) – Start date of the demand response events period

  • end_dt (datetime.datetime) – End date of the demand response events period

  • time_step (int) – Time step of the demand response events period in minutes

create_dr_events_mtcs(program_parameters, simulation_parameters, n_simulations)[source]

This function creates the demand response events for the given number of simulations

Parameters:

n_simulations (int) – Number of simulations

generate_event_dict(program_parameters, simulation_parameters)[source]

This function generates the event dictionary

Parameters:

None

get_pdates()[source]

This function sets the probability of each day being selected based on a uniform distribution

Parameters:

None

Returns:

p_calendar – Probability of each day being selected

Return type:

numpy.ndarray

set_event_dates(seed=None, p_dates=None)[source]

This function sets the event dates of the events based on a given distribution

Parameters:

p_dates (float) – Probability of each day being selected

set_event_duration(distribution, distribution_parameters, seed=None)[source]

This function sets the event duration of the events based on a given distribution

Parameters:

event_hours (int) – Number of hours of the demand response events

set_ndays(distribution, distribution_parameters, seed=None)[source]

This function sets the number of days of the events based on a given distribution

Parameters:

ndays (int) – Number of days between two demand response events

set_notification_time(notification_time=None)[source]

This function sets the notification time of the events

Parameters:

notification_time (int) – Notification time of the demand response events

set_program_parameters(min_days, max_days, min_duration, max_duration, program_start_time, program_end_time, max_consecutive_events=3, notification_time=None, notification_delta=None, notification_type='day_before', n_similar_weekdays=10, **kwargs)[source]

This function sets the program parameters for the demand response program

Parameters:

  • min_days (int) – Minimum number of days between two demand response events

  • max_days (int) – Maximum number of days between two demand response events

  • min_duration (int) – Minimum duration of a demand response event in hours

  • max_duration (int) – Maximum duration of a demand response event in hours

  • program_start_time (int) – Minimum start time of a demand response event in hours

  • program_end_time (int) – Maximum start time of a demand response event in hours

  • notification_time (int) – Notification time of a demand response event in hours

  • notification_type (str) – Type of notification time. Default is “day_before”. Other options are “day_of” and “hour_before”

set_start_times(distribution, distribution_parameters, seed=None)[source]

This function sets the start times of the events based on a given distribution

Parameters:

start_times (int) – Start time of the demand response events

dr_simulator.utils module

This module contains utility functions for DR Simulator

class dr_simulator.utils.DistributionTypes(value)[source]

Bases: Enum

Enum class for supported distributions

NORMAL = 'normal'
POISSON = 'poisson'
UNIFORM = 'uniform'
dr_simulator.utils.combine_overlapping_dr_events(dr_events_dts)[source]

Sorts the events in choronological order and combines overlapping demand response (DR) events into a single event

Parameters:

  • dr_events_dts (dict)

  • A dictionary where values are lists or arrays of start and end times of DR events.

Returns:

  • dr_events_dts (dict)

  • A dictionary where values are lists or arrays of start and end times of combined if overlapping DR events.

dr_simulator.utils.convert_dr_event_details(event_details)[source]

Converts the demand response event details to the format required by the optimizer

Parameters:

event_details (dict) – Dictionary with the details of the demand response event

Returns:

event_details – Dictionary with the details of the demand response event in the format required by the optimizer

Return type:

dict

dr_simulator.utils.create_calender(dates)[source]

This function creates a calendar for the given dates

Parameters:

dates (list) – List of dates

Returns:

  • woy (numpy.ndarray) – Week of the year of the dates

  • dow (numpy.ndarray) – Day of the week of the dates

  • calendar (numpy.ndarray) – Calendar of the dates

dr_simulator.utils.days_in_year_month(year, month)[source]
Parameters:

  • year (int)

  • month (int)

Returns:

number of days in a month of year

Return type:

int

dr_simulator.utils.get_date_range_prev_month(date, n_days)[source]

This function gets the date range for the previous month

Parameters:

  • date (datetime.datetime) – Date of the event

  • n_days (int) – Number of days in the previous month

Returns:

date_range – List of length n_days with the dates of the previous month

Return type:

list

dr_simulator.utils.get_day_of_adj_ratio(dr_period_details, output_data, electricity_purchase_varnames, datetime_varname, day_of_adj_details=None)[source]

Get the day-of-adjustment ratio for a given demand response event. The day-of-adjustment ratio is calculated as the average consumption of the window hours before the event divided by the average consumption of the same hours on similar weekdays. The day-of-adjustment ratio is capped at the day_of_adj_max value.

Parameters:

  • dr_period_details (dict) – Dictionary with the details of the demand response event period and baseline_days

  • output_data (pandas.DataFrame) – the output data for baseline calculation

  • electricity_purchase_varnames (list) – List of electricity purchase variable names

  • datetime_varname (str) – Name of the datetime variable in the output data

  • day_of_adj_details (dict) – Dictionary with the details of the day-of-adjustment calculation (default is {

    “maximum”: 0.4, “hours before”: 4, “duration”: 3

    }) for PG&E’s CBP DR

Returns:

day_of_adj_ratio – Day-of-adjustment ratio

Return type:

float

dr_simulator.utils.get_dr_baseline_dates(dr_data)[source]

Get the demand response baseline dates

Parameters:

dr_data (dict) – Dictionary with the demand response data

Returns:

dr_baseline_dates – np.array of np.datetime64 with the demand response baseline dates

Return type:

array of np.datetime64

dr_simulator.utils.get_dr_dates(event_details, horizon_start_dt, horizon_end_dt)[source]

Get the demand response event dates for the optimization horizon

Parameters:

  • event_details (list of dict) – Dictionary with the details of the demand response event

  • horizon_start_dt (np.datetime64) – Start datetime of the optimization horizon

  • horizon_end_dt (np.datetime64) – End datetime of the optimization horizon

Returns:

dr_events_dts – List of np.datetime64 with the demand response event dates for the optimization horizon

Return type:

dict of np.datetime64

dr_simulator.utils.get_freq_binsize_minutes(freq)[source]

Gets size of a given time frequency expressed in units of minutes :Parameters: freq (str) – a string of the form [type][freq_binsize], where type corresponds to a numpy.timedelta64 encoding

and freq binsize is an integer giving the number of increments of type of one binned increment of our time variable (for example ‘6h’ means the data are grouped into increments of 6 hours)

Raises:

ValueError – when resolution is not minute, hourly, or daily

Returns:

integer giving the number of minutes in the given time frequency unit

Return type:

int

dr_simulator.utils.get_hourly_average_consumption(similar_days, event_hour, output_data, electricity_purchase_varnames, datetime_varname)[source]

Get the baseline consumption for a given demand response event

Parameters:

  • similar_days (np.array of np.datetime64) – List of similar weekdays

  • event_hour (int) – Hour of the day of the demand response event

  • output_data (pandas.DataFrame) – the output data for baseline calculation

  • electricity_purchase_varnames (list) – List of electricity purchase variable names

  • datetime_varname (str) – Name of the datetime variable in the output data

Returns:

baseline_consumption – Baseline consumption in kWh

Return type:

float

dr_simulator.utils.get_hourly_dr_event_arrays(event_start_dt, horizon_start_dt, horizon_end_dt, resolution='15m')[source]

Get the hourly demand response event arrays for the optimization data with 1 for the hours of the demand response event and 0 otherwise for each demand response event hours

Parameters:

  • event_start_dt (np.datetime64) – Start datetime of the demand response event

  • event_end_dt (np.datetime64) – End datetime of the demand response event

  • horizon_start_dt (np.datetime64) – Start datetime of the optimization horizon

  • horizon_end_dt (np.datetime64) – End datetime of the optimization horizon

  • resolution (str) – Resolution of the optimization data

Returns:

hourly_dr_event_arrays – List of np.array with 1 for the hours of the demand response event and 0 otherwise

Return type:

list of np.array

dr_simulator.utils.get_n_similar_weekdays(date, prev_event_days, n_weekdays=10)[source]

This function gets the 10 similar weekdays excluding the event days

Parameters:

  • date (datetime.datetime) – Date of the event

  • prev_event_days (list) – List of previous event days

  • n_weekdays (int (default=10)) – Number of similar weekdays to return

Returns:

similar_weekdays – List of length of previous n_weekdays excluding the event days

Return type:

list

dr_simulator.utils.get_start_end_dt(dr_start_dt, dr_end_dt, horizon_start_dt, horizon_end_dt)[source]

Get the start and end datetime of the demand response event within the optimization horizon

Parameters:

  • dr_start_dt (np.datetime64) – Start datetime of the demand response event

  • dr_end_dt (np.datetime64) – End datetime of the demand response event

  • horizon_start_dt (np.datetime64) – Start datetime of the optimization horizon

  • horizon_end_dt (np.datetime64) – End datetime of the optimization horizon

Returns:

  • start_dt (np.datetime64) – Start datetime of the demand response event within the optimization horizon

  • end_dt (np.datetime64) – End datetime of the demand response event within the optimization horizon

dr_simulator.utils.json_dump(object_, path)[source]

Dumps a python object to a json string

Parameters:

  • object_ (object) – python object to convert to str

  • path (str) – path where the json string is saved

dr_simulator.utils.json_load(path)[source]

Loads a json string to python

Parameters:

path (str) – path to object to load

Returns:

object_ – python object converted from str

Return type:

object

dr_simulator.utils.parse_freq(freq)[source]

Parses a time frequency code string, returning its type and its freq_binsize

Parameters:

freq (str) – string of the form [type][freq_binsize], where type corresponds to a numpy.timedelta64 encoding and freq binsize is an integer giving the number of increments of type of one binned increment of our time variable (for example ‘6h’ means the data are grouped into increments of 6 hours)

Returns:

tuple of the form (int,`str`) giving the binsize and type of the time frequency given

Return type:

tuple

dr_simulator.utils.pickle_dump(object_, path)[source]

Pickles an object (fitted model, dictionary with data, etc)

Parameters:

  • object_ – object to compress

  • path (str) – path where the pickled object is saved

dr_simulator.utils.pickle_load(path)[source]

Loads a pickled object (fitted model, dictionary with data, etc)

Parameters:

path (str) – path to object to load

Returns:

unpickled object found at the path

Return type:

object

dr_simulator.utils.sanitize_dr_data(dr_data)[source]

Sanitize the demand response data

Parameters:

dr_data (dict) – Dictionary with the demand response data

Returns:

dr_data – Dictionary with the sanitized demand response data

Return type:

dict

dr_simulator.utils.text_to_param_dict(distr_type, distr_params_text)[source]

Converts distribution parameters entered as text to param_dict

Parameters:

  • distr_type (DistributionTypes) – Distribution type

  • distr_params_text (str) – Distribution parameters entered as text

Returns:

Distribution parameters as dictionary

Return type:

dict

dr_simulator.utils.validate_distribution_params(distr_type, distr_params)[source]

Validates the distribution parameters

Parameters:

  • distr_type (DistributionTypes) – Distribution type

  • distr_params (dict) – Distribution parameters

Returns:

True if the parameters are valid, False otherwise

Return type:

bool

dr_simulator.visulization_helper module

Helper functions for visualizing the DR event data

dr_simulator.visulization_helper.plot_dr_events(start_dt, end_dt, dr_events, sampled_event_hours)[source]

Plots the DR events in a monthly calendar

Parameters:

  • start_dt (datetime.datetime) – Start date of the calendar

  • end_dt (datetime.datetime) – End date of the calendar

  • dr_events (list) – List of datetime.datetime objects representing the start of each event

  • sampled_event_hours (list) – List of floats representing the number of hours of each event

Returns:

Figure and axes objects containing the calendar

Return type:

matplotlib.pyplot.figure, matplotlib.pyplot.axes

Module contents

Top-level package for Demand Response Simulator.

dr_simulator.get_module_version()[source]

Return the version of the module.