sagemathgh-38638: interface to new nauty generator for Hasse diagrams

    
add a basic interface to the new capability of nauty, namely a generator
for Hasse diagrams of posets

### 📝 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: sagemath#38638
Reported by: Frédéric Chapoton
Reviewer(s): David Coudert

src/sage/graphs/digraph_generators.py

@@ -28,6 +28,7 @@
     :meth:`~DiGraphGenerators.ImaseItoh`           | Return the digraph of Imase and Itoh of order `n` and degree `d`.
     :meth:`~DiGraphGenerators.Kautz`               | Return the Kautz digraph of degree `d` and diameter `D`.
     :meth:`~DiGraphGenerators.nauty_directg`       | Return an iterator yielding digraphs using nauty's ``directg`` program.
+    :meth:`~DiGraphGenerators.nauty_posetg`        | Return an iterator yielding Hasse diagrams of posets using nauty's ``genposetg`` program.
     :meth:`~DiGraphGenerators.Paley`               | Return a Paley digraph on `q` vertices.
     :meth:`~DiGraphGenerators.Path`                | Return a directed path on `n` vertices.
     :meth:`~DiGraphGenerators.RandomDirectedAcyclicGraph` | Return a random (weighted) directed acyclic graph of order `n`.
@@ -758,6 +759,63 @@ def nauty_directg(self, graphs, options='', debug=False):
             if line and line[0] == '&':
                 yield DiGraph(line[1:], format='dig6')
 
+    def nauty_posetg(self, options='', debug=False):
+        r"""
+        Return a generator which creates all posets using ``nauty``.
+
+        Here a poset is seen through its Hasse diagram, which is
+        an acyclic and transitively reduced digraph.
+
+        INPUT:
+
+        - ``options`` -- string (default: ``""``); a string passed to
+          ``genposetg`` as if it was run at a system command line.
+          At a minimum, you *must* pass the number of vertices you desire
+          and a choice between ``o`` and ``t`` for the output order.
+
+        - ``debug`` -- boolean (default: ``False``); if ``True`` the first line
+          of ``genposetg``'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 ``genposetg --help``::
+
+            n: the number of vertices, between 0 and 16
+            o: digraph6 output in arbitrary order
+            t: digraph6 output in topological order
+
+        EXAMPLES::
+
+            sage: gen = digraphs.nauty_posetg("5 o")
+            sage: len(list(gen))
+            63
+
+        This coincides with :oeis:`A000112`.
+        """
+        import shlex
+        from sage.features.nauty import NautyExecutable
+        geng_path = NautyExecutable("genposetg").absolute_filename()
+        sp = subprocess.Popen(shlex.quote(geng_path) + f" {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 option')
+        gen = sp.stdout
+        while True:
+            try:
+                s = next(gen)
+            except StopIteration:
+                # Exhausted list of graphs from nauty genposetg
+                return
+            G = DiGraph(s[1:-1], format='dig6')
+            yield G
+
     def Complete(self, n, loops=False):
         r"""
         Return the complete digraph on `n` vertices.
@@ -1486,7 +1544,9 @@ def RandomDirectedGNM(self, n, m, loops=False):
             sage: D.num_verts()
             10
             sage: D.loops()
-            [(0, 0, None), (1, 1, None), (2, 2, None), (3, 3, None), (4, 4, None), (5, 5, None), (6, 6, None), (7, 7, None), (8, 8, None), (9, 9, None)]
+            [(0, 0, None), (1, 1, None), (2, 2, None), (3, 3, None),
+             (4, 4, None), (5, 5, None), (6, 6, None), (7, 7, None),
+             (8, 8, None), (9, 9, None)]
 
         TESTS::