allow algorithm for Polyhedron_base.face_generator

src/sage/geometry/polyhedron/base3.py

@@ -371,7 +371,7 @@ def _test_combinatorial_polyhedron(self, tester=None, **options):
                                                        prefix=tester._prefix+"  ")
         tester.info(tester._prefix+" ", newline = False)
 
-    def face_generator(self, face_dimension=None, dual=None):
+    def face_generator(self, face_dimension=None, dual=None, algorithm=None):
         r"""
         Return an iterator over the faces of given dimension.
 
@@ -382,9 +382,13 @@ def face_generator(self, face_dimension=None, dual=None):
         - ``face_dimension`` -- integer (default ``None``),
           yield only faces of this dimension if specified
         - ``dual`` -- boolean (default ``None``);
-          if ``True``, generate the faces using the vertices;
-          if ``False``, generate the faces using the facets;
-          if ``None``, pick automatically
+          if ``True``, pick dual algorithm
+          if ``False``, pick primal algorithm
+        - ``algorithm`` -- string (optional);
+          specify whether to start with facets or vertices:
+          * ``'primal'`` -- start with the facets
+          * ``'dual'`` -- start with the vertices
+          * ``None`` -- choose automatically
 
         OUTPUT:
 
@@ -474,7 +478,7 @@ def face_generator(self, face_dimension=None, dual=None):
         In non-dual mode we can skip subfaces of the current (proper) face::
 
             sage: P = polytopes.cube()
-            sage: it = P.face_generator(dual=False)
+            sage: it = P.face_generator(algorithm='primal')
             sage: _ = next(it), next(it)
             sage: face = next(it)
             sage: face.ambient_H_indices()
@@ -500,7 +504,7 @@ def face_generator(self, face_dimension=None, dual=None):
         In dual mode we can skip supfaces of the current (proper) face::
 
             sage: P = polytopes.cube()
-            sage: it = P.face_generator(dual=True)
+            sage: it = P.face_generator(algorithm='dual')
             sage: _ = next(it), next(it)
             sage: face = next(it)
             sage: face.ambient_V_indices()
@@ -528,7 +532,7 @@ def face_generator(self, face_dimension=None, dual=None):
 
         In non-dual mode, we cannot skip supfaces::
 
-            sage: it = P.face_generator(dual=False)
+            sage: it = P.face_generator(algorithm='primal')
             sage: _ = next(it), next(it)
             sage: next(it)
             A 2-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 4 vertices
@@ -539,7 +543,7 @@ def face_generator(self, face_dimension=None, dual=None):
 
         In dual mode, we cannot skip subfaces::
 
-            sage: it = P.face_generator(dual=True)
+            sage: it = P.face_generator(algorithm='dual')
             sage: _ = next(it), next(it)
             sage: next(it)
             A 0-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 1 vertex
@@ -550,7 +554,7 @@ def face_generator(self, face_dimension=None, dual=None):
 
         We can only skip sub-/supfaces of proper faces::
 
-            sage: it = P.face_generator(dual=False)
+            sage: it = P.face_generator(algorithm='primal')
             sage: next(it)
             A 3-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 8 vertices
             sage: it.ignore_subfaces()
@@ -585,7 +589,35 @@ def face_generator(self, face_dimension=None, dual=None):
             sage: [f] = P.face_generator(2)
             sage: f.ambient_Hrepresentation()
             (An equation (1, 1, 1) x - 6 == 0,)
+
+        Check that ``dual`` keyword still works::
+
+             sage: P = polytopes.hypercube(4)
+             sage: list(P.face_generator(2, dual=False))[:4]
+             [A 2-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 4 vertices,
+              A 2-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 4 vertices,
+              A 2-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 4 vertices,
+              A 2-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 4 vertices]
+             sage: list(P.face_generator(2, dual=True))[:4]
+             [A 2-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 4 vertices,
+              A 2-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 4 vertices,
+              A 2-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 4 vertices,
+              A 2-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 4 vertices]
+
+        Check that we catch incorrect algorithms:
+
+             sage: list(P.face_generator(2, algorithm='integrate'))[:4]
+             Traceback (most recent call last):
+             ...
+             ValueError: algorithm must be 'primal', 'dual' or None
         """
+        if algorithm == 'primal':
+            dual = False
+        elif algorithm == 'dual':
+            dual = True
+        elif algorithm is not None:
+            raise ValueError("algorithm must be 'primal', 'dual' or None")
+
         from sage.geometry.polyhedron.combinatorial_polyhedron.face_iterator import FaceIterator_geom
         return FaceIterator_geom(self, output_dimension=face_dimension, dual=dual)