Add files using upload-large-folder tool

lib/python3.12/site-packages/sympy/combinatorics/__init__.py

@@ -0,0 +1,43 @@
+from sympy.combinatorics.permutations import Permutation, Cycle
+from sympy.combinatorics.prufer import Prufer
+from sympy.combinatorics.generators import cyclic, alternating, symmetric, dihedral
+from sympy.combinatorics.subsets import Subset
+from sympy.combinatorics.partitions import (Partition, IntegerPartition,
+    RGS_rank, RGS_unrank, RGS_enum)
+from sympy.combinatorics.polyhedron import (Polyhedron, tetrahedron, cube,
+    octahedron, dodecahedron, icosahedron)
+from sympy.combinatorics.perm_groups import PermutationGroup, Coset, SymmetricPermutationGroup
+from sympy.combinatorics.group_constructs import DirectProduct
+from sympy.combinatorics.graycode import GrayCode
+from sympy.combinatorics.named_groups import (SymmetricGroup, DihedralGroup,
+    CyclicGroup, AlternatingGroup, AbelianGroup, RubikGroup)
+from sympy.combinatorics.pc_groups import PolycyclicGroup, Collector
+from sympy.combinatorics.free_groups import free_group
+
+__all__ = [
+    'Permutation', 'Cycle',
+
+    'Prufer',
+
+    'cyclic', 'alternating', 'symmetric', 'dihedral',
+
+    'Subset',
+
+    'Partition', 'IntegerPartition', 'RGS_rank', 'RGS_unrank', 'RGS_enum',
+
+    'Polyhedron', 'tetrahedron', 'cube', 'octahedron', 'dodecahedron',
+    'icosahedron',
+
+    'PermutationGroup', 'Coset', 'SymmetricPermutationGroup',
+
+    'DirectProduct',
+
+    'GrayCode',
+
+    'SymmetricGroup', 'DihedralGroup', 'CyclicGroup', 'AlternatingGroup',
+    'AbelianGroup', 'RubikGroup',
+
+    'PolycyclicGroup', 'Collector',
+
+    'free_group',
+]

lib/python3.12/site-packages/sympy/combinatorics/coset_table.py

@@ -0,0 +1,1255 @@
+from sympy.combinatorics.free_groups import free_group
+from sympy.printing.defaults import DefaultPrinting
+
+from itertools import chain, product
+from bisect import bisect_left
+
+
+###############################################################################
+#                           COSET TABLE                                       #
+###############################################################################
+
+class CosetTable(DefaultPrinting):
+    # coset_table: Mathematically a coset table
+    #               represented using a list of lists
+    # alpha: Mathematically a coset (precisely, a live coset)
+    #       represented by an integer between i with 1 <= i <= n
+    #       alpha in c
+    # x: Mathematically an element of "A" (set of generators and
+    #   their inverses), represented using "FpGroupElement"
+    # fp_grp: Finitely Presented Group with < X|R > as presentation.
+    # H: subgroup of fp_grp.
+    # NOTE: We start with H as being only a list of words in generators
+    #       of "fp_grp". Since `.subgroup` method has not been implemented.
+
+    r"""
+
+    Properties
+    ==========
+
+    [1] `0 \in \Omega` and `\tau(1) = \epsilon`
+    [2] `\alpha^x = \beta \Leftrightarrow \beta^{x^{-1}} = \alpha`
+    [3] If `\alpha^x = \beta`, then `H \tau(\alpha)x = H \tau(\beta)`
+    [4] `\forall \alpha \in \Omega, 1^{\tau(\alpha)} = \alpha`
+
+    References
+    ==========
+
+    .. [1] Holt, D., Eick, B., O'Brien, E.
+           "Handbook of Computational Group Theory"
+
+    .. [2] John J. Cannon; Lucien A. Dimino; George Havas; Jane M. Watson
+           Mathematics of Computation, Vol. 27, No. 123. (Jul., 1973), pp. 463-490.
+           "Implementation and Analysis of the Todd-Coxeter Algorithm"
+
+    """
+    # default limit for the number of cosets allowed in a
+    # coset enumeration.
+    coset_table_max_limit = 4096000
+    # limit for the current instance
+    coset_table_limit = None
+    # maximum size of deduction stack above or equal to
+    # which it is emptied
+    max_stack_size = 100
+
+    def __init__(self, fp_grp, subgroup, max_cosets=None):
+        if not max_cosets:
+            max_cosets = CosetTable.coset_table_max_limit
+        self.fp_group = fp_grp
+        self.subgroup = subgroup
+        self.coset_table_limit = max_cosets
+        # "p" is setup independent of Omega and n
+        self.p = [0]
+        # a list of the form `[gen_1, gen_1^{-1}, ... , gen_k, gen_k^{-1}]`
+        self.A = list(chain.from_iterable((gen, gen**-1) \
+                for gen in self.fp_group.generators))
+        #P[alpha, x] Only defined when alpha^x is defined.
+        self.P = [[None]*len(self.A)]
+        # the mathematical coset table which is a list of lists
+        self.table = [[None]*len(self.A)]
+        self.A_dict = {x: self.A.index(x) for x in self.A}
+        self.A_dict_inv = {}
+        for x, index in self.A_dict.items():
+            if index % 2 == 0:
+                self.A_dict_inv[x] = self.A_dict[x] + 1
+            else:
+                self.A_dict_inv[x] = self.A_dict[x] - 1
+        # used in the coset-table based method of coset enumeration. Each of
+        # the element is called a "deduction" which is the form (alpha, x) whenever
+        # a value is assigned to alpha^x during a definition or "deduction process"
+        self.deduction_stack = []
+        # Attributes for modified methods.
+        H = self.subgroup
+        self._grp = free_group(', ' .join(["a_%d" % i for i in range(len(H))]))[0]
+        self.P = [[None]*len(self.A)]
+        self.p_p = {}
+
+    @property
+    def omega(self):
+        """Set of live cosets. """
+        return [coset for coset in range(len(self.p)) if self.p[coset] == coset]
+
+    def copy(self):
+        """
+        Return a shallow copy of Coset Table instance ``self``.
+
+        """
+        self_copy = self.__class__(self.fp_group, self.subgroup)
+        self_copy.table = [list(perm_rep) for perm_rep in self.table]
+        self_copy.p = list(self.p)
+        self_copy.deduction_stack = list(self.deduction_stack)
+        return self_copy
+
+    def __str__(self):
+        return "Coset Table on %s with %s as subgroup generators" \
+                % (self.fp_group, self.subgroup)
+
+    __repr__ = __str__
+
+    @property
+    def n(self):
+        """The number `n` represents the length of the sublist containing the
+        live cosets.
+
+        """
+        if not self.table:
+            return 0
+        return max(self.omega) + 1
+
+    # Pg. 152 [1]
+    def is_complete(self):
+        r"""
+        The coset table is called complete if it has no undefined entries
+        on the live cosets; that is, `\alpha^x` is defined for all
+        `\alpha \in \Omega` and `x \in A`.
+
+        """
+        return not any(None in self.table[coset] for coset in self.omega)
+
+    # Pg. 153 [1]
+    def define(self, alpha, x, modified=False):
+        r"""
+        This routine is used in the relator-based strategy of Todd-Coxeter
+        algorithm if some `\alpha^x` is undefined. We check whether there is
+        space available for defining a new coset. If there is enough space
+        then we remedy this by adjoining a new coset `\beta` to `\Omega`
+        (i.e to set of live cosets) and put that equal to `\alpha^x`, then
+        make an assignment satisfying Property[1]. If there is not enough space
+        then we halt the Coset Table creation. The maximum amount of space that
+        can be used by Coset Table can be manipulated using the class variable
+        ``CosetTable.coset_table_max_limit``.
+
+        See Also
+        ========
+
+        define_c
+
+        """
+        A = self.A
+        table = self.table
+        len_table = len(table)
+        if len_table >= self.coset_table_limit:
+            # abort the further generation of cosets
+            raise ValueError("the coset enumeration has defined more than "
+                    "%s cosets. Try with a greater value max number of cosets "
+                    % self.coset_table_limit)
+        table.append([None]*len(A))
+        self.P.append([None]*len(self.A))
+        # beta is the new coset generated
+        beta = len_table
+        self.p.append(beta)
+        table[alpha][self.A_dict[x]] = beta
+        table[beta][self.A_dict_inv[x]] = alpha
+        # P[alpha][x] = epsilon, P[beta][x**-1] = epsilon
+        if modified:
+            self.P[alpha][self.A_dict[x]] = self._grp.identity
+            self.P[beta][self.A_dict_inv[x]] = self._grp.identity
+            self.p_p[beta] = self._grp.identity
+
+    def define_c(self, alpha, x):
+        r"""
+        A variation of ``define`` routine, described on Pg. 165 [1], used in
+        the coset table-based strategy of Todd-Coxeter algorithm. It differs
+        from ``define`` routine in that for each definition it also adds the
+        tuple `(\alpha, x)` to the deduction stack.
+
+        See Also
+        ========
+
+        define
+
+        """
+        A = self.A
+        table = self.table
+        len_table = len(table)
+        if len_table >= self.coset_table_limit:
+            # abort the further generation of cosets
+            raise ValueError("the coset enumeration has defined more than "
+                    "%s cosets. Try with a greater value max number of cosets "
+                    % self.coset_table_limit)
+        table.append([None]*len(A))
+        # beta is the new coset generated
+        beta = len_table
+        self.p.append(beta)
+        table[alpha][self.A_dict[x]] = beta
+        table[beta][self.A_dict_inv[x]] = alpha
+        # append to deduction stack
+        self.deduction_stack.append((alpha, x))
+
+    def scan_c(self, alpha, word):
+        """
+        A variation of ``scan`` routine, described on pg. 165 of [1], which
+        puts at tuple, whenever a deduction occurs, to deduction stack.
+
+        See Also
+        ========
+
+        scan, scan_check, scan_and_fill, scan_and_fill_c
+
+        """
+        # alpha is an integer representing a "coset"
+        # since scanning can be in two cases
+        # 1. for alpha=0 and w in Y (i.e generating set of H)
+        # 2. alpha in Omega (set of live cosets), w in R (relators)
+        A_dict = self.A_dict
+        A_dict_inv = self.A_dict_inv
+        table = self.table
+        f = alpha
+        i = 0
+        r = len(word)
+        b = alpha
+        j = r - 1
+        # list of union of generators and their inverses
+        while i <= j and table[f][A_dict[word[i]]] is not None:
+            f = table[f][A_dict[word[i]]]
+            i += 1
+        if i > j:
+            if f != b:
+                self.coincidence_c(f, b)
+            return
+        while j >= i and table[b][A_dict_inv[word[j]]] is not None:
+            b = table[b][A_dict_inv[word[j]]]
+            j -= 1
+        if j < i:
+            # we have an incorrect completed scan with coincidence f ~ b
+            # run the "coincidence" routine
+            self.coincidence_c(f, b)
+        elif j == i:
+            # deduction process
+            table[f][A_dict[word[i]]] = b
+            table[b][A_dict_inv[word[i]]] = f
+            self.deduction_stack.append((f, word[i]))
+        # otherwise scan is incomplete and yields no information
+
+    # alpha, beta coincide, i.e. alpha, beta represent the pair of cosets where
+    # coincidence occurs
+    def coincidence_c(self, alpha, beta):
+        """
+        A variation of ``coincidence`` routine used in the coset-table based
+        method of coset enumeration. The only difference being on addition of
+        a new coset in coset table(i.e new coset introduction), then it is
+        appended to ``deduction_stack``.
+
+        See Also
+        ========
+
+        coincidence
+
+        """
+        A_dict = self.A_dict
+        A_dict_inv = self.A_dict_inv
+        table = self.table
+        # behaves as a queue
+        q = []
+        self.merge(alpha, beta, q)
+        while len(q) > 0:
+            gamma = q.pop(0)
+            for x in A_dict:
+                delta = table[gamma][A_dict[x]]
+                if delta is not None:
+                    table[delta][A_dict_inv[x]] = None
+                    # only line of difference from ``coincidence`` routine
+                    self.deduction_stack.append((delta, x**-1))
+                    mu = self.rep(gamma)
+                    nu = self.rep(delta)
+                    if table[mu][A_dict[x]] is not None:
+                        self.merge(nu, table[mu][A_dict[x]], q)
+                    elif table[nu][A_dict_inv[x]] is not None:
+                        self.merge(mu, table[nu][A_dict_inv[x]], q)
+                    else:
+                        table[mu][A_dict[x]] = nu
+                        table[nu][A_dict_inv[x]] = mu
+
+    def scan(self, alpha, word, y=None, fill=False, modified=False):
+        r"""
+        ``scan`` performs a scanning process on the input ``word``.
+        It first locates the largest prefix ``s`` of ``word`` for which
+        `\alpha^s` is defined (i.e is not ``None``), ``s`` may be empty. Let
+        ``word=sv``, let ``t`` be the longest suffix of ``v`` for which
+        `\alpha^{t^{-1}}` is defined, and let ``v=ut``. Then three
+        possibilities are there:
+
+        1. If ``t=v``, then we say that the scan completes, and if, in addition
+        `\alpha^s = \alpha^{t^{-1}}`, then we say that the scan completes
+        correctly.
+
+        2. It can also happen that scan does not complete, but `|u|=1`; that
+        is, the word ``u`` consists of a single generator `x \in A`. In that
+        case, if `\alpha^s = \beta` and `\alpha^{t^{-1}} = \gamma`, then we can
+        set `\beta^x = \gamma` and `\gamma^{x^{-1}} = \beta`. These assignments
+        are known as deductions and enable the scan to complete correctly.
+
+        3. See ``coicidence`` routine for explanation of third condition.
+
+        Notes
+        =====
+
+        The code for the procedure of scanning `\alpha \in \Omega`
+        under `w \in A*` is defined on pg. 155 [1]
+
+        See Also
+        ========
+
+        scan_c, scan_check, scan_and_fill, scan_and_fill_c
+
+        Scan and Fill
+        =============
+
+        Performed when the default argument fill=True.
+
+        Modified Scan
+        =============
+
+        Performed when the default argument modified=True
+
+        """
+        # alpha is an integer representing a "coset"
+        # since scanning can be in two cases
+        # 1. for alpha=0 and w in Y (i.e generating set of H)
+        # 2. alpha in Omega (set of live cosets), w in R (relators)
+        A_dict = self.A_dict
+        A_dict_inv = self.A_dict_inv
+        table = self.table
+        f = alpha
+        i = 0
+        r = len(word)
+        b = alpha
+        j = r - 1
+        b_p = y
+        if modified:
+            f_p = self._grp.identity
+        flag = 0
+        while fill or flag == 0:
+            flag = 1
+            while i <= j and table[f][A_dict[word[i]]] is not None:
+                if modified:
+                    f_p = f_p*self.P[f][A_dict[word[i]]]
+                f = table[f][A_dict[word[i]]]
+                i += 1
+            if i > j:
+                if f != b:
+                    if modified:
+                        self.modified_coincidence(f, b, f_p**-1*y)
+                    else:
+                        self.coincidence(f, b)
+                return
+            while j >= i and table[b][A_dict_inv[word[j]]] is not None:
+                if modified:
+                    b_p = b_p*self.P[b][self.A_dict_inv[word[j]]]
+                b = table[b][A_dict_inv[word[j]]]
+                j -= 1
+            if j < i:
+                # we have an incorrect completed scan with coincidence f ~ b
+                # run the "coincidence" routine
+                if modified:
+                    self.modified_coincidence(f, b, f_p**-1*b_p)
+                else:
+                    self.coincidence(f, b)
+            elif j == i:
+                # deduction process
+                table[f][A_dict[word[i]]] = b
+                table[b][A_dict_inv[word[i]]] = f
+                if modified:
+                    self.P[f][self.A_dict[word[i]]] = f_p**-1*b_p
+                    self.P[b][self.A_dict_inv[word[i]]] = b_p**-1*f_p
+                return
+            elif fill:
+                self.define(f, word[i], modified=modified)
+            # otherwise scan is incomplete and yields no information
+
+    # used in the low-index subgroups algorithm
+    def scan_check(self, alpha, word):
+        r"""
+        Another version of ``scan`` routine, described on, it checks whether
+        `\alpha` scans correctly under `word`, it is a straightforward
+        modification of ``scan``. ``scan_check`` returns ``False`` (rather than
+        calling ``coincidence``) if the scan completes incorrectly; otherwise
+        it returns ``True``.
+
+        See Also
+        ========
+
+        scan, scan_c, scan_and_fill, scan_and_fill_c
+
+        """
+        # alpha is an integer representing a "coset"
+        # since scanning can be in two cases
+        # 1. for alpha=0 and w in Y (i.e generating set of H)
+        # 2. alpha in Omega (set of live cosets), w in R (relators)
+        A_dict = self.A_dict
+        A_dict_inv = self.A_dict_inv
+        table = self.table
+        f = alpha
+        i = 0
+        r = len(word)
+        b = alpha
+        j = r - 1
+        while i <= j and table[f][A_dict[word[i]]] is not None:
+            f = table[f][A_dict[word[i]]]
+            i += 1
+        if i > j:
+            return f == b
+        while j >= i and table[b][A_dict_inv[word[j]]] is not None:
+            b = table[b][A_dict_inv[word[j]]]
+            j -= 1
+        if j < i:
+            # we have an incorrect completed scan with coincidence f ~ b
+            # return False, instead of calling coincidence routine
+            return False
+        elif j == i:
+            # deduction process
+            table[f][A_dict[word[i]]] = b
+            table[b][A_dict_inv[word[i]]] = f
+        return True
+
+    def merge(self, k, lamda, q, w=None, modified=False):
+        """
+        Merge two classes with representatives ``k`` and ``lamda``, described
+        on Pg. 157 [1] (for pseudocode), start by putting ``p[k] = lamda``.
+        It is more efficient to choose the new representative from the larger
+        of the two classes being merged, i.e larger among ``k`` and ``lamda``.
+        procedure ``merge`` performs the merging operation, adds the deleted
+        class representative to the queue ``q``.
+
+        Parameters
+        ==========
+
+        'k', 'lamda' being the two class representatives to be merged.
+
+        Notes
+        =====
+
+        Pg. 86-87 [1] contains a description of this method.
+
+        See Also
+        ========
+
+        coincidence, rep
+
+        """
+        p = self.p
+        rep = self.rep
+        phi = rep(k, modified=modified)
+        psi = rep(lamda, modified=modified)
+        if phi != psi:
+            mu = min(phi, psi)
+            v = max(phi, psi)
+            p[v] = mu
+            if modified:
+                if v == phi:
+                    self.p_p[phi] = self.p_p[k]**-1*w*self.p_p[lamda]
+                else:
+                    self.p_p[psi] = self.p_p[lamda]**-1*w**-1*self.p_p[k]
+            q.append(v)
+
+    def rep(self, k, modified=False):
+        r"""
+        Parameters
+        ==========
+
+        `k \in [0 \ldots n-1]`, as for ``self`` only array ``p`` is used
+
+        Returns
+        =======
+
+        Representative of the class containing ``k``.
+
+        Returns the representative of `\sim` class containing ``k``, it also
+        makes some modification to array ``p`` of ``self`` to ease further
+        computations, described on Pg. 157 [1].
+
+        The information on classes under `\sim` is stored in array `p` of
+        ``self`` argument, which will always satisfy the property:
+
+        `p[\alpha] \sim \alpha` and `p[\alpha]=\alpha \iff \alpha=rep(\alpha)`
+        `\forall \in [0 \ldots n-1]`.
+
+        So, for `\alpha \in [0 \ldots n-1]`, we find `rep(self, \alpha)` by
+        continually replacing `\alpha` by `p[\alpha]` until it becomes
+        constant (i.e satisfies `p[\alpha] = \alpha`):w
+
+        To increase the efficiency of later ``rep`` calculations, whenever we
+        find `rep(self, \alpha)=\beta`, we set
+        `p[\gamma] = \beta \forall \gamma \in p-chain` from `\alpha` to `\beta`
+
+        Notes
+        =====
+
+        ``rep`` routine is also described on Pg. 85-87 [1] in Atkinson's
+        algorithm, this results from the fact that ``coincidence`` routine
+        introduces functionality similar to that introduced by the
+        ``minimal_block`` routine on Pg. 85-87 [1].
+
+        See Also
+        ========
+
+        coincidence, merge
+
+        """
+        p = self.p
+        lamda = k
+        rho = p[lamda]
+        if modified:
+            s = p[:]
+        while rho != lamda:
+            if modified:
+                s[rho] = lamda
+            lamda = rho
+            rho = p[lamda]
+        if modified:
+            rho = s[lamda]
+            while rho != k:
+                mu = rho
+                rho = s[mu]
+                p[rho] = lamda
+                self.p_p[rho] = self.p_p[rho]*self.p_p[mu]
+        else:
+            mu = k
+            rho = p[mu]
+            while rho != lamda:
+                p[mu] = lamda
+                mu = rho
+                rho = p[mu]
+        return lamda
+
+    # alpha, beta coincide, i.e. alpha, beta represent the pair of cosets
+    # where coincidence occurs
+    def coincidence(self, alpha, beta, w=None, modified=False):
+        r"""
+        The third situation described in ``scan`` routine is handled by this
+        routine, described on Pg. 156-161 [1].
+
+        The unfortunate situation when the scan completes but not correctly,
+        then ``coincidence`` routine is run. i.e when for some `i` with
+        `1 \le i \le r+1`, we have `w=st` with `s = x_1 x_2 \dots x_{i-1}`,
+        `t = x_i x_{i+1} \dots x_r`, and `\beta = \alpha^s` and
+        `\gamma = \alpha^{t-1}` are defined but unequal. This means that
+        `\beta` and `\gamma` represent the same coset of `H` in `G`. Described
+        on Pg. 156 [1]. ``rep``
+
+        See Also
+        ========
+
+        scan
+
+        """
+        A_dict = self.A_dict
+        A_dict_inv = self.A_dict_inv
+        table = self.table
+        # behaves as a queue
+        q = []
+        if modified:
+            self.modified_merge(alpha, beta, w, q)
+        else:
+            self.merge(alpha, beta, q)
+        while len(q) > 0:
+            gamma = q.pop(0)
+            for x in A_dict:
+                delta = table[gamma][A_dict[x]]
+                if delta is not None:
+                    table[delta][A_dict_inv[x]] = None
+                    mu = self.rep(gamma, modified=modified)
+                    nu = self.rep(delta, modified=modified)
+                    if table[mu][A_dict[x]] is not None:
+                        if modified:
+                            v = self.p_p[delta]**-1*self.P[gamma][self.A_dict[x]]**-1
+                            v = v*self.p_p[gamma]*self.P[mu][self.A_dict[x]]
+                            self.modified_merge(nu, table[mu][self.A_dict[x]], v, q)
+                        else:
+                            self.merge(nu, table[mu][A_dict[x]], q)
+                    elif table[nu][A_dict_inv[x]] is not None:
+                        if modified:
+                            v = self.p_p[gamma]**-1*self.P[gamma][self.A_dict[x]]
+                            v = v*self.p_p[delta]*self.P[mu][self.A_dict_inv[x]]
+                            self.modified_merge(mu, table[nu][self.A_dict_inv[x]], v, q)
+                        else:
+                            self.merge(mu, table[nu][A_dict_inv[x]], q)
+                    else:
+                        table[mu][A_dict[x]] = nu
+                        table[nu][A_dict_inv[x]] = mu
+                        if modified:
+                            v = self.p_p[gamma]**-1*self.P[gamma][self.A_dict[x]]*self.p_p[delta]
+                            self.P[mu][self.A_dict[x]] = v
+                            self.P[nu][self.A_dict_inv[x]] = v**-1
+
+    # method used in the HLT strategy
+    def scan_and_fill(self, alpha, word):
+        """
+        A modified version of ``scan`` routine used in the relator-based
+        method of coset enumeration, described on pg. 162-163 [1], which
+        follows the idea that whenever the procedure is called and the scan
+        is incomplete then it makes new definitions to enable the scan to
+        complete; i.e it fills in the gaps in the scan of the relator or
+        subgroup generator.
+
+        """
+        self.scan(alpha, word, fill=True)
+
+    def scan_and_fill_c(self, alpha, word):
+        """
+        A modified version of ``scan`` routine, described on Pg. 165 second
+        para. [1], with modification similar to that of ``scan_anf_fill`` the
+        only difference being it calls the coincidence procedure used in the
+        coset-table based method i.e. the routine ``coincidence_c`` is used.
+
+        See Also
+        ========
+
+        scan, scan_and_fill
+
+        """
+        A_dict = self.A_dict
+        A_dict_inv = self.A_dict_inv
+        table = self.table
+        r = len(word)
+        f = alpha
+        i = 0
+        b = alpha
+        j = r - 1
+        # loop until it has filled the alpha row in the table.
+        while True:
+            # do the forward scanning
+            while i <= j and table[f][A_dict[word[i]]] is not None:
+                f = table[f][A_dict[word[i]]]
+                i += 1
+            if i > j:
+                if f != b:
+                    self.coincidence_c(f, b)
+                return
+            # forward scan was incomplete, scan backwards
+            while j >= i and table[b][A_dict_inv[word[j]]] is not None:
+                b = table[b][A_dict_inv[word[j]]]
+                j -= 1
+            if j < i:
+                self.coincidence_c(f, b)
+            elif j == i:
+                table[f][A_dict[word[i]]] = b
+                table[b][A_dict_inv[word[i]]] = f
+                self.deduction_stack.append((f, word[i]))
+            else:
+                self.define_c(f, word[i])
+
+    # method used in the HLT strategy
+    def look_ahead(self):
+        """
+        When combined with the HLT method this is known as HLT+Lookahead
+        method of coset enumeration, described on pg. 164 [1]. Whenever
+        ``define`` aborts due to lack of space available this procedure is
+        executed. This routine helps in recovering space resulting from
+        "coincidence" of cosets.
+
+        """
+        R = self.fp_group.relators
+        p = self.p
+        # complete scan all relators under all cosets(obviously live)
+        # without making new definitions
+        for beta in self.omega:
+            for w in R:
+                self.scan(beta, w)
+                if p[beta] < beta:
+                    break
+
+    # Pg. 166
+    def process_deductions(self, R_c_x, R_c_x_inv):
+        """
+        Processes the deductions that have been pushed onto ``deduction_stack``,
+        described on Pg. 166 [1] and is used in coset-table based enumeration.
+
+        See Also
+        ========
+
+        deduction_stack
+
+        """
+        p = self.p
+        table = self.table
+        while len(self.deduction_stack) > 0:
+            if len(self.deduction_stack) >= CosetTable.max_stack_size:
+                self.look_ahead()
+                del self.deduction_stack[:]
+                continue
+            else:
+                alpha, x = self.deduction_stack.pop()
+                if p[alpha] == alpha:
+                    for w in R_c_x:
+                        self.scan_c(alpha, w)
+                        if p[alpha] < alpha:
+                            break
+            beta = table[alpha][self.A_dict[x]]
+            if beta is not None and p[beta] == beta:
+                for w in R_c_x_inv:
+                    self.scan_c(beta, w)
+                    if p[beta] < beta:
+                        break
+
+    def process_deductions_check(self, R_c_x, R_c_x_inv):
+        """
+        A variation of ``process_deductions``, this calls ``scan_check``
+        wherever ``process_deductions`` calls ``scan``, described on Pg. [1].
+
+        See Also
+        ========
+
+        process_deductions
+
+        """
+        table = self.table
+        while len(self.deduction_stack) > 0:
+            alpha, x = self.deduction_stack.pop()
+            for w in R_c_x:
+                if not self.scan_check(alpha, w):
+                    return False
+            beta = table[alpha][self.A_dict[x]]
+            if beta is not None:
+                for w in R_c_x_inv:
+                    if not self.scan_check(beta, w):
+                        return False
+        return True
+
+    def switch(self, beta, gamma):
+        r"""Switch the elements `\beta, \gamma \in \Omega` of ``self``, used
+        by the ``standardize`` procedure, described on Pg. 167 [1].
+
+        See Also
+        ========
+
+        standardize
+
+        """
+        A = self.A
+        A_dict = self.A_dict
+        table = self.table
+        for x in A:
+            z = table[gamma][A_dict[x]]
+            table[gamma][A_dict[x]] = table[beta][A_dict[x]]
+            table[beta][A_dict[x]] = z
+            for alpha in range(len(self.p)):
+                if self.p[alpha] == alpha:
+                    if table[alpha][A_dict[x]] == beta:
+                        table[alpha][A_dict[x]] = gamma
+                    elif table[alpha][A_dict[x]] == gamma:
+                        table[alpha][A_dict[x]] = beta
+
+    def standardize(self):
+        r"""
+        A coset table is standardized if when running through the cosets and
+        within each coset through the generator images (ignoring generator
+        inverses), the cosets appear in order of the integers
+        `0, 1, \dots, n`. "Standardize" reorders the elements of `\Omega`
+        such that, if we scan the coset table first by elements of `\Omega`
+        and then by elements of A, then the cosets occur in ascending order.
+        ``standardize()`` is used at the end of an enumeration to permute the
+        cosets so that they occur in some sort of standard order.
+
+        Notes
+        =====
+
+        procedure is described on pg. 167-168 [1], it also makes use of the
+        ``switch`` routine to replace by smaller integer value.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> from sympy.combinatorics.fp_groups import FpGroup, coset_enumeration_r
+        >>> F, x, y = free_group("x, y")
+
+        # Example 5.3 from [1]
+        >>> f = FpGroup(F, [x**2*y**2, x**3*y**5])
+        >>> C = coset_enumeration_r(f, [])
+        >>> C.compress()
+        >>> C.table
+        [[1, 3, 1, 3], [2, 0, 2, 0], [3, 1, 3, 1], [0, 2, 0, 2]]
+        >>> C.standardize()
+        >>> C.table
+        [[1, 2, 1, 2], [3, 0, 3, 0], [0, 3, 0, 3], [2, 1, 2, 1]]
+
+        """
+        A = self.A
+        A_dict = self.A_dict
+        gamma = 1
+        for alpha, x in product(range(self.n), A):
+            beta = self.table[alpha][A_dict[x]]
+            if beta >= gamma:
+                if beta > gamma:
+                    self.switch(gamma, beta)
+                gamma += 1
+                if gamma == self.n:
+                    return
+
+    # Compression of a Coset Table
+    def compress(self):
+        """Removes the non-live cosets from the coset table, described on
+        pg. 167 [1].
+
+        """
+        gamma = -1
+        A = self.A
+        A_dict = self.A_dict
+        A_dict_inv = self.A_dict_inv
+        table = self.table
+        chi = tuple([i for i in range(len(self.p)) if self.p[i] != i])
+        for alpha in self.omega:
+            gamma += 1
+            if gamma != alpha:
+                # replace alpha by gamma in coset table
+                for x in A:
+                    beta = table[alpha][A_dict[x]]
+                    table[gamma][A_dict[x]] = beta
+                    table[beta][A_dict_inv[x]] == gamma
+        # all the cosets in the table are live cosets
+        self.p = list(range(gamma + 1))
+        # delete the useless columns
+        del table[len(self.p):]
+        # re-define values
+        for row in table:
+            for j in range(len(self.A)):
+                row[j] -= bisect_left(chi, row[j])
+
+    def conjugates(self, R):
+        R_c = list(chain.from_iterable((rel.cyclic_conjugates(), \
+                (rel**-1).cyclic_conjugates()) for rel in R))
+        R_set = set()
+        for conjugate in R_c:
+            R_set = R_set.union(conjugate)
+        R_c_list = []
+        for x in self.A:
+            r = {word for word in R_set if word[0] == x}
+            R_c_list.append(r)
+            R_set.difference_update(r)
+        return R_c_list
+
+    def coset_representative(self, coset):
+        '''
+        Compute the coset representative of a given coset.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> from sympy.combinatorics.fp_groups import FpGroup, coset_enumeration_r
+        >>> F, x, y = free_group("x, y")
+        >>> f = FpGroup(F, [x**3, y**3, x**-1*y**-1*x*y])
+        >>> C = coset_enumeration_r(f, [x])
+        >>> C.compress()
+        >>> C.table
+        [[0, 0, 1, 2], [1, 1, 2, 0], [2, 2, 0, 1]]
+        >>> C.coset_representative(0)
+        <identity>
+        >>> C.coset_representative(1)
+        y
+        >>> C.coset_representative(2)
+        y**-1
+
+        '''
+        for x in self.A:
+            gamma = self.table[coset][self.A_dict[x]]
+            if coset == 0:
+                return self.fp_group.identity
+            if gamma < coset:
+                return self.coset_representative(gamma)*x**-1
+
+    ##############################
+    #      Modified Methods      #
+    ##############################
+
+    def modified_define(self, alpha, x):
+        r"""
+        Define a function p_p from from [1..n] to A* as
+        an additional component of the modified coset table.
+
+        Parameters
+        ==========
+
+        \alpha \in \Omega
+        x \in A*
+
+        See Also
+        ========
+
+        define
+
+        """
+        self.define(alpha, x, modified=True)
+
+    def modified_scan(self, alpha, w, y, fill=False):
+        r"""
+        Parameters
+        ==========
+        \alpha \in \Omega
+        w \in A*
+        y \in (YUY^-1)
+        fill -- `modified_scan_and_fill` when set to True.
+
+        See Also
+        ========
+
+        scan
+        """
+        self.scan(alpha, w, y=y, fill=fill, modified=True)
+
+    def modified_scan_and_fill(self, alpha, w, y):
+        self.modified_scan(alpha, w, y, fill=True)
+
+    def modified_merge(self, k, lamda, w, q):
+        r"""
+        Parameters
+        ==========
+
+        'k', 'lamda' -- the two class representatives to be merged.
+        q -- queue of length l of elements to be deleted from `\Omega` *.
+        w -- Word in (YUY^-1)
+
+        See Also
+        ========
+
+        merge
+        """
+        self.merge(k, lamda, q, w=w, modified=True)
+
+    def modified_rep(self, k):
+        r"""
+        Parameters
+        ==========
+
+        `k \in [0 \ldots n-1]`
+
+        See Also
+        ========
+
+        rep
+        """
+        self.rep(k, modified=True)
+
+    def modified_coincidence(self, alpha, beta, w):
+        r"""
+        Parameters
+        ==========
+
+        A coincident pair `\alpha, \beta \in \Omega, w \in Y \cup Y^{-1}`
+
+        See Also
+        ========
+
+        coincidence
+
+        """
+        self.coincidence(alpha, beta, w=w, modified=True)
+
+###############################################################################
+#                           COSET ENUMERATION                                 #
+###############################################################################
+
+# relator-based method
+def coset_enumeration_r(fp_grp, Y, max_cosets=None, draft=None,
+                                    incomplete=False, modified=False):
+    """
+    This is easier of the two implemented methods of coset enumeration.
+    and is often called the HLT method, after Hazelgrove, Leech, Trotter
+    The idea is that we make use of ``scan_and_fill`` makes new definitions
+    whenever the scan is incomplete to enable the scan to complete; this way
+    we fill in the gaps in the scan of the relator or subgroup generator,
+    that's why the name relator-based method.
+
+    An instance of `CosetTable` for `fp_grp` can be passed as the keyword
+    argument `draft` in which case the coset enumeration will start with
+    that instance and attempt to complete it.
+
+    When `incomplete` is `True` and the function is unable to complete for
+    some reason, the partially complete table will be returned.
+
+    # TODO: complete the docstring
+
+    See Also
+    ========
+
+    scan_and_fill,
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.free_groups import free_group
+    >>> from sympy.combinatorics.fp_groups import FpGroup, coset_enumeration_r
+    >>> F, x, y = free_group("x, y")
+
+    # Example 5.1 from [1]
+    >>> f = FpGroup(F, [x**3, y**3, x**-1*y**-1*x*y])
+    >>> C = coset_enumeration_r(f, [x])
+    >>> for i in range(len(C.p)):
+    ...     if C.p[i] == i:
+    ...         print(C.table[i])
+    [0, 0, 1, 2]
+    [1, 1, 2, 0]
+    [2, 2, 0, 1]
+    >>> C.p
+    [0, 1, 2, 1, 1]
+
+    # Example from exercises Q2 [1]
+    >>> f = FpGroup(F, [x**2*y**2, y**-1*x*y*x**-3])
+    >>> C = coset_enumeration_r(f, [])
+    >>> C.compress(); C.standardize()
+    >>> C.table
+    [[1, 2, 3, 4],
+    [5, 0, 6, 7],
+    [0, 5, 7, 6],
+    [7, 6, 5, 0],
+    [6, 7, 0, 5],
+    [2, 1, 4, 3],
+    [3, 4, 2, 1],
+    [4, 3, 1, 2]]
+
+    # Example 5.2
+    >>> f = FpGroup(F, [x**2, y**3, (x*y)**3])
+    >>> Y = [x*y]
+    >>> C = coset_enumeration_r(f, Y)
+    >>> for i in range(len(C.p)):
+    ...     if C.p[i] == i:
+    ...         print(C.table[i])
+    [1, 1, 2, 1]
+    [0, 0, 0, 2]
+    [3, 3, 1, 0]
+    [2, 2, 3, 3]
+
+    # Example 5.3
+    >>> f = FpGroup(F, [x**2*y**2, x**3*y**5])
+    >>> Y = []
+    >>> C = coset_enumeration_r(f, Y)
+    >>> for i in range(len(C.p)):
+    ...     if C.p[i] == i:
+    ...         print(C.table[i])
+    [1, 3, 1, 3]
+    [2, 0, 2, 0]
+    [3, 1, 3, 1]
+    [0, 2, 0, 2]
+
+    # Example 5.4
+    >>> F, a, b, c, d, e = free_group("a, b, c, d, e")
+    >>> f = FpGroup(F, [a*b*c**-1, b*c*d**-1, c*d*e**-1, d*e*a**-1, e*a*b**-1])
+    >>> Y = [a]
+    >>> C = coset_enumeration_r(f, Y)
+    >>> for i in range(len(C.p)):
+    ...     if C.p[i] == i:
+    ...         print(C.table[i])
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
+
+    # example of "compress" method
+    >>> C.compress()
+    >>> C.table
+    [[0, 0, 0, 0, 0, 0, 0, 0, 0, 0]]
+
+    # Exercises Pg. 161, Q2.
+    >>> F, x, y = free_group("x, y")
+    >>> f = FpGroup(F, [x**2*y**2, y**-1*x*y*x**-3])
+    >>> Y = []
+    >>> C = coset_enumeration_r(f, Y)
+    >>> C.compress()
+    >>> C.standardize()
+    >>> C.table
+    [[1, 2, 3, 4],
+    [5, 0, 6, 7],
+    [0, 5, 7, 6],
+    [7, 6, 5, 0],
+    [6, 7, 0, 5],
+    [2, 1, 4, 3],
+    [3, 4, 2, 1],
+    [4, 3, 1, 2]]
+
+    # John J. Cannon; Lucien A. Dimino; George Havas; Jane M. Watson
+    # Mathematics of Computation, Vol. 27, No. 123. (Jul., 1973), pp. 463-490
+    # from 1973chwd.pdf
+    # Table 1. Ex. 1
+    >>> F, r, s, t = free_group("r, s, t")
+    >>> E1 = FpGroup(F, [t**-1*r*t*r**-2, r**-1*s*r*s**-2, s**-1*t*s*t**-2])
+    >>> C = coset_enumeration_r(E1, [r])
+    >>> for i in range(len(C.p)):
+    ...     if C.p[i] == i:
+    ...         print(C.table[i])
+    [0, 0, 0, 0, 0, 0]
+
+    Ex. 2
+    >>> F, a, b = free_group("a, b")
+    >>> Cox = FpGroup(F, [a**6, b**6, (a*b)**2, (a**2*b**2)**2, (a**3*b**3)**5])
+    >>> C = coset_enumeration_r(Cox, [a])
+    >>> index = 0
+    >>> for i in range(len(C.p)):
+    ...     if C.p[i] == i:
+    ...         index += 1
+    >>> index
+    500
+
+    # Ex. 3
+    >>> F, a, b = free_group("a, b")
+    >>> B_2_4 = FpGroup(F, [a**4, b**4, (a*b)**4, (a**-1*b)**4, (a**2*b)**4, \
+            (a*b**2)**4, (a**2*b**2)**4, (a**-1*b*a*b)**4, (a*b**-1*a*b)**4])
+    >>> C = coset_enumeration_r(B_2_4, [a])
+    >>> index = 0
+    >>> for i in range(len(C.p)):
+    ...     if C.p[i] == i:
+    ...         index += 1
+    >>> index
+    1024
+
+    References
+    ==========
+
+    .. [1] Holt, D., Eick, B., O'Brien, E.
+           "Handbook of computational group theory"
+
+    """
+    # 1. Initialize a coset table C for < X|R >
+    C = CosetTable(fp_grp, Y, max_cosets=max_cosets)
+    # Define coset table methods.
+    if modified:
+        _scan_and_fill = C.modified_scan_and_fill
+        _define = C.modified_define
+    else:
+        _scan_and_fill = C.scan_and_fill
+        _define = C.define
+    if draft:
+        C.table = draft.table[:]
+        C.p = draft.p[:]
+    R = fp_grp.relators
+    A_dict = C.A_dict
+    p = C.p
+    for i in range(len(Y)):
+        if modified:
+            _scan_and_fill(0, Y[i], C._grp.generators[i])
+        else:
+            _scan_and_fill(0, Y[i])
+    alpha = 0
+    while alpha < C.n:
+        if p[alpha] == alpha:
+            try:
+                for w in R:
+                    if modified:
+                        _scan_and_fill(alpha, w, C._grp.identity)
+                    else:
+                        _scan_and_fill(alpha, w)
+                    # if alpha was eliminated during the scan then break
+                    if p[alpha] < alpha:
+                        break
+                if p[alpha] == alpha:
+                    for x in A_dict:
+                        if C.table[alpha][A_dict[x]] is None:
+                            _define(alpha, x)
+            except ValueError as e:
+                if incomplete:
+                    return C
+                raise e
+        alpha += 1
+    return C
+
+def modified_coset_enumeration_r(fp_grp, Y, max_cosets=None, draft=None,
+                                    incomplete=False):
+    r"""
+    Introduce a new set of symbols y \in Y that correspond to the
+    generators of the subgroup. Store the elements of Y as a
+    word P[\alpha, x] and compute the coset table similar to that of
+    the regular coset enumeration methods.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.free_groups import free_group
+    >>> from sympy.combinatorics.fp_groups import FpGroup
+    >>> from sympy.combinatorics.coset_table import modified_coset_enumeration_r
+    >>> F, x, y = free_group("x, y")
+    >>> f = FpGroup(F, [x**3, y**3, x**-1*y**-1*x*y])
+    >>> C = modified_coset_enumeration_r(f, [x])
+    >>> C.table
+    [[0, 0, 1, 2], [1, 1, 2, 0], [2, 2, 0, 1], [None, 1, None, None], [1, 3, None, None]]
+
+    See Also
+    ========
+
+    coset_enumertation_r
+
+    References
+    ==========
+
+    .. [1] Holt, D., Eick, B., O'Brien, E.,
+           "Handbook of Computational Group Theory",
+           Section 5.3.2
+    """
+    return coset_enumeration_r(fp_grp, Y, max_cosets=max_cosets, draft=draft,
+                             incomplete=incomplete, modified=True)
+
+# Pg. 166
+# coset-table based method
+def coset_enumeration_c(fp_grp, Y, max_cosets=None, draft=None,
+                                                incomplete=False):
+    """
+    >>> from sympy.combinatorics.free_groups import free_group
+    >>> from sympy.combinatorics.fp_groups import FpGroup, coset_enumeration_c
+    >>> F, x, y = free_group("x, y")
+    >>> f = FpGroup(F, [x**3, y**3, x**-1*y**-1*x*y])
+    >>> C = coset_enumeration_c(f, [x])
+    >>> C.table
+    [[0, 0, 1, 2], [1, 1, 2, 0], [2, 2, 0, 1]]
+
+    """
+    # Initialize a coset table C for < X|R >
+    X = fp_grp.generators
+    R = fp_grp.relators
+    C = CosetTable(fp_grp, Y, max_cosets=max_cosets)
+    if draft:
+        C.table = draft.table[:]
+        C.p = draft.p[:]
+        C.deduction_stack = draft.deduction_stack
+        for alpha, x in product(range(len(C.table)), X):
+            if C.table[alpha][C.A_dict[x]] is not None:
+                C.deduction_stack.append((alpha, x))
+    A = C.A
+    # replace all the elements by cyclic reductions
+    R_cyc_red = [rel.identity_cyclic_reduction() for rel in R]
+    R_c = list(chain.from_iterable((rel.cyclic_conjugates(), (rel**-1).cyclic_conjugates()) \
+            for rel in R_cyc_red))
+    R_set = set()
+    for conjugate in R_c:
+        R_set = R_set.union(conjugate)
+    # a list of subsets of R_c whose words start with "x".
+    R_c_list = []
+    for x in C.A:
+        r = {word for word in R_set if word[0] == x}
+        R_c_list.append(r)
+        R_set.difference_update(r)
+    for w in Y:
+        C.scan_and_fill_c(0, w)
+    for x in A:
+        C.process_deductions(R_c_list[C.A_dict[x]], R_c_list[C.A_dict_inv[x]])
+    alpha = 0
+    while alpha < len(C.table):
+        if C.p[alpha] == alpha:
+            try:
+                for x in C.A:
+                    if C.p[alpha] != alpha:
+                        break
+                    if C.table[alpha][C.A_dict[x]] is None:
+                        C.define_c(alpha, x)
+                        C.process_deductions(R_c_list[C.A_dict[x]], R_c_list[C.A_dict_inv[x]])
+            except ValueError as e:
+                if incomplete:
+                    return C
+                raise e
+        alpha += 1
+    return C

lib/python3.12/site-packages/sympy/combinatorics/fp_groups.py

@@ -0,0 +1,1354 @@
+"""Finitely Presented Groups and its algorithms. """
+
+from sympy.core.singleton import S
+from sympy.core.symbol import symbols
+from sympy.combinatorics.free_groups import (FreeGroup, FreeGroupElement,
+                                                free_group)
+from sympy.combinatorics.rewritingsystem import RewritingSystem
+from sympy.combinatorics.coset_table import (CosetTable,
+                                             coset_enumeration_r,
+                                             coset_enumeration_c)
+from sympy.combinatorics import PermutationGroup
+from sympy.matrices.normalforms import invariant_factors
+from sympy.matrices import Matrix
+from sympy.polys.polytools import gcd
+from sympy.printing.defaults import DefaultPrinting
+from sympy.utilities import public
+from sympy.utilities.magic import pollute
+
+from itertools import product
+
+
+@public
+def fp_group(fr_grp, relators=()):
+    _fp_group = FpGroup(fr_grp, relators)
+    return (_fp_group,) + tuple(_fp_group._generators)
+
+@public
+def xfp_group(fr_grp, relators=()):
+    _fp_group = FpGroup(fr_grp, relators)
+    return (_fp_group, _fp_group._generators)
+
+# Does not work. Both symbols and pollute are undefined. Never tested.
+@public
+def vfp_group(fr_grpm, relators):
+    _fp_group = FpGroup(symbols, relators)
+    pollute([sym.name for sym in _fp_group.symbols], _fp_group.generators)
+    return _fp_group
+
+
+def _parse_relators(rels):
+    """Parse the passed relators."""
+    return rels
+
+
+###############################################################################
+#                           FINITELY PRESENTED GROUPS                         #
+###############################################################################
+
+
+class FpGroup(DefaultPrinting):
+    """
+    The FpGroup would take a FreeGroup and a list/tuple of relators, the
+    relators would be specified in such a way that each of them be equal to the
+    identity of the provided free group.
+
+    """
+    is_group = True
+    is_FpGroup = True
+    is_PermutationGroup = False
+
+    def __init__(self, fr_grp, relators):
+        relators = _parse_relators(relators)
+        self.free_group = fr_grp
+        self.relators = relators
+        self.generators = self._generators()
+        self.dtype = type("FpGroupElement", (FpGroupElement,), {"group": self})
+
+        # CosetTable instance on identity subgroup
+        self._coset_table = None
+        # returns whether coset table on identity subgroup
+        # has been standardized
+        self._is_standardized = False
+
+        self._order = None
+        self._center = None
+
+        self._rewriting_system = RewritingSystem(self)
+        self._perm_isomorphism = None
+        return
+
+    def _generators(self):
+        return self.free_group.generators
+
+    def make_confluent(self):
+        '''
+        Try to make the group's rewriting system confluent
+
+        '''
+        self._rewriting_system.make_confluent()
+        return
+
+    def reduce(self, word):
+        '''
+        Return the reduced form of `word` in `self` according to the group's
+        rewriting system. If it's confluent, the reduced form is the unique normal
+        form of the word in the group.
+
+        '''
+        return self._rewriting_system.reduce(word)
+
+    def equals(self, word1, word2):
+        '''
+        Compare `word1` and `word2` for equality in the group
+        using the group's rewriting system. If the system is
+        confluent, the returned answer is necessarily correct.
+        (If it is not, `False` could be returned in some cases
+        where in fact `word1 == word2`)
+
+        '''
+        if self.reduce(word1*word2**-1) == self.identity:
+            return True
+        elif self._rewriting_system.is_confluent:
+            return False
+        return None
+
+    @property
+    def identity(self):
+        return self.free_group.identity
+
+    def __contains__(self, g):
+        return g in self.free_group
+
+    def subgroup(self, gens, C=None, homomorphism=False):
+        '''
+        Return the subgroup generated by `gens` using the
+        Reidemeister-Schreier algorithm
+        homomorphism -- When set to True, return a dictionary containing the images
+                     of the presentation generators in the original group.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.fp_groups import FpGroup
+        >>> from sympy.combinatorics import free_group
+        >>> F, x, y = free_group("x, y")
+        >>> f = FpGroup(F, [x**3, y**5, (x*y)**2])
+        >>> H = [x*y, x**-1*y**-1*x*y*x]
+        >>> K, T = f.subgroup(H, homomorphism=True)
+        >>> T(K.generators)
+        [x*y, x**-1*y**2*x**-1]
+
+        '''
+
+        if not all(isinstance(g, FreeGroupElement) for g in gens):
+            raise ValueError("Generators must be `FreeGroupElement`s")
+        if not all(g.group == self.free_group for g in gens):
+                raise ValueError("Given generators are not members of the group")
+        if homomorphism:
+            g, rels, _gens = reidemeister_presentation(self, gens, C=C, homomorphism=True)
+        else:
+            g, rels = reidemeister_presentation(self, gens, C=C)
+        if g:
+            g = FpGroup(g[0].group, rels)
+        else:
+            g = FpGroup(free_group('')[0], [])
+        if homomorphism:
+            from sympy.combinatorics.homomorphisms import homomorphism
+            return g, homomorphism(g, self, g.generators, _gens, check=False)
+        return g
+
+    def coset_enumeration(self, H, strategy="relator_based", max_cosets=None,
+                                                        draft=None, incomplete=False):
+        """
+        Return an instance of ``coset table``, when Todd-Coxeter algorithm is
+        run over the ``self`` with ``H`` as subgroup, using ``strategy``
+        argument as strategy. The returned coset table is compressed but not
+        standardized.
+
+        An instance of `CosetTable` for `fp_grp` can be passed as the keyword
+        argument `draft` in which case the coset enumeration will start with
+        that instance and attempt to complete it.
+
+        When `incomplete` is `True` and the function is unable to complete for
+        some reason, the partially complete table will be returned.
+
+        """
+        if not max_cosets:
+            max_cosets = CosetTable.coset_table_max_limit
+        if strategy == 'relator_based':
+            C = coset_enumeration_r(self, H, max_cosets=max_cosets,
+                                                    draft=draft, incomplete=incomplete)
+        else:
+            C = coset_enumeration_c(self, H, max_cosets=max_cosets,
+                                                    draft=draft, incomplete=incomplete)
+        if C.is_complete():
+            C.compress()
+        return C
+
+    def standardize_coset_table(self):
+        """
+        Standardized the coset table ``self`` and makes the internal variable
+        ``_is_standardized`` equal to ``True``.
+
+        """
+        self._coset_table.standardize()
+        self._is_standardized = True
+
+    def coset_table(self, H, strategy="relator_based", max_cosets=None,
+                                                 draft=None, incomplete=False):
+        """
+        Return the mathematical coset table of ``self`` in ``H``.
+
+        """
+        if not H:
+            if self._coset_table is not None:
+                if not self._is_standardized:
+                    self.standardize_coset_table()
+            else:
+                C = self.coset_enumeration([], strategy, max_cosets=max_cosets,
+                                            draft=draft, incomplete=incomplete)
+                self._coset_table = C
+                self.standardize_coset_table()
+            return self._coset_table.table
+        else:
+            C = self.coset_enumeration(H, strategy, max_cosets=max_cosets,
+                                            draft=draft, incomplete=incomplete)
+            C.standardize()
+            return C.table
+
+    def order(self, strategy="relator_based"):
+        """
+        Returns the order of the finitely presented group ``self``. It uses
+        the coset enumeration with identity group as subgroup, i.e ``H=[]``.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> from sympy.combinatorics.fp_groups import FpGroup
+        >>> F, x, y = free_group("x, y")
+        >>> f = FpGroup(F, [x, y**2])
+        >>> f.order(strategy="coset_table_based")
+        2
+
+        """
+        if self._order is not None:
+            return self._order
+        if self._coset_table is not None:
+            self._order = len(self._coset_table.table)
+        elif len(self.relators) == 0:
+            self._order = self.free_group.order()
+        elif len(self.generators) == 1:
+            self._order = abs(gcd([r.array_form[0][1] for r in self.relators]))
+        elif self._is_infinite():
+            self._order = S.Infinity
+        else:
+            gens, C = self._finite_index_subgroup()
+            if C:
+                ind = len(C.table)
+                self._order = ind*self.subgroup(gens, C=C).order()
+            else:
+                self._order = self.index([])
+        return self._order
+
+    def _is_infinite(self):
+        '''
+        Test if the group is infinite. Return `True` if the test succeeds
+        and `None` otherwise
+
+        '''
+        used_gens = set()
+        for r in self.relators:
+            used_gens.update(r.contains_generators())
+        if not set(self.generators) <= used_gens:
+            return True
+        # Abelianisation test: check is the abelianisation is infinite
+        abelian_rels = []
+        for rel in self.relators:
+            abelian_rels.append([rel.exponent_sum(g) for g in self.generators])
+        m = Matrix(Matrix(abelian_rels))
+        if 0 in invariant_factors(m):
+            return True
+        else:
+            return None
+
+
+    def _finite_index_subgroup(self, s=None):
+        '''
+        Find the elements of `self` that generate a finite index subgroup
+        and, if found, return the list of elements and the coset table of `self` by
+        the subgroup, otherwise return `(None, None)`
+
+        '''
+        gen = self.most_frequent_generator()
+        rels = list(self.generators)
+        rels.extend(self.relators)
+        if not s:
+            if len(self.generators) == 2:
+                s = [gen] + [g for g in self.generators if g != gen]
+            else:
+                rand = self.free_group.identity
+                i = 0
+                while ((rand in rels or rand**-1 in rels or rand.is_identity)
+                        and i<10):
+                    rand = self.random()
+                    i += 1
+                s = [gen, rand] + [g for g in self.generators if g != gen]
+        mid = (len(s)+1)//2
+        half1 = s[:mid]
+        half2 = s[mid:]
+        draft1 = None
+        draft2 = None
+        m = 200
+        C = None
+        while not C and (m/2 < CosetTable.coset_table_max_limit):
+            m = min(m, CosetTable.coset_table_max_limit)
+            draft1 = self.coset_enumeration(half1, max_cosets=m,
+                                 draft=draft1, incomplete=True)
+            if draft1.is_complete():
+                C = draft1
+                half = half1
+            else:
+                draft2 = self.coset_enumeration(half2, max_cosets=m,
+                                 draft=draft2, incomplete=True)
+                if draft2.is_complete():
+                    C = draft2
+                    half = half2
+            if not C:
+                m *= 2
+        if not C:
+            return None, None
+        C.compress()
+        return half, C
+
+    def most_frequent_generator(self):
+        gens = self.generators
+        rels = self.relators
+        freqs = [sum(r.generator_count(g) for r in rels) for g in gens]
+        return gens[freqs.index(max(freqs))]
+
+    def random(self):
+        import random
+        r = self.free_group.identity
+        for i in range(random.randint(2,3)):
+            r = r*random.choice(self.generators)**random.choice([1,-1])
+        return r
+
+    def index(self, H, strategy="relator_based"):
+        """
+        Return the index of subgroup ``H`` in group ``self``.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> from sympy.combinatorics.fp_groups import FpGroup
+        >>> F, x, y = free_group("x, y")
+        >>> f = FpGroup(F, [x**5, y**4, y*x*y**3*x**3])
+        >>> f.index([x])
+        4
+
+        """
+        # TODO: use |G:H| = |G|/|H| (currently H can't be made into a group)
+        # when we know |G| and |H|
+
+        if H == []:
+            return self.order()
+        else:
+            C = self.coset_enumeration(H, strategy)
+            return len(C.table)
+
+    def __str__(self):
+        if self.free_group.rank > 30:
+            str_form = "<fp group with %s generators>" % self.free_group.rank
+        else:
+            str_form = "<fp group on the generators %s>" % str(self.generators)
+        return str_form
+
+    __repr__ = __str__
+
+#==============================================================================
+#                       PERMUTATION GROUP METHODS
+#==============================================================================
+
+    def _to_perm_group(self):
+        '''
+        Return an isomorphic permutation group and the isomorphism.
+        The implementation is dependent on coset enumeration so
+        will only terminate for finite groups.
+
+        '''
+        from sympy.combinatorics import Permutation
+        from sympy.combinatorics.homomorphisms import homomorphism
+        if self.order() is S.Infinity:
+            raise NotImplementedError("Permutation presentation of infinite "
+                                                  "groups is not implemented")
+        if self._perm_isomorphism:
+            T = self._perm_isomorphism
+            P = T.image()
+        else:
+            C = self.coset_table([])
+            gens = self.generators
+            images = [[C[i][2*gens.index(g)] for i in range(len(C))] for g in gens]
+            images = [Permutation(i) for i in images]
+            P = PermutationGroup(images)
+            T = homomorphism(self, P, gens, images, check=False)
+            self._perm_isomorphism = T
+        return P, T
+
+    def _perm_group_list(self, method_name, *args):
+        '''
+        Given the name of a `PermutationGroup` method (returning a subgroup
+        or a list of subgroups) and (optionally) additional arguments it takes,
+        return a list or a list of lists containing the generators of this (or
+        these) subgroups in terms of the generators of `self`.
+
+        '''
+        P, T = self._to_perm_group()
+        perm_result = getattr(P, method_name)(*args)
+        single = False
+        if isinstance(perm_result, PermutationGroup):
+            perm_result, single = [perm_result], True
+        result = []
+        for group in perm_result:
+            gens = group.generators
+            result.append(T.invert(gens))
+        return result[0] if single else result
+
+    def derived_series(self):
+        '''
+        Return the list of lists containing the generators
+        of the subgroups in the derived series of `self`.
+
+        '''
+        return self._perm_group_list('derived_series')
+
+    def lower_central_series(self):
+        '''
+        Return the list of lists containing the generators
+        of the subgroups in the lower central series of `self`.
+
+        '''
+        return self._perm_group_list('lower_central_series')
+
+    def center(self):
+        '''
+        Return the list of generators of the center of `self`.
+
+        '''
+        return self._perm_group_list('center')
+
+
+    def derived_subgroup(self):
+        '''
+        Return the list of generators of the derived subgroup of `self`.
+
+        '''
+        return self._perm_group_list('derived_subgroup')
+
+
+    def centralizer(self, other):
+        '''
+        Return the list of generators of the centralizer of `other`
+        (a list of elements of `self`) in `self`.
+
+        '''
+        T = self._to_perm_group()[1]
+        other = T(other)
+        return self._perm_group_list('centralizer', other)
+
+    def normal_closure(self, other):
+        '''
+        Return the list of generators of the normal closure of `other`
+        (a list of elements of `self`) in `self`.
+
+        '''
+        T = self._to_perm_group()[1]
+        other = T(other)
+        return self._perm_group_list('normal_closure', other)
+
+    def _perm_property(self, attr):
+        '''
+        Given an attribute of a `PermutationGroup`, return
+        its value for a permutation group isomorphic to `self`.
+
+        '''
+        P = self._to_perm_group()[0]
+        return getattr(P, attr)
+
+    @property
+    def is_abelian(self):
+        '''
+        Check if `self` is abelian.
+
+        '''
+        return self._perm_property("is_abelian")
+
+    @property
+    def is_nilpotent(self):
+        '''
+        Check if `self` is nilpotent.
+
+        '''
+        return self._perm_property("is_nilpotent")
+
+    @property
+    def is_solvable(self):
+        '''
+        Check if `self` is solvable.
+
+        '''
+        return self._perm_property("is_solvable")
+
+    @property
+    def elements(self):
+        '''
+        List the elements of `self`.
+
+        '''
+        P, T = self._to_perm_group()
+        return T.invert(P.elements)
+
+    @property
+    def is_cyclic(self):
+        """
+        Return ``True`` if group is Cyclic.
+
+        """
+        if len(self.generators) <= 1:
+            return True
+        try:
+            P, T = self._to_perm_group()
+        except NotImplementedError:
+            raise NotImplementedError("Check for infinite Cyclic group "
+                                      "is not implemented")
+        return P.is_cyclic
+
+    def abelian_invariants(self):
+        """
+        Return Abelian Invariants of a group.
+        """
+        try:
+            P, T = self._to_perm_group()
+        except NotImplementedError:
+            raise NotImplementedError("abelian invariants is not implemented"
+                                      "for infinite group")
+        return P.abelian_invariants()
+
+    def composition_series(self):
+        """
+        Return subnormal series of maximum length for a group.
+        """
+        try:
+            P, T = self._to_perm_group()
+        except NotImplementedError:
+            raise NotImplementedError("composition series is not implemented"
+                                      "for infinite group")
+        return P.composition_series()
+
+
+class FpSubgroup(DefaultPrinting):
+    '''
+    The class implementing a subgroup of an FpGroup or a FreeGroup
+    (only finite index subgroups are supported at this point). This
+    is to be used if one wishes to check if an element of the original
+    group belongs to the subgroup
+
+    '''
+    def __init__(self, G, gens, normal=False):
+        super().__init__()
+        self.parent = G
+        self.generators = list({g for g in gens if g != G.identity})
+        self._min_words = None #for use in __contains__
+        self.C = None
+        self.normal = normal
+
+    def __contains__(self, g):
+
+        if isinstance(self.parent, FreeGroup):
+            if self._min_words is None:
+                # make _min_words - a list of subwords such that
+                # g is in the subgroup if and only if it can be
+                # partitioned into these subwords. Infinite families of
+                # subwords are presented by tuples, e.g. (r, w)
+                # stands for the family of subwords r*w**n*r**-1
+
+                def _process(w):
+                    # this is to be used before adding new words
+                    # into _min_words; if the word w is not cyclically
+                    # reduced, it will generate an infinite family of
+                    # subwords so should be written as a tuple;
+                    # if it is, w**-1 should be added to the list
+                    # as well
+                    p, r = w.cyclic_reduction(removed=True)
+                    if not r.is_identity:
+                        return [(r, p)]
+                    else:
+                        return [w, w**-1]
+
+                # make the initial list
+                gens = []
+                for w in self.generators:
+                    if self.normal:
+                        w = w.cyclic_reduction()
+                    gens.extend(_process(w))
+
+                for w1 in gens:
+                    for w2 in gens:
+                        # if w1 and w2 are equal or are inverses, continue
+                        if w1 == w2 or (not isinstance(w1, tuple)
+                                                        and w1**-1 == w2):
+                            continue
+
+                        # if the start of one word is the inverse of the
+                        # end of the other, their multiple should be added
+                        # to _min_words because of cancellation
+                        if isinstance(w1, tuple):
+                            # start, end
+                            s1, s2 = w1[0][0], w1[0][0]**-1
+                        else:
+                            s1, s2 = w1[0], w1[len(w1)-1]
+
+                        if isinstance(w2, tuple):
+                            # start, end
+                            r1, r2 = w2[0][0], w2[0][0]**-1
+                        else:
+                            r1, r2 = w2[0], w2[len(w1)-1]
+
+                        # p1 and p2 are w1 and w2 or, in case when
+                        # w1 or w2 is an infinite family, a representative
+                        p1, p2 = w1, w2
+                        if isinstance(w1, tuple):
+                            p1 = w1[0]*w1[1]*w1[0]**-1
+                        if isinstance(w2, tuple):
+                            p2 = w2[0]*w2[1]*w2[0]**-1
+
+                        # add the product of the words to the list is necessary
+                        if r1**-1 == s2 and not (p1*p2).is_identity:
+                            new = _process(p1*p2)
+                            if new not in gens:
+                                gens.extend(new)
+
+                        if r2**-1 == s1 and not (p2*p1).is_identity:
+                            new = _process(p2*p1)
+                            if new not in gens:
+                                gens.extend(new)
+
+                self._min_words = gens
+
+            min_words = self._min_words
+
+            def _is_subword(w):
+                # check if w is a word in _min_words or one of
+                # the infinite families in it
+                w, r = w.cyclic_reduction(removed=True)
+                if r.is_identity or self.normal:
+                    return w in min_words
+                else:
+                    t = [s[1] for s in min_words if isinstance(s, tuple)
+                                                                and s[0] == r]
+                    return [s for s in t if w.power_of(s)] != []
+
+            # store the solution of words for which the result of
+            # _word_break (below) is known
+            known = {}
+
+            def _word_break(w):
+                # check if w can be written as a product of words
+                # in min_words
+                if len(w) == 0:
+                    return True
+                i = 0
+                while i < len(w):
+                    i += 1
+                    prefix = w.subword(0, i)
+                    if not _is_subword(prefix):
+                        continue
+                    rest = w.subword(i, len(w))
+                    if rest not in known:
+                        known[rest] = _word_break(rest)
+                    if known[rest]:
+                        return True
+                return False
+
+            if self.normal:
+                g = g.cyclic_reduction()
+            return _word_break(g)
+        else:
+            if self.C is None:
+                C = self.parent.coset_enumeration(self.generators)
+                self.C = C
+            i = 0
+            C = self.C
+            for j in range(len(g)):
+                i = C.table[i][C.A_dict[g[j]]]
+            return i == 0
+
+    def order(self):
+        if not self.generators:
+            return S.One
+        if isinstance(self.parent, FreeGroup):
+            return S.Infinity
+        if self.C is None:
+            C = self.parent.coset_enumeration(self.generators)
+            self.C = C
+        # This is valid because `len(self.C.table)` (the index of the subgroup)
+        # will always be finite - otherwise coset enumeration doesn't terminate
+        return self.parent.order()/len(self.C.table)
+
+    def to_FpGroup(self):
+        if isinstance(self.parent, FreeGroup):
+            gen_syms = [('x_%d'%i) for i in range(len(self.generators))]
+            return free_group(', '.join(gen_syms))[0]
+        return self.parent.subgroup(C=self.C)
+
+    def __str__(self):
+        if len(self.generators) > 30:
+            str_form = "<fp subgroup with %s generators>" % len(self.generators)
+        else:
+            str_form = "<fp subgroup on the generators %s>" % str(self.generators)
+        return str_form
+
+    __repr__ = __str__
+
+
+###############################################################################
+#                           LOW INDEX SUBGROUPS                               #
+###############################################################################
+
+def low_index_subgroups(G, N, Y=()):
+    """
+    Implements the Low Index Subgroups algorithm, i.e find all subgroups of
+    ``G`` upto a given index ``N``. This implements the method described in
+    [Sim94]. This procedure involves a backtrack search over incomplete Coset
+    Tables, rather than over forced coincidences.
+
+    Parameters
+    ==========
+
+    G: An FpGroup < X|R >
+    N: positive integer, representing the maximum index value for subgroups
+    Y: (an optional argument) specifying a list of subgroup generators, such
+    that each of the resulting subgroup contains the subgroup generated by Y.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics import free_group
+    >>> from sympy.combinatorics.fp_groups import FpGroup, low_index_subgroups
+    >>> F, x, y = free_group("x, y")
+    >>> f = FpGroup(F, [x**2, y**3, (x*y)**4])
+    >>> L = low_index_subgroups(f, 4)
+    >>> for coset_table in L:
+    ...     print(coset_table.table)
+    [[0, 0, 0, 0]]
+    [[0, 0, 1, 2], [1, 1, 2, 0], [3, 3, 0, 1], [2, 2, 3, 3]]
+    [[0, 0, 1, 2], [2, 2, 2, 0], [1, 1, 0, 1]]
+    [[1, 1, 0, 0], [0, 0, 1, 1]]
+
+    References
+    ==========
+
+    .. [1] Holt, D., Eick, B., O'Brien, E.
+           "Handbook of Computational Group Theory"
+           Section 5.4
+
+    .. [2] Marston Conder and Peter Dobcsanyi
+           "Applications and Adaptions of the Low Index Subgroups Procedure"
+
+    """
+    C = CosetTable(G, [])
+    R = G.relators
+    # length chosen for the length of the short relators
+    len_short_rel = 5
+    # elements of R2 only checked at the last step for complete
+    # coset tables
+    R2 = {rel for rel in R if len(rel) > len_short_rel}
+    # elements of R1 are used in inner parts of the process to prune
+    # branches of the search tree,
+    R1 = {rel.identity_cyclic_reduction() for rel in set(R) - R2}
+    R1_c_list = C.conjugates(R1)
+    S = []
+    descendant_subgroups(S, C, R1_c_list, C.A[0], R2, N, Y)
+    return S
+
+
+def descendant_subgroups(S, C, R1_c_list, x, R2, N, Y):
+    A_dict = C.A_dict
+    A_dict_inv = C.A_dict_inv
+    if C.is_complete():
+        # if C is complete then it only needs to test
+        # whether the relators in R2 are satisfied
+        for w, alpha in product(R2, C.omega):
+            if not C.scan_check(alpha, w):
+                return
+        # relators in R2 are satisfied, append the table to list
+        S.append(C)
+    else:
+        # find the first undefined entry in Coset Table
+        for alpha, x in product(range(len(C.table)), C.A):
+            if C.table[alpha][A_dict[x]] is None:
+                # this is "x" in pseudo-code (using "y" makes it clear)
+                undefined_coset, undefined_gen = alpha, x
+                break
+        # for filling up the undefine entry we try all possible values
+        # of beta in Omega or beta = n where beta^(undefined_gen^-1) is undefined
+        reach = C.omega + [C.n]
+        for beta in reach:
+            if beta < N:
+                if beta == C.n or C.table[beta][A_dict_inv[undefined_gen]] is None:
+                    try_descendant(S, C, R1_c_list, R2, N, undefined_coset, \
+                            undefined_gen, beta, Y)
+
+
+def try_descendant(S, C, R1_c_list, R2, N, alpha, x, beta, Y):
+    r"""
+    Solves the problem of trying out each individual possibility
+    for `\alpha^x.
+
+    """
+    D = C.copy()
+    if beta == D.n and beta < N:
+        D.table.append([None]*len(D.A))
+        D.p.append(beta)
+    D.table[alpha][D.A_dict[x]] = beta
+    D.table[beta][D.A_dict_inv[x]] = alpha
+    D.deduction_stack.append((alpha, x))
+    if not D.process_deductions_check(R1_c_list[D.A_dict[x]], \
+            R1_c_list[D.A_dict_inv[x]]):
+        return
+    for w in Y:
+        if not D.scan_check(0, w):
+            return
+    if first_in_class(D, Y):
+        descendant_subgroups(S, D, R1_c_list, x, R2, N, Y)
+
+
+def first_in_class(C, Y=()):
+    """
+    Checks whether the subgroup ``H=G1`` corresponding to the Coset Table
+    could possibly be the canonical representative of its conjugacy class.
+
+    Parameters
+    ==========
+
+    C: CosetTable
+
+    Returns
+    =======
+
+    bool: True/False
+
+    If this returns False, then no descendant of C can have that property, and
+    so we can abandon C. If it returns True, then we need to process further
+    the node of the search tree corresponding to C, and so we call
+    ``descendant_subgroups`` recursively on C.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics import free_group
+    >>> from sympy.combinatorics.fp_groups import FpGroup, CosetTable, first_in_class
+    >>> F, x, y = free_group("x, y")
+    >>> f = FpGroup(F, [x**2, y**3, (x*y)**4])
+    >>> C = CosetTable(f, [])
+    >>> C.table = [[0, 0, None, None]]
+    >>> first_in_class(C)
+    True
+    >>> C.table = [[1, 1, 1, None], [0, 0, None, 1]]; C.p = [0, 1]
+    >>> first_in_class(C)
+    True
+    >>> C.table = [[1, 1, 2, 1], [0, 0, 0, None], [None, None, None, 0]]
+    >>> C.p = [0, 1, 2]
+    >>> first_in_class(C)
+    False
+    >>> C.table = [[1, 1, 1, 2], [0, 0, 2, 0], [2, None, 0, 1]]
+    >>> first_in_class(C)
+    False
+
+    # TODO:: Sims points out in [Sim94] that performance can be improved by
+    # remembering some of the information computed by ``first_in_class``. If
+    # the ``continue alpha`` statement is executed at line 14, then the same thing
+    # will happen for that value of alpha in any descendant of the table C, and so
+    # the values the values of alpha for which this occurs could profitably be
+    # stored and passed through to the descendants of C. Of course this would
+    # make the code more complicated.
+
+    # The code below is taken directly from the function on page 208 of [Sim94]
+    # nu[alpha]
+
+    """
+    n = C.n
+    # lamda is the largest numbered point in Omega_c_alpha which is currently defined
+    lamda = -1
+    # for alpha in Omega_c, nu[alpha] is the point in Omega_c_alpha corresponding to alpha
+    nu = [None]*n
+    # for alpha in Omega_c_alpha, mu[alpha] is the point in Omega_c corresponding to alpha
+    mu = [None]*n
+    # mutually nu and mu are the mutually-inverse equivalence maps between
+    # Omega_c_alpha and Omega_c
+    next_alpha = False
+    # For each 0!=alpha in [0 .. nc-1], we start by constructing the equivalent
+    # standardized coset table C_alpha corresponding to H_alpha
+    for alpha in range(1, n):
+        # reset nu to "None" after previous value of alpha
+        for beta in range(lamda+1):
+            nu[mu[beta]] = None
+        # we only want to reject our current table in favour of a preceding
+        # table in the ordering in which 1 is replaced by alpha, if the subgroup
+        # G_alpha corresponding to this preceding table definitely contains the
+        # given subgroup
+        for w in Y:
+            # TODO: this should support input of a list of general words
+            # not just the words which are in "A" (i.e gen and gen^-1)
+            if C.table[alpha][C.A_dict[w]] != alpha:
+                # continue with alpha
+                next_alpha = True
+                break
+        if next_alpha:
+            next_alpha = False
+            continue
+        # try alpha as the new point 0 in Omega_C_alpha
+        mu[0] = alpha
+        nu[alpha] = 0
+        # compare corresponding entries in C and C_alpha
+        lamda = 0
+        for beta in range(n):
+            for x in C.A:
+                gamma = C.table[beta][C.A_dict[x]]
+                delta = C.table[mu[beta]][C.A_dict[x]]
+                # if either of the entries is undefined,
+                # we move with next alpha
+                if gamma is None or delta is None:
+                    # continue with alpha
+                    next_alpha = True
+                    break
+                if nu[delta] is None:
+                    # delta becomes the next point in Omega_C_alpha
+                    lamda += 1
+                    nu[delta] = lamda
+                    mu[lamda] = delta
+                if nu[delta] < gamma:
+                    return False
+                if nu[delta] > gamma:
+                    # continue with alpha
+                    next_alpha = True
+                    break
+            if next_alpha:
+                next_alpha = False
+                break
+    return True
+
+#========================================================================
+#                    Simplifying Presentation
+#========================================================================
+
+def simplify_presentation(*args, change_gens=False):
+    '''
+    For an instance of `FpGroup`, return a simplified isomorphic copy of
+    the group (e.g. remove redundant generators or relators). Alternatively,
+    a list of generators and relators can be passed in which case the
+    simplified lists will be returned.
+
+    By default, the generators of the group are unchanged. If you would
+    like to remove redundant generators, set the keyword argument
+    `change_gens = True`.
+
+    '''
+    if len(args) == 1:
+        if not isinstance(args[0], FpGroup):
+            raise TypeError("The argument must be an instance of FpGroup")
+        G = args[0]
+        gens, rels = simplify_presentation(G.generators, G.relators,
+                                              change_gens=change_gens)
+        if gens:
+            return FpGroup(gens[0].group, rels)
+        return FpGroup(FreeGroup([]), [])
+    elif len(args) == 2:
+        gens, rels = args[0][:], args[1][:]
+        if not gens:
+            return gens, rels
+        identity = gens[0].group.identity
+    else:
+        if len(args) == 0:
+            m = "Not enough arguments"
+        else:
+            m = "Too many arguments"
+        raise RuntimeError(m)
+
+    prev_gens = []
+    prev_rels = []
+    while not set(prev_rels) == set(rels):
+        prev_rels = rels
+        while change_gens and not set(prev_gens) == set(gens):
+            prev_gens = gens
+            gens, rels = elimination_technique_1(gens, rels, identity)
+        rels = _simplify_relators(rels)
+
+    if change_gens:
+        syms = [g.array_form[0][0] for g in gens]
+        F = free_group(syms)[0]
+        identity = F.identity
+        gens = F.generators
+        subs = dict(zip(syms, gens))
+        for j, r in enumerate(rels):
+            a = r.array_form
+            rel = identity
+            for sym, p in a:
+                rel = rel*subs[sym]**p
+            rels[j] = rel
+    return gens, rels
+
+def _simplify_relators(rels):
+    """
+    Simplifies a set of relators. All relators are checked to see if they are
+    of the form `gen^n`. If any such relators are found then all other relators
+    are processed for strings in the `gen` known order.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics import free_group
+    >>> from sympy.combinatorics.fp_groups import _simplify_relators
+    >>> F, x, y = free_group("x, y")
+    >>> w1 = [x**2*y**4, x**3]
+    >>> _simplify_relators(w1)
+    [x**3, x**-1*y**4]
+
+    >>> w2 = [x**2*y**-4*x**5, x**3, x**2*y**8, y**5]
+    >>> _simplify_relators(w2)
+    [x**-1*y**-2, x**-1*y*x**-1, x**3, y**5]
+
+    >>> w3 = [x**6*y**4, x**4]
+    >>> _simplify_relators(w3)
+    [x**4, x**2*y**4]
+
+    >>> w4 = [x**2, x**5, y**3]
+    >>> _simplify_relators(w4)
+    [x, y**3]
+
+    """
+    rels = rels[:]
+
+    if not rels:
+        return []
+
+    identity = rels[0].group.identity
+
+    # build dictionary with "gen: n" where gen^n is one of the relators
+    exps = {}
+    for i in range(len(rels)):
+        rel = rels[i]
+        if rel.number_syllables() == 1:
+            g = rel[0]
+            exp = abs(rel.array_form[0][1])
+            if rel.array_form[0][1] < 0:
+                rels[i] = rels[i]**-1
+                g = g**-1
+            if g in exps:
+                exp = gcd(exp, exps[g].array_form[0][1])
+            exps[g] = g**exp
+
+    one_syllables_words = list(exps.values())
+    # decrease some of the exponents in relators, making use of the single
+    # syllable relators
+    for i, rel in enumerate(rels):
+        if rel in one_syllables_words:
+            continue
+        rel = rel.eliminate_words(one_syllables_words, _all = True)
+        # if rels[i] contains g**n where abs(n) is greater than half of the power p
+        # of g in exps, g**n can be replaced by g**(n-p) (or g**(p-n) if n<0)
+        for g in rel.contains_generators():
+            if g in exps:
+                exp = exps[g].array_form[0][1]
+                max_exp = (exp + 1)//2
+                rel = rel.eliminate_word(g**(max_exp), g**(max_exp-exp), _all = True)
+                rel = rel.eliminate_word(g**(-max_exp), g**(-(max_exp-exp)), _all = True)
+        rels[i] = rel
+
+    rels = [r.identity_cyclic_reduction() for r in rels]
+
+    rels += one_syllables_words # include one_syllable_words in the list of relators
+    rels = list(set(rels)) # get unique values in rels
+    rels.sort()
+
+    # remove <identity> entries in rels
+    try:
+        rels.remove(identity)
+    except ValueError:
+        pass
+    return rels
+
+# Pg 350, section 2.5.1 from [2]
+def elimination_technique_1(gens, rels, identity):
+    rels = rels[:]
+    # the shorter relators are examined first so that generators selected for
+    # elimination will have shorter strings as equivalent
+    rels.sort()
+    gens = gens[:]
+    redundant_gens = {}
+    redundant_rels = []
+    used_gens = set()
+    # examine each relator in relator list for any generator occurring exactly
+    # once
+    for rel in rels:
+        # don't look for a redundant generator in a relator which
+        # depends on previously found ones
+        contained_gens = rel.contains_generators()
+        if any(g in contained_gens for g in redundant_gens):
+            continue
+        contained_gens = list(contained_gens)
+        contained_gens.sort(reverse = True)
+        for gen in contained_gens:
+            if rel.generator_count(gen) == 1 and gen not in used_gens:
+                k = rel.exponent_sum(gen)
+                gen_index = rel.index(gen**k)
+                bk = rel.subword(gen_index + 1, len(rel))
+                fw = rel.subword(0, gen_index)
+                chi = bk*fw
+                redundant_gens[gen] = chi**(-1*k)
+                used_gens.update(chi.contains_generators())
+                redundant_rels.append(rel)
+                break
+    rels = [r for r in rels if r not in redundant_rels]
+    # eliminate the redundant generators from remaining relators
+    rels = [r.eliminate_words(redundant_gens, _all = True).identity_cyclic_reduction() for r in rels]
+    rels = list(set(rels))
+    try:
+        rels.remove(identity)
+    except ValueError:
+        pass
+    gens = [g for g in gens if g not in redundant_gens]
+    return gens, rels
+
+###############################################################################
+#                           SUBGROUP PRESENTATIONS                            #
+###############################################################################
+
+# Pg 175 [1]
+def define_schreier_generators(C, homomorphism=False):
+    '''
+    Parameters
+    ==========
+
+    C -- Coset table.
+    homomorphism -- When set to True, return a dictionary containing the images
+                     of the presentation generators in the original group.
+    '''
+    y = []
+    gamma = 1
+    f = C.fp_group
+    X = f.generators
+    if homomorphism:
+        # `_gens` stores the elements of the parent group to
+        # to which the schreier generators correspond to.
+        _gens = {}
+        # compute the schreier Traversal
+        tau = {}
+        tau[0] = f.identity
+    C.P = [[None]*len(C.A) for i in range(C.n)]
+    for alpha, x in product(C.omega, C.A):
+        beta = C.table[alpha][C.A_dict[x]]
+        if beta == gamma:
+            C.P[alpha][C.A_dict[x]] = "<identity>"
+            C.P[beta][C.A_dict_inv[x]] = "<identity>"
+            gamma += 1
+            if homomorphism:
+                tau[beta] = tau[alpha]*x
+        elif x in X and C.P[alpha][C.A_dict[x]] is None:
+            y_alpha_x = '%s_%s' % (x, alpha)
+            y.append(y_alpha_x)
+            C.P[alpha][C.A_dict[x]] = y_alpha_x
+            if homomorphism:
+                _gens[y_alpha_x] = tau[alpha]*x*tau[beta]**-1
+    grp_gens = list(free_group(', '.join(y)))
+    C._schreier_free_group = grp_gens.pop(0)
+    C._schreier_generators = grp_gens
+    if homomorphism:
+        C._schreier_gen_elem = _gens
+    # replace all elements of P by, free group elements
+    for i, j in product(range(len(C.P)), range(len(C.A))):
+        # if equals "<identity>", replace by identity element
+        if C.P[i][j] == "<identity>":
+            C.P[i][j] = C._schreier_free_group.identity
+        elif isinstance(C.P[i][j], str):
+            r = C._schreier_generators[y.index(C.P[i][j])]
+            C.P[i][j] = r
+            beta = C.table[i][j]
+            C.P[beta][j + 1] = r**-1
+
+def reidemeister_relators(C):
+    R = C.fp_group.relators
+    rels = [rewrite(C, coset, word) for word in R for coset in range(C.n)]
+    order_1_gens = {i for i in rels if len(i) == 1}
+
+    # remove all the order 1 generators from relators
+    rels = list(filter(lambda rel: rel not in order_1_gens, rels))
+
+    # replace order 1 generators by identity element in reidemeister relators
+    for i in range(len(rels)):
+        w = rels[i]
+        w = w.eliminate_words(order_1_gens, _all=True)
+        rels[i] = w
+
+    C._schreier_generators = [i for i in C._schreier_generators
+                    if not (i in order_1_gens or i**-1 in order_1_gens)]
+
+    # Tietze transformation 1 i.e TT_1
+    # remove cyclic conjugate elements from relators
+    i = 0
+    while i < len(rels):
+        w = rels[i]
+        j = i + 1
+        while j < len(rels):
+            if w.is_cyclic_conjugate(rels[j]):
+                del rels[j]
+            else:
+                j += 1
+        i += 1
+
+    C._reidemeister_relators = rels
+
+
+def rewrite(C, alpha, w):
+    """
+    Parameters
+    ==========
+
+    C: CosetTable
+    alpha: A live coset
+    w: A word in `A*`
+
+    Returns
+    =======
+
+    rho(tau(alpha), w)
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.fp_groups import FpGroup, CosetTable, define_schreier_generators, rewrite
+    >>> from sympy.combinatorics import free_group
+    >>> F, x, y = free_group("x, y")
+    >>> f = FpGroup(F, [x**2, y**3, (x*y)**6])
+    >>> C = CosetTable(f, [])
+    >>> C.table = [[1, 1, 2, 3], [0, 0, 4, 5], [4, 4, 3, 0], [5, 5, 0, 2], [2, 2, 5, 1], [3, 3, 1, 4]]
+    >>> C.p = [0, 1, 2, 3, 4, 5]
+    >>> define_schreier_generators(C)
+    >>> rewrite(C, 0, (x*y)**6)
+    x_4*y_2*x_3*x_1*x_2*y_4*x_5
+
+    """
+    v = C._schreier_free_group.identity
+    for i in range(len(w)):
+        x_i = w[i]
+        v = v*C.P[alpha][C.A_dict[x_i]]
+        alpha = C.table[alpha][C.A_dict[x_i]]
+    return v
+
+# Pg 350, section 2.5.2 from [2]
+def elimination_technique_2(C):
+    """
+    This technique eliminates one generator at a time. Heuristically this
+    seems superior in that we may select for elimination the generator with
+    shortest equivalent string at each stage.
+
+    >>> from sympy.combinatorics import free_group
+    >>> from sympy.combinatorics.fp_groups import FpGroup, coset_enumeration_r, \
+            reidemeister_relators, define_schreier_generators, elimination_technique_2
+    >>> F, x, y = free_group("x, y")
+    >>> f = FpGroup(F, [x**3, y**5, (x*y)**2]); H = [x*y, x**-1*y**-1*x*y*x]
+    >>> C = coset_enumeration_r(f, H)
+    >>> C.compress(); C.standardize()
+    >>> define_schreier_generators(C)
+    >>> reidemeister_relators(C)
+    >>> elimination_technique_2(C)
+    ([y_1, y_2], [y_2**-3, y_2*y_1*y_2*y_1*y_2*y_1, y_1**2])
+
+    """
+    rels = C._reidemeister_relators
+    rels.sort(reverse=True)
+    gens = C._schreier_generators
+    for i in range(len(gens) - 1, -1, -1):
+        rel = rels[i]
+        for j in range(len(gens) - 1, -1, -1):
+            gen = gens[j]
+            if rel.generator_count(gen) == 1:
+                k = rel.exponent_sum(gen)
+                gen_index = rel.index(gen**k)
+                bk = rel.subword(gen_index + 1, len(rel))
+                fw = rel.subword(0, gen_index)
+                rep_by = (bk*fw)**(-1*k)
+                del rels[i]; del gens[j]
+                for l in range(len(rels)):
+                    rels[l] = rels[l].eliminate_word(gen, rep_by)
+                break
+    C._reidemeister_relators = rels
+    C._schreier_generators = gens
+    return C._schreier_generators, C._reidemeister_relators
+
+def reidemeister_presentation(fp_grp, H, C=None, homomorphism=False):
+    """
+    Parameters
+    ==========
+
+    fp_group: A finitely presented group, an instance of FpGroup
+    H: A subgroup whose presentation is to be found, given as a list
+    of words in generators of `fp_grp`
+    homomorphism: When set to True, return a homomorphism from the subgroup
+                    to the parent group
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics import free_group
+    >>> from sympy.combinatorics.fp_groups import FpGroup, reidemeister_presentation
+    >>> F, x, y = free_group("x, y")
+
+    Example 5.6 Pg. 177 from [1]
+    >>> f = FpGroup(F, [x**3, y**5, (x*y)**2])
+    >>> H = [x*y, x**-1*y**-1*x*y*x]
+    >>> reidemeister_presentation(f, H)
+    ((y_1, y_2), (y_1**2, y_2**3, y_2*y_1*y_2*y_1*y_2*y_1))
+
+    Example 5.8 Pg. 183 from [1]
+    >>> f = FpGroup(F, [x**3, y**3, (x*y)**3])
+    >>> H = [x*y, x*y**-1]
+    >>> reidemeister_presentation(f, H)
+    ((x_0, y_0), (x_0**3, y_0**3, x_0*y_0*x_0*y_0*x_0*y_0))
+
+    Exercises Q2. Pg 187 from [1]
+    >>> f = FpGroup(F, [x**2*y**2, y**-1*x*y*x**-3])
+    >>> H = [x]
+    >>> reidemeister_presentation(f, H)
+    ((x_0,), (x_0**4,))
+
+    Example 5.9 Pg. 183 from [1]
+    >>> f = FpGroup(F, [x**3*y**-3, (x*y)**3, (x*y**-1)**2])
+    >>> H = [x]
+    >>> reidemeister_presentation(f, H)
+    ((x_0,), (x_0**6,))
+
+    """
+    if not C:
+        C = coset_enumeration_r(fp_grp, H)
+    C.compress(); C.standardize()
+    define_schreier_generators(C, homomorphism=homomorphism)
+    reidemeister_relators(C)
+    gens, rels = C._schreier_generators, C._reidemeister_relators
+    gens, rels = simplify_presentation(gens, rels, change_gens=True)
+
+    C.schreier_generators = tuple(gens)
+    C.reidemeister_relators = tuple(rels)
+
+    if homomorphism:
+        _gens = []
+        for gen in gens:
+            _gens.append(C._schreier_gen_elem[str(gen)])
+        return C.schreier_generators, C.reidemeister_relators, _gens
+
+    return C.schreier_generators, C.reidemeister_relators
+
+
+FpGroupElement = FreeGroupElement

lib/python3.12/site-packages/sympy/combinatorics/free_groups.py

@@ -0,0 +1,1354 @@
+from __future__ import annotations
+
+from sympy.core import S
+from sympy.core.expr import Expr
+from sympy.core.symbol import Symbol, symbols as _symbols
+from sympy.core.sympify import CantSympify
+from sympy.printing.defaults import DefaultPrinting
+from sympy.utilities import public
+from sympy.utilities.iterables import flatten, is_sequence
+from sympy.utilities.magic import pollute
+from sympy.utilities.misc import as_int
+
+
+@public
+def free_group(symbols):
+    """Construct a free group returning ``(FreeGroup, (f_0, f_1, ..., f_(n-1))``.
+
+    Parameters
+    ==========
+
+    symbols : str, Symbol/Expr or sequence of str, Symbol/Expr (may be empty)
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics import free_group
+    >>> F, x, y, z = free_group("x, y, z")
+    >>> F
+    <free group on the generators (x, y, z)>
+    >>> x**2*y**-1
+    x**2*y**-1
+    >>> type(_)
+    <class 'sympy.combinatorics.free_groups.FreeGroupElement'>
+
+    """
+    _free_group = FreeGroup(symbols)
+    return (_free_group,) + tuple(_free_group.generators)
+
+@public
+def xfree_group(symbols):
+    """Construct a free group returning ``(FreeGroup, (f_0, f_1, ..., f_(n-1)))``.
+
+    Parameters
+    ==========
+
+    symbols : str, Symbol/Expr or sequence of str, Symbol/Expr (may be empty)
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.free_groups import xfree_group
+    >>> F, (x, y, z) = xfree_group("x, y, z")
+    >>> F
+    <free group on the generators (x, y, z)>
+    >>> y**2*x**-2*z**-1
+    y**2*x**-2*z**-1
+    >>> type(_)
+    <class 'sympy.combinatorics.free_groups.FreeGroupElement'>
+
+    """
+    _free_group = FreeGroup(symbols)
+    return (_free_group, _free_group.generators)
+
+@public
+def vfree_group(symbols):
+    """Construct a free group and inject ``f_0, f_1, ..., f_(n-1)`` as symbols
+    into the global namespace.
+
+    Parameters
+    ==========
+
+    symbols : str, Symbol/Expr or sequence of str, Symbol/Expr (may be empty)
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.free_groups import vfree_group
+    >>> vfree_group("x, y, z")
+    <free group on the generators (x, y, z)>
+    >>> x**2*y**-2*z # noqa: F821
+    x**2*y**-2*z
+    >>> type(_)
+    <class 'sympy.combinatorics.free_groups.FreeGroupElement'>
+
+    """
+    _free_group = FreeGroup(symbols)
+    pollute([sym.name for sym in _free_group.symbols], _free_group.generators)
+    return _free_group
+
+
+def _parse_symbols(symbols):
+    if not symbols:
+        return ()
+    if isinstance(symbols, str):
+        return _symbols(symbols, seq=True)
+    elif isinstance(symbols, (Expr, FreeGroupElement)):
+        return (symbols,)
+    elif is_sequence(symbols):
+        if all(isinstance(s, str) for s in symbols):
+            return _symbols(symbols)
+        elif all(isinstance(s, Expr) for s in symbols):
+            return symbols
+    raise ValueError("The type of `symbols` must be one of the following: "
+                     "a str, Symbol/Expr or a sequence of "
+                     "one of these types")
+
+
+##############################################################################
+#                          FREE GROUP                                        #
+##############################################################################
+
+_free_group_cache: dict[int, FreeGroup] = {}
+
+class FreeGroup(DefaultPrinting):
+    """
+    Free group with finite or infinite number of generators. Its input API
+    is that of a str, Symbol/Expr or a sequence of one of
+    these types (which may be empty)
+
+    See Also
+    ========
+
+    sympy.polys.rings.PolyRing
+
+    References
+    ==========
+
+    .. [1] https://www.gap-system.org/Manuals/doc/ref/chap37.html
+
+    .. [2] https://en.wikipedia.org/wiki/Free_group
+
+    """
+    is_associative = True
+    is_group = True
+    is_FreeGroup = True
+    is_PermutationGroup = False
+    relators: list[Expr] = []
+
+    def __new__(cls, symbols):
+        symbols = tuple(_parse_symbols(symbols))
+        rank = len(symbols)
+        _hash = hash((cls.__name__, symbols, rank))
+        obj = _free_group_cache.get(_hash)
+
+        if obj is None:
+            obj = object.__new__(cls)
+            obj._hash = _hash
+            obj._rank = rank
+            # dtype method is used to create new instances of FreeGroupElement
+            obj.dtype = type("FreeGroupElement", (FreeGroupElement,), {"group": obj})
+            obj.symbols = symbols
+            obj.generators = obj._generators()
+            obj._gens_set = set(obj.generators)
+            for symbol, generator in zip(obj.symbols, obj.generators):
+                if isinstance(symbol, Symbol):
+                    name = symbol.name
+                    if hasattr(obj, name):
+                        setattr(obj, name, generator)
+
+            _free_group_cache[_hash] = obj
+
+        return obj
+
+    def _generators(group):
+        """Returns the generators of the FreeGroup.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> F, x, y, z = free_group("x, y, z")
+        >>> F.generators
+        (x, y, z)
+
+        """
+        gens = []
+        for sym in group.symbols:
+            elm = ((sym, 1),)
+            gens.append(group.dtype(elm))
+        return tuple(gens)
+
+    def clone(self, symbols=None):
+        return self.__class__(symbols or self.symbols)
+
+    def __contains__(self, i):
+        """Return True if ``i`` is contained in FreeGroup."""
+        if not isinstance(i, FreeGroupElement):
+            return False
+        group = i.group
+        return self == group
+
+    def __hash__(self):
+        return self._hash
+
+    def __len__(self):
+        return self.rank
+
+    def __str__(self):
+        if self.rank > 30:
+            str_form = "<free group with %s generators>" % self.rank
+        else:
+            str_form = "<free group on the generators "
+            gens = self.generators
+            str_form += str(gens) + ">"
+        return str_form
+
+    __repr__ = __str__
+
+    def __getitem__(self, index):
+        symbols = self.symbols[index]
+        return self.clone(symbols=symbols)
+
+    def __eq__(self, other):
+        """No ``FreeGroup`` is equal to any "other" ``FreeGroup``.
+        """
+        return self is other
+
+    def index(self, gen):
+        """Return the index of the generator `gen` from ``(f_0, ..., f_(n-1))``.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> F, x, y = free_group("x, y")
+        >>> F.index(y)
+        1
+        >>> F.index(x)
+        0
+
+        """
+        if isinstance(gen, self.dtype):
+            return self.generators.index(gen)
+        else:
+            raise ValueError("expected a generator of Free Group %s, got %s" % (self, gen))
+
+    def order(self):
+        """Return the order of the free group.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> F, x, y = free_group("x, y")
+        >>> F.order()
+        oo
+
+        >>> free_group("")[0].order()
+        1
+
+        """
+        if self.rank == 0:
+            return S.One
+        else:
+            return S.Infinity
+
+    @property
+    def elements(self):
+        """
+        Return the elements of the free group.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> (z,) = free_group("")
+        >>> z.elements
+        {<identity>}
+
+        """
+        if self.rank == 0:
+            # A set containing Identity element of `FreeGroup` self is returned
+            return {self.identity}
+        else:
+            raise ValueError("Group contains infinitely many elements"
+                            ", hence cannot be represented")
+
+    @property
+    def rank(self):
+        r"""
+        In group theory, the `rank` of a group `G`, denoted `G.rank`,
+        can refer to the smallest cardinality of a generating set
+        for G, that is
+
+        \operatorname{rank}(G)=\min\{ |X|: X\subseteq G, \left\langle X\right\rangle =G\}.
+
+        """
+        return self._rank
+
+    @property
+    def is_abelian(self):
+        """Returns if the group is Abelian.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> f, x, y, z = free_group("x y z")
+        >>> f.is_abelian
+        False
+
+        """
+        return self.rank in (0, 1)
+
+    @property
+    def identity(self):
+        """Returns the identity element of free group."""
+        return self.dtype()
+
+    def contains(self, g):
+        """Tests if Free Group element ``g`` belong to self, ``G``.
+
+        In mathematical terms any linear combination of generators
+        of a Free Group is contained in it.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> f, x, y, z = free_group("x y z")
+        >>> f.contains(x**3*y**2)
+        True
+
+        """
+        if not isinstance(g, FreeGroupElement):
+            return False
+        elif self != g.group:
+            return False
+        else:
+            return True
+
+    def center(self):
+        """Returns the center of the free group `self`."""
+        return {self.identity}
+
+
+############################################################################
+#                          FreeGroupElement                                #
+############################################################################
+
+
+class FreeGroupElement(CantSympify, DefaultPrinting, tuple):
+    """Used to create elements of FreeGroup. It cannot be used directly to
+    create a free group element. It is called by the `dtype` method of the
+    `FreeGroup` class.
+
+    """
+    is_assoc_word = True
+
+    def new(self, init):
+        return self.__class__(init)
+
+    _hash = None
+
+    def __hash__(self):
+        _hash = self._hash
+        if _hash is None:
+            self._hash = _hash = hash((self.group, frozenset(tuple(self))))
+        return _hash
+
+    def copy(self):
+        return self.new(self)
+
+    @property
+    def is_identity(self):
+        if self.array_form == ():
+            return True
+        else:
+            return False
+
+    @property
+    def array_form(self):
+        """
+        SymPy provides two different internal kinds of representation
+        of associative words. The first one is called the `array_form`
+        which is a tuple containing `tuples` as its elements, where the
+        size of each tuple is two. At the first position the tuple
+        contains the `symbol-generator`, while at the second position
+        of tuple contains the exponent of that generator at the position.
+        Since elements (i.e. words) do not commute, the indexing of tuple
+        makes that property to stay.
+
+        The structure in ``array_form`` of ``FreeGroupElement`` is of form:
+
+        ``( ( symbol_of_gen, exponent ), ( , ), ... ( , ) )``
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> f, x, y, z = free_group("x y z")
+        >>> (x*z).array_form
+        ((x, 1), (z, 1))
+        >>> (x**2*z*y*x**2).array_form
+        ((x, 2), (z, 1), (y, 1), (x, 2))
+
+        See Also
+        ========
+
+        letter_repr
+
+        """
+        return tuple(self)
+
+    @property
+    def letter_form(self):
+        """
+        The letter representation of a ``FreeGroupElement`` is a tuple
+        of generator symbols, with each entry corresponding to a group
+        generator. Inverses of the generators are represented by
+        negative generator symbols.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> f, a, b, c, d = free_group("a b c d")
+        >>> (a**3).letter_form
+        (a, a, a)
+        >>> (a**2*d**-2*a*b**-4).letter_form
+        (a, a, -d, -d, a, -b, -b, -b, -b)
+        >>> (a**-2*b**3*d).letter_form
+        (-a, -a, b, b, b, d)
+
+        See Also
+        ========
+
+        array_form
+
+        """
+        return tuple(flatten([(i,)*j if j > 0 else (-i,)*(-j)
+                    for i, j in self.array_form]))
+
+    def __getitem__(self, i):
+        group = self.group
+        r = self.letter_form[i]
+        if r.is_Symbol:
+            return group.dtype(((r, 1),))
+        else:
+            return group.dtype(((-r, -1),))
+
+    def index(self, gen):
+        if len(gen) != 1:
+            raise ValueError()
+        return (self.letter_form).index(gen.letter_form[0])
+
+    @property
+    def letter_form_elm(self):
+        """
+        """
+        group = self.group
+        r = self.letter_form
+        return [group.dtype(((elm,1),)) if elm.is_Symbol \
+                else group.dtype(((-elm,-1),)) for elm in r]
+
+    @property
+    def ext_rep(self):
+        """This is called the External Representation of ``FreeGroupElement``
+        """
+        return tuple(flatten(self.array_form))
+
+    def __contains__(self, gen):
+        return gen.array_form[0][0] in tuple([r[0] for r in self.array_form])
+
+    def __str__(self):
+        if self.is_identity:
+            return "<identity>"
+
+        str_form = ""
+        array_form = self.array_form
+        for i in range(len(array_form)):
+            if i == len(array_form) - 1:
+                if array_form[i][1] == 1:
+                    str_form += str(array_form[i][0])
+                else:
+                    str_form += str(array_form[i][0]) + \
+                                    "**" + str(array_form[i][1])
+            else:
+                if array_form[i][1] == 1:
+                    str_form += str(array_form[i][0]) + "*"
+                else:
+                    str_form += str(array_form[i][0]) + \
+                                    "**" + str(array_form[i][1]) + "*"
+        return str_form
+
+    __repr__ = __str__
+
+    def __pow__(self, n):
+        n = as_int(n)
+        result = self.group.identity
+        if n == 0:
+            return result
+        if n < 0:
+            n = -n
+            x = self.inverse()
+        else:
+            x = self
+        while True:
+            if n % 2:
+                result *= x
+            n >>= 1
+            if not n:
+                break
+            x *= x
+        return result
+
+    def __mul__(self, other):
+        """Returns the product of elements belonging to the same ``FreeGroup``.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> f, x, y, z = free_group("x y z")
+        >>> x*y**2*y**-4
+        x*y**-2
+        >>> z*y**-2
+        z*y**-2
+        >>> x**2*y*y**-1*x**-2
+        <identity>
+
+        """
+        group = self.group
+        if not isinstance(other, group.dtype):
+            raise TypeError("only FreeGroup elements of same FreeGroup can "
+                    "be multiplied")
+        if self.is_identity:
+            return other
+        if other.is_identity:
+            return self
+        r = list(self.array_form + other.array_form)
+        zero_mul_simp(r, len(self.array_form) - 1)
+        return group.dtype(tuple(r))
+
+    def __truediv__(self, other):
+        group = self.group
+        if not isinstance(other, group.dtype):
+            raise TypeError("only FreeGroup elements of same FreeGroup can "
+                    "be multiplied")
+        return self*(other.inverse())
+
+    def __rtruediv__(self, other):
+        group = self.group
+        if not isinstance(other, group.dtype):
+            raise TypeError("only FreeGroup elements of same FreeGroup can "
+                    "be multiplied")
+        return other*(self.inverse())
+
+    def __add__(self, other):
+        return NotImplemented
+
+    def inverse(self):
+        """
+        Returns the inverse of a ``FreeGroupElement`` element
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> f, x, y, z = free_group("x y z")
+        >>> x.inverse()
+        x**-1
+        >>> (x*y).inverse()
+        y**-1*x**-1
+
+        """
+        group = self.group
+        r = tuple([(i, -j) for i, j in self.array_form[::-1]])
+        return group.dtype(r)
+
+    def order(self):
+        """Find the order of a ``FreeGroupElement``.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> f, x, y = free_group("x y")
+        >>> (x**2*y*y**-1*x**-2).order()
+        1
+
+        """
+        if self.is_identity:
+            return S.One
+        else:
+            return S.Infinity
+
+    def commutator(self, other):
+        """
+        Return the commutator of `self` and `x`: ``~x*~self*x*self``
+
+        """
+        group = self.group
+        if not isinstance(other, group.dtype):
+            raise ValueError("commutator of only FreeGroupElement of the same "
+                    "FreeGroup exists")
+        else:
+            return self.inverse()*other.inverse()*self*other
+
+    def eliminate_words(self, words, _all=False, inverse=True):
+        '''
+        Replace each subword from the dictionary `words` by words[subword].
+        If words is a list, replace the words by the identity.
+
+        '''
+        again = True
+        new = self
+        if isinstance(words, dict):
+            while again:
+                again = False
+                for sub in words:
+                    prev = new
+                    new = new.eliminate_word(sub, words[sub], _all=_all, inverse=inverse)
+                    if new != prev:
+                        again = True
+        else:
+            while again:
+                again = False
+                for sub in words:
+                    prev = new
+                    new = new.eliminate_word(sub, _all=_all, inverse=inverse)
+                    if new != prev:
+                        again = True
+        return new
+
+    def eliminate_word(self, gen, by=None, _all=False, inverse=True):
+        """
+        For an associative word `self`, a subword `gen`, and an associative
+        word `by` (identity by default), return the associative word obtained by
+        replacing each occurrence of `gen` in `self` by `by`. If `_all = True`,
+        the occurrences of `gen` that may appear after the first substitution will
+        also be replaced and so on until no occurrences are found. This might not
+        always terminate (e.g. `(x).eliminate_word(x, x**2, _all=True)`).
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> f, x, y = free_group("x y")
+        >>> w = x**5*y*x**2*y**-4*x
+        >>> w.eliminate_word( x, x**2 )
+        x**10*y*x**4*y**-4*x**2
+        >>> w.eliminate_word( x, y**-1 )
+        y**-11
+        >>> w.eliminate_word(x**5)
+        y*x**2*y**-4*x
+        >>> w.eliminate_word(x*y, y)
+        x**4*y*x**2*y**-4*x
+
+        See Also
+        ========
+        substituted_word
+
+        """
+        if by is None:
+            by = self.group.identity
+        if self.is_independent(gen) or gen == by:
+            return self
+        if gen == self:
+            return by
+        if gen**-1 == by:
+            _all = False
+        word = self
+        l = len(gen)
+
+        try:
+            i = word.subword_index(gen)
+            k = 1
+        except ValueError:
+            if not inverse:
+                return word
+            try:
+                i = word.subword_index(gen**-1)
+                k = -1
+            except ValueError:
+                return word
+
+        word = word.subword(0, i)*by**k*word.subword(i+l, len(word)).eliminate_word(gen, by)
+
+        if _all:
+            return word.eliminate_word(gen, by, _all=True, inverse=inverse)
+        else:
+            return word
+
+    def __len__(self):
+        """
+        For an associative word `self`, returns the number of letters in it.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> f, a, b = free_group("a b")
+        >>> w = a**5*b*a**2*b**-4*a
+        >>> len(w)
+        13
+        >>> len(a**17)
+        17
+        >>> len(w**0)
+        0
+
+        """
+        return sum(abs(j) for (i, j) in self)
+
+    def __eq__(self, other):
+        """
+        Two  associative words are equal if they are words over the
+        same alphabet and if they are sequences of the same letters.
+        This is equivalent to saying that the external representations
+        of the words are equal.
+        There is no "universal" empty word, every alphabet has its own
+        empty word.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> f, swapnil0, swapnil1 = free_group("swapnil0 swapnil1")
+        >>> f
+        <free group on the generators (swapnil0, swapnil1)>
+        >>> g, swap0, swap1 = free_group("swap0 swap1")
+        >>> g
+        <free group on the generators (swap0, swap1)>
+
+        >>> swapnil0 == swapnil1
+        False
+        >>> swapnil0*swapnil1 == swapnil1/swapnil1*swapnil0*swapnil1
+        True
+        >>> swapnil0*swapnil1 == swapnil1*swapnil0
+        False
+        >>> swapnil1**0 == swap0**0
+        False
+
+        """
+        group = self.group
+        if not isinstance(other, group.dtype):
+            return False
+        return tuple.__eq__(self, other)
+
+    def __lt__(self, other):
+        """
+        The  ordering  of  associative  words is defined by length and
+        lexicography (this ordering is called short-lex ordering), that
+        is, shorter words are smaller than longer words, and words of the
+        same length are compared w.r.t. the lexicographical ordering induced
+        by the ordering of generators. Generators  are  sorted  according
+        to the order in which they were created. If the generators are
+        invertible then each generator `g` is larger than its inverse `g^{-1}`,
+        and `g^{-1}` is larger than every generator that is smaller than `g`.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> f, a, b = free_group("a b")
+        >>> b < a
+        False
+        >>> a < a.inverse()
+        False
+
+        """
+        group = self.group
+        if not isinstance(other, group.dtype):
+            raise TypeError("only FreeGroup elements of same FreeGroup can "
+                             "be compared")
+        l = len(self)
+        m = len(other)
+        # implement lenlex order
+        if l < m:
+            return True
+        elif l > m:
+            return False
+        for i in range(l):
+            a = self[i].array_form[0]
+            b = other[i].array_form[0]
+            p = group.symbols.index(a[0])
+            q = group.symbols.index(b[0])
+            if p < q:
+                return True
+            elif p > q:
+                return False
+            elif a[1] < b[1]:
+                return True
+            elif a[1] > b[1]:
+                return False
+        return False
+
+    def __le__(self, other):
+        return (self == other or self < other)
+
+    def __gt__(self, other):
+        """
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> f, x, y, z = free_group("x y z")
+        >>> y**2 > x**2
+        True
+        >>> y*z > z*y
+        False
+        >>> x > x.inverse()
+        True
+
+        """
+        group = self.group
+        if not isinstance(other, group.dtype):
+            raise TypeError("only FreeGroup elements of same FreeGroup can "
+                             "be compared")
+        return not self <= other
+
+    def __ge__(self, other):
+        return not self < other
+
+    def exponent_sum(self, gen):
+        """
+        For an associative word `self` and a generator or inverse of generator
+        `gen`, ``exponent_sum`` returns the number of times `gen` appears in
+        `self` minus the number of times its inverse appears in `self`. If
+        neither `gen` nor its inverse occur in `self` then 0 is returned.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> F, x, y = free_group("x, y")
+        >>> w = x**2*y**3
+        >>> w.exponent_sum(x)
+        2
+        >>> w.exponent_sum(x**-1)
+        -2
+        >>> w = x**2*y**4*x**-3
+        >>> w.exponent_sum(x)
+        -1
+
+        See Also
+        ========
+
+        generator_count
+
+        """
+        if len(gen) != 1:
+            raise ValueError("gen must be a generator or inverse of a generator")
+        s = gen.array_form[0]
+        return s[1]*sum(i[1] for i in self.array_form if i[0] == s[0])
+
+    def generator_count(self, gen):
+        """
+        For an associative word `self` and a generator `gen`,
+        ``generator_count`` returns the multiplicity of generator
+        `gen` in `self`.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> F, x, y = free_group("x, y")
+        >>> w = x**2*y**3
+        >>> w.generator_count(x)
+        2
+        >>> w = x**2*y**4*x**-3
+        >>> w.generator_count(x)
+        5
+
+        See Also
+        ========
+
+        exponent_sum
+
+        """
+        if len(gen) != 1 or gen.array_form[0][1] < 0:
+            raise ValueError("gen must be a generator")
+        s = gen.array_form[0]
+        return s[1]*sum(abs(i[1]) for i in self.array_form if i[0] == s[0])
+
+    def subword(self, from_i, to_j, strict=True):
+        """
+        For an associative word `self` and two positive integers `from_i` and
+        `to_j`, `subword` returns the subword of `self` that begins at position
+        `from_i` and ends at `to_j - 1`, indexing is done with origin 0.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> f, a, b = free_group("a b")
+        >>> w = a**5*b*a**2*b**-4*a
+        >>> w.subword(2, 6)
+        a**3*b
+
+        """
+        group = self.group
+        if not strict:
+            from_i = max(from_i, 0)
+            to_j = min(len(self), to_j)
+        if from_i < 0 or to_j > len(self):
+            raise ValueError("`from_i`, `to_j` must be positive and no greater than "
+                    "the length of associative word")
+        if to_j <= from_i:
+            return group.identity
+        else:
+            letter_form = self.letter_form[from_i: to_j]
+            array_form = letter_form_to_array_form(letter_form, group)
+            return group.dtype(array_form)
+
+    def subword_index(self, word, start = 0):
+        '''
+        Find the index of `word` in `self`.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> f, a, b = free_group("a b")
+        >>> w = a**2*b*a*b**3
+        >>> w.subword_index(a*b*a*b)
+        1
+
+        '''
+        l = len(word)
+        self_lf = self.letter_form
+        word_lf = word.letter_form
+        index = None
+        for i in range(start,len(self_lf)-l+1):
+            if self_lf[i:i+l] == word_lf:
+                index = i
+                break
+        if index is not None:
+            return index
+        else:
+            raise ValueError("The given word is not a subword of self")
+
+    def is_dependent(self, word):
+        """
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> F, x, y = free_group("x, y")
+        >>> (x**4*y**-3).is_dependent(x**4*y**-2)
+        True
+        >>> (x**2*y**-1).is_dependent(x*y)
+        False
+        >>> (x*y**2*x*y**2).is_dependent(x*y**2)
+        True
+        >>> (x**12).is_dependent(x**-4)
+        True
+
+        See Also
+        ========
+
+        is_independent
+
+        """
+        try:
+            return self.subword_index(word) is not None
+        except ValueError:
+            pass
+        try:
+            return self.subword_index(word**-1) is not None
+        except ValueError:
+            return False
+
+    def is_independent(self, word):
+        """
+
+        See Also
+        ========
+
+        is_dependent
+
+        """
+        return not self.is_dependent(word)
+
+    def contains_generators(self):
+        """
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> F, x, y, z = free_group("x, y, z")
+        >>> (x**2*y**-1).contains_generators()
+        {x, y}
+        >>> (x**3*z).contains_generators()
+        {x, z}
+
+        """
+        group = self.group
+        gens = {group.dtype(((syllable[0], 1),)) for syllable in self.array_form}
+        return gens
+
+    def cyclic_subword(self, from_i, to_j):
+        group = self.group
+        l = len(self)
+        letter_form = self.letter_form
+        period1 = int(from_i/l)
+        if from_i >= l:
+            from_i -= l*period1
+            to_j -= l*period1
+        diff = to_j - from_i
+        word = letter_form[from_i: to_j]
+        period2 = int(to_j/l) - 1
+        word += letter_form*period2 + letter_form[:diff-l+from_i-l*period2]
+        word = letter_form_to_array_form(word, group)
+        return group.dtype(word)
+
+    def cyclic_conjugates(self):
+        """Returns a words which are cyclic to the word `self`.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> F, x, y = free_group("x, y")
+        >>> w = x*y*x*y*x
+        >>> w.cyclic_conjugates()
+        {x*y*x**2*y, x**2*y*x*y, y*x*y*x**2, y*x**2*y*x, x*y*x*y*x}
+        >>> s = x*y*x**2*y*x
+        >>> s.cyclic_conjugates()
+        {x**2*y*x**2*y, y*x**2*y*x**2, x*y*x**2*y*x}
+
+        References
+        ==========
+
+        .. [1] https://planetmath.org/cyclicpermutation
+
+        """
+        return {self.cyclic_subword(i, i+len(self)) for i in range(len(self))}
+
+    def is_cyclic_conjugate(self, w):
+        """
+        Checks whether words ``self``, ``w`` are cyclic conjugates.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> F, x, y = free_group("x, y")
+        >>> w1 = x**2*y**5
+        >>> w2 = x*y**5*x
+        >>> w1.is_cyclic_conjugate(w2)
+        True
+        >>> w3 = x**-1*y**5*x**-1
+        >>> w3.is_cyclic_conjugate(w2)
+        False
+
+        """
+        l1 = len(self)
+        l2 = len(w)
+        if l1 != l2:
+            return False
+        w1 = self.identity_cyclic_reduction()
+        w2 = w.identity_cyclic_reduction()
+        letter1 = w1.letter_form
+        letter2 = w2.letter_form
+        str1 = ' '.join(map(str, letter1))
+        str2 = ' '.join(map(str, letter2))
+        if len(str1) != len(str2):
+            return False
+
+        return str1 in str2 + ' ' + str2
+
+    def number_syllables(self):
+        """Returns the number of syllables of the associative word `self`.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> f, swapnil0, swapnil1 = free_group("swapnil0 swapnil1")
+        >>> (swapnil1**3*swapnil0*swapnil1**-1).number_syllables()
+        3
+
+        """
+        return len(self.array_form)
+
+    def exponent_syllable(self, i):
+        """
+        Returns the exponent of the `i`-th syllable of the associative word
+        `self`.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> f, a, b = free_group("a b")
+        >>> w = a**5*b*a**2*b**-4*a
+        >>> w.exponent_syllable( 2 )
+        2
+
+        """
+        return self.array_form[i][1]
+
+    def generator_syllable(self, i):
+        """
+        Returns the symbol of the generator that is involved in the
+        i-th syllable of the associative word `self`.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> f, a, b = free_group("a b")
+        >>> w = a**5*b*a**2*b**-4*a
+        >>> w.generator_syllable( 3 )
+        b
+
+        """
+        return self.array_form[i][0]
+
+    def sub_syllables(self, from_i, to_j):
+        """
+        `sub_syllables` returns the subword of the associative word `self` that
+        consists of syllables from positions `from_to` to `to_j`, where
+        `from_to` and `to_j` must be positive integers and indexing is done
+        with origin 0.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> f, a, b = free_group("a, b")
+        >>> w = a**5*b*a**2*b**-4*a
+        >>> w.sub_syllables(1, 2)
+        b
+        >>> w.sub_syllables(3, 3)
+        <identity>
+
+        """
+        if not isinstance(from_i, int) or not isinstance(to_j, int):
+            raise ValueError("both arguments should be integers")
+        group = self.group
+        if to_j <= from_i:
+            return group.identity
+        else:
+            r = tuple(self.array_form[from_i: to_j])
+            return group.dtype(r)
+
+    def substituted_word(self, from_i, to_j, by):
+        """
+        Returns the associative word obtained by replacing the subword of
+        `self` that begins at position `from_i` and ends at position `to_j - 1`
+        by the associative word `by`. `from_i` and `to_j` must be positive
+        integers, indexing is done with origin 0. In other words,
+        `w.substituted_word(w, from_i, to_j, by)` is the product of the three
+        words: `w.subword(0, from_i)`, `by`, and
+        `w.subword(to_j len(w))`.
+
+        See Also
+        ========
+
+        eliminate_word
+
+        """
+        lw = len(self)
+        if from_i >= to_j or from_i > lw or to_j > lw:
+            raise ValueError("values should be within bounds")
+
+        # otherwise there are four possibilities
+
+        # first if from=1 and to=lw then
+        if from_i == 0 and to_j == lw:
+            return by
+        elif from_i == 0:  # second if from_i=1 (and to_j < lw) then
+            return by*self.subword(to_j, lw)
+        elif to_j == lw:   # third if to_j=1 (and from_i > 1) then
+            return self.subword(0, from_i)*by
+        else:              # finally
+            return self.subword(0, from_i)*by*self.subword(to_j, lw)
+
+    def is_cyclically_reduced(self):
+        r"""Returns whether the word is cyclically reduced or not.
+        A word is cyclically reduced if by forming the cycle of the
+        word, the word is not reduced, i.e a word w = `a_1 ... a_n`
+        is called cyclically reduced if `a_1 \ne a_n^{-1}`.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> F, x, y = free_group("x, y")
+        >>> (x**2*y**-1*x**-1).is_cyclically_reduced()
+        False
+        >>> (y*x**2*y**2).is_cyclically_reduced()
+        True
+
+        """
+        if not self:
+            return True
+        return self[0] != self[-1]**-1
+
+    def identity_cyclic_reduction(self):
+        """Return a unique cyclically reduced version of the word.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> F, x, y = free_group("x, y")
+        >>> (x**2*y**2*x**-1).identity_cyclic_reduction()
+        x*y**2
+        >>> (x**-3*y**-1*x**5).identity_cyclic_reduction()
+        x**2*y**-1
+
+        References
+        ==========
+
+        .. [1] https://planetmath.org/cyclicallyreduced
+
+        """
+        word = self.copy()
+        group = self.group
+        while not word.is_cyclically_reduced():
+            exp1 = word.exponent_syllable(0)
+            exp2 = word.exponent_syllable(-1)
+            r = exp1 + exp2
+            if r == 0:
+                rep = word.array_form[1: word.number_syllables() - 1]
+            else:
+                rep = ((word.generator_syllable(0), exp1 + exp2),) + \
+                        word.array_form[1: word.number_syllables() - 1]
+            word = group.dtype(rep)
+        return word
+
+    def cyclic_reduction(self, removed=False):
+        """Return a cyclically reduced version of the word. Unlike
+        `identity_cyclic_reduction`, this will not cyclically permute
+        the reduced word - just remove the "unreduced" bits on either
+        side of it. Compare the examples with those of
+        `identity_cyclic_reduction`.
+
+        When `removed` is `True`, return a tuple `(word, r)` where
+        self `r` is such that before the reduction the word was either
+        `r*word*r**-1`.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> F, x, y = free_group("x, y")
+        >>> (x**2*y**2*x**-1).cyclic_reduction()
+        x*y**2
+        >>> (x**-3*y**-1*x**5).cyclic_reduction()
+        y**-1*x**2
+        >>> (x**-3*y**-1*x**5).cyclic_reduction(removed=True)
+        (y**-1*x**2, x**-3)
+
+        """
+        word = self.copy()
+        g = self.group.identity
+        while not word.is_cyclically_reduced():
+            exp1 = abs(word.exponent_syllable(0))
+            exp2 = abs(word.exponent_syllable(-1))
+            exp = min(exp1, exp2)
+            start = word[0]**abs(exp)
+            end = word[-1]**abs(exp)
+            word = start**-1*word*end**-1
+            g = g*start
+        if removed:
+            return word, g
+        return word
+
+    def power_of(self, other):
+        '''
+        Check if `self == other**n` for some integer n.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import free_group
+        >>> F, x, y = free_group("x, y")
+        >>> ((x*y)**2).power_of(x*y)
+        True
+        >>> (x**-3*y**-2*x**3).power_of(x**-3*y*x**3)
+        True
+
+        '''
+        if self.is_identity:
+            return True
+
+        l = len(other)
+        if l == 1:
+            # self has to be a power of one generator
+            gens = self.contains_generators()
+            s = other in gens or other**-1 in gens
+            return len(gens) == 1 and s
+
+        # if self is not cyclically reduced and it is a power of other,
+        # other isn't cyclically reduced and the parts removed during
+        # their reduction must be equal
+        reduced, r1 = self.cyclic_reduction(removed=True)
+        if not r1.is_identity:
+            other, r2 = other.cyclic_reduction(removed=True)
+            if r1 == r2:
+                return reduced.power_of(other)
+            return False
+
+        if len(self) < l or len(self) % l:
+            return False
+
+        prefix = self.subword(0, l)
+        if prefix == other or prefix**-1 == other:
+            rest = self.subword(l, len(self))
+            return rest.power_of(other)
+        return False
+
+
+def letter_form_to_array_form(array_form, group):
+    """
+    This method converts a list given with possible repetitions of elements in
+    it. It returns a new list such that repetitions of consecutive elements is
+    removed and replace with a tuple element of size two such that the first
+    index contains `value` and the second index contains the number of
+    consecutive repetitions of `value`.
+
+    """
+    a = list(array_form[:])
+    new_array = []
+    n = 1
+    symbols = group.symbols
+    for i in range(len(a)):
+        if i == len(a) - 1:
+            if a[i] == a[i - 1]:
+                if (-a[i]) in symbols:
+                    new_array.append((-a[i], -n))
+                else:
+                    new_array.append((a[i], n))
+            else:
+                if (-a[i]) in symbols:
+                    new_array.append((-a[i], -1))
+                else:
+                    new_array.append((a[i], 1))
+            return new_array
+        elif a[i] == a[i + 1]:
+            n += 1
+        else:
+            if (-a[i]) in symbols:
+                new_array.append((-a[i], -n))
+            else:
+                new_array.append((a[i], n))
+            n = 1
+
+
+def zero_mul_simp(l, index):
+    """Used to combine two reduced words."""
+    while index >=0 and index < len(l) - 1 and l[index][0] == l[index + 1][0]:
+        exp = l[index][1] + l[index + 1][1]
+        base = l[index][0]
+        l[index] = (base, exp)
+        del l[index + 1]
+        if l[index][1] == 0:
+            del l[index]
+            index -= 1

lib/python3.12/site-packages/sympy/combinatorics/galois.py

@@ -0,0 +1,611 @@
+r"""
+Construct transitive subgroups of symmetric groups, useful in Galois theory.
+
+Besides constructing instances of the :py:class:`~.PermutationGroup` class to
+represent the transitive subgroups of $S_n$ for small $n$, this module provides
+*names* for these groups.
+
+In some applications, it may be preferable to know the name of a group,
+rather than receive an instance of the :py:class:`~.PermutationGroup`
+class, and then have to do extra work to determine which group it is, by
+checking various properties.
+
+Names are instances of ``Enum`` classes defined in this module. With a name in
+hand, the name's ``get_perm_group`` method can then be used to retrieve a
+:py:class:`~.PermutationGroup`.
+
+The names used for groups in this module are taken from [1].
+
+References
+==========
+
+.. [1] Cohen, H. *A Course in Computational Algebraic Number Theory*.
+
+"""
+
+from collections import defaultdict
+from enum import Enum
+import itertools
+
+from sympy.combinatorics.named_groups import (
+    SymmetricGroup, AlternatingGroup, CyclicGroup, DihedralGroup,
+    set_symmetric_group_properties, set_alternating_group_properties,
+)
+from sympy.combinatorics.perm_groups import PermutationGroup
+from sympy.combinatorics.permutations import Permutation
+
+
+class S1TransitiveSubgroups(Enum):
+    """
+    Names for the transitive subgroups of S1.
+    """
+    S1 = "S1"
+
+    def get_perm_group(self):
+        return SymmetricGroup(1)
+
+
+class S2TransitiveSubgroups(Enum):
+    """
+    Names for the transitive subgroups of S2.
+    """
+    S2 = "S2"
+
+    def get_perm_group(self):
+        return SymmetricGroup(2)
+
+
+class S3TransitiveSubgroups(Enum):
+    """
+    Names for the transitive subgroups of S3.
+    """
+    A3 = "A3"
+    S3 = "S3"
+
+    def get_perm_group(self):
+        if self == S3TransitiveSubgroups.A3:
+            return AlternatingGroup(3)
+        elif self == S3TransitiveSubgroups.S3:
+            return SymmetricGroup(3)
+
+
+class S4TransitiveSubgroups(Enum):
+    """
+    Names for the transitive subgroups of S4.
+    """
+    C4 = "C4"
+    V = "V"
+    D4 = "D4"
+    A4 = "A4"
+    S4 = "S4"
+
+    def get_perm_group(self):
+        if self == S4TransitiveSubgroups.C4:
+            return CyclicGroup(4)
+        elif self == S4TransitiveSubgroups.V:
+            return four_group()
+        elif self == S4TransitiveSubgroups.D4:
+            return DihedralGroup(4)
+        elif self == S4TransitiveSubgroups.A4:
+            return AlternatingGroup(4)
+        elif self == S4TransitiveSubgroups.S4:
+            return SymmetricGroup(4)
+
+
+class S5TransitiveSubgroups(Enum):
+    """
+    Names for the transitive subgroups of S5.
+    """
+    C5 = "C5"
+    D5 = "D5"
+    M20 = "M20"
+    A5 = "A5"
+    S5 = "S5"
+
+    def get_perm_group(self):
+        if self == S5TransitiveSubgroups.C5:
+            return CyclicGroup(5)
+        elif self == S5TransitiveSubgroups.D5:
+            return DihedralGroup(5)
+        elif self == S5TransitiveSubgroups.M20:
+            return M20()
+        elif self == S5TransitiveSubgroups.A5:
+            return AlternatingGroup(5)
+        elif self == S5TransitiveSubgroups.S5:
+            return SymmetricGroup(5)
+
+
+class S6TransitiveSubgroups(Enum):
+    """
+    Names for the transitive subgroups of S6.
+    """
+    C6 = "C6"
+    S3 = "S3"
+    D6 = "D6"
+    A4 = "A4"
+    G18 = "G18"
+    A4xC2 = "A4 x C2"
+    S4m = "S4-"
+    S4p = "S4+"
+    G36m = "G36-"
+    G36p = "G36+"
+    S4xC2 = "S4 x C2"
+    PSL2F5 = "PSL2(F5)"
+    G72 = "G72"
+    PGL2F5 = "PGL2(F5)"
+    A6 = "A6"
+    S6 = "S6"
+
+    def get_perm_group(self):
+        if self == S6TransitiveSubgroups.C6:
+            return CyclicGroup(6)
+        elif self == S6TransitiveSubgroups.S3:
+            return S3_in_S6()
+        elif self == S6TransitiveSubgroups.D6:
+            return DihedralGroup(6)
+        elif self == S6TransitiveSubgroups.A4:
+            return A4_in_S6()
+        elif self == S6TransitiveSubgroups.G18:
+            return G18()
+        elif self == S6TransitiveSubgroups.A4xC2:
+            return A4xC2()
+        elif self == S6TransitiveSubgroups.S4m:
+            return S4m()
+        elif self == S6TransitiveSubgroups.S4p:
+            return S4p()
+        elif self == S6TransitiveSubgroups.G36m:
+            return G36m()
+        elif self == S6TransitiveSubgroups.G36p:
+            return G36p()
+        elif self == S6TransitiveSubgroups.S4xC2:
+            return S4xC2()
+        elif self == S6TransitiveSubgroups.PSL2F5:
+            return PSL2F5()
+        elif self == S6TransitiveSubgroups.G72:
+            return G72()
+        elif self == S6TransitiveSubgroups.PGL2F5:
+            return PGL2F5()
+        elif self == S6TransitiveSubgroups.A6:
+            return AlternatingGroup(6)
+        elif self == S6TransitiveSubgroups.S6:
+            return SymmetricGroup(6)
+
+
+def four_group():
+    """
+    Return a representation of the Klein four-group as a transitive subgroup
+    of S4.
+    """
+    return PermutationGroup(
+        Permutation(0, 1)(2, 3),
+        Permutation(0, 2)(1, 3)
+    )
+
+
+def M20():
+    """
+    Return a representation of the metacyclic group M20, a transitive subgroup
+    of S5 that is one of the possible Galois groups for polys of degree 5.
+
+    Notes
+    =====
+
+    See [1], Page 323.
+
+    """
+    G = PermutationGroup(Permutation(0, 1, 2, 3, 4), Permutation(1, 2, 4, 3))
+    G._degree = 5
+    G._order = 20
+    G._is_transitive = True
+    G._is_sym = False
+    G._is_alt = False
+    G._is_cyclic = False
+    G._is_dihedral = False
+    return G
+
+
+def S3_in_S6():
+    """
+    Return a representation of S3 as a transitive subgroup of S6.
+
+    Notes
+    =====
+
+    The representation is found by viewing the group as the symmetries of a
+    triangular prism.
+
+    """
+    G = PermutationGroup(Permutation(0, 1, 2)(3, 4, 5), Permutation(0, 3)(2, 4)(1, 5))
+    set_symmetric_group_properties(G, 3, 6)
+    return G
+
+
+def A4_in_S6():
+    """
+    Return a representation of A4 as a transitive subgroup of S6.
+
+    Notes
+    =====
+
+    This was computed using :py:func:`~.find_transitive_subgroups_of_S6`.
+
+    """
+    G = PermutationGroup(Permutation(0, 4, 5)(1, 3, 2), Permutation(0, 1, 2)(3, 5, 4))
+    set_alternating_group_properties(G, 4, 6)
+    return G
+
+
+def S4m():
+    """
+    Return a representation of the S4- transitive subgroup of S6.
+
+    Notes
+    =====
+
+    This was computed using :py:func:`~.find_transitive_subgroups_of_S6`.
+
+    """
+    G = PermutationGroup(Permutation(1, 4, 5, 3), Permutation(0, 4)(1, 5)(2, 3))
+    set_symmetric_group_properties(G, 4, 6)
+    return G
+
+
+def S4p():
+    """
+    Return a representation of the S4+ transitive subgroup of S6.
+
+    Notes
+    =====
+
+    This was computed using :py:func:`~.find_transitive_subgroups_of_S6`.
+
+    """
+    G = PermutationGroup(Permutation(0, 2, 4, 1)(3, 5), Permutation(0, 3)(4, 5))
+    set_symmetric_group_properties(G, 4, 6)
+    return G
+
+
+def A4xC2():
+    """
+    Return a representation of the (A4 x C2) transitive subgroup of S6.
+
+    Notes
+    =====
+
+    This was computed using :py:func:`~.find_transitive_subgroups_of_S6`.
+
+    """
+    return PermutationGroup(
+        Permutation(0, 4, 5)(1, 3, 2), Permutation(0, 1, 2)(3, 5, 4),
+        Permutation(5)(2, 4))
+
+
+def S4xC2():
+    """
+    Return a representation of the (S4 x C2) transitive subgroup of S6.
+
+    Notes
+    =====
+
+    This was computed using :py:func:`~.find_transitive_subgroups_of_S6`.
+
+    """
+    return PermutationGroup(
+        Permutation(1, 4, 5, 3), Permutation(0, 4)(1, 5)(2, 3),
+        Permutation(1, 4)(3, 5))
+
+
+def G18():
+    """
+    Return a representation of the group G18, a transitive subgroup of S6
+    isomorphic to the semidirect product of C3^2 with C2.
+
+    Notes
+    =====
+
+    This was computed using :py:func:`~.find_transitive_subgroups_of_S6`.
+
+    """
+    return PermutationGroup(
+        Permutation(5)(0, 1, 2), Permutation(3, 4, 5),
+        Permutation(0, 4)(1, 5)(2, 3))
+
+
+def G36m():
+    """
+    Return a representation of the group G36-, a transitive subgroup of S6
+    isomorphic to the semidirect product of C3^2 with C2^2.
+
+    Notes
+    =====
+
+    This was computed using :py:func:`~.find_transitive_subgroups_of_S6`.
+
+    """
+    return PermutationGroup(
+        Permutation(5)(0, 1, 2), Permutation(3, 4, 5),
+        Permutation(1, 2)(3, 5), Permutation(0, 4)(1, 5)(2, 3))
+
+
+def G36p():
+    """
+    Return a representation of the group G36+, a transitive subgroup of S6
+    isomorphic to the semidirect product of C3^2 with C4.
+
+    Notes
+    =====
+
+    This was computed using :py:func:`~.find_transitive_subgroups_of_S6`.
+
+    """
+    return PermutationGroup(
+        Permutation(5)(0, 1, 2), Permutation(3, 4, 5),
+        Permutation(0, 5, 2, 3)(1, 4))
+
+
+def G72():
+    """
+    Return a representation of the group G72, a transitive subgroup of S6
+    isomorphic to the semidirect product of C3^2 with D4.
+
+    Notes
+    =====
+
+    See [1], Page 325.
+
+    """
+    return PermutationGroup(
+        Permutation(5)(0, 1, 2),
+        Permutation(0, 4, 1, 3)(2, 5), Permutation(0, 3)(1, 4)(2, 5))
+
+
+def PSL2F5():
+    r"""
+    Return a representation of the group $PSL_2(\mathbb{F}_5)$, as a transitive
+    subgroup of S6, isomorphic to $A_5$.
+
+    Notes
+    =====
+
+    This was computed using :py:func:`~.find_transitive_subgroups_of_S6`.
+
+    """
+    G = PermutationGroup(
+        Permutation(0, 4, 5)(1, 3, 2), Permutation(0, 4, 3, 1, 5))
+    set_alternating_group_properties(G, 5, 6)
+    return G
+
+
+def PGL2F5():
+    r"""
+    Return a representation of the group $PGL_2(\mathbb{F}_5)$, as a transitive
+    subgroup of S6, isomorphic to $S_5$.
+
+    Notes
+    =====
+
+    See [1], Page 325.
+
+    """
+    G = PermutationGroup(
+        Permutation(0, 1, 2, 3, 4), Permutation(0, 5)(1, 2)(3, 4))
+    set_symmetric_group_properties(G, 5, 6)
+    return G
+
+
+def find_transitive_subgroups_of_S6(*targets, print_report=False):
+    r"""
+    Search for certain transitive subgroups of $S_6$.
+
+    The symmetric group $S_6$ has 16 different transitive subgroups, up to
+    conjugacy. Some are more easily constructed than others. For example, the
+    dihedral group $D_6$ is immediately found, but it is not at all obvious how
+    to realize $S_4$ or $S_5$ *transitively* within $S_6$.
+
+    In some cases there are well-known constructions that can be used. For
+    example, $S_5$ is isomorphic to $PGL_2(\mathbb{F}_5)$, which acts in a
+    natural way on the projective line $P^1(\mathbb{F}_5)$, a set of order 6.
+
+    In absence of such special constructions however, we can simply search for
+    generators. For example, transitive instances of $A_4$ and $S_4$ can be
+    found within $S_6$ in this way.
+
+    Once we are engaged in such searches, it may then be easier (if less
+    elegant) to find even those groups like $S_5$ that do have special
+    constructions, by mere search.
+
+    This function locates generators for transitive instances in $S_6$ of the
+    following subgroups:
+
+    * $A_4$
+    * $S_4^-$ ($S_4$ not contained within $A_6$)
+    * $S_4^+$ ($S_4$ contained within $A_6$)
+    * $A_4 \times C_2$
+    * $S_4 \times C_2$
+    * $G_{18}   = C_3^2 \rtimes C_2$
+    * $G_{36}^- = C_3^2 \rtimes C_2^2$
+    * $G_{36}^+ = C_3^2 \rtimes C_4$
+    * $G_{72}   = C_3^2 \rtimes D_4$
+    * $A_5$
+    * $S_5$
+
+    Note: Each of these groups also has a dedicated function in this module
+    that returns the group immediately, using generators that were found by
+    this search procedure.
+
+    The search procedure serves as a record of how these generators were
+    found. Also, due to randomness in the generation of the elements of
+    permutation groups, it can be called again, in order to (probably) get
+    different generators for the same groups.
+
+    Parameters
+    ==========
+
+    targets : list of :py:class:`~.S6TransitiveSubgroups` values
+        The groups you want to find.
+
+    print_report : bool (default False)
+        If True, print to stdout the generators found for each group.
+
+    Returns
+    =======
+
+    dict
+        mapping each name in *targets* to the :py:class:`~.PermutationGroup`
+        that was found
+
+    References
+    ==========
+
+    .. [2] https://en.wikipedia.org/wiki/Projective_linear_group#Exceptional_isomorphisms
+    .. [3] https://en.wikipedia.org/wiki/Automorphisms_of_the_symmetric_and_alternating_groups#PGL%282,5%29
+
+    """
+    def elts_by_order(G):
+        """Sort the elements of a group by their order. """
+        elts = defaultdict(list)
+        for g in G.elements:
+            elts[g.order()].append(g)
+        return elts
+
+    def order_profile(G, name=None):
+        """Determine how many elements a group has, of each order. """
+        elts = elts_by_order(G)
+        profile = {o:len(e) for o, e in elts.items()}
+        if name:
+            print(f'{name}: ' + ' '.join(f'{len(profile[r])}@{r}' for r in sorted(profile.keys())))
+        return profile
+
+    S6 = SymmetricGroup(6)
+    A6 = AlternatingGroup(6)
+    S6_by_order = elts_by_order(S6)
+
+    def search(existing_gens, needed_gen_orders, order, alt=None, profile=None, anti_profile=None):
+        """
+        Find a transitive subgroup of S6.
+
+        Parameters
+        ==========
+
+        existing_gens : list of Permutation
+            Optionally empty list of generators that must be in the group.
+
+        needed_gen_orders : list of positive int
+            Nonempty list of the orders of the additional generators that are
+            to be found.
+
+        order: int
+            The order of the group being sought.
+
+        alt: bool, None
+            If True, require the group to be contained in A6.
+            If False, require the group not to be contained in A6.
+
+        profile : dict
+            If given, the group's order profile must equal this.
+
+        anti_profile : dict
+            If given, the group's order profile must *not* equal this.
+
+        """
+        for gens in itertools.product(*[S6_by_order[n] for n in needed_gen_orders]):
+            if len(set(gens)) < len(gens):
+                continue
+            G = PermutationGroup(existing_gens + list(gens))
+            if G.order() == order and G.is_transitive():
+                if alt is not None and G.is_subgroup(A6) != alt:
+                    continue
+                if profile and order_profile(G) != profile:
+                    continue
+                if anti_profile and order_profile(G) == anti_profile:
+                    continue
+                return G
+
+    def match_known_group(G, alt=None):
+        needed = [g.order() for g in G.generators]
+        return search([], needed, G.order(), alt=alt, profile=order_profile(G))
+
+    found = {}
+
+    def finish_up(name, G):
+        found[name] = G
+        if print_report:
+            print("=" * 40)
+            print(f"{name}:")
+            print(G.generators)
+
+    if S6TransitiveSubgroups.A4 in targets or S6TransitiveSubgroups.A4xC2 in targets:
+        A4_in_S6 = match_known_group(AlternatingGroup(4))
+        finish_up(S6TransitiveSubgroups.A4, A4_in_S6)
+
+    if S6TransitiveSubgroups.S4m in targets or S6TransitiveSubgroups.S4xC2 in targets:
+        S4m_in_S6 = match_known_group(SymmetricGroup(4), alt=False)
+        finish_up(S6TransitiveSubgroups.S4m, S4m_in_S6)
+
+    if S6TransitiveSubgroups.S4p in targets:
+        S4p_in_S6 = match_known_group(SymmetricGroup(4), alt=True)
+        finish_up(S6TransitiveSubgroups.S4p, S4p_in_S6)
+
+    if S6TransitiveSubgroups.A4xC2 in targets:
+        A4xC2_in_S6 = search(A4_in_S6.generators, [2], 24, anti_profile=order_profile(SymmetricGroup(4)))
+        finish_up(S6TransitiveSubgroups.A4xC2, A4xC2_in_S6)
+
+    if S6TransitiveSubgroups.S4xC2 in targets:
+        S4xC2_in_S6 = search(S4m_in_S6.generators, [2], 48)
+        finish_up(S6TransitiveSubgroups.S4xC2, S4xC2_in_S6)
+
+    # For the normal factor N = C3^2 in any of the G_n subgroups, we take one
+    # obvious instance of C3^2 in S6:
+    N_gens = [Permutation(5)(0, 1, 2), Permutation(5)(3, 4, 5)]
+
+    if S6TransitiveSubgroups.G18 in targets:
+        G18_in_S6 = search(N_gens, [2], 18)
+        finish_up(S6TransitiveSubgroups.G18, G18_in_S6)
+
+    if S6TransitiveSubgroups.G36m in targets:
+        G36m_in_S6 = search(N_gens, [2, 2], 36, alt=False)
+        finish_up(S6TransitiveSubgroups.G36m, G36m_in_S6)
+
+    if S6TransitiveSubgroups.G36p in targets:
+        G36p_in_S6 = search(N_gens, [4], 36, alt=True)
+        finish_up(S6TransitiveSubgroups.G36p, G36p_in_S6)
+
+    if S6TransitiveSubgroups.G72 in targets:
+        G72_in_S6 = search(N_gens, [4, 2], 72)
+        finish_up(S6TransitiveSubgroups.G72, G72_in_S6)
+
+    # The PSL2(F5) and PGL2(F5) subgroups are isomorphic to A5 and S5, resp.
+
+    if S6TransitiveSubgroups.PSL2F5 in targets:
+        PSL2F5_in_S6 = match_known_group(AlternatingGroup(5))
+        finish_up(S6TransitiveSubgroups.PSL2F5, PSL2F5_in_S6)
+
+    if S6TransitiveSubgroups.PGL2F5 in targets:
+        PGL2F5_in_S6 = match_known_group(SymmetricGroup(5))
+        finish_up(S6TransitiveSubgroups.PGL2F5, PGL2F5_in_S6)
+
+    # There is little need to "search" for any of the groups C6, S3, D6, A6,
+    # or S6, since they all have obvious realizations within S6. However, we
+    # support them here just in case a random representation is desired.
+
+    if S6TransitiveSubgroups.C6 in targets:
+        C6 = match_known_group(CyclicGroup(6))
+        finish_up(S6TransitiveSubgroups.C6, C6)
+
+    if S6TransitiveSubgroups.S3 in targets:
+        S3 = match_known_group(SymmetricGroup(3))
+        finish_up(S6TransitiveSubgroups.S3, S3)
+
+    if S6TransitiveSubgroups.D6 in targets:
+        D6 = match_known_group(DihedralGroup(6))
+        finish_up(S6TransitiveSubgroups.D6, D6)
+
+    if S6TransitiveSubgroups.A6 in targets:
+        A6 = match_known_group(A6)
+        finish_up(S6TransitiveSubgroups.A6, A6)
+
+    if S6TransitiveSubgroups.S6 in targets:
+        S6 = match_known_group(S6)
+        finish_up(S6TransitiveSubgroups.S6, S6)
+
+    return found

lib/python3.12/site-packages/sympy/combinatorics/generators.py

@@ -0,0 +1,302 @@
+from sympy.combinatorics.permutations import Permutation
+from sympy.core.symbol import symbols
+from sympy.matrices import Matrix
+from sympy.utilities.iterables import variations, rotate_left
+
+
+def symmetric(n):
+    """
+    Generates the symmetric group of order n, Sn.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.generators import symmetric
+    >>> list(symmetric(3))
+    [(2), (1 2), (2)(0 1), (0 1 2), (0 2 1), (0 2)]
+    """
+    for perm in variations(range(n), n):
+        yield Permutation(perm)
+
+
+def cyclic(n):
+    """
+    Generates the cyclic group of order n, Cn.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.generators import cyclic
+    >>> list(cyclic(5))
+    [(4), (0 1 2 3 4), (0 2 4 1 3),
+     (0 3 1 4 2), (0 4 3 2 1)]
+
+    See Also
+    ========
+
+    dihedral
+    """
+    gen = list(range(n))
+    for i in range(n):
+        yield Permutation(gen)
+        gen = rotate_left(gen, 1)
+
+
+def alternating(n):
+    """
+    Generates the alternating group of order n, An.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.generators import alternating
+    >>> list(alternating(3))
+    [(2), (0 1 2), (0 2 1)]
+    """
+    for perm in variations(range(n), n):
+        p = Permutation(perm)
+        if p.is_even:
+            yield p
+
+
+def dihedral(n):
+    """
+    Generates the dihedral group of order 2n, Dn.
+
+    The result is given as a subgroup of Sn, except for the special cases n=1
+    (the group S2) and n=2 (the Klein 4-group) where that's not possible
+    and embeddings in S2 and S4 respectively are given.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.generators import dihedral
+    >>> list(dihedral(3))
+    [(2), (0 2), (0 1 2), (1 2), (0 2 1), (2)(0 1)]
+
+    See Also
+    ========
+
+    cyclic
+    """
+    if n == 1:
+        yield Permutation([0, 1])
+        yield Permutation([1, 0])
+    elif n == 2:
+        yield Permutation([0, 1, 2, 3])
+        yield Permutation([1, 0, 3, 2])
+        yield Permutation([2, 3, 0, 1])
+        yield Permutation([3, 2, 1, 0])
+    else:
+        gen = list(range(n))
+        for i in range(n):
+            yield Permutation(gen)
+            yield Permutation(gen[::-1])
+            gen = rotate_left(gen, 1)
+
+
+def rubik_cube_generators():
+    """Return the permutations of the 3x3 Rubik's cube, see
+    https://www.gap-system.org/Doc/Examples/rubik.html
+    """
+    a = [
+        [(1, 3, 8, 6), (2, 5, 7, 4), (9, 33, 25, 17), (10, 34, 26, 18),
+         (11, 35, 27, 19)],
+        [(9, 11, 16, 14), (10, 13, 15, 12), (1, 17, 41, 40), (4, 20, 44, 37),
+         (6, 22, 46, 35)],
+        [(17, 19, 24, 22), (18, 21, 23, 20), (6, 25, 43, 16), (7, 28, 42, 13),
+         (8, 30, 41, 11)],
+        [(25, 27, 32, 30), (26, 29, 31, 28), (3, 38, 43, 19), (5, 36, 45, 21),
+         (8, 33, 48, 24)],
+        [(33, 35, 40, 38), (34, 37, 39, 36), (3, 9, 46, 32), (2, 12, 47, 29),
+         (1, 14, 48, 27)],
+        [(41, 43, 48, 46), (42, 45, 47, 44), (14, 22, 30, 38),
+         (15, 23, 31, 39), (16, 24, 32, 40)]
+    ]
+    return [Permutation([[i - 1 for i in xi] for xi in x], size=48) for x in a]
+
+
+def rubik(n):
+    """Return permutations for an nxn Rubik's cube.
+
+    Permutations returned are for rotation of each of the slice
+    from the face up to the last face for each of the 3 sides (in this order):
+    front, right and bottom. Hence, the first n - 1 permutations are for the
+    slices from the front.
+    """
+
+    if n < 2:
+        raise ValueError('dimension of cube must be > 1')
+
+    # 1-based reference to rows and columns in Matrix
+    def getr(f, i):
+        return faces[f].col(n - i)
+
+    def getl(f, i):
+        return faces[f].col(i - 1)
+
+    def getu(f, i):
+        return faces[f].row(i - 1)
+
+    def getd(f, i):
+        return faces[f].row(n - i)
+
+    def setr(f, i, s):
+        faces[f][:, n - i] = Matrix(n, 1, s)
+
+    def setl(f, i, s):
+        faces[f][:, i - 1] = Matrix(n, 1, s)
+
+    def setu(f, i, s):
+        faces[f][i - 1, :] = Matrix(1, n, s)
+
+    def setd(f, i, s):
+        faces[f][n - i, :] = Matrix(1, n, s)
+
+    # motion of a single face
+    def cw(F, r=1):
+        for _ in range(r):
+            face = faces[F]
+            rv = []
+            for c in range(n):
+                for r in range(n - 1, -1, -1):
+                    rv.append(face[r, c])
+            faces[F] = Matrix(n, n, rv)
+
+    def ccw(F):
+        cw(F, 3)
+
+    # motion of plane i from the F side;
+    # fcw(0) moves the F face, fcw(1) moves the plane
+    # just behind the front face, etc...
+    def fcw(i, r=1):
+        for _ in range(r):
+            if i == 0:
+                cw(F)
+            i += 1
+            temp = getr(L, i)
+            setr(L, i, list(getu(D, i)))
+            setu(D, i, list(reversed(getl(R, i))))
+            setl(R, i, list(getd(U, i)))
+            setd(U, i, list(reversed(temp)))
+            i -= 1
+
+    def fccw(i):
+        fcw(i, 3)
+
+    # motion of the entire cube from the F side
+    def FCW(r=1):
+        for _ in range(r):
+            cw(F)
+            ccw(B)
+            cw(U)
+            t = faces[U]
+            cw(L)
+            faces[U] = faces[L]
+            cw(D)
+            faces[L] = faces[D]
+            cw(R)
+            faces[D] = faces[R]
+            faces[R] = t
+
+    def FCCW():
+        FCW(3)
+
+    # motion of the entire cube from the U side
+    def UCW(r=1):
+        for _ in range(r):
+            cw(U)
+            ccw(D)
+            t = faces[F]
+            faces[F] = faces[R]
+            faces[R] = faces[B]
+            faces[B] = faces[L]
+            faces[L] = t
+
+    def UCCW():
+        UCW(3)
+
+    # defining the permutations for the cube
+
+    U, F, R, B, L, D = names = symbols('U, F, R, B, L, D')
+
+    # the faces are represented by nxn matrices
+    faces = {}
+    count = 0
+    for fi in range(6):
+        f = []
+        for a in range(n**2):
+            f.append(count)
+            count += 1
+        faces[names[fi]] = Matrix(n, n, f)
+
+    # this will either return the value of the current permutation
+    # (show != 1) or else append the permutation to the group, g
+    def perm(show=0):
+        # add perm to the list of perms
+        p = []
+        for f in names:
+            p.extend(faces[f])
+        if show:
+            return p
+        g.append(Permutation(p))
+
+    g = []  # container for the group's permutations
+    I = list(range(6*n**2))  # the identity permutation used for checking
+
+    # define permutations corresponding to cw rotations of the planes
+    # up TO the last plane from that direction; by not including the
+    # last plane, the orientation of the cube is maintained.
+
+    # F slices
+    for i in range(n - 1):
+        fcw(i)
+        perm()
+        fccw(i)  # restore
+    assert perm(1) == I
+
+    # R slices
+    # bring R to front
+    UCW()
+    for i in range(n - 1):
+        fcw(i)
+        # put it back in place
+        UCCW()
+        # record
+        perm()
+        # restore
+        # bring face to front
+        UCW()
+        fccw(i)
+    # restore
+    UCCW()
+    assert perm(1) == I
+
+    # D slices
+    # bring up bottom
+    FCW()
+    UCCW()
+    FCCW()
+    for i in range(n - 1):
+        # turn strip
+        fcw(i)
+        # put bottom back on the bottom
+        FCW()
+        UCW()
+        FCCW()
+        # record
+        perm()
+        # restore
+        # bring up bottom
+        FCW()
+        UCCW()
+        FCCW()
+        # turn strip
+        fccw(i)
+    # put bottom back on the bottom
+    FCW()
+    UCW()
+    FCCW()
+    assert perm(1) == I
+
+    return g

lib/python3.12/site-packages/sympy/combinatorics/graycode.py

@@ -0,0 +1,430 @@
+from sympy.core import Basic, Integer
+
+import random
+
+
+class GrayCode(Basic):
+    """
+    A Gray code is essentially a Hamiltonian walk on
+    a n-dimensional cube with edge length of one.
+    The vertices of the cube are represented by vectors
+    whose values are binary. The Hamilton walk visits
+    each vertex exactly once. The Gray code for a 3d
+    cube is ['000','100','110','010','011','111','101',
+    '001'].
+
+    A Gray code solves the problem of sequentially
+    generating all possible subsets of n objects in such
+    a way that each subset is obtained from the previous
+    one by either deleting or adding a single object.
+    In the above example, 1 indicates that the object is
+    present, and 0 indicates that its absent.
+
+    Gray codes have applications in statistics as well when
+    we want to compute various statistics related to subsets
+    in an efficient manner.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics import GrayCode
+    >>> a = GrayCode(3)
+    >>> list(a.generate_gray())
+    ['000', '001', '011', '010', '110', '111', '101', '100']
+    >>> a = GrayCode(4)
+    >>> list(a.generate_gray())
+    ['0000', '0001', '0011', '0010', '0110', '0111', '0101', '0100', \
+    '1100', '1101', '1111', '1110', '1010', '1011', '1001', '1000']
+
+    References
+    ==========
+
+    .. [1] Nijenhuis,A. and Wilf,H.S.(1978).
+           Combinatorial Algorithms. Academic Press.
+    .. [2] Knuth, D. (2011). The Art of Computer Programming, Vol 4
+           Addison Wesley
+
+
+    """
+
+    _skip = False
+    _current = 0
+    _rank = None
+
+    def __new__(cls, n, *args, **kw_args):
+        """
+        Default constructor.
+
+        It takes a single argument ``n`` which gives the dimension of the Gray
+        code. The starting Gray code string (``start``) or the starting ``rank``
+        may also be given; the default is to start at rank = 0 ('0...0').
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import GrayCode
+        >>> a = GrayCode(3)
+        >>> a
+        GrayCode(3)
+        >>> a.n
+        3
+
+        >>> a = GrayCode(3, start='100')
+        >>> a.current
+        '100'
+
+        >>> a = GrayCode(4, rank=4)
+        >>> a.current
+        '0110'
+        >>> a.rank
+        4
+
+        """
+        if n < 1 or int(n) != n:
+            raise ValueError(
+                'Gray code dimension must be a positive integer, not %i' % n)
+        n = Integer(n)
+        args = (n,) + args
+        obj = Basic.__new__(cls, *args)
+        if 'start' in kw_args:
+            obj._current = kw_args["start"]
+            if len(obj._current) > n:
+                raise ValueError('Gray code start has length %i but '
+                'should not be greater than %i' % (len(obj._current), n))
+        elif 'rank' in kw_args:
+            if int(kw_args["rank"]) != kw_args["rank"]:
+                raise ValueError('Gray code rank must be a positive integer, '
+                'not %i' % kw_args["rank"])
+            obj._rank = int(kw_args["rank"]) % obj.selections
+            obj._current = obj.unrank(n, obj._rank)
+        return obj
+
+    def next(self, delta=1):
+        """
+        Returns the Gray code a distance ``delta`` (default = 1) from the
+        current value in canonical order.
+
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import GrayCode
+        >>> a = GrayCode(3, start='110')
+        >>> a.next().current
+        '111'
+        >>> a.next(-1).current
+        '010'
+        """
+        return GrayCode(self.n, rank=(self.rank + delta) % self.selections)
+
+    @property
+    def selections(self):
+        """
+        Returns the number of bit vectors in the Gray code.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import GrayCode
+        >>> a = GrayCode(3)
+        >>> a.selections
+        8
+        """
+        return 2**self.n
+
+    @property
+    def n(self):
+        """
+        Returns the dimension of the Gray code.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import GrayCode
+        >>> a = GrayCode(5)
+        >>> a.n
+        5
+        """
+        return self.args[0]
+
+    def generate_gray(self, **hints):
+        """
+        Generates the sequence of bit vectors of a Gray Code.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import GrayCode
+        >>> a = GrayCode(3)
+        >>> list(a.generate_gray())
+        ['000', '001', '011', '010', '110', '111', '101', '100']
+        >>> list(a.generate_gray(start='011'))
+        ['011', '010', '110', '111', '101', '100']
+        >>> list(a.generate_gray(rank=4))
+        ['110', '111', '101', '100']
+
+        See Also
+        ========
+
+        skip
+
+        References
+        ==========
+
+        .. [1] Knuth, D. (2011). The Art of Computer Programming,
+               Vol 4, Addison Wesley
+
+        """
+        bits = self.n
+        start = None
+        if "start" in hints:
+            start = hints["start"]
+        elif "rank" in hints:
+            start = GrayCode.unrank(self.n, hints["rank"])
+        if start is not None:
+            self._current = start
+        current = self.current
+        graycode_bin = gray_to_bin(current)
+        if len(graycode_bin) > self.n:
+            raise ValueError('Gray code start has length %i but should '
+            'not be greater than %i' % (len(graycode_bin), bits))
+        self._current = int(current, 2)
+        graycode_int = int(''.join(graycode_bin), 2)
+        for i in range(graycode_int, 1 << bits):
+            if self._skip:
+                self._skip = False
+            else:
+                yield self.current
+            bbtc = (i ^ (i + 1))
+            gbtc = (bbtc ^ (bbtc >> 1))
+            self._current = (self._current ^ gbtc)
+        self._current = 0
+
+    def skip(self):
+        """
+        Skips the bit generation.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import GrayCode
+        >>> a = GrayCode(3)
+        >>> for i in a.generate_gray():
+        ...     if i == '010':
+        ...         a.skip()
+        ...     print(i)
+        ...
+        000
+        001
+        011
+        010
+        111
+        101
+        100
+
+        See Also
+        ========
+
+        generate_gray
+        """
+        self._skip = True
+
+    @property
+    def rank(self):
+        """
+        Ranks the Gray code.
+
+        A ranking algorithm determines the position (or rank)
+        of a combinatorial object among all the objects w.r.t.
+        a given order. For example, the 4 bit binary reflected
+        Gray code (BRGC) '0101' has a rank of 6 as it appears in
+        the 6th position in the canonical ordering of the family
+        of 4 bit Gray codes.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import GrayCode
+        >>> a = GrayCode(3)
+        >>> list(a.generate_gray())
+        ['000', '001', '011', '010', '110', '111', '101', '100']
+        >>> GrayCode(3, start='100').rank
+        7
+        >>> GrayCode(3, rank=7).current
+        '100'
+
+        See Also
+        ========
+
+        unrank
+
+        References
+        ==========
+
+        .. [1] https://web.archive.org/web/20200224064753/http://statweb.stanford.edu/~susan/courses/s208/node12.html
+
+        """
+        if self._rank is None:
+            self._rank = int(gray_to_bin(self.current), 2)
+        return self._rank
+
+    @property
+    def current(self):
+        """
+        Returns the currently referenced Gray code as a bit string.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import GrayCode
+        >>> GrayCode(3, start='100').current
+        '100'
+        """
+        rv = self._current or '0'
+        if not isinstance(rv, str):
+            rv = bin(rv)[2:]
+        return rv.rjust(self.n, '0')
+
+    @classmethod
+    def unrank(self, n, rank):
+        """
+        Unranks an n-bit sized Gray code of rank k. This method exists
+        so that a derivative GrayCode class can define its own code of
+        a given rank.
+
+        The string here is generated in reverse order to allow for tail-call
+        optimization.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import GrayCode
+        >>> GrayCode(5, rank=3).current
+        '00010'
+        >>> GrayCode.unrank(5, 3)
+        '00010'
+
+        See Also
+        ========
+
+        rank
+        """
+        def _unrank(k, n):
+            if n == 1:
+                return str(k % 2)
+            m = 2**(n - 1)
+            if k < m:
+                return '0' + _unrank(k, n - 1)
+            return '1' + _unrank(m - (k % m) - 1, n - 1)
+        return _unrank(rank, n)
+
+
+def random_bitstring(n):
+    """
+    Generates a random bitlist of length n.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.graycode import random_bitstring
+    >>> random_bitstring(3) # doctest: +SKIP
+    100
+    """
+    return ''.join([random.choice('01') for i in range(n)])
+
+
+def gray_to_bin(bin_list):
+    """
+    Convert from Gray coding to binary coding.
+
+    We assume big endian encoding.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.graycode import gray_to_bin
+    >>> gray_to_bin('100')
+    '111'
+
+    See Also
+    ========
+
+    bin_to_gray
+    """
+    b = [bin_list[0]]
+    for i in range(1, len(bin_list)):
+        b += str(int(b[i - 1] != bin_list[i]))
+    return ''.join(b)
+
+
+def bin_to_gray(bin_list):
+    """
+    Convert from binary coding to gray coding.
+
+    We assume big endian encoding.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.graycode import bin_to_gray
+    >>> bin_to_gray('111')
+    '100'
+
+    See Also
+    ========
+
+    gray_to_bin
+    """
+    b = [bin_list[0]]
+    for i in range(1, len(bin_list)):
+        b += str(int(bin_list[i]) ^ int(bin_list[i - 1]))
+    return ''.join(b)
+
+
+def get_subset_from_bitstring(super_set, bitstring):
+    """
+    Gets the subset defined by the bitstring.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.graycode import get_subset_from_bitstring
+    >>> get_subset_from_bitstring(['a', 'b', 'c', 'd'], '0011')
+    ['c', 'd']
+    >>> get_subset_from_bitstring(['c', 'a', 'c', 'c'], '1100')
+    ['c', 'a']
+
+    See Also
+    ========
+
+    graycode_subsets
+    """
+    if len(super_set) != len(bitstring):
+        raise ValueError("The sizes of the lists are not equal")
+    return [super_set[i] for i, j in enumerate(bitstring)
+            if bitstring[i] == '1']
+
+
+def graycode_subsets(gray_code_set):
+    """
+    Generates the subsets as enumerated by a Gray code.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.graycode import graycode_subsets
+    >>> list(graycode_subsets(['a', 'b', 'c']))
+    [[], ['c'], ['b', 'c'], ['b'], ['a', 'b'], ['a', 'b', 'c'], \
+    ['a', 'c'], ['a']]
+    >>> list(graycode_subsets(['a', 'b', 'c', 'c']))
+    [[], ['c'], ['c', 'c'], ['c'], ['b', 'c'], ['b', 'c', 'c'], \
+    ['b', 'c'], ['b'], ['a', 'b'], ['a', 'b', 'c'], ['a', 'b', 'c', 'c'], \
+    ['a', 'b', 'c'], ['a', 'c'], ['a', 'c', 'c'], ['a', 'c'], ['a']]
+
+    See Also
+    ========
+
+    get_subset_from_bitstring
+    """
+    for bitstring in list(GrayCode(len(gray_code_set)).generate_gray()):
+        yield get_subset_from_bitstring(gray_code_set, bitstring)

lib/python3.12/site-packages/sympy/combinatorics/group_constructs.py

@@ -0,0 +1,61 @@
+from sympy.combinatorics.perm_groups import PermutationGroup
+from sympy.combinatorics.permutations import Permutation
+from sympy.utilities.iterables import uniq
+
+_af_new = Permutation._af_new
+
+
+def DirectProduct(*groups):
+    """
+    Returns the direct product of several groups as a permutation group.
+
+    Explanation
+    ===========
+
+    This is implemented much like the __mul__ procedure for taking the direct
+    product of two permutation groups, but the idea of shifting the
+    generators is realized in the case of an arbitrary number of groups.
+    A call to DirectProduct(G1, G2, ..., Gn) is generally expected to be faster
+    than a call to G1*G2*...*Gn (and thus the need for this algorithm).
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.group_constructs import DirectProduct
+    >>> from sympy.combinatorics.named_groups import CyclicGroup
+    >>> C = CyclicGroup(4)
+    >>> G = DirectProduct(C, C, C)
+    >>> G.order()
+    64
+
+    See Also
+    ========
+
+    sympy.combinatorics.perm_groups.PermutationGroup.__mul__
+
+    """
+    degrees = []
+    gens_count = []
+    total_degree = 0
+    total_gens = 0
+    for group in groups:
+        current_deg = group.degree
+        current_num_gens = len(group.generators)
+        degrees.append(current_deg)
+        total_degree += current_deg
+        gens_count.append(current_num_gens)
+        total_gens += current_num_gens
+    array_gens = []
+    for i in range(total_gens):
+        array_gens.append(list(range(total_degree)))
+    current_gen = 0
+    current_deg = 0
+    for i in range(len(gens_count)):
+        for j in range(current_gen, current_gen + gens_count[i]):
+            gen = ((groups[i].generators)[j - current_gen]).array_form
+            array_gens[j][current_deg:current_deg + degrees[i]] = \
+                [x + current_deg for x in gen]
+        current_gen += gens_count[i]
+        current_deg += degrees[i]
+    perm_gens = list(uniq([_af_new(list(a)) for a in array_gens]))
+    return PermutationGroup(perm_gens, dups=False)

lib/python3.12/site-packages/sympy/combinatorics/homomorphisms.py

@@ -0,0 +1,549 @@
+import itertools
+from sympy.combinatorics.fp_groups import FpGroup, FpSubgroup, simplify_presentation
+from sympy.combinatorics.free_groups import FreeGroup
+from sympy.combinatorics.perm_groups import PermutationGroup
+from sympy.core.intfunc import igcd
+from sympy.functions.combinatorial.numbers import totient
+from sympy.core.singleton import S
+
+class GroupHomomorphism:
+    '''
+    A class representing group homomorphisms. Instantiate using `homomorphism()`.
+
+    References
+    ==========
+
+    .. [1] Holt, D., Eick, B. and O'Brien, E. (2005). Handbook of computational group theory.
+
+    '''
+
+    def __init__(self, domain, codomain, images):
+        self.domain = domain
+        self.codomain = codomain
+        self.images = images
+        self._inverses = None
+        self._kernel = None
+        self._image = None
+
+    def _invs(self):
+        '''
+        Return a dictionary with `{gen: inverse}` where `gen` is a rewriting
+        generator of `codomain` (e.g. strong generator for permutation groups)
+        and `inverse` is an element of its preimage
+
+        '''
+        image = self.image()
+        inverses = {}
+        for k in list(self.images.keys()):
+            v = self.images[k]
+            if not (v in inverses
+                    or v.is_identity):
+                inverses[v] = k
+        if isinstance(self.codomain, PermutationGroup):
+            gens = image.strong_gens
+        else:
+            gens = image.generators
+        for g in gens:
+            if g in inverses or g.is_identity:
+                continue
+            w = self.domain.identity
+            if isinstance(self.codomain, PermutationGroup):
+                parts = image._strong_gens_slp[g][::-1]
+            else:
+                parts = g
+            for s in parts:
+                if s in inverses:
+                    w = w*inverses[s]
+                else:
+                    w = w*inverses[s**-1]**-1
+            inverses[g] = w
+
+        return inverses
+
+    def invert(self, g):
+        '''
+        Return an element of the preimage of ``g`` or of each element
+        of ``g`` if ``g`` is a list.
+
+        Explanation
+        ===========
+
+        If the codomain is an FpGroup, the inverse for equal
+        elements might not always be the same unless the FpGroup's
+        rewriting system is confluent. However, making a system
+        confluent can be time-consuming. If it's important, try
+        `self.codomain.make_confluent()` first.
+
+        '''
+        from sympy.combinatorics import Permutation
+        from sympy.combinatorics.free_groups import FreeGroupElement
+        if isinstance(g, (Permutation, FreeGroupElement)):
+            if isinstance(self.codomain, FpGroup):
+                g = self.codomain.reduce(g)
+            if self._inverses is None:
+                self._inverses = self._invs()
+            image = self.image()
+            w = self.domain.identity
+            if isinstance(self.codomain, PermutationGroup):
+                gens = image.generator_product(g)[::-1]
+            else:
+                gens = g
+            # the following can't be "for s in gens:"
+            # because that would be equivalent to
+            # "for s in gens.array_form:" when g is
+            # a FreeGroupElement. On the other hand,
+            # when you call gens by index, the generator
+            # (or inverse) at position i is returned.
+            for i in range(len(gens)):
+                s = gens[i]
+                if s.is_identity:
+                    continue
+                if s in self._inverses:
+                    w = w*self._inverses[s]
+                else:
+                    w = w*self._inverses[s**-1]**-1
+            return w
+        elif isinstance(g, list):
+            return [self.invert(e) for e in g]
+
+    def kernel(self):
+        '''
+        Compute the kernel of `self`.
+
+        '''
+        if self._kernel is None:
+            self._kernel = self._compute_kernel()
+        return self._kernel
+
+    def _compute_kernel(self):
+        G = self.domain
+        G_order = G.order()
+        if G_order is S.Infinity:
+            raise NotImplementedError(
+                "Kernel computation is not implemented for infinite groups")
+        gens = []
+        if isinstance(G, PermutationGroup):
+            K = PermutationGroup(G.identity)
+        else:
+            K = FpSubgroup(G, gens, normal=True)
+        i = self.image().order()
+        while K.order()*i != G_order:
+            r = G.random()
+            k = r*self.invert(self(r))**-1
+            if k not in K:
+                gens.append(k)
+                if isinstance(G, PermutationGroup):
+                    K = PermutationGroup(gens)
+                else:
+                    K = FpSubgroup(G, gens, normal=True)
+        return K
+
+    def image(self):
+        '''
+        Compute the image of `self`.
+
+        '''
+        if self._image is None:
+            values = list(set(self.images.values()))
+            if isinstance(self.codomain, PermutationGroup):
+                self._image = self.codomain.subgroup(values)
+            else:
+                self._image = FpSubgroup(self.codomain, values)
+        return self._image
+
+    def _apply(self, elem):
+        '''
+        Apply `self` to `elem`.
+
+        '''
+        if elem not in self.domain:
+            if isinstance(elem, (list, tuple)):
+                return [self._apply(e) for e in elem]
+            raise ValueError("The supplied element does not belong to the domain")
+        if elem.is_identity:
+            return self.codomain.identity
+        else:
+            images = self.images
+            value = self.codomain.identity
+            if isinstance(self.domain, PermutationGroup):
+                gens = self.domain.generator_product(elem, original=True)
+                for g in gens:
+                    if g in self.images:
+                        value = images[g]*value
+                    else:
+                        value = images[g**-1]**-1*value
+            else:
+                i = 0
+                for _, p in elem.array_form:
+                    if p < 0:
+                        g = elem[i]**-1
+                    else:
+                        g = elem[i]
+                    value = value*images[g]**p
+                    i += abs(p)
+        return value
+
+    def __call__(self, elem):
+        return self._apply(elem)
+
+    def is_injective(self):
+        '''
+        Check if the homomorphism is injective
+
+        '''
+        return self.kernel().order() == 1
+
+    def is_surjective(self):
+        '''
+        Check if the homomorphism is surjective
+
+        '''
+        im = self.image().order()
+        oth = self.codomain.order()
+        if im is S.Infinity and oth is S.Infinity:
+            return None
+        else:
+            return im == oth
+
+    def is_isomorphism(self):
+        '''
+        Check if `self` is an isomorphism.
+
+        '''
+        return self.is_injective() and self.is_surjective()
+
+    def is_trivial(self):
+        '''
+        Check is `self` is a trivial homomorphism, i.e. all elements
+        are mapped to the identity.
+
+        '''
+        return self.image().order() == 1
+
+    def compose(self, other):
+        '''
+        Return the composition of `self` and `other`, i.e.
+        the homomorphism phi such that for all g in the domain
+        of `other`, phi(g) = self(other(g))
+
+        '''
+        if not other.image().is_subgroup(self.domain):
+            raise ValueError("The image of `other` must be a subgroup of "
+                    "the domain of `self`")
+        images = {g: self(other(g)) for g in other.images}
+        return GroupHomomorphism(other.domain, self.codomain, images)
+
+    def restrict_to(self, H):
+        '''
+        Return the restriction of the homomorphism to the subgroup `H`
+        of the domain.
+
+        '''
+        if not isinstance(H, PermutationGroup) or not H.is_subgroup(self.domain):
+            raise ValueError("Given H is not a subgroup of the domain")
+        domain = H
+        images = {g: self(g) for g in H.generators}
+        return GroupHomomorphism(domain, self.codomain, images)
+
+    def invert_subgroup(self, H):
+        '''
+        Return the subgroup of the domain that is the inverse image
+        of the subgroup ``H`` of the homomorphism image
+
+        '''
+        if not H.is_subgroup(self.image()):
+            raise ValueError("Given H is not a subgroup of the image")
+        gens = []
+        P = PermutationGroup(self.image().identity)
+        for h in H.generators:
+            h_i = self.invert(h)
+            if h_i not in P:
+                gens.append(h_i)
+                P = PermutationGroup(gens)
+            for k in self.kernel().generators:
+                if k*h_i not in P:
+                    gens.append(k*h_i)
+                    P = PermutationGroup(gens)
+        return P
+
+def homomorphism(domain, codomain, gens, images=(), check=True):
+    '''
+    Create (if possible) a group homomorphism from the group ``domain``
+    to the group ``codomain`` defined by the images of the domain's
+    generators ``gens``. ``gens`` and ``images`` can be either lists or tuples
+    of equal sizes. If ``gens`` is a proper subset of the group's generators,
+    the unspecified generators will be mapped to the identity. If the
+    images are not specified, a trivial homomorphism will be created.
+
+    If the given images of the generators do not define a homomorphism,
+    an exception is raised.
+
+    If ``check`` is ``False``, do not check whether the given images actually
+    define a homomorphism.
+
+    '''
+    if not isinstance(domain, (PermutationGroup, FpGroup, FreeGroup)):
+        raise TypeError("The domain must be a group")
+    if not isinstance(codomain, (PermutationGroup, FpGroup, FreeGroup)):
+        raise TypeError("The codomain must be a group")
+
+    generators = domain.generators
+    if not all(g in generators for g in gens):
+        raise ValueError("The supplied generators must be a subset of the domain's generators")
+    if not all(g in codomain for g in images):
+        raise ValueError("The images must be elements of the codomain")
+
+    if images and len(images) != len(gens):
+        raise ValueError("The number of images must be equal to the number of generators")
+
+    gens = list(gens)
+    images = list(images)
+
+    images.extend([codomain.identity]*(len(generators)-len(images)))
+    gens.extend([g for g in generators if g not in gens])
+    images = dict(zip(gens,images))
+
+    if check and not _check_homomorphism(domain, codomain, images):
+        raise ValueError("The given images do not define a homomorphism")
+    return GroupHomomorphism(domain, codomain, images)
+
+def _check_homomorphism(domain, codomain, images):
+    """
+    Check that a given mapping of generators to images defines a homomorphism.
+
+    Parameters
+    ==========
+    domain : PermutationGroup, FpGroup, FreeGroup
+    codomain : PermutationGroup, FpGroup, FreeGroup
+    images : dict
+        The set of keys must be equal to domain.generators.
+        The values must be elements of the codomain.
+
+    """
+    pres = domain if hasattr(domain, 'relators') else domain.presentation()
+    rels = pres.relators
+    gens = pres.generators
+    symbols = [g.ext_rep[0] for g in gens]
+    symbols_to_domain_generators = dict(zip(symbols, domain.generators))
+    identity = codomain.identity
+
+    def _image(r):
+        w = identity
+        for symbol, power in r.array_form:
+            g = symbols_to_domain_generators[symbol]
+            w *= images[g]**power
+        return w
+
+    for r in rels:
+        if isinstance(codomain, FpGroup):
+            s = codomain.equals(_image(r), identity)
+            if s is None:
+                # only try to make the rewriting system
+                # confluent when it can't determine the
+                # truth of equality otherwise
+                success = codomain.make_confluent()
+                s = codomain.equals(_image(r), identity)
+                if s is None and not success:
+                    raise RuntimeError("Can't determine if the images "
+                        "define a homomorphism. Try increasing "
+                        "the maximum number of rewriting rules "
+                        "(group._rewriting_system.set_max(new_value); "
+                        "the current value is stored in group._rewriting"
+                        "_system.maxeqns)")
+        else:
+            s = _image(r).is_identity
+        if not s:
+            return False
+    return True
+
+def orbit_homomorphism(group, omega):
+    '''
+    Return the homomorphism induced by the action of the permutation
+    group ``group`` on the set ``omega`` that is closed under the action.
+
+    '''
+    from sympy.combinatorics import Permutation
+    from sympy.combinatorics.named_groups import SymmetricGroup
+    codomain = SymmetricGroup(len(omega))
+    identity = codomain.identity
+    omega = list(omega)
+    images = {g: identity*Permutation([omega.index(o^g) for o in omega]) for g in group.generators}
+    group._schreier_sims(base=omega)
+    H = GroupHomomorphism(group, codomain, images)
+    if len(group.basic_stabilizers) > len(omega):
+        H._kernel = group.basic_stabilizers[len(omega)]
+    else:
+        H._kernel = PermutationGroup([group.identity])
+    return H
+
+def block_homomorphism(group, blocks):
+    '''
+    Return the homomorphism induced by the action of the permutation
+    group ``group`` on the block system ``blocks``. The latter should be
+    of the same form as returned by the ``minimal_block`` method for
+    permutation groups, namely a list of length ``group.degree`` where
+    the i-th entry is a representative of the block i belongs to.
+
+    '''
+    from sympy.combinatorics import Permutation
+    from sympy.combinatorics.named_groups import SymmetricGroup
+
+    n = len(blocks)
+
+    # number the blocks; m is the total number,
+    # b is such that b[i] is the number of the block i belongs to,
+    # p is the list of length m such that p[i] is the representative
+    # of the i-th block
+    m = 0
+    p = []
+    b = [None]*n
+    for i in range(n):
+        if blocks[i] == i:
+            p.append(i)
+            b[i] = m
+            m += 1
+    for i in range(n):
+        b[i] = b[blocks[i]]
+
+    codomain = SymmetricGroup(m)
+    # the list corresponding to the identity permutation in codomain
+    identity = range(m)
+    images = {g: Permutation([b[p[i]^g] for i in identity]) for g in group.generators}
+    H = GroupHomomorphism(group, codomain, images)
+    return H
+
+def group_isomorphism(G, H, isomorphism=True):
+    '''
+    Compute an isomorphism between 2 given groups.
+
+    Parameters
+    ==========
+
+    G : A finite ``FpGroup`` or a ``PermutationGroup``.
+        First group.
+
+    H : A finite ``FpGroup`` or a ``PermutationGroup``
+        Second group.
+
+    isomorphism : bool
+        This is used to avoid the computation of homomorphism
+        when the user only wants to check if there exists
+        an isomorphism between the groups.
+
+    Returns
+    =======
+
+    If isomorphism = False -- Returns a boolean.
+    If isomorphism = True  -- Returns a boolean and an isomorphism between `G` and `H`.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics import free_group, Permutation
+    >>> from sympy.combinatorics.perm_groups import PermutationGroup
+    >>> from sympy.combinatorics.fp_groups import FpGroup
+    >>> from sympy.combinatorics.homomorphisms import group_isomorphism
+    >>> from sympy.combinatorics.named_groups import DihedralGroup, AlternatingGroup
+
+    >>> D = DihedralGroup(8)
+    >>> p = Permutation(0, 1, 2, 3, 4, 5, 6, 7)
+    >>> P = PermutationGroup(p)
+    >>> group_isomorphism(D, P)
+    (False, None)
+
+    >>> F, a, b = free_group("a, b")
+    >>> G = FpGroup(F, [a**3, b**3, (a*b)**2])
+    >>> H = AlternatingGroup(4)
+    >>> (check, T) = group_isomorphism(G, H)
+    >>> check
+    True
+    >>> T(b*a*b**-1*a**-1*b**-1)
+    (0 2 3)
+
+    Notes
+    =====
+
+    Uses the approach suggested by Robert Tarjan to compute the isomorphism between two groups.
+    First, the generators of ``G`` are mapped to the elements of ``H`` and
+    we check if the mapping induces an isomorphism.
+
+    '''
+    if not isinstance(G, (PermutationGroup, FpGroup)):
+        raise TypeError("The group must be a PermutationGroup or an FpGroup")
+    if not isinstance(H, (PermutationGroup, FpGroup)):
+        raise TypeError("The group must be a PermutationGroup or an FpGroup")
+
+    if isinstance(G, FpGroup) and isinstance(H, FpGroup):
+        G = simplify_presentation(G)
+        H = simplify_presentation(H)
+        # Two infinite FpGroups with the same generators are isomorphic
+        # when the relators are same but are ordered differently.
+        if G.generators == H.generators and (G.relators).sort() == (H.relators).sort():
+            if not isomorphism:
+                return True
+            return (True, homomorphism(G, H, G.generators, H.generators))
+
+    #  `_H` is the permutation group isomorphic to `H`.
+    _H = H
+    g_order = G.order()
+    h_order = H.order()
+
+    if g_order is S.Infinity:
+        raise NotImplementedError("Isomorphism methods are not implemented for infinite groups.")
+
+    if isinstance(H, FpGroup):
+        if h_order is S.Infinity:
+            raise NotImplementedError("Isomorphism methods are not implemented for infinite groups.")
+        _H, h_isomorphism = H._to_perm_group()
+
+    if (g_order != h_order) or (G.is_abelian != H.is_abelian):
+        if not isomorphism:
+            return False
+        return (False, None)
+
+    if not isomorphism:
+        # Two groups of the same cyclic numbered order
+        # are isomorphic to each other.
+        n = g_order
+        if (igcd(n, totient(n))) == 1:
+            return True
+
+    # Match the generators of `G` with subsets of `_H`
+    gens = list(G.generators)
+    for subset in itertools.permutations(_H, len(gens)):
+        images = list(subset)
+        images.extend([_H.identity]*(len(G.generators)-len(images)))
+        _images = dict(zip(gens,images))
+        if _check_homomorphism(G, _H, _images):
+            if isinstance(H, FpGroup):
+                images = h_isomorphism.invert(images)
+            T =  homomorphism(G, H, G.generators, images, check=False)
+            if T.is_isomorphism():
+                # It is a valid isomorphism
+                if not isomorphism:
+                    return True
+                return (True, T)
+
+    if not isomorphism:
+        return False
+    return (False, None)
+
+def is_isomorphic(G, H):
+    '''
+    Check if the groups are isomorphic to each other
+
+    Parameters
+    ==========
+
+    G : A finite ``FpGroup`` or a ``PermutationGroup``
+        First group.
+
+    H : A finite ``FpGroup`` or a ``PermutationGroup``
+        Second group.
+
+    Returns
+    =======
+
+    boolean
+    '''
+    return group_isomorphism(G, H, isomorphism=False)

lib/python3.12/site-packages/sympy/combinatorics/named_groups.py

@@ -0,0 +1,332 @@
+from sympy.combinatorics.group_constructs import DirectProduct
+from sympy.combinatorics.perm_groups import PermutationGroup
+from sympy.combinatorics.permutations import Permutation
+
+_af_new = Permutation._af_new
+
+
+def AbelianGroup(*cyclic_orders):
+    """
+    Returns the direct product of cyclic groups with the given orders.
+
+    Explanation
+    ===========
+
+    According to the structure theorem for finite abelian groups ([1]),
+    every finite abelian group can be written as the direct product of
+    finitely many cyclic groups.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.named_groups import AbelianGroup
+    >>> AbelianGroup(3, 4)
+    PermutationGroup([
+            (6)(0 1 2),
+            (3 4 5 6)])
+    >>> _.is_group
+    True
+
+    See Also
+    ========
+
+    DirectProduct
+
+    References
+    ==========
+
+    .. [1] https://groupprops.subwiki.org/wiki/Structure_theorem_for_finitely_generated_abelian_groups
+
+    """
+    groups = []
+    degree = 0
+    order = 1
+    for size in cyclic_orders:
+        degree += size
+        order *= size
+        groups.append(CyclicGroup(size))
+    G = DirectProduct(*groups)
+    G._is_abelian = True
+    G._degree = degree
+    G._order = order
+
+    return G
+
+
+def AlternatingGroup(n):
+    """
+    Generates the alternating group on ``n`` elements as a permutation group.
+
+    Explanation
+    ===========
+
+    For ``n > 2``, the generators taken are ``(0 1 2), (0 1 2 ... n-1)`` for
+    ``n`` odd
+    and ``(0 1 2), (1 2 ... n-1)`` for ``n`` even (See [1], p.31, ex.6.9.).
+    After the group is generated, some of its basic properties are set.
+    The cases ``n = 1, 2`` are handled separately.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.named_groups import AlternatingGroup
+    >>> G = AlternatingGroup(4)
+    >>> G.is_group
+    True
+    >>> a = list(G.generate_dimino())
+    >>> len(a)
+    12
+    >>> all(perm.is_even for perm in a)
+    True
+
+    See Also
+    ========
+
+    SymmetricGroup, CyclicGroup, DihedralGroup
+
+    References
+    ==========
+
+    .. [1] Armstrong, M. "Groups and Symmetry"
+
+    """
+    # small cases are special
+    if n in (1, 2):
+        return PermutationGroup([Permutation([0])])
+
+    a = list(range(n))
+    a[0], a[1], a[2] = a[1], a[2], a[0]
+    gen1 = a
+    if n % 2:
+        a = list(range(1, n))
+        a.append(0)
+        gen2 = a
+    else:
+        a = list(range(2, n))
+        a.append(1)
+        a.insert(0, 0)
+        gen2 = a
+    gens = [gen1, gen2]
+    if gen1 == gen2:
+        gens = gens[:1]
+    G = PermutationGroup([_af_new(a) for a in gens], dups=False)
+
+    set_alternating_group_properties(G, n, n)
+    G._is_alt = True
+    return G
+
+
+def set_alternating_group_properties(G, n, degree):
+    """Set known properties of an alternating group. """
+    if n < 4:
+        G._is_abelian = True
+        G._is_nilpotent = True
+    else:
+        G._is_abelian = False
+        G._is_nilpotent = False
+    if n < 5:
+        G._is_solvable = True
+    else:
+        G._is_solvable = False
+    G._degree = degree
+    G._is_transitive = True
+    G._is_dihedral = False
+
+
+def CyclicGroup(n):
+    """
+    Generates the cyclic group of order ``n`` as a permutation group.
+
+    Explanation
+    ===========
+
+    The generator taken is the ``n``-cycle ``(0 1 2 ... n-1)``
+    (in cycle notation). After the group is generated, some of its basic
+    properties are set.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.named_groups import CyclicGroup
+    >>> G = CyclicGroup(6)
+    >>> G.is_group
+    True
+    >>> G.order()
+    6
+    >>> list(G.generate_schreier_sims(af=True))
+    [[0, 1, 2, 3, 4, 5], [1, 2, 3, 4, 5, 0], [2, 3, 4, 5, 0, 1],
+    [3, 4, 5, 0, 1, 2], [4, 5, 0, 1, 2, 3], [5, 0, 1, 2, 3, 4]]
+
+    See Also
+    ========
+
+    SymmetricGroup, DihedralGroup, AlternatingGroup
+
+    """
+    a = list(range(1, n))
+    a.append(0)
+    gen = _af_new(a)
+    G = PermutationGroup([gen])
+
+    G._is_abelian = True
+    G._is_nilpotent = True
+    G._is_solvable = True
+    G._degree = n
+    G._is_transitive = True
+    G._order = n
+    G._is_dihedral = (n == 2)
+    return G
+
+
+def DihedralGroup(n):
+    r"""
+    Generates the dihedral group `D_n` as a permutation group.
+
+    Explanation
+    ===========
+
+    The dihedral group `D_n` is the group of symmetries of the regular
+    ``n``-gon. The generators taken are the ``n``-cycle ``a = (0 1 2 ... n-1)``
+    (a rotation of the ``n``-gon) and ``b = (0 n-1)(1 n-2)...``
+    (a reflection of the ``n``-gon) in cycle rotation. It is easy to see that
+    these satisfy ``a**n = b**2 = 1`` and ``bab = ~a`` so they indeed generate
+    `D_n` (See [1]). After the group is generated, some of its basic properties
+    are set.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.named_groups import DihedralGroup
+    >>> G = DihedralGroup(5)
+    >>> G.is_group
+    True
+    >>> a = list(G.generate_dimino())
+    >>> [perm.cyclic_form for perm in a]
+    [[], [[0, 1, 2, 3, 4]], [[0, 2, 4, 1, 3]],
+    [[0, 3, 1, 4, 2]], [[0, 4, 3, 2, 1]], [[0, 4], [1, 3]],
+    [[1, 4], [2, 3]], [[0, 1], [2, 4]], [[0, 2], [3, 4]],
+    [[0, 3], [1, 2]]]
+
+    See Also
+    ========
+
+    SymmetricGroup, CyclicGroup, AlternatingGroup
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Dihedral_group
+
+    """
+    # small cases are special
+    if n == 1:
+        return PermutationGroup([Permutation([1, 0])])
+    if n == 2:
+        return PermutationGroup([Permutation([1, 0, 3, 2]),
+               Permutation([2, 3, 0, 1]), Permutation([3, 2, 1, 0])])
+
+    a = list(range(1, n))
+    a.append(0)
+    gen1 = _af_new(a)
+    a = list(range(n))
+    a.reverse()
+    gen2 = _af_new(a)
+    G = PermutationGroup([gen1, gen2])
+    # if n is a power of 2, group is nilpotent
+    if n & (n-1) == 0:
+        G._is_nilpotent = True
+    else:
+        G._is_nilpotent = False
+    G._is_dihedral = True
+    G._is_abelian = False
+    G._is_solvable = True
+    G._degree = n
+    G._is_transitive = True
+    G._order = 2*n
+    return G
+
+
+def SymmetricGroup(n):
+    """
+    Generates the symmetric group on ``n`` elements as a permutation group.
+
+    Explanation
+    ===========
+
+    The generators taken are the ``n``-cycle
+    ``(0 1 2 ... n-1)`` and the transposition ``(0 1)`` (in cycle notation).
+    (See [1]). After the group is generated, some of its basic properties
+    are set.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.named_groups import SymmetricGroup
+    >>> G = SymmetricGroup(4)
+    >>> G.is_group
+    True
+    >>> G.order()
+    24
+    >>> list(G.generate_schreier_sims(af=True))
+    [[0, 1, 2, 3], [1, 2, 3, 0], [2, 3, 0, 1], [3, 1, 2, 0], [0, 2, 3, 1],
+    [1, 3, 0, 2], [2, 0, 1, 3], [3, 2, 0, 1], [0, 3, 1, 2], [1, 0, 2, 3],
+    [2, 1, 3, 0], [3, 0, 1, 2], [0, 1, 3, 2], [1, 2, 0, 3], [2, 3, 1, 0],
+    [3, 1, 0, 2], [0, 2, 1, 3], [1, 3, 2, 0], [2, 0, 3, 1], [3, 2, 1, 0],
+    [0, 3, 2, 1], [1, 0, 3, 2], [2, 1, 0, 3], [3, 0, 2, 1]]
+
+    See Also
+    ========
+
+    CyclicGroup, DihedralGroup, AlternatingGroup
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Symmetric_group#Generators_and_relations
+
+    """
+    if n == 1:
+        G = PermutationGroup([Permutation([0])])
+    elif n == 2:
+        G = PermutationGroup([Permutation([1, 0])])
+    else:
+        a = list(range(1, n))
+        a.append(0)
+        gen1 = _af_new(a)
+        a = list(range(n))
+        a[0], a[1] = a[1], a[0]
+        gen2 = _af_new(a)
+        G = PermutationGroup([gen1, gen2])
+    set_symmetric_group_properties(G, n, n)
+    G._is_sym = True
+    return G
+
+
+def set_symmetric_group_properties(G, n, degree):
+    """Set known properties of a symmetric group. """
+    if n < 3:
+        G._is_abelian = True
+        G._is_nilpotent = True
+    else:
+        G._is_abelian = False
+        G._is_nilpotent = False
+    if n < 5:
+        G._is_solvable = True
+    else:
+        G._is_solvable = False
+    G._degree = degree
+    G._is_transitive = True
+    G._is_dihedral = (n in [2, 3])  # cf Landau's func and Stirling's approx
+
+
+def RubikGroup(n):
+    """Return a group of Rubik's cube generators
+
+    >>> from sympy.combinatorics.named_groups import RubikGroup
+    >>> RubikGroup(2).is_group
+    True
+    """
+    from sympy.combinatorics.generators import rubik
+    if n <= 1:
+        raise ValueError("Invalid cube. n has to be greater than 1")
+    return PermutationGroup(rubik(n))

lib/python3.12/site-packages/sympy/combinatorics/pc_groups.py

@@ -0,0 +1,709 @@
+from sympy.ntheory.primetest import isprime
+from sympy.combinatorics.perm_groups import PermutationGroup
+from sympy.printing.defaults import DefaultPrinting
+from sympy.combinatorics.free_groups import free_group
+
+
+class PolycyclicGroup(DefaultPrinting):
+
+    is_group = True
+    is_solvable = True
+
+    def __init__(self, pc_sequence, pc_series, relative_order, collector=None):
+        """
+
+        Parameters
+        ==========
+
+        pc_sequence : list
+            A sequence of elements whose classes generate the cyclic factor
+            groups of pc_series.
+        pc_series : list
+            A subnormal sequence of subgroups where each factor group is cyclic.
+        relative_order : list
+            The orders of factor groups of pc_series.
+        collector : Collector
+            By default, it is None. Collector class provides the
+            polycyclic presentation with various other functionalities.
+
+        """
+        self.pcgs = pc_sequence
+        self.pc_series = pc_series
+        self.relative_order = relative_order
+        self.collector = Collector(self.pcgs, pc_series, relative_order) if not collector else collector
+
+    def is_prime_order(self):
+        return all(isprime(order) for order in self.relative_order)
+
+    def length(self):
+        return len(self.pcgs)
+
+
+class Collector(DefaultPrinting):
+
+    """
+    References
+    ==========
+
+    .. [1] Holt, D., Eick, B., O'Brien, E.
+           "Handbook of Computational Group Theory"
+           Section 8.1.3
+    """
+
+    def __init__(self, pcgs, pc_series, relative_order, free_group_=None, pc_presentation=None):
+        """
+
+        Most of the parameters for the Collector class are the same as for PolycyclicGroup.
+        Others are described below.
+
+        Parameters
+        ==========
+
+        free_group_ : tuple
+            free_group_ provides the mapping of polycyclic generating
+            sequence with the free group elements.
+        pc_presentation : dict
+            Provides the presentation of polycyclic groups with the
+            help of power and conjugate relators.
+
+        See Also
+        ========
+
+        PolycyclicGroup
+
+        """
+        self.pcgs = pcgs
+        self.pc_series = pc_series
+        self.relative_order = relative_order
+        self.free_group = free_group('x:{}'.format(len(pcgs)))[0] if not free_group_ else free_group_
+        self.index = {s: i for i, s in enumerate(self.free_group.symbols)}
+        self.pc_presentation = self.pc_relators()
+
+    def minimal_uncollected_subword(self, word):
+        r"""
+        Returns the minimal uncollected subwords.
+
+        Explanation
+        ===========
+
+        A word ``v`` defined on generators in ``X`` is a minimal
+        uncollected subword of the word ``w`` if ``v`` is a subword
+        of ``w`` and it has one of the following form
+
+        * `v = {x_{i+1}}^{a_j}x_i`
+
+        * `v = {x_{i+1}}^{a_j}{x_i}^{-1}`
+
+        * `v = {x_i}^{a_j}`
+
+        for `a_j` not in `\{1, \ldots, s-1\}`. Where, ``s`` is the power
+        exponent of the corresponding generator.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.named_groups import SymmetricGroup
+        >>> from sympy.combinatorics import free_group
+        >>> G = SymmetricGroup(4)
+        >>> PcGroup = G.polycyclic_group()
+        >>> collector = PcGroup.collector
+        >>> F, x1, x2 = free_group("x1, x2")
+        >>> word = x2**2*x1**7
+        >>> collector.minimal_uncollected_subword(word)
+        ((x2, 2),)
+
+        """
+        # To handle the case word = <identity>
+        if not word:
+            return None
+
+        array = word.array_form
+        re = self.relative_order
+        index = self.index
+
+        for i in range(len(array)):
+            s1, e1 = array[i]
+
+            if re[index[s1]] and (e1 < 0 or e1 > re[index[s1]]-1):
+                return ((s1, e1), )
+
+        for i in range(len(array)-1):
+            s1, e1 = array[i]
+            s2, e2 = array[i+1]
+
+            if index[s1] > index[s2]:
+                e = 1 if e2 > 0 else -1
+                return ((s1, e1), (s2, e))
+
+        return None
+
+    def relations(self):
+        """
+        Separates the given relators of pc presentation in power and
+        conjugate relations.
+
+        Returns
+        =======
+
+        (power_rel, conj_rel)
+            Separates pc presentation into power and conjugate relations.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.named_groups import SymmetricGroup
+        >>> G = SymmetricGroup(3)
+        >>> PcGroup = G.polycyclic_group()
+        >>> collector = PcGroup.collector
+        >>> power_rel, conj_rel = collector.relations()
+        >>> power_rel
+        {x0**2: (), x1**3: ()}
+        >>> conj_rel
+        {x0**-1*x1*x0: x1**2}
+
+        See Also
+        ========
+
+        pc_relators
+
+        """
+        power_relators = {}
+        conjugate_relators = {}
+        for key, value in self.pc_presentation.items():
+            if len(key.array_form) == 1:
+                power_relators[key] = value
+            else:
+                conjugate_relators[key] = value
+        return power_relators, conjugate_relators
+
+    def subword_index(self, word, w):
+        """
+        Returns the start and ending index of a given
+        subword in a word.
+
+        Parameters
+        ==========
+
+        word : FreeGroupElement
+            word defined on free group elements for a
+            polycyclic group.
+        w : FreeGroupElement
+            subword of a given word, whose starting and
+            ending index to be computed.
+
+        Returns
+        =======
+
+        (i, j)
+            A tuple containing starting and ending index of ``w``
+            in the given word.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.named_groups import SymmetricGroup
+        >>> from sympy.combinatorics import free_group
+        >>> G = SymmetricGroup(4)
+        >>> PcGroup = G.polycyclic_group()
+        >>> collector = PcGroup.collector
+        >>> F, x1, x2 = free_group("x1, x2")
+        >>> word = x2**2*x1**7
+        >>> w = x2**2*x1
+        >>> collector.subword_index(word, w)
+        (0, 3)
+        >>> w = x1**7
+        >>> collector.subword_index(word, w)
+        (2, 9)
+
+        """
+        low = -1
+        high = -1
+        for i in range(len(word)-len(w)+1):
+            if word.subword(i, i+len(w)) == w:
+                low = i
+                high = i+len(w)
+                break
+        if low == high == -1:
+            return -1, -1
+        return low, high
+
+    def map_relation(self, w):
+        """
+        Return a conjugate relation.
+
+        Explanation
+        ===========
+
+        Given a word formed by two free group elements, the
+        corresponding conjugate relation with those free
+        group elements is formed and mapped with the collected
+        word in the polycyclic presentation.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.named_groups import SymmetricGroup
+        >>> from sympy.combinatorics import free_group
+        >>> G = SymmetricGroup(3)
+        >>> PcGroup = G.polycyclic_group()
+        >>> collector = PcGroup.collector
+        >>> F, x0, x1 = free_group("x0, x1")
+        >>> w = x1*x0
+        >>> collector.map_relation(w)
+        x1**2
+
+        See Also
+        ========
+
+        pc_presentation
+
+        """
+        array = w.array_form
+        s1 = array[0][0]
+        s2 = array[1][0]
+        key = ((s2, -1), (s1, 1), (s2, 1))
+        key = self.free_group.dtype(key)
+        return self.pc_presentation[key]
+
+
+    def collected_word(self, word):
+        r"""
+        Return the collected form of a word.
+
+        Explanation
+        ===========
+
+        A word ``w`` is called collected, if `w = {x_{i_1}}^{a_1} * \ldots *
+        {x_{i_r}}^{a_r}` with `i_1 < i_2< \ldots < i_r` and `a_j` is in
+        `\{1, \ldots, {s_j}-1\}`.
+
+        Otherwise w is uncollected.
+
+        Parameters
+        ==========
+
+        word : FreeGroupElement
+            An uncollected word.
+
+        Returns
+        =======
+
+        word
+            A collected word of form `w = {x_{i_1}}^{a_1}, \ldots,
+            {x_{i_r}}^{a_r}` with `i_1, i_2, \ldots, i_r` and `a_j \in
+            \{1, \ldots, {s_j}-1\}`.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.named_groups import SymmetricGroup
+        >>> from sympy.combinatorics.perm_groups import PermutationGroup
+        >>> from sympy.combinatorics import free_group
+        >>> G = SymmetricGroup(4)
+        >>> PcGroup = G.polycyclic_group()
+        >>> collector = PcGroup.collector
+        >>> F, x0, x1, x2, x3 = free_group("x0, x1, x2, x3")
+        >>> word = x3*x2*x1*x0
+        >>> collected_word = collector.collected_word(word)
+        >>> free_to_perm = {}
+        >>> free_group = collector.free_group
+        >>> for sym, gen in zip(free_group.symbols, collector.pcgs):
+        ...     free_to_perm[sym] = gen
+        >>> G1 = PermutationGroup()
+        >>> for w in word:
+        ...     sym = w[0]
+        ...     perm = free_to_perm[sym]
+        ...     G1 = PermutationGroup([perm] + G1.generators)
+        >>> G2 = PermutationGroup()
+        >>> for w in collected_word:
+        ...     sym = w[0]
+        ...     perm = free_to_perm[sym]
+        ...     G2 = PermutationGroup([perm] + G2.generators)
+
+        The two are not identical, but they are equivalent:
+
+        >>> G1.equals(G2), G1 == G2
+        (True, False)
+
+        See Also
+        ========
+
+        minimal_uncollected_subword
+
+        """
+        free_group = self.free_group
+        while True:
+            w = self.minimal_uncollected_subword(word)
+            if not w:
+                break
+
+            low, high = self.subword_index(word, free_group.dtype(w))
+            if low == -1:
+                continue
+
+            s1, e1 = w[0]
+            if len(w) == 1:
+                re = self.relative_order[self.index[s1]]
+                q = e1 // re
+                r = e1-q*re
+
+                key = ((w[0][0], re), )
+                key = free_group.dtype(key)
+                if self.pc_presentation[key]:
+                    presentation = self.pc_presentation[key].array_form
+                    sym, exp = presentation[0]
+                    word_ = ((w[0][0], r), (sym, q*exp))
+                    word_ = free_group.dtype(word_)
+                else:
+                    if r != 0:
+                        word_ = ((w[0][0], r), )
+                        word_ = free_group.dtype(word_)
+                    else:
+                        word_ = None
+                word = word.eliminate_word(free_group.dtype(w), word_)
+
+            if len(w) == 2 and w[1][1] > 0:
+                s2, e2 = w[1]
+                s2 = ((s2, 1), )
+                s2 = free_group.dtype(s2)
+                word_ = self.map_relation(free_group.dtype(w))
+                word_ = s2*word_**e1
+                word_ = free_group.dtype(word_)
+                word = word.substituted_word(low, high, word_)
+
+            elif len(w) == 2 and w[1][1] < 0:
+                s2, e2 = w[1]
+                s2 = ((s2, 1), )
+                s2 = free_group.dtype(s2)
+                word_ = self.map_relation(free_group.dtype(w))
+                word_ = s2**-1*word_**e1
+                word_ = free_group.dtype(word_)
+                word = word.substituted_word(low, high, word_)
+
+        return word
+
+
+    def pc_relators(self):
+        r"""
+        Return the polycyclic presentation.
+
+        Explanation
+        ===========
+
+        There are two types of relations used in polycyclic
+        presentation.
+
+        * Power relations : Power relators are of the form `x_i^{re_i}`,
+          where `i \in \{0, \ldots, \mathrm{len(pcgs)}\}`, ``x`` represents polycyclic
+          generator and ``re`` is the corresponding relative order.
+
+        * Conjugate relations : Conjugate relators are of the form `x_j^-1x_ix_j`,
+          where `j < i \in \{0, \ldots, \mathrm{len(pcgs)}\}`.
+
+        Returns
+        =======
+
+        A dictionary with power and conjugate relations as key and
+        their collected form as corresponding values.
+
+        Notes
+        =====
+
+        Identity Permutation is mapped with empty ``()``.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.named_groups import SymmetricGroup
+        >>> from sympy.combinatorics.permutations import Permutation
+        >>> S = SymmetricGroup(49).sylow_subgroup(7)
+        >>> der = S.derived_series()
+        >>> G = der[len(der)-2]
+        >>> PcGroup = G.polycyclic_group()
+        >>> collector = PcGroup.collector
+        >>> pcgs = PcGroup.pcgs
+        >>> len(pcgs)
+        6
+        >>> free_group = collector.free_group
+        >>> pc_resentation = collector.pc_presentation
+        >>> free_to_perm = {}
+        >>> for s, g in zip(free_group.symbols, pcgs):
+        ...     free_to_perm[s] = g
+
+        >>> for k, v in pc_resentation.items():
+        ...     k_array = k.array_form
+        ...     if v != ():
+        ...        v_array = v.array_form
+        ...     lhs = Permutation()
+        ...     for gen in k_array:
+        ...         s = gen[0]
+        ...         e = gen[1]
+        ...         lhs = lhs*free_to_perm[s]**e
+        ...     if v == ():
+        ...         assert lhs.is_identity
+        ...         continue
+        ...     rhs = Permutation()
+        ...     for gen in v_array:
+        ...         s = gen[0]
+        ...         e = gen[1]
+        ...         rhs = rhs*free_to_perm[s]**e
+        ...     assert lhs == rhs
+
+        """
+        free_group = self.free_group
+        rel_order = self.relative_order
+        pc_relators = {}
+        perm_to_free = {}
+        pcgs = self.pcgs
+
+        for gen, s in zip(pcgs, free_group.generators):
+            perm_to_free[gen**-1] = s**-1
+            perm_to_free[gen] = s
+
+        pcgs = pcgs[::-1]
+        series = self.pc_series[::-1]
+        rel_order = rel_order[::-1]
+        collected_gens = []
+
+        for i, gen in enumerate(pcgs):
+            re = rel_order[i]
+            relation = perm_to_free[gen]**re
+            G = series[i]
+
+            l = G.generator_product(gen**re, original = True)
+            l.reverse()
+
+            word = free_group.identity
+            for g in l:
+                word = word*perm_to_free[g]
+
+            word = self.collected_word(word)
+            pc_relators[relation] = word if word else ()
+            self.pc_presentation = pc_relators
+
+            collected_gens.append(gen)
+            if len(collected_gens) > 1:
+                conj = collected_gens[len(collected_gens)-1]
+                conjugator = perm_to_free[conj]
+
+                for j in range(len(collected_gens)-1):
+                    conjugated = perm_to_free[collected_gens[j]]
+
+                    relation = conjugator**-1*conjugated*conjugator
+                    gens = conj**-1*collected_gens[j]*conj
+
+                    l = G.generator_product(gens, original = True)
+                    l.reverse()
+                    word = free_group.identity
+                    for g in l:
+                        word = word*perm_to_free[g]
+
+                    word = self.collected_word(word)
+                    pc_relators[relation] = word if word else ()
+                    self.pc_presentation = pc_relators
+
+        return pc_relators
+
+    def exponent_vector(self, element):
+        r"""
+        Return the exponent vector of length equal to the
+        length of polycyclic generating sequence.
+
+        Explanation
+        ===========
+
+        For a given generator/element ``g`` of the polycyclic group,
+        it can be represented as `g = {x_1}^{e_1}, \ldots, {x_n}^{e_n}`,
+        where `x_i` represents polycyclic generators and ``n`` is
+        the number of generators in the free_group equal to the length
+        of pcgs.
+
+        Parameters
+        ==========
+
+        element : Permutation
+            Generator of a polycyclic group.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.named_groups import SymmetricGroup
+        >>> from sympy.combinatorics.permutations import Permutation
+        >>> G = SymmetricGroup(4)
+        >>> PcGroup = G.polycyclic_group()
+        >>> collector = PcGroup.collector
+        >>> pcgs = PcGroup.pcgs
+        >>> collector.exponent_vector(G[0])
+        [1, 0, 0, 0]
+        >>> exp = collector.exponent_vector(G[1])
+        >>> g = Permutation()
+        >>> for i in range(len(exp)):
+        ...     g = g*pcgs[i]**exp[i] if exp[i] else g
+        >>> assert g == G[1]
+
+        References
+        ==========
+
+        .. [1] Holt, D., Eick, B., O'Brien, E.
+               "Handbook of Computational Group Theory"
+               Section 8.1.1, Definition 8.4
+
+        """
+        free_group = self.free_group
+        G = PermutationGroup()
+        for g in self.pcgs:
+            G = PermutationGroup([g] + G.generators)
+        gens = G.generator_product(element, original = True)
+        gens.reverse()
+
+        perm_to_free = {}
+        for sym, g in zip(free_group.generators, self.pcgs):
+            perm_to_free[g**-1] = sym**-1
+            perm_to_free[g] = sym
+        w = free_group.identity
+        for g in gens:
+            w = w*perm_to_free[g]
+
+        word = self.collected_word(w)
+
+        index = self.index
+        exp_vector = [0]*len(free_group)
+        word = word.array_form
+        for t in word:
+            exp_vector[index[t[0]]] = t[1]
+        return exp_vector
+
+    def depth(self, element):
+        r"""
+        Return the depth of a given element.
+
+        Explanation
+        ===========
+
+        The depth of a given element ``g`` is defined by
+        `\mathrm{dep}[g] = i` if `e_1 = e_2 = \ldots = e_{i-1} = 0`
+        and `e_i != 0`, where ``e`` represents the exponent-vector.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.named_groups import SymmetricGroup
+        >>> G = SymmetricGroup(3)
+        >>> PcGroup = G.polycyclic_group()
+        >>> collector = PcGroup.collector
+        >>> collector.depth(G[0])
+        2
+        >>> collector.depth(G[1])
+        1
+
+        References
+        ==========
+
+        .. [1] Holt, D., Eick, B., O'Brien, E.
+               "Handbook of Computational Group Theory"
+               Section 8.1.1, Definition 8.5
+
+        """
+        exp_vector = self.exponent_vector(element)
+        return next((i+1 for i, x in enumerate(exp_vector) if x), len(self.pcgs)+1)
+
+    def leading_exponent(self, element):
+        r"""
+        Return the leading non-zero exponent.
+
+        Explanation
+        ===========
+
+        The leading exponent for a given element `g` is defined
+        by `\mathrm{leading\_exponent}[g]` `= e_i`, if `\mathrm{depth}[g] = i`.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.named_groups import SymmetricGroup
+        >>> G = SymmetricGroup(3)
+        >>> PcGroup = G.polycyclic_group()
+        >>> collector = PcGroup.collector
+        >>> collector.leading_exponent(G[1])
+        1
+
+        """
+        exp_vector = self.exponent_vector(element)
+        depth = self.depth(element)
+        if depth != len(self.pcgs)+1:
+            return exp_vector[depth-1]
+        return None
+
+    def _sift(self, z, g):
+        h = g
+        d = self.depth(h)
+        while d < len(self.pcgs) and z[d-1] != 1:
+            k = z[d-1]
+            e = self.leading_exponent(h)*(self.leading_exponent(k))**-1
+            e = e % self.relative_order[d-1]
+            h = k**-e*h
+            d = self.depth(h)
+        return h
+
+    def induced_pcgs(self, gens):
+        """
+
+        Parameters
+        ==========
+
+        gens : list
+            A list of generators on which polycyclic subgroup
+            is to be defined.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.named_groups import SymmetricGroup
+        >>> S = SymmetricGroup(8)
+        >>> G = S.sylow_subgroup(2)
+        >>> PcGroup = G.polycyclic_group()
+        >>> collector = PcGroup.collector
+        >>> gens = [G[0], G[1]]
+        >>> ipcgs = collector.induced_pcgs(gens)
+        >>> [gen.order() for gen in ipcgs]
+        [2, 2, 2]
+        >>> G = S.sylow_subgroup(3)
+        >>> PcGroup = G.polycyclic_group()
+        >>> collector = PcGroup.collector
+        >>> gens = [G[0], G[1]]
+        >>> ipcgs = collector.induced_pcgs(gens)
+        >>> [gen.order() for gen in ipcgs]
+        [3]
+
+        """
+        z = [1]*len(self.pcgs)
+        G = gens
+        while G:
+            g = G.pop(0)
+            h = self._sift(z, g)
+            d = self.depth(h)
+            if d < len(self.pcgs):
+                for gen in z:
+                    if gen != 1:
+                        G.append(h**-1*gen**-1*h*gen)
+                z[d-1] = h;
+        z = [gen for gen in z if gen != 1]
+        return z
+
+    def constructive_membership_test(self, ipcgs, g):
+        """
+        Return the exponent vector for induced pcgs.
+        """
+        e = [0]*len(ipcgs)
+        h = g
+        d = self.depth(h)
+        for i, gen in enumerate(ipcgs):
+            while self.depth(gen) == d:
+                f = self.leading_exponent(h)*self.leading_exponent(gen)
+                f = f % self.relative_order[d-1]
+                h = gen**(-f)*h
+                e[i] = f
+                d = self.depth(h)
+        if h == 1:
+            return e
+        return False

lib/python3.12/site-packages/sympy/combinatorics/permutations.py

@@ -0,0 +1,3115 @@
+import random
+from collections import defaultdict
+from collections.abc import Iterable
+from functools import reduce
+
+from sympy.core.parameters import global_parameters
+from sympy.core.basic import Atom
+from sympy.core.expr import Expr
+from sympy.core.numbers import int_valued
+from sympy.core.numbers import Integer
+from sympy.core.sympify import _sympify
+from sympy.matrices import zeros
+from sympy.polys.polytools import lcm
+from sympy.printing.repr import srepr
+from sympy.utilities.iterables import (flatten, has_variety, minlex,
+    has_dups, runs, is_sequence)
+from sympy.utilities.misc import as_int
+from mpmath.libmp.libintmath import ifac
+from sympy.multipledispatch import dispatch
+
+def _af_rmul(a, b):
+    """
+    Return the product b*a; input and output are array forms. The ith value
+    is a[b[i]].
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.permutations import _af_rmul, Permutation
+
+    >>> a, b = [1, 0, 2], [0, 2, 1]
+    >>> _af_rmul(a, b)
+    [1, 2, 0]
+    >>> [a[b[i]] for i in range(3)]
+    [1, 2, 0]
+
+    This handles the operands in reverse order compared to the ``*`` operator:
+
+    >>> a = Permutation(a)
+    >>> b = Permutation(b)
+    >>> list(a*b)
+    [2, 0, 1]
+    >>> [b(a(i)) for i in range(3)]
+    [2, 0, 1]
+
+    See Also
+    ========
+
+    rmul, _af_rmuln
+    """
+    return [a[i] for i in b]
+
+
+def _af_rmuln(*abc):
+    """
+    Given [a, b, c, ...] return the product of ...*c*b*a using array forms.
+    The ith value is a[b[c[i]]].
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.permutations import _af_rmul, Permutation
+
+    >>> a, b = [1, 0, 2], [0, 2, 1]
+    >>> _af_rmul(a, b)
+    [1, 2, 0]
+    >>> [a[b[i]] for i in range(3)]
+    [1, 2, 0]
+
+    This handles the operands in reverse order compared to the ``*`` operator:
+
+    >>> a = Permutation(a); b = Permutation(b)
+    >>> list(a*b)
+    [2, 0, 1]
+    >>> [b(a(i)) for i in range(3)]
+    [2, 0, 1]
+
+    See Also
+    ========
+
+    rmul, _af_rmul
+    """
+    a = abc
+    m = len(a)
+    if m == 3:
+        p0, p1, p2 = a
+        return [p0[p1[i]] for i in p2]
+    if m == 4:
+        p0, p1, p2, p3 = a
+        return [p0[p1[p2[i]]] for i in p3]
+    if m == 5:
+        p0, p1, p2, p3, p4 = a
+        return [p0[p1[p2[p3[i]]]] for i in p4]
+    if m == 6:
+        p0, p1, p2, p3, p4, p5 = a
+        return [p0[p1[p2[p3[p4[i]]]]] for i in p5]
+    if m == 7:
+        p0, p1, p2, p3, p4, p5, p6 = a
+        return [p0[p1[p2[p3[p4[p5[i]]]]]] for i in p6]
+    if m == 8:
+        p0, p1, p2, p3, p4, p5, p6, p7 = a
+        return [p0[p1[p2[p3[p4[p5[p6[i]]]]]]] for i in p7]
+    if m == 1:
+        return a[0][:]
+    if m == 2:
+        a, b = a
+        return [a[i] for i in b]
+    if m == 0:
+        raise ValueError("String must not be empty")
+    p0 = _af_rmuln(*a[:m//2])
+    p1 = _af_rmuln(*a[m//2:])
+    return [p0[i] for i in p1]
+
+
+def _af_parity(pi):
+    """
+    Computes the parity of a permutation in array form.
+
+    Explanation
+    ===========
+
+    The parity of a permutation reflects the parity of the
+    number of inversions in the permutation, i.e., the
+    number of pairs of x and y such that x > y but p[x] < p[y].
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.permutations import _af_parity
+    >>> _af_parity([0, 1, 2, 3])
+    0
+    >>> _af_parity([3, 2, 0, 1])
+    1
+
+    See Also
+    ========
+
+    Permutation
+    """
+    n = len(pi)
+    a = [0] * n
+    c = 0
+    for j in range(n):
+        if a[j] == 0:
+            c += 1
+            a[j] = 1
+            i = j
+            while pi[i] != j:
+                i = pi[i]
+                a[i] = 1
+    return (n - c) % 2
+
+
+def _af_invert(a):
+    """
+    Finds the inverse, ~A, of a permutation, A, given in array form.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.permutations import _af_invert, _af_rmul
+    >>> A = [1, 2, 0, 3]
+    >>> _af_invert(A)
+    [2, 0, 1, 3]
+    >>> _af_rmul(_, A)
+    [0, 1, 2, 3]
+
+    See Also
+    ========
+
+    Permutation, __invert__
+    """
+    inv_form = [0] * len(a)
+    for i, ai in enumerate(a):
+        inv_form[ai] = i
+    return inv_form
+
+
+def _af_pow(a, n):
+    """
+    Routine for finding powers of a permutation.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics import Permutation
+    >>> from sympy.combinatorics.permutations import _af_pow
+    >>> p = Permutation([2, 0, 3, 1])
+    >>> p.order()
+    4
+    >>> _af_pow(p._array_form, 4)
+    [0, 1, 2, 3]
+    """
+    if n == 0:
+        return list(range(len(a)))
+    if n < 0:
+        return _af_pow(_af_invert(a), -n)
+    if n == 1:
+        return a[:]
+    elif n == 2:
+        b = [a[i] for i in a]
+    elif n == 3:
+        b = [a[a[i]] for i in a]
+    elif n == 4:
+        b = [a[a[a[i]]] for i in a]
+    else:
+        # use binary multiplication
+        b = list(range(len(a)))
+        while 1:
+            if n & 1:
+                b = [b[i] for i in a]
+                n -= 1
+                if not n:
+                    break
+            if n % 4 == 0:
+                a = [a[a[a[i]]] for i in a]
+                n = n // 4
+            elif n % 2 == 0:
+                a = [a[i] for i in a]
+                n = n // 2
+    return b
+
+
+def _af_commutes_with(a, b):
+    """
+    Checks if the two permutations with array forms
+    given by ``a`` and ``b`` commute.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.permutations import _af_commutes_with
+    >>> _af_commutes_with([1, 2, 0], [0, 2, 1])
+    False
+
+    See Also
+    ========
+
+    Permutation, commutes_with
+    """
+    return not any(a[b[i]] != b[a[i]] for i in range(len(a) - 1))
+
+
+class Cycle(dict):
+    """
+    Wrapper around dict which provides the functionality of a disjoint cycle.
+
+    Explanation
+    ===========
+
+    A cycle shows the rule to use to move subsets of elements to obtain
+    a permutation. The Cycle class is more flexible than Permutation in
+    that 1) all elements need not be present in order to investigate how
+    multiple cycles act in sequence and 2) it can contain singletons:
+
+    >>> from sympy.combinatorics.permutations import Perm, Cycle
+
+    A Cycle will automatically parse a cycle given as a tuple on the rhs:
+
+    >>> Cycle(1, 2)(2, 3)
+    (1 3 2)
+
+    The identity cycle, Cycle(), can be used to start a product:
+
+    >>> Cycle()(1, 2)(2, 3)
+    (1 3 2)
+
+    The array form of a Cycle can be obtained by calling the list
+    method (or passing it to the list function) and all elements from
+    0 will be shown:
+
+    >>> a = Cycle(1, 2)
+    >>> a.list()
+    [0, 2, 1]
+    >>> list(a)
+    [0, 2, 1]
+
+    If a larger (or smaller) range is desired use the list method and
+    provide the desired size -- but the Cycle cannot be truncated to
+    a size smaller than the largest element that is out of place:
+
+    >>> b = Cycle(2, 4)(1, 2)(3, 1, 4)(1, 3)
+    >>> b.list()
+    [0, 2, 1, 3, 4]
+    >>> b.list(b.size + 1)
+    [0, 2, 1, 3, 4, 5]
+    >>> b.list(-1)
+    [0, 2, 1]
+
+    Singletons are not shown when printing with one exception: the largest
+    element is always shown -- as a singleton if necessary:
+
+    >>> Cycle(1, 4, 10)(4, 5)
+    (1 5 4 10)
+    >>> Cycle(1, 2)(4)(5)(10)
+    (1 2)(10)
+
+    The array form can be used to instantiate a Permutation so other
+    properties of the permutation can be investigated:
+
+    >>> Perm(Cycle(1, 2)(3, 4).list()).transpositions()
+    [(1, 2), (3, 4)]
+
+    Notes
+    =====
+
+    The underlying structure of the Cycle is a dictionary and although
+    the __iter__ method has been redefined to give the array form of the
+    cycle, the underlying dictionary items are still available with the
+    such methods as items():
+
+    >>> list(Cycle(1, 2).items())
+    [(1, 2), (2, 1)]
+
+    See Also
+    ========
+
+    Permutation
+    """
+    def __missing__(self, arg):
+        """Enter arg into dictionary and return arg."""
+        return as_int(arg)
+
+    def __iter__(self):
+        yield from self.list()
+
+    def __call__(self, *other):
+        """Return product of cycles processed from R to L.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Cycle
+        >>> Cycle(1, 2)(2, 3)
+        (1 3 2)
+
+        An instance of a Cycle will automatically parse list-like
+        objects and Permutations that are on the right. It is more
+        flexible than the Permutation in that all elements need not
+        be present:
+
+        >>> a = Cycle(1, 2)
+        >>> a(2, 3)
+        (1 3 2)
+        >>> a(2, 3)(4, 5)
+        (1 3 2)(4 5)
+
+        """
+        rv = Cycle(*other)
+        for k, v in zip(list(self.keys()), [rv[self[k]] for k in self.keys()]):
+            rv[k] = v
+        return rv
+
+    def list(self, size=None):
+        """Return the cycles as an explicit list starting from 0 up
+        to the greater of the largest value in the cycles and size.
+
+        Truncation of trailing unmoved items will occur when size
+        is less than the maximum element in the cycle; if this is
+        desired, setting ``size=-1`` will guarantee such trimming.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Cycle
+        >>> p = Cycle(2, 3)(4, 5)
+        >>> p.list()
+        [0, 1, 3, 2, 5, 4]
+        >>> p.list(10)
+        [0, 1, 3, 2, 5, 4, 6, 7, 8, 9]
+
+        Passing a length too small will trim trailing, unchanged elements
+        in the permutation:
+
+        >>> Cycle(2, 4)(1, 2, 4).list(-1)
+        [0, 2, 1]
+        """
+        if not self and size is None:
+            raise ValueError('must give size for empty Cycle')
+        if size is not None:
+            big = max([i for i in self.keys() if self[i] != i] + [0])
+            size = max(size, big + 1)
+        else:
+            size = self.size
+        return [self[i] for i in range(size)]
+
+    def __repr__(self):
+        """We want it to print as a Cycle, not as a dict.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Cycle
+        >>> Cycle(1, 2)
+        (1 2)
+        >>> print(_)
+        (1 2)
+        >>> list(Cycle(1, 2).items())
+        [(1, 2), (2, 1)]
+        """
+        if not self:
+            return 'Cycle()'
+        cycles = Permutation(self).cyclic_form
+        s = ''.join(str(tuple(c)) for c in cycles)
+        big = self.size - 1
+        if not any(i == big for c in cycles for i in c):
+            s += '(%s)' % big
+        return 'Cycle%s' % s
+
+    def __str__(self):
+        """We want it to be printed in a Cycle notation with no
+        comma in-between.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Cycle
+        >>> Cycle(1, 2)
+        (1 2)
+        >>> Cycle(1, 2, 4)(5, 6)
+        (1 2 4)(5 6)
+        """
+        if not self:
+            return '()'
+        cycles = Permutation(self).cyclic_form
+        s = ''.join(str(tuple(c)) for c in cycles)
+        big = self.size - 1
+        if not any(i == big for c in cycles for i in c):
+            s += '(%s)' % big
+        s = s.replace(',', '')
+        return s
+
+    def __init__(self, *args):
+        """Load up a Cycle instance with the values for the cycle.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Cycle
+        >>> Cycle(1, 2, 6)
+        (1 2 6)
+        """
+
+        if not args:
+            return
+        if len(args) == 1:
+            if isinstance(args[0], Permutation):
+                for c in args[0].cyclic_form:
+                    self.update(self(*c))
+                return
+            elif isinstance(args[0], Cycle):
+                for k, v in args[0].items():
+                    self[k] = v
+                return
+        args = [as_int(a) for a in args]
+        if any(i < 0 for i in args):
+            raise ValueError('negative integers are not allowed in a cycle.')
+        if has_dups(args):
+            raise ValueError('All elements must be unique in a cycle.')
+        for i in range(-len(args), 0):
+            self[args[i]] = args[i + 1]
+
+    @property
+    def size(self):
+        if not self:
+            return 0
+        return max(self.keys()) + 1
+
+    def copy(self):
+        return Cycle(self)
+
+
+class Permutation(Atom):
+    r"""
+    A permutation, alternatively known as an 'arrangement number' or 'ordering'
+    is an arrangement of the elements of an ordered list into a one-to-one
+    mapping with itself. The permutation of a given arrangement is given by
+    indicating the positions of the elements after re-arrangement [2]_. For
+    example, if one started with elements ``[x, y, a, b]`` (in that order) and
+    they were reordered as ``[x, y, b, a]`` then the permutation would be
+    ``[0, 1, 3, 2]``. Notice that (in SymPy) the first element is always referred
+    to as 0 and the permutation uses the indices of the elements in the
+    original ordering, not the elements ``(a, b, ...)`` themselves.
+
+    >>> from sympy.combinatorics import Permutation
+    >>> from sympy import init_printing
+    >>> init_printing(perm_cyclic=False, pretty_print=False)
+
+    Permutations Notation
+    =====================
+
+    Permutations are commonly represented in disjoint cycle or array forms.
+
+    Array Notation and 2-line Form
+    ------------------------------------
+
+    In the 2-line form, the elements and their final positions are shown
+    as a matrix with 2 rows:
+
+    [0    1    2     ... n-1]
+    [p(0) p(1) p(2)  ... p(n-1)]
+
+    Since the first line is always ``range(n)``, where n is the size of p,
+    it is sufficient to represent the permutation by the second line,
+    referred to as the "array form" of the permutation. This is entered
+    in brackets as the argument to the Permutation class:
+
+    >>> p = Permutation([0, 2, 1]); p
+    Permutation([0, 2, 1])
+
+    Given i in range(p.size), the permutation maps i to i^p
+
+    >>> [i^p for i in range(p.size)]
+    [0, 2, 1]
+
+    The composite of two permutations p*q means first apply p, then q, so
+    i^(p*q) = (i^p)^q which is i^p^q according to Python precedence rules:
+
+    >>> q = Permutation([2, 1, 0])
+    >>> [i^p^q for i in range(3)]
+    [2, 0, 1]
+    >>> [i^(p*q) for i in range(3)]
+    [2, 0, 1]
+
+    One can use also the notation p(i) = i^p, but then the composition
+    rule is (p*q)(i) = q(p(i)), not p(q(i)):
+
+    >>> [(p*q)(i) for i in range(p.size)]
+    [2, 0, 1]
+    >>> [q(p(i)) for i in range(p.size)]
+    [2, 0, 1]
+    >>> [p(q(i)) for i in range(p.size)]
+    [1, 2, 0]
+
+    Disjoint Cycle Notation
+    -----------------------
+
+    In disjoint cycle notation, only the elements that have shifted are
+    indicated.
+
+    For example, [1, 3, 2, 0] can be represented as (0, 1, 3)(2).
+    This can be understood from the 2 line format of the given permutation.
+    In the 2-line form,
+    [0    1    2   3]
+    [1    3    2   0]
+
+    The element in the 0th position is 1, so 0 -> 1. The element in the 1st
+    position is three, so 1 -> 3. And the element in the third position is again
+    0, so 3 -> 0. Thus, 0 -> 1 -> 3 -> 0, and 2 -> 2. Thus, this can be represented
+    as 2 cycles: (0, 1, 3)(2).
+    In common notation, singular cycles are not explicitly written as they can be
+    inferred implicitly.
+
+    Only the relative ordering of elements in a cycle matter:
+
+    >>> Permutation(1,2,3) == Permutation(2,3,1) == Permutation(3,1,2)
+    True
+
+    The disjoint cycle notation is convenient when representing
+    permutations that have several cycles in them:
+
+    >>> Permutation(1, 2)(3, 5) == Permutation([[1, 2], [3, 5]])
+    True
+
+    It also provides some economy in entry when computing products of
+    permutations that are written in disjoint cycle notation:
+
+    >>> Permutation(1, 2)(1, 3)(2, 3)
+    Permutation([0, 3, 2, 1])
+    >>> _ == Permutation([[1, 2]])*Permutation([[1, 3]])*Permutation([[2, 3]])
+    True
+
+        Caution: when the cycles have common elements between them then the order
+        in which the permutations are applied matters. This module applies
+        the permutations from *left to right*.
+
+        >>> Permutation(1, 2)(2, 3) == Permutation([(1, 2), (2, 3)])
+        True
+        >>> Permutation(1, 2)(2, 3).list()
+        [0, 3, 1, 2]
+
+        In the above case, (1,2) is computed before (2,3).
+        As 0 -> 0, 0 -> 0, element in position 0 is 0.
+        As 1 -> 2, 2 -> 3, element in position 1 is 3.
+        As 2 -> 1, 1 -> 1, element in position 2 is 1.
+        As 3 -> 3, 3 -> 2, element in position 3 is 2.
+
+        If the first and second elements had been
+        swapped first, followed by the swapping of the second
+        and third, the result would have been [0, 2, 3, 1].
+        If, you want to apply the cycles in the conventional
+        right to left order, call the function with arguments in reverse order
+        as demonstrated below:
+
+        >>> Permutation([(1, 2), (2, 3)][::-1]).list()
+        [0, 2, 3, 1]
+
+    Entering a singleton in a permutation is a way to indicate the size of the
+    permutation. The ``size`` keyword can also be used.
+
+    Array-form entry:
+
+    >>> Permutation([[1, 2], [9]])
+    Permutation([0, 2, 1], size=10)
+    >>> Permutation([[1, 2]], size=10)
+    Permutation([0, 2, 1], size=10)
+
+    Cyclic-form entry:
+
+    >>> Permutation(1, 2, size=10)
+    Permutation([0, 2, 1], size=10)
+    >>> Permutation(9)(1, 2)
+    Permutation([0, 2, 1], size=10)
+
+    Caution: no singleton containing an element larger than the largest
+    in any previous cycle can be entered. This is an important difference
+    in how Permutation and Cycle handle the ``__call__`` syntax. A singleton
+    argument at the start of a Permutation performs instantiation of the
+    Permutation and is permitted:
+
+    >>> Permutation(5)
+    Permutation([], size=6)
+
+    A singleton entered after instantiation is a call to the permutation
+    -- a function call -- and if the argument is out of range it will
+    trigger an error. For this reason, it is better to start the cycle
+    with the singleton:
+
+    The following fails because there is no element 3:
+
+    >>> Permutation(1, 2)(3)
+    Traceback (most recent call last):
+    ...
+    IndexError: list index out of range
+
+    This is ok: only the call to an out of range singleton is prohibited;
+    otherwise the permutation autosizes:
+
+    >>> Permutation(3)(1, 2)
+    Permutation([0, 2, 1, 3])
+    >>> Permutation(1, 2)(3, 4) == Permutation(3, 4)(1, 2)
+    True
+
+
+    Equality testing
+    ----------------
+
+    The array forms must be the same in order for permutations to be equal:
+
+    >>> Permutation([1, 0, 2, 3]) == Permutation([1, 0])
+    False
+
+
+    Identity Permutation
+    --------------------
+
+    The identity permutation is a permutation in which no element is out of
+    place. It can be entered in a variety of ways. All the following create
+    an identity permutation of size 4:
+
+    >>> I = Permutation([0, 1, 2, 3])
+    >>> all(p == I for p in [
+    ... Permutation(3),
+    ... Permutation(range(4)),
+    ... Permutation([], size=4),
+    ... Permutation(size=4)])
+    True
+
+    Watch out for entering the range *inside* a set of brackets (which is
+    cycle notation):
+
+    >>> I == Permutation([range(4)])
+    False
+
+
+    Permutation Printing
+    ====================
+
+    There are a few things to note about how Permutations are printed.
+
+    .. deprecated:: 1.6
+
+       Configuring Permutation printing by setting
+       ``Permutation.print_cyclic`` is deprecated. Users should use the
+       ``perm_cyclic`` flag to the printers, as described below.
+
+    1) If you prefer one form (array or cycle) over another, you can set
+    ``init_printing`` with the ``perm_cyclic`` flag.
+
+    >>> from sympy import init_printing
+    >>> p = Permutation(1, 2)(4, 5)(3, 4)
+    >>> p
+    Permutation([0, 2, 1, 4, 5, 3])
+
+    >>> init_printing(perm_cyclic=True, pretty_print=False)
+    >>> p
+    (1 2)(3 4 5)
+
+    2) Regardless of the setting, a list of elements in the array for cyclic
+    form can be obtained and either of those can be copied and supplied as
+    the argument to Permutation:
+
+    >>> p.array_form
+    [0, 2, 1, 4, 5, 3]
+    >>> p.cyclic_form
+    [[1, 2], [3, 4, 5]]
+    >>> Permutation(_) == p
+    True
+
+    3) Printing is economical in that as little as possible is printed while
+    retaining all information about the size of the permutation:
+
+    >>> init_printing(perm_cyclic=False, pretty_print=False)
+    >>> Permutation([1, 0, 2, 3])
+    Permutation([1, 0, 2, 3])
+    >>> Permutation([1, 0, 2, 3], size=20)
+    Permutation([1, 0], size=20)
+    >>> Permutation([1, 0, 2, 4, 3, 5, 6], size=20)
+    Permutation([1, 0, 2, 4, 3], size=20)
+
+    >>> p = Permutation([1, 0, 2, 3])
+    >>> init_printing(perm_cyclic=True, pretty_print=False)
+    >>> p
+    (3)(0 1)
+    >>> init_printing(perm_cyclic=False, pretty_print=False)
+
+    The 2 was not printed but it is still there as can be seen with the
+    array_form and size methods:
+
+    >>> p.array_form
+    [1, 0, 2, 3]
+    >>> p.size
+    4
+
+    Short introduction to other methods
+    ===================================
+
+    The permutation can act as a bijective function, telling what element is
+    located at a given position
+
+    >>> q = Permutation([5, 2, 3, 4, 1, 0])
+    >>> q.array_form[1] # the hard way
+    2
+    >>> q(1) # the easy way
+    2
+    >>> {i: q(i) for i in range(q.size)} # showing the bijection
+    {0: 5, 1: 2, 2: 3, 3: 4, 4: 1, 5: 0}
+
+    The full cyclic form (including singletons) can be obtained:
+
+    >>> p.full_cyclic_form
+    [[0, 1], [2], [3]]
+
+    Any permutation can be factored into transpositions of pairs of elements:
+
+    >>> Permutation([[1, 2], [3, 4, 5]]).transpositions()
+    [(1, 2), (3, 5), (3, 4)]
+    >>> Permutation.rmul(*[Permutation([ti], size=6) for ti in _]).cyclic_form
+    [[1, 2], [3, 4, 5]]
+
+    The number of permutations on a set of n elements is given by n! and is
+    called the cardinality.
+
+    >>> p.size
+    4
+    >>> p.cardinality
+    24
+
+    A given permutation has a rank among all the possible permutations of the
+    same elements, but what that rank is depends on how the permutations are
+    enumerated. (There are a number of different methods of doing so.) The
+    lexicographic rank is given by the rank method and this rank is used to
+    increment a permutation with addition/subtraction:
+
+    >>> p.rank()
+    6
+    >>> p + 1
+    Permutation([1, 0, 3, 2])
+    >>> p.next_lex()
+    Permutation([1, 0, 3, 2])
+    >>> _.rank()
+    7
+    >>> p.unrank_lex(p.size, rank=7)
+    Permutation([1, 0, 3, 2])
+
+    The product of two permutations p and q is defined as their composition as
+    functions, (p*q)(i) = q(p(i)) [6]_.
+
+    >>> p = Permutation([1, 0, 2, 3])
+    >>> q = Permutation([2, 3, 1, 0])
+    >>> list(q*p)
+    [2, 3, 0, 1]
+    >>> list(p*q)
+    [3, 2, 1, 0]
+    >>> [q(p(i)) for i in range(p.size)]
+    [3, 2, 1, 0]
+
+    The permutation can be 'applied' to any list-like object, not only
+    Permutations:
+
+    >>> p(['zero', 'one', 'four', 'two'])
+    ['one', 'zero', 'four', 'two']
+    >>> p('zo42')
+    ['o', 'z', '4', '2']
+
+    If you have a list of arbitrary elements, the corresponding permutation
+    can be found with the from_sequence method:
+
+    >>> Permutation.from_sequence('SymPy')
+    Permutation([1, 3, 2, 0, 4])
+
+    Checking if a Permutation is contained in a Group
+    =================================================
+
+    Generally if you have a group of permutations G on n symbols, and
+    you're checking if a permutation on less than n symbols is part
+    of that group, the check will fail.
+
+    Here is an example for n=5 and we check if the cycle
+    (1,2,3) is in G:
+
+    >>> from sympy import init_printing
+    >>> init_printing(perm_cyclic=True, pretty_print=False)
+    >>> from sympy.combinatorics import Cycle, Permutation
+    >>> from sympy.combinatorics.perm_groups import PermutationGroup
+    >>> G = PermutationGroup(Cycle(2, 3)(4, 5), Cycle(1, 2, 3, 4, 5))
+    >>> p1 = Permutation(Cycle(2, 5, 3))
+    >>> p2 = Permutation(Cycle(1, 2, 3))
+    >>> a1 = Permutation(Cycle(1, 2, 3).list(6))
+    >>> a2 = Permutation(Cycle(1, 2, 3)(5))
+    >>> a3 = Permutation(Cycle(1, 2, 3),size=6)
+    >>> for p in [p1,p2,a1,a2,a3]: p, G.contains(p)
+    ((2 5 3), True)
+    ((1 2 3), False)
+    ((5)(1 2 3), True)
+    ((5)(1 2 3), True)
+    ((5)(1 2 3), True)
+
+    The check for p2 above will fail.
+
+    Checking if p1 is in G works because SymPy knows
+    G is a group on 5 symbols, and p1 is also on 5 symbols
+    (its largest element is 5).
+
+    For ``a1``, the ``.list(6)`` call will extend the permutation to 5
+    symbols, so the test will work as well. In the case of ``a2`` the
+    permutation is being extended to 5 symbols by using a singleton,
+    and in the case of ``a3`` it's extended through the constructor
+    argument ``size=6``.
+
+    There is another way to do this, which is to tell the ``contains``
+    method that the number of symbols the group is on does not need to
+    match perfectly the number of symbols for the permutation:
+
+    >>> G.contains(p2,strict=False)
+    True
+
+    This can be via the ``strict`` argument to the ``contains`` method,
+    and SymPy will try to extend the permutation on its own and then
+    perform the containment check.
+
+    See Also
+    ========
+
+    Cycle
+
+    References
+    ==========
+
+    .. [1] Skiena, S. 'Permutations.' 1.1 in Implementing Discrete Mathematics
+           Combinatorics and Graph Theory with Mathematica.  Reading, MA:
+           Addison-Wesley, pp. 3-16, 1990.
+
+    .. [2] Knuth, D. E. The Art of Computer Programming, Vol. 4: Combinatorial
+           Algorithms, 1st ed. Reading, MA: Addison-Wesley, 2011.
+
+    .. [3] Wendy Myrvold and Frank Ruskey. 2001. Ranking and unranking
+           permutations in linear time. Inf. Process. Lett. 79, 6 (September 2001),
+           281-284. DOI=10.1016/S0020-0190(01)00141-7
+
+    .. [4] D. L. Kreher, D. R. Stinson 'Combinatorial Algorithms'
+           CRC Press, 1999
+
+    .. [5] Graham, R. L.; Knuth, D. E.; and Patashnik, O.
+           Concrete Mathematics: A Foundation for Computer Science, 2nd ed.
+           Reading, MA: Addison-Wesley, 1994.
+
+    .. [6] https://en.wikipedia.org/w/index.php?oldid=499948155#Product_and_inverse
+
+    .. [7] https://en.wikipedia.org/wiki/Lehmer_code
+
+    """
+
+    is_Permutation = True
+
+    _array_form = None
+    _cyclic_form = None
+    _cycle_structure = None
+    _size = None
+    _rank = None
+
+    def __new__(cls, *args, size=None, **kwargs):
+        """
+        Constructor for the Permutation object from a list or a
+        list of lists in which all elements of the permutation may
+        appear only once.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> from sympy import init_printing
+        >>> init_printing(perm_cyclic=False, pretty_print=False)
+
+        Permutations entered in array-form are left unaltered:
+
+        >>> Permutation([0, 2, 1])
+        Permutation([0, 2, 1])
+
+        Permutations entered in cyclic form are converted to array form;
+        singletons need not be entered, but can be entered to indicate the
+        largest element:
+
+        >>> Permutation([[4, 5, 6], [0, 1]])
+        Permutation([1, 0, 2, 3, 5, 6, 4])
+        >>> Permutation([[4, 5, 6], [0, 1], [19]])
+        Permutation([1, 0, 2, 3, 5, 6, 4], size=20)
+
+        All manipulation of permutations assumes that the smallest element
+        is 0 (in keeping with 0-based indexing in Python) so if the 0 is
+        missing when entering a permutation in array form, an error will be
+        raised:
+
+        >>> Permutation([2, 1])
+        Traceback (most recent call last):
+        ...
+        ValueError: Integers 0 through 2 must be present.
+
+        If a permutation is entered in cyclic form, it can be entered without
+        singletons and the ``size`` specified so those values can be filled
+        in, otherwise the array form will only extend to the maximum value
+        in the cycles:
+
+        >>> Permutation([[1, 4], [3, 5, 2]], size=10)
+        Permutation([0, 4, 3, 5, 1, 2], size=10)
+        >>> _.array_form
+        [0, 4, 3, 5, 1, 2, 6, 7, 8, 9]
+        """
+        if size is not None:
+            size = int(size)
+
+        #a) ()
+        #b) (1) = identity
+        #c) (1, 2) = cycle
+        #d) ([1, 2, 3]) = array form
+        #e) ([[1, 2]]) = cyclic form
+        #f) (Cycle) = conversion to permutation
+        #g) (Permutation) = adjust size or return copy
+        ok = True
+        if not args:  # a
+            return cls._af_new(list(range(size or 0)))
+        elif len(args) > 1:  # c
+            return cls._af_new(Cycle(*args).list(size))
+        if len(args) == 1:
+            a = args[0]
+            if isinstance(a, cls):  # g
+                if size is None or size == a.size:
+                    return a
+                return cls(a.array_form, size=size)
+            if isinstance(a, Cycle):  # f
+                return cls._af_new(a.list(size))
+            if not is_sequence(a):  # b
+                if size is not None and a + 1 > size:
+                    raise ValueError('size is too small when max is %s' % a)
+                return cls._af_new(list(range(a + 1)))
+            if has_variety(is_sequence(ai) for ai in a):
+                ok = False
+        else:
+            ok = False
+        if not ok:
+            raise ValueError("Permutation argument must be a list of ints, "
+                             "a list of lists, Permutation or Cycle.")
+
+        # safe to assume args are valid; this also makes a copy
+        # of the args
+        args = list(args[0])
+
+        is_cycle = args and is_sequence(args[0])
+        if is_cycle:  # e
+            args = [[int(i) for i in c] for c in args]
+        else:  # d
+            args = [int(i) for i in args]
+
+        # if there are n elements present, 0, 1, ..., n-1 should be present
+        # unless a cycle notation has been provided. A 0 will be added
+        # for convenience in case one wants to enter permutations where
+        # counting starts from 1.
+
+        temp = flatten(args)
+        if has_dups(temp) and not is_cycle:
+            raise ValueError('there were repeated elements.')
+        temp = set(temp)
+
+        if not is_cycle:
+            if temp != set(range(len(temp))):
+                raise ValueError('Integers 0 through %s must be present.' %
+                max(temp))
+            if size is not None and temp and max(temp) + 1 > size:
+                raise ValueError('max element should not exceed %s' % (size - 1))
+
+        if is_cycle:
+            # it's not necessarily canonical so we won't store
+            # it -- use the array form instead
+            c = Cycle()
+            for ci in args:
+                c = c(*ci)
+            aform = c.list()
+        else:
+            aform = list(args)
+        if size and size > len(aform):
+            # don't allow for truncation of permutation which
+            # might split a cycle and lead to an invalid aform
+            # but do allow the permutation size to be increased
+            aform.extend(list(range(len(aform), size)))
+
+        return cls._af_new(aform)
+
+    @classmethod
+    def _af_new(cls, perm):
+        """A method to produce a Permutation object from a list;
+        the list is bound to the _array_form attribute, so it must
+        not be modified; this method is meant for internal use only;
+        the list ``a`` is supposed to be generated as a temporary value
+        in a method, so p = Perm._af_new(a) is the only object
+        to hold a reference to ``a``::
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.permutations import Perm
+        >>> from sympy import init_printing
+        >>> init_printing(perm_cyclic=False, pretty_print=False)
+        >>> a = [2, 1, 3, 0]
+        >>> p = Perm._af_new(a)
+        >>> p
+        Permutation([2, 1, 3, 0])
+
+        """
+        p = super().__new__(cls)
+        p._array_form = perm
+        p._size = len(perm)
+        return p
+
+    def copy(self):
+        return self.__class__(self.array_form)
+
+    def __getnewargs__(self):
+        return (self.array_form,)
+
+    def _hashable_content(self):
+        # the array_form (a list) is the Permutation arg, so we need to
+        # return a tuple, instead
+        return tuple(self.array_form)
+
+    @property
+    def array_form(self):
+        """
+        Return a copy of the attribute _array_form
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([[2, 0], [3, 1]])
+        >>> p.array_form
+        [2, 3, 0, 1]
+        >>> Permutation([[2, 0, 3, 1]]).array_form
+        [3, 2, 0, 1]
+        >>> Permutation([2, 0, 3, 1]).array_form
+        [2, 0, 3, 1]
+        >>> Permutation([[1, 2], [4, 5]]).array_form
+        [0, 2, 1, 3, 5, 4]
+        """
+        return self._array_form[:]
+
+    def list(self, size=None):
+        """Return the permutation as an explicit list, possibly
+        trimming unmoved elements if size is less than the maximum
+        element in the permutation; if this is desired, setting
+        ``size=-1`` will guarantee such trimming.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation(2, 3)(4, 5)
+        >>> p.list()
+        [0, 1, 3, 2, 5, 4]
+        >>> p.list(10)
+        [0, 1, 3, 2, 5, 4, 6, 7, 8, 9]
+
+        Passing a length too small will trim trailing, unchanged elements
+        in the permutation:
+
+        >>> Permutation(2, 4)(1, 2, 4).list(-1)
+        [0, 2, 1]
+        >>> Permutation(3).list(-1)
+        []
+        """
+        if not self and size is None:
+            raise ValueError('must give size for empty Cycle')
+        rv = self.array_form
+        if size is not None:
+            if size > self.size:
+                rv.extend(list(range(self.size, size)))
+            else:
+                # find first value from rhs where rv[i] != i
+                i = self.size - 1
+                while rv:
+                    if rv[-1] != i:
+                        break
+                    rv.pop()
+                    i -= 1
+        return rv
+
+    @property
+    def cyclic_form(self):
+        """
+        This is used to convert to the cyclic notation
+        from the canonical notation. Singletons are omitted.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([0, 3, 1, 2])
+        >>> p.cyclic_form
+        [[1, 3, 2]]
+        >>> Permutation([1, 0, 2, 4, 3, 5]).cyclic_form
+        [[0, 1], [3, 4]]
+
+        See Also
+        ========
+
+        array_form, full_cyclic_form
+        """
+        if self._cyclic_form is not None:
+            return list(self._cyclic_form)
+        array_form = self.array_form
+        unchecked = [True] * len(array_form)
+        cyclic_form = []
+        for i in range(len(array_form)):
+            if unchecked[i]:
+                cycle = []
+                cycle.append(i)
+                unchecked[i] = False
+                j = i
+                while unchecked[array_form[j]]:
+                    j = array_form[j]
+                    cycle.append(j)
+                    unchecked[j] = False
+                if len(cycle) > 1:
+                    cyclic_form.append(cycle)
+                    assert cycle == list(minlex(cycle))
+        cyclic_form.sort()
+        self._cyclic_form = cyclic_form[:]
+        return cyclic_form
+
+    @property
+    def full_cyclic_form(self):
+        """Return permutation in cyclic form including singletons.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> Permutation([0, 2, 1]).full_cyclic_form
+        [[0], [1, 2]]
+        """
+        need = set(range(self.size)) - set(flatten(self.cyclic_form))
+        rv = self.cyclic_form + [[i] for i in need]
+        rv.sort()
+        return rv
+
+    @property
+    def size(self):
+        """
+        Returns the number of elements in the permutation.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> Permutation([[3, 2], [0, 1]]).size
+        4
+
+        See Also
+        ========
+
+        cardinality, length, order, rank
+        """
+        return self._size
+
+    def support(self):
+        """Return the elements in permutation, P, for which P[i] != i.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([[3, 2], [0, 1], [4]])
+        >>> p.array_form
+        [1, 0, 3, 2, 4]
+        >>> p.support()
+        [0, 1, 2, 3]
+        """
+        a = self.array_form
+        return [i for i, e in enumerate(a) if a[i] != i]
+
+    def __add__(self, other):
+        """Return permutation that is other higher in rank than self.
+
+        The rank is the lexicographical rank, with the identity permutation
+        having rank of 0.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> I = Permutation([0, 1, 2, 3])
+        >>> a = Permutation([2, 1, 3, 0])
+        >>> I + a.rank() == a
+        True
+
+        See Also
+        ========
+
+        __sub__, inversion_vector
+
+        """
+        rank = (self.rank() + other) % self.cardinality
+        rv = self.unrank_lex(self.size, rank)
+        rv._rank = rank
+        return rv
+
+    def __sub__(self, other):
+        """Return the permutation that is other lower in rank than self.
+
+        See Also
+        ========
+
+        __add__
+        """
+        return self.__add__(-other)
+
+    @staticmethod
+    def rmul(*args):
+        """
+        Return product of Permutations [a, b, c, ...] as the Permutation whose
+        ith value is a(b(c(i))).
+
+        a, b, c, ... can be Permutation objects or tuples.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+
+        >>> a, b = [1, 0, 2], [0, 2, 1]
+        >>> a = Permutation(a); b = Permutation(b)
+        >>> list(Permutation.rmul(a, b))
+        [1, 2, 0]
+        >>> [a(b(i)) for i in range(3)]
+        [1, 2, 0]
+
+        This handles the operands in reverse order compared to the ``*`` operator:
+
+        >>> a = Permutation(a); b = Permutation(b)
+        >>> list(a*b)
+        [2, 0, 1]
+        >>> [b(a(i)) for i in range(3)]
+        [2, 0, 1]
+
+        Notes
+        =====
+
+        All items in the sequence will be parsed by Permutation as
+        necessary as long as the first item is a Permutation:
+
+        >>> Permutation.rmul(a, [0, 2, 1]) == Permutation.rmul(a, b)
+        True
+
+        The reverse order of arguments will raise a TypeError.
+
+        """
+        rv = args[0]
+        for i in range(1, len(args)):
+            rv = args[i]*rv
+        return rv
+
+    @classmethod
+    def rmul_with_af(cls, *args):
+        """
+        same as rmul, but the elements of args are Permutation objects
+        which have _array_form
+        """
+        a = [x._array_form for x in args]
+        rv = cls._af_new(_af_rmuln(*a))
+        return rv
+
+    def mul_inv(self, other):
+        """
+        other*~self, self and other have _array_form
+        """
+        a = _af_invert(self._array_form)
+        b = other._array_form
+        return self._af_new(_af_rmul(a, b))
+
+    def __rmul__(self, other):
+        """This is needed to coerce other to Permutation in rmul."""
+        cls = type(self)
+        return cls(other)*self
+
+    def __mul__(self, other):
+        """
+        Return the product a*b as a Permutation; the ith value is b(a(i)).
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.permutations import _af_rmul, Permutation
+
+        >>> a, b = [1, 0, 2], [0, 2, 1]
+        >>> a = Permutation(a); b = Permutation(b)
+        >>> list(a*b)
+        [2, 0, 1]
+        >>> [b(a(i)) for i in range(3)]
+        [2, 0, 1]
+
+        This handles operands in reverse order compared to _af_rmul and rmul:
+
+        >>> al = list(a); bl = list(b)
+        >>> _af_rmul(al, bl)
+        [1, 2, 0]
+        >>> [al[bl[i]] for i in range(3)]
+        [1, 2, 0]
+
+        It is acceptable for the arrays to have different lengths; the shorter
+        one will be padded to match the longer one:
+
+        >>> from sympy import init_printing
+        >>> init_printing(perm_cyclic=False, pretty_print=False)
+        >>> b*Permutation([1, 0])
+        Permutation([1, 2, 0])
+        >>> Permutation([1, 0])*b
+        Permutation([2, 0, 1])
+
+        It is also acceptable to allow coercion to handle conversion of a
+        single list to the left of a Permutation:
+
+        >>> [0, 1]*a # no change: 2-element identity
+        Permutation([1, 0, 2])
+        >>> [[0, 1]]*a # exchange first two elements
+        Permutation([0, 1, 2])
+
+        You cannot use more than 1 cycle notation in a product of cycles
+        since coercion can only handle one argument to the left. To handle
+        multiple cycles it is convenient to use Cycle instead of Permutation:
+
+        >>> [[1, 2]]*[[2, 3]]*Permutation([]) # doctest: +SKIP
+        >>> from sympy.combinatorics.permutations import Cycle
+        >>> Cycle(1, 2)(2, 3)
+        (1 3 2)
+
+        """
+        from sympy.combinatorics.perm_groups import PermutationGroup, Coset
+        if isinstance(other, PermutationGroup):
+            return Coset(self, other, dir='-')
+        a = self.array_form
+        # __rmul__ makes sure the other is a Permutation
+        b = other.array_form
+        if not b:
+            perm = a
+        else:
+            b.extend(list(range(len(b), len(a))))
+            perm = [b[i] for i in a] + b[len(a):]
+        return self._af_new(perm)
+
+    def commutes_with(self, other):
+        """
+        Checks if the elements are commuting.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> a = Permutation([1, 4, 3, 0, 2, 5])
+        >>> b = Permutation([0, 1, 2, 3, 4, 5])
+        >>> a.commutes_with(b)
+        True
+        >>> b = Permutation([2, 3, 5, 4, 1, 0])
+        >>> a.commutes_with(b)
+        False
+        """
+        a = self.array_form
+        b = other.array_form
+        return _af_commutes_with(a, b)
+
+    def __pow__(self, n):
+        """
+        Routine for finding powers of a permutation.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> from sympy import init_printing
+        >>> init_printing(perm_cyclic=False, pretty_print=False)
+        >>> p = Permutation([2, 0, 3, 1])
+        >>> p.order()
+        4
+        >>> p**4
+        Permutation([0, 1, 2, 3])
+        """
+        if isinstance(n, Permutation):
+            raise NotImplementedError(
+                'p**p is not defined; do you mean p^p (conjugate)?')
+        n = int(n)
+        return self._af_new(_af_pow(self.array_form, n))
+
+    def __rxor__(self, i):
+        """Return self(i) when ``i`` is an int.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation(1, 2, 9)
+        >>> 2^p == p(2) == 9
+        True
+        """
+        if int_valued(i):
+            return self(i)
+        else:
+            raise NotImplementedError(
+                "i^p = p(i) when i is an integer, not %s." % i)
+
+    def __xor__(self, h):
+        """Return the conjugate permutation ``~h*self*h` `.
+
+        Explanation
+        ===========
+
+        If ``a`` and ``b`` are conjugates, ``a = h*b*~h`` and
+        ``b = ~h*a*h`` and both have the same cycle structure.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation(1, 2, 9)
+        >>> q = Permutation(6, 9, 8)
+        >>> p*q != q*p
+        True
+
+        Calculate and check properties of the conjugate:
+
+        >>> c = p^q
+        >>> c == ~q*p*q and p == q*c*~q
+        True
+
+        The expression q^p^r is equivalent to q^(p*r):
+
+        >>> r = Permutation(9)(4, 6, 8)
+        >>> q^p^r == q^(p*r)
+        True
+
+        If the term to the left of the conjugate operator, i, is an integer
+        then this is interpreted as selecting the ith element from the
+        permutation to the right:
+
+        >>> all(i^p == p(i) for i in range(p.size))
+        True
+
+        Note that the * operator as higher precedence than the ^ operator:
+
+        >>> q^r*p^r == q^(r*p)^r == Permutation(9)(1, 6, 4)
+        True
+
+        Notes
+        =====
+
+        In Python the precedence rule is p^q^r = (p^q)^r which differs
+        in general from p^(q^r)
+
+        >>> q^p^r
+        (9)(1 4 8)
+        >>> q^(p^r)
+        (9)(1 8 6)
+
+        For a given r and p, both of the following are conjugates of p:
+        ~r*p*r and r*p*~r. But these are not necessarily the same:
+
+        >>> ~r*p*r == r*p*~r
+        True
+
+        >>> p = Permutation(1, 2, 9)(5, 6)
+        >>> ~r*p*r == r*p*~r
+        False
+
+        The conjugate ~r*p*r was chosen so that ``p^q^r`` would be equivalent
+        to ``p^(q*r)`` rather than ``p^(r*q)``. To obtain r*p*~r, pass ~r to
+        this method:
+
+        >>> p^~r == r*p*~r
+        True
+        """
+
+        if self.size != h.size:
+            raise ValueError("The permutations must be of equal size.")
+        a = [None]*self.size
+        h = h._array_form
+        p = self._array_form
+        for i in range(self.size):
+            a[h[i]] = h[p[i]]
+        return self._af_new(a)
+
+    def transpositions(self):
+        """
+        Return the permutation decomposed into a list of transpositions.
+
+        Explanation
+        ===========
+
+        It is always possible to express a permutation as the product of
+        transpositions, see [1]
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([[1, 2, 3], [0, 4, 5, 6, 7]])
+        >>> t = p.transpositions()
+        >>> t
+        [(0, 7), (0, 6), (0, 5), (0, 4), (1, 3), (1, 2)]
+        >>> print(''.join(str(c) for c in t))
+        (0, 7)(0, 6)(0, 5)(0, 4)(1, 3)(1, 2)
+        >>> Permutation.rmul(*[Permutation([ti], size=p.size) for ti in t]) == p
+        True
+
+        References
+        ==========
+
+        .. [1] https://en.wikipedia.org/wiki/Transposition_%28mathematics%29#Properties
+
+        """
+        a = self.cyclic_form
+        res = []
+        for x in a:
+            nx = len(x)
+            if nx == 2:
+                res.append(tuple(x))
+            elif nx > 2:
+                first = x[0]
+                for y in x[nx - 1:0:-1]:
+                    res.append((first, y))
+        return res
+
+    @classmethod
+    def from_sequence(self, i, key=None):
+        """Return the permutation needed to obtain ``i`` from the sorted
+        elements of ``i``. If custom sorting is desired, a key can be given.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+
+        >>> Permutation.from_sequence('SymPy')
+        (4)(0 1 3)
+        >>> _(sorted("SymPy"))
+        ['S', 'y', 'm', 'P', 'y']
+        >>> Permutation.from_sequence('SymPy', key=lambda x: x.lower())
+        (4)(0 2)(1 3)
+        """
+        ic = list(zip(i, list(range(len(i)))))
+        if key:
+            ic.sort(key=lambda x: key(x[0]))
+        else:
+            ic.sort()
+        return ~Permutation([i[1] for i in ic])
+
+    def __invert__(self):
+        """
+        Return the inverse of the permutation.
+
+        A permutation multiplied by its inverse is the identity permutation.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> from sympy import init_printing
+        >>> init_printing(perm_cyclic=False, pretty_print=False)
+        >>> p = Permutation([[2, 0], [3, 1]])
+        >>> ~p
+        Permutation([2, 3, 0, 1])
+        >>> _ == p**-1
+        True
+        >>> p*~p == ~p*p == Permutation([0, 1, 2, 3])
+        True
+        """
+        return self._af_new(_af_invert(self._array_form))
+
+    def __iter__(self):
+        """Yield elements from array form.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> list(Permutation(range(3)))
+        [0, 1, 2]
+        """
+        yield from self.array_form
+
+    def __repr__(self):
+        return srepr(self)
+
+    def __call__(self, *i):
+        """
+        Allows applying a permutation instance as a bijective function.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([[2, 0], [3, 1]])
+        >>> p.array_form
+        [2, 3, 0, 1]
+        >>> [p(i) for i in range(4)]
+        [2, 3, 0, 1]
+
+        If an array is given then the permutation selects the items
+        from the array (i.e. the permutation is applied to the array):
+
+        >>> from sympy.abc import x
+        >>> p([x, 1, 0, x**2])
+        [0, x**2, x, 1]
+        """
+        # list indices can be Integer or int; leave this
+        # as it is (don't test or convert it) because this
+        # gets called a lot and should be fast
+        if len(i) == 1:
+            i = i[0]
+            if not isinstance(i, Iterable):
+                i = as_int(i)
+                if i < 0 or i > self.size:
+                    raise TypeError(
+                        "{} should be an integer between 0 and {}"
+                        .format(i, self.size-1))
+                return self._array_form[i]
+            # P([a, b, c])
+            if len(i) != self.size:
+                raise TypeError(
+                    "{} should have the length {}.".format(i, self.size))
+            return [i[j] for j in self._array_form]
+        # P(1, 2, 3)
+        return self*Permutation(Cycle(*i), size=self.size)
+
+    def atoms(self):
+        """
+        Returns all the elements of a permutation
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> Permutation([0, 1, 2, 3, 4, 5]).atoms()
+        {0, 1, 2, 3, 4, 5}
+        >>> Permutation([[0, 1], [2, 3], [4, 5]]).atoms()
+        {0, 1, 2, 3, 4, 5}
+        """
+        return set(self.array_form)
+
+    def apply(self, i):
+        r"""Apply the permutation to an expression.
+
+        Parameters
+        ==========
+
+        i : Expr
+            It should be an integer between $0$ and $n-1$ where $n$
+            is the size of the permutation.
+
+            If it is a symbol or a symbolic expression that can
+            have integer values, an ``AppliedPermutation`` object
+            will be returned which can represent an unevaluated
+            function.
+
+        Notes
+        =====
+
+        Any permutation can be defined as a bijective function
+        $\sigma : \{ 0, 1, \dots, n-1 \} \rightarrow \{ 0, 1, \dots, n-1 \}$
+        where $n$ denotes the size of the permutation.
+
+        The definition may even be extended for any set with distinctive
+        elements, such that the permutation can even be applied for
+        real numbers or such, however, it is not implemented for now for
+        computational reasons and the integrity with the group theory
+        module.
+
+        This function is similar to the ``__call__`` magic, however,
+        ``__call__`` magic already has some other applications like
+        permuting an array or attaching new cycles, which would
+        not always be mathematically consistent.
+
+        This also guarantees that the return type is a SymPy integer,
+        which guarantees the safety to use assumptions.
+        """
+        i = _sympify(i)
+        if i.is_integer is False:
+            raise NotImplementedError("{} should be an integer.".format(i))
+
+        n = self.size
+        if (i < 0) == True or (i >= n) == True:
+            raise NotImplementedError(
+                "{} should be an integer between 0 and {}".format(i, n-1))
+
+        if i.is_Integer:
+            return Integer(self._array_form[i])
+        return AppliedPermutation(self, i)
+
+    def next_lex(self):
+        """
+        Returns the next permutation in lexicographical order.
+        If self is the last permutation in lexicographical order
+        it returns None.
+        See [4] section 2.4.
+
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([2, 3, 1, 0])
+        >>> p = Permutation([2, 3, 1, 0]); p.rank()
+        17
+        >>> p = p.next_lex(); p.rank()
+        18
+
+        See Also
+        ========
+
+        rank, unrank_lex
+        """
+        perm = self.array_form[:]
+        n = len(perm)
+        i = n - 2
+        while perm[i + 1] < perm[i]:
+            i -= 1
+        if i == -1:
+            return None
+        else:
+            j = n - 1
+            while perm[j] < perm[i]:
+                j -= 1
+            perm[j], perm[i] = perm[i], perm[j]
+            i += 1
+            j = n - 1
+            while i < j:
+                perm[j], perm[i] = perm[i], perm[j]
+                i += 1
+                j -= 1
+        return self._af_new(perm)
+
+    @classmethod
+    def unrank_nonlex(self, n, r):
+        """
+        This is a linear time unranking algorithm that does not
+        respect lexicographic order [3].
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> from sympy import init_printing
+        >>> init_printing(perm_cyclic=False, pretty_print=False)
+        >>> Permutation.unrank_nonlex(4, 5)
+        Permutation([2, 0, 3, 1])
+        >>> Permutation.unrank_nonlex(4, -1)
+        Permutation([0, 1, 2, 3])
+
+        See Also
+        ========
+
+        next_nonlex, rank_nonlex
+        """
+        def _unrank1(n, r, a):
+            if n > 0:
+                a[n - 1], a[r % n] = a[r % n], a[n - 1]
+                _unrank1(n - 1, r//n, a)
+
+        id_perm = list(range(n))
+        n = int(n)
+        r = r % ifac(n)
+        _unrank1(n, r, id_perm)
+        return self._af_new(id_perm)
+
+    def rank_nonlex(self, inv_perm=None):
+        """
+        This is a linear time ranking algorithm that does not
+        enforce lexicographic order [3].
+
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([0, 1, 2, 3])
+        >>> p.rank_nonlex()
+        23
+
+        See Also
+        ========
+
+        next_nonlex, unrank_nonlex
+        """
+        def _rank1(n, perm, inv_perm):
+            if n == 1:
+                return 0
+            s = perm[n - 1]
+            t = inv_perm[n - 1]
+            perm[n - 1], perm[t] = perm[t], s
+            inv_perm[n - 1], inv_perm[s] = inv_perm[s], t
+            return s + n*_rank1(n - 1, perm, inv_perm)
+
+        if inv_perm is None:
+            inv_perm = (~self).array_form
+        if not inv_perm:
+            return 0
+        perm = self.array_form[:]
+        r = _rank1(len(perm), perm, inv_perm)
+        return r
+
+    def next_nonlex(self):
+        """
+        Returns the next permutation in nonlex order [3].
+        If self is the last permutation in this order it returns None.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> from sympy import init_printing
+        >>> init_printing(perm_cyclic=False, pretty_print=False)
+        >>> p = Permutation([2, 0, 3, 1]); p.rank_nonlex()
+        5
+        >>> p = p.next_nonlex(); p
+        Permutation([3, 0, 1, 2])
+        >>> p.rank_nonlex()
+        6
+
+        See Also
+        ========
+
+        rank_nonlex, unrank_nonlex
+        """
+        r = self.rank_nonlex()
+        if r == ifac(self.size) - 1:
+            return None
+        return self.unrank_nonlex(self.size, r + 1)
+
+    def rank(self):
+        """
+        Returns the lexicographic rank of the permutation.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([0, 1, 2, 3])
+        >>> p.rank()
+        0
+        >>> p = Permutation([3, 2, 1, 0])
+        >>> p.rank()
+        23
+
+        See Also
+        ========
+
+        next_lex, unrank_lex, cardinality, length, order, size
+        """
+        if self._rank is not None:
+            return self._rank
+        rank = 0
+        rho = self.array_form[:]
+        n = self.size - 1
+        size = n + 1
+        psize = int(ifac(n))
+        for j in range(size - 1):
+            rank += rho[j]*psize
+            for i in range(j + 1, size):
+                if rho[i] > rho[j]:
+                    rho[i] -= 1
+            psize //= n
+            n -= 1
+        self._rank = rank
+        return rank
+
+    @property
+    def cardinality(self):
+        """
+        Returns the number of all possible permutations.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([0, 1, 2, 3])
+        >>> p.cardinality
+        24
+
+        See Also
+        ========
+
+        length, order, rank, size
+        """
+        return int(ifac(self.size))
+
+    def parity(self):
+        """
+        Computes the parity of a permutation.
+
+        Explanation
+        ===========
+
+        The parity of a permutation reflects the parity of the
+        number of inversions in the permutation, i.e., the
+        number of pairs of x and y such that ``x > y`` but ``p[x] < p[y]``.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([0, 1, 2, 3])
+        >>> p.parity()
+        0
+        >>> p = Permutation([3, 2, 0, 1])
+        >>> p.parity()
+        1
+
+        See Also
+        ========
+
+        _af_parity
+        """
+        if self._cyclic_form is not None:
+            return (self.size - self.cycles) % 2
+
+        return _af_parity(self.array_form)
+
+    @property
+    def is_even(self):
+        """
+        Checks if a permutation is even.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([0, 1, 2, 3])
+        >>> p.is_even
+        True
+        >>> p = Permutation([3, 2, 1, 0])
+        >>> p.is_even
+        True
+
+        See Also
+        ========
+
+        is_odd
+        """
+        return not self.is_odd
+
+    @property
+    def is_odd(self):
+        """
+        Checks if a permutation is odd.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([0, 1, 2, 3])
+        >>> p.is_odd
+        False
+        >>> p = Permutation([3, 2, 0, 1])
+        >>> p.is_odd
+        True
+
+        See Also
+        ========
+
+        is_even
+        """
+        return bool(self.parity() % 2)
+
+    @property
+    def is_Singleton(self):
+        """
+        Checks to see if the permutation contains only one number and is
+        thus the only possible permutation of this set of numbers
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> Permutation([0]).is_Singleton
+        True
+        >>> Permutation([0, 1]).is_Singleton
+        False
+
+        See Also
+        ========
+
+        is_Empty
+        """
+        return self.size == 1
+
+    @property
+    def is_Empty(self):
+        """
+        Checks to see if the permutation is a set with zero elements
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> Permutation([]).is_Empty
+        True
+        >>> Permutation([0]).is_Empty
+        False
+
+        See Also
+        ========
+
+        is_Singleton
+        """
+        return self.size == 0
+
+    @property
+    def is_identity(self):
+        return self.is_Identity
+
+    @property
+    def is_Identity(self):
+        """
+        Returns True if the Permutation is an identity permutation.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([])
+        >>> p.is_Identity
+        True
+        >>> p = Permutation([[0], [1], [2]])
+        >>> p.is_Identity
+        True
+        >>> p = Permutation([0, 1, 2])
+        >>> p.is_Identity
+        True
+        >>> p = Permutation([0, 2, 1])
+        >>> p.is_Identity
+        False
+
+        See Also
+        ========
+
+        order
+        """
+        af = self.array_form
+        return not af or all(i == af[i] for i in range(self.size))
+
+    def ascents(self):
+        """
+        Returns the positions of ascents in a permutation, ie, the location
+        where p[i] < p[i+1]
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([4, 0, 1, 3, 2])
+        >>> p.ascents()
+        [1, 2]
+
+        See Also
+        ========
+
+        descents, inversions, min, max
+        """
+        a = self.array_form
+        pos = [i for i in range(len(a) - 1) if a[i] < a[i + 1]]
+        return pos
+
+    def descents(self):
+        """
+        Returns the positions of descents in a permutation, ie, the location
+        where p[i] > p[i+1]
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([4, 0, 1, 3, 2])
+        >>> p.descents()
+        [0, 3]
+
+        See Also
+        ========
+
+        ascents, inversions, min, max
+        """
+        a = self.array_form
+        pos = [i for i in range(len(a) - 1) if a[i] > a[i + 1]]
+        return pos
+
+    def max(self) -> int:
+        """
+        The maximum element moved by the permutation.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([1, 0, 2, 3, 4])
+        >>> p.max()
+        1
+
+        See Also
+        ========
+
+        min, descents, ascents, inversions
+        """
+        a = self.array_form
+        if not a:
+            return 0
+        return max(_a for i, _a in enumerate(a) if _a != i)
+
+    def min(self) -> int:
+        """
+        The minimum element moved by the permutation.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([0, 1, 4, 3, 2])
+        >>> p.min()
+        2
+
+        See Also
+        ========
+
+        max, descents, ascents, inversions
+        """
+        a = self.array_form
+        if not a:
+            return 0
+        return min(_a for i, _a in enumerate(a) if _a != i)
+
+    def inversions(self):
+        """
+        Computes the number of inversions of a permutation.
+
+        Explanation
+        ===========
+
+        An inversion is where i > j but p[i] < p[j].
+
+        For small length of p, it iterates over all i and j
+        values and calculates the number of inversions.
+        For large length of p, it uses a variation of merge
+        sort to calculate the number of inversions.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([0, 1, 2, 3, 4, 5])
+        >>> p.inversions()
+        0
+        >>> Permutation([3, 2, 1, 0]).inversions()
+        6
+
+        See Also
+        ========
+
+        descents, ascents, min, max
+
+        References
+        ==========
+
+        .. [1] https://www.cp.eng.chula.ac.th/~prabhas//teaching/algo/algo2008/count-inv.htm
+
+        """
+        inversions = 0
+        a = self.array_form
+        n = len(a)
+        if n < 130:
+            for i in range(n - 1):
+                b = a[i]
+                for c in a[i + 1:]:
+                    if b > c:
+                        inversions += 1
+        else:
+            k = 1
+            right = 0
+            arr = a[:]
+            temp = a[:]
+            while k < n:
+                i = 0
+                while i + k < n:
+                    right = i + k * 2 - 1
+                    if right >= n:
+                        right = n - 1
+                    inversions += _merge(arr, temp, i, i + k, right)
+                    i = i + k * 2
+                k = k * 2
+        return inversions
+
+    def commutator(self, x):
+        """Return the commutator of ``self`` and ``x``: ``~x*~self*x*self``
+
+        If f and g are part of a group, G, then the commutator of f and g
+        is the group identity iff f and g commute, i.e. fg == gf.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> from sympy import init_printing
+        >>> init_printing(perm_cyclic=False, pretty_print=False)
+        >>> p = Permutation([0, 2, 3, 1])
+        >>> x = Permutation([2, 0, 3, 1])
+        >>> c = p.commutator(x); c
+        Permutation([2, 1, 3, 0])
+        >>> c == ~x*~p*x*p
+        True
+
+        >>> I = Permutation(3)
+        >>> p = [I + i for i in range(6)]
+        >>> for i in range(len(p)):
+        ...     for j in range(len(p)):
+        ...         c = p[i].commutator(p[j])
+        ...         if p[i]*p[j] == p[j]*p[i]:
+        ...             assert c == I
+        ...         else:
+        ...             assert c != I
+        ...
+
+        References
+        ==========
+
+        .. [1] https://en.wikipedia.org/wiki/Commutator
+        """
+
+        a = self.array_form
+        b = x.array_form
+        n = len(a)
+        if len(b) != n:
+            raise ValueError("The permutations must be of equal size.")
+        inva = [None]*n
+        for i in range(n):
+            inva[a[i]] = i
+        invb = [None]*n
+        for i in range(n):
+            invb[b[i]] = i
+        return self._af_new([a[b[inva[i]]] for i in invb])
+
+    def signature(self):
+        """
+        Gives the signature of the permutation needed to place the
+        elements of the permutation in canonical order.
+
+        The signature is calculated as (-1)^<number of inversions>
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([0, 1, 2])
+        >>> p.inversions()
+        0
+        >>> p.signature()
+        1
+        >>> q = Permutation([0,2,1])
+        >>> q.inversions()
+        1
+        >>> q.signature()
+        -1
+
+        See Also
+        ========
+
+        inversions
+        """
+        if self.is_even:
+            return 1
+        return -1
+
+    def order(self):
+        """
+        Computes the order of a permutation.
+
+        When the permutation is raised to the power of its
+        order it equals the identity permutation.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> from sympy import init_printing
+        >>> init_printing(perm_cyclic=False, pretty_print=False)
+        >>> p = Permutation([3, 1, 5, 2, 4, 0])
+        >>> p.order()
+        4
+        >>> (p**(p.order()))
+        Permutation([], size=6)
+
+        See Also
+        ========
+
+        identity, cardinality, length, rank, size
+        """
+
+        return reduce(lcm, [len(cycle) for cycle in self.cyclic_form], 1)
+
+    def length(self):
+        """
+        Returns the number of integers moved by a permutation.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> Permutation([0, 3, 2, 1]).length()
+        2
+        >>> Permutation([[0, 1], [2, 3]]).length()
+        4
+
+        See Also
+        ========
+
+        min, max, support, cardinality, order, rank, size
+        """
+
+        return len(self.support())
+
+    @property
+    def cycle_structure(self):
+        """Return the cycle structure of the permutation as a dictionary
+        indicating the multiplicity of each cycle length.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> Permutation(3).cycle_structure
+        {1: 4}
+        >>> Permutation(0, 4, 3)(1, 2)(5, 6).cycle_structure
+        {2: 2, 3: 1}
+        """
+        if self._cycle_structure:
+            rv = self._cycle_structure
+        else:
+            rv = defaultdict(int)
+            singletons = self.size
+            for c in self.cyclic_form:
+                rv[len(c)] += 1
+                singletons -= len(c)
+            if singletons:
+                rv[1] = singletons
+            self._cycle_structure = rv
+        return dict(rv)  # make a copy
+
+    @property
+    def cycles(self):
+        """
+        Returns the number of cycles contained in the permutation
+        (including singletons).
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> Permutation([0, 1, 2]).cycles
+        3
+        >>> Permutation([0, 1, 2]).full_cyclic_form
+        [[0], [1], [2]]
+        >>> Permutation(0, 1)(2, 3).cycles
+        2
+
+        See Also
+        ========
+        sympy.functions.combinatorial.numbers.stirling
+        """
+        return len(self.full_cyclic_form)
+
+    def index(self):
+        """
+        Returns the index of a permutation.
+
+        The index of a permutation is the sum of all subscripts j such
+        that p[j] is greater than p[j+1].
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([3, 0, 2, 1, 4])
+        >>> p.index()
+        2
+        """
+        a = self.array_form
+
+        return sum(j for j in range(len(a) - 1) if a[j] > a[j + 1])
+
+    def runs(self):
+        """
+        Returns the runs of a permutation.
+
+        An ascending sequence in a permutation is called a run [5].
+
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([2, 5, 7, 3, 6, 0, 1, 4, 8])
+        >>> p.runs()
+        [[2, 5, 7], [3, 6], [0, 1, 4, 8]]
+        >>> q = Permutation([1,3,2,0])
+        >>> q.runs()
+        [[1, 3], [2], [0]]
+        """
+        return runs(self.array_form)
+
+    def inversion_vector(self):
+        """Return the inversion vector of the permutation.
+
+        The inversion vector consists of elements whose value
+        indicates the number of elements in the permutation
+        that are lesser than it and lie on its right hand side.
+
+        The inversion vector is the same as the Lehmer encoding of a
+        permutation.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([4, 8, 0, 7, 1, 5, 3, 6, 2])
+        >>> p.inversion_vector()
+        [4, 7, 0, 5, 0, 2, 1, 1]
+        >>> p = Permutation([3, 2, 1, 0])
+        >>> p.inversion_vector()
+        [3, 2, 1]
+
+        The inversion vector increases lexicographically with the rank
+        of the permutation, the -ith element cycling through 0..i.
+
+        >>> p = Permutation(2)
+        >>> while p:
+        ...     print('%s %s %s' % (p, p.inversion_vector(), p.rank()))
+        ...     p = p.next_lex()
+        (2) [0, 0] 0
+        (1 2) [0, 1] 1
+        (2)(0 1) [1, 0] 2
+        (0 1 2) [1, 1] 3
+        (0 2 1) [2, 0] 4
+        (0 2) [2, 1] 5
+
+        See Also
+        ========
+
+        from_inversion_vector
+        """
+        self_array_form = self.array_form
+        n = len(self_array_form)
+        inversion_vector = [0] * (n - 1)
+
+        for i in range(n - 1):
+            val = 0
+            for j in range(i + 1, n):
+                if self_array_form[j] < self_array_form[i]:
+                    val += 1
+            inversion_vector[i] = val
+        return inversion_vector
+
+    def rank_trotterjohnson(self):
+        """
+        Returns the Trotter Johnson rank, which we get from the minimal
+        change algorithm. See [4] section 2.4.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([0, 1, 2, 3])
+        >>> p.rank_trotterjohnson()
+        0
+        >>> p = Permutation([0, 2, 1, 3])
+        >>> p.rank_trotterjohnson()
+        7
+
+        See Also
+        ========
+
+        unrank_trotterjohnson, next_trotterjohnson
+        """
+        if self.array_form == [] or self.is_Identity:
+            return 0
+        if self.array_form == [1, 0]:
+            return 1
+        perm = self.array_form
+        n = self.size
+        rank = 0
+        for j in range(1, n):
+            k = 1
+            i = 0
+            while perm[i] != j:
+                if perm[i] < j:
+                    k += 1
+                i += 1
+            j1 = j + 1
+            if rank % 2 == 0:
+                rank = j1*rank + j1 - k
+            else:
+                rank = j1*rank + k - 1
+        return rank
+
+    @classmethod
+    def unrank_trotterjohnson(cls, size, rank):
+        """
+        Trotter Johnson permutation unranking. See [4] section 2.4.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> from sympy import init_printing
+        >>> init_printing(perm_cyclic=False, pretty_print=False)
+        >>> Permutation.unrank_trotterjohnson(5, 10)
+        Permutation([0, 3, 1, 2, 4])
+
+        See Also
+        ========
+
+        rank_trotterjohnson, next_trotterjohnson
+        """
+        perm = [0]*size
+        r2 = 0
+        n = ifac(size)
+        pj = 1
+        for j in range(2, size + 1):
+            pj *= j
+            r1 = (rank * pj) // n
+            k = r1 - j*r2
+            if r2 % 2 == 0:
+                for i in range(j - 1, j - k - 1, -1):
+                    perm[i] = perm[i - 1]
+                perm[j - k - 1] = j - 1
+            else:
+                for i in range(j - 1, k, -1):
+                    perm[i] = perm[i - 1]
+                perm[k] = j - 1
+            r2 = r1
+        return cls._af_new(perm)
+
+    def next_trotterjohnson(self):
+        """
+        Returns the next permutation in Trotter-Johnson order.
+        If self is the last permutation it returns None.
+        See [4] section 2.4. If it is desired to generate all such
+        permutations, they can be generated in order more quickly
+        with the ``generate_bell`` function.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> from sympy import init_printing
+        >>> init_printing(perm_cyclic=False, pretty_print=False)
+        >>> p = Permutation([3, 0, 2, 1])
+        >>> p.rank_trotterjohnson()
+        4
+        >>> p = p.next_trotterjohnson(); p
+        Permutation([0, 3, 2, 1])
+        >>> p.rank_trotterjohnson()
+        5
+
+        See Also
+        ========
+
+        rank_trotterjohnson, unrank_trotterjohnson, sympy.utilities.iterables.generate_bell
+        """
+        pi = self.array_form[:]
+        n = len(pi)
+        st = 0
+        rho = pi[:]
+        done = False
+        m = n-1
+        while m > 0 and not done:
+            d = rho.index(m)
+            for i in range(d, m):
+                rho[i] = rho[i + 1]
+            par = _af_parity(rho[:m])
+            if par == 1:
+                if d == m:
+                    m -= 1
+                else:
+                    pi[st + d], pi[st + d + 1] = pi[st + d + 1], pi[st + d]
+                    done = True
+            else:
+                if d == 0:
+                    m -= 1
+                    st += 1
+                else:
+                    pi[st + d], pi[st + d - 1] = pi[st + d - 1], pi[st + d]
+                    done = True
+        if m == 0:
+            return None
+        return self._af_new(pi)
+
+    def get_precedence_matrix(self):
+        """
+        Gets the precedence matrix. This is used for computing the
+        distance between two permutations.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> from sympy import init_printing
+        >>> init_printing(perm_cyclic=False, pretty_print=False)
+        >>> p = Permutation.josephus(3, 6, 1)
+        >>> p
+        Permutation([2, 5, 3, 1, 4, 0])
+        >>> p.get_precedence_matrix()
+        Matrix([
+        [0, 0, 0, 0, 0, 0],
+        [1, 0, 0, 0, 1, 0],
+        [1, 1, 0, 1, 1, 1],
+        [1, 1, 0, 0, 1, 0],
+        [1, 0, 0, 0, 0, 0],
+        [1, 1, 0, 1, 1, 0]])
+
+        See Also
+        ========
+
+        get_precedence_distance, get_adjacency_matrix, get_adjacency_distance
+        """
+        m = zeros(self.size)
+        perm = self.array_form
+        for i in range(m.rows):
+            for j in range(i + 1, m.cols):
+                m[perm[i], perm[j]] = 1
+        return m
+
+    def get_precedence_distance(self, other):
+        """
+        Computes the precedence distance between two permutations.
+
+        Explanation
+        ===========
+
+        Suppose p and p' represent n jobs. The precedence metric
+        counts the number of times a job j is preceded by job i
+        in both p and p'. This metric is commutative.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([2, 0, 4, 3, 1])
+        >>> q = Permutation([3, 1, 2, 4, 0])
+        >>> p.get_precedence_distance(q)
+        7
+        >>> q.get_precedence_distance(p)
+        7
+
+        See Also
+        ========
+
+        get_precedence_matrix, get_adjacency_matrix, get_adjacency_distance
+        """
+        if self.size != other.size:
+            raise ValueError("The permutations must be of equal size.")
+        self_prec_mat = self.get_precedence_matrix()
+        other_prec_mat = other.get_precedence_matrix()
+        n_prec = 0
+        for i in range(self.size):
+            for j in range(self.size):
+                if i == j:
+                    continue
+                if self_prec_mat[i, j] * other_prec_mat[i, j] == 1:
+                    n_prec += 1
+        d = self.size * (self.size - 1)//2 - n_prec
+        return d
+
+    def get_adjacency_matrix(self):
+        """
+        Computes the adjacency matrix of a permutation.
+
+        Explanation
+        ===========
+
+        If job i is adjacent to job j in a permutation p
+        then we set m[i, j] = 1 where m is the adjacency
+        matrix of p.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation.josephus(3, 6, 1)
+        >>> p.get_adjacency_matrix()
+        Matrix([
+        [0, 0, 0, 0, 0, 0],
+        [0, 0, 0, 0, 1, 0],
+        [0, 0, 0, 0, 0, 1],
+        [0, 1, 0, 0, 0, 0],
+        [1, 0, 0, 0, 0, 0],
+        [0, 0, 0, 1, 0, 0]])
+        >>> q = Permutation([0, 1, 2, 3])
+        >>> q.get_adjacency_matrix()
+        Matrix([
+        [0, 1, 0, 0],
+        [0, 0, 1, 0],
+        [0, 0, 0, 1],
+        [0, 0, 0, 0]])
+
+        See Also
+        ========
+
+        get_precedence_matrix, get_precedence_distance, get_adjacency_distance
+        """
+        m = zeros(self.size)
+        perm = self.array_form
+        for i in range(self.size - 1):
+            m[perm[i], perm[i + 1]] = 1
+        return m
+
+    def get_adjacency_distance(self, other):
+        """
+        Computes the adjacency distance between two permutations.
+
+        Explanation
+        ===========
+
+        This metric counts the number of times a pair i,j of jobs is
+        adjacent in both p and p'. If n_adj is this quantity then
+        the adjacency distance is n - n_adj - 1 [1]
+
+        [1] Reeves, Colin R. Landscapes, Operators and Heuristic search, Annals
+        of Operational Research, 86, pp 473-490. (1999)
+
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([0, 3, 1, 2, 4])
+        >>> q = Permutation.josephus(4, 5, 2)
+        >>> p.get_adjacency_distance(q)
+        3
+        >>> r = Permutation([0, 2, 1, 4, 3])
+        >>> p.get_adjacency_distance(r)
+        4
+
+        See Also
+        ========
+
+        get_precedence_matrix, get_precedence_distance, get_adjacency_matrix
+        """
+        if self.size != other.size:
+            raise ValueError("The permutations must be of the same size.")
+        self_adj_mat = self.get_adjacency_matrix()
+        other_adj_mat = other.get_adjacency_matrix()
+        n_adj = 0
+        for i in range(self.size):
+            for j in range(self.size):
+                if i == j:
+                    continue
+                if self_adj_mat[i, j] * other_adj_mat[i, j] == 1:
+                    n_adj += 1
+        d = self.size - n_adj - 1
+        return d
+
+    def get_positional_distance(self, other):
+        """
+        Computes the positional distance between two permutations.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> p = Permutation([0, 3, 1, 2, 4])
+        >>> q = Permutation.josephus(4, 5, 2)
+        >>> r = Permutation([3, 1, 4, 0, 2])
+        >>> p.get_positional_distance(q)
+        12
+        >>> p.get_positional_distance(r)
+        12
+
+        See Also
+        ========
+
+        get_precedence_distance, get_adjacency_distance
+        """
+        a = self.array_form
+        b = other.array_form
+        if len(a) != len(b):
+            raise ValueError("The permutations must be of the same size.")
+        return sum(abs(a[i] - b[i]) for i in range(len(a)))
+
+    @classmethod
+    def josephus(cls, m, n, s=1):
+        """Return as a permutation the shuffling of range(n) using the Josephus
+        scheme in which every m-th item is selected until all have been chosen.
+        The returned permutation has elements listed by the order in which they
+        were selected.
+
+        The parameter ``s`` stops the selection process when there are ``s``
+        items remaining and these are selected by continuing the selection,
+        counting by 1 rather than by ``m``.
+
+        Consider selecting every 3rd item from 6 until only 2 remain::
+
+            choices    chosen
+            ========   ======
+              012345
+              01 345   2
+              01 34    25
+              01  4    253
+              0   4    2531
+              0        25314
+                       253140
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> Permutation.josephus(3, 6, 2).array_form
+        [2, 5, 3, 1, 4, 0]
+
+        References
+        ==========
+
+        .. [1] https://en.wikipedia.org/wiki/Flavius_Josephus
+        .. [2] https://en.wikipedia.org/wiki/Josephus_problem
+        .. [3] https://web.archive.org/web/20171008094331/http://www.wou.edu/~burtonl/josephus.html
+
+        """
+        from collections import deque
+        m -= 1
+        Q = deque(list(range(n)))
+        perm = []
+        while len(Q) > max(s, 1):
+            for dp in range(m):
+                Q.append(Q.popleft())
+            perm.append(Q.popleft())
+        perm.extend(list(Q))
+        return cls(perm)
+
+    @classmethod
+    def from_inversion_vector(cls, inversion):
+        """
+        Calculates the permutation from the inversion vector.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> from sympy import init_printing
+        >>> init_printing(perm_cyclic=False, pretty_print=False)
+        >>> Permutation.from_inversion_vector([3, 2, 1, 0, 0])
+        Permutation([3, 2, 1, 0, 4, 5])
+
+        """
+        size = len(inversion)
+        N = list(range(size + 1))
+        perm = []
+        try:
+            for k in range(size):
+                val = N[inversion[k]]
+                perm.append(val)
+                N.remove(val)
+        except IndexError:
+            raise ValueError("The inversion vector is not valid.")
+        perm.extend(N)
+        return cls._af_new(perm)
+
+    @classmethod
+    def random(cls, n):
+        """
+        Generates a random permutation of length ``n``.
+
+        Uses the underlying Python pseudo-random number generator.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> Permutation.random(2) in (Permutation([1, 0]), Permutation([0, 1]))
+        True
+
+        """
+        perm_array = list(range(n))
+        random.shuffle(perm_array)
+        return cls._af_new(perm_array)
+
+    @classmethod
+    def unrank_lex(cls, size, rank):
+        """
+        Lexicographic permutation unranking.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+        >>> from sympy import init_printing
+        >>> init_printing(perm_cyclic=False, pretty_print=False)
+        >>> a = Permutation.unrank_lex(5, 10)
+        >>> a.rank()
+        10
+        >>> a
+        Permutation([0, 2, 4, 1, 3])
+
+        See Also
+        ========
+
+        rank, next_lex
+        """
+        perm_array = [0] * size
+        psize = 1
+        for i in range(size):
+            new_psize = psize*(i + 1)
+            d = (rank % new_psize) // psize
+            rank -= d*psize
+            perm_array[size - i - 1] = d
+            for j in range(size - i, size):
+                if perm_array[j] > d - 1:
+                    perm_array[j] += 1
+            psize = new_psize
+        return cls._af_new(perm_array)
+
+    def resize(self, n):
+        """Resize the permutation to the new size ``n``.
+
+        Parameters
+        ==========
+
+        n : int
+            The new size of the permutation.
+
+        Raises
+        ======
+
+        ValueError
+            If the permutation cannot be resized to the given size.
+            This may only happen when resized to a smaller size than
+            the original.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Permutation
+
+        Increasing the size of a permutation:
+
+        >>> p = Permutation(0, 1, 2)
+        >>> p = p.resize(5)
+        >>> p
+        (4)(0 1 2)
+
+        Decreasing the size of the permutation:
+
+        >>> p = p.resize(4)
+        >>> p
+        (3)(0 1 2)
+
+        If resizing to the specific size breaks the cycles:
+
+        >>> p.resize(2)
+        Traceback (most recent call last):
+        ...
+        ValueError: The permutation cannot be resized to 2 because the
+        cycle (0, 1, 2) may break.
+        """
+        aform = self.array_form
+        l = len(aform)
+        if n > l:
+            aform += list(range(l, n))
+            return Permutation._af_new(aform)
+
+        elif n < l:
+            cyclic_form = self.full_cyclic_form
+            new_cyclic_form = []
+            for cycle in cyclic_form:
+                cycle_min = min(cycle)
+                cycle_max = max(cycle)
+                if cycle_min <= n-1:
+                    if cycle_max > n-1:
+                        raise ValueError(
+                            "The permutation cannot be resized to {} "
+                            "because the cycle {} may break."
+                            .format(n, tuple(cycle)))
+
+                    new_cyclic_form.append(cycle)
+            return Permutation(new_cyclic_form)
+
+        return self
+
+    # XXX Deprecated flag
+    print_cyclic = None
+
+
+def _merge(arr, temp, left, mid, right):
+    """
+    Merges two sorted arrays and calculates the inversion count.
+
+    Helper function for calculating inversions. This method is
+    for internal use only.
+    """
+    i = k = left
+    j = mid
+    inv_count = 0
+    while i < mid and j <= right:
+        if arr[i] < arr[j]:
+            temp[k] = arr[i]
+            k += 1
+            i += 1
+        else:
+            temp[k] = arr[j]
+            k += 1
+            j += 1
+            inv_count += (mid -i)
+    while i < mid:
+        temp[k] = arr[i]
+        k += 1
+        i += 1
+    if j <= right:
+        k += right - j + 1
+        j += right - j + 1
+        arr[left:k + 1] = temp[left:k + 1]
+    else:
+        arr[left:right + 1] = temp[left:right + 1]
+    return inv_count
+
+Perm = Permutation
+_af_new = Perm._af_new
+
+
+class AppliedPermutation(Expr):
+    """A permutation applied to a symbolic variable.
+
+    Parameters
+    ==========
+
+    perm : Permutation
+    x : Expr
+
+    Examples
+    ========
+
+    >>> from sympy import Symbol
+    >>> from sympy.combinatorics import Permutation
+
+    Creating a symbolic permutation function application:
+
+    >>> x = Symbol('x')
+    >>> p = Permutation(0, 1, 2)
+    >>> p.apply(x)
+    AppliedPermutation((0 1 2), x)
+    >>> _.subs(x, 1)
+    2
+    """
+    def __new__(cls, perm, x, evaluate=None):
+        if evaluate is None:
+            evaluate = global_parameters.evaluate
+
+        perm = _sympify(perm)
+        x = _sympify(x)
+
+        if not isinstance(perm, Permutation):
+            raise ValueError("{} must be a Permutation instance."
+                .format(perm))
+
+        if evaluate:
+            if x.is_Integer:
+                return perm.apply(x)
+
+        obj = super().__new__(cls, perm, x)
+        return obj
+
+
+@dispatch(Permutation, Permutation)
+def _eval_is_eq(lhs, rhs):
+    if lhs._size != rhs._size:
+        return None
+    return lhs._array_form == rhs._array_form

lib/python3.12/site-packages/sympy/combinatorics/polyhedron.py

@@ -0,0 +1,1019 @@
+from sympy.combinatorics import Permutation as Perm
+from sympy.combinatorics.perm_groups import PermutationGroup
+from sympy.core import Basic, Tuple, default_sort_key
+from sympy.sets import FiniteSet
+from sympy.utilities.iterables import (minlex, unflatten, flatten)
+from sympy.utilities.misc import as_int
+
+rmul = Perm.rmul
+
+
+class Polyhedron(Basic):
+    """
+    Represents the polyhedral symmetry group (PSG).
+
+    Explanation
+    ===========
+
+    The PSG is one of the symmetry groups of the Platonic solids.
+    There are three polyhedral groups: the tetrahedral group
+    of order 12, the octahedral group of order 24, and the
+    icosahedral group of order 60.
+
+    All doctests have been given in the docstring of the
+    constructor of the object.
+
+    References
+    ==========
+
+    .. [1] https://mathworld.wolfram.com/PolyhedralGroup.html
+
+    """
+    _edges = None
+
+    def __new__(cls, corners, faces=(), pgroup=()):
+        """
+        The constructor of the Polyhedron group object.
+
+        Explanation
+        ===========
+
+        It takes up to three parameters: the corners, faces, and
+        allowed transformations.
+
+        The corners/vertices are entered as a list of arbitrary
+        expressions that are used to identify each vertex.
+
+        The faces are entered as a list of tuples of indices; a tuple
+        of indices identifies the vertices which define the face. They
+        should be entered in a cw or ccw order; they will be standardized
+        by reversal and rotation to be give the lowest lexical ordering.
+        If no faces are given then no edges will be computed.
+
+            >>> from sympy.combinatorics.polyhedron import Polyhedron
+            >>> Polyhedron(list('abc'), [(1, 2, 0)]).faces
+            {(0, 1, 2)}
+            >>> Polyhedron(list('abc'), [(1, 0, 2)]).faces
+            {(0, 1, 2)}
+
+        The allowed transformations are entered as allowable permutations
+        of the vertices for the polyhedron. Instance of Permutations
+        (as with faces) should refer to the supplied vertices by index.
+        These permutation are stored as a PermutationGroup.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.permutations import Permutation
+        >>> from sympy import init_printing
+        >>> from sympy.abc import w, x, y, z
+        >>> init_printing(pretty_print=False, perm_cyclic=False)
+
+        Here we construct the Polyhedron object for a tetrahedron.
+
+        >>> corners = [w, x, y, z]
+        >>> faces = [(0, 1, 2), (0, 2, 3), (0, 3, 1), (1, 2, 3)]
+
+        Next, allowed transformations of the polyhedron must be given. This
+        is given as permutations of vertices.
+
+        Although the vertices of a tetrahedron can be numbered in 24 (4!)
+        different ways, there are only 12 different orientations for a
+        physical tetrahedron. The following permutations, applied once or
+        twice, will generate all 12 of the orientations. (The identity
+        permutation, Permutation(range(4)), is not included since it does
+        not change the orientation of the vertices.)
+
+        >>> pgroup = [Permutation([[0, 1, 2], [3]]), \
+                      Permutation([[0, 1, 3], [2]]), \
+                      Permutation([[0, 2, 3], [1]]), \
+                      Permutation([[1, 2, 3], [0]]), \
+                      Permutation([[0, 1], [2, 3]]), \
+                      Permutation([[0, 2], [1, 3]]), \
+                      Permutation([[0, 3], [1, 2]])]
+
+        The Polyhedron is now constructed and demonstrated:
+
+        >>> tetra = Polyhedron(corners, faces, pgroup)
+        >>> tetra.size
+        4
+        >>> tetra.edges
+        {(0, 1), (0, 2), (0, 3), (1, 2), (1, 3), (2, 3)}
+        >>> tetra.corners
+        (w, x, y, z)
+
+        It can be rotated with an arbitrary permutation of vertices, e.g.
+        the following permutation is not in the pgroup:
+
+        >>> tetra.rotate(Permutation([0, 1, 3, 2]))
+        >>> tetra.corners
+        (w, x, z, y)
+
+        An allowed permutation of the vertices can be constructed by
+        repeatedly applying permutations from the pgroup to the vertices.
+        Here is a demonstration that applying p and p**2 for every p in
+        pgroup generates all the orientations of a tetrahedron and no others:
+
+        >>> all = ( (w, x, y, z), \
+                    (x, y, w, z), \
+                    (y, w, x, z), \
+                    (w, z, x, y), \
+                    (z, w, y, x), \
+                    (w, y, z, x), \
+                    (y, z, w, x), \
+                    (x, z, y, w), \
+                    (z, y, x, w), \
+                    (y, x, z, w), \
+                    (x, w, z, y), \
+                    (z, x, w, y) )
+
+        >>> got = []
+        >>> for p in (pgroup + [p**2 for p in pgroup]):
+        ...     h = Polyhedron(corners)
+        ...     h.rotate(p)
+        ...     got.append(h.corners)
+        ...
+        >>> set(got) == set(all)
+        True
+
+        The make_perm method of a PermutationGroup will randomly pick
+        permutations, multiply them together, and return the permutation that
+        can be applied to the polyhedron to give the orientation produced
+        by those individual permutations.
+
+        Here, 3 permutations are used:
+
+        >>> tetra.pgroup.make_perm(3) # doctest: +SKIP
+        Permutation([0, 3, 1, 2])
+
+        To select the permutations that should be used, supply a list
+        of indices to the permutations in pgroup in the order they should
+        be applied:
+
+        >>> use = [0, 0, 2]
+        >>> p002 = tetra.pgroup.make_perm(3, use)
+        >>> p002
+        Permutation([1, 0, 3, 2])
+
+
+        Apply them one at a time:
+
+        >>> tetra.reset()
+        >>> for i in use:
+        ...     tetra.rotate(pgroup[i])
+        ...
+        >>> tetra.vertices
+        (x, w, z, y)
+        >>> sequentially = tetra.vertices
+
+        Apply the composite permutation:
+
+        >>> tetra.reset()
+        >>> tetra.rotate(p002)
+        >>> tetra.corners
+        (x, w, z, y)
+        >>> tetra.corners in all and tetra.corners == sequentially
+        True
+
+        Notes
+        =====
+
+        Defining permutation groups
+        ---------------------------
+
+        It is not necessary to enter any permutations, nor is necessary to
+        enter a complete set of transformations. In fact, for a polyhedron,
+        all configurations can be constructed from just two permutations.
+        For example, the orientations of a tetrahedron can be generated from
+        an axis passing through a vertex and face and another axis passing
+        through a different vertex or from an axis passing through the
+        midpoints of two edges opposite of each other.
+
+        For simplicity of presentation, consider a square --
+        not a cube -- with vertices 1, 2, 3, and 4:
+
+        1-----2  We could think of axes of rotation being:
+        |     |  1) through the face
+        |     |  2) from midpoint 1-2 to 3-4 or 1-3 to 2-4
+        3-----4  3) lines 1-4 or 2-3
+
+
+        To determine how to write the permutations, imagine 4 cameras,
+        one at each corner, labeled A-D:
+
+        A       B          A       B
+         1-----2            1-----3             vertex index:
+         |     |            |     |                 1   0
+         |     |            |     |                 2   1
+         3-----4            2-----4                 3   2
+        C       D          C       D                4   3
+
+        original           after rotation
+                           along 1-4
+
+        A diagonal and a face axis will be chosen for the "permutation group"
+        from which any orientation can be constructed.
+
+        >>> pgroup = []
+
+        Imagine a clockwise rotation when viewing 1-4 from camera A. The new
+        orientation is (in camera-order): 1, 3, 2, 4 so the permutation is
+        given using the *indices* of the vertices as:
+
+        >>> pgroup.append(Permutation((0, 2, 1, 3)))
+
+        Now imagine rotating clockwise when looking down an axis entering the
+        center of the square as viewed. The new camera-order would be
+        3, 1, 4, 2 so the permutation is (using indices):
+
+        >>> pgroup.append(Permutation((2, 0, 3, 1)))
+
+        The square can now be constructed:
+            ** use real-world labels for the vertices, entering them in
+               camera order
+            ** for the faces we use zero-based indices of the vertices
+               in *edge-order* as the face is traversed; neither the
+               direction nor the starting point matter -- the faces are
+               only used to define edges (if so desired).
+
+        >>> square = Polyhedron((1, 2, 3, 4), [(0, 1, 3, 2)], pgroup)
+
+        To rotate the square with a single permutation we can do:
+
+        >>> square.rotate(square.pgroup[0])
+        >>> square.corners
+        (1, 3, 2, 4)
+
+        To use more than one permutation (or to use one permutation more
+        than once) it is more convenient to use the make_perm method:
+
+        >>> p011 = square.pgroup.make_perm([0, 1, 1]) # diag flip + 2 rotations
+        >>> square.reset() # return to initial orientation
+        >>> square.rotate(p011)
+        >>> square.corners
+        (4, 2, 3, 1)
+
+        Thinking outside the box
+        ------------------------
+
+        Although the Polyhedron object has a direct physical meaning, it
+        actually has broader application. In the most general sense it is
+        just a decorated PermutationGroup, allowing one to connect the
+        permutations to something physical. For example, a Rubik's cube is
+        not a proper polyhedron, but the Polyhedron class can be used to
+        represent it in a way that helps to visualize the Rubik's cube.
+
+        >>> from sympy import flatten, unflatten, symbols
+        >>> from sympy.combinatorics import RubikGroup
+        >>> facelets = flatten([symbols(s+'1:5') for s in 'UFRBLD'])
+        >>> def show():
+        ...     pairs = unflatten(r2.corners, 2)
+        ...     print(pairs[::2])
+        ...     print(pairs[1::2])
+        ...
+        >>> r2 = Polyhedron(facelets, pgroup=RubikGroup(2))
+        >>> show()
+        [(U1, U2), (F1, F2), (R1, R2), (B1, B2), (L1, L2), (D1, D2)]
+        [(U3, U4), (F3, F4), (R3, R4), (B3, B4), (L3, L4), (D3, D4)]
+        >>> r2.rotate(0) # cw rotation of F
+        >>> show()
+        [(U1, U2), (F3, F1), (U3, R2), (B1, B2), (L1, D1), (R3, R1)]
+        [(L4, L2), (F4, F2), (U4, R4), (B3, B4), (L3, D2), (D3, D4)]
+
+        Predefined Polyhedra
+        ====================
+
+        For convenience, the vertices and faces are defined for the following
+        standard solids along with a permutation group for transformations.
+        When the polyhedron is oriented as indicated below, the vertices in
+        a given horizontal plane are numbered in ccw direction, starting from
+        the vertex that will give the lowest indices in a given face. (In the
+        net of the vertices, indices preceded by "-" indicate replication of
+        the lhs index in the net.)
+
+        tetrahedron, tetrahedron_faces
+        ------------------------------
+
+            4 vertices (vertex up) net:
+
+                 0 0-0
+                1 2 3-1
+
+            4 faces:
+
+            (0, 1, 2) (0, 2, 3) (0, 3, 1) (1, 2, 3)
+
+        cube, cube_faces
+        ----------------
+
+            8 vertices (face up) net:
+
+                0 1 2 3-0
+                4 5 6 7-4
+
+            6 faces:
+
+            (0, 1, 2, 3)
+            (0, 1, 5, 4) (1, 2, 6, 5) (2, 3, 7, 6) (0, 3, 7, 4)
+            (4, 5, 6, 7)
+
+        octahedron, octahedron_faces
+        ----------------------------
+
+            6 vertices (vertex up) net:
+
+                 0 0 0-0
+                1 2 3 4-1
+                 5 5 5-5
+
+            8 faces:
+
+            (0, 1, 2) (0, 2, 3) (0, 3, 4) (0, 1, 4)
+            (1, 2, 5) (2, 3, 5) (3, 4, 5) (1, 4, 5)
+
+        dodecahedron, dodecahedron_faces
+        --------------------------------
+
+            20 vertices (vertex up) net:
+
+                  0  1  2  3  4 -0
+                  5  6  7  8  9 -5
+                14 10 11 12 13-14
+                15 16 17 18 19-15
+
+            12 faces:
+
+            (0, 1, 2, 3, 4) (0, 1, 6, 10, 5) (1, 2, 7, 11, 6)
+            (2, 3, 8, 12, 7) (3, 4, 9, 13, 8) (0, 4, 9, 14, 5)
+            (5, 10, 16, 15, 14) (6, 10, 16, 17, 11) (7, 11, 17, 18, 12)
+            (8, 12, 18, 19, 13) (9, 13, 19, 15, 14)(15, 16, 17, 18, 19)
+
+        icosahedron, icosahedron_faces
+        ------------------------------
+
+            12 vertices (face up) net:
+
+                 0  0  0  0 -0
+                1  2  3  4  5 -1
+                 6  7  8  9  10 -6
+                  11 11 11 11 -11
+
+            20 faces:
+
+            (0, 1, 2) (0, 2, 3) (0, 3, 4)
+            (0, 4, 5) (0, 1, 5) (1, 2, 6)
+            (2, 3, 7) (3, 4, 8) (4, 5, 9)
+            (1, 5, 10) (2, 6, 7) (3, 7, 8)
+            (4, 8, 9) (5, 9, 10) (1, 6, 10)
+            (6, 7, 11) (7, 8, 11) (8, 9, 11)
+            (9, 10, 11) (6, 10, 11)
+
+        >>> from sympy.combinatorics.polyhedron import cube
+        >>> cube.edges
+        {(0, 1), (0, 3), (0, 4), (1, 2), (1, 5), (2, 3), (2, 6), (3, 7), (4, 5), (4, 7), (5, 6), (6, 7)}
+
+        If you want to use letters or other names for the corners you
+        can still use the pre-calculated faces:
+
+        >>> corners = list('abcdefgh')
+        >>> Polyhedron(corners, cube.faces).corners
+        (a, b, c, d, e, f, g, h)
+
+        References
+        ==========
+
+        .. [1] www.ocf.berkeley.edu/~wwu/articles/platonicsolids.pdf
+
+        """
+        faces = [minlex(f, directed=False, key=default_sort_key) for f in faces]
+        corners, faces, pgroup = args = \
+            [Tuple(*a) for a in (corners, faces, pgroup)]
+        obj = Basic.__new__(cls, *args)
+        obj._corners = tuple(corners)  # in order given
+        obj._faces = FiniteSet(*faces)
+        if pgroup and pgroup[0].size != len(corners):
+            raise ValueError("Permutation size unequal to number of corners.")
+        # use the identity permutation if none are given
+        obj._pgroup = PermutationGroup(
+            pgroup or [Perm(range(len(corners)))] )
+        return obj
+
+    @property
+    def corners(self):
+        """
+        Get the corners of the Polyhedron.
+
+        The method ``vertices`` is an alias for ``corners``.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Polyhedron
+        >>> from sympy.abc import a, b, c, d
+        >>> p = Polyhedron(list('abcd'))
+        >>> p.corners == p.vertices == (a, b, c, d)
+        True
+
+        See Also
+        ========
+
+        array_form, cyclic_form
+        """
+        return self._corners
+    vertices = corners
+
+    @property
+    def array_form(self):
+        """Return the indices of the corners.
+
+        The indices are given relative to the original position of corners.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.polyhedron import tetrahedron
+        >>> tetrahedron = tetrahedron.copy()
+        >>> tetrahedron.array_form
+        [0, 1, 2, 3]
+
+        >>> tetrahedron.rotate(0)
+        >>> tetrahedron.array_form
+        [0, 2, 3, 1]
+        >>> tetrahedron.pgroup[0].array_form
+        [0, 2, 3, 1]
+
+        See Also
+        ========
+
+        corners, cyclic_form
+        """
+        corners = list(self.args[0])
+        return [corners.index(c) for c in self.corners]
+
+    @property
+    def cyclic_form(self):
+        """Return the indices of the corners in cyclic notation.
+
+        The indices are given relative to the original position of corners.
+
+        See Also
+        ========
+
+        corners, array_form
+        """
+        return Perm._af_new(self.array_form).cyclic_form
+
+    @property
+    def size(self):
+        """
+        Get the number of corners of the Polyhedron.
+        """
+        return len(self._corners)
+
+    @property
+    def faces(self):
+        """
+        Get the faces of the Polyhedron.
+        """
+        return self._faces
+
+    @property
+    def pgroup(self):
+        """
+        Get the permutations of the Polyhedron.
+        """
+        return self._pgroup
+
+    @property
+    def edges(self):
+        """
+        Given the faces of the polyhedra we can get the edges.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Polyhedron
+        >>> from sympy.abc import a, b, c
+        >>> corners = (a, b, c)
+        >>> faces = [(0, 1, 2)]
+        >>> Polyhedron(corners, faces).edges
+        {(0, 1), (0, 2), (1, 2)}
+
+        """
+        if self._edges is None:
+            output = set()
+            for face in self.faces:
+                for i in range(len(face)):
+                    edge = tuple(sorted([face[i], face[i - 1]]))
+                    output.add(edge)
+            self._edges = FiniteSet(*output)
+        return self._edges
+
+    def rotate(self, perm):
+        """
+        Apply a permutation to the polyhedron *in place*. The permutation
+        may be given as a Permutation instance or an integer indicating
+        which permutation from pgroup of the Polyhedron should be
+        applied.
+
+        This is an operation that is analogous to rotation about
+        an axis by a fixed increment.
+
+        Notes
+        =====
+
+        When a Permutation is applied, no check is done to see if that
+        is a valid permutation for the Polyhedron. For example, a cube
+        could be given a permutation which effectively swaps only 2
+        vertices. A valid permutation (that rotates the object in a
+        physical way) will be obtained if one only uses
+        permutations from the ``pgroup`` of the Polyhedron. On the other
+        hand, allowing arbitrary rotations (applications of permutations)
+        gives a way to follow named elements rather than indices since
+        Polyhedron allows vertices to be named while Permutation works
+        only with indices.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Polyhedron, Permutation
+        >>> from sympy.combinatorics.polyhedron import cube
+        >>> cube = cube.copy()
+        >>> cube.corners
+        (0, 1, 2, 3, 4, 5, 6, 7)
+        >>> cube.rotate(0)
+        >>> cube.corners
+        (1, 2, 3, 0, 5, 6, 7, 4)
+
+        A non-physical "rotation" that is not prohibited by this method:
+
+        >>> cube.reset()
+        >>> cube.rotate(Permutation([[1, 2]], size=8))
+        >>> cube.corners
+        (0, 2, 1, 3, 4, 5, 6, 7)
+
+        Polyhedron can be used to follow elements of set that are
+        identified by letters instead of integers:
+
+        >>> shadow = h5 = Polyhedron(list('abcde'))
+        >>> p = Permutation([3, 0, 1, 2, 4])
+        >>> h5.rotate(p)
+        >>> h5.corners
+        (d, a, b, c, e)
+        >>> _ == shadow.corners
+        True
+        >>> copy = h5.copy()
+        >>> h5.rotate(p)
+        >>> h5.corners == copy.corners
+        False
+        """
+        if not isinstance(perm, Perm):
+            perm = self.pgroup[perm]
+            # and we know it's valid
+        else:
+            if perm.size != self.size:
+                raise ValueError('Polyhedron and Permutation sizes differ.')
+        a = perm.array_form
+        corners = [self.corners[a[i]] for i in range(len(self.corners))]
+        self._corners = tuple(corners)
+
+    def reset(self):
+        """Return corners to their original positions.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.polyhedron import tetrahedron as T
+        >>> T = T.copy()
+        >>> T.corners
+        (0, 1, 2, 3)
+        >>> T.rotate(0)
+        >>> T.corners
+        (0, 2, 3, 1)
+        >>> T.reset()
+        >>> T.corners
+        (0, 1, 2, 3)
+        """
+        self._corners = self.args[0]
+
+
+def _pgroup_calcs():
+    """Return the permutation groups for each of the polyhedra and the face
+    definitions: tetrahedron, cube, octahedron, dodecahedron, icosahedron,
+    tetrahedron_faces, cube_faces, octahedron_faces, dodecahedron_faces,
+    icosahedron_faces
+
+    Explanation
+    ===========
+
+    (This author did not find and did not know of a better way to do it though
+    there likely is such a way.)
+
+    Although only 2 permutations are needed for a polyhedron in order to
+    generate all the possible orientations, a group of permutations is
+    provided instead. A set of permutations is called a "group" if::
+
+    a*b = c (for any pair of permutations in the group, a and b, their
+    product, c, is in the group)
+
+    a*(b*c) = (a*b)*c (for any 3 permutations in the group associativity holds)
+
+    there is an identity permutation, I, such that I*a = a*I for all elements
+    in the group
+
+    a*b = I (the inverse of each permutation is also in the group)
+
+    None of the polyhedron groups defined follow these definitions of a group.
+    Instead, they are selected to contain those permutations whose powers
+    alone will construct all orientations of the polyhedron, i.e. for
+    permutations ``a``, ``b``, etc... in the group, ``a, a**2, ..., a**o_a``,
+    ``b, b**2, ..., b**o_b``, etc... (where ``o_i`` is the order of
+    permutation ``i``) generate all permutations of the polyhedron instead of
+    mixed products like ``a*b``, ``a*b**2``, etc....
+
+    Note that for a polyhedron with n vertices, the valid permutations of the
+    vertices exclude those that do not maintain its faces. e.g. the
+    permutation BCDE of a square's four corners, ABCD, is a valid
+    permutation while CBDE is not (because this would twist the square).
+
+    Examples
+    ========
+
+    The is_group checks for: closure, the presence of the Identity permutation,
+    and the presence of the inverse for each of the elements in the group. This
+    confirms that none of the polyhedra are true groups:
+
+    >>> from sympy.combinatorics.polyhedron import (
+    ... tetrahedron, cube, octahedron, dodecahedron, icosahedron)
+    ...
+    >>> polyhedra = (tetrahedron, cube, octahedron, dodecahedron, icosahedron)
+    >>> [h.pgroup.is_group for h in polyhedra]
+    ...
+    [True, True, True, True, True]
+
+    Although tests in polyhedron's test suite check that powers of the
+    permutations in the groups generate all permutations of the vertices
+    of the polyhedron, here we also demonstrate the powers of the given
+    permutations create a complete group for the tetrahedron:
+
+    >>> from sympy.combinatorics import Permutation, PermutationGroup
+    >>> for h in polyhedra[:1]:
+    ...     G = h.pgroup
+    ...     perms = set()
+    ...     for g in G:
+    ...         for e in range(g.order()):
+    ...             p = tuple((g**e).array_form)
+    ...             perms.add(p)
+    ...
+    ...     perms = [Permutation(p) for p in perms]
+    ...     assert PermutationGroup(perms).is_group
+
+    In addition to doing the above, the tests in the suite confirm that the
+    faces are all present after the application of each permutation.
+
+    References
+    ==========
+
+    .. [1] https://dogschool.tripod.com/trianglegroup.html
+
+    """
+    def _pgroup_of_double(polyh, ordered_faces, pgroup):
+        n = len(ordered_faces[0])
+        # the vertices of the double which sits inside a give polyhedron
+        # can be found by tracking the faces of the outer polyhedron.
+        # A map between face and the vertex of the double is made so that
+        # after rotation the position of the vertices can be located
+        fmap = dict(zip(ordered_faces,
+                        range(len(ordered_faces))))
+        flat_faces = flatten(ordered_faces)
+        new_pgroup = []
+        for p in pgroup:
+            h = polyh.copy()
+            h.rotate(p)
+            c = h.corners
+            # reorder corners in the order they should appear when
+            # enumerating the faces
+            reorder = unflatten([c[j] for j in flat_faces], n)
+            # make them canonical
+            reorder = [tuple(map(as_int,
+                       minlex(f, directed=False)))
+                       for f in reorder]
+            # map face to vertex: the resulting list of vertices are the
+            # permutation that we seek for the double
+            new_pgroup.append(Perm([fmap[f] for f in reorder]))
+        return new_pgroup
+
+    tetrahedron_faces = [
+        (0, 1, 2), (0, 2, 3), (0, 3, 1),  # upper 3
+        (1, 2, 3),  # bottom
+    ]
+
+    # cw from top
+    #
+    _t_pgroup = [
+        Perm([[1, 2, 3], [0]]),  # cw from top
+        Perm([[0, 1, 2], [3]]),  # cw from front face
+        Perm([[0, 3, 2], [1]]),  # cw from back right face
+        Perm([[0, 3, 1], [2]]),  # cw from back left face
+        Perm([[0, 1], [2, 3]]),  # through front left edge
+        Perm([[0, 2], [1, 3]]),  # through front right edge
+        Perm([[0, 3], [1, 2]]),  # through back edge
+    ]
+
+    tetrahedron = Polyhedron(
+        range(4),
+        tetrahedron_faces,
+        _t_pgroup)
+
+    cube_faces = [
+        (0, 1, 2, 3),  # upper
+        (0, 1, 5, 4), (1, 2, 6, 5), (2, 3, 7, 6), (0, 3, 7, 4),  # middle 4
+        (4, 5, 6, 7),  # lower
+    ]
+
+    # U, D, F, B, L, R = up, down, front, back, left, right
+    _c_pgroup = [Perm(p) for p in
+        [
+        [1, 2, 3, 0, 5, 6, 7, 4],  # cw from top, U
+        [4, 0, 3, 7, 5, 1, 2, 6],  # cw from F face
+        [4, 5, 1, 0, 7, 6, 2, 3],  # cw from R face
+
+        [1, 0, 4, 5, 2, 3, 7, 6],  # cw through UF edge
+        [6, 2, 1, 5, 7, 3, 0, 4],  # cw through UR edge
+        [6, 7, 3, 2, 5, 4, 0, 1],  # cw through UB edge
+        [3, 7, 4, 0, 2, 6, 5, 1],  # cw through UL edge
+        [4, 7, 6, 5, 0, 3, 2, 1],  # cw through FL edge
+        [6, 5, 4, 7, 2, 1, 0, 3],  # cw through FR edge
+
+        [0, 3, 7, 4, 1, 2, 6, 5],  # cw through UFL vertex
+        [5, 1, 0, 4, 6, 2, 3, 7],  # cw through UFR vertex
+        [5, 6, 2, 1, 4, 7, 3, 0],  # cw through UBR vertex
+        [7, 4, 0, 3, 6, 5, 1, 2],  # cw through UBL
+        ]]
+
+    cube = Polyhedron(
+        range(8),
+        cube_faces,
+        _c_pgroup)
+
+    octahedron_faces = [
+        (0, 1, 2), (0, 2, 3), (0, 3, 4), (0, 1, 4),  # top 4
+        (1, 2, 5), (2, 3, 5), (3, 4, 5), (1, 4, 5),  # bottom 4
+    ]
+
+    octahedron = Polyhedron(
+        range(6),
+        octahedron_faces,
+        _pgroup_of_double(cube, cube_faces, _c_pgroup))
+
+    dodecahedron_faces = [
+        (0, 1, 2, 3, 4),  # top
+        (0, 1, 6, 10, 5), (1, 2, 7, 11, 6), (2, 3, 8, 12, 7),  # upper 5
+        (3, 4, 9, 13, 8), (0, 4, 9, 14, 5),
+        (5, 10, 16, 15, 14), (6, 10, 16, 17, 11), (7, 11, 17, 18,
+          12),  # lower 5
+        (8, 12, 18, 19, 13), (9, 13, 19, 15, 14),
+        (15, 16, 17, 18, 19)  # bottom
+    ]
+
+    def _string_to_perm(s):
+        rv = [Perm(range(20))]
+        p = None
+        for si in s:
+            if si not in '01':
+                count = int(si) - 1
+            else:
+                count = 1
+                if si == '0':
+                    p = _f0
+                elif si == '1':
+                    p = _f1
+            rv.extend([p]*count)
+        return Perm.rmul(*rv)
+
+    # top face cw
+    _f0 = Perm([
+        1, 2, 3, 4, 0, 6, 7, 8, 9, 5, 11,
+        12, 13, 14, 10, 16, 17, 18, 19, 15])
+    # front face cw
+    _f1 = Perm([
+        5, 0, 4, 9, 14, 10, 1, 3, 13, 15,
+        6, 2, 8, 19, 16, 17, 11, 7, 12, 18])
+    # the strings below, like 0104 are shorthand for F0*F1*F0**4 and are
+    # the remaining 4 face rotations, 15 edge permutations, and the
+    # 10 vertex rotations.
+    _dodeca_pgroup = [_f0, _f1] + [_string_to_perm(s) for s in '''
+    0104 140 014 0410
+    010 1403 03104 04103 102
+    120 1304 01303 021302 03130
+    0412041 041204103 04120410 041204104 041204102
+    10 01 1402 0140 04102 0412 1204 1302 0130 03120'''.strip().split()]
+
+    dodecahedron = Polyhedron(
+        range(20),
+        dodecahedron_faces,
+        _dodeca_pgroup)
+
+    icosahedron_faces = [
+        (0, 1, 2), (0, 2, 3), (0, 3, 4), (0, 4, 5), (0, 1, 5),
+        (1, 6, 7), (1, 2, 7), (2, 7, 8), (2, 3, 8), (3, 8, 9),
+        (3, 4, 9), (4, 9, 10), (4, 5, 10), (5, 6, 10), (1, 5, 6),
+        (6, 7, 11), (7, 8, 11), (8, 9, 11), (9, 10, 11), (6, 10, 11)]
+
+    icosahedron = Polyhedron(
+        range(12),
+        icosahedron_faces,
+        _pgroup_of_double(
+            dodecahedron, dodecahedron_faces, _dodeca_pgroup))
+
+    return (tetrahedron, cube, octahedron, dodecahedron, icosahedron,
+        tetrahedron_faces, cube_faces, octahedron_faces,
+        dodecahedron_faces, icosahedron_faces)
+
+# -----------------------------------------------------------------------
+#   Standard Polyhedron groups
+#
+#   These are generated using _pgroup_calcs() above. However to save
+#   import time we encode them explicitly here.
+# -----------------------------------------------------------------------
+
+tetrahedron = Polyhedron(
+    Tuple(0, 1, 2, 3),
+    Tuple(
+        Tuple(0, 1, 2),
+        Tuple(0, 2, 3),
+        Tuple(0, 1, 3),
+        Tuple(1, 2, 3)),
+    Tuple(
+        Perm(1, 2, 3),
+        Perm(3)(0, 1, 2),
+        Perm(0, 3, 2),
+        Perm(0, 3, 1),
+        Perm(0, 1)(2, 3),
+        Perm(0, 2)(1, 3),
+        Perm(0, 3)(1, 2)
+    ))
+
+cube = Polyhedron(
+    Tuple(0, 1, 2, 3, 4, 5, 6, 7),
+    Tuple(
+        Tuple(0, 1, 2, 3),
+        Tuple(0, 1, 5, 4),
+        Tuple(1, 2, 6, 5),
+        Tuple(2, 3, 7, 6),
+        Tuple(0, 3, 7, 4),
+        Tuple(4, 5, 6, 7)),
+    Tuple(
+        Perm(0, 1, 2, 3)(4, 5, 6, 7),
+        Perm(0, 4, 5, 1)(2, 3, 7, 6),
+        Perm(0, 4, 7, 3)(1, 5, 6, 2),
+        Perm(0, 1)(2, 4)(3, 5)(6, 7),
+        Perm(0, 6)(1, 2)(3, 5)(4, 7),
+        Perm(0, 6)(1, 7)(2, 3)(4, 5),
+        Perm(0, 3)(1, 7)(2, 4)(5, 6),
+        Perm(0, 4)(1, 7)(2, 6)(3, 5),
+        Perm(0, 6)(1, 5)(2, 4)(3, 7),
+        Perm(1, 3, 4)(2, 7, 5),
+        Perm(7)(0, 5, 2)(3, 4, 6),
+        Perm(0, 5, 7)(1, 6, 3),
+        Perm(0, 7, 2)(1, 4, 6)))
+
+octahedron = Polyhedron(
+    Tuple(0, 1, 2, 3, 4, 5),
+    Tuple(
+        Tuple(0, 1, 2),
+        Tuple(0, 2, 3),
+        Tuple(0, 3, 4),
+        Tuple(0, 1, 4),
+        Tuple(1, 2, 5),
+        Tuple(2, 3, 5),
+        Tuple(3, 4, 5),
+        Tuple(1, 4, 5)),
+    Tuple(
+        Perm(5)(1, 2, 3, 4),
+        Perm(0, 4, 5, 2),
+        Perm(0, 1, 5, 3),
+        Perm(0, 1)(2, 4)(3, 5),
+        Perm(0, 2)(1, 3)(4, 5),
+        Perm(0, 3)(1, 5)(2, 4),
+        Perm(0, 4)(1, 3)(2, 5),
+        Perm(0, 5)(1, 4)(2, 3),
+        Perm(0, 5)(1, 2)(3, 4),
+        Perm(0, 4, 1)(2, 3, 5),
+        Perm(0, 1, 2)(3, 4, 5),
+        Perm(0, 2, 3)(1, 5, 4),
+        Perm(0, 4, 3)(1, 5, 2)))
+
+dodecahedron = Polyhedron(
+    Tuple(0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19),
+    Tuple(
+        Tuple(0, 1, 2, 3, 4),
+        Tuple(0, 1, 6, 10, 5),
+        Tuple(1, 2, 7, 11, 6),
+        Tuple(2, 3, 8, 12, 7),
+        Tuple(3, 4, 9, 13, 8),
+        Tuple(0, 4, 9, 14, 5),
+        Tuple(5, 10, 16, 15, 14),
+        Tuple(6, 10, 16, 17, 11),
+        Tuple(7, 11, 17, 18, 12),
+        Tuple(8, 12, 18, 19, 13),
+        Tuple(9, 13, 19, 15, 14),
+        Tuple(15, 16, 17, 18, 19)),
+    Tuple(
+        Perm(0, 1, 2, 3, 4)(5, 6, 7, 8, 9)(10, 11, 12, 13, 14)(15, 16, 17, 18, 19),
+        Perm(0, 5, 10, 6, 1)(2, 4, 14, 16, 11)(3, 9, 15, 17, 7)(8, 13, 19, 18, 12),
+        Perm(0, 10, 17, 12, 3)(1, 6, 11, 7, 2)(4, 5, 16, 18, 8)(9, 14, 15, 19, 13),
+        Perm(0, 6, 17, 19, 9)(1, 11, 18, 13, 4)(2, 7, 12, 8, 3)(5, 10, 16, 15, 14),
+        Perm(0, 2, 12, 19, 14)(1, 7, 18, 15, 5)(3, 8, 13, 9, 4)(6, 11, 17, 16, 10),
+        Perm(0, 4, 9, 14, 5)(1, 3, 13, 15, 10)(2, 8, 19, 16, 6)(7, 12, 18, 17, 11),
+        Perm(0, 1)(2, 5)(3, 10)(4, 6)(7, 14)(8, 16)(9, 11)(12, 15)(13, 17)(18, 19),
+        Perm(0, 7)(1, 2)(3, 6)(4, 11)(5, 12)(8, 10)(9, 17)(13, 16)(14, 18)(15, 19),
+        Perm(0, 12)(1, 8)(2, 3)(4, 7)(5, 18)(6, 13)(9, 11)(10, 19)(14, 17)(15, 16),
+        Perm(0, 8)(1, 13)(2, 9)(3, 4)(5, 12)(6, 19)(7, 14)(10, 18)(11, 15)(16, 17),
+        Perm(0, 4)(1, 9)(2, 14)(3, 5)(6, 13)(7, 15)(8, 10)(11, 19)(12, 16)(17, 18),
+        Perm(0, 5)(1, 14)(2, 15)(3, 16)(4, 10)(6, 9)(7, 19)(8, 17)(11, 13)(12, 18),
+        Perm(0, 11)(1, 6)(2, 10)(3, 16)(4, 17)(5, 7)(8, 15)(9, 18)(12, 14)(13, 19),
+        Perm(0, 18)(1, 12)(2, 7)(3, 11)(4, 17)(5, 19)(6, 8)(9, 16)(10, 13)(14, 15),
+        Perm(0, 18)(1, 19)(2, 13)(3, 8)(4, 12)(5, 17)(6, 15)(7, 9)(10, 16)(11, 14),
+        Perm(0, 13)(1, 19)(2, 15)(3, 14)(4, 9)(5, 8)(6, 18)(7, 16)(10, 12)(11, 17),
+        Perm(0, 16)(1, 15)(2, 19)(3, 18)(4, 17)(5, 10)(6, 14)(7, 13)(8, 12)(9, 11),
+        Perm(0, 18)(1, 17)(2, 16)(3, 15)(4, 19)(5, 12)(6, 11)(7, 10)(8, 14)(9, 13),
+        Perm(0, 15)(1, 19)(2, 18)(3, 17)(4, 16)(5, 14)(6, 13)(7, 12)(8, 11)(9, 10),
+        Perm(0, 17)(1, 16)(2, 15)(3, 19)(4, 18)(5, 11)(6, 10)(7, 14)(8, 13)(9, 12),
+        Perm(0, 19)(1, 18)(2, 17)(3, 16)(4, 15)(5, 13)(6, 12)(7, 11)(8, 10)(9, 14),
+        Perm(1, 4, 5)(2, 9, 10)(3, 14, 6)(7, 13, 16)(8, 15, 11)(12, 19, 17),
+        Perm(19)(0, 6, 2)(3, 5, 11)(4, 10, 7)(8, 14, 17)(9, 16, 12)(13, 15, 18),
+        Perm(0, 11, 8)(1, 7, 3)(4, 6, 12)(5, 17, 13)(9, 10, 18)(14, 16, 19),
+        Perm(0, 7, 13)(1, 12, 9)(2, 8, 4)(5, 11, 19)(6, 18, 14)(10, 17, 15),
+        Perm(0, 3, 9)(1, 8, 14)(2, 13, 5)(6, 12, 15)(7, 19, 10)(11, 18, 16),
+        Perm(0, 14, 10)(1, 9, 16)(2, 13, 17)(3, 19, 11)(4, 15, 6)(7, 8, 18),
+        Perm(0, 16, 7)(1, 10, 11)(2, 5, 17)(3, 14, 18)(4, 15, 12)(8, 9, 19),
+        Perm(0, 16, 13)(1, 17, 8)(2, 11, 12)(3, 6, 18)(4, 10, 19)(5, 15, 9),
+        Perm(0, 11, 15)(1, 17, 14)(2, 18, 9)(3, 12, 13)(4, 7, 19)(5, 6, 16),
+        Perm(0, 8, 15)(1, 12, 16)(2, 18, 10)(3, 19, 5)(4, 13, 14)(6, 7, 17)))
+
+icosahedron = Polyhedron(
+    Tuple(0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11),
+    Tuple(
+        Tuple(0, 1, 2),
+        Tuple(0, 2, 3),
+        Tuple(0, 3, 4),
+        Tuple(0, 4, 5),
+        Tuple(0, 1, 5),
+        Tuple(1, 6, 7),
+        Tuple(1, 2, 7),
+        Tuple(2, 7, 8),
+        Tuple(2, 3, 8),
+        Tuple(3, 8, 9),
+        Tuple(3, 4, 9),
+        Tuple(4, 9, 10),
+        Tuple(4, 5, 10),
+        Tuple(5, 6, 10),
+        Tuple(1, 5, 6),
+        Tuple(6, 7, 11),
+        Tuple(7, 8, 11),
+        Tuple(8, 9, 11),
+        Tuple(9, 10, 11),
+        Tuple(6, 10, 11)),
+    Tuple(
+        Perm(11)(1, 2, 3, 4, 5)(6, 7, 8, 9, 10),
+        Perm(0, 5, 6, 7, 2)(3, 4, 10, 11, 8),
+        Perm(0, 1, 7, 8, 3)(4, 5, 6, 11, 9),
+        Perm(0, 2, 8, 9, 4)(1, 7, 11, 10, 5),
+        Perm(0, 3, 9, 10, 5)(1, 2, 8, 11, 6),
+        Perm(0, 4, 10, 6, 1)(2, 3, 9, 11, 7),
+        Perm(0, 1)(2, 5)(3, 6)(4, 7)(8, 10)(9, 11),
+        Perm(0, 2)(1, 3)(4, 7)(5, 8)(6, 9)(10, 11),
+        Perm(0, 3)(1, 9)(2, 4)(5, 8)(6, 11)(7, 10),
+        Perm(0, 4)(1, 9)(2, 10)(3, 5)(6, 8)(7, 11),
+        Perm(0, 5)(1, 4)(2, 10)(3, 6)(7, 9)(8, 11),
+        Perm(0, 6)(1, 5)(2, 10)(3, 11)(4, 7)(8, 9),
+        Perm(0, 7)(1, 2)(3, 6)(4, 11)(5, 8)(9, 10),
+        Perm(0, 8)(1, 9)(2, 3)(4, 7)(5, 11)(6, 10),
+        Perm(0, 9)(1, 11)(2, 10)(3, 4)(5, 8)(6, 7),
+        Perm(0, 10)(1, 9)(2, 11)(3, 6)(4, 5)(7, 8),
+        Perm(0, 11)(1, 6)(2, 10)(3, 9)(4, 8)(5, 7),
+        Perm(0, 11)(1, 8)(2, 7)(3, 6)(4, 10)(5, 9),
+        Perm(0, 11)(1, 10)(2, 9)(3, 8)(4, 7)(5, 6),
+        Perm(0, 11)(1, 7)(2, 6)(3, 10)(4, 9)(5, 8),
+        Perm(0, 11)(1, 9)(2, 8)(3, 7)(4, 6)(5, 10),
+        Perm(0, 5, 1)(2, 4, 6)(3, 10, 7)(8, 9, 11),
+        Perm(0, 1, 2)(3, 5, 7)(4, 6, 8)(9, 10, 11),
+        Perm(0, 2, 3)(1, 8, 4)(5, 7, 9)(6, 11, 10),
+        Perm(0, 3, 4)(1, 8, 10)(2, 9, 5)(6, 7, 11),
+        Perm(0, 4, 5)(1, 3, 10)(2, 9, 6)(7, 8, 11),
+        Perm(0, 10, 7)(1, 5, 6)(2, 4, 11)(3, 9, 8),
+        Perm(0, 6, 8)(1, 7, 2)(3, 5, 11)(4, 10, 9),
+        Perm(0, 7, 9)(1, 11, 4)(2, 8, 3)(5, 6, 10),
+        Perm(0, 8, 10)(1, 7, 6)(2, 11, 5)(3, 9, 4),
+        Perm(0, 9, 6)(1, 3, 11)(2, 8, 7)(4, 10, 5)))
+
+tetrahedron_faces = [tuple(arg) for arg in tetrahedron.faces]
+
+cube_faces = [tuple(arg) for arg in cube.faces]
+
+octahedron_faces = [tuple(arg) for arg in octahedron.faces]
+
+dodecahedron_faces = [tuple(arg) for arg in dodecahedron.faces]
+
+icosahedron_faces = [tuple(arg) for arg in icosahedron.faces]

lib/python3.12/site-packages/sympy/combinatorics/prufer.py

@@ -0,0 +1,435 @@
+from sympy.core import Basic
+from sympy.core.containers import Tuple
+from sympy.tensor.array import Array
+from sympy.core.sympify import _sympify
+from sympy.utilities.iterables import flatten, iterable
+from sympy.utilities.misc import as_int
+
+from collections import defaultdict
+
+
+class Prufer(Basic):
+    """
+    The Prufer correspondence is an algorithm that describes the
+    bijection between labeled trees and the Prufer code. A Prufer
+    code of a labeled tree is unique up to isomorphism and has
+    a length of n - 2.
+
+    Prufer sequences were first used by Heinz Prufer to give a
+    proof of Cayley's formula.
+
+    References
+    ==========
+
+    .. [1] https://mathworld.wolfram.com/LabeledTree.html
+
+    """
+    _prufer_repr = None
+    _tree_repr = None
+    _nodes = None
+    _rank = None
+
+    @property
+    def prufer_repr(self):
+        """Returns Prufer sequence for the Prufer object.
+
+        This sequence is found by removing the highest numbered vertex,
+        recording the node it was attached to, and continuing until only
+        two vertices remain. The Prufer sequence is the list of recorded nodes.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.prufer import Prufer
+        >>> Prufer([[0, 3], [1, 3], [2, 3], [3, 4], [4, 5]]).prufer_repr
+        [3, 3, 3, 4]
+        >>> Prufer([1, 0, 0]).prufer_repr
+        [1, 0, 0]
+
+        See Also
+        ========
+
+        to_prufer
+
+        """
+        if self._prufer_repr is None:
+            self._prufer_repr = self.to_prufer(self._tree_repr[:], self.nodes)
+        return self._prufer_repr
+
+    @property
+    def tree_repr(self):
+        """Returns the tree representation of the Prufer object.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.prufer import Prufer
+        >>> Prufer([[0, 3], [1, 3], [2, 3], [3, 4], [4, 5]]).tree_repr
+        [[0, 3], [1, 3], [2, 3], [3, 4], [4, 5]]
+        >>> Prufer([1, 0, 0]).tree_repr
+        [[1, 2], [0, 1], [0, 3], [0, 4]]
+
+        See Also
+        ========
+
+        to_tree
+
+        """
+        if self._tree_repr is None:
+            self._tree_repr = self.to_tree(self._prufer_repr[:])
+        return self._tree_repr
+
+    @property
+    def nodes(self):
+        """Returns the number of nodes in the tree.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.prufer import Prufer
+        >>> Prufer([[0, 3], [1, 3], [2, 3], [3, 4], [4, 5]]).nodes
+        6
+        >>> Prufer([1, 0, 0]).nodes
+        5
+
+        """
+        return self._nodes
+
+    @property
+    def rank(self):
+        """Returns the rank of the Prufer sequence.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.prufer import Prufer
+        >>> p = Prufer([[0, 3], [1, 3], [2, 3], [3, 4], [4, 5]])
+        >>> p.rank
+        778
+        >>> p.next(1).rank
+        779
+        >>> p.prev().rank
+        777
+
+        See Also
+        ========
+
+        prufer_rank, next, prev, size
+
+        """
+        if self._rank is None:
+            self._rank = self.prufer_rank()
+        return self._rank
+
+    @property
+    def size(self):
+        """Return the number of possible trees of this Prufer object.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.prufer import Prufer
+        >>> Prufer([0]*4).size == Prufer([6]*4).size == 1296
+        True
+
+        See Also
+        ========
+
+        prufer_rank, rank, next, prev
+
+        """
+        return self.prev(self.rank).prev().rank + 1
+
+    @staticmethod
+    def to_prufer(tree, n):
+        """Return the Prufer sequence for a tree given as a list of edges where
+        ``n`` is the number of nodes in the tree.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.prufer import Prufer
+        >>> a = Prufer([[0, 1], [0, 2], [0, 3]])
+        >>> a.prufer_repr
+        [0, 0]
+        >>> Prufer.to_prufer([[0, 1], [0, 2], [0, 3]], 4)
+        [0, 0]
+
+        See Also
+        ========
+        prufer_repr: returns Prufer sequence of a Prufer object.
+
+        """
+        d = defaultdict(int)
+        L = []
+        for edge in tree:
+            # Increment the value of the corresponding
+            # node in the degree list as we encounter an
+            # edge involving it.
+            d[edge[0]] += 1
+            d[edge[1]] += 1
+        for i in range(n - 2):
+            # find the smallest leaf
+            for x in range(n):
+                if d[x] == 1:
+                    break
+            # find the node it was connected to
+            y = None
+            for edge in tree:
+                if x == edge[0]:
+                    y = edge[1]
+                elif x == edge[1]:
+                    y = edge[0]
+                if y is not None:
+                    break
+            # record and update
+            L.append(y)
+            for j in (x, y):
+                d[j] -= 1
+                if not d[j]:
+                    d.pop(j)
+            tree.remove(edge)
+        return L
+
+    @staticmethod
+    def to_tree(prufer):
+        """Return the tree (as a list of edges) of the given Prufer sequence.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.prufer import Prufer
+        >>> a = Prufer([0, 2], 4)
+        >>> a.tree_repr
+        [[0, 1], [0, 2], [2, 3]]
+        >>> Prufer.to_tree([0, 2])
+        [[0, 1], [0, 2], [2, 3]]
+
+        References
+        ==========
+
+        .. [1] https://hamberg.no/erlend/posts/2010-11-06-prufer-sequence-compact-tree-representation.html
+
+        See Also
+        ========
+        tree_repr: returns tree representation of a Prufer object.
+
+        """
+        tree = []
+        last = []
+        n = len(prufer) + 2
+        d = defaultdict(lambda: 1)
+        for p in prufer:
+            d[p] += 1
+        for i in prufer:
+            for j in range(n):
+            # find the smallest leaf (degree = 1)
+                if d[j] == 1:
+                    break
+            # (i, j) is the new edge that we append to the tree
+            # and remove from the degree dictionary
+            d[i] -= 1
+            d[j] -= 1
+            tree.append(sorted([i, j]))
+        last = [i for i in range(n) if d[i] == 1] or [0, 1]
+        tree.append(last)
+
+        return tree
+
+    @staticmethod
+    def edges(*runs):
+        """Return a list of edges and the number of nodes from the given runs
+        that connect nodes in an integer-labelled tree.
+
+        All node numbers will be shifted so that the minimum node is 0. It is
+        not a problem if edges are repeated in the runs; only unique edges are
+        returned. There is no assumption made about what the range of the node
+        labels should be, but all nodes from the smallest through the largest
+        must be present.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.prufer import Prufer
+        >>> Prufer.edges([1, 2, 3], [2, 4, 5]) # a T
+        ([[0, 1], [1, 2], [1, 3], [3, 4]], 5)
+
+        Duplicate edges are removed:
+
+        >>> Prufer.edges([0, 1, 2, 3], [1, 4, 5], [1, 4, 6]) # a K
+        ([[0, 1], [1, 2], [1, 4], [2, 3], [4, 5], [4, 6]], 7)
+
+        """
+        e = set()
+        nmin = runs[0][0]
+        for r in runs:
+            for i in range(len(r) - 1):
+                a, b = r[i: i + 2]
+                if b < a:
+                    a, b = b, a
+                e.add((a, b))
+        rv = []
+        got = set()
+        nmin = nmax = None
+        for ei in e:
+            got.update(ei)
+            nmin = min(ei[0], nmin) if nmin is not None else ei[0]
+            nmax = max(ei[1], nmax) if nmax is not None else ei[1]
+            rv.append(list(ei))
+        missing = set(range(nmin, nmax + 1)) - got
+        if missing:
+            missing = [i + nmin for i in missing]
+            if len(missing) == 1:
+                msg = 'Node %s is missing.' % missing.pop()
+            else:
+                msg = 'Nodes %s are missing.' % sorted(missing)
+            raise ValueError(msg)
+        if nmin != 0:
+            for i, ei in enumerate(rv):
+                rv[i] = [n - nmin for n in ei]
+            nmax -= nmin
+        return sorted(rv), nmax + 1
+
+    def prufer_rank(self):
+        """Computes the rank of a Prufer sequence.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.prufer import Prufer
+        >>> a = Prufer([[0, 1], [0, 2], [0, 3]])
+        >>> a.prufer_rank()
+        0
+
+        See Also
+        ========
+
+        rank, next, prev, size
+
+        """
+        r = 0
+        p = 1
+        for i in range(self.nodes - 3, -1, -1):
+            r += p*self.prufer_repr[i]
+            p *= self.nodes
+        return r
+
+    @classmethod
+    def unrank(self, rank, n):
+        """Finds the unranked Prufer sequence.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.prufer import Prufer
+        >>> Prufer.unrank(0, 4)
+        Prufer([0, 0])
+
+        """
+        n, rank = as_int(n), as_int(rank)
+        L = defaultdict(int)
+        for i in range(n - 3, -1, -1):
+            L[i] = rank % n
+            rank = (rank - L[i])//n
+        return Prufer([L[i] for i in range(len(L))])
+
+    def __new__(cls, *args, **kw_args):
+        """The constructor for the Prufer object.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.prufer import Prufer
+
+        A Prufer object can be constructed from a list of edges:
+
+        >>> a = Prufer([[0, 1], [0, 2], [0, 3]])
+        >>> a.prufer_repr
+        [0, 0]
+
+        If the number of nodes is given, no checking of the nodes will
+        be performed; it will be assumed that nodes 0 through n - 1 are
+        present:
+
+        >>> Prufer([[0, 1], [0, 2], [0, 3]], 4)
+        Prufer([[0, 1], [0, 2], [0, 3]], 4)
+
+        A Prufer object can be constructed from a Prufer sequence:
+
+        >>> b = Prufer([1, 3])
+        >>> b.tree_repr
+        [[0, 1], [1, 3], [2, 3]]
+
+        """
+        arg0 = Array(args[0]) if args[0] else Tuple()
+        args = (arg0,) + tuple(_sympify(arg) for arg in args[1:])
+        ret_obj = Basic.__new__(cls, *args, **kw_args)
+        args = [list(args[0])]
+        if args[0] and iterable(args[0][0]):
+            if not args[0][0]:
+                raise ValueError(
+                    'Prufer expects at least one edge in the tree.')
+            if len(args) > 1:
+                nnodes = args[1]
+            else:
+                nodes = set(flatten(args[0]))
+                nnodes = max(nodes) + 1
+                if nnodes != len(nodes):
+                    missing = set(range(nnodes)) - nodes
+                    if len(missing) == 1:
+                        msg = 'Node %s is missing.' % missing.pop()
+                    else:
+                        msg = 'Nodes %s are missing.' % sorted(missing)
+                    raise ValueError(msg)
+            ret_obj._tree_repr = [list(i) for i in args[0]]
+            ret_obj._nodes = nnodes
+        else:
+            ret_obj._prufer_repr = args[0]
+            ret_obj._nodes = len(ret_obj._prufer_repr) + 2
+        return ret_obj
+
+    def next(self, delta=1):
+        """Generates the Prufer sequence that is delta beyond the current one.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.prufer import Prufer
+        >>> a = Prufer([[0, 1], [0, 2], [0, 3]])
+        >>> b = a.next(1) # == a.next()
+        >>> b.tree_repr
+        [[0, 2], [0, 1], [1, 3]]
+        >>> b.rank
+        1
+
+        See Also
+        ========
+
+        prufer_rank, rank, prev, size
+
+        """
+        return Prufer.unrank(self.rank + delta, self.nodes)
+
+    def prev(self, delta=1):
+        """Generates the Prufer sequence that is -delta before the current one.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.prufer import Prufer
+        >>> a = Prufer([[0, 1], [1, 2], [2, 3], [1, 4]])
+        >>> a.rank
+        36
+        >>> b = a.prev()
+        >>> b
+        Prufer([1, 2, 0])
+        >>> b.rank
+        35
+
+        See Also
+        ========
+
+        prufer_rank, rank, next, size
+
+        """
+        return Prufer.unrank(self.rank -delta, self.nodes)

lib/python3.12/site-packages/sympy/combinatorics/rewritingsystem_fsm.py

@@ -0,0 +1,60 @@
+class State:
+    '''
+    A representation of a state managed by a ``StateMachine``.
+
+    Attributes:
+        name (instance of FreeGroupElement or string) -- State name which is also assigned to the Machine.
+        transisitons (OrderedDict) -- Represents all the transitions of the state object.
+        state_type (string) -- Denotes the type (accept/start/dead) of the state.
+        rh_rule (instance of FreeGroupElement) -- right hand rule for dead state.
+        state_machine (instance of StateMachine object) -- The finite state machine that the state belongs to.
+    '''
+
+    def __init__(self, name, state_machine, state_type=None, rh_rule=None):
+        self.name = name
+        self.transitions = {}
+        self.state_machine = state_machine
+        self.state_type = state_type[0]
+        self.rh_rule = rh_rule
+
+    def add_transition(self, letter, state):
+        '''
+        Add a transition from the current state to a new state.
+
+        Keyword Arguments:
+            letter -- The alphabet element the current state reads to make the state transition.
+            state -- This will be an instance of the State object which represents a new state after in the transition after the alphabet is read.
+
+        '''
+        self.transitions[letter] = state
+
+class StateMachine:
+    '''
+    Representation of a finite state machine the manages the states and the transitions of the automaton.
+
+    Attributes:
+        states (dictionary) -- Collection of all registered `State` objects.
+        name (str) -- Name of the state machine.
+    '''
+
+    def __init__(self, name, automaton_alphabet):
+        self.name = name
+        self.automaton_alphabet = automaton_alphabet
+        self.states = {} # Contains all the states in the machine.
+        self.add_state('start', state_type='s')
+
+    def add_state(self, state_name, state_type=None, rh_rule=None):
+        '''
+        Instantiate a state object and stores it in the 'states' dictionary.
+
+        Arguments:
+            state_name (instance of FreeGroupElement or string) -- name of the new states.
+            state_type (string) -- Denotes the type (accept/start/dead) of the state added.
+            rh_rule (instance of FreeGroupElement) -- right hand rule for dead state.
+
+        '''
+        new_state = State(state_name, self, state_type, rh_rule)
+        self.states[state_name] = new_state
+
+    def __repr__(self):
+        return "%s" % (self.name)

lib/python3.12/site-packages/sympy/combinatorics/schur_number.py

@@ -0,0 +1,160 @@
+"""
+The Schur number S(k) is the largest integer n for which the interval [1,n]
+can be partitioned into k sum-free sets.(https://mathworld.wolfram.com/SchurNumber.html)
+"""
+import math
+from sympy.core import S
+from sympy.core.basic import Basic
+from sympy.core.function import Function
+from sympy.core.numbers import Integer
+
+
+class SchurNumber(Function):
+    r"""
+    This function creates a SchurNumber object
+    which is evaluated for `k \le 5` otherwise only
+    the lower bound information can be retrieved.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.schur_number import SchurNumber
+
+    Since S(3) = 13, hence the output is a number
+    >>> SchurNumber(3)
+    13
+
+    We do not know the Schur number for values greater than 5, hence
+    only the object is returned
+    >>> SchurNumber(6)
+    SchurNumber(6)
+
+    Now, the lower bound information can be retrieved using lower_bound()
+    method
+    >>> SchurNumber(6).lower_bound()
+    536
+
+    """
+
+    @classmethod
+    def eval(cls, k):
+        if k.is_Number:
+            if k is S.Infinity:
+                return S.Infinity
+            if k.is_zero:
+                return S.Zero
+            if not k.is_integer or k.is_negative:
+                raise ValueError("k should be a positive integer")
+            first_known_schur_numbers = {1: 1, 2: 4, 3: 13, 4: 44, 5: 160}
+            if k <= 5:
+                return Integer(first_known_schur_numbers[k])
+
+    def lower_bound(self):
+        f_ = self.args[0]
+        # Improved lower bounds known for S(6) and S(7)
+        if f_ == 6:
+            return Integer(536)
+        if f_ == 7:
+            return Integer(1680)
+        # For other cases, use general expression
+        if f_.is_Integer:
+            return 3*self.func(f_ - 1).lower_bound() - 1
+        return (3**f_ - 1)/2
+
+
+def _schur_subsets_number(n):
+
+    if n is S.Infinity:
+        raise ValueError("Input must be finite")
+    if n <= 0:
+        raise ValueError("n must be a non-zero positive integer.")
+    elif n <= 3:
+        min_k = 1
+    else:
+        min_k = math.ceil(math.log(2*n + 1, 3))
+
+    return Integer(min_k)
+
+
+def schur_partition(n):
+    """
+
+    This function returns the partition in the minimum number of sum-free subsets
+    according to the lower bound given by the Schur Number.
+
+    Parameters
+    ==========
+
+    n: a number
+        n is the upper limit of the range [1, n] for which we need to find and
+        return the minimum number of free subsets according to the lower bound
+        of schur number
+
+    Returns
+    =======
+
+    List of lists
+        List of the minimum number of sum-free subsets
+
+    Notes
+    =====
+
+    It is possible for some n to make the partition into less
+    subsets since the only known Schur numbers are:
+    S(1) = 1, S(2) = 4, S(3) = 13, S(4) = 44.
+    e.g for n = 44 the lower bound from the function above is 5 subsets but it has been proven
+    that can be done with 4 subsets.
+
+    Examples
+    ========
+
+    For n = 1, 2, 3 the answer is the set itself
+
+    >>> from sympy.combinatorics.schur_number import schur_partition
+    >>> schur_partition(2)
+    [[1, 2]]
+
+    For n > 3, the answer is the minimum number of sum-free subsets:
+
+    >>> schur_partition(5)
+    [[3, 2], [5], [1, 4]]
+
+    >>> schur_partition(8)
+    [[3, 2], [6, 5, 8], [1, 4, 7]]
+    """
+
+    if isinstance(n, Basic) and not n.is_Number:
+        raise ValueError("Input value must be a number")
+
+    number_of_subsets = _schur_subsets_number(n)
+    if n == 1:
+        sum_free_subsets = [[1]]
+    elif n == 2:
+        sum_free_subsets = [[1, 2]]
+    elif n == 3:
+        sum_free_subsets = [[1, 2, 3]]
+    else:
+        sum_free_subsets = [[1, 4], [2, 3]]
+
+    while len(sum_free_subsets) < number_of_subsets:
+        sum_free_subsets = _generate_next_list(sum_free_subsets, n)
+        missed_elements = [3*k + 1 for k in range(len(sum_free_subsets), (n-1)//3 + 1)]
+        sum_free_subsets[-1] += missed_elements
+
+    return sum_free_subsets
+
+
+def _generate_next_list(current_list, n):
+    new_list = []
+
+    for item in current_list:
+        temp_1 = [number*3 for number in item if number*3 <= n]
+        temp_2 = [number*3 - 1 for number in item if number*3 - 1 <= n]
+        new_item = temp_1 + temp_2
+        new_list.append(new_item)
+
+    last_list = [3*k + 1 for k in range(len(current_list)+1) if 3*k + 1 <= n]
+    new_list.append(last_list)
+    current_list = new_list
+
+    return current_list

lib/python3.12/site-packages/sympy/combinatorics/subsets.py

@@ -0,0 +1,619 @@
+from itertools import combinations
+
+from sympy.combinatorics.graycode import GrayCode
+
+
+class Subset():
+    """
+    Represents a basic subset object.
+
+    Explanation
+    ===========
+
+    We generate subsets using essentially two techniques,
+    binary enumeration and lexicographic enumeration.
+    The Subset class takes two arguments, the first one
+    describes the initial subset to consider and the second
+    describes the superset.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics import Subset
+    >>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
+    >>> a.next_binary().subset
+    ['b']
+    >>> a.prev_binary().subset
+    ['c']
+    """
+
+    _rank_binary = None
+    _rank_lex = None
+    _rank_graycode = None
+    _subset = None
+    _superset = None
+
+    def __new__(cls, subset, superset):
+        """
+        Default constructor.
+
+        It takes the ``subset`` and its ``superset`` as its parameters.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
+        >>> a.subset
+        ['c', 'd']
+        >>> a.superset
+        ['a', 'b', 'c', 'd']
+        >>> a.size
+        2
+        """
+        if len(subset) > len(superset):
+            raise ValueError('Invalid arguments have been provided. The '
+                             'superset must be larger than the subset.')
+        for elem in subset:
+            if elem not in superset:
+                raise ValueError('The superset provided is invalid as it does '
+                                 'not contain the element {}'.format(elem))
+        obj = object.__new__(cls)
+        obj._subset = subset
+        obj._superset = superset
+        return obj
+
+    def __eq__(self, other):
+        """Return a boolean indicating whether a == b on the basis of
+        whether both objects are of the class Subset and if the values
+        of the subset and superset attributes are the same.
+        """
+        if not isinstance(other, Subset):
+            return NotImplemented
+        return self.subset == other.subset and self.superset == other.superset
+
+    def iterate_binary(self, k):
+        """
+        This is a helper function. It iterates over the
+        binary subsets by ``k`` steps. This variable can be
+        both positive or negative.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
+        >>> a.iterate_binary(-2).subset
+        ['d']
+        >>> a = Subset(['a', 'b', 'c'], ['a', 'b', 'c', 'd'])
+        >>> a.iterate_binary(2).subset
+        []
+
+        See Also
+        ========
+
+        next_binary, prev_binary
+        """
+        bin_list = Subset.bitlist_from_subset(self.subset, self.superset)
+        n = (int(''.join(bin_list), 2) + k) % 2**self.superset_size
+        bits = bin(n)[2:].rjust(self.superset_size, '0')
+        return Subset.subset_from_bitlist(self.superset, bits)
+
+    def next_binary(self):
+        """
+        Generates the next binary ordered subset.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
+        >>> a.next_binary().subset
+        ['b']
+        >>> a = Subset(['a', 'b', 'c', 'd'], ['a', 'b', 'c', 'd'])
+        >>> a.next_binary().subset
+        []
+
+        See Also
+        ========
+
+        prev_binary, iterate_binary
+        """
+        return self.iterate_binary(1)
+
+    def prev_binary(self):
+        """
+        Generates the previous binary ordered subset.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> a = Subset([], ['a', 'b', 'c', 'd'])
+        >>> a.prev_binary().subset
+        ['a', 'b', 'c', 'd']
+        >>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
+        >>> a.prev_binary().subset
+        ['c']
+
+        See Also
+        ========
+
+        next_binary, iterate_binary
+        """
+        return self.iterate_binary(-1)
+
+    def next_lexicographic(self):
+        """
+        Generates the next lexicographically ordered subset.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
+        >>> a.next_lexicographic().subset
+        ['d']
+        >>> a = Subset(['d'], ['a', 'b', 'c', 'd'])
+        >>> a.next_lexicographic().subset
+        []
+
+        See Also
+        ========
+
+        prev_lexicographic
+        """
+        i = self.superset_size - 1
+        indices = Subset.subset_indices(self.subset, self.superset)
+
+        if i in indices:
+            if i - 1 in indices:
+                indices.remove(i - 1)
+            else:
+                indices.remove(i)
+                i = i - 1
+                while i >= 0 and i not in indices:
+                    i = i - 1
+                if i >= 0:
+                    indices.remove(i)
+                    indices.append(i+1)
+        else:
+            while i not in indices and i >= 0:
+                i = i - 1
+            indices.append(i + 1)
+
+        ret_set = []
+        super_set = self.superset
+        for i in indices:
+            ret_set.append(super_set[i])
+        return Subset(ret_set, super_set)
+
+    def prev_lexicographic(self):
+        """
+        Generates the previous lexicographically ordered subset.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> a = Subset([], ['a', 'b', 'c', 'd'])
+        >>> a.prev_lexicographic().subset
+        ['d']
+        >>> a = Subset(['c','d'], ['a', 'b', 'c', 'd'])
+        >>> a.prev_lexicographic().subset
+        ['c']
+
+        See Also
+        ========
+
+        next_lexicographic
+        """
+        i = self.superset_size - 1
+        indices = Subset.subset_indices(self.subset, self.superset)
+
+        while i >= 0 and i not in indices:
+            i = i - 1
+
+        if i == 0 or i - 1 in indices:
+            indices.remove(i)
+        else:
+            if i >= 0:
+                indices.remove(i)
+                indices.append(i - 1)
+            indices.append(self.superset_size - 1)
+
+        ret_set = []
+        super_set = self.superset
+        for i in indices:
+            ret_set.append(super_set[i])
+        return Subset(ret_set, super_set)
+
+    def iterate_graycode(self, k):
+        """
+        Helper function used for prev_gray and next_gray.
+        It performs ``k`` step overs to get the respective Gray codes.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> a = Subset([1, 2, 3], [1, 2, 3, 4])
+        >>> a.iterate_graycode(3).subset
+        [1, 4]
+        >>> a.iterate_graycode(-2).subset
+        [1, 2, 4]
+
+        See Also
+        ========
+
+        next_gray, prev_gray
+        """
+        unranked_code = GrayCode.unrank(self.superset_size,
+                                       (self.rank_gray + k) % self.cardinality)
+        return Subset.subset_from_bitlist(self.superset,
+                                          unranked_code)
+
+    def next_gray(self):
+        """
+        Generates the next Gray code ordered subset.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> a = Subset([1, 2, 3], [1, 2, 3, 4])
+        >>> a.next_gray().subset
+        [1, 3]
+
+        See Also
+        ========
+
+        iterate_graycode, prev_gray
+        """
+        return self.iterate_graycode(1)
+
+    def prev_gray(self):
+        """
+        Generates the previous Gray code ordered subset.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> a = Subset([2, 3, 4], [1, 2, 3, 4, 5])
+        >>> a.prev_gray().subset
+        [2, 3, 4, 5]
+
+        See Also
+        ========
+
+        iterate_graycode, next_gray
+        """
+        return self.iterate_graycode(-1)
+
+    @property
+    def rank_binary(self):
+        """
+        Computes the binary ordered rank.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> a = Subset([], ['a','b','c','d'])
+        >>> a.rank_binary
+        0
+        >>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
+        >>> a.rank_binary
+        3
+
+        See Also
+        ========
+
+        iterate_binary, unrank_binary
+        """
+        if self._rank_binary is None:
+            self._rank_binary = int("".join(
+                Subset.bitlist_from_subset(self.subset,
+                                           self.superset)), 2)
+        return self._rank_binary
+
+    @property
+    def rank_lexicographic(self):
+        """
+        Computes the lexicographic ranking of the subset.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
+        >>> a.rank_lexicographic
+        14
+        >>> a = Subset([2, 4, 5], [1, 2, 3, 4, 5, 6])
+        >>> a.rank_lexicographic
+        43
+        """
+        if self._rank_lex is None:
+            def _ranklex(self, subset_index, i, n):
+                if subset_index == [] or i > n:
+                    return 0
+                if i in subset_index:
+                    subset_index.remove(i)
+                    return 1 + _ranklex(self, subset_index, i + 1, n)
+                return 2**(n - i - 1) + _ranklex(self, subset_index, i + 1, n)
+            indices = Subset.subset_indices(self.subset, self.superset)
+            self._rank_lex = _ranklex(self, indices, 0, self.superset_size)
+        return self._rank_lex
+
+    @property
+    def rank_gray(self):
+        """
+        Computes the Gray code ranking of the subset.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> a = Subset(['c','d'], ['a','b','c','d'])
+        >>> a.rank_gray
+        2
+        >>> a = Subset([2, 4, 5], [1, 2, 3, 4, 5, 6])
+        >>> a.rank_gray
+        27
+
+        See Also
+        ========
+
+        iterate_graycode, unrank_gray
+        """
+        if self._rank_graycode is None:
+            bits = Subset.bitlist_from_subset(self.subset, self.superset)
+            self._rank_graycode = GrayCode(len(bits), start=bits).rank
+        return self._rank_graycode
+
+    @property
+    def subset(self):
+        """
+        Gets the subset represented by the current instance.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
+        >>> a.subset
+        ['c', 'd']
+
+        See Also
+        ========
+
+        superset, size, superset_size, cardinality
+        """
+        return self._subset
+
+    @property
+    def size(self):
+        """
+        Gets the size of the subset.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
+        >>> a.size
+        2
+
+        See Also
+        ========
+
+        subset, superset, superset_size, cardinality
+        """
+        return len(self.subset)
+
+    @property
+    def superset(self):
+        """
+        Gets the superset of the subset.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
+        >>> a.superset
+        ['a', 'b', 'c', 'd']
+
+        See Also
+        ========
+
+        subset, size, superset_size, cardinality
+        """
+        return self._superset
+
+    @property
+    def superset_size(self):
+        """
+        Returns the size of the superset.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
+        >>> a.superset_size
+        4
+
+        See Also
+        ========
+
+        subset, superset, size, cardinality
+        """
+        return len(self.superset)
+
+    @property
+    def cardinality(self):
+        """
+        Returns the number of all possible subsets.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> a = Subset(['c', 'd'], ['a', 'b', 'c', 'd'])
+        >>> a.cardinality
+        16
+
+        See Also
+        ========
+
+        subset, superset, size, superset_size
+        """
+        return 2**(self.superset_size)
+
+    @classmethod
+    def subset_from_bitlist(self, super_set, bitlist):
+        """
+        Gets the subset defined by the bitlist.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> Subset.subset_from_bitlist(['a', 'b', 'c', 'd'], '0011').subset
+        ['c', 'd']
+
+        See Also
+        ========
+
+        bitlist_from_subset
+        """
+        if len(super_set) != len(bitlist):
+            raise ValueError("The sizes of the lists are not equal")
+        ret_set = []
+        for i in range(len(bitlist)):
+            if bitlist[i] == '1':
+                ret_set.append(super_set[i])
+        return Subset(ret_set, super_set)
+
+    @classmethod
+    def bitlist_from_subset(self, subset, superset):
+        """
+        Gets the bitlist corresponding to a subset.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> Subset.bitlist_from_subset(['c', 'd'], ['a', 'b', 'c', 'd'])
+        '0011'
+
+        See Also
+        ========
+
+        subset_from_bitlist
+        """
+        bitlist = ['0'] * len(superset)
+        if isinstance(subset, Subset):
+            subset = subset.subset
+        for i in Subset.subset_indices(subset, superset):
+            bitlist[i] = '1'
+        return ''.join(bitlist)
+
+    @classmethod
+    def unrank_binary(self, rank, superset):
+        """
+        Gets the binary ordered subset of the specified rank.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> Subset.unrank_binary(4, ['a', 'b', 'c', 'd']).subset
+        ['b']
+
+        See Also
+        ========
+
+        iterate_binary, rank_binary
+        """
+        bits = bin(rank)[2:].rjust(len(superset), '0')
+        return Subset.subset_from_bitlist(superset, bits)
+
+    @classmethod
+    def unrank_gray(self, rank, superset):
+        """
+        Gets the Gray code ordered subset of the specified rank.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Subset
+        >>> Subset.unrank_gray(4, ['a', 'b', 'c']).subset
+        ['a', 'b']
+        >>> Subset.unrank_gray(0, ['a', 'b', 'c']).subset
+        []
+
+        See Also
+        ========
+
+        iterate_graycode, rank_gray
+        """
+        graycode_bitlist = GrayCode.unrank(len(superset), rank)
+        return Subset.subset_from_bitlist(superset, graycode_bitlist)
+
+    @classmethod
+    def subset_indices(self, subset, superset):
+        """Return indices of subset in superset in a list; the list is empty
+        if all elements of ``subset`` are not in ``superset``.
+
+        Examples
+        ========
+
+            >>> from sympy.combinatorics import Subset
+            >>> superset = [1, 3, 2, 5, 4]
+            >>> Subset.subset_indices([3, 2, 1], superset)
+            [1, 2, 0]
+            >>> Subset.subset_indices([1, 6], superset)
+            []
+            >>> Subset.subset_indices([], superset)
+            []
+
+        """
+        a, b = superset, subset
+        sb = set(b)
+        d = {}
+        for i, ai in enumerate(a):
+            if ai in sb:
+                d[ai] = i
+                sb.remove(ai)
+                if not sb:
+                    break
+        else:
+            return []
+        return [d[bi] for bi in b]
+
+
+def ksubsets(superset, k):
+    """
+    Finds the subsets of size ``k`` in lexicographic order.
+
+    This uses the itertools generator.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.subsets import ksubsets
+    >>> list(ksubsets([1, 2, 3], 2))
+    [(1, 2), (1, 3), (2, 3)]
+    >>> list(ksubsets([1, 2, 3, 4, 5], 2))
+    [(1, 2), (1, 3), (1, 4), (1, 5), (2, 3), (2, 4), \
+    (2, 5), (3, 4), (3, 5), (4, 5)]
+
+    See Also
+    ========
+
+    Subset
+    """
+    return combinations(superset, k)

lib/python3.12/site-packages/sympy/combinatorics/tensor_can.py

@@ -0,0 +1,1190 @@
+from sympy.combinatorics.permutations import Permutation, _af_rmul, \
+    _af_invert, _af_new
+from sympy.combinatorics.perm_groups import PermutationGroup, _orbit, \
+    _orbit_transversal
+from sympy.combinatorics.util import _distribute_gens_by_base, \
+    _orbits_transversals_from_bsgs
+
+"""
+    References for tensor canonicalization:
+
+    [1] R. Portugal "Algorithmic simplification of tensor expressions",
+        J. Phys. A 32 (1999) 7779-7789
+
+    [2] R. Portugal, B.F. Svaiter "Group-theoretic Approach for Symbolic
+        Tensor Manipulation: I. Free Indices"
+        arXiv:math-ph/0107031v1
+
+    [3] L.R.U. Manssur, R. Portugal "Group-theoretic Approach for Symbolic
+        Tensor Manipulation: II. Dummy Indices"
+        arXiv:math-ph/0107032v1
+
+    [4] xperm.c part of XPerm written by J. M. Martin-Garcia
+        http://www.xact.es/index.html
+"""
+
+
+def dummy_sgs(dummies, sym, n):
+    """
+    Return the strong generators for dummy indices.
+
+    Parameters
+    ==========
+
+    dummies : List of dummy indices.
+        `dummies[2k], dummies[2k+1]` are paired indices.
+        In base form, the dummy indices are always in
+        consecutive positions.
+    sym : symmetry under interchange of contracted dummies::
+        * None  no symmetry
+        * 0     commuting
+        * 1     anticommuting
+
+    n : number of indices
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.tensor_can import dummy_sgs
+    >>> dummy_sgs(list(range(2, 8)), 0, 8)
+    [[0, 1, 3, 2, 4, 5, 6, 7, 8, 9], [0, 1, 2, 3, 5, 4, 6, 7, 8, 9],
+     [0, 1, 2, 3, 4, 5, 7, 6, 8, 9], [0, 1, 4, 5, 2, 3, 6, 7, 8, 9],
+     [0, 1, 2, 3, 6, 7, 4, 5, 8, 9]]
+    """
+    if len(dummies) > n:
+        raise ValueError("List too large")
+    res = []
+    # exchange of contravariant and covariant indices
+    if sym is not None:
+        for j in dummies[::2]:
+            a = list(range(n + 2))
+            if sym == 1:
+                a[n] = n + 1
+                a[n + 1] = n
+            a[j], a[j + 1] = a[j + 1], a[j]
+            res.append(a)
+    # rename dummy indices
+    for j in dummies[:-3:2]:
+        a = list(range(n + 2))
+        a[j:j + 4] = a[j + 2], a[j + 3], a[j], a[j + 1]
+        res.append(a)
+    return res
+
+
+def _min_dummies(dummies, sym, indices):
+    """
+    Return list of minima of the orbits of indices in group of dummies.
+    See ``double_coset_can_rep`` for the description of ``dummies`` and ``sym``.
+    ``indices`` is the initial list of dummy indices.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.tensor_can import _min_dummies
+    >>> _min_dummies([list(range(2, 8))], [0], list(range(10)))
+    [0, 1, 2, 2, 2, 2, 2, 2, 8, 9]
+    """
+    num_types = len(sym)
+    m = [min(dx) if dx else None for dx in dummies]
+    res = indices[:]
+    for i in range(num_types):
+        for c, i in enumerate(indices):
+            for j in range(num_types):
+                if i in dummies[j]:
+                    res[c] = m[j]
+                    break
+    return res
+
+
+def _trace_S(s, j, b, S_cosets):
+    """
+    Return the representative h satisfying s[h[b]] == j
+
+    If there is not such a representative return None
+    """
+    for h in S_cosets[b]:
+        if s[h[b]] == j:
+            return h
+    return None
+
+
+def _trace_D(gj, p_i, Dxtrav):
+    """
+    Return the representative h satisfying h[gj] == p_i
+
+    If there is not such a representative return None
+    """
+    for h in Dxtrav:
+        if h[gj] == p_i:
+            return h
+    return None
+
+
+def _dumx_remove(dumx, dumx_flat, p0):
+    """
+    remove p0 from dumx
+    """
+    res = []
+    for dx in dumx:
+        if p0 not in dx:
+            res.append(dx)
+            continue
+        k = dx.index(p0)
+        if k % 2 == 0:
+            p0_paired = dx[k + 1]
+        else:
+            p0_paired = dx[k - 1]
+        dx.remove(p0)
+        dx.remove(p0_paired)
+        dumx_flat.remove(p0)
+        dumx_flat.remove(p0_paired)
+        res.append(dx)
+
+
+def transversal2coset(size, base, transversal):
+    a = []
+    j = 0
+    for i in range(size):
+        if i in base:
+            a.append(sorted(transversal[j].values()))
+            j += 1
+        else:
+            a.append([list(range(size))])
+    j = len(a) - 1
+    while a[j] == [list(range(size))]:
+        j -= 1
+    return a[:j + 1]
+
+
+def double_coset_can_rep(dummies, sym, b_S, sgens, S_transversals, g):
+    r"""
+    Butler-Portugal algorithm for tensor canonicalization with dummy indices.
+
+    Parameters
+    ==========
+
+      dummies
+        list of lists of dummy indices,
+        one list for each type of index;
+        the dummy indices are put in order contravariant, covariant
+        [d0, -d0, d1, -d1, ...].
+
+      sym
+        list of the symmetries of the index metric for each type.
+
+      possible symmetries of the metrics
+              * 0     symmetric
+              * 1     antisymmetric
+              * None  no symmetry
+
+      b_S
+        base of a minimal slot symmetry BSGS.
+
+      sgens
+        generators of the slot symmetry BSGS.
+
+      S_transversals
+        transversals for the slot BSGS.
+
+      g
+        permutation representing the tensor.
+
+    Returns
+    =======
+
+    Return 0 if the tensor is zero, else return the array form of
+    the permutation representing the canonical form of the tensor.
+
+    Notes
+    =====
+
+    A tensor with dummy indices can be represented in a number
+    of equivalent ways which typically grows exponentially with
+    the number of indices. To be able to establish if two tensors
+    with many indices are equal becomes computationally very slow
+    in absence of an efficient algorithm.
+
+    The Butler-Portugal algorithm [3] is an efficient algorithm to
+    put tensors in canonical form, solving the above problem.
+
+    Portugal observed that a tensor can be represented by a permutation,
+    and that the class of tensors equivalent to it under slot and dummy
+    symmetries is equivalent to the double coset `D*g*S`
+    (Note: in this documentation we use the conventions for multiplication
+    of permutations p, q with (p*q)(i) = p[q[i]] which is opposite
+    to the one used in the Permutation class)
+
+    Using the algorithm by Butler to find a representative of the
+    double coset one can find a canonical form for the tensor.
+
+    To see this correspondence,
+    let `g` be a permutation in array form; a tensor with indices `ind`
+    (the indices including both the contravariant and the covariant ones)
+    can be written as
+
+    `t = T(ind[g[0]], \dots, ind[g[n-1]])`,
+
+    where `n = len(ind)`;
+    `g` has size `n + 2`, the last two indices for the sign of the tensor
+    (trick introduced in [4]).
+
+    A slot symmetry transformation `s` is a permutation acting on the slots
+    `t \rightarrow T(ind[(g*s)[0]], \dots, ind[(g*s)[n-1]])`
+
+    A dummy symmetry transformation acts on `ind`
+    `t \rightarrow T(ind[(d*g)[0]], \dots, ind[(d*g)[n-1]])`
+
+    Being interested only in the transformations of the tensor under
+    these symmetries, one can represent the tensor by `g`, which transforms
+    as
+
+    `g -> d*g*s`, so it belongs to the coset `D*g*S`, or in other words
+    to the set of all permutations allowed by the slot and dummy symmetries.
+
+    Let us explain the conventions by an example.
+
+    Given a tensor `T^{d3 d2 d1}{}_{d1 d2 d3}` with the slot symmetries
+          `T^{a0 a1 a2 a3 a4 a5} = -T^{a2 a1 a0 a3 a4 a5}`
+
+          `T^{a0 a1 a2 a3 a4 a5} = -T^{a4 a1 a2 a3 a0 a5}`
+
+    and symmetric metric, find the tensor equivalent to it which
+    is the lowest under the ordering of indices:
+    lexicographic ordering `d1, d2, d3` and then contravariant
+    before covariant index; that is the canonical form of the tensor.
+
+    The canonical form is `-T^{d1 d2 d3}{}_{d1 d2 d3}`
+    obtained using `T^{a0 a1 a2 a3 a4 a5} = -T^{a2 a1 a0 a3 a4 a5}`.
+
+    To convert this problem in the input for this function,
+    use the following ordering of the index names
+    (- for covariant for short) `d1, -d1, d2, -d2, d3, -d3`
+
+    `T^{d3 d2 d1}{}_{d1 d2 d3}` corresponds to `g = [4, 2, 0, 1, 3, 5, 6, 7]`
+    where the last two indices are for the sign
+
+    `sgens = [Permutation(0, 2)(6, 7), Permutation(0, 4)(6, 7)]`
+
+    sgens[0] is the slot symmetry `-(0, 2)`
+    `T^{a0 a1 a2 a3 a4 a5} = -T^{a2 a1 a0 a3 a4 a5}`
+
+    sgens[1] is the slot symmetry `-(0, 4)`
+    `T^{a0 a1 a2 a3 a4 a5} = -T^{a4 a1 a2 a3 a0 a5}`
+
+    The dummy symmetry group D is generated by the strong base generators
+    `[(0, 1), (2, 3), (4, 5), (0, 2)(1, 3), (0, 4)(1, 5)]`
+    where the first three interchange covariant and contravariant
+    positions of the same index (d1 <-> -d1) and the last two interchange
+    the dummy indices themselves (d1 <-> d2).
+
+    The dummy symmetry acts from the left
+    `d = [1, 0, 2, 3, 4, 5, 6, 7]`  exchange `d1 \leftrightarrow -d1`
+    `T^{d3 d2 d1}{}_{d1 d2 d3} == T^{d3 d2}{}_{d1}{}^{d1}{}_{d2 d3}`
+
+    `g=[4, 2, 0, 1, 3, 5, 6, 7]  -> [4, 2, 1, 0, 3, 5, 6, 7] = _af_rmul(d, g)`
+    which differs from `_af_rmul(g, d)`.
+
+    The slot symmetry acts from the right
+    `s = [2, 1, 0, 3, 4, 5, 7, 6]`  exchanges slots 0 and 2 and changes sign
+    `T^{d3 d2 d1}{}_{d1 d2 d3} == -T^{d1 d2 d3}{}_{d1 d2 d3}`
+
+    `g=[4,2,0,1,3,5,6,7]  -> [0, 2, 4, 1, 3, 5, 7, 6] = _af_rmul(g, s)`
+
+    Example in which the tensor is zero, same slot symmetries as above:
+    `T^{d2}{}_{d1 d3}{}^{d1 d3}{}_{d2}`
+
+    `= -T^{d3}{}_{d1 d3}{}^{d1 d2}{}_{d2}`   under slot symmetry `-(0,4)`;
+
+    `= T_{d3 d1}{}^{d3}{}^{d1 d2}{}_{d2}`    under slot symmetry `-(0,2)`;
+
+    `= T^{d3}{}_{d1 d3}{}^{d1 d2}{}_{d2}`    symmetric metric;
+
+    `= 0`  since two of these lines have tensors differ only for the sign.
+
+    The double coset D*g*S consists of permutations `h = d*g*s` corresponding
+    to equivalent tensors; if there are two `h` which are the same apart
+    from the sign, return zero; otherwise
+    choose as representative the tensor with indices
+    ordered lexicographically according to `[d1, -d1, d2, -d2, d3, -d3]`
+    that is ``rep = min(D*g*S) = min([d*g*s for d in D for s in S])``
+
+    The indices are fixed one by one; first choose the lowest index
+    for slot 0, then the lowest remaining index for slot 1, etc.
+    Doing this one obtains a chain of stabilizers
+
+    `S \rightarrow S_{b0} \rightarrow S_{b0,b1} \rightarrow \dots` and
+    `D \rightarrow D_{p0} \rightarrow D_{p0,p1} \rightarrow \dots`
+
+    where ``[b0, b1, ...] = range(b)`` is a base of the symmetric group;
+    the strong base `b_S` of S is an ordered sublist of it;
+    therefore it is sufficient to compute once the
+    strong base generators of S using the Schreier-Sims algorithm;
+    the stabilizers of the strong base generators are the
+    strong base generators of the stabilizer subgroup.
+
+    ``dbase = [p0, p1, ...]`` is not in general in lexicographic order,
+    so that one must recompute the strong base generators each time;
+    however this is trivial, there is no need to use the Schreier-Sims
+    algorithm for D.
+
+    The algorithm keeps a TAB of elements `(s_i, d_i, h_i)`
+    where `h_i = d_i \times g \times s_i` satisfying `h_i[j] = p_j` for `0 \le j < i`
+    starting from `s_0 = id, d_0 = id, h_0 = g`.
+
+    The equations `h_0[0] = p_0, h_1[1] = p_1, \dots` are solved in this order,
+    choosing each time the lowest possible value of p_i
+
+    For `j < i`
+    `d_i*g*s_i*S_{b_0, \dots, b_{i-1}}*b_j = D_{p_0, \dots, p_{i-1}}*p_j`
+    so that for dx in `D_{p_0,\dots,p_{i-1}}` and sx in
+    `S_{base[0], \dots, base[i-1]}` one has `dx*d_i*g*s_i*sx*b_j = p_j`
+
+    Search for dx, sx such that this equation holds for `j = i`;
+    it can be written as `s_i*sx*b_j = J, dx*d_i*g*J = p_j`
+    `sx*b_j = s_i**-1*J; sx = trace(s_i**-1, S_{b_0,...,b_{i-1}})`
+    `dx**-1*p_j = d_i*g*J; dx = trace(d_i*g*J, D_{p_0,...,p_{i-1}})`
+
+    `s_{i+1} = s_i*trace(s_i**-1*J, S_{b_0,...,b_{i-1}})`
+    `d_{i+1} = trace(d_i*g*J, D_{p_0,...,p_{i-1}})**-1*d_i`
+    `h_{i+1}*b_i = d_{i+1}*g*s_{i+1}*b_i = p_i`
+
+    `h_n*b_j = p_j` for all j, so that `h_n` is the solution.
+
+    Add the found `(s, d, h)` to TAB1.
+
+    At the end of the iteration sort TAB1 with respect to the `h`;
+    if there are two consecutive `h` in TAB1 which differ only for the
+    sign, the tensor is zero, so return 0;
+    if there are two consecutive `h` which are equal, keep only one.
+
+    Then stabilize the slot generators under `i` and the dummy generators
+    under `p_i`.
+
+    Assign `TAB = TAB1` at the end of the iteration step.
+
+    At the end `TAB` contains a unique `(s, d, h)`, since all the slots
+    of the tensor `h` have been fixed to have the minimum value according
+    to the symmetries. The algorithm returns `h`.
+
+    It is important that the slot BSGS has lexicographic minimal base,
+    otherwise there is an `i` which does not belong to the slot base
+    for which `p_i` is fixed by the dummy symmetry only, while `i`
+    is not invariant from the slot stabilizer, so `p_i` is not in
+    general the minimal value.
+
+    This algorithm differs slightly from the original algorithm [3]:
+      the canonical form is minimal lexicographically, and
+      the BSGS has minimal base under lexicographic order.
+      Equal tensors `h` are eliminated from TAB.
+
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.permutations import Permutation
+    >>> from sympy.combinatorics.tensor_can import double_coset_can_rep, get_transversals
+    >>> gens = [Permutation(x) for x in [[2, 1, 0, 3, 4, 5, 7, 6], [4, 1, 2, 3, 0, 5, 7, 6]]]
+    >>> base = [0, 2]
+    >>> g = Permutation([4, 2, 0, 1, 3, 5, 6, 7])
+    >>> transversals = get_transversals(base, gens)
+    >>> double_coset_can_rep([list(range(6))], [0], base, gens, transversals, g)
+    [0, 1, 2, 3, 4, 5, 7, 6]
+
+    >>> g = Permutation([4, 1, 3, 0, 5, 2, 6, 7])
+    >>> double_coset_can_rep([list(range(6))], [0], base, gens, transversals, g)
+    0
+    """
+    size = g.size
+    g = g.array_form
+    num_dummies = size - 2
+    indices = list(range(num_dummies))
+    all_metrics_with_sym = not any(_ is None for _ in sym)
+    num_types = len(sym)
+    dumx = dummies[:]
+    dumx_flat = []
+    for dx in dumx:
+        dumx_flat.extend(dx)
+    b_S = b_S[:]
+    sgensx = [h._array_form for h in sgens]
+    if b_S:
+        S_transversals = transversal2coset(size, b_S, S_transversals)
+    # strong generating set for D
+    dsgsx = []
+    for i in range(num_types):
+        dsgsx.extend(dummy_sgs(dumx[i], sym[i], num_dummies))
+    idn = list(range(size))
+    # TAB = list of entries (s, d, h) where h = _af_rmuln(d,g,s)
+    # for short, in the following d*g*s means _af_rmuln(d,g,s)
+    TAB = [(idn, idn, g)]
+    for i in range(size - 2):
+        b = i
+        testb = b in b_S and sgensx
+        if testb:
+            sgensx1 = [_af_new(_) for _ in sgensx]
+            deltab = _orbit(size, sgensx1, b)
+        else:
+            deltab = {b}
+        # p1 = min(IMAGES) = min(Union D_p*h*deltab for h in TAB)
+        if all_metrics_with_sym:
+            md = _min_dummies(dumx, sym, indices)
+        else:
+            md = [min(_orbit(size, [_af_new(
+                ddx) for ddx in dsgsx], ii)) for ii in range(size - 2)]
+
+        p_i = min(min(md[h[x]] for x in deltab) for s, d, h in TAB)
+        dsgsx1 = [_af_new(_) for _ in dsgsx]
+        Dxtrav = _orbit_transversal(size, dsgsx1, p_i, False, af=True) \
+            if dsgsx else None
+        if Dxtrav:
+            Dxtrav = [_af_invert(x) for x in Dxtrav]
+        # compute the orbit of p_i
+        for ii in range(num_types):
+            if p_i in dumx[ii]:
+                # the orbit is made by all the indices in dum[ii]
+                if sym[ii] is not None:
+                    deltap = dumx[ii]
+                else:
+                    # the orbit is made by all the even indices if p_i
+                    # is even, by all the odd indices if p_i is odd
+                    p_i_index = dumx[ii].index(p_i) % 2
+                    deltap = dumx[ii][p_i_index::2]
+                break
+        else:
+            deltap = [p_i]
+        TAB1 = []
+        while TAB:
+            s, d, h = TAB.pop()
+            if min(md[h[x]] for x in deltab) != p_i:
+                continue
+            deltab1 = [x for x in deltab if md[h[x]] == p_i]
+            # NEXT = s*deltab1 intersection (d*g)**-1*deltap
+            dg = _af_rmul(d, g)
+            dginv = _af_invert(dg)
+            sdeltab = [s[x] for x in deltab1]
+            gdeltap = [dginv[x] for x in deltap]
+            NEXT = [x for x in sdeltab if x in gdeltap]
+            # d, s satisfy
+            # d*g*s*base[i-1] = p_{i-1}; using the stabilizers
+            # d*g*s*S_{base[0],...,base[i-1]}*base[i-1] =
+            # D_{p_0,...,p_{i-1}}*p_{i-1}
+            # so that to find d1, s1 satisfying d1*g*s1*b = p_i
+            # one can look for dx in D_{p_0,...,p_{i-1}} and
+            # sx in S_{base[0],...,base[i-1]}
+            # d1 = dx*d; s1 = s*sx
+            # d1*g*s1*b = dx*d*g*s*sx*b = p_i
+            for j in NEXT:
+                if testb:
+                    # solve s1*b = j with s1 = s*sx for some element sx
+                    # of the stabilizer of ..., base[i-1]
+                    # sx*b = s**-1*j; sx = _trace_S(s, j,...)
+                    # s1 = s*trace_S(s**-1*j,...)
+                    s1 = _trace_S(s, j, b, S_transversals)
+                    if not s1:
+                        continue
+                    else:
+                        s1 = [s[ix] for ix in s1]
+                else:
+                    s1 = s
+                # assert s1[b] == j  # invariant
+                # solve d1*g*j = p_i with d1 = dx*d for some element dg
+                # of the stabilizer of ..., p_{i-1}
+                # dx**-1*p_i = d*g*j; dx**-1 = trace_D(d*g*j,...)
+                # d1 = trace_D(d*g*j,...)**-1*d
+                # to save an inversion in the inner loop; notice we did
+                # Dxtrav = [perm_af_invert(x) for x in Dxtrav] out of the loop
+                if Dxtrav:
+                    d1 = _trace_D(dg[j], p_i, Dxtrav)
+                    if not d1:
+                        continue
+                else:
+                    if p_i != dg[j]:
+                        continue
+                    d1 = idn
+                assert d1[dg[j]] == p_i  # invariant
+                d1 = [d1[ix] for ix in d]
+                h1 = [d1[g[ix]] for ix in s1]
+                # assert h1[b] == p_i  # invariant
+                TAB1.append((s1, d1, h1))
+
+        # if TAB contains equal permutations, keep only one of them;
+        # if TAB contains equal permutations up to the sign, return 0
+        TAB1.sort(key=lambda x: x[-1])
+        prev = [0] * size
+        while TAB1:
+            s, d, h = TAB1.pop()
+            if h[:-2] == prev[:-2]:
+                if h[-1] != prev[-1]:
+                    return 0
+            else:
+                TAB.append((s, d, h))
+            prev = h
+
+        # stabilize the SGS
+        sgensx = [h for h in sgensx if h[b] == b]
+        if b in b_S:
+            b_S.remove(b)
+        _dumx_remove(dumx, dumx_flat, p_i)
+        dsgsx = []
+        for i in range(num_types):
+            dsgsx.extend(dummy_sgs(dumx[i], sym[i], num_dummies))
+    return TAB[0][-1]
+
+
+def canonical_free(base, gens, g, num_free):
+    """
+    Canonicalization of a tensor with respect to free indices
+    choosing the minimum with respect to lexicographical ordering
+    in the free indices.
+
+    Explanation
+    ===========
+
+    ``base``, ``gens``  BSGS for slot permutation group
+    ``g``               permutation representing the tensor
+    ``num_free``        number of free indices
+    The indices must be ordered with first the free indices
+
+    See explanation in double_coset_can_rep
+    The algorithm is a variation of the one given in [2].
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics import Permutation
+    >>> from sympy.combinatorics.tensor_can import canonical_free
+    >>> gens = [[1, 0, 2, 3, 5, 4], [2, 3, 0, 1, 4, 5],[0, 1, 3, 2, 5, 4]]
+    >>> gens = [Permutation(h) for h in gens]
+    >>> base = [0, 2]
+    >>> g = Permutation([2, 1, 0, 3, 4, 5])
+    >>> canonical_free(base, gens, g, 4)
+    [0, 3, 1, 2, 5, 4]
+
+    Consider the product of Riemann tensors
+    ``T = R^{a}_{d0}^{d1,d2}*R_{d2,d1}^{d0,b}``
+    The order of the indices is ``[a, b, d0, -d0, d1, -d1, d2, -d2]``
+    The permutation corresponding to the tensor is
+    ``g = [0, 3, 4, 6, 7, 5, 2, 1, 8, 9]``
+
+    In particular ``a`` is position ``0``, ``b`` is in position ``9``.
+    Use the slot symmetries to get `T` is a form which is the minimal
+    in lexicographic order in the free indices ``a`` and ``b``, e.g.
+    ``-R^{a}_{d0}^{d1,d2}*R^{b,d0}_{d2,d1}`` corresponding to
+    ``[0, 3, 4, 6, 1, 2, 7, 5, 9, 8]``
+
+    >>> from sympy.combinatorics.tensor_can import riemann_bsgs, tensor_gens
+    >>> base, gens = riemann_bsgs
+    >>> size, sbase, sgens = tensor_gens(base, gens, [[], []], 0)
+    >>> g = Permutation([0, 3, 4, 6, 7, 5, 2, 1, 8, 9])
+    >>> canonical_free(sbase, [Permutation(h) for h in sgens], g, 2)
+    [0, 3, 4, 6, 1, 2, 7, 5, 9, 8]
+    """
+    g = g.array_form
+    size = len(g)
+    if not base:
+        return g[:]
+
+    transversals = get_transversals(base, gens)
+    for x in sorted(g[:-2]):
+        if x not in base:
+            base.append(x)
+    h = g
+    for transv in transversals:
+        h_i = [size]*num_free
+        # find the element s in transversals[i] such that
+        # _af_rmul(h, s) has its free elements with the lowest position in h
+        s = None
+        for sk in transv.values():
+            h1 = _af_rmul(h, sk)
+            hi = [h1.index(ix) for ix in range(num_free)]
+            if hi < h_i:
+                h_i = hi
+                s = sk
+        if s:
+            h = _af_rmul(h, s)
+    return h
+
+
+def _get_map_slots(size, fixed_slots):
+    res = list(range(size))
+    pos = 0
+    for i in range(size):
+        if i in fixed_slots:
+            continue
+        res[i] = pos
+        pos += 1
+    return res
+
+
+def _lift_sgens(size, fixed_slots, free, s):
+    a = []
+    j = k = 0
+    fd = list(zip(fixed_slots, free))
+    fd = [y for x, y in sorted(fd)]
+    num_free = len(free)
+    for i in range(size):
+        if i in fixed_slots:
+            a.append(fd[k])
+            k += 1
+        else:
+            a.append(s[j] + num_free)
+            j += 1
+    return a
+
+
+def canonicalize(g, dummies, msym, *v):
+    """
+    canonicalize tensor formed by tensors
+
+    Parameters
+    ==========
+
+    g : permutation representing the tensor
+
+    dummies : list representing the dummy indices
+      it can be a list of dummy indices of the same type
+      or a list of lists of dummy indices, one list for each
+      type of index;
+      the dummy indices must come after the free indices,
+      and put in order contravariant, covariant
+      [d0, -d0, d1,-d1,...]
+
+    msym :  symmetry of the metric(s)
+        it can be an integer or a list;
+        in the first case it is the symmetry of the dummy index metric;
+        in the second case it is the list of the symmetries of the
+        index metric for each type
+
+    v : list, (base_i, gens_i, n_i, sym_i) for tensors of type `i`
+
+    base_i, gens_i : BSGS for tensors of this type.
+        The BSGS should have minimal base under lexicographic ordering;
+        if not, an attempt is made do get the minimal BSGS;
+        in case of failure,
+        canonicalize_naive is used, which is much slower.
+
+    n_i :    number of tensors of type `i`.
+
+    sym_i :  symmetry under exchange of component tensors of type `i`.
+
+        Both for msym and sym_i the cases are
+            * None  no symmetry
+            * 0     commuting
+            * 1     anticommuting
+
+    Returns
+    =======
+
+    0 if the tensor is zero, else return the array form of
+    the permutation representing the canonical form of the tensor.
+
+    Algorithm
+    =========
+
+    First one uses canonical_free to get the minimum tensor under
+    lexicographic order, using only the slot symmetries.
+    If the component tensors have not minimal BSGS, it is attempted
+    to find it; if the attempt fails canonicalize_naive
+    is used instead.
+
+    Compute the residual slot symmetry keeping fixed the free indices
+    using tensor_gens(base, gens, list_free_indices, sym).
+
+    Reduce the problem eliminating the free indices.
+
+    Then use double_coset_can_rep and lift back the result reintroducing
+    the free indices.
+
+    Examples
+    ========
+
+    one type of index with commuting metric;
+
+    `A_{a b}` and `B_{a b}` antisymmetric and commuting
+
+    `T = A_{d0 d1} * B^{d0}{}_{d2} * B^{d2 d1}`
+
+    `ord = [d0,-d0,d1,-d1,d2,-d2]` order of the indices
+
+    g = [1, 3, 0, 5, 4, 2, 6, 7]
+
+    `T_c = 0`
+
+    >>> from sympy.combinatorics.tensor_can import get_symmetric_group_sgs, canonicalize, bsgs_direct_product
+    >>> from sympy.combinatorics import Permutation
+    >>> base2a, gens2a = get_symmetric_group_sgs(2, 1)
+    >>> t0 = (base2a, gens2a, 1, 0)
+    >>> t1 = (base2a, gens2a, 2, 0)
+    >>> g = Permutation([1, 3, 0, 5, 4, 2, 6, 7])
+    >>> canonicalize(g, range(6), 0, t0, t1)
+    0
+
+    same as above, but with `B_{a b}` anticommuting
+
+    `T_c = -A^{d0 d1} * B_{d0}{}^{d2} * B_{d1 d2}`
+
+    can = [0,2,1,4,3,5,7,6]
+
+    >>> t1 = (base2a, gens2a, 2, 1)
+    >>> canonicalize(g, range(6), 0, t0, t1)
+    [0, 2, 1, 4, 3, 5, 7, 6]
+
+    two types of indices `[a,b,c,d,e,f]` and `[m,n]`, in this order,
+    both with commuting metric
+
+    `f^{a b c}` antisymmetric, commuting
+
+    `A_{m a}` no symmetry, commuting
+
+    `T = f^c{}_{d a} * f^f{}_{e b} * A_m{}^d * A^{m b} * A_n{}^a * A^{n e}`
+
+    ord = [c,f,a,-a,b,-b,d,-d,e,-e,m,-m,n,-n]
+
+    g = [0,7,3, 1,9,5, 11,6, 10,4, 13,2, 12,8, 14,15]
+
+    The canonical tensor is
+    `T_c = -f^{c a b} * f^{f d e} * A^m{}_a * A_{m d} * A^n{}_b * A_{n e}`
+
+    can = [0,2,4, 1,6,8, 10,3, 11,7, 12,5, 13,9, 15,14]
+
+    >>> base_f, gens_f = get_symmetric_group_sgs(3, 1)
+    >>> base1, gens1 = get_symmetric_group_sgs(1)
+    >>> base_A, gens_A = bsgs_direct_product(base1, gens1, base1, gens1)
+    >>> t0 = (base_f, gens_f, 2, 0)
+    >>> t1 = (base_A, gens_A, 4, 0)
+    >>> dummies = [range(2, 10), range(10, 14)]
+    >>> g = Permutation([0, 7, 3, 1, 9, 5, 11, 6, 10, 4, 13, 2, 12, 8, 14, 15])
+    >>> canonicalize(g, dummies, [0, 0], t0, t1)
+    [0, 2, 4, 1, 6, 8, 10, 3, 11, 7, 12, 5, 13, 9, 15, 14]
+    """
+    from sympy.combinatorics.testutil import canonicalize_naive
+    if not isinstance(msym, list):
+        if msym not in (0, 1, None):
+            raise ValueError('msym must be 0, 1 or None')
+        num_types = 1
+    else:
+        num_types = len(msym)
+        if not all(msymx in (0, 1, None) for msymx in msym):
+            raise ValueError('msym entries must be 0, 1 or None')
+        if len(dummies) != num_types:
+            raise ValueError(
+                'dummies and msym must have the same number of elements')
+    size = g.size
+    num_tensors = 0
+    v1 = []
+    for base_i, gens_i, n_i, sym_i in v:
+        # check that the BSGS is minimal;
+        # this property is used in double_coset_can_rep;
+        # if it is not minimal use canonicalize_naive
+        if not _is_minimal_bsgs(base_i, gens_i):
+            mbsgs = get_minimal_bsgs(base_i, gens_i)
+            if not mbsgs:
+                can = canonicalize_naive(g, dummies, msym, *v)
+                return can
+            base_i, gens_i = mbsgs
+        v1.append((base_i, gens_i, [[]] * n_i, sym_i))
+        num_tensors += n_i
+
+    if num_types == 1 and not isinstance(msym, list):
+        dummies = [dummies]
+        msym = [msym]
+    flat_dummies = []
+    for dumx in dummies:
+        flat_dummies.extend(dumx)
+
+    if flat_dummies and flat_dummies != list(range(flat_dummies[0], flat_dummies[-1] + 1)):
+        raise ValueError('dummies is not valid')
+
+    # slot symmetry of the tensor
+    size1, sbase, sgens = gens_products(*v1)
+    if size != size1:
+        raise ValueError(
+            'g has size %d, generators have size %d' % (size, size1))
+    free = [i for i in range(size - 2) if i not in flat_dummies]
+    num_free = len(free)
+
+    # g1 minimal tensor under slot symmetry
+    g1 = canonical_free(sbase, sgens, g, num_free)
+    if not flat_dummies:
+        return g1
+    # save the sign of g1
+    sign = 0 if g1[-1] == size - 1 else 1
+
+    # the free indices are kept fixed.
+    # Determine free_i, the list of slots of tensors which are fixed
+    # since they are occupied by free indices, which are fixed.
+    start = 0
+    for i, (base_i, gens_i, n_i, sym_i) in enumerate(v):
+        free_i = []
+        len_tens = gens_i[0].size - 2
+        # for each component tensor get a list od fixed islots
+        for j in range(n_i):
+            # get the elements corresponding to the component tensor
+            h = g1[start:(start + len_tens)]
+            fr = []
+            # get the positions of the fixed elements in h
+            for k in free:
+                if k in h:
+                    fr.append(h.index(k))
+            free_i.append(fr)
+            start += len_tens
+        v1[i] = (base_i, gens_i, free_i, sym_i)
+    # BSGS of the tensor with fixed free indices
+    # if tensor_gens fails in gens_product, use canonicalize_naive
+    size, sbase, sgens = gens_products(*v1)
+
+    # reduce the permutations getting rid of the free indices
+    pos_free = [g1.index(x) for x in range(num_free)]
+    size_red = size - num_free
+    g1_red = [x - num_free for x in g1 if x in flat_dummies]
+    if sign:
+        g1_red.extend([size_red - 1, size_red - 2])
+    else:
+        g1_red.extend([size_red - 2, size_red - 1])
+    map_slots = _get_map_slots(size, pos_free)
+    sbase_red = [map_slots[i] for i in sbase if i not in pos_free]
+    sgens_red = [_af_new([map_slots[i] for i in y._array_form if i not in pos_free]) for y in sgens]
+    dummies_red = [[x - num_free for x in y] for y in dummies]
+    transv_red = get_transversals(sbase_red, sgens_red)
+    g1_red = _af_new(g1_red)
+    g2 = double_coset_can_rep(
+        dummies_red, msym, sbase_red, sgens_red, transv_red, g1_red)
+    if g2 == 0:
+        return 0
+    # lift to the case with the free indices
+    g3 = _lift_sgens(size, pos_free, free, g2)
+    return g3
+
+
+def perm_af_direct_product(gens1, gens2, signed=True):
+    """
+    Direct products of the generators gens1 and gens2.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.tensor_can import perm_af_direct_product
+    >>> gens1 = [[1, 0, 2, 3], [0, 1, 3, 2]]
+    >>> gens2 = [[1, 0]]
+    >>> perm_af_direct_product(gens1, gens2, False)
+    [[1, 0, 2, 3, 4, 5], [0, 1, 3, 2, 4, 5], [0, 1, 2, 3, 5, 4]]
+    >>> gens1 = [[1, 0, 2, 3, 5, 4], [0, 1, 3, 2, 4, 5]]
+    >>> gens2 = [[1, 0, 2, 3]]
+    >>> perm_af_direct_product(gens1, gens2, True)
+    [[1, 0, 2, 3, 4, 5, 7, 6], [0, 1, 3, 2, 4, 5, 6, 7], [0, 1, 2, 3, 5, 4, 6, 7]]
+    """
+    gens1 = [list(x) for x in gens1]
+    gens2 = [list(x) for x in gens2]
+    s = 2 if signed else 0
+    n1 = len(gens1[0]) - s
+    n2 = len(gens2[0]) - s
+    start = list(range(n1))
+    end = list(range(n1, n1 + n2))
+    if signed:
+        gens1 = [gen[:-2] + end + [gen[-2] + n2, gen[-1] + n2]
+                 for gen in gens1]
+        gens2 = [start + [x + n1 for x in gen] for gen in gens2]
+    else:
+        gens1 = [gen + end for gen in gens1]
+        gens2 = [start + [x + n1 for x in gen] for gen in gens2]
+
+    res = gens1 + gens2
+
+    return res
+
+
+def bsgs_direct_product(base1, gens1, base2, gens2, signed=True):
+    """
+    Direct product of two BSGS.
+
+    Parameters
+    ==========
+
+    base1 : base of the first BSGS.
+
+    gens1 : strong generating sequence of the first BSGS.
+
+    base2, gens2 : similarly for the second BSGS.
+
+    signed : flag for signed permutations.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.tensor_can import (get_symmetric_group_sgs, bsgs_direct_product)
+    >>> base1, gens1 = get_symmetric_group_sgs(1)
+    >>> base2, gens2 = get_symmetric_group_sgs(2)
+    >>> bsgs_direct_product(base1, gens1, base2, gens2)
+    ([1], [(4)(1 2)])
+    """
+    s = 2 if signed else 0
+    n1 = gens1[0].size - s
+    base = list(base1)
+    base += [x + n1 for x in base2]
+    gens1 = [h._array_form for h in gens1]
+    gens2 = [h._array_form for h in gens2]
+    gens = perm_af_direct_product(gens1, gens2, signed)
+    size = len(gens[0])
+    id_af = list(range(size))
+    gens = [h for h in gens if h != id_af]
+    if not gens:
+        gens = [id_af]
+    return base, [_af_new(h) for h in gens]
+
+
+def get_symmetric_group_sgs(n, antisym=False):
+    """
+    Return base, gens of the minimal BSGS for (anti)symmetric tensor
+
+    Parameters
+    ==========
+
+    n : rank of the tensor
+    antisym : bool
+        ``antisym = False`` symmetric tensor
+        ``antisym = True``  antisymmetric tensor
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.tensor_can import get_symmetric_group_sgs
+    >>> get_symmetric_group_sgs(3)
+    ([0, 1], [(4)(0 1), (4)(1 2)])
+    """
+    if n == 1:
+        return [], [_af_new(list(range(3)))]
+    gens = [Permutation(n - 1)(i, i + 1)._array_form for i in range(n - 1)]
+    if antisym == 0:
+        gens = [x + [n, n + 1] for x in gens]
+    else:
+        gens = [x + [n + 1, n] for x in gens]
+    base = list(range(n - 1))
+    return base, [_af_new(h) for h in gens]
+
+riemann_bsgs = [0, 2], [Permutation(0, 1)(4, 5), Permutation(2, 3)(4, 5),
+                        Permutation(5)(0, 2)(1, 3)]
+
+
+def get_transversals(base, gens):
+    """
+    Return transversals for the group with BSGS base, gens
+    """
+    if not base:
+        return []
+    stabs = _distribute_gens_by_base(base, gens)
+    orbits, transversals = _orbits_transversals_from_bsgs(base, stabs)
+    transversals = [{x: h._array_form for x, h in y.items()} for y in
+                    transversals]
+    return transversals
+
+
+def _is_minimal_bsgs(base, gens):
+    """
+    Check if the BSGS has minimal base under lexigographic order.
+
+    base, gens BSGS
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics import Permutation
+    >>> from sympy.combinatorics.tensor_can import riemann_bsgs, _is_minimal_bsgs
+    >>> _is_minimal_bsgs(*riemann_bsgs)
+    True
+    >>> riemann_bsgs1 = ([2, 0], ([Permutation(5)(0, 1)(4, 5), Permutation(5)(0, 2)(1, 3)]))
+    >>> _is_minimal_bsgs(*riemann_bsgs1)
+    False
+    """
+    base1 = []
+    sgs1 = gens[:]
+    size = gens[0].size
+    for i in range(size):
+        if not all(h._array_form[i] == i for h in sgs1):
+            base1.append(i)
+            sgs1 = [h for h in sgs1 if h._array_form[i] == i]
+    return base1 == base
+
+
+def get_minimal_bsgs(base, gens):
+    """
+    Compute a minimal GSGS
+
+    base, gens BSGS
+
+    If base, gens is a minimal BSGS return it; else return a minimal BSGS
+    if it fails in finding one, it returns None
+
+    TODO: use baseswap in the case in which if it fails in finding a
+    minimal BSGS
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics import Permutation
+    >>> from sympy.combinatorics.tensor_can import get_minimal_bsgs
+    >>> riemann_bsgs1 = ([2, 0], ([Permutation(5)(0, 1)(4, 5), Permutation(5)(0, 2)(1, 3)]))
+    >>> get_minimal_bsgs(*riemann_bsgs1)
+    ([0, 2], [(0 1)(4 5), (5)(0 2)(1 3), (2 3)(4 5)])
+    """
+    G = PermutationGroup(gens)
+    base, gens = G.schreier_sims_incremental()
+    if not _is_minimal_bsgs(base, gens):
+        return None
+    return base, gens
+
+
+def tensor_gens(base, gens, list_free_indices, sym=0):
+    """
+    Returns size, res_base, res_gens BSGS for n tensors of the
+    same type.
+
+    Explanation
+    ===========
+
+    base, gens BSGS for tensors of this type
+    list_free_indices  list of the slots occupied by fixed indices
+                       for each of the tensors
+
+    sym symmetry under commutation of two tensors
+    sym   None  no symmetry
+    sym   0     commuting
+    sym   1     anticommuting
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.tensor_can import tensor_gens, get_symmetric_group_sgs
+
+    two symmetric tensors with 3 indices without free indices
+
+    >>> base, gens = get_symmetric_group_sgs(3)
+    >>> tensor_gens(base, gens, [[], []])
+    (8, [0, 1, 3, 4], [(7)(0 1), (7)(1 2), (7)(3 4), (7)(4 5), (7)(0 3)(1 4)(2 5)])
+
+    two symmetric tensors with 3 indices with free indices in slot 1 and 0
+
+    >>> tensor_gens(base, gens, [[1], [0]])
+    (8, [0, 4], [(7)(0 2), (7)(4 5)])
+
+    four symmetric tensors with 3 indices, two of which with free indices
+
+    """
+    def _get_bsgs(G, base, gens, free_indices):
+        """
+        return the BSGS for G.pointwise_stabilizer(free_indices)
+        """
+        if not free_indices:
+            return base[:], gens[:]
+        else:
+            H = G.pointwise_stabilizer(free_indices)
+            base, sgs = H.schreier_sims_incremental()
+            return base, sgs
+
+    # if not base there is no slot symmetry for the component tensors
+    # if list_free_indices.count([]) < 2 there is no commutation symmetry
+    # so there is no resulting slot symmetry
+    if not base and list_free_indices.count([]) < 2:
+        n = len(list_free_indices)
+        size = gens[0].size
+        size = n * (size - 2) + 2
+        return size, [], [_af_new(list(range(size)))]
+
+    # if any(list_free_indices) one needs to compute the pointwise
+    # stabilizer, so G is needed
+    if any(list_free_indices):
+        G = PermutationGroup(gens)
+    else:
+        G = None
+
+    # no_free list of lists of indices for component tensors without fixed
+    # indices
+    no_free = []
+    size = gens[0].size
+    id_af = list(range(size))
+    num_indices = size - 2
+    if not list_free_indices[0]:
+        no_free.append(list(range(num_indices)))
+    res_base, res_gens = _get_bsgs(G, base, gens, list_free_indices[0])
+    for i in range(1, len(list_free_indices)):
+        base1, gens1 = _get_bsgs(G, base, gens, list_free_indices[i])
+        res_base, res_gens = bsgs_direct_product(res_base, res_gens,
+                                                 base1, gens1, 1)
+        if not list_free_indices[i]:
+            no_free.append(list(range(size - 2, size - 2 + num_indices)))
+        size += num_indices
+    nr = size - 2
+    res_gens = [h for h in res_gens if h._array_form != id_af]
+    # if sym there are no commuting tensors stop here
+    if sym is None or not no_free:
+        if not res_gens:
+            res_gens = [_af_new(id_af)]
+        return size, res_base, res_gens
+
+    # if the component tensors have moinimal BSGS, so is their direct
+    # product P; the slot symmetry group is S = P*C, where C is the group
+    # to (anti)commute the component tensors with no free indices
+    # a stabilizer has the property S_i = P_i*C_i;
+    # the BSGS of P*C has SGS_P + SGS_C and the base is
+    # the ordered union of the bases of P and C.
+    # If P has minimal BSGS, so has S with this base.
+    base_comm = []
+    for i in range(len(no_free) - 1):
+        ind1 = no_free[i]
+        ind2 = no_free[i + 1]
+        a = list(range(ind1[0]))
+        a.extend(ind2)
+        a.extend(ind1)
+        base_comm.append(ind1[0])
+        a.extend(list(range(ind2[-1] + 1, nr)))
+        if sym == 0:
+            a.extend([nr, nr + 1])
+        else:
+            a.extend([nr + 1, nr])
+        res_gens.append(_af_new(a))
+    res_base = list(res_base)
+    # each base is ordered; order the union of the two bases
+    for i in base_comm:
+        if i not in res_base:
+            res_base.append(i)
+    res_base.sort()
+    if not res_gens:
+        res_gens = [_af_new(id_af)]
+
+    return size, res_base, res_gens
+
+
+def gens_products(*v):
+    """
+    Returns size, res_base, res_gens BSGS for n tensors of different types.
+
+    Explanation
+    ===========
+
+    v is a sequence of (base_i, gens_i, free_i, sym_i)
+    where
+    base_i, gens_i  BSGS of tensor of type `i`
+    free_i          list of the fixed slots for each of the tensors
+                    of type `i`; if there are `n_i` tensors of type `i`
+                    and none of them have fixed slots, `free = [[]]*n_i`
+    sym   0 (1) if the tensors of type `i` (anti)commute among themselves
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.tensor_can import get_symmetric_group_sgs, gens_products
+    >>> base, gens = get_symmetric_group_sgs(2)
+    >>> gens_products((base, gens, [[], []], 0))
+    (6, [0, 2], [(5)(0 1), (5)(2 3), (5)(0 2)(1 3)])
+    >>> gens_products((base, gens, [[1], []], 0))
+    (6, [2], [(5)(2 3)])
+    """
+    res_size, res_base, res_gens = tensor_gens(*v[0])
+    for i in range(1, len(v)):
+        size, base, gens = tensor_gens(*v[i])
+        res_base, res_gens = bsgs_direct_product(res_base, res_gens, base,
+                                                 gens, 1)
+    res_size = res_gens[0].size
+    id_af = list(range(res_size))
+    res_gens = [h for h in res_gens if h != id_af]
+    if not res_gens:
+        res_gens = [id_af]
+    return res_size, res_base, res_gens

lib/python3.12/site-packages/sympy/combinatorics/testutil.py

@@ -0,0 +1,357 @@
+from sympy.combinatorics import Permutation
+from sympy.combinatorics.util import _distribute_gens_by_base
+
+rmul = Permutation.rmul
+
+
+def _cmp_perm_lists(first, second):
+    """
+    Compare two lists of permutations as sets.
+
+    Explanation
+    ===========
+
+    This is used for testing purposes. Since the array form of a
+    permutation is currently a list, Permutation is not hashable
+    and cannot be put into a set.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.permutations import Permutation
+    >>> from sympy.combinatorics.testutil import _cmp_perm_lists
+    >>> a = Permutation([0, 2, 3, 4, 1])
+    >>> b = Permutation([1, 2, 0, 4, 3])
+    >>> c = Permutation([3, 4, 0, 1, 2])
+    >>> ls1 = [a, b, c]
+    >>> ls2 = [b, c, a]
+    >>> _cmp_perm_lists(ls1, ls2)
+    True
+
+    """
+    return {tuple(a) for a in first} == \
+           {tuple(a) for a in second}
+
+
+def _naive_list_centralizer(self, other, af=False):
+    from sympy.combinatorics.perm_groups import PermutationGroup
+    """
+    Return a list of elements for the centralizer of a subgroup/set/element.
+
+    Explanation
+    ===========
+
+    This is a brute force implementation that goes over all elements of the
+    group and checks for membership in the centralizer. It is used to
+    test ``.centralizer()`` from ``sympy.combinatorics.perm_groups``.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.testutil import _naive_list_centralizer
+    >>> from sympy.combinatorics.named_groups import DihedralGroup
+    >>> D = DihedralGroup(4)
+    >>> _naive_list_centralizer(D, D)
+    [Permutation([0, 1, 2, 3]), Permutation([2, 3, 0, 1])]
+
+    See Also
+    ========
+
+    sympy.combinatorics.perm_groups.centralizer
+
+    """
+    from sympy.combinatorics.permutations import _af_commutes_with
+    if hasattr(other, 'generators'):
+        elements = list(self.generate_dimino(af=True))
+        gens = [x._array_form for x in other.generators]
+        commutes_with_gens = lambda x: all(_af_commutes_with(x, gen) for gen in gens)
+        centralizer_list = []
+        if not af:
+            for element in elements:
+                if commutes_with_gens(element):
+                    centralizer_list.append(Permutation._af_new(element))
+        else:
+            for element in elements:
+                if commutes_with_gens(element):
+                    centralizer_list.append(element)
+        return centralizer_list
+    elif hasattr(other, 'getitem'):
+        return _naive_list_centralizer(self, PermutationGroup(other), af)
+    elif hasattr(other, 'array_form'):
+        return _naive_list_centralizer(self, PermutationGroup([other]), af)
+
+
+def _verify_bsgs(group, base, gens):
+    """
+    Verify the correctness of a base and strong generating set.
+
+    Explanation
+    ===========
+
+    This is a naive implementation using the definition of a base and a strong
+    generating set relative to it. There are other procedures for
+    verifying a base and strong generating set, but this one will
+    serve for more robust testing.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.named_groups import AlternatingGroup
+    >>> from sympy.combinatorics.testutil import _verify_bsgs
+    >>> A = AlternatingGroup(4)
+    >>> A.schreier_sims()
+    >>> _verify_bsgs(A, A.base, A.strong_gens)
+    True
+
+    See Also
+    ========
+
+    sympy.combinatorics.perm_groups.PermutationGroup.schreier_sims
+
+    """
+    from sympy.combinatorics.perm_groups import PermutationGroup
+    strong_gens_distr = _distribute_gens_by_base(base, gens)
+    current_stabilizer = group
+    for i in range(len(base)):
+        candidate = PermutationGroup(strong_gens_distr[i])
+        if current_stabilizer.order() != candidate.order():
+            return False
+        current_stabilizer = current_stabilizer.stabilizer(base[i])
+    if current_stabilizer.order() != 1:
+        return False
+    return True
+
+
+def _verify_centralizer(group, arg, centr=None):
+    """
+    Verify the centralizer of a group/set/element inside another group.
+
+    This is used for testing ``.centralizer()`` from
+    ``sympy.combinatorics.perm_groups``
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.named_groups import (SymmetricGroup,
+    ... AlternatingGroup)
+    >>> from sympy.combinatorics.perm_groups import PermutationGroup
+    >>> from sympy.combinatorics.permutations import Permutation
+    >>> from sympy.combinatorics.testutil import _verify_centralizer
+    >>> S = SymmetricGroup(5)
+    >>> A = AlternatingGroup(5)
+    >>> centr = PermutationGroup([Permutation([0, 1, 2, 3, 4])])
+    >>> _verify_centralizer(S, A, centr)
+    True
+
+    See Also
+    ========
+
+    _naive_list_centralizer,
+    sympy.combinatorics.perm_groups.PermutationGroup.centralizer,
+    _cmp_perm_lists
+
+    """
+    if centr is None:
+        centr = group.centralizer(arg)
+    centr_list = list(centr.generate_dimino(af=True))
+    centr_list_naive = _naive_list_centralizer(group, arg, af=True)
+    return _cmp_perm_lists(centr_list, centr_list_naive)
+
+
+def _verify_normal_closure(group, arg, closure=None):
+    from sympy.combinatorics.perm_groups import PermutationGroup
+    """
+    Verify the normal closure of a subgroup/subset/element in a group.
+
+    This is used to test
+    sympy.combinatorics.perm_groups.PermutationGroup.normal_closure
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.named_groups import (SymmetricGroup,
+    ... AlternatingGroup)
+    >>> from sympy.combinatorics.testutil import _verify_normal_closure
+    >>> S = SymmetricGroup(3)
+    >>> A = AlternatingGroup(3)
+    >>> _verify_normal_closure(S, A, closure=A)
+    True
+
+    See Also
+    ========
+
+    sympy.combinatorics.perm_groups.PermutationGroup.normal_closure
+
+    """
+    if closure is None:
+        closure = group.normal_closure(arg)
+    conjugates = set()
+    if hasattr(arg, 'generators'):
+        subgr_gens = arg.generators
+    elif hasattr(arg, '__getitem__'):
+        subgr_gens = arg
+    elif hasattr(arg, 'array_form'):
+        subgr_gens = [arg]
+    for el in group.generate_dimino():
+        conjugates.update(gen ^ el for gen in subgr_gens)
+    naive_closure = PermutationGroup(list(conjugates))
+    return closure.is_subgroup(naive_closure)
+
+
+def canonicalize_naive(g, dummies, sym, *v):
+    """
+    Canonicalize tensor formed by tensors of the different types.
+
+    Explanation
+    ===========
+
+    sym_i symmetry under exchange of two component tensors of type `i`
+          None  no symmetry
+          0     commuting
+          1     anticommuting
+
+    Parameters
+    ==========
+
+    g : Permutation representing the tensor.
+    dummies : List of dummy indices.
+    msym : Symmetry of the metric.
+    v : A list of (base_i, gens_i, n_i, sym_i) for tensors of type `i`.
+        base_i, gens_i BSGS for tensors of this type
+        n_i  number of tensors of type `i`
+
+    Returns
+    =======
+
+    Returns 0 if the tensor is zero, else returns the array form of
+    the permutation representing the canonical form of the tensor.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.testutil import canonicalize_naive
+    >>> from sympy.combinatorics.tensor_can import get_symmetric_group_sgs
+    >>> from sympy.combinatorics import Permutation
+    >>> g = Permutation([1, 3, 2, 0, 4, 5])
+    >>> base2, gens2 = get_symmetric_group_sgs(2)
+    >>> canonicalize_naive(g, [2, 3], 0, (base2, gens2, 2, 0))
+    [0, 2, 1, 3, 4, 5]
+    """
+    from sympy.combinatorics.perm_groups import PermutationGroup
+    from sympy.combinatorics.tensor_can import gens_products, dummy_sgs
+    from sympy.combinatorics.permutations import _af_rmul
+    v1 = []
+    for i in range(len(v)):
+        base_i, gens_i, n_i, sym_i = v[i]
+        v1.append((base_i, gens_i, [[]]*n_i, sym_i))
+    size, sbase, sgens = gens_products(*v1)
+    dgens = dummy_sgs(dummies, sym, size-2)
+    if isinstance(sym, int):
+        num_types = 1
+        dummies = [dummies]
+        sym = [sym]
+    else:
+        num_types = len(sym)
+    dgens = []
+    for i in range(num_types):
+        dgens.extend(dummy_sgs(dummies[i], sym[i], size - 2))
+    S = PermutationGroup(sgens)
+    D = PermutationGroup([Permutation(x) for x in dgens])
+    dlist = list(D.generate(af=True))
+    g = g.array_form
+    st = set()
+    for s in S.generate(af=True):
+        h = _af_rmul(g, s)
+        for d in dlist:
+            q = tuple(_af_rmul(d, h))
+            st.add(q)
+    a = list(st)
+    a.sort()
+    prev = (0,)*size
+    for h in a:
+        if h[:-2] == prev[:-2]:
+            if h[-1] != prev[-1]:
+                return 0
+        prev = h
+    return list(a[0])
+
+
+def graph_certificate(gr):
+    """
+    Return a certificate for the graph
+
+    Parameters
+    ==========
+
+    gr : adjacency list
+
+    Explanation
+    ===========
+
+    The graph is assumed to be unoriented and without
+    external lines.
+
+    Associate to each vertex of the graph a symmetric tensor with
+    number of indices equal to the degree of the vertex; indices
+    are contracted when they correspond to the same line of the graph.
+    The canonical form of the tensor gives a certificate for the graph.
+
+    This is not an efficient algorithm to get the certificate of a graph.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.testutil import graph_certificate
+    >>> gr1 = {0:[1, 2, 3, 5], 1:[0, 2, 4], 2:[0, 1, 3, 4], 3:[0, 2, 4], 4:[1, 2, 3, 5], 5:[0, 4]}
+    >>> gr2 = {0:[1, 5], 1:[0, 2, 3, 4], 2:[1, 3, 5], 3:[1, 2, 4, 5], 4:[1, 3, 5], 5:[0, 2, 3, 4]}
+    >>> c1 = graph_certificate(gr1)
+    >>> c2 = graph_certificate(gr2)
+    >>> c1
+    [0, 2, 4, 6, 1, 8, 10, 12, 3, 14, 16, 18, 5, 9, 15, 7, 11, 17, 13, 19, 20, 21]
+    >>> c1 == c2
+    True
+    """
+    from sympy.combinatorics.permutations import _af_invert
+    from sympy.combinatorics.tensor_can import get_symmetric_group_sgs, canonicalize
+    items = list(gr.items())
+    items.sort(key=lambda x: len(x[1]), reverse=True)
+    pvert = [x[0] for x in items]
+    pvert = _af_invert(pvert)
+
+    # the indices of the tensor are twice the number of lines of the graph
+    num_indices = 0
+    for v, neigh in items:
+        num_indices += len(neigh)
+    # associate to each vertex its indices; for each line
+    # between two vertices assign the
+    # even index to the vertex which comes first in items,
+    # the odd index to the other vertex
+    vertices = [[] for i in items]
+    i = 0
+    for v, neigh in items:
+        for v2 in neigh:
+            if pvert[v] < pvert[v2]:
+                vertices[pvert[v]].append(i)
+                vertices[pvert[v2]].append(i+1)
+                i += 2
+    g = []
+    for v in vertices:
+        g.extend(v)
+    assert len(g) == num_indices
+    g += [num_indices, num_indices + 1]
+    size = num_indices + 2
+    assert sorted(g) == list(range(size))
+    g = Permutation(g)
+    vlen = [0]*(len(vertices[0])+1)
+    for neigh in vertices:
+        vlen[len(neigh)] += 1
+    v = []
+    for i in range(len(vlen)):
+        n = vlen[i]
+        if n:
+            base, gens = get_symmetric_group_sgs(i)
+            v.append((base, gens, n, 0))
+    v.reverse()
+    dummies = list(range(num_indices))
+    can = canonicalize(g, dummies, 0, *v)
+    return can

lib/python3.12/site-packages/sympy/combinatorics/util.py

@@ -0,0 +1,532 @@
+from sympy.combinatorics.permutations import Permutation, _af_invert, _af_rmul
+from sympy.ntheory import isprime
+
+rmul = Permutation.rmul
+_af_new = Permutation._af_new
+
+############################################
+#
+# Utilities for computational group theory
+#
+############################################
+
+
+def _base_ordering(base, degree):
+    r"""
+    Order `\{0, 1, \dots, n-1\}` so that base points come first and in order.
+
+    Parameters
+    ==========
+
+    base : the base
+    degree : the degree of the associated permutation group
+
+    Returns
+    =======
+
+    A list ``base_ordering`` such that ``base_ordering[point]`` is the
+    number of ``point`` in the ordering.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics import SymmetricGroup
+    >>> from sympy.combinatorics.util import _base_ordering
+    >>> S = SymmetricGroup(4)
+    >>> S.schreier_sims()
+    >>> _base_ordering(S.base, S.degree)
+    [0, 1, 2, 3]
+
+    Notes
+    =====
+
+    This is used in backtrack searches, when we define a relation `\ll` on
+    the underlying set for a permutation group of degree `n`,
+    `\{0, 1, \dots, n-1\}`, so that if `(b_1, b_2, \dots, b_k)` is a base we
+    have `b_i \ll b_j` whenever `i<j` and `b_i \ll a` for all
+    `i\in\{1,2, \dots, k\}` and `a` is not in the base. The idea is developed
+    and applied to backtracking algorithms in [1], pp.108-132. The points
+    that are not in the base are taken in increasing order.
+
+    References
+    ==========
+
+    .. [1] Holt, D., Eick, B., O'Brien, E.
+           "Handbook of computational group theory"
+
+    """
+    base_len = len(base)
+    ordering = [0]*degree
+    for i in range(base_len):
+        ordering[base[i]] = i
+    current = base_len
+    for i in range(degree):
+        if i not in base:
+            ordering[i] = current
+            current += 1
+    return ordering
+
+
+def _check_cycles_alt_sym(perm):
+    """
+    Checks for cycles of prime length p with n/2 < p < n-2.
+
+    Explanation
+    ===========
+
+    Here `n` is the degree of the permutation. This is a helper function for
+    the function is_alt_sym from sympy.combinatorics.perm_groups.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.util import _check_cycles_alt_sym
+    >>> from sympy.combinatorics import Permutation
+    >>> a = Permutation([[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10], [11, 12]])
+    >>> _check_cycles_alt_sym(a)
+    False
+    >>> b = Permutation([[0, 1, 2, 3, 4, 5, 6], [7, 8, 9, 10]])
+    >>> _check_cycles_alt_sym(b)
+    True
+
+    See Also
+    ========
+
+    sympy.combinatorics.perm_groups.PermutationGroup.is_alt_sym
+
+    """
+    n = perm.size
+    af = perm.array_form
+    current_len = 0
+    total_len = 0
+    used = set()
+    for i in range(n//2):
+        if i not in used and i < n//2 - total_len:
+            current_len = 1
+            used.add(i)
+            j = i
+            while af[j] != i:
+                current_len += 1
+                j = af[j]
+                used.add(j)
+            total_len += current_len
+            if current_len > n//2 and current_len < n - 2 and isprime(current_len):
+                return True
+    return False
+
+
+def _distribute_gens_by_base(base, gens):
+    r"""
+    Distribute the group elements ``gens`` by membership in basic stabilizers.
+
+    Explanation
+    ===========
+
+    Notice that for a base `(b_1, b_2, \dots, b_k)`, the basic stabilizers
+    are defined as `G^{(i)} = G_{b_1, \dots, b_{i-1}}` for
+    `i \in\{1, 2, \dots, k\}`.
+
+    Parameters
+    ==========
+
+    base : a sequence of points in `\{0, 1, \dots, n-1\}`
+    gens : a list of elements of a permutation group of degree `n`.
+
+    Returns
+    =======
+    list
+        List of length `k`, where `k` is the length of *base*. The `i`-th entry
+        contains those elements in *gens* which fix the first `i` elements of
+        *base* (so that the `0`-th entry is equal to *gens* itself). If no
+        element fixes the first `i` elements of *base*, the `i`-th element is
+        set to a list containing the identity element.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.named_groups import DihedralGroup
+    >>> from sympy.combinatorics.util import _distribute_gens_by_base
+    >>> D = DihedralGroup(3)
+    >>> D.schreier_sims()
+    >>> D.strong_gens
+    [(0 1 2), (0 2), (1 2)]
+    >>> D.base
+    [0, 1]
+    >>> _distribute_gens_by_base(D.base, D.strong_gens)
+    [[(0 1 2), (0 2), (1 2)],
+     [(1 2)]]
+
+    See Also
+    ========
+
+    _strong_gens_from_distr, _orbits_transversals_from_bsgs,
+    _handle_precomputed_bsgs
+
+    """
+    base_len = len(base)
+    degree = gens[0].size
+    stabs = [[] for _ in range(base_len)]
+    max_stab_index = 0
+    for gen in gens:
+        j = 0
+        while j < base_len - 1 and gen._array_form[base[j]] == base[j]:
+            j += 1
+        if j > max_stab_index:
+            max_stab_index = j
+        for k in range(j + 1):
+            stabs[k].append(gen)
+    for i in range(max_stab_index + 1, base_len):
+        stabs[i].append(_af_new(list(range(degree))))
+    return stabs
+
+
+def _handle_precomputed_bsgs(base, strong_gens, transversals=None,
+                             basic_orbits=None, strong_gens_distr=None):
+    """
+    Calculate BSGS-related structures from those present.
+
+    Explanation
+    ===========
+
+    The base and strong generating set must be provided; if any of the
+    transversals, basic orbits or distributed strong generators are not
+    provided, they will be calculated from the base and strong generating set.
+
+    Parameters
+    ==========
+
+    base : the base
+    strong_gens : the strong generators
+    transversals : basic transversals
+    basic_orbits : basic orbits
+    strong_gens_distr : strong generators distributed by membership in basic stabilizers
+
+    Returns
+    =======
+
+    (transversals, basic_orbits, strong_gens_distr)
+        where *transversals* are the basic transversals, *basic_orbits* are the
+        basic orbits, and *strong_gens_distr* are the strong generators distributed
+        by membership in basic stabilizers.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.named_groups import DihedralGroup
+    >>> from sympy.combinatorics.util import _handle_precomputed_bsgs
+    >>> D = DihedralGroup(3)
+    >>> D.schreier_sims()
+    >>> _handle_precomputed_bsgs(D.base, D.strong_gens,
+    ... basic_orbits=D.basic_orbits)
+    ([{0: (2), 1: (0 1 2), 2: (0 2)}, {1: (2), 2: (1 2)}], [[0, 1, 2], [1, 2]], [[(0 1 2), (0 2), (1 2)], [(1 2)]])
+
+    See Also
+    ========
+
+    _orbits_transversals_from_bsgs, _distribute_gens_by_base
+
+    """
+    if strong_gens_distr is None:
+        strong_gens_distr = _distribute_gens_by_base(base, strong_gens)
+    if transversals is None:
+        if basic_orbits is None:
+            basic_orbits, transversals = \
+                _orbits_transversals_from_bsgs(base, strong_gens_distr)
+        else:
+            transversals = \
+                _orbits_transversals_from_bsgs(base, strong_gens_distr,
+                                           transversals_only=True)
+    else:
+        if basic_orbits is None:
+            base_len = len(base)
+            basic_orbits = [None]*base_len
+            for i in range(base_len):
+                basic_orbits[i] = list(transversals[i].keys())
+    return transversals, basic_orbits, strong_gens_distr
+
+
+def _orbits_transversals_from_bsgs(base, strong_gens_distr,
+                                   transversals_only=False, slp=False):
+    """
+    Compute basic orbits and transversals from a base and strong generating set.
+
+    Explanation
+    ===========
+
+    The generators are provided as distributed across the basic stabilizers.
+    If the optional argument ``transversals_only`` is set to True, only the
+    transversals are returned.
+
+    Parameters
+    ==========
+
+    base : The base.
+    strong_gens_distr : Strong generators distributed by membership in basic stabilizers.
+    transversals_only : bool, default: False
+        A flag switching between returning only the
+        transversals and both orbits and transversals.
+    slp : bool, default: False
+        If ``True``, return a list of dictionaries containing the
+        generator presentations of the elements of the transversals,
+        i.e. the list of indices of generators from ``strong_gens_distr[i]``
+        such that their product is the relevant transversal element.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics import SymmetricGroup
+    >>> from sympy.combinatorics.util import _distribute_gens_by_base
+    >>> S = SymmetricGroup(3)
+    >>> S.schreier_sims()
+    >>> strong_gens_distr = _distribute_gens_by_base(S.base, S.strong_gens)
+    >>> (S.base, strong_gens_distr)
+    ([0, 1], [[(0 1 2), (2)(0 1), (1 2)], [(1 2)]])
+
+    See Also
+    ========
+
+    _distribute_gens_by_base, _handle_precomputed_bsgs
+
+    """
+    from sympy.combinatorics.perm_groups import _orbit_transversal
+    base_len = len(base)
+    degree = strong_gens_distr[0][0].size
+    transversals = [None]*base_len
+    slps = [None]*base_len
+    if transversals_only is False:
+        basic_orbits = [None]*base_len
+    for i in range(base_len):
+        transversals[i], slps[i] = _orbit_transversal(degree, strong_gens_distr[i],
+                                 base[i], pairs=True, slp=True)
+        transversals[i] = dict(transversals[i])
+        if transversals_only is False:
+            basic_orbits[i] = list(transversals[i].keys())
+    if transversals_only:
+        return transversals
+    else:
+        if not slp:
+            return basic_orbits, transversals
+        return basic_orbits, transversals, slps
+
+
+def _remove_gens(base, strong_gens, basic_orbits=None, strong_gens_distr=None):
+    """
+    Remove redundant generators from a strong generating set.
+
+    Parameters
+    ==========
+
+    base : a base
+    strong_gens : a strong generating set relative to *base*
+    basic_orbits : basic orbits
+    strong_gens_distr : strong generators distributed by membership in basic stabilizers
+
+    Returns
+    =======
+
+    A strong generating set with respect to ``base`` which is a subset of
+    ``strong_gens``.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics import SymmetricGroup
+    >>> from sympy.combinatorics.util import _remove_gens
+    >>> from sympy.combinatorics.testutil import _verify_bsgs
+    >>> S = SymmetricGroup(15)
+    >>> base, strong_gens = S.schreier_sims_incremental()
+    >>> new_gens = _remove_gens(base, strong_gens)
+    >>> len(new_gens)
+    14
+    >>> _verify_bsgs(S, base, new_gens)
+    True
+
+    Notes
+    =====
+
+    This procedure is outlined in [1],p.95.
+
+    References
+    ==========
+
+    .. [1] Holt, D., Eick, B., O'Brien, E.
+           "Handbook of computational group theory"
+
+    """
+    from sympy.combinatorics.perm_groups import _orbit
+    base_len = len(base)
+    degree = strong_gens[0].size
+    if strong_gens_distr is None:
+        strong_gens_distr = _distribute_gens_by_base(base, strong_gens)
+    if basic_orbits is None:
+        basic_orbits = []
+        for i in range(base_len):
+            basic_orbit = _orbit(degree, strong_gens_distr[i], base[i])
+            basic_orbits.append(basic_orbit)
+    strong_gens_distr.append([])
+    res = strong_gens[:]
+    for i in range(base_len - 1, -1, -1):
+        gens_copy = strong_gens_distr[i][:]
+        for gen in strong_gens_distr[i]:
+            if gen not in strong_gens_distr[i + 1]:
+                temp_gens = gens_copy[:]
+                temp_gens.remove(gen)
+                if temp_gens == []:
+                    continue
+                temp_orbit = _orbit(degree, temp_gens, base[i])
+                if temp_orbit == basic_orbits[i]:
+                    gens_copy.remove(gen)
+                    res.remove(gen)
+    return res
+
+
+def _strip(g, base, orbits, transversals):
+    """
+    Attempt to decompose a permutation using a (possibly partial) BSGS
+    structure.
+
+    Explanation
+    ===========
+
+    This is done by treating the sequence ``base`` as an actual base, and
+    the orbits ``orbits`` and transversals ``transversals`` as basic orbits and
+    transversals relative to it.
+
+    This process is called "sifting". A sift is unsuccessful when a certain
+    orbit element is not found or when after the sift the decomposition
+    does not end with the identity element.
+
+    The argument ``transversals`` is a list of dictionaries that provides
+    transversal elements for the orbits ``orbits``.
+
+    Parameters
+    ==========
+
+    g : permutation to be decomposed
+    base : sequence of points
+    orbits : list
+        A list in which the ``i``-th entry is an orbit of ``base[i]``
+        under some subgroup of the pointwise stabilizer of `
+        `base[0], base[1], ..., base[i - 1]``. The groups themselves are implicit
+        in this function since the only information we need is encoded in the orbits
+        and transversals
+    transversals : list
+        A list of orbit transversals associated with the orbits *orbits*.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics import Permutation, SymmetricGroup
+    >>> from sympy.combinatorics.util import _strip
+    >>> S = SymmetricGroup(5)
+    >>> S.schreier_sims()
+    >>> g = Permutation([0, 2, 3, 1, 4])
+    >>> _strip(g, S.base, S.basic_orbits, S.basic_transversals)
+    ((4), 5)
+
+    Notes
+    =====
+
+    The algorithm is described in [1],pp.89-90. The reason for returning
+    both the current state of the element being decomposed and the level
+    at which the sifting ends is that they provide important information for
+    the randomized version of the Schreier-Sims algorithm.
+
+    References
+    ==========
+
+    .. [1] Holt, D., Eick, B., O'Brien, E."Handbook of computational group theory"
+
+    See Also
+    ========
+
+    sympy.combinatorics.perm_groups.PermutationGroup.schreier_sims
+    sympy.combinatorics.perm_groups.PermutationGroup.schreier_sims_random
+
+    """
+    h = g._array_form
+    base_len = len(base)
+    for i in range(base_len):
+        beta = h[base[i]]
+        if beta == base[i]:
+            continue
+        if beta not in orbits[i]:
+            return _af_new(h), i + 1
+        u = transversals[i][beta]._array_form
+        h = _af_rmul(_af_invert(u), h)
+    return _af_new(h), base_len + 1
+
+
+def _strip_af(h, base, orbits, transversals, j, slp=[], slps={}):
+    """
+    optimized _strip, with h, transversals and result in array form
+    if the stripped elements is the identity, it returns False, base_len + 1
+
+    j    h[base[i]] == base[i] for i <= j
+
+    """
+    base_len = len(base)
+    for i in range(j+1, base_len):
+        beta = h[base[i]]
+        if beta == base[i]:
+            continue
+        if beta not in orbits[i]:
+            if not slp:
+                return h, i + 1
+            return h, i + 1, slp
+        u = transversals[i][beta]
+        if h == u:
+            if not slp:
+                return False, base_len + 1
+            return False, base_len + 1, slp
+        h = _af_rmul(_af_invert(u), h)
+        if slp:
+            u_slp = slps[i][beta][:]
+            u_slp.reverse()
+            u_slp = [(i, (g,)) for g in u_slp]
+            slp = u_slp + slp
+    if not slp:
+        return h, base_len + 1
+    return h, base_len + 1, slp
+
+
+def _strong_gens_from_distr(strong_gens_distr):
+    """
+    Retrieve strong generating set from generators of basic stabilizers.
+
+    This is just the union of the generators of the first and second basic
+    stabilizers.
+
+    Parameters
+    ==========
+
+    strong_gens_distr : strong generators distributed by membership in basic stabilizers
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics import SymmetricGroup
+    >>> from sympy.combinatorics.util import (_strong_gens_from_distr,
+    ... _distribute_gens_by_base)
+    >>> S = SymmetricGroup(3)
+    >>> S.schreier_sims()
+    >>> S.strong_gens
+    [(0 1 2), (2)(0 1), (1 2)]
+    >>> strong_gens_distr = _distribute_gens_by_base(S.base, S.strong_gens)
+    >>> _strong_gens_from_distr(strong_gens_distr)
+    [(0 1 2), (2)(0 1), (1 2)]
+
+    See Also
+    ========
+
+    _distribute_gens_by_base
+
+    """
+    if len(strong_gens_distr) == 1:
+        return strong_gens_distr[0][:]
+    else:
+        result = strong_gens_distr[0]
+        for gen in strong_gens_distr[1]:
+            if gen not in result:
+                result.append(gen)
+        return result

lib/python3.12/site-packages/sympy/functions/combinatorial/__init__.py

@@ -0,0 +1 @@
+# Stub __init__.py for sympy.functions.combinatorial

lib/python3.12/site-packages/sympy/functions/combinatorial/factorials.py

@@ -0,0 +1,1133 @@
+from __future__ import annotations
+from functools import reduce
+
+from sympy.core import S, sympify, Dummy, Mod
+from sympy.core.cache import cacheit
+from sympy.core.function import Function, ArgumentIndexError, PoleError
+from sympy.core.logic import fuzzy_and
+from sympy.core.numbers import Integer, pi, I
+from sympy.core.relational import Eq
+from sympy.external.gmpy import gmpy as _gmpy
+from sympy.ntheory import sieve
+from sympy.ntheory.residue_ntheory import binomial_mod
+from sympy.polys.polytools import Poly
+
+from math import factorial as _factorial, prod, sqrt as _sqrt
+
+class CombinatorialFunction(Function):
+    """Base class for combinatorial functions. """
+
+    def _eval_simplify(self, **kwargs):
+        from sympy.simplify.combsimp import combsimp
+        # combinatorial function with non-integer arguments is
+        # automatically passed to gammasimp
+        expr = combsimp(self)
+        measure = kwargs['measure']
+        if measure(expr) <= kwargs['ratio']*measure(self):
+            return expr
+        return self
+
+
+###############################################################################
+######################## FACTORIAL and MULTI-FACTORIAL ########################
+###############################################################################
+
+
+class factorial(CombinatorialFunction):
+    r"""Implementation of factorial function over nonnegative integers.
+       By convention (consistent with the gamma function and the binomial
+       coefficients), factorial of a negative integer is complex infinity.
+
+       The factorial is very important in combinatorics where it gives
+       the number of ways in which `n` objects can be permuted. It also
+       arises in calculus, probability, number theory, etc.
+
+       There is strict relation of factorial with gamma function. In
+       fact `n! = gamma(n+1)` for nonnegative integers. Rewrite of this
+       kind is very useful in case of combinatorial simplification.
+
+       Computation of the factorial is done using two algorithms. For
+       small arguments a precomputed look up table is used. However for bigger
+       input algorithm Prime-Swing is used. It is the fastest algorithm
+       known and computes `n!` via prime factorization of special class
+       of numbers, called here the 'Swing Numbers'.
+
+       Examples
+       ========
+
+       >>> from sympy import Symbol, factorial, S
+       >>> n = Symbol('n', integer=True)
+
+       >>> factorial(0)
+       1
+
+       >>> factorial(7)
+       5040
+
+       >>> factorial(-2)
+       zoo
+
+       >>> factorial(n)
+       factorial(n)
+
+       >>> factorial(2*n)
+       factorial(2*n)
+
+       >>> factorial(S(1)/2)
+       factorial(1/2)
+
+       See Also
+       ========
+
+       factorial2, RisingFactorial, FallingFactorial
+    """
+
+    def fdiff(self, argindex=1):
+        from sympy.functions.special.gamma_functions import (gamma, polygamma)
+        if argindex == 1:
+            return gamma(self.args[0] + 1)*polygamma(0, self.args[0] + 1)
+        else:
+            raise ArgumentIndexError(self, argindex)
+
+    _small_swing = [
+        1, 1, 1, 3, 3, 15, 5, 35, 35, 315, 63, 693, 231, 3003, 429, 6435, 6435, 109395,
+        12155, 230945, 46189, 969969, 88179, 2028117, 676039, 16900975, 1300075,
+        35102025, 5014575, 145422675, 9694845, 300540195, 300540195
+    ]
+
+    _small_factorials: list[int] = []
+
+    @classmethod
+    def _swing(cls, n):
+        if n < 33:
+            return cls._small_swing[n]
+        else:
+            N, primes = int(_sqrt(n)), []
+
+            for prime in sieve.primerange(3, N + 1):
+                p, q = 1, n
+
+                while True:
+                    q //= prime
+
+                    if q > 0:
+                        if q & 1 == 1:
+                            p *= prime
+                    else:
+                        break
+
+                if p > 1:
+                    primes.append(p)
+
+            for prime in sieve.primerange(N + 1, n//3 + 1):
+                if (n // prime) & 1 == 1:
+                    primes.append(prime)
+
+            L_product = prod(sieve.primerange(n//2 + 1, n + 1))
+            R_product = prod(primes)
+
+            return L_product*R_product
+
+    @classmethod
+    def _recursive(cls, n):
+        if n < 2:
+            return 1
+        else:
+            return (cls._recursive(n//2)**2)*cls._swing(n)
+
+    @classmethod
+    def eval(cls, n):
+        n = sympify(n)
+
+        if n.is_Number:
+            if n.is_zero:
+                return S.One
+            elif n is S.Infinity:
+                return S.Infinity
+            elif n.is_Integer:
+                if n.is_negative:
+                    return S.ComplexInfinity
+                else:
+                    n = n.p
+
+                    if n < 20:
+                        if not cls._small_factorials:
+                            result = 1
+                            for i in range(1, 20):
+                                result *= i
+                                cls._small_factorials.append(result)
+                        result = cls._small_factorials[n-1]
+
+                    # GMPY factorial is faster, use it when available
+                    #
+                    # XXX: There is a sympy.external.gmpy.factorial function
+                    # which provides gmpy.fac if available or the flint version
+                    # if flint is used. It could be used here to avoid the
+                    # conditional logic but it needs to be checked whether the
+                    # pure Python fallback used there is as fast as the
+                    # fallback used here (perhaps the fallback here should be
+                    # moved to sympy.external.ntheory).
+                    elif _gmpy is not None:
+                        result = _gmpy.fac(n)
+
+                    else:
+                        bits = bin(n).count('1')
+                        result = cls._recursive(n)*2**(n - bits)
+
+                    return Integer(result)
+
+    def _facmod(self, n, q):
+        res, N = 1, int(_sqrt(n))
+
+        # Exponent of prime p in n! is e_p(n) = [n/p] + [n/p**2] + ...
+        # for p > sqrt(n), e_p(n) < sqrt(n), the primes with [n/p] = m,
+        # occur consecutively and are grouped together in pw[m] for
+        # simultaneous exponentiation at a later stage
+        pw = [1]*N
+
+        m = 2 # to initialize the if condition below
+        for prime in sieve.primerange(2, n + 1):
+            if m > 1:
+                m, y = 0, n // prime
+                while y:
+                    m += y
+                    y //= prime
+            if m < N:
+                pw[m] = pw[m]*prime % q
+            else:
+                res = res*pow(prime, m, q) % q
+
+        for ex, bs in enumerate(pw):
+            if ex == 0 or bs == 1:
+                continue
+            if bs == 0:
+                return 0
+            res = res*pow(bs, ex, q) % q
+
+        return res
+
+    def _eval_Mod(self, q):
+        n = self.args[0]
+        if n.is_integer and n.is_nonnegative and q.is_integer:
+            aq = abs(q)
+            d = aq - n
+            if d.is_nonpositive:
+                return S.Zero
+            else:
+                isprime = aq.is_prime
+                if d == 1:
+                    # Apply Wilson's theorem (if a natural number n > 1
+                    # is a prime number, then (n-1)! = -1 mod n) and
+                    # its inverse (if n > 4 is a composite number, then
+                    # (n-1)! = 0 mod n)
+                    if isprime:
+                        return -1 % q
+                    elif isprime is False and (aq - 6).is_nonnegative:
+                        return S.Zero
+                elif n.is_Integer and q.is_Integer:
+                    n, d, aq = map(int, (n, d, aq))
+                    if isprime and (d - 1 < n):
+                        fc = self._facmod(d - 1, aq)
+                        fc = pow(fc, aq - 2, aq)
+                        if d%2:
+                            fc = -fc
+                    else:
+                        fc = self._facmod(n, aq)
+
+                    return fc % q
+
+    def _eval_rewrite_as_gamma(self, n, piecewise=True, **kwargs):
+        from sympy.functions.special.gamma_functions import gamma
+        return gamma(n + 1)
+
+    def _eval_rewrite_as_Product(self, n, **kwargs):
+        from sympy.concrete.products import Product
+        if n.is_nonnegative and n.is_integer:
+            i = Dummy('i', integer=True)
+            return Product(i, (i, 1, n))
+
+    def _eval_is_integer(self):
+        if self.args[0].is_integer and self.args[0].is_nonnegative:
+            return True
+
+    def _eval_is_positive(self):
+        if self.args[0].is_integer and self.args[0].is_nonnegative:
+            return True
+
+    def _eval_is_even(self):
+        x = self.args[0]
+        if x.is_integer and x.is_nonnegative:
+            return (x - 2).is_nonnegative
+
+    def _eval_is_composite(self):
+        x = self.args[0]
+        if x.is_integer and x.is_nonnegative:
+            return (x - 3).is_nonnegative
+
+    def _eval_is_real(self):
+        x = self.args[0]
+        if x.is_nonnegative or x.is_noninteger:
+            return True
+
+    def _eval_as_leading_term(self, x, logx=None, cdir=0):
+        arg = self.args[0].as_leading_term(x)
+        arg0 = arg.subs(x, 0)
+        if arg0.is_zero:
+            return S.One
+        elif not arg0.is_infinite:
+            return self.func(arg)
+        raise PoleError("Cannot expand %s around 0" % (self))
+
+class MultiFactorial(CombinatorialFunction):
+    pass
+
+
+class subfactorial(CombinatorialFunction):
+    r"""The subfactorial counts the derangements of $n$ items and is
+    defined for non-negative integers as:
+
+    .. math:: !n = \begin{cases} 1 & n = 0 \\ 0 & n = 1 \\
+                    (n-1)(!(n-1) + !(n-2)) & n > 1 \end{cases}
+
+    It can also be written as ``int(round(n!/exp(1)))`` but the
+    recursive definition with caching is implemented for this function.
+
+    An interesting analytic expression is the following [2]_
+
+    .. math:: !x = \Gamma(x + 1, -1)/e
+
+    which is valid for non-negative integers `x`. The above formula
+    is not very useful in case of non-integers. `\Gamma(x + 1, -1)` is
+    single-valued only for integral arguments `x`, elsewhere on the positive
+    real axis it has an infinite number of branches none of which are real.
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Subfactorial
+    .. [2] https://mathworld.wolfram.com/Subfactorial.html
+
+    Examples
+    ========
+
+    >>> from sympy import subfactorial
+    >>> from sympy.abc import n
+    >>> subfactorial(n + 1)
+    subfactorial(n + 1)
+    >>> subfactorial(5)
+    44
+
+    See Also
+    ========
+
+    factorial, uppergamma,
+    sympy.utilities.iterables.generate_derangements
+    """
+
+    @classmethod
+    @cacheit
+    def _eval(self, n):
+        if not n:
+            return S.One
+        elif n == 1:
+            return S.Zero
+        else:
+            z1, z2 = 1, 0
+            for i in range(2, n + 1):
+                z1, z2 = z2, (i - 1)*(z2 + z1)
+            return z2
+
+    @classmethod
+    def eval(cls, arg):
+        if arg.is_Number:
+            if arg.is_Integer and arg.is_nonnegative:
+                return cls._eval(arg)
+            elif arg is S.NaN:
+                return S.NaN
+            elif arg is S.Infinity:
+                return S.Infinity
+
+    def _eval_is_even(self):
+        if self.args[0].is_odd and self.args[0].is_nonnegative:
+            return True
+
+    def _eval_is_integer(self):
+        if self.args[0].is_integer and self.args[0].is_nonnegative:
+            return True
+
+    def _eval_rewrite_as_factorial(self, arg, **kwargs):
+        from sympy.concrete.summations import summation
+        i = Dummy('i')
+        f = S.NegativeOne**i / factorial(i)
+        return factorial(arg) * summation(f, (i, 0, arg))
+
+    def _eval_rewrite_as_gamma(self, arg, piecewise=True, **kwargs):
+        from sympy.functions.elementary.exponential import exp
+        from sympy.functions.special.gamma_functions import (gamma, lowergamma)
+        return (S.NegativeOne**(arg + 1)*exp(-I*pi*arg)*lowergamma(arg + 1, -1)
+                + gamma(arg + 1))*exp(-1)
+
+    def _eval_rewrite_as_uppergamma(self, arg, **kwargs):
+        from sympy.functions.special.gamma_functions import uppergamma
+        return uppergamma(arg + 1, -1)/S.Exp1
+
+    def _eval_is_nonnegative(self):
+        if self.args[0].is_integer and self.args[0].is_nonnegative:
+            return True
+
+    def _eval_is_odd(self):
+        if self.args[0].is_even and self.args[0].is_nonnegative:
+            return True
+
+
+class factorial2(CombinatorialFunction):
+    r"""The double factorial `n!!`, not to be confused with `(n!)!`
+
+    The double factorial is defined for nonnegative integers and for odd
+    negative integers as:
+
+    .. math:: n!! = \begin{cases} 1 & n = 0 \\
+                    n(n-2)(n-4) \cdots 1 & n\ \text{positive odd} \\
+                    n(n-2)(n-4) \cdots 2 & n\ \text{positive even} \\
+                    (n+2)!!/(n+2) & n\ \text{negative odd} \end{cases}
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Double_factorial
+
+    Examples
+    ========
+
+    >>> from sympy import factorial2, var
+    >>> n = var('n')
+    >>> n
+    n
+    >>> factorial2(n + 1)
+    factorial2(n + 1)
+    >>> factorial2(5)
+    15
+    >>> factorial2(-1)
+    1
+    >>> factorial2(-5)
+    1/3
+
+    See Also
+    ========
+
+    factorial, RisingFactorial, FallingFactorial
+    """
+
+    @classmethod
+    def eval(cls, arg):
+        # TODO: extend this to complex numbers?
+
+        if arg.is_Number:
+            if not arg.is_Integer:
+                raise ValueError("argument must be nonnegative integer "
+                                    "or negative odd integer")
+
+            # This implementation is faster than the recursive one
+            # It also avoids "maximum recursion depth exceeded" runtime error
+            if arg.is_nonnegative:
+                if arg.is_even:
+                    k = arg / 2
+                    return 2**k * factorial(k)
+                return factorial(arg) / factorial2(arg - 1)
+
+
+            if arg.is_odd:
+                return arg*(S.NegativeOne)**((1 - arg)/2) / factorial2(-arg)
+            raise ValueError("argument must be nonnegative integer "
+                                "or negative odd integer")
+
+
+    def _eval_is_even(self):
+        # Double factorial is even for every positive even input
+        n = self.args[0]
+        if n.is_integer:
+            if n.is_odd:
+                return False
+            if n.is_even:
+                if n.is_positive:
+                    return True
+                if n.is_zero:
+                    return False
+
+    def _eval_is_integer(self):
+        # Double factorial is an integer for every nonnegative input, and for
+        # -1 and -3
+        n = self.args[0]
+        if n.is_integer:
+            if (n + 1).is_nonnegative:
+                return True
+            if n.is_odd:
+                return (n + 3).is_nonnegative
+
+    def _eval_is_odd(self):
+        # Double factorial is odd for every odd input not smaller than -3, and
+        # for 0
+        n = self.args[0]
+        if n.is_odd:
+            return (n + 3).is_nonnegative
+        if n.is_even:
+            if n.is_positive:
+                return False
+            if n.is_zero:
+                return True
+
+    def _eval_is_positive(self):
+        # Double factorial is positive for every nonnegative input, and for
+        # every odd negative input which is of the form -1-4k for an
+        # nonnegative integer k
+        n = self.args[0]
+        if n.is_integer:
+            if (n + 1).is_nonnegative:
+                return True
+            if n.is_odd:
+                return ((n + 1) / 2).is_even
+
+    def _eval_rewrite_as_gamma(self, n, piecewise=True, **kwargs):
+        from sympy.functions.elementary.miscellaneous import sqrt
+        from sympy.functions.elementary.piecewise import Piecewise
+        from sympy.functions.special.gamma_functions import gamma
+        return 2**(n/2)*gamma(n/2 + 1) * Piecewise((1, Eq(Mod(n, 2), 0)),
+                (sqrt(2/pi), Eq(Mod(n, 2), 1)))
+
+
+###############################################################################
+######################## RISING and FALLING FACTORIALS ########################
+###############################################################################
+
+
+class RisingFactorial(CombinatorialFunction):
+    r"""
+    Rising factorial (also called Pochhammer symbol [1]_) is a double valued
+    function arising in concrete mathematics, hypergeometric functions
+    and series expansions. It is defined by:
+
+    .. math:: \texttt{rf(y, k)} = (x)^k = x \cdot (x+1) \cdots (x+k-1)
+
+    where `x` can be arbitrary expression and `k` is an integer. For
+    more information check "Concrete mathematics" by Graham, pp. 66
+    or visit https://mathworld.wolfram.com/RisingFactorial.html page.
+
+    When `x` is a `~.Poly` instance of degree $\ge 1$ with a single variable,
+    `(x)^k = x(y) \cdot x(y+1) \cdots x(y+k-1)`, where `y` is the
+    variable of `x`. This is as described in [2]_.
+
+    Examples
+    ========
+
+    >>> from sympy import rf, Poly
+    >>> from sympy.abc import x
+    >>> rf(x, 0)
+    1
+    >>> rf(1, 5)
+    120
+    >>> rf(x, 5) == x*(1 + x)*(2 + x)*(3 + x)*(4 + x)
+    True
+    >>> rf(Poly(x**3, x), 2)
+    Poly(x**6 + 3*x**5 + 3*x**4 + x**3, x, domain='ZZ')
+
+    Rewriting is complicated unless the relationship between
+    the arguments is known, but rising factorial can
+    be rewritten in terms of gamma, factorial, binomial,
+    and falling factorial.
+
+    >>> from sympy import Symbol, factorial, ff, binomial, gamma
+    >>> n = Symbol('n', integer=True, positive=True)
+    >>> R = rf(n, n + 2)
+    >>> for i in (rf, ff, factorial, binomial, gamma):
+    ...  R.rewrite(i)
+    ...
+    RisingFactorial(n, n + 2)
+    FallingFactorial(2*n + 1, n + 2)
+    factorial(2*n + 1)/factorial(n - 1)
+    binomial(2*n + 1, n + 2)*factorial(n + 2)
+    gamma(2*n + 2)/gamma(n)
+
+    See Also
+    ========
+
+    factorial, factorial2, FallingFactorial
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Pochhammer_symbol
+    .. [2] Peter Paule, "Greatest Factorial Factorization and Symbolic
+           Summation", Journal of Symbolic Computation, vol. 20, pp. 235-268,
+           1995.
+
+    """
+
+    @classmethod
+    def eval(cls, x, k):
+        x = sympify(x)
+        k = sympify(k)
+
+        if x is S.NaN or k is S.NaN:
+            return S.NaN
+        elif x is S.One:
+            return factorial(k)
+        elif k.is_Integer:
+            if k.is_zero:
+                return S.One
+            else:
+                if k.is_positive:
+                    if x is S.Infinity:
+                        return S.Infinity
+                    elif x is S.NegativeInfinity:
+                        if k.is_odd:
+                            return S.NegativeInfinity
+                        else:
+                            return S.Infinity
+                    else:
+                        if isinstance(x, Poly):
+                            gens = x.gens
+                            if len(gens)!= 1:
+                                raise ValueError("rf only defined for "
+                                            "polynomials on one generator")
+                            else:
+                                return reduce(lambda r, i:
+                                              r*(x.shift(i)),
+                                              range(int(k)), 1)
+                        else:
+                            return reduce(lambda r, i: r*(x + i),
+                                          range(int(k)), 1)
+
+                else:
+                    if x is S.Infinity:
+                        return S.Infinity
+                    elif x is S.NegativeInfinity:
+                        return S.Infinity
+                    else:
+                        if isinstance(x, Poly):
+                            gens = x.gens
+                            if len(gens)!= 1:
+                                raise ValueError("rf only defined for "
+                                            "polynomials on one generator")
+                            else:
+                                return 1/reduce(lambda r, i:
+                                                r*(x.shift(-i)),
+                                                range(1, abs(int(k)) + 1), 1)
+                        else:
+                            return 1/reduce(lambda r, i:
+                                            r*(x - i),
+                                            range(1, abs(int(k)) + 1), 1)
+
+        if k.is_integer == False:
+            if x.is_integer and x.is_negative:
+                return S.Zero
+
+    def _eval_rewrite_as_gamma(self, x, k, piecewise=True, **kwargs):
+        from sympy.functions.elementary.piecewise import Piecewise
+        from sympy.functions.special.gamma_functions import gamma
+        if not piecewise:
+            if (x <= 0) == True:
+                return S.NegativeOne**k*gamma(1 - x) / gamma(-k - x + 1)
+            return gamma(x + k) / gamma(x)
+        return Piecewise(
+            (gamma(x + k) / gamma(x), x > 0),
+            (S.NegativeOne**k*gamma(1 - x) / gamma(-k - x + 1), True))
+
+    def _eval_rewrite_as_FallingFactorial(self, x, k, **kwargs):
+        return FallingFactorial(x + k - 1, k)
+
+    def _eval_rewrite_as_factorial(self, x, k, **kwargs):
+        from sympy.functions.elementary.piecewise import Piecewise
+        if x.is_integer and k.is_integer:
+            return Piecewise(
+                (factorial(k + x - 1)/factorial(x - 1), x > 0),
+                (S.NegativeOne**k*factorial(-x)/factorial(-k - x), True))
+
+    def _eval_rewrite_as_binomial(self, x, k, **kwargs):
+        if k.is_integer:
+            return factorial(k) * binomial(x + k - 1, k)
+
+    def _eval_rewrite_as_tractable(self, x, k, limitvar=None, **kwargs):
+        from sympy.functions.special.gamma_functions import gamma
+        if limitvar:
+            k_lim = k.subs(limitvar, S.Infinity)
+            if k_lim is S.Infinity:
+                return (gamma(x + k).rewrite('tractable', deep=True) / gamma(x))
+            elif k_lim is S.NegativeInfinity:
+                return (S.NegativeOne**k*gamma(1 - x) / gamma(-k - x + 1).rewrite('tractable', deep=True))
+        return self.rewrite(gamma).rewrite('tractable', deep=True)
+
+    def _eval_is_integer(self):
+        return fuzzy_and((self.args[0].is_integer, self.args[1].is_integer,
+                          self.args[1].is_nonnegative))
+
+
+class FallingFactorial(CombinatorialFunction):
+    r"""
+    Falling factorial (related to rising factorial) is a double valued
+    function arising in concrete mathematics, hypergeometric functions
+    and series expansions. It is defined by
+
+    .. math:: \texttt{ff(x, k)} = (x)_k = x \cdot (x-1) \cdots (x-k+1)
+
+    where `x` can be arbitrary expression and `k` is an integer. For
+    more information check "Concrete mathematics" by Graham, pp. 66
+    or [1]_.
+
+    When `x` is a `~.Poly` instance of degree $\ge 1$ with single variable,
+    `(x)_k = x(y) \cdot x(y-1) \cdots x(y-k+1)`, where `y` is the
+    variable of `x`. This is as described in
+
+    >>> from sympy import ff, Poly, Symbol
+    >>> from sympy.abc import x
+    >>> n = Symbol('n', integer=True)
+
+    >>> ff(x, 0)
+    1
+    >>> ff(5, 5)
+    120
+    >>> ff(x, 5) == x*(x - 1)*(x - 2)*(x - 3)*(x - 4)
+    True
+    >>> ff(Poly(x**2, x), 2)
+    Poly(x**4 - 2*x**3 + x**2, x, domain='ZZ')
+    >>> ff(n, n)
+    factorial(n)
+
+    Rewriting is complicated unless the relationship between
+    the arguments is known, but falling factorial can
+    be rewritten in terms of gamma, factorial and binomial
+    and rising factorial.
+
+    >>> from sympy import factorial, rf, gamma, binomial, Symbol
+    >>> n = Symbol('n', integer=True, positive=True)
+    >>> F = ff(n, n - 2)
+    >>> for i in (rf, ff, factorial, binomial, gamma):
+    ...  F.rewrite(i)
+    ...
+    RisingFactorial(3, n - 2)
+    FallingFactorial(n, n - 2)
+    factorial(n)/2
+    binomial(n, n - 2)*factorial(n - 2)
+    gamma(n + 1)/2
+
+    See Also
+    ========
+
+    factorial, factorial2, RisingFactorial
+
+    References
+    ==========
+
+    .. [1] https://mathworld.wolfram.com/FallingFactorial.html
+    .. [2] Peter Paule, "Greatest Factorial Factorization and Symbolic
+           Summation", Journal of Symbolic Computation, vol. 20, pp. 235-268,
+           1995.
+
+    """
+
+    @classmethod
+    def eval(cls, x, k):
+        x = sympify(x)
+        k = sympify(k)
+
+        if x is S.NaN or k is S.NaN:
+            return S.NaN
+        elif k.is_integer and x == k:
+            return factorial(x)
+        elif k.is_Integer:
+            if k.is_zero:
+                return S.One
+            else:
+                if k.is_positive:
+                    if x is S.Infinity:
+                        return S.Infinity
+                    elif x is S.NegativeInfinity:
+                        if k.is_odd:
+                            return S.NegativeInfinity
+                        else:
+                            return S.Infinity
+                    else:
+                        if isinstance(x, Poly):
+                            gens = x.gens
+                            if len(gens)!= 1:
+                                raise ValueError("ff only defined for "
+                                            "polynomials on one generator")
+                            else:
+                                return reduce(lambda r, i:
+                                              r*(x.shift(-i)),
+                                              range(int(k)), 1)
+                        else:
+                            return reduce(lambda r, i: r*(x - i),
+                                          range(int(k)), 1)
+                else:
+                    if x is S.Infinity:
+                        return S.Infinity
+                    elif x is S.NegativeInfinity:
+                        return S.Infinity
+                    else:
+                        if isinstance(x, Poly):
+                            gens = x.gens
+                            if len(gens)!= 1:
+                                raise ValueError("rf only defined for "
+                                            "polynomials on one generator")
+                            else:
+                                return 1/reduce(lambda r, i:
+                                                r*(x.shift(i)),
+                                                range(1, abs(int(k)) + 1), 1)
+                        else:
+                            return 1/reduce(lambda r, i: r*(x + i),
+                                            range(1, abs(int(k)) + 1), 1)
+
+    def _eval_rewrite_as_gamma(self, x, k, piecewise=True, **kwargs):
+        from sympy.functions.elementary.piecewise import Piecewise
+        from sympy.functions.special.gamma_functions import gamma
+        if not piecewise:
+            if (x < 0) == True:
+                return S.NegativeOne**k*gamma(k - x) / gamma(-x)
+            return gamma(x + 1) / gamma(x - k + 1)
+        return Piecewise(
+            (gamma(x + 1) / gamma(x - k + 1), x >= 0),
+            (S.NegativeOne**k*gamma(k - x) / gamma(-x), True))
+
+    def _eval_rewrite_as_RisingFactorial(self, x, k, **kwargs):
+        return rf(x - k + 1, k)
+
+    def _eval_rewrite_as_binomial(self, x, k, **kwargs):
+        if k.is_integer:
+            return factorial(k) * binomial(x, k)
+
+    def _eval_rewrite_as_factorial(self, x, k, **kwargs):
+        from sympy.functions.elementary.piecewise import Piecewise
+        if x.is_integer and k.is_integer:
+            return Piecewise(
+                (factorial(x)/factorial(-k + x), x >= 0),
+                (S.NegativeOne**k*factorial(k - x - 1)/factorial(-x - 1), True))
+
+    def _eval_rewrite_as_tractable(self, x, k, limitvar=None, **kwargs):
+        from sympy.functions.special.gamma_functions import gamma
+        if limitvar:
+            k_lim = k.subs(limitvar, S.Infinity)
+            if k_lim is S.Infinity:
+                return (S.NegativeOne**k*gamma(k - x).rewrite('tractable', deep=True) / gamma(-x))
+            elif k_lim is S.NegativeInfinity:
+                return (gamma(x + 1) / gamma(x - k + 1).rewrite('tractable', deep=True))
+        return self.rewrite(gamma).rewrite('tractable', deep=True)
+
+    def _eval_is_integer(self):
+        return fuzzy_and((self.args[0].is_integer, self.args[1].is_integer,
+                          self.args[1].is_nonnegative))
+
+
+rf = RisingFactorial
+ff = FallingFactorial
+
+###############################################################################
+########################### BINOMIAL COEFFICIENTS #############################
+###############################################################################
+
+
+class binomial(CombinatorialFunction):
+    r"""Implementation of the binomial coefficient. It can be defined
+    in two ways depending on its desired interpretation:
+
+    .. math:: \binom{n}{k} = \frac{n!}{k!(n-k)!}\ \text{or}\
+                \binom{n}{k} = \frac{(n)_k}{k!}
+
+    First, in a strict combinatorial sense it defines the
+    number of ways we can choose `k` elements from a set of
+    `n` elements. In this case both arguments are nonnegative
+    integers and binomial is computed using an efficient
+    algorithm based on prime factorization.
+
+    The other definition is generalization for arbitrary `n`,
+    however `k` must also be nonnegative. This case is very
+    useful when evaluating summations.
+
+    For the sake of convenience, for negative integer `k` this function
+    will return zero no matter the other argument.
+
+    To expand the binomial when `n` is a symbol, use either
+    ``expand_func()`` or ``expand(func=True)``. The former will keep
+    the polynomial in factored form while the latter will expand the
+    polynomial itself. See examples for details.
+
+    Examples
+    ========
+
+    >>> from sympy import Symbol, Rational, binomial, expand_func
+    >>> n = Symbol('n', integer=True, positive=True)
+
+    >>> binomial(15, 8)
+    6435
+
+    >>> binomial(n, -1)
+    0
+
+    Rows of Pascal's triangle can be generated with the binomial function:
+
+    >>> for N in range(8):
+    ...     print([binomial(N, i) for i in range(N + 1)])
+    ...
+    [1]
+    [1, 1]
+    [1, 2, 1]
+    [1, 3, 3, 1]
+    [1, 4, 6, 4, 1]
+    [1, 5, 10, 10, 5, 1]
+    [1, 6, 15, 20, 15, 6, 1]
+    [1, 7, 21, 35, 35, 21, 7, 1]
+
+    As can a given diagonal, e.g. the 4th diagonal:
+
+    >>> N = -4
+    >>> [binomial(N, i) for i in range(1 - N)]
+    [1, -4, 10, -20, 35]
+
+    >>> binomial(Rational(5, 4), 3)
+    -5/128
+    >>> binomial(Rational(-5, 4), 3)
+    -195/128
+
+    >>> binomial(n, 3)
+    binomial(n, 3)
+
+    >>> binomial(n, 3).expand(func=True)
+    n**3/6 - n**2/2 + n/3
+
+    >>> expand_func(binomial(n, 3))
+    n*(n - 2)*(n - 1)/6
+
+    In many cases, we can also compute binomial coefficients modulo a
+    prime p quickly using Lucas' Theorem [2]_, though we need to include
+    `evaluate=False` to postpone evaluation:
+
+    >>> from sympy import Mod
+    >>> Mod(binomial(156675, 4433, evaluate=False), 10**5 + 3)
+    28625
+
+    Using a generalisation of Lucas's Theorem given by Granville [3]_,
+    we can extend this to arbitrary n:
+
+    >>> Mod(binomial(10**18, 10**12, evaluate=False), (10**5 + 3)**2)
+    3744312326
+
+    References
+    ==========
+
+    .. [1] https://www.johndcook.com/blog/binomial_coefficients/
+    .. [2] https://en.wikipedia.org/wiki/Lucas%27s_theorem
+    .. [3] Binomial coefficients modulo prime powers, Andrew Granville,
+        Available: https://web.archive.org/web/20170202003812/http://www.dms.umontreal.ca/~andrew/PDF/BinCoeff.pdf
+    """
+
+    def fdiff(self, argindex=1):
+        from sympy.functions.special.gamma_functions import polygamma
+        if argindex == 1:
+            # https://functions.wolfram.com/GammaBetaErf/Binomial/20/01/01/
+            n, k = self.args
+            return binomial(n, k)*(polygamma(0, n + 1) - \
+                polygamma(0, n - k + 1))
+        elif argindex == 2:
+            # https://functions.wolfram.com/GammaBetaErf/Binomial/20/01/02/
+            n, k = self.args
+            return binomial(n, k)*(polygamma(0, n - k + 1) - \
+                polygamma(0, k + 1))
+        else:
+            raise ArgumentIndexError(self, argindex)
+
+    @classmethod
+    def _eval(self, n, k):
+        # n.is_Number and k.is_Integer and k != 1 and n != k
+
+        if k.is_Integer:
+            if n.is_Integer and n >= 0:
+                n, k = int(n), int(k)
+
+                if k > n:
+                    return S.Zero
+                elif k > n // 2:
+                    k = n - k
+
+                # XXX: This conditional logic should be moved to
+                # sympy.external.gmpy and the pure Python version of bincoef
+                # should be moved to sympy.external.ntheory.
+                if _gmpy is not None:
+                    return Integer(_gmpy.bincoef(n, k))
+
+                d, result = n - k, 1
+                for i in range(1, k + 1):
+                    d += 1
+                    result = result * d // i
+                return Integer(result)
+            else:
+                d, result = n - k, 1
+                for i in range(1, k + 1):
+                    d += 1
+                    result *= d
+                return result / _factorial(k)
+
+    @classmethod
+    def eval(cls, n, k):
+        n, k = map(sympify, (n, k))
+        d = n - k
+        n_nonneg, n_isint = n.is_nonnegative, n.is_integer
+        if k.is_zero or ((n_nonneg or n_isint is False)
+                and d.is_zero):
+            return S.One
+        if (k - 1).is_zero or ((n_nonneg or n_isint is False)
+                and (d - 1).is_zero):
+            return n
+        if k.is_integer:
+            if k.is_negative or (n_nonneg and n_isint and d.is_negative):
+                return S.Zero
+            elif n.is_number:
+                res = cls._eval(n, k)
+                return res.expand(basic=True) if res else res
+        elif n_nonneg is False and n_isint:
+            # a special case when binomial evaluates to complex infinity
+            return S.ComplexInfinity
+        elif k.is_number:
+            from sympy.functions.special.gamma_functions import gamma
+            return gamma(n + 1)/(gamma(k + 1)*gamma(n - k + 1))
+
+    def _eval_Mod(self, q):
+        n, k = self.args
+
+        if any(x.is_integer is False for x in (n, k, q)):
+            raise ValueError("Integers expected for binomial Mod")
+
+        if all(x.is_Integer for x in (n, k, q)):
+            n, k = map(int, (n, k))
+            aq, res = abs(q), 1
+
+            # handle negative integers k or n
+            if k < 0:
+                return S.Zero
+            if n < 0:
+                n = -n + k - 1
+                res = -1 if k%2 else 1
+
+            # non negative integers k and n
+            if k > n:
+                return S.Zero
+
+            isprime = aq.is_prime
+            aq = int(aq)
+            if isprime:
+                if aq < n:
+                    # use Lucas Theorem
+                    N, K = n, k
+                    while N or K:
+                        res = res*binomial(N % aq, K % aq) % aq
+                        N, K = N // aq, K // aq
+
+                else:
+                    # use Factorial Modulo
+                    d = n - k
+                    if k > d:
+                        k, d = d, k
+                    kf = 1
+                    for i in range(2, k + 1):
+                        kf = kf*i % aq
+                    df = kf
+                    for i in range(k + 1, d + 1):
+                        df = df*i % aq
+                    res *= df
+                    for i in range(d + 1, n + 1):
+                        res = res*i % aq
+
+                    res *= pow(kf*df % aq, aq - 2, aq)
+                    res %= aq
+
+            elif _sqrt(q) < k and q != 1:
+                res = binomial_mod(n, k, q)
+
+            else:
+                # Binomial Factorization is performed by calculating the
+                # exponents of primes <= n in `n! /(k! (n - k)!)`,
+                # for non-negative integers n and k. As the exponent of
+                # prime in n! is e_p(n) = [n/p] + [n/p**2] + ...
+                # the exponent of prime in binomial(n, k) would be
+                # e_p(n) - e_p(k) - e_p(n - k)
+                M = int(_sqrt(n))
+                for prime in sieve.primerange(2, n + 1):
+                    if prime > n - k:
+                        res = res*prime % aq
+                    elif prime > n // 2:
+                        continue
+                    elif prime > M:
+                        if n % prime < k % prime:
+                            res = res*prime % aq
+                    else:
+                        N, K = n, k
+                        exp = a = 0
+
+                        while N > 0:
+                            a = int((N % prime) < (K % prime + a))
+                            N, K = N // prime, K // prime
+                            exp += a
+
+                        if exp > 0:
+                            res *= pow(prime, exp, aq)
+                            res %= aq
+
+            return S(res % q)
+
+    def _eval_expand_func(self, **hints):
+        """
+        Function to expand binomial(n, k) when m is positive integer
+        Also,
+        n is self.args[0] and k is self.args[1] while using binomial(n, k)
+        """
+        n = self.args[0]
+        if n.is_Number:
+            return binomial(*self.args)
+
+        k = self.args[1]
+        if (n-k).is_Integer:
+            k = n - k
+
+        if k.is_Integer:
+            if k.is_zero:
+                return S.One
+            elif k.is_negative:
+                return S.Zero
+            else:
+                n, result = self.args[0], 1
+                for i in range(1, k + 1):
+                    result *= n - k + i
+                return result / _factorial(k)
+        else:
+            return binomial(*self.args)
+
+    def _eval_rewrite_as_factorial(self, n, k, **kwargs):
+        return factorial(n)/(factorial(k)*factorial(n - k))
+
+    def _eval_rewrite_as_gamma(self, n, k, piecewise=True, **kwargs):
+        from sympy.functions.special.gamma_functions import gamma
+        return gamma(n + 1)/(gamma(k + 1)*gamma(n - k + 1))
+
+    def _eval_rewrite_as_tractable(self, n, k, limitvar=None, **kwargs):
+        return self._eval_rewrite_as_gamma(n, k).rewrite('tractable')
+
+    def _eval_rewrite_as_FallingFactorial(self, n, k, **kwargs):
+        if k.is_integer:
+            return ff(n, k) / factorial(k)
+
+    def _eval_is_integer(self):
+        n, k = self.args
+        if n.is_integer and k.is_integer:
+            return True
+        elif k.is_integer is False:
+            return False
+
+    def _eval_is_nonnegative(self):
+        n, k = self.args
+        if n.is_integer and k.is_integer:
+            if n.is_nonnegative or k.is_negative or k.is_even:
+                return True
+            elif k.is_even is False:
+                return  False
+
+    def _eval_as_leading_term(self, x, logx=None, cdir=0):
+        from sympy.functions.special.gamma_functions import gamma
+        return self.rewrite(gamma)._eval_as_leading_term(x, logx=logx, cdir=cdir)

lib/python3.12/site-packages/sympy/functions/combinatorial/tests/test_comb_factorials.py

@@ -0,0 +1,653 @@
+from sympy.concrete.products import Product
+from sympy.core.function import expand_func
+from sympy.core.mod import Mod
+from sympy.core.mul import Mul
+from sympy.core import EulerGamma
+from sympy.core.numbers import (Float, I, Rational, nan, oo, pi, zoo)
+from sympy.core.relational import Eq
+from sympy.core.singleton import S
+from sympy.core.symbol import (Dummy, Symbol, symbols)
+from sympy.functions.combinatorial.factorials import (ff, rf, binomial, factorial, factorial2)
+from sympy.functions.elementary.miscellaneous import sqrt
+from sympy.functions.elementary.piecewise import Piecewise
+from sympy.functions.special.gamma_functions import (gamma, polygamma)
+from sympy.polys.polytools import Poly
+from sympy.series.order import O
+from sympy.simplify.simplify import simplify
+from sympy.core.expr import unchanged
+from sympy.core.function import ArgumentIndexError
+from sympy.functions.combinatorial.factorials import subfactorial
+from sympy.functions.special.gamma_functions import uppergamma
+from sympy.testing.pytest import XFAIL, raises, slow
+
+#Solves and Fixes Issue #10388 - This is the updated test for the same solved issue
+
+def test_rf_eval_apply():
+    x, y = symbols('x,y')
+    n, k = symbols('n k', integer=True)
+    m = Symbol('m', integer=True, nonnegative=True)
+
+    assert rf(nan, y) is nan
+    assert rf(x, nan) is nan
+
+    assert unchanged(rf, x, y)
+
+    assert rf(oo, 0) == 1
+    assert rf(-oo, 0) == 1
+
+    assert rf(oo, 6) is oo
+    assert rf(-oo, 7) is -oo
+    assert rf(-oo, 6) is oo
+
+    assert rf(oo, -6) is oo
+    assert rf(-oo, -7) is oo
+
+    assert rf(-1, pi) == 0
+    assert rf(-5, 1 + I) == 0
+
+    assert unchanged(rf, -3, k)
+    assert unchanged(rf, x, Symbol('k', integer=False))
+    assert rf(-3, Symbol('k', integer=False)) == 0
+    assert rf(Symbol('x', negative=True, integer=True), Symbol('k', integer=False)) == 0
+
+    assert rf(x, 0) == 1
+    assert rf(x, 1) == x
+    assert rf(x, 2) == x*(x + 1)
+    assert rf(x, 3) == x*(x + 1)*(x + 2)
+    assert rf(x, 5) == x*(x + 1)*(x + 2)*(x + 3)*(x + 4)
+
+    assert rf(x, -1) == 1/(x - 1)
+    assert rf(x, -2) == 1/((x - 1)*(x - 2))
+    assert rf(x, -3) == 1/((x - 1)*(x - 2)*(x - 3))
+
+    assert rf(1, 100) == factorial(100)
+
+    assert rf(x**2 + 3*x, 2) == (x**2 + 3*x)*(x**2 + 3*x + 1)
+    assert isinstance(rf(x**2 + 3*x, 2), Mul)
+    assert rf(x**3 + x, -2) == 1/((x**3 + x - 1)*(x**3 + x - 2))
+
+    assert rf(Poly(x**2 + 3*x, x), 2) == Poly(x**4 + 8*x**3 + 19*x**2 + 12*x, x)
+    assert isinstance(rf(Poly(x**2 + 3*x, x), 2), Poly)
+    raises(ValueError, lambda: rf(Poly(x**2 + 3*x, x, y), 2))
+    assert rf(Poly(x**3 + x, x), -2) == 1/(x**6 - 9*x**5 + 35*x**4 - 75*x**3 + 94*x**2 - 66*x + 20)
+    raises(ValueError, lambda: rf(Poly(x**3 + x, x, y), -2))
+
+    assert rf(x, m).is_integer is None
+    assert rf(n, k).is_integer is None
+    assert rf(n, m).is_integer is True
+    assert rf(n, k + pi).is_integer is False
+    assert rf(n, m + pi).is_integer is False
+    assert rf(pi, m).is_integer is False
+
+    def check(x, k, o, n):
+        a, b = Dummy(), Dummy()
+        r = lambda x, k: o(a, b).rewrite(n).subs({a:x,b:k})
+        for i in range(-5,5):
+          for j in range(-5,5):
+              assert o(i, j) == r(i, j), (o, n, i, j)
+    check(x, k, rf, ff)
+    check(x, k, rf, binomial)
+    check(n, k, rf, factorial)
+    check(x, y, rf, factorial)
+    check(x, y, rf, binomial)
+
+    assert rf(x, k).rewrite(ff) == ff(x + k - 1, k)
+    assert rf(x, k).rewrite(gamma) == Piecewise(
+        (gamma(k + x)/gamma(x), x > 0),
+        ((-1)**k*gamma(1 - x)/gamma(-k - x + 1), True))
+    assert rf(5, k).rewrite(gamma) == gamma(k + 5)/24
+    assert rf(x, k).rewrite(binomial) == factorial(k)*binomial(x + k - 1, k)
+    assert rf(n, k).rewrite(factorial) == Piecewise(
+        (factorial(k + n - 1)/factorial(n - 1), n > 0),
+        ((-1)**k*factorial(-n)/factorial(-k - n), True))
+    assert rf(5, k).rewrite(factorial) == factorial(k + 4)/24
+    assert rf(x, y).rewrite(factorial) == rf(x, y)
+    assert rf(x, y).rewrite(binomial) == rf(x, y)
+
+    import random
+    from mpmath import rf as mpmath_rf
+    for i in range(100):
+        x = -500 + 500 * random.random()
+        k = -500 + 500 * random.random()
+        assert (abs(mpmath_rf(x, k) - rf(x, k)) < 10**(-15))
+
+
+def test_ff_eval_apply():
+    x, y = symbols('x,y')
+    n, k = symbols('n k', integer=True)
+    m = Symbol('m', integer=True, nonnegative=True)
+
+    assert ff(nan, y) is nan
+    assert ff(x, nan) is nan
+
+    assert unchanged(ff, x, y)
+
+    assert ff(oo, 0) == 1
+    assert ff(-oo, 0) == 1
+
+    assert ff(oo, 6) is oo
+    assert ff(-oo, 7) is -oo
+    assert ff(-oo, 6) is oo
+
+    assert ff(oo, -6) is oo
+    assert ff(-oo, -7) is oo
+
+    assert ff(x, 0) == 1
+    assert ff(x, 1) == x
+    assert ff(x, 2) == x*(x - 1)
+    assert ff(x, 3) == x*(x - 1)*(x - 2)
+    assert ff(x, 5) == x*(x - 1)*(x - 2)*(x - 3)*(x - 4)
+
+    assert ff(x, -1) == 1/(x + 1)
+    assert ff(x, -2) == 1/((x + 1)*(x + 2))
+    assert ff(x, -3) == 1/((x + 1)*(x + 2)*(x + 3))
+
+    assert ff(100, 100) == factorial(100)
+
+    assert ff(2*x**2 - 5*x, 2) == (2*x**2  - 5*x)*(2*x**2 - 5*x - 1)
+    assert isinstance(ff(2*x**2 - 5*x, 2), Mul)
+    assert ff(x**2 + 3*x, -2) == 1/((x**2 + 3*x + 1)*(x**2 + 3*x + 2))
+
+    assert ff(Poly(2*x**2 - 5*x, x), 2) == Poly(4*x**4 - 28*x**3 + 59*x**2 - 35*x, x)
+    assert isinstance(ff(Poly(2*x**2 - 5*x, x), 2), Poly)
+    raises(ValueError, lambda: ff(Poly(2*x**2 - 5*x, x, y), 2))
+    assert ff(Poly(x**2 + 3*x, x), -2) == 1/(x**4 + 12*x**3 + 49*x**2 + 78*x + 40)
+    raises(ValueError, lambda: ff(Poly(x**2 + 3*x, x, y), -2))
+
+
+    assert ff(x, m).is_integer is None
+    assert ff(n, k).is_integer is None
+    assert ff(n, m).is_integer is True
+    assert ff(n, k + pi).is_integer is False
+    assert ff(n, m + pi).is_integer is False
+    assert ff(pi, m).is_integer is False
+
+    assert isinstance(ff(x, x), ff)
+    assert ff(n, n) == factorial(n)
+
+    def check(x, k, o, n):
+        a, b = Dummy(), Dummy()
+        r = lambda x, k: o(a, b).rewrite(n).subs({a:x,b:k})
+        for i in range(-5,5):
+          for j in range(-5,5):
+              assert o(i, j) == r(i, j), (o, n)
+    check(x, k, ff, rf)
+    check(x, k, ff, gamma)
+    check(n, k, ff, factorial)
+    check(x, k, ff, binomial)
+    check(x, y, ff, factorial)
+    check(x, y, ff, binomial)
+
+    assert ff(x, k).rewrite(rf) == rf(x - k + 1, k)
+    assert ff(x, k).rewrite(gamma) == Piecewise(
+        (gamma(x + 1)/gamma(-k + x + 1), x >= 0),
+        ((-1)**k*gamma(k - x)/gamma(-x), True))
+    assert ff(5, k).rewrite(gamma) == 120/gamma(6 - k)
+    assert ff(n, k).rewrite(factorial) == Piecewise(
+        (factorial(n)/factorial(-k + n), n >= 0),
+        ((-1)**k*factorial(k - n - 1)/factorial(-n - 1), True))
+    assert ff(5, k).rewrite(factorial) == 120/factorial(5 - k)
+    assert ff(x, k).rewrite(binomial) == factorial(k) * binomial(x, k)
+    assert ff(x, y).rewrite(factorial) == ff(x, y)
+    assert ff(x, y).rewrite(binomial) == ff(x, y)
+
+    import random
+    from mpmath import ff as mpmath_ff
+    for i in range(100):
+        x = -500 + 500 * random.random()
+        k = -500 + 500 * random.random()
+        a = mpmath_ff(x, k)
+        b = ff(x, k)
+        assert (abs(a - b) < abs(a) * 10**(-15))
+
+
+def test_rf_ff_eval_hiprec():
+    maple = Float('6.9109401292234329956525265438452')
+    us = ff(18, Rational(2, 3)).evalf(32)
+    assert abs(us - maple)/us < 1e-31
+
+    maple = Float('6.8261540131125511557924466355367')
+    us = rf(18, Rational(2, 3)).evalf(32)
+    assert abs(us - maple)/us < 1e-31
+
+    maple = Float('34.007346127440197150854651814225')
+    us = rf(Float('4.4', 32), Float('2.2', 32));
+    assert abs(us - maple)/us < 1e-31
+
+
+def test_rf_lambdify_mpmath():
+    from sympy.utilities.lambdify import lambdify
+    x, y = symbols('x,y')
+    f = lambdify((x,y), rf(x, y), 'mpmath')
+    maple = Float('34.007346127440197')
+    us = f(4.4, 2.2)
+    assert abs(us - maple)/us < 1e-15
+
+
+def test_factorial():
+    x = Symbol('x')
+    n = Symbol('n', integer=True)
+    k = Symbol('k', integer=True, nonnegative=True)
+    r = Symbol('r', integer=False)
+    s = Symbol('s', integer=False, negative=True)
+    t = Symbol('t', nonnegative=True)
+    u = Symbol('u', noninteger=True)
+
+    assert factorial(-2) is zoo
+    assert factorial(0) == 1
+    assert factorial(7) == 5040
+    assert factorial(19) == 121645100408832000
+    assert factorial(31) == 8222838654177922817725562880000000
+    assert factorial(n).func == factorial
+    assert factorial(2*n).func == factorial
+
+    assert factorial(x).is_integer is None
+    assert factorial(n).is_integer is None
+    assert factorial(k).is_integer
+    assert factorial(r).is_integer is None
+
+    assert factorial(n).is_positive is None
+    assert factorial(k).is_positive
+
+    assert factorial(x).is_real is None
+    assert factorial(n).is_real is None
+    assert factorial(k).is_real is True
+    assert factorial(r).is_real is None
+    assert factorial(s).is_real is True
+    assert factorial(t).is_real is True
+    assert factorial(u).is_real is True
+
+    assert factorial(x).is_composite is None
+    assert factorial(n).is_composite is None
+    assert factorial(k).is_composite is None
+    assert factorial(k + 3).is_composite is True
+    assert factorial(r).is_composite is None
+    assert factorial(s).is_composite is None
+    assert factorial(t).is_composite is None
+    assert factorial(u).is_composite is None
+
+    assert factorial(oo) is oo
+
+
+def test_factorial_Mod():
+    pr = Symbol('pr', prime=True)
+    p, q = 10**9 + 9, 10**9 + 33 # prime modulo
+    r, s = 10**7 + 5, 33333333 # composite modulo
+    assert Mod(factorial(pr - 1), pr) == pr - 1
+    assert Mod(factorial(pr - 1), -pr) == -1
+    assert Mod(factorial(r - 1, evaluate=False), r) == 0
+    assert Mod(factorial(s - 1, evaluate=False), s) == 0
+    assert Mod(factorial(p - 1, evaluate=False), p) == p - 1
+    assert Mod(factorial(q - 1, evaluate=False), q) == q - 1
+    assert Mod(factorial(p - 50, evaluate=False), p) == 854928834
+    assert Mod(factorial(q - 1800, evaluate=False), q) == 905504050
+    assert Mod(factorial(153, evaluate=False), r) == Mod(factorial(153), r)
+    assert Mod(factorial(255, evaluate=False), s) == Mod(factorial(255), s)
+    assert Mod(factorial(4, evaluate=False), 3) == S.Zero
+    assert Mod(factorial(5, evaluate=False), 6) == S.Zero
+
+
+def test_factorial_diff():
+    n = Symbol('n', integer=True)
+
+    assert factorial(n).diff(n) == \
+        gamma(1 + n)*polygamma(0, 1 + n)
+    assert factorial(n**2).diff(n) == \
+        2*n*gamma(1 + n**2)*polygamma(0, 1 + n**2)
+    raises(ArgumentIndexError, lambda: factorial(n**2).fdiff(2))
+
+
+def test_factorial_series():
+    n = Symbol('n', integer=True)
+
+    assert factorial(n).series(n, 0, 3) == \
+        1 - n*EulerGamma + n**2*(EulerGamma**2/2 + pi**2/12) + O(n**3)
+
+
+def test_factorial_rewrite():
+    n = Symbol('n', integer=True)
+    k = Symbol('k', integer=True, nonnegative=True)
+
+    assert factorial(n).rewrite(gamma) == gamma(n + 1)
+    _i = Dummy('i')
+    assert factorial(k).rewrite(Product).dummy_eq(Product(_i, (_i, 1, k)))
+    assert factorial(n).rewrite(Product) == factorial(n)
+
+
+def test_factorial2():
+    n = Symbol('n', integer=True)
+
+    assert factorial2(-1) == 1
+    assert factorial2(0) == 1
+    assert factorial2(7) == 105
+    assert factorial2(8) == 384
+
+    # The following is exhaustive
+    tt = Symbol('tt', integer=True, nonnegative=True)
+    tte = Symbol('tte', even=True, nonnegative=True)
+    tpe = Symbol('tpe', even=True, positive=True)
+    tto = Symbol('tto', odd=True, nonnegative=True)
+    tf = Symbol('tf', integer=True, nonnegative=False)
+    tfe = Symbol('tfe', even=True, nonnegative=False)
+    tfo = Symbol('tfo', odd=True, nonnegative=False)
+    ft = Symbol('ft', integer=False, nonnegative=True)
+    ff = Symbol('ff', integer=False, nonnegative=False)
+    fn = Symbol('fn', integer=False)
+    nt = Symbol('nt', nonnegative=True)
+    nf = Symbol('nf', nonnegative=False)
+    nn = Symbol('nn')
+    z = Symbol('z', zero=True)
+    #Solves and Fixes Issue #10388 - This is the updated test for the same solved issue
+    raises(ValueError, lambda: factorial2(oo))
+    raises(ValueError, lambda: factorial2(Rational(5, 2)))
+    raises(ValueError, lambda: factorial2(-4))
+    assert factorial2(n).is_integer is None
+    assert factorial2(tt - 1).is_integer
+    assert factorial2(tte - 1).is_integer
+    assert factorial2(tpe - 3).is_integer
+    assert factorial2(tto - 4).is_integer
+    assert factorial2(tto - 2).is_integer
+    assert factorial2(tf).is_integer is None
+    assert factorial2(tfe).is_integer is None
+    assert factorial2(tfo).is_integer is None
+    assert factorial2(ft).is_integer is None
+    assert factorial2(ff).is_integer is None
+    assert factorial2(fn).is_integer is None
+    assert factorial2(nt).is_integer is None
+    assert factorial2(nf).is_integer is None
+    assert factorial2(nn).is_integer is None
+
+    assert factorial2(n).is_positive is None
+    assert factorial2(tt - 1).is_positive is True
+    assert factorial2(tte - 1).is_positive is True
+    assert factorial2(tpe - 3).is_positive is True
+    assert factorial2(tpe - 1).is_positive is True
+    assert factorial2(tto - 2).is_positive is True
+    assert factorial2(tto - 1).is_positive is True
+    assert factorial2(tf).is_positive is None
+    assert factorial2(tfe).is_positive is None
+    assert factorial2(tfo).is_positive is None
+    assert factorial2(ft).is_positive is None
+    assert factorial2(ff).is_positive is None
+    assert factorial2(fn).is_positive is None
+    assert factorial2(nt).is_positive is None
+    assert factorial2(nf).is_positive is None
+    assert factorial2(nn).is_positive is None
+
+    assert factorial2(tt).is_even is None
+    assert factorial2(tt).is_odd is None
+    assert factorial2(tte).is_even is None
+    assert factorial2(tte).is_odd is None
+    assert factorial2(tte + 2).is_even is True
+    assert factorial2(tpe).is_even is True
+    assert factorial2(tpe).is_odd is False
+    assert factorial2(tto).is_odd is True
+    assert factorial2(tf).is_even is None
+    assert factorial2(tf).is_odd is None
+    assert factorial2(tfe).is_even is None
+    assert factorial2(tfe).is_odd is None
+    assert factorial2(tfo).is_even is False
+    assert factorial2(tfo).is_odd is None
+    assert factorial2(z).is_even is False
+    assert factorial2(z).is_odd is True
+
+
+def test_factorial2_rewrite():
+    n = Symbol('n', integer=True)
+    assert factorial2(n).rewrite(gamma) == \
+        2**(n/2)*Piecewise((1, Eq(Mod(n, 2), 0)), (sqrt(2)/sqrt(pi), Eq(Mod(n, 2), 1)))*gamma(n/2 + 1)
+    assert factorial2(2*n).rewrite(gamma) == 2**n*gamma(n + 1)
+    assert factorial2(2*n + 1).rewrite(gamma) == \
+        sqrt(2)*2**(n + S.Half)*gamma(n + Rational(3, 2))/sqrt(pi)
+
+
+def test_binomial():
+    x = Symbol('x')
+    n = Symbol('n', integer=True)
+    nz = Symbol('nz', integer=True, nonzero=True)
+    k = Symbol('k', integer=True)
+    kp = Symbol('kp', integer=True, positive=True)
+    kn = Symbol('kn', integer=True, negative=True)
+    u = Symbol('u', negative=True)
+    v = Symbol('v', nonnegative=True)
+    p = Symbol('p', positive=True)
+    z = Symbol('z', zero=True)
+    nt = Symbol('nt', integer=False)
+    kt = Symbol('kt', integer=False)
+    a = Symbol('a', integer=True, nonnegative=True)
+    b = Symbol('b', integer=True, nonnegative=True)
+
+    assert binomial(0, 0) == 1
+    assert binomial(1, 1) == 1
+    assert binomial(10, 10) == 1
+    assert binomial(n, z) == 1
+    assert binomial(1, 2) == 0
+    assert binomial(-1, 2) == 1
+    assert binomial(1, -1) == 0
+    assert binomial(-1, 1) == -1
+    assert binomial(-1, -1) == 0
+    assert binomial(S.Half, S.Half) == 1
+    assert binomial(-10, 1) == -10
+    assert binomial(-10, 7) == -11440
+    assert binomial(n, -1) == 0 # holds for all integers (negative, zero, positive)
+    assert binomial(kp, -1) == 0
+    assert binomial(nz, 0) == 1
+    assert expand_func(binomial(n, 1)) == n
+    assert expand_func(binomial(n, 2)) == n*(n - 1)/2
+    assert expand_func(binomial(n, n - 2)) == n*(n - 1)/2
+    assert expand_func(binomial(n, n - 1)) == n
+    assert binomial(n, 3).func == binomial
+    assert binomial(n, 3).expand(func=True) ==  n**3/6 - n**2/2 + n/3
+    assert expand_func(binomial(n, 3)) ==  n*(n - 2)*(n - 1)/6
+    assert binomial(n, n).func == binomial # e.g. (-1, -1) == 0, (2, 2) == 1
+    assert binomial(n, n + 1).func == binomial  # e.g. (-1, 0) == 1
+    assert binomial(kp, kp + 1) == 0
+    assert binomial(kn, kn) == 0 # issue #14529
+    assert binomial(n, u).func == binomial
+    assert binomial(kp, u).func == binomial
+    assert binomial(n, p).func == binomial
+    assert binomial(n, k).func == binomial
+    assert binomial(n, n + p).func == binomial
+    assert binomial(kp, kp + p).func == binomial
+
+    assert expand_func(binomial(n, n - 3)) == n*(n - 2)*(n - 1)/6
+
+    assert binomial(n, k).is_integer
+    assert binomial(nt, k).is_integer is None
+    assert binomial(x, nt).is_integer is False
+
+    assert binomial(gamma(25), 6) == 79232165267303928292058750056084441948572511312165380965440075720159859792344339983120618959044048198214221915637090855535036339620413440000
+    assert binomial(1324, 47) == 906266255662694632984994480774946083064699457235920708992926525848438478406790323869952
+    assert binomial(1735, 43) == 190910140420204130794758005450919715396159959034348676124678207874195064798202216379800
+    assert binomial(2512, 53) == 213894469313832631145798303740098720367984955243020898718979538096223399813295457822575338958939834177325304000
+    assert binomial(3383, 52) == 27922807788818096863529701501764372757272890613101645521813434902890007725667814813832027795881839396839287659777235
+    assert binomial(4321, 51) == 124595639629264868916081001263541480185227731958274383287107643816863897851139048158022599533438936036467601690983780576
+
+    assert binomial(a, b).is_nonnegative is True
+    assert binomial(-1, 2, evaluate=False).is_nonnegative is True
+    assert binomial(10, 5, evaluate=False).is_nonnegative is True
+    assert binomial(10, -3, evaluate=False).is_nonnegative is True
+    assert binomial(-10, -3, evaluate=False).is_nonnegative is True
+    assert binomial(-10, 2, evaluate=False).is_nonnegative is True
+    assert binomial(-10, 1, evaluate=False).is_nonnegative is False
+    assert binomial(-10, 7, evaluate=False).is_nonnegative is False
+
+    # issue #14625
+    for _ in (pi, -pi, nt, v, a):
+        assert binomial(_, _) == 1
+        assert binomial(_, _ - 1) == _
+    assert isinstance(binomial(u, u), binomial)
+    assert isinstance(binomial(u, u - 1), binomial)
+    assert isinstance(binomial(x, x), binomial)
+    assert isinstance(binomial(x, x - 1), binomial)
+
+    #issue #18802
+    assert expand_func(binomial(x + 1, x)) == x + 1
+    assert expand_func(binomial(x, x - 1)) == x
+    assert expand_func(binomial(x + 1, x - 1)) == x*(x + 1)/2
+    assert expand_func(binomial(x**2 + 1, x**2)) == x**2 + 1
+
+    # issue #13980 and #13981
+    assert binomial(-7, -5) == 0
+    assert binomial(-23, -12) == 0
+    assert binomial(Rational(13, 2), -10) == 0
+    assert binomial(-49, -51) == 0
+
+    assert binomial(19, Rational(-7, 2)) == S(-68719476736)/(911337863661225*pi)
+    assert binomial(0, Rational(3, 2)) == S(-2)/(3*pi)
+    assert binomial(-3, Rational(-7, 2)) is zoo
+    assert binomial(kn, kt) is zoo
+
+    assert binomial(nt, kt).func == binomial
+    assert binomial(nt, Rational(15, 6)) == 8*gamma(nt + 1)/(15*sqrt(pi)*gamma(nt - Rational(3, 2)))
+    assert binomial(Rational(20, 3), Rational(-10, 8)) == gamma(Rational(23, 3))/(gamma(Rational(-1, 4))*gamma(Rational(107, 12)))
+    assert binomial(Rational(19, 2), Rational(-7, 2)) == Rational(-1615, 8388608)
+    assert binomial(Rational(-13, 5), Rational(-7, 8)) == gamma(Rational(-8, 5))/(gamma(Rational(-29, 40))*gamma(Rational(1, 8)))
+    assert binomial(Rational(-19, 8), Rational(-13, 5)) == gamma(Rational(-11, 8))/(gamma(Rational(-8, 5))*gamma(Rational(49, 40)))
+
+    # binomial for complexes
+    assert binomial(I, Rational(-89, 8)) == gamma(1 + I)/(gamma(Rational(-81, 8))*gamma(Rational(97, 8) + I))
+    assert binomial(I, 2*I) == gamma(1 + I)/(gamma(1 - I)*gamma(1 + 2*I))
+    assert binomial(-7, I) is zoo
+    assert binomial(Rational(-7, 6), I) == gamma(Rational(-1, 6))/(gamma(Rational(-1, 6) - I)*gamma(1 + I))
+    assert binomial((1+2*I), (1+3*I)) == gamma(2 + 2*I)/(gamma(1 - I)*gamma(2 + 3*I))
+    assert binomial(I, 5) == Rational(1, 3) - I/S(12)
+    assert binomial((2*I + 3), 7) == -13*I/S(63)
+    assert isinstance(binomial(I, n), binomial)
+    assert expand_func(binomial(3, 2, evaluate=False)) == 3
+    assert expand_func(binomial(n, 0, evaluate=False)) == 1
+    assert expand_func(binomial(n, -2, evaluate=False)) == 0
+    assert expand_func(binomial(n, k)) == binomial(n, k)
+
+
+def test_binomial_Mod():
+    p, q = 10**5 + 3, 10**9 + 33 # prime modulo
+    r = 10**7 + 5 # composite modulo
+
+    # A few tests to get coverage
+    # Lucas Theorem
+    assert Mod(binomial(156675, 4433, evaluate=False), p) == Mod(binomial(156675, 4433), p)
+
+    # factorial Mod
+    assert Mod(binomial(1234, 432, evaluate=False), q) == Mod(binomial(1234, 432), q)
+
+    # binomial factorize
+    assert Mod(binomial(253, 113, evaluate=False), r) == Mod(binomial(253, 113), r)
+
+    # using Granville's generalisation of Lucas' Theorem
+    assert Mod(binomial(10**18, 10**12, evaluate=False), p*p) == 3744312326
+
+
+@slow
+def test_binomial_Mod_slow():
+    p, q = 10**5 + 3, 10**9 + 33 # prime modulo
+    r, s = 10**7 + 5, 33333333 # composite modulo
+
+    n, k, m = symbols('n k m')
+    assert (binomial(n, k) % q).subs({n: s, k: p}) == Mod(binomial(s, p), q)
+    assert (binomial(n, k) % m).subs({n: 8, k: 5, m: 13}) == 4
+    assert (binomial(9, k) % 7).subs(k, 2) == 1
+
+    # Lucas Theorem
+    assert Mod(binomial(123456, 43253, evaluate=False), p) == Mod(binomial(123456, 43253), p)
+    assert Mod(binomial(-178911, 237, evaluate=False), p) == Mod(-binomial(178911 + 237 - 1, 237), p)
+    assert Mod(binomial(-178911, 238, evaluate=False), p) == Mod(binomial(178911 + 238 - 1, 238), p)
+
+    # factorial Mod
+    assert Mod(binomial(9734, 451, evaluate=False), q) == Mod(binomial(9734, 451), q)
+    assert Mod(binomial(-10733, 4459, evaluate=False), q) == Mod(binomial(-10733, 4459), q)
+    assert Mod(binomial(-15733, 4458, evaluate=False), q) == Mod(binomial(-15733, 4458), q)
+    assert Mod(binomial(23, -38, evaluate=False), q) is S.Zero
+    assert Mod(binomial(23, 38, evaluate=False), q) is S.Zero
+
+    # binomial factorize
+    assert Mod(binomial(753, 119, evaluate=False), r) == Mod(binomial(753, 119), r)
+    assert Mod(binomial(3781, 948, evaluate=False), s) == Mod(binomial(3781, 948), s)
+    assert Mod(binomial(25773, 1793, evaluate=False), s) == Mod(binomial(25773, 1793), s)
+    assert Mod(binomial(-753, 118, evaluate=False), r) == Mod(binomial(-753, 118), r)
+    assert Mod(binomial(-25773, 1793, evaluate=False), s) == Mod(binomial(-25773, 1793), s)
+
+
+def test_binomial_diff():
+    n = Symbol('n', integer=True)
+    k = Symbol('k', integer=True)
+
+    assert binomial(n, k).diff(n) == \
+        (-polygamma(0, 1 + n - k) + polygamma(0, 1 + n))*binomial(n, k)
+    assert binomial(n**2, k**3).diff(n) == \
+        2*n*(-polygamma(
+            0, 1 + n**2 - k**3) + polygamma(0, 1 + n**2))*binomial(n**2, k**3)
+
+    assert binomial(n, k).diff(k) == \
+        (-polygamma(0, 1 + k) + polygamma(0, 1 + n - k))*binomial(n, k)
+    assert binomial(n**2, k**3).diff(k) == \
+        3*k**2*(-polygamma(
+            0, 1 + k**3) + polygamma(0, 1 + n**2 - k**3))*binomial(n**2, k**3)
+    raises(ArgumentIndexError, lambda: binomial(n, k).fdiff(3))
+
+
+def test_binomial_rewrite():
+    n = Symbol('n', integer=True)
+    k = Symbol('k', integer=True)
+    x = Symbol('x')
+
+    assert binomial(n, k).rewrite(
+        factorial) == factorial(n)/(factorial(k)*factorial(n - k))
+    assert binomial(
+        n, k).rewrite(gamma) == gamma(n + 1)/(gamma(k + 1)*gamma(n - k + 1))
+    assert binomial(n, k).rewrite(ff) == ff(n, k) / factorial(k)
+    assert binomial(n, x).rewrite(ff) == binomial(n, x)
+
+
+@XFAIL
+def test_factorial_simplify_fail():
+    # simplify(factorial(x + 1).diff(x) - ((x + 1)*factorial(x)).diff(x))) == 0
+    from sympy.abc import x
+    assert simplify(x*polygamma(0, x + 1) - x*polygamma(0, x + 2) +
+                    polygamma(0, x + 1) - polygamma(0, x + 2) + 1) == 0
+
+
+def test_subfactorial():
+    assert all(subfactorial(i) == ans for i, ans in enumerate(
+        [1, 0, 1, 2, 9, 44, 265, 1854, 14833, 133496]))
+    assert subfactorial(oo) is oo
+    assert subfactorial(nan) is nan
+    assert subfactorial(23) == 9510425471055777937262
+    assert unchanged(subfactorial, 2.2)
+
+    x = Symbol('x')
+    assert subfactorial(x).rewrite(uppergamma) == uppergamma(x + 1, -1)/S.Exp1
+
+    tt = Symbol('tt', integer=True, nonnegative=True)
+    tf = Symbol('tf', integer=True, nonnegative=False)
+    tn = Symbol('tf', integer=True)
+    ft = Symbol('ft', integer=False, nonnegative=True)
+    ff = Symbol('ff', integer=False, nonnegative=False)
+    fn = Symbol('ff', integer=False)
+    nt = Symbol('nt', nonnegative=True)
+    nf = Symbol('nf', nonnegative=False)
+    nn = Symbol('nf')
+    te = Symbol('te', even=True, nonnegative=True)
+    to = Symbol('to', odd=True, nonnegative=True)
+    assert subfactorial(tt).is_integer
+    assert subfactorial(tf).is_integer is None
+    assert subfactorial(tn).is_integer is None
+    assert subfactorial(ft).is_integer is None
+    assert subfactorial(ff).is_integer is None
+    assert subfactorial(fn).is_integer is None
+    assert subfactorial(nt).is_integer is None
+    assert subfactorial(nf).is_integer is None
+    assert subfactorial(nn).is_integer is None
+    assert subfactorial(tt).is_nonnegative
+    assert subfactorial(tf).is_nonnegative is None
+    assert subfactorial(tn).is_nonnegative is None
+    assert subfactorial(ft).is_nonnegative is None
+    assert subfactorial(ff).is_nonnegative is None
+    assert subfactorial(fn).is_nonnegative is None
+    assert subfactorial(nt).is_nonnegative is None
+    assert subfactorial(nf).is_nonnegative is None
+    assert subfactorial(nn).is_nonnegative is None
+    assert subfactorial(tt).is_even is None
+    assert subfactorial(tt).is_odd is None
+    assert subfactorial(te).is_odd is True
+    assert subfactorial(to).is_even is True

lib/python3.12/site-packages/sympy/functions/combinatorial/tests/test_comb_numbers.py

@@ -0,0 +1,1241 @@
+import string
+
+from sympy.concrete.products import Product
+from sympy.concrete.summations import Sum
+from sympy.core.function import (diff, expand_func)
+from sympy.core import (EulerGamma, TribonacciConstant)
+from sympy.core.numbers import (Float, I, Rational, oo, pi)
+from sympy.core.singleton import S
+from sympy.core.symbol import (Dummy, Symbol, symbols)
+from sympy.functions.combinatorial.numbers import carmichael
+from sympy.functions.elementary.complexes import (im, re)
+from sympy.functions.elementary.integers import floor
+from sympy.polys.polytools import cancel
+from sympy.series.limits import limit, Limit
+from sympy.series.order import O
+from sympy.functions import (
+    bernoulli, harmonic, bell, fibonacci, tribonacci, lucas, euler, catalan,
+    genocchi, andre, partition, divisor_sigma, udivisor_sigma, legendre_symbol,
+    jacobi_symbol, kronecker_symbol, mobius,
+    primenu, primeomega, totient, reduced_totient, primepi,
+    motzkin, binomial, gamma, sqrt, cbrt, hyper, log, digamma,
+    trigamma, polygamma, factorial, sin, cos, cot, polylog, zeta, dirichlet_eta)
+from sympy.functions.combinatorial.numbers import _nT
+from sympy.ntheory.factor_ import factorint
+
+from sympy.core.expr import unchanged
+from sympy.core.numbers import GoldenRatio, Integer
+
+from sympy.testing.pytest import raises, nocache_fail, warns_deprecated_sympy
+from sympy.abc import x
+
+
+def test_carmichael():
+    with warns_deprecated_sympy():
+        assert carmichael.is_prime(2821) == False
+
+
+def test_bernoulli():
+    assert bernoulli(0) == 1
+    assert bernoulli(1) == Rational(1, 2)
+    assert bernoulli(2) == Rational(1, 6)
+    assert bernoulli(3) == 0
+    assert bernoulli(4) == Rational(-1, 30)
+    assert bernoulli(5) == 0
+    assert bernoulli(6) == Rational(1, 42)
+    assert bernoulli(7) == 0
+    assert bernoulli(8) == Rational(-1, 30)
+    assert bernoulli(10) == Rational(5, 66)
+    assert bernoulli(1000001) == 0
+
+    assert bernoulli(0, x) == 1
+    assert bernoulli(1, x) == x - S.Half
+    assert bernoulli(2, x) == x**2 - x + Rational(1, 6)
+    assert bernoulli(3, x) == x**3 - (3*x**2)/2 + x/2
+
+    # Should be fast; computed with mpmath
+    b = bernoulli(1000)
+    assert b.p % 10**10 == 7950421099
+    assert b.q == 342999030
+
+    b = bernoulli(10**6, evaluate=False).evalf()
+    assert str(b) == '-2.23799235765713e+4767529'
+
+    # Issue #8527
+    l = Symbol('l', integer=True)
+    m = Symbol('m', integer=True, nonnegative=True)
+    n = Symbol('n', integer=True, positive=True)
+    assert isinstance(bernoulli(2 * l + 1), bernoulli)
+    assert isinstance(bernoulli(2 * m + 1), bernoulli)
+    assert bernoulli(2 * n + 1) == 0
+
+    assert bernoulli(x, 1) == bernoulli(x)
+
+    assert str(bernoulli(0.0, 2.3).evalf(n=10)) == '1.000000000'
+    assert str(bernoulli(1.0).evalf(n=10)) == '0.5000000000'
+    assert str(bernoulli(1.2).evalf(n=10)) == '0.4195995367'
+    assert str(bernoulli(1.2, 0.8).evalf(n=10)) == '0.2144830348'
+    assert str(bernoulli(1.2, -0.8).evalf(n=10)) == '-1.158865646 - 0.6745558744*I'
+    assert str(bernoulli(3.0, 1j).evalf(n=10)) == '1.5 - 0.5*I'
+    assert str(bernoulli(I).evalf(n=10)) == '0.9268485643 - 0.5821580598*I'
+    assert str(bernoulli(I, I).evalf(n=10)) == '0.1267792071 + 0.01947413152*I'
+    assert bernoulli(x).evalf() == bernoulli(x)
+
+
+def test_bernoulli_rewrite():
+    from sympy.functions.elementary.piecewise import Piecewise
+    n = Symbol('n', integer=True, nonnegative=True)
+
+    assert bernoulli(-1).rewrite(zeta) == pi**2/6
+    assert bernoulli(-2).rewrite(zeta) == 2*zeta(3)
+    assert not bernoulli(n, -3).rewrite(zeta).has(harmonic)
+    assert bernoulli(-4, x).rewrite(zeta) == 4*zeta(5, x)
+    assert isinstance(bernoulli(n, x).rewrite(zeta), Piecewise)
+    assert bernoulli(n+1, x).rewrite(zeta) == -(n+1) * zeta(-n, x)
+
+
+def test_fibonacci():
+    assert [fibonacci(n) for n in range(-3, 5)] == [2, -1, 1, 0, 1, 1, 2, 3]
+    assert fibonacci(100) == 354224848179261915075
+    assert [lucas(n) for n in range(-3, 5)] == [-4, 3, -1, 2, 1, 3, 4, 7]
+    assert lucas(100) == 792070839848372253127
+
+    assert fibonacci(1, x) == 1
+    assert fibonacci(2, x) == x
+    assert fibonacci(3, x) == x**2 + 1
+    assert fibonacci(4, x) == x**3 + 2*x
+
+    # issue #8800
+    n = Dummy('n')
+    assert fibonacci(n).limit(n, S.Infinity) is S.Infinity
+    assert lucas(n).limit(n, S.Infinity) is S.Infinity
+
+    assert fibonacci(n).rewrite(sqrt) == \
+        2**(-n)*sqrt(5)*((1 + sqrt(5))**n - (-sqrt(5) + 1)**n) / 5
+    assert fibonacci(n).rewrite(sqrt).subs(n, 10).expand() == fibonacci(10)
+    assert fibonacci(n).rewrite(GoldenRatio).subs(n,10).evalf() == \
+        Float(fibonacci(10))
+    assert lucas(n).rewrite(sqrt) == \
+        (fibonacci(n-1).rewrite(sqrt) + fibonacci(n+1).rewrite(sqrt)).simplify()
+    assert lucas(n).rewrite(sqrt).subs(n, 10).expand() == lucas(10)
+    raises(ValueError, lambda: fibonacci(-3, x))
+
+
+def test_tribonacci():
+    assert [tribonacci(n) for n in range(8)] == [0, 1, 1, 2, 4, 7, 13, 24]
+    assert tribonacci(100) == 98079530178586034536500564
+
+    assert tribonacci(0, x) == 0
+    assert tribonacci(1, x) == 1
+    assert tribonacci(2, x) == x**2
+    assert tribonacci(3, x) == x**4 + x
+    assert tribonacci(4, x) == x**6 + 2*x**3 + 1
+    assert tribonacci(5, x) == x**8 + 3*x**5 + 3*x**2
+
+    n = Dummy('n')
+    assert tribonacci(n).limit(n, S.Infinity) is S.Infinity
+
+    w = (-1 + S.ImaginaryUnit * sqrt(3)) / 2
+    a = (1 + cbrt(19 + 3*sqrt(33)) + cbrt(19 - 3*sqrt(33))) / 3
+    b = (1 + w*cbrt(19 + 3*sqrt(33)) + w**2*cbrt(19 - 3*sqrt(33))) / 3
+    c = (1 + w**2*cbrt(19 + 3*sqrt(33)) + w*cbrt(19 - 3*sqrt(33))) / 3
+    assert tribonacci(n).rewrite(sqrt) == \
+      (a**(n + 1)/((a - b)*(a - c))
+      + b**(n + 1)/((b - a)*(b - c))
+      + c**(n + 1)/((c - a)*(c - b)))
+    assert tribonacci(n).rewrite(sqrt).subs(n, 4).simplify() == tribonacci(4)
+    assert tribonacci(n).rewrite(GoldenRatio).subs(n,10).evalf() == \
+        Float(tribonacci(10))
+    assert tribonacci(n).rewrite(TribonacciConstant) == floor(
+            3*TribonacciConstant**n*(102*sqrt(33) + 586)**Rational(1, 3)/
+            (-2*(102*sqrt(33) + 586)**Rational(1, 3) + 4 + (102*sqrt(33)
+            + 586)**Rational(2, 3)) + S.Half)
+    raises(ValueError, lambda: tribonacci(-1, x))
+
+
+@nocache_fail
+def test_bell():
+    assert [bell(n) for n in range(8)] == [1, 1, 2, 5, 15, 52, 203, 877]
+
+    assert bell(0, x) == 1
+    assert bell(1, x) == x
+    assert bell(2, x) == x**2 + x
+    assert bell(5, x) == x**5 + 10*x**4 + 25*x**3 + 15*x**2 + x
+    assert bell(oo) is S.Infinity
+    raises(ValueError, lambda: bell(oo, x))
+
+    raises(ValueError, lambda: bell(-1))
+    raises(ValueError, lambda: bell(S.Half))
+
+    X = symbols('x:6')
+    # X = (x0, x1, .. x5)
+    # at the same time: X[1] = x1, X[2] = x2 for standard readablity.
+    # but we must supply zero-based indexed object X[1:] = (x1, .. x5)
+
+    assert bell(6, 2, X[1:]) == 6*X[5]*X[1] + 15*X[4]*X[2] + 10*X[3]**2
+    assert bell(
+        6, 3, X[1:]) == 15*X[4]*X[1]**2 + 60*X[3]*X[2]*X[1] + 15*X[2]**3
+
+    X = (1, 10, 100, 1000, 10000)
+    assert bell(6, 2, X) == (6 + 15 + 10)*10000
+
+    X = (1, 2, 3, 3, 5)
+    assert bell(6, 2, X) == 6*5 + 15*3*2 + 10*3**2
+
+    X = (1, 2, 3, 5)
+    assert bell(6, 3, X) == 15*5 + 60*3*2 + 15*2**3
+
+    # Dobinski's formula
+    n = Symbol('n', integer=True, nonnegative=True)
+    # For large numbers, this is too slow
+    # For nonintegers, there are significant precision errors
+    for i in [0, 2, 3, 7, 13, 42, 55]:
+        # Running without the cache this is either very slow or goes into an
+        # infinite loop.
+        assert bell(i).evalf() == bell(n).rewrite(Sum).evalf(subs={n: i})
+
+    m = Symbol("m")
+    assert bell(m).rewrite(Sum) == bell(m)
+    assert bell(n, m).rewrite(Sum) == bell(n, m)
+    # issue 9184
+    n = Dummy('n')
+    assert bell(n).limit(n, S.Infinity) is S.Infinity
+
+
+def test_harmonic():
+    n = Symbol("n")
+    m = Symbol("m")
+
+    assert harmonic(n, 0) == n
+    assert harmonic(n).evalf() == harmonic(n)
+    assert harmonic(n, 1) == harmonic(n)
+    assert harmonic(1, n) == 1
+
+    assert harmonic(0, 1) == 0
+    assert harmonic(1, 1) == 1
+    assert harmonic(2, 1) == Rational(3, 2)
+    assert harmonic(3, 1) == Rational(11, 6)
+    assert harmonic(4, 1) == Rational(25, 12)
+    assert harmonic(0, 2) == 0
+    assert harmonic(1, 2) == 1
+    assert harmonic(2, 2) == Rational(5, 4)
+    assert harmonic(3, 2) == Rational(49, 36)
+    assert harmonic(4, 2) == Rational(205, 144)
+    assert harmonic(0, 3) == 0
+    assert harmonic(1, 3) == 1
+    assert harmonic(2, 3) == Rational(9, 8)
+    assert harmonic(3, 3) == Rational(251, 216)
+    assert harmonic(4, 3) == Rational(2035, 1728)
+
+    assert harmonic(oo, -1) is S.NaN
+    assert harmonic(oo, 0) is oo
+    assert harmonic(oo, S.Half) is oo
+    assert harmonic(oo, 1) is oo
+    assert harmonic(oo, 2) == (pi**2)/6
+    assert harmonic(oo, 3) == zeta(3)
+    assert harmonic(oo, Dummy(negative=True)) is S.NaN
+    ip = Dummy(integer=True, positive=True)
+    if (1/ip <= 1) is True:  #---------------------------------+
+        assert None, 'delete this if-block and the next line' #|
+    ip = Dummy(even=True, positive=True)  #--------------------+
+    assert harmonic(oo, 1/ip) is oo
+    assert harmonic(oo, 1 + ip) is zeta(1 + ip)
+
+    assert harmonic(0, m) == 0
+    assert harmonic(-1, -1) == 0
+    assert harmonic(-1, 0) == -1
+    assert harmonic(-1, 1) is S.ComplexInfinity
+    assert harmonic(-1, 2) is S.NaN
+    assert harmonic(-3, -2) == -5
+    assert harmonic(-3, -3) == 9
+
+
+def test_harmonic_rational():
+    ne = S(6)
+    no = S(5)
+    pe = S(8)
+    po = S(9)
+    qe = S(10)
+    qo = S(13)
+
+    Heee = harmonic(ne + pe/qe)
+    Aeee = (-log(10) + 2*(Rational(-1, 4) + sqrt(5)/4)*log(sqrt(-sqrt(5)/8 + Rational(5, 8)))
+             + 2*(-sqrt(5)/4 - Rational(1, 4))*log(sqrt(sqrt(5)/8 + Rational(5, 8)))
+             + pi*sqrt(2*sqrt(5)/5 + 1)/2 + Rational(13944145, 4720968))
+
+    Heeo = harmonic(ne + pe/qo)
+    Aeeo = (-log(26) + 2*log(sin(pi*Rational(3, 13)))*cos(pi*Rational(4, 13)) + 2*log(sin(pi*Rational(2, 13)))*cos(pi*Rational(32, 13))
+             + 2*log(sin(pi*Rational(5, 13)))*cos(pi*Rational(80, 13)) - 2*log(sin(pi*Rational(6, 13)))*cos(pi*Rational(5, 13))
+             - 2*log(sin(pi*Rational(4, 13)))*cos(pi/13) + pi*cot(pi*Rational(5, 13))/2 - 2*log(sin(pi/13))*cos(pi*Rational(3, 13))
+             + Rational(2422020029, 702257080))
+
+    Heoe = harmonic(ne + po/qe)
+    Aeoe = (-log(20) + 2*(Rational(1, 4) + sqrt(5)/4)*log(Rational(-1, 4) + sqrt(5)/4)
+             + 2*(Rational(-1, 4) + sqrt(5)/4)*log(sqrt(-sqrt(5)/8 + Rational(5, 8)))
+             + 2*(-sqrt(5)/4 - Rational(1, 4))*log(sqrt(sqrt(5)/8 + Rational(5, 8)))
+             + 2*(-sqrt(5)/4 + Rational(1, 4))*log(Rational(1, 4) + sqrt(5)/4)
+             + Rational(11818877030, 4286604231) + pi*sqrt(2*sqrt(5) + 5)/2)
+
+    Heoo = harmonic(ne + po/qo)
+    Aeoo = (-log(26) + 2*log(sin(pi*Rational(3, 13)))*cos(pi*Rational(54, 13)) + 2*log(sin(pi*Rational(4, 13)))*cos(pi*Rational(6, 13))
+             + 2*log(sin(pi*Rational(6, 13)))*cos(pi*Rational(108, 13)) - 2*log(sin(pi*Rational(5, 13)))*cos(pi/13)
+             - 2*log(sin(pi/13))*cos(pi*Rational(5, 13)) + pi*cot(pi*Rational(4, 13))/2
+             - 2*log(sin(pi*Rational(2, 13)))*cos(pi*Rational(3, 13)) + Rational(11669332571, 3628714320))
+
+    Hoee = harmonic(no + pe/qe)
+    Aoee = (-log(10) + 2*(Rational(-1, 4) + sqrt(5)/4)*log(sqrt(-sqrt(5)/8 + Rational(5, 8)))
+             + 2*(-sqrt(5)/4 - Rational(1, 4))*log(sqrt(sqrt(5)/8 + Rational(5, 8)))
+             + pi*sqrt(2*sqrt(5)/5 + 1)/2 + Rational(779405, 277704))
+
+    Hoeo = harmonic(no + pe/qo)
+    Aoeo = (-log(26) + 2*log(sin(pi*Rational(3, 13)))*cos(pi*Rational(4, 13)) + 2*log(sin(pi*Rational(2, 13)))*cos(pi*Rational(32, 13))
+             + 2*log(sin(pi*Rational(5, 13)))*cos(pi*Rational(80, 13)) - 2*log(sin(pi*Rational(6, 13)))*cos(pi*Rational(5, 13))
+             - 2*log(sin(pi*Rational(4, 13)))*cos(pi/13) + pi*cot(pi*Rational(5, 13))/2
+             - 2*log(sin(pi/13))*cos(pi*Rational(3, 13)) + Rational(53857323, 16331560))
+
+    Hooe = harmonic(no + po/qe)
+    Aooe = (-log(20) + 2*(Rational(1, 4) + sqrt(5)/4)*log(Rational(-1, 4) + sqrt(5)/4)
+             + 2*(Rational(-1, 4) + sqrt(5)/4)*log(sqrt(-sqrt(5)/8 + Rational(5, 8)))
+             + 2*(-sqrt(5)/4 - Rational(1, 4))*log(sqrt(sqrt(5)/8 + Rational(5, 8)))
+             + 2*(-sqrt(5)/4 + Rational(1, 4))*log(Rational(1, 4) + sqrt(5)/4)
+             + Rational(486853480, 186374097) + pi*sqrt(2*sqrt(5) + 5)/2)
+
+    Hooo = harmonic(no + po/qo)
+    Aooo = (-log(26) + 2*log(sin(pi*Rational(3, 13)))*cos(pi*Rational(54, 13)) + 2*log(sin(pi*Rational(4, 13)))*cos(pi*Rational(6, 13))
+             + 2*log(sin(pi*Rational(6, 13)))*cos(pi*Rational(108, 13)) - 2*log(sin(pi*Rational(5, 13)))*cos(pi/13)
+             - 2*log(sin(pi/13))*cos(pi*Rational(5, 13)) + pi*cot(pi*Rational(4, 13))/2
+             - 2*log(sin(pi*Rational(2, 13)))*cos(3*pi/13) + Rational(383693479, 125128080))
+
+    H = [Heee, Heeo, Heoe, Heoo, Hoee, Hoeo, Hooe, Hooo]
+    A = [Aeee, Aeeo, Aeoe, Aeoo, Aoee, Aoeo, Aooe, Aooo]
+    for h, a in zip(H, A):
+        e = expand_func(h).doit()
+        assert cancel(e/a) == 1
+        assert abs(h.n() - a.n()) < 1e-12
+
+
+def test_harmonic_evalf():
+    assert str(harmonic(1.5).evalf(n=10)) == '1.280372306'
+    assert str(harmonic(1.5, 2).evalf(n=10)) == '1.154576311'  # issue 7443
+    assert str(harmonic(4.0, -3).evalf(n=10)) == '100.0000000'
+    assert str(harmonic(7.0, 1.0).evalf(n=10)) == '2.592857143'
+    assert str(harmonic(1, pi).evalf(n=10)) == '1.000000000'
+    assert str(harmonic(2, pi).evalf(n=10)) == '1.113314732'
+    assert str(harmonic(1000.0, pi).evalf(n=10)) == '1.176241563'
+    assert str(harmonic(I).evalf(n=10)) == '0.6718659855 + 1.076674047*I'
+    assert str(harmonic(I, I).evalf(n=10)) == '-0.3970915266 + 1.9629689*I'
+
+    assert harmonic(-1.0, 1).evalf() is S.NaN
+    assert harmonic(-2.0, 2.0).evalf() is S.NaN
+
+def test_harmonic_rewrite():
+    from sympy.functions.elementary.piecewise import Piecewise
+    n = Symbol("n")
+    m = Symbol("m", integer=True, positive=True)
+    x1 = Symbol("x1", positive=True)
+    x2 = Symbol("x2", negative=True)
+
+    assert harmonic(n).rewrite(digamma) == polygamma(0, n + 1) + EulerGamma
+    assert harmonic(n).rewrite(trigamma) == polygamma(0, n + 1) + EulerGamma
+    assert harmonic(n).rewrite(polygamma) == polygamma(0, n + 1) + EulerGamma
+
+    assert harmonic(n,3).rewrite(polygamma) == polygamma(2, n + 1)/2 - polygamma(2, 1)/2
+    assert isinstance(harmonic(n,m).rewrite(polygamma), Piecewise)
+
+    assert expand_func(harmonic(n+4)) == harmonic(n) + 1/(n + 4) + 1/(n + 3) + 1/(n + 2) + 1/(n + 1)
+    assert expand_func(harmonic(n-4)) == harmonic(n) - 1/(n - 1) - 1/(n - 2) - 1/(n - 3) - 1/n
+
+    assert harmonic(n, m).rewrite("tractable") == harmonic(n, m).rewrite(polygamma)
+    assert harmonic(n, x1).rewrite("tractable") == harmonic(n, x1)
+    assert harmonic(n, x1 + 1).rewrite("tractable") == zeta(x1 + 1) - zeta(x1 + 1, n + 1)
+    assert harmonic(n, x2).rewrite("tractable") == zeta(x2) - zeta(x2, n + 1)
+
+    _k = Dummy("k")
+    assert harmonic(n).rewrite(Sum).dummy_eq(Sum(1/_k, (_k, 1, n)))
+    assert harmonic(n, m).rewrite(Sum).dummy_eq(Sum(_k**(-m), (_k, 1, n)))
+
+
+def test_harmonic_calculus():
+    y = Symbol("y", positive=True)
+    z = Symbol("z", negative=True)
+    assert harmonic(x, 1).limit(x, 0) == 0
+    assert harmonic(x, y).limit(x, 0) == 0
+    assert harmonic(x, 1).series(x, y, 2) == \
+            harmonic(y) + (x - y)*zeta(2, y + 1) + O((x - y)**2, (x, y))
+    assert limit(harmonic(x, y), x, oo) == harmonic(oo, y)
+    assert limit(harmonic(x, y + 1), x, oo) == zeta(y + 1)
+    assert limit(harmonic(x, y - 1), x, oo) == harmonic(oo, y - 1)
+    assert limit(harmonic(x, z), x, oo) == Limit(harmonic(x, z), x, oo, dir='-')
+    assert limit(harmonic(x, z + 1), x, oo) == oo
+    assert limit(harmonic(x, z + 2), x, oo) == harmonic(oo, z + 2)
+    assert limit(harmonic(x, z - 1), x, oo) == Limit(harmonic(x, z - 1), x, oo, dir='-')
+
+
+def test_euler():
+    assert euler(0) == 1
+    assert euler(1) == 0
+    assert euler(2) == -1
+    assert euler(3) == 0
+    assert euler(4) == 5
+    assert euler(6) == -61
+    assert euler(8) == 1385
+
+    assert euler(20, evaluate=False) != 370371188237525
+
+    n = Symbol('n', integer=True)
+    assert euler(n) != -1
+    assert euler(n).subs(n, 2) == -1
+
+    assert euler(-1) == S.Pi / 2
+    assert euler(-1, 1) == 2*log(2)
+    assert euler(-2).evalf() == (2*S.Catalan).evalf()
+    assert euler(-3).evalf() == (S.Pi**3 / 16).evalf()
+    assert str(euler(2.3).evalf(n=10)) == '-1.052850274'
+    assert str(euler(1.2, 3.4).evalf(n=10)) == '3.575613489'
+    assert str(euler(I).evalf(n=10)) == '1.248446443 - 0.7675445124*I'
+    assert str(euler(I, I).evalf(n=10)) == '0.04812930469 + 0.01052411008*I'
+
+    assert euler(20).evalf() == 370371188237525.0
+    assert euler(20, evaluate=False).evalf() == 370371188237525.0
+
+    assert euler(n).rewrite(Sum) == euler(n)
+    n = Symbol('n', integer=True, nonnegative=True)
+    assert euler(2*n + 1).rewrite(Sum) == 0
+    _j = Dummy('j')
+    _k = Dummy('k')
+    assert euler(2*n).rewrite(Sum).dummy_eq(
+            I*Sum((-1)**_j*2**(-_k)*I**(-_k)*(-2*_j + _k)**(2*n + 1)*
+                  binomial(_k, _j)/_k, (_j, 0, _k), (_k, 1, 2*n + 1)))
+
+
+def test_euler_odd():
+    n = Symbol('n', odd=True, positive=True)
+    assert euler(n) == 0
+    n = Symbol('n', odd=True)
+    assert euler(n) != 0
+
+
+def test_euler_polynomials():
+    assert euler(0, x) == 1
+    assert euler(1, x) == x - S.Half
+    assert euler(2, x) == x**2 - x
+    assert euler(3, x) == x**3 - (3*x**2)/2 + Rational(1, 4)
+    m = Symbol('m')
+    assert isinstance(euler(m, x), euler)
+    from sympy.core.numbers import Float
+    A = Float('-0.46237208575048694923364757452876131e8')  # from Maple
+    B = euler(19, S.Pi).evalf(32)
+    assert abs((A - B)/A) < 1e-31
+
+
+def test_euler_polynomial_rewrite():
+    m = Symbol('m')
+    A = euler(m, x).rewrite('Sum');
+    assert A.subs({m:3, x:5}).doit() == euler(3, 5)
+
+
+def test_catalan():
+    n = Symbol('n', integer=True)
+    m = Symbol('m', integer=True, positive=True)
+    k = Symbol('k', integer=True, nonnegative=True)
+    p = Symbol('p', nonnegative=True)
+
+    catalans = [1, 1, 2, 5, 14, 42, 132, 429, 1430, 4862, 16796, 58786]
+    for i, c in enumerate(catalans):
+        assert catalan(i) == c
+        assert catalan(n).rewrite(factorial).subs(n, i) == c
+        assert catalan(n).rewrite(Product).subs(n, i).doit() == c
+
+    assert unchanged(catalan, x)
+    assert catalan(2*x).rewrite(binomial) == binomial(4*x, 2*x)/(2*x + 1)
+    assert catalan(S.Half).rewrite(gamma) == 8/(3*pi)
+    assert catalan(S.Half).rewrite(factorial).rewrite(gamma) ==\
+        8 / (3 * pi)
+    assert catalan(3*x).rewrite(gamma) == 4**(
+        3*x)*gamma(3*x + S.Half)/(sqrt(pi)*gamma(3*x + 2))
+    assert catalan(x).rewrite(hyper) == hyper((-x + 1, -x), (2,), 1)
+
+    assert catalan(n).rewrite(factorial) == factorial(2*n) / (factorial(n + 1)
+                                                              * factorial(n))
+    assert isinstance(catalan(n).rewrite(Product), catalan)
+    assert isinstance(catalan(m).rewrite(Product), Product)
+
+    assert diff(catalan(x), x) == (polygamma(
+        0, x + S.Half) - polygamma(0, x + 2) + log(4))*catalan(x)
+
+    assert catalan(x).evalf() == catalan(x)
+    c = catalan(S.Half).evalf()
+    assert str(c) == '0.848826363156775'
+    c = catalan(I).evalf(3)
+    assert str((re(c), im(c))) == '(0.398, -0.0209)'
+
+    # Assumptions
+    assert catalan(p).is_positive is True
+    assert catalan(k).is_integer is True
+    assert catalan(m+3).is_composite is True
+
+
+def test_genocchi():
+    genocchis = [0, -1, -1, 0, 1, 0, -3, 0, 17]
+    for n, g in enumerate(genocchis):
+        assert genocchi(n) == g
+
+    m = Symbol('m', integer=True)
+    n = Symbol('n', integer=True, positive=True)
+    assert unchanged(genocchi, m)
+    assert genocchi(2*n + 1) == 0
+    gn = 2 * (1 - 2**n) * bernoulli(n)
+    assert genocchi(n).rewrite(bernoulli).factor() == gn.factor()
+    gnx = 2 * (bernoulli(n, x) - 2**n * bernoulli(n, (x+1) / 2))
+    assert genocchi(n, x).rewrite(bernoulli).factor() == gnx.factor()
+    assert genocchi(2 * n).is_odd
+    assert genocchi(2 * n).is_even is False
+    assert genocchi(2 * n + 1).is_even
+    assert genocchi(n).is_integer
+    assert genocchi(4 * n).is_positive
+    # these are the only 2 prime Genocchi numbers
+    assert genocchi(6, evaluate=False).is_prime == S(-3).is_prime
+    assert genocchi(8, evaluate=False).is_prime
+    assert genocchi(4 * n + 2).is_negative
+    assert genocchi(4 * n + 1).is_negative is False
+    assert genocchi(4 * n - 2).is_negative
+
+    g0 = genocchi(0, evaluate=False)
+    assert g0.is_positive is False
+    assert g0.is_negative is False
+    assert g0.is_even is True
+    assert g0.is_odd is False
+
+    assert genocchi(0, x) == 0
+    assert genocchi(1, x) == -1
+    assert genocchi(2, x) == 1 - 2*x
+    assert genocchi(3, x) == 3*x - 3*x**2
+    assert genocchi(4, x) == -1 + 6*x**2 - 4*x**3
+    y = Symbol("y")
+    assert genocchi(5, (x+y)**100) == -5*(x+y)**400 + 10*(x+y)**300 - 5*(x+y)**100
+
+    assert str(genocchi(5.0, 4.0).evalf(n=10)) == '-660.0000000'
+    assert str(genocchi(Rational(5, 4)).evalf(n=10)) == '-1.104286457'
+    assert str(genocchi(-2).evalf(n=10)) == '3.606170709'
+    assert str(genocchi(1.3, 3.7).evalf(n=10)) == '-1.847375373'
+    assert str(genocchi(I, 1.0).evalf(n=10)) == '-0.3161917278 - 1.45311955*I'
+
+    n = Symbol('n')
+    assert genocchi(n, x).rewrite(dirichlet_eta) == -2*n * dirichlet_eta(1-n, x)
+
+
+def test_andre():
+    nums = [1, 1, 1, 2, 5, 16, 61, 272, 1385, 7936, 50521]
+    for n, a in enumerate(nums):
+        assert andre(n) == a
+    assert andre(S.Infinity) == S.Infinity
+    assert andre(-1) == -log(2)
+    assert andre(-2) == -2*S.Catalan
+    assert andre(-3) == 3*zeta(3)/16
+    assert andre(-5) == -15*zeta(5)/256
+    # In fact andre(-2*n) is related to the Dirichlet *beta* function
+    # at 2*n, but SymPy doesn't implement that (or general L-functions)
+    assert unchanged(andre, -4)
+
+    n = Symbol('n', integer=True, nonnegative=True)
+    assert unchanged(andre, n)
+    assert andre(n).is_integer is True
+    assert andre(n).is_positive is True
+
+    assert str(andre(10, evaluate=False).evalf(n=10)) == '50521.00000'
+    assert str(andre(-1, evaluate=False).evalf(n=10)) == '-0.6931471806'
+    assert str(andre(-2, evaluate=False).evalf(n=10)) == '-1.831931188'
+    assert str(andre(-4, evaluate=False).evalf(n=10)) == '1.977889103'
+    assert str(andre(I, evaluate=False).evalf(n=10)) == '2.378417833 + 0.6343322845*I'
+
+    assert andre(x).rewrite(polylog) == \
+            (-I)**(x+1) * polylog(-x, I) + I**(x+1) * polylog(-x, -I)
+    assert andre(x).rewrite(zeta) == \
+            2 * gamma(x+1) / (2*pi)**(x+1) * \
+            (zeta(x+1, Rational(1,4)) - cos(pi*x) * zeta(x+1, Rational(3,4)))
+
+
+@nocache_fail
+def test_partition():
+    partition_nums = [1, 1, 2, 3, 5, 7, 11, 15, 22]
+    for n, p in enumerate(partition_nums):
+        assert partition(n) == p
+
+    x = Symbol('x')
+    y = Symbol('y', real=True)
+    m = Symbol('m', integer=True)
+    n = Symbol('n', integer=True, negative=True)
+    p = Symbol('p', integer=True, nonnegative=True)
+    assert partition(m).is_integer
+    assert not partition(m).is_negative
+    assert partition(m).is_nonnegative
+    assert partition(n).is_zero
+    assert partition(p).is_positive
+    assert partition(x).subs(x, 7) == 15
+    assert partition(y).subs(y, 8) == 22
+    raises(TypeError, lambda: partition(Rational(5, 4)))
+
+
+def test_divisor_sigma():
+    # error
+    m = Symbol('m', integer=False)
+    raises(TypeError, lambda: divisor_sigma(m))
+    raises(TypeError, lambda: divisor_sigma(4.5))
+    raises(TypeError, lambda: divisor_sigma(1, m))
+    raises(TypeError, lambda: divisor_sigma(1, 4.5))
+    m = Symbol('m', positive=False)
+    raises(ValueError, lambda: divisor_sigma(m))
+    raises(ValueError, lambda: divisor_sigma(0))
+    m = Symbol('m', negative=True)
+    raises(ValueError, lambda: divisor_sigma(1, m))
+    raises(ValueError, lambda: divisor_sigma(1, -1))
+
+    # special case
+    p = Symbol('p', prime=True)
+    k = Symbol('k', integer=True)
+    assert divisor_sigma(p, 1) == p + 1
+    assert divisor_sigma(p, k) == p**k + 1
+
+    # property
+    n = Symbol('n', integer=True, positive=True)
+    assert divisor_sigma(n).is_integer is True
+    assert divisor_sigma(n).is_positive is True
+
+    # symbolic
+    k = Symbol('k', integer=True, zero=False)
+    assert divisor_sigma(4, k) == 2**(2*k) + 2**k + 1
+    assert divisor_sigma(6, k) == (2**k + 1) * (3**k + 1)
+
+    # Integer
+    assert divisor_sigma(23450) == 50592
+    assert divisor_sigma(23450, 0) == 24
+    assert divisor_sigma(23450, 1) == 50592
+    assert divisor_sigma(23450, 2) == 730747500
+    assert divisor_sigma(23450, 3) == 14666785333344
+
+
+def test_udivisor_sigma():
+    # error
+    m = Symbol('m', integer=False)
+    raises(TypeError, lambda: udivisor_sigma(m))
+    raises(TypeError, lambda: udivisor_sigma(4.5))
+    raises(TypeError, lambda: udivisor_sigma(1, m))
+    raises(TypeError, lambda: udivisor_sigma(1, 4.5))
+    m = Symbol('m', positive=False)
+    raises(ValueError, lambda: udivisor_sigma(m))
+    raises(ValueError, lambda: udivisor_sigma(0))
+    m = Symbol('m', negative=True)
+    raises(ValueError, lambda: udivisor_sigma(1, m))
+    raises(ValueError, lambda: udivisor_sigma(1, -1))
+
+    # special case
+    p = Symbol('p', prime=True)
+    k = Symbol('k', integer=True)
+    assert udivisor_sigma(p, 1) == p + 1
+    assert udivisor_sigma(p, k) == p**k + 1
+
+    # property
+    n = Symbol('n', integer=True, positive=True)
+    assert udivisor_sigma(n).is_integer is True
+    assert udivisor_sigma(n).is_positive is True
+
+    # Integer
+    A034444 = [1, 2, 2, 2, 2, 4, 2, 2, 2, 4, 2, 4, 2, 4, 4, 2, 2, 4, 2, 4,
+               4, 4, 2, 4, 2, 4, 2, 4, 2, 8, 2, 2, 4, 4, 4, 4, 2, 4, 4, 4,
+               2, 8, 2, 4, 4, 4, 2, 4, 2, 4, 4, 4, 2, 4, 4, 4, 4, 4, 2, 8]
+    for n, val in enumerate(A034444, 1):
+        assert udivisor_sigma(n, 0) == val
+    A034448 = [1, 3, 4, 5, 6, 12, 8, 9, 10, 18, 12, 20, 14, 24, 24, 17, 18,
+               30, 20, 30, 32, 36, 24, 36, 26, 42, 28, 40, 30, 72, 32, 33,
+               48, 54, 48, 50, 38, 60, 56, 54, 42, 96, 44, 60, 60, 72, 48]
+    for n, val in enumerate(A034448, 1):
+        assert udivisor_sigma(n, 1) == val
+    A034676 = [1, 5, 10, 17, 26, 50, 50, 65, 82, 130, 122, 170, 170, 250,
+               260, 257, 290, 410, 362, 442, 500, 610, 530, 650, 626, 850,
+               730, 850, 842, 1300, 962, 1025, 1220, 1450, 1300, 1394, 1370]
+    for n, val in enumerate(A034676, 1):
+        assert udivisor_sigma(n, 2) == val
+
+
+def test_legendre_symbol():
+    # error
+    m = Symbol('m', integer=False)
+    raises(TypeError, lambda: legendre_symbol(m, 3))
+    raises(TypeError, lambda: legendre_symbol(4.5, 3))
+    raises(TypeError, lambda: legendre_symbol(1, m))
+    raises(TypeError, lambda: legendre_symbol(1, 4.5))
+    m = Symbol('m', prime=False)
+    raises(ValueError, lambda: legendre_symbol(1, m))
+    raises(ValueError, lambda: legendre_symbol(1, 6))
+    m = Symbol('m', odd=False)
+    raises(ValueError, lambda: legendre_symbol(1, m))
+    raises(ValueError, lambda: legendre_symbol(1, 2))
+
+    # special case
+    p = Symbol('p', prime=True)
+    k = Symbol('k', integer=True)
+    assert legendre_symbol(p*k, p) == 0
+    assert legendre_symbol(1, p) == 1
+
+    # property
+    n = Symbol('n')
+    m = Symbol('m')
+    assert legendre_symbol(m, n).is_integer is True
+    assert legendre_symbol(m, n).is_prime is False
+
+    # Integer
+    assert legendre_symbol(5, 11) == 1
+    assert legendre_symbol(25, 41) == 1
+    assert legendre_symbol(67, 101) == -1
+    assert legendre_symbol(0, 13) == 0
+    assert legendre_symbol(9, 3) == 0
+
+
+def test_jacobi_symbol():
+    # error
+    m = Symbol('m', integer=False)
+    raises(TypeError, lambda: jacobi_symbol(m, 3))
+    raises(TypeError, lambda: jacobi_symbol(4.5, 3))
+    raises(TypeError, lambda: jacobi_symbol(1, m))
+    raises(TypeError, lambda: jacobi_symbol(1, 4.5))
+    m = Symbol('m', positive=False)
+    raises(ValueError, lambda: jacobi_symbol(1, m))
+    raises(ValueError, lambda: jacobi_symbol(1, -6))
+    m = Symbol('m', odd=False)
+    raises(ValueError, lambda: jacobi_symbol(1, m))
+    raises(ValueError, lambda: jacobi_symbol(1, 2))
+
+    # special case
+    p = Symbol('p', integer=True)
+    k = Symbol('k', integer=True)
+    assert jacobi_symbol(p*k, p) == 0
+    assert jacobi_symbol(1, p) == 1
+    assert jacobi_symbol(1, 1) == 1
+    assert jacobi_symbol(0, 1) == 1
+
+    # property
+    n = Symbol('n')
+    m = Symbol('m')
+    assert jacobi_symbol(m, n).is_integer is True
+    assert jacobi_symbol(m, n).is_prime is False
+
+    # Integer
+    assert jacobi_symbol(25, 41) == 1
+    assert jacobi_symbol(-23, 83) == -1
+    assert jacobi_symbol(3, 9) == 0
+    assert jacobi_symbol(42, 97) == -1
+    assert jacobi_symbol(3, 5) == -1
+    assert jacobi_symbol(7, 9) == 1
+    assert jacobi_symbol(0, 3) == 0
+    assert jacobi_symbol(0, 1) == 1
+    assert jacobi_symbol(2, 1) == 1
+    assert jacobi_symbol(1, 3) == 1
+
+
+def test_kronecker_symbol():
+    # error
+    m = Symbol('m', integer=False)
+    raises(TypeError, lambda: kronecker_symbol(m, 3))
+    raises(TypeError, lambda: kronecker_symbol(4.5, 3))
+    raises(TypeError, lambda: kronecker_symbol(1, m))
+    raises(TypeError, lambda: kronecker_symbol(1, 4.5))
+
+    # special case
+    p = Symbol('p', integer=True)
+    assert kronecker_symbol(1, p) == 1
+    assert kronecker_symbol(1, 1) == 1
+    assert kronecker_symbol(0, 1) == 1
+
+    # property
+    n = Symbol('n')
+    m = Symbol('m')
+    assert kronecker_symbol(m, n).is_integer is True
+    assert kronecker_symbol(m, n).is_prime is False
+
+    # Integer
+    for n in range(3, 10, 2):
+        for a in range(-n, n):
+            val = kronecker_symbol(a, n)
+            assert val == jacobi_symbol(a, n)
+            minus = kronecker_symbol(a, -n)
+            if a < 0:
+                assert -minus == val
+            else:
+                assert minus == val
+            even = kronecker_symbol(a, 2 * n)
+            if a % 2 == 0:
+                assert even == 0
+            elif a % 8 in [1, 7]:
+                assert even == val
+            else:
+                assert -even == val
+    assert kronecker_symbol(1, 0) == kronecker_symbol(-1, 0) == 1
+    assert kronecker_symbol(0, 0) == 0
+
+
+def test_mobius():
+    # error
+    m = Symbol('m', integer=False)
+    raises(TypeError, lambda: mobius(m))
+    raises(TypeError, lambda: mobius(4.5))
+    m = Symbol('m', positive=False)
+    raises(ValueError, lambda: mobius(m))
+    raises(ValueError, lambda: mobius(-3))
+
+    # special case
+    p = Symbol('p', prime=True)
+    assert mobius(p) == -1
+
+    # property
+    n = Symbol('n', integer=True, positive=True)
+    assert mobius(n).is_integer is True
+    assert mobius(n).is_prime is False
+
+    # symbolic
+    n = Symbol('n', integer=True, positive=True)
+    k = Symbol('k', integer=True, positive=True)
+    assert mobius(n**2) == 0
+    assert mobius(4*n) == 0
+    assert isinstance(mobius(n**k), mobius)
+    assert mobius(n**(k+1)) == 0
+    assert isinstance(mobius(3**k), mobius)
+    assert mobius(3**(k+1)) == 0
+    m = Symbol('m')
+    assert isinstance(mobius(4*m), mobius)
+
+    # Integer
+    assert mobius(13*7) == 1
+    assert mobius(1) == 1
+    assert mobius(13*7*5) == -1
+    assert mobius(13**2) == 0
+    A008683 = [1, -1, -1, 0, -1, 1, -1, 0, 0, 1, -1, 0, -1, 1, 1, 0, -1, 0,
+               -1, 0, 1, 1, -1, 0, 0, 1, 0, 0, -1, -1, -1, 0, 1, 1, 1, 0, -1,
+               1, 1, 0, -1, -1, -1, 0, 0, 1, -1, 0, 0, 0, 1, 0, -1, 0, 1, 0]
+    for n, val in enumerate(A008683, 1):
+        assert mobius(n) == val
+
+
+def test_primenu():
+    # error
+    m = Symbol('m', integer=False)
+    raises(TypeError, lambda: primenu(m))
+    raises(TypeError, lambda: primenu(4.5))
+    m = Symbol('m', positive=False)
+    raises(ValueError, lambda: primenu(m))
+    raises(ValueError, lambda: primenu(0))
+
+    # special case
+    p = Symbol('p', prime=True)
+    assert primenu(p) == 1
+
+    # property
+    n = Symbol('n', integer=True, positive=True)
+    assert primenu(n).is_integer is True
+    assert primenu(n).is_nonnegative is True
+
+    # Integer
+    assert primenu(7*13) == 2
+    assert primenu(2*17*19) == 3
+    assert primenu(2**3 * 17 * 19**2) == 3
+    A001221 = [0, 1, 1, 1, 1, 2, 1, 1, 1, 2, 1, 2, 1, 2, 2, 1, 1, 2,
+               1, 2, 2, 2, 1, 2, 1, 2, 1, 2, 1, 3, 1, 1, 2, 2, 2, 2]
+    for n, val in enumerate(A001221, 1):
+        assert primenu(n) == val
+
+
+def test_primeomega():
+    # error
+    m = Symbol('m', integer=False)
+    raises(TypeError, lambda: primeomega(m))
+    raises(TypeError, lambda: primeomega(4.5))
+    m = Symbol('m', positive=False)
+    raises(ValueError, lambda: primeomega(m))
+    raises(ValueError, lambda: primeomega(0))
+
+    # special case
+    p = Symbol('p', prime=True)
+    assert primeomega(p) == 1
+
+    # property
+    n = Symbol('n', integer=True, positive=True)
+    assert primeomega(n).is_integer is True
+    assert primeomega(n).is_nonnegative is True
+
+    # Integer
+    assert primeomega(7*13) == 2
+    assert primeomega(2*17*19) == 3
+    assert primeomega(2**3 * 17 * 19**2) == 6
+    A001222 = [0, 1, 1, 2, 1, 2, 1, 3, 2, 2, 1, 3, 1, 2, 2, 4, 1, 3,
+               1, 3, 2, 2, 1, 4, 2, 2, 3, 3, 1, 3, 1, 5, 2, 2, 2, 4]
+    for n, val in enumerate(A001222, 1):
+        assert primeomega(n) == val
+
+
+def test_totient():
+    # error
+    m = Symbol('m', integer=False)
+    raises(TypeError, lambda: totient(m))
+    raises(TypeError, lambda: totient(4.5))
+    m = Symbol('m', positive=False)
+    raises(ValueError, lambda: totient(m))
+    raises(ValueError, lambda: totient(0))
+
+    # special case
+    p = Symbol('p', prime=True)
+    assert totient(p) == p - 1
+
+    # property
+    n = Symbol('n', integer=True, positive=True)
+    assert totient(n).is_integer is True
+    assert totient(n).is_positive is True
+
+    # Integer
+    assert totient(7*13) == totient(factorint(7*13)) == (7-1)*(13-1)
+    assert totient(2*17*19) == totient(factorint(2*17*19)) == (17-1)*(19-1)
+    assert totient(2**3 * 17 * 19**2) == totient({2: 3, 17: 1, 19: 2}) == 2**2 * (17-1) * 19*(19-1)
+    A000010 = [1, 1, 2, 2, 4, 2, 6, 4, 6, 4, 10, 4, 12, 6, 8, 8, 16,
+               6, 18, 8, 12, 10, 22, 8, 20, 12, 18, 12, 28, 8, 30, 16,
+               20, 16, 24, 12, 36, 18, 24, 16, 40, 12, 42, 20, 24, 22]
+    for n, val in enumerate(A000010, 1):
+        assert totient(n) == val
+
+
+def test_reduced_totient():
+    # error
+    m = Symbol('m', integer=False)
+    raises(TypeError, lambda: reduced_totient(m))
+    raises(TypeError, lambda: reduced_totient(4.5))
+    m = Symbol('m', positive=False)
+    raises(ValueError, lambda: reduced_totient(m))
+    raises(ValueError, lambda: reduced_totient(0))
+
+    # special case
+    p = Symbol('p', prime=True)
+    assert reduced_totient(p) == p - 1
+
+    # property
+    n = Symbol('n', integer=True, positive=True)
+    assert reduced_totient(n).is_integer is True
+    assert reduced_totient(n).is_positive is True
+
+    # Integer
+    assert reduced_totient(7*13) == reduced_totient(factorint(7*13)) == 12
+    assert reduced_totient(2*17*19) == reduced_totient(factorint(2*17*19)) == 144
+    assert reduced_totient(2**2 * 11) == reduced_totient({2: 2, 11: 1}) == 10
+    assert reduced_totient(2**3 * 17 * 19**2) == reduced_totient({2: 3, 17: 1, 19: 2}) == 2736
+    A002322 = [1, 1, 2, 2, 4, 2, 6, 2, 6, 4, 10, 2, 12, 6, 4, 4, 16, 6,
+               18, 4, 6, 10, 22, 2, 20, 12, 18, 6, 28, 4, 30, 8, 10, 16,
+               12, 6, 36, 18, 12, 4, 40, 6, 42, 10, 12, 22, 46, 4, 42]
+    for n, val in enumerate(A002322, 1):
+        assert reduced_totient(n) == val
+
+
+def test_primepi():
+    # error
+    z = Symbol('z', real=False)
+    raises(TypeError, lambda: primepi(z))
+    raises(TypeError, lambda: primepi(I))
+
+    # property
+    n = Symbol('n', integer=True, positive=True)
+    assert primepi(n).is_integer is True
+    assert primepi(n).is_nonnegative is True
+
+    # infinity
+    assert primepi(oo) == oo
+    assert primepi(-oo) == 0
+
+    # symbol
+    x = Symbol('x')
+    assert isinstance(primepi(x), primepi)
+
+    # Integer
+    assert primepi(0) == 0
+    A000720 = [0, 1, 2, 2, 3, 3, 4, 4, 4, 4, 5, 5, 6, 6, 6, 6, 7, 7, 8,
+               8, 8, 8, 9, 9, 9, 9, 9, 9, 10, 10, 11, 11, 11, 11, 11, 11,
+               12, 12, 12, 12, 13, 13, 14, 14, 14, 14, 15, 15, 15, 15]
+    for n, val in enumerate(A000720, 1):
+        assert primepi(n) == primepi(n + 0.5) == val
+
+
+def test__nT():
+       assert [_nT(i, j) for i in range(5) for j in range(i + 2)] == [
+    1, 0, 0, 1, 0, 0, 1, 1, 0, 0, 1, 1, 1, 0, 0, 1, 2, 1, 1, 0]
+       check = [_nT(10, i) for i in range(11)]
+       assert check == [0, 1, 5, 8, 9, 7, 5, 3, 2, 1, 1]
+       assert all(type(i) is int for i in check)
+       assert _nT(10, 5) == 7
+       assert _nT(100, 98) == 2
+       assert _nT(100, 100) == 1
+       assert _nT(10, 3) == 8
+
+
+def test_nC_nP_nT():
+    from sympy.utilities.iterables import (
+        multiset_permutations, multiset_combinations, multiset_partitions,
+        partitions, subsets, permutations)
+    from sympy.functions.combinatorial.numbers import (
+        nP, nC, nT, stirling, _stirling1, _stirling2, _multiset_histogram, _AOP_product)
+
+    from sympy.combinatorics.permutations import Permutation
+    from sympy.core.random import choice
+
+    c = string.ascii_lowercase
+    for i in range(100):
+        s = ''.join(choice(c) for i in range(7))
+        u = len(s) == len(set(s))
+        try:
+            tot = 0
+            for i in range(8):
+                check = nP(s, i)
+                tot += check
+                assert len(list(multiset_permutations(s, i))) == check
+                if u:
+                    assert nP(len(s), i) == check
+            assert nP(s) == tot
+        except AssertionError:
+            print(s, i, 'failed perm test')
+            raise ValueError()
+
+    for i in range(100):
+        s = ''.join(choice(c) for i in range(7))
+        u = len(s) == len(set(s))
+        try:
+            tot = 0
+            for i in range(8):
+                check = nC(s, i)
+                tot += check
+                assert len(list(multiset_combinations(s, i))) == check
+                if u:
+                    assert nC(len(s), i) == check
+            assert nC(s) == tot
+            if u:
+                assert nC(len(s)) == tot
+        except AssertionError:
+            print(s, i, 'failed combo test')
+            raise ValueError()
+
+    for i in range(1, 10):
+        tot = 0
+        for j in range(1, i + 2):
+            check = nT(i, j)
+            assert check.is_Integer
+            tot += check
+            assert sum(1 for p in partitions(i, j, size=True) if p[0] == j) == check
+        assert nT(i) == tot
+
+    for i in range(1, 10):
+        tot = 0
+        for j in range(1, i + 2):
+            check = nT(range(i), j)
+            tot += check
+            assert len(list(multiset_partitions(list(range(i)), j))) == check
+        assert nT(range(i)) == tot
+
+    for i in range(100):
+        s = ''.join(choice(c) for i in range(7))
+        u = len(s) == len(set(s))
+        try:
+            tot = 0
+            for i in range(1, 8):
+                check = nT(s, i)
+                tot += check
+                assert len(list(multiset_partitions(s, i))) == check
+                if u:
+                    assert nT(range(len(s)), i) == check
+            if u:
+                assert nT(range(len(s))) == tot
+            assert nT(s) == tot
+        except AssertionError:
+            print(s, i, 'failed partition test')
+            raise ValueError()
+
+    # tests for Stirling numbers of the first kind that are not tested in the
+    # above
+    assert [stirling(9, i, kind=1) for i in range(11)] == [
+        0, 40320, 109584, 118124, 67284, 22449, 4536, 546, 36, 1, 0]
+    perms = list(permutations(range(4)))
+    assert [sum(1 for p in perms if Permutation(p).cycles == i)
+            for i in range(5)] == [0, 6, 11, 6, 1] == [
+            stirling(4, i, kind=1) for i in range(5)]
+    # http://oeis.org/A008275
+    assert [stirling(n, k, signed=1)
+        for n in range(10) for k in range(1, n + 1)] == [
+            1, -1,
+            1, 2, -3,
+            1, -6, 11, -6,
+            1, 24, -50, 35, -10,
+            1, -120, 274, -225, 85, -15,
+            1, 720, -1764, 1624, -735, 175, -21,
+            1, -5040, 13068, -13132, 6769, -1960, 322, -28,
+            1, 40320, -109584, 118124, -67284, 22449, -4536, 546, -36, 1]
+    # https://en.wikipedia.org/wiki/Stirling_numbers_of_the_first_kind
+    assert  [stirling(n, k, kind=1)
+        for n in range(10) for k in range(n+1)] == [
+            1,
+            0, 1,
+            0, 1, 1,
+            0, 2, 3, 1,
+            0, 6, 11, 6, 1,
+            0, 24, 50, 35, 10, 1,
+            0, 120, 274, 225, 85, 15, 1,
+            0, 720, 1764, 1624, 735, 175, 21, 1,
+            0, 5040, 13068, 13132, 6769, 1960, 322, 28, 1,
+            0, 40320, 109584, 118124, 67284, 22449, 4536, 546, 36, 1]
+    # https://en.wikipedia.org/wiki/Stirling_numbers_of_the_second_kind
+    assert [stirling(n, k, kind=2)
+        for n in range(10) for k in range(n+1)] == [
+            1,
+            0, 1,
+            0, 1, 1,
+            0, 1, 3, 1,
+            0, 1, 7, 6, 1,
+            0, 1, 15, 25, 10, 1,
+            0, 1, 31, 90, 65, 15, 1,
+            0, 1, 63, 301, 350, 140, 21, 1,
+            0, 1, 127, 966, 1701, 1050, 266, 28, 1,
+            0, 1, 255, 3025, 7770, 6951, 2646, 462, 36, 1]
+    assert stirling(3, 4, kind=1) == stirling(3, 4, kind=1) == 0
+    raises(ValueError, lambda: stirling(-2, 2))
+
+    # Assertion that the return type is SymPy Integer.
+    assert isinstance(_stirling1(6, 3), Integer)
+    assert isinstance(_stirling2(6, 3), Integer)
+
+    def delta(p):
+        if len(p) == 1:
+            return oo
+        return min(abs(i[0] - i[1]) for i in subsets(p, 2))
+    parts = multiset_partitions(range(5), 3)
+    d = 2
+    assert (sum(1 for p in parts if all(delta(i) >= d for i in p)) ==
+            stirling(5, 3, d=d) == 7)
+
+    # other coverage tests
+    assert nC('abb', 2) == nC('aab', 2) == 2
+    assert nP(3, 3, replacement=True) == nP('aabc', 3, replacement=True) == 27
+    assert nP(3, 4) == 0
+    assert nP('aabc', 5) == 0
+    assert nC(4, 2, replacement=True) == nC('abcdd', 2, replacement=True) == \
+        len(list(multiset_combinations('aabbccdd', 2))) == 10
+    assert nC('abcdd') == sum(nC('abcdd', i) for i in range(6)) == 24
+    assert nC(list('abcdd'), 4) == 4
+    assert nT('aaaa') == nT(4) == len(list(partitions(4))) == 5
+    assert nT('aaab') == len(list(multiset_partitions('aaab'))) == 7
+    assert nC('aabb'*3, 3) == 4  # aaa, bbb, abb, baa
+    assert dict(_AOP_product((4,1,1,1))) == {
+        0: 1, 1: 4, 2: 7, 3: 8, 4: 8, 5: 7, 6: 4, 7: 1}
+    # the following was the first t that showed a problem in a previous form of
+    # the function, so it's not as random as it may appear
+    t = (3, 9, 4, 6, 6, 5, 5, 2, 10, 4)
+    assert sum(_AOP_product(t)[i] for i in range(55)) == 58212000
+    raises(ValueError, lambda: _multiset_histogram({1:'a'}))
+
+
+def test_PR_14617():
+    from sympy.functions.combinatorial.numbers import nT
+    for n in (0, []):
+        for k in (-1, 0, 1):
+            if k == 0:
+                assert nT(n, k) == 1
+            else:
+                assert nT(n, k) == 0
+
+
+def test_issue_8496():
+    n = Symbol("n")
+    k = Symbol("k")
+
+    raises(TypeError, lambda: catalan(n, k))
+
+
+def test_issue_8601():
+    n = Symbol('n', integer=True, negative=True)
+
+    assert catalan(n - 1) is S.Zero
+    assert catalan(Rational(-1, 2)) is S.ComplexInfinity
+    assert catalan(-S.One) == Rational(-1, 2)
+    c1 = catalan(-5.6).evalf()
+    assert str(c1) == '6.93334070531408e-5'
+    c2 = catalan(-35.4).evalf()
+    assert str(c2) == '-4.14189164517449e-24'
+
+
+def test_motzkin():
+    assert motzkin.is_motzkin(4) == True
+    assert motzkin.is_motzkin(9) == True
+    assert motzkin.is_motzkin(10) == False
+    assert motzkin.find_motzkin_numbers_in_range(10,200) == [21, 51, 127]
+    assert motzkin.find_motzkin_numbers_in_range(10,400) == [21, 51, 127, 323]
+    assert motzkin.find_motzkin_numbers_in_range(10,1600) == [21, 51, 127, 323, 835]
+    assert motzkin.find_first_n_motzkins(5) == [1, 1, 2, 4, 9]
+    assert motzkin.find_first_n_motzkins(7) == [1, 1, 2, 4, 9, 21, 51]
+    assert motzkin.find_first_n_motzkins(10) == [1, 1, 2, 4, 9, 21, 51, 127, 323, 835]
+    raises(ValueError, lambda: motzkin.eval(77.58))
+    raises(ValueError, lambda: motzkin.eval(-8))
+    raises(ValueError, lambda: motzkin.find_motzkin_numbers_in_range(-2,7))
+    raises(ValueError, lambda: motzkin.find_motzkin_numbers_in_range(13,7))
+    raises(ValueError, lambda: motzkin.find_first_n_motzkins(112.8))
+
+
+def test_nD_derangements():
+    from sympy.utilities.iterables import (partitions, multiset,
+        multiset_derangements, multiset_permutations)
+    from sympy.functions.combinatorial.numbers import nD
+
+    got = []
+    for i in partitions(8, k=4):
+        s = []
+        it = 0
+        for k, v in i.items():
+            for i in range(v):
+                s.extend([it]*k)
+                it += 1
+        ms = multiset(s)
+        c1 = sum(1 for i in multiset_permutations(s) if
+            all(i != j for i, j in zip(i, s)))
+        assert c1 == nD(ms) == nD(ms, 0) == nD(ms, 1)
+        v = [tuple(i) for i in multiset_derangements(s)]
+        c2 = len(v)
+        assert c2 == len(set(v))
+        assert c1 == c2
+        got.append(c1)
+    assert got == [1, 4, 6, 12, 24, 24, 61, 126, 315, 780, 297, 772,
+        2033, 5430, 14833]
+
+    assert nD('1112233456', brute=True) == nD('1112233456') == 16356
+    assert nD('') == nD([]) == nD({}) == 0
+    assert nD({1: 0}) == 0
+    raises(ValueError, lambda: nD({1: -1}))
+    assert nD('112') == 0
+    assert nD(i='112') == 0
+    assert [nD(n=i) for i in range(6)] == [0, 0, 1, 2, 9, 44]
+    assert nD((i for i in range(4))) == nD('0123') == 9
+    assert nD(m=(i for i in range(4))) == 3
+    assert nD(m={0: 1, 1: 1, 2: 1, 3: 1}) == 3
+    assert nD(m=[0, 1, 2, 3]) == 3
+    raises(TypeError, lambda: nD(m=0))
+    raises(TypeError, lambda: nD(-1))
+    assert nD({-1: 1, -2: 1}) == 1
+    assert nD(m={0: 3}) == 0
+    raises(ValueError, lambda: nD(i='123', n=3))
+    raises(ValueError, lambda: nD(i='123', m=(1,2)))
+    raises(ValueError, lambda: nD(n=0, m=(1,2)))
+    raises(ValueError, lambda: nD({1: -1}))
+    raises(ValueError, lambda: nD(m={-1: 1, 2: 1}))
+    raises(ValueError, lambda: nD(m={1: -1, 2: 1}))
+    raises(ValueError, lambda: nD(m=[-1, 2]))
+    raises(TypeError, lambda: nD({1: x}))
+    raises(TypeError, lambda: nD(m={1: x}))
+    raises(TypeError, lambda: nD(m={x: 1}))
+
+
+def test_deprecated_ntheory_symbolic_functions():
+    from sympy.testing.pytest import warns_deprecated_sympy
+
+    with warns_deprecated_sympy():
+        assert not carmichael.is_carmichael(3)
+    with warns_deprecated_sympy():
+        assert carmichael.find_carmichael_numbers_in_range(10, 20) == []
+    with warns_deprecated_sympy():
+        assert carmichael.find_first_n_carmichaels(1)

lib/python3.12/site-packages/sympy/series/__init__.py

@@ -0,0 +1,23 @@
+"""A module that handles series: find a limit, order the series etc.
+"""
+from .order import Order
+from .limits import limit, Limit
+from .gruntz import gruntz
+from .series import series
+from .approximants import approximants
+from .residues import residue
+from .sequences import SeqPer, SeqFormula, sequence, SeqAdd, SeqMul
+from .fourier import fourier_series
+from .formal import fps
+from .limitseq import difference_delta, limit_seq
+
+from sympy.core.singleton import S
+EmptySequence = S.EmptySequence
+
+O = Order
+
+__all__ = ['Order', 'O', 'limit', 'Limit', 'gruntz', 'series', 'approximants',
+        'residue', 'EmptySequence', 'SeqPer', 'SeqFormula', 'sequence',
+        'SeqAdd', 'SeqMul', 'fourier_series', 'fps', 'difference_delta',
+        'limit_seq'
+        ]

lib/python3.12/site-packages/sympy/series/acceleration.py

@@ -0,0 +1,101 @@
+"""
+Convergence acceleration / extrapolation methods for series and
+sequences.
+
+References:
+Carl M. Bender & Steven A. Orszag, "Advanced Mathematical Methods for
+Scientists and Engineers: Asymptotic Methods and Perturbation Theory",
+Springer 1999. (Shanks transformation: pp. 368-375, Richardson
+extrapolation: pp. 375-377.)
+"""
+
+from sympy.core.numbers import Integer
+from sympy.core.singleton import S
+from sympy.functions.combinatorial.factorials import factorial
+
+
+def richardson(A, k, n, N):
+    """
+    Calculate an approximation for lim k->oo A(k) using Richardson
+    extrapolation with the terms A(n), A(n+1), ..., A(n+N+1).
+    Choosing N ~= 2*n often gives good results.
+
+    Examples
+    ========
+
+    A simple example is to calculate exp(1) using the limit definition.
+    This limit converges slowly; n = 100 only produces two accurate
+    digits:
+
+        >>> from sympy.abc import n
+        >>> e = (1 + 1/n)**n
+        >>> print(round(e.subs(n, 100).evalf(), 10))
+        2.7048138294
+
+    Richardson extrapolation with 11 appropriately chosen terms gives
+    a value that is accurate to the indicated precision:
+
+        >>> from sympy import E
+        >>> from sympy.series.acceleration import richardson
+        >>> print(round(richardson(e, n, 10, 20).evalf(), 10))
+        2.7182818285
+        >>> print(round(E.evalf(), 10))
+        2.7182818285
+
+    Another useful application is to speed up convergence of series.
+    Computing 100 terms of the zeta(2) series 1/k**2 yields only
+    two accurate digits:
+
+        >>> from sympy.abc import k, n
+        >>> from sympy import Sum
+        >>> A = Sum(k**-2, (k, 1, n))
+        >>> print(round(A.subs(n, 100).evalf(), 10))
+        1.6349839002
+
+    Richardson extrapolation performs much better:
+
+        >>> from sympy import pi
+        >>> print(round(richardson(A, n, 10, 20).evalf(), 10))
+        1.6449340668
+        >>> print(round(((pi**2)/6).evalf(), 10))     # Exact value
+        1.6449340668
+
+    """
+    s = S.Zero
+    for j in range(0, N + 1):
+        s += (A.subs(k, Integer(n + j)).doit() * (n + j)**N *
+              S.NegativeOne**(j + N) / (factorial(j) * factorial(N - j)))
+    return s
+
+
+def shanks(A, k, n, m=1):
+    """
+    Calculate an approximation for lim k->oo A(k) using the n-term Shanks
+    transformation S(A)(n). With m > 1, calculate the m-fold recursive
+    Shanks transformation S(S(...S(A)...))(n).
+
+    The Shanks transformation is useful for summing Taylor series that
+    converge slowly near a pole or singularity, e.g. for log(2):
+
+        >>> from sympy.abc import k, n
+        >>> from sympy import Sum, Integer
+        >>> from sympy.series.acceleration import shanks
+        >>> A = Sum(Integer(-1)**(k+1) / k, (k, 1, n))
+        >>> print(round(A.subs(n, 100).doit().evalf(), 10))
+        0.6881721793
+        >>> print(round(shanks(A, n, 25).evalf(), 10))
+        0.6931396564
+        >>> print(round(shanks(A, n, 25, 5).evalf(), 10))
+        0.6931471806
+
+    The correct value is 0.6931471805599453094172321215.
+    """
+    table = [A.subs(k, Integer(j)).doit() for j in range(n + m + 2)]
+    table2 = table[:]
+
+    for i in range(1, m + 1):
+        for j in range(i, n + m + 1):
+            x, y, z = table[j - 1], table[j], table[j + 1]
+            table2[j] = (z*x - y**2) / (z + x - 2*y)
+        table = table2[:]
+    return table[n]