# sage_setup: distribution = sagemath-combinat
r"""
Set partitions

This module defines a class for immutable partitioning of a set. For
mutable version see :func:`DisjointSet`.

AUTHORS:

- Mike Hansen
- MuPAD-Combinat developers (for algorithms and design inspiration).
- Travis Scrimshaw (2013-02-28): Removed ``CombinatorialClass`` and added
  entry point through :class:`SetPartition`.
- Martin Rubey (2017-10-10): Cleanup, add crossings and nestings, add
  random generation.
"""
# ****************************************************************************
#       Copyright (C) 2007 Mike Hansen <mhansen@gmail.com>,
#
#  Distributed under the terms of the GNU General Public License (GPL)
#
#    This code is distributed in the hope that it will be useful,
#    but WITHOUT ANY WARRANTY; without even the implied warranty of
#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
#    General Public License for more details.
#
#  The full text of the GPL is available at:
#
#                  https://www.gnu.org/licenses/
# ****************************************************************************
import itertools
from itertools import repeat
from sage.sets.set import Set, Set_generic

from sage.structure.parent import Parent
from sage.structure.unique_representation import UniqueRepresentation
from sage.structure.list_clone import ClonableArray
from sage.categories.infinite_enumerated_sets import InfiniteEnumeratedSets
from sage.categories.finite_enumerated_sets import FiniteEnumeratedSets
from sage.misc.inherit_comparison import InheritComparisonClasscallMetaclass
from sage.misc.lazy_import import lazy_import
from sage.rings.infinity import infinity
from sage.rings.integer import Integer
from sage.combinat.combinatorial_map import combinatorial_map
from sage.combinat.set_partition_iterator import (set_partition_iterator,
                                                  set_partition_iterator_blocks)
from sage.combinat.partition import Partition, Partitions
from sage.combinat.combinat import bell_number, stirling_number2 as stirling2
from sage.combinat.permutation import Permutation
from sage.arith.misc import factorial
from sage.misc.prandom import random, randint, sample
from sage.sets.disjoint_set import DisjointSet

lazy_import('sage.combinat.posets.hasse_diagram', 'HasseDiagram')
lazy_import('sage.probability.probability_distribution', 'GeneralDiscreteDistribution')


class AbstractSetPartition(ClonableArray,
        metaclass=InheritComparisonClasscallMetaclass):
    r"""
    Methods of set partitions which are independent of the base set
    """

    def _repr_(self):
        """
        Return a string representation of ``self``.

        EXAMPLES::

            sage: S = SetPartitions(4)
            sage: S([[1,3],[2,4]])
            {{1, 3}, {2, 4}}
        """
        try:
            s = [sorted(x) for x in self]
        except TypeError:
            s = [sorted(x, key=str) for x in self]
        return '{' + ', '.join('{' + repr(x)[1:-1] + '}' for x in s) + '}'

    def __hash__(self):
        """
        Return the hash of ``self``.

        The parent is not included as part of the hash.

        EXAMPLES::

            sage: P = SetPartitions(4)
            sage: A = SetPartition([[1], [2,3], [4]])
            sage: B = P([[1], [2,3], [4]])
            sage: hash(A) == hash(B)
            True
        """
        return sum(hash(x) for x in self)

    def __eq__(self, y):
        """
        Check equality of ``self`` and ``y``.

        The parent is not included as part of the equality check.

        EXAMPLES::

            sage: P = SetPartitions(4)
            sage: A = SetPartition([[1], [2,3], [4]])
            sage: B = P([[1], [2,3], [4]])
            sage: A == B
            True
            sage: C = P([[2, 3], [1], [4]])
            sage: A == C
            True
            sage: D = P([[1], [2, 4], [3]])
            sage: A == D
            False

        Note that this may give incorrect answers if the base set is not totally ordered::

            sage: a,b = frozenset([0,1]), frozenset([2,3])
            sage: p1 = SetPartition([[a], [b]])
            sage: p2 = SetPartition([[b], [a]])
            sage: p1 == p2
            False
        """
        if not isinstance(y, AbstractSetPartition):
            return False
        return list(self) == list(y)

    def __ne__(self, y):
        """
        Check lack of equality of ``self`` and ``y``.

        The parent is not included as part of the equality check.

        EXAMPLES::

            sage: P = SetPartitions(4)
            sage: A = SetPartition([[1], [2,3], [4]])
            sage: B = P([[1], [2,3], [4]])
            sage: A != B
            False
            sage: C = P([[2, 3], [1], [4]])
            sage: A != C
            False
            sage: D = P([[1], [2, 4], [3]])
            sage: A != D
            True

        Note that this may give incorrect answers if the base set is not totally ordered::

            sage: a,b = frozenset([0,1]), frozenset([2,3])
            sage: p1 = SetPartition([[a], [b]])
            sage: p2 = SetPartition([[b], [a]])
            sage: p1 != p2
            True
        """
        return not (self == y)

    def __lt__(self, y):
        """
        Check that ``self`` is less than ``y``.

        The ordering used is lexicographic, where:

        - a set partition is considered as the list of its parts
          sorted by increasing smallest element;

        - each part is regarded as a list of its elements, sorted
          in increasing order;

        - the parts themselves are compared lexicographically.

        EXAMPLES::

            sage: P = SetPartitions(4)
            sage: A = P([[1], [2,3], [4]])
            sage: B = SetPartition([[1,2,3], [4]])
            sage: A < B
            True
            sage: C = P([[1,2,4], [3]])
            sage: B < C
            True
            sage: B < B
            False
            sage: D = P([[1,4], [2], [3]])
            sage: E = P([[1,4], [2,3]])
            sage: D < E
            True
            sage: F = P([[1,2,4], [3]])
            sage: E < C
            False
            sage: A < E
            True
            sage: A < C
            True
        """
        if not isinstance(y, AbstractSetPartition):
            return False
        return [sorted(i) for i in self] < [sorted(i) for i in y]

    def __gt__(self, y):
        """
        Check that ``self`` is greater than ``y``.

        The ordering used is lexicographic, where:

        - a set partition is considered as the list of its parts
          sorted by increasing smallest element;

        - each part is regarded as a list of its elements, sorted
          in increasing order;

        - the parts themselves are compared lexicographically.

        EXAMPLES::

            sage: P = SetPartitions(4)
            sage: A = P([[1], [2,3], [4]])
            sage: B = SetPartition([[1,2,3], [4]])
            sage: B > A
            True
            sage: A > B
            False
        """
        if not isinstance(y, AbstractSetPartition):
            return False
        return [sorted(i) for i in self] > [sorted(i) for i in y]

    def __le__(self, y):
        """
        Check that ``self`` is less than or equals ``y``.

        The ordering used is lexicographic, where:

        - a set partition is considered as the list of its parts
          sorted by increasing smallest element;

        - each part is regarded as a list of its elements, sorted
          in increasing order;

        - the parts themselves are compared lexicographically.

        EXAMPLES::

            sage: P = SetPartitions(4)
            sage: A = P([[1], [2,3], [4]])
            sage: B = SetPartition([[1,2,3], [4]])
            sage: A <= B
            True
            sage: A <= A
            True
        """
        return self == y or self < y

    def __ge__(self, y):
        """
        Check that ``self`` is greater than or equals ``y``.

        The ordering used is lexicographic, where:

        - a set partition is considered as the list of its parts
          sorted by increasing smallest element;

        - each part is regarded as a list of its elements, sorted
          in increasing order;

        - the parts themselves are compared lexicographically.

        EXAMPLES::

            sage: P = SetPartitions(4)
            sage: A = P([[1], [2,3], [4]])
            sage: B = SetPartition([[1,2,3], [4]])
            sage: B >= A
            True
            sage: B >= B
            True
        """
        return self == y or self > y

    def __mul__(self, other):
        r"""
        The product of the set partitions ``self`` and ``other``.

        The product of two set partitions `B` and `C` is defined as the
        set partition whose parts are the nonempty intersections between
        each part of `B` and each part of `C`. This product is also
        the infimum of `B` and `C` in the classical set partition
        lattice (that is, the coarsest set partition which is finer than
        each of `B` and `C`). Consequently, ``inf`` acts as an alias for
        this method.

        .. SEEALSO::

            :meth:`sup`

        EXAMPLES::

            sage: x = SetPartition([ [1,2], [3,5,4] ])
            sage: y = SetPartition(( (3,1,2), (5,4) ))
            sage: x * y
            {{1, 2}, {3}, {4, 5}}

            sage: S = SetPartitions(4)
            sage: sp1 = S([[2,3,4], [1]])
            sage: sp2 = S([[1,3], [2,4]])
            sage: s = S([[2,4], [3], [1]])
            sage: sp1.inf(sp2) == s
            True

        TESTS:

        Here is a different implementation of the ``__mul__`` method
        (one that was formerly used for the ``inf`` method, before it
        was realized that the methods do the same thing)::

            sage: def mul2(s, t):
            ....:     temp = [ss.intersection(ts) for ss in s for ts in t]
            ....:     temp = filter(bool, temp)
            ....:     return s.__class__(s.parent(), temp)

        Let us check that this gives the same as ``__mul__`` on set
        partitions of `\{1, 2, 3, 4\}`::

            sage: all( all( mul2(s, t) == s * t for s in SetPartitions(4) )
            ....:      for t in SetPartitions(4) )
            True
        """
        new_composition = []
        for B in self:
            for C in other:
                BintC = B.intersection(C)
                if BintC:
                    new_composition.append(BintC)
        return SetPartition(new_composition)

    inf = __mul__

    def sup(self, t):
        """
        Return the supremum of ``self`` and ``t`` in the classical set
        partition lattice.

        The supremum of two set partitions `B` and `C` is obtained as the
        transitive closure of the relation which relates `i` to `j` if
        and only if `i` and `j` are in the same part in at least
        one of the set partitions `B` and `C`.

        .. SEEALSO::

            :meth:`__mul__`

        EXAMPLES::

            sage: S = SetPartitions(4)
            sage: sp1 = S([[2,3,4], [1]])
            sage: sp2 = S([[1,3], [2,4]])
            sage: s = S([[1,2,3,4]])
            sage: sp1.sup(sp2) == s
            True
        """
        res = list(self)
        for p in t:
            # find blocks in res which intersect p
            inters = [(i, q) for i, q in enumerate(res)
                      if any(a in q for a in p)]
            # remove these blocks from res
            for i, _ in reversed(inters):
                del res[i]
            # add the union
            res.append([e for _, q in inters for e in q])
        return self.parent()(res)

    def standard_form(self):
        r"""
        Return ``self`` as a list of lists.

        When the ground set is totally ordered, the elements of each
        block are listed in increasing order.

        This is not related to standard set partitions (which simply
        means set partitions of `[n] = \{ 1, 2, \ldots , n \}` for some
        integer `n`) or standardization (:meth:`standardization`).

        EXAMPLES::

            sage: [x.standard_form() for x in SetPartitions(4, [2,2])]                  # needs sage.graphs sage.rings.finite_rings
            [[[1, 2], [3, 4]], [[1, 4], [2, 3]], [[1, 3], [2, 4]]]

        TESTS::

            sage: SetPartition([(1, 9, 8), (2, 3, 4, 5, 6, 7)]).standard_form()
            [[1, 8, 9], [2, 3, 4, 5, 6, 7]]
        """
        return [sorted(i) for i in self]

    def base_set(self):
        """
        Return the base set of ``self``, which is the union of all parts
        of ``self``.

        EXAMPLES::

            sage: SetPartition([[1], [2,3], [4]]).base_set()
            {1, 2, 3, 4}
            sage: SetPartition([[1,2,3,4]]).base_set()
            {1, 2, 3, 4}
            sage: SetPartition([]).base_set()
            {}
        """
        return Set(e for p in self for e in p)

    def base_set_cardinality(self):
        """
        Return the cardinality of the base set of ``self``, which is the sum
        of the sizes of the parts of ``self``.

        This is also known as the *size* (sometimes the *weight*) of
        a set partition.

        EXAMPLES::

            sage: SetPartition([[1], [2,3], [4]]).base_set_cardinality()
            4
            sage: SetPartition([[1,2,3,4]]).base_set_cardinality()
            4
        """
        return sum(len(x) for x in self)

    def coarsenings(self):
        """
        Return a list of coarsenings of ``self``.

        .. SEEALSO::

            :meth:`refinements`

        EXAMPLES::

            sage: SetPartition([[1,3],[2,4]]).coarsenings()
            [{{1, 2, 3, 4}}, {{1, 3}, {2, 4}}]
            sage: SetPartition([[1],[2,4],[3]]).coarsenings()
            [{{1, 2, 3, 4}},
             {{1, 2, 4}, {3}},
             {{1, 3}, {2, 4}},
             {{1}, {2, 3, 4}},
             {{1}, {2, 4}, {3}}]
            sage: SetPartition([]).coarsenings()
            [{}]
        """
        SP = SetPartitions(len(self))

        def union(s):
            # Return the partition obtained by combining, for every
            # part of s, those parts of self which are indexed by
            # the elements of this part of s into a single part.
            ret = []
            for part in s:
                cur = []
                for i in part:
                    cur.extend(self[i - 1])  # -1 for indexing
                ret.append(cur)
            return ret
        return [self.parent()(union(s)) for s in SP]

    def max_block_size(self):
        r"""
        The maximum block size of the diagram.

        EXAMPLES::

            sage: # needs sage.modules
            sage: from sage.combinat.diagram_algebras import PartitionDiagram, PartitionDiagrams
            sage: pd = PartitionDiagram([[1,-3,-5],[2,4],[3,-1,-2],[5],[-4]])
            sage: pd.max_block_size()
            3
            sage: sorted(d.max_block_size() for d in PartitionDiagrams(2))
            [1, 2, 2, 2, 2, 2, 2, 2, 2, 2, 3, 3, 3, 3, 4]
            sage: sorted(sp.max_block_size() for sp in SetPartitions(3))
            [1, 2, 2, 2, 3]
        """
        return max(len(block) for block in self)

    def conjugate(self):
        r"""
        An involution exchanging singletons and circular adjacencies.

        This method implements the definition of the conjugate of
        a set partition defined in [Cal2005]_.

        INPUT:

        - ``self`` -- set partition of an ordered set

        OUTPUT: a set partition

        EXAMPLES::

            sage: SetPartition([[1,6,7],[2,8],[3,4,5]]).conjugate()
            {{1, 4, 7}, {2, 8}, {3}, {5}, {6}}
            sage: all(sp.conjugate().conjugate()==sp for sp in SetPartitions([1,3,5,7]))
            True
            sage: SetPartition([]).conjugate()
            {}
        """
        def next_one(a, support):
            return support[(support.index(a) + 1) % len(support)]

        def addback(S, terminals, rsupport):
            out = list(S)
            for a in terminals * 2:
                if a not in out and next_one(a, rsupport) in out:
                    out.append(a)
            return out

        def pre_conjugate(sp):
            if len(sp) <= 1:
                return SetPartition([[a] for S in sp for a in S])
            if sp.max_block_size() == 1:
                return SetPartition([sp.base_set()])
            support = sorted(a for S in sp for a in S)
            initials = [a for S in sp for a in S if next_one(a, support) in S]
            singletons = [a for S in sp for a in S if len(S) == 1]
            if not initials and not singletons:
                return sp
            rho = pre_conjugate(
                SetPartition([[a for a in S if a not in initials]
                for S in sp if len(S) > 1 and any(a not in initials for a in S)]))
            # add back initials as singletons and singletons as terminals
            return SetPartition([addback(S, singletons, support[::-1])
                for S in rho] + [[a] for a in initials])
        support = sorted(a for S in self for a in S)
        return SetPartition([[support[-support.index(a) - 1] for a in S]
            for S in pre_conjugate(self)])


