Trac #25675: Crosslinks to poset catalog, add documentation of sage.g…

…eometry.polyhedron.base* and combinatorial_polyhedron

Add a mention about `GrowthDiagram.rules.Sylvester().P_graph(5)`,
`polytopes.tetrahedron().face_lattice()` etc. to poset catalog.

Repair the documentation of polyhedra damaged in #32651.

Add documentation of combinatorial polyhedra.

URL: https://trac.sagemath.org/25675
Reported by: jmantysalo
Ticket author(s): Frédéric Chapoton, Matthias Koeppe, John Palmieri
Reviewer(s): John Palmieri, Matthias Koeppe

src/doc/en/reference/discrete_geometry/index.rst

@@ -47,6 +47,20 @@ Lattice polyhedra
    sage/geometry/polyhedron/ppl_lattice_polygon
    sage/geometry/polyhedron/ppl_lattice_polytope
 
+Combinatorial Polyhedra
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. toctree::
+   :maxdepth: 1
+
+   sage/geometry/polyhedron/combinatorial_polyhedron/base
+   sage/geometry/polyhedron/combinatorial_polyhedron/combinatorial_face
+   sage/geometry/polyhedron/combinatorial_polyhedron/polyhedron_face_lattice
+   sage/geometry/polyhedron/combinatorial_polyhedron/face_iterator
+   sage/geometry/polyhedron/combinatorial_polyhedron/list_of_faces
+   sage/geometry/polyhedron/combinatorial_polyhedron/conversions
+
+
 Polyhedral complexes
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -76,6 +90,14 @@ Base classes for polyhedra
 .. toctree::
    :maxdepth: 1
 
+   sage/geometry/polyhedron/base0
+   sage/geometry/polyhedron/base1
+   sage/geometry/polyhedron/base2
+   sage/geometry/polyhedron/base3
+   sage/geometry/polyhedron/base4
+   sage/geometry/polyhedron/base5
+   sage/geometry/polyhedron/base6
+   sage/geometry/polyhedron/base7
    sage/geometry/polyhedron/base
    sage/geometry/polyhedron/base_QQ
    sage/geometry/polyhedron/base_ZZ
@@ -88,6 +110,7 @@ Backends for Polyhedra
    :maxdepth: 1
 
    sage/geometry/polyhedron/backend_cdd
+   sage/geometry/polyhedron/backend_cdd_rdf
    sage/geometry/polyhedron/backend_field
    sage/geometry/polyhedron/backend_normaliz
    sage/geometry/polyhedron/backend_polymake
@@ -113,6 +136,7 @@ Miscellaneous
 .. toctree::
    :maxdepth: 1
 
+   sage/geometry/abc
    sage/geometry/convex_set
    sage/geometry/linear_expression
    sage/geometry/newton_polygon

src/sage/combinat/posets/poset_examples.py

@@ -65,10 +65,20 @@
     :meth:`~Posets.YoungsLatticePrincipalOrderIdeal` | Return the principal order ideal of the partition `lam` in Young's Lattice.
     :meth:`~Posets.YoungFibonacci` | Return the Young-Fibonacci lattice up to rank `n`.
 
+**Other available posets:**
+
+.. csv-table::
+    :class: contentstable
+    :widths: 30, 70
+    :delim: |
+
+    :meth:`~sage.geometry.polyhedron.base4.Polyhedron_base4.face_lattice` | Return the face lattice of a polyhedron.
+    :meth:`~sage.geometry.polyhedron.combinatorial_polyhedron.base.CombinatorialPolyhedron.face_lattice` | Return the face lattice of a combinatorial polyhedron.
+
 Constructions
 -------------
 """
-#*****************************************************************************
+# ****************************************************************************
 #       Copyright (C) 2008 Peter Jipsen <jipsen@chapman.edu>,
 #                          Franco Saliola <saliola@gmail.com>
 #
@@ -81,8 +91,8 @@
 #
 #  The full text of the GPL is available at:
 #
-#                  http://www.gnu.org/licenses/
-#*****************************************************************************
+#                  https://www.gnu.org/licenses/
+# ****************************************************************************
 
 from sage.misc.classcall_metaclass import ClasscallMetaclass
 import sage.categories.posets
@@ -130,7 +140,7 @@ class Posets(metaclass=ClasscallMetaclass):
         sage: TestSuite(P).run()
     """
     @staticmethod
