# API Reference

## Read data, build model & optimize

`UnitCommitment.read` — Function

    read(path::AbstractString)::UnitCommitmentInstance

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

Example

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

source
`UnitCommitment.read_benchmark` — Function

    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")

source
`UnitCommitment.build_model` — Function

    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,
            ),
        ),
    )

source
`UnitCommitment.optimize!` — 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.

source
`UnitCommitment.solution` — Function

    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)

source
`UnitCommitment.validate` — Function

    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.

source
`UnitCommitment.write` — Function

    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)

source

## Modify instance

`UnitCommitment.slice` — Function

    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)

source
`UnitCommitment.randomize!` — Method

    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)

source
`UnitCommitment.generate_initial_conditions!` — Function

    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.

source

## Formulations

`UnitCommitment.Formulation` — Type

    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

source
`UnitCommitment.ShiftFactorsFormulation` — Type

    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.

source
`UnitCommitment.ArrCon2000` — Module

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

source
`UnitCommitment.CarArr2006` — Module

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

source
`UnitCommitment.DamKucRajAta2016` — Module

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

source
`UnitCommitment.Gar1962` — Module

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

source
`UnitCommitment.KnuOstWat2018` — Module

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

source
`UnitCommitment.MorLatRam2013` — Module

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

source
`UnitCommitment.PanGua2016` — Module

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

source
`UnitCommitment.WanHob2016` — Module

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.

source

## Solution Methods

`UnitCommitment.XavQiuWanThi2019.Method` — Type

    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.

source

## Randomization Methods

`UnitCommitment.XavQiuAhm2021.Randomization` — Type

    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

source

Theme

This document was generated with Documenter.jl version 0.27.21 on Monday 18 July 2022. Using Julia version 1.7.3.