add get_peak_line_amps_percent, refactor line amp method names

CHANGELOG.md

@@ -1,5 +1,8 @@
 # LinDistFlow Changelog
 
+## dev
+- add `get_line_amps`, `get_peak_line_amps_percent`, and `define_line_amps_pu`
+
 ## v0.5.0
 - deprecate `get_edge_values` and `get_bus_values` in favor of `CommonOPF.get_variable_values`
 - add `Results` for `SinglePhase` and `MultiPhase` models

docs/src/index.md

@@ -70,7 +70,8 @@ The fields of the `Results` struct are dictionaries that have the same indices a
 Results(m::JuMP.AbstractModel, p::Inputs{SinglePhase}; digits=8)
 Results(m::JuMP.AbstractModel, p::Inputs{MultiPhase}; digits=8)
 ```
-Approximate line amperage values can also be obtained via `get_line_amp_approximations` for multi-phase models.
+Approximate line amperage values can be obtained via `get_line_amps` and `get_peak_line_amps_percent` for multi-phase models.
 ```@docs
-get_line_amp_approximations
+get_line_amps
+get_peak_line_amps_percent
 ```

docs/src/methods.md

@@ -5,5 +5,5 @@ j_to_k
 i_to_j
 singlephase38linesInputs
 constrain_line_amps
-define_line_amp_estimates
+define_line_amps_pu
 ```

src/LinDistFlow.jl

@@ -30,8 +30,9 @@ export
     remove_bus!,
     combine_parallel_lines!,
     Results,
-    get_line_amp_approximations,
-    define_line_amp_estimates
+    get_line_amps,
+    define_line_amps_pu,
+    get_peak_line_amps_percent
 
 include("utils.jl")
 include("model_single_phase.jl")

src/model_multi_phase.jl

@@ -216,7 +216,7 @@ end
 
 
 """
-    define_line_amp_estimates(m::JuMP.AbstractModel, p::Inputs{MultiPhase})
+    define_line_amps_pu(m::JuMP.AbstractModel, p::Inputs{MultiPhase})
 
 Estimating the line amps as ``|(V_i - V_j) / Z|`` where we use the approximation:
 
@@ -226,7 +226,7 @@ Estimating the line amps as ``|(V_i - V_j) / Z|`` where we use the approximation
 
 The expressions are stored in the `model.obj_dict` with key `:amps_pu`.
 """
-function define_line_amp_estimates(m::JuMP.AbstractModel, p::Inputs{MultiPhase})
+function define_line_amps_pu(m::JuMP.AbstractModel, p::Inputs{MultiPhase})
     Pij = m[:Pij]
     Qij = m[:Qij]
     m[:amps_pu] = Dict(ek => Dict() for ek in p.edge_keys)
@@ -251,11 +251,11 @@ end
 
 Constrain the estimated line amps using the `p.Isquared_up_bounds` in both the postive and negative directions.
 
-See `define_line_amp_estimates` for more.
+See `define_line_amps_pu` for more.
 """
 function constrain_line_amps(m::JuMP.AbstractModel, p::Inputs{MultiPhase})
     if !(:amps_pu in keys(m.obj_dict))
-        define_line_amp_estimates(m, p)
+        define_line_amps_pu(m, p)
     end
     for j in p.busses
         for i in i_to_j(j, p)  # for radial network there is only one i in i_to_j

src/results.jl

@@ -115,17 +115,16 @@ end
 
 
 """
-    get_line_amp_approximations(m::JuMP.AbstractModel, p::Inputs{MultiPhase})
+    get_line_amps(m::JuMP.AbstractModel, p::Inputs{MultiPhase})
 
 Estimating the line amps as ``|(V_i - V_j) / Z|`` where we use the approximation:
-
 ``
 |V_i - V_j| \\approx r_{ij} P_{ij} + x_{ij} Q_{ij}
 ``
 """
-function get_line_amp_approximations(m::JuMP.AbstractModel, p::Inputs{MultiPhase})
+function get_line_amps(m::JuMP.AbstractModel, p::Inputs{MultiPhase})
     if !(:amps_pu in keys(m.obj_dict))
-        define_line_amp_estimates(m, p)
+        define_line_amps_pu(m, p)
     end
     optimal_amps = Dict{String, Dict{Int, Vector{Float64}}}()
     for (edge_key, phs_dict) in m[:amps_pu]
@@ -136,3 +135,33 @@ function get_line_amp_approximations(m::JuMP.AbstractModel, p::Inputs{MultiPhase
     end
     return optimal_amps
 end
+
+
+"""
+    get_peak_line_amps_percent(m::JuMP.AbstractModel, p::Inputs{MultiPhase})
+
+A `Dict{String, Float64}` with edge keys and peak percent line amps (peak over all time steps)
+
+Estimating the line amps as ``|(V_i - V_j) / Z|`` where we use the approximation:
+``
+|V_i - V_j| \\approx r_{ij} P_{ij} + x_{ij} Q_{ij}
+``
+"""
+function get_peak_line_amps_percent(m::JuMP.AbstractModel, p::Inputs{MultiPhase})
+    if !(:amps_pu in keys(m.obj_dict))
+        define_line_amps_pu(m, p)
+    end
+    optimal_amps = get_line_amps(m, p)
+    peak_percents = Dict{String, Float64}()
+    for j in p.busses
+        for i in i_to_j(j, p)  # for radial network there is only one i in i_to_j
+            i_j = string(i*"-"*j)
+            ij_linecode = get_ijlinecode(i,j,p)
+            amps_limit = sqrt(p.Isquared_up_bounds[ij_linecode])
+            for phs in p.phases_into_bus[j]
+                peak_percents[i_j] = maximum(optimal_amps[i_j][phs]) / amps_limit * 100
+            end
+        end
+    end
+    return peak_percents
+end

test/runtests.jl

@@ -255,7 +255,7 @@ end
 end
 
 
-@testset "constrain line amps" begin
+@testset "line amps" begin
 
     p = Inputs(
         joinpath("data", "13bus", "IEEE13Nodeckt.dss"), 
@@ -284,7 +284,8 @@ end
     optimize!(m)
 
     # find the max amps then constrain it, should get infeasible problem
-    optimal_amps = get_line_amp_approximations(m, p)
+    optimal_amps = get_line_amps(m, p)
+    optimal_amps_percent = get_peak_line_amps_percent(m, p)
     # collect all the values by unpacking the dict of dicts
     max_amps = maximum(vcat(collect(vcat(v...) for v in values.(values(optimal_amps)))...))
     p.Isquared_up_bounds = Dict(