deprecate keyword dual

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, algorithm=None):
+    def face_generator(self, face_dimension=None, algorithm=None, **kwds):
         r"""
         Return an iterator over the faces of given dimension.
 
@@ -381,9 +381,6 @@ def face_generator(self, face_dimension=None, dual=None, algorithm=None):
 
         - ``face_dimension`` -- integer (default ``None``),
           yield only faces of this dimension if specified
-        - ``dual`` -- boolean (default ``None``);
-          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
@@ -590,19 +587,21 @@ def face_generator(self, face_dimension=None, dual=None, algorithm=None):
             sage: f.ambient_Hrepresentation()
             (An equation (1, 1, 1) x - 6 == 0,)
 
-        Check that ``dual`` keyword still works::
+        The ``dual`` keyword is deprecated::
 
              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]
+             sage: list(P.face_generator(dual=False))[:4]
+             doctest:...: DeprecationWarning: the keyword dual is deprecated; use algorithm instead
+             See https://trac.sagemath.org/33646 for details.
+             [A 4-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 16 vertices,
+              A -1-dimensional face of a Polyhedron in ZZ^4,
+              A 3-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 8 vertices,
+              A 3-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 8 vertices]
+             sage: list(P.face_generator(True))[:4]
+             [A 1-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 2 vertices,
+              A 1-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 2 vertices,
+              A 1-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 2 vertices,
+              A 1-dimensional face of a Polyhedron in ZZ^4 defined as the convex hull of 2 vertices]
 
         Check that we catch incorrect algorithms:
 
@@ -611,13 +610,25 @@ def face_generator(self, face_dimension=None, dual=None, algorithm=None):
              ...
              ValueError: algorithm must be 'primal', 'dual' or None
         """
+        dual = None
         if algorithm == 'primal':
             dual = False
         elif algorithm == 'dual':
             dual = True
+        elif algorithm in (False, True):
+            from sage.misc.superseded import deprecation
+            deprecation(33646, "the keyword dual is deprecated; use algorithm instead")
+            dual = algorithm
         elif algorithm is not None:
             raise ValueError("algorithm must be 'primal', 'dual' or None")
 
+        if kwds:
+            from sage.misc.superseded import deprecation
+            deprecation(33646, "the keyword dual is deprecated; use algorithm instead")
+            if 'dual' in kwds and dual is None:
+                dual = kwds['dual']
+
+
         from sage.geometry.polyhedron.combinatorial_polyhedron.face_iterator import FaceIterator_geom
         return FaceIterator_geom(self, output_dimension=face_dimension, dual=dual)
 
