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 mins

• set_battery_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(battery_dict, inv_properties, key, model_diag_level, sim_time, solver)

Bases: object

This agent manages the battery/inverter

Parameters:

• battery_dict (dict) –

• 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

batteryCapacity

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

ProfitMargin_slope

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

Type:

float

ProfitMargin_intercept

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

Type:

float

pm_hi

Highest possible profit margin in %

Type:

float

pm_lo

Lowest possible profit margin in %

Type:

float

RT_state_maintain

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

Type:

bool

RT_state_maintain_flag

0. 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 Battery

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” wich 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_battery_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()

Makes a single battery agent and run DA

tesp_support.dsot.case_comparison_plots module

tesp_support.dsot.case_comparison_plots.plot_lmp_stats(cases, data_paths, output_path, dso_num, variable)

Will plot LMPS by month, duration, and versus netloads loads (for select month), and save to file. :param cases: names of the cases :type cases: List[str] :param data_paths: location of the data files to be used. :type data_paths: 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 :param variable: :type variable: str

Returns:

saves dso lmps plots to file

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)

tesp_support.dsot.customer_CFS.get_customer_df(dso_range, case_path, metadata_path)

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, DSO_Cash_Flows, DSO_Revenues_and_Energy_Sales, Market_Purchases, Market_Purchases_base_case)

tesp_support.dsot.dso_CFS.get_DSO_df(dso_range, case_config, DSOmetadata, case_path, base_case_path)

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_mean_for_diff_groups(df, main_variables, variables_combs, cfs_start_position=24)

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, dso_num, metadata, dso_expenses, tariff_path, dso_scaling_factor, num_indust_cust)

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 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

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.get_cust_bill(cust, bill_df, bill_metadata)

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

Returns:

dictionary of customers annual energy bill

Return type:

customer_annual_bill (dict)

tesp_support.dsot.dso_rate_making.read_meters(metadata, dir_path, folder_prefix, dso_num, day_range, SF, dso_data_path)

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

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 industial) 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 min:

• set_battery_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(ev_dict, inv_properties, key, model_diag_level, sim_time, solver)

Bases: object

This agent manages the electric vehicle (ev)

Parameters:

• ev_dict (dict) –

• 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

evCapacity

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:

float) (1 X windowLength

ProfitMargin_slope

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

Type:

float

ProfitMargin_intercept

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

Type:

float

pm_hi

Highest possible profit margin in %

Type:

float

pm_lo

Lowest possible profit margin in %

Type:

float

RT_state_maintain

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

Type:

bool

RT_state_maintain_flag

0. 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:

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:

float) (1 X Window Length

prev_clr_Price

cleared prices ($/kWh) from previous market iteration

Type:

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 EV

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 ev 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 ev. 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_ev(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 -> active power (-) charging (+) discharging

Return type:

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_ev_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 battery agent and run DA

tesp_support.dsot.forecasting module

Class responsible for forecasting

Implements the substation level DA price forecast and load forecast

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)

Correcs the quantity submited to the wolsale 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(moh, hod, dow, model_diag_level, sim_time)

Updates the time-scheduled thermostat setting

Parameters:

• moh (int) – the minute of the hour from 0 to 59

• hod (int) – the hour of the day, from 0 to 23

• dow (int) – the day of the week, zero being Monday

• 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

change_solargain(moh, hod, dow)

Updates the pre-recorder solar gain

Parameters:

• moh (int) – the minute of the hour from 0 to 59

• hod (int) – the hour of the day, from 0 to 23

• dow (int) – the day of the week, zero being Monday

Updates:

solar_gain

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_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.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)

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

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)

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)

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’ 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 agent 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 (range) – 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.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.pv_agent.test()

Makes a single pv agent and run DA

tesp_support.dsot.residential_feeder_glm module

Replaces ZIP loads with houses, and optional storage and solar generation.

