tesp_support.api package

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

Submodules

tesp_support.api.bench_profile module

tesp_support.api.bench_profile.bench_profile(func)

tesp_support.api.data module

Path and Data functions for use within tesp_support.

tesp_support.api.data.arguments(description='', args='')

tesp_support.api.data.tesp_component()

tesp_support.api.entity module

class tesp_support.api.entity.Entity(entity, config)

Bases: object

add_attr(datatype, label, unit, item, value=None)

Add the Item attribute to the Entity

Parameters:

datatype (str) – Describes the datatype of the attribute
label (str) – Describes the attribute
unit (str) – The unit name of the attribute
item (str) – The name of the attribute
value (any) – The value of the item

Return type:

Item

count()

Returns:: The number of defined Items in the Entity
Return type:: int

del_attr(item)

Delete the Item from the Entity

Parameters:: item (str) – name of the attribute in the Entity

del_instance(object_name)

Delete the Entity instance

Parameters:: object_name (str) – the name of the instance

del_item(object_name, item)

Delete the value of the Entity instance from the Item

Parameters:

object_name (str) – the name of the instance
item (str) – name of the Item

find_item(item)

Find the Item from the Entity

Parameters:: item (str) – name of the attribute in the entity
Return type:: Item

get_instance(object_name)

Get the Entity instance

Parameters:: object_name (str) – the name of the instance
Returns:: an object with name and values or None when object_name is invalid
Return type:: Entity instance

instanceToJson()

Stringify the instance(s) in the Entity to JSON

Returns:: JSON string of the instance(s) in the Entity
Return type:: str

instanceToSQLite(connection)

Commit the instance(s) in the Entity to SQLite

Parameters:: connection – A valid sqlite connection object

set_instance(object_name, params)

Set the Entity instance the given set of parameters

Parameters:

object_name (str) – the name of the instance
params (list<list>) – list of the attribute parameters

Returns:

an object with name and values

Return type:

Entity instance

set_item(object_name, item, val)

Set the value of the Entity instance for the Item

Parameters:

object_name (str) – the name of the instance
item (str) – name of the Item
val (any) – value of the item

Returns:

the value or None when the value has not been set

Return type:

any

toHelp()

List the Item(s) in the Entity in help format with datatype, label, name, default value

Returns:: format list of the Items in the Entity
Return type:: str

toJson()

List the Item(s) in the Entity in json string format

Returns:: JSON string of the Items in the Entity
Return type:: str

toList()

List the Item(s) in the Entity

Returns:: list of Items in the Entity
Return type:: dict

toSQLite(connection)

Create a sqlite table to store the Item(s) in the Entity: with datatype, label, name, unit, default value

Parameters:: connection (Connection) – A valid sqlite connection object

class tesp_support.api.entity.Item(datatype, label, unit, item, value=None, range_check=None)

Bases: object

toFrame()

List the attribute in the Items

Returns:: with label, value, unit, datatype, name, range_check
Return type:: dist

toJSON()

Stringify the attribute in the Items to JSON

Returns:: JSON string with label, unit, datatype, value
Return type:: str

toList()

List the attribute in the Items

Returns:: with label, value, unit, datatype, name
Return type:: dist

tesp_support.api.entity.assign_defaults(obj, file_name)

Utilities that opens a JSON file and assigns the attributes to the specified object

Parameters:

obj (object) – any object like module or class
file_name (str) – a JSON file fully qualified path and name

Returns:

a dictionary of the JSON that has been loaded

Return type:

dict

tesp_support.api.entity.assign_item_defaults(obj, file_name)

Utilities that opens a JSON file and assigns the attributes Item to the specified object

Parameters:

obj (object) – any object like module or class
file_name (str) – a JSON file fully qualified path and name

Returns:

a dictionary of the JSON that has been loaded

Return type:

dict

tesp_support.api.gridpiq module

This script attempts to demonstrate the grid PIQ for new TESP API.

class tesp_support.api.gridpiq.GridPIQ

Bases: object

avg_dispatch_data(count)

Parameters:: count (int) –

reset_dispatch_data()

set_datetime(start_datetime, end_datetime, s_offset, e_offset)

Parameters:

start_datetime (str) – the start date and time with the format ‘%Y-%m-%d %H:%M:%S’
end_datetime (str) – the end date and time with the format ‘%Y-%m-%d %H:%M:%S’
s_offset (int) – in hours
e_offset (int) – in hours

set_dispatch_data(kind, idx, data)

Parameters:

kind –
idx –
data –

set_max_load(data)

Parameters:: data (float) –

toJson()

Return type:: dict

write(filename)

tesp_support.api.helpers module

Utility functions for use within tesp_support, including new agents.

class tesp_support.api.helpers.HelicsMsg(name, period)

Bases: object

config(_n, _v)

pubs(_g, _k, _t, _o, _p)

pubs_e(_g, _k, _t, _u)

pubs_n(_g, _k, _t)

subs(_k, _t, _o, _p)

subs_e(_r, _k, _t, _i)

subs_n(_k, _t)

write_file(_fn)

class tesp_support.api.helpers.all_but_one_level(level)

Bases: object

static filter(logRecord)

class tesp_support.api.helpers.all_from_one_level_down(level)

Bases: object

filter(logRecord)

tesp_support.api.helpers.enable_logging(level, model_diag_level, name_prefix)

Enable logging for process

Parameters:

level (str) – the logging level you want set for the process
model_diag_level (int) – initial value used to filter logging files
name_prefix (str) – description prefix for the log file name

tesp_support.api.helpers.get_run_solver(name, pyo, model, solver)

tesp_support.api.helpers.gld_strict_name(val)

Sanitizes a name for GridLAB-D publication to FNCS GridLAB-D name should not begin with a number, or contain ‘-’ for 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.api.helpers.random_norm_trunc(dist_array)

tesp_support.api.helpers.zoneMeterName(ldname)

Enforces the meter naming convention for commercial zones The commercial zones must be children of load objects This routine replaces “_load_” with “_meter”.

Parameters:: ldname (str) – the GridLAB-D name of a load, ends with _load_##
Returns:: The GridLAB-D name of upstream meter
Return type:: str

tesp_support.api.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.api.make_ems.cooling_coil_sensor(name, target, op)

tesp_support.api.make_ems.get_eplus_token(sval)

tesp_support.api.make_ems.global_variable(name, op)

tesp_support.api.make_ems.heating_coil_sensor(name, target, op)

tesp_support.api.make_ems.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.api.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:

sourcedir (str) – directory of the output from EnergyPlus baseline simulation, default ./output
baseidf (str) – is the original EnergyPlus model file without the EMS
target (str) – desired output file in PWD, default ems.idf
write_summary –
bHELICS –

tesp_support.api.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
target (str) – fully qualified path for new model
StepsPerHour –

tesp_support.api.make_ems.output_variable(name, target, op)

tesp_support.api.make_ems.print_idf_summary(zones, zonecontrols, thermostats, schedules, hcoils, ccoils, hvacs)

tesp_support.api.make_ems.schedule_actuator(name, target, op)

tesp_support.api.make_ems.schedule_sensor(name, op)

tesp_support.api.make_ems.summarize_idf(fname, baseidf)

tesp_support.api.make_ems.valid_var(name)

tesp_support.api.make_ems.write_new_ems(target, zones, zonecontrols, thermostats, schedules, hcoils, ccoils, hvacs, bHELICS)

tesp_support.api.make_ems.zone_heating_sensor(name, op)

tesp_support.api.make_ems.zone_occupant_sensor(name, op)

tesp_support.api.make_ems.zone_sensible_cooling_sensor(name, op)

tesp_support.api.make_ems.zone_sensible_heating_sensor(name, op)

tesp_support.api.make_ems.zone_temperature_sensor(name, op)

