Ticket #5793: cliquer-5-ref.patch

sage/graphs/cliquer.pyx

@@ -94 +94 @@
     
     EXAMPLES::
     
-    sage: C = Graph('DJ{')
-    sage: clique_number(C)
-    4
-    sage: G = Graph({0:[1,2,3], 1:[2], 3:[0,1]})
-    sage: G.show(figsize=[2,2])
-    sage: clique_number(G)
-    3
+        sage: C = Graph('DJ{')
+        sage: clique_number(C)
+        4
+        sage: G = Graph({0:[1,2,3], 1:[2], 3:[0,1]})
+        sage: G.show(figsize=[2,2])
+        sage: clique_number(G)
+        3
     """
     graph=graph.relabel(inplace=False)
     cdef graph_t *g
@@ -116 +116 @@
 
 
 def list_composition(a,b):
+    """
+    Composes a list ``a`` with a map ``b``.
+    
+    EXAMPLE::
+    
+        sage: from sage.graphs.cliquer import list_composition
+        sage: list_composition([1,3,'a'], {'a':'b', 1:2, 2:3, 3:4})
+        [2, 4, 'b']
+    
+    """
     value=[]
     for i in a:
         value.append(b[i])

sage/graphs/graph.py

@@ -9755 +9755 @@
 
     ### Cliques
     
-    def cliques(self):
-        """
-        Returns the list of maximal cliques. Each maximal clique is
-        represented by a list of vertices.
-        
-        Currently only implemented for undirected graphs. Use
-        to_undirected to convert a digraph to an undirected graph.
-        
-        Maximal cliques are the largest complete subgraphs containing a
-        given point. This function is based on Networkx's implementation of
-        the Bron and Kerbosch Algorithm, [1].
-        
+    def cliques_maximal(self):
+        """
+        Returns the list of all maximal cliques, with each clique represented
+        by a list of vertices. A clique is an induced complete subgraph, and a
+        maximal clique is one not contained in a larger one.
+        
+        NOTES:
+        
+         - Currently only implemented for undirected graphs. Use to_undirected
+           to convert a digraph to an undirected graph.
+        
+        ALGORITHM:
+        
+         - This function is based on Networkx's implementation of the Bron and
+           Kerbosch Algorithm, [1].
+            
         REFERENCE:
 
         - [1] Coen Bron and Joep Kerbosch. (1973). Algorithm 457:
@@ -9776 +9780 @@
         
         EXAMPLES::
         
-            sage: (graphs.ChvatalGraph()).cliques()
+            sage: graphs.ChvatalGraph().cliques_maximal()
             [[0, 1], [0, 4], [0, 6], [0, 9], [2, 1], [2, 3], [2, 6], [2, 8], [3, 4], [3, 7], [3, 9], [5, 1], [5, 4], [5, 10], [5, 11], [7, 1], [7, 8], [7, 11], [8, 4], [8, 10], [10, 6], [10, 9], [11, 6], [11, 9]]
             sage: G = Graph({0:[1,2,3], 1:[2], 3:[0,1]})
             sage: G.show(figsize=[2,2])
-            sage: G.cliques()
+            sage: G.cliques_maximal()
             [[0, 1, 2], [0, 1, 3]]
+            sage: C=graphs.PetersenGraph()
+            sage: C.cliques_maximal()
+            [[0, 1], [0, 4], [0, 5], [2, 1], [2, 3], [2, 7], [3, 4], [3, 8], [6, 1], [6, 8], [6, 9], [7, 5], [7, 9], [8, 5], [9, 4]]
+            sage: C = Graph('DJ{')
+            sage: C.cliques_maximal()
+            [[4, 1, 2, 3], [4, 0]]
+
         """
         import networkx.cliques
         return networkx.cliques.find_cliques(self.networkx_graph(copy=False))
         
