IEEE39 Bus Tutorial - Part I: Model Creation

This tutorial can be downloaded as a normal Julia script here.

This is the first part of a four-part tutorial series for the IEEE 39-bus test system:

  • Part I: Model Creation (this tutorial) - Build the network structure with buses, lines, and components
  • Part II: Initialization - Perform power flow calculations and dynamic initialization
  • Part III: Dynamic Simulation - Run time-domain simulations and analyze system behavior
  • Part IV: Advanced Modeling & Parameter Optimization - Create custom components and optimize system parameters

In this first part, we'll construct the complete IEEE 39-bus network model using PowerDynamics.jl, including generators, loads, transmission lines, and control systems.

System Structure

The system consists of 39 buses (with 10 generators and 19 loads) and 46 branches (12 of which are transformers).

The buses fall into the following categories:

  • Junction: pure transient buses without dynamic components
  • Load: buses with loads only
  • Controlled Machine: buses with controlled machines (generators with AVR and GOV)
  • Controlled Machine + Load: buses with controlled machines and loads
  • Uncontrolled Machine + Load: buses with uncontrolled machines and loads

For the power flow solution, we have a slack bus, PV buses and PQ buses.

For the dynamic simulation, we will use the following models:

  • ZIP Load for loads,
  • 6th Order Sauer-Pai Machine and
  • AVR Type I and TGOV1 for controlled machines.

Setup and Data Loading

No Standardized Data Import

As of now, PowerDynamics.jl does not support any advanced import mechanisms for power grids. Therefore, this tutorial loads the data from some custom CSV files.

First, we'll load the required packages and read the system data from CSV files. The IEEE 39-bus system data is organized into separate files for different components.

using PowerDynamics
using PowerDynamics.Library
using ModelingToolkitBase
using NetworkDynamics
using DataFrames
using CSV

DATA_DIR = joinpath(pkgdir(PowerDynamics), "docs", "examples", "ieee39data")

The system data is stored in CSV files containing:

bus.csv - Bus Configuration Data
ParameterDescription
busBus number (unique identifier)
bus_typePower flow bus type: "PQ" (load), "PV" (generator), "Slack" (reference)
categoryComponent category: "junction", "load", "ctrld_machine", "ctrld_machine_load", "unctrld_machine_load"
PActive power injection [pu] (positive = generation, negative = load)
QReactive power injection [pu] (positive = generation, negative = load)
VVoltage magnitude [pu] (for PV and Slack buses)
base_kvBase voltage level [kV]
has_loadBoolean flag indicating presence of load component
has_genBoolean flag indicating presence of generator component
has_avrBoolean flag indicating presence of automatic voltage regulator
has_govBoolean flag indicating presence of turbine governor
branch.csv - Transmission Line and Transformer Data
ParameterDescription
src_busSource bus number
dst_busDestination bus number
transformerTransformer flag (0 = line, 1 = transformer)
r_srcSource end transformation ratio [pu]
RSeries resistance [pu]
XSeries reactance [pu]
G_srcSource end shunt conductance [pu]
G_dstDestination end shunt conductance [pu]
B_srcSource end shunt susceptance [pu]
B_dstDestination end shunt susceptance [pu]
load.csv - ZIP Load Model Parameters
ParameterDescription
busBus number where load is connected
PsetActive power at operation point [pu]
QsetReactive power at operation point [pu]
KpZActive power constant impedance fraction
KqZReactive power constant impedance fraction
KpIActive power constant current fraction
KqIReactive power constant current fraction
KpCActive power constant power fraction (1-KpZ-KpI)
KqCReactive power constant power fraction (1-KqZ-KqI)

Note: ZIP loads combine constant impedance (Z), constant current (I), and constant power (P) components.

