Updates for PowerModels v0.16 (#696)

* improved flexibity of branch flow expressions

* remove flow variables from PF definition

* NLSolve AC Power Flow Solver (#689)

* add NLSolve to deps
* add complex admittance matrix computation
* add julia native ac power flow solver, closes #590
* add tests for native ac pf solver

* Use Generic InfrastructureModels Tools (#691)

* updates for im solution generalization
* fixes for downstream packages, export and pm_fields macro
* remove InitializePowerModel, instantiate_model, update ref_ext api

* Update PWL implementation to sos variant (#692)

* lambda variant of pwl costs on generators and dclines

* update data correcting scripts for better power flow support

* revised semantics of propagate_topology_status, closes #677

* break pf-native test to separate file

* add PowerFlowData struct to support ac pf solves with minimal memory allocation

* Improved Generator Assignment in AC-PF (#695)

* update ac pf to assign generators based on reactive capacity
* refactor generator assignment to _assign_pg and _assign_qg functions
* add bus_gens to PowerFlowData struct

* add ac power flow solver docs

* add notes to changelog

* prep for release v0.16.0

CHANGELOG.md

@@ -4,6 +4,21 @@ PowerModels.jl Change Log
 ### Staged
 - nothing
 
+### v0.16.0
+- Added a native AC Power Flow solver in polar coordinates that uses NLSolve (#590)
+- Added `ismulticonductor` check on data models
+- Made branch power flow expressions formulation agnostic (#684) (breaking)
+- Changed the PWL cost implementation from a max formulation to a relaxaed sos formulation
+- Updated PWL cost data processing to require points that span a generators complete operating range (breaking)
+- Updated `correct_bus_types!` to correct slack buses and focus on preparation for power flow studies (breaking)
+- Updated ref extensions API to use ref and data dictionaries, not power model types (#668) (breaking)
+- Replaced `propagate_topology_status!` with `simplify_network!` (breaking)
+- Moved isolated component removal from `propagate_topology_status!` into `deactivate_isolated_components!` (#677) (breaking)
+- Removed InitializePowerModel and instantiate_model to use InfratructureModels versions (breaking)
+- Removed export of some functions defined in InfratructureModels (breaking)
+- Removed branch flow variables from generic Power Flow problem specification (breaking)
+- Removed bus type modification from `check_reference_bus` (breaking)
+
 ### v0.15.5
 - Made matpower cost data parser more robust to floating point numbers
 - Fixed the type of derived "ncost" values in `export_matpower`

Project.toml

@@ -2,7 +2,7 @@ name = "PowerModels"
 uuid = "c36e90e8-916a-50a6-bd94-075b64ef4655"
 authors = ["Carleton Coffrin"]
 repo = "https://github.com/lanl-ansi/PowerModels.jl"
-version = "0.15.5"
+version = "0.16.0"
 
 [deps]
 InfrastructureModels = "2030c09a-7f63-5d83-885d-db604e0e9cc0"
@@ -11,6 +11,7 @@ JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
 Memento = "f28f55f0-a522-5efc-85c2-fe41dfb9b2d9"
+NLsolve = "2774e3e8-f4cf-5e23-947b-6d7e65073b56"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 
 [compat]
@@ -22,6 +23,7 @@ JuMP = "~0.19.1, ~0.20, ~0.21"
 Juniper = ">= 0.4"
 MathOptInterface = "~0.8, ~0.9"
 Memento = "~0.10, ~0.11, ~0.12, ~0.13, ~1.0"
+NLsolve = "4.0"
 SCS = ">= 0.6.3"
 julia = "^1"
 

docs/make.jl

@@ -12,6 +12,7 @@ makedocs(
             "Network Data Format" => "network-data.md",
             "Result Data Format" => "result-data.md",
             "Mathematical Model" => "math-model.md",
+            "Power Flow" => "power-flow.md",
             "Storage Model" => "storage.md",
             "Switch Model" => "switch.md",
             "Multi Networks" => "multi-networks.md",

docs/src/network-data.md

@@ -174,7 +174,7 @@ data = PowerModels.parse_file("matpower/case3.m")
 PowerModels.propagate_topology_status!(data)
 opf_result = run_ac_opf(data, with_optimizer(Ipopt.Optimizer))
 ```
-The `test/data/matpower/case7_tplgy.m` case provides an example of the kind of component status deductions that can be made.  The `propagate_topology_status!` function can be helpful in diagnosing network models that converge to an infeasible solution.
+The `test/data/matpower/case7_tplgy.m` case provides an example of the kind of component status deductions that can be made.  The `simplify_network!`, `propagate_topology_status!` and `deactivate_isolated_components!` functions can be helpful in diagnosing network models that do not converge or have an infeasible solution.
 
 For details on all of the network data helper functions see, `src/core/data.jl`.
 

docs/src/power-flow.md

@@ -0,0 +1,145 @@
+# Power Flow Computations
+
+The typical goal of PowerModels is to build a JuMP model that is used to solve
+power network optimization problems.  The JuMP model abstraction enables
+PowerModels to have state-of-the-art performance on a wide range of problem
+formulations including those with discrete variables and complex non-linear
+constraints, such as semi-definite cones.  That said, for the specific case of
+power flow computations, in some specific applications performance gains can
+be had by avoiding the JuMP model abstraction and solving the problem more
+directly.  To that end, PowerModels includes Julia-native solvers
+for AC power flow in polar voltage coordinates and the DC power flow approximation.
+This section provides an overview of the different power flow options that are
+available in PowerModels and under what circumstances they may be beneficial.
+
+
+## Generic Power Flow
+
+The general purpose power flow solver in PowerModels is,
+
+```@docs
+run_pf
+```
+
+This function builds a JuMP model for a wide variety of the power flow formulations
+supported by PowerModels.  For example it supports,
+* `ACPPowerModel` - a non-convex nonlinear AC power flow using complex voltages in polar coordinates
+* `ACRPowerModel` - a non-convex nonlinear AC power flow using complex voltages in rectangular coordinates
+* `SOCWRPowerModel` - a convex quadratic relaxation of the power flow problem
+* `DCPPowerModel` - a linear DC approximation of the power flow problem
+The typical `ACPPowerModel` and `DCPPowerModel` formulations are available via
+the shorthand form `run_ac_pf` and `run_dc_pf` respectively.
+
+The `run_pf` solution method is both formulation and solver agnostic and
+can leverage the wide range of solvers that are available in the JuMP
+ecosystem.  Many of these solvers are commercial-grade, which in turn makes
+`run_pf` the most reliable power flow solution method in PowerModels.
+
+!!! note
+    Use of `run_pf` is highly recommended over the other solution methods for
+    increased robustness.  Applications that benefit from the Julia native
+    solution methods are an exception to this general rule.
+
+
+### Warm Starting
+
+In some applications an initial guess of the power flow solution may be
+available.  In such a case, this information may be able to decrease a solver's
+time to convergence, especial when solving systems of nonlinear equations.
+The `_start` postfix can be used in the network data to initialize the solver's
+variables and provide a suitable solution guess.  The most common values are
+as follows,
+
+For each generator,
+* `pg_start` - active power injection starting point
+* `qg_start` - reactive power injection starting point
+
+For each bus,
+* `vm_start` - voltage magnitude starting point for the `ACPPowerModel` model
+* `va_start` - voltage angle starting point for the `ACPPowerModel` model
+* `vr_start` - real voltage starting point for the `ACRPowerModel` model
+* `vi_start` - imaginary voltage starting point for the `ACRPowerModel` model
+
+The following helper function can be used to use the solution point in the
+network data as the starting point for `run_ac_pf`.
+```@docs
+set_ac_pf_start_values!
+```
+
+!!! warning
+    Warm starting a solver is a very delicate task and can easily result in
+    degraded performance.  Using PowerModels' default flat-start values is
+    recommended before experimenting with warm starting a solver.
+
+
+## Native AC Power Flow
+
+The AC Power Flow problem is ubiquitous in power system analysis.
+The problem requires solving a system of nonlinear equations, usually via a
+Newton-Raphson type of algorithm.  In PowerModels, the package
+[NLSolve](https://github.com/JuliaNLSolvers/NLsolve.jl) is used for solving
+this system of nonlinear equations.  NLsolve provides a variety of established
+solution methods.  The following function is used to solve AC Power Flow problem
+with voltages in polar coordinates with NLsolve.
+```@docs
+compute_ac_pf
+```
+`compute_ac_pf` will typically provide an identical result to `run_ac_pf`.
+However, the existence of solution degeneracy around generator injection
+assignments and multiple power flow solutions can yield different results.
+The primary advantage of `compute_ac_pf` over `run_ac_pf` is that it does not
+require building a JuMP model.  If the initial point for the AC Power Flow
+solution is near-feasible then `compute_ac_pf` can result in a significant
+runtime saving by converging quickly and reducing data-wrangling and memory
+allocation overheads.  This initial guess is provided using the standard
+`_start` values.  The `set_ac_pf_start_values!` function provides a convenient
+way of setting a suitable starting point.
+
+!!! tip
+    If `compute_ac_pf` fails to converge try `run_ac_pf` instead.
+
+
+## Native DC Power Flow
+
+At its core the DC Power Flow problem simply requires solving a system of 
+linear equations.  This can be done natively in Julia via the `\` operator.
+The following function can be used to solve a DC Power Flow using Julia's
+built-in linear systems solvers.
+```@docs
+compute_dc_pf
+```
+The `compute_dc_pf` method should provide identical results to `run_dc_pf`.
+The primary advantage of `compute_dc_pf` over `run_dc_pf` is that it does not
+require building a JuMP model.  This results in significant memory saving and
+marginal performance saving due to reduced data-wrangling overhead.  The
+primary use-case of this model is to compute the voltage angle values from
+a collection of bus injections when working with a formulation that does not
+explicitly model these values, such as a PTDF or LODF formulation.
+The following utility function provides an example of how `compute_dc_pf` is
+typically used.
+```@docs
+run_opf_ptdf_flow_cuts
+```
+
+This solver does not support warm starting.
+
+
+## Network Admittance Matrix
+
+Internally `compute_ac_pf` and `compute_dc_pf` utilize an admittance matrix
+representation of the network data, which may be useful in other contexts.
+The foundational type for both representations is `AdmittanceMatrix{T}`.
+```@docs
+AdmittanceMatrix
+```
+In the case of an full admittance matrix and simplified susceptance the type is 
+`AdmittanceMatrix{Complex{Float64}}` and `AdmittanceMatrix{Float64}`, respectively.
+
+The following functions can be used to compute the admittance matrix and
+susceptance matrix from PowerModels network data.
+```@docs
+calc_admittance_matrix
+calc_susceptance_matrix
+```
+
+

src/PowerModels.jl

@@ -3,9 +3,11 @@ module PowerModels
 import LinearAlgebra, SparseArrays
 
 import JSON
-import JuMP
 import Memento
 
+import NLsolve
+
+import JuMP
 import MathOptInterface
 const _MOI = MathOptInterface