<!doctype html> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <title>Creating a mathematical programming model — DOcplex.MP: Mathematical Programming Modeling for Python V2.16 documentation</title> <link rel="stylesheet" href="_static/bizstyle.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/underscore.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> <script type="text/javascript" src="_static/language_data.js"></script> <script async="async" type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/latest.js?config=TeX-AMS-MML_HTMLorMML"></script> <script type="text/javascript" src="_static/bizstyle.js"></script> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="Examples of mathematical programming" href="samples.html" /> <link rel="prev" title="Setting up an optimization engine" href="getting_started.html" /> <meta name="viewport" content="width=device-width,initial-scale=1.0"> <!--[if lt IE 9]> <script type="text/javascript" src="_static/css3-mediaqueries.js"></script> <![endif]--> </head><body> <div class="related" role="navigation" aria-label="related navigation"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="samples.html" title="Examples of mathematical programming" accesskey="N">next</a> |</li> <li class="right" > <a href="getting_started.html" title="Setting up an optimization engine" accesskey="P">previous</a> |</li> <li class="nav-item nav-item-0"><a href="index.html">DOcplex.MP: Mathematical Programming Modeling for Python V2.16 documentation</a> »</li> </ul> </div> <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebarwrapper"> <h3><a href="index.html">Table of Contents</a></h3> <ul> <li><a class="reference internal" href="#">Creating a mathematical programming model</a><ul> <li><a class="reference internal" href="#define-model-decision-variables">Define model decision variables</a></li> <li><a class="reference internal" href="#build-model-expressions">Build model expressions</a></li> <li><a class="reference internal" href="#aggregated-expressions">Aggregated expressions</a></li> <li><a class="reference internal" href="#building-constraints">Building constraints</a></li> <li><a class="reference internal" href="#build-a-model">Build a model</a><ul> <li><a class="reference internal" href="#import-necessary-modules">Import necessary modules</a></li> <li><a class="reference internal" href="#solving-parameters">Solving parameters</a></li> </ul> </li> <li><a class="reference internal" href="#retrieve-results">Retrieve results</a></li> <li><a class="reference internal" href="#generate-lp-file">Generate LP file</a></li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="getting_started.html" title="previous chapter">Setting up an optimization engine</a></p> <h4>Next topic</h4> <p class="topless"><a href="samples.html" title="next chapter">Examples of mathematical programming</a></p> <div id="searchbox" style="display: none" role="search"> <h3>Quick search</h3> <div class="searchformwrapper"> <form class="search" action="search.html" method="get"> <input type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <div class="section" id="creating-a-mathematical-programming-model"> <h1>Creating a mathematical programming model<a class="headerlink" href="#creating-a-mathematical-programming-model" title="Permalink to this headline">¶</a></h1> <p>Building a model requires:</p> <blockquote> <div><ul class="simple"> <li>defining decision variables and their scopes (what are the possible values for these variables),</li> <li>creating constraints from variables to express interactions between variables and business limitations; only variable values which satisfy the constraints are possible,</li> <li>adding constraints in a model, and</li> <li>defining what is the objective to optimize. The objective is a numerical criterion which is used to rank possible solutions. Mathematical programming algorithms aim to return the best possible solution. This step is optional: if no objective is defined, the algorithm returns one feasible solution.</li> </ul> </div></blockquote> <p>The folder <code class="docutils literal notranslate"><span class="pre">Examples</span></code> contains a set of <a class="reference internal" href="samples.html"><span class="doc">examples</span></a> that can be used as a starting point to create a new model.</p> <p>The mathematical programming elements are implemented in the Python modules located in <code class="docutils literal notranslate"><span class="pre">docplex/mp</span></code>. The factory used to create constraints, manipulate the expressions, and so on is described <a class="reference external" href="docplex.mp.model.html">in the DOcplex.MP reference manual</a>.</p> <div class="section" id="define-model-decision-variables"> <h2>Define model decision variables<a class="headerlink" href="#define-model-decision-variables" title="Permalink to this headline">¶</a></h2> <p>Decision variables are created using factory methods on the <cite>Model</cite> class. The <cite>Model</cite> can create single variables, lists of variables, and dictionaries of variables indexed by business objects. Here is a table of the standard factory methods to create variables:</p> <blockquote> <div><table border="1" class="docutils"> <colgroup> <col width="42%" /> <col width="58%" /> </colgroup> <thead valign="bottom"> <tr class="row-odd"><th class="head">Function</th> <th class="head">Creates</th> </tr> </thead> <tbody valign="top"> <tr class="row-even"><td><em>binary_var()</em></td> <td>Single binary variable</td> </tr> <tr class="row-odd"><td><em>binary_var_list()</em></td> <td>List of binary variables</td> </tr> <tr class="row-even"><td><em>binary_var_dict()</em></td> <td>Dictionary of binary variables</td> </tr> <tr class="row-odd"><td><em>binary_var_matrix()</em></td> <td>Matrix of binary variables</td> </tr> <tr class="row-even"><td><em>integer_var()</em></td> <td>Single integer variable</td> </tr> <tr class="row-odd"><td><em>integer_var_list()</em></td> <td>List of integer variables</td> </tr> <tr class="row-even"><td><em>integer_var_dict()</em></td> <td>Dictionary of integer variables</td> </tr> <tr class="row-odd"><td><em>integer_var_matrix()</em></td> <td>Matrix of integer variables</td> </tr> <tr class="row-even"><td><em>continuous_var()</em></td> <td>Single continuous variable</td> </tr> <tr class="row-odd"><td><em>continuous_var_list()</em></td> <td>List of continuous variables</td> </tr> <tr class="row-even"><td><em>continuous_var_dict()</em></td> <td>Dictionary of continuous variables</td> </tr> <tr class="row-odd"><td><em>continuous_var_matrix()</em></td> <td>Matrix of continuous variables</td> </tr> </tbody> </table> </div></blockquote> <p>There are three types of decision variables according to their scope of possible values: binary variables (0 or 1), integer variables, or continuous variables. The detailed attributes for variables can be found in the class <cite>Var</cite> in the module <a class="reference external" href="docplex.mp.linear.html">linear.py</a>.</p> </div> <div class="section" id="build-model-expressions"> <h2>Build model expressions<a class="headerlink" href="#build-model-expressions" title="Permalink to this headline">¶</a></h2> <p>Constraints in mathematical programming are built with linear combinations of decision variables, sums of elementary expressions of the form <cite>k *x</cite> where <cite>k</cite> is a number and <cite>x</cite> is a variable.</p> <p>Python arithmetic operators (+,-,*,/) are overloaded to create expressions in a simple manner; for example, if <cite>x</cite>, <cite>y</cite>, <cite>z</cite> are decision variables, <cite>3*x+5*y+7*z</cite> is an expression.</p> </div> <div class="section" id="aggregated-expressions"> <h2>Aggregated expressions<a class="headerlink" href="#aggregated-expressions" title="Permalink to this headline">¶</a></h2> <p>DOcplex.MP allows the creation of large expressions over collections of variables by using the <cite>Model.sum</cite> method. Though Python’s built-in <cite>sum()</cite> function can also be used, <cite>Model.sum()</cite> is much faster for building larger expressions. Aggregated expressions can also be used to build constraints.</p> </div> <div class="section" id="building-constraints"> <h2>Building constraints<a class="headerlink" href="#building-constraints" title="Permalink to this headline">¶</a></h2> <p>To simplify the writing of a model, Python comparison operators (==,<=,>=) are also overloaded to compare expressions and build constraints that must be satisfied by the decision variables. For example, <cite>x+y+z == 1</cite> is a constraint that forces the sum of all three variables to be equal to 1.</p> <p>Explicit methods are also available on the model object to ease their creation, such as <em>eq_constraint</em>, <em>le_constraint</em>…</p> </div> <div class="section" id="build-a-model"> <h2>Build a model<a class="headerlink" href="#build-a-model" title="Permalink to this headline">¶</a></h2> <p>The mathematical programming model itself is represented by the class <em>Model</em> implemented in the module <a class="reference external" href="docplex.mp.model.html">model.py</a>.</p> <p>A constraint is added to the model by calling the method <em>add_constraint()</em> with the constraint as the parameter, and, possibly, an optional string argument to name the constraint. A constraint is active only if it has been added to the model.</p> <div class="section" id="import-necessary-modules"> <h3>Import necessary modules<a class="headerlink" href="#import-necessary-modules" title="Permalink to this headline">¶</a></h3> <p>The following is a condensed example of a sudoku problem that uses the default import policy. More comments are available in the files in the directory <code class="docutils literal notranslate"><span class="pre">docplex/mp/examples</span></code>.</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">docplex.mp.model</span> <span class="k">import</span> <span class="n">Model</span> <span class="n">myInput</span> <span class="o">=</span><span class="p">[[</span><span class="mi">8</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">],</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">],</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">9</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">],</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">],</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">],</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">0</span><span class="p">],</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">8</span><span class="p">],</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">],</span> <span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">9</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">]]</span> <span class="n">model</span> <span class="o">=</span> <span class="n">Model</span><span class="p">(</span><span class="s2">"sudoku"</span><span class="p">)</span> <span class="n">R</span> <span class="o">=</span> <span class="nb">range</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">10</span><span class="p">)</span> <span class="n">idx</span> <span class="o">=</span> <span class="p">[(</span><span class="n">i</span><span class="p">,</span> <span class="n">j</span><span class="p">,</span> <span class="n">k</span><span class="p">)</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">R</span> <span class="k">for</span> <span class="n">j</span> <span class="ow">in</span> <span class="n">R</span> <span class="k">for</span> <span class="n">k</span> <span class="ow">in</span> <span class="n">R</span><span class="p">]</span> <span class="n">x</span> <span class="o">=</span> <span class="n">model</span><span class="o">.</span><span class="n">binary_var_dict</span><span class="p">(</span><span class="n">idx</span><span class="p">,</span> <span class="s2">"X"</span><span class="p">)</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">R</span><span class="p">:</span> <span class="k">for</span> <span class="n">j</span> <span class="ow">in</span> <span class="n">R</span><span class="p">:</span> <span class="k">if</span> <span class="n">myInput</span><span class="p">[</span><span class="n">i</span> <span class="o">-</span> <span class="mi">1</span><span class="p">][</span><span class="n">j</span> <span class="o">-</span> <span class="mi">1</span><span class="p">]</span> <span class="o">!=</span> <span class="mi">0</span><span class="p">:</span> <span class="n">model</span><span class="o">.</span><span class="n">add_constraint</span><span class="p">(</span><span class="n">x</span><span class="p">[</span><span class="n">i</span><span class="p">,</span> <span class="n">j</span><span class="p">,</span> <span class="n">myInput</span><span class="p">[</span><span class="n">i</span> <span class="o">-</span> <span class="mi">1</span><span class="p">][</span><span class="n">j</span> <span class="o">-</span> <span class="mi">1</span><span class="p">]]</span> <span class="o">==</span> <span class="mi">1</span><span class="p">)</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">R</span><span class="p">:</span> <span class="k">for</span> <span class="n">j</span> <span class="ow">in</span> <span class="n">R</span><span class="p">:</span> <span class="n">model</span><span class="o">.</span><span class="n">add_constraint</span><span class="p">(</span><span class="n">model</span><span class="o">.</span><span class="n">sum</span><span class="p">(</span><span class="n">x</span><span class="p">[</span><span class="n">i</span><span class="p">,</span> <span class="n">j</span><span class="p">,</span> <span class="n">k</span><span class="p">]</span> <span class="k">for</span> <span class="n">k</span> <span class="ow">in</span> <span class="n">R</span><span class="p">)</span> <span class="o">==</span> <span class="mi">1</span><span class="p">)</span> <span class="k">for</span> <span class="n">j</span> <span class="ow">in</span> <span class="n">R</span><span class="p">:</span> <span class="k">for</span> <span class="n">k</span> <span class="ow">in</span> <span class="n">R</span><span class="p">:</span> <span class="n">model</span><span class="o">.</span><span class="n">add_constraint</span><span class="p">(</span><span class="n">model</span><span class="o">.</span><span class="n">sum</span><span class="p">(</span><span class="n">x</span><span class="p">[</span><span class="n">i</span><span class="p">,</span> <span class="n">j</span><span class="p">,</span> <span class="n">k</span><span class="p">]</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">R</span><span class="p">)</span> <span class="o">==</span> <span class="mi">1</span><span class="p">)</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="n">R</span><span class="p">:</span> <span class="k">for</span> <span class="n">k</span> <span class="ow">in</span> <span class="n">R</span><span class="p">:</span> <span class="n">model</span><span class="o">.</span><span class="n">add_constraint</span><span class="p">(</span><span class="n">model</span><span class="o">.</span><span class="n">sum</span><span class="p">(</span><span class="n">x</span><span class="p">[</span><span class="n">i</span><span class="p">,</span> <span class="n">j</span><span class="p">,</span> <span class="n">k</span><span class="p">]</span> <span class="k">for</span> <span class="n">j</span> <span class="ow">in</span> <span class="n">R</span><span class="p">)</span> <span class="o">==</span> <span class="mi">1</span><span class="p">)</span> <span class="n">solution</span> <span class="o">=</span> <span class="n">model</span><span class="o">.</span><span class="n">solve</span><span class="p">()</span> <span class="n">solution</span><span class="o">.</span><span class="n">print_information</span><span class="p">()</span> </pre></div> </div> <p>The <em>solve()</em> method returns an object of class <a class="reference external" href="docplex.mp.solution.html#docplex.mp.solution.SolveSolution">SolveSolution</a> that contains the result of solving, or None if the model has no solution. This object is described in the section “Retrieve results”.</p> <p>The method <em>print_information()</em> prints a default view of the status of the solve and the values of all variables. The object <em>SolveSolution</em> contains all the necessary accessors to create a customized solution output.</p> </div> <div class="section" id="solving-parameters"> <h3>Solving parameters<a class="headerlink" href="#solving-parameters" title="Permalink to this headline">¶</a></h3> <p>Solving parameters can be adjusted using the “parameters” attribute of the model. Parameters implement a hierarchical tree of attributes reflecting the parameter hierarchy of CPLEX. For example, use <em>model.parameters.mip.tolerances.mip_gap = 0.05</em> to set the MIP gap to 5% before solve.</p> </div> </div> <div class="section" id="retrieve-results"> <h2>Retrieve results<a class="headerlink" href="#retrieve-results" title="Permalink to this headline">¶</a></h2> <p>Results from the solve are returned in a data structure of the class <em>SolveSolution</em>, implemented in the module <cite>SolveSolution</cite>. This object contains:</p> <blockquote> <div><ul class="simple"> <li>global model information, such as status of the search, value of the objective, and</li> <li>the value of each variable</li> </ul> </div></blockquote> <p>Many shortcuts are available to write simpler code.</p> <blockquote> <div><ul class="simple"> <li>As <cite>solve()</cite> returns None if the model has no solution, one can test directly if a solution is present.</li> <li><dl class="first docutils"> <dt>A simplified Python value for each object is directly accessible by using square brackets (<em>msol[vname]</em>). The result is:</dt> <dd><ul class="first last"> <li>an integer for integer variables and</li> <li>a float for continuous variables.</li> </ul> </dd> </dl> </li> </ul> </div></blockquote> <p>The following code is an example of solution printing for the NQueen example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">sys</span> <span class="k">import</span> <span class="n">stdout</span> <span class="k">if</span> <span class="n">msol</span><span class="p">:</span> <span class="n">stdout</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s2">"Solution:"</span><span class="p">)</span> <span class="k">for</span> <span class="n">v</span> <span class="ow">in</span> <span class="n">x</span><span class="p">:</span> <span class="n">stdout</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s2">" "</span> <span class="o">+</span> <span class="nb">str</span><span class="p">(</span><span class="n">msol</span><span class="p">[</span><span class="n">v</span><span class="p">]))</span> <span class="n">stdout</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s2">"</span><span class="se">\n</span><span class="s2">"</span><span class="p">)</span> <span class="k">else</span><span class="p">:</span> <span class="n">stdout</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s2">"Solve status: "</span> <span class="o">+</span> <span class="n">msol</span><span class="o">.</span><span class="n">get_solve_status</span><span class="p">()</span> <span class="o">+</span> <span class="s2">"</span><span class="se">\n</span><span class="s2">"</span><span class="p">)</span> </pre></div> </div> </div> <div class="section" id="generate-lp-file"> <h2>Generate LP file<a class="headerlink" href="#generate-lp-file" title="Permalink to this headline">¶</a></h2> <p>The generation of the LP file corresponding to a model is made available by calling the method <em>export_as_lp()</em>, as demonstrated in the following example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">mdl</span> <span class="o">=</span> <span class="n">Model</span><span class="p">()</span> <span class="o">.</span> <span class="o">.</span> <span class="o">.</span> <span class="o">.</span> <span class="o">.</span> <span class="o"><</span><span class="n">Construction</span> <span class="n">of</span> <span class="n">the</span> <span class="n">model</span><span class="o">></span> <span class="o">.</span> <span class="o">.</span> <span class="o">.</span> <span class="o">.</span> <span class="o">.</span> <span class="n">mdl</span><span class="o">.</span><span class="n">export_as_lp</span><span class="p">()</span> </pre></div> </div> </div> </div> </div> </div> </div> <div class="clearer"></div> </div> <div class="related" role="navigation" aria-label="related navigation"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" >index</a></li> <li class="right" > <a href="py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="samples.html" title="Examples of mathematical programming" >next</a> |</li> <li class="right" > <a href="getting_started.html" title="Setting up an optimization engine" >previous</a> |</li> <li class="nav-item nav-item-0"><a href="index.html">DOcplex.MP: Mathematical Programming Modeling for Python V2.16 documentation</a> »</li> </ul> </div> <div class="footer" role="contentinfo"> © Copyright 2016-2019, IBM®. </div> </body> </html>