As this module populates the feeder backbone with houses and DER, it uses the Networkx package to perform graph-based capacity analysis, upgrading fuses, transformers and lines to serve the expected load. Transformers have a margin of 20% to avoid overloads, while fuses have a margin of 150% to avoid overloads. These can be changed by editing tables and variables in the source file.

There are two kinds of house populating methods implemented:

• Feeders with Service Transformers:

  This case applies to the full PNNL taxonomy feeders. Do not specify the taxchoice argument to populate_feeder. Each service transformer receiving houses will have a short service drop and a small number of houses attached.

• Feeders without Service Transformers:

  This applies to the reduced-order ERCOT feeders. To invoke this mode, pecify the taxchoice argument to populate_feeder. Each primary load to receive houses will have a large service transformer, large service drop and large number of houses attached.

References

GridAPPS-D Feeder Models

Public Functions:

populate_feeder:

processes one GridLAB-D input file

Todo

• Verify the level zero mobile home thermal integrity properties; these were copied from the MATLAB feeder generator

• Populate commercial building loads

tesp_support.dsot.residential_feeder_glm.Find1PhaseXfmr(kva)

Select a standard 1-phase transformer size, with data

Standard sizes are 5, 10, 15, 25, 37.5, 50, 75, 100, 167, 250, 333 or 500 kVA

Parameters:

kva (float) – the minimum transformer rating

Returns:

the kva, %r, %x, %no-load loss, %magnetizing current

Return type:

[float,float,float,float,float]

tesp_support.dsot.residential_feeder_glm.Find1PhaseXfmrKva(kva)

Select a standard 1-phase transformer size, with some margin

Standard sizes are 5, 10, 15, 25, 37.5, 50, 75, 100, 167, 250, 333 or 500 kVA

Parameters:

kva (float) – the minimum transformer rating

Returns:

the kva size, or 0 if none found

Return type:

float

tesp_support.dsot.residential_feeder_glm.Find3PhaseXfmr(kva)

Select a standard 3-phase transformer size, with data

Standard sizes are 30, 45, 75, 112.5, 150, 225, 300, 500, 750, 1000, 1500, 2000, 2500, 3750, 5000, 7500 or 10000 kVA

Parameters:

kva (float) – the minimum transformer rating

Returns:

the kva, %r, %x, %no-load loss, %magnetizing current

Return type:

[float,float,float,float,float]

tesp_support.dsot.residential_feeder_glm.Find3PhaseXfmrKva(kva)

Select a standard 3-phase transformer size, with some margin

Standard sizes are 30, 45, 75, 112.5, 150, 225, 300, 500, 750, 1000, 1500, 2000, 2500, 3750, 5000, 7500 or 10000 kVA

Parameters:

kva (float) – the minimum transformer rating

Returns:

the kva size, or 0 if none found

Return type:

float

tesp_support.dsot.residential_feeder_glm.FindFuseLimit(amps)

Find a Fuse size that’s unlikely to melt during power flow

Will choose a fuse size of 40, 65, 100 or 200 Amps. If that’s not large enough, will choose a recloser size of 280, 400, 560, 630 or 800 Amps. If that’s not large enough, will choose a breaker size of 600 (skipped), 1200 or 2000 Amps. If that’s not large enough, will choose 999999.

Parameters:

amps (float) – the maximum load current expected; some margin will be added

Returns:

the GridLAB-D fuse size to insert

Return type:

float

tesp_support.dsot.residential_feeder_glm.ProcessTaxonomyFeeder(outname, rootname, vll, vln, avghouse, avgcommercial)

Parse and re-populate one backbone feeder, usually but not necessarily one of the PNNL taxonomy feeders

This function:

• reads and parses the backbone model from rootname.glm

• replaces loads with houses and DER

• upgrades transformers and fuses as needed, based on a radial graph analysis

• writes the repopulated feeder to outname.glm

Parameters:

• outname (str) – the output feeder model name

