Ticket #7652: trac_7652.patch

File trac_7652.patch, 9.1 KB (added by ncohen, 11 years ago)
  • doc/en/constructions/index.rst

    # HG changeset patch
    # User Nathann Cohen <nathann.cohen@gmail.com>
    # Date 1260456798 -3600
    # Node ID 92a5c0a4d83bff785f2024d8de51b7c94c2fa72d
    # Parent  aa94d77e51e53e2096214e99828486d0b3c685e6
    Adds Linear Programming to the Constructions Document.
    
    diff -r aa94d77e51e5 -r 92a5c0a4d83b doc/en/constructions/index.rst
    a b  
    3434   linear_algebra
    3535   linear_codes
    3636   graph_theory
     37   linear_programming
    3738   rep_theory
    3839   rings
    3940   polynomials
     
    4546   interface_issues
    4647   contributions
    4748
     49
    4850Indices and tables
    4951==================
    5052
  • new file doc/en/constructions/linear_programming.rst

    diff -r aa94d77e51e5 -r 92a5c0a4d83b doc/en/constructions/linear_programming.rst
    - +  
     1Linear Programming
     2==================
     3
     4Basics
     5------
     6
     7What is a Linear Program ?
     8""""""""""""""""""""""""""
     9
     10A linear program consists of the following two pieces of information :
     11
     12    * A linear function, called the objective, which is
     13      to be maximized or minimized (for example `2 x + y`)
     14    * Linear constraints on the variables (for example,
     15      `3 x + y \leq 2` and  `2 x + 3 y \leq 8`)
     16
     17The solver will then try to find a solution to the system of
     18constraints such that the objective function is optimized, and
     19return the values of the variables.
     20
     21
     22
     23What is a Mixed Integer Linear Program ?
     24""""""""""""""""""""""""""""""""""""""""""
     25
     26It is simply a Linear Program such that some variables are forced
     27to take integer values instead of real values. This difference becomes
     28very important when one learns that solving a Linear Program can be done
     29in polynomial time while solving a general Mixed Integer Linear Program
     30is `NP`-Complete (= there is no polynomial algorithm to solve it,
     31according to a widely-spread belief that `P\neq NP`)
     32
     33Why is Linear Programming so useful ?
     34""""""""""""""""""""""""""""""""""""""
     35
     36Linear Programming is very useful in many Optimization and
     37Graph-Theoretical problems because of its wide range of expression.
     38Most of the time, a natural Linear Program can be easily written
     39to solve a problem whose solution will be quickly computed thanks
     40to the wealth of heuristics already contained in Linear Program
     41Solvers. It is often hard to theoretically find out the execution
     42time of a Linear Program, though they give very interesting results
     43in practice.
     44
     45For more information, you can consult the Wikipedia page dedicated to
     46Linear Programming : http://en.wikipedia.org/wiki/Linear_programming
     47
     48How can I solve a linear program using Sage ?
     49---------------------------------------------
     50
     51Sage can solve Linear Programs or Mixed Integer Linear Programs through
     52the class ``MixedIntegerLinearProgram`` defined in ``sage.numerical.mip``. To illustrate how it can be
     53used, we will try to solve the following problem :
     54
     55.. MATH::
     56
     57    \mbox{Maximize : }&2 x_1 + x_2\\
     58    \mbox{Such that : }&3 x_1 + 4 x_2\leq 2.5\\
     59    &0.5\leq 1.2 x_1 + 0.5 x_2 \leq 4
     60
     61First, we need a few informations about ``MIPVariable`` and
     62how to read the optimal values when the solver has finished its job.
     63
     64Variables in ``MixedIntegerLinearProgram``
     65""""""""""""""""""""""""""""""""""""""""""""
     66
     67A variable linked to an instance of ``MixedIntegerLinearProgram`` behaves exactly as
     68a dictionary would. It is declared the following way ::
     69
     70    sage: p=MixedIntegerLinearProgram()
     71    sage: variable=p.new_variable()
     72
     73The variable ``variable`` can contain as many keys as you
     74would like, each of them being formally `unique`. For example
     75the following constraint (where `P` denotes the pressure,
     76and `T` the temperature) :
     77
     78.. MATH::
     79    2 T_{\mbox{Madrid}} + 3 T_{\mbox{London}} -
     80    P_{\mbox{Seattle}} + \mbox{flow}_{3,5} +
     81    8 \mbox{cost}_{(1,3)} + x_3 < 5\\
     82
     83... can be expressed in Sage (quite naturally, I hope !) this way ::
     84
     85    sage: p=MixedIntegerLinearProgram()
     86    sage: temperature=p.new_variable()
     87    sage: pressure=p.new_variable()
     88    sage: x=p.new_variable()
     89    sage: cost=p.new_variable()
     90    sage: flow=p.new_variable(dim=2)
     91    sage: p.add_constraint(2*temperature["Madrid"]+3*temperature["London"]-pressure["Seattle"]+flow[3][5]+8*cost[(1,3)]+x[3],max=5)
     92
     93This example is just meant to show you the different possibilities
     94offered to you when you use the ``MixedIntegerLinearProgram`` class. You will not need
     95to declare so many variables in usual applications.
     96
     97Notice how the variable ``flow`` is defined : you can use any hashable
     98object as a key for a ``MIPVariable``, but if you think you need
     99more than one dimension, you need to explicitely say it when
     100calling ``MixedIntegerLinearProgram.new_variable()``
     101
     102For the user's convenience, however, there is a default variable
     103attached to a Linear Program : indeed, the previous implementation
     104means that each "variable" actually represents a property of
     105a set of objects (these objects are strings in the case of ``temperature``
     106or a pair in the case of ``cost``). In some cases, though it is useful to
     107define an absolute variable which will not be indexed on anything. This can
     108be done through the following notation ::
     109
     110    sage: p = MixedIntegerLinearProgram()
     111    sage: B = p.new_variable()
     112    sage: p.set_objective( p["first unique variable"] + B[2] + p[-3] )
     113
     114In this case, two of these "unique" variables are defined through
     115``p["first unique variable"]`` and ``p[-3]``.
     116   
     117Let us solve this system !
     118""""""""""""""""""""""""""
     119
     120Now that we know what are variables,
     121we are only several lines away from solving our system ::
     122
     123    sage: # First, we define our MixedIntegerLinearProgram object, setting maximization=True
     124    sage: p=MixedIntegerLinearProgram( maximization = True )
     125    sage: x=p.new_variable()
     126    sage: # Definition of the objective function
     127    sage: p.set_objective( 2*x[1]+x[2] )
     128    sage: # Next, the two constraints
     129    sage: p.add_constraint( 3*x[1]+4*x[2], max=2.5 )
     130    sage: p.add_constraint( 1.5*x[1]+0.5*x[2], max=4,min=0.5 )
     131    sage: p.solve() # optional - requires Glpk or COIN-OR/CBC
     132    1.6666666666666667
     133    sage: x_sol=p.get_values(x)
     134    sage: print x_sol
     135    {1: 0.83333333333333337, 2: 0.0}
     136
     137
     138The value returned by ``MixedIntegerLinearProgram.solve()`` is the optimal value of
     139the objective function. To read the values taken by the variables
     140one needs to call the method ``MixedIntegerLinearProgram.get_values`` which can return
     141multiple values at the same time if needed (type
     142``sage: MixedIntegerLinearProgram.get_values?`` for more information on this function)
     143
     144Some famous examples
     145---------------------------
     146
     147Vertex Cover in a graph
     148""""""""""""""""""""""""
     149
     150In the Vertex Cover problem, we are given a graph `G` and we want to find
     151a subset `S` of its vertices of minimal cardinality such that each edge
     152`e` is incident to at least one vertex of `S`. In order to achieve it, we
     153define a binary variable `b_v` for each vertex `v`.
     154
     155.. MATH::
     156
     157    \mbox{Maximize : }& \sum_{v\in G.vertices()} b_v\\
     158    \mbox{Such that : }&\forall (u,v)\in G.edges(), b_u + b_v \geq 1\\
     159    &\forall v,b_v \mbox{ is a binary variable}
     160
     161In the linear program, the syntax is exactly the same ::
     162
     163    sage: g=graphs.PetersenGraph()
     164    sage: p=MixedIntegerLinearProgram(maximization=False)
     165    sage: b=p.new_variable()
     166    sage: for (u,v) in g.edges(labels=None):
     167    ...          p.add_constraint(b[u]+b[v],min=1)
     168    sage: p.set_binary(b)
     169   
     170And you but have to type ``p.solve()`` to see the result !
     171
     172Maximum matching in a Graph
     173""""""""""""""""""""""""""""
     174
     175In the maximum matching problem, we are given a graph `G`, and we are
     176looking for a set of edges `M` of maximum cardinality such
     177that no two edges from `M` are adjacent :
     178
     179.. MATH::
     180
     181    \mbox{Maximize : }& \sum_{e\in G.edges()} b_e\\
     182    \mbox{Such that : }&\forall v\in G.vertices(), \sum_{(v,w)\in G}b_{uv} \leq 1\\
     183    &\forall e\in G.edges(),b_e \mbox{ is a binary variable}
     184
     185Here is how this is solved through Sage on a Petersen Graph ::
     186
     187    sage: g=graphs.PetersenGraph()
     188    sage: p=MixedIntegerLinearProgram()
     189    sage: b=p.new_variable(dim=2)
     190    sage: for u in g.vertices():
     191    ...    p.add_constraint(sum([b[u][v] for v in g.neighbors(u)]),max=1)
     192    sage: for (u,v) in g.edges(labels=None):
     193    ...    p.add_constraint(b[u][v]+b[v][u],min=1,max=1)
     194
     195And the next step is ``p.solve()`` !
     196
     197
     198Solvers
     199-------
     200
     201Sage solves linear programs by calling specific libraries. Two are available
     202for the moment :
     203
     204     * `GLPK <http://www.gnu.org/software/glpk/>`_ : A Linear Program solver
     205       from `GNU <http://www.gnu.org/>`_
     206     * `CBC <http://www.coin-or.org/projects/Cbc.xml>`_ : Mixed
     207       Integer Linear Program solver from
     208       `COIN-OR <http://www.coin-or.org/>`_
     209
     210To install them if they are not available on your installation of Sage, type ::
     211
     212     sage: # To install GLPK
     213     sage: install_package('glpk') # not tested
     214     sage: # To install Coin-OR Branch and Cut (CBC)
     215     sage: install_package('cbc')  # not tested