tesp_support.consensus package

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

Submodules

tesp_support.consensus.case_merge module

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

Public Functions:
merge_glm:

combines GridLAB-D input files

merge_glm_dict:

combines GridLAB-D metadata files

merge_agent_dict:

combines the substation agent configuration files

merge_substation_yaml:

combines the substation agent FNCS publish/subscribe files

merge_fncs_config:

combines GridLAB-D FNCS publish/subscribe files

tesp_support.consensus.case_merge.merge_agent_dict(target, sources)

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

Parameters:

  • target (str) – the path to the target JSON file, including the name of the file

  • sources (list) – list of feeder names in the target directory to merge

tesp_support.consensus.case_merge.merge_fncs_config(target, dso, sources)

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

Parameters:

  • target (str) – the path to the target TXT file, including the name of the file

  • dso (str) – dso id

  • sources (list) – list of feeder names in the target directory to merge

tesp_support.consensus.case_merge.merge_glm(target, sources, xfmva)

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

Parameters:

  • target (str) – the path to the target GLM file, including the name of the file

  • sources (list) – list of feeder names in the target directory to merge

  • xfmva (int) –

tesp_support.consensus.case_merge.merge_glm_dict(target, sources, xfmva)

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

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

Parameters:

  • target (str) – the path to the target JSON file, including the name of the file

  • sources (list) – list of feeder names in the target directory to merge

  • xfmva (int) –

tesp_support.consensus.case_merge.merge_substation_yaml(target, sources)

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

Parameters:

  • target (str) – the path to the target YAML file, including the name of the file

  • sources (list) – list of feeder names in the target directory to merge

tesp_support.consensus.dg_agent module

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

Public Functions:
substation_loop:

initializes and runs the agents

tesp_support.consensus.dg_agent.destroy_federate(fed)
tesp_support.consensus.dg_agent.inner_substation_loop(configfile, metrics_root, with_market)

Helper function that initializes and runs the DSOT agents

TODO: This needs to be updated Reads configfile. Writes auction_metrics_root_metrics.json and controller_metrics_root_metrics.json upon completion.

Parameters:

  • configfile (str) – fully qualified path to the JSON agent configuration file

  • metrics_root (str) – base name of the case for metrics output

  • with_market (bool) – flag that determines if we run with markets

tesp_support.consensus.dg_agent.register_federate(json_filename)
tesp_support.consensus.dg_agent.substation_loop(configfile, metrics_root, with_market=True)

Wrapper for inner_substation_loop

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

tesp_support.consensus.dg_agent.worker(arg)

tesp_support.consensus.dso_agent module

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

Public Functions:
substation_loop:

initializes and runs the agents

tesp_support.consensus.dso_agent.destroy_federate(fed)
tesp_support.consensus.dso_agent.inner_substation_loop(configfile, metrics_root, with_market)

Helper function that initializes and runs the DSOT agents

TODO: This needs to be updated Reads configfile. Writes auction_metrics_root_metrics.json and controller_metrics_root_metrics.json upon completion.

Parameters:

  • configfile (str) – fully qualified path to the JSON agent configuration file

  • metrics_root (str) – base name of the case for metrics output

  • with_market (bool) – flag that determines if we run with markets

tesp_support.consensus.dso_agent.register_federate(json_filename)
tesp_support.consensus.dso_agent.substation_loop(configfile, metrics_root, with_market=True)

Wrapper for inner_substation_loop

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

tesp_support.consensus.dso_agent.worker(arg)

tesp_support.consensus.dso_market module

Class that manages the operation of DSO agent

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

class tesp_support.consensus.dso_market.DSOMarket(dso_dict, key)

Bases: object

This agent manages the DSO operating

Parameters:

  • dso_dict –

  • key –

name

name of the DSO agent

Type:

str

price_cap

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

Type:

float

num_samples

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

Type:

int

windowLength

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

Type:

int

DSO_Q_max

maximum limit of the DSO load capacity, in kWh

Type:

float

transformer_degradation

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

Type:

bool

curve_a

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

Type:

array

curve_b

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

Type:

array

curve_c

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

Type:

array

Pwclear_RT

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

Type:

float

Pwclear_DA

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

Type:

list

trial_cleared_quantity_RT

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

Type:

float

trial_cleared_quantity_DA

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

Type:

list

curve_DSO_RT

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

