passagemath-graphs 10.5.10__cp39-cp39-macosx_14_0_arm64.whl → 10.5.43__cp39-cp39-macosx_14_0_arm64.whl

sage/graphs/digraph_generators.py

@@ -204,7 +204,7 @@ class DiGraphGenerators:
         218
     """
 
-    def ButterflyGraph(self, n, vertices='strings'):
+    def ButterflyGraph(self, n, vertices='strings', immutable=False):
         r"""
         Return a `n`-dimensional butterfly graph.
 
@@ -224,6 +224,9 @@ class DiGraphGenerators:
           vertices are zero-one strings (default) or tuples over GF(2)
           (``vertices='vectors'``)
 
+        - ``immutable`` -- boolean (default: ``False``); whether to return
+          an immutable or mutable digraph.
+
         EXAMPLES::
 
             sage: digraphs.ButterflyGraph(2).edges(sort=True, labels=False)
@@ -324,9 +327,10 @@ class DiGraphGenerators:
             for x in range(n + 1):
                 pos[v, x] = (dec * x, i)
         return DiGraph([pos.keys(), E], format='vertices_and_edges', pos=pos,
-                       name="{}-dimensional Butterfly".format(n))
+                       name="{}-dimensional Butterfly".format(n),
+                       immutable=immutable)
 
-    def Path(self, n):
+    def Path(self, n, immutable=False):
         r"""
         Return a directed path on `n` vertices.
 
@@ -334,6 +338,9 @@ class DiGraphGenerators:
 
         - ``n`` -- integer; number of vertices in the path
 
+        - ``immutable`` -- boolean (default: ``False``); whether to return
+          an immutable or mutable digraph.
+
         EXAMPLES::
 
             sage: g = digraphs.Path(5)
@@ -344,15 +351,13 @@ class DiGraphGenerators:
             sage: g.automorphism_group().cardinality()                                  # needs sage.groups
             1
         """
-        g = DiGraph(n, name='Path')
-
-        if n:
-            g.add_path(list(range(n)))
-
+        g = DiGraph([range(n), zip(range(n - 1), range(1, n))],
+                    format='vertices_and_edges', name='Path',
+                    immutable=immutable)
         g.set_pos({i: (i, 0) for i in range(n)})
         return g
 
-    def StronglyRegular(self, n):
+    def StronglyRegular(self, n, immutable=False):
         r"""
         Return a Strongly Regular digraph with `n` vertices.
 
@@ -363,6 +368,9 @@ class DiGraphGenerators:
 
         - ``n`` -- integer; the number of vertices of the digraph
 
+        - ``immutable`` -- boolean (default: ``False``); whether to return
+          an immutable or mutable digraph.
+
         .. SEEALSO::
 
             - :func:`sage.combinat.matrices.hadamard_matrix.skew_hadamard_matrix`
@@ -398,15 +406,23 @@ class DiGraphGenerators:
         H = skew_hadamard_matrix(n + 1, skew_normalize=True)
         M = H[1:, 1:]
         M = (M + ones_matrix(n)) / 2 - identity_matrix(n)
-        return DiGraph(M, format='adjacency_matrix', name='Strongly regular digraph')
+        return DiGraph(M, format='adjacency_matrix', immutable=immutable,
+                       name='Strongly regular digraph')
 
-    def Paley(self, q):
+    def Paley(self, q, immutable=False):
         r"""
         Return a Paley digraph on `q` vertices.
 
         Parameter `q` must be the power of a prime number and congruent to 3 mod
         4.
 
+        INPUT:
+
+        - ``q`` -- integer; the number of vertices of the digraph
+
+        - ``immutable`` -- boolean (default: ``False``); whether to return
+          an immutable or mutable digraph.
+
         .. SEEALSO::
 
             - :wikipedia:`Paley_graph`
@@ -449,13 +465,12 @@ class DiGraphGenerators:
             raise ValueError("parameter q must be a prime power")
         if not mod(q, 4) == 3:
             raise ValueError("parameter q must be congruent to 3 mod 4")
-        g = DiGraph([FiniteField(q, 'a'),
-                     lambda i, j: (i != j) and (j - i).is_square()],
-                    loops=False,
-                    name="Paley digraph with parameter {}".format(q))
-        return g
+        return DiGraph([FiniteField(q, 'a'),
+                        lambda i, j: (i != j) and (j - i).is_square()],
+                       format='rule', loops=False, immutable=immutable,
+                       name="Paley digraph with parameter {}".format(q))
 
-    def TransitiveTournament(self, n):
+    def TransitiveTournament(self, n, immutable=False):
         r"""
         Return a transitive tournament on `n` vertices.
 
@@ -467,6 +482,9 @@ class DiGraphGenerators:
 
         - ``n`` -- integer; number of vertices in the tournament
 
+        - ``immutable`` -- boolean (default: ``False``); whether to return
+          an immutable or mutable digraph.
+
         EXAMPLES::
 
             sage: g = digraphs.TransitiveTournament(5)
@@ -491,17 +509,17 @@ class DiGraphGenerators:
             ...
             ValueError: the number of vertices cannot be strictly negative
         """
