Trac #29186: Add simplicity and simpliciality to polyhedra

In #27086 we have implemented simplicity and simpliciality for
combinatorial polyhedra. We expose this methods in `Polyhedron_base`.

The methods return the largest `k` such that the polytope is
`k`-simple/simplicial. In case of unbounded polyhedra a
`NotImplementedError` is raised.

A polytope is `k`-simplicial if every `k`-face is a simplex. It is
`k`-simple if its dual/polar is `k`-simplicial.

URL: https://trac.sagemath.org/29186
Reported by: gh-kliem
Ticket author(s): Jonathan Kliem
Reviewer(s): Jean-Philippe Labbé

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

@@ -72,6 +72,8 @@ List of Polyhedron methods
     :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.f_vector` |  the `f`-vector (number of faces of each dimension)
     :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.flag_f_vector` |  the flag-`f`-vector (number of chains of faces)
     :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.neighborliness` | highest cardinality for which all `k`-subsets of the vertices are faces of the polyhedron
+    :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.simpliciality` | highest cardinality for which all `k`-faces are simplices
+    :meth:`~sage.geometry.polyhedron.base.Polyhedron_base.simplicity` | highest cardinality for which the polar is `k`-simplicial
 
 **Implementation properties**
 

src/sage/geometry/polyhedron/base.py

@@ -3124,6 +3124,40 @@ def combinatorial_polyhedron(self):
         from sage.geometry.polyhedron.combinatorial_polyhedron.base import CombinatorialPolyhedron
         return CombinatorialPolyhedron(self)
 
+    def simplicity(self):
+        r"""
+        Return the largest integer `k` such that the polytope is `k`-simple.
+
+        A polytope `P` is `k`-simple, if every `(d-1-k)`-face
+        is contained in exactly `k+1` facets of `P` for `1 \leq k \leq d-1`.
+        Equivalently it is `k`-simple if the polar/dual polytope is `k`-simplicial.
+        If `self` is a simplex, it returns its dimension.
+
+        EXAMPLES::
+
+            sage: polytopes.hypersimplex(4,2).simplicity()
+            1
+            sage: polytopes.hypersimplex(5,2).simplicity()
+            2
+            sage: polytopes.hypersimplex(6,2).simplicity()
+            3
+            sage: polytopes.simplex(3).simplicity()
+            3
+            sage: polytopes.simplex(1).simplicity()
+            1
+
+        The method is not implemented for unbounded polyhedra::
+
+            sage: p = Polyhedron(vertices=[(0,0)],rays=[(1,0),(0,1)])
+            sage: p.simplicity()
+            Traceback (most recent call last):
+            ...
+            NotImplementedError: this function is implemented for polytopes only
+        """
+        if not(self.is_compact()):
+            raise NotImplementedError("this function is implemented for polytopes only")
+        return self.combinatorial_polyhedron().simplicity()
+
     def is_simple(self):
         """
         Test for simplicity of a polytope.
@@ -3143,6 +3177,38 @@ def is_simple(self):
         if not self.is_compact(): return False
         return self.combinatorial_polyhedron().is_simple()
 
+    def simpliciality(self):
+        r"""
+        Return the largest interger `k` such that the polytope is `k`-simplicial.
+
+        A polytope is `k`-simplicial, if every `k`-face is a simplex.
+        If `self` is a simplex, returns its dimension.
+
+        EXAMPLES::
+
+            sage: polytopes.cyclic_polytope(10,4).simpliciality()
+            3
+            sage: polytopes.hypersimplex(5,2).simpliciality()
+            2
+            sage: polytopes.cross_polytope(4).simpliciality()
+            3
+            sage: polytopes.simplex(3).simpliciality()
+            3
+            sage: polytopes.simplex(1).simpliciality()
+            1
+
+        The method is not implemented for unbounded polyhedra::
+
+            sage: p = Polyhedron(vertices=[(0,0)],rays=[(1,0),(0,1)])
+            sage: p.simpliciality()
+            Traceback (most recent call last):
+            ...
+            NotImplementedError: this function is implemented for polytopes only
+        """
+        if not(self.is_compact()):
+            raise NotImplementedError("this function is implemented for polytopes only")
+        return self.combinatorial_polyhedron().simpliciality()
+
     def is_simplicial(self):
         """
         Tests if the polytope is simplicial

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

@@ -1739,7 +1739,7 @@ cdef class CombinatorialPolyhedron(SageObject):
         Return the dimension in case of a simplex.
 
         A polytope `P` is `k`-simple, if every `(d-1-k)`-face
-        is contained in exactly `k+1` facets of `P` for `1 <= k <= d-1`.
+        is contained in exactly `k+1` facets of `P` for `1 \leq k \leq d-1`.
 
         Equivalently it is `k`-simple if the polar/dual polytope is `k`-simplicial.