Code Reference

TSO Case Data

The TSO schema was based on the MATPOWER formats for the network and generator cost data, supplemented with TESP data. Code in fncsTSO.py reads this data from a JSON file.

Transmission System Operator (TSO)

http://example.com/root.json

type

object

properties

  • version

The Version Schema

not used

type

integer

examples

2

default

0

  • baseMVA

The Basemva Schema

MVA base for impedances

type

integer

examples

100

default

0

  • StartTime

The Starttime Schema

Date and time corresponding to 0 seconds in FNCS

type

string

examples

2013-07-01 00:00:00

pattern

^(.*)$

default

  • Tmax

The Tmax Schema

Number of seconds to simulate

type

integer

examples

86400

default

0

  • Period

The Period Schema

Optimal power flow (OPF) interval in seconds

type

integer

examples

300

default

0

  • dt

The Dt Schema

Regular power flow (PF) interval in seconds

type

integer

examples

60

default

0

  • pf_dc

The Pf_dc Schema

1 for DC PF, 0 for AC PF

type

integer

examples

1

default

0

  • opf_dc

The Opf_dc Schema

1 for DC OPF, 0 for AC OPF

type

integer

examples

1

default

0

  • bus

The Bus Schema

Bus data, including loads and voltage base

type

array

items

Bus Array

type

array

items

Bus Number

type

number

examples

1

Type (1=load,2=gen,3=swing)

type

number

enum

1, 2, 3

examples

3

Pd (load)

type

number

examples

15167.5

Qd (load)

type

number

examples

3079.89

Gs (shunt MW)

type

number

examples

0

Bs (shunt MVA)

type

number

examples

5000

Area

type

number

examples

1

V magnitude (pu)

type

number

examples

1

V angle (deg)

type

number

examples

0

kV base

type

number

examples

345

Zone

type

number

examples

1

Vmax pu

type

number

examples

1.1

Vmin pu

type

number

examples

0.9

  • gen

The Gen Schema

Generator ratings

type

array

items

Generator Array

type

array

items

Bus

type

number

examples

1

Pg (MW)

type

number

examples

0

Qg (MVAR)

type

number

examples

0

Qmax (MVAR)

type

number

examples

6567

Qmin (MVAR)

type

number

examples

-6567

Vg (pu)

type

number

examples

1

MVA base

type

number

examples

19978.8

Status (1 in service)

type

number

enum

0, 1

examples

1

Pmax (MW)

type

number

examples

19978.8

Pmin (MW)

type

number

examples

1998

Pc1

type

number

examples

0

Pc2

type

number

examples

0

Qc1min

type

number

examples

0

Qc1max

type

number

examples

0

Qc2min

type

number

examples

0

Qc2max

type

number

examples

0

AGC ramp rate

type

number

examples

0

10-min ramp rate

type

number

examples

0

30-min ramp rate

type

number

examples

0

Reactive ramp rate

type

number

examples

0

Area participation factor

type

number

examples

0

  • branch

The Branch Schema

Lines and transformers; pu impedance and ratings

type

array

items

Branch Array

type

array

items

From Bus

type

number

examples

5

To Bus

type

number

examples

6

R (pu)

type

number

examples

0.004237

X (pu)

type

number

examples

0.035898

B (pu)

type

number

examples

2.48325

Rating A, short term (MVA)

type

number

examples

2168

Rating B, long term (MVA)

type

number

examples

2168

Rating C, emergency (MVA)

type

number

examples

2168

Tap Ratio for Xfmrs (From/To)

type

number

examples

0

Shift Angle for Xfmrs (deg)

type

number

examples

0

Status (1 in service)

type

number

enum

0, 1

examples

1

Min Angle Difference From-To (deg)

type

number

examples

-360

Max Angle Difference From-To (deg)

type

number

examples

360

  • areas

The Areas Schema

PF areas are not currently used in TESP

type

array

  • gencost

The Gencost Schema

Cost functions for generators and dispatchable loads

type

array

items

Generator Cost Array

Indexing must match the Generators

type

array

items

Flag - 2 for polynomial, 1 for piecewise linear

type

number

examples

2

Startup cost

type

number

examples

0

Shutdown cost

type

number

examples

0

Number of coefficients

type

number

examples

3

C2 coefficient

type

number

examples

0.005

C1 coefficient

type

number

examples

40

C0 coefficient

type

number

examples

0

  • FNCS

The FNCS Schema

FNCS topics, scaling factors and initial conditions at selected buses

type

array

items

FNCS Bus Array

type

array

items

bus ID

type

number

examples

1

FNCS Topic

type

string

examples

SUBSTATION1

GridLAB-D Scale Factor

type

number

examples

792

Nominal P in MW

type

number

examples

15167.5

Nominal Q in MVAR

type

number

examples

3079.89

Scale factor for curve load

type

number

examples

0.5

Skew for curve load in seconds

type

number

examples

1711

Estimated P at time 0

type

number

examples

4788.99

Estimated Q at time 0

type

number

examples

972.66

  • UnitsOut

The Units Out Schema

Schedule of generators out of service

type

array

items

Generator Outage Array

type

array

items

Index into Generators

type

number

examples

1

Time outage starts in seconds

type

number

examples

108000

Time outage ends in seconds

type

number

examples

154000

  • BranchesOut

The Branches Out Schema

Schedules of branches out of service

type

array

items

Branch Outage Array

type

array

