REF: Ensure all PMD functions' phase loops are internal (#168)

This refactor ensures that all variable and constraint functions internal to PowerModelsDistribution, e.g. those containing `_mc_`, have any loops over the phases internal to that function, instead of requiring an explicit loop inside the problem definition.

Updates changelog

Closes #81
Closes #61
Closes #152

CHANGELOG.md

@@ -2,6 +2,7 @@ PowerModelsDistribution.jl Change Log
 ===================================
 
 ### staged
+- Change internal variable and constraint functions to loop over phases internally (breaking) (#168)
 - Fix bug in OpenDSS parser on Lines where the connected phases are listed out of order (#167)
 - Add ability to "bank" single phase OpenDSS transformers into a single multiphase transformer (#166)
 - Add virtual line to sourcebus to model source impedance (#165)

LICENSE.md

@@ -1,9 +1,19 @@
-Copyright (c) 2016, Los Alamos National Security, LLC
+Copyright (c) 2018, Triad National Security, LLC.
+
 All rights reserved.
-Copyright 2016. Los Alamos National Security, LLC. This software was produced under U.S. Government contract DE-AC52-06NA25396 for Los Alamos National Laboratory (LANL), which is operated by Los Alamos National Security, LLC for the U.S. Department of Energy. The U.S. Government has rights to use, reproduce, and distribute this software.  NEITHER THE GOVERNMENT NOR LOS ALAMOS NATIONAL SECURITY, LLC MAKES ANY WARRANTY, EXPRESS OR IMPLIED, OR ASSUMES ANY LIABILITY FOR THE USE OF THIS SOFTWARE.  If software is modified to produce derivative works, such modified software should be clearly marked, so as not to confuse it with the version available from LANL.
+
+This program was produced under U.S. Government contract 89233218CNA000001 for Los Alamos National Laboratory (LANL), which is operated by Triad National Security, LLC for the U.S. Department of Energy/National Nuclear Security Administration. The U.S. Government has rights to use, reproduce, and distribute this software. NEITHER THE GOVERNMENT NOR TRIAD NATIONAL SECURITY, LLC MAKES ANY WARRANTY, EXPRESS OR IMPLIED, OR ASSUMES ANY LIABILITY FOR THE USE OF THIS SOFTWARE. If software is modified to produce derivative works, such modified software should be clearly marked, so as not to confuse it with the version available from LANL.
+
+All rights in the program are reserved by Triad National Security, LLC, and the U.S. Department of Energy/National Nuclear Security Administration. The Government is granted for itself and others acting on its behalf a nonexclusive, paid-up, irrevocable worldwide license in this material to reproduce, prepare derivative works, distribute copies to the public, perform publicly and display publicly, and to permit others to do so.
 
 Additionally, redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-1.	Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 
-2.	Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 
-3.	Neither the name of Los Alamos National Security, LLC, Los Alamos National Laboratory, LANL, the U.S. Government, nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.  
-THIS SOFTWARE IS PROVIDED BY LOS ALAMOS NATIONAL SECURITY, LLC AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL LOS ALAMOS NATIONAL SECURITY, LLC OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of Triad National Security, LLC, Los Alamos National Laboratory, LANL, the U.S. Government, nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY TRIAD NATIONAL SECURITY, LLC AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL TRIAD NATIONAL SECURITY, LLC OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+LICENSEE AGREES TO WAIVE ANY AND ALL CLAIMS AGAINST THE U.S. GOVERNMENT AND THE UNITED STATES GOVERNMENT'S CONTRACTORS AND SUBCONTRACTORS, AND SHALL INDEMNIFY AND HOLD HARMLESS THE U.S. GOVERNMENT AND THE UNITED STATES GOVERNMENT'S CONTRACTORS AND SUBCONTRACTORS FOR ANY LIABILITIES, DEMANDS, DAMAGES, EXPENSES, OR LOSSES THAT MAY ARISE FROM RECIPIENT'S USE OF THE NUFLOOD SOFTWARE OR PROVIDED DOCUMENTATION, INCLUDING ANY LIABILITIES OR DAMAGES FROM PRODUCTS BASED ON, OR RESULTING FROM, THE USE THEREOF.

README.md

@@ -13,23 +13,23 @@ Dev:
 PowerModelsDistribution.jl is an extention package of PowerModels.jl for Steady-State Power Distribution Network Optimization.  It is designed to enable computational evaluation of emerging power network formulations and algorithms in a common platform.  The code is engineered to decouple problem specifications (e.g. Power Flow, Optimal Power Flow, ...) from the power network formulations (e.g. AC, linear-approximation, SOC-relaxation, ...).
 This enables the definition of a wide variety of power network formulations and their comparison on common problem specifications.
 
-**Core Problem Specifications**
+## Core Problem Specifications
 
-* Power Flow (pf)
-* Optimal Power Flow (opf), for the Bus Injection Model (BIM) as well as the Branch Flow Model (BFM)
-* Continuous load shed, minimum load delta (mld), for the Branch Flow Model (LPLinUBFPowerModel), AC Polar (ACPPowerModel), and Network Flow Approximation (NFAPowerModel)
+- Power Flow (pf)
+- Optimal Power Flow (opf), for the Bus Injection Model (BIM) as well as the Branch Flow Model (BFM)
+- Continuous load shed, minimum load delta (mld), for the Branch Flow Model (LPLinUBFPowerModel), AC Polar (ACPPowerModel), and Network Flow Approximation (NFAPowerModel)
 
-**Core Network Formulations**
+## Core Network Formulations
 
-* AC (polar and rectangular coordinates)
-* SDP BFM relaxation
-* SOC BFM and BIM relaxation (W-space)
-* Linear approximation (LinDist3Flow and simplified unbalanced DistFlow)
+- AC (polar and rectangular coordinates)
+- SDP BFM relaxation
+- SOC BFM and BIM relaxation (W-space)
+- Linear approximation (LinDist3Flow and simplified unbalanced DistFlow)
 
-**Network Data Formats**
+## Network Data Formats
 
-* Matlab ".m" files (extended for three-phase)
-* OpenDSS ".dss" files
+- Matlab ".m" files (extended for three-phase)
+- OpenDSS ".dss" files
 
 **Warning:** This package is under active development and may change drastically without warning.
 
@@ -41,8 +41,8 @@ Community-driven development and enhancement of PowerModelsDistribution are welc
 
 This code has been developed as part of the Advanced Network Science Initiative at Los Alamos National Laboratory.  The primary developers are David Fobes(@pseudocubic) and Carleton Coffrin(@ccoffrin) with support from the following contributors:
 
-* Sander Claeys (@sanderclaeys) KU Leuven, transformer models and ACR formulation
-* Frederik Geth (@frederikgeth) CSIRO, Distribution modeling advise
+- Sander Claeys (@sanderclaeys) KU Leuven, transformer models and ACR formulation
+- Frederik Geth (@frederikgeth) CSIRO, Distribution modeling advise
 
 ## License
 

docs/src/formulation-details.md

@@ -1,46 +1,46 @@
 # Three-phase formulation details
 
 
-## `StandardACPForm`
+## `AbstractACPModel`
 Real-valued formulation from:
 - Formulation without shunts: Mahdad, B., Bouktir, T., & Srairi, K. (2006). A three-phase power flow modelization: a tool for optimal location and control of FACTS devices in unbalanced power systems. In IEEE Industrial Electronics IECON (pp. 2238–2243).
 
 
 
-## `StandardDCPForm`
-Applying all of the standard DC linearization tricks to the `StandardACPForm`
+## `AbstractDCPModel`
+Applying all of the standard DC linearization tricks to the `AbstractACPModel`
 
-## `SOCWRForm`
-Applying the standard BIM voltage cross-product (sine and cosine) substitution tricks to `StandardACPForm` results immediately in a SOC formulation.
+## `SOCWRModel`
+Applying the standard BIM voltage cross-product (sine and cosine) substitution tricks to `AbstractACPModel` results immediately in a SOC formulation.
 
-## `SDPUBFForm`
+## `SDPUBFModel`
 The BFM SDP relaxation as described in:
 - Gan, L., & Low, S. H. (2014). Convex relaxations and linear approximation for optimal power flow in multiphase radial networks. In PSSC (pp. 1–9). Wroclaw, Poland. https://doi.org/10.1109/PSCC.2014.7038399
 Note that this formulation is complex-valued and additional steps are needed to implement this in JuMP.
 
-## `SOCNLPUBFForm`
-The starting point is `SDPUBFForm`. The SDP constraint can be relaxed to a set of SOC constraints, starting from either the real or complex form of the matrix on which the PSD-ness constraint is applied.
+## `SOCNLPUBFModel`
+The starting point is `SDPUBFModel`. The SDP constraint can be relaxed to a set of SOC constraints, starting from either the real or complex form of the matrix on which the PSD-ness constraint is applied.
 - Kim, S., Kojima, M., & Yamashita, M. (2003). Second order cone programming relaxation of a positive semidefinite constraint. Optimization Methods and Software, 18(5), 535–541. https://doi.org/10.1080/1055678031000148696
 - Andersen, M. S., Hansson, A., & Vandenberghe, L. (2014). Reduced-complexity semidefinite relaxations of optimal power flow problems. IEEE Trans. Power Syst., 29(4), 1855–1863.
 
 
-## `SOCConicUBFForm`
-See `SOCNLPUBFForm`
+## `SOCConicUBFModel`
+See `SOCNLPUBFModel`
 
 
-## `LPfullUBFForm`
+## `LPfullUBFModel`
 Matrix formulation that generalizes `simplified DistFlow equations`, as introduced in :
 - Gan, L., & Low, S. H. (2014). Convex relaxations and linear approximation for optimal power flow in multiphase radial networks. In PSSC (pp. 1–9). Wroclaw, Poland. https://doi.org/10.1109/PSCC.2014.7038399
 
 Note that this formulation is complex-valued and additional steps are needed to implement this in JuMP.
 
-## `LPdiagUBFForm`
+## `LPdiagUBFModel`
 This formulation has originally been developed by Sankur et al.
 - Sankur, M. D., Dobbe, R., Stewart, E., Callaway, D. S., & Arnold, D. B. (2016). A linearized power flow model for optimization in unbalanced distribution systems. https://arxiv.org/abs/1606.04492v2
 
-This formulation is here cast as only considering the diagonal elements defined in `LPfullUBFForm`, which furthermore leads to the imaginary part of the lifted node voltage variable W being redundant and substituted out.
+This formulation is here cast as only considering the diagonal elements defined in `LPfullUBFModel`, which furthermore leads to the imaginary part of the lifted node voltage variable W being redundant and substituted out.
 
-## `LPLinUBFForm`
+## `LPLinUBFModel`
 Scalar reformulation of:
 - Sankur, M. D., Dobbe, R., Stewart, E., Callaway, D. S., & Arnold, D. B. (2016). A linearized power flow model for optimization in unbalanced distribution systems. https://arxiv.org/abs/1606.04492v2
 This formulation was already derived in real variables and parameters.

docs/src/index.md

@@ -7,6 +7,7 @@ CurrentModule = PowerModelsDistribution
 ## Overview
 
 PowerModelsDistribution.jl is a Julia/JuMP extension package to PowerModels.jl for modeling of Multi-Phase (with a focus on three-phase) power grids.
+
 ## Installation
 
 The latest stable release of PowerModels can be installed using the Julia package manager with

docs/src/math-model.md

@@ -2,7 +2,6 @@
 
 As PowerModelsDistribution implements a variety of power network optimization problems, the implementation is the best reference for precise mathematical formulations.  This section provides a complex number based mathematical specification for a prototypical unbalanced AC Optimal Power Flow problem, to provide an overview of the typical mathematical models in PowerModelsDistribution.
 
-
 ## Unbalanced AC Optimal Power Flow
 
 PowerModelsDistribution implements a  generalized version of the AC Optimal Power Flow problem, from [Matpower](http://www.pserc.cornell.edu/matpower/) but extended to take into account phase unbalance [^1].  These generalizations make it possible for PowerModelsDistribution to more accurately capture real-world distribution network datasets.  The core generalizations are,
@@ -11,17 +10,18 @@ PowerModelsDistribution implements a  generalized version of the AC Optimal Powe
 - Line charging (shunt) that supports a conductance and asymmetrical values
 
 In the mathematical description below,
+
 - Bold typeface indicates a vector ($\in \mathbb{C}^c$) or matrix ($\in \mathbb{C}^{c\times c}$)
 - Operator $diag$ takes the diagonal (vector) from a square matrix
 - The set of complex numbers is $\mathbb{C}$ and real numbers is $\mathbb{R}$
 - Superscript $H$ indicates complex conjugate transpose (Hermitian adjoint)
 - Note that complex power is defined as $\mathbf{S}_{ij} = \mathbf{V}_{i} \mathbf{I}_{ij}^H$ and is therefore a complex matrix of dimension $c \times c$
 - The line $\mathbf{Y}^c_{ij}, \mathbf{Y}^c_{ji}$ and bus $\mathbf{Y}^s_{k}$ shunt matrices do not need to be diagonal
 
-
 ### Sets
 
 The definitions of the sets involved remain unchanged w.r.t. the balanced OPF problem definition, except for the addition of the conductor set:
+
 ```math
 \begin{align}
 %
@@ -36,9 +36,11 @@ The definitions of the sets involved remain unchanged w.r.t. the balanced OPF pr
 %
 \end{align}
 ```
+
 where the set of conductors $C$ typically equals $\{ a,b,c\}$.
 
 ### Data
+
 ```math
 \begin{align}
 \mbox{data:} & \nonumber \\
@@ -53,12 +55,15 @@ where the set of conductors $C$ typically equals $\{ a,b,c\}$.
 %
 \end{align}
 ```
+
 where the notation $\mathbf{v}^l_{i} := [v^l_{i,c}]_{c \in C}$ reflects that the vector $\mathbf{v}^l_{i}$ is constructed by putting the individual phase values $v^l_{i,c}$ in a vector (in order $a,b,c$).
 
 Alternatively, the series impedance of a line can be written in impedance form:
+
 ```math
 \mathbf{Z}_{ij} \in \mathbb{C}^{c\times c} \;\; \forall (i,j) \in E \nonumber, \mathbf{Y}_{ij} = ( \mathbf{Z}_{ij})^{-1}
 ```
+
 where superscript $-1$ indicates the matrix inverse. Note that $\mathbf{Y}_{ij}$ or $\mathbf{Z}_{ij}$ may not be invertible, e.g. in case of single-phase branches in a three-phase grid. In this case the [pseudo-inverse](https://en.wikipedia.org/wiki/Moore%E2%80%93Penrose_inverse) can be used.
 
 ### Variables for a Bus Injection Model
@@ -72,8 +77,7 @@ where superscript $-1$ indicates the matrix inverse. Note that $\mathbf{Y}_{ij}$
 \end{align}
 ```
 
-
-###  Mathematical Formulation of a Bus Injection Model
+### Mathematical Formulation of a Bus Injection Model
 
 A complete mathematical model is as follows,
 
@@ -95,7 +99,6 @@ A complete mathematical model is as follows,
 \end{align}
 ```
 
-
 ### Variables for a Branch Flow Model
 
 ```math
@@ -108,8 +111,7 @@ A complete mathematical model is as follows,
 \end{align}
 ```
 
-
-###  Mathematical Formulation of a Branch Flow Model
+### Mathematical Formulation of a Branch Flow Model
 
 A complete mathematical model is as follows,
 
@@ -132,5 +134,4 @@ A complete mathematical model is as follows,
 \end{align}
 ```
 
-
 [^1] Gan, L., & Low, S. H. (2014). Convex relaxations and linear approximation for optimal power flow in multiphase radial networks. In PSSC (pp. 1–9). Wroclaw, Poland. https://doi.org/10.1109/PSCC.2014.7038399

docs/src/quickguide.md

@@ -16,7 +16,6 @@ The run commands in PowerModelsDistribution return detailed results data in the
 result = run_ac_mc_opf("case3_unbalanced.dss", with_optimizer(Ipopt.Optimizer))
 ```
 
-
 ## Accessing Different Formulations
 
 The function "run_ac_mc_opf" is a shorthands for a more general formulation-independent OPF execution, "run_mc_opf".
@@ -33,9 +32,11 @@ Note that PowerModels needs to be loaded to access formulations which are extend
 using SCS
 run_mc_opf_bf("case3_unbalanced.dss", SDPUBFPowerModel, with_optimizer(SCS.Optimizer))
 ```
+
 Note that you have to use a SDP-capable solver, e.g. the open-source solver SCS, to solve SDP models.
 
 ## Inspecting the Formulation
+
 The following example demonstrates how to break a `run_mc_opf` call into seperate model building and solving steps.  This allows inspection of the JuMP model created by PowerModelsDistribution for the AC-OPF problem,
 
 ```julia

docs/src/specifications.md

@@ -1,14 +1,17 @@
 # Problem Specifications
 
-
 ## Optimal Power Flow (OPF) with On-Load Tap Changers (OLTC)
+
 This problem is identical to `mc_opf`, except that all transformers are now modelled as on-load tap changers (OLTCs). Each phase has an individual tap ratio, which can be either variable or fixed, as specified in the data model.
+
 ### Objective
+
 ```julia
 objective_min_fuel_cost(pm)
 ```
 
 ### Variables
+
 ```julia
 variable_mc_voltage(pm)
 variable_mc_branch_flow(pm)
@@ -22,6 +25,7 @@ variable_mc_oltc_tap(pm)
 ```
 
 ### Constraints
+
 ```julia
 constraint_mc_model_voltage(pm)
 
@@ -34,8 +38,8 @@ for i in PMs.ids(pm, :bus), c in PMs.conductor_ids(pm)
 end
 
 for i in PMs.ids(pm, :branch)
-    constraint_mc_ohms_yt_from(pm, i, cnd=c)
-    constraint_mc_ohms_yt_to(pm, i, cnd=c)
+    constraint_mc_ohms_yt_from(pm, i)
+    constraint_mc_ohms_yt_to(pm, i)
 
     for c in PMs.conductor_ids(pm)
         PMs.constraint_voltage_angle_difference(pm, i, cnd=c)
@@ -55,14 +59,17 @@ end
 ```
 
 ## Optimal Power Flow (OPF) with Load Models (LM)
+
 Unlike `mc_opf`, which models all loads as constant power loads, this problem specification additionally supports loads proportional to the voltage magnitude (a.k.a. constant current) and the square of the voltage magnitude (a.k.a. constant impedance). Each load now has associated active and reactive power variables. In `mc_opf`, loads are directly added as parameters in KCL.
 
 ### Objective
+
 ```julia
 objective_min_fuel_cost(pm)
 ```
 
 ### Variables
+
 ```julia
 variable_mc_voltage(pm)
 variable_mc_branch_flow(pm)
@@ -76,6 +83,7 @@ variable_mc_oltc_tap(pm)
 ```
 
 ### Constraints
+
 ```julia
 constraint_mc_model_voltage(pm)
 
@@ -122,23 +130,25 @@ end
 ```
 
 ## Power Flow (PF) with Load Models (LM)
+
 Unlike `mc_pf`, which models all loads as constant power loads, this problem specification additionally supports loads proportional to the voltage magnitude (a.k.a. constant current) and the square of the voltage magnitude (a.k.a. constant impedance). Each load now has associated active and reactive power variables. In `mc_pf`, loads are directly added as parameters in KCL.
 
 ### Variables
+
 ```julia
 variable_mc_voltage(pm, bounded=false)
 variable_mc_branch_flow(pm, bounded=false)
+variable_mc_trans_flow(pm, bounded=false)
+variable_mc_load(pm)
 
 for c in PMs.conductor_ids(pm)
     PMs.variable_generation(pm, bounded=false, cnd=c)
-    variable_mc_load(pm, cnd=c)
     PMs.variable_dcline_flow(pm, bounded=false, cnd=c)
 end
-
-variable_mc_trans_flow(pm, bounded=false)
 ```
 
 ### Constraints
+
 ```julia
 constraint_mc_model_voltage(pm, bounded=false)
 
@@ -187,7 +197,6 @@ for i in PMs.ids(pm, :branch)
 end
 
 for (i,dcline) in PMs.ref(pm, :dcline), c in PMs.conductor_ids(pm)
-
     PMs.constraint_active_dcline_setpoint(pm, i, cnd=c)
 
     f_bus = PMs.ref(pm, :bus)[dcline["f_bus"]]