diff --git a/Makefile b/Makefile index 6823fad..41f1275 100644 --- a/Makefile +++ b/Makefile @@ -8,8 +8,8 @@ clean: rm -rfv build Manifest.toml test/Manifest.toml deps/formatter/build deps/formatter/Manifest.toml docs: - cd docs; make clean; make dirhtml - rsync -avP --delete-after docs/_build/dirhtml/ ../docs/$(VERSION)/ + cd docs; julia --project=. make.jl; cd .. + rsync -avP --delete-after docs/build/ ../docs/$(VERSION)/ format: cd deps/formatter; ../../juliaw format.jl diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index c987782..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,14 +0,0 @@ -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = . -BUILDDIR = _build - -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 0000000..aa949e8 --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,3 @@ +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +UnitCommitment = "64606440-39ea-11e9-0f29-3303a1d3d877" diff --git a/docs/_static/custom.css b/docs/_static/custom.css deleted file mode 100644 index dc39c46..0000000 --- a/docs/_static/custom.css +++ /dev/null @@ -1,49 +0,0 @@ -h1.site-logo { - font-size: 30px !important; -} - -h1.site-logo small { - font-size: 20px !important; -} - -h1.site-logo { - font-size: 30px !important; -} - -h1.site-logo small { - font-size: 20px !important; -} - -tbody, thead, pre { - border: 1px solid rgba(0, 0, 0, 0.25); -} - -table td, th { - padding: 8px; -} - -table p { - margin-bottom: 0; -} - -table td code { - white-space: nowrap; -} - -table tr, -table th { - border-bottom: 1px solid rgba(0, 0, 0, 0.1); -} - -table tr:last-child { - border-bottom: 0; -} - -pre { - box-shadow: inherit !important; - background-color: #fff; -} - -.text-align\:center { - text-align: center; -} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 5c95c8f..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,16 +0,0 @@ -project = "UnitCommitment.jl" -copyright = "2020-2022, UChicago Argonne, LLC" -author = "" -release = "0.3" -extensions = ["myst_parser"] -templates_path = ["_templates"] -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] -html_theme = "sphinx_book_theme" -html_static_path = ["_static"] -html_css_files = ["custom.css"] -html_theme_options = { - "repository_url": "https://github.com/ANL-CEEESA/UnitCommitment.jl/", - "use_repository_button": False, - "extra_navbar": "", -} -html_title = f"UnitCommitment.jl
{release}" diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 0000000..d7a587e --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,16 @@ +using Documenter, UnitCommitment + +makedocs( + sitename="UnitCommitment.jl", + pages=[ + "Home" => "index.md", + "usage.md", + "format.md", + "instances.md", + "model.md", + "api.md", + ], + format = Documenter.HTML( + assets=["assets/custom.css"], + ) +) diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index cdb4a16..0000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,4 +0,0 @@ -Sphinx==3.5.4 -sphinx-book-theme==0.1.0 -myst-parser==0.14.0 -Jinja2==3.0.2 \ No newline at end of file diff --git a/docs/src/api.md b/docs/src/api.md new file mode 100644 index 0000000..4cb85ac --- /dev/null +++ b/docs/src/api.md @@ -0,0 +1,48 @@ +# API Reference + +## Read data, build model & optimize + +```@docs +UnitCommitment.read +UnitCommitment.read_benchmark +UnitCommitment.build_model +UnitCommitment.optimize! +UnitCommitment.solution +UnitCommitment.validate +UnitCommitment.write +``` + +## Modify instance + +```@docs +UnitCommitment.slice +UnitCommitment.randomize! +generate_initial_conditions! +``` + +## Formulations + +```@docs +UnitCommitment.ArrCon2000 +UnitCommitment.CarArr2006 +UnitCommitment.DamKucRajAta2016 +UnitCommitment.Gar1962 +UnitCommitment.KnuOstWat2018 +UnitCommitment.MorLatRam2013 +UnitCommitment.PanGua2016 +UnitCommitment.WanHob2016 +``` + +## Solution Methods + +```@docs +UnitCommitment.XavQiuWanThi2019 +UnitCommitment.XavQiuWanThi2019.Method +``` + +## Randomization Methods + +```@docs +UnitCommitment.XavQiuAhm2021 +UnitCommitment.XavQiuAhm2021.Randomization +``` \ No newline at end of file diff --git a/docs/_static/cost_curve.png b/docs/src/assets/cost_curve.png similarity index 100% rename from docs/_static/cost_curve.png rename to docs/src/assets/cost_curve.png diff --git a/docs/src/assets/custom.css b/docs/src/assets/custom.css new file mode 100644 index 0000000..07214a3 --- /dev/null +++ b/docs/src/assets/custom.css @@ -0,0 +1,36 @@ +@media screen and (min-width: 1056px) { + #documenter .docs-main { + max-width: 65rem !important; + } +} + + +tbody, thead, pre { + border: 1px solid rgba(0, 0, 0, 0.25); +} + +table td, th { + padding: 8px; +} + +table p { + margin-bottom: 0; +} + +table td code { + white-space: nowrap; +} + +table tr, +table th { + border-bottom: 1px solid rgba(0, 0, 0, 0.1); +} + +table tr:last-child { + border-bottom: 0; +} + +code { + background-color: transparent; + color: rgb(232, 62, 140); +} \ No newline at end of file diff --git a/docs/format.md b/docs/src/format.md similarity index 96% rename from docs/format.md rename to docs/src/format.md index de86b21..3f9887c 100644 --- a/docs/format.md +++ b/docs/src/format.md @@ -1,32 +1,20 @@ -```{sectnum} ---- -start: 2 -depth: 2 -suffix: . ---- -``` - - Data Format =========== - Input Data Format ----------------- Instances are specified by JSON files containing the following main sections: -* Parameters -* Buses -* Generators -* Price-sensitive loads -* Transmission lines -* Reserves -* Contingencies - -Each section is described in detail below. See [case118/2017-01-01.json.gz][example] for a complete example. +* [Parameters](#Parameters) +* [Buses](#Buses) +* [Generators](#Generators) +* [Price-sensitive loads](#Price-sensitive-loads) +* [Transmission lines](#Transmission-lines) +* [Reserves](#Reserves) +* [Contingencies](#Contingencies) -[example]: https://axavier.org/UnitCommitment.jl/0.3/instances/matpower/case118/2017-01-01.json.gz +Each section is described in detail below. See [case118/2017-01-01.json.gz](https://axavier.org/UnitCommitment.jl/0.3/instances/matpower/case118/2017-01-01.json.gz) for a complete example. ### Parameters @@ -46,7 +34,7 @@ This section describes system-wide parameters, such as power balance penalty, an "Parameters": { "Version": "0.3", "Time horizon (h)": 4, - "Power balance penalty ($/MW)": 1000.0, + "Power balance penalty ($/MW)": 1000.0 } } ``` @@ -105,11 +93,13 @@ This section describes all generators in the system, including thermal units, re Production costs are represented as piecewise-linear curves. Figure 1 shows an example cost curve with three segments, where it costs \$1400, \$1600, \$2200 and \$2400 to generate, respectively, 100, 110, 130 and 135 MW of power. To model this generator, `Production cost curve (MW)` should be set to `[100, 110, 130, 135]`, and `Production cost curve ($)` should be set to `[1400, 1600, 2200, 2400]`. Note that this curve also specifies the production limits. Specifically, the first point identifies the minimum power output when the unit is operational, while the last point identifies the maximum power output. +```@raw html
- +
Figure 1. Piecewise-linear production cost curve.

+``` #### Additional remarks: @@ -173,7 +163,7 @@ This section describes components in the system which may increase or reduce the } ``` -### Transmission Lines +### Transmission lines This section describes the characteristics of transmission system, such as its topology and the susceptance of each transmission line. diff --git a/docs/index.md b/docs/src/index.md similarity index 81% rename from docs/index.md rename to docs/src/index.md index 0fd6456..b81db9c 100644 --- a/docs/index.md +++ b/docs/src/index.md @@ -6,25 +6,23 @@ * **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, 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. +* **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](https://doi.org/10.1109/59.871739), [MorLatRam2013](https://doi.org/10.1109/TPWRS.2013.2251373), [DamKucRajAta2016](https://doi.org/10.1007/s10107-015-0919-9), [PanGua2016](https://doi.org/10.1287/opre.2016.1520)), multiple piecewise-linear costs formulations ([Gar1962](https://doi.org/10.1109/AIEEPAS.1962.4501405), [CarArr2006](https://doi.org/10.1109/TPWRS.2006.876672), [KnuOstWat2018](https://doi.org/10.1109/TPWRS.2017.2783850)) and contingency screening methods ([XavQiuWanThi2019](https://doi.org/10.1109/TPWRS.2019.2892620)). 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 +## Table of Contents -### Authors +```@contents +Pages = ["usage.md", "format.md", "instances.md", "model.md", "api.md"] +Depth = 3 +``` + +## Authors * **Alinson S. Xavier** (Argonne National Laboratory) * **Aleksandr M. Kazachkov** (University of Florida) * **Ogün Yurdakul** (Technische Universität Berlin) * **Feng Qiu** (Argonne National Laboratory) -### Acknowledgments +## Acknowledgments * 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. @@ -32,7 +30,7 @@ * Based upon work supported by the **U.S. Department of Energy Advanced Grid Modeling Program** under Grant DE-OE0000875. -### Citing +## Citing If you use UnitCommitment.jl in your research (instances, models or algorithms), we kindly request that you cite the package as follows: @@ -40,7 +38,7 @@ If you use UnitCommitment.jl in your research (instances, models or algorithms), If you use the instances, we additionally request that you cite the original sources, as described in the [instances page](instances.md). -### License +## License ```text UnitCommitment.jl: A Julia/JuMP Optimization Package for Security-Constrained Unit Commitment @@ -68,16 +66,3 @@ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING N OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ``` - -## Site contents - -```{toctree} ---- -maxdepth: 2 ---- -usage.md -format.md -instances.md -model.md -``` - diff --git a/docs/instances.md b/docs/src/instances.md similarity index 95% rename from docs/instances.md rename to docs/src/instances.md index 67a81fc..29bfad0 100644 --- a/docs/instances.md +++ b/docs/src/instances.md @@ -1,19 +1,11 @@ -```{sectnum} ---- -start: 3 -depth: 2 -suffix: . ---- -``` - Instances ========= UnitCommitment.jl provides a large collection of benchmark instances collected from the literature and converted to a [common data format](format.md). In some cases, as indicated below, the original instances have been extended, with realistic parameters, using data-driven methods. If you use these instances in your research, we request that you cite UnitCommitment.jl, as well as the original sources, as listed below. Benchmark instances can be loaded with `UnitCommitment.read_benchmark(name)`, as explained in the [usage section](usage.md). Instance files can also be [directly downloaded from our website](https://axavier.org/UnitCommitment.jl/0.3/instances/). -```{warning} -The instances included in UC.jl are still under development and may change in the future. If you use these instances in your research, for reproducibility, you should specify what version of UC.jl they came from. -``` +!!! warning + + The instances included in UC.jl are still under development and may change in the future. If you use these instances in your research, for reproducibility, you should specify what version of UC.jl they came from. MATPOWER @@ -33,7 +25,7 @@ Because most MATPOWER test cases were originally designed for power flow studies * **Contingencies** were set to include all N-1 transmission line contingencies that do not generate islands or isolated buses. More specifically, there is one contingency for each transmission line, as long as that transmission line is not a bridge in the network graph. -For each MATPOWER test case, UC.jl provides 364 variations (`2017-01-01` to `2017-12-30`) corresponding different days of the year. +For each MATPOWER test case, UC.jl provides 365 variations (`2017-01-01` to `2017-12-31`) corresponding different days of the year. ### MATPOWER/UW-PSTCA @@ -296,14 +288,9 @@ References * [BaBlEh19] **Clayton Barrows, Aaron Bloom, Ali Ehlen, Jussi Ikaheimo, Jennie Jorgenson, Dheepak Krishnamurthy, Jessica Lau et al.** "The IEEE Reliability Test System: A Proposed 2019 Update." IEEE Transactions on Power Systems (2019). [DOI: 10.1109/TPWRS.2019.2925557](https://doi.org/10.1109/TPWRS.2019.2925557) -* [JoFlMa16] **C. Josz, S. Fliscounakis, J. Maeght, and P. Panciatici.** "AC Power Flow -Data in MATPOWER and QCQP Format: iTesla, RTE Snapshots, and PEGASE". [ArXiv (2016)](https://arxiv.org/abs/1603.01533). +* [JoFlMa16] **C. Josz, S. Fliscounakis, J. Maeght, and P. Panciatici.** "AC Power Flow Data in MATPOWER and QCQP Format: iTesla, RTE Snapshots, and PEGASE". [ArXiv (2016)](https://arxiv.org/abs/1603.01533). -* [FlPaCa13] **S. Fliscounakis, P. Panciatici, F. Capitanescu, and L. Wehenkel.** -"Contingency ranking with respect to overloads in very large power -systems taking into account uncertainty, preventive and corrective -actions", Power Systems, IEEE Trans. on, (28)4:4909-4917, 2013. -[DOI: 10.1109/TPWRS.2013.2251015](https://doi.org/10.1109/TPWRS.2013.2251015) +* [FlPaCa13] **S. Fliscounakis, P. Panciatici, F. Capitanescu, and L. Wehenkel.** "Contingency ranking with respect to overloads in very large power systems taking into account uncertainty, preventive and corrective actions", Power Systems, IEEE Trans. on, (28)4:4909-4917, 2013. [DOI: 10.1109/TPWRS.2013.2251015](https://doi.org/10.1109/TPWRS.2013.2251015) * [MTPWR] **D. Zimmerman, C. E. Murillo-Sandnchez and R. J. Thomas.** "Matpower: Steady-state operations, planning, and analysis tools forpower systems research and education", IEEE Transactions on PowerSystems, vol. 26, no. 1, pp. 12 –19, Feb. 2011. [DOI: 10.1109/TPWRS.2010.2051168](https://doi.org/10.1109/TPWRS.2010.2051168) diff --git a/docs/model.md b/docs/src/model.md similarity index 74% rename from docs/model.md rename to docs/src/model.md index 8936207..cb8e15d 100644 --- a/docs/model.md +++ b/docs/src/model.md @@ -1,11 +1,3 @@ -```{sectnum} ---- -start: 4 -depth: 2 -suffix: . ---- -``` - JuMP Model ========== @@ -17,7 +9,7 @@ Decision variables ### Generators Name | Symbol | Description | Unit ------|:--------:|-------------|:------: +:-----|:--------:|:-------------|:------: `is_on[g,t]` | $u_{g}(t)$ | True if generator `g` is on at time `t`. | Binary `switch_on[g,t]` | $v_{g}(t)$ | True is generator `g` switches on at time `t`. | Binary `switch_off[g,t]` | $w_{g}(t)$ | True if generator `g` switches off at time `t`. | Binary @@ -30,7 +22,7 @@ Name | Symbol | Description | Unit ### Buses Name | Symbol | Description | Unit ------|:------:|-------------|:------: +:-----|:------:|:-------------|:------: `net_injection[b,t]` | $n_b(t)$ | Net injection at bus `b` at time `t`. | MW `curtail[b,t]` | $s^+_b(t)$ | Amount of load curtailed at bus `b` at time `t` | MW @@ -38,69 +30,24 @@ Name | Symbol | Description | Unit ### Price-sensitive loads Name | Symbol | Description | Unit ------|:------:|-------------|:------: +:-----|:------:|:-------------|:------: `loads[s,t]` | $d_{s}(t)$ | Amount of power served to price-sensitive load `s` at time `t`. | MW ### Transmission lines Name | Symbol | Description | Unit ------|:------:|-------------|:------: +:-----|:------:|:-------------|:------: `flow[l,t]` | $f_l(t)$ | Power flow on line `l` at time `t`. | MW `overflow[l,t]` | $f^+_l(t)$ | Amount of flow above the limit for line `l` at time `t`. | MW -```{warning} +!!! warning -Since transmission and N-1 security constraints are enforced in a lazy way, most of the `flow[l,t]` variables are never added to the model. Accessing `model[:flow][l,t]` without first checking that the variable exists will likely generate an error. -``` + Since transmission and N-1 security constraints are enforced in a lazy way, most of the `flow[l,t]` variables are never added to the model. Accessing `model[:flow][l,t]` without first checking that the variable exists will likely generate an error. Objective function ------------------ -$$ -\begin{align} - \text{minimize} \;\; & - \sum_{t \in \mathcal{T}} - \sum_{g \in \mathcal{G}} - C^\text{min}_g(t) u_g(t) \\ - & - + \sum_{t \in \mathcal{T}} - \sum_{g \in \mathcal{G}} - \sum_{g \in \mathcal{K}_g} - C^k_g(t) p^k_g(t) \\ - & - + \sum_{t \in \mathcal{T}} - \sum_{g \in \mathcal{G}} - \sum_{s \in \mathcal{S}_g} - C^s_{g}(t) \delta^s_g(t) \\ - & - + \sum_{t \in \mathcal{T}} - \sum_{l \in \mathcal{L}} - C^\text{overflow}_{l}(t) f^+_l(t) \\ - & - + \sum_{t \in \mathcal{T}} - \sum_{b \in \mathcal{B}} - C^\text{curtail}(t) s^+_b(t) \\ - & - - \sum_{t \in \mathcal{T}} - \sum_{s \in \mathcal{PS}} - R_{s}(t) d_{s}(t) \\ - -\end{align} -$$ -where -- $\mathcal{B}$ is the set of buses -- $\mathcal{G}$ is the set of generators -- $\mathcal{L}$ is the set of transmission lines -- $\mathcal{PS}$ is the set of price-sensitive loads -- $\mathcal{S}_g$ is the set of start-up categories for generator $g$ -- $\mathcal{T}$ is the set of time steps -- $C^\text{curtail}(t)$ is the curtailment penalty (in \$/MW) -- $C^\text{min}_g(t)$ is the cost of keeping generator $g$ on and producing at minimum power during time $t$ (in \$) -- $C^\text{overflow}_{l}(t)$ is the flow limit penalty for line $l$ at time $t$ (in \$/MW) -- $C^k_g(t)$ is the cost for generator $g$ to produce 1 MW of power at time $t$ under piecewise linear segment $k$ -- $C^s_{g}(t)$ is the cost of starting up generator $g$ at time $t$ under start-up category $s$ (in \$) -- $R_{s}(t)$ is the revenue obtained from serving price-sensitive load $s$ at time $t$ (in \$/MW) - +TODO Constraints ----------- diff --git a/docs/usage.md b/docs/src/usage.md similarity index 92% rename from docs/usage.md rename to docs/src/usage.md index de3f794..3c65b75 100644 --- a/docs/usage.md +++ b/docs/src/usage.md @@ -1,11 +1,3 @@ -```{sectnum} ---- -start: 1 -depth: 2 -suffix: . ---- -``` - Usage ===== @@ -126,9 +118,9 @@ model = UnitCommitment.build_model( UnitCommitment.optimize!(model) ``` -```{warning} -The function `generate_initial_conditions!` may return different initial conditions after each call, even if the same instance and the same optimizer is provided. The particular algorithm may also change in a future version of UC.jl. For these reasons, it is recommended that you generate initial conditions exactly once for each instance and store them for later use. -``` +!!! warning + + The function `generate_initial_conditions!` may return different initial conditions after each call, even if the same instance and the same optimizer is provided. The particular algorithm may also change in a future version of UC.jl. For these reasons, it is recommended that you generate initial conditions exactly once for each instance and store them for later use. ### Verifying solutions diff --git a/src/model/formulations/WanHob2016/structs.jl b/src/model/formulations/WanHob2016/structs.jl index 52f621b..1a1ab64 100644 --- a/src/model/formulations/WanHob2016/structs.jl +++ b/src/model/formulations/WanHob2016/structs.jl @@ -4,6 +4,7 @@ """ Formulation described in: + B. Wang and B. F. Hobbs, "Real-Time Markets for Flexiramp: A Stochastic Unit Commitment-Based Analysis," in IEEE Transactions on Power Systems, vol. 31, no. 2, pp. 846-860, March 2016, doi: 10.1109/TPWRS.2015.2411268.