class SetPartition(AbstractSetPartition,
                   metaclass=InheritComparisonClasscallMetaclass):
    r"""
    A partition of a set.

    A set partition `p` of a set `S` is a partition of `S` into subsets
    called parts and represented as a set of sets. By extension, a set
    partition of a nonnegative integer `n` is the set partition of the
    integers from 1 to `n`. The number of set partitions of `n` is called
    the `n`-th Bell number.

    There is a natural integer partition associated with a set partition,
    namely the nonincreasing sequence of sizes of all its parts.

    There is a classical lattice associated with all set partitions of
    `n`. The infimum of two set partitions is the set partition obtained
    by intersecting all the parts of both set partitions. The supremum
    is obtained by transitive closure of the relation `i` related to `j`
    if and only if they are in the same part in at least one of the set
    partitions.

    We will use terminology from partitions, in particular the *length* of
    a set partition `A = \{A_1, \ldots, A_k\}` is the number of parts of `A`
    and is denoted by `|A| := k`. The *size* of `A` is the cardinality of `S`.
    We will also sometimes use the notation `[n] := \{1, 2, \ldots, n\}`.

    EXAMPLES:

    There are 5 set partitions of the set `\{1,2,3\}`::

        sage: SetPartitions(3).cardinality()                                            # needs sage.libs.flint
        5

    Here is the list of them::

        sage: SetPartitions(3).list()                                                   # needs sage.graphs
        [{{1, 2, 3}}, {{1, 2}, {3}}, {{1, 3}, {2}}, {{1}, {2, 3}}, {{1}, {2}, {3}}]

    There are 6 set partitions of `\{1,2,3,4\}` whose underlying partition is
    `[2, 1, 1]`::

        sage: SetPartitions(4, [2,1,1]).list()                                          # needs sage.graphs sage.rings.finite_rings
        [{{1}, {2, 4}, {3}},
         {{1}, {2}, {3, 4}},
         {{1, 4}, {2}, {3}},
         {{1, 3}, {2}, {4}},
         {{1, 2}, {3}, {4}},
         {{1}, {2, 3}, {4}}]

    Since :issue:`14140`, we can create a set partition directly by
    :class:`SetPartition`, which creates the base set by taking the
    union of the parts passed in::

        sage: s = SetPartition([[1,3],[2,4]]); s
        {{1, 3}, {2, 4}}
        sage: s.parent()
        Set partitions
    """
    @staticmethod
    def __classcall_private__(cls, parts, check=True):
        """
        Create a set partition from ``parts`` with the appropriate parent.

        EXAMPLES::

            sage: s = SetPartition([[1,3],[2,4]]); s
            {{1, 3}, {2, 4}}
            sage: s.parent()
            Set partitions
        """
        P = SetPartitions()
        return P.element_class(P, parts, check=check)

    def __init__(self, parent, s, check=True):
        """
        Initialize ``self``.

        Internally, a set partition is stored as iterable of blocks,
        sorted by minimal element.

        EXAMPLES::

            sage: S = SetPartitions(4)
            sage: s = S([[1,3],[2,4]])
            sage: TestSuite(s).run()
            sage: SetPartition([])
            {}
        """
        self._latex_options = {}
        try:
            s = sorted(map(frozenset, s), key=min)
        except TypeError:
            s = sorted(map(frozenset, s), key=lambda b: min(str(b)))
        ClonableArray.__init__(self, parent, s, check=check)

    def check(self):
        """
        Check that we are a valid set partition.

        EXAMPLES::

            sage: S = SetPartitions(4)
            sage: s = S([[1, 3], [2, 4]])
            sage: s.check()

        TESTS::

            sage: s = S([[1, 2, 3]], check=False)
            sage: s.check()
            Traceback (most recent call last):
            ...
            ValueError: {{1, 2, 3}} is not an element of Set partitions of {1, 2, 3, 4}

            sage: s = S([1, 2, 3])
            Traceback (most recent call last):
            ...
            TypeError: 'sage.rings.integer.Integer' object is not iterable
        """
        if self not in self.parent():
            raise ValueError(f"{self} is not an element of {self.parent()}")

    def set_latex_options(self, **kwargs):
        r"""
        Set the latex options for use in the ``_latex_`` function.

        - ``tikz_scale`` -- (default: 1) scale for use with tikz package

        - ``plot`` -- (default: ``None``) ``None`` returns the set notation,
          ``linear`` returns a linear plot, ``cyclic`` returns a cyclic
          plot

        - ``color`` -- (default: ``'black'``) the arc colors

        - ``fill`` -- boolean (default: ``False``); if ``True`` then fills
          ``color``, else you can pass in a color to alter the fill color -
          *only works with cyclic plot*

        - ``show_labels`` -- boolean (default: ``True``); if ``True`` shows
          labels (*only works with plots*)

        - ``radius`` -- (default: ``'1cm'``) radius of circle for cyclic
          plot - *only works with cyclic plot*

        - ``angle`` -- (default: 0) angle for linear plot

        EXAMPLES::

            sage: SP = SetPartition([[1,6], [3,5,4]])
            sage: SP.set_latex_options(tikz_scale=2,plot='linear',fill=True,color='blue',angle=45)
            sage: SP.set_latex_options(plot='cyclic')
            sage: SP.latex_options()
            {'angle': 45,
             'color': 'blue',
             'fill': True,
             'plot': 'cyclic',
             'radius': '1cm',
             'show_labels': True,
             'tikz_scale': 2}
        """
        valid_args = ['tikz_scale', 'plot', 'color', 'fill', 'show_labels',
                      'radius', 'angle']

        for key in kwargs:
            if key not in valid_args:
                raise ValueError(f"unknown keyword argument: {key}")
            if key == 'plot':
                if not (kwargs['plot'] == 'cyclic'
                        or kwargs['plot'] == 'linear'
                        or kwargs['plot'] is None):
                    raise ValueError("plot must be None, 'cyclic', or 'linear'")

        self._latex_options.update(kwargs)

    def latex_options(self):
        r"""
        Return the latex options for use in the ``_latex_`` function as a
        dictionary. The default values are set using the global options.

        Options can be found in :meth:`set_latex_options`

        EXAMPLES::

            sage: SP = SetPartition([[1,6], [3,5,4]]); SP.latex_options()
            {'angle': 0,
             'color': 'black',
             'fill': False,
             'plot': None,
             'radius': '1cm',
             'show_labels': True,
             'tikz_scale': 1}
        """
        opts = self._latex_options.copy()
        if "tikz_scale" not in opts:
            opts["tikz_scale"] = 1
        if "plot" not in opts:
            opts["plot"] = None
        if "color" not in opts:
            opts['color'] = 'black'
        if "fill" not in opts:
            opts["fill"] = False
        if "show_labels" not in opts:
            opts['show_labels'] = True
        if "radius" not in opts:
            opts['radius'] = "1cm"
        if "angle" not in opts:
            opts['angle'] = 0
        return opts

    def _latex_(self):
        r"""
        Return a `\LaTeX` string representation of ``self``.

        EXAMPLES::

            sage: x = SetPartition([[1,2], [3,5,4]])
            sage: latex(x)
            \{\{1, 2\}, \{3, 4, 5\}\}

            sage: x.set_latex_options(plot='linear', angle=25, color='red')
            sage: latex(x)
            \begin{tikzpicture}[scale=1]
            \node[below=.05cm] at (0,0) {$1$};
            \node[draw,circle, inner sep=0pt, minimum width=4pt, fill=black] (0) at (0,0) {};
            \node[below=.05cm] at (1,0) {$2$};
            \node[draw,circle, inner sep=0pt, minimum width=4pt, fill=black] (1) at (1,0) {};
            \node[below=.05cm] at (2,0) {$3$};
            \node[draw,circle, inner sep=0pt, minimum width=4pt, fill=black] (2) at (2,0) {};
            \node[below=.05cm] at (3,0) {$4$};
            \node[draw,circle, inner sep=0pt, minimum width=4pt, fill=black] (3) at (3,0) {};
            \node[below=.05cm] at (4,0) {$5$};
            \node[draw,circle, inner sep=0pt, minimum width=4pt, fill=black] (4) at (4,0) {};
            \draw[color=red] (1) to [out=115,in=65] (0);
            \draw[color=red] (3) to [out=115,in=65] (2);
            \draw[color=red] (4) to [out=115,in=65] (3);
            \end{tikzpicture}

            sage: p = SetPartition([['a','c'],['b','d'],['e']])
            sage: p.set_latex_options(plot='cyclic', color='blue', fill=True, tikz_scale=2)
            sage: latex(p)
            \begin{tikzpicture}[scale=2]
            \draw (0,0) circle [radius=1cm];
            \node[label=90:a] (0) at (90:1cm) {};
            \node[label=18:b] (1) at (18:1cm) {};
            \node[label=-54:c] (2) at (-54:1cm) {};
            \node[label=-126:d] (3) at (-126:1cm) {};
            \node[label=-198:e] (4) at (-198:1cm) {};
            \draw[-,thick,color=blue,fill=blue,fill opacity=0.1] ...
            \draw[-,thick,color=blue,fill=blue,fill opacity=0.1] ...
            \draw[-,thick,color=blue,fill=blue,fill opacity=0.1] ...
            \fill[color=black] (0) circle (1.5pt);
            \fill[color=black] (1) circle (1.5pt);
            \fill[color=black] (2) circle (1.5pt);
            \fill[color=black] (3) circle (1.5pt);
            \fill[color=black] (4) circle (1.5pt);
            \end{tikzpicture}
        """
        latex_options = self.latex_options()
        if latex_options["plot"] is None:
            return repr(self).replace("{", r"\{").replace("}", r"\}")

        from sage.misc.latex import latex
        latex.add_package_to_preamble_if_available("tikz")
        res = "\\begin{{tikzpicture}}[scale={}]\n".format(latex_options['tikz_scale'])

        cardinality = self.base_set_cardinality()
        from sage.rings.integer_ring import ZZ
        if all(x in ZZ for x in self.base_set()):
            sort_key = ZZ
        else:
            sort_key = str
        base_set = sorted(self.base_set(), key=sort_key)
        color = latex_options['color']

        # If we want cyclic plots
        if latex_options['plot'] == 'cyclic':
            degrees = 360 // cardinality
            radius = latex_options['radius']

            res += "\\draw (0,0) circle [radius={}];\n".format(radius)

            # Add nodes
            for k, i in enumerate(base_set):
                location = (cardinality - k) * degrees - 270
                if latex_options['show_labels']:
                    res += "\\node[label={}:{}]".format(location, i)
                else:
                    res += "\\node"
                res += " ({}) at ({}:{}) {{}};\n".format(k, location, radius)

            # Setup partitions
            for partition in sorted(self, key=str):
                res += "\\draw[-,thick,color=" + color
                if latex_options['fill'] is not False:
                    if isinstance(latex_options['fill'], str):
                        res += ",fill=" + latex_options['fill']
                    else:
                        res += ",fill={},fill opacity=0.1".format(color)
                res += "] "
                res += " -- ".join("({}.center)".format(base_set.index(j))
                                   for j in sorted(partition, key=sort_key))
                res += " -- cycle;\n"

            # Draw the circles on top
            for k in range(len(base_set)):
                res += "\\fill[color=black] ({}) circle (1.5pt);\n".format(k)

        # If we want line plots
        elif latex_options['plot'] == 'linear':
            angle = latex_options['angle']
            # setup line
            for k, i in enumerate(base_set):
                if latex_options['show_labels']:
                    res += "\\node[below=.05cm] at ({},0) {{${}$}};\n".format(k, i)
                res += "\\node[draw,circle, inner sep=0pt, minimum width=4pt, fill=black] "
                res += "({k}) at ({k},0) {{}};\n".format(k=k)

            # setup arcs
            for partition in sorted(self, key=str):
                p = sorted(partition, key=sort_key)
                if len(p) <= 1:
                    continue
                for k in range(1, len(p)):
                    res += "\\draw[color={}] ({})".format(color, base_set.index(p[k]))
                    res += " to [out={},in={}] ".format(90 + angle, 90 - angle)
                    res += "({});\n".format(base_set.index(p[k - 1]))
        else:
            raise ValueError("plot must be None, 'cyclic', or 'linear'")

        res += "\\end{tikzpicture}"
        return res

    cardinality = ClonableArray.__len__

    size = AbstractSetPartition.base_set_cardinality

    def pipe(self, other):
        r"""
        Return the pipe of the set partitions ``self`` and ``other``.

        The pipe of two set partitions is defined as follows:

        For any integer `k` and any subset `I` of `\ZZ`, let `I + k`
        denote the subset of `\ZZ` obtained by adding `k` to every
        element of `k`.

        If `B` and `C` are set partitions of `[n]` and `[m]`,
        respectively, then the pipe of `B` and `C` is defined as the
        set partition

        .. MATH::

            \{ B_1, B_2, \ldots, B_b,
            C_1 + n, C_2 + n, \ldots, C_c + n \}

        of `[n+m]`, where `B = \{ B_1, B_2, \ldots, B_b \}` and
        `C = \{ C_1, C_2, \ldots, C_c \}`. This pipe is denoted by
        `B | C`.

        EXAMPLES::

            sage: SetPartition([[1,3],[2,4]]).pipe(SetPartition([[1,3],[2]]))
            {{1, 3}, {2, 4}, {5, 7}, {6}}
            sage: SetPartition([]).pipe(SetPartition([[1,2],[3,5],[4]]))
            {{1, 2}, {3, 5}, {4}}
            sage: SetPartition([[1,2],[3,5],[4]]).pipe(SetPartition([]))
            {{1, 2}, {3, 5}, {4}}
            sage: SetPartition([[1,2],[3]]).pipe(SetPartition([[1]]))
            {{1, 2}, {3}, {4}}
        """
        # Note: GIGO if self and other are not standard.
        parts = list(self)
        n = self.base_set_cardinality()
        for newpart in other:
            raised_newpart = Set(i + n for i in newpart)
            parts.append(raised_newpart)
        return SetPartition(parts)

    @combinatorial_map(name='shape')
    def shape(self):
        r"""
        Return the integer partition whose parts are the sizes of the sets
        in ``self``.

        EXAMPLES::

            sage: S = SetPartitions(5)
            sage: x = S([[1,2], [3,5,4]])
            sage: x.shape()
            [3, 2]
            sage: y = S([[2], [3,1], [5,4]])
            sage: y.shape()
            [2, 2, 1]
        """
        return Partition(sorted(map(len, self), reverse=True))

    # we define aliases for shape()
    shape_partition = shape
    to_partition = shape

    @combinatorial_map(name='to permutation')
    def to_permutation(self):
        r"""
        Convert a set partition of `\{1,...,n\}` to a permutation by considering
        the blocks of the partition as cycles.

        The cycles are such that the number of excedences is maximised, that is,
        each cycle is of the form `(a_1,a_2, ...,a_k)` with `a_1<a_2<...<a_k`.

        EXAMPLES::

            sage: s = SetPartition([[1,3],[2,4]])
            sage: s.to_permutation()
            [3, 4, 1, 2]
        """
        return Permutation(tuple(map(tuple, self.standard_form())))

    def to_restricted_growth_word(self, bijection='blocks'):
        r"""
        Convert a set partition of `\{1,...,n\}` to a word of length `n`
        with letters in the nonnegative integers such that each
        letter is at most 1 larger than all the letters before.

        INPUT:

        - ``bijection`` -- (default: ``blocks``) defines the map from
          set partitions to restricted growth functions.  These are
          currently:

          - ``blocks``: :meth:`to_restricted_growth_word_blocks`.

          - ``intertwining``: :meth:`to_restricted_growth_word_intertwining`.

        OUTPUT: a restricted growth word

        .. SEEALSO::

            :meth:`SetPartitions.from_restricted_growth_word`

        EXAMPLES::

            sage: P = SetPartition([[1,4],[2,8],[3,5,6,9],[7]])
            sage: P.to_restricted_growth_word()
            [0, 1, 2, 0, 2, 2, 3, 1, 2]

            sage: P.to_restricted_growth_word("intertwining")
            [0, 1, 2, 2, 1, 0, 3, 3, 2]

            sage: P = SetPartition([[1,2,4,7],[3,9],[5,6,10,11,13],[8],[12]])
            sage: P.to_restricted_growth_word()
            [0, 0, 1, 0, 2, 2, 0, 3, 1, 2, 2, 4, 2]

            sage: P.to_restricted_growth_word("intertwining")
            [0, 0, 1, 1, 2, 0, 1, 3, 3, 3, 0, 4, 1]

        TESTS::

            sage: P = SetPartition([])
            sage: P.to_restricted_growth_word()
            []
            sage: P.to_restricted_growth_word("intertwining")
            []
            sage: S = SetPartitions(5, 2)
            sage: all(S.from_restricted_growth_word(P.to_restricted_growth_word()) == P for P in S)
            True

            sage: S = SetPartitions(5, 2)
            sage: all(S.from_restricted_growth_word(P.to_restricted_growth_word("intertwining"), "intertwining") == P for P in S)
            True
        """
        if bijection == "blocks":
            return self.to_restricted_growth_word_blocks()
        if bijection == "intertwining":
            return self.to_restricted_growth_word_intertwining()
        raise ValueError("the given bijection is not valid")

    def to_restricted_growth_word_blocks(self):
        r"""
        Convert a set partition of `\{1,...,n\}` to a word of length `n`
        with letters in the nonnegative integers such that each
        letter is at most 1 larger than all the letters before.

        The word is obtained by sorting the blocks by their minimal
        element and setting the letters at the positions of the
        elements in the `i`-th block to `i`.

        OUTPUT: a restricted growth word

        .. SEEALSO::

            :meth:`to_restricted_growth_word`
            :meth:`SetPartitions.from_restricted_growth_word`

        EXAMPLES::

            sage: P = SetPartition([[1,4],[2,8],[3,5,6,9],[7]])
            sage: P.to_restricted_growth_word_blocks()
            [0, 1, 2, 0, 2, 2, 3, 1, 2]
        """
        w = [0] * self.size()
        # we can assume that the blocks are sorted by minimal element
        for i, B in enumerate(self):
            for j in B:
                w[j - 1] = i
        return w

    def to_restricted_growth_word_intertwining(self):
        r"""
        Convert a set partition of `\{1,...,n\}` to a word of length `n`
        with letters in the nonnegative integers such that each
        letter is at most 1 larger than all the letters before.

        The `i`-th letter of the word is the numbers of crossings of
        the arc (or half-arc) in the extended arc diagram ending at
        `i`, with arcs (or half-arcs) beginning at a smaller element
        and ending at a larger element.

        OUTPUT: a restricted growth word

        .. SEEALSO::

            :meth:`to_restricted_growth_word`
            :meth:`SetPartitions.from_restricted_growth_word`

        EXAMPLES::

            sage: P = SetPartition([[1,4],[2,8],[3,5,6,9],[7]])
            sage: P.to_restricted_growth_word_intertwining()
            [0, 1, 2, 2, 1, 0, 3, 3, 2]
        """
        A = sorted(self.arcs())
        O = (min(B) for B in self)  # openers
        C = [max(B) for B in self]  # closers
        I = [0] * self.size()
        for i in O:
            I[i - 1] = sum(1 for k, l in A if k < i < l) + sum(1 for k in C if k < i)
        for i, j in A:
            I[j - 1] = sum(1 for k, l in A if i < k < j < l) + sum(1 for k in C if i < k < j)
        return I

    def openers(self):
        """
        Return the minimal elements of the blocks.

        EXAMPLES::

            sage: P = SetPartition([[1,2,4,7],[3,9],[5,6,10,11,13],[8],[12]])
            sage: P.openers()
            [1, 3, 5, 8, 12]
        """
        return sorted([min(B) for B in self])

    def closers(self):
        """
        Return the maximal elements of the blocks.

        EXAMPLES::

            sage: P = SetPartition([[1,2,4,7],[3,9],[5,6,10,11,13],[8],[12]])
            sage: P.closers()
            [7, 8, 9, 12, 13]
        """
        return sorted([max(B) for B in self])

    def to_rook_placement(self, bijection='arcs'):
        r"""
        Return a set of pairs defining a placement of non-attacking rooks
        on a triangular board.

        The cells of the board corresponding to a set partition of
        `\{1,...,n\}` are the pairs `(i,j)` with `0 < i < j < n+1`.

        INPUT:

        - ``bijection`` -- (default: ``arcs``) defines the bijection
          from set partitions to rook placements.  These are
          currently:

          - ``arcs``: :meth:`arcs`
          - ``gamma``: :meth:`to_rook_placement_gamma`
          - ``rho``: :meth:`to_rook_placement_rho`
          - ``psi``: :meth:`to_rook_placement_psi`

        .. SEEALSO::

            :meth:`SetPartitions.from_rook_placement`

        EXAMPLES::

            sage: P = SetPartition([[1,2,4,7],[3,9],[5,6,10,11,13],[8],[12]])
            sage: P.to_rook_placement()
            [(1, 2), (2, 4), (4, 7), (3, 9), (5, 6), (6, 10), (10, 11), (11, 13)]
            sage: P.to_rook_placement("gamma")
            [(1, 4), (3, 5), (4, 6), (5, 8), (7, 11), (8, 9), (10, 12), (12, 13)]
            sage: P.to_rook_placement("rho")
            [(1, 2), (2, 6), (3, 4), (4, 10), (5, 9), (6, 7), (10, 11), (11, 13)]
            sage: P.to_rook_placement("psi")
            [(1, 2), (2, 6), (3, 4), (5, 9), (6, 7), (7, 10), (9, 11), (11, 13)]
        """
        if bijection == "arcs":
            return self.arcs()
        if bijection == "gamma":
            return self.to_rook_placement_gamma()
        if bijection == "rho":
            return self.to_rook_placement_rho()
        if bijection == "psi":
            return self.to_rook_placement_psi()
        raise ValueError("the given map is not valid")

    def to_rook_placement_gamma(self):
        """
        Return the rook diagram obtained by placing rooks according to
        Wachs and White's bijection gamma.

        Note that our index convention differs from the convention in
        [WW1991]_: regarding the rook board as a lower-right
        triangular grid, we refer with `(i,j)` to the cell in the
        `i`-th column from the right and the `j`-th row from the top.

        The algorithm proceeds as follows: non-attacking rooks are
        placed beginning at the left column.  If `n+1-i` is an
        opener, column `i` remains empty.  Otherwise, we place a rook
        into column `i`, such that the number of cells below the
        rook, which are not yet attacked by another rook, equals the
        index of the block to which `n+1-i` belongs.

        OUTPUT: list of coordinates

        .. SEEALSO::

            - :meth:`to_rook_placement`
            - :meth:`SetPartitions.from_rook_placement`
            - :meth:`SetPartitions.from_rook_placement_gamma`

        EXAMPLES::

            sage: P = SetPartition([[1,4],[2,8],[3,5,6,9],[7]])
            sage: P.to_rook_placement_gamma()
            [(1, 3), (2, 7), (4, 5), (5, 6), (6, 9)]

        Figure 5 in [WW1991]_::

            sage: P = SetPartition([[1,2,4,7],[3,9],[5,6,10,11,13],[8],[12]])
            sage: r = P.to_rook_placement_gamma(); r
            [(1, 4), (3, 5), (4, 6), (5, 8), (7, 11), (8, 9), (10, 12), (12, 13)]

        TESTS::

            sage: P = SetPartition([])
            sage: P.to_rook_placement_gamma()
            []
            sage: S = SetPartitions(5, 2)
            sage: all(S.from_rook_placement(P.to_rook_placement("gamma"), "gamma") == P for P in S)
            True
        """
        n = self.size()
        if n == 0:
            return []
        w = self.to_restricted_growth_word_blocks()
        # the set of openers - leftmost occurrences of a letter in w
        EC = sorted([w.index(i) for i in range(max(w) + 1)])
        rooks = []  # pairs (row i, column j)
        R = []  # attacked rows
        for c in range(n):  # columns from left to right
            if c not in EC:
                r = 0
                w_c = w[c]
                while w_c > 0 or r in R:
                    if r not in R:
                        w_c -= 1
                    r += 1
                rooks.append((n - c, n - r))
                R.append(r)
        return sorted(rooks)

    def to_rook_placement_rho(self):
        """
        Return the rook diagram obtained by placing rooks according to
        Wachs and White's bijection rho.

        Note that our index convention differs from the convention in
        [WW1991]_: regarding the rook board as a lower-right
        triangular grid, we refer with `(i,j)` to the cell in the
        `i`-th column from the right and the `j`-th row from the top.

        The algorithm proceeds as follows: non-attacking rooks are
        placed beginning at the top row.  The columns corresponding
        to the closers of the set partition remain empty.  Let `rs_j`
        be the number of closers which are larger than `j` and
        whose block is before the block of `j`.

        We then place a rook into row `j`, such that the number of
        cells to the left of the rook, which are not yet attacked by
        another rook and are not in a column corresponding to a
        closer, equals `rs_j`, unless there are not enough cells in
        this row available, in which case the row remains empty.

        One can show that the precisely those rows which correspond
        to openers of the set partition remain empty.

        OUTPUT: list of coordinates

        .. SEEALSO::

            - :meth:`to_rook_placement`
            - :meth:`SetPartitions.from_rook_placement`
            - :meth:`SetPartitions.from_rook_placement_rho`

        EXAMPLES::

            sage: P = SetPartition([[1,4],[2,8],[3,5,6,9],[7]])
            sage: P.to_rook_placement_rho()
            [(1, 5), (2, 6), (3, 4), (5, 9), (6, 8)]

        Figure 6 in [WW1991]_::

            sage: P = SetPartition([[1,2,4,7],[3,9],[5,6,10,11,13],[8],[12]])
            sage: r = P.to_rook_placement_rho(); r
            [(1, 2), (2, 6), (3, 4), (4, 10), (5, 9), (6, 7), (10, 11), (11, 13)]

            sage: sorted(P.closers() + [i for i, _ in r]) == list(range(1,14))
            True
            sage: sorted(P.openers() + [j for _, j in r]) == list(range(1,14))
            True

        TESTS::

            sage: P = SetPartition([])
            sage: P.to_rook_placement_rho()
            []
            sage: S = SetPartitions(5, 2)
            sage: all(S.from_rook_placement(P.to_rook_placement("rho"), "rho") == P for P in S)
            True
        """
        n = self.size()
        if n == 0:
            return []
        w = self.to_restricted_growth_word_blocks()
        w_rev = w[::-1]
        # the set of closers - rightmost occurrences of a letter in w
        R = sorted([n - w_rev.index(i) - 1 for i in range(max(w) + 1)])
        # the number of closers which are larger than i and whose
        # block is before the block of i
        rs = [sum(1 for j in R if j > i and w[j] < w[i]) for i in range(n)]
        EC = [n - j for j in R]  # empty columns
        rooks = []  # pairs (row i, column j)
        for i in range(1, n):
            U = [j for j in range(n + 1 - i, n + 1) if j not in EC]
            if rs[i] < len(U):
                j = U[rs[i]]
                rooks.append((n + 1 - j, i + 1))
                EC.append(j)
        return sorted(rooks)

    def to_rook_placement_psi(self):
        r"""
        Return the rook diagram obtained by placing rooks according to
        Yip's bijection psi.

        OUTPUT: list of coordinates

        .. SEEALSO::

            - :meth:`to_rook_placement`
            - :meth:`SetPartitions.from_rook_placement`
            - :meth:`SetPartitions.from_rook_placement_psi`

        EXAMPLES:

        Example 36 (arXiv version: Example 4.5) in [Yip2018]_::

            sage: P = SetPartition([[1, 5], [2], [3, 8, 9], [4], [6, 7]])
            sage: P.to_rook_placement_psi()
            [(1, 7), (3, 8), (4, 5), (7, 9)]

        Note that the columns corresponding to the minimal elements
        of the blocks remain empty.

        TESTS::

            sage: P = SetPartition([])
            sage: P.to_rook_placement_psi()
            []
            sage: S = SetPartitions(5,2)
            sage: all(S.from_rook_placement(P.to_rook_placement("psi"), "psi") == P for P in S)
            True
        """
        # Yip draws the diagram as an upper triangular matrix, thus
        # we refer to the cell in row i and column j with (i, j)
        n = self.size()
        degrees = []
        P = [sorted(e) for e in self]
        for j in range(n, 0, -1):
            # find the block number into which c was placed by first
            # removing j and then sorting the blocks
            B = next(B for B in P if B[-1] == j)
            if len(B) == 1:
                P.remove(B)
            else:
                del B[-1]
                P = sorted(P, key=lambda B: (-len(B), min(B)))
                b = P.index(B)
                i = j - b - 1
                degrees.append((j, i))
        # reconstruct rooks from degree sequence
        rooks = []
        attacked_rows = []
        for j, d in reversed(degrees):
            i = 1
            while d > i + sum(1 for r in attacked_rows if r > i):
                i += 1
            attacked_rows.append(i)
            rooks.append((i, j))
        return sorted(rooks)

    def apply_permutation(self, p):
        r"""
        Apply ``p`` to the underlying set of ``self``.

        INPUT:

        - ``p`` -- a permutation

        EXAMPLES::

            sage: x = SetPartition([[1,2], [3,5,4]])
            sage: p = Permutation([2,1,4,5,3])
            sage: x.apply_permutation(p)
            {{1, 2}, {3, 4, 5}}
            sage: q = Permutation([3,2,1,5,4])
            sage: x.apply_permutation(q)
            {{1, 4, 5}, {2, 3}}

            sage: m = PerfectMatching([(1,4),(2,6),(3,5)])
            sage: m.apply_permutation(Permutation([4,1,5,6,3,2]))
            [(1, 2), (3, 5), (4, 6)]
        """
        return self.__class__(self.parent(), [Set(map(p, B)) for B in self])

    def crossings_iterator(self):
        r"""
        Return the crossing arcs of a set partition on a totally ordered set.

        OUTPUT:

        We place the elements of the ground set in order on a
        line and draw the set partition by linking consecutive
        elements of each block in the upper half-plane. This
        function returns an iterator over the pairs of crossing
        lines (as a line correspond to a pair, the iterator
        produces pairs of pairs).

        EXAMPLES::

            sage: p = SetPartition([[1,4],[2,5,7],[3,6]])
            sage: next(p.crossings_iterator())
            ((1, 4), (2, 5))

        TESTS::

            sage: p = SetPartition([]);  p.crossings()
            []
        """
        # each arc is sorted, but the set of arcs might not be
        arcs = sorted(self.arcs(), key=min)
        while arcs:
            i1, j1 = arcs.pop(0)
            for i2, j2 in arcs:
                # we know that i1 < i2 and i1 < j1 and i2 < j2
                if i2 < j1 < j2:
                    yield ((i1, j1), (i2, j2))

    def crossings(self):
        r"""
        Return the crossing arcs of a set partition on a totally ordered set.

        OUTPUT:

        We place the elements of the ground set in order on a
        line and draw the set partition by linking consecutive
        elements of each block in the upper half-plane. This
        function returns a list of the pairs of crossing lines
        (as a line correspond to a pair, it returns a list of
        pairs of pairs).

        EXAMPLES::

            sage: p = SetPartition([[1,4],[2,5,7],[3,6]])
            sage: p.crossings()
            [((1, 4), (2, 5)), ((1, 4), (3, 6)), ((2, 5), (3, 6)), ((3, 6), (5, 7))]

        TESTS::

            sage: p = SetPartition([]);  p.crossings()
            []
        """
        return list(self.crossings_iterator())

    def number_of_crossings(self):
        r"""
        Return the number of crossings.

        OUTPUT:

        We place the elements of the ground set in order on a
        line and draw the set partition by linking consecutive
        elements of each block in the upper half-plane. This
        function returns the number the pairs of crossing lines.

        EXAMPLES::

            sage: p = SetPartition([[1,4],[2,5,7],[3,6]])
            sage: p.number_of_crossings()
            4

            sage: n = PerfectMatching([3,8,1,7,6,5,4,2]); n
            [(1, 3), (2, 8), (4, 7), (5, 6)]
            sage: n.number_of_crossings()
            1
        """
        return Integer(len(list(self.crossings_iterator())))

    def is_noncrossing(self) -> bool:
        r"""
        Check if ``self`` is noncrossing.

        OUTPUT:

        We place the elements of the ground set in order on a
        line and draw the set partition by linking consecutive
        elements of each block in the upper half-plane.  This
        function returns ``True`` if the picture obtained this
        way has no crossings.

        EXAMPLES::

            sage: p = SetPartition([[1,4],[2,5,7],[3,6]])
            sage: p.is_noncrossing()
            False

            sage: n = PerfectMatching([3,8,1,7,6,5,4,2]); n
            [(1, 3), (2, 8), (4, 7), (5, 6)]
            sage: n.is_noncrossing()
            False
            sage: PerfectMatching([(1, 4), (2, 3), (5, 6)]).is_noncrossing()
            True
        """
        it = self.crossings_iterator()
        try:
            next(it)
        except StopIteration:
            return True
        return False

    def nestings_iterator(self):
        r"""
        Iterate over the nestings of ``self``.

        OUTPUT:

        We place the elements of the ground set in order on a
        line and draw the set partition by linking consecutive
        elements of each block in the upper half-plane. This
        function returns an iterator over the pairs of nesting
        lines (as a line correspond to a pair, the iterator
        produces pairs of pairs).

        EXAMPLES::

            sage: n = PerfectMatching([(1, 6), (2, 7), (3, 5), (4, 8)])
            sage: it = n.nestings_iterator()
            sage: next(it)
            ((1, 6), (3, 5))
            sage: next(it)
            ((2, 7), (3, 5))
            sage: next(it)
            Traceback (most recent call last):
            ...
            StopIteration
        """
        # each arc is sorted, but the set of arcs might not be
        arcs = sorted(self.arcs(), key=min)
        while arcs:
            i1, j1 = arcs.pop(0)
            for i2, j2 in arcs:
                # we know that i1 < i2 and i1 < j1 and i2 < j2
                if i2 < j2 < j1:
                    yield ((i1, j1), (i2, j2))

    def nestings(self):
        r"""
        Return the nestings of ``self``.

        OUTPUT:

        We place the elements of the ground set in order on a
        line and draw the set partition by linking consecutive
        elements of each block in the upper half-plane. This
        function returns the list of the pairs of nesting lines
        (as a line correspond to a pair, it returns a list of
        pairs of pairs).

        EXAMPLES::

            sage: m = PerfectMatching([(1, 6), (2, 7), (3, 5), (4, 8)])
            sage: m.nestings()
            [((1, 6), (3, 5)), ((2, 7), (3, 5))]

            sage: n = PerfectMatching([3,8,1,7,6,5,4,2]); n
            [(1, 3), (2, 8), (4, 7), (5, 6)]
            sage: n.nestings()
            [((2, 8), (4, 7)), ((2, 8), (5, 6)), ((4, 7), (5, 6))]

        TESTS::

            sage: m = PerfectMatching([]); m.nestings()
            []
        """
        return list(self.nestings_iterator())

    def number_of_nestings(self):
        r"""
        Return the number of nestings of ``self``.

        OUTPUT:

        We place the elements of the ground set in order on a
        line and draw the set partition by linking consecutive
        elements of each block in the upper half-plane. This
        function returns the number the pairs of nesting lines.

        EXAMPLES::

            sage: n = PerfectMatching([3,8,1,7,6,5,4,2]); n
            [(1, 3), (2, 8), (4, 7), (5, 6)]
            sage: n.number_of_nestings()
            3
        """
        c = Integer(0)
        one = Integer(1)
        for _ in self.nestings_iterator():
            c += one
        return c

    def is_nonnesting(self) -> bool:
        r"""
        Return if ``self`` is nonnesting or not.

        OUTPUT:

        We place the elements of the ground set in order on a
        line and draw the set partition by linking consecutive
        elements of each block in the upper half-plane. This
        function returns ``True`` if the picture obtained this
        way has no nestings.

        EXAMPLES::

            sage: n = PerfectMatching([3,8,1,7,6,5,4,2]); n
            [(1, 3), (2, 8), (4, 7), (5, 6)]
            sage: n.is_nonnesting()
            False
            sage: PerfectMatching([(1, 3), (2, 5), (4, 6)]).is_nonnesting()
            True
        """
        it = self.nestings_iterator()
        try:
            next(it)
        except StopIteration:
            return True
        return False

    def is_atomic(self) -> bool:
        r"""
        Return if ``self`` is an atomic set partition.

        A (standard) set partition `A` can be split if there exist `j < i`
        such that `\max(A_j) < \min(A_i)` where `A` is ordered by minimal
        elements. This means we can write `A = B | C` for some nonempty set
        partitions `B` and `C`. We call a set partition *atomic* if it
        cannot be split and is nonempty. Here, the pipe symbol
        `|` is as defined in method :meth:`pipe`.

        EXAMPLES::

            sage: SetPartition([[1,3], [2]]).is_atomic()
            True
            sage: SetPartition([[1,3], [2], [4]]).is_atomic()
            False
            sage: SetPartition([[1], [2,4], [3]]).is_atomic()
            False
            sage: SetPartition([[1,2,3,4]]).is_atomic()
            True
            sage: SetPartition([[1, 4], [2], [3]]).is_atomic()
            True
            sage: SetPartition([]).is_atomic()
            False
        """
        if len(self) == 0:
            return False
        maximum_so_far = max(self[0])
        for S in self[1:]:
            if maximum_so_far < min(S):
                return False
            maximum_so_far = max(maximum_so_far, *S)
        return True

    def standardization(self):
        r"""
        Return the standardization of ``self``.

        Given a set partition `A = \{A_1, \ldots, A_n\}` of an ordered
        set `S`, the standardization of `A` is the set partition of
        `\{1, 2, \ldots, |S|\}` obtained by replacing the elements of
        the parts of `A` by the integers `1, 2, \ldots, |S|` in such
        a way that their relative order is preserved (i. e., the
        smallest element in the whole set partition is replaced by
        `1`, the next-smallest by `2`, and so on).

        EXAMPLES::

            sage: SetPartition([[4], [1, 3]]).standardization()
            {{1, 2}, {3}}
            sage: SetPartition([[4], [6, 3]]).standardization()
            {{1, 3}, {2}}
            sage: SetPartition([]).standardization()
            {}
            sage: SetPartition([('c','b'),('d','f'),('e','a')]).standardization()
            {{1, 5}, {2, 3}, {4, 6}}
        """
        r = {e: i for i, e in enumerate(sorted(self.base_set()), 1)}
        return SetPartitions(len(r))([[r[e] for e in b] for b in self])

    def restriction(self, I):
        """
        Return the restriction of ``self`` to a subset ``I``
        (which is given as a set or list or any other iterable).

        EXAMPLES::

            sage: A = SetPartition([[1], [2,3]])
            sage: A.restriction([1,2])
            {{1}, {2}}
            sage: A.restriction([2,3])
            {{2, 3}}
            sage: A.restriction([])
            {}
            sage: A.restriction([4])
            {}
        """
        ret = []
        for part in self:
            newpart = [i for i in part if i in I]
            if len(newpart) != 0:
                ret.append(newpart)
        return SetPartition(ret)

    def ordered_set_partition_action(self, s):
        r"""
        Return the action of an ordered set partition ``s`` on ``self``.

        Let `A = \{A_1, A_2, \ldots, A_k\}` be a set partition of some
        set `S` and `s` be an ordered set partition (i.e., set composition)
        of a subset of `[k]`. Let `A^{\downarrow}` denote the standardization
        of `A`, and `A_{\{ i_1, i_2, \ldots, i_m \}}` denote the sub-partition
        `\{A_{i_1}, A_{i_2}, \ldots, A_{i_m}\}` for any subset
        `\{i_1, \ldots, i_m\}` of `\{1, \ldots, k\}`. We define the set
        partition `s(A)` by

        .. MATH::

            s(A) = A_{s_1}^{\downarrow} | A_{s_2}^{\downarrow} | \cdots
            | A_{s_q}^{\downarrow}.

        where `s = (s_1, s_2, \ldots, s_q)`. Here, the pipe symbol
        `|` is as defined in method :meth:`pipe`.

        This is `s[A]` in section 2.3 in [LM2011]_.

        INPUT:

        - ``s`` -- an ordered set partition with base set a subset
          of `\{1, \ldots, k\}`

        EXAMPLES::

            sage: A = SetPartition([[1], [2,4], [3]])
            sage: s = OrderedSetPartition([[1,3], [2]])
            sage: A.ordered_set_partition_action(s)
            {{1}, {2}, {3, 4}}
            sage: s = OrderedSetPartition([[2,3], [1]])
            sage: A.ordered_set_partition_action(s)
            {{1, 3}, {2}, {4}}

        We create Figure 1 in [LM2011]_ (we note that there is a typo in the
        lower-left corner of the table in the published version of the
        paper, whereas the arXiv version gives the correct partition)::

            sage: A = SetPartition([[1,3], [2,9], [4,5,8], [7]])
            sage: B = SetPartition([[1,3], [2,8], [4,5,6], [7]])
            sage: C = SetPartition([[1,5], [2,8], [3,4,6], [7]])
            sage: s = OrderedSetPartition([[1,3], [2]])
            sage: t = OrderedSetPartition([[2], [3,4]])
            sage: u = OrderedSetPartition([[1], [2,3,4]])
            sage: A.ordered_set_partition_action(s)
            {{1, 2}, {3, 4, 5}, {6, 7}}
            sage: A.ordered_set_partition_action(t)
            {{1, 2}, {3, 4, 6}, {5}}
            sage: A.ordered_set_partition_action(u)
            {{1, 2}, {3, 8}, {4, 5, 7}, {6}}
            sage: B.ordered_set_partition_action(s)
            {{1, 2}, {3, 4, 5}, {6, 7}}
            sage: B.ordered_set_partition_action(t)
            {{1, 2}, {3, 4, 5}, {6}}
            sage: B.ordered_set_partition_action(u)
            {{1, 2}, {3, 8}, {4, 5, 6}, {7}}
            sage: C.ordered_set_partition_action(s)
            {{1, 4}, {2, 3, 5}, {6, 7}}
            sage: C.ordered_set_partition_action(t)
            {{1, 2}, {3, 4, 5}, {6}}
            sage: C.ordered_set_partition_action(u)
            {{1, 2}, {3, 8}, {4, 5, 6}, {7}}

        REFERENCES:

        - [LM2011]_
        """
        cur = 1
        ret = []
        for part in s:
            sub_parts = [list(self[i - 1]) for i in part]  # -1 for indexing
            # Standardizing sub_parts (the cur variable not being reset
            # to 1 gives us the offset we want):
            mins = [min(i) for i in sub_parts]
            over_max = max(map(max, sub_parts)) + 1
            temp = [[] for _ in repeat(None, len(part))]
            while min(mins) != over_max:
                m = min(mins)
                i = mins.index(m)
                temp[i].append(cur)
                cur += 1
                sub_parts[i].pop(sub_parts[i].index(m))
                if len(sub_parts[i]) != 0:
                    mins[i] = min(sub_parts[i])
                else:
                    mins[i] = over_max
            ret += temp
        return SetPartition(ret)

    def refinements(self):
        """
        Return a list of refinements of ``self``.

        .. SEEALSO::

            :meth:`coarsenings`

        EXAMPLES::

            sage: SetPartition([[1,3],[2,4]]).refinements()                             # needs sage.graphs sage.libs.flint
            [{{1, 3}, {2, 4}},
             {{1, 3}, {2}, {4}},
             {{1}, {2, 4}, {3}},
             {{1}, {2}, {3}, {4}}]
            sage: SetPartition([[1],[2,4],[3]]).refinements()                           # needs sage.graphs sage.libs.flint
            [{{1}, {2, 4}, {3}}, {{1}, {2}, {3}, {4}}]
            sage: SetPartition([]).refinements()                                        # needs sage.graphs sage.libs.flint
            [{}]
        """
        L = [SetPartitions(part) for part in self]
        return [SetPartition(sum(map(list, x), [])) for x in itertools.product(*L)]

    def strict_coarsenings(self):
        r"""
        Return all strict coarsenings of ``self``.

        Strict coarsening is the binary relation on set partitions
        defined as the transitive-and-reflexive closure of the
        relation `\prec` defined as follows: For two set partitions
        `A` and `B`, we have `A \prec B` if there exist parts
        `A_i, A_j` of `A` such that `\max(A_i) < \min(A_j)` and
        `B = A \setminus \{A_i, A_j\} \cup \{ A_i \cup A_j \}`.

        EXAMPLES::

            sage: A = SetPartition([[1],[2,3],[4]])
            sage: A.strict_coarsenings()
            [{{1}, {2, 3}, {4}}, {{1, 2, 3}, {4}}, {{1, 4}, {2, 3}},
             {{1}, {2, 3, 4}}, {{1, 2, 3, 4}}]
            sage: SetPartition([[1],[2,4],[3]]).strict_coarsenings()
            [{{1}, {2, 4}, {3}}, {{1, 2, 4}, {3}}, {{1, 3}, {2, 4}}]
            sage: SetPartition([]).strict_coarsenings()
            [{}]
        """
        # This is more or less generic code for computing a
        # transitive-and-reflexive closure by depth-first search.
        todo = [self]
        visited = set([self])
        ret = [self]
        while todo:
            A = todo.pop()
            for i, part in enumerate(A):
                for j, other in enumerate(A[i + 1:]):
                    if max(part) < min(other):
                        next_pi = A[:i]
                        next_pi.append(part.union(other))
                        next_pi += A[i + 1:i + 1 + j] + A[i + j + 2:]
                        next_pi = SetPartition(next_pi)
                        if next_pi not in visited:
                            todo.append(next_pi)
                            visited.add(next_pi)
                            ret.append(next_pi)
        return ret

    def arcs(self):
        r"""
        Return ``self`` as a list of arcs.

        Assuming that the blocks are sorted, the arcs are the pairs
        of consecutive elements in the blocks.

        EXAMPLES::

            sage: A = SetPartition([[1],[2,3],[4]])
            sage: A.arcs()
            [(2, 3)]
            sage: B = SetPartition([[1,3,6,7],[2,5],[4]])
            sage: B.arcs()
            [(1, 3), (3, 6), (6, 7), (2, 5)]
        """
        arcs = []
        for p in self:
            p = sorted(p)
            arcs.extend((p[i], p[i + 1]) for i in range(len(p) - 1))
        return arcs

    def plot(self, angle=None, color='black', base_set_dict=None):
        r"""
        Return a plot of ``self``.

        INPUT:

        - ``angle`` -- (default: `\pi/4`) the angle at which the arcs take off
          (if angle is negative, the arcs are drawn below the horizontal line)

        - ``color`` -- (default: ``'black'``) color of the arcs

        - ``base_set_dict`` -- (optional) dictionary with keys elements
          of :meth:`base_set()` and values as integer or float

        EXAMPLES::

            sage: p = SetPartition([[1,10,11],[2,3,7],[4,5,6],[8,9]])
            sage: p.plot()                                                              # needs sage.plot sage.symbolic
            Graphics object consisting of 29 graphics primitives

        .. PLOT::

            p = SetPartition([[1,10,11],[2,3,7],[4,5,6],[8,9]])
            sphinx_plot(p.plot())

        ::

            sage: p = SetPartition([[1,3,4],[2,5]])
            sage: print(p.plot().description())                                         # needs sage.plot sage.symbolic
            Point set defined by 1 point(s):    [(0.0, 0.0)]
            Point set defined by 1 point(s):    [(1.0, 0.0)]
            Point set defined by 1 point(s):    [(2.0, 0.0)]
            Point set defined by 1 point(s):    [(3.0, 0.0)]
            Point set defined by 1 point(s):    [(4.0, 0.0)]
            Text '1' at the point (0.0,-0.1)
            Text '2' at the point (1.0,-0.1)
            Text '3' at the point (2.0,-0.1)
            Text '4' at the point (3.0,-0.1)
            Text '5' at the point (4.0,-0.1)
            Arc with center (1.0,-1.0) radii (1.41421356237...,1.41421356237...)
             angle 0.0 inside the sector (0.785398163397...,2.35619449019...)
            Arc with center (2.5,-0.5) radii (0.70710678118...,0.70710678118...)
             angle 0.0 inside the sector (0.785398163397...,2.35619449019...)
            Arc with center (2.5,-1.5) radii (2.1213203435...,2.1213203435...)
             angle 0.0 inside the sector (0.785398163397...,2.35619449019...)
            sage: p = SetPartition([['a','c'],['b','d'],['e']])
            sage: print(p.plot().description())                                         # needs sage.plot sage.symbolic
            Point set defined by 1 point(s):  [(0.0, 0.0)]
            Point set defined by 1 point(s):    [(1.0, 0.0)]
            Point set defined by 1 point(s):    [(2.0, 0.0)]
            Point set defined by 1 point(s):    [(3.0, 0.0)]
            Point set defined by 1 point(s):    [(4.0, 0.0)]
            Text 'a' at the point (0.0,-0.1)
            Text 'b' at the point (1.0,-0.1)
            Text 'c' at the point (2.0,-0.1)
            Text 'd' at the point (3.0,-0.1)
            Text 'e' at the point (4.0,-0.1)
            Arc with center (1.0,-1.0) radii (1.41421356237...,1.41421356237...)
             angle 0.0 inside the sector (0.785398163397...,2.35619449019...)
            Arc with center (2.0,-1.0) radii (1.41421356237...,1.41421356237...)
             angle 0.0 inside the sector (0.785398163397...,2.35619449019...)
            sage: p = SetPartition([['a','c'],['b','d'],['e']])
            sage: print(p.plot(base_set_dict={'a':0,'b':1,'c':2,                        # needs sage.plot sage.symbolic
            ....:                             'd':-2.3,'e':5.4}).description())
            Point set defined by 1 point(s):    [(-2.3, 0.0)]
            Point set defined by 1 point(s):    [(0.0, 0.0)]
            Point set defined by 1 point(s):    [(1.0, 0.0)]
            Point set defined by 1 point(s):    [(2.0, 0.0)]
            Point set defined by 1 point(s):    [(5.4, 0.0)]
            Text 'a' at the point (0.0,-0.1)
            Text 'b' at the point (1.0,-0.1)
            Text 'c' at the point (2.0,-0.1)
            Text 'd' at the point (-2.3,-0.1)
            Text 'e' at the point (5.4,-0.1)
            Arc with center (-0.6...,-1.65) radii (2.3334523779...,2.3334523779...)
             angle 0.0 inside the sector (0.785398163397...,2.35619449019...)
            Arc with center (1.0,-1.0) radii (1.4142135623...,1.4142135623...)
             angle 0.0 inside the sector (0.785398163397...,2.35619449019...)
        """
        from sage.plot.graphics import Graphics
        from sage.plot.point import point
        from sage.plot.text import text
        from sage.plot.arc import arc
        from sage.symbolic.constants import pi
        from sage.functions.trig import tan, sin
        from sage.functions.generalized import sgn

        diag = Graphics()
        sorted_vertices_list = list(self.base_set())
        sorted_vertices_list.sort()

        if angle is None:
            angle = pi / 4

        if base_set_dict is not None:
            vertices_dict = base_set_dict
        else:
            vertices_dict = {val: pos for pos, val in enumerate(sorted_vertices_list)}

        for elt in vertices_dict:
            pos = vertices_dict[elt]
            diag += point((pos, 0), size=30, color=color)
            diag += text(elt, (pos, -sgn(angle) * 0.1), color=color)
            # TODO: change 0.1 to something proportional to the height of the picture

        for k, j in self.arcs():
            pos_k, pos_j = float(vertices_dict[k]), float(vertices_dict[j])
            center = ((pos_k + pos_j) / 2,
                      -abs(pos_j - pos_k) / (2 * tan(angle)))
            r1 = abs((pos_j - pos_k) / (2 * sin(angle)))
            sector = (sgn(angle) * (pi / 2 - angle),
                      sgn(angle) * (pi / 2 + angle))
            diag += arc(center=center, r1=r1, sector=sector, color=color)

        diag.axes(False)
        return diag


