Merge pull request #36 from nickrobinson251/npr/impedance-corrections

Add parsing of transformer impedance corrections

docs/src/api.md

@@ -58,3 +58,8 @@ VSCDCLines
 ```@docs
 SwitchedShunts
 ```
+
+## Transformer Impedance Corrections
+```@docs
+ImpedanceCorrections
+```

src/PowerFlowData.jl

@@ -10,7 +10,7 @@ using Tables
 export parse_network
 export Network
 export CaseID, Buses, Loads, Generators, Branches, Transformers, AreaInterchanges
-export TwoTerminalDCLines, VSCDCLines, SwitchedShunts
+export TwoTerminalDCLines, VSCDCLines, SwitchedShunts, ImpedanceCorrections
 
 include("debug.jl")
 include("types.jl")

src/parsing.jl

@@ -57,9 +57,12 @@ function parse_network(source)
     vsc_dc, pos = parse_records!(VSCDCLines(), bytes, pos, len, OPTIONS)
     @debug 1 "Parsed VSCDCLines: nrows = $(length(vsc_dc)), pos = $pos"
 
-    switched_shunts, pos = parse_records!(SwitchedShunts(), bytes, pos, len, OPTIONS)
+    switched_shunts, pos = parse_records!(SwitchedShunts(nbuses÷11), bytes, pos, len, OPTIONS)
     @debug 1 "Parsed SwitchedShunts: nrows = $(length(switched_shunts)), pos = $pos"
 
+    impedance_corrections, pos = parse_records!(ImpedanceCorrections(), bytes, pos, len, OPTIONS)
+    @debug 1 "Parsed ImpedanceCorrections: nrows = $(length(impedance_corrections)), pos = $pos"
+
     return Network(
         caseid,
         buses,
@@ -71,6 +74,7 @@ function parse_network(source)
         two_terminal_dc,
         vsc_dc,
         switched_shunts,
+        impedance_corrections,
     )
 end
 
@@ -213,19 +217,28 @@ end
 ### SwitchedShunts
 ###
 
-# SwitchedShunts can have anywhere between 1 - 8 `N` and `B` values in the data itself,
-# if n2, b2, ..., n8, b8 are not present, we set them to zero.
-@generated function parse_row!(rec::R, bytes, pos, len, options) where {R <: SwitchedShunts}
+const N_SPECIAL = IdDict(
+    # SwitchedShunts can have anywhere between 1 - 8 `N` and `B` values in the data itself,
+    # if n2, b2, ..., n8, b8 are not present, we set them to zero.
+    # i.e. the last 14 = 7(n) + 7(b) columns reqire special handling.
+    SwitchedShunts => 14,
+    # SwitchedShunts can have anywhere between 2 - 11 `T` and `F` values in the data itself,
+    # if t3, f3, ..., t11, f11 are not present, we set them to zero.
+    # i.e. the last 18 = 9(t) + 9(f) columns reqire special handling.
+    ImpedanceCorrections => 18,
+)
+
+@generated function parse_row!(rec::R, bytes, pos, len, options) where {R <: Union{SwitchedShunts, ImpedanceCorrections}}
     block = Expr(:block)
-    N = fieldcount(R) - 14  # the last 14 = 7(N) + 7(B) columns reqire special handling.
+    N = fieldcount(R) - N_SPECIAL[R]
     append!(block.args, _parse_values(R, 1, N))
     coln = N + 1
     colb = N + 2
