Grid Configuration (YAML)

The config.yaml file is the core of 4PACE. It defines the network topology, component specifications, economic planning data, and complex dynamic controllers.

This guide serves as an exhaustive reference for all supported structures and parameters.

Global Settings

These parameters define the base values for the entire per-unit (p.u.) system.

Parameter	Type	Description
Sbase	Float	[Required] System base apparent power in MVA (e.g., 100.0).

Buses & Components

The buses list contains all nodes in the network. Each bus can host multiple components.

Bus Attributes

• name (String): [Required] Unique identifier for the bus.

• Vbase (Float): [Required] Base voltage of the bus in kV.

• bus_type (String): Reference for Load Flow (e.g., ‘Slack’, ‘PV’, ‘PQ’).

• components (List): A list of electrical devices attached to this bus.

Component Types

Inside the components list, you must specify the type of the device. Below are the supported components and their parameters:

SynchronousMachine (Generators)

Represents generators, motors, or condensers with full dynamic and fault capabilities.

• Basic & OPF: name, P, Q, Pmin, Pmax, Qmin, Qmax, S_rated, pf, mode (‘generator’, ‘motor’, ‘condenser’), a, b, c (cost curve parameters).

• Fault & Impedance: R, X, Xd, Xd_prime, Xd_sub (Crucial for Faults), X2, X0.

• Dynamics: H (Inertia), Td0_prime.

• Controllers: Nested blocks for avr, gov, and pss (See Controllers section below).

• Planning (CEP): is_candidate, capex_per_mw, max_build_mw, lifetime_years, interest_rate.

AsynchronousMachine (Induction Motor)

• Basic: name, P_rated, V_rated, poles, freq.

• Circuit: Rs, Xs, Rr, Xr, Xm.

• State: s (slip), load_type (e.g., ‘constant_torque’).

Inverter (Solar PV / Wind)

• Basic: name, S_max, P, Q, control_mode, source_type (‘solar’, ‘wind’, ‘bess’).

• Fault Logic: I_fault_limit_pu (Max reactive current injection limit during faults, e.g., 1.2).

• Planning (CEP): is_candidate, capex_per_mw, max_build_mw, lifetime_years.

Battery (BESS)

• Basic: name, P_max, E_max, init_soc, eta (efficiency).

• Fault Logic: I_fault_limit_pu (e.g., 1.5).

• Planning (CEP): is_candidate, capex_per_mw, capex_per_mwh, max_build_mw, max_build_mwh.

Load

• Basic: name, model (‘P’, ‘I’, ‘Z’), P (MW), Q (MVAr), R, X.

Shunt (Capacitors / Reactors)

• Basic: name, Q_nom (MVAr), V_nom (kV).

Controllers (Nested in SynchronousMachine)

SEXS (AVR)

Simplified Excitation System (IEEE Type 1 Equivalent). * type: “SEXS” * Ka (Gain), Ta (Time constant), Efd_min, Efd_max (Limits).

TGOV1 (Governor)

IEEE Standard Steam Turbine-Governor Model. * type: “TGOV1” * R (Speed droop), T1, T2, T3 (Time constants), Vmax, Vmin (Valve limits), Dt (Damping).

PSS1A (Power System Stabilizer)

IEEE Standard Power System Stabilizer. * type: “PSS1A” * K_pss (Gain), T_w (Washout), T1, T2, T3, T4 (Lead-lag time constants), V_max, V_min.

FACTS Devices

CSVGN1 (SVC - Shunt FACTS)

Standard Static Var Compensator. Resides inside the bus components list. * type: “CSVGN1” * name, V_ref (Target Voltage), K_svc (Gain), T_1 (Delay), B_max, B_min (Susceptance limits).

STATCOM1 (Shunt FACTS)

Voltage Source Converter based Shunt. Resides inside the bus components list. * type: “STATCOM1” * name, V_ref, K_r (Gain), T_r (Delay), Iq_max, Iq_min (Reactive current limits).