class SetPartitions(UniqueRepresentation, Parent):
    r"""
    An (unordered) partition of a set `S` is a set of pairwise
    disjoint nonempty subsets with union `S`, and is represented
    by a sorted list of such subsets.

    ``SetPartitions(s)`` returns the class of all set partitions of the set
    ``s``, which can be given as a set or a string; if a string, each
    character is considered an element.

    ``SetPartitions(n)``, where ``n`` is an integer, returns the class of
    all set partitions of the set `\{1, 2, \ldots, n\}`.

    You may specify a second argument `k`. If `k` is an integer,
    :class:`SetPartitions` returns the class of set partitions into `k` parts;
    if it is an integer partition, :class:`SetPartitions` returns the class of
    set partitions whose block sizes correspond to that integer partition.

    The Bell number `B_n`, named in honor of Eric Temple Bell,
    is the number of different partitions of a set with `n` elements.

    EXAMPLES::

        sage: S = [1,2,3,4]
        sage: SetPartitions(S, 2)
        Set partitions of {1, 2, 3, 4} with 2 parts
        sage: SetPartitions([1,2,3,4], [3,1]).list()                                    # needs sage.graphs sage.rings.finite_rings
        [{{1}, {2, 3, 4}}, {{1, 2, 3}, {4}}, {{1, 2, 4}, {3}}, {{1, 3, 4}, {2}}]
        sage: SetPartitions(7, [3,3,1]).cardinality()                                   # needs sage.libs.flint
        70

    In strings, repeated letters are not considered distinct as of
    :issue:`14140`::

        sage: SetPartitions('abcde').cardinality()                                      # needs sage.libs.flint
        52
        sage: SetPartitions('aabcd').cardinality()                                      # needs sage.libs.flint
        15

    If the number of parts exceeds the length of the set,
    an empty iterator is returned (:issue:`37643`)::

        sage: SetPartitions(range(3), 4).list()
        []
        sage: SetPartitions('abcd', 6).list()
        []

    REFERENCES:

    - :wikipedia:`Partition_of_a_set`
    """
    @staticmethod
    def __classcall_private__(cls, s=None, part=None):
        """
        Normalize input to ensure a unique representation.

        EXAMPLES::

            sage: S = SetPartitions(4)
            sage: T = SetPartitions([1,2,3,4])
            sage: S is T
            True
        """
        if s is None:
            return SetPartitions_all()
        if isinstance(s, (int, Integer)):
            s = frozenset(range(1, s + 1))
        else:
            try:
                if s.cardinality() == infinity:
                    raise ValueError("the set must be finite")
            except AttributeError:
                pass
            s = frozenset(s)

        if part is None:
            return SetPartitions_set(s)
        else:
            if isinstance(part, (int, Integer)):
                return SetPartitions_setn(s, part)
            else:
                part = sorted(part, reverse=True)
                if part not in Partitions(len(s)):
                    raise ValueError("part must be an integer partition of %s" % len(s))
                return SetPartitions_setparts(s, Partition(part))

    def __contains__(self, x):
        """
        TESTS::

            sage: S = SetPartitions(4, [2,2])
            sage: SA = SetPartitions()
            sage: all(sp in SA for sp in S)                                             # needs sage.graphs sage.modules sage.rings.finite_rings
            True
            sage: Set([Set([1,2]),Set([3,7])]) in SA                                    # needs sage.graphs
            True
            sage: Set([Set([1,2]),Set([2,3])]) in SA                                    # needs sage.graphs
            False
            sage: Set([]) in SA                                                         # needs sage.graphs
            True
        """
        # x must be a set
        if not isinstance(x, (SetPartition, set, frozenset, Set_generic)):
            return False

        # Check that all parts are disjoint
        base_set = set(e for p in x for e in p)
        if len(base_set) != sum(map(len, x)):
            return False

        # Check to make sure each element of x is a set
        for s in x:
            if not isinstance(s, (set, frozenset, Set_generic)):
                return False

        return True

    def _element_constructor_(self, s, check=True):
        """
        Construct an element of ``self`` from ``s``.

        INPUT:

        - ``s`` -- set of sets

        EXAMPLES::

            sage: S = SetPartitions(4)
            sage: elt = S([[1,3],[2,4]]); elt
            {{1, 3}, {2, 4}}
            sage: P = SetPartitions()
            sage: P(elt).parent() is P
            True
            sage: S = SetPartitions([])
            sage: S([])
            {}
        """
        if isinstance(s, SetPartition):
            if isinstance(s.parent(), SetPartitions):
                return self.element_class(self, s, check=check)
            raise ValueError("cannot convert %s into an element of %s" % (s, self))
        return self.element_class(self, s, check=check)

    Element = SetPartition

    def from_restricted_growth_word(self, w, bijection='blocks'):
        r"""
        Convert a word of length `n` with letters in the nonnegative
        integers such that each letter is at most 1 larger than all
        the letters before to a set partition of `\{1,...,n\}`.

        INPUT:

        - ``w`` -- a restricted growth word

        - ``bijection`` -- (default: ``blocks``) defines the map from
          restricted growth functions to set partitions.  These are
          currently:

          - ``blocks``: .

          - ``intertwining``: :meth:`from_restricted_growth_word_intertwining`.

        OUTPUT: a set partition

        .. SEEALSO::

            :meth:`SetPartition.to_restricted_growth_word`

        EXAMPLES::

            sage: SetPartitions().from_restricted_growth_word([0, 1, 2, 0, 2, 2, 3, 1, 2])
            {{1, 4}, {2, 8}, {3, 5, 6, 9}, {7}}

            sage: SetPartitions().from_restricted_growth_word([0, 0, 1, 0, 2, 2, 0, 3, 1, 2, 2, 4, 2])
            {{1, 2, 4, 7}, {3, 9}, {5, 6, 10, 11, 13}, {8}, {12}}

            sage: SetPartitions().from_restricted_growth_word([0, 0, 1, 0, 2, 2, 0, 3, 1, 2, 2, 4, 2], "intertwining")
            {{1, 2, 6, 7, 9}, {3, 4}, {5, 10, 13}, {8, 11}, {12}}
        """
        if bijection == "blocks":
            return self.from_restricted_growth_word_blocks(w)
        if bijection == "intertwining":
            return self.from_restricted_growth_word_intertwining(w)
        raise ValueError("the given bijection is not valid")

    def from_restricted_growth_word_blocks(self, w):
        r"""
        Convert a word of length `n` with letters in the nonnegative
        integers such that each letter is at most 1 larger than all
        the letters before to a set partition of `\{1,...,n\}`.

        ``w[i]`` is the index of the block containing ``i+1`` when
        sorting the blocks by their minimal element.

        INPUT:

        - ``w`` -- a restricted growth word

        OUTPUT: a set partition

        .. SEEALSO::

            :meth:`from_restricted_growth_word`
            :meth:`SetPartition.to_restricted_growth_word`

        EXAMPLES::

            sage: SetPartitions().from_restricted_growth_word_blocks([0, 0, 1, 0, 2, 2, 0, 3, 1, 2, 2, 4, 2])
            {{1, 2, 4, 7}, {3, 9}, {5, 6, 10, 11, 13}, {8}, {12}}
        """
        R = []
        for i, B in enumerate(w, 1):
            if len(R) <= B:
                R.append([i])
            else:
                R[B].append(i)
        return self.element_class(self, R)

    def from_restricted_growth_word_intertwining(self, w):
        r"""
        Convert a word of length `n` with letters in the nonnegative
        integers such that each letter is at most 1 larger than all
        the letters before to a set partition of `\{1,...,n\}`.

        The `i`-th letter of the word is the numbers of crossings of
        the arc (or half-arc) in the extended arc diagram ending at
        `i`, with arcs (or half-arcs) beginning at a smaller element
        and ending at a larger element.

        INPUT:

        - ``w`` -- a restricted growth word

        OUTPUT: a set partition

        .. SEEALSO::

            :meth:`from_restricted_growth_word`
            :meth:`SetPartition.to_restricted_growth_word`

        EXAMPLES::

            sage: SetPartitions().from_restricted_growth_word_intertwining([0, 0, 1, 0, 2, 2, 0, 3, 1, 2, 2, 4, 2])
            {{1, 2, 6, 7, 9}, {3, 4}, {5, 10, 13}, {8, 11}, {12}}
        """
        if len(w) == 0:
            return self.element_class(self, [])
        R = [[1]]
        C = [1]  # closers, always reverse sorted
        m = 0  # max
        for i in range(1, len(w)):
            if w[i] == 1 + m:  # i+1 is an opener
                m += 1
                R.append([i + 1])
            else:
                # add i+1 to the block, such that there are I[i] closers thereafter
                l = C[w[i]]
                B = next(B for B in R if l in B)
                B.append(i + 1)
                C.remove(l)
            C = [i + 1] + C
        return self.element_class(self, R)

    def from_rook_placement(self, rooks, bijection='arcs', n=None):
        r"""
        Convert a rook placement of the triangular grid to a set
        partition of `\{1,...,n\}`.

        If ``n`` is not given, it is first checked whether it can be
        determined from the parent, otherwise it is the maximal
        occurring integer in the set of rooks.

        INPUT:

        - ``rooks`` -- list of pairs `(i,j)` satisfying
          `0 < i < j < n+1`

        - ``bijection`` -- (default: ``arcs``) defines the map from
          rook placements to set partitions.  These are currently:

          - ``arcs``: :meth:`from_arcs`.
          - ``gamma``: :meth:`from_rook_placement_gamma`.
          - ``rho``: :meth:`from_rook_placement_rho`.
          - ``psi``: :meth:`from_rook_placement_psi`.

        - ``n`` -- (optional) the size of the ground set

        .. SEEALSO::

            :meth:`SetPartition.to_rook_placement`

        EXAMPLES::

            sage: SetPartitions(9).from_rook_placement([[1,4],[2,8],[3,5],[5,6],[6,9]])
            {{1, 4}, {2, 8}, {3, 5, 6, 9}, {7}}

            sage: SetPartitions(13).from_rook_placement([[12,13],[10,12],[8,9],[7,11],[5,8],[4,6],[3,5],[1,4]], "gamma")
            {{1, 2, 4, 7}, {3, 9}, {5, 6, 10, 11, 13}, {8}, {12}}

        TESTS::

            sage: SetPartitions().from_rook_placement([])
            {}
            sage: SetPartitions().from_rook_placement([], "gamma")
            {}
            sage: SetPartitions().from_rook_placement([], "rho")
            {}
            sage: SetPartitions().from_rook_placement([], "psi")
            {}
            sage: SetPartitions().from_rook_placement([], n=2)
            {{1}, {2}}
            sage: SetPartitions().from_rook_placement([], "gamma", 2)
            {{1}, {2}}
            sage: SetPartitions().from_rook_placement([], "rho", 2)
            {{1}, {2}}
            sage: SetPartitions().from_rook_placement([], "psi", 2)
            {{1}, {2}}
        """
        if n is None:
            try:
                n = self.base_set_cardinality()
            except AttributeError:
                n = max((max(r) for r in rooks), default=0)

        if bijection == "arcs":
            return self.from_arcs(rooks, n)
        if bijection == "rho":
            return self.from_rook_placement_rho(rooks, n)
        if bijection == "gamma":
            return self.from_rook_placement_gamma(rooks, n)
        if bijection == "psi":
            return self.from_rook_placement_psi(rooks, n)
        raise ValueError("the given bijection is not valid")

    def from_arcs(self, arcs, n):
        r"""
        Return the coarsest set partition of `\{1,...,n\}` such that any
        two elements connected by an arc are in the same block.

        INPUT:

        - ``n`` -- integer specifying the size of the set
          partition to be produced

        - ``arcs`` -- list of pairs specifying which elements are
          in the same block

        .. SEEALSO::

            - :meth:`from_rook_placement`
            - :meth:`SetPartition.to_rook_placement`
            - :meth:`SetPartition.arcs`

        EXAMPLES::

            sage: SetPartitions().from_arcs([(2,3)], 5)
            {{1}, {2, 3}, {4}, {5}}
        """
        P = DisjointSet(range(1, n + 1))
        for i, j in arcs:
            P.union(i, j)
        return self.element_class(self, P)

    def from_rook_placement_gamma(self, rooks, n):
        r"""
        Return the set partition of `\{1,...,n\}` corresponding to the
        given rook placement by applying Wachs and White's bijection
        gamma.

        Note that our index convention differs from the convention in
        [WW1991]_: regarding the rook board as a lower-right
        triangular grid, we refer with `(i,j)` to the cell in the
        `i`-th column from the right and the `j`-th row from the top.

        INPUT:

        - ``n`` -- integer specifying the size of the set
          partition to be produced

        - ``rooks`` -- list of pairs `(i,j)` such that `0 < i < j < n+1`

        OUTPUT: a set partition

        .. SEEALSO::

            - :meth:`from_rook_placement`
            - :meth:`SetPartition.to_rook_placement`
            - :meth:`SetPartition.to_rook_placement_gamma`

        EXAMPLES:

        Figure 5 in [WW1991]_ concerns the following rook placement::

            sage: r = [(1, 4), (3, 5), (4, 6), (5, 8), (7, 11), (8, 9), (10, 12), (12, 13)]

        Note that the rook `(1, 4)`, translated into Wachs and
        White's convention, is a rook in row 4 from the top and
        column 13 from the left.  The corresponding set partition
        is::

            sage: SetPartitions().from_rook_placement_gamma(r, 13)
            {{1, 2, 4, 7}, {3, 9}, {5, 6, 10, 11, 13}, {8}, {12}}
        """
        if n == 0:
            return self.element_class(self, [])
        # the columns of the board, beginning with column n-1
        C = [set(range(n + 1 - j, n + 1)) for j in range(1, n)]
        # delete cells north and east of each rook
        for j, i in rooks:
            # north
            C[n - j - 1].difference_update(range(j + 1, i + 1))
            # east
            for l in range(n + 1 - j, n + 1):
                C[l - 2].discard(i)
        w = [0] + [len(c) for c in C]
        return self.from_restricted_growth_word_blocks(w)

    def from_rook_placement_rho(self, rooks, n):
        r"""
        Return the set partition of `\{1,...,n\}` corresponding to the
        given rook placement by applying Wachs and White's bijection
        rho.

        Note that our index convention differs from the convention in
        [WW1991]_: regarding the rook board as a lower-right
        triangular grid, we refer with `(i,j)` to the cell in the
        `i`-th column from the right and the `j`-th row from the top.

        INPUT:

        - ``n`` -- integer specifying the size of the set
          partition to be produced

        - ``rooks`` -- list of pairs `(i,j)` such that `0 < i < j < n+1`

        OUTPUT: a set partition

        .. SEEALSO::

            - :meth:`from_rook_placement`
            - :meth:`SetPartition.to_rook_placement`
            - :meth:`SetPartition.to_rook_placement_rho`

        EXAMPLES:

        Figure 5 in [WW1991]_ concerns the following rook placement::

            sage: r = [(1, 2), (2, 6), (3, 4), (4, 10), (5, 9), (6, 7), (10, 11), (11, 13)]

        Note that the rook `(1, 2)`, translated into Wachs and
        White's convention, is a rook in row 2 from the top and
        column 13 from the left.  The corresponding set partition
        is::

            sage: SetPartitions().from_rook_placement_rho(r, 13)
            {{1, 2, 4, 7}, {3, 9}, {5, 6, 10, 11, 13}, {8}, {12}}
        """
        # the closers correspond to the empty columns
        cols = [j for j, _ in rooks]
        R = [j for j in range(1, n + 1) if j not in cols]
        # the columns of the board, beginning with column n-1
        C = [set(range(n + 1 - j, n + 1)) if n - j not in R else set()
             for j in range(1, n)]
        for j, i in rooks:  # column j from right, row i from top
            # south
            C[n - j - 1].difference_update(range(i, n + 1))
            # east
            for l in range(n + 1 - j, n + 1):
                C[l - 2].discard(i)

        C_flat = [i for c in C for i in c]
        # the number of closers which are larger than i and whose
        # block is before the block of i
        rs = [C_flat.count(i) for i in range(1, n + 1)]
        # create the blocks
        P = [[] for _ in R]
        for i in range(1, n + 1):
            k = rs[i - 1]
            # find k-th block which does not yet have a closer
            b = 0
            while k > 0 or (P[b] and P[b][-1] in R):
                if P[b][-1] not in R:
                    k -= 1
                b += 1
            P[b].append(i)
        return self.element_class(self, P)

    def from_rook_placement_psi(self, rooks, n):
        r"""
        Return the set partition of `\{1,...,n\}` corresponding to the
        given rook placement by applying Yip's bijection psi.

        INPUT:

        - ``n`` -- integer specifying the size of the set
          partition to be produced

        - ``rooks`` -- list of pairs `(i,j)` such that `0 < i < j < n+1`

        OUTPUT: a set partition

        .. SEEALSO::

            - :meth:`from_rook_placement`
            - :meth:`SetPartition.to_rook_placement`
            - :meth:`SetPartition.to_rook_placement_psi`

        EXAMPLES:

        Example 36 (arXiv version: Example 4.5) in [Yip2018]_
        concerns the following rook placement::

            sage: r = [(4,5), (1,7), (3, 8), (7,9)]
            sage: SetPartitions().from_rook_placement_psi(r, 9)
            {{1, 5}, {2}, {3, 8, 9}, {4}, {6, 7}}
        """
        # Yip draws the diagram as an upper triangular matrix, thus
        # we refer to the cell in row i and column j with (i, j)
        P = []
        rooks_by_column = {j: i for (i, j) in rooks}
        for c in range(1, n + 1):
            # determine the weight of column c
            try:
                r = rooks_by_column[c]
                n_rooks = 1
                ne = r - 1 + sum(1 for i, j in rooks if i > r and j < c)
            except KeyError:
                n_rooks = 0
                ne = sum(1 for i, j in rooks if j < c)

            b = c - n_rooks - ne
            if len(P) == b - 1:
                P.append([c])
            else:
                P[b - 1].append(c)
            P = sorted(P, key=lambda B: (-len(B), min(B)))
        return self.element_class(self, P)

    def is_less_than(self, s, t) -> bool:
        r"""
        Check if `s < t` in the refinement ordering on set partitions.

        This means that `s` is a refinement of `t` and satisfies
        `s \neq t`.

        A set partition `s` is said to be a refinement of a set
        partition `t` of the same set if and only if each part of
        `s` is a subset of a part of `t`.

        EXAMPLES::

            sage: S = SetPartitions(4)
            sage: s = S([[1,3],[2,4]])
            sage: t = S([[1],[2],[3],[4]])
            sage: S.is_less_than(t, s)
            True
            sage: S.is_less_than(s, t)
            False
            sage: S.is_less_than(s, s)
            False
        """
        if hasattr(s.parent(), "_set"):
            S = s.parent()._set
        else:
            S = s.base_set()
        if hasattr(t.parent(), "_set"):
            T = t.parent()._set
        else:
            T = t.base_set()
        if S != T:
            raise ValueError("cannot compare partitions of different sets")

        if s == t:
            return False

        for p in s:
            x = next(iter(p))
            for t_ in t:
                if x in t_:
                    break
            for p_ in p:
                if p_ not in t_:
                    return False
        return True

    lt = is_less_than

    def is_strict_refinement(self, s, t) -> bool:
        r"""
        Return ``True`` if ``s`` is a strict refinement of ``t`` and
        satisfies `s \neq t`.

        A set partition `s` is said to be a strict refinement of a set
        partition `t` of the same set if and only if one can obtain
        `t` from `s` by repeatedly combining pairs of parts whose
        convex hulls don't intersect (i. e., whenever we are combining
        two parts, the maximum of each of them should be smaller than
        the minimum of the other).

        EXAMPLES::

            sage: S = SetPartitions(4)
            sage: s = S([[1],[2],[3],[4]])
            sage: t = S([[1,3],[2,4]])
            sage: u = S([[1,2,3,4]])
            sage: S.is_strict_refinement(s, t)
            True
            sage: S.is_strict_refinement(t, u)
            False
            sage: A = SetPartition([[1,3],[2,4]])
            sage: B = SetPartition([[1,2,3,4]])
            sage: S.is_strict_refinement(s, A)
            True
            sage: S.is_strict_refinement(t, B)
            False
        """
        if hasattr(s.parent(), "_set"):
            S = s.parent()._set
        else:
            S = frozenset(s.base_set())
        if hasattr(t.parent(), "_set"):
            T = t.parent()._set
        else:
            T = frozenset(t.base_set())
        if S != T:
            raise ValueError("cannot compare partitions of different sets")

        if s == t:
            return False

        for p in t:
            L = [x for x in s if x.issubset(p)]
            if sum(len(x) for x in L) != len(p) \
                    or any(max(L[i]) > min(L[i + 1])
                           for i in range(len(L) - 1)):
                return False
        return True


