gh-39518: line_graph for multigraphs
    
We generalize the `line_graph` method to graphs possibly with multiple
edges and/or loops.
It is useful in order to compute the line-graph of a multigraph but also
to generate the edge-colorings of a multigraph from the
`all_graph_coloring` method.

### 📝 Checklist

- [x] The title is concise and informative.
- [x] The description explains in detail what this PR is about.
- [ ] I have linked a relevant issue or discussion.
- [x] I have created tests covering the changes.
- [x] I have updated the documentation and checked the documentation
preview.
    
URL: #39518
Reported by: Fabien Vignes-Tourneret
Reviewer(s): David Coudert, Frédéric Chapoton

Author: Release Manager

src/sage/graphs/line_graph.pyx

@@ -127,6 +127,8 @@ Functions
 ---------
 """
 
+from sage.structure.element cimport parent
+
 
 def is_line_graph(g, certificate=False):
     r"""
@@ -263,21 +265,32 @@ def is_line_graph(g, certificate=False):
     return True
 
 
-def line_graph(g, labels=True):
+def line_graph(g, labels=True, return_labels=False):
     """
-    Return the line graph of the (di)graph ``g``.
+    Return the line graph of the (di)graph ``g`` (multiedges and loops allowed).
 
     INPUT:
 
     - ``labels`` -- boolean (default: ``True``); whether edge labels should be
       taken in consideration. If ``labels=True``, the vertices of the line graph
-      will be triples ``(u,v,label)``, and pairs of vertices otherwise.
-
-    The line graph of an undirected graph G is an undirected graph H such that
-    the vertices of H are the edges of G and two vertices e and f of H are
+      will be triples ``(u,v,label)``, and pairs of vertices otherwise.  In case
+      of multiple edges, the vertices of the line graph will be triples
+      ``(u,v,an integer)``.
+
+    - ``return_labels`` -- boolean (default: ``False``); whether edge labels should
+      be stored or not. If g has multiple edges and if ``return_labels=True``, the
+      method returns a list the first element of which is the line-graph of g
+      and the second element is a dictionary {vertex of the line-graph: former
+      corresponding edge with its original label}. If ``return_labels=False``,
+      the method returns only the line-graph.
+
+    The line graph of an undirected graph G is an undirected simple graph H such
+    that the vertices of H are the edges of G and two vertices e and f of H are
     adjacent if e and f share a common vertex in G. In other words, an edge in H
     represents a path of length 2 in G.
 
+    Loops are not adjacent to themselves.
+
     The line graph of a directed graph G is a directed graph H such that the
     vertices of H are the edges of G and two vertices e and f of H are adjacent
     if e and f share a common vertex in G and the terminal vertex of e is the
@@ -311,7 +324,7 @@ def line_graph(g, labels=True):
          (1, 2, None),
          (1, 3, None),
          (2, 3, None)]
-        sage: h.am()                                                                    # needs sage.modules
+        sage: h.am()                                                                # needs sage.modules
         [0 1 1 1 1 0]
         [1 0 1 1 0 1]
         [1 1 0 0 1 1]
@@ -321,7 +334,7 @@ def line_graph(g, labels=True):
         sage: h2 = g.line_graph(labels=False)
         sage: h2.vertices(sort=True)
         [(0, 1), (0, 2), (0, 3), (1, 2), (1, 3), (2, 3)]
-        sage: h2.am() == h.am()                                                         # needs sage.modules
+        sage: h2.am() == h.am()                                                     # needs sage.modules
         True
         sage: g = DiGraph([[1..4], lambda i,j: i < j])
         sage: h = g.line_graph()
@@ -338,6 +351,40 @@ def line_graph(g, labels=True):
          ((1, 3, None), (3, 4, None), None),
          ((2, 3, None), (3, 4, None), None)]
 
+    Examples with multiple edges::
+
+        sage: L = Graph([(0,1),(0,1),(1,2)],multiedges=True).line_graph()
+        sage: L.edges()
+        [((0, 1, 0), (0, 1, 1), None), ((0, 1, 1), (1, 2, 2), None),
+        ((0, 1, 0), (1, 2, 2), None)]
+        sage: G = Graph([(0,1),(0,1,'a'),(0,1,'b'),(0,2),(1,2,'c')],
+        ....: multiedges=True)
+        sage: L = G.line_graph(False,True)
+        sage: L[0].edges()
+        [((0, 1, 1), (0, 1, 2), None), ((0, 1, 0), (0, 1, 2), None),
+        ((0, 1, 2), (0, 2, 3), None), ((0, 1, 2), (1, 2, 4), None), ((0, 1, 0),
+        (0, 1, 1), None), ((0, 1, 1), (0, 2, 3), None), ((0, 1, 1),
+        (1, 2, 4), None), ((0, 1, 0), (0, 2, 3), None), ((0, 1, 0),
+        (1, 2, 4), None), ((0, 2, 3), (1, 2, 4), None)]
+        sage: L[1]
+        {(0, 1, 0): (0, 1, None),
+        (0, 1, 1): (0, 1, 'b'),
+        (0, 1, 2): (0, 1, 'a'),
+        (0, 2, 3): (0, 2, None),
+        (1, 2, 4): (1, 2, 'c')}
+        sage: g = DiGraph([(0,1),(0,1),(1,2)],multiedges=True)
+        sage: g.line_graph().edges()
+        [((0, 1, 1), (1, 2, 2), None), ((0, 1, 0), (1, 2, 2), None)]
+
+    An example with a loop::
+
+        sage: g = Graph([(0,0),(0,1),(0,2),(1,2)],multiedges=True,loops=True)
+        sage: L = g.line_graph()
+        sage: L.edges()
+        [((0, 0, None), (0, 1, None), None), ((0, 0, None), (0, 2, None), None),
+        ((0, 1, None), (0, 2, None), None), ((0, 1, None), (1, 2, None), None),
+        ((0, 2, None), (1, 2, None), None)]
+
     TESTS:
 
     :issue:`13787`::
@@ -351,17 +398,31 @@ def line_graph(g, labels=True):
     """
     cdef dict conflicts = {}
     cdef list elist = []
