Reorganize files; document some methods

src/solution/fix.jl

@@ -0,0 +1,33 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+"""
+    fix!(model::JuMP.Model, solution::AbstractDict)::Nothing
+
+Fix the value of all binary variables to the ones specified by the given
+solution. Useful for computing LMPs.
+"""
+function fix!(model::JuMP.Model, solution::AbstractDict)::Nothing
+    instance, T = model[:instance], model[:instance].time
+    is_on = model[:is_on]
+    prod_above = model[:prod_above]
+    reserve = model[:reserve]
+    for g in instance.units
+        for t in 1:T
+            is_on_value = round(solution["Is on"][g.name][t])
+            production_value =
+                round(solution["Production (MW)"][g.name][t], digits = 5)
+            reserve_value =
+                round(solution["Reserve (MW)"][g.name][t], digits = 5)
+            JuMP.fix(is_on[g.name, t], is_on_value, force = true)
+            JuMP.fix(
+                prod_above[g.name, t],
+                production_value - is_on_value * g.min_power[t],
+                force = true,
+            )
+            JuMP.fix(reserve[g.name, t], reserve_value, force = true)
+        end
+    end
+    return
+end

src/solution/methods/XaQiWaTh19/enforce.jl

@@ -0,0 +1,83 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function _enforce_transmission(
+    model::JuMP.Model,
+    violations::Vector{_Violation},
+)::Nothing
+    for v in violations
+        _enforce_transmission(
+            model = model,
+            violation = v,
+            isf = model[:isf],
+            lodf = model[:lodf],
+        )
+    end
+    return
+end
+
+function _enforce_transmission(;
+    model::JuMP.Model,
+    violation::_Violation,
+    isf::Matrix{Float64},
+    lodf::Matrix{Float64},
+)::Nothing
+    instance = model[:instance]
+    limit::Float64 = 0.0
+    overflow = model[:overflow]
+    net_injection = model[:net_injection]
+
+    if violation.outage_line === nothing
+        limit = violation.monitored_line.normal_flow_limit[violation.time]
+        @info @sprintf(
+            "    %8.3f MW overflow in %-5s time %3d (pre-contingency)",
+            violation.amount,
+            violation.monitored_line.name,
+            violation.time,
+        )
+    else
+        limit = violation.monitored_line.emergency_flow_limit[violation.time]
+        @info @sprintf(
+            "    %8.3f MW overflow in %-5s time %3d (outage: line %s)",
+            violation.amount,
+            violation.monitored_line.name,
+            violation.time,
+            violation.outage_line.name,
+        )
+    end
+
+    fm = violation.monitored_line.name
+    t = violation.time
+    flow = @variable(model, base_name = "flow[$fm,$t]")
+
+    v = overflow[violation.monitored_line.name, violation.time]
+    @constraint(model, flow <= limit + v)
+    @constraint(model, -flow <= limit + v)
+
+    if violation.outage_line === nothing
+        @constraint(
+            model,
+            flow == sum(
+                net_injection[b.name, violation.time] *
+                isf[violation.monitored_line.offset, b.offset] for
+                b in instance.buses if b.offset > 0
+            )
+        )
+    else
+        @constraint(
+            model,
+            flow == sum(
+                net_injection[b.name, violation.time] * (
+                    isf[violation.monitored_line.offset, b.offset] + (
+                        lodf[
+                            violation.monitored_line.offset,
+                            violation.outage_line.offset,
+                        ] * isf[violation.outage_line.offset, b.offset]
+                    )
+                ) for b in instance.buses if b.offset > 0
+            )
+        )
+    end
+    return nothing
+end

src/solution/methods/XaQiWaTh19/filter.jl