+    def cliques(self):
+        """
+        (Deprecated) alias for ``cliques_maximal``. See that function for more
+        details.
+        
+        EXAMPLE::
+        
+            sage: C = Graph('DJ{')
+            sage: C.cliques()
+            doctest:...: DeprecationWarning: The function 'cliques' has been deprecated. Use 'cliques_maximal' or 'cliques_maximum'.
+            [[4, 1, 2, 3], [4, 0]]
+
+        """
+        from sage.misc.misc import deprecation
+        deprecation("The function 'cliques' has been deprecated. Use " + \
+                    "'cliques_maximal' or 'cliques_maximum'.")
+        return self.cliques_maximal()
+        
+    def cliques_maximum(self):
+        """
+        Returns the list of all maximum cliques, with each clique represented
+        by a list of vertices. A clique is an induced complete subgraph, and a
+        maximum clique is one of maximal order.
+        
+        NOTES:
+        
+         - Currently only implemented for undirected graphs. Use to_undirected
+           to convert a digraph to an undirected graph.
+        
+        ALGORITHM:
+        
+         - This function is based on Cliquer, [1].
+            
+        REFERENCE:
+
+        - [1] Sampo Niskanen and Patric R. J. Östergård, "Cliquer User's Guide,
+          Version 1.0," Communications Laboratory, Helsinki University of
+          Technology, Espoo, Finland, Tech. Rep. T48, 2003.
+        
+        EXAMPLES::
+        
+            sage: graphs.ChvatalGraph().cliques_maximum()
+            [[0, 1], [0, 4], [0, 6], [0, 9], [1, 2], [1, 5], [1, 7], [2, 3], [2, 6], [2, 8], [3, 4], [3, 7], [3, 9], [4, 5], [4, 8], [5, 10], [5, 11], [6, 10], [6, 11], [7, 8], [7, 11], [8, 10], [9, 10], [9, 11]]
+            sage: G = Graph({0:[1,2,3], 1:[2], 3:[0,1]})
+            sage: G.show(figsize=[2,2])
+            sage: G.cliques_maximum()
+            [[0, 1, 2], [0, 1, 3]]
+            sage: C=graphs.PetersenGraph()
+            sage: C.cliques_maximum()
+            [[0, 1], [0, 4], [0, 5], [1, 2], [1, 6], [2, 3], [2, 7], [3, 4], [3, 8], [4, 9], [5, 7], [5, 8], [6, 8], [6, 9], [7, 9]]
+            sage: C = Graph('DJ{')
+            sage: C.cliques_maximum()
+            [[1, 2, 3, 4]]
+
+        """
+        from sage.graphs.cliquer import all_max_clique
+        return sorted(all_max_clique(self))
+
+    def clique_maximum(self):
+        """
+        Returns the vertex set of a maximal order complete subgraph.
+        
+        NOTE:
+        
+         - Currently only implemented for undirected graphs. Use to_undirected
+           to convert a digraph to an undirected graph.
+        
+        ALGORITHM:
+        
+         - This function is based on Cliquer, [1].
+            
+        REFERENCE:
+
+        - [1] Sampo Niskanen and Patric R. J. Östergård, "Cliquer User's Guide,
+          Version 1.0," Communications Laboratory, Helsinki University of
+          Technology, Espoo, Finland, Tech. Rep. T48, 2003.
+        
+        EXAMPLES::
+        
+            sage: C=graphs.PetersenGraph()
+            sage: C.clique_maximum()
+            [7, 9]
+            sage: C = Graph('DJ{')
+            sage: C.clique_maximum()
+            [1, 2, 3, 4]
+
+        """
+        from sage.graphs.cliquer import max_clique
+        return max_clique(self)
+
+    def clique_number(self, algorithm="cliquer", cliques=None):
+        """
+        Returns the order of the largest clique of the graph (the clique
+        number).
+
+        NOTE:
+        
+         - Currently only implemented for undirected graphs. Use to_undirected
+           to convert a digraph to an undirected graph.
+
+        INPUT:
+        
+         - ``algorithm`` - either ``cliquer`` or ``networkx``
+        
+           - ``cliquer`` - This wraps the C program Cliquer, [1].
+        
+           - ``networkx`` - This function is based on Networkx's implementation
+                of the Bron and Kerbosch Algorithm, [2].
+            
+         - ``cliques'' - an optional list of cliques that can be input if
+              already computed. Ignored unless ``algorithm=='networkx'``.
+        
+        REFERENCE:
+
+        - [1] Sampo Niskanen and Patric R. J. Östergård, "Cliquer User's Guide,
+          Version 1.0," Communications Laboratory, Helsinki University of
+          Technology, Espoo, Finland, Tech. Rep. T48, 2003.
+
+        - [2] Coen Bron and Joep Kerbosch. (1973). Algorithm 457:
+          Finding All Cliques of an Undirected Graph. Commun. ACM. v
+          16. n 9.  pages 575-577. ACM Press. [Online] Available:
+          http://www.ram.org/computing/rambin/rambin.html
+        
+        EXAMPLES::
+        
+            sage: C = Graph('DJ{')
+            sage: C.clique_number()
+            4
+            sage: G = Graph({0:[1,2,3], 1:[2], 3:[0,1]})
+            sage: G.show(figsize=[2,2])
+            sage: G.clique_number()
+            3
+
+        """
+        if algorithm=="cliquer":
+            from sage.graphs.cliquer import clique_number
+            return clique_number(self)        
+        elif algorithm=="networkx":
+            import networkx.cliques
+            return networkx.cliques.graph_clique_number(self.networkx_graph(copy=False),cliques)
+        else:
+            raise NotImplementedError("Only 'networkx' and 'cliquer' are supported.")
+
+    def cliques_number_of(self, vertices=None, cliques=None, with_labels=False):
+        """
+        Returns a list of the number of maximal cliques containing each
+        vertex. (Returns a single value if only one input vertex).
+        
+        NOTES:
+        
+         - Currently only implemented for undirected graphs. Use to_undirected
+           to convert a digraph to an undirected graph.
+        
+        INPUT:
+        
+        -  ``vertices`` - the vertices to inspect (default is
+           entire graph)
+        
+        -  ``with_labels`` - (boolean) default False returns
+           list as above True returns a dictionary keyed by vertex labels
+        
+        -  ``cliques`` - list of cliques (if already
+           computed)
+        
+        
+        EXAMPLES::
+        
+            sage: C = Graph('DJ{')
+            sage: C.cliques_number_of()
+            [1, 1, 1, 1, 2]
+            sage: E = C.cliques_maximal()
+            sage: E
+            [[4, 1, 2, 3], [4, 0]]
+            sage: C.cliques_number_of(cliques=E)
+            [1, 1, 1, 1, 2]
+            sage: F = graphs.Grid2dGraph(2,3)
+            sage: X = F.cliques_number_of(with_labels=True)
+            sage: for v in sorted(X.iterkeys()):
+            ...    print v, X[v]
+            (0, 0) 2
+            (0, 1) 3
+            (0, 2) 2
+            (1, 0) 2
+            (1, 1) 3
+            (1, 2) 2
+            sage: F.cliques_number_of(vertices=[(0, 1), (1, 2)])
+            [3, 2]
+            sage: G = Graph({0:[1,2,3], 1:[2], 3:[0,1]})
+            sage: G.show(figsize=[2,2])
+            sage: G.cliques_number_of()
+            [2, 2, 1, 1]
+        """
+        import networkx.cliques
+        return networkx.cliques.number_of_cliques(self.networkx_graph(copy=False), vertices, cliques, with_labels)
+        
     def cliques_get_max_clique_graph(self, name=''):
         """
         Returns a graph constructed with maximal cliques as vertices, and
         edges between maximal cliques with common members in the original
         graph.
         
-        Currently only implemented for undirected graphs. Use
-        to_undirected to convert a digraph to an undirected graph.
-        
-        INPUT:
-        
+        NOTES:
+        
+         - Currently only implemented for undirected graphs. Use to_undirected
+           to convert a digraph to an undirected graph.
+        
+        INPUT:
         
         -  ``name`` - The name of the new graph.
         
-        
         EXAMPLES::
         
             sage: (graphs.ChvatalGraph()).cliques_get_max_clique_graph()
@@ -9817 +10023 @@
 
     def cliques_get_clique_bipartite(self, **kwds):
         """
