GenericGraph.adjacency_matrix: If vertices=True, edges=True, construc…

…t a morphism

src/sage/graphs/generic_graph.py

@@ -2127,15 +2127,23 @@ def incidence_matrix(self, oriented=None, sparse=True, vertices=None, edges=None
         - ``sparse`` -- boolean (default: ``True``); whether to use a sparse or
           a dense matrix
 
-        - ``vertices`` -- list (default: ``None``); when specified, the `i`-th
-          row of the matrix corresponds to the `i`-th vertex in the ordering of
-          ``vertices``, otherwise, the `i`-th row of the matrix corresponds to
-          the `i`-th vertex in the ordering given by method :meth:`vertices`.
+        - ``vertices`` -- list, ``None``, or ``True`` (default: ``None``);
 
-        - ``edges`` -- list (default: ``None``); when specified, the `i`-th
-          column of the matrix corresponds to the `i`-th edge in the ordering of
-          ``edges``, otherwise, the `i`-th column of the matrix corresponds to
-          the `i`-th edge in the ordering given by method :meth:`edge_iterator`.
+          - when a list, the `i`-th row of the matrix corresponds to the `i`-th
+            vertex in the ordering of ``vertices``,
+          - when ``None``, the `i`-th row of the matrix corresponds to
+            the `i`-th vertex in the ordering given by method :meth:`vertices`,
+          - when ``True``, construct a morphism of free modules instead of a matrix,
+            where the codomain's basis is indexed by the vertices.
+
+        - ``edges`` -- list, ``None``, or ``True`` (default: ``None``);
+
+          - when a list, the `i`-th column of the matrix corresponds to the `i`-th
+            edge in the ordering of ``edges``,
+          - when ``None``, the `i`-th column of the matrix corresponds to
+            the `i`-th edge in the ordering given by method :meth:`edge_iterator`,
+          - when ``True``, construct a morphism of free modules instead of a matrix,
+            where the domain's basis is indexed by the edges.
 
         - ``base_ring`` -- a ring (default: ``ZZ``); the base ring of the matrix
           space to use.
@@ -2259,6 +2267,25 @@ def incidence_matrix(self, oriented=None, sparse=True, vertices=None, edges=None
             ValueError: matrix is immutable; please change a copy instead
             (i.e., use copy(M) to change a copy of M).
 
+        Creating a module morphism::
+
+            sage: # needs sage.modules
+            sage: D12 = posets.DivisorLattice(12).hasse_diagram()
+            sage: phi_VE = D12.incidence_matrix(vertices=True, edges=True); phi_VE
+            Generic morphism:
+              From: Free module generated by
+                      {(1, 2), (1, 3), (2, 4), (2, 6), (3, 6), (4, 12), (6, 12)}
+                    over Integer Ring
+              To:   Free module generated by {1, 2, 3, 4, 6, 12} over Integer Ring
+            sage: print(phi_VE._unicode_art_matrix())
+                         (1, 2)  (1, 3)  (2, 4)  (2, 6)  (3, 6) (4, 12) (6, 12)
+                      1⎛     -1      -1       0       0       0       0       0⎞
+                      2⎜      1       0      -1      -1       0       0       0⎟
+                      3⎜      0       1       0       0      -1       0       0⎟
+                      4⎜      0       0       1       0       0      -1       0⎟
+                      6⎜      0       0       0       1       1       0      -1⎟
+                     12⎝      0       0       0       0       0       1       1⎠
+
         TESTS::
 
             sage: P5 = graphs.PathGraph(5)
@@ -2280,15 +2307,24 @@ def incidence_matrix(self, oriented=None, sparse=True, vertices=None, edges=None
         if oriented is None:
             oriented = self.is_directed()
 
+        row_keys = None
+        if vertices is True:
+            vertices = self.vertices(sort=False)
+            row_keys = tuple(vertices)  # because a list is not hashable
         if vertices is None:
             vertices = self.vertices(sort=False)
         elif (len(vertices) != self.num_verts() or
               set(vertices) != set(self.vertex_iterator())):
             raise ValueError("parameter vertices must be a permutation of the vertices")
 
+        column_keys = None
         verts = {v: i for i, v in enumerate(vertices)}
-        if edges is None:
-            edges = self.edge_iterator(labels=False)
+        use_edge_labels = kwds.pop('use_edge_labels', False)
+        if edges is True:
+            edges = self.edges(labels=use_edge_labels)
+            column_keys = tuple(edges)  # because an EdgesView is not hashable
+        elif edges is None:
+            edges = self.edge_iterator(labels=use_edge_labels)
         elif len(edges) != self.size():
             raise ValueError("parameter edges must be a permutation of the edges")
         else:
@@ -2320,8 +2356,13 @@ def reorder(u, v):
                 m[verts[e[0]], i] += 1
                 m[verts[e[1]], i] += 1
 
+        if row_keys is not None or column_keys is not None:
+            m.set_immutable()
+            return matrix(m, row_keys=row_keys, column_keys=column_keys)
+
         if immutable:
             m.set_immutable()
+
         return m
 
     def distance_matrix(self, vertices=None, *, base_ring=None, **kwds):