API Reference
Read data, build model & optimize
UnitCommitment.read — Functionread(path::AbstractString)::UnitCommitmentInstanceRead a unit commitment instance from a file. The file may be gzipped.
Example
import UnitCommitment
-instance = UnitCommitment.read("/path/to/input.json.gz")UnitCommitment.read_benchmark — Functionread_benchmark(name::AbstractString)::UnitCommitmentInstanceRead 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")UnitCommitment.build_model — Functionfunction build_model(;
+API Reference · UnitCommitment.jl API Reference
Read data, build model & optimize
UnitCommitment.read — Functionread(path::AbstractString)::UnitCommitmentInstance
Read instance from a file. The file may be gzipped.
Example
instance = UnitCommitment.read("/path/to/input.json.gz")
sourceUnitCommitment.read_benchmark — Functionread_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")
sourceUnitCommitment.build_model — Functionfunction 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.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.
sourceUnitCommitment.optimize! — Functionfunction 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.
sourceMissing docstring. Missing docstring for UnitCommitment.solution. Check Documenter's build log for details.
UnitCommitment.validate — Functionvalidate(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.
sourceMissing docstring. Missing docstring for UnitCommitment.write. Check Documenter's build log for details.
Modify instance
UnitCommitment.slice — Functionslice(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)
sourceUnitCommitment.randomize! — Functionfunction randomize!(
- instance::UnitCommitment.UnitCommitmentInstance,
- method::XavQiuAhm2021.Randomization,
+)::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,
+ ),
+ ),
+)
sourceUnitCommitment.optimize! — Functionoptimize!(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.
sourceUnitCommitment.solution — Functionsolution(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)
sourceUnitCommitment.validate — Functionvalidate(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.
sourceUnitCommitment.write — Functionwrite(filename::AbstractString, solution::AbstractDict)::Nothing
Write the given solution to a JSON file.
Example
solution = UnitCommitment.solution(model)
+UnitCommitment.write("/tmp/output.json", solution)
sourceModify instance
UnitCommitment.slice — Functionslice(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)
sourceUnitCommitment.randomize! — Methodfunction randomize!(
+ instance::UnitCommitmentInstance;
+ method = UnitCommitment.XavQiuAhm2021.Randomization();
rng = MersenneTwister(),
-)::Nothing
Randomize costs and loads based on the method described in XavQiuAhm2021.
sourceMissing docstring. Missing docstring for generate_initial_conditions!. Check Documenter's build log for details.
Formulations
UnitCommitment.ArrCon2000 — ModuleFormulation described in:
Arroyo, J. M., & Conejo, A. J. (2000). Optimal response of a thermal unit
+)::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)
sourceUnitCommitment.generate_initial_conditions! — Functiongenerate_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.
sourceFormulations
UnitCommitment.Formulation — Typestruct 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 variablespwl_costs: Formulation for the piecewise linear costsramping: Formulation for ramping constraintsstartup_costs: Formulation for time-dependent start-up costsstatus_vars: Formulation for the status variables (e.g. is_on, is_off)transmission: Formulation for transmission and N-1 security constraints
sourceUnitCommitment.ShiftFactorsFormulation — Typestruct 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.
sourceUnitCommitment.ArrCon2000 — ModuleFormulation 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
sourceUnitCommitment.CarArr2006 — ModuleFormulation described in:
Carrión, M., & Arroyo, J. M. (2006). A computationally efficient
+1098-1104. DOI: https://doi.org/10.1109/59.871739
sourceUnitCommitment.CarArr2006 — ModuleFormulation 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
sourceUnitCommitment.DamKucRajAta2016 — ModuleFormulation described in:
Damcı-Kurt, P., Küçükyavuz, S., Rajan, D., & Atamtürk, A. (2016). A polyhedral
+DOI: https://doi.org/10.1109/TPWRS.2006.876672
sourceUnitCommitment.DamKucRajAta2016 — ModuleFormulation 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
sourceUnitCommitment.Gar1962 — ModuleFormulation described in:
Garver, L. L. (1962). Power generation scheduling by integer
+DOI: https://doi.org/10.1007/s10107-015-0919-9
sourceUnitCommitment.Gar1962 — ModuleFormulation 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
sourceUnitCommitment.KnuOstWat2018 — ModuleFormulation described in:
Knueven, B., Ostrowski, J., & Watson, J. P. (2018). Exploiting identical
+DOI: https://doi.org/10.1109/AIEEPAS.1962.4501405
sourceUnitCommitment.KnuOstWat2018 — ModuleFormulation 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
sourceUnitCommitment.MorLatRam2013 — ModuleFormulation described in:
Morales-España, G., Latorre, J. M., & Ramos, A. (2013). Tight and compact
+4496-4507. DOI: https://doi.org/10.1109/TPWRS.2017.2783850
sourceUnitCommitment.MorLatRam2013 — ModuleFormulation 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
sourceUnitCommitment.PanGua2016 — ModuleFormulation described in:
Pan, K., & Guan, Y. (2016). Strong formulations for multistage stochastic
+on Power Systems, 28(4), 4897-4908. DOI: https://doi.org/10.1109/TPWRS.2013.2251373
sourceUnitCommitment.PanGua2016 — ModuleFormulation 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
sourceUnitCommitment.WanHob2016 — ModuleFormulation described in:
B. Wang and B. F. Hobbs, "Real-Time Markets for Flexiramp: A Stochastic
+DOI: https://doi.org/10.1287/opre.2016.1520
sourceUnitCommitment.WanHob2016 — ModuleFormulation 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.
sourceSolution Methods
UnitCommitment.XavQiuWanThi2019 — ModuleLazy 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
sourceUnitCommitment.XavQiuWanThi2019.Method — Typemutable struct Method
+vol. 31, no. 2, pp. 846-860, March 2016, doi: 10.1109/TPWRS.2015.2411268.
sourceSolution Methods
UnitCommitment.XavQiuWanThi2019.Method — Typemutable 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.
sourceRandomization Methods
UnitCommitment.XavQiuAhm2021 — ModuleMethods 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
sourceUnitCommitment.XavQiuAhm2021.Randomization — Typestruct Randomization
+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.
sourceRandomization Methods
UnitCommitment.XavQiuAhm2021.Randomization — Typestruct Randomization
cost = Uniform(0.95, 1.05)
load_profile_mu = [...]
load_profile_sigma = [...]
@@ -49,4 +84,4 @@ Journal on Computing 33.2 (2021): 739-756. DOI: 10.1287/ijoc.2020.0976
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:
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.
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.
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.
sourceSettings
This document was generated with Documenter.jl version 0.27.21 on Sunday 17 July 2022. Using Julia version 1.7.3.
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:
Production and startup costs: For each unit
u, the vectorsu.min_power_costandu.cost_segmentsare multiplied by a constantα[u]sampled from the providedcostdistribution. Ifrandomize_costsis false, skips this step.Load share: For each bus
band timet, the valueb.load[t]is multiplied by(β[b] * b.load[t]) / sum(β[b2] * b2.load[t] for b2 in buses), whereβ[b]is sampled from the providedload_sharedistribution. Ifrandomize_load_shareis false, skips this step.Peak system load and temporal load profile: Sets the peak load to
ρ * C, whereρis sampled frompeak_loadandCis the maximum system capacity, at any time. Also scales the loads of all buses, so thatsystem_load[t+1]becomes equal tosystem_load[t] * γ[t], whereγ[t]is sampled fromNormal(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. Ifload_profile_sigmaandload_profile_muhave fewer elements thaninstance.time, wraps around. Ifrandomize_load_profileis 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