From 5beff627d3ac39c78162ebb6c9603562c2d408d4 Mon Sep 17 00:00:00 2001 From: Alinson S Xavier Date: Mon, 24 Jan 2022 10:42:55 -0600 Subject: [PATCH 1/2] Cite sources in read_benchmark; update docs --- Makefile | 2 +- docs/instances.md | 86 +++++++++++++++++--------------------------- src/instance/read.jl | 10 ++++-- 3 files changed, 41 insertions(+), 57 deletions(-) diff --git a/Makefile b/Makefile index a331d19..7d62316 100644 --- a/Makefile +++ b/Makefile @@ -2,7 +2,7 @@ # Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved. # Released under the modified BSD license. See COPYING.md for more details. -VERSION := 0.2 +VERSION := 0.3 clean: rm -rfv build diff --git a/docs/instances.md b/docs/instances.md index 7682343..eb6c9b1 100644 --- a/docs/instances.md +++ b/docs/instances.md @@ -9,7 +9,11 @@ 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. Benchmark instances can be loaded with `UnitCommitment.read_benchmark(name)`, as explained in the [usage section](usage.md). +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). + +```{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 @@ -29,7 +33,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 two variations (`2017-02-01` and `2017-08-01`) corresponding respectively to a winter and to a summer test case. +For each MATPOWER test case, UC.jl provides 365 variations, corresponding to each day of the year (from `2017-01-01` to `2017-12-31`). ### MATPOWER/UW-PSTCA @@ -37,16 +41,11 @@ A variety of smaller IEEE test cases, [compiled by University of Washington](htt | Name | Buses | Generators | Lines | Contingencies | References | |------|-------|------------|-------|---------------|--------| -| `matpower/case14/2017-02-01` | 14 | 5 | 20 | 19 | [MTPWR, PSTCA] -| `matpower/case14/2017-08-01` | 14 | 5 | 20 | 19 | [MTPWR, PSTCA] -| `matpower/case30/2017-02-01` | 30 | 6 | 41 | 38 | [MTPWR, PSTCA] -| `matpower/case30/2017-08-01` | 30 | 6 | 41 | 38 | [MTPWR, PSTCA] -| `matpower/case57/2017-02-01` | 57 | 7 | 80 | 79 | [MTPWR, PSTCA] -| `matpower/case57/2017-08-01` | 57 | 7 | 80 | 79 | [MTPWR, PSTCA] -| `matpower/case118/2017-02-01` | 118 | 54 | 186 | 177 | [MTPWR, PSTCA] -| `matpower/case118/2017-08-01` | 118 | 54 | 186 | 177 | [MTPWR, PSTCA] -| `matpower/case300/2017-02-01` | 300 | 69 | 411 | 320 | [MTPWR, PSTCA] -| `matpower/case300/2017-08-01` | 300 | 69 | 411 | 320 | [MTPWR, PSTCA] +| `matpower/case14/2017-01-01` | 14 | 5 | 20 | 19 | [MTPWR, PSTCA] +| `matpower/case30/2017-01-01` | 30 | 6 | 41 | 38 | [MTPWR, PSTCA] +| `matpower/case57/2017-01-01` | 57 | 7 | 80 | 79 | [MTPWR, PSTCA] +| `matpower/case118/2017-01-01` | 118 | 54 | 186 | 177 | [MTPWR, PSTCA] +| `matpower/case300/2017-01-01` | 300 | 69 | 411 | 320 | [MTPWR, PSTCA] ### MATPOWER/Polish @@ -55,22 +54,14 @@ Test cases based on the Polish 400, 220 and 110 kV networks, originally provided | Name | Buses | Generators | Lines | Contingencies | References | |------|-------|------------|-------|---------------|--------| -| `matpower/case2383wp/2017-02-01` | 2383 | 323 | 2896 | 2240 | [MTPWR] -| `matpower/case2383wp/2017-08-01` | 2383 | 323 | 2896 | 2240 | [MTPWR] -| `matpower/case2736sp/2017-02-01` | 2736 | 289 | 3504 | 3159 | [MTPWR] -| `matpower/case2736sp/2017-08-01` | 2736 | 289 | 3504 | 3159 | [MTPWR] -| `matpower/case2737sop/2017-02-01` | 2737 | 267 | 3506 | 3161 | [MTPWR] -| `matpower/case2737sop/2017-08-01` | 2737 | 267 | 3506 | 3161 | [MTPWR] -| `matpower/case2746wop/2017-02-01` | 2746 | 443 | 3514 | 3155 | [MTPWR] -| `matpower/case2746wop/2017-08-01` | 2746 | 443 | 3514 | 3155 | [MTPWR] -| `matpower/case2746wp/2017-02-01` | 2746 | 457 | 3514 | 3156 | [MTPWR] -| `matpower/case2746wp/2017-08-01` | 2746 | 457 | 3514 | 3156 | [MTPWR] -| `matpower/case3012wp/2017-02-01` | 3012 | 496 | 3572 | 2854 | [MTPWR] -| `matpower/case3012wp/2017-08-01` | 3012 | 496 | 3572 | 2854 | [MTPWR] -| `matpower/case3120sp/2017-02-01` | 3120 | 483 | 3693 | 2950 | [MTPWR] -| `matpower/case3120sp/2017-08-01` | 3120 | 483 | 3693 | 2950 | [MTPWR] -| `matpower/case3375wp/2017-02-01` | 3374 | 590 | 4161 | 3245 | [MTPWR] -| `matpower/case3375wp/2017-08-01` | 3374 | 590 | 4161 | 3245 | [MTPWR] +| `matpower/case2383wp/2017-01-01` | 2383 | 323 | 2896 | 2240 | [MTPWR] +| `matpower/case2736sp/2017-01-01` | 2736 | 289 | 3504 | 3159 | [MTPWR] +| `matpower/case2737sop/2017-01-01` | 2737 | 267 | 3506 | 3161 | [MTPWR] +| `matpower/case2746wop/2017-01-01` | 2746 | 443 | 3514 | 3155 | [MTPWR] +| `matpower/case2746wp/2017-01-01` | 2746 | 457 | 3514 | 3156 | [MTPWR] +| `matpower/case3012wp/2017-01-01` | 3012 | 496 | 3572 | 2854 | [MTPWR] +| `matpower/case3120sp/2017-01-01` | 3120 | 483 | 3693 | 2950 | [MTPWR] +| `matpower/case3375wp/2017-01-01` | 3374 | 590 | 4161 | 3245 | [MTPWR] ### MATPOWER/PEGASE @@ -78,16 +69,11 @@ Test cases from the [Pan European Grid Advanced Simulation and State Estimation | Name | Buses | Generators | Lines | Contingencies | References | |------|-------|------------|-------|---------------|--------| -| `matpower/case89pegase/2017-02-01` | 89 | 12 | 210 | 192 | [JoFlMa16, FlPaCa13, MTPWR] -| `matpower/case89pegase/2017-08-01` | 89 | 12 | 210 | 192 | [JoFlMa16, FlPaCa13, MTPWR] -| `matpower/case1354pegase/2017-02-01` | 1354 | 260 | 1991 | 1288 | [JoFlMa16, FlPaCa13, MTPWR] -| `matpower/case1354pegase/2017-08-01` | 1354 | 260 | 1991 | 1288 | [JoFlMa16, FlPaCa13, MTPWR] -| `matpower/case2869pegase/2017-02-01` | 2869 | 510 | 4582 | 3579 | [JoFlMa16, FlPaCa13, MTPWR] -| `matpower/case2869pegase/2017-08-01` | 2869 | 510 | 4582 | 3579 | [JoFlMa16, FlPaCa13, MTPWR] -| `matpower/case9241pegase/2017-02-01` | 9241 | 1445 | 16049 | 13932 | [JoFlMa16, FlPaCa13, MTPWR] -| `matpower/case9241pegase/2017-08-01` | 9241 | 1445 | 16049 | 13932 | [JoFlMa16, FlPaCa13, MTPWR] -| `matpower/case13659pegase/2017-02-01` | 13659 | 4092 | 20467 | 13932 | [JoFlMa16, FlPaCa13, MTPWR] -| `matpower/case13659pegase/2017-08-01` | 13659 | 4092 | 20467 | 13932 | [JoFlMa16, FlPaCa13, MTPWR] +| `matpower/case89pegase/2017-01-01` | 89 | 12 | 210 | 192 | [JoFlMa16, FlPaCa13, MTPWR] +| `matpower/case1354pegase/2017-01-01` | 1354 | 260 | 1991 | 1288 | [JoFlMa16, FlPaCa13, MTPWR] +| `matpower/case2869pegase/2017-01-01` | 2869 | 510 | 4582 | 3579 | [JoFlMa16, FlPaCa13, MTPWR] +| `matpower/case9241pegase/2017-01-01` | 9241 | 1445 | 16049 | 13932 | [JoFlMa16, FlPaCa13, MTPWR] +| `matpower/case13659pegase/2017-01-01` | 13659 | 4092 | 20467 | 13932 | [JoFlMa16, FlPaCa13, MTPWR] ### MATPOWER/RTE @@ -95,22 +81,14 @@ Test cases from the R&D Division at [Reseau de Transport d'Electricite](https:// | Name | Buses | Generators | Lines | Contingencies | References | |------|-------|------------|-------|---------------|--------| -| `matpower/case1888rte/2017-02-01` | 1888 | 296 | 2531 | 1484 | [MTPWR, JoFlMa16] -| `matpower/case1888rte/2017-08-01` | 1888 | 296 | 2531 | 1484 | [MTPWR, JoFlMa16] -| `matpower/case1951rte/2017-02-01` | 1951 | 390 | 2596 | 1497 | [MTPWR, JoFlMa16] -| `matpower/case1951rte/2017-08-01` | 1951 | 390 | 2596 | 1497 | [MTPWR, JoFlMa16] -| `matpower/case2848rte/2017-02-01` | 2848 | 544 | 3776 | 2242 | [MTPWR, JoFlMa16] -| `matpower/case2848rte/2017-08-01` | 2848 | 544 | 3776 | 2242 | [MTPWR, JoFlMa16] -| `matpower/case2868rte/2017-02-01` | 2868 | 596 | 3808 | 2260 | [MTPWR, JoFlMa16] -| `matpower/case2868rte/2017-08-01` | 2868 | 596 | 3808 | 2260 | [MTPWR, JoFlMa16] -| `matpower/case6468rte/2017-02-01` | 6468 | 1262 | 9000 | 6094 | [MTPWR, JoFlMa16] -| `matpower/case6468rte/2017-08-01` | 6468 | 1262 | 9000 | 6094 | [MTPWR, JoFlMa16] -| `matpower/case6470rte/2017-02-01` | 6470 | 1306 | 9005 | 6085 | [MTPWR, JoFlMa16] -| `matpower/case6470rte/2017-08-01` | 6470 | 1306 | 9005 | 6085 | [MTPWR, JoFlMa16] -| `matpower/case6495rte/2017-02-01` | 6495 | 1352 | 9019 | 6060 | [MTPWR, JoFlMa16] -| `matpower/case6495rte/2017-08-01` | 6495 | 1352 | 9019 | 6060 | [MTPWR, JoFlMa16] -| `matpower/case6515rte/2017-02-01` | 6515 | 1368 | 9037 | 6063 | [MTPWR, JoFlMa16] -| `matpower/case6515rte/2017-08-01` | 6515 | 1368 | 9037 | 6063 | [MTPWR, JoFlMa16] +| `matpower/case1888rte/2017-01-01` | 1888 | 296 | 2531 | 1484 | [MTPWR, JoFlMa16] +| `matpower/case1951rte/2017-01-01` | 1951 | 390 | 2596 | 1497 | [MTPWR, JoFlMa16] +| `matpower/case2848rte/2017-01-01` | 2848 | 544 | 3776 | 2242 | [MTPWR, JoFlMa16] +| `matpower/case2868rte/2017-01-01` | 2868 | 596 | 3808 | 2260 | [MTPWR, JoFlMa16] +| `matpower/case6468rte/2017-01-01` | 6468 | 1262 | 9000 | 6094 | [MTPWR, JoFlMa16] +| `matpower/case6470rte/2017-01-01` | 6470 | 1306 | 9005 | 6085 | [MTPWR, JoFlMa16] +| `matpower/case6495rte/2017-01-01` | 6495 | 1352 | 9019 | 6060 | [MTPWR, JoFlMa16] +| `matpower/case6515rte/2017-01-01` | 6515 | 1368 | 9037 | 6063 | [MTPWR, JoFlMa16] PGLIB-UC Instances diff --git a/src/instance/read.jl b/src/instance/read.jl index 3ca522c..59956b9 100644 --- a/src/instance/read.jl +++ b/src/instance/read.jl @@ -23,15 +23,21 @@ Example import UnitCommitment instance = UnitCommitment.read_benchmark("matpower/case3375wp/2017-02-01") """ -function read_benchmark(name::AbstractString)::UnitCommitmentInstance +function read_benchmark(name::AbstractString; quiet::Bool=false)::UnitCommitmentInstance basedir = dirname(@__FILE__) filename = "$basedir/../../instances/$name.json.gz" url = "$INSTANCES_URL/$name.json.gz" if !isfile(filename) - @info "Downloading: $(url)" + if !quiet + @info "Downloading: $(url)" + end dpath = download(url) mkpath(dirname(filename)) cp(dpath, filename) + json = _read_json(filename) + if "SOURCE" in keys(json) && !quiet + @info "If you use this instance in your research, please cite:\n\n$(json["SOURCE"])\n" + end end return UnitCommitment.read(filename) end From ec0f9dcfcd8c734dcd10a17cdf93481d99787771 Mon Sep 17 00:00:00 2001 From: Alinson S Xavier Date: Tue, 1 Mar 2022 16:16:24 -0600 Subject: [PATCH 2/2] Temporarily revert changes to instances.md; download v0.2 instances --- Makefile | 2 +- docs/instances.md | 54 ++++++++++++++++++++++---------------------- src/instance/read.jl | 2 +- 3 files changed, 29 insertions(+), 29 deletions(-) diff --git a/Makefile b/Makefile index 7d62316..a331d19 100644 --- a/Makefile +++ b/Makefile @@ -2,7 +2,7 @@ # Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved. # Released under the modified BSD license. See COPYING.md for more details. -VERSION := 0.3 +VERSION := 0.2 clean: rm -rfv build diff --git a/docs/instances.md b/docs/instances.md index eb6c9b1..b2e7c63 100644 --- a/docs/instances.md +++ b/docs/instances.md @@ -33,7 +33,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 365 variations, corresponding to each day of the year (from `2017-01-01` to `2017-12-31`). +For each MATPOWER test case, UC.jl provides two variations (`2017-02-01` and `2017-08-01`) corresponding respectively to a winter and to a summer test case. ### MATPOWER/UW-PSTCA @@ -41,11 +41,11 @@ A variety of smaller IEEE test cases, [compiled by University of Washington](htt | Name | Buses | Generators | Lines | Contingencies | References | |------|-------|------------|-------|---------------|--------| -| `matpower/case14/2017-01-01` | 14 | 5 | 20 | 19 | [MTPWR, PSTCA] -| `matpower/case30/2017-01-01` | 30 | 6 | 41 | 38 | [MTPWR, PSTCA] -| `matpower/case57/2017-01-01` | 57 | 7 | 80 | 79 | [MTPWR, PSTCA] -| `matpower/case118/2017-01-01` | 118 | 54 | 186 | 177 | [MTPWR, PSTCA] -| `matpower/case300/2017-01-01` | 300 | 69 | 411 | 320 | [MTPWR, PSTCA] +| `matpower/case14/2017-02-01` | 14 | 5 | 20 | 19 | [MTPWR, PSTCA] +| `matpower/case30/2017-02-01` | 30 | 6 | 41 | 38 | [MTPWR, PSTCA] +| `matpower/case57/2017-02-01` | 57 | 7 | 80 | 79 | [MTPWR, PSTCA] +| `matpower/case118/2017-02-01` | 118 | 54 | 186 | 177 | [MTPWR, PSTCA] +| `matpower/case300/2017-02-01` | 300 | 69 | 411 | 320 | [MTPWR, PSTCA] ### MATPOWER/Polish @@ -54,14 +54,14 @@ Test cases based on the Polish 400, 220 and 110 kV networks, originally provided | Name | Buses | Generators | Lines | Contingencies | References | |------|-------|------------|-------|---------------|--------| -| `matpower/case2383wp/2017-01-01` | 2383 | 323 | 2896 | 2240 | [MTPWR] -| `matpower/case2736sp/2017-01-01` | 2736 | 289 | 3504 | 3159 | [MTPWR] -| `matpower/case2737sop/2017-01-01` | 2737 | 267 | 3506 | 3161 | [MTPWR] -| `matpower/case2746wop/2017-01-01` | 2746 | 443 | 3514 | 3155 | [MTPWR] -| `matpower/case2746wp/2017-01-01` | 2746 | 457 | 3514 | 3156 | [MTPWR] -| `matpower/case3012wp/2017-01-01` | 3012 | 496 | 3572 | 2854 | [MTPWR] -| `matpower/case3120sp/2017-01-01` | 3120 | 483 | 3693 | 2950 | [MTPWR] -| `matpower/case3375wp/2017-01-01` | 3374 | 590 | 4161 | 3245 | [MTPWR] +| `matpower/case2383wp/2017-02-01` | 2383 | 323 | 2896 | 2240 | [MTPWR] +| `matpower/case2736sp/2017-02-01` | 2736 | 289 | 3504 | 3159 | [MTPWR] +| `matpower/case2737sop/2017-02-01` | 2737 | 267 | 3506 | 3161 | [MTPWR] +| `matpower/case2746wop/2017-02-01` | 2746 | 443 | 3514 | 3155 | [MTPWR] +| `matpower/case2746wp/2017-02-01` | 2746 | 457 | 3514 | 3156 | [MTPWR] +| `matpower/case3012wp/2017-02-01` | 3012 | 496 | 3572 | 2854 | [MTPWR] +| `matpower/case3120sp/2017-02-01` | 3120 | 483 | 3693 | 2950 | [MTPWR] +| `matpower/case3375wp/2017-02-01` | 3374 | 590 | 4161 | 3245 | [MTPWR] ### MATPOWER/PEGASE @@ -69,11 +69,11 @@ Test cases from the [Pan European Grid Advanced Simulation and State Estimation | Name | Buses | Generators | Lines | Contingencies | References | |------|-------|------------|-------|---------------|--------| -| `matpower/case89pegase/2017-01-01` | 89 | 12 | 210 | 192 | [JoFlMa16, FlPaCa13, MTPWR] -| `matpower/case1354pegase/2017-01-01` | 1354 | 260 | 1991 | 1288 | [JoFlMa16, FlPaCa13, MTPWR] -| `matpower/case2869pegase/2017-01-01` | 2869 | 510 | 4582 | 3579 | [JoFlMa16, FlPaCa13, MTPWR] -| `matpower/case9241pegase/2017-01-01` | 9241 | 1445 | 16049 | 13932 | [JoFlMa16, FlPaCa13, MTPWR] -| `matpower/case13659pegase/2017-01-01` | 13659 | 4092 | 20467 | 13932 | [JoFlMa16, FlPaCa13, MTPWR] +| `matpower/case89pegase/2017-02-01` | 89 | 12 | 210 | 192 | [JoFlMa16, FlPaCa13, MTPWR] +| `matpower/case1354pegase/2017-02-01` | 1354 | 260 | 1991 | 1288 | [JoFlMa16, FlPaCa13, MTPWR] +| `matpower/case2869pegase/2017-02-01` | 2869 | 510 | 4582 | 3579 | [JoFlMa16, FlPaCa13, MTPWR] +| `matpower/case9241pegase/2017-02-01` | 9241 | 1445 | 16049 | 13932 | [JoFlMa16, FlPaCa13, MTPWR] +| `matpower/case13659pegase/2017-02-01` | 13659 | 4092 | 20467 | 13932 | [JoFlMa16, FlPaCa13, MTPWR] ### MATPOWER/RTE @@ -81,14 +81,14 @@ Test cases from the R&D Division at [Reseau de Transport d'Electricite](https:// | Name | Buses | Generators | Lines | Contingencies | References | |------|-------|------------|-------|---------------|--------| -| `matpower/case1888rte/2017-01-01` | 1888 | 296 | 2531 | 1484 | [MTPWR, JoFlMa16] -| `matpower/case1951rte/2017-01-01` | 1951 | 390 | 2596 | 1497 | [MTPWR, JoFlMa16] -| `matpower/case2848rte/2017-01-01` | 2848 | 544 | 3776 | 2242 | [MTPWR, JoFlMa16] -| `matpower/case2868rte/2017-01-01` | 2868 | 596 | 3808 | 2260 | [MTPWR, JoFlMa16] -| `matpower/case6468rte/2017-01-01` | 6468 | 1262 | 9000 | 6094 | [MTPWR, JoFlMa16] -| `matpower/case6470rte/2017-01-01` | 6470 | 1306 | 9005 | 6085 | [MTPWR, JoFlMa16] -| `matpower/case6495rte/2017-01-01` | 6495 | 1352 | 9019 | 6060 | [MTPWR, JoFlMa16] -| `matpower/case6515rte/2017-01-01` | 6515 | 1368 | 9037 | 6063 | [MTPWR, JoFlMa16] +| `matpower/case1888rte/2017-02-01` | 1888 | 296 | 2531 | 1484 | [MTPWR, JoFlMa16] +| `matpower/case1951rte/2017-02-01` | 1951 | 390 | 2596 | 1497 | [MTPWR, JoFlMa16] +| `matpower/case2848rte/2017-02-01` | 2848 | 544 | 3776 | 2242 | [MTPWR, JoFlMa16] +| `matpower/case2868rte/2017-02-01` | 2868 | 596 | 3808 | 2260 | [MTPWR, JoFlMa16] +| `matpower/case6468rte/2017-02-01` | 6468 | 1262 | 9000 | 6094 | [MTPWR, JoFlMa16] +| `matpower/case6470rte/2017-02-01` | 6470 | 1306 | 9005 | 6085 | [MTPWR, JoFlMa16] +| `matpower/case6495rte/2017-02-01` | 6495 | 1352 | 9019 | 6060 | [MTPWR, JoFlMa16] +| `matpower/case6515rte/2017-02-01` | 6515 | 1368 | 9037 | 6063 | [MTPWR, JoFlMa16] PGLIB-UC Instances diff --git a/src/instance/read.jl b/src/instance/read.jl index 59956b9..621976b 100644 --- a/src/instance/read.jl +++ b/src/instance/read.jl @@ -8,7 +8,7 @@ using DataStructures using GZip import Base: getindex, time -const INSTANCES_URL = "https://axavier.org/UnitCommitment.jl/0.3/instances" +const INSTANCES_URL = "https://axavier.org/UnitCommitment.jl/0.2/instances" """ read_benchmark(name::AbstractString)::UnitCommitmentInstance