Ticket #7527: trac_7527.patch

File trac_7527.patch, 7.9 KB (added by ncohen, 11 years ago)
  • doc/en/reference/graphs.rst

    # HG changeset patch
    # User Nathann Cohen <nathann.cohen@gmail.com>
    # Date 1259138586 -3600
    # Node ID bc59642e3e2cafbdf8153136d5d5e198fe523ab6
    # Parent  fee71ad457d0b6881f989cbe69b9bfe2eee0cd55
    Adds graph_coloring to the reference manual, plus docstring fixes
    
    diff -r fee71ad457d0 -r bc59642e3e2c doc/en/reference/graphs.rst
    a b  
    66
    77   sage/graphs/cliquer
    88   sage/graphs/graph
     9   sage/graphs/graph_coloring
    910   sage/graphs/graph_generators
    1011   sage/graphs/graph_database
    1112   sage/graphs/graph_list
  • sage/graphs/graph_coloring.py

    diff -r fee71ad457d0 -r bc59642e3e2c sage/graphs/graph_coloring.py
    a b  
    2020from graph_generators import GraphGenerators
    2121
    2222def all_graph_colorings(G,n,count_only=False):
    23     """
    24     Computes all n-colorings of the graph G by casting the graph
     23    r"""
     24    Computes all `n`-colorings of the graph `G` by casting the graph
    2525    coloring problem into an exact cover problem, and passing this
    2626    into an implementation of the Dancing Links algorithm described
    2727    by Knuth (who attributes the idea to Hitotumatu and Noshita).
    2828
    2929    The construction works as follows:
    3030     (columns)
    31       * The first |V| columns correspond to a vertex -- a 1 in this
     31      * The first `|V|` columns correspond to a vertex -- a `1` in this
    3232           column indicates that that vertex has a color.
    33       * After those |V| columns, we add n*|E| columns -- a 1 in
     33      * After those `|V|` columns, we add `n*|E|` columns -- a `1` in
    3434           these columns indicate that a particular edge is
    3535           incident to a vertex with a certain color.
    3636
    3737     (rows)
    38       * For each vertex, add n rows; one for each color c.  Place
    39            a 1 in the column corresponding to the vertex, and a 1
     38      * For each vertex, add `n` rows; one for each color `c`.  Place
     39           a `1` in the column corresponding to the vertex, and a `1`
    4040           in the appropriate column for each edge incident to the
    4141           vertex, indicating that that edge is incident to the
    42            color c.
    43       * If n > 2, the above construction cannot be exactly covered
     42           color `c`.
     43      * If `n > 2`, the above construction cannot be exactly covered
    4444           since each edge will be incident to only two vertices
    45            (and hence two colors) - so we add n*|E| rows, each one
    46            containing a 1 for each of the n*|E| columns.  These
     45           (and hence two colors) - so we add `n*|E|` rows, each one
     46           containing a `1` for each of the `n*|E|` columns.  These
    4747           get added to the cover solutions "for free" during the
    4848           backtracking.
    4949
    50     Note that this construction results in n*|V| + 2*n*|E| + n*|E|
     50    Note that this construction results in `n*|V| + 2*n*|E| + n*|E|`
    5151    entries in the matrix.  The Dancing Links algorithm uses a
    52     sparse representation, so if the graph is simple, |E| <= |V|^2
    53     and n <= |V|, this construction runs in O(|V|^3) time.
     52    sparse representation, so if the graph is simple, `|E| \leq |V|^2`
     53    and `n <= |V|`, this construction runs in `O(|V|^3)` time.
    5454    Back-conversion to a coloring solution is a simple scan of the
    55     solutions, which will contain |V| + (n-2)*|E| entries,  so
    56     runs in O(|V|^3) time also.  For most graphs, the conversion
     55    solutions, which will contain `|V| + (n-2)*|E|` entries,  so
     56    runs in `O(|V|^3)` time also.  For most graphs, the conversion
    5757    will be much faster -- for example, a planar graph will be
    58     transformed for 4-coloring in linear time since |E| = O(|V|).
     58    transformed for `4`-coloring in linear time since `|E| = O(|V|)`.
    5959
    6060    REFERENCES:
    6161        http://www-cs-staff.stanford.edu/~uno/papers/dancing-color.ps.gz
    6262
    63     EXAMPLES:
     63    EXAMPLES::
     64
    6465        sage: from sage.graphs.graph_coloring import all_graph_colorings
    6566        sage: G = Graph({0:[1,2,3],1:[2]})
    6667        sage: n = 0
     
    7677        sage: print "G has %s 3-colorings."%n
    7778        G has 12 3-colorings.
    7879
    79     TESTS:
     80    TESTS::
     81
    8082        sage: G = Graph({0:[1,2,3],1:[2]})
    8183        sage: for C in all_graph_colorings(G,0): print C
    8284        sage: for C in all_graph_colorings(G,-1): print C
     
    142144        raise RuntimeError, "Too much recursion!  Graph coloring failed."
    143145
    144146def first_coloring(G,n=0):
    145     """
    146     Given a graph, and optionally a natural number n, returns
    147     the first coloring we find with at least n colors.
     147    r"""
     148    Given a graph, and optionally a natural number `n`, returns
     149    the first coloring we find with at least `n` colors.
    148150
    149     EXAMPLES:
     151    EXAMPLES::
     152
    150153        sage: from sage.graphs.graph_coloring import first_coloring
    151154        sage: G = Graph({0:[1,2,3],1:[2]})
    152155        sage: first_coloring(G,3)
     
    158161            return C
    159162
    160163def number_of_n_colorings(G,n):
    161     """
    162     Given a graph G and a natural number n, returns the number of
    163     n-colorings of the graph.
     164    r"""
     165    Given a graph `G` and a natural number `n`, returns the number of
     166    `n`-colorings of the graph.
    164167
    165     EXAMPLES:
     168    EXAMPLES::
     169
    166170        sage: from sage.graphs.graph_coloring import number_of_n_colorings
    167171        sage: G = Graph({0:[1,2,3],1:[2]})
    168172        sage: number_of_n_colorings(G,3)
     
    184188    return m
    185189
    186190def numbers_of_colorings(G):
    187     """
    188     Returns the number of n-colorings of the graph G for n from
    189     0 to |V|.
     191    r"""
     192    Returns the number of `n`-colorings of the graph `G` for `n` from
     193    `0` to `|V|`.
    190194
    191     EXAMPLES:
     195    EXAMPLES::
     196
    192197        sage: from sage.graphs.graph_coloring import numbers_of_colorings
    193198        sage: G = Graph({0:[1,2,3],1:[2]})
    194199        sage: numbers_of_colorings(G)
     
    198203    return [number_of_n_colorings(G,i) for i in range(0,o+1)]
    199204
    200205def chromatic_number(G):
    201     """
     206    r"""
    202207    Returns the minimal number of colors needed to color the
    203     vertices of the graph G.
     208    vertices of the graph `G`.
    204209
    205     EXAMPLES:
     210    EXAMPLES::
     211
    206212        sage: from sage.graphs.graph_coloring import chromatic_number
    207213        sage: G = Graph({0:[1,2,3],1:[2]})
    208214        sage: chromatic_number(G)
     
    229235            return n   
    230236
    231237class Test:
    232     """
     238    r"""
    233239    This class performs randomized testing for all_graph_colorings.
    234240    Since everything else in this file is derived from
    235241    all_graph_colorings, this is a pretty good randomized tester for
    236     the entire file.  Note that for a graph G, G.chromatic_polynomial()
     242    the entire file.  Note that for a graph `G`, ``G.chromatic_polynomial()``
    237243    uses an entirely different algorithm, so we provide a good,
    238244    independent test.
    239245    """
    240246
    241247    def random(self,tests = 1000):
    242         """
    243         Calls self.random_all_graph_colorings().  In the future, if
     248        r"""
     249        Calls ``self.random_all_graph_colorings()``.  In the future, if
    244250        other methods are added, it should call them, too.
    245251       
    246         TESTS:
     252        TESTS::
     253
    247254            sage: from sage.graphs.graph_coloring import Test
    248255            sage: Test().random(1)
    249256        """
    250257        self.random_all_graph_colorings(tests)
    251258
    252259    def random_all_graph_colorings(self,tests = 1000):
    253         """
     260        r"""
    254261        Verifies the results of all_graph_colorings in three ways:
    255262            1) all colorings are unique
    256             2) number of m-colorings is P(m) (where P is the chromatic
     263            2) number of m-colorings is `P(m)` (where `P` is the chromatic
    257264               polynomial of the graph being tested)
    258265            3) colorings are valid -- that is, that no two vertices of
    259266               the same color share an edge.
    260267
    261         TESTS:
     268        TESTS::
     269
    262270            sage: from sage.graphs.graph_coloring import Test
    263271            sage: Test().random_all_graph_colorings(1)
    264272        """