tesp_support.api.metrics_api module

tesp_support.api.metrics_api.actual_der_vs_projected_ratio(actual_der, actual_col_name, projected_col_name, projected_der=None)

This function calculates the accuracy of the predictive model, by comparing predicted results with actual results

Metric defined in the document VM_Actual Benefits_Predicted Benefits.docx

Parameters:

actual_der (dataframe) – time series dataframe that contains the total benefits from DER, as observed ex post.
actual_col_name (str) – id of the dataframe column that contains the actual DER benefit values
projected_col_name (str) – id of the dataframe column that contains the projected DER benefit values
projected_der (dataframe) – time series dataframe that contains the projected benefits from DER, as observed ex post.

Returns:

time series dataframe that contains the calculated ratios

Return type:

dataframe

tesp_support.api.metrics_api.get_average_air_temp_deviation(actual_df, actual_col_name, set_point_col_name, set_points_df, start_date_time)

Function calculates per device average deviation from desired indoor temperature set point in a year for each DSO

Metric defined in document VM_Average Indoor Air Temp Deviation.docx

Parameters:

actual_df (dataframe) – per-device average deviation from desired air temperature set point
actual_col_name (str) – dataframe column id for the location of actual temperatures
set_point_col_name (str) – dataframe column id for the location of set point data
set_points_df (dataframe) – time series data frame containing the set points data.
start_date_time (str) – the starting date and time when the calculation should start

Returns:

the average of the calculated differences between the average of actual: indoor temperature deviation from set point over one year.

Return type:

float

tesp_support.api.metrics_api.get_average_unit_price(time_series, column_id, start_date_time)

Function calculates the market average unit price (of electricity) over the course of 8,760 hours, in a specific service territory managed by an independent system operator

Metric defined in document VM_Market Average Unit Price.docx

Parameters:

time_series (dataframe) – time series dataframe that contains the hourly market electricity prices for a year
column_id (str) – name of the dataframe column that the price data is located
start_date_time (str) – the date and time that the calculations are to start at

Returns:

the average unit price for the year

Return type:

float

tesp_support.api.metrics_api.get_avg_customer_demand(time_series, start_date, val_col_id)

This function calculates the average of customer demand based on 8,760 hours of the year

Metric defined in VM_Average Customer Demand.docx

Parameters:

time_series (dataframe) – time series dataframe representing a time series containing customer demand records
start_date (datetime) – the start date and time that should be used in the calculation
val_col_id (str) – id of the dataframe column which contains the customer demand data values

Returns:

the calculated yearly average customer demand

Return type:

float

tesp_support.api.metrics_api.get_emergency_scarcity_sell(scarcity_power_df, scarcity_col_id, scarcity_price_df, price_col_id, generation_capacity_df, gen_col_id, available_power_df, available_col_id)

Function calculates the annual value of firm energy for Scarcity Conditions

Metric is defined in the document VM_Emergency Scarcity Wholesales Sells.docx

Parameters:

scarcity_power_df (dataframe) – time series dataframe that contains the power data used in calculation
scarcity_col_id (str) – name of the dataframe column where the power data is located
scarcity_price_df (dataframe) – time series dataframe that contains the price data used in calculation
price_col_id (str) – name of the dataframe column where the price data is located
generation_capacity_df (dataframe) – time series dataframe that contains the generation data used in calculation
gen_col_id (str) – name of the dataframe column where the generation data is located
available_power_df (dataframe) – time series dataframe that contains the available power data used in calculation
available_col_id (str) – name of the dataframe column where the available power data is located

Returns:

time series dataframe containing the calculated scarcity values

Return type:

dataframe

tesp_support.api.metrics_api.get_feeder_energy_losses(feeder_gen_df, gen_column_id, feeder_load_df, load_column_id, start_date_time, duration)

Function calculates the impact of trans-active energy systems on feeder energy losses. Data records in the time series entered as input must be recorded at five minute intervals

Metric defined in document VM_Feeder Energy Losses.docx

Parameters:

feeder_gen_df (dataframe) – data frame containing the 5-min average total generation from bulk power system and DERs
gen_column_id (str) – name of the column in the feeder generation dataframe where the generation data is located
feeder_load_df (dataframe) – data frame containing the 5-min average total load
load_column_id (str) – name of the column in the feeder load dataframe where the load data is located
start_date_time (str) – calculation start date and time
duration (int) – the duration of time in hours that the calculations are to be performed

Returns:

a dataframe object containing the generation, load, and losses data

Return type:

dataframe

tesp_support.api.metrics_api.get_hot_water_deficit(water_temperatures, water_column_id, desired_temperatures, desired_column_id, flow_rates, flow_column_id, delta_t, start_date_time, duration)

Function calculates device energy deficit from desired hot water temperature set point in a year

Metric defined in document VM_Hot Water Supply Deficit.docx

Parameters:

water_temperatures (dataframe) – per device 5-min average hot water actual temperature
water_column_id (str) – name of the dataframe column where the temperature data is located
desired_temperatures (dataframe) – per device 5-min average hot water temperature set point
desired_column_id (str) – name of the dataframe column where the set point temperature data is located
flow_rates (dataframe) – per device 5-min average hot water flow rate
flow_column_id (str) – name of the dataframe column where the flow rate data is located
delta_t (float) – time difference
start_date_time (str) – the date and time that the calculations are to start at
duration (int) – the length of time which the calculations should be executed

Returns:

time series dataframe containing the calculated deficit data

Return type:

dataframe

tesp_support.api.metrics_api.get_indoor_air_temp_deviation(time_series, column_id, set_point, start_date_time, duration)

Function calculates the maximum actual indoor temperature deviation from set point over one year.

Metric is defined in document VM_Max Indoor Air Temp Deviation.docx

Parameters:

time_series (dataframe) – time series dataframe that contains 5 minute max deviation data for a year
column_id (str) – the name of the dataframe column where the deviation data is located
set_point (float) – The set point value that is to be used in the calculation
start_date_time (str) – the date and time that the calculations are to start
duration (int) – the time duration in hours for which the calculations should be performed

Returns:

time series dataframe containing the maximum deviations calculated hourly from the input data

Return type:

dataframe

tesp_support.api.metrics_api.get_max_comm_packet_size(time_series, size_column_id, start_date_time, duration)

Function calculates the maximum size of a message sent in the communication channels

Metric is defined in document VM_Maximum Communication Packet Size.docx

Parameters:

time_series (dataframe) – time series dataframe that contains the communication network packet size Mbs
size_column_id (str) – name of the dataframe column that contains the packet size data
start_date_time (str) – the starting date and time when the calculation should start
duration (int) – the length of time which the calculations should be executed

Returns:

the maximum communication packet size for the time period entered

Return type:

float

tesp_support.api.metrics_api.get_max_duration_over_voltage(time_series, column_id, limit_val, start_date_time, duration)

Function calculates the maximum duration of an over-voltage event reported at each feeder

Metric defined in document VM_Max Duration of Over-Voltage Violations.docx

Parameters:

time_series (dataframe) – time series dataframe that contains the 5-minute three-phase voltage data
column_id (str) – name of the dataframe column the voltage data is located
limit_val (float) – threshold value used to compare voltage values against
start_date_time (str) – calculation start date and time
duration (int) – the duration of time in hours that the calculations are to be performed

Returns:

hourly time series dataframe containing the calculated maximum duration of voltage violating under-voltage limit

Return type:

dataframe

tesp_support.api.metrics_api.get_max_duration_under_voltage(time_series, column_id, limit_val, start_date_time, duration)

Function calculates the maximum duration of an under-voltage event reported at each feeder

Metric defined in document VM_Max Duration of Under-Voltage Violations.docx

Parameters:

time_series (dataframe) – time series dataframe that contains the 5-minute three-phase voltage data
column_id (str) – name of the dataframe column the voltage data is located
limit_val (float) – threshold value used to compare voltage values against
start_date_time (str) – calculation start date and time
duration (int) – the duration of time in hours that the calculations are to be performed

Returns:

hourly time series dataframe containing the calculated maximum duration of voltage violating under-voltage limit

Return type:

dataframe

tesp_support.api.metrics_api.get_max_market_price(time_series, column_id, start_date_time)

Function calculates the highest market price (of electricity) over the course of 8,760 hours, in a specific service territory managed by an independent system operator

Metric defined in document VM_Highest Market Price.docx

Parameters:

time_series (dataframe) – time series dataframe containing the hourly market price for electricity within a territory served by an ISO or balancing authority, for each of the 8,760 hours per year.
column_id (str) – name of the dataframe column where the market price data is located
start_date_time (str) – the date and time that the calculations are to start at

Returns:

the maximum market price value found in the market price dataset

Return type:

float

tesp_support.api.metrics_api.get_max_over_voltage(time_series, column_id, threshold_val, start_date_time, duration)

Function calculates the maximum over-voltage deviation reported each hour in the feeder voltage data

Metric is defined in document VM_Max Over-Voltage Violations.docx

Parameters:

time_series (dataframe) – time series dataframe containing feeder voltage data in 5 minute intervals
column_id (str) – the name of the dataframe column where the voltage data is located
threshold_val (float) – the maximum threshold data that is used to compare against the voltage data
start_date_time (str) – calculation start date and time
duration (int) – the duration of time in hours that the calculations are to be performed

Returns:

time series dataframe containing the calculated hourly over voltage maximum values

Return type:

dataframe

tesp_support.api.metrics_api.get_max_under_voltage(time_series, column_id, threshold_val, start_date_time, duration)

Function calculates the maximum over-voltage deviation reported each hour in the feeder voltage data

Metric is defined in document VM_Max Under-Voltage Violations.docx

Parameters:

time_series (dataframe) – time series dataframe containing feeder voltage data in 5 minute intervals
column_id (str) – the name of the dataframe column where the voltage data is located
threshold_val (float) – the maximum threshold data that is used to compare against the voltage data
start_date_time (str) – calculation start date and time
duration (int) – the duration of time in hours that the calculations are to be performed

Returns:

time series dataframe containing the calculated hourly over voltage maximum values

Return type:

dataframe

tesp_support.api.metrics_api.get_mean_absolute_percentage(actual_load_df, actual_col_id, forecasted_load_df, forecasted_col_id, start_date_time, duration)

Function calculates the prediction accuracy of load forecasting methods.

Metric is defined in document VM_Mean Absolute Percentage (Load) Error.docx

Parameters:

actual_load_df (dataframe) – time series dataframe containing the actual load observed over a period of time
actual_col_id (str) – name of the column where actual load data is located
forecasted_load_df (dataframe) – time series dataframe containing the forecasted load observed over a period of time
forecasted_col_id (str) – name of the column where forecasted load data is located
start_date_time (str) – the starting date and time when the calculation should start
duration (int) – the length of time in hours which the calculations should be executed

Returns:

time series dataframe containing the calculated ratios, the calculated average value

Return type:

dataframe, float

tesp_support.api.metrics_api.get_minimum_market_price(time_series, price_col_id, start_date_time)

Function calculates the minimum market price (of electricity) over the course of 8,760 hours

Metric defined in document VM_Minimum Market Price.docx

Parameters:

time_series (dataframe) – Hourly market prices for electricity
price_col_id (str) – name of the dataframe column where the price data is located
start_date_time (str) – the starting date and time when the calculation should start

Returns:

the minimum market price found in the data over the course of a year

Return type:

float

tesp_support.api.metrics_api.get_peak_demand(time_series, column_id, start_date_time)

This function calculates the highest hourly electricity demand (MW) in the year of data contained in the dataframe

This metric is defined in document VM_PeakDemand or PeakSupply.docx

Parameters:

time_series (dataframe) – time series dataframe that contains the demand values over the course of a year
column_id (str) – name of the dataframe column where the demand data is located
start_date_time (str) – calculation start date and time

Returns:

maximum value identified in the dataframe column identified by column_id

Return type:

float

tesp_support.api.metrics_api.get_peak_supply(time_series, column_id, start_date_time)

This function calculates the highest hourly electricity supply (MW) in the year of data contained in the dataframe

This metric is defined in document VM_PeakDemand or PeakSupply.docx

Parameters:

time_series (dataframe) – time series dataframe that contains the supply values over the course of a year
column_id (str) – name of the dataframe column where the supply data is located
start_date_time (str) – calculation start date and time

Returns:

maximum value identified in the dataframe column identified by column_id

Return type:

float

tesp_support.api.metrics_api.get_pv_aep_valuation(solar_irradiation, pv_system_area, pv_system_efficiency)

Function calculates and estimate of the total annual power output from a PV system in the units of kWh

Metric defined in the document VM_PV Annual Energy Production.docx

Parameters:

solar_irradiation (float) – total solar irradiation incident on PV surface in the units of kWh/sq.m.
pv_system_area (float) – PV System Area
pv_system_efficiency (float) – PV System Efficiency

Returns:

the product of the three input values

Return type:

float

tesp_support.api.metrics_api.get_reactive_power_demand(time_series, max_col_id, avg_col_id, start_date_time, duration)

Function calculates the maximum and average substation reactive power flow reported each hour

Metric is defined in document VM_Substation Reactive Power Demand.docx

Parameters:

time_series (dataframe) – time series dataframe containing the 5-minute substation reactive power flow data
max_col_id (str) – name of the dataframe column containing the 5-minute maximum data
avg_col_id (str) – name of the dataframe column containing the 5-minute average data
start_date_time (str) – the starting date and time when the calculation should start
duration (int) – the length of time in hours which the calculations should be executed

Returns:

time series dataframe containing the hourly maximum and average values calculated by the function

Return type:

dataframe

tesp_support.api.metrics_api.get_substation_peak_power(time_series, power_col_id, start_date_time, duration)

Function calculates a substation’s maximum real power flow

Metric defined in document VM_Substation Peak Real Power Demand.docx

Parameters:

time_series (dataframe) – time series containing substation real power flow (Mvar) at 5 minute intervals
power_col_id (str) – name of the dataframe column containing the power flow data
start_date_time (str) – the starting date and time when the calculation should start
duration (int) – the length of time in hours which the calculations should be executed

Returns:

time series dataframe containing the calculated hourly peak power flow

Return type:

dataframe

tesp_support.api.metrics_api.get_synch_date_range(time_series)

Function returns the latest starting date/time and the earliest ending date/time of the time series data frames in the time series list

Parameters:: time_series (list<dataframe>) – List containing a set of pandas dataframes each representing a time series
Returns:: the latest start and the earliest end times found in the list of data frames
Return type:: datetime, datetime

tesp_support.api.metrics_api.get_system_energy_loss(energy_sold_df, sold_col_id, energy_purchased_df, purchased_col_id, start_date_time, duration)

Function calculates the energy losses inclusive of transmission and distribution losses

Metric defined in document VM_Total System Losses.docx

Parameters:

energy_sold_df (dataframe) – time series dataframe containing the 5-minute sold energy data
sold_col_id (str) – name of the dataframe column where the sold data is located
energy_purchased_df (dataframe) – time series dataframe containing the 5-minute purchased energy data
purchased_col_id (str) – name of the dataframe column where the purchased data is located
start_date_time (str) – the starting date and time when the calculation should start
duration (int) – the length of time in hours which the calculations should be executed

Returns:

time series dataframe containing the calculated hourly energy loss

Return type:

dataframe

tesp_support.api.metrics_api.get_system_energy_losses(feeder_generation_df, gen_col_id, feeder_load_df, feeder_col_id, start_date_time, duration)

