Ticket #15283: trac_15283-rowmotion-dg.patch

File trac_15283-rowmotion-dg.patch, 27.3 KB (added by Darij Grinberg, 9 years ago)

revised version

  • sage/categories/finite_posets.py

    # HG changeset patch
    # User darij grinberg <darijgrinberg@gmail.com>
    # Date 1382371811 25200
    # Node ID c04aa203ff307f5a7098c2c37349abb59ed4a48e
    # Parent  a5b15d54f35086284081a4dc4a9d105c52d835f9
    trac #15283: rowmotion and Panyushev complement iterators, revised
    
    diff --git a/sage/categories/finite_posets.py b/sage/categories/finite_posets.py
    a b Finite posets 
    33
    44Here is some terminology used in this file:
    55
    6 - An *order filter* (or *upper set*) is a subset `S` such that if `x \leq y` and `x\in S` then `y\in S`.
     6- An *order filter* (or *upper set*) of a poset `P` is a subset `S` of `P`
     7  such that if `x \leq y` and `x\in S` then `y\in S`.
    78
    8 - An *order ideal* (or *lower set*) is a subset `S` such that if `x \leq y` and `y\in S` then `x\in S`.
     9- An *order ideal* (or *lower set*) of a poset `P` is a subset `S` of `P`
     10  such that if `x \leq y` and `y\in S` then `x\in S`.
    911"""
    1012#*****************************************************************************
    1113#  Copyright (C) 2011 Nicolas M. Thiery <nthiery at users.sf.net>
    class FinitePosets(Category): 
    8587            Returns whether this poset is *self-dual*, that is
    8688            isomorphic to its dual poset.
    8789
    88             EXAMPLE::
     90            EXAMPLES::
    8991
    9092                sage: P = Poset(([1,2,3],[[1,3],[2,3]]),cover_relations=True)
    9193                sage: P.is_selfdual()
    class FinitePosets(Category): 
    9597                sage: P.is_selfdual()
    9698                True
    9799
     100                sage: P = Poset( {} )
     101                sage: P.is_selfdual()
     102                True
    98103            """
    99104            return self.is_isomorphic( self.dual() )
    100105
    class FinitePosets(Category): 
    104109
    105110        def is_poset_isomorphism(self, f, codomain):
    106111            r"""
     112            Return whether `f` is an isomorphism of posets from
     113            ``self`` to ``codomain``.
     114
    107115            INPUT:
    108116
    109117            - ``f`` -- a function from ``self`` to ``codomain``
    110118            - ``codomain`` -- a poset
    111119
    112             Returns whether `f` is an isomorphism of posets form
    113             ``self`` to ``codomain``.
    114 
    115120            EXAMPLES:
    116121
    117122            We build the poset `D` of divisors of 30, and check that
    118123            it is isomorphic to the boolean lattice `B` of the subsets
    119124            of `\{2,3,5\}` ordered by inclusion, via the reverse
    120             function `f: B \mapsto D, b \rightarrow \prod_{x\in b} x`::
     125            function `f: B \to D, b \mapsto \prod_{x\in b} x`::
    121126
    122127                sage: D = Poset((divisors(30), attrcall("divides")))
    123128                sage: B = Poset(([frozenset(s) for s in Subsets([2,3,5])], attrcall("issubset")))
    class FinitePosets(Category): 
    167172
    168173        def is_poset_morphism(self, f, codomain):
    169174            r"""
     175            Return whether `f` is a morphism of posets from ``self``
     176            to ``codomain``, that is
     177
     178            .. MATH::
     179
     180                x\leq y \Longrightarrow f(x) \leq f(y)
     181
     182            for all `x` and `y` in ``self``.
     183
    170184            INPUT:
    171185
    172186            - ``f`` -- a function from ``self`` to ``codomain``
    173187            - ``codomain`` -- a poset
    174188
    175             Returns whether `f` is a morphism of posets form ``self``
    176             to ``codomain``, that is
    177 
    178             .. math::  x\leq y \Longrightarrow f(x) \leq f(y)
    179 
    180189            EXAMPLES:
    181190
    182191            We build the boolean lattice of the subsets of
    183192            `\{2,3,5,6\}` and the lattice of divisors of `30`, and
    184             check that the map `b \mapsto \gcd(\prod_{x\in b}, 30)` is a
    185             morphism of posets::
     193            check that the map `b \mapsto \gcd(\prod_{x\in b} x, 30)`
     194            is a morphism of posets::
    186195
    187196                sage: D = Poset((divisors(30), attrcall("divides")))
    188197                sage: B = Poset(([frozenset(s) for s in Subsets([2,3,5,6])], attrcall("issubset")))
    class FinitePosets(Category): 
    239248
    240249        def order_ideal_generators(self, ideal, direction='down'):
    241250            r"""
    242             Generators for an order ideal (resp. an order filter)
     251            Return the antichain of (minimal) generators of the order
     252            ideal (resp. order filter) ``ideal``.
    243253
    244254            INPUT:
    245255
    246             - ``ideal`` -- an order ideal `I` of ``self``, as a list (or iterable)
    247             - ``direction`` -- 'up' or 'down' (default: 'down')
     256            - ``ideal`` -- an order ideal `I` (resp. order filter)
     257              of ``self``, as a list (or iterable); this should be
     258              an order ideal if ``direction`` is set to ``'down'``,
     259              and an order filter if ``direction`` is set to
     260              ``'up'``.
     261            - ``direction`` -- ``'up'`` or ``'down'`` (default:
     262              ``'down'``).
    248263
    249             Returns the minimal set of generators for the ideal
    250             `I`. It forms an antichain.
     264            The antichain of (minimal) generators of an order ideal
     265            `I` in a poset `P` is the set of all minimal elements of
     266            `P`. In the case of an order filter, the definition is
     267            similar, but with "maximal" used instead of "minimal".
    251268
    252269            EXAMPLES:
    253270
    class FinitePosets(Category): 
    305322
    306323        def order_ideal_complement_generators(self, antichain, direction='up'):
    307324            r"""
    308             The generators of the complement of an order ideal (resp. order filter)
     325            Return the Panyushev complement of the antichain
     326            ``antichain``.
     327
     328            Given an antichain `A` of a poset `P`, the Panyushev
     329            complement of `A` is defined to be the antichain consisting
     330            of the minimal elements of the order filter `B`, where `B`
     331            is the (set-theoretic) complement of the order ideal of
     332            `P` generated by `A`.
     333
     334            Setting the optional keyword variable ``direction`` to
     335            ``'down'`` leads to the inverse Panyushev complement being
     336            computed instead of the Panyushev complement. The inverse
     337            Panyushev complement of an antichain `A` is the antichain
     338            whose Panyushev complement is `A`. It can be found as the
     339            antichain consisting of the maximal elements of the order
     340            ideal `C`, where `C` is the (set-theoretic) complement of
     341            the order filter of `P` generated by `A`.
     342
     343            :meth:`panyushev_complement` is an alias for this method.
     344
     345            Panyushev complementation is related (actually, isomorphic)
     346            to rowmotion (:meth:`rowmotion`).
    309347
    310348            INPUT:
    311349
    class FinitePosets(Category): 
    316354
    317355            OUTPUT:
    318356
    319             - the complement order filter (resp. order ideal), represented
    320               by its generating antichain
     357            - the generating antichain of the complement order filter
     358              (resp. order ideal) of the order ideal (resp. order filter)
     359              generated by the antichain ``antichain``
    321360
    322361            EXAMPLES::
    323362
    class FinitePosets(Category): 
    360399            The image of the order ideal ``order_ideal`` under rowmotion
    361400            in ``self``.
    362401
     402            Rowmotion on a finite poset `P` is an automorphism of the set
     403            `J(P)` of all order ideals of `P`. One way to define it is as
     404            follows: Given an order ideal `I \in J(P)`, we let `F` be the
     405            set-theoretic complement of `I` in `P`. Furthermore we let
     406            `A` be the antichain consisting of all minimal elements of
     407            `F`. Then, the rowmotion of `I` is defined to be the order
     408            ideal of `P` generated by the antichain `A` (that is, the
     409            order ideal consisting of each element of `P` which has some
     410            element of `A` above it).
     411
     412            Rowmotion is related (actually, isomorphic) to Panyushev
     413            complementation (:meth:`panyushev_complement`).
     414
    363415            INPUT:
    364416
    365417            - ``order_ideal`` -- an order ideal of ``self``, as a set
    class FinitePosets(Category): 
    389441            r"""
    390442            Return the Panyushev orbits of antichains in ``self``.
    391443           
     444            The Panyushev orbit of an antichain is its orbit under
     445            Panyushev complementation (see
     446            :meth:`panyushev_complement`).
     447
    392448            INPUT:
    393449
    394450            - ``element_constructor`` (defaults to ``set``) -- a type
    class FinitePosets(Category): 
    399455            OUTPUT:
    400456
    401457            - the partition of the set of all antichains of ``self`` into
    402               orbits under Panyushev complementation. This is returned as 
    403               a list of lists ``L`` such that for each ``L`` and ``i``, 
     458              orbits under Panyushev complementation. This is returned as
     459              a list of lists ``L`` such that for each ``L`` and ``i``,
    404460              cyclically:
    405461              ``self.order_ideal_complement_generators(L[i]) == L[i+1]``.
    406462              The entries ``L[i]`` are sets by default, but depending on
    class FinitePosets(Category): 
    442498            r"""
    443499            Return the rowmotion orbits of order ideals in ``self``.
    444500
     501            The rowmotion orbit of an order ideal is its orbit under
     502            rowmotion (see :meth:`rowmotion`).
     503
    445504            INPUT:
    446505
    447506            - ``element_constructor`` (defaults to ``set``) -- a type
    class FinitePosets(Category): 
    452511            OUTPUT:
    453512
    454513            - the partition of the set of all order ideals of ``self``
    455               into orbits under rowmotion. This is returned as 
    456               a list of lists ``L`` such that for each ``L`` and ``i``, 
     514              into orbits under rowmotion. This is returned as
     515              a list of lists ``L`` such that for each ``L`` and ``i``,
    457516              cyclically: ``self.rowmotion(L[i]) == L[i+1]``.
    458517              The entries ``L[i]`` are sets by default, but depending on
    459518              the optional keyword variable ``element_constructors``
    class FinitePosets(Category): 
    477536
    478537        def toggling_orbits(self, vs, element_constructor = set):
    479538            r"""
    480             Returns the orbits of order ideals in ``self`` under the
    481             sequence of toggles given by ``vs``.
     539            Return the orbits of order ideals in ``self`` under the
     540            operation of toggling the vertices ``vs[0], vs[1], ...``
     541            in this order.
     542
     543            See :meth:`order_ideal_toggle` for a definition of toggling.
     544
     545            .. WARNING::
     546
     547                The orbits are those under the composition of toggles,
     548                *not* under the single toggles themselves. Thus, for
     549                example, if ``vs == [1,2]``, then the orbits have the
     550                form `(I, T_2 T_1 I, T_2 T_1 T_2 T_1 I, \ldots)`
     551                (where `I` denotes an order ideal and `T_i` means
     552                toggling at `i`) rather than
     553                `(I, T_1 I, T_2 T_1 I, T_1 T_2 T_1 I, \ldots)`.
    482554           
    483555            INPUT:
    484556           
    class FinitePosets(Category): 
    516588                orbits.append(map(element_constructor, orbit))
    517589            return orbits
    518590
     591        def panyushev_orbit_iter(self, antichain, element_constructor=set, stop=True, check=True):
     592            r"""
     593            Iterate over the Panyushev orbit of an antichain
     594            ``antichain`` of ``self``.
     595
     596            The Panyushev orbit of an antichain is its orbit under
     597            Panyushev complementation (see
     598            :meth:`panyushev_complement`).
     599
     600            INPUT:
     601
     602            - ``antichain`` -- an antichain of ``self``, given as an
     603              iterable.
     604
     605            - ``element_constructor`` (defaults to ``set``) -- a type
     606              constructor (``set``, ``tuple``, ``list``, ``frozenset``,
     607              ``iter``, etc.) which is to be applied to the antichains
     608              before they are yielded.
     609
     610            - ``stop`` -- a Boolean (default: ``True``) determining
     611              whether the iterator should stop once it completes its
     612              cycle (this happens when it is set to ``True``) or go on
     613              forever (this happens when it is set to ``False``).
     614
     615            - ``check`` -- a Boolean (default: ``True``) determining
     616              whether ``antichain`` should be checked for being an
     617              antichain.
     618
     619            OUTPUT:
     620
     621            - an iterator over the orbit of the antichain ``antichain``
     622              under Panyushev complementation. This iterator `I` has the
     623              property that ``I[0] == antichain`` and each `i` satisfies
     624              ``self.order_ideal_complement_generators(I[i]) == I[i+1]``,
     625              where ``I[i+1]`` has to be understood as ``I[0]`` if it is
     626              undefined.
     627              The entries ``I[i]`` are sets by default, but depending on
     628              the optional keyword variable ``element_constructors``
     629              they can also be tuples, lists etc.
     630
     631            EXAMPLES::
     632
     633                sage: P = Poset( ( [1,2,3], [ [1,3], [2,3] ] ) )
     634                sage: list(P.panyushev_orbit_iter(set([1, 2])))
     635                [set([1, 2]), set([3]), set([])]
     636                sage: list(P.panyushev_orbit_iter([1, 2]))
     637                [set([1, 2]), set([3]), set([])]
     638                sage: list(P.panyushev_orbit_iter([2, 1]))
     639                [set([1, 2]), set([3]), set([])]
     640                sage: list(P.panyushev_orbit_iter(set([1, 2]), element_constructor=list))
     641                [[1, 2], [3], []]
     642                sage: list(P.panyushev_orbit_iter(set([1, 2]), element_constructor=frozenset))
     643                [frozenset([1, 2]), frozenset([3]), frozenset([])]
     644                sage: list(P.panyushev_orbit_iter(set([1, 2]), element_constructor=tuple))
     645                [(1, 2), (3,), ()]
     646
     647                sage: P = Poset( {} )
     648                sage: list(P.panyushev_orbit_iter([]))
     649                [set([])]
     650
     651                sage: P = Poset({ 1: [2, 3], 2: [4], 3: [4], 4: [] })
     652                sage: Piter = P.panyushev_orbit_iter([2], stop=False)
     653                sage: Piter.next()
     654                set([2])
     655                sage: Piter.next()
     656                set([3])
     657                sage: Piter.next()
     658                set([2])
     659                sage: Piter.next()
     660                set([3])
     661            """
     662            # TODO: implement a generic function taking a set and
     663            # bijections on this set, and returning an orbit of a given
     664            # element.
     665            if check:
     666                for i in antichain:
     667                    for j in antichain:
     668                        if self.gt(i, j):
     669                            raise ValueError("the given antichain is not an antichain")
     670            starter = set(antichain)     # sanitize input
     671            yield element_constructor(starter)
     672            next = starter
     673            if stop:
     674                while True:
     675                    next = self.order_ideal_complement_generators(next)
     676                    if next == starter:
     677                        break
     678                    yield element_constructor(next)
     679            else:
     680                while True:
     681                    next = self.order_ideal_complement_generators(next)
     682                    yield element_constructor(next)
     683
     684        def rowmotion_orbit_iter(self, oideal, element_constructor=set, stop=True, check=True):
     685            r"""
     686            Iterate over the rowmotion orbit of an order ideal
     687            ``oideal`` of ``self``.
     688
     689            The rowmotion orbit of an order ideal is its orbit under
     690            rowmotion (see :meth:`rowmotion`).
     691
     692            INPUT:
     693
     694            - ``oideal`` -- an order ideal of ``self``, given as an
     695              iterable.
     696
     697            - ``element_constructor`` (defaults to ``set``) -- a type
     698              constructor (``set``, ``tuple``, ``list``, ``frozenset``,
     699              ``iter``, etc.) which is to be applied to the order
     700              ideals before they are yielded.
     701
     702            - ``stop`` -- a Boolean (default: ``True``) determining
     703              whether the iterator should stop once it completes its
     704              cycle (this happens when it is set to ``True``) or go on
     705              forever (this happens when it is set to ``False``).
     706
     707            - ``check`` -- a Boolean (default: ``True``) determining
     708              whether ``oideal`` should be checked for being an
     709              order ideal.
     710
     711            OUTPUT:
     712
     713            - an iterator over the orbit of the order ideal ``oideal``
     714              under rowmotion. This iterator `I` has the property that
     715              ``I[0] == oideal`` and that every `i` satisfies
     716              ``self.rowmotion(I[i]) == I[i+1]``, where ``I[i+1]`` has
     717              to be understood as ``I[0]`` if it is undefined.
     718              The entries ``I[i]`` are sets by default, but depending on
     719              the optional keyword variable ``element_constructors``
     720              they can also be tuples, lists etc.
     721
     722            EXAMPLES::
     723
     724                sage: P = Poset( ( [1,2,3], [ [1,3], [2,3] ] ) )
     725                sage: list(P.rowmotion_orbit_iter(set([1, 2])))
     726                [set([1, 2]), set([1, 2, 3]), set([])]
     727                sage: list(P.rowmotion_orbit_iter([1, 2]))
     728                [set([1, 2]), set([1, 2, 3]), set([])]
     729                sage: list(P.rowmotion_orbit_iter([2, 1]))
     730                [set([1, 2]), set([1, 2, 3]), set([])]
     731                sage: list(P.rowmotion_orbit_iter(set([1, 2]), element_constructor=list))
     732                [[1, 2], [1, 2, 3], []]
     733                sage: list(P.rowmotion_orbit_iter(set([1, 2]), element_constructor=frozenset))
     734                [frozenset([1, 2]), frozenset([1, 2, 3]), frozenset([])]
     735                sage: list(P.rowmotion_orbit_iter(set([1, 2]), element_constructor=tuple))
     736                [(1, 2), (1, 2, 3), ()]
     737
     738                sage: P = Poset( {} )
     739                sage: list(P.rowmotion_orbit_iter([]))
     740                [set([])]
     741
     742                sage: P = Poset({ 1: [2, 3], 2: [4], 3: [4], 4: [] })
     743                sage: Piter = P.rowmotion_orbit_iter([1, 2, 3], stop=False)
     744                sage: Piter.next()
     745                set([1, 2, 3])
     746                sage: Piter.next()
     747                set([1, 2, 3, 4])
     748                sage: Piter.next()
     749                set([])
     750                sage: Piter.next()
     751                set([1])
     752                sage: Piter.next()
     753                set([1, 2, 3])
     754
     755                sage: P = Poset({ 1: [4], 2: [4, 5], 3: [5] })
     756                sage: list(P.rowmotion_orbit_iter([1, 2], element_constructor=list))
     757                [[1, 2], [1, 2, 3, 4], [2, 3, 5], [1], [2, 3], [1, 2, 3, 5], [1, 2, 4], [3]]
     758            """
     759            # TODO: implement a generic function taking a set and
     760            # bijections on this set, and returning an orbit of a given
     761            # element.
     762            if check:
     763                for i in oideal:
     764                    for j in self.lower_covers(i):
     765                        if not j in oideal:
     766                            raise ValueError("the given order ideal is not an order ideal")
     767            starter = set(oideal)     # sanitize input
     768            yield element_constructor(starter)
     769            next = starter
     770            if stop:
     771                while True:
     772                    next = self.rowmotion(next)
     773                    if next == starter:
     774                        break
     775                    yield element_constructor(next)
     776            else:
     777                while True:
     778                    next = self.rowmotion(next)
     779                    yield element_constructor(next)
     780
     781        def toggling_orbit_iter(self, vs, oideal, element_constructor=set, stop=True, check=True):
     782            r"""
     783            Iterate over the orbit of an order ideal ``oideal`` of
     784            ``self`` under the operation of toggling the vertices
     785            ``vs[0], vs[1], ...`` in this order.
     786
     787            See :meth:`order_ideal_toggle` for a definition of toggling.
     788
     789            .. WARNING::
     790
     791                The orbit is that under the composition of toggles,
     792                *not* under the single toggles themselves. Thus, for
     793                example, if ``vs == [1,2]``, then the orbit has the
     794                form `(I, T_2 T_1 I, T_2 T_1 T_2 T_1 I, \ldots)`
     795                (where `I` denotes ``oideal`` and `T_i` means
     796                toggling at `i`) rather than
     797                `(I, T_1 I, T_2 T_1 I, T_1 T_2 T_1 I, \ldots)`.
     798
     799            INPUT:
     800
     801            - ``vs``: a list (or other iterable) of elements of ``self``
     802              (but since the output depends on the order, sets should
     803              not be used as ``vs``).
     804
     805            - ``oideal`` -- an order ideal of ``self``, given as an
     806              iterable.
     807
     808            - ``element_constructor`` (defaults to ``set``) -- a type
     809              constructor (``set``, ``tuple``, ``list``, ``frozenset``,
     810              ``iter``, etc.) which is to be applied to the order
     811              ideals before they are yielded.
     812
     813            - ``stop`` -- a Boolean (default: ``True``) determining
     814              whether the iterator should stop once it completes its
     815              cycle (this happens when it is set to ``True``) or go on
     816              forever (this happens when it is set to ``False``).
     817
     818            - ``check`` -- a Boolean (default: ``True``) determining
     819              whether ``oideal`` should be checked for being an
     820              order ideal.
     821
     822            OUTPUT:
     823
     824            - an iterator over the orbit of the order ideal ``oideal``
     825              under toggling the vertices in the list ``vs`` in this
     826              order. This iterator `I` has the property that
     827              ``I[0] == oideal`` and that every `i` satisfies
     828              ``self.order_ideal_toggles(I[i], vs) == I[i+1]``, where
     829              ``I[i+1]`` has to be understood as ``I[0]`` if it is
     830              undefined.
     831              The entries ``I[i]`` are sets by default, but depending on
     832              the optional keyword variable ``element_constructors``
     833              they can also be tuples, lists etc.
     834
     835            EXAMPLES::
     836
     837                sage: P = Poset( ( [1,2,3], [ [1,3], [2,3] ] ) )
     838                sage: list(P.toggling_orbit_iter([1, 3, 1], set([1, 2])))
     839                [set([1, 2])]
     840                sage: list(P.toggling_orbit_iter([1, 2, 3], set([1, 2])))
     841                [set([1, 2]), set([]), set([1, 2, 3])]
     842                sage: list(P.toggling_orbit_iter([3, 2, 1], set([1, 2])))
     843                [set([1, 2]), set([1, 2, 3]), set([])]
     844                sage: list(P.toggling_orbit_iter([3, 2, 1], set([1, 2]), element_constructor=list))
     845                [[1, 2], [1, 2, 3], []]
     846                sage: list(P.toggling_orbit_iter([3, 2, 1], set([1, 2]), element_constructor=frozenset))
     847                [frozenset([1, 2]), frozenset([1, 2, 3]), frozenset([])]
     848                sage: list(P.toggling_orbit_iter([3, 2, 1], set([1, 2]), element_constructor=tuple))
     849                [(1, 2), (1, 2, 3), ()]
     850                sage: list(P.toggling_orbit_iter([3, 2, 1], [2, 1], element_constructor=tuple))
     851                [(1, 2), (1, 2, 3), ()]
     852
     853                sage: P = Poset( {} )
     854                sage: list(P.toggling_orbit_iter([], []))
     855                [set([])]
     856
     857                sage: P = Poset({ 1: [2, 3], 2: [4], 3: [4], 4: [] })
     858                sage: Piter = P.toggling_orbit_iter([1, 2, 4, 3], [1, 2, 3], stop=False)
     859                sage: Piter.next()
     860                set([1, 2, 3])
     861                sage: Piter.next()
     862                set([1])
     863                sage: Piter.next()
     864                set([])
     865                sage: Piter.next()
     866                set([1, 2, 3])
     867                sage: Piter.next()
     868                set([1])
     869            """
     870            # TODO: implement a generic function taking a set and
     871            # bijections on this set, and returning an orbit of a given
     872            # element.
     873            if check:
     874                for i in oideal:
     875                    for j in self.lower_covers(i):
     876                        if not j in oideal:
     877                            raise ValueError("the given order ideal is not an order ideal")
     878            starter = set(oideal)     # sanitize input
     879            yield element_constructor(starter)
     880            next = starter
     881            if stop:
     882                while True:
     883                    next = self.order_ideal_toggles(next, vs)
     884                    if next == starter:
     885                        break
     886                    yield element_constructor(next)
     887            else:
     888                while True:
     889                    next = self.order_ideal_toggles(next, vs)
     890                    yield element_constructor(next)
     891
    519892        def order_ideals_lattice(self, as_ideals=True):
    520893            r"""
    521             Returns the lattice of order ideals of a poset `P`,
    522             ordered by inclusion. The usual notation is `J(P)`.
     894            Return the lattice of order ideals of a poset ``self``,
     895            ordered by inclusion.
    523896
    524             The underlying set is by default the set of order ideals
    525             of `P`. It can be alternatively chosen to be the set of
    526             antichains of `P`.
     897            The lattice of order ideals of a poset `P` is usually
     898            denoted by `J(P)`. Its underlying set is the set of order
     899            ideals of `P`, and its partial order is given by
     900            inclusion.
     901
     902            The order ideals of `P` are in a canonical bijection
     903            with the antichains of `P`. The bijection maps every
     904            order ideal to the antichain formed by its maximal
     905            elements. By setting the ``as_ideals`` keyword variable to
     906            ``False``, one can make this method apply this bijection
     907            before returning the lattice.
    527908
    528909            INPUT:
    529910
    class FinitePosets(Category): 
    579960        @abstract_method(optional = True)
    580961        def antichains(self):
    581962            r"""
    582             Returns all antichains of ``self``.
     963            Return all antichains of ``self``.
    583964
    584965            EXAMPLES::
    585966
  • sage/categories/posets.py

    diff --git a/sage/categories/posets.py b/sage/categories/posets.py
    a b class Posets(Category): 
    370370            r"""
    371371            Return the result of toggling the element ``v`` in the
    372372            order ideal ``I``.
    373            
     373
     374            If `v` is an element of a poset `P`, then toggling the
     375            element `v` is an automorphism of the set `J(P)` of all
     376            order ideals of `P`. It is defined as follows: If `I`
     377            is an order ideal of `P`, then the image of `I` under
     378            toggling the element `v` is
     379
     380            - the set `I \cup \{ v \}`, if `v \not\in I` but
     381              every element of `P` smaller than `v` is in `I`;
     382
     383            - the set `I \setminus \{ v \}`, if `v \in I` but
     384              no element of `P` greater than `v` is in `I`;
     385
     386            - `I` otherwise.
     387
     388            This image always is an order ideal of `P`.
     389
    374390            EXAMPLES::
    375391           
    376392                sage: P = Poset({1: [2,3], 2: [4], 3: []})
    class Posets(Category): 
    407423            Return the result of toggling the elements of the list (or
    408424            iterable) ``vs`` (one by one, from left to right) in the order
    409425            ideal ``I``.
    410            
     426
     427            See :meth:`order_ideal_toggle` for a definition of toggling.
     428
    411429            EXAMPLES::
    412            
     430
    413431                sage: P = Poset({1: [2,3], 2: [4], 3: []})
    414432                sage: I = Set({1, 2})
    415433                sage: P.order_ideal_toggles(I, [1,2,3,4])