IEEE39 Bus Tutorial - Part I: Model Creation

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.

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

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

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 ModelingToolkit
using NetworkDynamics
using DataFrames
using CSV

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

The system data is stored in CSV files containing:

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:

BASE_MVA = 100.0
BASE_FREQ = 60.0

Subcomponent Definition

As stated above, our buses fall into 5 different categories. We will define a "template" for each of those categories and then create the individual buses from those templates. By doing so, we can reach substantial performance improvements, as we do not have to repeatedly compile the same models (the symbolic simplification is quite costly). Instead, we copy the templates and adjust parameters.

However, before we can define the bus templates, we need to define the individual subcomponents. Those subcomponents are MTK models and not yet compiled node models. See Modeling Concepts and the custom bus tutorial.

Load Model

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

(t) ┌──────────┐
 o──┤ ZIP Load │
    └──────────┘

load = ZIPLoad(;name=:ZIPLoad)

Generator Models

For generators, we use the Sauer-Pai machine model, which is a 6th-order synchronous machine model. We create two variants:

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

(t) ┌─────────┐
 o──┤ Machine │
    └─────────┘

uncontrolled_machine = SauerPaiMachine(;
    τ_m_input=false,  ## No external mechanical torque input
    vf_input=false,   ## No external field voltage input
    name=:machine,
)

Controlled Machine: Includes automatic voltage regulator (AVR) and turbine governor controls.

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        │
      └───────────────────────────────┘

_machine = SauerPaiMachine(;
    name=:machine,
)
_avr = AVRTypeI(;
    name=:avr,
    ceiling_function=:quadratic,
)
_gov = TGOV1(; name=:gov,)

controlled_machine = CompositeInjector(
    [_machine, _avr, _gov],
    name=:ctrld_gen
)

Bus Template Creation

Now we have all the components (i.e., the MTK models) so we can combine them into full bus models and compile the methods.

Junction Bus

Pure transmission buses with no generation or load

           ╔══════════════════════╗
           ║ Junction (compiled)  ║
 Network   ║  ┌─────────────────┐ ║
interface  ║  │MTKBus           │ ║
 current ────→│┌──────┐         │ ║
           ║  ││BusBar│(nothing)│ ║
 voltage ←────│└──────┘         │ ║
           ║  └─────────────────┘ ║
           ╚══════════════════════╝

@named junction_bus_template = Bus(MTKBus())
strip_defaults!(junction_bus_template)  ## Clear default parameters for manual setting

VertexModel :junction_bus_template PureStateMap()
 ├─ 2 inputs:  [busbar₊i_r, busbar₊i_i]
 ├─ 2 states:  [busbar₊u_i, busbar₊u_r]
 |    with diagonal mass matrix [0, 0]
 └─ 2 outputs: [busbar₊u_r, busbar₊u_i]

Load Bus

Buses with only load components

           ╔═════════════════════╗
           ║ Load (compiled)     ║
 Network   ║  ┌────────────────┐ ║
interface  ║  │MTKBus          │ ║
 current ────→│┌──────┐ ┌────┐ │ ║
           ║  ││BusBar├o┤Load│ │ ║
 voltage ←────│└──────┘ └────┘ │ ║
           ║  └────────────────┘ ║
           ╚═════════════════════╝

@named load_bus_template = Bus(MTKBus(load))
strip_defaults!(load_bus_template)

VertexModel :load_bus_template PureStateMap()
 ├─ 2 inputs:  [busbar₊i_r, busbar₊i_i]
 ├─ 2 states:  [busbar₊u_r, busbar₊u_i]
 |    with diagonal mass matrix [0, 0]
 ├─ 2 outputs: [busbar₊u_r, busbar₊u_i]
 └─ 9 params:  [ZIPLoad₊Pset, ZIPLoad₊Qset, ZIPLoad₊Vset≈1, ZIPLoad₊KpZ, ZIPLoad₊KqZ, ZIPLoad₊KpI, ZIPLoad₊KqI, ZIPLoad₊KpC, ZIPLoad₊KqC]

Generator Bus (Controlled)

Buses with controlled generators (machine + AVR + governor)

            ╔════════════════════════════════════════════════╗
            ║ Ctrld Machine Bus (compiled)                   ║
            ║  ┌───────────────────────────────────────────┐ ║
            ║  │MTKBus                                     │ ║
            ║  │         ┌───────────────────────────────┐ │ ║
  Network   ║  │         │CtrldMachine  ╭─────→────╮     │ │ ║
 interface  ║  │         │    ┌─────────┴─┐      ┌─┴───┐ │ │ ║
  current ────→│┌──────┐ │    │           ├───←──┤ AVR │ │ │ ║
            ║  ││BusBar├o┼────┤ Sauer-Pai │      └─────┘ │ │ ║
  voltage ←────│└──────┘ │    │ Machine   │      ┌─────┐ │ │ ║
            ║  │         │    │           ├───←──┤ Gov │ │ │ ║
            ║  │         │    └─────────┬─┘      └─┬───┘ │ │ ║
            ║  │         │              ╰─────→────╯     │ │ ║
            ║  │         └───────────────────────────────┘ │ ║
            ║  └───────────────────────────────────────────┘ ║
            ╚════════════════════════════════════════════════╝

