Files
ortools-clone/documentation/user_manual/index.html
nikolaj.van.omme@gmail.com 7fc4c48e28 Doc automatic update
2015-02-10 19:24:05 +00:00

451 lines
24 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Foreword &mdash; or-tools User&#39;s Manual</title>
<link rel="stylesheet" href="_static/default.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: 'doc version 0.0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: false
};
</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>
<link rel="shortcut icon" href="_static/logo.ico"/>
<link rel="top" title="or-tools User&#39;s Manual" href="#" />
<link rel="next" title="1. Introduction to constraint programming" href="manual/introduction.html" />
</head>
<body>
<div class="related">
<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="manual/introduction.html" title="1. Introduction to constraint programming"
accesskey="N">next</a> |</li>
<li><a href="#">or-tools User&#39;s Manual</a> &raquo;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="foreword">
<h1>Foreword</h1>
<p>We are glad to welcome you to the <strong>or-tools users manual</strong>. In this foreword, we try to answer
most common questions a newcomer could have when discovering this manual or the library for
the first time.</p>
<p>The <strong>or-tools</strong> library is a set of <strong>o</strong>perations <strong>r</strong>esearch <strong>tools</strong> developed at Google.
If you have no idea
what <a class="reference external" href="http://en.wikipedia.org/wiki/Operations_research">operations research</a> is, you still can use our
library to solve common small problems with
the help of our <a class="reference external" href="http://en.wikipedia.org/wiki/Constraint_programming">Constraint Programming</a> (CP) solver.
If you do know what operations research
is and how difficult it is sometimes to find efficient, easy to use and open source code, we hope
you will enjoy using our library. We have put a lot of efforts in order to make it user friendly and
continue to improve it on a daily basis. Furthermore, we encourage interactivity and are always
open to suggestions. See the section <a class="reference internal" href="#how-to-reach-us">How to reach us?</a> below. If you have comments about this
manual or the documentation in general, see the section <a class="reference internal" href="#do-you-have-comments">Do you have comments?</a>.</p>
<div class="sidebar">
<p class="first sidebar-title">Content at a glance</p>
<p>This manual is divided in four parts:</p>
<ul>
<li><p class="first">Part I: Basics</p>
<p>
<a class="reference internal" href="manual/introduction.html"><em>1. Introduction to CP</em></a><br>
<a class="reference internal" href="manual/first_steps.html"><em>2. First steps with or-tools</em></a><br>
<a class="reference internal" href="manual/objectives.html"><em>3. Using objectives</em></a><br>
<a class="reference internal" href="manual/reification.html"><em>4. Reification</em></a><br>
</p></li>
<li><p class="first">Part II: Customization</p>
<p>
<a class="reference internal" href="manual/search_primitives.html"><em>5. Search primitives</em></a><br>
<a class="reference internal" href="manual/LS.html"><em>6. Local Search</em></a><br>
<a class="reference internal" href="manual/metaheuristics.html"><em>7. Meta-heuristics</em></a><br>
<a class="reference internal" href="manual/custom_constraints.html"><em>8. Custom constraints</em></a>
</p></li>
<li><p class="first">Part III: Routing</p>
<p>
<a class="reference internal" href="manual/TSP.html"><em>9. TSP with constraints</em></a><br>
<a class="reference internal" href="manual/VRP.html"><em>10. VRP with constraints</em></a><br>
</p></li>
<li><p class="first">Part IV: Technicalities</p>
<p>
<a class="reference internal" href="manual/utilities.html"><em>11. Utilities</em></a><br>
<a class="reference internal" href="manual/modeling_tricks.html"><em>12. Modeling tricks</em></a><br>
<a class="reference internal" href="manual/under_the_hood.html"><em>13. Under the hood</em></a>
</p></li>
</ul>
<blockquote class="last">
<div>If you are lost, use the links on the right sidebar <img alt="." class="align-bottom" src="_images/rarr.png" style="height: 9pt;" /></div></blockquote>
</div>
<ul class="simple">
<li><a class="reference internal" href="#foreword-what"><em>What is or-tools?</em></a></li>
<li><a class="reference internal" href="#foreword-will-learn"><em>Optimization tools at Google</em></a></li>
<li><a class="reference internal" href="#foreword-will-not-learn"><em>What you will not learn in this document</em></a></li>
<li><a class="reference internal" href="#foreword-how-read"><em>How to read this document?</em></a></li>
<li><a class="reference internal" href="#foreword-targeted-audience"><em>Targeted audience</em></a></li>
<li><a class="reference internal" href="#foreword-conventions"><em>Conventions used in this manual</em></a></li>
<li><a class="reference internal" href="#foreword-accompanying-code"><em>Accompanying code for this manual</em></a></li>
<li><a class="reference internal" href="#foreword-how-to-reach-us"><em>How to reach us?</em></a></li>
<li><a class="reference internal" href="#foreword-how-to-reference-doc"><em>How to reference this document?</em></a></li>
<li><a class="reference internal" href="#foreword-comments"><em>Do you have comments?</em></a></li>
</ul>
<div class="section" id="what-is-or-tools">
<span id="foreword-what"></span><h2>What is or-tools?</h2>
<p>The or-tools library is a set of operations research tools written in C++ at Google.</p>
<p>The main tools are:</p>
<ul class="simple">
<li>A Constraint Programming solver.</li>
<li>A simple and unified interface to several linear programming and mixed integer
programming solvers (<a class="reference external" href="https://projects.coin-or.org/Cbc">CBC</a>, <a class="reference external" href="https://projects.coin-or.org/Clp">CLP</a>,
<a class="reference external" href="https://developers.google.com/optimization/docs/lp/glop">GLOP</a>, <a class="reference external" href="https://www.gnu.org/software/glpk/">GLPK</a>,
<a class="reference external" href="http://www.gurobi.com/">Gurobi</a>,
<a class="reference external" href="http://scip.zib.de/">SCIP</a> and <a class="reference external" href="http://sulumoptimization.com/">Sulum</a>).</li>
<li>Knapsack algorithms.</li>
<li>Graph algorithms (shortest paths, min cost flow, max flow, linear sum assignment).</li>
<li><em>FlatZinc</em> support.</li>
</ul>
</div>
<p>In short, the or-tools library is:</p>
<ul>
<li><p class="first"><strong>Open source and free</strong> Everything, including the examples, the implementations of the
algorithms, the various documentations, is licenced under the Apache License 2.0 and
is available for download. If you make substantial improvements to our code, please share it
with the whole community.</p>
</li>
<li><p class="first"><strong>Alive</strong> The library is actively maintained and updates and improvements are made on an
almost daily basis.</p>
</li>
<li><p class="first"><strong>Documented</strong> OK, we just started to write the documentation but there are already numerous
examples written in C++, Python, Java and C#!</p>
</li>
<li><p class="first"><strong>Portable</strong> Because it is made by Google, the code conforms strictly to the Google coding
styles. The code is known to compile on:</p>
<ul class="simple">
<li>gcc 4.7.x and above on Ubuntu 12.04 and up (12.04, 12.10, 13.04, 13.10)</li>
<li>XCode &gt;= 5.0 (clang++ with C++11 support)</li>
<li>Microsoft Visual Studio 2012 and 2013 (2010 is not supported as it lacks support for C++11)</li>
</ul>
<p>Both 32 bit and 64 bit architectures are supported, although the code is optimized to run in
64 bit mode.</p>
</li>
<li><p class="first"><strong>Efficient</strong> All we can say is that we use it internally at Google.</p>
</li>
<li><p class="first"><strong>Accessible</strong> Everything is coded in C++ but is available through SWIG in Python, Java, and
.NET (using Mono on non-Windows platforms).</p>
</li>
<li><p class="first"><strong>User-friendly</strong> We try to make our code as easy to use as possible (especially in Python
and C#). Of course, there is a (small) learning curve to use our library but once you master
several basic concepts, it is quite straightforward to code with the or-tools library.</p>
</li>
<li><p class="first"><strong>Tested</strong> We use it internally at Google since a few years and the community of users is
growing.</p>
</li>
</ul>
<div class="section" id="optimization-tools-at-google">
<span id="foreword-will-learn"></span><h2>Optimization tools at Google</h2>
<p>If you want to know more about optimization at Google, we refer the interested read to our
<a class="reference external" href="https://developers.google.com/optimization/">Google Optimization</a> page.</p>
</div>
<div class="section" id="what-you-will-learn-in-this-document">
<h2>What you will learn in this document</h2>
<p>This manual is intended to give you the necessary knowledge to use the library and explore the
reference manual by yourself. We describe the basic concepts but also how to customize your
search in Constraint Programming (CP). One of the strength of our library is its routing solver in
CP to solve node- and vehicle routing problems with constraints. We describe how to customize your
routing algorithms. After reading this manual, you will be able to understand our way of coding
and how to use the full potential of our library.</p>
<p>We detail the content of the manual in the section <a class="reference internal" href="manual/introduction/manual_content.html#manual-content"><em>The content of the manual</em></a>.</p>
</div>
<div class="section" id="what-you-will-not-learn-in-this-document">
<span id="foreword-will-not-learn"></span><h2>What you will not learn in this document</h2>
<p>This document is by no means a tutorial on Operations Research nor on Constraint Programming although we
try to give you a glimpse of the best practices.
It is also NOT a reference manual (refer to the documentation hub to find the reference manual).
There are way too many methods, parameters, functions, etc. to explain them all in details. Once
you understand the concepts and methods explained in this manual, you shouldnt have any
trouble scanning the reference manual and find the right method, parameter, function, . . . or code
them yourselves!</p>
<p>We dont document the non Constraint Programming (CP) part of the library. If you have any
questions about the non-CP part of the library, dont hesitate to ask them on the mailing list. See
the section <a class="reference internal" href="#how-to-reach-us">How to reach us?</a> below.</p>
<p>We don&#8217;t discuss the <tt class="docutils literal"><span class="pre">flatzinc</span></tt> implementation nor the parallel solving process.</p>
<p>This document will not describe how to use the library (and the syntactic sugar introduced when
possible) with <tt class="docutils literal"><span class="pre">Python</span></tt>, <tt class="docutils literal"><span class="pre">Java</span></tt> nor <tt class="docutils literal"><span class="pre">C#</span></tt>. This could possibly change in the future. The tutorial examples
(see below) exist also in <tt class="docutils literal"><span class="pre">Python</span></tt>, <tt class="docutils literal"><span class="pre">Java</span></tt> and <tt class="docutils literal"><span class="pre">C#</span></tt> though.</p>
</div>
<div class="section" id="how-to-read-this-document">
<span id="foreword-how-read"></span><h2>How to read this document?</h2>
<p>You could read this document from cover to cover but we have put a lot of efforts to make each
chapter stands on its own. The best way to read this manual is to look for a specific answer, use
the index or the table of contents to find a reference to that information. If you are
missing some requirements to understand a section, you can always backtrack on prerequisite
knowledge. For each chapter, we list those prerequisites. This non-linear way of reading is
probably the most efficient and rewarding one!</p>
<p>That said, the manual is kept short so that you can read it in its entirety. The first part (<em>Basics</em>)
is an introduction on how to use the CP solver to solve small problems. For real problems, you
need to customize your search and this is explained in the second part (<em>Customization</em>). If you are
interested in the routing part of the library, the third part is for you (<em>Routing</em>). Finally, some utilities
and tricks are described in the last part (<em>Technicalities</em>).</p>
</div>
<div class="section" id="targeted-audience">
<span id="foreword-targeted-audience"></span><h2>Targeted audience</h2>
<p>This manual is written with two types of readers in mind. First, someone who is not familiar with Constraint Programming
nor is she a professional programmer. Second, an educated reader who masters Constraint Programming and is
quite at ease without
necessarily mastering one of the supported computer languages.</p>
<p>From time to time, we refer to scientific articles: you don&#8217;t need to read and understand them to follow the
manual.</p>
<p>Did we succeed to write for such different profiles?
You tell us!</p>
</div>
<div class="section" id="conventions-used-in-this-manual">
<span id="foreword-conventions"></span><h2>Conventions used in this manual</h2>
<p>All the code is systematically written in <tt class="docutils literal"><span class="pre">monospace</span> <span class="pre">font</span></tt>. Function and methods names are
followed by parentheses. The method <tt class="docutils literal"><span class="pre">MakeSomething()</span></tt> and the parameter <tt class="docutils literal"><span class="pre">something</span></tt> are
two beautiful examples of this convention.</p>
<p>To draw your attention on important matters, we use a box with a danger warning sign.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">You have been warned!</p>
</div>
<p>To explain some details that would break the flow of the text, we use a box with a light bulb.</p>
<div class="topic">
<p class="topic-title first">This is an explanation that would break the flow of the text</p>
<p>This is why we prefer to put our explanation aside in a box with a light bulb.</p>
</div>
<p>To focus on some parts of the code, we omit non necessary code or code lines and replace them
by &#8221;...&#8221;.</p>
<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">operations_research</span> <span class="p">{</span>
<span class="n">IntVar</span><span class="o">*</span> <span class="k">const</span> <span class="n">MakeBaseLine2</span><span class="p">(...)</span> <span class="p">{</span>
<span class="p">...</span>
<span class="p">}</span>
<span class="p">...</span>
<span class="kt">void</span> <span class="n">CPIsFun</span><span class="p">()</span> <span class="p">{</span>
<span class="c1">// Magic happens here!</span>
<span class="p">}</span>
<span class="p">}</span> <span class="c1">// namespace operations_research</span>
</pre></div>
</div>
<p>In this example, the parameters of the function <tt class="docutils literal"><span class="pre">MakeBaseLine2()</span></tt> are stripped as are the content
of this method and the code lines that follow the definition of this function. The purpose of this
example is to show that the code is written inside the <tt class="docutils literal"><span class="pre">namespace</span> <span class="pre">operations_research</span></tt>.</p>
<p>All commands are issued from a Unix-like terminal:</p>
<div class="highlight-bash"><div class="highlight"><pre>./golomb1 --n<span class="o">=</span>5 --cp_no_solve --cp_show_constraints
</pre></div>
</div>
<p>Adapt the command lines to your type of terminal and operating system.</p>
</div>
<div class="section" id="accompanying-code-for-this-manual">
<span id="foreword-accompanying-code"></span><h2>Accompanying code for this manual</h2>
<p>All the examples in this manual are coded in C++. For the most important code snippets, you can
find complete examples on the documentation hub:</p>
<p><a class="reference external" href="http://or-tools.googlecode.com/svn/trunk/documentation/documentation_hub.html#tutorial_examples">http://or-tools.googlecode.com/svn/trunk/documentation/documentation_hub.html#tutorial_examples</a></p>
<p>or under the following directory of the or-tools library:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">documentation/tutorials/C++</span></tt></li>
</ul>
<p>If you prefer to code in Python, Java or C#, we have translated (will translate) all the examples in your
favourite language. You can find the complete examples on the documentation hub or under the
directories:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">documentation/tutorials/Python</span></tt></li>
<li><tt class="docutils literal"><span class="pre">documentation/tutorials/Java</span></tt></li>
<li><tt class="docutils literal"><span class="pre">documentation/tutorials/Csharp</span></tt>.</li>
</ul>
</div>
<div class="section" id="how-to-reach-us">
<span id="foreword-how-to-reach-us"></span><h2>How to reach us?</h2>
<p>The whole project or-tools is hosted on Google code:</p>
<p><a class="reference external" href="http://code.google.com/p/or-tools/">http://code.google.com/p/or-tools/</a></p>
<p>You can follow us on Google+:</p>
<p><a class="reference external" href="https://plus.google.com/u/0/108010024297451468877/posts">https://plus.google.com/u/0/108010024297451468877/posts</a></p>
<p>and post your questions, suggestions, remarks, . . . to the or-tools discussion group:</p>
<p><a class="reference external" href="http://groups.google.com/group/or-tools-discuss">http://groups.google.com/group/or-tools-discuss</a></p>
</div>
<div class="section" id="how-to-reference-this-document">
<span id="foreword-how-to-reference-doc"></span><h2>How to reference this document?</h2>
<p>Refer to the written document like this:</p>
<ol class="upperalpha simple" start="14">
<li>van Omme, L. Perron and V. Furnon, <em>or-tools user&#8217;s manual</em>, Google, 2014.</li>
</ol>
<p>Here is a bibtex entry:</p>
<div class="highlight-text"><div class="highlight"><pre>@TECHREPORT{or-tools-user-manual,
author = {Nikolaj van Omme and Laurent Perron and Vincent Furnon},
title = {or-tools user&#39;s manual},
institution = {Google},
year = {2014}
}
</pre></div>
</div>
</div>
<div class="section" id="do-you-have-comments">
<span id="foreword-comments"></span><h2>Do you have comments?</h2>
If you have comments, suggestions, corrections, feedback, ..., about this document or about the
documentation of the or-tools library in general, please send them to
<script type="text/javascript">
n = 'ortools.doc';
d = 'gmail.com';
document.write('<a href="ma');
document.write('ilto:' + n + '@');
document.write(d + '">');
document.write(n + '@');
document.write(d + '</a>.');
</script>
<noscript>ortools.doc(at)gmail.com.</noscript>
<br><p>Thank you very much.</p>
<p>Happy reading!</p>
<p>The or-tools team</p>
</div>
<div class="toctree-wrapper compound">
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<table>
<tr>
<td width="60"><img src="_static/logo.png" width="50" height="50" alt="" /></td>
<td><p class="library_name">Google <a href="http://code.google.com/p/or-tools/"><strong>or-tools</strong></a><br>open source library</p></td>
</tr>
</table>
<h1>User's Manual</h1>
<h3>Google search</h3>
<form method="get" action="http://www.google.com/search">
<div style="padding:-1px;width:15em;">
<table border="0" cellpadding="0">
<tr><td>
<input type="text" name="q" size="25"
maxlength="255" value="" />
<input type="submit" value="Go" /></td></tr>
<tr><td align="center" style="font-size:80%">
Search:
<select name="sitesearch" width="125" style="width: 125px">
<option value="http://or-tools.googlecode.com/svn/trunk/documentation/user_manual/" selected>user's manual</option>
<option value="http://or-tools.googlecode.com/svn/trunk/documentation/faq/">faq</option>
<option value="http://or-tools.googlecode.com/svn/trunk/documentation/reference_manual/or-tools/">reference manual</option>
<option value="http://or-tools.googlecode.com/svn/trunk/documentation/">All or-tools doc</option>
</select>
</td></tr>
</table>
</div>
</form>
</br>
<h3>Welcome</h3>
<ul>
<li><a href="#">Content and foreword</a></li>
<li><a href="http://or-tools.googlecode.com/svn/trunk/documentation/documentation_hub.html">Documentation's hub</a></li>
<li><a href="http://code.google.com/p/or-tools/">The or-tools open source library</a></li></li>
</ul>
<h3>Tutorial examples</h3>
<ul>
<li><a href="http://or-tools.googlecode.com/svn/trunk/documentation/documentation_hub.html#tutorial_C++">C++</a></li>
<li><a href="http://or-tools.googlecode.com/svn/trunk/documentation/documentation_hub.html#tutorial_Python">Python</a></li>
<li><a href="http://or-tools.googlecode.com/svn/trunk/documentation/documentation_hub.html#tutorial_Java">Java</a></li>
<li><a href="http://or-tools.googlecode.com/svn/trunk/documentation/documentation_hub.html#tutorial_Csharp">C#</a></li>
</ul>
<h3>Chapters</h3>
<h5>Part I: Basics</h5>
<ul>
<li><a class="reference internal" href="manual/introduction.html">1. Introduction to CP</a></li>
<li><a class="reference internal" href="manual/first_steps.html">2. First steps with or-tools</a></li>
<li><a class="reference internal" href="manual/objectives.html">3. Using objectives</a></li>
<li><a class="reference internal" href="manual/reification.html">4. Reification</a></li>
</ul>
<h5>Part II: Customization</h5>
<ul>
<li><a class="reference internal" href="manual/search_primitives.html">5. Search primitives</li>
<li><a class="reference internal" href="manual/LS.html">6. Local Search</a></li>
<li><a class="reference internal" href="manual/metaheuristics.html">7. Meta-heuristics</a></li>
<li><a class="reference internal" href="manual/custom_constraints.html">8. Custom constraints</a></li>
</ul>
<h5>Part III: Routing</h5>
<ul>
<li><a class="reference internal" href="manual/TSP.html">9. TSP with constraints</a></li>
<li><a class="reference internal" href="manual/VRP.html">10. VRP with constraints</a></li>
</ul>
<h5>Part IV: Technicalities</h5>
<ul>
<li><a class="reference internal" href="manual/utilities.html">11. Utilities</a></li>
<li><a class="reference internal" href="manual/modeling_tricks.html">12. Modeling tricks</a></li>
<li><a class="reference internal" href="manual/under_the_hood.html">13. Under the hood</a></li>
</ul>
<h5>Appendices</h5>
<ul>
<li><a class="reference internal" href="genindex.html">Index</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<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="manual/introduction.html" title="1. Introduction to constraint programming"
>next</a> |</li>
<li><a href="#">or-tools User&#39;s Manual</a> &raquo;</li>
</ul>
</div>
<div class="footer">
&copy; Copyright 2012-2015, Google.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
</div>
</body>
</html>