+    cdef dict origlabels_dic = {}  # stores original labels of edges in case of multiple edges
+
+    multiple = g.has_multiple_edges()
+
+    if multiple:
+        # As the edges of g are the vertices of its line graph, we need to distinguish between the mutliple edges of g.
+        # To this aim, we assign to each edge of g an integer label (between 0 and g.size() - 1) and set labels to True
+        # in order to keep these labels during the construction of the line graph.
+        labels = True
+        origlabels_dic = {(u, v, id): (u, v, label)
+                          for id, (u, v, label) in enumerate(g.edge_iterator())}
+        g = parent(g)([g, origlabels_dic.keys()], format='vertices_and_edges', multiedges=True)
 
-    g._scream_if_not_simple()
     if g._directed:
         from sage.graphs.digraph import DiGraph
         G = DiGraph()
         G.add_vertices(g.edge_iterator(labels=labels))
         for v in g:
             # Connect appropriate incident edges of the vertex v
             G.add_edges((e, f) for e in g.incoming_edge_iterator(v, labels=labels)
-                        for f in g.outgoing_edge_iterator(v, labels=labels))
-        return G
+                            for f in g.outgoing_edge_iterator(v, labels=labels))
+        if return_labels and multiple:
+            return [G, origlabels_dic]
+        else:
+            return G
 
     from sage.graphs.graph import Graph
     G = Graph()
@@ -393,7 +454,7 @@ def line_graph(g, labels=True):
         elist = []
 
         # Add the edge to the list, according to hashes, as previously
-        for e in g.edge_iterator(v, labels=labels):
+        for e in g.edge_iterator(v, labels=labels):  # iterates over the edges incident to v
             if hash(e[0]) < hash(e[1]):
                 elist.append(e)
             elif hash(e[0]) > hash(e[1]):
@@ -402,12 +463,17 @@ def line_graph(g, labels=True):
                 elist.append(conflicts[e])
 
         # All pairs of elements in elist are edges of the line graph
+        # if g has multiple edges, some pairs appear more than once but as G is defined as simple,
+        # the corresponding edges are not added as multiedges (as it should be).
         while elist:
             x = elist.pop()
             for y in elist:
                 G.add_edge(x, y)
 
-    return G
+    if return_labels and multiple:
+        return [G, origlabels_dic]
+    else:
+        return G
 
 
 def root_graph(g, verbose=False):