class SetPartitions_all(SetPartitions):
    r"""
    All set partitions.
    """

    def __init__(self):
        """
        Initialize ``self``.

        EXAMPLES::

            sage: S = SetPartitions()
            sage: TestSuite(S).run()
        """
        SetPartitions.__init__(self, category=InfiniteEnumeratedSets())

    def subset(self, size=None, **kwargs):
        """
        Return the subset of set partitions of a given size and
        additional keyword arguments.

        EXAMPLES::

            sage: P = SetPartitions()
            sage: P.subset(4)
            Set partitions of {1, 2, 3, 4}
        """
        if size is None:
            return self
        return SetPartitions(size, **kwargs)

    def _repr_(self):
        """
        Return a string representation of ``self``.

        EXAMPLES::

            sage: SetPartitions()
            Set partitions
        """
        return "Set partitions"

    def __iter__(self):
        """
        Iterate over ``self``.

        EXAMPLES::

            sage: it = SetPartitions().__iter__()
            sage: [next(it) for x in range(10)]
            [{}, {{1}}, {{1, 2}}, {{1}, {2}}, {{1, 2, 3}}, {{1, 2}, {3}},
             {{1, 3}, {2}}, {{1}, {2, 3}}, {{1}, {2}, {3}}, {{1, 2, 3, 4}}]
        """
        n = 0
        while True:
            for x in SetPartitions_set(frozenset(range(1, n + 1))):
                yield self.element_class(self, list(x))
            n += 1


