Improve sysimage.jl

Fix duplicated startup constraint

.github/workflows/test.yml

@@ -9,8 +9,8 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        julia-version: ['1.3', '1.4', '1.5', '1.6']
-        julia-arch: [x64, x86]
+        julia-version: ['1.4', '1.5', '1.6']
+        julia-arch: [x64]
         os: [ubuntu-latest, windows-latest, macOS-latest]
         exclude:
           - os: macOS-latest

.gitignore

@@ -8,6 +8,7 @@
 benchmark/results
 benchmark/runs
 benchmark/tables
+benchmark/tmp.json
 build
 instances/**/*.json
 instances/_source
@@ -17,3 +18,4 @@ TODO.md
 docs/_build
 .vscode
 Manifest.toml
+*/Manifest.toml

CHANGELOG.md

@@ -4,18 +4,29 @@ All notable changes to this project will be documented in this file.
 
 - The format is based on [Keep a Changelog][changelog].
 - This project adheres to [Semantic Versioning][semver].
-- For versions before 1.0, we follow [the Pkg.jl convention][pkjjl]
+- For versions before 1.0, we follow the [Pkg.jl convention][pkjjl]
   that `0.a.b` is compatible with `0.a.c`.
 
 [changelog]: https://keepachangelog.com/en/1.0.0/
 [semver]: https://semver.org/spec/v2.0.0.html
 [pkjjl]: https://pkgdocs.julialang.org/v1/compatibility/#compat-pre-1.0
 