machine.csv - Generator (Sauer-Pai Machine) Parameters
ParameterDescription
busBus number where generator is connected
SnMachine power rating [MVA]
V_bBus voltage base [kV] (unused: duplicates base_kv in bus.csv)
VnMachine voltage rating [kV]
R_sStator resistance [pu]
X_lsStator leakage reactance [pu]
X_dd-axis synchronous reactance [pu]
X_qq-axis synchronous reactance [pu]
Xโ€ฒ_dd-axis transient reactance [pu]
Xโ€ฒ_qq-axis transient reactance [pu]
Xโ€ณ_dd-axis subtransient reactance [pu]
Xโ€ณ_qq-axis subtransient reactance [pu]
Tโ€ฒ_d0d-axis transient time constant [s]
Tโ€ฒ_q0q-axis transient time constant [s]
Tโ€ณ_d0d-axis subtransient time constant [s]
Tโ€ณ_q0q-axis subtransient time constant [s]
HInertia constant [s]
DDirect shaft damping coefficient
avr.csv - Automatic Voltage Regulator (AVR Type I) Parameters
ParameterDescription
busBus number where AVR-controlled generator is located
KaAmplifier gain
KeField circuit integral deviation
KfStabilizer gain
TaAmplifier time constant [s]
TfStabilizer time constant [s]
TeField circuit time constant [s]
TrMeasurement time constant [s]
vr_minMinimum regulator voltage [pu]
vr_maxMaximum regulator voltage [pu]
E1First ceiling voltage [pu]
Se1First ceiling saturation factor
E2Second ceiling voltage [pu]
Se2Second ceiling saturation factor
gov.csv - Turbine Governor (TGOV1) Parameters
ParameterDescription
busBus number where governor-controlled generator is located
V_minMinimum valve position [pu]
V_maxMaximum valve position [pu]
RGovernor droop [Machine PU]
T1First transient time constant [s]
T2Second transient time constant [s]
T3Third transient time constant [s]
DTTurbine damping coefficient
ฯ‰_refFrequency setpoint [pu]
branch_df = CSV.read(joinpath(DATA_DIR, "branch.csv"), DataFrame)
bus_df = CSV.read(joinpath(DATA_DIR, "bus.csv"), DataFrame)
load_df = CSV.read(joinpath(DATA_DIR, "load.csv"), DataFrame)
machine_df = CSV.read(joinpath(DATA_DIR, "machine.csv"), DataFrame)
avr_df = CSV.read(joinpath(DATA_DIR, "avr.csv"), DataFrame)
gov_df = CSV.read(joinpath(DATA_DIR, "gov.csv"), DataFrame)

System base values follow the IEEE 39-bus standard. Sbase and the frequency base are global in PowerDynamics: they are set once, before any model is constructed, and every component built afterwards bakes them in. Since they are read at construction time, changing them later has no effect on models that already exist โ€” and by the same token, a script that changes them should restore the defaults when it is done, which we do at the very end of this page.

BASE_MVA = 100.0
BASE_FREQ = 60.0
set_Sbase!(BASE_MVA)
set_fbase!(BASE_FREQ)

Device Models

Each bus is a busbar plus whatever devices the data lists for it. Before we build the buses, we look at the device models we are going to use. Those are MTK models and not yet compiled node models. See Modeling Concepts and the custom bus tutorial.

Load Model

We use the ZIPLoad model to represent loads. This model satisfies the Injector Interface.

(t) โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
 oโ”€โ”€โ”ค ZIP Load โ”‚
    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Generator Models

For generators, we use the SauerPaiMachine, a 6th-order synchronous machine model. It appears in two variants.

Uncontrolled Machine: No external control inputs for mechanical torque or field voltage. This model satisfies the Injector Interface directly.

(t) โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
 oโ”€โ”€โ”ค Machine โ”‚
    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Controlled Machine: Includes an automatic voltage regulator (AVRTypeI) and a turbine governor (TGOV1).