class SetPartitions_set(SetPartitions):
    """
    Set partitions of a fixed set `S`.
    """
    @staticmethod
    def __classcall_private__(cls, s):
        """
        Normalize ``s`` to ensure a unique representation.

        EXAMPLES::

            sage: S1 = SetPartitions(set([2,1,4]))
            sage: S2 = SetPartitions([4,1,2])
            sage: S3 = SetPartitions((1,2,4))
            sage: S1 is S2, S1 is S3
            (True, True)
        """
        return super().__classcall__(cls, frozenset(s))

    def __init__(self, s):
        """
        Initialize ``self``.

        EXAMPLES::

            sage: S = SetPartitions(3)
            sage: TestSuite(S).run()
            sage: SetPartitions(0).list()
            [{}]
            sage: SetPartitions([]).list()
            [{}]
        """
        self._set = s
        SetPartitions.__init__(self, category=FiniteEnumeratedSets())

    def _repr_(self):
        """
        TESTS::

            sage: SetPartitions([1,2,3])
            Set partitions of {1, 2, 3}
        """
        return "Set partitions of %s" % (Set(self._set))

    def __contains__(self, x):
        """
        TESTS::

            sage: S = SetPartitions(4, [2,2])
            sage: all(sp in S for sp in S)                                              # needs sage.graphs sage.rings.finite_rings
            True
            sage: SetPartition([[1,3],[2,4]]) in SetPartitions(3)                       # needs sage.graphs
            False
            sage: SetPartition([[1,3],[2,4]]) in SetPartitions(4, [3,1])                # needs sage.graphs
            False
            sage: SetPartition([[2],[1,3,4]]) in SetPartitions(4, [3,1])                # needs sage.graphs
            True
        """
        # Must pass the general check
        if not SetPartitions.__contains__(self, x):
            return False

        # Make sure that the number of elements match up
        if sum(map(len, x)) != len(self._set):
            return False

        # Make sure that the union of all the sets is the original set
        return Set(e for p in x for e in p) == Set(self._set)

    def random_element(self):
        r"""
        Return a random set partition.

        This is a very naive implementation of Knuths outline in F3B,
        7.2.1.5.

        EXAMPLES::

            sage: S = SetPartitions(10)
            sage: s = S.random_element()                                                # needs sage.symbolic
            sage: s.parent() is S                                                       # needs sage.symbolic
            True
            sage: assert s in S, s                                                      # needs sage.symbolic

            sage: S = SetPartitions(["a", "b", "c"])
            sage: s = S.random_element()                                                # needs sage.symbolic
            sage: s.parent() is S                                                       # needs sage.symbolic
            True
            sage: assert s in S, s                                                      # needs sage.symbolic
        """
        base_set = list(self.base_set())
        N = len(base_set)
        from sage.symbolic.constants import e
        c = float(e) * bell_number(N)
        # it would be much better to generate M in the way Knuth
        # recommends, the following is a waste
        G = GeneralDiscreteDistribution([float(m)**N / (c * factorial(m)) for m in range(4 * N)])
        M = G.get_random_element() - 1
        l = (randint(0, M) for i in range(N))
        p = {}
        for i, b in enumerate(l):
            if b in p:
                p[b].append(base_set[i])
            else:
                p[b] = [base_set[i]]

        return self.element_class(self, p.values(), check=False)

    def cardinality(self):
        """
        Return the number of set partitions of the set `S`.

        The cardinality is given by the `n`-th Bell number where `n` is the
        number of elements in the set `S`.

        EXAMPLES::

            sage: # needs sage.libs.flint
            sage: SetPartitions([1,2,3,4]).cardinality()
            15
            sage: SetPartitions(3).cardinality()
            5
            sage: SetPartitions(3,2).cardinality()
            3
            sage: SetPartitions([]).cardinality()
            1
        """
        return bell_number(len(self._set))

    def __iter__(self):
        """
        Iterate over ``self``.

        EXAMPLES::

            sage: SetPartitions(3).list()
            [{{1, 2, 3}}, {{1, 2}, {3}}, {{1, 3}, {2}}, {{1}, {2, 3}}, {{1}, {2}, {3}}]

            sage: SetPartitions(["a", "b"]).list()
            [{{'a', 'b'}}, {{'a'}, {'b'}}]
        """
        try:
            s = sorted(self._set)
        except TypeError:
            s = sorted(self._set, key=str)
        for sp in set_partition_iterator(s):
            yield self.element_class(self, sp, check=False)

    def base_set(self):
        """
        Return the base set of ``self``.

        EXAMPLES::

            sage: SetPartitions(3).base_set()
            {1, 2, 3}

            sage: sorted(SetPartitions(["a", "b", "c"]).base_set())
            ['a', 'b', 'c']
        """
        return Set(self._set)

    def base_set_cardinality(self):
        """
        Return the cardinality of the base set of ``self``.

        EXAMPLES::

            sage: SetPartitions(3).base_set_cardinality()
            3
        """
        return len(self._set)