• rootname (str) – the input (usually taxonomy) feeder model name

• vll (float) – the feeder primary line-to-line voltage

• vln (float) – the feeder primary line-to-neutral voltage

• avghouse (float) – the average house load in kVA

• avgcommercial (float) – the average commercial load in kVA, not used

tesp_support.dsot.residential_feeder_glm.accumulate_load_kva(data)

Add up the total kva in a load-bearing object instance

Considers constant_power_A/B/C/1/2/12 and power_1/2/12 attributes

Parameters:

data (dict) – dictionary of data for a selected GridLAB-D instance

tesp_support.dsot.residential_feeder_glm.buildingTypeLabel(rgn, bldg, ti)

Formatted name of region, building type name and thermal integrity level

Parameters:

• rgn (int) – region number 1..5

• bldg (int) – 0 for single-family, 1 for apartment, 2 for mobile home

• ti (int) – thermal integrity level, 0..6 for single-family, only 0..2 valid for apartment or mobile home

tesp_support.dsot.residential_feeder_glm.checkResidentialBuildingTable()

Verify that the regional building parameter histograms sum to one

tesp_support.dsot.residential_feeder_glm.connect_ercot_commercial(op)

For the reduced-order ERCOT feeders, add a billing meter to the commercial load points, except small ZIPLOADs

Parameters:

op (file) – an open GridLAB-D input file

tesp_support.dsot.residential_feeder_glm.connect_ercot_houses(model, h, op, vln, vsec)

For the reduced-order ERCOT feeders, add houses and a large service transformer to the load points

Parameters:

• model (dict) – the parsed GridLAB-D model

• h (dict) – the object ID hash

• op (file) – an open GridLAB-D input file

• vln (float) – the primary line-to-neutral voltage

• vsec (float) – the secondary line-to-neutral voltage

tesp_support.dsot.residential_feeder_glm.getDsoThermalTable()

tesp_support.dsot.residential_feeder_glm.identify_ercot_houses(model, h, t, avgHouse, rgn)

For the reduced-order ERCOT feeders, scan each primary load to determine the number of houses it should have

Parameters:

• model (dict) – the parsed GridLAB-D model

• h (dict) – the object ID hash

• t (str) – the GridLAB-D class name to scan

• avgHouse (float) – the average house load in kva

• rgn (int) – the region number, 1..5

tesp_support.dsot.residential_feeder_glm.identify_xfmr_houses(model, h, t, seg_loads, avgHouse, rgn)

For the full-order feeders, scan each service transformer to determine the number of houses it should have

Parameters:

• model (dict) – the parsed GridLAB-D model

• h (dict) – the object ID hash

• t (str) – the GridLAB-D class name to scan

• seg_loads (dict) – dictionary of downstream load (kva) served by each GridLAB-D link

• avgHouse (float) – the average house load in kva

• rgn (int) – the region number, 1..5

tesp_support.dsot.residential_feeder_glm.is_drive_time_valid(drive_sch)

checks if work arrival time and home arrival time adds up properly :param drive_sch:

Returns:

true or false

tesp_support.dsot.residential_feeder_glm.is_edge_class(s)

Identify switch, fuse, recloser, regulator, transformer, overhead_line, underground_line and triplex_line instances

Edge class is networkx terminology. In GridLAB-D, edge classes are called links.

Parameters:

s (str) – the GridLAB-D class name

Returns:

True if an edge class, False otherwise

Return type:

bool

tesp_support.dsot.residential_feeder_glm.is_node_class(s)

Identify node, load, meter, triplex_node or triplex_meter instances

Parameters:

s (str) – the GridLAB-D class name

Returns:

True if a node class, False otherwise

Return type:

bool

tesp_support.dsot.residential_feeder_glm.log_model(model, h)

Prints the whole parsed model for debugging

Parameters:

• model (dict) – parsed GridLAB-D model

• h (dict) – object ID hash