items

Index into Branches

type

number

examples

2

Time outage starts in seconds

type

number

examples

108000

Time outage ends in seconds

type

number

examples

154000

  • swing_bus

The Swing_bus Schema

Swing bus designation, depends on unit commitment

type

integer

examples

1

default

0

definitions

src Directory Structure

This list shows directories and Python files under the tesp/src repository. On GitHub, each README contains a list of other files.

  • archive

    • pypower; legacy files to patch PYPOWER; we have been able to incorporate these patches into the main PYPOWER distribution.

  • energyplus; C++ code to build a simple interface agent for EnergyPlus; this is part of the TESP distribution and used in the te30, sgip1 and energyplus examples.

  • gridlabd; legacy files for the house populations and feeder growth model; these features are mostly subsumed into tesp_support

  • jupyter; a prototype Jupyter notebook used for post-processing demonstrations and training

  • matpower

    • ubuntu; legacy code that wraps MATPOWER for TESP, but only on Ubuntu. We now use PYPOWER. In 2017, the wrapping process was very difficult on Mac OS X, and unsuccessful on Windows using free compilers.

  • tesp_support; runs PYPOWER without FNCS

    • setup.py; contains the version number and dependencies for tesp_support package

    • tesp_support; Python code for agents, configuration and post-processing.

      • TMY2EPW.py; command-line script that converts a TMY2 file to the EnergyPlus EPW format.

      • TMY3toCSV.py; converts TMY3 weather data to CSV format for common use by agents.

      • __init__.py; boilerplate for a Python package

      • api.py; collects Python import statements needed to use public functions from Python code outside of this directory.

      • auction.py; supervises one double-auction and multiple HVAC agents for a feeder; communicates via FNCS with GridLAB-D and PYPOWER/AMES

      • feederGenerator.py; from a PNNL taxonomy feeder as the backbone, populates it with houses, solar PV, batteries and smart inverters

      • fncs.py; the Python interface to FNCS, which is a C/C++ shared object library, or dynamic link library (Windows)

      • fncsPYPOWER.py; manages PYPOWER solutions for the te30 and sgip1 examples, based on a 9-bus textbook model. Note that the ERCOT cases use custom local versions of this code instead.

      • glm_dict.py; parses the GridLAB-D input (GLM) file and produces metafile data in JSON format, describing the houses, meters, DER, capacitors and regulators

      • precool.py; manages a set of house thermostats for NIST TE Challenge 2. There is no communication with a market. If the house experiences an overvoltage, the thermostat is turned down and locked for 4 hours, unless the house temperature violates comfort limits.

      • prep_auction.py; configures the agent metadata (JSON) and GridLAB-D FNCS subscriptions/publications for the double-auction, double-ramp simulations

      • prep_precool.py; configures the agent metadata (JSON) and GridLAB-D FNCS subscriptions/publications for NIST TE Challenge 2 precooling

      • process_agents.py; makes tabular and plotted summaries of agent results

      • process_eplus.py; makes tabular and plotted summaries of EnergyPlus results

      • process_gld.py; makes tabular and plotted summaries of GridLAB-D results (substation power/losses, average and sample house temperatures, meter voltage min/max)

      • process_houses.py; plots the HVAC power and air temperature for all houses

      • process_inv.py; makes tabular and plotted summaries of results for NIST TE Challenge 2, including inverters, capacitor switching and tap changes

      • process_pypower.py; makes tabular and plotted summaries of PYPOWER results for the 9-bus model in te30 or sgip1

      • process_voltages.py; plots the minimum and maximum voltage for all houses

      • simple_auction.py; implements the double-auction agent and the Olympic Peninsula cooling agent, as separate Python classes, called by auction.py

      • tesp_case.py; supervises the assembly of a TESP case with one feeder, one EnergyPlus building and one PYPOWER model. Reads the JSON file from tesp_config.py

      • tesp_config.py; a GUI for creating the JSON file used to configure a TESP case

      • tesp_monitor.py; a GUI for launching a TESP simulation, monitoring its progress, and terminating it early if necessary
        • weatherAgent.py; publishes weather and forecasts based on a CSV file

      • README.md; this file

      • matpower; legacy code that configures and post-processes MATPOWER v5+ for TESP. We now use PYPOWER and AMES instead.

      • sgip1; custom code that plotted curves from different cases on the same graph. Used for a 2018 journal paper on TESP and the SGIP1 example.

      • valuation; custom code that post-processed SGIP1 outputs for the 2018 journal paper. May serve as an example, or use Jupyter notebooks instead.

    • test; scripts that support testing the package; not automated.

tesp_support package

TESP is the Transactive Energy Simulation Platform tesp_support contains the Python files that are part of TESP

Submodules

tesp_support.TMY2EPW module

Functions to convert Typical Meteorological Year data for EnergyPlus

The input must be in TMY2 format. If only TMY3 files are available, see the TMY3toTMY2_ansi.c program distributed with TESP under the support/weather/TMY2EPW/source_code directory.

Public Functions:
convert_tmy2_to_epw

Converts TMY2 file to EPW.

tesp_support.TMY2EPW.convert_tmy2_to_epw(fileroot)

Converts TMY2 to EPW

Reads fileroot.tmy2 and writes fileroot.epw

Parameters

fileroot (str) – The input path and base file name, without extension

tesp_support.TMY2EPW.removeZero(x)

helper function to strip leading ‘0’ from a string

