Add comments to new functions

src/PowerFlow.jl

@@ -144,7 +144,7 @@ end
 #*------------------------------------------------------------------------------
 
 #=
-Calculates the total impact of a hurricane given the time series of damaged transmission lines. Each time a transmission line is destroyed, the AC power flow equations are solved and failure cascades may unfold. The output of the solver is saved in a .txt file.
+Calculates the total impact of a hurricane given a time series of damaged transmission lines. Each time a transmission line is destroyed, the AC power flow equations are solved and failure cascades may unfold. The output of the solver is saved in a .txt file.
 =#
 function calc_total_impact!(
         network_data::Dict{String,<:Any},
@@ -165,6 +165,9 @@ function calc_total_impact!(
     return nothing
 end
 
+#=
+See calc_total_impact!
+=#
 function _calc_total_impact!(
         network_data::Dict{String,<:Any},
         tl_damage::Array{Tuple{String,Int64},1}; # time series of tl damage
@@ -227,6 +230,9 @@ function calc_cascade!(
     return nothing
 end
 
+#=
+Identifies connected components in the network and restores active power balance in each component.
+=#
 function restore_p_balance!(network_data::Dict{String,<:Any})
     ### Calculate connected components
     connected_components = calc_connected_components(network_data)
@@ -242,6 +248,9 @@ function restore_p_balance!(network_data::Dict{String,<:Any})
     return nothing
 end
 
+#=
+Restores active power balance in a connected component identified by the set of buses cc. Depending on whether an overproduction or underproduction exists, generator dispatches may be increased or reduced. If necessary, load can be shed by reducing the demands uniformly until the total demand matches generation. For more details see flow chart. 
+=#
 function _restore_p_balance!(network_data::Dict{String,<:Any}, cc::Set{Int64})
     active_cc_gens = [
         gen["index"] for gen in values(network_data["gen"]) if 
@@ -304,6 +313,9 @@ function _restore_p_balance!(network_data::Dict{String,<:Any}, cc::Set{Int64})
     return nothing
 end
 
+#=
+Calculates and returns the active power mismatch in a connected component identified by the set of buses cc. Depending on whether an overproduction or underproduction exists, the limiting mismatch with minimum or maximum possible active power generation is also calculated and returned.
+=#
 function calc_Δp(
         network_data::Dict{String,<:Any},
         active_cc_gens::Array{Int64,1}, 
@@ -327,22 +339,25 @@ function calc_Δp(
     cc_Δp = cc_pg - cc_pd - cc_ploss 
     if isapprox(cc_Δp, 0, atol=1e-10) # "sufficient" power balance
         cc_Δp = 0.0
-        cc_Δp_lim = NaN
+        cc_Δp_lim = NaN # limiting mismatch not needed
     elseif cc_Δp > 0 # overproduction
         cc_pmin = sum(
             [network_data["gen"]["$g"]["pmin"] for g in active_cc_gens]
         ) # minimum possible active power dispatch
-        cc_Δp_lim = cc_pmin - cc_pd - cc_ploss
+        cc_Δp_lim = cc_pmin - cc_pd - cc_ploss # limiting mismatch
     elseif cc_Δp < 0 # underproduction
         cc_pmax = sum(
             [network_data["gen"]["$g"]["pmax"] for g in active_cc_gens]
         ) # maximum possible active power dispatch
-        cc_Δp_lim = cc_pmax - cc_pd - cc_ploss
+        cc_Δp_lim = cc_pmax - cc_pd - cc_ploss # limiting mismatch
     end
 
     return cc_Δp, cc_Δp_lim
 end
 
+#=
+Uniformly reduces active power dispatches of active generators in a connected component according to the active power mismatch. This is done recursively, since generators may hit their minimum dispatch, which has to be compensated by other generators.
+=#
 function _reduce_p_dispatch!(
         network_data::Dict{String,<:Any},
         active_cc_gens::Array{Int64,1},
@@ -380,6 +395,9 @@ function _reduce_p_dispatch!(
     return nothing
 end
 
+#=
+Uniformly increases active power dispatches of active generators in a connected component according the active power mismatch. This is done recursively, since generators may hit their maximum dispatch, which has to be compensated by other generators.
+=#
 function _increase_p_dispatch!(
         network_data::Dict{String,<:Any},
         active_cc_gens::Array{Int64,1},
@@ -417,7 +435,9 @@ function _increase_p_dispatch!(
     return nothing
 end
 
-# assumption: generators already at their maximum active power dispatch
+#=
+Sheds the amount of load necessary to restore active power balance in a connected component. If active generators are already operated at their maximum possible dispatch, the amount of load shed should be optimal (minimal). 
+=#
 function _shed_minimum_load!(
         network_data::Dict{String,<:Any},
         active_cc_gens::Array{Int64,1},