Ticket #6190: trac_6190.patch

File trac_6190.patch, 7.9 KB (added by davidloeffler, 13 years ago)

  • sage/combinat/backtrack.py 

    # HG changeset patch
# User David Loeffler <D.Loeffler@dpmms.cam.ac.uk>
# Date 1243980985 -3600
# Node ID f656ef7ae2f0388d974c332b0429bee0e914f455
# Parent  f77ae09d3d24458409f0431fe7d06d7c250d1f41
[mq]: trac_6190.patch

diff -r f77ae09d3d24 -r f656ef7ae2f0 sage/combinat/backtrack.py
    a b  
    55elements can be enumerated by exploring a search space with a (lazy)
    66tree or graph structure.
    77
    8  - SearchForest:
    9    Depth first search through a tree described by a `children` function
    10  - GenericBacktracker:
    11    Depth first search through a tree described by a `children` function, with branch pruning, ...
    12  - TransitiveIdeal:
    13    Depth first search through a graph described by a `neighbours` relation
    14  - TransitiveIdealGraded:
    15    Breath first search through a graph described by a `neighbours` relation
     8- :class:`~sage.combinat.backtrack.SearchForest`: Depth first search through a
     9  tree described by a ``children`` function.
     10- :class:`~sage.combinat.backtrack.GenericBacktracker`: Depth first search
     11  through a tree described by a ``children`` function, with branch pruning,
     12  etc.
     13- :class:`~sage.combinat.backtrack.TransitiveIdeal`: Depth first search through a
     14  graph described by a ``neighbours`` relation.
     15- :class:`~sage.combinat.backtrack.TransitiveIdealGraded`: Breath first search
     16  through a graph described by a ``neighbours`` relation.
    1617
    17 Todo: find a good and consistent naming scheme!!! Do we want to
    18 emphasize the underlying graph/tree structure? The branch&bound
    19 aspect? The transitive closure of a relation point of view?
     18TODO:
    2019
    21 Todo: do we want TransitiveIdeal(relation, generators) or TransitiveIdeal(generators, relation)?
    22 The code needs to be standardized once the choice is done.
     20#. Find a good and consistent naming scheme! Do we want to emphasize the
     21   underlying graph/tree structure? The branch & bound aspect? The transitive
     22   closure of a relation point of view?
     23
     24#. Do we want ``TransitiveIdeal(relation, generators)`` or
     25   ``TransitiveIdeal(generators, relation)``?  The code needs to be standardized once
     26   the choice is made.
    2327
    2428"""
    2529#*****************************************************************************
    … …  
    3943#*****************************************************************************
    4044class GenericBacktracker(object):
    4145    r"""
    42     A generic backtrack tool for exploring a search space organized as
    43     a tree, with branch pruning, ...
     46    A generic backtrack tool for exploring a search space organized as a tree,
     47    with branch pruning, etc.
    4448
    45     See also ``SearchForest`` and ``TransitiveIdeal`` for handling
    46     simple special cases.
     49    See also :class:`~sage.combinat.backtrack.SearchForest` and
     50    :class:`~sage.combinat.backtrack.TransitiveIdeal` for handling simple
     51    special cases.
    4752    """
    4853
    4954    def __init__(self, initial_data, initial_state):
    … …  
    97102
    98103def search_forest_iterator(roots, children):
    99104    r"""
    100     INPUT:
    101 
    102      - ``roots``: a list (or iterable)
    103 
    104      - ``children``: a function returning a list (or iterable)
    105    
    106105    Returns an iterator on the nodes of the forest having the given
    107106    roots, and where ``children(x)`` returns the children of the node ``x``
    108107    of the forest.  Note that every node of the tree is returned,
    109108    not simply the leaves.
    110109
     110    INPUT:
     111
     112    - ``roots``: a list (or iterable)
     113    - ``children``: a function returning a list (or iterable)
     114       
    111115    EXAMPLES:
    112116   
    113         Search tree where leaves are binary sequences of length 3::
     117    Search tree where leaves are binary sequences of length 3::
    114118
    115119        sage: from sage.combinat.backtrack import search_forest_iterator
    116120        sage: list(search_forest_iterator([[]], lambda l: [l+[0], l+[1]] if len(l) < 3 else []))
    117121        [[], [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]]
    118122       
    119         Search tree where leaves are ordered sequences of length 2 from a 4-set::
     123    Search tree where leaves are ordered sequences of length 2 from a 4-set::
    120124   
    121125        sage: from sage.combinat.backtrack import search_forest_iterator
    122126        sage: list(search_forest_iterator([[]], lambda l: [l + [i] for i in range(4) if i not in l] if len(l) < 2 else []))
    … …  
    142146from sage.combinat.combinat import CombinatorialClass
    143147class SearchForest(CombinatorialClass):
    144148    r"""
    145     INPUT::
     149    Returns the set of nodes of the forest having the given roots, and where
     150    ``children(x)`` returns the children of the node ``x`` of the forest.
    146151
    147      - ``roots``: a list (or iterable)
     152    See also :class:`~sage.combinat.backtrack.GenericBacktracker`,
     153    :class:`~sage.combinat.backtrack.TransitiveIdeal`, and
     154    :class:`~sage.combinat.backtrack.TransitiveIdealGraded`.
    148155
    149      - ``children``: a function returning a list (or iterable)
     156    INPUT:
     157
     158    - ``roots``: a list (or iterable)
     159    - ``children``: a function returning a list (or iterable)
    150160   
    151     Returns the set of nodes of the forest having the given roots, and
    152     where ``children(x)`` returns the children of the node ``x`` of the forest.
    153 
    154     See also ``GenericBacktracker``, ``TransitiveIdeal``, and ``TransitiveIdealGraded``.
    155 
    156161    EXAMPLES:
    157162
    158         A generator object for binary sequencences of length 3, listed::
     163    A generator object for binary sequencences of length 3, listed::
    159164
    160165        sage: list(SearchForest([[]], lambda l: [l+[0], l+[1]] if len(l) < 3 else []))
    161166        [[], [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]]
    162167
    163         A generator object for ordered sequences of length 2 from a 4-set, sampled::
     168    A generator object for ordered sequences of length 2 from a 4-set, sampled::
    164169
    165170        sage: tb = SearchForest([[]], lambda l: [l + [i] for i in range(4) if i not in l] if len(l) < 2 else [])
    166171        sage: tb[0]
    … …  
    185190    def _repr_(self):
    186191        r"""
    187192        TESTS::
     193
    188194            sage: SearchForest((1,), lambda x: [x+1])   # Todo: improve!
    189195            An enumerated set
    190196        """
    … …  
    219225    r"""
    220226    Generic tool for constructing ideals of a relation.
    221227
    222     INPUT::
     228    INPUT:
    223229
    224230    - ``relation``: a function (or callable) returning a list (or iterable)
    225 
    226231    - ``generators``: a list (or iterable)
    227232
    228233    Returns the set `S` of elements that can be obtained by repeated
    … …  
    238243    relation. The memory complexity is the depth, that is the maximal
    239244    distance between a generator and an element of `S`.
    240245
    241     See also ``SearchForest` and ``TransitiveIdealGraded``.
     246    See also :class:`~sage.combinat.backtrack.SearchForest` and
     247    :class:`~sage.combinat.backtrack.TransitiveIdealGraded`.
    242248
    243249    EXAMPLES::
    244250
    … …  
    261267        sage: [p for p in TransitiveIdeal(lambda x:[x],[Permutation([3,1,2,4]), Permutation([2,1,3,4])])]
    262268        [[2, 1, 3, 4], [3, 1, 2, 4]]
    263269
    264     We now illustrates that the enumeration is done lazily, by depth
    265     first search::
     270    We now illustrate that the enumeration is done lazily, by depth first
     271    search::
    266272
    267273        sage: C = TransitiveIdeal(lambda x: [x-1, x+1], (-10, 0, 10))
    268274        sage: f = C.__iter__()
    … …  
    331337    r"""
    332338    Generic tool for constructing ideals of a relation.
    333339
    334     INPUT::
     340    INPUT:
    335341
    336342    - ``relation``: a function (or callable) returning a list (or iterable)
    337 
    338343    - ``generators``: a list (or iterable)
    339344
    340345    Returns the set `S` of elements that can be obtained by repeated
    … …  
    351356    the relation. The memory complexity is the depth, that is the
    352357    maximal distance between a generator and an element of `S`.
    353358
    354     See also ``SearchForest` and ``TransitiveIdeal``.
     359    See also :class:`~sage.combinat.backtrack.SearchForest` and
     360    :class:`~sage.combinat.backtrack.TransitiveIdeal`.
    355361
    356362    EXAMPLES::
    357363