Sort key as sort_facets parameter of SimplicialComplex

Author: jdemeyer

src/sage/homology/simplicial_complex.py

@@ -152,6 +152,7 @@
 from __future__ import print_function, absolute_import
 from six.moves import range
 from six import integer_types
+from operator import index as PyNumber_Index
 
 # possible future directions for SimplicialComplex:
 #
@@ -828,7 +829,7 @@ class SimplicialComplex(Parent, GenericCellComplex):
     :param maximality_check: see below
     :type maximality_check: boolean; optional, default ``True``
     :param sort_facets: see below
-    :type sort_facets: boolean; optional, default ``True``
+    :type sort_facets: boolean or sorting key; optional, default ``True``
     :param name_check: see below
     :type name_check: boolean; optional, default ``False``
     :param is_mutable: Set to ``False`` to make this immutable
@@ -857,8 +858,9 @@ class SimplicialComplex(Parent, GenericCellComplex):
     this class may fail if faces which are claimed to be maximal are
     in fact not.
 
-    If ``sort_facets`` is ``True``, sort the vertices in each facet.  If
-    the vertices in different facets are not ordered compatibly (e.g.,
+    If ``sort_facets`` is ``True``, sort the vertices.  You can also
+    specify a sorting key as ``sort_facets``, which is then used to sort.
+    If the vertices in different facets are not ordered compatibly (e.g.,
     if you have facets ``(1, 3, 5)`` and ``(5, 3, 8)``), then homology
     calculations may have unpredictable results.
 
@@ -908,6 +910,11 @@ class SimplicialComplex(Parent, GenericCellComplex):
         sage: SimplicialComplex(from_characteristic_function=(f, l.ground_set()))
         Simplicial complex with 21 vertices and 168 facets
 
+    The vertices can be sorted with a custom key::
+
+        sage: SimplicialComplex([10], sort_facets=str)
+        Simplicial complex with 11 vertices and facets {(0, 1, 10, 2, 3, 4, 5, 6, 7, 8, 9)}
+
     TESTS:
 
     Check that we can make mutable copies (see :trac:`14142`)::
@@ -974,6 +981,13 @@ def __init__(self,
 
             sage: TestSuite(S).run()
             sage: TestSuite(S3).run()
+
+        ::
+
+            sage: SimplicialComplex([2], sort_facets="bogus")
+            Traceback (most recent call last):
+            ...
+            TypeError: sort_facets should be a boolean or callable, not 'bogus'
         """
         if (maximal_faces is not None and
             from_characteristic_function is not None):
@@ -1014,15 +1028,26 @@ def __init__(self,
             self._sorted = False
             return
 
-        if isinstance(vertex_set, (int, Integer)):
-            vertices = tuple(range(vertex_set + 1))
-        elif sort_facets:
-            try:
-                vertices = tuple(sorted(vertex_set))
-            except TypeError:
-                vertices = tuple(sorted(vertex_set, key=str))
+        try:
+            # Check whether vertex_set is an integer
+            n = PyNumber_Index(vertex_set)
+        except TypeError:
+            pass
         else:
-            vertices = tuple(vertex_set)
+            vertex_set = range(n + 1)
+
+        if sort_facets is True:
+            vertex_set = sorted(vertex_set)
+        elif callable(sort_facets):
+            vertex_set = sorted(vertex_set, key=sort_facets)
+        elif not sort_facets:
+            # Ensure that sort_facets is either a callable or boolean
+            sort_facets = False
+        else:
+            raise TypeError("sort_facets should be a boolean or callable, not {!r}"
+                            .format(sort_facets))
+        vertices = tuple(vertex_set)
+
         gen_dict = {}
         for v in vertices:
             if name_check:
@@ -1050,11 +1075,10 @@ def __init__(self,
             if (maximality_check and
                 any(face.is_face(other) for other in good_faces)):
                 continue
-            if sort_facets:
-                try:
-                    face = Simplex(sorted(face.tuple()))
-                except TypeError:
-                    face = Simplex(sorted(face.tuple(), key=str))
+            if sort_facets is True:
+                face = Simplex(sorted(face.tuple()))
+            elif sort_facets is not False:
+                face = Simplex(sorted(face.tuple(), key=sort_facets))
             good_faces.append(face)
 
         # if no maximal faces, add the empty face as a facet
@@ -1065,8 +1089,8 @@ def __init__(self,
         self._vertex_set = vertices
         # self._facets: unsorted list of facets
         self._facets = good_faces
-        # self._sorted: True if the vertex set should be sorted. This
-        # gets used by the add_face method.
+        # self._sorted: True if the vertex set should be sorted or
+        # sorting key. This gets used by the add_face method.
         self._sorted = sort_facets
         # self._faces: dictionary of dictionaries of faces.  The main
         # dictionary is keyed by subcomplexes, and each value is a
@@ -2477,10 +2501,12 @@ def add_face(self, face):
         if not self._is_mutable:
             raise ValueError("This simplicial complex is not mutable")
 
-        if self._sorted:
+        if self._sorted is True:
             new_face = Simplex(sorted(face))
-        else:
+        elif self._sorted is False:
             new_face = Simplex(face)
+        else:
+            new_face = Simplex(sorted(face, key=self._sorted))
 
         face_is_maximal = True
         for other in self._facets:
@@ -4187,7 +4213,7 @@ def _is_numeric(self):
 
         EXAMPLES::
 
-            sage: s = SimplicialComplex()
+            sage: s = SimplicialComplex(sort_facets=str)
             sage: s._is_numeric()
             True
             sage: s.add_face(['a', 'b', 123])
@@ -4212,7 +4238,7 @@ def _translation_to_numeric(self):
 
         EXAMPLES::
 
-            sage: s = SimplicialComplex()
+            sage: s = SimplicialComplex(sort_facets=str)
             sage: s._translation_to_numeric()
             {}
             sage: s.add_face(['a', 'b', 123])
@@ -4240,7 +4266,7 @@ def _translation_from_numeric(self):
 
         EXAMPLES::
 
-            sage: s = SimplicialComplex()
+            sage: s = SimplicialComplex(sort_facets=str)
             sage: s._translation_from_numeric()
             {}
             sage: s.add_face(['a', 'b', 123])