-        Returns a bipartite graph constructed such that cliques are the
+        Returns a bipartite graph constructed such that maximal cliques are the
         right vertices and the left vertices are retained from the given
         graph. Right and left vertices are connected if the bottom vertex
         belongs to the clique represented by a top vertex.
         
-        Currently only implemented for undirected graphs. Use
-        to_undirected to convert a digraph to an undirected graph.
+        NOTES:
+        
+         - Currently only implemented for undirected graphs. Use to_undirected
+           to convert a digraph to an undirected graph.
         
         EXAMPLES::
         
@@ -9840 +10048 @@
         from bipartite_graph import BipartiteGraph
         return BipartiteGraph(networkx.cliques.make_clique_bipartite(self.networkx_graph(copy=False), **kwds))
 
-
-    def clique_number(self,algorithm="cliquer",cliques=None):
-        """
-        Returns the size of the largest clique of the graph (clique
-        number). By default, the Cliquer algorithm is used 
-        ( algorithm="cliquer" ) but you can also chose the networkx
-        algorithm instead ( algorithm="networkx" )
-
-        INPUT :
-
-        - ``cliques'' : This parameter is an optional list of cliques that can be input if already computed.         
-                        ONLY USED BY NetworkX !!!
-        
-        Currently only implemented for undirected graphs. Use
-        to_undirected to convert a digraph to an undirected graph.
-        
-        EXAMPLES::
-        
-            sage: C = Graph('DJ{')
-            sage: C.clique_number()
-            4
-            sage: G = Graph({0:[1,2,3], 1:[2], 3:[0,1]})
-            sage: G.show(figsize=[2,2])
-            sage: G.clique_number()
-            3
-        """
-        if algorithm=="cliquer":
-            from sage.graphs.cliquer import clique_number
-            return clique_number(self)        
-        elif algorithm=="networkx":
-            import networkx.cliques
-            return networkx.cliques.graph_clique_number(self.networkx_graph(copy=False),cliques)
-        else:
-            raise NotImplementedError("Only 'networkx' and 'cliquer' are supported.")
-
-
-    def maximum_clique(self):
-        """
-        Returns the vertex set of a maximum complete subgraph.
-        
-        Currently only implemented for undirected graphs. Use
-        to_undirected to convert a digraph to an undirected graph.
+    def independent_set(self):
+        """
+        Returns a maximal independent set, which is a set of vertices which
+        induces an empty subgraph. Uses Cliquer.
+        
+        NOTES:
+        
+         - Currently only implemented for undirected graphs. Use to_undirected
+           to convert a digraph to an undirected graph.
         
         EXAMPLES::
         
         sage: C=graphs.PetersenGraph()
