tesp_support.dsot package

Transactive Energy Simulation Platform (TESP) Contains the python files for the DSOT analysis

Submodules

tesp_support.dsot.Wh_Energy_Purchases module

Utilities to open and read load

Todo: files should be passed in for ‘load*’ functions

Public Functions:

load_hourly_data:: Utility to open csv file for hourly load data
load_realtime_data:: Utility to open csv file 5 min load data
load_price_data:: Utility to open csv file LMP data
Wh_Energy_Purchases:: Computes the total costs, total energy purchases and average price annually

tesp_support.dsot.Wh_Energy_Purchases.Wh_Energy_Purchases(dir_path, dso_num, simdata=False, h1=5, h2=16, h3=20, place='Houston')

Computes the total costs, total energy purchases and average price annually for bilateral, day-ahead and real-time markets from hourly and 5 min ERCOT energy and price data.

Loads hourly ERCOT energy and price data.
Computes minimum wholesale price and quantity for day, evening, and weekend to represent the fixed prices and energy quantities for the bilateral market.
Total annual average price, total cost and total energy purchases from the bilateral market are then computed.

Parameters:

dir_path (str) – path of the ERCOT energ and price data
dso_num (int) – dso number (1-8)
simdata (bool) – If True will seek simulation data. If false will use 2016 ERCOT data.
h1 (int) – hours specified to define day
h2 (int) – hours specified to define evening
h3 (int) – hours specified to define night respectively (e.g. weekday hours h1 to h2, evening hours from h2+1 to h3, and night hours are from h3+1 to h1 the next day)
place (str) – location of DSO

Returns:

real-time, day-ahead, and bilateral market purchases (annual cost, energy and average price)

Return type:

dict

tesp_support.dsot.Wh_Energy_Purchases.load_hourly_data(dir_path, dso_num, simdata)

Utility to open hourly ERCOT csv file.

The entire date range for the data (e.g. 1 year) is considered

Parameters:

dir_path (str) – directory path of data
dso_num (int) – dso number
simdata (bool) – If True will seek simulation data. If false will use 2016 ERCOT data.

Returns:

dataframe of ERCOT data for dso specified

Return type:

dataframe

tesp_support.dsot.Wh_Energy_Purchases.load_price_data(dir_path, market_type, dso_num, simdata, place)

Utility to open 5 min ERCOT csv file.

The entire date range for the data (e.g. 1 year) is considered

Parameters:

dir_path (str) – directory path of data
market_type (str) – string telling the market type (‘DA’,’RT’)
dso_num (int) – dso number
simdata (bool) – If True will seek simulation data. If false will use 2016 ERCOT data.
place (str) – location of DSO

Return type:

prices_data

tesp_support.dsot.Wh_Energy_Purchases.load_realtime_data(dir_path, dso_num, simdata)

Utility to open 5 min ERCOT csv file.

The entire date range for the data (e.g. 1 year) is considered

Parameters:

dir_path (str) – directory path of data
dso_num (int) – dso number
simdata (bool) – If True will seek simulation data. If false will use 2016 ERCOT data.

Returns:

15 min dataframe of ERCOT data for specified dso

Return type:

dataframe

tesp_support.dsot.balance_sheet_functions module

tesp_support.dsot.balance_sheet_functions.iso_balance_sheet_annual(meta_path, write_path, write_to_txt=False, write_to_JSON=False)

This function calculates …

Parameters:

meta_path
write_path
write_to_txt
write_to_JSON

Return type:

dict

tesp_support.dsot.balance_sheet_functions.test_iso()

tesp_support.dsot.balance_sheet_functions.test_too()

tesp_support.dsot.balance_sheet_functions.too_balance_sheet_annual(meta_path, write_path, write_to_txt=False, write_to_JSON=False)

This function calculates …

Parameters:

meta_path
write_path
write_to_txt
write_to_JSON

Return type:

dict

tesp_support.dsot.battery_agent module

Class that controls the Battery DER

Implements the optimum schedule of charging and discharging DA; generate the bids for DA and RT; monitor and supervisory control of GridLAB-D environment element.

The function call order for this agent is:

initialize()

Repeats at every hour:

formulate_bid_da() {return BID}
set_price_forecast(forecasted_price)

Repeats at every 5 minutes:

set_SOC(msg_str) {updates C_init}
formulate_bid_rt() {return BID}
inform_bid(price) {update RTprice}
bid_accepted() {update inv_P_setpoint and GridLAB-D P_out if needed}

class tesp_support.dsot.battery_agent.BatteryDSOT(diction, inv_properties, key, model_diag_level, sim_time, solver)

Bases: object

This agent manages the battery/inverter (bt)

Parameters:

diction (dict) – battery/inverter parameters
inv_properties (dict)
key (str)
model_diag_level (int) – Specific level for logging errors; set it to 11
sim_time (str) – Current time in the simulation; should be human-readable
solver (str)

Initialize from Args

name

name of this agent

Type:: str

Rc

rated charging power in kW for the battery

Type:: float

Rd

rated discharging power in kW for the battery

Type:: float

Lin

battery charging loss in %

Type:: float

Lout

battery discharging loss in %

Type:: float

Cmin

minimum allowable stored energy in kWh (state of charge lower limit)

Type:: float

Cmax

maximum allowable stored energy in kWh (state of charge upper limit)

Type:: float

Cinit

initial stored energy in the battery in kWh

Type:: float

capacity

battery capacity in kWh

Type:: float

batteryLifeDegFactor

constant to model battery degradation

Type:: float

windowLength

length of day ahead optimization period in hours (e.g. 48-hours)

Type:: int

dayAheadCapacity

% of battery capacity reserved for day ahead bidding

Type:: float

No initialization required

bidSpread

this can be used to spread out bids in multiple hours. When set to 1 hour (recommended), it’s effect is none

Type:: int

P

location of P in bids

Type:: int

Q

location of Q in bids

Type:: int

f_DA

forecasted prices in $/kWh for all the hours in the duration of windowLength

