Trac #6637: standardize the interface to TransitiveIdeal and friends

1. Implement a single entry point for recursively enumerated sets:

{{{
     RecursivelyEnumeratedSet(seeds, successors, structure=...,
enumeration=...)
}}}

where `structure` takes values in the set `[None, 'forest', 'graded',
'symmetric']` and `enumeration` takes values in the set `[None, 'depth',
'breadth', 'naive']`.

2. Deprecate `TransitiveIdeal`, `TransitiveIdealGraded` and
`SearchForest` as entry point.

3. `TransitiveIdeal(succ, seeds)` keeps the same behavior as before and
is now the same as `RecursivelyEnumeratedSet(seeds, succ,
structure=None, enumeration='naive')`.

4. `TransitiveIdealGraded(succ, seeds, max_depth)` keeps the same
behavior as before and is now the same as
`RecursivelyEnumeratedSet(seeds, succ, structure=None,
enumeration='breadth', max_depth=max_depth)`.

Remarks:

A. For now the code of `SearchForest` is still in
`sage/combinat/backtrack.py`. It should be moved in
`sage/sets/recursively_enumerated_set.pyx` in a later ticket.

B. `TransitiveIdeal` and `TransitiveIealGraded` are used in the code of
`sage/combinat`, `sage/categories` and `sage/groups` at least. These
should be updated to use `RecursivelyEnumeratedSet` in a later ticket
for speed improvements and also to avoid issues explained in C below.

C. Note that there were some issues with `TransitiveIdeal` and
`TransitiveIdealGraded`, namely:

 - Enumeration of `TransitiveIdeal` is claimed to be depth first search
in the top level file `backtrack.py`, but in fact, it is neither breadth
first neither depth first. It is what I call a naive search.
 - Enumeration of `TransitiveIdealGraded` is indeed breadth first as
claimed but it does not make use of the graded hypothesis at all because
it remembers every generated elements.

See [http://www.liafa.univ-paris-diderot.fr/~labbe/blogue/2014/04/my-
status-report-at-sage-days-57-recursivelyenumeratedset/ my status report
at SageDays57] for more info.

URL: http://trac.sagemath.org/6637
Reported by: nthiery
Ticket author(s): Sébastien Labbé
Reviewer(s): Travis Scrimshaw

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

@@ -30,6 +30,7 @@ Basic Structures
    sage/sets/disjoint_union_enumerated_sets
    sage/sets/set_from_iterator
    sage/sets/finite_enumerated_set
+   sage/sets/recursively_enumerated_set
    sage/sets/finite_set_maps
    sage/sets/finite_set_map_cy
    sage/sets/integer_range

src/module_list.py

@@ -1933,6 +1933,9 @@ def uname_specific(name, value, alternative):
               extra_compile_args = ['-std=c99'],
               depends = flint_depends),
 
+    Extension('sage.sets.recursively_enumerated_set',
+              sources = ['sage/sets/recursively_enumerated_set.pyx']),
+
     ################################
     ##
     ## sage.stats

src/sage/combinat/all.py

@@ -134,7 +134,18 @@
 from matrices.all import *
 # Posets
 from posets.all import *
-from backtrack import TransitiveIdeal, TransitiveIdealGraded, SearchForest
+
+from sage.misc.superseded import deprecated_callable_import
+deprecated_callable_import(6637,
+                           'sage.combinat.backtrack',
+                           globals(),
+                           locals(),
+                           ["SearchForest", 
+                            "TransitiveIdeal", 
+                            "TransitiveIdealGraded"],
+                           ("This class soon will not be available in that "
+                            "way anymore. Use RecursivelyEnumeratedSet "
+                            "instead."))
 
 # Cluster Algebras and Quivers
 from cluster_algebra_quiver.all import *

src/sage/combinat/root_system/plot.py

@@ -214,7 +214,9 @@
 small height in the root poset::
 
     sage: L = RootSystem(["A",1,1]).root_lattice()
-    sage: positive_roots = TransitiveIdealGraded(attrcall("pred"), L.simple_roots())
+    sage: seed = L.simple_roots()
+    sage: succ = attrcall("pred")
+    sage: positive_roots = RecursivelyEnumeratedSet(seed, succ, structure='graded')
     sage: it = iter(positive_roots)
     sage: first_positive_roots = [it.next() for i in range(10)]
     sage: L.plot(roots=first_positive_roots, affine=False, alcoves=False)
@@ -238,7 +240,9 @@
 Here is a polished solution for the first exercise::
 
     sage: L = RootSystem(["A",1,1]).weight_space()
-    sage: positive_coroots = TransitiveIdealGraded(attrcall("pred"), L.simple_coroots())
+    sage: seed = L.simple_coroots()
+    sage: succ = attrcall("pred")
+    sage: positive_coroots = RecursivelyEnumeratedSet(seed, succ, structure='graded')
     sage: it = iter(positive_coroots)
     sage: first_positive_coroots = [it.next() for i in range(20)]
     sage: p = L.plot(fundamental_chamber=True, reflection_hyperplanes=first_positive_coroots,

src/sage/sets/all.py

@@ -3,6 +3,8 @@
 from non_negative_integers import NonNegativeIntegers
 from positive_integers import PositiveIntegers
 from finite_enumerated_set import FiniteEnumeratedSet
+from sage.misc.lazy_import import lazy_import
+lazy_import('sage.sets.recursively_enumerated_set','RecursivelyEnumeratedSet')
 from totally_ordered_finite_set import TotallyOrderedFiniteSet
 from disjoint_union_enumerated_sets import DisjointUnionEnumeratedSets
 from primes import Primes

src/sage/sets/recursively_enumerated_set.pxd

@@ -0,0 +1,28 @@
+#*****************************************************************************
+#       Copyright (C) 2014 Sage
+#
+#  Distributed under the terms of the GNU General Public License (GPL)
+#  The full text of the GPL is available at:
+#                  http://www.gnu.org/licenses/
+#
+###############################################################################
+
+cimport sage.structure.parent
+
+cdef class RecursivelyEnumeratedSet_generic(sage.structure.parent.Parent):
+    cdef readonly _seeds
+    cdef public successors
+    cdef readonly str _enumeration
+    cdef readonly _max_depth
+    cdef readonly _graded_component
+    cdef readonly _graded_component_it
+
+    cpdef seeds(self)
+    cpdef graded_component(self, depth)
+
+cdef class RecursivelyEnumeratedSet_symmetric(RecursivelyEnumeratedSet_generic):
+    cdef set _get_next_graded_component(self, set A, set B)
+
+cdef class RecursivelyEnumeratedSet_graded(RecursivelyEnumeratedSet_generic):
+    cdef set _get_next_graded_component(self, set B)
+