Type:

Curve

curve_DSO_DA

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

Type:

dict

curve_ws_node

dictionary of wholesale node curves, indexed by day_of_sim and hour_of_day

Type:

dict

trial_clear_type_RT

trial cleared type of real-time wholesale node trial clearing

Type:

int

trial_clear_type_DA

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

Type:

list

hour_of_day

current hour of the day

Type:

int

day_of_week

current day of the week

Type:

int

customer_count_mix_residential

Residential percentage of the total customer count mix

number_of_gld_homes

Total number of GLD homes for the DSO

clean_bids_DA()

Initialize the day-ahead wholesale node trial clearing

clean_bids_RT()

Initialize the real-time wholesale node trial clearing

curve_aggregator_DSO_DA(demand_curve_DA, Q_max)

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

Parameters:

  • demand_curve_DA (dict) – a collection of demand curves to be aggregated for day-ahead

  • Q_max (float) – maximum capacity of the substation, in kW

curve_aggregator_DSO_RT(demand_curve_RT, Q_max)

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

Parameters:

  • demand_curve_RT (Curve) – demand curve to be aggregated for real-time

  • Q_max (float) – maximum capacity of the substation, in kW

curve_preprocess(substation_demand_curve, Q_max)
An internal shared function called by curve_aggregator_DSO_RT and curve_aggregator_DSO_DA functions to truncate

the substation demand curve before aggregation as well as convert the retail prices into wholesale prices

Parameters:

  • substation_demand_curve (Curve) – substation demand curve to be preprocessed

  • Q_max (float) – maximum capacity of the substation, in kW

Returns:

preprocessed demand curve

Return type:

preprocessed_curve (curve)

generate_TOC(costInterval, maxPuLoad, num_samples, TOC_dict)

Function used to calculate the total owning cost of transformer

Parameters:

  • costInterval (int) – interval for calculating the cost, in minutes

  • maxPuLoad (float) – maximum pu loading factor

  • num_samples (int) – number of sampling points

  • TOC_dict (dict) – configuration parameters for transformer

Returns:

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

Return type:

DollarsForPlot (list)

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)

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

set_cleared_q_da(val)

Set the clear quantity for day ahead

Parameters:

val (double) – lmp for the bus/substation

set_cleared_q_rt(val)

Set the clear quantity for real time

Parameters:

val (double) – lmp for the bus/substation

set_ind_load(industrial_load)

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

Parameters:

industrial_load (str) – industrial load of substation

set_ind_load_da(industrial_load_da)

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

Parameters:

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

set_lmp_da(val)

Set the lmp for day ahead

Parameters:

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

set_lmp_rt(val)

Set the lmp for real time

Parameters:

val (double) – lmp for the bus/substation

set_ref_load(ref_load)

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

Parameters:

ref_load (str) – total load of substation

set_ref_load_da(ref_load_da)

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

Parameters:

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

set_total_load(total_load)

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

Parameters:

total_load (str) – total load of substation

substation_supply_curve_DA(retail_obj)

Function used to generate the DA supply curves for each substation

Args:

Variables:

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

Returns:

a collection of substation supply curves for day-ahead market clearing

Return type:

supply_curve_DA (list)

substation_supply_curve_RT(retail_obj)

Function used to generate the RT supply curve for each substation

Args:

Variables:

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

Returns:

substation supply curve for real-time market clearing

Return type:

supply_curve_RT (curve)

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

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

Parameters:

  • Prclear (float) – retail price overted from wholesale price obtained from trial wholesale node clearing, in $/kWh

  • FeederCongCapacity (float) – feeder congestion capacity, in kWh

  • FeederPkDemandCapacity (float) – feeder peak demand, in kWh

  • num_samples (int) – number of sampling points

  • Q_max (float) – substation limit, in kWh

  • maxPuLoading (float) – maximum pu loading factor

  • TOC_dict (dict) – configuration parameters for transformer

Variables:

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

Returns:

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

Return type:

SupplyQuantities (list)

test_function()

Test function with the only purpose of returning the name of the object

trial_wholesale_clearing(curve_ws_node, curve_DSO)
An internal shared function called by set_Pwclear_RT and

set_Pwclear_DA functions to implement the trial wholesale node clearing

Parameters:

  • curve_ws_node (Curve) – wholesale node curve

  • curve_DSO (Curve) – aggregated demand curve at DSO level

