ANL-CEEESA
/
UnitCommitment.jl
mirror of https://github.com/ANL-CEEESA/UnitCommitment.jl.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: Minor changes; add examples to repository

Browse Source
pull/33/merge
Alinson S. Xavier 2 years ago
parent d49712f41b
commit b39b14afa4
Signed by: isoron
GPG Key ID: 0DA8E4B9E1109DCA
8 changed files with 2217 additions and 50 deletions
Show Stats Download Patch File Download Diff File

4
docs/Project.toml
Unescape View File

@ -1,5 +1,9 @@
[deps]
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
Glob = "c27321d9-0574-5035-807b-f59d2c89b15c"
HiGHS = "87dc4568-4c63-4d18-b0c0-bb2238e4078b"
JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
MPI = "da04e1cc-30fd-572f-bb4f-1f8673147195"
Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"
UnitCommitment = "64606440-39ea-11e9-0f29-3303a1d3d877"

1158
docs/example/out.json
View File

File diff suppressed because it is too large Load Diff

495
docs/example/s1.json
Unescape View File

@ -0,0 +1,495 @@
{
"Parameters": {
"Version": "0.3",
"Time horizon (h)": 4
},
"Generators": {
"g1": {
"Bus": "b1",
"Production cost curve (MW)": [
100,
110,
130,
135
],
"Production cost curve ($)": [
1400,
1600,
2200,
2400
],
"Startup delays (h)": [
1,
2,
3
],
"Startup costs ($)": [
1000.0,
1500.0,
2000.0
],
"Initial status (h)": -100,
"Initial power (MW)": 0
},
"g2": {
"Bus": "b2",
"Production cost curve (MW)": [
0,
47,
94,
140
],
"Production cost curve ($)": [
0,
2256.00,
4733.37,
7395.39
],
"Startup delays (h)": [
1,
4
],
"Startup costs ($)": [
3000.0,
4000.0
],
"Ramp up limit (MW)": 98.0,
"Ramp down limit (MW)": 98.0,
"Startup limit (MW)": 98.0,
"Shutdown limit (MW)": 98.0,
"Minimum uptime (h)": 4,
"Minimum downtime (h)": 4,
"Maximum daily energy (MWh)": null,
"Maximum daily starts": null,
"Initial status (h)": -8,
"Initial power (MW)": 0,
"Reserve eligibility": [
"r1"
]
},
"g3": {
"Bus": "b3",
"Production cost curve (MW)": [
0,
33,
66,
100
],
"Production cost curve ($)": [
0,
1113.75,
2369.07,
3891.54
],
"Startup delays (h)": [
1,
4,
8
],
"Startup costs ($)": [
1000.0,
2000.0,
3000.0
],
"Ramp up limit (MW)": 70.0,
"Ramp down limit (MW)": 70.0,
"Startup limit (MW)": 70.0,
"Shutdown limit (MW)": 70.0,
"Must run?": true,
"Minimum uptime (h)": 1,
"Minimum downtime (h)": 1,
"Maximum daily energy (MWh)": null,
"Maximum daily starts": null,
"Initial status (h)": -6,
"Initial power (MW)": 0,
"Reserve eligibility": [
"r1"
]
},
"g4": {
"Bus": "b6",
"Production cost curve (MW)": [
33,
66,
100
],
"Production cost curve ($)": [
1113.75,
2369.07,
3891.54
],
"Initial status (h)": -100,
"Initial power (MW)": 0,
"Reserve eligibility": [
"r1"
]
},
"g5": {
"Bus": "b8",
"Production cost curve (MW)": [
33,
66,
100
],
"Production cost curve ($)": [
1113.75,
2369.07,
3891.54
],
"Initial status (h)": -100,
"Initial power (MW)": 0,
"Reserve eligibility": [
"r1"
]
},
"g6": {
"Bus": "b8",
"Production cost curve (MW)": [
100
],
"Production cost curve ($)": [
10000.00
],
"Initial status (h)": -100,
"Initial power (MW)": 0,
"Reserve eligibility": [
"r1"
]
}
},
"Buses": {
"b1": {
"Load (MW)": 0.0
},
"b2": {
"Load (MW)": [
26.01527,
24.46212,
23.29725,
22.90897
]
},
"b3": {
"Load (MW)": [
112.93263,
106.19039,
101.1337,
99.44814
]
},
"b4": {
"Load (MW)": [
57.30552,
53.88429,
51.31838,
50.46307
]
},
"b5": {
"Load (MW)": [
9.11134,
8.56738,
8.15941,
8.02342
]
},
"b6": {
"Load (MW)": [
13.42723,
12.62561,
12.02439,
11.82398
]
},
"b7": {
"Load (MW)": 0.0
},
"b8": {
"Load (MW)": 0.0
},
"b9": {
"Load (MW)": [
35.36638,
33.25495,
31.67138,
31.14353
]
},
"b10": {
"Load (MW)": [
10.78974,
10.14558,
9.66246,
9.50141
]
},
"b11": {
"Load (MW)": [
4.19601,
3.9455,
3.75762,
3.69499
]
},
"b12": {
"Load (MW)": [
7.31305,
6.87645,
6.549,
6.43985
]
},
"b13": {
"Load (MW)": [
16.18461,
15.21837,
14.49368,
14.25212
]
},
"b14": {
"Load (MW)": [
17.86302,
16.79657,
15.99673,
15.73012
]
}
},
"Transmission lines": {
"l1": {
"Source bus": "b1",
"Target bus": "b2",
"Reactance (ohms)": 0.05917000000000001,
"Susceptance (S)": 29.496860773945063,
"Normal flow limit (MW)": 300.0,
"Emergency flow limit (MW)": 400.0,
"Flow limit penalty ($/MW)": 1000.0
},
"l2": {
"Source bus": "b1",
"Target bus": "b5",
"Reactance (ohms)": 0.22304000000000002,
"Susceptance (S)": 7.825184953346168
},
"l3": {
"Source bus": "b2",
"Target bus": "b3",
"Reactance (ohms)": 0.19797,
"Susceptance (S)": 8.816129979261149
},
"l4": {
"Source bus": "b2",
"Target bus": "b4",
"Reactance (ohms)": 0.17632,
"Susceptance (S)": 9.898645939169292
},
"l5": {
"Source bus": "b2",
"Target bus": "b5",
"Reactance (ohms)": 0.17388,
"Susceptance (S)": 10.037550333530765
},
"l6": {
"Source bus": "b3",
"Target bus": "b4",
"Reactance (ohms)": 0.17103,
"Susceptance (S)": 10.204813494675376
},
"l7": {
"Source bus": "b4",
"Target bus": "b5",
"Reactance (ohms)": 0.04211,
"Susceptance (S)": 41.44690695783257
},
"l8": {
"Source bus": "b4",
"Target bus": "b7",
"Reactance (ohms)": 0.20911999999999997,
"Susceptance (S)": 8.346065665619404
},
"l9": {
"Source bus": "b4",
"Target bus": "b9",
"Reactance (ohms)": 0.55618,
"Susceptance (S)": 3.1380654680037567
},
"l10": {
"Source bus": "b5",
"Target bus": "b6",
"Reactance (ohms)": 0.25201999999999997,
"Susceptance (S)": 6.92536009838239
},
"l11": {
"Source bus": "b6",
"Target bus": "b11",
"Reactance (ohms)": 0.1989,
"Susceptance (S)": 8.774908255376218
},
"l12": {
"Source bus": "b6",
"Target bus": "b12",
"Reactance (ohms)": 0.25581,
"Susceptance (S)": 6.8227561549365925
},
"l13": {
"Source bus": "b6",
"Target bus": "b13",
"Reactance (ohms)": 0.13027,
"Susceptance (S)": 13.397783465067395
},
"l14": {
"Source bus": "b7",
"Target bus": "b8",
"Reactance (ohms)": 0.17615,
"Susceptance (S)": 9.908198989465395
},
"l15": {
"Source bus": "b7",
"Target bus": "b9",
"Reactance (ohms)": 0.11001,
"Susceptance (S)": 15.865187273832648
},
"l16": {
"Source bus": "b9",
"Target bus": "b10",
"Reactance (ohms)": 0.0845,
"Susceptance (S)": 20.65478404727017
},
"l17": {
"Source bus": "b9",
"Target bus": "b14",
"Reactance (ohms)": 0.27038,
"Susceptance (S)": 6.4550974628091184
},
"l18": {
"Source bus": "b10",
"Target bus": "b11",
"Reactance (ohms)": 0.19207,
"Susceptance (S)": 9.08694357262628
},
"l19": {
"Source bus": "b12",
"Target bus": "b13",
"Reactance (ohms)": 0.19988,
"Susceptance (S)": 8.73188539120637
},
"l20": {
"Source bus": "b13",
"Target bus": "b14",
"Reactance (ohms)": 0.34802,
"Susceptance (S)": 5.0150257226433235
}
},
"Contingencies": {
"c1": {
"Affected lines": [
"l1"
]
},
"c2": {
"Affected lines": [
"l2"
]
},
"c3": {
"Affected lines": [
"l3"
]
},
"c4": {
"Affected lines": [
"l4"
]
},
"c5": {
"Affected lines": [
"l5"
]
},
"c6": {
"Affected lines": [
"l6"
]
},
"c7": {
"Affected lines": [
"l7"
]
},
"c8": {
"Affected lines": [
"l8"
]
},
"c9": {
"Affected lines": [
"l9"
]
},
"c10": {
"Affected lines": [
"l10"
]
},
"c11": {
"Affected lines": [
"l11"
]
},
"c12": {
"Affected lines": [
"l12"
]
},
"c13": {
"Affected lines": [
"l13"
]
},
"c15": {
"Affected lines": [
"l15"
]
},
"c16": {
"Affected lines": [
"l16"
]
},
"c17": {
"Affected lines": [
"l17"
]
},
"c18": {
"Affected lines": [
"l18"
]
},
"c19": {
"Affected lines": [
"l19"
]
},
"c20": {
"Affected lines": [
"l20"
]
}
},
"Price-sensitive loads": {
"ps1": {
"Bus": "b3",
"Revenue ($/MW)": 100.0,
"Demand (MW)": 50.0
}
},
"Reserves": {
"r1": {
"Type": "Spinning",
"Amount (MW)": 100.0,
"Shortfall penalty ($/MW)": 1000.0
}
}
}