tesp_support.TMY3toCSV module

TMY3toCSV

Convert typical meteorological year version 3 (TMY3) data to comma separated values (CSV) for common use by TESP agents.

tesp_support.TMY3toCSV.readtmy3(filename=None, coerce_year=None, recolumn=True)

Read a TMY3 file in to a pandas dataframe.

tesp_support.TMY3toCSV.weathercsv(tmyfile, outputfile, start_time, end_time, year_)

Converts TMY3 weather data to CSV in the requested time range

Parameters
  • tmyfile – string the input TMY3 data file

  • outputfile – string the output CSV data file

  • start_time – string the starting date and time of interest, like 2013-07-01 00:00:00

  • end_time – string the ending date and time of interest, like 2013-07-08 00:00:00

  • year – integer the year of interest

Returns

nothing

tesp_support.TMY3toCSV.weathercsv_cloudy_day(start_time, end_time, outputfile)

tesp_support.api module

Functions intended for public access.

Example

To start PYPOWER for connection to FNCS:

import tesp_support.api as tesp
tesp.pypower_loop('te30_pp.json','TE_Challenge')
Public Functions:
convert_tmy2_to_epw

Command line utility that converts TMY2 weather files to the EPW format for EnergyPlus.

glm_dict

Writes the JSON metadata from a GridLAB-D file.

make_ems

Creates the energy management system (EMS) for FNCS/HELICS to interface with EnergyPlus.

make_monte_carlo_cases

Makes a subdirectory with all files needed to run a Monte Carlo TESP simulation, as directed by a JSON file.

make_tesp_case

Makes a subdirectory with all files needed to run a TESP simulation, as directed by a JSON file.

populate_feeder

Replaces the ZIP loads with houses in a GridLAB-D file.

precool_loop

Supervises FNCS messages and time steps for a GridLAB-D substation with many price-taking and pre-cooling HVAC controllers.

prep_precool

Writes agent metadata and FNCS subscriptions used in precool_loop.

prep_substation

Writes agent metadata and FNCS subscriptions used in substation_loop.

pypower_loop

Supervises the FNCS messages, time steps, optimal power flow and power flow for PYPOWER.

startWeatherAgent

Publishes FNCS messages and forecasts from a weather CSV file.

substation_loop

Supervises FNCS messages and time steps for a GridLAB-D substation with one double-auction market and many HVAC controllers.

summarize_opf

Print the OPF solution from PYPOWER (debugging).

weathercsv

Converts TMY3 weather data to CSV format.

write_node_houses

Write a transformer, service drop, meters and houses connected to a node, replacing load.

write_node_house_configs

write the transformer, service drop and inverter configuration attributes for houses at a node.

tesp_support.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.case_merge.key_present(val, ary)
tesp_support.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.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.case_merge.merge_gld_msg(target, sources)
tesp_support.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.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

tesp_support.case_merge.merge_substation_msg(target, sources)
tesp_support.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.feederGenerator module

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

As this module populates the feeder backbone wiht 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 Transfomers

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

  • Feeders without Service Transformers

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

References

GridAPPS-D Feeder Models

Public Functions:
populate_feeder

processes one GridLAB-D input file

Todo

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

tesp_support.feederGenerator.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.feederGenerator.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.feederGenerator.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.feederGenerator.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.feederGenerator.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.feederGenerator.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.feederGenerator.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.feederGenerator.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.feederGenerator.checkResidentialBuildingTable()

Verify that the regional building parameter histograms sum to one

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

Boolean

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

Boolean

tesp_support.feederGenerator.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.feederGenerator.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.feederGenerator.parse_kva(cplx)

Parse the kVA magnitude from GridLAB-D P+jQ volt-amperes in rectangular form

Parameters

cplx (str) – the GridLAB-D P+jQ value

Returns

the parsed kva value

Return type

float

tesp_support.feederGenerator.parse_kva_old(arg)

Parse the kVA magnitude from GridLAB-D P+jQ volt-amperes in rectangular form

DEPRECATED

Parameters

cplx (str) – the GridLAB-D P+jQ value

Returns

the parsed kva value

Return type

float

tesp_support.feederGenerator.populate_all_feeders()

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

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

  • targetdir (str) – directory to receive the output files, defaults to ./CaseName

tesp_support.feederGenerator.randomize_commercial_skew()
tesp_support.feederGenerator.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.feederGenerator.selectResidentialBuilding(rgnTable, prob)

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

Parameters

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

tesp_support.feederGenerator.selectSetpointBins(bldg, rand)

Randomly choose a histogram row from the cooling and heating setpoints

The random number for the heating setpoint 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.feederGenerator.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.feederGenerator.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.feederGenerator.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.feederGenerator.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.feederGenerator.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.feederGenerator.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.feederGenerator.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.feederGenerator.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

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.feederGenerator.write_local_triplex_configurations(op)

Write a 4/0 AA triplex configuration

Parameters

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

tesp_support.feederGenerator.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 (boolean) – True to write the IEEE 1547-2018 smarter inverter function setpoints

tesp_support.feederGenerator.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 (boolean) – if True, reseed each function call. Default value False provides repeatability of output.

tesp_support.feederGenerator.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.feederGenerator.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.feederGenerator.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.feederGenerator.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.feederGenerator.write_tariff(op)

Writes tariff information to billing meters

Parameters

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

