Updates for PowerModels v0.17 (#702)

* Rename Problem Modeling Functions (#700)
  * update constraint names
  * update variable function names
  * update expression function names

update details are documented in issue #701

* update docs for new function names

* minor updates for InfrastructureModels v0.5

* Fix reactive power control in storage systems (#699)

Co-authored-by: Geth, Frederik (Energy, Newcastle) <[email protected]>
Co-authored-by: Carleton Coffrin <[email protected]>

CHANGELOG.md

@@ -4,6 +4,12 @@ PowerModels.jl Change Log
 ### Staged
 - nothing
 
+### v0.17.0
+- Updated to new function name convention, details in issue #701 (#555,#656) (breaking)
+- Update to InfrastructureModels v0.5 (breaking)
+- Added support for Memento v1.1
+- Fixed storage reactive power dispatch model, added reactive power control variable (breaking)
+
 ### v0.16.0
 - Added a native AC Power Flow solver in polar coordinates that uses NLSolve (#590)
 - Added `ismulticonductor` check on data models
@@ -13,7 +19,7 @@ PowerModels.jl Change Log
 - 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)
+- Moved isolated component removal 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)

Project.toml

@@ -16,13 +16,13 @@ SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 
 [compat]
 Cbc = ">= 0.4"
-InfrastructureModels = "~0.4.3"
+InfrastructureModels = "~0.5"
 Ipopt = ">= 0.4"
 JSON = "~0.18, ~0.19, ~0.20, ~0.21"
 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"
+Memento = "~0.10, ~0.11, ~0.12, ~0.13, ~1.0, ~1.1"
 NLsolve = "4.0"
 SCS = ">= 0.6.3"
 julia = "^1"

docs/src/constraints.md

@@ -14,14 +14,14 @@ These templates should be defined over `AbstractPowerModel` and should not refer
 ```@docs
 constraint_model_voltage
 constraint_model_voltage_on_off
-constraint_model_voltage_ne
+constraint_ne_model_voltage
 ```
 
 ## Generator Constraints
 
 ```@docs
-constraint_active_gen_setpoint
-constraint_reactive_gen_setpoint
+constraint_gen_setpoint_active
+constraint_gen_setpoint_reactive
 ```
 
 ## Bus Constraints
@@ -38,7 +38,7 @@ constraint_voltage_magnitude_setpoint
 ```@docs
 constraint_power_balance
 constraint_power_balance_ls
-constraint_power_balance_ne
+constraint_ne_power_balance
 ```
 
 ## Branch Constraints
@@ -57,8 +57,8 @@ constraint_ohms_y_to
 ```@docs
 constraint_ohms_yt_from_on_off
 constraint_ohms_yt_to_on_off
-constraint_ohms_yt_from_ne
-constraint_ohms_yt_to_ne
+constraint_ne_ohms_yt_from
+constraint_ne_ohms_yt_to
 ```
 
 ### Current
@@ -77,8 +77,8 @@ constraint_thermal_limit_from
 constraint_thermal_limit_to
 constraint_thermal_limit_from_on_off
 constraint_thermal_limit_to_on_off
-constraint_thermal_limit_from_ne
-constraint_thermal_limit_to_ne
+constraint_ne_thermal_limit_from
+constraint_ne_thermal_limit_to
 ```
 
 ### Current Limit Constraints
@@ -92,14 +92,14 @@ constraint_current_limit
 ```@docs
 constraint_voltage_angle_difference
 constraint_voltage_angle_difference_on_off
-constraint_voltage_angle_difference_ne
+constraint_ne_voltage_angle_difference
 ```
 
 ### Loss Constraints
 
 ```@docs
-constraint_loss_lb
-constraint_flow_losses
+constraint_power_losses
+constraint_power_losses_lb
 constraint_voltage_magnitude_difference
 ```
 
@@ -110,14 +110,14 @@ constraint_storage_thermal_limit
 constraint_storage_current_limit
 constraint_storage_complementarity_nl
 constraint_storage_complementarity_mi
-constraint_storage_loss
+constraint_storage_losses
 constraint_storage_state_initial
 constraint_storage_state
 ```
 
 ## DC Line Constraints
 
 ```@docs
-constraint_dcline
-constraint_active_dcline_setpoint
+constraint_dcline_power_losses
+constraint_dcline_setpoint_active
 ```

docs/src/developer.md

@@ -9,13 +9,45 @@ scope functions).  Underscores are used to separate multi-word function names
 and the words should typically be ordered from general to more specific,
 so that alphabetical sorting clusters similar functions together.
 
+Due to model-agnostic design of PowerModels, top level functions are implicitly defined on complex numbers.  Specializations of these functions yield different complex coordinates systems and real-valued model parameters.  
 
-## Variable and Parameter Naming Guidelines
+Top level functions have the following structure,
+```
+<variable|constraint>_<component short name>_<quantity name>(_fr|_to)(_on_off)
+```
+The suffixes have the following meanings,
+- `_fr`: the from-side of a two-terminal component (e.g., branch or switch)
+- `_to`: the to-side of a two-terminal component (e.g., branch or switch)
+- `_on_off`: indicates that the constraint can be added or removed with a discrete 0-1 indicator variable.
+Note that the from-to orientation of two-terminal components is often arbitrary and does not imply a direction of flow.
+
+The most common values of `<quantity name>` are `power`, `current` and `voltage`.  Compound names like `voltage_product` are also possible.
 
-### Suffixes
 
-- `_fr`: from-side ('i'-node)
-- `_to`: to-side ('j'-node)
+Lower level functions have the following structure,
+```
+<variable|constraint>_<component short name>_<quantity name>
+(_real|_imaginary|_magnitude|_angle|_factor)(_fr|_to)(_sqr)(_on_off)
+```
+The additional suffixes have the following meanings,
+- `_real`: the real component of a complex value in rectangular coordinates
+- `_imaginary`: the imaginary component of a complex value in rectangular coordinates
+- `_magnitude`: the magnitude of a complex value in polar coordinates
+- `_angle`: the angle of a complex value in polar coordinates
+- `_factor`: a continuous real value (usually in the range 0.0 to 1.0), that scales a complex value in equal proportions
+- `_sqr`: the square of a value, usually paired with `_magnitude`
+
+
+### Special Cases
+
+In the interest of intuitive names for users, the following special cases are also acceptable,
+
+- The value of `<component short name>` can be omitted from constraint definitions for one of the canonical components that it applies to.
+- `_power_real` -(can be replaced with)-> `_active`
+- `_power_imaginary` -(can be replaced with)-> `_reactive`
+
+
+## Variable and Parameter Naming Guidelines
 
 ### Power
 
@@ -90,7 +122,7 @@ $y = g + j\cdot b$:
 - phase ids: `phase`, `ph`, `h`
 
 
-## DistFlow derivation
+## DistFlow Derivation
 
 ### For an asymmetric pi section
 Following notation of [^1], but recognizing it derives the SOC BFM without shunts.

docs/src/formulations.md

@@ -25,11 +25,11 @@ QCRMPowerModel <: AbstractWRForm
 SOCBFPowerModel <: AbstractSOCBFModel
 ```
 
-For details on `AbstractPowerModel`, see the section on [Power Model](@ref).
+For details on `AbstractPowerModel`, see the section on [Power Model](@ref).  A more comprehensive list of supported formulation is documented in [Formulation Details](@ref).
 
 ## User-Defined Abstractions
 
-Consider the class of conic Models for power flow models. One way of modelling them in this package is through the following type hierarchy:
+Consider the class of conic Models for power flow models. One way of modeling them in this package is through the following type hierarchy:
 ```julia
 AbstractConicPowerModel <: AbstractPowerModel
 AbstractWRMModel <: AbstractConicPowerModel