495
docs/example/s2.json
Unescape View File

@ -0,0 +1,495 @@
{
"Parameters": {
"Version": "0.3",
"Time horizon (h)": 4
},
"Generators": {
"g1": {
"Bus": "b1",
"Production cost curve (MW)": [
100,
110,
130,
135
],
"Production cost curve ($)": [
1400,
1600,
2200,
2400
],
"Startup delays (h)": [
1,
2,
3
],
"Startup costs ($)": [
1000.0,
1500.0,
2000.0
],
"Initial status (h)": -100,
"Initial power (MW)": 0
},
"g2": {
"Bus": "b2",
"Production cost curve (MW)": [
0,
47,
94,
140
],
"Production cost curve ($)": [
0,
2256.00,
4733.37,
7395.39
],
"Startup delays (h)": [
1,
4
],
"Startup costs ($)": [
3000.0,
4000.0
],
"Ramp up limit (MW)": 98.0,
"Ramp down limit (MW)": 98.0,
"Startup limit (MW)": 98.0,
"Shutdown limit (MW)": 98.0,
"Minimum uptime (h)": 4,
"Minimum downtime (h)": 4,
"Maximum daily energy (MWh)": null,
"Maximum daily starts": null,
"Initial status (h)": -8,
"Initial power (MW)": 0,
"Reserve eligibility": [
"r1"
]
},
"g3": {
"Bus": "b3",
"Production cost curve (MW)": [
0,
33,
66,
100
],
"Production cost curve ($)": [
0,
1113.75,
2369.07,
3891.54
],
"Startup delays (h)": [
1,
4,
8
],
"Startup costs ($)": [
1000.0,
2000.0,
3000.0
],
"Ramp up limit (MW)": 70.0,
"Ramp down limit (MW)": 70.0,
"Startup limit (MW)": 70.0,
"Shutdown limit (MW)": 70.0,
"Must run?": true,
"Minimum uptime (h)": 1,
"Minimum downtime (h)": 1,
"Maximum daily energy (MWh)": null,
"Maximum daily starts": null,
"Initial status (h)": -6,
"Initial power (MW)": 0,
"Reserve eligibility": [
"r1"
]
},
"g4": {
"Bus": "b6",
"Production cost curve (MW)": [
33,
66,
100
],
"Production cost curve ($)": [
1113.75,
2369.07,
3891.54
],
"Initial status (h)": -100,
"Initial power (MW)": 0,
"Reserve eligibility": [
"r1"
]
},
"g5": {
"Bus": "b8",
"Production cost curve (MW)": [
33,
66,
100
],
"Production cost curve ($)": [
1113.75,
2369.07,
3891.54
],
"Initial status (h)": -100,
"Initial power (MW)": 0,
"Reserve eligibility": [
"r1"
]
},
"g6": {
"Bus": "b8",
"Production cost curve (MW)": [
100
],
"Production cost curve ($)": [
10000.00
],
"Initial status (h)": -100,
"Initial power (MW)": 0,
"Reserve eligibility": [
"r1"
]
}
},
"Buses": {
"b1": {
"Load (MW)": 0.0
},
"b2": {
"Load (MW)": [
26.01527,
24.46212,
23.29725,
22.90897
]
},
"b3": {
"Load (MW)": [
112.93263,
106.19039,
101.1337,
99.44814
]
},
"b4": {
"Load (MW)": [
57.30552,
53.88429,
51.31838,
50.46307
]
},
"b5": {
"Load (MW)": [
9.11134,
8.56738,
8.15941,
8.02342
]
},
"b6": {
"Load (MW)": [
13.42723,
12.62561,
12.02439,
11.82398
]
},
"b7": {
"Load (MW)": 0.0
},
"b8": {
"Load (MW)": 0.0
},
"b9": {
"Load (MW)": [
35.36638,
33.25495,
31.67138,
31.14353
]
},
"b10": {
"Load (MW)": [
10.78974,
10.14558,
9.66246,
9.50141
]
},
"b11": {
"Load (MW)": [
4.19601,
3.9455,
3.75762,
3.69499
]
},
"b12": {
"Load (MW)": [
7.31305,
6.87645,
6.549,
6.43985
]
},
"b13": {
"Load (MW)": [
16.18461,
15.21837,
14.49368,
14.25212
]
},
"b14": {
"Load (MW)": [
17.86302,
16.79657,
15.99673,
15.73012
]
}
},
"Transmission lines": {
"l1": {
"Source bus": "b1",
"Target bus": "b2",
"Reactance (ohms)": 0.05917000000000001,
"Susceptance (S)": 29.496860773945063,
"Normal flow limit (MW)": 300.0,
"Emergency flow limit (MW)": 400.0,
"Flow limit penalty ($/MW)": 1000.0
},
"l2": {
"Source bus": "b1",
"Target bus": "b5",
"Reactance (ohms)": 0.22304000000000002,
"Susceptance (S)": 7.825184953346168
},
"l3": {
"Source bus": "b2",
"Target bus": "b3",
"Reactance (ohms)": 0.19797,
"Susceptance (S)": 8.816129979261149
},
"l4": {
"Source bus": "b2",
"Target bus": "b4",
"Reactance (ohms)": 0.17632,
"Susceptance (S)": 9.898645939169292
},
"l5": {
"Source bus": "b2",
"Target bus": "b5",
"Reactance (ohms)": 0.17388,
"Susceptance (S)": 10.037550333530765
},
"l6": {
"Source bus": "b3",
"Target bus": "b4",
"Reactance (ohms)": 0.17103,
"Susceptance (S)": 10.204813494675376
},
"l7": {
"Source bus": "b4",
"Target bus": "b5",
"Reactance (ohms)": 0.04211,
"Susceptance (S)": 41.44690695783257
},
"l8": {
"Source bus": "b4",
"Target bus": "b7",
"Reactance (ohms)": 0.20911999999999997,
"Susceptance (S)": 8.346065665619404
},
"l9": {
"Source bus": "b4",
"Target bus": "b9",
"Reactance (ohms)": 0.55618,
"Susceptance (S)": 3.1380654680037567
},
"l10": {
"Source bus": "b5",
"Target bus": "b6",
"Reactance (ohms)": 0.25201999999999997,
"Susceptance (S)": 6.92536009838239
},
"l11": {
"Source bus": "b6",
"Target bus": "b11",
"Reactance (ohms)": 0.1989,
"Susceptance (S)": 8.774908255376218
},
"l12": {
"Source bus": "b6",
"Target bus": "b12",
"Reactance (ohms)": 0.25581,
"Susceptance (S)": 6.8227561549365925
},
"l13": {
"Source bus": "b6",
"Target bus": "b13",
"Reactance (ohms)": 0.13027,
"Susceptance (S)": 13.397783465067395
},
"l14": {
"Source bus": "b7",
"Target bus": "b8",
"Reactance (ohms)": 0.17615,
"Susceptance (S)": 9.908198989465395
},
"l15": {
"Source bus": "b7",
"Target bus": "b9",
"Reactance (ohms)": 0.11001,
"Susceptance (S)": 15.865187273832648
},
"l16": {
"Source bus": "b9",
"Target bus": "b10",
"Reactance (ohms)": 0.0845,
"Susceptance (S)": 20.65478404727017
},
"l17": {
"Source bus": "b9",
"Target bus": "b14",
"Reactance (ohms)": 0.27038,
"Susceptance (S)": 6.4550974628091184
},
"l18": {
"Source bus": "b10",
"Target bus": "b11",
"Reactance (ohms)": 0.19207,
"Susceptance (S)": 9.08694357262628
},
"l19": {
"Source bus": "b12",
"Target bus": "b13",
"Reactance (ohms)": 0.19988,
"Susceptance (S)": 8.73188539120637
},
"l20": {
"Source bus": "b13",
"Target bus": "b14",
"Reactance (ohms)": 0.34802,
"Susceptance (S)": 5.0150257226433235
}
},
"Contingencies": {
"c1": {
"Affected lines": [
"l1"
]
},
"c2": {
"Affected lines": [
"l2"
]
},
"c3": {
"Affected lines": [
"l3"
]
},
"c4": {
"Affected lines": [
"l4"
]
},
"c5": {
"Affected lines": [
"l5"
]
},
"c6": {
"Affected lines": [
"l6"
]
},
"c7": {
"Affected lines": [
"l7"
]
},
"c8": {
"Affected lines": [
"l8"
]
},
"c9": {
"Affected lines": [
"l9"
]
},
"c10": {
"Affected lines": [
"l10"
]
},
"c11": {
"Affected lines": [
"l11"
]
},
"c12": {
"Affected lines": [
"l12"
]
},
"c13": {
"Affected lines": [
"l13"
]
},
"c15": {
"Affected lines": [
"l15"
]
},
"c16": {
"Affected lines": [
"l16"
]
},
"c17": {
"Affected lines": [
"l17"
]
},
"c18": {
"Affected lines": [
"l18"
]
},
"c19": {
"Affected lines": [
"l19"
]
},
"c20": {
"Affected lines": [
"l20"
]
}
},
"Price-sensitive loads": {
"ps1": {
"Bus": "b3",
"Revenue ($/MW)": 100.0,
"Demand (MW)": 50.0
}
},
"Reserves": {
"r1": {
"Type": "Spinning",
"Amount (MW)": 100.0,
"Shortfall penalty ($/MW)": 1000.0
}
}
}