-    def __classcall__(cls, n = None):
+    def __classcall__(cls, n=None):
         r"""
         Return either the category of all posets, or the finite
         enumerated set of all finite posets on ``n`` elements up to an

src/sage/geometry/cone_catalog.py

@@ -177,7 +177,7 @@ def nonnegative_orthant(ambient_dim=None, lattice=None):
 
     OUTPUT:
 
-    A :class:`.ConvexRationalPolyhedralCone` living in ``lattice``
+    A :class:`~sage.geometry.cone.ConvexRationalPolyhedralCone` living in ``lattice``
     and having ``ambient_dim`` standard basis vectors as its
     generators. Each generating ray has the integer ring as its
     base ring.
@@ -287,7 +287,7 @@ def rearrangement(p, ambient_dim=None, lattice=None):
 
     OUTPUT:
 
-    A :class:`.ConvexRationalPolyhedralCone` representing the
+    A :class:`~sage.geometry.cone.ConvexRationalPolyhedralCone` representing the
     rearrangement cone of order ``p`` living in ``lattice``, with
     ambient dimension ``ambient_dim``. Each generating ray has the
     integer ring as its base ring.
@@ -506,7 +506,7 @@ def schur(ambient_dim=None, lattice=None):
 
     OUTPUT:
 
-    A :class:`.ConvexRationalPolyhedralCone` representing the Schur
+    A :class:`~sage.geometry.cone.ConvexRationalPolyhedralCone` representing the Schur
     cone living in ``lattice``, with ambient dimension ``ambient_dim``.
     Each generating ray has the integer ring as its base ring.
 
@@ -635,7 +635,7 @@ def trivial(ambient_dim=None, lattice=None):
 
     OUTPUT:
 
-    A :class:`.ConvexRationalPolyhedralCone` representing the
+    A :class:`~sage.geometry.cone.ConvexRationalPolyhedralCone` representing the
     trivial cone with no nonzero generators living in ``lattice``,
     with ambient dimension ``ambient_dim``.
 

src/sage/geometry/polyhedron/base.py

@@ -1,24 +1,5 @@
 r"""
-Base class for polyhedra
-
-This is split into several modules, organized as follows:
-
-- :mod:`~sage.geometry.polyhedron.base0` -- basic initialization etc.
-
-- :mod:`~sage.geometry.polyhedron.base1` -- methods defined by the
-                                            :class:`~sage.geometry.convex_set.ConvexSet_base` API
-
-- :mod:`~sage.geometry.polyhedron.base2` -- lattice points
-
-- :mod:`~sage.geometry.polyhedron.base3` -- combinatorial methods
-
-- :mod:`~sage.geometry.polyhedron.base4` -- methods relying on graphs
-
-- :mod:`~sage.geometry.polyhedron.base5` -- constructions of new polyhedra
-
-- :mod:`~sage.geometry.polyhedron.base6` -- plotting and affine projection
-
-- :mod:`~sage.geometry.polyhedron.base7` -- triangulation and volume
+Base class for polyhedra: Miscellaneous methods
 """
 
 # ****************************************************************************
@@ -123,8 +104,8 @@ class Polyhedron_base(Polyhedron_base7):
     - ``Hrep_minimal`` (optional) -- see below
 
     - ``pref_rep`` -- string (default: ``None``);
-       one of``Vrep`` or ``Hrep`` to pick this in case the backend
-       cannot initialize from complete double description
+      one of ``Vrep`` or ``Hrep`` to pick this in case the backend
+      cannot initialize from complete double description
 
     - ``mutable`` -- ignored
 
@@ -416,7 +397,8 @@ def radius_square(self):
 
         OUTPUT:
 
-        The square of the radius, which is in :meth:`base_ring`.
+        The square of the radius, which is in
+        :meth:`~sage.geometry.polyhedron.base0.Polyhedron_base0.base_ring`.
 
         EXAMPLES::
 
@@ -634,7 +616,7 @@ def hyperplane_arrangement(self):
         A :class:`hyperplane arrangement
         <sage.geometry.hyperplane_arrangement.arrangement.HyperplaneArrangementElement>`
         consisting of the hyperplanes defined by the
-        :meth:`Hrepresentation`.
+        :meth:`~sage.geometry.polyhedron.base0.Polyhedron_base0.Hrepresentation`.
         If the polytope is full-dimensional, this is the hyperplane
         arrangement spanned by the facets of the polyhedron.
 
@@ -799,7 +781,7 @@ def is_minkowski_summand(self, Y):
         r"""
         Test whether ``Y`` is a Minkowski summand.
 