tesp_support.feederGenerator.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.feederGenerator.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.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 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 fncsPYPOWER.py

  • under examples, see loadshed/loadshed.py

tesp_support.fncs.agentGetEvents()

Retrieve FNCS agent messages

Returns

concatenation of agent messages

Return type

str

tesp_support.fncs.agentPublish(value)

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

Parameters

value (str) – value

tesp_support.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.fncs.die()

Call FNCS die because of simulator error

tesp_support.fncs.finalize()

Call FNCS finalize to end connection with broker

tesp_support.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.fncs.get_events()

Retrieve FNCS messages after time_request returns

Returns

tuple of decoded FNCS events

Return type

list

tesp_support.fncs.get_events_size()

Get the size of the event queue

tesp_support.fncs.get_id()

Find the FNCS ID

tesp_support.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.fncs.get_keys()

Find the list of topics

Returns

decoded topic names

Return type

[str]

tesp_support.fncs.get_keys_size()

Get the size of the keys

tesp_support.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.fncs.get_simulator_count()

Find the FNCS simulator count

tesp_support.fncs.get_value(key)

Extract value from a FNCS message

Parameters

key (str) – the topic

Returns

decoded value

Return type

str

tesp_support.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.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.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.fncs.get_version()

Find the FNCS version

Returns

major, minor and patch numbers

Return type

int, int, int

tesp_support.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.fncs.is_initialized()

Determine whether the FNCS library has been initialized

Returns

True if initialized, False if not.

Return type

Boolean

tesp_support.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.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.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.fncs.time_request(time)

FNCS time request

Parameters

time (int) – requested time.

tesp_support.fncs.update_time_delta(delta)

Update simulator time delta value

Parameters

delta (int) – time delta.

tesp_support.fncsPYPOWER module

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

Public Functions:
pypower_loop

Initializes and runs the simulation.

tesp_support.fncsPYPOWER.load_json_case(fname)

Helper function to load PYPOWER case from a JSON file

Parameters

fname (str) – the JSON file to open

Returns

the loaded PYPOWER case structure

Return type

dict

tesp_support.fncsPYPOWER.make_dictionary(ppc, rootname)

Helper function to write the JSON metafile for post-processing

Parameters
  • ppc (dict) – PYPOWER case file structure

  • rootname (str) – to write rootname_m_dict.json

tesp_support.fncsPYPOWER.parse_mva(arg)

Helper function to parse P+jQ from a FNCS value

Parameters

arg (str) – FNCS value in rectangular format

Returns

P [MW] and Q [MVAR]

Return type

float, float

tesp_support.fncsPYPOWER.pypower_loop(casefile, rootname, helicsConfig=None)

Public function to start PYPOWER solutions under control of FNCS or HELICS

The time step, maximum time, and other data must be set up in a JSON file. This function will run the case under FNCS, manage the FNCS message traffic, and shutdown FNCS upon completion. Five files are written:

  • rootname.csv; intermediate solution results during simulation

  • rootname_m_dict.json; metadata for post-processing

  • bus_rootname_metrics.json; bus metrics for GridLAB-D connections, upon completion

  • gen_rootname_metrics.json; bulk system generator metrics, upon completion

  • sys_rootname_metrics.json; bulk system-level metrics, upon completion

Parameters
  • casefile (str) – the configuring JSON file name, without extension

  • rootname (str) – the root filename for metrics output, without extension

tesp_support.fncsPYPOWER.summarize_opf(res)

Helper function to print optimal power flow solution (debugging)

Parameters

res (dict) – solved PYPOWER case structure

tesp_support.glm_dict 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.glm_dict.append_include_file(lines, fname)
tesp_support.glm_dict.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.glm_dict.glm_dict(nameroot, ercot=False, te30=False)

Writes the JSON metadata file from a GLM file

This function reads nameroot.glm and writes nameroot_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
  • nameroot (str) – path and file name of the GLM file, without the extension

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

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

tesp_support.glm_dict.isCommercialHouse(house_class)
tesp_support.glm_dict.ti_enumeration_string(tok)

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

tesp_support.helpers module

Utility functions for use within tesp_support, including new agents.

class tesp_support.helpers.ClearingType(value)

Bases: enum.IntEnum

Describes the market clearing type

BUYER = 5
EXACT = 3
FAILURE = 1
NULL = 0
PRICE = 2
SELLER = 4
tesp_support.helpers.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.helpers.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 (Boolean) – 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.helpers.gld_strict_name(val)

Sanitizes a name for GridLAB-D publication to FNCS

Parameters

val (str) – the input name

Returns

val with all ‘-‘ replaced by ‘_’, and any leading digit replaced by ‘gld_’

Return type

str

tesp_support.helpers.idf_int(val)

Helper function to format integers for the EnergyPlus IDF input data file

Parameters

val (int) – the integer to format

Returns

the integer in string format, padded with a comma and zero or one blanks, in order to fill three spaces

Return type

str

tesp_support.helpers.parse_fncs_magnitude(arg)

Parse the magnitude of a possibly complex number from FNCS

Parameters

arg (str) – the FNCS string value

Returns

the parsed number, or 0 if parsing fails

Return type

float

tesp_support.helpers.parse_fncs_number(arg)

Parse floating-point number from a FNCS message; must not have leading sign or exponential notation

Parameters

arg (str) – the FNCS string value

Returns

the parsed number

Return type

float

tesp_support.helpers.parse_kw(arg)

