Ticket #13917: trac_13917-v2-more_doc.patch

File trac_13917-v2-more_doc.patch, 6.9 KB (added by vdelecroix, 8 years ago)
  • sage/graphs/independent_sets.pyx

    # HG changeset patch
    # User Vincent Delecroix <20100.delecroix at gmail.com>
    # Date 1370547466 -7200
    # Node ID 31eae4462cba814353082054704d0a063267d691
    # Parent  ae02d739de6fb71bcd2495fe5cc695809ef44572
    trac 13917: add more documentation
    
    diff --git a/sage/graphs/independent_sets.pyx b/sage/graphs/independent_sets.pyx
    a b  
    4040
    4141cdef class IndependentSets:
    4242    r"""
    43     An instance of this class represents the set of independent sets of a graph.
     43    The set of independent sets of a graph.
    4444
    45     For more information on independent sets, see the
     45    For more information on independent sets, see
    4646    :wikipedia:`Independent_set_(graph_theory)`.
    4747
    4848    INPUT:
     
    5858    ALGORITHM:
    5959
    6060    The enumeration of independent sets is done naively : given an independent
    61     sets, this implementation considers all ways to add a new vertex to it
    62     (while keeping it an independent sets), and then creates new independent
     61    set, this implementation considers all ways to add a new vertex to it
     62    (while keeping it an independent set), and then creates new independent
    6363    sets from all those that were created this way.
    6464
    6565    The implementation, however, is not recursive.
     
    7878
    7979        sage: from sage.graphs.independent_sets import IndependentSets
    8080        sage: g = graphs.ClawGraph()
    81         sage: list(IndependentSets(g))
     81        sage: I = IndependentSets(g)
     82        sage: list(I)
    8283        [[0], [1], [1, 2], [1, 2, 3], [1, 3], [2], [2, 3], [3], []]
    8384
    8485    Count them::
    8586
    86         sage: IndependentSets(g).cardinality()
     87        sage: I.cardinality()
    8788        9
    8889
    8990    List only the maximal independent sets::
    9091
    91         sage: list(IndependentSets(g, maximal = True))
     92        sage: Im = IndependentSets(g, maximal = True)
     93        sage: list(Im)
    9294        [[0], [1, 2, 3]]
    9395
    9496    And count them::
    9597
    96         sage: IndependentSets(g, maximal = True).cardinality()
     98        sage: Im.cardinality()
    9799        2
    98100
    99101    One can easily obtain an iterator over all independent sets of given
     
    107109    Similarly, one can easily count the number of independent sets of each
    108110    cardinality::
    109111
    110         sage: number_of_is = [0] * g.order()
     112        sage: number_of = [0] * g.order()
    111113        sage: for x in IndependentSets(g):
    112         ...      number_of_is[len(x)] += 1
    113         sage: print number_of_is
     114        ....:     number_of[len(x)] += 1
     115        sage: print number_of
    114116        [1, 10, 30, 30, 5, 0, 0, 0, 0, 0]
     117
     118    Given a subset of the vertices, it is possible to test whether it is an
     119    independent set::
     120
     121        sage: g = graphs.DurerGraph()
     122        sage: I = IndependentSets(g)
     123        sage: [0,2] in I
     124        True
     125        sage: [0,3,5] in I
     126        False
     127
     128    If an element of the subset is not a vertex, then an error is raised::
     129
     130        sage: [0, 'a', 'b', 'c'] in I
     131        Traceback (most recent call last):
     132        ...
     133        ProgrammerError: It should not be a segfault!
    115134    """
    116135    def __init__(self, G, maximal = False, complement = False):
    117136        r"""
     
    150169            ...          print len(IS), len(set(IS2))
    151170            sage: for i in range(5):
    152171            ...       check_matching(graphs.RandomGNP(11,.3))
     172
     173        Check the error for the empty graph::
     174
     175            sage: IndependentSets(graphs.empty_graph())
     176            Traceback (most recent call last):
     177            ...
     178            ProgrammerError: It should not be a segfault!
    153179        """
    154180        cdef int i
    155181        if G.order() == 0:
     
    171197
    172198    def __iter__(self):
    173199        r"""
    174         Returns self, as it has a __next__ method.
     200        Returns an iterator over the independent sets of self.
    175201
    176202        TESTS::
    177203
    178204            sage: from sage.graphs.independent_sets import IndependentSets
    179             sage: list(IndependentSets(graphs.PetersenGraph()))
    180             [[0], [0, 2], [0, 2, 6], [0, 2, 8], [0, 2, 8, 9], [0, 2, 9],
    181              [0, 3], [0, 3, 6], [0, 3, 6, 7], [0, 3, 7], [0, 3, 9],
    182              [0, 6], [0, 6, 7], [0, 7], [0, 7, 8], [0, 8], [0, 8, 9],
    183              [0, 9], [1], [1, 3], [1, 3, 5], [1, 3, 5, 9], [1, 3, 7],
    184              [1, 3, 9], [1, 4], [1, 4, 5], [1, 4, 7], [1, 4, 7, 8],
    185              [1, 4, 8], [1, 5], [1, 5, 9], [1, 7], [1, 7, 8], [1, 8],
    186              [1, 8, 9], [1, 9], [2], [2, 4], [2, 4, 5], [2, 4, 5, 6],
    187              [2, 4, 6], [2, 4, 8], [2, 5], [2, 5, 6], [2, 5, 9],
    188              [2, 6], [2, 8], [2, 8, 9], [2, 9], [3], [3, 5],
    189              [3, 5, 6], [3, 5, 9], [3, 6], [3, 6, 7], [3, 7],
    190              [3, 9], [4], [4, 5], [4, 5, 6], [4, 6], [4, 6, 7], [4, 7],
    191              [4, 7, 8], [4, 8], [5], [5, 6], [5, 9], [6], [6, 7], [7],
    192              [7, 8], [8], [8, 9], [9], []]
     205            sage: I = IndependentSets(graphs.PetersenGraph())
     206            sage: iter1 = iter(I)
     207            sage: iter2 = iter(I)
     208            sage: iter1.next()      # indirect doctest
     209            [0]
     210            sage: iter2.next()      # indirect doctest
     211            [0]
     212            sage: iter2.next()
     213            [0, 2]
     214            sage: iter1.next()
     215            [0, 2]
    193216        """
    194217        cdef int i = 0
    195218
     
    252275                if i == 0:
    253276                    if not self.maximal:
    254277                        count+=1
    255                         yield []
    256 
     278                        if not self.count_only:
     279                            yield []
    257280                    break
    258281
    259282                # Going backward, we explored all we could there !
     
    272295        bitset_free(current_set)
    273296        bitset_free(tmp)
    274297
    275 
    276298    def __dealloc__(self):
    277299        r"""
    278300        Frees everything we ever allocated
     
    310332        r"""
    311333        Checks whether the set is an independent set (possibly maximal)
    312334
     335        INPUT:
     336
    313337        - ``S`` -- a set of vertices to be tested.
    314338
    315         EXAMPLE::
     339        TESTS::
    316340
    317         All independent sets of PetersenGraph are ... independent sets ::
     341        All independent sets of PetersenGraph are... independent sets::
    318342
    319343            sage: from sage.graphs.independent_sets import IndependentSets
     344            sage: G = graphs.PetersenGraph()
    320345            sage: IS = IndependentSets(graphs.PetersenGraph())
    321             sage: all( s in IS for s in IS)
     346            sage: all(s in IS for s in IS)
     347            True
     348
     349        And only them are::
     350
     351            sage: IS2 = [x for x in subsets(G.vertices()) if x in IS]
     352            sage: sorted(IS) == sorted(IS2)
    322353            True
    323354
    324355        Same with maximal independent sets::
    325356
    326357            sage: IS = IndependentSets(graphs.PetersenGraph(), maximal = True)
    327             sage: all( s in IS for s in IS)
     358            sage: S = Subsets(G.vertices())
     359            sage: all(s in IS for s in IS)
     360            True
     361            sage: IS2 = [x for x in subsets(G.vertices()) if x in IS]
     362            sage: sorted(IS) == sorted(IS2)
    328363            True
    329364        """
    330365        # Set of vertices as a bitset