Components & Fields

Every PowerWorld object type is represented by a component class (e.g. Bus, Gen, Branch). These classes carry metadata about their fields — which ones are primary keys, which are editable, and what the full set of available columns looks like. This metadata drives the indexable interface and provides IDE autocomplete.

The TS class provides constants for transient stability result fields, organized by object type.

from esapp.components import *
from esapp import TS

Keys and Field Categories

Primary keys uniquely identify an object in PowerWorld. They’re always included in query results and required when writing a DataFrame back. Different object types have different key structures:

In [2]:

Bus.keys(), Gen.keys(), Branch.keys()

Out[2]:

(['BusNum'],
 ['BusNum', 'GenID'],
 ['BusName_NomVolt:1', 'BusNum', 'LineCircuit', 'BusNum:1'])

Beyond primary keys, each component has several field categories:

  • Identifiers - the union of primary and secondary keys (like BusName or AreaNum). Secondary keys help PowerWorld resolve which object you mean during writes.

  • Editable - fields you can modify (generation setpoints, voltage targets, load values, etc.). Writing to a read-only field raises a ValueError.

  • Settable - identifiers plus editable fields, i.e. everything allowed in a write operation.

  • Fields - the complete set of all known fields, including read-only calculated results.

In [8]:

Bus.identifiers()

Out[8]:

{'AreaNum', 'BusName', 'BusName_NomVolt', 'BusNomVolt', 'BusNum', 'ZoneNum'}

In [4]:

len(Bus.editable()), len(Bus.settable()), len(Bus.fields())

Out[4]:

(111, 113, 581)

Transient Stability Fields

The TS class provides constants for transient stability result fields, organized by object type - TS.Gen, TS.Bus, TS.Branch, TS.Load, etc. Each field is a TSField with a name and description. Typing TS.Gen. in your IDE autocompletes every available generator result field.

Some fields are indexed (e.g. multiple input signals on a bus). Use bracket notation like TS.Bus.Input[1] to create the indexed variant. Use dir() to list all available fields for a given object type.

In [5]:

TS.Gen.P, TS.Gen.Q, TS.Gen.Delta

Out[5]:

(TSField('TSGenP'), TSField('TSGenQ'), TSField('TSGenDelta'))

In [6]:

TS.Gen.Delta.description

Out[6]:

'Rotor Angle relative to angle reference (degrees)'

In [7]:

TS.Bus.Input[1], TS.Bus.Input[2]

Out[7]:

(TSField('TSBusInput:1'), TSField('TSBusInput:2'))