-        sage: C.maximum_clique()
-        [7, 9]
-        """
-        from sage.graphs.cliquer import max_clique
-        return max_clique(self)
-
-    def maximum_independent_set(self):
-        """
-        Returns the vertex set of a independent (stable) subgraph.
-        
-        Currently only implemented for undirected graphs. Use
-        to_undirected to convert a digraph to an undirected graph.
-        
-        EXAMPLES::
-        
-        sage: C=graphs.PetersenGraph()
-        sage: C.maximum_independent_set()
+        sage: C.independent_set()
         [0, 3, 6, 7]
 
         """
         from sage.graphs.cliquer import max_clique
         return max_clique(self.complement())
 
-    def maximum_cliques(self):
-        """
-        Returns the vertex sets of *ALL* the maximum complete subgraphs.
-        
-        Currently only implemented for undirected graphs. Use
-        to_undirected to convert a digraph to an undirected graph.
-        
-        EXAMPLES::
-        
-        sage: C=graphs.PetersenGraph()
-        sage: C.maximum_cliques()
-        [[2, 7], [7, 9], [6, 8], [6, 9], [0, 4], [4, 9], [5, 7], [0, 5], [5, 8], [3, 4], [2, 3], [3, 8], [1, 6], [0, 1], [1, 2]]
-        """
-
-        from sage.graphs.cliquer import all_max_clique
-        return all_max_clique(self)
-
-    def cliques_vertex_clique_number(self, algorithm="cliquer",vertices=None, with_labels=False, cliques=None):
+    def cliques_vertex_clique_number(self, algorithm="cliquer", vertices=None,
+                                     with_labels=False, cliques=None):
         r"""
         Returns a list of sizes of the largest maximal cliques containing
         each vertex. (Returns a single value if only one input vertex).
         
-        Currently only implemented for undirected graphs. Use
-        to_undirected to convert a digraph to an undirected graph.
-        
-        INPUT:
-        
-        -  ``algorithm'' - "cliquer" or "networkx"
-
-        -  ``vertices`` - the vertices to inspect (default is
-           entire graph)
-                        ONLY USED BY NetworkX !!!           
-        
-        -  ``with_labels`` - (boolean) default False returns
-           list as above True returns a dictionary keyed by vertex labels
-                        ONLY USED BY NetworkX !!!
-        
-        -  ``cliques`` - list of cliques (if already
-           computed)
-                        ONLY USED BY NetworkX !!!        
+        NOTES:
+        
+         - Currently only implemented for undirected graphs. Use to_undirected
+           to convert a digraph to an undirected graph.
+        
+        INPUT:
+        
+         - ``algorithm`` - either ``cliquer`` or ``networkx``
+        
+           - ``cliquer`` - This wraps the C program Cliquer, [1].
+        
+           - ``networkx`` - This function is based on Networkx's implementation
+                of the Bron and Kerbosch Algorithm, [2].
+
+        -  ``vertices`` - the vertices to inspect (default is entire graph).
+           Ignored unless ``algorithm=='networkx'``.
+        
+        -  ``with_labels`` - (boolean) default False returns list as above
+           True returns a dictionary keyed by vertex labels. Ignored unless
+           ``algorithm=='networkx'``.
+        
+        -  ``cliques`` - list of cliques (if already computed).  Ignored unless
+           ``algorithm=='networkx'``.
         
         EXAMPLES::
         
             sage: C = Graph('DJ{')
             sage: C.cliques_vertex_clique_number()
             [2, 4, 4, 4, 4]
