You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
329 lines
17 KiB
329 lines
17 KiB
<!DOCTYPE html>
|
|
<html lang="en">
|
|
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
|
|
|
|
|
|
<link rel="../img/favicon.ico">
|
|
|
|
|
|
<title>Usage - MIPLearn</title>
|
|
|
|
|
|
<link rel="stylesheet" href="//use.fontawesome.com/releases/v5.5.0/css/all.css" integrity="sha384-B4dIYHKNBt8Bc12p+WXckhzcICo0wtJAoU8YZTY5qE0Id1GSseTk6S+L3BlXeVIU" crossorigin="anonymous">
|
|
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/hack-font@3.3.0/build/web/hack.min.css">
|
|
<link href='//fonts.googleapis.com/css?family=PT+Sans:400,400italic,700,700italic&subset=latin-ext,latin' rel='stylesheet' type='text/css'>
|
|
<link href='//fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,700italic,400,300,600,700&subset=latin-ext,latin' rel='stylesheet' type='text/css'>
|
|
<link href="../css/bootstrap-custom.min.css" rel="stylesheet">
|
|
<link href="../css/base.min.css" rel="stylesheet">
|
|
<link href="../css/cinder.min.css" rel="stylesheet">
|
|
<link href="../css/highlight.min.css" rel="stylesheet">
|
|
|
|
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
|
|
<!--[if lt IE 9]>
|
|
<script src="https://cdn.jsdelivr.net/npm/html5shiv@3.7.3/dist/html5shiv.min.js"></script>
|
|
<script src="https://cdn.jsdelivr.net/npm/respond.js@1.4.2/dest/respond.min.js"></script>
|
|
<![endif]-->
|
|
|
|
<script src="//ajax.googleapis.com/ajax/libs/webfont/1.6.26/webfont.js"></script>
|
|
<script>
|
|
WebFont.load({
|
|
google: {
|
|
families: ['Open Sans', 'PT Sans']
|
|
}
|
|
});
|
|
</script>
|
|
|
|
|
|
|
|
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<div class="navbar navbar-default navbar-fixed-top" role="navigation">
|
|
<div class="container">
|
|
|
|
<!-- Collapsed navigation -->
|
|
<div class="navbar-header">
|
|
<!-- Expander button -->
|
|
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
|
|
<span class="sr-only">Toggle navigation</span>
|
|
<span class="icon-bar"></span>
|
|
<span class="icon-bar"></span>
|
|
<span class="icon-bar"></span>
|
|
</button>
|
|
|
|
|
|
<!-- Main title -->
|
|
|
|
<a class="navbar-brand" href="..">MIPLearn</a>
|
|
</div>
|
|
|
|
<!-- Expanded navigation -->
|
|
<div class="navbar-collapse collapse">
|
|
<!-- Main navigation -->
|
|
<ul class="nav navbar-nav">
|
|
|
|
|
|
<li >
|
|
<a href="..">Home</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li class="active">
|
|
<a href="./">Usage</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li >
|
|
<a href="../benchmark/">Benchmark</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li >
|
|
<a href="../problems/">Problems</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li >
|
|
<a href="../customization/">Customization</a>
|
|
</li>
|
|
|
|
|
|
|
|
<li >
|
|
<a href="../about/">About</a>
|
|
</li>
|
|
|
|
|
|
</ul>
|
|
|
|
<ul class="nav navbar-nav navbar-right">
|
|
<li>
|
|
<a href="#" data-toggle="modal" data-target="#mkdocs_search_modal">
|
|
<i class="fas fa-search"></i> Search
|
|
</a>
|
|
</li>
|
|
<li >
|
|
<a rel="prev" href="..">
|
|
<i class="fas fa-arrow-left"></i> Previous
|
|
</a>
|
|
</li>
|
|
<li >
|
|
<a rel="next" href="../benchmark/">
|
|
Next <i class="fas fa-arrow-right"></i>
|
|
</a>
|
|
</li>
|
|
<li>
|
|
<a href="https://github.com/iSoron/miplearn/edit/master/docs/usage.md"><i class="fab fa-github"></i> Edit on GitHub</a>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="container">
|
|
|
|
|
|
<div class="col-md-3"><div class="bs-sidebar hidden-print affix well" role="complementary">
|
|
<ul class="nav bs-sidenav">
|
|
<li class="first-level active"><a href="#usage">Usage</a></li>
|
|
<li class="second-level"><a href="#installation">Installation</a></li>
|
|
|
|
<li class="second-level"><a href="#using-learningsolver">Using LearningSolver</a></li>
|
|
|
|
<li class="second-level"><a href="#describing-problem-instances">Describing problem instances</a></li>
|
|
|
|
<li class="second-level"><a href="#obtaining-heuristic-solutions">Obtaining heuristic solutions</a></li>
|
|
|
|
<li class="second-level"><a href="#saving-and-loading-solver-state">Saving and loading solver state</a></li>
|
|
|
|
<li class="second-level"><a href="#solving-training-instances-in-parallel">Solving training instances in parallel</a></li>
|
|
|
|
<li class="second-level"><a href="#current-limitations">Current Limitations</a></li>
|
|
|
|
</ul>
|
|
</div></div>
|
|
<div class="col-md-9" role="main">
|
|
|
|
<h1 id="usage">Usage</h1>
|
|
<h3 id="installation">Installation</h3>
|
|
<p>The package is currently available for Python and Pyomo. It can be installed as follows:</p>
|
|
<pre><code class="bash">pip install git+ssh://git@github.com/iSoron/miplearn.git
|
|
</code></pre>
|
|
|
|
<p>A Julia + JuMP version of the package is planned.</p>
|
|
<h3 id="using-learningsolver">Using <code>LearningSolver</code></h3>
|
|
<p>The main class provided by this package is <code>LearningSolver</code>, a reference learning-enhanced MIP solver which automatically extracts information from previous runs to accelerate the solution of new instances. Assuming we already have a list of instances to solve, <code>LearningSolver</code> can be used as follows:</p>
|
|
<pre><code class="python">from miplearn import LearningSolver
|
|
|
|
all_instances = ... # user-provided list of instances to solve
|
|
solver = LearningSolver()
|
|
for instance in all_instances:
|
|
solver.solve(instance)
|
|
solver.fit()
|
|
</code></pre>
|
|
|
|
<p>During the first call to <code>solver.solve(instance)</code>, the solver will process the instance from scratch, since no historical information is available, but it will already start gathering information. By calling <code>solver.fit()</code>, we instruct the solver to train all the internal Machine Learning models based on the information gathered so far. As this operation can be expensive, it may be performed after a larger batch of instances has been solved, instead of after every solve. After the first call to <code>solver.fit()</code>, subsequent calls to <code>solver.solve(instance)</code> will automatically use the trained Machine Learning models to accelerate the solution process.</p>
|
|
<h3 id="describing-problem-instances">Describing problem instances</h3>
|
|
<p>Instances to be solved by <code>LearningSolver</code> must derive from the abstract class <code>miplearn.Instance</code>. The following three abstract methods must be implemented:</p>
|
|
<ul>
|
|
<li><code>instance.to_model()</code>, which returns a concrete Pyomo model corresponding to the instance;</li>
|
|
<li><code>instance.get_instance_features()</code>, which returns a 1-dimensional Numpy array of (numerical) features describing the entire instance;</li>
|
|
<li><code>instance.get_variable_features(var, index)</code>, which returns a 1-dimensional array of (numerical) features describing a particular decision variable.</li>
|
|
</ul>
|
|
<p>The first method is used by <code>LearningSolver</code> to construct a concrete Pyomo model, which will be provided to the internal MIP solver. The user should keep a reference to this Pyomo model, in order to retrieve, for example, the optimal variable values.</p>
|
|
<p>The second and third methods provide an encoding of the instance, which can be used by the ML models to make predictions. In the knapsack problem, for example, an implementation may decide to provide as instance features the average weights, average prices, number of items and the size of the knapsack. The weight and the price of each individual item could be provided as variable features. See <code>miplearn/problems/knapsack.py</code> for a concrete example.</p>
|
|
<p>An optional method which can be implemented is <code>instance.get_variable_category(var, index)</code>, which returns a category (a string, an integer or any hashable type) for each decision variable. If two variables have the same category, <code>LearningSolver</code> will use the same internal ML model to predict the values of both variables. By default, all variables belong to the <code>"default"</code> category, and therefore only one ML model is used for all variables. If the returned category is <code>None</code>, ML predictors will ignore the variable.</p>
|
|
<p>It is not necessary to have a one-to-one correspondence between features and problem instances. One important (and deliberate) limitation of MIPLearn, however, is that <code>get_instance_features()</code> must always return arrays of same length for all relevant instances of the problem. Similarly, <code>get_variable_features(var, index)</code> must also always return arrays of same length for all variables in each category. It is up to the user to decide how to encode variable-length characteristics of the problem into fixed-length vectors. In graph problems, for example, graph embeddings can be used to reduce the (variable-length) lists of nodes and edges into a fixed-length structure that still preserves some properties of the graph. Different instance encodings may have significant impact on performance.</p>
|
|
<h3 id="obtaining-heuristic-solutions">Obtaining heuristic solutions</h3>
|
|
<p>By default, <code>LearningSolver</code> uses Machine Learning to accelerate the MIP solution process, while maintaining all optimality guarantees provided by the MIP solver. In the default mode of operation, for example, predicted optimal solutions are used only as MIP starts.</p>
|
|
<p>For more significant performance benefits, <code>LearningSolver</code> can also be configured to place additional trust in the Machine Learning predictors, by using the <code>mode="heuristic"</code> constructor argument. When operating in this mode, if a ML model is statistically shown (through <em>stratified k-fold cross validation</em>) to have exceptionally high accuracy, the solver may decide to restrict the search space based on its predictions. The parts of the solution which the ML models cannot predict accurately will still be explored using traditional (branch-and-bound) methods. For particular applications, this mode has been shown to quickly produce optimal or near-optimal solutions (see <a href="../about/#references">references</a> and <a href="../benchmark/">benchmark results</a>).</p>
|
|
<div class="admonition danger">
|
|
<p class="admonition-title">Danger</p>
|
|
<p>The <code>heuristic</code> mode provides no optimality guarantees, and therefore should only be used if the solver is first trained on a large and representative set of training instances. Training on a small or non-representative set of instances may produce low-quality solutions, or make the solver incorrectly classify new instances as infeasible.</p>
|
|
</div>
|
|
<h3 id="saving-and-loading-solver-state">Saving and loading solver state</h3>
|
|
<p>After solving a large number of training instances, it may be desirable to save the current state of <code>LearningSolver</code> to disk, so that the solver can still use the acquired knowledge after the application restarts. This can be accomplished by using the methods <code>solver.save_state(filename)</code> and <code>solver.load_state(filename)</code>, as the following example illustrates:</p>
|
|
<pre><code class="python">from miplearn import LearningSolver
|
|
|
|
solver = LearningSolver()
|
|
for instance in some_instances:
|
|
solver.solve(instance)
|
|
solver.fit()
|
|
solver.save_state("/tmp/state.bin")
|
|
|
|
# Application restarts...
|
|
|
|
solver = LearningSolver()
|
|
solver.load_state("/tmp/state.bin")
|
|
for instance in more_instances:
|
|
solver.solve(instance)
|
|
</code></pre>
|
|
|
|
<p>In addition to storing the training data, <code>save_state</code> also stores all trained ML models. Therefore, if the the models were trained before saving the state to disk, it is not necessary to train them again after loading.</p>
|
|
<h3 id="solving-training-instances-in-parallel">Solving training instances in parallel</h3>
|
|
<p>In many situations, training instances can be solved in parallel to accelerate the training process. <code>LearningSolver</code> provides the method <code>parallel_solve(instances)</code> to easily achieve this:</p>
|
|
<pre><code class="python">from miplearn import LearningSolver
|
|
|
|
# Training phase...
|
|
solver = LearningSolver(...) # training solver parameters
|
|
solver.parallel_solve(training_instances, n_jobs=4)
|
|
solver.fit()
|
|
solver.save_state("/tmp/data.bin")
|
|
|
|
# Test phase...
|
|
solver = LearningSolver(...) # test solver parameters
|
|
solver.load_state("/tmp/data.bin")
|
|
solver.solve(test_instance)
|
|
</code></pre>
|
|
|
|
<p>After all training instances have been solved in parallel, the ML models can be trained and saved to disk as usual, using <code>fit</code> and <code>save_state</code>, as explained in the previous subsections.</p>
|
|
<h3 id="current-limitations">Current Limitations</h3>
|
|
<ul>
|
|
<li>Only binary and continuous decision variables are currently supported.</li>
|
|
<li>Solver callbacks (lazy constraints, cutting planes) are not currently supported.</li>
|
|
<li>Only <code>gurobi_persistent</code> is currently fully supported by all solver components. Other solvers may work if some components are disabled.</li>
|
|
</ul></div>
|
|
|
|
|
|
</div>
|
|
|
|
<footer class="col-md-12 text-center">
|
|
|
|
<hr>
|
|
<p>
|
|
<small>Copyright © 2020, UChicago Argonne, LLC. All Rights Reserved.<br></small>
|
|
|
|
<small>Documentation built with <a href="http://www.mkdocs.org/">MkDocs</a>.</p></small>
|
|
|
|
|
|
|
|
</footer>
|
|
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
|
|
<script src="../js/bootstrap-3.0.3.min.js"></script>
|
|
<script src="../js/highlight.pack.js"></script>
|
|
<script>hljs.initHighlightingOnLoad();</script>
|
|
<script>var base_url = ".."</script>
|
|
|
|
<script src="../js/base.js"></script>
|
|
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
|
|
<script src="../js/mathjax.js"></script>
|
|
<script src="../search/main.js"></script>
|
|
|
|
<div class="modal" id="mkdocs_search_modal" tabindex="-1" role="dialog" aria-labelledby="searchModalLabel" aria-hidden="true">
|
|
<div class="modal-dialog modal-lg">
|
|
<div class="modal-content">
|
|
<div class="modal-header">
|
|
<h4 class="modal-title" id="searchModalLabel">Search</h4>
|
|
<button type="button" class="close" data-dismiss="modal"><span aria-hidden="true">×</span><span class="sr-only">Close</span></button>
|
|
</div>
|
|
<div class="modal-body">
|
|
<p>
|
|
From here you can search these documents. Enter
|
|
your search terms below.
|
|
</p>
|
|
<form>
|
|
<div class="form-group">
|
|
<input type="text" class="form-control" placeholder="Search..." id="mkdocs-search-query" title="Type search term here">
|
|
</div>
|
|
</form>
|
|
<div id="mkdocs-search-results"></div>
|
|
</div>
|
|
<div class="modal-footer">
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div><div class="modal" id="mkdocs_keyboard_modal" tabindex="-1" role="dialog" aria-labelledby="keyboardModalLabel" aria-hidden="true">
|
|
<div class="modal-dialog">
|
|
<div class="modal-content">
|
|
<div class="modal-header">
|
|
<h4 class="modal-title" id="keyboardModalLabel">Keyboard Shortcuts</h4>
|
|
<button type="button" class="close" data-dismiss="modal"><span aria-hidden="true">×</span><span class="sr-only">Close</span></button>
|
|
</div>
|
|
<div class="modal-body">
|
|
<table class="table">
|
|
<thead>
|
|
<tr>
|
|
<th style="width: 20%;">Keys</th>
|
|
<th>Action</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td class="help shortcut"><kbd>?</kbd></td>
|
|
<td>Open this help</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="next shortcut"><kbd>n</kbd></td>
|
|
<td>Next page</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="prev shortcut"><kbd>p</kbd></td>
|
|
<td>Previous page</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="search shortcut"><kbd>s</kbd></td>
|
|
<td>Search</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="modal-footer">
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
|
|
</html>
|