Trac #31571: Improve interface to plantri

As suggested in David Coudert's answer to

- [https://ask.sagemath.org/question/56405 Ask Sage question 56405: Find
25-vertex 4-regular planar graphs using plantri]

URL: https://trac.sagemath.org/31571
Reported by: slelievre
Ticket author(s): David Coudert
Reviewer(s): Frédéric Chapoton

src/sage/graphs/graph_generators.py

@@ -1392,7 +1392,11 @@ def fusenes(self, hexagon_count, benzenoids=False):
 
     def planar_graphs(self, order, minimum_degree=None,
                       minimum_connectivity=None,
-                      exact_connectivity=False, only_bipartite=False,
+                      exact_connectivity=False,
+                      minimum_edges=None,
+                      maximum_edges=None,
+                      maximum_face_size=None,
+                      only_bipartite=False,
                       dual=False):
         r"""
         An iterator over connected planar graphs using the plantri generator.
@@ -1429,6 +1433,15 @@ def planar_graphs(self, order, minimum_degree=None,
           This option cannot be used with ``minimum_connectivity=3``, or if
           the minimum connectivity is not explicitly set.
 
+        - ``minimum_edges`` -- integer (default: ``None``); lower bound on the
+          number of edges
+
+        - ``maximum_edges`` -- integer (default: ``None``); upper bound on the
+          number of edges
+
+        - ``maximum_face_size`` -- integer (default: ``None``); upper bound on
+          the size of a face and so on the maximum degree of the dual graph
+
         - ``only_bipartite`` - default: ``False`` - if ``True`` only bipartite
           graphs will be generated. This option cannot be used for graphs with
           a minimum degree larger than 3.
@@ -1492,6 +1505,24 @@ def planar_graphs(self, order, minimum_degree=None,
             sage: list(graphs.planar_graphs(1, minimum_degree=1))  # optional plantri
             []
 
+        Specifying lower and upper bounds on the number of edges::
+
+            sage: len(list(graphs.planar_graphs(4)))  # optional plantri
+            6
+            sage: len(list(graphs.planar_graphs(4, minimum_edges=4)))  # optional plantri
+            4
+            sage: len(list(graphs.planar_graphs(4, maximum_edges=4)))  # optional plantri
+            4
+            sage: len(list(graphs.planar_graphs(4, minimum_edges=4, maximum_edges=4)))  # optional plantri
+            2
+
+        Specifying the maximum size of a face::
+
+            sage: len(list(graphs.planar_graphs(4, maximum_face_size=3)))  # optional plantri
+            1
+            sage: len(list(graphs.planar_graphs(4, maximum_face_size=4)))  # optional plantri
+            3
+
         TESTS:
 
         The number of edges in a planar graph is equal to the number of edges in
@@ -1546,6 +1577,31 @@ def planar_graphs(self, order, minimum_degree=None,
         if only_bipartite and minimum_degree > 3:
             raise NotImplementedError("Generation of bipartite planar graphs with minimum degree 4 or 5 is not implemented.")
 
+        edges = ''
+        if minimum_edges is None:
+            if maximum_edges is not None:
+                if maximum_edges < order - 1:
+                    raise ValueError("the number of edges cannot be less than order - 1")
+                edges = '-e:{}'.format(maximum_edges)
+        else:
+            if minimum_edges > 3*order - 6:
+                raise ValueError("the number of edges cannot be more than 3*order - 6")
+            if maximum_edges is None:
+                edges = '-e{}:'.format(minimum_edges)
+            elif minimum_edges > maximum_edges:
+                raise ValueError("the maximum number of edges must be larger "
+                                 "or equal to the minimum number of edges")
+            elif minimum_edges == maximum_edges:
+                edges = '-e{}'.format(minimum_edges)
+            else:
+                edges = '-e{}:{}'.format(minimum_edges, maximum_edges)
+
+        faces = ''
+        if maximum_face_size is not None:
+            if maximum_face_size < 3:
+                raise ValueError("the upper bound on the size of a face must be at least 3")
+            faces = '-f{}'.format(maximum_face_size)
+
         if order == 0:
             return
 
@@ -1564,12 +1620,13 @@ def planar_graphs(self, order, minimum_degree=None,
         from sage.features.graph_generators import Plantri
         Plantri().require()
 
-        cmd = 'plantri -p{}m{}c{}{}{} {}'
+        cmd = 'plantri -p{}m{}c{}{}{} {} {} {}'
         command = cmd.format('b' if only_bipartite else '',
                              minimum_degree,
                              minimum_connectivity,
                              'x' if exact_connectivity else '',
                              'd' if dual else '',
+                             edges, faces,
                              order)
 
         sp = subprocess.Popen(command, shell=True,