A number of small edits.

Combinatorial Polyhedron grabs dimension from Polyhedron

some doctest fixes

ListOfAllFaces -> PolyhedronFaceLattice

changed repr methods

changed error type

some changes on intro docstring

added reference

alignments for import

more reference

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

@@ -2642,6 +2642,11 @@ REFERENCES:
             algebra of type* `A`. Proc. Amer. Math. Soc. **138** (2010), no. 11,
             3877--3889.
 
+.. [KS2019] \J. Kliem and C. Stump.
+            *A face iterator for polyhedra and more general finite locally
+            branched lattices*.
+            Preprint (2019): :arxiv:`1905.01945`.
+
 .. [KSV2011] Ian Kiming, Matthias Schuett and Helena Verrill, "Lifts
              of projective congruence groups", J. London
              Math. Soc. (2011) 83 (1): 96-120,

src/module_list.py

@@ -305,8 +305,8 @@ def uname_specific(name, value, alternative):
     Extension('sage.geometry.polyhedron.combinatorial_polyhedron.face_iterator',
               sources = ['sage/geometry/polyhedron/combinatorial_polyhedron/face_iterator.pyx']),
 
-    Extension('sage.geometry.polyhedron.combinatorial_polyhedron.list_of_all_faces',
-              sources = ['sage/geometry/polyhedron/combinatorial_polyhedron/list_of_all_faces.pyx']),
+    Extension('sage.geometry.polyhedron.combinatorial_polyhedron.polyhedron_face_lattice',
+              sources = ['sage/geometry/polyhedron/combinatorial_polyhedron/polyhedron_face_lattice.pyx']),
 
     Extension('sage.geometry.polyhedron.combinatorial_polyhedron.combinatorial_face',
               sources = ['sage/geometry/polyhedron/combinatorial_polyhedron/combinatorial_face.pyx']),

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

@@ -4,7 +4,7 @@ from sage.ext.memory_allocator  cimport MemoryAllocator
 from sage.structure.sage_object cimport SageObject
 from .face_iterator             cimport FaceIterator, CombinatorialFace
 from .list_of_faces             cimport ListOfFaces
-from .list_of_all_faces         cimport ListOfAllFaces
+from .polyhedron_face_lattice   cimport PolyhedronFaceLattice
 
 @cython.final
 cdef class CombinatorialPolyhedron(SageObject):
@@ -37,7 +37,7 @@ cdef class CombinatorialPolyhedron(SageObject):
     cdef size_t _n_ridges
     cdef size_t **_face_lattice_incidences  # stores incidences in Hasse diagram labeled indices of the faces
     cdef size_t _n_face_lattice_incidences
-    cdef ListOfAllFaces _all_faces          # class to generate Hasse diagram incidences
+    cdef PolyhedronFaceLattice _all_faces          # class to generate Hasse diagram incidences
 
     # Space for edges, ridges, etc. is allocated with ``MemoryAllocators``.
     # Upon sucess they are copied to ``_mem_tuple``.

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