The controlled machine is modeled as a composite injector. It consists of 3 subcomponents: the machine, the AVR and the governor. The AVR receives the voltage magnitude measurement from the terminal of the machine and sets the field voltage. The governor receives the frequency measurement and sets the mechanical torque. Together, they satisfy the Injector Interface.

      โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
      โ”‚ CtrldMachine  u_mag_meas      โ”‚
      โ”‚              โ•ญโ”€โ”€โ”€โ”€โ”€โ†’โ”€โ”€โ”€โ”€โ•ฎ     โ”‚
      โ”‚    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”      โ”Œโ”€โ”ดโ”€โ”€โ”€โ” โ”‚
  (t) โ”‚    โ”‚           โ”œโ”€โ”€โ”€โ†โ”€โ”€โ”ค AVR โ”‚ โ”‚
   oโ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”ค Sauer-Pai โ”‚ vf   โ””โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚
      โ”‚    โ”‚ Machine   โ”‚ ฯ„_m  โ”Œโ”€โ”€โ”€โ”€โ”€โ” โ”‚
      โ”‚    โ”‚           โ”œโ”€โ”€โ”€โ†โ”€โ”€โ”ค Gov โ”‚ โ”‚
      โ”‚    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”˜      โ””โ”€โ”ฌโ”€โ”€โ”€โ”˜ โ”‚
      โ”‚              โ•ฐโ”€โ”€โ”€โ”€โ”€โ†’โ”€โ”€โ”€โ”€โ•ฏ     โ”‚
      โ”‚                 ฯ‰_meas        โ”‚
      โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Bus Structures

Combining those devices, the buses in the data come in five structures. We don't need to set them up ahead of time; they emerge when we build each bus from the devices listed for it. Still, it helps to know what is coming.

Junction Bus: pure transmission buses with no generation or load.

           โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•—
           โ•‘ Junction (compiled)  โ•‘
 Network   โ•‘  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ•‘
interface  โ•‘  โ”‚MTKBus           โ”‚ โ•‘
 current โ”€โ”€โ”€โ”€โ†’โ”‚โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”         โ”‚ โ•‘
           โ•‘  โ”‚โ”‚BusBarโ”‚(nothing)โ”‚ โ•‘
 voltage โ†โ”€โ”€โ”€โ”€โ”‚โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”˜         โ”‚ โ•‘
           โ•‘  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ•‘
           โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•

Load Bus: buses with only a load.

           โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•—
           โ•‘ Load (compiled)     โ•‘
 Network   โ•‘  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ•‘
interface  โ•‘  โ”‚MTKBus          โ”‚ โ•‘
 current โ”€โ”€โ”€โ”€โ†’โ”‚โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ” โ”‚ โ•‘
           โ•‘  โ”‚โ”‚BusBarโ”œoโ”คLoadโ”‚ โ”‚ โ•‘
 voltage โ†โ”€โ”€โ”€โ”€โ”‚โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ•‘
           โ•‘  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ•‘
           โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•

Generator Bus (Controlled): buses with a controlled generator (machine + AVR + governor).

            โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•—
            โ•‘ Ctrld Machine Bus (compiled)                   โ•‘
            โ•‘  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ•‘
            โ•‘  โ”‚MTKBus                                     โ”‚ โ•‘
            โ•‘  โ”‚         โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ•‘
  Network   โ•‘  โ”‚         โ”‚CtrldMachine  โ•ญโ”€โ”€โ”€โ”€โ”€โ†’โ”€โ”€โ”€โ”€โ•ฎ     โ”‚ โ”‚ โ•‘
 interface  โ•‘  โ”‚         โ”‚    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”      โ”Œโ”€โ”ดโ”€โ”€โ”€โ” โ”‚ โ”‚ โ•‘
  current โ”€โ”€โ”€โ”€โ†’โ”‚โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚    โ”‚           โ”œโ”€โ”€โ”€โ†โ”€โ”€โ”ค AVR โ”‚ โ”‚ โ”‚ โ•‘
            โ•‘  โ”‚โ”‚BusBarโ”œoโ”ผโ”€โ”€โ”€โ”€โ”ค Sauer-Pai โ”‚      โ””โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ”‚ โ•‘
  voltage โ†โ”€โ”€โ”€โ”€โ”‚โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚    โ”‚ Machine   โ”‚      โ”Œโ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ”‚ โ•‘
            โ•‘  โ”‚         โ”‚    โ”‚           โ”œโ”€โ”€โ”€โ†โ”€โ”€โ”ค Gov โ”‚ โ”‚ โ”‚ โ•‘
            โ•‘  โ”‚         โ”‚    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”˜      โ””โ”€โ”ฌโ”€โ”€โ”€โ”˜ โ”‚ โ”‚ โ•‘
            โ•‘  โ”‚         โ”‚              โ•ฐโ”€โ”€โ”€โ”€โ”€โ†’โ”€โ”€โ”€โ”€โ•ฏ     โ”‚ โ”‚ โ•‘
            โ•‘  โ”‚         โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ•‘
            โ•‘  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ•‘
            โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•

