Update docs

2025-12-06 09:28:51 -06:00 · 2024-12-10 12:14:36 -06:00
parent 184af2a869
commit 112963c178
37 changed files with 15544 additions and 3662 deletions
--- a/0.4/guide/solvers/index.html
+++ b/0.4/guide/solvers/index.html
@@ -1,10 +1,10 @@
+
 <!DOCTYPE html>

-<html lang="en" data-content_root="../../">
+<html>
  <head>
    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
-
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>9. Learning Solver &#8212; MIPLearn 0.4</title>
    
  <link href="../../_static/css/theme.css" rel="stylesheet" />
@@ -22,21 +22,25 @@
      

    
-    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=362ab14a" />
-    <link rel="stylesheet" type="text/css" href="../../_static/sphinx-book-theme.acff12b8f9c144ce68a297486a2fa670.css?v=b0dfe17c" />
-    <link rel="stylesheet" type="text/css" href="../../_static/nbsphinx-code-cells.css?v=2aa19091" />
-    <link rel="stylesheet" type="text/css" href="../../_static/custom.css?v=f8244a84" />
+    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
+    <link rel="stylesheet" href="../../_static/sphinx-book-theme.acff12b8f9c144ce68a297486a2fa670.css" type="text/css" />
+    <link rel="stylesheet" type="text/css" href="../../_static/nbsphinx-code-cells.css" />
+    <link rel="stylesheet" type="text/css" href="../../_static/nbsphinx-code-cells.css" />
+    <link rel="stylesheet" type="text/css" href="../../_static/nbsphinx-code-cells.css" />
+    <link rel="stylesheet" type="text/css" href="../../_static/nbsphinx-code-cells.css" />
+    <link rel="stylesheet" type="text/css" href="../../_static/nbsphinx-code-cells.css" />
+    <link rel="stylesheet" type="text/css" href="../../_static/custom.css" />
    
  <link rel="preload" as="script" href="../../_static/js/index.1c5a1a01449ed65a7b51.js">

-    <script src="../../_static/documentation_options.js?v=751a5dd3"></script>
-    <script src="../../_static/doctools.js?v=888ff710"></script>
-    <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
+    <script id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
+    <script src="../../_static/jquery.js"></script>
+    <script src="../../_static/underscore.js"></script>
+    <script src="../../_static/doctools.js"></script>
    <script crossorigin="anonymous" integrity="sha256-Ae2Vz/4ePdIu6ZyI/5ZGsYnb+m0JlOmKPjt6XZ9JJkA=" src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>
-    <script src="../../_static/sphinx-book-theme.12a9622fbb08dcb3a2a40b2c02b83a57.js?v=7c4c3336"></script>
+    <script src="../../_static/sphinx-book-theme.12a9622fbb08dcb3a2a40b2c02b83a57.js"></script>
+    <script async="async" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/latest.js?config=TeX-AMS-MML_HTMLorMML"></script>
    <script type="text/x-mathjax-config">MathJax.Hub.Config({"tex2jax": {"inlineMath": [["\\(", "\\)"]], "displayMath": [["\\[", "\\]"]], "processRefs": false, "processEnvironments": false}})</script>
-    <script>window.MathJax = {"tex": {"inlineMath": [["$", "$"], ["\\(", "\\)"]], "processEscapes": true}, "options": {"ignoreHtmlClass": "tex2jax_ignore|mathjax_ignore|document", "processHtmlClass": "tex2jax_process|mathjax_process|math|output_area"}}</script>
-    <script defer="defer" src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
    <link rel="index" title="Index" href="../../genindex/" />
    <link rel="search" title="Search" href="../../search/" />
    <link rel="next" title="10. Benchmark Problems" href="../../api/problems/" />
@@ -68,7 +72,7 @@
  <input type="search" class="form-control" name="q" id="search-input" placeholder="Search the docs ..." aria-label="Search the docs ..." autocomplete="off" >
 </form><nav class="bd-links" id="bd-docs-nav" aria-label="Main navigation">
    <div class="bd-toc-item active">
-        <p class="caption" role="heading">
+        <p class="caption">
 <span class="caption-text">
  Tutorials
 </span>
@@ -95,7 +99,7 @@
  </a>
 </li>
 </ul>
-<p class="caption" role="heading">
+<p class="caption">
 <span class="caption-text">
  User Guide
 </span>
@@ -127,7 +131,7 @@
  </a>
 </li>
 </ul>
-<p class="caption" role="heading">
+<p class="caption">
 <span class="caption-text">
  Python API Reference
 </span>
@@ -251,12 +255,12 @@
        
              <div>
                