Parse the kilowatt load of a possibly complex number from FNCS

Parameters

arg (str) – the FNCS string value

Returns

the parsed number in kW, or 0 if parsing fails

Return type

float

tesp_support.helpers.stop_helics_federate(fed)
tesp_support.helpers.zoneMeterName(ldname)

Enforces the meter naming convention for commercial zones

Commercial zones must be children of load objects. This routine replaces “_load_” with “_meter”.

Parameters

objname (str) – the GridLAB-D name of a load, ends with _load_##

Returns

The GridLAB-D name of upstream meter

Return type

str

tesp_support.hvac 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.hvac.hvac(dict, key, aucObj)

Bases: object

This agent manages thermostat setpoint and bidding for a house

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

Boolean

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

Boolean

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, Falso if not

Return type

Boolean

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, Boolean]

inform_bid(price)

Set the cleared_price attribute

Parameters

price (float) – cleared price in $/kwh

set_air_temp_from_fncs_str(str)

Sets the air_temp attribute

Parameters

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

set_air_temp_from_helics(val)
set_hvac_load_from_fncs_str(str)

Sets the hvac_load attribute, if greater than zero

Parameters

str (str) – FNCS message with load in kW

set_hvac_load_from_helics(val)
set_hvac_state_from_fncs_str(str)

Sets the hvac_on attribute

Parameters

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

set_hvac_state_from_helics(val)
set_voltage_from_fncs_str(str)

Sets the mtr_v attribute

Parameters

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

set_voltage_from_helics(val)

tesp_support.make_ems module

Creates and merges the EMS for an EnergyPlus building model

Public Functions:
make_ems

Creates the energy management system (EMS) for FNCS/HELICS to interface with EnergyPlus.

merge_idf

Assembles the base IDF, the EMS, start time and end time

tesp_support.make_ems.cooling_coil_sensor(name, target, op)
tesp_support.make_ems.get_eplus_token(sval)
tesp_support.make_ems.global_variable(name, op)
tesp_support.make_ems.heating_coil_sensor(name, target, op)
tesp_support.make_ems.make_ems(sourcedir='./output', baseidf='SchoolBase.idf', target='ems.idf', write_summary=False, bHELICS=False)

Creates the EMS for an EnergyPlus building model

Parameters
  • target (str) – desired output file in PWD, default ems.idf

  • baseidf (str) – is the original EnergyPlus model file without the EMS

  • sourcedir (str) – directory of the output from EnergyPlus baseline simulation, default ./output

tesp_support.make_ems.merge_idf(base, ems, StartTime, EndTime, target, StepsPerHour)

Assembles a base EnergyPlus building model with EMS and simulation period

Parameters
  • base (str) – fully qualified base IDF model

  • ems (str) – fully qualified EMS model file

  • StartTime (str) – Date-Time to start simulation, Y-m-d H:M:S

  • EndTime (str) – Date-Time to end simulation, Y-m-d H:M:S

tesp_support.make_ems.output_variable(name, target, op)
tesp_support.make_ems.print_idf_summary(target, zones, zonecontrols, thermostats, schedules, hcoils, ccoils, hvacs)
tesp_support.make_ems.schedule_actuator(name, target, op)
tesp_support.make_ems.schedule_sensor(name, op)
tesp_support.make_ems.summarize_idf(fname, baseidf)
tesp_support.make_ems.valid_var(name)
tesp_support.make_ems.write_new_ems(target, zones, zonecontrols, thermostats, schedules, hcoils, ccoils, hvacs, bHELICS)
tesp_support.make_ems.zone_heating_sensor(name, op)
tesp_support.make_ems.zone_occupant_sensor(name, op)
tesp_support.make_ems.zone_sensible_cooling_sensor(name, op)
tesp_support.make_ems.zone_sensible_heating_sensor(name, op)
tesp_support.make_ems.zone_temperature_sensor(name, op)

tesp_support.parse_msout module

tesp_support.parse_msout.next_matrix(fp, var)
tesp_support.parse_msout.next_val(fp, var, bInteger=True)
tesp_support.parse_msout.read_most_solution(fname='msout.txt')

tesp_support.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 setpoints in response to time-of-use rates and overvoltages. The precooler agents also estimate house equivalent thermal parameter (ETP) models based on total floor area, number of stories, number of exterior doors and and estiamted 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.precool.parse_fncs_magnitude(arg)

Helper function to find the magnitude of a possibly complex number from FNCS

Parameters

arg (str) – The FNCS value

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

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

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

Boolean

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

Boolean

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

Set the air_temp member variable

Parameters

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

set_voltage(str)

Sets the mtr_v attribute

Parameters

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

tesp_support.prep_eplus module

tesp_support.prep_eplus.configure_eplus(caseConfig, template_dir)
tesp_support.prep_eplus.make_gld_eplus_case(fname, bGlmReady=False)
tesp_support.prep_eplus.prepare_bldg_dict(caseConfig)
tesp_support.prep_eplus.prepare_glm_dict(caseConfig)
tesp_support.prep_eplus.prepare_glm_file(caseConfig)
tesp_support.prep_eplus.prepare_glm_helics(caseConfig, fedMeters, fedLoadNames)
tesp_support.prep_eplus.prepare_run_script(caseConfig, fedMeters)
tesp_support.prep_eplus.writeGlmClass(theseLines, thisClass, op)

tesp_support.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.prep_precool.prep_precool(nameroot, time_step=15)

