tesp_support.original package

Submodules

tesp_support.original.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

merge_gld_msg:

combines GridLAB-D HELICS publish/subscribe configurations

merge_substation_msg:

combines the substation agent HELICS publish/subscribe configurations

tesp_support.original.case_merge.key_present(val, ary)

tesp_support.original.case_merge.merge_agent_dict(target, sources, xfmva)

Combines the substation agent configuration files into target/target.json. The source files must already exist.

Parameters:

• target (str) – the directory and root case name

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

tesp_support.original.case_merge.merge_fncs_config(target, sources)

Combines GridLAB-D input files into target/target.txt. The source feeders must already exist.

Parameters:

• target (str) – the directory and root case name

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

tesp_support.original.case_merge.merge_gld_msg(target, sources)

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

Combines GridLAB-D input files into target/target.glm. The source files must already exist.

Parameters:

• target (str) – the directory and root case name

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

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

Combines GridLAB-D metadata files into target/target.json. The source files must already exist.

Each constituent feeder has a new ID constructed from the NamePrefix + original base_feeder, then every child object on that feeder will have its feeder_id, originally network_node, changed to match the new one.

Parameters:

• target (str) – the directory and root case name

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

• xfmva (int)

tesp_support.original.case_merge.merge_substation_msg(target, sources)

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

Combines GridLAB-D input files into target/target.yaml. The source files must already exist.

Parameters:

• target (str) – the directory and root case name

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

tesp_support.original.commercial_feeder_glm module

tesp_support.original.copperplate_feeder_glm module

tesp_support.original.curve module

Utility functions for use within tesp_support, including new agents.

class tesp_support.original.curve.ClearingType(value)

Bases: IntEnum

Describes the market clearing type

BUYER = 5

EXACT = 3

FAILURE = 1

NULL = 0

PRICE = 2

SELLER = 4

tesp_support.original.curve.aggregate_bid(crv)

Aggregates the buyer curve into a quadratic or straight-line fit with zero intercept

Parameters:

crv (curve) – the accumulated buyer bids

Returns:

Qunresp, Qmaxresp, degree, c2 and c1 scaled to MW instead of kW. c0 is always zero.

Return type:

[float, float, int, float, float]

class tesp_support.original.curve.curve

Bases: object

Accumulates a set of price, quantity bids for later aggregation. The default order is descending by price.

price

array of prices, in $/kWh

Type:

[float]

quantity

array of quantities, in kW

Type:

[float]

count

the number of collected bids

Type:

int

total

the total kW bidding

Type:

float

total_on

the total kW bidding that are currently on

Type:

float

total_off

the total kW bidding that are currently off

Type:

float

add_to_curve(price, quantity, is_on)

Add one point to the curve

Parameters:

• price (float) – the bid price, should be $/kWhr

• quantity (float) – the bid quantity, should be kW

• is_on (bool) – True if the load is currently on, False if not

set_curve_order(flag)

Set the curve order (by price) to ascending or descending

Parameters:

flag (str) – ‘ascending’ or ‘descending’

tesp_support.original.fncs module

Functions that provide access from Python to the FNCS library

Notes

Depending on the operating system, libfncs.dylib, libfncs.dll or libfncs.so must already be installed. Besides the defined Python wrapper functions, these pass-through library calls are always needed:

• fncs.finalize: call after the simulation completes

• fncs.time_request (long): request the next time step; blocks execution of this process until FNCS grants the requested time. Then, the process should check for messages from FNCS.

These pass-through calls are also available, but not used in TESP:

• fncs.route

• fncs.update_time_delta

• fncs.get_id

• fncs.get_simulator_count

• fncs.get_events_size

• fncs.get_keys_size

• fncs.die: stops FNCS and sends ‘die’ to other simulators

References

ctypes

FNCS

Examples

• under tesp_support, see substation.py, precool.py and tso_PYPOWER_f.py

• under examples, see loadshed/loadshed.py

tesp_support.original.fncs.agentGetEvents()

Retrieve FNCS agent messages

Returns:

concatenation of agent messages

Return type:

str

tesp_support.original.fncs.agentPublish(value)

Publish a value over FNCS, under the configured simulator name / agent name

Parameters:

value (str) – value

tesp_support.original.fncs.agentRegister(config=None)

Initialize the FNCS configuration for the agent interface

Parameters:

config (str) – a ZPL file. If None (default), provide YAML file in FNCS_CONFIG_FILE environment variable.

tesp_support.original.fncs.die()

Call FNCS die because of simulator error

tesp_support.original.fncs.finalize()

Call FNCS finalize to end connection with broker

tesp_support.original.fncs.get_event_at(i)

Retrieve FNCS message by index number after time_request returns

Returns:

one decoded FNCS event

Return type:

str

tesp_support.original.fncs.get_events()

Retrieve FNCS messages after time_request returns

Returns:

tuple of decoded FNCS events

Return type:

list

tesp_support.original.fncs.get_events_size()

Get the size of the event queue

tesp_support.original.fncs.get_id()