Function calculates the total energy loss at a feeder

Metric is defined in document VM_System Energy Losses.docx

Parameters:

feeder_generation_df (dataframe) – time series dataframe containing the 5-minute total feeder generation data
gen_col_id (str) – name of the dataframe column where the generation data is located
feeder_load_df (dataframe) – time series dataframe containing the 5-minute total feeder load data
feeder_col_id (str) – name of the dataframe column where the load data is located
start_date_time (str) – the starting date and time when the calculation should start
duration (int) – the length of time in hours which the calculations should be executed

Returns:

time series dataframe containing the calculated hourly energy losses

Return type:

dataframe

tesp_support.api.metrics_api.get_total_pv_reactive_power(time_series, pv_col_id, start_date_time, duration)

Function calculates the hourly total system reactive power generated from PV

Metric defined in document VM_Total PV Reactive Power.docx

Parameters:

time_series (dataframe) – time series dataframe that contains the 5-minute power data used in the calculations
pv_col_id (str) – name of the dataframe column where the power data is located
start_date_time (str) – the starting date and time when the calculation should start
duration (int) – the length of time in hours which the calculations should be executed

Returns:

time series dataframe containing the calculated hourly total reactive power values

Return type:

dataframe

tesp_support.api.metrics_api.get_total_pv_real_power(time_series, pv_col_id, start_date_time, duration)

Function calculates the hourly total system reactive power generated from PV

Metric is defined in document VM_Total PV Real Power.docx

Parameters:

time_series (dataframe) – time series dataframe that contains the 5-minute power data used in the calculations
pv_col_id (str) – name of the dataframe column where the power data is located
start_date_time (str) – the starting date and time when the calculation should start
duration (int) – the length of time in hours which the calculations should be executed

Return type:

dataframe

tesp_support.api.metrics_api.get_total_wind_reactive_power(time_series, power_col_id, start_date_time, duration)

Function calculates the hourly total system reactive power generated from Wind

Metric defined in document VM_Total Wind Reactive Power.docx

Parameters:

time_series (dataframe) – time series dataframe containing the 5-minute wind reactive power data
power_col_id (str) – name of the dataframe column where the wind data is located
start_date_time (str) – the starting date and time when the calculation should start
duration (int) – the length of time in hours which the calculations should be executed

Returns:

time series dataframe containing the hourly wind power results

Return type:

dataframe

tesp_support.api.metrics_api.get_total_wind_real_power(time_series, power_col_id, start_date_time, duration)

Function calculates the hourly total system real power generated from wind

Metric defined in document VM_Total Wind Real Power.docx

Parameters:

time_series (dataframe) – time series dataframe containing the 5-minute wind power data
power_col_id (str) – name of the dataframe column where the wind data is located
start_date_time (str) – the starting date and time when the calculation should start
duration (int) – the length of time in hours which the calculations should be executed

Returns:

time series dataframe containing the hourly total wind data results

Return type:

dataframe

tesp_support.api.metrics_api.get_transmission_over_voltage(time_series, voltage_col_id, compare_val, start_date_time, duration)

Function calculates the maximum over-voltage violations at the transmission node

Metric defined in document VM_Transmission Over-Voltage Violation.docx

Parameters:

time_series (dataframe) – time series dataframe containing the 3-phase transmission node voltage
voltage_col_id (str) – name of the dataframe column containing the voltage data
compare_val (float) – threshold value to compare the data against
start_date_time (str) – the starting date and time when the calculation should start
duration (int) – the length of time in hours which the calculations should be executed

Returns:

time series dataframe containing the hourly transmission over voltage results

Return type:

dataframe

tesp_support.api.metrics_api.get_transmission_under_voltage(time_series, voltage_col_id, compare_val, start_date_time, duration)

Function calculates the maximum under-voltage violations at the transmission node

Metric defined in document VM_Transmission Under-Voltage Violation.docx

Parameters:

time_series (dataframe) – time series dataframe that contains the 5-minute voltage data
voltage_col_id (str) – name of the column where the voltage data is located
compare_val (float) – threshold value to compare the voltage data against
start_date_time (str) – the starting date and time when the calculation should start
duration (int) – the length of time in hours which the calculations should be executed

Returns:

time series dataframe containing the calculated hourly under voltage results

Return type:

dataframe

tesp_support.api.metrics_api.get_transmission_voltage_magnitude(time_series, column_id, start_date, duration)

Function calculates the hourly min, max, and avg values from the five-minute data contained in the time_series dataframe

Metric defined in document VM_Transmission Voltage Magnitude.docx

Parameters:

time_series (dataframe) – time series dataframe containing the five-minute data
column_id (str) – the name of the dataframe column with contains the transmission voltage data
start_date (datetime) – the starting date and time when the calculations should take place
duration (int) – the duration in hours to calculate the ending date and time when the calculations should take place

Returns:

the calculated hourly min, max, and average values in a time series dataframe

Return type:

dataframe

tesp_support.api.metrics_api.get_under_voltage_count(time_series, val_col_id, minimum_value)

Function calculates number of under-voltage violations during the year

Metric defined in VM_Count of Transmission Under-Voltage Violation Events.docx

Parameters:

time_series (dataframe) – dataframe containing a time series of transmission values
val_col_id (str) – The id of the dataframe column where the transmission values are located
minimum_value (float) – The value that is to be used to compare transmission values against

Returns:

time series dataframe containing a column with the under voltage counts

Return type:

dataframe

tesp_support.api.metrics_api.get_unserved_electric_load(supply_df, supply_col_id, demand_df, demand_col_id, start_date_time)

Function calculates the demand that was not met by supply during the course of 8760 hours

Metric defined in document VM_Unserved Electric Load.docx

Parameters:

supply_df (dataframe) – hourly supply data per year
supply_col_id (str) – name of the dataframe column where the supply data is located
demand_df (dataframe) – hourly demand data per year
demand_col_id (str) – name of the dataframe column where the demand data is located
start_date_time (str) – the starting date and time when the calculation should start

Returns:

time series dataframe containing the calculated unserved load data

Return type:

dataframe

tesp_support.api.metrics_api.get_valuation(time_series, start_date, column_index)

Function calculates the average power generated by solar photovoltaic (PV) power generators aggregated by hour of day.

Metric defined in document VM_Distribution of PV real power generation by hour.docx

Parameters:

time_series (dataframe) – dataframe containing the timeseries data to be used to calculate the valuations
start_date (datetime) – the starting date when the calculations will be started
column_index (str) – the dataframe column id that is used to identify the location of the values in the dataframe

Returns:

function returns a tuple containing the dataframe containing the valuation: values as a time series, a float representing the 14th percentile of the values, and a float representing the 86th percentile of the values

Return type:

dataframe, float, float

tesp_support.api.metrics_api.get_wind_energy_production(time_series, prod_col_id, start_date_time, duration)

Function calculates the amount of energy produced by wind at a feeder

Metric defined in document VM_Wind Energy Production.docx

Parameters:

time_series (dataframe) – time series dataframe that contains the 5-minute wind energy production data
prod_col_id (str) – name of the column where the wind energy production data is located
start_date_time (str) – the starting date and time when the calculation should start
duration (int) – the length of time in hours which the calculations should be executed

Returns:

time series dataframe containing the calculated hourly total wind energy results

Return type:

dataframe

tesp_support.api.metrics_api.synch_series(time_series, synch_interval, interval_unit)

Function synchronizes all the time series data frames in the time_series list, so they all have the same start and ending times and the same number of times based upon a shared sampling interval

Parameters:

time_series (list<dataframe>) – time series dataframe
synch_interval (int) – the size of the time intervals to be used in the time series
interval_unit (str) – the unit of the time interval the time series is to be sampled “T”, “H”, “S”