Type:: List[float]) (1 X windowLength

RT_state_maintain

true if battery must maintain charging or discharging state for 1 hour

Type:: bool

RT_state_maintain_flag

not define at current hour (-1) charging (+1) discharging

Type:: int

RT_flag

if True, has to update GridLAB-D

Type:: bool

inv_P_setpoint

next GridLAB-D inverter power output

Type:: float

optimized_Quantity

Optimized quantity

Type:: List[float]) (1 X Window Length

#not used if not biding DA

prev_clr_Quantity

cleared quantities (kWh) from previous market iteration for all hours

Type:: List[float]) (1 X Window Length

prev_clr_Price

cleared prices ($/kWh) from previous market iteration

Type:: List[float]) (1 X windowLength

BindingObjFunc

if True, then optimization considers cleared price, quantities from previous iteration in the objective function

Type:: bool

DA_cleared_price(price)

Set the DA_cleared_price attribute

Parameters:: price (float) – cleared price in $/kWh

DA_optimal_quantities()

Generates Day Ahead optimized quantities for agent

Returns:: Optimal quantity from optimization for all hours of the window specified by windowLength
Return type:: Quantity (float) (1 x windowLength)

RT_fix_four_points_range(BID, Ql, Qu)

Verify feasible range of RT bid

Parameters:

BID (float) ((1,2)X4) – 4 point bid
Ql
Qu

Returns:

4 point bid only the feasible range

Return type:

BIDr (float) ((1,2)X4)

RT_gridlabd_set_P(model_diag_level, sim_time)

Update variables for battery output “inverter”

Parameters:

model_diag_level (int) – Specific level for logging errors; set it to 11
sim_time (str) – Current time in the simulation; should be human-readable

inv_P_setpoint is a float in W

bid_accepted(current_time)

Update the P and Q settings if the last bid was accepted

Returns:: True if the inverter settings changed, False if not.
Return type:: bool

con_rule_eq1(m, i)

con_rule_eq2(m, i)

con_rule_eq3(m, i)

con_rule_ine1(m, i)

con_rule_ine2(m, i)

formulate_bid_da()

Formulate 4 points of P and Q bids for the DA market

Function calls “DA_optimal_quantities” to obtain the optimal quantities for the DA market. With the quantities, the 4 point bids are formulated.

Before returning the BID the function resets “RT_state_maintain_flag” which, if RT_state_maintain is TRUE, the battery will be forced to keep its state (i.e., charging or discharging).

Returns:: store last DA market bids
Return type:: BID (float) (((1,2)X4) X windowLength)

formulate_bid_rt()

Formulates RT bid

Uses the last 4 point bid from DA market and consider current state of charge of the battery. Will change points to change points for feasible range of Qmin Qmax points if necessary. Furthermore, allows a maximum deviation of +/-100% from the DA plan.

Returns:: bid in Real Time market
Return type:: realTimeBid (float) ((1,2) x 4)

from_P_to_Q_battery(BID, PRICE)

Convert the 4 point bids to a quantity with the known price

Parameters:

BID (float) ((1,2)X4) – 4 point bid
PRICE (float) – cleared price in $/kWh

Returns:

active power (-) charging (+) discharging

Return type:

_quantity (float)

inform_bid(price)

Set the cleared_price attribute

Parameters:: price (float) – cleared price in $/kWh

obj_rule(m)

set_SOC(msg_str, model_diag_level, sim_time)

Set the battery state of charge

Updates the self.Cinit of the battery

Parameters:

msg_str (str) – message with battery SOC in pu
model_diag_level (int) – Specific level for logging errors; set it to 11
sim_time (str) – Current time in the simulation; should be human-readable

set_price_forecast(forecasted_price)

Set the f_DA attribute

Parameters:: forecasted_price (float x 48) – cleared price in $/kWh

test_function(): Test function with the only purpose of returning the name of the object

tesp_support.dsot.battery_agent.test()

Testing

Makes a single agent and run DA

tesp_support.dsot.case_comparison_plots module

tesp_support.dsot.case_merge module

Combines GridLAB-D and agent files to run a multi-feeder TESP simulation

Public Functions:

merge_glm:: combines GridLAB-D input files
merge_glm_dict:: combines GridLAB-D metadata files
merge_agent_dict:: combines the substation agent configuration files
merge_substation_yaml:: combines the substation agent FNCS publish/subscribe files
merge_fncs_config:: combines GridLAB-D FNCS publish/subscribe files

tesp_support.dsot.case_merge.merge_agent_dict(target, sources)

Combines the substation agent configuration files into “target”. The source files must already exist.

Parameters:

target (str) – the path to the target JSON file, including the name of the file
sources (list) – list of feeder names in the target directory to merge

tesp_support.dsot.case_merge.merge_fncs_config(target, sources)

Combines GridLAB-D input files into “target”. The source feeders must already exist.

Parameters:

target (str) – the path to the target TXT file, including the name of the file
sources (list) – list of feeder names in the target directory to merge

tesp_support.dsot.case_merge.merge_glm(target, sources, xfmva)

Combines GridLAB-D input files into “target”. The source files must already exist.

Parameters:

target (str) – the path to the target GLM file, including the name of the file
sources (list) – list of feeder names in the target directory to merge
xfmva (int)

tesp_support.dsot.case_merge.merge_glm_dict(target, sources, xfmva)

Combines GridLAB-D metadata files into “target”. The source files must already exist.

The output JSON won’t have a top-level base_feeder attribute. Instead, the base_feeder from each source file will become a feeder key in the output JSON feeders dictionary, and then every child object on that feeder will have its feeder_id, originally network_node, changed to match the base_feeder.

Parameters:

target (str) – the path to the target JSON file, including the name of the file
sources (list) – list of feeder names in the target directory to merge
xfmva (int)

tesp_support.dsot.case_merge.merge_substation_yaml(target, sources)

Combines GridLAB-D input files into “target”. The source files must already exist.

Parameters:

target (str) – the path to the target YAML file, including the name of the file
sources (list) – list of feeder names in the target directory to merge

tesp_support.dsot.customer_CFS module

@author: yint392

tesp_support.dsot.customer_CFS.customer_CFS(GLD_metadata, metadata_path, customer, customer_bill, rate_scenario)

tesp_support.dsot.dso_CFS module

@author: yint392

tesp_support.dsot.dso_CFS.dso_CFS(case_config, DSOmetadata, dso_num, DSO_peak_demand, DSO_base_case_peak_demand, System_peak_fraction, DSO_Cash_Flows, DSO_Revenues_and_Energy_Sales, Market_Purchases, Market_Purchases_base_case, rate_scenario=None)

tesp_support.dsot.dso_helper_functions module

@author: yint392

tesp_support.dsot.dso_helper_functions.TEAM(FteLev1=100.0, SalaryEsc1=1.3)

tesp_support.dsot.dso_helper_functions.get_DSO_df(dso_range, case_config, DSOmetadata, case_path, base_case_path, rate_scenario=None)

tesp_support.dsot.dso_helper_functions.get_customer_df(dso_range, case_path, metadata_path, rate_scenario)

tesp_support.dsot.dso_helper_functions.get_mean_for_diff_groups(df, main_variables, variables_combs, cfs_start_position=25)

tesp_support.dsot.dso_helper_functions.labor(group, metadata_general, metadata_dso, utility_type, NoSubstations)

tesp_support.dsot.dso_helper_functions.labor_increase(group, metadata_general, metadata_dso, utility_type, NoSubstations, TransactiveCaseFlag)

tesp_support.dsot.dso_helper_functions.labor_network_admin(group, hourly_rate, metadata_general, metadata_dso, utility_type, NoSubstations)

tesp_support.dsot.dso_helper_functions.labor_network_admin_increase(group, hourly_rate, metadata_general, metadata_dso, utility_type, NoSubstations, TransactiveCaseFlag)

tesp_support.dsot.dso_helper_functions.labor_network_admin_transactive(group, hourly_rate, metadata_general, metadata_dso, utility_type, NoSubstations, TransactiveCaseFlag)

tesp_support.dsot.dso_helper_functions.labor_transactive(group, metadata_general, metadata_dso, utility_type, NoSubstations, TransactiveCaseFlag)

tesp_support.dsot.dso_helper_functions.returnDictSum(temp_dict)

tesp_support.dsot.dso_map module

tesp_support.dsot.dso_map.prepare_metadata(node, end_row, feeder_mode, high_renewables_case, DSO_Load_Threshold)

tesp_support.dsot.dso_market module

Class that manages the operation of DSO agent

Functionalities include: Aggregate demand bids from different substations; Wholesale no da trial clearing; Conversion between wholesale price and retail price; Generate substation supply curves with and without consideration of the transformer degradation.

class tesp_support.dsot.dso_market.DSOMarket(dso_dict, key)

Bases: object

This agent manages the DSO operating

Parameters:

dso_dict
key

name

name of the DSO agent

Type:: str

price_cap

the maximum price that is allowed in the market, in $/kWh

Type:: float

num_samples

the number of sampling points, describes how precisely the curve is sampled

Type:: int

windowLength

length of the planning horizon for the DA market, in hours

Type:: int

DSO_Q_max

maximum limit of the DSO load capacity, in kWh

Type:: float

transformer_degradation

flag variable, equals to 1 when transformer degradation effect is taken into account

Type:: bool

curve_a

array of second order coefficients for the wholesale node curve, indexed by day_of_sim and hour_of_day

Type:: array

curve_b

array of first order coefficients of the wholesale node curve, indexed by day_of_sim and hour_of_day

Type:: array

curve_c

array of intercepts of the wholesale node curve, indexed by day_of_sim and hour_of_day

Type:: array

Pwclear_RT

cleared wholesale price by real-time wholesale node trial clearing, in $/kWh

Type:: float

Pwclear_DA

list of cleared wholesale price by day-ahead wholesale node trial clearing, in $/kWh, indexed by hour

Type:: list

trial_cleared_quantity_RT

trial cleared quantity by real-time wholesale node trial clearing, in kWh

Type:: float

trial_cleared_quantity_DA

trial cleared quantity by day-ahead wholesale node trial clearing, in kWh

Type:: list

curve_DSO_RT

aggregated demand curve at DSO level from real-time retail market

Type:: Curve

curve_DSO_DA

dictionary of aggregated demand curves at DSO level from day-ahead retail market, indexed by hour

Type:: dict

curve_ws_node

dictionary of wholesale node curves, indexed by day_of_sim and hour_of_day

Type:: dict

trial_clear_type_RT

trial cleared type of real-time wholesale node trial clearing

Type:: int

trial_clear_type_DA

trial cleared type of day-ahead wholesale node trial clearing, indexed by hour

Type:: list

hour_of_day

current hour of the day

Type:: int

day_of_week

current day of the week

Type:: int

customer_count_mix_residential: Residential percentage of the total customer count mix

number_of_gld_homes: Total number of GLD homes for the DSO

clean_bids_DA(): Initialize the day-ahead wholesale node trial clearing

clean_bids_RT(): Initialize the real-time wholesale node trial clearing

curve_aggregator_DSO_DA(demand_curve_DA, Q_max)

Function used to aggregate the substation-level DA demand curves into a DSO-level DA demand curve

Parameters:

demand_curve_DA (dict) – a collection of demand curves to be aggregated for day-ahead
Q_max (float) – maximum capacity of the substation, in kW

curve_aggregator_DSO_RT(demand_curve_RT, Q_max)

Function used to aggregate the substation-level RT demand curves into a DSO-level RT demand curve

Parameters:

demand_curve_RT (Curve) – demand curve to be aggregated for real-time
Q_max (float) – maximum capacity of the substation, in kW

curve_preprocess(substation_demand_curve, Q_max)

An internal shared function called by curve_aggregator_DSO_RT and curve_aggregator_DSO_DA functions to truncate the substation demand curve before aggregation as well as convert the retail prices into wholesale prices

Parameters:

substation_demand_curve (Curve) – substation demand curve to be preprocessed
Q_max (float) – maximum capacity of the substation, in kW

Returns:

preprocessed demand curve

Return type:

preprocessed_curve (curve)

generate_TOC(costInterval, maxPuLoad, num_samples, TOC_dict)

Function used to calculate the total owning cost of transformer

Parameters:

costInterval (int) – interval for calculating the cost, in minutes
maxPuLoad (float) – maximum pu loading factor
num_samples (int) – number of sampling points
TOC_dict (dict) – configuration parameters for transformer

Returns:

price axis of unit owning cost, in $/kWh LoadsForPlot (list): quantity axis of unit owing cost, in kWh

Return type:

DollarsForPlot (list)

get_prices_of_quantities(Q, day, hour)

Returns the prices DSO quadratic curve cost for a list of quantities

Parameters:

Q (list of float) – quantities
day (int) – day of the week
hour (int) – hour of the day

Returns:

prices for the quantities

Return type:

P (list of float)

retail_rate(Pw)

Function used to convert the wholesale prices into retail prices

Parameters:: Pw (float) – wholesale price, in $/kWh
Returns:: retail price, in $/kWh
Return type:: Pr (float)

retail_rate_inverse(Pr)

Function used to convert the retail prices into wholesale prices

Parameters:: Pr (float) – retail price, in $/kWh
Returns:: wholesale price, in $/kWh
Return type:: Pw (float)

set_Pwclear_DA(hour_of_day, day_of_week)

Function used to implement the DA trial wholesale node clearing and update the Pwclear_DA value

Parameters:

hour_of_day (int) – current hour of the day
day_of_week (int) – current day of the week

set_Pwclear_RT(hour_of_day, day_of_week, lmp=False)

Function used to implement the RT trial wholesale node clearing and update the Pwclear_RT value

Parameters:

hour_of_day (int) – current hour of the day
day_of_week (int) – current day of the week
lmp

set_cleared_q_da(val)

Set the clear quantity for day ahead

Parameters:: val (double) – lmp for the bus/substation

set_cleared_q_rt(val)

Set the clear quantity for real time

Parameters:: val (double) – lmp for the bus/substation

set_ind_load(industrial_load)

Set the industrial load based on provided load by a csv file after base-case, complex number

Parameters:: industrial_load (str) – industrial load of substation

set_ind_load_da(industrial_load_da)

Set the ercot ind load for the next 24-hours provided load by a csv file after base-case, complex number

Parameters:: industrial_load_da (24 x 1 array of double) – industry load values for the next day ahead are given in MW

set_lmp_da(val)

Set the lmp for day ahead

Parameters:: val (array of double) – lmp for the day ahead

set_lmp_rt(val)

Set the lmp for real time

Parameters:: val (double) – lmp for the bus/substation

set_ref_load(ref_load)

Set the reference (ercot) load based on provided load by a csv file after base-case, complex number

Parameters:: ref_load (str) – total load of substation

set_ref_load_da(ref_load_da)

Set the ercot load for the next 24-hours provided load by a csv file after base-case, complex number

Parameters:: ref_load_da (24 x 1 array of double) – ercot load values for the next day ahead

set_total_load(total_load)

Set the residential load based on provided load by GLD, complex number

Parameters:: total_load (str) – total load of substation

substation_supply_curve_DA(retail_obj)

Function used to generate the DA supply curves for each substation

Args:

Variables:: FeederCongPrice (float): feeder congestion price, in $/kWh FeederPkDemandPrice (float): feeder peak demand price, in $/kWh FeederCongCapacity (float): feeder congestion capacity, in kWh FeederPkDemandCapacity (float): feeder peak demand, in kWh Q_max_retail (float): substation limit, in kWh Q_max_DSO (float): can change when the demand bid is higher than the original DSO limit maxPuLoading (float): maximum pu loading factor TOC_dict (dict): configuration parameters for transformer

Returns:: a collection of substation supply curves for day-ahead market clearing
Return type:: supply_curve_DA (list)

substation_supply_curve_RT(retail_obj)

Function used to generate the RT supply curve for each substation

Args:

Variables:: FeederCongPrice (float): feeder congestion price, in $/kWh FeederPkDemandPrice (float): feeder peak demand price, in $/kWh FeederCongCapacity (float): feeder congestion capacity, in kWh FeederPkDemandCapacity (float): feeder peak demand, in kWh Q_max_retail (float): substation limit, in kWh Q_max_DSO (float): can change when the demand bid is higher than the original DSO limit maxPuLoading (float): maximum pu loading factor TOC_dict (dict): configuration parameters for transformer

Returns:: substation supply curve for real-time market clearing
Return type:: supply_curve_RT (curve)

supply_curve(Prclear, FeederCongCapacity, FeederPkDemandCapacity, num_samples, Q_max, maxPuLoading, TOC_dict)

An internal shared function called by substation_supply_curve_RT and substation_supply_curve_DA functions to generate the supply curve when considering the transformer degradation

Parameters:

Prclear (float) – retail price overted from wholesale price obtained from trial wholesale node clearing, in $/kWh
FeederCongCapacity (float) – feeder congestion capacity, in kWh
FeederPkDemandCapacity (float) – feeder peak demand, in kWh
num_samples (int) – number of sampling points
Q_max (float) – substation limit, in kWh
maxPuLoading (float) – maximum pu loading factor
TOC_dict (dict) – configuration parameters for transformer

Variables:: FeederCongPrice (float): feeder congestion price, in $/kWh FeederPkDemandPrice (float): feeder peak demand price, in $/kWh

Returns:: quantity sampling of the supply curve, in kWh SupplyPrices (list): prices sampling of the supply curve, in $/kWh
Return type:: SupplyQuantities (list)

test_function(): Test function with the only purpose of returning the name of the object

trial_wholesale_clearing(curve_ws_node, curve_DSO, day, hour)

An internal shared function called by set_Pwclear_RT and set_Pwclear_DA functions to implement the trial wholesale node clearing

Parameters:

curve_ws_node (Curve) – wholesale node curve
curve_DSO (Curve) – aggregated demand curve at DSO level
day
hour

Returns:

cleared price, in $/kWh cleared_quantity(float): cleared quantity, in kWh trial_clear_type (int): clear type

Return type:

Pwclear (float)

update_wholesale_node_curve(): Update the wholesale node curves according to the most updated curve coefficients, may be updated every day

tesp_support.dsot.dso_market.test()

tesp_support.dsot.dso_quadratic_curves module

Class that prepares the quadratic curves for DSO market

class tesp_support.dsot.dso_quadratic_curves.DSO_LMPs_vs_Q(config_path='LMP_DATA', file_name='/Annual_DA_LMP_Load_data.csv')

Bases: object

This object creats the quadractive curves witht historical data from the base case

Parameters:

config_path (str) – path to file directory
file_name (str) – name of the CSV file containing the historical DA LMP prices with associated quantities

config_path

path to file directory

Type:: str

df_dsos_lml_q

list of lmps and associated quantity trou time

Type:: list od dataframes

lmps_names

list of lmps names

Type:: list of str

q_lmps_names

list of quantities names

Type:: list of str

degree

degree of curve to be fitted

Type:: int

coeficients_weekday

24 arrays of 3 for every DSO

Type:: array of arrays

coeficients_weekend

24 arrays of 3 for every DSO

Type:: array of arrays

c_to_DSO_m(DSO, C)

Convert coefficients to DSO market

Parameters:

DSO (int) – DSO identifier
C (int) – from 0 to 2 especifing the curve coeficient being taken

fit_model(i, p_time)

Fit a quadractive curve utilizing sklearn

Parameters:

i (int) – DSO identifier
p_time (np array bool) – True for samples utilized in fiiting the quadractic curve

Returns:

[[‘1’, ‘x’, ‘x^2’]] quadractic curve coeficients

Return type:

df_dsos_lml_q (array)

make_json_out(): Save the fitted curve to json

multiple_fit_calls()

Calls the fit model for each scenario

The scenarios are hour of day and day type (i.e., weekday and weekends)

organize_remuve_outliers(data_da)

Orginize and remuve outliers from dataframe of multiple DSO

Parameters:: data_da (dataframe) – contaings historical data from DA LMPs with associated quantities
Returns:: every element of the list is a DSO with historical price and quantiti. The index is pandas datetime.
Return type:: df_dsos_lml_q (list of dataframes)

tesp_support.dsot.dso_rate_making module

@author: reev057

tesp_support.dsot.dso_rate_making.DSO_rate_making(case, base_case, dso_num, metadata, dso_expenses, tariff_path, dso_scaling_factor, num_indust_cust, case_name='', iterate=False, rate_scenario=None, trans_cost_balance_method=None)

Main function to call for calculating the customer energy consumption, monthly bills, and tariff adjustments to ensure revenue matches expenses. Saves meter and bill dataframes to a hdf5 file. :param case: directory path for the case to be analyzed :type case: str :param base_case: directory path for the base case containing baseline demand values :type base_case: str :param dso_num: number of the DSO folder to be opened :type dso_num: str :param metadata: :param dso_expenses: dso expenses that need to be matched by customer revenue :type dso_expenses: TBD :param tariff_path: :param dso_scaling_factor: multiplier on customer bills to reflect the total number of customers in the DSO :type dso_scaling_factor: float :param num_indust_cust: number of industrial customers :type num_indust_cust: int :param case_name: name of the case (‘MR-BAU’, ‘MR-Batt’, ‘MR-Flex’, ‘MR-BAU’, ‘MR-Batt’, ‘MR-Flex’) :type case_name: str :param iterate: If True will iterate once to square up revenue. :type iterate: Boolean :param rate_scenario: A str specifying the rate scenario under investigation: flat, :type rate_scenario: str :param time-of-use: :param subscription: :param or transactive. If None: :param this function defaults to DSO+T.: :param trans_cost_balance_method: A str indicating the cost component of the transactive :type trans_cost_balance_method: str :param rate that will be adjusted to recover all unmet costs.:

Returns:: dataframe of energy consumption and max 15 minute power consumption for each month and total bill_df : dataframe of monthly and total bill for each house broken out by each element (energy, demand, connection, and total bill) tariff: Updated dictionary of tariff structure with rates adjusted to ensure revenue meets expenses surplus: dollar value difference between dso revenue and expenses. When converged should be tiny (e.g. 1e-12)
Return type:: meter_df

tesp_support.dsot.dso_rate_making.annual_energy(month_list, folder_prefix, dso_num, metadata)

Creates a dataframe of monthly energy consumption values and annual sum based on monthly h5 files. :param month_list: list of lists. Each sub list has month name (str), directory path (str) :type month_list: list :param folder_prefix: prefix of GLD folder name (e.g. ‘/TE_base_s’) :type folder_prefix: str :param dso_num: number of the DSO folder to be opened :type dso_num: str :param metadata: metadata of GridLAB-D model entities :type metadata: dict

Returns:: dataframe of energy consumption and max 15 minute power consumption for each month and total year_energysum_df: dataframe of energy consumption summations by customer class (res., commercial, and indust)
Return type:: year_meter_df

tesp_support.dsot.dso_rate_making.calc_cust_bill(metadata, meter_df, trans_df, energy_sum_df, tariff, dso_num, SF, ind_cust)

Calculate the customer bill using summary meter data and fixed tariff structure. :param metadata: metadata structure for the DSO to be analyzed :type metadata: dict :param meter_df: monthly and total energy consumption and peak power by house (meter) :type meter_df: dataframe :param trans_df: :param energy_sum_df: :param tariff: dictionary of fixed tariff structure :type tariff: dict :param dso_num: :param SF: Scaling factor to scale GLD results to TSO scale (e.g. 1743) :type SF: float :param ind_cust: number of industrial customers :type ind_cust: int

Returns:: dataframe of monthly and total bill for each house broken out by each element (energy, demand, connection, and total bill)
Return type:: bill_df

tesp_support.dsot.dso_rate_making.calculate_consumer_bills(case_path, base_path, metadata, meter_df, trans_df, energy_sum_df, tariff, dso_num, sf, num_ind_cust, rate_scenario)

Calculates the consumers’ bills for the four different scenarios considered in the Rates Analysis work. :param case_path: A string specifying the directory path of the case being analyzed. :type case_path: str :param base_path: A string specifying the directory path of the reference case (containing baseline demand). :type base_path: str :param metadata: A dictionary containing the metadata structure of the DSO. :type metadata: dict :param meter_df: DataFrame containing consumers’ consumption information. :type meter_df: pandas.DataFrame :param trans_df: DataFrame containing consumers’ transactive consumption :type trans_df: pandas.DataFrame :param information.: :param energy_sum_df: DataFrame containing consumption information for :type energy_sum_df: pandas.DataFrame :param each consumer class.: :param tariff: A dictionary of pertinant tariff information. Includes information :type tariff: dict :param for the volumetric rates: :type for the volumetric rates: i.e., flat and time-of-use :param dso_num: A string specifying the number of the DSo being considered. :type dso_num: str :param sf: Scaling factor to scale the GridLAB-D results to TSO scale. :type sf: float :param num_ind_cust: Number of industrial consumers. :type num_ind_cust: int :param rate_scenario: A str specifying the rate scenario under investigation: flat, :type rate_scenario: str :param time-of-use: :param subscription: :param transactive: :param or dsot.:

Returns:: DataFrame containing bill information for each meter. billsum_df (pandas.DataFrame): DataFrame containing bill information for each load sector.
Return type:: bill_df (pandas.DataFrame)

tesp_support.dsot.dso_rate_making.calculate_tariff_prices(case_path, base_case_path, metadata, meter_df, trans_df, energy_sum_df, tariff, dso_num, sf, num_ind_cust, industrial_file, rate_scenario, trans_cost_balance_method=None)

Determines the prices that ensure enough revenue is collected to recover the DSO’s expenses. :param case_path: A string specifying the directory path of the case being analyzed. :type case_path: str :param base_case_path: A string specifying the directory path of the base_case being used as a reference. :type base_case_path: str :param metadata: A dictionary containing the metadata structure of the DSO. :type metadata: dict :param meter_df: DataFrame containing consumers’ consumption information. :type meter_df: pandas.DataFrame :param trans_df: DataFrame containing consumers’ transactive consumption :type trans_df: pandas.DataFrame :param information.: :param energy_sum_df: DataFrame containing consumption information for :type energy_sum_df: pandas.DataFrame :param each consumer class.: :param tariff: A dictionary of pertinant tariff information. Includes information :type tariff: dict :param for the volumetric rates: :type for the volumetric rates: i.e., flat and time-of-use :param dso_num: A string specifying the number of the DSO being considered. :type dso_num: str :param sf: Scaling factor to scale the GridLAB-D results to TSO scale. :type sf: float :param num_ind_cust: Number of industrial consumers. :type num_ind_cust: int :param industrial_file: File path to the bulk industrial loads. :type industrial_file: str :param rate_scenario: A str specifying the rate scenario under investigation: flat, :type rate_scenario: str :param time-of-use: :param subscription: :param transactive: :param or dsot.: :param trans_cost_balance_method: A str indicating the cost component of the :type trans_cost_balance_method: str :param transactive rate that will be adjusted to recover all unmet costs.:

Returns:: A dictionary containing the prices that need to be calculated for each of the rates considered in the rate scenario.
Return type:: prices (dict)

tesp_support.dsot.dso_rate_making.calculate_tier_credit(dso_num, tariff_class, tariff, total_energy)

Calculate the tier credit added to the consumers’ bills from the declining-block rate. :param dso_num: A string specifying the number of the DSO being considered. :type dso_num: str :param tariff_class: Indicates the type of consumer that is under consideration. :type tariff_class: str :param tariff: A dictionary of pertinant tariff information. Includes information :type tariff: dict :param for the volumetric rates: :type for the volumetric rates: i.e., flat and time-of-use :param total_energy: Consumer’s total energy consumption for the month. :type total_energy: float

Returns:: The tier credit that will be applied to the energy portion of the consumer’s bill.
Return type:: tier_credit (float)

tesp_support.dsot.dso_rate_making.create_baseline_demand_profiles_for_each_meter(demand_df, dso_num, type_of_baseline, save=False, save_path=None)

Creates a pandas DataFrame that contains hourly time-series data for each meter in a DSO. The data in this DataFrame is configured to be a baseline demand profile, determined according to a specified metric. The resultant DataFrame can be saved to a .h5 file if desired. :param demand_df: Monthly hourly demand data for each meter. :type demand_df: pandas.DataFrame :param dso_num: The number of a valid substation in the system model. :type dso_num: int :param type_of_baseline: The type of baseline demand that should be considered. :type type_of_baseline: str :param There are four types of baselines supported by this function: ‘daily’, :param ‘day_of_week’: :param ‘weekdays_and_weekends’: :param and ‘monthly’.: :param save: Indicates whether the output data should be saved in a .h5 :type save: bool :param file. If True: :param data is saved to the location specified by ‘save_path’.: :param save_path: File path that indicates where the resultant baseline demand :type save_path: str :param profile should be saved: :param if allowed by ‘save’.:

Returns:: Monthly hourly baseline demand data for each meter.
Return type:: bl_demand_df (pandas.DataFrame)

tesp_support.dsot.dso_rate_making.create_demand_profiles_for_each_meter(dir_path, dso_num, day_range, save=False)

Creates a pandas DataFrame that contains hourly time-series data for each meter in a DSO. The resultant DataFrame can be saved to a .h5 file if desired. :param dir_path: Contains file path of daily power and voltage information for :type dir_path: str :param each meter in five-minute time steps.: :param dso_num: The number of a valid substation in the system model. :type dso_num: int :param day_range: List of day numbers in a month to be considered. :type day_range: list :param save: Indicates whether the output data should be saved in a .h5 :type save: bool :param file. If True: :param data is saved to the same location as what is provided in: :param ‘dir_path’.:

Returns:: Monthly hourly demand data for each meter.
Return type:: demand_df (pandas.DataFrame)

tesp_support.dsot.dso_rate_making.get_cust_bill(cust, bill_df, bill_metadata, energy_df, rate_scenario)

Populates dictionary of individual customer’s annual bill. :param cust: customer name (meter name from GLD dictionary) :type cust: str :param bill_df: dataframe of annual and monthly customer bills :type bill_df: dataframe :param bill_metadata: dictionary of GLD metadata including tarrif and building type for each meter :type bill_metadata: dict :param energy_df: :param rate_scenario: A str specifying the rate scenario under investigation: flat, :type rate_scenario: str :param time-of-use: :param subscription: :param or transactive. If None: :param this function defaults to DSO+T.:

Returns:: dictionary of customers annual energy bill
Return type:: customer_annual_bill (dict)

tesp_support.dsot.dso_rate_making.get_total_dso_costs(case_path, dso_num, rate_scenario, seasons_dict=None)

Sets the DSO’s expenses according to the rate scenario being considered. Uses an arbitrarily selected large value (that attempts to still be a similar order of magnitude as the DSO’s expected expenses) if the DSO CFS results have not been calculated and stored. :param case_path: A string specifying the directory path of the case being analyzed. :type case_path: str :param dso_num: A string specifying the number of the DSo being considered. :type dso_num: str :param rate_scenario: A str specifying the rate scenario under investigation: flat, :type rate_scenario: str :param time-of-use: :param subscription: :param or transactive.: :param seasons_dict: A dict specifying the seasons being considered and their :type seasons_dict: dict :param constituent months. Defaults to None.:

Returns:: The DSO’s total expenses, provided as a float, or the seasonal expenses, provided as a dict.
Return type:: dso_expenses (float/dict)

tesp_support.dsot.dso_rate_making.read_meters(metadata, dir_path, folder_prefix, dso_num, day_range, SF, dso_data_path, rate_scenario=None)

Determines the total energy consumed and max power consumption for all meters within a DSO for a series of days. Also collects information on day ahead and real time quantities consumed by transactive customers. Creates summation of these statistics by customer class. :param metadata: metadata structure for the DSO to be analyzed :type metadata: dict :param dir_path: directory path for the case to be analyzed :type dir_path: str :param folder_prefix: prefix of GLD folder name (e.g. ‘TE_base_s’) :type folder_prefix: str :param dso_num: number of the DSO folder to be opened :type dso_num: str :param day_range: range of days to be summed (for example a month). :type day_range: list :param SF: Scaling factor to scale GLD results to TSO scale (e.g. 1743) :type SF: float :param dso_data_path: A str specifying the directory in which the time-of-use rate :type dso_data_path: str :param rate_scenario: A str specifying the rate scenario under investigation (e.g. :type rate_scenario: str :param flat: :param time-of-use or TOU: :param subscription: :param or transactive): :param defaults to None.:

Returns:: dataframe of energy consumption and max 15 minute power consumption for each month and total energysum_df: dataframe of energy consumption summations by customer class (residential, commercial, and industrial) saves the two dataframe above to an h5 file in the dir_path
Return type:: meter_df

tesp_support.dsot.ev_agent module

Class that controls the Electric Vehicle

Implements the optimum schedule of charging and discharging DA; generate the bids for DA and RT; monitor and supervisory control of GridLAB-D environment element.

The function call order for this agent is:

initialize()

set_price_forecast(forecasted_price)

Repeats at every hour:

formulate_bid_da() {return BID}
set_price_forecast(forecasted_price)

Repeats at every 5 minutes:

set_SOC(msg_str) {updates C_init}
formulate_bid_rt() {return BID}
inform_bid(price) {update RTprice}
bid_accepted() {update inv_P_setpoint and GridLAB-D P_out if needed}

class tesp_support.dsot.ev_agent.EVDSOT(diction, inv_properties, key, model_diag_level, sim_time, solver)

Bases: object

This agent manages the electric vehicle (ev)

Parameters:

diction (dict) – electric vehicle parameters
inv_properties (dict)
key (str)
model_diag_level (int) – Specific level for logging errors; set it to 11
sim_time (str) – Current time in the simulation; should be human-readable
solver (str)

Initialize from Args

name

name of this agent

Type:: str

Rc

rated charging power in kW for the battery

Type:: float

Rd

rated discharging power in kW for the battery

Type:: float

Lin

battery charging loss in %

Type:: float

Lout

battery discharging loss in %

Type:: float

Cmin

minimum allowable stored energy in kWh (state of charge lower limit)

Type:: float

Cmax

maximum allowable stored energy in kWh (state of charge upper limit)

Type:: float

Cinit

initial stored energy in the battery in kWh

Type:: float

capacity

battery capacity in kWh

Type:: float

batteryLifeDegFactor

constant to model battery degradation

Type:: float

windowLength

length of day ahead optimization period in hours (e.g. 48-hours)

Type:: int

dayAheadCapacity

% of battery capacity reserved for day ahead bidding

Type:: float

No initialization required

bidSpread

this can be used to spread out bids in multiple hours. When set to 1 hour (recommended), it’s effect is none

Type:: int

P

location of P in bids

Type:: int

Q

location of Q in bids

Type:: int

f_DA

forecasted prices in $/kWh for all the hours in the duration of windowLength

Type:: List[float]) (1 X windowLength

RT_state_maintain

true if battery must maintain charging or discharging state for 1 hour

Type:: bool

RT_state_maintain_flag

not define at current hour (-1) charging (+1) discharging

Type:: int

RT_flag

if True, has to update GridLAB-D

Type:: bool

inv_P_setpoint

next GridLAB-D inverter power output

Type:: float

optimized_Quantity

Optimized quantity

Type:: List[float]) (1 X Window Length

#not used if not biding DA

prev_clr_Quantity

cleared quantities (kWh) from previous market iteration for all hours

Type:: List[float]) (1 X Window Length

prev_clr_Price

cleared prices ($/kWh) from previous market iteration

Type:: List[float]) (1 X windowLength

BindingObjFunc

if True, then optimization considers cleared price, quantities from previous iteration in the objective function

Type:: bool

DA_cleared_price(price)

Set the DA_cleared_price attribute

Parameters:: price (float) – cleared price in $/kWh

DA_model_parameters(sim_time)

DA_optimal_quantities()

Generates Day Ahead optimized quantities for agent

Returns:: Optimal quantity from optimization for all hours of the window specified by windowLength
Return type:: Quantity (float) (1 x windowLength)

RT_fix_four_points_range(BID, Ql, Qu)

Verify feasible range of RT bid

Parameters:

BID (float) ((1,2)X4) – 4 point bid
Ql
Qu

Returns:

4 point bid only the feasible range

Return type:

BIDr (float) ((1,2)X4)

RT_gridlabd_set_P(model_diag_level, sim_time)

Update variables for battery output “inverter”

Parameters:

model_diag_level (int) – Specific level for logging errors; set it to 11
sim_time (str) – Current time in the simulation; should be human-readable

inv_P_setpoint is a float in W

bid_accepted(current_time)

Update the P and Q settings if the last bid was accepted

Returns:: True if the inverter settings changed, False if not.
Return type:: bool

con_rule_eq1(m, i)

con_rule_eq2(m, i)

con_rule_eq3(m, i)

con_rule_eq4(m, i)

con_rule_ine1(m, i)

con_rule_ine2(m, i)

formulate_bid_da()

Formulate 4 points of P and Q bids for the DA market

Function calls “DA_optimal_quantities” to obtain the optimal quantities for the DA market. With the quantities, the 4 point bids are formulated.

Before returning the BID the function resets “RT_state_maintain_flag” which, if RT_state_maintain is TRUE, the battery will be forced to keep its state (i.e., charging or discharging).

Returns:: store last DA market bids
Return type:: BID (float) (((1,2)X4) X windowLength)

formulate_bid_rt()

Formulates RT bid

Uses the last 4 point bid from DA market and consider current state of charge of the battery. Will change points to change points for feasible range of Qmin Qmax points if necessary. Furthermore, allows a maximum deviation of +/-100% from the DA plan.

Returns:: bid in Real Time market
Return type:: realTimeBid (float) ((1,2) x 4)

from_P_to_Q_battery(BID, PRICE)

Convert the 4 point bids to a quantity with the known price

Parameters:

BID (float) ((1,2)X4) – 4 point bid
PRICE (float) – cleared price in $/kWh

Returns:

active power (-) charging (+) discharging

Return type:

_quantity (float)

get_car_home_duration(cur_secs, interval)

Return the duration of car at home during the given ‘interval’ seconds starting from cur_secs

Parameters:

cur_secs – (seconds) current (starting) time with reference of midnight as 0
interval – (seconds) duration in which status needs to be estimated

Returns:

duration in seconds for which car is at home in given interval

get_uncntrl_ev_load(sim_time)

Function returns 48-hour forecast of ev load in base case w/o optimization

Parameters:: sim_time (datetime)
Returns:: 48-hour forecast of ev load in base case w/o optimization
Return type:: list

inform_bid(price)

Set the cleared_price attribute

Parameters:: price (float) – cleared price in $/kWh

is_car_home(cur_secs)

Is the Car is at home

Parameters:: cur_secs – current time in seconds
Returns:: if car is at home at cur_secs is True or otherwise False
Return type:: bool

is_car_leaving_home(cur_secs, interval)

Tells if car is leaving from home during the given ‘interval’

Parameters:

cur_secs – (seconds) current (starting) time with reference of midnight as 0
interval – (seconds) duration in which status needs to be estimated

Returns:

if car is leaving from home during the given ‘interval’: seconds starting from cur_secs is True or otherwise False

Return type:

bool

obj_rule(m)

set_SOC(msg_str, model_diag_level, sim_time)

Set the ev state of charge

Updates the self.Cinit of the battery

Parameters:

msg_str (str) – message with ev SOC in percentage
model_diag_level (int) – Specific level for logging errors; set it to 11
sim_time (str) – Current time in the simulation; should be human-readable

set_price_forecast(forecasted_price)

Set the f_DA attribute

Parameters:: forecasted_price (float x 48) – cleared price in $/kWh

test_function(): Test function with the only purpose of returning the name of the object

tesp_support.dsot.ev_agent.test()

Testing

Makes a single agent and run DA

tesp_support.dsot.forecasting module

Class responsible for forecasting

Implements the substation level DA price forecast and load forecast. Accesses forecast data using the schedule server; see “schedule_server.py” for further implementation details.

class tesp_support.dsot.forecasting.Forecasting(port, config_Q)

Bases: object

This Class perform the forecast

Parameters:

TODO (#) – update inputs
TODO – Load base case run files

# TODO: update attributes

add_skew_scalar(datafr, N_skew, N_scalar)

Skew the values with given seconds and multiply by scalar in the whole year dataframe

Args: datafr (DataFrame): dataframe created with the schedule name for a year N_skew (int): number of seconds to skew either (+ or -)

calc_solar_flux(cpt, day_of_yr, lat, sol_time, dnr_i, dhr_i, vertical_angle)

calc_solargain(day_of_yr, time, dnr, dhr, lat, lon, tz_offset)

correcting_Q_forecast_10_AM(Q_10_AM, offset, day_of_week)

Corrects the quantity submitted to the wholesale market at 10 AM

Parameters:: Q_10_AM (list of 24 float) – DA quantities
Returns:: Corrected 10 AM Quantities

forecasting_schedules(name, time, len_forecast=48)

get_internal_gain_forecast(skew_scalar, time, extra_forecast_hours=0)

Forecast the electric zip_load and internal gain of all zip loads of a house by reading schedule files and applying skew. Forecast is for 48-hours ahead from start time :param skew_scalar: dictionary containing ‘zip_skew’, ‘zip_scalar’ and ‘zip_heatgain_fraction’ for each zip load :param ‘zip_skew’ is a scalar and same for all type of zip loads for the given house. ‘zip_scalar’ and ‘zip_heatgain_fraction’: :param are dictionary containing different values for each tyoe of zip load: :param time: Datetime format: forecast start time :param extra_forecast_hours: (int) number of hours for which forecast needs to be stored. For example if it is 24, then :param we need to get forecast for 48+24=72 hours so that there is no need to come back to this function for next 24-hours.:

Returns:: list of (48+extra_forecast_hours) values of total zipl loads and total internal gain due to zip loads

get_solar_forecast(time, dso_num)

get_solar_gain_forecast(climate_conf, current_time)

get_substation_unresponsive_industrial_load_forecast(peak_load=3500.0)

Get substation unresponsive industrial load forecast

Args:
peak_load (float): peak load in kWh

Returns:: forecast of next 48-hours unresponsive load
Return type:: base_run_load (float x 48)

get_substation_unresponsive_load_forecast(peak_load=7500.0)

Get substation unresponsive load forecast

TODO: Update to model that make use of the base case run files TODO: Get weather forecast from weather agent

Parameters:: peak_load (float) – peak load in kWh
Returns:: forecast of next 48-hours unresponsive load
Return type:: base_run_load (float x 48)

get_waterdraw_forecast(skew_scalar, time)

static initialize_schedule_dataframe(start_time, end_time)

Initialize the data frame for one year

Parameters:

start_time (datetime, str) – time in str format - DD/MM/YYY HH:MT:SS
end_time (datetime, str) – time in str format - DD/MM/YYY HH:MT:SS

make_dataframe_schedule(filename, schedule_name)

Reads .glm files with multiple schedule names and makes dataframe for a year for given schedule name

Parameters:

filename (str) – name of glm file to be loaded
schedule_name (str) – name of the schedule to be laoded

set_retail_price_forecast(DA_SW_prices)

Set substation price forecast

Nonsummable diminishing.

Parameters:: DA_SW_prices (float x 48) – cleared price in $/kWh from the last shifting window run
Returns:: forecasted prices in $/kWh for the next 48-hours
Return type:: forecasted_price (float x 48)

set_sch_year(year)

set_solar_diffuse_forecast(fncs_str): Set the 48-hour solar diffuse forecast :param param fncs_str: solar_diffuse_forecast ([float x 48]):

set_solar_direct_forecast(fncs_str): Set the 48-hour solar direct forecast :param param fncs_str: solar_direct_forecast ([float x 48]):

set_temperature_forecast(fncs_str)

Set the 48-hour temperature forecast

Parameters:: fncs_str – temperature_forecast ([float x 48]): predicted temperature in F

tesp_support.dsot.forecasting.test()

tesp_support.dsot.gen_map module

tesp_support.dsot.gen_map.prepare_network(node, node_col, high_renewables_case, zero_pmin=False, zero_index=False, on_ehv=True, split_start_cost=False, high_ramp_rates=False, coal=True)

tesp_support.dsot.generator_balance_sheet_func module

@author: yint392

tesp_support.dsot.generator_balance_sheet_func.generator_balance_sheet_annual(generator_num, gen_type, meta_path, system_path, path_to_write, write_to_txt=False, write_to_JSON=False)

tesp_support.dsot.glm_dictionary module

Functions to create metadata from a GridLAB-D input (GLM) file

Metadata is written to a JSON file, for convenient loading into a Python dictionary. It can be used for agent configuration, e.g., to initialize a forecasting model based on some nominal data. It’s also used with metrics output in post-processing.

Public Functions:

glm_dict:: Writes the JSON metadata file.

tesp_support.dsot.glm_dictionary.append_include_file(lines, fname)

tesp_support.dsot.glm_dictionary.ercotMeterName(objname)

Enforces the meter naming convention for ERCOT

Replaces anything after the last _ with mtr.

Parameters:: objname (str) – the GridLAB-D name of a house or inverter
Returns:: The GridLAB-D name of upstream meter
Return type:: str

tesp_support.dsot.glm_dictionary.glm_dict(name_root, config=None, ercot=False)

Writes the JSON metadata file from a GLM file

This function reads name_root.glm and writes [name_root]_glm_dict.json The GLM file should have some meters and triplex_meters with the bill_mode attribute defined, which identifies them as billing meters that parent houses and inverters. If this is not the case, ERCOT naming rules can be applied to identify billing meters.

Parameters:

name_root (str) – path and file name of the GLM file, without the extension
config (dict)
ercot (bool) – request ERCOT billing meter naming. Defaults to false. — THIS NEEDS TO LEAVE THIS PLACE
te30 (bool) – request hierarchical meter handling in the 30-house test harness. Defaults to false. — THIS NEEDS TO LEAVE THIS PLACE

tesp_support.dsot.glm_dictionary.ti_enumeration_string(tok): if thermal_integrity_level is an integer, convert to a string for the metadata

tesp_support.dsot.helpers_dsot module

Utility functions for use within tesp_support, including new agents. This is DSO+T specific helper functions

class tesp_support.dsot.helpers_dsot.Curve(pricecap, num_samples)

Bases: object

Accumulates a set of price, quantity bidding curves for later aggregation

Parameters:

pricecap (float) – the maximum price that is allowed in the market, in $/kWh
num_samples (int) – the number of sampling points, describes how precisely the curve is sampled

prices

array of prices, in $/kWh

Type:: [float]

quantities

array of quantities, in kW

Type:: [float]

uncontrollable_only

equals to 1 when there is only uncontrollable load demand bids in the market

Type:: bool

curve_aggregator(identity, bid_curve)

Adding one more bid curve to the aggregated seller or buyer curve

Args:
identity (str): identifies whether the bid is collected from a “Buyer” or “Seller” bid_curve ([list]): a nested list with dimension (m, 2), with m equals 2 to 4

curve_aggregator_DSO(substation_demand_curve)

Adding one substation bid curve to the aggregated DSO bid curve,

applied when then curve instance is a DSO demand curve

Args:: substation_demand_curve(Curve): a curve object representing the aggregated substation demand curve

update_price_caps(): Update price caps based on the price points

class tesp_support.dsot.helpers_dsot.HvacMode(value)

Bases: IntEnum

Describes the operating mode of the HVAC

COOLING = 0

HEATING = 1

class tesp_support.dsot.helpers_dsot.MarketClearingType(value)

Bases: IntEnum

Describes the market clearing type

CONGESTED = 1

FAILURE = 2

UNCONGESTED = 0

tesp_support.dsot.helpers_dsot.curve_bid_sorting(identity, bid_curve)

Sorting the 4-point curve bid primarily on prices and secondarily on quantities

For “Buyer”, the bid prices are ordered descendingly and bid quantities are ordered ascendingly; For “Seller”, both the bid prices and the bid quantities are ordered descendingly;

Parameters:

identity (str) – identifies whether the bid is collected from a “Buyer” or “Seller”
bid_curve ([list]) – unsorted curve bid

Outputs:: sorted_bid_curve ([list]): sorted curve bid

tesp_support.dsot.helpers_dsot.get_intersect(a1, a2, b1, b2)

tesp_support.dsot.helpers_dsot.resample_curve(x_vec, y_vec, min_q, max_q, num_samples)

tesp_support.dsot.helpers_dsot.resample_curve_for_market(x_vec_1, y_vec_1, x_vec_2, y_vec_2)

tesp_support.dsot.helpers_dsot.resample_curve_for_price_only(x_vec_1, x_vec_2, y_vec_2)

tesp_support.dsot.helpers_dsot.test()

tesp_support.dsot.helpers_dsot.write_dsot_management_script(master_file, case_path, system_config=None, substation_config=None, weather_config=None)

Write experiment management scripts from JSON configuration data, linux and helics only

Reads the simulation configuration file or dictionary and writes

run.{sh, bat}, simple run script to launch experiment
kill.{sh, bat}, simple run script to kill experiment
clean.{sh, bat}, simple run script to clean generated output files from the experiment

Parameters:

master_file (str) – name of the master file to the experiment case
case_path (str) – path to the experiment case
system_config (dict) – configuration of the system for the experiment case
substation_config (dict) – configuration of the substations in the experiment case
weather_config (dict) – configuration of the climates being used

tesp_support.dsot.helpers_dsot.write_dsot_management_script_f(master_file, case_path, system_config=None, substation_config=None, weather_config=None)

Write experiment management scripts from JSON configuration data, windows and linux, fncs only

Reads the simulation configuration file or dictionary and writes

run.{sh, bat}, simple run script to launch experiment
kill.{sh, bat}, simple run script to kill experiment
clean.{sh, bat}, simple run script to clean generated output files from the experiment

Parameters:

master_file (str) – name of the master file to the experiment case
case_path (str) – path to the experiment case
system_config (dict) – configuration of the system for the experiment case
substation_config (dict) – configuration of the substations in the experiment case
weather_config (dict) – configuration of the climates being used

tesp_support.dsot.helpers_dsot.write_management_script(archive_folder, case_path, outPath, gld_Debug, run_post)

tesp_support.dsot.helpers_dsot.write_mircogrids_management_script(master_file, case_path, system_config=None, substation_config=None, weather_config=None)

Write experiment management scripts from JSON configuration data, linux ans helics only

Reads the simulation configuration file or dictionary and writes

run.{sh, bat}, simple run script to launch experiment
kill.{sh, bat}, simple run script to kill experiment
clean.{sh, bat}, simple run script to clean generated output files from the experiment

Parameters:

master_file (str) – name of the master file to the experiment case
case_path (str) – path to the experiment case
system_config (dict) – configuration of the system for the experiment case
substation_config (dict) – configuration of the substations in the experiment case
weather_config (dict) – configuration of the climates being used

tesp_support.dsot.helpers_dsot.write_players_msg(case_path, sys_config, dt)

tesp_support.dsot.hvac_agent module

Class that …

TODO: update the purpose of this Agent

class tesp_support.dsot.hvac_agent.HVACDSOT(hvac_dict, house_properties, key, model_diag_level, sim_time, solver)

Bases: object

This agent …

# TODO: update the purpose of this Agent

Parameters:

hvac_dict (dict)
house_properties (dict)
key (str)
model_diag_level (int) – Specific level for logging errors; set it to 11
sim_time (str) – Current time in the simulation; should be human-readable
solver (str)

# TODO: update attributes for this agent

DA_model_parameters(moh3, hod3, dow3)

self.basepoint_cooling = 73.278 self.temp_min_cool = self.temp_min_cool + self.basepoint_cooling self.temp_max_cool = self.temp_max_cool + self.basepoint_cooling self.thermostat_mode = ‘Cooling’

if self.thermostat_mode == ‘Cooling’:: temp_min_48hour = self.temp_min_cool temp_max_48hour = self.temp_max_cool
else:: temp_min_48hour = self.temp_min_heat temp_max_48hour = self.temp_max_heat

DA_optimal_quantities()

Generates Day Ahead optimized quantities for Water Heater according to the forecasted prices and water draw schedule, called by DA_formulate_bid function

Returns:: Optimized quantities for each hour in the DA bidding horizon, in kWh
Return type:: Quantity (list) (1 x windowLength)

bid_accepted(model_diag_level, sim_time)

Update the thermostat setting if the last bid was accepted

The last bid is always “accepted”. If it wasn’t high enough, then the thermostat could be turned up.

Parameters:

model_diag_level (int) – Specific level for logging errors; set to 11
sim_time (str) – Current time in the simulation; should be human-readable

Returns:

True if the thermostat setting changes, False if not.

Return type:

bool

calc_etp_model()

Sets the ETP parameters from configuration data

References

Thermal Integrity Table Inputs and Defaults

calc_solar_flux(cpt, day_of_yr, lat, sol_time, dnr_i, dhr_i, vertical_angle)

calc_solargain(day_of_yr, start_hour, dnr, dhr, lat, lon, tz_offset)

calc_thermostat_settings(model_diag_level, sim_time)

Sets the ETP parameters from configuration data

Parameters:

model_diag_level (int) – Specific level for logging errors; set to 11
sim_time (str) – Current time in the simulation; should be human-readable

References

Table 3 - Easy to use slider settings

change_basepoint(model_diag_level, sim_time)

Updates the time-scheduled thermostat setting

Parameters:

model_diag_level (int) – Specific level for logging errors; set to 11
sim_time (str) – Current time in the simulation; should be human-readable

Returns:

True if the setting changed, False if not

Return type:

bool

con_rule_eq1(m, t)

formulate_bid_da()

Formulate windowLength hours 4 points PQ bid curves for the DA market

Function calls DA_optimal_quantities to obtain the optimal quantities for the DA market. With the quantities, a 4 point bids are formulated for each hour.

Returns: BID (float) (windowLength X 4 X 2): DA bids to be sent to the retail DA market

formulate_bid_rt(model_diag_level, sim_time)

Bid to run the air conditioner through the next period for real-time

Parameters:

model_diag_level (int) – Specific level for logging errors; set to 11
sim_time (str) – Current time in the simulation; should be human-readable

Returns:

[bid price $/kwh, bid quantity kW] x 4

Return type:

[[float, float], [float, float], [float, float], [float, float]]

get_scheduled_setpt(moh3, hod4, dow3)

Parameters:

moh3 – (int): the minute of the hour from 0 to 59
hod4 – (int): the hour of the day, from 0 to 23
dow3 – (int): the day of the week, zero being Monday

get_solargain(climate_conf, current_time)

estimates the nominal solargain without solargain_factor

Parameters:

climate_conf – latitude and longitude info in a dict
current_time – the time for which solargain needs to be estiamted

get_uncntrl_hvac_load(moh, hod, dow)

inform_bid(price)

Set the cleared_price attribute

Parameters:: price (float) – cleared price in $/kwh

obj_rule(m)

set_air_temp(fncs_str, model_diag_level, sim_time)

Sets the air_temp attribute

Parameters:

fncs_str (str) – FNCS message with temperature in degrees Fahrenheit
model_diag_level (int) – Specific level for logging errors; set to 11
sim_time (str) – Current time in the simulation; should be human-readable

set_da_cleared_quantity(BID, PRICE)

Convert the 4 point bids to a quantity with the known price

Parameters:

BID (float) ((1,2)X4) – 4 point bid
PRICE (float) – cleared price in $/kWh

Returns:

cleared quantity

Return type:

quantity (float)

set_house_load(fncs_str)

Sets the hvac_load attribute, if greater than zero

Parameters:: fncs_str (str) – FNCS message with load in kW

set_humidity(fncs_str)

Sets the humidity attribute

Parameters:: fncs_str (str) – FNCS message with humidity

set_humidity_forecast(fncs_str)

Set the 48-hour price forecast and calculate min and max

Parameters:: fncs_str – temperature_forecast ([float x 48]): predicted temperature in F

set_hvac_load(fncs_str)

Sets the hvac_load attribute, if greater than zero

Parameters:: fncs_str (str) – FNCS message with load in kW

set_hvac_state(fncs_str)

Sets the hvac_on attribute

Parameters:: fncs_str (str) – FNCS message with state, ON or OFF

set_internalgain_forecast(internalgain_array): Set the 48-hour internalgain forecast :param internalgain_array: internalgain_forecast ([float x 48]): forecasted internalgain in BTu/h

set_price_forecast(price_forecast)

Set the 24-hour price forecast and calculate mean and std

Parameters:: price_forecast ([float x 24]) – predicted price in $/kwh

set_solar_diffuse(fncs_str)

Sets the solar diffuse attribute, if greater than zero

Parameters:: fncs_str (str) – FNCS message with solar irradiance

set_solar_direct(fncs_str)

Sets the solar irradiance attribute, if greater than zero

Parameters:: fncs_str (str) – FNCS message with solar irradiance

set_solargain_forecast(solargain_array)

Set the 48-hour solargain forecast

Parameters:: solargain_array – solargain_forecast ([float x 48]): forecasted solargain in BTu/(h*sf)

set_temperature(fncs_str)

Sets the outside temperature attribute

Parameters:: fncs_str (str) – FNCS message with outdoor temperature in F

set_temperature_forecast(fncs_str)

Set the 48-hour price forecast and calculate min and max

Parameters:: fncs_str – temperature_forecast ([float x 48]): predicted temperature in F

set_time(minute, hour, day)

Sets the current hour and minute

Parameters:

minute (int) – the minute of the hour from 0 to 59
hour (int) – the hour of the day, from 0 to 23
day (int) – the day of the week, zero being Monday

set_voltage(fncs_str)

Sets the mtr_v attribute

Parameters:: fncs_str (str) – FNCS message with meter line-neutral voltage

set_wh_load(fncs_str)

Sets the wh_load attribute, if greater than zero

Parameters:: fncs_str (str) – FNCS message with load in kW

set_zipload_forecast(forecast_ziploads)

Set the 48-hour zipload forecast :param forecast_ziploads: array of zipload forecast

Returns: nothing, sets the property

store_full_internalgain_forecast(forecast_internalgain)

Parameters:: forecast_internalgain – internal gain forecast to store for future

Returns: sets the variable so that it can be used later hours as well

store_full_zipload_forecast(forecast_ziploads)

Parameters:: forecast_ziploads – internal gain forecast to store for future

Returns: sets the variable so that it can be used later hours as well

temp_bound_rule(m, t)

test_function(): Test function with the only purpose of returning the name of the object

update_temp_limits_da(cooling_setpt, heating_setpt)

tesp_support.dsot.hvac_agent.test()

Testing

Makes a single hvac agent and run DA

tesp_support.dsot.load_less_solar module

Creates a new 200-bus load profile that is the original load profile less the distributed solar generation for that bus. For the hourly profile the solar data that is used is the hourly forecast data. For the five-minute profile the actual 5minute solar data is used. Users can select whether they need to generate hourly or five-minute datasets.

An 8-bus aggregated profile is also created (hourly or five-minute) automatically after the full 200-bus load dataset has been created.

class tesp_support.dsot.load_less_solar.Mode(value)

Bases: Enum

An enumeration.

FIVE_MINUTE = 1

HOUR = 0

tesp_support.dsot.load_less_solar.create_8_node_load_less_solar(dso_meta, load_dir, input_load_filename, output_load_filename)

Using information in the dso_meta dictionary, this function aggregates the 200-bus load-less-solar values into the 8-bus values. The resulting dataset is written out to file.

Parameters:

dso_meta – DSO metadata defining how 200-node buses map to 8-node buses
load_dir – Directory with input load data file
input_load_filename – Filename only, no path
output_load_filename – Filename only, no path

Returns:

(none)

tesp_support.dsot.load_less_solar.create_load_less_solar(input_load_filename, output_load_filename, solar_dir, load_dir, mode)

Hourly data is used for the DA market and needs to subtract the distributed generation solar forecast. 5-minute data is RT and needs to subtract the actual solar production.

Sample hourly load data:: Hour_End,Bus0,Bus1,Bus2,Bus3,Bus4,Bus5,Bus6,… 12/29/2015 0:00,3659.8,248.49,1652,4415.4,201.28,50.374,83.668,… 12/29/2015 1:00,3659.8,248.49,1652,4415.4,201.28,50.374,83.668,… 12/29/2015 2:00,3603.9,246.54,1626.8,4348,198.2,49.784,82.688,… 12/29/2015 3:00,3577.2,246.19,1614.8,4315.8,196.74,49.431,… 12/29/2015 4:00,3595.8,247.46,1623.1,4338.1,197.76,49.543,… 12/29/2015 5:00,3666,249.03,1654.8,4422.9,201.62,50.085,83.188,… 12/29/2015 6:00,3795.8,253.74,1713.4,4579.4,208.75,51.893,… 12/29/2015 7:00,3931.7,260.87,1774.8,4743.5,216.23,53.583,…
Sample hourly DSO distributed solar forecast data:: 0 0 0 0 0 0 0 0 1.079 2.518 3.499 6.463
Sample 5-minute load data:: Seconds,Bus1,Bus2,Bus3,Bus4,Bus5,Bus6,Bus7,Bus8, 0,3659.8,248.5,1652,4415.4,201.3,50.4,83.7,145.1 300,3659.8,248.5,1652,4415.4,201.3,50.4,83.7,145.1 600,3659.8,248.5,1652,4415.4,201.3,50.4,83.7,145.1 900,3659.8,248.5,1652,4415.4,201.3,50.4,83.7,145.1 1200,3659.8,248.5,1652,4415.4,201.3,50.4,83.7,145.1
Sample 5-minute solar data:: 12/29/15 0:00,0 12/29/15 0:05,0 12/29/15 0:10,0 12/29/15 0:15,0 12/29/15 0:20,0 12/29/15 0:25,0 12/29/15 0:30,0 12/29/15 0:35,0 12/29/15 0:40,0 12/29/15 0:45,0 12/29/15 0:50,0 12/29/15 0:55,0 12/29/15 1:00,0

Parameters:

load_filename – Filename of input load data
solar_dir – Directory of input solar data
load_dir – Directory of input load data

Returns:

list of list of load data less solar

Return type:

load_data

tesp_support.dsot.load_less_solar.data(self, message, *args, **kws)

tesp_support.dsot.load_less_solar.parse_DSO_metadata_Excel(dso_metadata_path_Excel, worksheet_name)

This function parses the DSO metadata which is contained in a JSON and Excel files. Most of the metadata is in the JSON but one crucial piece of information is in the Excel file: the mapping of the 200-node to 8-node buses.

Sample of the bus-generator file: (Note the first columns is empty)

200 bus 8 bus: 1 1 2 1 3 1 4 1 5 1 6 1 …

Parameters:

dso_metadata_path_Excel (str)
parsed. (containing the metadata to be)
worksheet_name (str)
metadata (containing the)

Returns:

dso_meta (list of dicts) - One dictionary per DSO with appropriate metadata captured.

tesp_support.dsot.load_less_solar.read_load_file(load_path)

Parameters:: load_path – Path to load file that is being read in
Returns:: list of lists with the headers and load data
Return type:: load_data

tesp_support.dsot.load_less_solar.write_out_load_file(load_data, out_path)

Writes out load data to CSV file. Assumes a list of lists format.

Parameters:

load_data – Load data to be written to CSV.
out_path – Path and filename of output file

Returns:

tesp_support.dsot.map_results module

tesp_support.dsot.plots module

tesp_support.dsot.plots.DSO_loadprofiles(dso_num, dso_range, day_range, case, dso_metadata_file, metadata_path, plot_weather=True)

For a specified dso range and case this function will analyze the ratios of Res, Comm, and Industrial.

Parameters:

dso_num (str) – number of the DSO folder to be opened
dso_range (range) – the DSO range that the data should be analyzed
day_range (list) – range of days to be summed (for example a month)
case (str) – folder extension of case of interest
dso_metadata_file (str) – folder extension and file name for DSO metadata

Returns:

dataframe with analysis values saves values to file

tesp_support.dsot.plots.RCI_analysis(dso_range, case, data_path, metadata_path, dso_metadata_file, energybill=False)

For a specified dso range and case this function will analyze the ratios of Res, Comm, and Industrial. :param dso_range: the DSO range that the data should be analyzed :type dso_range: list :param case: folder extension of case of interest :type case: str :param data_path: :type data_path: str :param metadata_path: :type metadata_path: str :param dso_metadata_file: DSO and Comm Building metadata :type dso_metadata_file: str :param energybill: :type energybill: bool

Returns:: dataframe with analysis values saves values to file

tesp_support.dsot.plots.TicTocGenerator()

tesp_support.dsot.plots.amenity_loss(gld_metadata, dir_path, folder_prefix, dso_num, day_range)

Determines the loss of amenity metrics (aka unmet hours) for HVAC and WH.

Parameters:

gld_metadata (dict) – gld metadata structure for the DSO to be analyzed
dir_path (str) – directory path for the case to be analyzed
folder_prefix (str) – prefix of GLD folder name (e.g. ‘/TE_base_s’)
dso_num (str) – number of the DSO folder to be opened
day_range (range) – range of days to be summed (for example a month).

Returns:

dataframe of loss of amenity metrics for HVAC and WH

Return type:

amenity_df

tesp_support.dsot.plots.annual_amenity(metadata, month_list, folder_prefix, dso_num)

Creates a dataframe of monthly energy consumption values and annual sum based on monthly h5 files. :param month_list: list of lists. Each sub list has month name (str), directory path (str) :type month_list: list :param folder_prefix: prefix of GLD folder name (e.g. ‘/TE_base_s’) :type folder_prefix: str :param dso_num: number of the DSO folder to be opened :type dso_num: str

Returns:: dataframe of energy consumption and max 15 minute power consumption for each month and total year_energysum_df: dataframe of energy consumption summations by customer class (res., commercial, and indust)
Return type:: year_meter_df

tesp_support.dsot.plots.bldg_load_stack(dso, day_range, case, agent_prefix, gld_prefix, metadata_path, daily_dso_plots=False)

For a specified dso, system, variable, and day this function will load in the required data, plot the daily profile and save the plot to file. :param dso: the DSO that the data should be plotted for (e.g. ‘1’) :type dso: int :param day_range: range of starting day and ending day of data to include :type day_range: range :param case: folder extension of case of interest :type case: str :param agent_prefix: folder extension for agent data :type agent_prefix: str :param gld_prefix: folder extension for GridLAB-D data :type gld_prefix: str :param metadata_path: path of folder containing metadata :type metadata_path: str :param daily_dso_plots: :type daily_dso_plots: bool

Returns:: saves daily profile plot to file

tesp_support.dsot.plots.bldg_stack_plot(dso_range, day_range, case, metadata_path)

For a specified dso, system, variable, and day this function will load in the required data, plot the daily profile and save the plot to file. :param dso_range: :type dso_range: list :param day_range: range of starting day and ending day of data to include :type day_range: range :param case: folder extension of case of interest :type case: str :param metadata_path: path of folder containing metadata :type metadata_path: str

Returns:: saves daily profile plot to file

tesp_support.dsot.plots.customer_comparative_analysis(case_data, comp_data, case_path, comp_path, dso_num, dso_metadata_path, month='sum', slice=None)

Creates a comparison of change in energy consumption and anemities for all customers :param case_data: path location for reference case with annual energy and amenity data :type case_data: str :param comp_data: path location for comparison case with annual energy and amenity data :type comp_data: str :param case_path: path location for reference case with simulation metadata for agents/GLD etc. :type case_path: str :param comp_path: path location for comparison case with simulation metadata for agents/GLD etc. :type comp_path: str :param dso_num: dso to be plotted :type dso_num: str :param dso_metadata_path: path to location of DSO metadata files :type dso_metadata_path: str :param month: month of annual analysis to be plotted. set to ‘sum’ to plot aggregate of all data. :type month: str :param slice: sub set of data to be plotted (e.g. ‘residential’, ‘office’, ‘HVAC’ :type slice: str

Returns:: saves plot to file.

tesp_support.dsot.plots.customer_meta_data(glm_meta, agent_meta, dso_metadata_path)

Update GLM dictionary with information from agent dictionary needed for customer billing.

Parameters:

glm_meta (dict) – dictionary of GridLAB-D information
agent_meta (dict) – dictionary of transactive agent information
dso_metadata_path (str) – location of metadata for commercial buildings

Returns:

dictionary of GridLAB-D information

Return type:

glm_meta (dict)

tesp_support.dsot.plots.daily_load_plots(dso, system, subsystem, variable, day, case, comp, agent_prefix, gld_prefix)

For a specified dso, system, variable, and day this function will load in the required data, plot the daily profile and save the plot to file. :param dso: the DSO that the data should be plotted for (e.g. ‘1’) :type dso: str :param system: the system to be plotted (e.g. ‘substation’, ‘house’, ‘HVAC_agent’) :type system: str :param subsystem: the individual house to be plotted (e.g. ‘HousesA_hse_1’) or the operator to be used if :type subsystem: str :param aggregating many houses: :type aggregating many houses: e.g. ‘sum’, ‘mean’ :param variable: variable to be plotted from system dataframe (e.g. ‘cooling_setpoint’ or ‘real_power_avg’) :type variable: str :param day: the day to plotted. :type day: str :param case: folder extension of case of interest :type case: str :param comp: folder extension of a comparison case of interest. Optional - set to None to show just one case. :type comp: str :param agent_prefix: folder extension for agent data :type agent_prefix: str :param gld_prefix: folder extension for GridLAB-D data :type gld_prefix: str

Returns:: saves daily profile plot to file

tesp_support.dsot.plots.daily_summary_plots(dso, system, subsystem, variable, day_range, case, comp, oper, diff, denom, agent_prefix, gld_prefix)

For a specified day range, system, variable, and dso this function will load in the required data and plot the variable for each day based on the operator and compare it to another case (optional). :param dso: the DSO that the data should be plotted for (e.g. ‘1’) :type dso: str :param system: the system to be plotted (e.g. ‘substation’, ‘house’, ‘HVAC_agent’) :type system: str :param subsystem: the individual house to be plotted (e.g. ‘HousesA_hse_1’) or the operator to be used if :type subsystem: str :param aggregating many houses: :type aggregating many houses: e.g. ‘sum, ‘mean’ :param variable: variable to be plotted from system dataframe (e.g. ‘cooling_setpoint’ or ‘real_power_avg’) :type variable: str :param day_range: range of the day indexes to be plotted. Day 1 has an index of 0 :type day_range: range :param case: folder extension of case of interest :type case: str :param comp: folder extension of comparison case of interest :type comp: str :param oper: operator for selecting a scalar value to represent the daily range (e.g. ‘min, ‘max’, ‘mean’) :type oper: str :param diff: If True will plot the difference between the baseline (case) and comparison (comp) :type diff: bool :param denom: denominator that values should be divided by before plotting :type denom: value :param agent_prefix: folder extension for agent data :type agent_prefix: str :param gld_prefix: folder extension for GridLAB-D data :type gld_prefix: str

Returns:: saves plots to file

tesp_support.dsot.plots.der_load_stack(dso, day_range, case, gld_prefix, metadata_path)

For a specified dso and day range this function will load in the required data, process the data for the stacked DER loads and save the data to file. :param dso: the DSO that the data should be plotted for (e.g. ‘1’) :type dso: int :param day_range: the day range to plotted. :type day_range: range :param case: folder extension of case of interest :type case: str :param gld_prefix: folder extension for GridLAB-D data :type gld_prefix: str :param metadata_path: path of folder containing metadata :type metadata_path: str

Returns:: saves dso DER loads data to file

tesp_support.dsot.plots.der_stack_plot(dso_range, day_range, metadata_path, case, comp=None, plot_ref=False)

For a specified dso range and day range this function will load in the required data, plot the stacked DER loads and save the plot to file. :param dso_range: the DSO range that should be plotted. :type dso_range: list :param day_range: the day range to plotted. :type day_range: range :param metadata_path: path of folder containing metadata :type metadata_path: str :param case: folder extension of case of interest :type case: str :param comp: folder extension for reference case to be plotted in comparison :type comp: str :param plot_ref: If True will plot line of reference data (currently 2016 ERCOT loads) :type plot_ref: Bool

Returns:: saves hdf and csv data files of combined dso data saves DER stack plot to file

tesp_support.dsot.plots.df_reduction(df, subsystem, variable, format)

This utility slices a dataframe based on the subsystem (or aggregation) of interest. This is used for agent or house data where there is multiple house data per timestep and reduction is needed before plotting data. :param df: dataframe to be reduced :type df: dataframe :param subsystem: the individual house to be plotted (e.g. ‘HousesA_hse_1’) or the operator to be used if :type subsystem: str :param aggregating many houses: :type aggregating many houses: e.g. ‘sum’, ‘mean’ :param variable: variable to be plotted from system dataframe (e.g. ‘cooling_setpoint’ or ‘real_power_avg’) :type variable: str :param format: flag as to whether the data is GridLAB-D (‘gld’) or agent (‘agent’) as the format is slightly different. :type format: str

Returns:: reduced dataframe
Return type:: df (dataframe)

tesp_support.dsot.plots.dso_comparison_plot(dso_range, system, subsystem, variable, day, case, agent_prefix, gld_prefix)

For a specified dso range, system, variable, and day this function will load in the required data, plot the variable for all DSOs and save the plot to file. :param dso_range: the DSO range that the data should be plotted for :type dso_range: range :param system: the system to be plotted (e.g. ‘substation’, ‘house’, ‘HVAC_agent’) :type system: str :param subsystem: the individual house to be plotted (e.g. ‘HousesA_hse_1’) or the operator to be used if :type subsystem: str :param aggregating many houses: :type aggregating many houses: e.g. ‘sum, ‘mean’ :param variable: variable to be plotted from system dataframe (e.g. ‘cooling_setpoint’ or ‘real_power_avg’) :type variable: str :param day: the day to plotted. :type day: str :param case: folder extension of case of interest :type case: str :param agent_prefix: folder extension for agent data :type agent_prefix: str :param gld_prefix: folder extension for GridLAB-D data :type gld_prefix: str

Returns:: saves dso comparison plot to file

tesp_support.dsot.plots.dso_forecast_stats(dso_range, day_range, case, dso_metadata_file, ercot_dir)

For a specified dso range and day range this function will load in the required data, plot forecast errors for all for DSOs and save the plots to file. :param dso_range: the DSO range that the data should be plotted for :type dso_range: list :param day_range: the day to plotted. :type day_range: range :param case: folder extension of case of interest :type case: str :param dso_metadata_file: path and file name of the dso metadata file :type dso_metadata_file: str :param ercot_dir: path location of the ercot and industial load metadata :type ercot_dir: str

Returns:: saves dso comparison plot to file

tesp_support.dsot.plots.dso_lmp_stats(month_list, output_path, renew_forecast_file, dso_range)

For a specified dso range and list of month path information this function will load in the required data, and summarize DSO LMPs versus loads for all months, and plot comparisons. :param month_list: list of lists. Each sub list has month name (str), directory path (str) :type month_list: list :param output_path: path of the location where output (plots, csv) should be saved :type output_path: str :param renew_forecast_file: path and name of ercot renewable generation forecast csv file :type renew_forecast_file: str

Returns:: saves dso load comparison plots to file saves csv of RT and DA loads and LMPs to file

tesp_support.dsot.plots.dso_load_stats(dso_range, month_list, data_path, metadata_path, plot=False)

For a specified dso range and list of month path information this function will load in the required data, and summarize DSO loads for all months, plot comparisons, and find Qmax. :param dso_range: the DSO range that the data should be plotted for :type dso_range: list :param month_list: list of lists. Each sub list has month name (str), directory path (str) :type month_list: list :param data_path: path of the location where output (plots, csv) should be saved :type data_path: str :param metadata_path: location of ercot load data :type metadata_path: str

Returns:: saves dso load comparison plots to file saves summary of Qmax for each DSO to file

tesp_support.dsot.plots.dso_market_plot(dso_range, day, case, dso_metadata_file, ercot_dir, comp_case=None)

For a specified dso range and day this function will load in the required data, plot standard market price and quantity values all for DSOs and save the plots to file. :param dso_range: the DSO range that the data should be plotted for :type dso_range: list :param day: the day to plotted. :type day: str :param case: folder extension of case of interest :type case: str :param dso_metadata_file: path and file name of the dso metadata file :type dso_metadata_file: str :param ercot_dir: path location of the ercot and industial load metadata :type ercot_dir: str

Returns:: saves dso comparison plot to file

tesp_support.dsot.plots.find_edge_cases(dso, base_case, day_range, agent_prefix, gld_prefix)

For a specified dso and case this function will return the day associated with a range of ‘edge cases’ for example the hottest day or biggest swing in prices. :param dso: the DSO that the data should be plotted for (e.g. ‘1’) :type dso: str :param base_case: folder extension of case of interest :type base_case: str :param day_range: range of days to be summed (for example a month) :type day_range: list :param agent_prefix: folder extension for agent data :type agent_prefix: str :param gld_prefix: folder extension for GridLAB-D data :type gld_prefix: str

Returns:: dataframe with values for each day dictionary of worst values. saves values to file

tesp_support.dsot.plots.generation_load_profiles(dir_path, metadata_path, data_path, day_range, use_ercot_fuel_mix_data=False, comp=None)

For a specified day range this function plots the stacked profiles of all generators (by fuel type) along with load plots. :param dir_path: path locating the AMES data file :type dir_path: str :param metadata_path: path locating the ERCOT load profile 5 minute data :type metadata_path: str :param data_path: path to the folder containing the plots sub folder :type data_path: str :param day_range: range of starting day and ending day of plot :type day_range: range :param use_ercot_fuel_mix_data: If True plots 2016 actual ERCOT data, if False plots AMES RT data. :type use_ercot_fuel_mix_data: bool :param comp: folder path containing the generation data for the comparison case. Set to None for no comparison :type comp: str

Returns:: saves plots to file

tesp_support.dsot.plots.generation_statistics(dir_path, config_dir, config_file, day_range, use_gen_data=True)

For a specified day range this function plots the stacked profiles of all generators (by fuel type) along with load plots. :param dir_path: path locating the AMES data file :type dir_path: str :param config_dir: path locating the case config file :type config_dir: str :param config_file: name of the case config file :type config_file: str :param day_range: range of starting day and ending day of plot :type day_range: range :param use_gen_data: if True uses dispatched generator performance from PyPower. If False uses dispatched :type use_gen_data: bool :param AMES performance:

Returns:: saves plots to file

tesp_support.dsot.plots.get_date(dir_path, dso, day): Utility to return start time (datetime format) of simulation day (str) in question

tesp_support.dsot.plots.get_day_df(dso, system, subsystem, variable, day, case, agent_prefix, gld_prefix)

This utility loads and returns a dataframe for the desired variable for the day and dso in question. :param dso: the DSO that the data should be plotted for (e.g. ‘1’) :type dso: str :param system: the system to be plotted (e.g. ‘substation’, ‘house’, ‘HVAC_agent’) :type system: str :param subsystem: the individual house to be plotted (e.g. ‘HousesA_hse_1’) or the operator to be used if :type subsystem: str :param aggregating many houses: :type aggregating many houses: e.g. ‘sum, ‘mean’ :param variable: variable to be plotted from system dataframe (e.g. ‘cooling_setpoint’ or ‘real_power_avg’) :type variable: str :param day: the day to plotted. :type day: str :param case: folder extension of case of interest :type case: str :param agent_prefix: folder extension for agent data :type agent_prefix: str :param gld_prefix: folder extension for GridLAB-D data :type gld_prefix: str

Returns:: reduced dataframe
Return type:: df (dataframe)

tesp_support.dsot.plots.get_house_schedules(agent_metadata, gld_metadata, house_name)

Utility to get schedules directly from the agent dictionary. This allows evaluation of schedules prior to agent control. :param agent_metadata: dictionary of agent metadata :type agent_metadata: dict :param gld_metadata: dictionary of gld metadata :type gld_metadata: dict :param house_name: name of GLD house object schedules are wanted for :type house_name: str

Returns:: dictionary of schedules in list form
Return type:: schedules (dict)

tesp_support.dsot.plots.heatmap_plots(dso, system, subsystem, variable, day_range, case, agent_prefix, gld_prefix)

For a specified day, system, variable, and day_range this function will load in the required data, manipulate the dataframe into the required shape, plot the heatmap and save the heatmap to file. :param dso: the DSO that the data should be plotted for (e.g. ‘1’) :type dso: str :param system: the system to be plotted (e.g. ‘substation’, ‘house’, ‘HVAC_agent’) :type system: str :param subsystem: the individual house to be plotted (e.g. ‘HousesA_hse_1’) or the operator to be used if :type subsystem: str :param aggregating many houses: :type aggregating many houses: e.g. ‘sum, ‘mean’ :param variable: variable to be plotted from system dataframe (e.g. ‘cooling_setpoint’ or ‘real_power_avg’) :type variable: str :param day_range: range of the day indexes to be plotted. Day 1 has an index of 0 :type day_range: range :param case: folder extension of case of interest :type case: str :param agent_prefix: folder extension for agent data :type agent_prefix: str :param gld_prefix: folder extension for GridLAB-D data :type gld_prefix: str

Returns:: saves heatmap to file

tesp_support.dsot.plots.house_check(dso_range, sourceCase, targetCase, houseProperties)

Main function of the module.

Parameters:: argv – Command line arguments given as: -d <Substation/DSO number to be analyzed> -s <source case folder name> -t <target case folder name> -p <property to compare by plots>
Return type:: None

tesp_support.dsot.plots.limit_check(log_list, dso_num, system, variable, day_range, base_case, agent_prefix, GLD_prefix, max_lim, min_lim)

For a specified dso, system, variable, and day_range this function will the time and place of the value that most exceeds upper and lower limits. A text description will be added to a log list and returned. :param log_list: list of limit excursions that will be added to. :type log_list: list :param dso_num: the DSO that the data should be plotted for (e.g. ‘1’) :type dso_num: str :param system: the system to be checked (e.g. ‘substation’, ‘house’, ‘HVAC_agent’) :type system: str :param variable: variable to be checked from system dataframe (e.g. ‘cooling_setpoint’ or ‘real_power_avg’) :type variable: str :param day_range: range of the day indexes to be checked. Day 1 has an index of 0 :type day_range: range :param base_case: folder extension of case of interest :type base_case: str :param agent_prefix: folder extension for agent data :type agent_prefix: str :param GLD_prefix: folder extension for GridLAB-D data :type GLD_prefix: str :param max_lim: upper value that variable should not exceed during simulation :type max_lim: float :param min_lim: lower value that variable should not exceed during simulation :type min_lim: float

Returns:: saves heatmap to file

tesp_support.dsot.plots.load_agent_data(dir_path, folder_prefix, dso_num, day_num, agent_name)

Utility to open h5 files for agent data.

Parameters:

dir_path (str) – path of parent directory where DSO folders live
folder_prefix (str) – prefix of DSO folder name (e.g. ‘/TE_base_s’)
dso_num (str) – number of the DSO folder to be opened
day_num (str) – simulation day number (1 = first day of simulation)
agent_name (str) – name of agent data to load (e.g. ‘house’, ‘substation’, ‘inverter’, ‘retail site’ etc)

Returns:

dataframe of system metadata agent_df: dataframe of agent timeseries data

Return type:

agent_meta_df

tesp_support.dsot.plots.load_ames_data(dir_path, day_range)

Utility to open AMES csv file.

Parameters:

dir_path (str) – path of directory where AMES data lives
day_range (range) – range of simulation days for data to be returned

Returns:

dataframe of AMES data

Return type:

data_df

tesp_support.dsot.plots.load_da_retail_price(dir_path, folder_prefix, dso_num, day_num, retail=True)

Utility to return day ahead cleared retail price. Data corresponds to 10am bid day before mapped to actual datetime when the energy will be consumed. :param dir_path: path of parent directory where DSO folders live :type dir_path: str :param folder_prefix: prefix of DSO folder name (e.g. ‘/TE_base_s’) :type folder_prefix: str :param dso_num: number of the DSO folder to be opened :type dso_num: str :param day_num: simulation day number (1 = first day of simulation) :type day_num: str

Returns:: dataframe of cleared DA retail price
Return type:: retail_da_data_df

tesp_support.dsot.plots.load_duration_plot(dso, system, subsystem, variable, day, case, comp, agent_prefix, gld_prefix)

For a specified dso, system, variable, and day this function will load in the required data, plot the load duration profile and save the plot to file. NOTE: currently for one day = should extend to a day-range. :param dso: the DSO that the data should be plotted for (e.g. ‘1’) :type dso: str :param system: the system to be plotted (e.g. ‘substation’, ‘house’, ‘HVAC_agent’) :type system: str :param subsystem: the individual house to be plotted (e.g. ‘HousesA_hse_1’) or the operator to be used if :type subsystem: str :param aggregating many houses: :type aggregating many houses: e.g. ‘sum, ‘mean’ :param variable: variable to be plotted from system dataframe (e.g. ‘cooling_setpoint’ or ‘real_power_avg’) :type variable: str :param day: the day to plotted. :type day: str :param case: folder extension of case of interest :type case: str :param comp: folder extension of a comparison case of interest. Optional - set to None to show just one case. :type comp: str :param agent_prefix: folder extension for agent data :type agent_prefix: str :param gld_prefix: folder extension for GridLAB-D data :type gld_prefix: str

Returns:: saves load duration plot to file

tesp_support.dsot.plots.load_ercot_data(metadata_file, sim_start, day_range)

Utility to open ercot csv file.

Parameters:

metadata_file (str) – path of where the metadata_file lives
sim_start (datetime) – start time of the simulation (from generate_case_config.json)
day_range (range) – range of simulation days for data to be returned

Returns:

dataframe of ERCOT 2016 fuel mix data

Return type:

data_df

tesp_support.dsot.plots.load_ercot_fuel_mix(metadata_path, dir_path, day_range)

Utility to open AMES csv file.

Parameters:

metadata_path (str) – path of directory where ERCOT Fuel mix data lives
dir_path (str) – path of directory where AMES data lives
day_range (range) – range of simulation days for data to be returned

Returns:

dataframe of AMES data

Return type:

data_df

tesp_support.dsot.plots.load_gen_data(dir_path, gen_name, day_range)

Utility to open h5 files for generator data.

Parameters:

dir_path (str) – path of parent directory where DSO folders live
gen_name (str) – name of generator (e.g. ‘’)
day_range (range) – range of days to be summed (for example a month)

Returns:

dataframe of system metadata

Return type:

gen_data_df (dataframe)

tesp_support.dsot.plots.load_indust_data(indust_file, day_range)

Utility to open industrial load csv file.

Parameters:

indust_file (str) – path and filename where the industrial csv load lives
day_range (list) – range of simulation days for data to be returned

Returns:

dataframe of industrial loads per DSO bus

Return type:

data_df

tesp_support.dsot.plots.load_json(dir_path, file_name): Utility to open Json files.

tesp_support.dsot.plots.load_retail_data(dir_path, folder_prefix, dso_num, day_num, agent_name)

Utility to open h5 files for agent data. :param dir_path: path of parent directory where DSO folders live :type dir_path: str :param folder_prefix: prefix of DSO folder name (e.g. ‘/TE_base_s’) :type folder_prefix: str :param dso_num: number of the DSO folder to be opened :type dso_num: str :param day_num: simulation day number (1 = first day of simulation) :type day_num: str :param agent_name: name of agent data to load (e.g. ‘house’, ‘substation’, ‘inverter’ etc) :type agent_name: str

Returns:: dataframe of system metadata agent_df: dataframe of agent timeseries data
Return type:: agent_meta_df

tesp_support.dsot.plots.load_system_data(dir_path, folder_prefix, dso_num, day_num, system_name)

Utility to open GLD created h5 files for systems’ data. :param dir_path: path of parent directory where DSO folders live :type dir_path: str :param folder_prefix: prefix of DSO folder name (e.g. ‘/TE_base_s’) :type folder_prefix: str :param dso_num: number of the DSO folder to be opened :type dso_num: str :param day_num: simulation day number (1 = first day of simulation) :type day_num: str :param system_name: name of system data to load (e.g. ‘house’, ‘substation’, ‘inverter’ etc) :type system_name: str

Returns:: dataframe of system metadata system_df: dataframe of system timeseries data
Return type:: system_meta_df

tesp_support.dsot.plots.load_weather_data(dir_path, folder_prefix, dso_num, day_num)

Utility to open weather dat files and find day of data

Parameters:

dir_path (str) – path of parent directory where DSO folders live
folder_prefix (str) – prefix of DSO folder name (e.g. /DSO_)
dso_num (str) – number of the DSO folder to be opened
day_num (str) – simulation day number (1 = first day of simulation)

Returns:

dataframe of weather data for simulation day requested

Return type:

weather_df

tesp_support.dsot.plots.metadata_dist_plots(system, sys_class, variable, dso_range, case, data_path, metadata_path, agent_prefix)

For system, class, and dso_range this function will load in the required data, and plot a histogram of the population distribution. :param system: the system to be plotted (e.g. ‘house’) :type system: str :param sys_class: the subclass to be plotted (e.g. ‘SINGLE_FAMILY’). If system has no subsystems or you want to :type sys_class: str :param see the full population set equal to None: :param variable: variable to be plotted from system dataframe (e.g. ‘sqft’) :type variable: str :param dso_range: range of the DSOs to be plotted. DSO 1 has an index of 0 :type dso_range: list :param case: folder extension of case of interest :type case: str :param data_path: :type data_path: str :param metadata_path: :type metadata_path: str :param agent_prefix: folder extension for agent data :type agent_prefix: str

Returns:: saves plot of population distribution to file

tesp_support.dsot.plots.non_participating_dso_loads(dso_range, case, metadata_path)

For a specified dso range case, and metadata path information this function will load in the required data (ERCOT load profiles for non-participating DSOS). :param case: path where the annual case lives :type case: str :param dso_range: List of DSOs that are being modeled in the system :type dso_range: list

Returns:: saves dso load comparison plots to file

tesp_support.dsot.plots.plot_lmp_stats(data_path, output_path, dso_num, month_index=8)

Will plot LMPS by month, duration, and versus netloads loads (for select month), and save to file. :param data_path: location of the data files to be used. :type data_path: str :param output_path: path of the location where output (plots, csv) should be saved :type output_path: str :param dso_num: bus number for LMP data to be plotted :type dso_num: str

Returns:: saves dso lmps plots to file

tesp_support.dsot.plots.run_plots()

tesp_support.dsot.plots.tic()

tesp_support.dsot.plots.toc(tempBool=True)

tesp_support.dsot.plots.transmission_statistics(metadata_file_path, case_config_path, data_path, day_range, sim_results=False)

For a specified day range this function determines key transmission statistics (e.g. line lenght, max normalized line usage etc).

Parameters:

metadata_file_path (str) – path and file name of the 8/200-bus metadata json file
case_config_path (str) – path and file name locating the system case config json file
data_path (str) – path to the folder containing the simulation results
day_range (range) – range of starting day and ending day of data to include
sim_results (bool) – if True loads in simuation results. If false skips simulation results.

Returns:

saves csv statistics to files

tesp_support.dsot.plots.wind_diff(x)

tesp_support.dsot.pv_agent module

Class that controls the Photovoltaic Solar agents for now, it only provides day ahead forecast for each agent. It does not participate in bidding

class tesp_support.dsot.pv_agent.PVDSOT(pv_dict, inv_properties, key, model_diag_level, sim_time)

Bases: object

This agent manages the PV solar

Parameters:

pv_dict (diction) – dictionary to populate attributes
inv_properties (diction)
key (str) – name of this agent
model_diag_level (int) – Specific level for logging errors; set it to 11
sim_time (str) – Current time in the simulation; should be human-readable

Initialize from Args

name

name of this agent

Type:: str

participating

participating from pv_dict dictionary

Type:: bool

rating

rating from pv_dict dictionary

Type:: float

scaling_factor

scaling_factor from pv_dict dictionary

Type:: float

slider

slider_setting from pv_dict dictionary

Type:: float

windowLength

48 always for now

Type:: int

TIME

range(0, self.windowLength)

Type:: list

scale_pv_forecast(solar_f)

tesp_support.dsot.residential_feeder_glm module

tesp_support.dsot.retail_market module

Class that manages the operation of retail market at substation-level

Functionalities include: collecting curve bids from DER and DSO agents; generating aggregated buyer and seller curves; market clearing for both RT and DA retail markets; deciding cleared quantity for individual DERs.

The function call order for this agent is:

initialize(retail_dict)

Repeats at every hour:
clean_bids_DA() curve_aggregator_DA(identity, bid, id) … curve_aggregator_DA(identity, bid, id) clear_market_DA(transformer_degradation, Q_max)

Repeats at every 5 min:
clean_bids_RT() curve_aggregator_RT(identity, bid, id) … curve_aggregator_RT(identity, bid, id) clear_market_RT(transformer_degradation, Q_max)

class tesp_support.dsot.retail_market.RetailMarket(retail_dict, key)

Bases: object

This agent manages the retail market operating

Parameters:

retail_dict
key

name

name of the retail market agent

Type:: str

price_cap

the maximum price that is allowed in the market, in $/kWh

Type:: float

num_samples

the number of sampling points, describes how precisely the curve is sampled

Type:: int

windowLength

length of the planning horizon for the DA market, in hours

Type:: int

Q_max

capacity of the substation, in kWh

Type:: float

maxPuLoading

rate of the maxPuLoading for transformer

Type:: float

curve_buyer_RT

aggregated buyer curve, updated after receiving each RT buyer bid

Type:: Curve

curve_seller_RT

aggregated seller curve, updated after receiving each RT seller bid

Type:: Curve

curve_buyer_DA

48 aggregated buyer curves, updated after receiving each DA buyer bid

Type:: dict of curves

curve_seller_DA

48 aggregated seller curves, updated after receiving each DA seller bid

Type:: dict of curves

clear_type_RT

0=uncongested, 1=congested, 2=inefficient, 3=failure

Type:: int

clear_type_DA

list of clear type at each hour

Type:: list

cleared_price_RT

cleared price for the substation for the next 5-min

Type:: float

cleared_price_DA

list of cleared price at each hour

Type:: list

cleared_quantity_RT

cleared quantity for the substation for the next 5-min

Type:: float

cleared_quantity_DA

list of cleared quantity at each hour

Type:: list

site unresponsive DA

Site Day Ahead quantity which is unresponsive

Type:: list

AMES_RT

Smooth Quadratics

Type:: list X 5

AMES_DA

X windowLength): Smooth Quadratics

Type:: (list X 5

basecase

If true no agent market, false agent market

Type:: bool

load_flexibility

If true load is bid in to the market, false all load is unresponsive

Type:: bool

U_price_cap_CA

Upper price range for curve aggregator (CA)

Type:: float

L_price_cap_CA

Lower price range for curve aggregator (CA)

Type:: float

TOC_dict

parameters related to transformer lifetime cost calculation, including OperatingPeriod (int): operating period, in minute timeStep (int): timestep, in minute Tamb (float): ambient temperature, in deg C delta_T_TO_init (int): initial delta temperature of top oil, in deg C delta_T_W_init (int): initial delta temperature of winding, in deg C BP (float): initial cost of transformer, in $ toc_A (float): cost per watt for no-load losses, in $/W toc_B (float): cost per watt for load losses, in $/W Base_Year (float): expected lifespan of transformer, in year P_Rated (float): capacity, in W NLL_rate (float): no load loss rate, in % LL_rate (float): load loss rate, in % Sec_V (float): secondary voltage level, in volt TOU_TOR (float): oil time constant, in minute TOU_GR (float): winding time constant, in minute Oil_n (float): Oil exponent n Wind_m (float): Winding exponent m delta_T_TOR (float): top oil temperature rise, in deg C delta_T_ave_wind_R (float): average winding temperature rise over ambient temperature, in deg C

Type:: dict

clean_bids_DA(): Initialize the day-ahead market

clean_bids_RT(): Initialize the real-time market

clear_market(curve_buyer, curve_seller, transformer_degradation, Q_max)

Shared function called by both clear_market_RT and clear_market_DA functions to find the intersection between supply curve and demand curve

Parameters:

curve_buyer (Curve) – aggregated buyer curve
curve_seller (Curve) – aggregated seller curve
transformer_degradation (bool) – equals to 1 if transformer_degradation is considered in the supply curve
Q_max (float) – substation capacity, in kWh

Outputs:: clear_type (int) cleared_price (float) cleared_quantity (float) congestion_surcharge (float)

clear_market_DA(transformer_degradation, Q_max)

Function used for clearing the DA market

Three steps of work are fullfilled in a loop in this function: First the buyer curve at each hour is fitted polynomial; Second clear_market function is called for calculating the cleared price and cleared quantity for the whole market at each hour; Third distribute_cleared_quantity function is called for finding the cleared price and cleared quantity for the individual DERs at each hour.

buyer_info_DA and seller_info_DA, clear_type_DA, cleared_price_DA and cleared_quantity_DA are updated with cleared results

clear_market_RT(transformer_degradation, Q_max)

Function used for clearing the RT market

Three steps of work are fullfilled in this function: First the buyer curve is fitted polynomial; Second clear_market function is called for calculating the cleared price and cleared quantity for the whole market; Third distribute_cleared_quantity function is called for finding the cleared price and cleared quantity for the individual DERs.

buyer_info_RT and seller_info_RT, clear_type_RT, cleared_price_RT and cleared_quantity_RT are updated with cleared results

convert_2_AMES_quadratic_BID(curve, Q_cleared, price_forecast, c_type)

Convert aggregated DSO type bid to AMES quadratic curve

Parameters:

curve (Curve) – substation demand curve to be preprocessed
price_forecast – locally forecast price at the substation level
Q_cleared – locally cleared quantity at the substation
c_type (str) – ‘DA’ for day-ahead and ‘RT’ for real-time

Returns:

f(Q)=resp_c2*Q^2+C1*Q+C0: unresp_mw (float): minimum demand MW resp_max_mw (float): maximum demand MW resp_c2 (float): quadratic coefficient resp_c1 (float): linear coefficient resp_c0 (float): constant coefficient resp_deg (int): equal to “2” to represent the current order in the list

Return type:

quadratic_bid (list)

curve_aggregator_AMES_DA(demand_curve_DA, Q_max, Q_cleared, price_forecast)

Function used to aggregate the substation-level DA demand curves into a DSO-level DA demand curve

Parameters:

demand_curve_DA (dict) – a collection of demand curves to be aggregated for day-ahead
Q_max (float) – maximum capacity of the substation, in kW
Q_cleared (float) – locally cleared quantity of the substation in kW
price_forecast (float) – locally forecast price at the substation level

curve_aggregator_AMES_RT(demand_curve_RT, Q_max, Q_cleared, price_forecast)

Function used to aggregate the substation-level RT demand curves into a DSO-level RT demand curve

Parameters:

demand_curve_RT (Curve) – demand curve to be aggregated for real-time
Q_max (float) – maximum capacity of the substation, in kW
Q_cleared (float) – locally cleared quantity of the substation in kW
price_forecast (float) – locally forecast price at the substation level

curve_aggregator_DA(identity, bid_DA, name)

Function used to collect the DA bid and update the accumulated buyer or seller curve

Parameters:

identity (str) – identifies whether the bid is collected from a “Buyer” or “Seller”
bid_DA (list) – a nested list with dimension (self.windowLength, m, 2), with m equals 2 to 4
name (str) – name of the buyer or seller

curve_aggregator_RT(identity, bid_RT, name)

Function used to collect the RT bid and update the accumulated buyer or seller curve

Parameters:

identity (str) – identifies whether the bid is collected from a “Buyer” or “Seller”
bid_RT (list) – a nested list with dimension (m, 2), with m equals 2 to 4
name (str) – name of the buyer or seller

curve_preprocess(substation_demand_curve, Q_max)

An internal shared function called by curve_aggregator_DSO_RT and curve_aggregator_DSO_DA functions to truncate: the substation demand curve before aggregation as well as convert the retail prices into wholesale prices

Parameters:

substation_demand_curve (Curve) – substation demand curve to be preprocessed
Q_max (float) – maximum capacity of the substation, in kW

Returns:

preprocessed demand curve

Return type:

preprocessed_curve (curve)

process_site_da_quantities(forecast_load, name, status)

Function stores the day-ahead quantities, primarily for HVAC at the moment, it utilizes

arguments in: unresponsive loads (1x 48) dataframe responsive loads (1x48) dataframe name: of the house (str) returns self.site_quantity_DA (dict, ‘name’, ‘ status (participating or not participating’, ‘Quantity (1 x 48) )

retail_rate_inverse(Pr)

Function used to convert the retail prices into wholesale prices

Parameters:: Pr (float) – retail price, in $/kWh
Returns:: wholesale price, in $/kWh
Return type:: Pw (float)

test_function(): Test function with the only purpose of returning the name of the object

update_price_CA(price_forecast): Updates the price_CA

tesp_support.dsot.retail_market.test(): Testing AMES

tesp_support.dsot.sankey module

tesp_support.dsot.sankey.label_nodes(data, total_value): Adds max quantity of node value to node label

tesp_support.dsot.sankey.load_CFS_data(results_path, dso_range, update_data, scale, labelvals, calibrate)

Initiates and updates Sankey diagram data structure for Cash Flow Sheet data. :param results_path: directory path for the case to be analyzed. Should be run after annual post-processing :type results_path: str :param dso_range: range of DSOs to be included in data analysis :type dso_range: range :param update_data: If True pulls in analysis data. If False plots Sankey with default data to show structure :type update_data: bool :param scale: If True scales data to $B from standard $K CFS units :type scale: bool :param labelvals: If True adds quantitative values to node labels :type labelvals: bool :param calibrate: If True it squares up values that are typically slightly off in the analysis :type calibrate: bool

Returns:: Sankey data structure for Plotly Sankey diagram plotting
Return type:: data (dict)

tesp_support.dsot.sankey.load_CFS_delta_data(results_path, comp_path, dso_range, update_data, scale, labelvals, metadata_file, calibrate)

Initiates and updates Sankey diagram data structure for Cash Flow Sheet data. :param results_path: directory path for the case to be analyzed. Should be run after annual post-processing :type results_path: str :param comp_path: directory path for the baseline (business-as-usual) case. :type comp_path: str :param dso_range: range of DSOs to be included in data analysis :type dso_range: range :param update_data: If True pulls in analysis data. If False plots Sankey with default data to show structure :type update_data: bool :param scale: If True scales data to $B from standard $K CFS units :type scale: bool :param labelvals: If True adds quantitative values to node labels :type labelvals: bool :param calibrate: If True it squares up values that are typically slightly off in the analysis :type calibrate: bool

Returns:: Sankey data structure for Plotly Sankey diagram plotting
Return type:: data (dict)

tesp_support.dsot.sankey.load_energy_data(results_path, dso_range, update_data, scale, labelvals, calibrate=True)

Initiates and updates Sankey diagram data structure for simulation energy data. :param results_path: directory path for the case to be analyzed. Should be run after annual post-processing :type results_path: str :param dso_range: range of DSOs to be included in data analysis :type dso_range: range :param update_data: If True pulls in analysis data. If False plots Sankey with default data to show structure :type update_data: bool :param scale: If True scales data to GW from standard MW CFS units :type scale: bool :param labelvals: If True adds quantitative values to node labels :type labelvals: bool :param calibrate: If True it squares up values that are typically slightly off in the analysis :type calibrate: bool

Returns:: Sankey data structure for Plotly Sankey diagram plotting
Return type:: data (dict)

tesp_support.dsot.sankey.rec_diff(d1, d2)

tesp_support.dsot.sankey.sankey_plot()

tesp_support.dsot.solar module

This script provides a few essential functions:

Download hourly annual solar data for a specified list of locations from the National Solar Radiation Database (NSRDB).
Simulate the power production for a standard size solar array for each of the solar profiles downloaded using NREL’s PySAM (Python wrapper for their SAM tool).
Aggregate the individual solar profiles to form standardized distributed solar power profiles and centralized utility-scale profiles for the DSO+T 200-node model and 8-node model.

The script includes various housekeeping functions such as file management, automatic generation of distributed solar sites around the primary DSO location, and formatting of the necessary files for ingest by their target simulators.

This script is structured like virtually all of my scripts are structured: running this script with no arguments will perform a comprehensive standard analysis using reasonable default inputs. All necessary inputs and requested outputs will be produced in the “auto-run” folder as a sort of combination example and test case.

Its worth noting that as of this writing, the NSRDB is VERY slow to respond by the provided API and the daily limit of files requests is relatively modest. To gather all the data to run ten distributed solar sites per DSO (200-node) required literally a day.

Also note that use of this API requires registration and use of an NREL- provided API key. This file has my API key removed so that I don’t inadvertently share its use with all of PNNL. Get your own key.

DSO+T is simulating 2016 which includes a Leap Day. The NSRDB data does not include data for this day (which is odd, given that the data is based on satellite photos; the source data should exist). I’m replicating data from Feb 28th as the data for Feb. 29th, but I’m only doing this when creating the output files. All the original NRSDB and SAM power profiles only contains 365 days of data.

tesp_support.dsot.solar.add_locations(dso_meta, solar_meta, nsrdb_path)

This function adds a number of random locations (specified in solar_meta) withing a certain distance (specified in solar_meta) of a DSO to replicate the effects of the distributed solar generation. Also randomizes the tilt and azimuth orientation of the panels for each distributed location.

The primary location for the DSO is the lat/long from the DSO metadata file and is also added to the solar site list. This is the location that will be used for any utility-scale solar generation.

Parameters:

dso_meta (list) – List of dicts with metadata associated with each DSO
solar_meta (dict) – Metadata related to the solar parameters
nsrdb_path (str) – Path to the directory with the NSRDB data

Returns:

One dictionary per DSO with appropriate metadata captured. Each dictionary has an added item, “distributed locations” which is a dict of parameters for the distributed solar generation

Return type:

dso_meta (list of dicts)

tesp_support.dsot.solar.aggregate_scale_solar_pv_profiles(dso_meta, solar_meta, output_path)

This function calculates the utility-scale and distributed solar PV power profiles. The utility scale profile is from a single location (the primary DSO location) while the distributed profile is an equally-weighted average of all profiles for the DSO.

Both the utility-scale and distributed power profiles are scaled to meet both the total solar capacity contribution of the DSO and their relative ratios between utility-scale and dsitributed.

Parameters:

dso_meta (list) – List of dicts with metadata associated with each DSO, pecifically with the load fraction needed to scale the solar PV power profiles as well as the profiles themselves
solar_meta (dict) – User-specified solar metadata
output_path (str) – Path to the solar PV power profiles for all DSOs.

Returns:

List of dicts with metadata associated with each DSO, updated to include the scaled and aggregated utility-scale and dsitributed solar profiles.

Return type:

dso_meta (list)

tesp_support.dsot.solar.aggregate_to_8_nodes(dso_meta, output_path)

This function aggregates the individual profiles for each of the 200 nodes into a single profile for each of the reduced 8 nodes in the smaller model. This is done for both the utility and the distributed solar profiles.

The 8-node DSOs are added to the dso_meta object to the end of the list. They don’t have all the same metadata as the original 200-node DSOs.

Parameters:

dso_meta (list) – List of dicts with metadata associated with each DSO, specifically 200-node DSO solar profiles
output_path (str) – Location to write out aggregated solar
data. (profile)

Returns:

List of dicts with metadata associated with each DSO, updated to include aggregated solar profile data and output file location.

Return type:

dso_meta (list)

tesp_support.dsot.solar.build_dso_solar_folders(dso_meta, output_path)

Creates folders for the solar data in the output path. Folders are only created if they don’t already exist.

Parameters:

dso_meta – metadata dictionary containing the DSO name
output_path – string specifying output path of data

tesp_support.dsot.solar.calc_dso_solar_fraction(dso_meta)

This function calculates the total target PV fraction in proportion with the total average load of the system. That is, it answers the question, “What fraction of the total installed PV should be allocated to each DSO?” (The total size of the installed PV for all of ERCOT is pre-defined by another analysis.)

Parameters:: dso_meta (list) – List of dicts with metadata associated with each DSO, specifically the average annual load of each DSO
Returns:: List of dicts with metadata associated with each DSO, updated to include load fractions for each DSO.
Return type:: dso_meta (list)

tesp_support.dsot.solar.calc_solarPV_power(dso_meta, output_path)

This function uses PySAM from NREL (https://sam.nrel.gov/software-development-kit-sdk/pysam.html) to calculate the solar PV power generation for a solar array at the indicated site. Metadata associated with each site determines the tilt and azimuth. All other array modeling parameters (largely losses) are constant across all sites. The array size is also fixed at a 1 MW.

Parameters:

dso_meta (list) – List of dicts with metadata associated with each DSO, specifically the solar PV information per site
output_path (str) – Location to write out solar PV power data

Returns:

List of dicts with metadata associated with each DSO, updated to include power profiles for each site in the DSO.

Return type:

dso_meta (list)

tesp_support.dsot.solar.create_GLD_files(dso_meta)

This function creates 5-minute power profiles from hourly profiles through the power of linear interpolation technology (TM). These profiles are formatted as GridLAB-D tape players.

Example: 2008-12-25 00:00:00,622368.3864 2008-12-25 00:05:00,738071.2498 2008-12-25 00:10:00,680611.3676 2008-12-25 00:15:00,696280.9035

It only acts on the distributed power profiles since these are the ones that are needed by the distribution system simulator to be used to implement distributed (rooftop) generation in the DSO.

Parameters:: dso_meta (list) – List of dicts with metadata associated with each DSO including the current distributed power profiles.
Returns:: List of dicts with DSO data including the location of the interpolated values. Decided not to save these inside the dictionary themselves due to their size and the fact that I don’t anticipate needing to reuse them.
Return type:: dso-Meta (list)

tesp_support.dsot.solar.create_dsot_utility_solar_file(dso_meta, output_path)

This function creates a time-series “tape” file for ingest by the DSO+T co-simulation for each of the 200 utility-scale solar PV generation sites. The format is specific to this study (though not opaque in the least); a sample is shown below taken from the wind profile:

time,wind26,wind28,wind29,… 2015-12-29 00:00:00,238.100,646.600,365.400,… 2015-12-29 01:00:00,231.497,646.600,365.400,… …

The data needed for these profiles starts prior to Jan 1 to allow the models to warm up. The data prior to Jan 1 is not crucial, and I’ll just the Jan 1 data for those early days as a good-enough approximation.

Also creates an interpolated 5-min version of the file for the RT market.

Parameters:

dso_meta (list) – List of dicts with metadata associated with each DSO including the utility-scale solar PV power profiles.
output_path (str) – Path to directory where file will be written

tesp_support.dsot.solar.create_graphs(dso_meta, type)

This function graphs four weeks out of the year for each DSO to enable easy comparison between the effects of the distributed and utility (single-point) solar power profiles.

Graph image files are saved alongside solar profile files.

Parameters:

dso_meta (list) – List of dicts with metadata associated with each DSO, specifically the distributed and utility scale solar power profiles.
type (str) – Keyword indicating the type of graph to create

tesp_support.dsot.solar.create_hourly_solar_forecast(dso_meta, dso_type, rng_seed)

This function creates an hourly forecast for the utility profile by adding noise from a random distribution to it. The parameters for said distribution come from literature (https://www.nrel.gov/docs/fy15osti/63876.pdf).

In a clumsy way that I’m not proud of now that I’m documenting the function, the user decides whether to add noise to the 8-node DSOs or the 200-node DSOs by defining a value for the “dso_type” parameter.

Parameters:

dso_meta (list) – List of dicts with metadata associated with each DSO including the current utility dso power profiles.
dso_type (int) – Used to indicate whether to create forecast files for the 8-node or 200-node utility power profiles. Valid values are “8” or “200”.

Returns:

List of dicts with DSO data including the synthesized forecast profiles.

Return type:

dso-Meta (list)

tesp_support.dsot.solar.download_nsrdb_data(dso_meta, solar_meta, output_path)

This function queries the NSRDB database over the web and pulls down the solar data down and stores it in a Pandas dataframe.

Parameters:

dso_meta (list) – List of dicts with metadata associated with each DSO, specifically the site information
solar_meta (list) – List of metadata related to the solar parameters
output_path (str) – Location to write out solar data from the NSRDB so that we don’t have to re-query the database for data we already have.

Returns:

List of dicts with metadata associated with each DSO, updated to include NSRDB-specific information such as the abreviated lats and longs from the downloaded solar data as well as a path to each downloaded file and a boolean indicating a file has been downloaded for the given site.

Return type:

dso_meta (list)

tesp_support.dsot.solar.forecast_cleanup(dso_meta, idx, error, profile, forecast_profile)

This function cleans up the forecast power profiles to eliminate negative forecast values and non-zero forecasts when the actual values are zero (used as an indication that it is night). Not a great approximation but good enough.

The 8-node DSOs are added to the dso_meta object to the end of the list. They don’t have all the same metadata as the original 200-node DSOs.

Parameters:

dso_meta (list) – List of dicts with metadata associated with each DSO
idx (int) – Index for dso_meta to indicate which DSO needs to be cleaned up.
error (list) – List of values containing the synthesized error signal
forecast_profile (list) – List of values containing the forecast profile with forecast errors added (sometimes causing problems that this function cleans up).

Returns:

List of values containing the forecast profile after cleaning.

Return type:

forecast_profile (list)

tesp_support.dsot.solar.generate_KML(dso_meta, output_file)

This function attempts to make a KML file that can be loaded into Google Earth to visualize the solar locations.

Parameters:

dso_meta (list) – List of dicts with metadata associated with each DSO
output_file (str) – Location to write output KML

tesp_support.dsot.solar.generate_forecast_metrics(dso_meta, output_path)

Calculates the RMSE associated with each solar forecast file and write it out to file.

Parameters:

dso_meta
output_path

Returns:

(none)

tesp_support.dsot.solar.log_metdata(dso_meta)

tesp_support.dsot.solar.parse_DSO_metadata_Excel(dso_metadata_path, worksheet_name)

(DEPRECATED): Metadata is now stored in JSON file. See parse_DSO_metadata_Excel_JSON. This function parses the DSO metadata which is contained in an Excel spreadsheet

Parameters:

dso_metadata_path (str) – Path to the Excel file containing the metadata to be parsed.
worksheet_name (str) – Name of the worksheet in the Excel file containing the metadata

Returns:

One dictionary per DSO with appropriate metadata captured.

Return type:

dso_meta (list of dicts)

tesp_support.dsot.solar.parse_DSO_metadata_Excel_JSON(dso_metadata_path_Excel, worksheet_name, dso_metadata_path_JSON)

This function parses the DSO metadata which is contained in a JSON and Excel files. Most of the metadata is in the JSON but one crucial piece of information is in the Excel file: the mapping of the 200-node to 8-node buses.

Sample of the bus-generator file: (Note the first columns is empty) 200 bus 8 bus 1 1 2 1 3 1 4 1 5 1 6 1 …

Sample of JSON structure: “general”: { … } “DSO_1”: { “bus_number”: 1, “latitude”: 33.02, “longitude”: -96.85, “average_load_MW”: 4154.30537, … }, …

Parameters:

dso_metadata_path_Excel (str) – Path to the Excel file containing the metadata to be parsed.
worksheet_name (str) – Name of the worksheet in the Excel file containing the metadata.
dso_metadata_path_JSON (str) – Path to the JSON file containing the metadata to be parsed.

Returns:

One dictionary per DSO with appropriate metadata captured.

Return type:

dso_meta (list of dicts)

tesp_support.dsot.solar.parse_solar_metadata(solar_metadata_path)

This function parses the solar metadata JSON.

Parameters:: solar_metadata_path (str) – Path to the JSON file containing the metadata to be parsed.
Returns:: Dictionary form of the data in the JSON file
Return type:: solar_dict (dicts)

tesp_support.dsot.solar.truncate(f, n=3)

This function truncates the passed in value to the specified number of decimals. The default value is three decimals.

Parameters:

f (string/float) – Value to be truncated
n (int) – Number of decimal places to truncate to

Returns:

Truncated value of f

Return type:

truc_val (string/float)

tesp_support.dsot.solar.write_power_profile(output_path, power_data)

This function writes out a power profile to the provided file. Only intended to write out a single value per line. I probably should have used the standard CSV library instead.

Parameters:

power_data (list) – List of power values
output_path (str) – Path to the location of file to write.

tesp_support.dsot.substation module

Manages the Transactive Control scheme for DSO+T implementation version 1

Public Functions:

dso_loop:: initializes and runs the agents

tesp_support.dsot.substation.dso_loop(metrics_root, with_market)

Wrapper for inner_substation_loop

When inner_substation_loop finishes, timing and memory metrics will be printed for non-Windows platforms.

tesp_support.dsot.substation_f module

Manages the Transactive Control scheme for DSO+T implementation version 1

Public Functions:

dso_loop_f:: initializes and runs the agents

tesp_support.dsot.substation_f.dso_loop_f(configfile, metrics_root, with_market)

Wrapper for inner_substation_loop

When inner_substation_loop finishes, timing and memory metrics will be printed for non-Windows platforms.

tesp_support.dsot.tou module

tesp_support.dsot.tou.main(dso_name, method)

tesp_support.dsot.tou.time_of_use_price_profile(tou_params, step_size, dso_name, save_path=None)

Creates a price profile that corresponds to parameters of a specified time-of-use rate.

Parameters:

tou_params (dict) – A dictionary of relevant time-of-use rate parameters for each DSO. Includes time-of-use rate periods, off-peak price, scaling between off-peak price and specified time-of-use period, and seasonal membership for each month.
step_size (str) – A string indicating the size of each time step in a format recognizable by pandas (e.g., “1h” corresponds to time steps of one hour, “5min” corresponds to time steps of five minutes).
dso_name (str) – A string specifying the DSO’s name.
save_path (str) – A string specifying the directory to which the created time-of-use price profile should be saved. If no price profile should be saved, provide None. Defaults to not saving the created price profile.

Reutrns:: tou_profile (pandas.DataFrame): A DataFrame specifying the price profile for each DSO in time steps of size step_size.

tesp_support.dsot.water_heater_agent module

Class that controls the Water Heater DER

Implements the optimum schedule of heating element operation given DA price forecast; generate the bids for DA and RT; monitor and supervisory control of GridLAB-D environment element with the implementation of new SOHC model and new delta_SOHC model

The function call order for this agent is:

initialize

Repeats at every hour:

DA_forecasted_price(forecasted_price)
DA_forecasted_schedule(forecasted_schedule)
formulate_bid_da()

Repeats at every 5 min:

formulate_bid_rt()
bid_accepted()

class tesp_support.dsot.water_heater_agent.WaterHeaterDSOT(wh_dict, wh_properties, key, model_diag_level, sim_time, solver)

Bases: object

This agent manage the operation of water heater

Parameters:

wh_dict (dict)
wh_properties (dict)
key (str)
model_diag_level (int) – Specific level for logging errors; set it to 11
sim_time (str) – Current time in the simulation; should be human-readable
solver (str)

volume

volume of the tank, in gal

Type:: float

diameter

diameter of the tank layer, in ft

Type:: float

Phw

rated power of the heating elements, in kW

Type:: float

Tcold

temperature of the inlet cold water, in degF

Type:: float

Tambient

ambient temperature, in degF

Type:: float

Tdesired

setpoint value with highest user comfort, in degF

Type:: float

Tmax

highest tolerant temperature of the water, in degF

Type:: float

Tmin

lowest tolerant temperature of the water, in degF

Type:: float

windowLength

length of DA bidding timeframe

Type:: int

weight_SOHC

weight of the upper temperature measure when estimating the SOHC, falls into range [0, 1]

Type:: float

weight_comfort

weight of the user comfort in the DA quantity optimization objective, falls into range [0, 1]

Type:: float

ProfitMargin_intercept

specified in % and used to modify slope of bid curve. Set to 0 to disable

Type:: float

ProfitMargin_slope

specified in % to generate a small dead band (i.e., change in price does not affect quantity). Set to 0 to disable

Type:: float

participating

equals to 1 when participate in the price-responsive biddings

Type:: bool

price_cap

the maximum price that is allowed in the retail market, in $/kWh

Type:: float

H_tank

height of the water tank, in ft

Type:: float

A_tank

area of the layer of tank, in ft2

Type:: float

A_wall

area of the water tank wall, in ft2

Type:: float

R_tank

tank insulation, in ft2*hr*degF/Btu

Type:: float

Cp

specific heat of water, in Btu/lbm*degF

Type:: float

Rho

density of the water, in lbm/ft3

Type:: float

BTUperkWh

unit conversion from kWh to BTU, in BTU/kWh

Type:: float

GALperFt3

unit conversion from ft3 to gallon, in ga/ft3

Type:: float

T_upper

current set point of the upper heating element, in degF

Type:: float

T_bottom

current set point of the bottom heating element, in degF

Type:: float

SOHC

statue of heat charge, in %

Type:: float

SOHC_desired

desired SOHC, in %

Type:: float

SOHC_max

maximum SOHC, in %

Type:: float

SOHC_min

minimum SOHC, in %

Type:: float

states_upper

list of states and time in 5-min of upper element

Type:: list

states_bottom

list of states and time in 5-min of bottom element

Type:: list

runtime_upper

runtime of the upper element during 5-min

Type:: float

runtime_bottom

runtime of the lower element during 5-min

Type:: float

E_upper

energy consumed by the upper element in 5min, in kWh

Type:: float

E_bottom

energy consumed by the bottom elemnt in 5min, in kWh

Type:: float

wd_rate

averaged water draw flow rate in the 5min, in gal/min

Type:: float

Setpoint_upper

setpoint to be set for the upper element, in degF

Type:: float

Setpoint_bottom

setpoint to be set for the bottom element, in degF

Type:: float

length_memory

length of memory for the historical data

Type:: int

his_T_upper

historical time series data of the temperature measurement at the upper position

Type:: list

his_T_bottom

historical time series data of the temperature measurement at the bottom position

Type:: list

his_SOHC

historical time series data of the SOHC

Type:: list

his_E_upper

historical time series power consumption of upper element

Type:: list

his_E_bottom

historical time series power consumption of bottom element

Type:: list

his_wd_rate

historical time series water draw flow rate data

Type:: list

f_DA_price

forecasted DA price

Type:: list

f_DA_schedule

forecasted DA water draw schedule

Type:: list

P

index of price in the bid curve matrix

Type:: int

Q

index of quantity in the bid curve matrix

Type:: int

DA_cleared_prices

list of 48-hours day-ahead cleared prices

Type:: list

DA_cleared_quantities

list of 48-hours day-ahead cleared quantities

Type:: list

RT_cleared_price

cleared price for the next 5min

Type:: float

RT_cleared_quantity

cleared quantity for the next 5min

Type:: float

hourto5min

conversion from hour to 5min, equals to 12

Type:: int

hour

current hour

Type:: int

minute

current minute

Type:: int

co0_hour

intercept of the hourly delta SOHC model

Type:: float

co1_hour

coefficient of the water draw flow rate in the hourly delta SOHC model

Type:: float

co2_hour

coefficient of the upper element consumption in the hourly delta SOHC model

Type:: float

co3_hour

coefficient of the bottom element consumption in the hourly delta SOHC model

Type:: float

co0_5min

intercept of the 5min delta SOHC model

Type:: float

co1_5min

coefficient of the water draw flow rate in the 5min delta SOHC model

Type:: float

co2_5min

coefficient of the upper element consumption in the 5min delta SOHC model

Type:: float

co3_5min

coefficient of the bottom element consumption in the 5min delta SOHC model

Type:: float

RT_SOHC_max

the maximum SOHC the water heater can achieve in the next 5min, in %

Type:: float

RT_SOHC_min

the minimum SOHC the water heater can achieve in the next 5min, in %

Type:: float

RT_Q_max

higher quantity boundary of the RT bid curve, in kWh

Type:: float

RT_Q_min

lower quantity boundary of the RT bid curve, in kWh

Type:: float

DA_optimal_quantities()

Generates Day Ahead optimized quantities for Water Heater according to the forecasted prices and water draw schedule, called by DA_formulate_bid function

Returns:: Optimized quantities for each hour in the DA bidding horizon, in kWh
Return type:: Quantity (list) (1 x windowLength)

bid_accepted(model_diag_level, sim_time)

Update the thermostat setting if the last bid was accepted

The last bid is always “accepted”. If it wasn’t high enough, then the thermostat could be turned up.

Parameters:

model_diag_level (int) – Specific level for logging errors; set it to 11
sim_time (str) – Current time in the simulation; should be human-readable

Returns:

True if the thermostat setting changes, False if not.

Return type:

bool

con_rule_eq1(m, t)

con_rule_ine1(m, t)

delta_SOHC_model_5min(): Function used to fit the 5min delta_SOHC estimation model, where 5min delta_SOHC is assumed to be a function of wd_rate E_upper and E_bottom values with 5min interval

delta_SOHC_model_hour(): Function used to fit the hourly delta_SOHC estimation model, where hourly delta_SOHC is assumed to be a function of wd_rate E_upper and E_bottom values with one-hour interval

estimate_wd_rate_5min(): Function used to estimate the water_draw flow rate in the previous 5 mins, called by update_WH_his every 5 mins

formulate_bid_da()

Formulate windowLength hours 4 points PQ bid curves for the DA market

Function calls DA_optimal_quantities to obtain the optimal quantities for the DA market. With the quantities, a 4 point bids are formulated for each hour.

Returns BID (float) (windowLength X 4 X 2): DA bids to be send to the retail DA market

formulate_bid_rt(model_diag_level, sim_time)

Formulate 4 points PQ bid curve for the RT market

Given the physical and operational constraints of the water heater and the current water heater status, 4 points RT bid curve is formulated for the next 5min.

Parameters:

model_diag_level (int) – Specific level for logging errors: set it to 11
sim_time (str) – Current time in the simulation; should be human-readable

Returns:

RT bid to be send to the retail RT market

Return type:

BID (float) (4 X 2)

from_P_to_Q_WH(BID, PRICE)

Convert the 4 point bids to a quantity with the known price

Parameters:

BID (float) ((1,2)X4) – 4 point bid
PRICE (float) – cleared price in $/kWh

Returns:

quantity to be consumed in the next 5-min

Return type:

quantity (float)

get_uncntrl_wh_load()

This simulates the waterheater model without

Returns:: 48-hours forecast of non transactive waterheater kw consumption without optimization (agent participation)
Return type:: list

inform_bid_da(DAprices)

Updated the DA_cleared_prices and DA_cleared_quantities attributes when informed by retail market agent

Parameters:: DAprices (list) – cleared prices from the last DA market clearing, in $/kWh, provided by retail market agent

inform_bid_rt(RTprice)

Updated the RT_cleared_prices and RT_cleared_quantities attributes when informed by retail market agent

Parameters:: RTprice (float) – cleared price from the last RT market clearing, in $/kWh, provided by retail market agent

obj_rule(m)

set_air_temp(fncs_str, model_diag_level, sim_time)

Sets the air_temp attribute

Parameters:

fncs_str (str) – FNCS message with temperature in degrees Fahrenheit
model_diag_level (int) – Specific level for logging errors; set to 11
sim_time (str) – Current time in the simulation; should be human-readable

set_da_cleared_quantity(BID, PRICE)

Convert the 4 point bids to a quantity with the known price

Parameters:

BID (float) ((1,2)X4) – 4 point bid
PRICE (float) – cleared price in $/kWh

Returns:

cleared quantity

Return type:

quantity (float)

set_forecasted_schedule(forecasted_waterdraw_array)

Set the f_DA_schedule attribute

Parameters:: forecasted_waterdraw_array (list) – forecasted waterdraw flow rate schedule in gallons/min, provided by forecast agent

set_price_forecast(forecasted_price)

Set the f_DA_price attribute

Parameters:: forecasted_price (list) – forecasted DA prices in $/kwh, provided by retail market agent

set_time(minute, hour)

Sets the current hour and minute

Parameters:

minute (int) – the minute of the hour from 0 to 59
hour (int) – the hour of the day, from 0 to 23

set_wh_load(fncs_str)

Sets the water heater load attribute, if greater than zero

Parameters:: fncs_str (str) – FNCS message with load in kW

set_wh_lower_state(fncs_str)

Sets the lower element state attribute

Parameters:: fncs_str (str) – FNCS message with ON/OFF status

set_wh_lower_temperature(fncs_str, model_diag_level, sim_time)

Sets the lower tank temperature attribute

Parameters:

fncs_str (str) – FNCS message with temperature in degrees Fahrenheit
model_diag_level (int) – Specific level for logging errors; set it to 11
sim_time (str) – Current time in the simulation; should be human-readable

set_wh_upper_state(fncs_str)

Sets the upper element state attribute

Parameters:: fncs_str (str) – FNCS message with ON/OFF status

set_wh_upper_temperature(fncs_str, model_diag_level, sim_time)

Sets the upper tank temperature attribute

Parameters:

fncs_str (str) – FNCS message with temperature in degrees Fahrenheit
model_diag_level (int) – Specific level for logging errors; set it to 11
sim_time (str) – Current time in the simulation; should be human-readable

set_wh_wd_rate_val(fncs_str)

Sets the water draw rate attribute

Parameters:: fncs_str (str) – FNCS message with wdrate value in gpm

test_function(): Test function with the only purpose of returning the name of the object

update_WH_his(model_diag_level, sim_time)

Update the historical memory of water heater based on updated readings, called by formulate_bid_rt every 5 mins

Parameters:

model_diag_level (int) – Specific level for logging errors; set it to 11
sim_time (str) – Current time in the simulation; should be human-readable

tesp_support.dsot.water_heater_agent.test()

tesp_support.dsot.wind_gen_year module

Written by Ankit Singhal and Mitch Pelton This scripts use Tom’s wind model to generate wind power generation and write in csv files. This script should be kept in tesp_support folder

It writes two files:

1. wind.csv: can be considered as actual wind value. It is written with 5 minute resolution. Tom’s model generates hourly data which is interpolated to 5 minute (300 seconds) resolution.

2. wind_forecast.csv: a gaussian distribution of error is added to generate hourly wind forecast. First error is added in 5 minute resolution data which then averaged to hourly data.

tesp_support.dsot.wind_gen_year.generate_wind_data_24hr(wind_plants)

tesp_support.dsot.wind_gen_year.make_wind_plants(ppc)

tesp_support.dsot.wind_gen_year.test()