@@ -1813,7 +1824,8 @@ def _test_combinatorial_face_as_combinatorial_polyhedron(self, tester=None, **op
         C1 = self.combinatorial_polyhedron()
         it1 = C1.face_iter()
         C2 = C1.dual()
-        it2 = C2.face_iter(dual=not it1.dual)
+        algorithm = 'primal' if it1.dual else 'dual'
+        it2 = C2.face_iter(algorithm=algorithm)
 
         for f in it:
             f1 = next(it1)

src/sage/geometry/polyhedron/combinatorial_polyhedron/base.pyx

@@ -1036,7 +1036,7 @@ cdef class CombinatorialPolyhedron(SageObject):
         # It is essential to have the facets in the exact same order as
         # on input, so that pickle/unpickle by :meth:`reduce` works.
         # Every facet knows its index by the facet representation.
-        face_iter = self.face_iter(self.dimension() - 1, dual=False)
+        face_iter = self.face_iter(self.dimension() - 1, algorithm='primal')
         facets = [None] * self.n_facets()
         for face in face_iter:
             index = face.ambient_H_indices()[0]
@@ -1148,7 +1148,7 @@ cdef class CombinatorialPolyhedron(SageObject):
                 for Vindex in range(self.n_Vrepresentation()):
                     incidence_matrix.set_unsafe_int(Vindex, Hindex, 1)
 
-        facet_iter = self.face_iter(self.dimension() - 1, dual=False)
+        facet_iter = self.face_iter(self.dimension() - 1, algorithm='primal')
         for facet in facet_iter:
             Hindex = facet.ambient_H_indices()[0]
             for Vindex in facet.ambient_V_indices():
@@ -1521,7 +1521,7 @@ cdef class CombinatorialPolyhedron(SageObject):
             sage: C.facet_graph()
             Graph on 10 vertices
         """
-        face_iter = self.face_iter(self.dimension() - 1, dual=False)
+        face_iter = self.face_iter(self.dimension() - 1, algorithm='primal')
         if names:
             V = list(facet.ambient_Hrepresentation() for facet in face_iter)
         else:
@@ -1620,7 +1620,7 @@ cdef class CombinatorialPolyhedron(SageObject):
                 return DiGraph([[v], []])
 
         # The face iterator will iterate through the facets in opposite order.
-        facet_iter = self.face_iter(self.dimension() - 1, dual=False)
+        facet_iter = self.face_iter(self.dimension() - 1, algorithm='primal')
         n_facets = self.n_facets()
         n_Vrep = self.n_Vrepresentation()
 
@@ -2445,6 +2445,7 @@ cdef class CombinatorialPolyhedron(SageObject):
         To check this property it suffices to check for all facets of the polyhedron.
         """
         if not self.is_compact():
+
             raise ValueError("polyhedron has to be compact")
 
         n_facets = self.n_facets()
@@ -2595,16 +2596,13 @@ cdef class CombinatorialPolyhedron(SageObject):
         """
         return self.face_generator().meet_of_Hrep(*indices)
 
-    def face_generator(self, dimension=None, dual=None, algorithm=None):
+    def face_generator(self, dimension=None, algorithm=None, **kwds):
         r"""
         Iterator over all proper faces of specified dimension.
 
         INPUT:
 
         - ``dimension`` -- if specified, then iterate over only this dimension
-        - ``dual`` -- boolean (default ``None``);
-          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
@@ -2682,18 +2680,39 @@ cdef class CombinatorialPolyhedron(SageObject):
             (A ray in the direction (1, 0), A vertex at (1, 0))
             (A ray in the direction (0, 1), A vertex at (0, 1))
 
+        TESTS:
+
+        The kewword ``dual`` is deprecated::
+
+            sage: C = CombinatorialPolyhedron([[0,1,2],[0,1,3],[0,2,3],[1,2,3]])
+            sage: it = C.face_generator(1, False)
+            doctest:...: DeprecationWarning: the keyword dual is deprecated; use algorithm instead
+            See https://trac.sagemath.org/33646 for details.
+            sage: it = C.face_generator(1, dual=True)
+
         .. SEEALSO::
 
             :class:`~sage.geometry.polyhedron.combinatorial_polyhedron.face_iterator.FaceIterator`,
             :class:`~sage.geometry.polyhedron.combinatorial_polyhedron.combinatorial_face.CombinatorialFace`.
         """
+        dual = None
         if algorithm == 'primal':
             dual = False
         elif algorithm == 'dual':
             dual = True
+        elif algorithm in (False, True):
+            from sage.misc.superseded import deprecation
+            deprecation(33646, "the keyword dual is deprecated; use algorithm instead")
+            dual = algorithm
         elif algorithm is not None:
             raise ValueError("algorithm must be 'primal', 'dual' or None")
 
+        if kwds:
+            from sage.misc.superseded import deprecation
+            deprecation(33646, "the keyword dual is deprecated; use algorithm instead")
+            if 'dual' in kwds and dual is None:
+                dual = kwds['dual']
+
         cdef FaceIterator face_iter
         if dual is None:
             # Determine the faster way, to iterate through all faces.

src/sage/geometry/polyhedron/combinatorial_polyhedron/face_iterator.pyx

@@ -829,7 +829,7 @@ cdef class FaceIterator_base(SageObject):
         In non-dual mode we construct the meet of facets::
 
             sage: P = polytopes.cube()
-            sage: it = P.face_generator(dual=False)
+            sage: it = P.face_generator(algorithm='primal')
             sage: it._meet_of_coatoms(1,2)
             A 1-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 2 vertices
             sage: it._meet_of_coatoms(1,2,3)
@@ -840,7 +840,7 @@ cdef class FaceIterator_base(SageObject):
         In dual mode we construct the join of vertices/rays::
 
             sage: P = polytopes.cube()
-            sage: it = P.face_generator(dual=True)
+            sage: it = P.face_generator(algorithm='dual')
             sage: it._meet_of_coatoms(1,2)
             A 1-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 2 vertices
             sage: it._meet_of_coatoms(1,2,3)
@@ -938,7 +938,7 @@ cdef class FaceIterator_base(SageObject):
         In dual mode we construct the meet of facets::
 
             sage: P = polytopes.cube()
-            sage: it = P.face_generator(dual=True)
+            sage: it = P.face_generator(algorithm='dual')
             sage: it._join_of_atoms(1,2)
             A 1-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 2 vertices
             sage: it._join_of_atoms(1,2,3)
@@ -949,7 +949,7 @@ cdef class FaceIterator_base(SageObject):
         In non-dual mode we construct the join of vertices/rays::
 
             sage: P = polytopes.cube()
-            sage: it = P.face_generator(dual=False)
+            sage: it = P.face_generator(algorithm='primal')
             sage: it._join_of_atoms(1,2)
             A 1-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 2 vertices
             sage: it._join_of_atoms(1,2,3)
@@ -1639,12 +1639,12 @@ cdef class FaceIterator_geom(FaceIterator_base):
 
     Construct faces by the dual or not::
 
-        sage: it = P.face_generator(dual=False)
+        sage: it = P.face_generator(algorithm='primal')
         sage: _ = next(it), next(it)
         sage: next(it).dim()
         2
 
-        sage: it = P.face_generator(dual=True)
+        sage: it = P.face_generator(algorithm='dual')
         sage: _ = next(it), next(it)
         sage: next(it).dim()
         0
@@ -1672,7 +1672,7 @@ cdef class FaceIterator_geom(FaceIterator_base):
          (A vertex at (0, 0, 0), A ray in the direction (0, 1, 0)),
          (A vertex at (0, 0, 0),),
          (A vertex at (0, 0, 0), A ray in the direction (0, 0, 1))]
-        sage: it = P.face_generator(dual=True)
+        sage: it = P.face_generator(algorithm='dual')
         Traceback (most recent call last):
         ...
         ValueError: cannot iterate over dual of unbounded Polyedron
@@ -1692,7 +1692,7 @@ cdef class FaceIterator_geom(FaceIterator_base):
     In non-dual mode one can ignore all faces contained in the current 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()
@@ -1717,7 +1717,7 @@ cdef class FaceIterator_geom(FaceIterator_base):
          (0, 1, 2),
          (0, 1)]
 
-        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
@@ -1729,7 +1729,7 @@ cdef class FaceIterator_geom(FaceIterator_base):
     In dual mode one can ignore all faces that contain the current 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: next(it)
         A 0-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 1 vertex
@@ -1762,7 +1762,7 @@ cdef class FaceIterator_geom(FaceIterator_base):
          (1, 2),
          (0, 1)]
 
-        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