Returns:

time series dataframe containing the resampled data of the original

Return type:

list<dataframe>

tesp_support.api.metrics_api.synch_series_lengths(time_series)

Function clips each of the time series in the time_series list so that each time series data frame has the same start and ending times

Parameters:: time_series (list<dataframe>) – List containing a set of pandas dataframes each representing a time series
Returns:: a list containing the clipped time series data frames
Return type:: list<dataframe>

tesp_support.api.metrics_api.synch_time_series(series_list, synch_interval, interval_unit)

Function resamples the time steps of the dataframes contained in the input data frame list to match the time intervals specified in the inputs

Parameters:

series_list (list<dataframe>) – List containing a set of pandas dataframes each representing a time series
synch_interval (int) – the size of the time step which should be used to resample the dataframe
interval_unit (str) – the measurement unit of the interval to be sampled. The options for this function include the following options “nanoseconds”, “seconds”, “minutes”, “hours”, “days”, “months”, “years”

Returns:

pandas dataframe time series containing the resampled columns of data

Return type:

list<dataframe>

tesp_support.api.metrics_base_api module

tesp_support.api.metrics_base_api.adjust_date_time(start_date, offset_type, offset_val)

Function returns a date time object that is calculated by adding the offset_val to the entered start date

Parameters:

start_date – (datetime) the start date time
offset_type (str) – defines what interval of time is to be used. The following identifiers can be used “years”, “months”, “days”, “hours”, “minutes”, “seconds”, “nanoseconds”
offset_val (int) – the number of time intervals that are to be added to start_time

Returns:

the modified date time

Return type:

dataframe

tesp_support.api.metrics_base_api.check_dataframe_synchronization(data_frame_1, data_frame_2)

Function checks that two time series dataframes are synchronized by comparing size, starting time, and ending time of the data sets. If they are synchronized, the returns “Synchronized”. If they are not, then the function will return an error message dependent upon what test failed.

Parameters:

data_frame_1 (dataframe) – time series dataframe
data_frame_2 (dataframe) – time series dataframe

Returns:

a “Synchronized” message if the two dataframes are synchronized, if not, the function returns an error message

Return type:

str

tesp_support.api.metrics_base_api.check_for_5_minute_data(time_series)

Function checks if the data in the time series is 5-minute intervals

Parameters:: time_series (dataframe) – time series dataframe containing 5-minute data records
Returns:: True if the data in the dataframe is 5-minute and False if it is not
Return type:: bool

tesp_support.api.metrics_base_api.check_for_full_year_data(time_series)

Function checks if the input time series dataframe contains a full year’s worth of data

Parameters:: time_series (dataframe) – time series dataframe containing a year’s worth of data
Returns:: True if the time series contains a full year’s worth of data
Return type:: bool

tesp_support.api.metrics_base_api.check_for_hourly_data(time_series)

Function checks if the data in the time series is hourly

Parameters:: time_series (dataframe) – time series dataframe containing hourly data
Returns:: True if the data in the dataframe is hourly and False if it is not hourly
Return type:: bool

tesp_support.api.metrics_base_api.create_testing_dataframe(start_date, end_date, col_names, time_interval)

Function creates a testing dataframe containing random values

Parameters:

start_date (str) – the starting date of the time series
end_date (str) – then ending date of the time series
col_names (list<string>) – the names to be used as the column headers in the resultant dataframe
time_interval (int) – frequency of time intervals. These designations are the same as the designations used to define a pandas date_range e.g. “T”, “5T”, “H”, “12H”,…

Returns:

time series dataframe containing random data values over the course of the defined time range

Return type:

dataframe

tesp_support.api.metrics_base_api.get_accuracy_ratio(input_df, actual_index, simulated_index)

Function calculates the ratio of simulated data to actual data

Parameters:

input_df (dataframe) – time series dataframe containing data columns for actual and simulated values
actual_index (str) – column id where the actual data is located
simulated_index (str) – column id where the simulated data is located

Returns:

time series dataframe containing the calculated ratio values

Return type:

dataframe

tesp_support.api.metrics_base_api.get_avg_column_value(time_series, val_index)

Function calculates the mean of the values in a data column of a dataframe

Parameters:

time_series (dataframe) – time series dataframe containing the data to be averaged
val_index (str) – name of the column that contains the data to be averaged

Returns:

calculated average value for the column identified in the function arguments

Return type:

float

tesp_support.api.metrics_base_api.get_avg_data_value(time_series, column_id)

Function calculates the average of a column in the time series dataframe and returns the average value of the column

Parameters:

time_series (dataframe) – time series dataframe containing the data to be averaged
column_id (str) – name of the data column for which the average is to be calculated

Returns:

calculated average for the identified dataframe column

Return type:

float

tesp_support.api.metrics_base_api.get_column_total_value(time_series, column_id)

Function returns the sum of the values in a dataframe column

Parameters:

time_series (dataframe) – the time series dataframe which contains the data to be summed
column_id (str) – name of the column containing the values to be summed

Returns:

the sum of the values contained in the identified dataframe column

Return type:

float

tesp_support.api.metrics_base_api.get_max_column_value(time_series, val_index)

Function searches a designated column in the time series dataframe and returns the maximum value found in the column

Parameters:

time_series (dataframe) – time series dataframe containing the data to be searched for a maximum value
val_index (str) – name of the column where the data is located to calculate the maximum value

Returns:

the maximum data value found in the designated column

Return type:

float

tesp_support.api.metrics_base_api.get_min_column_value(time_series, val_index)

Function searches a designated column in the time series dataframe and returns the minimum value found in the column

Parameters:

time_series (dataframe) – time series dataframe containing the data to be searched for a minimum value
val_index (str) – name of the column where the data is located to calculate the minimum value

Returns:

the minimum data value found in the designated column

Return type:

dataframe

tesp_support.api.metrics_base_api.get_node_data(time_series, node_id, id_column_name)

Function queries the time series dataframe for the data set identified by the entered node id

Parameters:

time_series (dataframe) – time series dataframe contains the node data to be queried
node_id (str) – the id of the node that is to be used in the query
id_column_name (str) – name of the time series dataframe column that contains the node ids to be queried against

Returns:

time series dataframe containing data specific to a single node id

Return type:

dataframe

tesp_support.api.metrics_base_api.get_node_ids(time_series, id_column_name)

Function queries a list of unique values from a time series dataframe based upon a column id entered by the user

Parameters:

time_series (dataframe) – time series dataframe that contains the values to be queried
id_column_name (str) – name of the dataframe column where the values are located

Returns:

list object containing the unique values found in the time series dataframe

Return type:

list

tesp_support.api.metrics_base_api.get_time_series_average(time_series, start_date, duration)

Function calculates the average of each data column in the dataframe

Parameters:

time_series (dataframe) – time series dataframe containing the data to be averaged
start_date (str) – the starting date and time that should be used in the calculation of the averages
duration (int) – the duration in hours that the averages should be calculated

Returns:

dataframe containing the average value for each column in the input dataframe

Return type:

dataframe

tesp_support.api.metrics_base_api.get_time_series_difference_values(time_series, column_id, time_series2, column_id2)

Function calculates the difference between data in a column of a dataframe with the data in a column of a second dataframe

Parameters:

time_series (dataframe) – time series dataframe containing a data set to be used in the calculation
column_id (str) – name of the column where the data to be used is located
time_series2 (dataframe) – time series dataframe containing a data set to be used in the calculation
column_id2 (str) – name of the column where the data to be used is located

Returns:

the total value difference calculated as time_series2 - time_series1

Return type:

float

tesp_support.api.metrics_base_api.get_time_series_max_value_over(time_series, column_id, compare_value)

Function calculates the maximum value out of the number of values in a dataframe column that are greater than a comparison value

Parameters:

