Ran JuliaFormatter

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

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,11 +5,11 @@
 JULIA := julia --color=yes --project=@.
 VERSION := 0.2
 
-build/sysimage.so: src/sysimage.jl Project.toml Manifest.toml
+build/sysimage.so: src/utils/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
+	cd benchmark; $(JULIA) --trace-compile=../build/precompile.jl benchmark.jl test/case14
+	$(JULIA) src/utils/sysimage.jl
 
 clean:
 	rm -rf build/*
@@ -24,7 +24,7 @@ test: build/sysimage.so
 
 
 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"
@@ -19,6 +20,7 @@ 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"
@@ -29,6 +31,7 @@ julia = "1"
 [extras]
 Cbc = "9961bab8-2fa3-5c5a-9d89-47fab24efd76"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+Gurobi = "2e9cd046-0924-5485-92f1-d5272153d98b"
 
 [targets]
-test = ["Cbc", "Test"]
+test = ["Cbc", "Test", "Gurobi"]

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.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"]
@@ -324,6 +268,7 @@ function _from_json(json; repair = true)
     instance = UnitCommitmentInstance(
         T,
         power_balance_penalty,
+        shortfall_penalty,
         units,
         buses,
         lines,
@@ -336,54 +281,3 @@ function _from_json(json; repair = true)
     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,100 @@
+# 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
+
+mutable struct UnitCommitmentInstance
+    time::Int
+    power_balance_penalty::Vector{Float64}
+    "Penalty for failing to meet reserve requirement."
+    shortfall_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
+
+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,66 @@
+# 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.
+- `formulation`:
+    the details of which constraints, variables, etc. to use
+- `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,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.
+
+"""
+    _add_ramp_eqs!(model, unit, formulation_prod_vars, formulation_ramping, formulation_status_vars)::Nothing
+
+Ensure constraints on ramping are met.
+Based on Arroyo and Conejo (2000).
+Eqns. (24), (25) in Knueven et al. (2020).
+
+Adds constraints identified by `ArrCon200.Ramping` to `model` using variables `Gar1962.ProdVars` and `is_on` from `Gar1962.StatusVars`.
+"""
+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)
+
+    # Gar1962.ProdVars
+    prod_above = model[:prod_above]
+
+    # Gar1962.StatusVars
+    is_on = model[:is_on]
+    switch_off = model[:switch_off]
+    switch_on = model[:switch_on]
+
+    is_initially_on = _is_initially_on(g) > 0
+
+    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 Knueven 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 Knueven 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,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:
+
+    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
+
+"""
+Constraints
+---
+* `eq_ramp_up`: Equation (24) in Knueven et al. (2020)
+* `eq_ramp_down`: Equation (25) in Knueven et al. (2020)
+"""
+struct Ramping <: RampingFormulation end
+
+end

src/model/formulations/CarArr2006/pwlcosts.jl

@@ -0,0 +1,60 @@
+# 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.
+
+"""
+    _add_production_piecewise_linear_eqs!
+
+Ensure respect of production limits along each segment.
+Creates constraints `CarArr2006.PwlCosts` using variables `Gar1962.StatusVars`
+"""
+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 Knueven 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 Knueven 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 Knueven 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,29 @@
+# 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
+
+"""
+Based on Garver (1962) and Carrión and Arryo (2006),
+which replaces (42) in Knueven et al. (2020) with a weaker version missing the on/off variable.
+Equations (45), (43), (44) in Knueven et al. (2020).
+
+Constraints
+---
+* `eq_prod_above_def`: Equation (43) in Knueven et al. (2020)
+* `eq_segprod_limit`: Equation (45) in Knueven et al. (2020)
+"""
+struct PwlCosts <: PiecewiseLinearCostsFormulation end
+
+end

src/model/formulations/DamKucRajAta2016/ramp.jl

@@ -0,0 +1,144 @@
+# 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.
+
+"""
+    _add_ramp_eqs!
+
+Ensure constraints on ramping are met.
+Based on Damcı-Kurt et al. (2016).
+Eqns. (35), (36) in Knueven et al. (2020).
+
+Variables
+---
+* :prod_above
+* :reserve
+* :is_on
+* :switch_on
+* :switch_off],
+
+Constraints
+---
+* :eq_str_ramp_up
+* :eq_str_ramp_down
+"""
+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
+    is_initially_on = _is_initially_on(g)
+
+    # The following are the same for generator g across all time periods
+    SU = g.startup_limit   # startup rate
+    SD = g.shutdown_limit  # shutdown rate
+    RU = g.ramp_up_limit   # ramp up rate
+    RD = g.ramp_down_limit # ramp down rate
+
+    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 Knueven 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 Knueven 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 is_initially_on
+            on_last_period = 1.0
+        end
+
+        if t > 1 && time_invariant
+            # Equation (36) in Knueven 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 Knueven 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,72 @@
+# 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.
+
+"""
+    _add_production_vars!(model, unit, formulation_prod_vars)
+
+Adds symbols identified by `Gar1962.ProdVars` to `model`.
+"""
+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
+
+"""
+    _add_production_limit_eqs!(model, unit, formulation_prod_vars)
+
+Ensure production limit constraints are met.
+Based on Garver (1962) and Morales-España et al. (2013).
+Eqns. (18), part of (69) in Knueven et al. (2020).
+
+===
+Variables
+* :is_on
+* :prod_above
+* :reserve
+
+===
+Constraints
+* :eq_prod_limit
+"""
+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 Knueven 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 Knueven 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 Knueven 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,81 @@
+# 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.
+
+"""
+    _add_production_piecewise_linear_eqs!
+
+Ensure respect of production limits along each segment.
+Based on Garver (1962).
+Equations (42), (43), (44) in Knueven 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*.
+
+Added to `model`: `:eq_prod_above_def` and `:eq_segprod_limit`.
+
+===
+Variables
+* :segprod
+* :is_on
+* :prod_above
+
+===
+Constraints
+* :eq_prod_above_def
+* :eq_segprod_limit
+"""
+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 Knueven 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 Knueven 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 Knueven 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,160 @@
+# 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.
+
+"""
+    _add_status_vars!
+
+Adds symbols identified by `Gar1962.StatusVars` to `model`.
+Fix variables if a certain generator _must_ run or based on initial conditions.
+"""
+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)
+    FIX_VARS = !formulation_status_vars.fix_vars_via_constraint
+    is_initially_on = _is_initially_on(g) > 0
+    for t in 1:model[:instance].time
+        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)
+
+        # Use initial conditions and whether a unit must run to fix variables
+        if FIX_VARS
+            # Fix variables using fix function
+            if g.must_run[t]
+                # If the generator _must_ run, then it is obviously on and cannot be switched off
+                # In the first time period, force unit to switch on if was off before
+                # Otherwise, unit is on, and will never turn off, so will never need to turn on
+                fix(is_on[g.name, t], 1.0; force = true)
+                fix(
+                    switch_on[g.name, t],
+                    (t == 1 ? 1.0 - _is_initially_on(g) : 0.0);
+                    force = true,
+                )
+                fix(switch_off[g.name, t], 0.0; force = true)
+            elseif t == 1
+                if is_initially_on
+                    # Generator was on (for g.initial_status time periods),
+                    # so cannot be more switched on until the period after the first time it can be turned off
+                    fix(switch_on[g.name, 1], 0.0; force = true)
+                else
+                    # Generator is initially off (for -g.initial_status time periods)
+                    # Cannot be switched off more
+                    fix(switch_off[g.name, 1], 0.0; force = true)
+                end
+            end
+        else
+            # Add explicit constraint if !FIX_VARS
+            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
+            elseif t == 1
+                if is_initially_on
+                    switch_on[g.name, t] = 0.0
+                else
+                    switch_off[g.name, t] = 0.0
+                end
+            end
+        end
+
+        # Use initial conditions and whether a unit must run to fix variables
+        if FIX_VARS
+            # Fix variables using fix function
+            if g.must_run[t]
+                # If the generator _must_ run, then it is obviously on and cannot be switched off
+                # In the first time period, force unit to switch on if was off before
+                # Otherwise, unit is on, and will never turn off, so will never need to turn on
+                fix(is_on[g.name, t], 1.0; force = true)
+                fix(
+                    switch_on[g.name, t],
+                    (t == 1 ? 1.0 - _is_initially_on(g) : 0.0);
+                    force = true,
+                )
+                fix(switch_off[g.name, t], 0.0; force = true)
+            elseif t == 1
+                if is_initially_on
+                    # Generator was on (for g.initial_status time periods),
+                    # so cannot be more switched on until the period after the first time it can be turned off
+                    fix(switch_on[g.name, 1], 0.0; force = true)
+                else
+                    # Generator is initially off (for -g.initial_status time periods)
+                    # Cannot be switched off more
+                    fix(switch_off[g.name, 1], 0.0; force = true)
+                end
+            end
+        else
+            # Add explicit constraint if !FIX_VARS
+            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
+            elseif t == 1
+                if is_initially_on
+                    switch_on[g.name, t] = 0.0
+                else
+                    switch_off[g.name, t] = 0.0
+                end
+            end
+        end
+    end
+    return
+end
+
+"""
+    _add_status_eqs!
+
+Creates constraints `eq_binary_link` and `eq_switch_on_off` using variables in `Gar1962.StatusVars`.
+
+Constraints
+---
+* `eq_binary_link`
+* `eq_switch_on_off`
+"""
+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]
+            continue
+        end
+
+        # Link binary variables
+        # Equation (2) in Knueven et al. (2020), originally from Garver (1962)
+        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
+        # amk: I am not sure this is in Knueven et al. (2020)
+        eq_switch_on_off[g.name, t] = @constraint(
+            model,
+            switch_on[g.name, t] + switch_off[g.name, t] <= 1
+        )
+    end
+    return
+end

src/model/formulations/Gar1962/structs.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.
+
+"""
+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
+
+"""
+Variables
+---
+* `prod_above`:
+        [gen, t];
+        *production above minimum required level*;
+        lb: 0, ub: Inf.
+        KnuOstWat2020: `p'_g(t)`
+* `segprod`:
+        [gen, segment, t];
+        *how much generator produces on cost segment in time t*;
+        lb: 0, ub: Inf.
+        KnuOstWat2020: `p_g^l(t)`
+"""
+struct ProdVars <: ProductionVarsFormulation end
+
+struct PwlCosts <: PiecewiseLinearCostsFormulation end
+
+"""
+Variables
+---
+* `is_on`:
+        [gen, t];
+        *is generator on at time t?*
+        lb: 0, ub: 1, binary.
+        KnuOstWat2020: `u_g(t)`
+* `switch_on`:
+        [gen, t];
+        *indicator that generator will be turned on at t*;
+        lb: 0, ub: 1, binary.
+        KnuOstWat2020: `v_g(t)`
+* `switch_off`: binary;
+        [gen, t];
+        *indicator that generator will be turned off at t*;
+        lb: 0, ub: 1, binary.
+        KnuOstWat2020: `w_g(t)`
+
+Arguments
+---
+* `fix_vars_via_constraint`:
+        indicator for whether to set vars to a constant using `fix` or by adding an explicit constraint
+        (particulary useful for debugging purposes).
+"""
+struct StatusVars <: StatusVarsFormulation
+    fix_vars_via_constraint::Bool
+
+    StatusVars() = new(false)
+end
+
+end

src/model/formulations/GenMorRam2017/startstop.jl

@@ -0,0 +1,100 @@
+# 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.
+
+"""
+    _add_startup_shutdown_limit_eqs!(model::JuMP.Model, g::Unit)::Nothing
+
+Startup and shutdown limits from Gentile et al. (2017).
+Eqns. (20), (23a), and (23b) in Knueven et al. (2020).
+
+Creates constraints `eq_startstop_limit`,  `eq_startup_limit`, and `eq_shutdown_limit`
+using variables `Gar1962.StatusVars`, `prod_above` from `Gar1962.ProdVars`, and `reserve`.
+
+Constraints
+---
+* `eq_startstop_limit`
+* `eq_startup_limit`
+* `eq_shutdown_limit`
+"""
+function _add_startup_shutdown_limit_eqs!(
+    model::JuMP.Model,
+    g::Unit,
+    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
+
+    eq_startstop_limit = _init(model, :eq_startstop_limit)
+    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
+    gi = g.name
+
+    if g.initial_power > g.shutdown_limit
+        #eqs.shutdown_limit[gi, 0] = @constraint(mip, vars.switch_off[gi, 1] <= 0)
+        if formulation_status_vars.always_create_vars
+            fix(switch_off[gi, 1], 0.0; force = true)
+            @constraint(mip, vars.switch_off[gi, 1] <= 0)
+        else
+            switch_off[gi, 1] = 0.0
+        end
+    end
+
+    for t in 1:T
+        ## 2020-10-09 amk: added eqn (20) and check of g.min_uptime
+        # Not present in (23) in Kneueven et al.
+        if g.min_uptime > 1
+            # Equation (20) in Knueven et al. (2020)
+            eqs.startstop_limit[gi, t] = @constraint(
+                model,
+                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] - (
+                    t < T ?
+                    max(0, g.max_power[t] - g.shutdown_limit) *
+                    switch_off[gi, t+1] : 0.0
+                )
+            )
+        else
+            ## Startup limits
+            # Equation (23a) in Knueven et al. (2020)
+            eqs.startup_limit[gi, t] = @constraint(
+                model,
+                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] - (
+                    t < T ?
+                    max(0, g.startup_limit - g.shutdown_limit) *
+                    switch_off[gi, t+1] : 0.0
+                )
+            )
+
+            ## Shutdown limits
+            if t < T
+                # Equation (23b) in Knueven et al. (2020)
+                eqs.shutdown_limit[gi, t] = @constraint(
+                    model,
+                    prod_above[gi, t] + reserve[gi, t] <=
+                    (g.max_power[t] - g.min_power[t]) * xis_on[gi, t] - (
+                        t < T ?
+                        max(0, g.max_power[t] - g.shutdown_limit) *
+                        switch_off[gi, t+1] : 0.0
+                    ) -
+                    max(0, g.shutdown_limit - g.startup_limit) *
+                    switch_on[gi, t]
+                )
+            end
+        end
+    end
+end

src/model/formulations/KnuOstWat2018/pwlcosts.jl

@@ -0,0 +1,132 @@
+# 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.
+
+"""
+    _add_production_piecewise_linear_eqs!
+
+Ensure respect of production limits along each segment.
+Based on Knueven et al. (2018b).
+Eqns. (43), (44), (46), (48) in Knueven 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*.
+
+===
+Variables
+* :segprod
+* :is_on
+* :switch_on
+* :switch_off
+* :prod_above
+
+===
+Constraints
+* :eq_prod_above_def
+* :eq_segprod_limit_a
+* :eq_segprod_limit_b
+* :eq_segprod_limit_c
+"""
+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 Knueven 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 Knueven 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 Knueven 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 Knueven 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 Knueven 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/scosts.jl

@@ -0,0 +1,123 @@
+# 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.
+
+"""
+    _add_startup_cost_eqs!
+
+Extended formulation of startup costs using indicator variables
+based on Knueven, Ostrowski, and Watson, 2020
+--- equations (59), (60), (61).
+
+Variables
+---
+* switch_on
+* switch_off
+* downtime_arc
+
+Constraints
+---
+* eq_startup_at_t
+* eq_shutdown_at_t
+"""
+function _add_startup_cost_eqs!(
+    model::JuMP.Model,
+    g::Unit,
+    formulation::MorLatRam2013.StartupCosts,
+)::Nothing
+    S = length(g.startup_categories)
+    if S == 0
+        return
+    end
+    gn = g.name
+
+    _init(model, eq_startup_at_t)
+    _init(model, eq_shutdown_at_t)
+
+    switch_on = model[:switch_on]
+    switch_off = model[:switch_off]
+    downtime_arc = model[:downtime_arc]
+
+    DT = g.min_downtime # minimum time offline
+    TC = g.startup_categories[S].delay # time offline until totally cold
+
+    # If initial_status < 0, then this is the amount of time the generator has been off
+    initial_time_shutdown = (g.initial_status < 0 ? -g.initial_status : 0)
+
+    for t in 1:model[:instance].time
+        # Fix to zero values of downtime_arc outside the feasible time pairs
+        # Specifically, x(t,t') = 0 if t' does not belong to 𝒢 = [t+DT, t+TC-1]
+        # This is because DT is the minimum downtime, so there is no way x(t,t')=1 for t'<t+DT
+        # and TC is the "time until cold" => if the generator starts afterwards, always has max cost
+        #start_time = min(t + DT, T)
+        #end_time = min(t + TC - 1, T)
+        #for tmp_t in t+1:start_time
+        #  fix(vars.downtime_arc[gn, t, tmp_t], 0.; force = true)
+        #end
+        #for tmp_t in end_time+1:T
+        #  fix(vars.downtime_arc[gn, t, tmp_t], 0.; force = true)
+        #end
+
+        # Equation (59) in Knueven et al. (2020)
+        # Relate downtime_arc with switch_on
+        # "switch_on[g,t] >= x_g(t',t) for all t' \in [t-TC+1, t-DT]"
+        eq_startup_at_t[gn, t] = @constraint(
+            model,
+            switch_on[gn, t] >= sum(
+                downtime_arc[gn, tmp_t, t] for
+                tmp_t in t-TC+1:t-DT if tmp_t >= 1
+            )
+        )
+
+        # Equation (60) in Knueven et al. (2020)
+        # "switch_off[g,t] >= x_g(t,t') for all t' \in [t+DT, t+TC-1]"
+        eqs.shutdown_at_t[gn, t] = @constraint(
+            model,
+            switch_off[gn, t] >= sum(
+                downtime_arc[gn, t, tmp_t] for
+                tmp_t in t+DT:t+TC-1 if tmp_t <= T
+            )
+        )
+
+        # Objective function terms for start-up costs
+        # Equation (61) in Knueven et al. (2020)
+        default_category = S
+        if initial_time_shutdown > 0 && t + initial_time_shutdown - 1 < TC
+            for s in 1:S-1
+                # If off for x periods before, then belongs to category s
+                # if -x+1 in [t-delay[s+1]+1,t-delay[s]]
+                # or, equivalently, if total time off in [delay[s], delay[s+1]-1]
+                # where total time off = t - 1 + initial_time_shutdown
+                # (the -1 because not off for current time period)
+                if t + initial_time_shutdown - 1 <
+                   g.startup_categories[s+1].delay
+                    default_category = s
+                    break # does not go into next category
+                end
+            end
+        end
+        add_to_expression!(
+            model[:obj],
+            switch_on[gn, t],
+            g.startup_categories[default_category].cost,
+        )
+
+        for s in 1:S-1
+            # Objective function terms for start-up costs
+            # Equation (61) in Knueven et al. (2020)
+            # Says to replace the cost of last category with cost of category s
+            start_range = max((t - g.startup_categories[s+1].delay + 1), 1)
+            end_range = min((t - g.startup_categories[s].delay), T - 1)
+            for tmp_t in start_range:end_range
+                if (t < tmp_t + DT) || (t >= tmp_t + TC) # the second clause should never be true for s < S
+                    continue
+                end
+                add_to_expression!(
+                    model[:obj],
+                    downtime_arc[gn, tmp_t, t],
+                    g.startup_categories[s].cost - g.startup_categories[S].cost,
+                )
+            end
+        end # iterate over startup categories
+    end # iterate over time
+end # add_startup_costs_KneOstWat20

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,151 @@
+# 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.
+
+"""
+    _add_ramp_eqs!
+
+Ensure constraints on ramping are met.
+Needs to be used in combination with shutdown rate constraints, e.g., (21b) in Knueven et al. (2020).
+Based on Morales-España, Latorre, and Ramos, 2013.
+Eqns. (26)+(27) [replaced by (24)+(25) if time-varying min demand] in Knueven et al. (2020).
+
+Variables
+---
+* :is_on
+* :switch_off
+* :switch_on
+* :prod_above
+* :reserve
+
+Constraints
+---
+* :eq_ramp_up
+* :eq_ramp_down
+"""
+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   # startup rate
+    SD = g.shutdown_limit  # shutdown rate
+    RU = g.ramp_up_limit   # ramp up rate
+    RD = g.ramp_down_limit # ramp down rate
+    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 Knueven 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 Knueven 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,88 @@
+# 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.
+
+"""
+    _add_startup_cost_eqs!
+
+Extended formulation of startup costs using indicator variables
+based on Muckstadt and Wilson, 1968;
+this version by Morales-España, Latorre, and Ramos, 2013.
+Eqns. (54), (55), and (56) in Knueven et al. (2020).
+Note that the last 'constraint' is actually setting the objective.
+
+\tstartup[gi,s,t] ≤ sum_{i=s.delay}^{(s+1).delay-1} switch_off[gi,t-i]
+\tswitch_on[gi,t] = sum_{s=1}^{length(startup_categories)} startup[gi,s,t]
+\tstartup_cost[gi,t] = sum_{s=1}^{length(startup_categories)} cost_segments[s].cost * startup[gi,s,t]
+
+Variables
+---
+* startup
+* switch_on
+* switch_off
+
+Constraints
+---
+* eq_startup_choose
+* eq_startup_restrict
+"""
+function _add_startup_cost_eqs!(
+    model::JuMP.Model,
+    g::Unit,
+    formulation::MorLatRam2013.StartupCosts,
+)::Nothing
+    S = length(g.startup_categories)
+    if S == 0
+        return
+    end
+
+    # Constraints created
+    eq_startup_choose = _init(model, :eq_startup_choose)
+    eq_startup_restrict = _init(model, :eq_startup_restrict)
+
+    # Variables needed
+    startup = model[:startup]
+    switch_on = model[:switch_on]
+    switch_off = model[:switch_off]
+
+    gn = g.name
+    for t in 1:model[:instance].time
+        # If unit is switching on, we must choose a startup category
+        # Equation (55) in Knueven et al. (2020)
+        eq_startup_choose[gn, t] = @constraint(
+            model,
+            switch_on[gn, t] == sum(startup[gn, 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)
+                # If initial_status < 0, then this is the amount of time the generator has been off
+                initial_sum = (
+                    g.initial_status < 0 && (g.initial_status + 1 in range) ? 1.0 : 0.0
+                )
+                # Change of index version of equation (54) in Knueven et al. (2020):
+                #   startup[gi,s,t] ≤ sum_{i=s.delay}^{(s+1).delay-1} switch_off[gi,t-i]
+                eq_startup_restrict[gn, t, s] = @constraint(
+                    model,
+                    startup[gn, t, s] <=
+                    initial_sum +
+                    sum(switch_off[gn, i] for i in range if i >= 1)
+                )
+            end # if s < S (not the last category)
+
+            # Objective function terms for start-up costs
+            # Equation (56) in Knueven et al. (2020)
+            add_to_expression!(
+                model[:obj],
+                startup[gn, t, s],
+                g.startup_categories[s].cost,
+            )
+        end # iterate over startup categories
+    end # iterate over time
+    return
+end

src/model/formulations/MorLatRam2013/startstop.jl

@@ -0,0 +1,89 @@
+# 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.
+
+"""
+    _add_startup_shutdown_limit_eqs!(model::JuMP.Model, g::Unit)::Nothing
+
+Startup and shutdown limits from Morales-España et al. (2013a).
+Eqns. (20), (21a), and (21b) in Knueven et al. (2020).
+
+Variables
+---
+* :is_on
+* :prod_above
+* :reserve
+* :switch_on
+* :switch_off
+
+Constraints
+---
+* :eq_startstop_limit
+* :eq_startup_limit
+* :eq_shutdown_limit
+"""
+function _add_startup_shutdown_limit_eqs!(model::JuMP.Model, g::Unit)::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
+
+    eq_startstop_limit = _init(model, :eq_startstop_limit)
+    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
+    gi = g.name
+    for t in 1:T
+        ## 2020-10-09 amk: added eqn (20) and check of g.min_uptime
+        if g.min_uptime > 1 && t < T
+            # Equation (20) in Knueven et al. (2020)
+            # UT > 1 required, to guarantee that vars.switch_on[gi, t] and vars.switch_off[gi, t+1] are not both = 1 at the same time
+            eq_startstop_limit[gi, t] = @constraint(
+                model,
+                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] -
+                max(0, g.max_power[t] - g.shutdown_limit) * switch_off[gi, t+1]
+            )
+        else
+            ## Startup limits
+            # Equation (21a) in Knueven et al. (2020)
+            # Proposed by Morales-España et al. (2013a)
+            eqs_startup_limit[gi, t] = @constraint(
+                model,
+                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 limits
+            if t < T
+                # Equation (21b) in Knueven et al. (2020)
+                # TODO different from what was in previous model, due to reserve variable
+                # ax: ideally should have reserve_up and reserve_down variables
+                #     i.e., the generator should be able to increase/decrease production as specified
+                #     (this is a heuristic for a "robust" solution,
+                #     in case there is an outage or a surge, and flow has to be redirected)
+                # amk: if shutdown_limit is the max prod of generator in time period before shutting down,
+                #      then it makes sense to count reserves, because otherwise, if reserves ≠ 0,
+                #      then the generator will actually produce more than the limit
+                eqs.shutdown_limit[gi, t] = @constraint(
+                    model,
+                    prod_above[gi, t] +
+                    (RESERVES_WHEN_SHUT_DOWN ? reserve[gi, t] : 0.0) <=
+                    (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
+        end # check if g.min_uptime > 1
+    end # loop over time
+end # _add_startup_shutdown_limit_eqs!

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/NowRom2000/scosts.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.
+
+"""
+    _add_startup_cost_eqs!
+
+Based on Nowak and Römisch, 2000.
+Introduces auxiliary startup cost variable, c_g^SU(t) for each time period,
+and uses startup status variable, u_g(t);
+there are exponentially many facets in this space,
+but there is a linear-time separation algorithm (Brandenburg et al., 2017).
+"""
+function _add_startup_cost_eqs!(
+    model::JuMP.Model,
+    g::Unit,
+    formulation::MorLatRam2013.StartupCosts,
+)::Nothing
+    return error("Not implemented.")
+end

src/model/formulations/OstAnjVan2012/ramp.jl

@@ -0,0 +1,85 @@
+# 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.
+
+"""
+    _add_ramp_eqs!
+
+Ensure constraints on ramping are met.
+Based on Ostrowski, Anjos, Vannelli (2012).
+Eqn (37) in Knueven et al. (2020).
+
+Variables
+---
+* :is_on
+* :prod_above
+* :reserve
+
+Constraints
+---
+* :eq_str_prod_limit
+"""
+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 = _is_initially_on(g)
+
+    gn = g.name
+    eq_str_prod_limit = _init(model, :eq_str_prod_limit)
+
+    # Variables that we need
+    reserve = model[:reserve]
+
+    # Gar1962.ProdVars
+    prod_above = model[:prod_above]
+
+    # Gar1962.StatusVars
+    is_on = model[:is_on]
+    switch_off = model[:switch_off]
+
+    # The following are the same for generator g across all time periods
+    UT = g.min_uptime
+
+    SU = g.startup_limit   # startup rate
+    SD = g.shutdown_limit  # shutdown rate
+    RU = g.ramp_up_limit   # ramp up rate
+    RD = g.ramp_down_limit # ramp down rate
+
+    # TODO check initial conditions, but maybe okay as long as (35) and (36) are also used
+    for t in 1:model[:instance].time
+        Pbar = g.max_power[t]
+
+        #TRD = floor((Pbar - SU)/RD)
+        # TODO check amk changed TRD wrt Knueven et al.
+        TRD = ceil((Pbar - SD) / RD) # ramp down time
+
+        if Pbar < 1e-7
+            # Skip this time period if max power = 0
+            continue
+        end
+
+        if UT >= 1
+            # Equation (37) in Knueven et al. (2020)
+            KSD = min(TRD, UT - 1, T - t - 1)
+            eq_str_prod_limit[gn, t] = @constraint(
+                model,
+                prod_above[gn, t] +
+                g.min_power[t] * is_on[gn, t] +
+                (RESERVES_WHEN_RAMP_DOWN ? reserve[gn, t] : 0.0) <=
+                Pbar * is_on[gi, t] - sum(
+                    (Pbar - (SD + i * RD)) * switch_off[gi, t+1+i] for
+                    i in 0:KSD
+                )
+            )
+        end # check UT >= 1
+    end # loop over time
+end

src/model/formulations/PanGua2016/ramp.jl

@@ -0,0 +1,129 @@
+# 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.
+
+"""
+    _add_ramp_eqs!
+
+Add tighter upper bounds on production based on ramp-down trajectory.
+Based on (28) in Pan and Guan (2016).
+But there is an extra time period covered using (40) of Knueven et al. (2020).
+Eqns. (38), (40), (41) in Knueven et al. (2020).
+
+Variables
+---
+* :prod_above
+* :reserve
+* :is_on
+* :switch_on
+* :switch_off
+
+Constraints
+---
+* :str_prod_limit
+* :prod_limit_ramp_up_extra_period
+* :prod_limit_shutdown_trajectory
+"""
+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 Knueven 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 Knueven 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 Knueven 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 Knueven 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,29 @@
+# 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.
+
+"""
+    _add_bus!(model::JuMP.Model, b::Bus)::Nothing
+
+Creates `expr_net_injection` and adds `curtail` variable to `model`.
+"""
+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,30 @@
+# 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.
+
+"""
+    _add_price_sensitive_load!(model::JuMP.Model, ps::PriceSensitiveLoad)
+"""
+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

@@ -18,7 +18,7 @@ function _injection_shift_factors(;
     lines::Array{TransmissionLine},
 )
     susceptance = _susceptance_matrix(lines)
-    incidence = _reduced_incidence_matrix(lines = lines, buses = buses)
+    incidence = _reduced_incidence_matrix(buses = buses, lines = lines)
     laplacian = transpose(incidence) * susceptance * incidence
     isf = susceptance * incidence * inv(Array(laplacian))
     return isf
@@ -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,87 @@
+# 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
+
+Every formulation has to specify components for setting production variables and limits,
+startup costs and piecewise-linear costs, ramping variables and constraints,
+status variables (on/off, starting up, shutting down), and transmission constraints.
+
+Some of these components are allowed to be empty, as long as overall validity of the formulation is maintained.
+"""
+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,95 @@
+# 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.
+
+"""
+    _add_system_wide_eqs!(model::JuMP.Model)::Nothing
+
+Adds constraints that apply to the whole system, such as relating to net injection and reserves.
+"""
+function _add_system_wide_eqs!(model::JuMP.Model)::Nothing
+    _add_net_injection_eqs!(model)
+    _add_reserve_eqs!(model)
+    return
+end
+
+"""
+    _add_net_injection_eqs!(model::JuMP.Model)::Nothing
+
+Adds `net_injection`, `eq_net_injection_def`, and `eq_power_balance` identifiers into `model`.
+
+Variables
+---
+* `expr_net_injection`
+* `net_injection`
+
+Constraints
+---
+* `eq_net_injection_def`
+* `eq_power_balance`
+"""
+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
+
+"""
+    _add_reserve_eqs!(model::JuMP.Model)::Nothing
+
+Ensure constraints on reserves are met.
+Based on Morales-España et al. (2013a).
+Eqn. (68) from Knueven et al. (2020).
+
+Adds `eq_min_reserve` identifier to `model`, and corresponding constraint.
+
+Variables
+---
+* `reserve`
+* `reserve_shortfall`
+
+Constraints
+---
+* `eq_min_reserve`
+"""
+function _add_reserve_eqs!(model::JuMP.Model)::Nothing
+    instance = model[:instance]
+    eq_min_reserve = _init(model, :eq_min_reserve)
+    instance = model[:instance]
+    for t in 1:instance.time
+        # Equation (68) in Knueven 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,329 @@
+# 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.
+
+"""
+    _add_unit!(model::JuMP.Model, g::Unit, formulation::Formulation)
+
+Add production, reserve, startup, shutdown, and status variables,
+and constraints for min uptime/downtime, net injection, production, ramping, startup, shutdown, and status.
+
+Fix variables if a certain generator _must_ run or if a generator provides spinning reserves.
+Also, add overflow penalty to objective for each transmission line.
+"""
+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_shutdown_cost_eqs!(model, g)
+    _add_startup_shutdown_limit_eqs!(
+        model,
+        g,
+        formulation.status_vars,
+        formulation.prod_vars,
+    )
+    _add_status_eqs!(model, g, formulation.status_vars)
+    return
+end
+
+_is_initially_on(g::Unit)::Float64 = (g.initial_status > 0 ? 1.0 : 0.0)
+
+"""
+    _add_reserve_vars!(model::JuMP.Model, g::Unit)::Nothing
+
+Add `:reserve` variable to `model`, fixed to zero if no spinning reserves specified.
+"""
+function _add_reserve_vars!(
+    model::JuMP.Model,
+    g::Unit,
+    ALWAYS_CREATE_VARS = false,
+)::Nothing
+    reserve = _init(model, :reserve)
+    reserve_shortfall = _init(model, :reserve_shortfall) # for accounting for shortfall penalty in the objective
+    for t in 1:model[:instance].time
+        if g.provides_spinning_reserves[t]
+            reserve[g.name, t] = @variable(model, lower_bound = 0)
+        else
+            if ALWAYS_CREATE_VARS
+                reserve[g.name, t] = @variable(model, lower_bound = 0)
+                fix(reserve[g.name, t], 0.0; force = true)
+            else
+                reserve[g.name, t] = 0.0
+            end
+        end
+        reserve_shortfall[t] =
+            (model[:instance].shortfall_penalty[t] >= 0) ?
+            @variable(model, lower_bound = 0) : 0.0
+    end
+    return
+end
+
+"""
+    _add_reserve_eqs!(model::JuMP.Model, g::Unit)::Nothing
+"""
+function _add_reserve_eqs!(model::JuMP.Model, g::Unit)::Nothing
+    # nothing to do here
+    return
+end
+
+"""
+    _add_startup_shutdown_vars!(model::JuMP.Model, g::Unit)::Nothing
+
+Add `startup` to model.
+"""
+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
+
+"""
+    _add_startup_shutdown_limit_eqs!(model::JuMP.Model, g::Unit)::Nothing
+
+Creates startup/shutdown limit constraints below based on variables `Gar1962.StatusVars`, `prod_above` from `Gar1962.ProdVars`, and `reserve`.
+
+Constraints
+---
+* :eq_startup_limit
+* :eq_shutdown_limit
+"""
+function _add_startup_shutdown_limit_eqs!(
+    model::JuMP.Model,
+    g::Unit,
+    formulation_status_vars::Gar1962.StatusVars,
+    formulation_prod_vars::Gar1962.ProdVars,
+)::Nothing
+    eq_shutdown_limit = _init(model, :eq_shutdown_limit)
+    eq_startup_limit = _init(model, :eq_startup_limit)
+
+    is_on = model[:is_on]
+    switch_off = model[:switch_off]
+    switch_on = model[:switch_on]
+    prod_above = model[:prod_above]
+    reserve = model[:reserve]
+
+    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
+            # TODO check what happens with these variables when exporting the model
+            # Generator producing too much to be turned off in the first time period
+            # (can a binary variable have bounds x = 0?)
+            if formulation_status_vars.fix_vars_via_constraint
+                eq_shutdown_limit[g.name, 0] =
+                    @constraint(model, model[:switch_off][g.name, 1] <= 0.0)
+            else
+                fix(model[:switch_off][g.name, 1], 0.0; force = true)
+            end
+        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
+
+"""
+    _add_shutdown_cost_eqs!(model::JuMP.Model, g::Unit)::Nothing
+
+Variables
+---
+* `switch_off`
+"""
+function _add_shutdown_cost_eqs!(model::JuMP.Model, g::Unit)::Nothing
+    T = model[:instance].time
+    gi = g.name
+    for t in 1:T
+        shutdown_cost = 0.0
+        if shutdown_cost > 1e-7
+            # Equation (62) in Knueven et al. (2020)
+            add_to_expression!(
+                model[:obj],
+                model[:switch_off][gi, t],
+                shutdown_cost,
+            )
+        end
+    end # loop over time
+end
+
+"""
+    _add_ramp_eqs!(model, unit, formulation)
+"""
+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
+
+"""
+    _add_min_uptime_downtime_eqs!(model::JuMP.Model, g::Unit)::Nothing
+
+Ensure constraints on up/down time are met.
+Based on Garver (1962), Malkin (2003), and Rajan and Takritti (2005).
+Eqns. (3), (4), (5) in Knueven et al. (2020).
+
+Variables
+---
+* `is_on`
+* `switch_off`
+* `switch_on`
+
+Constraints
+---
+* `eq_min_uptime`
+* `eq_min_downtime`
+"""
+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
+        # Equation (4) in Knueven et al. (2020)
+        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
+        # Equation (5) in Knueven et al. (2020)
+        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
+        # Equations (3a) and (3b) in Knueven et al. (2020)
+        # (using :switch_on and :switch_off instead of :is_on)
+        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
+
+"""
+    _add_net_injection_eqs!(model::JuMP.Model, g::Unit)::Nothing
+"""
+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/transform/randomize.jl

@@ -0,0 +1,53 @@
+# 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.
+
+using Distributions
+
+function randomize_unit_costs!(
+    instance::UnitCommitmentInstance;
+    distribution = Uniform(0.95, 1.05),
+)::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_distribution!(
+    instance::UnitCommitmentInstance;
+    distribution = Uniform(0.90, 1.10),
+)::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_peak_load!(
+    instance::UnitCommitmentInstance;
+    distribution = Uniform(0.925, 1.075),
+)::Nothing
+    α = rand(distribution)
+    for bus in instance.buses
+        bus.load *= α
+    end
+    return
+end
+
+export randomize_unit_costs!, randomize_load_distribution!, randomize_peak_load!

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

@@ -5,12 +5,20 @@
 using PackageCompiler
 
 using DataStructures
+using Distributions
 using JSON
 using JuMP
 using MathOptInterface
 using SparseArrays
 
-pkg = [:DataStructures, :JSON, :JuMP, :MathOptInterface, :SparseArrays]
+pkg = [
+    :DataStructures,
+    :Distributions,
+    :JSON,
+    :JuMP,
+    :MathOptInterface,
+    :SparseArrays,
+]
 
 @info "Building system image..."
 create_sysimage(

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/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,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.
+
+using UnitCommitment
+
+@testset "read_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

test/instance/read_test.jl

@@ -0,0 +1,115 @@
+# 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[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_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

@@ -7,12 +7,30 @@ using UnitCommitment
 
 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")
+        include("transform/randomize_test.jl")
+    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,7 +4,7 @@
 
 using UnitCommitment, Cbc, JuMP
 
-@testset "Initial conditions" begin
+@testset "generate_initial_conditions!" begin
     # Load instance
     instance = UnitCommitment.read("$(pwd())/fixtures/case118-initcond.json.gz")
     optimizer = optimizer_with_attributes(Cbc.Optimizer, "logLevel" => 0)

test/transform/randomize_test.jl

@@ -0,0 +1,43 @@
+# 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, Cbc, JuMP
+
+_get_instance() = UnitCommitment.read_benchmark("matpower/case118/2017-02-01")
+_total_load(instance) = sum(b.load[1] for b in instance.buses)
+
+@testset "randomize_unit_costs!" begin
+    instance = _get_instance()
+    unit = instance.units[10]
+    prev_min_power_cost = unit.min_power_cost
+    prev_prod_cost = unit.cost_segments[1].cost
+    prev_startup_cost = unit.startup_categories[1].cost
+    randomize_unit_costs!(instance)
+    @test prev_min_power_cost != unit.min_power_cost
+    @test prev_prod_cost != unit.cost_segments[1].cost
+    @test prev_startup_cost != unit.startup_categories[1].cost
+end
+
+@testset "randomize_load_distribution!" begin
+    instance = _get_instance()
+    bus = instance.buses[1]
+    prev_load = instance.buses[1].load[1]
+    prev_total_load = _total_load(instance)
+    randomize_load_distribution!(instance)
+    curr_total_load = _total_load(instance)
+    @test prev_load != instance.buses[1].load[1]
+    @test abs(prev_total_load - curr_total_load) < 1e-3
+end
+
+@testset "randomize_peak_load!" begin
+    instance = _get_instance()
+    bus = instance.buses[1]
+    prev_total_load = _total_load(instance)
+    prev_share = bus.load[1] / prev_total_load
+    randomize_peak_load!(instance)
+    curr_total_load = _total_load(instance)
+    curr_share = bus.load[1] / prev_total_load
+    @test curr_total_load != prev_total_load
+    @test abs(curr_share - prev_share) < 1e-3
+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,39 @@
+# 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 "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