### Navigation

- index
- modules |
- next |
- previous |
- Combinatorics »
- Posets »

# Posets

This module implements finite partially ordered sets. It defines:

`FinitePoset` | A class for finite posets
`FinitePosets_n` | A class for finite posets up to isomorphism (i.e. unlabeled posets)
`Poset()` | Construct a finite poset from various forms of input data.
`is_poset()` | Tests whether a directed graph is acyclic and transitively reduced.

List of Poset methods

`antichains_iterator()` | Returns an iterator over the antichains of the poset.
`antichains()` | Returns the antichains of the poset.
`bottom()` | Returns the bottom element of the poset, if it exists.
`cardinality()` | Returns the number of elements in the poset.
`chains()` | Returns all the chains of `self`
`chain_polytope()` | Returns the chain polytope of the poset.
`chain_polynomial()` | Returns the chain polynomial of the poset.
`closed_interval()` | Returns a list of the elements \(z\) such that \(x \le z \le y\).
`compare_elements()` | Compares \(x\) and \(y\) in the poset.
`comparability_graph()` | Returns the comparability graph of the poset.
`cover_relations_iterator()` | Returns an iterator for the cover relations of the poset.
`cover_relations()` | Returns the list of pairs [u,v] which are cover relations
`covers()` | Returns True if y covers x and False otherwise.
`coxeter_transformation()` | Returns the matrix of the Auslander-Reiten translation acting on the Grothendieck group of the derived category of modules.
`dilworth_decomposition()` | Returns a partition of the points into the minimal number of chains.
`dual()` | Returns the dual poset of the given poset.
`evacuation()` | Computes evacuation on the linear extension associated to the poset `self`.
`f_polynomial()` | Returns the f-polynomial of a bounded poset.
`flag_f_polynomial()` | Returns the flag f-polynomial of a bounded and ranked poset.
`flag_h_polynomial()` | Returns the flag h-polynomial of a bounded and ranked poset.
`frank_network()` | Returns Frank’s network (a DiGraph along with a cost function on its edges) associated to `self`.
`graphviz_string()` | Returns a representation in the DOT language, ready to render in graphviz.
`greene_shape()` | Computes the Greene-Kleitman partition aka Greene shape of the poset `self`.
`h_polynomial()` | Returns the h-polynomial of a bounded poset.
`has_bottom()` | Returns True if the poset has a unique minimal element.
`hasse_diagram()` | Returns the Hasse diagram of `self` as a Sage `DiGraph`.
`has_isomorphic_subposet()` | Return `True` if the poset contains a subposet isomorphic to another poset, and `False` otherwise.
`has_top()` | Returns True if the poset contains a unique maximal element, and False otherwise.
`height()` | Return the height (number of elements in the longest chain) of the poset.
`incomparability_graph()` | Returns the incomparability graph of the poset.
`interval()` | Returns a list of the elements \(z\) such that \(x \le z \le y\).
`is_bounded()` | Returns True if the poset contains a unique maximal element and a unique minimal element, and False otherwise.
`is_chain()` | Returns True if the poset is totally ordered, and False otherwise.
`is_connected()` | Return `True` if the poset is connected, and `False` otherwise.
`is_EL_labelling()` | Returns whether `f` is an EL labelling of `self`
`is_gequal()` | Returns `True` if \(x\) is greater than or equal to \(y\) in the poset, and `False` otherwise.
`is_graded()` | Returns whether this poset is graded.
`is_greater_than()` | Returns `True` if \(x\) is greater than but not equal to \(y\) in the poset, and `False` otherwise.
`is_isomorphic()` | Returns True if both posets are isomorphic.
`is_join_semilattice()` | Returns True is the poset has a join operation, and False otherwise.
`is_lequal()` | Returns `True` if \(x\) is less than or equal to \(y\) in the poset, and `False` otherwise.
`is_less_than()` | Returns `True` if \(x\) is less than but not equal to \(y\) in the poset, and `False` otherwise.
`is_linear_extension()` | Returns whether `l` is a linear extension of `self`
`is_meet_semilattice()` | Returns True if self has a meet operation, and False otherwise.
`isomorphic_subposets_iterator()` | Return an iterator over the subposets isomorphic to another poset.
`isomorphic_subposets()` | Return all subposets isomorphic to another poset.
`is_incomparable_chain_free()` | Returns whether the poset is \((m+n)\)-free.
`is_ranked()` | Returns whether this poset is ranked.
`is_slender()` | Returns whether the poset `self` is slender or not.
`lequal_matrix()` | Computes the matrix whose `(i,j)` entry is 1 if `self.linear_extension()[i] < self.linear_extension()[j]` and 0 otherwise
`level_sets()` | Returns a list l such that l[i+1] is the set of minimal elements of the poset obtained by removing the elements in l[0], l[1], ..., l[i].
`linear_extension()` | Returns a linear extension of this poset.
`linear_extensions()` | Returns the enumerated set of all the linear extensions of this poset
`list()` | List the elements of the poset. This just returns the result of `linear_extension()`.
`lower_covers_iterator()` | Returns an iterator for the lower covers of the element y. An lower cover of y is an element x such that y x is a cover relation.
`lower_covers()` | Returns a list of lower covers of the element y. An lower cover of y is an element x such that y x is a cover relation.
`maximal_antichains()` | Return all maximal antichains of the poset.
`maximal_chains()` | Returns all maximal chains of this poset. Each chain is listed in increasing order.
`maximal_elements()` | Returns a list of the maximal elements of the poset.
`minimal_elements()` | Returns a list of the minimal elements of the poset.
`mobius_function_matrix()` | Returns a matrix whose `(i,j)` entry is the value of the Mobius function evaluated at `self.linear_extension()[i]` and `self.linear_extension()[j]`.
`mobius_function()` | Returns the value of the Mobius function of the poset on the elements x and y.
`open_interval()` | Returns a list of the elements \(z\) such that \(x < z < y\). The order is that induced by the ordering in
`order_complex()` | Returns the order complex associated to this poset.
`order_filter()` | Returns the order filter generated by a list of elements.
`order_ideal()` | Returns the order ideal generated by a list of elements.
`order_polynomial()` | Returns the order polynomial of the poset.
`order_polytope()` | Returns the order polytope of the poset.
`p_partition_enumerator()` | Returns a \(P\)-partition enumerator of the poset.
`plot()` | Returns a Graphic object corresponding the Hasse diagram of the poset.
`product()` | Returns the cartesian product of `self` and `other`.
`promotion()` | Computes the (extended) promotion on the linear extension of the poset `self`
`random_subposet()` | Return a random subposet that contains each element with probability `p`.
`rank_function()` | Returns a rank function of the poset, if it exists.
`rank()` | Returns the rank of an element, or the rank of the poset if element is None.
`relabel()` | Returns a copy of this poset with its elements relabelled
`relations_iterator()` | Returns an iterator for all the relations of the poset.
`relations()` | Returns a list of all relations of the poset.
`show()` | Shows the Graphics object corresponding the Hasse diagram of the poset.
`subposet()` | Returns the poset containing elements with partial order induced by that of self.
`top()` | Returns the top element of the poset, if it exists.
`unwrap()` | Unwraps an element of this poset
`upper_covers_iterator()` | Returns an iterator for the upper covers of the element y. An upper cover of y is an element x such that y x is a cover relation.
`upper_covers()` | Returns a list of upper covers of the element y. An upper cover of y is an element x such that y x is a cover relation.
`width()` | Returns the width of the poset (the size of its longest antichain).
`with_linear_extension()` | Returns a copy of `self` with a different default linear extension.
`zeta_polynomial()` | Returns the zeta polynomial of the poset.

## Classes and functions

