# HG changeset patch
# User David Loeffler
# Date 1243980985 3600
# Node ID f656ef7ae2f0388d974c332b0429bee0e914f455
# Parent f77ae09d3d24458409f0431fe7d06d7c250d1f41
[mq]: trac_6190.patch
diff r f77ae09d3d24 r f656ef7ae2f0 sage/combinat/backtrack.py
 a/sage/combinat/backtrack.py Sun May 31 23:38:12 2009 0700
+++ b/sage/combinat/backtrack.py Tue Jun 02 23:16:25 2009 +0100
@@ 5,21 +5,25 @@
elements can be enumerated by exploring a search space with a (lazy)
tree or graph structure.
  SearchForest:
 Depth first search through a tree described by a `children` function
  GenericBacktracker:
 Depth first search through a tree described by a `children` function, with branch pruning, ...
  TransitiveIdeal:
 Depth first search through a graph described by a `neighbours` relation
  TransitiveIdealGraded:
 Breath first search through a graph described by a `neighbours` relation
+ :class:`~sage.combinat.backtrack.SearchForest`: Depth first search through a
+ tree described by a ``children`` function.
+ :class:`~sage.combinat.backtrack.GenericBacktracker`: Depth first search
+ through a tree described by a ``children`` function, with branch pruning,
+ etc.
+ :class:`~sage.combinat.backtrack.TransitiveIdeal`: Depth first search through a
+ graph described by a ``neighbours`` relation.
+ :class:`~sage.combinat.backtrack.TransitiveIdealGraded`: Breath first search
+ through a graph described by a ``neighbours`` relation.
Todo: find a good and consistent naming scheme!!! Do we want to
emphasize the underlying graph/tree structure? The branch&bound
aspect? The transitive closure of a relation point of view?
+TODO:
Todo: do we want TransitiveIdeal(relation, generators) or TransitiveIdeal(generators, relation)?
The code needs to be standardized once the choice is done.
+#. Find a good and consistent naming scheme! Do we want to emphasize the
+ underlying graph/tree structure? The branch & bound aspect? The transitive
+ closure of a relation point of view?
+
+#. Do we want ``TransitiveIdeal(relation, generators)`` or
+ ``TransitiveIdeal(generators, relation)``? The code needs to be standardized once
+ the choice is made.
"""
#*****************************************************************************
@@ 39,11 +43,12 @@
#*****************************************************************************
class GenericBacktracker(object):
r"""
 A generic backtrack tool for exploring a search space organized as
 a tree, with branch pruning, ...
+ A generic backtrack tool for exploring a search space organized as a tree,
+ with branch pruning, etc.
 See also ``SearchForest`` and ``TransitiveIdeal`` for handling
 simple special cases.
+ See also :class:`~sage.combinat.backtrack.SearchForest` and
+ :class:`~sage.combinat.backtrack.TransitiveIdeal` for handling simple
+ special cases.
"""
def __init__(self, initial_data, initial_state):
@@ 97,26 +102,25 @@
def search_forest_iterator(roots, children):
r"""
 INPUT:

  ``roots``: a list (or iterable)

  ``children``: a function returning a list (or iterable)

Returns an iterator on the nodes of the forest having the given
roots, and where ``children(x)`` returns the children of the node ``x``
of the forest. Note that every node of the tree is returned,
not simply the leaves.
+ INPUT:
+
+  ``roots``: a list (or iterable)
+  ``children``: a function returning a list (or iterable)
+
EXAMPLES:
 Search tree where leaves are binary sequences of length 3::
+ Search tree where leaves are binary sequences of length 3::
sage: from sage.combinat.backtrack import search_forest_iterator
sage: list(search_forest_iterator([[]], lambda l: [l+[0], l+[1]] if len(l) < 3 else []))
[[], [0], [0, 0], [0, 0, 0], [0, 0, 1], [0, 1], [0, 1, 0], [0, 1, 1], [1], [1, 0], [1, 0, 0], [1, 0, 1], [1, 1], [1, 1, 0], [1, 1, 1]]
 Search tree where leaves are ordered sequences of length 2 from a 4set::