Sets up agent configurations for the NIST TE Challenge 2 example

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

  • nameroot_agent_dict.json, contains configuration data for the precooler agents

  • nameroot_precool.yaml, contains FNCS subscriptions for the precooler agents

  • nameroot_FNCS_Config.txt, a GridLAB-D include file with FNCS publications and subscriptions

Parameters

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

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

  • nameroot_FNCS_Config.txt, a GridLAB-D include file with FNCS publications and subscriptions

Parameters

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

tesp_support.prep_substation.prep_substation(gldfileroot, jsonfile='')

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

Always reads gldfileroot.glm and writes:

  • gldfileroot_agent_dict.json, contains configuration data for the simple_auction and hvac agents

  • gldfileroot_substation.yaml, contains FNCS subscriptions for the psimple_auction and hvac agents

  • gldfileroot_FNCS_Config.txt, a GridLAB-D include file with FNCS publications and subscriptions

  • gldfileroot_Weather_Config.json, contains configuration data for the weather agent

If provided, this function also reads jsonfile as created by tesp_config and used by tesp_case. This supplemental data includes time-scheduled thermostat setpoints (NB: do not use the scheduled setpoint 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)

tesp_support.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.process_agents.plot_agents(dict, save_file=None, save_only=False)
tesp_support.process_agents.process_agents(nameroot, dictname='', print_dictionary=False, save_file=None, save_only=False)

Plots cleared price, plus bids from the first HVAC controller

This function reads auction_nameroot_metrics.json and controller_nameroot_metrics.json for the data; it reads nameroot_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
  • nameroot (str) – name of the TESP case, not necessarily the same as the GLM case, without the extension

  • dictname (str) – metafile name (with json extension) for a different GLM dictionary, if it’s not nameroot_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 (Boolean) – set True with save_file to skip the display of the plot. Otherwise, script waits for user keypress.

tesp_support.process_agents.read_agent_metrics(nameroot, dictname='', print_dictionary=False)

tesp_support.process_eplus module

Functions to plot data from the EnergyPlus agent

Public Functions:
process_eplus

Reads the data and metadata, then makes the plots.

tesp_support.process_eplus.plot_eplus(dict, title=None, save_file=None, save_only=False)
tesp_support.process_eplus.process_eplus(nameroot, title=None, save_file=None, save_only=False)

Plots the min and max line-neutral voltages for every billing meter

This function reads eplus_nameroot_metrics.json for both metadata and data. This must exist in the current working directory. One graph is generated with 3 subplots:

  1. Cooling system setpoint, actual temperature and the difference between them.

  2. Heating system setpoint, actual temperature and the difference between them.

  3. Price that the building controller responded to.

Parameters
  • nameroot (str) – name of the TESP case, not necessarily the same as the EnergyPlus case, without the extension

  • title (str) – supertitle for the page of plots.

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

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

tesp_support.process_eplus.read_eplus_metrics(nameroot, quiet=False)

tesp_support.process_gld module

Functions to plot data from GridLAB-D

Public Functions:
process_gld

Reads the data and metadata, then makes the plots.

tesp_support.process_gld.plot_gld(dict, save_file=None, save_only=False)
tesp_support.process_gld.process_gld(nameroot, dictname='', save_file=None, save_only=False)

Plots a summary/sample of power, air temperature and voltage

This function reads substation_nameroot_metrics.json, billing_meter_nameroot_metrics.json and house_nameroot_metrics.json for the data; it reads nameroot_glm_dict.json for the metadata. These must all exist in the current working directory. Makes one graph with 4 subplots:

  1. Substation real power and losses

  2. Average air temperature over all houses

  3. Min/Max line-to-neutral voltage and Min/Max line-to-line voltage at the first billing meter

  4. Min, Max and Average air temperature at the first house

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

  • dictname (str) – metafile name (with json extension) for a different GLM dictionary, if it’s not nameroot_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 (Boolean) – set True with save_file to skip the display of the plot. Otherwise, script waits for user keypress.

tesp_support.process_gld.read_gld_metrics(nameroot, dictname='')

tesp_support.process_houses module

Functions to plot house data from GridLAB-D

Public Functions:
process_houses

Reads the data and metadata, then makes the plot.

tesp_support.process_houses.plot_houses(dict, save_file=None, save_only=False)
tesp_support.process_houses.process_houses(nameroot, dictname='', save_file=None, save_only=True)

Plots the temperature and HVAC power for every house

This function reads substation_nameroot_metrics.json and house_nameroot_metrics.json for the data; it reads nameroot_glm_dict.json for the metadata. These must all exist in the current working directory. Makes one graph with 2 subplots:

  1. Average air temperature at every house

  2. Average HVAC power at every house

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

  • dictname (str) – metafile name (with json extension) for a different GLM dictionary, if it’s not nameroot_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 (Boolean) – set True with save_file to skip the display of the plot. Otherwise, script waits for user keypress.

tesp_support.process_houses.read_house_metrics(nameroot, dictname='')

tesp_support.process_inv module

Functions to plot inverter and volt-var data from GridLAB-D, for NIST TE Challenge 2

Public Functions:
process_inv

Reads the data and metadata, then makes the plots.

tesp_support.process_inv.process_inv(nameroot, dictname='', save_file=None, save_only=False)

Plots inverter and volt-var data for the NIST TE Challenge 2 / IEEE 8500 examples