@@ -1,32 +1,12 @@
 r"""
-CombinatorialFace
+Combinatorial face of a polyhedron
 
 This module provides the combinatorical type of a polyhedral face.
 
-Terminology in this module:
-
-- Vrepr                 -- ``[vertices, rays, lines]`` of the polyhedron.
-- Hrepr                 -- inequalities and equalities of the polyhedron.
-- Facets                -- facets of the polyhedron.
-- Coatoms               -- the faces from which all others are constructed in
-                           the face iterator. This will be facets or Vrepr.
-                           In non-dual mode, faces are constructed as
-                           intersections of the facets. In dual mode, the are
-                           constructed theoretically as joins of vertices.
-                           The coatoms are reprsented as incidences with the
-                           atoms they contain.
-- Atoms                 -- facets or Vrepr depending on application of algorithm.
-                           Atoms are reprsented as incidences of coatoms they
-                           are contained in.
-
-- Vrepresentation       -- represents a face by a list of Vrepr it contains.
-- Hrepresentation       -- represents a face by a list of Hrepr it is contained in.
-- bit representation    -- represents incidences as ``uint64_t``-array, where
-                           each Bit represents one incidences. There might
-                           be trailing zeros, to fit alignment-requirements.
-                           In most instances, faces are represented by the
-                           Bit-representation, where each bit corresponds to
-                           an atom.
+,, SEEALSO::
+
+    :mod:`sage.geometry.polyhedron.combinatorial_polyhedron.base`,
+    :mod:`sage.geometry.polyhedron.combinatorial_polyhedron.face_iterator`.
 
 EXAMPLES:
 
@@ -36,7 +16,7 @@ Obtain a face from a face iterator::
     sage: C = CombinatorialPolyhedron(P)
     sage: it = C.face_iter()
     sage: face = next(it); face
-    Combinatorial type of a 2-dimensional face of a 3-dimensional polyhedron
+    A 2-dimensional face of a 3-dimensional combinatorial polyhedron
 
 Obtain a face from a face lattice index:
 
@@ -45,15 +25,15 @@ Obtain a face from a face lattice index:
     sage: sorted(C.face_lattice()._elements)
     [0, 1, 2, 3, 4, 5, 6, 7]
     sage: face = C.face_by_face_lattice_index(0); face
-    Combinatorial type of a -1-dimensional face of a 2-dimensional polyhedron
+    A -1-dimensional face of a 2-dimensional combinatorial polyhedron
 
 Obtain further information regarding a face::
 
     sage: P = polytopes.octahedron()
     sage: C = CombinatorialPolyhedron(P)
     sage: it = C.face_iter(2)
     sage: face = next(it); face
-    Combinatorial type of a 2-dimensional face of a 3-dimensional polyhedron
+    A 2-dimensional face of a 3-dimensional combinatorial polyhedron
     sage: face.Vrepr()
     (A vertex at (0, 0, 1), A vertex at (0, 1, 0), A vertex at (1, 0, 0))
     sage: face.length_Vrepr()
@@ -87,12 +67,12 @@ AUTHOR:
 from __future__ import absolute_import, division, print_function
 
 import numbers
-from sage.rings.integer     cimport smallInteger
-from .conversions           cimport bit_repr_to_Vrepr_list
-from .base                  cimport CombinatorialPolyhedron
-from .bit_vector_operations cimport count_atoms, bit_repr_to_coatom_repr
-from .list_of_all_faces     cimport ListOfAllFaces
-from libc.string            cimport memcpy
+from sage.rings.integer         cimport smallInteger
+from .conversions               cimport bit_repr_to_Vrepr_list
+from .base                      cimport CombinatorialPolyhedron
+from .bit_vector_operations     cimport count_atoms, bit_repr_to_coatom_repr
+from .polyhedron_face_lattice   cimport PolyhedronFaceLattice
+from libc.string                cimport memcpy
 
 cdef extern from "Python.h":
     int unlikely(int) nogil  # Defined by Cython
@@ -109,15 +89,15 @@ cdef class CombinatorialFace(SageObject):
         sage: C = CombinatorialPolyhedron(P)
         sage: it = C.face_iter()
         sage: next(it)
-        Combinatorial type of a 0-dimensional face of a 5-dimensional polyhedron
+        A 0-dimensional face of a 5-dimensional combinatorial polyhedron
 
     Obtain a combinatorial face from an index of the face lattice::
 
         sage: F = C.face_lattice()
         sage: F._elements[3]
         29
         sage: C.face_by_face_lattice_index(29)
-        Combinatorial type of a 1-dimensional face of a 5-dimensional polyhedron
+        A 1-dimensional face of a 5-dimensional combinatorial polyhedron
 
     Obtain the dimension of a combinatorial face::
 
@@ -170,15 +150,15 @@ cdef class CombinatorialFace(SageObject):
             ....: [0,2,3],[1,2,3]])
             sage: it = C.face_iter()
             sage: next(it)     # indirect doctest
-            Combinatorial type of a 2-dimensional face of a 3-dimensional polyhedron
+            A 2-dimensional face of a 3-dimensional combinatorial polyhedron
 
             sage: C.face_by_face_lattice_index(0)
-            Combinatorial type of a -1-dimensional face of a 3-dimensional polyhedron
+            A -1-dimensional face of a 3-dimensional combinatorial polyhedron
 
             sage: TestSuite(sage.geometry.polyhedron.combinatorial_polyhedron.combinatorial_face.CombinatorialFace).run()
         """
         cdef FaceIterator it
