exposed a_maximal_chain to polyhedron_base

src/doc/en/thematic_tutorials/geometry/polyhedra_quickref.rst

@@ -158,6 +158,7 @@ List of Polyhedron methods
     :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.boundary_complex` | returns the boundary complex of simplicial compact polyhedron
     :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.center` | returns the average of the vertices of the polyhedron
     :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.representative_point` | returns the sum of the center and the rays
+    :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.a_maximal_chain` | returns a maximal chain of faces
     :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.face_fan` | returns the fan spanned by the faces of the polyhedron
     :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.face_generator` | a generator over the faces
     :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.faces` | the list of faces

src/sage/geometry/polyhedron/base.py

@@ -2695,6 +2695,40 @@ def representative_point(self):
         accumulator.set_immutable()
         return accumulator
 
+    def a_maximal_chain(self):
+        r"""
+        Return a maximal chain of the face lattice in increasing order.
+
+        EXAMPLES::
+
+            sage: P = polytopes.cube()
+            sage: P.a_maximal_chain()
+            [A -1-dimensional face of a Polyhedron in ZZ^3,
+             A 0-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 1 vertex,
+             A 1-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 2 vertices,
+             A 2-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 4 vertices,
+             A 3-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 8 vertices]
+            sage: P = polytopes.cube()
+            sage: chain = P.a_maximal_chain(); chain
+            [A -1-dimensional face of a Polyhedron in ZZ^3,
+             A 0-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 1 vertex,
+             A 1-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 2 vertices,
+             A 2-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 4 vertices,
+             A 3-dimensional face of a Polyhedron in ZZ^3 defined as the convex hull of 8 vertices]
+            sage: [face.ambient_V_indices() for face in chain]
+            [(), (0,), (0, 4), (0, 1, 4, 5), (0, 1, 2, 3, 4, 5, 6, 7)]
+        """
+        comb_chain = self.combinatorial_polyhedron().a_maximal_chain()
+
+        from sage.geometry.polyhedron.face import combinatorial_face_to_polyhedral_face
+        empty_face = self.faces(-1)[0]
+        universe = self.faces(self.dim())[0]
+
+        return [empty_face] + \
+               [combinatorial_face_to_polyhedral_face(self, face)
+                for face in comb_chain] + \
+               [universe]
+
     @cached_method
     def radius_square(self):
         """