@named ctrld_machine_bus_template = Bus(
    MTKBus(controlled_machine);
)
strip_defaults!(ctrld_machine_bus_template)
# Set system-wide base values for all generators
set_default!(ctrld_machine_bus_template, r"S_b$", BASE_MVA)
set_default!(ctrld_machine_bus_template, r"ω_b$", 2π*BASE_FREQ)

VertexModel :ctrld_machine_bus_template PureStateMap()
 ├─  2 inputs:  [busbar₊i_r, busbar₊i_i]
 ├─ 15 states:  [ctrld_gen₊gov₊τ_m₊u≈0, ctrld_gen₊gov₊xg1≈1, ctrld_gen₊gov₊xg2≈0, ctrld_gen₊avr₊vfout≈1, ctrld_gen₊avr₊v_fb≈0, ctrld_gen₊avr₊vr≈0, ctrld_gen₊avr₊vm≈1, ctrld_gen₊machine₊ψ″_q≈0, ctrld_gen₊machine₊ψ″_d≈1, ctrld_gen₊machine₊E′_d≈1, ctrld_gen₊machine₊E′_q≈0, ctrld_gen₊machine₊ω≈1, ctrld_gen₊machine₊δ≈0, busbar₊u_r, busbar₊u_i]
 |     with diagonal mass matrix [0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0]
 ├─  2 outputs: [busbar₊u_r, busbar₊u_i]
 └─ 42 params:  [ctrld_gen₊machine₊R_s, ctrld_gen₊machine₊X_d, ctrld_gen₊machine₊X_q, ctrld_gen₊machine₊X′_d, ctrld_gen₊machine₊X′_q, ctrld_gen₊machine₊X″_d, ctrld_gen₊machine₊X″_q, ctrld_gen₊machine₊X_ls, ctrld_gen₊machine₊T′_d0, ctrld_gen₊machine₊T″_d0, ctrld_gen₊machine₊T′_q0, ctrld_gen₊machine₊T″_q0, ctrld_gen₊machine₊H, ctrld_gen₊machine₊D, ctrld_gen₊machine₊S_b=100, ctrld_gen₊machine₊V_b, ctrld_gen₊machine₊ω_b=376.99, ctrld_gen₊machine₊Sn, ctrld_gen₊machine₊Vn, ctrld_gen₊avr₊Tr, ctrld_gen₊avr₊vref≈1, ctrld_gen₊avr₊Ka, ctrld_gen₊avr₊Ke, ctrld_gen₊avr₊Kf, ctrld_gen₊avr₊Ta, ctrld_gen₊avr₊Tf, ctrld_gen₊avr₊Te, ctrld_gen₊avr₊vr_min, ctrld_gen₊avr₊vr_max, ctrld_gen₊avr₊E1, ctrld_gen₊avr₊E2, ctrld_gen₊avr₊Se1, ctrld_gen₊avr₊Se2, ctrld_gen₊gov₊ω_ref, ctrld_gen₊gov₊p_ref≈1, ctrld_gen₊gov₊V_min, ctrld_gen₊gov₊V_max, ctrld_gen₊gov₊R, ctrld_gen₊gov₊T1, ctrld_gen₊gov₊T2, ctrld_gen₊gov₊T3, ctrld_gen₊gov₊DT]

Generator + Load Bus (Controlled)

Buses with both controlled generators and loads

            ╔═════════════════════════════════════════════════╗
            ║ Ctrld Machine Load Bus (compiled)               ║
            ║  ┌────────────────────────────────────────────┐ ║
            ║  │MTKBus    ┌───────────────────────────────┐ │ ║
            ║  │          │CtrldMachine  ╭─────→────╮     │ │ ║
            ║  │          │    ┌─────────┴─┐      ┌─┴───┐ │ │ ║
            ║  │          │    │           ├───←──┤ AVR │ │ │ ║
  Network   ║  │        ┌─┼────┤ Sauer-Pai │      └─────┘ │ │ ║
 interface  ║  │        │ │    │ Machine   │      ┌─────┐ │ │ ║
  current ────→│┌──────┐│ │    │           ├───←──┤ Gov │ │ │ ║
            ║  ││BusBar├o │    └─────────┬─┘      └─┬───┘ │ │ ║
  voltage ←────│└──────┘│ │              ╰─────→────╯     │ │ ║
            ║  │        │ └───────────────────────────────┘ │ ║
            ║  │        │ ┌──────┐                          │ ║
            ║  │        └─┤ Load │                          │ ║
            ║  │          └──────┘                          │ ║
            ║  └────────────────────────────────────────────┘ ║
            ╚═════════════════════════════════════════════════╝