@@ -0,0 +1,44 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function _offer(filter::_ViolationFilter, v::_Violation)::Nothing
+    if v.monitored_line.offset ∉ keys(filter.queues)
+        filter.queues[v.monitored_line.offset] =
+            PriorityQueue{_Violation,Float64}()
+    end
+    q::PriorityQueue{_Violation,Float64} =
+        filter.queues[v.monitored_line.offset]
+    if length(q) < filter.max_per_line
+        enqueue!(q, v => v.amount)
+    else
+        if v.amount > peek(q)[1].amount
+            dequeue!(q)
+            enqueue!(q, v => v.amount)
+        end
+    end
+    return nothing
+end
+
+function _query(filter::_ViolationFilter)::Array{_Violation,1}
+    violations = Array{_Violation,1}()
+    time_queue = PriorityQueue{_Violation,Float64}()
+    for l in keys(filter.queues)
+        line_queue = filter.queues[l]
+        while length(line_queue) > 0
+            v = dequeue!(line_queue)
+            if length(time_queue) < filter.max_total
+                enqueue!(time_queue, v => v.amount)
+            else
+                if v.amount > peek(time_queue)[1].amount
+                    dequeue!(time_queue)
+                    enqueue!(time_queue, v => v.amount)
+                end
+            end
+        end
+    end
+    while length(time_queue) > 0
+        violations = [violations; dequeue!(time_queue)]
+    end
+    return violations
+end

src/solution/methods/XaQiWaTh19/find.jl

