GitHub

Variables for Mathematical Programs

CommonOPF provides standard variables names so that the packages that build upon CommonOPF can leverage common results getters and VariableBounds.

Variable Containers

CommonOPF provides variable containers to standardize indexing across OPF models. The order of indexing is:

  1. var_symbol like :v
  2. bus_or_edge
  3. time_step
  4. phase in [1, 2, 3] (if MultiPhase model)

Single phase models

CommonOPF.add_time_vector_variables! — Function
add_time_vector_variables!(
    m::JuMP.AbstractModel, 
    net::Network{SinglePhase}, 
    var_symbol::Symbol, 
    indices::AbstractVector{T} 
) where {T}

Add variables to the m.obj_dict indexed on:

  1. var_symbol like :v
  2. indices, typically a Vector{String} for bus indices or a Vector{Tuple{String, String}} for edge indices (like ("bus1", "bus2"))
  3. timesteps in 1:net.Ntimesteps

For example, accessing the edge variable :sij one edge ("bus1", "bus2") voltage variable at time step 5 looks like:

m[:sij][("bus1", "bus2")][5]
source

Multiphase models

CommonOPF.multiphase_bus_variable_container — Function
multiphase_bus_variable_container(; default::DefaultType=missing)

Return a DefaultDict of DefaultDict with three key types for indexing variables on:

  1. AbstractString for bus names
  2. Int for time step
  3. AbstractVecOrMat for vectors or matrices of phase variables
source
CommonOPF.multiphase_edge_variable_container — Function
multiphase_edge_variable_container(; default::DefaultType=missing)

Return a DefaultDict of DefaultDict with three key types for indexing variables on:

  1. Tuple{String, String} for edge names
  2. Int for time step
  3. AbstractVecOrMat for vectors or matrices of phase variables
source

Variable Bounds

CommonOPF.VariableBounds — Type
struct VariableBounds

Limits for decision variables in mathematical programs. Upper and lower values can be specified for power, current, and voltage variables. The VariableBounds struct is attached to Network.bounds upon creation of the Network. 

mutable struct VariableBounds
    s_upper_real::Union{Real, Missing}
    s_lower_real::Union{Real, Missing}
    s_upper_imag::Union{Real, Missing}
    s_lower_imag::Union{Real, Missing}
    
    v_upper_mag::Union{Real, Missing}
    v_lower_mag::Union{Real, Missing}

    i_upper_mag::Union{Real, Missing}
    i_lower_mag::Union{Real, Missing}
end
source
CommonOPF.VariableBounds — Method
function VariableBounds(ntwk::Dict)

Check for the keys of the VariableBounds struct in the ntwk dictionary. Any missing bounds are set to missing.

source

Documenting Variables

CommonOPF provides a way to document model variables within the Network struct. See the CommonOPF.VariableInfo struct and the CommonOPF.print_var_info method below for details. As an example (and test) of the print_var_info method:

CommonOPF.print_var_info(net)
┌────────┬─────────────────────────────────────────────────────┬───────────────────┬─────────────────────┐
│ symbol │                                         description │             units │          dimensions │
├────────┼─────────────────────────────────────────────────────┼───────────────────┼─────────────────────┤
│    pij │              sending end real power from bus i to j │     RealPowerUnit │ (Edge, Time, Phase) │
├────────┼─────────────────────────────────────────────────────┼───────────────────┼─────────────────────┤
│     pj │               net bus injection real power on bus j │     RealPowerUnit │  (Bus, Time, Phase) │
├────────┼─────────────────────────────────────────────────────┼───────────────────┼─────────────────────┤
│    qij │ sending end ReactivePowerUnit power from bus i to j │     RealPowerUnit │ (Edge, Time, Phase) │
├────────┼─────────────────────────────────────────────────────┼───────────────────┼─────────────────────┤
│     qj │           net bus injection reactive power on bus j │ ReactivePowerUnit │  (Bus, Time, Phase) │
├────────┼─────────────────────────────────────────────────────┼───────────────────┼─────────────────────┤
│  vsqrd │                           voltage magnitude squared │          VoltUnit │  (Bus, Time, Phase) │
└────────┴─────────────────────────────────────────────────────┴───────────────────┴─────────────────────┘
CommonOPF.Units — Type
@enum Units begin
    AmpUnit
    VoltUnit
    TimeUnit
    ApparentPowerUnit
    ComplexPowerUnit
    ReactivePowerUnit
    RealPowerUnit
    RadiansUnit
end

Units acceptable for CommonOPF variables.

source
CommonOPF.Dimensions — Type
@enum Dimensions begin
    BusDimension
    EdgeDimension
    TimeDimension
    PhaseDimension
    PhaseMatrixDimension
    HermitianMatrixDimension
    RealReactiveDimension
    BusTerminalDimension
end

Dimensions for specifying variable and constraint indices in CommonOPF, i.e. how to access a variable or constraint in the JuMP.Model.obj_dict.

source
CommonOPF.print_var_info — Function
print_var_info(net::Network)

Print the variable info in net.var_info in a table like:

julia> print_var_info(net)
┌────────┬───────────────────────────┬──────────┬────────────────────┐
│ symbol │               description │    units │         dimensions │
├────────┼───────────────────────────┼──────────┼────────────────────┤
│  vsqrd │ voltage magnitude squared │ VoltUnit │ (Bus, Time, Phase) │
└────────┴───────────────────────────┴──────────┴────────────────────┘

Add values to Network.var_info like:

net.var_info[:vsqrd] = CommonOPF.VariableInfo(
    :vsqrd,
    "voltage magnitude squared",
    CommonOPF.VoltUnit,
    (CommonOPF.BusDimension, CommonOPF.TimeDimension, CommonOPF.PhaseDimension)
)
source