parent
3da6f7e08b
commit
5c81be4660
@ -0,0 +1,14 @@
|
||||
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)
|
||||
|
Before Width: | Height: | Size: 35 KiB After Width: | Height: | Size: 35 KiB |
@ -0,0 +1,49 @@
|
||||
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;
|
||||
}
|
||||
@ -0,0 +1,16 @@
|
||||
project = "UnitCommitment.jl"
|
||||
copyright = "2020-2021, UChicago Argonne, LLC"
|
||||
author = ""
|
||||
release = "0.2"
|
||||
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": True,
|
||||
"extra_navbar": "",
|
||||
}
|
||||
html_title = f"UnitCommitment.jl<br/><small>{release}</small>"
|
||||
@ -0,0 +1,182 @@
|
||||
```{sectnum}
|
||||
---
|
||||
start: 3
|
||||
depth: 2
|
||||
suffix: .
|
||||
---
|
||||
```
|
||||
|
||||
# Customization
|
||||
|
||||
## Customizing solver parameters
|
||||
|
||||
### Selecting the internal MIP solver
|
||||
|
||||
By default, `LearningSolver` uses [Gurobi](https://www.gurobi.com/) as its internal MIP solver, and expects models to be provided using the Pyomo modeling language. Supported solvers and modeling languages include:
|
||||
|
||||
* `GurobiPyomoSolver`: Gurobi with Pyomo (default).
|
||||
* `CplexPyomoSolver`: [IBM ILOG CPLEX](https://www.ibm.com/products/ilog-cplex-optimization-studio) with Pyomo.
|
||||
* `XpressPyomoSolver`: [FICO XPRESS Solver](https://www.fico.com/en/products/fico-xpress-solver) with Pyomo.
|
||||
* `GurobiSolver`: Gurobi without any modeling language.
|
||||
|
||||
To switch between solvers, provide the desired class using the `solver` argument:
|
||||
|
||||
```python
|
||||
from miplearn import LearningSolver, CplexPyomoSolver
|
||||
solver = LearningSolver(solver=CplexPyomoSolver)
|
||||
```
|
||||
|
||||
To configure a particular solver, use the `params` constructor argument, as shown below.
|
||||
|
||||
```python
|
||||
from miplearn import LearningSolver, GurobiPyomoSolver
|
||||
solver = LearningSolver(
|
||||
solver=lambda: GurobiPyomoSolver(
|
||||
params={
|
||||
"TimeLimit": 900,
|
||||
"MIPGap": 1e-3,
|
||||
"NodeLimit": 1000,
|
||||
}
|
||||
),
|
||||
)
|
||||
```
|
||||
|
||||
|
||||
## Customizing solver components
|
||||
|
||||
`LearningSolver` is composed by a number of individual machine-learning components, each targeting a different part of the solution process. Each component can be individually enabled, disabled or customized. The following components are enabled by default:
|
||||
|
||||
* `LazyConstraintComponent`: Predicts which lazy constraint to initially enforce.
|
||||
* `ObjectiveValueComponent`: Predicts the optimal value of the optimization problem, given the optimal solution to the LP relaxation.
|
||||
* `PrimalSolutionComponent`: Predicts optimal values for binary decision variables. In heuristic mode, this component fixes the variables to their predicted values. In exact mode, the predicted values are provided to the solver as a (partial) MIP start.
|
||||
|
||||
The following components are also available, but not enabled by default:
|
||||
|
||||
* `BranchPriorityComponent`: Predicts good branch priorities for decision variables.
|
||||
|
||||
### Selecting components
|
||||
|
||||
To create a `LearningSolver` with a specific set of components, the `components` constructor argument may be used, as the next example shows:
|
||||
|
||||
```python
|
||||
# Create a solver without any components
|
||||
solver1 = LearningSolver(components=[])
|
||||
|
||||
# Create a solver with only two components
|
||||
solver2 = LearningSolver(components=[
|
||||
LazyConstraintComponent(...),
|
||||
PrimalSolutionComponent(...),
|
||||
])
|
||||
```
|
||||
|
||||
### Adjusting component aggressiveness
|
||||
|
||||
The aggressiveness of classification components, such as `PrimalSolutionComponent` and `LazyConstraintComponent`, can be adjusted through the `threshold` constructor argument. Internally, these components ask the machine learning models how confident are they on each prediction they make, then automatically discard all predictions that have low confidence. The `threshold` argument specifies how confident should the ML models be for a prediction to be considered trustworthy. Lowering a component's threshold increases its aggressiveness, while raising a component's threshold makes it more conservative.
|
||||
|
||||
For example, if the ML model predicts that a certain binary variable will assume value `1.0` in the optimal solution with 75% confidence, and if the `PrimalSolutionComponent` is configured to discard all predictions with less than 90% confidence, then this variable will not be included in the predicted MIP start.
|
||||
|
||||
MIPLearn currently provides two types of thresholds:
|
||||
|
||||
* `MinProbabilityThreshold(p: List[float])` A threshold which indicates that a prediction is trustworthy if its probability of being correct, as computed by the machine learning model, is above a fixed value.
|
||||
* `MinPrecisionThreshold(p: List[float])` A dynamic threshold which automatically adjusts itself during training to ensure that the component achieves at least a given precision on the training data set. Note that increasing a component's precision may reduce its recall.
|
||||
|
||||
The example below shows how to build a `PrimalSolutionComponent` which fixes variables to zero with at least 80% precision, and to one with at least 95% precision. Other components are configured similarly.
|
||||
|
||||
```python
|
||||
from miplearn import PrimalSolutionComponent, MinPrecisionThreshold
|
||||
|
||||
PrimalSolutionComponent(
|
||||
mode="heuristic",
|
||||
threshold=MinPrecisionThreshold([0.80, 0.95]),
|
||||
)
|
||||
```
|
||||
|
||||
### Evaluating component performance
|
||||
|
||||
MIPLearn allows solver components to be modified, trained and evaluated in isolation. In the following example, we build and
|
||||
fit `PrimalSolutionComponent` outside the solver, then evaluate its performance.
|
||||
|
||||
```python
|
||||
from miplearn import PrimalSolutionComponent
|
||||
|
||||
# User-provided set of previously-solved instances
|
||||
train_instances = [...]
|
||||
|
||||
# Construct and fit component on a subset of training instances
|
||||
comp = PrimalSolutionComponent()
|
||||
comp.fit(train_instances[:100])
|
||||
|
||||
# Evaluate performance on an additional set of training instances
|
||||
ev = comp.evaluate(train_instances[100:150])
|
||||
```
|
||||
|
||||
The method `evaluate` returns a dictionary with performance evaluation statistics for each training instance provided,
|
||||
and for each type of prediction the component makes. To obtain a summary across all instances, pandas may be used, as below:
|
||||
|
||||
```python
|
||||
import pandas as pd
|
||||
pd.DataFrame(ev["Fix one"]).mean(axis=1)
|
||||
```
|
||||
```text
|
||||
Predicted positive 3.120000
|
||||
Predicted negative 196.880000
|
||||
Condition positive 62.500000
|
||||
Condition negative 137.500000
|
||||
True positive 3.060000
|
||||
True negative 137.440000
|
||||
False positive 0.060000
|
||||
False negative 59.440000
|
||||
Accuracy 0.702500
|
||||
F1 score 0.093050
|
||||
Recall 0.048921
|
||||
Precision 0.981667
|
||||
Predicted positive (%) 1.560000
|
||||
Predicted negative (%) 98.440000
|
||||
Condition positive (%) 31.250000
|
||||
Condition negative (%) 68.750000
|
||||
True positive (%) 1.530000
|
||||
True negative (%) 68.720000
|
||||
False positive (%) 0.030000
|
||||
False negative (%) 29.720000
|
||||
dtype: float64
|
||||
```
|
||||
|
||||
Regression components (such as `ObjectiveValueComponent`) can also be trained and evaluated similarly,
|
||||
as the next example shows:
|
||||
|
||||
```python
|
||||
from miplearn import ObjectiveValueComponent
|
||||
comp = ObjectiveValueComponent()
|
||||
comp.fit(train_instances[:100])
|
||||
ev = comp.evaluate(train_instances[100:150])
|
||||
|
||||
import pandas as pd
|
||||
pd.DataFrame(ev).mean(axis=1)
|
||||
```
|
||||
```text
|
||||
Mean squared error 7001.977827
|
||||
Explained variance 0.519790
|
||||
Max error 242.375804
|
||||
Mean absolute error 65.843924
|
||||
R2 0.517612
|
||||
Median absolute error 65.843924
|
||||
dtype: float64
|
||||
```
|
||||
|
||||
### Using customized ML classifiers and regressors
|
||||
|
||||
By default, given a training set of instantes, MIPLearn trains a fixed set of ML classifiers and regressors, then selects the best one based on cross-validation performance. Alternatively, the user may specify which ML model a component should use through the `classifier` or `regressor` contructor parameters. Scikit-learn classifiers and regressors are currently supported. A future version of the package will add compatibility with Keras models.
|
||||
|
||||
The example below shows how to construct a `PrimalSolutionComponent` which internally uses scikit-learn's `KNeighborsClassifiers`. Any other scikit-learn classifier or pipeline can be used. It needs to be wrapped in `ScikitLearnClassifier` to ensure that all the proper data transformations are applied.
|
||||
|
||||
```python
|
||||
from miplearn import PrimalSolutionComponent, ScikitLearnClassifier
|
||||
from sklearn.neighbors import KNeighborsClassifier
|
||||
|
||||
comp = PrimalSolutionComponent(
|
||||
classifier=ScikitLearnClassifier(
|
||||
KNeighborsClassifier(n_neighbors=5),
|
||||
),
|
||||
)
|
||||
comp.fit(train_instances)
|
||||
```
|
||||
@ -0,0 +1,72 @@
|
||||
# UnitCommitment.jl
|
||||
|
||||
**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
|
||||
|
||||
* **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 Tools:** The package provides automated benchmark scripts to accurately evaluate the performance impact of proposed code changes.
|
||||
|
||||
### Authors
|
||||
* **Alinson Santos Xavier** (Argonne National Laboratory)
|
||||
* **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.
|
||||
|
||||
* 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
|
||||
|
||||
* Based upon work supported by the **U.S. Department of Energy Advanced Grid Modeling Program** under Grant DE-OE0000875.
|
||||
|
||||
### Citing
|
||||
|
||||
If you use UnitCommitment.jl in your research (that is, if you use either the provided instances files, the mathematical models, or the 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).
|
||||
|
||||
If you use the instances, we additionally request that you cite the original sources, as described in the [instances page](instances.md).
|
||||
|
||||
### License
|
||||
|
||||
```text
|
||||
UnitCommitment.jl: A Julia/JuMP Optimization Package for Security-Constrained Unit Commitment
|
||||
Copyright © 2020, 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.
|
||||
```
|
||||
|
||||
## Site contents
|
||||
|
||||
```{toctree}
|
||||
---
|
||||
maxdepth: 2
|
||||
---
|
||||
usage.md
|
||||
format.md
|
||||
instances.md
|
||||
about.md
|
||||
```
|
||||
|
||||
@ -1,26 +0,0 @@
|
||||
site_name: UnitCommitment.jl
|
||||
theme:
|
||||
name: cinder
|
||||
hljs_languages:
|
||||
- julia
|
||||
copyright: "Copyright © 2020, UChicago Argonne, LLC. All Rights Reserved."
|
||||
repo_url: https://github.com/ANL-CEEESA/unitcommitment.jl
|
||||
edit_uri: edit/dev/src/docs/
|
||||
nav:
|
||||
- Home: index.md
|
||||
- Usage: usage.md
|
||||
- Format: format.md
|
||||
- Instances: instances.md
|
||||
plugins:
|
||||
- search
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
- mdx_math
|
||||
- fenced_code
|
||||
extra_javascript:
|
||||
- https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML
|
||||
- js/mathjax.js
|
||||
docs_dir: src/docs
|
||||
site_dir: docs
|
||||
extra_css:
|
||||
- "css/custom.css"
|
||||
@ -1,28 +0,0 @@
|
||||
.navbar-default {
|
||||
border-bottom: 0px;
|
||||
background-color: #fff;
|
||||
box-shadow: 0px 0px 15px rgba(0, 0, 0, 0.2);
|
||||
}
|
||||
|
||||
a, .navbar-default a {
|
||||
color: #06a !important;
|
||||
font-weight: normal;
|
||||
}
|
||||
|
||||
.disabled > a {
|
||||
color: #999 !important;
|
||||
}
|
||||
|
||||
.navbar-default a:hover,
|
||||
.navbar-default .active,
|
||||
.active > a {
|
||||
background-color: #f0f0f0 !important;
|
||||
}
|
||||
|
||||
.icon-bar {
|
||||
background-color: #666 !important;
|
||||
}
|
||||
|
||||
.navbar-collapse {
|
||||
border-color: #fff !important;
|
||||
}
|
||||
File diff suppressed because one or more lines are too long
@ -1,42 +0,0 @@
|
||||
# UnitCommitment.jl
|
||||
|
||||
**UnitCommitment.jl** (UC.jl) is a Julia 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
|
||||
|
||||
* **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 Tools:** The package provides automated benchmark scripts to accurately evaluate the performance impact of proposed code changes.
|
||||
|
||||
### Documentation
|
||||
|
||||
* [Usage](usage.md)
|
||||
* [Data Format](format.md)
|
||||
* [Instances](instances.md)
|
||||
|
||||
### Source code
|
||||
|
||||
* [https://github.com/ANL-CEEESA/unitcommitment.jl](https://github.com/ANL-CEEESA/unitcommitment.jl)
|
||||
|
||||
### Authors
|
||||
* **Alinson Santos Xavier** (Argonne National Laboratory)
|
||||
* **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.
|
||||
|
||||
* 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
|
||||
|
||||
If you use UnitCommitment.jl in your research, we 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).
|
||||
|
||||
If you make use of the provided instances files, we request that you additionally cite the original sources, as described in the [instances page](instances.md).
|
||||
|
||||
### License
|
||||
|
||||
Released under the modified BSD license. See `LICENSE.md` for more details.
|
||||
@ -1,8 +0,0 @@
|
||||
MathJax.Hub.Config({
|
||||
"tex2jax": { inlineMath: [ [ '$', '$' ] ] }
|
||||
});
|
||||
MathJax.Hub.Config({
|
||||
config: ["MMLorHTML.js"],
|
||||
jax: ["input/TeX", "output/HTML-CSS", "output/NativeMML"],
|
||||
extensions: ["MathMenu.js", "MathZoom.js"]
|
||||
});
|
||||
Loading…
Reference in new issue