trac #33670: add interface to nauty's gentreeg

Author: dcoudert

build/pkgs/nauty/spkg-configure.m4

@@ -2,7 +2,7 @@
 # only detect nauty >= 2.6 because we use the digraph6 format from
 # that version -- and converseg was added in nauty-2.6.
 AC_DEFUN([SAGE_TEST_NAUTY_PROGS], [
-    m4_foreach([nautyprog], [directg, gentourng, geng, genbg, converseg], [
+    m4_foreach([nautyprog], [directg, gentourng, geng, genbg, gentreeg, converseg], [
       AC_PATH_PROG([$2]nautyprog, [[$1]nautyprog])
       AS_IF([test x$[$2]nautyprog = x], [sage_spkg_install_nauty=yes])
     ])

src/sage/features/nauty.py

@@ -52,7 +52,7 @@ def __init__(self):
         """
         JoinFeature.__init__(self, "nauty",
                              [NautyExecutable(name)
-                              for name in ('directg', 'gentourng', 'geng', 'genbg', 'converseg')])
+                              for name in ('directg', 'gentourng', 'geng', 'genbg', 'gentreeg', 'converseg')])
 
 
 def all_features():

src/sage/graphs/generators/families.py

@@ -22,6 +22,7 @@
 from math import sin, cos, pi
 from sage.graphs.graph import Graph
 from itertools import combinations
+import subprocess
 
 
 def JohnsonGraph(n, k):
@@ -3414,6 +3415,129 @@ def trees(vertices):
     from sage.graphs.trees import TreeIterator
     return iter(TreeIterator(vertices))
 
+def nauty_gentreeg(options="", debug=False):
+    r"""
+    Return a generator which creates non-isomorphic trees from nauty's gentreeg
+    program.
+
+    INPUT:
+
+    - ``options`` -- string (default: ``""``); a string passed to ``gentreeg``
+      as if it was run at a system command line. At a minimum, you *must* pass
+      the number of vertices you desire. Sage expects the graphs to be in
+      nauty's "sparse6" format, do not set an option to change this default or
+      results will be unpredictable.
+
+    - ``debug`` -- boolean (default: ``False``); if ``True`` the first line of
+      ``gentreeg``'s output to standard error is captured and the first call to
+      the generator's ``next()`` function will return this line as a string. A
+      line leading with ">A" indicates a successful initiation of the program
+      with some information on the arguments, while a line beginning with ">E"
+      indicates an error with the input.
+
+    The possible options, obtained as output of ``gentreeg -help``::
+
+           n            : the number of vertices. Must be in range 1..128
+        res/mod         : only generate subset res out of subsets 0..mod-1
+          -D<int>       : an upper bound for the maximum degree
+          -Z<int>:<int> : bounds on the diameter
+          -q            : suppress auxiliary output
+
+    Options which cause ``gentreeg`` to use an output format different than the
+    sparse6 format are not listed above (-p, -l, -u) as they will confuse the
+    creation of a Sage graph. The res/mod option can be useful when using the
+    output in a routine run several times in parallel.
+
+    OUTPUT:
+
+    A generator which will produce the graphs as Sage graphs. These will be
+    simple graphs: no loops, no multiple edges, no directed edges.
+
+    .. SEEALSO::
+
+        :meth:`trees` -- another generator of trees
+
+    EXAMPLES:
+
+    The generator can be used to construct trees for testing, one at a time
+    (usually inside a loop). Or it can be used to create an entire list all at
+    once if there is sufficient memory to contain it::
+
+        sage: gen = graphs.nauty_gentreeg("4")
+        sage: next(gen)
+        Graph on 4 vertices
+        sage: next(gen)
+        Graph on 4 vertices
+        sage: next(gen)
+        Traceback (most recent call last):
+        ...
+        StopIteration
+
+    The number of trees on the first few vertex counts. This aggrees with
+    :oeis:`A000055`::
+
+        sage: [len(list(graphs.nauty_gentreeg(str(i)))) for i in range(1, 15)]
+        [1, 1, 1, 2, 3, 6, 11, 23, 47, 106, 235, 551, 1301, 3159]
+
+    The ``debug`` switch can be used to examine ``gentreeg``'s reaction to the
+    input in the ``options`` string.  We illustrate success. (A failure will be
+    a string beginning with ">E".)  Passing the "-q" switch to ``gentreeg`` will
+    suppress the indicator of a successful initiation, and so the first returned
+    value might be an empty string if ``debug`` is ``True``::
+
+        sage: gen = graphs.nauty_gentreeg("4", debug=True)
+        sage: print(next(gen))
+        >A ...gentreeg Z=2:3 D=3 n=4
+        sage: gen = graphs.nauty_gentreeg("4 -q", debug=True)
+        sage: next(gen)
+        ''
+
+    TESTS:
+
+    The number `n` of vertices must be in range 1..128::
+
+        sage: list(graphs.nauty_gentreeg("0", debug=False))
+        Traceback (most recent call last):
+        ...
+        ValueError: wrong format of parameter options
+        sage: list(graphs.nauty_gentreeg("0", debug=True))
+        ['>E gentreeg: n must be in the range 1..128\n']
+        sage: list(graphs.nauty_gentreeg("200", debug=True))
+        ['>E gentreeg: n must be in the range 1..128\n']
+
+    Wrong input::
+
+        sage: list(graphs.nauty_gentreeg("3 -x", debug=False))
+        Traceback (most recent call last):
+        ...
+        ValueError: wrong format of parameter options
+        sage: list(graphs.nauty_gentreeg("3 -x", debug=True))
+        ['>E Usage: ...gentreeg [-D#] [-Z#:#] [-ulps] [-q] n [res/mod] ...
+        sage: list(graphs.nauty_gentreeg("3", debug=True))
+        ['>A ...gentreeg Z=2:2 D=2 n=3\n', Graph on 3 vertices]
+    """
+    import shlex
+    from sage.features.nauty import NautyExecutable
+    gen_path = NautyExecutable("gentreeg").absolute_filename()
+    sp = subprocess.Popen(shlex.quote(gen_path) + " {0}".format(options), shell=True,
+                          stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+                          stderr=subprocess.PIPE, close_fds=True,
+                          encoding='latin-1')
+    msg = sp.stderr.readline()
+    if debug:
+        yield msg
+    elif msg.startswith('>E'):
+        raise ValueError('wrong format of parameter options')
+    gen = sp.stdout
+    while True:
+        try:
+            s = next(gen)
+        except StopIteration:
+            # Exhausted list of graphs from nauty geng
+            return
+        G = Graph(s[:-1], format='sparse6', loops=False, multiedges=False)
+        yield G
+
 def RingedTree(k, vertex_labels = True):
     r"""
     Return the ringed tree on k-levels.

src/sage/graphs/graph_generators.py

@@ -276,6 +276,7 @@ def __append_to_doc(methods):
      "SwitchedSquaredSkewHadamardMatrixGraph",
      "strongly_regular_graph",
      "trees",
+     "nauty_gentreeg",
      "triangulations",
      "TuranGraph",
      "UstimenkoGraph",
@@ -2342,6 +2343,7 @@ def quadrangulations(self, order, minimum_degree=None, minimum_connectivity=None
     TabacjnGraph           = staticmethod(families.TabacjnGraph)
     TadpoleGraph           = staticmethod(families.TadpoleGraph)
     trees                  = staticmethod(families.trees)
+    nauty_gentreeg         = staticmethod(families.nauty_gentreeg)
     TuranGraph             = staticmethod(families.TuranGraph)
     UstimenkoGraph         = staticmethod(distance_regular.UstimenkoGraph)
     WheelGraph             = staticmethod(families.WheelGraph)