TCSC1 (Series FACTS)

Thyristor Controlled Series Capacitor. Resides in the global series_facts list (outside buses). * type: “TCSC1” * name, branch_name (Target line to clamp onto), P_ref (Target active power flow in p.u.). * K_p (Gain), T_p (Delay), X_max, X_min (Reactance injection limits).

Branches

The branches list defines the connections between buses.

TransmissionLine

• Basic: from_bus, to_bus, R, X, B_shunt, S_max, length_km.

• Fault Logic: R0, X0, B0_shunt (Zero Sequence Parameters).

• Planning (CEP): is_candidate, capex_per_mva, max_build_mva, lifetime_years.

Transformer

• Basic: from_bus, to_bus, R, X, S_max.

• Tap Changer: tap_ratio, phase_shift, auto_tap, target_V, tap_step, tap_min, tap_max.

• Fault Logic: R0, X0, connection_type (‘yg-yg’, ‘delta-yg’, ‘yg-delta’, ‘delta-delta’).

• Planning (CEP): is_candidate, capex_per_mva, max_build_mva.

Example: Modified IEEE 14 Bus System

Here is how multiple components, complex controllers, and FACTS devices come together:

Sbase: 100.0
buses:
  - name: "1"
    Vbase: 132.0
    bus_type: Slack
    components:
      - type: SynchronousMachine
        name: G1
        a: 0.0
        b: 20.0
        c: 0.043
        Pmax: 332.4
        Pmin: 0.0
        Qmax: 150.0
        Qmin: -20.0
        Xd_sub: 0.15
        X2: 0.15
        X0: 0.05
        # --- Control Systems ---
        avr:
          type: SEXS
          Ka: 200.0
          Ta: 0.02
        gov:
          type: TGOV1
          R: 0.05
          T1: 0.5
        pss:
          type: PSS1A
          K_pss: 10.0

  - name: "2"
    Vbase: 132.0
    bus_type: PV
    components:
      - type: SynchronousMachine
        name: G2
        P: 40.0
        a: 0.0
        b: 20.0
        c: 0.25
        Pmax: 140.0
        Pmin: 0.0
        Qmax: 100.0
        Qmin: -50.0
        Xd: 2.0
        Xd_sub: 0.15
        Td0_prime: 0.5
        X2: 0.20
        X0: 0.07
        # --- Control Systems ---
        avr:
          type: SEXS
          Ka: 200.0
          Ta: 0.02
        gov:
          type: TGOV1
          R: 0.05
          T1: 0.5
        pss:
          type: PSS1A
          K_pss: 10.0

      - type: Load
        name: L2
        P: 21.7
        Q: 12.7

  - name: "3"
    Vbase: 132.0
    bus_type: PV
    components:
      - type: SynchronousMachine
        name: G3
        P: 0.0
        a: 0.0
        b: 40.0
        c: 0.01
        Pmax: 100.0
        Pmin: 0.0
        Qmax: 80.0
        Qmin: -20.0
        Xd_sub: 0.25
        X2: 0.25
        X0: 0.09
        # --- Control Systems ---
        avr:
          type: SEXS
          Ka: 200.0
          Ta: 0.02
        gov:
          type: TGOV1
          R: 0.05
          T1: 0.5
        pss:
          type: PSS1A
          K_pss: 10.0

      - type: Load
        name: L3
        P: 94.2
        Q: 19.0

  - name: "4"
    Vbase: 132.0
    bus_type: PQ
    components:
      - type: Load
        name: L4
        P: 47.8
        Q: -3.9
      - type: CSVGN1
        name: SVC_Bus4
        V_ref: 1.02
        K_svc: 50.0
        T_1: 0.05
        B_max: 2.0
        B_min: -1.0

  - name: "5"
    Vbase: 132.0
    bus_type: PQ
    components:
      - type: Load
        name: L5
        P: 7.6
        Q: 1.6

  - name: "6"
    Vbase: 33.0
    bus_type: PV
    components:
      - type: SynchronousMachine
        name: G6
        P: 0.0
        a: 0.0
        b: 20.0
        c: 0.01
        Pmax: 100.0
        Pmin: 0.0
        Qmax: 60.0
        Qmin: -20.0
        Xd_sub: 0.25
        X2: 0.25
        X0: 0.10
        # --- Control Systems ---
        avr:
          type: SEXS
          Ka: 200.0
          Ta: 0.02
        gov:
          type: TGOV1
          R: 0.05
          T1: 0.5
        pss:
          type: PSS1A
          K_pss: 10.0

      - type: Load
        name: L6
        P: 11.2
        Q: 7.5

  - name: "7"
    Vbase: 33.0
    bus_type: PQ
    components: []

  - name: "8"
    Vbase: 33.0
    bus_type: PV
    components:
      - type: SynchronousMachine
        name: G8
        P: 0.0
        a: 0.0
        b: 20.0
        c: 0.01
        Pmax: 100.0
        Pmin: 0.0
        Qmax: 60.0
        Qmin: -20.0
        Xd_sub: 0.25
        X2: 0.25
        X0: 0.10
        # --- Control Systems ---
        avr:
          type: SEXS
          Ka: 200.0
          Ta: 0.02
        gov:
          type: TGOV1
          R: 0.05
          T1: 0.5
        pss:
          type: PSS1A
          K_pss: 10.0

  - name: "9"
    Vbase: 33.0
    bus_type: PQ
    components:
      - type: Load
        name: L9
        P: 29.5
        Q: 16.6
      - type: STATCOM1
        name: STAT_Bus9
        V_ref: 1.0
        K_r: 40.0
        T_r: 0.02
        Iq_max: 1.5
        Iq_min: -1.5

  - name: "10"
    Vbase: 33.0
    bus_type: PQ
    components:
      - type: Load
        name: L10
        P: 9.0
        Q: 5.8

  - name: "11"
    Vbase: 33.0
    bus_type: PQ
    components:
      - type: Load
        name: L11
        P: 3.5
        Q: 1.8

  - name: "12"
    Vbase: 33.0
    bus_type: PQ
    components:
      - type: Load
        name: L12
        P: 6.1
        Q: 1.6

  - name: "13"
    Vbase: 33.0
    bus_type: PQ
    components:
      - type: Load
        name: L13
        P: 13.5
        Q: 5.8

  - name: "14"
    Vbase: 33.0
    bus_type: PQ
    components:
      - type: Load
        name: L14
        P: 14.9
        Q: 5.0
      - type: Shunt
        name: Cap14
        Q_nom: 25.0
      - type: Battery
        name: BESS_14
        is_candidate: true
        capex_per_mw: 10000.0
        capex_per_mwh: 15000.0
        max_build_mw: 50.0
        max_build_mwh: 200.0
        lifetime_years: 10
        interest_rate: 0.05
        eta: 0.95
        init_soc: 0.5
        P_max: 45.82
        E_max: 200.00
        I_fault_limit_pu: 1.5
      - type: Inverter
        name: PV_14
        is_candidate: true
        source_type: solar
        capex_per_mw: 50000.0
        max_build_mw: 80.0
        lifetime_years: 20
        interest_rate: 0.05
        S_max: 80
        I_fault_limit_pu: 1.2