28
docs/make.jl
Unescape View File

@ -1,16 +1,18 @@
using Documenter, UnitCommitment, JuMP
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"],
function make()
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"],
)
)
)
end

2
docs/src/format.md
Unescape View File

@ -23,7 +23,7 @@ This section describes system-wide parameters, such as power balance penalty, an
| Key | Description | Default | Time series? | Uncertain?
| :----------------------------- | :------------------------------------------------ | :------: | :------------:| :----------:
| `Version` | Version of UnitCommitment.jl this file was written for. Required to ensure that the file remains readable in future versions of the package. If you are following this page to construct the file, this field should equal `0.3`. | Required | No | No
| `Version` | Version of UnitCommitment.jl this file was written for. Required to ensure that the file remains readable in future versions of the package. If you are following this page to construct the file, this field should equal `0.4`. | Required | No | No
| `Time horizon (min)` or `Time horizon (h)` | Length of the planning horizon (in minutes or hours). Either `Time horizon (min)` or `Time horizon (h)` is required, but not both. | Required | No | No
| `Time step (min)` | Length of each time step (in minutes). Must be a divisor of 60 (e.g. 60, 30, 20, 15, etc). | `60` | No | No
| `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` | No | Yes

6
docs/src/index.md
Unescape View File

@ -4,9 +4,9 @@
## 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.
* **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 thermal generator characteristics (including ramping, piecewise-linear production cost curves and time-dependent startup costs), as well as profiled generators, reserves, price-sensitive loads, battery storage, transmission, 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 the deterministic and stochastic 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.
* **Model Implementation**: The package provides a Julia/JuMP implementations of state-of-the-art formulations and solution methods for the deterministic and stochastic 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)), 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)), contingency screening methods ([XavQiuWanThi2019](https://doi.org/10.1109/TPWRS.2019.2892620)) and decomposition methods. 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.
## Table of Contents
@ -35,7 +35,7 @@ Depth = 3
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, Aleksandr M. Kazachkov, Ogün Yurdakul, Feng Qiu**, "UnitCommitment.jl: A Julia/JuMP Optimization Package for Security-Constrained Unit Commitment (Version 0.4)". Zenodo (2022). [DOI: 10.5281/zenodo.4269874](https://doi.org/10.5281/zenodo.4269874).
* **Alinson S. Xavier, Aleksandr M. Kazachkov, Ogün Yurdakul, Jun He, Feng Qiu**, "UnitCommitment.jl: A Julia/JuMP Optimization Package for Security-Constrained Unit Commitment (Version 0.4)". Zenodo (2023). [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).

79
docs/src/usage.md
Unescape View File

@ -10,31 +10,27 @@ UnitCommitment.jl was tested and developed with [Julia 1.9](https://julialang.or
pkg> add UnitCommitment@0.4
```
To solve the optimization models, a mixed-integer linear programming (MILP) solver is also required. Please see the [JuMP installation guide](https://jump.dev/JuMP.jl/stable/installation/) for more instructions on installing a solver. Typical open-source choices are [HiGHS](https://github.com/jump-dev/HiGHS.jl), [Cbc](https://github.com/JuliaOpt/Cbc.jl) and [GLPK](https://github.com/JuliaOpt/GLPK.jl). In the instructions below, Cbc will be used, but any other MILP solver listed in JuMP installation guide should also be compatible.
To solve the optimization models, a mixed-integer linear programming (MILP) solver is also required. Please see the [JuMP installation guide](https://jump.dev/JuMP.jl/stable/installation/) for more instructions on installing a solver. Typical open-source choices are [HiGHS](https://github.com/jump-dev/HiGHS.jl), [Cbc](https://github.com/JuliaOpt/Cbc.jl) and [GLPK](https://github.com/JuliaOpt/GLPK.jl). In the instructions below, HiGHS will be used, but any other MILP solver listed in JuMP installation guide should also be compatible.
Typical Usage
-------------
### Solving user-provided instances
The first step to use UC.jl is to construct JSON files that describe each scenario of your stochastic 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 scenario files; (2) build the optimization model; (3) run the optimization; and (4) extract the optimal solution.
!!! note
> By default, UC.jl uses the extensive form to solve the problem. For a more advanced solution method, see below.
The first step to use UC.jl is to construct JSON files that describe each scenario of your deterministic or stochastic 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 scenario files; (2) build the optimization model; (3) run the optimization; and (4) extract the optimal solution.
```julia
using Cbc
using JSON
using HiGHS
using JuMP
using UnitCommitment
# 1. Read instance
instance = UnitCommitment.read(["/path/to/s1.json", "/path/to/s2.json"])
instance = UnitCommitment.read(["example/s1.json", "example/s2.json"])
# 2. Construct optimization model
model = UnitCommitment.build_model(
instance=instance,
optimizer=Cbc.Optimizer,
optimizer=HiGHS.Optimizer,
)
# 3. Solve model
@ -42,28 +38,39 @@ UnitCommitment.optimize!(model)
# 4. Write solution to a file
solution = UnitCommitment.solution(model)
UnitCommitment.write("/path/to/output.json", solution)
UnitCommitment.write("example/out.json", solution)
```
To read all files in a given folder, the [Glob](https://github.com/vtjnash/Glob.jl) package can be used:
To read multiple files from a given folder, the [Glob](https://github.com/vtjnash/Glob.jl) package can be used:
```julia
```jldoctest usage1; output = false
using Glob
instance = UnitCommitment.read(glob("*.json", "/path/to/scenarios/"))
using UnitCommitment
instance = UnitCommitment.read(glob("s*.json", "example/"))
# output
UnitCommitmentInstance(2 scenarios, 6 thermal units, 0 profiled units, 14 buses, 20 lines, 19 contingencies, 1 price sensitive loads, 4 time steps)
```
To solve deterministic instances, a single scenario file may be provided.
```julia
instance = UnitCommitment.read("/path/to/s1.json")
```jldoctest usage1; output = false
instance = UnitCommitment.read("example/s1.json")
# output
UnitCommitmentInstance(1 scenarios, 6 thermal units, 0 profiled units, 14 buses, 20 lines, 19 contingencies, 1 price sensitive loads, 4 time steps)
```
### Solving benchmark instances
UnitCommitment.jl contains a large number of deterministic 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
```jldoctest usage1; output = false
instance = UnitCommitment.read_benchmark("matpower/case3375wp/2017-02-01")
# output
UnitCommitmentInstance(1 scenarios, 590 thermal units, 0 profiled units, 3374 buses, 4161 lines, 3245 contingencies, 0 price sensitive loads, 36 time steps)
```
## Customizing the formulation
@ -71,7 +78,7 @@ instance = UnitCommitment.read_benchmark("matpower/case3375wp/2017-02-01")
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.
```julia
using Cbc
using HiGHS
using UnitCommitment
import UnitCommitment:
@ -86,7 +93,7 @@ instance = UnitCommitment.read_benchmark(
model = UnitCommitment.build_model(
instance = instance,
optimizer = Cbc.Optimizer,
optimizer = HiGHS.Optimizer,
formulation = Formulation(
pwl_costs = KnuOstWat2018.PwlCosts(),
ramping = MorLatRam2013.Ramping(),
@ -101,24 +108,24 @@ model = UnitCommitment.build_model(
## Generating initial conditions
When creating random unit commitment instances for benchmark purposes, it is often hard to compute, in advance, sensible initial conditions for all generators. Setting initial conditions naively (for example, making all generators initially off and producing no power) can easily cause the instance to become infeasible due to excessive ramping. Initial conditions can also make it hard to modify existing instances. For example, increasing the system load without carefully modifying the initial conditions may make the problem infeasible or unrealistically challenging to solve.
When creating random unit commitment instances for benchmark purposes, it is often hard to compute, in advance, sensible initial conditions for all thermal generators. Setting initial conditions naively (for example, making all generators initially off and producing no power) can easily cause the instance to become infeasible due to excessive ramping. Initial conditions can also make it hard to modify existing instances. For example, increasing the system load without carefully modifying the initial conditions may make the problem infeasible or unrealistically challenging to solve.
To help with this issue, UC.jl provides a utility function which can generate feasible initial conditions by solving a single-period optimization problem, as shown below:
```julia
using Cbc
using HiGHS
using UnitCommitment
# Read original instance
instance = UnitCommitment.read("instance.json")
instance = UnitCommitment.read("example/s1.json")
# Generate initial conditions (in-place)
UnitCommitment.generate_initial_conditions!(instance, Cbc.Optimizer)
UnitCommitment.generate_initial_conditions!(instance, HiGHS.Optimizer)
# Construct and solve optimization model
model = UnitCommitment.build_model(
instance=instance,
optimizer=Cbc.Optimizer,
optimizer=HiGHS.Optimizer,
)
UnitCommitment.optimize!(model)
```
@ -129,20 +136,24 @@ UnitCommitment.optimize!(model)
## Verifying solutions
When developing new formulations, it is very easy to introduce subtle errors in the model that result in incorrect solutions. To help with this, UC.jl includes a utility function that verifies if a given solution is feasible, and, if not, prints all the validation errors it found. The implementation of this function is completely independent from the implementation of the optimization model, and therefore can be used to validate it. The function can also be used to verify solutions produced by other optimization packages, as long as they follow the [UC.jl data format](format.md).
When developing new formulations, it is very easy to introduce subtle errors in the model that result in incorrect solutions. To help avoiding this, UC.jl includes a utility function that verifies if a given solution is feasible, and, if not, prints all the validation errors it found. The implementation of this function is completely independent from the implementation of the optimization model, and therefore can be used to validate it.
```julia
```jldoctest; output = false
using JSON
using UnitCommitment
# Read instance
instance = UnitCommitment.read("instance.json")
instance = UnitCommitment.read("example/s1.json")
# Read solution (potentially produced by other packages)
solution = JSON.parsefile("solution.json")
solution = JSON.parsefile("example/out.json")
# Validate solution and print validation errors
UnitCommitment.validate(instance, solution)
# output
true
```
## Progressive Hedging
@ -155,7 +166,7 @@ The following example shows how to solve SCUC instances using progressive hedgin
```julia
using Cbc
using HiGHS
using MPI
using UnitCommitment
using Glob
@ -167,12 +178,12 @@ MPI.Init()
ph = UnitCommitment.ProgressiveHedging()
# 3. Read problem instance
instance = UnitCommitment.read(["s1.json", "s2.json"], ph)
instance = UnitCommitment.read(["example/s1.json", "example/s2.json"], ph)
# 4. Build JuMP model
model = UnitCommitment.build_model(
instance = instance,
optimizer = Cbc.Optimizer,
optimizer = HiGHS.Optimizer,
)
# 5. Run the decentralized optimization algorithm
@ -185,7 +196,7 @@ solution = UnitCommitment.solution(model, ph)
MPI.Finalize()
```
When using PH, the model can be customized as usual, with a different formulations or additional user-provided constraints. Note that `read`, in this case, takes `ph` as an argument. This allows each Julia process to read only the instance files that are relevant to it. Similarly, the `solution` function gathers the optimal solution of each processes and returns a combined dictionary.
When using PH, the model can be customized as usual, with different formulations or additional user-provided constraints. Note that `read`, in this case, takes `ph` as an argument. This allows each Julia process to read only the instance files that are relevant to it. Similarly, the `solution` function gathers the optimal solution of each processes and returns a combined dictionary.
Each process solves a sub-problem with $\frac{s}{p}$ scenarios, where $s$ is the total number of scenarios and $p$ is the number of MPI processes. For instance, if we have 15 scenario files and 5 processes, then each process will solve a JuMP model that contains data for 3 scenarios. If the total number of scenarios is not divisible by the number of processes, then an error will be thrown.
@ -283,7 +294,9 @@ aelmp = UnitCommitment.compute_lmp(
@show aelmp["s1", "b1", 1]
```
## Time Decomposition Method
## Time Decomposition
Solving unit commitment instances that have long time horizons (for example, year-long 8760-hour instances) requires a substantial amount of computational power. To address this issue, UC.jl offers a time decomposition method, which breaks the instance down into multiple overlapping subproblems, solves them sequentially, then reassembles the solution.
When solving a unit commitment instance with a dense time slot structure, computational complexity can become a significant challenge. For instance, if the instance contains hourly data for an entire year (8760 hours), solving such a model can require a substantial amount of computational power. To address this issue, UC.jl provides a time_decomposition method within the `optimize!` function. This method decomposes the problem into multiple sub-problems, solving them sequentially.

Write Preview
Loading…
Cancel
Save