Ticket #7533: trac_7533_distance_graphs.patch

sage/graphs/graph.py

@@ -5511 +5511 @@
             return 0
         return max(e)
 
+    def distance_graph(self, dist):
+        r"""
+        Returns the graph on the same vertex set as
+        the original graph but vertices are adjacent
+        in the returned graph if and only if they are
+        at a specified distance in the original graph.
+
+        INPUT:
+
+        - ``dist`` is a nonnegative integer or
+          ``Infinity``.  The latter describes
+          vertex pairs in separate components.
+
+        OUTPUT:
+
+        The returned value is an undirected graph.  Loops
+        will only be present in the distance 0 graph.  If
+        the original graph has a position dictionary specifying
+        locations of vertices for plotting, then this information
+        is copied over to the distance graph.  In some instances
+        this layout may not be the best, and might even be confusing
+        when edges run on top of each other.
+
+        EXAMPLES::
+
+            sage: G = graphs.CompleteGraph(3)
+            sage: H = G.cartesian_product(graphs.CompleteGraph(2))
+            sage: K = H.distance_graph(2)
+            sage: K.am()
+            [0 0 0 1 0 1]
+            [0 0 1 0 1 0]
+            [0 1 0 0 0 1]
+            [1 0 0 0 1 0]
+            [0 1 0 1 0 0]
+            [1 0 1 0 0 0]
+
+        A complete collection of distance graphs will have
+        adjacency matrices that sum to the matrix of all ones. ::
+
+            sage: P = graphs.PathGraph(20)
+            sage: all_ones = sum([P.distance_graph(i).am() for i in range(20)])
+            sage: all_ones == matrix(ZZ, 20, 20, [1]*400)
+            True
+
+        Four-bit strings differing in one bit is the same as
+        four-bit strings differing in three bits.  ::
+
+            sage: G = graphs.CubeGraph(4)
+            sage: H = G.distance_graph(3)
+            sage: G.is_isomorphic(H)
+            True
+
+        An example of using ``Infinity`` as the distance in
+        a graph that is not connected. ::
+
+            sage: G = graphs.CompleteGraph(3)
+            sage: H = G.disjoint_union(graphs.CompleteGraph(2))
+            sage: L = H.distance_graph(Infinity)
+            sage: L.am()
+            [0 0 0 1 1]
+            [0 0 0 1 1]
+            [0 0 0 1 1]
+            [1 1 1 0 0]
+            [1 1 1 0 0]
+
+        TESTS:
+
+        It is an error to provide a distance that is not an integer type. ::
+
+            sage: G = graphs.CompleteGraph(5)
+            sage: G.distance_graph('junk')
+            Traceback (most recent call last):
+            ...
+            TypeError: unable to convert x (=junk) to an integer
+
+        It is an error to provide a negative distance. ::
+
+            sage: G = graphs.CompleteGraph(5)
+            sage: G.distance_graph(-3)
+            Traceback (most recent call last):
+            ...
+            ValueError: Distance graph for a negative distance (d=-3) is not defined
+
+        AUTHOR:
+
+        Rob Beezer, 2009-11-25
+        """
+        from sage.rings.infinity import Infinity
+        from copy import copy
+        d = dist
+        if not(dist == Infinity):
+            d = Integer(dist)
+            if d < 0:
+                raise ValueError('Distance graph for a negative distance (d=%d) is not defined' % d)
+        vertices = {}
+        for v in self.vertex_iterator():
+            vertices[v] = {}
+        positions = copy(self.get_pos())
+        D = Graph(vertices, pos=positions, multiedges=False, loops=True)
+        D.name("Distance %s graph of " % str(d) + self.name())
+        for u in self.vertex_iterator():
+            for v in self.vertex_iterator():
+                if self.distance(u,v) == d:
+                    D.add_edge(u,v)
+        return D
+
     def girth(self):
         """
         Computes the girth of the graph. For directed graphs, computes the