+ Search tree where leaves are ordered sequences of length 2 from a 4set::
sage: from sage.combinat.backtrack import search_forest_iterator
sage: list(search_forest_iterator([[]], lambda l: [l + [i] for i in range(4) if i not in l] if len(l) < 2 else []))
@@ 142,25 +146,26 @@
from sage.combinat.combinat import CombinatorialClass
class SearchForest(CombinatorialClass):
r"""
 INPUT::
+ Returns the set of nodes of the forest having the given roots, and where
+ ``children(x)`` returns the children of the node ``x`` of the forest.
  ``roots``: a list (or iterable)
+ See also :class:`~sage.combinat.backtrack.GenericBacktracker`,
+ :class:`~sage.combinat.backtrack.TransitiveIdeal`, and
+ :class:`~sage.combinat.backtrack.TransitiveIdealGraded`.
  ``children``: a function returning a list (or iterable)
+ INPUT:
+
+  ``roots``: a list (or iterable)
+  ``children``: a function returning a list (or iterable)
 Returns the set of nodes of the forest having the given roots, and
 where ``children(x)`` returns the children of the node ``x`` of the forest.

 See also ``GenericBacktracker``, ``TransitiveIdeal``, and ``TransitiveIdealGraded``.

EXAMPLES:
 A generator object for binary sequencences of length 3, listed::
+ A generator object for binary sequencences of length 3, listed::
sage: list(SearchForest([[]], lambda l: [l+[0], l+[1]] if len(l) < 3 else []))
[[], [0], [0, 0], [0, 0, 0], [0, 0, 1], [0, 1], [0, 1, 0], [0, 1, 1], [1], [1, 0], [1, 0, 0], [1, 0, 1], [1, 1], [1, 1, 0], [1, 1, 1]]
 A generator object for ordered sequences of length 2 from a 4set, sampled::
+ A generator object for ordered sequences of length 2 from a 4set, sampled::
sage: tb = SearchForest([[]], lambda l: [l + [i] for i in range(4) if i not in l] if len(l) < 2 else [])
sage: tb[0]
@@ 185,6 +190,7 @@
def _repr_(self):
r"""
TESTS::
+
sage: SearchForest((1,), lambda x: [x+1]) # Todo: improve!
An enumerated set
"""
@@ 219,10 +225,9 @@
r"""
Generic tool for constructing ideals of a relation.
 INPUT::
+ INPUT:
 ``relation``: a function (or callable) returning a list (or iterable)

 ``generators``: a list (or iterable)
Returns the set `S` of elements that can be obtained by repeated
@@ 238,7 +243,8 @@
relation. The memory complexity is the depth, that is the maximal
distance between a generator and an element of `S`.
 See also ``SearchForest` and ``TransitiveIdealGraded``.
+ See also :class:`~sage.combinat.backtrack.SearchForest` and
+ :class:`~sage.combinat.backtrack.TransitiveIdealGraded`.
EXAMPLES::
@@ 261,8 +267,8 @@
sage: [p for p in TransitiveIdeal(lambda x:[x],[Permutation([3,1,2,4]), Permutation([2,1,3,4])])]
[[2, 1, 3, 4], [3, 1, 2, 4]]
 We now illustrates that the enumeration is done lazily, by depth
 first search::
+ We now illustrate that the enumeration is done lazily, by depth first
+ search::
sage: C = TransitiveIdeal(lambda x: [x1, x+1], (10, 0, 10))
sage: f = C.__iter__()
@@ 331,10 +337,9 @@
r"""
Generic tool for constructing ideals of a relation.
 INPUT::
+ INPUT:
 ``relation``: a function (or callable) returning a list (or iterable)

 ``generators``: a list (or iterable)
Returns the set `S` of elements that can be obtained by repeated
@@ 351,7 +356,8 @@
the relation. The memory complexity is the depth, that is the
maximal distance between a generator and an element of `S`.
 See also ``SearchForest` and ``TransitiveIdeal``.
+ See also :class:`~sage.combinat.backtrack.SearchForest` and
+ :class:`~sage.combinat.backtrack.TransitiveIdeal`.
EXAMPLES::