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.commercial_feeder_glm.create_comm_zones(bldg, comm_loads, key, op, batt_metadata, storage_percentage, ev_metadata, ev_percentage, solar_percentage, pv_rating_MW, solar_Q_player, case_type, metrics, metrics_interval, mode=None)
For large buildings, breaks building up into multiple zones.
For all buildings sends definition dictionary to function that writes out building definition to GLD file format.
- Parameters:
bldg (dict) – dictionary of building parameters for the building to be processed.
comm_loads –
key (str) – name of feeder node or meter being used
op (any) – GLD output file
batt_metadata –
storage_percentage –
ev_metadata –
ev_percentage –
solar_percentage –
pv_rating_MW –
solar_Q_player –
case_type –
metrics –
metrics_interval –
mode (str) – if ‘test’ will ensure that GLD output function does not set parent - allows buildings to be run in GLD without feeder info
- tesp_support.original.commercial_feeder_glm.define_comm_bldg(bldg_metadata, dso_type, num_bldgs)
Randomly selects a set number of buildings by type and size (sq. ft.)
- Parameters:
bldg_metadata – dictionary of DSO+T specific building parameter data
dso_type – ‘Urban’, ‘Suburban’, or ‘Rural’
num_bldgs – scalar value of number of buildings to be selected
- tesp_support.original.commercial_feeder_glm.define_comm_loads(bldg_type, bldg_size, dso_type, climate, bldg_metadata)
Determines building parameters based on building type, dso type, and (ASHRAE) climate zone
- Parameters:
bldg_type (str) – class of building (e.g. ‘strip_mall’, etc.)
bldg_size – size of the building in sq. ft.
dso_type (str) – whether the dso is ‘Urban’, ‘Suburban’, or ‘Rural’
climate (str) – ASHRAE climate zone that the DSO resides in (e.g. ‘2A’)
bldg_metadata – dictionary of DSO+T specific building parameter data
- tesp_support.original.commercial_feeder_glm.find_envelope_prop(prop, age, env_data, climate)
- Returns the envelope value for a given type of property based on the age and (ASHRAE) climate zone of the
building
- Parameters:
prop (str) – envelope material property of interest (e.g. ‘wood-framed’ or ‘u-windows’)
age (int) – age of the building in question (typically between 1945 and present).
env_data (dict) – Dictionary of envelope property data
climate ('string') – ASHRAE climate zone of building (e.g. ‘2A’)
- Returns:
property value - typically a U-value.
- Return type:
val (float)
- tesp_support.original.commercial_feeder_glm.normalize_dict_prob(name, diction)
Ensures that the probability distribution of values in a dictionary effectively sums to one
- Parameters:
name – name of dictionary to normalize
diction – dictionary of elements and associated non-cumulative probabilities
- tesp_support.original.commercial_feeder_glm.rand_bin_select(diction, probability)
Returns the element (bin) in a dictionary given a certain probability
- Parameters:
diction – dictionary of elements and associated non-cumulative probabilities
probability – scalar value between 0 and 1
- tesp_support.original.commercial_feeder_glm.sub_bin_select(_bin, _type, _prob)
Returns a scalar value within a bin range based on a uniform probability within that bin range
- Parameters:
_bin – name of bin
_type – building parameter describing set of bins
_prob – scalar value between 0 and 1
- tesp_support.original.commercial_feeder_glm.write_one_commercial_zone(bldg, op, metrics, metrics_interval, mode=None)
Write one pre-configured commercial zone as a house
- Parameters:
bldg – dictionary of GridLAB-D house and zipload attributes
op (file) – open file to write to
metrics (list) –
metrics_interval (int) –
mode (str) – if in ‘test’ mode will not write out parent info.
tesp_support.original.copperplate_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
- 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.original.copperplate_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.original.copperplate_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.original.copperplate_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.original.copperplate_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.original.copperplate_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.original.copperplate_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.original.copperplate_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.original.copperplate_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.original.copperplate_feeder_glm.checkResidentialBuildingTable()
Verify that the regional building parameter histograms sum to one
- tesp_support.original.copperplate_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.original.copperplate_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.original.copperplate_feeder_glm.getDsoThermalTable(dso_type)
- tesp_support.original.copperplate_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.original.copperplate_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.original.copperplate_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.original.copperplate_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.original.copperplate_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.original.copperplate_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.original.copperplate_feeder_glm.populate_feeder(config=None)
Wrapper function that processes one feeder. One or two keyword arguments must be supplied.
- Parameters:
config (dict) – dictionary of feeder population data already read in, mutually exclusive with configfile
- tesp_support.original.copperplate_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.original.copperplate_feeder_glm.selectResidentialBuilding(rgnTable, prob)
Selects the building with region and probability
- Parameters:
rgnTable –
prob –
- tesp_support.original.copperplate_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.original.copperplate_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.original.copperplate_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.original.copperplate_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.original.copperplate_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.original.copperplate_feeder_glm.write_link_class(model, h, t, seg_loads, op)
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.original.copperplate_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.original.copperplate_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.original.copperplate_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.original.copperplate_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.original.copperplate_feeder_glm.write_tariff(op)
Writes tariff information to billing meters
- Parameters:
op (file) – an open GridLAB-D input file
- tesp_support.original.copperplate_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.original.copperplate_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.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
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
- 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:
Cleared price from the only auction, and bid price from the first controller
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
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 <https://github.com/GRIDAPPSD/Powergrid-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
- tesp_support.original.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.original.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.original.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.original.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.original.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.original.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.original.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.original.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.original.residential_feeder_glm.checkResidentialBuildingTable()
Verify that the regional building parameter histograms sum to one
- tesp_support.original.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.original.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.original.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.original.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.original.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.original.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.original.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.original.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.original.residential_feeder_glm.populate_all_feeders()
Wrapper function that batch processes all taxonomy feeders in the casefiles table (see source file)
- tesp_support.original.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.original.residential_feeder_glm.randomize_commercial_skew()
- tesp_support.original.residential_feeder_glm.randomize_residential_skew()
- tesp_support.original.residential_feeder_glm.randomize_skew(value, skew_max)
- tesp_support.original.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.original.residential_feeder_glm.selectResidentialBuilding(rgnTable, prob)
Selects the building with region and probability
- Parameters:
rgnTable –
prob –
- tesp_support.original.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.original.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..6 for single-family, 0..2 for apartment or mobile home
- tesp_support.original.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.original.residential_feeder_glm.write_commercial_loads(rgn, key, op)
Put commercial building zones and ZIP loads into the model
- Parameters:
rgn (int) – region 1..5 where the building is located
key (str) – GridLAB-D load name that is being replaced
op (file) – open file to write to
- tesp_support.original.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.original.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.original.residential_feeder_glm.write_houses(basenode, op, vnom, bIgnoreThermostatSchedule=True, bWriteService=True, bTriplex=True, setpoint_offset=1.0)
Put houses, along with solar panels and batteries, onto a node
- Parameters:
basenode (str) – GridLAB-D node name
op (file) – open file to write to
vnom (float) – nominal line-to-neutral voltage at basenode
- tesp_support.original.residential_feeder_glm.write_kersting_quadriplex(fp, kva)
Writes a quadriplex_line_configuration based on 1/0 AA example from Kersting’s book
The conductor capacity is 202 amps, so the number of triplex in parallel will be kva/sqrt(3)/0.208/202
- tesp_support.original.residential_feeder_glm.write_kersting_triplex(fp, kva)
Writes a triplex_line_configuration based on 1/0 AA example from Kersting’s book
The conductor capacity is 202 amps, so the number of triplex in parallel will be kva/0.12/202
- tesp_support.original.residential_feeder_glm.write_link_class(model, h, t, seg_loads, op, want_metrics=False)
Write a GridLAB-D link (i.e. edge) class
- Parameters:
model (dict) – the parsed GridLAB-D model
h (dict) – the object ID hash
t (str) – the GridLAB-D class
seg_loads (dict) – a dictionary of downstream loads for each link
op (file) – an open GridLAB-D input file
- tesp_support.original.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.original.residential_feeder_glm.write_node_house_configs(fp, xfkva, xfkvll, xfkvln, phs, want_inverter=False)
Writes transformers, inverter settings for GridLAB-D houses at a primary load point.
An aggregated single-phase triplex or three-phase quadriplex line configuration is also written, based on estimating enough parallel 1/0 AA to supply xfkva load. This function should only be called once for each combination of xfkva and phs to use, and it should be called before write_node_houses.
- Parameters:
fp (file) – Previously opened text file for writing; the caller closes it.
xfkva (float) – the total transformer size to serve expected load; make this big enough to avoid overloads
xfkvll (float) – line-to-line voltage [kV] on the primary. The secondary voltage will be 208 three-phase
xfkvln (float) – line-to-neutral voltage [kV] on the primary. The secondary voltage will be 120/240 for split secondary
phs (str) – either ‘ABC’ for three-phase, or concatenation of ‘A’, ‘B’, and/or ‘C’ with ‘S’ for single-phase to triplex
want_inverter (bool) – True to write the IEEE 1547-2018 smarter inverter function setpoints
- tesp_support.original.residential_feeder_glm.write_node_houses(fp, node, region, xfkva, phs, nh=None, loadkw=None, house_avg_kw=None, secondary_ft=None, storage_fraction=0.0, solar_fraction=0.0, electric_cooling_fraction=0.5, node_metrics_interval=None, random_seed=False)
Writes GridLAB-D houses to a primary load point.
One aggregate service transformer is included, plus an optional aggregate secondary service drop. Each house has a separate meter or triplex_meter, each with a common parent, either a node or triplex_node on either the transformer secondary, or the end of the service drop. The houses may be written per phase, i.e., unbalanced load, or as a balanced three-phase load. The houses should be #included into a master GridLAB-D file. Before using this function, call write_node_house_configs once, and only once, for each combination xfkva/phs that will be used.
- Parameters:
fp (file) – Previously opened text file for writing; the caller closes it.
node (str) – the GridLAB-D primary node name
region (int) – the taxonomy region for housing population, 1..6
xfkva (float) – the total transformer size to serve expected load; make this big enough to avoid overloads
phs (str) – ‘ABC’ for three-phase balanced distribution, ‘AS’, ‘BS’, or ‘CS’ for single-phase triplex
nh (int) – directly specify the number of houses; an alternative to loadkw and house_avg_kw
loadkw (float) – total load kW that the houses will represent; with house_avg_kw, an alternative to nh
house_avg_kw (float) – average house load in kW; with loadkw, an alternative to nh
secondary_ft (float) – if not None, the length of adequately sized secondary circuit from transformer to the meters
electric_cooling_fraction (float) – fraction of houses to have air conditioners
solar_fraction (float) – fraction of houses to have rooftop solar panels
storage_fraction (float) – fraction of houses with solar panels that also have residential storage systems
node_metrics_interval (int) – if not None, the metrics collection interval in seconds for houses, meters, solar and storage at this node
random_seed (bool) – if True, reseed each function call. Default value False provides repeatability of output.
- tesp_support.original.residential_feeder_glm.write_one_commercial_zone(bldg, op)
Write one pre-configured commercial zone as a house
- Parameters:
bldg – dictionary of GridLAB-D house and zipload attributes
op (file) – open file to write to
- tesp_support.original.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.original.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.original.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.original.residential_feeder_glm.write_tariff(op)
Writes tariff information to billing meters
- Parameters:
op (file) – an open GridLAB-D input file
- tesp_support.original.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.original.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.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
- 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:
- 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
Creates and fills a subdirectory with files to run a TESP simulation
Use tesp_config to graphically edit the case configuration
- Public Functions:
- make_tesp_case:
sets up for a single-shot TESP case
- make_monte_carlo_cases:
sets up for a Monte Carlo TESP case of up to 20 shots
- first_tesp_feeder:
customization of make_tesp_case that will accept more feeders
- add_tesp_feeder:
add another feeder to the case directory created by first_tesp_feeder
- tesp_support.original.tesp_case.add_tesp_feeder(cfgfile)
Wrapper function to start a single TESP case configuration.
This function opens the JSON file, and calls write_tesp_case for just the GridLAB-D files. The subdirectory targetdir doesn’t have to match the case name in cfgfile, and it should be created first with make_tesp_case
- Parameters:
cfgfile (str) – JSON file containing the TESP case configuration
- tesp_support.original.tesp_case.make_monte_carlo_cases(cfgfile='test.json')
Writes up to 20 TESP simulation case setups to a directory for Monte Carlo simulations
Latin hypercube sampling is recommended; sample values may be specified via tesp_config
- Parameters:
cfgfile (str) – JSON file containing the TESP case configuration
- tesp_support.original.tesp_case.make_tesp_case(cfgfile='test.json')
Wrapper function for a single TESP case configuration.
This function opens the JSON file, and calls write_tesp_case
- Parameters:
cfgfile (str) – JSON file containing the TESP case configuration
- tesp_support.original.tesp_case.modify_mc_config(config, mcvar, band, sample)
Helper function that modifies the Monte Carlo configuration for a specific sample, i.e., shot
For variables that have a band associated, the agent preparation code will apply additional randomization. This applies to thermostat ramps, offset limits, and period starting or ending times. For those variables, the Monte Carlo sample value is a mean, and the agent preparation code will apply a uniform distribution to obtain the actual value for each house.
- tesp_support.original.tesp_case.write_tesp_case(config, cfgfile, freshdir=True)
Writes the TESP case from data structure to JSON file
This function assumes one GridLAB-D, one EnergyPlus, one PYPOWER and one substation_loop federate will participate in the TESP simulation. See the DSO+T study functions, which are customized to ERCOT 8-bus and 200-bus models, for examples of other configurations.
The TESP support directories, working directory and case name are all specified in config. This function will create one directory as follows:
workdir = config[‘SimulationConfig’][‘WorkingDirectory’]
casename = config[‘SimulationConfig’][‘CaseName’]
new directory created will be casedir = workdir/casename
This function will read or copy several files that are specified in the config. They should all exist. These include taxonomy feeders, GridLAB-D schedules, weather files, a base EnergyPlus model, a base PYPOWER model, and supporting scripts for the end user to invoke from the casedir. The user could add more base model files weather files or schedule files under the TESP support directory, where this tesp_case module will be able to find and use them.
This function will launch and wait for 6 subprocesses to assist in the case configuration. All must execute successfully:
TMY3toTMY2_ansi, which converts the user-selected TMY3 file to TMY2
tesp.convert_tmy2_to_epw, which converts the TMY2 file to EPW for EnergyPlus
tesp.TMY3toCSV, which converts the TMY3 file to CSV for the weather agent
tesp.populate_feeder, which populates the user-selected taxonomy feeder with houses and DER
tesp.glm_dict, which creates metadata for the populated feeder
tesp.prep_substation, which creates metadata and FNCS/HELICS configurations for the substation agents
As the configuration process finishes, several files are written to casedir:
casename.glm: the GridLAB-D model, copied and modified from the TESP support directory
casename_gridlabd.txt: FNCS subscriptions and publications, included by casename.glm
casename_agent_dict.json: metadata for the simple_auction and hvac agents
casename_glm_dict.json: metadata for casename.glm
casename_pp.json: the PYPOWER model, copied and modified from the TESP support directory
casename_substation.yaml: FNCS subscriptions and time step for the substation, which manages the simple_auction and hvac controllers
NonGLDLoad.txt: non-responsive load data for the PYPOWER model buses, currently hard-wired for the 9-bus model. See the ERCOT case files for examples of expanded options.
SchoolDualController.idf: the EnergyPlus model, copied and modified from the TESP support directory
WA-Yakima_Air_Terminal.epw: the selected weather file for EnergyPlus, others can be selected
WA-Yakima_Air_Terminal.tmy3: the selected weather file for GridLAB-D, others can be selected
appliance_schedules.glm: time schedules for GridLAB-D
clean.sh: Linux/Mac OS X helper to clean up simulation outputs
commercial_schedules.glm: non-responsive non-responsive time schedules for GridLAB-D, invariant
eplus.yaml: FNCS subscriptions and time step for EnergyPlus
eplus_agent.yaml: FNCS subscriptions and time step for the EnergyPlus agent
kill5570.sh: Linux/Mac OS X helper to kill all federates listening on port 5570
launch_auction.py: helper script for the GUI solution monitor to launch the substation federate
launch_pp.py: helper script for the GUI solution monitor to launch the PYPOWER federate
monitor.py: helper to launch the GUI solution monitor (FNCS_CONFIG_FILE envar must be set for this process, see gui.sh under examples/te30)
plots.py: helper script that will plot a selection of case outputs
pypower.yaml: FNCS subscriptions and time step for PYPOWER
run.sh: Linux/Mac OS X helper to launch the TESP simulation
monitor.json: shell commands and other configuration data for the solution monitor GUI
tesp_monitor.json: HELICS subscriptions and time step for the solution monitor GUI
tesp_monitor.yaml: FNCS subscriptions and time step for the solution monitor GUI
water_and_setpoint_schedule_v5.glm: non-responsive time schedules for GridLAB-D, invariant
weather.dat: CSV file of temperature, pressure, humidity, solar direct, solar diffuse and wind speed
casename_gridlabd.txt: HELICS subscriptions and publications, included by casename.glm
casename_substation.json: HELICS subscriptions and time step for the substation, which manages the simple_auction and hvac controllers
eplus.json: HELICS subscriptions and time step for EnergyPlus
eplus_agent.json: HELICS subscriptions and time step for the EnergyPlus agent
pypower.json: HELICS subscriptions and time step for PYPOWER
- Parameters:
config (dict) – the complete case data structure
cfgfile (str) – the name of the JSON file that was read
freshdir (bool) – flag to create the directory and base files anew
tesp_support.original.tesp_config module
Presents a GUI to configure and package TESP cases
- Public Functions:
- show_tesp_config:
Initializes and runs the GUI
References
Graphical User Interfaces with Tk
- class tesp_support.original.tesp_config.TespConfigGUI(master)
Bases:
object
Manages a seven-page GUI for case configuration
The GUI opens and saves a JSON file in the format used by tesp.tesp_config
Todo
Possible data loss if the user updated the number of Monte Carlo cases, but didn’t click the Update button before saving the case configuration.
- nb
the top-level GUI with tabbed pages
- Type:
Notebook
- f1
the page for date/time setup, along with T&D files, weather files and file paths
- Type:
Frame
- f2
the page for feeder generator setup
- Type:
Frame
- f3
the page for PYPOWER setup
- Type:
Frame
- f4
the page for EnergyPlus setup
- Type:
Frame
- f5
the page for simple_auction and hvac agent setup
- Type:
Frame
- f6
the page for time-scheduled thermostat settings
- Type:
Frame
- f7
the page for Monte Carlo setup
- Type:
Frame
- AttachFrame(tag, vars)
Creates a GUI page and loads it with data
Label, Combobox and Entry (i.e. edit) controls are automatically created for each row of data
- Parameters:
tag (str) – the name of the Frame, i.e., GUI page
vars (dict) – the section of case configuration data to be loaded onto this new GUI page
- InitializeMonteCarlo(n)
Makes default variable choices and then initializes the Monte Carlo GUI page
- Parameters:
n (int) – the number of Monte Carlo shots
- JsonToSection(jsn, vars)
Helper function that transfers a JSON file segment into GUI data structures
- Parameters:
jsn (dict) – the loaded JSON file
vars (dict) – the local data structure
- OpenConfig()
Opens a JSON case configuration; transfers its data to the GUI
- ReadFrame(f, vars)
Helper function that reads values from gridded GUI controls into the local case configuration
- Parameters:
f (Frame) – the GUI page to read
vars (dict) – the local data structure to update
- ReadLatLong()
Updates the Latitude and Longitude from TMY3 file
- ReloadFrame(f, vars)
Helper function to recreate the GUI page controls and load them with values
- Parameters:
f (Frame) – the GUI page to reload
vars (dict) – the section of case configuration with values to be loaded
- SaveConfig()
Updates the local case configuration from the GUI, queries user for a file name, and then saves case configuration to that file
- SizeMonteCarlo(n)
Initializes the Monte Carlo data structures with variable choices and samples
- Parameters:
n (int) – the number of Monte Carlo shots
- SizeMonteCarloFrame(f)
Update the Monte Carlo page to match the number of shots and variables
- Parameters:
f (Frame) – the Monte Carlo GUI page
- UpdateEMS(event)
- UpdateMonteCarloFrame()
Transfer data from the Monte Carlo page into the case configuration
- mcBand(var)
Find the band size corresponding to each Monte Carlo variable choice
- Parameters:
var (str) – one of ElectricCoolingParticipation, ThermostatRampMid, ThermostatOffsetLimitMid, WeekdayEveningStartMid or WeekdayEveningSetMid
- mcSample(var)
Return an appropriate random value for each Monte Carlo variable choice
- Parameters:
var (str) – one of ElectricCoolingParticipation, ThermostatRampMid, ThermostatOffsetLimitMid, WeekdayEveningStartMid or WeekdayEveningSetMid
- update_entry(ctl, val)
- tesp_support.original.tesp_config.show_tesp_config()
Runs the GUI. Reads and writes JSON case configuration files.
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
- 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
- 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:
- plot1
second plot
- Type:
- plot2
third plot
- Type:
- plot3
fourth plot
- Type:
- 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)