Generator + Load Bus (Controlled): buses with both a controlled generator and a load.

            โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•—
            โ•‘ Ctrld Machine Load Bus (compiled)               โ•‘
            โ•‘  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ•‘
            โ•‘  โ”‚MTKBus    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ•‘
            โ•‘  โ”‚          โ”‚CtrldMachine  โ•ญโ”€โ”€โ”€โ”€โ”€โ†’โ”€โ”€โ”€โ”€โ•ฎ     โ”‚ โ”‚ โ•‘
            โ•‘  โ”‚          โ”‚    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”      โ”Œโ”€โ”ดโ”€โ”€โ”€โ” โ”‚ โ”‚ โ•‘
            โ•‘  โ”‚          โ”‚    โ”‚           โ”œโ”€โ”€โ”€โ†โ”€โ”€โ”ค AVR โ”‚ โ”‚ โ”‚ โ•‘
  Network   โ•‘  โ”‚        โ”Œโ”€โ”ผโ”€โ”€โ”€โ”€โ”ค Sauer-Pai โ”‚      โ””โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ”‚ โ•‘
 interface  โ•‘  โ”‚        โ”‚ โ”‚    โ”‚ Machine   โ”‚      โ”Œโ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ”‚ โ•‘
  current โ”€โ”€โ”€โ”€โ†’โ”‚โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚ โ”‚    โ”‚           โ”œโ”€โ”€โ”€โ†โ”€โ”€โ”ค Gov โ”‚ โ”‚ โ”‚ โ•‘
            โ•‘  โ”‚โ”‚BusBarโ”œo โ”‚    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”˜      โ””โ”€โ”ฌโ”€โ”€โ”€โ”˜ โ”‚ โ”‚ โ•‘
  voltage โ†โ”€โ”€โ”€โ”€โ”‚โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚ โ”‚              โ•ฐโ”€โ”€โ”€โ”€โ”€โ†’โ”€โ”€โ”€โ”€โ•ฏ     โ”‚ โ”‚ โ•‘
            โ•‘  โ”‚        โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ•‘
            โ•‘  โ”‚        โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”                          โ”‚ โ•‘
            โ•‘  โ”‚        โ””โ”€โ”ค Load โ”‚                          โ”‚ โ•‘
            โ•‘  โ”‚          โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”˜                          โ”‚ โ•‘
            โ•‘  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ•‘
            โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•

Generator + Load Bus (Uncontrolled): buses with an uncontrolled generator and a load.

            โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•—
            โ•‘ Unctr. Ma. Load Bus (compiled) โ•‘
            โ•‘  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”    โ•‘
  Network   โ•‘  โ”‚MTKBus      โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚    โ•‘
 interface  โ•‘  โ”‚          โ”Œโ”€โ”ค Machine โ”‚ โ”‚    โ•‘
  current โ”€โ”€โ”€โ”€โ†’โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚    โ•‘
            โ•‘  โ”‚ โ”‚BusBarโ”œโ”€o             โ”‚    โ•‘
  voltage โ†โ”€โ”€โ”€โ”€โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”    โ”‚    โ•‘
            โ•‘  โ”‚          โ””โ”€โ”ค Load โ”‚    โ”‚    โ•‘
            โ•‘  โ”‚            โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”˜    โ”‚    โ•‘
            โ•‘  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜    โ•‘
            โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•

