Jd/area balance network models

docs/src/api/PowerSimulations.md

@@ -7,7 +7,7 @@ end
 
 # API Reference
 
-### Table of Contents
+## Table of Contents
 
 * [Device Models](#Device-Models)
     * [Formulations](#Formulations)
@@ -42,7 +42,7 @@ end
  
 ```
 
-# Device Models
+## Device Models
 
 List of structures and methods for Device models
 
@@ -66,7 +66,7 @@ Refer to the [Problem Templates Page](@ref op_problem_template) for available `P
 
 ---
 
-# Decision Models
+## Decision Models
 
 ```@docs
 DecisionModel
@@ -83,7 +83,7 @@ solve!(::DecisionModel)
 
 ---
 
-# Emulation Models
+## Emulation Models
 
 ```@docs
 EmulationModel
@@ -100,7 +100,7 @@ run!(::EmulationModel)
 
 ---
 
-# Service Models
+## Service Models
 
 List of structures and methods for Service models
 
@@ -115,7 +115,7 @@ ServiceModel
 
 ---
 
-# Simulation Models
+## Simulation Models
 
 Refer to the [Simulations Page](@ref running_a_simulation) to explanations on how to setup a Simulation, with Sequencing and Feedforwards.
 
@@ -210,7 +210,7 @@ LowerBoundFeedForwardSlack
 
 ---
 
-# Constraints
+## Constraints
 
 ### Common Constraints
 
@@ -222,7 +222,6 @@ PieceWiseLinearCostConstraint
 ### Network Constraints
 
 ```@docs
-AreaDispatchBalanceConstraint
 CopperPlateBalanceConstraint
 NodalBalanceActiveConstraint
 NodalBalanceReactiveConstraint
@@ -292,7 +291,7 @@ FeedforwardLowerBoundConstraint
 
 ---
 
-# Parameters
+## Parameters
 
 ### Time Series Parameters
 

docs/src/formulation_library/Network.md

@@ -7,8 +7,10 @@ Network formulations are used to describe how the network and buses are handled
 | `CopperPlatePowerModel` | Copper plate connection between all components, i.e. infinite transmission capacity |
 | `AreaBalancePowerModel` | Network model approximation to represent inter-area flow with each area represented as a single node |
 | `PTDFPowerModel` | Uses the PTDF factor matrix to compute the fraction of power transferred in the network across the branches |
+| `AreaPTDFPowerModel` | Uses the PTDF factor matrix to compute the fraction of power transferred in the network across the branches and balances power by Area instead of system-wide |
 
 [`PowerModels.jl`](https://github.com/lanl-ansi/PowerModels.jl) available formulations:
+
 - Exact non-convex models: `ACPPowerModel`, `ACRPowerModel`, `ACTPowerModel`.
 - Linear approximations: `DCPPowerModel`, `NFAPowerModel`.
 - Quadratic approximations: `DCPLLPowerModel`, `LPACCPowerModel`
@@ -28,10 +30,11 @@ CopperPlatePowerModel
 **Variables:**
 
 If Slack variables are enabled:
+
 - [`SystemBalanceSlackUp`](@ref):
   - Bounds: [0.0, ]
   - Default initial value: 0.0
-  - Default proportional cost: 1e6 
+  - Default proportional cost: 1e6
   - Symbol: ``p^\text{sl,up}``
 - [`SystemBalanceSlackDown`](@ref):
   - Bounds: [0.0, ]
@@ -66,20 +69,30 @@ AreaBalancePowerModel
 ```
 
 **Variables:**
+If Slack variables are enabled:
 
-Slack variables are not supported for `AreaBalancePowerModel`
+- [`SystemBalanceSlackUp`](@ref) by area:
+  - Bounds: [0.0, ]
+  - Default initial value: 0.0
+  - Default proportional cost: 1e6
+  - Symbol: ``p^\text{sl,up}``
+- [`SystemBalanceSlackDown`](@ref) by area:
+  - Bounds: [0.0, ]
+  - Default initial value: 0.0
+  - Default proportional cost: 1e6
+  - Symbol: ``p^\text{sl,dn}``
 
 **Objective:**
 
-No changes to the objective function.
+Adds ``p^\text{sl,up}`` and ``p^\text{sl,dn}`` terms to the respective active power balance expressions `ActivePowerBalance` per area.
 
 **Expressions:**
 
-Creates `ActivePowerBalance` expressions for each bus that then are used to balance active power for all buses within a single area.
+Creates `ActivePowerBalance` expressions for each area that then are used to balance active power for all buses within a single area.
 
 **Constraints:**
 
-Adds the `AreaDispatchBalanceConstraint` to balance the active power of all components available in an area.
+Adds the `CopperPlateBalanceConstraint` to balance the active power of all components available in an area.
 
 ```math
 \begin{align}
@@ -98,10 +111,11 @@ PTDFPowerModel
 **Variables:**
 
 If Slack variables are enabled:
+
 - [`SystemBalanceSlackUp`](@ref):
   - Bounds: [0.0, ]
   - Default initial value: 0.0
-  - Default proportional cost: 1e6 
+  - Default proportional cost: 1e6
   - Symbol: ``p^\text{sl,up}``
 - [`SystemBalanceSlackDown`](@ref):
   - Bounds: [0.0, ]
@@ -128,4 +142,3 @@ Adds the `CopperPlateBalanceConstraint` to balance the active power of all compo
 ```
 
 In addition creates `NodalBalanceActiveConstraint` for HVDC buses balance, if DC components are connected to an HVDC network.
-

docs/src/tutorials/adding_new_problem_model.md

@@ -62,7 +62,7 @@ my_model = DecisionModel{MyCustomDecisionProblem}(
 These methods can be defined optionally for your problem. By default for problems subtyped from `DecisionProblem` these checks are not executed. If the problems are subtyped from `DefaultDecisionProblem` these checks are always conducted with PowerSimulations defaults and require compliance with those defaults to pass. In any case, these can be overloaded when necessary depending on the problem requirements.
 
 1. `validate_template`
-2. `validate_time_series`
+2. `validate_time_series!`
 3. `reset!`
 4. `solve_impl!`
 

src/PowerSimulations.jl

@@ -21,6 +21,7 @@ export NetworkModel
 export PTDFPowerModel
 export CopperPlatePowerModel
 export AreaBalancePowerModel
+export AreaPTDFPowerModel
 
 ######## Device Models ########
 export DeviceModel
@@ -242,7 +243,6 @@ export AbsoluteValueConstraint
 export ActivePowerVariableLimitsConstraint
 export ActivePowerVariableTimeSeriesLimitsConstraint
 export ActiveRangeICConstraint
-export AreaDispatchBalanceConstraint
 export AreaParticipationAssignmentConstraint
 export BalanceAuxConstraint
 export CommitmentConstraint
@@ -553,6 +553,7 @@ include("devices_models/devices/renewable_generation.jl")
 include("devices_models/devices/thermal_generation.jl")
 include("devices_models/devices/electric_loads.jl")
 include("devices_models/devices/AC_branches.jl")
+include("devices_models/devices/area_interchange.jl")
 include("devices_models/devices/TwoTerminalDC_branches.jl")
 include("devices_models/devices/HVDCsystems.jl")
 include("devices_models/devices/regulation_device.jl")

src/core/constraints.jl

@@ -20,7 +20,6 @@ The specified constraint is generally formulated as:
 \\sum_{c \\in \\text{components}_a} p_t^c = 0, \\quad \\forall a\\in \\{1,\\dots, A\\}, t \\in \\{1, \\dots, T\\}
 ```
 """
-struct AreaDispatchBalanceConstraint <: ConstraintType end
 struct AreaParticipationAssignmentConstraint <: ConstraintType end
 struct BalanceAuxConstraint <: ConstraintType end
 """
@@ -78,7 +77,7 @@ The specified constraint is formulated as:
 ```math
 \\begin{align*}
 &  \\text{ActivePowerRangeExpressionUB}_t := p_t^\\text{th} - \\text{on}_t^\\text{th}P^\\text{th,max} \\le 0, \\quad  \\forall t\\in \\{1, \\dots, T\\}  \\\\
-&  \\text{ActivePowerRangeExpressionLB}_t := p_t^\\text{th} - \\text{on}_t^\\text{th}P^\\text{th,min} \\ge 0, \\quad  \\forall t\\in \\{1, \\dots, T\\} 
+&  \\text{ActivePowerRangeExpressionLB}_t := p_t^\\text{th} - \\text{on}_t^\\text{th}P^\\text{th,min} \\ge 0, \\quad  \\forall t\\in \\{1, \\dots, T\\}
 \\end{align*}
 ```
 """
@@ -162,7 +161,7 @@ For more information check [Branch Formulations](@ref PowerSystems.Branch-Formul
 The specified constraint is formulated as:
 
 ```math
-R^\\text{to,min} \\le f_t^\\text{to-from}  \\le R^\\text{to,max},\\quad \\forall t \\in \\{1,\\dots, T\\} 
+R^\\text{to,min} \\le f_t^\\text{to-from}  \\le R^\\text{to,max},\\quad \\forall t \\in \\{1,\\dots, T\\}
 ```
 """
 struct FlowRateConstraintToFrom <: ConstraintType end
@@ -274,7 +273,7 @@ The specified constraint is formulated as:
 ```math
 \\begin{align*}
 &  f_t - f_t^\\text{sl,up} \\le R^\\text{max},\\quad \\forall t \\in \\{1,\\dots, T\\} \\\\
-&  f_t + f_t^\\text{sl,lo} \\ge -R^\\text{max},\\quad \\forall t \\in \\{1,\\dots, T\\} 
+&  f_t + f_t^\\text{sl,lo} \\ge -R^\\text{max},\\quad \\forall t \\in \\{1,\\dots, T\\}
 \\end{align*}
 ```
 """
@@ -343,7 +342,7 @@ The specified constraints are formulated as:
 ```math
 \\begin{align*}
 & f_t^\\text{to-from} - f_t^\\text{from-to} \\le \\ell_t,\\quad \\forall t \\in \\{1,\\dots, T\\} \\\\
-& f_t^\\text{from-to} - f_t^\\text{to-from} \\le \\ell_t,\\quad \\forall t \\in \\{1,\\dots, T\\} 
+& f_t^\\text{from-to} - f_t^\\text{to-from} \\le \\ell_t,\\quad \\forall t \\in \\{1,\\dots, T\\}
 \\end{align*}
 ```
 """

src/core/formulations.jl

@@ -166,6 +166,10 @@ struct CopperPlatePowerModel <: PM.AbstractActivePowerModel end
 Approximation to represent inter-area flow with each area represented as a single node.
 """
 struct AreaBalancePowerModel <: PM.AbstractActivePowerModel end
+"""
+Linear active power approximation using the power transfer distribution factor [PTDF](https://nrel-sienna.github.io/PowerNetworkMatrices.jl/stable/tutorials/tutorial_PTDF_matrix/) matrix. Balacing areas independently.
+"""
+struct AreaPTDFPowerModel <: AbstractPTDFModel end
 
 #================================================
     # exact non-convex models

src/core/network_model.jl

@@ -118,7 +118,10 @@ function instantiate_network_model(
     return
 end
 
-function instantiate_network_model(model::NetworkModel{PTDFPowerModel}, sys::PSY.System)
+function instantiate_network_model(
+    model::NetworkModel{<:AbstractPTDFModel},
+    sys::PSY.System,
+)
     if get_PTDF_matrix(model) === nothing
         @info "PTDF Matrix not provided. Calculating using PowerNetworkMatrices.PTDF"
         model.PTDF_matrix =
@@ -140,7 +143,7 @@ end
 function _assign_subnetworks_to_buses(
     model::NetworkModel{T},
     sys::PSY.System,
-) where {T <: Union{CopperPlatePowerModel, PTDFPowerModel}}
+) where {T <: Union{CopperPlatePowerModel, AbstractPTDFModel}}
     subnetworks = model.subnetworks
     temp_bus_map = Dict{Int, Int}()
     radial_network_reduction = PSI.get_radial_network_reduction(model)

src/core/optimization_container.jl

@@ -460,9 +460,40 @@ function _make_system_expressions!(
     container::OptimizationContainer,
     subnetworks::Dict{Int, Set{Int}},
     dc_bus_numbers::Vector{Int},
-    ::Type{T},
+    ::Type{AreaPTDFPowerModel},
+    areas::IS.FlattenIteratorWrapper{PSY.Area},
+)
+    if length(subnetworks) > 1
+        throw(
+            IS.ConflictingInputsError(
+                "AreaPTDFPowerModel doesn't support systems with multiple asynchrous areas",
+            ),
+        )
+    end
+
+    time_steps = get_time_steps(container)
+    ac_bus_numbers = collect(Iterators.flatten(values(subnetworks)))
+    subnetworks = collect(keys(subnetworks))
+    container.expressions = Dict(
+        ExpressionKey(ActivePowerBalance, PSY.Area) =>
+            _make_container_array(PSY.get_name.(areas), time_steps),
+        ExpressionKey(ActivePowerBalance, PSY.DCBus) =>
+            _make_container_array(dc_bus_numbers, time_steps),
+        ExpressionKey(ActivePowerBalance, PSY.ACBus) =>
+        # Bus numbers are sorted to guarantee consistency in the order between the
+        # containers
+            _make_container_array(sort!(ac_bus_numbers), time_steps),
+    )
+    return
+end
+
+function _make_system_expressions!(
+    container::OptimizationContainer,
+    subnetworks::Dict{Int, Set{Int}},
+    dc_bus_numbers::Vector{Int},
+    ::Type{PTDFPowerModel},
     bus_reduction_map::Dict{Int64, Set{Int64}},
-) where {T <: PTDFPowerModel}
+)
     time_steps = get_time_steps(container)
     if isempty(bus_reduction_map)
         ac_bus_numbers = collect(Iterators.flatten(values(subnetworks)))
@@ -483,6 +514,27 @@ function _make_system_expressions!(
     return
 end
 
+function _make_system_expressions!(
+    container::OptimizationContainer,
+    subnetworks::Dict{Int, Set{Int}},
+    ::Type{AreaBalancePowerModel},
+    areas::IS.FlattenIteratorWrapper{PSY.Area},
+)
+    if length(subnetworks) > 1
+        throw(
+            IS.ConflictingInputsError(
+                "AreaBalancePowerModel doesn't support systems with multiple asynchrous areas",
+            ),
+        )
+    end
+    time_steps = get_time_steps(container)
+    container.expressions = Dict(
+        ExpressionKey(ActivePowerBalance, PSY.Area) =>
+            _make_container_array(PSY.get_name.(areas), time_steps),
+    )
+    return
+end
+
 function initialize_system_expressions!(
     container::OptimizationContainer,
     ::Type{T},
@@ -495,6 +547,37 @@ function initialize_system_expressions!(
     return
 end
 
+function initialize_system_expressions!(
+    container::OptimizationContainer,
+    ::Type{AreaBalancePowerModel},
+    subnetworks::Dict{Int, Set{Int}},
+    system::PSY.System,
+    ::Dict{Int64, Set{Int64}},
+)
+    areas = PSY.get_components(PSY.Area, system)
+    _make_system_expressions!(container, subnetworks, AreaBalancePowerModel, areas)
+    return
+end
+
+function initialize_system_expressions!(
+    container::OptimizationContainer,
+    ::Type{AreaPTDFPowerModel},
+    subnetworks::Dict{Int, Set{Int}},
+    system::PSY.System,
+    ::Dict{Int64, Set{Int64}},
+)
+    areas = PSY.get_components(PSY.Area, system)
+    dc_bus_numbers = [PSY.get_number(b) for b in PSY.get_components(PSY.DCBus, system)]
+    _make_system_expressions!(
+        container,
+        subnetworks,
+        dc_bus_numbers,
+        AreaPTDFPowerModel,
+        areas,
+    )
+    return
+end
+
 function build_impl!(
     container::OptimizationContainer,
     template::ProblemTemplate,