class SetPartitions_setparts(SetPartitions_set):
    r"""
    Set partitions with fixed partition sizes corresponding to an
    integer partition `\lambda`.
    """
    @staticmethod
    def __classcall_private__(cls, s, parts):
        """
        Normalize input to ensure a unique representation.

        EXAMPLES::

            sage: S = SetPartitions(4, [2,2])
            sage: T = SetPartitions([1,2,3,4], Partition([2,2]))
            sage: S is T
            True

            sage: S = SetPartitions(4, [3,1])
            sage: T = SetPartitions(4, (1,3))
            sage: S is T
            True
        """
        if isinstance(s, (int, Integer)):
            s = list(range(1, s + 1))
        return super().__classcall__(cls, frozenset(s), Partition(parts))

    def __init__(self, s, parts):
        """
        Initialize the data structure.

        We can assume here that ``parts`` is a :class:`Partition`.

        TESTS::

            sage: S = SetPartitions(4, [2,2])
            sage: TestSuite(S).run()                                                    # needs sage.graphs sage.libs.flint
        """
        SetPartitions_set.__init__(self, s)
        self._parts = parts

    def _repr_(self):
        """
        TESTS::

            sage: SetPartitions(4, [2,2])
            Set partitions of {1, 2, 3, 4} with sizes in [2, 2]
        """
        return "Set partitions of %s with sizes in %s" % (Set(self._set), self._parts)

    def shape(self):
        r"""
        Return the partition of block sizes of the set partitions in ``self``.

        EXAMPLES::

            sage: SetPartitions(5, [2,2,1]).shape()
            [2, 2, 1]
        """
        return self._parts

    def cardinality(self):
        r"""
        Return the cardinality of ``self``.

        This algorithm counts for each block of the partition the
        number of ways to fill it using values from the set.  Then,
        for each distinct value `v` of block size, we divide the result by
        the number of ways to arrange the blocks of size `v` in the
        set partition.

        For example, if we want to count the number of set partitions
        of size 13 having [3,3,3,2,2] as underlying partition we
        compute the number of ways to fill each block of the
        partition, which is `\binom{13}{3} \binom{10}{3} \binom{7}{3}
        \binom{4}{2}\binom{2}{2}` and as we have three blocks of size
        `3` and two blocks of size `2`, we divide the result by
        `3!2!` which gives us `600600`.

        EXAMPLES::

            sage: SetPartitions(3, [2,1]).cardinality()
            3
            sage: SetPartitions(13, Partition([3,3,3,2,2])).cardinality()
            600600

        TESTS::

            sage: all((len(SetPartitions(size, part)) == SetPartitions(size, part).cardinality()
            ....:     for size in range(8) for part in Partitions(size)))
            True
            sage: sum((SetPartitions(13, p).cardinality()                               # needs sage.libs.flint
            ....:     for p in Partitions(13))) == SetPartitions(13).cardinality()
            True
        """
        from sage.misc.misc_c import prod

        remaining_subset_size = Integer(len(self._set))
        cardinal = Integer(1)
        for subset_size in self._parts:
            cardinal *= remaining_subset_size.binomial(subset_size)
            remaining_subset_size -= subset_size

        repetitions = (Integer(rep).factorial()
                       for rep in self._parts.to_exp_dict().values()
                       if rep != 1)
        cardinal /= prod(repetitions)
        return Integer(cardinal)

    def _set_partition_poset(self):
        r"""
        Return the Hasse diagram of a poset whose linear extensions correspond
        to the set partitions with specified block sizes.

        TESTS::

            sage: P = SetPartitions(["a", "b", "c", "d", "e"],                          # needs sage.graphs
            ....:                   [2,2,1])._set_partition_poset()
            sage: P.cover_relations()                                                   # needs sage.graphs
            [(1, 2), (1, 3), (3, 4)]

            sage: n = 9
            sage: all(SetPartitions(n, mu).cardinality() ==                             # needs sage.graphs sage.modules
            ....:     len(list(SetPartitions(n, mu)._set_partition_poset().linear_extensions()))
            ....:     for mu in Partitions(n))
            True
        """
        c = self._parts.to_exp_dict()
        covers = {}
        i = 0
        for s in sorted(c):
            # s is the block size
            # each block is one tree in the poset
            for m in range(c[s]):
                # m is the multiplicity of blocks with size s
                #
                # the first element in each non-final block has an
                # additional cover
                first = i
                if s == 1:
                    covers[i] = []
                else:
                    for _ in range(s - 1):
                        covers[i] = [i + 1]
                        i += 1
                i += 1
                if m < c[s] - 1:
                    covers[first].append(i)
        return HasseDiagram(covers)

    def __iter__(self):
        """
        An iterator for all the set partitions of the given set with
        the given sizes.

        EXAMPLES::

            sage: SetPartitions(3, [2,1]).list()                                        # needs sage.graphs sage.rings.finite_rings
            [{{1}, {2, 3}}, {{1, 2}, {3}}, {{1, 3}, {2}}]

            sage: SetPartitions(["a", "b", "c"], [2,1]).list()                          # needs sage.graphs sage.rings.finite_rings
            [{{'a'}, {'b', 'c'}}, {{'a', 'b'}, {'c'}}, {{'a', 'c'}, {'b'}}]

        TESTS::

            sage: n = 8
            sage: all(SetPartitions(n, mu).cardinality()                                # needs sage.graphs sage.rings.finite_rings
            ....:      == len(list(SetPartitions(n, mu))) for mu in Partitions(n))
            True
        """
        # Ruskey, Combinatorial Generation, sec. 5.10.1 and Knuth TAOCP 4A 7.2.1.5, Exercise 6
        k = len(self._parts)
        n = len(self._set)
        P = self._set_partition_poset()
        try:
            s = sorted(self._set)
        except TypeError:
            s = sorted(self._set, key=str)

        sums = [0]
        for b in sorted(self._parts):
            sums.append(sums[-1] + b)

        for ext in P.linear_extensions():
            pi = [None] * n
            for i in range(n):
                pi[ext[i]] = s[i]
            sp = [[pi[j] for j in range(sums[i], sums[i + 1])]
                  for i in range(k)]
            yield self.element_class(self, sp, check=False)

    def __contains__(self, x):
        """
        Check containment.

        TESTS::

            sage: S = SetPartitions(4, [3,1])
            sage: Set([Set([1,2,3]), Set([4])]) in S
            True
            sage: Set([Set([1,3]), Set([2,4])]) in S
            False
            sage: Set([Set([1,2,3,4])]) in S
            False
        """
        if not SetPartitions_set.__contains__(self, x):
            return False
        return sorted(map(len, x), reverse=True) == self._parts

    def random_element(self):
        r"""
        Return a random set partition of ``self``.

        ALGORITHM:

        Based on the cardinality method. For each block size `k_i`,
        we choose a uniformly random subset `X_i \subseteq S_i` of
        size `k_i` of the elements `S_i` that have not yet been selected.
        Thus, we define `S_{i+1} = S_i \setminus X_i` with `S_i = S`
        being the defining set. This is not yet proven to be uniformly
        distributed, but numerical tests show this is likely uniform.

        EXAMPLES::

            sage: S = SetPartitions(10, [4,3,2,1])
            sage: s = S.random_element()
            sage: s.parent() is S
            True
            sage: assert s in S, s

            sage: S = SetPartitions(["a", "b", "c", "d"], [2,2])
            sage: s = S.random_element()
            sage: s.parent() is S
            True
            sage: assert s in S, s
        """
        base_set = list(self.base_set())
        N = len(base_set)
        ret = []
        for p in self._parts:
            X = sample(range(N), p)
            ret.append([base_set[i] for i in X])
            for i in sorted(X, reverse=True):
                del base_set[i]
            N -= p

        return self.element_class(self, ret, check=False)


