Merge branch 'jd/area_balance_network_models' into rh/psy4_renaming

NREL-Sienna · Jun 13, 2024 · 45fd8e7 · 45fd8e7
2 parents 91b127d + f8a63c4
commit 45fd8e7
Show file tree

Hide file tree

Showing 33 changed files with 1,409 additions and 266 deletions.
diff --git a/docs/src/api/PowerSimulations.md b/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
 &nbsp;
 ```
 
-# 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
 

diff --git a/docs/src/formulation_library/Network.md b/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.
-
diff --git a/docs/src/tutorials/adding_new_problem_model.md b/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!`
 

diff --git a/src/PowerSimulations.jl b/src/PowerSimulations.jl
@@ -21,6 +21,7 @@ export NetworkModel
 export PTDFPowerModel
 export CopperPlatePowerModel
 export AreaBalancePowerModel
+export AreaPTDFPowerModel
 
 ######## Device Models ########
 export DeviceModel
@@ -238,10 +239,10 @@ export PowerOutput
 
 # Constraints
 export AbsoluteValueConstraint
+export LineFlowBoundConstraint
 export ActivePowerVariableLimitsConstraint
 export ActivePowerVariableTimeSeriesLimitsConstraint
 export ActiveRangeICConstraint
-export AreaDispatchBalanceConstraint
 export AreaParticipationAssignmentConstraint
 export BalanceAuxConstraint
 export CommitmentConstraint
@@ -552,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")

diff --git a/src/core/constraints.jl b/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*}
 ```
 """
@@ -413,5 +412,7 @@ p_t \\le \\text{ActivePowerTimeSeriesParameter}_t, \\quad \\forall t \\in \\{1,\
 """
 struct ActivePowerVariableTimeSeriesLimitsConstraint <: PowerVariableLimitsConstraint end
 
+struct LineFlowBoundConstraint <: ConstraintType end
+
 abstract type EventConstraint <: ConstraintType end
 struct OutageConstraint <: EventConstraint end
diff --git a/src/core/definitions.jl b/src/core/definitions.jl
@@ -15,6 +15,15 @@ const GAE = JuMP.GenericAffExpr{Float64, JuMP.VariableRef}
 const JuMPAffineExpressionArray = Matrix{GAE}
 const JuMPAffineExpressionVector = Vector{GAE}
 const JuMPConstraintArray = DenseAxisArray{JuMP.ConstraintRef}
+const JuMPAffineExpressionDArray = JuMP.Containers.DenseAxisArray{
+    JuMP.AffExpr,
+    2,
+    Tuple{Vector{Int64}, UnitRange{Int64}},
+    Tuple{
+        JuMP.Containers._AxisLookup{Dict{Int64, Int64}},
+        JuMP.Containers._AxisLookup{Tuple{Int64, Int64}},
+    },
+}
 const JuMPVariableMatrix = DenseAxisArray{
     JuMP.VariableRef,
     2,

diff --git a/src/core/expressions.jl b/src/core/expressions.jl
@@ -13,6 +13,7 @@ struct ActivePowerRangeExpressionUB <: RangeConstraintUBExpressions end
 struct ComponentReserveUpBalanceExpression <: ExpressionType end
 struct ComponentReserveDownBalanceExpression <: ExpressionType end
 struct InterfaceTotalFlow <: ExpressionType end
+struct PTDFBranchFlow <: ExpressionType end
 
 should_write_resulting_value(::Type{<:CostExpressions}) = true
 should_write_resulting_value(::Type{InterfaceTotalFlow}) = true

diff --git a/src/core/formulations.jl b/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

diff --git a/src/core/network_model.jl b/src/core/network_model.jl
@@ -35,6 +35,7 @@ mutable struct NetworkModel{T <: PM.AbstractPowerModel}
     radial_network_reduction::PNM.RadialNetworkReduction
     reduce_radial_branches::Bool
     subsystem::Union{Nothing, String}
+    modeled_branch_types::Vector{DataType}
 
     function NetworkModel(
         ::Type{T};
@@ -54,6 +55,7 @@ mutable struct NetworkModel{T <: PM.AbstractPowerModel}
             PNM.RadialNetworkReduction(),
             reduce_radial_branches,
             nothing,
+            Vector{DataType}(),
         )
     end
 end
@@ -118,7 +120,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 +145,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)