Ticket #6774: trac-6774-graph-tour-review.patch

File trac-6774-graph-tour-review.patch, 11.8 KB (added by jason, 11 years ago)

apply on top of previous patch

  • doc/en/tutorial/tour_graphtheory.rst

    # HG changeset patch
    # User Jason Grout <jason-sage@creativetrax.com>
    # Date 1253179860 18000
    # Node ID 013f7f3feb56a414172a14950c44b7fa80986c36
    # Parent  3369a618ad1987b1658e4b34394b3466d89d93da
    Typos, punctuation fixes, and minor editing.
    
    diff -r 3369a618ad19 -r 013f7f3feb56 doc/en/tutorial/tour_graphtheory.rst
    a b  
    55-----------
    66
    77A Graph is a set of vertices connected by edges
    8 (see `Wikipedia <http://en.wikipedia.org/wiki/Graph_(mathematics)>`_ )
     8(see `Wikipedia <http://en.wikipedia.org/wiki/Graph_(mathematics)>`_).
    99
    10 One can very easily create a graph in sage by typing ::
     10One can very easily create a graph in sage by typing::
    1111   
    1212    sage: g=Graph()
    1313
     
    1717    sage: g
    1818    Graph on 0 vertices
    1919
    20 This graph is not very interesting as it is by default the empty graph.. But
    2120Sage contains a large collection of predefined graph classes
    22 that can be listed this way :
     21that can be listed this way:
    2322   
    24     * type in Sage : ``graphs.``
    25       ( do not press "Enter", and do not forget the final "." )
    26     * hit "tabulation" two times in a row
     23    1. type in Sage: ``graphs.`` (do not press "Enter", and do not
     24       forget the final "."), then
     25
     26    2. hit the tab key two times in a row
    2727   
    2828You will see the list of methods defined in the class ``graphs``,
    29 all of which generate graphs you can play with !
     29all of which generate graphs you can play with!
    3030
    31 If you want to see what they look like, begin this way ::
     31If you want to see what they look like, you can plot the graphs::
    3232   
    3333    sage: g=graphs.PetersenGraph()
    3434    sage: g.plot()
    35 
    36 or::
    37 
    3835    sage: g=graphs.ChvatalGraph()
    3936    sage: g.plot()
    4037
    41 If you are curious about what these graphs are, for example 
    42 if you wonder what ``RandomGNP`` actually is, you but have to type ::
     38If you are curious about what these graphs are, for example, if you
     39wonder what ``RandomGNP`` actually is, use the standard Sage help::
    4340
    4441    sage: graphs.RandomGNP?
    4542
    4643Once you have defined the graph you want, you can begin
    47 to work on it by using thealmost 200 functions on graphs
    48 in the Sage library !If your graph is named ``g``, you can
    49 list these functions as previously this way :
     44to work on it by using the hundreds of functions for graphs
     45in the Sage libraryIf your graph is named ``g``, you can
     46list these functions using tab completion:
    5047   
    51     * type in Sage : ``g.``
    52       ( do not press "Enter", and do not forget the final "." )
    53     * hit "tabulation" two times in a row   
     48    1. type in Sage: ``g.`` (do not press "Enter", and do not forget
     49       the final "."), then
     50
     51    2. hit the tab key two times in a row
    5452
    5553As usual, you can get some information about what these
    56 functions do by typing( if you want to know about the ``diameter()``
    57 method )::
     54functions do by typing (if you want to know about the :meth:`diameter()`
     55method)::
    5856
    5957    sage: g.diameter?
    6058
    61 If you have defined a graph ``g`` having several connected
    62 components ( = which is notconnected... Type ``g.is_connected()``
    63 to know whether your graph is ), you canprint each one of
    64 its connected components with only two lines :   
     59To find out if a graph is connected, use :meth:`is_connected`::
    6560
    66 ( if you do not have such a graph G, here is one
    67 for free :  ``g=graphs.RandomGNP(30,.05)``    )::   
     61   sage: g=graphs.RandomGNP(100, 0.01)
     62   sage: g.is_connected()
     63
     64You can plot each connected component separately::
    6865
    6966    sage: for component in g.connected_components():
    7067    ...      g.subgraph(component).plot()
     
    7572
    7673The first elements you want to find in a graph are its vertices
    7774and its edges. The vertices of a graph ``g`` are returned
    78 by ``g.vertices()`` and its edges are returned by ``g.edges()``.
     75by :meth:`g.vertices` and its edges are returned by :meth:`g.edges`.
    7976In Sage, the edges of a graph are represented as tuples ``(u,v,l)``
    8077where ``u`` and ``v`` are vertices, and ``l`` a label attached
    81 to the edge ( this label can be of any type, even though
    82 several functions expect it to be a real value ).
     78to the edge (this label can be of any type, even though
     79several functions expect it to be a real value).
    8380
    84 The methods ``g.order()`` and ``g.size()`` respectively return the number
     81The methods :meth:`g.order` and :meth:`g.size` respectively return the number
    8582of vertices and the number of edges.
    8683
    8784At any moment, you can display the adjacency matrix of you graph
    88 by using the method ``g.am()`` and plot the graph with ``g.plot()``.
     85by using the method :meth:`g.adjacency_matrix` and plot the graph with :meth:`g.plot`.
    8986
    90 What interesting things can you do with Graphs in Sage ?
     87What interesting things can you do with Graphs in Sage?
    9188---------------------------------------------------------
    9289
    93 Computing matching
     90Compute maximum matchings
    9491^^^^^^^^^^^^^^^^^^^
    9592
    96 Maximum Matching a polynomial problem in Graph Theory, and
    97 have a thousand of different applications. This, just to
    98 mean that the following list of examples is not (yet?) exhaustive.
     93Maximum Matchings, a polynomial problem in Graph Theory, has many
     94different applications.  In the subsections that follow, we will look
     95at a few of these applications.
    9996
    100 For more information on matching :
    101 `Matching <http://en.wikipedia.org/wiki/Matching>`_
     97For more information on matchings, see `Matching
     98<http://en.wikipedia.org/wiki/Matching>`_.
    10299
    103100Small company
    104101""""""""""""""""
    105102
    106103Let us say that you are in charge of a small company with 4 employees
    107104`\{e_1,e_2,e_3,e_4\}` and have several tasks `\{t_1,t_2,t_3,t_4\}`
    108 to give them. Unfortunately, no worker is skilled enough to do all of them :
     105to give them. Unfortunately, no worker is skilled enough to do all of them:
    109106
    110107    * `e_1` can do `t_1, t_3, t_4`
    111108    * `e_2` can do `t_1, t_3, t_5`
     
    117114You are lucky if you do not know how to solve this problem manually,
    118115because this is typically an application of matching in graphs
    119116(and if you have found the solution, I assure you it gets harder
    120 when you have more of them) !
     117when you have more of employees).
    121118
    122 To solve this problem, you but have to create the graph corresponding
    123 to the information above, and solve the matching problem :::
     119To solve this problem, create the graph corresponding to the
     120information above, and solve the matching problem::
    124121   
    125122    sage: g=Graph({"e0":['t1', 't3', 't4'],"e1":['t1', 't3',
    126123            't5'],"e2":['t1', 't2', 't3', 't4', 't5'],
     
    129126    [('e2', 't4', None), ('e3', 't5', None), ('e0', 't3', None),
    130127     ('e1', 't1', None), ('e4', 't2', None)]
    131128
    132 If you prefer to "see" the result, you can also type ::
     129If you prefer to "see" the result, you can also type::
    133130   
    134131    sage: g.plot(edge_colors={"red":g.max_matching()})
    135132
    136 Sage 1 : Pain 0
     133Wasn't that simple?
    137134
    138135Summer camp
    139136""""""""""""
    140137
    141 You know have under your responsibility 5 rooms and 10 children
    142 `\{c_0,...,c_9\}`. You need to decide those of them who will
     138You know have under your responsibility five rooms and ten children
     139`\{c_0,...,c_9\}`. You need to decide which of them will
    143140sleep in the same rooms, but you do not want two of them to be
    144141together if they do not like each other or if you expect trouble
    145 from the pair... Here are the constraints :
     142from the pair. Here are the constraints:
    146143
    147144    * `c_0` can sleep with `c_5`
    148145    * `c_1` can sleep with `c_5, c_8`
     
    153150    * `c_6` can sleep with `c_7, c_9`
    154151    * `c_7` can sleep with `c_9`
    155152
    156 As previously, this defines a graph whose adjacency matrix has
    157 just been defined ! You now but have to create it in Sage, and
    158 look for a maximum matching...::
     153As done previously, this defines a graph. Now create it in Sage, and
     154ask for a maximum matching::
    159155
    160156    sage: g=Graph({'c0':['c5'],'c1':['c5', 'c8'],'c2':['c3',
    161157            'c8', 'c9'],'c3':['c9'],'c4':['c9'],'c5':['c9'],
     
    164160    [('c0', 'c5', None), ('c6', 'c7', None), ('c2', 'c3', None),
    165161     ('c4', 'c9', None), ('c1', 'c8', None)]
    166162
    167 If you prefer to "see" the result, you can also type ::
     163If you prefer to "see" the result, you can also type::
    168164   
    169165    sage: g.plot(edge_colors={"red":g.max_matching()})
    170166
    171 And this is another problem Sage solved for you !
    172 
    173 
     167And this is another problem Sage solved for you!
    174168
    175169Vertex coloring
    176170^^^^^^^^^^^^^^^
    177171
    178172You are in front of a map of Western Europe that you would like
    179173to color. Obviously, you can not color both France and Italy
    180 with the same color as they have a common boundary, and you would
    181 not like to mix the two.. Actually, you want to color :
     174with the same color, as they have a common boundary, and you would
     175not like to mix the two. Actually, you want to color:
    182176
    183177    * Austria
    184178    * Belgium
     
    194188    * United Kingdom
    195189
    196190And would like to know how many colors you need, and how to color
    197 them. Well, as Sage was specially built to help you solve this
    198 kind of tremendously exciting questions, here is the way to solve them :
     191them. Well, as Sage was especially built to help you solve this
     192kind of tremendously exciting question, here is the way to solve them:
    199193
    200     * First, create the graph of Western Europe in Sage
    201     * Use the ``vertex_coloring()`` method
     194    1. Create the graph of Western Europe in Sage
     195    2. Use the :meth:`vertex_coloring` method
    202196
    203 In Sage ::
     197In Sage::
    204198
    205199    sage: g=Graph({"France":["Italy","Spain","Swiss","Luxembourg","Belgium",
    206200                             "Germany","Austria"],
     
    216210     ['Belgium', 'Swiss'],
    217211     ['Luxembourg', 'Italy']]
    218212   
    219 You can now look for your pens. 4 of them :-)
     213You can now look for your pens---four of them.
    220214
    221215For more information on graph
    222 coloring : `Graph coloring <http://en.wikipedia.org/wiki/Graph_coloring>`_
     216coloring, see `Graph coloring <http://en.wikipedia.org/wiki/Graph_coloring>`_.
    223217
    224 For more informations on why it could not have required more pens :
    225 `Four color theorem <http://en.wikipedia.org/wiki/Four_color_theorem>`_
     218For more informations on why it could not have required more pens, see the
     219`Four color theorem
     220<http://en.wikipedia.org/wiki/Four_color_theorem>`_.
    226221
    227222Edge coloring
    228223^^^^^^^^^^^^^^
    229224
    230 You are organizing a soccer tournament ( or table tennis if you
    231 do not like soccer, but this is not really relevant ), with 10
    232 different teams that are to play against each other. Besides,
    233 the teams will play every Wednesday and will not be able to play
    234 two times the same day. How can you schedule them in such a way
    235 that the tournament will not last for too long ?
     225You are organizing a soccer tournament, with ten different teams that
     226are to play against each other. The teams will play every Wednesday
     227and will not be able to play two times on the same day. How can you
     228schedule them in such a way that the tournament will not last for too
     229long?
    236230
    237231This is an easy application of the Edge Coloring problem on a
    238232complete graph. If you number your teams as `1,...,10`, here
    239 is how you can obtain your scheduling ::
     233is how you can obtain your scheduling::
    240234
    241235    sage: g=graphs.CompleteGraph(10)
    242236    sage: g.edge_coloring()
     
    250244     [(0, 5, None), (1, 3, None), (6, 7, None), (2, 4, None), (8, 9, None)],
    251245     [(3, 8, None), (4, 6, None), (1, 9, None), (0, 7, None), (2, 5, None)]]
    252246
    253 And each line you see is the set of games being played on a particular
    254 day. If you prefer to plot the result, try ::
     247Each line you see is the set of games being played on a particular
     248day. If you prefer to plot the result, try::
    255249
    256250    sage: g.plot(edge_colors=g.edge_coloring(hex_colors=True))
    257251
    258 Pretty, isn´t it ? Each day has its own color.
     252Pretty, isn't it? Each day has its own color.
    259253
    260 
    261 
    262 Two links for more information :
     254Two links for more information:
    263255    * `About edge coloring <http://en.wikipedia.org/wiki/Edge_coloring>`_
    264256    * `About the scheduling of tournaments <http://en.wikipedia.org/wiki/Round-robin>`_
    265257