@named ctrld_machine_load_bus_template = Bus(
    MTKBus(controlled_machine, load);
)
strip_defaults!(ctrld_machine_load_bus_template)
set_default!(ctrld_machine_load_bus_template, r"S_b$", BASE_MVA)
set_default!(ctrld_machine_load_bus_template, r"ω_b$", 2π*BASE_FREQ)

VertexModel :ctrld_machine_load_bus_template NoFeedForward()
 ├─  2 inputs:  [busbar₊i_r, busbar₊i_i]
 ├─ 15 states:  [ctrld_gen₊gov₊τ_m₊u≈0, ctrld_gen₊machine₊terminal₊i_r≈0, ctrld_gen₊machine₊terminal₊i_i≈0, ctrld_gen₊gov₊xg1≈1, ctrld_gen₊gov₊xg2≈0, ctrld_gen₊avr₊vfout≈1, ctrld_gen₊avr₊v_fb≈0, ctrld_gen₊avr₊vr≈0, ctrld_gen₊avr₊vm≈1, ctrld_gen₊machine₊ψ″_q≈0, ctrld_gen₊machine₊ψ″_d≈1, ctrld_gen₊machine₊E′_d≈1, ctrld_gen₊machine₊E′_q≈0, ctrld_gen₊machine₊ω≈1, ctrld_gen₊machine₊δ≈0]
 |     with diagonal mass matrix [0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]
 ├─  2 outputs: [busbar₊u_r, busbar₊u_i]
 └─ 51 params:  [ctrld_gen₊machine₊R_s, ctrld_gen₊machine₊X_d, ctrld_gen₊machine₊X_q, ctrld_gen₊machine₊X′_d, ctrld_gen₊machine₊X′_q, ctrld_gen₊machine₊X″_d, ctrld_gen₊machine₊X″_q, ctrld_gen₊machine₊X_ls, ctrld_gen₊machine₊T′_d0, ctrld_gen₊machine₊T″_d0, ctrld_gen₊machine₊T′_q0, ctrld_gen₊machine₊T″_q0, ctrld_gen₊machine₊H, ctrld_gen₊machine₊D, ctrld_gen₊machine₊S_b=100, ctrld_gen₊machine₊V_b, ctrld_gen₊machine₊ω_b=376.99, ctrld_gen₊machine₊Sn, ctrld_gen₊machine₊Vn, ctrld_gen₊avr₊Tr, ctrld_gen₊avr₊vref≈1, ctrld_gen₊avr₊Ka, ctrld_gen₊avr₊Ke, ctrld_gen₊avr₊Kf, ctrld_gen₊avr₊Ta, ctrld_gen₊avr₊Tf, ctrld_gen₊avr₊Te, ctrld_gen₊avr₊vr_min, ctrld_gen₊avr₊vr_max, ctrld_gen₊avr₊E1, ctrld_gen₊avr₊E2, ctrld_gen₊avr₊Se1, ctrld_gen₊avr₊Se2, ctrld_gen₊gov₊ω_ref, ctrld_gen₊gov₊p_ref≈1, ctrld_gen₊gov₊V_min, ctrld_gen₊gov₊V_max, ctrld_gen₊gov₊R, ctrld_gen₊gov₊T1, ctrld_gen₊gov₊T2, ctrld_gen₊gov₊T3, ctrld_gen₊gov₊DT, ZIPLoad₊Pset, ZIPLoad₊Qset, ZIPLoad₊Vset≈1, ZIPLoad₊KpZ, ZIPLoad₊KqZ, ZIPLoad₊KpI, ZIPLoad₊KqI, ZIPLoad₊KpC, ZIPLoad₊KqC]

Generator + Load Bus (Uncontrolled)

Buses with uncontrolled generators and loads

            ╔════════════════════════════════╗
            ║ Unctr. Ma. Load Bus (compiled) ║
            ║  ┌────────────────────────┐    ║
  Network   ║  │MTKBus      ┌─────────┐ │    ║
 interface  ║  │          ┌─┤ Machine │ │    ║
  current ────→│ ┌──────┐ │ └─────────┘ │    ║
            ║  │ │BusBar├─o             │    ║
  voltage ←────│ └──────┘ │ ┌──────┐    │    ║
            ║  │          └─┤ Load │    │    ║
            ║  │            └──────┘    │    ║
            ║  └────────────────────────┘    ║
            ╚════════════════════════════════╝