Model Cache

Getting from model equations to a compiled bus takes three steps:

  1. Construct the MTK models of the individual devices, such as the machine or the AVR. This is surprisingly costly, because it creates a lot of symbolic terms.
  2. Combine the models into composite systems, for example with CompositeInjector or MTKBus.
  3. Compile the bus with compile_bus. NetworkDynamics simplifies the equations of the whole bus and generates Julia code for them.

Most buses in a grid share their structure. The eight buses with a controlled machine in this system have the same equations and differ only in their parameter values. Repeating steps 1 and 3 for each of them would be wasted work. There are two ways to avoid that.

Templates: build one bus per structure up front and create every other bus as a copy of it with compile_bus(template; vidx, name), adjusting the parameters afterwards. Copying is the fastest way to get a bus. The catch is that you have to know the structures before you build the grid: sort the buses into categories, build a template for each category and pick the right one for every bus.

Model cache: build every bus from scratch, as if it were the only one, and let NetworkDynamics remember the expensive steps. Device models defined with @cached_component, like all library models used here, cover step 1: constructing a device again with the same options returns the stored model with the new parameter values. compile_bus covers step 3: for a bus with the same structure as an earlier one, it reuses the simplified equations and the generated code. This is a bit slower than copying a template, but the code simply follows the data.

What counts as the same structure are the equations, variables and model options (such as whether the machine has a field voltage input). Parameter values don't matter. If you are curious what was reused, NetworkDynamics.mtk_cache_stats() lists the cache hits.

This tutorial uses the cache. It is off by default, so we switch it on.

NetworkDynamics.set_mtk_cache!(:on)

Bus Construction

The device parameters are spread over the CSV files, one row per bus. A small helper collects the row of a bus into a NamedTuple, so we can splat it right into the model constructor.

function csv_params(table, bus)
    row = table[findfirst(==(bus), table.bus), :]
    # `V_b` in machine.csv duplicates `base_kv` in bus.csv. The voltage base is a
    # property of the bus, not of the machine, so we take it from bus.csv below.
    cols = filter(c -> c โˆ‰ ("bus", "V_b"), names(table))
    NamedTuple(Symbol(c) => row[c] for c in cols)
end

Now we go through bus.csv and build every bus from the devices the flags has_gen, has_avr, has_gov and has_load ask for:

  1. Build the device models with their parameters from the CSV files
  2. Combine them in an MTKBus
  3. Compile the bus with compile_bus, passing the vertex index, the power flow model (PQ, PV or Slack) and the voltage base

The voltage base is the one per-unit base that is genuinely per bus (this system mixes 16.5, 138, 230 and 345 kV). It only affects the SI observables (u_kV, P_MW, โ€ฆ) and is handed down to the incident lines during initialization. Sbase and ฯ‰base need no attention: they were set globally above and are picked up by every model we construct.

Compiling a bus is the expensive step. Since the cache is on, only the first bus of each structure is actually compiled; all others reuse it.