+## [0.2.2] - 2021-07-21
+### Fixed
+- Fix small bug in validation scripts related to startup costs
+- Fix duplicated startup constraints (@mtanneau, #12)
+
+## [0.2.1] - 2021-06-02
+### Added
+- Add multiple ramping formulations (ArrCon2000, MorLatRam2013, DamKucRajAta2016, PanGua2016)
+- Add multiple piecewise-linear costs formulations (Garver1962, CarArr2006, KnuOstWat2018)
+- Allow benchmark scripts to compare multiple formulations
+
 ## [0.2.0] - 2021-05-28
 ### Added
 - Add sub-hourly unit commitment.
 - Add `UnitCommitment.write(filename, solution)`.
-- Add mathematical formulation to the documentation.
+- Add current mathematical formulation to the documentation.
 
 ### Changed
 - Rename "Time (h)" parameter to "Time horizon (h)".

Makefile

@@ -5,26 +5,23 @@
 JULIA := julia --color=yes --project=@.
 VERSION := 0.2
 
-build/sysimage.so: src/sysimage.jl Project.toml Manifest.toml
-	mkdir -p build
-	mkdir -p benchmark/results/test
-	cd benchmark; $(JULIA) --trace-compile=../build/precompile.jl run.jl test/case14.1.sol.json
-	$(JULIA) src/sysimage.jl
+build/sysimage.so: src/utils/sysimage.jl Project.toml
+	julia --project=. -e "using Pkg; Pkg.instantiate()"
+	julia --project=test -e "using Pkg; Pkg.instantiate()"
+	$(JULIA) src/utils/sysimage.jl test/runtests.jl
 
 clean:
-	rm -rf build/*
+	rm -rfv build
 
 docs:
 	cd docs; make clean; make dirhtml
 	rsync -avP --delete-after docs/_build/dirhtml/ ../docs/$(VERSION)/
 	
 test: build/sysimage.so
-	@echo Running tests...
-	$(JULIA) --sysimage build/sysimage.so -e 'using Pkg; Pkg.test("UnitCommitment")' | tee build/test.log
-
+	$(JULIA) --sysimage build/sysimage.so test/runtests.jl
 
 format:
-	julia -e 'using JuliaFormatter; format("src"); format("test"); format("benchmark")'
+	julia -e 'using JuliaFormatter; format(["src", "test", "benchmark"], verbose=true);'
 
 install-deps:
 	julia -e 'using Pkg; Pkg.add(PackageSpec(name="JuliaFormatter", version="0.14.4"))'

Project.toml

@@ -2,10 +2,11 @@ name = "UnitCommitment"
 uuid = "64606440-39ea-11e9-0f29-3303a1d3d877"
 authors = ["Santos Xavier, Alinson <axavier@anl.gov>"]
 repo = "https://github.com/ANL-CEEESA/UnitCommitment.jl"
-version = "0.2.0"
+version = "0.2.2"
 
 [deps]
 DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 GZip = "92fee26a-97fe-5a0c-ad85-20a5f3185b63"
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
@@ -14,21 +15,15 @@ Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
 MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
 PackageCompiler = "9b87118b-4619-50d2-8e1e-99f35a4d4d9d"
 Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 
 [compat]
-Cbc = "0.7"
 DataStructures = "0.18"
+Distributions = "0.25"
 GZip = "0.5"
 JSON = "0.21"
 JuMP = "0.21"
 MathOptInterface = "0.9"
 PackageCompiler = "1"
 julia = "1"
-
-[extras]
-Cbc = "9961bab8-2fa3-5c5a-9d89-47fab24efd76"
-Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
-
-[targets]
-test = ["Cbc", "Test"]

README.md

@@ -11,43 +11,134 @@
   </a>
   <a href="https://github.com/ANL-CEEESA/UnitCommitment.jl/discussions">
     <img src="https://img.shields.io/badge/GitHub-Discussions-%23fc4ebc" />
-  </a>  
+  </a>
 </p>
 
-**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
+## 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.
+* **Data Format:** The package proposes an extensible and fully-documented JSON-based data format for SCUC, developed in collaboration with Independent System Operators (ISOs), which describes the most important aspects of the problem. The format supports 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, converted into a common data format, and extended using data-driven methods to make them more challenging and realistic.
+* **Model Implementation**: The package provides Julia/JuMP implementations of state-of-the-art formulations and solution methods for SCUC, including multiple ramping formulations ([ArrCon2000][ArrCon2000], [MorLatRam2013][MorLatRam2013], [DamKucRajAta2016][DamKucRajAta2016], [PanGua2016][PanGua2016]), multiple piecewise-linear costs formulations ([Gar1962][Gar1962], [CarArr2006][CarArr2006], [KnuOstWat2018][KnuOstWat2018]) and contingency screening methods ([XavQiuWanThi2019][XavQiuWanThi2019]). Our goal is to keep these implementations 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.
 
-### Documentation
+[ArrCon2000]: https://doi.org/10.1109/59.871739
+[CarArr2006]: https://doi.org/10.1109/TPWRS.2006.876672
+[DamKucRajAta2016]: https://doi.org/10.1007/s10107-015-0919-9
+[Gar1962]: https://doi.org/10.1109/AIEEPAS.1962.4501405
+[KnuOstWat2018]: https://doi.org/10.1109/TPWRS.2017.2783850
+[MorLatRam2013]: https://doi.org/10.1109/TPWRS.2013.2251373
+[PanGua2016]: https://doi.org/10.1287/opre.2016.1520
+[XavQiuWanThi2019]: https://doi.org/10.1109/TPWRS.2019.2892620
 
-* [Usage](https://anl-ceeesa.github.io/UnitCommitment.jl/0.1/usage/)
-* [Data Format](https://anl-ceeesa.github.io/UnitCommitment.jl/0.1/format/)
-* [Instances](https://anl-ceeesa.github.io/UnitCommitment.jl/0.1/instances/)
+## Sample Usage
 
-### Authors
-* **Alinson Santos Xavier** (Argonne National Laboratory)
+```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
+
+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 S. Xavier** (Argonne National Laboratory)
+* **Aleksandr M. Kazachkov** (University of Florida)
 * **Feng Qiu** (Argonne National Laboratory)
 
-### Acknowledgments
+## Acknowledgments
 
-* We would like to thank **Aleksandr M. Kazachkov** (University of Florida), **Yonghong Chen** (Midcontinent Independent System Operator), **Feng Pan** (Pacific Northwest National Laboratory) for valuable feedback on early versions of this package.
+* We would like to **Yonghong Chen** (Midcontinent Independent System Operator), **Feng Pan** (Pacific Northwest National Laboratory) for valuable feedback on early versions of this package.
 
-* Based upon work supported by **Laboratory Directed Research and Development** (LDRD) funding from Argonne National Laboratory, provided by the Director, Office of Science, of the U.S. Department of Energy under Contract No. DE-AC02-06CH11357, and the U.S. Department of Energy **Advanced Grid Modeling Program** under Grant DE-OE0000875
+* Based upon work supported by **Laboratory Directed Research and Development** (LDRD) funding from Argonne National Laboratory, provided by the Director, Office of Science, of the U.S. Department of Energy under Contract No. DE-AC02-06CH11357
 
-### Citing
+* Based upon work supported by the **U.S. Department of Energy Advanced Grid Modeling Program** under Grant DE-OE0000875.
 
-If you use UnitCommitment.jl in your research, we request that you cite the package as follows:
+## Citing
 
-* **Alinson S. Xavier, Feng Qiu**. "UnitCommitment.jl: A Julia/JuMP Optimization Package for Security-Constrained Unit Commitment". Zenodo (2020). [DOI: 10.5281/zenodo.4269874](https://doi.org/10.5281/zenodo.4269874).
+If you use UnitCommitment.jl in your research (instances, models or algorithms), we kindly request that you cite the package as follows:
 
-If you make use of the provided instances files, we request that you additionally cite the original sources, as described in the [instances page](https://anl-ceeesa.github.io/UnitCommitment.jl/0.1/instances/).
+* **Alinson S. Xavier, Aleksandr M. Kazachkov, Feng Qiu**. "UnitCommitment.jl: A Julia/JuMP Optimization Package for Security-Constrained Unit Commitment". Zenodo (2020). [DOI: 10.5281/zenodo.4269874](https://doi.org/10.5281/zenodo.4269874).
 
-### License
+If you use the instances, we additionally request that you cite the original sources, as described in the [instances page](docs/instances.md).
 
-Released under the modified BSD license. See `LICENSE.md` for more details.
+## License
+
+```text
+UnitCommitment.jl: A Julia/JuMP Optimization Package for Security-Constrained Unit Commitment
+Copyright © 2020-2021, UChicago Argonne, LLC. All Rights Reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted
+provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of
+   conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of
+   conditions and the following disclaimer in the documentation and/or other materials provided
+   with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors may be used to
+   endorse or promote products derived from this software without specific prior written
+   permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+```
 

benchmark/Makefile

@@ -1,105 +0,0 @@
-# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
-# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
-# Released under the modified BSD license. See COPYING.md for more details.
-
-SHELL := /bin/bash
-JULIA := julia --project=. --sysimage ../build/sysimage.so
-TIMESTAMP := $(shell date "+%Y-%m-%d %H:%M")
-SRC_FILES := $(wildcard ../src/*.jl)
-
-INSTANCES_PGLIB := \
-        pglib-uc/ca/2014-09-01_reserves_0 \
-        pglib-uc/ca/2014-09-01_reserves_1 \
-        pglib-uc/ca/2015-03-01_reserves_0 \
-        pglib-uc/ca/2015-06-01_reserves_0 \
-        pglib-uc/ca/Scenario400_reserves_1 \
-        pglib-uc/ferc/2015-01-01_lw \
-        pglib-uc/ferc/2015-05-01_lw \
-        pglib-uc/ferc/2015-07-01_hw \
-        pglib-uc/ferc/2015-10-01_lw \
-        pglib-uc/ferc/2015-12-01_lw \
-        pglib-uc/rts_gmlc/2020-04-03 \
-        pglib-uc/rts_gmlc/2020-09-20 \
-        pglib-uc/rts_gmlc/2020-10-27 \
-        pglib-uc/rts_gmlc/2020-11-25 \
-        pglib-uc/rts_gmlc/2020-12-23
-
-INSTANCES_MATPOWER := \
-	matpower/case118/2017-02-01 \
-	matpower/case118/2017-08-01 \
-	matpower/case300/2017-02-01 \
-	matpower/case300/2017-08-01 \
-	matpower/case1354pegase/2017-02-01 \
-	matpower/case1888rte/2017-02-01 \
-	matpower/case1951rte/2017-08-01 \
-	matpower/case2848rte/2017-02-01 \
-	matpower/case2868rte/2017-08-01 \
-	matpower/case3375wp/2017-08-01 \
-	matpower/case6468rte/2017-08-01 \
-	matpower/case6515rte/2017-08-01
-
-INSTANCES_ORLIB := \
-	or-lib/20_0_1_w \
-	or-lib/20_0_5_w \
-	or-lib/50_0_2_w \
-	or-lib/75_0_2_w \
-	or-lib/100_0_1_w \
-	or-lib/100_0_4_w \
-	or-lib/100_0_5_w \
-	or-lib/200_0_3_w \
-	or-lib/200_0_7_w \
-	or-lib/200_0_9_w
-
-INSTANCES_TEJADA19 := \
-	tejada19/UC_24h_290g \
-	tejada19/UC_24h_623g \
-	tejada19/UC_24h_959g \
-	tejada19/UC_24h_1577g \
-	tejada19/UC_24h_1888g \
-	tejada19/UC_168h_72g \
-	tejada19/UC_168h_86g \
-	tejada19/UC_168h_130g \
-	tejada19/UC_168h_131g \
-	tejada19/UC_168h_199g
-
-SAMPLES := 1 2 3 4 5
-SOLUTIONS_MATPOWER := $(foreach s,$(SAMPLES),$(addprefix results/,$(addsuffix .$(s).sol.json,$(INSTANCES_MATPOWER))))
-SOLUTIONS_PGLIB := $(foreach s,$(SAMPLES),$(addprefix results/,$(addsuffix .$(s).sol.json,$(INSTANCES_PGLIB))))
-SOLUTIONS_ORLIB := $(foreach s,$(SAMPLES),$(addprefix results/,$(addsuffix .$(s).sol.json,$(INSTANCES_ORLIB))))
-SOLUTIONS_TEJADA19 := $(foreach s,$(SAMPLES),$(addprefix results/,$(addsuffix .$(s).sol.json,$(INSTANCES_TEJADA19))))
-
-.PHONY: tables save small large clean-mps matpower pglib orlib
-
-all: matpower pglib orlib tejada19
-
-matpower: $(SOLUTIONS_MATPOWER)
-
-pglib: $(SOLUTIONS_PGLIB)
-
-orlib: $(SOLUTIONS_ORLIB)
-
-tejada19: $(SOLUTIONS_TEJADA19)
-
-clean:
-	@rm -rf tables/benchmark* tables/compare* results
-    
-clean-mps:
-	@rm -fv results/*/*.mps.gz results/*/*/*.mps.gz
-
-clean-sol:
-	@rm -rf results/*/*.sol.* results/*/*/*.sol.*
-        
-save:
-	mkdir -p "runs/$(TIMESTAMP)"
-	rsync -avP results tables "runs/$(TIMESTAMP)/"
-
-results/%.sol.json: run.jl
-	@echo "run  $*"
-	@mkdir -p $(dir results/$*)
-	@$(JULIA) run.jl $* 2>&1 | cat > results/$*.log
-	@echo "run  $* [done]"
-
-tables:
-	@mkdir -p tables
-	@python scripts/table.py
-	#@python scripts/compare.py tables/reference.csv tables/benchmark.csv

benchmark/benchmark.jl

@@ -0,0 +1,158 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+using Distributed
+using Pkg
+Pkg.activate(".")
+
+@everywhere using Pkg
+@everywhere Pkg.activate(".")
+
+@everywhere using UnitCommitment
+@everywhere using JuMP
+@everywhere using Gurobi
+@everywhere using JSON
+@everywhere using Logging
+@everywhere using Printf
+@everywhere using LinearAlgebra
+@everywhere using Random
+
+@everywhere import UnitCommitment:
+    ArrCon2000,
+    CarArr2006,
+    DamKucRajAta2016,
+    Formulation,
+    Gar1962,
+    KnuOstWat2018,
+    MorLatRam2013,
+    PanGua2016,
+    XavQiuWanThi2019
+
+@everywhere UnitCommitment._setup_logger()
+
+function main()
+    cases = [
+        "pglib-uc/ca/2014-09-01_reserves_0",
+        "pglib-uc/ca/2014-09-01_reserves_1",
+        "pglib-uc/ca/2015-03-01_reserves_0",
+        "pglib-uc/ca/2015-06-01_reserves_0",
+        "pglib-uc/ca/Scenario400_reserves_1",
+        "pglib-uc/ferc/2015-01-01_lw",
+        "pglib-uc/ferc/2015-05-01_lw",
+        "pglib-uc/ferc/2015-07-01_hw",
+        "pglib-uc/ferc/2015-10-01_lw",
+        "pglib-uc/ferc/2015-12-01_lw",
+        "pglib-uc/rts_gmlc/2020-04-03",
+        "pglib-uc/rts_gmlc/2020-09-20",
+        "pglib-uc/rts_gmlc/2020-10-27",
+        "pglib-uc/rts_gmlc/2020-11-25",
+        "pglib-uc/rts_gmlc/2020-12-23",
+        "or-lib/20_0_1_w",
+        "or-lib/20_0_5_w",
+        "or-lib/50_0_2_w",
+        "or-lib/75_0_2_w",
+        "or-lib/100_0_1_w",
+        "or-lib/100_0_4_w",
+        "or-lib/100_0_5_w",
+        "or-lib/200_0_3_w",
+        "or-lib/200_0_7_w",
+        "or-lib/200_0_9_w",
+        "tejada19/UC_24h_290g",
+        "tejada19/UC_24h_623g",
+        "tejada19/UC_24h_959g",
+        "tejada19/UC_24h_1577g",
+        "tejada19/UC_24h_1888g",
+        "tejada19/UC_168h_72g",
+        "tejada19/UC_168h_86g",
+        "tejada19/UC_168h_130g",
+        "tejada19/UC_168h_131g",
+        "tejada19/UC_168h_199g",
+    ]
+    formulations = Dict(
+        "Default" => Formulation(),
+        "ArrCon2000" => Formulation(ramping = ArrCon2000.Ramping()),
+        "CarArr2006" => Formulation(pwl_costs = CarArr2006.PwlCosts()),
+        "DamKucRajAta2016" =>
+            Formulation(ramping = DamKucRajAta2016.Ramping()),
+        "Gar1962" => Formulation(pwl_costs = Gar1962.PwlCosts()),
+        "KnuOstWat2018" =>
+            Formulation(pwl_costs = KnuOstWat2018.PwlCosts()),
+        "MorLatRam2013" => Formulation(ramping = MorLatRam2013.Ramping()),
+        "PanGua2016" => Formulation(ramping = PanGua2016.Ramping()),
+    )
+    trials = [i for i in 1:5]
+    combinations = [
+        (c, f.first, f.second, t) for c in cases for f in formulations for
+        t in trials
+    ]
+    shuffle!(combinations)
+    @sync @distributed for c in combinations
+        _run_combination(c...)
+    end
+end
+
+@everywhere function _run_combination(
+    case,
+    formulation_name,
+    formulation,
+    trial,
+)
+    name = "$formulation_name/$case"
+    dirname = "results/$name"
+    mkpath(dirname)
+    if isfile("$dirname/$trial.json")
+        @info @sprintf("%-4s %-16s %s", "skip", formulation_name, case)
+        return
+    end
+    @info @sprintf("%-4s %-16s %s", "run", formulation_name, case)
+    open("$dirname/$trial.log", "w") do file
+        redirect_stdout(file) do
+            redirect_stderr(file) do
+                return _run_sample(case, formulation, "$dirname/$trial")
+            end
+        end
+    end
+    @info @sprintf("%-4s %-16s %s", "done", formulation_name, case)
+end
+
+@everywhere function _run_sample(case, formulation, prefix)
+    total_time = @elapsed begin
+        @info "Reading: $case"
+        time_read = @elapsed begin
+            instance = UnitCommitment.read_benchmark(case)
+        end
+        @info @sprintf("Read problem in %.2f seconds", time_read)
+        BLAS.set_num_threads(4)
+        model = UnitCommitment.build_model(
+            instance = instance,
+            formulation = formulation,
+            optimizer = optimizer_with_attributes(
+                Gurobi.Optimizer,
+                "Threads" => 4,
+                "Seed" => rand(1:1000),
+            ),
+            variable_names = true,
+        )
+        @info "Optimizing..."
+        BLAS.set_num_threads(1)
+        UnitCommitment.optimize!(
+            model,
+            XavQiuWanThi2019.Method(time_limit = 3600.0, gap_limit = 1e-4),
+        )
+    end
+    @info @sprintf("Total time was %.2f seconds", total_time)
+    @info "Writing solution: $prefix.json"
+    solution = UnitCommitment.solution(model)
+    UnitCommitment.write("$prefix.json", solution)
+    @info "Verifying solution..."
+    return UnitCommitment.validate(instance, solution)
+    # @info "Exporting model..."
+    # return JuMP.write_to_file(model, model_filename)
+end
+
+if length(ARGS) > 0
+    _run_sample(ARGS[1], UnitCommitment.Formulation(), "tmp")
+else
+    main()
+end

benchmark/run.jl

@@ -1,66 +0,0 @@
-# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
-# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
-# Released under the modified BSD license. See COPYING.md for more details.
-
-using UnitCommitment
-using JuMP
-using Gurobi
-using JSON
-using Logging
-using Printf
-using LinearAlgebra
-
-UnitCommitment._setup_logger()
-
-function main()
-    basename, suffix = split(ARGS[1], ".")
-    solution_filename = "results/$basename.$suffix.sol.json"
-    model_filename = "results/$basename.$suffix.mps.gz"
-
-    time_limit = 60 * 20
-
-    BLAS.set_num_threads(4)
-
-    total_time = @elapsed begin
-        @info "Reading: $basename"
-        time_read = @elapsed begin
-            instance = UnitCommitment.read_benchmark(basename)
-        end
-        @info @sprintf("Read problem in %.2f seconds", time_read)
-
-        time_model = @elapsed begin
-            model = build_model(
-                instance = instance,
-                optimizer = optimizer_with_attributes(
-                    Gurobi.Optimizer,
-                    "Threads" => 4,
-                    "Seed" => rand(1:1000),
-                ),
-                variable_names = true,
-            )
-        end
-
-        @info "Optimizing..."
-        BLAS.set_num_threads(1)
-        UnitCommitment.optimize!(
-            model,
-            time_limit = time_limit,
-            gap_limit = 1e-3,
-        )
-    end
-    @info @sprintf("Total time was %.2f seconds", total_time)
-
-    @info "Writing: $solution_filename"
-    solution = UnitCommitment.solution(model)
-    open(solution_filename, "w") do file
-        return JSON.print(file, solution, 2)
-    end
-
-    @info "Verifying solution..."
-    UnitCommitment.validate(instance, solution)
-
-    @info "Exporting model..."
-    return JuMP.write_to_file(model, model_filename)
-end
-
-main()

benchmark/scripts/compare.py

@@ -5,71 +5,82 @@
 import pandas as pd
 import numpy as np
 import seaborn as sns
+import matplotlib
 import matplotlib.pyplot as plt
 import sys
 
-# easy_cutoff = 120
-
-b1 = pd.read_csv(sys.argv[1], index_col=0)
-b2 = pd.read_csv(sys.argv[2], index_col=0)
-
-c1 = b1.groupby(["Group", "Instance", "Sample"])[
-    ["Optimization time (s)", "Primal bound"]
-].mean()
-c2 = b2.groupby(["Group", "Instance", "Sample"])[
-    ["Optimization time (s)", "Primal bound"]
-].mean()
-c1.columns = ["A Time (s)", "A Value"]
-c2.columns = ["B Time (s)", "B Value"]
-
-merged = pd.concat([c1, c2], axis=1)
-merged["Speedup"] = merged["A Time (s)"] / merged["B Time (s)"]
-merged["Time diff (s)"] = merged["B Time (s)"] - merged["A Time (s)"]
-merged["Value diff (%)"] = np.round(
-    (merged["B Value"] - merged["A Value"]) / merged["A Value"] * 100.0, 5
+matplotlib.use("Agg")
+sns.set("talk")
+sns.set_palette(
+    [
+        "#9b59b6",
+        "#3498db",
+        "#95a5a6",
+        "#e74c3c",
+        "#34495e",
+        "#2ecc71",
+    ]
 )
-merged.loc[merged.loc[:, "B Time (s)"] <= 0, "Speedup"] = float("nan")
-merged.loc[merged.loc[:, "B Time (s)"] <= 0, "Time diff (s)"] = float("nan")
-# merged = merged[(merged["A Time (s)"] >= easy_cutoff) | (merged["B Time (s)"] >= easy_cutoff)]
-merged.reset_index(inplace=True)
-merged["Name"] = merged["Group"] + "/" + merged["Instance"]
-# merged = merged.sort_values(by="Speedup", ascending=False)
 
+filename = sys.argv[1]
+m1 = sys.argv[2]
+m2 = sys.argv[3]
 
-k = len(merged.groupby("Name"))
-plt.figure(figsize=(12, 0.50 * k))
-plt.rcParams["xtick.bottom"] = plt.rcParams["xtick.labelbottom"] = True
-plt.rcParams["xtick.top"] = plt.rcParams["xtick.labeltop"] = True
-sns.set_style("whitegrid")
-sns.set_palette("Set1")
+# Prepare data
+data = pd.read_csv(filename, index_col=0)
+b1 = (
+    data[data["Group"] == m1]
+    .groupby(["Instance", "Sample"])
+    .mean()[["Optimization time (s)"]]
+)
+b2 = (
+    data[data["Group"] == m2]
+    .groupby(["Instance", "Sample"])
+    .mean()[["Optimization time (s)"]]
+)
+b1.columns = [f"{m1} time (s)"]
+b2.columns = [f"{m2} time (s)"]
+merged = pd.merge(b1, b2, left_index=True, right_index=True).reset_index().dropna()
+merged["Speedup"] = merged[f"{m1} time (s)"] / merged[f"{m2} time (s)"]
+merged["Group"] = merged["Instance"].str.replace(r"\/.*", "", regex=True)
+merged = merged.sort_values(by=["Instance", "Sample"], ascending=True)
+merged = merged[(merged[f"{m1} time (s)"] > 0) & (merged[f"{m2} time (s)"] > 0)]
+
+# Plot results
+k1 = len(merged.groupby("Instance").mean())
+k2 = len(merged.groupby("Group").mean())
+k = k1 + k2
+fig = plt.figure(
+    constrained_layout=True,
+    figsize=(15, max(5, 0.75 * k)),
+)
+plt.suptitle(f"{m1} vs {m2}")
+gs1 = fig.add_gridspec(nrows=k, ncols=1)
+ax1 = fig.add_subplot(gs1[0:k1, 0:1])
+ax2 = fig.add_subplot(gs1[k1:, 0:1], sharex=ax1)
 sns.barplot(
     data=merged,
     x="Speedup",
-    y="Name",
-    color="tab:red",
-    capsize=0.15,
+    y="Instance",
+    color="tab:purple",
     errcolor="k",
     errwidth=1.25,
+    ax=ax1,
 )
-plt.axvline(1.0, linestyle="--", color="k")
-plt.tight_layout()
+sns.barplot(
+    data=merged,
+    x="Speedup",
+    y="Group",
+    color="tab:purple",
+    errcolor="k",
+    errwidth=1.25,
+    ax=ax2,
+)
+ax1.axvline(1.0, linestyle="--", color="k")
+ax2.axvline(1.0, linestyle="--", color="k")
 
 print("Writing tables/compare.png")
 plt.savefig("tables/compare.png", dpi=150)
 
 print("Writing tables/compare.csv")
-merged.loc[
-    :,
-    [
-        "Group",
-        "Instance",
-        "Sample",
-        "A Time (s)",
-        "B Time (s)",
-        "Speedup",
-        "Time diff (s)",
-        "A Value",
-        "B Value",
-        "Value diff (%)",
-    ],
-].to_csv("tables/compare.csv", index_label="Index")
+merged.to_csv("tables/compare.csv", index_label="Index")

benchmark/scripts/table.py

@@ -6,11 +6,13 @@ from pathlib import Path
 import pandas as pd
 import re
 from tabulate import tabulate
+from colorama import init, Fore, Back, Style
+
+init()
 
 
 def process_all_log_files():
-    pathlist = list(Path(".").glob("results/*/*/*.log"))
-    pathlist += list(Path(".").glob("results/*/*.log"))
+    pathlist = list(Path(".").glob("results/**/*.log"))
     rows = []
     for path in pathlist:
         if ".ipy" in str(path):
@@ -26,9 +28,9 @@ def process_all_log_files():
 
 def process(filename):
     parts = filename.replace(".log", "").split("/")
-    group_name = "/".join(parts[1:-1])
-    instance_name = parts[-1]
-    instance_name, sample_name = instance_name.split(".")
+    group_name = parts[1]
+    instance_name = "/".join(parts[2:-1])
+    sample_name = parts[-1]
     nodes = 0.0
     optimize_time = 0.0
     simplex_iterations = 0.0
@@ -49,6 +51,7 @@ def process(filename):
     # m = re.search("case([0-9]*)", instance_name)
     # n_buses = int(m.group(1))
     n_buses = 0
+    validation_errors = 0
 
     with open(filename) as file:
         for line in file.readlines():
@@ -138,6 +141,14 @@ def process(filename):
             if m is not None:
                 transmission_count += 1
 
+            m = re.search(r".*Found ([0-9]*) validation errors", line)
+            if m is not None:
+                validation_errors += int(m.group(1))
+                print(
+                    f"{Fore.YELLOW}{Style.BRIGHT}Warning:{Style.RESET_ALL} {validation_errors:8d} "
+                    f"{Style.DIM}validation errors in {Style.RESET_ALL}{group_name}/{instance_name}/{sample_name}"
+                )
+
     return {
         "Group": group_name,
         "Instance": instance_name,
@@ -169,34 +180,44 @@ def process(filename):
         "Transmission screening constraints": transmission_count,
         "Transmission screening time": transmission_time,
         "Transmission screening calls": transmission_calls,
+        "Validation errors": validation_errors,
     }
 
 
 def generate_chart():
     import pandas as pd
+    import matplotlib
     import matplotlib.pyplot as plt
     import seaborn as sns
 
+    matplotlib.use("Agg")
+    sns.set("talk")
+    sns.set_palette(
+        [
+            "#9b59b6",
+            "#3498db",
+            "#95a5a6",
+            "#e74c3c",
+            "#34495e",
+            "#2ecc71",
+        ]
+    )
+
     tables = []
     files = ["tables/benchmark.csv"]
     for f in files:
         table = pd.read_csv(f, index_col=0)
-        table.loc[:, "Instance"] = (
-            table.loc[:, "Group"] + "/" + table.loc[:, "Instance"]
-        )
         table.loc[:, "Filename"] = f
         tables += [table]
     benchmark = pd.concat(tables, sort=True)
-    benchmark = benchmark.sort_values(by="Instance")
-    k = len(benchmark.groupby("Instance"))
-    plt.figure(figsize=(12, 0.50 * k))
-    sns.set_style("whitegrid")
-    sns.set_palette("Set1")
+    benchmark = benchmark.sort_values(by=["Group", "Instance"])
+    k1 = len(benchmark.groupby("Instance"))
+    k2 = len(benchmark.groupby("Group"))
+    plt.figure(figsize=(12, 0.25 * k1 * k2))
     sns.barplot(
         y="Instance",
         x="Total time (s)",
-        color="tab:red",
-        capsize=0.15,
+        hue="Group",
         errcolor="k",
         errwidth=1.25,
         data=benchmark,

docs/format.md

@@ -28,13 +28,14 @@ Each section is described in detail below. For a complete example, see [case14](
 
 ### Parameters
 
-This section describes system-wide parameters, such as power balance penalties,  optimization parameters, such as the length of the planning horizon and the time.
+This section describes system-wide parameters, such as power balance and reserve shortfall penalties, and optimization parameters, such as the length of the planning horizon and the time.
 
 | Key                            | Description                                       | Default  | Time series?
 | :----------------------------- | :------------------------------------------------ | :------: | :------------:
-| `Time horizon (h)`                     | Length of the planning horizon (in hours). | Required | N
+| `Time horizon (h)` | Length of the planning horizon (in hours). | Required | N
 | `Time step (min)` | Length of each time step (in minutes). Must be a divisor of 60 (e.g. 60, 30, 20, 15, etc). | `60` | N
 | `Power balance penalty ($/MW)` | Penalty for system-wide shortage or surplus in production (in $/MW). This is charged per time step. For example, if there is a shortage of 1 MW for three time steps, three times this amount will be charged. | `1000.0` | Y
+| `Reserve shortfall penalty ($/MW)` | Penalty for system-wide shortage in meeting reserve requirements (in $/MW). This is charged per time step. Negative value implies reserve constraints must always be satisfied. | `-1` | Y
 
 
 #### Example
@@ -42,7 +43,8 @@ This section describes system-wide parameters, such as power balance penalties,
 {
     "Parameters": {
         "Time horizon (h)": 4,
-        "Power balance penalty ($/MW)": 1000.0
+        "Power balance penalty ($/MW)": 1000.0,
+        "Reserve shortfall penalty ($/MW)": -1.0
     }
 }
 ```

docs/index.md

@@ -2,20 +2,30 @@
 
 **UnitCommitment.jl** (UC.jl) is a Julia/JuMP 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
+## 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][ArrCon2000], [MorLatRam2013][MorLatRam2013], [DamKucRajAta2016][DamKucRajAta2016], [PanGua2016][PanGua2016]), multiple piecewise-linear costs formulations ([Gar1962][Gar1962], [CarArr2006][CarArr2006], [KnuOstWat2018][KnuOstWat2018]) and contingency screening methods ([XavQiuWanThi2019][XavQiuWanThi2019]). Our goal is to keep these implementations 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.
 
+[ArrCon2000]: https://doi.org/10.1109/59.871739
+[CarArr2006]: https://doi.org/10.1109/TPWRS.2006.876672
+[DamKucRajAta2016]: https://doi.org/10.1007/s10107-015-0919-9
+[Gar1962]: https://doi.org/10.1109/AIEEPAS.1962.4501405
+[KnuOstWat2018]: https://doi.org/10.1109/TPWRS.2017.2783850
+[MorLatRam2013]: https://doi.org/10.1109/TPWRS.2013.2251373
+[PanGua2016]: https://doi.org/10.1287/opre.2016.1520
+[XavQiuWanThi2019]: https://doi.org/10.1109/TPWRS.2019.2892620
+
 ### Authors
-* **Alinson Santos Xavier** (Argonne National Laboratory)
+* **Alinson S. Xavier** (Argonne National Laboratory)
+* **Aleksandr M. Kazachkov** (University of Florida)
 * **Feng Qiu** (Argonne National Laboratory)
 
 ### Acknowledgments
 
-* We would like to thank **Aleksandr M. Kazachkov** (University of Florida), **Yonghong Chen** (Midcontinent Independent System Operator), **Feng Pan** (Pacific Northwest National Laboratory) for valuable feedback on early versions of this package.
+* We would like to thank **Yonghong Chen** (Midcontinent Independent System Operator), **Feng Pan** (Pacific Northwest National Laboratory) for valuable feedback on early versions of this package.
 
 * Based upon work supported by **Laboratory Directed Research and Development** (LDRD) funding from Argonne National Laboratory, provided by the Director, Office of Science, of the U.S. Department of Energy under Contract No. DE-AC02-06CH11357
 
@@ -25,7 +35,7 @@
 
 If you use UnitCommitment.jl in your research (instances, models or algorithms), we kindly request that you cite the package as follows:
 
-* **Alinson S. Xavier, Feng Qiu**, "UnitCommitment.jl: A Julia/JuMP Optimization Package for Security-Constrained Unit Commitment". Zenodo (2020). [DOI: 10.5281/zenodo.4269874](https://doi.org/10.5281/zenodo.4269874).
+* **Alinson S. Xavier, Aleksandr M. Kazachkov, Feng Qiu**, "UnitCommitment.jl: A Julia/JuMP Optimization Package for Security-Constrained Unit Commitment". Zenodo (2020). [DOI: 10.5281/zenodo.4269874](https://doi.org/10.5281/zenodo.4269874).
 
 If you use the instances, we additionally request that you cite the original sources, as described in the [instances page](instances.md).
 

docs/instances.md

@@ -315,7 +315,7 @@ Tejada19
 References
 ----------
 
-* [UCJL] **Alinson S. Xavier, Feng Qiu.** "UnitCommitment.jl: A Julia/JuMP Optimization Package for Security-Constrained Unit Commitment". Zenodo (2020). [DOI: 10.5281/zenodo.4269874](https://doi.org/10.5281/zenodo.4269874)
+* [UCJL] **Alinson S. Xavier, Aleksandr M. Kazachkov, Feng Qiu.** "UnitCommitment.jl: A Julia/JuMP Optimization Package for Security-Constrained Unit Commitment". Zenodo (2020). [DOI: 10.5281/zenodo.4269874](https://doi.org/10.5281/zenodo.4269874)
 
 * [KnOsWa20] **Bernard Knueven, James Ostrowski and Jean-Paul Watson.** "On Mixed-Integer Programming Formulations for the Unit Commitment Problem". INFORMS Journal on Computing (2020). [DOI: 10.1287/ijoc.2019.0944](https://doi.org/10.1287/ijoc.2019.0944)
 

docs/model.md

@@ -148,7 +148,7 @@ for g in instance.units
 end
 ```
 
-### Modifying the model
+### Fixing variables, modifying objective function and adding constraints
 
 Since we now have a direct reference to the JuMP decision variables, it is possible to fix variables, change the coefficients in the objective function, or even add new constraints to the model before solving it. The script below shows how can this be accomplished. For more information on modifying an existing model, [see the JuMP documentation](https://jump.dev/JuMP.jl/stable/manual/variables/).
 
@@ -190,6 +190,54 @@ JuMP.set_objective_coefficient(
 UnitCommitment.optimize!(model)
 ```
 
+### Adding new component to a bus
+
+The following snippet shows how to add a new grid component to a particular bus. For each time step, we create decision variables for the new grid component, add these variables to the objective function, then attach the component to a particular bus by modifying some existing model constraints. 
+
+```julia
+using Cbc
+using JuMP
+using UnitCommitment
+
+# Load instance and build base model
+instance = UnitCommitment.read_benchmark("matpower/case118/2017-02-01")
+model = UnitCommitment.build_model(
+    instance=instance,
+    optimizer=Cbc.Optimizer,
+)
+
+# Get the number of time steps in the original instance
+T = instance.time
+
+# Create decision variables for the new grid component.
+# In this example, we assume that the new component can
+# inject up to 10 MW of power at each time step, so we
+# create new continuous variables 0 ≤ x[t] ≤ 10.
+@variable(model, x[1:T], lower_bound=0.0, upper_bound=10.0)
+
+# For each time step
+for t in 1:T
+
+    # Add production costs to the objective function.
+    # In this example, we assume a cost of $5/MW.
+    set_objective_coefficient(model, x[t], 5.0)
+
+    # Attach the new component to bus b1, by modifying the
+    # constraint `eq_net_injection`.
+    set_normalized_coefficient(
+        model[:eq_net_injection]["b1", t],
+        x[t],
+        1.0,
+    )
+end
+
+# Solve the model
+UnitCommitment.optimize!(model)
+
+# Show optimal values for the x variables
+@show value.(x)
+```
+
 References
 ----------
 * [KnOsWa20] **Bernard Knueven, James Ostrowski and Jean-Paul Watson.** "On Mixed-Integer Programming Formulations for the Unit Commitment Problem". INFORMS Journal on Computing (2020). [DOI: 10.1287/ijoc.2019.0944](https://doi.org/10.1287/ijoc.2019.0944)

docs/usage.md

@@ -33,35 +33,33 @@ Typical Usage
 
 ### Solving user-provided instances
 
-The first step to use UC.jl is to construct a JSON file describing your unit commitment instance. See the [data format page]() for a complete description of the data format UC.jl expects. The next steps, as shown below, are to read the instance from file, construct the optimization model, run the optimization and extract the optimal solution.
+The first step to use UC.jl is to construct a JSON file describing your unit commitment instance. See [Data Format](format.md) for a complete description of the data format UC.jl expects. The next steps, as shown below, are to: (1) read the instance from file; (2) construct the optimization model; (3) run the optimization; and (4) extract the optimal solution.
 
 ```julia
 using Cbc
 using JSON
 using UnitCommitment
 
-# Read instance
+# 1. Read instance
 instance = UnitCommitment.read("/path/to/input.json")
 
-# Construct optimization model
+# 2. Construct optimization model
 model = UnitCommitment.build_model(
     instance=instance,
     optimizer=Cbc.Optimizer,
 )
 
-# Solve model
+# 3. Solve model
 UnitCommitment.optimize!(model)
 
-# Extract solution
+# 4. Write solution to a file
 solution = UnitCommitment.solution(model)
-
-# Write solution to a file
 UnitCommitment.write("/path/to/output.json", solution)
 ```
 
 ### Solving benchmark instances
 
-As described in the [Instances page](instances.md), UnitCommitment.jl contains a number of benchmark instances collected from the literature. To solve one of these instances individually, instead of constructing your own, the function `read_benchmark` can be used:
+UnitCommitment.jl contains a large number of benchmark instances collected from the literature and converted into a common data format. To solve one of these instances individually, instead of constructing your own, the function `read_benchmark` can be used, as shown below. See [Instances](instances.md) for the complete list of available instances.
 
 ```julia
 using UnitCommitment
@@ -71,10 +69,38 @@ instance = UnitCommitment.read_benchmark("matpower/case3375wp/2017-02-01")
 Advanced usage
 --------------
 
+### Customizing the formulation
 
-### Modifying the formulation
+By default, `build_model` uses a formulation that combines modeling components from different publications, and that has been carefully tested, using our own benchmark scripts, to provide good performance across a wide variety of instances. This default formulation is expected to change over time, as new methods are proposed in the literature. You can, however, construct your own formulation, based on the modeling components that you choose, as shown in the next example.
 
-For the time being, the recommended way of modifying the MILP formulation used by UC.jl is to create a local copy of our git repository and directly modify the source code of the package. In a future version, it will be possible to switch between multiple formulations, or to simply add/remove constraints after the model has been generated.
+```julia
+using Cbc
+using UnitCommitment
+
+import UnitCommitment:
+    Formulation,
+    KnuOstWat2018,
+    MorLatRam2013,
+    ShiftFactorsFormulation
+
+instance = UnitCommitment.read_benchmark(
+    "matpower/case118/2017-02-01",
+)
+
+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,
+        ),
+    ),
+)
+```
 
 ### Generating initial conditions
 
@@ -93,7 +119,10 @@ instance = UnitCommitment.read("instance.json")
 UnitCommitment.generate_initial_conditions!(instance, Cbc.Optimizer)
 
 # Construct and solve optimization model
-model = UnitCommitment.build_model(instance, Cbc.Optimizer)
+model = UnitCommitment.build_model(
+    instance=instance,
+    optimizer=Cbc.Optimizer,
+)
 UnitCommitment.optimize!(model)
 ```
 

src/UnitCommitment.jl

@@ -3,12 +3,54 @@
 # Released under the modified BSD license. See COPYING.md for more details.
 
 module UnitCommitment
-include("log.jl")
-include("instance.jl")
-include("screening.jl")
-include("model.jl")
-include("sensitivity.jl")
-include("validate.jl")
-include("convert.jl")
-include("initcond.jl")
+
+include("instance/structs.jl")
+include("model/formulations/base/structs.jl")
+include("solution/structs.jl")
+
+include("model/formulations/ArrCon2000/structs.jl")
+include("model/formulations/CarArr2006/structs.jl")
+include("model/formulations/DamKucRajAta2016/structs.jl")
+include("model/formulations/Gar1962/structs.jl")
+include("model/formulations/KnuOstWat2018/structs.jl")
+include("model/formulations/MorLatRam2013/structs.jl")
+include("model/formulations/PanGua2016/structs.jl")
+include("solution/methods/XavQiuWanThi2019/structs.jl")
+
+include("import/egret.jl")
+include("instance/read.jl")
+include("model/build.jl")
+include("model/formulations/ArrCon2000/ramp.jl")
+include("model/formulations/base/bus.jl")
+include("model/formulations/base/line.jl")
+include("model/formulations/base/psload.jl")
+include("model/formulations/base/sensitivity.jl")
+include("model/formulations/base/system.jl")
+include("model/formulations/base/unit.jl")
+include("model/formulations/CarArr2006/pwlcosts.jl")
+include("model/formulations/DamKucRajAta2016/ramp.jl")
+include("model/formulations/Gar1962/pwlcosts.jl")
+include("model/formulations/Gar1962/status.jl")
+include("model/formulations/Gar1962/prod.jl")
+include("model/formulations/KnuOstWat2018/pwlcosts.jl")
+include("model/formulations/MorLatRam2013/ramp.jl")
+include("model/formulations/MorLatRam2013/scosts.jl")
+include("model/formulations/PanGua2016/ramp.jl")
+include("model/jumpext.jl")
+include("solution/fix.jl")
+include("solution/methods/XavQiuWanThi2019/enforce.jl")
+include("solution/methods/XavQiuWanThi2019/filter.jl")
+include("solution/methods/XavQiuWanThi2019/find.jl")
+include("solution/methods/XavQiuWanThi2019/optimize.jl")
+include("solution/optimize.jl")
+include("solution/solution.jl")
+include("solution/warmstart.jl")
+include("solution/write.jl")
+include("transform/initcond.jl")
+include("transform/slice.jl")
+include("transform/randomize/XavQiuAhm2021.jl")
+include("utils/log.jl")
+include("validation/repair.jl")
+include("validation/validate.jl")
+
 end

src/import/egret.jl

@@ -4,16 +4,15 @@
 
 using DataStructures, JSON, GZip
 
-function _read_json(path::String)::OrderedDict
-    if endswith(path, ".gz")
-        file = GZip.gzopen(path)
-    else
-        file = open(path)
-    end
-    return JSON.parse(file, dicttype = () -> DefaultOrderedDict(nothing))
-end
+"""
 
-function _read_egret_solution(path::String)::OrderedDict
+    read_egret_solution(path::String)::OrderedDict
+
+Read a JSON solution file produced by EGRET and transforms it into a
+dictionary having the same structure as the one produced by
+UnitCommitment.solution(model).
+"""
+function read_egret_solution(path::String)::OrderedDict
     egret = _read_json(path)
     T = length(egret["system"]["time_keys"])
 

src/instance/read.jl

@@ -8,104 +8,35 @@ using DataStructures
 using GZip
 import Base: getindex, time
 
-mutable struct Bus
-    name::String
-    offset::Int
-    load::Vector{Float64}
-    units::Vector
-    price_sensitive_loads::Vector
-end
+"""
+    read_benchmark(name::AbstractString)::UnitCommitmentInstance
 
-mutable struct CostSegment
-    mw::Vector{Float64}
-    cost::Vector{Float64}
-end
+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.
 
-mutable struct StartupCategory
-    delay::Int
-    cost::Float64
-end
-
-mutable struct Unit
-    name::String
-    bus::Bus
-    max_power::Vector{Float64}
-    min_power::Vector{Float64}
-    must_run::Vector{Bool}
-    min_power_cost::Vector{Float64}
-    cost_segments::Vector{CostSegment}
-    min_uptime::Int
-    min_downtime::Int
-    ramp_up_limit::Float64
-    ramp_down_limit::Float64
-    startup_limit::Float64
-    shutdown_limit::Float64
-    initial_status::Union{Int,Nothing}
-    initial_power::Union{Float64,Nothing}
-    provides_spinning_reserves::Vector{Bool}
-    startup_categories::Vector{StartupCategory}
-end
-
-mutable struct TransmissionLine
-    name::String
-    offset::Int
-    source::Bus
-    target::Bus
-    reactance::Float64
-    susceptance::Float64
-    normal_flow_limit::Vector{Float64}
-    emergency_flow_limit::Vector{Float64}
-    flow_limit_penalty::Vector{Float64}
-end
-
-mutable struct Reserves
-    spinning::Vector{Float64}
-end
-
-mutable struct Contingency
-    name::String
-    lines::Vector{TransmissionLine}
-    units::Vector{Unit}
-end
-
-mutable struct PriceSensitiveLoad
-    name::String
-    bus::Bus
-    demand::Vector{Float64}
-    revenue::Vector{Float64}
-end
-
-mutable struct UnitCommitmentInstance
-    time::Int
-    power_balance_penalty::Vector{Float64}
-    units::Vector{Unit}
-    buses::Vector{Bus}
-    lines::Vector{TransmissionLine}
-    reserves::Reserves
-    contingencies::Vector{Contingency}
-    price_sensitive_loads::Vector{PriceSensitiveLoad}
-end
-
-function Base.show(io::IO, instance::UnitCommitmentInstance)
-    print(io, "UnitCommitmentInstance(")
-    print(io, "$(length(instance.units)) units, ")
-    print(io, "$(length(instance.buses)) buses, ")
-    print(io, "$(length(instance.lines)) lines, ")
-    print(io, "$(length(instance.contingencies)) contingencies, ")
-    print(
-        io,
-        "$(length(instance.price_sensitive_loads)) price sensitive loads, ",
-    )
-    print(io, "$(instance.time) time steps")
-    print(io, ")")
-    return
-end
+Example
+-------
 
+    import UnitCommitment
+    instance = UnitCommitment.read_benchmark("matpower/case3375wp/2017-02-01")
+"""
 function read_benchmark(name::AbstractString)::UnitCommitmentInstance
     basedir = dirname(@__FILE__)
-    return UnitCommitment.read("$basedir/../instances/$name.json.gz")
+    return UnitCommitment.read("$basedir/../../instances/$name.json.gz")
 end
 
+"""
+    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")
+"""
 function read(path::AbstractString)::UnitCommitmentInstance
     if endswith(path, ".gz")
         return _read(gzopen(path))
@@ -120,6 +51,15 @@ function _read(file::IO)::UnitCommitmentInstance
     )
 end
 
+function _read_json(path::String)::OrderedDict
+    if endswith(path, ".gz")
+        file = GZip.gzopen(path)
+    else
+        file = open(path)
+    end
+    return JSON.parse(file, dicttype = () -> DefaultOrderedDict(nothing))
+end
+
 function _from_json(json; repair = true)
     units = Unit[]
     buses = Bus[]
@@ -158,6 +98,10 @@ function _from_json(json; repair = true)
         json["Parameters"]["Power balance penalty (\$/MW)"],
         default = [1000.0 for t in 1:T],
     )
+    shortfall_penalty = timeseries(
+        json["Parameters"]["Reserve shortfall penalty (\$/MW)"],
+        default = [-1.0 for t in 1:T],
+    )
 
     # Read buses
     for (bus_name, dict) in json["Buses"]
@@ -322,68 +266,23 @@ function _from_json(json; repair = true)
     end
 
     instance = UnitCommitmentInstance(
-        T,
-        power_balance_penalty,
-        units,
-        buses,
-        lines,
-        reserves,
-        contingencies,
-        loads,
+        buses_by_name = Dict(b.name => b for b in buses),
+        buses = buses,
+        contingencies_by_name = Dict(c.name => c for c in contingencies),
+        contingencies = contingencies,
+        lines_by_name = Dict(l.name => l for l in lines),
+        lines = lines,
+        power_balance_penalty = power_balance_penalty,
+        price_sensitive_loads_by_name = Dict(ps.name => ps for ps in loads),
+        price_sensitive_loads = loads,
+        reserves = reserves,
+        shortfall_penalty = shortfall_penalty,
+        time = T,
+        units_by_name = Dict(g.name => g for g in units),
+        units = units,
     )
     if repair
         UnitCommitment.repair!(instance)
     end
     return instance
 end
-
-"""
-    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 slice(
-    instance::UnitCommitmentInstance,
-    range::UnitRange{Int},
-)::UnitCommitmentInstance
-    modified = deepcopy(instance)
-    modified.time = length(range)
-    modified.power_balance_penalty = modified.power_balance_penalty[range]
-    modified.reserves.spinning = modified.reserves.spinning[range]
-    for u in modified.units
-        u.max_power = u.max_power[range]
-        u.min_power = u.min_power[range]
-        u.must_run = u.must_run[range]
-        u.min_power_cost = u.min_power_cost[range]
-        u.provides_spinning_reserves = u.provides_spinning_reserves[range]
-        for s in u.cost_segments
-            s.mw = s.mw[range]
-            s.cost = s.cost[range]
-        end
-    end
-    for b in modified.buses
-        b.load = b.load[range]
-    end
-    for l in modified.lines
-        l.normal_flow_limit = l.normal_flow_limit[range]
-        l.emergency_flow_limit = l.emergency_flow_limit[range]
-        l.flow_limit_penalty = l.flow_limit_penalty[range]
-    end
-    for ps in modified.price_sensitive_loads
-        ps.demand = ps.demand[range]
-        ps.revenue = ps.revenue[range]
-    end
-    return modified
-end
-
-export UnitCommitmentInstance

src/instance/structs.jl

@@ -0,0 +1,104 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+mutable struct Bus
+    name::String
+    offset::Int
+    load::Vector{Float64}
+    units::Vector
+    price_sensitive_loads::Vector
+end
+
+mutable struct CostSegment
+    mw::Vector{Float64}
+    cost::Vector{Float64}
+end
+
+mutable struct StartupCategory
+    delay::Int
+    cost::Float64
+end
+
+mutable struct Unit
+    name::String
+    bus::Bus
+    max_power::Vector{Float64}
+    min_power::Vector{Float64}
+    must_run::Vector{Bool}
+    min_power_cost::Vector{Float64}
+    cost_segments::Vector{CostSegment}
+    min_uptime::Int
+    min_downtime::Int
+    ramp_up_limit::Float64
+    ramp_down_limit::Float64
+    startup_limit::Float64
+    shutdown_limit::Float64
+    initial_status::Union{Int,Nothing}
+    initial_power::Union{Float64,Nothing}
+    provides_spinning_reserves::Vector{Bool}
+    startup_categories::Vector{StartupCategory}
+end
+
+mutable struct TransmissionLine
+    name::String
+    offset::Int
+    source::Bus
+    target::Bus
+    reactance::Float64
+    susceptance::Float64
+    normal_flow_limit::Vector{Float64}
+    emergency_flow_limit::Vector{Float64}
+    flow_limit_penalty::Vector{Float64}
+end
+
+mutable struct Reserves
+    spinning::Vector{Float64}
+end
+
+mutable struct Contingency
+    name::String
+    lines::Vector{TransmissionLine}
+    units::Vector{Unit}
+end
+
+mutable struct PriceSensitiveLoad
+    name::String
+    bus::Bus
+    demand::Vector{Float64}
+    revenue::Vector{Float64}
+end
+
+Base.@kwdef mutable struct UnitCommitmentInstance
+    buses_by_name::Dict{AbstractString,Bus}
+    buses::Vector{Bus}
+    contingencies_by_name::Dict{AbstractString,Contingency}
+    contingencies::Vector{Contingency}
+    lines_by_name::Dict{AbstractString,TransmissionLine}
+    lines::Vector{TransmissionLine}
+    power_balance_penalty::Vector{Float64}
+    price_sensitive_loads_by_name::Dict{AbstractString,PriceSensitiveLoad}
+    price_sensitive_loads::Vector{PriceSensitiveLoad}
+    reserves::Reserves
+    shortfall_penalty::Vector{Float64}
+    time::Int
+    units_by_name::Dict{AbstractString,Unit}
+    units::Vector{Unit}
+end
+
+function Base.show(io::IO, instance::UnitCommitmentInstance)
+    print(io, "UnitCommitmentInstance(")
+    print(io, "$(length(instance.units)) units, ")
+    print(io, "$(length(instance.buses)) buses, ")
+    print(io, "$(length(instance.lines)) lines, ")
+    print(io, "$(length(instance.contingencies)) contingencies, ")
+    print(
+        io,
+        "$(length(instance.price_sensitive_loads)) price sensitive loads, ",
+    )
+    print(io, "$(instance.time) time steps")
+    print(io, ")")
+    return
+end
+
+export UnitCommitmentInstance

src/model.jl

@@ -1,787 +0,0 @@
-# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
-# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
-# Released under the modified BSD license. See COPYING.md for more details.
-
-using JuMP, MathOptInterface, DataStructures
-import JuMP: value, fix, set_name
-
-# Extend some JuMP functions so that decision variables can be safely replaced by
-# (constant) floating point numbers.
-function value(x::Float64)
-    return x
-end
-
-function fix(x::Float64, v::Float64; force)
-    return abs(x - v) < 1e-6 || error("Value mismatch: $x != $v")
-end
-
-function set_name(x::Float64, n::String)
-    # nop
-end
-
-function build_model(;
-    filename::Union{String,Nothing} = nothing,
-    instance::Union{UnitCommitmentInstance,Nothing} = nothing,
-    isf::Union{Matrix{Float64},Nothing} = nothing,
-    lodf::Union{Matrix{Float64},Nothing} = nothing,
-    isf_cutoff::Float64 = 0.005,
-    lodf_cutoff::Float64 = 0.001,
-    optimizer = nothing,
-    variable_names::Bool = false,
-)::JuMP.Model
-    if (filename === nothing) && (instance === nothing)
-        error("Either filename or instance must be specified")
-    end
-
-    if filename !== nothing
-        @info "Reading: $(filename)"
-        time_read = @elapsed begin
-            instance = UnitCommitment.read(filename)
-        end
-        @info @sprintf("Read problem in %.2f seconds", time_read)
-    end
-
-    if length(instance.buses) == 1
-        isf = zeros(0, 0)
-        lodf = zeros(0, 0)
-    else
-        if isf === nothing
-            @info "Computing injection shift factors..."
-            time_isf = @elapsed begin
-                isf = UnitCommitment._injection_shift_factors(
-                    lines = instance.lines,
-                    buses = instance.buses,
-                )
-            end
-            @info @sprintf("Computed ISF in %.2f seconds", time_isf)
-
-            @info "Computing line outage factors..."
-            time_lodf = @elapsed begin
-                lodf = UnitCommitment._line_outage_factors(
-                    lines = instance.lines,
-                    buses = instance.buses,
-                    isf = isf,
-                )
-            end
-            @info @sprintf("Computed LODF in %.2f seconds", time_lodf)
-
-            @info @sprintf(
-                "Applying PTDF and LODF cutoffs (%.5f, %.5f)",
-                isf_cutoff,
-                lodf_cutoff
-            )
-            isf[abs.(isf).<isf_cutoff] .= 0
-            lodf[abs.(lodf).<lodf_cutoff] .= 0
-        end
-    end
-
-    @info "Building model..."
-    time_model = @elapsed begin
-        model = Model()
-        if optimizer !== nothing
-            set_optimizer(model, optimizer)
-        end
-        model[:obj] = AffExpr()
-        model[:instance] = instance
-        model[:isf] = isf
-        model[:lodf] = lodf
-        for field in [
-            :prod_above,
-            :segprod,
-            :reserve,
-            :is_on,
-            :switch_on,
-            :switch_off,
-            :net_injection,
-            :curtail,
-            :overflow,
-            :loads,
-            :startup,
-            :eq_startup_choose,
-            :eq_startup_restrict,
-            :eq_segprod_limit,
-            :eq_prod_above_def,
-            :eq_prod_limit,
-            :eq_binary_link,
-            :eq_switch_on_off,
-            :eq_ramp_up,
-            :eq_ramp_down,
-            :eq_startup_limit,
-            :eq_shutdown_limit,
-            :eq_min_uptime,
-            :eq_min_downtime,
-            :eq_power_balance,
-            :eq_net_injection_def,
-            :eq_min_reserve,
-            :expr_inj,
-            :expr_reserve,
-            :expr_net_injection,
-        ]
-            model[field] = OrderedDict()
-        end
-        for lm in instance.lines
-            _add_transmission_line!(model, lm)
-        end
-        for b in instance.buses
-            _add_bus!(model, b)
-        end
-        for g in instance.units
-            _add_unit!(model, g)
-        end
-        for ps in instance.price_sensitive_loads
-            _add_price_sensitive_load!(model, ps)
-        end
-        _build_net_injection_eqs!(model)
-        _build_reserve_eqs!(model)
-        _build_obj_function!(model)
-    end
-    @info @sprintf("Built model in %.2f seconds", time_model)
-
-    if variable_names
-        _set_names!(model)
-    end
-
-    return model
-end
-
-function _add_transmission_line!(model, lm)
-    obj, T = model[:obj], model[:instance].time
-    overflow = model[:overflow]
-    for t in 1:T
-        v = overflow[lm.name, t] = @variable(model, lower_bound = 0)
-        add_to_expression!(obj, v, lm.flow_limit_penalty[t])
-    end
-end
-
-function _add_bus!(model::JuMP.Model, b::Bus)
-    mip = model
-    net_injection = model[:expr_net_injection]
-    reserve = model[:expr_reserve]
-    curtail = model[:curtail]
-    for t in 1:model[:instance].time
-        # Fixed load
-        net_injection[b.name, t] = AffExpr(-b.load[t])
-
-        # Reserves
-        reserve[b.name, t] = AffExpr()
-
-        # Load curtailment
-        curtail[b.name, t] =
-            @variable(mip, lower_bound = 0, upper_bound = b.load[t])
-        add_to_expression!(net_injection[b.name, t], curtail[b.name, t], 1.0)
-        add_to_expression!(
-            model[:obj],
-            curtail[b.name, t],
-            model[:instance].power_balance_penalty[t],
-        )
-    end
-end
-
-function _add_price_sensitive_load!(model::JuMP.Model, ps::PriceSensitiveLoad)
-    mip = model
-    loads = model[:loads]
-    net_injection = model[:expr_net_injection]
-    for t in 1:model[:instance].time
-        # Decision variable
-        loads[ps.name, t] =
-            @variable(mip, lower_bound = 0, upper_bound = ps.demand[t])
-
-        # Objective function terms
-        add_to_expression!(model[:obj], loads[ps.name, t], -ps.revenue[t])
-
-        # Net injection
-        add_to_expression!(
-            net_injection[ps.bus.name, t],
-            loads[ps.name, t],
-            -1.0,
-        )
-    end
-end
-
-function _add_unit!(model::JuMP.Model, g::Unit)
-    mip, T = model, model[:instance].time
-    gi, K, S = g.name, length(g.cost_segments), length(g.startup_categories)
-
-    segprod = model[:segprod]
-    prod_above = model[:prod_above]
-    reserve = model[:reserve]
-    startup = model[:startup]
-    is_on = model[:is_on]
-    switch_on = model[:switch_on]
-    switch_off = model[:switch_off]
-    expr_net_injection = model[:expr_net_injection]
-    expr_reserve = model[:expr_reserve]
-
-    if !all(g.must_run) && any(g.must_run)
-        error("Partially must-run units are not currently supported")
-    end
-
-    if g.initial_power === nothing || g.initial_status === nothing
-        error("Initial conditions for $(g.name) must be provided")
-    end
-
-    is_initially_on = (g.initial_status > 0 ? 1.0 : 0.0)
-
-    # Decision variables
-    for t in 1:T
-        for k in 1:K
-            segprod[gi, t, k] = @variable(model, lower_bound = 0)
-        end
-        prod_above[gi, t] = @variable(model, lower_bound = 0)
-        if g.provides_spinning_reserves[t]
-            reserve[gi, t] = @variable(model, lower_bound = 0)
-        else
-            reserve[gi, t] = 0.0
-        end
-        for s in 1:S
-            startup[gi, t, s] = @variable(model, binary = true)
-        end
-        if g.must_run[t]
-            is_on[gi, t] = 1.0
-            switch_on[gi, t] = (t == 1 ? 1.0 - is_initially_on : 0.0)
-            switch_off[gi, t] = 0.0
-        else
-            is_on[gi, t] = @variable(model, binary = true)
-            switch_on[gi, t] = @variable(model, binary = true)
-            switch_off[gi, t] = @variable(model, binary = true)
-        end
-    end
-
-    for t in 1:T
-        # Time-dependent start-up costs
-        for s in 1:S
-            # If unit is switching on, we must choose a startup category
-            model[:eq_startup_choose][gi, t, s] = @constraint(
-                mip,
-                switch_on[gi, t] == sum(startup[gi, t, s] for s in 1:S)
-            )
-
-            # If unit has not switched off in the last `delay` time periods, startup category is forbidden.
-            # The last startup category is always allowed.
-            if s < S
-                range_start = t - g.startup_categories[s+1].delay + 1
-                range_end = t - g.startup_categories[s].delay
-                range = (range_start:range_end)
-                initial_sum = (
-                    g.initial_status < 0 && (g.initial_status + 1 in range) ? 1.0 : 0.0
-                )
-                model[:eq_startup_restrict][gi, t, s] = @constraint(
-                    mip,
-                    startup[gi, t, s] <=
-                    initial_sum +
-                    sum(switch_off[gi, i] for i in range if i >= 1)
-                )
-            end
-
-            # Objective function terms for start-up costs
-            add_to_expression!(
-                model[:obj],
-                startup[gi, t, s],
-                g.startup_categories[s].cost,
-            )
-        end
-
-        # Objective function terms for production costs
-        add_to_expression!(model[:obj], is_on[gi, t], g.min_power_cost[t])
-        for k in 1:K
-            add_to_expression!(
-                model[:obj],
-                segprod[gi, t, k],
-                g.cost_segments[k].cost[t],
-            )
-        end
-
-        # Production limits (piecewise-linear segments)
-        for k in 1:K
-            model[:eq_segprod_limit][gi, t, k] = @constraint(
-                mip,
-                segprod[gi, t, k] <= g.cost_segments[k].mw[t] * is_on[gi, t]
-            )
-        end
-
-        # Definition of production
-        model[:eq_prod_above_def][gi, t] = @constraint(
-            mip,
-            prod_above[gi, t] == sum(segprod[gi, t, k] for k in 1:K)
-        )
-
-        # Production limit
-        model[:eq_prod_limit][gi, t] = @constraint(
-            mip,
-            prod_above[gi, t] + reserve[gi, t] <=
-            (g.max_power[t] - g.min_power[t]) * is_on[gi, t]
-        )
-
-        # Binary variable equations for economic units
-        if !g.must_run[t]
-
-            # Link binary variables
-            if t == 1
-                model[:eq_binary_link][gi, t] = @constraint(
-                    mip,
-                    is_on[gi, t] - is_initially_on ==
-                    switch_on[gi, t] - switch_off[gi, t]
-                )
-            else
-                model[:eq_binary_link][gi, t] = @constraint(
-                    mip,
-                    is_on[gi, t] - is_on[gi, t-1] ==
-                    switch_on[gi, t] - switch_off[gi, t]
-                )
-            end
-
-            # Cannot switch on and off at the same time
-            model[:eq_switch_on_off][gi, t] =
-                @constraint(mip, switch_on[gi, t] + switch_off[gi, t] <= 1)
-        end
-
-        # Ramp up limit
-        if t == 1
-            if is_initially_on == 1
-                model[:eq_ramp_up][gi, t] = @constraint(
-                    mip,
-                    prod_above[gi, t] + reserve[gi, t] <=
-                    (g.initial_power - g.min_power[t]) + g.ramp_up_limit
-                )
-            end
-        else
-            model[:eq_ramp_up][gi, t] = @constraint(
-                mip,
-                prod_above[gi, t] + reserve[gi, t] <=
-                prod_above[gi, t-1] + g.ramp_up_limit
-            )
-        end
-
-        # Ramp down limit
-        if t == 1
-            if is_initially_on == 1
-                model[:eq_ramp_down][gi, t] = @constraint(
-                    mip,
-                    prod_above[gi, t] >=
-                    (g.initial_power - g.min_power[t]) - g.ramp_down_limit
-                )
-            end
-        else
-            model[:eq_ramp_down][gi, t] = @constraint(
-                mip,
-                prod_above[gi, t] >= prod_above[gi, t-1] - g.ramp_down_limit
-            )
-        end
-
-        # Startup limit
-        model[:eq_startup_limit][gi, t] = @constraint(
-            mip,
-            prod_above[gi, t] + reserve[gi, t] <=
-            (g.max_power[t] - g.min_power[t]) * is_on[gi, t] -
-            max(0, g.max_power[t] - g.startup_limit) * switch_on[gi, t]
-        )
-
-        # Shutdown limit
-        if g.initial_power > g.shutdown_limit
-            model[:eq_shutdown_limit][gi, 0] =
-                @constraint(mip, switch_off[gi, 1] <= 0)
-        end
-        if t < T
-            model[:eq_shutdown_limit][gi, t] = @constraint(
-                mip,
-                prod_above[gi, t] <=
-                (g.max_power[t] - g.min_power[t]) * is_on[gi, t] -
-                max(0, g.max_power[t] - g.shutdown_limit) * switch_off[gi, t+1]
-            )
-        end
-
-        # Minimum up-time
-        model[:eq_min_uptime][gi, t] = @constraint(
-            mip,
-            sum(switch_on[gi, i] for i in (t-g.min_uptime+1):t if i >= 1) <=
-            is_on[gi, t]
-        )
-
-        # # Minimum down-time
-        model[:eq_min_downtime][gi, t] = @constraint(
-            mip,
-            sum(switch_off[gi, i] for i in (t-g.min_downtime+1):t if i >= 1) <= 1 - is_on[gi, t]
-        )
-
-        # Minimum up/down-time for initial periods
-        if t == 1
-            if g.initial_status > 0
-                model[:eq_min_uptime][gi, 0] = @constraint(
-                    mip,
-                    sum(
-                        switch_off[gi, i] for
-                        i in 1:(g.min_uptime-g.initial_status) if i <= T
-                    ) == 0
-                )
-            else
-                model[:eq_min_downtime][gi, 0] = @constraint(
-                    mip,
-                    sum(
-                        switch_on[gi, i] for
-                        i in 1:(g.min_downtime+g.initial_status) if i <= T
-                    ) == 0
-                )
-            end
-        end
-
-        # Add to net injection expression
-        add_to_expression!(
-            expr_net_injection[g.bus.name, t],
-            prod_above[g.name, t],
-            1.0,
-        )
-        add_to_expression!(
-            expr_net_injection[g.bus.name, t],
-            is_on[g.name, t],
-            g.min_power[t],
-        )
-
-        # Add to reserves expression
-        add_to_expression!(expr_reserve[g.bus.name, t], reserve[gi, t], 1.0)
-    end
-end
-
-function _build_obj_function!(model::JuMP.Model)
-    @objective(model, Min, model[:obj])
-end
-
-function _build_net_injection_eqs!(model::JuMP.Model)
-    T = model[:instance].time
-    net_injection = model[:net_injection]
-    for t in 1:T, b in model[:instance].buses
-        n = net_injection[b.name, t] = @variable(model)
-        model[:eq_net_injection_def][t, b.name] =
-            @constraint(model, n == model[:expr_net_injection][b.name, t])
-    end
-    for t in 1:T
-        model[:eq_power_balance][t] = @constraint(
-            model,
-            sum(net_injection[b.name, t] for b in model[:instance].buses) == 0
-        )
-    end
-end
-
-function _build_reserve_eqs!(model::JuMP.Model)
-    reserves = model[:instance].reserves
-    for t in 1:model[:instance].time
-        model[:eq_min_reserve][t] = @constraint(
-            model,
-            sum(
-                model[:expr_reserve][b.name, t] for b in model[:instance].buses
-            ) >= reserves.spinning[t]
-        )
-    end
-end
-
-function _enforce_transmission(;
-    model::JuMP.Model,
-    violation::Violation,
-    isf::Matrix{Float64},
-    lodf::Matrix{Float64},
-)::Nothing
-    instance = model[:instance]
-    limit::Float64 = 0.0
-    overflow = model[:overflow]
-    net_injection = model[:net_injection]
-
-    if violation.outage_line === nothing
-        limit = violation.monitored_line.normal_flow_limit[violation.time]
-        @info @sprintf(
-            "    %8.3f MW overflow in %-5s time %3d (pre-contingency)",
-            violation.amount,
-            violation.monitored_line.name,
-            violation.time,
-        )
-    else
-        limit = violation.monitored_line.emergency_flow_limit[violation.time]
-        @info @sprintf(
-            "    %8.3f MW overflow in %-5s time %3d (outage: line %s)",
-            violation.amount,
-            violation.monitored_line.name,
-            violation.time,
-            violation.outage_line.name,
-        )
-    end
-
-    fm = violation.monitored_line.name
-    t = violation.time
-    flow = @variable(model, base_name = "flow[$fm,$t]")
-
-    v = overflow[violation.monitored_line.name, violation.time]
-    @constraint(model, flow <= limit + v)
-    @constraint(model, -flow <= limit + v)
-
-    if violation.outage_line === nothing
-        @constraint(
-            model,
-            flow == sum(
-                net_injection[b.name, violation.time] *
-                isf[violation.monitored_line.offset, b.offset] for
-                b in instance.buses if b.offset > 0
-            )
-        )
-    else
-        @constraint(
-            model,
-            flow == sum(
-                net_injection[b.name, violation.time] * (
-                    isf[violation.monitored_line.offset, b.offset] + (
-                        lodf[
-                            violation.monitored_line.offset,
-                            violation.outage_line.offset,
-                        ] * isf[violation.outage_line.offset, b.offset]
-                    )
-                ) for b in instance.buses if b.offset > 0
-            )
-        )
-    end
-    return nothing
-end
-
-function _set_names!(model::JuMP.Model)
-    @info "Setting variable and constraint names..."
-    time_varnames = @elapsed begin
-        _set_names!(object_dictionary(model))
-    end
-    @info @sprintf("Set names in %.2f seconds", time_varnames)
-end
-
-function _set_names!(dict::Dict)
-    for name in keys(dict)
-        dict[name] isa AbstractDict || continue
-        for idx in keys(dict[name])
-            if dict[name][idx] isa AffExpr
-                continue
-            end
-            idx_str = join(map(string, idx), ",")
-            set_name(dict[name][idx], "$name[$idx_str]")
-        end
-    end
-end
-
-function solution(model::JuMP.Model)
-    instance, T = model[:instance], model[:instance].time
-    function timeseries(vars, collection)
-        return OrderedDict(
-            b.name => [round(value(vars[b.name, t]), digits = 5) for t in 1:T]
-            for b in collection
-        )
-    end
-    function production_cost(g)
-        return [
-            value(model[:is_on][g.name, t]) * g.min_power_cost[t] + sum(
-                Float64[
-                    value(model[:segprod][g.name, t, k]) *
-                    g.cost_segments[k].cost[t] for
-                    k in 1:length(g.cost_segments)
-                ],
-            ) for t in 1:T
-        ]
-    end
-    function production(g)
-        return [
-            value(model[:is_on][g.name, t]) * g.min_power[t] + sum(
-                Float64[
-                    value(model[:segprod][g.name, t, k]) for
-                    k in 1:length(g.cost_segments)
-                ],
-            ) for t in 1:T
-        ]
-    end
-    function startup_cost(g)
-        S = length(g.startup_categories)
-        return [
-            sum(
-                g.startup_categories[s].cost *
-                value(model[:startup][g.name, t, s]) for s in 1:S
-            ) for t in 1:T
-        ]
-    end
-    sol = OrderedDict()
-    sol["Production (MW)"] =
-        OrderedDict(g.name => production(g) for g in instance.units)
-    sol["Production cost (\$)"] =
-        OrderedDict(g.name => production_cost(g) for g in instance.units)
-    sol["Startup cost (\$)"] =
-        OrderedDict(g.name => startup_cost(g) for g in instance.units)
-    sol["Is on"] = timeseries(model[:is_on], instance.units)
-    sol["Switch on"] = timeseries(model[:switch_on], instance.units)
-    sol["Switch off"] = timeseries(model[:switch_off], instance.units)
-    sol["Reserve (MW)"] = timeseries(model[:reserve], instance.units)
-    sol["Net injection (MW)"] =
-        timeseries(model[:net_injection], instance.buses)
-    sol["Load curtail (MW)"] = timeseries(model[:curtail], instance.buses)
-    if !isempty(instance.lines)
-        sol["Line overflow (MW)"] = timeseries(model[:overflow], instance.lines)
-    end
-    if !isempty(instance.price_sensitive_loads)
-        sol["Price-sensitive loads (MW)"] =
-            timeseries(model[:loads], instance.price_sensitive_loads)
-    end
-    return sol
-end
-
-function write(filename::AbstractString, solution::AbstractDict)::Nothing
-    open(filename, "w") do file
-        return JSON.print(file, solution, 2)
-    end
-    return
-end
-
-function fix!(model::JuMP.Model, solution::AbstractDict)::Nothing
-    instance, T = model[:instance], model[:instance].time
-    is_on = model[:is_on]
-    prod_above = model[:prod_above]
-    reserve = model[:reserve]
-    for g in instance.units
-        for t in 1:T
-            is_on_value = round(solution["Is on"][g.name][t])
-            production_value =
-                round(solution["Production (MW)"][g.name][t], digits = 5)
-            reserve_value =
-                round(solution["Reserve (MW)"][g.name][t], digits = 5)
-            JuMP.fix(is_on[g.name, t], is_on_value, force = true)
-            JuMP.fix(
-                prod_above[g.name, t],
-                production_value - is_on_value * g.min_power[t],
-                force = true,
-            )
-            JuMP.fix(reserve[g.name, t], reserve_value, force = true)
-        end
-    end
-    return
-end
-
-function set_warm_start!(model::JuMP.Model, solution::AbstractDict)::Nothing
-    instance, T = model[:instance], model[:instance].time
-    is_on = model[:is_on]
-    prod_above = model[:prod_above]
-    reserve = model[:reserve]
-    for g in instance.units
-        for t in 1:T
-            JuMP.set_start_value(is_on[g.name, t], solution["Is on"][g.name][t])
-            JuMP.set_start_value(
-                switch_on[g.name, t],
-                solution["Switch on"][g.name][t],
-            )
-            JuMP.set_start_value(
-                switch_off[g.name, t],
-                solution["Switch off"][g.name][t],
-            )
-        end
-    end
-    return
-end
-
-function optimize!(
-    model::JuMP.Model;
-    time_limit = 3600,
-    gap_limit = 1e-4,
-    two_phase_gap = true,
-)::Nothing
-    function set_gap(gap)
-        try
-            JuMP.set_optimizer_attribute(model, "MIPGap", gap)
-            @info @sprintf("MIP gap tolerance set to %f", gap)
-        catch
-            @warn "Could not change MIP gap tolerance"
-        end
-    end
-
-    instance = model[:instance]
-    initial_time = time()
-
-    large_gap = false
-    has_transmission = (length(model[:isf]) > 0)
-
-    if has_transmission && two_phase_gap
-        set_gap(1e-2)
-        large_gap = true
-    else
-        set_gap(gap_limit)
-    end
-
-    while true
-        time_elapsed = time() - initial_time
-        time_remaining = time_limit - time_elapsed
-        if time_remaining < 0
-            @info "Time limit exceeded"
-            break
-        end
-
-        @info @sprintf(
-            "Setting MILP time limit to %.2f seconds",
-            time_remaining
-        )
-        JuMP.set_time_limit_sec(model, time_remaining)
-
-        @info "Solving MILP..."
-        JuMP.optimize!(model)
-
-        has_transmission || break
-
-        violations = _find_violations(model)
-        if isempty(violations)
-            @info "No violations found"
-            if large_gap
-                large_gap = false
-                set_gap(gap_limit)
-            else
-                break
-            end
-        else
-            _enforce_transmission(model, violations)
-        end
-    end
-
-    return
-end
-
-function _find_violations(model::JuMP.Model)
-    instance = model[:instance]
-    net_injection = model[:net_injection]
-    overflow = model[:overflow]
-    length(instance.buses) > 1 || return []
-    violations = []
-    @info "Verifying transmission limits..."
-    time_screening = @elapsed begin
-        non_slack_buses = [b for b in instance.buses if b.offset > 0]
-        net_injection_values = [
-            value(net_injection[b.name, t]) for b in non_slack_buses,
-            t in 1:instance.time
-        ]
-        overflow_values = [
-            value(overflow[lm.name, t]) for lm in instance.lines,
-            t in 1:instance.time
-        ]
-        violations = UnitCommitment._find_violations(
-            instance = instance,
-            net_injections = net_injection_values,
-            overflow = overflow_values,
-            isf = model[:isf],
-            lodf = model[:lodf],
-        )
-    end
-    @info @sprintf(
-        "Verified transmission limits in %.2f seconds",
-        time_screening
-    )
-    return violations
-end
-
-function _enforce_transmission(
-    model::JuMP.Model,
-    violations::Vector{Violation},
-)::Nothing
-    for v in violations
-        _enforce_transmission(
-            model = model,
-            violation = v,
-            isf = model[:isf],
-            lodf = model[:lodf],
-        )
-    end
-    return
-end
-
-export build_model

src/model/build.jl

@@ -0,0 +1,64 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+using JuMP, MathOptInterface, DataStructures
+import JuMP: value, fix, set_name
+
+"""
+    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 build_model(;
+    instance::UnitCommitmentInstance,
+    optimizer = nothing,
+    formulation = Formulation(),
+    variable_names::Bool = false,
+)::JuMP.Model
+    @info "Building model..."
+    time_model = @elapsed begin
+        model = Model()
+        if optimizer !== nothing
+            set_optimizer(model, optimizer)
+        end
+        model[:obj] = AffExpr()
+        model[:instance] = instance
+        _setup_transmission(model, formulation.transmission)
+        for l in instance.lines
+            _add_transmission_line!(model, l, formulation.transmission)
+        end
+        for b in instance.buses
+            _add_bus!(model, b)
+        end
+        for g in instance.units
+            _add_unit!(model, g, formulation)
+        end
+        for ps in instance.price_sensitive_loads
+            _add_price_sensitive_load!(model, ps)
+        end
+        _add_system_wide_eqs!(model)
+        @objective(model, Min, model[:obj])
+    end
+    @info @sprintf("Built model in %.2f seconds", time_model)
+    if variable_names
+        _set_names!(model)
+    end
+    return model
+end

src/model/formulations/ArrCon2000/ramp.jl

@@ -0,0 +1,98 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function _add_ramp_eqs!(
+    model::JuMP.Model,
+    g::Unit,
+    formulation_prod_vars::Gar1962.ProdVars,
+    formulation_ramping::ArrCon2000.Ramping,
+    formulation_status_vars::Gar1962.StatusVars,
+)::Nothing
+    # TODO: Move upper case constants to model[:instance]
+    RESERVES_WHEN_START_UP = true
+    RESERVES_WHEN_RAMP_UP = true
+    RESERVES_WHEN_RAMP_DOWN = true
+    RESERVES_WHEN_SHUT_DOWN = true
+    gn = g.name
+    RU = g.ramp_up_limit
+    RD = g.ramp_down_limit
+    SU = g.startup_limit
+    SD = g.shutdown_limit
+    reserve = model[:reserve]
+    eq_ramp_down = _init(model, :eq_ramp_down)
+    eq_ramp_up = _init(model, :eq_ramp_up)
+    is_initially_on = (g.initial_status > 0)
+
+    # Gar1962.ProdVars
+    prod_above = model[:prod_above]
+
+    # Gar1962.StatusVars
+    is_on = model[:is_on]
+    switch_off = model[:switch_off]
+    switch_on = model[:switch_on]
+
+    for t in 1:model[:instance].time
+        # Ramp up limit
+        if t == 1
+            if is_initially_on
+                # min power is _not_ multiplied by is_on because if !is_on, then ramp up is irrelevant
+                eq_ramp_up[gn, t] = @constraint(
+                    model,
+                    g.min_power[t] +
+                    prod_above[gn, t] +
+                    (RESERVES_WHEN_RAMP_UP ? reserve[gn, t] : 0.0) <=
+                    g.initial_power + RU
+                )
+            end
+        else
+            max_prod_this_period =
+                g.min_power[t] * is_on[gn, t] +
+                prod_above[gn, t] +
+                (
+                    RESERVES_WHEN_START_UP || RESERVES_WHEN_RAMP_UP ?
+                    reserve[gn, t] : 0.0
+                )
+            min_prod_last_period =
+                g.min_power[t-1] * is_on[gn, t-1] + prod_above[gn, t-1]
+
+            # Equation (24) in Kneuven et al. (2020)
+            eq_ramp_up[gn, t] = @constraint(
+                model,
+                max_prod_this_period - min_prod_last_period <=
+                RU * is_on[gn, t-1] + SU * switch_on[gn, t]
+            )
+        end
+
+        # Ramp down limit
+        if t == 1
+            if is_initially_on
+                # TODO If RD < SD, or more specifically if
+                #      min_power + RD < initial_power < SD
+                #      then the generator should be able to shut down at time t = 1,
+                #      but the constraint below will force the unit to produce power
+                eq_ramp_down[gn, t] = @constraint(
+                    model,
+                    g.initial_power - (g.min_power[t] + prod_above[gn, t]) <= RD
+                )
+            end
+        else
+            max_prod_last_period =
+                g.min_power[t-1] * is_on[gn, t-1] +
+                prod_above[gn, t-1] +
+                (
+                    RESERVES_WHEN_SHUT_DOWN || RESERVES_WHEN_RAMP_DOWN ?
+                    reserve[gn, t-1] : 0.0
+                )
+            min_prod_this_period =
+                g.min_power[t] * is_on[gn, t] + prod_above[gn, t]
+
+            # Equation (25) in Kneuven et al. (2020)
+            eq_ramp_down[gn, t] = @constraint(
+                model,
+                max_prod_last_period - min_prod_this_period <=
+                RD * is_on[gn, t] + SD * switch_off[gn, t]
+            )
+        end
+    end
+end

src/model/formulations/ArrCon2000/structs.jl

@@ -0,0 +1,18 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+"""
+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
+"""
+module ArrCon2000
+
+import ..RampingFormulation
+
+struct Ramping <: RampingFormulation end
+
+end

src/model/formulations/CarArr2006/pwlcosts.jl

@@ -0,0 +1,54 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function _add_production_piecewise_linear_eqs!(
+    model::JuMP.Model,
+    g::Unit,
+    formulation_prod_vars::Gar1962.ProdVars,
+    formulation_pwl_costs::CarArr2006.PwlCosts,
+    formulation_status_vars::StatusVarsFormulation,
+)::Nothing
+    eq_prod_above_def = _init(model, :eq_prod_above_def)
+    eq_segprod_limit = _init(model, :eq_segprod_limit)
+    segprod = model[:segprod]
+    gn = g.name
+
+    # Gar1962.ProdVars
+    prod_above = model[:prod_above]
+
+    K = length(g.cost_segments)
+    for t in 1:model[:instance].time
+        gn = g.name
+        for k in 1:K
+            # Equation (45) in Kneuven et al. (2020)
+            # NB: when reading instance, UnitCommitment.jl already calculates
+            #     difference between max power for segments k and k-1 so the
+            #     value of cost_segments[k].mw[t] is the max production *for
+            #     that segment*
+            eq_segprod_limit[gn, t, k] = @constraint(
+                model,
+                segprod[gn, t, k] <= g.cost_segments[k].mw[t]
+            )
+
+            # Also add this as an explicit upper bound on segprod to make the
+            # solver's work a bit easier
+            set_upper_bound(segprod[gn, t, k], g.cost_segments[k].mw[t])
+
+            # Definition of production
+            # Equation (43) in Kneuven et al. (2020)
+            eq_prod_above_def[gn, t] = @constraint(
+                model,
+                prod_above[gn, t] == sum(segprod[gn, t, k] for k in 1:K)
+            )
+
+            # Objective function
+            # Equation (44) in Kneuven et al. (2020)
+            add_to_expression!(
+                model[:obj],
+                segprod[gn, t, k],
+                g.cost_segments[k].cost[t],
+            )
+        end
+    end
+end

src/model/formulations/CarArr2006/structs.jl

@@ -0,0 +1,19 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+"""
+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
+"""
+module CarArr2006
+
+import ..PiecewiseLinearCostsFormulation
+
+struct PwlCosts <: PiecewiseLinearCostsFormulation end
+
+end

src/model/formulations/DamKucRajAta2016/ramp.jl

@@ -0,0 +1,122 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function _add_ramp_eqs!(
+    model::JuMP.Model,
+    g::Unit,
+    formulation_prod_vars::Gar1962.ProdVars,
+    formulation_ramping::DamKucRajAta2016.Ramping,
+    formulation_status_vars::Gar1962.StatusVars,
+)::Nothing
+    # TODO: Move upper case constants to model[:instance]
+    RESERVES_WHEN_START_UP = true
+    RESERVES_WHEN_RAMP_UP = true
+    RESERVES_WHEN_RAMP_DOWN = true
+    RESERVES_WHEN_SHUT_DOWN = true
+    known_initial_conditions = true
+    is_initially_on = (g.initial_status > 0)
+    SU = g.startup_limit
+    SD = g.shutdown_limit
+    RU = g.ramp_up_limit
+    RD = g.ramp_down_limit
+    gn = g.name
+    eq_str_ramp_down = _init(model, :eq_str_ramp_down)
+    eq_str_ramp_up = _init(model, :eq_str_ramp_up)
+    reserve = model[:reserve]
+
+    # Gar1962.ProdVars
+    prod_above = model[:prod_above]
+
+    # Gar1962.StatusVars
+    is_on = model[:is_on]
+    switch_off = model[:switch_off]
+    switch_on = model[:switch_on]
+
+    for t in 1:model[:instance].time
+        time_invariant =
+            (t > 1) ? (abs(g.min_power[t] - g.min_power[t-1]) < 1e-7) : true
+
+        # if t > 1 && !time_invariant
+        #     @warn(
+        #         "Ramping according to Damcı-Kurt et al. (2016) requires " *
+        #         "time-invariant minimum power. This does not hold for " *
+        #         "generator $(gn): min_power[$t] = $(g.min_power[t]); " *
+        #         "min_power[$(t-1)] = $(g.min_power[t-1]). Reverting to " *
+        #         "Arroyo and Conejo (2000) formulation for this generator.",
+        #     )
+        # end
+
+        max_prod_this_period =
+            prod_above[gn, t] + (
+                RESERVES_WHEN_START_UP || RESERVES_WHEN_RAMP_UP ?
+                reserve[gn, t] : 0.0
+            )
+        min_prod_last_period = 0.0
+        if t > 1 && time_invariant
+            min_prod_last_period = prod_above[gn, t-1]
+
+            # Equation (35) in Kneuven et al. (2020)
+            # Sparser version of (24)
+            eq_str_ramp_up[gn, t] = @constraint(
+                model,
+                max_prod_this_period - min_prod_last_period <=
+                (SU - g.min_power[t] - RU) * switch_on[gn, t] +
+                RU * is_on[gn, t]
+            )
+        elseif (t == 1 && is_initially_on) || (t > 1 && !time_invariant)
+            if t > 1
+                min_prod_last_period =
+                    prod_above[gn, t-1] + g.min_power[t-1] * is_on[gn, t-1]
+            else
+                min_prod_last_period = max(g.initial_power, 0.0)
+            end
+
+            # Add the min prod at time t back in to max_prod_this_period to get _total_ production
+            # (instead of using the amount above minimum, as min prod for t < 1 is unknown)
+            max_prod_this_period += g.min_power[t] * is_on[gn, t]
+
+            # Modified version of equation (35) in Kneuven et al. (2020)
+            # Equivalent to (24)
+            eq_str_ramp_up[gn, t] = @constraint(
+                model,
+                max_prod_this_period - min_prod_last_period <=
+                (SU - RU) * switch_on[gn, t] + RU * is_on[gn, t]
+            )
+        end
+
+        max_prod_last_period =
+            min_prod_last_period + (
+                t > 1 && (RESERVES_WHEN_SHUT_DOWN || RESERVES_WHEN_RAMP_DOWN) ?
+                reserve[gn, t-1] : 0.0
+            )
+        min_prod_this_period = prod_above[gn, t]
+        on_last_period = 0.0
+        if t > 1
+            on_last_period = is_on[gn, t-1]
+        elseif (known_initial_conditions && g.initial_status > 0)
+            on_last_period = 1.0
+        end
+
+        if t > 1 && time_invariant
+            # Equation (36) in Kneuven et al. (2020)
+            eq_str_ramp_down[gn, t] = @constraint(
+                model,
+                max_prod_last_period - min_prod_this_period <=
+                (SD - g.min_power[t] - RD) * switch_off[gn, t] +
+                RD * on_last_period
+            )
+        elseif (t == 1 && is_initially_on) || (t > 1 && !time_invariant)
+            # Add back in min power
+            min_prod_this_period += g.min_power[t] * is_on[gn, t]
+
+            # Modified version of equation (36) in Kneuven et al. (2020)
+            # Equivalent to (25)
+            eq_str_ramp_down[gn, t] = @constraint(
+                model,
+                max_prod_last_period - min_prod_this_period <=
+                (SD - RD) * switch_off[gn, t] + RD * on_last_period
+            )
+        end
+    end
+end

src/model/formulations/DamKucRajAta2016/structs.jl

@@ -0,0 +1,18 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+"""
+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
+"""
+module DamKucRajAta2016
+
+import ..RampingFormulation
+
+struct Ramping <: RampingFormulation end
+
+end

src/model/formulations/Gar1962/prod.jl

@@ -0,0 +1,50 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function _add_production_vars!(
+    model::JuMP.Model,
+    g::Unit,
+    formulation_prod_vars::Gar1962.ProdVars,
+)::Nothing
+    prod_above = _init(model, :prod_above)
+    segprod = _init(model, :segprod)
+    for t in 1:model[:instance].time
+        for k in 1:length(g.cost_segments)
+            segprod[g.name, t, k] = @variable(model, lower_bound = 0)
+        end
+        prod_above[g.name, t] = @variable(model, lower_bound = 0)
+    end
+    return
+end
+
+function _add_production_limit_eqs!(
+    model::JuMP.Model,
+    g::Unit,
+    formulation_prod_vars::Gar1962.ProdVars,
+)::Nothing
+    eq_prod_limit = _init(model, :eq_prod_limit)
+    is_on = model[:is_on]
+    prod_above = model[:prod_above]
+    reserve = model[:reserve]
+    gn = g.name
+    for t in 1:model[:instance].time
+        # Objective function terms for production costs
+        # Part of (69) of Kneuven et al. (2020) as C^R_g * u_g(t) term
+        add_to_expression!(model[:obj], is_on[gn, t], g.min_power_cost[t])
+
+        # Production limit
+        # Equation (18) in Kneuven et al. (2020)
+        #   as \bar{p}_g(t) \le \bar{P}_g u_g(t)
+        # amk: this is a weaker version of (20) and (21) in Kneuven et al. (2020)
+        #      but keeping it here in case those are not present
+        power_diff = max(g.max_power[t], 0.0) - max(g.min_power[t], 0.0)
+        if power_diff < 1e-7
+            power_diff = 0.0
+        end
+        eq_prod_limit[gn, t] = @constraint(
+            model,
+            prod_above[gn, t] + reserve[gn, t] <= power_diff * is_on[gn, t]
+        )
+    end
+end

src/model/formulations/Gar1962/pwlcosts.jl

@@ -0,0 +1,59 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function _add_production_piecewise_linear_eqs!(
+    model::JuMP.Model,
+    g::Unit,
+    formulation_prod_vars::Gar1962.ProdVars,
+    formulation_pwl_costs::Gar1962.PwlCosts,
+    formulation_status_vars::Gar1962.StatusVars,
+)::Nothing
+    eq_prod_above_def = _init(model, :eq_prod_above_def)
+    eq_segprod_limit = _init(model, :eq_segprod_limit)
+    segprod = model[:segprod]
+    gn = g.name
+
+    # Gar1962.ProdVars
+    prod_above = model[:prod_above]
+
+    # Gar1962.StatusVars
+    is_on = model[:is_on]
+
+    K = length(g.cost_segments)
+    for t in 1:model[:instance].time
+        # Definition of production
+        # Equation (43) in Kneuven et al. (2020)
+        eq_prod_above_def[gn, t] = @constraint(
+            model,
+            prod_above[gn, t] == sum(segprod[gn, t, k] for k in 1:K)
+        )
+
+        for k in 1:K
+            # Equation (42) in Kneuven et al. (2020)
+            # Without this, solvers will add a lot of implied bound cuts to
+            # have this same effect.
+            # NB: when reading instance, UnitCommitment.jl already calculates
+            #     difference between max power for segments k and k-1 so the
+            #     value of cost_segments[k].mw[t] is the max production *for
+            #     that segment*
+            eq_segprod_limit[gn, t, k] = @constraint(
+                model,
+                segprod[gn, t, k] <= g.cost_segments[k].mw[t] * is_on[gn, t]
+            )
+
+            # Also add this as an explicit upper bound on segprod to make the
+            # solver's work a bit easier
+            set_upper_bound(segprod[gn, t, k], g.cost_segments[k].mw[t])
+
+            # Objective function
+            # Equation (44) in Kneuven et al. (2020)
+            add_to_expression!(
+                model[:obj],
+                segprod[gn, t, k],
+                g.cost_segments[k].cost[t],
+            )
+        end
+    end
+    return
+end

src/model/formulations/Gar1962/status.jl

@@ -0,0 +1,61 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function _add_status_vars!(
+    model::JuMP.Model,
+    g::Unit,
+    formulation_status_vars::Gar1962.StatusVars,
+)::Nothing
+    is_on = _init(model, :is_on)
+    switch_on = _init(model, :switch_on)
+    switch_off = _init(model, :switch_off)
+    for t in 1:model[:instance].time
+        if g.must_run[t]
+            is_on[g.name, t] = 1.0
+            switch_on[g.name, t] = (t == 1 ? 1.0 - _is_initially_on(g) : 0.0)
+            switch_off[g.name, t] = 0.0
+        else
+            is_on[g.name, t] = @variable(model, binary = true)
+            switch_on[g.name, t] = @variable(model, binary = true)
+            switch_off[g.name, t] = @variable(model, binary = true)
+        end
+    end
+    return
+end
+
+function _add_status_eqs!(
+    model::JuMP.Model,
+    g::Unit,
+    formulation_status_vars::Gar1962.StatusVars,
+)::Nothing
+    eq_binary_link = _init(model, :eq_binary_link)
+    eq_switch_on_off = _init(model, :eq_switch_on_off)
+    is_on = model[:is_on]
+    switch_off = model[:switch_off]
+    switch_on = model[:switch_on]
+    for t in 1:model[:instance].time
+        if !g.must_run[t]
+            # Link binary variables
+            if t == 1
+                eq_binary_link[g.name, t] = @constraint(
+                    model,
+                    is_on[g.name, t] - _is_initially_on(g) ==
+                    switch_on[g.name, t] - switch_off[g.name, t]
+                )
+            else
+                eq_binary_link[g.name, t] = @constraint(
+                    model,
+                    is_on[g.name, t] - is_on[g.name, t-1] ==
+                    switch_on[g.name, t] - switch_off[g.name, t]
+                )
+            end
+            # Cannot switch on and off at the same time
+            eq_switch_on_off[g.name, t] = @constraint(
+                model,
+                switch_on[g.name, t] + switch_off[g.name, t] <= 1
+            )
+        end
+    end
+    return
+end

src/model/formulations/Gar1962/structs.jl

@@ -0,0 +1,24 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+"""
+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
+
+"""
+module Gar1962
+
+import ..PiecewiseLinearCostsFormulation
+import ..ProductionVarsFormulation
+import ..StatusVarsFormulation
+
+struct ProdVars <: ProductionVarsFormulation end
+struct PwlCosts <: PiecewiseLinearCostsFormulation end
+struct StatusVars <: StatusVarsFormulation end
+
+end

src/model/formulations/KnuOstWat2018/pwlcosts.jl

@@ -0,0 +1,108 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function _add_production_piecewise_linear_eqs!(
+    model::JuMP.Model,
+    g::Unit,
+    formulation_prod_vars::Gar1962.ProdVars,
+    formulation_pwl_costs::KnuOstWat2018.PwlCosts,
+    formulation_status_vars::Gar1962.StatusVars,
+)::Nothing
+    eq_prod_above_def = _init(model, :eq_prod_above_def)
+    eq_segprod_limit_a = _init(model, :eq_segprod_limit_a)
+    eq_segprod_limit_b = _init(model, :eq_segprod_limit_b)
+    eq_segprod_limit_c = _init(model, :eq_segprod_limit_c)
+    segprod = model[:segprod]
+    gn = g.name
+    K = length(g.cost_segments)
+    T = model[:instance].time
+
+    # Gar1962.ProdVars
+    prod_above = model[:prod_above]
+
+    # Gar1962.StatusVars
+    is_on = model[:is_on]
+    switch_on = model[:switch_on]
+    switch_off = model[:switch_off]
+
+    for t in 1:T
+        for k in 1:K
+            # Pbar^{k-1)
+            Pbar0 =
+                g.min_power[t] +
+                (k > 1 ? sum(g.cost_segments[ell].mw[t] for ell in 1:k-1) : 0.0)
+            # Pbar^k
+            Pbar1 = g.cost_segments[k].mw[t] + Pbar0
+
+            Cv = 0.0
+            SU = g.startup_limit   # startup rate
+            if Pbar1 <= SU
+                Cv = 0.0
+            elseif Pbar0 < SU # && Pbar1 > SU
+                Cv = Pbar1 - SU
+            else # Pbar0 >= SU
+                # this will imply that we cannot produce along this segment if
+                # switch_on = 1
+                Cv = g.cost_segments[k].mw[t]
+            end
+            Cw = 0.0
+            SD = g.shutdown_limit  # shutdown rate
+            if Pbar1 <= SD
+                Cw = 0.0
+            elseif Pbar0 < SD # && Pbar1 > SD
+                Cw = Pbar1 - SD
+            else # Pbar0 >= SD
+                Cw = g.cost_segments[k].mw[t]
+            end
+
+            if g.min_uptime > 1
+                # Equation (46) in Kneuven et al. (2020)
+                eq_segprod_limit_a[gn, t, k] = @constraint(
+                    model,
+                    segprod[gn, t, k] <=
+                    g.cost_segments[k].mw[t] * is_on[gn, t] -
+                    Cv * switch_on[gn, t] -
+                    (t < T ? Cw * switch_off[gn, t+1] : 0.0)
+                )
+            else
+                # Equation (47a)/(48a) in Kneuven et al. (2020)
+                eq_segprod_limit_b[gn, t, k] = @constraint(
+                    model,
+                    segprod[gn, t, k] <=
+                    g.cost_segments[k].mw[t] * is_on[gn, t] -
+                    Cv * switch_on[gn, t] -
+                    (t < T ? max(0, Cv - Cw) * switch_off[gn, t+1] : 0.0)
+                )
+
+                # Equation (47b)/(48b) in Kneuven et al. (2020)
+                eq_segprod_limit_c[gn, t, k] = @constraint(
+                    model,
+                    segprod[gn, t, k] <=
+                    g.cost_segments[k].mw[t] * is_on[gn, t] -
+                    max(0, Cw - Cv) * switch_on[gn, t] -
+                    (t < T ? Cw * switch_off[gn, t+1] : 0.0)
+                )
+            end
+
+            # Definition of production
+            # Equation (43) in Kneuven et al. (2020)
+            eq_prod_above_def[gn, t] = @constraint(
+                model,
+                prod_above[gn, t] == sum(segprod[gn, t, k] for k in 1:K)
+            )
+
+            # Objective function
+            # Equation (44) in Kneuven et al. (2020)
+            add_to_expression!(
+                model[:obj],
+                segprod[gn, t, k],
+                g.cost_segments[k].cost[t],
+            )
+
+            # Also add an explicit upper bound on segprod to make the solver's
+            # work a bit easier
+            set_upper_bound(segprod[gn, t, k], g.cost_segments[k].mw[t])
+        end
+    end
+end

src/model/formulations/KnuOstWat2018/structs.jl

@@ -0,0 +1,18 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+"""
+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
+"""
+module KnuOstWat2018
+
+import ..PiecewiseLinearCostsFormulation
+
+struct PwlCosts <: PiecewiseLinearCostsFormulation end
+
+end

src/model/formulations/MorLatRam2013/ramp.jl

@@ -0,0 +1,130 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function _add_ramp_eqs!(
+    model::JuMP.Model,
+    g::Unit,
+    formulation_prod_vars::Gar1962.ProdVars,
+    formulation_ramping::MorLatRam2013.Ramping,
+    formulation_status_vars::Gar1962.StatusVars,
+)::Nothing
+    # TODO: Move upper case constants to model[:instance]
+    RESERVES_WHEN_START_UP = true
+    RESERVES_WHEN_RAMP_UP = true
+    RESERVES_WHEN_RAMP_DOWN = true
+    RESERVES_WHEN_SHUT_DOWN = true
+    is_initially_on = (g.initial_status > 0)
+    SU = g.startup_limit
+    SD = g.shutdown_limit
+    RU = g.ramp_up_limit
+    RD = g.ramp_down_limit
+    gn = g.name
+    eq_ramp_down = _init(model, :eq_ramp_down)
+    eq_ramp_up = _init(model, :eq_str_ramp_up)
+    reserve = model[:reserve]
+
+    # Gar1962.ProdVars
+    prod_above = model[:prod_above]
+
+    # Gar1962.StatusVars
+    is_on = model[:is_on]
+    switch_off = model[:switch_off]
+    switch_on = model[:switch_on]
+
+    for t in 1:model[:instance].time
+        time_invariant =
+            (t > 1) ? (abs(g.min_power[t] - g.min_power[t-1]) < 1e-7) : true
+
+        # Ramp up limit
+        if t == 1
+            if is_initially_on
+                eq_ramp_up[gn, t] = @constraint(
+                    model,
+                    g.min_power[t] +
+                    prod_above[gn, t] +
+                    (RESERVES_WHEN_RAMP_UP ? reserve[gn, t] : 0.0) <=
+                    g.initial_power + RU
+                )
+            end
+        else
+            # amk: without accounting for time-varying min power terms,
+            #      we might get an infeasible schedule, e.g. if min_power[t-1] = 0, min_power[t] = 10
+            #      and ramp_up_limit = 5, the constraint (p'(t) + r(t) <= p'(t-1) + RU)
+            #      would be satisfied with p'(t) = r(t) = p'(t-1) = 0
+            #      Note that if switch_on[t] = 1, then eqns (20) or (21) go into effect
+            if !time_invariant
+                # Use equation (24) instead
+                SU = g.startup_limit
+                max_prod_this_period =
+                    g.min_power[t] * is_on[gn, t] +
+                    prod_above[gn, t] +
+                    (
+                        RESERVES_WHEN_START_UP || RESERVES_WHEN_RAMP_UP ?
+                        reserve[gn, t] : 0.0
+                    )
+                min_prod_last_period =
+                    g.min_power[t-1] * is_on[gn, t-1] + prod_above[gn, t-1]
+                eq_ramp_up[gn, t] = @constraint(
+                    model,
+                    max_prod_this_period - min_prod_last_period <=
+                    RU * is_on[gn, t-1] + SU * switch_on[gn, t]
+                )
+            else
+                # Equation (26) in Kneuven et al. (2020)
+                # TODO: what if RU < SU? places too stringent upper bound
+                # prod_above[gn, t] when starting up, and creates diff with (24).
+                eq_ramp_up[gn, t] = @constraint(
+                    model,
+                    prod_above[gn, t] +
+                    (RESERVES_WHEN_RAMP_UP ? reserve[gn, t] : 0.0) -
+                    prod_above[gn, t-1] <= RU
+                )
+            end
+        end
+
+        # Ramp down limit
+        if t == 1
+            if is_initially_on
+                # TODO If RD < SD, or more specifically if
+                #        min_power + RD < initial_power < SD
+                #      then the generator should be able to shut down at time t = 1,
+                #      but the constraint below will force the unit to produce power
+                eq_ramp_down[gn, t] = @constraint(
+                    model,
+                    g.initial_power - (g.min_power[t] + prod_above[gn, t]) <= RD
+                )
+            end
+        else
+            # amk: similar to ramp_up, need to account for time-dependent min_power
+            if !time_invariant
+                # Revert to (25)
+                SD = g.shutdown_limit
+                max_prod_last_period =
+                    g.min_power[t-1] * is_on[gn, t-1] +
+                    prod_above[gn, t-1] +
+                    (
+                        RESERVES_WHEN_SHUT_DOWN || RESERVES_WHEN_RAMP_DOWN ?
+                        reserve[gn, t-1] : 0.0
+                    )
+                min_prod_this_period =
+                    g.min_power[t] * is_on[gn, t] + prod_above[gn, t]
+                eq_ramp_down[gn, t] = @constraint(
+                    model,
+                    max_prod_last_period - min_prod_this_period <=
+                    RD * is_on[gn, t] + SD * switch_off[gn, t]
+                )
+            else
+                # Equation (27) in Kneuven et al. (2020)
+                # TODO: Similar to above, what to do if shutting down in time t
+                # and RD < SD? There is a difference with (25).
+                eq_ramp_down[gn, t] = @constraint(
+                    model,
+                    prod_above[gn, t-1] +
+                    (RESERVES_WHEN_RAMP_DOWN ? reserve[gn, t-1] : 0.0) -
+                    prod_above[gn, t] <= RD
+                )
+            end
+        end
+    end
+end

src/model/formulations/MorLatRam2013/scosts.jl

@@ -0,0 +1,50 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function _add_startup_cost_eqs!(
+    model::JuMP.Model,
+    g::Unit,
+    formulation::MorLatRam2013.StartupCosts,
+)::Nothing
+    eq_startup_choose = _init(model, :eq_startup_choose)
+    eq_startup_restrict = _init(model, :eq_startup_restrict)
+    S = length(g.startup_categories)
+    startup = model[:startup]
+    for t in 1:model[:instance].time
+        # If unit is switching on, we must choose a startup category
+        eq_startup_choose[g.name, t] = @constraint(
+            model,
+            model[:switch_on][g.name, t] ==
+            sum(startup[g.name, t, s] for s in 1:S)
+        )
+
+        for s in 1:S
+            # If unit has not switched off in the last `delay` time periods, startup category is forbidden.
+            # The last startup category is always allowed.
+            if s < S
+                range_start = t - g.startup_categories[s+1].delay + 1
+                range_end = t - g.startup_categories[s].delay
+                range = (range_start:range_end)
+                initial_sum = (
+                    g.initial_status < 0 && (g.initial_status + 1 in range) ? 1.0 : 0.0
+                )
+                eq_startup_restrict[g.name, t, s] = @constraint(
+                    model,
+                    startup[g.name, t, s] <=
+                    initial_sum + sum(
+                        model[:switch_off][g.name, i] for i in range if i >= 1
+                    )
+                )
+            end
+
+            # Objective function terms for start-up costs
+            add_to_expression!(
+                model[:obj],
+                startup[g.name, t, s],
+                g.startup_categories[s].cost,
+            )
+        end
+    end
+    return
+end

src/model/formulations/MorLatRam2013/structs.jl

@@ -0,0 +1,20 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+"""
+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
+"""
+module MorLatRam2013
+
+import ..RampingFormulation
+import ..StartupCostsFormulation
+
+struct Ramping <: RampingFormulation end
+struct StartupCosts <: StartupCostsFormulation end
+
+end

src/model/formulations/PanGua2016/ramp.jl

@@ -0,0 +1,107 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function _add_ramp_eqs!(
+    model::JuMP.Model,
+    g::Unit,
+    formulation_prod_vars::Gar1962.ProdVars,
+    formulation_ramping::PanGua2016.Ramping,
+    formulation_status_vars::Gar1962.StatusVars,
+)::Nothing
+    # TODO: Move upper case constants to model[:instance]
+    RESERVES_WHEN_SHUT_DOWN = true
+    gn = g.name
+    reserve = model[:reserve]
+    eq_str_prod_limit = _init(model, :eq_str_prod_limit)
+    eq_prod_limit_ramp_up_extra_period =
+        _init(model, :eq_prod_limit_ramp_up_extra_period)
+    eq_prod_limit_shutdown_trajectory =
+        _init(model, :eq_prod_limit_shutdown_trajectory)
+    UT = g.min_uptime
+    SU = g.startup_limit   # startup rate, i.e., max production right after startup
+    SD = g.shutdown_limit  # shutdown rate, i.e., max production right before shutdown
+    RU = g.ramp_up_limit   # ramp up rate
+    RD = g.ramp_down_limit # ramp down rate
+    T = model[:instance].time
+
+    # Gar1962.ProdVars
+    prod_above = model[:prod_above]
+
+    # Gar1962.StatusVars
+    is_on = model[:is_on]
+    switch_off = model[:switch_off]
+    switch_on = model[:switch_on]
+
+    for t in 1:T
+        Pbar = g.max_power[t]
+        if Pbar < 1e-7
+            # Skip this time period if max power = 0
+            continue
+        end
+
+        #TRD = floor((Pbar - SU) / RD) # ramp down time
+        # TODO check amk changed TRD wrt Kneuven et al.
+        TRD = ceil((Pbar - SD) / RD)  # ramp down time
+        TRU = floor((Pbar - SU) / RU) # ramp up time, can be negative if Pbar < SU
+
+        # TODO check initial time periods: what if generator has been running for x periods?
+        # But maybe ok as long as (35) and (36) are also used...
+        if UT > 1
+            # Equation (38) in Kneuven et al. (2020)
+            # Generalization of (20)
+            # Necessary that if any of the switch_on = 1 in the sum,
+            # then switch_off[gn, t+1] = 0
+            eq_str_prod_limit[gn, t] = @constraint(
+                model,
+                prod_above[gn, t] +
+                g.min_power[t] * is_on[gn, t] +
+                reserve[gn, t] <=
+                Pbar * is_on[gn, t] -
+                (t < T ? (Pbar - SD) * switch_off[gn, t+1] : 0.0) - sum(
+                    (Pbar - (SU + i * RU)) * switch_on[gn, t-i] for
+                    i in 0:min(UT - 2, TRU, t - 1)
+                )
+            )
+
+            if UT - 2 < TRU
+                # Equation (40) in Kneuven et al. (2020)
+                # Covers an additional time period of the ramp-up trajectory, compared to (38)
+                eq_prod_limit_ramp_up_extra_period[gn, t] = @constraint(
+                    model,
+                    prod_above[gn, t] +
+                    g.min_power[t] * is_on[gn, t] +
+                    reserve[gn, t] <=
+                    Pbar * is_on[gn, t] - sum(
+                        (Pbar - (SU + i * RU)) * switch_on[gn, t-i] for
+                        i in 0:min(UT - 1, TRU, t - 1)
+                    )
+                )
+            end
+
+            # Add in shutdown trajectory if KSD >= 0 (else this is dominated by (38))
+            KSD = min(TRD, UT - 1, T - t - 1)
+            if KSD > 0
+                KSU = min(TRU, UT - 2 - KSD, t - 1)
+                # Equation (41) in Kneuven et al. (2020)
+                eq_prod_limit_shutdown_trajectory[gn, t] = @constraint(
+                    model,
+                    prod_above[gn, t] +
+                    g.min_power[t] * is_on[gn, t] +
+                    (RESERVES_WHEN_SHUT_DOWN ? reserve[gn, t] : 0.0) <=
+                    Pbar * is_on[gn, t] - sum(
+                        (Pbar - (SD + i * RD)) * switch_off[gn, t+1+i] for
+                        i in 0:KSD
+                    ) - sum(
+                        (Pbar - (SU + i * RU)) * switch_on[gn, t-i] for
+                        i in 0:KSU
+                    ) - (
+                        (KSU >= TRU || KSU > t - 2) ? 0.0 :
+                        max(0, (SU + (KSU + 1) * RU) - (SD + TRD * RD)) *
+                        switch_on[gn, t-(KSU+1)]
+                    )
+                )
+            end
+        end
+    end
+end

src/model/formulations/PanGua2016/structs.jl

@@ -0,0 +1,18 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+"""
+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
+"""
+module PanGua2016
+
+import ..RampingFormulation
+
+struct Ramping <: RampingFormulation end
+
+end

src/model/formulations/base/bus.jl

@@ -0,0 +1,24 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function _add_bus!(model::JuMP.Model, b::Bus)::Nothing
+    net_injection = _init(model, :expr_net_injection)
+    curtail = _init(model, :curtail)
+    for t in 1:model[:instance].time
+        # Fixed load
+        net_injection[b.name, t] = AffExpr(-b.load[t])
+
+        # Load curtailment
+        curtail[b.name, t] =
+            @variable(model, lower_bound = 0, upper_bound = b.load[t])
+
+        add_to_expression!(net_injection[b.name, t], curtail[b.name, t], 1.0)
+        add_to_expression!(
+            model[:obj],
+            curtail[b.name, t],
+            model[:instance].power_balance_penalty[t],
+        )
+    end
+    return
+end

src/model/formulations/base/line.jl

@@ -0,0 +1,61 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function _add_transmission_line!(
+    model::JuMP.Model,
+    lm::TransmissionLine,
+    f::ShiftFactorsFormulation,
+)::Nothing
+    overflow = _init(model, :overflow)
+    for t in 1:model[:instance].time
+        overflow[lm.name, t] = @variable(model, lower_bound = 0)
+        add_to_expression!(
+            model[:obj],
+            overflow[lm.name, t],
+            lm.flow_limit_penalty[t],
+        )
+    end
+    return
+end
+
+function _setup_transmission(
+    model::JuMP.Model,
+    formulation::ShiftFactorsFormulation,
+)::Nothing
+    instance = model[:instance]
+    isf = formulation.precomputed_isf
+    lodf = formulation.precomputed_lodf
+    if length(instance.buses) == 1
+        isf = zeros(0, 0)
+        lodf = zeros(0, 0)
+    elseif isf === nothing
+        @info "Computing injection shift factors..."
+        time_isf = @elapsed begin
+            isf = UnitCommitment._injection_shift_factors(
+                lines = instance.lines,
+                buses = instance.buses,
+            )
+        end
+        @info @sprintf("Computed ISF in %.2f seconds", time_isf)
+        @info "Computing line outage factors..."
+        time_lodf = @elapsed begin
+            lodf = UnitCommitment._line_outage_factors(
+                lines = instance.lines,
+                buses = instance.buses,
+                isf = isf,
+            )
+        end
+        @info @sprintf("Computed LODF in %.2f seconds", time_lodf)
+        @info @sprintf(
+            "Applying PTDF and LODF cutoffs (%.5f, %.5f)",
+            formulation.isf_cutoff,
+            formulation.lodf_cutoff
+        )
+        isf[abs.(isf).<formulation.isf_cutoff] .= 0
+        lodf[abs.(lodf).<formulation.lodf_cutoff] .= 0
+    end
+    model[:isf] = isf
+    model[:lodf] = lodf
+    return
+end

src/model/formulations/base/psload.jl

@@ -0,0 +1,27 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function _add_price_sensitive_load!(
+    model::JuMP.Model,
+    ps::PriceSensitiveLoad,
+)::Nothing
+    loads = _init(model, :loads)
+    net_injection = _init(model, :expr_net_injection)
+    for t in 1:model[:instance].time
+        # Decision variable
+        loads[ps.name, t] =
+            @variable(model, lower_bound = 0, upper_bound = ps.demand[t])
+
+        # Objective function terms
+        add_to_expression!(model[:obj], loads[ps.name, t], -ps.revenue[t])
+
+        # Net injection
+        add_to_expression!(
+            net_injection[ps.bus.name, t],
+            loads[ps.name, t],
+            -1.0,
+        )
+    end
+    return
+end

src/model/formulations/base/sensitivity.jl

@@ -72,10 +72,9 @@ function _line_outage_factors(;
     lines::Array{TransmissionLine,1},
     isf::Array{Float64,2},
 )::Array{Float64,2}
-    n_lines, n_buses = size(isf)
     incidence = Array(_reduced_incidence_matrix(lines = lines, buses = buses))
     lodf::Array{Float64,2} = isf * transpose(incidence)
-    m, n = size(lodf)
+    _, n = size(lodf)
     for i in 1:n
         lodf[:, i] *= 1.0 / (1.0 - lodf[i, i])
         lodf[i, i] = -1

src/model/formulations/base/structs.jl

@@ -0,0 +1,78 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+abstract type TransmissionFormulation end
+abstract type RampingFormulation end
+abstract type PiecewiseLinearCostsFormulation end
+abstract type StartupCostsFormulation end
+abstract type StatusVarsFormulation end
+abstract type ProductionVarsFormulation end
+
+struct Formulation
+    prod_vars::ProductionVarsFormulation
+    pwl_costs::PiecewiseLinearCostsFormulation
+    ramping::RampingFormulation
+    startup_costs::StartupCostsFormulation
+    status_vars::StatusVarsFormulation
+    transmission::TransmissionFormulation
+
+    function Formulation(;
+        prod_vars::ProductionVarsFormulation = Gar1962.ProdVars(),
+        pwl_costs::PiecewiseLinearCostsFormulation = KnuOstWat2018.PwlCosts(),
+        ramping::RampingFormulation = MorLatRam2013.Ramping(),
+        startup_costs::StartupCostsFormulation = MorLatRam2013.StartupCosts(),
+        status_vars::StatusVarsFormulation = Gar1962.StatusVars(),
+        transmission::TransmissionFormulation = ShiftFactorsFormulation(),
+    )
+        return new(
+            prod_vars,
+            pwl_costs,
+            ramping,
+            startup_costs,
+            status_vars,
+            transmission,
+        )
+    end
+end
+
+"""
+    struct ShiftFactorsFormulation <: TransmissionFormulation
+        isf_cutoff::Float64
+        lodf_cutoff::Float64
+        precomputed_isf::Union{Nothing,Matrix{Float64}}
+        precomputed_lodf::Union{Nothing,Matrix{Float64}}
+    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::Union{Matrix{Float64},Nothing} = nothing`:
+    the injection shift factors matrix. If not provided, it will be computed.
+- `precomputed_lodf::Union{Matrix{Float64},Nothing} = nothing`: 
+    the line outage distribution factors matrix. If not provided, it will be
+    computed.
+- `isf_cutoff::Float64 = 0.005`: 
+    the cutoff that should be applied to the ISF matrix. Entries with magnitude
+    smaller than this value will be set to zero.
+- `lodf_cutoff::Float64 = 0.001`: 
+    the cutoff that should be applied to the LODF matrix. Entries with magnitude
+    smaller than this value will be set to zero.
+"""
+struct ShiftFactorsFormulation <: TransmissionFormulation
+    isf_cutoff::Float64
+    lodf_cutoff::Float64
+    precomputed_isf::Union{Nothing,Matrix{Float64}}
+    precomputed_lodf::Union{Nothing,Matrix{Float64}}
+
+    function ShiftFactorsFormulation(;
+        isf_cutoff = 0.005,
+        lodf_cutoff = 0.001,
+        precomputed_isf = nothing,
+        precomputed_lodf = nothing,
+    )
+        return new(isf_cutoff, lodf_cutoff, precomputed_isf, precomputed_lodf)
+    end
+end

src/model/formulations/base/system.jl

@@ -0,0 +1,56 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function _add_system_wide_eqs!(model::JuMP.Model)::Nothing
+    _add_net_injection_eqs!(model)
+    _add_reserve_eqs!(model)
+    return
+end
+
+function _add_net_injection_eqs!(model::JuMP.Model)::Nothing
+    T = model[:instance].time
+    net_injection = _init(model, :net_injection)
+    eq_net_injection = _init(model, :eq_net_injection)
+    eq_power_balance = _init(model, :eq_power_balance)
+    for t in 1:T, b in model[:instance].buses
+        n = net_injection[b.name, t] = @variable(model)
+        eq_net_injection[b.name, t] =
+            @constraint(model, -n + model[:expr_net_injection][b.name, t] == 0)
+    end
+    for t in 1:T
+        eq_power_balance[t] = @constraint(
+            model,
+            sum(net_injection[b.name, t] for b in model[:instance].buses) == 0
+        )
+    end
+    return
+end
+
+function _add_reserve_eqs!(model::JuMP.Model)::Nothing
+    eq_min_reserve = _init(model, :eq_min_reserve)
+    instance = model[:instance]
+    for t in 1:instance.time
+        # Equation (68) in Kneuven et al. (2020)
+        # As in Morales-España et al. (2013a)
+        # Akin to the alternative formulation with max_power_avail
+        # from Carrión and Arroyo (2006) and Ostrowski et al. (2012)
+        shortfall_penalty = instance.shortfall_penalty[t]
+        eq_min_reserve[t] = @constraint(
+            model,
+            sum(model[:reserve][g.name, t] for g in instance.units) +
+            (shortfall_penalty >= 0 ? model[:reserve_shortfall][t] : 0.0) >=
+            instance.reserves.spinning[t]
+        )
+
+        # Account for shortfall contribution to objective
+        if shortfall_penalty >= 0
+            add_to_expression!(
+                model[:obj],
+                shortfall_penalty,
+                model[:reserve_shortfall][t],
+            )
+        end
+    end
+    return
+end

src/model/formulations/base/unit.jl

@@ -0,0 +1,218 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function _add_unit!(model::JuMP.Model, g::Unit, formulation::Formulation)
+    if !all(g.must_run) && any(g.must_run)
+        error("Partially must-run units are not currently supported")
+    end
+    if g.initial_power === nothing || g.initial_status === nothing
+        error("Initial conditions for $(g.name) must be provided")
+    end
+
+    # Variables
+    _add_production_vars!(model, g, formulation.prod_vars)
+    _add_reserve_vars!(model, g)
+    _add_startup_shutdown_vars!(model, g)
+    _add_status_vars!(model, g, formulation.status_vars)
+
+    # Constraints and objective function
+    _add_min_uptime_downtime_eqs!(model, g)
+    _add_net_injection_eqs!(model, g)
+    _add_production_limit_eqs!(model, g, formulation.prod_vars)
+    _add_production_piecewise_linear_eqs!(
+        model,
+        g,
+        formulation.prod_vars,
+        formulation.pwl_costs,
+        formulation.status_vars,
+    )
+    _add_ramp_eqs!(
+        model,
+        g,
+        formulation.prod_vars,
+        formulation.ramping,
+        formulation.status_vars,
+    )
+    _add_startup_cost_eqs!(model, g, formulation.startup_costs)
+    _add_startup_shutdown_limit_eqs!(model, g)
+    _add_status_eqs!(model, g, formulation.status_vars)
+    return
+end
+
+_is_initially_on(g::Unit)::Float64 = (g.initial_status > 0 ? 1.0 : 0.0)
+
+function _add_reserve_vars!(model::JuMP.Model, g::Unit)::Nothing
+    reserve = _init(model, :reserve)
+    reserve_shortfall = _init(model, :reserve_shortfall)
+    for t in 1:model[:instance].time
+        if g.provides_spinning_reserves[t]
+            reserve[g.name, t] = @variable(model, lower_bound = 0)
+        else
+            reserve[g.name, t] = 0.0
+        end
+        reserve_shortfall[t] =
+            (model[:instance].shortfall_penalty[t] >= 0) ?
+            @variable(model, lower_bound = 0) : 0.0
+    end
+    return
+end
+
+function _add_reserve_eqs!(model::JuMP.Model, g::Unit)::Nothing
+    reserve = model[:reserve]
+    for t in 1:model[:instance].time
+        add_to_expression!(expr_reserve[g.bus.name, t], reserve[g.name, t], 1.0)
+    end
+    return
+end
+
+function _add_startup_shutdown_vars!(model::JuMP.Model, g::Unit)::Nothing
+    startup = _init(model, :startup)
+    for t in 1:model[:instance].time
+        for s in 1:length(g.startup_categories)
+            startup[g.name, t, s] = @variable(model, binary = true)
+        end
+    end
+    return
+end
+
+function _add_startup_shutdown_limit_eqs!(model::JuMP.Model, g::Unit)::Nothing
+    eq_shutdown_limit = _init(model, :eq_shutdown_limit)
+    eq_startup_limit = _init(model, :eq_startup_limit)
+    is_on = model[:is_on]
+    prod_above = model[:prod_above]
+    reserve = model[:reserve]
+    switch_off = model[:switch_off]
+    switch_on = model[:switch_on]
+    T = model[:instance].time
+    for t in 1:T
+        # Startup limit
+        eq_startup_limit[g.name, t] = @constraint(
+            model,
+            prod_above[g.name, t] + reserve[g.name, t] <=
+            (g.max_power[t] - g.min_power[t]) * is_on[g.name, t] -
+            max(0, g.max_power[t] - g.startup_limit) * switch_on[g.name, t]
+        )
+        # Shutdown limit
+        if g.initial_power > g.shutdown_limit
+            eq_shutdown_limit[g.name, 0] =
+                @constraint(model, switch_off[g.name, 1] <= 0)
+        end
+        if t < T
+            eq_shutdown_limit[g.name, t] = @constraint(
+                model,
+                prod_above[g.name, t] <=
+                (g.max_power[t] - g.min_power[t]) * is_on[g.name, t] -
+                max(0, g.max_power[t] - g.shutdown_limit) *
+                switch_off[g.name, t+1]
+            )
+        end
+    end
+    return
+end
+
+function _add_ramp_eqs!(
+    model::JuMP.Model,
+    g::Unit,
+    formulation::RampingFormulation,
+)::Nothing
+    prod_above = model[:prod_above]
+    reserve = model[:reserve]
+    eq_ramp_up = _init(model, :eq_ramp_up)
+    eq_ramp_down = _init(model, :eq_ramp_down)
+    for t in 1:model[:instance].time
+        # Ramp up limit 
+        if t == 1
+            if _is_initially_on(g) == 1
+                eq_ramp_up[g.name, t] = @constraint(
+                    model,
+                    prod_above[g.name, t] + reserve[g.name, t] <=
+                    (g.initial_power - g.min_power[t]) + g.ramp_up_limit
+                )
+            end
+        else
+            eq_ramp_up[g.name, t] = @constraint(
+                model,
+                prod_above[g.name, t] + reserve[g.name, t] <=
+                prod_above[g.name, t-1] + g.ramp_up_limit
+            )
+        end
+
+        # Ramp down limit
+        if t == 1
+            if _is_initially_on(g) == 1
+                eq_ramp_down[g.name, t] = @constraint(
+                    model,
+                    prod_above[g.name, t] >=
+                    (g.initial_power - g.min_power[t]) - g.ramp_down_limit
+                )
+            end
+        else
+            eq_ramp_down[g.name, t] = @constraint(
+                model,
+                prod_above[g.name, t] >=
+                prod_above[g.name, t-1] - g.ramp_down_limit
+            )
+        end
+    end
+end
+
+function _add_min_uptime_downtime_eqs!(model::JuMP.Model, g::Unit)::Nothing
+    is_on = model[:is_on]
+    switch_off = model[:switch_off]
+    switch_on = model[:switch_on]
+    eq_min_uptime = _init(model, :eq_min_uptime)
+    eq_min_downtime = _init(model, :eq_min_downtime)
+    T = model[:instance].time
+    for t in 1:T
+        # Minimum up-time
+        eq_min_uptime[g.name, t] = @constraint(
+            model,
+            sum(switch_on[g.name, i] for i in (t-g.min_uptime+1):t if i >= 1) <= is_on[g.name, t]
+        )
+        # Minimum down-time
+        eq_min_downtime[g.name, t] = @constraint(
+            model,
+            sum(
+                switch_off[g.name, i] for i in (t-g.min_downtime+1):t if i >= 1
+            ) <= 1 - is_on[g.name, t]
+        )
+        # Minimum up/down-time for initial periods
+        if t == 1
+            if g.initial_status > 0
+                eq_min_uptime[g.name, 0] = @constraint(
+                    model,
+                    sum(
+                        switch_off[g.name, i] for
+                        i in 1:(g.min_uptime-g.initial_status) if i <= T
+                    ) == 0
+                )
+            else
+                eq_min_downtime[g.name, 0] = @constraint(
+                    model,
+                    sum(
+                        switch_on[g.name, i] for
+                        i in 1:(g.min_downtime+g.initial_status) if i <= T
+                    ) == 0
+                )
+            end
+        end
+    end
+end
+
+function _add_net_injection_eqs!(model::JuMP.Model, g::Unit)::Nothing
+    expr_net_injection = model[:expr_net_injection]
+    for t in 1:model[:instance].time
+        # Add to net injection expression
+        add_to_expression!(
+            expr_net_injection[g.bus.name, t],
+            model[:prod_above][g.name, t],
+            1.0,
+        )
+        add_to_expression!(
+            expr_net_injection[g.bus.name, t],
+            model[:is_on][g.name, t],
+            g.min_power[t],
+        )
+    end
+end

src/model/jumpext.jl

@@ -0,0 +1,48 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+# This file extends some JuMP functions so that decision variables can be safely
+# replaced by (constant) floating point numbers.
+
+import JuMP: value, fix, set_name
+
+function value(x::Float64)
+    return x
+end
+
+function fix(x::Float64, v::Float64; force)
+    return abs(x - v) < 1e-6 || error("Value mismatch: $x != $v")
+end
+
+function set_name(x::Float64, n::String)
+    # nop
+end
+
+function _init(model::JuMP.Model, key::Symbol)::OrderedDict
+    if !(key in keys(object_dictionary(model)))
+        model[key] = OrderedDict()
+    end
+    return model[key]
+end
+
+function _set_names!(model::JuMP.Model)
+    @info "Setting variable and constraint names..."
+    time_varnames = @elapsed begin
+        _set_names!(object_dictionary(model))
+    end
+    @info @sprintf("Set names in %.2f seconds", time_varnames)
+end
+
+function _set_names!(dict::Dict)
+    for name in keys(dict)
+        dict[name] isa AbstractDict || continue
+        for idx in keys(dict[name])
+            if dict[name][idx] isa AffExpr
+                continue
+            end
+            idx_str = join(map(string, idx), ",")
+            set_name(dict[name][idx], "$name[$idx_str]")
+        end
+    end
+end

src/solution/fix.jl

@@ -0,0 +1,33 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+"""
+    fix!(model::JuMP.Model, solution::AbstractDict)::Nothing
+
+Fix the value of all binary variables to the ones specified by the given
+solution. Useful for computing LMPs.
+"""
+function fix!(model::JuMP.Model, solution::AbstractDict)::Nothing
+    instance, T = model[:instance], model[:instance].time
+    is_on = model[:is_on]
+    prod_above = model[:prod_above]
+    reserve = model[:reserve]
+    for g in instance.units
+        for t in 1:T
+            is_on_value = round(solution["Is on"][g.name][t])
+            prod_value =
+                round(solution["Production (MW)"][g.name][t], digits = 5)
+            reserve_value =
+                round(solution["Reserve (MW)"][g.name][t], digits = 5)
+            JuMP.fix(is_on[g.name, t], is_on_value, force = true)
+            JuMP.fix(
+                prod_above[g.name, t],
+                prod_value - is_on_value * g.min_power[t],
+                force = true,
+            )
+            JuMP.fix(reserve[g.name, t], reserve_value, force = true)
+        end
+    end
+    return
+end

src/solution/methods/XavQiuWanThi2019/enforce.jl

@@ -0,0 +1,83 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function _enforce_transmission(
+    model::JuMP.Model,
+    violations::Vector{_Violation},
+)::Nothing
+    for v in violations
+        _enforce_transmission(
+            model = model,
+            violation = v,
+            isf = model[:isf],
+            lodf = model[:lodf],
+        )
+    end
+    return
+end
+
+function _enforce_transmission(;
+    model::JuMP.Model,
+    violation::_Violation,
+    isf::Matrix{Float64},
+    lodf::Matrix{Float64},
+)::Nothing
+    instance = model[:instance]
+    limit::Float64 = 0.0
+    overflow = model[:overflow]
+    net_injection = model[:net_injection]
+
+    if violation.outage_line === nothing
+        limit = violation.monitored_line.normal_flow_limit[violation.time]
+        @info @sprintf(
+            "    %8.3f MW overflow in %-5s time %3d (pre-contingency)",
+            violation.amount,
+            violation.monitored_line.name,
+            violation.time,
+        )
+    else
+        limit = violation.monitored_line.emergency_flow_limit[violation.time]
+        @info @sprintf(
+            "    %8.3f MW overflow in %-5s time %3d (outage: line %s)",
+            violation.amount,
+            violation.monitored_line.name,
+            violation.time,
+            violation.outage_line.name,
+        )
+    end
+
+    fm = violation.monitored_line.name
+    t = violation.time
+    flow = @variable(model, base_name = "flow[$fm,$t]")
+
+    v = overflow[violation.monitored_line.name, violation.time]
+    @constraint(model, flow <= limit + v)
+    @constraint(model, -flow <= limit + v)
+
+    if violation.outage_line === nothing
+        @constraint(
+            model,
+            flow == sum(
+                net_injection[b.name, violation.time] *
+                isf[violation.monitored_line.offset, b.offset] for
+                b in instance.buses if b.offset > 0
+            )
+        )
+    else
+        @constraint(
+            model,
+            flow == sum(
+                net_injection[b.name, violation.time] * (
+                    isf[violation.monitored_line.offset, b.offset] + (
+                        lodf[
+                            violation.monitored_line.offset,
+                            violation.outage_line.offset,
+                        ] * isf[violation.outage_line.offset, b.offset]
+                    )
+                ) for b in instance.buses if b.offset > 0
+            )
+        )
+    end
+    return nothing
+end

src/solution/methods/XavQiuWanThi2019/filter.jl

@@ -0,0 +1,44 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function _offer(filter::_ViolationFilter, v::_Violation)::Nothing
+    if v.monitored_line.offset ∉ keys(filter.queues)
+        filter.queues[v.monitored_line.offset] =
+            PriorityQueue{_Violation,Float64}()
+    end
+    q::PriorityQueue{_Violation,Float64} =
+        filter.queues[v.monitored_line.offset]
+    if length(q) < filter.max_per_line
+        enqueue!(q, v => v.amount)
+    else
+        if v.amount > peek(q)[1].amount
+            dequeue!(q)
+            enqueue!(q, v => v.amount)
+        end
+    end
+    return nothing
+end
+
+function _query(filter::_ViolationFilter)::Array{_Violation,1}
+    violations = Array{_Violation,1}()
+    time_queue = PriorityQueue{_Violation,Float64}()
+    for l in keys(filter.queues)
+        line_queue = filter.queues[l]
+        while length(line_queue) > 0
+            v = dequeue!(line_queue)
+            if length(time_queue) < filter.max_total
+                enqueue!(time_queue, v => v.amount)
+            else
+                if v.amount > peek(time_queue)[1].amount
+                    dequeue!(time_queue)
+                    enqueue!(time_queue, v => v.amount)
+                end
+            end
+        end
+    end
+    while length(time_queue) > 0
+        violations = [violations; dequeue!(time_queue)]
+    end
+    return violations
+end

src/solution/methods/XavQiuWanThi2019/find.jl

@@ -1,91 +1,56 @@
 # UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
 # Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
 # Released under the modified BSD license. See COPYING.md for more details.
-# Copyright (C) 2019 Argonne National Laboratory
-# Written by Alinson Santos Xavier <axavier@anl.gov>
 
-using DataStructures
-using Base.Threads
+import Base.Threads: @threads
 
-struct Violation
-    time::Int
-    monitored_line::TransmissionLine
-    outage_line::Union{TransmissionLine,Nothing}
-    amount::Float64  # Violation amount (in MW)
-end
-
-function Violation(;
-    time::Int,
-    monitored_line::TransmissionLine,
-    outage_line::Union{TransmissionLine,Nothing},
-    amount::Float64,
-)::Violation
-    return Violation(time, monitored_line, outage_line, amount)
-end
-
-mutable struct ViolationFilter
-    max_per_line::Int
-    max_total::Int
-    queues::Dict{Int,PriorityQueue{Violation,Float64}}
-end
-
-function ViolationFilter(;
-    max_per_line::Int = 1,
-    max_total::Int = 5,
-)::ViolationFilter
-    return ViolationFilter(max_per_line, max_total, Dict())
-end
-
-function _offer(filter::ViolationFilter, v::Violation)::Nothing
-    if v.monitored_line.offset ∉ keys(filter.queues)
-        filter.queues[v.monitored_line.offset] =
-            PriorityQueue{Violation,Float64}()
-    end
-    q::PriorityQueue{Violation,Float64} = filter.queues[v.monitored_line.offset]
-    if length(q) < filter.max_per_line
-        enqueue!(q, v => v.amount)
-    else
-        if v.amount > peek(q)[1].amount
-            dequeue!(q)
-            enqueue!(q, v => v.amount)
-        end
-    end
-    return nothing
-end
-
-function _query(filter::ViolationFilter)::Array{Violation,1}
-    violations = Array{Violation,1}()
-    time_queue = PriorityQueue{Violation,Float64}()
-    for l in keys(filter.queues)
-        line_queue = filter.queues[l]
-        while length(line_queue) > 0
-            v = dequeue!(line_queue)
-            if length(time_queue) < filter.max_total
-                enqueue!(time_queue, v => v.amount)
-            else
-                if v.amount > peek(time_queue)[1].amount
-                    dequeue!(time_queue)
-                    enqueue!(time_queue, v => v.amount)
-                end
-            end
-        end
-    end
-    while length(time_queue) > 0
-        violations = [violations; dequeue!(time_queue)]
+function _find_violations(
+    model::JuMP.Model;
+    max_per_line::Int,
+    max_per_period::Int,
+)
+    instance = model[:instance]
+    net_injection = model[:net_injection]
+    overflow = model[:overflow]
+    length(instance.buses) > 1 || return []
+    violations = []
+    @info "Verifying transmission limits..."
+    time_screening = @elapsed begin
+        non_slack_buses = [b for b in instance.buses if b.offset > 0]
+        net_injection_values = [
+            value(net_injection[b.name, t]) for b in non_slack_buses,
+            t in 1:instance.time
+        ]
+        overflow_values = [
+            value(overflow[lm.name, t]) for lm in instance.lines,
+            t in 1:instance.time
+        ]
+        violations = UnitCommitment._find_violations(
+            instance = instance,
+            net_injections = net_injection_values,
+            overflow = overflow_values,
+            isf = model[:isf],
+            lodf = model[:lodf],
+            max_per_line = max_per_line,
+            max_per_period = max_per_period,
+        )
     end
+    @info @sprintf(
+        "Verified transmission limits in %.2f seconds",
+        time_screening
+    )
     return violations
 end
 
 """
-
     function _find_violations(
         instance::UnitCommitmentInstance,
         net_injections::Array{Float64, 2};
         isf::Array{Float64,2},
         lodf::Array{Float64,2},
-        max_per_line::Int = 1,
-        max_per_period::Int = 5,
-    )::Array{Violation, 1}
+        max_per_line::Int,
+        max_per_period::Int,
+    )::Array{_Violation, 1}
 
 Find transmission constraint violations (both pre-contingency, as well as
 post-contingency).
@@ -103,9 +68,9 @@ function _find_violations(;
     overflow::Array{Float64,2},
     isf::Array{Float64,2},
     lodf::Array{Float64,2},
-    max_per_line::Int = 1,
-    max_per_period::Int = 5,
-)::Array{Violation,1}
+    max_per_line::Int,
+    max_per_period::Int,
+)::Array{_Violation,1}
     B = length(instance.buses) - 1
     L = length(instance.lines)
     T = instance.time
@@ -116,7 +81,7 @@ function _find_violations(;
     size(lodf) == (L, L) || error("lodf has incorrect size")
 
     filters = Dict(
-        t => ViolationFilter(
+        t => _ViolationFilter(
             max_total = max_per_period,
             max_per_line = max_per_line,
         ) for t in 1:T
@@ -177,7 +142,7 @@ function _find_violations(;
             if pre_v[lm, k] > 1e-5
                 _offer(
                     filters[t],
-                    Violation(
+                    _Violation(
                         time = t,
                         monitored_line = instance.lines[lm],
                         outage_line = nothing,
@@ -192,7 +157,7 @@ function _find_violations(;
             if post_v[lm, lc, k] > 1e-5 && is_vulnerable[lc]
                 _offer(
                     filters[t],
-                    Violation(
+                    _Violation(
                         time = t,
                         monitored_line = instance.lines[lm],
                         outage_line = instance.lines[lc],
@@ -203,7 +168,7 @@ function _find_violations(;
         end
     end
 
-    violations = Violation[]
+    violations = _Violation[]
     for t in 1:instance.time
         append!(violations, _query(filters[t]))
     end

src/solution/methods/XavQiuWanThi2019/optimize.jl

@@ -0,0 +1,56 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function optimize!(model::JuMP.Model, method::XavQiuWanThi2019.Method)::Nothing
+    function set_gap(gap)
+        try
+            JuMP.set_optimizer_attribute(model, "MIPGap", gap)
+            @info @sprintf("MIP gap tolerance set to %f", gap)
+        catch
+            @warn "Could not change MIP gap tolerance"
+        end
+    end
+    initial_time = time()
+    large_gap = false
+    has_transmission = (length(model[:isf]) > 0)
+    if has_transmission && method.two_phase_gap
+        set_gap(1e-2)
+        large_gap = true
+    else
+        set_gap(method.gap_limit)
+    end
+    while true
+        time_elapsed = time() - initial_time
+        time_remaining = method.time_limit - time_elapsed
+        if time_remaining < 0
+            @info "Time limit exceeded"
+            break
+        end
+        @info @sprintf(
+            "Setting MILP time limit to %.2f seconds",
+            time_remaining
+        )
+        JuMP.set_time_limit_sec(model, time_remaining)
+        @info "Solving MILP..."
+        JuMP.optimize!(model)
+        has_transmission || break
+        violations = _find_violations(
+            model,
+            max_per_line = method.max_violations_per_line,
+            max_per_period = method.max_violations_per_period,
+        )
+        if isempty(violations)
+            @info "No violations found"
+            if large_gap
+                large_gap = false
+                set_gap(method.gap_limit)
+            else
+                break
+            end
+        else
+            _enforce_transmission(model, violations)
+        end
+    end
+    return
+end

src/solution/methods/XavQiuWanThi2019/structs.jl

@@ -0,0 +1,93 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+"""
+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
+"""
+module XavQiuWanThi2019
+import ..SolutionMethod
+"""
+    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.
+- `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 Method <: SolutionMethod
+    time_limit::Float64
+    gap_limit::Float64
+    two_phase_gap::Bool
+    max_violations_per_line::Int
+    max_violations_per_period::Int
+
+    function Method(;
+        time_limit::Float64 = 86400.0,
+        gap_limit::Float64 = 1e-3,
+        two_phase_gap::Bool = true,
+        max_violations_per_line::Int = 1,
+        max_violations_per_period::Int = 5,
+    )
+        return new(
+            time_limit,
+            gap_limit,
+            two_phase_gap,
+            max_violations_per_line,
+            max_violations_per_period,
+        )
+    end
+end
+end
+
+import DataStructures: PriorityQueue
+
+struct _Violation
+    time::Int
+    monitored_line::TransmissionLine
+    outage_line::Union{TransmissionLine,Nothing}
+    amount::Float64
+
+    function _Violation(;
+        time::Int,
+        monitored_line::TransmissionLine,
+        outage_line::Union{TransmissionLine,Nothing},
+        amount::Float64,
+    )
+        return new(time, monitored_line, outage_line, amount)
+    end
+end
+
+mutable struct _ViolationFilter
+    max_per_line::Int
+    max_total::Int
+    queues::Dict{Int,PriorityQueue{_Violation,Float64}}
+
+    function _ViolationFilter(; max_per_line::Int = 1, max_total::Int = 5)
+        return new(max_per_line, max_total, Dict())
+    end
+end

src/solution/optimize.jl

@@ -0,0 +1,14 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+"""
+    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.
+"""
+function optimize!(model::JuMP.Model)::Nothing
+    return UnitCommitment.optimize!(model, XavQiuWanThi2019.Method())
+end

src/solution/solution.jl

@@ -0,0 +1,71 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function solution(model::JuMP.Model)::OrderedDict
+    instance, T = model[:instance], model[:instance].time
+    function timeseries(vars, collection)
+        return OrderedDict(
+            b.name => [round(value(vars[b.name, t]), digits = 5) for t in 1:T]
+            for b in collection
+        )
+    end
+    function production_cost(g)
+        return [
+            value(model[:is_on][g.name, t]) * g.min_power_cost[t] + sum(
+                Float64[
+                    value(model[:segprod][g.name, t, k]) *
+                    g.cost_segments[k].cost[t] for
+                    k in 1:length(g.cost_segments)
+                ],
+            ) for t in 1:T
+        ]
+    end
+    function production(g)
+        return [
+            value(model[:is_on][g.name, t]) * g.min_power[t] + sum(
+                Float64[
+                    value(model[:segprod][g.name, t, k]) for
+                    k in 1:length(g.cost_segments)
+                ],
+            ) for t in 1:T
+        ]
+    end
+    function startup_cost(g)
+        S = length(g.startup_categories)
+        return [
+            sum(
+                g.startup_categories[s].cost *
+                value(model[:startup][g.name, t, s]) for s in 1:S
+            ) for t in 1:T
+        ]
+    end
+    sol = OrderedDict()
+    sol["Production (MW)"] =
+        OrderedDict(g.name => production(g) for g in instance.units)
+    sol["Production cost (\$)"] =
+        OrderedDict(g.name => production_cost(g) for g in instance.units)
+    sol["Startup cost (\$)"] =
+        OrderedDict(g.name => startup_cost(g) for g in instance.units)
+    sol["Is on"] = timeseries(model[:is_on], instance.units)
+    sol["Switch on"] = timeseries(model[:switch_on], instance.units)
+    sol["Switch off"] = timeseries(model[:switch_off], instance.units)
+    sol["Reserve (MW)"] = timeseries(model[:reserve], instance.units)
+    sol["Reserve shortfall (MW)"] = OrderedDict(
+        t =>
+            (instance.shortfall_penalty[t] >= 0) ?
+            round(value(model[:reserve_shortfall][t]), digits = 5) : 0.0 for
+        t in 1:instance.time
+    )
+    sol["Net injection (MW)"] =
+        timeseries(model[:net_injection], instance.buses)
+    sol["Load curtail (MW)"] = timeseries(model[:curtail], instance.buses)
+    if !isempty(instance.lines)
+        sol["Line overflow (MW)"] = timeseries(model[:overflow], instance.lines)
+    end
+    if !isempty(instance.price_sensitive_loads)
+        sol["Price-sensitive loads (MW)"] =
+            timeseries(model[:loads], instance.price_sensitive_loads)
+    end
+    return sol
+end

src/solution/structs.jl

@@ -0,0 +1,5 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+abstract type SolutionMethod end

src/solution/warmstart.jl

@@ -0,0 +1,22 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function set_warm_start!(model::JuMP.Model, solution::AbstractDict)::Nothing
+    instance, T = model[:instance], model[:instance].time
+    is_on = model[:is_on]
+    for g in instance.units
+        for t in 1:T
+            JuMP.set_start_value(is_on[g.name, t], solution["Is on"][g.name][t])
+            JuMP.set_start_value(
+                switch_on[g.name, t],
+                solution["Switch on"][g.name][t],
+            )
+            JuMP.set_start_value(
+                switch_off[g.name, t],
+                solution["Switch off"][g.name][t],
+            )
+        end
+    end
+    return
+end

src/solution/write.jl

@@ -0,0 +1,10 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+function write(filename::AbstractString, solution::AbstractDict)::Nothing
+    open(filename, "w") do file
+        return JSON.print(file, solution, 2)
+    end
+    return
+end

src/sysimage.jl

@@ -1,20 +0,0 @@
-# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
-# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
-# Released under the modified BSD license. See COPYING.md for more details.
-
-using PackageCompiler
-
-using DataStructures
-using JSON
-using JuMP
-using MathOptInterface
-using SparseArrays
-
-pkg = [:DataStructures, :JSON, :JuMP, :MathOptInterface, :SparseArrays]
-
-@info "Building system image..."
-create_sysimage(
-    pkg,
-    precompile_statements_file = "build/precompile.jl",
-    sysimage_path = "build/sysimage.so",
-)

src/transform/randomize/XavQiuAhm2021.jl

@@ -0,0 +1,209 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020-2021, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+"""
+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
+"""
+module XavQiuAhm2021
+
+using Distributions
+import ..UnitCommitmentInstance
+
+"""
+    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.
+"""
+Base.@kwdef struct Randomization
+    cost = Uniform(0.95, 1.05)
+    load_profile_mu::Vector{Float64} = [
+        1.0,
+        0.978,
+        0.98,
+        1.004,
+        1.02,
+        1.078,
+        1.132,
+        1.018,
+        0.999,
+        1.006,
+        0.999,
+        0.987,
+        0.975,
+        0.984,
+        0.995,
+        1.005,
+        1.045,
+        1.106,
+        0.981,
+        0.981,
+        0.978,
+        0.948,
+        0.928,
+        0.953,
+    ]
+    load_profile_sigma::Vector{Float64} = [
+        0.0,
+        0.011,
+        0.015,
+        0.01,
+        0.012,
+        0.029,
+        0.055,
+        0.027,
+        0.026,
+        0.023,
+        0.013,
+        0.012,
+        0.014,
+        0.011,
+        0.008,
+        0.008,
+        0.02,
+        0.02,
+        0.016,
+        0.012,
+        0.014,
+        0.015,
+        0.017,
+        0.024,
+    ]
+    load_share = Uniform(0.90, 1.10)
+    peak_load = Uniform(0.6 * 0.925, 0.6 * 1.075)
+    randomize_load_profile::Bool = true
+    randomize_costs::Bool = true
+    randomize_load_share::Bool = true
+end
+
+function _randomize_costs(
+    instance::UnitCommitmentInstance,
+    distribution,
+)::Nothing
+    for unit in instance.units
+        α = rand(distribution)
+        unit.min_power_cost *= α
+        for k in unit.cost_segments
+            k.cost *= α
+        end
+        for s in unit.startup_categories
+            s.cost *= α
+        end
+    end
+    return
+end
+
+function _randomize_load_share(
+    instance::UnitCommitmentInstance,
+    distribution,
+)::Nothing
+    α = rand(distribution, length(instance.buses))
+    for t in 1:instance.time
+        total = sum(bus.load[t] for bus in instance.buses)
+        den = sum(
+            bus.load[t] / total * α[i] for
+            (i, bus) in enumerate(instance.buses)
+        )
+        for (i, bus) in enumerate(instance.buses)
+            bus.load[t] *= α[i] / den
+        end
+    end
+    return
+end
+
+function _randomize_load_profile(
+    instance::UnitCommitmentInstance,
+    params::Randomization,
+)::Nothing
+    # Generate new system load
+    system_load = [1.0]
+    for t in 2:instance.time
+        idx = (t - 1) % length(params.load_profile_mu) + 1
+        gamma = rand(
+            Normal(params.load_profile_mu[idx], params.load_profile_sigma[idx]),
+        )
+        push!(system_load, system_load[t-1] * gamma)
+    end
+    capacity = sum(maximum(u.max_power) for u in instance.units)
+    peak_load = rand(params.peak_load) * capacity
+    system_load = system_load ./ maximum(system_load) .* peak_load
+
+    # Scale bus loads to match the new system load
+    prev_system_load = sum(b.load for b in instance.buses)
+    for b in instance.buses
+        for t in 1:instance.time
+            b.load[t] *= system_load[t] / prev_system_load[t]
+        end
+    end
+
+    return
+end
+
+end
+
+"""
+    function randomize!(
+        instance::UnitCommitment.UnitCommitmentInstance,
+        method::XavQiuAhm2021.Randomization,
+    )::Nothing
+
+Randomize costs and loads based on the method described in XavQiuAhm2021.
+"""
+function randomize!(
+    instance::UnitCommitment.UnitCommitmentInstance,
+    method::XavQiuAhm2021.Randomization,
+)::Nothing
+    if method.randomize_costs
+        XavQiuAhm2021._randomize_costs(instance, method.cost)
+    end
+    if method.randomize_load_share
+        XavQiuAhm2021._randomize_load_share(instance, method.load_share)
+    end
+    if method.randomize_load_profile
+        XavQiuAhm2021._randomize_load_profile(instance, method)
+    end
+    return
+end
+
+export randomize!

src/transform/slice.jl

@@ -0,0 +1,52 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+"""
+    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 slice(
+    instance::UnitCommitmentInstance,
+    range::UnitRange{Int},
+)::UnitCommitmentInstance
+    modified = deepcopy(instance)
+    modified.time = length(range)
+    modified.power_balance_penalty = modified.power_balance_penalty[range]
+    modified.reserves.spinning = modified.reserves.spinning[range]
+    for u in modified.units
+        u.max_power = u.max_power[range]
+        u.min_power = u.min_power[range]
+        u.must_run = u.must_run[range]
+        u.min_power_cost = u.min_power_cost[range]
+        u.provides_spinning_reserves = u.provides_spinning_reserves[range]
+        for s in u.cost_segments
+            s.mw = s.mw[range]
+            s.cost = s.cost[range]
+        end
+    end
+    for b in modified.buses
+        b.load = b.load[range]
+    end
+    for l in modified.lines
+        l.normal_flow_limit = l.normal_flow_limit[range]
+        l.emergency_flow_limit = l.emergency_flow_limit[range]
+        l.flow_limit_penalty = l.flow_limit_penalty[range]
+    end
+    for ps in modified.price_sensitive_loads
+        ps.demand = ps.demand[range]
+        ps.revenue = ps.revenue[range]
+    end
+    return modified
+end

src/utils/log.jl

@@ -49,6 +49,9 @@ function handle_message(
     if level >= logger.screen_log_level
         printstyled(time_string, color = color)
         println(message)
+        flush(stdout)
+        flush(stderr)
+        Base.Libc.flush_cstdio()
     end
     if logger.file !== nothing && level >= logger.io_log_level
         write(logger.file, time_string)

src/utils/sysimage.jl

@@ -0,0 +1,33 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+using PackageCompiler
+using TOML
+using Logging
+
+Logging.disable_logging(Logging.Info)
+mkpath("build")
+
+println("Generating precompilation statements...")
+run(`julia --project=. --trace-compile=build/precompile.jl $(ARGS)`)
+
+println("Finding dependencies...")
+project = TOML.parsefile("Project.toml")
+manifest = TOML.parsefile("Manifest.toml")
+deps = Symbol[]
+for dep in keys(project["deps"])
+    if "path" in keys(manifest[dep][1])
+        println("  - $(dep) [skip]")
+    else
+        println("  - $(dep)")
+        push!(deps, Symbol(dep))
+    end
+end
+
+println("Building system image...")
+create_sysimage(
+    deps,
+    precompile_statements_file = "build/precompile.jl",
+    sysimage_path = "build/sysimage.so",
+)

src/validation/repair.jl

@@ -0,0 +1,69 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+"""
+    repair!(instance)
+
+Verifies that the given unit commitment instance is valid and automatically
+fixes some validation errors if possible, issuing a warning for each error
+found. If a validation error cannot be automatically fixed, issues an
+exception.
+
+Returns the number of validation errors found.
+"""
+function repair!(instance::UnitCommitmentInstance)::Int
+    n_errors = 0
+
+    for g in instance.units
+
+        # Startup costs and delays must be increasing
+        for s in 2:length(g.startup_categories)
+            if g.startup_categories[s].delay <= g.startup_categories[s-1].delay
+                prev_value = g.startup_categories[s].delay
+                new_value = g.startup_categories[s-1].delay + 1
+                @warn "Generator $(g.name) has non-increasing startup delays (category $s). " *
+                      "Changing delay: $prev_value → $new_value"
+                g.startup_categories[s].delay = new_value
+                n_errors += 1
+            end
+
+            if g.startup_categories[s].cost < g.startup_categories[s-1].cost
+                prev_value = g.startup_categories[s].cost
+                new_value = g.startup_categories[s-1].cost
+                @warn "Generator $(g.name) has decreasing startup cost (category $s). " *
+                      "Changing cost: $prev_value → $new_value"
+                g.startup_categories[s].cost = new_value
+                n_errors += 1
+            end
+        end
+
+        for t in 1:instance.time
+            # Production cost curve should be convex
+            for k in 2:length(g.cost_segments)
+                cost = g.cost_segments[k].cost[t]
+                min_cost = g.cost_segments[k-1].cost[t]
+                if cost < min_cost - 1e-5
+                    @warn "Generator $(g.name) has non-convex production cost curve " *
+                          "(segment $k, time $t). Changing cost: $cost → $min_cost"
+                    g.cost_segments[k].cost[t] = min_cost
+                    n_errors += 1
+                end
+            end
+
+            # Startup limit must be greater than min_power
+            if g.startup_limit < g.min_power[t]
+                new_limit = g.min_power[t]
+                prev_limit = g.startup_limit
+                @warn "Generator $(g.name) has startup limit lower than minimum power. " *
+                      "Changing startup limit: $prev_limit → $new_limit"
+                g.startup_limit = new_limit
+                n_errors += 1
+            end
+        end
+    end
+
+    return n_errors
+end
+
+export repair!

src/validation/validate.jl

@@ -6,70 +6,6 @@ using Printf
 
 bin(x) = [xi > 0.5 for xi in x]
 
-"""
-    repair!(instance)
-
-Verifies that the given unit commitment instance is valid and automatically
-fixes some validation errors if possible, issuing a warning for each error
-found. If a validation error cannot be automatically fixed, issues an
-exception.
-
-Returns the number of validation errors found.
-"""
-function repair!(instance::UnitCommitmentInstance)::Int
-    n_errors = 0
-
-    for g in instance.units
-
-        # Startup costs and delays must be increasing
-        for s in 2:length(g.startup_categories)
-            if g.startup_categories[s].delay <= g.startup_categories[s-1].delay
-                prev_value = g.startup_categories[s].delay
-                new_value = g.startup_categories[s-1].delay + 1
-                @warn "Generator $(g.name) has non-increasing startup delays (category $s). " *
-                      "Changing delay: $prev_value → $new_value"
-                g.startup_categories[s].delay = new_value
-                n_errors += 1
-            end
-
-            if g.startup_categories[s].cost < g.startup_categories[s-1].cost
-                prev_value = g.startup_categories[s].cost
-                new_value = g.startup_categories[s-1].cost
-                @warn "Generator $(g.name) has decreasing startup cost (category $s). " *
-                      "Changing cost: $prev_value → $new_value"
-                g.startup_categories[s].cost = new_value
-                n_errors += 1
-            end
-        end
-
-        for t in 1:instance.time
-            # Production cost curve should be convex
-            for k in 2:length(g.cost_segments)
-                cost = g.cost_segments[k].cost[t]
-                min_cost = g.cost_segments[k-1].cost[t]
-                if cost < min_cost - 1e-5
-                    @warn "Generator $(g.name) has non-convex production cost curve " *
-                          "(segment $k, time $t). Changing cost: $cost → $min_cost"
-                    g.cost_segments[k].cost[t] = min_cost
-                    n_errors += 1
-                end
-            end
-
-            # Startup limit must be greater than min_power
-            if g.startup_limit < g.min_power[t]
-                new_limit = g.min_power[t]
-                prev_limit = g.startup_limit
-                @warn "Generator $(g.name) has startup limit lower than minimum power. " *
-                      "Changing startup limit: $prev_limit → $new_limit"
-                g.startup_limit = new_limit
-                n_errors += 1
-            end
-        end
-    end
-
-    return n_errors
-end
-
 function validate(instance_filename::String, solution_filename::String)
     instance = UnitCommitment.read(instance_filename)
     solution = JSON.parse(open(solution_filename))
@@ -272,12 +208,8 @@ function _validate_units(instance, solution; tol = 0.01)
                         break
                     end
                 end
-                if t == time_down + 1
-                    initial_down = unit.min_downtime
-                    if unit.initial_status < 0
-                        initial_down = -unit.initial_status
-                    end
-                    time_down += initial_down
+                if (t == time_down + 1) && (unit.initial_status < 0)
+                    time_down -= unit.initial_status
                 end
 
                 # Calculate startup costs
@@ -310,14 +242,6 @@ function _validate_units(instance, solution; tol = 0.01)
                         break
                     end
                 end
-                if t == time_up + 1
-                    initial_up = unit.min_uptime
-                    if unit.initial_status > 0
-                        initial_up = unit.initial_status
-                    end
-                    time_up += initial_up
-                end
-
                 if (t == time_up + 1) && (unit.initial_status > 0)
                     time_up += unit.initial_status
                 end
@@ -400,11 +324,16 @@ function _validate_reserve_and_demand(instance, solution, tol = 0.01)
         # Verify spinning reserves
         reserve =
             sum(solution["Reserve (MW)"][g.name][t] for g in instance.units)
-        if reserve < instance.reserves.spinning[t] - tol
+        reserve_shortfall =
+            (instance.shortfall_penalty[t] >= 0) ?
+            solution["Reserve shortfall (MW)"][t] : 0
+
+        if reserve + reserve_shortfall < instance.reserves.spinning[t] - tol
             @error @sprintf(
-                "Insufficient spinning reserves at time %d (%.2f should be %.2f)",
+                "Insufficient spinning reserves at time %d (%.2f + %.2f should be %.2f)",
                 t,
                 reserve,
+                reserve_shortfall,
                 instance.reserves.spinning[t],
             )
             err_count += 1

test/Project.toml

@@ -0,0 +1,26 @@
+[deps]
+Cbc = "9961bab8-2fa3-5c5a-9d89-47fab24efd76"
+DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
+Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
+GZip = "92fee26a-97fe-5a0c-ad85-20a5f3185b63"
+Gurobi = "2e9cd046-0924-5485-92f1-d5272153d98b"
+JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
+JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Logging = "56ddb016-857b-54e1-b83d-db4d58db5568"
+MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
+PackageCompiler = "9b87118b-4619-50d2-8e1e-99f35a4d4d9d"
+Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[compat]
+DataStructures = "0.18"
+Distributions = "0.25"
+GZip = "0.5"
+JSON = "0.21"
+JuMP = "0.21"
+MathOptInterface = "0.9"
+PackageCompiler = "1"
+julia = "1"

test/convert_test.jl

@@ -1,22 +0,0 @@
-# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
-# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
-# Released under the modified BSD license. See COPYING.md for more details.
-
-using UnitCommitment
-
-@testset "convert" begin
-    @testset "EGRET solution" begin
-        solution =
-            UnitCommitment._read_egret_solution("fixtures/egret_output.json.gz")
-        for attr in ["Is on", "Production (MW)", "Production cost (\$)"]
-            @test attr in keys(solution)
-            @test "115_STEAM_1" in keys(solution[attr])
-            @test length(solution[attr]["115_STEAM_1"]) == 48
-        end
-        @test solution["Production cost (\$)"]["315_CT_6"][15:20] ==
-              [0.0, 0.0, 884.44, 1470.71, 1470.71, 884.44]
-        @test solution["Startup cost (\$)"]["315_CT_6"][15:20] ==
-              [0.0, 0.0, 5665.23, 0.0, 0.0, 0.0]
-        @test length(keys(solution["Is on"])) == 154
-    end
-end

test/import/egret_test.jl

@@ -0,0 +1,23 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+using UnitCommitment
+
+basedir = @__DIR__
+
+@testset "read_egret_solution" begin
+    solution = UnitCommitment.read_egret_solution(
+        "$basedir/../fixtures/egret_output.json.gz",
+    )
+    for attr in ["Is on", "Production (MW)", "Production cost (\$)"]
+        @test attr in keys(solution)
+        @test "115_STEAM_1" in keys(solution[attr])
+        @test length(solution[attr]["115_STEAM_1"]) == 48
+    end
+    @test solution["Production cost (\$)"]["315_CT_6"][15:20] ==
+          [0.0, 0.0, 884.44, 1470.71, 1470.71, 884.44]
+    @test solution["Startup cost (\$)"]["315_CT_6"][15:20] ==
+          [0.0, 0.0, 5665.23, 0.0, 0.0, 0.0]
+    @test length(keys(solution["Is on"])) == 154
+end

test/instance/read_test.jl

@@ -0,0 +1,121 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+using UnitCommitment, LinearAlgebra, Cbc, JuMP, JSON, GZip
+
+@testset "read_benchmark" begin
+    instance = UnitCommitment.read_benchmark("test/case14")
+
+    @test length(instance.lines) == 20
+    @test length(instance.buses) == 14
+    @test length(instance.units) == 6
+    @test length(instance.contingencies) == 19
+    @test length(instance.price_sensitive_loads) == 1
+    @test instance.time == 4
+
+    @test instance.lines[5].name == "l5"
+    @test instance.lines[5].source.name == "b2"
+    @test instance.lines[5].target.name == "b5"
+    @test instance.lines[5].reactance ≈ 0.17388
+    @test instance.lines[5].susceptance ≈ 10.037550333
+    @test instance.lines[5].normal_flow_limit == [1e8 for t in 1:4]
+    @test instance.lines[5].emergency_flow_limit == [1e8 for t in 1:4]
+    @test instance.lines[5].flow_limit_penalty == [5e3 for t in 1:4]
+    @test instance.lines_by_name["l5"].name == "l5"
+
+    @test instance.lines[1].name == "l1"
+    @test instance.lines[1].source.name == "b1"
+    @test instance.lines[1].target.name == "b2"
+    @test instance.lines[1].reactance ≈ 0.059170
+    @test instance.lines[1].susceptance ≈ 29.496860773945
+    @test instance.lines[1].normal_flow_limit == [300.0 for t in 1:4]
+    @test instance.lines[1].emergency_flow_limit == [400.0 for t in 1:4]
+    @test instance.lines[1].flow_limit_penalty == [1e3 for t in 1:4]
+
+    @test instance.buses[9].name == "b9"
+    @test instance.buses[9].load == [35.36638, 33.25495, 31.67138, 31.14353]
+    @test instance.buses_by_name["b9"].name == "b9"
+
+    unit = instance.units[1]
+    @test unit.name == "g1"
+    @test unit.bus.name == "b1"
+    @test unit.ramp_up_limit == 1e6
+    @test unit.ramp_down_limit == 1e6
+    @test unit.startup_limit == 1e6
+    @test unit.shutdown_limit == 1e6
+    @test unit.must_run == [false for t in 1:4]
+    @test unit.min_power_cost == [1400.0 for t in 1:4]
+    @test unit.min_uptime == 1
+    @test unit.min_downtime == 1
+    @test unit.provides_spinning_reserves == [true for t in 1:4]
+    for t in 1:1
+        @test unit.cost_segments[1].mw[t] == 10.0
+        @test unit.cost_segments[2].mw[t] == 20.0
+        @test unit.cost_segments[3].mw[t] == 5.0
+        @test unit.cost_segments[1].cost[t] ≈ 20.0
+        @test unit.cost_segments[2].cost[t] ≈ 30.0
+        @test unit.cost_segments[3].cost[t] ≈ 40.0
+    end
+    @test length(unit.startup_categories) == 3
+    @test unit.startup_categories[1].delay == 1
+    @test unit.startup_categories[2].delay == 2
+    @test unit.startup_categories[3].delay == 3
+    @test unit.startup_categories[1].cost == 1000.0
+    @test unit.startup_categories[2].cost == 1500.0
+    @test unit.startup_categories[3].cost == 2000.0
+    @test instance.units_by_name["g1"].name == "g1"
+
+    unit = instance.units[2]
+    @test unit.name == "g2"
+    @test unit.must_run == [false for t in 1:4]
+
+    unit = instance.units[3]
+    @test unit.name == "g3"
+    @test unit.bus.name == "b3"
+    @test unit.ramp_up_limit == 70.0
+    @test unit.ramp_down_limit == 70.0
+    @test unit.startup_limit == 70.0
+    @test unit.shutdown_limit == 70.0
+    @test unit.must_run == [true for t in 1:4]
+    @test unit.min_power_cost == [0.0 for t in 1:4]
+    @test unit.min_uptime == 1
+    @test unit.min_downtime == 1
+    @test unit.provides_spinning_reserves == [true for t in 1:4]
+    for t in 1:4
+        @test unit.cost_segments[1].mw[t] ≈ 33
+        @test unit.cost_segments[2].mw[t] ≈ 33
+        @test unit.cost_segments[3].mw[t] ≈ 34
+        @test unit.cost_segments[1].cost[t] ≈ 33.75
+        @test unit.cost_segments[2].cost[t] ≈ 38.04
+        @test unit.cost_segments[3].cost[t] ≈ 44.77853
+    end
+
+    @test instance.reserves.spinning == zeros(4)
+
+    @test instance.contingencies[1].lines == [instance.lines[1]]
+    @test instance.contingencies[1].units == []
+    @test instance.contingencies[1].name == "c1"
+    @test instance.contingencies_by_name["c1"].name == "c1"
+
+    load = instance.price_sensitive_loads[1]
+    @test load.name == "ps1"
+    @test load.bus.name == "b3"
+    @test load.revenue == [100.0 for t in 1:4]
+    @test load.demand == [50.0 for t in 1:4]
+    @test instance.price_sensitive_loads_by_name["ps1"].name == "ps1"
+end
+
+@testset "read_benchmark sub-hourly" begin
+    instance = UnitCommitment.read_benchmark("test/case14-sub-hourly")
+    @test instance.time == 4
+    unit = instance.units[1]
+    @test unit.name == "g1"
+    @test unit.min_uptime == 2
+    @test unit.min_downtime == 2
+    @test length(unit.startup_categories) == 3
+    @test unit.startup_categories[1].delay == 2
+    @test unit.startup_categories[2].delay == 4
+    @test unit.startup_categories[3].delay == 6
+    @test unit.initial_status == -200
+end

test/instance_test.jl

@@ -1,158 +0,0 @@
-# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
-# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
-# Released under the modified BSD license. See COPYING.md for more details.
-
-using UnitCommitment, LinearAlgebra, Cbc, JuMP, JSON, GZip
-
-@testset "Instance" begin
-    @testset "read" begin
-        instance = UnitCommitment.read_benchmark("test/case14")
-
-        @test length(instance.lines) == 20
-        @test length(instance.buses) == 14
-        @test length(instance.units) == 6
-        @test length(instance.contingencies) == 19
-        @test length(instance.price_sensitive_loads) == 1
-        @test instance.time == 4
-
-        @test instance.lines[5].name == "l5"
-        @test instance.lines[5].source.name == "b2"
-        @test instance.lines[5].target.name == "b5"
-        @test instance.lines[5].reactance ≈ 0.17388
-        @test instance.lines[5].susceptance ≈ 10.037550333
-        @test instance.lines[5].normal_flow_limit == [1e8 for t in 1:4]
-        @test instance.lines[5].emergency_flow_limit == [1e8 for t in 1:4]
-        @test instance.lines[5].flow_limit_penalty == [5e3 for t in 1:4]
-
-        @test instance.lines[1].name == "l1"
-        @test instance.lines[1].source.name == "b1"
-        @test instance.lines[1].target.name == "b2"
-        @test instance.lines[1].reactance ≈ 0.059170
-        @test instance.lines[1].susceptance ≈ 29.496860773945
-        @test instance.lines[1].normal_flow_limit == [300.0 for t in 1:4]
-        @test instance.lines[1].emergency_flow_limit == [400.0 for t in 1:4]
-        @test instance.lines[1].flow_limit_penalty == [1e3 for t in 1:4]
-
-        @test instance.buses[9].name == "b9"
-        @test instance.buses[9].load == [35.36638, 33.25495, 31.67138, 31.14353]
-
-        unit = instance.units[1]
-        @test unit.name == "g1"
-        @test unit.bus.name == "b1"
-        @test unit.ramp_up_limit == 1e6
-        @test unit.ramp_down_limit == 1e6
-        @test unit.startup_limit == 1e6
-        @test unit.shutdown_limit == 1e6
-        @test unit.must_run == [false for t in 1:4]
-        @test unit.min_power_cost == [1400.0 for t in 1:4]
-        @test unit.min_uptime == 1
-        @test unit.min_downtime == 1
-        @test unit.provides_spinning_reserves == [true for t in 1:4]
-        for t in 1:1
-            @test unit.cost_segments[1].mw[t] == 10.0
-            @test unit.cost_segments[2].mw[t] == 20.0
-            @test unit.cost_segments[3].mw[t] == 5.0
-            @test unit.cost_segments[1].cost[t] ≈ 20.0
-            @test unit.cost_segments[2].cost[t] ≈ 30.0
-            @test unit.cost_segments[3].cost[t] ≈ 40.0
-        end
-        @test length(unit.startup_categories) == 3
-        @test unit.startup_categories[1].delay == 1
-        @test unit.startup_categories[2].delay == 2
-        @test unit.startup_categories[3].delay == 3
-        @test unit.startup_categories[1].cost == 1000.0
-        @test unit.startup_categories[2].cost == 1500.0
-        @test unit.startup_categories[3].cost == 2000.0
-
-        unit = instance.units[2]
-        @test unit.name == "g2"
-        @test unit.must_run == [false for t in 1:4]
-
-        unit = instance.units[3]
-        @test unit.name == "g3"
-        @test unit.bus.name == "b3"
-        @test unit.ramp_up_limit == 70.0
-        @test unit.ramp_down_limit == 70.0
-        @test unit.startup_limit == 70.0
-        @test unit.shutdown_limit == 70.0
-        @test unit.must_run == [true for t in 1:4]
-        @test unit.min_power_cost == [0.0 for t in 1:4]
-        @test unit.min_uptime == 1
-        @test unit.min_downtime == 1
-        @test unit.provides_spinning_reserves == [true for t in 1:4]
-        for t in 1:4
-            @test unit.cost_segments[1].mw[t] ≈ 33
-            @test unit.cost_segments[2].mw[t] ≈ 33
-            @test unit.cost_segments[3].mw[t] ≈ 34
-            @test unit.cost_segments[1].cost[t] ≈ 33.75
-            @test unit.cost_segments[2].cost[t] ≈ 38.04
-            @test unit.cost_segments[3].cost[t] ≈ 44.77853
-        end
-
-        @test instance.reserves.spinning == zeros(4)
-
-        @test instance.contingencies[1].lines == [instance.lines[1]]
-        @test instance.contingencies[1].units == []
-
-        load = instance.price_sensitive_loads[1]
-        @test load.name == "ps1"
-        @test load.bus.name == "b3"
-        @test load.revenue == [100.0 for t in 1:4]
-        @test load.demand == [50.0 for t in 1:4]
-    end
-
-    @testset "read sub-hourly" begin
-        instance = UnitCommitment.read_benchmark("test/case14-sub-hourly")
-        @test instance.time == 4
-        unit = instance.units[1]
-        @test unit.name == "g1"
-        @test unit.min_uptime == 2
-        @test unit.min_downtime == 2
-        @test length(unit.startup_categories) == 3
-        @test unit.startup_categories[1].delay == 2
-        @test unit.startup_categories[2].delay == 4
-        @test unit.startup_categories[3].delay == 6
-        @test unit.initial_status == -200
-    end
-
-    @testset "slice" begin
-        instance = UnitCommitment.read_benchmark("test/case14")
-        modified = UnitCommitment.slice(instance, 1:2)
-
-        # Should update all time-dependent fields
-        @test modified.time == 2
-        @test length(modified.power_balance_penalty) == 2
-        @test length(modified.reserves.spinning) == 2
-        for u in modified.units
-            @test length(u.max_power) == 2
-            @test length(u.min_power) == 2
-            @test length(u.must_run) == 2
-            @test length(u.min_power_cost) == 2
-            @test length(u.provides_spinning_reserves) == 2
-            for s in u.cost_segments
-                @test length(s.mw) == 2
-                @test length(s.cost) == 2
-            end
-        end
-        for b in modified.buses
-            @test length(b.load) == 2
-        end
-        for l in modified.lines
-            @test length(l.normal_flow_limit) == 2
-            @test length(l.emergency_flow_limit) == 2
-            @test length(l.flow_limit_penalty) == 2
-        end
-        for ps in modified.price_sensitive_loads
-            @test length(ps.demand) == 2
-            @test length(ps.revenue) == 2
-        end
-
-        # Should be able to build model without errors
-        optimizer = optimizer_with_attributes(Cbc.Optimizer, "logLevel" => 0)
-        model = build_model(
-            instance = modified,
-            optimizer = optimizer,
-            variable_names = true,
-        )
-    end
-end

test/model/formulations_test.jl

@@ -0,0 +1,74 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+using UnitCommitment
+using JuMP
+import UnitCommitment:
+    ArrCon2000,
+    CarArr2006,
+    DamKucRajAta2016,
+    Formulation,
+    Gar1962,
+    KnuOstWat2018,
+    MorLatRam2013,
+    PanGua2016,
+    XavQiuWanThi2019
+
+if ENABLE_LARGE_TESTS
+    using Gurobi
+end
+
+function _small_test(formulation::Formulation)::Nothing
+    instances = ["matpower/case118/2017-02-01", "test/case14"]
+    for instance in instances
+        # Should not crash
+        UnitCommitment.build_model(
+            instance = UnitCommitment.read_benchmark(instance),
+            formulation = formulation,
+        )
+    end
+    return
+end
+
+function _large_test(formulation::Formulation)::Nothing
+    instances = ["pglib-uc/ca/Scenario400_reserves_1"]
+    for instance in instances
+        instance = UnitCommitment.read_benchmark(instance)
+        model = UnitCommitment.build_model(
+            instance = instance,
+            formulation = formulation,
+            optimizer = Gurobi.Optimizer,
+        )
+        UnitCommitment.optimize!(
+            model,
+            XavQiuWanThi2019.Method(two_phase_gap = false, gap_limit = 0.1),
+        )
+        solution = UnitCommitment.solution(model)
+        @test UnitCommitment.validate(instance, solution)
+    end
+    return
+end
+
+function _test(formulation::Formulation)::Nothing
+    _small_test(formulation)
+    if ENABLE_LARGE_TESTS
+        _large_test(formulation)
+    end
+end
+
+@testset "formulations" begin
+    _test(Formulation())
+    _test(Formulation(ramping = ArrCon2000.Ramping()))
+    # _test(Formulation(ramping = DamKucRajAta2016.Ramping()))
+    _test(
+        Formulation(
+            ramping = MorLatRam2013.Ramping(),
+            startup_costs = MorLatRam2013.StartupCosts(),
+        ),
+    )
+    _test(Formulation(ramping = PanGua2016.Ramping()))
+    _test(Formulation(pwl_costs = Gar1962.PwlCosts()))
+    _test(Formulation(pwl_costs = CarArr2006.PwlCosts()))
+    _test(Formulation(pwl_costs = KnuOstWat2018.PwlCosts()))
+end

test/model_test.jl

@@ -1,39 +0,0 @@
-# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
-# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
-# Released under the modified BSD license. See COPYING.md for more details.
-
-using UnitCommitment, LinearAlgebra, Cbc, JuMP
-
-@testset "Model" begin
-    @testset "Run" begin
-        instance = UnitCommitment.read_benchmark("test/case14")
-        for line in instance.lines, t in 1:4
-            line.normal_flow_limit[t] = 10.0
-        end
-        optimizer = optimizer_with_attributes(Cbc.Optimizer, "logLevel" => 0)
-        model = build_model(
-            instance = instance,
-            optimizer = optimizer,
-            variable_names = true,
-        )
-        @test name(model[:is_on]["g1", 1]) == "is_on[g1,1]"
-
-        # Optimize and retrieve solution
-        UnitCommitment.optimize!(model)
-        solution = UnitCommitment.solution(model)
-
-        # Write solution to a file
-        filename = tempname()
-        UnitCommitment.write(filename, solution)
-        loaded = JSON.parsefile(filename)
-        @test length(loaded["Is on"]) == 6
-
-        # Verify solution
-        @test UnitCommitment.validate(instance, solution)
-
-        # Reoptimize with fixed solution
-        UnitCommitment.fix!(model, solution)
-        UnitCommitment.optimize!(model)
-        @test UnitCommitment.validate(instance, solution)
-    end
-end

test/runtests.jl

@@ -5,14 +5,35 @@
 using Test
 using UnitCommitment
 
+push!(Base.LOAD_PATH, @__DIR__)
 UnitCommitment._setup_logger()
 
+const ENABLE_LARGE_TESTS = ("UCJL_LARGE_TESTS" in keys(ENV))
+
 @testset "UnitCommitment" begin
-    include("instance_test.jl")
-    include("model_test.jl")
-    include("sensitivity_test.jl")
-    include("screening_test.jl")
-    include("convert_test.jl")
-    include("validate_test.jl")
-    include("initcond_test.jl")
+    include("usage.jl")
+    @testset "import" begin
+        include("import/egret_test.jl")
+    end
+    @testset "instance" begin
+        include("instance/read_test.jl")
+    end
+    @testset "model" begin
+        include("model/formulations_test.jl")
+    end
+    @testset "XavQiuWanThi19" begin
+        include("solution/methods/XavQiuWanThi19/filter_test.jl")
+        include("solution/methods/XavQiuWanThi19/find_test.jl")
+        include("solution/methods/XavQiuWanThi19/sensitivity_test.jl")
+    end
+    @testset "transform" begin
+        include("transform/initcond_test.jl")
+        include("transform/slice_test.jl")
+        @testset "randomize" begin
+            include("transform/randomize/XavQiuAhm2021_test.jl")
+        end
+    end
+    @testset "validation" begin
+        include("validation/repair_test.jl")
+    end
 end

test/screening_test.jl

@@ -1,112 +0,0 @@
-# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
-# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
-# Released under the modified BSD license. See COPYING.md for more details.
-
-using UnitCommitment, Test, LinearAlgebra
-import UnitCommitment: Violation, _offer, _query
-
-@testset "Screening" begin
-    @testset "Violation filter" begin
-        instance = UnitCommitment.read_benchmark("test/case14")
-        filter = UnitCommitment.ViolationFilter(max_per_line = 1, max_total = 2)
-
-        _offer(
-            filter,
-            Violation(
-                time = 1,
-                monitored_line = instance.lines[1],
-                outage_line = nothing,
-                amount = 100.0,
-            ),
-        )
-        _offer(
-            filter,
-            Violation(
-                time = 1,
-                monitored_line = instance.lines[1],
-                outage_line = instance.lines[1],
-                amount = 300.0,
-            ),
-        )
-        _offer(
-            filter,
-            Violation(
-                time = 1,
-                monitored_line = instance.lines[1],
-                outage_line = instance.lines[5],
-                amount = 500.0,
-            ),
-        )
-        _offer(
-            filter,
-            Violation(
-                time = 1,
-                monitored_line = instance.lines[1],
-                outage_line = instance.lines[4],
-                amount = 400.0,
-            ),
-        )
-        _offer(
-            filter,
-            Violation(
-                time = 1,
-                monitored_line = instance.lines[2],
-                outage_line = instance.lines[1],
-                amount = 200.0,
-            ),
-        )
-        _offer(
-            filter,
-            Violation(
-                time = 1,
-                monitored_line = instance.lines[2],
-                outage_line = instance.lines[8],
-                amount = 100.0,
-            ),
-        )
-
-        actual = _query(filter)
-        expected = [
-            Violation(
-                time = 1,
-                monitored_line = instance.lines[2],
-                outage_line = instance.lines[1],
-                amount = 200.0,
-            ),
-            Violation(
-                time = 1,
-                monitored_line = instance.lines[1],
-                outage_line = instance.lines[5],
-                amount = 500.0,
-            ),
-        ]
-        @test actual == expected
-    end
-
-    @testset "find_violations" begin
-        instance = UnitCommitment.read_benchmark("test/case14")
-        for line in instance.lines, t in 1:instance.time
-            line.normal_flow_limit[t] = 1.0
-            line.emergency_flow_limit[t] = 1.0
-        end
-        isf = UnitCommitment._injection_shift_factors(
-            lines = instance.lines,
-            buses = instance.buses,
-        )
-        lodf = UnitCommitment._line_outage_factors(
-            lines = instance.lines,
-            buses = instance.buses,
-            isf = isf,
-        )
-        inj = [1000.0 for b in 1:13, t in 1:instance.time]
-        overflow = [0.0 for l in instance.lines, t in 1:instance.time]
-        violations = UnitCommitment._find_violations(
-            instance = instance,
-            net_injections = inj,
-            overflow = overflow,
-            isf = isf,
-            lodf = lodf,
-        )
-        @test length(violations) == 20
-    end
-end

test/sensitivity_test.jl

@@ -1,145 +0,0 @@
-# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
-# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
-# Released under the modified BSD license. See COPYING.md for more details.
-
-using UnitCommitment, Test, LinearAlgebra
-
-@testset "Sensitivity" begin
-    @testset "Susceptance matrix" begin
-        instance = UnitCommitment.read_benchmark("test/case14")
-        actual = UnitCommitment._susceptance_matrix(instance.lines)
-        @test size(actual) == (20, 20)
-        expected = Diagonal([
-            29.5,
-            7.83,
-            8.82,
-            9.9,
-            10.04,
-            10.2,
-            41.45,
-            8.35,
-            3.14,
-            6.93,
-            8.77,
-            6.82,
-            13.4,
-            9.91,
-            15.87,
-            20.65,
-            6.46,
-            9.09,
-            8.73,
-            5.02,
-        ])
-        @test round.(actual, digits = 2) == expected
-    end
-
-    @testset "Reduced incidence matrix" begin
-        instance = UnitCommitment.read_benchmark("test/case14")
-        actual = UnitCommitment._reduced_incidence_matrix(
-            lines = instance.lines,
-            buses = instance.buses,
-        )
-        @test size(actual) == (20, 13)
-        @test actual[1, 1] == -1.0
-        @test actual[3, 1] == 1.0
-        @test actual[4, 1] == 1.0
-        @test actual[5, 1] == 1.0
-        @test actual[3, 2] == -1.0
-        @test actual[6, 2] == 1.0
-        @test actual[4, 3] == -1.0
-        @test actual[6, 3] == -1.0
-        @test actual[7, 3] == 1.0
-        @test actual[8, 3] == 1.0
-        @test actual[9, 3] == 1.0
-        @test actual[2, 4] == -1.0
-        @test actual[5, 4] == -1.0
-        @test actual[7, 4] == -1.0
-        @test actual[10, 4] == 1.0
-        @test actual[10, 5] == -1.0
-        @test actual[11, 5] == 1.0
-        @test actual[12, 5] == 1.0
-        @test actual[13, 5] == 1.0
-        @test actual[8, 6] == -1.0
-        @test actual[14, 6] == 1.0
-        @test actual[15, 6] == 1.0
-        @test actual[14, 7] == -1.0
-        @test actual[9, 8] == -1.0
-        @test actual[15, 8] == -1.0
-        @test actual[16, 8] == 1.0
-        @test actual[17, 8] == 1.0
-        @test actual[16, 9] == -1.0
-        @test actual[18, 9] == 1.0
-        @test actual[11, 10] == -1.0
-        @test actual[18, 10] == -1.0
-        @test actual[12, 11] == -1.0
-        @test actual[19, 11] == 1.0
-        @test actual[13, 12] == -1.0
-        @test actual[19, 12] == -1.0
-        @test actual[20, 12] == 1.0
-        @test actual[17, 13] == -1.0
-        @test actual[20, 13] == -1.0
-    end
-
-    @testset "Injection Shift Factors (ISF)" begin
-        instance = UnitCommitment.read_benchmark("test/case14")
-        actual = UnitCommitment._injection_shift_factors(
-            lines = instance.lines,
-            buses = instance.buses,
-        )
-        @test size(actual) == (20, 13)
-        @test round.(actual, digits = 2) == [
-            -0.84 -0.75 -0.67 -0.61 -0.63 -0.66 -0.66 -0.65 -0.65 -0.64 -0.63 -0.63 -0.64
-            -0.16 -0.25 -0.33 -0.39 -0.37 -0.34 -0.34 -0.35 -0.35 -0.36 -0.37 -0.37 -0.36
-            0.03 -0.53 -0.15 -0.1 -0.12 -0.14 -0.14 -0.14 -0.13 -0.13 -0.12 -0.12 -0.13
-            0.06 -0.14 -0.32 -0.22 -0.25 -0.3 -0.3 -0.29 -0.28 -0.27 -0.25 -0.26 -0.27
-            0.08 -0.07 -0.2 -0.29 -0.26 -0.22 -0.22 -0.22 -0.23 -0.25 -0.26 -0.26 -0.24
-            0.03 0.47 -0.15 -0.1 -0.12 -0.14 -0.14 -0.14 -0.13 -0.13 -0.12 -0.12 -0.13
-            0.08 0.31 0.5 -0.3 -0.03 0.36 0.36 0.28 0.23 0.1 -0.0 0.02 0.17
-            0.0 0.01 0.02 -0.01 -0.22 -0.63 -0.63 -0.45 -0.41 -0.32 -0.24 -0.25 -0.36
-            0.0 0.01 0.01 -0.01 -0.12 -0.17 -0.17 -0.26 -0.24 -0.18 -0.14 -0.14 -0.21
-            -0.0 -0.02 -0.03 0.02 -0.66 -0.2 -0.2 -0.29 -0.36 -0.5 -0.63 -0.61 -0.43
-            -0.0 -0.01 -0.02 0.01 0.21 -0.12 -0.12 -0.17 -0.28 -0.53 0.18 0.15 -0.03
-            -0.0 -0.0 -0.0 0.0 0.03 -0.02 -0.02 -0.03 -0.02 0.01 -0.52 -0.17 -0.09
-            -0.0 -0.01 -0.01 0.01 0.11 -0.06 -0.06 -0.09 -0.05 0.02 -0.28 -0.59 -0.31
-            -0.0 -0.0 -0.0 -0.0 -0.0 -0.0 -1.0 -0.0 -0.0 -0.0 -0.0 -0.0 0.0
-            0.0 0.01 0.02 -0.01 -0.22 0.37 0.37 -0.45 -0.41 -0.32 -0.24 -0.25 -0.36
-            0.0 0.01 0.02 -0.01 -0.21 0.12 0.12 0.17 -0.72 -0.47 -0.18 -0.15 0.03
-            0.0 0.01 0.01 -0.01 -0.14 0.08 0.08 0.12 0.07 -0.03 -0.2 -0.24 -0.6
-            0.0 0.01 0.02 -0.01 -0.21 0.12 0.12 0.17 0.28 -0.47 -0.18 -0.15 0.03
-            -0.0 -0.0 -0.0 0.0 0.03 -0.02 -0.02 -0.03 -0.02 0.01 0.48 -0.17 -0.09
-            -0.0 -0.01 -0.01 0.01 0.14 -0.08 -0.08 -0.12 -0.07 0.03 0.2 0.24 -0.4
-        ]
-    end
-
-    @testset "Line Outage Distribution Factors (LODF)" begin
-        instance = UnitCommitment.read_benchmark("test/case14")
-        isf_before = UnitCommitment._injection_shift_factors(
-            lines = instance.lines,
-            buses = instance.buses,
-        )
-        lodf = UnitCommitment._line_outage_factors(
-            lines = instance.lines,
-            buses = instance.buses,
-            isf = isf_before,
-        )
-        for contingency in instance.contingencies
-            for lc in contingency.lines
-                prev_susceptance = lc.susceptance
-                lc.susceptance = 0.0
-                isf_after = UnitCommitment._injection_shift_factors(
-                    lines = instance.lines,
-                    buses = instance.buses,
-                )
-                lc.susceptance = prev_susceptance
-                for lm in instance.lines
-                    expected = isf_after[lm.offset, :]
-                    actual =
-                        isf_before[lm.offset, :] +
-                        lodf[lm.offset, lc.offset] * isf_before[lc.offset, :]
-                    @test norm(expected - actual) < 1e-6
-                end
-            end
-        end
-    end
-end

test/solution/methods/XavQiuWanThi19/filter_test.jl

@@ -0,0 +1,83 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+using UnitCommitment, Test, LinearAlgebra
+import UnitCommitment: _Violation, _offer, _query
+
+@testset "_ViolationFilter" begin
+    instance = UnitCommitment.read_benchmark("test/case14")
+    filter = UnitCommitment._ViolationFilter(max_per_line = 1, max_total = 2)
+
+    _offer(
+        filter,
+        _Violation(
+            time = 1,
+            monitored_line = instance.lines[1],
+            outage_line = nothing,
+            amount = 100.0,
+        ),
+    )
+    _offer(
+        filter,
+        _Violation(
+            time = 1,
+            monitored_line = instance.lines[1],
+            outage_line = instance.lines[1],
+            amount = 300.0,
+        ),
+    )
+    _offer(
+        filter,
+        _Violation(
+            time = 1,
+            monitored_line = instance.lines[1],
+            outage_line = instance.lines[5],
+            amount = 500.0,
+        ),
+    )
+    _offer(
+        filter,
+        _Violation(
+            time = 1,
+            monitored_line = instance.lines[1],
+            outage_line = instance.lines[4],
+            amount = 400.0,
+        ),
+    )
+    _offer(
+        filter,
+        _Violation(
+            time = 1,
+            monitored_line = instance.lines[2],
+            outage_line = instance.lines[1],
+            amount = 200.0,
+        ),
+    )
+    _offer(
+        filter,
+        _Violation(
+            time = 1,
+            monitored_line = instance.lines[2],
+            outage_line = instance.lines[8],
+            amount = 100.0,
+        ),
+    )
+
+    actual = _query(filter)
+    expected = [
+        _Violation(
+            time = 1,
+            monitored_line = instance.lines[2],
+            outage_line = instance.lines[1],
+            amount = 200.0,
+        ),
+        _Violation(
+            time = 1,
+            monitored_line = instance.lines[1],
+            outage_line = instance.lines[5],
+            amount = 500.0,
+        ),
+    ]
+    @test actual == expected
+end

test/solution/methods/XavQiuWanThi19/find_test.jl

@@ -0,0 +1,35 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+using UnitCommitment, Test, LinearAlgebra
+import UnitCommitment: _Violation, _offer, _query
+
+@testset "find_violations" begin
+    instance = UnitCommitment.read_benchmark("test/case14")
+    for line in instance.lines, t in 1:instance.time
+        line.normal_flow_limit[t] = 1.0
+        line.emergency_flow_limit[t] = 1.0
+    end
+    isf = UnitCommitment._injection_shift_factors(
+        lines = instance.lines,
+        buses = instance.buses,
+    )
+    lodf = UnitCommitment._line_outage_factors(
+        lines = instance.lines,
+        buses = instance.buses,
+        isf = isf,
+    )
+    inj = [1000.0 for b in 1:13, t in 1:instance.time]
+    overflow = [0.0 for l in instance.lines, t in 1:instance.time]
+    violations = UnitCommitment._find_violations(
+        instance = instance,
+        net_injections = inj,
+        overflow = overflow,
+        isf = isf,
+        lodf = lodf,
+        max_per_line = 1,
+        max_per_period = 5,
+    )
+    @test length(violations) == 20
+end

test/solution/methods/XavQiuWanThi19/sensitivity_test.jl

@@ -0,0 +1,143 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+using UnitCommitment, Test, LinearAlgebra
+
+@testset "_susceptance_matrix" begin
+    instance = UnitCommitment.read_benchmark("test/case14")
+    actual = UnitCommitment._susceptance_matrix(instance.lines)
+    @test size(actual) == (20, 20)
+    expected = Diagonal([
+        29.5,
+        7.83,
+        8.82,
+        9.9,
+        10.04,
+        10.2,
+        41.45,
+        8.35,
+        3.14,
+        6.93,
+        8.77,
+        6.82,
+        13.4,
+        9.91,
+        15.87,
+        20.65,
+        6.46,
+        9.09,
+        8.73,
+        5.02,
+    ])
+    @test round.(actual, digits = 2) == expected
+end
+
+@testset "_reduced_incidence_matrix" begin
+    instance = UnitCommitment.read_benchmark("test/case14")
+    actual = UnitCommitment._reduced_incidence_matrix(
+        lines = instance.lines,
+        buses = instance.buses,
+    )
+    @test size(actual) == (20, 13)
+    @test actual[1, 1] == -1.0
+    @test actual[3, 1] == 1.0
+    @test actual[4, 1] == 1.0
+    @test actual[5, 1] == 1.0
+    @test actual[3, 2] == -1.0
+    @test actual[6, 2] == 1.0
+    @test actual[4, 3] == -1.0
+    @test actual[6, 3] == -1.0
+    @test actual[7, 3] == 1.0
+    @test actual[8, 3] == 1.0
+    @test actual[9, 3] == 1.0
+    @test actual[2, 4] == -1.0
+    @test actual[5, 4] == -1.0
+    @test actual[7, 4] == -1.0
+    @test actual[10, 4] == 1.0
+    @test actual[10, 5] == -1.0
+    @test actual[11, 5] == 1.0
+    @test actual[12, 5] == 1.0
+    @test actual[13, 5] == 1.0
+    @test actual[8, 6] == -1.0
+    @test actual[14, 6] == 1.0
+    @test actual[15, 6] == 1.0
+    @test actual[14, 7] == -1.0
+    @test actual[9, 8] == -1.0
+    @test actual[15, 8] == -1.0
+    @test actual[16, 8] == 1.0
+    @test actual[17, 8] == 1.0
+    @test actual[16, 9] == -1.0
+    @test actual[18, 9] == 1.0
+    @test actual[11, 10] == -1.0
+    @test actual[18, 10] == -1.0
+    @test actual[12, 11] == -1.0
+    @test actual[19, 11] == 1.0
+    @test actual[13, 12] == -1.0
+    @test actual[19, 12] == -1.0
+    @test actual[20, 12] == 1.0
+    @test actual[17, 13] == -1.0
+    @test actual[20, 13] == -1.0
+end
+
+@testset "_injection_shift_factors" begin
+    instance = UnitCommitment.read_benchmark("test/case14")
+    actual = UnitCommitment._injection_shift_factors(
+        lines = instance.lines,
+        buses = instance.buses,
+    )
+    @test size(actual) == (20, 13)
+    @test round.(actual, digits = 2) == [
+        -0.84 -0.75 -0.67 -0.61 -0.63 -0.66 -0.66 -0.65 -0.65 -0.64 -0.63 -0.63 -0.64
+        -0.16 -0.25 -0.33 -0.39 -0.37 -0.34 -0.34 -0.35 -0.35 -0.36 -0.37 -0.37 -0.36
+        0.03 -0.53 -0.15 -0.1 -0.12 -0.14 -0.14 -0.14 -0.13 -0.13 -0.12 -0.12 -0.13
+        0.06 -0.14 -0.32 -0.22 -0.25 -0.3 -0.3 -0.29 -0.28 -0.27 -0.25 -0.26 -0.27
+        0.08 -0.07 -0.2 -0.29 -0.26 -0.22 -0.22 -0.22 -0.23 -0.25 -0.26 -0.26 -0.24
+        0.03 0.47 -0.15 -0.1 -0.12 -0.14 -0.14 -0.14 -0.13 -0.13 -0.12 -0.12 -0.13
+        0.08 0.31 0.5 -0.3 -0.03 0.36 0.36 0.28 0.23 0.1 -0.0 0.02 0.17
+        0.0 0.01 0.02 -0.01 -0.22 -0.63 -0.63 -0.45 -0.41 -0.32 -0.24 -0.25 -0.36
+        0.0 0.01 0.01 -0.01 -0.12 -0.17 -0.17 -0.26 -0.24 -0.18 -0.14 -0.14 -0.21
+        -0.0 -0.02 -0.03 0.02 -0.66 -0.2 -0.2 -0.29 -0.36 -0.5 -0.63 -0.61 -0.43
+        -0.0 -0.01 -0.02 0.01 0.21 -0.12 -0.12 -0.17 -0.28 -0.53 0.18 0.15 -0.03
+        -0.0 -0.0 -0.0 0.0 0.03 -0.02 -0.02 -0.03 -0.02 0.01 -0.52 -0.17 -0.09
+        -0.0 -0.01 -0.01 0.01 0.11 -0.06 -0.06 -0.09 -0.05 0.02 -0.28 -0.59 -0.31
+        -0.0 -0.0 -0.0 -0.0 -0.0 -0.0 -1.0 -0.0 -0.0 -0.0 -0.0 -0.0 0.0
+        0.0 0.01 0.02 -0.01 -0.22 0.37 0.37 -0.45 -0.41 -0.32 -0.24 -0.25 -0.36
+        0.0 0.01 0.02 -0.01 -0.21 0.12 0.12 0.17 -0.72 -0.47 -0.18 -0.15 0.03
+        0.0 0.01 0.01 -0.01 -0.14 0.08 0.08 0.12 0.07 -0.03 -0.2 -0.24 -0.6
+        0.0 0.01 0.02 -0.01 -0.21 0.12 0.12 0.17 0.28 -0.47 -0.18 -0.15 0.03
+        -0.0 -0.0 -0.0 0.0 0.03 -0.02 -0.02 -0.03 -0.02 0.01 0.48 -0.17 -0.09
+        -0.0 -0.01 -0.01 0.01 0.14 -0.08 -0.08 -0.12 -0.07 0.03 0.2 0.24 -0.4
+    ]
+end
+
+@testset "_line_outage_factors" begin
+    instance = UnitCommitment.read_benchmark("test/case14")
+    isf_before = UnitCommitment._injection_shift_factors(
+        lines = instance.lines,
+        buses = instance.buses,
+    )
+    lodf = UnitCommitment._line_outage_factors(
+        lines = instance.lines,
+        buses = instance.buses,
+        isf = isf_before,
+    )
+    for contingency in instance.contingencies
+        for lc in contingency.lines
+            prev_susceptance = lc.susceptance
+            lc.susceptance = 0.0
+            isf_after = UnitCommitment._injection_shift_factors(
+                lines = instance.lines,
+                buses = instance.buses,
+            )
+            lc.susceptance = prev_susceptance
+            for lm in instance.lines
+                expected = isf_after[lm.offset, :]
+                actual =
+                    isf_before[lm.offset, :] +
+                    lodf[lm.offset, lc.offset] * isf_before[lc.offset, :]
+                @test norm(expected - actual) < 1e-6
+            end
+        end
+    end
+end

test/transform/initcond_test.jl

@@ -4,9 +4,12 @@
 
 using UnitCommitment, Cbc, JuMP
 
-@testset "Initial conditions" begin
+basedir = @__DIR__
+
+@testset "generate_initial_conditions!" begin
     # Load instance
-    instance = UnitCommitment.read("$(pwd())/fixtures/case118-initcond.json.gz")
+    instance =
+        UnitCommitment.read("$basedir/../fixtures/case118-initcond.json.gz")
     optimizer = optimizer_with_attributes(Cbc.Optimizer, "logLevel" => 0)
 
     # All units should have unknown initial conditions

test/transform/randomize/XavQiuAhm2021_test.jl

@@ -0,0 +1,63 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+import Random
+import UnitCommitment: XavQiuAhm2021
+
+using Distributions
+using UnitCommitment, Cbc, JuMP
+
+get_instance() = UnitCommitment.read_benchmark("matpower/case118/2017-02-01")
+system_load(instance) = sum(b.load for b in instance.buses)
+test_approx(x, y) = @test isapprox(x, y, atol = 1e-3)
+
+@testset "XavQiuAhm2021" begin
+    @testset "cost and load share" begin
+        instance = get_instance()
+
+        # Check original costs
+        unit = instance.units[10]
+        test_approx(unit.min_power_cost[1], 825.023)
+        test_approx(unit.cost_segments[1].cost[1], 36.659)
+        test_approx(unit.startup_categories[1].cost[1], 7570.42)
+
+        # Check original load share
+        bus = instance.buses[1]
+        prev_system_load = system_load(instance)
+        test_approx(bus.load[1] / prev_system_load[1], 0.012)
+
+        Random.seed!(42)
+        randomize!(
+            instance,
+            XavQiuAhm2021.Randomization(randomize_load_profile = false),
+        )
+
+        # Check randomized costs
+        test_approx(unit.min_power_cost[1], 831.977)
+        test_approx(unit.cost_segments[1].cost[1], 36.968)
+        test_approx(unit.startup_categories[1].cost[1], 7634.226)
+
+        # Check randomized load share
+        curr_system_load = system_load(instance)
+        test_approx(bus.load[1] / curr_system_load[1], 0.013)
+
+        # System load should not change
+        @test prev_system_load ≈ curr_system_load
+    end
+
+    @testset "load profile" begin
+        instance = get_instance()
+
+        # Check original load profile
+        @test round.(system_load(instance), digits = 1)[1:8] ≈
+              [3059.5, 2983.2, 2937.5, 2953.9, 3073.1, 3356.4, 4068.5, 4018.8]
+
+        Random.seed!(42)
+        randomize!(instance, XavQiuAhm2021.Randomization())
+
+        # Check randomized load profile
+        @test round.(system_load(instance), digits = 1)[1:8] ≈
+              [4854.7, 4849.2, 4732.7, 4848.2, 4948.4, 5231.1, 5874.8, 5934.8]
+    end
+end

test/transform/slice_test.jl

@@ -0,0 +1,46 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+using UnitCommitment, LinearAlgebra, Cbc, JuMP, JSON, GZip
+
+@testset "slice" begin
+    instance = UnitCommitment.read_benchmark("test/case14")
+    modified = UnitCommitment.slice(instance, 1:2)
+
+    # Should update all time-dependent fields
+    @test modified.time == 2
+    @test length(modified.power_balance_penalty) == 2
+    @test length(modified.reserves.spinning) == 2
+    for u in modified.units
+        @test length(u.max_power) == 2
+        @test length(u.min_power) == 2
+        @test length(u.must_run) == 2
+        @test length(u.min_power_cost) == 2
+        @test length(u.provides_spinning_reserves) == 2
+        for s in u.cost_segments
+            @test length(s.mw) == 2
+            @test length(s.cost) == 2
+        end
+    end
+    for b in modified.buses
+        @test length(b.load) == 2
+    end
+    for l in modified.lines
+        @test length(l.normal_flow_limit) == 2
+        @test length(l.emergency_flow_limit) == 2
+        @test length(l.flow_limit_penalty) == 2
+    end
+    for ps in modified.price_sensitive_loads
+        @test length(ps.demand) == 2
+        @test length(ps.revenue) == 2
+    end
+
+    # Should be able to build model without errors
+    optimizer = optimizer_with_attributes(Cbc.Optimizer, "logLevel" => 0)
+    model = UnitCommitment.build_model(
+        instance = modified,
+        optimizer = optimizer,
+        variable_names = true,
+    )
+end

test/usage.jl

@@ -0,0 +1,37 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+using UnitCommitment, LinearAlgebra, Cbc, JuMP, JSON
+
+@testset "build_model" begin
+    instance = UnitCommitment.read_benchmark("test/case14")
+    for line in instance.lines, t in 1:4
+        line.normal_flow_limit[t] = 10.0
+    end
+    optimizer = optimizer_with_attributes(Cbc.Optimizer, "logLevel" => 0)
+    model = UnitCommitment.build_model(
+        instance = instance,
+        optimizer = optimizer,
+        variable_names = true,
+    )
+    @test name(model[:is_on]["g1", 1]) == "is_on[g1,1]"
+
+    # Optimize and retrieve solution
+    UnitCommitment.optimize!(model)
+    solution = UnitCommitment.solution(model)
+
+    # Write solution to a file
+    filename = tempname()
+    UnitCommitment.write(filename, solution)
+    loaded = JSON.parsefile(filename)
+    @test length(loaded["Is on"]) == 6
+
+    # Verify solution
+    @test UnitCommitment.validate(instance, solution)
+
+    # Reoptimize with fixed solution
+    UnitCommitment.fix!(model, solution)
+    UnitCommitment.optimize!(model)
+    @test UnitCommitment.validate(instance, solution)
+end

test/validate_test.jl

@@ -1,43 +0,0 @@
-# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
-# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
-# Released under the modified BSD license. See COPYING.md for more details.
-
-using UnitCommitment, JSON, GZip, DataStructures
-
-function parse_case14()
-    return JSON.parse(
-        GZip.gzopen("../instances/test/case14.json.gz"),
-        dicttype = () -> DefaultOrderedDict(nothing),
-    )
-end
-
-@testset "Validation" begin
-    @testset "repair!" begin
-        @testset "Cost curve should be convex" begin
-            json = parse_case14()
-            json["Generators"]["g1"]["Production cost curve (MW)"] =
-                [100, 150, 200]
-            json["Generators"]["g1"]["Production cost curve (\$)"] =
-                [10, 25, 30]
-            instance = UnitCommitment._from_json(json, repair = false)
-            @test UnitCommitment.repair!(instance) == 4
-        end
-
-        @testset "Startup limit must be greater than Pmin" begin
-            json = parse_case14()
-            json["Generators"]["g1"]["Production cost curve (MW)"] = [100, 150]
-            json["Generators"]["g1"]["Production cost curve (\$)"] = [100, 150]
-            json["Generators"]["g1"]["Startup limit (MW)"] = 80
-            instance = UnitCommitment._from_json(json, repair = false)
-            @test UnitCommitment.repair!(instance) == 1
-        end
-
-        @testset "Startup costs and delays must be increasing" begin
-            json = parse_case14()
-            json["Generators"]["g1"]["Startup costs (\$)"] = [300, 200, 100]
-            json["Generators"]["g1"]["Startup delays (h)"] = [8, 4, 2]
-            instance = UnitCommitment._from_json(json, repair = false)
-            @test UnitCommitment.repair!(instance) == 4
-        end
-    end
-end

test/validation/repair_test.jl

@@ -0,0 +1,41 @@
+# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment
+# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved.
+# Released under the modified BSD license. See COPYING.md for more details.
+
+using UnitCommitment, JSON, GZip, DataStructures
+
+basedir = @__DIR__
+
+function parse_case14()
+    return JSON.parse(
+        GZip.gzopen("$basedir/../../instances/test/case14.json.gz"),
+        dicttype = () -> DefaultOrderedDict(nothing),
+    )
+end
+
+@testset "repair!" begin
+    @testset "Cost curve should be convex" begin
+        json = parse_case14()
+        json["Generators"]["g1"]["Production cost curve (MW)"] = [100, 150, 200]
+        json["Generators"]["g1"]["Production cost curve (\$)"] = [10, 25, 30]
+        instance = UnitCommitment._from_json(json, repair = false)
+        @test UnitCommitment.repair!(instance) == 4
+    end
+
+    @testset "Startup limit must be greater than Pmin" begin
+        json = parse_case14()
+        json["Generators"]["g1"]["Production cost curve (MW)"] = [100, 150]
+        json["Generators"]["g1"]["Production cost curve (\$)"] = [100, 150]
+        json["Generators"]["g1"]["Startup limit (MW)"] = 80
+        instance = UnitCommitment._from_json(json, repair = false)
+        @test UnitCommitment.repair!(instance) == 1
+    end
+
+    @testset "Startup costs and delays must be increasing" begin
+        json = parse_case14()
+        json["Generators"]["g1"]["Startup costs (\$)"] = [300, 200, 100]
+        json["Generators"]["g1"]["Startup delays (h)"] = [8, 4, 2]
+        instance = UnitCommitment._from_json(json, repair = false)
+        @test UnitCommitment.repair!(instance) == 4
+    end
+end