This function reads substation_nameroot_metrics.json, billing_meter_nameroot_metrics.json, capacitor_nameroot_metrics.json, regulator_nameroot_metrics.json, house_nameroot_metrics.json and inverter_nameroot_metrics.json for the data; it reads nameroot_glm_dict.json for the metadata. If possible, it reads precool_nameroot_metrics.json for temperature deviation. These must all exist in the current working directory. One graph is generated with 10 subplots:

  1. Average P and Q over all inverters

  2. Min, Max and Average line-neutral voltage over all billing meters

  3. Average air temperature over all houses

  4. Average temperature deviations from the setpoint over all houses

  5. Total of ANSI C84 A and B range violation counts, summing over all billing meters

  6. Total of ANSI C84 A and B range violation durations, summing over all billing meters

  7. Substation total power, losses, house power, house HVAC power and house waterheater power

  8. The accumulated bill, summed over all billing meters

  9. The accumulated capacitor switching counts for each of 4 capacitor banks, if found, as in the IEEE 8500 case

  10. The accumulated regulator counts for each of 4 voltage regulators, if found, as in the IEEE 8500 case

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

  • dictname (str) – metafile name (with json extension) for a different GLM dictionary, if it’s not nameroot_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 (Boolean) – set True with save_file to skip the display of the plot. Otherwise, script waits for user keypress.

tesp_support.process_pypower module

Functions to plot bus and generator data from PYPOWER

Public Functions:
process_pypower

Reads the data and metadata, then makes the plots.

tesp_support.process_pypower.plot_pypower(dict, save_file=None, save_only=False)
tesp_support.process_pypower.process_pypower(nameroot, save_file=None, save_only=True)

Plots bus and generator quantities for the 9-bus system used in te30 or sgip1 examples

This function reads bus_nameroot_metrics.json and gen_nameroot_metrics.json for the data, and nameroot_m_dict.json for the metadata. These must all exist in the current working directory. One graph is generated with 8 subplots:

  1. Bus P and Q demands, at the single GridLAB-D connection

  2. Bus P and Q locational marginal prices (LMP), at the single GridLAB-D connection

  3. Bus Vmin, Vmax and Vavg, at the single GridLAB-D connection

  4. All 4 generator prices

  5. Generator 1 P and Q output

  6. Generator 2 P and Q output

  7. Generator 3 P and Q output

  8. Generator 4 P and Q output

Parameters
  • nameroot (str) – file name of the TESP case, not necessarily the same as the PYPOWER case, without the JSON extension

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

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

tesp_support.process_pypower.read_pypower_metrics(nameroot)

tesp_support.process_voltages module

Functions to plot all billing meter voltages from GridLAB-D

Public Functions:
process_voltages

Reads the data and metadata, then makes the plot.

tesp_support.process_voltages.plot_voltages(dict, save_file=None, save_only=False)
tesp_support.process_voltages.process_voltages(nameroot, dictname='', save_file=None, save_only=True)

Plots the min and max line-neutral voltages for every billing meter

This function reads substation_nameroot_metrics.json and billing_meter_nameroot_metrics.json for the voltage data, and nameroot_glm_dict.json for the meter names. These must all exist in the current working directory. One graph is generated with 2 subplots:

  1. The Min line-to-neutral voltage at each billing meter

  2. The Max line-to-neutral voltage at each billing meter

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

  • dictname (str) – metafile name (with json extension) for a different GLM dictionary, if it’s not nameroot_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 (Boolean) – set True with save_file to skip the display of the plot. Otherwise, script waits for user keypress.

tesp_support.process_voltages.read_voltage_metrics(nameroot, dictname='')

tesp_support.run_test_case module

Runs the set of TESP test cases

tesp_support.run_test_case.GetTestCaseReports()
tesp_support.run_test_case.InitializeTestCaseReports()
tesp_support.run_test_case.ProcessLine(line, local_vars)
tesp_support.run_test_case.RunTestCase(fname, casename=None)

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

class tesp_support.simple_auction.simple_auction(dict, key)

Bases: object

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

References

Market Module Overview - Auction

Parameters
  • dict (dict) – 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 dict

Type

float

mean

the historical mean price in $/kwh, from dict

Type

float

period

the market clearing period in seconds, from dict

Type

float

pricecap

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

Type

float

max_capacity_reference_bid_quantity
Type

float

statistic_mode

always 1, not used, from dict

Type

int

stat_mode

always ST_CURR, not used, from dict

Type

str

stat_interval

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

Type

str

stat_type

always mean and standard deviation, not used, from dict

Type

str

stat_value

always zero, not used, from dict

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

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

helpers.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 FNCS seconds, should be <= time_granted, for the log file only

  • time_granted (int) – the current time in FNCS 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, Boolean]) – price in $/kwh, quantity in kW and the HVAC on state

initAuction()

Sets the clearing_price and lmp to the mean price

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 accumlates 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
  • (int) (time_granted) – next clearing time in FNCS seconds, should be <= time_granted, for the log file only

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

Returns

None

update_statistics()

Update price history statistics - not implemented

tesp_support.substation module

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

Public Functions:
substation_loop

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.substation.fncs_substation_loop(configfile, metrics_root, hour_stop=48, flag='WithMarket')

Helper function that initializes and runs the agents