@@ -0,0 +1,177 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+import Base.Threads: @threads
+
+function _find_violations(
+    model::JuMP.Model;
+    max_per_line::Int,
+    max_per_period::Int,
+)
+    instance = model[:instance]
+    net_injection = model[:net_injection]
+    overflow = model[:overflow]
+    length(instance.buses) > 1 || return []
+    violations = []
+    @info "Verifying transmission limits..."
+    time_screening = @elapsed begin
+        non_slack_buses = [b for b in instance.buses if b.offset > 0]
+        net_injection_values = [
+            value(net_injection[b.name, t]) for b in non_slack_buses,
+            t in 1:instance.time
+        ]
+        overflow_values = [
+            value(overflow[lm.name, t]) for lm in instance.lines,
+            t in 1:instance.time
+        ]
+        violations = UnitCommitment._find_violations(
+            instance = instance,
+            net_injections = net_injection_values,
+            overflow = overflow_values,
+            isf = model[:isf],
+            lodf = model[:lodf],
+            max_per_line = max_per_line,
+            max_per_period = max_per_period,
+        )
+    end
+    @info @sprintf(
+        "Verified transmission limits in %.2f seconds",
+        time_screening
+    )
+    return violations
+end
+
+"""
+    function _find_violations(
+        instance::UnitCommitmentInstance,
+        net_injections::Array{Float64, 2};
+        isf::Array{Float64,2},
+        lodf::Array{Float64,2},
+        max_per_line::Int,
+        max_per_period::Int,
+    )::Array{_Violation, 1}
+
+Find transmission constraint violations (both pre-contingency, as well as
+post-contingency).
+
+The argument `net_injection` should be a (B-1) x T matrix, where B is the
+number of buses and T is the number of time periods. The arguments `isf` and
+`lodf` can be computed using UnitCommitment.injection_shift_factors and
+UnitCommitment.line_outage_factors. The argument `overflow` specifies how much
+flow above the transmission limits (in MW) is allowed. It should be an L x T
+matrix, where L is the number of transmission lines.
+"""
+function _find_violations(;
+    instance::UnitCommitmentInstance,
+    net_injections::Array{Float64,2},
+    overflow::Array{Float64,2},
+    isf::Array{Float64,2},
+    lodf::Array{Float64,2},
+    max_per_line::Int,
+    max_per_period::Int,
+)::Array{_Violation,1}
+    B = length(instance.buses) - 1
+    L = length(instance.lines)
+    T = instance.time
+    K = nthreads()
+
+    size(net_injections) == (B, T) || error("net_injections has incorrect size")
+    size(isf) == (L, B) || error("isf has incorrect size")
+    size(lodf) == (L, L) || error("lodf has incorrect size")
+
+    filters = Dict(
+        t => _ViolationFilter(
+            max_total = max_per_period,
+            max_per_line = max_per_line,
+        ) for t in 1:T
+    )
+
+    pre_flow::Array{Float64} = zeros(L, K)           # pre_flow[lm, thread]
+    post_flow::Array{Float64} = zeros(L, L, K)       # post_flow[lm, lc, thread]
+    pre_v::Array{Float64} = zeros(L, K)              # pre_v[lm, thread]
+    post_v::Array{Float64} = zeros(L, L, K)          # post_v[lm, lc, thread]
+
+    normal_limits::Array{Float64,2} = [
+        l.normal_flow_limit[t] + overflow[l.offset, t] for
+        l in instance.lines, t in 1:T
+    ]
+
+    emergency_limits::Array{Float64,2} = [
+        l.emergency_flow_limit[t] + overflow[l.offset, t] for
+        l in instance.lines, t in 1:T
+    ]
+
+    is_vulnerable::Array{Bool} = zeros(Bool, L)
+    for c in instance.contingencies
+        is_vulnerable[c.lines[1].offset] = true
+    end
+
+    @threads for t in 1:T
+        k = threadid()
+
+        # Pre-contingency flows
+        pre_flow[:, k] = isf * net_injections[:, t]
+
+        # Post-contingency flows
+        for lc in 1:L, lm in 1:L
+            post_flow[lm, lc, k] =
+                pre_flow[lm, k] + pre_flow[lc, k] * lodf[lm, lc]
+        end
+
+        # Pre-contingency violations
+        for lm in 1:L
+            pre_v[lm, k] = max(
+                0.0,
+                pre_flow[lm, k] - normal_limits[lm, t],
+                -pre_flow[lm, k] - normal_limits[lm, t],
+            )
+        end
+
+        # Post-contingency violations
+        for lc in 1:L, lm in 1:L
+            post_v[lm, lc, k] = max(
+                0.0,
+                post_flow[lm, lc, k] - emergency_limits[lm, t],
+                -post_flow[lm, lc, k] - emergency_limits[lm, t],
+            )
+        end
+
+        # Offer pre-contingency violations
+        for lm in 1:L
+            if pre_v[lm, k] > 1e-5
+                _offer(
+                    filters[t],
+                    _Violation(
+                        time = t,
+                        monitored_line = instance.lines[lm],
+                        outage_line = nothing,
+                        amount = pre_v[lm, k],
+                    ),
+                )
+            end
+        end
+
+        # Offer post-contingency violations
+        for lm in 1:L, lc in 1:L
+            if post_v[lm, lc, k] > 1e-5 && is_vulnerable[lc]
+                _offer(
+                    filters[t],
+                    _Violation(
+                        time = t,
+                        monitored_line = instance.lines[lm],
+                        outage_line = instance.lines[lc],
+                        amount = post_v[lm, lc, k],
+                    ),
+                )
+            end
+        end
+    end
+
+    violations = _Violation[]
+    for t in 1:instance.time
+        append!(violations, _query(filters[t]))
+    end
+
+    return violations
+end

src/solution/methods/XaQiWaTh19/optimize.jl

