Ticket #7527: trac_7527-rebased.patch

File trac_7527-rebased.patch, 7.2 KB (added by mvngu, 11 years ago)

rebased; based on Sage 4.3.alpha1

  • doc/en/reference/graphs.rst

    # HG changeset patch
    # User Nathann Cohen <nathann.cohen@gmail.com>
    # Date 1259138586 -3600
    # Node ID 8ca939870ef50e8f8ec3d94a0b9508d32489867c
    # Parent  18a4ec53e18a7dd51639dc0ea4f3bd9541430e32
    trac 7527: Adds graph_coloring to the reference manual, plus docstring fixes
    
    diff -r 18a4ec53e18a -r 8ca939870ef5 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 18a4ec53e18a -r 8ca939870ef5 sage/graphs/graph_coloring.py
    a b  
    2222from graph_generators import GraphGenerators
    2323
    2424def all_graph_colorings(G,n,count_only=False):
    25     """
    26     Computes all n-colorings of the graph G by casting the graph
     25    r"""
     26    Computes all `n`-colorings of the graph `G` by casting the graph
    2727    coloring problem into an exact cover problem, and passing this
    2828    into an implementation of the Dancing Links algorithm described
    2929    by Knuth (who attributes the idea to Hitotumatu and Noshita).
    3030
    3131    The construction works as follows:
    3232     (columns)
    33       * The first |V| columns correspond to a vertex -- a 1 in this
     33      * The first `|V|` columns correspond to a vertex -- a `1` in this
    3434           column indicates that that vertex has a color.
    35       * After those |V| columns, we add n*|E| columns -- a 1 in
     35      * After those `|V|` columns, we add `n*|E|` columns -- a `1` in
    3636           these columns indicate that a particular edge is
    3737           incident to a vertex with a certain color.
    3838
    3939     (rows)
    40       * For each vertex, add n rows; one for each color c.  Place
    41            a 1 in the column corresponding to the vertex, and a 1
     40      * For each vertex, add `n` rows; one for each color `c`.  Place
     41           a `1` in the column corresponding to the vertex, and a `1`
    4242           in the appropriate column for each edge incident to the
    4343           vertex, indicating that that edge is incident to the
    44            color c.
    45       * If n > 2, the above construction cannot be exactly covered
     44           color `c`.
     45      * If `n > 2`, the above construction cannot be exactly covered
    4646           since each edge will be incident to only two vertices
    47            (and hence two colors) - so we add n*|E| rows, each one
    48            containing a 1 for each of the n*|E| columns.  These
     47           (and hence two colors) - so we add `n*|E|` rows, each one
     48           containing a `1` for each of the `n*|E|` columns.  These
    4949           get added to the cover solutions "for free" during the
    5050           backtracking.
    5151
    52     Note that this construction results in n*|V| + 2*n*|E| + n*|E|
     52    Note that this construction results in `n*|V| + 2*n*|E| + n*|E|`
    5353    entries in the matrix.  The Dancing Links algorithm uses a
    54     sparse representation, so if the graph is simple, |E| <= |V|^2
    55     and n <= |V|, this construction runs in O(|V|^3) time.
     54    sparse representation, so if the graph is simple, `|E| \leq |V|^2`
     55    and `n <= |V|`, this construction runs in `O(|V|^3)` time.
    5656    Back-conversion to a coloring solution is a simple scan of the
    57     solutions, which will contain |V| + (n-2)*|E| entries,  so
    58     runs in O(|V|^3) time also.  For most graphs, the conversion
     57    solutions, which will contain `|V| + (n-2)*|E|` entries,  so
     58    runs in `O(|V|^3)` time also.  For most graphs, the conversion
    5959    will be much faster -- for example, a planar graph will be
    60     transformed for 4-coloring in linear time since |E| = O(|V|).
     60    transformed for `4`-coloring in linear time since `|E| = O(|V|)`.
    6161
    6262    REFERENCES:
    6363        http://www-cs-staff.stanford.edu/~uno/papers/dancing-color.ps.gz
    6464
    65     EXAMPLES:
     65    EXAMPLES::
     66
    6667        sage: from sage.graphs.graph_coloring import all_graph_colorings
    6768        sage: G = Graph({0:[1,2,3],1:[2]})
    6869        sage: n = 0
     
    7879        sage: print "G has %s 3-colorings."%n
    7980        G has 12 3-colorings.
    8081
    81     TESTS:
     82    TESTS::
     83
    8284        sage: G = Graph({0:[1,2,3],1:[2]})
    8385        sage: for C in all_graph_colorings(G,0): print C
    8486        sage: for C in all_graph_colorings(G,-1): print C
     
    172174                return C.values()
    173175
    174176def number_of_n_colorings(G,n):
    175     """
    176     Given a graph G and a natural number n, returns the number of
    177     n-colorings of the graph.
     177    r"""
     178    Given a graph `G` and a natural number `n`, returns the number of
     179    `n`-colorings of the graph.
    178180
    179     EXAMPLES:
     181    EXAMPLES::
     182
    180183        sage: from sage.graphs.graph_coloring import number_of_n_colorings
    181184        sage: G = Graph({0:[1,2,3],1:[2]})
    182185        sage: number_of_n_colorings(G,3)
     
    198201    return m
    199202
    200203def numbers_of_colorings(G):
    201     """
    202     Returns the number of n-colorings of the graph G for n from
    203     0 to |V|.
     204    r"""
     205    Returns the number of `n`-colorings of the graph `G` for `n` from
     206    `0` to `|V|`.
    204207
    205     EXAMPLES:
     208    EXAMPLES::
     209
    206210        sage: from sage.graphs.graph_coloring import numbers_of_colorings
    207211        sage: G = Graph({0:[1,2,3],1:[2]})
    208212        sage: numbers_of_colorings(G)
     
    212216    return [number_of_n_colorings(G,i) for i in range(0,o+1)]
    213217
    214218def chromatic_number(G):
    215     """
     219    r"""
    216220    Returns the minimal number of colors needed to color the
    217     vertices of the graph G.
     221    vertices of the graph `G`.
    218222
    219     EXAMPLES:
     223    EXAMPLES::
     224
    220225        sage: from sage.graphs.graph_coloring import chromatic_number
    221226        sage: G = Graph({0:[1,2,3],1:[2]})
    222227        sage: chromatic_number(G)
     
    645650        return g
    646651
    647652class Test:
    648     """
     653    r"""
    649654    This class performs randomized testing for all_graph_colorings.
    650655    Since everything else in this file is derived from
    651656    all_graph_colorings, this is a pretty good randomized tester for
    652     the entire file.  Note that for a graph G, G.chromatic_polynomial()
     657    the entire file.  Note that for a graph `G`, ``G.chromatic_polynomial()``
    653658    uses an entirely different algorithm, so we provide a good,
    654659    independent test.
    655660    """
    656661
    657662    def random(self,tests = 1000):
    658         """
    659         Calls self.random_all_graph_colorings().  In the future, if
     663        r"""
     664        Calls ``self.random_all_graph_colorings()``.  In the future, if
    660665        other methods are added, it should call them, too.
    661666       
    662         TESTS:
     667        TESTS::
     668
    663669            sage: from sage.graphs.graph_coloring import Test
    664670            sage: Test().random(1)
    665671        """
    666672        self.random_all_graph_colorings(tests)
    667673
    668674    def random_all_graph_colorings(self,tests = 1000):
    669         """
     675        r"""
    670676        Verifies the results of all_graph_colorings in three ways:
    671677            1) all colorings are unique
    672             2) number of m-colorings is P(m) (where P is the chromatic
     678            2) number of m-colorings is `P(m)` (where `P` is the chromatic
    673679               polynomial of the graph being tested)
    674680            3) colorings are valid -- that is, that no two vertices of
    675681               the same color share an edge.
    676682
    677         TESTS:
     683        TESTS::
     684
    678685            sage: from sage.graphs.graph_coloring import Test
    679686            sage: Test().random_all_graph_colorings(1)
    680687        """