-        g = DiGraph(n, name="Transitive Tournament")
-
-        for i in range(n - 1):
-            for j in range(i + 1, n):
-                g.add_edge(i, j)
+        if n < 0:
+            raise ValueError('the number of vertices cannot be strictly negative')
 
+        from itertools import combinations
+        g = DiGraph([range(n), combinations(range(n), 2)],
+                    format='vertices_and_edges', immutable=immutable,
+                    name="Transitive Tournament")
         g._circle_embedding(list(range(n)))
-
         return g
 
-    def RandomTournament(self, n):
+    def RandomTournament(self, n, immutable=False):
         r"""
         Return a random tournament on `n` vertices.
 
@@ -513,6 +531,9 @@ class DiGraphGenerators:
 
         - ``n`` -- integer; number of vertices
 
+        - ``immutable`` -- boolean (default: ``False``); whether to return
+          an immutable or mutable digraph.
+
         EXAMPLES::
 
             sage: T = digraphs.RandomTournament(10); T
@@ -534,15 +555,17 @@ class DiGraphGenerators:
             - :meth:`~sage.graphs.digraph_generators.DiGraphGenerators.Complete`
             - :meth:`~sage.graphs.digraph_generators.DiGraphGenerators.RandomSemiComplete`
         """
-        from sage.misc.prandom import random
-        g = DiGraph(n, name="Random Tournament")
+        if n < 0:
+            raise ValueError('the number of vertices cannot be strictly negative')
 
-        for i in range(n - 1):
-            for j in range(i + 1, n):
-                if random() <= .5:
-                    g.add_edge(i, j)
-                else:
-                    g.add_edge(j, i)
+        from itertools import combinations
+        from sage.misc.prandom import getrandbits
+
+        bits = getrandbits(n * (n - 1) // 2)
+        edges = ((i, j) if (bits >> k) & 1 else (j, i)
+                 for k, (i, j) in enumerate(combinations(range(n), 2)))
+        g = DiGraph([range(n), edges], format='vertices_and_edges',
+                    immutable=immutable, name="Random Tournament")
 
         g._circle_embedding(list(range(n)))
 
@@ -550,7 +573,8 @@ class DiGraphGenerators:
 
     def tournaments_nauty(self, n,
                           min_out_degree=None, max_out_degree=None,
-                          strongly_connected=False, debug=False, options=""):
+                          strongly_connected=False, debug=False, options="",
+                          immutable=False):
         r"""
         Iterator over all tournaments on `n` vertices using Nauty.
 
@@ -572,6 +596,9 @@ class DiGraphGenerators:
           to Nauty's gentourng. See its documentation for more information :
           `<https://pallini.di.uniroma1.it>`_.
 
+        - ``immutable`` -- boolean (default: ``False``); whether to return
+          immutable or mutable digraphs.
+
         EXAMPLES::
 
             sage: # needs nauty
@@ -614,22 +641,11 @@ class DiGraphGenerators:
         if debug:
             yield sp.stderr.readline()
 
-        gen = sp.stdout
-        while True:
-            try:
-                s = bytes_to_str(next(gen))
-            except StopIteration:
-                # Exhausted list of graphs from nauty geng
-                return
-
-            G = DiGraph(n)
+        def edges(s):
             i = 0
             j = 1
             for b in s[:-1]:
-                if b == '0':
-                    G.add_edge(i, j)
-                else:
-                    G.add_edge(j, i)
+                yield (i, j) if b == '0' else (j, i)
 
                 if j == n - 1:
                     i += 1
@@ -637,9 +653,18 @@ class DiGraphGenerators:
                 else:
                     j += 1
 
-            yield G
+        gen = sp.stdout
+        while True:
+            try:
+                s = bytes_to_str(next(gen))
+            except StopIteration:
+                # Exhausted list of graphs from nauty geng
+                return
+
+            yield DiGraph([range(n), edges(s)], format='vertices_and_edges',
+                          immutable=immutable)
 
-    def nauty_directg(self, graphs, options='', debug=False):
+    def nauty_directg(self, graphs, options='', debug=False, immutable=False):
         r"""
         Return an iterator yielding digraphs using nauty's ``directg`` program.
 
@@ -671,6 +696,9 @@ class DiGraphGenerators:
         - ``debug`` -- boolean (default: ``False``); if ``True`` ``directg``
           standard error and standard output are displayed
 
+        - ``immutable`` -- boolean (default: ``False``); whether to return
+          immutable or mutable digraphs.
+
         EXAMPLES::
 
             sage: # needs nauty
@@ -764,9 +792,9 @@ class DiGraphGenerators:
             # digraph6 specifications:
             # http://users.cecs.anu.edu.au/~bdm/data/formats.txt
             if line and line[0] == '&':
-                yield DiGraph(line[1:], format='dig6')
+                yield DiGraph(line[1:], format='dig6', immutable=immutable)
 