@@ -0,0 +1,67 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+"""
+    optimize!(model::JuMP.Model, method::_XaQiWaTh19)::Nothing
+
+Solve the given unit commitment model, enforcing transmission and N-1
+security constraints lazily, according to the algorithm described in:
+
+    Xavier, A. S., Qiu, F., Wang, F., & Thimmapuram, P. R. (2019). Transmission
+    constraint filtering in large-scale security-constrained unit commitment. 
+    IEEE Transactions on Power Systems, 34(3), 2457-2460.
+"""
+function optimize!(model::JuMP.Model, method::_XaQiWaTh19)::Nothing
+    function set_gap(gap)
+        try
+            JuMP.set_optimizer_attribute(model, "MIPGap", gap)
+            @info @sprintf("MIP gap tolerance set to %f", gap)
+        catch
+            @warn "Could not change MIP gap tolerance"
+        end
+    end
+    instance = model[:instance]
+    initial_time = time()
+    large_gap = false
+    has_transmission = (length(model[:isf]) > 0)
+    if has_transmission && method.two_phase_gap
+        set_gap(1e-2)
+        large_gap = true
+    else
+        set_gap(method.gap_limit)
+    end
+    while true
+        time_elapsed = time() - initial_time
+        time_remaining = method.time_limit - time_elapsed
+        if time_remaining < 0
+            @info "Time limit exceeded"
+            break
+        end
+        @info @sprintf(
+            "Setting MILP time limit to %.2f seconds",
+            time_remaining
+        )
+        JuMP.set_time_limit_sec(model, time_remaining)
+        @info "Solving MILP..."
+        JuMP.optimize!(model)
+        has_transmission || break
+        violations = _find_violations(
+            model,
+            max_per_line = method.max_violations_per_line,
+            max_per_period = method.max_violations_per_period,
+        )
+        if isempty(violations)
+            @info "No violations found"
+            if large_gap
+                large_gap = false
+                set_gap(method.gap_limit)
+            else
+                break
+            end
+        else
+            _enforce_transmission(model, violations)
+        end
+    end
+    return
+end

src/solution/methods/XaQiWaTh19/structs.jl

@@ -0,0 +1,78 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+import DataStructures: PriorityQueue
+
+"""
+    struct _XaQiWaTh19 <: SolutionMethod
+        time_limit::Float64
+        gap_limit::Float64
+        two_phase_gap::Bool
+    end
+
+Lazy constraint solution method described in:
+
+    Xavier, A. S., Qiu, F., Wang, F., & Thimmapuram, P. R. (2019). Transmission
+    constraint filtering in large-scale security-constrained unit commitment. 
+    IEEE Transactions on Power Systems, 34(3), 2457-2460.
+
+Fields
+=========
+- `time_limit`:
+    the time limit over the entire optimization procedure.
+- `gap_limit`: 
+    the desired relative optimality gap.
+- `two_phase_gap`: 
+    if true, solve the problem with large gap tolerance first, then reduce
+    the gap tolerance when no further violated constraints are found.
+"""
+struct _XaQiWaTh19
+    time_limit::Float64
+    gap_limit::Float64
+    two_phase_gap::Bool
+    max_violations_per_line::Int
+    max_violations_per_period::Int
+
+    function _XaQiWaTh19(;
+        time_limit::Float64,
+        gap_limit::Float64,
+        two_phase_gap::Bool,
+        max_violations_per_line::Int,
+        max_violations_per_period::Int,
+    )
+        return new(
+            time_limit,
+            gap_limit,
+            two_phase_gap,
+            max_violations_per_line,
+            max_violations_per_period,
+        )
+    end
+end
+
+struct _Violation
+    time::Int
+    monitored_line::TransmissionLine
+    outage_line::Union{TransmissionLine,Nothing}
+    amount::Float64
+
+    function _Violation(;
+        time::Int,
+        monitored_line::TransmissionLine,
+        outage_line::Union{TransmissionLine,Nothing},
+        amount::Float64,
+    )
+        return new(time, monitored_line, outage_line, amount)
+    end
+end
+
+mutable struct _ViolationFilter
+    max_per_line::Int
+    max_total::Int
+    queues::Dict{Int,PriorityQueue{_Violation,Float64}}
+
+    function _ViolationFilter(; max_per_line::Int = 1, max_total::Int = 5)
+        return new(max_per_line, max_total, Dict())
+    end
+end

src/solution/optimize.jl