Reads configfile. Writes auction_metrics_root_metrics.json and controller_metrics_root_metrics.json upon completion.

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

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

  • hour_stop (float) – number of hours to simulation

  • flag (str) – WithMarket or NoMarket to use the simple_auction, or not

tesp_support.substation.helics_substation_loop(configfile, metrics_root, hour_stop, flag, helicsConfig)
tesp_support.substation.substation_loop(configfile, metrics_root, hour_stop=48, flag='WithMarket', helicsConfig=None)

Wrapper for inner_substation_loop

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

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

  • targetdir (str) – directory, based on cwd, to receive the TESP case files

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

  • tesp_monitor.json: shell commands and other configuration data 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

Parameters
  • config (dict) – the complete case data structure

  • cfgfile (str) – the name of the JSON file that was read

  • freshdir (boolean) – flag to create the directory and base files anew

Todo

  • Write gui.sh, per the te30 examples

tesp_support.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.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.tesp_config.show_tesp_config()

Runs the GUI. Reads and writes JSON case configuration files.

tesp_support.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.tesp_monitor.TespMonitorGUI(master)

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 FNCS federates, and a YAML file with 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, EnergPlus, 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
  • root (Tk) – the TCL Tk toolkit instance

  • top (Window) – the top-level TCL Tk Window

  • labelvar (StringVar) – used to display the monitor JSON configuration file path

  • hrs ([float]) – x-axis data array for time in hours, shared by all plots

  • y0 ([float]) – y-axis data array for PYPOWER bus voltage

  • y1 ([float]) – y-axis data array for EnergyPlus load

  • y2lmp ([float]) – y-axis data array for PYPOWER LMP

  • y2auc ([float]) – y-axis data array for simple_auction cleared_price

  • y3fncs ([float]) – y-axis data array for GridLAB-D load via FNCS

  • y3gld ([float]) – y-axis data array for sample-and-hold GridLAB-D load

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

  • y0min (float) – the first y axis minimum value

  • y0max (float) – the first y axis maximum value

  • y1min (float) – the second y axis minimum value

  • y1max (float) – the second y axis maximum value

  • y2min (float) – the third y axis minimum value

  • y2max (float) – the third y axis maximum value

  • y3min (float) – the fourth y axis minimum value

  • y3max (float) – the fourth y axis maximum value

  • hour_stop (float) – the maximum x axis time value to plot

  • ln0 (Line2D) – the plotted PYPOWER bus voltage, color GREEN

  • ln1 (Line2D) – the plotted EnergyPlus load, color RED

  • ln2lmp (Line2D) – the plotted PYPOWER locational marginal price (LMP), color BLUE

  • ln2auc (Line2D) – the plotted simple_auction cleared_price, color BLACK

  • ln3gld (Line2D) – the plotted sample-and-hold GridLAB-D substation load, color MAGENTA

  • ln3fncs (Line2D) – the plotted GridLAB-D substation load published via FNCS; may be zero if not published for the current animation frame, color CYAN

  • fig (Figure) – animated Matplotlib figure hosted on the GUI

  • ax (Axes) – set of 4 xy axes to plot on

  • canvas (FigureCanvasTkAgg) – a TCL Tk canvas that can host Matplotlib

  • bFNCSactive (Boolean) – True if a TESP simulation is running with other FNCS federates, False if not

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

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 federates in TESP, except for this monitor

launch_all()

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.

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.

Parameters

i (int) – the animation frame number

tesp_support.tesp_monitor.show_tesp_monitor()

Creates and displays the monitor GUI

tesp_support.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.tesp_monitor_ercot.ChoosablePlot(master, color='red', xLabel='', topicDict={}, **kwargs)

Bases: tkinter.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.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

Boolean

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.

Parameters

i (int) – the animation frame number

tesp_support.tesp_monitor_ercot.show_tesp_monitor()

Creates and displays the monitor GUI

tesp_support.weatherAgent module

Weather Agent

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

tesp_support.weatherAgent.convertTimeToSeconds(time)

Convert time string with unit to integer in seconds

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

Parameters

time – str time with unit

Returns

int represent the input time in second

tesp_support.weatherAgent.deltaTimeToResmapleFreq(time)

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

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

Parameters

time – str time with unit

Returns

str time with resample frequency

tesp_support.weatherAgent.findDeltaTimeMultiplier(time)

find the multiplier to convert delta_time to seconds

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

Parameters

time – str time with unit

Returns

int the multiplier to convert delta_time to seconds

tesp_support.weatherAgent.show_resource_consumption()
tesp_support.weatherAgent.startWeatherAgent(file)

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

Parameters

file – string the weather data file

Returns

nothing

tesp_support.weatherAgent.stop_helics_federate(fed)
tesp_support.weatherAgent.usage()
class tesp_support.weatherAgent.weather_forecast(variable, period, W_dict)

Bases: object

This object includes the error to a weather variable

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

  • period (int) – period of the sinusoidal bias

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

weather_variable

Type of weather variable being forecasted

Type

str

# Type of error insertion
distribution

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

Type

int

P_e_bias

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

Type

float

P_e_envelope

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

Type

float

Lower_e_bound

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

Type

float

# Bias variable
biasM

sinusoidal bias for altering the error envelope

Type

float) (1 X period

Period_bias

period of the sinusoidal bias

Type

int

get_truncated_normal(EL, EH)

Truncated normal distribution

make_forecast(weather, t=0)

Include error to a known weather variable

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

  • t (int) – time in hours

Returns

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

Return type

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