branches:
  # Transmission Lines
  - {type: TransmissionLine, name: "L1-2", from_bus: "1", to_bus: "2", R: 0.01938, X: 0.05917, S_max: 250, R0: 0.05814, X0: 0.17751}
  - {type: TransmissionLine, name: "L1-5", from_bus: "1", to_bus: "5", R: 0.05403, X: 0.22304, S_max: 250, R0: 0.16209, X0: 0.66912}
  - {type: TransmissionLine, name: "L2-3", from_bus: "2", to_bus: "3", R: 0.04699, X: 0.19797, S_max: 150, R0: 0.14097, X0: 0.59391}
  - {type: TransmissionLine, name: "L2-4", from_bus: "2", to_bus: "4", R: 0.05811, X: 0.17632, S_max: 100, R0: 0.17433, X0: 0.52896}
  - {type: TransmissionLine, name: "L2-5", from_bus: "2", to_bus: "5", R: 0.05695, X: 0.17388, S_max: 100, R0: 0.17085, X0: 0.52164}
  - {type: TransmissionLine, name: "L3-4", from_bus: "3", to_bus: "4", R: 0.06701, X: 0.17103, S_max: 150, R0: 0.20103, X0: 0.51309}
  - {type: TransmissionLine, name: "L4-5", from_bus: "4", to_bus: "5", R: 0.01335, X: 0.04211, S_max: 180, R0: 0.04005, X0: 0.12633}
  - {type: TransmissionLine, name: "L6-11", from_bus: "6", to_bus: "11", R: 0.09498, X: 0.19890, S_max: 120, R0: 0.28494, X0: 0.59670}
  - {type: TransmissionLine, name: "L6-12", from_bus: "6", to_bus: "12", R: 0.12291, X: 0.25581, S_max: 100, R0: 0.36873, X0: 0.76743}
  - {type: TransmissionLine, name: "L6-13", from_bus: "6", to_bus: "13", R: 0.06615, X: 0.13027, S_max: 150, R0: 0.19845, X0: 0.39081}
  - {type: TransmissionLine, name: "L7-8", from_bus: "7", to_bus: "8", R: 0.0, X: 0.17615, S_max: 100, R0: 0.0, X0: 0.52845}
  - {type: TransmissionLine, name: "L7-9", from_bus: "7", to_bus: "9", R: 0.0, X: 0.11001, S_max: 100, R0: 0.0, X0: 0.33003}
  - {type: TransmissionLine, name: "L9-10", from_bus: "9", to_bus: "10", R: 0.03181, X: 0.08450, S_max: 100, R0: 0.09543, X0: 0.25350}
  - {type: TransmissionLine, name: "L9-14", from_bus: "9", to_bus: "14", R: 0.12711, X: 0.27038, S_max: 100, R0: 0.38133, X0: 0.81114}
  - {type: TransmissionLine, name: "L10-11", from_bus: "10", to_bus: "11", R: 0.08205, X: 0.19207, S_max: 100, R0: 0.24615, X0: 0.57621}
  - {type: TransmissionLine, name: "L12-13", from_bus: "12", to_bus: "13", R: 0.22092, X: 0.19988, S_max: 100, R0: 0.66276, X0: 0.59964}
  - {type: TransmissionLine, name: "L13-14", from_bus: "13", to_bus: "14", R: 0.17093, X: 0.34802, S_max: 100, R0: 0.51279, X0: 1.04406}

  # Transformers
  - {type: Transformer, name: "T4-7", from_bus: "4", to_bus: "7", R: 0.0, X: 0.20912, tap_ratio: 0.978, R0: 0.0, X0: 0.20912, connection_type: "yg-yg"}
  - {type: Transformer, name: "T4-9", from_bus: "4", to_bus: "9", R: 0.0, X: 0.55618, tap_ratio: 0.969, R0: 0.0, X0: 0.55618, connection_type: "yg-yg"}
  - {type: Transformer, name: "T5-6", from_bus: "5", to_bus: "6", R: 0.0, X: 0.25202, tap_ratio: 0.932, R0: 0.0, X0: 0.25202, connection_type: "yg-yg"}

series_facts:
  # Adding a TCSC to clamp onto Transmission Line L4-5
  - type: TCSC1
    name: TCSC_L4_5
    branch_name: L4-5
    P_ref: 0.5   # Target flow in pu (50 MW)
    K_p: 2.0
    T_p: 0.05
    X_max: 0.05  # Slight inductive capability
    X_min: -0.3