@@ -0,0 +1,23 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+"""
+    function optimize!(model::JuMP.Model)::Nothing
+
+Solve the given unit commitment model. Unlike JuMP.optimize!, this uses more
+advanced methods to accelerate the solution process and to enforce transmission
+and N-1 security constraints.
+"""
+function optimize!(model::JuMP.Model)::Nothing
+    return UnitCommitment.optimize!(
+        model,
+        _XaQiWaTh19(
+            time_limit = 3600.0,
+            gap_limit = 1e-4,
+            two_phase_gap = true,
+            max_violations_per_line = 1,
+            max_violations_per_period = 5,
+        ),
+    )
+end

src/solution/solution.jl

@@ -0,0 +1,65 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function solution(model::JuMP.Model)::OrderedDict
+    instance, T = model[:instance], model[:instance].time
+    function timeseries(vars, collection)
+        return OrderedDict(
+            b.name => [round(value(vars[b.name, t]), digits = 5) for t in 1:T]
+            for b in collection
+        )
+    end
+    function production_cost(g)
+        return [
+            value(model[:is_on][g.name, t]) * g.min_power_cost[t] + sum(
+                Float64[
+                    value(model[:segprod][g.name, t, k]) *
+                    g.cost_segments[k].cost[t] for
+                    k in 1:length(g.cost_segments)
+                ],
+            ) for t in 1:T
+        ]
+    end
+    function production(g)
+        return [
+            value(model[:is_on][g.name, t]) * g.min_power[t] + sum(
+                Float64[
+                    value(model[:segprod][g.name, t, k]) for
+                    k in 1:length(g.cost_segments)
+                ],
+            ) for t in 1:T
+        ]
+    end
+    function startup_cost(g)
+        S = length(g.startup_categories)
+        return [
+            sum(
+                g.startup_categories[s].cost *
+                value(model[:startup][g.name, t, s]) for s in 1:S
+            ) for t in 1:T
+        ]
+    end
+    sol = OrderedDict()
+    sol["Production (MW)"] =
+        OrderedDict(g.name => production(g) for g in instance.units)
+    sol["Production cost (\$)"] =
+        OrderedDict(g.name => production_cost(g) for g in instance.units)
+    sol["Startup cost (\$)"] =
+        OrderedDict(g.name => startup_cost(g) for g in instance.units)
+    sol["Is on"] = timeseries(model[:is_on], instance.units)
+    sol["Switch on"] = timeseries(model[:switch_on], instance.units)
+    sol["Switch off"] = timeseries(model[:switch_off], instance.units)
+    sol["Reserve (MW)"] = timeseries(model[:reserve], instance.units)
+    sol["Net injection (MW)"] =
+        timeseries(model[:net_injection], instance.buses)
+    sol["Load curtail (MW)"] = timeseries(model[:curtail], instance.buses)
+    if !isempty(instance.lines)
+        sol["Line overflow (MW)"] = timeseries(model[:overflow], instance.lines)
+    end
+    if !isempty(instance.price_sensitive_loads)
+        sol["Price-sensitive loads (MW)"] =
+            timeseries(model[:loads], instance.price_sensitive_loads)
+    end
+    return sol
+end

src/solution/structs.jl

@@ -0,0 +1,5 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+abstract type SolutionMethod end

src/solution/warmstart.jl

@@ -0,0 +1,24 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function set_warm_start!(model::JuMP.Model, solution::AbstractDict)::Nothing
+    instance, T = model[:instance], model[:instance].time
+    is_on = model[:is_on]
+    prod_above = model[:prod_above]
+    reserve = model[:reserve]
+    for g in instance.units
+        for t in 1:T
+            JuMP.set_start_value(is_on[g.name, t], solution["Is on"][g.name][t])
+            JuMP.set_start_value(
+                switch_on[g.name, t],
+                solution["Switch on"][g.name][t],
+            )
+            JuMP.set_start_value(
+                switch_off[g.name, t],
+                solution["Switch off"][g.name][t],
+            )
+        end
+    end
+    return
+end

src/solution/write.jl

@@ -0,0 +1,10 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function write(filename::AbstractString, solution::AbstractDict)::Nothing
+    open(filename, "w") do file
+        return JSON.print(file, solution, 2)
+    end
+    return
+end