API Reference

read(path::AbstractString)::UnitCommitmentInstance

Read a deterministic test case from the given file. The file may be gzipped.

Example

instance = UnitCommitment.read("s1.json.gz")

read(path::Vector{String})::UnitCommitmentInstance

Read a stochastic unit commitment instance from the given files. Each file describes a scenario. The files may be gzipped.

Example

instance = UnitCommitment.read(["s1.json.gz", "s2.json.gz"])

read_benchmark(name::AbstractString)::UnitCommitmentInstance

Read one of the benchmark instances included in the package. See Instances for the entire list of benchmark instances available.

Example

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

function build_model(;
    instance::UnitCommitmentInstance,
    optimizer = nothing,
    formulation = Formulation(),
    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.
• formulation: the MIP formulation to use. By default, uses a formulation that combines modeling components from different publications that provides good performance across a wide variety of instances. An alternative formulation may also be provided.
• 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.

Examples

# Read benchmark instance
instance = UnitCommitment.read_benchmark("matpower/case118/2017-02-01")

# Construct model (using state-of-the-art defaults)
model = UnitCommitment.build_model(
    instance = instance,
    optimizer = Cbc.Optimizer,
)

# Construct model (using customized formulation)
model = UnitCommitment.build_model(
    instance = instance,
    optimizer = Cbc.Optimizer,
    formulation = Formulation(
        pwl_costs = KnuOstWat2018.PwlCosts(),
        ramping = MorLatRam2013.Ramping(),
        startup_costs = MorLatRam2013.StartupCosts(),
        transmission = ShiftFactorsFormulation(
            isf_cutoff = 0.005,
            lodf_cutoff = 0.001,
        ),
    ),
)

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.

solution(model::JuMP.Model)::OrderedDict

Extracts the optimal solution from the UC.jl model. The model must be solved beforehand.

Example

UnitCommitment.optimize!(model)
solution = UnitCommitment.solution(model)

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.

write(filename::AbstractString, solution::AbstractDict)::Nothing

Write the given solution to a JSON file.

Example

solution = UnitCommitment.solution(model)
UnitCommitment.write("/tmp/output.json", solution)

function compute_lmp(
    model::JuMP.Model,
    method::ConventionalLMP;
    optimizer,
)::OrderedDict{Tuple{String,String,Int},Float64}

Calculates conventional locational marginal prices of the given unit commitment instance. Returns a dictionary mapping (bus_name, time) to the marginal price.

Arguments

• model: the UnitCommitment model, must be solved before calling this function.

• method: the LMP method.

• optimizer: the optimizer for solving the LP problem.

Examples

using UnitCommitment
using HiGHS

import UnitCommitment: ConventionalLMP

# Read benchmark instance
instance = UnitCommitment.read_benchmark("matpower/case118/2018-01-01")

# Build the model
model = UnitCommitment.build_model(
    instance = instance,
    optimizer = HiGHS.Optimizer,
)

# Optimize the model
UnitCommitment.optimize!(model)

# Compute the LMPs using the conventional method
lmp = UnitCommitment.compute_lmp(
    model,
    ConventionalLMP(),
    optimizer = HiGHS.Optimizer,
)

# Access the LMPs
# Example: "s1" is the scenario name, "b1" is the bus name, 1 is the first time slot
@show lmp["s1", "b1", 1]

struct AELMP <: PricingMethod 
    allow_offline_participation::Bool = true
    consider_startup_costs::Bool = true
end

Approximate Extended LMPs.

Arguments

• allow_offline_participation: If true, offline assets are allowed to participate in pricing.
• consider_startup_costs: If true, the start-up costs are averaged over each unit production; otherwise the production costs stay the same.

function compute_lmp(
    model::JuMP.Model,
    method::AELMP;
    optimizer,
)::OrderedDict{Tuple{String,Int},Float64}

Calculates the approximate extended locational marginal prices of the given unit commitment instance.

The AELPM does the following three things:

1. It sets the minimum power output of each generator to zero
2. It averages the start-up cost over the offer blocks for each generator
3. It relaxes all integrality constraints

Returns a dictionary mapping (bus_name, time) to the marginal price.

WARNING: This approximation method is not fully developed. The implementation is based on MISO Phase I only.

1. It only supports Fast Start resources. More specifically, the minimum up/down time has to be zero.
2. The method does NOT support time-varying start-up costs.
3. An asset is considered offline if it is never on throughout all time periods.
4. The method does NOT support multiple scenarios.

Arguments

• model: the UnitCommitment model, must be solved before calling this function if offline participation is not allowed.

• method: the AELMP method.

• optimizer: the optimizer for solving the LP problem.

Examples

using UnitCommitment
using HiGHS

import UnitCommitment: AELMP

# Read benchmark instance
instance = UnitCommitment.read_benchmark("matpower/case118/2017-02-01")

# Build the model
model = UnitCommitment.build_model(
    instance = instance,
    optimizer = HiGHS.Optimizer,
)

# Optimize the model
UnitCommitment.optimize!(model)

# Compute the AELMPs
aelmp = UnitCommitment.compute_lmp(
    model,
    AELMP(
        allow_offline_participation = false,
        consider_startup_costs = true
    ),
    optimizer = HiGHS.Optimizer
)

# Access the AELMPs
# Example: "s1" is the scenario name, "b1" is the bus name, 1 is the first time slot
# Note: although scenario is supported, the query still keeps the scenario keys for consistency.
@show aelmp["s1", "b1", 1]

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("matpower/case118/2017-02-01")
modified = UnitCommitment.slice(instance, 1:2)

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

Randomizes instance parameters according to the provided randomization method.

Example

instance = UnitCommitment.read_benchmark("matpower/case118/2017-02-01")
UnitCommitment.randomize!(instance)
model = UnitCommitment.build_model(; instance)

generate_initial_conditions!(instance, optimizer)

Generates feasible initial conditions for the given instance, by constructing and solving a single-period mixed-integer optimization problem, using the given optimizer. The instance is modified in-place.

struct Formulation
    prod_vars::ProductionVarsFormulation
    pwl_costs::PiecewiseLinearCostsFormulation
    ramping::RampingFormulation
    startup_costs::StartupCostsFormulation
    status_vars::StatusVarsFormulation
    transmission::TransmissionFormulation
end

Struct provided to build_model that holds various formulation components.

Fields

• prod_vars: Formulation for the production decision variables
• pwl_costs: Formulation for the piecewise linear costs
• ramping: Formulation for ramping constraints
• startup_costs: Formulation for time-dependent start-up costs
• status_vars: Formulation for the status variables (e.g. is_on, is_off)
• transmission: Formulation for transmission and N-1 security constraints

struct ShiftFactorsFormulation <: TransmissionFormulation
    isf_cutoff::Float64 = 0.005
    lodf_cutoff::Float64 = 0.001
    precomputed_isf=nothing
    precomputed_lodf=nothing
end

Transmission formulation based on Injection Shift Factors (ISF) and Line Outage Distribution Factors (LODF). Constraints are enforced in a lazy way.

Arguments

• precomputed_isf: the injection shift factors matrix. If not provided, it will be computed.
• precomputed_lodf: the line outage distribution factors matrix. If not provided, it will be computed.
• isf_cutoff: the cutoff that should be applied to the ISF matrix. Entries with magnitude smaller than this value will be set to zero.
• lodf_cutoff: the cutoff that should be applied to the LODF matrix. Entries with magnitude smaller than this value will be set to zero.

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.

mutable struct Method
    time_limit::Float64
    gap_limit::Float64
    two_phase_gap::Bool
    max_violations_per_line::Int
    max_violations_per_period::Int
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.
DOI: https://doi.org/10.1109/TPWRS.2019.2892620

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.

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.

References

• 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