busses = []
for row in eachrow(bus_df)
    i = row.bus
    injectors = []

    if row.has_gen
        machine = SauerPaiMachine(;
            name=:machine,
            vf_input=row.has_avr,   ## field voltage set by an AVR
            ฯ„_m_input=row.has_gov,  ## mechanical torque set by a governor
            csv_params(machine_df, i)...,
        )
        if row.has_avr || row.has_gov
            # machine and controllers form one composite injector
            ctrld_gen = Any[machine]
            if row.has_avr
                avr = AVRTypeI(; name=:avr, ceiling_function=:quadratic, csv_params(avr_df, i)...)
                push!(ctrld_gen, avr)
            end
            if row.has_gov
                gov = TGOV1(; name=:gov, csv_params(gov_df, i)...)
                push!(ctrld_gen, gov)
            end
            push!(injectors, CompositeInjector(ctrld_gen; name=:ctrld_gen))
        else
            push!(injectors, machine)
        end
    end

    if row.has_load
        load = ZIPLoad(; name=:ZIPLoad, csv_params(load_df, i)...)
        push!(injectors, load)
    end

    pf_model = if row.bus_type == "PQ"
        pfPQ(P=row.P, Q=row.Q)  ## Load bus: fixed P and Q
    elseif row.bus_type == "PV"
        pfPV(P=row.P, V=row.V)  ## Generator bus: fixed P and V
    elseif row.bus_type == "Slack"
        pfSlack(V=row.V, ฮด=0)   ## Slack bus: fixed V and angle
    end

    bus = compile_bus(MTKBus(injectors...);
        vidx=i, name=Symbol("bus$i"), pf=pf_model, Vbase=row.base_kv)
    push!(busses, bus)
end

Transmission Line Creation

The IEEE 39-bus system includes both transmission lines and transformers, all modeled using the ฯ€-line equivalent circuit model.

The model consists of several layers:

  1. The PiModel, which satisfies the Branch Interface as it has two terminals
  2. The MTKLine constructor, which creates a MTK model fulfilling the MTKLine Interface
  3. The compiled EdgeModel created by calling the compile_line constructor
       โ•”โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•—
       โ•‘ EdgeModel (compiled)             โ•‘
   src โ•‘ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ•‘ dst
vertex โ•‘ โ”‚MTKLine                       โ”‚ โ•‘ vertex
   u โ”€โ”€โ”€โ†’โ”‚โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚โ†โ”€โ”€โ”€ u
       โ•‘ โ”‚โ”‚LineEndโ”œoโ”ค PiLine โ”œoโ”คLineEndโ”‚โ”‚ โ•‘
   i โ†โ”€โ”€โ”€โ”‚โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚โ”€โ”€โ”€โ†’ i
       โ•‘ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ•‘
       โ•šโ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•โ•

(We used the PiLine_fault model since we plan on simulating short circuits later.)

A line has two voltage bases, srcโ‚ŠVbase and dstโ‚ŠVbase, one per LineEnd โ€” a transformer between the 16.5 kV generator buses and the 345 kV grid has genuinely different bases on its two ends. We do not set them here: each LineEnd declares that it inherits its Vbase from the bus it is attached to, and that inheritance is resolved during initialization, once the line knows its neighbours. Part II shows the result.

Each transmission element is created by:

  1. Compiling a line model with its source and destination buses
  2. Setting electrical parameters (resistance, reactance, susceptance) from CSV data
branches = []
for row in eachrow(branch_df)
    # Create line instance with topology
    line = compile_line(MTKLine(PiLine_fault(;name=:piline)); src=row.src_bus, dst=row.dst_bus)

    # Apply electrical parameters from CSV data
    for col_name in names(branch_df)
        if col_name โˆ‰ ["src_bus", "dst_bus", "transformer"]
            set_default!(line, Regex(col_name*"\$"), row[col_name])
        end
    end

    push!(branches, line)
end

Network Assembly

Finally, we combine all buses and transmission lines into a complete network model. This creates the IEEE 39-bus test system ready for initialization and simulation.

nw = Network(busses, branches)
Network with 192 states and 1662 parameters
 โ”œโ”€ 39 vertices (5 unique types)
 โ””โ”€ 46 edges (1 unique type)
Edge-Aggregation using SequentialAggregator(+)

All models are built, so we restore the global bases to their defaults. Calling the setters without an argument does that, and it keeps this page's 60 Hz from leaking into whatever is constructed next in the same session.

set_Sbase!()
set_fbase!()
314.1592653589793

The network nw now contains the complete IEEE 39-bus model structure. In Part 2 of this tutorial series, we'll initialize this network by solving the power flow and setting up the dynamic initial conditions.


This page was generated using Literate.jl.