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 tso_PYPOWER.py and tso_psst.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 simulation
	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
DSO	The DSO Schema
	DSO topics, scaling factors and initial conditions at selected buses
	type	array
	items	DSO Bus Array
		type	array
		items
			bus ID
			type	integer
			examples	1
			Name for passing messages
			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.

• comms_metrics; a Power Distribution System Model Analysis tool not yet public though pypi. Not only can it perform metric calculations, it also has the ability to plot the models as a network and parse different file formats as pre-processing for the data analysis.

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

• synComGraph; graph algorithms to generate a synthetic communication network graph topology corresponding to a given feeder topology

• tesp_support; utilities for building and running using PYPOWER with or without FNCS/HELICS co-simulations

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

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

    • api; code that configures new capabilities for TESP

      • data.py; the paths to data libraries

      • entity.py; utilities for assign json file to attribute in python script

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

      • helpers.py; utility functions for use within tesp_support

      • make_ems.py; creates and merges the EMS for an EnergyPlus building model

      • model.py; GridLAB-D model I/O for TESP api

      • modifier.py; modify GridLAB-D model I/O for TESP api

      • metric_api.py; utility metric api functions for use in post-processing

      • metric_collector.py; utility metric collector functions for use within simulation or post process

      • parse_helpers.py; parse text for different types of numbers

      • player.py; configure and plays a files for a simulation

      • 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

      • test_runner.py; auto test runner for TESP run* cases based on pre-existing shell script file.

      • time_helpers.py; utility time functions for use within tesp_support, including new agents

      • tso_helpers.py; helpers for PYPOWER, PSST, MOST solutions

      • tso_PSST.py; manages PSST solutions for the DSOT example, based on a 8-bus or 200-bus model. Note that the ERCOT cases use custom local versions of this code instead.

      • tso_PYPOWER.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.

    • original; legacy code that configures most example/capabilities for TESP

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

      • copperplate_feeder_glm.py; from a PNNL taxonomy feeder as the backbone, populates it with sudo copperplate

      • curve; accumulates a set of price, quantity bids for later aggregation for a curve

      • 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_precool.py; configures the agent metadata (JSON) and GridLAB-D HELICS subscriptions/publications for NIST TE Challenge 2 precooling

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

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

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

      • 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

    • weather; code that configures weather capabilities for TESP

      • PSM_download.py; simple script to download PSM weather files and convert them to DAT files

      • PSMv3toDAT.py; this code reads in PSM v3 csv files to converts weather DAT format for common use by agents

      • README.md; this file

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

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

      • weather_Agent.py; publishes weather and forecasts based on a CSV file

    • consensus; custom code that for running the consensus mechanism on microgrid n DSOT co simulation using TSO and DSO DER agents.

    • dsot; custom code that for running the DSOT co simulation using TSO and DSO DER agents. Used for a 2021 journal paper on TESP and the DSOT example.

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

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

    • 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

Links to Dependencies

• Docker

• EnergyPlus

• GridLAB-D

• Matplotlib

• MATPOWER

• NetworkX

• NumPy

• Pandas

• pip

• PYPOWER

• Python

• SciPy

• TESP

tesp_support package

Transactive Energy Simulation Platform (TESP) Contains the python packages for the tesp_support

Example

To start PYPOWER for connection to FNCS:

import tesp_support.original.tso_PYPOWER_f as tesp
tesp.tso_pypower_loop_f('te30_pp.json','TE_Challenge')

To start PYPOWER for connection to HELICS:

import tesp_support.api.tso_PYPOWER as tesp
tesp.tso_pypower_loop('te30_pp.json','TE_Challenge', helicsConfig='tso.json')

Subpackages

• tesp_support.api package
  • Submodules
  • tesp_support.api.bench_profile module
  • tesp_support.api.data module
  • tesp_support.api.entity module
  • tesp_support.api.gridpiq module
  • tesp_support.api.helpers module
  • tesp_support.api.make_ems module
  • tesp_support.api.metrics_api module
  • tesp_support.api.metrics_base_api module
  • tesp_support.api.metrics_collector module
  • tesp_support.api.model_GLM module
  • tesp_support.api.modify_GLM module
  • tesp_support.api.parse_helpers module
  • tesp_support.api.player module
  • tesp_support.api.process_eplus module
  • tesp_support.api.process_gld module
  • tesp_support.api.process_houses module
  • tesp_support.api.process_inv module
  • tesp_support.api.process_pypower module
  • tesp_support.api.process_voltages module
  • tesp_support.api.schedule_client module
  • tesp_support.api.schedule_server module
  • tesp_support.api.store module
  • tesp_support.api.substation module
  • tesp_support.api.test_runner module
  • tesp_support.api.time_helpers module
  • tesp_support.api.tso_PYPOWER module
  • tesp_support.api.tso_helpers module
  • tesp_support.api.tso_psst module