Find the FNCS ID

tesp_support.original.fncs.get_key_at(i)

Get the topic by index number

Parameters:

i (int) – the index number

Returns:

decoded topic name

Return type:

str

tesp_support.original.fncs.get_keys()

Find the list of topics

Returns:

decoded topic names

Return type:

[str]

tesp_support.original.fncs.get_keys_size()

Get the size of the keys

tesp_support.original.fncs.get_name()

Find the FNCS simulator name

Returns:

the name of this simulator as provided in the ZPL or YAML file

Return type:

str

tesp_support.original.fncs.get_simulator_count()

Find the FNCS simulator count

tesp_support.original.fncs.get_value(key)

Extract value from a FNCS message

Parameters:

key (str) – the topic

Returns:

decoded value

Return type:

str

tesp_support.original.fncs.get_value_at(key, i)

For list publications, get the value by index

Parameters:

• key (str) – the topic

• i (int) – the list index number

Returns:

decoded value

Return type:

str

tesp_support.original.fncs.get_values(key)

For list publications, get the list of values

Parameters:

key (str) – the topic

Returns:

decoded values

Return type:

[str]

tesp_support.original.fncs.get_values_size(key)

For list publications, find how many values were published

Parameters:

key (str) – the topic

Returns:

the number of values for this topic

Return type:

int

tesp_support.original.fncs.get_version()

Find the FNCS version

Returns:

major, minor and patch numbers

Return type:

int, int, int

tesp_support.original.fncs.initialize(config=None)

Initialize the FNCS configuration

Parameters:

config (str) – a ZPL file. If None (default), provide YAML file in FNCS_CONFIG_FILE environment variable.

tesp_support.original.fncs.is_initialized()

Determine whether the FNCS library has been initialized

Returns:

True if initialized, False if not.

Return type:

bool

tesp_support.original.fncs.publish(key, value)

Publish a value over FNCS, under the simulator name

Parameters:

• key (str) – topic under the simulator name

• value (str) – value

tesp_support.original.fncs.publish_anon(key, value)

Publish a value over FNCS, under the ‘anonymous’ simulator name

Parameters:

• key (str) – topic under ‘anonymous’

• value (str) – value

tesp_support.original.fncs.route(sender, receiver, key, value)

Route a value over FNCS from sender to receiver

Parameters:

• sender (str) – simulator routing the message

• receiver (str) – simulator to route the message to

• key (str) – topic under the simulator name

• value (str) – value

tesp_support.original.fncs.time_request(time)

FNCS time request

Parameters:

time (int) – requested time.

tesp_support.original.fncs.update_time_delta(delta)

Update simulator time delta value

Parameters:

delta (int) – time delta.

tesp_support.original.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.original.glm_dictionary.append_include_file(lines, fname)

Parameters:

• lines (list<str>)

• fname (string)