time_series (dataframe) – time series dataframe containing the data to be compared
column_id (str) – the name of the column in the dataframe where the data is located
compare_value (str) – the value the data is to be compared with

Returns:

the maximum of the values that are greater than the compare value

Return type:

int

tesp_support.api.metrics_base_api.get_time_series_max_value_under(time_series, column_id, compare_value)

Function calculates the maximum value out of the number of values in a dataframe column that are less than a comparison value

Parameters:

time_series (dataframe) – time series dataframe containing the data to be compared
column_id (str) – the name of the column in the dataframe where the data is located
compare_value (str) – the value the data is to be compared with

Returns:

the maximum of the values that are less than the compare value

Return type:

int

tesp_support.api.metrics_collector module

Utility functions for metrics collection within tesp_support, able to write to JSON and HDF5

class tesp_support.api.metrics_collector.MetricsCollector(start_time='1970-01-01 00:00:00')

Bases: object

Metrics collector base class that handles collecting and writing data to disk (.json).

start_time

the start time of the simulation

Type:: pd.Timestamp

metrics_stores

list of MetricsStores holding/growing data

Type:: list

classmethod factory(start_time='1970-01-01 00:00:00', write_hdf5=False)

Parameters:

start_time (str) – start time of simulation in datetime string format
write_hdf5 (bool) – flag to determine if we write to .h5 (if True) or .json (if False; defaults to this)

Returns:

MetricsCollectorHDF or Base instance, depending on write_hdf5 flag

Return type:

MetricsCollector

finalize_writing()

register_metrics_store(metrics_store)

Parameters:: metrics_store (MetricsStore) – A store to be appended to our ongoing list

write_metrics(): Write all known metrics to disk (.json) and reset data within each metric.

class tesp_support.api.metrics_collector.MetricsCollectorHDF(start_time='1970-01-01 00:00:00')

Bases: MetricsCollector

finalize_writing()

write_metrics(): Write all known metrics to disk (.h5).

class tesp_support.api.metrics_collector.MetricsStore(name_units_pairs, file_string, collector)

Bases: object

This stores our metrics in appropriately sized tables, geared towards being ready to write to hdf5 (so writing to json might take longer than if we kept things ready to write to json).

time_uid_pairs

an ongoing list of (time, uid) pairs incoming with data

Type:: list

index_to_shapes

shapes of incoming column’s units

Type:: list

file_string

the file path (barring extension) which will be appended with “_metrics.{h5, json}”

Type:: str

collector

a common store for these metrics, to ease writing out all metrics/tables

Type:: MetricsCollector

append_data(time, uid, *args): Appends a single (time, uid) pair’s metrics to appropriate tables (depends on shape of each arg)

time (str or int): time in seconds after start of simulation uid (str or int or ?): unique identifier of an object (e.g. a name) args (list): an list of length/order equal to name_units_pairs seen when constructing this store

clear()

class tesp_support.api.metrics_collector.MetricsTable(columns, units)

Bases: object

append_data(data)

clear()

to_frame(times, uids, shape, filename='')

tesp_support.api.metrics_collector.deepish_copy(obj)

Faster approach to deepcopy, for an object of the simple python types. :param obj: original object to copy

Returns:: copy of obj
Return type:: object

tesp_support.api.metrics_collector.finalize_hdf(metrics_store)

tesp_support.api.metrics_collector.to_hdf(metrics_store, start_time, num_writes_counter)

This function writes the metric data to HDF5 files (and clears the data)

Parameters:

metrics_store (MetricsStore) – a store containing metrics tables to dump to file
start_time (pd.Timestamp) – start time of simulation times
num_writes_counter (int) – interval counter

tesp_support.api.metrics_collector.to_json(metrics_store, start_time): This function writes the metric data to JSON files (and clears the data) :param metrics_store: a store containing metrics tables to dump to file :type metrics_store: MetricsStore :param start_time: start time of simulation times :type start_time: pd.Timestamp

tesp_support.api.model_GLM module

GridLAB-D model I/O for TESP api

class tesp_support.api.model_GLM.GLM: Bases: object

class tesp_support.api.model_GLM.GLModel

Bases: object

GLModel class

Examples miscellaneous for set declarations:

#set profiler=1
#set pauseatexit=1
#set relax_naming_rules=1
#set suppress_repeat_messages=1

Examples format value set declarations:

#set double_format=%+.12lg
#set complex_format=%+.12lg%+.12lg%c
#set complex_output_format=RECT

Example Deltamode set declarations:

#set deltamode_timestep=100000000       //100 ms
#set deltamode_maximumtime=60000000000  //1 minute
#set deltamode_iteration_limit=10       //Iteration limit
#set deltamode_forced_always=true

Backbone file should follow order below:

clock
#set ...
#define ...
#include ...
module ...
objects ...
schedule ...

Can be used any where:

#define -> are one line black boxes
#include -> *.glm files are black boxes
#ifdef / #endif -> are black boxes

add_object(_type, name, params)

del_object(_type, name)

draw_network()

edge_classes = {'fuse': 'blue', 'overhead_line': 'black', 'parent': 'violet', 'recloser': 'green', 'regulator': 'yellow', 'switch': 'red', 'transformer': 'orange', 'triplex_line': 'brown', 'underground_line': 'gray'}

entitiesToHelp()

entitiesToJson()

entitiesToSQLite(filename)

get_InlineComment(object_name, item_id)

Parameters:

object_name –
item_id –

Returns:

contain the line that makes up item and the comment

Return type:

str

get_InsideComments(object_name, item_id)

Parameters:

object_name –
item_id –

Returns:

contain the lines that makes up the comment

Return type:

str

static get_diction(obj_entities, object_name, instanceTo, name)

get_module_instance(mod_type)

get_object_instance(obj_type, object_name)

static get_region(s)

static 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

glm_module(mod, line, itr)

Store a clock/module/class in the model structure

Parameters:

mod (str) – glm type [date, class, module]
line (str) – glm line containing the object definition
itr (iter) – iterator over the list of lines

Returns:

the module type

Return type:

str

glm_object(parent, line, itr, oidh, counter)

Store an object in the model structure

Parameters:

parent (str) – name of parent object (used for nested object defs)
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
counter (int) – object counter

Returns:

the current line, counter, name

Return type:

str, int, str

glm_schedule(line, itr)

instanceToModule(i_module, module_name)

Adds the comments pulled from the glm file to the new/modified glm file.

Parameters:

i_module –
module_name –

Returns:

contains the lines that make up the module

Return type:

str

instanceToObject(i_object, object_name)

Adds the comments pulled from the glm file to the new/modified glm file.

Parameters:

i_object –
object_name –

Returns:

contains the lines that make up the object

Return type:

str

instancesToGLM()

instancesToSQLite(filename)

is_edge_class(s)

Edge class is networkx terminology. In GridLAB-D, we will represent those with the variable ‘edge_classes’ define in this model

Parameters:: s (str) – the GridLAB-D class name
Returns:: True if an edge class, False otherwise
Return type:: bool

is_node_class(s)

Node class is networkx terminology. In GridLAB-D, we will represent those nodes with the variable ‘node_classes’ define in this model

Node class is networkx terminology. In GridLAB-D, node classes are in node_class. :param s: the GridLAB-D class name :type s: str

Returns:: True if a node class, False otherwise
Return type:: bool

node_classes = {'house': 'brown', 'load': 'blue', 'meter': 'green', 'node': 'red', 'substation': 'black', 'triplex_meter': 'orange', 'triplex_node': 'yellow'}

plot_model(node_labels=False, edge_labels=False, node_legend=True, edge_legend=True)

read(filename)

readBackboneModel(root_name)

readModel(filename)

Reads and parses the model from filename, usually but not necessarily one of the PNNL taxonomy feeders

