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
Balance Sheet functions
- tesp_support.dsot.balance_sheet_functions.iso_balance_sheet_annual(meta_path, write_path, write_to_txt=False, write_to_JSON=False)
This function calculates …
- Parameters:
meta_path
write_path
write_to_txt
write_to_JSON
- Return type:
dict
- tesp_support.dsot.balance_sheet_functions.test_iso()
- tesp_support.dsot.balance_sheet_functions.test_too()
- tesp_support.dsot.balance_sheet_functions.too_balance_sheet_annual(meta_path, write_path, write_to_txt=False, write_to_JSON=False)
This function calculates …
- Parameters:
meta_path
write_path
write_to_txt
write_to_JSON
- Return type:
dict
tesp_support.dsot.battery_agent module
Class that controls the Battery DER
Implements the optimum schedule of charging and discharging DA; generate the bids for DA and RT; monitor and supervisory control of GridLAB-D environment element.
- The function call order for this agent is:
initialize()
- Repeats at every hour:
formulate_bid_da() {return BID}
set_price_forecast(forecasted_price)
- Repeats at every 5 minutes:
set_SOC(msg_str) {updates C_init}
formulate_bid_rt() {return BID}
inform_bid(price) {update RTprice}
bid_accepted() {update inv_P_setpoint and GridLAB-D P_out if needed}
- class tesp_support.dsot.battery_agent.BatteryDSOT(diction, inv_properties, key, model_diag_level, sim_time, solver)
Bases:
objectThis agent manages the battery/inverter (bt)
- Parameters:
diction (dict) – battery/inverter parameters
inv_properties (dict)
key (str)
model_diag_level (int) – Specific level for logging errors; set it to 11
sim_time (str) – Current time in the simulation; should be human-readable
solver (str)
- Initialize from Args
- name
name of this agent
- Type:
str
- Rc
rated charging power in kW for the battery
- Type:
float
- Rd
rated discharging power in kW for the battery
- Type:
float
- Lin
battery charging loss in %
- Type:
float
- Lout
battery discharging loss in %
- Type:
float
- Cmin
minimum allowable stored energy in kWh (state of charge lower limit)
- Type:
float
- Cmax
maximum allowable stored energy in kWh (state of charge upper limit)
- Type:
float
- Cinit
initial stored energy in the battery in kWh
- Type:
float
- capacity
battery capacity in kWh
- Type:
float
- batteryLifeDegFactor
constant to model battery degradation
- Type:
float
- windowLength
length of day ahead optimization period in hours (e.g. 48-hours)
- Type:
int
- dayAheadCapacity
% of battery capacity reserved for day ahead bidding
- Type:
float
- No initialization required
- bidSpread
this can be used to spread out bids in multiple hours. When set to 1 hour (recommended), its effect is none
- Type:
int
- P
location of P in bids
- Type:
int
- Q
location of Q in bids
- Type:
int
- f_DA
forecasted prices in $/kWh for all the hours in the duration of windowLength
- Type:
List[float]) (1 X windowLength
- RT_state_maintain
true if battery must maintain charging or discharging state for 1 hour
- Type:
bool
- RT_state_maintain_flag
not define at current hour (-1) charging (+1) discharging
- Type:
int
- RT_flag
if True, has to update GridLAB-D
- Type:
bool
- inv_P_setpoint
next GridLAB-D inverter power output
- Type:
float
- optimized_Quantity
Optimized quantity
- Type:
List[float]) (1 X Window Length
- #not used if not biding DA
- prev_clr_Quantity
cleared quantities (kWh) from previous market iteration for all hours
- Type:
List[float]) (1 X Window Length
- prev_clr_Price
cleared prices ($/kWh) from previous market iteration
- Type:
List[float]) (1 X windowLength
- BindingObjFunc
if True, then optimization considers cleared price, quantities from previous iteration in the objective function
- Type:
bool
- DA_cleared_price(price)
Set the DA_cleared_price attribute
- Parameters:
price (float) – cleared price in $/kWh
- DA_optimal_quantities()
Generates Day Ahead optimized quantities for agent
- Returns:
Optimal quantity from optimization for all hours of the window specified by windowLength
- Return type:
Quantity (float) (1 x windowLength)
- RT_fix_four_points_range(BID, Ql, Qu)
Verify feasible range of RT bid
- Parameters:
BID (float) ((1,2)X4) – 4 point bid
Ql
Qu
- Returns:
4 point bid only the feasible range
- Return type:
BIDr (float) ((1,2)X4)
- RT_gridlabd_set_P(sim_time)
Update variables for battery output “inverter”
- Parameters:
sim_time (str) – Current time in the simulation; should be human-readable
inv_P_setpoint is a float in W
- bid_accepted(current_time)
Update the P and Q settings if the last bid was accepted
- Returns:
True if the inverter settings changed, False if not.
- Return type:
bool
- con_rule_eq1(m, i)
- con_rule_eq2(m, i)
- con_rule_eq3(m, i)
- con_rule_ine1(m, i)
- con_rule_ine2(m, i)
- formulate_bid_da()
Formulate 4 points of P and Q bids for the DA market
Function calls “DA_optimal_quantities” to obtain the optimal quantities for the DA market. With the quantities, the 4 point bids are formulated.
Before returning the BID the function resets “RT_state_maintain_flag” which, if RT_state_maintain is TRUE, the battery will be forced to keep its state (i.e., charging or discharging).
- Returns:
store last DA market bids
- Return type:
BID (float) (((1,2)X4) X windowLength)
- formulate_bid_rt()
Formulates RT bid
Uses the last 4 point bid from DA market and consider current state of charge of the battery. Will change points to change points for feasible range of Qmin Qmax points if necessary. Furthermore, allows a maximum deviation of +/-100% from the DA plan.
- Returns:
bid in Real Time market
- Return type:
realTimeBid (float) ((1,2) x 4)
- from_P_to_Q_battery(BID, PRICE)
Convert the 4 point bids to a quantity with the known price
- Parameters:
BID (float) ((1,2)X4) – 4 point bid
PRICE (float) – cleared price in $/kWh
- Returns:
active power (-) charging (+) discharging
- Return type:
_quantity (float)
- inform_bid(price)
Set the cleared_price attribute
- Parameters:
price (float) – cleared price in $/kWh
- obj_rule(m)
- set_SOC(msg_str, 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
sim_time (str) – Current time in the simulation; should be human-readable
- set_price_forecast(forecasted_price)
Set the f_DA attribute
- Parameters:
forecasted_price (float x 48) – cleared price in $/kWh
- test_function()
Test function with the only purpose of returning the name of the object
- tesp_support.dsot.battery_agent.test()
Testing
Makes a single agent and run DA
tesp_support.dsot.case_comparison_plots module
- tesp_support.dsot.case_comparison_plots.customer_bill_component_comparison(cases, data_paths, output_path, dso_num)
Will plot key average bill components by month and duration 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
- Returns:
saves customer monthly bill plots to file
- tesp_support.dsot.case_comparison_plots.customer_cfs_delta(cases, data_paths, metadata_file, metadata_path=None)
Will plot customer population CFS savings comparisons. :param data_paths: location of the data files to be used. :type data_paths: str
- Returns:
saves dso lmps plots to file
- tesp_support.dsot.case_comparison_plots.customer_monthly_stats(cases, data_paths, output_path, dso_num, cust_class=None)
Will plot key variables by month and duration 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
- Returns:
saves customer monthly bill plots to file
- tesp_support.dsot.case_comparison_plots.dso_cfs_delta(cases_list, data_paths_list, dso_range, metadata_file, metadata_path)
Will plot LMPS by month, duration, and versus netloads loads (for select month), and save to file. :param cases: :param data_paths: location of the data files to be used. :type data_paths: list :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.case_comparison_plots.load_comparison_plot(day_range, metadata_path, cases, data_paths, output_path)
For a specified day range this function will load in the required data, plot the total DSO load. :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 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
- Returns:
saves comparison load plot to file
- tesp_support.dsot.case_comparison_plots.plot_annual_stats(cases, data_paths, output_path, dso_num, variable)
Will plot key variables by month and duration 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: variable to be plotted: ‘DA LMP’, ‘RT LMP’, ‘Total Load’, ‘Hybrid’, ‘Renewable Percent’, :type variable: str :param ‘Curtailment Percent’:
- Returns:
saves annual monthly stats plots to file
- tesp_support.dsot.case_comparison_plots.plot_customer_pdf(attribute, variables, metric, pop_df, case, output_path)
Will plot customer population savings comparisons. :param attribute: customer attribute to be studied (e.g. tariff class) :type attribute: str :param variables: list of variables possible for each attribute (e.g. [‘residential’, ‘commercial’]) :type variables: list :param metric: metric of interest to be plotted (e.g. ‘net_bill_savings_pct’) :type metric: 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
- Returns:
saves customer pdf plots to file
- tesp_support.dsot.case_comparison_plots.rates_plots()
- tesp_support.dsot.case_comparison_plots.rec_diff(d1, d2)
- tesp_support.dsot.case_comparison_plots.reduction_by_class(cases, data_paths, output_path, variable)
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.case_comparison_plots.retail_price_comparison_plot(dso, day_range, metadata_path, cases, data_paths, rate_scenarios, Month, output_path)
For a specified dso and day range this function will load in the required data, plot the retail price. :param dso: the DSO range that should be plotted. :type dso: num :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 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
- Returns:
saves comparison load plot to file
tesp_support.dsot.case_merge module
tesp_support.dsot.customer_CFS module
@author: yint392
- tesp_support.dsot.customer_CFS.customer_CFS(GLD_metadata, metadata_path, customer, customer_bill, rate_scenario)
tesp_support.dsot.dso_CFS module
@author: yint392
- tesp_support.dsot.dso_CFS.dso_CFS(case_config, DSOmetadata, dso_num, DSO_peak_demand, DSO_base_case_peak_demand, System_peak_fraction, DSO_Cash_Flows, DSO_Revenues_and_Energy_Sales, Market_Purchases, Market_Purchases_base_case, rate_scenario=None)
tesp_support.dsot.dso_helper_functions module
@author: yint392
- tesp_support.dsot.dso_helper_functions.TEAM(FteLev1=100.0, SalaryEsc1=1.3)
- tesp_support.dsot.dso_helper_functions.get_DSO_df(dso_range, case_config, DSOmetadata, case_path, base_case_path, rate_scenario=None)
- tesp_support.dsot.dso_helper_functions.get_customer_df(dso_range, case_path, metadata_path, rate_scenario)
- tesp_support.dsot.dso_helper_functions.get_mean_for_diff_groups(df, main_variables, variables_combs, cfs_start_position=25)
- tesp_support.dsot.dso_helper_functions.labor(group, metadata_general, metadata_dso, utility_type, NoSubstations)
- tesp_support.dsot.dso_helper_functions.labor_increase(group, metadata_general, metadata_dso, utility_type, NoSubstations, TransactiveCaseFlag)
- tesp_support.dsot.dso_helper_functions.labor_network_admin(group, hourly_rate, metadata_general, metadata_dso, utility_type, NoSubstations)
- tesp_support.dsot.dso_helper_functions.labor_network_admin_increase(group, hourly_rate, metadata_general, metadata_dso, utility_type, NoSubstations, TransactiveCaseFlag)
- tesp_support.dsot.dso_helper_functions.labor_network_admin_transactive(group, hourly_rate, metadata_general, metadata_dso, utility_type, NoSubstations, TransactiveCaseFlag)
- tesp_support.dsot.dso_helper_functions.labor_transactive(group, metadata_general, metadata_dso, utility_type, NoSubstations, TransactiveCaseFlag)
- tesp_support.dsot.dso_helper_functions.returnDictSum(temp_dict)
tesp_support.dsot.dso_map module
- tesp_support.dsot.dso_map.prepare_metadata(node, end_row, feeder_mode, high_renewables_case, DSO_Load_Threshold)
tesp_support.dsot.dso_market module
DSO market agent implementation.
This module defines DSOMarket, which performs DSO-side market functions:
- aggregate substation demand bids (RT and DA),
- execute trial wholesale-node clearing,
- convert between wholesale and retail prices,
- construct substation supply curves, including optional transformer degradation cost.
- class tesp_support.dsot.dso_market.DSOMarket(dso_dict, key)
Bases:
objectDSO-side market model for DSOT co-simulation.
The class maintains real-time (RT) and day-ahead (DA) bid/curve state, performs wholesale trial clearing, and produces retail-facing supply curves for substations.
- Parameters:
dso_dict (dict) – DSO configuration (limits, coefficients, scaling, and runtime options).
key (str) – DSO market agent identifier.
- 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_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 by resetting DA clearing state and initializing empty aggregated DA demand curves.
- clean_bids_RT()
Initialize the real-time wholesale node trial clearing by resetting RT clearing state and initializing an empty aggregated RT demand curve.
- 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
- generate_TOC(costInterval, maxPuLoad, num_samples, TOC_dict)
Compute transformer total owning cost (TOC) of transformer over sampled loading points.
- Parameters:
costInterval (int) – Cost accumulation interval in minutes.
maxPuLoad (float) – Maximum per-unit loading factor.
num_samples (int) – Number of sampled loading points.
TOC_dict (dict) – Transformer thermal/economic parameters.
- Returns:
DollarsForPlot: Cost values over sampled loading points.
LoadsForPlot: Per-unit loading points used for plotting.
- Return type:
tuple[list[float], list[float]]
- 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 cleared day-ahead quantities.
- Parameters:
val (str) – JSON-encoded array of DA cleared quantities (lmp for the
bus/substation).
- set_cleared_q_rt(val)
Set cleared real-time quantity.
- Parameters:
val (str) – JSON-encoded RT cleared quantity (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.
Set day-ahead industrial load profile (MW) for the DA horizon.
- Parameters:
industrial_load_da (str (24 x 1 array of double)) – JSON-encoded
MW. (array of industrial load values in)
- set_lmp_da(val)
Set the lmp for day ahead
- Parameters:
val (array of double) – JSON-encoded RT LMP payload 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 reference ERCOT load from a complex-power string based on provided load by a csv file after base case.
- Parameters:
ref_load (str) – Total substation load value.
- 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 (str (24 x 1 array of double)) – JSON-encoded array
ahead. (of ercot load values for the next day)
- set_total_load(total_load)
Set the residential load based on provided load by GLD, complex number
- Parameters:
total_load (str) – Total substation load value.
- substation_supply_curve_DA(retail_obj)
Function used to generate the DA supply curves for each substation
Build DA supply curves sent from DSO to a retail market.
- Parameters:
retail_obj (RetailMarket) – Retail market object providing feeder constraints and DA buyer curve context.
- Returns:
Hour-indexed DA substation supply curves.
- Return type:
dict[int, Curve]
- substation_supply_curve_RT(retail_obj)
Function used to generate the RT supply curve for each substation
Build the RT supply curve sent from DSO to a retail market.
- Parameters:
retail_obj (RetailMarket) – Retail market object providing feeder constraints and RT buyer curve context.
- Returns:
RT substation supply curve in retail-price space.
- Return type:
- 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
Create a supply curve with transformer-degradation adder.
Used by RT/DA substation supply-curve builders when degradation is enabled.
Build a retail supply curve with optional transformer owning-cost adder.
This helper is used by both RT and DA substation supply-curve builders when transformer degradation is enabled. It first forms a piecewise baseline price curve (using feeder capacity thresholds), then adds a per-kW owning-cost component derived from
generate_TOC().- Parameters:
Prclear (float) – Base retail clearing price in $/kWh.
FeederCongCapacity (float) – Feeder congestion threshold (quantity axis).
FeederPkDemandCapacity (float) – Feeder peak-demand threshold (quantity axis).
num_samples (int) – Number of curve sample points.
Q_max (float) – Substation quantity limit used for curve scaling.
maxPuLoading (float) – Maximum per-unit loading considered for TOC.
TOC_dict (dict) – Transformer owning-cost configuration parameters.
- Returns:
SupplyQuantities: sampled quantities from 0 to
Q_max * maxPuLoading.SupplyPrices: sampled prices in $/kWh after adding degradation adder.
- Return type:
tuple[np.ndarray, list[float]]
Notes
self.dollarsPerKWis updated as a side effect.generate_TOC(60, ...)is used, so the adder is computed on a 60-minute basis.
- test_function()
Test function with the only purpose of returning the name of the object
- Returns:
The name of the market object (debug helper).
- Return type:
str
- 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
Perform one wholesale trial clearing between supply and aggregated DSO demand.
- Args:
curve_ws_node (Curve): Wholesale-node supply curve. curve_DSO (Curve): Aggregated DSO demand curve. day (int): Day-of-week index used for diagnostics and curve selection. hour (int): Hour-of-day index used for diagnostics and curve selection.
- Returns:
- tuple[float, float, MarketClearingType]:
Cleared wholesale price ($/kWh), cleared quantity (kWh), and clearing type.
- update_wholesale_node_curve()
Rebuild wholesale-node supply curves from current quadratic coefficients.
Recomputes curve samples for each day-of-week and hour-of-day.
- tesp_support.dsot.dso_market.test()
Run an ad hoc smoke test for DSOMarket RT/DA clearing workflows.
This helper constructs sample DSO/retail objects, submits representative bids, executes clearing, and prints/plots outputs for manual inspection.
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:
objectThis object creates the quadratic curves with 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 through 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
- coefficients_weekday
24 arrays of 3 for every DSO
- Type:
array of arrays
- coefficients_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 specifying the curve coefficient being taken
- fit_model(i, p_time)
Fit a quadratic curve utilizing sklearn
- Parameters:
i (int) – DSO identifier
p_time (np array bool) – True for samples utilized in fitting the quadratic curve
- Returns:
[[‘1’, ‘x’, ‘x^2’]] quadratic curve coefficients
- Return type:
df_dsos_lml_q (array)
- make_json_out(rate_scenario='')
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_remove_outliers(data_da)
Organize and remove outliers from dataframe of multiple DSO
- Parameters:
data_da (dataframe) – contains historical data from DA LMPs with associated quantities
- Returns:
every element of the list is a DSO with historical price and quantity. The index is pandas datetime.
- Return type:
df_dsos_lml_q (list of dataframes)
tesp_support.dsot.dso_rate_making module
DSO rate-making and billing calculations for the DSOT rates analysis.
This module implements the two-stage DSO billing workflow:
- Stage 1 – Monthly (called once per month during co-simulation postprocessing)
read_meters() → energy_metrics_data.h5 / transactive_metrics_data.h5 Written to: <monthly_path>/Substation_<N>/
- Stage 2 – Annual (called by run_annual_postprocessing.py after all months complete)
- annual_energy() → reads monthly energy_metrics_data.h5 files and
produces annual energy_dso_<N>_data.h5 in the case folder.
- DSO_rate_making() → reads annual energy HDF5 files, calculates cost-recovery
tariff prices, computes individual customer bills, and writes bill HDF5/CSV files back to the case folder.
Rate scenarios supported
“flat” – Uniform volumetric rate; non-participating customers only. “time-of-use” – Seasonal peak/off-peak rates; requires time_of_use_parameters.json. “subscription” – Block-purchase rate with net deviation charge; requires
per-meter demand profiles from base_case monthly folders.
- “transactive” – Day-ahead + real-time LMP-based pricing with volumetric
distribution charge for participating customers.
“dsot” – DSO+T transactive rate (similar to transactive). None – Defaults to DSO+T (same as “dsot”).
Key required input files (per case folder)
energy_dso_<N>_data.h5 – Annual per-meter energy (from annual_energy()) transactive_dso_<N>_data.h5 – Annual transactive cleared quantities generate_case_config.json – Simulation config (provides indLoad path) rate_case_values_<scenario>.json – Tariff structure (read from tariff_path) default_case_config.json – Simulation defaults (provides LMP multiplier) DSO_CFS_Summary.csv – DSO expenses (optional; defaults to 1e10) Annual_DA_LMP_Load_data.csv – Annual DA LMP series (transactive/dsot/subscription) time_of_use_parameters.json – TOU period definitions (TOU/subscription only)
Key output files written per call to DSO_rate_making()
- bill_dso_<N>_data.h5 – Customer bill DataFrame (keys: cust_bill_data,
bill_sum_data)
cust_bill_dso_<N>_data.csv – Per-meter bill CSV billsum_dso_<N>_data.csv – Sectoral bill summary CSV rate_case_values_<scenario>.json – Updated tariff with cost-recovery prices time_of_use_parameters.json – Updated TOU/subscription prices (TOU/sub only)
- tesp_support.dsot.dso_rate_making.DSO_rate_making(case, base_case, dso_num, metadata, tariff_path, dso_scaling_factor, num_indust_cust, case_name='', rate_scenario=None, trans_cost_balance_method=None, include_RT=True)
Compute cost-recovery tariff prices and customer bills for one DSO.
This is the primary annual billing entry point. It orchestrates the full rate-making workflow in two steps:
- Step 1 – calculate_tariff_prices()
Solves for the volumetric (or fixed) price component that ensures the DSO recovers its total annual expenses. The solved prices are written back into the tariff dict and persisted to disk at tariff_path/rate_case_values_<scenario>.json.
- Step 2 – calculate_consumer_bills()
Applies the updated tariff prices to every billing meter to produce per-customer and per-sector bill DataFrames. Bills are written to HDF5 and CSV files in the case folder.
The surplus return value is the percentage difference between actual revenue (sum of all bills) and the DSO’s required expenses. A non-zero surplus on the first pass is expected and is eliminated by the two-pass workflow in run_annual_postprocessing.py. After the second pass, surplus should be near zero.
- Parameters:
case (str) – Absolute path to the annual case folder. This is the folder that contains energy_dso_<N>_data.h5, transactive_dso_<N>_data.h5, and generate_case_config.json.
base_case (str) – Absolute path to the demand-reference case folder. For non-subscription rates this is unused inside calculate_tariff_prices but is forwarded to calculate_consumer_bills (where it is only needed for the subscription scenario). Typically TOU_path or flat_path for the base case itself.
dso_num (int or str) – DSO/bus number. Converted to str internally; must correspond to a key in the loaded tariff dict (e.g. ‘DSO_1’).
metadata (dict) – GLD billing-meter metadata dictionary (from Substation_<N>_glm_dict.json) with tariff_class and cust_participating populated on each meter entry.
tariff_path (str) –
Absolute path to the shared metadata/tariff directory. The function loads from here:
rate_case_values_<scenario>.json – tariff structure
default_case_config.json – LMP multiplier setting
And reads from case/generate_case_config.json the filename of the bulk industrial load CSV, which it resolves under tariff_path.
dso_scaling_factor (float) – Ratio of actual DSO customers to simulated GLD customers. Bills are scaled by this factor when aggregating to sector totals.
num_indust_cust (int) – Number of industrial customers at this DSO node; used to scale the industrial fixed-charge total.
case_name (str, optional) – Case label for DSO+T legacy scenarios (e.g. ‘MR-BAU’). When non-empty, the tariff file is named rate_case_values_<case_name>.json; when empty (default), rate_scenario drives the filename.
rate_scenario (str, optional) – Rate scenario string. One of ‘flat’, ‘time-of-use’, ‘subscription’, ‘transactive’, ‘dsot’, or None (defaults to DSO+T).
trans_cost_balance_method (str, optional) – For transactive/dsot rates, selects which charge absorbs residual cost: None or ‘volumetric’ adjusts transactive_dist_rate; ‘fixed’ adjusts transactive_connection_charge. Defaults to None.
include_RT (bool) – If True, real-time energy charges are included in participating-customer bills. Set False to exclude RT corrections. Defaults to True.
- Returns:
- Nested revenue summary dict with flat/TOU/
subscription/transactive/DSO+T line items.
- DSO_Revenues_and_Energy_Sales (dict): Detailed revenue and energy-sold
summary including per-class breakdowns and effective cost.
- tariff (dict): Updated tariff structure with solved cost-recovery prices
(same object that was loaded from rate_case_values_*.json; also written back to disk at tariff_path).
- surplus (float): Revenue surplus as a percentage of required expenses:
(actual_revenue - required_expenses) / required_expenses * 100. Ideally near zero after the second pass.
- Return type:
DSO_Cash_Flows (dict)
- Files read:
case/energy_dso_<N>_data.h5 case/transactive_dso_<N>_data.h5 case/generate_case_config.json tariff_path/rate_case_values_<scenario>.json tariff_path/default_case_config.json tariff_path/<industrial_load_filename>
- Files written:
case/bill_dso_<N>_data.h5 (keys: cust_bill_data, bill_sum_data) case/cust_bill_dso_<N>_data.csv case/billsum_dso_<N>_data.csv tariff_path/rate_case_values_<scenario>.json (updated prices) case/time_of_use_parameters.json (TOU and subscription only)
- tesp_support.dsot.dso_rate_making.annual_energy(month_list, folder_prefix, dso_num, metadata)
Aggregate monthly per-meter energy HDF5 files into a single annual DataFrame.
This is the annual postprocessing counterpart to read_meters(). For each month in month_list it reads the energy_metrics_data.h5 and transactive_metrics_data.h5 files produced by the monthly read_meters() call and combines the monthly ‘sum’ columns into a single DataFrame where each column is one calendar month.
After concatenation, annual totals are computed: - ‘kw-hr’ and transactive quantities are summed across all months. - ‘max_kw’ is the maximum over all months (peak demand). - ‘avg_load’ is the mean over all months. - ‘load_factor’ is recomputed from the annual avg_load / max_kw.
- Parameters:
month_list (list) –
List of per-month descriptors. Each entry is a list with at least two elements:
[0] month_name (str): Short label (e.g. ‘Jan’), used as the column name in the output DataFrames.
[1] month_path (str): Absolute path to the monthly simulation folder that contains the Substation subfolder.
folder_prefix (str) – GLD Substation subfolder prefix (e.g. ‘/Substation_’).
dso_num (str) – DSO number as a string (e.g. ‘1’).
metadata (dict) – GLD billing-meter metadata used only to recompute ‘load_factor’ for each meter.
- Returns:
- Annual per-meter energy with one column
per month plus a ‘sum’ column.
year_energysum_df (pd.DataFrame): Annual sectoral energy totals. year_trans_sum_df (pd.DataFrame): Annual transactive quantities.
- Return type:
year_meter_df (pd.DataFrame)
- Required files (per month entry in month_list):
<month_path>/Substation_<N>/energy_metrics_data.h5 <month_path>/Substation_<N>/transactive_metrics_data.h5
- tesp_support.dsot.dso_rate_making.calculate_consumer_bills(case_path, base_path, metadata, meter_df, trans_df, energy_sum_df, tariff, dso_num, sf, num_ind_cust, rate_scenario, include_RT=True)
Compute per-meter and per-sector consumer bills given solved tariff prices.
This function is called after calculate_tariff_prices() has determined the cost-recovery tariff prices and updated the tariff dictionary. It iterates over every billing meter and applies the appropriate rate schedule depending on whether the customer is participating (transactive / TOU / subscription) or non-participating (flat rate).
Billing logic by rate scenario:
‘flat’: All customers pay flat rate regardless of participation.
- ‘time-of-use’: Participating customers pay TOU period prices; non-participating
customers pay the flat rate.
- ‘subscription’: Participating customers pay a block TOU energy charge on their
baseline demand plus a net deviation charge (actual vs baseline) priced at the real-time DA LMP + adder.
- ‘transactive’ / ‘dsot’: Participating customers pay DA/RT LMP-based charges
plus a volumetric distribution charge; non-participating pay flat.
Industrial loads are always calculated separately using the bulk industrial load totals from energy_sum_df rather than per-meter data.
Column naming dependency: meter_df, trans_df, and energy_sum_df are expected to have 3-character month-name columns (‘Jan’, ‘Feb’, ‘Mar’, etc.), because calculate_tariff_prices() renames them in-place before this function is called. tou_params season/period keys must match these 3-char names.
Subscription directory mapping: For the subscription rate, per-meter hourly demand profiles are loaded from monthly subfolders inside case_path and base_path. The function discovers these subfolders by listing case_path and matching entries whose 4th _-delimited token is a 2-digit month number (e.g. 8_rnd_2016_01_pv_bt_fl_ev → token ‘01’). The matching subfolder must also exist inside base_path.
- Parameters:
case_path (str) – Absolute path to the annual case folder. Used to read time_of_use_parameters.json, Annual_DA_LMP_Load_data.csv, and monthly demand profiles.
base_path (str) – Absolute path to the demand-reference case folder. Required only for the subscription rate (baseline demand).
metadata (dict) – GLD billing-meter metadata with tariff_class, cust_participating, building_type, etc. populated.
meter_df (pd.DataFrame) – Annual per-meter energy DataFrame with 3-char month columns (already renamed by calculate_tariff_prices).
trans_df (pd.DataFrame) – Annual transactive DataFrame (same column format).
energy_sum_df (pd.DataFrame) – Annual sectoral energy totals (same format).
tariff (dict) – Tariff structure with cost-recovery prices already written in by DSO_rate_making().
dso_num (str) – DSO number as a string (e.g. ‘1’).
sf (float) – Customer scaling factor for sectoral bill summation.
num_ind_cust (int) – Number of industrial customers at this DSO node.
rate_scenario (str) – One of ‘flat’, ‘time-of-use’, ‘subscription’, ‘transactive’, or ‘dsot’.
include_RT (bool) – If True, real-time energy charges are applied to participating customers. Defaults to True.
- Returns:
- Per-meter bill components with MultiIndex
(meter_name, bill_component); columns are 3-char months plus ‘sum’ and ‘volatility’.
- billsum_df (pd.DataFrame): Sectoral bill totals with MultiIndex
(load_type, bill_component).
- Return type:
bill_df (pd.DataFrame)
- Required external files:
time_of_use_parameters.json (case_path; TOU and subscription)
Annual_DA_LMP_Load_data.csv (case_path; subscription)
- Substation_<N>_baseline_demand_by_meter.h5 (base_path monthly subfolders;
subscription only)
- Substation_<N>_demand_by_meter.h5 (case_path monthly subfolders;
subscription only)
- tesp_support.dsot.dso_rate_making.calculate_tariff_prices(case_path, base_case_path, metadata, meter_df, trans_df, energy_sum_df, tariff, dso_num, sf, num_ind_cust, industrial_file, rate_scenario, trans_cost_balance_method=None, include_RT=True)
Solve for the tariff prices that allow the DSO to recover its annual expenses.
This function implements a closed-form cost-recovery solve for each rate scenario. The general approach is:
Read the DSO’s total annual expenses from DSO_CFS_Summary.csv via get_total_dso_costs(). If the file does not yet exist (first-pass postprocessing), a large placeholder value (1e10) is used, and the user must re-run after DSO_CFS_Summary.csv is produced.
Compute the revenue that fixed charges, demand charges, and any previously-known energy charges would already recover.
Solve algebraically for the remaining volumetric (or fixed) price that closes the gap between projected revenue and expenses.
The solved prices are returned in the prices dict and must be written back into the tariff structure by the user (DSO_rate_making).
Important side effect – DataFrame column rename: meter_df, energy_sum_df, and trans_df are renamed in-place so that their month-column names are truncated to 3 characters (e.g. ‘March’ → ‘Mar’, ‘August’ → ‘Aug’). Because DataFrames are passed by reference, the user’s objects are also renamed. calculate_consumer_bills() therefore receives already-renamed columns and must use the 3-char names when looking up tou_params. (TODO: remove this side effect once month names are standardised upstream.)
- Parameters:
case_path (str) – Absolute path to the annual case folder. Used to read DSO_CFS_Summary.csv, time_of_use_parameters.json, Annual_DA_LMP_Load_data.csv, and monthly subfolder demand profiles (subscription rate).
base_case_path (str) – Absolute path to the demand-reference case folder. Required only for the subscription rate, where per-meter baseline demand profiles are loaded from monthly subfolders here.
metadata (dict) – GLD billing-meter metadata with tariff_class and cust_participating populated on every meter entry.
meter_df (pd.DataFrame) – Annual per-meter energy DataFrame produced by annual_energy(). Mutated in-place (column rename).
trans_df (pd.DataFrame) – Annual transactive DataFrame from annual_energy(). Mutated in-place (column rename).
energy_sum_df (pd.DataFrame) – Annual sectoral energy totals from annual_energy(). Mutated in-place (column rename).
tariff (dict) – Loaded tariff structure (rate_case_values_*.json). Read-only inside this function; prices are returned separately.
dso_num (str) – DSO number as a string (e.g. ‘1’).
sf (float) – Customer scaling factor (simulated-to-actual ratio).
num_ind_cust (int) – Number of industrial customers at this DSO node.
industrial_file (str) – Absolute path to the bulk industrial load CSV.
rate_scenario (str) – One of ‘flat’, ‘time-of-use’, ‘subscription’, ‘transactive’, or ‘dsot’.
trans_cost_balance_method (str, optional) – For transactive/dsot rates, controls which charge component absorbs residual cost. None or ‘volumetric’ adjusts the volumetric distribution rate; ‘fixed’ adjusts the connection charge. Defaults to None.
include_RT (bool) – If True, real-time energy charges contribute to revenue in the transactive/dsot solve. Defaults to True.
- Returns:
- Solved price components, keyed by scenario:
’flat_rate’ for flat/TOU/subscription/transactive/dsot
’tou_rate_<season>’ for TOU (one key per season)
’subscription_rate_<season>’ for subscription
’transactive_volumetric_rate’ or ‘transactive_fixed_charge’
’dsot_volumetric_rate’
- dso_expenses (float or dict): Total DSO expenses used in the solve;
a dict keyed by season for TOU and subscription rate scenarios.
- Return type:
prices (dict)
- Required external files:
DSO_CFS_Summary.csv (case_path; optional, defaults to 1e10)
time_of_use_parameters.json (case_path; TOU and subscription)
Annual_DA_LMP_Load_data.csv (case_path; transactive, dsot, subscription)
- Substation_<N>_demand_by_meter.h5 (subscription; per-month in case_path and
base_case_path subfolders)
- tesp_support.dsot.dso_rate_making.calculate_tier_credit(dso_num, tariff_class, tariff, total_energy)
Calculate the tier credit added to the consumers’ bills from the declining-block rate. :param dso_num: A string specifying the number of the DSO being considered. :type dso_num: str :param tariff_class: Indicates the type of consumer that is under consideration. :type tariff_class: str :param tariff: A dictionary of pertinant tariff information. Includes information :type tariff: dict :param for the volumetric rates: :type for the volumetric rates: i.e., flat and time-of-use :param total_energy: Consumer’s total energy consumption for the month. :type total_energy: float
- Returns:
The tier credit that will be applied to the energy portion of the consumer’s bill.
- Return type:
tier_credit (float)
- tesp_support.dsot.dso_rate_making.create_baseline_demand_profiles_for_each_meter(demand_df, dso_num, type_of_baseline, save=False, save_path=None)
Creates a pandas DataFrame that contains hourly time-series data for each meter in a DSO. The data in this DataFrame is configured to be a baseline demand profile, determined according to a specified metric. The resultant DataFrame can be saved to a .h5 file if desired. :param demand_df: Monthly hourly demand data for each meter. :type demand_df: pandas.DataFrame :param dso_num: The number of a valid substation in the system model. :type dso_num: int :param type_of_baseline: The type of baseline demand that should be considered. :type type_of_baseline: str :param There are four types of baselines supported by this function: ‘daily’, :param ‘day_of_week’: :param ‘weekdays_and_weekends’: :param and ‘monthly’.: :param save: Indicates whether the output data should be saved in a .h5 :type save: bool :param file. If True: :param data is saved to the location specified by ‘save_path’.: :param save_path: File path that indicates where the resultant baseline demand :type save_path: str :param profile should be saved: :param if allowed by ‘save’.:
- Returns:
Monthly hourly baseline demand data for each meter.
- Return type:
bl_demand_df (pandas.DataFrame)
- tesp_support.dsot.dso_rate_making.create_demand_profiles_for_each_meter(dir_path, dso_num, day_range, save=False)
Creates a pandas DataFrame that contains hourly time-series data for each meter in a DSO. The resultant DataFrame can be saved to a .h5 file if desired. :param dir_path: Contains file path of daily power and voltage information for :type dir_path: str :param each meter in five-minute time steps.: :param dso_num: The number of a valid substation in the system model. :type dso_num: int :param day_range: List of day numbers in a month to be considered. :type day_range: list :param save: Indicates whether the output data should be saved in a .h5 :type save: bool :param file. If True: :param data is saved to the same location as what is provided in: :param ‘dir_path’.:
- Returns:
Monthly hourly demand data for each meter.
- Return type:
demand_df (pandas.DataFrame)
- tesp_support.dsot.dso_rate_making.get_cust_bill(cust, bill_df, bill_metadata, energy_df, rate_scenario)
Build an annual bill summary dictionary for a single billing meter.
Extracts the annual (‘sum’ column) bill components from bill_df for the specified customer and packages them into a nested dict that is easier to inspect and serialize than the raw DataFrame. The dict always contains flat-rate fields; scenario-specific fields (TOU, subscription, transactive, DSO+T) are added when rate_scenario matches.
This function is typically called once per DSO after DSO_rate_making() to generate a representative sample bill for diagnostic output. It does not write any files.
- Parameters:
cust (str) – Billing meter name (must be a key in bill_metadata[‘billingmeters’] and an index level in bill_df).
bill_df (pd.DataFrame) – Per-meter bill DataFrame returned by calculate_consumer_bills() (or read from bill_dso_<N>_data.h5, key ‘cust_bill_data’).
bill_metadata (dict) – GLD billing-meter metadata with building_type and tariff_class populated for each meter.
energy_df (pd.DataFrame) – Annual per-meter energy DataFrame returned by annual_energy() (or read from energy_dso_<N>_data.h5, key ‘energy_data’).
rate_scenario (str) – Rate scenario string (‘flat’, ‘time-of-use’, ‘subscription’, ‘transactive’, ‘dsot’, or None).
- Returns:
- Nested bill summary containing:
BillsFix: flat-rate energy, demand, and connection charges
EnergyQuantity: total annual kW-hr
MaxLoad: annual peak demand (kW)
LoadFactor: annual load factor
BlendedRate: effective $/kW-hr across all charges
RateDesign: the rate_scenario string
CustomerType: building_type and tariff_class
Volatility: monthly bill volatility (max-min)/mean
Additional scenario-specific keys (e.g. BillsTOU, BillsSubscription, BillsTransactive)
- Return type:
customer_annual_bill (dict)
- tesp_support.dsot.dso_rate_making.get_total_dso_costs(case_path, dso_num, rate_scenario, seasons_dict=None)
Read the DSO’s annual expenses from the CFS summary CSV.
This function provides the required-revenue target used by calculate_tariff_prices() to solve for cost-recovery prices. It reads capital and operating expenses from DSO_CFS_Summary.csv, which is produced by the dso_cfs step in run_annual_postprocessing.py.
Two-pass dependency: On the first postprocessing pass, DSO_CFS_Summary.csv does not yet exist, so this function returns a large placeholder (1e10 dollars) and logs a warning. The first-pass rates are therefore approximate. On the second pass, the file exists and real expenses are used, producing accurate cost-recovery prices.
For TOU and subscription scenarios, expenses are split by season using the seasons_dict argument, because each season has a separate price.
- Parameters:
case_path (str) – Absolute path to the annual case folder containing DSO_CFS_Summary.csv.
dso_num (str) – DSO number as a string (e.g. ‘1’). Used to select the ‘DSO_<N>’ column from the CSV.
rate_scenario (str) – Rate scenario string; determines whether expenses are returned as a scalar (flat/transactive/dsot) or a season-keyed dict (time-of-use/subscription).
seasons_dict (dict, optional) – For TOU and subscription rates, a dict mapping season labels to lists of 3-char month names (e.g. {‘summer’: [‘Jun’, ‘Jul’, ‘Aug’], ‘winter’: […]}). Required when rate_scenario is ‘time-of-use’ or ‘subscription’. Defaults to None.
- Returns:
- Total DSO annual expenses in dollars.
float: for flat, transactive, and dsot scenarios.
dict keyed by season label: for TOU and subscription.
Returns 1e10 (or 1e10 / num_seasons per season) when the CFS summary file is not available.
- Return type:
dso_expenses (float or dict)
- tesp_support.dsot.dso_rate_making.read_meters(metadata, dir_path, folder_prefix, dso_num, day_range, SF, dso_data_path, rate_scenario=None)
Compute per-meter energy and transactive metrics for a monthly day range.
This is the monthly postprocessing entry point. It reads raw GridLAB-D HDF5 files for each simulation day, aggregates energy consumption and day-ahead/real-time quantities, and writes the results to HDF5 files inside the GLD Substation subfolder. These files are later consumed by annual_energy() during annual postprocessing.
- Parameters:
metadata (dict) – GLD billing-meter metadata dictionary (from Substation_<N>_glm_dict.json). Must have tariff_class and cust_participating populated on each meter entry before this function is called.
dir_path (str) – Absolute path to the monthly simulation case folder (e.g. <case>/8_rnd_2016_01_pv_bt_fl_ev).
folder_prefix (str) – Substation subfolder prefix, e.g. ‘/Substation_’.
dso_num (str) – DSO/bus number as a string (e.g. ‘1’).
day_range (list) – 1-based simulation day indices to process (e.g. range(4, 32) for a January run excluding run-in days).
SF (float) – Scaling factor that converts simulated GLD load to the full DSO customer population (e.g. 1743).
dso_data_path (str) – Relative path (from dir_path’s parent) to the shared metadata directory containing bulk industrial load CSVs and TOU parameter JSON files. The function prefixes ‘../’ to this value when building file paths, so it must be a path fragment relative to one level above dir_path.
rate_scenario (str, optional) – Rate scenario string – ‘flat’, ‘time-of-use’ (or ‘TOU’), ‘subscription’, ‘transactive’, or ‘dsot’. Controls which additional TOU-period metrics are computed. Defaults to None.
- Returns:
- Per-meter monthly energy metrics with a
MultiIndex (meter_name, variable); columns are calendar dates plus ‘sum’.
- energysum_df (pd.DataFrame): Sectoral energy totals with MultiIndex
(load_type, variable); load_types are residential, commercial, industrial, total.
- Return type:
meter_df (pd.DataFrame)
- Side effects:
- Writes to dir_path + folder_prefix + dso_num:
energy_metrics_data.h5 (keys: energy_data, energy_sums)
transactive_metrics_data.h5 (key: trans_data)
Notes
Days for which Retail_Quantities.h5 has no key, or for which DA-LMP data is unavailable, are silently skipped with a logged warning.
The industrial bulk load file path is resolved as os.path.join(‘../’ + dso_data_path, <filename>). This is a relative construction that requires the user’s working directory to be one level above dso_data_path. If the working directory has changed (e.g. after prior os.chdir calls), this path may not resolve correctly.
tesp_support.dsot.ev_agent module
Class that controls the Electric Vehicle
Implements the optimum schedule of charging and discharging DA; generate the bids for DA and RT; monitor and supervisory control of GridLAB-D environment element.
- The function call order for this agent is:
initialize()
set_price_forecast(forecasted_price)
- Repeats at every hour:
formulate_bid_da() {return BID}
set_price_forecast(forecasted_price)
- Repeats at every 5 minutes:
set_SOC(msg_str) {updates C_init}
formulate_bid_rt() {return BID}
inform_bid(price) {update RTprice}
bid_accepted() {update inv_P_setpoint and GridLAB-D P_out if needed}
- class tesp_support.dsot.ev_agent.EVDSOT(diction, inv_properties, key, model_diag_level, sim_time, solver)
Bases:
objectThis agent manages the electric vehicle (ev)
- Parameters:
diction (dict) – electric vehicle parameters
inv_properties (dict)
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
solver (str)
- Initialize from Args
- name
name of this agent
- Type:
str
- Rc
rated charging power in kW for the battery
- Type:
float
- Rd
rated discharging power in kW for the battery
- Type:
float
- Lin
battery charging loss in %
- Type:
float
- Lout
battery discharging loss in %
- Type:
float
- Cmin
minimum allowable stored energy in kWh (state of charge lower limit)
- Type:
float
- Cmax
maximum allowable stored energy in kWh (state of charge upper limit)
- Type:
float
- Cinit
initial stored energy in the battery in kWh
- Type:
float
- capacity
battery capacity in kWh
- Type:
float
- batteryLifeDegFactor
constant to model battery degradation
- Type:
float
- windowLength
length of day ahead optimization period in hours (e.g. 48-hours)
- Type:
int
- dayAheadCapacity
% of battery capacity reserved for day ahead bidding
- Type:
float
- No initialization required
- bidSpread
this can be used to spread out bids in multiple hours. When set to 1 hour (recommended), it’s effect is none
- Type:
int
- P
location of P in bids
- Type:
int
- Q
location of Q in bids
- Type:
int
- f_DA
forecasted prices in $/kWh for all the hours in the duration of windowLength
- Type:
List[float]) (1 X windowLength
- RT_state_maintain
true if battery must maintain charging or discharging state for 1 hour
- Type:
bool
- RT_state_maintain_flag
not define at current hour (-1) charging (+1) discharging
- Type:
int
- RT_flag
if True, has to update GridLAB-D
- Type:
bool
- inv_P_setpoint
next GridLAB-D inverter power output
- Type:
float
- optimized_Quantity
Optimized quantity
- Type:
List[float]) (1 X Window Length
- #not used if not biding DA
- prev_clr_Quantity
cleared quantities (kWh) from previous market iteration for all hours
- Type:
List[float]) (1 X Window Length
- prev_clr_Price
cleared prices ($/kWh) from previous market iteration
- Type:
List[float]) (1 X windowLength
- BindingObjFunc
if True, then optimization considers cleared price, quantities from previous iteration in the objective function
- Type:
bool
- DA_cleared_price(price)
Set the DA_cleared_price attribute
- Parameters:
price (float) – cleared price in $/kWh
- DA_model_parameters(sim_time)
- DA_optimal_quantities()
Generates Day Ahead optimized quantities for agent
- Returns:
Optimal quantity from optimization for all hours of the window specified by windowLength
- Return type:
Quantity (float) (1 x windowLength)
- RT_fix_four_points_range(BID, Ql, Qu)
Verify feasible range of RT bid
- Parameters:
BID (float) ((1,2)X4) – 4 point bid
Ql
Qu
- Returns:
4 point bid only the feasible range
- Return type:
BIDr (float) ((1,2)X4)
- RT_gridlabd_set_P(sim_time)
Update variables for battery output “inverter”
- Parameters:
sim_time (str) – Current time in the simulation; should be human-readable
inv_P_setpoint is a float in W
- bid_accepted(current_time)
Update the P and Q settings if the last bid was accepted
- Returns:
True if the inverter settings changed, False if not.
- Return type:
bool
- con_rule_eq1(m, i)
- con_rule_eq2(m, i)
- con_rule_eq3(m, i)
- con_rule_eq4(m, i)
- con_rule_ine1(m, i)
- con_rule_ine2(m, i)
- formulate_bid_da()
Formulate 4 points of P and Q bids for the DA market
Function calls “DA_optimal_quantities” to obtain the optimal quantities for the DA market. With the quantities, the 4 point bids are formulated.
Before returning the BID the function resets “RT_state_maintain_flag” which, if RT_state_maintain is TRUE, the battery will be forced to keep its state (i.e., charging or discharging).
- Returns:
store last DA market bids
- Return type:
BID (float) (((1,2)X4) X windowLength)
- formulate_bid_rt()
Formulates RT bid
Uses the last 4 point bid from DA market and consider current state of charge of the battery. Will change points to change points for feasible range of Qmin Qmax points if necessary. Furthermore, allows a maximum deviation of +/-100% from the DA plan.
- Returns:
bid in Real Time market
- Return type:
realTimeBid (float) ((1,2) x 4)
- from_P_to_Q_battery(BID, PRICE)
Convert the 4 point bids to a quantity with the known price
- Parameters:
BID (float) ((1,2)X4) – 4 point bid
PRICE (float) – cleared price in $/kWh
- Returns:
active power (-) charging (+) discharging
- Return type:
_quantity (float)
- get_car_home_duration(cur_secs, interval)
Return the duration of car at home during the given ‘interval’ seconds starting from cur_secs
- Parameters:
cur_secs – (seconds) current (starting) time with reference of midnight as 0
interval – (seconds) duration in which status needs to be estimated
- Returns:
duration in seconds for which car is at home in given interval
- get_uncntrl_ev_load(sim_time)
Function returns 48-hour forecast of ev load in base case w/o optimization
- Parameters:
sim_time (datetime)
- Returns:
48-hour forecast of ev load in base case w/o optimization
- Return type:
list
- inform_bid(price)
Set the cleared_price attribute
- Parameters:
price (float) – cleared price in $/kWh
- is_car_home(cur_secs)
Is the Car is at home
- Parameters:
cur_secs – current time in seconds
- Returns:
if car is at home at cur_secs is True or otherwise False
- Return type:
bool
- is_car_leaving_home(cur_secs, interval)
Tells if car is leaving from home during the given ‘interval’
- Parameters:
cur_secs – (seconds) current (starting) time with reference of midnight as 0
interval – (seconds) duration in which status needs to be estimated
- Returns:
- if car is leaving from home during the given ‘interval’
seconds starting from cur_secs is True or otherwise False
- Return type:
bool
- obj_rule(m)
- set_SOC(msg_str, 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
sim_time (str) – Current time in the simulation; should be human-readable
- set_price_forecast(forecasted_price)
Set the f_DA attribute
- Parameters:
forecasted_price (float x 48) – cleared price in $/kWh
- test_function()
Test function with the only purpose of returning the name of the object
- tesp_support.dsot.ev_agent.test()
Testing
Makes a single agent and run DA
tesp_support.dsot.forecasting module
Class responsible for forecasting
Implements the substation level DA price forecast and load forecast. Accesses forecast data using the schedule server; see “schedule_server.py” for further implementation details.
- class tesp_support.dsot.forecasting.Forecasting(port, config_Q)
Bases:
objectThis 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
- Parameters:
datafr (DataFrame) – dataframe created with the schedule name for a year
N_skew (int) – number of seconds to skew either (+ or -)
N_scalar (int) – scalar multiplier
- calc_solar_flux(cpt, day_of_yr, lat, sol_time, dnr_i, dhr_i, vertical_angle)
- calc_solargain(day_of_yr, time, dnr, dhr, lat, lon, tz_offset)
- correcting_Q_forecast_10_AM(Q_10_AM, offset, day_of_week)
Corrects the quantity submitted to the wholesale market at 10 AM
- Parameters:
Q_10_AM (list of 24 float) – DA quantities
- Returns:
Corrected 10 AM Quantities
- forecasting_schedules(name, time, len_forecast=48)
- get_internal_gain_forecast(skew_scalar, time, extra_forecast_hours=0)
Forecast the electric zip_load and internal gain of all zip loads of a house by reading schedule files and applying skew. Forecast is for 48-hours ahead from start time :param skew_scalar: dictionary containing ‘zip_skew’, ‘zip_scalar’ and ‘zip_heatgain_fraction’ for each zip load :param ‘zip_skew’ is a scalar and same for all type of zip loads for the given house. ‘zip_scalar’ and ‘zip_heatgain_fraction’: :param are dictionary containing different values for each type 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 zip 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 loaded
- 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(message: str)
Set the 48-hour solar diffuse forecast :param param message: solar_diffuse_forecast ([float x 48]):
- set_solar_direct_forecast(message: str)
Set the 48-hour solar direct forecast :param param message: solar_direct_forecast ([float x 48]):
- set_temperature_forecast(message: str)
Set the 48-hour temperature forecast
- Parameters:
message – 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)
This version of glm_dict is deprecated as it does not utilize GLMModifier() and instead relies on the .glm to be written with serialized print statements that can be read and interpreted line-by-line. Modern .glm files are no longer written this way and therefore this dictionary method will be inaccurate if used with the new gld_feeder_generator.py or any modern .glm-writing script.
- This renamed glm_dict_line() was written to work with:
prepare_case_dsot.py
residential_feeder_glm.py
commercial_feeder_glm.py
copperplate_feeder_glm.py
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.glm_diction(case_name, feed_key)
Writes the JSON metadata file with the feeder information. Utilizes GLMModifier() to read and parse through the .glm
- Parameters:
case_name (str) – name of the test case
feed_key (str) – feeder number
- 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:
objectAccumulates 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:
IntEnumDescribes the operating mode of the HVAC
- COOLING = 0
- HEATING = 1
- class tesp_support.dsot.helpers_dsot.MarketClearingType(value)
Bases:
IntEnumDescribes 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, config=None, 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
config (dict) – new configuration of the system for 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, config=None, 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
config (dict) – new configuration of the system for 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, out_path, gld_debug, run_post)
- tesp_support.dsot.helpers_dsot.write_mircogrids_management_script(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:
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:
objectThis 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(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:
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
- 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(sim_time)
Sets the ETP parameters from configuration data
- Parameters:
sim_time (str) – Current time in the simulation; should be human-readable
References
- change_basepoint(sim_time)
Updates the time-scheduled thermostat setting
- Parameters:
sim_time (str) – Current time in the simulation; should be human-readable
- Returns:
True if the setting changed, False if not
- Return type:
bool
- con_rule_eq1(m, t)
- formulate_bid_da()
Formulate windowLength hours 4 points PQ bid curves for the DA market
Function calls DA_optimal_quantities to obtain the optimal quantities for the DA market. With the quantities, a 4 point bids are formulated for each hour.
- Returns
BID (float) (windowLength X 4 X 2): DA bids to be sent to the retail DA market
- formulate_bid_rt(sim_time)
Bid to run the air conditioner through the next period for real-time
- Parameters:
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 solar gain without solar gain factor
- Parameters:
climate_conf – latitude and longitude info in a dict
current_time – the time for which solar gain needs to be estimated
- 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)
- sanity_checks()
- set_air_temp(message, sim_time)
Sets the air_temp attribute
- Parameters:
message (str) – Message with temperature in degrees Fahrenheit
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(message: str)
Sets the house_load attribute, if greater than zero
- Parameters:
message (str) – Message with load in kW
- set_humidity(message: str)
Sets the humidity attribute
- Parameters:
message (str) – Message with humidity
- set_humidity_forecast(message)
Set the 48-hour humidity_forecast so that it can be used for forcasting
- Parameters:
message – humidity forecast ([float x 48]): predicted humidity in relative percent
- set_hvac_load(message: str)
Sets the hvac_load attribute, if greater than zero
- Parameters:
message (str) – Message with load in kW
- set_hvac_state(message: str)
Sets the hvac_on attribute
- Parameters:
message (str) – Message with state, ON or OFF
- set_internalgain_forecast(internalgain_forecast)
Set the 48-hour internalgain_forecast variable so that it can be used for forcasting
- Parameters:
internalgain_forecast – internal gain forecast ([float x 48]): forecasted internal gain in BTu/h
- set_price_forecast(price_forecast)
Set the 24-hour price forecast and calculate price mean, std_dev and delta
- Parameters:
price_forecast ([float x 24]) – predicted price in $/kwh
- set_solar_diffuse(message: str)
Sets the solar diffuse attribute, if greater than zero
- Parameters:
message (str) – Message with solar irradiance
- set_solar_direct(message: str)
Sets the solar irradiance attribute, if greater than zero
- Parameters:
message (str) – Message with solar irradiance
- set_solargain_forecast(solargain_forecast)
Set the 48-hour solargain_forecast variable so that it can be used for forcasting
- Parameters:
solargain_forecast – solar gain forecast ([float x 48]): forecasted solar gain in BTu/(h*sf)
- set_temperature(message: str)
Sets the outside temperature attribute
- Parameters:
message (str) – Message with outdoor temperature in F
- set_temperature_forecast(message)
Set the 48-hour price forecast and calculate min and max
- Parameters:
message – temperature_forecast ([float x 48]): predicted temperature in F
- set_time(minute, hour, day)
Sets the current hour and minute
- Parameters:
minute (int) – the minute of the hour from 0 to 59
hour (int) – the hour of the day, from 0 to 23
day (int) – the day of the week, zero being Monday
- set_voltage(message: str)
Sets the mtr_v attribute
- Parameters:
message (str) – Message with meter line-neutral voltage
- set_wh_load(message: str)
Sets the wh_load attribute, if greater than zero
- Parameters:
message (str) – Message with load in kW
- set_zipload_forecast(forecast_ziploads)
Set the 48-hour forecast_ziploads variable so that it can be used for forcasting
- Parameters:
forecast_ziploads – array of zipload forecast
- store_full_internalgain_forecast(full_internalgain_forecast)
Sets the full_internalgain_forecast variable so that it can be used for forcasting
- Parameters:
full_internalgain_forecast – internal gain forecast to store for future
- store_full_zipload_forecast(full_forecast_ziploads)
Sets the full_forecast_ziploads variable so that it can be used for forcasting
- Parameters:
full_forecast_ziploads – zip load forecast to store for future
- 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:
EnumAn enumeration.
- FIVE_MINUTE = 1
- HOUR = 0
- tesp_support.dsot.load_less_solar.create_8_node_load_less_solar(dso_meta, load_dir, input_load_filename, output_load_filename)
Using information in the dso_meta dictionary, this function aggregates the 200-bus load-less-solar values into the 8-bus values. The resulting dataset is written out to file.
- Parameters:
dso_meta – DSO metadata defining how 200-node buses map to 8-node buses
load_dir – Directory with input load data file
input_load_filename – Filename only, no path
output_load_filename – Filename only, no path
- Returns:
(none)
- tesp_support.dsot.load_less_solar.create_load_less_solar(input_load_filename, output_load_filename, solar_dir, load_dir, mode)
Hourly data is used for the DA market and needs to subtract the distributed generation solar forecast. 5-minute data is RT and needs to subtract the actual solar production.
- Sample hourly load data:
Hour_End,Bus0,Bus1,Bus2,Bus3,Bus4,Bus5,Bus6,… 12/29/2015 0:00,3659.8,248.49,1652,4415.4,201.28,50.374,83.668,… 12/29/2015 1:00,3659.8,248.49,1652,4415.4,201.28,50.374,83.668,… 12/29/2015 2:00,3603.9,246.54,1626.8,4348,198.2,49.784,82.688,… 12/29/2015 3:00,3577.2,246.19,1614.8,4315.8,196.74,49.431,… 12/29/2015 4:00,3595.8,247.46,1623.1,4338.1,197.76,49.543,… 12/29/2015 5:00,3666,249.03,1654.8,4422.9,201.62,50.085,83.188,… 12/29/2015 6:00,3795.8,253.74,1713.4,4579.4,208.75,51.893,… 12/29/2015 7:00,3931.7,260.87,1774.8,4743.5,216.23,53.583,…
- Sample hourly DSO distributed solar forecast data:
0 0 0 0 0 0 0 0 1.079 2.518 3.499 6.463
- Sample 5-minute load data:
Seconds,Bus1,Bus2,Bus3,Bus4,Bus5,Bus6,Bus7,Bus8, 0,3659.8,248.5,1652,4415.4,201.3,50.4,83.7,145.1 300,3659.8,248.5,1652,4415.4,201.3,50.4,83.7,145.1 600,3659.8,248.5,1652,4415.4,201.3,50.4,83.7,145.1 900,3659.8,248.5,1652,4415.4,201.3,50.4,83.7,145.1 1200,3659.8,248.5,1652,4415.4,201.3,50.4,83.7,145.1
- Sample 5-minute solar data:
12/29/15 0:00,0 12/29/15 0:05,0 12/29/15 0:10,0 12/29/15 0:15,0 12/29/15 0:20,0 12/29/15 0:25,0 12/29/15 0:30,0 12/29/15 0:35,0 12/29/15 0:40,0 12/29/15 0:45,0 12/29/15 0:50,0 12/29/15 0:55,0 12/29/15 1:00,0
- Parameters:
load_filename – Filename of input load data
solar_dir – Directory of input solar data
load_dir – Directory of input load data
- Returns:
list of list of load data less solar
- Return type:
load_data
- tesp_support.dsot.load_less_solar.data(self, message, *args, **kws)
- tesp_support.dsot.load_less_solar.parse_DSO_metadata_Excel(dso_metadata_path_Excel, worksheet_name)
This function parses the DSO metadata which is contained in a JSON and Excel files. Most of the metadata is in the JSON but one crucial piece of information is in the Excel file: the mapping of the 200-node to 8-node buses.
- Sample of the bus-generator file: (Note the first columns is empty)
- 200 bus 8 bus
1 1 2 1 3 1 4 1 5 1 6 1 …
- Parameters:
dso_metadata_path_Excel (str)
parsed. (containing the metadata to be)
worksheet_name (str)
metadata (containing the)
- Returns:
dso_meta (list of dicts) - One dictionary per DSO with appropriate metadata captured.
- tesp_support.dsot.load_less_solar.read_load_file(load_path)
- Parameters:
load_path – Path to load file that is being read in
- Returns:
list of lists with the headers and load data
- Return type:
load_data
- tesp_support.dsot.load_less_solar.write_out_load_file(load_data, out_path)
Writes out load data to CSV file. Assumes a list of lists format.
- Parameters:
load_data – Load data to be written to CSV.
out_path – Path and filename of output file
Returns:
tesp_support.dsot.map_results module
- tesp_support.dsot.map_results.bulk_system_map_plot(dataPath, configPath, shapePath, case_config_path, case_config_name, day_range, hour, contour_index, ercot200, realtime, showplot=False, plotdata=True, dispatchgenonly=True)
Creates a comparison of change in energy consumption and amenities for all customers
- Returns:
saves plot to file.
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.
- Parameters:
dso (int) – the DSO that the data should be plotted for (e.g. ‘1’)
day_range (range) – the day range to plotted.
case (str) – folder extension of case of interest
gld_prefix (str) – folder extension for GridLAB-D data
metadata_path (str) – path of folder containing metadata
- Returns:
saves dso DER loads data to file
- tesp_support.dsot.plots.der_stack_plot(dso_range, day_range, metadata_path, case, comp=None, plot_ref=False)
For a specified dso range and day range this function will load in the required data, plot the stacked DER loads and save the plot to file. :param dso_range: the DSO range that should be plotted. :type dso_range: list :param day_range: the day range to plotted. :type day_range: range :param metadata_path: path of folder containing metadata :type metadata_path: str :param case: folder extension of case of interest :type case: str :param comp: folder extension for reference case to be plotted in comparison :type comp: str :param plot_ref: If True will plot line of reference data (currently 2016 ERCOT loads) :type plot_ref: Bool
- Returns:
saves hdf and csv data files of combined dso data saves DER stack plot to file
- tesp_support.dsot.plots.df_reduction(df, subsystem, variable, format)
This utility slices a dataframe based on the subsystem (or aggregation) of interest. This is used for agent or house data where there is multiple house data per timestep and reduction is needed before plotting data. :param df: dataframe to be reduced :type df: dataframe :param subsystem: the individual house to be plotted (e.g. ‘HousesA_hse_1’) or the operator to be used if :type subsystem: str :param aggregating many houses: :type aggregating many houses: e.g. ‘sum’, ‘mean’ :param variable: variable to be plotted from system dataframe (e.g. ‘cooling_setpoint’ or ‘real_power_avg’) :type variable: str :param format: flag as to whether the data is GridLAB-D (‘gld’) or agent (‘agent’) as the format is slightly different. :type format: str
- Returns:
reduced dataframe
- Return type:
df (dataframe)
- tesp_support.dsot.plots.dso_comparison_plot(dso_range, system, subsystem, variable, day, case, agent_prefix, gld_prefix)
For a specified dso range, system, variable, and day this function will load in the required data, plot the variable for all DSOs and save the plot to file. :param dso_range: the DSO range that the data should be plotted for :type dso_range: range :param system: the system to be plotted (e.g. ‘substation’, ‘house’, ‘HVAC_agent’) :type system: str :param subsystem: the individual house to be plotted (e.g. ‘HousesA_hse_1’) or the operator to be used if :type subsystem: str :param aggregating many houses: :type aggregating many houses: e.g. ‘sum, ‘mean’ :param variable: variable to be plotted from system dataframe (e.g. ‘cooling_setpoint’ or ‘real_power_avg’) :type variable: str :param day: the day to plotted. :type day: str :param case: folder extension of case of interest :type case: str :param agent_prefix: folder extension for agent data :type agent_prefix: str :param gld_prefix: folder extension for GridLAB-D data :type gld_prefix: str
- Returns:
saves dso comparison plot to file
- tesp_support.dsot.plots.dso_forecast_stats(dso_range, day_range, case, dso_metadata_file, ercot_dir)
For a specified dso range and day range this function will load in the required data, plot forecast errors for all for DSOs and save the plots to file. :param dso_range: the DSO range that the data should be plotted for :type dso_range: list :param day_range: the day to plotted. :type day_range: range :param case: folder extension of case of interest :type case: str :param dso_metadata_file: path and file name of the dso metadata file :type dso_metadata_file: str :param ercot_dir: path location of the ercot and industial load metadata :type ercot_dir: str
- Returns:
saves dso comparison plot to file
- tesp_support.dsot.plots.dso_lmp_stats(month_list, output_path, renew_forecast_file, dso_range)
For a specified dso range and list of month path information this function will load in the required data, and summarize DSO LMPs versus loads for all months, and plot comparisons. :param month_list: list of lists. Each sub list has month name (str), directory path (str) :type month_list: list :param output_path: path of the location where output (plots, csv) should be saved :type output_path: str :param renew_forecast_file: path and name of ercot renewable generation forecast csv file :type renew_forecast_file: str
- Returns:
saves dso load comparison plots to file saves csv of RT and DA loads and LMPs to file
- tesp_support.dsot.plots.dso_load_stats(dso_range, month_list, data_path, metadata_path, plot=False)
For a specified dso range and list of month path information this function will load in the required data, and summarize DSO loads for all months, plot comparisons, and find Qmax. :param dso_range: the DSO range that the data should be plotted for :type dso_range: list :param month_list: list of lists. Each sub list has month name (str), directory path (str) :type month_list: list :param data_path: path of the location where output (plots, csv) should be saved :type data_path: str :param metadata_path: location of ercot load data :type metadata_path: str
- Returns:
saves dso load comparison plots to file saves summary of Qmax for each DSO to file
- tesp_support.dsot.plots.dso_market_plot(dso_range, day, case, dso_metadata_file, ercot_dir, comp_case=None)
For a specified dso range and day this function will load in the required data, plot standard market price and quantity values all for DSOs and save the plots to file. :param dso_range: the DSO range that the data should be plotted for :type dso_range: list :param day: the day to plotted. :type day: str :param case: folder extension of case of interest :type case: str :param dso_metadata_file: path and file name of the dso metadata file :type dso_metadata_file: str :param ercot_dir: path location of the ercot and industial load metadata :type ercot_dir: str
- Returns:
saves dso comparison plot to file
- tesp_support.dsot.plots.find_edge_cases(dso, base_case, day_range, agent_prefix, gld_prefix)
For a specified dso and case this function will return the day associated with a range of ‘edge cases’ for example the hottest day or biggest swing in prices. :param dso: the DSO that the data should be plotted for (e.g. ‘1’) :type dso: str :param base_case: folder extension of case of interest :type base_case: str :param day_range: range of days to be summed (for example a month) :type day_range: list :param agent_prefix: folder extension for agent data :type agent_prefix: str :param gld_prefix: folder extension for GridLAB-D data :type gld_prefix: str
- Returns:
dataframe with values for each day dictionary of worst values. saves values to file
- tesp_support.dsot.plots.generation_load_profiles(dir_path, metadata_path, data_path, day_range, use_ercot_fuel_mix_data=False, comp=None)
For a specified day range this function plots the stacked profiles of all generators (by fuel type) along with load plots. :param dir_path: path locating the AMES data file :type dir_path: str :param metadata_path: path locating the ERCOT load profile 5 minute data :type metadata_path: str :param data_path: path to the folder containing the plots sub folder :type data_path: str :param day_range: range of starting day and ending day of plot :type day_range: range :param use_ercot_fuel_mix_data: If True plots 2016 actual ERCOT data, if False plots AMES RT data. :type use_ercot_fuel_mix_data: bool :param comp: folder path containing the generation data for the comparison case. Set to None for no comparison :type comp: str
- Returns:
saves plots to file
- tesp_support.dsot.plots.generation_statistics(dir_path, config_dir, config_file, day_range, use_gen_data=True)
For a specified day range this function plots the stacked profiles of all generators (by fuel type) along with load plots. :param dir_path: path locating the AMES data file :type dir_path: str :param config_dir: path locating the case config file :type config_dir: str :param config_file: name of the case config file :type config_file: str :param day_range: range of starting day and ending day of plot :type day_range: range :param use_gen_data: if True uses dispatched generator performance from PyPower. If False uses dispatched :type use_gen_data: bool :param AMES performance:
- Returns:
saves plots to file
- tesp_support.dsot.plots.get_date(dir_path, dso, day)
Utility to return start time (datetime format) of simulation day (str) in question
- tesp_support.dsot.plots.get_day_df(dso, system, subsystem, variable, day, case, agent_prefix, gld_prefix)
This utility loads and returns a dataframe for the desired variable for the day and dso in question. :param dso: the DSO that the data should be plotted for (e.g. ‘1’) :type dso: str :param system: the system to be plotted (e.g. ‘substation’, ‘house’, ‘HVAC_agent’) :type system: str :param subsystem: the individual house to be plotted (e.g. ‘HousesA_hse_1’) or the operator to be used if :type subsystem: str :param aggregating many houses: :type aggregating many houses: e.g. ‘sum, ‘mean’ :param variable: variable to be plotted from system dataframe (e.g. ‘cooling_setpoint’ or ‘real_power_avg’) :type variable: str :param day: the day to plotted. :type day: str :param case: folder extension of case of interest :type case: str :param agent_prefix: folder extension for agent data :type agent_prefix: str :param gld_prefix: folder extension for GridLAB-D data :type gld_prefix: str
- Returns:
reduced dataframe
- Return type:
df (dataframe)
- tesp_support.dsot.plots.get_house_schedules(agent_metadata, gld_metadata, house_name)
Utility to get schedules directly from the agent dictionary. This allows evaluation of schedules prior to agent control. :param agent_metadata: dictionary of agent metadata :type agent_metadata: dict :param gld_metadata: dictionary of gld metadata :type gld_metadata: dict :param house_name: name of GLD house object schedules are wanted for :type house_name: str
- Returns:
dictionary of schedules in list form
- Return type:
schedules (dict)
- tesp_support.dsot.plots.heatmap_plots(dso, system, subsystem, variable, day_range, case, agent_prefix, gld_prefix)
For a specified day, system, variable, and day_range this function will load in the required data, manipulate the dataframe into the required shape, plot the heatmap and save the heatmap to file. :param dso: the DSO that the data should be plotted for (e.g. ‘1’) :type dso: str :param system: the system to be plotted (e.g. ‘substation’, ‘house’, ‘HVAC_agent’) :type system: str :param subsystem: the individual house to be plotted (e.g. ‘HousesA_hse_1’) or the operator to be used if :type subsystem: str :param aggregating many houses: :type aggregating many houses: e.g. ‘sum, ‘mean’ :param variable: variable to be plotted from system dataframe (e.g. ‘cooling_setpoint’ or ‘real_power_avg’) :type variable: str :param day_range: range of the day indexes to be plotted. Day 1 has an index of 0 :type day_range: range :param case: folder extension of case of interest :type case: str :param agent_prefix: folder extension for agent data :type agent_prefix: str :param gld_prefix: folder extension for GridLAB-D data :type gld_prefix: str
- Returns:
saves heatmap to file
- tesp_support.dsot.plots.house_check(dso_range, sourceCase, targetCase, houseProperties)
Main function of the module.
- Parameters:
argv – Command line arguments given as: -d <Substation/DSO number to be analyzed> -s <source case folder name> -t <target case folder name> -p <property to compare by plots>
- Return type:
None
- tesp_support.dsot.plots.limit_check(log_list, dso_num, system, variable, day_range, base_case, agent_prefix, GLD_prefix, max_lim, min_lim)
For a specified dso, system, variable, and day_range this function will the time and place of the value that most exceeds upper and lower limits. A text description will be added to a log list and returned. :param log_list: list of limit excursions that will be added to. :type log_list: list :param dso_num: the DSO that the data should be plotted for (e.g. ‘1’) :type dso_num: str :param system: the system to be checked (e.g. ‘substation’, ‘house’, ‘HVAC_agent’) :type system: str :param variable: variable to be checked from system dataframe (e.g. ‘cooling_setpoint’ or ‘real_power_avg’) :type variable: str :param day_range: range of the day indexes to be checked. Day 1 has an index of 0 :type day_range: range :param base_case: folder extension of case of interest :type base_case: str :param agent_prefix: folder extension for agent data :type agent_prefix: str :param GLD_prefix: folder extension for GridLAB-D data :type GLD_prefix: str :param max_lim: upper value that variable should not exceed during simulation :type max_lim: float :param min_lim: lower value that variable should not exceed during simulation :type min_lim: float
- Returns:
saves heatmap to file
- tesp_support.dsot.plots.load_agent_data(dir_path, folder_prefix, dso_num, day_num, agent_name)
Utility to open h5 files for agent data.
- Parameters:
dir_path (str) – path of parent directory where DSO folders live
folder_prefix (str) – prefix of DSO folder name (e.g. ‘/TE_base_s’)
dso_num (str) – number of the DSO folder to be opened
day_num (str) – simulation day number (1 = first day of simulation)
agent_name (str) – name of agent data to load (e.g. ‘house’, ‘substation’, ‘inverter’, ‘retail site’ etc)
- Returns:
dataframe of system metadata agent_df: dataframe of agent timeseries data
- Return type:
agent_meta_df
- tesp_support.dsot.plots.load_ames_data(dir_path, day_range)
Utility to open AMES csv file.
- Parameters:
dir_path (str) – path of directory where AMES data lives
day_range (range) – range of simulation days for data to be returned
- Returns:
dataframe of AMES data
- Return type:
data_df
- tesp_support.dsot.plots.load_da_retail_price(dir_path, folder_prefix, dso_num, day_num, retail=True)
Utility to return day ahead cleared retail price. Data corresponds to 10am bid day before mapped to actual datetime when the energy will be consumed. :param dir_path: path of parent directory where DSO folders live :type dir_path: str :param folder_prefix: prefix of DSO folder name (e.g. ‘/TE_base_s’) :type folder_prefix: str :param dso_num: number of the DSO folder to be opened :type dso_num: str :param day_num: simulation day number (1 = first day of simulation) :type day_num: str
- Returns:
dataframe of cleared DA retail price
- Return type:
retail_da_data_df
- tesp_support.dsot.plots.load_duration_plot(dso, system, subsystem, variable, day, case, comp, agent_prefix, gld_prefix)
For a specified dso, system, variable, and day this function will load in the required data, plot the load duration profile and save the plot to file. NOTE: currently for one day = should extend to a day-range. :param dso: the DSO that the data should be plotted for (e.g. ‘1’) :type dso: str :param system: the system to be plotted (e.g. ‘substation’, ‘house’, ‘HVAC_agent’) :type system: str :param subsystem: the individual house to be plotted (e.g. ‘HousesA_hse_1’) or the operator to be used if :type subsystem: str :param aggregating many houses: :type aggregating many houses: e.g. ‘sum, ‘mean’ :param variable: variable to be plotted from system dataframe (e.g. ‘cooling_setpoint’ or ‘real_power_avg’) :type variable: str :param day: the day to plotted. :type day: str :param case: folder extension of case of interest :type case: str :param comp: folder extension of a comparison case of interest. Optional - set to None to show just one case. :type comp: str :param agent_prefix: folder extension for agent data :type agent_prefix: str :param gld_prefix: folder extension for GridLAB-D data :type gld_prefix: str
- Returns:
saves load duration plot to file
- tesp_support.dsot.plots.load_ercot_data(ercot_metadata_file, sim_start, day_range)
Utility to open ercot csv file.
- Parameters:
ercot_metadata_file (str) – path of where the ercot_metadata_file lives
sim_start (datetime) – start time of the simulation (from generate_case_config.json)
day_range (range) – range of simulation days for data to be returned
- Returns:
dataframe of ERCOT 2016 fuel mix data
- Return type:
data_df
- tesp_support.dsot.plots.load_ercot_fuel_mix(metadata_path, dir_path, day_range)
Utility to open AMES csv file.
- Parameters:
metadata_path (str) – path of directory where ERCOT Fuel mix data lives
dir_path (str) – path of directory where AMES data lives
day_range (range) – range of simulation days for data to be returned
- Returns:
dataframe of AMES data
- Return type:
data_df
- tesp_support.dsot.plots.load_gen_data(dir_path, gen_name, day_range)
Utility to open h5 files for generator data.
- Parameters:
dir_path (str) – path of parent directory where DSO folders live
gen_name (str) – name of generator (e.g. ‘’)
day_range (range) – range of days to be summed (for example a month)
- Returns:
dataframe of system metadata
- Return type:
gen_data_df (dataframe)
- tesp_support.dsot.plots.load_indust_data(indust_file, day_range)
Utility to open industrial load csv file.
- Parameters:
indust_file (str) – path and filename where the industrial csv load lives
day_range (list) – range of simulation days for data to be returned
- Returns:
dataframe of industrial loads per DSO bus
- Return type:
data_df
- tesp_support.dsot.plots.load_json(dir_path, file_name, use_cache=True)
Utility to open Json files. :param dir_path: location of json file :type dir_path: str :param filename: name json file :type filename: str :param use_cache: set true to use cache. False to avoid cache (important to use for :type use_cache: bool :param files updated and accessed multiple times in analysis - e.g.: :param TOU_parameters):
- Returns:
json file contents
- Return type:
output
- 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_surcharge_data(dir_path, gen_name, day_range)
- tesp_support.dsot.plots.load_system_data(dir_path, folder_prefix, dso_num, day_num, system_name)
Utility to open GLD created h5 files for systems’ data. :param dir_path: path of parent directory where DSO folders live :type dir_path: str :param folder_prefix: prefix of DSO folder name (e.g. ‘/TE_base_s’) :type folder_prefix: str :param dso_num: number of the DSO folder to be opened :type dso_num: str :param day_num: simulation day number (1 = first day of simulation) :type day_num: str :param system_name: name of system data to load (e.g. ‘house’, ‘substation’, ‘inverter’ etc) :type system_name: str
- Returns:
dataframe of system metadata system_df: dataframe of system timeseries data
- Return type:
system_meta_df
- tesp_support.dsot.plots.load_weather_data(dir_path, folder_prefix, dso_num, day_num)
Utility to open weather dat files and find day of data
- Parameters:
dir_path (str) – path of parent directory where DSO folders live
folder_prefix (str) – prefix of DSO folder name (e.g. /DSO_)
dso_num (str) – number of the DSO folder to be opened
day_num (str) – simulation day number (1 = first day of simulation)
- Returns:
dataframe of weather data for simulation day requested
- Return type:
weather_df
- tesp_support.dsot.plots.metadata_dist_plots(system, sys_class, variable, dso_range, case, data_path, metadata_path, agent_prefix)
For system, class, and dso_range this function will load in the required data, and plot a histogram of the population distribution. :param system: the system to be plotted (e.g. ‘house’) :type system: str :param sys_class: the subclass to be plotted (e.g. ‘SINGLE_FAMILY’). If system has no subsystems or you want to :type sys_class: str :param see the full population set equal to None: :param variable: variable to be plotted from system dataframe (e.g. ‘sqft’) :type variable: str :param dso_range: range of the DSOs to be plotted. DSO 1 has an index of 0 :type dso_range: list :param case: folder extension of case of interest :type case: str :param data_path: :type data_path: str :param metadata_path: :type metadata_path: str :param agent_prefix: folder extension for agent data :type agent_prefix: str
- Returns:
saves plot of population distribution to file
- tesp_support.dsot.plots.non_participating_dso_loads(dso_range, case, metadata_path)
For a specified dso range case, and metadata path information this function will load in the required data (ERCOT load profiles for non-participating DSOS). :param case: path where the annual case lives :type case: str :param dso_range: List of DSOs that are being modeled in the system :type dso_range: list
- Returns:
saves dso load comparison plots to file
- tesp_support.dsot.plots.plot_lmp_stats(data_path, output_path, dso_num, month_index=8)
Will plot LMPS by month, duration, and versus netloads loads (for select month), and save to file. :param data_path: location of the data files to be used. :type data_path: str :param output_path: path of the location where output (plots, csv) should be saved :type output_path: str :param dso_num: bus number for LMP data to be plotted :type dso_num: str
- Returns:
saves dso lmps plots to file
- tesp_support.dsot.plots.run_plots()
- tesp_support.dsot.plots.subscription_plot(dso, day_range, metadata_path, case, demand_case)
Plots comparison of subscription load and base demand load (as well as price comparison). :param dso: the DSO range that should be plotted. :type dso: int :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.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, solver)
Bases:
objectThis 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
solver (str)
- Initialize from Args
- name
name of this agent
- Type:
str
- participating
participating from pv_dict dictionary
- Type:
bool
- rating
rating from pv_dict dictionary
- Type:
float
- scaling_factor
scaling_factor from pv_dict dictionary
- Type:
float
- slider
slider_setting from pv_dict dictionary
- Type:
float
- windowLength
48 always for now
- Type:
int
- TIME
range(0, self.windowLength)
- Type:
list
- scale_pv_forecast(solar_f)
tesp_support.dsot.residential_feeder_glm module
tesp_support.dsot.retail_market module
Class that manages the operation of retail market at substation-level
This module defines RetailMarket, which performs customer-facing
day-ahead (DA) and real-time (RT) market functions:
- collect and aggregate participant curve bids from DER and DSO agents,
- generate aggregated buyer and seller curves
- clear RT and DA retail markets against DSO supply curves,
- compute cleared quantities, prices, and congestion components 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:
objectThe market agent in charge of managing the retail market operation
The class maintains RT/DA bid state, aggregates buyer/seller curves, clears retail markets, and stores cleared outcomes for downstream agent control and settlement analysis.
- Parameters:
retail_dict (dict) – Retail market configuration (caps, sampling, horizon, feeder and TOC-related options).
key (str) – Retail market agent identifier.
- 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_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 by resetting DA market state and initializing empty DA buyer/seller curves
- clean_bids_RT()
Initialize the real-time market by resetting RT market state and initializing empty RT buyer/seller curves
- 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:
- Outputs:
clear_type (int) cleared_price (float) cleared_quantity (float) congestion_surcharge (float)
- clear_market_DA(transformer_degradation, Q_max)
Clear the DA retail market for all DA intervals.
- Three steps of work are fullfilled in a loop in this function:
the buyer curve at each hour is fitted polynomial;
- clear_market function is called for calculating the cleared price
and cleared quantity for the whole market at each hour;
- 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
- Parameters:
transformer_degradation (bool) – Whether TOC/degradation effects are active.
Q_max (float) – Retail feeder quantity limit used for clearing context.
- Returns:
Cleared DA prices, quantities, and clear-types if returned by implementation.
- Return type:
tuple[list[float], list[float], list[object]] | None
- clear_market_RT(transformer_degradation, Q_max)
Clear the RT retail market and store cleared RT outputs.
- Three steps of work are fullfilled in this function:
the buyer curve is fitted polynomial;
- clear_market function is called for calculating the cleared price
and cleared quantity for the whole market;
- 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
- Parameters:
transformer_degradation (bool) – Whether TOC/degradation effects are active.
Q_max (float) – Retail feeder quantity limit used for clearing context.
- Returns:
Cleared RT price, quantity, and clear-type if returned by implementation.
- Return type:
tuple[float, float, object] | None
- 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. Aggregates one DA participant bid profile into DA market curves.
- Parameters:
identity (str) – identifies whether the bid is collected from a “Buyer” or “Seller”
bid_DA (list) – DA bid profile by interval (per-interval bid points) (a nested list with dimension (self.windowLength, m, 2), with m equals 2 to 4)
name (str) – Participant(buyer or seller) identifier used for logging/debug
- curve_aggregator_RT(identity, bid_RT, name)
Function used to collect the RT bid and update the accumulated buyer or seller curve. Aggregates one RT participant bid into the retail market curve.
- Parameters:
identity (str) – identifies whether the bid is collected from a “Buyer” or “Seller”
bid_RT (list) – RT bid points (quantity/price pairs) (a nested list with dimension (m, 2), with m equals 2 to 4)
name (str) – Participant(buyer or seller) identifier used for logging/debug.
- 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
- 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)
Update the control-area retail price signal used by customer agents.
Applies the current clearing outcome (or configured fallback rule) to compute the control-area retail price signal broadcast for downstream bidding/response (i.e., the responsive customer agents).
- Returns:
Updated price value or updates internal state, depending on call pattern.
- tesp_support.dsot.retail_market.test()
Run a smoke test for RetailMarket initialization and clearing paths.
Intended for quick developer checks that representative bids can be ingested and both DA/RT clearing routines execute with valid output structure.
- Returns:
None.
tesp_support.dsot.sankey module
- tesp_support.dsot.sankey.label_nodes(data, total_value)
Adds max quantity of node value to node label
- tesp_support.dsot.sankey.load_CFS_data(results_path, dso_range, update_data, scale, labelvals, calibrate)
Initiates and updates Sankey diagram data structure for Cash Flow Sheet data. :param results_path: directory path for the case to be analyzed. Should be run after annual post-processing :type results_path: str :param dso_range: range of DSOs to be included in data analysis :type dso_range: range :param update_data: If True pulls in analysis data. If False plots Sankey with default data to show structure :type update_data: bool :param scale: If True scales data to $B from standard $K CFS units :type scale: bool :param labelvals: If True adds quantitative values to node labels :type labelvals: bool :param calibrate: If True it squares up values that are typically slightly off in the analysis :type calibrate: bool
- Returns:
Sankey data structure for Plotly Sankey diagram plotting
- Return type:
data (dict)
- tesp_support.dsot.sankey.load_CFS_delta_data(results_path, comp_path, dso_range, update_data, scale, labelvals, metadata_file, calibrate)
Initiates and updates Sankey diagram data structure for Cash Flow Sheet data. :param results_path: directory path for the case to be analyzed. Should be run after annual post-processing :type results_path: str :param comp_path: directory path for the baseline (business-as-usual) case. :type comp_path: str :param dso_range: range of DSOs to be included in data analysis :type dso_range: range :param update_data: If True pulls in analysis data. If False plots Sankey with default data to show structure :type update_data: bool :param scale: If True scales data to $B from standard $K CFS units :type scale: bool :param labelvals: If True adds quantitative values to node labels :type labelvals: bool :param calibrate: If True it squares up values that are typically slightly off in the analysis :type calibrate: bool
- Returns:
Sankey data structure for Plotly Sankey diagram plotting
- Return type:
data (dict)
- tesp_support.dsot.sankey.load_energy_data(results_path, dso_range, update_data, scale, labelvals, calibrate=True, mode='Average')
Initiates and updates Sankey diagram data structure for simulation energy data. :param results_path: directory path for the case to be analyzed. Should be run after annual post-processing :type results_path: str :param dso_range: range of DSOs to be included in data analysis :type dso_range: range :param update_data: If True pulls in analysis data. If False plots Sankey with default data to show structure :type update_data: bool :param scale: If True scales data to GW from standard MW CFS units :type scale: bool :param labelvals: If True adds quantitative values to node labels :type labelvals: bool :param calibrate: If True it squares up values that are typically slightly off in the analysis :type calibrate: bool :param mode: Determines if the power plotted is for annual ‘Average’ or coincident ‘Peak’ :type mode: string
- 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.tesp_monitor module
tesp_support.dsot.tou module
- tesp_support.dsot.tou.main(dso_name, method)
- tesp_support.dsot.tou.time_of_use_price_profile(tou_params, step_size, dso_name, save_path=None)
Creates a price profile that corresponds to parameters of a specified time-of-use rate.
- Parameters:
tou_params (dict) – A dictionary of relevant time-of-use rate parameters for each DSO. Includes time-of-use rate periods, off-peak price, scaling between off-peak price and specified time-of-use period, and seasonal membership for each month.
step_size (str) – A string indicating the size of each time step in a format recognizable by pandas (e.g., “1h” corresponds to time steps of one hour, “5min” corresponds to time steps of five minutes).
dso_name (str) – A string specifying the DSO’s name.
save_path (str) – A string specifying the directory to which the created time-of-use price profile should be saved. If no price profile should be saved, provide None. Defaults to not saving the created price profile.
- Returns:
A DataFrame specifying the price profile for each DSO in time steps of size step_size.
- Return type:
tou_profile (pandas.DataFrame)
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:
objectThis 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(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:
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(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:
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(message, sim_time)
Sets the air_temp attribute
- Parameters:
message (str) – Message with temperature in degrees Fahrenheit
sim_time (str) – Current time in the simulation; should be human-readable
- set_da_cleared_quantity(BID, PRICE)
Convert the 4 point bids to a quantity with the known price
- Parameters:
BID (float) ((1,2)X4) – 4 point bid
PRICE (float) – cleared price in $/kWh
- Returns:
cleared quantity
- Return type:
quantity (float)
- set_forecasted_schedule(forecasted_waterdraw_array)
Set the f_DA_schedule attribute
- Parameters:
forecasted_waterdraw_array (list) – forecasted waterdraw flow rate schedule in gallons/min, provided by forecast agent
- set_price_forecast(forecasted_price)
Set the f_DA_price attribute
- Parameters:
forecasted_price (list) – forecasted DA prices in $/kwh, provided by retail market agent
- set_time(minute, hour)
Sets the current hour and minute
- Parameters:
minute (int) – the minute of the hour from 0 to 59
hour (int) – the hour of the day, from 0 to 23
- set_wh_load(message: str)
Sets the water heater load attribute, if greater than zero
- Parameters:
message (str) – Message with load in kW
- set_wh_lower_state(message: str)
Sets the lower element state attribute
- Parameters:
message (str) – Message with ON/OFF status
- set_wh_lower_temperature(message, sim_time)
Sets the lower tank temperature attribute
- Parameters:
message (str) – Message with temperature in degrees Fahrenheit
sim_time (str) – Current time in the simulation; should be human-readable
- set_wh_upper_state(message: str)
Sets the upper element state attribute
- Parameters:
message (str) – Message with ON/OFF status
- set_wh_upper_temperature(message, sim_time)
Sets the upper tank temperature attribute
- Parameters:
message (str) – Message with temperature in degrees Fahrenheit
sim_time (str) – Current time in the simulation; should be human-readable
- set_wh_wd_rate_val(message: str)
Sets the water draw rate attribute
- Parameters:
message (str) – Message with wdrate value in gpm
- test_function()
Test function with the only purpose of returning the name of the object
- update_WH_his(sim_time)
Update the historical memory of water heater based on updated readings, called by formulate_bid_rt every 5 mins
- Parameters:
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()