@named unctrld_machine_load_bus_template = Bus(
    MTKBus(uncontrolled_machine, load);
)
strip_defaults!(unctrld_machine_load_bus_template)
set_default!(unctrld_machine_load_bus_template, r"S_b$", BASE_MVA)
set_default!(unctrld_machine_load_bus_template, r"ω_b$", 2π*BASE_FREQ)

VertexModel :unctrld_machine_load_bus_template NoFeedForward()
 ├─  2 inputs:  [busbar₊i_r, busbar₊i_i]
 ├─  8 states:  [machine₊terminal₊i_i≈0, machine₊terminal₊i_r≈0, machine₊ψ″_q≈0, machine₊ψ″_d≈1, machine₊E′_d≈1, machine₊E′_q≈0, machine₊ω≈1, machine₊δ≈0]
 |     with diagonal mass matrix [0, 0, 1, 1, 1, 1, 1, 1]
 ├─  2 outputs: [busbar₊u_r, busbar₊u_i]
 └─ 30 params:  [machine₊vf_set≈1, machine₊τ_m_set≈1, machine₊R_s, machine₊X_d, machine₊X_q, machine₊X′_d, machine₊X′_q, machine₊X″_d, machine₊X″_q, machine₊X_ls, machine₊T′_d0, machine₊T″_d0, machine₊T′_q0, machine₊T″_q0, machine₊H, machine₊D, machine₊S_b=100, machine₊V_b, machine₊ω_b=376.99, machine₊Sn, machine₊Vn, ZIPLoad₊Pset, ZIPLoad₊Qset, ZIPLoad₊Vset≈1, ZIPLoad₊KpZ, ZIPLoad₊KqZ, ZIPLoad₊KpI, ZIPLoad₊KqI, ZIPLoad₊KpC, ZIPLoad₊KqC]

Bus Instantiation and Parameter Setting

Now we create the actual bus instances by copying templates and applying specific parameters from the CSV data files.

# Helper function to apply CSV parameters to bus components
function apply_csv_params!(bus, table, bus_index)
    row_idx = findfirst(table.bus .== bus_index)

    # Apply all parameters except "bus" column
    row = table[row_idx, :]
    for col_name in names(table)
        if col_name != "bus"
            set_default!(bus, Regex(col_name*"\$"), row[col_name])
        end
    end
end

For each bus in the system, we:

1. Select the appropriate template based on its category
2. Create a bus instance with the correct vertex index and name
3. Apply component-specific parameters from CSV files
4. Set the power flow model (PQ, PV, or Slack)

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

    # Select template based on bus category
    bus = if row.category == "junction"
        Bus(junction_bus_template; vidx=i, name=Symbol("bus$i"))
    elseif row.category == "load"
        Bus(load_bus_template; vidx=i, name=Symbol("bus$i"))
    elseif row.category == "ctrld_machine"
        Bus(ctrld_machine_bus_template; vidx=i, name=Symbol("bus$i"))
    elseif row.category == "ctrld_machine_load"
        Bus(ctrld_machine_load_bus_template; vidx=i, name=Symbol("bus$i"))
    elseif row.category == "unctrld_machine_load"
        Bus(unctrld_machine_load_bus_template; vidx=i, name=Symbol("bus$i"))
    end

    # Apply component parameters from CSV files
    row.has_load && apply_csv_params!(bus, load_df, i)
    row.has_gen && apply_csv_params!(bus, machine_df, i)
    row.has_avr && apply_csv_params!(bus, avr_df, i)
    row.has_gov && apply_csv_params!(bus, gov_df, i)

    # Set power flow model based on bus type
    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
    set_pfmodel!(bus, pf_model)

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

@named piline_template = Line(MTKLine(PiLine_fault(;name=:piline)))

EdgeModel :piline_template PureFeedForward()
 ├─ 2/2 inputs:  src=[src₊u_r, src₊u_i] dst=[dst₊u_r, dst₊u_i]
 ├─   0 states:  []  
 ├─ 2/2 outputs: src=[src₊i_r, src₊i_i] dst=[dst₊i_r, dst₊i_i]
 └─  16 params:  [piline₊R, piline₊X, piline₊G_src, piline₊B_src, piline₊G_dst, piline₊B_dst, piline₊r_src=1, piline₊r_dst=1, piline₊R_fault=0, piline₊X_fault=0, piline₊G_fault=0, piline₊B_fault=0, piline₊pos=0.5, piline₊active=1, piline₊shortcircuit=0, piline₊faultimp=0]

Each transmission element is created by:

1. Instantiating a line from the template with 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 = Line(piline_template; 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 201 states and 1306 parameters
 ├─ 39 vertices (5 unique types)
 └─ 46 edges (1 unique type)
Edge-Aggregation using SequentialAggregator(+)

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.