-    for _ in 2:8  # parse n2, b2, ..., n8, b8
-        Tn = eltype(fieldtype(SwitchedShunts, coln))
-        Tb = eltype(fieldtype(SwitchedShunts, colb))
+    for _ in 1:(N_SPECIAL[R] ÷ 2)
+        Tn = eltype(fieldtype(R, coln))
+        Tb = eltype(fieldtype(R, colb))
         push!(block.args, :(
-            if newline(code)  # TODO: improve on checking `newline` 7 times?
+            if newline(code)  # TODO: improve on checking `newline` multiple times?
                 push!(getfield(rec, $coln), zero($Tn))
                 push!(getfield(rec, $colb), zero($Tb))
             else

src/types.jl

@@ -383,10 +383,10 @@ Each AC transformer to be represented in PSS/E is introduced through transformer
 that specify all the data required to model transformers in power flow calculations, with
 one exception.
 
-That exception is a set of ancillary data, comprising transformer impedance correction tables,
+That exception is a set of ancillary data, comprising transformer impedance correction records,
 which define the manner in which transformer impedance changes as off-nominal turns ratio or
 phase shift angle is adjusted. Those data records are described in Transformer Impedance
-Correction Tables.
+Correction Records, [`ImpedanceCorrections`](@ref).
 
 Both two-winding and three-winding transformers are specified in the transformer data records.
 The data records for the two-winding transformer are common to the three-winding transformer;
@@ -674,9 +674,10 @@ struct Transformers <: Records
     """
     ntp1::Vector{Int16}
     """
-    The number of a transformer impedance correction table if this transformer winding’s
+    The number of a transformer impedance correction record if this transformer winding’s
     impedance is to be a function of either off-nominal turns ratio or phase shift angle,
     or 0 if no transformer impedance correction is to be applied to this transformer winding.
+    See [`ImpedanceCorrections`](@ref).
     `tab1` = 0 by default.
     """
     tab1::Vector{Int}
@@ -800,9 +801,10 @@ struct Transformers <: Records
     """
     ntp2::Vector{Union{Int16, Missing}}
     """
-    The number of a transformer impedance correction table if this transformer winding’s
+    The number of a transformer impedance correction record if this transformer winding’s
     impedance is to be a function of either off-nominal turns ratio or phase shift angle,
     or 0 if no transformer impedance correction is to be applied to this transformer winding.
+    See [`ImpedanceCorrections`](@ref).
     `tab2` = 0 by default.
     _Ignored for a two-winding transformer._
     """
@@ -932,9 +934,10 @@ struct Transformers <: Records
     """
     ntp3::Vector{Union{Int16, Missing}}
     """
-    The number of a transformer impedance correction table if this transformer winding’s
+    The number of a transformer impedance correction record if this transformer winding’s
     impedance is to be a function of either off-nominal turns ratio or phase shift angle,
     or 0 if no transformer impedance correction is to be applied to this transformer winding.
+    See [`ImpedanceCorrections`](@ref).
     `tab3` = 0 by default.
     _Ignored for a two-winding transformer._
     """
@@ -1656,6 +1659,68 @@ struct SwitchedShunts <: Records
     b8::Vector{Float64}
 end
 
+"""
+    $TYPEDEF
+
+Transformer impedance corrections are used to model a change of transformer impedance
+as off-nominal turns ratio or phase shift angle is adjusted.
+
+The ``T_i`` values on a transformer impedance correction record must all be either tap
+ratios or phase shift angles. They must be entered in strictly ascending order;
+i.e. for each ``i``, ``T_{i+1} > T_i``. Each ``F_i`` entered must be greater than zero.
+
+On each record, at least 2 pairs of values must be specified and up to 11 may be entered.
+
+The ``T_i`` values that are a function of tap ratio (rather than phase shift angle)
+are in units of the controlling winding’s off-nominal turns ratio in pu of the controlling
+winding’s bus base voltage.
+
+Although a transformer winding is assigned to an impedance correction record, each record may
+be shared among many transformer windings. If the first ``T`` in a record is less than 0.5 or
+the last ``T`` entered is greater than 1.5, ``T`` is assumed to be the phase shift angle and
+the impedance of each transformer winding assigned to the record is treated as a function of
+phase shift angle. Otherwise, the impedances of the transformer windings assigned to the record
+are made sensitive to off-nominal turns ratio.
+
+# Fields
+$TYPEDFIELDS
+"""
+struct ImpedanceCorrections <: Records
+    "Impedance correction record number."
+    i::Vector{Int16}
+    """
+    Either off-nominal turns ratio in pu or phase shift angle in degrees.
+    `ti` = 0.0 by default.
+    """
+    t1::Vector{Float64}
+    """
+    Scaling factor by which transformer nominal impedance is to be multiplied to obtain the
+    actual transformer impedance for the corresponding `ti`.
+    `fi` = 0.0 by default.
+    """
+    f1::Vector{Float64}
+    t2::Vector{Float64}
+    f2::Vector{Float64}
+    t3::Vector{Float64}
+    f3::Vector{Float64}
+    t4::Vector{Float64}
+    f4::Vector{Float64}
+    t5::Vector{Float64}
+    f5::Vector{Float64}
+    t6::Vector{Float64}
+    f6::Vector{Float64}
+    t7::Vector{Float64}
+    f7::Vector{Float64}
+    t8::Vector{Float64}
+    f8::Vector{Float64}
+    t9::Vector{Float64}
+    f9::Vector{Float64}
+    t10::Vector{Float64}
+    f10::Vector{Float64}
+    t11::Vector{Float64}
+    f11::Vector{Float64}
+end
+
 ###
 ### Network
 ###
@@ -1718,6 +1783,8 @@ struct Network
     vsc_dc::VSCDCLines
     "Switched Shunt records."
     switched_shunts::SwitchedShunts
+    "Transformer impedance correction records."
+    impedance_corrections::ImpedanceCorrections
 end
 
 ###

test/runtests.jl

@@ -63,7 +63,7 @@ using Test
         @test repr(mime, net; context) == "Network"
         @test repr(mime, net) == strip(
             """
-            Network with 10 data categories:
+            Network with 11 data categories:
              $(sprint(show, mime, net.caseid))
              $(sprint(show, mime, net.buses; context))
              $(sprint(show, mime, net.loads; context))
@@ -74,6 +74,7 @@ using Test
              $(sprint(show, mime, net.two_terminal_dc; context))
              $(sprint(show, mime, net.vsc_dc; context))
              $(sprint(show, mime, net.switched_shunts; context))
+             $(sprint(show, mime, net.impedance_corrections; context))
             """
         )
         @test repr(mime, net.caseid) == "CaseID: (ic = 0, sbase = 100.0)"
@@ -158,7 +159,15 @@ using Test
         @test vsc_dc.rmpct2 == [100.0]     # last entry of 3nd row
 
         switched_shunts = net1.switched_shunts
-        @test isempty(switched_shunts)
+        @test switched_shunts.i == [113]   # first col
+        @test switched_shunts.n1 == [1]    # `n1` always present
+        @test switched_shunts.b1 == [26.0] # `b1` always present
+        @test switched_shunts.n8 == [0]    # `n8` not present; should default to zero
+        @test switched_shunts.b8 == [0.0]  # last col; `b8` not present; default to zero
+
+        impedance_corrections = net1.impedance_corrections
+        @test impedance_corrections.i == [1]       # first col
+        @test impedance_corrections.f11 == [0.0]   # last col; `f11` not present; default to zero
     end
 
     @testset "v29 file" begin
@@ -232,5 +241,9 @@ using Test
         @test switched_shunts.b2 == [0.0, 17.69]   # `b2` col present only for second entry
         @test switched_shunts.n8 == [0, 0]         # `n8` col not present for either entry
         @test switched_shunts.b8 == [0.0, 0.0]     # last col; `b8` col not present for either entry
+
+        impedance_corrections = net2.impedance_corrections
+        @test impedance_corrections.i == [1, 2]          # first col
+        @test impedance_corrections.f11 == [3.34, 1.129] # last col
     end
 end

test/testfiles/synthetic_data_v29.raw

@@ -34,6 +34,8 @@
    175,1,1.04200,0.92200,     0,  100.0,'            ',   39.52, 2,  19.76
    177,0,1.06400,0.98400,     0,  100.0,'            ',    0.00, 1,  15.60, 1,  17.69
 0 / END OF SWITCHED SHUNT DATA, BEGIN IMPEDANCE CORRECTION DATA
+ 1, -44.00, 1.34000, -31.30, 4.44000, -22.20, 4.00000, -21.70, 3.03030, -13.50, 2.00000,   0.00, 1.00000,  13.50, 1.76000,  27.50, 5.67800,  33.30, 3.66600,  41.70, 2.25000,  47.00, 3.34000
+ 2, -38.90, 2.40600, -34.50, 2.25200, -17.00, 1.11900, -10.30, 1.90600,  -5.50, 2.02900,   2.70, 1.00900,   9.00, 4.18100,  15.00, 6.16100,  22.20, 1.19900,  28.80, 3.45600,  35.10, 1.12900
 0 / END OF IMPEDANCE CORRECTION DATA, BEGIN MULTI-TERMINAL DC DATA
 0 / END OF MULTI-TERMINAL DC DATA, BEGIN MULTI-SECTION LINE DATA
 0 / END OF MULTI-SECTION LINE DATA, BEGIN ZONE DATA

test/testfiles/synthetic_data_v30.raw

@@ -36,8 +36,9 @@ SOME OTHER COMMENTS
   1117, 1, 1, 150.000,1.01200,1118.0000,1.6400,  0.00, 210.00, 1300.19,0.5000, 100.00,-100.00,1117,100.00
    114, 2, 1, -20.000,1.02100,1119.0000,1.6400,  0.00, 210.00, 1300.19,0.5000, 100.00,-100.00, 114,100.00
 0 / end of Voltage Source Converter cards
-0 / end of shunt cards
 113,0, 1.123, 1.123,     0, 100.0,' '     ,     26.00, 1,  26.00                                                                                       /* [GILLY   113  ] */
+0 / end of shunt cards
+     1, -40.000, 1.849, -30.000, 1.402, -20.000, 1.196, -10.000, 1.045,   0.000, 1.000,  10.000, 1.045,  20.000, 1.161,  30.000, 1.366,  40.000, 1.741
 0 / end of transformer impedance correction table cards
 0 / end of multi-terminal DC line cards
 0 / end of multi-section line cards