class SetPartitions_setn(SetPartitions_set):
    """
    Set partitions with a given number of blocks.
    """
    @staticmethod
    def __classcall_private__(cls, s, k):
        """
        Normalize ``s`` to ensure a unique representation.

        EXAMPLES::

            sage: S1 = SetPartitions(set([2,1,4]), 2)
            sage: S2 = SetPartitions([4,1,2], 2)
            sage: S3 = SetPartitions((1,2,4), 2)
            sage: S1 is S2, S1 is S3
            (True, True)
        """
        return super().__classcall__(cls, frozenset(s), k)

    def __init__(self, s, k):
        """
        TESTS::

            sage: S = SetPartitions(5, 3)
            sage: TestSuite(S).run()
        """
        self._k = k
        SetPartitions_set.__init__(self, s)

    def _repr_(self):
        """
        TESTS::

            sage: SetPartitions(5, 3)
            Set partitions of {1, 2, 3, 4, 5} with 3 parts
        """
        return "Set partitions of %s with %s parts" % (Set(self._set), self._k)

    def number_of_blocks(self):
        r"""
        Return the number of blocks of the set partitions in ``self``.

        EXAMPLES::

            sage: SetPartitions(5, 3).number_of_blocks()
            3
        """
        return self._k

    def cardinality(self):
        """
        The Stirling number of the second kind is the number of partitions
        of a set of size `n` into `k` blocks.

        EXAMPLES::

            sage: SetPartitions(5, 3).cardinality()
            25
            sage: stirling_number2(5,3)
            25
        """
        return stirling2(len(self._set), self._k)

    def __iter__(self):
        """
        Iterate over ``self``.

        EXAMPLES::

            sage: SetPartitions(4, 2).list()
            [{{1, 3, 4}, {2}},
             {{1, 4}, {2, 3}},
             {{1, 2, 4}, {3}},
             {{1, 3}, {2, 4}},
             {{1}, {2, 3, 4}},
             {{1, 2}, {3, 4}},
             {{1, 2, 3}, {4}}]

            sage: SetPartitions(["a", "b", "c"], 2).list()
            [{{'a', 'c'}, {'b'}}, {{'a'}, {'b', 'c'}}, {{'a', 'b'}, {'c'}}]
        """
        try:
            s = sorted(self._set)
        except TypeError:
            s = sorted(self._set, key=str)
        for sp in set_partition_iterator_blocks(s, self._k):
            yield self.element_class(self, sp, check=False)

    def __contains__(self, x):
        """
        Check containment.

        TESTS::

            sage: S = SetPartitions(4, 2)
            sage: Set([Set([1,2,3]), Set([4])]) in S
            True
            sage: Set([Set([1,3]), Set([2,4])]) in S
            True
            sage: Set([Set([1,2,3,4])]) in S
            False
        """
        if not SetPartitions_set.__contains__(self, x):
            return False
        return len(x) == self._k

    def random_element(self):
        r"""
        Return a random set partition of ``self``.

        See https://mathoverflow.net/questions/141999.

        EXAMPLES::

            sage: S = SetPartitions(10, 4)
            sage: s = S.random_element()
            sage: s.parent() is S
            True
            sage: assert s in S, s

            sage: S = SetPartitions(["a", "b", "c"], 2)
            sage: s = S.random_element()
            sage: s.parent() is S
            True
            sage: assert s in S, s
        """
        def re(N, k):
            if N == 0:
                return [[]]
            if N == 1:
                return [[0]]
            if stirling2(N - 1, k - 1) > random() * stirling2(N, k):
                return [[N - 1]] + re(N - 1, k - 1)

            p = re(N - 1, k)
            p[randint(0, len(p) - 1)].append(N - 1)
            return p

        base_set = list(self.base_set())
        N = len(base_set)
        k = self._k
        p = re(N, k)
        return self.element_class(self, [[base_set[e] for e in b] for b in p], check=False)


