missing 3wt methods (#211)

* add missing 3wt transformer methods

* add missing predicates

* formatter

* add missing 3WT methods

* add new struct

* update common to return the correct type

* update tests

* use get for filters

---------

Co-authored-by: m-bossart <bossart.matt@gmail.com>

Author: jd-lara

Project.toml

@@ -28,6 +28,6 @@ KLU = "^0.6"
 LinearAlgebra = "1"
 MKL = "0.9"
 Pardiso = "1"
-PowerSystems = "5"
+PowerSystems = "^5.2"
 SparseArrays = "1"
 julia = "^1.6"

src/BranchesSeries.jl

@@ -181,7 +181,7 @@ function add_to_map(series_circuit::BranchesSeries, filters::Dict)
         end
         return true
     else
-        filter = filters[first(keys(series_circuit.branches))]
+        filter = get(filters, first(keys(series_circuit.branches)), x -> true)
         return all([filter(device) for device in first(values(series_circuit.branches))])
     end
     error("Invalid condition reached in add_to_map for BranchesSeries")

src/EquivalentBranch.jl

@@ -0,0 +1,34 @@
+"""
+    EquivalentBranch
+
+Represents the equivalent parameters of a network branch for power flow calculations.
+
+# Fields
+- `equivalent_r::Float64`: Equivalent series resistance (p.u.)
+- `equivalent_x::Float64`: Equivalent series reactance (p.u.)
+- `equivalent_g_from::Float64`: Equivalent shunt conductance at the "from" bus (p.u.)
+- `equivalent_b_from::Float64`: Equivalent shunt susceptance at the "from" bus (p.u.)
+- `equivalent_g_to::Float64`: Equivalent shunt conductance at the "to" bus (p.u.)
+- `equivalent_b_to::Float64`: Equivalent shunt susceptance at the "to" bus (p.u.)
+- `equivalent_tap::Float64`: Equivalent transformer tap ratio
+- `equivalent_shift::Float64`: Equivalent phase shift angle (radians)
+"""
+mutable struct EquivalentBranch
+    equivalent_r::Float64
+    equivalent_x::Float64
+    equivalent_g_from::Float64
+    equivalent_b_from::Float64
+    equivalent_g_to::Float64
+    equivalent_b_to::Float64
+    equivalent_tap::Float64
+    equivalent_shift::Float64
+end
+
+get_equivalent_r(eb::EquivalentBranch) = eb.equivalent_r
+get_equivalent_x(eb::EquivalentBranch) = eb.equivalent_x
+get_equivalent_g_from(eb::EquivalentBranch) = eb.equivalent_g_from
+get_equivalent_b_from(eb::EquivalentBranch) = eb.equivalent_b_from
+get_equivalent_g_to(eb::EquivalentBranch) = eb.equivalent_g_to
+get_equivalent_b_to(eb::EquivalentBranch) = eb.equivalent_b_to
+get_equivalent_tap(eb::EquivalentBranch) = eb.equivalent_tap
+get_equivalent_shift(eb::EquivalentBranch) = eb.equivalent_shift

src/NetworkReductionData.jl

@@ -301,8 +301,8 @@ get_removed_buses(rb::NetworkReductionData) = rb.removed_buses
 get_removed_arcs(rb::NetworkReductionData) = rb.removed_arcs
 get_added_admittance_map(rb::NetworkReductionData) = rb.added_admittance_map
 get_added_branch_map(rb::NetworkReductionData) = rb.added_branch_map
-get_name_to_arc_map(rb::NetworkReductionData) = rb.name_to_arc_map
 get_all_branch_maps_by_type(rb::NetworkReductionData) = rb.all_branch_maps_by_type
+
 """
     get_reductions(rb::NetworkReductionData)
 
@@ -316,6 +316,15 @@ Get the reduction container from NetworkReductionData.
 """
 get_reductions(rb::NetworkReductionData) = rb.reductions
 
+get_name_to_arc_maps(rb::NetworkReductionData) = rb.name_to_arc_map
+
+get_name_to_arc_map(rb::NetworkReductionData, ::Type{T}) where {T <: PSY.ACTransmission} =
+    rb.name_to_arc_map[T]
+get_name_to_arc_map(
+    rb::NetworkReductionData,
+    ::Type{ThreeWindingTransformerWinding{T}},
+) where {T <: PSY.ThreeWindingTransformer} = rb.name_to_arc_map[T]
+
 has_radial_reduction(rb::NetworkReductionData) = has_radial_reduction(rb.reductions)
 has_degree_two_reduction(rb::NetworkReductionData) = has_degree_two_reduction(rb.reductions)
 has_ward_reduction(rb::NetworkReductionData) = has_ward_reduction(rb.reductions)
@@ -370,15 +379,16 @@ Gets the concrete types of all AC transmission branches included in an instance
 - `Set{DataType}`: Vector of the retained branch types.
 """
 function get_ac_transmission_types(network_reduction_data::NetworkReductionData)
-    direct_types = Set(typeof.(keys(network_reduction_data.reverse_direct_branch_map)))
+    direct_types =
+        Set(typeof.(keys(network_reduction_data.reverse_direct_branch_map)))
     parallel_types =
-        Set(typeof.(keys(network_reduction_data.reverse_parallel_branch_map)))
-    series_types = Set(typeof.(keys(network_reduction_data.reverse_series_branch_map)))
-    transformer_3w_devices =
-        Set(
-            first(tuple) for tuple in keys(network_reduction_data.reverse_transformer3W_map)
+        Set{DataType}(typeof.(keys(network_reduction_data.reverse_parallel_branch_map)))
+    series_types =
+        Set{DataType}(typeof.(keys(network_reduction_data.reverse_series_branch_map)))
+    transformer_3W_types =
+        Set{DataType}(
+            get_transformer_type.(keys(network_reduction_data.reverse_transformer3W_map)),
         )
-    transformer_3W_types = typeof.(transformer_3w_devices)
     return union(direct_types, parallel_types, series_types, transformer_3W_types)
 end
 

src/PowerNetworkMatrices.jl

@@ -75,6 +75,7 @@ import LinearAlgebra: LAPACK.getrf!, LAPACK.getrs!
 include("PowerNetworkMatrix.jl")
 include("ThreeWindingTransformerWinding.jl")
 include("definitions.jl")
+include("EquivalentBranch.jl")
 include("BranchesSeries.jl")
 include("BranchesParallel.jl")
 include("NetworkReduction.jl")

src/ThreeWindingTransformerWinding.jl

@@ -21,6 +21,9 @@ end
 
 get_transformer(tw::ThreeWindingTransformerWinding) = tw.transformer
 get_winding_number(tw::ThreeWindingTransformerWinding) = tw.winding_number
+get_transformer_type(
+    ::ThreeWindingTransformerWinding{T},
+) where {T <: PSY.ThreeWindingTransformer} = T
 
 function get_name(three_wt_winding::ThreeWindingTransformerWinding)
     transformer = get_transformer(three_wt_winding)
@@ -34,6 +37,70 @@ function get_series_susceptance(segment::ThreeWindingTransformerWinding)
     return PSY.get_series_susceptances(tfw)[winding_int]
 end
 
+"""
+    get_equivalent_r(tw::ThreeWindingTransformerWinding)
+
+Get the resistance for a specific winding of a three-winding transformer.
+Returns the winding-specific series resistance.
+"""
+function get_equivalent_r(tw::ThreeWindingTransformerWinding)
+    tfw = get_transformer(tw)
+    winding_num = get_winding_number(tw)
+
+    if winding_num == 1
+        return PSY.get_r_primary(tfw)
+    elseif winding_num == 2
+        return PSY.get_r_secondary(tfw)
+    elseif winding_num == 3
+        return PSY.get_r_tertiary(tfw)
+    else
+        throw(ArgumentError("Invalid winding number: $winding_num"))
+    end
+end
+
+"""
+    get_equivalent_x(tw::ThreeWindingTransformerWinding)
+
+Get the reactance for a specific winding of a three-winding transformer.
+Returns the winding-specific series reactance.
+"""
+function get_equivalent_x(tw::ThreeWindingTransformerWinding)
+    tfw = get_transformer(tw)
+    winding_num = get_winding_number(tw)
+
+    if winding_num == 1
+        return PSY.get_x_primary(tfw)
+    elseif winding_num == 2
+        return PSY.get_x_secondary(tfw)
+    elseif winding_num == 3
+        return PSY.get_x_tertiary(tfw)
+    else
+        throw(ArgumentError("Invalid winding number: $winding_num"))
+    end
+end
+
+"""
+    get_equivalent_b(tw::ThreeWindingTransformerWinding)
+
+Get the susceptance for a specific winding of a three-winding transformer.
+For the primary winding (winding 1), returns the shunt susceptance from the transformer.
+For secondary and tertiary windings, returns 0.0 as the shunt is only on the primary side.
+"""
+function get_equivalent_b(tw::ThreeWindingTransformerWinding)
+    tfw = get_transformer(tw)
+    winding_num = get_winding_number(tw)
+
+    if winding_num == 1
+        # Only the primary winding has the shunt susceptance
+        return (from = PSY.get_b(tfw), to = 0.0)
+    elseif winding_num == 2 || winding_num == 3
+        # Secondary and tertiary windings don't have shunt susceptance
+        return (from = 0.0, to = 0.0)
+    else
+        throw(ArgumentError("Invalid winding number: $winding_num"))
+    end
+end
+
 """
     get_equivalent_rating(tw::ThreeWindingTransformerWinding)
 
@@ -107,6 +174,52 @@ function get_arc_tuple(tr::ThreeWindingTransformerWinding)
     end
 end
 
+"""
+    get_equivalent_tap(tw::ThreeWindingTransformerWinding)
+
+Get the tap (turns ratio) for a specific winding of a three-winding transformer.
+Returns the winding-specific turns ratio for phase shifting transformers.
+"""
+function get_equivalent_tap(
+    tw::ThreeWindingTransformerWinding{PSY.PhaseShiftingTransformer3W},
+)
+    tfw = get_transformer(tw)
+    winding_num = get_winding_number(tw)
+
+    if winding_num == 1
+        return PSY.get_primary_turns_ratio(tfw)
+    elseif winding_num == 2
+        return PSY.get_secondary_turns_ratio(tfw)
+    elseif winding_num == 3
+        return PSY.get_tertiary_turns_ratio(tfw)
+    else
+        throw(ArgumentError("Invalid winding number: $winding_num"))
+    end
+end
+
+"""
+    get_equivalent_α(tw::ThreeWindingTransformerWinding)
+
+Get the phase angle (α) for a specific winding of a three-winding transformer.
+Returns the winding-specific phase shift angle for phase shifting transformers.
+"""
+function get_equivalent_α(
+    tw::ThreeWindingTransformerWinding{PSY.PhaseShiftingTransformer3W},
+)
+    tfw = get_transformer(tw)
+    winding_num = get_winding_number(tw)
+
+    if winding_num == 1
+        return PSY.get_α_primary(tfw)
+    elseif winding_num == 2
+        return PSY.get_α_secondary(tfw)
+    elseif winding_num == 3
+        return PSY.get_α_tertiary(tfw)
+    else
+        throw(ArgumentError("Invalid winding number: $winding_num"))
+    end
+end
+
 function add_to_map(device::ThreeWindingTransformerWinding, filters::Dict)
     return add_to_map(get_transformer(device), filters)
 end

src/common.jl

@@ -308,9 +308,9 @@ end
 """
     get_equivalent_physical_branch_parameters(equivalent_ybus::Matrix{ComplexF32})
 
-Takes as input a 2x2 Matrix{ComplexF32} representing the Ybus contribution of either a 
-BranchesParallel or BranchesSeries object. 
-Returns a dictionary of equivalent parameters, matching the PowerModels data format. 
+Takes as input a 2x2 Matrix{ComplexF32} representing the Ybus contribution of either a
+BranchesParallel or BranchesSeries object.
+Returns a dictionary of equivalent parameters, matching the PowerModels data format.
 """
 function _get_equivalent_physical_branch_parameters(equivalent_ybus::Matrix{ComplexF32})
     y_11, y_12, y_21, y_22 = equivalent_ybus
@@ -337,14 +337,5 @@ function _get_equivalent_physical_branch_parameters(equivalent_ybus::Matrix{Comp
     b_from = imag(y_11 - y_l)
     g_to = real(y_22 - y_l)
     b_to = imag(y_22 - y_l)
-    return Dict{Symbol, Float64}(
-        :r => r,
-        :x => x,
-        :g_from => g_from,
-        :b_from => b_from,
-        :g_to => g_to,
-        :b_to => b_to,
-        :tap => tap,
-        :shift => shift,
-    )
+    return EquivalentBranch(r, x, g_from, b_from, g_to, b_to, tap, shift)
 end