Parameters:: filename (str) – fully qualified model path/name

set_declarations = ['profiler', 'iteration_limit', 'randomseed', 'relax_naming_rules', 'minimum_timestep', 'suppress_repeat_messages', 'pauseatexit', 'double_format', 'complex_format', 'complex_output_format', 'deltamode_timestep', 'deltamode_maximumtime', 'deltamode_iteration_limit', 'deltamode_forced_always']

set_module_instance(mod_type, params)

set_object_instance(obj_type, object_name, params)

write(filepath)

tesp_support.api.model_GLM.test1()

tesp_support.api.modify_GLM module

class tesp_support.api.modify_GLM.Defaults: Bases: object

class tesp_support.api.modify_GLM.GLMModifier

Bases: object

add_module(gld_type, params)

add_module_attr(gld_type, name, item_name, item_value)

add_object(gld_type, name, params)

add_object_attr(gld_type, name, item_name, item_value)

del_module(gld_type, name)

del_module_attr(gld_type, name, item_name)

del_object(gld_type, name)

del_object_attr(gld_type, name, item_name)

read_model(filepath)

rename_object(gld_type, old_name, new_name)

replace_object_type()

resize()

resize_secondary_transformers()

resize_substation_transformer()

set_simulation_times()

write_model(filepath)

tesp_support.api.parse_helpers module

tesp_support.api.parse_helpers.parse_helic_input(arg)

Helper function to find the magnitude of a possibly complex number from Helics as a string

Parameters:: arg (str) – The Helics value
Returns:: the parsed number, or 0 if parsing fails
Return type:: float

tesp_support.api.parse_helpers.parse_kva(arg)

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

Parameters:: arg (str) – the GridLAB-D P+jQ value
Returns:: the parsed kva value
Return type:: float

tesp_support.api.parse_helpers.parse_kva_old(arg)

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

Parameters:: arg (str) – the GridLAB-D P+jQ value
Returns:: the parsed kva value
Return type:: float

