Trac #29840: Document choice of base ring of incidence matrix and adj…

…acency matrices

Currently incidence matrix and adjacency matrices of
polyhedra/cones/lattice polytopes are set up with base ring `ZZ`.

This ticket documents this.

URL: https://trac.sagemath.org/29840
Reported by: gh-kliem
Ticket author(s): Jonathan Kliem
Reviewer(s): Matthias Koeppe

src/sage/geometry/cone.py

@@ -2771,6 +2771,11 @@ def incidence_matrix(self):
 
             sage: halfspace.incidence_matrix().is_immutable()
             True
+
+        Check that the base ring is ``ZZ``, see :trac:`29840`::
+
+            sage: halfspace.incidence_matrix().base_ring()
+            Integer Ring
         """
         normals = self.facet_normals()
         incidence_matrix = matrix(ZZ, self.nrays(),

src/sage/geometry/lattice_polytope.py

@@ -2389,6 +2389,11 @@ def incidence_matrix(self):
 
             sage: o.incidence_matrix().is_immutable()
             True
+
+        Check that the base ring is ``ZZ``, see :trac:`29840`::
+
+            sage: o.incidence_matrix().base_ring()
+            Integer Ring
         """
         incidence_matrix = matrix(ZZ, self.nvertices(),
                                   self.nfacets(), 0)

src/sage/geometry/polyhedron/base.py

@@ -2484,6 +2484,18 @@ def vertex_adjacency_matrix(self):
             (0, 0, 0, 0, 1) A ray in the direction (1, 1)
             (0, 0, 1, 1, 0) A vertex at (3, 0)
 
+        The vertex adjacency matrix has base ring integers. This way one can express various
+        counting questions::
+
+            sage: P = polytopes.cube()
+            sage: Q = P.stack(P.faces(2)[0])
+            sage: M = Q.vertex_adjacency_matrix()
+            sage: sum(M)
+            (4, 4, 3, 3, 4, 4, 4, 3, 3)
+            sage: G = Q.vertex_graph()
+            sage: G.degree()
+            [4, 4, 3, 3, 4, 4, 4, 3, 3]
+
         TESTS:
 
         Check that :trac:`28828` is fixed::
@@ -2565,6 +2577,15 @@ def facet_adjacency_matrix(self):
             [1 1 1 0 1]
             [1 1 1 1 0]
 
+        The facet adjacency matrix has base ring integers. This way one can express various
+        counting questions::
+
+            sage: P = polytopes.cube()
+            sage: Q = P.stack(P.faces(2)[0])
+            sage: M = Q.facet_adjacency_matrix()
+            sage: sum(M)
+            (4, 4, 4, 4, 3, 3, 3, 3, 4)
+
         TESTS:
 
         Check that :trac:`28828` is fixed::
@@ -2671,6 +2692,14 @@ def incidence_matrix(self):
             [0 1 0]
             [0 0 1]
 
+        The incidence matrix has base ring integers. This way one can express various
+        counting questions::
+
+            sage: P = polytopes.twenty_four_cell()
+            sage: M = P.incidence_matrix()
+            sage: sum(sum(x) for x in M) == P.flag_f_vector(0,3)
+            True
+
         TESTS:
 
         Check that :trac:`28828` is fixed::

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

@@ -1033,6 +1033,12 @@ cdef class CombinatorialPolyhedron(SageObject):
             sage: C.incidence_matrix.clear_cache()
             sage: C.incidence_matrix()
             []
+
+        Check that the base ring is ``ZZ``, see :trac:`29840`::
+
+            sage: C = CombinatorialPolyhedron([[0,1,2], [0,1,3], [0,2,3], [1,2,3]])
+            sage: C.incidence_matrix().base_ring()
+            Integer Ring
         """
         from sage.rings.all import ZZ
         from sage.matrix.constructor import matrix