-  <section id="Learning-Solver">
-<h1><span class="section-number">9. </span>Learning Solver<a class="headerlink" href="#Learning-Solver" title="Link to this heading">¶</a></h1>
+  <div class="section" id="Learning-Solver">
+<h1><span class="section-number">9. </span>Learning Solver<a class="headerlink" href="#Learning-Solver" title="Permalink to this headline">¶</a></h1>
 <p>On previous pages, we discussed various components of the MIPLearn framework, including training data collectors, feature extractors, and individual machine learning components. In this page, we introduce <strong>LearningSolver</strong>, the main class of the framework which integrates all the aforementioned components into a cohesive whole. Using <strong>LearningSolver</strong> involves three steps: (i) configuring the solver; (ii) training the ML components; and (iii) solving new MIP instances. In the following, we
 describe each of these steps, then conclude with a complete runnable example.</p>
-<section id="Configuring-the-solver">
-<h2><span class="section-number">9.1. </span>Configuring the solver<a class="headerlink" href="#Configuring-the-solver" title="Link to this heading">¶</a></h2>
+<div class="section" id="Configuring-the-solver">
+<h2><span class="section-number">9.1. </span>Configuring the solver<a class="headerlink" href="#Configuring-the-solver" title="Permalink to this headline">¶</a></h2>
 <p><strong>LearningSolver</strong> is composed by multiple individual machine learning components, each targeting a different part of the solution process, or implementing a different machine learning strategy. This architecture allows strategies to be easily enabled, disabled or customized, making the framework flexible. By default, no components are provided and <strong>LearningSolver</strong> is equivalent to a traditional MIP solver. To specify additional components, the <code class="docutils literal notranslate"><span class="pre">components</span></code> constructor argument may be used:</p>
 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">solver</span> <span class="o">=</span> <span class="n">LearningSolver</span><span class="p">(</span>
    <span class="n">components</span><span class="o">=</span><span class="p">[</span>
@@ -268,9 +272,9 @@ describe each of these steps, then conclude with a complete runnable example.</p
 </pre></div>
 </div>
 <p>In this example, three components <code class="docutils literal notranslate"><span class="pre">comp1</span></code>, <code class="docutils literal notranslate"><span class="pre">comp2</span></code> and <code class="docutils literal notranslate"><span class="pre">comp3</span></code> are provided. The strategies implemented by these components are applied sequentially when solving the problem. For example, <code class="docutils literal notranslate"><span class="pre">comp1</span></code> and <code class="docutils literal notranslate"><span class="pre">comp2</span></code> could fix a subset of decision variables, while <code class="docutils literal notranslate"><span class="pre">comp3</span></code> constructs a warm start for the remaining problem.</p>
-</section>
-<section id="Training-and-solving-new-instances">
-<h2><span class="section-number">9.2. </span>Training and solving new instances<a class="headerlink" href="#Training-and-solving-new-instances" title="Link to this heading">¶</a></h2>
+</div>
+<div class="section" id="Training-and-solving-new-instances">
+<h2><span class="section-number">9.2. </span>Training and solving new instances<a class="headerlink" href="#Training-and-solving-new-instances" title="Permalink to this headline">¶</a></h2>
 <p>Once a solver is configured, its ML components need to be trained. This can be achieved by the <code class="docutils literal notranslate"><span class="pre">solver.fit</span></code> method, as illustrated below. The method accepts a list of HDF5 files and trains each individual component sequentially. Once the solver is trained, new instances can be solved using <code class="docutils literal notranslate"><span class="pre">solver.optimize</span></code>. The method returns a dictionary of statistics collected by each component, such as the number of variables fixed.</p>
 <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Build instances</span>
 <span class="n">train_data</span> <span class="o">=</span> <span class="o">...</span>
@@ -290,79 +294,79 @@ describe each of these steps, then conclude with a complete runnable example.</p
 <span class="n">stats</span> <span class="o">=</span> <span class="n">solver</span><span class="o">.</span><span class="n">optimize</span><span class="p">(</span><span class="n">test_data</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">build_model</span><span class="p">)</span>
 </pre></div>
 </div>
-</section>
-<section id="Complete-example">
-<h2><span class="section-number">9.3. </span>Complete example<a class="headerlink" href="#Complete-example" title="Link to this heading">¶</a></h2>
+</div>
+<div class="section" id="Complete-example">
+<h2><span class="section-number">9.3. </span>Complete example<a class="headerlink" href="#Complete-example" title="Permalink to this headline">¶</a></h2>
 <p>In the example below, we illustrate the usage of <strong>LearningSolver</strong> by building instances of the Traveling Salesman Problem, collecting training data, training the ML components, then solving a new instance.</p>
 <div class="nbinput docutils container">
 <div class="prompt highlight-none notranslate"><div class="highlight"><pre><span></span>[1]:
 </pre></div>
 </div>
-<div class="input_area highlight-ipython3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">random</span>
+<div class="input_area highlight-ipython3 notranslate"><div class="highlight"><pre><span></span>import random

-<span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="nn">np</span>
-<span class="kn">from</span> <span class="nn">scipy.stats</span> <span class="kn">import</span> <span class="n">uniform</span><span class="p">,</span> <span class="n">randint</span>
-<span class="kn">from</span> <span class="nn">sklearn.linear_model</span> <span class="kn">import</span> <span class="n">LogisticRegression</span>
+import numpy as np
+from scipy.stats import uniform, randint
+from sklearn.linear_model import LogisticRegression

-<span class="kn">from</span> <span class="nn">miplearn.classifiers.minprob</span> <span class="kn">import</span> <span class="n">MinProbabilityClassifier</span>
-<span class="kn">from</span> <span class="nn">miplearn.classifiers.singleclass</span> <span class="kn">import</span> <span class="n">SingleClassFix</span>
-<span class="kn">from</span> <span class="nn">miplearn.collectors.basic</span> <span class="kn">import</span> <span class="n">BasicCollector</span>
-<span class="kn">from</span> <span class="nn">miplearn.components.primal.actions</span> <span class="kn">import</span> <span class="n">SetWarmStart</span>
-<span class="kn">from</span> <span class="nn">miplearn.components.primal.indep</span> <span class="kn">import</span> <span class="n">IndependentVarsPrimalComponent</span>
-<span class="kn">from</span> <span class="nn">miplearn.extractors.AlvLouWeh2017</span> <span class="kn">import</span> <span class="n">AlvLouWeh2017Extractor</span>
-<span class="kn">from</span> <span class="nn">miplearn.io</span> <span class="kn">import</span> <span class="n">write_pkl_gz</span>
-<span class="kn">from</span> <span class="nn">miplearn.problems.tsp</span> <span class="kn">import</span> <span class="p">(</span>
-    <span class="n">TravelingSalesmanGenerator</span><span class="p">,</span>
-    <span class="n">build_tsp_model_gurobipy</span><span class="p">,</span>
-<span class="p">)</span>
-<span class="kn">from</span> <span class="nn">miplearn.solvers.learning</span> <span class="kn">import</span> <span class="n">LearningSolver</span>
+from miplearn.classifiers.minprob import MinProbabilityClassifier
+from miplearn.classifiers.singleclass import SingleClassFix
+from miplearn.collectors.basic import BasicCollector
+from miplearn.components.primal.actions import SetWarmStart
+from miplearn.components.primal.indep import IndependentVarsPrimalComponent
+from miplearn.extractors.AlvLouWeh2017 import AlvLouWeh2017Extractor
+from miplearn.io import write_pkl_gz
+from miplearn.problems.tsp import (
+    TravelingSalesmanGenerator,
+    build_tsp_model_gurobipy,
+)
+from miplearn.solvers.learning import LearningSolver

-<span class="c1"># Set random seed to make example reproducible.</span>
-<span class="n">random</span><span class="o">.</span><span class="n">seed</span><span class="p">(</span><span class="mi">42</span><span class="p">)</span>
-<span class="n">np</span><span class="o">.</span><span class="n">random</span><span class="o">.</span><span class="n">seed</span><span class="p">(</span><span class="mi">42</span><span class="p">)</span>
+# Set random seed to make example reproducible.
+random.seed(42)
+np.random.seed(42)

-<span class="c1"># Generate a few instances of the traveling salesman problem.</span>
-<span class="n">data</span> <span class="o">=</span> <span class="n">TravelingSalesmanGenerator</span><span class="p">(</span>
-    <span class="n">n</span><span class="o">=</span><span class="n">randint</span><span class="p">(</span><span class="n">low</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span> <span class="n">high</span><span class="o">=</span><span class="mi">11</span><span class="p">),</span>
-    <span class="n">x</span><span class="o">=</span><span class="n">uniform</span><span class="p">(</span><span class="n">loc</span><span class="o">=</span><span class="mf">0.0</span><span class="p">,</span> <span class="n">scale</span><span class="o">=</span><span class="mf">1000.0</span><span class="p">),</span>
-    <span class="n">y</span><span class="o">=</span><span class="n">uniform</span><span class="p">(</span><span class="n">loc</span><span class="o">=</span><span class="mf">0.0</span><span class="p">,</span> <span class="n">scale</span><span class="o">=</span><span class="mf">1000.0</span><span class="p">),</span>
-    <span class="n">gamma</span><span class="o">=</span><span class="n">uniform</span><span class="p">(</span><span class="n">loc</span><span class="o">=</span><span class="mf">0.90</span><span class="p">,</span> <span class="n">scale</span><span class="o">=</span><span class="mf">0.20</span><span class="p">),</span>
-    <span class="n">fix_cities</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
-    <span class="nb">round</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span>
-<span class="p">)</span><span class="o">.</span><span class="n">generate</span><span class="p">(</span><span class="mi">50</span><span class="p">)</span>
+# Generate a few instances of the traveling salesman problem.
+data = TravelingSalesmanGenerator(
+    n=randint(low=10, high=11),
+    x=uniform(loc=0.0, scale=1000.0),
+    y=uniform(loc=0.0, scale=1000.0),
+    gamma=uniform(loc=0.90, scale=0.20),
+    fix_cities=True,
+    round=True,
+).generate(50)

-<span class="c1"># Save instance data to data/tsp/00000.pkl.gz, data/tsp/00001.pkl.gz, ...</span>
-<span class="n">all_data</span> <span class="o">=</span> <span class="n">write_pkl_gz</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="s2">&quot;data/tsp&quot;</span><span class="p">)</span>
+# Save instance data to data/tsp/00000.pkl.gz, data/tsp/00001.pkl.gz, ...
+all_data = write_pkl_gz(data, &quot;data/tsp&quot;)

-<span class="c1"># Split train/test data</span>
-<span class="n">train_data</span> <span class="o">=</span> <span class="n">all_data</span><span class="p">[:</span><span class="mi">40</span><span class="p">]</span>
-<span class="n">test_data</span> <span class="o">=</span> <span class="n">all_data</span><span class="p">[</span><span class="mi">40</span><span class="p">:]</span>
+# Split train/test data
+train_data = all_data[:40]
+test_data = all_data[40:]

-<span class="c1"># Collect training data</span>
-<span class="n">bc</span> <span class="o">=</span> <span class="n">BasicCollector</span><span class="p">()</span>
-<span class="n">bc</span><span class="o">.</span><span class="n">collect</span><span class="p">(</span><span class="n">train_data</span><span class="p">,</span> <span class="n">build_tsp_model_gurobipy</span><span class="p">,</span> <span class="n">n_jobs</span><span class="o">=</span><span class="mi">4</span><span class="p">)</span>
+# Collect training data
+bc = BasicCollector()
+bc.collect(train_data, build_tsp_model_gurobipy, n_jobs=4)

-<span class="c1"># Build learning solver</span>
-<span class="n">solver</span> <span class="o">=</span> <span class="n">LearningSolver</span><span class="p">(</span>
-    <span class="n">components</span><span class="o">=</span><span class="p">[</span>
-        <span class="n">IndependentVarsPrimalComponent</span><span class="p">(</span>
-            <span class="n">base_clf</span><span class="o">=</span><span class="n">SingleClassFix</span><span class="p">(</span>
-                <span class="n">MinProbabilityClassifier</span><span class="p">(</span>
-                    <span class="n">base_clf</span><span class="o">=</span><span class="n">LogisticRegression</span><span class="p">(),</span>
-                    <span class="n">thresholds</span><span class="o">=</span><span class="p">[</span><span class="mf">0.95</span><span class="p">,</span> <span class="mf">0.95</span><span class="p">],</span>
-                <span class="p">),</span>
-            <span class="p">),</span>
-            <span class="n">extractor</span><span class="o">=</span><span class="n">AlvLouWeh2017Extractor</span><span class="p">(),</span>
-            <span class="n">action</span><span class="o">=</span><span class="n">SetWarmStart</span><span class="p">(),</span>
-        <span class="p">)</span>
-    <span class="p">]</span>
-<span class="p">)</span>
+# Build learning solver
+solver = LearningSolver(
+    components=[
+        IndependentVarsPrimalComponent(
+            base_clf=SingleClassFix(
+                MinProbabilityClassifier(
+                    base_clf=LogisticRegression(),
+                    thresholds=[0.95, 0.95],
+                ),
+            ),
+            extractor=AlvLouWeh2017Extractor(),
+            action=SetWarmStart(),
+        )
+    ]
+)

-<span class="c1"># Train ML models</span>
-<span class="n">solver</span><span class="o">.</span><span class="n">fit</span><span class="p">(</span><span class="n">train_data</span><span class="p">)</span>
+# Train ML models
+solver.fit(train_data)

-<span class="c1"># Solve a test instance</span>
-<span class="n">solver</span><span class="o">.</span><span class="n">optimize</span><span class="p">(</span><span class="n">test_data</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">build_tsp_model_gurobipy</span><span class="p">)</span>
+# Solve a test instance
+solver.optimize(test_data[0], build_tsp_model_gurobipy)
 </pre></div>
 </div>
 </div>
@@ -457,8 +461,8 @@ User-callback calls 110, time in user-callback 0.00 sec
 </pre></div>
 </div>
 </div>
-</section>
-</section>
+</div>
+</div>


              </div>