-        See :meth:`minkowski_sum`.
+        See :meth:`~sage.geometry.polyhedron.base5.Polyhedron_base5.minkowski_sum`.
 
         OUTPUT:
 
@@ -841,6 +823,7 @@ def barycentric_subdivision(self, subdivision_frac=None):
         REFERENCE:
 
         See :wikipedia:`Barycentric_subdivision`
+
         Section 6.6, Handbook of Convex Geometry, Volume A, edited by P.M. Gruber and J.M.
         Wills. 1993, North-Holland Publishing Co..
 
@@ -954,7 +937,8 @@ def permutations_to_matrices(self, conj_class_reps, acting_group=None, additiona
 
         The dictionary has entries for the generators of the ``acting_group``
         and the representatives of conjugacy classes in ``conj_class_reps``. By
-        default, the ``acting_group`` is the ``restricted_automorphism_group``
+        default, the ``acting_group`` is the
+        :meth:`~sage.geometry.polyhedron.base4.Polyhedron_base4.restricted_automorphism_group`
         of the polytope. Each element in ``additional_elts`` also becomes a key.
 
         INPUT:
@@ -963,16 +947,16 @@ def permutations_to_matrices(self, conj_class_reps, acting_group=None, additiona
           conjugacy classes of the ``acting_group``.
 
         - ``acting_group`` -- a subgroup of polytope's
-          ``restricted_automorphism_group``.
+          :meth:`~sage.geometry.polyhedron.base4.Polyhedron_base4.restricted_automorphism_group`.
 
-        - ``additional_elts`` -- list (default=None). a subset of the
-          ``restricted_automorphism_group`` of the polytope expressed as
-          permutations.
+        - ``additional_elts`` -- list (default=None). A subset of the
+          :meth:`~sage.geometry.polyhedron.base4.Polyhedron_base4.restricted_automorphism_group`
+          of the polytope expressed as permutations.
 
         OUTPUT:
 
-        A dictionary between elements of ``the restricted_automorphism_group``
-        or ``acting_group`` expressed as permutations (keys) and matrices (values).
+        A dictionary between elements of the ``acting_group`` expressed as permutations
+        (keys) and matrices (values).
 
         EXAMPLES:
 

src/sage/geometry/polyhedron/base0.py

@@ -1,7 +1,5 @@
 r"""
-Base class for polyhedra, part 0
-
-Initialization and access to Vrepresentation and Hrepresentation.
+Base class for polyhedra: Initialization and access to Vrepresentation and Hrepresentation
 """
 
 # ****************************************************************************
@@ -909,7 +907,7 @@ def inequalities_list(self):
 
             It is recommended to use :meth:`inequalities` or
             :meth:`inequality_generator` instead to iterate over the
-            list of :class:`Inequality` objects.
+            list of :class:`~sage.geometry.polyhedron.representation.Inequality` objects.
 
         EXAMPLES::
 
@@ -991,7 +989,7 @@ def vertices_list(self):
         .. NOTE::
 
             It is recommended to use :meth:`vertex_generator` instead to
-            iterate over the list of :class:`Vertex` objects.
+            iterate over the list of :class:`~sage.geometry.polyhedron.representation.Vertex` objects.
 
         .. WARNING::
 
@@ -1202,7 +1200,7 @@ def rays_list(self):
 
             It is recommended to use :meth:`rays` or
             :meth:`ray_generator` instead to iterate over the list of
-            :class:`Ray` objects.
+            :class:`~sage.geometry.polyhedron.representation.Ray` objects.
 
         OUTPUT:
 
@@ -1257,7 +1255,7 @@ def lines_list(self):
         .. NOTE::
 
             It is recommended to use :meth:`line_generator` instead to
-            iterate over the list of :class:`Line` objects.
+            iterate over the list of :class:`~sage.geometry.polyhedron.representation.Line` objects.
 
         EXAMPLES::
 

src/sage/geometry/polyhedron/base1.py

@@ -1,5 +1,5 @@
 r"""
-Base class for polyhedra, part 1
+Base class for polyhedra: Implementation of the :class:`ConvexSet_base` API
 
 Define methods that exist for convex sets,
 but not constructions such as dilation or product.
@@ -428,7 +428,7 @@ def an_affine_basis(self):
         """
         Return points in ``self`` that are a basis for the affine span of the polytope.
 
-        This implementation of the method :meth:`ConvexSet_base.an_affine_basis`
+        This implementation of the method :meth:`~sage.geometry.convex_set.ConvexSet_base.an_affine_basis`
         for polytopes guarantees the following:
 
         - All points are vertices.

src/sage/geometry/polyhedron/base2.py

@@ -1,7 +1,5 @@
 r"""
-Base class for polyhedra, part 2
-
-Define methods related to lattice points.
+Base class for polyhedra: Methods related to lattice points
 """
 
 # ****************************************************************************
@@ -345,7 +343,7 @@ def integral_points_count(self, **kwds):
         r"""
         Return the number of integral points in the polyhedron.
 
-        This generic version of this method simply calls ``integral_points``.
+        This generic version of this method simply calls :meth:`integral_points`.
 
         EXAMPLES::
 
@@ -529,7 +527,7 @@ def get_integral_point(self, index, **kwds):
         Return the ``index``-th integral point in this polyhedron.
 
         This is equivalent to ``sorted(self.integral_points())[index]``.
-        However, so long as self.integral_points_count() does not need to
+        However, so long as :meth:`integral_points_count` does not need to
         enumerate all integral points, neither does this method. Hence it can
         be significantly faster. If the polyhedron is not compact, a
         ``ValueError`` is raised.
@@ -541,7 +539,7 @@ def get_integral_point(self, index, **kwds):
           is raised.
 
         - ``**kwds`` -- optional keyword parameters that are passed to
-          :meth:`self.integral_points_count`.
+          :meth:`integral_points_count`.
 
         ALGORITHM:
 
@@ -627,14 +625,14 @@ def random_integral_point(self, **kwds):
         INPUT:
 
         - ``**kwds`` -- optional keyword parameters that are passed to
-          :meth:`self.get_integral_point`.
+          :meth:`get_integral_point`.
 
         OUTPUT:
 
         The integral point in the polyhedron chosen uniformly at random. If the
         polyhedron is not compact, a ``ValueError`` is raised. If the
-        polyhedron does not contain any integral points, an ``EmptySetError`` is
-        raised.
+        polyhedron does not contain any integral points, an
+        :class:`~sage.categories.sets_cat.EmptySetError` is raised.
 
         .. SEEALSO::