• tesp_support.consensus package
  • Submodules
  • tesp_support.consensus.case_merge module
  • tesp_support.consensus.dg_agent module
  • tesp_support.consensus.dso_agent module
  • tesp_support.consensus.dso_market module
  • tesp_support.consensus.forecasting module
  • tesp_support.consensus.generator module
  • tesp_support.consensus.glm_dictionary module
  • tesp_support.consensus.microgrid module
  • tesp_support.consensus.microgrid_agent module
  • tesp_support.consensus.residential_feeder_glm module
  • tesp_support.consensus.retail_market module
  • tesp_support.consensus.substation module
  • tesp_support.consensus.weather_agent module
• tesp_support.dsot package
  • Submodules
  • tesp_support.dsot.Wh_Energy_Purchases module
  • tesp_support.dsot.balance_sheet_functions module
  • tesp_support.dsot.battery_agent module
  • tesp_support.dsot.case_comparison_plots module
  • tesp_support.dsot.case_merge module
  • tesp_support.dsot.customer_CFS module
  • tesp_support.dsot.dso_CFS module
  • tesp_support.dsot.dso_helper_functions module
  • tesp_support.dsot.dso_map module
  • tesp_support.dsot.dso_market module
  • tesp_support.dsot.dso_quadratic_curves module
  • tesp_support.dsot.dso_rate_making module
  • tesp_support.dsot.ev_agent module
  • tesp_support.dsot.forecasting module
  • tesp_support.dsot.gen_map module
  • tesp_support.dsot.generator_balance_sheet_func module
  • tesp_support.dsot.glm_dictionary module
  • tesp_support.dsot.helpers_dsot module
  • tesp_support.dsot.hvac_agent module
  • tesp_support.dsot.load_less_solar module
  • tesp_support.dsot.plots module
  • tesp_support.dsot.pv_agent module
  • tesp_support.dsot.residential_feeder_glm module
  • tesp_support.dsot.retail_market module
  • tesp_support.dsot.sankey module
  • tesp_support.dsot.solar module
  • tesp_support.dsot.substation module
  • tesp_support.dsot.substation_f module
  • tesp_support.dsot.water_heater_agent module
  • tesp_support.dsot.wind_gen_year module
• tesp_support.matpower package
  • Submodules
  • tesp_support.matpower.matpower_dict module
  • tesp_support.matpower.process_matpower module
• tesp_support.original package
  • Submodules
  • tesp_support.original.case_merge module
  • tesp_support.original.commercial_feeder_glm module
  • tesp_support.original.copperplate_feeder_glm module
  • tesp_support.original.curve module
  • tesp_support.original.fncs module
  • tesp_support.original.glm_dictionary module
  • tesp_support.original.hvac_agent module
  • tesp_support.original.parse_msout module
  • tesp_support.original.player_f module
  • tesp_support.original.precool module
  • tesp_support.original.prep_eplus module
  • tesp_support.original.prep_precool module
  • tesp_support.original.prep_substation module
  • tesp_support.original.process_agents module
  • tesp_support.original.residential_feeder_glm module
  • tesp_support.original.simple_auction module
  • tesp_support.original.substation_f module
  • tesp_support.original.tesp_case module
  • tesp_support.original.tesp_config module
  • tesp_support.original.tesp_monitor module
  • tesp_support.original.tesp_monitor_ercot module
  • tesp_support.original.tso_PYPOWER_f module
  • tesp_support.original.tso_psst_f module
• tesp_support.sgip1 package
  • Submodules
  • tesp_support.sgip1.compare_auction module
  • tesp_support.sgip1.compare_csv module
  • tesp_support.sgip1.compare_hvac module
  • tesp_support.sgip1.compare_prices module
  • tesp_support.sgip1.compare_pypower module
• tesp_support.valuation package
  • Submodules
  • tesp_support.valuation.TransmissionMetricsProcessor module
• tesp_support.weather package
  • Submodules
  • tesp_support.weather.PSM_download module
  • tesp_support.weather.PSMv3toDAT module
  • tesp_support.weather.TMY3toCSV module
  • tesp_support.weather.TMYtoEPW module
  • tesp_support.weather.weather_agent module
  • tesp_support.weather.weather_agent_f module