tesp_support.api.parse_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.api.parse_helpers.parse_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.api.parse_helpers.parse_magnitude_1(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.api.parse_helpers.parse_magnitude_2(arg)

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

Parameters:: arg (str) – The FNCS value
Returns:: the parsed number, or 0 if parsing fails
Return type:: float

tesp_support.api.parse_helpers.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.api.parse_helpers.parse_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.api.player module

tesp_support.api.player.load_player_loop(casename, keyName)

tesp_support.api.player.make_player(data_path)

Parameters:

name (str) – name of the player
prefix (str) – the prefix for the file prefix_player.json name and the federate prefix_player name
vals_rows (int) – number of rows in the file
power_factor (float) – power factor a load file, 0 for generator file
dt_load_collector (int) – interval between rows
date_time_str (str) – date and time “YYYY-MM-DD HH:MM:SS”
data_path (str) – the data file to be published
output (bool) – If true the player outputs data given at the dt_load_collector interval
output_hist (bool) – If true the player outputs data history
load (bool) – If true this a load player, else a generator player

Return type:

dict

tesp_support.api.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.api.process_eplus.plot_eplus(diction, title=None, save_file=None, save_only=False)

tesp_support.api.process_eplus.process_eplus(name_root, title=None, save_file=None, save_only=False)

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

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

Cooling system setpoint, actual temperature and the difference between them.
Heating system setpoint, actual temperature and the difference between them.
Price that the building controller responded to.

Parameters:

name_root (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 (bool) – set True with save_file to skip the display of the plot. Otherwise, script waits for user keypress.

tesp_support.api.process_eplus.read_eplus_metrics(path, name_root, quiet=False)

tesp_support.api.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.api.process_gld.plot_gld(diction, save_file=None, save_only=False)

tesp_support.api.process_gld.process_gld(name_root, diction_name='', save_file=None, save_only=False)

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

This function reads substation_[name_root]_metrics.json, billing_meter_[name_root]_metrics.json and house_[name_root]_metrics.json for the data; it reads [name_root]_glm_dict.json for the metadata. These must all exist in the current working directory. Makes one graph with 4 subplots:

Substation real power and losses
Average air temperature over all houses
Min/Max line-to-neutral voltage and Min/Max line-to-line voltage at the first billing meter
Min, Max and Average air temperature at the first house

Parameters:

name_root (str) – name of the TESP case, not necessarily the same as the GLM case, without the extension
diction_name (str) – metafile name (with json extension) for a different GLM dictionary, if it’s not [name_root]_glm_dict.json. Defaults to empty.
save_file (str) – name of a file to save plot, should include the png or pdf extension to determine type.
save_only (bool) – set True with save_file to skip the display of the plot. Otherwise, script waits for user keypress.

tesp_support.api.process_gld.read_gld_metrics(path, name_root, diction_name='')

tesp_support.api.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.api.process_houses.plot_houses(diction, save_file=None, save_only=False)

tesp_support.api.process_houses.process_houses(name_root, diction_name='', save_file=None, save_only=True)

Plots the temperature and HVAC power for every house

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

Average air temperature at every house
Average HVAC power at every house

Parameters:

name_root (str) – name of the TESP case, not necessarily the same as the GLM case, without the extension
diction_name (str) – metafile name (with json extension) for a different GLM dictionary, if it’s not [name_root]_glm_dict.json. Defaults to empty.
save_file (str) – name of a file to save plot, should include the png or pdf extension to determine type.
save_only (bool) – set True with save_file to skip the display of the plot. Otherwise, script waits for user keypress.

tesp_support.api.process_houses.read_houses_metrics(path, name_root, diction_name='')

tesp_support.api.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.api.process_inv.plot_inv(diction, save_file=None, save_only=False)

tesp_support.api.process_inv.process_inv(name_root, diction_name='', title=None, 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_[name_root]_metrics.json, billing_meter_[name_root]_metrics.json, capacitor_[name_root]_metrics.json, regulator_[name_root]_metrics.json, house_[name_root]_metrics.json and inverter_[name_root]_metrics.json for the data; it reads [name_root]_glm_dict.json for the metadata. If possible, it reads precool_[name_root]_metrics.json for temperature deviation. These must all exist in the current working directory. One graph is generated with 10 subplots:

Average P and Q over all inverters
Min, Max and Average line-neutral voltage over all billing meters
Average air temperature over all houses
Average temperature deviations from the setpoint over all houses
Total of ANSI C84 A and B range violation counts, summing over all billing meters
Total of ANSI C84 A and B range violation durations, summing over all billing meters
Substation total power, losses, house power, house HVAC power and house waterheater power
The accumulated bill, summed over all billing meters
The accumulated capacitor switching counts for each of 4 capacitor banks, if found, as in the IEEE 8500 case
The accumulated regulator counts for each of 4 voltage regulators, if found, as in the IEEE 8500 case

Parameters:

name_root (str) – name of the TESP case, not necessarily the same as the GLM case, without the extension
diction_name (str) – metafile name (with json extension) for a different GLM dictionary, if it’s not [name_root]_glm_dict.json. Defaults to empty.
title (str) –
save_file (str) – name of a file to save plot, should include the png or pdf extension to determine type.
save_only (bool) – set True with save_file to skip the display of the plot. Otherwise, script waits for user keypress.

tesp_support.api.process_inv.read_inv_metrics(path, name_root, diction_name='')

tesp_support.api.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.api.process_pypower.plot_pypower(diction, title=None, save_file=None, save_only=False)

tesp_support.api.process_pypower.process_pypower(name_root, title=None, 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_[name_root]_metrics.json and gen_[name_root]_metrics.json for the data, and [name_root]_m_dict.json for the metadata. These must all exist in the current working directory. One graph is generated with 8 subplots:

Bus P and Q demands, at the single GridLAB-D connection
Bus P and Q locational marginal prices (LMP), at the single GridLAB-D connection
Bus Vmin, Vmax and Vavg, at the single GridLAB-D connection
All 4 generator prices
Generator 1 P and Q output
Generator 2 P and Q output
Generator 3 P and Q output
Generator 4 P and Q output

Parameters:

name_root (str) – file name of the TESP case, not necessarily the same as the PYPOWER case, w/out the JSON 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 (bool) – set True with save_file to skip the display of the plot. Otherwise, script waits for user keypress.

tesp_support.api.process_pypower.read_pypower_metrics(path, name_root)

tesp_support.api.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.api.process_voltages.plot_voltages(diction, save_file=None, save_only=False)

tesp_support.api.process_voltages.process_voltages(name_root, diction_name='', save_file=None, save_only=True)

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

This function reads substation_[name_root]_metrics.json and billing_meter_[name_root]_metrics.json for the voltage data, and [name_root]_glm_dict.json for the meter names. These must all exist in the current working directory. One graph is generated with 2 subplots:

The Min line-to-neutral voltage at each billing meter
The Max line-to-neutral voltage at each billing meter

Parameters:

name_root (str) – name of the TESP case, not necessarily the same as the GLM case, without the extension
diction_name (str) – metafile name (with json extension) for a different GLM dictionary, if it’s not [name_root]_glm_dict.json. Defaults to empty.
save_file (str) – name of a file to save plot, should include the png or pdf extension to determine type.
save_only (bool) – set True with save_file to skip the display of the plot. Otherwise, script waits for user keypress.

tesp_support.api.process_voltages.read_voltages_metrics(path, name_root, diction_name='')

tesp_support.api.schedule_client module

class tesp_support.api.schedule_client.DataClient(port): Bases: object

tesp_support.api.schedule_server module

class tesp_support.api.schedule_server.DataProxy

Bases: object

static forecasting_pv_schedules(name, time, window_length, col_num)

Returns window length values of the given time for the name of schedule forecast and column

Parameters:

name (str) – schedule name for data frame
time (any) – current time
window_length (int) – length of window
col_num (int) – column number 1 to n

static forecasting_schedules(name, time, len_forecast)

Returns len_forecast values from the given time as for the name schedule forecast

Parameters:

name (str) – schedule name for data frame used to forecast
time (any) – current time at which DA optimization occurs
len_forecast (int) – length of forecast in hours

tesp_support.api.schedule_server.main()

tesp_support.api.schedule_server.schedule_server(config_file, port)

tesp_support.api.store module

Path and Data functions for use within tesp_support, including new agents.

class tesp_support.api.store.Directory(file, description=None)

Bases: object

get_includeDirs()

get_includeFiles(path)

set_includeDir(path, recurse=False)

set_includeFile(path, mask)

toJSON()

zip(zipfile)

class tesp_support.api.store.Schema(file, name=None, description=None)

Bases: object

get_columns(table, skip_rows=0)

get_date(table)

get_series_data(table, start, end, usecols=None, index_col=None)

get_tables()

set_date_bycol(table, name)

set_date_byrow(table, start, interval)

toJSON()

class tesp_support.api.store.Store(file)

Bases: object

add_directory(directory)

add_file(path, name='', description='')

add_path(path, description='')

add_schema(scheme)

del_directory(name)

del_schema(name)

get_directory(name)

get_schema(name=None)

read()

write()

zip()

tesp_support.api.store.test_hdf5()

tesp_support.api.store.unzip(file, path): This function unzip take name add .zip and unzip the file to specified path. Then finds the store json in that path and fixes the relative path for the stores work

tesp_support.api.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.api.test_runner module

Auto test runner for TESP run* cases Runs a test case based on pre-existing shell script file.

If FNCS or HELICS broker exist the test waits for the broker process to finish before function returns.

This code has limited functionality as the ‘run*’ scripts for the examples are written in a very specified way.

tesp_support.api.test_runner.block_test(call)

tesp_support.api.test_runner.docker_line(line, local_vars)

tesp_support.api.test_runner.exec_test(file_name, case_name=None)

tesp_support.api.test_runner.init_tests()

tesp_support.api.test_runner.process_line(line, local_vars)

tesp_support.api.test_runner.report_tests()

tesp_support.api.test_runner.run_docker_test(file_name, case_name=None)

tesp_support.api.test_runner.run_test(file_name, case_name=None)

tesp_support.api.test_runner.services(name, image, env, cnt, outfile, depends=None)

tesp_support.api.test_runner.start_test(case_name=None)

tesp_support.api.time_helpers module

Utility time functions for use within tesp_support, including new agents.

tesp_support.api.time_helpers.add_hhmm_secs(hhmm, secs)

Add hhmm time + seconds duration

Parameters:

hhmm (float) – HHMM
secs (int) – seconds

Returns:

hhmm+secs in hhmm format

tesp_support.api.time_helpers.get_dist(mean, var)

Get a random number from a distribution given mean and %variability

Parameters:

mean (float) – mean of distribution
var (float) – % variability

Returns:

one random entry from distribution

Return type:

float

tesp_support.api.time_helpers.get_duration(arrival, leave)

Convert arrival and leaving time to duration

Parameters:

arrival (float) – in HHMM format
leave (float) – in HHMM format

Returns:

duration in seconds

Return type:

int

tesp_support.api.time_helpers.get_hhmm_from_secs(time)

Convert seconds to HHMM

Parameters:: time (int) – seconds
Returns:: HHMM
Return type:: int

tesp_support.api.time_helpers.get_secs_from_hhmm(time)

Convert HHMM to seconds

Parameters:: time (float) – HHMM
Returns:: seconds
Return type:: int

tesp_support.api.time_helpers.is_hhmm_valid(time)

Check if HHMM is a valid number

Parameters:: time (float) – HHMM format
Returns:: true if valid or false if not
Return type:: bool

tesp_support.api.time_helpers.subtract_hhmm_secs(hhmm, secs)

Subtract hhmm time - secs duration

Parameters:

hhmm (float) – HHMM format time
secs (int) – seconds

Returns:

arrival time in HHMM

tesp_support.api.tso_PYPOWER module

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

Public Functions:

pypower_loop:: Initializes and runs the simulation.

tesp_support.api.tso_helpers module

Helpers for PYPOWER, PSST, MOST solutions

Public Functions:: print_matrix, print_keyed_matrix, load_json_case, print_mod_load, summarize_opf, make_dictionary, dist_slack

tesp_support.api.tso_helpers.dist_slack(mpc, prev_load)

Parameters:

mpc (dict) – PYPOWER case structure
prev_load (float) – previous load

Returns:

generator loads

Return type:

array

tesp_support.api.tso_helpers.load_json_case(file_name)

Helper function to load PYPOWER case from a JSON file

Parameters:: file_name (str) – the JSON file name to open
Returns:: the loaded PYPOWER case structure
Return type:: dict

tesp_support.api.tso_helpers.make_dictionary(mpc)

Helper function to write the JSON model dictionary metafile for post-processing

Additions to DSO, and Pnom==>Pmin for generators are there

Parameters:: mpc (dict) – PYPOWER case file structure based on matpower

tesp_support.api.tso_helpers.print_keyed_matrix(lbl, D, fmt='{:8.4f}')

tesp_support.api.tso_helpers.print_m_case(ppc, ppc_case)

tesp_support.api.tso_helpers.print_matrix(lbl, A, fmt='{:8.4f}')

tesp_support.api.tso_helpers.print_mod_load(bus, dso, model_load, msg, ts)

tesp_support.api.tso_helpers.summarize_opf(mpc)

Helper function to print optimal power flow solution (debugging)

Parameters:: mpc (dict) – solved using PYPOWER case structure

tesp_support.api.tso_psst module

tesp_support.api.tso_psst.make_generator_plants(ppc, renewables)