# 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


6  6  
7  7  sage/graphs/cliquer 
8  8  sage/graphs/graph 
 9  sage/graphs/graph_coloring 
9  10  sage/graphs/graph_generators 
10  11  sage/graphs/graph_database 
11  12  sage/graphs/graph_list 
diff r fee71ad457d0 r bc59642e3e2c sage/graphs/graph_coloring.py
a

b


20  20  from graph_generators import GraphGenerators 
21  21  
22  22  def all_graph_colorings(G,n,count_only=False): 
23   """ 
24   Computes all ncolorings of the graph G by casting the graph 
 23  r""" 
 24  Computes all `n`colorings of the graph `G` by casting the graph 
25  25  coloring problem into an exact cover problem, and passing this 
26  26  into an implementation of the Dancing Links algorithm described 
27  27  by Knuth (who attributes the idea to Hitotumatu and Noshita). 
28  28  
29  29  The construction works as follows: 
30  30  (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 
32  32  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 
34  34  these columns indicate that a particular edge is 
35  35  incident to a vertex with a certain color. 
36  36  
37  37  (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` 
40  40  in the appropriate column for each edge incident to the 
41  41  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 
44  44  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 
47  47  get added to the cover solutions "for free" during the 
48  48  backtracking. 
49  49  
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` 
51  51  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. 
54  54  Backconversion to a coloring solution is a simple scan of the 
55   solutions, which will contain V + (n2)*E entries, so 
56   runs in O(V^3) time also. For most graphs, the conversion 
 55  solutions, which will contain `V + (n2)*E` entries, so 
 56  runs in `O(V^3)` time also. For most graphs, the conversion 
57  57  will be much faster  for example, a planar graph will be 
58   transformed for 4coloring in linear time since E = O(V). 
 58  transformed for `4`coloring in linear time since `E = O(V)`. 
59  59  
60  60  REFERENCES: 
61  61  http://wwwcsstaff.stanford.edu/~uno/papers/dancingcolor.ps.gz 
62  62  
63   EXAMPLES: 
 63  EXAMPLES:: 
 64  
64  65  sage: from sage.graphs.graph_coloring import all_graph_colorings 
65  66  sage: G = Graph({0:[1,2,3],1:[2]}) 
66  67  sage: n = 0 
… 
… 

76  77  sage: print "G has %s 3colorings."%n 
77  78  G has 12 3colorings. 
78  79  
79   TESTS: 
 80  TESTS:: 
 81  
80  82  sage: G = Graph({0:[1,2,3],1:[2]}) 
81  83  sage: for C in all_graph_colorings(G,0): print C 
82  84  sage: for C in all_graph_colorings(G,1): print C 
… 
… 

142  144  raise RuntimeError, "Too much recursion! Graph coloring failed." 
143  145  
144  146  def 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. 
148  150  
149   EXAMPLES: 
 151  EXAMPLES:: 
 152  
150  153  sage: from sage.graphs.graph_coloring import first_coloring 
151  154  sage: G = Graph({0:[1,2,3],1:[2]}) 
152  155  sage: first_coloring(G,3) 
… 
… 

158  161  return C 
159  162  
160  163  def number_of_n_colorings(G,n): 
161   """ 
162   Given a graph G and a natural number n, returns the number of 
163   ncolorings 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. 
164  167  
165   EXAMPLES: 
 168  EXAMPLES:: 
 169  
166  170  sage: from sage.graphs.graph_coloring import number_of_n_colorings 
167  171  sage: G = Graph({0:[1,2,3],1:[2]}) 
168  172  sage: number_of_n_colorings(G,3) 
… 
… 

184  188  return m 
185  189  
186  190  def numbers_of_colorings(G): 
187   """ 
188   Returns the number of ncolorings 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`. 
190  194  
191   EXAMPLES: 
 195  EXAMPLES:: 
 196  
192  197  sage: from sage.graphs.graph_coloring import numbers_of_colorings 
193  198  sage: G = Graph({0:[1,2,3],1:[2]}) 
194  199  sage: numbers_of_colorings(G) 
… 
… 

198  203  return [number_of_n_colorings(G,i) for i in range(0,o+1)] 
199  204  
200  205  def chromatic_number(G): 
201   """ 
 206  r""" 
202  207  Returns the minimal number of colors needed to color the 
203   vertices of the graph G. 
 208  vertices of the graph `G`. 
204  209  
205   EXAMPLES: 
 210  EXAMPLES:: 
 211  
206  212  sage: from sage.graphs.graph_coloring import chromatic_number 
207  213  sage: G = Graph({0:[1,2,3],1:[2]}) 
208  214  sage: chromatic_number(G) 
… 
… 

229  235  return n 
230  236  
231  237  class Test: 
232   """ 
 238  r""" 
233  239  This class performs randomized testing for all_graph_colorings. 
234  240  Since everything else in this file is derived from 
235  241  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()`` 
237  243  uses an entirely different algorithm, so we provide a good, 
238  244  independent test. 
239  245  """ 
240  246  
241  247  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 
244  250  other methods are added, it should call them, too. 
245  251  
246   TESTS: 
 252  TESTS:: 
 253  
247  254  sage: from sage.graphs.graph_coloring import Test 
248  255  sage: Test().random(1) 
249  256  """ 
250  257  self.random_all_graph_colorings(tests) 
251  258  
252  259  def random_all_graph_colorings(self,tests = 1000): 
253   """ 
 260  r""" 
254  261  Verifies the results of all_graph_colorings in three ways: 
255  262  1) all colorings are unique 
256   2) number of mcolorings is P(m) (where P is the chromatic 
 263  2) number of mcolorings is `P(m)` (where `P` is the chromatic 
257  264  polynomial of the graph being tested) 
258  265  3) colorings are valid  that is, that no two vertices of 
259  266  the same color share an edge. 
260  267  
261   TESTS: 
 268  TESTS:: 
 269  
262  270  sage: from sage.graphs.graph_coloring import Test 
263  271  sage: Test().random_all_graph_colorings(1) 
264  272  """ 