improve documentation (esp. for results)

NLaws · Jul 30, 2023 · ca6c5d0 · ca6c5d0
1 parent 89c5c6a
commit ca6c5d0
Show file tree

Hide file tree

Showing 7 changed files with 43 additions and 11 deletions.
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,5 +1,6 @@
 [deps]
 CommonOPF = "dad7ea18-2b21-482e-81c1-e84414cc4b03"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
 LinDistFlow = "bf674bac-ffe4-48d3-9f32-72124ffa9ede"
 LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
diff --git a/docs/make.jl b/docs/make.jl
@@ -1,6 +1,7 @@
 using Documenter
 using CommonOPF
 using LinDistFlow
+using JuMP
 
 makedocs(
     sitename = "LinDistFlow.jl Documentation",

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -10,7 +10,7 @@ There are two methods for creating `Inputs`:
 2. Providing the network topology
 ```@docs
 Inputs(::String, ::String)
-Inputs(::Array{Tuple}, ::Array{String}, ::Array{Float64}, ::Vector{Vector}, ::String)
+Inputs(::AbstractVector{<:Tuple}, ::AbstractVector{<:AbstractString}, ::AbstractVector{<:Real}, ::AbstractVector{<:AbstractVector}, ::String)
 ```
 Both of the `Inputs` functions return a mutable `Inputs` struct:
 ```@docs
@@ -61,4 +61,16 @@ m[:cons][:injection_equalities]["680"][:P][1] = @constraint(m, [t in 1:p.Ntimest
 ```
 where `p` is short for "parameters" and is the `Inputs` struct for the problem of interest. Note that it is not necessary to store the new constraints in the `m[:cons][:injection_equalities]`.
 
-See the [JuMP documentation](https://jump.dev/JuMP.jl/stable/manual/constraints/#Delete-a-constraint) for more on deleting constraints.
+See the [JuMP documentation](https://jump.dev/JuMP.jl/stable/manual/constraints/#Delete-a-constraint) for more on deleting constraints.
+
+# Results
+Results for the power flow variables can be retrieved via the `Results` methods described below. 
+The fields of the `Results` struct are dictionaries that have the same indices as the variables described above.
+```@docs
+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.
+```@docs
+get_line_amp_approximations
+```
diff --git a/docs/src/methods.md b/docs/src/methods.md
@@ -5,4 +5,5 @@ j_to_k
 i_to_j
 singlephase38linesInputs
 constrain_line_amps
+define_line_amp_estimates
 ```
diff --git a/src/LinDistFlow.jl b/src/LinDistFlow.jl
@@ -30,7 +30,8 @@ export
     remove_bus!,
     combine_parallel_lines!,
     Results,
-    get_line_amp_approximations
+    get_line_amp_approximations,
+    define_line_amp_estimates
 
 include("utils.jl")
 include("model_single_phase.jl")

diff --git a/src/model_multi_phase.jl b/src/model_multi_phase.jl
@@ -215,6 +215,17 @@ function constrain_loads(m, p::Inputs{MultiPhase})
 end
 
 
+"""
+    define_line_amp_estimates(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}
+``
+
+The expressions are stored in the `model.obj_dict` with key `:amps_pu`.
+"""
 function define_line_amp_estimates(m::JuMP.AbstractModel, p::Inputs{MultiPhase})
     Pij = m[:Pij]
     Qij = m[:Qij]
@@ -238,13 +249,9 @@ end
 """
     constrain_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}
-``
+Constrain the estimated line amps using the `p.Isquared_up_bounds` in both the postive and negative directions.
 
-The expressions are stored in the `model.obj_dict` with key `:amps_pu`.
+See `define_line_amp_estimates` for more.
 """
 function constrain_line_amps(m::JuMP.AbstractModel, p::Inputs{MultiPhase})
     if !(:amps_pu in keys(m.obj_dict))

diff --git a/src/results.jl b/src/results.jl
@@ -14,7 +14,7 @@ end
 
 
 """
-    Results(m::AbstractModel, p::Inputs{SinglePhase})
+    Results(m::AbstractModel, p::Inputs{SinglePhase}; digits=8)
 
 return a `Results` struct with fieldnames:
 
@@ -44,7 +44,7 @@ end
 
 
 """
-    Results(m::AbstractModel, p::Inputs{MultiPhase})
+    Results(m::AbstractModel, p::Inputs{MultiPhase}; digits=8)
 
 return a `Results` struct with fieldnames:
 
@@ -114,6 +114,15 @@ function CommonOPF.get_variable_values(var::Symbol, m::JuMP.AbstractModel, p::In
 end
 
 
+"""
+    get_line_amp_approximations(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})
     if !(:amps_pu in keys(m.obj_dict))
         define_line_amp_estimates(m, p)