-            sage: E = C.cliques()
+            sage: E = C.cliques_maximal()
             sage: E
             [[4, 1, 2, 3], [4, 0]]
             sage: C.cliques_vertex_clique_number(cliques=E,algorithm="networkx")
@@ -9976 +10124 @@
             sage: G.show(figsize=[2,2])
             sage: G.cliques_vertex_clique_number()
             [3, 3, 3, 3]
+
         """
 
         if algorithm=="cliquer":
@@ -9993 +10142 @@
         else:
             raise NotImplementedError("Only 'networkx' and 'cliquer' are supported.")
 
-        
-    def cliques_number_of(self, vertices=None, cliques=None, with_labels=False):
-        """
-        Returns a list of the number of maximal cliques containing each
-        vertex. (Returns a single value if only one input vertex).
-        
-        Currently only implemented for undirected graphs. Use
-        to_undirected to convert a digraph to an undirected graph.
-        
-        INPUT:
-        
+    def cliques_containing_vertex(self, vertices=None, cliques=None, with_labels=False):
+        """
+        Returns the cliques containing each vertex, represented as a list
+        of lists. (Returns a single list if only one input vertex).
+        
+        NOTE:
+        
+         - Currently only implemented for undirected graphs. Use to_undirected
+           to convert a digraph to an undirected graph.
+        
+        INPUT:
         
         -  ``vertices`` - the vertices to inspect (default is
            entire graph)
@@ -10014 +10163 @@
         -  ``cliques`` - list of cliques (if already
            computed)
         
-        
-        EXAMPLES::
-        
-            sage: C = Graph('DJ{')
-            sage: C.cliques_number_of()
-            [1, 1, 1, 1, 2]
-            sage: E = C.cliques()
-            sage: E
-            [[4, 1, 2, 3], [4, 0]]
-            sage: C.cliques_number_of(cliques=E)
-            [1, 1, 1, 1, 2]
-            sage: F = graphs.Grid2dGraph(2,3)
-            sage: X = F.cliques_number_of(with_labels=True)
-            sage: for v in sorted(X.iterkeys()):
-            ...    print v, X[v]
-            (0, 0) 2
-            (0, 1) 3
-            (0, 2) 2
-            (1, 0) 2
-            (1, 1) 3
-            (1, 2) 2
-            sage: F.cliques_number_of(vertices=[(0, 1), (1, 2)])
-            [3, 2]
-            sage: G = Graph({0:[1,2,3], 1:[2], 3:[0,1]})
-            sage: G.show(figsize=[2,2])
-            sage: G.cliques_number_of()
-            [2, 2, 1, 1]
-        """
-        import networkx.cliques
-        return networkx.cliques.number_of_cliques(self.networkx_graph(copy=False), vertices, cliques, with_labels)
-        
-    def cliques_containing_vertex(self, vertices=None, cliques=None, with_labels=False):
-        """
-        Returns the cliques containing each vertex, represented as a list
-        of lists. (Returns a single list if only one input vertex).
-        
-        Currently only implemented for undirected graphs. Use
-        to_undirected to convert a digraph to an undirected graph.
-        
-        INPUT:
-        
-        
-        -  ``vertices`` - the vertices to inspect (default is
-           entire graph)
-        
-        -  ``with_labels`` - (boolean) default False returns
-           list as above True returns a dictionary keyed by vertex labels
-        
-        -  ``cliques`` - list of cliques (if already
-           computed)
-        
-        
         EXAMPLES::
         
             sage: C = Graph('DJ{')
             sage: C.cliques_containing_vertex()
             [[[4, 0]], [[4, 1, 2, 3]], [[4, 1, 2, 3]], [[4, 1, 2, 3]], [[4, 1, 2, 3], [4, 0]]]
-            sage: E = C.cliques()
+            sage: E = C.cliques_maximal()
             sage: E
             [[4, 1, 2, 3], [4, 0]]
             sage: C.cliques_containing_vertex(cliques=E)
@@ -10092 +10189 @@
             sage: G.show(figsize=[2,2])
             sage: G.cliques_containing_vertex()
             [[[0, 1, 2], [0, 1, 3]], [[0, 1, 2], [0, 1, 3]], [[0, 1, 2]], [[0, 1, 3]]]
+
         """
         import networkx.cliques
         return networkx.cliques.cliques_containing_node(self.networkx_graph(copy=False), vertices, cliques, with_labels)