tesp_support.original.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.original.glm_dictionary.glm_dict(name_root, ercot=False, te30=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

• ercot (bool) – request ERCOT billing meter naming. Defaults to false.

• te30 (bool) – request hierarchical meter handling in the 30-house test harness. Defaults to false.

tesp_support.original.glm_dictionary.isCommercialHouse(house_class)

tesp_support.original.glm_dictionary.ti_enumeration_string(tok)

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

tesp_support.original.hvac_agent module

Class that controls the responsive thermostat for one house.

Implements the ramp bidding method, with HVAC power as the bid quantity, and thermostat setting changes as the response mechanism.

class tesp_support.original.hvac_agent.hvac(hvac_dict, key, aucObj)

Bases: object

This agent manages thermostat setpoint and bidding for a house

Parameters:

• hvac_dict (dict) – dictionary row for this agent from the JSON configuration file

• key (str) – name of this agent, also key for its dictionary row

• aucObj (simple_auction) – the auction this agent bids into

name

name of this agent

Type:

str

control_mode

control mode from dict (CN_RAMP or CN_NONE, which still implements the setpoint schedule)

Type:

str

houseName

name of the corresponding house in GridLAB-D, from dict

Type:

str

meterName

name of the corresponding triplex_meter in GridLAB-D, from dict

Type:

str

period

market clearing period, in seconds, from dict

Type:

float

wakeup_start

hour of the day (0..24) for scheduled weekday wakeup period thermostat setpoint, from dict

Type:

float

daylight_start

hour of the day (0..24) for scheduled weekday daytime period thermostat setpoint, from dict

Type:

float

evening_start

hour of the day (0..24) for scheduled weekday evening (return home) period thermostat setpoint, from dict

Type:

float

night_start

hour of the day (0..24) for scheduled weekday nighttime period thermostat setpoint, from dict

Type:

float

wakeup_set

preferred thermostat setpoint for the weekday wakeup period, in deg F, from dict

Type:

float

daylight_set

preferred thermostat setpoint for the weekday daytime period, in deg F, from dict

Type:

float

evening_set

preferred thermostat setpoint for the weekday evening (return home) period, in deg F, from dict

Type:

float

night_set

preferred thermostat setpoint for the weekday nighttime period, in deg F, from dict

Type:

float

weekend_day_start

hour of the day (0..24) for scheduled weekend daytime period thermostat setpoint, from dict

Type:

float

weekend_day_set

preferred thermostat setpoint for the weekend daytime period, in deg F, from dict

Type:

float

weekend_night_start

hour of the day (0..24) for scheduled weekend nighttime period thermostat setpoint, from dict

Type:

float

weekend_night_set

preferred thermostat setpoint for the weekend nighttime period, in deg F, from dict

Type:

float

deadband

thermostat deadband in deg F, invariant, from dict

Type:

float

offset_limit

maximum allowed change from the time-scheduled setpoint, in deg F, from dict

Type:

float

ramp

bidding ramp denominator in multiples of the price standard deviation, from dict

Type:

float

price_cap

the highest allowed bid price in $/kwh, from dict

Type:

float

bid_delay

from dict, not implemented

Type:

float

use_predictive_bidding

from dict, not implemented

Type:

float

std_dev

standard deviation of expected price, determines the bidding ramp slope, initialized from aucObj

Type:

float

mean

mean of the expected price, determines the bidding ramp origin, initialized from aucObj

Type:

float

Trange

the allowed range of setpoint variation, bracketing the preferred time-scheduled setpoint

Type:

float

air_temp

current air temperature of the house in deg F

Type:

float

hvac_kw

most recent non-zero HVAC power in kW, this will be the bid quantity

Type:

float

mtr_v

current line-neutral voltage at the triplex meter

Type:

float

hvac_on

True if the house HVAC is currently running

Type:

bool

basepoint

the preferred time-scheduled thermostat setpoint in deg F

Type:

float

setpoint

the thermostat setpoint, including price response, in deg F

Type:

float

bid_price

the current bid price in $/kwh

Type:

float

cleared_price

the cleared market price in $/kwh

Type:

float

bid_accepted()

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

Returns:

True if the thermostat setting changes, False if not.

Return type:

bool

change_basepoint(hod, dow)

Updates the time-scheduled thermostat setting

Parameters:

• hod (float) – the hour of the day, from 0 to 24

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

Returns:

True if the setting changed, False if not

Return type:

bool

formulate_bid()

Bid to run the air conditioner through the next period

Returns:

bid price in $/kwh, bid quantity in kW and current HVAC on state, or None if not bidding

Return type:

[float, float, bool]

inform_bid(price)

Set the cleared_price attribute

Parameters:

price (float) – cleared price in $/kwh

set_air_temp_from_fncs_str(val)

Sets the air_temp attribute

Parameters:

val (str) – FNCS message with temperature in degrees Fahrenheit

set_air_temp_from_helics(val)

set_hvac_load_from_fncs_str(val)

Sets the hvac_load attribute, if greater than zero

Parameters:

val (str) – FNCS message with load in kW

set_hvac_load_from_helics(val)

set_hvac_state_from_fncs_str(val)

Sets the hvac_on attribute

Parameters:

val (str) – FNCS message with state, ON or OFF

set_hvac_state_from_helics(val)

set_voltage_from_fncs_str(val)

Sets the mtr_v attribute

Parameters:

val (str) – FNCS message with meter line-neutral voltage

set_voltage_from_helics(val)

tesp_support.original.parse_msout module

tesp_support.original.parse_msout.next_matrix(fp, var)

tesp_support.original.parse_msout.next_val(fp, var, bInteger=True)

tesp_support.original.parse_msout.read_most_solution(fname='msout.txt')

tesp_support.original.player_f module

tesp_support.original.player_f.load_player_loop_f(casename, keyName)

tesp_support.original.precool module

Classes for NIST TE Challenge 2 example

The precool_loop class manages time stepping and FNCS messages for the precooler agents, which adjust thermostat set points in response to time-of-use rates and over voltages. The precooler agents also estimate house equivalent thermal parameter (ETP) models based on total floor area, number of stories, number of exterior doors and estimated thermal integrity level. This ETP estimate serves as an example for other agent developers; it’s not actually used by the precooler agent.

Public Functions:

precooler_loop:

Initializes and runs the precooler agents.

tesp_support.original.precool.fncs_precool_loop(nhours, metrics_root, dict_root, response)

Function that supervises FNCS messages and time stepping for precooler agents

Opens metrics_root_agent_dict.json and metrics_root_glm_dict.json for configuration. Writes precool_metrics_root.json at completion.

Parameters:

• nhours (float) – number of hours to simulate

• metrics_root (str) – name of the case, without file extension

• dict_root (str) – repeat metrics_root, or the name of a shared case dictionary without file extension

• response (str) – combination of Price and/or Voltage

tesp_support.original.precool.helics_precool_loop(nhours, metrics_root, dict_root, response, helicsConfig)

Function that supervises FNCS messages and time stepping for precooler agents

Opens metrics_root_agent_dict.json and metrics_root_glm_dict.json for configuration. Writes precool_metrics_root.json at completion.

Parameters:

• nhours (float) – number of hours to simulate

• metrics_root (str) – name of the case, without file extension

• dict_root (str) – repeat metrics_root, or the name of a shared case dictionary without file extension

• response (str) – combination of Price and/or Voltage

• helicsConfig (str) – name for HELICS message file

tesp_support.original.precool.precool_loop(nhours, metrics_root, dict_root, response='PriceVoltage', helicsConfig=None)

Wrapper for inner_substation_loop

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

class tesp_support.original.precool.precooler(name, agentrow, gldrow, k, mean, stddev, lockout_time, precooling_quiet, precooling_off, bPrice, bVoltage)

Bases: object

This agent manages the house thermostat for time-of-use and overvoltage responses.

References

NIST TE Modeling and Simulation Challenge

Parameters:

• name (str) – name of this agent

• agentrow (dict) – row from the FNCS configuration dictionary for this agent

• gldrow (dict) – row from the GridLAB-D metadata dictionary for this agent’s house

• k (float) – bidding function denominator, in multiples of stddev

• mean (float) – mean of the price

• stddev (float) – standard deviation of the price

• lockout_time (float) – time in seconds between allowed changes due to voltage

• precooling_quiet (float) – time of day in seconds when precooling is allowed

• precooling_off (float) – time of day in seconds when overvoltage precooling is always turned off

name

name of this agent

Type:

str

meterName

name of the corresponding triplex_meter in GridLAB-D, from agentrow

Type:

str

night_set

preferred thermostat setpoint during nighttime hours, deg F, from agentrow

Type:

float

day_set

preferred thermostat setpoint during daytime hours, deg F, from agentrow

Type:

float

day_start_hour

hour of the day when daytime thermostat setting period begins, from agentrow

Type:

float

day_end_hour

hour of the day when daytime thermostat setting period ends, from agentrow

Type:

float

deadband

thermostat deadband in deg F, invariant, from agentrow, from agentrow

Type:

float

vthresh

meter line-to-neutral voltage that triggers precooling, from agentrow

Type:

float

toffset

temperature setpoint change for precooling, in deg F, from agentrow

Type:

float

k

bidding function denominator, in multiples of stddev

Type:

float

mean

mean of the price

Type:

float

stddev

standard deviation of the price

Type:

float

lockout_time

time in seconds between allowed changes due to voltage

Type:

float

precooling_quiet

time of day in seconds when precooling is allowed

Type:

float

precooling_off

time of day in seconds when overvoltage precooling is always turned off

Type:

float

air_temp

current air temperature of the house in deg F

Type:

float

mtr_v

current line-neutral voltage at the triplex meter

Type:

float

basepoint

the preferred time-scheduled thermostat setpoint in deg F

Type:

float

setpoint

the thermostat setpoint, including price response, in deg F

Type:

float

lastchange

time of day in seconds when the setpoint was last changed

Type:

float

precooling

True if the house is precooling, False if not

Type:

bool

ti

thermal integrity level, as enumerated for GridLAB-D, from gldrow

Type:

int

sqft (float

total floor area in square feet, from gldrow

stories

number of stories, from gldrow

Type:

int

doors

number of exterior doors, from gldrow

Type:

int

UA

heat loss coefficient

Type:

float

CA

total air thermal mass

Type:

float

HM

interior mass surface conductance

Type:

float

CM

total house thermal mass

Type:

float

check_setpoint_change(hour_of_day, price, time_seconds)

Update the setpoint for time of day and price

Parameters:

• hour_of_day (float) – the current time of day, 0..24

• price (float) – the current price in $/kwh

• time_seconds (long long) – the current FNCS time in seconds

Returns:

True if the setpoint changed, False if not

Return type:

bool

get_temperature_deviation()

For metrics, find the difference between air temperature and time-scheduled (preferred) setpoint

Returns:

absolute value of deviation

Return type:

float

make_etp_model()

Sets the ETP parameters from configuration data

References

Thermal Integrity Table Inputs and Defaults

set_air_temp(val)

Set the air_temp member variable

Parameters:

val (str) – FNCS/HELICS message with temperature in degrees Fahrenheit

set_voltage(val)

Sets the mtr_v attribute

Parameters:

val (str) – HELICS message with meter line-neutral voltage

set_voltage_f(val)

Sets the mtr_v attribute

Parameters:

val (str) – FNCS message with meter line-neutral voltage

tesp_support.original.prep_eplus module

tesp_support.original.prep_eplus.configure_eplus(caseConfig, template_dir)

tesp_support.original.prep_eplus.make_gld_eplus_case(fname, bGlmReady=False)

tesp_support.original.prep_eplus.prepare_bldg_dict(caseConfig)

tesp_support.original.prep_eplus.prepare_glm_dict(caseConfig)

tesp_support.original.prep_eplus.prepare_glm_file(caseConfig)

tesp_support.original.prep_eplus.prepare_glm_helics(caseConfig, fedMeters, fedLoadNames)

tesp_support.original.prep_eplus.prepare_run_script(caseConfig, fedMeters)

tesp_support.original.prep_eplus.writeGlmClass(theseLines, thisClass, op)

tesp_support.original.prep_precool module

Writes the precooling agent and GridLAB-D metadata for NIST TE Challenge 2 example

Public Functions:

prep_precool:

writes the JSON and YAML files

tesp_support.original.prep_precool.prep_precool(name_root, time_step=15)

Sets up agent configurations for the NIST TE Challenge 2 example

Reads the GridLAB-D data from name_root.glm; it should contain houses with thermal_integrity_level attributes. Writes:

• [name_root]_agent_dict.json, contains configuration data for the precooler agents

• [name_root]_precool.yaml, contains FNCS subscriptions for the precooler agents

• [name_root]_gridlabd.txt, a GridLAB-D include file with FNCS publications and subscriptions

Parameters:

• name_root (str) – the name of the GridLAB-D file, without extension

• time_step (int) – time step period

tesp_support.original.prep_substation module

Sets up the FNCS and agent configurations for te30 and sgip1 examples

This works for other TESP cases that have one GridLAB-D file, one EnergyPlus model, and one PYPOWER model. Use tesp_case or tesp_config modules to specify supplemental configuration data for these TESP cases, to be provided as the optional jsonfile argument to prep_substation.

Public Functions:

prep_substation:

processes a GridLAB-D file for one substation and one or more feeders

tesp_support.original.prep_substation.ProcessGLM(fileroot)

Helper function that processes one GridLAB-D file

Reads fileroot.glm and writes:

• [fileroot]_agent_dict.json, contains configuration data for the simple_auction and hvac agents

• [fileroot]_substation.yaml, contains FNCS subscriptions for the psimple_auction and hvac agents

• [fileroot]_gridlabd.txt, a GridLAB-D include file with FNCS publications and subscriptions

• [fileroot]_substation.json, contains HELICS subscriptions for the psimple_auction and hvac agents

• [fileroot]_gridlabd.json, a GridLAB-D include file with HELICS publications and subscriptions

Parameters:

fileroot (str) – path to and base file name for the GridLAB-D file, without an extension

tesp_support.original.prep_substation.prep_substation(gldfileroot, jsonfile='', bus_id=None)

Process a base GridLAB-D file with supplemental JSON configuration data

If provided, this function also reads jsonfile as created by tesp_config and used by tesp_case. This supplemental data includes time-scheduled thermostat set points (NB: do not use the scheduled set point feature within GridLAB-D, as the first FNCS messages will erase those schedules during simulation). The supplemental data also includes time step and market period, the load scaling factor to PYPOWER, ramp bidding function parameters and the EnergyPlus connection point. If not provided, the default values from te30 and sgip1 examples will be used.

Parameters:

• gldfileroot (str) – path to and base file name for the GridLAB-D file, without an extension

• jsonfile (str) – fully qualified path to an optional JSON configuration file (if not provided, an E+ connection to Eplus_load will be created)

• bus_id – substation bus identifier

tesp_support.original.process_agents module

Functions to plot data from GridLAB-D substation agents

Public Functions:

process_agents:

Reads the data and metadata, then makes the plots.

tesp_support.original.process_agents.plot_agents(diction, save_file=None, save_only=False)

tesp_support.original.process_agents.process_agents(name_root, diction_name='', save_file=None, save_only=False, print_dictionary=False)

Plots cleared price, plus bids from the first HVAC controller

This function reads auction_[name_root]_metrics.json and controller_[name_root]_metrics.json for the data; it reads [name_root]_glm_dict.json for the metadata. These must all exist in the current working directory. Makes one graph with 2 subplots:

1. Cleared price from the only auction, and bid price from the first controller

2. Bid quantity from the first controller

Parameters:

• name_root (str) – name of the TESP case, not necessarily the same as the GLM case, without the extension

• diction_name (str) – metafile name (with json extension) for a different GLM dictionary, if it’s not [name_root]_glm_dict.json. Defaults to empty.

• save_file (str) – name of a file to save plot, should include the png or pdf extension to determine type.

• save_only (bool) – set True with save_file to skip the display of the plot. Otherwise, script waits for user keypress.

• print_dictionary (bool) – set True to print dictionary.

tesp_support.original.process_agents.read_agent_metrics(path, name_root, diction_name='', print_dictionary=False)

tesp_support.original.residential_feeder_glm module

tesp_support.original.simple_auction module

Double-auction mechanism for the 5-minute markets in te30 and sgip1 examples

The substation_loop module manages one instance of this class per GridLAB-D substation.

Todo

• Initialize and update price history statistics

• Allow for adjustment of clearing_scalar

• Handle negative price bids from HVAC agents, currently they are discarded

• Distribute marginal quantities and fractions; these are not currently applied to HVACs

2021-10-29 TDH: Key assumptions we need to refactor out of this: - This is a retail market working under a wholesale market. We want something more general that can operate at any market level. - Load state is not necessary information to run a market. PNNL TSP has traditionally had the construct of responsive and unresponsive loads and I think the idea is crucial for being able to get good quadratic curve fits on the demand curve (by lopping off the unresponsive portion) but I think we should refactor this so that these assumptions are not so tightly integrated with the formulation.

class tesp_support.original.simple_auction.simple_auction(diction, key)

Bases: object

This class implements a simplified version of the double-auction market embedded in GridLAB-D.

References

Market Module Overview - Auction

Parameters:

• diction (diction) – a row from the agent configuration JSON file

• key (str) – the name of this agent, which is the market key from the agent configuration JSON file

name

the name of this auction, also the market key from the configuration JSON file

Type:

str

std_dev

the historical standard deviation of the price, in $/kwh, from diction

Type:

float

mean

the historical mean price in $/kwh, from diction

Type:

float

price_cap

the maximum allowed market clearing price, in $/kwh, from diction

Type:

float

max_capacity_reference_bid_quantity

this market’s maximum capacity, likely defined by a physical limitation in the circuit(s) being managed.

Type:

float

statistic_mode

always 1, not used, from diction

Type:

int

stat_mode

always ST_CURR, not used, from diction

Type:

str

stat_interval

always 86400 seconds, for one day, not used, from diction

Type:

str

stat_type

always mean and standard deviation, not used, from diction

Type:

str

stat_value

always zero, not used, from diction

Type:

str

curve_buyer

data structure to accumulate buyer bids

Type:

curve

curve_seller

data structure to accumulate seller bids

Type:

curve

refload

the latest substation load from GridLAB-D. This is initially assumed to be all unresponsive and using the load state parameter when adding demand bids (which are generally price_responsive) all loads that bid and are on are removed from the assumed unresponsive load value

Type:

float

lmp

the latest locational marginal price from the bulk system market

Type:

float

unresp

unresponsive load, i.e., total substation load less the bidding, running HVACs

Type:

float

agg_unresp

aggregated unresponsive load, i.e., total substation load less the bidding, running HVACs

Type:

float

agg_resp_max

total load of the bidding HVACs

Type:

float

agg_deg

degree of the aggregate bid curve polynomial, should be 0 (zero or one bids), 1 (2 bids) or 2 (more bids)

Type:

int

agg_c2

second-order coefficient of the aggregate bid curve

Type:

float

agg_c1

first-order coefficient of the aggregate bid curve

Type:

float

clearing_type

describes the solution type or boundary case for the latest market clearing

Type:

ClearingType

clearing_quantity

quantity at the last market clearing

Type:

float

clearing_price

price at the last market clearing

Type:

float

marginal_quantity

quantity of a partially accepted bid

Type:

float

marginal_frac

fraction of the bid quantity accepted from a marginal buyer or seller

Type:

float

clearing_scalar

used for interpolation at boundary cases, always 0.5

Type:

float

add_unresponsive_load(quantity)

aggregate_bids()

Aggregates the unresponsive load and responsive load bids for submission to the bulk system market

clear_bids()

Re-initializes curve_buyer and curve_seller, sets the unresponsive load estimate to the total substation load.

clear_market(tnext_clear=0, time_granted=0)

Solves for the market clearing price and quantity

Uses the current contents of curve_seller and curve_buyer. Updates clearing_price, clearing_quantity, clearing_type, marginal_quantity and marginal_frac.

Parameters:

• tnext_clear (int) – next clearing time in seconds, should be <= time_granted, for the log file only

• time_granted (int) – the current time in seconds, for the log file only

collect_bid(bid)

Gather HVAC bids into curve_buyer

Also adjusts the unresponsive load estimate, by subtracting the HVAC power if the HVAC is on.

Parameters:

bid ([float, float, bool]) – price in $/kwh, quantity in kW and the HVAC on state

initAuction()

Sets the clearing_price and lmp to the mean price

2021-10-29 TDH: TODO - Any reason we can’t put this in constructor?

set_lmp(lmp)

Sets the lmp attribute

Parameters:

lmp (float) – locational marginal price from the bulk system market

set_refload(kw)

Sets the refload attribute

Parameters:

kw (float) – GridLAB-D substation load in kw

supplier_bid(bid)

Gather supplier bids into curve_seller

Use this to enter curves in step-wise blocks.

Parameters:

bid ([float, float]) – price in $/kwh, quantity in kW

surplusCalculation(tnext_clear=0, time_granted=0)

Calculates consumer surplus (and its average) and supplier surplus.

This function goes through all the bids higher than clearing price from buyers to calculate consumer surplus, and also accumulates the quantities that will be cleared while doing so. Of the cleared quantities, the quantity for unresponsive loads are also collected. Then go through each seller to calculate supplier surplus. Part of the supplier surplus corresponds to unresponsive load are excluded and calculated separately.

Parameters:

• tnext_clear (int) – next clearing time in seconds, should be <= time_granted, for the log file only

• time_granted (int) – the current time in seconds, for the log file only

update_statistics()

Update price history statistics - not implemented

tesp_support.original.substation_f module

Manages the simple_auction and hvac agents for the te30 and sgip1 examples

Public Functions:

substation_loop_f:

initializes and runs the agents

Todo

• Getting an overflow error when killing process - investigate whether that happens if simulation runs to completion

• Allow changes in the starting date and time; now it’s always midnight on July 1, 2013

• Allow multiple markets per substation, e.g., 5-minute and day-ahead for the DSO+T study

tesp_support.original.tesp_case module

tesp_support.original.tesp_config module

tesp_support.original.tesp_monitor module

Presents a GUI to launch a TESP simulation and monitor its progress

Public Functions:

show_tesp_monitor:

Initializes and runs the monitor GUI

References

Graphical User Interfaces with Tk

Matplotlib Animation

class tesp_support.original.tesp_monitor.TespMonitorGUI(master, HELICS=True)

Bases: object

Manages a GUI with 4 plotted variables, and buttons to stop TESP

The GUI reads a JSON file with scripted shell commands to launch other HELICS/FNCS federates, and a YAML file with HELICS/FNCS subscriptions to update the solution status. Both JSON and YAML files are written by tesp.tesp_config The plotted variables provide a sign-of-life and sign-of-stability indication for each of the major federates in the te30 or sgip1 examples, namely GridLAB-D, PYPOWER, EnergyPlus, and the substation_loop that manages a simple_auction with multiple hvac agents. If a solution appears to be unstable or must be stopped for any other reason, exiting the solution monitor will do so.

The plots are created and updated with animated and bit-blitted Matplotlib graphs hosted on a TkInter GUI. When the JSON and YAML files are loaded, the x axis is laid out to match the total TESP simulation time range.

Parameters:

master

root

the TCL Tk toolkit instance

Type:

Tk

top

the top-level TCL Tk Window

Type:

Window

labelvar

used to display the monitor JSON configuration file path

Type:

StringVar

hrs

x-axis data array for time in hours, shared by all plots

Type:

[float]

y0

y-axis data array for PYPOWER bus voltage

Type:

[float]

y1

y-axis data array for EnergyPlus load

Type:

[float]

y2lmp

y-axis data array for PYPOWER LMP

Type:

[float]

y2auc

y-axis data array for simple_auction cleared_price

Type:

[float]

y3fncs

y-axis data array for GridLAB-D load via FNCS

Type:

[float]

y3gld

y-axis data array for sample-and-hold GridLAB-D load

Type:

[float]

gld_load

the most recent load published by GridLAB-D; due to the deadband, this value isn’t necessary published at every FNCS time step

Type:

float

y0min

the first y axis minimum value

Type:

float

y0max

the first y axis maximum value

Type:

float

y1min

the second y axis minimum value

Type:

float

y1max

the second y axis maximum value

Type:

float

y2min

the third y axis minimum value

Type:

float

y2max

the third y axis maximum value

Type:

float

y3min

the fourth y axis minimum value

Type:

float

y3max

the fourth y axis maximum value

Type:

float

hour_stop

the maximum x axis time value to plot

Type:

float

ln0

the plotted PYPOWER bus voltage, color GREEN

Type:

Line2D

ln1

the plotted EnergyPlus load, color RED

Type:

Line2D

ln2lmp

the plotted PYPOWER locational marginal price (LMP), color BLUE

Type:

Line2D

ln2auc

the plotted simple_auction cleared_price, color BLACK

Type:

Line2D

ln3gld

the plotted sample-and-hold GridLAB-D substation load, color MAGENTA

Type:

Line2D

ln3fncs

the plotted GridLAB-D substation load published via FNCS; may be zero if not published for the current animation frame, color CYAN

Type:

Line2D

fig

animated Matplotlib figure hosted on the GUI

Type:

Figure

ax

set of 4 xy axes to plot on

Type:

Axes

canvas

a TCL Tk canvas that can host Matplotlib

Type:

FigureCanvasTkAgg

bFNCSactive

True if a TESP simulation is running with other FNCS federates, False if not

Type:

bool

bHELICSactive

True if a TESP simulation is running with other HELICS federates, False if not

Type:

bool

OpenConfig()

Read the JSON configuration file for this monitor, and initialize the plot axes

Quit()

Shuts down this monitor, and also shuts down FNCS/HELICS if active

expand_limits(v, vmin, vmax)

Whenever a variable meets a vertical axis limit, expand the limits with 10% padding above and below

Parameters:

• v (float) – the out of range value

• vmin (float) – the current minimum vertical axis value

• vmax (float) – the current maximum vertical axis value

Returns:

the new vmin and vmax

Return type:

float, float

kill_all()

Shut down all FNCS/HELICS federates in TESP, except for this monitor

launch_all()

Launches the simulators, initializes HELICS and starts the animated plots

launch_all_f()

Launches the simulators, initializes FNCS and starts the animated plots

on_closing()

Verify whether the user wants to stop TESP simulations before exiting the monitor

This monitor is itself a FNCS federate, so it can not be shut down without shutting down all other FNCS federates in the TESP simulation.

reset_plot()

update_plots(i)

This function is called by Matplotlib for each animation frame

Each time called, collect HELICS messages until the next time to plot has been reached. Then update the plot quantities and return the Line2D objects that have been updated for plotting. Check for new data outside the plotted vertical range, which triggers a full re-draw of the axes. On the last frame, finalize HELICS.

Args:

i (int): the animation frame number

update_plots_f(i)

This function is called by Matplotlib for each animation frame

Each time called, collect FNCS messages until the next time to plot has been reached. Then update the plot quantities and return the Line2D objects that have been updated for plotting. Check for new data outside the plotted vertical range, which triggers a full re-draw of the axes. On the last frame, finalize FNCS.

Args:

i (int): the animation frame number

tesp_support.original.tesp_monitor.show_tesp_monitor(HELICS=True)

Creates and displays the monitor GUI

tesp_support.original.tesp_monitor_ercot module

Presents a GUI to launch a TESP simulation and monitor its progress

This version differs from the one in tesp_monitor, in that the user can select the FNCS federate and topic to plot. The number of monitored plots is still fixed at 4.

Public Functions:

show_tesp_monitor:

Initializes and runs the monitor GUI

References

Graphical User Interfaces with Tk

Matplotlib Animation

class tesp_support.original.tesp_monitor_ercot.ChoosablePlot(master, color='red', xLabel='', topicDict={}, **kwargs)

Bases: Frame

Hosts one Matplotlib animation with a selected variable to plot

Parameters:

• master

• color (str) – Matplotlib color of the line to plot

• xLabel (str) – label for the x axis

• topicDict (dict) – dictionary of FNCS topic choices to plot

• kwargs – arbitrary keyword arguments

topicDict

listOfTopics

root

the TCL Tk toolkit instance

Type:

Tk

fig

animated Matplotlib figure hosted on the GUI

Type:

Figure

ax

set of 4 xy axes to plot on

Type:

Axes

xLabel

horizontal axis label

Type:

str

yLabel

vertical axis label

Type:

str

hrs

y

ymin

Type:

float

ymax

Type:

float

color

title

Type:

str

ln

Type:

Line2D

topicSelectionRow

topicLabel

combobox

voltageLabel

voltageBase

voltageBaseTextbox

onTopicSelected(event)

Change the GUI labels to match selected plot variable

Parameters:

event

class tesp_support.original.tesp_monitor_ercot.TespMonitorGUI(master)

Bases: object

Version of the monitor GUI that hosts 4 choosable plots

Parameters:

master

root

the TCL Tk toolkit instance

Type:

Tk

top

the top-level TCL Tk Window

Type:

Window

labelvar

used to display the monitor JSON configuration file path

Type:

StringVar

plot0

first plot

Type:

ChoosablePlot

plot1

second plot

Type:

ChoosablePlot

plot2

third plot

Type:

ChoosablePlot

plot3

fourth plot

Type:

ChoosablePlot

topicDict

plots

Type:

Frame

scrollbar

Type:

Scrollbar

frameInCanvas

Type:

Frame

canvas

a TCL Tk canvas that can host Matplotlib

Type:

FigureCanvasTkAgg

bFNCSactive

True if a TESP simulation is running with other FNCS federates, False if not

Type:

bool

CalculateValue(topic, value, plot)

Parses a value from FNCS to plot

Parameters:

• topic (str) – the FNCS topic

• value (str) – the FNCS value

• plot (ChoosablePlot) – the plot that will be updated; contains the voltage base if needed

Returns:

the parsed value

Return type:

float

OpenConfig()

Read the JSON configuration file for this monitor, and initialize the plot axes

Quit()

Shuts down this monitor, and also shuts down FNCS if active

kill_all()

Shut down all FNCS federates in TESP, except for this monitor

launch_all()

Launches the simulators, initializes FNCS and starts the animated plots

onFrameConfigure(event)

Reset the scroll region to encompass the inner frame

on_closing()

Verify whether the user wants to stop TESP simulations before exiting the monitor

This monitor is itself a FNCS federate, so it can not be shut down without shutting down all other FNCS federates in the TESP simulation.

update_plots(i)

This function is called by Matplotlib for each animation frame

Each time called, collect FNCS messages until the next time to plot has been reached. Then update the plot quantities and return the Line2D objects that have been updated for plotting. Check for new data outside the plotted vertical range, which triggers a full re-draw of the axes. On the last frame, finalize FNCS.

Args:

i (int): the animation frame number

tesp_support.original.tesp_monitor_ercot.show_tesp_monitor()

Creates and displays the monitor GUI

tesp_support.original.tso_PYPOWER_f module

PYPOWER solutions under control of FNCS or HELICS for te30 and dsot, sgip1 examples

Public Functions:

pypower_loop:

Initializes and runs the simulation.

tesp_support.original.tso_psst_f module

tesp_support.original.tso_psst_f.make_generator_plants(ppc, renewables)