MIPLearn v0.3

Author: iSoron

Diff for: .github/ISSUE_TEMPLATE/bug_report.md

@@ -1,5 +1,3 @@
-*.h5
-*.jld2
 TODO.md
 .idea
 *.gz
@@ -80,6 +78,8 @@ wheels/
 notebooks/
 .vscode
 tmp
-benchmark/tsp
-benchmark/stab
-benchmark/knapsack
+benchmark/data
+benchmark/results
+**/*.xz
+**/*.h5
+**/*.jld2

Diff for: .github/ISSUE_TEMPLATE/config.yml

@@ -4,4 +4,4 @@ disallow_untyped_defs = True
 disallow_untyped_calls = True
 disallow_incomplete_defs = True
 pretty = True
-no_implicit_optional = True
+no_implicit_optional = True

Diff for: .github/workflows/lint.yml

@@ -0,0 +1,27 @@
+{
+    "creators": [
+        {
+            "orcid": "0000-0002-5022-9802",
+            "affiliation": "Argonne National Laboratory",
+            "name": "Santos Xavier, Alinson"
+        },
+        {
+            "affiliation": "Argonne National Laboratory",
+            "name": "Qiu, Feng"
+        },
+        {
+            "affiliation": "Georgia Institute of Technology",
+            "name": "Gu, Xiaoyi"
+        },
+        {
+            "affiliation": "Georgia Institute of Technology",
+            "name": "Becu, Berkay"
+        },
+        {
+            "affiliation": "Georgia Institute of Technology",
+            "name": "Dey, Santanu S."
+        }
+    ],
+    "title": "MIPLearn: An Extensible Framework for Learning-Enhanced Optimization",
+    "description": "<b>MIPLearn</b> is an extensible framework for solving discrete optimization problems using a combination of Mixed-Integer Linear Programming (MIP) and Machine Learning (ML). MIPLearn uses ML methods to automatically identify patterns in previously solved instances of the problem, then uses these patterns to accelerate the performance of conventional state-of-the-art MIP solvers such as CPLEX, Gurobi or XPRESS."
+}

Diff for: .github/workflows/test.yml

@@ -1,45 +1,34 @@
-# MIPLearn: Changelog
+# Changelog
 
-## [0.2.0] - [Unreleased]
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.0] - 2023-06-08
+
+This is a complete rewrite of the original prototype package, with an entirely new API, focused on performance, scalability and flexibility.
 
 ### Added
 
-- **Added two new machine learning components:**
-  - Added `StaticLazyConstraintComponent`, which allows the user to mark some constraints in the formulation as lazy, instead of constructing them in a callback. ML predicts which static lazy constraints should be kept in the formulation, and which should be removed. 
-  - Added `UserCutComponents`, which predicts which user cuts should be generated and added to the formulation as constraints ahead-of-time, before solving the MIP.
-- **Added support to additional MILP solvers:**
-  - Added support for CPLEX and XPRESS, through the Pyomo modeling language, in addition to (existing) Gurobi. The solver classes are named `CplexPyomoSolver`, `XpressPyomoSolver` and `GurobiPyomoSolver`.
-  - Added support for Gurobi without any modeling language. The solver class is named `GurobiSolver`. In this case, `instance.to_model` should return ` gp.Model` object.
-  - Added support to direct MPS files, produced externally, through the `GurobiSolver` class mentioned above.
-- **Added dynamic thresholds:** 
-  - In previous versions of the package, it was necessary to manually adjust component aggressiveness to reach a desired precision/recall. This can now be done automatically with `MinProbabilityThreshold`, `MinPrecisionThreshold` and `MinRecallThreshold`.
-- **Reduced memory requirements:**
-  - Previous versions of the package required all training instances to be kept in memory at all times, which was prohibitive for large-scale problems. It is now possible to store instances in file until they are needed, using `PickledGzInstance`.
-- **Refactoring:**
-  - Added static types to all classes (with mypy).
+- Add support for Python/Gurobipy and Julia/JuMP, in addition to the existing Python/Pyomo interface.
+- Add six new random instance generators (bin packing, capacitated p-median, set cover, set packing, unit commitment, vertex cover), in addition to the three existing generators (multiknapsack, stable set, tsp).
+- Collect some additional raw training data (e.g. basis status, reduced costs, etc)
+- Add new primal solution ML strategies (memorizing, independent vars and joint vars)
+- Add new primal solution actions (set warm start, fix variables, enforce proximity)
+- Add runnable tutorials and user guides to the documentation.
 
 ### Changed
 
-- Variables are now referenced by their names, instead of tuples `(var_name, index)`. This change was required to improve the compatibility with modeling languages other than Pyomo, which do not follow this convention. For performance reasons, the functions `get_variable_features` and `get_variable_categories` should now return a dictionary containing categories and features for all relevant variables. Previously, MIPLearn had to perform two function calls per variable, which was too slow for very large models.
-- Internal solvers must now be specified as objects, instead of strings. For example,
-  ```python
-  solver = LearningSolver(
-      solver=GurobiPyomoSolver(
-          params={
-              "TimeLimit": 300,
-              "Threads": 4,
-          }      
-      )
-  )
-  ```
-- `LazyConstraintComponent` has been renamed to `DynamicLazyConstraintsComponent`.
-- Categories, lazy constraints and cutting plane identifiers must now be strings, instead `Hashable`. This change was required for compatibility with HDF5 data format.
+- To support large-scale problems and datasets, switch from an in-memory architecture to a file-based architecture, using HDF5 files.
+- To accelerate development cycle, split training data collection from feature extraction.
 
 ### Removed
 
-- Temporarily removed the experimental `BranchPriorityComponent`. This component will be re-added in the Julia version of the package.
-- Removed `solver.add` method, previously used to add components to an existing solver. Use the constructor `LearningSolver(components=[...])` instead.
+- Temporarily remove ML strategies for lazy constraints
+- Remove benchmarks from documentation. These will be published in a separate paper.
+
 
 ## [0.1.0] - 2020-11-23
 
-- Initial public release
+- Initial public release

Diff for: .gitignore

@@ -22,4 +22,4 @@ DISCLAIMER
 
 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.
 
-********************************************************************************
+********************************************************************************

Diff for: .mypy.ini

@@ -2,8 +2,8 @@ PYTHON      := python3
 PYTEST      := pytest
 PIP         := $(PYTHON) -m pip
 MYPY        := $(PYTHON) -m mypy
-PYTEST_ARGS := -W ignore::DeprecationWarning -vv --log-level=DEBUG tests
-VERSION     := 0.2
+PYTEST_ARGS := -W ignore::DeprecationWarning -vv --log-level=DEBUG
+VERSION     := 0.3
 
 all: docs test
 
@@ -24,11 +24,8 @@ docs:
 	cd docs; make clean; make dirhtml
 	rsync -avP --delete-after docs/_build/dirhtml/ ../docs/$(VERSION)
 
-
 install-deps:
 	$(PIP) install --upgrade pip
-	$(PIP) install --upgrade -i https://pypi.gurobi.com 'gurobipy>=9.5,<9.6'
-	$(PIP) install --upgrade xpress
 	$(PIP) install --upgrade -r requirements.txt
 
 install:
@@ -41,9 +38,11 @@ reformat:
 	$(PYTHON) -m black .
 
 test:
+	# pyflakes miplearn tests
+	black --check .
 	# rm -rf .mypy_cache
-	# $(MYPY) -p miplearn
-	# $(MYPY) -p tests
+	$(MYPY) -p miplearn
+	$(MYPY) -p tests
 	$(PYTEST) $(PYTEST_ARGS) 
 
 .PHONY: test test-watch docs install dist

Diff for: .pre-commit-config.yaml

@@ -14,36 +14,51 @@
   </a>
 </p>
 
-**MIPLearn** is an extensible framework for solving discrete optimization problems using a combination of Mixed-Integer Linear Programming (MIP) and Machine Learning (ML).
+**MIPLearn** is an extensible framework for solving discrete optimization problems using a combination of Mixed-Integer Linear Programming (MIP) and Machine Learning (ML). MIPLearn uses ML methods to automatically identify patterns in previously solved instances of the problem, then uses these patterns to accelerate the performance of conventional state-of-the-art MIP solvers such as CPLEX, Gurobi or XPRESS.
 
-MIPLearn uses ML methods to automatically identify patterns in previously solved instances of the problem, then uses these patterns to accelerate the performance of conventional state-of-the-art MIP solvers such as CPLEX, Gurobi or XPRESS. Unlike pure ML methods, MIPLearn is not only able to find high-quality solutions to discrete optimization problems, but it can also prove the optimality and feasibility of these solutions. Unlike conventional MIP solvers, MIPLearn can take full advantage of very specific observations that happen to be true in a particular family of instances (such as the observation that a particular constraint is typically redundant, or that a particular variable typically assumes a certain value). For certain classes of problems, this approach has been shown to provide significant performance benefits (see [benchmarks](https://anl-ceeesa.github.io/MIPLearn/0.1/problems/) and [references](https://anl-ceeesa.github.io/MIPLearn/0.1/about/)).
-
-Features
---------
-* **MIPLearn proposes a flexible problem specification format,** which allows users to describe their particular optimization problems to a Learning-Enhanced MIP solver, both from the MIP perspective and from the ML perspective, without making any assumptions on the problem being modeled, the mathematical formulation of the problem, or ML encoding.
-
-* **MIPLearn provides a reference implementation of a *Learning-Enhanced Solver*,** which can use the above problem specification format to automatically predict, based on previously solved instances, a number of hints to accelerate MIP performance. 
-
-* **MIPLearn provides a set of benchmark problems and random instance generators,** covering applications from different domains, which can be used to quickly evaluate new learning-enhanced MIP techniques in a measurable and reproducible way.
-
-* **MIPLearn is customizable and extensible**. For MIP and ML researchers exploring new techniques to accelerate MIP performance based on historical data, each component of the reference solver can be individually replaced, extended or customized.
+Unlike pure ML methods, MIPLearn is not only able to find high-quality solutions to discrete optimization problems, but it can also prove the optimality and feasibility of these solutions. Unlike conventional MIP solvers, MIPLearn can take full advantage of very specific observations that happen to be true in a particular family of instances (such as the observation that a particular constraint is typically redundant, or that a particular variable typically assumes a certain value). For certain classes of problems, this approach may provide significant performance benefits.
 
 Documentation
 -------------
 
-For installation instructions, basic usage and benchmarks results, see the [official documentation](https://anl-ceeesa.github.io/MIPLearn/).
+- Tutorials:
+    1. [Getting started (Pyomo)](https://anl-ceeesa.github.io/MIPLearn/0.3/tutorials/getting-started-pyomo/)
+    2. [Getting started (Gurobipy)](https://anl-ceeesa.github.io/MIPLearn/0.3/tutorials/getting-started-gurobipy/)
+    3. [Getting started (JuMP)](https://anl-ceeesa.github.io/MIPLearn/0.3/tutorials/getting-started-jump/)
+- User Guide
+    1. [Benchmark problems](https://anl-ceeesa.github.io/MIPLearn/0.3/guide/problems/)
+    2. [Training data collectors](https://anl-ceeesa.github.io/MIPLearn/0.3/guide/collectors/)
+    3. [Feature extractors](https://anl-ceeesa.github.io/MIPLearn/0.3/guide/features/)
+    4. [Primal components](https://anl-ceeesa.github.io/MIPLearn/0.3/guide/primal/)
+    5. [Learning solver](https://anl-ceeesa.github.io/MIPLearn/0.3/guide/solvers/)
+- Python API Reference
+    1. [Benchmark problems](https://anl-ceeesa.github.io/MIPLearn/0.3/api/problems/)
+    2. [Collectors & extractors](https://anl-ceeesa.github.io/MIPLearn/0.3/api/collectors/)
+    3. [Components](https://anl-ceeesa.github.io/MIPLearn/0.3/api/components/)
+    4. [Solvers](https://anl-ceeesa.github.io/MIPLearn/0.3/api/solvers/)
+    5. [Helpers](https://anl-ceeesa.github.io/MIPLearn/0.3/api/helpers/)
+
+Authors
+-------
+
+- **Alinson S. Xavier** (Argonne National Laboratory)
+- **Feng Qiu** (Argonne National Laboratory)
+- **Xiaoyi Gu** (Georgia Institute of Technology)
+- **Berkay Becu** (Georgia Institute of Technology)
+- **Santanu S. Dey**  (Georgia Institute of Technology)
+
 
 Acknowledgments
 ---------------
-* 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.
+* 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.
+* Based upon work supported by the **U.S. Department of Energy Advanced Grid Modeling Program**.
 
 Citing MIPLearn
 ---------------
 
 If you use MIPLearn in your research (either the solver or the included problem generators), we kindly request that you cite the package as follows:
 
-* **Alinson S. Xavier, Feng Qiu.** *MIPLearn: An Extensible Framework for Learning-Enhanced Optimization*. Zenodo (2020). DOI: [10.5281/zenodo.4287567](https://doi.org/10.5281/zenodo.4287567)
+* **Alinson S. Xavier, Feng Qiu, Xiaoyi Gu, Berkay Becu, Santanu S. Dey.** *MIPLearn: An Extensible Framework for Learning-Enhanced Optimization (Version 0.3)*. Zenodo (2023). DOI: [10.5281/zenodo.4287567](https://doi.org/10.5281/zenodo.4287567)
 
 If you use MIPLearn in the field of power systems optimization, we kindly request that you cite the reference below, in which the main techniques implemented in MIPLearn were first developed:
 

Diff for: .zenodo.json

@@ -1,8 +1,14 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
 
+# Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)