-        cdef ListOfAllFaces all_faces
+        cdef PolyhedronFaceLattice all_faces
 
         if isinstance(data, FaceIterator):
             assert dimension is None and index is None, "dimension and index must be ``None``, when providing a face iterator"
@@ -200,14 +180,14 @@ cdef class CombinatorialFace(SageObject):
             self.coatoms            = it.coatoms
             self._hash_index        = it._index
 
-        elif isinstance(data, ListOfAllFaces):
+        elif isinstance(data, PolyhedronFaceLattice):
             all_faces = data
             assert isinstance(dimension, numbers.Integral), "dimension must be an integer"
             assert isinstance(index, numbers.Integral), "index must be an integer"
             assert -1 <= dimension <= all_faces.dimension, "dimension must be a face dimension of the polyhedron"
             assert 0 <= index < all_faces.f_vector[dimension + 1], "index is out of range"
 
-            # Copy data from ListOfAllFaces.
+            # Copy data from PolyhedronFaceLattice.
             self._dual              = all_faces.dual
             self.face_mem           = ListOfFaces(1, all_faces.face_length*64)
             self.face               = self.face_mem.data[0]
@@ -239,13 +219,14 @@ cdef class CombinatorialFace(SageObject):
             sage: it = C.face_iter(dimension=3, dual=False)
             sage: face = next(it)
             sage: face.__repr__()
-            'Combinatorial type of a 3-dimensional face of a 5-dimensional polyhedron'
+            'A 3-dimensional face of a 5-dimensional combinatorial polyhedron'
             sage: it = C.face_iter(dimension=3, dual=True)
             sage: face = next(it)
             sage: face.__repr__()
-            'Combinatorial type of a 3-dimensional face of a 5-dimensional polyhedron'
+            'A 3-dimensional face of a 5-dimensional combinatorial polyhedron'
         """
-        return "Combinatorial type of a {}-dimensional face of a {}-dimensional polyhedron".format(self.dimension(), self.ambient_dimension())
+        return "A {}-dimensional face of a {}-dimensional combinatorial polyhedron"\
+                .format(self.dimension(), self.ambient_dimension())
 
     def __reduce__(self):
         r"""

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

@@ -66,11 +66,11 @@ AUTHOR:
 #                  http://www.gnu.org/licenses/
 #*****************************************************************************
 
-from __future__ import absolute_import, division
+from __future__             import absolute_import, division
 from sage.structure.element import is_Matrix
 
-from libc.string    cimport memset
-from .list_of_faces cimport ListOfFaces
+from libc.string            cimport memset
+from .list_of_faces         cimport ListOfFaces
 
 cdef extern from "Python.h":
     int unlikely(int) nogil  # Defined by Cython
@@ -274,7 +274,7 @@ def incidence_matrix_to_bit_repr_of_facets(matrix):
         14
         sage: facets.n_atoms
         24
-        sage: for i in range(facets.n_faces):
+        sage: for i in range(facets.n_faces):  # long time
         ....:     print(bit_repr_to_Vrepr_list_wrapper(facets, i))
         (18, 19, 20, 21, 22, 23)
         (9, 11, 15, 17, 21, 23)
@@ -454,7 +454,7 @@ def facets_tuple_to_bit_repr_of_facets(tuple facets_input, size_t n_Vrepr):
         sage: bi_pyr = ((0,1,4), (1,2,4), (2,3,4), (3,0,4),
         ....:           (0,1,5), (1,2,5), (2,3,5), (3,0,5))
         sage: facets = facets_tuple_to_bit_repr_of_facets(bi_pyr, 6)
-        sage: for i in range(8):
+        sage: for i in range(8):  # long time
         ....:     print(bit_repr_to_Vrepr_list_wrapper(facets, i))
         (0, 1, 4)
         (1, 2, 4)