def cyclic_permutations_of_set_partition(set_part):
    """
    Return all combinations of cyclic permutations of each cell of the
    set partition.

    AUTHORS:

    - Robert L. Miller

    EXAMPLES::

        sage: from sage.combinat.set_partition import cyclic_permutations_of_set_partition
        sage: cyclic_permutations_of_set_partition([[1,2,3,4],[5,6,7]])
        [[[1, 2, 3, 4], [5, 6, 7]],
         [[1, 2, 4, 3], [5, 6, 7]],
         [[1, 3, 2, 4], [5, 6, 7]],
         [[1, 3, 4, 2], [5, 6, 7]],
         [[1, 4, 2, 3], [5, 6, 7]],
         [[1, 4, 3, 2], [5, 6, 7]],
         [[1, 2, 3, 4], [5, 7, 6]],
         [[1, 2, 4, 3], [5, 7, 6]],
         [[1, 3, 2, 4], [5, 7, 6]],
         [[1, 3, 4, 2], [5, 7, 6]],
         [[1, 4, 2, 3], [5, 7, 6]],
         [[1, 4, 3, 2], [5, 7, 6]]]
    """
    return list(cyclic_permutations_of_set_partition_iterator(set_part))


def cyclic_permutations_of_set_partition_iterator(set_part):
    """
    Iterate over all combinations of cyclic permutations of each cell
    of the set partition.

    AUTHORS:

    - Robert L. Miller

    EXAMPLES::

        sage: from sage.combinat.set_partition import cyclic_permutations_of_set_partition_iterator
        sage: list(cyclic_permutations_of_set_partition_iterator([[1,2,3,4],[5,6,7]]))
        [[[1, 2, 3, 4], [5, 6, 7]],
         [[1, 2, 4, 3], [5, 6, 7]],
         [[1, 3, 2, 4], [5, 6, 7]],
         [[1, 3, 4, 2], [5, 6, 7]],
         [[1, 4, 2, 3], [5, 6, 7]],
         [[1, 4, 3, 2], [5, 6, 7]],
         [[1, 2, 3, 4], [5, 7, 6]],
         [[1, 2, 4, 3], [5, 7, 6]],
         [[1, 3, 2, 4], [5, 7, 6]],
         [[1, 3, 4, 2], [5, 7, 6]],
         [[1, 4, 2, 3], [5, 7, 6]],
         [[1, 4, 3, 2], [5, 7, 6]]]
    """
    from sage.combinat.permutation import CyclicPermutations
    if len(set_part) == 1:
        for i in CyclicPermutations(set_part[0]):
            yield [i]
    else:
        for right in cyclic_permutations_of_set_partition_iterator(set_part[1:]):
            for perm in CyclicPermutations(set_part[0]):
                yield [perm] + right