tesp_support.dsot.residential_feeder_glm.match_driving_schedule(ev_range, ev_mileage, ev_max_charge)

Method to match the schedule of each vehicle from NHTS data based on vehicle ev_range

tesp_support.dsot.residential_feeder_glm.obj(parent, model, line, itr, oidh, octr)

Store an object in the model structure

Parameters:

• parent (str) – name of parent object (used for nested object defs)

• model (dict) – dictionary model structure

• line (str) – glm line containing the object definition

• itr (iter) – iterator over the list of lines

• oidh (dict) – hash of object id’s to object names

• octr (int) – object counter

Returns:

the current line and updated octr

Return type:

str, int

tesp_support.dsot.residential_feeder_glm.populate_all_feeders()

Wrapper function that batch processes all taxonomy feeders in the casefiles table (see source file)

tesp_support.dsot.residential_feeder_glm.populate_feeder(configfile=None, config=None, taxconfig=None)

Wrapper function that processes one feeder. One or two keyword arguments must be supplied.

Parameters:

• configfile (str) – JSON file name for the feeder population data, mutually exclusive with config

• config (dict) – dictionary of feeder population data already read in, mutually exclusive with configfile

• taxconfig (dict) – dictionary of custom taxonomy data for ERCOT processing

tesp_support.dsot.residential_feeder_glm.process_nhts_data(data_file)

read the large nhts survey data file containing driving data, process it and return a dataframe :param data_file: path of the file

Returns:

dataframe containing start_time, end_time, travel_day (weekday/weekend) and daily miles driven

tesp_support.dsot.residential_feeder_glm.randomize_commercial_skew()

tesp_support.dsot.residential_feeder_glm.randomize_residential_skew()

tesp_support.dsot.residential_feeder_glm.randomize_skew(value, skew_max)

tesp_support.dsot.residential_feeder_glm.replace_commercial_loads(model, h, t, avgBuilding)

For the full-order feeders, scan each load with load_class==C to determine the number of zones it should have

Parameters:

• model (dict) – the parsed GridLAB-D model

• h (dict) – the object ID hash

• t (str) – the GridLAB-D class name to scan

• avgBuilding (float) – the average building in kva

tesp_support.dsot.residential_feeder_glm.selectEVmodel(evTable, prob)

Selects the building and vintage type :param evTable: models probability list :type evTable: dict :param prob: probability :type prob: ?

tesp_support.dsot.residential_feeder_glm.selectResidentialBuilding(rgnTable, prob)

Selects the building with region and probability

Parameters:

• rgnTable –

• prob –

tesp_support.dsot.residential_feeder_glm.selectSetpointBins(bldg, rand)

Randomly choose a histogram row from the cooling and heating setpoints

The random number for the heating and cooling set points row is generated internally.

Parameters:

• bldg (int) – 0 for single-family, 1 for apartment, 2 for mobile home

• rand (float) – random number [0..1] for the cooling setpoint row

tesp_support.dsot.residential_feeder_glm.selectThermalProperties(bldgIdx, tiIdx)

Retrieve the building thermal properties for a given type and integrity level

Parameters:

• bldgIdx (int) – 0 for single-family, 1 for apartment, 2 for mobile home

• tiIdx (int) – 0..7 for single-family, apartment or mobile home

tesp_support.dsot.residential_feeder_glm.union_of_phases(phs1, phs2)

Collect all phases on both sides of a connection

Parameters:

• phs1 (str) – first phasing

• phs2 (str) – second phasing

Returns:

union of phs1 and phs2

Return type:

str

tesp_support.dsot.residential_feeder_glm.write_config_class(model, h, t, op)

Write a GridLAB-D configuration (i.e. not a link or node) class

Parameters:

• model (dict) – the parsed GridLAB-D model

• h (dict) – the object ID hash

• t (str) – the GridLAB-D class

• op (file) – an open GridLAB-D input file

