From 107337f6215501df8a940b801d7ad25fcd0989fc Mon Sep 17 00:00:00 2001 From: Alinson S Xavier Date: Wed, 2 Jun 2021 08:14:03 -0500 Subject: [PATCH] Remove _build_model; update docs --- README.md | 64 ++++++++++++++++++++++++++++++--- benchmark/benchmark.jl | 7 ++-- src/model/build.jl | 15 +------- test/model/formulations_test.jl | 2 +- 4 files changed, 65 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 032bf2b..bc9fce8 100755 --- a/README.md +++ b/README.md @@ -11,21 +11,75 @@ - +

-**UnitCommitment.jl** (UC.jl) is an optimization package for the Security-Constrained Unit Commitment Problem (SCUC), a fundamental optimization problem in power systems used, for example, to clear the day-ahead electricity markets. The package provides benchmark instances for the problem and JuMP implementations of state-of-the-art mixed-integer programming formulations. +**UnitCommitment.jl** (UC.jl) is an optimization package for the Security-Constrained Unit Commitment Problem (SCUC), a fundamental optimization problem in power systems used, for example, to clear the day-ahead electricity markets. The package provides benchmark instances for the problem and Julia/JuMP implementations of state-of-the-art mixed-integer programming formulations. ## Package Components * **Data Format:** The package proposes an extensible and fully-documented JSON-based data specification format for SCUC, developed in collaboration with Independent System Operators (ISOs), which describes the most important aspects of the problem. The format supports all the most common generator characteristics (including ramping, piecewise-linear production cost curves and time-dependent startup costs), as well as operating reserves, price-sensitive loads, transmission networks and contingencies. -* **Benchmark Instances:** The package provides a diverse collection of large-scale benchmark instances collected from the literature and extended to make them more challenging and realistic. -* **Model Implementation**: The package provides a Julia/JuMP implementation of state-of-the-art formulations and solution methods for SCUC. Our goal is to keep this implementation up-to-date, as new methods are proposed in the literature. +* **Benchmark Instances:** The package provides a diverse collection of large-scale benchmark instances collected from the literature, converted into a common data format, and extended using data-driven methods to make them more challenging and realistic. +* **Model Implementation**: The package provides a Julia/JuMP implementations of state-of-the-art formulations and solution methods for SCUC, including multiple ramping formulations (*ArrCon2000*, *MorLatRam2013*, *DamKucRajAta2016*, *PanGua2016*), multiple piecewise-linear costs formulations (*Gar1962*, *CarArr2006*, *KnuOstWat2018*) and contingency screening methods (*XavQiuWanThi2019*). Our goal is to keep these implementation up-to-date as new methods are proposed in the literature. * **Benchmark Tools:** The package provides automated benchmark scripts to accurately evaluate the performance impact of proposed code changes. +## Sample Usage + +```julia +using Cbc +using JuMP +using UnitCommitment + +import UnitCommitment: + Formulation, + KnuOstWat2018, + MorLatRam2013, + ShiftFactorsFormulation + +# 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, + ), + ), +) + +# Modify the model (e.g. add custom constraints) +@constraint( + model, + model[:is_on]["g3",1] + model[:is_on]["g4",1] <= 1, +) + +# Solve model +UnitCommitment.optimize!(model) + +# Extract solution +solution = UnitCommitment.solution(model) +UnitCommitment.write("/tmp/output.json", solution) +``` + ## Documentation -For installation instructions and basic usage, see the [official documentation](https://anl-ceeesa.github.io/UnitCommitment.jl/). +1. [Usage](https://anl-ceeesa.github.io/UnitCommitment.jl/0.2/usage/) +2. [Data Format](https://anl-ceeesa.github.io/UnitCommitment.jl/0.2/format/) +3. [Instances](https://anl-ceeesa.github.io/UnitCommitment.jl/0.2/instances/) +4. [JuMP Model](https://anl-ceeesa.github.io/UnitCommitment.jl/0.2/model/) ## Authors * **Alinson Santos Xavier** (Argonne National Laboratory) diff --git a/benchmark/benchmark.jl b/benchmark/benchmark.jl index 22457c3..212a55b 100644 --- a/benchmark/benchmark.jl +++ b/benchmark/benchmark.jl @@ -70,6 +70,7 @@ function main() "tejada19/UC_168h_199g", ] formulations = Dict( + "Default" => Formulation(), "ArrCon2000" => Formulation(ramping = ArrCon2000.Ramping()), "CarArr2006" => Formulation(pwl_costs = CarArr2006.PwlCosts()), "DamKucRajAta2016" => @@ -123,9 +124,9 @@ end end @info @sprintf("Read problem in %.2f seconds", time_read) BLAS.set_num_threads(4) - model = UnitCommitment._build_model( - instance, - formulation, + model = UnitCommitment.build_model( + instance = instance, + formulation = formulation, optimizer = optimizer_with_attributes( Gurobi.Optimizer, "Threads" => 4, diff --git a/src/model/build.jl b/src/model/build.jl index 10decb3..87a9a66 100644 --- a/src/model/build.jl +++ b/src/model/build.jl @@ -29,20 +29,7 @@ Arguments function build_model(; instance::UnitCommitmentInstance, optimizer = nothing, - variable_names::Bool = false, -)::JuMP.Model - return _build_model( - instance, - Formulation(), - optimizer = optimizer, - variable_names = variable_names, - ) -end - -function _build_model( - instance::UnitCommitmentInstance, - formulation::Formulation; - optimizer = nothing, + formulation = Formulation(), variable_names::Bool = false, )::JuMP.Model @info "Building model..." diff --git a/test/model/formulations_test.jl b/test/model/formulations_test.jl index 98a261b..5f3a7ff 100644 --- a/test/model/formulations_test.jl +++ b/test/model/formulations_test.jl @@ -15,7 +15,7 @@ import UnitCommitment: function _test(formulation::Formulation)::Nothing instance = UnitCommitment.read_benchmark("matpower/case118/2017-02-01") - UnitCommitment._build_model(instance, formulation) # should not crash + UnitCommitment.build_model(instance = instance, formulation = formulation) # should not crash return end