Add files using upload-large-folder tool

.venv/lib/python3.13/site-packages/sympy/algebras/__init__.py

@@ -0,0 +1,3 @@
+from .quaternion import Quaternion
+
+__all__ = ["Quaternion",]

.venv/lib/python3.13/site-packages/sympy/algebras/quaternion.py

@@ -0,0 +1,1666 @@
+from sympy.core.numbers import Rational
+from sympy.core.singleton import S
+from sympy.core.relational import is_eq
+from sympy.functions.elementary.complexes import (conjugate, im, re, sign)
+from sympy.functions.elementary.exponential import (exp, log as ln)
+from sympy.functions.elementary.miscellaneous import sqrt
+from sympy.functions.elementary.trigonometric import (acos, asin, atan2)
+from sympy.functions.elementary.trigonometric import (cos, sin)
+from sympy.simplify.trigsimp import trigsimp
+from sympy.integrals.integrals import integrate
+from sympy.matrices.dense import MutableDenseMatrix as Matrix
+from sympy.core.sympify import sympify, _sympify
+from sympy.core.expr import Expr
+from sympy.core.logic import fuzzy_not, fuzzy_or
+from sympy.utilities.misc import as_int
+
+from mpmath.libmp.libmpf import prec_to_dps
+
+
+def _check_norm(elements, norm):
+    """validate if input norm is consistent"""
+    if norm is not None and norm.is_number:
+        if norm.is_positive is False:
+            raise ValueError("Input norm must be positive.")
+
+        numerical = all(i.is_number and i.is_real is True for i in elements)
+        if numerical and is_eq(norm**2, sum(i**2 for i in elements)) is False:
+            raise ValueError("Incompatible value for norm.")
+
+
+def _is_extrinsic(seq):
+    """validate seq and return True if seq is lowercase and False if uppercase"""
+    if type(seq) != str:
+        raise ValueError('Expected seq to be a string.')
+    if len(seq) != 3:
+        raise ValueError("Expected 3 axes, got `{}`.".format(seq))
+
+    intrinsic = seq.isupper()
+    extrinsic = seq.islower()
+    if not (intrinsic or extrinsic):
+        raise ValueError("seq must either be fully uppercase (for extrinsic "
+                         "rotations), or fully lowercase, for intrinsic "
+                         "rotations).")
+
+    i, j, k = seq.lower()
+    if (i == j) or (j == k):
+        raise ValueError("Consecutive axes must be different")
+
+    bad = set(seq) - set('xyzXYZ')
+    if bad:
+        raise ValueError("Expected axes from `seq` to be from "
+                         "['x', 'y', 'z'] or ['X', 'Y', 'Z'], "
+                         "got {}".format(''.join(bad)))
+
+    return extrinsic
+
+
+class Quaternion(Expr):
+    """Provides basic quaternion operations.
+    Quaternion objects can be instantiated as ``Quaternion(a, b, c, d)``
+    as in $q = a + bi + cj + dk$.
+
+    Parameters
+    ==========
+
+    norm : None or number
+        Pre-defined quaternion norm. If a value is given, Quaternion.norm
+        returns this pre-defined value instead of calculating the norm
+
+    Examples
+    ========
+
+    >>> from sympy import Quaternion
+    >>> q = Quaternion(1, 2, 3, 4)
+    >>> q
+    1 + 2*i + 3*j + 4*k
+
+    Quaternions over complex fields can be defined as:
+
+    >>> from sympy import Quaternion
+    >>> from sympy import symbols, I
+    >>> x = symbols('x')
+    >>> q1 = Quaternion(x, x**3, x, x**2, real_field = False)
+    >>> q2 = Quaternion(3 + 4*I, 2 + 5*I, 0, 7 + 8*I, real_field = False)
+    >>> q1
+    x + x**3*i + x*j + x**2*k
+    >>> q2
+    (3 + 4*I) + (2 + 5*I)*i + 0*j + (7 + 8*I)*k
+
+    Defining symbolic unit quaternions:
+
+    >>> from sympy import Quaternion
+    >>> from sympy.abc import w, x, y, z
+    >>> q = Quaternion(w, x, y, z, norm=1)
+    >>> q
+    w + x*i + y*j + z*k
+    >>> q.norm()
+    1
+
+    References
+    ==========
+
+    .. [1] https://www.euclideanspace.com/maths/algebra/realNormedAlgebra/quaternions/
+    .. [2] https://en.wikipedia.org/wiki/Quaternion
+
+    """
+    _op_priority = 11.0
+
+    is_commutative = False
+
+    def __new__(cls, a=0, b=0, c=0, d=0, real_field=True, norm=None):
+        a, b, c, d = map(sympify, (a, b, c, d))
+
+        if any(i.is_commutative is False for i in [a, b, c, d]):
+            raise ValueError("arguments have to be commutative")
+        obj = super().__new__(cls, a, b, c, d)
+        obj._real_field = real_field
+        obj.set_norm(norm)
+        return obj
+
+    def set_norm(self, norm):
+        """Sets norm of an already instantiated quaternion.
+
+        Parameters
+        ==========
+
+        norm : None or number
+            Pre-defined quaternion norm. If a value is given, Quaternion.norm
+            returns this pre-defined value instead of calculating the norm
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> from sympy.abc import a, b, c, d
+        >>> q = Quaternion(a, b, c, d)
+        >>> q.norm()
+        sqrt(a**2 + b**2 + c**2 + d**2)
+
+        Setting the norm:
+
+        >>> q.set_norm(1)
+        >>> q.norm()
+        1
+
+        Removing set norm:
+
+        >>> q.set_norm(None)
+        >>> q.norm()
+        sqrt(a**2 + b**2 + c**2 + d**2)
+
+        """
+        norm = sympify(norm)
+        _check_norm(self.args, norm)
+        self._norm = norm
+
+    @property
+    def a(self):
+        return self.args[0]
+
+    @property
+    def b(self):
+        return self.args[1]
+
+    @property
+    def c(self):
+        return self.args[2]
+
+    @property
+    def d(self):
+        return self.args[3]
+
+    @property
+    def real_field(self):
+        return self._real_field
+
+    @property
+    def product_matrix_left(self):
+        r"""Returns 4 x 4 Matrix equivalent to a Hamilton product from the
+        left. This can be useful when treating quaternion elements as column
+        vectors. Given a quaternion $q = a + bi + cj + dk$ where a, b, c and d
+        are real numbers, the product matrix from the left is:
+
+        .. math::
+
+            M  =  \begin{bmatrix} a  &-b  &-c  &-d \\
+                                  b  & a  &-d  & c \\
+                                  c  & d  & a  &-b \\
+                                  d  &-c  & b  & a \end{bmatrix}
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> from sympy.abc import a, b, c, d
+        >>> q1 = Quaternion(1, 0, 0, 1)
+        >>> q2 = Quaternion(a, b, c, d)
+        >>> q1.product_matrix_left
+        Matrix([
+        [1, 0,  0, -1],
+        [0, 1, -1,  0],
+        [0, 1,  1,  0],
+        [1, 0,  0,  1]])
+
+        >>> q1.product_matrix_left * q2.to_Matrix()
+        Matrix([
+        [a - d],
+        [b - c],
+        [b + c],
+        [a + d]])
+
+        This is equivalent to:
+
+        >>> (q1 * q2).to_Matrix()
+        Matrix([
+        [a - d],
+        [b - c],
+        [b + c],
+        [a + d]])
+        """
+        return Matrix([
+                [self.a, -self.b, -self.c, -self.d],
+                [self.b, self.a, -self.d, self.c],
+                [self.c, self.d, self.a, -self.b],
+                [self.d, -self.c, self.b, self.a]])
+
+    @property
+    def product_matrix_right(self):
+        r"""Returns 4 x 4 Matrix equivalent to a Hamilton product from the
+        right. This can be useful when treating quaternion elements as column
+        vectors. Given a quaternion $q = a + bi + cj + dk$ where a, b, c and d
+        are real numbers, the product matrix from the left is:
+
+        .. math::
+
+            M  =  \begin{bmatrix} a  &-b  &-c  &-d \\
+                                  b  & a  & d  &-c \\
+                                  c  &-d  & a  & b \\
+                                  d  & c  &-b  & a \end{bmatrix}
+
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> from sympy.abc import a, b, c, d
+        >>> q1 = Quaternion(a, b, c, d)
+        >>> q2 = Quaternion(1, 0, 0, 1)
+        >>> q2.product_matrix_right
+        Matrix([
+        [1, 0, 0, -1],
+        [0, 1, 1, 0],
+        [0, -1, 1, 0],
+        [1, 0, 0, 1]])
+
+        Note the switched arguments: the matrix represents the quaternion on
+        the right, but is still considered as a matrix multiplication from the
+        left.
+
+        >>> q2.product_matrix_right * q1.to_Matrix()
+        Matrix([
+        [ a - d],
+        [ b + c],
+        [-b + c],
+        [ a + d]])
+
+        This is equivalent to:
+
+        >>> (q1 * q2).to_Matrix()
+        Matrix([
+        [ a - d],
+        [ b + c],
+        [-b + c],
+        [ a + d]])
+        """
+        return Matrix([
+                [self.a, -self.b, -self.c, -self.d],
+                [self.b, self.a, self.d, -self.c],
+                [self.c, -self.d, self.a, self.b],
+                [self.d, self.c, -self.b, self.a]])
+
+    def to_Matrix(self, vector_only=False):
+        """Returns elements of quaternion as a column vector.
+        By default, a ``Matrix`` of length 4 is returned, with the real part as the
+        first element.
+        If ``vector_only`` is ``True``, returns only imaginary part as a Matrix of
+        length 3.
+
+        Parameters
+        ==========
+
+        vector_only : bool
+            If True, only imaginary part is returned.
+            Default value: False
+
+        Returns
+        =======
+
+        Matrix
+            A column vector constructed by the elements of the quaternion.
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> from sympy.abc import a, b, c, d
+        >>> q = Quaternion(a, b, c, d)
+        >>> q
+        a + b*i + c*j + d*k
+
+        >>> q.to_Matrix()
+        Matrix([
+        [a],
+        [b],
+        [c],
+        [d]])
+
+
+        >>> q.to_Matrix(vector_only=True)
+        Matrix([
+        [b],
+        [c],
+        [d]])
+
+        """
+        if vector_only:
+            return Matrix(self.args[1:])
+        else:
+            return Matrix(self.args)
+
+    @classmethod
+    def from_Matrix(cls, elements):
+        """Returns quaternion from elements of a column vector`.
+        If vector_only is True, returns only imaginary part as a Matrix of
+        length 3.
+
+        Parameters
+        ==========
+
+        elements : Matrix, list or tuple of length 3 or 4. If length is 3,
+            assume real part is zero.
+            Default value: False
+
+        Returns
+        =======
+
+        Quaternion
+            A quaternion created from the input elements.
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> from sympy.abc import a, b, c, d
+        >>> q = Quaternion.from_Matrix([a, b, c, d])
+        >>> q
+        a + b*i + c*j + d*k
+
+        >>> q = Quaternion.from_Matrix([b, c, d])
+        >>> q
+        0 + b*i + c*j + d*k
+
+        """
+        length = len(elements)
+        if length != 3 and length != 4:
+            raise ValueError("Input elements must have length 3 or 4, got {} "
+                             "elements".format(length))
+
+        if length == 3:
+            return Quaternion(0, *elements)
+        else:
+            return Quaternion(*elements)
+
+    @classmethod
+    def from_euler(cls, angles, seq):
+        """Returns quaternion equivalent to rotation represented by the Euler
+        angles, in the sequence defined by ``seq``.
+
+        Parameters
+        ==========
+
+        angles : list, tuple or Matrix of 3 numbers
+            The Euler angles (in radians).
+        seq : string of length 3
+            Represents the sequence of rotations.
+            For extrinsic rotations, seq must be all lowercase and its elements
+            must be from the set ``{'x', 'y', 'z'}``
+            For intrinsic rotations, seq must be all uppercase and its elements
+            must be from the set ``{'X', 'Y', 'Z'}``
+
+        Returns
+        =======
+
+        Quaternion
+            The normalized rotation quaternion calculated from the Euler angles
+            in the given sequence.
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> from sympy import pi
+        >>> q = Quaternion.from_euler([pi/2, 0, 0], 'xyz')
+        >>> q
+        sqrt(2)/2 + sqrt(2)/2*i + 0*j + 0*k
+
+        >>> q = Quaternion.from_euler([0, pi/2, pi] , 'zyz')
+        >>> q
+        0 + (-sqrt(2)/2)*i + 0*j + sqrt(2)/2*k
+
+        >>> q = Quaternion.from_euler([0, pi/2, pi] , 'ZYZ')
+        >>> q
+        0 + sqrt(2)/2*i + 0*j + sqrt(2)/2*k
+
+        """
+
+        if len(angles) != 3:
+            raise ValueError("3 angles must be given.")
+
+        extrinsic = _is_extrinsic(seq)
+        i, j, k = seq.lower()
+
+        # get elementary basis vectors
+        ei = [1 if n == i else 0 for n in 'xyz']
+        ej = [1 if n == j else 0 for n in 'xyz']
+        ek = [1 if n == k else 0 for n in 'xyz']
+
+        # calculate distinct quaternions
+        qi = cls.from_axis_angle(ei, angles[0])
+        qj = cls.from_axis_angle(ej, angles[1])
+        qk = cls.from_axis_angle(ek, angles[2])
+
+        if extrinsic:
+            return trigsimp(qk * qj * qi)
+        else:
+            return trigsimp(qi * qj * qk)
+
+    def to_euler(self, seq, angle_addition=True, avoid_square_root=False):
+        r"""Returns Euler angles representing same rotation as the quaternion,
+        in the sequence given by ``seq``. This implements the method described
+        in [1]_.
+
+        For degenerate cases (gymbal lock cases), the third angle is
+        set to zero.
+
+        Parameters
+        ==========
+
+        seq : string of length 3
+            Represents the sequence of rotations.
+            For extrinsic rotations, seq must be all lowercase and its elements
+            must be from the set ``{'x', 'y', 'z'}``
+            For intrinsic rotations, seq must be all uppercase and its elements
+            must be from the set ``{'X', 'Y', 'Z'}``
+
+        angle_addition : bool
+            When True, first and third angles are given as an addition and
+            subtraction of two simpler ``atan2`` expressions. When False, the
+            first and third angles are each given by a single more complicated
+            ``atan2`` expression. This equivalent expression is given by:
+
+            .. math::
+
+                \operatorname{atan_2} (b,a) \pm \operatorname{atan_2} (d,c) =
+                \operatorname{atan_2} (bc\pm ad, ac\mp bd)
+
+            Default value: True
+
+        avoid_square_root : bool
+            When True, the second angle is calculated with an expression based
+            on ``acos``, which is slightly more complicated but avoids a square
+            root. When False, second angle is calculated with ``atan2``, which
+            is simpler and can be better for numerical reasons (some
+            numerical implementations of ``acos`` have problems near zero).
+            Default value: False
+
+
+        Returns
+        =======
+
+        Tuple
+            The Euler angles calculated from the quaternion
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> from sympy.abc import a, b, c, d
+        >>> euler = Quaternion(a, b, c, d).to_euler('zyz')
+        >>> euler
+        (-atan2(-b, c) + atan2(d, a),
+         2*atan2(sqrt(b**2 + c**2), sqrt(a**2 + d**2)),
+         atan2(-b, c) + atan2(d, a))
+
+
+        References
+        ==========
+
+        .. [1] https://doi.org/10.1371/journal.pone.0276302
+
+        """
+        if self.is_zero_quaternion():
+            raise ValueError('Cannot convert a quaternion with norm 0.')
+
+        angles = [0, 0, 0]
+
+        extrinsic = _is_extrinsic(seq)
+        i, j, k = seq.lower()
+
+        # get index corresponding to elementary basis vectors
+        i = 'xyz'.index(i) + 1
+        j = 'xyz'.index(j) + 1
+        k = 'xyz'.index(k) + 1
+
+        if not extrinsic:
+            i, k = k, i
+
+        # check if sequence is symmetric
+        symmetric = i == k
+        if symmetric:
+            k = 6 - i - j
+
+        # parity of the permutation
+        sign = (i - j) * (j - k) * (k - i) // 2
+
+        # permutate elements
+        elements = [self.a, self.b, self.c, self.d]
+        a = elements[0]
+        b = elements[i]
+        c = elements[j]
+        d = elements[k] * sign
+
+        if not symmetric:
+            a, b, c, d = a - c, b + d, c + a, d - b
+
+        if avoid_square_root:
+            if symmetric:
+                n2 = self.norm()**2
+                angles[1] = acos((a * a + b * b - c * c - d * d) / n2)
+            else:
+                n2 = 2 * self.norm()**2
+                angles[1] = asin((c * c + d * d - a * a - b * b) / n2)
+        else:
+            angles[1] = 2 * atan2(sqrt(c * c + d * d), sqrt(a * a + b * b))
+            if not symmetric:
+                angles[1] -= S.Pi / 2
+
+        # Check for singularities in numerical cases
+        case = 0
+        if is_eq(c, S.Zero) and is_eq(d, S.Zero):
+            case = 1
+        if is_eq(a, S.Zero) and is_eq(b, S.Zero):
+            case = 2
+
+        if case == 0:
+            if angle_addition:
+                angles[0] = atan2(b, a) + atan2(d, c)
+                angles[2] = atan2(b, a) - atan2(d, c)
+            else:
+                angles[0] = atan2(b*c + a*d, a*c - b*d)
+                angles[2] = atan2(b*c - a*d, a*c + b*d)
+
+        else:  # any degenerate case
+            angles[2 * (not extrinsic)] = S.Zero
+            if case == 1:
+                angles[2 * extrinsic] = 2 * atan2(b, a)
+            else:
+                angles[2 * extrinsic] = 2 * atan2(d, c)
+                angles[2 * extrinsic] *= (-1 if extrinsic else 1)
+
+        # for Tait-Bryan angles
+        if not symmetric:
+            angles[0] *= sign
+
+        if extrinsic:
+            return tuple(angles[::-1])
+        else:
+            return tuple(angles)
+
+    @classmethod
+    def from_axis_angle(cls, vector, angle):
+        """Returns a rotation quaternion given the axis and the angle of rotation.
+
+        Parameters
+        ==========
+
+        vector : tuple of three numbers
+            The vector representation of the given axis.
+        angle : number
+            The angle by which axis is rotated (in radians).
+
+        Returns
+        =======
+
+        Quaternion
+            The normalized rotation quaternion calculated from the given axis and the angle of rotation.
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> from sympy import pi, sqrt
+        >>> q = Quaternion.from_axis_angle((sqrt(3)/3, sqrt(3)/3, sqrt(3)/3), 2*pi/3)
+        >>> q
+        1/2 + 1/2*i + 1/2*j + 1/2*k
+
+        """
+        (x, y, z) = vector
+        norm = sqrt(x**2 + y**2 + z**2)
+        (x, y, z) = (x / norm, y / norm, z / norm)
+        s = sin(angle * S.Half)
+        a = cos(angle * S.Half)
+        b = x * s
+        c = y * s
+        d = z * s
+
+        # note that this quaternion is already normalized by construction:
+        # c^2 + (s*x)^2 + (s*y)^2 + (s*z)^2 = c^2 + s^2*(x^2 + y^2 + z^2) = c^2 + s^2 * 1 = c^2 + s^2 = 1
+        # so, what we return is a normalized quaternion
+
+        return cls(a, b, c, d)
+
+    @classmethod
+    def from_rotation_matrix(cls, M):
+        """Returns the equivalent quaternion of a matrix. The quaternion will be normalized
+        only if the matrix is special orthogonal (orthogonal and det(M) = 1).
+
+        Parameters
+        ==========
+
+        M : Matrix
+            Input matrix to be converted to equivalent quaternion. M must be special
+            orthogonal (orthogonal and det(M) = 1) for the quaternion to be normalized.
+
+        Returns
+        =======
+
+        Quaternion
+            The quaternion equivalent to given matrix.
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> from sympy import Matrix, symbols, cos, sin, trigsimp
+        >>> x = symbols('x')
+        >>> M = Matrix([[cos(x), -sin(x), 0], [sin(x), cos(x), 0], [0, 0, 1]])
+        >>> q = trigsimp(Quaternion.from_rotation_matrix(M))
+        >>> q
+        sqrt(2)*sqrt(cos(x) + 1)/2 + 0*i + 0*j + sqrt(2 - 2*cos(x))*sign(sin(x))/2*k
+
+        """
+
+        absQ = M.det()**Rational(1, 3)
+
+        a = sqrt(absQ + M[0, 0] + M[1, 1] + M[2, 2]) / 2
+        b = sqrt(absQ + M[0, 0] - M[1, 1] - M[2, 2]) / 2
+        c = sqrt(absQ - M[0, 0] + M[1, 1] - M[2, 2]) / 2
+        d = sqrt(absQ - M[0, 0] - M[1, 1] + M[2, 2]) / 2
+
+        b = b * sign(M[2, 1] - M[1, 2])
+        c = c * sign(M[0, 2] - M[2, 0])
+        d = d * sign(M[1, 0] - M[0, 1])
+
+        return Quaternion(a, b, c, d)
+
+    def __add__(self, other):
+        return self.add(other)
+
+    def __radd__(self, other):
+        return self.add(other)
+
+    def __sub__(self, other):
+        return self.add(other*-1)
+
+    def __mul__(self, other):
+        return self._generic_mul(self, _sympify(other))
+
+    def __rmul__(self, other):
+        return self._generic_mul(_sympify(other), self)
+
+    def __pow__(self, p):
+        return self.pow(p)
+
+    def __neg__(self):
+        return Quaternion(-self.a, -self.b, -self.c, -self.d)
+
+    def __truediv__(self, other):
+        return self * sympify(other)**-1
+
+    def __rtruediv__(self, other):
+        return sympify(other) * self**-1
+
+    def _eval_Integral(self, *args):
+        return self.integrate(*args)
+
+    def diff(self, *symbols, **kwargs):
+        kwargs.setdefault('evaluate', True)
+        return self.func(*[a.diff(*symbols, **kwargs) for a  in self.args])
+
+    def add(self, other):
+        """Adds quaternions.
+
+        Parameters
+        ==========
+
+        other : Quaternion
+            The quaternion to add to current (self) quaternion.
+
+        Returns
+        =======
+
+        Quaternion
+            The resultant quaternion after adding self to other
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> from sympy import symbols
+        >>> q1 = Quaternion(1, 2, 3, 4)
+        >>> q2 = Quaternion(5, 6, 7, 8)
+        >>> q1.add(q2)
+        6 + 8*i + 10*j + 12*k
+        >>> q1 + 5
+        6 + 2*i + 3*j + 4*k
+        >>> x = symbols('x', real = True)
+        >>> q1.add(x)
+        (x + 1) + 2*i + 3*j + 4*k
+
+        Quaternions over complex fields :
+
+        >>> from sympy import Quaternion
+        >>> from sympy import I
+        >>> q3 = Quaternion(3 + 4*I, 2 + 5*I, 0, 7 + 8*I, real_field = False)
+        >>> q3.add(2 + 3*I)
+        (5 + 7*I) + (2 + 5*I)*i + 0*j + (7 + 8*I)*k
+
+        """
+        q1 = self
+        q2 = sympify(other)
+
+        # If q2 is a number or a SymPy expression instead of a quaternion
+        if not isinstance(q2, Quaternion):
+            if q1.real_field and q2.is_complex:
+                return Quaternion(re(q2) + q1.a, im(q2) + q1.b, q1.c, q1.d)
+            elif q2.is_commutative:
+                return Quaternion(q1.a + q2, q1.b, q1.c, q1.d)
+            else:
+                raise ValueError("Only commutative expressions can be added with a Quaternion.")
+
+        return Quaternion(q1.a + q2.a, q1.b + q2.b, q1.c + q2.c, q1.d
+                          + q2.d)
+
+    def mul(self, other):
+        """Multiplies quaternions.
+
+        Parameters
+        ==========
+
+        other : Quaternion or symbol
+            The quaternion to multiply to current (self) quaternion.
+
+        Returns
+        =======
+
+        Quaternion
+            The resultant quaternion after multiplying self with other
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> from sympy import symbols
+        >>> q1 = Quaternion(1, 2, 3, 4)
+        >>> q2 = Quaternion(5, 6, 7, 8)
+        >>> q1.mul(q2)
+        (-60) + 12*i + 30*j + 24*k
+        >>> q1.mul(2)
+        2 + 4*i + 6*j + 8*k
+        >>> x = symbols('x', real = True)
+        >>> q1.mul(x)
+        x + 2*x*i + 3*x*j + 4*x*k
+
+        Quaternions over complex fields :
+
+        >>> from sympy import Quaternion
+        >>> from sympy import I
+        >>> q3 = Quaternion(3 + 4*I, 2 + 5*I, 0, 7 + 8*I, real_field = False)
+        >>> q3.mul(2 + 3*I)
+        (2 + 3*I)*(3 + 4*I) + (2 + 3*I)*(2 + 5*I)*i + 0*j + (2 + 3*I)*(7 + 8*I)*k
+
+        """
+        return self._generic_mul(self, _sympify(other))
+
+    @staticmethod
+    def _generic_mul(q1, q2):
+        """Generic multiplication.
+
+        Parameters
+        ==========
+
+        q1 : Quaternion or symbol
+        q2 : Quaternion or symbol
+
+        It is important to note that if neither q1 nor q2 is a Quaternion,
+        this function simply returns q1 * q2.
+
+        Returns
+        =======
+
+        Quaternion
+            The resultant quaternion after multiplying q1 and q2
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> from sympy import Symbol, S
+        >>> q1 = Quaternion(1, 2, 3, 4)
+        >>> q2 = Quaternion(5, 6, 7, 8)
+        >>> Quaternion._generic_mul(q1, q2)
+        (-60) + 12*i + 30*j + 24*k
+        >>> Quaternion._generic_mul(q1, S(2))
+        2 + 4*i + 6*j + 8*k
+        >>> x = Symbol('x', real = True)
+        >>> Quaternion._generic_mul(q1, x)
+        x + 2*x*i + 3*x*j + 4*x*k
+
+        Quaternions over complex fields :
+
+        >>> from sympy import I
+        >>> q3 = Quaternion(3 + 4*I, 2 + 5*I, 0, 7 + 8*I, real_field = False)
+        >>> Quaternion._generic_mul(q3, 2 + 3*I)
+        (2 + 3*I)*(3 + 4*I) + (2 + 3*I)*(2 + 5*I)*i + 0*j + (2 + 3*I)*(7 + 8*I)*k
+
+        """
+        # None is a Quaternion:
+        if not isinstance(q1, Quaternion) and not isinstance(q2, Quaternion):
+            return q1 * q2
+
+        # If q1 is a number or a SymPy expression instead of a quaternion
+        if not isinstance(q1, Quaternion):
+            if q2.real_field and q1.is_complex:
+                return Quaternion(re(q1), im(q1), 0, 0) * q2
+            elif q1.is_commutative:
+                return Quaternion(q1 * q2.a, q1 * q2.b, q1 * q2.c, q1 * q2.d)
+            else:
+                raise ValueError("Only commutative expressions can be multiplied with a Quaternion.")
+
+        # If q2 is a number or a SymPy expression instead of a quaternion
+        if not isinstance(q2, Quaternion):
+            if q1.real_field and q2.is_complex:
+                return q1 * Quaternion(re(q2), im(q2), 0, 0)
+            elif q2.is_commutative:
+                return Quaternion(q2 * q1.a, q2 * q1.b, q2 * q1.c, q2 * q1.d)
+            else:
+                raise ValueError("Only commutative expressions can be multiplied with a Quaternion.")
+
+        # If any of the quaternions has a fixed norm, pre-compute norm
+        if q1._norm is None and q2._norm is None:
+            norm = None
+        else:
+            norm = q1.norm() * q2.norm()
+
+        return Quaternion(-q1.b*q2.b - q1.c*q2.c - q1.d*q2.d + q1.a*q2.a,
+                          q1.b*q2.a + q1.c*q2.d - q1.d*q2.c + q1.a*q2.b,
+                          -q1.b*q2.d + q1.c*q2.a + q1.d*q2.b + q1.a*q2.c,
+                          q1.b*q2.c - q1.c*q2.b + q1.d*q2.a + q1.a * q2.d,
+                          norm=norm)
+
+    def _eval_conjugate(self):
+        """Returns the conjugate of the quaternion."""
+        q = self
+        return Quaternion(q.a, -q.b, -q.c, -q.d, norm=q._norm)
+
+    def norm(self):
+        """Returns the norm of the quaternion."""
+        if self._norm is None:  # check if norm is pre-defined
+            q = self
+            # trigsimp is used to simplify sin(x)^2 + cos(x)^2 (these terms
+            # arise when from_axis_angle is used).
+            return sqrt(trigsimp(q.a**2 + q.b**2 + q.c**2 + q.d**2))
+
+        return self._norm
+
+    def normalize(self):
+        """Returns the normalized form of the quaternion."""
+        q = self
+        return q * (1/q.norm())
+
+    def inverse(self):
+        """Returns the inverse of the quaternion."""
+        q = self
+        if not q.norm():
+            raise ValueError("Cannot compute inverse for a quaternion with zero norm")
+        return conjugate(q) * (1/q.norm()**2)
+
+    def pow(self, p):
+        """Finds the pth power of the quaternion.
+
+        Parameters
+        ==========
+
+        p : int
+            Power to be applied on quaternion.
+
+        Returns
+        =======
+
+        Quaternion
+            Returns the p-th power of the current quaternion.
+            Returns the inverse if p = -1.
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> q = Quaternion(1, 2, 3, 4)
+        >>> q.pow(4)
+        668 + (-224)*i + (-336)*j + (-448)*k
+
+        """
+        try:
+            q, p = self, as_int(p)
+        except ValueError:
+            return NotImplemented
+
+        if p < 0:
+            q, p = q.inverse(), -p
+
+        if p == 1:
+            return q
+
+        res = Quaternion(1, 0, 0, 0)
+        while p > 0:
+            if p & 1:
+                res *= q
+            q *= q
+            p >>= 1
+
+        return res
+
+    def exp(self):
+        """Returns the exponential of $q$, given by $e^q$.
+
+        Returns
+        =======
+
+        Quaternion
+            The exponential of the quaternion.
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> q = Quaternion(1, 2, 3, 4)
+        >>> q.exp()
+        E*cos(sqrt(29))
+        + 2*sqrt(29)*E*sin(sqrt(29))/29*i
+        + 3*sqrt(29)*E*sin(sqrt(29))/29*j
+        + 4*sqrt(29)*E*sin(sqrt(29))/29*k
+
+        """
+        # exp(q) = e^a(cos||v|| + v/||v||*sin||v||)
+        q = self
+        vector_norm = sqrt(q.b**2 + q.c**2 + q.d**2)
+        a = exp(q.a) * cos(vector_norm)
+        b = exp(q.a) * sin(vector_norm) * q.b / vector_norm
+        c = exp(q.a) * sin(vector_norm) * q.c / vector_norm
+        d = exp(q.a) * sin(vector_norm) * q.d / vector_norm
+
+        return Quaternion(a, b, c, d)
+
+    def log(self):
+        r"""Returns the logarithm of the quaternion, given by $\log q$.
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> q = Quaternion(1, 2, 3, 4)
+        >>> q.log()
+        log(sqrt(30))
+        + 2*sqrt(29)*acos(sqrt(30)/30)/29*i
+        + 3*sqrt(29)*acos(sqrt(30)/30)/29*j
+        + 4*sqrt(29)*acos(sqrt(30)/30)/29*k
+
+        """
+        # log(q) = log||q|| + v/||v||*arccos(a/||q||)
+        q = self
+        vector_norm = sqrt(q.b**2 + q.c**2 + q.d**2)
+        q_norm = q.norm()
+        a = ln(q_norm)
+        b = q.b * acos(q.a / q_norm) / vector_norm
+        c = q.c * acos(q.a / q_norm) / vector_norm
+        d = q.d * acos(q.a / q_norm) / vector_norm
+
+        return Quaternion(a, b, c, d)
+
+    def _eval_subs(self, *args):
+        elements = [i.subs(*args) for i in self.args]
+        norm = self._norm
+        if norm is not None:
+            norm = norm.subs(*args)
+        _check_norm(elements, norm)
+        return Quaternion(*elements, norm=norm)
+
+    def _eval_evalf(self, prec):
+        """Returns the floating point approximations (decimal numbers) of the quaternion.
+
+        Returns
+        =======
+
+        Quaternion
+            Floating point approximations of quaternion(self)
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> from sympy import sqrt
+        >>> q = Quaternion(1/sqrt(1), 1/sqrt(2), 1/sqrt(3), 1/sqrt(4))
+        >>> q.evalf()
+        1.00000000000000
+        + 0.707106781186547*i
+        + 0.577350269189626*j
+        + 0.500000000000000*k
+
+        """
+        nprec = prec_to_dps(prec)
+        return Quaternion(*[arg.evalf(n=nprec) for arg in self.args])
+
+    def pow_cos_sin(self, p):
+        """Computes the pth power in the cos-sin form.
+
+        Parameters
+        ==========
+
+        p : int
+            Power to be applied on quaternion.
+
+        Returns
+        =======
+
+        Quaternion
+            The p-th power in the cos-sin form.
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> q = Quaternion(1, 2, 3, 4)
+        >>> q.pow_cos_sin(4)
+        900*cos(4*acos(sqrt(30)/30))
+        + 1800*sqrt(29)*sin(4*acos(sqrt(30)/30))/29*i
+        + 2700*sqrt(29)*sin(4*acos(sqrt(30)/30))/29*j
+        + 3600*sqrt(29)*sin(4*acos(sqrt(30)/30))/29*k
+
+        """
+        # q = ||q||*(cos(a) + u*sin(a))
+        # q^p = ||q||^p * (cos(p*a) + u*sin(p*a))
+
+        q = self
+        (v, angle) = q.to_axis_angle()
+        q2 = Quaternion.from_axis_angle(v, p * angle)
+        return q2 * (q.norm()**p)
+
+    def integrate(self, *args):
+        """Computes integration of quaternion.
+
+        Returns
+        =======
+
+        Quaternion
+            Integration of the quaternion(self) with the given variable.
+
+        Examples
+        ========
+
+        Indefinite Integral of quaternion :
+
+        >>> from sympy import Quaternion
+        >>> from sympy.abc import x
+        >>> q = Quaternion(1, 2, 3, 4)
+        >>> q.integrate(x)
+        x + 2*x*i + 3*x*j + 4*x*k
+
+        Definite integral of quaternion :
+
+        >>> from sympy import Quaternion
+        >>> from sympy.abc import x
+        >>> q = Quaternion(1, 2, 3, 4)
+        >>> q.integrate((x, 1, 5))
+        4 + 8*i + 12*j + 16*k
+
+        """
+        return Quaternion(integrate(self.a, *args), integrate(self.b, *args),
+                          integrate(self.c, *args), integrate(self.d, *args))
+
+    @staticmethod
+    def rotate_point(pin, r):
+        """Returns the coordinates of the point pin (a 3 tuple) after rotation.
+
+        Parameters
+        ==========
+
+        pin : tuple
+            A 3-element tuple of coordinates of a point which needs to be
+            rotated.
+        r : Quaternion or tuple
+            Axis and angle of rotation.
+
+            It's important to note that when r is a tuple, it must be of the form
+            (axis, angle)
+
+        Returns
+        =======
+
+        tuple
+            The coordinates of the point after rotation.
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> from sympy import symbols, trigsimp, cos, sin
+        >>> x = symbols('x')
+        >>> q = Quaternion(cos(x/2), 0, 0, sin(x/2))
+        >>> trigsimp(Quaternion.rotate_point((1, 1, 1), q))
+        (sqrt(2)*cos(x + pi/4), sqrt(2)*sin(x + pi/4), 1)
+        >>> (axis, angle) = q.to_axis_angle()
+        >>> trigsimp(Quaternion.rotate_point((1, 1, 1), (axis, angle)))
+        (sqrt(2)*cos(x + pi/4), sqrt(2)*sin(x + pi/4), 1)
+
+        """
+        if isinstance(r, tuple):
+            # if r is of the form (vector, angle)
+            q = Quaternion.from_axis_angle(r[0], r[1])
+        else:
+            # if r is a quaternion
+            q = r.normalize()
+        pout = q * Quaternion(0, pin[0], pin[1], pin[2]) * conjugate(q)
+        return (pout.b, pout.c, pout.d)
+
+    def to_axis_angle(self):
+        """Returns the axis and angle of rotation of a quaternion.
+
+        Returns
+        =======
+
+        tuple
+            Tuple of (axis, angle)
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> q = Quaternion(1, 1, 1, 1)
+        >>> (axis, angle) = q.to_axis_angle()
+        >>> axis
+        (sqrt(3)/3, sqrt(3)/3, sqrt(3)/3)
+        >>> angle
+        2*pi/3
+
+        """
+        q = self
+        if q.a.is_negative:
+            q = q * -1
+
+        q = q.normalize()
+        angle = trigsimp(2 * acos(q.a))
+
+        # Since quaternion is normalised, q.a is less than 1.
+        s = sqrt(1 - q.a*q.a)
+
+        x = trigsimp(q.b / s)
+        y = trigsimp(q.c / s)
+        z = trigsimp(q.d / s)
+
+        v = (x, y, z)
+        t = (v, angle)
+
+        return t
+
+    def to_rotation_matrix(self, v=None, homogeneous=True):
+        """Returns the equivalent rotation transformation matrix of the quaternion
+        which represents rotation about the origin if ``v`` is not passed.
+
+        Parameters
+        ==========
+
+        v : tuple or None
+            Default value: None
+        homogeneous : bool
+            When True, gives an expression that may be more efficient for
+            symbolic calculations but less so for direct evaluation. Both
+            formulas are mathematically equivalent.
+            Default value: True
+
+        Returns
+        =======
+
+        tuple
+            Returns the equivalent rotation transformation matrix of the quaternion
+            which represents rotation about the origin if v is not passed.
+
+        Examples
+        ========
+
+        >>> from sympy import Quaternion
+        >>> from sympy import symbols, trigsimp, cos, sin
+        >>> x = symbols('x')
+        >>> q = Quaternion(cos(x/2), 0, 0, sin(x/2))
+        >>> trigsimp(q.to_rotation_matrix())
+        Matrix([
+        [cos(x), -sin(x), 0],
+        [sin(x),  cos(x), 0],
+        [     0,       0, 1]])
+
+        Generates a 4x4 transformation matrix (used for rotation about a point
+        other than the origin) if the point(v) is passed as an argument.
+        """
+
+        q = self
+        s = q.norm()**-2
+
+        # diagonal elements are different according to parameter normal
+        if homogeneous:
+            m00 = s*(q.a**2 + q.b**2 - q.c**2 - q.d**2)
+            m11 = s*(q.a**2 - q.b**2 + q.c**2 - q.d**2)
+            m22 = s*(q.a**2 - q.b**2 - q.c**2 + q.d**2)
+        else:
+            m00 = 1 - 2*s*(q.c**2 + q.d**2)
+            m11 = 1 - 2*s*(q.b**2 + q.d**2)
+            m22 = 1 - 2*s*(q.b**2 + q.c**2)
+
+        m01 = 2*s*(q.b*q.c - q.d*q.a)
+        m02 = 2*s*(q.b*q.d + q.c*q.a)
+
+        m10 = 2*s*(q.b*q.c + q.d*q.a)
+        m12 = 2*s*(q.c*q.d - q.b*q.a)
+
+        m20 = 2*s*(q.b*q.d - q.c*q.a)
+        m21 = 2*s*(q.c*q.d + q.b*q.a)
+
+        if not v:
+            return Matrix([[m00, m01, m02], [m10, m11, m12], [m20, m21, m22]])
+
+        else:
+            (x, y, z) = v
+
+            m03 = x - x*m00 - y*m01 - z*m02
+            m13 = y - x*m10 - y*m11 - z*m12
+            m23 = z - x*m20 - y*m21 - z*m22
+            m30 = m31 = m32 = 0
+            m33 = 1
+
+            return Matrix([[m00, m01, m02, m03], [m10, m11, m12, m13],
+                          [m20, m21, m22, m23], [m30, m31, m32, m33]])
+
+    def scalar_part(self):
+        r"""Returns scalar part($\mathbf{S}(q)$) of the quaternion q.
+
+        Explanation
+        ===========
+
+        Given a quaternion $q = a + bi + cj + dk$, returns $\mathbf{S}(q) = a$.
+
+        Examples
+        ========
+
+        >>> from sympy.algebras.quaternion import Quaternion
+        >>> q = Quaternion(4, 8, 13, 12)
+        >>> q.scalar_part()
+        4
+
+        """
+
+        return self.a
+
+    def vector_part(self):
+        r"""
+        Returns $\mathbf{V}(q)$, the vector part of the quaternion $q$.
+
+        Explanation
+        ===========
+
+        Given a quaternion $q = a + bi + cj + dk$, returns $\mathbf{V}(q) = bi + cj + dk$.
+
+        Examples
+        ========
+
+        >>> from sympy.algebras.quaternion import Quaternion
+        >>> q = Quaternion(1, 1, 1, 1)
+        >>> q.vector_part()
+        0 + 1*i + 1*j + 1*k
+
+        >>> q = Quaternion(4, 8, 13, 12)
+        >>> q.vector_part()
+        0 + 8*i + 13*j + 12*k
+
+        """
+
+        return Quaternion(0, self.b, self.c, self.d)
+
+    def axis(self):
+        r"""
+        Returns $\mathbf{Ax}(q)$, the axis of the quaternion $q$.
+
+        Explanation
+        ===========
+
+        Given a quaternion $q = a + bi + cj + dk$, returns $\mathbf{Ax}(q)$  i.e., the versor of the vector part of that quaternion
+        equal to $\mathbf{U}[\mathbf{V}(q)]$.
+        The axis is always an imaginary unit with square equal to $-1 + 0i + 0j + 0k$.
+
+        Examples
+        ========
+
+        >>> from sympy.algebras.quaternion import Quaternion
+        >>> q = Quaternion(1, 1, 1, 1)
+        >>> q.axis()
+        0 + sqrt(3)/3*i + sqrt(3)/3*j + sqrt(3)/3*k
+
+        See Also
+        ========
+
+        vector_part
+
+        """
+        axis = self.vector_part().normalize()
+
+        return Quaternion(0, axis.b, axis.c, axis.d)
+
+    def is_pure(self):
+        """
+        Returns true if the quaternion is pure, false if the quaternion is not pure
+        or returns none if it is unknown.
+
+        Explanation
+        ===========
+
+        A pure quaternion (also a vector quaternion) is a quaternion with scalar
+        part equal to 0.
+
+        Examples
+        ========
+
+        >>> from sympy.algebras.quaternion import Quaternion
+        >>> q = Quaternion(0, 8, 13, 12)
+        >>> q.is_pure()
+        True
+
+        See Also
+        ========
+        scalar_part
+
+        """
+
+        return self.a.is_zero
+
+    def is_zero_quaternion(self):
+        """
+        Returns true if the quaternion is a zero quaternion or false if it is not a zero quaternion
+        and None if the value is unknown.
+
+        Explanation
+        ===========
+
+        A zero quaternion is a quaternion with both scalar part and
+        vector part equal to 0.
+
+        Examples
+        ========
+
+        >>> from sympy.algebras.quaternion import Quaternion
+        >>> q = Quaternion(1, 0, 0, 0)
+        >>> q.is_zero_quaternion()
+        False
+
+        >>> q = Quaternion(0, 0, 0, 0)
+        >>> q.is_zero_quaternion()
+        True
+
+        See Also
+        ========
+        scalar_part
+        vector_part
+
+        """
+
+        return self.norm().is_zero
+
+    def angle(self):
+        r"""
+        Returns the angle of the quaternion measured in the real-axis plane.
+
+        Explanation
+        ===========
+
+        Given a quaternion $q = a + bi + cj + dk$ where $a$, $b$, $c$ and $d$
+        are real numbers, returns the angle of the quaternion given by
+
+        .. math::
+            \theta := 2 \operatorname{atan_2}\left(\sqrt{b^2 + c^2 + d^2}, {a}\right)
+
+        Examples
+        ========
+
+        >>> from sympy.algebras.quaternion import Quaternion
+        >>> q = Quaternion(1, 4, 4, 4)
+        >>> q.angle()
+        2*atan(4*sqrt(3))
+
+        """
+
+        return 2 * atan2(self.vector_part().norm(), self.scalar_part())
+
+
+    def arc_coplanar(self, other):
+        """
+        Returns True if the transformation arcs represented by the input quaternions happen in the same plane.
+
+        Explanation
+        ===========
+
+        Two quaternions are said to be coplanar (in this arc sense) when their axes are parallel.
+        The plane of a quaternion is the one normal to its axis.
+
+        Parameters
+        ==========
+
+        other : a Quaternion
+
+        Returns
+        =======
+
+        True : if the planes of the two quaternions are the same, apart from its orientation/sign.
+        False : if the planes of the two quaternions are not the same, apart from its orientation/sign.
+        None : if plane of either of the quaternion is unknown.
+
+        Examples
+        ========
+
+        >>> from sympy.algebras.quaternion import Quaternion
+        >>> q1 = Quaternion(1, 4, 4, 4)
+        >>> q2 = Quaternion(3, 8, 8, 8)
+        >>> Quaternion.arc_coplanar(q1, q2)
+        True
+
+        >>> q1 = Quaternion(2, 8, 13, 12)
+        >>> Quaternion.arc_coplanar(q1, q2)
+        False
+
+        See Also
+        ========
+
+        vector_coplanar
+        is_pure
+
+        """
+        if (self.is_zero_quaternion()) or (other.is_zero_quaternion()):
+            raise ValueError('Neither of the given quaternions can be 0')
+
+        return fuzzy_or([(self.axis() - other.axis()).is_zero_quaternion(), (self.axis() + other.axis()).is_zero_quaternion()])
+
+    @classmethod
+    def vector_coplanar(cls, q1, q2, q3):
+        r"""
+        Returns True if the axis of the pure quaternions seen as 3D vectors
+        ``q1``, ``q2``, and ``q3`` are coplanar.
+
+        Explanation
+        ===========
+
+        Three pure quaternions are vector coplanar if the quaternions seen as 3D vectors are coplanar.
+
+        Parameters
+        ==========
+
+        q1
+            A pure Quaternion.
+        q2
+            A pure Quaternion.
+        q3
+            A pure Quaternion.
+
+        Returns
+        =======
+
+        True : if the axis of the pure quaternions seen as 3D vectors
+        q1, q2, and q3 are coplanar.
+        False : if the axis of the pure quaternions seen as 3D vectors
+        q1, q2, and q3 are not coplanar.
+        None : if the axis of the pure quaternions seen as 3D vectors
+        q1, q2, and q3 are coplanar is unknown.
+
+        Examples
+        ========
+
+        >>> from sympy.algebras.quaternion import Quaternion
+        >>> q1 = Quaternion(0, 4, 4, 4)
+        >>> q2 = Quaternion(0, 8, 8, 8)
+        >>> q3 = Quaternion(0, 24, 24, 24)
+        >>> Quaternion.vector_coplanar(q1, q2, q3)
+        True
+
+        >>> q1 = Quaternion(0, 8, 16, 8)
+        >>> q2 = Quaternion(0, 8, 3, 12)
+        >>> Quaternion.vector_coplanar(q1, q2, q3)
+        False
+
+        See Also
+        ========
+
+        axis
+        is_pure
+
+        """
+
+        if fuzzy_not(q1.is_pure()) or fuzzy_not(q2.is_pure()) or fuzzy_not(q3.is_pure()):
+            raise ValueError('The given quaternions must be pure')
+
+        M = Matrix([[q1.b, q1.c, q1.d], [q2.b, q2.c, q2.d], [q3.b, q3.c, q3.d]]).det()
+        return M.is_zero
+
+    def parallel(self, other):
+        """
+        Returns True if the two pure quaternions seen as 3D vectors are parallel.
+
+        Explanation
+        ===========
+
+        Two pure quaternions are called parallel when their vector product is commutative which
+        implies that the quaternions seen as 3D vectors have same direction.
+
+        Parameters
+        ==========
+
+        other : a Quaternion
+
+        Returns
+        =======
+
+        True : if the two pure quaternions seen as 3D vectors are parallel.
+        False : if the two pure quaternions seen as 3D vectors are not parallel.
+        None : if the two pure quaternions seen as 3D vectors are parallel is unknown.
+
+        Examples
+        ========
+
+        >>> from sympy.algebras.quaternion import Quaternion
+        >>> q = Quaternion(0, 4, 4, 4)
+        >>> q1 = Quaternion(0, 8, 8, 8)
+        >>> q.parallel(q1)
+        True
+
+        >>> q1 = Quaternion(0, 8, 13, 12)
+        >>> q.parallel(q1)
+        False
+
+        """
+
+        if fuzzy_not(self.is_pure()) or fuzzy_not(other.is_pure()):
+            raise ValueError('The provided quaternions must be pure')
+
+        return (self*other - other*self).is_zero_quaternion()
+
+    def orthogonal(self, other):
+        """
+        Returns the orthogonality of two quaternions.
+
+        Explanation
+        ===========
+
+        Two pure quaternions are called orthogonal when their product is anti-commutative.
+
+        Parameters
+        ==========
+
+        other : a Quaternion
+
+        Returns
+        =======
+
+        True : if the two pure quaternions seen as 3D vectors are orthogonal.
+        False : if the two pure quaternions seen as 3D vectors are not orthogonal.
+        None : if the two pure quaternions seen as 3D vectors are orthogonal is unknown.
+
+        Examples
+        ========
+
+        >>> from sympy.algebras.quaternion import Quaternion
+        >>> q = Quaternion(0, 4, 4, 4)
+        >>> q1 = Quaternion(0, 8, 8, 8)
+        >>> q.orthogonal(q1)
+        False
+
+        >>> q1 = Quaternion(0, 2, 2, 0)
+        >>> q = Quaternion(0, 2, -2, 0)
+        >>> q.orthogonal(q1)
+        True
+
+        """
+
+        if fuzzy_not(self.is_pure()) or fuzzy_not(other.is_pure()):
+            raise ValueError('The given quaternions must be pure')
+
+        return (self*other + other*self).is_zero_quaternion()
+
+    def index_vector(self):
+        r"""
+        Returns the index vector of the quaternion.
+
+        Explanation
+        ===========
+
+        The index vector is given by $\mathbf{T}(q)$, the norm (or magnitude) of
+        the quaternion $q$, multiplied by $\mathbf{Ax}(q)$, the axis of $q$.
+
+        Returns
+        =======
+
+        Quaternion: representing index vector of the provided quaternion.
+
+        Examples
+        ========
+
+        >>> from sympy.algebras.quaternion import Quaternion
+        >>> q = Quaternion(2, 4, 2, 4)
+        >>> q.index_vector()
+        0 + 4*sqrt(10)/3*i + 2*sqrt(10)/3*j + 4*sqrt(10)/3*k
+
+        See Also
+        ========
+
+        axis
+        norm
+
+        """
+
+        return self.norm() * self.axis()
+
+    def mensor(self):
+        """
+        Returns the natural logarithm of the norm(magnitude) of the quaternion.
+
+        Examples
+        ========
+
+        >>> from sympy.algebras.quaternion import Quaternion
+        >>> q = Quaternion(2, 4, 2, 4)
+        >>> q.mensor()
+        log(2*sqrt(10))
+        >>> q.norm()
+        2*sqrt(10)
+
+        See Also
+        ========
+
+        norm
+
+        """
+
+        return ln(self.norm())

.venv/lib/python3.13/site-packages/sympy/assumptions/__init__.py

@@ -0,0 +1,18 @@
+"""
+A module to implement logical predicates and assumption system.
+"""
+
+from .assume import (
+    AppliedPredicate, Predicate, AssumptionsContext, assuming,
+    global_assumptions
+)
+from .ask import Q, ask, register_handler, remove_handler
+from .refine import refine
+from .relation import BinaryRelation, AppliedBinaryRelation
+
+__all__ = [
+    'AppliedPredicate', 'Predicate', 'AssumptionsContext', 'assuming',
+    'global_assumptions', 'Q', 'ask', 'register_handler', 'remove_handler',
+    'refine',
+    'BinaryRelation', 'AppliedBinaryRelation'
+]

.venv/lib/python3.13/site-packages/sympy/assumptions/ask.py

@@ -0,0 +1,651 @@
+"""Module for querying SymPy objects about assumptions."""
+
+from sympy.assumptions.assume import (global_assumptions, Predicate,
+        AppliedPredicate)
+from sympy.assumptions.cnf import CNF, EncodedCNF, Literal
+from sympy.core import sympify
+from sympy.core.kind import BooleanKind
+from sympy.core.relational import Eq, Ne, Gt, Lt, Ge, Le
+from sympy.logic.inference import satisfiable
+from sympy.utilities.decorator import memoize_property
+from sympy.utilities.exceptions import (sympy_deprecation_warning,
+                                        SymPyDeprecationWarning,
+                                        ignore_warnings)
+
+
+# Memoization is necessary for the properties of AssumptionKeys to
+# ensure that only one object of Predicate objects are created.
+# This is because assumption handlers are registered on those objects.
+
+
+class AssumptionKeys:
+    """
+    This class contains all the supported keys by ``ask``.
+    It should be accessed via the instance ``sympy.Q``.
+
+    """
+
+    # DO NOT add methods or properties other than predicate keys.
+    # SAT solver checks the properties of Q and use them to compute the
+    # fact system. Non-predicate attributes will break this.
+
+    @memoize_property
+    def hermitian(self):
+        from .handlers.sets import HermitianPredicate
+        return HermitianPredicate()
+
+    @memoize_property
+    def antihermitian(self):
+        from .handlers.sets import AntihermitianPredicate
+        return AntihermitianPredicate()
+
+    @memoize_property
+    def real(self):
+        from .handlers.sets import RealPredicate
+        return RealPredicate()
+
+    @memoize_property
+    def extended_real(self):
+        from .handlers.sets import ExtendedRealPredicate
+        return ExtendedRealPredicate()
+
+    @memoize_property
+    def imaginary(self):
+        from .handlers.sets import ImaginaryPredicate
+        return ImaginaryPredicate()
+
+    @memoize_property
+    def complex(self):
+        from .handlers.sets import ComplexPredicate
+        return ComplexPredicate()
+
+    @memoize_property
+    def algebraic(self):
+        from .handlers.sets import AlgebraicPredicate
+        return AlgebraicPredicate()
+
+    @memoize_property
+    def transcendental(self):
+        from .predicates.sets import TranscendentalPredicate
+        return TranscendentalPredicate()
+
+    @memoize_property
+    def integer(self):
+        from .handlers.sets import IntegerPredicate
+        return IntegerPredicate()
+
+    @memoize_property
+    def noninteger(self):
+        from .predicates.sets import NonIntegerPredicate
+        return NonIntegerPredicate()
+
+    @memoize_property
+    def rational(self):
+        from .handlers.sets import RationalPredicate
+        return RationalPredicate()
+
+    @memoize_property
+    def irrational(self):
+        from .handlers.sets import IrrationalPredicate
+        return IrrationalPredicate()
+
+    @memoize_property
+    def finite(self):
+        from .handlers.calculus import FinitePredicate
+        return FinitePredicate()
+
+    @memoize_property
+    def infinite(self):
+        from .handlers.calculus import InfinitePredicate
+        return InfinitePredicate()
+
+    @memoize_property
+    def positive_infinite(self):
+        from .handlers.calculus import PositiveInfinitePredicate
+        return PositiveInfinitePredicate()
+
+    @memoize_property
+    def negative_infinite(self):
+        from .handlers.calculus import NegativeInfinitePredicate
+        return NegativeInfinitePredicate()
+
+    @memoize_property
+    def positive(self):
+        from .handlers.order import PositivePredicate
+        return PositivePredicate()
+
+    @memoize_property
+    def negative(self):
+        from .handlers.order import NegativePredicate
+        return NegativePredicate()
+
+    @memoize_property
+    def zero(self):
+        from .handlers.order import ZeroPredicate
+        return ZeroPredicate()
+
+    @memoize_property
+    def extended_positive(self):
+        from .handlers.order import ExtendedPositivePredicate
+        return ExtendedPositivePredicate()
+
+    @memoize_property
+    def extended_negative(self):
+        from .handlers.order import ExtendedNegativePredicate
+        return ExtendedNegativePredicate()
+
+    @memoize_property
+    def nonzero(self):
+        from .handlers.order import NonZeroPredicate
+        return NonZeroPredicate()
+
+    @memoize_property
+    def nonpositive(self):
+        from .handlers.order import NonPositivePredicate
+        return NonPositivePredicate()
+
+    @memoize_property
+    def nonnegative(self):
+        from .handlers.order import NonNegativePredicate
+        return NonNegativePredicate()
+
+    @memoize_property
+    def extended_nonzero(self):
+        from .handlers.order import ExtendedNonZeroPredicate
+        return ExtendedNonZeroPredicate()
+
+    @memoize_property
+    def extended_nonpositive(self):
+        from .handlers.order import ExtendedNonPositivePredicate
+        return ExtendedNonPositivePredicate()
+
+    @memoize_property
+    def extended_nonnegative(self):
+        from .handlers.order import ExtendedNonNegativePredicate
+        return ExtendedNonNegativePredicate()
+
+    @memoize_property
+    def even(self):
+        from .handlers.ntheory import EvenPredicate
+        return EvenPredicate()
+
+    @memoize_property
+    def odd(self):
+        from .handlers.ntheory import OddPredicate
+        return OddPredicate()
+
+    @memoize_property
+    def prime(self):
+        from .handlers.ntheory import PrimePredicate
+        return PrimePredicate()
+
+    @memoize_property
+    def composite(self):
+        from .handlers.ntheory import CompositePredicate
+        return CompositePredicate()
+
+    @memoize_property
+    def commutative(self):
+        from .handlers.common import CommutativePredicate
+        return CommutativePredicate()
+
+    @memoize_property
+    def is_true(self):
+        from .handlers.common import IsTruePredicate
+        return IsTruePredicate()
+
+    @memoize_property
+    def symmetric(self):
+        from .handlers.matrices import SymmetricPredicate
+        return SymmetricPredicate()
+
+    @memoize_property
+    def invertible(self):
+        from .handlers.matrices import InvertiblePredicate
+        return InvertiblePredicate()
+
+    @memoize_property
+    def orthogonal(self):
+        from .handlers.matrices import OrthogonalPredicate
+        return OrthogonalPredicate()
+
+    @memoize_property
+    def unitary(self):
+        from .handlers.matrices import UnitaryPredicate
+        return UnitaryPredicate()
+
+    @memoize_property
+    def positive_definite(self):
+        from .handlers.matrices import PositiveDefinitePredicate
+        return PositiveDefinitePredicate()
+
+    @memoize_property
+    def upper_triangular(self):
+        from .handlers.matrices import UpperTriangularPredicate
+        return UpperTriangularPredicate()
+
+    @memoize_property
+    def lower_triangular(self):
+        from .handlers.matrices import LowerTriangularPredicate
+        return LowerTriangularPredicate()
+
+    @memoize_property
+    def diagonal(self):
+        from .handlers.matrices import DiagonalPredicate
+        return DiagonalPredicate()
+
+    @memoize_property
+    def fullrank(self):
+        from .handlers.matrices import FullRankPredicate
+        return FullRankPredicate()
+
+    @memoize_property
+    def square(self):
+        from .handlers.matrices import SquarePredicate
+        return SquarePredicate()
+
+    @memoize_property
+    def integer_elements(self):
+        from .handlers.matrices import IntegerElementsPredicate
+        return IntegerElementsPredicate()
+
+    @memoize_property
+    def real_elements(self):
+        from .handlers.matrices import RealElementsPredicate
+        return RealElementsPredicate()
+
+    @memoize_property
+    def complex_elements(self):
+        from .handlers.matrices import ComplexElementsPredicate
+        return ComplexElementsPredicate()
+
+    @memoize_property
+    def singular(self):
+        from .predicates.matrices import SingularPredicate
+        return SingularPredicate()
+
+    @memoize_property
+    def normal(self):
+        from .predicates.matrices import NormalPredicate
+        return NormalPredicate()
+
+    @memoize_property
+    def triangular(self):
+        from .predicates.matrices import TriangularPredicate
+        return TriangularPredicate()
+
+    @memoize_property
+    def unit_triangular(self):
+        from .predicates.matrices import UnitTriangularPredicate
+        return UnitTriangularPredicate()
+
+    @memoize_property
+    def eq(self):
+        from .relation.equality import EqualityPredicate
+        return EqualityPredicate()
+
+    @memoize_property
+    def ne(self):
+        from .relation.equality import UnequalityPredicate
+        return UnequalityPredicate()
+
+    @memoize_property
+    def gt(self):
+        from .relation.equality import StrictGreaterThanPredicate
+        return StrictGreaterThanPredicate()
+
+    @memoize_property
+    def ge(self):
+        from .relation.equality import GreaterThanPredicate
+        return GreaterThanPredicate()
+
+    @memoize_property
+    def lt(self):
+        from .relation.equality import StrictLessThanPredicate
+        return StrictLessThanPredicate()
+
+    @memoize_property
+    def le(self):
+        from .relation.equality import LessThanPredicate
+        return LessThanPredicate()
+
+
+Q = AssumptionKeys()
+
+def _extract_all_facts(assump, exprs):
+    """
+    Extract all relevant assumptions from *assump* with respect to given *exprs*.
+
+    Parameters
+    ==========
+
+    assump : sympy.assumptions.cnf.CNF
+
+    exprs : tuple of expressions
+
+    Returns
+    =======
+
+    sympy.assumptions.cnf.CNF
+
+    Examples
+    ========
+
+    >>> from sympy import Q
+    >>> from sympy.assumptions.cnf import CNF
+    >>> from sympy.assumptions.ask import _extract_all_facts
+    >>> from sympy.abc import x, y
+    >>> assump = CNF.from_prop(Q.positive(x) & Q.integer(y))
+    >>> exprs = (x,)
+    >>> cnf = _extract_all_facts(assump, exprs)
+    >>> cnf.clauses
+    {frozenset({Literal(Q.positive, False)})}
+
+    """
+    facts = set()
+
+    for clause in assump.clauses:
+        args = []
+        for literal in clause:
+            if isinstance(literal.lit, AppliedPredicate) and len(literal.lit.arguments) == 1:
+                if literal.lit.arg in exprs:
+                    # Add literal if it has matching in it
+                    args.append(Literal(literal.lit.function, literal.is_Not))
+                else:
+                    # If any of the literals doesn't have matching expr don't add the whole clause.
+                    break
+            else:
+                # If any of the literals aren't unary predicate don't add the whole clause.
+                break
+
+        else:
+            if args:
+                facts.add(frozenset(args))
+    return CNF(facts)
+
+
+def ask(proposition, assumptions=True, context=global_assumptions):
+    """
+    Function to evaluate the proposition with assumptions.
+
+    Explanation
+    ===========
+
+    This function evaluates the proposition to ``True`` or ``False`` if
+    the truth value can be determined. If not, it returns ``None``.
+
+    It should be discerned from :func:`~.refine` which, when applied to a
+    proposition, simplifies the argument to symbolic ``Boolean`` instead of
+    Python built-in ``True``, ``False`` or ``None``.
+
+    **Syntax**
+
+        * ask(proposition)
+            Evaluate the *proposition* in global assumption context.
+
+        * ask(proposition, assumptions)
+            Evaluate the *proposition* with respect to *assumptions* in
+            global assumption context.
+
+    Parameters
+    ==========
+
+    proposition : Boolean
+        Proposition which will be evaluated to boolean value. If this is
+        not ``AppliedPredicate``, it will be wrapped by ``Q.is_true``.
+
+    assumptions : Boolean, optional
+        Local assumptions to evaluate the *proposition*.
+
+    context : AssumptionsContext, optional
+        Default assumptions to evaluate the *proposition*. By default,
+        this is ``sympy.assumptions.global_assumptions`` variable.
+
+    Returns
+    =======
+
+    ``True``, ``False``, or ``None``
+
+    Raises
+    ======
+
+    TypeError : *proposition* or *assumptions* is not valid logical expression.
+
+    ValueError : assumptions are inconsistent.
+
+    Examples
+    ========
+
+    >>> from sympy import ask, Q, pi
+    >>> from sympy.abc import x, y
+    >>> ask(Q.rational(pi))
+    False
+    >>> ask(Q.even(x*y), Q.even(x) & Q.integer(y))
+    True
+    >>> ask(Q.prime(4*x), Q.integer(x))
+    False
+
+    If the truth value cannot be determined, ``None`` will be returned.
+
+    >>> print(ask(Q.odd(3*x))) # cannot determine unless we know x
+    None
+
+    ``ValueError`` is raised if assumptions are inconsistent.
+
+    >>> ask(Q.integer(x), Q.even(x) & Q.odd(x))
+    Traceback (most recent call last):
+      ...
+    ValueError: inconsistent assumptions Q.even(x) & Q.odd(x)
+
+    Notes
+    =====
+
+    Relations in assumptions are not implemented (yet), so the following
+    will not give a meaningful result.
+
+    >>> ask(Q.positive(x), x > 0)
+
+    It is however a work in progress.
+
+    See Also
+    ========
+
+    sympy.assumptions.refine.refine : Simplification using assumptions.
+        Proposition is not reduced to ``None`` if the truth value cannot
+        be determined.
+    """
+    from sympy.assumptions.satask import satask
+    from sympy.assumptions.lra_satask import lra_satask
+    from sympy.logic.algorithms.lra_theory import UnhandledInput
+
+    proposition = sympify(proposition)
+    assumptions = sympify(assumptions)
+
+    if isinstance(proposition, Predicate) or proposition.kind is not BooleanKind:
+        raise TypeError("proposition must be a valid logical expression")
+
+    if isinstance(assumptions, Predicate) or assumptions.kind is not BooleanKind:
+        raise TypeError("assumptions must be a valid logical expression")
+
+    binrelpreds = {Eq: Q.eq, Ne: Q.ne, Gt: Q.gt, Lt: Q.lt, Ge: Q.ge, Le: Q.le}
+    if isinstance(proposition, AppliedPredicate):
+        key, args = proposition.function, proposition.arguments
+    elif proposition.func in binrelpreds:
+        key, args = binrelpreds[type(proposition)], proposition.args
+    else:
+        key, args = Q.is_true, (proposition,)
+
+    # convert local and global assumptions to CNF
+    assump_cnf = CNF.from_prop(assumptions)
+    assump_cnf.extend(context)
+
+    # extract the relevant facts from assumptions with respect to args
+    local_facts = _extract_all_facts(assump_cnf, args)
+
+    # convert default facts and assumed facts to encoded CNF
+    known_facts_cnf = get_all_known_facts()
+    enc_cnf = EncodedCNF()
+    enc_cnf.from_cnf(CNF(known_facts_cnf))
+    enc_cnf.add_from_cnf(local_facts)
+
+    # check the satisfiability of given assumptions
+    if local_facts.clauses and satisfiable(enc_cnf) is False:
+        raise ValueError("inconsistent assumptions %s" % assumptions)
+
+    # quick computation for single fact
+    res = _ask_single_fact(key, local_facts)
+    if res is not None:
+        return res
+
+    # direct resolution method, no logic
+    res = key(*args)._eval_ask(assumptions)
+    if res is not None:
+        return bool(res)
+
+    # using satask (still costly)
+    res = satask(proposition, assumptions=assumptions, context=context)
+    if res is not None:
+        return res
+
+    try:
+        res = lra_satask(proposition, assumptions=assumptions, context=context)
+    except UnhandledInput:
+        return None
+
+    return res
+
+
+def _ask_single_fact(key, local_facts):
+    """
+    Compute the truth value of single predicate using assumptions.
+
+    Parameters
+    ==========
+
+    key : sympy.assumptions.assume.Predicate
+        Proposition predicate.
+
+    local_facts : sympy.assumptions.cnf.CNF
+        Local assumption in CNF form.
+
+    Returns
+    =======
+
+    ``True``, ``False`` or ``None``
+
+    Examples
+    ========
+
+    >>> from sympy import Q
+    >>> from sympy.assumptions.cnf import CNF
+    >>> from sympy.assumptions.ask import _ask_single_fact
+
+    If prerequisite of proposition is rejected by the assumption,
+    return ``False``.
+
+    >>> key, assump = Q.zero, ~Q.zero
+    >>> local_facts = CNF.from_prop(assump)
+    >>> _ask_single_fact(key, local_facts)
+    False
+    >>> key, assump = Q.zero, ~Q.even
+    >>> local_facts = CNF.from_prop(assump)
+    >>> _ask_single_fact(key, local_facts)
+    False
+
+    If assumption implies the proposition, return ``True``.
+
+    >>> key, assump = Q.even, Q.zero
+    >>> local_facts = CNF.from_prop(assump)
+    >>> _ask_single_fact(key, local_facts)
+    True
+
+    If proposition rejects the assumption, return ``False``.
+
+    >>> key, assump = Q.even, Q.odd
+    >>> local_facts = CNF.from_prop(assump)
+    >>> _ask_single_fact(key, local_facts)
+    False
+    """
+    if local_facts.clauses:
+
+        known_facts_dict = get_known_facts_dict()
+
+        if len(local_facts.clauses) == 1:
+            cl, = local_facts.clauses
+            if len(cl) == 1:
+                f, = cl
+                prop_facts = known_facts_dict.get(key, None)
+                prop_req = prop_facts[0] if prop_facts is not None else set()
+                if f.is_Not and f.arg in prop_req:
+                    # the prerequisite of proposition is rejected
+                    return False
+
+        for clause in local_facts.clauses:
+            if len(clause) == 1:
+                f, = clause
+                prop_facts = known_facts_dict.get(f.arg, None) if not f.is_Not else None
+                if prop_facts is None:
+                    continue
+
+                prop_req, prop_rej = prop_facts
+                if key in prop_req:
+                    # assumption implies the proposition
+                    return True
+                elif key in prop_rej:
+                    # proposition rejects the assumption
+                    return False
+
+    return None
+
+
+def register_handler(key, handler):
+    """
+    Register a handler in the ask system. key must be a string and handler a
+    class inheriting from AskHandler.
+
+    .. deprecated:: 1.8.
+        Use multipledispatch handler instead. See :obj:`~.Predicate`.
+
+    """
+    sympy_deprecation_warning(
+        """
+        The AskHandler system is deprecated. The register_handler() function
+        should be replaced with the multipledispatch handler of Predicate.
+        """,
+        deprecated_since_version="1.8",
+        active_deprecations_target='deprecated-askhandler',
+    )
+    if isinstance(key, Predicate):
+        key = key.name.name
+    Qkey = getattr(Q, key, None)
+    if Qkey is not None:
+        Qkey.add_handler(handler)
+    else:
+        setattr(Q, key, Predicate(key, handlers=[handler]))
+
+
+def remove_handler(key, handler):
+    """
+    Removes a handler from the ask system.
+
+    .. deprecated:: 1.8.
+        Use multipledispatch handler instead. See :obj:`~.Predicate`.
+
+    """
+    sympy_deprecation_warning(
+        """
+        The AskHandler system is deprecated. The remove_handler() function
+        should be replaced with the multipledispatch handler of Predicate.
+        """,
+        deprecated_since_version="1.8",
+        active_deprecations_target='deprecated-askhandler',
+    )
+    if isinstance(key, Predicate):
+        key = key.name.name
+    # Don't show the same warning again recursively
+    with ignore_warnings(SymPyDeprecationWarning):
+        getattr(Q, key).remove_handler(handler)
+
+
+from sympy.assumptions.ask_generated import (get_all_known_facts,
+    get_known_facts_dict)

.venv/lib/python3.13/site-packages/sympy/assumptions/ask_generated.py

@@ -0,0 +1,352 @@
+"""
+Do NOT manually edit this file.
+Instead, run ./bin/ask_update.py.
+"""
+
+from sympy.assumptions.ask import Q
+from sympy.assumptions.cnf import Literal
+from sympy.core.cache import cacheit
+
+@cacheit
+def get_all_known_facts():
+    """
+    Known facts between unary predicates as CNF clauses.
+    """
+    return {
+        frozenset((Literal(Q.algebraic, False), Literal(Q.imaginary, True), Literal(Q.transcendental, False))),
+        frozenset((Literal(Q.algebraic, False), Literal(Q.negative, True), Literal(Q.transcendental, False))),
+        frozenset((Literal(Q.algebraic, False), Literal(Q.positive, True), Literal(Q.transcendental, False))),
+        frozenset((Literal(Q.algebraic, False), Literal(Q.rational, True))),
+        frozenset((Literal(Q.algebraic, False), Literal(Q.transcendental, False), Literal(Q.zero, True))),
+        frozenset((Literal(Q.algebraic, True), Literal(Q.finite, False))),
+        frozenset((Literal(Q.algebraic, True), Literal(Q.transcendental, True))),
+        frozenset((Literal(Q.antihermitian, False), Literal(Q.hermitian, False), Literal(Q.zero, True))),
+        frozenset((Literal(Q.antihermitian, False), Literal(Q.imaginary, True))),
+        frozenset((Literal(Q.commutative, False), Literal(Q.finite, True))),
+        frozenset((Literal(Q.commutative, False), Literal(Q.infinite, True))),
+        frozenset((Literal(Q.complex_elements, False), Literal(Q.real_elements, True))),
+        frozenset((Literal(Q.composite, False), Literal(Q.even, True), Literal(Q.positive, True), Literal(Q.prime, False))),
+        frozenset((Literal(Q.composite, True), Literal(Q.even, False), Literal(Q.odd, False))),
+        frozenset((Literal(Q.composite, True), Literal(Q.positive, False))),
+        frozenset((Literal(Q.composite, True), Literal(Q.prime, True))),
+        frozenset((Literal(Q.diagonal, False), Literal(Q.lower_triangular, True), Literal(Q.upper_triangular, True))),
+        frozenset((Literal(Q.diagonal, True), Literal(Q.lower_triangular, False))),
+        frozenset((Literal(Q.diagonal, True), Literal(Q.normal, False))),
+        frozenset((Literal(Q.diagonal, True), Literal(Q.symmetric, False))),
+        frozenset((Literal(Q.diagonal, True), Literal(Q.upper_triangular, False))),
+        frozenset((Literal(Q.even, False), Literal(Q.odd, False), Literal(Q.prime, True))),
+        frozenset((Literal(Q.even, False), Literal(Q.zero, True))),
+        frozenset((Literal(Q.even, True), Literal(Q.odd, True))),
+        frozenset((Literal(Q.even, True), Literal(Q.rational, False))),
+        frozenset((Literal(Q.finite, False), Literal(Q.transcendental, True))),
+        frozenset((Literal(Q.finite, True), Literal(Q.infinite, True))),
+        frozenset((Literal(Q.fullrank, False), Literal(Q.invertible, True))),
+        frozenset((Literal(Q.fullrank, True), Literal(Q.invertible, False), Literal(Q.square, True))),
+        frozenset((Literal(Q.hermitian, False), Literal(Q.negative, True))),
+        frozenset((Literal(Q.hermitian, False), Literal(Q.positive, True))),
+        frozenset((Literal(Q.hermitian, False), Literal(Q.zero, True))),
+        frozenset((Literal(Q.imaginary, True), Literal(Q.negative, True))),
+        frozenset((Literal(Q.imaginary, True), Literal(Q.positive, True))),
+        frozenset((Literal(Q.imaginary, True), Literal(Q.zero, True))),
+        frozenset((Literal(Q.infinite, False), Literal(Q.negative_infinite, True))),
+        frozenset((Literal(Q.infinite, False), Literal(Q.positive_infinite, True))),
+        frozenset((Literal(Q.integer_elements, True), Literal(Q.real_elements, False))),
+        frozenset((Literal(Q.invertible, False), Literal(Q.positive_definite, True))),
+        frozenset((Literal(Q.invertible, False), Literal(Q.singular, False))),
+        frozenset((Literal(Q.invertible, False), Literal(Q.unitary, True))),
+        frozenset((Literal(Q.invertible, True), Literal(Q.singular, True))),
+        frozenset((Literal(Q.invertible, True), Literal(Q.square, False))),
+        frozenset((Literal(Q.irrational, False), Literal(Q.negative, True), Literal(Q.rational, False))),
+        frozenset((Literal(Q.irrational, False), Literal(Q.positive, True), Literal(Q.rational, False))),
+        frozenset((Literal(Q.irrational, False), Literal(Q.rational, False), Literal(Q.zero, True))),
+        frozenset((Literal(Q.irrational, True), Literal(Q.negative, False), Literal(Q.positive, False), Literal(Q.zero, False))),
+        frozenset((Literal(Q.irrational, True), Literal(Q.rational, True))),
+        frozenset((Literal(Q.lower_triangular, False), Literal(Q.triangular, True), Literal(Q.upper_triangular, False))),
+        frozenset((Literal(Q.lower_triangular, True), Literal(Q.triangular, False))),
+        frozenset((Literal(Q.negative, False), Literal(Q.positive, False), Literal(Q.rational, True), Literal(Q.zero, False))),
+        frozenset((Literal(Q.negative, True), Literal(Q.negative_infinite, True))),
+        frozenset((Literal(Q.negative, True), Literal(Q.positive, True))),
+        frozenset((Literal(Q.negative, True), Literal(Q.positive_infinite, True))),
+        frozenset((Literal(Q.negative, True), Literal(Q.zero, True))),
+        frozenset((Literal(Q.negative_infinite, True), Literal(Q.positive, True))),
+        frozenset((Literal(Q.negative_infinite, True), Literal(Q.positive_infinite, True))),
+        frozenset((Literal(Q.negative_infinite, True), Literal(Q.zero, True))),
+        frozenset((Literal(Q.normal, False), Literal(Q.unitary, True))),
+        frozenset((Literal(Q.normal, True), Literal(Q.square, False))),
+        frozenset((Literal(Q.odd, True), Literal(Q.rational, False))),
+        frozenset((Literal(Q.orthogonal, False), Literal(Q.real_elements, True), Literal(Q.unitary, True))),
+        frozenset((Literal(Q.orthogonal, True), Literal(Q.positive_definite, False))),
+        frozenset((Literal(Q.orthogonal, True), Literal(Q.unitary, False))),
+        frozenset((Literal(Q.positive, False), Literal(Q.prime, True))),
+        frozenset((Literal(Q.positive, True), Literal(Q.positive_infinite, True))),
+        frozenset((Literal(Q.positive, True), Literal(Q.zero, True))),
+        frozenset((Literal(Q.positive_infinite, True), Literal(Q.zero, True))),
+        frozenset((Literal(Q.square, False), Literal(Q.symmetric, True))),
+        frozenset((Literal(Q.triangular, False), Literal(Q.unit_triangular, True))),
+        frozenset((Literal(Q.triangular, False), Literal(Q.upper_triangular, True)))
+    }
+
+@cacheit
+def get_all_known_matrix_facts():
+    """
+    Known facts between unary predicates for matrices as CNF clauses.
+    """
+    return {
+        frozenset((Literal(Q.complex_elements, False), Literal(Q.real_elements, True))),
+        frozenset((Literal(Q.diagonal, False), Literal(Q.lower_triangular, True), Literal(Q.upper_triangular, True))),
+        frozenset((Literal(Q.diagonal, True), Literal(Q.lower_triangular, False))),
+        frozenset((Literal(Q.diagonal, True), Literal(Q.normal, False))),
+        frozenset((Literal(Q.diagonal, True), Literal(Q.symmetric, False))),
+        frozenset((Literal(Q.diagonal, True), Literal(Q.upper_triangular, False))),
+        frozenset((Literal(Q.fullrank, False), Literal(Q.invertible, True))),
+        frozenset((Literal(Q.fullrank, True), Literal(Q.invertible, False), Literal(Q.square, True))),
+        frozenset((Literal(Q.integer_elements, True), Literal(Q.real_elements, False))),
+        frozenset((Literal(Q.invertible, False), Literal(Q.positive_definite, True))),
+        frozenset((Literal(Q.invertible, False), Literal(Q.singular, False))),
+        frozenset((Literal(Q.invertible, False), Literal(Q.unitary, True))),
+        frozenset((Literal(Q.invertible, True), Literal(Q.singular, True))),
+        frozenset((Literal(Q.invertible, True), Literal(Q.square, False))),
+        frozenset((Literal(Q.lower_triangular, False), Literal(Q.triangular, True), Literal(Q.upper_triangular, False))),
+        frozenset((Literal(Q.lower_triangular, True), Literal(Q.triangular, False))),
+        frozenset((Literal(Q.normal, False), Literal(Q.unitary, True))),
+        frozenset((Literal(Q.normal, True), Literal(Q.square, False))),
+        frozenset((Literal(Q.orthogonal, False), Literal(Q.real_elements, True), Literal(Q.unitary, True))),
+        frozenset((Literal(Q.orthogonal, True), Literal(Q.positive_definite, False))),
+        frozenset((Literal(Q.orthogonal, True), Literal(Q.unitary, False))),
+        frozenset((Literal(Q.square, False), Literal(Q.symmetric, True))),
+        frozenset((Literal(Q.triangular, False), Literal(Q.unit_triangular, True))),
+        frozenset((Literal(Q.triangular, False), Literal(Q.upper_triangular, True)))
+    }
+
+@cacheit
+def get_all_known_number_facts():
+    """
+    Known facts between unary predicates for numbers as CNF clauses.
+    """
+    return {
+        frozenset((Literal(Q.algebraic, False), Literal(Q.imaginary, True), Literal(Q.transcendental, False))),
+        frozenset((Literal(Q.algebraic, False), Literal(Q.negative, True), Literal(Q.transcendental, False))),
+        frozenset((Literal(Q.algebraic, False), Literal(Q.positive, True), Literal(Q.transcendental, False))),
+        frozenset((Literal(Q.algebraic, False), Literal(Q.rational, True))),
+        frozenset((Literal(Q.algebraic, False), Literal(Q.transcendental, False), Literal(Q.zero, True))),
+        frozenset((Literal(Q.algebraic, True), Literal(Q.finite, False))),
+        frozenset((Literal(Q.algebraic, True), Literal(Q.transcendental, True))),
+        frozenset((Literal(Q.antihermitian, False), Literal(Q.hermitian, False), Literal(Q.zero, True))),
+        frozenset((Literal(Q.antihermitian, False), Literal(Q.imaginary, True))),
+        frozenset((Literal(Q.commutative, False), Literal(Q.finite, True))),
+        frozenset((Literal(Q.commutative, False), Literal(Q.infinite, True))),
+        frozenset((Literal(Q.composite, False), Literal(Q.even, True), Literal(Q.positive, True), Literal(Q.prime, False))),
+        frozenset((Literal(Q.composite, True), Literal(Q.even, False), Literal(Q.odd, False))),
+        frozenset((Literal(Q.composite, True), Literal(Q.positive, False))),
+        frozenset((Literal(Q.composite, True), Literal(Q.prime, True))),
+        frozenset((Literal(Q.even, False), Literal(Q.odd, False), Literal(Q.prime, True))),
+        frozenset((Literal(Q.even, False), Literal(Q.zero, True))),
+        frozenset((Literal(Q.even, True), Literal(Q.odd, True))),
+        frozenset((Literal(Q.even, True), Literal(Q.rational, False))),
+        frozenset((Literal(Q.finite, False), Literal(Q.transcendental, True))),
+        frozenset((Literal(Q.finite, True), Literal(Q.infinite, True))),
+        frozenset((Literal(Q.hermitian, False), Literal(Q.negative, True))),
+        frozenset((Literal(Q.hermitian, False), Literal(Q.positive, True))),
+        frozenset((Literal(Q.hermitian, False), Literal(Q.zero, True))),
+        frozenset((Literal(Q.imaginary, True), Literal(Q.negative, True))),
+        frozenset((Literal(Q.imaginary, True), Literal(Q.positive, True))),
+        frozenset((Literal(Q.imaginary, True), Literal(Q.zero, True))),
+        frozenset((Literal(Q.infinite, False), Literal(Q.negative_infinite, True))),
+        frozenset((Literal(Q.infinite, False), Literal(Q.positive_infinite, True))),
+        frozenset((Literal(Q.irrational, False), Literal(Q.negative, True), Literal(Q.rational, False))),
+        frozenset((Literal(Q.irrational, False), Literal(Q.positive, True), Literal(Q.rational, False))),
+        frozenset((Literal(Q.irrational, False), Literal(Q.rational, False), Literal(Q.zero, True))),
+        frozenset((Literal(Q.irrational, True), Literal(Q.negative, False), Literal(Q.positive, False), Literal(Q.zero, False))),
+        frozenset((Literal(Q.irrational, True), Literal(Q.rational, True))),
+        frozenset((Literal(Q.negative, False), Literal(Q.positive, False), Literal(Q.rational, True), Literal(Q.zero, False))),
+        frozenset((Literal(Q.negative, True), Literal(Q.negative_infinite, True))),
+        frozenset((Literal(Q.negative, True), Literal(Q.positive, True))),
+        frozenset((Literal(Q.negative, True), Literal(Q.positive_infinite, True))),
+        frozenset((Literal(Q.negative, True), Literal(Q.zero, True))),
+        frozenset((Literal(Q.negative_infinite, True), Literal(Q.positive, True))),
+        frozenset((Literal(Q.negative_infinite, True), Literal(Q.positive_infinite, True))),
+        frozenset((Literal(Q.negative_infinite, True), Literal(Q.zero, True))),
+        frozenset((Literal(Q.odd, True), Literal(Q.rational, False))),
+        frozenset((Literal(Q.positive, False), Literal(Q.prime, True))),
+        frozenset((Literal(Q.positive, True), Literal(Q.positive_infinite, True))),
+        frozenset((Literal(Q.positive, True), Literal(Q.zero, True))),
+        frozenset((Literal(Q.positive_infinite, True), Literal(Q.zero, True)))
+    }
+
+@cacheit
+def get_known_facts_dict():
+    """
+    Logical relations between unary predicates as dictionary.
+
+    Each key is a predicate, and item is two groups of predicates.
+    First group contains the predicates which are implied by the key, and
+    second group contains the predicates which are rejected by the key.
+
+    """
+    return {
+        Q.algebraic: (set([Q.algebraic, Q.commutative, Q.complex, Q.finite]),
+        set([Q.infinite, Q.negative_infinite, Q.positive_infinite,
+        Q.transcendental])),
+        Q.antihermitian: (set([Q.antihermitian]), set([])),
+        Q.commutative: (set([Q.commutative]), set([])),
+        Q.complex: (set([Q.commutative, Q.complex, Q.finite]),
+        set([Q.infinite, Q.negative_infinite, Q.positive_infinite])),
+        Q.complex_elements: (set([Q.complex_elements]), set([])),
+        Q.composite: (set([Q.algebraic, Q.commutative, Q.complex, Q.composite,
+        Q.extended_nonnegative, Q.extended_nonzero,
+        Q.extended_positive, Q.extended_real, Q.finite, Q.hermitian,
+        Q.integer, Q.nonnegative, Q.nonzero, Q.positive, Q.rational,
+        Q.real]), set([Q.extended_negative, Q.extended_nonpositive,
+        Q.imaginary, Q.infinite, Q.irrational, Q.negative,
+        Q.negative_infinite, Q.nonpositive, Q.positive_infinite,
+        Q.prime, Q.transcendental, Q.zero])),
+        Q.diagonal: (set([Q.diagonal, Q.lower_triangular, Q.normal, Q.square,
+        Q.symmetric, Q.triangular, Q.upper_triangular]), set([])),
+        Q.even: (set([Q.algebraic, Q.commutative, Q.complex, Q.even,
+        Q.extended_real, Q.finite, Q.hermitian, Q.integer, Q.rational,
+        Q.real]), set([Q.imaginary, Q.infinite, Q.irrational,
+        Q.negative_infinite, Q.odd, Q.positive_infinite,
+        Q.transcendental])),
+        Q.extended_negative: (set([Q.commutative, Q.extended_negative,
+        Q.extended_nonpositive, Q.extended_nonzero, Q.extended_real]),
+        set([Q.composite, Q.extended_nonnegative, Q.extended_positive,
+        Q.imaginary, Q.nonnegative, Q.positive, Q.positive_infinite,
+        Q.prime, Q.zero])),
+        Q.extended_nonnegative: (set([Q.commutative, Q.extended_nonnegative,
+        Q.extended_real]), set([Q.extended_negative, Q.imaginary,
+        Q.negative, Q.negative_infinite])),
+        Q.extended_nonpositive: (set([Q.commutative, Q.extended_nonpositive,
+        Q.extended_real]), set([Q.composite, Q.extended_positive,
+        Q.imaginary, Q.positive, Q.positive_infinite, Q.prime])),
+        Q.extended_nonzero: (set([Q.commutative, Q.extended_nonzero,
+        Q.extended_real]), set([Q.imaginary, Q.zero])),
+        Q.extended_positive: (set([Q.commutative, Q.extended_nonnegative,
+        Q.extended_nonzero, Q.extended_positive, Q.extended_real]),
+        set([Q.extended_negative, Q.extended_nonpositive, Q.imaginary,
+        Q.negative, Q.negative_infinite, Q.nonpositive, Q.zero])),
+        Q.extended_real: (set([Q.commutative, Q.extended_real]),
+        set([Q.imaginary])),
+        Q.finite: (set([Q.commutative, Q.finite]), set([Q.infinite,
+        Q.negative_infinite, Q.positive_infinite])),
+        Q.fullrank: (set([Q.fullrank]), set([])),
+        Q.hermitian: (set([Q.hermitian]), set([])),
+        Q.imaginary: (set([Q.antihermitian, Q.commutative, Q.complex,
+        Q.finite, Q.imaginary]), set([Q.composite, Q.even,
+        Q.extended_negative, Q.extended_nonnegative,
+        Q.extended_nonpositive, Q.extended_nonzero,
+        Q.extended_positive, Q.extended_real, Q.infinite, Q.integer,
+        Q.irrational, Q.negative, Q.negative_infinite, Q.nonnegative,
+        Q.nonpositive, Q.nonzero, Q.odd, Q.positive,
+        Q.positive_infinite, Q.prime, Q.rational, Q.real, Q.zero])),
+        Q.infinite: (set([Q.commutative, Q.infinite]), set([Q.algebraic,
+        Q.complex, Q.composite, Q.even, Q.finite, Q.imaginary,
+        Q.integer, Q.irrational, Q.negative, Q.nonnegative,
+        Q.nonpositive, Q.nonzero, Q.odd, Q.positive, Q.prime,
+        Q.rational, Q.real, Q.transcendental, Q.zero])),
+        Q.integer: (set([Q.algebraic, Q.commutative, Q.complex,
+        Q.extended_real, Q.finite, Q.hermitian, Q.integer, Q.rational,
+        Q.real]), set([Q.imaginary, Q.infinite, Q.irrational,
+        Q.negative_infinite, Q.positive_infinite, Q.transcendental])),
+        Q.integer_elements: (set([Q.complex_elements, Q.integer_elements,
+        Q.real_elements]), set([])),
+        Q.invertible: (set([Q.fullrank, Q.invertible, Q.square]),
+        set([Q.singular])),
+        Q.irrational: (set([Q.commutative, Q.complex, Q.extended_nonzero,
+        Q.extended_real, Q.finite, Q.hermitian, Q.irrational,
+        Q.nonzero, Q.real]), set([Q.composite, Q.even, Q.imaginary,
+        Q.infinite, Q.integer, Q.negative_infinite, Q.odd,
+        Q.positive_infinite, Q.prime, Q.rational, Q.zero])),
+        Q.is_true: (set([Q.is_true]), set([])),
+        Q.lower_triangular: (set([Q.lower_triangular, Q.triangular]), set([])),
+        Q.negative: (set([Q.commutative, Q.complex, Q.extended_negative,
+        Q.extended_nonpositive, Q.extended_nonzero, Q.extended_real,
+        Q.finite, Q.hermitian, Q.negative, Q.nonpositive, Q.nonzero,
+        Q.real]), set([Q.composite, Q.extended_nonnegative,
+        Q.extended_positive, Q.imaginary, Q.infinite,
+        Q.negative_infinite, Q.nonnegative, Q.positive,
+        Q.positive_infinite, Q.prime, Q.zero])),
+        Q.negative_infinite: (set([Q.commutative, Q.extended_negative,
+        Q.extended_nonpositive, Q.extended_nonzero, Q.extended_real,
+        Q.infinite, Q.negative_infinite]), set([Q.algebraic,
+        Q.complex, Q.composite, Q.even, Q.extended_nonnegative,
+        Q.extended_positive, Q.finite, Q.imaginary, Q.integer,
+        Q.irrational, Q.negative, Q.nonnegative, Q.nonpositive,
+        Q.nonzero, Q.odd, Q.positive, Q.positive_infinite, Q.prime,
+        Q.rational, Q.real, Q.transcendental, Q.zero])),
+        Q.noninteger: (set([Q.noninteger]), set([])),
+        Q.nonnegative: (set([Q.commutative, Q.complex, Q.extended_nonnegative,
+        Q.extended_real, Q.finite, Q.hermitian, Q.nonnegative,
+        Q.real]), set([Q.extended_negative, Q.imaginary, Q.infinite,
+        Q.negative, Q.negative_infinite, Q.positive_infinite])),
+        Q.nonpositive: (set([Q.commutative, Q.complex, Q.extended_nonpositive,
+        Q.extended_real, Q.finite, Q.hermitian, Q.nonpositive,
+        Q.real]), set([Q.composite, Q.extended_positive, Q.imaginary,
+        Q.infinite, Q.negative_infinite, Q.positive,
+        Q.positive_infinite, Q.prime])),
+        Q.nonzero: (set([Q.commutative, Q.complex, Q.extended_nonzero,
+        Q.extended_real, Q.finite, Q.hermitian, Q.nonzero, Q.real]),
+        set([Q.imaginary, Q.infinite, Q.negative_infinite,
+        Q.positive_infinite, Q.zero])),
+        Q.normal: (set([Q.normal, Q.square]), set([])),
+        Q.odd: (set([Q.algebraic, Q.commutative, Q.complex,
+        Q.extended_nonzero, Q.extended_real, Q.finite, Q.hermitian,
+        Q.integer, Q.nonzero, Q.odd, Q.rational, Q.real]),
+        set([Q.even, Q.imaginary, Q.infinite, Q.irrational,
+        Q.negative_infinite, Q.positive_infinite, Q.transcendental,
+        Q.zero])),
+        Q.orthogonal: (set([Q.fullrank, Q.invertible, Q.normal, Q.orthogonal,
+        Q.positive_definite, Q.square, Q.unitary]), set([Q.singular])),
+        Q.positive: (set([Q.commutative, Q.complex, Q.extended_nonnegative,
+        Q.extended_nonzero, Q.extended_positive, Q.extended_real,
+        Q.finite, Q.hermitian, Q.nonnegative, Q.nonzero, Q.positive,
+        Q.real]), set([Q.extended_negative, Q.extended_nonpositive,
+        Q.imaginary, Q.infinite, Q.negative, Q.negative_infinite,
+        Q.nonpositive, Q.positive_infinite, Q.zero])),
+        Q.positive_definite: (set([Q.fullrank, Q.invertible,
+        Q.positive_definite, Q.square]), set([Q.singular])),
+        Q.positive_infinite: (set([Q.commutative, Q.extended_nonnegative,
+        Q.extended_nonzero, Q.extended_positive, Q.extended_real,
+        Q.infinite, Q.positive_infinite]), set([Q.algebraic,
+        Q.complex, Q.composite, Q.even, Q.extended_negative,
+        Q.extended_nonpositive, Q.finite, Q.imaginary, Q.integer,
+        Q.irrational, Q.negative, Q.negative_infinite, Q.nonnegative,
+        Q.nonpositive, Q.nonzero, Q.odd, Q.positive, Q.prime,
+        Q.rational, Q.real, Q.transcendental, Q.zero])),
+        Q.prime: (set([Q.algebraic, Q.commutative, Q.complex,
+        Q.extended_nonnegative, Q.extended_nonzero,
+        Q.extended_positive, Q.extended_real, Q.finite, Q.hermitian,
+        Q.integer, Q.nonnegative, Q.nonzero, Q.positive, Q.prime,
+        Q.rational, Q.real]), set([Q.composite, Q.extended_negative,
+        Q.extended_nonpositive, Q.imaginary, Q.infinite, Q.irrational,
+        Q.negative, Q.negative_infinite, Q.nonpositive,
+        Q.positive_infinite, Q.transcendental, Q.zero])),
+        Q.rational: (set([Q.algebraic, Q.commutative, Q.complex,
+        Q.extended_real, Q.finite, Q.hermitian, Q.rational, Q.real]),
+        set([Q.imaginary, Q.infinite, Q.irrational,
+        Q.negative_infinite, Q.positive_infinite, Q.transcendental])),
+        Q.real: (set([Q.commutative, Q.complex, Q.extended_real, Q.finite,
+        Q.hermitian, Q.real]), set([Q.imaginary, Q.infinite,
+        Q.negative_infinite, Q.positive_infinite])),
+        Q.real_elements: (set([Q.complex_elements, Q.real_elements]), set([])),
+        Q.singular: (set([Q.singular]), set([Q.invertible, Q.orthogonal,
+        Q.positive_definite, Q.unitary])),
+        Q.square: (set([Q.square]), set([])),
+        Q.symmetric: (set([Q.square, Q.symmetric]), set([])),
+        Q.transcendental: (set([Q.commutative, Q.complex, Q.finite,
+        Q.transcendental]), set([Q.algebraic, Q.composite, Q.even,
+        Q.infinite, Q.integer, Q.negative_infinite, Q.odd,
+        Q.positive_infinite, Q.prime, Q.rational, Q.zero])),
+        Q.triangular: (set([Q.triangular]), set([])),
+        Q.unit_triangular: (set([Q.triangular, Q.unit_triangular]), set([])),
+        Q.unitary: (set([Q.fullrank, Q.invertible, Q.normal, Q.square,
+        Q.unitary]), set([Q.singular])),
+        Q.upper_triangular: (set([Q.triangular, Q.upper_triangular]), set([])),
+        Q.zero: (set([Q.algebraic, Q.commutative, Q.complex, Q.even,
+        Q.extended_nonnegative, Q.extended_nonpositive,
+        Q.extended_real, Q.finite, Q.hermitian, Q.integer,
+        Q.nonnegative, Q.nonpositive, Q.rational, Q.real, Q.zero]),
+        set([Q.composite, Q.extended_negative, Q.extended_nonzero,
+        Q.extended_positive, Q.imaginary, Q.infinite, Q.irrational,
+        Q.negative, Q.negative_infinite, Q.nonzero, Q.odd, Q.positive,
+        Q.positive_infinite, Q.prime, Q.transcendental])),
+    }

.venv/lib/python3.13/site-packages/sympy/assumptions/assume.py

@@ -0,0 +1,485 @@
+"""A module which implements predicates and assumption context."""
+
+from contextlib import contextmanager
+import inspect
+from sympy.core.symbol import Str
+from sympy.core.sympify import _sympify
+from sympy.logic.boolalg import Boolean, false, true
+from sympy.multipledispatch.dispatcher import Dispatcher, str_signature
+from sympy.utilities.exceptions import sympy_deprecation_warning
+from sympy.utilities.iterables import is_sequence
+from sympy.utilities.source import get_class
+
+
+class AssumptionsContext(set):
+    """
+    Set containing default assumptions which are applied to the ``ask()``
+    function.
+
+    Explanation
+    ===========
+
+    This is used to represent global assumptions, but you can also use this
+    class to create your own local assumptions contexts. It is basically a thin
+    wrapper to Python's set, so see its documentation for advanced usage.
+
+    Examples
+    ========
+
+    The default assumption context is ``global_assumptions``, which is initially empty:
+
+    >>> from sympy import ask, Q
+    >>> from sympy.assumptions import global_assumptions
+    >>> global_assumptions
+    AssumptionsContext()
+
+    You can add default assumptions:
+
+    >>> from sympy.abc import x
+    >>> global_assumptions.add(Q.real(x))
+    >>> global_assumptions
+    AssumptionsContext({Q.real(x)})
+    >>> ask(Q.real(x))
+    True
+
+    And remove them:
+
+    >>> global_assumptions.remove(Q.real(x))
+    >>> print(ask(Q.real(x)))
+    None
+
+    The ``clear()`` method removes every assumption:
+
+    >>> global_assumptions.add(Q.positive(x))
+    >>> global_assumptions
+    AssumptionsContext({Q.positive(x)})
+    >>> global_assumptions.clear()
+    >>> global_assumptions
+    AssumptionsContext()
+
+    See Also
+    ========
+
+    assuming
+
+    """
+
+    def add(self, *assumptions):
+        """Add assumptions."""
+        for a in assumptions:
+            super().add(a)
+
+    def _sympystr(self, printer):
+        if not self:
+            return "%s()" % self.__class__.__name__
+        return "{}({})".format(self.__class__.__name__, printer._print_set(self))
+
+global_assumptions = AssumptionsContext()
+
+
+class AppliedPredicate(Boolean):
+    """
+    The class of expressions resulting from applying ``Predicate`` to
+    the arguments. ``AppliedPredicate`` merely wraps its argument and
+    remain unevaluated. To evaluate it, use the ``ask()`` function.
+
+    Examples
+    ========
+
+    >>> from sympy import Q, ask
+    >>> Q.integer(1)
+    Q.integer(1)
+
+    The ``function`` attribute returns the predicate, and the ``arguments``
+    attribute returns the tuple of arguments.
+
+    >>> type(Q.integer(1))
+    <class 'sympy.assumptions.assume.AppliedPredicate'>
+    >>> Q.integer(1).function
+    Q.integer
+    >>> Q.integer(1).arguments
+    (1,)
+
+    Applied predicates can be evaluated to a boolean value with ``ask``:
+
+    >>> ask(Q.integer(1))
+    True
+
+    """
+    __slots__ = ()
+
+    def __new__(cls, predicate, *args):
+        if not isinstance(predicate, Predicate):
+            raise TypeError("%s is not a Predicate." % predicate)
+        args = map(_sympify, args)
+        return super().__new__(cls, predicate, *args)
+
+    @property
+    def arg(self):
+        """
+        Return the expression used by this assumption.
+
+        Examples
+        ========
+
+        >>> from sympy import Q, Symbol
+        >>> x = Symbol('x')
+        >>> a = Q.integer(x + 1)
+        >>> a.arg
+        x + 1
+
+        """
+        # Will be deprecated
+        args = self._args
+        if len(args) == 2:
+            # backwards compatibility
+            return args[1]
+        raise TypeError("'arg' property is allowed only for unary predicates.")
+
+    @property
+    def function(self):
+        """
+        Return the predicate.
+        """
+        # Will be changed to self.args[0] after args overriding is removed
+        return self._args[0]
+
+    @property
+    def arguments(self):
+        """
+        Return the arguments which are applied to the predicate.
+        """
+        # Will be changed to self.args[1:] after args overriding is removed
+        return self._args[1:]
+
+    def _eval_ask(self, assumptions):
+        return self.function.eval(self.arguments, assumptions)
+
+    @property
+    def binary_symbols(self):
+        from .ask import Q
+        if self.function == Q.is_true:
+            i = self.arguments[0]
+            if i.is_Boolean or i.is_Symbol:
+                return i.binary_symbols
+        if self.function in (Q.eq, Q.ne):
+            if true in self.arguments or false in self.arguments:
+                if self.arguments[0].is_Symbol:
+                    return {self.arguments[0]}
+                elif self.arguments[1].is_Symbol:
+                    return {self.arguments[1]}
+        return set()
+
+
+class PredicateMeta(type):
+    def __new__(cls, clsname, bases, dct):
+        # If handler is not defined, assign empty dispatcher.
+        if "handler" not in dct:
+            name = f"Ask{clsname.capitalize()}Handler"
+            handler = Dispatcher(name, doc="Handler for key %s" % name)
+            dct["handler"] = handler
+
+        dct["_orig_doc"] = dct.get("__doc__", "")
+
+        return super().__new__(cls, clsname, bases, dct)
+
+    @property
+    def __doc__(cls):
+        handler = cls.handler
+        doc = cls._orig_doc
+        if cls is not Predicate and handler is not None:
+            doc += "Handler\n"
+            doc += "    =======\n\n"
+
+            # Append the handler's doc without breaking sphinx documentation.
+            docs = ["    Multiply dispatched method: %s" % handler.name]
+            if handler.doc:
+                for line in handler.doc.splitlines():
+                    if not line:
+                        continue
+                    docs.append("    %s" % line)
+            other = []
+            for sig in handler.ordering[::-1]:
+                func = handler.funcs[sig]
+                if func.__doc__:
+                    s = '    Inputs: <%s>' % str_signature(sig)
+                    lines = []
+                    for line in func.__doc__.splitlines():
+                        lines.append("    %s" % line)
+                    s += "\n".join(lines)
+                    docs.append(s)
+                else:
+                    other.append(str_signature(sig))
+            if other:
+                othersig = "    Other signatures:"
+                for line in other:
+                    othersig += "\n        * %s" % line
+                docs.append(othersig)
+
+            doc += '\n\n'.join(docs)
+
+        return doc
+
+
+class Predicate(Boolean, metaclass=PredicateMeta):
+    """
+    Base class for mathematical predicates. It also serves as a
+    constructor for undefined predicate objects.
+
+    Explanation
+    ===========
+
+    Predicate is a function that returns a boolean value [1].
+
+    Predicate function is object, and it is instance of predicate class.
+    When a predicate is applied to arguments, ``AppliedPredicate``
+    instance is returned. This merely wraps the argument and remain
+    unevaluated. To obtain the truth value of applied predicate, use the
+    function ``ask``.
+
+    Evaluation of predicate is done by multiple dispatching. You can
+    register new handler to the predicate to support new types.
+
+    Every predicate in SymPy can be accessed via the property of ``Q``.
+    For example, ``Q.even`` returns the predicate which checks if the
+    argument is even number.
+
+    To define a predicate which can be evaluated, you must subclass this
+    class, make an instance of it, and register it to ``Q``. After then,
+    dispatch the handler by argument types.
+
+    If you directly construct predicate using this class, you will get
+    ``UndefinedPredicate`` which cannot be dispatched. This is useful
+    when you are building boolean expressions which do not need to be
+    evaluated.
+
+    Examples
+    ========
+
+    Applying and evaluating to boolean value:
+
+    >>> from sympy import Q, ask
+    >>> ask(Q.prime(7))
+    True
+
+    You can define a new predicate by subclassing and dispatching. Here,
+    we define a predicate for sexy primes [2] as an example.
+
+    >>> from sympy import Predicate, Integer
+    >>> class SexyPrimePredicate(Predicate):
+    ...     name = "sexyprime"
+    >>> Q.sexyprime = SexyPrimePredicate()
+    >>> @Q.sexyprime.register(Integer, Integer)
+    ... def _(int1, int2, assumptions):
+    ...     args = sorted([int1, int2])
+    ...     if not all(ask(Q.prime(a), assumptions) for a in args):
+    ...         return False
+    ...     return args[1] - args[0] == 6
+    >>> ask(Q.sexyprime(5, 11))
+    True
+
+    Direct constructing returns ``UndefinedPredicate``, which can be
+    applied but cannot be dispatched.
+
+    >>> from sympy import Predicate, Integer
+    >>> Q.P = Predicate("P")
+    >>> type(Q.P)
+    <class 'sympy.assumptions.assume.UndefinedPredicate'>
+    >>> Q.P(1)
+    Q.P(1)
+    >>> Q.P.register(Integer)(lambda expr, assump: True)
+    Traceback (most recent call last):
+      ...
+    TypeError: <class 'sympy.assumptions.assume.UndefinedPredicate'> cannot be dispatched.
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Predicate_%28mathematical_logic%29
+    .. [2] https://en.wikipedia.org/wiki/Sexy_prime
+
+    """
+
+    is_Atom = True
+
+    def __new__(cls, *args, **kwargs):
+        if cls is Predicate:
+            return UndefinedPredicate(*args, **kwargs)
+        obj = super().__new__(cls, *args)
+        return obj
+
+    @property
+    def name(self):
+        # May be overridden
+        return type(self).__name__
+
+    @classmethod
+    def register(cls, *types, **kwargs):
+        """
+        Register the signature to the handler.
+        """
+        if cls.handler is None:
+            raise TypeError("%s cannot be dispatched." % type(cls))
+        return cls.handler.register(*types, **kwargs)
+
+    @classmethod
+    def register_many(cls, *types, **kwargs):
+        """
+        Register multiple signatures to same handler.
+        """
+        def _(func):
+            for t in types:
+                if not is_sequence(t):
+                    t = (t,)  # for convenience, allow passing `type` to mean `(type,)`
+                cls.register(*t, **kwargs)(func)
+        return _
+
+    def __call__(self, *args):
+        return AppliedPredicate(self, *args)
+
+    def eval(self, args, assumptions=True):
+        """
+        Evaluate ``self(*args)`` under the given assumptions.
+
+        This uses only direct resolution methods, not logical inference.
+        """
+        result = None
+        try:
+            result = self.handler(*args, assumptions=assumptions)
+        except NotImplementedError:
+            pass
+        return result
+
+    def _eval_refine(self, assumptions):
+        # When Predicate is no longer Boolean, delete this method
+        return self
+
+
+class UndefinedPredicate(Predicate):
+    """
+    Predicate without handler.
+
+    Explanation
+    ===========
+
+    This predicate is generated by using ``Predicate`` directly for
+    construction. It does not have a handler, and evaluating this with
+    arguments is done by SAT solver.
+
+    Examples
+    ========
+
+    >>> from sympy import Predicate, Q
+    >>> Q.P = Predicate('P')
+    >>> Q.P.func
+    <class 'sympy.assumptions.assume.UndefinedPredicate'>
+    >>> Q.P.name
+    Str('P')
+
+    """
+
+    handler = None
+
+    def __new__(cls, name, handlers=None):
+        # "handlers" parameter supports old design
+        if not isinstance(name, Str):
+            name = Str(name)
+        obj = super(Boolean, cls).__new__(cls, name)
+        obj.handlers = handlers or []
+        return obj
+
+    @property
+    def name(self):
+        return self.args[0]
+
+    def _hashable_content(self):
+        return (self.name,)
+
+    def __getnewargs__(self):
+        return (self.name,)
+
+    def __call__(self, expr):
+        return AppliedPredicate(self, expr)
+
+    def add_handler(self, handler):
+        sympy_deprecation_warning(
+            """
+            The AskHandler system is deprecated. Predicate.add_handler()
+            should be replaced with the multipledispatch handler of Predicate.
+            """,
+            deprecated_since_version="1.8",
+            active_deprecations_target='deprecated-askhandler',
+        )
+        self.handlers.append(handler)
+
+    def remove_handler(self, handler):
+        sympy_deprecation_warning(
+            """
+            The AskHandler system is deprecated. Predicate.remove_handler()
+            should be replaced with the multipledispatch handler of Predicate.
+            """,
+            deprecated_since_version="1.8",
+            active_deprecations_target='deprecated-askhandler',
+        )
+        self.handlers.remove(handler)
+
+    def eval(self, args, assumptions=True):
+        # Support for deprecated design
+        # When old design is removed, this will always return None
+        sympy_deprecation_warning(
+            """
+            The AskHandler system is deprecated. Evaluating UndefinedPredicate
+            objects should be replaced with the multipledispatch handler of
+            Predicate.
+            """,
+            deprecated_since_version="1.8",
+            active_deprecations_target='deprecated-askhandler',
+            stacklevel=5,
+        )
+        expr, = args
+        res, _res = None, None
+        mro = inspect.getmro(type(expr))
+        for handler in self.handlers:
+            cls = get_class(handler)
+            for subclass in mro:
+                eval_ = getattr(cls, subclass.__name__, None)
+                if eval_ is None:
+                    continue
+                res = eval_(expr, assumptions)
+                # Do not stop if value returned is None
+                # Try to check for higher classes
+                if res is None:
+                    continue
+                if _res is None:
+                    _res = res
+                else:
+                    # only check consistency if both resolutors have concluded
+                    if _res != res:
+                        raise ValueError('incompatible resolutors')
+                break
+        return res
+
+
+@contextmanager
+def assuming(*assumptions):
+    """
+    Context manager for assumptions.
+
+    Examples
+    ========
+
+    >>> from sympy import assuming, Q, ask
+    >>> from sympy.abc import x, y
+    >>> print(ask(Q.integer(x + y)))
+    None
+    >>> with assuming(Q.integer(x), Q.integer(y)):
+    ...     print(ask(Q.integer(x + y)))
+    True
+    """
+    old_global_assumptions = global_assumptions.copy()
+    global_assumptions.update(assumptions)
+    try:
+        yield
+    finally:
+        global_assumptions.clear()
+        global_assumptions.update(old_global_assumptions)

.venv/lib/python3.13/site-packages/sympy/assumptions/cnf.py

@@ -0,0 +1,445 @@
+"""
+The classes used here are for the internal use of assumptions system
+only and should not be used anywhere else as these do not possess the
+signatures common to SymPy objects. For general use of logic constructs
+please refer to sympy.logic classes And, Or, Not, etc.
+"""
+from itertools import combinations, product, zip_longest
+from sympy.assumptions.assume import AppliedPredicate, Predicate
+from sympy.core.relational import Eq, Ne, Gt, Lt, Ge, Le
+from sympy.core.singleton import S
+from sympy.logic.boolalg import Or, And, Not, Xnor
+from sympy.logic.boolalg import (Equivalent, ITE, Implies, Nand, Nor, Xor)
+
+
+class Literal:
+    """
+    The smallest element of a CNF object.
+
+    Parameters
+    ==========
+
+    lit : Boolean expression
+
+    is_Not : bool
+
+    Examples
+    ========
+
+    >>> from sympy import Q
+    >>> from sympy.assumptions.cnf import Literal
+    >>> from sympy.abc import x
+    >>> Literal(Q.even(x))
+    Literal(Q.even(x), False)
+    >>> Literal(~Q.even(x))
+    Literal(Q.even(x), True)
+    """
+
+    def __new__(cls, lit, is_Not=False):
+        if isinstance(lit, Not):
+            lit = lit.args[0]
+            is_Not = True
+        elif isinstance(lit, (AND, OR, Literal)):
+            return ~lit if is_Not else lit
+        obj = super().__new__(cls)
+        obj.lit = lit
+        obj.is_Not = is_Not
+        return obj
+
+    @property
+    def arg(self):
+        return self.lit
+
+    def rcall(self, expr):
+        if callable(self.lit):
+            lit = self.lit(expr)
+        else:
+            lit = self.lit.apply(expr)
+        return type(self)(lit, self.is_Not)
+
+    def __invert__(self):
+        is_Not = not self.is_Not
+        return Literal(self.lit, is_Not)
+
+    def __str__(self):
+        return '{}({}, {})'.format(type(self).__name__, self.lit, self.is_Not)
+
+    __repr__ = __str__
+
+    def __eq__(self, other):
+        return self.arg == other.arg and self.is_Not == other.is_Not
+
+    def __hash__(self):
+        h = hash((type(self).__name__, self.arg, self.is_Not))
+        return h
+
+
+class OR:
+    """
+    A low-level implementation for Or
+    """
+    def __init__(self, *args):
+        self._args = args
+
+    @property
+    def args(self):
+        return sorted(self._args, key=str)
+
+    def rcall(self, expr):
+        return type(self)(*[arg.rcall(expr)
+                            for arg in self._args
+                            ])
+
+    def __invert__(self):
+        return AND(*[~arg for arg in self._args])
+
+    def __hash__(self):
+        return hash((type(self).__name__,) + tuple(self.args))
+
+    def __eq__(self, other):
+        return self.args == other.args
+
+    def __str__(self):
+        s = '(' + ' | '.join([str(arg) for arg in self.args]) + ')'
+        return s
+
+    __repr__ = __str__
+
+
+class AND:
+    """
+    A low-level implementation for And
+    """
+    def __init__(self, *args):
+        self._args = args
+
+    def __invert__(self):
+        return OR(*[~arg for arg in self._args])
+
+    @property
+    def args(self):
+        return sorted(self._args, key=str)
+
+    def rcall(self, expr):
+        return type(self)(*[arg.rcall(expr)
+                            for arg in self._args
+                            ])
+
+    def __hash__(self):
+        return hash((type(self).__name__,) + tuple(self.args))
+
+    def __eq__(self, other):
+        return self.args == other.args
+
+    def __str__(self):
+        s = '('+' & '.join([str(arg) for arg in self.args])+')'
+        return s
+
+    __repr__ = __str__
+
+
+def to_NNF(expr, composite_map=None):
+    """
+    Generates the Negation Normal Form of any boolean expression in terms
+    of AND, OR, and Literal objects.
+
+    Examples
+    ========
+
+    >>> from sympy import Q, Eq
+    >>> from sympy.assumptions.cnf import to_NNF
+    >>> from sympy.abc import x, y
+    >>> expr = Q.even(x) & ~Q.positive(x)
+    >>> to_NNF(expr)
+    (Literal(Q.even(x), False) & Literal(Q.positive(x), True))
+
+    Supported boolean objects are converted to corresponding predicates.
+
+    >>> to_NNF(Eq(x, y))
+    Literal(Q.eq(x, y), False)
+
+    If ``composite_map`` argument is given, ``to_NNF`` decomposes the
+    specified predicate into a combination of primitive predicates.
+
+    >>> cmap = {Q.nonpositive: Q.negative | Q.zero}
+    >>> to_NNF(Q.nonpositive, cmap)
+    (Literal(Q.negative, False) | Literal(Q.zero, False))
+    >>> to_NNF(Q.nonpositive(x), cmap)
+    (Literal(Q.negative(x), False) | Literal(Q.zero(x), False))
+    """
+    from sympy.assumptions.ask import Q
+
+    if composite_map is None:
+        composite_map = {}
+
+
+    binrelpreds = {Eq: Q.eq, Ne: Q.ne, Gt: Q.gt, Lt: Q.lt, Ge: Q.ge, Le: Q.le}
+    if type(expr) in binrelpreds:
+        pred = binrelpreds[type(expr)]
+        expr = pred(*expr.args)
+
+    if isinstance(expr, Not):
+        arg = expr.args[0]
+        tmp = to_NNF(arg, composite_map)  # Strategy: negate the NNF of expr
+        return ~tmp
+
+    if isinstance(expr, Or):
+        return OR(*[to_NNF(x, composite_map) for x in Or.make_args(expr)])
+
+    if isinstance(expr, And):
+        return AND(*[to_NNF(x, composite_map) for x in And.make_args(expr)])
+
+    if isinstance(expr, Nand):
+        tmp = AND(*[to_NNF(x, composite_map) for x in expr.args])
+        return ~tmp
+
+    if isinstance(expr, Nor):
+        tmp = OR(*[to_NNF(x, composite_map) for x in expr.args])
+        return ~tmp
+
+    if isinstance(expr, Xor):
+        cnfs = []
+        for i in range(0, len(expr.args) + 1, 2):
+            for neg in combinations(expr.args, i):
+                clause = [~to_NNF(s, composite_map) if s in neg else to_NNF(s, composite_map)
+                          for s in expr.args]
+                cnfs.append(OR(*clause))
+        return AND(*cnfs)
+
+    if isinstance(expr, Xnor):
+        cnfs = []
+        for i in range(0, len(expr.args) + 1, 2):
+            for neg in combinations(expr.args, i):
+                clause = [~to_NNF(s, composite_map) if s in neg else to_NNF(s, composite_map)
+                          for s in expr.args]
+                cnfs.append(OR(*clause))
+        return ~AND(*cnfs)
+
+    if isinstance(expr, Implies):
+        L, R = to_NNF(expr.args[0], composite_map), to_NNF(expr.args[1], composite_map)
+        return OR(~L, R)
+
+    if isinstance(expr, Equivalent):
+        cnfs = []
+        for a, b in zip_longest(expr.args, expr.args[1:], fillvalue=expr.args[0]):
+            a = to_NNF(a, composite_map)
+            b = to_NNF(b, composite_map)
+            cnfs.append(OR(~a, b))
+        return AND(*cnfs)
+
+    if isinstance(expr, ITE):
+        L = to_NNF(expr.args[0], composite_map)
+        M = to_NNF(expr.args[1], composite_map)
+        R = to_NNF(expr.args[2], composite_map)
+        return AND(OR(~L, M), OR(L, R))
+
+    if isinstance(expr, AppliedPredicate):
+        pred, args = expr.function, expr.arguments
+        newpred = composite_map.get(pred, None)
+        if newpred is not None:
+            return to_NNF(newpred.rcall(*args), composite_map)
+
+    if isinstance(expr, Predicate):
+        newpred = composite_map.get(expr, None)
+        if newpred is not None:
+            return to_NNF(newpred, composite_map)
+
+    return Literal(expr)
+
+
+def distribute_AND_over_OR(expr):
+    """
+    Distributes AND over OR in the NNF expression.
+    Returns the result( Conjunctive Normal Form of expression)
+    as a CNF object.
+    """
+    if not isinstance(expr, (AND, OR)):
+        tmp = set()
+        tmp.add(frozenset((expr,)))
+        return CNF(tmp)
+
+    if isinstance(expr, OR):
+        return CNF.all_or(*[distribute_AND_over_OR(arg)
+                            for arg in expr._args])
+
+    if isinstance(expr, AND):
+        return CNF.all_and(*[distribute_AND_over_OR(arg)
+                             for arg in expr._args])
+
+
+class CNF:
+    """
+    Class to represent CNF of a Boolean expression.
+    Consists of set of clauses, which themselves are stored as
+    frozenset of Literal objects.
+
+    Examples
+    ========
+
+    >>> from sympy import Q
+    >>> from sympy.assumptions.cnf import CNF
+    >>> from sympy.abc import x
+    >>> cnf = CNF.from_prop(Q.real(x) & ~Q.zero(x))
+    >>> cnf.clauses
+    {frozenset({Literal(Q.zero(x), True)}),
+    frozenset({Literal(Q.negative(x), False),
+    Literal(Q.positive(x), False), Literal(Q.zero(x), False)})}
+    """
+    def __init__(self, clauses=None):
+        if not clauses:
+            clauses = set()
+        self.clauses = clauses
+
+    def add(self, prop):
+        clauses = CNF.to_CNF(prop).clauses
+        self.add_clauses(clauses)
+
+    def __str__(self):
+        s = ' & '.join(
+            ['(' + ' | '.join([str(lit) for lit in clause]) +')'
+            for clause in self.clauses]
+        )
+        return s
+
+    def extend(self, props):
+        for p in props:
+            self.add(p)
+        return self
+
+    def copy(self):
+        return CNF(set(self.clauses))
+
+    def add_clauses(self, clauses):
+        self.clauses |= clauses
+
+    @classmethod
+    def from_prop(cls, prop):
+        res = cls()
+        res.add(prop)
+        return res
+
+    def __iand__(self, other):
+        self.add_clauses(other.clauses)
+        return self
+
+    def all_predicates(self):
+        predicates = set()
+        for c in self.clauses:
+            predicates |= {arg.lit for arg in c}
+        return predicates
+
+    def _or(self, cnf):
+        clauses = set()
+        for a, b in product(self.clauses, cnf.clauses):
+            tmp = set(a)
+            tmp.update(b)
+            clauses.add(frozenset(tmp))
+        return CNF(clauses)
+
+    def _and(self, cnf):
+        clauses = self.clauses.union(cnf.clauses)
+        return CNF(clauses)
+
+    def _not(self):
+        clss = list(self.clauses)
+        ll = {frozenset((~x,)) for x in clss[-1]}
+        ll = CNF(ll)
+
+        for rest in clss[:-1]:
+            p = {frozenset((~x,)) for x in rest}
+            ll = ll._or(CNF(p))
+        return ll
+
+    def rcall(self, expr):
+        clause_list = []
+        for clause in self.clauses:
+            lits = [arg.rcall(expr) for arg in clause]
+            clause_list.append(OR(*lits))
+        expr = AND(*clause_list)
+        return distribute_AND_over_OR(expr)
+
+    @classmethod
+    def all_or(cls, *cnfs):
+        b = cnfs[0].copy()
+        for rest in cnfs[1:]:
+            b = b._or(rest)
+        return b
+
+    @classmethod
+    def all_and(cls, *cnfs):
+        b = cnfs[0].copy()
+        for rest in cnfs[1:]:
+            b = b._and(rest)
+        return b
+
+    @classmethod
+    def to_CNF(cls, expr):
+        from sympy.assumptions.facts import get_composite_predicates
+        expr = to_NNF(expr, get_composite_predicates())
+        expr = distribute_AND_over_OR(expr)
+        return expr
+
+    @classmethod
+    def CNF_to_cnf(cls, cnf):
+        """
+        Converts CNF object to SymPy's boolean expression
+        retaining the form of expression.
+        """
+        def remove_literal(arg):
+            return Not(arg.lit) if arg.is_Not else arg.lit
+
+        return And(*(Or(*(remove_literal(arg) for arg in clause)) for clause in cnf.clauses))
+
+
+class EncodedCNF:
+    """
+    Class for encoding the CNF expression.
+    """
+    def __init__(self, data=None, encoding=None):
+        if not data and not encoding:
+            data = []
+            encoding = {}
+        self.data = data
+        self.encoding = encoding
+        self._symbols = list(encoding.keys())
+
+    def from_cnf(self, cnf):
+        self._symbols = list(cnf.all_predicates())
+        n = len(self._symbols)
+        self.encoding = dict(zip(self._symbols, range(1, n + 1)))
+        self.data = [self.encode(clause) for clause in cnf.clauses]
+
+    @property
+    def symbols(self):
+        return self._symbols
+
+    @property
+    def variables(self):
+        return range(1, len(self._symbols) + 1)
+
+    def copy(self):
+        new_data = [set(clause) for clause in self.data]
+        return EncodedCNF(new_data, dict(self.encoding))
+
+    def add_prop(self, prop):
+        cnf = CNF.from_prop(prop)
+        self.add_from_cnf(cnf)
+
+    def add_from_cnf(self, cnf):
+        clauses = [self.encode(clause) for clause in cnf.clauses]
+        self.data += clauses
+
+    def encode_arg(self, arg):
+        literal = arg.lit
+        value = self.encoding.get(literal, None)
+        if value is None:
+            n = len(self._symbols)
+            self._symbols.append(literal)
+            value = self.encoding[literal] = n + 1
+        if arg.is_Not:
+            return -value
+        else:
+            return value
+
+    def encode(self, clause):
+        return {self.encode_arg(arg) if not arg.lit == S.false else 0 for arg in clause}

.venv/lib/python3.13/site-packages/sympy/assumptions/facts.py

@@ -0,0 +1,270 @@
+"""
+Known facts in assumptions module.
+
+This module defines the facts between unary predicates in ``get_known_facts()``,
+and supports functions to generate the contents in
+``sympy.assumptions.ask_generated`` file.
+"""
+
+from sympy.assumptions.ask import Q
+from sympy.assumptions.assume import AppliedPredicate
+from sympy.core.cache import cacheit
+from sympy.core.symbol import Symbol
+from sympy.logic.boolalg import (to_cnf, And, Not, Implies, Equivalent,
+    Exclusive,)
+from sympy.logic.inference import satisfiable
+
+
+@cacheit
+def get_composite_predicates():
+    # To reduce the complexity of sat solver, these predicates are
+    # transformed into the combination of primitive predicates.
+    return {
+        Q.real : Q.negative | Q.zero | Q.positive,
+        Q.integer : Q.even | Q.odd,
+        Q.nonpositive : Q.negative | Q.zero,
+        Q.nonzero : Q.negative | Q.positive,
+        Q.nonnegative : Q.zero | Q.positive,
+        Q.extended_real : Q.negative_infinite | Q.negative | Q.zero | Q.positive | Q.positive_infinite,
+        Q.extended_positive: Q.positive | Q.positive_infinite,
+        Q.extended_negative: Q.negative | Q.negative_infinite,
+        Q.extended_nonzero: Q.negative_infinite | Q.negative | Q.positive | Q.positive_infinite,
+        Q.extended_nonpositive: Q.negative_infinite | Q.negative | Q.zero,
+        Q.extended_nonnegative: Q.zero | Q.positive | Q.positive_infinite,
+        Q.complex : Q.algebraic | Q.transcendental
+    }
+
+
+@cacheit
+def get_known_facts(x=None):
+    """
+    Facts between unary predicates.
+
+    Parameters
+    ==========
+
+    x : Symbol, optional
+        Placeholder symbol for unary facts. Default is ``Symbol('x')``.
+
+    Returns
+    =======
+
+    fact : Known facts in conjugated normal form.
+
+    """
+    if x is None:
+        x = Symbol('x')
+
+    fact = And(
+        get_number_facts(x),
+        get_matrix_facts(x)
+    )
+    return fact
+
+
+@cacheit
+def get_number_facts(x = None):
+    """
+    Facts between unary number predicates.
+
+    Parameters
+    ==========
+
+    x : Symbol, optional
+        Placeholder symbol for unary facts. Default is ``Symbol('x')``.
+
+    Returns
+    =======
+
+    fact : Known facts in conjugated normal form.
+
+    """
+    if x is None:
+        x = Symbol('x')
+
+    fact = And(
+        # primitive predicates for extended real exclude each other.
+        Exclusive(Q.negative_infinite(x), Q.negative(x), Q.zero(x),
+            Q.positive(x), Q.positive_infinite(x)),
+
+        # build complex plane
+        Exclusive(Q.real(x), Q.imaginary(x)),
+        Implies(Q.real(x) | Q.imaginary(x), Q.complex(x)),
+
+        # other subsets of complex
+        Exclusive(Q.transcendental(x), Q.algebraic(x)),
+        Equivalent(Q.real(x), Q.rational(x) | Q.irrational(x)),
+        Exclusive(Q.irrational(x), Q.rational(x)),
+        Implies(Q.rational(x), Q.algebraic(x)),
+
+        # integers
+        Exclusive(Q.even(x), Q.odd(x)),
+        Implies(Q.integer(x), Q.rational(x)),
+        Implies(Q.zero(x), Q.even(x)),
+        Exclusive(Q.composite(x), Q.prime(x)),
+        Implies(Q.composite(x) | Q.prime(x), Q.integer(x) & Q.positive(x)),
+        Implies(Q.even(x) & Q.positive(x) & ~Q.prime(x), Q.composite(x)),
+
+        # hermitian and antihermitian
+        Implies(Q.real(x), Q.hermitian(x)),
+        Implies(Q.imaginary(x), Q.antihermitian(x)),
+        Implies(Q.zero(x), Q.hermitian(x) | Q.antihermitian(x)),
+
+        # define finity and infinity, and build extended real line
+        Exclusive(Q.infinite(x), Q.finite(x)),
+        Implies(Q.complex(x), Q.finite(x)),
+        Implies(Q.negative_infinite(x) | Q.positive_infinite(x), Q.infinite(x)),
+
+        # commutativity
+        Implies(Q.finite(x) | Q.infinite(x), Q.commutative(x)),
+    )
+    return fact
+
+
+@cacheit
+def get_matrix_facts(x = None):
+    """
+    Facts between unary matrix predicates.
+
+    Parameters
+    ==========
+
+    x : Symbol, optional
+        Placeholder symbol for unary facts. Default is ``Symbol('x')``.
+
+    Returns
+    =======
+
+    fact : Known facts in conjugated normal form.
+
+    """
+    if x is None:
+        x = Symbol('x')
+
+    fact = And(
+        # matrices
+        Implies(Q.orthogonal(x), Q.positive_definite(x)),
+        Implies(Q.orthogonal(x), Q.unitary(x)),
+        Implies(Q.unitary(x) & Q.real_elements(x), Q.orthogonal(x)),
+        Implies(Q.unitary(x), Q.normal(x)),
+        Implies(Q.unitary(x), Q.invertible(x)),
+        Implies(Q.normal(x), Q.square(x)),
+        Implies(Q.diagonal(x), Q.normal(x)),
+        Implies(Q.positive_definite(x), Q.invertible(x)),
+        Implies(Q.diagonal(x), Q.upper_triangular(x)),
+        Implies(Q.diagonal(x), Q.lower_triangular(x)),
+        Implies(Q.lower_triangular(x), Q.triangular(x)),
+        Implies(Q.upper_triangular(x), Q.triangular(x)),
+        Implies(Q.triangular(x), Q.upper_triangular(x) | Q.lower_triangular(x)),
+        Implies(Q.upper_triangular(x) & Q.lower_triangular(x), Q.diagonal(x)),
+        Implies(Q.diagonal(x), Q.symmetric(x)),
+        Implies(Q.unit_triangular(x), Q.triangular(x)),
+        Implies(Q.invertible(x), Q.fullrank(x)),
+        Implies(Q.invertible(x), Q.square(x)),
+        Implies(Q.symmetric(x), Q.square(x)),
+        Implies(Q.fullrank(x) & Q.square(x), Q.invertible(x)),
+        Equivalent(Q.invertible(x), ~Q.singular(x)),
+        Implies(Q.integer_elements(x), Q.real_elements(x)),
+        Implies(Q.real_elements(x), Q.complex_elements(x)),
+    )
+    return fact
+
+
+
+def generate_known_facts_dict(keys, fact):
+    """
+    Computes and returns a dictionary which contains the relations between
+    unary predicates.
+
+    Each key is a predicate, and item is two groups of predicates.
+    First group contains the predicates which are implied by the key, and
+    second group contains the predicates which are rejected by the key.
+
+    All predicates in *keys* and *fact* must be unary and have same placeholder
+    symbol.
+
+    Parameters
+    ==========
+
+    keys : list of AppliedPredicate instances.
+
+    fact : Fact between predicates in conjugated normal form.
+
+    Examples
+    ========
+
+    >>> from sympy import Q, And, Implies
+    >>> from sympy.assumptions.facts import generate_known_facts_dict
+    >>> from sympy.abc import x
+    >>> keys = [Q.even(x), Q.odd(x), Q.zero(x)]
+    >>> fact = And(Implies(Q.even(x), ~Q.odd(x)),
+    ...     Implies(Q.zero(x), Q.even(x)))
+    >>> generate_known_facts_dict(keys, fact)
+    {Q.even: ({Q.even}, {Q.odd}),
+     Q.odd: ({Q.odd}, {Q.even, Q.zero}),
+     Q.zero: ({Q.even, Q.zero}, {Q.odd})}
+    """
+    fact_cnf = to_cnf(fact)
+    mapping = single_fact_lookup(keys, fact_cnf)
+
+    ret = {}
+    for key, value in mapping.items():
+        implied = set()
+        rejected = set()
+        for expr in value:
+            if isinstance(expr, AppliedPredicate):
+                implied.add(expr.function)
+            elif isinstance(expr, Not):
+                pred = expr.args[0]
+                rejected.add(pred.function)
+        ret[key.function] = (implied, rejected)
+    return ret
+
+
+@cacheit
+def get_known_facts_keys():
+    """
+    Return every unary predicates registered to ``Q``.
+
+    This function is used to generate the keys for
+    ``generate_known_facts_dict``.
+
+    """
+    # exclude polyadic predicates
+    exclude = {Q.eq, Q.ne, Q.gt, Q.lt, Q.ge, Q.le}
+
+    result = []
+    for attr in Q.__class__.__dict__:
+        if attr.startswith('__'):
+            continue
+        pred = getattr(Q, attr)
+        if pred in exclude:
+            continue
+        result.append(pred)
+    return result
+
+
+def single_fact_lookup(known_facts_keys, known_facts_cnf):
+    # Return the dictionary for quick lookup of single fact
+    mapping = {}
+    for key in known_facts_keys:
+        mapping[key] = {key}
+        for other_key in known_facts_keys:
+            if other_key != key:
+                if ask_full_inference(other_key, key, known_facts_cnf):
+                    mapping[key].add(other_key)
+                if ask_full_inference(~other_key, key, known_facts_cnf):
+                    mapping[key].add(~other_key)
+    return mapping
+
+
+def ask_full_inference(proposition, assumptions, known_facts_cnf):
+    """
+    Method for inferring properties about objects.
+
+    """
+    if not satisfiable(And(known_facts_cnf, assumptions, proposition)):
+        return False
+    if not satisfiable(And(known_facts_cnf, assumptions, Not(proposition))):
+        return True
+    return None

.venv/lib/python3.13/site-packages/sympy/assumptions/lra_satask.py

@@ -0,0 +1,286 @@
+from sympy.assumptions.assume import global_assumptions
+from sympy.assumptions.cnf import CNF, EncodedCNF
+from sympy.assumptions.ask import Q
+from sympy.logic.inference import satisfiable
+from sympy.logic.algorithms.lra_theory import UnhandledInput, ALLOWED_PRED
+from sympy.matrices.kind import MatrixKind
+from sympy.core.kind import NumberKind
+from sympy.assumptions.assume import AppliedPredicate
+from sympy.core.mul import Mul
+from sympy.core.singleton import S
+
+
+def lra_satask(proposition, assumptions=True, context=global_assumptions):
+    """
+    Function to evaluate the proposition with assumptions using SAT algorithm
+    in conjunction with an Linear Real Arithmetic theory solver.
+
+    Used to handle inequalities. Should eventually be depreciated and combined
+    into satask, but infinity handling and other things need to be implemented
+    before that can happen.
+    """
+    props = CNF.from_prop(proposition)
+    _props = CNF.from_prop(~proposition)
+
+    cnf = CNF.from_prop(assumptions)
+    assumptions = EncodedCNF()
+    assumptions.from_cnf(cnf)
+
+    context_cnf = CNF()
+    if context:
+        context_cnf = context_cnf.extend(context)
+
+    assumptions.add_from_cnf(context_cnf)
+
+    return check_satisfiability(props, _props, assumptions)
+
+# Some predicates such as Q.prime can't be handled by lra_satask.
+# For example, (x > 0) & (x < 1) & Q.prime(x) is unsat but lra_satask would think it was sat.
+# WHITE_LIST is a list of predicates that can always be handled.
+WHITE_LIST = ALLOWED_PRED | {Q.positive, Q.negative, Q.zero, Q.nonzero, Q.nonpositive, Q.nonnegative,
+                                            Q.extended_positive, Q.extended_negative, Q.extended_nonpositive,
+                                            Q.extended_negative, Q.extended_nonzero, Q.negative_infinite,
+                                            Q.positive_infinite}
+
+
+def check_satisfiability(prop, _prop, factbase):
+    sat_true = factbase.copy()
+    sat_false = factbase.copy()
+    sat_true.add_from_cnf(prop)
+    sat_false.add_from_cnf(_prop)
+
+    all_pred, all_exprs = get_all_pred_and_expr_from_enc_cnf(sat_true)
+
+    for pred in all_pred:
+        if pred.function not in WHITE_LIST and pred.function != Q.ne:
+            raise UnhandledInput(f"LRASolver: {pred} is an unhandled predicate")
+    for expr in all_exprs:
+        if expr.kind == MatrixKind(NumberKind):
+            raise UnhandledInput(f"LRASolver: {expr} is of MatrixKind")
+        if expr == S.NaN:
+            raise UnhandledInput("LRASolver: nan")
+
+    # convert old assumptions into predicates and add them to sat_true and sat_false
+    # also check for unhandled predicates
+    for assm in extract_pred_from_old_assum(all_exprs):
+        n = len(sat_true.encoding)
+        if assm not in sat_true.encoding:
+            sat_true.encoding[assm] = n+1
+        sat_true.data.append([sat_true.encoding[assm]])
+
+        n = len(sat_false.encoding)
+        if assm not in sat_false.encoding:
+            sat_false.encoding[assm] = n+1
+        sat_false.data.append([sat_false.encoding[assm]])
+
+
+    sat_true = _preprocess(sat_true)
+    sat_false = _preprocess(sat_false)
+
+    can_be_true = satisfiable(sat_true, use_lra_theory=True) is not False
+    can_be_false = satisfiable(sat_false, use_lra_theory=True) is not False
+
+    if can_be_true and can_be_false:
+        return None
+
+    if can_be_true and not can_be_false:
+        return True
+
+    if not can_be_true and can_be_false:
+        return False
+
+    if not can_be_true and not can_be_false:
+        raise ValueError("Inconsistent assumptions")
+
+
+def _preprocess(enc_cnf):
+    """
+    Returns an encoded cnf with only Q.eq, Q.gt, Q.lt,
+    Q.ge, and Q.le predicate.
+
+    Converts every unequality into a disjunction of strict
+    inequalities. For example, x != 3 would become
+    x < 3 OR x > 3.
+
+    Also converts all negated Q.ne predicates into
+    equalities.
+    """
+
+    # loops through each literal in each clause
+    # to construct a new, preprocessed encodedCNF
+
+    enc_cnf = enc_cnf.copy()
+    cur_enc = 1
+    rev_encoding = {value: key for key, value in enc_cnf.encoding.items()}
+
+    new_encoding = {}
+    new_data = []
+    for clause in enc_cnf.data:
+        new_clause = []
+        for lit in clause:
+            if lit == 0:
+                new_clause.append(lit)
+                new_encoding[lit] = False
+                continue
+            prop = rev_encoding[abs(lit)]
+            negated = lit < 0
+            sign = (lit > 0) - (lit < 0)
+
+            prop = _pred_to_binrel(prop)
+
+            if not isinstance(prop, AppliedPredicate):
+                if prop not in new_encoding:
+                    new_encoding[prop] = cur_enc
+                    cur_enc += 1
+                lit = new_encoding[prop]
+                new_clause.append(sign*lit)
+                continue
+
+
+            if negated and prop.function == Q.eq:
+                negated = False
+                prop = Q.ne(*prop.arguments)
+
+            if prop.function == Q.ne:
+                arg1, arg2 = prop.arguments
+                if negated:
+                    new_prop = Q.eq(arg1, arg2)
+                    if new_prop not in new_encoding:
+                        new_encoding[new_prop] = cur_enc
+                        cur_enc += 1
+
+                    new_enc = new_encoding[new_prop]
+                    new_clause.append(new_enc)
+                    continue
+                else:
+                    new_props = (Q.gt(arg1, arg2), Q.lt(arg1, arg2))
+                    for new_prop in new_props:
+                        if new_prop not in new_encoding:
+                            new_encoding[new_prop] = cur_enc
+                            cur_enc += 1
+
+                        new_enc = new_encoding[new_prop]
+                        new_clause.append(new_enc)
+                    continue
+
+            if prop.function == Q.eq and negated:
+                assert False
+
+            if prop not in new_encoding:
+                new_encoding[prop] = cur_enc
+                cur_enc += 1
+            new_clause.append(new_encoding[prop]*sign)
+        new_data.append(new_clause)
+
+    assert len(new_encoding) >= cur_enc - 1
+
+    enc_cnf = EncodedCNF(new_data, new_encoding)
+    return enc_cnf
+
+
+def _pred_to_binrel(pred):
+    if not isinstance(pred, AppliedPredicate):
+        return pred
+
+    if pred.function in pred_to_pos_neg_zero:
+        f = pred_to_pos_neg_zero[pred.function]
+        if f is False:
+            return False
+        pred = f(pred.arguments[0])
+
+    if pred.function == Q.positive:
+        pred = Q.gt(pred.arguments[0], 0)
+    elif pred.function == Q.negative:
+        pred = Q.lt(pred.arguments[0], 0)
+    elif pred.function == Q.zero:
+        pred = Q.eq(pred.arguments[0], 0)
+    elif pred.function == Q.nonpositive:
+        pred = Q.le(pred.arguments[0], 0)
+    elif pred.function == Q.nonnegative:
+        pred = Q.ge(pred.arguments[0], 0)
+    elif pred.function == Q.nonzero:
+        pred = Q.ne(pred.arguments[0], 0)
+
+    return pred
+
+pred_to_pos_neg_zero = {
+    Q.extended_positive: Q.positive,
+    Q.extended_negative: Q.negative,
+    Q.extended_nonpositive: Q.nonpositive,
+    Q.extended_negative: Q.negative,
+    Q.extended_nonzero: Q.nonzero,
+    Q.negative_infinite: False,
+    Q.positive_infinite: False
+}
+
+def get_all_pred_and_expr_from_enc_cnf(enc_cnf):
+    all_exprs = set()
+    all_pred = set()
+    for pred in enc_cnf.encoding.keys():
+        if isinstance(pred, AppliedPredicate):
+            all_pred.add(pred)
+            all_exprs.update(pred.arguments)
+
+    return all_pred, all_exprs
+
+def extract_pred_from_old_assum(all_exprs):
+    """
+    Returns a list of relevant new assumption predicate
+    based on any old assumptions.
+
+    Raises an UnhandledInput exception if any of the assumptions are
+    unhandled.
+
+    Ignored predicate:
+    - commutative
+    - complex
+    - algebraic
+    - transcendental
+    - extended_real
+    - real
+    - all matrix predicate
+    - rational
+    - irrational
+
+    Example
+    =======
+    >>> from sympy.assumptions.lra_satask import extract_pred_from_old_assum
+    >>> from sympy import symbols
+    >>> x, y = symbols("x y", positive=True)
+    >>> extract_pred_from_old_assum([x, y, 2])
+    [Q.positive(x), Q.positive(y)]
+    """
+    ret = []
+    for expr in all_exprs:
+        if not hasattr(expr, "free_symbols"):
+            continue
+        if len(expr.free_symbols) == 0:
+            continue
+
+        if expr.is_real is not True:
+            raise UnhandledInput(f"LRASolver: {expr} must be real")
+        # test for I times imaginary variable; such expressions are considered real
+        if isinstance(expr, Mul) and any(arg.is_real is not True for arg in expr.args):
+            raise UnhandledInput(f"LRASolver: {expr} must be real")
+
+        if expr.is_integer == True and expr.is_zero != True:
+            raise UnhandledInput(f"LRASolver: {expr} is an integer")
+        if expr.is_integer == False:
+            raise UnhandledInput(f"LRASolver: {expr} can't be an integer")
+        if expr.is_rational == False:
+            raise UnhandledInput(f"LRASolver: {expr} is irational")
+
+        if expr.is_zero:
+            ret.append(Q.zero(expr))
+        elif expr.is_positive:
+            ret.append(Q.positive(expr))
+        elif expr.is_negative:
+            ret.append(Q.negative(expr))
+        elif expr.is_nonzero:
+            ret.append(Q.nonzero(expr))
+        elif expr.is_nonpositive:
+            ret.append(Q.nonpositive(expr))
+        elif expr.is_nonnegative:
+            ret.append(Q.nonnegative(expr))
+
+    return ret

.venv/lib/python3.13/site-packages/sympy/assumptions/refine.py

@@ -0,0 +1,405 @@
+from __future__ import annotations
+from typing import Callable
+
+from sympy.core import S, Add, Expr, Basic, Mul, Pow, Rational
+from sympy.core.logic import fuzzy_not
+from sympy.logic.boolalg import Boolean
+
+from sympy.assumptions import ask, Q  # type: ignore
+
+
+def refine(expr, assumptions=True):
+    """
+    Simplify an expression using assumptions.
+
+    Explanation
+    ===========
+
+    Unlike :func:`~.simplify` which performs structural simplification
+    without any assumption, this function transforms the expression into
+    the form which is only valid under certain assumptions. Note that
+    ``simplify()`` is generally not done in refining process.
+
+    Refining boolean expression involves reducing it to ``S.true`` or
+    ``S.false``. Unlike :func:`~.ask`, the expression will not be reduced
+    if the truth value cannot be determined.
+
+    Examples
+    ========
+
+    >>> from sympy import refine, sqrt, Q
+    >>> from sympy.abc import x
+    >>> refine(sqrt(x**2), Q.real(x))
+    Abs(x)
+    >>> refine(sqrt(x**2), Q.positive(x))
+    x
+
+    >>> refine(Q.real(x), Q.positive(x))
+    True
+    >>> refine(Q.positive(x), Q.real(x))
+    Q.positive(x)
+
+    See Also
+    ========
+
+    sympy.simplify.simplify.simplify : Structural simplification without assumptions.
+    sympy.assumptions.ask.ask : Query for boolean expressions using assumptions.
+    """
+    if not isinstance(expr, Basic):
+        return expr
+
+    if not expr.is_Atom:
+        args = [refine(arg, assumptions) for arg in expr.args]
+        # TODO: this will probably not work with Integral or Polynomial
+        expr = expr.func(*args)
+    if hasattr(expr, '_eval_refine'):
+        ref_expr = expr._eval_refine(assumptions)
+        if ref_expr is not None:
+            return ref_expr
+    name = expr.__class__.__name__
+    handler = handlers_dict.get(name, None)
+    if handler is None:
+        return expr
+    new_expr = handler(expr, assumptions)
+    if (new_expr is None) or (expr == new_expr):
+        return expr
+    if not isinstance(new_expr, Expr):
+        return new_expr
+    return refine(new_expr, assumptions)
+
+
+def refine_abs(expr, assumptions):
+    """
+    Handler for the absolute value.
+
+    Examples
+    ========
+
+    >>> from sympy import Q, Abs
+    >>> from sympy.assumptions.refine import refine_abs
+    >>> from sympy.abc import x
+    >>> refine_abs(Abs(x), Q.real(x))
+    >>> refine_abs(Abs(x), Q.positive(x))
+    x
+    >>> refine_abs(Abs(x), Q.negative(x))
+    -x
+
+    """
+    from sympy.functions.elementary.complexes import Abs
+    arg = expr.args[0]
+    if ask(Q.real(arg), assumptions) and \
+            fuzzy_not(ask(Q.negative(arg), assumptions)):
+        # if it's nonnegative
+        return arg
+    if ask(Q.negative(arg), assumptions):
+        return -arg
+    # arg is Mul
+    if isinstance(arg, Mul):
+        r = [refine(abs(a), assumptions) for a in arg.args]
+        non_abs = []
+        in_abs = []
+        for i in r:
+            if isinstance(i, Abs):
+                in_abs.append(i.args[0])
+            else:
+                non_abs.append(i)
+        return Mul(*non_abs) * Abs(Mul(*in_abs))
+
+
+def refine_Pow(expr, assumptions):
+    """
+    Handler for instances of Pow.
+
+    Examples
+    ========
+
+    >>> from sympy import Q
+    >>> from sympy.assumptions.refine import refine_Pow
+    >>> from sympy.abc import x,y,z
+    >>> refine_Pow((-1)**x, Q.real(x))
+    >>> refine_Pow((-1)**x, Q.even(x))
+    1
+    >>> refine_Pow((-1)**x, Q.odd(x))
+    -1
+
+    For powers of -1, even parts of the exponent can be simplified:
+
+    >>> refine_Pow((-1)**(x+y), Q.even(x))
+    (-1)**y
+    >>> refine_Pow((-1)**(x+y+z), Q.odd(x) & Q.odd(z))
+    (-1)**y
+    >>> refine_Pow((-1)**(x+y+2), Q.odd(x))
+    (-1)**(y + 1)
+    >>> refine_Pow((-1)**(x+3), True)
+    (-1)**(x + 1)
+
+    """
+    from sympy.functions.elementary.complexes import Abs
+    from sympy.functions import sign
+    if isinstance(expr.base, Abs):
+        if ask(Q.real(expr.base.args[0]), assumptions) and \
+                ask(Q.even(expr.exp), assumptions):
+            return expr.base.args[0] ** expr.exp
+    if ask(Q.real(expr.base), assumptions):
+        if expr.base.is_number:
+            if ask(Q.even(expr.exp), assumptions):
+                return abs(expr.base) ** expr.exp
+            if ask(Q.odd(expr.exp), assumptions):
+                return sign(expr.base) * abs(expr.base) ** expr.exp
+        if isinstance(expr.exp, Rational):
+            if isinstance(expr.base, Pow):
+                return abs(expr.base.base) ** (expr.base.exp * expr.exp)
+
+        if expr.base is S.NegativeOne:
+            if expr.exp.is_Add:
+
+                old = expr
+
+                # For powers of (-1) we can remove
+                #  - even terms
+                #  - pairs of odd terms
+                #  - a single odd term + 1
+                #  - A numerical constant N can be replaced with mod(N,2)
+
+                coeff, terms = expr.exp.as_coeff_add()
+                terms = set(terms)
+                even_terms = set()
+                odd_terms = set()
+                initial_number_of_terms = len(terms)
+
+                for t in terms:
+                    if ask(Q.even(t), assumptions):
+                        even_terms.add(t)
+                    elif ask(Q.odd(t), assumptions):
+                        odd_terms.add(t)
+
+                terms -= even_terms
+                if len(odd_terms) % 2:
+                    terms -= odd_terms
+                    new_coeff = (coeff + S.One) % 2
+                else:
+                    terms -= odd_terms
+                    new_coeff = coeff % 2
+
+                if new_coeff != coeff or len(terms) < initial_number_of_terms:
+                    terms.add(new_coeff)
+                    expr = expr.base**(Add(*terms))
+
+                # Handle (-1)**((-1)**n/2 + m/2)
+                e2 = 2*expr.exp
+                if ask(Q.even(e2), assumptions):
+                    if e2.could_extract_minus_sign():
+                        e2 *= expr.base
+                if e2.is_Add:
+                    i, p = e2.as_two_terms()
+                    if p.is_Pow and p.base is S.NegativeOne:
+                        if ask(Q.integer(p.exp), assumptions):
+                            i = (i + 1)/2
+                            if ask(Q.even(i), assumptions):
+                                return expr.base**p.exp
+                            elif ask(Q.odd(i), assumptions):
+                                return expr.base**(p.exp + 1)
+                            else:
+                                return expr.base**(p.exp + i)
+
+                if old != expr:
+                    return expr
+
+
+def refine_atan2(expr, assumptions):
+    """
+    Handler for the atan2 function.
+
+    Examples
+    ========
+
+    >>> from sympy import Q, atan2
+    >>> from sympy.assumptions.refine import refine_atan2
+    >>> from sympy.abc import x, y
+    >>> refine_atan2(atan2(y,x), Q.real(y) & Q.positive(x))
+    atan(y/x)
+    >>> refine_atan2(atan2(y,x), Q.negative(y) & Q.negative(x))
+    atan(y/x) - pi
+    >>> refine_atan2(atan2(y,x), Q.positive(y) & Q.negative(x))
+    atan(y/x) + pi
+    >>> refine_atan2(atan2(y,x), Q.zero(y) & Q.negative(x))
+    pi
+    >>> refine_atan2(atan2(y,x), Q.positive(y) & Q.zero(x))
+    pi/2
+    >>> refine_atan2(atan2(y,x), Q.negative(y) & Q.zero(x))
+    -pi/2
+    >>> refine_atan2(atan2(y,x), Q.zero(y) & Q.zero(x))
+    nan
+    """
+    from sympy.functions.elementary.trigonometric import atan
+    y, x = expr.args
+    if ask(Q.real(y) & Q.positive(x), assumptions):
+        return atan(y / x)
+    elif ask(Q.negative(y) & Q.negative(x), assumptions):
+        return atan(y / x) - S.Pi
+    elif ask(Q.positive(y) & Q.negative(x), assumptions):
+        return atan(y / x) + S.Pi
+    elif ask(Q.zero(y) & Q.negative(x), assumptions):
+        return S.Pi
+    elif ask(Q.positive(y) & Q.zero(x), assumptions):
+        return S.Pi/2
+    elif ask(Q.negative(y) & Q.zero(x), assumptions):
+        return -S.Pi/2
+    elif ask(Q.zero(y) & Q.zero(x), assumptions):
+        return S.NaN
+    else:
+        return expr
+
+
+def refine_re(expr, assumptions):
+    """
+    Handler for real part.
+
+    Examples
+    ========
+
+    >>> from sympy.assumptions.refine import refine_re
+    >>> from sympy import Q, re
+    >>> from sympy.abc import x
+    >>> refine_re(re(x), Q.real(x))
+    x
+    >>> refine_re(re(x), Q.imaginary(x))
+    0
+    """
+    arg = expr.args[0]
+    if ask(Q.real(arg), assumptions):
+        return arg
+    if ask(Q.imaginary(arg), assumptions):
+        return S.Zero
+    return _refine_reim(expr, assumptions)
+
+
+def refine_im(expr, assumptions):
+    """
+    Handler for imaginary part.
+
+    Explanation
+    ===========
+
+    >>> from sympy.assumptions.refine import refine_im
+    >>> from sympy import Q, im
+    >>> from sympy.abc import x
+    >>> refine_im(im(x), Q.real(x))
+    0
+    >>> refine_im(im(x), Q.imaginary(x))
+    -I*x
+    """
+    arg = expr.args[0]
+    if ask(Q.real(arg), assumptions):
+        return S.Zero
+    if ask(Q.imaginary(arg), assumptions):
+        return - S.ImaginaryUnit * arg
+    return _refine_reim(expr, assumptions)
+
+def refine_arg(expr, assumptions):
+    """
+    Handler for complex argument
+
+    Explanation
+    ===========
+
+    >>> from sympy.assumptions.refine import refine_arg
+    >>> from sympy import Q, arg
+    >>> from sympy.abc import x
+    >>> refine_arg(arg(x), Q.positive(x))
+    0
+    >>> refine_arg(arg(x), Q.negative(x))
+    pi
+    """
+    rg = expr.args[0]
+    if ask(Q.positive(rg), assumptions):
+        return S.Zero
+    if ask(Q.negative(rg), assumptions):
+        return S.Pi
+    return None
+
+
+def _refine_reim(expr, assumptions):
+    # Helper function for refine_re & refine_im
+    expanded = expr.expand(complex = True)
+    if expanded != expr:
+        refined = refine(expanded, assumptions)
+        if refined != expanded:
+            return refined
+    # Best to leave the expression as is
+    return None
+
+
+def refine_sign(expr, assumptions):
+    """
+    Handler for sign.
+
+    Examples
+    ========
+
+    >>> from sympy.assumptions.refine import refine_sign
+    >>> from sympy import Symbol, Q, sign, im
+    >>> x = Symbol('x', real = True)
+    >>> expr = sign(x)
+    >>> refine_sign(expr, Q.positive(x) & Q.nonzero(x))
+    1
+    >>> refine_sign(expr, Q.negative(x) & Q.nonzero(x))
+    -1
+    >>> refine_sign(expr, Q.zero(x))
+    0
+    >>> y = Symbol('y', imaginary = True)
+    >>> expr = sign(y)
+    >>> refine_sign(expr, Q.positive(im(y)))
+    I
+    >>> refine_sign(expr, Q.negative(im(y)))
+    -I
+    """
+    arg = expr.args[0]
+    if ask(Q.zero(arg), assumptions):
+        return S.Zero
+    if ask(Q.real(arg)):
+        if ask(Q.positive(arg), assumptions):
+            return S.One
+        if ask(Q.negative(arg), assumptions):
+            return S.NegativeOne
+    if ask(Q.imaginary(arg)):
+        arg_re, arg_im = arg.as_real_imag()
+        if ask(Q.positive(arg_im), assumptions):
+            return S.ImaginaryUnit
+        if ask(Q.negative(arg_im), assumptions):
+            return -S.ImaginaryUnit
+    return expr
+
+
+def refine_matrixelement(expr, assumptions):
+    """
+    Handler for symmetric part.
+
+    Examples
+    ========
+
+    >>> from sympy.assumptions.refine import refine_matrixelement
+    >>> from sympy import MatrixSymbol, Q
+    >>> X = MatrixSymbol('X', 3, 3)
+    >>> refine_matrixelement(X[0, 1], Q.symmetric(X))
+    X[0, 1]
+    >>> refine_matrixelement(X[1, 0], Q.symmetric(X))
+    X[0, 1]
+    """
+    from sympy.matrices.expressions.matexpr import MatrixElement
+    matrix, i, j = expr.args
+    if ask(Q.symmetric(matrix), assumptions):
+        if (i - j).could_extract_minus_sign():
+            return expr
+        return MatrixElement(matrix, j, i)
+
+handlers_dict: dict[str, Callable[[Expr, Boolean], Expr]] = {
+    'Abs': refine_abs,
+    'Pow': refine_Pow,
+    'atan2': refine_atan2,
+    're': refine_re,
+    'im': refine_im,
+    'arg': refine_arg,
+    'sign': refine_sign,
+    'MatrixElement': refine_matrixelement
+}

.venv/lib/python3.13/site-packages/sympy/assumptions/satask.py

@@ -0,0 +1,369 @@
+"""
+Module to evaluate the proposition with assumptions using SAT algorithm.
+"""
+
+from sympy.core.singleton import S
+from sympy.core.symbol import Symbol
+from sympy.core.kind import NumberKind, UndefinedKind
+from sympy.assumptions.ask_generated import get_all_known_matrix_facts, get_all_known_number_facts
+from sympy.assumptions.assume import global_assumptions, AppliedPredicate
+from sympy.assumptions.sathandlers import class_fact_registry
+from sympy.core import oo
+from sympy.logic.inference import satisfiable
+from sympy.assumptions.cnf import CNF, EncodedCNF
+from sympy.matrices.kind import MatrixKind
+
+
+def satask(proposition, assumptions=True, context=global_assumptions,
+        use_known_facts=True, iterations=oo):
+    """
+    Function to evaluate the proposition with assumptions using SAT algorithm.
+
+    This function extracts every fact relevant to the expressions composing
+    proposition and assumptions. For example, if a predicate containing
+    ``Abs(x)`` is proposed, then ``Q.zero(Abs(x)) | Q.positive(Abs(x))``
+    will be found and passed to SAT solver because ``Q.nonnegative`` is
+    registered as a fact for ``Abs``.
+
+    Proposition is evaluated to ``True`` or ``False`` if the truth value can be
+    determined. If not, ``None`` is returned.
+
+    Parameters
+    ==========
+
+    proposition : Any boolean expression.
+        Proposition which will be evaluated to boolean value.
+
+    assumptions : Any boolean expression, optional.
+        Local assumptions to evaluate the *proposition*.
+
+    context : AssumptionsContext, optional.
+        Default assumptions to evaluate the *proposition*. By default,
+        this is ``sympy.assumptions.global_assumptions`` variable.
+
+    use_known_facts : bool, optional.
+        If ``True``, facts from ``sympy.assumptions.ask_generated``
+        module are passed to SAT solver as well.
+
+    iterations : int, optional.
+        Number of times that relevant facts are recursively extracted.
+        Default is infinite times until no new fact is found.
+
+    Returns
+    =======
+
+    ``True``, ``False``, or ``None``
+
+    Examples
+    ========
+
+    >>> from sympy import Abs, Q
+    >>> from sympy.assumptions.satask import satask
+    >>> from sympy.abc import x
+    >>> satask(Q.zero(Abs(x)), Q.zero(x))
+    True
+
+    """
+    props = CNF.from_prop(proposition)
+    _props = CNF.from_prop(~proposition)
+
+    assumptions = CNF.from_prop(assumptions)
+
+    context_cnf = CNF()
+    if context:
+        context_cnf = context_cnf.extend(context)
+
+    sat = get_all_relevant_facts(props, assumptions, context_cnf,
+        use_known_facts=use_known_facts, iterations=iterations)
+    sat.add_from_cnf(assumptions)
+    if context:
+        sat.add_from_cnf(context_cnf)
+
+    return check_satisfiability(props, _props, sat)
+
+
+def check_satisfiability(prop, _prop, factbase):
+    sat_true = factbase.copy()
+    sat_false = factbase.copy()
+    sat_true.add_from_cnf(prop)
+    sat_false.add_from_cnf(_prop)
+    can_be_true = satisfiable(sat_true)
+    can_be_false = satisfiable(sat_false)
+
+    if can_be_true and can_be_false:
+        return None
+
+    if can_be_true and not can_be_false:
+        return True
+
+    if not can_be_true and can_be_false:
+        return False
+
+    if not can_be_true and not can_be_false:
+        # TODO: Run additional checks to see which combination of the
+        # assumptions, global_assumptions, and relevant_facts are
+        # inconsistent.
+        raise ValueError("Inconsistent assumptions")
+
+
+def extract_predargs(proposition, assumptions=None, context=None):
+    """
+    Extract every expression in the argument of predicates from *proposition*,
+    *assumptions* and *context*.
+
+    Parameters
+    ==========
+
+    proposition : sympy.assumptions.cnf.CNF
+
+    assumptions : sympy.assumptions.cnf.CNF, optional.
+
+    context : sympy.assumptions.cnf.CNF, optional.
+        CNF generated from assumptions context.
+
+    Examples
+    ========
+
+    >>> from sympy import Q, Abs
+    >>> from sympy.assumptions.cnf import CNF
+    >>> from sympy.assumptions.satask import extract_predargs
+    >>> from sympy.abc import x, y
+    >>> props = CNF.from_prop(Q.zero(Abs(x*y)))
+    >>> assump = CNF.from_prop(Q.zero(x) & Q.zero(y))
+    >>> extract_predargs(props, assump)
+    {x, y, Abs(x*y)}
+
+    """
+    req_keys = find_symbols(proposition)
+    keys = proposition.all_predicates()
+    # XXX: We need this since True/False are not Basic
+    lkeys = set()
+    if assumptions:
+        lkeys |= assumptions.all_predicates()
+    if context:
+        lkeys |= context.all_predicates()
+
+    lkeys = lkeys - {S.true, S.false}
+    tmp_keys = None
+    while tmp_keys != set():
+        tmp = set()
+        for l in lkeys:
+            syms = find_symbols(l)
+            if (syms & req_keys) != set():
+                tmp |= syms
+        tmp_keys = tmp - req_keys
+        req_keys |= tmp_keys
+    keys |= {l for l in lkeys if find_symbols(l) & req_keys != set()}
+
+    exprs = set()
+    for key in keys:
+        if isinstance(key, AppliedPredicate):
+            exprs |= set(key.arguments)
+        else:
+            exprs.add(key)
+    return exprs
+
+def find_symbols(pred):
+    """
+    Find every :obj:`~.Symbol` in *pred*.
+
+    Parameters
+    ==========
+
+    pred : sympy.assumptions.cnf.CNF, or any Expr.
+
+    """
+    if isinstance(pred, CNF):
+        symbols = set()
+        for a in pred.all_predicates():
+            symbols |= find_symbols(a)
+        return symbols
+    return pred.atoms(Symbol)
+
+
+def get_relevant_clsfacts(exprs, relevant_facts=None):
+    """
+    Extract relevant facts from the items in *exprs*. Facts are defined in
+    ``assumptions.sathandlers`` module.
+
+    This function is recursively called by ``get_all_relevant_facts()``.
+
+    Parameters
+    ==========
+
+    exprs : set
+        Expressions whose relevant facts are searched.
+
+    relevant_facts : sympy.assumptions.cnf.CNF, optional.
+        Pre-discovered relevant facts.
+
+    Returns
+    =======
+
+    exprs : set
+        Candidates for next relevant fact searching.
+
+    relevant_facts : sympy.assumptions.cnf.CNF
+        Updated relevant facts.
+
+    Examples
+    ========
+
+    Here, we will see how facts relevant to ``Abs(x*y)`` are recursively
+    extracted. On the first run, set containing the expression is passed
+    without pre-discovered relevant facts. The result is a set containing
+    candidates for next run, and ``CNF()`` instance containing facts
+    which are relevant to ``Abs`` and its argument.
+
+    >>> from sympy import Abs
+    >>> from sympy.assumptions.satask import get_relevant_clsfacts
+    >>> from sympy.abc import x, y
+    >>> exprs = {Abs(x*y)}
+    >>> exprs, facts = get_relevant_clsfacts(exprs)
+    >>> exprs
+    {x*y}
+    >>> facts.clauses #doctest: +SKIP
+    {frozenset({Literal(Q.odd(Abs(x*y)), False), Literal(Q.odd(x*y), True)}),
+    frozenset({Literal(Q.zero(Abs(x*y)), False), Literal(Q.zero(x*y), True)}),
+    frozenset({Literal(Q.even(Abs(x*y)), False), Literal(Q.even(x*y), True)}),
+    frozenset({Literal(Q.zero(Abs(x*y)), True), Literal(Q.zero(x*y), False)}),
+    frozenset({Literal(Q.even(Abs(x*y)), False),
+                Literal(Q.odd(Abs(x*y)), False),
+                Literal(Q.odd(x*y), True)}),
+    frozenset({Literal(Q.even(Abs(x*y)), False),
+                Literal(Q.even(x*y), True),
+                Literal(Q.odd(Abs(x*y)), False)}),
+    frozenset({Literal(Q.positive(Abs(x*y)), False),
+                Literal(Q.zero(Abs(x*y)), False)})}
+
+    We pass the first run's results to the second run, and get the expressions
+    for next run and updated facts.
+
+    >>> exprs, facts = get_relevant_clsfacts(exprs, relevant_facts=facts)
+    >>> exprs
+    {x, y}
+
+    On final run, no more candidate is returned thus we know that all
+    relevant facts are successfully retrieved.
+
+    >>> exprs, facts = get_relevant_clsfacts(exprs, relevant_facts=facts)
+    >>> exprs
+    set()
+
+    """
+    if not relevant_facts:
+        relevant_facts = CNF()
+
+    newexprs = set()
+    for expr in exprs:
+        for fact in class_fact_registry(expr):
+            newfact = CNF.to_CNF(fact)
+            relevant_facts = relevant_facts._and(newfact)
+            for key in newfact.all_predicates():
+                if isinstance(key, AppliedPredicate):
+                    newexprs |= set(key.arguments)
+
+    return newexprs - exprs, relevant_facts
+
+
+def get_all_relevant_facts(proposition, assumptions, context,
+        use_known_facts=True, iterations=oo):
+    """
+    Extract all relevant facts from *proposition* and *assumptions*.
+
+    This function extracts the facts by recursively calling
+    ``get_relevant_clsfacts()``. Extracted facts are converted to
+    ``EncodedCNF`` and returned.
+
+    Parameters
+    ==========
+
+    proposition : sympy.assumptions.cnf.CNF
+        CNF generated from proposition expression.
+
+    assumptions : sympy.assumptions.cnf.CNF
+        CNF generated from assumption expression.
+
+    context : sympy.assumptions.cnf.CNF
+        CNF generated from assumptions context.
+
+    use_known_facts : bool, optional.
+        If ``True``, facts from ``sympy.assumptions.ask_generated``
+        module are encoded as well.
+
+    iterations : int, optional.
+        Number of times that relevant facts are recursively extracted.
+        Default is infinite times until no new fact is found.
+
+    Returns
+    =======
+
+    sympy.assumptions.cnf.EncodedCNF
+
+    Examples
+    ========
+
+    >>> from sympy import Q
+    >>> from sympy.assumptions.cnf import CNF
+    >>> from sympy.assumptions.satask import get_all_relevant_facts
+    >>> from sympy.abc import x, y
+    >>> props = CNF.from_prop(Q.nonzero(x*y))
+    >>> assump = CNF.from_prop(Q.nonzero(x))
+    >>> context = CNF.from_prop(Q.nonzero(y))
+    >>> get_all_relevant_facts(props, assump, context) #doctest: +SKIP
+    <sympy.assumptions.cnf.EncodedCNF at 0x7f09faa6ccd0>
+
+    """
+    # The relevant facts might introduce new keys, e.g., Q.zero(x*y) will
+    # introduce the keys Q.zero(x) and Q.zero(y), so we need to run it until
+    # we stop getting new things. Hopefully this strategy won't lead to an
+    # infinite loop in the future.
+    i = 0
+    relevant_facts = CNF()
+    all_exprs = set()
+    while True:
+        if i == 0:
+            exprs = extract_predargs(proposition, assumptions, context)
+        all_exprs |= exprs
+        exprs, relevant_facts = get_relevant_clsfacts(exprs, relevant_facts)
+        i += 1
+        if i >= iterations:
+            break
+        if not exprs:
+            break
+
+    if use_known_facts:
+        known_facts_CNF = CNF()
+
+        if any(expr.kind == MatrixKind(NumberKind) for expr in all_exprs):
+            known_facts_CNF.add_clauses(get_all_known_matrix_facts())
+        # check for undefinedKind since kind system isn't fully implemented
+        if any(((expr.kind == NumberKind) or (expr.kind == UndefinedKind)) for expr in all_exprs):
+            known_facts_CNF.add_clauses(get_all_known_number_facts())
+
+        kf_encoded = EncodedCNF()
+        kf_encoded.from_cnf(known_facts_CNF)
+
+        def translate_literal(lit, delta):
+            if lit > 0:
+                return lit + delta
+            else:
+                return lit - delta
+
+        def translate_data(data, delta):
+            return [{translate_literal(i, delta) for i in clause} for clause in data]
+        data = []
+        symbols = []
+        n_lit = len(kf_encoded.symbols)
+        for i, expr in enumerate(all_exprs):
+            symbols += [pred(expr) for pred in kf_encoded.symbols]
+            data += translate_data(kf_encoded.data, i * n_lit)
+
+        encoding = dict(list(zip(symbols, range(1, len(symbols)+1))))
+        ctx = EncodedCNF(data, encoding)
+    else:
+        ctx = EncodedCNF()
+
+    ctx.add_from_cnf(relevant_facts)
+
+    return ctx

.venv/lib/python3.13/site-packages/sympy/assumptions/sathandlers.py

@@ -0,0 +1,322 @@
+from collections import defaultdict
+
+from sympy.assumptions.ask import Q
+from sympy.core import (Add, Mul, Pow, Number, NumberSymbol, Symbol)
+from sympy.core.numbers import ImaginaryUnit
+from sympy.functions.elementary.complexes import Abs
+from sympy.logic.boolalg import (Equivalent, And, Or, Implies)
+from sympy.matrices.expressions import MatMul
+
+# APIs here may be subject to change
+
+
+### Helper functions ###
+
+def allargs(symbol, fact, expr):
+    """
+    Apply all arguments of the expression to the fact structure.
+
+    Parameters
+    ==========
+
+    symbol : Symbol
+        A placeholder symbol.
+
+    fact : Boolean
+        Resulting ``Boolean`` expression.
+
+    expr : Expr
+
+    Examples
+    ========
+
+    >>> from sympy import Q
+    >>> from sympy.assumptions.sathandlers import allargs
+    >>> from sympy.abc import x, y
+    >>> allargs(x, Q.negative(x) | Q.positive(x), x*y)
+    (Q.negative(x) | Q.positive(x)) & (Q.negative(y) | Q.positive(y))
+
+    """
+    return And(*[fact.subs(symbol, arg) for arg in expr.args])
+
+
+def anyarg(symbol, fact, expr):
+    """
+    Apply any argument of the expression to the fact structure.
+
+    Parameters
+    ==========
+
+    symbol : Symbol
+        A placeholder symbol.
+
+    fact : Boolean
+        Resulting ``Boolean`` expression.
+
+    expr : Expr
+
+    Examples
+    ========
+
+    >>> from sympy import Q
+    >>> from sympy.assumptions.sathandlers import anyarg
+    >>> from sympy.abc import x, y
+    >>> anyarg(x, Q.negative(x) & Q.positive(x), x*y)
+    (Q.negative(x) & Q.positive(x)) | (Q.negative(y) & Q.positive(y))
+
+    """
+    return Or(*[fact.subs(symbol, arg) for arg in expr.args])
+
+
+def exactlyonearg(symbol, fact, expr):
+    """
+    Apply exactly one argument of the expression to the fact structure.
+
+    Parameters
+    ==========
+
+    symbol : Symbol
+        A placeholder symbol.
+
+    fact : Boolean
+        Resulting ``Boolean`` expression.
+
+    expr : Expr
+
+    Examples
+    ========
+
+    >>> from sympy import Q
+    >>> from sympy.assumptions.sathandlers import exactlyonearg
+    >>> from sympy.abc import x, y
+    >>> exactlyonearg(x, Q.positive(x), x*y)
+    (Q.positive(x) & ~Q.positive(y)) | (Q.positive(y) & ~Q.positive(x))
+
+    """
+    pred_args = [fact.subs(symbol, arg) for arg in expr.args]
+    res = Or(*[And(pred_args[i], *[~lit for lit in pred_args[:i] +
+        pred_args[i+1:]]) for i in range(len(pred_args))])
+    return res
+
+
+### Fact registry ###
+
+class ClassFactRegistry:
+    """
+    Register handlers against classes.
+
+    Explanation
+    ===========
+
+    ``register`` method registers the handler function for a class. Here,
+    handler function should return a single fact. ``multiregister`` method
+    registers the handler function for multiple classes. Here, handler function
+    should return a container of multiple facts.
+
+    ``registry(expr)`` returns a set of facts for *expr*.
+
+    Examples
+    ========
+
+    Here, we register the facts for ``Abs``.
+
+    >>> from sympy import Abs, Equivalent, Q
+    >>> from sympy.assumptions.sathandlers import ClassFactRegistry
+    >>> reg = ClassFactRegistry()
+    >>> @reg.register(Abs)
+    ... def f1(expr):
+    ...     return Q.nonnegative(expr)
+    >>> @reg.register(Abs)
+    ... def f2(expr):
+    ...     arg = expr.args[0]
+    ...     return Equivalent(~Q.zero(arg), ~Q.zero(expr))
+
+    Calling the registry with expression returns the defined facts for the
+    expression.
+
+    >>> from sympy.abc import x
+    >>> reg(Abs(x))
+    {Q.nonnegative(Abs(x)), Equivalent(~Q.zero(x), ~Q.zero(Abs(x)))}
+
+    Multiple facts can be registered at once by ``multiregister`` method.
+
+    >>> reg2 = ClassFactRegistry()
+    >>> @reg2.multiregister(Abs)
+    ... def _(expr):
+    ...     arg = expr.args[0]
+    ...     return [Q.even(arg) >> Q.even(expr), Q.odd(arg) >> Q.odd(expr)]
+    >>> reg2(Abs(x))
+    {Implies(Q.even(x), Q.even(Abs(x))), Implies(Q.odd(x), Q.odd(Abs(x)))}
+
+    """
+    def __init__(self):
+        self.singlefacts = defaultdict(frozenset)
+        self.multifacts = defaultdict(frozenset)
+
+    def register(self, cls):
+        def _(func):
+            self.singlefacts[cls] |= {func}
+            return func
+        return _
+
+    def multiregister(self, *classes):
+        def _(func):
+            for cls in classes:
+                self.multifacts[cls] |= {func}
+            return func
+        return _
+
+    def __getitem__(self, key):
+        ret1 = self.singlefacts[key]
+        for k in self.singlefacts:
+            if issubclass(key, k):
+                ret1 |= self.singlefacts[k]
+
+        ret2 = self.multifacts[key]
+        for k in self.multifacts:
+            if issubclass(key, k):
+                ret2 |= self.multifacts[k]
+
+        return ret1, ret2
+
+    def __call__(self, expr):
+        ret = set()
+
+        handlers1, handlers2 = self[type(expr)]
+
+        ret.update(h(expr) for h in handlers1)
+        for h in handlers2:
+            ret.update(h(expr))
+        return ret
+
+class_fact_registry = ClassFactRegistry()
+
+
+
+### Class fact registration ###
+
+x = Symbol('x')
+
+## Abs ##
+
+@class_fact_registry.multiregister(Abs)
+def _(expr):
+    arg = expr.args[0]
+    return [Q.nonnegative(expr),
+            Equivalent(~Q.zero(arg), ~Q.zero(expr)),
+            Q.even(arg) >> Q.even(expr),
+            Q.odd(arg) >> Q.odd(expr),
+            Q.integer(arg) >> Q.integer(expr),
+            ]
+
+
+### Add ##
+
+@class_fact_registry.multiregister(Add)
+def _(expr):
+    return [allargs(x, Q.positive(x), expr) >> Q.positive(expr),
+            allargs(x, Q.negative(x), expr) >> Q.negative(expr),
+            allargs(x, Q.real(x), expr) >> Q.real(expr),
+            allargs(x, Q.rational(x), expr) >> Q.rational(expr),
+            allargs(x, Q.integer(x), expr) >> Q.integer(expr),
+            exactlyonearg(x, ~Q.integer(x), expr) >> ~Q.integer(expr),
+            ]
+
+@class_fact_registry.register(Add)
+def _(expr):
+    allargs_real = allargs(x, Q.real(x), expr)
+    onearg_irrational = exactlyonearg(x, Q.irrational(x), expr)
+    return Implies(allargs_real, Implies(onearg_irrational, Q.irrational(expr)))
+
+
+### Mul ###
+
+@class_fact_registry.multiregister(Mul)
+def _(expr):
+    return [Equivalent(Q.zero(expr), anyarg(x, Q.zero(x), expr)),
+            allargs(x, Q.positive(x), expr) >> Q.positive(expr),
+            allargs(x, Q.real(x), expr) >> Q.real(expr),
+            allargs(x, Q.rational(x), expr) >> Q.rational(expr),
+            allargs(x, Q.integer(x), expr) >> Q.integer(expr),
+            exactlyonearg(x, ~Q.rational(x), expr) >> ~Q.integer(expr),
+            allargs(x, Q.commutative(x), expr) >> Q.commutative(expr),
+            ]
+
+@class_fact_registry.register(Mul)
+def _(expr):
+    # Implicitly assumes Mul has more than one arg
+    # Would be allargs(x, Q.prime(x) | Q.composite(x)) except 1 is composite
+    # More advanced prime assumptions will require inequalities, as 1 provides
+    # a corner case.
+    allargs_prime = allargs(x, Q.prime(x), expr)
+    return Implies(allargs_prime, ~Q.prime(expr))
+
+@class_fact_registry.register(Mul)
+def _(expr):
+    # General Case: Odd number of imaginary args implies mul is imaginary(To be implemented)
+    allargs_imag_or_real = allargs(x, Q.imaginary(x) | Q.real(x), expr)
+    onearg_imaginary = exactlyonearg(x, Q.imaginary(x), expr)
+    return Implies(allargs_imag_or_real, Implies(onearg_imaginary, Q.imaginary(expr)))
+
+@class_fact_registry.register(Mul)
+def _(expr):
+    allargs_real = allargs(x, Q.real(x), expr)
+    onearg_irrational = exactlyonearg(x, Q.irrational(x), expr)
+    return Implies(allargs_real, Implies(onearg_irrational, Q.irrational(expr)))
+
+@class_fact_registry.register(Mul)
+def _(expr):
+    # Including the integer qualification means we don't need to add any facts
+    # for odd, since the assumptions already know that every integer is
+    # exactly one of even or odd.
+    allargs_integer = allargs(x, Q.integer(x), expr)
+    anyarg_even = anyarg(x, Q.even(x), expr)
+    return Implies(allargs_integer, Equivalent(anyarg_even, Q.even(expr)))
+
+
+### MatMul ###
+
+@class_fact_registry.register(MatMul)
+def _(expr):
+    allargs_square = allargs(x, Q.square(x), expr)
+    allargs_invertible = allargs(x, Q.invertible(x), expr)
+    return Implies(allargs_square, Equivalent(Q.invertible(expr), allargs_invertible))
+
+
+### Pow ###
+
+@class_fact_registry.multiregister(Pow)
+def _(expr):
+    base, exp = expr.base, expr.exp
+    return [
+        (Q.real(base) & Q.even(exp) & Q.nonnegative(exp)) >> Q.nonnegative(expr),
+        (Q.nonnegative(base) & Q.odd(exp) & Q.nonnegative(exp)) >> Q.nonnegative(expr),
+        (Q.nonpositive(base) & Q.odd(exp) & Q.nonnegative(exp)) >> Q.nonpositive(expr),
+        Equivalent(Q.zero(expr), Q.zero(base) & Q.positive(exp))
+    ]
+
+
+### Numbers ###
+
+_old_assump_getters = {
+    Q.positive: lambda o: o.is_positive,
+    Q.zero: lambda o: o.is_zero,
+    Q.negative: lambda o: o.is_negative,
+    Q.rational: lambda o: o.is_rational,
+    Q.irrational: lambda o: o.is_irrational,
+    Q.even: lambda o: o.is_even,
+    Q.odd: lambda o: o.is_odd,
+    Q.imaginary: lambda o: o.is_imaginary,
+    Q.prime: lambda o: o.is_prime,
+    Q.composite: lambda o: o.is_composite,
+}
+
+@class_fact_registry.multiregister(Number, NumberSymbol, ImaginaryUnit)
+def _(expr):
+    ret = []
+    for p, getter in _old_assump_getters.items():
+        pred = p(expr)
+        prop = getter(expr)
+        if prop is not None:
+            ret.append(Equivalent(pred, prop))
+    return ret

.venv/lib/python3.13/site-packages/sympy/assumptions/wrapper.py

@@ -0,0 +1,164 @@
+"""
+Functions and wrapper object to call assumption property and predicate
+query with same syntax.
+
+In SymPy, there are two assumption systems. Old assumption system is
+defined in sympy/core/assumptions, and it can be accessed by attribute
+such as ``x.is_even``. New assumption system is defined in
+sympy/assumptions, and it can be accessed by predicates such as
+``Q.even(x)``.
+
+Old assumption is fast, while new assumptions can freely take local facts.
+In general, old assumption is used in evaluation method and new assumption
+is used in refinement method.
+
+In most cases, both evaluation and refinement follow the same process, and
+the only difference is which assumption system is used. This module provides
+``is_[...]()`` functions and ``AssumptionsWrapper()`` class which allows
+using two systems with same syntax so that parallel code implementation can be
+avoided.
+
+Examples
+========
+
+For multiple use, use ``AssumptionsWrapper()``.
+
+>>> from sympy import Q, Symbol
+>>> from sympy.assumptions.wrapper import AssumptionsWrapper
+>>> x = Symbol('x')
+>>> _x = AssumptionsWrapper(x, Q.even(x))
+>>> _x.is_integer
+True
+>>> _x.is_odd
+False
+
+For single use, use ``is_[...]()`` functions.
+
+>>> from sympy.assumptions.wrapper import is_infinite
+>>> a = Symbol('a')
+>>> print(is_infinite(a))
+None
+>>> is_infinite(a, Q.finite(a))
+False
+
+"""
+
+from sympy.assumptions import ask, Q
+from sympy.core.basic import Basic
+from sympy.core.sympify import _sympify
+
+
+def make_eval_method(fact):
+    def getit(self):
+        pred = getattr(Q, fact)
+        ret = ask(pred(self.expr), self.assumptions)
+        return ret
+    return getit
+
+
+# we subclass Basic to use the fact deduction and caching
+class AssumptionsWrapper(Basic):
+    """
+    Wrapper over ``Basic`` instances to call predicate query by
+    ``.is_[...]`` property
+
+    Parameters
+    ==========
+
+    expr : Basic
+
+    assumptions : Boolean, optional
+
+    Examples
+    ========
+
+    >>> from sympy import Q, Symbol
+    >>> from sympy.assumptions.wrapper import AssumptionsWrapper
+    >>> x = Symbol('x', even=True)
+    >>> AssumptionsWrapper(x).is_integer
+    True
+    >>> y = Symbol('y')
+    >>> AssumptionsWrapper(y, Q.even(y)).is_integer
+    True
+
+    With ``AssumptionsWrapper``, both evaluation and refinement can be supported
+    by single implementation.
+
+    >>> from sympy import Function
+    >>> class MyAbs(Function):
+    ...     @classmethod
+    ...     def eval(cls, x, assumptions=True):
+    ...         _x = AssumptionsWrapper(x, assumptions)
+    ...         if _x.is_nonnegative:
+    ...             return x
+    ...         if _x.is_negative:
+    ...             return -x
+    ...     def _eval_refine(self, assumptions):
+    ...         return MyAbs.eval(self.args[0], assumptions)
+    >>> MyAbs(x)
+    MyAbs(x)
+    >>> MyAbs(x).refine(Q.positive(x))
+    x
+    >>> MyAbs(Symbol('y', negative=True))
+    -y
+
+    """
+    def __new__(cls, expr, assumptions=None):
+        if assumptions is None:
+            return expr
+        obj = super().__new__(cls, expr, _sympify(assumptions))
+        obj.expr = expr
+        obj.assumptions = assumptions
+        return obj
+
+    _eval_is_algebraic = make_eval_method("algebraic")
+    _eval_is_antihermitian = make_eval_method("antihermitian")
+    _eval_is_commutative = make_eval_method("commutative")
+    _eval_is_complex = make_eval_method("complex")
+    _eval_is_composite = make_eval_method("composite")
+    _eval_is_even = make_eval_method("even")
+    _eval_is_extended_negative = make_eval_method("extended_negative")
+    _eval_is_extended_nonnegative = make_eval_method("extended_nonnegative")
+    _eval_is_extended_nonpositive = make_eval_method("extended_nonpositive")
+    _eval_is_extended_nonzero = make_eval_method("extended_nonzero")
+    _eval_is_extended_positive = make_eval_method("extended_positive")
+    _eval_is_extended_real = make_eval_method("extended_real")
+    _eval_is_finite = make_eval_method("finite")
+    _eval_is_hermitian = make_eval_method("hermitian")
+    _eval_is_imaginary = make_eval_method("imaginary")
+    _eval_is_infinite = make_eval_method("infinite")
+    _eval_is_integer = make_eval_method("integer")
+    _eval_is_irrational = make_eval_method("irrational")
+    _eval_is_negative = make_eval_method("negative")
+    _eval_is_noninteger = make_eval_method("noninteger")
+    _eval_is_nonnegative = make_eval_method("nonnegative")
+    _eval_is_nonpositive = make_eval_method("nonpositive")
+    _eval_is_nonzero = make_eval_method("nonzero")
+    _eval_is_odd = make_eval_method("odd")
+    _eval_is_polar = make_eval_method("polar")
+    _eval_is_positive = make_eval_method("positive")
+    _eval_is_prime = make_eval_method("prime")
+    _eval_is_rational = make_eval_method("rational")
+    _eval_is_real = make_eval_method("real")
+    _eval_is_transcendental = make_eval_method("transcendental")
+    _eval_is_zero = make_eval_method("zero")
+
+
+# one shot functions which are faster than AssumptionsWrapper
+
+def is_infinite(obj, assumptions=None):
+    if assumptions is None:
+        return obj.is_infinite
+    return ask(Q.infinite(obj), assumptions)
+
+
+def is_extended_real(obj, assumptions=None):
+    if assumptions is None:
+        return obj.is_extended_real
+    return ask(Q.extended_real(obj), assumptions)
+
+
+def is_extended_nonnegative(obj, assumptions=None):
+    if assumptions is None:
+        return obj.is_extended_nonnegative
+    return ask(Q.extended_nonnegative(obj), assumptions)

.venv/lib/python3.13/site-packages/sympy/benchmarks/bench_discrete_log.py

@@ -0,0 +1,83 @@
+import sys
+from time import time
+from sympy.ntheory.residue_ntheory import (discrete_log,
+        _discrete_log_trial_mul, _discrete_log_shanks_steps,
+        _discrete_log_pollard_rho, _discrete_log_pohlig_hellman)
+
+
+# Cyclic group (Z/pZ)* with p prime, order p - 1 and generator g
+data_set_1 = [
+        # p, p - 1, g
+        [191, 190, 19],
+        [46639, 46638, 6],
+        [14789363, 14789362, 2],
+        [4254225211, 4254225210, 2],
+        [432751500361, 432751500360, 7],
+        [158505390797053, 158505390797052, 2],
+        [6575202655312007, 6575202655312006, 5],
+        [8430573471995353769, 8430573471995353768, 3],
+        [3938471339744997827267, 3938471339744997827266, 2],
+        [875260951364705563393093, 875260951364705563393092, 5],
+    ]
+
+
+# Cyclic sub-groups of (Z/nZ)* with prime order p and generator g
+# (n, p are primes and n = 2 * p + 1)
+data_set_2 = [
+        # n, p, g
+        [227, 113, 3],
+        [2447, 1223, 2],
+        [24527, 12263, 2],
+        [245639, 122819, 2],
+        [2456747, 1228373, 3],
+        [24567899, 12283949, 3],
+        [245679023, 122839511, 2],
+        [2456791307, 1228395653, 3],
+        [24567913439, 12283956719, 2],
+        [245679135407, 122839567703, 2],
+        [2456791354763, 1228395677381, 3],
+        [24567913550903, 12283956775451, 2],
+        [245679135509519, 122839567754759, 2],
+    ]
+
+
+# Cyclic sub-groups of (Z/nZ)* with smooth order o and generator g
+data_set_3 = [
+        # n, o, g
+        [2**118, 2**116, 3],
+    ]
+
+
+def bench_discrete_log(data_set, algo=None):
+    if algo is None:
+        f = discrete_log
+    elif algo == 'trial':
+        f = _discrete_log_trial_mul
+    elif algo == 'shanks':
+        f = _discrete_log_shanks_steps
+    elif algo == 'rho':
+        f = _discrete_log_pollard_rho
+    elif algo == 'ph':
+        f = _discrete_log_pohlig_hellman
+    else:
+        raise ValueError("Argument 'algo' should be one"
+                " of ('trial', 'shanks', 'rho' or 'ph')")
+
+    for i, data in enumerate(data_set):
+        for j, (n, p, g) in enumerate(data):
+            t = time()
+            l = f(n, pow(g, p - 1, n), g, p)
+            t = time() - t
+            print('[%02d-%03d] %15.10f' % (i, j, t))
+            assert l == p - 1
+
+
+if __name__ == '__main__':
+    algo = sys.argv[1] \
+            if len(sys.argv) > 1 else None
+    data_set = [
+            data_set_1,
+            data_set_2,
+            data_set_3,
+        ]
+    bench_discrete_log(data_set, algo)

.venv/lib/python3.13/site-packages/sympy/benchmarks/bench_meijerint.py

@@ -0,0 +1,261 @@
+# conceal the implicit import from the code quality tester
+from sympy.core.numbers import (oo, pi)
+from sympy.core.symbol import (Symbol, symbols)
+from sympy.functions.elementary.exponential import exp
+from sympy.functions.elementary.miscellaneous import sqrt
+from sympy.functions.special.bessel import besseli
+from sympy.functions.special.gamma_functions import gamma
+from sympy.integrals.integrals import integrate
+from sympy.integrals.transforms import (mellin_transform,
+    inverse_fourier_transform, inverse_mellin_transform,
+    laplace_transform, inverse_laplace_transform, fourier_transform)
+
+LT = laplace_transform
+FT = fourier_transform
+MT = mellin_transform
+IFT = inverse_fourier_transform
+ILT = inverse_laplace_transform
+IMT = inverse_mellin_transform
+
+from sympy.abc import x, y
+nu, beta, rho = symbols('nu beta rho')
+
+apos, bpos, cpos, dpos, posk, p = symbols('a b c d k p', positive=True)
+k = Symbol('k', real=True)
+negk = Symbol('k', negative=True)
+
+mu1, mu2 = symbols('mu1 mu2', real=True, nonzero=True, finite=True)
+sigma1, sigma2 = symbols('sigma1 sigma2', real=True, nonzero=True,
+                         finite=True, positive=True)
+rate = Symbol('lambda', positive=True)
+
+
+def normal(x, mu, sigma):
+    return 1/sqrt(2*pi*sigma**2)*exp(-(x - mu)**2/2/sigma**2)
+
+
+def exponential(x, rate):
+    return rate*exp(-rate*x)
+alpha, beta = symbols('alpha beta', positive=True)
+betadist = x**(alpha - 1)*(1 + x)**(-alpha - beta)*gamma(alpha + beta) \
+    /gamma(alpha)/gamma(beta)
+kint = Symbol('k', integer=True, positive=True)
+chi = 2**(1 - kint/2)*x**(kint - 1)*exp(-x**2/2)/gamma(kint/2)
+chisquared = 2**(-k/2)/gamma(k/2)*x**(k/2 - 1)*exp(-x/2)
+dagum = apos*p/x*(x/bpos)**(apos*p)/(1 + x**apos/bpos**apos)**(p + 1)
+d1, d2 = symbols('d1 d2', positive=True)
+f = sqrt(((d1*x)**d1 * d2**d2)/(d1*x + d2)**(d1 + d2))/x \
+    /gamma(d1/2)/gamma(d2/2)*gamma((d1 + d2)/2)
+nupos, sigmapos = symbols('nu sigma', positive=True)
+rice = x/sigmapos**2*exp(-(x**2 + nupos**2)/2/sigmapos**2)*besseli(0, x*
+                         nupos/sigmapos**2)
+mu = Symbol('mu', real=True)
+laplace = exp(-abs(x - mu)/bpos)/2/bpos
+
+u = Symbol('u', polar=True)
+tpos = Symbol('t', positive=True)
+
+
+def E(expr):
+    integrate(expr*exponential(x, rate)*normal(y, mu1, sigma1),
+                     (x, 0, oo), (y, -oo, oo), meijerg=True)
+    integrate(expr*exponential(x, rate)*normal(y, mu1, sigma1),
+                     (y, -oo, oo), (x, 0, oo), meijerg=True)
+
+bench = [
+    'MT(x**nu*Heaviside(x - 1), x, s)',
+    'MT(x**nu*Heaviside(1 - x), x, s)',
+    'MT((1-x)**(beta - 1)*Heaviside(1-x), x, s)',
+    'MT((x-1)**(beta - 1)*Heaviside(x-1), x, s)',
+    'MT((1+x)**(-rho), x, s)',
+    'MT(abs(1-x)**(-rho), x, s)',
+    'MT((1-x)**(beta-1)*Heaviside(1-x) + a*(x-1)**(beta-1)*Heaviside(x-1), x, s)',
+    'MT((x**a-b**a)/(x-b), x, s)',
+    'MT((x**a-bpos**a)/(x-bpos), x, s)',
+    'MT(exp(-x), x, s)',
+    'MT(exp(-1/x), x, s)',
+    'MT(log(x)**4*Heaviside(1-x), x, s)',
+    'MT(log(x)**3*Heaviside(x-1), x, s)',
+    'MT(log(x + 1), x, s)',
+    'MT(log(1/x + 1), x, s)',
+    'MT(log(abs(1 - x)), x, s)',
+    'MT(log(abs(1 - 1/x)), x, s)',
+    'MT(log(x)/(x+1), x, s)',
+    'MT(log(x)**2/(x+1), x, s)',
+    'MT(log(x)/(x+1)**2, x, s)',
+    'MT(erf(sqrt(x)), x, s)',
+
+    'MT(besselj(a, 2*sqrt(x)), x, s)',
+    'MT(sin(sqrt(x))*besselj(a, sqrt(x)), x, s)',
+    'MT(cos(sqrt(x))*besselj(a, sqrt(x)), x, s)',
+    'MT(besselj(a, sqrt(x))**2, x, s)',
+    'MT(besselj(a, sqrt(x))*besselj(-a, sqrt(x)), x, s)',
+    'MT(besselj(a - 1, sqrt(x))*besselj(a, sqrt(x)), x, s)',
+    'MT(besselj(a, sqrt(x))*besselj(b, sqrt(x)), x, s)',
+    'MT(besselj(a, sqrt(x))**2 + besselj(-a, sqrt(x))**2, x, s)',
+    'MT(bessely(a, 2*sqrt(x)), x, s)',
+    'MT(sin(sqrt(x))*bessely(a, sqrt(x)), x, s)',
+    'MT(cos(sqrt(x))*bessely(a, sqrt(x)), x, s)',
+    'MT(besselj(a, sqrt(x))*bessely(a, sqrt(x)), x, s)',
+    'MT(besselj(a, sqrt(x))*bessely(b, sqrt(x)), x, s)',
+    'MT(bessely(a, sqrt(x))**2, x, s)',
+
+    'MT(besselk(a, 2*sqrt(x)), x, s)',
+    'MT(besselj(a, 2*sqrt(2*sqrt(x)))*besselk(a, 2*sqrt(2*sqrt(x))), x, s)',
+    'MT(besseli(a, sqrt(x))*besselk(a, sqrt(x)), x, s)',
+    'MT(besseli(b, sqrt(x))*besselk(a, sqrt(x)), x, s)',
+    'MT(exp(-x/2)*besselk(a, x/2), x, s)',
+
+    # later: ILT, IMT
+
+    'LT((t-apos)**bpos*exp(-cpos*(t-apos))*Heaviside(t-apos), t, s)',
+    'LT(t**apos, t, s)',
+    'LT(Heaviside(t), t, s)',
+    'LT(Heaviside(t - apos), t, s)',
+    'LT(1 - exp(-apos*t), t, s)',
+    'LT((exp(2*t)-1)*exp(-bpos - t)*Heaviside(t)/2, t, s, noconds=True)',
+    'LT(exp(t), t, s)',
+    'LT(exp(2*t), t, s)',
+    'LT(exp(apos*t), t, s)',
+    'LT(log(t/apos), t, s)',
+    'LT(erf(t), t, s)',
+    'LT(sin(apos*t), t, s)',
+    'LT(cos(apos*t), t, s)',
+    'LT(exp(-apos*t)*sin(bpos*t), t, s)',
+    'LT(exp(-apos*t)*cos(bpos*t), t, s)',
+    'LT(besselj(0, t), t, s, noconds=True)',
+    'LT(besselj(1, t), t, s, noconds=True)',
+
+    'FT(Heaviside(1 - abs(2*apos*x)), x, k)',
+    'FT(Heaviside(1-abs(apos*x))*(1-abs(apos*x)), x, k)',
+    'FT(exp(-apos*x)*Heaviside(x), x, k)',
+    'IFT(1/(apos + 2*pi*I*x), x, posk, noconds=False)',
+    'IFT(1/(apos + 2*pi*I*x), x, -posk, noconds=False)',
+    'IFT(1/(apos + 2*pi*I*x), x, negk)',
+    'FT(x*exp(-apos*x)*Heaviside(x), x, k)',
+    'FT(exp(-apos*x)*sin(bpos*x)*Heaviside(x), x, k)',
+    'FT(exp(-apos*x**2), x, k)',
+    'IFT(sqrt(pi/apos)*exp(-(pi*k)**2/apos), k, x)',
+    'FT(exp(-apos*abs(x)), x, k)',
+
+    'integrate(normal(x, mu1, sigma1), (x, -oo, oo), meijerg=True)',
+    'integrate(x*normal(x, mu1, sigma1), (x, -oo, oo), meijerg=True)',
+    'integrate(x**2*normal(x, mu1, sigma1), (x, -oo, oo), meijerg=True)',
+    'integrate(x**3*normal(x, mu1, sigma1), (x, -oo, oo), meijerg=True)',
+    'integrate(normal(x, mu1, sigma1)*normal(y, mu2, sigma2),'
+    '          (x, -oo, oo), (y, -oo, oo), meijerg=True)',
+    'integrate(x*normal(x, mu1, sigma1)*normal(y, mu2, sigma2),'
+    '          (x, -oo, oo), (y, -oo, oo), meijerg=True)',
+    'integrate(y*normal(x, mu1, sigma1)*normal(y, mu2, sigma2),'
+    '          (x, -oo, oo), (y, -oo, oo), meijerg=True)',
+    'integrate(x*y*normal(x, mu1, sigma1)*normal(y, mu2, sigma2),'
+    '          (x, -oo, oo), (y, -oo, oo), meijerg=True)',
+    'integrate((x+y+1)*normal(x, mu1, sigma1)*normal(y, mu2, sigma2),'
+    '          (x, -oo, oo), (y, -oo, oo), meijerg=True)',
+    'integrate((x+y-1)*normal(x, mu1, sigma1)*normal(y, mu2, sigma2),'
+    '                   (x, -oo, oo), (y, -oo, oo), meijerg=True)',
+    'integrate(x**2*normal(x, mu1, sigma1)*normal(y, mu2, sigma2),'
+    '                (x, -oo, oo), (y, -oo, oo), meijerg=True)',
+    'integrate(y**2*normal(x, mu1, sigma1)*normal(y, mu2, sigma2),'
+    '          (x, -oo, oo), (y, -oo, oo), meijerg=True)',
+    'integrate(exponential(x, rate), (x, 0, oo), meijerg=True)',
+    'integrate(x*exponential(x, rate), (x, 0, oo), meijerg=True)',
+    'integrate(x**2*exponential(x, rate), (x, 0, oo), meijerg=True)',
+    'E(1)',
+    'E(x*y)',
+    'E(x*y**2)',
+    'E((x+y+1)**2)',
+    'E(x+y+1)',
+    'E((x+y-1)**2)',
+    'integrate(betadist, (x, 0, oo), meijerg=True)',
+    'integrate(x*betadist, (x, 0, oo), meijerg=True)',
+    'integrate(x**2*betadist, (x, 0, oo), meijerg=True)',
+    'integrate(chi, (x, 0, oo), meijerg=True)',
+    'integrate(x*chi, (x, 0, oo), meijerg=True)',
+    'integrate(x**2*chi, (x, 0, oo), meijerg=True)',
+    'integrate(chisquared, (x, 0, oo), meijerg=True)',
+    'integrate(x*chisquared, (x, 0, oo), meijerg=True)',
+    'integrate(x**2*chisquared, (x, 0, oo), meijerg=True)',
+    'integrate(((x-k)/sqrt(2*k))**3*chisquared, (x, 0, oo), meijerg=True)',
+    'integrate(dagum, (x, 0, oo), meijerg=True)',
+    'integrate(x*dagum, (x, 0, oo), meijerg=True)',
+    'integrate(x**2*dagum, (x, 0, oo), meijerg=True)',
+    'integrate(f, (x, 0, oo), meijerg=True)',
+    'integrate(x*f, (x, 0, oo), meijerg=True)',
+    'integrate(x**2*f, (x, 0, oo), meijerg=True)',
+    'integrate(rice, (x, 0, oo), meijerg=True)',
+    'integrate(laplace, (x, -oo, oo), meijerg=True)',
+    'integrate(x*laplace, (x, -oo, oo), meijerg=True)',
+    'integrate(x**2*laplace, (x, -oo, oo), meijerg=True)',
+    'integrate(log(x) * x**(k-1) * exp(-x) / gamma(k), (x, 0, oo))',
+
+    'integrate(sin(z*x)*(x**2-1)**(-(y+S(1)/2)), (x, 1, oo), meijerg=True)',
+    'integrate(besselj(0,x)*besselj(1,x)*exp(-x**2), (x, 0, oo), meijerg=True)',
+    'integrate(besselj(0,x)*besselj(1,x)*besselk(0,x), (x, 0, oo), meijerg=True)',
+    'integrate(besselj(0,x)*besselj(1,x)*exp(-x**2), (x, 0, oo), meijerg=True)',
+    'integrate(besselj(a,x)*besselj(b,x)/x, (x,0,oo), meijerg=True)',
+
+    'hyperexpand(meijerg((-s - a/2 + 1, -s + a/2 + 1), (-a/2 - S(1)/2, -s + a/2 + S(3)/2), (a/2, -a/2), (-a/2 - S(1)/2, -s + a/2 + S(3)/2), 1))',
+    "gammasimp(S('2**(2*s)*(-pi*gamma(-a + 1)*gamma(a + 1)*gamma(-a - s + 1)*gamma(-a + s - 1/2)*gamma(a - s + 3/2)*gamma(a + s + 1)/(a*(a + s)) - gamma(-a - 1/2)*gamma(-a + 1)*gamma(a + 1)*gamma(a + 3/2)*gamma(-s + 3/2)*gamma(s - 1/2)*gamma(-a + s + 1)*gamma(a - s + 1)/(a*(-a + s)))*gamma(-2*s + 1)*gamma(s + 1)/(pi*s*gamma(-a - 1/2)*gamma(a + 3/2)*gamma(-s + 1)*gamma(-s + 3/2)*gamma(s - 1/2)*gamma(-a - s + 1)*gamma(-a + s - 1/2)*gamma(a - s + 1)*gamma(a - s + 3/2))'))",
+
+    'mellin_transform(E1(x), x, s)',
+    'inverse_mellin_transform(gamma(s)/s, s, x, (0, oo))',
+    'mellin_transform(expint(a, x), x, s)',
+    'mellin_transform(Si(x), x, s)',
+    'inverse_mellin_transform(-2**s*sqrt(pi)*gamma((s + 1)/2)/(2*s*gamma(-s/2 + 1)), s, x, (-1, 0))',
+    'mellin_transform(Ci(sqrt(x)), x, s)',
+    'inverse_mellin_transform(-4**s*sqrt(pi)*gamma(s)/(2*s*gamma(-s + S(1)/2)),s, u, (0, 1))',
+    'laplace_transform(Ci(x), x, s)',
+    'laplace_transform(expint(a, x), x, s)',
+    'laplace_transform(expint(1, x), x, s)',
+    'laplace_transform(expint(2, x), x, s)',
+    'inverse_laplace_transform(-log(1 + s**2)/2/s, s, u)',
+    'inverse_laplace_transform(log(s + 1)/s, s, x)',
+    'inverse_laplace_transform((s - log(s + 1))/s**2, s, x)',
+    'laplace_transform(Chi(x), x, s)',
+    'laplace_transform(Shi(x), x, s)',
+
+    'integrate(exp(-z*x)/x, (x, 1, oo), meijerg=True, conds="none")',
+    'integrate(exp(-z*x)/x**2, (x, 1, oo), meijerg=True, conds="none")',
+    'integrate(exp(-z*x)/x**3, (x, 1, oo), meijerg=True,conds="none")',
+    'integrate(-cos(x)/x, (x, tpos, oo), meijerg=True)',
+    'integrate(-sin(x)/x, (x, tpos, oo), meijerg=True)',
+    'integrate(sin(x)/x, (x, 0, z), meijerg=True)',
+    'integrate(sinh(x)/x, (x, 0, z), meijerg=True)',
+    'integrate(exp(-x)/x, x, meijerg=True)',
+    'integrate(exp(-x)/x**2, x, meijerg=True)',
+    'integrate(cos(u)/u, u, meijerg=True)',
+    'integrate(cosh(u)/u, u, meijerg=True)',
+    'integrate(expint(1, x), x, meijerg=True)',
+    'integrate(expint(2, x), x, meijerg=True)',
+    'integrate(Si(x), x, meijerg=True)',
+    'integrate(Ci(u), u, meijerg=True)',
+    'integrate(Shi(x), x, meijerg=True)',
+    'integrate(Chi(u), u, meijerg=True)',
+    'integrate(Si(x)*exp(-x), (x, 0, oo), meijerg=True)',
+    'integrate(expint(1, x)*sin(x), (x, 0, oo), meijerg=True)'
+]
+
+from time import time
+from sympy.core.cache import clear_cache
+import sys
+
+timings = []
+
+if __name__ == '__main__':
+    for n, string in enumerate(bench):
+        clear_cache()
+        _t = time()
+        exec(string)
+        _t = time() - _t
+        timings += [(_t, string)]
+        sys.stdout.write('.')
+        sys.stdout.flush()
+        if n % (len(bench) // 10) == 0:
+            sys.stdout.write('%s' % (10*n // len(bench)))
+    print()
+
+    timings.sort(key=lambda x: -x[0])
+
+    for ti, string in timings:
+        print('%.2fs %s' % (ti, string))

.venv/lib/python3.13/site-packages/sympy/benchmarks/bench_symbench.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python
+from sympy.core.random import random
+from sympy.core.numbers import (I, Integer, pi)
+from sympy.core.symbol import Symbol
+from sympy.core.sympify import sympify
+from sympy.functions.elementary.miscellaneous import sqrt
+from sympy.functions.elementary.trigonometric import sin
+from sympy.polys.polytools import factor
+from sympy.simplify.simplify import simplify
+from sympy.abc import x, y, z
+from timeit import default_timer as clock
+
+
+def bench_R1():
+    "real(f(f(f(f(f(f(f(f(f(f(i/2)))))))))))"
+    def f(z):
+        return sqrt(Integer(1)/3)*z**2 + I/3
+    f(f(f(f(f(f(f(f(f(f(I/2)))))))))).as_real_imag()[0]
+
+
+def bench_R2():
+    "Hermite polynomial hermite(15, y)"
+    def hermite(n, y):
+        if n == 1:
+            return 2*y
+        if n == 0:
+            return 1
+        return (2*y*hermite(n - 1, y) - 2*(n - 1)*hermite(n - 2, y)).expand()
+
+    hermite(15, y)
+
+
+def bench_R3():
+    "a = [bool(f==f) for _ in range(10)]"
+    f = x + y + z
+    [bool(f == f) for _ in range(10)]
+
+
+def bench_R4():
+    # we don't have Tuples
+    pass
+
+
+def bench_R5():
+    "blowup(L, 8); L=uniq(L)"
+    def blowup(L, n):
+        for i in range(n):
+            L.append( (L[i] + L[i + 1]) * L[i + 2] )
+
+    def uniq(x):
+        v = set(x)
+        return v
+    L = [x, y, z]
+    blowup(L, 8)
+    L = uniq(L)
+
+
+def bench_R6():
+    "sum(simplify((x+sin(i))/x+(x-sin(i))/x) for i in range(100))"
+    sum(simplify((x + sin(i))/x + (x - sin(i))/x) for i in range(100))
+
+
+def bench_R7():
+    "[f.subs(x, random()) for _ in range(10**4)]"
+    f = x**24 + 34*x**12 + 45*x**3 + 9*x**18 + 34*x**10 + 32*x**21
+    [f.subs(x, random()) for _ in range(10**4)]
+
+
+def bench_R8():
+    "right(x^2,0,5,10^4)"
+    def right(f, a, b, n):
+        a = sympify(a)
+        b = sympify(b)
+        n = sympify(n)
+        x = f.atoms(Symbol).pop()
+        Deltax = (b - a)/n
+        c = a
+        est = 0
+        for i in range(n):
+            c += Deltax
+            est += f.subs(x, c)
+        return est*Deltax
+
+    right(x**2, 0, 5, 10**4)
+
+
+def _bench_R9():
+    "factor(x^20 - pi^5*y^20)"
+    factor(x**20 - pi**5*y**20)
+
+
+def bench_R10():
+    "v = [-pi,-pi+1/10..,pi]"
+    def srange(min, max, step):
+        v = [min]
+        while (max - v[-1]).evalf() > 0:
+            v.append(v[-1] + step)
+        return v[:-1]
+    srange(-pi, pi, sympify(1)/10)
+
+
+def bench_R11():
+    "a = [random() + random()*I for w in [0..1000]]"
+    [random() + random()*I for w in range(1000)]
+
+
+def bench_S1():
+    "e=(x+y+z+1)**7;f=e*(e+1);f.expand()"
+    e = (x + y + z + 1)**7
+    f = e*(e + 1)
+    f.expand()
+
+
+if __name__ == '__main__':
+    benchmarks = [
+        bench_R1,
+        bench_R2,
+        bench_R3,
+        bench_R5,
+        bench_R6,
+        bench_R7,
+        bench_R8,
+        #_bench_R9,
+        bench_R10,
+        bench_R11,
+        #bench_S1,
+    ]
+
+    report = []
+    for b in benchmarks:
+        t = clock()
+        b()
+        t = clock() - t
+        print("%s%65s: %f" % (b.__name__, b.__doc__, t))

.venv/lib/python3.13/site-packages/sympy/codegen/__init__.py

@@ -0,0 +1,24 @@
+""" The ``sympy.codegen`` module contains classes and functions for building
+abstract syntax trees of algorithms. These trees may then be printed by the
+code-printers in ``sympy.printing``.
+
+There are several submodules available:
+- ``sympy.codegen.ast``: AST nodes useful across multiple languages.
+- ``sympy.codegen.cnodes``: AST nodes useful for the C family of languages.
+- ``sympy.codegen.fnodes``: AST nodes useful for Fortran.
+- ``sympy.codegen.cfunctions``: functions specific to C (C99 math functions)
+- ``sympy.codegen.ffunctions``: functions specific to Fortran (e.g. ``kind``).
+
+
+
+"""
+from .ast import (
+    Assignment, aug_assign, CodeBlock, For, Attribute, Variable, Declaration,
+    While, Scope, Print, FunctionPrototype, FunctionDefinition, FunctionCall
+)
+
+__all__ = [
+    'Assignment', 'aug_assign', 'CodeBlock', 'For', 'Attribute', 'Variable',
+    'Declaration', 'While', 'Scope', 'Print', 'FunctionPrototype',
+    'FunctionDefinition', 'FunctionCall',
+]

.venv/lib/python3.13/site-packages/sympy/codegen/abstract_nodes.py

@@ -0,0 +1,18 @@
+"""This module provides containers for python objects that are valid
+printing targets but are not a subclass of SymPy's Printable.
+"""
+
+
+from sympy.core.containers import Tuple
+
+
+class List(Tuple):
+    """Represents a (frozen) (Python) list (for code printing purposes)."""
+    def __eq__(self, other):
+        if isinstance(other, list):
+            return self == List(*other)
+        else:
+            return self.args == other
+
+    def __hash__(self):
+        return super().__hash__()

.venv/lib/python3.13/site-packages/sympy/codegen/algorithms.py

@@ -0,0 +1,180 @@
+from sympy.core.containers import Tuple
+from sympy.core.numbers import oo
+from sympy.core.relational import (Gt, Lt)
+from sympy.core.symbol import (Dummy, Symbol)
+from sympy.functions.elementary.complexes import Abs
+from sympy.functions.elementary.miscellaneous import Min, Max
+from sympy.logic.boolalg import And
+from sympy.codegen.ast import (
+    Assignment, AddAugmentedAssignment, break_, CodeBlock, Declaration, FunctionDefinition,
+    Print, Return, Scope, While, Variable, Pointer, real
+)
+from sympy.codegen.cfunctions import isnan
+
+""" This module collects functions for constructing ASTs representing algorithms. """
+
+def newtons_method(expr, wrt, atol=1e-12, delta=None, *, rtol=4e-16, debug=False,
+                   itermax=None, counter=None, delta_fn=lambda e, x: -e/e.diff(x),
+                   cse=False, handle_nan=None,
+                   bounds=None):
+    """ Generates an AST for Newton-Raphson method (a root-finding algorithm).
+
+    Explanation
+    ===========
+
+    Returns an abstract syntax tree (AST) based on ``sympy.codegen.ast`` for Netwon's
+    method of root-finding.
+
+    Parameters
+    ==========
+
+    expr : expression
+    wrt : Symbol
+        With respect to, i.e. what is the variable.
+    atol : number or expression
+        Absolute tolerance (stopping criterion)
+    rtol : number or expression
+        Relative tolerance (stopping criterion)
+    delta : Symbol
+        Will be a ``Dummy`` if ``None``.
+    debug : bool
+        Whether to print convergence information during iterations
+    itermax : number or expr
+        Maximum number of iterations.
+    counter : Symbol
+        Will be a ``Dummy`` if ``None``.
+    delta_fn: Callable[[Expr, Symbol], Expr]
+        computes the step, default is newtons method. For e.g. Halley's method
+        use delta_fn=lambda e, x: -2*e*e.diff(x)/(2*e.diff(x)**2 - e*e.diff(x, 2))
+    cse: bool
+        Perform common sub-expression elimination on delta expression
+    handle_nan: Token
+        How to handle occurrence of not-a-number (NaN).
+    bounds: Optional[tuple[Expr, Expr]]
+        Perform optimization within bounds
+
+    Examples
+    ========
+
+    >>> from sympy import symbols, cos
+    >>> from sympy.codegen.ast import Assignment
+    >>> from sympy.codegen.algorithms import newtons_method
+    >>> x, dx, atol = symbols('x dx atol')
+    >>> expr = cos(x) - x**3
+    >>> algo = newtons_method(expr, x, atol=atol, delta=dx)
+    >>> algo.has(Assignment(dx, -expr/expr.diff(x)))
+    True
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Newton%27s_method
+
+    """
+
+    if delta is None:
+        delta = Dummy()
+        Wrapper = Scope
+        name_d = 'delta'
+    else:
+        Wrapper = lambda x: x
+        name_d = delta.name
+
+    delta_expr = delta_fn(expr, wrt)
+    if cse:
+        from sympy.simplify.cse_main import cse
+        cses, (red,) = cse([delta_expr.factor()])
+        whl_bdy = [Assignment(dum, sub_e) for dum, sub_e in cses]
+        whl_bdy += [Assignment(delta, red)]
+    else:
+        whl_bdy = [Assignment(delta, delta_expr)]
+    if handle_nan is not None:
+        whl_bdy += [While(isnan(delta), CodeBlock(handle_nan, break_))]
+    whl_bdy += [AddAugmentedAssignment(wrt, delta)]
+    if bounds is not None:
+        whl_bdy += [Assignment(wrt, Min(Max(wrt, bounds[0]), bounds[1]))]
+    if debug:
+        prnt = Print([wrt, delta], r"{}=%12.5g {}=%12.5g\n".format(wrt.name, name_d))
+        whl_bdy += [prnt]
+    req = Gt(Abs(delta), atol + rtol*Abs(wrt))
+    declars = [Declaration(Variable(delta, type=real, value=oo))]
+    if itermax is not None:
+        counter = counter or Dummy(integer=True)
+        v_counter = Variable.deduced(counter, 0)
+        declars.append(Declaration(v_counter))
+        whl_bdy.append(AddAugmentedAssignment(counter, 1))
+        req = And(req, Lt(counter, itermax))
+    whl = While(req, CodeBlock(*whl_bdy))
+    blck = declars
+    if debug:
+        blck.append(Print([wrt], r"{}=%12.5g\n".format(wrt.name)))
+    blck += [whl]
+    return Wrapper(CodeBlock(*blck))
+
+
+def _symbol_of(arg):
+    if isinstance(arg, Declaration):
+        arg = arg.variable.symbol
+    elif isinstance(arg, Variable):
+        arg = arg.symbol
+    return arg
+
+
+def newtons_method_function(expr, wrt, params=None, func_name="newton", attrs=Tuple(), *, delta=None, **kwargs):
+    """ Generates an AST for a function implementing the Newton-Raphson method.
+
+    Parameters
+    ==========
+
+    expr : expression
+    wrt : Symbol
+        With respect to, i.e. what is the variable
+    params : iterable of symbols
+        Symbols appearing in expr that are taken as constants during the iterations
+        (these will be accepted as parameters to the generated function).
+    func_name : str
+        Name of the generated function.
+    attrs : Tuple
+        Attribute instances passed as ``attrs`` to ``FunctionDefinition``.
+    \\*\\*kwargs :
+        Keyword arguments passed to :func:`sympy.codegen.algorithms.newtons_method`.
+
+    Examples
+    ========
+
+    >>> from sympy import symbols, cos
+    >>> from sympy.codegen.algorithms import newtons_method_function
+    >>> from sympy.codegen.pyutils import render_as_module
+    >>> x = symbols('x')
+    >>> expr = cos(x) - x**3
+    >>> func = newtons_method_function(expr, x)
+    >>> py_mod = render_as_module(func)  # source code as string
+    >>> namespace = {}
+    >>> exec(py_mod, namespace, namespace)
+    >>> res = eval('newton(0.5)', namespace)
+    >>> abs(res - 0.865474033102) < 1e-12
+    True
+
+    See Also
+    ========
+
+    sympy.codegen.algorithms.newtons_method
+
+    """
+    if params is None:
+        params = (wrt,)
+    pointer_subs = {p.symbol: Symbol('(*%s)' % p.symbol.name)
+                    for p in params if isinstance(p, Pointer)}
+    if delta is None:
+        delta = Symbol('d_' + wrt.name)
+        if expr.has(delta):
+            delta = None  # will use Dummy
+    algo = newtons_method(expr, wrt, delta=delta, **kwargs).xreplace(pointer_subs)
+    if isinstance(algo, Scope):
+        algo = algo.body
+    not_in_params = expr.free_symbols.difference({_symbol_of(p) for p in params})
+    if not_in_params:
+        raise ValueError("Missing symbols in params: %s" % ', '.join(map(str, not_in_params)))
+    declars = tuple(Variable(p, real) for p in params)
+    body = CodeBlock(algo, Return(wrt))
+    return FunctionDefinition(real, func_name, declars, body, attrs=attrs)

.venv/lib/python3.13/site-packages/sympy/codegen/approximations.py

@@ -0,0 +1,187 @@
+import math
+from sympy.sets.sets import Interval
+from sympy.calculus.singularities import is_increasing, is_decreasing
+from sympy.codegen.rewriting import Optimization
+from sympy.core.function import UndefinedFunction
+
+"""
+This module collects classes useful for approximate rewriting of expressions.
+This can be beneficial when generating numeric code for which performance is
+of greater importance than precision (e.g. for preconditioners used in iterative
+methods).
+"""
+
+class SumApprox(Optimization):
+    """
+    Approximates sum by neglecting small terms.
+
+    Explanation
+    ===========
+
+    If terms are expressions which can be determined to be monotonic, then
+    bounds for those expressions are added.
+
+    Parameters
+    ==========
+
+    bounds : dict
+        Mapping expressions to length 2 tuple of bounds (low, high).
+    reltol : number
+        Threshold for when to ignore a term. Taken relative to the largest
+        lower bound among bounds.
+
+    Examples
+    ========
+
+    >>> from sympy import exp
+    >>> from sympy.abc import x, y, z
+    >>> from sympy.codegen.rewriting import optimize
+    >>> from sympy.codegen.approximations import SumApprox
+    >>> bounds = {x: (-1, 1), y: (1000, 2000), z: (-10, 3)}
+    >>> sum_approx3 = SumApprox(bounds, reltol=1e-3)
+    >>> sum_approx2 = SumApprox(bounds, reltol=1e-2)
+    >>> sum_approx1 = SumApprox(bounds, reltol=1e-1)
+    >>> expr = 3*(x + y + exp(z))
+    >>> optimize(expr, [sum_approx3])
+    3*(x + y + exp(z))
+    >>> optimize(expr, [sum_approx2])
+    3*y + 3*exp(z)
+    >>> optimize(expr, [sum_approx1])
+    3*y
+
+    """
+
+    def __init__(self, bounds, reltol, **kwargs):
+        super().__init__(**kwargs)
+        self.bounds = bounds
+        self.reltol = reltol
+
+    def __call__(self, expr):
+        return expr.factor().replace(self.query, lambda arg: self.value(arg))
+
+    def query(self, expr):
+        return expr.is_Add
+
+    def value(self, add):
+        for term in add.args:
+            if term.is_number or term in self.bounds or len(term.free_symbols) != 1:
+                continue
+            fs, = term.free_symbols
+            if fs not in self.bounds:
+                continue
+            intrvl = Interval(*self.bounds[fs])
+            if is_increasing(term, intrvl, fs):
+                self.bounds[term] = (
+                    term.subs({fs: self.bounds[fs][0]}),
+                    term.subs({fs: self.bounds[fs][1]})
+                )
+            elif is_decreasing(term, intrvl, fs):
+                self.bounds[term] = (
+                    term.subs({fs: self.bounds[fs][1]}),
+                    term.subs({fs: self.bounds[fs][0]})
+                )
+            else:
+                return add
+
+        if all(term.is_number or term in self.bounds for term in add.args):
+            bounds = [(term, term) if term.is_number else self.bounds[term] for term in add.args]
+            largest_abs_guarantee = 0
+            for lo, hi in bounds:
+                if lo <= 0 <= hi:
+                    continue
+                largest_abs_guarantee = max(largest_abs_guarantee,
+                                            min(abs(lo), abs(hi)))
+            new_terms = []
+            for term, (lo, hi) in zip(add.args, bounds):
+                if max(abs(lo), abs(hi)) >= largest_abs_guarantee*self.reltol:
+                    new_terms.append(term)
+            return add.func(*new_terms)
+        else:
+            return add
+
+
+class SeriesApprox(Optimization):
+    """ Approximates functions by expanding them as a series.
+
+    Parameters
+    ==========
+
+    bounds : dict
+        Mapping expressions to length 2 tuple of bounds (low, high).
+    reltol : number
+        Threshold for when to ignore a term. Taken relative to the largest
+        lower bound among bounds.
+    max_order : int
+        Largest order to include in series expansion
+    n_point_checks : int (even)
+        The validity of an expansion (with respect to reltol) is checked at
+        discrete points (linearly spaced over the bounds of the variable). The
+        number of points used in this numerical check is given by this number.
+
+    Examples
+    ========
+
+    >>> from sympy import sin, pi
+    >>> from sympy.abc import x, y
+    >>> from sympy.codegen.rewriting import optimize
+    >>> from sympy.codegen.approximations import SeriesApprox
+    >>> bounds = {x: (-.1, .1), y: (pi-1, pi+1)}
+    >>> series_approx2 = SeriesApprox(bounds, reltol=1e-2)
+    >>> series_approx3 = SeriesApprox(bounds, reltol=1e-3)
+    >>> series_approx8 = SeriesApprox(bounds, reltol=1e-8)
+    >>> expr = sin(x)*sin(y)
+    >>> optimize(expr, [series_approx2])
+    x*(-y + (y - pi)**3/6 + pi)
+    >>> optimize(expr, [series_approx3])
+    (-x**3/6 + x)*sin(y)
+    >>> optimize(expr, [series_approx8])
+    sin(x)*sin(y)
+
+    """
+    def __init__(self, bounds, reltol, max_order=4, n_point_checks=4, **kwargs):
+        super().__init__(**kwargs)
+        self.bounds = bounds
+        self.reltol = reltol
+        self.max_order = max_order
+        if n_point_checks % 2 == 1:
+            raise ValueError("Checking the solution at expansion point is not helpful")
+        self.n_point_checks = n_point_checks
+        self._prec = math.ceil(-math.log10(self.reltol))
+
+    def __call__(self, expr):
+        return expr.factor().replace(self.query, lambda arg: self.value(arg))
+
+    def query(self, expr):
+        return (expr.is_Function and not isinstance(expr, UndefinedFunction)
+                and len(expr.args) == 1)
+
+    def value(self, fexpr):
+        free_symbols = fexpr.free_symbols
+        if len(free_symbols) != 1:
+            return fexpr
+        symb, = free_symbols
+        if symb not in self.bounds:
+            return fexpr
+        lo, hi = self.bounds[symb]
+        x0 = (lo + hi)/2
+        cheapest = None
+        for n in range(self.max_order+1, 0, -1):
+            fseri = fexpr.series(symb, x0=x0, n=n).removeO()
+            n_ok = True
+            for idx in range(self.n_point_checks):
+                x = lo + idx*(hi - lo)/(self.n_point_checks - 1)
+                val = fseri.xreplace({symb: x})
+                ref = fexpr.xreplace({symb: x})
+                if abs((1 - val/ref).evalf(self._prec)) > self.reltol:
+                    n_ok = False
+                    break
+
+            if n_ok:
+                cheapest = fseri
+            else:
+                break
+
+        if cheapest is None:
+            return fexpr
+        else:
+            return cheapest

.venv/lib/python3.13/site-packages/sympy/codegen/ast.py

@@ -0,0 +1,1906 @@
+"""
+Types used to represent a full function/module as an Abstract Syntax Tree.
+
+Most types are small, and are merely used as tokens in the AST. A tree diagram
+has been included below to illustrate the relationships between the AST types.
+
+
+AST Type Tree
+-------------
+::
+
+  *Basic*
+       |
+       |
+   CodegenAST
+       |
+       |--->AssignmentBase
+       |             |--->Assignment
+       |             |--->AugmentedAssignment
+       |                                    |--->AddAugmentedAssignment
+       |                                    |--->SubAugmentedAssignment
+       |                                    |--->MulAugmentedAssignment
+       |                                    |--->DivAugmentedAssignment
+       |                                    |--->ModAugmentedAssignment
+       |
+       |--->CodeBlock
+       |
+       |
+       |--->Token
+                |--->Attribute
+                |--->For
+                |--->String
+                |       |--->QuotedString
+                |       |--->Comment
+                |--->Type
+                |       |--->IntBaseType
+                |       |              |--->_SizedIntType
+                |       |                               |--->SignedIntType
+                |       |                               |--->UnsignedIntType
+                |       |--->FloatBaseType
+                |                        |--->FloatType
+                |                        |--->ComplexBaseType
+                |                                           |--->ComplexType
+                |--->Node
+                |       |--->Variable
+                |       |           |---> Pointer
+                |       |--->FunctionPrototype
+                |                            |--->FunctionDefinition
+                |--->Element
+                |--->Declaration
+                |--->While
+                |--->Scope
+                |--->Stream
+                |--->Print
+                |--->FunctionCall
+                |--->BreakToken
+                |--->ContinueToken
+                |--->NoneToken
+                |--->Return
+
+
+Predefined types
+----------------
+
+A number of ``Type`` instances are provided in the ``sympy.codegen.ast`` module
+for convenience. Perhaps the two most common ones for code-generation (of numeric
+codes) are ``float32`` and ``float64`` (known as single and double precision respectively).
+There are also precision generic versions of Types (for which the codeprinters selects the
+underlying data type at time of printing): ``real``, ``integer``, ``complex_``, ``bool_``.
+
+The other ``Type`` instances defined are:
+
+- ``intc``: Integer type used by C's "int".
+- ``intp``: Integer type used by C's "unsigned".
+- ``int8``, ``int16``, ``int32``, ``int64``: n-bit integers.
+- ``uint8``, ``uint16``, ``uint32``, ``uint64``: n-bit unsigned integers.
+- ``float80``: known as "extended precision" on modern x86/amd64 hardware.
+- ``complex64``: Complex number represented by two ``float32`` numbers
+- ``complex128``: Complex number represented by two ``float64`` numbers
+
+Using the nodes
+---------------
+
+It is possible to construct simple algorithms using the AST nodes. Let's construct a loop applying
+Newton's method::
+
+    >>> from sympy import symbols, cos
+    >>> from sympy.codegen.ast import While, Assignment, aug_assign, Print, QuotedString
+    >>> t, dx, x = symbols('tol delta val')
+    >>> expr = cos(x) - x**3
+    >>> whl = While(abs(dx) > t, [
+    ...     Assignment(dx, -expr/expr.diff(x)),
+    ...     aug_assign(x, '+', dx),
+    ...     Print([x])
+    ... ])
+    >>> from sympy import pycode
+    >>> py_str = pycode(whl)
+    >>> print(py_str)
+    while (abs(delta) > tol):
+        delta = (val**3 - math.cos(val))/(-3*val**2 - math.sin(val))
+        val += delta
+        print(val)
+    >>> import math
+    >>> tol, val, delta = 1e-5, 0.5, float('inf')
+    >>> exec(py_str)
+    1.1121416371
+    0.909672693737
+    0.867263818209
+    0.865477135298
+    0.865474033111
+    >>> print('%3.1g' % (math.cos(val) - val**3))
+    -3e-11
+
+If we want to generate Fortran code for the same while loop we simple call ``fcode``::
+
+    >>> from sympy import fcode
+    >>> print(fcode(whl, standard=2003, source_format='free'))
+    do while (abs(delta) > tol)
+       delta = (val**3 - cos(val))/(-3*val**2 - sin(val))
+       val = val + delta
+       print *, val
+    end do
+
+There is a function constructing a loop (or a complete function) like this in
+:mod:`sympy.codegen.algorithms`.
+
+"""
+
+from __future__ import annotations
+from typing import Any
+
+from collections import defaultdict
+
+from sympy.core.relational import (Ge, Gt, Le, Lt)
+from sympy.core import Symbol, Tuple, Dummy
+from sympy.core.basic import Basic
+from sympy.core.expr import Expr, Atom
+from sympy.core.numbers import Float, Integer, oo
+from sympy.core.sympify import _sympify, sympify, SympifyError
+from sympy.utilities.iterables import (iterable, topological_sort,
+                                       numbered_symbols, filter_symbols)
+
+
+def _mk_Tuple(args):
+    """
+    Create a SymPy Tuple object from an iterable, converting Python strings to
+    AST strings.
+
+    Parameters
+    ==========
+
+    args: iterable
+        Arguments to :class:`sympy.Tuple`.
+
+    Returns
+    =======
+
+    sympy.Tuple
+    """
+    args = [String(arg) if isinstance(arg, str) else arg for arg in args]
+    return Tuple(*args)
+
+
+class CodegenAST(Basic):
+    __slots__ = ()
+
+
+class Token(CodegenAST):
+    """ Base class for the AST types.
+
+    Explanation
+    ===========
+
+    Defining fields are set in ``_fields``. Attributes (defined in _fields)
+    are only allowed to contain instances of Basic (unless atomic, see
+    ``String``). The arguments to ``__new__()`` correspond to the attributes in
+    the order defined in ``_fields`. The ``defaults`` class attribute is a
+    dictionary mapping attribute names to their default values.
+
+    Subclasses should not need to override the ``__new__()`` method. They may
+    define a class or static method named ``_construct_<attr>`` for each
+    attribute to process the value passed to ``__new__()``. Attributes listed
+    in the class attribute ``not_in_args`` are not passed to :class:`~.Basic`.
+    """
+
+    __slots__: tuple[str, ...] = ()
+    _fields = __slots__
+    defaults: dict[str, Any] = {}
+    not_in_args: list[str] = []
+    indented_args = ['body']
+
+    @property
+    def is_Atom(self):
+        return len(self._fields) == 0
+
+    @classmethod
+    def _get_constructor(cls, attr):
+        """ Get the constructor function for an attribute by name. """
+        return getattr(cls, '_construct_%s' % attr, lambda x: x)
+
+    @classmethod
+    def _construct(cls, attr, arg):
+        """ Construct an attribute value from argument passed to ``__new__()``. """
+        # arg may be ``NoneToken()``, so comparison is done using == instead of ``is`` operator
+        if arg == None:
+            return cls.defaults.get(attr, none)
+        else:
+            if isinstance(arg, Dummy):  # SymPy's replace uses Dummy instances
+                return arg
+            else:
+                return cls._get_constructor(attr)(arg)
+
+    def __new__(cls, *args, **kwargs):
+        # Pass through existing instances when given as sole argument
+        if len(args) == 1 and not kwargs and isinstance(args[0], cls):
+            return args[0]
+
+        if len(args) > len(cls._fields):
+            raise ValueError("Too many arguments (%d), expected at most %d" % (len(args), len(cls._fields)))
+
+        attrvals = []
+
+        # Process positional arguments
+        for attrname, argval in zip(cls._fields, args):
+            if attrname in kwargs:
+                raise TypeError('Got multiple values for attribute %r' % attrname)
+
+            attrvals.append(cls._construct(attrname, argval))
+
+        # Process keyword arguments
+        for attrname in cls._fields[len(args):]:
+            if attrname in kwargs:
+                argval = kwargs.pop(attrname)
+
+            elif attrname in cls.defaults:
+                argval = cls.defaults[attrname]
+
+            else:
+                raise TypeError('No value for %r given and attribute has no default' % attrname)
+
+            attrvals.append(cls._construct(attrname, argval))
+
+        if kwargs:
+            raise ValueError("Unknown keyword arguments: %s" % ' '.join(kwargs))
+
+        # Parent constructor
+        basic_args = [
+            val for attr, val in zip(cls._fields, attrvals)
+            if attr not in cls.not_in_args
+        ]
+        obj = CodegenAST.__new__(cls, *basic_args)
+
+        # Set attributes
+        for attr, arg in zip(cls._fields, attrvals):
+            setattr(obj, attr, arg)
+
+        return obj
+
+    def __eq__(self, other):
+        if not isinstance(other, self.__class__):
+            return False
+        for attr in self._fields:
+            if getattr(self, attr) != getattr(other, attr):
+                return False
+        return True
+
+    def _hashable_content(self):
+        return tuple([getattr(self, attr) for attr in self._fields])
+
+    def __hash__(self):
+        return super().__hash__()
+
+    def _joiner(self, k, indent_level):
+        return (',\n' + ' '*indent_level) if k in self.indented_args else ', '
+
+    def _indented(self, printer, k, v, *args, **kwargs):
+        il = printer._context['indent_level']
+        def _print(arg):
+            if isinstance(arg, Token):
+                return printer._print(arg, *args, joiner=self._joiner(k, il), **kwargs)
+            else:
+                return printer._print(arg, *args, **kwargs)
+
+        if isinstance(v, Tuple):
+            joined = self._joiner(k, il).join([_print(arg) for arg in v.args])
+            if k in self.indented_args:
+                return '(\n' + ' '*il + joined + ',\n' + ' '*(il - 4) + ')'
+            else:
+                return ('({0},)' if len(v.args) == 1 else '({0})').format(joined)
+        else:
+            return _print(v)
+
+    def _sympyrepr(self, printer, *args, joiner=', ', **kwargs):
+        from sympy.printing.printer import printer_context
+        exclude = kwargs.get('exclude', ())
+        values = [getattr(self, k) for k in self._fields]
+        indent_level = printer._context.get('indent_level', 0)
+
+        arg_reprs = []
+
+        for i, (attr, value) in enumerate(zip(self._fields, values)):
+            if attr in exclude:
+                continue
+
+            # Skip attributes which have the default value
+            if attr in self.defaults and value == self.defaults[attr]:
+                continue
+
+            ilvl = indent_level + 4 if attr in self.indented_args else 0
+            with printer_context(printer, indent_level=ilvl):
+                indented = self._indented(printer, attr, value, *args, **kwargs)
+            arg_reprs.append(('{1}' if i == 0 else '{0}={1}').format(attr, indented.lstrip()))
+
+        return "{}({})".format(self.__class__.__name__, joiner.join(arg_reprs))
+
+    _sympystr = _sympyrepr
+
+    def __repr__(self):  # sympy.core.Basic.__repr__ uses sstr
+        from sympy.printing import srepr
+        return srepr(self)
+
+    def kwargs(self, exclude=(), apply=None):
+        """ Get instance's attributes as dict of keyword arguments.
+
+        Parameters
+        ==========
+
+        exclude : collection of str
+            Collection of keywords to exclude.
+
+        apply : callable, optional
+            Function to apply to all values.
+        """
+        kwargs = {k: getattr(self, k) for k in self._fields if k not in exclude}
+        if apply is not None:
+            return {k: apply(v) for k, v in kwargs.items()}
+        else:
+            return kwargs
+
+class BreakToken(Token):
+    """ Represents 'break' in C/Python ('exit' in Fortran).
+
+    Use the premade instance ``break_`` or instantiate manually.
+
+    Examples
+    ========
+
+    >>> from sympy import ccode, fcode
+    >>> from sympy.codegen.ast import break_
+    >>> ccode(break_)
+    'break'
+    >>> fcode(break_, source_format='free')
+    'exit'
+    """
+
+break_ = BreakToken()
+
+
+class ContinueToken(Token):
+    """ Represents 'continue' in C/Python ('cycle' in Fortran)
+
+    Use the premade instance ``continue_`` or instantiate manually.
+
+    Examples
+    ========
+
+    >>> from sympy import ccode, fcode
+    >>> from sympy.codegen.ast import continue_
+    >>> ccode(continue_)
+    'continue'
+    >>> fcode(continue_, source_format='free')
+    'cycle'
+    """
+
+continue_ = ContinueToken()
+
+class NoneToken(Token):
+    """ The AST equivalence of Python's NoneType
+
+    The corresponding instance of Python's ``None`` is ``none``.
+
+    Examples
+    ========
+
+    >>> from sympy.codegen.ast import none, Variable
+    >>> from sympy import pycode
+    >>> print(pycode(Variable('x').as_Declaration(value=none)))
+    x = None
+
+    """
+    def __eq__(self, other):
+        return other is None or isinstance(other, NoneToken)
+
+    def _hashable_content(self):
+        return ()
+
+    def __hash__(self):
+        return super().__hash__()
+
+
+none = NoneToken()
+
+
+class AssignmentBase(CodegenAST):
+    """ Abstract base class for Assignment and AugmentedAssignment.
+
+    Attributes:
+    ===========
+
+    op : str
+        Symbol for assignment operator, e.g. "=", "+=", etc.
+    """
+
+    def __new__(cls, lhs, rhs):
+        lhs = _sympify(lhs)
+        rhs = _sympify(rhs)
+
+        cls._check_args(lhs, rhs)
+
+        return super().__new__(cls, lhs, rhs)
+
+    @property
+    def lhs(self):
+        return self.args[0]
+
+    @property
+    def rhs(self):
+        return self.args[1]
+
+    @classmethod
+    def _check_args(cls, lhs, rhs):
+        """ Check arguments to __new__ and raise exception if any problems found.
+
+        Derived classes may wish to override this.
+        """
+        from sympy.matrices.expressions.matexpr import (
+            MatrixElement, MatrixSymbol)
+        from sympy.tensor.indexed import Indexed
+        from sympy.tensor.array.expressions import ArrayElement
+
+        # Tuple of things that can be on the lhs of an assignment
+        assignable = (Symbol, MatrixSymbol, MatrixElement, Indexed, Element, Variable,
+                ArrayElement)
+        if not isinstance(lhs, assignable):
+            raise TypeError("Cannot assign to lhs of type %s." % type(lhs))
+
+        # Indexed types implement shape, but don't define it until later. This
+        # causes issues in assignment validation. For now, matrices are defined
+        # as anything with a shape that is not an Indexed
+        lhs_is_mat = hasattr(lhs, 'shape') and not isinstance(lhs, Indexed)
+        rhs_is_mat = hasattr(rhs, 'shape') and not isinstance(rhs, Indexed)
+
+        # If lhs and rhs have same structure, then this assignment is ok
+        if lhs_is_mat:
+            if not rhs_is_mat:
+                raise ValueError("Cannot assign a scalar to a matrix.")
+            elif lhs.shape != rhs.shape:
+                raise ValueError("Dimensions of lhs and rhs do not align.")
+        elif rhs_is_mat and not lhs_is_mat:
+            raise ValueError("Cannot assign a matrix to a scalar.")
+
+
+class Assignment(AssignmentBase):
+    """
+    Represents variable assignment for code generation.
+
+    Parameters
+    ==========
+
+    lhs : Expr
+        SymPy object representing the lhs of the expression. These should be
+        singular objects, such as one would use in writing code. Notable types
+        include Symbol, MatrixSymbol, MatrixElement, and Indexed. Types that
+        subclass these types are also supported.
+
+    rhs : Expr
+        SymPy object representing the rhs of the expression. This can be any
+        type, provided its shape corresponds to that of the lhs. For example,
+        a Matrix type can be assigned to MatrixSymbol, but not to Symbol, as
+        the dimensions will not align.
+
+    Examples
+    ========
+
+    >>> from sympy import symbols, MatrixSymbol, Matrix
+    >>> from sympy.codegen.ast import Assignment
+    >>> x, y, z = symbols('x, y, z')
+    >>> Assignment(x, y)
+    Assignment(x, y)
+    >>> Assignment(x, 0)
+    Assignment(x, 0)
+    >>> A = MatrixSymbol('A', 1, 3)
+    >>> mat = Matrix([x, y, z]).T
+    >>> Assignment(A, mat)
+    Assignment(A, Matrix([[x, y, z]]))
+    >>> Assignment(A[0, 1], x)
+    Assignment(A[0, 1], x)
+    """
+
+    op = ':='
+
+
+class AugmentedAssignment(AssignmentBase):
+    """
+    Base class for augmented assignments.
+
+    Attributes:
+    ===========
+
+    binop : str
+       Symbol for binary operation being applied in the assignment, such as "+",
+       "*", etc.
+    """
+    binop: str | None
+
+    @property
+    def op(self):
+        return self.binop + '='
+
+
+class AddAugmentedAssignment(AugmentedAssignment):
+    binop = '+'
+
+
+class SubAugmentedAssignment(AugmentedAssignment):
+    binop = '-'
+
+
+class MulAugmentedAssignment(AugmentedAssignment):
+    binop = '*'
+
+
+class DivAugmentedAssignment(AugmentedAssignment):
+    binop = '/'
+
+
+class ModAugmentedAssignment(AugmentedAssignment):
+    binop = '%'
+
+
+# Mapping from binary op strings to AugmentedAssignment subclasses
+augassign_classes = {
+    cls.binop: cls for cls in [
+        AddAugmentedAssignment, SubAugmentedAssignment, MulAugmentedAssignment,
+        DivAugmentedAssignment, ModAugmentedAssignment
+    ]
+}
+
+
+def aug_assign(lhs, op, rhs):
+    """
+    Create 'lhs op= rhs'.
+
+    Explanation
+    ===========
+
+    Represents augmented variable assignment for code generation. This is a
+    convenience function. You can also use the AugmentedAssignment classes
+    directly, like AddAugmentedAssignment(x, y).
+
+    Parameters
+    ==========
+
+    lhs : Expr
+        SymPy object representing the lhs of the expression. These should be
+        singular objects, such as one would use in writing code. Notable types
+        include Symbol, MatrixSymbol, MatrixElement, and Indexed. Types that
+        subclass these types are also supported.
+
+    op : str
+        Operator (+, -, /, \\*, %).
+
+    rhs : Expr
+        SymPy object representing the rhs of the expression. This can be any
+        type, provided its shape corresponds to that of the lhs. For example,
+        a Matrix type can be assigned to MatrixSymbol, but not to Symbol, as
+        the dimensions will not align.
+
+    Examples
+    ========
+
+    >>> from sympy import symbols
+    >>> from sympy.codegen.ast import aug_assign
+    >>> x, y = symbols('x, y')
+    >>> aug_assign(x, '+', y)
+    AddAugmentedAssignment(x, y)
+    """
+    if op not in augassign_classes:
+        raise ValueError("Unrecognized operator %s" % op)
+    return augassign_classes[op](lhs, rhs)
+
+
+class CodeBlock(CodegenAST):
+    """
+    Represents a block of code.
+
+    Explanation
+    ===========
+
+    For now only assignments are supported. This restriction will be lifted in
+    the future.
+
+    Useful attributes on this object are:
+
+    ``left_hand_sides``:
+        Tuple of left-hand sides of assignments, in order.
+    ``left_hand_sides``:
+        Tuple of right-hand sides of assignments, in order.
+    ``free_symbols``: Free symbols of the expressions in the right-hand sides
+        which do not appear in the left-hand side of an assignment.
+
+    Useful methods on this object are:
+
+    ``topological_sort``:
+        Class method. Return a CodeBlock with assignments
+        sorted so that variables are assigned before they
+        are used.
+    ``cse``:
+        Return a new CodeBlock with common subexpressions eliminated and
+        pulled out as assignments.
+
+    Examples
+    ========
+
+    >>> from sympy import symbols, ccode
+    >>> from sympy.codegen.ast import CodeBlock, Assignment
+    >>> x, y = symbols('x y')
+    >>> c = CodeBlock(Assignment(x, 1), Assignment(y, x + 1))
+    >>> print(ccode(c))
+    x = 1;
+    y = x + 1;
+
+    """
+    def __new__(cls, *args):
+        left_hand_sides = []
+        right_hand_sides = []
+        for i in args:
+            if isinstance(i, Assignment):
+                lhs, rhs = i.args
+                left_hand_sides.append(lhs)
+                right_hand_sides.append(rhs)
+
+        obj = CodegenAST.__new__(cls, *args)
+
+        obj.left_hand_sides = Tuple(*left_hand_sides)
+        obj.right_hand_sides = Tuple(*right_hand_sides)
+        return obj
+
+    def __iter__(self):
+        return iter(self.args)
+
+    def _sympyrepr(self, printer, *args, **kwargs):
+        il = printer._context.get('indent_level', 0)
+        joiner = ',\n' + ' '*il
+        joined = joiner.join(map(printer._print, self.args))
+        return ('{}(\n'.format(' '*(il-4) + self.__class__.__name__,) +
+                ' '*il + joined + '\n' + ' '*(il - 4) + ')')
+
+    _sympystr = _sympyrepr
+
+    @property
+    def free_symbols(self):
+        return super().free_symbols - set(self.left_hand_sides)
+
+    @classmethod
+    def topological_sort(cls, assignments):
+        """
+        Return a CodeBlock with topologically sorted assignments so that
+        variables are assigned before they are used.
+
+        Examples
+        ========
+
+        The existing order of assignments is preserved as much as possible.
+
+        This function assumes that variables are assigned to only once.
+
+        This is a class constructor so that the default constructor for
+        CodeBlock can error when variables are used before they are assigned.
+
+        >>> from sympy import symbols
+        >>> from sympy.codegen.ast import CodeBlock, Assignment
+        >>> x, y, z = symbols('x y z')
+
+        >>> assignments = [
+        ...     Assignment(x, y + z),
+        ...     Assignment(y, z + 1),
+        ...     Assignment(z, 2),
+        ... ]
+        >>> CodeBlock.topological_sort(assignments)
+        CodeBlock(
+            Assignment(z, 2),
+            Assignment(y, z + 1),
+            Assignment(x, y + z)
+        )
+
+        """
+
+        if not all(isinstance(i, Assignment) for i in assignments):
+            # Will support more things later
+            raise NotImplementedError("CodeBlock.topological_sort only supports Assignments")
+
+        if any(isinstance(i, AugmentedAssignment) for i in assignments):
+            raise NotImplementedError("CodeBlock.topological_sort does not yet work with AugmentedAssignments")
+
+        # Create a graph where the nodes are assignments and there is a directed edge
+        # between nodes that use a variable and nodes that assign that
+        # variable, like
+
+        # [(x := 1, y := x + 1), (x := 1, z := y + z), (y := x + 1, z := y + z)]
+
+        # If we then topologically sort these nodes, they will be in
+        # assignment order, like
+
+        # x := 1
+        # y := x + 1
+        # z := y + z
+
+        # A = The nodes
+        #
+        # enumerate keeps nodes in the same order they are already in if
+        # possible. It will also allow us to handle duplicate assignments to
+        # the same variable when those are implemented.
+        A = list(enumerate(assignments))
+
+        # var_map = {variable: [nodes for which this variable is assigned to]}
+        # like {x: [(1, x := y + z), (4, x := 2 * w)], ...}
+        var_map = defaultdict(list)
+        for node in A:
+            i, a = node
+            var_map[a.lhs].append(node)
+
+        # E = Edges in the graph
+        E = []
+        for dst_node in A:
+            i, a = dst_node
+            for s in a.rhs.free_symbols:
+                for src_node in var_map[s]:
+                    E.append((src_node, dst_node))
+
+        ordered_assignments = topological_sort([A, E])
+
+        # De-enumerate the result
+        return cls(*[a for i, a in ordered_assignments])
+
+    def cse(self, symbols=None, optimizations=None, postprocess=None,
+        order='canonical'):
+        """
+        Return a new code block with common subexpressions eliminated.
+
+        Explanation
+        ===========
+
+        See the docstring of :func:`sympy.simplify.cse_main.cse` for more
+        information.
+
+        Examples
+        ========
+
+        >>> from sympy import symbols, sin
+        >>> from sympy.codegen.ast import CodeBlock, Assignment
+        >>> x, y, z = symbols('x y z')
+
+        >>> c = CodeBlock(
+        ...     Assignment(x, 1),
+        ...     Assignment(y, sin(x) + 1),
+        ...     Assignment(z, sin(x) - 1),
+        ... )
+        ...
+        >>> c.cse()
+        CodeBlock(
+            Assignment(x, 1),
+            Assignment(x0, sin(x)),
+            Assignment(y, x0 + 1),
+            Assignment(z, x0 - 1)
+        )
+
+        """
+        from sympy.simplify.cse_main import cse
+
+        # Check that the CodeBlock only contains assignments to unique variables
+        if not all(isinstance(i, Assignment) for i in self.args):
+            # Will support more things later
+            raise NotImplementedError("CodeBlock.cse only supports Assignments")
+
+        if any(isinstance(i, AugmentedAssignment) for i in self.args):
+            raise NotImplementedError("CodeBlock.cse does not yet work with AugmentedAssignments")
+
+        for i, lhs in enumerate(self.left_hand_sides):
+            if lhs in self.left_hand_sides[:i]:
+                raise NotImplementedError("Duplicate assignments to the same "
+                    "variable are not yet supported (%s)" % lhs)
+
+        # Ensure new symbols for subexpressions do not conflict with existing
+        existing_symbols = self.atoms(Symbol)
+        if symbols is None:
+            symbols = numbered_symbols()
+        symbols = filter_symbols(symbols, existing_symbols)
+
+        replacements, reduced_exprs = cse(list(self.right_hand_sides),
+            symbols=symbols, optimizations=optimizations, postprocess=postprocess,
+            order=order)
+
+        new_block = [Assignment(var, expr) for var, expr in
+            zip(self.left_hand_sides, reduced_exprs)]
+        new_assignments = [Assignment(var, expr) for var, expr in replacements]
+        return self.topological_sort(new_assignments + new_block)
+
+
+class For(Token):
+    """Represents a 'for-loop' in the code.
+
+    Expressions are of the form:
+        "for target in iter:
+            body..."
+
+    Parameters
+    ==========
+
+    target : symbol
+    iter : iterable
+    body : CodeBlock or iterable
+!        When passed an iterable it is used to instantiate a CodeBlock.
+
+    Examples
+    ========
+
+    >>> from sympy import symbols, Range
+    >>> from sympy.codegen.ast import aug_assign, For
+    >>> x, i, j, k = symbols('x i j k')
+    >>> for_i = For(i, Range(10), [aug_assign(x, '+', i*j*k)])
+    >>> for_i  # doctest: -NORMALIZE_WHITESPACE
+    For(i, iterable=Range(0, 10, 1), body=CodeBlock(
+        AddAugmentedAssignment(x, i*j*k)
+    ))
+    >>> for_ji = For(j, Range(7), [for_i])
+    >>> for_ji  # doctest: -NORMALIZE_WHITESPACE
+    For(j, iterable=Range(0, 7, 1), body=CodeBlock(
+        For(i, iterable=Range(0, 10, 1), body=CodeBlock(
+            AddAugmentedAssignment(x, i*j*k)
+        ))
+    ))
+    >>> for_kji =For(k, Range(5), [for_ji])
+    >>> for_kji  # doctest: -NORMALIZE_WHITESPACE
+    For(k, iterable=Range(0, 5, 1), body=CodeBlock(
+        For(j, iterable=Range(0, 7, 1), body=CodeBlock(
+            For(i, iterable=Range(0, 10, 1), body=CodeBlock(
+                AddAugmentedAssignment(x, i*j*k)
+            ))
+        ))
+    ))
+    """
+    __slots__ = _fields = ('target', 'iterable', 'body')
+    _construct_target = staticmethod(_sympify)
+
+    @classmethod
+    def _construct_body(cls, itr):
+        if isinstance(itr, CodeBlock):
+            return itr
+        else:
+            return CodeBlock(*itr)
+
+    @classmethod
+    def _construct_iterable(cls, itr):
+        if not iterable(itr):
+            raise TypeError("iterable must be an iterable")
+        if isinstance(itr, list):  # _sympify errors on lists because they are mutable
+            itr = tuple(itr)
+        return _sympify(itr)
+
+
+class String(Atom, Token):
+    """ SymPy object representing a string.
+
+    Atomic object which is not an expression (as opposed to Symbol).
+
+    Parameters
+    ==========
+
+    text : str
+
+    Examples
+    ========
+
+    >>> from sympy.codegen.ast import String
+    >>> f = String('foo')
+    >>> f
+    foo
+    >>> str(f)
+    'foo'
+    >>> f.text
+    'foo'
+    >>> print(repr(f))
+    String('foo')
+
+    """
+    __slots__ = _fields = ('text',)
+    not_in_args = ['text']
+    is_Atom = True
+
+    @classmethod
+    def _construct_text(cls, text):
+        if not isinstance(text, str):
+            raise TypeError("Argument text is not a string type.")
+        return text
+
+    def _sympystr(self, printer, *args, **kwargs):
+        return self.text
+
+    def kwargs(self, exclude = (), apply = None):
+        return {}
+
+    #to be removed when Atom is given a suitable func
+    @property
+    def func(self):
+        return lambda: self
+
+    def _latex(self, printer):
+        from sympy.printing.latex import latex_escape
+        return r'\texttt{{"{}"}}'.format(latex_escape(self.text))
+
+class QuotedString(String):
+    """ Represents a string which should be printed with quotes. """
+
+class Comment(String):
+    """ Represents a comment. """
+
+class Node(Token):
+    """ Subclass of Token, carrying the attribute 'attrs' (Tuple)
+
+    Examples
+    ========
+
+    >>> from sympy.codegen.ast import Node, value_const, pointer_const
+    >>> n1 = Node([value_const])
+    >>> n1.attr_params('value_const')  # get the parameters of attribute (by name)
+    ()
+    >>> from sympy.codegen.fnodes import dimension
+    >>> n2 = Node([value_const, dimension(5, 3)])
+    >>> n2.attr_params(value_const)  # get the parameters of attribute (by Attribute instance)
+    ()
+    >>> n2.attr_params('dimension')  # get the parameters of attribute (by name)
+    (5, 3)
+    >>> n2.attr_params(pointer_const) is None
+    True
+
+    """
+
+    __slots__: tuple[str, ...] = ('attrs',)
+    _fields = __slots__
+
+    defaults: dict[str, Any] = {'attrs': Tuple()}
+
+    _construct_attrs = staticmethod(_mk_Tuple)
+
+    def attr_params(self, looking_for):
+        """ Returns the parameters of the Attribute with name ``looking_for`` in self.attrs """
+        for attr in self.attrs:
+            if str(attr.name) == str(looking_for):
+                return attr.parameters
+
+
+class Type(Token):
+    """ Represents a type.
+
+    Explanation
+    ===========
+
+    The naming is a super-set of NumPy naming. Type has a classmethod
+    ``from_expr`` which offer type deduction. It also has a method
+    ``cast_check`` which casts the argument to its type, possibly raising an
+    exception if rounding error is not within tolerances, or if the value is not
+    representable by the underlying data type (e.g. unsigned integers).
+
+    Parameters
+    ==========
+
+    name : str
+        Name of the type, e.g. ``object``, ``int16``, ``float16`` (where the latter two
+        would use the ``Type`` sub-classes ``IntType`` and ``FloatType`` respectively).
+        If a ``Type`` instance is given, the said instance is returned.
+
+    Examples
+    ========
+
+    >>> from sympy.codegen.ast import Type
+    >>> t = Type.from_expr(42)
+    >>> t
+    integer
+    >>> print(repr(t))
+    IntBaseType(String('integer'))
+    >>> from sympy.codegen.ast import uint8
+    >>> uint8.cast_check(-1)   # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+      ...
+    ValueError: Minimum value for data type bigger than new value.
+    >>> from sympy.codegen.ast import float32
+    >>> v6 = 0.123456
+    >>> float32.cast_check(v6)
+    0.123456
+    >>> v10 = 12345.67894
+    >>> float32.cast_check(v10)  # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+      ...
+    ValueError: Casting gives a significantly different value.
+    >>> boost_mp50 = Type('boost::multiprecision::cpp_dec_float_50')
+    >>> from sympy import cxxcode
+    >>> from sympy.codegen.ast import Declaration, Variable
+    >>> cxxcode(Declaration(Variable('x', type=boost_mp50)))
+    'boost::multiprecision::cpp_dec_float_50 x'
+
+    References
+    ==========
+
+    .. [1] https://numpy.org/doc/stable/user/basics.types.html
+
+    """
+    __slots__: tuple[str, ...] = ('name',)
+    _fields = __slots__
+
+    _construct_name = String
+
+    def _sympystr(self, printer, *args, **kwargs):
+        return str(self.name)
+
+    @classmethod
+    def from_expr(cls, expr):
+        """ Deduces type from an expression or a ``Symbol``.
+
+        Parameters
+        ==========
+
+        expr : number or SymPy object
+            The type will be deduced from type or properties.
+
+        Examples
+        ========
+
+        >>> from sympy.codegen.ast import Type, integer, complex_
+        >>> Type.from_expr(2) == integer
+        True
+        >>> from sympy import Symbol
+        >>> Type.from_expr(Symbol('z', complex=True)) == complex_
+        True
+        >>> Type.from_expr(sum)  # doctest: +ELLIPSIS
+        Traceback (most recent call last):
+          ...
+        ValueError: Could not deduce type from expr.
+
+        Raises
+        ======
+
+        ValueError when type deduction fails.
+
+        """
+        if isinstance(expr, (float, Float)):
+            return real
+        if isinstance(expr, (int, Integer)) or getattr(expr, 'is_integer', False):
+            return integer
+        if getattr(expr, 'is_real', False):
+            return real
+        if isinstance(expr, complex) or getattr(expr, 'is_complex', False):
+            return complex_
+        if isinstance(expr, bool) or getattr(expr, 'is_Relational', False):
+            return bool_
+        else:
+            raise ValueError("Could not deduce type from expr.")
+
+    def _check(self, value):
+        pass
+
+    def cast_check(self, value, rtol=None, atol=0, precision_targets=None):
+        """ Casts a value to the data type of the instance.
+
+        Parameters
+        ==========
+
+        value : number
+        rtol : floating point number
+            Relative tolerance. (will be deduced if not given).
+        atol : floating point number
+            Absolute tolerance (in addition to ``rtol``).
+        type_aliases : dict
+            Maps substitutions for Type, e.g. {integer: int64, real: float32}
+
+        Examples
+        ========
+
+        >>> from sympy.codegen.ast import integer, float32, int8
+        >>> integer.cast_check(3.0) == 3
+        True
+        >>> float32.cast_check(1e-40)  # doctest: +ELLIPSIS
+        Traceback (most recent call last):
+          ...
+        ValueError: Minimum value for data type bigger than new value.
+        >>> int8.cast_check(256)  # doctest: +ELLIPSIS
+        Traceback (most recent call last):
+          ...
+        ValueError: Maximum value for data type smaller than new value.
+        >>> v10 = 12345.67894
+        >>> float32.cast_check(v10)  # doctest: +ELLIPSIS
+        Traceback (most recent call last):
+          ...
+        ValueError: Casting gives a significantly different value.
+        >>> from sympy.codegen.ast import float64
+        >>> float64.cast_check(v10)
+        12345.67894
+        >>> from sympy import Float
+        >>> v18 = Float('0.123456789012345646')
+        >>> float64.cast_check(v18)
+        Traceback (most recent call last):
+          ...
+        ValueError: Casting gives a significantly different value.
+        >>> from sympy.codegen.ast import float80
+        >>> float80.cast_check(v18)
+        0.123456789012345649
+
+        """
+        val = sympify(value)
+
+        ten = Integer(10)
+        exp10 = getattr(self, 'decimal_dig', None)
+
+        if rtol is None:
+            rtol = 1e-15 if exp10 is None else 2.0*ten**(-exp10)
+
+        def tol(num):
+            return atol + rtol*abs(num)
+
+        new_val = self.cast_nocheck(value)
+        self._check(new_val)
+
+        delta = new_val - val
+        if abs(delta) > tol(val):  # rounding, e.g. int(3.5) != 3.5
+            raise ValueError("Casting gives a significantly different value.")
+
+        return new_val
+
+    def _latex(self, printer):
+        from sympy.printing.latex import latex_escape
+        type_name = latex_escape(self.__class__.__name__)
+        name = latex_escape(self.name.text)
+        return r"\text{{{}}}\left(\texttt{{{}}}\right)".format(type_name, name)
+
+
+class IntBaseType(Type):
+    """ Integer base type, contains no size information. """
+    __slots__ = ()
+    cast_nocheck = lambda self, i: Integer(int(i))
+
+
+class _SizedIntType(IntBaseType):
+    __slots__ = ('nbits',)
+    _fields = Type._fields + __slots__
+
+    _construct_nbits = Integer
+
+    def _check(self, value):
+        if value < self.min:
+            raise ValueError("Value is too small: %d < %d" % (value, self.min))
+        if value > self.max:
+            raise ValueError("Value is too big: %d > %d" % (value, self.max))
+
+
+class SignedIntType(_SizedIntType):
+    """ Represents a signed integer type. """
+    __slots__ = ()
+    @property
+    def min(self):
+        return -2**(self.nbits-1)
+
+    @property
+    def max(self):
+        return 2**(self.nbits-1) - 1
+
+
+class UnsignedIntType(_SizedIntType):
+    """ Represents an unsigned integer type. """
+    __slots__ = ()
+    @property
+    def min(self):
+        return 0
+
+    @property
+    def max(self):
+        return 2**self.nbits - 1
+
+two = Integer(2)
+
+class FloatBaseType(Type):
+    """ Represents a floating point number type. """
+    __slots__ = ()
+    cast_nocheck = Float
+
+class FloatType(FloatBaseType):
+    """ Represents a floating point type with fixed bit width.
+
+    Base 2 & one sign bit is assumed.
+
+    Parameters
+    ==========
+
+    name : str
+        Name of the type.
+    nbits : integer
+        Number of bits used (storage).
+    nmant : integer
+        Number of bits used to represent the mantissa.
+    nexp : integer
+        Number of bits used to represent the mantissa.
+
+    Examples
+    ========
+
+    >>> from sympy import S
+    >>> from sympy.codegen.ast import FloatType
+    >>> half_precision = FloatType('f16', nbits=16, nmant=10, nexp=5)
+    >>> half_precision.max
+    65504
+    >>> half_precision.tiny == S(2)**-14
+    True
+    >>> half_precision.eps == S(2)**-10
+    True
+    >>> half_precision.dig == 3
+    True
+    >>> half_precision.decimal_dig == 5
+    True
+    >>> half_precision.cast_check(1.0)
+    1.0
+    >>> half_precision.cast_check(1e5)  # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+      ...
+    ValueError: Maximum value for data type smaller than new value.
+    """
+
+    __slots__ = ('nbits', 'nmant', 'nexp',)
+    _fields = Type._fields + __slots__
+
+    _construct_nbits = _construct_nmant = _construct_nexp = Integer
+
+
+    @property
+    def max_exponent(self):
+        """ The largest positive number n, such that 2**(n - 1) is a representable finite value. """
+        # cf. C++'s ``std::numeric_limits::max_exponent``
+        return two**(self.nexp - 1)
+
+    @property
+    def min_exponent(self):
+        """ The lowest negative number n, such that 2**(n - 1) is a valid normalized number. """
+        # cf. C++'s ``std::numeric_limits::min_exponent``
+        return 3 - self.max_exponent
+
+    @property
+    def max(self):
+        """ Maximum value representable. """
+        return (1 - two**-(self.nmant+1))*two**self.max_exponent
+
+    @property
+    def tiny(self):
+        """ The minimum positive normalized value. """
+        # See C macros: FLT_MIN, DBL_MIN, LDBL_MIN
+        # or C++'s ``std::numeric_limits::min``
+        # or numpy.finfo(dtype).tiny
+        return two**(self.min_exponent - 1)
+
+
+    @property
+    def eps(self):
+        """ Difference between 1.0 and the next representable value. """
+        return two**(-self.nmant)
+
+    @property
+    def dig(self):
+        """ Number of decimal digits that are guaranteed to be preserved in text.
+
+        When converting text -> float -> text, you are guaranteed that at least ``dig``
+        number of digits are preserved with respect to rounding or overflow.
+        """
+        from sympy.functions import floor, log
+        return floor(self.nmant * log(2)/log(10))
+
+    @property
+    def decimal_dig(self):
+        """ Number of digits needed to store & load without loss.
+
+        Explanation
+        ===========
+
+        Number of decimal digits needed to guarantee that two consecutive conversions
+        (float -> text -> float) to be idempotent. This is useful when one do not want
+        to loose precision due to rounding errors when storing a floating point value
+        as text.
+        """
+        from sympy.functions import ceiling, log
+        return ceiling((self.nmant + 1) * log(2)/log(10) + 1)
+
+    def cast_nocheck(self, value):
+        """ Casts without checking if out of bounds or subnormal. """
+        if value == oo:  # float(oo) or oo
+            return float(oo)
+        elif value == -oo:  # float(-oo) or -oo
+            return float(-oo)
+        return Float(str(sympify(value).evalf(self.decimal_dig)), self.decimal_dig)
+
+    def _check(self, value):
+        if value < -self.max:
+            raise ValueError("Value is too small: %d < %d" % (value, -self.max))
+        if value > self.max:
+            raise ValueError("Value is too big: %d > %d" % (value, self.max))
+        if abs(value) < self.tiny:
+            raise ValueError("Smallest (absolute) value for data type bigger than new value.")
+
+class ComplexBaseType(FloatBaseType):
+
+    __slots__ = ()
+
+    def cast_nocheck(self, value):
+        """ Casts without checking if out of bounds or subnormal. """
+        from sympy.functions import re, im
+        return (
+            super().cast_nocheck(re(value)) +
+            super().cast_nocheck(im(value))*1j
+        )
+
+    def _check(self, value):
+        from sympy.functions import re, im
+        super()._check(re(value))
+        super()._check(im(value))
+
+
+class ComplexType(ComplexBaseType, FloatType):
+    """ Represents a complex floating point number. """
+    __slots__ = ()
+
+
+# NumPy types:
+intc = IntBaseType('intc')
+intp = IntBaseType('intp')
+int8 = SignedIntType('int8', 8)
+int16 = SignedIntType('int16', 16)
+int32 = SignedIntType('int32', 32)
+int64 = SignedIntType('int64', 64)
+uint8 = UnsignedIntType('uint8', 8)
+uint16 = UnsignedIntType('uint16', 16)
+uint32 = UnsignedIntType('uint32', 32)
+uint64 = UnsignedIntType('uint64', 64)
+float16 = FloatType('float16', 16, nexp=5, nmant=10)  # IEEE 754 binary16, Half precision
+float32 = FloatType('float32', 32, nexp=8, nmant=23)  # IEEE 754 binary32, Single precision
+float64 = FloatType('float64', 64, nexp=11, nmant=52)  # IEEE 754 binary64, Double precision
+float80 = FloatType('float80', 80, nexp=15, nmant=63)  # x86 extended precision (1 integer part bit), "long double"
+float128 = FloatType('float128', 128, nexp=15, nmant=112)  # IEEE 754 binary128, Quadruple precision
+float256 = FloatType('float256', 256, nexp=19, nmant=236)  # IEEE 754 binary256, Octuple precision
+
+complex64 = ComplexType('complex64', nbits=64, **float32.kwargs(exclude=('name', 'nbits')))
+complex128 = ComplexType('complex128', nbits=128, **float64.kwargs(exclude=('name', 'nbits')))
+
+# Generic types (precision may be chosen by code printers):
+untyped = Type('untyped')
+real = FloatBaseType('real')
+integer = IntBaseType('integer')
+complex_ = ComplexBaseType('complex')
+bool_ = Type('bool')
+
+
+class Attribute(Token):
+    """ Attribute (possibly parametrized)
+
+    For use with :class:`sympy.codegen.ast.Node` (which takes instances of
+    ``Attribute`` as ``attrs``).
+
+    Parameters
+    ==========
+
+    name : str
+    parameters : Tuple
+
+    Examples
+    ========
+
+    >>> from sympy.codegen.ast import Attribute
+    >>> volatile = Attribute('volatile')
+    >>> volatile
+    volatile
+    >>> print(repr(volatile))
+    Attribute(String('volatile'))
+    >>> a = Attribute('foo', [1, 2, 3])
+    >>> a
+    foo(1, 2, 3)
+    >>> a.parameters == (1, 2, 3)
+    True
+    """
+    __slots__ = _fields = ('name', 'parameters')
+    defaults = {'parameters': Tuple()}
+
+    _construct_name = String
+    _construct_parameters = staticmethod(_mk_Tuple)
+
+    def _sympystr(self, printer, *args, **kwargs):
+        result = str(self.name)
+        if self.parameters:
+            result += '(%s)' % ', '.join((printer._print(
+                arg, *args, **kwargs) for arg in self.parameters))
+        return result
+
+value_const = Attribute('value_const')
+pointer_const = Attribute('pointer_const')
+
+
+class Variable(Node):
+    """ Represents a variable.
+
+    Parameters
+    ==========
+
+    symbol : Symbol
+    type : Type (optional)
+        Type of the variable.
+    attrs : iterable of Attribute instances
+        Will be stored as a Tuple.
+
+    Examples
+    ========
+
+    >>> from sympy import Symbol
+    >>> from sympy.codegen.ast import Variable, float32, integer
+    >>> x = Symbol('x')
+    >>> v = Variable(x, type=float32)
+    >>> v.attrs
+    ()
+    >>> v == Variable('x')
+    False
+    >>> v == Variable('x', type=float32)
+    True
+    >>> v
+    Variable(x, type=float32)
+
+    One may also construct a ``Variable`` instance with the type deduced from
+    assumptions about the symbol using the ``deduced`` classmethod:
+
+    >>> i = Symbol('i', integer=True)
+    >>> v = Variable.deduced(i)
+    >>> v.type == integer
+    True
+    >>> v == Variable('i')
+    False
+    >>> from sympy.codegen.ast import value_const
+    >>> value_const in v.attrs
+    False
+    >>> w = Variable('w', attrs=[value_const])
+    >>> w
+    Variable(w, attrs=(value_const,))
+    >>> value_const in w.attrs
+    True
+    >>> w.as_Declaration(value=42)
+    Declaration(Variable(w, value=42, attrs=(value_const,)))
+
+    """
+
+    __slots__ = ('symbol', 'type', 'value')
+    _fields = __slots__ + Node._fields
+
+    defaults = Node.defaults.copy()
+    defaults.update({'type': untyped, 'value': none})
+
+    _construct_symbol = staticmethod(sympify)
+    _construct_value = staticmethod(sympify)
+
+    @classmethod
+    def deduced(cls, symbol, value=None, attrs=Tuple(), cast_check=True):
+        """ Alt. constructor with type deduction from ``Type.from_expr``.
+
+        Deduces type primarily from ``symbol``, secondarily from ``value``.
+
+        Parameters
+        ==========
+
+        symbol : Symbol
+        value : expr
+            (optional) value of the variable.
+        attrs : iterable of Attribute instances
+        cast_check : bool
+            Whether to apply ``Type.cast_check`` on ``value``.
+
+        Examples
+        ========
+
+        >>> from sympy import Symbol
+        >>> from sympy.codegen.ast import Variable, complex_
+        >>> n = Symbol('n', integer=True)
+        >>> str(Variable.deduced(n).type)
+        'integer'
+        >>> x = Symbol('x', real=True)
+        >>> v = Variable.deduced(x)
+        >>> v.type
+        real
+        >>> z = Symbol('z', complex=True)
+        >>> Variable.deduced(z).type == complex_
+        True
+
+        """
+        if isinstance(symbol, Variable):
+            return symbol
+
+        try:
+            type_ = Type.from_expr(symbol)
+        except ValueError:
+            type_ = Type.from_expr(value)
+
+        if value is not None and cast_check:
+            value = type_.cast_check(value)
+        return cls(symbol, type=type_, value=value, attrs=attrs)
+
+    def as_Declaration(self, **kwargs):
+        """ Convenience method for creating a Declaration instance.
+
+        Explanation
+        ===========
+
+        If the variable of the Declaration need to wrap a modified
+        variable keyword arguments may be passed (overriding e.g.
+        the ``value`` of the Variable instance).
+
+        Examples
+        ========
+
+        >>> from sympy.codegen.ast import Variable, NoneToken
+        >>> x = Variable('x')
+        >>> decl1 = x.as_Declaration()
+        >>> # value is special NoneToken() which must be tested with == operator
+        >>> decl1.variable.value is None  # won't work
+        False
+        >>> decl1.variable.value == None  # not PEP-8 compliant
+        True
+        >>> decl1.variable.value == NoneToken()  # OK
+        True
+        >>> decl2 = x.as_Declaration(value=42.0)
+        >>> decl2.variable.value == 42.0
+        True
+
+        """
+        kw = self.kwargs()
+        kw.update(kwargs)
+        return Declaration(self.func(**kw))
+
+    def _relation(self, rhs, op):
+        try:
+            rhs = _sympify(rhs)
+        except SympifyError:
+            raise TypeError("Invalid comparison %s < %s" % (self, rhs))
+        return op(self, rhs, evaluate=False)
+
+    __lt__ = lambda self, other: self._relation(other, Lt)
+    __le__ = lambda self, other: self._relation(other, Le)
+    __ge__ = lambda self, other: self._relation(other, Ge)
+    __gt__ = lambda self, other: self._relation(other, Gt)
+
+class Pointer(Variable):
+    """ Represents a pointer. See ``Variable``.
+
+    Examples
+    ========
+
+    Can create instances of ``Element``:
+
+    >>> from sympy import Symbol
+    >>> from sympy.codegen.ast import Pointer
+    >>> i = Symbol('i', integer=True)
+    >>> p = Pointer('x')
+    >>> p[i+1]
+    Element(x, indices=(i + 1,))
+
+    """
+    __slots__ = ()
+
+    def __getitem__(self, key):
+        try:
+            return Element(self.symbol, key)
+        except TypeError:
+            return Element(self.symbol, (key,))
+
+
+class Element(Token):
+    """ Element in (a possibly N-dimensional) array.
+
+    Examples
+    ========
+
+    >>> from sympy.codegen.ast import Element
+    >>> elem = Element('x', 'ijk')
+    >>> elem.symbol.name == 'x'
+    True
+    >>> elem.indices
+    (i, j, k)
+    >>> from sympy import ccode
+    >>> ccode(elem)
+    'x[i][j][k]'
+    >>> ccode(Element('x', 'ijk', strides='lmn', offset='o'))
+    'x[i*l + j*m + k*n + o]'
+
+    """
+    __slots__ = _fields = ('symbol', 'indices', 'strides', 'offset')
+    defaults = {'strides': none, 'offset': none}
+    _construct_symbol = staticmethod(sympify)
+    _construct_indices = staticmethod(lambda arg: Tuple(*arg))
+    _construct_strides = staticmethod(lambda arg: Tuple(*arg))
+    _construct_offset = staticmethod(sympify)
+
+
+class Declaration(Token):
+    """ Represents a variable declaration
+
+    Parameters
+    ==========
+
+    variable : Variable
+
+    Examples
+    ========
+
+    >>> from sympy.codegen.ast import Declaration, NoneToken, untyped
+    >>> z = Declaration('z')
+    >>> z.variable.type == untyped
+    True
+    >>> # value is special NoneToken() which must be tested with == operator
+    >>> z.variable.value is None  # won't work
+    False
+    >>> z.variable.value == None  # not PEP-8 compliant
+    True
+    >>> z.variable.value == NoneToken()  # OK
+    True
+    """
+    __slots__ = _fields = ('variable',)
+    _construct_variable = Variable
+
+
+class While(Token):
+    """ Represents a 'for-loop' in the code.
+
+    Expressions are of the form:
+        "while condition:
+             body..."
+
+    Parameters
+    ==========
+
+    condition : expression convertible to Boolean
+    body : CodeBlock or iterable
+        When passed an iterable it is used to instantiate a CodeBlock.
+
+    Examples
+    ========
+
+    >>> from sympy import symbols, Gt, Abs
+    >>> from sympy.codegen import aug_assign, Assignment, While
+    >>> x, dx = symbols('x dx')
+    >>> expr = 1 - x**2
+    >>> whl = While(Gt(Abs(dx), 1e-9), [
+    ...     Assignment(dx, -expr/expr.diff(x)),
+    ...     aug_assign(x, '+', dx)
+    ... ])
+
+    """
+    __slots__ = _fields = ('condition', 'body')
+    _construct_condition = staticmethod(lambda cond: _sympify(cond))
+
+    @classmethod
+    def _construct_body(cls, itr):
+        if isinstance(itr, CodeBlock):
+            return itr
+        else:
+            return CodeBlock(*itr)
+
+
+class Scope(Token):
+    """ Represents a scope in the code.
+
+    Parameters
+    ==========
+
+    body : CodeBlock or iterable
+        When passed an iterable it is used to instantiate a CodeBlock.
+
+    """
+    __slots__ = _fields = ('body',)
+
+    @classmethod
+    def _construct_body(cls, itr):
+        if isinstance(itr, CodeBlock):
+            return itr
+        else:
+            return CodeBlock(*itr)
+
+
+class Stream(Token):
+    """ Represents a stream.
+
+    There are two predefined Stream instances ``stdout`` & ``stderr``.
+
+    Parameters
+    ==========
+
+    name : str
+
+    Examples
+    ========
+
+    >>> from sympy import pycode, Symbol
+    >>> from sympy.codegen.ast import Print, stderr, QuotedString
+    >>> print(pycode(Print(['x'], file=stderr)))
+    print(x, file=sys.stderr)
+    >>> x = Symbol('x')
+    >>> print(pycode(Print([QuotedString('x')], file=stderr)))  # print literally "x"
+    print("x", file=sys.stderr)
+
+    """
+    __slots__ = _fields = ('name',)
+    _construct_name = String
+
+stdout = Stream('stdout')
+stderr = Stream('stderr')
+
+
+class Print(Token):
+    r""" Represents print command in the code.
+
+    Parameters
+    ==========
+
+    formatstring : str
+    *args : Basic instances (or convertible to such through sympify)
+
+    Examples
+    ========
+
+    >>> from sympy.codegen.ast import Print
+    >>> from sympy import pycode
+    >>> print(pycode(Print('x y'.split(), "coordinate: %12.5g %12.5g\\n")))
+    print("coordinate: %12.5g %12.5g\n" % (x, y), end="")
+
+    """
+
+    __slots__ = _fields = ('print_args', 'format_string', 'file')
+    defaults = {'format_string': none, 'file': none}
+
+    _construct_print_args = staticmethod(_mk_Tuple)
+    _construct_format_string = QuotedString
+    _construct_file = Stream
+
+
+class FunctionPrototype(Node):
+    """ Represents a function prototype
+
+    Allows the user to generate forward declaration in e.g. C/C++.
+
+    Parameters
+    ==========
+
+    return_type : Type
+    name : str
+    parameters: iterable of Variable instances
+    attrs : iterable of Attribute instances
+
+    Examples
+    ========
+
+    >>> from sympy import ccode, symbols
+    >>> from sympy.codegen.ast import real, FunctionPrototype
+    >>> x, y = symbols('x y', real=True)
+    >>> fp = FunctionPrototype(real, 'foo', [x, y])
+    >>> ccode(fp)
+    'double foo(double x, double y)'
+
+    """
+
+    __slots__ = ('return_type', 'name', 'parameters')
+    _fields: tuple[str, ...] = __slots__ + Node._fields
+
+    _construct_return_type = Type
+    _construct_name = String
+
+    @staticmethod
+    def _construct_parameters(args):
+        def _var(arg):
+            if isinstance(arg, Declaration):
+                return arg.variable
+            elif isinstance(arg, Variable):
+                return arg
+            else:
+                return Variable.deduced(arg)
+        return Tuple(*map(_var, args))
+
+    @classmethod
+    def from_FunctionDefinition(cls, func_def):
+        if not isinstance(func_def, FunctionDefinition):
+            raise TypeError("func_def is not an instance of FunctionDefinition")
+        return cls(**func_def.kwargs(exclude=('body',)))
+
+
+class FunctionDefinition(FunctionPrototype):
+    """ Represents a function definition in the code.
+
+    Parameters
+    ==========
+
+    return_type : Type
+    name : str
+    parameters: iterable of Variable instances
+    body : CodeBlock or iterable
+    attrs : iterable of Attribute instances
+
+    Examples
+    ========
+
+    >>> from sympy import ccode, symbols
+    >>> from sympy.codegen.ast import real, FunctionPrototype
+    >>> x, y = symbols('x y', real=True)
+    >>> fp = FunctionPrototype(real, 'foo', [x, y])
+    >>> ccode(fp)
+    'double foo(double x, double y)'
+    >>> from sympy.codegen.ast import FunctionDefinition, Return
+    >>> body = [Return(x*y)]
+    >>> fd = FunctionDefinition.from_FunctionPrototype(fp, body)
+    >>> print(ccode(fd))
+    double foo(double x, double y){
+        return x*y;
+    }
+    """
+
+    __slots__ = ('body', )
+    _fields = FunctionPrototype._fields[:-1] + __slots__ + Node._fields
+
+    @classmethod
+    def _construct_body(cls, itr):
+        if isinstance(itr, CodeBlock):
+            return itr
+        else:
+            return CodeBlock(*itr)
+
+    @classmethod
+    def from_FunctionPrototype(cls, func_proto, body):
+        if not isinstance(func_proto, FunctionPrototype):
+            raise TypeError("func_proto is not an instance of FunctionPrototype")
+        return cls(body=body, **func_proto.kwargs())
+
+
+class Return(Token):
+    """ Represents a return command in the code.
+
+    Parameters
+    ==========
+
+    return : Basic
+
+    Examples
+    ========
+
+    >>> from sympy.codegen.ast import Return
+    >>> from sympy.printing.pycode import pycode
+    >>> from sympy import Symbol
+    >>> x = Symbol('x')
+    >>> print(pycode(Return(x)))
+    return x
+
+    """
+    __slots__ = _fields = ('return',)
+    _construct_return=staticmethod(_sympify)
+
+
+class FunctionCall(Token, Expr):
+    """ Represents a call to a function in the code.
+
+    Parameters
+    ==========
+
+    name : str
+    function_args : Tuple
+
+    Examples
+    ========
+
+    >>> from sympy.codegen.ast import FunctionCall
+    >>> from sympy import pycode
+    >>> fcall = FunctionCall('foo', 'bar baz'.split())
+    >>> print(pycode(fcall))
+    foo(bar, baz)
+
+    """
+    __slots__ = _fields = ('name', 'function_args')
+
+    _construct_name = String
+    _construct_function_args = staticmethod(lambda args: Tuple(*args))
+
+
+class Raise(Token):
+    """ Prints as 'raise ...' in Python, 'throw ...' in C++"""
+    __slots__ = _fields = ('exception',)
+
+
+class RuntimeError_(Token):
+    """ Represents 'std::runtime_error' in C++ and 'RuntimeError' in Python.
+
+    Note that the latter is uncommon, and you might want to use e.g. ValueError.
+    """
+    __slots__ = _fields = ('message',)
+    _construct_message = String

.venv/lib/python3.13/site-packages/sympy/codegen/cfunctions.py

@@ -0,0 +1,558 @@
+"""
+This module contains SymPy functions mathcin corresponding to special math functions in the
+C standard library (since C99, also available in C++11).
+
+The functions defined in this module allows the user to express functions such as ``expm1``
+as a SymPy function for symbolic manipulation.
+
+"""
+from sympy.core.function import ArgumentIndexError, Function
+from sympy.core.numbers import Rational
+from sympy.core.power import Pow
+from sympy.core.singleton import S
+from sympy.functions.elementary.exponential import exp, log
+from sympy.functions.elementary.miscellaneous import sqrt
+from sympy.logic.boolalg import BooleanFunction, true, false
+
+def _expm1(x):
+    return exp(x) - S.One
+
+
+class expm1(Function):
+    """
+    Represents the exponential function minus one.
+
+    Explanation
+    ===========
+
+    The benefit of using ``expm1(x)`` over ``exp(x) - 1``
+    is that the latter is prone to cancellation under finite precision
+    arithmetic when x is close to zero.
+
+    Examples
+    ========
+
+    >>> from sympy.abc import x
+    >>> from sympy.codegen.cfunctions import expm1
+    >>> '%.0e' % expm1(1e-99).evalf()
+    '1e-99'
+    >>> from math import exp
+    >>> exp(1e-99) - 1
+    0.0
+    >>> expm1(x).diff(x)
+    exp(x)
+
+    See Also
+    ========
+
+    log1p
+    """
+    nargs = 1
+
+    def fdiff(self, argindex=1):
+        """
+        Returns the first derivative of this function.
+        """
+        if argindex == 1:
+            return exp(*self.args)
+        else:
+            raise ArgumentIndexError(self, argindex)
+
+    def _eval_expand_func(self, **hints):
+        return _expm1(*self.args)
+
+    def _eval_rewrite_as_exp(self, arg, **kwargs):
+        return exp(arg) - S.One
+
+    _eval_rewrite_as_tractable = _eval_rewrite_as_exp
+
+    @classmethod
+    def eval(cls, arg):
+        exp_arg = exp.eval(arg)
+        if exp_arg is not None:
+            return exp_arg - S.One
+
+    def _eval_is_real(self):
+        return self.args[0].is_real
+
+    def _eval_is_finite(self):
+        return self.args[0].is_finite
+
+
+def _log1p(x):
+    return log(x + S.One)
+
+
+class log1p(Function):
+    """
+    Represents the natural logarithm of a number plus one.
+
+    Explanation
+    ===========
+
+    The benefit of using ``log1p(x)`` over ``log(x + 1)``
+    is that the latter is prone to cancellation under finite precision
+    arithmetic when x is close to zero.
+
+    Examples
+    ========
+
+    >>> from sympy.abc import x
+    >>> from sympy.codegen.cfunctions import log1p
+    >>> from sympy import expand_log
+    >>> '%.0e' % expand_log(log1p(1e-99)).evalf()
+    '1e-99'
+    >>> from math import log
+    >>> log(1 + 1e-99)
+    0.0
+    >>> log1p(x).diff(x)
+    1/(x + 1)
+
+    See Also
+    ========
+
+    expm1
+    """
+    nargs = 1
+
+
+    def fdiff(self, argindex=1):
+        """
+        Returns the first derivative of this function.
+        """
+        if argindex == 1:
+            return S.One/(self.args[0] + S.One)
+        else:
+            raise ArgumentIndexError(self, argindex)
+
+
+    def _eval_expand_func(self, **hints):
+        return _log1p(*self.args)
+
+    def _eval_rewrite_as_log(self, arg, **kwargs):
+        return _log1p(arg)
+
+    _eval_rewrite_as_tractable = _eval_rewrite_as_log
+
+    @classmethod
+    def eval(cls, arg):
+        if arg.is_Rational:
+            return log(arg + S.One)
+        elif not arg.is_Float:  # not safe to add 1 to Float
+            return log.eval(arg + S.One)
+        elif arg.is_number:
+            return log(Rational(arg) + S.One)
+
+    def _eval_is_real(self):
+        return (self.args[0] + S.One).is_nonnegative
+
+    def _eval_is_finite(self):
+        if (self.args[0] + S.One).is_zero:
+            return False
+        return self.args[0].is_finite
+
+    def _eval_is_positive(self):
+        return self.args[0].is_positive
+
+    def _eval_is_zero(self):
+        return self.args[0].is_zero
+
+    def _eval_is_nonnegative(self):
+        return self.args[0].is_nonnegative
+
+_Two = S(2)
+
+def _exp2(x):
+    return Pow(_Two, x)
+
+class exp2(Function):
+    """
+    Represents the exponential function with base two.
+
+    Explanation
+    ===========
+
+    The benefit of using ``exp2(x)`` over ``2**x``
+    is that the latter is not as efficient under finite precision
+    arithmetic.
+
+    Examples
+    ========
+
+    >>> from sympy.abc import x
+    >>> from sympy.codegen.cfunctions import exp2
+    >>> exp2(2).evalf() == 4.0
+    True
+    >>> exp2(x).diff(x)
+    log(2)*exp2(x)
+
+    See Also
+    ========
+
+    log2
+    """
+    nargs = 1
+
+
+    def fdiff(self, argindex=1):
+        """
+        Returns the first derivative of this function.
+        """
+        if argindex == 1:
+            return self*log(_Two)
+        else:
+            raise ArgumentIndexError(self, argindex)
+
+    def _eval_rewrite_as_Pow(self, arg, **kwargs):
+        return _exp2(arg)
+
+    _eval_rewrite_as_tractable = _eval_rewrite_as_Pow
+
+    def _eval_expand_func(self, **hints):
+        return _exp2(*self.args)
+
+    @classmethod
+    def eval(cls, arg):
+        if arg.is_number:
+            return _exp2(arg)
+
+
+def _log2(x):
+    return log(x)/log(_Two)
+
+
+class log2(Function):
+    """
+    Represents the logarithm function with base two.
+
+    Explanation
+    ===========
+
+    The benefit of using ``log2(x)`` over ``log(x)/log(2)``
+    is that the latter is not as efficient under finite precision
+    arithmetic.
+
+    Examples
+    ========
+
+    >>> from sympy.abc import x
+    >>> from sympy.codegen.cfunctions import log2
+    >>> log2(4).evalf() == 2.0
+    True
+    >>> log2(x).diff(x)
+    1/(x*log(2))
+
+    See Also
+    ========
+
+    exp2
+    log10
+    """
+    nargs = 1
+
+    def fdiff(self, argindex=1):
+        """
+        Returns the first derivative of this function.
+        """
+        if argindex == 1:
+            return S.One/(log(_Two)*self.args[0])
+        else:
+            raise ArgumentIndexError(self, argindex)
+
+
+    @classmethod
+    def eval(cls, arg):
+        if arg.is_number:
+            result = log.eval(arg, base=_Two)
+            if result.is_Atom:
+                return result
+        elif arg.is_Pow and arg.base == _Two:
+            return arg.exp
+
+    def _eval_evalf(self, *args, **kwargs):
+        return self.rewrite(log).evalf(*args, **kwargs)
+
+    def _eval_expand_func(self, **hints):
+        return _log2(*self.args)
+
+    def _eval_rewrite_as_log(self, arg, **kwargs):
+        return _log2(arg)
+
+    _eval_rewrite_as_tractable = _eval_rewrite_as_log
+
+
+def _fma(x, y, z):
+    return x*y + z
+
+
+class fma(Function):
+    """
+    Represents "fused multiply add".
+
+    Explanation
+    ===========
+
+    The benefit of using ``fma(x, y, z)`` over ``x*y + z``
+    is that, under finite precision arithmetic, the former is
+    supported by special instructions on some CPUs.
+
+    Examples
+    ========
+
+    >>> from sympy.abc import x, y, z
+    >>> from sympy.codegen.cfunctions import fma
+    >>> fma(x, y, z).diff(x)
+    y
+
+    """
+    nargs = 3
+
+    def fdiff(self, argindex=1):
+        """
+        Returns the first derivative of this function.
+        """
+        if argindex in (1, 2):
+            return self.args[2 - argindex]
+        elif argindex == 3:
+            return S.One
+        else:
+            raise ArgumentIndexError(self, argindex)
+
+
+    def _eval_expand_func(self, **hints):
+        return _fma(*self.args)
+
+    def _eval_rewrite_as_tractable(self, arg, limitvar=None, **kwargs):
+        return _fma(arg)
+
+
+_Ten = S(10)
+
+
+def _log10(x):
+    return log(x)/log(_Ten)
+
+
+class log10(Function):
+    """
+    Represents the logarithm function with base ten.
+
+    Examples
+    ========
+
+    >>> from sympy.abc import x
+    >>> from sympy.codegen.cfunctions import log10
+    >>> log10(100).evalf() == 2.0
+    True
+    >>> log10(x).diff(x)
+    1/(x*log(10))
+
+    See Also
+    ========
+
+    log2
+    """
+    nargs = 1
+
+    def fdiff(self, argindex=1):
+        """
+        Returns the first derivative of this function.
+        """
+        if argindex == 1:
+            return S.One/(log(_Ten)*self.args[0])
+        else:
+            raise ArgumentIndexError(self, argindex)
+
+
+    @classmethod
+    def eval(cls, arg):
+        if arg.is_number:
+            result = log.eval(arg, base=_Ten)
+            if result.is_Atom:
+                return result
+        elif arg.is_Pow and arg.base == _Ten:
+            return arg.exp
+
+    def _eval_expand_func(self, **hints):
+        return _log10(*self.args)
+
+    def _eval_rewrite_as_log(self, arg, **kwargs):
+        return _log10(arg)
+
+    _eval_rewrite_as_tractable = _eval_rewrite_as_log
+
+
+def _Sqrt(x):
+    return Pow(x, S.Half)
+
+
+class Sqrt(Function):  # 'sqrt' already defined in sympy.functions.elementary.miscellaneous
+    """
+    Represents the square root function.
+
+    Explanation
+    ===========
+
+    The reason why one would use ``Sqrt(x)`` over ``sqrt(x)``
+    is that the latter is internally represented as ``Pow(x, S.Half)`` which
+    may not be what one wants when doing code-generation.
+
+    Examples
+    ========
+
+    >>> from sympy.abc import x
+    >>> from sympy.codegen.cfunctions import Sqrt
+    >>> Sqrt(x)
+    Sqrt(x)
+    >>> Sqrt(x).diff(x)
+    1/(2*sqrt(x))
+
+    See Also
+    ========
+
+    Cbrt
+    """
+    nargs = 1
+
+    def fdiff(self, argindex=1):
+        """
+        Returns the first derivative of this function.
+        """
+        if argindex == 1:
+            return Pow(self.args[0], Rational(-1, 2))/_Two
+        else:
+            raise ArgumentIndexError(self, argindex)
+
+    def _eval_expand_func(self, **hints):
+        return _Sqrt(*self.args)
+
+    def _eval_rewrite_as_Pow(self, arg, **kwargs):
+        return _Sqrt(arg)
+
+    _eval_rewrite_as_tractable = _eval_rewrite_as_Pow
+
+
+def _Cbrt(x):
+    return Pow(x, Rational(1, 3))
+
+
+class Cbrt(Function):  # 'cbrt' already defined in sympy.functions.elementary.miscellaneous
+    """
+    Represents the cube root function.
+
+    Explanation
+    ===========
+
+    The reason why one would use ``Cbrt(x)`` over ``cbrt(x)``
+    is that the latter is internally represented as ``Pow(x, Rational(1, 3))`` which
+    may not be what one wants when doing code-generation.
+
+    Examples
+    ========
+
+    >>> from sympy.abc import x
+    >>> from sympy.codegen.cfunctions import Cbrt
+    >>> Cbrt(x)
+    Cbrt(x)
+    >>> Cbrt(x).diff(x)
+    1/(3*x**(2/3))
+
+    See Also
+    ========
+
+    Sqrt
+    """
+    nargs = 1
+
+    def fdiff(self, argindex=1):
+        """
+        Returns the first derivative of this function.
+        """
+        if argindex == 1:
+            return Pow(self.args[0], Rational(-_Two/3))/3
+        else:
+            raise ArgumentIndexError(self, argindex)
+
+
+    def _eval_expand_func(self, **hints):
+        return _Cbrt(*self.args)
+
+    def _eval_rewrite_as_Pow(self, arg, **kwargs):
+        return _Cbrt(arg)
+
+    _eval_rewrite_as_tractable = _eval_rewrite_as_Pow
+
+
+def _hypot(x, y):
+    return sqrt(Pow(x, 2) + Pow(y, 2))
+
+
+class hypot(Function):
+    """
+    Represents the hypotenuse function.
+
+    Explanation
+    ===========
+
+    The hypotenuse function is provided by e.g. the math library
+    in the C99 standard, hence one may want to represent the function
+    symbolically when doing code-generation.
+
+    Examples
+    ========
+
+    >>> from sympy.abc import x, y
+    >>> from sympy.codegen.cfunctions import hypot
+    >>> hypot(3, 4).evalf() == 5.0
+    True
+    >>> hypot(x, y)
+    hypot(x, y)
+    >>> hypot(x, y).diff(x)
+    x/hypot(x, y)
+
+    """
+    nargs = 2
+
+    def fdiff(self, argindex=1):
+        """
+        Returns the first derivative of this function.
+        """
+        if argindex in (1, 2):
+            return 2*self.args[argindex-1]/(_Two*self.func(*self.args))
+        else:
+            raise ArgumentIndexError(self, argindex)
+
+
+    def _eval_expand_func(self, **hints):
+        return _hypot(*self.args)
+
+    def _eval_rewrite_as_Pow(self, arg, **kwargs):
+        return _hypot(arg)
+
+    _eval_rewrite_as_tractable = _eval_rewrite_as_Pow
+
+
+class isnan(BooleanFunction):
+    nargs = 1
+
+    @classmethod
+    def eval(cls, arg):
+        if arg is S.NaN:
+            return true
+        elif arg.is_number:
+            return false
+        else:
+            return None
+
+
+class isinf(BooleanFunction):
+    nargs = 1
+
+    @classmethod
+    def eval(cls, arg):
+        if arg.is_infinite:
+            return true
+        elif arg.is_finite:
+            return false
+        else:
+            return None

.venv/lib/python3.13/site-packages/sympy/codegen/cnodes.py

@@ -0,0 +1,156 @@
+"""
+AST nodes specific to the C family of languages
+"""
+
+from sympy.codegen.ast import (
+    Attribute, Declaration, Node, String, Token, Type, none,
+    FunctionCall, CodeBlock
+    )
+from sympy.core.basic import Basic
+from sympy.core.containers import Tuple
+from sympy.core.sympify import sympify
+
+void = Type('void')
+
+restrict = Attribute('restrict')  # guarantees no pointer aliasing
+volatile = Attribute('volatile')
+static = Attribute('static')
+
+
+def alignof(arg):
+    """ Generate of FunctionCall instance for calling 'alignof' """
+    return FunctionCall('alignof', [String(arg) if isinstance(arg, str) else arg])
+
+
+def sizeof(arg):
+    """ Generate of FunctionCall instance for calling 'sizeof'
+
+    Examples
+    ========
+
+    >>> from sympy.codegen.ast import real
+    >>> from sympy.codegen.cnodes import sizeof
+    >>> from sympy import ccode
+    >>> ccode(sizeof(real))
+    'sizeof(double)'
+    """
+    return FunctionCall('sizeof', [String(arg) if isinstance(arg, str) else arg])
+
+
+class CommaOperator(Basic):
+    """ Represents the comma operator in C """
+    def __new__(cls, *args):
+        return Basic.__new__(cls, *[sympify(arg) for arg in args])
+
+
+class Label(Node):
+    """ Label for use with e.g. goto statement.
+
+    Examples
+    ========
+
+    >>> from sympy import ccode, Symbol
+    >>> from sympy.codegen.cnodes import Label, PreIncrement
+    >>> print(ccode(Label('foo')))
+    foo:
+    >>> print(ccode(Label('bar', [PreIncrement(Symbol('a'))])))
+    bar:
+    ++(a);
+
+    """
+    __slots__ = _fields = ('name', 'body')
+    defaults = {'body': none}
+    _construct_name = String
+
+    @classmethod
+    def _construct_body(cls, itr):
+        if isinstance(itr, CodeBlock):
+            return itr
+        else:
+            return CodeBlock(*itr)
+
+
+class goto(Token):
+    """ Represents goto in C """
+    __slots__ = _fields = ('label',)
+    _construct_label = Label
+
+
+class PreDecrement(Basic):
+    """ Represents the pre-decrement operator
+
+    Examples
+    ========
+
+    >>> from sympy.abc import x
+    >>> from sympy.codegen.cnodes import PreDecrement
+    >>> from sympy import ccode
+    >>> ccode(PreDecrement(x))
+    '--(x)'
+
+    """
+    nargs = 1
+
+
+class PostDecrement(Basic):
+    """ Represents the post-decrement operator
+
+    Examples
+    ========
+
+    >>> from sympy.abc import x
+    >>> from sympy.codegen.cnodes import PostDecrement
+    >>> from sympy import ccode
+    >>> ccode(PostDecrement(x))
+    '(x)--'
+
+    """
+    nargs = 1
+
+
+class PreIncrement(Basic):
+    """ Represents the pre-increment operator
+
+    Examples
+    ========
+
+    >>> from sympy.abc import x
+    >>> from sympy.codegen.cnodes import PreIncrement
+    >>> from sympy import ccode
+    >>> ccode(PreIncrement(x))
+    '++(x)'
+
+    """
+    nargs = 1
+
+
+class PostIncrement(Basic):
+    """ Represents the post-increment operator
+
+    Examples
+    ========
+
+    >>> from sympy.abc import x
+    >>> from sympy.codegen.cnodes import PostIncrement
+    >>> from sympy import ccode
+    >>> ccode(PostIncrement(x))
+    '(x)++'
+
+    """
+    nargs = 1
+
+
+class struct(Node):
+    """ Represents a struct in C """
+    __slots__ = _fields = ('name', 'declarations')
+    defaults = {'name': none}
+    _construct_name = String
+
+    @classmethod
+    def _construct_declarations(cls, args):
+        return Tuple(*[Declaration(arg) for arg in args])
+
+
+class union(struct):
+    """ Represents a union in C """
+    __slots__ = ()

.venv/lib/python3.13/site-packages/sympy/codegen/cutils.py

@@ -0,0 +1,8 @@
+from sympy.printing.c import C99CodePrinter
+
+def render_as_source_file(content, Printer=C99CodePrinter, settings=None):
+    """ Renders a C source file (with required #include statements) """
+    printer = Printer(settings or {})
+    code_str = printer.doprint(content)
+    includes = '\n'.join(['#include <%s>' % h for h in printer.headers])
+    return includes + '\n\n' + code_str

.venv/lib/python3.13/site-packages/sympy/codegen/cxxnodes.py

@@ -0,0 +1,14 @@
+"""
+AST nodes specific to C++.
+"""
+
+from sympy.codegen.ast import Attribute, String, Token, Type, none
+
+class using(Token):
+    """ Represents a 'using' statement in C++ """
+    __slots__ = _fields = ('type', 'alias')
+    defaults = {'alias': none}
+    _construct_type = Type
+    _construct_alias = String
+
+constexpr = Attribute('constexpr')

.venv/lib/python3.13/site-packages/sympy/codegen/fnodes.py

@@ -0,0 +1,658 @@
+"""
+AST nodes specific to Fortran.
+
+The functions defined in this module allows the user to express functions such as ``dsign``
+as a SymPy function for symbolic manipulation.
+"""
+
+from __future__ import annotations
+from sympy.codegen.ast import (
+    Attribute, CodeBlock, FunctionCall, Node, none, String,
+    Token, _mk_Tuple, Variable
+)
+from sympy.core.basic import Basic
+from sympy.core.containers import Tuple
+from sympy.core.expr import Expr
+from sympy.core.function import Function
+from sympy.core.numbers import Float, Integer
+from sympy.core.symbol import Str
+from sympy.core.sympify import sympify
+from sympy.logic import true, false
+from sympy.utilities.iterables import iterable
+
+
+
+pure = Attribute('pure')
+elemental = Attribute('elemental')  # (all elemental procedures are also pure)
+
+intent_in = Attribute('intent_in')
+intent_out = Attribute('intent_out')
+intent_inout = Attribute('intent_inout')
+
+allocatable = Attribute('allocatable')
+
+class Program(Token):
+    """ Represents a 'program' block in Fortran.
+
+    Examples
+    ========
+
+    >>> from sympy.codegen.ast import Print
+    >>> from sympy.codegen.fnodes import Program
+    >>> prog = Program('myprogram', [Print([42])])
+    >>> from sympy import fcode
+    >>> print(fcode(prog, source_format='free'))
+    program myprogram
+        print *, 42
+    end program
+
+    """
+    __slots__ = _fields = ('name', 'body')
+    _construct_name = String
+    _construct_body = staticmethod(lambda body: CodeBlock(*body))
+
+
+class use_rename(Token):
+    """ Represents a renaming in a use statement in Fortran.
+
+    Examples
+    ========
+
+    >>> from sympy.codegen.fnodes import use_rename, use
+    >>> from sympy import fcode
+    >>> ren = use_rename("thingy", "convolution2d")
+    >>> print(fcode(ren, source_format='free'))
+    thingy => convolution2d
+    >>> full = use('signallib', only=['snr', ren])
+    >>> print(fcode(full, source_format='free'))
+    use signallib, only: snr, thingy => convolution2d
+
+    """
+    __slots__ = _fields = ('local', 'original')
+    _construct_local = String
+    _construct_original = String
+
+def _name(arg):
+    if hasattr(arg, 'name'):
+        return arg.name
+    else:
+        return String(arg)
+
+class use(Token):
+    """ Represents a use statement in Fortran.
+
+    Examples
+    ========
+
+    >>> from sympy.codegen.fnodes import use
+    >>> from sympy import fcode
+    >>> fcode(use('signallib'), source_format='free')
+    'use signallib'
+    >>> fcode(use('signallib', [('metric', 'snr')]), source_format='free')
+    'use signallib, metric => snr'
+    >>> fcode(use('signallib', only=['snr', 'convolution2d']), source_format='free')
+    'use signallib, only: snr, convolution2d'
+
+    """
+    __slots__ = _fields = ('namespace', 'rename', 'only')
+    defaults = {'rename': none, 'only': none}
+    _construct_namespace = staticmethod(_name)
+    _construct_rename = staticmethod(lambda args: Tuple(*[arg if isinstance(arg, use_rename) else use_rename(*arg) for arg in args]))
+    _construct_only = staticmethod(lambda args: Tuple(*[arg if isinstance(arg, use_rename) else _name(arg) for arg in args]))
+
+
+class Module(Token):
+    """ Represents a module in Fortran.
+
+    Examples
+    ========
+
+    >>> from sympy.codegen.fnodes import Module
+    >>> from sympy import fcode
+    >>> print(fcode(Module('signallib', ['implicit none'], []), source_format='free'))
+    module signallib
+    implicit none
+    <BLANKLINE>
+    contains
+    <BLANKLINE>
+    <BLANKLINE>
+    end module
+
+    """
+    __slots__ = _fields = ('name', 'declarations', 'definitions')
+    defaults = {'declarations': Tuple()}
+    _construct_name = String
+
+    @classmethod
+    def _construct_declarations(cls, args):
+        args = [Str(arg) if isinstance(arg, str) else arg for arg in args]
+        return CodeBlock(*args)
+
+    _construct_definitions = staticmethod(lambda arg: CodeBlock(*arg))
+
+
+class Subroutine(Node):
+    """ Represents a subroutine in Fortran.
+
+    Examples
+    ========
+
+    >>> from sympy import fcode, symbols
+    >>> from sympy.codegen.ast import Print
+    >>> from sympy.codegen.fnodes import Subroutine
+    >>> x, y = symbols('x y', real=True)
+    >>> sub = Subroutine('mysub', [x, y], [Print([x**2 + y**2, x*y])])
+    >>> print(fcode(sub, source_format='free', standard=2003))
+    subroutine mysub(x, y)
+    real*8 :: x
+    real*8 :: y
+    print *, x**2 + y**2, x*y
+    end subroutine
+
+    """
+    __slots__ = ('name', 'parameters', 'body')
+    _fields = __slots__ + Node._fields
+    _construct_name = String
+    _construct_parameters = staticmethod(lambda params: Tuple(*map(Variable.deduced, params)))
+
+    @classmethod
+    def _construct_body(cls, itr):
+        if isinstance(itr, CodeBlock):
+            return itr
+        else:
+            return CodeBlock(*itr)
+
+class SubroutineCall(Token):
+    """ Represents a call to a subroutine in Fortran.
+
+    Examples
+    ========
+
+    >>> from sympy.codegen.fnodes import SubroutineCall
+    >>> from sympy import fcode
+    >>> fcode(SubroutineCall('mysub', 'x y'.split()))
+    '       call mysub(x, y)'
+
+    """
+    __slots__ = _fields = ('name', 'subroutine_args')
+    _construct_name = staticmethod(_name)
+    _construct_subroutine_args = staticmethod(_mk_Tuple)
+
+
+class Do(Token):
+    """ Represents a Do loop in in Fortran.
+
+    Examples
+    ========
+
+    >>> from sympy import fcode, symbols
+    >>> from sympy.codegen.ast import aug_assign, Print
+    >>> from sympy.codegen.fnodes import Do
+    >>> i, n = symbols('i n', integer=True)
+    >>> r = symbols('r', real=True)
+    >>> body = [aug_assign(r, '+', 1/i), Print([i, r])]
+    >>> do1 = Do(body, i, 1, n)
+    >>> print(fcode(do1, source_format='free'))
+    do i = 1, n
+        r = r + 1d0/i
+        print *, i, r
+    end do
+    >>> do2 = Do(body, i, 1, n, 2)
+    >>> print(fcode(do2, source_format='free'))
+    do i = 1, n, 2
+        r = r + 1d0/i
+        print *, i, r
+    end do
+
+    """
+
+    __slots__ = _fields = ('body', 'counter', 'first', 'last', 'step', 'concurrent')
+    defaults = {'step': Integer(1), 'concurrent': false}
+    _construct_body = staticmethod(lambda body: CodeBlock(*body))
+    _construct_counter = staticmethod(sympify)
+    _construct_first = staticmethod(sympify)
+    _construct_last = staticmethod(sympify)
+    _construct_step = staticmethod(sympify)
+    _construct_concurrent = staticmethod(lambda arg: true if arg else false)
+
+
+class ArrayConstructor(Token):
+    """ Represents an array constructor.
+
+    Examples
+    ========
+
+    >>> from sympy import fcode
+    >>> from sympy.codegen.fnodes import ArrayConstructor
+    >>> ac = ArrayConstructor([1, 2, 3])
+    >>> fcode(ac, standard=95, source_format='free')
+    '(/1, 2, 3/)'
+    >>> fcode(ac, standard=2003, source_format='free')
+    '[1, 2, 3]'
+
+    """
+    __slots__ = _fields = ('elements',)
+    _construct_elements = staticmethod(_mk_Tuple)
+
+
+class ImpliedDoLoop(Token):
+    """ Represents an implied do loop in Fortran.
+
+    Examples
+    ========
+
+    >>> from sympy import Symbol, fcode
+    >>> from sympy.codegen.fnodes import ImpliedDoLoop, ArrayConstructor
+    >>> i = Symbol('i', integer=True)
+    >>> idl = ImpliedDoLoop(i**3, i, -3, 3, 2)  # -27, -1, 1, 27
+    >>> ac = ArrayConstructor([-28, idl, 28]) # -28, -27, -1, 1, 27, 28
+    >>> fcode(ac, standard=2003, source_format='free')
+    '[-28, (i**3, i = -3, 3, 2), 28]'
+
+    """
+    __slots__ = _fields = ('expr', 'counter', 'first', 'last', 'step')
+    defaults = {'step': Integer(1)}
+    _construct_expr = staticmethod(sympify)
+    _construct_counter = staticmethod(sympify)
+    _construct_first = staticmethod(sympify)
+    _construct_last = staticmethod(sympify)
+    _construct_step = staticmethod(sympify)
+
+
+class Extent(Basic):
+    """ Represents a dimension extent.
+
+    Examples
+    ========
+
+    >>> from sympy.codegen.fnodes import Extent
+    >>> e = Extent(-3, 3)  # -3, -2, -1, 0, 1, 2, 3
+    >>> from sympy import fcode
+    >>> fcode(e, source_format='free')
+    '-3:3'
+    >>> from sympy.codegen.ast import Variable, real
+    >>> from sympy.codegen.fnodes import dimension, intent_out
+    >>> dim = dimension(e, e)
+    >>> arr = Variable('x', real, attrs=[dim, intent_out])
+    >>> fcode(arr.as_Declaration(), source_format='free', standard=2003)
+    'real*8, dimension(-3:3, -3:3), intent(out) :: x'
+
+    """
+    def __new__(cls, *args):
+        if len(args) == 2:
+            low, high = args
+            return Basic.__new__(cls, sympify(low), sympify(high))
+        elif len(args) == 0 or (len(args) == 1 and args[0] in (':', None)):
+            return Basic.__new__(cls)  # assumed shape
+        else:
+            raise ValueError("Expected 0 or 2 args (or one argument == None or ':')")
+
+    def _sympystr(self, printer):
+        if len(self.args) == 0:
+            return ':'
+        return ":".join(str(arg) for arg in self.args)
+
+assumed_extent = Extent() # or Extent(':'), Extent(None)
+
+
+def dimension(*args):
+    """ Creates a 'dimension' Attribute with (up to 7) extents.
+
+    Examples
+    ========
+
+    >>> from sympy import fcode
+    >>> from sympy.codegen.fnodes import dimension, intent_in
+    >>> dim = dimension('2', ':')  # 2 rows, runtime determined number of columns
+    >>> from sympy.codegen.ast import Variable, integer
+    >>> arr = Variable('a', integer, attrs=[dim, intent_in])
+    >>> fcode(arr.as_Declaration(), source_format='free', standard=2003)
+    'integer*4, dimension(2, :), intent(in) :: a'
+
+    """
+    if len(args) > 7:
+        raise ValueError("Fortran only supports up to 7 dimensional arrays")
+    parameters = []
+    for arg in args:
+        if isinstance(arg, Extent):
+            parameters.append(arg)
+        elif isinstance(arg, str):
+            if arg == ':':
+                parameters.append(Extent())
+            else:
+                parameters.append(String(arg))
+        elif iterable(arg):
+            parameters.append(Extent(*arg))
+        else:
+            parameters.append(sympify(arg))
+    if len(args) == 0:
+        raise ValueError("Need at least one dimension")
+    return Attribute('dimension', parameters)
+
+
+assumed_size = dimension('*')
+
+def array(symbol, dim, intent=None, *, attrs=(), value=None, type=None):
+    """ Convenience function for creating a Variable instance for a Fortran array.
+
+    Parameters
+    ==========
+
+    symbol : symbol
+    dim : Attribute or iterable
+        If dim is an ``Attribute`` it need to have the name 'dimension'. If it is
+        not an ``Attribute``, then it is passed to :func:`dimension` as ``*dim``
+    intent : str
+        One of: 'in', 'out', 'inout' or None
+    \\*\\*kwargs:
+        Keyword arguments for ``Variable`` ('type' & 'value')
+
+    Examples
+    ========
+
+    >>> from sympy import fcode
+    >>> from sympy.codegen.ast import integer, real
+    >>> from sympy.codegen.fnodes import array
+    >>> arr = array('a', '*', 'in', type=integer)
+    >>> print(fcode(arr.as_Declaration(), source_format='free', standard=2003))
+    integer*4, dimension(*), intent(in) :: a
+    >>> x = array('x', [3, ':', ':'], intent='out', type=real)
+    >>> print(fcode(x.as_Declaration(value=1), source_format='free', standard=2003))
+    real*8, dimension(3, :, :), intent(out) :: x = 1
+
+    """
+    if isinstance(dim, Attribute):
+        if str(dim.name) != 'dimension':
+            raise ValueError("Got an unexpected Attribute argument as dim: %s" % str(dim))
+    else:
+        dim = dimension(*dim)
+
+    attrs = list(attrs) + [dim]
+    if intent is not None:
+        if intent not in (intent_in, intent_out, intent_inout):
+            intent = {'in': intent_in, 'out': intent_out, 'inout': intent_inout}[intent]
+        attrs.append(intent)
+    if type is None:
+        return Variable.deduced(symbol, value=value, attrs=attrs)
+    else:
+        return Variable(symbol, type, value=value, attrs=attrs)
+
+def _printable(arg):
+    return String(arg) if isinstance(arg, str) else sympify(arg)
+
+
+def allocated(array):
+    """ Creates an AST node for a function call to Fortran's "allocated(...)"
+
+    Examples
+    ========
+
+    >>> from sympy import fcode
+    >>> from sympy.codegen.fnodes import allocated
+    >>> alloc = allocated('x')
+    >>> fcode(alloc, source_format='free')
+    'allocated(x)'
+
+    """
+    return FunctionCall('allocated', [_printable(array)])
+
+
+def lbound(array, dim=None, kind=None):
+    """ Creates an AST node for a function call to Fortran's "lbound(...)"
+
+    Parameters
+    ==========
+
+    array : Symbol or String
+    dim : expr
+    kind : expr
+
+    Examples
+    ========
+
+    >>> from sympy import fcode
+    >>> from sympy.codegen.fnodes import lbound
+    >>> lb = lbound('arr', dim=2)
+    >>> fcode(lb, source_format='free')
+    'lbound(arr, 2)'
+
+    """
+    return FunctionCall(
+        'lbound',
+        [_printable(array)] +
+        ([_printable(dim)] if dim else []) +
+        ([_printable(kind)] if kind else [])
+    )
+
+
+def ubound(array, dim=None, kind=None):
+    return FunctionCall(
+        'ubound',
+        [_printable(array)] +
+        ([_printable(dim)] if dim else []) +
+        ([_printable(kind)] if kind else [])
+    )
+
+
+def shape(source, kind=None):
+    """ Creates an AST node for a function call to Fortran's "shape(...)"
+
+    Parameters
+    ==========
+
+    source : Symbol or String
+    kind : expr
+
+    Examples
+    ========
+
+    >>> from sympy import fcode
+    >>> from sympy.codegen.fnodes import shape
+    >>> shp = shape('x')
+    >>> fcode(shp, source_format='free')
+    'shape(x)'
+
+    """
+    return FunctionCall(
+        'shape',
+        [_printable(source)] +
+        ([_printable(kind)] if kind else [])
+    )
+
+
+def size(array, dim=None, kind=None):
+    """ Creates an AST node for a function call to Fortran's "size(...)"
+
+    Examples
+    ========
+
+    >>> from sympy import fcode, Symbol
+    >>> from sympy.codegen.ast import FunctionDefinition, real, Return
+    >>> from sympy.codegen.fnodes import array, sum_, size
+    >>> a = Symbol('a', real=True)
+    >>> body = [Return((sum_(a**2)/size(a))**.5)]
+    >>> arr = array(a, dim=[':'], intent='in')
+    >>> fd = FunctionDefinition(real, 'rms', [arr], body)
+    >>> print(fcode(fd, source_format='free', standard=2003))
+    real*8 function rms(a)
+    real*8, dimension(:), intent(in) :: a
+    rms = sqrt(sum(a**2)*1d0/size(a))
+    end function
+
+    """
+    return FunctionCall(
+        'size',
+        [_printable(array)] +
+        ([_printable(dim)] if dim else []) +
+        ([_printable(kind)] if kind else [])
+    )
+
+
+def reshape(source, shape, pad=None, order=None):
+    """ Creates an AST node for a function call to Fortran's "reshape(...)"
+
+    Parameters
+    ==========
+
+    source : Symbol or String
+    shape : ArrayExpr
+
+    """
+    return FunctionCall(
+        'reshape',
+        [_printable(source), _printable(shape)] +
+        ([_printable(pad)] if pad else []) +
+        ([_printable(order)] if pad else [])
+    )
+
+
+def bind_C(name=None):
+    """ Creates an Attribute ``bind_C`` with a name.
+
+    Parameters
+    ==========
+
+    name : str
+
+    Examples
+    ========
+
+    >>> from sympy import fcode, Symbol
+    >>> from sympy.codegen.ast import FunctionDefinition, real, Return
+    >>> from sympy.codegen.fnodes import array, sum_, bind_C
+    >>> a = Symbol('a', real=True)
+    >>> s = Symbol('s', integer=True)
+    >>> arr = array(a, dim=[s], intent='in')
+    >>> body = [Return((sum_(a**2)/s)**.5)]
+    >>> fd = FunctionDefinition(real, 'rms', [arr, s], body, attrs=[bind_C('rms')])
+    >>> print(fcode(fd, source_format='free', standard=2003))
+    real*8 function rms(a, s) bind(C, name="rms")
+    real*8, dimension(s), intent(in) :: a
+    integer*4 :: s
+    rms = sqrt(sum(a**2)/s)
+    end function
+
+    """
+    return Attribute('bind_C', [String(name)] if name else [])
+
+class GoTo(Token):
+    """ Represents a goto statement in Fortran
+
+    Examples
+    ========
+
+    >>> from sympy.codegen.fnodes import GoTo
+    >>> go = GoTo([10, 20, 30], 'i')
+    >>> from sympy import fcode
+    >>> fcode(go, source_format='free')
+    'go to (10, 20, 30), i'
+
+    """
+    __slots__ = _fields = ('labels', 'expr')
+    defaults = {'expr': none}
+    _construct_labels = staticmethod(_mk_Tuple)
+    _construct_expr = staticmethod(sympify)
+
+
+class FortranReturn(Token):
+    """ AST node explicitly mapped to a fortran "return".
+
+    Explanation
+    ===========
+
+    Because a return statement in fortran is different from C, and
+    in order to aid reuse of our codegen ASTs the ordinary
+    ``.codegen.ast.Return`` is interpreted as assignment to
+    the result variable of the function. If one for some reason needs
+    to generate a fortran RETURN statement, this node should be used.
+
+    Examples
+    ========
+
+    >>> from sympy.codegen.fnodes import FortranReturn
+    >>> from sympy import fcode
+    >>> fcode(FortranReturn('x'))
+    '       return x'
+
+    """
+    __slots__ = _fields = ('return_value',)
+    defaults = {'return_value': none}
+    _construct_return_value = staticmethod(sympify)
+
+
+class FFunction(Function):
+    _required_standard = 77
+
+    def _fcode(self, printer):
+        name = self.__class__.__name__
+        if printer._settings['standard'] < self._required_standard:
+            raise NotImplementedError("%s requires Fortran %d or newer" %
+                                      (name, self._required_standard))
+        return '{}({})'.format(name, ', '.join(map(printer._print, self.args)))
+
+
+class F95Function(FFunction):
+    _required_standard = 95
+
+
+class isign(FFunction):
+    """ Fortran sign intrinsic for integer arguments. """
+    nargs = 2
+
+
+class dsign(FFunction):
+    """ Fortran sign intrinsic for double precision arguments. """
+    nargs = 2
+
+
+class cmplx(FFunction):
+    """ Fortran complex conversion function. """
+    nargs = 2  # may be extended to (2, 3) at a later point
+
+
+class kind(FFunction):
+    """ Fortran kind function. """
+    nargs = 1
+
+
+class merge(F95Function):
+    """ Fortran merge function """
+    nargs = 3
+
+
+class _literal(Float):
+    _token: str
+    _decimals: int
+
+    def _fcode(self, printer, *args, **kwargs):
+        mantissa, sgnd_ex = ('%.{}e'.format(self._decimals) % self).split('e')
+        mantissa = mantissa.strip('0').rstrip('.')
+        ex_sgn, ex_num = sgnd_ex[0], sgnd_ex[1:].lstrip('0')
+        ex_sgn = '' if ex_sgn == '+' else ex_sgn
+        return (mantissa or '0') + self._token + ex_sgn + (ex_num or '0')
+
+
+class literal_sp(_literal):
+    """ Fortran single precision real literal """
+    _token = 'e'
+    _decimals = 9
+
+
+class literal_dp(_literal):
+    """ Fortran double precision real literal """
+    _token = 'd'
+    _decimals = 17
+
+
+class sum_(Token, Expr):
+    __slots__ = _fields = ('array', 'dim', 'mask')
+    defaults = {'dim': none, 'mask': none}
+    _construct_array = staticmethod(sympify)
+    _construct_dim = staticmethod(sympify)
+
+
+class product_(Token, Expr):
+    __slots__ = _fields = ('array', 'dim', 'mask')
+    defaults = {'dim': none, 'mask': none}
+    _construct_array = staticmethod(sympify)
+    _construct_dim = staticmethod(sympify)

.venv/lib/python3.13/site-packages/sympy/codegen/futils.py

@@ -0,0 +1,40 @@
+from itertools import chain
+from sympy.codegen.fnodes import Module
+from sympy.core.symbol import Dummy
+from sympy.printing.fortran import FCodePrinter
+
+""" This module collects utilities for rendering Fortran code. """
+
+
+def render_as_module(definitions, name, declarations=(), printer_settings=None):
+    """ Creates a ``Module`` instance and renders it as a string.
+
+    This generates Fortran source code for a module with the correct ``use`` statements.
+
+    Parameters
+    ==========
+
+    definitions : iterable
+        Passed to :class:`sympy.codegen.fnodes.Module`.
+    name : str
+        Passed to :class:`sympy.codegen.fnodes.Module`.
+    declarations : iterable
+        Passed to :class:`sympy.codegen.fnodes.Module`. It will be extended with
+        use statements, 'implicit none' and public list generated from ``definitions``.
+    printer_settings : dict
+        Passed to ``FCodePrinter`` (default: ``{'standard': 2003, 'source_format': 'free'}``).
+
+    """
+    printer_settings = printer_settings or {'standard': 2003, 'source_format': 'free'}
+    printer = FCodePrinter(printer_settings)
+    dummy = Dummy()
+    if isinstance(definitions, Module):
+        raise ValueError("This function expects to construct a module on its own.")
+    mod = Module(name, chain(declarations, [dummy]), definitions)
+    fstr = printer.doprint(mod)
+    module_use_str = '   %s\n' % '   \n'.join(['use %s, only: %s' % (k, ', '.join(v)) for
+                                                k, v in printer.module_uses.items()])
+    module_use_str += '   implicit none\n'
+    module_use_str += '   private\n'
+    module_use_str += '   public %s\n' % ', '.join([str(node.name) for node in definitions if getattr(node, 'name', None)])
+    return fstr.replace(printer.doprint(dummy), module_use_str)

.venv/lib/python3.13/site-packages/sympy/codegen/matrix_nodes.py

@@ -0,0 +1,71 @@
+"""
+Additional AST nodes for operations on matrices. The nodes in this module
+are meant to represent optimization of matrix expressions within codegen's
+target languages that cannot be represented by SymPy expressions.
+
+As an example, we can use :meth:`sympy.codegen.rewriting.optimize` and the
+``matin_opt`` optimization provided in :mod:`sympy.codegen.rewriting` to
+transform matrix multiplication under certain assumptions:
+
+    >>> from sympy import symbols, MatrixSymbol
+    >>> n = symbols('n', integer=True)
+    >>> A = MatrixSymbol('A', n, n)
+    >>> x = MatrixSymbol('x', n, 1)
+    >>> expr = A**(-1) * x
+    >>> from sympy import assuming, Q
+    >>> from sympy.codegen.rewriting import matinv_opt, optimize
+    >>> with assuming(Q.fullrank(A)):
+    ...     optimize(expr, [matinv_opt])
+    MatrixSolve(A, vector=x)
+"""
+
+from .ast import Token
+from sympy.matrices import MatrixExpr
+from sympy.core.sympify import sympify
+
+
+class MatrixSolve(Token, MatrixExpr):
+    """Represents an operation to solve a linear matrix equation.
+
+    Parameters
+    ==========
+
+    matrix : MatrixSymbol
+
+      Matrix representing the coefficients of variables in the linear
+      equation. This matrix must be square and full-rank (i.e. all columns must
+      be linearly independent) for the solving operation to be valid.
+
+    vector : MatrixSymbol
+
+      One-column matrix representing the solutions to the equations
+      represented in ``matrix``.
+
+    Examples
+    ========
+
+    >>> from sympy import symbols, MatrixSymbol
+    >>> from sympy.codegen.matrix_nodes import MatrixSolve
+    >>> n = symbols('n', integer=True)
+    >>> A = MatrixSymbol('A', n, n)
+    >>> x = MatrixSymbol('x', n, 1)
+    >>> from sympy.printing.numpy import NumPyPrinter
+    >>> NumPyPrinter().doprint(MatrixSolve(A, x))
+    'numpy.linalg.solve(A, x)'
+    >>> from sympy import octave_code
+    >>> octave_code(MatrixSolve(A, x))
+    'A \\\\ x'
+
+    """
+    __slots__ = _fields = ('matrix', 'vector')
+
+    _construct_matrix = staticmethod(sympify)
+    _construct_vector = staticmethod(sympify)
+
+    @property
+    def shape(self):
+        return self.vector.shape
+
+    def _eval_derivative(self, x):
+        A, b = self.matrix, self.vector
+        return MatrixSolve(A, b.diff(x) - A.diff(x) * MatrixSolve(A, b))

.venv/lib/python3.13/site-packages/sympy/codegen/numpy_nodes.py

@@ -0,0 +1,177 @@
+from sympy.core.function import Add, ArgumentIndexError, Function
+from sympy.core.power import Pow
+from sympy.core.singleton import S
+from sympy.core.sorting import default_sort_key
+from sympy.core.sympify import sympify
+from sympy.functions.elementary.exponential import exp, log
+from sympy.functions.elementary.miscellaneous import Max, Min
+from .ast import Token, none
+
+
+def _logaddexp(x1, x2, *, evaluate=True):
+    return log(Add(exp(x1, evaluate=evaluate), exp(x2, evaluate=evaluate), evaluate=evaluate))
+
+
+_two = S.One*2
+_ln2 = log(_two)
+
+
+def _lb(x, *, evaluate=True):
+    return log(x, evaluate=evaluate)/_ln2
+
+
+def _exp2(x, *, evaluate=True):
+    return Pow(_two, x, evaluate=evaluate)
+
+
+def _logaddexp2(x1, x2, *, evaluate=True):
+    return _lb(Add(_exp2(x1, evaluate=evaluate),
+                   _exp2(x2, evaluate=evaluate), evaluate=evaluate))
+
+
+class logaddexp(Function):
+    """ Logarithm of the sum of exponentiations of the inputs.
+
+    Helper class for use with e.g. numpy.logaddexp
+
+    See Also
+    ========
+
+    https://numpy.org/doc/stable/reference/generated/numpy.logaddexp.html
+    """
+    nargs = 2
+
+    def __new__(cls, *args):
+        return Function.__new__(cls, *sorted(args, key=default_sort_key))
+
+    def fdiff(self, argindex=1):
+        """
+        Returns the first derivative of this function.
+        """
+        if argindex == 1:
+            wrt, other = self.args
+        elif argindex == 2:
+            other, wrt = self.args
+        else:
+            raise ArgumentIndexError(self, argindex)
+        return S.One/(S.One + exp(other-wrt))
+
+    def _eval_rewrite_as_log(self, x1, x2, **kwargs):
+        return _logaddexp(x1, x2)
+
+    def _eval_evalf(self, *args, **kwargs):
+        return self.rewrite(log).evalf(*args, **kwargs)
+
+    def _eval_simplify(self, *args, **kwargs):
+        a, b = (x.simplify(**kwargs) for x in self.args)
+        candidate = _logaddexp(a, b)
+        if candidate != _logaddexp(a, b, evaluate=False):
+            return candidate
+        else:
+            return logaddexp(a, b)
+
+
+class logaddexp2(Function):
+    """ Logarithm of the sum of exponentiations of the inputs in base-2.
+
+    Helper class for use with e.g. numpy.logaddexp2
+
+    See Also
+    ========
+
+    https://numpy.org/doc/stable/reference/generated/numpy.logaddexp2.html
+    """
+    nargs = 2
+
+    def __new__(cls, *args):
+        return Function.__new__(cls, *sorted(args, key=default_sort_key))
+
+    def fdiff(self, argindex=1):
+        """
+        Returns the first derivative of this function.
+        """
+        if argindex == 1:
+            wrt, other = self.args
+        elif argindex == 2:
+            other, wrt = self.args
+        else:
+            raise ArgumentIndexError(self, argindex)
+        return S.One/(S.One + _exp2(other-wrt))
+
+    def _eval_rewrite_as_log(self, x1, x2, **kwargs):
+        return _logaddexp2(x1, x2)
+
+    def _eval_evalf(self, *args, **kwargs):
+        return self.rewrite(log).evalf(*args, **kwargs)
+
+    def _eval_simplify(self, *args, **kwargs):
+        a, b = (x.simplify(**kwargs).factor() for x in self.args)
+        candidate = _logaddexp2(a, b)
+        if candidate != _logaddexp2(a, b, evaluate=False):
+            return candidate
+        else:
+            return logaddexp2(a, b)
+
+
+class amin(Token):
+    """ Minimum value along an axis.
+
+    Helper class for use with e.g. numpy.amin
+
+
+    See Also
+    ========
+
+    https://numpy.org/doc/stable/reference/generated/numpy.amin.html
+    """
+    __slots__ = _fields = ('array', 'axis')
+    defaults = {'axis': none}
+    _construct_axis = staticmethod(sympify)
+
+
+class amax(Token):
+    """ Maximum value along an axis.
+
+    Helper class for use with e.g. numpy.amax
+
+
+    See Also
+    ========
+
+    https://numpy.org/doc/stable/reference/generated/numpy.amax.html
+    """
+    __slots__ = _fields = ('array', 'axis')
+    defaults = {'axis': none}
+    _construct_axis = staticmethod(sympify)
+
+
+class maximum(Function):
+    """ Element-wise maximum of array elements.
+
+    Helper class for use with e.g. numpy.maximum
+
+
+    See Also
+    ========
+
+    https://numpy.org/doc/stable/reference/generated/numpy.maximum.html
+    """
+
+    def _eval_rewrite_as_Max(self, *args):
+        return Max(*self.args)
+
+
+class minimum(Function):
+    """ Element-wise minimum of array elements.
+
+    Helper class for use with e.g. numpy.minimum
+
+
+    See Also
+    ========
+
+    https://numpy.org/doc/stable/reference/generated/numpy.minimum.html
+    """
+
+    def _eval_rewrite_as_Min(self, *args):
+        return Min(*self.args)

.venv/lib/python3.13/site-packages/sympy/codegen/pynodes.py

@@ -0,0 +1,11 @@
+from .abstract_nodes import List as AbstractList
+from .ast import Token
+
+
+class List(AbstractList):
+    pass
+
+
+class NumExprEvaluate(Token):
+    """represents a call to :class:`numexpr`s :func:`evaluate`"""
+    __slots__ = _fields = ('expr',)

.venv/lib/python3.13/site-packages/sympy/codegen/pyutils.py

@@ -0,0 +1,24 @@
+from sympy.printing.pycode import PythonCodePrinter
+
+""" This module collects utilities for rendering Python code. """
+
+
+def render_as_module(content, standard='python3'):
+    """Renders Python code as a module (with the required imports).
+
+    Parameters
+    ==========
+
+    standard :
+        See the parameter ``standard`` in
+        :meth:`sympy.printing.pycode.pycode`
+    """
+
+    printer = PythonCodePrinter({'standard':standard})
+    pystr = printer.doprint(content)
+    if printer._settings['fully_qualified_modules']:
+        module_imports_str = '\n'.join('import %s' % k for k in printer.module_imports)
+    else:
+        module_imports_str = '\n'.join(['from %s import %s' % (k, ', '.join(v)) for
+                                        k, v in printer.module_imports.items()])
+    return module_imports_str + '\n\n' + pystr

.venv/lib/python3.13/site-packages/sympy/codegen/rewriting.py

@@ -0,0 +1,357 @@
+"""
+Classes and functions useful for rewriting expressions for optimized code
+generation. Some languages (or standards thereof), e.g. C99, offer specialized
+math functions for better performance and/or precision.
+
+Using the ``optimize`` function in this module, together with a collection of
+rules (represented as instances of ``Optimization``), one can rewrite the
+expressions for this purpose::
+
+    >>> from sympy import Symbol, exp, log
+    >>> from sympy.codegen.rewriting import optimize, optims_c99
+    >>> x = Symbol('x')
+    >>> optimize(3*exp(2*x) - 3, optims_c99)
+    3*expm1(2*x)
+    >>> optimize(exp(2*x) - 1 - exp(-33), optims_c99)
+    expm1(2*x) - exp(-33)
+    >>> optimize(log(3*x + 3), optims_c99)
+    log1p(x) + log(3)
+    >>> optimize(log(2*x + 3), optims_c99)
+    log(2*x + 3)
+
+The ``optims_c99`` imported above is tuple containing the following instances
+(which may be imported from ``sympy.codegen.rewriting``):
+
+- ``expm1_opt``
+- ``log1p_opt``
+- ``exp2_opt``
+- ``log2_opt``
+- ``log2const_opt``
+
+
+"""
+from sympy.core.function import expand_log
+from sympy.core.singleton import S
+from sympy.core.symbol import Wild
+from sympy.functions.elementary.complexes import sign
+from sympy.functions.elementary.exponential import (exp, log)
+from sympy.functions.elementary.miscellaneous import (Max, Min)
+from sympy.functions.elementary.trigonometric import (cos, sin, sinc)
+from sympy.assumptions import Q, ask
+from sympy.codegen.cfunctions import log1p, log2, exp2, expm1
+from sympy.codegen.matrix_nodes import MatrixSolve
+from sympy.core.expr import UnevaluatedExpr
+from sympy.core.power import Pow
+from sympy.codegen.numpy_nodes import logaddexp, logaddexp2
+from sympy.codegen.scipy_nodes import cosm1, powm1
+from sympy.core.mul import Mul
+from sympy.matrices.expressions.matexpr import MatrixSymbol
+from sympy.utilities.iterables import sift
+
+
+class Optimization:
+    """ Abstract base class for rewriting optimization.
+
+    Subclasses should implement ``__call__`` taking an expression
+    as argument.
+
+    Parameters
+    ==========
+    cost_function : callable returning number
+    priority : number
+
+    """
+    def __init__(self, cost_function=None, priority=1):
+        self.cost_function = cost_function
+        self.priority=priority
+
+    def cheapest(self, *args):
+        return min(args, key=self.cost_function)
+
+
+class ReplaceOptim(Optimization):
+    """ Rewriting optimization calling replace on expressions.
+
+    Explanation
+    ===========
+
+    The instance can be used as a function on expressions for which
+    it will apply the ``replace`` method (see
+    :meth:`sympy.core.basic.Basic.replace`).
+
+    Parameters
+    ==========
+
+    query :
+        First argument passed to replace.
+    value :
+        Second argument passed to replace.
+
+    Examples
+    ========
+
+    >>> from sympy import Symbol
+    >>> from sympy.codegen.rewriting import ReplaceOptim
+    >>> from sympy.codegen.cfunctions import exp2
+    >>> x = Symbol('x')
+    >>> exp2_opt = ReplaceOptim(lambda p: p.is_Pow and p.base == 2,
+    ...     lambda p: exp2(p.exp))
+    >>> exp2_opt(2**x)
+    exp2(x)
+
+    """
+
+    def __init__(self, query, value, **kwargs):
+        super().__init__(**kwargs)
+        self.query = query
+        self.value = value
+
+    def __call__(self, expr):
+        return expr.replace(self.query, self.value)
+
+
+def optimize(expr, optimizations):
+    """ Apply optimizations to an expression.
+
+    Parameters
+    ==========
+
+    expr : expression
+    optimizations : iterable of ``Optimization`` instances
+        The optimizations will be sorted with respect to ``priority`` (highest first).
+
+    Examples
+    ========
+
+    >>> from sympy import log, Symbol
+    >>> from sympy.codegen.rewriting import optims_c99, optimize
+    >>> x = Symbol('x')
+    >>> optimize(log(x+3)/log(2) + log(x**2 + 1), optims_c99)
+    log1p(x**2) + log2(x + 3)
+
+    """
+
+    for optim in sorted(optimizations, key=lambda opt: opt.priority, reverse=True):
+        new_expr = optim(expr)
+        if optim.cost_function is None:
+            expr = new_expr
+        else:
+            expr = optim.cheapest(expr, new_expr)
+    return expr
+
+
+exp2_opt = ReplaceOptim(
+    lambda p: p.is_Pow and p.base == 2,
+    lambda p: exp2(p.exp)
+)
+
+
+_d = Wild('d', properties=[lambda x: x.is_Dummy])
+_u = Wild('u', properties=[lambda x: not x.is_number and not x.is_Add])
+_v = Wild('v')
+_w = Wild('w')
+_n = Wild('n', properties=[lambda x: x.is_number])
+
+sinc_opt1 = ReplaceOptim(
+    sin(_w)/_w, sinc(_w)
+)
+sinc_opt2 = ReplaceOptim(
+    sin(_n*_w)/_w, _n*sinc(_n*_w)
+)
+sinc_opts = (sinc_opt1, sinc_opt2)
+
+log2_opt = ReplaceOptim(_v*log(_w)/log(2), _v*log2(_w), cost_function=lambda expr: expr.count(
+    lambda e: (  # division & eval of transcendentals are expensive floating point operations...
+        e.is_Pow and e.exp.is_negative  # division
+        or (isinstance(e, (log, log2)) and not e.args[0].is_number))  # transcendental
+    )
+)
+
+log2const_opt = ReplaceOptim(log(2)*log2(_w), log(_w))
+
+logsumexp_2terms_opt = ReplaceOptim(
+    lambda l: (isinstance(l, log)
+               and l.args[0].is_Add
+               and len(l.args[0].args) == 2
+               and all(isinstance(t, exp) for t in l.args[0].args)),
+    lambda l: (
+        Max(*[e.args[0] for e in l.args[0].args]) +
+        log1p(exp(Min(*[e.args[0] for e in l.args[0].args])))
+    )
+)
+
+
+class FuncMinusOneOptim(ReplaceOptim):
+    """Specialization of ReplaceOptim for functions evaluating "f(x) - 1".
+
+    Explanation
+    ===========
+
+    Numerical functions which go toward one as x go toward zero is often best
+    implemented by a dedicated function in order to avoid catastrophic
+    cancellation. One such example is ``expm1(x)`` in the C standard library
+    which evaluates ``exp(x) - 1``. Such functions preserves many more
+    significant digits when its argument is much smaller than one, compared
+    to subtracting one afterwards.
+
+    Parameters
+    ==========
+
+    func :
+        The function which is subtracted by one.
+    func_m_1 :
+        The specialized function evaluating ``func(x) - 1``.
+    opportunistic : bool
+        When ``True``, apply the transformation as long as the magnitude of the
+        remaining number terms decreases. When ``False``, only apply the
+        transformation if it completely eliminates the number term.
+
+    Examples
+    ========
+
+    >>> from sympy import symbols, exp
+    >>> from sympy.codegen.rewriting import FuncMinusOneOptim
+    >>> from sympy.codegen.cfunctions import expm1
+    >>> x, y = symbols('x y')
+    >>> expm1_opt = FuncMinusOneOptim(exp, expm1)
+    >>> expm1_opt(exp(x) + 2*exp(5*y) - 3)
+    expm1(x) + 2*expm1(5*y)
+
+
+    """
+
+    def __init__(self, func, func_m_1, opportunistic=True):
+        weight = 10  # <-- this is an arbitrary number (heuristic)
+        super().__init__(lambda e: e.is_Add, self.replace_in_Add,
+                         cost_function=lambda expr: expr.count_ops() - weight*expr.count(func_m_1))
+        self.func = func
+        self.func_m_1 = func_m_1
+        self.opportunistic = opportunistic
+
+    def _group_Add_terms(self, add):
+        numbers, non_num = sift(add.args, lambda arg: arg.is_number, binary=True)
+        numsum = sum(numbers)
+        terms_with_func, other = sift(non_num, lambda arg: arg.has(self.func), binary=True)
+        return numsum, terms_with_func, other
+
+    def replace_in_Add(self, e):
+        """ passed as second argument to Basic.replace(...) """
+        numsum, terms_with_func, other_non_num_terms = self._group_Add_terms(e)
+        if numsum == 0:
+            return e
+        substituted, untouched = [], []
+        for with_func in terms_with_func:
+            if with_func.is_Mul:
+                func, coeff = sift(with_func.args, lambda arg: arg.func == self.func, binary=True)
+                if len(func) == 1 and len(coeff) == 1:
+                    func, coeff = func[0], coeff[0]
+                else:
+                    coeff = None
+            elif with_func.func == self.func:
+                func, coeff = with_func, S.One
+            else:
+                coeff = None
+
+            if coeff is not None and coeff.is_number and sign(coeff) == -sign(numsum):
+                if self.opportunistic:
+                    do_substitute = abs(coeff+numsum) < abs(numsum)
+                else:
+                    do_substitute = coeff+numsum == 0
+
+                if do_substitute:  # advantageous substitution
+                    numsum += coeff
+                    substituted.append(coeff*self.func_m_1(*func.args))
+                    continue
+            untouched.append(with_func)
+
+        return e.func(numsum, *substituted, *untouched, *other_non_num_terms)
+
+    def __call__(self, expr):
+        alt1 = super().__call__(expr)
+        alt2 = super().__call__(expr.factor())
+        return self.cheapest(alt1, alt2)
+
+
+expm1_opt = FuncMinusOneOptim(exp, expm1)
+cosm1_opt = FuncMinusOneOptim(cos, cosm1)
+powm1_opt = FuncMinusOneOptim(Pow, powm1)
+
+log1p_opt = ReplaceOptim(
+    lambda e: isinstance(e, log),
+    lambda l: expand_log(l.replace(
+        log, lambda arg: log(arg.factor())
+    )).replace(log(_u+1), log1p(_u))
+)
+
+def create_expand_pow_optimization(limit, *, base_req=lambda b: b.is_symbol):
+    """ Creates an instance of :class:`ReplaceOptim` for expanding ``Pow``.
+
+    Explanation
+    ===========
+
+    The requirements for expansions are that the base needs to be a symbol
+    and the exponent needs to be an Integer (and be less than or equal to
+    ``limit``).
+
+    Parameters
+    ==========
+
+    limit : int
+         The highest power which is expanded into multiplication.
+    base_req : function returning bool
+         Requirement on base for expansion to happen, default is to return
+         the ``is_symbol`` attribute of the base.
+
+    Examples
+    ========
+
+    >>> from sympy import Symbol, sin
+    >>> from sympy.codegen.rewriting import create_expand_pow_optimization
+    >>> x = Symbol('x')
+    >>> expand_opt = create_expand_pow_optimization(3)
+    >>> expand_opt(x**5 + x**3)
+    x**5 + x*x*x
+    >>> expand_opt(x**5 + x**3 + sin(x)**3)
+    x**5 + sin(x)**3 + x*x*x
+    >>> opt2 = create_expand_pow_optimization(3, base_req=lambda b: not b.is_Function)
+    >>> opt2((x+1)**2 + sin(x)**2)
+    sin(x)**2 + (x + 1)*(x + 1)
+
+    """
+    return ReplaceOptim(
+        lambda e: e.is_Pow and base_req(e.base) and e.exp.is_Integer and abs(e.exp) <= limit,
+        lambda p: (
+            UnevaluatedExpr(Mul(*([p.base]*+p.exp), evaluate=False)) if p.exp > 0 else
+            1/UnevaluatedExpr(Mul(*([p.base]*-p.exp), evaluate=False))
+        ))
+
+# Optimization procedures for turning A**(-1) * x into MatrixSolve(A, x)
+def _matinv_predicate(expr):
+    # TODO: We should be able to support more than 2 elements
+    if expr.is_MatMul and len(expr.args) == 2:
+        left, right = expr.args
+        if left.is_Inverse and right.shape[1] == 1:
+            inv_arg = left.arg
+            if isinstance(inv_arg, MatrixSymbol):
+                return bool(ask(Q.fullrank(left.arg)))
+
+    return False
+
+def _matinv_transform(expr):
+    left, right = expr.args
+    inv_arg = left.arg
+    return MatrixSolve(inv_arg, right)
+
+
+matinv_opt = ReplaceOptim(_matinv_predicate, _matinv_transform)
+
+
+logaddexp_opt = ReplaceOptim(log(exp(_v)+exp(_w)), logaddexp(_v, _w))
+logaddexp2_opt = ReplaceOptim(log(Pow(2, _v)+Pow(2, _w)), logaddexp2(_v, _w)*log(2))
+
+# Collections of optimizations:
+optims_c99 = (expm1_opt, log1p_opt, exp2_opt, log2_opt, log2const_opt)
+
+optims_numpy = optims_c99 + (logaddexp_opt, logaddexp2_opt,) + sinc_opts
+
+optims_scipy = (cosm1_opt, powm1_opt)

.venv/lib/python3.13/site-packages/sympy/codegen/scipy_nodes.py

@@ -0,0 +1,79 @@
+from sympy.core.function import Add, ArgumentIndexError, Function
+from sympy.core.power import Pow
+from sympy.core.singleton import S
+from sympy.functions.elementary.exponential import log
+from sympy.functions.elementary.trigonometric import cos, sin
+
+
+def _cosm1(x, *, evaluate=True):
+    return Add(cos(x, evaluate=evaluate), -S.One, evaluate=evaluate)
+
+
+class cosm1(Function):
+    """ Minus one plus cosine of x, i.e. cos(x) - 1. For use when x is close to zero.
+
+    Helper class for use with e.g. scipy.special.cosm1
+    See: https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.cosm1.html
+    """
+    nargs = 1
+
+    def fdiff(self, argindex=1):
+        """
+        Returns the first derivative of this function.
+        """
+        if argindex == 1:
+            return -sin(*self.args)
+        else:
+            raise ArgumentIndexError(self, argindex)
+
+    def _eval_rewrite_as_cos(self, x, **kwargs):
+        return _cosm1(x)
+
+    def _eval_evalf(self, *args, **kwargs):
+        return self.rewrite(cos).evalf(*args, **kwargs)
+
+    def _eval_simplify(self, **kwargs):
+        x, = self.args
+        candidate = _cosm1(x.simplify(**kwargs))
+        if candidate != _cosm1(x, evaluate=False):
+            return candidate
+        else:
+            return cosm1(x)
+
+
+def _powm1(x, y, *, evaluate=True):
+    return Add(Pow(x, y, evaluate=evaluate), -S.One, evaluate=evaluate)
+
+
+class powm1(Function):
+    """ Minus one plus x to the power of y, i.e. x**y - 1. For use when x is close to one or y is close to zero.
+
+    Helper class for use with e.g. scipy.special.powm1
+    See: https://docs.scipy.org/doc/scipy/reference/generated/scipy.special.powm1.html
+    """
+    nargs = 2
+
+    def fdiff(self, argindex=1):
+        """
+        Returns the first derivative of this function.
+        """
+        if argindex == 1:
+            return Pow(self.args[0], self.args[1])*self.args[1]/self.args[0]
+        elif argindex == 2:
+            return log(self.args[0])*Pow(*self.args)
+        else:
+            raise ArgumentIndexError(self, argindex)
+
+    def _eval_rewrite_as_Pow(self, x, y, **kwargs):
+        return _powm1(x, y)
+
+    def _eval_evalf(self, *args, **kwargs):
+        return self.rewrite(Pow).evalf(*args, **kwargs)
+
+    def _eval_simplify(self, **kwargs):
+        x, y = self.args
+        candidate = _powm1(x.simplify(**kwargs), y.simplify(**kwargs))
+        if candidate != _powm1(x, y, evaluate=False):
+            return candidate
+        else:
+            return powm1(x, y)

.venv/lib/python3.13/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',
+]

.venv/lib/python3.13/site-packages/sympy/combinatorics/coset_table.py

@@ -0,0 +1,1259 @@
+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()
+            if not all(self.scan_check(alpha, w) for w in R_c_x):
+                return False
+            beta = table[alpha][self.A_dict[x]]
+            if beta is not None:
+                if not all(self.scan_check(beta, w) for w in R_c_x_inv):
+                    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
+                    # XXX: The line below uses == rather than = which means
+                    # that it has no effect. It is not clear though if it is
+                    # correct simply to delete the line or to change it to
+                    # use =. Changing it causes some tests to fail.
+                    #
+                    # https://github.com/sympy/sympy/issues/27633
+                    table[beta][A_dict_inv[x]] == gamma # noqa: B015
+        # 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

.venv/lib/python3.13/site-packages/sympy/combinatorics/fp_groups.py

@@ -0,0 +1,1352 @@
+"""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]
+                rels = [rel.eliminate_word(gen, rep_by) for rel in rels]
+                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 = [C._schreier_gen_elem[str(gen)] for gen in gens]
+        return C.schreier_generators, C.reidemeister_relators, _gens
+
+    return C.schreier_generators, C.reidemeister_relators
+
+
+FpGroupElement = FreeGroupElement

.venv/lib/python3.13/site-packages/sympy/combinatorics/free_groups.py

@@ -0,0 +1,1360 @@
+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 __getnewargs__(self):
+        """Return a tuple of arguments that must be passed to __new__ in order to support pickling this object."""
+        return (self.symbols,)
+
+    def __getstate__(self):
+        # Don't pickle any fields because they are regenerated within __new__
+        return None
+
+    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.
+
+    """
+    __slots__ = ()
+    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):
+        return not self.array_form
+
+    @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

.venv/lib/python3.13/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

.venv/lib/python3.13/site-packages/sympy/combinatorics/generators.py

@@ -0,0 +1,301 @@
+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)]
+    """
+    yield from (Permutation(perm) for perm in variations(range(n), n))
+
+
+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

.venv/lib/python3.13/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)

.venv/lib/python3.13/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)

.venv/lib/python3.13/site-packages/sympy/combinatorics/group_numbers.py

@@ -0,0 +1,294 @@
+from itertools import chain, combinations
+
+from sympy.external.gmpy import gcd
+from sympy.ntheory.factor_ import factorint
+from sympy.utilities.misc import as_int
+
+
+def _is_nilpotent_number(factors: dict) -> bool:
+    """ Check whether `n` is a nilpotent number.
+    Note that ``factors`` is a prime factorization of `n`.
+
+    This is a low-level helper for ``is_nilpotent_number``, for internal use.
+    """
+    for p in factors.keys():
+        for q, e in factors.items():
+            # We want to calculate
+            # any(pow(q, k, p) == 1 for k in range(1, e + 1))
+            m = 1
+            for _ in range(e):
+                m = m*q % p
+                if m == 1:
+                    return False
+    return True
+
+
+def is_nilpotent_number(n) -> bool:
+    """
+    Check whether `n` is a nilpotent number. A number `n` is said to be
+    nilpotent if and only if every finite group of order `n` is nilpotent.
+    For more information see [1]_.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.group_numbers import is_nilpotent_number
+    >>> from sympy import randprime
+    >>> is_nilpotent_number(21)
+    False
+    >>> is_nilpotent_number(randprime(1, 30)**12)
+    True
+
+    References
+    ==========
+
+    .. [1] Pakianathan, J., Shankar, K., Nilpotent Numbers,
+           The American Mathematical Monthly, 107(7), 631-634.
+    .. [2] https://oeis.org/A056867
+
+    """
+    n = as_int(n)
+    if n <= 0:
+        raise ValueError("n must be a positive integer, not %i" % n)
+    return _is_nilpotent_number(factorint(n))
+
+
+def is_abelian_number(n) -> bool:
+    """
+    Check whether `n` is an abelian number. A number `n` is said to be abelian
+    if and only if every finite group of order `n` is abelian. For more
+    information see [1]_.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.group_numbers import is_abelian_number
+    >>> from sympy import randprime
+    >>> is_abelian_number(4)
+    True
+    >>> is_abelian_number(randprime(1, 2000)**2)
+    True
+    >>> is_abelian_number(60)
+    False
+
+    References
+    ==========
+
+    .. [1] Pakianathan, J., Shankar, K., Nilpotent Numbers,
+           The American Mathematical Monthly, 107(7), 631-634.
+    .. [2] https://oeis.org/A051532
+
+    """
+    n = as_int(n)
+    if n <= 0:
+        raise ValueError("n must be a positive integer, not %i" % n)
+    factors = factorint(n)
+    return all(e < 3 for e in factors.values()) and _is_nilpotent_number(factors)
+
+
+def is_cyclic_number(n) -> bool:
+    """
+    Check whether `n` is a cyclic number. A number `n` is said to be cyclic
+    if and only if every finite group of order `n` is cyclic. For more
+    information see [1]_.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.group_numbers import is_cyclic_number
+    >>> from sympy import randprime
+    >>> is_cyclic_number(15)
+    True
+    >>> is_cyclic_number(randprime(1, 2000)**2)
+    False
+    >>> is_cyclic_number(4)
+    False
+
+    References
+    ==========
+
+    .. [1] Pakianathan, J., Shankar, K., Nilpotent Numbers,
+           The American Mathematical Monthly, 107(7), 631-634.
+    .. [2] https://oeis.org/A003277
+
+    """
+    n = as_int(n)
+    if n <= 0:
+        raise ValueError("n must be a positive integer, not %i" % n)
+    factors = factorint(n)
+    return all(e == 1 for e in factors.values()) and _is_nilpotent_number(factors)
+
+
+def _holder_formula(prime_factors):
+    r""" Number of groups of order `n`.
+    where `n` is squarefree and its prime factors are ``prime_factors``.
+    i.e., ``n == math.prod(prime_factors)``
+
+    Explanation
+    ===========
+
+    When `n` is squarefree, the number of groups of order `n` is expressed by
+
+    .. math ::
+        \sum_{d \mid n} \prod_p \frac{p^{c(p, d)} - 1}{p - 1}
+
+    where `n=de`, `p` is the prime factor of `e`,
+    and `c(p, d)` is the number of prime factors `q` of `d` such that `q \equiv 1 \pmod{p}` [2]_.
+
+    The formula is elegant, but can be improved when implemented as an algorithm.
+    Since `n` is assumed to be squarefree, the divisor `d` of `n` can be identified with the power set of prime factors.
+    We let `N` be the set of prime factors of `n`.
+    `F = \{p \in N : \forall q \in N, q \not\equiv 1 \pmod{p} \}, M = N \setminus F`, we have the following.
+
+    .. math ::
+        \sum_{d \in 2^{M}} \prod_{p \in M \setminus d} \frac{p^{c(p, F \cup d)} - 1}{p - 1}
+
+    Practically, many prime factors are expected to be members of `F`, thus reducing computation time.
+
+    Parameters
+    ==========
+
+    prime_factors : set
+        The set of prime factors of ``n``. where `n` is squarefree.
+
+    Returns
+    =======
+
+    int : Number of groups of order ``n``
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.group_numbers import _holder_formula
+    >>> _holder_formula({2}) # n = 2
+    1
+    >>> _holder_formula({2, 3}) # n = 2*3 = 6
+    2
+
+    See Also
+    ========
+
+    groups_count
+
+    References
+    ==========
+
+    .. [1] Otto Holder, Die Gruppen der Ordnungen p^3, pq^2, pqr, p^4,
+           Math. Ann. 43 pp. 301-412 (1893).
+           http://dx.doi.org/10.1007/BF01443651
+    .. [2] John H. Conway, Heiko Dietrich and E.A. O'Brien,
+           Counting groups: gnus, moas and other exotica
+           The Mathematical Intelligencer 30, 6-15 (2008)
+           https://doi.org/10.1007/BF02985731
+
+    """
+    F = {p for p in prime_factors if all(q % p != 1 for q in prime_factors)}
+    M = prime_factors - F
+
+    s = 0
+    powerset = chain.from_iterable(combinations(M, r) for r in range(len(M)+1))
+    for ps in powerset:
+        ps = set(ps)
+        prod = 1
+        for p in M - ps:
+            c = len([q for q in F | ps if q % p == 1])
+            prod *= (p**c - 1) // (p - 1)
+            if not prod:
+                break
+        s += prod
+    return s
+
+
+def groups_count(n):
+    r""" Number of groups of order `n`.
+    In [1]_, ``gnu(n)`` is given, so we follow this notation here as well.
+
+    Parameters
+    ==========
+
+    n : Integer
+        ``n`` is a positive integer
+
+    Returns
+    =======
+
+    int : ``gnu(n)``
+
+    Raises
+    ======
+
+    ValueError
+        Number of groups of order ``n`` is unknown or not implemented.
+        For example, gnu(`2^{11}`) is not yet known.
+        On the other hand, gnu(99) is known to be 2,
+        but this has not yet been implemented in this function.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.group_numbers import groups_count
+    >>> groups_count(3) # There is only one cyclic group of order 3
+    1
+    >>> # There are two groups of order 10: the cyclic group and the dihedral group
+    >>> groups_count(10)
+    2
+
+    See Also
+    ========
+
+    is_cyclic_number
+        `n` is cyclic iff gnu(n) = 1
+
+    References
+    ==========
+
+    .. [1] John H. Conway, Heiko Dietrich and E.A. O'Brien,
+           Counting groups: gnus, moas and other exotica
+           The Mathematical Intelligencer 30, 6-15 (2008)
+           https://doi.org/10.1007/BF02985731
+    .. [2] https://oeis.org/A000001
+
+    """
+    n = as_int(n)
+    if n <= 0:
+        raise ValueError("n must be a positive integer, not %i" % n)
+    factors = factorint(n)
+    if len(factors) == 1:
+        (p, e) = list(factors.items())[0]
+        if p == 2:
+            A000679 = [1, 1, 2, 5, 14, 51, 267, 2328, 56092, 10494213, 49487367289]
+            if e < len(A000679):
+                return A000679[e]
+        if p == 3:
+            A090091 = [1, 1, 2, 5, 15, 67, 504, 9310, 1396077, 5937876645]
+            if e < len(A090091):
+                return A090091[e]
+        if e <= 2: # gnu(p) = 1, gnu(p**2) = 2
+            return e
+        if e == 3: # gnu(p**3) = 5
+            return 5
+        if e == 4: # if p is an odd prime, gnu(p**4) = 15
+            return 15
+        if e == 5: # if p >= 5, gnu(p**5) is expressed by the following equation
+            return 61 + 2*p + 2*gcd(p-1, 3) + gcd(p-1, 4)
+        if e == 6: # if p >= 6, gnu(p**6) is expressed by the following equation
+            return 3*p**2 + 39*p + 344 +\
+                  24*gcd(p-1, 3) + 11*gcd(p-1, 4) + 2*gcd(p-1, 5)
+        if e == 7: # if p >= 7, gnu(p**7) is expressed by the following equation
+            if p == 5:
+                return 34297
+            return 3*p**5 + 12*p**4 + 44*p**3 + 170*p**2 + 707*p + 2455 +\
+                  (4*p**2 + 44*p + 291)*gcd(p-1, 3) + (p**2 + 19*p + 135)*gcd(p-1, 4) + \
+                  (3*p + 31)*gcd(p-1, 5) + 4*gcd(p-1, 7) + 5*gcd(p-1, 8) + gcd(p-1, 9)
+    if any(e > 1 for e in factors.values()): # n is not squarefree
+        # some known values for small n that have more than 1 factor and are not square free (https://oeis.org/A000001)
+        small = {12: 5, 18: 5, 20: 5, 24: 15, 28: 4, 36: 14, 40: 14, 44: 4, 45: 2, 48: 52,
+                50: 5, 52: 5, 54: 15, 56: 13, 60: 13, 63: 4, 68: 5, 72: 50, 75: 3, 76: 4,
+                80: 52, 84: 15, 88: 12, 90: 10, 92: 4}
+        if n in small:
+            return small[n]
+        raise ValueError("Number of groups of order n is unknown or not implemented")
+    if len(factors) == 2: # n is squarefree semiprime
+        p, q = sorted(factors.keys())
+        return 2 if q % p == 1 else 1
+    return _holder_formula(set(factors.keys()))

.venv/lib/python3.13/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)

.venv/lib/python3.13/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))

.venv/lib/python3.13/site-packages/sympy/combinatorics/partitions.py

@@ -0,0 +1,745 @@
+from sympy.core import Basic, Dict, sympify, Tuple
+from sympy.core.numbers import Integer
+from sympy.core.sorting import default_sort_key
+from sympy.core.sympify import _sympify
+from sympy.functions.combinatorial.numbers import bell
+from sympy.matrices import zeros
+from sympy.sets.sets import FiniteSet, Union
+from sympy.utilities.iterables import flatten, group
+from sympy.utilities.misc import as_int
+
+
+from collections import defaultdict
+
+
+class Partition(FiniteSet):
+    """
+    This class represents an abstract partition.
+
+    A partition is a set of disjoint sets whose union equals a given set.
+
+    See Also
+    ========
+
+    sympy.utilities.iterables.partitions,
+    sympy.utilities.iterables.multiset_partitions
+    """
+
+    _rank = None
+    _partition = None
+
+    def __new__(cls, *partition):
+        """
+        Generates a new partition object.
+
+        This method also verifies if the arguments passed are
+        valid and raises a ValueError if they are not.
+
+        Examples
+        ========
+
+        Creating Partition from Python lists:
+
+        >>> from sympy.combinatorics import Partition
+        >>> a = Partition([1, 2], [3])
+        >>> a
+        Partition({3}, {1, 2})
+        >>> a.partition
+        [[1, 2], [3]]
+        >>> len(a)
+        2
+        >>> a.members
+        (1, 2, 3)
+
+        Creating Partition from Python sets:
+
+        >>> Partition({1, 2, 3}, {4, 5})
+        Partition({4, 5}, {1, 2, 3})
+
+        Creating Partition from SymPy finite sets:
+
+        >>> from sympy import FiniteSet
+        >>> a = FiniteSet(1, 2, 3)
+        >>> b = FiniteSet(4, 5)
+        >>> Partition(a, b)
+        Partition({4, 5}, {1, 2, 3})
+        """
+        args = []
+        dups = False
+        for arg in partition:
+            if isinstance(arg, list):
+                as_set = set(arg)
+                if len(as_set) < len(arg):
+                    dups = True
+                    break  # error below
+                arg = as_set
+            args.append(_sympify(arg))
+
+        if not all(isinstance(part, FiniteSet) for part in args):
+            raise ValueError(
+                "Each argument to Partition should be " \
+                "a list, set, or a FiniteSet")
+
+        # sort so we have a canonical reference for RGS
+        U = Union(*args)
+        if dups or len(U) < sum(len(arg) for arg in args):
+            raise ValueError("Partition contained duplicate elements.")
+
+        obj = FiniteSet.__new__(cls, *args)
+        obj.members = tuple(U)
+        obj.size = len(U)
+        return obj
+
+    def sort_key(self, order=None):
+        """Return a canonical key that can be used for sorting.
+
+        Ordering is based on the size and sorted elements of the partition
+        and ties are broken with the rank.
+
+        Examples
+        ========
+
+        >>> from sympy import default_sort_key
+        >>> from sympy.combinatorics import Partition
+        >>> from sympy.abc import x
+        >>> a = Partition([1, 2])
+        >>> b = Partition([3, 4])
+        >>> c = Partition([1, x])
+        >>> d = Partition(list(range(4)))
+        >>> l = [d, b, a + 1, a, c]
+        >>> l.sort(key=default_sort_key); l
+        [Partition({1, 2}), Partition({1}, {2}), Partition({1, x}), Partition({3, 4}), Partition({0, 1, 2, 3})]
+        """
+        if order is None:
+            members = self.members
+        else:
+            members = tuple(sorted(self.members,
+                             key=lambda w: default_sort_key(w, order)))
+        return tuple(map(default_sort_key, (self.size, members, self.rank)))
+
+    @property
+    def partition(self):
+        """Return partition as a sorted list of lists.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Partition
+        >>> Partition([1], [2, 3]).partition
+        [[1], [2, 3]]
+        """
+        if self._partition is None:
+            self._partition = sorted([sorted(p, key=default_sort_key)
+                                      for p in self.args])
+        return self._partition
+
+    def __add__(self, other):
+        """
+        Return permutation whose rank is ``other`` greater than current rank,
+        (mod the maximum rank for the set).
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Partition
+        >>> a = Partition([1, 2], [3])
+        >>> a.rank
+        1
+        >>> (a + 1).rank
+        2
+        >>> (a + 100).rank
+        1
+        """
+        other = as_int(other)
+        offset = self.rank + other
+        result = RGS_unrank((offset) %
+                            RGS_enum(self.size),
+                            self.size)
+        return Partition.from_rgs(result, self.members)
+
+    def __sub__(self, other):
+        """
+        Return permutation whose rank is ``other`` less than current rank,
+        (mod the maximum rank for the set).
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Partition
+        >>> a = Partition([1, 2], [3])
+        >>> a.rank
+        1
+        >>> (a - 1).rank
+        0
+        >>> (a - 100).rank
+        1
+        """
+        return self.__add__(-other)
+
+    def __le__(self, other):
+        """
+        Checks if a partition is less than or equal to
+        the other based on rank.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Partition
+        >>> a = Partition([1, 2], [3, 4, 5])
+        >>> b = Partition([1], [2, 3], [4], [5])
+        >>> a.rank, b.rank
+        (9, 34)
+        >>> a <= a
+        True
+        >>> a <= b
+        True
+        """
+        return self.sort_key() <= sympify(other).sort_key()
+
+    def __lt__(self, other):
+        """
+        Checks if a partition is less than the other.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Partition
+        >>> a = Partition([1, 2], [3, 4, 5])
+        >>> b = Partition([1], [2, 3], [4], [5])
+        >>> a.rank, b.rank
+        (9, 34)
+        >>> a < b
+        True
+        """
+        return self.sort_key() < sympify(other).sort_key()
+
+    @property
+    def rank(self):
+        """
+        Gets the rank of a partition.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Partition
+        >>> a = Partition([1, 2], [3], [4, 5])
+        >>> a.rank
+        13
+        """
+        if self._rank is not None:
+            return self._rank
+        self._rank = RGS_rank(self.RGS)
+        return self._rank
+
+    @property
+    def RGS(self):
+        """
+        Returns the "restricted growth string" of the partition.
+
+        Explanation
+        ===========
+
+        The RGS is returned as a list of indices, L, where L[i] indicates
+        the block in which element i appears. For example, in a partition
+        of 3 elements (a, b, c) into 2 blocks ([c], [a, b]) the RGS is
+        [1, 1, 0]: "a" is in block 1, "b" is in block 1 and "c" is in block 0.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Partition
+        >>> a = Partition([1, 2], [3], [4, 5])
+        >>> a.members
+        (1, 2, 3, 4, 5)
+        >>> a.RGS
+        (0, 0, 1, 2, 2)
+        >>> a + 1
+        Partition({3}, {4}, {5}, {1, 2})
+        >>> _.RGS
+        (0, 0, 1, 2, 3)
+        """
+        rgs = {}
+        partition = self.partition
+        for i, part in enumerate(partition):
+            for j in part:
+                rgs[j] = i
+        return tuple([rgs[i] for i in sorted(
+            [i for p in partition for i in p], key=default_sort_key)])
+
+    @classmethod
+    def from_rgs(self, rgs, elements):
+        """
+        Creates a set partition from a restricted growth string.
+
+        Explanation
+        ===========
+
+        The indices given in rgs are assumed to be the index
+        of the element as given in elements *as provided* (the
+        elements are not sorted by this routine). Block numbering
+        starts from 0. If any block was not referenced in ``rgs``
+        an error will be raised.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics import Partition
+        >>> Partition.from_rgs([0, 1, 2, 0, 1], list('abcde'))
+        Partition({c}, {a, d}, {b, e})
+        >>> Partition.from_rgs([0, 1, 2, 0, 1], list('cbead'))
+        Partition({e}, {a, c}, {b, d})
+        >>> a = Partition([1, 4], [2], [3, 5])
+        >>> Partition.from_rgs(a.RGS, a.members)
+        Partition({2}, {1, 4}, {3, 5})
+        """
+        if len(rgs) != len(elements):
+            raise ValueError('mismatch in rgs and element lengths')
+        max_elem = max(rgs) + 1
+        partition = [[] for i in range(max_elem)]
+        j = 0
+        for i in rgs:
+            partition[i].append(elements[j])
+            j += 1
+        if not all(p for p in partition):
+            raise ValueError('some blocks of the partition were empty.')
+        return Partition(*partition)
+
+
+class IntegerPartition(Basic):
+    """
+    This class represents an integer partition.
+
+    Explanation
+    ===========
+
+    In number theory and combinatorics, a partition of a positive integer,
+    ``n``, also called an integer partition, is a way of writing ``n`` as a
+    list of positive integers that sum to n. Two partitions that differ only
+    in the order of summands are considered to be the same partition; if order
+    matters then the partitions are referred to as compositions. For example,
+    4 has five partitions: [4], [3, 1], [2, 2], [2, 1, 1], and [1, 1, 1, 1];
+    the compositions [1, 2, 1] and [1, 1, 2] are the same as partition
+    [2, 1, 1].
+
+    See Also
+    ========
+
+    sympy.utilities.iterables.partitions,
+    sympy.utilities.iterables.multiset_partitions
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Partition_%28number_theory%29
+    """
+
+    _dict = None
+    _keys = None
+
+    def __new__(cls, partition, integer=None):
+        """
+        Generates a new IntegerPartition object from a list or dictionary.
+
+        Explanation
+        ===========
+
+        The partition can be given as a list of positive integers or a
+        dictionary of (integer, multiplicity) items. If the partition is
+        preceded by an integer an error will be raised if the partition
+        does not sum to that given integer.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.partitions import IntegerPartition
+        >>> a = IntegerPartition([5, 4, 3, 1, 1])
+        >>> a
+        IntegerPartition(14, (5, 4, 3, 1, 1))
+        >>> print(a)
+        [5, 4, 3, 1, 1]
+        >>> IntegerPartition({1:3, 2:1})
+        IntegerPartition(5, (2, 1, 1, 1))
+
+        If the value that the partition should sum to is given first, a check
+        will be made to see n error will be raised if there is a discrepancy:
+
+        >>> IntegerPartition(10, [5, 4, 3, 1])
+        Traceback (most recent call last):
+        ...
+        ValueError: The partition is not valid
+
+        """
+        if integer is not None:
+            integer, partition = partition, integer
+        if isinstance(partition, (dict, Dict)):
+            _ = []
+            for k, v in sorted(partition.items(), reverse=True):
+                if not v:
+                    continue
+                k, v = as_int(k), as_int(v)
+                _.extend([k]*v)
+            partition = tuple(_)
+        else:
+            partition = tuple(sorted(map(as_int, partition), reverse=True))
+        sum_ok = False
+        if integer is None:
+            integer = sum(partition)
+            sum_ok = True
+        else:
+            integer = as_int(integer)
+
+        if not sum_ok and sum(partition) != integer:
+            raise ValueError("Partition did not add to %s" % integer)
+        if any(i < 1 for i in partition):
+            raise ValueError("All integer summands must be greater than one")
+
+        obj = Basic.__new__(cls, Integer(integer), Tuple(*partition))
+        obj.partition = list(partition)
+        obj.integer = integer
+        return obj
+
+    def prev_lex(self):
+        """Return the previous partition of the integer, n, in lexical order,
+        wrapping around to [1, ..., 1] if the partition is [n].
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.partitions import IntegerPartition
+        >>> p = IntegerPartition([4])
+        >>> print(p.prev_lex())
+        [3, 1]
+        >>> p.partition > p.prev_lex().partition
+        True
+        """
+        d = defaultdict(int)
+        d.update(self.as_dict())
+        keys = self._keys
+        if keys == [1]:
+            return IntegerPartition({self.integer: 1})
+        if keys[-1] != 1:
+            d[keys[-1]] -= 1
+            if keys[-1] == 2:
+                d[1] = 2
+            else:
+                d[keys[-1] - 1] = d[1] = 1
+        else:
+            d[keys[-2]] -= 1
+            left = d[1] + keys[-2]
+            new = keys[-2]
+            d[1] = 0
+            while left:
+                new -= 1
+                if left - new >= 0:
+                    d[new] += left//new
+                    left -= d[new]*new
+        return IntegerPartition(self.integer, d)
+
+    def next_lex(self):
+        """Return the next partition of the integer, n, in lexical order,
+        wrapping around to [n] if the partition is [1, ..., 1].
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.partitions import IntegerPartition
+        >>> p = IntegerPartition([3, 1])
+        >>> print(p.next_lex())
+        [4]
+        >>> p.partition < p.next_lex().partition
+        True
+        """
+        d = defaultdict(int)
+        d.update(self.as_dict())
+        key = self._keys
+        a = key[-1]
+        if a == self.integer:
+            d.clear()
+            d[1] = self.integer
+        elif a == 1:
+            if d[a] > 1:
+                d[a + 1] += 1
+                d[a] -= 2
+            else:
+                b = key[-2]
+                d[b + 1] += 1
+                d[1] = (d[b] - 1)*b
+                d[b] = 0
+        else:
+            if d[a] > 1:
+                if len(key) == 1:
+                    d.clear()
+                    d[a + 1] = 1
+                    d[1] = self.integer - a - 1
+                else:
+                    a1 = a + 1
+                    d[a1] += 1
+                    d[1] = d[a]*a - a1
+                    d[a] = 0
+            else:
+                b = key[-2]
+                b1 = b + 1
+                d[b1] += 1
+                need = d[b]*b + d[a]*a - b1
+                d[a] = d[b] = 0
+                d[1] = need
+        return IntegerPartition(self.integer, d)
+
+    def as_dict(self):
+        """Return the partition as a dictionary whose keys are the
+        partition integers and the values are the multiplicity of that
+        integer.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.partitions import IntegerPartition
+        >>> IntegerPartition([1]*3 + [2] + [3]*4).as_dict()
+        {1: 3, 2: 1, 3: 4}
+        """
+        if self._dict is None:
+            groups = group(self.partition, multiple=False)
+            self._keys = [g[0] for g in groups]
+            self._dict = dict(groups)
+        return self._dict
+
+    @property
+    def conjugate(self):
+        """
+        Computes the conjugate partition of itself.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.partitions import IntegerPartition
+        >>> a = IntegerPartition([6, 3, 3, 2, 1])
+        >>> a.conjugate
+        [5, 4, 3, 1, 1, 1]
+        """
+        j = 1
+        temp_arr = list(self.partition) + [0]
+        k = temp_arr[0]
+        b = [0]*k
+        while k > 0:
+            while k > temp_arr[j]:
+                b[k - 1] = j
+                k -= 1
+            j += 1
+        return b
+
+    def __lt__(self, other):
+        """Return True if self is less than other when the partition
+        is listed from smallest to biggest.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.partitions import IntegerPartition
+        >>> a = IntegerPartition([3, 1])
+        >>> a < a
+        False
+        >>> b = a.next_lex()
+        >>> a < b
+        True
+        >>> a == b
+        False
+        """
+        return list(reversed(self.partition)) < list(reversed(other.partition))
+
+    def __le__(self, other):
+        """Return True if self is less than other when the partition
+        is listed from smallest to biggest.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.partitions import IntegerPartition
+        >>> a = IntegerPartition([4])
+        >>> a <= a
+        True
+        """
+        return list(reversed(self.partition)) <= list(reversed(other.partition))
+
+    def as_ferrers(self, char='#'):
+        """
+        Prints the ferrer diagram of a partition.
+
+        Examples
+        ========
+
+        >>> from sympy.combinatorics.partitions import IntegerPartition
+        >>> print(IntegerPartition([1, 1, 5]).as_ferrers())
+        #####
+        #
+        #
+        """
+        return "\n".join([char*i for i in self.partition])
+
+    def __str__(self):
+        return str(list(self.partition))
+
+
+def random_integer_partition(n, seed=None):
+    """
+    Generates a random integer partition summing to ``n`` as a list
+    of reverse-sorted integers.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.partitions import random_integer_partition
+
+    For the following, a seed is given so a known value can be shown; in
+    practice, the seed would not be given.
+
+    >>> random_integer_partition(100, seed=[1, 1, 12, 1, 2, 1, 85, 1])
+    [85, 12, 2, 1]
+    >>> random_integer_partition(10, seed=[1, 2, 3, 1, 5, 1])
+    [5, 3, 1, 1]
+    >>> random_integer_partition(1)
+    [1]
+    """
+    from sympy.core.random import _randint
+
+    n = as_int(n)
+    if n < 1:
+        raise ValueError('n must be a positive integer')
+
+    randint = _randint(seed)
+
+    partition = []
+    while (n > 0):
+        k = randint(1, n)
+        mult = randint(1, n//k)
+        partition.append((k, mult))
+        n -= k*mult
+    partition.sort(reverse=True)
+    partition = flatten([[k]*m for k, m in partition])
+    return partition
+
+
+def RGS_generalized(m):
+    """
+    Computes the m + 1 generalized unrestricted growth strings
+    and returns them as rows in matrix.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.partitions import RGS_generalized
+    >>> RGS_generalized(6)
+    Matrix([
+    [  1,   1,   1,  1,  1, 1, 1],
+    [  1,   2,   3,  4,  5, 6, 0],
+    [  2,   5,  10, 17, 26, 0, 0],
+    [  5,  15,  37, 77,  0, 0, 0],
+    [ 15,  52, 151,  0,  0, 0, 0],
+    [ 52, 203,   0,  0,  0, 0, 0],
+    [203,   0,   0,  0,  0, 0, 0]])
+    """
+    d = zeros(m + 1)
+    for i in range(m + 1):
+        d[0, i] = 1
+
+    for i in range(1, m + 1):
+        for j in range(m):
+            if j <= m - i:
+                d[i, j] = j * d[i - 1, j] + d[i - 1, j + 1]
+            else:
+                d[i, j] = 0
+    return d
+
+
+def RGS_enum(m):
+    """
+    RGS_enum computes the total number of restricted growth strings
+    possible for a superset of size m.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.partitions import RGS_enum
+    >>> from sympy.combinatorics import Partition
+    >>> RGS_enum(4)
+    15
+    >>> RGS_enum(5)
+    52
+    >>> RGS_enum(6)
+    203
+
+    We can check that the enumeration is correct by actually generating
+    the partitions. Here, the 15 partitions of 4 items are generated:
+
+    >>> a = Partition(list(range(4)))
+    >>> s = set()
+    >>> for i in range(20):
+    ...     s.add(a)
+    ...     a += 1
+    ...
+    >>> assert len(s) == 15
+
+    """
+    if (m < 1):
+        return 0
+    elif (m == 1):
+        return 1
+    else:
+        return bell(m)
+
+
+def RGS_unrank(rank, m):
+    """
+    Gives the unranked restricted growth string for a given
+    superset size.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.partitions import RGS_unrank
+    >>> RGS_unrank(14, 4)
+    [0, 1, 2, 3]
+    >>> RGS_unrank(0, 4)
+    [0, 0, 0, 0]
+    """
+    if m < 1:
+        raise ValueError("The superset size must be >= 1")
+    if rank < 0 or RGS_enum(m) <= rank:
+        raise ValueError("Invalid arguments")
+
+    L = [1] * (m + 1)
+    j = 1
+    D = RGS_generalized(m)
+    for i in range(2, m + 1):
+        v = D[m - i, j]
+        cr = j*v
+        if cr <= rank:
+            L[i] = j + 1
+            rank -= cr
+            j += 1
+        else:
+            L[i] = int(rank / v + 1)
+            rank %= v
+    return [x - 1 for x in L[1:]]
+
+
+def RGS_rank(rgs):
+    """
+    Computes the rank of a restricted growth string.
+
+    Examples
+    ========
+
+    >>> from sympy.combinatorics.partitions import RGS_rank, RGS_unrank
+    >>> RGS_rank([0, 1, 2, 1, 3])
+    42
+    >>> RGS_rank(RGS_unrank(4, 7))
+    4
+    """
+    rgs_size = len(rgs)
+    rank = 0
+    D = RGS_generalized(rgs_size)
+    for i in range(1, rgs_size):
+        n = len(rgs[(i + 1):])
+        m = max(rgs[0:i])
+        rank += D[n, m + 1] * rgs[i]
+    return rank

.venv/lib/python3.13/site-packages/sympy/combinatorics/pc_groups.py

@@ -0,0 +1,710 @@
+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. If not exists, (-1,-1) is returned.
+
+        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)
+        >>> w = x1**8
+        >>> collector.subword_index(word, w)
+        (-1, -1)
+
+        """
+        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
+        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

.venv/lib/python3.13/site-packages/sympy/combinatorics/permutations.py

@@ -0,0 +1,3114 @@
+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.copy()
+        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 e != 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]
+                res.extend((first, y) for y in x[nx - 1:0:-1])
+        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

.venv/lib/python3.13/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]