Ticket #7652: trac_7652-reviewer.patch

File trac_7652-reviewer.patch, 16.2 KB (added by mvngu, 11 years ago)

reviewer patch

  • doc/en/constructions/linear_programming.rst 

    # HG changeset patch
# User Minh Van Nguyen <nguyenminh2@gmail.com>
# Date 1260580510 28800
# Node ID 63d8e7ebcef853e3ad181c252039d9cdf1a80145
# Parent  1245120e8f9755ada808b0618ad14abff5b8122f
trac 7652: linear programming; reviewer patch

diff -r 1245120e8f97 -r 63d8e7ebcef8 doc/en/constructions/linear_programming.rst
    a b  
    11Linear Programming
    22==================
    33
     4
    45Basics
    56------
    67
    7 What is a Linear Program ?
    8 """"""""""""""""""""""""""
     8What is a linear program?
     9"""""""""""""""""""""""""
    910
    10 A linear program consists of the following two pieces of information :
     11A linear program consists of the following two pieces of information:
    1112
    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`)
     13* A linear function, called the objective function, which is
     14  to be maximized or minimized, e.g. `2 x + y`.
    1615
    17 The solver will then try to find a solution to the system of
    18 constraints such that the objective function is optimized, and
    19 return the values of the variables.
     16* Linear constraints on the variables, e.g. `3 x + y \leq 2` and
     17  `2 x + 3 y \leq 8`.
    2018
     19A linear program solver would then try to find a solution to the
     20system of constraints such that the objective function is optimized, and
     21return specific values for the variables.
    2122
     23What is a mixed integer linear program?
     24"""""""""""""""""""""""""""""""""""""""
    2225
    23 What is a Mixed Integer Linear Program ?
     26A mixed integer linear program is a linear program such that some
     27variables are forced to take integer values instead of real
     28values. This difference affects the time required to solve a
     29particular linear program. Indeed, solving a linear program can be
     30done in polynomial time while solving a general mixed integer linear
     31program is usually `NP`-complete, i.e. it can take exponential time,
     32according to a widely-held belief that `P \neq NP`.
     33
     34Why is linear programming so useful?
     35""""""""""""""""""""""""""""""""""""
     36
     37Linear programming is very useful in many optimization and
     38graph-theoretic problems because of its wide range of expression.
     39A linear program can be written to solve a problem whose
     40solution could be obtained within reasonable time using the wealth of
     41heuristics already contained in linear program solvers. It is often
     42difficult to theoretically determine the execution time of a linear
     43program, though it could produce very interesting results in
     44practice.
     45
     46For more information, consult the Wikipedia page dedicated to
     47linear programming: http://en.wikipedia.org/wiki/Linear_programming
     48
     49
     50How can I solve a linear program using Sage?
     51--------------------------------------------
     52
     53Sage can solve linear programs or mixed integer linear programs
     54through the class ``MixedIntegerLinearProgram`` defined in
     55``sage.numerical.mip``. To illustrate how it can be used, we will try
     56to solve the following problem:
     57
     58.. MATH::
     59
     60    \text{Maximize: }  & 2 x_1 + x_2 \\
     61    \text{Such that: } & 3 x_1 + 4 x_2 \leq 2.5 \\
     62                       & 0.5 \leq 1.2 x_1 + 0.5 x_2 \leq 4
     63
     64First, we need to discuss ``MIPVariable`` and how to read the optimal
     65values when the solver has finished its job.
     66
     67Variables in ``MixedIntegerLinearProgram``
    2468""""""""""""""""""""""""""""""""""""""""""
    2569
    26 It is simply a Linear Program such that some variables are forced
    27 to take integer values instead of real values. This difference becomes
    28 very important when one learns that solving a Linear Program can be done
    29 in polynomial time while solving a general Mixed Integer Linear Program
    30 is `NP`-Complete (= there is no polynomial algorithm to solve it,
    31 according to a widely-spread belief that `P\neq NP`)
     70A variable linked to an instance of ``MixedIntegerLinearProgram``
     71behaves exactly as a dictionary would. It is declared as follows::
    3272
    33 Why is Linear Programming so useful ?
    34 """"""""""""""""""""""""""""""""""""""
    35 
    36 Linear Programming is very useful in many Optimization and
    37 Graph-Theoretical problems because of its wide range of expression.
    38 Most of the time, a natural Linear Program can be easily written
    39 to solve a problem whose solution will be quickly computed thanks
    40 to the wealth of heuristics already contained in Linear Program
    41 Solvers. It is often hard to theoretically find out the execution
    42 time of a Linear Program, though they give very interesting results
    43 in practice.
    44 
    45 For more information, you can consult the Wikipedia page dedicated to
    46 Linear Programming : http://en.wikipedia.org/wiki/Linear_programming
    47 
    48 How can I solve a linear program using Sage ?
    49 ---------------------------------------------
    50 
    51 Sage can solve Linear Programs or Mixed Integer Linear Programs through
    52 the class ``MixedIntegerLinearProgram`` defined in ``sage.numerical.mip``. To illustrate how it can be
    53 used, 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 
    61 First, we need a few informations about ``MIPVariable`` and
    62 how to read the optimal values when the solver has finished its job.
    63 
    64 Variables in ``MixedIntegerLinearProgram``
    65 """"""""""""""""""""""""""""""""""""""""""""
    66 
    67 A variable linked to an instance of ``MixedIntegerLinearProgram`` behaves exactly as
    68 a dictionary would. It is declared the following way ::
    69 
    70     sage: p=MixedIntegerLinearProgram()
    71     sage: variable=p.new_variable()
     73    sage: p = MixedIntegerLinearProgram()
     74    sage: variable = p.new_variable()
    7275
    7376The variable ``variable`` can contain as many keys as you
    74 would like, each of them being formally `unique`. For example
    75 the following constraint (where `P` denotes the pressure,
    76 and `T` the temperature) :
     77like, where each key must be unique. For example, the following
     78constraint (where `P` denotes pressure and `T` temperature)
    7779
    7880.. 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\\
    8281
    83 ... can be expressed in Sage (quite naturally, I hope !) this way ::
     82    2 T_{\text{Madrid}} + 3 T_{\text{London}} - P_{\text{Seattle}} + \text{flow}_{3, 5} + 8 \text{cost}_{(1, 3)} + x_3 < 5
    8483
    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)
     84can be written as::
    9285
    93 This example is just meant to show you the different possibilities
    94 offered to you when you use the ``MixedIntegerLinearProgram`` class. You will not need
    95 to declare so many variables in usual applications.
     86    sage: p = MixedIntegerLinearProgram()
     87    sage: temperature = p.new_variable()
     88    sage: pressure = p.new_variable()
     89    sage: x = p.new_variable()
     90    sage: cost = p.new_variable()
     91    sage: flow = p.new_variable(dim=2)
     92    sage: p.add_constraint(2*temperature["Madrid"] + 3*temperature["London"] - pressure["Seattle"] + flow[3][5] + 8*cost[(1, 3)] + x[3], max=5)
    9693
    97 Notice how the variable ``flow`` is defined : you can use any hashable
     94This example shows different possibilities for using the
     95``MixedIntegerLinearProgram`` class. You would not need to declare so
     96many variables in some common applications of linear programming.
     97
     98Notice how the variable ``flow`` is defined: you can use any hashable
    9899object as a key for a ``MIPVariable``, but if you think you need
    99 more than one dimension, you need to explicitely say it when
    100 calling ``MixedIntegerLinearProgram.new_variable()``
     100more than one dimension, you need to explicitly specify it when
     101calling ``MixedIntegerLinearProgram.new_variable()``.
    101102
    102 For the user's convenience, however, there is a default variable
    103 attached to a Linear Program : indeed, the previous implementation
    104 means that each "variable" actually represents a property of
    105 a set of objects (these objects are strings in the case of ``temperature``
    106 or a pair in the case of ``cost``). In some cases, though it is useful to
    107 define an absolute variable which will not be indexed on anything. This can
    108 be done through the following notation ::
     103For the user's convenience, there is a default variable
     104attached to a linear program. The above code listing means that each
     105``variable`` actually represents a property of a set of objects
     106(these objects are strings in the case of ``temperature`` or a pair in
     107the case of ``cost``). In some cases, it is useful to define an
     108absolute variable which will not be indexed on anything. This can be
     109done as follows::
    109110
    110111    sage: p = MixedIntegerLinearProgram()
    111112    sage: B = p.new_variable()
    112     sage: p.set_objective( p["first unique variable"] + B[2] + p[-3] )
     113    sage: p.set_objective(p["first unique variable"] + B[2] + p[-3])
    113114
    114115In this case, two of these "unique" variables are defined through
    115116``p["first unique variable"]`` and ``p[-3]``.
    116    
    117 Let us solve this system !
    118 """"""""""""""""""""""""""
    119117
    120 Now that we know what are variables,
    121 we are only several lines away from solving our system ::
     118Let's solve this system
     119"""""""""""""""""""""""
    122120
    123     sage: # First, we define our MixedIntegerLinearProgram object, setting maximization=True
    124     sage: p=MixedIntegerLinearProgram( maximization = True )
    125     sage: x=p.new_variable()
     121Now that we know what variables are, we are only several steps away
     122from solving our system::
     123
     124    sage: # First, we define our MixedIntegerLinearProgram object,
     125    sage: # setting maximization=True.
     126    sage: p = MixedIntegerLinearProgram(maximization=True)
     127    sage: x = p.new_variable()
    126128    sage: # Definition of the objective function
    127     sage: p.set_objective( 2*x[1]+x[2] )
     129    sage: p.set_objective(2*x[1] + x[2])
    128130    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
     131    sage: p.add_constraint(3*x[1] + 4*x[2], max=2.5)
     132    sage: p.add_constraint(1.5*x[1]+0.5*x[2], max=4, min=0.5)
     133    sage: p.solve()                # optional - requires GLPK or COIN-OR/CBC
    132134    1.6666666666666667
    133     sage: x_sol=p.get_values(x)
    134     sage: print x_sol
     135    sage: x_sol = p.get_values(x)  # optional - requires GLPK or COIN-OR/CBC
     136    sage: print x_sol              # optional - requires GLPK or COIN-OR/CBC
    135137    {1: 0.83333333333333337, 2: 0.0}
    136138
     139The value returned by ``MixedIntegerLinearProgram.solve()`` is the
     140optimal value of the objective function. To read the values taken by
     141the variables, one needs to call the method
     142``MixedIntegerLinearProgram.get_values()`` which can return multiple
     143values at the same time if needed (type
     144``MixedIntegerLinearProgram.get_values?`` for more information
     145on this function).
    137146
    138 The value returned by ``MixedIntegerLinearProgram.solve()`` is the optimal value of
    139 the objective function. To read the values taken by the variables
    140 one needs to call the method ``MixedIntegerLinearProgram.get_values`` which can return
    141 multiple values at the same time if needed (type
    142 ``sage: MixedIntegerLinearProgram.get_values?`` for more information on this function)
    143147
    144148Some famous examples
    145 ---------------------------
     149--------------------
    146150
    147 Vertex Cover in a graph
    148 """"""""""""""""""""""""
     151Vertex cover in a graph
     152"""""""""""""""""""""""
    149153
    150 In the Vertex Cover problem, we are given a graph `G` and we want to find
    151 a 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
    153 define a binary variable `b_v` for each vertex `v`.
     154Let `G = (V, E)` be a graph with vertex set `V` and edge set `E`. In
     155the vertex cover problem, we are given `G` and we want to find
     156a subset `S \subseteq V` of minimal cardinality such that each
     157edge `e` is incident to at least one vertex in `S`. In order to
     158achieve this, we define a binary variable `b_v` for each vertex
     159`v`. The vertex cover problem can be expressed as the following linear
     160program:
    154161
    155 .. MATH:: 
     162.. MATH::
    156163
    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}
     164    \text{Maximize: }  & \sum_{v \in V} b_v \\
     165    \text{Such that: } & \forall (u, v) \in E, b_u + b_v \geq 1 \\
     166                       & \forall v, b_v \text{ is a binary variable}
    160167
    161 In the linear program, the syntax is exactly the same ::
     168In the linear program, the syntax is exactly the same::
    162169
    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)
     170    sage: g = graphs.PetersenGraph()
     171    sage: p = MixedIntegerLinearProgram(maximization=False)
     172    sage: b = p.new_variable()
     173    sage: for u, v in g.edges(labels=None):
     174    ...       p.add_constraint(b[u] + b[v], min=1)
    168175    sage: p.set_binary(b)
    169    
    170 And you but have to type ``p.solve()`` to see the result !
    171176
    172 Maximum matching in a Graph
    173 """"""""""""""""""""""""""""
     177And you need to type ``p.solve()`` to see the result.
    174178
    175 In the maximum matching problem, we are given a graph `G`, and we are
    176 looking for a set of edges `M` of maximum cardinality such
    177 that no two edges from `M` are adjacent :
     179Maximum matching in a graph
     180"""""""""""""""""""""""""""
    178181
    179 .. MATH::
     182In the maximum matching problem, we are given a graph `G = (V, E)`
     183and we want a set of edges `M \subseteq E` of maximum cardinality such
     184that no two edges from `M` are adjacent:
    180185
    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}
     186.. MATH::
    184187
    185 Here is how this is solved through Sage on a Petersen Graph ::
     188    \text{Maximize: }  & \sum_{e \in E} b_e \\
     189    \text{Such that: } & \forall v \in V, \sum_{(v,u) \in E} b_{vu} \leq 1 \\
     190                       & \forall e \in E, b_e \text{ is a binary variable}
    186191
    187     sage: g=graphs.PetersenGraph()
    188     sage: p=MixedIntegerLinearProgram()
    189     sage: b=p.new_variable(dim=2)
     192Here, we use Sage to solve the maximum matching problem for the case
     193of the Petersen graph::
     194
     195    sage: g = graphs.PetersenGraph()
     196    sage: p = MixedIntegerLinearProgram()
     197    sage: b = p.new_variable(dim=2)
    190198    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)
     199    ...       p.add_constraint(sum([b[u][v] for v in g.neighbors(u)]), max=1)
     200    sage: for u, v in g.edges(labels=None):
     201    ...       p.add_constraint(b[u][v] + b[v][u], min=1, max=1)
    194202
    195 And the next step is ``p.solve()`` !
     203And the next step is ``p.solve()``.
    196204
    197205
    198206Solvers
    199207-------
    200208
    201 Sage solves linear programs by calling specific libraries. Two are available
    202 for the moment :
     209Sage solves linear programs by calling specific libraries. The
     210following libraries are currently supported as optional packages:
    203211
    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/>`_
     212* `GLPK <http://www.gnu.org/software/glpk/>`_: A linear program solver
     213  from `GNU <http://www.gnu.org/>`_
    209214
    210 To install them if they are not available on your installation of Sage, type ::
     215* `CBC <http://www.coin-or.org/projects/Cbc.xml>`_: Mixed integer
     216  linear program solver from `COIN-OR <http://www.coin-or.org/>`_
    211217
    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
     218Each of these packages can be installed as follows::
     219
     220    sage: # To install GLPK
     221    sage: install_package("glpk")  # not tested
     222    sage: # To install COIN-OR Branch and Cut (CBC)
     223    sage: install_package("cbc")   # not tested