tesp_support.dsot.residential_feeder_glm.write_ercot_small_loads(basenode, op, vnom)

For the reduced-order ERCOT feeders, write loads that are too small for houses

Parameters:

• basenode (str) – the GridLAB-D node name

• op (file) – an open GridLAB-D input file

• vnom (float) – the primary line-to-neutral voltage

tesp_support.dsot.residential_feeder_glm.write_houses(basenode, op, vnom)

Put houses, along with solar panels and batteries, onto a node

Parameters:

• basenode (str) – GridLAB-D node name

• op (file) – open file to write to

• vnom (float) – nominal line-to-neutral voltage at basenode

tesp_support.dsot.residential_feeder_glm.write_link_class(model, h, t, seg_loads, op, want_metrics=False)

Write a GridLAB-D link (i.e. edge) class

Parameters:

• model (dict) – the parsed GridLAB-D model

• h (dict) – the object ID hash

• t (str) – the GridLAB-D class

• seg_loads (dict) – a dictionary of downstream loads for each link

• op (file) – an open GridLAB-D input file

tesp_support.dsot.residential_feeder_glm.write_local_triplex_configurations(op)

Write a 4/0 AA triplex configuration

Parameters:

op (file) – an open GridLAB-D input file

tesp_support.dsot.residential_feeder_glm.write_small_loads(basenode, op, vnom)

Write loads that are too small for a house, onto a node

Parameters:

• basenode (str) – GridLAB-D node name

• op (file) – open file to write to

• vnom (float) – nominal line-to-neutral voltage at basenode

tesp_support.dsot.residential_feeder_glm.write_solar_inv_settings(op)

Writes volt-var and volt-watt settings for solar inverters

Parameters:

op (file) – an open GridLAB-D input file

tesp_support.dsot.residential_feeder_glm.write_substation(op, name, phs, vnom, vll)

Write the substation swing node, transformer, metrics collector and fncs_msg object

Parameters:

• op (file) – an open GridLAB-D input file

• name (str) – node name of the primary (not transmission) substation bus

• phs (str) – primary phasing in the substation

• vnom (float) – not used

• vll (float) – feeder primary line-to-line voltage

tesp_support.dsot.residential_feeder_glm.write_tariff(op)

Writes tariff information to billing meters

Parameters:

op (file) – an open GridLAB-D input file

tesp_support.dsot.residential_feeder_glm.write_voltage_class(model, h, t, op, vprim, vll, secmtrnode)

Write GridLAB-D instances that have a primary nominal voltage, i.e., node, meter and load

Parameters:

• model (dict) – a parsed GridLAB-D model

• h (dict) – the object ID hash

• t (str) – the GridLAB-D class name to write

• op (file) – an open GridLAB-D input file

• vprim (float) – the primary nominal line-to-neutral voltage

• vll (float) – the primary nominal line-to-line voltage

• secmtrnode (dict) – key to [transfomer kva, phasing, nominal voltage] by secondary node name

tesp_support.dsot.residential_feeder_glm.write_xfmr_config(key, phs, kvat, vnom, vsec, install_type, vprimll, vprimln, op)

Write a transformer_configuration

Parameters:

• key (str) – name of the configuration

• phs (str) – primary phasing

• kvat (float) – transformer rating in kVA

• vnom (float) – primary voltage rating, not used any longer (see vprimll and vprimln)

• vsec (float) – secondary voltage rating, should be line-to-neutral for single-phase or line-to-line for three-phase

• install_type (str) – should be VAULT, PADMOUNT or POLETOP

• vprimll (float) – primary line-to-line voltage, used for three-phase transformers

• vprimln (float) – primary line-to-neutral voltage, used for single-phase transformers

• op (file) – an open GridLAB-D input file

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)

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

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)

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 metadata_file:

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)

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

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.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(hour, minute)

Sets the current hour and minute

Parameters:

• hour (int) – current hour

• minute (int) – current minute

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()