Returns:

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

Return type:

Pwclear (float)

update_wholesale_node_curve()

Update the wholesale node curves according to the most updated curve coefficients, may be updated every day

tesp_support.consensus.dso_market.test()

tesp_support.consensus.forecasting module

Class responsible for forecasting

Implements the substation level DA price forecast and load forecast

class tesp_support.consensus.forecasting.Forecasting

Bases: object

This Class perform the forecast

Parameters:

  • TODO (#) – update inputs

  • TODO – Load base case run files

TODO

update attributes

add_skew_scalar(datafr, N_skew, N_scalar)

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

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

calc_solar_flux(cpt, day_of_yr, lat, sol_time, dnr_i, dhr_i, vertical_angle)
calc_solargain(day_of_yr, time, dnr, dhr, lat, lon, tz_offset)
forecasting_schedules(datafr, time)

Returns windowlength values of given time as forecating :param datafr: schedule dataframe used to forecast :param time: current time at which DA optimization occurs

get_internal_gain_forecast(skew_scalar, time)

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 :type skew_scalar: dict :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 :type time: datetime

Returns:

48 values of total zip loads and total internal gain due to zip loads

Return type:

list

get_solar_gain_forecast(climate_conf, current_time)
get_substation_unresponsive_industrial_load_forecast(peak_load=3500.0)

Get substation unresponsive industrial load forecast

Args:

peak_load (float): peak load in kWh

Returns:

forecast of next 48-hours unresponsive load

Return type:

base_run_load (float x 48)

get_substation_unresponsive_load_forecast(peak_load=7500.0)

Get substation unresponsive load forecast

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

Parameters:

peak_load (float) – peak load in kWh

Returns:

forecast of next 48-hours unresponsive load

Return type:

base_run_load (float x 48)

get_waterdraw_forecast(skew_scalar, time)
static initialize_schedule_dataframe(start_time, end_time)

Initialize the data frame for one year

Parameters:

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

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

make_dataframe_schedule(filename, schedule_name)

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

Parameters:

  • filename (str) – name of glm file to be loaded

  • schedule_name (str) – name of the schedule to be laoded

set_retail_price_forecast(DA_SW_prices)

Set substation price forecast

Nonsummable diminishing.

Parameters:

DA_SW_prices (float x 48) – cleared price in $/kWh from the last shifting window run

Returns:

forecasted prices in $/kWh for the next 48-hours

Return type:

forecasted_price (float x 48)

set_sch_year(year)
set_solar_diffuse_forecast(fncs_str)

Set the 48 hour solar diffuse forecast :param solar_diffuse_forecast: :type solar_diffuse_forecast: [float x 48]

set_solar_direct_forecast(fncs_str)

Set the 48 hour solar direct forecast :param solar_direct_forecast: :type solar_direct_forecast: [float x 48]

tesp_support.consensus.generator module

tesp_support.consensus.generator.Consenus_dist_DA(dso_market_obj, DA_horizon, fed, hour_of_day, time_granted, time_market_DA_complete)
tesp_support.consensus.generator.Consenus_dist_RT(dso_market_obj, fed, hour_of_day, time_granted, time_market_RT_complete)
tesp_support.consensus.generator.construct_Laplacian(N_agents)

tesp_support.consensus.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.consensus.glm_dictionary.append_include_file(lines, fname)
tesp_support.consensus.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.consensus.glm_dictionary.glm_dict_with_microgrids(name_root, config=None, ercot=False)

Writes the JSON metadata file from a GLM file

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

Parameters:

  • name_root (str) – path and file name of the GLM file, without the extension

  • config (dict) –

  • ercot (bool) – request ERCOT billing meter naming. Defaults to false. — THIS NEEDS TO LEAVE THIS PLACE

  • te30 (bool) – request hierarchical meter handling in the 30-house test harness. Defaults to false. — THIS NEEDS TO LEAVE THIS PLACE

tesp_support.consensus.glm_dictionary.ti_enumeration_string(tok)

if thermal_integrity_level is an integer, convert to a string for the metadata

tesp_support.consensus.microgrid module

tesp_support.consensus.microgrid.Consenus_dist_DA(dso_market_obj, DA_horizon, fed, time_granted, time_market_DA_complete)
tesp_support.consensus.microgrid.Consenus_dist_RT(dso_market_obj, fed, time_granted, time_market_RT_complete)
tesp_support.consensus.microgrid.construct_Laplacian(N_agents)

tesp_support.consensus.microgrid_agent module

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

Public Functions:
substation_loop:

initializes and runs the agents

tesp_support.consensus.microgrid_agent.destroy_federate(fed)
tesp_support.consensus.microgrid_agent.inner_substation_loop(configfile, metrics_root, with_market)

Helper function that initializes and runs the DSOT agents

TODO: This needs to be updated Reads configfile. Writes auction_metrics_root_metrics.json and controller_metrics_root_metrics.json upon completion.

Parameters:

  • configfile (str) – fully qualified path to the JSON agent configuration file

  • metrics_root (str) – base name of the case for metrics output

  • with_market (bool) – flag that determines if we run with markets

tesp_support.consensus.microgrid_agent.register_federate(json_filename)
tesp_support.consensus.microgrid_agent.substation_loop(configfile, metrics_root, with_market=True)

Wrapper for inner_substation_loop

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

tesp_support.consensus.microgrid_agent.worker(arg)

tesp_support.consensus.residential_feeder_glm module

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

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

There are two kinds of house populating methods implemented:

  • Feeders with Service Transformers:

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

  • Feeders without Service Transformers:

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

References

GridAPPS-D Feeder Models

Public Functions:
populate_feeder:

processes one GridLAB-D input file

Todo

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

  • Populate commercial building loads

tesp_support.consensus.residential_feeder_glm.Find1PhaseXfmr(kva)

Select a standard 1-phase transformer size, with data

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

Parameters:

kva (float) – the minimum transformer rating

Returns:

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

Return type:

[float,float,float,float,float]

tesp_support.consensus.residential_feeder_glm.Find1PhaseXfmrKva(kva)

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

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

Parameters:

kva (float) – the minimum transformer rating

Returns:

the kva size, or 0 if none found

Return type:

float

tesp_support.consensus.residential_feeder_glm.Find3PhaseXfmr(kva)

Select a standard 3-phase transformer size, with data

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

Parameters:

kva (float) – the minimum transformer rating

Returns:

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

Return type:

[float,float,float,float,float]

tesp_support.consensus.residential_feeder_glm.Find3PhaseXfmrKva(kva)

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

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

Parameters:

kva (float) – the minimum transformer rating

Returns:

the kva size, or 0 if none found

Return type:

float

tesp_support.consensus.residential_feeder_glm.FindFuseLimit(amps)

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

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

Parameters:

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

Returns:

the GridLAB-D fuse size to insert

Return type:

float

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

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

This function:

  • reads and parses the backbone model from rootname.glm

  • replaces loads with houses and DER

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

  • writes the repopulated feeder to outname.glm

Parameters:

  • outname (str) – the output feeder model name

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

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

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

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

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

tesp_support.consensus.residential_feeder_glm.accumulate_load_kva(data)

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

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

Parameters:

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

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

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

Parameters:

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

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

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

tesp_support.consensus.residential_feeder_glm.checkResidentialBuildingTable()

Verify that the regional building parameter histograms sum to one

tesp_support.consensus.residential_feeder_glm.connect_ercot_commercial(op)

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

Parameters:

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

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

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

Parameters:

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

  • h (dict) – the object ID hash

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

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

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

tesp_support.consensus.residential_feeder_glm.getDsoThermalTable(dso_type)
tesp_support.consensus.residential_feeder_glm.get_dist(mean, var)

get a random number from a distribution given mean and %variability :param mean: mean of distribution :param var: % variability

Returns:

one random entry from distribution

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

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

Parameters:

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

  • h (dict) – the object ID hash

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

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

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

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

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

Parameters:

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

  • h (dict) – the object ID hash

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

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

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

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

tesp_support.consensus.residential_feeder_glm.is_edge_class(s)

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

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

Parameters:

s (str) – the GridLAB-D class name

Returns:

True if an edge class, False otherwise

Return type:

bool

tesp_support.consensus.residential_feeder_glm.is_node_class(s)

Identify node, load, meter, triplex_node or triplex_meter instances

Parameters:

s (str) – the GridLAB-D class name

Returns:

True if a node class, False otherwise

Return type:

bool

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

Prints the whole parsed model for debugging

Parameters:

  • model (dict) – parsed GridLAB-D model

  • h (dict) – object ID hash

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

Store an object in the model structure

Parameters:

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

  • model (dict) – dictionary model structure

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

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

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

  • octr (int) – object counter

Returns:

the current line and updated octr

Return type:

str, int

tesp_support.consensus.residential_feeder_glm.populate_all_feeders()

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

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

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

Parameters:

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

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

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

tesp_support.consensus.residential_feeder_glm.randomize_commercial_skew()
tesp_support.consensus.residential_feeder_glm.randomize_residential_skew()
tesp_support.consensus.residential_feeder_glm.randomize_skew(value, skew_max)
tesp_support.consensus.residential_feeder_glm.replace_commercial_loads(model, h, t, avgBuilding)

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

Parameters:

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

  • h (dict) – the object ID hash

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

  • avgBuilding (float) – the average building in kva

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

Selects the building with region and probability

Parameters:

  • rgnTable –

  • prob –

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

Randomly choose a histogram row from the cooling and heating setpoints

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

Parameters:

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

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

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

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

Parameters:

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

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

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

Collect all phases on both sides of a connection

Parameters:

  • phs1 (str) – first phasing

  • phs2 (str) – second phasing

Returns:

union of phs1 and phs2

Return type:

str

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

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

Parameters:

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

  • h (dict) – the object ID hash

  • t (str) – the GridLAB-D class

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

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

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

Parameters:

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

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

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

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

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

Parameters:

  • basenode (str) – GridLAB-D node name

  • op (file) – open file to write to

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

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

Parameters:

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

  • h (dict) – the object ID hash

  • t (str) – the GridLAB-D class

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

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

tesp_support.consensus.residential_feeder_glm.write_local_triplex_configurations(op)

Write a 4/0 AA triplex configuration

Parameters:

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

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

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

Parameters:

  • basenode (str) – GridLAB-D node name

  • op (file) – open file to write to

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

tesp_support.consensus.residential_feeder_glm.write_solar_inv_settings(op)

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

Parameters:

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

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

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

Parameters:

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

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

  • phs (str) – primary phasing in the substation

  • vnom (float) – not used

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

tesp_support.consensus.residential_feeder_glm.write_tariff(op)

Writes tariff information to billing meters

Parameters:

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

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

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

Parameters:

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

  • h (dict) – the object ID hash

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

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

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

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

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

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

Write a transformer_configuration

Parameters:

  • key (str) – name of the configuration

  • phs (str) – primary phasing

  • kvat (float) – transformer rating in kVA

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

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

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

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

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

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

tesp_support.consensus.retail_market module

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

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

The function call order for this agent is:

initialize(retail_dict)

Repeats at every hour:

clean_bids_DA() curve_aggregator_DA(identity, bid, id) … curve_aggregator_DA(identity, bid, id) clear_market_DA(transformer_degradation, Q_max)

Repeats at every 5 min:

clean_bids_RT() curve_aggregator_RT(identity, bid, id) … curve_aggregator_RT(identity, bid, id) clear_market_RT(transformer_degradation, Q_max)

class tesp_support.consensus.retail_market.RetailMarket(retail_dict, key)

Bases: object

This agent manages the retail market operating

Parameters:

  • retail_dict –

  • key –

name

name of the retail market agent

Type:

str

price_cap

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

Type:

float

num_samples

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

Type:

int

windowLength

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

Type:

int

Q_max

capacity of the substation, in kWh

Type:

float

maxPuLoading

rate of the maxPuLoading for transformer

Type:

float

curve_buyer_RT

aggregated buyer curve, updated after receiving each RT buyer bid

Type:

Curve

curve_seller_RT

aggregated seller curve, updated after receiving each RT seller bid

Type:

Curve

curve_buyer_DA

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

Type:

dict of curves

curve_seller_DA

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

Type:

dict of curves

clear_type_RT

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

Type:

int

clear_type_DA

list of clear type at each hour

Type:

list

cleared_price_RT

cleared price for the substation for the next 5-min

Type:

float

cleared_price_DA

list of cleared price at each hour

Type:

list

cleared_quantity_RT

cleared quantity for the substation for the next 5-min

Type:

float

cleared_quantity_DA

list of cleared quantity at each hour

Type:

list

site_responsive_DA

Site_Day_Ahead quantity which is responsive

Type:

list

site unresponsive DA

Site Day Ahead quantity which is unresponsive

Type:

list

AMES_RT

Smooth Quadratics

Type:

list X 5

AMES_DA

Smooth Quadratics

Type:

(list X 5) X windowLength

TOC_dict

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

Type:

dict

clean_bids_DA()

Initialize the day-ahead market

clean_bids_RT()

Initialize the real-time market

clear_market(curve_buyer, curve_seller, transformer_degradation, Q_max)

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

Parameters:

  • curve_buyer (Curve) – aggregated buyer curve

  • curve_seller (Curve) – aggregated seller curve

  • transformer_degradation (bool) – equals to 1 if transformer_degradation is considered in the supply curve

  • Q_max (float) – substation capacity, in kWh

Outputs:

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

clear_market_DA(transformer_degradation, Q_max)

Function used for clearing the DA market

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

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

clear_market_RT(transformer_degradation, Q_max)

Function used for clearing the RT market

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

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

convert_2_AMES_quadratic_BID(curve, Q_cleared, price_forecast)

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

Returns:

f(Q)=resp_c2*Q^2+C1*Q+C0

unresp_mw (float): minimum demand MW resp_max_mw (float): maximum demand MW resp_c2 (float): quadratic coefficient resp_c1 (float): linear coefficient resp_c0 (float): constant coefficient resp_deg (int): equal to “2” to represent the current order in the list

Return type:

quadratic_bid (list)

curve_aggregator_AMES_DA(demand_curve_DA, Q_max, Q_cleared, price_forecast)

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

Parameters:

  • demand_curve_DA (dict) – a collection of demand curves to be aggregated for day-ahead

  • Q_max (float) – maximum capacity of the substation, in kW

  • Q_cleared (float) – locally cleared quantity of the substation in kW

  • price_forecast (float) – locally forecast price at the substation level

curve_aggregator_AMES_RT(demand_curve_RT, Q_max, Q_cleared, price_forecast)

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

Parameters:

  • demand_curve_RT (Curve) – demand curve to be aggregated for real-time

  • Q_max (float) – maximum capacity of the substation, in kW

  • Q_cleared (float) – locally cleared quantity of the substation in kW

  • price_forecast (float) – locally forecast price at the substation level

curve_aggregator_DA(identity, bid_DA, name)

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

Parameters:

  • identity (str) – identifies whether the bid is collected from a “Buyer” or “Seller”

  • bid_DA (list) – a nested list with dimension (self.windowLength, m, 2), with m equals 2 to 4

  • name (str) – name of the buyer or seller

curve_aggregator_RT(identity, bid_RT, name)

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

Parameters:

  • identity (str) – identifies whether the bid is collected from a “Buyer” or “Seller”

  • bid_RT (list) – a nested list with dimension (m, 2), with m equals 2 to 4

  • name (str) – name of the buyer or seller

curve_preprocess(substation_demand_curve, Q_max)
An internal shared function called by curve_aggregator_DSO_RT and curve_aggregator_DSO_DA functions to truncate

the substation demand curve before aggregation as well as convert the retail prices into wholesale prices

Parameters:

  • substation_demand_curve (Curve) – substation demand curve to be preprocessed

  • Q_max (float) – maximum capacity of the substation, in kW

Returns:

preprocessed demand curve

Return type:

preprocessed_curve (curve)

formulate_bid_industrial_da(industrial_load_forecast, price_forecast)
This file is to create a bid curve for industrial customer for the given demand-price elasticity

elasticity (a) = (del-Q/Q)/(del-P/P) –> del-Q/del-p = a * Q / P The slope of the bid curve for the industrial load will be Slope (S) = (del-Q/del-P) The Q-axis intercept for the bid curve will be (C_Q) = Q + S * del-p = Q - a * Q The P-axis intercept for the bid curve will be (C_P) = P + S * 1 / del-Q = P - P / a

Args:

price_forecast: forecasted price in $/kWh at the instance (if we are going to bid directly in ISO, then this is LMP forecast, or else, it is retail price forecast industrial_load_forecast: forecast quantity of industrial load in kW at that instant

Returns:

bid_da (float) (1 x windowLength): Bid quantity from optimization for all hours of the window specified by windowLength

formulate_bid_industrial_rt(industrial_load, price_cleared)
This file is to create real time bid curve for industrial customer for the given demand-price elasticity

elasticity (a) = (del-Q/Q)/(del-P/P) –> del-Q/del-p = a * Q / P The slope of the bid curve for the industrial load will be Slope (S) = (del-Q/del-P) The Q-axis intercept for the bid curve will be (C_Q) = Q + S * del-p = Q - a * Q The P-axis intercept for the bid curve will be (C_P) = P + S * 1 / del-Q = P - P / a

Args:

price_cleared (float): Price cleared in $/kWh at the instance (if we are going to bid directly in ISO, then this is LMP forecast, or else, it is retail price forecast industrial_load (float): The most updated (closer to real-time) industrial load in kW at that instant

Returns:

bid_rt (1,2)X4): 4 point industrial load bid

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

tesp_support.consensus.retail_market.test()

Testing AMES

tesp_support.consensus.substation module

tesp_support.consensus.substation.Consenus_dist_DA(dso_market_obj, DA_horizon, fed, hour_of_day, time_granted, time_market_DA_complete)
tesp_support.consensus.substation.Consenus_dist_RT(dso_market_obj, fed, hour_of_day, time_granted, time_market_RT_complete)
tesp_support.consensus.substation.construct_Laplacian(N_agents)

tesp_support.consensus.weather_agent module

Weather Agent

This weather agent needs an WEATHER_CONFIG environment variable to be set, which is a json file.

tesp_support.consensus.weather_agent.convertTimeToSeconds(time)

Convert time string with unit to integer in seconds

It only parse unit in day, hour, minute and second. It will not recognize week, month, year, millisecond, microsecond or nanosecond, they can be added if needed.

Parameters:

time (str) – time with unit

Returns:

(int) represent the input time in second

tesp_support.consensus.weather_agent.deltaTimeToResmapleFreq(time)

Convert time unit to a resampling frequency that can be recognized by pandas.DataFrame.resample()

It only parse unit in day, hour, minute and second. It won’t recognize week, month, year, millisecond, microsecond or nanosecond, they can be added if needed.

Parameters:

time (str) – time with unit

Returns:

(str) time with resample frequency

tesp_support.consensus.weather_agent.destroy_federate(fed)
tesp_support.consensus.weather_agent.findDeltaTimeMultiplier(time)

Find the multiplier to convert delta_time to seconds

It only parse unit in day, hour, minute and second. It won’t recognize week, month, year, millisecond, microsecond or nanosecond, they can be added if needed.

Parameters:

time (str) – time with unit

Returns:

(int) the multiplier to convert delta_time to seconds

tesp_support.consensus.weather_agent.register_federate(json_filename)
tesp_support.consensus.weather_agent.startWeatherAgent(file)

The weather agent publishes weather data as configured by the json file

Parameters:

file (str) – the weather data file

Returns:

(none)

tesp_support.consensus.weather_agent.usage()
class tesp_support.consensus.weather_agent.weather_forecast(variable, period, W_dict)

Bases: object

This object includes the error to a weather variable

Parameters:

  • variable (str) – Type of weather variable being forecasted

  • period (int) – period of the sinusoidal bias

  • W_dict (dict) – dictionary for specifying the generation of the error envelope

weather_variable

Type of weather variable being forecasted

Type:

str

# Type of error insertion
distribution

type of distribution –> 0 uniform;1 triangular;2 truncated normal the standard deviation is computed for 95% of values to be within bounds in a conventional normal distribution

Type:

int

P_e_bias

pu maximum bias at first hour –> [0 to 1]

Type:

float

P_e_envelope

pu maximum error from mean values –> [0 to 1]

Type:

float

Lower_e_bound

pu of the maximum error at the first hour –> [0 to 1]

Type:

float

# Bias variable
biasM

sinusoidal bias for altering the error envelope

Type:

float) (1 X period

Period_bias

period of the sinusoidal bias

Type:

int

get_truncated_normal(EL, EH)

Truncated normal distribution

make_forecast(weather, t=0)

Include error to a known weather variable

Parameters:

  • weather (float) (1 x desired number of hours ahead) – known weather variable

  • t (int) – time in hours

Returns:

weather variable with included error ENV_U (float) (1 x desired number of hours ahead): envelope with bias upper bound ENV_l (float) (1 x desired number of hours ahead): envelope with bias lower bound

Return type:

weather_f (float) (1 x desired number of hours ahead)