API Reference

read(path::AbstractString)::UnitCommitmentInstance

Read a unit commitment instance from a file. The file may be gzipped.

Example

import UnitCommitment
instance = UnitCommitment.read("/path/to/input.json.gz")

read_benchmark(name::AbstractString)::UnitCommitmentInstance

Read one of the benchmark unit commitment instances included in the package. See "Instances" section of the documentation for the entire list of benchmark instances available.

Example

import UnitCommitment
instance = UnitCommitment.read_benchmark("matpower/case3375wp/2017-02-01")

function build_model(;
    instance::UnitCommitmentInstance,
    optimizer = nothing,
    variable_names::Bool = false,
)::JuMP.Model

Build the JuMP model corresponding to the given unit commitment instance.

Arguments

• instance: the instance.
• optimizer: the optimizer factory that should be attached to this model (e.g. Cbc.Optimizer). If not provided, no optimizer will be attached.
• variable_names: If true, set variable and constraint names. Important if the model is going to be exported to an MPS file. For large models, this can take significant time, so it's disabled by default.

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.

validate(instance, solution)::Bool

Verifies that the given solution is feasible for the problem. If feasible, silently returns true. In infeasible, returns false and prints the validation errors to the screen.

This function is implemented independently from the optimization model in model.jl, and therefore can be used to verify that the model is indeed producing valid solutions. It can also be used to verify the solutions produced by other optimization packages.

slice(instance, range)

Creates a new instance, with only a subset of the time periods. This function does not modify the provided instance. The initial conditions are also not modified.

Example

# Build a 2-hour UC instance
instance = UnitCommitment.read_benchmark("test/case14")
modified = UnitCommitment.slice(instance, 1:2)

function randomize!(
    instance::UnitCommitment.UnitCommitmentInstance,
    method::XavQiuAhm2021.Randomization,
    rng = MersenneTwister(),
)::Nothing

Randomize costs and loads based on the method described in XavQiuAhm2021.

Formulation described in:

Arroyo, J. M., & Conejo, A. J. (2000). Optimal response of a thermal unit
to an electricity spot market. IEEE Transactions on power systems, 15(3), 
1098-1104. DOI: https://doi.org/10.1109/59.871739

Formulation described in:

Carrión, M., & Arroyo, J. M. (2006). A computationally efficient
mixed-integer linear formulation for the thermal unit commitment problem.
IEEE Transactions on power systems, 21(3), 1371-1378.
DOI: https://doi.org/10.1109/TPWRS.2006.876672

Formulation described in:

Damcı-Kurt, P., Küçükyavuz, S., Rajan, D., & Atamtürk, A. (2016). A polyhedral
study of production ramping. Mathematical Programming, 158(1), 175-205.
DOI: https://doi.org/10.1007/s10107-015-0919-9

Formulation described in:

Garver, L. L. (1962). Power generation scheduling by integer
programming-development of theory. Transactions of the American Institute
of Electrical Engineers. Part III: Power Apparatus and Systems, 81(3), 730-734.
DOI: https://doi.org/10.1109/AIEEPAS.1962.4501405

Formulation described in:

Knueven, B., Ostrowski, J., & Watson, J. P. (2018). Exploiting identical
generators in unit commitment. IEEE Transactions on Power Systems, 33(4),
4496-4507. DOI: https://doi.org/10.1109/TPWRS.2017.2783850

Formulation described in:

Morales-España, G., Latorre, J. M., & Ramos, A. (2013). Tight and compact
MILP formulation for the thermal unit commitment problem. IEEE Transactions
on Power Systems, 28(4), 4897-4908. DOI: https://doi.org/10.1109/TPWRS.2013.2251373

Formulation described in:

Pan, K., & Guan, Y. (2016). Strong formulations for multistage stochastic
self-scheduling unit commitment. Operations Research, 64(6), 1482-1498.
DOI: https://doi.org/10.1287/opre.2016.1520

Formulation described in:

B. Wang and B. F. Hobbs, "Real-Time Markets for Flexiramp: A Stochastic 
Unit Commitment-Based Analysis," in IEEE Transactions on Power Systems, 
vol. 31, no. 2, pp. 846-860, March 2016, doi: 10.1109/TPWRS.2015.2411268.

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.
DOI: https://doi.org/10.1109/TPWRS.2019.2892620

mutable struct Method
    time_limit::Float64
    gap_limit::Float64
    two_phase_gap::Bool
    max_violations_per_line::Int
    max_violations_per_period::Int
end

Fields

• time_limit: the time limit over the entire optimization procedure.
• gap_limit: the desired relative optimality gap. Only used when two_phase_gap=true.
• 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.
• max_violations_per_line: maximum number of violated transmission constraints to add to the formulation per transmission line.
• max_violations_per_period: maximum number of violated transmission constraints to add to the formulation per time period.

Methods described in:

Xavier, Álinson S., Feng Qiu, and Shabbir Ahmed. "Learning to solve
large-scale security-constrained unit commitment problems." INFORMS
Journal on Computing 33.2 (2021): 739-756. DOI: 10.1287/ijoc.2020.0976

struct Randomization
    cost = Uniform(0.95, 1.05)
    load_profile_mu = [...]
    load_profile_sigma = [...]
    load_share = Uniform(0.90, 1.10)
    peak_load = Uniform(0.6 * 0.925, 0.6 * 1.075)
    randomize_costs = true
    randomize_load_profile = true
    randomize_load_share = true
end

Randomization method that changes: (1) production and startup costs, (2) share of load coming from each bus, (3) peak system load, and (4) temporal load profile, as follows:

1. Production and startup costs: For each unit u, the vectors u.min_power_cost and u.cost_segments are multiplied by a constant α[u] sampled from the provided cost distribution. If randomize_costs is false, skips this step.

2. Load share: For each bus b and time t, the value b.load[t] is multiplied by (β[b] * b.load[t]) / sum(β[b2] * b2.load[t] for b2 in buses), where β[b] is sampled from the provided load_share distribution. If randomize_load_share is false, skips this step.

3. Peak system load and temporal load profile: Sets the peak load to ρ * C, where ρ is sampled from peak_load and C is the maximum system capacity, at any time. Also scales the loads of all buses, so that system_load[t+1] becomes equal to system_load[t] * γ[t], where γ[t] is sampled from Normal(load_profile_mu[t], load_profile_sigma[t]).

   The system load for the first time period is set so that the peak load matches ρ * C. If load_profile_sigma and load_profile_mu have fewer elements than instance.time, wraps around. If randomize_load_profile is false, skips this step.

The default parameters were obtained based on an analysis of publicly available bid and hourly data from PJM, corresponding to the month of January, 2017. For more details, see Section 4.2 of the paper.