-    def nauty_posetg(self, options='', debug=False):
+    def nauty_posetg(self, options='', debug=False, immutable=False):
         r"""
         Return a generator which creates all posets using ``nauty``.
 
@@ -787,6 +815,9 @@ class DiGraphGenerators:
           the program with some information on the arguments, while a line
           beginning with ">E" indicates an error with the input.
 
+        - ``immutable`` -- boolean (default: ``False``); whether to return
+          immutable or mutable posets.
+
         The possible options, obtained as output of ``genposetg --help``::
 
             n: the number of vertices, between 0 and 16
@@ -820,10 +851,9 @@ class DiGraphGenerators:
             except StopIteration:
                 # Exhausted list of graphs from nauty genposetg
                 return
-            G = DiGraph(s[1:-1], format='dig6')
-            yield G
+            yield DiGraph(s[1:-1], format='dig6', immutable=immutable)
 
-    def Complete(self, n, loops=False):
+    def Complete(self, n, loops=False, immutable=False):
         r"""
         Return the complete digraph on `n` vertices.
 
@@ -834,6 +864,9 @@ class DiGraphGenerators:
         - ``loops`` -- boolean (default: ``False``); whether to add loops or
           not, i.e., edges from `u` to itself
 
+        - ``immutable`` -- boolean (default: ``False``); whether to return
+          an immutable or mutable digraph.
+
         .. SEEALSO::
 
             - :meth:`~sage.graphs.digraph_generators.DiGraphGenerators.RandomSemiComplete`
@@ -856,24 +889,32 @@ class DiGraphGenerators:
             ...
             ValueError: the number of vertices cannot be strictly negative
         """
-        G = DiGraph(n, name="Complete digraph" + (" with loops" if loops else ''), loops=loops)
-
-        if loops:
-            G.add_edges((u, u) for u in range(n))
+        if n < 0:
+            raise ValueError('the number of vertices cannot be strictly negative')
 
-        G.add_edges((u, v) for u in range(n) for v in range(n) if u != v)
+        edges = ((u, v) for u in range(n) for v in range(n) if u != v or loops)
+        G = DiGraph([range(n), edges], format='vertices_and_edges',
+                    loops=loops, immutable=immutable,
+                    name="Complete digraph" + (" with loops" if loops else ''))
 
         G._circle_embedding(list(range(n)))
 
         return G
 
-    def Circuit(self, n):
+    def Circuit(self, n, immutable=False):
         r"""
         Return the circuit on `n` vertices.
 
         The circuit is an oriented
         :meth:`~sage.graphs.graph_generators.GraphGenerators.CycleGraph`.
 
+        INPUT:
+
+        - ``n`` -- integer; number of vertices
+
+        - ``immutable`` -- boolean (default: ``False``); whether to return
+          an immutable or mutable digraph.
+
         EXAMPLES:
 
         A circuit is the smallest strongly connected digraph::
@@ -882,19 +923,20 @@ class DiGraphGenerators:
             sage: len(circuit.strongly_connected_components()) == 1
             True
         """
-        g = DiGraph(n, name='Circuit')
-
+        if n < 0:
+            raise ValueError('the number of vertices cannot be strictly negative')
         if n == 1:
-            g.allow_loops(True)
-            g.add_edge(0, 0)
-            return g
-        elif n:
-            g.add_edges(zip(range(n - 1), range(1, n)))
-            g.add_edge(n - 1, 0)
-            g._circle_embedding(list(range(n)))
+            return DiGraph([(0, 0)], format='list_of_edges', loops=True,
+                           immutable=immutable, name='Circuit')
+
+        from itertools import chain
+        edges = zip(range(n), chain(range(1, n), [0]))
+        g = DiGraph([range(n), edges], format='vertices_and_edges',
+                    immutable=immutable, name='Circuit')
+        g._circle_embedding(list(range(n)))
         return g
 
-    def Circulant(self, n, integers):
+    def Circulant(self, n, integers, immutable=False):
         r"""
         Return a circulant digraph on `n` vertices from a set of integers.
 
@@ -909,6 +951,9 @@ class DiGraphGenerators:
           that there is an edge from `i` to `j` if and only if `(j-i) \pmod{n}`
           is an integer
 
+        - ``immutable`` -- boolean (default: ``False``); whether to return
+          an immutable or mutable digraph.
+
         EXAMPLES:
 
         Construct and show the circulant graph [3, 5, 7], a digraph on 13
@@ -947,12 +992,11 @@ class DiGraphGenerators:
             if not i % n:
                 loops = True
 
-        G = DiGraph(n, name="Circulant graph (" + str(integers) + ")", loops=loops)
-
+        edges = ((v, (v + j) % n) for j in integers for v in range(n))
+        G = DiGraph([range(n), edges], format='vertices_and_edges',
+                    loops=loops, immutable=immutable,
+                    name="Circulant graph (" + str(integers) + ")")
         G._circle_embedding(list(range(n)))
-        for v in range(n):
-            G.add_edges((v, (v + j) % n) for j in integers)
-
         return G
 
     def DeBruijn(self, k, n, vertices='strings'):