class `sage.combinat.posets.posets.``FinitePoset`(hasse_diagram, elements, category, facade, key)

  Bases: `sage.structure.unique_representation.UniqueRepresentation`, `sage.structure.parent.Parent`

  A (finite) \(n\)-element poset constructed from a directed acyclic graph.

  INPUT:

  - `hasse_diagram` – an instance of `FinitePoset`, or a `DiGraph` that is transitively-reduced, acyclic, loop-free, and multiedge-free.
  - `elements` – an optional list of elements, with `element[i]` corresponding to vertex `i`. If `elements` is `None`, then it is set to be the vertex set of the digraph. Note that if this option is set, then `elements` is considered as a specified linear extension of the poset and the \(linear_extension\) attribute is set.
  - `category` – `FinitePosets`, or a subcategory thereof.
  - `facade` – a boolean or `None` (default); whether the `FinitePoset`‘s elements should be wrapped to make them aware of the Poset they belong to.
    - If `facade = True`, the `FinitePoset`‘s elements are exactly those given as input.
    - If `facade = False`, the `FinitePoset`‘s elements will become `PosetElement` objects.
    - If `facade = None` (default) the expected behaviour is the behaviour of `facade = True`, unless the opposite can be deduced from the context (i.e. for instance if a `FinitePoset` is built from another `FinitePoset`, itself built with `facade = False`)
  - `key` – any hashable value (default: `None`).

  EXAMPLES:

      sage: uc = [[2,3], [], [1], [1], [1], [3,4]]
      sage: from sage.combinat.posets.posets import FinitePoset
      sage: P = FinitePoset(DiGraph(dict([[i,uc[i]] for i in range(len(uc))])), facade=False); P
      Finite poset containing 6 elements
      sage: P.cover_relations()
      [[5, 4], [5, 3], [4, 1], [0, 2], [0, 3], [2, 1], [3, 1]]
      sage: TestSuite(P).run()
      sage: P.category()
      Join of Category of finite posets and Category of finite enumerated sets
      sage: P.__class__
      <class 'sage.combinat.posets.posets.FinitePoset_with_category'>

      sage: Q = sage.combinat.posets.posets.FinitePoset(P, facade = False); Q
      Finite poset containing 6 elements

      sage: Q is P
      True

  We keep the same underlying Hasse diagram, but change the elements:

      sage: Q = sage.combinat.posets.posets.FinitePoset(P, elements=[1,2,3,4,5,6], facade=False); Q
      Finite poset containing 6 elements with distinguished linear extension
      sage: Q.cover_relations()
      [[1, 2], [1, 5], [2, 6], [3, 4], [3, 5], [4, 6], [5, 6]]

  We test the facade argument:

      sage: P = Poset(DiGraph({'a':['b'],'b':['c'],'c':['d']}), facade=False)
      sage: P.category()
      Join of Category of finite posets and Category of finite enumerated sets
      sage: parent(P[0]) is P
      True

      sage: Q = Poset(DiGraph({'a':['b'],'b':['c'],'c':['d']}), facade=True)
      sage: Q.category()
      Join of Category of finite posets
          and Category of finite enumerated sets
          and Category of facade sets
      sage: parent(Q[0]) is str
      True
      sage: TestSuite(Q).run(skip = ['_test_an_element']) # is_parent_of is not yet implemented

  Changing a non facade poset to a facade poset:

      sage: PQ = Poset(P, facade=True)
      sage: PQ.category()
      Join of Category of finite posets
          and Category of finite enumerated sets
          and Category of facade sets
      sage: parent(PQ[0]) is str
      True
      sage: PQ is Q
      True

  Changing a facade poset to a non facade poset:

      sage: QP = Poset(Q, facade = False)
      sage: QP.category()
      Join of Category of finite posets
          and Category of finite enumerated sets
      sage: parent(QP[0]) is QP
      True

  Note

  A class that inherits from this class needs to define `Element`. This is the class of the elements that the inheriting class contains. For example, for this class, `FinitePoset`, `Element` is `PosetElement`. It can also define `_dual_class` which is the class of dual posets of this class. E.g. `FiniteMeetSemilattice._dual_class` is `FiniteJoinSemilattice`.

  TESTS:

  Equality is derived from `UniqueRepresentation`. We check that this gives consistent results:

      sage: P = Poset([[1,2],[3],[3]])
      sage: P == P
      True
      sage: Q = Poset([[1,2],[],[1]])
      sage: Q == P
      False
      sage: p1, p2 = Posets(2).list()
      sage: p2 == p1, p1 != p2
      (False, True)
      sage: [[p1.__eq__(p2) for p1 in Posets(2)] for p2 in Posets(2)]
      [[True, False], [False, True]]
      sage: [[p2.__eq__(p1) for p1 in Posets(2)] for p2 in Posets(2)]
      [[True, False], [False, True]]
      sage: [[p2 == p1 for p1 in Posets(3)] for p2 in Posets(3)]
      [[True, False, False, False, False],
       [False, True, False, False, False],
       [False, False, True, False, False],
       [False, False, False, True, False],
       [False, False, False, False, True]]

      sage: [[p1.__ne__(p2) for p1 in Posets(2)] for p2 in Posets(2)]
      [[False, True], [True, False]]
      sage: P = Poset([[1,2,4],[3],[3]])
      sage: Q = Poset([[1,2],[],[1],[4]])
      sage: P != Q
      True
      sage: P != P
      False
      sage: Q != Q
      False
      sage: [[p1.__ne__(p2) for p1 in Posets(2)] for p2 in Posets(2)]
      [[False, True], [True, False]]

      sage: P = Poset((divisors(12), attrcall("divides")), linear_extension=True)
      sage: Q = Poset(P)
      sage: Q == P
      False
      sage: Q = Poset(P, linear_extension=True)
      sage: Q == P
      True

  `Element`

    alias of `PosetElement`

  `antichains`(element_constructor=<type 'list'>)

    Returns the antichains of the poset.

    INPUT:

    > - `element_constructor` – a function taking an iterable as argument (default: list)

    OUTPUT: an enumerated set

    An antichain of a poset is a collection of elements of the poset that are pairwise incomparable.

    EXAMPLES:

        sage: A = Posets.PentagonPoset().antichains(); A
        Set of antichains of Finite lattice containing 5 elements
        sage: list(A)
        [[], [0], [1], [1, 2], [1, 3], [2], [3], [4]]
        sage: A.cardinality()
        8
        sage: A[3]
        [1, 2]
        sage: list(Posets.AntichainPoset(3).antichains())
        [[], [2], [2, 1], [2, 1, 0], [2, 0], [1], [1, 0], [0]]
        sage: list(Posets.ChainPoset(3).antichains())
        [[], [0], [1], [2]]

    To get the antichains of a given size one can currently use:

        sage: list(A.elements_of_depth_iterator(2))
        [[1, 2], [1, 3]]

    Eventually the following syntax will be accepted:

        sage: A.subset(size = 2) # todo: not implemented

    To get the antichains as, say, sets, one may use the `element_constructor` option:

        sage: list(Posets.ChainPoset(3).antichains(element_constructor = set))
        [set(), {0}, {1}, {2}]

    Note

    Internally, this uses `sage.combinat.subsets_pairwise.PairwiseCompatibleSubsets` and `SearchForest`. At this point, iterating through this set is about twice slower than using `antichains_iterator()` (tested on `posets.AntichainPoset(15)`). The algorithm is the same (depth first search through the tree), but `antichains_iterator()` manually inlines things which apparently avoids some infrastructure overhead.

    On the other hand, this returns a full featured enumerated set, with containment testing, etc.

    See also

    `maximal_antichains()`

  `antichains_iterator`()

    Returns an iterator over the antichains of the poset.

    EXAMPLES:

        sage: Posets.PentagonPoset().antichains_iterator()
        <generator object antichains_iterator at ...>

    See also

    `antichains()`

  `bottom`()

    Returns the bottom element of the poset, if it exists.

    EXAMPLES:

        sage: P = Poset({0:[3],1:[3],2:[3],3:[4],4:[]})
        sage: P.bottom() is None
        True
        sage: Q = Poset({0:[1],1:[]})
        sage: Q.bottom()
        0

  `canonical_label`()

    Return the unique poset on the labels \(\{0, \ldots, n-1\}\) (where \(n\) is the number of elements in `self`) that is isomorphic to `self` and invariant in the isomorphism class.

    See also

    - `canonical_label()`

    EXAMPLES:

        sage: P = Poset((divisors(12), attrcall("divides")), linear_extension=True, facade=False)
        sage: P.list()
        [1, 2, 3, 4, 6, 12]
        sage: P.cover_relations()
        [[1, 2], [1, 3], [2, 4], [2, 6], [3, 6], [4, 12], [6, 12]]
        sage: Q = P.canonical_label()
        sage: Q.list()
        [0, 1, 2, 3, 4, 5]
        sage: Q.cover_relations()
        [[0, 1], [0, 2], [1, 4], [2, 3], [2, 4], [3, 5], [4, 5]]

    As a facade:

        sage: P = Poset((divisors(12), attrcall("divides")), facade=True, linear_extension=True)
        sage: P.list()
        [1, 2, 3, 4, 6, 12]
        sage: P.cover_relations()
        [[1, 2], [1, 3], [2, 4], [2, 6], [3, 6], [4, 12], [6, 12]]
        sage: Q = P.canonical_label()
        sage: Q.list()
        [0, 1, 2, 3, 4, 5]
        sage: Q.cover_relations()
        [[0, 1], [0, 2], [1, 4], [2, 3], [2, 4], [3, 5], [4, 5]]

    TESTS:

        sage: P = Poset(digraphs.Path(10), linear_extension = True)
        sage: Q = P.canonical_label()
        sage: Q.linear_extension()
        [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
        sage: Q.cover_relations()
        [[0, 1], [1, 2], [2, 3], [3, 4], [4, 5], [5, 6], [6, 7], [7, 8], [8, 9]]
        sage: P = Poset(digraphs.Path(10))
        sage: Q = P.canonical_label()
        sage: Q.linear_extension()
        [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
        sage: Q.cover_relations()
        [[0, 1], [1, 2], [2, 3], [3, 4], [4, 5], [5, 6], [6, 7], [7, 8], [8, 9]]

  `cardinality`()

    Returns the number of elements in the poset.

    EXAMPLES:

        sage: Poset([[1,2,3],[4],[4],[4],[]]).cardinality()
        5

  `chain_polynomial`()

    Return the chain polynomial of `self`.

    The coefficient of \(q^k\) is the number of chains of length \(k\) in `self`. The length of a chain is the number of elements.

    Warning

    This is not what has been called the chain polynomial in [St1986]. The latter is identical with the order polynomial (`order_polynomial()`).

    EXAMPLES:

        sage: P = Posets.ChainPoset(3)
        sage: t = P.chain_polynomial(); t
        q^3 + 3*q^2 + 3*q + 1
        sage: t(1) == len(list(P.chains()))
        True

        sage: P = Posets.BooleanLattice(3)
        sage: P.chain_polynomial()
        6*q^4 + 18*q^3 + 19*q^2 + 8*q + 1

        sage: P = Posets.AntichainPoset(5)
        sage: P.chain_polynomial()
        5*q + 1

        sage: P = Poset({})
        sage: P.chain_polynomial()
        1
        sage: parent(P.chain_polynomial())
        Univariate Polynomial Ring in q over Integer Ring

        sage: R = Poset({1: []})
        sage: R.chain_polynomial()
        q + 1

  `chain_polytope`()

    Return the chain polytope of the poset `self`.

    The chain polytope of a finite poset \(P\) is defined as the subset of \(\RR^P\) consisting of all maps \(x : P \to \RR\) satisfying

    \[x(p) \geq 0 \mbox{ for all } p \in P,\]

    and

    \[\begin{split}x(p_1) + x(p_2) + \ldots + x(p_k) \leq 1 \mbox{ for all chains } p_1 < p_2 < \ldots < p_k \mbox{ in } P.\end{split}\]

    This polytope was defined and studied in [St1986].

    EXAMPLES:

        sage: P = posets.AntichainPoset(3)
        sage: Q = P.chain_polytope();Q
        A 3-dimensional polyhedron in QQ^3 defined as the convex hull of 8 vertices
        sage: P = posets.PentagonPoset()
        sage: Q = P.chain_polytope();Q
        A 5-dimensional polyhedron in QQ^5 defined as the convex hull of 8 vertices

  `chains`(element_constructor=<type 'list'>, exclude=None)

    Return all the chains of `self`.

    INPUT:

    - `element_constructor` – a function taking an iterable as

        argument (default: `list`)

    - `exclude` – elements of the poset to be excluded (default: `None`)

    OUTPUT:

    The enumerated set of all chains of `self`, each of which is given as an `element_constructor`.

    A chain of a poset is a set of elements of the poset that are pairwise comparable.

    EXAMPLES:

        sage: A = Posets.PentagonPoset().chains(); A
        Set of chains of Finite lattice containing 5 elements
        sage: list(A)
        [[], [0], [0, 1], [0, 1, 4], [0, 2], [0, 2, 3], [0, 2, 3, 4], [0, 2, 4], [0, 3], [0, 3, 4], [0, 4], [1], [1, 4], [2], [2, 3], [2, 3, 4], [2, 4], [3], [3, 4], [4]]

    To get the chains of a given size one can currently use:

        sage: list(A.elements_of_depth_iterator(2))
        [[0, 1], [0, 2], [0, 3], [0, 4], [1, 4], [2, 3], [2, 4], [3, 4]]

    For bounded posets, one can exclude the bounds as follows:

        sage: P = Posets.DiamondPoset(5)
        sage: list(P.chains(exclude=[0, 4]))
        [[], [1], [2], [3]]

    Another example of exclusion of vertices:

        sage: P = Poset({1: [2, 3], 2: [4], 3: [4, 5]})
        sage: list(P.chains(element_constructor=tuple, exclude=[3]))
        [(), (1,), (1, 2), (1, 2, 4), (1, 4), (1, 5), (2,), (2, 4), (4,), (5,)]

    Eventually the following syntax will be accepted:

        sage: A.subset(size = 2) # todo: not implemented

    See also

    `maximal_chains()`, `antichains()`

  `characteristic_polynomial`()

    Return the characteristic polynomial of a graded poset `self`.

    If \(P\) is a graded poset with rank \(n\) and a unique minimal element \(\hat{0}\), then the characteristic polynomial of \(P\) is defined to be

    \[\sum_{x \in P} \mu(\hat{0}, x) q^{n-\rho(x)} \in \ZZ[q],\]

    where \(\rho\) is the rank function, and \(\mu\) is the Moebius function of \(P\).

    See section 3.10 of [EnumComb1].

    EXAMPLES:

        sage: P = Posets.DiamondPoset(5)
        sage: P.characteristic_polynomial()
        q^2 - 3*q + 2
        sage: P = Poset({1:[2,3],2:[4],3:[5],4:[6],5:[6],6:[7]})
        sage: P.characteristic_polynomial()
        q^4 - 2*q^3 + q
        sage: P = Poset({1: []})
        sage: P.characteristic_polynomial()
        1

  `closed_interval`(x, y)

    Return a list of the elements \(z\) such that \(x \le z \le y\).

    EXAMPLES:

        sage: uc = [[1,3,2],[4],[4,5,6],[6],[7],[7],[7],[]]
        sage: dag = DiGraph(dict(zip(range(len(uc)),uc)))
        sage: P = Poset(dag)
        sage: I = set(map(P,[2,5,6,4,7]))
        sage: I == set(P.closed_interval(2,7))
        True

  `comparability_graph`()

    Returns the comparability graph of `self`.

    See Wikipedia article Comparability_graph

    See also

    `incomparability_graph()`, `sage.graphs.comparability`

    EXAMPLES:

        sage: p = posets.ChainPoset(4)
        sage: p.comparability_graph().is_isomorphic(graphs.CompleteGraph(4))
        True

        sage: p = posets.DiamondPoset(5)
        sage: g = p.comparability_graph(); g
        Comparability graph on 5 vertices
        sage: g.size()
        7

  `compare_elements`(x, y)

    Compare \(x\) and \(y\) in the poset.

    If `x` = `y`, then `0` is returned; if `x` < `y`, then `-1` is returned; if `x` > `y`, then `1` is returned; and if `x` and `y` are not comparable, then `None` is returned.

    EXAMPLES:

        sage: P = Poset([[1,2],[4],[3],[4],[]])
        sage: P.compare_elements(0,0)
        0
        sage: P.compare_elements(0,4)
        -1
        sage: P.compare_elements(4,0)
        1
        sage: P.compare_elements(1,2)

  `cover_relations`()

    Returns the list of pairs [u,v] of elements of the poset such that u v is a cover relation (that is, u v and there does not exist z such that u z v).

    EXAMPLES:

        sage: Q = Poset({0:[2], 1:[2], 2:[3], 3:[4], 4:[]})
        sage: Q.cover_relations()
        [[1, 2], [0, 2], [2, 3], [3, 4]]

  `cover_relations_iterator`()

    Returns an iterator for the cover relations of the poset.

    EXAMPLES:

        sage: Q = Poset({0:[2], 1:[2], 2:[3], 3:[4], 4:[]})
        sage: type(Q.cover_relations_iterator())
        <type 'generator'>
        sage: [z for z in Q.cover_relations_iterator()]
        [[1, 2], [0, 2], [2, 3], [3, 4]]

  `covers`(x, y)

    Returns True if y covers x and False otherwise.

    EXAMPLES:

        sage: Q = Poset([[1,5],[2,6],[3],[4],[],[6,3],[4]])
        sage: Q.covers(Q(1),Q(6))
        True
        sage: Q.covers(Q(1),Q(4))
        False

  `coxeter_transformation`()

    Returns the matrix of the Auslander-Reiten translation acting on the Grothendieck group of the derived category of modules on the poset `self`, in the basis of simple modules. This matrix is usually called the Coxeter transformation.

    EXAMPLES:

        sage: Posets.PentagonPoset().coxeter_transformation()
        [ 0  0  0  0 -1]
        [ 0  0  0  1 -1]
        [ 0  1  0  0 -1]
        [-1  1  1  0 -1]
        [-1  1  0  1 -1]

    TESTS:

        sage: M = Posets.PentagonPoset().coxeter_transformation()
        sage: M**8 == 1
        True

  `dilworth_decomposition`()

    Return a partition of the points into the minimal number of chains.

    According to Dilworth’s theorem, the points of a poset can be partitioned into \(\alpha\) chains, where \(\alpha\) is the cardinality of its largest antichain. This method returns such a partition.

    See Wikipedia article Dilworth’s_theorem.

    See also

    `width()` – return the width of the poset.

    ALGORITHM:

    We build a bipartite graph in which a vertex \(v\) of the poset is represented by two vertices \(v^-,v^+\). For any two \(u,v\) such that \(u<v\) in the poset we add an edge \(v^+u^-\).

    A matching in this graph is equivalent to a partition of the poset into chains: indeed, a chain \(v_1...v_k\) gives rise to the matching \(v_1^+v_2^-,v_2^+v_3^-,...\), and from a matching one can build the union of chains.

    According to Dilworth’s theorem, the number of chains is equal to
      \(\alpha\) (the posets’ width).

    EXAMPLE:

        sage: p = posets.BooleanLattice(4)
        sage: p.width()
        6
        sage: p.dilworth_decomposition()  # random
        [[7, 6, 4], [11, 3], [12, 8, 0], [13, 9, 1], [14, 10, 2], [15, 5]]

    TESTS:

        sage: p = posets.IntegerCompositions(5)
        sage: d = p.dilworth_decomposition()
        sage: for chain in d:
        ....:    for i in range(len(chain)-1):
        ....:        assert p.is_greater_than(chain[i],chain[i+1])
        sage: set(p) == set().union(*d)
        True

  `dual`()

    Return the dual poset of the given poset.

    EXAMPLES:

        sage: P = Poset(([1,2,3],[[1,2],[1,3]]))
        sage: P.cover_relations()
        [[1, 2], [1, 3]]
        sage: Q = P.dual()
        sage: Q.cover_relations()
        [[3, 1], [2, 1]]

        sage: P = LatticePoset([[1,2],[3],[3]], facade = True)
        sage: P.cover_relations()
        [[0, 1], [0, 2], [1, 3], [2, 3]]
        sage: Q = P.dual()
        sage: Q.cover_relations()
        [[3, 2], [3, 1], [2, 0], [1, 0]]
        sage: Q.category()
        Join of Category of finite lattice posets
            and Category of finite enumerated sets
            and Category of facade sets
        sage: Q.__class__
        <class 'sage.combinat.posets.lattices.FiniteLatticePoset_with_category'>

        sage: P = MeetSemilattice([[1,2],[3],[3]])
        sage: P.dual().__class__
        <class 'sage.combinat.posets.lattices.FiniteJoinSemilattice_with_category'>
        sage: P = JoinSemilattice([[1,2],[3],[3]])
        sage: P.dual().__class__
        <class 'sage.combinat.posets.lattices.FiniteMeetSemilattice_with_category'>

  `evacuation`()

    Compute evacuation on the linear extension associated to the poset `self`.

    OUTPUT:

    - an isomorphic poset, with the same default linear extension

    Evacuation is defined on a poset `self` of size \(n\) by applying the evacuation operator \((\tau_1 \cdots \tau_{n-1}) (\tau_1 \cdots \tau_{n-2}) \cdots (\tau_1)\), to the default linear extension \(\pi\) of `self` (see `evacuation()`), and relabeling `self` accordingly. For more details see [Stan2009].

    See also

    - `linear_extension()`
    - `with_linear_extension()` and the `linear_extension` option of `Poset()`
    - `evacuation()`
    - `promotion()`

    REFERENCES:

    [Stan2009] | (1, 2, 3) Richard Stanley, Promotion and evacuation, Electron. J. Combin. 16 (2009), no. 2, Special volume in honor of Anders Björner, Research Paper 9, 24 pp.

    EXAMPLES:

        sage: P = Poset(([1,2], [[1,2]]), linear_extension=True, facade=False)
        sage: P.evacuation()
        Finite poset containing 2 elements with distinguished linear extension
        sage: P.evacuation() == P
        True

        sage: P = Poset(([1,2,3,4,5,6,7], [[1,2],[1,4],[2,3],[2,5],[3,6],[4,7],[5,6]]), linear_extension=True, facade=False)
        sage: P.list()
        [1, 2, 3, 4, 5, 6, 7]
        sage: Q = P.evacuation(); Q
        Finite poset containing 7 elements with distinguished linear extension
        sage: Q.cover_relations()
        [[1, 2], [1, 3], [2, 5], [3, 4], [3, 6], [4, 7], [6, 7]]

    Note that the results depend on the linear extension associated to the poset:

        sage: P = Poset(([1,2,3,4,5,6,7], [[1,2],[1,4],[2,3],[2,5],[3,6],[4,7],[5,6]]))
        sage: P.list()
        [1, 2, 3, 5, 6, 4, 7]
        sage: Q = P.evacuation(); Q
        Finite poset containing 7 elements with distinguished linear extension
        sage: Q.cover_relations()
        [[1, 2], [1, 5], [2, 3], [5, 6], [5, 4], [6, 7], [4, 7]]

    Here is an example of a poset where the vertices are not labelled by \(\{1,2,\ldots,n\}\):

        sage: P = Poset((divisors(15), attrcall("divides")), linear_extension = True)
        sage: P.list()
        [1, 3, 5, 15]
        sage: Q = P.evacuation(); Q
        Finite poset containing 4 elements with distinguished linear extension
        sage: Q.cover_relations()
        [[1, 3], [1, 5], [3, 15], [5, 15]]

    AUTHOR:

    - Anne Schilling (2012-02-18)
  `f_polynomial`()

    Return the \(f\)-polynomial of a bounded poset `self`.

    This is the \(f\)-polynomial of the order complex of the poset minus its bounds.

    The coefficient of \(q^i\) is the number of chains of \(i+1\) elements containing both bounds of the poset.

    See also

    `is_bounded()`, `h_polynomial()`, `order_complex()`, `sage.homology.cell_complex.GenericCellComplex.f_vector()`

    Warning

    This is slightly different from the `fPolynomial` method in Macaulay2.

    EXAMPLES:

        sage: P = Posets.DiamondPoset(5)
        sage: P.f_polynomial()
        3*q^2 + q
        sage: P = Poset({1:[2,3],2:[4],3:[5],4:[6],5:[7],6:[7]})
        sage: P.f_polynomial()
        q^4 + 4*q^3 + 5*q^2 + q

        sage: P = Poset({2: []})
        sage: P.f_polynomial()
        1

  `flag_f_polynomial`()

    Return the flag \(f\)-polynomial of a bounded and ranked poset `self`.

    This is the sum, over all chains containing both bounds, of a monomial encoding the ranks of the elements of the chain.

    More precisely, if \(P\) is a bounded ranked poset, then the flag \(f\)-polynomial of \(P\) is defined as the polynomial

    \[\begin{split}\sum_{\substack{p_0 < p_1 < \ldots < p_k, \\ p_0 = \min P, \ p_k = \max P}} x_{\rho(p_1)} x_{\rho(p_2)} \cdots x_{\rho(p_k)} \in \ZZ[x_1, x_2, \cdots, x_n]\end{split}\]

    where \(\min P\) and \(\max P\) are (respectively) the minimum and the maximum of \(P\), where \(\rho\) is the rank function of \(P\) (normalized to satisfy \(\rho(\min P) = 0\)), and where \(n\) is the rank of \(\max P\). (Note that the indeterminate \(x_0\) doesn’t actually appear in the polynomial.)

    For technical reasons, the polynomial is returned in the slightly larger ring \(\ZZ[x_0, x_1, x_2, \cdots, x_{n+1}]\) by this method.

    See Wikipedia article h-vector.

    See also

    `is_bounded()`, `flag_h_polynomial()`

    EXAMPLES:

        sage: P = Posets.DiamondPoset(5)
        sage: P.flag_f_polynomial()
        3*x1*x2 + x2

        sage: P = Poset({1:[2,3],2:[4],3:[5],4:[6],5:[6]})
        sage: fl = P.flag_f_polynomial(); fl
        2*x1*x2*x3 + 2*x1*x3 + 2*x2*x3 + x3
        sage: q = polygen(ZZ,'q')
        sage: fl(q,q,q,q) == P.f_polynomial()
        True

        sage: P = Poset({1:[2,3,4],2:[5],3:[5],4:[5],5:[6]})
        sage: P.flag_f_polynomial()
        3*x1*x2*x3 + 3*x1*x3 + x2*x3 + x3

        sage: P = Poset({2: [3]})
        sage: P.flag_f_polynomial()
        x1

        sage: P = Poset({2: []})
        sage: P.flag_f_polynomial()
        1

  `flag_h_polynomial`()

    Return the flag \(h\)-polynomial of a bounded and ranked poset `self`.

    If \(P\) is a bounded ranked poset whose maximal element has rank \(n\) (where the minimal element is set to have rank \(0\)), then the flag \(h\)-polynomial of \(P\) is defined as the polynomial

    \[\prod_{k=1}^n (1-x_k) \cdot f \left(\frac{x_1}{1-x_1}, \frac{x_2}{1-x_2}, \cdots, \frac{x_n}{1-x_n}\right) \in \ZZ[x_1, x_2, \cdots, x_n],\]

    where \(f\) is the flag \(f\)-polynomial of \(P\) (see `flag_f_polynomial()`).

    For technical reasons, the polynomial is returned in the slightly larger ring \(\QQ[x_0, x_1, x_2, \cdots, x_{n+1}]\) by this method.

    See Wikipedia article h-vector.

    See also

    `is_bounded()`, `flag_f_polynomial()`

    EXAMPLES:

        sage: P = Posets.DiamondPoset(5)
        sage: P.flag_h_polynomial()
        2*x1*x2 + x2

        sage: P = Poset({1:[2,3],2:[4],3:[5],4:[6],5:[6]})
        sage: fl = P.flag_h_polynomial(); fl
        -x1*x2*x3 + x1*x3 + x2*x3 + x3
        sage: q = polygen(ZZ,'q')
        sage: fl(q,q,q,q) == P.h_polynomial()
        True

        sage: P = Poset({1:[2,3,4],2:[5],3:[5],4:[5],5:[6]})
        sage: P.flag_h_polynomial()
        2*x1*x3 + x3

        sage: P = posets.ChainPoset(4)
        sage: P.flag_h_polynomial()
        x3

        sage: P = Poset({2: [3]})
        sage: P.flag_h_polynomial()
        x1

        sage: P = Poset({2: []})
        sage: P.flag_h_polynomial()
        1

  `frank_network`()

    Computes Frank’s network of the poset `self`. This is defined in Section 8 of [BF1999].

    OUTPUT:

    A pair \((G, e)\), where \(G\) is Frank’s network of \(P\) encoded as a `DiGraph`, and \(e\) is the cost function on its edges encoded as a dictionary (indexed by these edges, which in turn are encoded as tuples of 2 vertices).

    Note

    Frank’s network of \(P\) is a certain directed graph with \(2|P| + 2\) vertices, defined in Section 8 of [BF1999]. Its set of vertices consists of two vertices \((0, p)\) and \((1, p)\) for each element \(p\) of \(P\), as well as two vertices \((-1, 0)\) and \((2, 0)\). (These notations are not the ones used in [BF1999]; see the table below for their relation.) The edges are:

    - for each \(p\) in \(P\), an edge from \((-1, 0)\) to \((0, p)\);
    - for each \(p\) in \(P\), an edge from \((1, p)\) to \((2, 0)\);
    - for each \(p\) and \(q\) in \(P\) such that \(x \geq y\), an edge from \((0, p)\) to \((1, q)\).

    We make this digraph into a network in the sense of flow theory as follows: The vertex \((-1, 0)\) is considered as the source of this network, and the vertex \((2, 0)\) as the sink. The cost function is defined to be \(1\) on the edge from \((0, p)\) to \((1, p)\) for each \(p \in P\), and to be \(0\) on every other edge. The capacity is \(1\) on each edge. Here is how to translate this notations into that used in [BF1999]:

        our notations                    [BF1999]
           (-1, 0)                          s
           (0, p)                          x_p
           (1, p)                          y_p
           (2, 0)                           t
            a[e]                           a(e)

    REFERENCES:

    [BF1999] | (1, 2, 3, 4, 5) Thomas Britz, Sergey Fomin, Finite posets and Ferrers shapes, Advances in Mathematics 158, pp. 86-127 (2001), Arxiv math/9912126 (the arXiv version has less errors).

    EXAMPLES:

        sage: ps = [[16,12,14,-13],[[12,14],[14,-13],[12,16],[16,-13]]]
        sage: G, e = Poset(ps).frank_network()
        sage: G.edges()
        [((-1, 0), (0, -13), None), ((-1, 0), (0, 12), None), ((-1, 0), (0, 14), None), ((-1, 0), (0, 16), None), ((0, -13), (1, -13), None), ((0, -13), (1, 12), None), ((0, -13), (1, 14), None), ((0, -13), (1, 16), None), ((0, 12), (1, 12), None), ((0, 14), (1, 12), None), ((0, 14), (1, 14), None), ((0, 16), (1, 12), None), ((0, 16), (1, 16), None), ((1, -13), (2, 0), None), ((1, 12), (2, 0), None), ((1, 14), (2, 0), None), ((1, 16), (2, 0), None)]
        sage: e
        {((-1, 0), (0, -13)): 0,
         ((-1, 0), (0, 12)): 0,
         ((-1, 0), (0, 14)): 0,
         ((-1, 0), (0, 16)): 0,
         ((0, -13), (1, -13)): 1,
         ((0, -13), (1, 12)): 0,
         ((0, -13), (1, 14)): 0,
         ((0, -13), (1, 16)): 0,
         ((0, 12), (1, 12)): 1,
         ((0, 14), (1, 12)): 0,
         ((0, 14), (1, 14)): 1,
         ((0, 16), (1, 12)): 0,
         ((0, 16), (1, 16)): 1,
         ((1, -13), (2, 0)): 0,
         ((1, 12), (2, 0)): 0,
         ((1, 14), (2, 0)): 0,
         ((1, 16), (2, 0)): 0}
        sage: qs = [[1,2,3,4,5,6,7,8,9],[[1,3],[3,4],[5,7],[1,9],[2,3]]]
        sage: Poset(qs).frank_network()
        (Digraph on 20 vertices,
         {((-1, 0), (0, 1)): 0,
          ((-1, 0), (0, 2)): 0,
          ((-1, 0), (0, 3)): 0,
          ((-1, 0), (0, 4)): 0,
          ((-1, 0), (0, 5)): 0,
          ((-1, 0), (0, 6)): 0,
          ((-1, 0), (0, 7)): 0,
          ((-1, 0), (0, 8)): 0,
          ((-1, 0), (0, 9)): 0,
          ((0, 1), (1, 1)): 1,
          ((0, 2), (1, 2)): 1,
          ((0, 3), (1, 1)): 0,
          ((0, 3), (1, 2)): 0,
          ((0, 3), (1, 3)): 1,
          ((0, 4), (1, 1)): 0,
          ((0, 4), (1, 2)): 0,
          ((0, 4), (1, 3)): 0,
          ((0, 4), (1, 4)): 1,
          ((0, 5), (1, 5)): 1,
          ((0, 6), (1, 6)): 1,
          ((0, 7), (1, 5)): 0,
          ((0, 7), (1, 7)): 1,
          ((0, 8), (1, 8)): 1,
          ((0, 9), (1, 1)): 0,
          ((0, 9), (1, 9)): 1,
          ((1, 1), (2, 0)): 0,
          ((1, 2), (2, 0)): 0,
          ((1, 3), (2, 0)): 0,
          ((1, 4), (2, 0)): 0,
          ((1, 5), (2, 0)): 0,
          ((1, 6), (2, 0)): 0,
          ((1, 7), (2, 0)): 0,
          ((1, 8), (2, 0)): 0,
          ((1, 9), (2, 0)): 0})

    AUTHOR:

    - Darij Grinberg (2013-05-09)
  `ge`(x, y)

    Returns `True` if \(x\) is greater than or equal to \(y\) in the poset, and `False` otherwise.

    EXAMPLES:

        sage: Q = Poset({0:[2], 1:[2], 2:[3], 3:[4], 4:[]})
        sage: x,y,z = Q(0),Q(1),Q(4)
        sage: Q.is_gequal(x,y)
        False
        sage: Q.is_gequal(y,x)
        False
        sage: Q.is_gequal(x,z)
        False
        sage: Q.is_gequal(z,x)
        True
        sage: Q.is_gequal(z,y)
        True
        sage: Q.is_gequal(z,z)
        True

  `graphviz_string`(graph_string='graph', edge_string='--')

    Returns a representation in the DOT language, ready to render in graphviz.

    REFERENCES:

    - http://www.graphviz.org/doc/info/lang.html

    EXAMPLES:

        sage: P = Poset({'a':['b'],'b':['d'],'c':['d'],'d':['f'],'e':['f'],'f':[]})
        sage: print P.graphviz_string()
        graph {
        "f";"d";"b";"a";"c";"e";
        "f"--"e";"d"--"c";"b"--"a";"d"--"b";"f"--"d";
        }

  `greene_shape`()

    Return the Greene-Kleitman partition of `self`.

    The Greene-Kleitman partition of a finite poset \(P\) is the partition \((c_1 - c_0, c_2 - c_1, c_3 - c_2, \ldots)\), where \(c_k\) is the maximum cardinality of a union of \(k\) chains of \(P\). Equivalently, this is the conjugate of the partition \((a_1 - a_0, a_2 - a_1, a_3 - a_2, \ldots)\), where \(a_k\) is the maximum cardinality of a union of \(k\) antichains of \(P\).

    See many sources, e. g., [BF1999], for proofs of this equivalence.

    EXAMPLES:

        sage: P = Poset([[3,2,1],[[3,1],[2,1]]])
        sage: P.greene_shape()
        [2, 1]
        sage: P = Poset([[1,2,3,4],[[1,4],[2,4],[4,3]]])
        sage: P.greene_shape()
        [3, 1]
        sage: P = Poset([[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22],[[1,4],[2,4],[4,3]]])
        sage: P.greene_shape()
        [3, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]
        sage: P = Poset([[],[]])
        sage: P.greene_shape()
        []

    AUTHOR:

    - Darij Grinberg (2013-05-09)
  `gt`(x, y)

    Returns `True` if \(x\) is greater than but not equal to \(y\) in the poset, and `False` otherwise.

    EXAMPLES:

        sage: Q = Poset({0:[2], 1:[2], 2:[3], 3:[4], 4:[]})
        sage: x,y,z = Q(0),Q(1),Q(4)
        sage: Q.is_greater_than(x,y)
        False
        sage: Q.is_greater_than(y,x)
        False
        sage: Q.is_greater_than(x,z)
        False
        sage: Q.is_greater_than(z,x)
        True
        sage: Q.is_greater_than(z,y)
        True
        sage: Q.is_greater_than(z,z)
        False

  `h_polynomial`()

    Return the \(h\)-polynomial of a bounded poset `self`.

    This is the \(h\)-polynomial of the order complex of the poset minus its bounds.

    This is related to the \(f\)-polynomial by a simple change of variables:

    \[h(q) = (1-q)^{\deg f} f \left( \frac{q}{1-q} \right),\]

    where \(f\) and \(h\) denote the \(f\)-polynomial and the \(h\)-polynomial, respectively.

    See Wikipedia article h-vector.

    See also

    `is_bounded()`, `f_polynomial()`, `order_complex()`, `sage.homology.simplicial_complex.SimplicialComplex.h_vector()`

    Warning

    This is slightly different from the `hPolynomial` method in Macaulay2.

    EXAMPLES:

        sage: P = Posets.AntichainPoset(3).order_ideals_lattice()
        sage: P.h_polynomial()
        q^3 + 4*q^2 + q
        sage: P = Posets.DiamondPoset(5)
        sage: P.h_polynomial()
        2*q^2 + q
        sage: P = Poset({1: []})
        sage: P.h_polynomial()
        1

  `has_bottom`()

    Returns True if the poset has a unique minimal element.

    EXAMPLES:

        sage: P = Poset({0:[3],1:[3],2:[3],3:[4],4:[]})
        sage: P.has_bottom()
        False
        sage: Q = Poset({0:[1],1:[]})
        sage: Q.has_bottom()
        True

  `has_isomorphic_subposet`(other)

    Return `True` if the poset contains a subposet isomorphic to `other`.

    By subposet we mean that there exist a set `X` of elements such that `self.subposet(X)` is isomorphic to `other`.

    INPUT:

    - `other` – a finite poset

    EXAMPLES:

        sage: D = Poset({1:[2,3], 2:[4], 3:[4]})
        sage: T = Poset({1:[2,3], 2:[4,5], 3:[6,7]})
        sage: N5 = Posets.PentagonPoset()

        sage: N5.has_isomorphic_subposet(T)
        False
        sage: N5.has_isomorphic_subposet(D)
        True

        sage: len([P for P in Posets(5) if P.has_isomorphic_subposet(D)])
        11

  `has_top`()

    Returns True if the poset contains a unique maximal element, and False otherwise.

    EXAMPLES:

        sage: P = Poset({0:[3],1:[3],2:[3],3:[4,5],4:[],5:[]})
        sage: P.has_top()
        False
        sage: Q = Poset({0:[1],1:[]})
        sage: Q.has_top()
        True

  `hasse_diagram`(wrapped=True)

    Return the Hasse diagram of `self` as a Sage `DiGraph`. If `dot2tex` is installed, then this sets the Hasse diagram’s latex options to use the `dot2tex` formatting.

    Todo

    Should the vertices of the diagram have the poset as parent?

    EXAMPLES:

        sage: Q = Poset({5:[2,3], 1:[3,4], 2:[0], 3:[0], 4:[0]}, facade = False)
        sage: Q.hasse_diagram()
        Digraph on 6 vertices

        sage: P = Poset({'a':['b'],'b':['d'],'c':['d'],'d':['f'],'e':['f'],'f':[]}, facade = False)
        sage: H = P.hasse_diagram()
        sage: P.cover_relations()
        [[e, f], [c, d], [a, b], [b, d], [d, f]]
        sage: H.edges()
        [(a, b, None), (c, d, None), (b, d, None), (e, f, None), (d, f, None)]

        sage: P = Poset((divisors(15), attrcall("divides")), facade = False)
        sage: H = P.hasse_diagram()
        sage: H.vertices()
        [1, 5, 3, 15]
        sage: H.edges()
        [(1, 3, None), (1, 5, None), (5, 15, None), (3, 15, None)]
        sage: H.set_latex_options(format = "dot2tex")   # optional - dot2tex
        sage: view(H, tight_page=True) # optional - dot2tex

  `height`()

    Return the height (number of elements in the longest chain) of the poset.

    EXAMPLES:

        sage: P = Poset({0:[1],2:[3,4],4:[5,6]})
        sage: P.height()
        3
        sage: Posets.PentagonPoset().height()
        4
        sage: Poset({}).height()
        0

  `incomparability_graph`()

    Returns the incomparability graph of `self`.

    This is the complement of the comparability graph.

    See also

    `comparability_graph()`, `sage.graphs.comparability`

    EXAMPLES:

        sage: p = posets.ChainPoset(4)
        sage: p.incomparability_graph().size()
        0

        sage: p = posets.DiamondPoset(5)
        sage: g = p.incomparability_graph(); g
        Incomparability graph on 5 vertices
        sage: g.size()
        3

  `interval`(x, y)

    Return a list of the elements \(z\) such that \(x \le z \le y\).

    INPUT:

    - `x` – any element of the poset
    - `y` – any element of the poset

    EXAMPLES:

        sage: uc = [[1,3,2],[4],[4,5,6],[6],[7],[7],[7],[]]
        sage: dag = DiGraph(dict(zip(range(len(uc)),uc)))
        sage: P = Poset(dag)
        sage: I = set(map(P,[2,5,6,4,7]))
        sage: I == set(P.interval(2,7))
        True

        sage: dg = DiGraph({"a":["b","c"], "b":["d"], "c":["d"]})
        sage: P = Poset(dg, facade = False)
        sage: P.interval("a","d")
        [a, b, c, d]

  `interval_iterator`()

    Returns an iterator over all pairs \(x<y\) in `self`.

    EXAMPLES:

        sage: list(Posets.PentagonPoset().interval_iterator())
        [[0, 1], [0, 2], [0, 3], [0, 4], [1, 4], [2, 3], [2, 4], [3, 4]]

    See also

    `maximal_chains()`, `chains()`

  `is_EL_labelling`(f, return_raising_chains=False)

    Returns `True` if `f` is an EL labelling of `self`.

    A labelling \(f\) of the edges of the Hasse diagram of a poset is called an EL labelling (edge lexicographic labelling) if for any two elements \(u\) and \(v\) with \(u \leq v\),

    > - there is a unique \(f\)-raising chain from \(u\) to \(v\) in the Hasse diagram, and this chain is lexicographically first among all chains from \(u\) to \(v\).

    For more details, see [Bj1980].

    INPUT:

    - `f` – a function taking two elements `a` and `b` in `self` such that `b` covers `a` and returning elements in a totally ordered set.
    - `return_raising_chains` (optional; default:`False`) if `True`, returns the set of all raising chains in `self`, if possible.

    EXAMPLES:

    Let us consider a Boolean poset:

        sage: P = Poset([[(0,0),(0,1),(1,0),(1,1)],[[(0,0),(0,1)],[(0,0),(1,0)],[(0,1),(1,1)],[(1,0),(1,1)]]],facade=True)
        sage: label = lambda a,b: min( i for i in [0,1] if a[i] != b[i] )
        sage: P.is_EL_labelling(label)
        True
        sage: P.is_EL_labelling(label,return_raising_chains=True)
        {((0, 0), (0, 1)): [1],
         ((0, 0), (1, 0)): [0],
         ((0, 0), (1, 1)): [0, 1],
         ((0, 1), (1, 1)): [0],
         ((1, 0), (1, 1)): [1]}

    REFERENCES:

    [Bj1980] | Anders Björner, Shellable and Cohen-Macaulay partially ordered sets, Trans. Amer. Math. Soc. 260 (1980), 159-183, doi:10.1090/S0002-9947-1980-0570784-2

  `is_bounded`()

    Return `True` if the poset `self` is bounded, and `False` otherwise.

    We call a poset bounded if it contains a unique maximal element and a unique minimal element.

    EXAMPLES:

        sage: P = Poset({0:[3],1:[3],2:[3],3:[4,5],4:[],5:[]})
        sage: P.is_bounded()
        False
        sage: Q = Poset({0:[1],1:[]})
        sage: Q.is_bounded()
        True

  `is_chain`()

    Returns True if the poset is totally ordered, and False otherwise.

    EXAMPLES:

        sage: L = Poset({0:[1],1:[2],2:[3],3:[4]})
        sage: L.is_chain()
        True
        sage: V = Poset({0:[1,2]})
        sage: V.is_chain()
        False

  `is_chain_of_poset`(o, ordered=False)

    Return whether an iterable `o` is a chain of `self`, including a check for `o` being ordered from smallest to largest element if the keyword `ordered` is set to `True`.

    INPUT:

    - `o` – an iterable (e. g., list, set, or tuple) containing some elements of `self`
    - `ordered` – a Boolean (default: `False`) which decides whether the notion of a chain includes being ordered

    OUTPUT:

    If `ordered` is set to `False`, the truth value of the following assertion is returned: The subset of `self` formed by the elements of `o` is a chain in `self`.

    If `ordered` is set to `True`, the truth value of the following assertion is returned: Every element of the list `o` is (strictly!) smaller than its successor in `self`. (This makes no sense if `ordered` is a set.)

    EXAMPLES:

        sage: P = Poset((divisors(12), attrcall("divides")))
        sage: sorted(P.list())
        [1, 2, 3, 4, 6, 12]
        sage: P.is_chain_of_poset([2, 4])
        True
        sage: P.is_chain_of_poset([12, 6])
        True
        sage: P.is_chain_of_poset([12, 6], ordered=True)
        False
        sage: P.is_chain_of_poset([6, 12], ordered=True)
        True
        sage: P.is_chain_of_poset(())
        True
        sage: P.is_chain_of_poset((), ordered=True)
        True
        sage: P.is_chain_of_poset((3, 4, 12))
        False
        sage: P.is_chain_of_poset((3, 6, 12, 1))
        True
        sage: P.is_chain_of_poset((3, 6, 12, 1), ordered=True)
        False
        sage: P.is_chain_of_poset((3, 6, 12), ordered=True)
        True
        sage: P.is_chain_of_poset((1, 1, 3))
        True
        sage: P.is_chain_of_poset((1, 1, 3), ordered=True)
        False
        sage: P.is_chain_of_poset((1, 3), ordered=True)
        True
        sage: P.is_chain_of_poset((6, 1, 1, 3))
        True
        sage: P.is_chain_of_poset((2, 1, 1, 3))
        False

  `is_connected`()

    Return `True` if the poset is connected, and `False` otherwise.

    Poset is not connected if it can be divided to disjoint parts \(S_1\) and \(S_2\) so that every element of \(S_1\) is incomparable to every element of \(S_2\).

    EXAMPLES:

        sage: P=Poset({1:[2,3], 3:[4,5]})
        sage: P.is_connected()
        True
        sage: P=Poset({1:[2,3], 3:[4,5], 6:[7,8]})
        sage: P.is_connected()
        False

  `is_gequal`(x, y)

    Returns `True` if \(x\) is greater than or equal to \(y\) in the poset, and `False` otherwise.

    EXAMPLES:

        sage: Q = Poset({0:[2], 1:[2], 2:[3], 3:[4], 4:[]})
        sage: x,y,z = Q(0),Q(1),Q(4)
        sage: Q.is_gequal(x,y)
        False
        sage: Q.is_gequal(y,x)
        False
        sage: Q.is_gequal(x,z)
        False
        sage: Q.is_gequal(z,x)
        True
        sage: Q.is_gequal(z,y)
        True
        sage: Q.is_gequal(z,z)
        True

  `is_graded`()

    Returns whether this poset is graded.

    A poset is graded if all its maximal chains have the same length. There are various competing definitions for graded posets (see Wikipedia article Graded_poset). This definition is from section 3.1 of Richard Stanley’s Enumerative Combinatorics, Vol. 1 [EnumComb1].

    Note that every graded poset is ranked, but the converse is not true.

    See also

    `is_ranked()`

    EXAMPLES:

        sage: P = Poset([[1],[2],[3],[4],[]])
        sage: P.is_graded()
        True
        sage: Q = Poset([[1,5],[2,6],[3],[4],[],[6,3],[4]])
        sage: Q.is_graded()
        False
        sage: P = Poset( ([1,2,3,4],[[1,2],[2,4],[3,4]] ))
        sage: P.is_graded()
        False
        sage: P = Poset({1: [2, 3], 4: [5]})
        sage: P.is_graded()
        True
        sage: P = Poset({1: [2, 3], 3: [4]})
        sage: P.is_graded()
        False
        sage: P = Poset({1: [2, 3], 4: []})
        sage: P.is_graded()
        False
        sage: P = Posets.BooleanLattice(4)
        sage: P.is_graded()
        True
        sage: P = RootSystem(['D',4]).root_poset()
        sage: P.is_graded()
        True
        sage: P = Poset({})
        sage: P.is_graded()
        True

    TESTS:

    Here we test that the empty poset is graded:

        sage: Poset([[],[]]).is_graded()
        True

  `is_greater_than`(x, y)

    Returns `True` if \(x\) is greater than but not equal to \(y\) in the poset, and `False` otherwise.

    EXAMPLES:

        sage: Q = Poset({0:[2], 1:[2], 2:[3], 3:[4], 4:[]})
        sage: x,y,z = Q(0),Q(1),Q(4)
        sage: Q.is_greater_than(x,y)
        False
        sage: Q.is_greater_than(y,x)
        False
        sage: Q.is_greater_than(x,z)
        False
        sage: Q.is_greater_than(z,x)
        True
        sage: Q.is_greater_than(z,y)
        True
        sage: Q.is_greater_than(z,z)
        False

  `is_incomparable_chain_free`(m, n=None)

    Returns `True` if the poset is \((m+n)\)-free (that is, there is no pair of incomparable chains of lengths \(m\) and \(n\)), and `False` if not.

    If `m` is a tuple of pairs of chain lengths, returns `True` if the poset does not contain a pair of incomparable chains whose lengths comprise one of the chain pairs, and `False` if not. A poset is \((m+n)\)-free if it contains no induced subposet that is isomorphic to the poset consisting of two disjoint chains of lengths \(m\) and \(n\). See, for example, Exercise 15 in Chapter 3 of [EnumComb1].

    INPUT:

    - `m` - tuple of pairs of nonnegative integers
    - `m`, `n` - nonnegative integers

    EXAMPLES:

        sage: P = Poset({0:[2], 1:[2], 2:[3], 3:[4], 4:[]})
        sage: P.is_incomparable_chain_free(1, 1)
        False
        sage: P.is_incomparable_chain_free(2, 1)
        True

        sage: P = Poset(((0, 1, 2, 3, 4), ((0, 1), (1, 2), (0, 3), (4, 2))))
        sage: P.is_incomparable_chain_free(((3, 1), (2, 2)))
        True

        sage: P = Poset((("a", "b", "c", "d", "e", "f", "g", "h", "i", "j"), (("d", "a"), ("e", "a"), ("f", "a"), ("g", "a"), ("h", "b"), ("f", "b"), ("h", "c"), ("g", "c"), ("h", "d"), ("i", "d"), ("h", "e"), ("i", "e"), ("j", "f"), ("i", "f"), ("j", "g"), ("i", "g"), ("j", "h"))))
        sage: P.is_incomparable_chain_free(3, 1)
        True
        sage: P.is_incomparable_chain_free(2, 2)
        False

        sage: [len([p for p in Posets(n) if p.is_incomparable_chain_free(((3, 1), (2, 2)))]) for n in range(6)] # long time
        [1, 1, 2, 5, 14, 42]

    TESTS:

        sage: Q = Poset({0:[2], 1:[2], 2:[3], 3:[4], 4:[]})
        sage: Q.is_incomparable_chain_free(2, 20/10)
        True
        sage: Q.is_incomparable_chain_free(2, pi)
        Traceback (most recent call last):
        ...
        TypeError: 2 and pi must be integers.
        sage: Q.is_incomparable_chain_free(2, -1)
        Traceback (most recent call last):
        ...
        ValueError: 2 and -1 must be nonnegative integers.
        sage: P = Poset(((0, 1, 2, 3, 4), ((0, 1), (1, 2), (0, 3), (4, 2))))
        sage: P.is_incomparable_chain_free((3, 1))
        Traceback (most recent call last):
        ...
        TypeError: (3, 1) is not a tuple of tuples.
        sage: P.is_incomparable_chain_free([3, 1], [2, 2])
        Traceback (most recent call last):
        ...
        TypeError: [3, 1] and [2, 2] must be integers.
        sage: P.is_incomparable_chain_free([[3, 1], [2, 2]])
        True
        sage: P.is_incomparable_chain_free(([3, 1], [2, 2]))
        True
        sage: P.is_incomparable_chain_free([3, 1], 2)
        Traceback (most recent call last):
        ...
        TypeError: [3, 1] and 2 must be integers.
        sage: P.is_incomparable_chain_free(([3, 1], [2, 2, 2]))
        Traceback (most recent call last):
        ...
        ValueError: '([3, 1], [2, 2, 2])' is not a tuple of length-2 tuples.

    AUTHOR:

    - Eric Rowland (2013-05-28)

    REFERENCES:

    [EnumComb1] | (1, 2, 3, 4, 5) Richard P. Stanley, Enumerative Combinatorics, volume 1, Second Edition, Cambridge University Press (2011). http://math.mit.edu/~rstan/ec/ec1/

  `is_isomorphic`(other)

    Returns True if both posets are isomorphic.

    EXAMPLES:

        sage: P = Poset(([1,2,3],[[1,3],[2,3]]))
        sage: Q = Poset(([4,5,6],[[4,6],[5,6]]))
        sage: P.is_isomorphic( Q )
        True

  `is_join_semilattice`()

    Returns True is the poset has a join operation, and False otherwise.

    EXAMPLES:

        sage: P = Poset([[1,3,2],[4],[4,5,6],[6],[7],[7],[7],[]])
        sage: P.is_join_semilattice()
        True

        sage: P = Poset([[1,2],[3],[3],[]])
        sage: P.is_join_semilattice()
        True

        sage: P = Poset({0:[2,3],1:[2,3]})
        sage: P.is_join_semilattice()
        False

  `is_lequal`(x, y)

    Returns `True` if \(x\) is less than or equal to \(y\) in the poset, and `False` otherwise.

    EXAMPLES:

        sage: Q = Poset({0:[2], 1:[2], 2:[3], 3:[4], 4:[]})
        sage: x,y,z = Q(0),Q(1),Q(4)
        sage: Q.is_lequal(x,y)
        False
        sage: Q.is_lequal(y,x)
        False
        sage: Q.is_lequal(x,z)
        True
        sage: Q.is_lequal(y,z)
        True
        sage: Q.is_lequal(z,z)
        True

  `is_less_than`(x, y)

    Returns `True` if \(x\) is less than but not equal to \(y\) in the poset, and `False` otherwise.

    EXAMPLES:

        sage: Q = Poset({0:[2], 1:[2], 2:[3], 3:[4], 4:[]})
        sage: x,y,z = Q(0),Q(1),Q(4)
        sage: Q.is_less_than(x,y)
        False
        sage: Q.is_less_than(y,x)
        False
        sage: Q.is_less_than(x,z)
        True
        sage: Q.is_less_than(y,z)
        True
        sage: Q.is_less_than(z,z)
        False

  `is_linear_extension`(l)

    Returns whether `l` is a linear extension of `self`

    INPUT:

    - `l` – a list (or iterable) containing all of the elements of `self` exactly once

    See also

    `linear_extension()`, `linear_extensions()`

    EXAMPLES:

        sage: P = Poset((divisors(12), attrcall("divides")), facade=True, linear_extension=True)
        sage: P.list()
        [1, 2, 3, 4, 6, 12]
        sage: P.is_linear_extension([1, 2, 4, 3, 6, 12])
        True
        sage: P.is_linear_extension([1, 2, 4, 6, 3, 12])
        False

        sage: [p for p in Permutations(list(P)) if P.is_linear_extension(p)]
        [[1, 2, 3, 4, 6, 12],
         [1, 2, 3, 6, 4, 12],
         [1, 2, 4, 3, 6, 12],
         [1, 3, 2, 4, 6, 12],
         [1, 3, 2, 6, 4, 12]]
        sage: list(P.linear_extensions())
        [[1, 2, 3, 4, 6, 12],
         [1, 2, 3, 6, 4, 12],
         [1, 2, 4, 3, 6, 12],
         [1, 3, 2, 4, 6, 12],
         [1, 3, 2, 6, 4, 12]]

    Note

    This is used and systematically tested in `LinearExtensionsOfPosets`

    TESTS:

    Check that trac ticket #15313 is fixed:

        sage: P = Poset((divisors(12), attrcall("divides")), facade=True, linear_extension=True)
        sage: P.is_linear_extension([1,2,4,3,6,12,1337])
        False
        sage: P.is_linear_extension([1,2,4,3,6,666,12,1337])
        False
        sage: P = Poset(DiGraph(5))
        sage: P.is_linear_extension(['David', 'McNeil', 'La', 'Lamentable', 'Aventure', 'de', 'Simon', 'Wiesenthal'])
        False

  `is_meet_semilattice`()

    Returns True if self has a meet operation, and False otherwise.

    EXAMPLES:

        sage: P = Poset([[1,3,2],[4],[4,5,6],[6],[7],[7],[7],[]], facade = False)
        sage: P.is_meet_semilattice()
        True

        sage: P = Poset([[1,2],[3],[3],[]])
        sage: P.is_meet_semilattice()
        True

        sage: P = Poset({0:[2,3],1:[2,3]})
        sage: P.is_meet_semilattice()
        False

  `is_parent_of`(x)

    Returns True if x is an element of the poset.

    TESTS:

        sage: from sage.combinat.posets.posets import FinitePoset
        sage: P5 = FinitePoset(DiGraph({(5,):[(4,1),(3,2)], \
                (4,1):[(3,1,1),(2,2,1)], \
                (3,2):[(3,1,1),(2,2,1)], \
                (3,1,1):[(2,1,1,1)], \
                (2,2,1):[(2,1,1,1)], \
                (2,1,1,1):[(1,1,1,1,1)], \
                (1,1,1,1,1):[]}))
        sage: x = P5.list()[3]
        sage: x in P5
        True

    For the sake of speed, an element with the right class and parent is assumed to be in this parent. This can possibly be counterfeited by feeding garbage to the constructor:

        sage: x = P5.element_class(P5, "a", 5)
        sage: x in P5
        True

  `is_ranked`()

    Returns whether this poset is ranked.

    A poset is ranked if it admits a rank function. For more information about the rank function, see `rank_function()`.

    See also

    `is_graded()`.

    EXAMPLES:

        sage: P = Poset([[1],[2],[3],[4],[]])
        sage: P.is_ranked()
        True
        sage: Q = Poset([[1,5],[2,6],[3],[4],[],[6,3],[4]])
        sage: Q.is_ranked()
        False
        sage: P = Poset( ([1,2,3,4],[[1,2],[2,4],[3,4]] ))
        sage: P.is_ranked()
        True

  `is_slender`()

    Return whether the poset `self` is slender or not.

    It is assumed for this method that `self` is a finite graded poset. A finite poset \(P\) is called slender if every rank 2 interval contains three or four elements. See [Stan2009].

    EXAMPLES:

        sage: P = Poset(([1,2,3,4],[[1,2],[1,3],[2,4],[3,4]]), facade = True)
        sage: P.is_slender()
        True
        sage: P = Poset(([1,2,3,4,5],[[1,2],[1,3],[1,4],[2,5],[3,5],[4,5]]), facade = True)
        sage: P.is_slender()
        False

        sage: W = WeylGroup(['A',2])
        sage: G = W.bruhat_poset()
        sage: G.is_slender()
        True
        sage: W = WeylGroup(['A',3])
        sage: G = W.bruhat_poset()
        sage: G.is_slender()
        True

  `isomorphic_subposets`(other)

    Return a list of subposets of \(self\) isomorphic to \(other\).

    By subposet we mean `self.subposet(X)` which is isomorphic to `other` and where `X` is a subset of elements of `self`.

    INPUT:

    - `other` – a finite poset

    EXAMPLES:

        sage: C2=Poset({0:[1]})
        sage: C3=Poset({'a':['b'], 'b':['c']})
        sage: for x in C3.isomorphic_subposets(C2): print x.cover_relations()
        [['b', 'c']]
        [['a', 'c']]
        [['a', 'b']]
        sage: D = Poset({1:[2,3], 2:[4], 3:[4]})
        sage: N5 = Posets.PentagonPoset()
        sage: len(N5.isomorphic_subposets(D))
        2

    Note

    If this function takes too much time, try using `isomorphic_subposets_iterator()`.

  `isomorphic_subposets_iterator`(other)

    Return an iterator over the subposets of \(self\) isomorphic to \(other\).

    By subposet we mean `self.subposet(X)` which is isomorphic to `other` and where `X` is a subset of elements of `self`.

    INPUT:

    - `other` – a finite poset

    EXAMPLES:

        sage: D = Poset({1:[2,3], 2:[4], 3:[4]})
        sage: N5 = Posets.PentagonPoset()
        sage: for P in N5.isomorphic_subposets_iterator(D):
        ....:     print P.cover_relations()
        [[0, 1], [0, 2], [1, 4], [2, 4]]
        [[0, 1], [0, 3], [1, 4], [3, 4]]
        [[0, 1], [0, 2], [1, 4], [2, 4]]
        [[0, 1], [0, 3], [1, 4], [3, 4]]

    Warning

    This function will return same subposet as many times as there are automorphism on it. This is due to `subgraph_search_iterator()` returning labelled subgraphs. On the other hand, this function does not eat memory like `isomorphic_subposets()` does.

  `join_matrix`()

    Deprecated as a function of posets, moved to lattices.

    Convert a poset \(P\) to join-semilattice and use it like `JoinSemilattice(P).join_matrix()`.

  `le`(x, y)

    Returns `True` if \(x\) is less than or equal to \(y\) in the poset, and `False` otherwise.

    EXAMPLES:

        sage: Q = Poset({0:[2], 1:[2], 2:[3], 3:[4], 4:[]})
        sage: x,y,z = Q(0),Q(1),Q(4)
        sage: Q.is_lequal(x,y)
        False
        sage: Q.is_lequal(y,x)
        False
        sage: Q.is_lequal(x,z)
        True
        sage: Q.is_lequal(y,z)
        True
        sage: Q.is_lequal(z,z)
        True

  `lequal_matrix`(ring=Integer Ring, sparse=False)

    Computes the matrix whose `(i,j)` entry is 1 if `self.linear_extension()[i] < self.linear_extension()[j]` and 0 otherwise.

    INPUT:

    - `ring` – the ring of coefficients (default: `ZZ`)
    - `sparse` – whether the returned matrix is sparse or not (default: `True`)

    EXAMPLES:

        sage: P = Poset([[1,3,2],[4],[4,5,6],[6],[7],[7],[7],[]], facade = False)
        sage: LEQM = P.lequal_matrix(); LEQM
        [1 1 1 1 1 1 1 1]
        [0 1 0 1 0 0 0 1]
        [0 0 1 1 1 0 1 1]
        [0 0 0 1 0 0 0 1]
        [0 0 0 0 1 0 0 1]
        [0 0 0 0 0 1 1 1]
        [0 0 0 0 0 0 1 1]
        [0 0 0 0 0 0 0 1]
        sage: LEQM[1,3]
        1
        sage: P.linear_extension()[1] < P.linear_extension()[3]
        True
        sage: LEQM[2,5]
        0
        sage: P.linear_extension()[2] < P.linear_extension()[5]
        False

    We now demonstrate the usage of the optional parameters:

        sage: P.lequal_matrix(ring=QQ, sparse=False).parent()
        Full MatrixSpace of 8 by 8 dense matrices over Rational Field

  `level_sets`()

    Return a list `l` such that `l[i]` is the set of minimal elements of the poset obtained from `self` by removing the elements in `l[0], l[1], ..., l[i-1]`. (In particular, `l[0]` is the set of minimal elements of `self`.)

    EXAMPLES:

        sage: P = Poset({0:[1,2],1:[3],2:[3],3:[]})
        sage: [len(x) for x in P.level_sets()]
        [1, 2, 1]

        sage: Q = Poset({0:[1,2], 1:[3], 2:[4], 3:[4]})
        sage: [len(x) for x in Q.level_sets()]
        [1, 2, 1, 1]

  `linear_extension`(linear_extension=None, check=True)

    Return a linear extension of this poset.

    A linear extension of a finite poset \(P\) of size \(n\) is a total ordering \(\pi := \pi_0 \pi_1 \ldots \pi_{n-1}\) of its elements such that \(i<j\) whenever \(\pi_i < \pi_j\) in the poset \(P\).

    INPUT:

    - `linear_extension` – (default: `None`) a list of the elements of `self`
    - `check` – a boolean (default: True); whether to check that `linear_extension` is indeed a linear extension of `self`.

    See also

    `is_linear_extension()`, `linear_extensions()`

    EXAMPLES:

        sage: P = Poset((divisors(15), attrcall("divides")), facade=True)

    Without optional argument, the default linear extension of the poset is returned, as a plain list:

        sage: P.linear_extension()
        [1, 3, 5, 15]

    Otherwise, a full-featured linear extension is constructed as an element of `P.linear_extensions()`:

        sage: l = P.linear_extension([1,5,3,15]); l
        [1, 5, 3, 15]
        sage: type(l)
        <class 'sage.combinat.posets.linear_extensions.LinearExtensionsOfPoset_with_category.element_class'>
        sage: l.parent()
        The set of all linear extensions of Finite poset containing 4 elements

    By default, the linear extension is checked for correctness:

        sage: l = P.linear_extension([1,3,15,5])
        Traceback (most recent call last):
        ...
        ValueError: [1, 3, 15, 5] is not a linear extension of Finite poset containing 4 elements

    This can be disabled (at your own risks!) with:

        sage: P.linear_extension([1,3,15,5], check=False)
        [1, 3, 15, 5]

    Todo

    - Is it acceptable to have those two features for a single method?
    - In particular, we miss a short idiom to get the default linear extension
  `linear_extensions`(facade=False)

    Returns the enumerated set of all the linear extensions of this poset

    INPUT:

    - `facade` – a boolean (default: `False`); whether to return the linear extensions as plain lists

      Warning

      The `facade` option is not yet fully functional:

          sage: P = Poset((divisors(12), attrcall("divides")), linear_extension=True)
          sage: L = P.linear_extensions(facade=True); L
          The set of all linear extensions of Finite poset containing 6 elements with distinguished linear extension
          sage: L([1, 2, 3, 4, 6, 12])
          Traceback (most recent call last):
          ...
          TypeError: Cannot convert list to sage.structure.element.Element

    See also

    `linear_extension()`, `is_linear_extension()`

    EXAMPLES:

        sage: P = Poset((divisors(12), attrcall("divides")), linear_extension=True)
        sage: P.list()
        [1, 2, 3, 4, 6, 12]
        sage: L = P.linear_extensions(); L
        The set of all linear extensions of Finite poset containing 6 elements with distinguished linear extension
        sage: l = L.an_element(); l
        [1, 2, 3, 4, 6, 12]
        sage: L.cardinality()
        5
        sage: L.list()
        [[1, 2, 3, 4, 6, 12],
         [1, 2, 3, 6, 4, 12],
         [1, 2, 4, 3, 6, 12],
         [1, 3, 2, 4, 6, 12],
         [1, 3, 2, 6, 4, 12]]

    Each element is aware that it is a linear extension of \(P\):

        sage: type(l.parent())
        <class 'sage.combinat.posets.linear_extensions.LinearExtensionsOfPoset_with_category'>

    With `facade=True`, the elements of `L` are plain lists instead:

        sage: L = P.linear_extensions(facade=True)
        sage: l = L.an_element()
        sage: type(l)
        <type 'list'>

    Warning

    In Sage <= 4.8, this function used to return a plain list of lists. To recover the previous functionality, please use:

        sage: L = list(P.linear_extensions(facade=True)); L
        [[1, 2, 3, 4, 6, 12],
         [1, 2, 3, 6, 4, 12],
         [1, 2, 4, 3, 6, 12],
         [1, 3, 2, 4, 6, 12],
         [1, 3, 2, 6, 4, 12]]
        sage: type(L[0])
        <type 'list'>

    TESTS:

        sage: D = Poset({ 0:[1,2], 1:[3], 2:[3,4] })
        sage: list(D.linear_extensions())
        [[0, 1, 2, 3, 4], [0, 1, 2, 4, 3], [0, 2, 1, 3, 4], [0, 2, 1, 4, 3], [0, 2, 4, 1, 3]]

  `list`()

    List the elements of the poset. This just returns the result of `linear_extension()`.

    EXAMPLES:

        sage: D = Poset({ 0:[1,2], 1:[3], 2:[3,4] }, facade = False)
        sage: D.list()
        [0, 1, 2, 3, 4]
        sage: type(D.list()[0])
        <class 'sage.combinat.posets.elements.FinitePoset_with_category.element_class'>

  `lower_covers`(y)

    Returns a list of lower covers of the element y. An lower cover of y is an element x such that y x is a cover relation.

    EXAMPLES:

        sage: Q = Poset({0:[2], 1:[2], 2:[3], 3:[4], 4:[]})
        sage: map(Q.lower_covers,Q.list())
        [[], [], [1, 0], [2], [3]]

  `lower_covers_iterator`(y)

    Returns an iterator for the lower covers of the element y. An lower cover of y is an element x such that y x is a cover relation.

    EXAMPLES:

        sage: Q = Poset({0:[2], 1:[2], 2:[3], 3:[4], 4:[]})
        sage: type(Q.lower_covers_iterator(0))
        <type 'generator'>

  `lt`(x, y)

    Returns `True` if \(x\) is less than but not equal to \(y\) in the poset, and `False` otherwise.

    EXAMPLES:

        sage: Q = Poset({0:[2], 1:[2], 2:[3], 3:[4], 4:[]})
        sage: x,y,z = Q(0),Q(1),Q(4)
        sage: Q.is_less_than(x,y)
        False
        sage: Q.is_less_than(y,x)
        False
        sage: Q.is_less_than(x,z)
        True
        sage: Q.is_less_than(y,z)
        True
        sage: Q.is_less_than(z,z)
        False

  `maximal_antichains`()

    Return all maximal antichains of the poset.

    EXAMPLES:

        sage: P=Poset({'a':['b', 'c'], 'b':['d','e']})
        sage: P.maximal_antichains()
        [['a'], ['b', 'c'], ['c', 'd', 'e']]

        sage: Posets.PentagonPoset().maximal_antichains()
        [[0], [1, 2], [1, 3], [4]]

    See also

    `maximal_chains()`, `antichains()`

  `maximal_chains`(partial=None)

    Return all maximal chains of this poset.

    Each chain is listed in increasing order.

    INPUT:

    - `partial` – list (optional); if present, find all maximal chains starting with the elements in partial

    Returns list of the maximal chains of this poset.

    This is used in constructing the order complex for the poset.

    EXAMPLES:

        sage: P = Posets.BooleanLattice(3)
        sage: P.maximal_chains()
        [[0, 1, 3, 7], [0, 1, 5, 7], [0, 2, 3, 7], [0, 2, 6, 7], [0, 4, 5, 7], [0, 4, 6, 7]]
        sage: P.maximal_chains(partial=[0,2])
        [[0, 2, 3, 7], [0, 2, 6, 7]]
        sage: Q = Posets.ChainPoset(6)
        sage: Q.maximal_chains()
        [[0, 1, 2, 3, 4, 5]]

    See also

    `maximal_antichains()`, `chains()`

  `maximal_elements`()

    Returns a list of the maximal elements of the poset.

    EXAMPLES:

        sage: P = Poset({0:[3],1:[3],2:[3],3:[4],4:[]})
        sage: P.maximal_elements()
        [4]

  `meet_matrix`()

    Deprecated as a function of posets, moved to lattices.

    Convert a poset \(P\) to meet-semilattice and use it like `MeetSemilattice(P).join_matrix()`.

  `minimal_elements`()

    Returns a list of the minimal elements of the poset.

    EXAMPLES:

        sage: P = Poset({0:[3],1:[3],2:[3],3:[4],4:[]})
        sage: P(0) in P.minimal_elements()
        True
        sage: P(1) in P.minimal_elements()
        True
        sage: P(2) in P.minimal_elements()
        True

  `mobius_function`(x, y)

    Returns the value of the Mobius function of the poset on the elements x and y.

    EXAMPLES:

        sage: P = Poset([[1,2,3],[4],[4],[4],[]])
        sage: P.mobius_function(P(0),P(4))
        2
        sage: sum([P.mobius_function(P(0),v) for v in P])
        0
        sage: sum([abs(P.mobius_function(P(0),v)) \
        ....:      for v in P])
        6
        sage: for u,v in P.cover_relations_iterator():
        ....:     if P.mobius_function(u,v) != -1:
        ....:         print "Bug in mobius_function!"

        sage: Q = Poset([[1,3,2],[4],[4,5,6],[6],[7],[7],[7],[]])
        sage: Q.mobius_function(Q(0),Q(7))
        0
        sage: Q.mobius_function(Q(0),Q(5))
        0
        sage: Q.mobius_function(Q(2),Q(7))
        2
        sage: Q.mobius_function(Q(3),Q(3))
        1
        sage: sum([Q.mobius_function(Q(0),v) for v in Q])
        0

  `mobius_function_matrix`(ring=Integer Ring, sparse=False)

    Returns a matrix whose `(i,j)` entry is the value of the Mobius function evaluated at `self.linear_extension()[i]` and `self.linear_extension()[j]`.

    INPUT:

    - `ring` – the ring of coefficients (default: `ZZ`)
    - `sparse` – whether the returned matrix is sparse or not (default: `True`)

    EXAMPLES:

        sage: P = Poset([[4,2,3],[],[1],[1],[1]])
        sage: x,y = (P.linear_extension()[0],P.linear_extension()[1])
        sage: P.mobius_function(x,y)
        -1
        sage: M = P.mobius_function_matrix(); M
        [ 1 -1 -1 -1  2]
        [ 0  1  0  0 -1]
        [ 0  0  1  0 -1]
        [ 0  0  0  1 -1]
        [ 0  0  0  0  1]
        sage: M[0,4]
        2
        sage: M[0,1]
        -1

    We now demonstrate the usage of the optional parameters:

        sage: P.mobius_function_matrix(ring=QQ, sparse=False).parent()
        Full MatrixSpace of 5 by 5 dense matrices over Rational Field

  `open_interval`(x, y)

    Return a list of the elements \(z\) such that \(x < z < y\).

    EXAMPLES:

        sage: uc = [[1,3,2],[4],[4,5,6],[6],[7],[7],[7],[]]
        sage: dag = DiGraph(dict(zip(range(len(uc)),uc)))
        sage: P = Poset(dag)
        sage: I = set(map(P,[5,6,4]))
        sage: I == set(P.open_interval(2,7))
        True

        sage: dg = DiGraph({"a":["b","c"], "b":["d"], "c":["d"]})
        sage: P = Poset(dg, facade = False)
        sage: P.open_interval("a","d")
        [b, c]

  `order_complex`(on_ints=False)

    Return the order complex associated to this poset.

    The order complex is the simplicial complex with vertices equal to the elements of the poset, and faces given by the chains.

    INPUT:

    - `on_ints` – a boolean (default: False)

    EXAMPLES:

        sage: P = Posets.BooleanLattice(3)
        sage: S = P.order_complex(); S
        Simplicial complex with vertex set (0, 1, 2, 3, 4, 5, 6, 7) and 6 facets
        sage: S.f_vector()
        [1, 8, 19, 18, 6]
        sage: S.homology()      # S is contractible
        {0: 0, 1: 0, 2: 0, 3: 0}
        sage: Q = P.subposet([1,2,3,4,5,6])
        sage: Q.order_complex().homology()    # a circle
        {0: 0, 1: Z}

        sage: P = Poset((divisors(15), attrcall("divides")), facade = True)
        sage: P.order_complex()
        Simplicial complex with vertex set (1, 3, 5, 15) and facets {(1, 3, 15), (1, 5, 15)}

    If `on_ints`, then the elements of the poset are labelled \(0,1,\dots\) in the chain complex:

        sage: P.order_complex(on_ints=True)
        Simplicial complex with vertex set (0, 1, 2, 3) and facets {(0, 2, 3), (0, 1, 3)}

  `order_filter`(elements)

    Returns the order filter generated by the elements of an iterable `elements`.

    \(I\) is an order filter if, for any \(x\) in \(I\) and \(y\) such that \(y \ge x\), then \(y\) is in \(I\).

    EXAMPLES:

        sage: B = Posets.BooleanLattice(4)
        sage: B.order_filter([3,8])
        [3, 7, 8, 9, 10, 11, 12, 13, 14, 15]

  `order_ideal`(elements)

    Returns the order ideal generated by the elements of an iterable `elements`.

    \(I\) is an order ideal if, for any \(x\) in \(I\) and \(y\) such that \(y \le x\), then \(y\) is in \(I\).

    EXAMPLES:

        sage: B = Posets.BooleanLattice(4)
        sage: B.order_ideal([7,10])
        [0, 1, 2, 3, 4, 5, 6, 7, 8, 10]
        sage: B.order_ideal(iter(range(4, 9)))
        [0, 1, 2, 3, 4, 5, 6, 7, 8]

  `order_polynomial`()

    Return the order polynomial of `self`.

    The order polynomial \(\Omega_P(q)\) of a poset \(P\) is defined as the unique polynomial \(S\) such that for each integer \(m \geq 1\), \(S(m)\) is the number of order-preserving maps from \(P\) to \(\{1,\ldots,m\}\).

    See sections 3.12 and 3.15 of [EnumComb1], and also [St1986].

    See also

    `order_polytope()`

    EXAMPLES:

        sage: P = Posets.AntichainPoset(3)
        sage: P.order_polynomial()
        q^3

        sage: P = Posets.ChainPoset(3)
        sage: f = P.order_polynomial(); f
        1/6*q^3 + 1/2*q^2 + 1/3*q
        sage: [f(i) for i in range(4)]
        [0, 1, 4, 10]

  `order_polytope`()

    Return the order polytope of the poset `self`.

    The order polytope of a finite poset \(P\) is defined as the subset of \(\RR^P\) consisting of all maps \(x : P \to \RR\) satisfying

    \[0 \leq x(p) \leq 1 \mbox{ for all } p \in P,\]

    and

    \[\begin{split}x(p) \leq x(q) \mbox{ for all } p, q \in P \mbox{ satisfying } p < q.\end{split}\]

    This polytope was defined and studied in [St1986].

    EXAMPLES:

        sage: P = posets.AntichainPoset(3)
        sage: Q = P.order_polytope();Q
        A 3-dimensional polyhedron in QQ^3 defined as the convex hull of 8 vertices
        sage: P = posets.PentagonPoset()
        sage: Q = P.order_polytope();Q
        A 5-dimensional polyhedron in QQ^5 defined as the convex hull of 8 vertices

        sage: P = Poset([[1,2,3],[[1,2],[1,3]]])
        sage: Q = P.order_polytope()
        sage: Q.contains((1,0,0))
        False
        sage: Q.contains((0,1,1))
        True

    REFERENCES:

    [St1986] | (1, 2, 3, 4) Richard Stanley. Two poset polytopes, Discrete Comput. Geom. (1986), doi:10.1007/BF02187680

  `p_partition_enumerator`(tup, R, check=False)

    Return a \(P\)-partition enumerator of `self`.

    Given a total order \(\prec\) on the elements of a finite poset \(P\) (the order of \(P\) and the total order \(\prec\) can be unrelated; in particular, the latter does not have to extend the former), a \(P\)-partition enumerator is the quasisymmetric function \(\sum_f \prod_{p \in P} x_{f(p)}\), where the first sum is taken over all \(P\)-partitions \(f\).

    A \(P\)-partition is a function \(f : P \to \{1,2,3,...\}\) satisfying the following properties for any two elements \(i\) and \(j\) of \(P\) satisfying \(i <_P j\):

    - if \(i \prec j\) then \(f(i) \leq f(j)\),
    - if \(j \prec i\) then \(f(i) < f(j)\).

    INPUT:

    - `tup` – the tuple containing all elements of \(P\) (each of them exactly once), in the order dictated by the total order \(\prec\)
    - `R` – a commutative ring

    OUTPUT:

    The \(P\)-partition enumerator of `self` according to `tup` in the algebra \(QSym\) of quasisymmetric functions over the base ring \(R\).

    EXAMPLES:

        sage: P = Poset([[1,2,3,4],[[1,4],[2,4],[4,3]]])
        sage: FP = P.p_partition_enumerator((3,1,2,4), QQ, check=True); FP
        2*M[1, 1, 1, 1] + 2*M[1, 2, 1] + M[2, 1, 1] + M[3, 1]

        sage: expansion = FP.expand(5)
        sage: xs = expansion.parent().gens()
        sage: expansion == sum([xs[a]*xs[b]*xs[c]*xs[d] for a in range(5) for b in range(5) for c in range(5) for d in range(5) if a <= b and c <= b and b < d])
        True

        sage: P = Poset([[],[]])
        sage: FP = P.p_partition_enumerator((), QQ, check=True); FP
        M[]

  `plot`(label_elements=True, element_labels=None, vertex_size=300, vertex_colors=None, layout='acyclic', **kwds)

    Returns a Graphic object for the Hasse diagram of the poset.

    The poset is increasing from bottom to top.

    By default, the vertices are labelled.

    If the poset is ranked, the plot uses the rank function for the heights of the vertices.

    INPUT:

    - `label_elements` (default: `True`) - whether to display element labels
    - `element_labels` (default: `None`) - a dictionary of element labels

    EXAMPLES:

        sage: D = Poset({ 1:[2,3], 2:[4], 3:[4,5] })
        sage: D.plot(label_elements=False)
        Graphics object consisting of 6 graphics primitives
        sage: D.plot()
        Graphics object consisting of 11 graphics primitives
        sage: type(D.plot())
        <class 'sage.plot.graphics.Graphics'>
        sage: elm_labs = {1:'a', 2:'b', 3:'c', 4:'d', 5:'e'}
        sage: D.plot(element_labels=elm_labs)
        Graphics object consisting of 11 graphics primitives

    Plot of the empy poset:

        sage: P = Poset({})
        sage: P.plot()
        Graphics object consisting of 0 graphics primitives

    Plot of a ranked poset:

        sage: P = Poset(DiGraph('E@ACA@?'))
        sage: P.is_ranked()
        True
        sage: P.plot()
        Graphics object consisting of 12 graphics primitives

    TESTS:

    We check that `label_elements` and `element_labels` are honored:

        sage: def get_plot_labels(P): return sorted(t.string for t in P if isinstance(t, sage.plot.text.Text))
        sage: P1 = Poset({ 0:[1,2], 1:[3], 2:[3,4] })
        sage: P2 = Poset({ 0:[1,2], 1:[3], 2:[3,4] }, facade=True)
        sage: get_plot_labels(P1.plot(label_elements=False))
        []
        sage: get_plot_labels(P1.plot(label_elements=True))
        ['0', '1', '2', '3', '4']
        sage: element_labels = {0:'a', 1:'b', 2:'c', 3:'d', 4:'e'}
        sage: get_plot_labels(P1.plot(element_labels=element_labels))
        ['a', 'b', 'c', 'd', 'e']
        sage: get_plot_labels(P2.plot(element_labels=element_labels))
        ['a', 'b', 'c', 'd', 'e']

  `product`(other)

    Returns the cartesian product of `self` and `other`.

    EXAMPLES:

        sage: P = Posets.ChainPoset(3)
        sage: Q = Posets.ChainPoset(4)
        sage: PQ = P.product(Q) ; PQ
        Finite poset containing 12 elements
        sage: len(PQ.hasse_diagram().edges())
        17
        sage: Q.product(P).is_isomorphic(PQ)
        True

        sage: P = Posets.BooleanLattice(2)
        sage: Q = P.product(P)
        sage: Q.is_isomorphic(Posets.BooleanLattice(4))
        True

  `promotion`(i=1)

    Compute the (extended) promotion on the linear extension of the poset `self`.

    INPUT:

    - `i` – an integer between \(1\) and \(n\) (default: \(1\))

    OUTPUT:

    - an isomorphic poset, with the same default linear extension

    The extended promotion is defined on a poset `self` of size \(n\) by applying the promotion operator \(\tau_i \tau_{i+1} \cdots \tau_{n-1}\) to the default linear extension \(\pi\) of `self` (see `promotion()`), and relabeling `self` accordingly. For more details see [Stan2009].

    When the vertices of the poset `self` are labelled by \(\{1,2,\ldots,n\}\), the linear extension is the identity, and \(i=1\), the above algorithm corresponds to the promotion operator on posets defined by Schützenberger as follows. Remove \(1\) from `self` and replace it by the minimum \(j\) of all labels covering \(1\) in the poset. Then, remove \(j\) and replace it by the minimum of all labels covering \(j\), and so on. This process ends when a label is a local maximum. Place the label \(n+1\) at this vertex. Finally, decrease all labels by \(1\).

    EXAMPLES:

        sage: P = Poset(([1,2], [[1,2]]), linear_extension=True, facade=False)
        sage: P.promotion()
        Finite poset containing 2 elements with distinguished linear extension
        sage: P == P.promotion()
        True

        sage: P = Poset(([1,2,3,4,5,6,7], [[1,2],[1,4],[2,3],[2,5],[3,6],[4,7],[5,6]]))
        sage: P.list()
        [1, 2, 3, 5, 6, 4, 7]
        sage: Q = P.promotion(4); Q
        Finite poset containing 7 elements with distinguished linear extension
        sage: Q.cover_relations()
        [[1, 2], [1, 6], [2, 3], [2, 5], [3, 7], [5, 7], [6, 4]]

    Note that if one wants to obtain the promotion defined by Schützenberger’s algorithm directly on the poset, one needs to make sure the linear extension is the identity:

        sage: P = P.with_linear_extension([1,2,3,4,5,6,7])
        sage: P.list()
        [1, 2, 3, 4, 5, 6, 7]
        sage: Q = P.promotion(4); Q
        Finite poset containing 7 elements with distinguished linear extension
        sage: Q.cover_relations()
        [[1, 2], [1, 6], [2, 3], [2, 4], [3, 5], [4, 5], [6, 7]]
        sage: Q = P.promotion()
        sage: Q.cover_relations()
        [[1, 2], [1, 3], [2, 4], [2, 5], [3, 6], [4, 7], [5, 7]]

    Here is an example for a poset not labelled by \(\{1, 2, \ldots, n\}\):

        sage: P = Poset((divisors(30), attrcall("divides")), linear_extension=True)
        sage: P.list()
        [1, 2, 3, 5, 6, 10, 15, 30]
        sage: P.cover_relations()
        [[1, 2], [1, 3], [1, 5], [2, 6], [2, 10], [3, 6], [3, 15],
         [5, 10], [5, 15], [6, 30], [10, 30], [15, 30]]
        sage: Q = P.promotion(4); Q
        Finite poset containing 8 elements with distinguished linear extension
        sage: Q.cover_relations()
        [[1, 2], [1, 3], [1, 6], [2, 5], [2, 15], [3, 5], [3, 10],
         [5, 30], [6, 10], [6, 15], [10, 30], [15, 30]]

    See also

    - `linear_extension()`
    - `with_linear_extension()` and the `linear_extension` option of `Poset()`
    - `promotion()`
    - `evacuation()`

    AUTHOR:

    - Anne Schilling (2012-02-18)
  `random_subposet`(p)

    Return a random subposet that contains each element with probability `p`.

    EXAMPLES:

        sage: P = Posets.BooleanLattice(3)
        sage: set_random_seed(0)
        sage: Q = P.random_subposet(0.5)
        sage: Q.cover_relations()
        [[0, 2], [0, 5], [2, 3], [3, 7], [5, 7]]

  `rank`(element=None)

    Return the rank of an element `element` in the poset `self`, or the rank of the poset if `element` is `None`.

    (The rank of a poset is the length of the longest chain of elements of the poset.)

    EXAMPLES:

        sage: P = Poset([[1,3,2],[4],[4,5,6],[6],[7],[7],[7],[]], facade = False)
        sage: P.rank(5)
        2
        sage: P.rank()
        3
        sage: Q = Poset([[1,2],[3],[],[]])

        sage: P = Posets.SymmetricGroupBruhatOrderPoset(4)
        sage: [(v,P.rank(v)) for v in P]
        [('1234', 0),
         ('1243', 1),
        ...
         ('4312', 5),
         ('4321', 6)]

  `rank_function`()

    Return the (normalized) rank function of the poset, if it exists.

    A rank function of a poset \(P\) is a function \(r\) that maps elements of \(P\) to integers and satisfies: \(r(x) = r(y) + 1\) if \(x\) covers \(y\). The function \(r\) is normalized such that its minimum value on every connected component of the Hasse diagram of \(P\) is \(0\). This determines the function \(r\) uniquely (when it exists).

    OUTPUT:

    - a lambda function, if the poset admits a rank function
    - `None`, if the poset does not admit a rank function

    EXAMPLES:

        sage: P = Poset(([1,2,3,4],[[1,4],[2,3],[3,4]]), facade=True)
        sage: P.rank_function() is not None
        True
        sage: P = Poset(([1,2,3,4,5],[[1,2],[2,3],[3,4],[1,5],[5,4]]), facade=True)
        sage: P.rank_function() is not None
        False
        sage: P = Poset(([1,2,3,4,5,6,7,8],[[1,4],[2,3],[3,4],[5,7],[6,7]]), facade=True)
        sage: f = P.rank_function(); f is not None
        True
        sage: f(5)
        0
        sage: f(2)
        0

    TESTS:

        sage: P = Poset([[1,3,2],[4],[4,5,6],[6],[7],[7],[7],[]])
        sage: r = P.rank_function()
        sage: for u,v in P.cover_relations_iterator():
        ....:     if r(v) != r(u) + 1:
        ....:         print "Bug in rank_function!"

        sage: Q = Poset([[1,2],[4],[3],[4],[]])
        sage: Q.rank_function() is None
        True

  `relabel`(relabeling)

    Return a copy of this poset with its elements relabelled.

    INPUT:

    - `relabeling` – a function or dictionnary

      This function should map each (non-wrapped) element of `self` to some distinct object.

    EXAMPLES:

        sage: P = Poset((divisors(12), attrcall("divides")), linear_extension=True, facade = False)
        sage: P.list()
        [1, 2, 3, 4, 6, 12]
        sage: P.cover_relations()
        [[1, 2], [1, 3], [2, 4], [2, 6], [3, 6], [4, 12], [6, 12]]
        sage: Q = P.relabel(lambda x: 12/x)
        sage: Q.list()
        [12, 6, 4, 3, 2, 1]
        sage: Q.cover_relations()
        [[12, 6], [12, 4], [6, 3], [6, 2], [4, 2], [3, 1], [2, 1]]

    Here we relabel the elements of a poset by \(\{0,1,2, ...\}\), using a dictionary:

        sage: P = Poset((divisors(12), attrcall("divides")), linear_extension=True, facade=False)
        sage: relabeling = {c.element:i for (i,c) in enumerate(P)}; relabeling
        {1: 0, 2: 1, 3: 2, 4: 3, 6: 4, 12: 5}
        sage: Q = P.relabel(relabeling)
        sage: Q.list()
        [0, 1, 2, 3, 4, 5]
        sage: Q.cover_relations()
        [[0, 1], [0, 2], [1, 3], [1, 4], [2, 4], [3, 5], [4, 5]]

    Mind the `c.element`; this is because the relabeling is applied to the elements of the poset without the wrapping. Thanks to this convention, the same relabeling function can be used both for facade or non facade posets:

        sage: P = Poset((divisors(12), attrcall("divides")), facade = True, linear_extension=True)
        sage: P.list()
        [1, 2, 3, 4, 6, 12]
        sage: Q = P.relabel(lambda x: 12/x)
        sage: Q.list()
        [12, 6, 4, 3, 2, 1]
        sage: Q.cover_relations()
        [[12, 6], [12, 4], [6, 3], [6, 2], [4, 2], [3, 1], [2, 1]]

    Note

    As can be seen in the above examples, the default linear extension of `Q` is that of `P` after relabeling. In particular, `P` and `Q` share the same internal Hasse diagram.

    TESTS:

    The following checks that trac ticket #14019 has been fixed:

        sage: d = DiGraph({2:[1],3:[1]})
        sage: p1 = Poset(d)
        sage: p2 = p1.relabel({1:1,2:3,3:2})
        sage: p1.hasse_diagram() == p2.hasse_diagram()
        True
        sage: p1 == p2
        True

        sage: d = DiGraph({2:[1],3:[1]})
        sage: p1 = Poset(d)
        sage: p2 = p1.relabel({1:2,2:3,3:1})
        sage: p3 = p2.relabel({2:1,1:2,3:3})
        sage: p1.hasse_diagram() == p3.hasse_diagram()
        True
        sage: p1 == p3
        True

  `relations`()

    Returns a list of all relations of the poset.

    OUTPUT:

    A list of pairs (each pair is a list), where the first element of the pair is less than or equal to the second element.

    Pairs are produced in a rough sort of lexicographic order, where earlier elements are from lower levels of the poset.

    EXAMPLES:

        sage: Q = Poset({0:[2], 1:[2], 2:[3], 3:[4], 4:[]})
        sage: Q.relations()
        [[1, 1], [1, 2], [1, 3], [1, 4], [0, 0], [0, 2], [0, 3], [0, 4], [2, 2], [2, 3], [2, 4], [3, 3], [3, 4], [4, 4]]

    AUTHOR:

    - Rob Beezer (2011-05-04)
  `relations_iterator`()

    Returns an iterator for all the relations of the poset.

    OUTPUT:

    A generator that produces pairs (each pair is a list), where the first element of the pair is less than or equal to the second element.

    Pairs are produced in a rough sort of lexicographic order, where earlier elements are from lower levels of the poset.

    EXAMPLES:

        sage: Q = Poset({0:[2], 1:[2], 2:[3], 3:[4], 4:[]})
        sage: type(Q.relations_iterator())
        <type 'generator'>
        sage: [z for z in Q.relations_iterator()]
        [[1, 1], [1, 2], [1, 3], [1, 4], [0, 0], [0, 2], [0, 3], [0, 4], [2, 2], [2, 3], [2, 4], [3, 3], [3, 4], [4, 4]]

    AUTHOR:

    - Rob Beezer (2011-05-04)
  `show`(label_elements=True, element_labels=None, vertex_size=300, vertex_colors=None, layout='acyclic', **kwds)

    Shows the Graphics object corresponding the Hasse diagram of the poset. Optionally, it is labelled.

    INPUT:

    - `label_elements` - whether to display element labels
    - `element_labels` - a dictionary of element labels

    EXAMPLES:

        sage: D = Poset({ 0:[1,2], 1:[3], 2:[3,4] })
        sage: D.plot(label_elements=False)
        Graphics object consisting of 6 graphics primitives
        sage: D.show()
        sage: elm_labs = {0:'a', 1:'b', 2:'c', 3:'d', 4:'e'}
        sage: D.show(element_labels=elm_labs)

  `subposet`(elements)

    Return the poset containing elements with partial order induced by that of `self`.

    EXAMPLES:

        sage: P = Poset({"a":["c","d"], "b":["d","e"], "c":["f"], "d":["f"], "e":["f"]}, facade = False)
        sage: Q = P.subposet(["a","b","f"]); Q
        Finite poset containing 3 elements
        sage: Q.cover_relations()
        [[b, f], [a, f]]

    A subposet of a facade poset is again a facade poset:

        sage: P = Poset({"a":["c","d"], "b":["d","e"], "c":["f"], "d":["f"], "e":["f"]}, facade=True)
        sage: Q = P.subposet(["a","b","f"]); Q
        Finite poset containing 3 elements
        sage: Q.cover_relations()
        [['b', 'f'], ['a', 'f']]

    One may specified wrapped elements or not:

        sage: P = Poset({"a":["c","d"], "b":["d","e"], "c":["f"], "d":["f"], "e":["f"]}, facade = False)
        sage: Q = P.subposet([P("a"),P("b"),P("f")]); Q
        Finite poset containing 3 elements
        sage: Q.cover_relations()
        [[b, f], [a, f]]

        sage: B = posets.BooleanLattice(2)
        sage: above = B.principal_order_filter(0)
        sage: Q = B.subposet(above)
        sage: above_new = Q.principal_order_filter(Q.list()[0])
        sage: Q.subposet(above_new)
        Finite poset containing 4 elements

    TESTS:

        sage: P.subposet(("a","b","f"))
        Finite poset containing 3 elements
        sage: P.subposet(["a","b","x"])
        Traceback (most recent call last):
        ...
        ValueError: <type 'str'> is not an element of this poset
        sage: P.subposet(3)
        Traceback (most recent call last):
        ...
        TypeError: 'sage.rings.integer.Integer' object is not iterable

  `to_graph`()

    Return the graph of `self` corresponding to forgetting the poset structure.

    EXAMPLES:

        sage: P = Poset({0:[1,2],1:[3],2:[3],3:[]})
        sage: G = P.to_graph(); G
        Graph on 4 vertices
        sage: S = Poset()
        sage: H = S.to_graph(); H
        Graph on 0 vertices

    Check that it is hashable and coincides with the Hasse diagram as a graph:

        sage: hash(G) == hash(G)
        True
        sage: G == Graph(P.hasse_diagram())
        True

  `top`()

    Returns the top element of the poset, if it exists.

    EXAMPLES:

        sage: P = Poset({0:[3],1:[3],2:[3],3:[4,5],4:[],5:[]})
        sage: P.top() is None
        True
        sage: Q = Poset({0:[1],1:[]})
        sage: Q.top()
        1

    TESTS:

        sage: R = Poset([[0],[]])
        sage: R.list()
        [0]
        sage: R.top() #Trac #10776
        0

  `unwrap`(element)

    Return the element `element` of the poset `self` in unwrapped form.

    INPUT:

    - `element` – an element of `self`

    EXAMPLES:

        sage: P = Poset((divisors(15), attrcall("divides")), facade = False)
        sage: x = P.an_element(); x
        1
        sage: x.parent()
        Finite poset containing 4 elements
        sage: P.unwrap(x)
        1
        sage: P.unwrap(x).parent()
        Integer Ring

    For a non facade poset, this is equivalent to using the `.element` attribute:

        sage: P.unwrap(x) is x.element
        True

    For a facade poset, this does nothing:

        sage: P = Poset((divisors(15), attrcall("divides")), facade=True)
        sage: x = P.an_element()
        sage: P.unwrap(x) is x
        True

    This method is useful in code where we don’t know if `P` is a facade poset or not.

  `upper_covers`(y)

    Returns a list of upper covers of the element y. An upper cover of y is an element x such that y x is a cover relation.

    EXAMPLES:

        sage: Q = Poset({0:[2], 1:[2], 2:[3], 3:[4], 4:[]})
        sage: map(Q.upper_covers,Q.list())
        [[2], [2], [3], [4], []]

  `upper_covers_iterator`(y)

    Returns an iterator for the upper covers of the element y. An upper cover of y is an element x such that y x is a cover relation.

    EXAMPLES:

        sage: Q = Poset({0:[2], 1:[2], 2:[3], 3:[4], 4:[]})
        sage: type(Q.upper_covers_iterator(0))
        <type 'generator'>

  `width`()

    Return the width of the poset (the size of its longest antichain).

    It is computed through a matching in a bipartite graph. See Wikipedia article Dilworth’s_theorem for more information.

    See also

    `dilworth_decomposition()` – return a partition of the poset into the smallest number of chains.

    EXAMPLE:

        sage: p = posets.BooleanLattice(4)
        sage: p.width()
        6

  `with_linear_extension`(linear_extension)

    Return a copy of `self` with a different default linear extension.

    EXAMPLES:

        sage: P = Poset((divisors(12), attrcall("divides")), linear_extension=True)
        sage: P.cover_relations()
        [[1, 2], [1, 3], [2, 4], [2, 6], [3, 6], [4, 12], [6, 12]]
        sage: list(P)
        [1, 2, 3, 4, 6, 12]
        sage: Q = P.with_linear_extension([1,3,2,6,4,12])
        sage: list(Q)
        [1, 3, 2, 6, 4, 12]
        sage: Q.cover_relations()
        [[1, 3], [1, 2], [3, 6], [2, 6], [2, 4], [6, 12], [4, 12]]

    TESTS:

    We check that we can pass in a list of elements of `P` instead:

        sage: Q = P.with_linear_extension(map(P, [1,3,2,6,4,12]))
        sage: list(Q)
        [1, 3, 2, 6, 4, 12]
        sage: Q.cover_relations()
        [[1, 3], [1, 2], [3, 6], [2, 6], [2, 4], [6, 12], [4, 12]]

    We check that this works for facade posets too:

        sage: P = Poset((divisors(12), attrcall("divides")), facade=True)
        sage: Q = P.with_linear_extension([1,3,2,6,4,12])
        sage: list(Q)
        [1, 3, 2, 6, 4, 12]
        sage: Q.cover_relations()
        [[1, 3], [1, 2], [3, 6], [2, 6], [2, 4], [6, 12], [4, 12]]
        sage: sorted(Q.cover_relations()) == sorted(P.cover_relations())
        True

    Note

    With the current implementation, this requires relabeling the internal `DiGraph` which is \(O(n+m)\), where \(n\) is the number of elements and \(m\) the number of cover relations.

  `zeta_polynomial`()

    Return the zeta polynomial of the poset `self`.

    The zeta polynomial of a poset is the unique polynomial \(Z(q)\) such that for every integer \(m > 1\), \(Z(m)\) is the number of weakly increasing sequences \(x_1 \leq x_2 \leq \dots \leq x_{m-1}\) of elements of the poset.

    The polynomial \(Z(q)\) is integral-valued, but generally doesn’t have integer coefficients. It can be computed as

    \[Z(q) = \sum_{k \geq 1} \dbinom{q-2}{k-1} c_k,\]

    where \(c_k\) is the number of all chains of length \(k\) in the poset.

    For more information, see section 3.12 of [EnumComb1].

    In particular, \(Z(2)\) is the number of vertices and \(Z(3)\) is the number of intervals.

    EXAMPLES:

        sage: Posets.ChainPoset(2).zeta_polynomial()
        q
        sage: Posets.ChainPoset(3).zeta_polynomial()
        1/2*q^2 + 1/2*q
        sage: P = posets.PentagonPoset()
        sage: P.zeta_polynomial()
        1/6*q^3 + q^2 - 1/6*q
        sage: P = Posets.DiamondPoset(5)
        sage: P.zeta_polynomial()
        3/2*q^2 - 1/2*q

    TESTS:

    Checking the simplest cases:

        sage: Poset({}).zeta_polynomial()
        0
        sage: Poset({1: []}).zeta_polynomial()
        1
        sage: Poset({1: [], 2: []}).zeta_polynomial()
        2

class `sage.combinat.posets.posets.``FinitePosets_n`(n)

  Bases: `sage.structure.unique_representation.UniqueRepresentation`, `sage.structure.parent.Parent`

  The finite enumerated set of all posets on \(n\) vertices, up to an isomorphism.

  EXAMPLES:

      sage: P = Posets(3)
      sage: P.cardinality()
      5
      sage: for p in P: print p.cover_relations()
      []
      [[1, 2]]
      [[0, 1], [0, 2]]
      [[0, 1], [1, 2]]
      [[1, 2], [0, 2]]

  `cardinality`(from_iterator=False)

    Return the cardinality of this object.

    Note

    By default, this returns pre-computed values obtained from the On-Line Encyclopedia of Integer Sequences (OEIS sequence A000112). To override this, pass the argument `from_iterator=True`.

    EXAMPLES:

        sage: P = Posets(3)
        sage: P.cardinality()
        5
        sage: P.cardinality(from_iterator=True)
        5

`sage.combinat.posets.posets.``Poset`(data=None, element_labels=None, cover_relations=False, linear_extension=False, category=None, facade=None, key=None)

  Construct a finite poset from various forms of input data.

  INPUT:

  - `data` – different input are accepted by this constructor:

    1. A two-element list or tuple `(E, R)`, where `E` is a collection of elements of the poset and `R` is a collection of relations `x <= y`, each represented as a two-element lists/tuples/iterables such as `[x, y]`. The poset is then the transitive closure of the provided relations. If `cover_relations=True`, then `R` is assumed to contain exactly the cover relations of the poset. If `E` is empty, then `E` is taken to be the set of elements appearing in the relations `R`.

    2. A two-element list or tuple `(E, f)`, where `E` is the set of elements of the poset and `f` is a function such that, for any pair `x, y` of elements of `E`, `f(x, y)` returns whether `x <= y`. If `cover_relations=True`, then `f(x,y)` should return whether `x` is covered by `y`.

    3. A dictionary, list or tuple of upper covers: `data[x]` is a list of the elements that cover the element \(x\) in the poset.

       Warning

       If data is a list or tuple of length \(2\), then it is handled by the above case..

    4. An acyclic, loop-free and multi-edge free `DiGraph`. If `cover_relations` is `True`, then the edges of the digraph are assumed to correspond to the cover relations of the poset. Otherwise, the cover relations are computed.

    5. A previously constructed poset (the poset itself is returned).

  - `element_labels` – (default: `None`); an optional list or dictionary of objects that label the poset elements.

  - `cover_relations` – a boolean (default: `False`); whether the data can be assumed to describe a directed acyclic graph whose arrows are cover relations; otherwise, the cover relations are first computed.

  - `linear_extension` – a boolean (default: `False`); whether to use the provided list of elements as default linear extension for the poset; otherwise a linear extension is computed. If the data is given as the pair `(E, f)`, then `E` is taken to be the linear extension.

  - `facade` – a boolean or `None` (default); whether the `Poset()`‘s elements should be wrapped to make them aware of the Poset they belong to.

    - If `facade = True`, the `Poset()`‘s elements are exactly those given as input.
    - If `facade = False`, the `Poset()`‘s elements will become `PosetElement` objects.
    - If `facade = None` (default) the expected behaviour is the behaviour of `facade = True`, unless the opposite can be deduced from the context (i.e. for instance if a `Poset()` is built from another `Poset()`, itself built with `facade = False`)

  OUTPUT:

  `FinitePoset` – an instance of the `FinitePoset`` class.

  If `category` is specified, then the poset is created in this category instead of `FinitePosets`.

  See also

  `Posets`, `Posets`, `FinitePosets`

  EXAMPLES:

  1. Elements and cover relations:

         sage: elms = [1,2,3,4,5,6,7]
         sage: rels = [[1,2],[3,4],[4,5],[2,5]]
         sage: Poset((elms, rels), cover_relations = True, facade = False)
         Finite poset containing 7 elements

     Elements and non-cover relations:

         sage: elms = [1,2,3,4]
         sage: rels = [[1,2],[1,3],[1,4],[2,3],[2,4],[3,4]]
         sage: P = Poset( [elms,rels] ,cover_relations=False); P
         Finite poset containing 4 elements
         sage: P.cover_relations()
         [[1, 2], [2, 3], [3, 4]]

  2. Elements and function: the standard permutations of [1, 2, 3, 4] with the Bruhat order:

         sage: elms = Permutations(4)
         sage: fcn = lambda p,q : p.bruhat_lequal(q)
         sage: Poset((elms, fcn))
         Finite poset containing 24 elements

     With a function that identifies the cover relations: the set partitions of \(\{1, 2, 3\}\) ordered by refinement:

         sage: elms = SetPartitions(3)
         sage: def fcn(A, B):
         ....:     if len(A) != len(B)+1:
         ....:         return False
         ....:     for a in A:
         ....:         if not any(set(a).issubset(b) for b in B):
         ....:             return False
         ....:     return True
         sage: Poset((elms, fcn), cover_relations=True)
         Finite poset containing 5 elements

  3. A dictionary of upper covers:

         sage: Poset({'a':['b','c'], 'b':['d'], 'c':['d'], 'd':[]})
         Finite poset containing 4 elements

     A list of upper covers:

         sage: Poset([[1,2],[4],[3],[4],[]])
         Finite poset containing 5 elements

     A list of upper covers and a dictionary of labels:

         sage: elm_labs = {0:"a",1:"b",2:"c",3:"d",4:"e"}
         sage: P = Poset([[1,2],[4],[3],[4],[]], elm_labs, facade = False)
         sage: P.list()
         [a, b, c, d, e]

     Warning

     The special case where the argument data is a list or tuple of length 2 is handled by the above cases. So you cannot use this method to input a 2-element poset.

  4. An acyclic DiGraph.

         sage: dag = DiGraph({0:[2,3], 1:[3,4], 2:[5], 3:[5], 4:[5]})
         sage: Poset(dag)
         Finite poset containing 6 elements

     Any directed acyclic graph without loops or multiple edges, as long as `cover_relations=False`:

         sage: dig = DiGraph({0:[2,3], 1:[3,4,5], 2:[5], 3:[5], 4:[5]})
         sage: dig.allows_multiple_edges()
         False
         sage: dig.allows_loops()
         False
         sage: dig.transitive_reduction() == dig
         False
         sage: Poset(dig, cover_relations=False)
         Finite poset containing 6 elements
         sage: Poset(dig, cover_relations=True)
         Traceback (most recent call last):
         ...
         ValueError: Hasse diagram is not transitively reduced.

  Default Linear extension

  Every poset \(P\) obtained with `Poset` comes equipped with a default linear extension, which is also used for enumerating its elements. By default, this linear extension is computed, and has no particular significance:

      sage: P = Poset((divisors(12), attrcall("divides")))
      sage: P.list()
      [1, 2, 4, 3, 6, 12]
      sage: P.linear_extension()
      [1, 2, 4, 3, 6, 12]

  You may enforce a specific linear extension using the `linear_extension` option:

      sage: P = Poset((divisors(12), attrcall("divides")), linear_extension=True)
      sage: P.list()
      [1, 2, 3, 4, 6, 12]
      sage: P.linear_extension()
      [1, 2, 3, 4, 6, 12]

  Depending on popular request, `Poset` might eventually get modified to always use the provided list of elements as default linear extension, when it is one.

  See also

  `FinitePoset.linear_extensions()`

  Facade posets

  When `facade = False`, the elements of a poset are wrapped so as to make them aware that they belong to that poset:

      sage: P = Poset(DiGraph({'d':['c','b'],'c':['a'],'b':['a']}), facade = False)
      sage: d,c,b,a = list(P)
      sage: a.parent() is P
      True

  This allows for comparing elements according to \(P\):

      sage: c < a
      True

  However, this may have surprising effects:

      sage: my_elements = ['a','b','c','d']
      sage: any(x in my_elements for x in P)
      False

  and can be annoying when one wants to manipulate the elements of the poset:

      sage: a + b
      Traceback (most recent call last):
      ...
      TypeError: unsupported operand type(s) for +: 'FinitePoset_with_category.element_class' and 'FinitePoset_with_category.element_class'
      sage: a.element + b.element
      'ab'

  By default, facade posets are constructed instead:

      sage: P = Poset(DiGraph({'d':['c','b'],'c':['a'],'b':['a']}))

  In this example, the elements of the poset remain plain strings:

      sage: d,c,b,a = list(P)
      sage: type(a)
      <type 'str'>

  Of course, those strings are not aware of \(P\). So to compare two such strings, one needs to query \(P\):

      sage: a < b
      True
      sage: P.lt(a,b)
      False

  which models the usual mathematical notation \(a <_P b\).

  Most operations seem to still work, but at this point there is no guarantee whatsoever:

      sage: P.list()
      ['d', 'c', 'b', 'a']
      sage: P.principal_order_ideal('a')
      ['d', 'c', 'b', 'a']
      sage: P.principal_order_ideal('b')
      ['d', 'b']
      sage: P.principal_order_ideal('d')
      ['d']
      sage: TestSuite(P).run()

  Warning

  `DiGraph` is used to construct the poset, and the vertices of a `DiGraph` are converted to plain Python `int`‘s if they are `Integer`‘s:

      sage: G = DiGraph({0:[2,3], 1:[3,4], 2:[5], 3:[5], 4:[5]})
      sage: type(G.vertices()[0])
      <type 'int'>

  This is worked around by systematically converting back the vertices of a poset to `Integer`‘s if they are `int`‘s:

      sage: P = Poset((divisors(15), attrcall("divides")), facade = False)
      sage: type(P.an_element().element)
      <type 'sage.rings.integer.Integer'>

      sage: P = Poset((divisors(15), attrcall("divides")), facade=True)
      sage: type(P.an_element())
      <type 'sage.rings.integer.Integer'>

  This may be abusive:

      sage: P = Poset((range(5), operator.le), facade = True)
      sage: P.an_element().parent()
      Integer Ring

  Unique representation

  As most parents, `Poset` have unique representation (see `UniqueRepresentation`). Namely if two posets are created from two equal data, then they are not only equal but actually identical:

      sage: data1 = [[1,2],[3],[3]]
      sage: data2 = [[1,2],[3],[3]]
      sage: P1 = Poset(data1)
      sage: P2 = Poset(data2)
      sage: P1 == P2
      True
      sage: P1 is P2
      True

  In situations where this behaviour is not desired, one can use the `key` option:

      sage: P1 = Poset(data1, key = "foo")
      sage: P2 = Poset(data2, key = "bar")
      sage: P1 is P2
      False
      sage: P1 == P2
      False

  `key` can be any hashable value and is passed down to `UniqueRepresentation`. It is otherwise ignored by the poset constructor.

  TESTS:

      sage: P = Poset([[1,2],[3],[3]])
      sage: type(hash(P))
      <type 'int'>

  Bad input:

      sage: Poset([1,2,3], lambda x,y : x<y)
      Traceback (most recent call last):
      ...
      ValueError: element_labels should be a dict or a list if different from None. (Did you intend data to be equal to a pair ?)

`sage.combinat.posets.posets.``is_poset`(dig)

  Tests whether a directed graph is acyclic and transitively reduced.

  EXAMPLES:

      sage: from sage.combinat.posets.posets import is_poset
      sage: dig = DiGraph({0:[2,3], 1:[3,4,5], 2:[5], 3:[5], 4:[5]})
      sage: is_poset(dig)
      False
      sage: is_poset(dig.transitive_reduction())
      True

### Navigation

- index
- modules |
- next |
- previous |
- Combinatorics »
- Posets »