Add files using upload-large-folder tool

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

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

lib/python3.12/site-packages/sympy/algebras/quaternion.py

@@ -0,0 +1,1667 @@
+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
+
+        """
+        # TODO: is this expression correct?
+        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())

lib/python3.12/site-packages/sympy/algebras/tests/test_quaternion.py

@@ -0,0 +1,428 @@
+from sympy.testing.pytest import slow
+from sympy.core.function import diff
+from sympy.core.function import expand
+from sympy.core.numbers import (E, I, Rational, pi)
+from sympy.core.singleton import S
+from sympy.core.symbol import (Symbol, symbols)
+from sympy.functions.elementary.complexes import (Abs, conjugate, im, re, sign)
+from sympy.functions.elementary.exponential import log
+from sympy.functions.elementary.miscellaneous import sqrt
+from sympy.functions.elementary.trigonometric import (acos, asin, cos, sin, atan2, atan)
+from sympy.integrals.integrals import integrate
+from sympy.matrices.dense import Matrix
+from sympy.simplify import simplify
+from sympy.simplify.trigsimp import trigsimp
+from sympy.algebras.quaternion import Quaternion
+from sympy.testing.pytest import raises
+import math
+from itertools import permutations, product
+
+w, x, y, z = symbols('w:z')
+phi = symbols('phi')
+
+def test_quaternion_construction():
+    q = Quaternion(w, x, y, z)
+    assert q + q == Quaternion(2*w, 2*x, 2*y, 2*z)
+
+    q2 = Quaternion.from_axis_angle((sqrt(3)/3, sqrt(3)/3, sqrt(3)/3),
+                                    pi*Rational(2, 3))
+    assert q2 == Quaternion(S.Half, S.Half,
+                            S.Half, S.Half)
+
+    M = Matrix([[cos(phi), -sin(phi), 0], [sin(phi), cos(phi), 0], [0, 0, 1]])
+    q3 = trigsimp(Quaternion.from_rotation_matrix(M))
+    assert q3 == Quaternion(
+        sqrt(2)*sqrt(cos(phi) + 1)/2, 0, 0, sqrt(2 - 2*cos(phi))*sign(sin(phi))/2)
+
+    nc = Symbol('nc', commutative=False)
+    raises(ValueError, lambda: Quaternion(w, x, nc, z))
+
+
+def test_quaternion_construction_norm():
+    q1 = Quaternion(*symbols('a:d'))
+
+    q2 = Quaternion(w, x, y, z)
+    assert expand((q1*q2).norm()**2 - (q1.norm()**2 * q2.norm()**2)) == 0
+
+    q3 = Quaternion(w, x, y, z, norm=1)
+    assert (q1 * q3).norm() == q1.norm()
+
+
+def test_issue_25254():
+    # calculating the inverse cached the norm which caused problems
+    # when multiplying
+    p = Quaternion(1, 0, 0, 0)
+    q = Quaternion.from_axis_angle((1, 1, 1), 3 * math.pi/4)
+    qi = q.inverse()  # this operation cached the norm
+    test = q * p * qi
+    assert ((test - p).norm() < 1E-10)
+
+
+def test_to_and_from_Matrix():
+    q = Quaternion(w, x, y, z)
+    q_full = Quaternion.from_Matrix(q.to_Matrix())
+    q_vect = Quaternion.from_Matrix(q.to_Matrix(True))
+    assert (q - q_full).is_zero_quaternion()
+    assert (q.vector_part() - q_vect).is_zero_quaternion()
+
+
+def test_product_matrices():
+    q1 = Quaternion(w, x, y, z)
+    q2 = Quaternion(*(symbols("a:d")))
+    assert (q1 * q2).to_Matrix() == q1.product_matrix_left * q2.to_Matrix()
+    assert (q1 * q2).to_Matrix() == q2.product_matrix_right * q1.to_Matrix()
+
+    R1 = (q1.product_matrix_left * q1.product_matrix_right.T)[1:, 1:]
+    R2 = simplify(q1.to_rotation_matrix()*q1.norm()**2)
+    assert R1 == R2
+
+
+def test_quaternion_axis_angle():
+
+    test_data = [ # axis, angle, expected_quaternion
+        ((1, 0, 0), 0, (1, 0, 0, 0)),
+        ((1, 0, 0), pi/2, (sqrt(2)/2, sqrt(2)/2, 0, 0)),
+        ((0, 1, 0), pi/2, (sqrt(2)/2, 0, sqrt(2)/2, 0)),
+        ((0, 0, 1), pi/2, (sqrt(2)/2, 0, 0, sqrt(2)/2)),
+        ((1, 0, 0), pi, (0, 1, 0, 0)),
+        ((0, 1, 0), pi, (0, 0, 1, 0)),
+        ((0, 0, 1), pi, (0, 0, 0, 1)),
+        ((1, 1, 1), pi, (0, 1/sqrt(3),1/sqrt(3),1/sqrt(3))),
+        ((sqrt(3)/3, sqrt(3)/3, sqrt(3)/3), pi*2/3, (S.Half, S.Half, S.Half, S.Half))
+    ]
+
+    for axis, angle, expected in test_data:
+        assert Quaternion.from_axis_angle(axis, angle) == Quaternion(*expected)
+
+
+def test_quaternion_axis_angle_simplification():
+    result = Quaternion.from_axis_angle((1, 2, 3), asin(4))
+    assert result.a == cos(asin(4)/2)
+    assert result.b == sqrt(14)*sin(asin(4)/2)/14
+    assert result.c == sqrt(14)*sin(asin(4)/2)/7
+    assert result.d == 3*sqrt(14)*sin(asin(4)/2)/14
+
+def test_quaternion_complex_real_addition():
+    a = symbols("a", complex=True)
+    b = symbols("b", real=True)
+    # This symbol is not complex:
+    c = symbols("c", commutative=False)
+
+    q = Quaternion(w, x, y, z)
+    assert a + q == Quaternion(w + re(a), x + im(a), y, z)
+    assert 1 + q == Quaternion(1 + w, x, y, z)
+    assert I + q == Quaternion(w, 1 + x, y, z)
+    assert b + q == Quaternion(w + b, x, y, z)
+    raises(ValueError, lambda: c + q)
+    raises(ValueError, lambda: q * c)
+    raises(ValueError, lambda: c * q)
+
+    assert -q == Quaternion(-w, -x, -y, -z)
+
+    q1 = Quaternion(3 + 4*I, 2 + 5*I, 0, 7 + 8*I, real_field = False)
+    q2 = Quaternion(1, 4, 7, 8)
+
+    assert q1 + (2 + 3*I) == Quaternion(5 + 7*I, 2 + 5*I, 0, 7 + 8*I)
+    assert q2 + (2 + 3*I) == Quaternion(3, 7, 7, 8)
+    assert q1 * (2 + 3*I) == \
+    Quaternion((2 + 3*I)*(3 + 4*I), (2 + 3*I)*(2 + 5*I), 0, (2 + 3*I)*(7 + 8*I))
+    assert q2 * (2 + 3*I) == Quaternion(-10, 11, 38, -5)
+
+    q1 = Quaternion(1, 2, 3, 4)
+    q0 = Quaternion(0, 0, 0, 0)
+    assert q1 + q0 == q1
+    assert q1 - q0 == q1
+    assert q1 - q1 == q0
+
+
+def test_quaternion_subs():
+    q = Quaternion.from_axis_angle((0, 0, 1), phi)
+    assert q.subs(phi, 0) == Quaternion(1, 0, 0, 0)
+
+
+def test_quaternion_evalf():
+    assert (Quaternion(sqrt(2), 0, 0, sqrt(3)).evalf() ==
+            Quaternion(sqrt(2).evalf(), 0, 0, sqrt(3).evalf()))
+    assert (Quaternion(1/sqrt(2), 0, 0, 1/sqrt(2)).evalf() ==
+            Quaternion((1/sqrt(2)).evalf(), 0, 0, (1/sqrt(2)).evalf()))
+
+
+def test_quaternion_functions():
+    q = Quaternion(w, x, y, z)
+    q1 = Quaternion(1, 2, 3, 4)
+    q0 = Quaternion(0, 0, 0, 0)
+
+    assert conjugate(q) == Quaternion(w, -x, -y, -z)
+    assert q.norm() == sqrt(w**2 + x**2 + y**2 + z**2)
+    assert q.normalize() == Quaternion(w, x, y, z) / sqrt(w**2 + x**2 + y**2 + z**2)
+    assert q.inverse() == Quaternion(w, -x, -y, -z) / (w**2 + x**2 + y**2 + z**2)
+    assert q.inverse() == q.pow(-1)
+    raises(ValueError, lambda: q0.inverse())
+    assert q.pow(2) == Quaternion(w**2 - x**2 - y**2 - z**2, 2*w*x, 2*w*y, 2*w*z)
+    assert q**(2) == Quaternion(w**2 - x**2 - y**2 - z**2, 2*w*x, 2*w*y, 2*w*z)
+    assert q1.pow(-2) == Quaternion(
+        Rational(-7, 225), Rational(-1, 225), Rational(-1, 150), Rational(-2, 225))
+    assert q1**(-2) == Quaternion(
+        Rational(-7, 225), Rational(-1, 225), Rational(-1, 150), Rational(-2, 225))
+    assert q1.pow(-0.5) == NotImplemented
+    raises(TypeError, lambda: q1**(-0.5))
+
+    assert q1.exp() == \
+    Quaternion(E * cos(sqrt(29)),
+               2 * sqrt(29) * E * sin(sqrt(29)) / 29,
+               3 * sqrt(29) * E * sin(sqrt(29)) / 29,
+               4 * sqrt(29) * E * sin(sqrt(29)) / 29)
+    assert q1.log() == \
+    Quaternion(log(sqrt(30)),
+               2 * sqrt(29) * acos(sqrt(30)/30) / 29,
+               3 * sqrt(29) * acos(sqrt(30)/30) / 29,
+               4 * sqrt(29) * acos(sqrt(30)/30) / 29)
+
+    assert q1.pow_cos_sin(2) == \
+    Quaternion(30 * cos(2 * acos(sqrt(30)/30)),
+               60 * sqrt(29) * sin(2 * acos(sqrt(30)/30)) / 29,
+               90 * sqrt(29) * sin(2 * acos(sqrt(30)/30)) / 29,
+               120 * sqrt(29) * sin(2 * acos(sqrt(30)/30)) / 29)
+
+    assert diff(Quaternion(x, x, x, x), x) == Quaternion(1, 1, 1, 1)
+
+    assert integrate(Quaternion(x, x, x, x), x) == \
+    Quaternion(x**2 / 2, x**2 / 2, x**2 / 2, x**2 / 2)
+
+    assert Quaternion.rotate_point((1, 1, 1), q1) == (S.One / 5, 1, S(7) / 5)
+    n = Symbol('n')
+    raises(TypeError, lambda: q1**n)
+    n = Symbol('n', integer=True)
+    raises(TypeError, lambda: q1**n)
+
+    assert Quaternion(22, 23, 55, 8).scalar_part() == 22
+    assert Quaternion(w, x, y, z).scalar_part() == w
+
+    assert Quaternion(22, 23, 55, 8).vector_part() == Quaternion(0, 23, 55, 8)
+    assert Quaternion(w, x, y, z).vector_part() == Quaternion(0, x, y, z)
+
+    assert q1.axis() == Quaternion(0, 2*sqrt(29)/29, 3*sqrt(29)/29, 4*sqrt(29)/29)
+    assert q1.axis().pow(2) == Quaternion(-1, 0, 0, 0)
+    assert q0.axis().scalar_part() == 0
+    assert (q.axis() == Quaternion(0,
+                                   x/sqrt(x**2 + y**2 + z**2),
+                                   y/sqrt(x**2 + y**2 + z**2),
+                                   z/sqrt(x**2 + y**2 + z**2)))
+
+    assert q0.is_pure() is True
+    assert q1.is_pure() is False
+    assert Quaternion(0, 0, 0, 3).is_pure() is True
+    assert Quaternion(0, 2, 10, 3).is_pure() is True
+    assert Quaternion(w, 2, 10, 3).is_pure() is None
+
+    assert q1.angle() == 2*atan(sqrt(29))
+    assert q.angle() == 2*atan2(sqrt(x**2 + y**2 + z**2), w)
+
+    assert Quaternion.arc_coplanar(q1, Quaternion(2, 4, 6, 8)) is True
+    assert Quaternion.arc_coplanar(q1, Quaternion(1, -2, -3, -4)) is True
+    assert Quaternion.arc_coplanar(q1, Quaternion(1, 8, 12, 16)) is True
+    assert Quaternion.arc_coplanar(q1, Quaternion(1, 2, 3, 4)) is True
+    assert Quaternion.arc_coplanar(q1, Quaternion(w, 4, 6, 8)) is True
+    assert Quaternion.arc_coplanar(q1, Quaternion(2, 7, 4, 1)) is False
+    assert Quaternion.arc_coplanar(q1, Quaternion(w, x, y, z)) is None
+    raises(ValueError, lambda: Quaternion.arc_coplanar(q1, q0))
+
+    assert Quaternion.vector_coplanar(
+        Quaternion(0, 8, 12, 16),
+        Quaternion(0, 4, 6, 8),
+        Quaternion(0, 2, 3, 4)) is True
+    assert Quaternion.vector_coplanar(
+        Quaternion(0, 0, 0, 0), Quaternion(0, 4, 6, 8), Quaternion(0, 2, 3, 4)) is True
+    assert Quaternion.vector_coplanar(
+        Quaternion(0, 8, 2, 6), Quaternion(0, 1, 6, 6), Quaternion(0, 0, 3, 4)) is False
+    assert Quaternion.vector_coplanar(
+        Quaternion(0, 1, 3, 4),
+        Quaternion(0, 4, w, 6),
+        Quaternion(0, 6, 8, 1)) is None
+    raises(ValueError, lambda:
+        Quaternion.vector_coplanar(q0, Quaternion(0, 4, 6, 8), q1))
+
+    assert Quaternion(0, 1, 2, 3).parallel(Quaternion(0, 2, 4, 6)) is True
+    assert Quaternion(0, 1, 2, 3).parallel(Quaternion(0, 2, 2, 6)) is False
+    assert Quaternion(0, 1, 2, 3).parallel(Quaternion(w, x, y, 6)) is None
+    raises(ValueError, lambda: q0.parallel(q1))
+
+    assert Quaternion(0, 1, 2, 3).orthogonal(Quaternion(0, -2, 1, 0)) is True
+    assert Quaternion(0, 2, 4, 7).orthogonal(Quaternion(0, 2, 2, 6)) is False
+    assert Quaternion(0, 2, 4, 7).orthogonal(Quaternion(w, x, y, 6)) is None
+    raises(ValueError, lambda: q0.orthogonal(q1))
+
+    assert q1.index_vector() == Quaternion(
+        0, 2*sqrt(870)/29,
+        3*sqrt(870)/29,
+        4*sqrt(870)/29)
+    assert Quaternion(0, 3, 9, 4).index_vector() == Quaternion(0, 3, 9, 4)
+
+    assert Quaternion(4, 3, 9, 4).mensor() == log(sqrt(122))
+    assert Quaternion(3, 3, 0, 2).mensor() == log(sqrt(22))
+
+    assert q0.is_zero_quaternion() is True
+    assert q1.is_zero_quaternion() is False
+    assert Quaternion(w, 0, 0, 0).is_zero_quaternion() is None
+
+def test_quaternion_conversions():
+    q1 = Quaternion(1, 2, 3, 4)
+
+    assert q1.to_axis_angle() == ((2 * sqrt(29)/29,
+                                   3 * sqrt(29)/29,
+                                   4 * sqrt(29)/29),
+                                   2 * acos(sqrt(30)/30))
+
+    assert (q1.to_rotation_matrix() ==
+            Matrix([[Rational(-2, 3), Rational(2, 15), Rational(11, 15)],
+                    [Rational(2, 3), Rational(-1, 3), Rational(2, 3)],
+                    [Rational(1, 3), Rational(14, 15), Rational(2, 15)]]))
+
+    assert (q1.to_rotation_matrix((1, 1, 1)) ==
+            Matrix([
+                [Rational(-2, 3), Rational(2, 15), Rational(11, 15), Rational(4, 5)],
+                [Rational(2, 3), Rational(-1, 3), Rational(2, 3), S.Zero],
+                [Rational(1, 3), Rational(14, 15), Rational(2, 15), Rational(-2, 5)],
+                [S.Zero, S.Zero, S.Zero, S.One]]))
+
+    theta = symbols("theta", real=True)
+    q2 = Quaternion(cos(theta/2), 0, 0, sin(theta/2))
+
+    assert trigsimp(q2.to_rotation_matrix()) == Matrix([
+                                               [cos(theta), -sin(theta), 0],
+                                               [sin(theta),  cos(theta), 0],
+                                               [0,           0,          1]])
+
+    assert q2.to_axis_angle() == ((0, 0, sin(theta/2)/Abs(sin(theta/2))),
+                                   2*acos(cos(theta/2)))
+
+    assert trigsimp(q2.to_rotation_matrix((1, 1, 1))) == Matrix([
+               [cos(theta), -sin(theta), 0, sin(theta) - cos(theta) + 1],
+               [sin(theta),  cos(theta), 0, -sin(theta) - cos(theta) + 1],
+               [0,           0,          1,  0],
+               [0,           0,          0,  1]])
+
+
+def test_rotation_matrix_homogeneous():
+    q = Quaternion(w, x, y, z)
+    R1 = q.to_rotation_matrix(homogeneous=True) * q.norm()**2
+    R2 = simplify(q.to_rotation_matrix(homogeneous=False) * q.norm()**2)
+    assert R1 == R2
+
+
+def test_quaternion_rotation_iss1593():
+    """
+    There was a sign mistake in the definition,
+    of the rotation matrix. This tests that particular sign mistake.
+    See issue 1593 for reference.
+    See wikipedia
+    https://en.wikipedia.org/wiki/Quaternions_and_spatial_rotation#Quaternion-derived_rotation_matrix
+    for the correct definition
+    """
+    q = Quaternion(cos(phi/2), sin(phi/2), 0, 0)
+    assert(trigsimp(q.to_rotation_matrix()) == Matrix([
+                [1,        0,         0],
+                [0, cos(phi), -sin(phi)],
+                [0, sin(phi),  cos(phi)]]))
+
+
+def test_quaternion_multiplication():
+    q1 = Quaternion(3 + 4*I, 2 + 5*I, 0, 7 + 8*I, real_field = False)
+    q2 = Quaternion(1, 2, 3, 5)
+    q3 = Quaternion(1, 1, 1, y)
+
+    assert Quaternion._generic_mul(S(4), S.One) == 4
+    assert (Quaternion._generic_mul(S(4), q1) ==
+            Quaternion(12 + 16*I, 8 + 20*I, 0, 28 + 32*I))
+    assert q2.mul(2) == Quaternion(2, 4, 6, 10)
+    assert q2.mul(q3) == Quaternion(-5*y - 4, 3*y - 2, 9 - 2*y, y + 4)
+    assert q2.mul(q3) == q2*q3
+
+    z = symbols('z', complex=True)
+    z_quat = Quaternion(re(z), im(z), 0, 0)
+    q = Quaternion(*symbols('q:4', real=True))
+
+    assert z * q == z_quat * q
+    assert q * z == q * z_quat
+
+
+def test_issue_16318():
+    #for rtruediv
+    q0 = Quaternion(0, 0, 0, 0)
+    raises(ValueError, lambda: 1/q0)
+    #for rotate_point
+    q = Quaternion(1, 2, 3, 4)
+    (axis, angle) = q.to_axis_angle()
+    assert Quaternion.rotate_point((1, 1, 1), (axis, angle)) == (S.One / 5, 1, S(7) / 5)
+    #test for to_axis_angle
+    q = Quaternion(-1, 1, 1, 1)
+    axis = (-sqrt(3)/3, -sqrt(3)/3, -sqrt(3)/3)
+    angle = 2*pi/3
+    assert (axis, angle) == q.to_axis_angle()
+
+
+@slow
+def test_to_euler():
+    q = Quaternion(w, x, y, z)
+    q_normalized = q.normalize()
+
+    seqs = ['zxy', 'zyx', 'zyz', 'zxz']
+    seqs += [seq.upper() for seq in seqs]
+
+    for seq in seqs:
+        euler_from_q = q.to_euler(seq)
+        q_back = simplify(Quaternion.from_euler(euler_from_q, seq))
+        assert q_back == q_normalized
+
+
+def test_to_euler_iss24504():
+    """
+    There was a mistake in the degenerate case testing
+    See issue 24504 for reference.
+    """
+    q = Quaternion.from_euler((phi, 0, 0), 'zyz')
+    assert trigsimp(q.to_euler('zyz'), inverse=True) == (phi, 0, 0)
+
+
+def test_to_euler_numerical_singilarities():
+
+    def test_one_case(angles, seq):
+        q = Quaternion.from_euler(angles, seq)
+        assert q.to_euler(seq) == angles
+
+    # symmetric
+    test_one_case((pi/2,  0, 0), 'zyz')
+    test_one_case((pi/2,  0, 0), 'ZYZ')
+    test_one_case((pi/2,  pi, 0), 'zyz')
+    test_one_case((pi/2,  pi, 0), 'ZYZ')
+
+    # asymmetric
+    test_one_case((pi/2,  pi/2, 0), 'zyx')
+    test_one_case((pi/2,  -pi/2, 0), 'zyx')
+    test_one_case((pi/2,  pi/2, 0), 'ZYX')
+    test_one_case((pi/2,  -pi/2, 0), 'ZYX')
+
+
+@slow
+def test_to_euler_options():
+    def test_one_case(q):
+        angles1 = Matrix(q.to_euler(seq, True, True))
+        angles2 = Matrix(q.to_euler(seq, False, False))
+        angle_errors = simplify(angles1-angles2).evalf()
+        for angle_error in angle_errors:
+            # forcing angles to set {-pi, pi}
+            angle_error = (angle_error + pi) % (2 * pi) - pi
+            assert angle_error < 10e-7
+
+    for xyz in ('xyz', 'XYZ'):
+        for seq_tuple in permutations(xyz):
+            for symmetric in (True, False):
+                if symmetric:
+                    seq = ''.join([seq_tuple[0], seq_tuple[1], seq_tuple[0]])
+                else:
+                    seq = ''.join(seq_tuple)
+
+                for elements in product([-1, 0, 1], repeat=4):
+                    q = Quaternion(*elements)
+                    if not q.is_zero_quaternion():
+                        test_one_case(q)

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

@@ -0,0 +1,25 @@
+"""Calculus-related methods."""
+
+from .euler import euler_equations
+from .singularities import (singularities, is_increasing,
+                            is_strictly_increasing, is_decreasing,
+                            is_strictly_decreasing, is_monotonic)
+from .finite_diff import finite_diff_weights, apply_finite_diff, differentiate_finite
+from .util import (periodicity, not_empty_in, is_convex,
+                   stationary_points, minimum, maximum)
+from .accumulationbounds import AccumBounds
+
+__all__ = [
+'euler_equations',
+
+'singularities', 'is_increasing',
+'is_strictly_increasing', 'is_decreasing',
+'is_strictly_decreasing', 'is_monotonic',
+
+'finite_diff_weights', 'apply_finite_diff', 'differentiate_finite',
+
+'periodicity', 'not_empty_in', 'is_convex', 'stationary_points',
+'minimum', 'maximum',
+
+'AccumBounds'
+]

lib/python3.12/site-packages/sympy/calculus/accumulationbounds.py

@@ -0,0 +1,804 @@
+from sympy.core import Add, Mul, Pow, S
+from sympy.core.basic import Basic
+from sympy.core.expr import Expr
+from sympy.core.numbers import _sympifyit, oo, zoo
+from sympy.core.relational import is_le, is_lt, is_ge, is_gt
+from sympy.core.sympify import _sympify
+from sympy.functions.elementary.miscellaneous import Min, Max
+from sympy.logic.boolalg import And
+from sympy.multipledispatch import dispatch
+from sympy.series.order import Order
+from sympy.sets.sets import FiniteSet
+
+
+class AccumulationBounds(Expr):
+    r"""An accumulation bounds.
+
+    # Note AccumulationBounds has an alias: AccumBounds
+
+    AccumulationBounds represent an interval `[a, b]`, which is always closed
+    at the ends. Here `a` and `b` can be any value from extended real numbers.
+
+    The intended meaning of AccummulationBounds is to give an approximate
+    location of the accumulation points of a real function at a limit point.
+
+    Let `a` and `b` be reals such that `a \le b`.
+
+    `\left\langle a, b\right\rangle = \{x \in \mathbb{R} \mid a \le x \le b\}`
+
+    `\left\langle -\infty, b\right\rangle = \{x \in \mathbb{R} \mid x \le b\} \cup \{-\infty, \infty\}`
+
+    `\left\langle a, \infty \right\rangle = \{x \in \mathbb{R} \mid a \le x\} \cup \{-\infty, \infty\}`
+
+    `\left\langle -\infty, \infty \right\rangle = \mathbb{R} \cup \{-\infty, \infty\}`
+
+    ``oo`` and ``-oo`` are added to the second and third definition respectively,
+    since if either ``-oo`` or ``oo`` is an argument, then the other one should
+    be included (though not as an end point). This is forced, since we have,
+    for example, ``1/AccumBounds(0, 1) = AccumBounds(1, oo)``, and the limit at
+    `0` is not one-sided. As `x` tends to `0-`, then `1/x \rightarrow -\infty`, so `-\infty`
+    should be interpreted as belonging to ``AccumBounds(1, oo)`` though it need
+    not appear explicitly.
+
+    In many cases it suffices to know that the limit set is bounded.
+    However, in some other cases more exact information could be useful.
+    For example, all accumulation values of `\cos(x) + 1` are non-negative.
+    (``AccumBounds(-1, 1) + 1 = AccumBounds(0, 2)``)
+
+    A AccumulationBounds object is defined to be real AccumulationBounds,
+    if its end points are finite reals.
+
+    Let `X`, `Y` be real AccumulationBounds, then their sum, difference,
+    product are defined to be the following sets:
+
+    `X + Y = \{ x+y \mid x \in X \cap y \in Y\}`
+
+    `X - Y = \{ x-y \mid x \in X \cap y \in Y\}`
+
+    `X \times Y = \{ x \times y \mid x \in X \cap y \in Y\}`
+
+    When an AccumBounds is raised to a negative power, if 0 is contained
+    between the bounds then an infinite range is returned, otherwise if an
+    endpoint is 0 then a semi-infinite range with consistent sign will be returned.
+
+    AccumBounds in expressions behave a lot like Intervals but the
+    semantics are not necessarily the same. Division (or exponentiation
+    to a negative integer power) could be handled with *intervals* by
+    returning a union of the results obtained after splitting the
+    bounds between negatives and positives, but that is not done with
+    AccumBounds. In addition, bounds are assumed to be independent of
+    each other; if the same bound is used in more than one place in an
+    expression, the result may not be the supremum or infimum of the
+    expression (see below). Finally, when a boundary is ``1``,
+    exponentiation to the power of ``oo`` yields ``oo``, neither
+    ``1`` nor ``nan``.
+
+    Examples
+    ========
+
+    >>> from sympy import AccumBounds, sin, exp, log, pi, E, S, oo
+    >>> from sympy.abc import x
+
+    >>> AccumBounds(0, 1) + AccumBounds(1, 2)
+    AccumBounds(1, 3)
+
+    >>> AccumBounds(0, 1) - AccumBounds(0, 2)
+    AccumBounds(-2, 1)
+
+    >>> AccumBounds(-2, 3)*AccumBounds(-1, 1)
+    AccumBounds(-3, 3)
+
+    >>> AccumBounds(1, 2)*AccumBounds(3, 5)
+    AccumBounds(3, 10)
+
+    The exponentiation of AccumulationBounds is defined
+    as follows:
+
+    If 0 does not belong to `X` or `n > 0` then
+
+    `X^n = \{ x^n \mid x \in X\}`
+
+    >>> AccumBounds(1, 4)**(S(1)/2)
+    AccumBounds(1, 2)
+
+    otherwise, an infinite or semi-infinite result is obtained:
+
+    >>> 1/AccumBounds(-1, 1)
+    AccumBounds(-oo, oo)
+    >>> 1/AccumBounds(0, 2)
+    AccumBounds(1/2, oo)
+    >>> 1/AccumBounds(-oo, 0)
+    AccumBounds(-oo, 0)
+
+    A boundary of 1 will always generate all nonnegatives:
+
+    >>> AccumBounds(1, 2)**oo
+    AccumBounds(0, oo)
+    >>> AccumBounds(0, 1)**oo
+    AccumBounds(0, oo)
+
+    If the exponent is itself an AccumulationBounds or is not an
+    integer then unevaluated results will be returned unless the base
+    values are positive:
+
+    >>> AccumBounds(2, 3)**AccumBounds(-1, 2)
+    AccumBounds(1/3, 9)
+    >>> AccumBounds(-2, 3)**AccumBounds(-1, 2)
+    AccumBounds(-2, 3)**AccumBounds(-1, 2)
+
+    >>> AccumBounds(-2, -1)**(S(1)/2)
+    sqrt(AccumBounds(-2, -1))
+
+    Note: `\left\langle a, b\right\rangle^2` is not same as `\left\langle a, b\right\rangle \times \left\langle a, b\right\rangle`
+
+    >>> AccumBounds(-1, 1)**2
+    AccumBounds(0, 1)
+
+    >>> AccumBounds(1, 3) < 4
+    True
+
+    >>> AccumBounds(1, 3) < -1
+    False
+
+    Some elementary functions can also take AccumulationBounds as input.
+    A function `f` evaluated for some real AccumulationBounds `\left\langle a, b \right\rangle`
+    is defined as `f(\left\langle a, b\right\rangle) = \{ f(x) \mid a \le x \le b \}`
+
+    >>> sin(AccumBounds(pi/6, pi/3))
+    AccumBounds(1/2, sqrt(3)/2)
+
+    >>> exp(AccumBounds(0, 1))
+    AccumBounds(1, E)
+
+    >>> log(AccumBounds(1, E))
+    AccumBounds(0, 1)
+
+    Some symbol in an expression can be substituted for a AccumulationBounds
+    object. But it does not necessarily evaluate the AccumulationBounds for
+    that expression.
+
+    The same expression can be evaluated to different values depending upon
+    the form it is used for substitution since each instance of an
+    AccumulationBounds is considered independent. For example:
+
+    >>> (x**2 + 2*x + 1).subs(x, AccumBounds(-1, 1))
+    AccumBounds(-1, 4)
+
+    >>> ((x + 1)**2).subs(x, AccumBounds(-1, 1))
+    AccumBounds(0, 4)
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Interval_arithmetic
+
+    .. [2] https://fab.cba.mit.edu/classes/S62.12/docs/Hickey_interval.pdf
+
+    Notes
+    =====
+
+    Do not use ``AccumulationBounds`` for floating point interval arithmetic
+    calculations, use ``mpmath.iv`` instead.
+    """
+
+    is_extended_real = True
+    is_number = False
+
+    def __new__(cls, min, max):
+
+        min = _sympify(min)
+        max = _sympify(max)
+
+        # Only allow real intervals (use symbols with 'is_extended_real=True').
+        if not min.is_extended_real or not max.is_extended_real:
+            raise ValueError("Only real AccumulationBounds are supported")
+
+        if max == min:
+            return max
+
+        # Make sure that the created AccumBounds object will be valid.
+        if max.is_number and min.is_number:
+            bad = max.is_comparable and min.is_comparable and max < min
+        else:
+            bad = (max - min).is_extended_negative
+        if bad:
+            raise ValueError(
+                "Lower limit should be smaller than upper limit")
+
+        return Basic.__new__(cls, min, max)
+
+    # setting the operation priority
+    _op_priority = 11.0
+
+    def _eval_is_real(self):
+        if self.min.is_real and self.max.is_real:
+            return True
+
+    @property
+    def min(self):
+        """
+        Returns the minimum possible value attained by AccumulationBounds
+        object.
+
+        Examples
+        ========
+
+        >>> from sympy import AccumBounds
+        >>> AccumBounds(1, 3).min
+        1
+
+        """
+        return self.args[0]
+
+    @property
+    def max(self):
+        """
+        Returns the maximum possible value attained by AccumulationBounds
+        object.
+
+        Examples
+        ========
+
+        >>> from sympy import AccumBounds
+        >>> AccumBounds(1, 3).max
+        3
+
+        """
+        return self.args[1]
+
+    @property
+    def delta(self):
+        """
+        Returns the difference of maximum possible value attained by
+        AccumulationBounds object and minimum possible value attained
+        by AccumulationBounds object.
+
+        Examples
+        ========
+
+        >>> from sympy import AccumBounds
+        >>> AccumBounds(1, 3).delta
+        2
+
+        """
+        return self.max - self.min
+
+    @property
+    def mid(self):
+        """
+        Returns the mean of maximum possible value attained by
+        AccumulationBounds object and minimum possible value
+        attained by AccumulationBounds object.
+
+        Examples
+        ========
+
+        >>> from sympy import AccumBounds
+        >>> AccumBounds(1, 3).mid
+        2
+
+        """
+        return (self.min + self.max) / 2
+
+    @_sympifyit('other', NotImplemented)
+    def _eval_power(self, other):
+        return self.__pow__(other)
+
+    @_sympifyit('other', NotImplemented)
+    def __add__(self, other):
+        if isinstance(other, Expr):
+            if isinstance(other, AccumBounds):
+                return AccumBounds(
+                    Add(self.min, other.min),
+                    Add(self.max, other.max))
+            if other is S.Infinity and self.min is S.NegativeInfinity or \
+                    other is S.NegativeInfinity and self.max is S.Infinity:
+                return AccumBounds(-oo, oo)
+            elif other.is_extended_real:
+                if self.min is S.NegativeInfinity and self.max is S.Infinity:
+                    return AccumBounds(-oo, oo)
+                elif self.min is S.NegativeInfinity:
+                    return AccumBounds(-oo, self.max + other)
+                elif self.max is S.Infinity:
+                    return AccumBounds(self.min + other, oo)
+                else:
+                    return AccumBounds(Add(self.min, other), Add(self.max, other))
+            return Add(self, other, evaluate=False)
+        return NotImplemented
+
+    __radd__ = __add__
+
+    def __neg__(self):
+        return AccumBounds(-self.max, -self.min)
+
+    @_sympifyit('other', NotImplemented)
+    def __sub__(self, other):
+        if isinstance(other, Expr):
+            if isinstance(other, AccumBounds):
+                return AccumBounds(
+                    Add(self.min, -other.max),
+                    Add(self.max, -other.min))
+            if other is S.NegativeInfinity and self.min is S.NegativeInfinity or \
+                    other is S.Infinity and self.max is S.Infinity:
+                return AccumBounds(-oo, oo)
+            elif other.is_extended_real:
+                if self.min is S.NegativeInfinity and self.max is S.Infinity:
+                    return AccumBounds(-oo, oo)
+                elif self.min is S.NegativeInfinity:
+                    return AccumBounds(-oo, self.max - other)
+                elif self.max is S.Infinity:
+                    return AccumBounds(self.min - other, oo)
+                else:
+                    return AccumBounds(
+                        Add(self.min, -other),
+                        Add(self.max, -other))
+            return Add(self, -other, evaluate=False)
+        return NotImplemented
+
+    @_sympifyit('other', NotImplemented)
+    def __rsub__(self, other):
+        return self.__neg__() + other
+
+    @_sympifyit('other', NotImplemented)
+    def __mul__(self, other):
+        if self.args == (-oo, oo):
+            return self
+        if isinstance(other, Expr):
+            if isinstance(other, AccumBounds):
+                if other.args == (-oo, oo):
+                    return other
+                v = set()
+                for a in self.args:
+                    vi = other*a
+                    v.update(vi.args or (vi,))
+                return AccumBounds(Min(*v), Max(*v))
+            if other is S.Infinity:
+                if self.min.is_zero:
+                    return AccumBounds(0, oo)
+                if self.max.is_zero:
+                    return AccumBounds(-oo, 0)
+            if other is S.NegativeInfinity:
+                if self.min.is_zero:
+                    return AccumBounds(-oo, 0)
+                if self.max.is_zero:
+                    return AccumBounds(0, oo)
+            if other.is_extended_real:
+                if other.is_zero:
+                    if self.max is S.Infinity:
+                        return AccumBounds(0, oo)
+                    if self.min is S.NegativeInfinity:
+                        return AccumBounds(-oo, 0)
+                    return S.Zero
+                if other.is_extended_positive:
+                    return AccumBounds(
+                        Mul(self.min, other),
+                        Mul(self.max, other))
+                elif other.is_extended_negative:
+                    return AccumBounds(
+                        Mul(self.max, other),
+                        Mul(self.min, other))
+            if isinstance(other, Order):
+                return other
+            return Mul(self, other, evaluate=False)
+        return NotImplemented
+
+    __rmul__ = __mul__
+
+    @_sympifyit('other', NotImplemented)
+    def __truediv__(self, other):
+        if isinstance(other, Expr):
+            if isinstance(other, AccumBounds):
+                if other.min.is_positive or other.max.is_negative:
+                    return self * AccumBounds(1/other.max, 1/other.min)
+
+                if (self.min.is_extended_nonpositive and self.max.is_extended_nonnegative and
+                    other.min.is_extended_nonpositive and other.max.is_extended_nonnegative):
+                    if self.min.is_zero and other.min.is_zero:
+                        return AccumBounds(0, oo)
+                    if self.max.is_zero and other.min.is_zero:
+                        return AccumBounds(-oo, 0)
+                    return AccumBounds(-oo, oo)
+
+                if self.max.is_extended_negative:
+                    if other.min.is_extended_negative:
+                        if other.max.is_zero:
+                            return AccumBounds(self.max / other.min, oo)
+                        if other.max.is_extended_positive:
+                            # if we were dealing with intervals we would return
+                            # Union(Interval(-oo, self.max/other.max),
+                            #       Interval(self.max/other.min, oo))
+                            return AccumBounds(-oo, oo)
+
+                    if other.min.is_zero and other.max.is_extended_positive:
+                        return AccumBounds(-oo, self.max / other.max)
+
+                if self.min.is_extended_positive:
+                    if other.min.is_extended_negative:
+                        if other.max.is_zero:
+                            return AccumBounds(-oo, self.min / other.min)
+                        if other.max.is_extended_positive:
+                            # if we were dealing with intervals we would return
+                            # Union(Interval(-oo, self.min/other.min),
+                            #       Interval(self.min/other.max, oo))
+                            return AccumBounds(-oo, oo)
+
+                    if other.min.is_zero and other.max.is_extended_positive:
+                        return AccumBounds(self.min / other.max, oo)
+
+            elif other.is_extended_real:
+                if other in (S.Infinity, S.NegativeInfinity):
+                    if self == AccumBounds(-oo, oo):
+                        return AccumBounds(-oo, oo)
+                    if self.max is S.Infinity:
+                        return AccumBounds(Min(0, other), Max(0, other))
+                    if self.min is S.NegativeInfinity:
+                        return AccumBounds(Min(0, -other), Max(0, -other))
+                if other.is_extended_positive:
+                    return AccumBounds(self.min / other, self.max / other)
+                elif other.is_extended_negative:
+                    return AccumBounds(self.max / other, self.min / other)
+            if (1 / other) is S.ComplexInfinity:
+                return Mul(self, 1 / other, evaluate=False)
+            else:
+                return Mul(self, 1 / other)
+
+        return NotImplemented
+
+    @_sympifyit('other', NotImplemented)
+    def __rtruediv__(self, other):
+        if isinstance(other, Expr):
+            if other.is_extended_real:
+                if other.is_zero:
+                    return S.Zero
+                if (self.min.is_extended_nonpositive and self.max.is_extended_nonnegative):
+                    if self.min.is_zero:
+                        if other.is_extended_positive:
+                            return AccumBounds(Mul(other, 1 / self.max), oo)
+                        if other.is_extended_negative:
+                            return AccumBounds(-oo, Mul(other, 1 / self.max))
+                    if self.max.is_zero:
+                        if other.is_extended_positive:
+                            return AccumBounds(-oo, Mul(other, 1 / self.min))
+                        if other.is_extended_negative:
+                            return AccumBounds(Mul(other, 1 / self.min), oo)
+                    return AccumBounds(-oo, oo)
+                else:
+                    return AccumBounds(Min(other / self.min, other / self.max),
+                                       Max(other / self.min, other / self.max))
+            return Mul(other, 1 / self, evaluate=False)
+        else:
+            return NotImplemented
+
+    @_sympifyit('other', NotImplemented)
+    def __pow__(self, other):
+        if isinstance(other, Expr):
+            if other is S.Infinity:
+                if self.min.is_extended_nonnegative:
+                    if self.max < 1:
+                        return S.Zero
+                    if self.min > 1:
+                        return S.Infinity
+                    return AccumBounds(0, oo)
+                elif self.max.is_extended_negative:
+                    if self.min > -1:
+                        return S.Zero
+                    if self.max < -1:
+                        return zoo
+                    return S.NaN
+                else:
+                    if self.min > -1:
+                        if self.max < 1:
+                            return S.Zero
+                        return AccumBounds(0, oo)
+                    return AccumBounds(-oo, oo)
+
+            if other is S.NegativeInfinity:
+                return (1/self)**oo
+
+            # generically true
+            if (self.max - self.min).is_nonnegative:
+                # well defined
+                if self.min.is_nonnegative:
+                    # no 0 to worry about
+                    if other.is_nonnegative:
+                        # no infinity to worry about
+                        return self.func(self.min**other, self.max**other)
+
+            if other.is_zero:
+                return S.One  # x**0 = 1
+
+            if other.is_Integer or other.is_integer:
+                if self.min.is_extended_positive:
+                    return AccumBounds(
+                        Min(self.min**other, self.max**other),
+                        Max(self.min**other, self.max**other))
+                elif self.max.is_extended_negative:
+                    return AccumBounds(
+                        Min(self.max**other, self.min**other),
+                        Max(self.max**other, self.min**other))
+
+                if other % 2 == 0:
+                    if other.is_extended_negative:
+                        if self.min.is_zero:
+                            return AccumBounds(self.max**other, oo)
+                        if self.max.is_zero:
+                            return AccumBounds(self.min**other, oo)
+                        return (1/self)**(-other)
+                    return AccumBounds(
+                        S.Zero, Max(self.min**other, self.max**other))
+                elif other % 2 == 1:
+                    if other.is_extended_negative:
+                        if self.min.is_zero:
+                            return AccumBounds(self.max**other, oo)
+                        if self.max.is_zero:
+                            return AccumBounds(-oo, self.min**other)
+                        return (1/self)**(-other)
+                    return AccumBounds(self.min**other, self.max**other)
+
+            # non-integer exponent
+            # 0**neg or neg**frac yields complex
+            if (other.is_number or other.is_rational) and (
+                    self.min.is_extended_nonnegative or (
+                    other.is_extended_nonnegative and
+                    self.min.is_extended_nonnegative)):
+                num, den = other.as_numer_denom()
+                if num is S.One:
+                    return AccumBounds(*[i**(1/den) for i in self.args])
+
+                elif den is not S.One:  # e.g. if other is not Float
+                    return (self**num)**(1/den)  # ok for non-negative base
+
+            if isinstance(other, AccumBounds):
+                if (self.min.is_extended_positive or
+                        self.min.is_extended_nonnegative and
+                        other.min.is_extended_nonnegative):
+                    p = [self**i for i in other.args]
+                    if not any(i.is_Pow for i in p):
+                        a = [j for i in p for j in i.args or (i,)]
+                        try:
+                            return self.func(min(a), max(a))
+                        except TypeError:  # can't sort
+                            pass
+
+            return Pow(self, other, evaluate=False)
+
+        return NotImplemented
+
+    @_sympifyit('other', NotImplemented)
+    def __rpow__(self, other):
+        if other.is_real and other.is_extended_nonnegative and (
+                self.max - self.min).is_extended_positive:
+            if other is S.One:
+                return S.One
+            if other.is_extended_positive:
+                a, b = [other**i for i in self.args]
+                if min(a, b) != a:
+                    a, b = b, a
+                return self.func(a, b)
+            if other.is_zero:
+                if self.min.is_zero:
+                    return self.func(0, 1)
+                if self.min.is_extended_positive:
+                    return S.Zero
+
+        return Pow(other, self, evaluate=False)
+
+    def __abs__(self):
+        if self.max.is_extended_negative:
+            return self.__neg__()
+        elif self.min.is_extended_negative:
+            return AccumBounds(S.Zero, Max(abs(self.min), self.max))
+        else:
+            return self
+
+
+    def __contains__(self, other):
+        """
+        Returns ``True`` if other is contained in self, where other
+        belongs to extended real numbers, ``False`` if not contained,
+        otherwise TypeError is raised.
+
+        Examples
+        ========
+
+        >>> from sympy import AccumBounds, oo
+        >>> 1 in AccumBounds(-1, 3)
+        True
+
+        -oo and oo go together as limits (in AccumulationBounds).
+
+        >>> -oo in AccumBounds(1, oo)
+        True
+
+        >>> oo in AccumBounds(-oo, 0)
+        True
+
+        """
+        other = _sympify(other)
+
+        if other in (S.Infinity, S.NegativeInfinity):
+            if self.min is S.NegativeInfinity or self.max is S.Infinity:
+                return True
+            return False
+
+        rv = And(self.min <= other, self.max >= other)
+        if rv not in (True, False):
+            raise TypeError("input failed to evaluate")
+        return rv
+
+    def intersection(self, other):
+        """
+        Returns the intersection of 'self' and 'other'.
+        Here other can be an instance of :py:class:`~.FiniteSet` or AccumulationBounds.
+
+        Parameters
+        ==========
+
+        other : AccumulationBounds
+            Another AccumulationBounds object with which the intersection
+            has to be computed.
+
+        Returns
+        =======
+
+        AccumulationBounds
+            Intersection of ``self`` and ``other``.
+
+        Examples
+        ========
+
+        >>> from sympy import AccumBounds, FiniteSet
+        >>> AccumBounds(1, 3).intersection(AccumBounds(2, 4))
+        AccumBounds(2, 3)
+
+        >>> AccumBounds(1, 3).intersection(AccumBounds(4, 6))
+        EmptySet
+
+        >>> AccumBounds(1, 4).intersection(FiniteSet(1, 2, 5))
+        {1, 2}
+
+        """
+        if not isinstance(other, (AccumBounds, FiniteSet)):
+            raise TypeError(
+                "Input must be AccumulationBounds or FiniteSet object")
+
+        if isinstance(other, FiniteSet):
+            fin_set = S.EmptySet
+            for i in other:
+                if i in self:
+                    fin_set = fin_set + FiniteSet(i)
+            return fin_set
+
+        if self.max < other.min or self.min > other.max:
+            return S.EmptySet
+
+        if self.min <= other.min:
+            if self.max <= other.max:
+                return AccumBounds(other.min, self.max)
+            if self.max > other.max:
+                return other
+
+        if other.min <= self.min:
+            if other.max < self.max:
+                return AccumBounds(self.min, other.max)
+            if other.max > self.max:
+                return self
+
+    def union(self, other):
+        # TODO : Devise a better method for Union of AccumBounds
+        # this method is not actually correct and
+        # can be made better
+        if not isinstance(other, AccumBounds):
+            raise TypeError(
+                "Input must be AccumulationBounds or FiniteSet object")
+
+        if self.min <= other.min and self.max >= other.min:
+            return AccumBounds(self.min, Max(self.max, other.max))
+
+        if other.min <= self.min and other.max >= self.min:
+            return AccumBounds(other.min, Max(self.max, other.max))
+
+
+@dispatch(AccumulationBounds, AccumulationBounds) # type: ignore # noqa:F811
+def _eval_is_le(lhs, rhs): # noqa:F811
+    if is_le(lhs.max, rhs.min):
+        return True
+    if is_gt(lhs.min, rhs.max):
+        return False
+
+
+@dispatch(AccumulationBounds, Basic) # type: ignore # noqa:F811
+def _eval_is_le(lhs, rhs): # noqa: F811
+
+    """
+    Returns ``True `` if range of values attained by ``lhs`` AccumulationBounds
+    object is greater than the range of values attained by ``rhs``,
+    where ``rhs`` may be any value of type AccumulationBounds object or
+    extended real number value, ``False`` if ``rhs`` satisfies
+    the same property, else an unevaluated :py:class:`~.Relational`.
+
+    Examples
+    ========
+
+    >>> from sympy import AccumBounds, oo
+    >>> AccumBounds(1, 3) > AccumBounds(4, oo)
+    False
+    >>> AccumBounds(1, 4) > AccumBounds(3, 4)
+    AccumBounds(1, 4) > AccumBounds(3, 4)
+    >>> AccumBounds(1, oo) > -1
+    True
+
+    """
+    if not rhs.is_extended_real:
+            raise TypeError(
+                "Invalid comparison of %s %s" %
+                (type(rhs), rhs))
+    elif rhs.is_comparable:
+        if is_le(lhs.max, rhs):
+            return True
+        if is_gt(lhs.min, rhs):
+            return False
+
+
+@dispatch(AccumulationBounds, AccumulationBounds)
+def _eval_is_ge(lhs, rhs): # noqa:F811
+    if is_ge(lhs.min, rhs.max):
+        return True
+    if is_lt(lhs.max, rhs.min):
+        return False
+
+
+@dispatch(AccumulationBounds, Expr)  # type:ignore
+def _eval_is_ge(lhs, rhs): # noqa: F811
+    """
+    Returns ``True`` if range of values attained by ``lhs`` AccumulationBounds
+    object is less that the range of values attained by ``rhs``, where
+    other may be any value of type AccumulationBounds object or extended
+    real number value, ``False`` if ``rhs`` satisfies the same
+    property, else an unevaluated :py:class:`~.Relational`.
+
+    Examples
+    ========
+
+    >>> from sympy import AccumBounds, oo
+    >>> AccumBounds(1, 3) >= AccumBounds(4, oo)
+    False
+    >>> AccumBounds(1, 4) >= AccumBounds(3, 4)
+    AccumBounds(1, 4) >= AccumBounds(3, 4)
+    >>> AccumBounds(1, oo) >= 1
+    True
+    """
+
+    if not rhs.is_extended_real:
+        raise TypeError(
+            "Invalid comparison of %s %s" %
+            (type(rhs), rhs))
+    elif rhs.is_comparable:
+        if is_ge(lhs.min, rhs):
+            return True
+        if is_lt(lhs.max, rhs):
+            return False
+
+
+@dispatch(Expr, AccumulationBounds)  # type:ignore
+def _eval_is_ge(lhs, rhs): # noqa:F811
+    if not lhs.is_extended_real:
+        raise TypeError(
+            "Invalid comparison of %s %s" %
+            (type(lhs), lhs))
+    elif lhs.is_comparable:
+        if is_le(rhs.max, lhs):
+            return True
+        if is_gt(rhs.min, lhs):
+            return False
+
+
+@dispatch(AccumulationBounds, AccumulationBounds)  # type:ignore
+def _eval_is_ge(lhs, rhs): # noqa:F811
+    if is_ge(lhs.min, rhs.max):
+        return True
+    if is_lt(lhs.max, rhs.min):
+        return False
+
+# setting an alias for AccumulationBounds
+AccumBounds = AccumulationBounds

lib/python3.12/site-packages/sympy/calculus/euler.py

@@ -0,0 +1,108 @@
+"""
+This module implements a method to find
+Euler-Lagrange Equations for given Lagrangian.
+"""
+from itertools import combinations_with_replacement
+from sympy.core.function import (Derivative, Function, diff)
+from sympy.core.relational import Eq
+from sympy.core.singleton import S
+from sympy.core.symbol import Symbol
+from sympy.core.sympify import sympify
+from sympy.utilities.iterables import iterable
+
+
+def euler_equations(L, funcs=(), vars=()):
+    r"""
+    Find the Euler-Lagrange equations [1]_ for a given Lagrangian.
+
+    Parameters
+    ==========
+
+    L : Expr
+        The Lagrangian that should be a function of the functions listed
+        in the second argument and their derivatives.
+
+        For example, in the case of two functions $f(x,y)$, $g(x,y)$ and
+        two independent variables $x$, $y$ the Lagrangian has the form:
+
+            .. math:: L\left(f(x,y),g(x,y),\frac{\partial f(x,y)}{\partial x},
+                      \frac{\partial f(x,y)}{\partial y},
+                      \frac{\partial g(x,y)}{\partial x},
+                      \frac{\partial g(x,y)}{\partial y},x,y\right)
+
+        In many cases it is not necessary to provide anything, except the
+        Lagrangian, it will be auto-detected (and an error raised if this
+        cannot be done).
+
+    funcs : Function or an iterable of Functions
+        The functions that the Lagrangian depends on. The Euler equations
+        are differential equations for each of these functions.
+
+    vars : Symbol or an iterable of Symbols
+        The Symbols that are the independent variables of the functions.
+
+    Returns
+    =======
+
+    eqns : list of Eq
+        The list of differential equations, one for each function.
+
+    Examples
+    ========
+
+    >>> from sympy import euler_equations, Symbol, Function
+    >>> x = Function('x')
+    >>> t = Symbol('t')
+    >>> L = (x(t).diff(t))**2/2 - x(t)**2/2
+    >>> euler_equations(L, x(t), t)
+    [Eq(-x(t) - Derivative(x(t), (t, 2)), 0)]
+    >>> u = Function('u')
+    >>> x = Symbol('x')
+    >>> L = (u(t, x).diff(t))**2/2 - (u(t, x).diff(x))**2/2
+    >>> euler_equations(L, u(t, x), [t, x])
+    [Eq(-Derivative(u(t, x), (t, 2)) + Derivative(u(t, x), (x, 2)), 0)]
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Euler%E2%80%93Lagrange_equation
+
+    """
+
+    funcs = tuple(funcs) if iterable(funcs) else (funcs,)
+
+    if not funcs:
+        funcs = tuple(L.atoms(Function))
+    else:
+        for f in funcs:
+            if not isinstance(f, Function):
+                raise TypeError('Function expected, got: %s' % f)
+
+    vars = tuple(vars) if iterable(vars) else (vars,)
+
+    if not vars:
+        vars = funcs[0].args
+    else:
+        vars = tuple(sympify(var) for var in vars)
+
+    if not all(isinstance(v, Symbol) for v in vars):
+        raise TypeError('Variables are not symbols, got %s' % vars)
+
+    for f in funcs:
+        if not vars == f.args:
+            raise ValueError("Variables %s do not match args: %s" % (vars, f))
+
+    order = max([len(d.variables) for d in L.atoms(Derivative)
+                        if d.expr in funcs] + [0])
+
+    eqns = []
+    for f in funcs:
+        eq = diff(L, f)
+        for i in range(1, order + 1):
+            for p in combinations_with_replacement(vars, i):
+                eq = eq + S.NegativeOne**i*diff(L, diff(f, *p), *p)
+        new_eq = Eq(eq, 0)
+        if isinstance(new_eq, Eq):
+            eqns.append(new_eq)
+
+    return eqns

lib/python3.12/site-packages/sympy/calculus/finite_diff.py

@@ -0,0 +1,476 @@
+"""
+Finite difference weights
+=========================
+
+This module implements an algorithm for efficient generation of finite
+difference weights for ordinary differentials of functions for
+derivatives from 0 (interpolation) up to arbitrary order.
+
+The core algorithm is provided in the finite difference weight generating
+function (``finite_diff_weights``), and two convenience functions are provided
+for:
+
+- estimating a derivative (or interpolate) directly from a series of points
+    is also provided (``apply_finite_diff``).
+- differentiating by using finite difference approximations
+    (``differentiate_finite``).
+
+"""
+
+from sympy.core.function import Derivative
+from sympy.core.singleton import S
+from sympy.core.function import Subs
+from sympy.core.traversal import preorder_traversal
+from sympy.utilities.exceptions import sympy_deprecation_warning
+from sympy.utilities.iterables import iterable
+
+
+
+def finite_diff_weights(order, x_list, x0=S.One):
+    """
+    Calculates the finite difference weights for an arbitrarily spaced
+    one-dimensional grid (``x_list``) for derivatives at ``x0`` of order
+    0, 1, ..., up to ``order`` using a recursive formula. Order of accuracy
+    is at least ``len(x_list) - order``, if ``x_list`` is defined correctly.
+
+    Parameters
+    ==========
+
+    order: int
+        Up to what derivative order weights should be calculated.
+        0 corresponds to interpolation.
+    x_list: sequence
+        Sequence of (unique) values for the independent variable.
+        It is useful (but not necessary) to order ``x_list`` from
+        nearest to furthest from ``x0``; see examples below.
+    x0: Number or Symbol
+        Root or value of the independent variable for which the finite
+        difference weights should be generated. Default is ``S.One``.
+
+    Returns
+    =======
+
+    list
+        A list of sublists, each corresponding to coefficients for
+        increasing derivative order, and each containing lists of
+        coefficients for increasing subsets of x_list.
+
+    Examples
+    ========
+
+    >>> from sympy import finite_diff_weights, S
+    >>> res = finite_diff_weights(1, [-S(1)/2, S(1)/2, S(3)/2, S(5)/2], 0)
+    >>> res
+    [[[1, 0, 0, 0],
+      [1/2, 1/2, 0, 0],
+      [3/8, 3/4, -1/8, 0],
+      [5/16, 15/16, -5/16, 1/16]],
+     [[0, 0, 0, 0],
+      [-1, 1, 0, 0],
+      [-1, 1, 0, 0],
+      [-23/24, 7/8, 1/8, -1/24]]]
+    >>> res[0][-1]  # FD weights for 0th derivative, using full x_list
+    [5/16, 15/16, -5/16, 1/16]
+    >>> res[1][-1]  # FD weights for 1st derivative
+    [-23/24, 7/8, 1/8, -1/24]
+    >>> res[1][-2]  # FD weights for 1st derivative, using x_list[:-1]
+    [-1, 1, 0, 0]
+    >>> res[1][-1][0]  # FD weight for 1st deriv. for x_list[0]
+    -23/24
+    >>> res[1][-1][1]  # FD weight for 1st deriv. for x_list[1], etc.
+    7/8
+
+    Each sublist contains the most accurate formula at the end.
+    Note, that in the above example ``res[1][1]`` is the same as ``res[1][2]``.
+    Since res[1][2] has an order of accuracy of
+    ``len(x_list[:3]) - order = 3 - 1 = 2``, the same is true for ``res[1][1]``!
+
+    >>> res = finite_diff_weights(1, [S(0), S(1), -S(1), S(2), -S(2)], 0)[1]
+    >>> res
+    [[0, 0, 0, 0, 0],
+     [-1, 1, 0, 0, 0],
+     [0, 1/2, -1/2, 0, 0],
+     [-1/2, 1, -1/3, -1/6, 0],
+     [0, 2/3, -2/3, -1/12, 1/12]]
+    >>> res[0]  # no approximation possible, using x_list[0] only
+    [0, 0, 0, 0, 0]
+    >>> res[1]  # classic forward step approximation
+    [-1, 1, 0, 0, 0]
+    >>> res[2]  # classic centered approximation
+    [0, 1/2, -1/2, 0, 0]
+    >>> res[3:]  # higher order approximations
+    [[-1/2, 1, -1/3, -1/6, 0], [0, 2/3, -2/3, -1/12, 1/12]]
+
+    Let us compare this to a differently defined ``x_list``. Pay attention to
+    ``foo[i][k]`` corresponding to the gridpoint defined by ``x_list[k]``.
+
+    >>> foo = finite_diff_weights(1, [-S(2), -S(1), S(0), S(1), S(2)], 0)[1]
+    >>> foo
+    [[0, 0, 0, 0, 0],
+     [-1, 1, 0, 0, 0],
+     [1/2, -2, 3/2, 0, 0],
+     [1/6, -1, 1/2, 1/3, 0],
+     [1/12, -2/3, 0, 2/3, -1/12]]
+    >>> foo[1]  # not the same and of lower accuracy as res[1]!
+    [-1, 1, 0, 0, 0]
+    >>> foo[2]  # classic double backward step approximation
+    [1/2, -2, 3/2, 0, 0]
+    >>> foo[4]  # the same as res[4]
+    [1/12, -2/3, 0, 2/3, -1/12]
+
+    Note that, unless you plan on using approximations based on subsets of
+    ``x_list``, the order of gridpoints does not matter.
+
+    The capability to generate weights at arbitrary points can be
+    used e.g. to minimize Runge's phenomenon by using Chebyshev nodes:
+
+    >>> from sympy import cos, symbols, pi, simplify
+    >>> N, (h, x) = 4, symbols('h x')
+    >>> x_list = [x+h*cos(i*pi/(N)) for i in range(N,-1,-1)] # chebyshev nodes
+    >>> print(x_list)
+    [-h + x, -sqrt(2)*h/2 + x, x, sqrt(2)*h/2 + x, h + x]
+    >>> mycoeffs = finite_diff_weights(1, x_list, 0)[1][4]
+    >>> [simplify(c) for c in  mycoeffs] #doctest: +NORMALIZE_WHITESPACE
+    [(h**3/2 + h**2*x - 3*h*x**2 - 4*x**3)/h**4,
+    (-sqrt(2)*h**3 - 4*h**2*x + 3*sqrt(2)*h*x**2 + 8*x**3)/h**4,
+    (6*h**2*x - 8*x**3)/h**4,
+    (sqrt(2)*h**3 - 4*h**2*x - 3*sqrt(2)*h*x**2 + 8*x**3)/h**4,
+    (-h**3/2 + h**2*x + 3*h*x**2 - 4*x**3)/h**4]
+
+    Notes
+    =====
+
+    If weights for a finite difference approximation of 3rd order
+    derivative is wanted, weights for 0th, 1st and 2nd order are
+    calculated "for free", so are formulae using subsets of ``x_list``.
+    This is something one can take advantage of to save computational cost.
+    Be aware that one should define ``x_list`` from nearest to furthest from
+    ``x0``. If not, subsets of ``x_list`` will yield poorer approximations,
+    which might not grand an order of accuracy of ``len(x_list) - order``.
+
+    See also
+    ========
+
+    sympy.calculus.finite_diff.apply_finite_diff
+
+    References
+    ==========
+
+    .. [1] Generation of Finite Difference Formulas on Arbitrarily Spaced
+            Grids, Bengt Fornberg; Mathematics of computation; 51; 184;
+            (1988); 699-706; doi:10.1090/S0025-5718-1988-0935077-0
+
+    """
+    # The notation below closely corresponds to the one used in the paper.
+    order = S(order)
+    if not order.is_number:
+        raise ValueError("Cannot handle symbolic order.")
+    if order < 0:
+        raise ValueError("Negative derivative order illegal.")
+    if int(order) != order:
+        raise ValueError("Non-integer order illegal")
+    M = order
+    N = len(x_list) - 1
+    delta = [[[0 for nu in range(N+1)] for n in range(N+1)] for
+             m in range(M+1)]
+    delta[0][0][0] = S.One
+    c1 = S.One
+    for n in range(1, N+1):
+        c2 = S.One
+        for nu in range(n):
+            c3 = x_list[n] - x_list[nu]
+            c2 = c2 * c3
+            if n <= M:
+                delta[n][n-1][nu] = 0
+            for m in range(min(n, M)+1):
+                delta[m][n][nu] = (x_list[n]-x0)*delta[m][n-1][nu] -\
+                    m*delta[m-1][n-1][nu]
+                delta[m][n][nu] /= c3
+        for m in range(min(n, M)+1):
+            delta[m][n][n] = c1/c2*(m*delta[m-1][n-1][n-1] -
+                                    (x_list[n-1]-x0)*delta[m][n-1][n-1])
+        c1 = c2
+    return delta
+
+
+def apply_finite_diff(order, x_list, y_list, x0=S.Zero):
+    """
+    Calculates the finite difference approximation of
+    the derivative of requested order at ``x0`` from points
+    provided in ``x_list`` and ``y_list``.
+
+    Parameters
+    ==========
+
+    order: int
+        order of derivative to approximate. 0 corresponds to interpolation.
+    x_list: sequence
+        Sequence of (unique) values for the independent variable.
+    y_list: sequence
+        The function value at corresponding values for the independent
+        variable in x_list.
+    x0: Number or Symbol
+        At what value of the independent variable the derivative should be
+        evaluated. Defaults to 0.
+
+    Returns
+    =======
+
+    sympy.core.add.Add or sympy.core.numbers.Number
+        The finite difference expression approximating the requested
+        derivative order at ``x0``.
+
+    Examples
+    ========
+
+    >>> from sympy import apply_finite_diff
+    >>> cube = lambda arg: (1.0*arg)**3
+    >>> xlist = range(-3,3+1)
+    >>> apply_finite_diff(2, xlist, map(cube, xlist), 2) - 12 # doctest: +SKIP
+    -3.55271367880050e-15
+
+    we see that the example above only contain rounding errors.
+    apply_finite_diff can also be used on more abstract objects:
+
+    >>> from sympy import IndexedBase, Idx
+    >>> x, y = map(IndexedBase, 'xy')
+    >>> i = Idx('i')
+    >>> x_list, y_list = zip(*[(x[i+j], y[i+j]) for j in range(-1,2)])
+    >>> apply_finite_diff(1, x_list, y_list, x[i])
+    ((x[i + 1] - x[i])/(-x[i - 1] + x[i]) - 1)*y[i]/(x[i + 1] - x[i]) -
+    (x[i + 1] - x[i])*y[i - 1]/((x[i + 1] - x[i - 1])*(-x[i - 1] + x[i])) +
+    (-x[i - 1] + x[i])*y[i + 1]/((x[i + 1] - x[i - 1])*(x[i + 1] - x[i]))
+
+    Notes
+    =====
+
+    Order = 0 corresponds to interpolation.
+    Only supply so many points you think makes sense
+    to around x0 when extracting the derivative (the function
+    need to be well behaved within that region). Also beware
+    of Runge's phenomenon.
+
+    See also
+    ========
+
+    sympy.calculus.finite_diff.finite_diff_weights
+
+    References
+    ==========
+
+    Fortran 90 implementation with Python interface for numerics: finitediff_
+
+    .. _finitediff: https://github.com/bjodah/finitediff
+
+    """
+
+    # In the original paper the following holds for the notation:
+    # M = order
+    # N = len(x_list) - 1
+
+    N = len(x_list) - 1
+    if len(x_list) != len(y_list):
+        raise ValueError("x_list and y_list not equal in length.")
+
+    delta = finite_diff_weights(order, x_list, x0)
+
+    derivative = 0
+    for nu in range(len(x_list)):
+        derivative += delta[order][N][nu]*y_list[nu]
+    return derivative
+
+
+def _as_finite_diff(derivative, points=1, x0=None, wrt=None):
+    """
+    Returns an approximation of a derivative of a function in
+    the form of a finite difference formula. The expression is a
+    weighted sum of the function at a number of discrete values of
+    (one of) the independent variable(s).
+
+    Parameters
+    ==========
+
+    derivative: a Derivative instance
+
+    points: sequence or coefficient, optional
+        If sequence: discrete values (length >= order+1) of the
+        independent variable used for generating the finite
+        difference weights.
+        If it is a coefficient, it will be used as the step-size
+        for generating an equidistant sequence of length order+1
+        centered around ``x0``. default: 1 (step-size 1)
+
+    x0: number or Symbol, optional
+        the value of the independent variable (``wrt``) at which the
+        derivative is to be approximated. Default: same as ``wrt``.
+
+    wrt: Symbol, optional
+        "with respect to" the variable for which the (partial)
+        derivative is to be approximated for. If not provided it
+        is required that the Derivative is ordinary. Default: ``None``.
+
+    Examples
+    ========
+
+    >>> from sympy import symbols, Function, exp, sqrt, Symbol
+    >>> from sympy.calculus.finite_diff import _as_finite_diff
+    >>> x, h = symbols('x h')
+    >>> f = Function('f')
+    >>> _as_finite_diff(f(x).diff(x))
+    -f(x - 1/2) + f(x + 1/2)
+
+    The default step size and number of points are 1 and ``order + 1``
+    respectively. We can change the step size by passing a symbol
+    as a parameter:
+
+    >>> _as_finite_diff(f(x).diff(x), h)
+    -f(-h/2 + x)/h + f(h/2 + x)/h
+
+    We can also specify the discretized values to be used in a sequence:
+
+    >>> _as_finite_diff(f(x).diff(x), [x, x+h, x+2*h])
+    -3*f(x)/(2*h) + 2*f(h + x)/h - f(2*h + x)/(2*h)
+
+    The algorithm is not restricted to use equidistant spacing, nor
+    do we need to make the approximation around ``x0``, but we can get
+    an expression estimating the derivative at an offset:
+
+    >>> e, sq2 = exp(1), sqrt(2)
+    >>> xl = [x-h, x+h, x+e*h]
+    >>> _as_finite_diff(f(x).diff(x, 1), xl, x+h*sq2)
+    2*h*((h + sqrt(2)*h)/(2*h) - (-sqrt(2)*h + h)/(2*h))*f(E*h + x)/((-h + E*h)*(h + E*h)) +
+    (-(-sqrt(2)*h + h)/(2*h) - (-sqrt(2)*h + E*h)/(2*h))*f(-h + x)/(h + E*h) +
+    (-(h + sqrt(2)*h)/(2*h) + (-sqrt(2)*h + E*h)/(2*h))*f(h + x)/(-h + E*h)
+
+    Partial derivatives are also supported:
+
+    >>> y = Symbol('y')
+    >>> d2fdxdy=f(x,y).diff(x,y)
+    >>> _as_finite_diff(d2fdxdy, wrt=x)
+    -Derivative(f(x - 1/2, y), y) + Derivative(f(x + 1/2, y), y)
+
+    See also
+    ========
+
+    sympy.calculus.finite_diff.apply_finite_diff
+    sympy.calculus.finite_diff.finite_diff_weights
+
+    """
+    if derivative.is_Derivative:
+        pass
+    elif derivative.is_Atom:
+        return derivative
+    else:
+        return derivative.fromiter(
+            [_as_finite_diff(ar, points, x0, wrt) for ar
+             in derivative.args], **derivative.assumptions0)
+
+    if wrt is None:
+        old = None
+        for v in derivative.variables:
+            if old is v:
+                continue
+            derivative = _as_finite_diff(derivative, points, x0, v)
+            old = v
+        return derivative
+
+    order = derivative.variables.count(wrt)
+
+    if x0 is None:
+        x0 = wrt
+
+    if not iterable(points):
+        if getattr(points, 'is_Function', False) and wrt in points.args:
+            points = points.subs(wrt, x0)
+        # points is simply the step-size, let's make it a
+        # equidistant sequence centered around x0
+        if order % 2 == 0:
+            # even order => odd number of points, grid point included
+            points = [x0 + points*i for i
+                      in range(-order//2, order//2 + 1)]
+        else:
+            # odd order => even number of points, half-way wrt grid point
+            points = [x0 + points*S(i)/2 for i
+                      in range(-order, order + 1, 2)]
+    others = [wrt, 0]
+    for v in set(derivative.variables):
+        if v == wrt:
+            continue
+        others += [v, derivative.variables.count(v)]
+    if len(points) < order+1:
+        raise ValueError("Too few points for order %d" % order)
+    return apply_finite_diff(order, points, [
+        Derivative(derivative.expr.subs({wrt: x}), *others) for
+        x in points], x0)
+
+
+def differentiate_finite(expr, *symbols,
+                         points=1, x0=None, wrt=None, evaluate=False):
+    r""" Differentiate expr and replace Derivatives with finite differences.
+
+    Parameters
+    ==========
+
+    expr : expression
+    \*symbols : differentiate with respect to symbols
+    points: sequence, coefficient or undefined function, optional
+        see ``Derivative.as_finite_difference``
+    x0: number or Symbol, optional
+        see ``Derivative.as_finite_difference``
+    wrt: Symbol, optional
+        see ``Derivative.as_finite_difference``
+
+    Examples
+    ========
+
+    >>> from sympy import sin, Function, differentiate_finite
+    >>> from sympy.abc import x, y, h
+    >>> f, g = Function('f'), Function('g')
+    >>> differentiate_finite(f(x)*g(x), x, points=[x-h, x+h])
+    -f(-h + x)*g(-h + x)/(2*h) + f(h + x)*g(h + x)/(2*h)
+
+    ``differentiate_finite`` works on any expression, including the expressions
+    with embedded derivatives:
+
+    >>> differentiate_finite(f(x) + sin(x), x, 2)
+    -2*f(x) + f(x - 1) + f(x + 1) - 2*sin(x) + sin(x - 1) + sin(x + 1)
+    >>> differentiate_finite(f(x, y), x, y)
+    f(x - 1/2, y - 1/2) - f(x - 1/2, y + 1/2) - f(x + 1/2, y - 1/2) + f(x + 1/2, y + 1/2)
+    >>> differentiate_finite(f(x)*g(x).diff(x), x)
+    (-g(x) + g(x + 1))*f(x + 1/2) - (g(x) - g(x - 1))*f(x - 1/2)
+
+    To make finite difference with non-constant discretization step use
+    undefined functions:
+
+    >>> dx = Function('dx')
+    >>> differentiate_finite(f(x)*g(x).diff(x), points=dx(x))
+    -(-g(x - dx(x)/2 - dx(x - dx(x)/2)/2)/dx(x - dx(x)/2) +
+    g(x - dx(x)/2 + dx(x - dx(x)/2)/2)/dx(x - dx(x)/2))*f(x - dx(x)/2)/dx(x) +
+    (-g(x + dx(x)/2 - dx(x + dx(x)/2)/2)/dx(x + dx(x)/2) +
+    g(x + dx(x)/2 + dx(x + dx(x)/2)/2)/dx(x + dx(x)/2))*f(x + dx(x)/2)/dx(x)
+
+    """
+    if any(term.is_Derivative for term in list(preorder_traversal(expr))):
+        evaluate = False
+
+    Dexpr = expr.diff(*symbols, evaluate=evaluate)
+    if evaluate:
+        sympy_deprecation_warning("""
+        The evaluate flag to differentiate_finite() is deprecated.
+
+        evaluate=True expands the intermediate derivatives before computing
+        differences, but this usually not what you want, as it does not
+        satisfy the product rule.
+        """,
+            deprecated_since_version="1.5",
+             active_deprecations_target="deprecated-differentiate_finite-evaluate",
+        )
+        return Dexpr.replace(
+            lambda arg: arg.is_Derivative,
+            lambda arg: arg.as_finite_difference(points=points, x0=x0, wrt=wrt))
+    else:
+        DFexpr = Dexpr.as_finite_difference(points=points, x0=x0, wrt=wrt)
+        return DFexpr.replace(
+            lambda arg: isinstance(arg, Subs),
+            lambda arg: arg.expr.as_finite_difference(
+                    points=points, x0=arg.point[0], wrt=arg.variables[0]))

lib/python3.12/site-packages/sympy/calculus/singularities.py

@@ -0,0 +1,406 @@
+"""
+Singularities
+=============
+
+This module implements algorithms for finding singularities for a function
+and identifying types of functions.
+
+The differential calculus methods in this module include methods to identify
+the following function types in the given ``Interval``:
+- Increasing
+- Strictly Increasing
+- Decreasing
+- Strictly Decreasing
+- Monotonic
+
+"""
+
+from sympy.core.power import Pow
+from sympy.core.singleton import S
+from sympy.core.symbol import Symbol
+from sympy.core.sympify import sympify
+from sympy.functions.elementary.exponential import log
+from sympy.functions.elementary.trigonometric import sec, csc, cot, tan, cos
+from sympy.functions.elementary.hyperbolic import (
+    sech, csch, coth, tanh, cosh, asech, acsch, atanh, acoth)
+from sympy.utilities.misc import filldedent
+
+
+def singularities(expression, symbol, domain=None):
+    """
+    Find singularities of a given function.
+
+    Parameters
+    ==========
+
+    expression : Expr
+        The target function in which singularities need to be found.
+    symbol : Symbol
+        The symbol over the values of which the singularity in
+        expression in being searched for.
+
+    Returns
+    =======
+
+    Set
+        A set of values for ``symbol`` for which ``expression`` has a
+        singularity. An ``EmptySet`` is returned if ``expression`` has no
+        singularities for any given value of ``Symbol``.
+
+    Raises
+    ======
+
+    NotImplementedError
+        Methods for determining the singularities of this function have
+        not been developed.
+
+    Notes
+    =====
+
+    This function does not find non-isolated singularities
+    nor does it find branch points of the expression.
+
+    Currently supported functions are:
+        - univariate continuous (real or complex) functions
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Mathematical_singularity
+
+    Examples
+    ========
+
+    >>> from sympy import singularities, Symbol, log
+    >>> x = Symbol('x', real=True)
+    >>> y = Symbol('y', real=False)
+    >>> singularities(x**2 + x + 1, x)
+    EmptySet
+    >>> singularities(1/(x + 1), x)
+    {-1}
+    >>> singularities(1/(y**2 + 1), y)
+    {-I, I}
+    >>> singularities(1/(y**3 + 1), y)
+    {-1, 1/2 - sqrt(3)*I/2, 1/2 + sqrt(3)*I/2}
+    >>> singularities(log(x), x)
+    {0}
+
+    """
+    from sympy.solvers.solveset import solveset
+
+    if domain is None:
+        domain = S.Reals if symbol.is_real else S.Complexes
+    try:
+        sings = S.EmptySet
+        e = expression.rewrite([sec, csc, cot, tan], cos)
+        e = e.rewrite([sech, csch, coth, tanh], cosh)
+        for i in e.atoms(Pow):
+            if i.exp.is_infinite:
+                raise NotImplementedError
+            if i.exp.is_negative:
+                # XXX: exponent of varying sign not handled
+                sings += solveset(i.base, symbol, domain)
+        for i in expression.atoms(log, asech, acsch):
+            sings += solveset(i.args[0], symbol, domain)
+        for i in expression.atoms(atanh, acoth):
+            sings += solveset(i.args[0] - 1, symbol, domain)
+            sings += solveset(i.args[0] + 1, symbol, domain)
+        return sings
+    except NotImplementedError:
+        raise NotImplementedError(filldedent('''
+            Methods for determining the singularities
+            of this function have not been developed.'''))
+
+
+###########################################################################
+#                      DIFFERENTIAL CALCULUS METHODS                      #
+###########################################################################
+
+
+def monotonicity_helper(expression, predicate, interval=S.Reals, symbol=None):
+    """
+    Helper function for functions checking function monotonicity.
+
+    Parameters
+    ==========
+
+    expression : Expr
+        The target function which is being checked
+    predicate : function
+        The property being tested for. The function takes in an integer
+        and returns a boolean. The integer input is the derivative and
+        the boolean result should be true if the property is being held,
+        and false otherwise.
+    interval : Set, optional
+        The range of values in which we are testing, defaults to all reals.
+    symbol : Symbol, optional
+        The symbol present in expression which gets varied over the given range.
+
+    It returns a boolean indicating whether the interval in which
+    the function's derivative satisfies given predicate is a superset
+    of the given interval.
+
+    Returns
+    =======
+
+    Boolean
+        True if ``predicate`` is true for all the derivatives when ``symbol``
+        is varied in ``range``, False otherwise.
+
+    """
+    from sympy.solvers.solveset import solveset
+
+    expression = sympify(expression)
+    free = expression.free_symbols
+
+    if symbol is None:
+        if len(free) > 1:
+            raise NotImplementedError(
+                'The function has not yet been implemented'
+                ' for all multivariate expressions.'
+            )
+
+    variable = symbol or (free.pop() if free else Symbol('x'))
+    derivative = expression.diff(variable)
+    predicate_interval = solveset(predicate(derivative), variable, S.Reals)
+    return interval.is_subset(predicate_interval)
+
+
+def is_increasing(expression, interval=S.Reals, symbol=None):
+    """
+    Return whether the function is increasing in the given interval.
+
+    Parameters
+    ==========
+
+    expression : Expr
+        The target function which is being checked.
+    interval : Set, optional
+        The range of values in which we are testing (defaults to set of
+        all real numbers).
+    symbol : Symbol, optional
+        The symbol present in expression which gets varied over the given range.
+
+    Returns
+    =======
+
+    Boolean
+        True if ``expression`` is increasing (either strictly increasing or
+        constant) in the given ``interval``, False otherwise.
+
+    Examples
+    ========
+
+    >>> from sympy import is_increasing
+    >>> from sympy.abc import x, y
+    >>> from sympy import S, Interval, oo
+    >>> is_increasing(x**3 - 3*x**2 + 4*x, S.Reals)
+    True
+    >>> is_increasing(-x**2, Interval(-oo, 0))
+    True
+    >>> is_increasing(-x**2, Interval(0, oo))
+    False
+    >>> is_increasing(4*x**3 - 6*x**2 - 72*x + 30, Interval(-2, 3))
+    False
+    >>> is_increasing(x**2 + y, Interval(1, 2), x)
+    True
+
+    """
+    return monotonicity_helper(expression, lambda x: x >= 0, interval, symbol)
+
+
+def is_strictly_increasing(expression, interval=S.Reals, symbol=None):
+    """
+    Return whether the function is strictly increasing in the given interval.
+
+    Parameters
+    ==========
+
+    expression : Expr
+        The target function which is being checked.
+    interval : Set, optional
+        The range of values in which we are testing (defaults to set of
+        all real numbers).
+    symbol : Symbol, optional
+        The symbol present in expression which gets varied over the given range.
+
+    Returns
+    =======
+
+    Boolean
+        True if ``expression`` is strictly increasing in the given ``interval``,
+        False otherwise.
+
+    Examples
+    ========
+
+    >>> from sympy import is_strictly_increasing
+    >>> from sympy.abc import x, y
+    >>> from sympy import Interval, oo
+    >>> is_strictly_increasing(4*x**3 - 6*x**2 - 72*x + 30, Interval.Ropen(-oo, -2))
+    True
+    >>> is_strictly_increasing(4*x**3 - 6*x**2 - 72*x + 30, Interval.Lopen(3, oo))
+    True
+    >>> is_strictly_increasing(4*x**3 - 6*x**2 - 72*x + 30, Interval.open(-2, 3))
+    False
+    >>> is_strictly_increasing(-x**2, Interval(0, oo))
+    False
+    >>> is_strictly_increasing(-x**2 + y, Interval(-oo, 0), x)
+    False
+
+    """
+    return monotonicity_helper(expression, lambda x: x > 0, interval, symbol)
+
+
+def is_decreasing(expression, interval=S.Reals, symbol=None):
+    """
+    Return whether the function is decreasing in the given interval.
+
+    Parameters
+    ==========
+
+    expression : Expr
+        The target function which is being checked.
+    interval : Set, optional
+        The range of values in which we are testing (defaults to set of
+        all real numbers).
+    symbol : Symbol, optional
+        The symbol present in expression which gets varied over the given range.
+
+    Returns
+    =======
+
+    Boolean
+        True if ``expression`` is decreasing (either strictly decreasing or
+        constant) in the given ``interval``, False otherwise.
+
+    Examples
+    ========
+
+    >>> from sympy import is_decreasing
+    >>> from sympy.abc import x, y
+    >>> from sympy import S, Interval, oo
+    >>> is_decreasing(1/(x**2 - 3*x), Interval.open(S(3)/2, 3))
+    True
+    >>> is_decreasing(1/(x**2 - 3*x), Interval.open(1.5, 3))
+    True
+    >>> is_decreasing(1/(x**2 - 3*x), Interval.Lopen(3, oo))
+    True
+    >>> is_decreasing(1/(x**2 - 3*x), Interval.Ropen(-oo, S(3)/2))
+    False
+    >>> is_decreasing(1/(x**2 - 3*x), Interval.Ropen(-oo, 1.5))
+    False
+    >>> is_decreasing(-x**2, Interval(-oo, 0))
+    False
+    >>> is_decreasing(-x**2 + y, Interval(-oo, 0), x)
+    False
+
+    """
+    return monotonicity_helper(expression, lambda x: x <= 0, interval, symbol)
+
+
+def is_strictly_decreasing(expression, interval=S.Reals, symbol=None):
+    """
+    Return whether the function is strictly decreasing in the given interval.
+
+    Parameters
+    ==========
+
+    expression : Expr
+        The target function which is being checked.
+    interval : Set, optional
+        The range of values in which we are testing (defaults to set of
+        all real numbers).
+    symbol : Symbol, optional
+        The symbol present in expression which gets varied over the given range.
+
+    Returns
+    =======
+
+    Boolean
+        True if ``expression`` is strictly decreasing in the given ``interval``,
+        False otherwise.
+
+    Examples
+    ========
+
+    >>> from sympy import is_strictly_decreasing
+    >>> from sympy.abc import x, y
+    >>> from sympy import S, Interval, oo
+    >>> is_strictly_decreasing(1/(x**2 - 3*x), Interval.Lopen(3, oo))
+    True
+    >>> is_strictly_decreasing(1/(x**2 - 3*x), Interval.Ropen(-oo, S(3)/2))
+    False
+    >>> is_strictly_decreasing(1/(x**2 - 3*x), Interval.Ropen(-oo, 1.5))
+    False
+    >>> is_strictly_decreasing(-x**2, Interval(-oo, 0))
+    False
+    >>> is_strictly_decreasing(-x**2 + y, Interval(-oo, 0), x)
+    False
+
+    """
+    return monotonicity_helper(expression, lambda x: x < 0, interval, symbol)
+
+
+def is_monotonic(expression, interval=S.Reals, symbol=None):
+    """
+    Return whether the function is monotonic in the given interval.
+
+    Parameters
+    ==========
+
+    expression : Expr
+        The target function which is being checked.
+    interval : Set, optional
+        The range of values in which we are testing (defaults to set of
+        all real numbers).
+    symbol : Symbol, optional
+        The symbol present in expression which gets varied over the given range.
+
+    Returns
+    =======
+
+    Boolean
+        True if ``expression`` is monotonic in the given ``interval``,
+        False otherwise.
+
+    Raises
+    ======
+
+    NotImplementedError
+        Monotonicity check has not been implemented for the queried function.
+
+    Examples
+    ========
+
+    >>> from sympy import is_monotonic
+    >>> from sympy.abc import x, y
+    >>> from sympy import S, Interval, oo
+    >>> is_monotonic(1/(x**2 - 3*x), Interval.open(S(3)/2, 3))
+    True
+    >>> is_monotonic(1/(x**2 - 3*x), Interval.open(1.5, 3))
+    True
+    >>> is_monotonic(1/(x**2 - 3*x), Interval.Lopen(3, oo))
+    True
+    >>> is_monotonic(x**3 - 3*x**2 + 4*x, S.Reals)
+    True
+    >>> is_monotonic(-x**2, S.Reals)
+    False
+    >>> is_monotonic(x**2 + y + 1, Interval(1, 2), x)
+    True
+
+    """
+    from sympy.solvers.solveset import solveset
+
+    expression = sympify(expression)
+
+    free = expression.free_symbols
+    if symbol is None and len(free) > 1:
+        raise NotImplementedError(
+            'is_monotonic has not yet been implemented'
+            ' for all multivariate expressions.'
+        )
+
+    variable = symbol or (free.pop() if free else Symbol('x'))
+    turning_points = solveset(expression.diff(variable), variable, interval)
+    return interval.intersection(turning_points) is S.EmptySet

lib/python3.12/site-packages/sympy/calculus/tests/test_accumulationbounds.py

@@ -0,0 +1,336 @@
+from sympy.core.numbers import (E, Rational, oo, pi, zoo)
+from sympy.core.singleton import S
+from sympy.core.symbol import Symbol
+from sympy.functions.elementary.exponential import (exp, log)
+from sympy.functions.elementary.miscellaneous import (Max, Min, sqrt)
+from sympy.functions.elementary.trigonometric import (cos, sin, tan)
+from sympy.calculus.accumulationbounds import AccumBounds
+from sympy.core import Add, Mul, Pow
+from sympy.core.expr import unchanged
+from sympy.testing.pytest import raises, XFAIL
+from sympy.abc import x
+
+a = Symbol('a', real=True)
+B = AccumBounds
+
+
+def test_AccumBounds():
+    assert B(1, 2).args == (1, 2)
+    assert B(1, 2).delta is S.One
+    assert B(1, 2).mid == Rational(3, 2)
+    assert B(1, 3).is_real == True
+
+    assert B(1, 1) is S.One
+
+    assert B(1, 2) + 1 == B(2, 3)
+    assert 1 + B(1, 2) == B(2, 3)
+    assert B(1, 2) + B(2, 3) == B(3, 5)
+
+    assert -B(1, 2) == B(-2, -1)
+
+    assert B(1, 2) - 1 == B(0, 1)
+    assert 1 - B(1, 2) == B(-1, 0)
+    assert B(2, 3) - B(1, 2) == B(0, 2)
+
+    assert x + B(1, 2) == Add(B(1, 2), x)
+    assert a + B(1, 2) == B(1 + a, 2 + a)
+    assert B(1, 2) - x == Add(B(1, 2), -x)
+
+    assert B(-oo, 1) + oo == B(-oo, oo)
+    assert B(1, oo) + oo is oo
+    assert B(1, oo) - oo == B(-oo, oo)
+    assert (-oo - B(-1, oo)) is -oo
+    assert B(-oo, 1) - oo is -oo
+
+    assert B(1, oo) - oo == B(-oo, oo)
+    assert B(-oo, 1) - (-oo) == B(-oo, oo)
+    assert (oo - B(1, oo)) == B(-oo, oo)
+    assert (-oo - B(1, oo)) is -oo
+
+    assert B(1, 2)/2 == B(S.Half, 1)
+    assert 2/B(2, 3) == B(Rational(2, 3), 1)
+    assert 1/B(-1, 1) == B(-oo, oo)
+
+    assert abs(B(1, 2)) == B(1, 2)
+    assert abs(B(-2, -1)) == B(1, 2)
+    assert abs(B(-2, 1)) == B(0, 2)
+    assert abs(B(-1, 2)) == B(0, 2)
+    c = Symbol('c')
+    raises(ValueError, lambda: B(0, c))
+    raises(ValueError, lambda: B(1, -1))
+    r = Symbol('r', real=True)
+    raises(ValueError, lambda: B(r, r - 1))
+
+
+def test_AccumBounds_mul():
+    assert B(1, 2)*2 == B(2, 4)
+    assert 2*B(1, 2) == B(2, 4)
+    assert B(1, 2)*B(2, 3) == B(2, 6)
+    assert B(0, 2)*B(2, oo) == B(0, oo)
+    l, r = B(-oo, oo), B(-a, a)
+    assert l*r == B(-oo, oo)
+    assert r*l == B(-oo, oo)
+    l, r = B(1, oo), B(-3, -2)
+    assert l*r == B(-oo, -2)
+    assert r*l == B(-oo, -2)
+    assert B(1, 2)*0 == 0
+    assert B(1, oo)*0 == B(0, oo)
+    assert B(-oo, 1)*0 == B(-oo, 0)
+    assert B(-oo, oo)*0 == B(-oo, oo)
+
+    assert B(1, 2)*x == Mul(B(1, 2), x, evaluate=False)
+
+    assert B(0, 2)*oo == B(0, oo)
+    assert B(-2, 0)*oo == B(-oo, 0)
+    assert B(0, 2)*(-oo) == B(-oo, 0)
+    assert B(-2, 0)*(-oo) == B(0, oo)
+    assert B(-1, 1)*oo == B(-oo, oo)
+    assert B(-1, 1)*(-oo) == B(-oo, oo)
+    assert B(-oo, oo)*oo == B(-oo, oo)
+
+
+def test_AccumBounds_div():
+    assert B(-1, 3)/B(3, 4) == B(Rational(-1, 3), 1)
+    assert B(-2, 4)/B(-3, 4) == B(-oo, oo)
+    assert B(-3, -2)/B(-4, 0) == B(S.Half, oo)
+
+    # these two tests can have a better answer
+    # after Union of B is improved
+    assert B(-3, -2)/B(-2, 1) == B(-oo, oo)
+    assert B(2, 3)/B(-2, 2) == B(-oo, oo)
+
+    assert B(-3, -2)/B(0, 4) == B(-oo, Rational(-1, 2))
+    assert B(2, 4)/B(-3, 0) == B(-oo, Rational(-2, 3))
+    assert B(2, 4)/B(0, 3) == B(Rational(2, 3), oo)
+
+    assert B(0, 1)/B(0, 1) == B(0, oo)
+    assert B(-1, 0)/B(0, 1) == B(-oo, 0)
+    assert B(-1, 2)/B(-2, 2) == B(-oo, oo)
+
+    assert 1/B(-1, 2) == B(-oo, oo)
+    assert 1/B(0, 2) == B(S.Half, oo)
+    assert (-1)/B(0, 2) == B(-oo, Rational(-1, 2))
+    assert 1/B(-oo, 0) == B(-oo, 0)
+    assert 1/B(-1, 0) == B(-oo, -1)
+    assert (-2)/B(-oo, 0) == B(0, oo)
+    assert 1/B(-oo, -1) == B(-1, 0)
+
+    assert B(1, 2)/a == Mul(B(1, 2), 1/a, evaluate=False)
+
+    assert B(1, 2)/0 == B(1, 2)*zoo
+    assert B(1, oo)/oo == B(0, oo)
+    assert B(1, oo)/(-oo) == B(-oo, 0)
+    assert B(-oo, -1)/oo == B(-oo, 0)
+    assert B(-oo, -1)/(-oo) == B(0, oo)
+    assert B(-oo, oo)/oo == B(-oo, oo)
+    assert B(-oo, oo)/(-oo) == B(-oo, oo)
+    assert B(-1, oo)/oo == B(0, oo)
+    assert B(-1, oo)/(-oo) == B(-oo, 0)
+    assert B(-oo, 1)/oo == B(-oo, 0)
+    assert B(-oo, 1)/(-oo) == B(0, oo)
+
+
+def test_issue_18795():
+    r = Symbol('r', real=True)
+    a = B(-1,1)
+    c = B(7, oo)
+    b = B(-oo, oo)
+    assert c - tan(r) == B(7-tan(r), oo)
+    assert b + tan(r) == B(-oo, oo)
+    assert (a + r)/a == B(-oo, oo)*B(r - 1, r + 1)
+    assert (b + a)/a == B(-oo, oo)
+
+
+def test_AccumBounds_func():
+    assert (x**2 + 2*x + 1).subs(x, B(-1, 1)) == B(-1, 4)
+    assert exp(B(0, 1)) == B(1, E)
+    assert exp(B(-oo, oo)) == B(0, oo)
+    assert log(B(3, 6)) == B(log(3), log(6))
+
+
+@XFAIL
+def test_AccumBounds_powf():
+    nn = Symbol('nn', nonnegative=True)
+    assert B(1 + nn, 2 + nn)**B(1, 2) == B(1 + nn, (2 + nn)**2)
+    i = Symbol('i', integer=True, negative=True)
+    assert B(1, 2)**i == B(2**i, 1)
+
+
+def test_AccumBounds_pow():
+    assert B(0, 2)**2 == B(0, 4)
+    assert B(-1, 1)**2 == B(0, 1)
+    assert B(1, 2)**2 == B(1, 4)
+    assert B(-1, 2)**3 == B(-1, 8)
+    assert B(-1, 1)**0 == 1
+
+    assert B(1, 2)**Rational(5, 2) == B(1, 4*sqrt(2))
+    assert B(0, 2)**S.Half == B(0, sqrt(2))
+
+    neg = Symbol('neg', negative=True)
+    assert unchanged(Pow, B(neg, 1), S.Half)
+    nn = Symbol('nn', nonnegative=True)
+    assert B(nn, nn + 1)**S.Half == B(sqrt(nn), sqrt(nn + 1))
+    assert B(nn, nn + 1)**nn == B(nn**nn, (nn + 1)**nn)
+    assert unchanged(Pow, B(nn, nn + 1), x)
+    i = Symbol('i', integer=True)
+    assert B(1, 2)**i == B(Min(1, 2**i), Max(1, 2**i))
+    i = Symbol('i', integer=True, nonnegative=True)
+    assert B(1, 2)**i == B(1, 2**i)
+    assert B(0, 1)**i == B(0**i, 1)
+
+    assert B(1, 5)**(-2) == B(Rational(1, 25), 1)
+    assert B(-1, 3)**(-2) == B(0, oo)
+    assert B(0, 2)**(-3) == B(Rational(1, 8), oo)
+    assert B(-2, 0)**(-3) == B(-oo, -Rational(1, 8))
+    assert B(0, 2)**(-2) == B(Rational(1, 4), oo)
+    assert B(-1, 2)**(-3) == B(-oo, oo)
+    assert B(-3, -2)**(-3) == B(Rational(-1, 8), Rational(-1, 27))
+    assert B(-3, -2)**(-2) == B(Rational(1, 9), Rational(1, 4))
+    assert B(0, oo)**S.Half == B(0, oo)
+    assert B(-oo, 0)**(-2) == B(0, oo)
+    assert B(-2, 0)**(-2) == B(Rational(1, 4), oo)
+
+    assert B(Rational(1, 3), S.Half)**oo is S.Zero
+    assert B(0, S.Half)**oo is S.Zero
+    assert B(S.Half, 1)**oo == B(0, oo)
+    assert B(0, 1)**oo == B(0, oo)
+    assert B(2, 3)**oo is oo
+    assert B(1, 2)**oo == B(0, oo)
+    assert B(S.Half, 3)**oo == B(0, oo)
+    assert B(Rational(-1, 3), Rational(-1, 4))**oo is S.Zero
+    assert B(-1, Rational(-1, 2))**oo is S.NaN
+    assert B(-3, -2)**oo is zoo
+    assert B(-2, -1)**oo is S.NaN
+    assert B(-2, Rational(-1, 2))**oo is S.NaN
+    assert B(Rational(-1, 2), S.Half)**oo is S.Zero
+    assert B(Rational(-1, 2), 1)**oo == B(0, oo)
+    assert B(Rational(-2, 3), 2)**oo == B(0, oo)
+    assert B(-1, 1)**oo == B(-oo, oo)
+    assert B(-1, S.Half)**oo == B(-oo, oo)
+    assert B(-1, 2)**oo == B(-oo, oo)
+    assert B(-2, S.Half)**oo == B(-oo, oo)
+
+    assert B(1, 2)**x == Pow(B(1, 2), x, evaluate=False)
+
+    assert B(2, 3)**(-oo) is S.Zero
+    assert B(0, 2)**(-oo) == B(0, oo)
+    assert B(-1, 2)**(-oo) == B(-oo, oo)
+
+    assert (tan(x)**sin(2*x)).subs(x, B(0, pi/2)) == \
+        Pow(B(-oo, oo), B(0, 1))
+
+
+def test_AccumBounds_exponent():
+    # base is 0
+    z = 0**B(a, a + S.Half)
+    assert z.subs(a, 0) == B(0, 1)
+    assert z.subs(a, 1) == 0
+    p = z.subs(a, -1)
+    assert p.is_Pow and p.args == (0, B(-1, -S.Half))
+    # base > 0
+    #   when base is 1 the type of bounds does not matter
+    assert 1**B(a, a + 1) == 1
+    #  otherwise we need to know if 0 is in the bounds
+    assert S.Half**B(-2, 2) == B(S(1)/4, 4)
+    assert 2**B(-2, 2) == B(S(1)/4, 4)
+
+    # +eps may introduce +oo
+    # if there is a negative integer exponent
+    assert B(0, 1)**B(S(1)/2, 1) == B(0, 1)
+    assert B(0, 1)**B(0, 1) == B(0, 1)
+
+    # positive bases have positive bounds
+    assert B(2, 3)**B(-3, -2) == B(S(1)/27, S(1)/4)
+    assert B(2, 3)**B(-3, 2) == B(S(1)/27, 9)
+
+    # bounds generating imaginary parts unevaluated
+    assert unchanged(Pow, B(-1, 1), B(1, 2))
+    assert B(0, S(1)/2)**B(1, oo) == B(0, S(1)/2)
+    assert B(0, 1)**B(1, oo) == B(0, oo)
+    assert B(0, 2)**B(1, oo) == B(0, oo)
+    assert B(0, oo)**B(1, oo) == B(0, oo)
+    assert B(S(1)/2, 1)**B(1, oo) == B(0, oo)
+    assert B(S(1)/2, 1)**B(-oo, -1) == B(0, oo)
+    assert B(S(1)/2, 1)**B(-oo, oo) == B(0, oo)
+    assert B(S(1)/2, 2)**B(1, oo) == B(0, oo)
+    assert B(S(1)/2, 2)**B(-oo, -1) == B(0, oo)
+    assert B(S(1)/2, 2)**B(-oo, oo) == B(0, oo)
+    assert B(S(1)/2, oo)**B(1, oo) == B(0, oo)
+    assert B(S(1)/2, oo)**B(-oo, -1) == B(0, oo)
+    assert B(S(1)/2, oo)**B(-oo, oo) == B(0, oo)
+    assert B(1, 2)**B(1, oo) == B(0, oo)
+    assert B(1, 2)**B(-oo, -1) == B(0, oo)
+    assert B(1, 2)**B(-oo, oo) == B(0, oo)
+    assert B(1, oo)**B(1, oo) == B(0, oo)
+    assert B(1, oo)**B(-oo, -1) == B(0, oo)
+    assert B(1, oo)**B(-oo, oo) == B(0, oo)
+    assert B(2, oo)**B(1, oo) == B(2, oo)
+    assert B(2, oo)**B(-oo, -1) == B(0, S(1)/2)
+    assert B(2, oo)**B(-oo, oo) == B(0, oo)
+
+
+def test_comparison_AccumBounds():
+    assert (B(1, 3) < 4) == S.true
+    assert (B(1, 3) < -1) == S.false
+    assert (B(1, 3) < 2).rel_op == '<'
+    assert (B(1, 3) <= 2).rel_op == '<='
+
+    assert (B(1, 3) > 4) == S.false
+    assert (B(1, 3) > -1) == S.true
+    assert (B(1, 3) > 2).rel_op == '>'
+    assert (B(1, 3) >= 2).rel_op == '>='
+
+    assert (B(1, 3) < B(4, 6)) == S.true
+    assert (B(1, 3) < B(2, 4)).rel_op == '<'
+    assert (B(1, 3) < B(-2, 0)) == S.false
+
+    assert (B(1, 3) <= B(4, 6)) == S.true
+    assert (B(1, 3) <= B(-2, 0)) == S.false
+
+    assert (B(1, 3) > B(4, 6)) == S.false
+    assert (B(1, 3) > B(-2, 0)) == S.true
+
+    assert (B(1, 3) >= B(4, 6)) == S.false
+    assert (B(1, 3) >= B(-2, 0)) == S.true
+
+    # issue 13499
+    assert (cos(x) > 0).subs(x, oo) == (B(-1, 1) > 0)
+
+    c = Symbol('c')
+    raises(TypeError, lambda: (B(0, 1) < c))
+    raises(TypeError, lambda: (B(0, 1) <= c))
+    raises(TypeError, lambda: (B(0, 1) > c))
+    raises(TypeError, lambda: (B(0, 1) >= c))
+
+
+def test_contains_AccumBounds():
+    assert (1 in B(1, 2)) == S.true
+    raises(TypeError, lambda: a in B(1, 2))
+    assert 0 in B(-1, 0)
+    raises(TypeError, lambda:
+        (cos(1)**2 + sin(1)**2 - 1) in B(-1, 0))
+    assert (-oo in B(1, oo)) == S.true
+    assert (oo in B(-oo, 0)) == S.true
+
+    # issue 13159
+    assert Mul(0, B(-1, 1)) == Mul(B(-1, 1), 0) == 0
+    import itertools
+    for perm in itertools.permutations([0, B(-1, 1), x]):
+        assert Mul(*perm) == 0
+
+
+def test_intersection_AccumBounds():
+    assert B(0, 3).intersection(B(1, 2)) == B(1, 2)
+    assert B(0, 3).intersection(B(1, 4)) == B(1, 3)
+    assert B(0, 3).intersection(B(-1, 2)) == B(0, 2)
+    assert B(0, 3).intersection(B(-1, 4)) == B(0, 3)
+    assert B(0, 1).intersection(B(2, 3)) == S.EmptySet
+    raises(TypeError, lambda: B(0, 3).intersection(1))
+
+
+def test_union_AccumBounds():
+    assert B(0, 3).union(B(1, 2)) == B(0, 3)
+    assert B(0, 3).union(B(1, 4)) == B(0, 4)
+    assert B(0, 3).union(B(-1, 2)) == B(-1, 3)
+    assert B(0, 3).union(B(-1, 4)) == B(-1, 4)
+    raises(TypeError, lambda: B(0, 3).union(1))

lib/python3.12/site-packages/sympy/calculus/tests/test_euler.py

@@ -0,0 +1,74 @@
+from sympy.core.function import (Derivative as D, Function)
+from sympy.core.relational import Eq
+from sympy.core.symbol import (Symbol, symbols)
+from sympy.functions.elementary.trigonometric import (cos, sin)
+from sympy.testing.pytest import raises
+from sympy.calculus.euler import euler_equations as euler
+
+
+def test_euler_interface():
+    x = Function('x')
+    y = Symbol('y')
+    t = Symbol('t')
+    raises(TypeError, lambda: euler())
+    raises(TypeError, lambda: euler(D(x(t), t)*y(t), [x(t), y]))
+    raises(ValueError, lambda: euler(D(x(t), t)*x(y), [x(t), x(y)]))
+    raises(TypeError, lambda: euler(D(x(t), t)**2, x(0)))
+    raises(TypeError, lambda: euler(D(x(t), t)*y(t), [t]))
+    assert euler(D(x(t), t)**2/2, {x(t)}) == [Eq(-D(x(t), t, t), 0)]
+    assert euler(D(x(t), t)**2/2, x(t), {t}) == [Eq(-D(x(t), t, t), 0)]
+
+
+def test_euler_pendulum():
+    x = Function('x')
+    t = Symbol('t')
+    L = D(x(t), t)**2/2 + cos(x(t))
+    assert euler(L, x(t), t) == [Eq(-sin(x(t)) - D(x(t), t, t), 0)]
+
+
+def test_euler_henonheiles():
+    x = Function('x')
+    y = Function('y')
+    t = Symbol('t')
+    L = sum(D(z(t), t)**2/2 - z(t)**2/2 for z in [x, y])
+    L += -x(t)**2*y(t) + y(t)**3/3
+    assert euler(L, [x(t), y(t)], t) == [Eq(-2*x(t)*y(t) - x(t) -
+                                            D(x(t), t, t), 0),
+                                         Eq(-x(t)**2 + y(t)**2 -
+                                            y(t) - D(y(t), t, t), 0)]
+
+
+def test_euler_sineg():
+    psi = Function('psi')
+    t = Symbol('t')
+    x = Symbol('x')
+    L = D(psi(t, x), t)**2/2 - D(psi(t, x), x)**2/2 + cos(psi(t, x))
+    assert euler(L, psi(t, x), [t, x]) == [Eq(-sin(psi(t, x)) -
+                                              D(psi(t, x), t, t) +
+                                              D(psi(t, x), x, x), 0)]
+
+
+def test_euler_high_order():
+    # an example from hep-th/0309038
+    m = Symbol('m')
+    k = Symbol('k')
+    x = Function('x')
+    y = Function('y')
+    t = Symbol('t')
+    L = (m*D(x(t), t)**2/2 + m*D(y(t), t)**2/2 -
+         k*D(x(t), t)*D(y(t), t, t) + k*D(y(t), t)*D(x(t), t, t))
+    assert euler(L, [x(t), y(t)]) == [Eq(2*k*D(y(t), t, t, t) -
+                                         m*D(x(t), t, t), 0),
+                                      Eq(-2*k*D(x(t), t, t, t) -
+                                         m*D(y(t), t, t), 0)]
+
+    w = Symbol('w')
+    L = D(x(t, w), t, w)**2/2
+    assert euler(L) == [Eq(D(x(t, w), t, t, w, w), 0)]
+
+def test_issue_18653():
+    x, y, z = symbols("x y z")
+    f, g, h = symbols("f g h", cls=Function, args=(x, y))
+    f, g, h = f(), g(), h()
+    expr2 = f.diff(x)*h.diff(z)
+    assert euler(expr2, (f,), (x, y)) == []

lib/python3.12/site-packages/sympy/calculus/tests/test_finite_diff.py

@@ -0,0 +1,168 @@
+from itertools import product
+
+from sympy.core.function import (Function, diff)
+from sympy.core.numbers import Rational
+from sympy.core.singleton import S
+from sympy.core.symbol import symbols
+from sympy.functions.elementary.exponential import exp
+from sympy.calculus.finite_diff import (
+    apply_finite_diff, differentiate_finite, finite_diff_weights,
+    _as_finite_diff
+)
+from sympy.testing.pytest import raises, warns_deprecated_sympy
+
+
+def test_apply_finite_diff():
+    x, h = symbols('x h')
+    f = Function('f')
+    assert (apply_finite_diff(1, [x-h, x+h], [f(x-h), f(x+h)], x) -
+            (f(x+h)-f(x-h))/(2*h)).simplify() == 0
+
+    assert (apply_finite_diff(1, [5, 6, 7], [f(5), f(6), f(7)], 5) -
+            (Rational(-3, 2)*f(5) + 2*f(6) - S.Half*f(7))).simplify() == 0
+    raises(ValueError, lambda: apply_finite_diff(1, [x, h], [f(x)]))
+
+
+def test_finite_diff_weights():
+
+    d = finite_diff_weights(1, [5, 6, 7], 5)
+    assert d[1][2] == [Rational(-3, 2), 2, Rational(-1, 2)]
+
+    # Table 1, p. 702 in doi:10.1090/S0025-5718-1988-0935077-0
+    # --------------------------------------------------------
+    xl = [0, 1, -1, 2, -2, 3, -3, 4, -4]
+
+    # d holds all coefficients
+    d = finite_diff_weights(4, xl, S.Zero)
+
+    # Zeroeth derivative
+    for i in range(5):
+        assert d[0][i] == [S.One] + [S.Zero]*8
+
+    # First derivative
+    assert d[1][0] == [S.Zero]*9
+    assert d[1][2] == [S.Zero, S.Half, Rational(-1, 2)] + [S.Zero]*6
+    assert d[1][4] == [S.Zero, Rational(2, 3), Rational(-2, 3), Rational(-1, 12), Rational(1, 12)] + [S.Zero]*4
+    assert d[1][6] == [S.Zero, Rational(3, 4), Rational(-3, 4), Rational(-3, 20), Rational(3, 20),
+                       Rational(1, 60), Rational(-1, 60)] + [S.Zero]*2
+    assert d[1][8] == [S.Zero, Rational(4, 5), Rational(-4, 5), Rational(-1, 5), Rational(1, 5),
+                       Rational(4, 105), Rational(-4, 105), Rational(-1, 280), Rational(1, 280)]
+
+    # Second derivative
+    for i in range(2):
+        assert d[2][i] == [S.Zero]*9
+    assert d[2][2] == [-S(2), S.One, S.One] + [S.Zero]*6
+    assert d[2][4] == [Rational(-5, 2), Rational(4, 3), Rational(4, 3), Rational(-1, 12), Rational(-1, 12)] + [S.Zero]*4
+    assert d[2][6] == [Rational(-49, 18), Rational(3, 2), Rational(3, 2), Rational(-3, 20), Rational(-3, 20),
+                       Rational(1, 90), Rational(1, 90)] + [S.Zero]*2
+    assert d[2][8] == [Rational(-205, 72), Rational(8, 5), Rational(8, 5), Rational(-1, 5), Rational(-1, 5),
+                       Rational(8, 315), Rational(8, 315), Rational(-1, 560), Rational(-1, 560)]
+
+    # Third derivative
+    for i in range(3):
+        assert d[3][i] == [S.Zero]*9
+    assert d[3][4] == [S.Zero, -S.One, S.One, S.Half, Rational(-1, 2)] + [S.Zero]*4
+    assert d[3][6] == [S.Zero, Rational(-13, 8), Rational(13, 8), S.One, -S.One,
+                       Rational(-1, 8), Rational(1, 8)] + [S.Zero]*2
+    assert d[3][8] == [S.Zero, Rational(-61, 30), Rational(61, 30), Rational(169, 120), Rational(-169, 120),
+                       Rational(-3, 10), Rational(3, 10), Rational(7, 240), Rational(-7, 240)]
+
+    # Fourth derivative
+    for i in range(4):
+        assert d[4][i] == [S.Zero]*9
+    assert d[4][4] == [S(6), -S(4), -S(4), S.One, S.One] + [S.Zero]*4
+    assert d[4][6] == [Rational(28, 3), Rational(-13, 2), Rational(-13, 2), S(2), S(2),
+                       Rational(-1, 6), Rational(-1, 6)] + [S.Zero]*2
+    assert d[4][8] == [Rational(91, 8), Rational(-122, 15), Rational(-122, 15), Rational(169, 60), Rational(169, 60),
+                       Rational(-2, 5), Rational(-2, 5), Rational(7, 240), Rational(7, 240)]
+
+    # Table 2, p. 703 in doi:10.1090/S0025-5718-1988-0935077-0
+    # --------------------------------------------------------
+    xl = [[j/S(2) for j in list(range(-i*2+1, 0, 2))+list(range(1, i*2+1, 2))]
+          for i in range(1, 5)]
+
+    # d holds all coefficients
+    d = [finite_diff_weights({0: 1, 1: 2, 2: 4, 3: 4}[i], xl[i], 0) for
+         i in range(4)]
+
+    # Zeroth derivative
+    assert d[0][0][1] == [S.Half, S.Half]
+    assert d[1][0][3] == [Rational(-1, 16), Rational(9, 16), Rational(9, 16), Rational(-1, 16)]
+    assert d[2][0][5] == [Rational(3, 256), Rational(-25, 256), Rational(75, 128), Rational(75, 128),
+                          Rational(-25, 256), Rational(3, 256)]
+    assert d[3][0][7] == [Rational(-5, 2048), Rational(49, 2048), Rational(-245, 2048), Rational(1225, 2048),
+                          Rational(1225, 2048), Rational(-245, 2048), Rational(49, 2048), Rational(-5, 2048)]
+
+    # First derivative
+    assert d[0][1][1] == [-S.One, S.One]
+    assert d[1][1][3] == [Rational(1, 24), Rational(-9, 8), Rational(9, 8), Rational(-1, 24)]
+    assert d[2][1][5] == [Rational(-3, 640), Rational(25, 384), Rational(-75, 64),
+                          Rational(75, 64), Rational(-25, 384), Rational(3, 640)]
+    assert d[3][1][7] == [Rational(5, 7168), Rational(-49, 5120),
+                          Rational(245, 3072), Rational(-1225, 1024),
+                          Rational(1225, 1024), Rational(-245, 3072),
+                          Rational(49, 5120), Rational(-5, 7168)]
+
+    # Reasonably the rest of the table is also correct... (testing of that
+    # deemed excessive at the moment)
+    raises(ValueError, lambda: finite_diff_weights(-1, [1, 2]))
+    raises(ValueError, lambda: finite_diff_weights(1.2, [1, 2]))
+    x = symbols('x')
+    raises(ValueError, lambda: finite_diff_weights(x, [1, 2]))
+
+
+def test_as_finite_diff():
+    x = symbols('x')
+    f = Function('f')
+    dx = Function('dx')
+
+    _as_finite_diff(f(x).diff(x), [x-2, x-1, x, x+1, x+2])
+
+    # Use of undefined functions in ``points``
+    df_true = -f(x+dx(x)/2-dx(x+dx(x)/2)/2) / dx(x+dx(x)/2) \
+              + f(x+dx(x)/2+dx(x+dx(x)/2)/2) / dx(x+dx(x)/2)
+    df_test = diff(f(x), x).as_finite_difference(points=dx(x), x0=x+dx(x)/2)
+    assert (df_test - df_true).simplify() == 0
+
+
+def test_differentiate_finite():
+    x, y, h = symbols('x y h')
+    f = Function('f')
+    with warns_deprecated_sympy():
+        res0 = differentiate_finite(f(x, y) + exp(42), x, y, evaluate=True)
+    xm, xp, ym, yp = [v + sign*S.Half for v, sign in product([x, y], [-1, 1])]
+    ref0 = f(xm, ym) + f(xp, yp) - f(xm, yp) - f(xp, ym)
+    assert (res0 - ref0).simplify() == 0
+
+    g = Function('g')
+    with warns_deprecated_sympy():
+        res1 = differentiate_finite(f(x)*g(x) + 42, x, evaluate=True)
+    ref1 = (-f(x - S.Half) + f(x + S.Half))*g(x) + \
+           (-g(x - S.Half) + g(x + S.Half))*f(x)
+    assert (res1 - ref1).simplify() == 0
+
+    res2 = differentiate_finite(f(x) + x**3 + 42, x, points=[x-1, x+1])
+    ref2 = (f(x + 1) + (x + 1)**3 - f(x - 1) - (x - 1)**3)/2
+    assert (res2 - ref2).simplify() == 0
+    raises(TypeError, lambda: differentiate_finite(f(x)*g(x), x,
+                                                   pints=[x-1, x+1]))
+
+    res3 = differentiate_finite(f(x)*g(x).diff(x), x)
+    ref3 = (-g(x) + g(x + 1))*f(x + S.Half) - (g(x) - g(x - 1))*f(x - S.Half)
+    assert res3 == ref3
+
+    res4 = differentiate_finite(f(x)*g(x).diff(x).diff(x), x)
+    ref4 = -((g(x - Rational(3, 2)) - 2*g(x - S.Half) + g(x + S.Half))*f(x - S.Half)) \
+           + (g(x - S.Half) - 2*g(x + S.Half) + g(x + Rational(3, 2)))*f(x + S.Half)
+    assert res4 == ref4
+
+    res5_expr = f(x).diff(x)*g(x).diff(x)
+    res5 = differentiate_finite(res5_expr, points=[x-h, x, x+h])
+    ref5 = (-2*f(x)/h + f(-h + x)/(2*h) + 3*f(h + x)/(2*h))*(-2*g(x)/h + g(-h + x)/(2*h) \
+           + 3*g(h + x)/(2*h))/(2*h) - (2*f(x)/h - 3*f(-h + x)/(2*h) - \
+           f(h + x)/(2*h))*(2*g(x)/h - 3*g(-h + x)/(2*h) - g(h + x)/(2*h))/(2*h)
+    assert res5 == ref5
+
+    res6 = res5.limit(h, 0).doit()
+    ref6 = diff(res5_expr, x)
+    assert res6 == ref6

lib/python3.12/site-packages/sympy/calculus/tests/test_singularities.py

@@ -0,0 +1,122 @@
+from sympy.core.numbers import (I, Rational, pi, oo)
+from sympy.core.singleton import S
+from sympy.core.symbol import Symbol, Dummy
+from sympy.core.function import Lambda
+from sympy.functions.elementary.exponential import (exp, log)
+from sympy.functions.elementary.trigonometric import sec, csc
+from sympy.functions.elementary.hyperbolic import (coth, sech,
+                                                   atanh, asech, acoth, acsch)
+from sympy.functions.elementary.miscellaneous import sqrt
+from sympy.calculus.singularities import (
+    singularities,
+    is_increasing,
+    is_strictly_increasing,
+    is_decreasing,
+    is_strictly_decreasing,
+    is_monotonic
+)
+from sympy.sets import Interval, FiniteSet, Union, ImageSet
+from sympy.testing.pytest import raises
+from sympy.abc import x, y
+
+
+def test_singularities():
+    x = Symbol('x')
+    assert singularities(x**2, x) == S.EmptySet
+    assert singularities(x/(x**2 + 3*x + 2), x) == FiniteSet(-2, -1)
+    assert singularities(1/(x**2 + 1), x) == FiniteSet(I, -I)
+    assert singularities(x/(x**3 + 1), x) == \
+        FiniteSet(-1, (1 - sqrt(3) * I) / 2, (1 + sqrt(3) * I) / 2)
+    assert singularities(1/(y**2 + 2*I*y + 1), y) == \
+        FiniteSet(-I + sqrt(2)*I, -I - sqrt(2)*I)
+    _n = Dummy('n')
+    assert singularities(sech(x), x).dummy_eq(Union(
+        ImageSet(Lambda(_n, 2*_n*I*pi + I*pi/2), S.Integers),
+        ImageSet(Lambda(_n, 2*_n*I*pi + 3*I*pi/2), S.Integers)))
+    assert singularities(coth(x), x).dummy_eq(Union(
+        ImageSet(Lambda(_n, 2*_n*I*pi + I*pi), S.Integers),
+        ImageSet(Lambda(_n, 2*_n*I*pi), S.Integers)))
+    assert singularities(atanh(x), x) == FiniteSet(-1, 1)
+    assert singularities(acoth(x), x) == FiniteSet(-1, 1)
+    assert singularities(asech(x), x) == FiniteSet(0)
+    assert singularities(acsch(x), x) == FiniteSet(0)
+
+    x = Symbol('x', real=True)
+    assert singularities(1/(x**2 + 1), x) == S.EmptySet
+    assert singularities(exp(1/x), x, S.Reals) == FiniteSet(0)
+    assert singularities(exp(1/x), x, Interval(1, 2)) == S.EmptySet
+    assert singularities(log((x - 2)**2), x, Interval(1, 3)) == FiniteSet(2)
+    raises(NotImplementedError, lambda: singularities(x**-oo, x))
+    assert singularities(sec(x), x, Interval(0, 3*pi)) == FiniteSet(
+        pi/2, 3*pi/2, 5*pi/2)
+    assert singularities(csc(x), x, Interval(0, 3*pi)) == FiniteSet(
+        0, pi, 2*pi, 3*pi)
+
+
+def test_is_increasing():
+    """Test whether is_increasing returns correct value."""
+    a = Symbol('a', negative=True)
+
+    assert is_increasing(x**3 - 3*x**2 + 4*x, S.Reals)
+    assert is_increasing(-x**2, Interval(-oo, 0))
+    assert not is_increasing(-x**2, Interval(0, oo))
+    assert not is_increasing(4*x**3 - 6*x**2 - 72*x + 30, Interval(-2, 3))
+    assert is_increasing(x**2 + y, Interval(1, oo), x)
+    assert is_increasing(-x**2*a, Interval(1, oo), x)
+    assert is_increasing(1)
+
+    assert is_increasing(4*x**3 - 6*x**2 - 72*x + 30, Interval(-2, 3)) is False
+
+
+def test_is_strictly_increasing():
+    """Test whether is_strictly_increasing returns correct value."""
+    assert is_strictly_increasing(
+        4*x**3 - 6*x**2 - 72*x + 30, Interval.Ropen(-oo, -2))
+    assert is_strictly_increasing(
+        4*x**3 - 6*x**2 - 72*x + 30, Interval.Lopen(3, oo))
+    assert not is_strictly_increasing(
+        4*x**3 - 6*x**2 - 72*x + 30, Interval.open(-2, 3))
+    assert not is_strictly_increasing(-x**2, Interval(0, oo))
+    assert not is_strictly_decreasing(1)
+
+    assert is_strictly_increasing(4*x**3 - 6*x**2 - 72*x + 30, Interval.open(-2, 3)) is False
+
+
+def test_is_decreasing():
+    """Test whether is_decreasing returns correct value."""
+    b = Symbol('b', positive=True)
+
+    assert is_decreasing(1/(x**2 - 3*x), Interval.open(Rational(3,2), 3))
+    assert is_decreasing(1/(x**2 - 3*x), Interval.open(1.5, 3))
+    assert is_decreasing(1/(x**2 - 3*x), Interval.Lopen(3, oo))
+    assert not is_decreasing(1/(x**2 - 3*x), Interval.Ropen(-oo, Rational(3, 2)))
+    assert not is_decreasing(-x**2, Interval(-oo, 0))
+    assert not is_decreasing(-x**2*b, Interval(-oo, 0), x)
+
+
+def test_is_strictly_decreasing():
+    """Test whether is_strictly_decreasing returns correct value."""
+    assert is_strictly_decreasing(1/(x**2 - 3*x), Interval.Lopen(3, oo))
+    assert not is_strictly_decreasing(
+        1/(x**2 - 3*x), Interval.Ropen(-oo, Rational(3, 2)))
+    assert not is_strictly_decreasing(-x**2, Interval(-oo, 0))
+    assert not is_strictly_decreasing(1)
+    assert is_strictly_decreasing(1/(x**2 - 3*x), Interval.open(Rational(3,2), 3))
+    assert is_strictly_decreasing(1/(x**2 - 3*x), Interval.open(1.5, 3))
+
+
+def test_is_monotonic():
+    """Test whether is_monotonic returns correct value."""
+    assert is_monotonic(1/(x**2 - 3*x), Interval.open(Rational(3,2), 3))
+    assert is_monotonic(1/(x**2 - 3*x), Interval.open(1.5, 3))
+    assert is_monotonic(1/(x**2 - 3*x), Interval.Lopen(3, oo))
+    assert is_monotonic(x**3 - 3*x**2 + 4*x, S.Reals)
+    assert not is_monotonic(-x**2, S.Reals)
+    assert is_monotonic(x**2 + y + 1, Interval(1, 2), x)
+    raises(NotImplementedError, lambda: is_monotonic(x**2 + y + 1))
+
+
+def test_issue_23401():
+    x = Symbol('x')
+    expr = (x + 1)/(-1.0e-3*x**2 + 0.1*x + 0.1)
+    assert is_increasing(expr, Interval(1,2), x)

lib/python3.12/site-packages/sympy/calculus/tests/test_util.py

@@ -0,0 +1,392 @@
+from sympy.core.function import Lambda
+from sympy.core.numbers import (E, I, Rational, oo, pi)
+from sympy.core.relational import Eq
+from sympy.core.singleton import S
+from sympy.core.symbol import (Dummy, Symbol)
+from sympy.functions.elementary.complexes import (Abs, re)
+from sympy.functions.elementary.exponential import (exp, log)
+from sympy.functions.elementary.integers import frac
+from sympy.functions.elementary.miscellaneous import sqrt
+from sympy.functions.elementary.piecewise import Piecewise
+from sympy.functions.elementary.trigonometric import (
+    cos, cot, csc, sec, sin, tan, asin, acos, atan, acot, asec, acsc)
+from sympy.functions.elementary.hyperbolic import (sinh, cosh, tanh, coth,
+    sech, csch, asinh, acosh, atanh, acoth, asech, acsch)
+from sympy.functions.special.gamma_functions import gamma
+from sympy.functions.special.error_functions import expint
+from sympy.matrices.expressions.matexpr import MatrixSymbol
+from sympy.simplify.simplify import simplify
+from sympy.calculus.util import (function_range, continuous_domain, not_empty_in,
+                                 periodicity, lcim, is_convex,
+                                 stationary_points, minimum, maximum)
+from sympy.sets.sets import (Interval, FiniteSet, Complement, Union)
+from sympy.sets.fancysets import ImageSet
+from sympy.sets.conditionset import ConditionSet
+from sympy.testing.pytest import XFAIL, raises, _both_exp_pow, slow
+from sympy.abc import x, y
+
+a = Symbol('a', real=True)
+
+def test_function_range():
+    assert function_range(sin(x), x, Interval(-pi/2, pi/2)
+        ) == Interval(-1, 1)
+    assert function_range(sin(x), x, Interval(0, pi)
+        ) == Interval(0, 1)
+    assert function_range(tan(x), x, Interval(0, pi)
+        ) == Interval(-oo, oo)
+    assert function_range(tan(x), x, Interval(pi/2, pi)
+        ) == Interval(-oo, 0)
+    assert function_range((x + 3)/(x - 2), x, Interval(-5, 5)
+        ) == Union(Interval(-oo, Rational(2, 7)), Interval(Rational(8, 3), oo))
+    assert function_range(1/(x**2), x, Interval(-1, 1)
+        ) == Interval(1, oo)
+    assert function_range(exp(x), x, Interval(-1, 1)
+        ) == Interval(exp(-1), exp(1))
+    assert function_range(log(x) - x, x, S.Reals
+        ) == Interval(-oo, -1)
+    assert function_range(sqrt(3*x - 1), x, Interval(0, 2)
+        ) == Interval(0, sqrt(5))
+    assert function_range(x*(x - 1) - (x**2 - x), x, S.Reals
+        ) == FiniteSet(0)
+    assert function_range(x*(x - 1) - (x**2 - x) + y, x, S.Reals
+        ) == FiniteSet(y)
+    assert function_range(sin(x), x, Union(Interval(-5, -3), FiniteSet(4))
+        ) == Union(Interval(-sin(3), 1), FiniteSet(sin(4)))
+    assert function_range(cos(x), x, Interval(-oo, -4)
+        ) == Interval(-1, 1)
+    assert function_range(cos(x), x, S.EmptySet) == S.EmptySet
+    assert function_range(x/sqrt(x**2+1), x, S.Reals) == Interval.open(-1,1)
+    raises(NotImplementedError, lambda : function_range(
+        exp(x)*(sin(x) - cos(x))/2 - x, x, S.Reals))
+    raises(NotImplementedError, lambda : function_range(
+        sin(x) + x, x, S.Reals)) # issue 13273
+    raises(NotImplementedError, lambda : function_range(
+        log(x), x, S.Integers))
+    raises(NotImplementedError, lambda : function_range(
+        sin(x)/2, x, S.Naturals))
+
+
+@slow
+def test_function_range1():
+    assert function_range(tan(x)**2 + tan(3*x)**2 + 1, x, S.Reals) == Interval(1,oo)
+
+
+def test_continuous_domain():
+    assert continuous_domain(sin(x), x, Interval(0, 2*pi)) == Interval(0, 2*pi)
+    assert continuous_domain(tan(x), x, Interval(0, 2*pi)) == \
+        Union(Interval(0, pi/2, False, True), Interval(pi/2, pi*Rational(3, 2), True, True),
+              Interval(pi*Rational(3, 2), 2*pi, True, False))
+    assert continuous_domain(cot(x), x, Interval(0, 2*pi)) == Union(
+        Interval.open(0, pi), Interval.open(pi, 2*pi))
+    assert continuous_domain((x - 1)/((x - 1)**2), x, S.Reals) == \
+        Union(Interval(-oo, 1, True, True), Interval(1, oo, True, True))
+    assert continuous_domain(log(x) + log(4*x - 1), x, S.Reals) == \
+        Interval(Rational(1, 4), oo, True, True)
+    assert continuous_domain(1/sqrt(x - 3), x, S.Reals) == Interval(3, oo, True, True)
+    assert continuous_domain(1/x - 2, x, S.Reals) == \
+        Union(Interval.open(-oo, 0), Interval.open(0, oo))
+    assert continuous_domain(1/(x**2 - 4) + 2, x, S.Reals) == \
+        Union(Interval.open(-oo, -2), Interval.open(-2, 2), Interval.open(2, oo))
+    assert continuous_domain((x+1)**pi, x, S.Reals) == Interval(-1, oo)
+    assert continuous_domain((x+1)**(pi/2), x, S.Reals) == Interval(-1, oo)
+    assert continuous_domain(x**x, x, S.Reals) == Interval(0, oo)
+    assert continuous_domain((x+1)**log(x**2), x, S.Reals) == Union(
+        Interval.Ropen(-1, 0), Interval.open(0, oo))
+    domain = continuous_domain(log(tan(x)**2 + 1), x, S.Reals)
+    assert not domain.contains(3*pi/2)
+    assert domain.contains(5)
+    d = Symbol('d', even=True, zero=False)
+    assert continuous_domain(x**(1/d), x, S.Reals) == Interval(0, oo)
+    n = Dummy('n')
+    assert continuous_domain(1/sin(x), x, S.Reals).dummy_eq(Complement(
+        S.Reals, Union(ImageSet(Lambda(n, 2*n*pi + pi), S.Integers),
+                       ImageSet(Lambda(n, 2*n*pi), S.Integers))))
+    assert continuous_domain(sin(x) + cos(x), x, S.Reals) == S.Reals
+    assert continuous_domain(asin(x), x, S.Reals) == Interval(-1, 1) # issue #21786
+    assert continuous_domain(1/acos(log(x)), x, S.Reals) == Interval.Ropen(exp(-1), E)
+    assert continuous_domain(sinh(x)+cosh(x), x, S.Reals) == S.Reals
+    assert continuous_domain(tanh(x)+sech(x), x, S.Reals) == S.Reals
+    assert continuous_domain(atan(x)+asinh(x), x, S.Reals) == S.Reals
+    assert continuous_domain(acosh(x), x, S.Reals) == Interval(1, oo)
+    assert continuous_domain(atanh(x), x, S.Reals) == Interval.open(-1, 1)
+    assert continuous_domain(atanh(x)+acosh(x), x, S.Reals) == S.EmptySet
+    assert continuous_domain(asech(x), x, S.Reals) == Interval.Lopen(0, 1)
+    assert continuous_domain(acoth(x), x, S.Reals) == Union(
+        Interval.open(-oo, -1), Interval.open(1, oo))
+    assert continuous_domain(asec(x), x, S.Reals) == Union(
+        Interval(-oo, -1), Interval(1, oo))
+    assert continuous_domain(acsc(x), x, S.Reals) == Union(
+        Interval(-oo, -1), Interval(1, oo))
+    for f in (coth, acsch, csch):
+        assert continuous_domain(f(x), x, S.Reals) == Union(
+            Interval.open(-oo, 0), Interval.open(0, oo))
+    assert continuous_domain(acot(x), x, S.Reals).contains(0) == False
+    assert continuous_domain(1/(exp(x) - x), x, S.Reals) == Complement(
+        S.Reals, ConditionSet(x, Eq(-x + exp(x), 0), S.Reals))
+    assert continuous_domain(frac(x**2), x, Interval(-2,-1)) == Union(
+        Interval.open(-2, -sqrt(3)), Interval.open(-sqrt(2), -1),
+        Interval.open(-sqrt(3), -sqrt(2)))
+    assert continuous_domain(frac(x), x, S.Reals) == Complement(
+        S.Reals, S.Integers)
+    raises(NotImplementedError, lambda : continuous_domain(
+        1/(x**2+1), x, S.Complexes))
+    raises(NotImplementedError, lambda : continuous_domain(
+        gamma(x), x, Interval(-5,0)))
+    assert continuous_domain(x + gamma(pi), x, S.Reals) == S.Reals
+
+
+@XFAIL
+def test_continuous_domain_acot():
+    acot_cont = Piecewise((pi+acot(x), x<0), (acot(x), True))
+    assert continuous_domain(acot_cont, x, S.Reals) == S.Reals
+
+@XFAIL
+def test_continuous_domain_gamma():
+    assert continuous_domain(gamma(x), x, S.Reals).contains(-1) == False
+
+@XFAIL
+def test_continuous_domain_neg_power():
+    assert continuous_domain((x-2)**(1-x), x, S.Reals) == Interval.open(2, oo)
+
+
+def test_not_empty_in():
+    assert not_empty_in(FiniteSet(x, 2*x).intersect(Interval(1, 2, True, False)), x) == \
+        Interval(S.Half, 2, True, False)
+    assert not_empty_in(FiniteSet(x, x**2).intersect(Interval(1, 2)), x) == \
+        Union(Interval(-sqrt(2), -1), Interval(1, 2))
+    assert not_empty_in(FiniteSet(x**2 + x, x).intersect(Interval(2, 4)), x) == \
+        Union(Interval(-sqrt(17)/2 - S.Half, -2),
+              Interval(1, Rational(-1, 2) + sqrt(17)/2), Interval(2, 4))
+    assert not_empty_in(FiniteSet(x/(x - 1)).intersect(S.Reals), x) == \
+        Complement(S.Reals, FiniteSet(1))
+    assert not_empty_in(FiniteSet(a/(a - 1)).intersect(S.Reals), a) == \
+        Complement(S.Reals, FiniteSet(1))
+    assert not_empty_in(FiniteSet((x**2 - 3*x + 2)/(x - 1)).intersect(S.Reals), x) == \
+        Complement(S.Reals, FiniteSet(1))
+    assert not_empty_in(FiniteSet(3, 4, x/(x - 1)).intersect(Interval(2, 3)), x) == \
+        Interval(-oo, oo)
+    assert not_empty_in(FiniteSet(4, x/(x - 1)).intersect(Interval(2, 3)), x) == \
+        Interval(S(3)/2, 2)
+    assert not_empty_in(FiniteSet(x/(x**2 - 1)).intersect(S.Reals), x) == \
+        Complement(S.Reals, FiniteSet(-1, 1))
+    assert not_empty_in(FiniteSet(x, x**2).intersect(Union(Interval(1, 3, True, True),
+                                                           Interval(4, 5))), x) == \
+        Union(Interval(-sqrt(5), -2), Interval(-sqrt(3), -1, True, True),
+              Interval(1, 3, True, True), Interval(4, 5))
+    assert not_empty_in(FiniteSet(1).intersect(Interval(3, 4)), x) == S.EmptySet
+    assert not_empty_in(FiniteSet(x**2/(x + 2)).intersect(Interval(1, oo)), x) == \
+        Union(Interval(-2, -1, True, False), Interval(2, oo))
+    raises(ValueError, lambda: not_empty_in(x))
+    raises(ValueError, lambda: not_empty_in(Interval(0, 1), x))
+    raises(NotImplementedError,
+           lambda: not_empty_in(FiniteSet(x).intersect(S.Reals), x, a))
+
+
+@_both_exp_pow
+def test_periodicity():
+    assert periodicity(sin(2*x), x) == pi
+    assert periodicity((-2)*tan(4*x), x) == pi/4
+    assert periodicity(sin(x)**2, x) == 2*pi
+    assert periodicity(3**tan(3*x), x) == pi/3
+    assert periodicity(tan(x)*cos(x), x) == 2*pi
+    assert periodicity(sin(x)**(tan(x)), x) == 2*pi
+    assert periodicity(tan(x)*sec(x), x) == 2*pi
+    assert periodicity(sin(2*x)*cos(2*x) - y, x) == pi/2
+    assert periodicity(tan(x) + cot(x), x) == pi
+    assert periodicity(sin(x) - cos(2*x), x) == 2*pi
+    assert periodicity(sin(x) - 1, x) == 2*pi
+    assert periodicity(sin(4*x) + sin(x)*cos(x), x) == pi
+    assert periodicity(exp(sin(x)), x) == 2*pi
+    assert periodicity(log(cot(2*x)) - sin(cos(2*x)), x) == pi
+    assert periodicity(sin(2*x)*exp(tan(x) - csc(2*x)), x) == pi
+    assert periodicity(cos(sec(x) - csc(2*x)), x) == 2*pi
+    assert periodicity(tan(sin(2*x)), x) == pi
+    assert periodicity(2*tan(x)**2, x) == pi
+    assert periodicity(sin(x%4), x) == 4
+    assert periodicity(sin(x)%4, x) == 2*pi
+    assert periodicity(tan((3*x-2)%4), x) == Rational(4, 3)
+    assert periodicity((sqrt(2)*(x+1)+x) % 3, x) == 3 / (sqrt(2)+1)
+    assert periodicity((x**2+1) % x, x) is None
+    assert periodicity(sin(re(x)), x) == 2*pi
+    assert periodicity(sin(x)**2 + cos(x)**2, x) is S.Zero
+    assert periodicity(tan(x), y) is S.Zero
+    assert periodicity(sin(x) + I*cos(x), x) == 2*pi
+    assert periodicity(x - sin(2*y), y) == pi
+
+    assert periodicity(exp(x), x) is None
+    assert periodicity(exp(I*x), x) == 2*pi
+    assert periodicity(exp(I*a), a) == 2*pi
+    assert periodicity(exp(a), a) is None
+    assert periodicity(exp(log(sin(a) + I*cos(2*a)), evaluate=False), a) == 2*pi
+    assert periodicity(exp(log(sin(2*a) + I*cos(a)), evaluate=False), a) == 2*pi
+    assert periodicity(exp(sin(a)), a) == 2*pi
+    assert periodicity(exp(2*I*a), a) == pi
+    assert periodicity(exp(a + I*sin(a)), a) is None
+    assert periodicity(exp(cos(a/2) + sin(a)), a) == 4*pi
+    assert periodicity(log(x), x) is None
+    assert periodicity(exp(x)**sin(x), x) is None
+    assert periodicity(sin(x)**y, y) is None
+
+    assert periodicity(Abs(sin(Abs(sin(x)))), x) == pi
+    assert all(periodicity(Abs(f(x)), x) == pi for f in (
+        cos, sin, sec, csc, tan, cot))
+    assert periodicity(Abs(sin(tan(x))), x) == pi
+    assert periodicity(Abs(sin(sin(x) + tan(x))), x) == 2*pi
+    assert periodicity(sin(x) > S.Half, x) == 2*pi
+
+    assert periodicity(x > 2, x) is None
+    assert periodicity(x**3 - x**2 + 1, x) is None
+    assert periodicity(Abs(x), x) is None
+    assert periodicity(Abs(x**2 - 1), x) is None
+
+    assert periodicity((x**2 + 4)%2, x) is None
+    assert periodicity((E**x)%3, x) is None
+
+    assert periodicity(sin(expint(1, x))/expint(1, x), x) is None
+    # returning `None` for any Piecewise
+    p = Piecewise((0, x < -1), (x**2, x <= 1), (log(x), True))
+    assert periodicity(p, x) is None
+
+    m = MatrixSymbol('m', 3, 3)
+    raises(NotImplementedError, lambda: periodicity(sin(m), m))
+    raises(NotImplementedError, lambda: periodicity(sin(m[0, 0]), m))
+    raises(NotImplementedError, lambda: periodicity(sin(m), m[0, 0]))
+    raises(NotImplementedError, lambda: periodicity(sin(m[0, 0]), m[0, 0]))
+
+
+def test_periodicity_check():
+    assert periodicity(tan(x), x, check=True) == pi
+    assert periodicity(sin(x) + cos(x), x, check=True) == 2*pi
+    assert periodicity(sec(x), x) == 2*pi
+    assert periodicity(sin(x*y), x) == 2*pi/abs(y)
+    assert periodicity(Abs(sec(sec(x))), x) == pi
+
+
+def test_lcim():
+    assert lcim([S.Half, S(2), S(3)]) == 6
+    assert lcim([pi/2, pi/4, pi]) == pi
+    assert lcim([2*pi, pi/2]) == 2*pi
+    assert lcim([S.One, 2*pi]) is None
+    assert lcim([S(2) + 2*E, E/3 + Rational(1, 3), S.One + E]) == S(2) + 2*E
+
+
+def test_is_convex():
+    assert is_convex(1/x, x, domain=Interval.open(0, oo)) == True
+    assert is_convex(1/x, x, domain=Interval(-oo, 0)) == False
+    assert is_convex(x**2, x, domain=Interval(0, oo)) == True
+    assert is_convex(1/x**3, x, domain=Interval.Lopen(0, oo)) == True
+    assert is_convex(-1/x**3, x, domain=Interval.Ropen(-oo, 0)) == True
+    assert is_convex(log(x) ,x) == False
+    assert is_convex(x**2+y**2, x, y) == True
+    assert is_convex(cos(x) + cos(y), x) == False
+    assert is_convex(8*x**2 - 2*y**2, x, y) == False
+
+
+def test_stationary_points():
+    assert stationary_points(sin(x), x, Interval(-pi/2, pi/2)
+        ) == {-pi/2, pi/2}
+    assert  stationary_points(sin(x), x, Interval.Ropen(0, pi/4)
+        ) is S.EmptySet
+    assert stationary_points(tan(x), x,
+        ) is S.EmptySet
+    assert stationary_points(sin(x)*cos(x), x, Interval(0, pi)
+        ) == {pi/4, pi*Rational(3, 4)}
+    assert stationary_points(sec(x), x, Interval(0, pi)
+        ) == {0, pi}
+    assert stationary_points((x+3)*(x-2), x
+        ) == FiniteSet(Rational(-1, 2))
+    assert stationary_points((x + 3)/(x - 2), x, Interval(-5, 5)
+        ) is S.EmptySet
+    assert stationary_points((x**2+3)/(x-2), x
+        ) == {2 - sqrt(7), 2 + sqrt(7)}
+    assert stationary_points((x**2+3)/(x-2), x, Interval(0, 5)
+        ) == {2 + sqrt(7)}
+    assert stationary_points(x**4 + x**3 - 5*x**2, x, S.Reals
+        ) == FiniteSet(-2, 0, Rational(5, 4))
+    assert stationary_points(exp(x), x
+        ) is S.EmptySet
+    assert stationary_points(log(x) - x, x, S.Reals
+        ) == {1}
+    assert stationary_points(cos(x), x, Union(Interval(0, 5), Interval(-6, -3))
+        ) == {0, -pi, pi}
+    assert stationary_points(y, x, S.Reals
+        ) == S.Reals
+    assert stationary_points(y, x, S.EmptySet) == S.EmptySet
+
+
+def test_maximum():
+    assert maximum(sin(x), x) is S.One
+    assert maximum(sin(x), x, Interval(0, 1)) == sin(1)
+    assert maximum(tan(x), x) is oo
+    assert maximum(tan(x), x, Interval(-pi/4, pi/4)) is S.One
+    assert maximum(sin(x)*cos(x), x, S.Reals) == S.Half
+    assert simplify(maximum(sin(x)*cos(x), x, Interval(pi*Rational(3, 8), pi*Rational(5, 8)))
+        ) == sqrt(2)/4
+    assert maximum((x+3)*(x-2), x) is oo
+    assert maximum((x+3)*(x-2), x, Interval(-5, 0)) == S(14)
+    assert maximum((x+3)/(x-2), x, Interval(-5, 0)) == Rational(2, 7)
+    assert simplify(maximum(-x**4-x**3+x**2+10, x)
+        ) == 41*sqrt(41)/512 + Rational(5419, 512)
+    assert maximum(exp(x), x, Interval(-oo, 2)) == exp(2)
+    assert maximum(log(x) - x, x, S.Reals) is S.NegativeOne
+    assert maximum(cos(x), x, Union(Interval(0, 5), Interval(-6, -3))
+        ) is S.One
+    assert maximum(cos(x)-sin(x), x, S.Reals) == sqrt(2)
+    assert maximum(y, x, S.Reals) == y
+    assert maximum(abs(a**3 + a), a, Interval(0, 2)) == 10
+    assert maximum(abs(60*a**3 + 24*a), a, Interval(0, 2)) == 528
+    assert maximum(abs(12*a*(5*a**2 + 2)), a, Interval(0, 2)) == 528
+    assert maximum(x/sqrt(x**2+1), x, S.Reals) == 1
+
+    raises(ValueError, lambda : maximum(sin(x), x, S.EmptySet))
+    raises(ValueError, lambda : maximum(log(cos(x)), x, S.EmptySet))
+    raises(ValueError, lambda : maximum(1/(x**2 + y**2 + 1), x, S.EmptySet))
+    raises(ValueError, lambda : maximum(sin(x), sin(x)))
+    raises(ValueError, lambda : maximum(sin(x), x*y, S.EmptySet))
+    raises(ValueError, lambda : maximum(sin(x), S.One))
+
+
+def test_minimum():
+    assert minimum(sin(x), x) is S.NegativeOne
+    assert minimum(sin(x), x, Interval(1, 4)) == sin(4)
+    assert minimum(tan(x), x) is -oo
+    assert minimum(tan(x), x, Interval(-pi/4, pi/4)) is S.NegativeOne
+    assert minimum(sin(x)*cos(x), x, S.Reals) == Rational(-1, 2)
+    assert simplify(minimum(sin(x)*cos(x), x, Interval(pi*Rational(3, 8), pi*Rational(5, 8)))
+        ) == -sqrt(2)/4
+    assert minimum((x+3)*(x-2), x) == Rational(-25, 4)
+    assert minimum((x+3)/(x-2), x, Interval(-5, 0)) == Rational(-3, 2)
+    assert minimum(x**4-x**3+x**2+10, x) == S(10)
+    assert minimum(exp(x), x, Interval(-2, oo)) == exp(-2)
+    assert minimum(log(x) - x, x, S.Reals) is -oo
+    assert minimum(cos(x), x, Union(Interval(0, 5), Interval(-6, -3))
+        ) is S.NegativeOne
+    assert minimum(cos(x)-sin(x), x, S.Reals) == -sqrt(2)
+    assert minimum(y, x, S.Reals) == y
+    assert minimum(x/sqrt(x**2+1), x, S.Reals) == -1
+
+    raises(ValueError, lambda : minimum(sin(x), x, S.EmptySet))
+    raises(ValueError, lambda : minimum(log(cos(x)), x, S.EmptySet))
+    raises(ValueError, lambda : minimum(1/(x**2 + y**2 + 1), x, S.EmptySet))
+    raises(ValueError, lambda : minimum(sin(x), sin(x)))
+    raises(ValueError, lambda : minimum(sin(x), x*y, S.EmptySet))
+    raises(ValueError, lambda : minimum(sin(x), S.One))
+
+
+def test_issue_19869():
+    assert (maximum(sqrt(3)*(x - 1)/(3*sqrt(x**2 + 1)), x)
+        ) == sqrt(3)/3
+
+
+def test_issue_16469():
+    f = abs(a)
+    assert function_range(f, a, S.Reals) == Interval(0, oo, False, True)
+
+
+@_both_exp_pow
+def test_issue_18747():
+    assert periodicity(exp(pi*I*(x/4 + S.Half/2)), x) == 8
+
+
+def test_issue_25942():
+    assert (acos(x) > pi/3).as_set() == Interval.Ropen(-1, S(1)/2)

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

@@ -0,0 +1,905 @@
+from .accumulationbounds import AccumBounds, AccumulationBounds # noqa: F401
+from .singularities import singularities
+from sympy.core import Pow, S
+from sympy.core.function import diff, expand_mul, Function
+from sympy.core.kind import NumberKind
+from sympy.core.mod import Mod
+from sympy.core.numbers import equal_valued
+from sympy.core.relational import Relational
+from sympy.core.symbol import Symbol, Dummy
+from sympy.core.sympify import _sympify
+from sympy.functions.elementary.complexes import Abs, im, re
+from sympy.functions.elementary.exponential import exp, log
+from sympy.functions.elementary.integers import frac
+from sympy.functions.elementary.piecewise import Piecewise
+from sympy.functions.elementary.trigonometric import (
+    TrigonometricFunction, sin, cos, tan, cot, csc, sec,
+    asin, acos, acot, atan, asec, acsc)
+from sympy.functions.elementary.hyperbolic import (sinh, cosh, tanh, coth,
+    sech, csch, asinh, acosh, atanh, acoth, asech, acsch)
+from sympy.polys.polytools import degree, lcm_list
+from sympy.sets.sets import (Interval, Intersection, FiniteSet, Union,
+                             Complement)
+from sympy.sets.fancysets import ImageSet
+from sympy.sets.conditionset import ConditionSet
+from sympy.utilities import filldedent
+from sympy.utilities.iterables import iterable
+from sympy.matrices.dense import hessian
+
+
+def continuous_domain(f, symbol, domain):
+    """
+    Returns the domain on which the function expression f is continuous.
+
+    This function is limited by the ability to determine the various
+    singularities and discontinuities of the given function.
+    The result is either given as a union of intervals or constructed using
+    other set operations.
+
+    Parameters
+    ==========
+
+    f : :py:class:`~.Expr`
+        The concerned function.
+    symbol : :py:class:`~.Symbol`
+        The variable for which the intervals are to be determined.
+    domain : :py:class:`~.Interval`
+        The domain over which the continuity of the symbol has to be checked.
+
+    Examples
+    ========
+
+    >>> from sympy import Interval, Symbol, S, tan, log, pi, sqrt
+    >>> from sympy.calculus.util import continuous_domain
+    >>> x = Symbol('x')
+    >>> continuous_domain(1/x, x, S.Reals)
+    Union(Interval.open(-oo, 0), Interval.open(0, oo))
+    >>> continuous_domain(tan(x), x, Interval(0, pi))
+    Union(Interval.Ropen(0, pi/2), Interval.Lopen(pi/2, pi))
+    >>> continuous_domain(sqrt(x - 2), x, Interval(-5, 5))
+    Interval(2, 5)
+    >>> continuous_domain(log(2*x - 1), x, S.Reals)
+    Interval.open(1/2, oo)
+
+    Returns
+    =======
+
+    :py:class:`~.Interval`
+        Union of all intervals where the function is continuous.
+
+    Raises
+    ======
+
+    NotImplementedError
+        If the method to determine continuity of such a function
+        has not yet been developed.
+
+    """
+    from sympy.solvers.inequalities import solve_univariate_inequality
+
+    if not domain.is_subset(S.Reals):
+        raise NotImplementedError(filldedent('''
+            Domain must be a subset of S.Reals.
+            '''))
+    implemented = [Pow, exp, log, Abs, frac,
+                   sin, cos, tan, cot, sec, csc,
+                   asin, acos, atan, acot, asec, acsc,
+                   sinh, cosh, tanh, coth, sech, csch,
+                   asinh, acosh, atanh, acoth, asech, acsch]
+    used = [fct.func for fct in f.atoms(Function) if fct.has(symbol)]
+    if any(func not in implemented for func in used):
+        raise NotImplementedError(filldedent('''
+            Unable to determine the domain of the given function.
+            '''))
+
+    x = Symbol('x')
+    constraints = {
+        log: (x > 0,),
+        asin: (x >= -1, x <= 1),
+        acos: (x >= -1, x <= 1),
+        acosh: (x >= 1,),
+        atanh: (x > -1, x < 1),
+        asech: (x > 0, x <= 1)
+    }
+    constraints_union = {
+        asec: (x <= -1, x >= 1),
+        acsc: (x <= -1, x >= 1),
+        acoth: (x < -1, x > 1)
+    }
+
+    cont_domain = domain
+    for atom in f.atoms(Pow):
+        den = atom.exp.as_numer_denom()[1]
+        if atom.exp.is_rational and den.is_odd:
+            pass    # 0**negative handled by singularities()
+        else:
+            constraint = solve_univariate_inequality(atom.base >= 0,
+                                                        symbol).as_set()
+            cont_domain = Intersection(constraint, cont_domain)
+
+    for atom in f.atoms(Function):
+        if atom.func in constraints:
+            for c in constraints[atom.func]:
+                constraint_relational = c.subs(x, atom.args[0])
+                constraint_set = solve_univariate_inequality(
+                    constraint_relational, symbol).as_set()
+                cont_domain = Intersection(constraint_set, cont_domain)
+        elif atom.func in constraints_union:
+            constraint_set = S.EmptySet
+            for c in constraints_union[atom.func]:
+                constraint_relational = c.subs(x, atom.args[0])
+                constraint_set += solve_univariate_inequality(
+                    constraint_relational, symbol).as_set()
+            cont_domain = Intersection(constraint_set, cont_domain)
+        # XXX: the discontinuities below could be factored out in
+        # a new "discontinuities()".
+        elif atom.func == acot:
+            from sympy.solvers.solveset import solveset_real
+            # Sympy's acot() has a step discontinuity at 0. Since it's
+            # neither an essential singularity nor a pole, singularities()
+            # will not report it. But it's still relevant for determining
+            # the continuity of the function f.
+            cont_domain -= solveset_real(atom.args[0], symbol)
+            # Note that the above may introduce spurious discontinuities, e.g.
+            # for abs(acot(x)) at 0.
+        elif atom.func == frac:
+            from sympy.solvers.solveset import solveset_real
+            r = function_range(atom.args[0], symbol, domain)
+            r = Intersection(r, S.Integers)
+            if r.is_finite_set:
+                discont = S.EmptySet
+                for n in r:
+                    discont += solveset_real(atom.args[0]-n, symbol)
+            else:
+                discont = ConditionSet(
+                    symbol, S.Integers.contains(atom.args[0]), cont_domain)
+            cont_domain -= discont
+
+    return cont_domain - singularities(f, symbol, domain)
+
+
+def function_range(f, symbol, domain):
+    """
+    Finds the range of a function in a given domain.
+    This method is limited by the ability to determine the singularities and
+    determine limits.
+
+    Parameters
+    ==========
+
+    f : :py:class:`~.Expr`
+        The concerned function.
+    symbol : :py:class:`~.Symbol`
+        The variable for which the range of function is to be determined.
+    domain : :py:class:`~.Interval`
+        The domain under which the range of the function has to be found.
+
+    Examples
+    ========
+
+    >>> from sympy import Interval, Symbol, S, exp, log, pi, sqrt, sin, tan
+    >>> from sympy.calculus.util import function_range
+    >>> x = Symbol('x')
+    >>> function_range(sin(x), x, Interval(0, 2*pi))
+    Interval(-1, 1)
+    >>> function_range(tan(x), x, Interval(-pi/2, pi/2))
+    Interval(-oo, oo)
+    >>> function_range(1/x, x, S.Reals)
+    Union(Interval.open(-oo, 0), Interval.open(0, oo))
+    >>> function_range(exp(x), x, S.Reals)
+    Interval.open(0, oo)
+    >>> function_range(log(x), x, S.Reals)
+    Interval(-oo, oo)
+    >>> function_range(sqrt(x), x, Interval(-5, 9))
+    Interval(0, 3)
+
+    Returns
+    =======
+
+    :py:class:`~.Interval`
+        Union of all ranges for all intervals under domain where function is
+        continuous.
+
+    Raises
+    ======
+
+    NotImplementedError
+        If any of the intervals, in the given domain, for which function
+        is continuous are not finite or real,
+        OR if the critical points of the function on the domain cannot be found.
+    """
+
+    if domain is S.EmptySet:
+        return S.EmptySet
+
+    period = periodicity(f, symbol)
+    if period == S.Zero:
+        # the expression is constant wrt symbol
+        return FiniteSet(f.expand())
+
+    from sympy.series.limits import limit
+    from sympy.solvers.solveset import solveset
+
+    if period is not None:
+        if isinstance(domain, Interval):
+            if (domain.inf - domain.sup).is_infinite:
+                domain = Interval(0, period)
+        elif isinstance(domain, Union):
+            for sub_dom in domain.args:
+                if isinstance(sub_dom, Interval) and \
+                ((sub_dom.inf - sub_dom.sup).is_infinite):
+                    domain = Interval(0, period)
+
+    intervals = continuous_domain(f, symbol, domain)
+    range_int = S.EmptySet
+    if isinstance(intervals,(Interval, FiniteSet)):
+        interval_iter = (intervals,)
+
+    elif isinstance(intervals, Union):
+        interval_iter = intervals.args
+
+    else:
+            raise NotImplementedError(filldedent('''
+                Unable to find range for the given domain.
+                '''))
+
+    for interval in interval_iter:
+        if isinstance(interval, FiniteSet):
+            for singleton in interval:
+                if singleton in domain:
+                    range_int += FiniteSet(f.subs(symbol, singleton))
+        elif isinstance(interval, Interval):
+            vals = S.EmptySet
+            critical_points = S.EmptySet
+            critical_values = S.EmptySet
+            bounds = ((interval.left_open, interval.inf, '+'),
+                   (interval.right_open, interval.sup, '-'))
+
+            for is_open, limit_point, direction in bounds:
+                if is_open:
+                    critical_values += FiniteSet(limit(f, symbol, limit_point, direction))
+                    vals += critical_values
+
+                else:
+                    vals += FiniteSet(f.subs(symbol, limit_point))
+
+            solution = solveset(f.diff(symbol), symbol, interval)
+
+            if not iterable(solution):
+                raise NotImplementedError(
+                        'Unable to find critical points for {}'.format(f))
+            if isinstance(solution, ImageSet):
+                raise NotImplementedError(
+                        'Infinite number of critical points for {}'.format(f))
+
+            critical_points += solution
+
+            for critical_point in critical_points:
+                vals += FiniteSet(f.subs(symbol, critical_point))
+
+            left_open, right_open = False, False
+
+            if critical_values is not S.EmptySet:
+                if critical_values.inf == vals.inf:
+                    left_open = True
+
+                if critical_values.sup == vals.sup:
+                    right_open = True
+
+            range_int += Interval(vals.inf, vals.sup, left_open, right_open)
+        else:
+            raise NotImplementedError(filldedent('''
+                Unable to find range for the given domain.
+                '''))
+
+    return range_int
+
+
+def not_empty_in(finset_intersection, *syms):
+    """
+    Finds the domain of the functions in ``finset_intersection`` in which the
+    ``finite_set`` is not-empty.
+
+    Parameters
+    ==========
+
+    finset_intersection : Intersection of FiniteSet
+        The unevaluated intersection of FiniteSet containing
+        real-valued functions with Union of Sets
+    syms : Tuple of symbols
+        Symbol for which domain is to be found
+
+    Raises
+    ======
+
+    NotImplementedError
+        The algorithms to find the non-emptiness of the given FiniteSet are
+        not yet implemented.
+    ValueError
+        The input is not valid.
+    RuntimeError
+        It is a bug, please report it to the github issue tracker
+        (https://github.com/sympy/sympy/issues).
+
+    Examples
+    ========
+
+    >>> from sympy import FiniteSet, Interval, not_empty_in, oo
+    >>> from sympy.abc import x
+    >>> not_empty_in(FiniteSet(x/2).intersect(Interval(0, 1)), x)
+    Interval(0, 2)
+    >>> not_empty_in(FiniteSet(x, x**2).intersect(Interval(1, 2)), x)
+    Union(Interval(1, 2), Interval(-sqrt(2), -1))
+    >>> not_empty_in(FiniteSet(x**2/(x + 2)).intersect(Interval(1, oo)), x)
+    Union(Interval.Lopen(-2, -1), Interval(2, oo))
+    """
+
+    # TODO: handle piecewise defined functions
+    # TODO: handle transcendental functions
+    # TODO: handle multivariate functions
+    if len(syms) == 0:
+        raise ValueError("One or more symbols must be given in syms.")
+
+    if finset_intersection is S.EmptySet:
+        return S.EmptySet
+
+    if isinstance(finset_intersection, Union):
+        elm_in_sets = finset_intersection.args[0]
+        return Union(not_empty_in(finset_intersection.args[1], *syms),
+                     elm_in_sets)
+
+    if isinstance(finset_intersection, FiniteSet):
+        finite_set = finset_intersection
+        _sets = S.Reals
+    else:
+        finite_set = finset_intersection.args[1]
+        _sets = finset_intersection.args[0]
+
+    if not isinstance(finite_set, FiniteSet):
+        raise ValueError('A FiniteSet must be given, not %s: %s' %
+                         (type(finite_set), finite_set))
+
+    if len(syms) == 1:
+        symb = syms[0]
+    else:
+        raise NotImplementedError('more than one variables %s not handled' %
+                                  (syms,))
+
+    def elm_domain(expr, intrvl):
+        """ Finds the domain of an expression in any given interval """
+        from sympy.solvers.solveset import solveset
+
+        _start = intrvl.start
+        _end = intrvl.end
+        _singularities = solveset(expr.as_numer_denom()[1], symb,
+                                  domain=S.Reals)
+
+        if intrvl.right_open:
+            if _end is S.Infinity:
+                _domain1 = S.Reals
+            else:
+                _domain1 = solveset(expr < _end, symb, domain=S.Reals)
+        else:
+            _domain1 = solveset(expr <= _end, symb, domain=S.Reals)
+
+        if intrvl.left_open:
+            if _start is S.NegativeInfinity:
+                _domain2 = S.Reals
+            else:
+                _domain2 = solveset(expr > _start, symb, domain=S.Reals)
+        else:
+            _domain2 = solveset(expr >= _start, symb, domain=S.Reals)
+
+        # domain in the interval
+        expr_with_sing = Intersection(_domain1, _domain2)
+        expr_domain = Complement(expr_with_sing, _singularities)
+        return expr_domain
+
+    if isinstance(_sets, Interval):
+        return Union(*[elm_domain(element, _sets) for element in finite_set])
+
+    if isinstance(_sets, Union):
+        _domain = S.EmptySet
+        for intrvl in _sets.args:
+            _domain_element = Union(*[elm_domain(element, intrvl)
+                                      for element in finite_set])
+            _domain = Union(_domain, _domain_element)
+        return _domain
+
+
+def periodicity(f, symbol, check=False):
+    """
+    Tests the given function for periodicity in the given symbol.
+
+    Parameters
+    ==========
+
+    f : :py:class:`~.Expr`
+        The concerned function.
+    symbol : :py:class:`~.Symbol`
+        The variable for which the period is to be determined.
+    check : bool, optional
+        The flag to verify whether the value being returned is a period or not.
+
+    Returns
+    =======
+
+    period
+        The period of the function is returned.
+        ``None`` is returned when the function is aperiodic or has a complex period.
+        The value of $0$ is returned as the period of a constant function.
+
+    Raises
+    ======
+
+    NotImplementedError
+        The value of the period computed cannot be verified.
+
+
+    Notes
+    =====
+
+    Currently, we do not support functions with a complex period.
+    The period of functions having complex periodic values such
+    as ``exp``, ``sinh`` is evaluated to ``None``.
+
+    The value returned might not be the "fundamental" period of the given
+    function i.e. it may not be the smallest periodic value of the function.
+
+    The verification of the period through the ``check`` flag is not reliable
+    due to internal simplification of the given expression. Hence, it is set
+    to ``False`` by default.
+
+    Examples
+    ========
+    >>> from sympy import periodicity, Symbol, sin, cos, tan, exp
+    >>> x = Symbol('x')
+    >>> f = sin(x) + sin(2*x) + sin(3*x)
+    >>> periodicity(f, x)
+    2*pi
+    >>> periodicity(sin(x)*cos(x), x)
+    pi
+    >>> periodicity(exp(tan(2*x) - 1), x)
+    pi/2
+    >>> periodicity(sin(4*x)**cos(2*x), x)
+    pi
+    >>> periodicity(exp(x), x)
+    """
+    if symbol.kind is not NumberKind:
+        raise NotImplementedError("Cannot use symbol of kind %s" % symbol.kind)
+    temp = Dummy('x', real=True)
+    f = f.subs(symbol, temp)
+    symbol = temp
+
+    def _check(orig_f, period):
+        '''Return the checked period or raise an error.'''
+        new_f = orig_f.subs(symbol, symbol + period)
+        if new_f.equals(orig_f):
+            return period
+        else:
+            raise NotImplementedError(filldedent('''
+                The period of the given function cannot be verified.
+                When `%s` was replaced with `%s + %s` in `%s`, the result
+                was `%s` which was not recognized as being the same as
+                the original function.
+                So either the period was wrong or the two forms were
+                not recognized as being equal.
+                Set check=False to obtain the value.''' %
+                (symbol, symbol, period, orig_f, new_f)))
+
+    orig_f = f
+    period = None
+
+    if isinstance(f, Relational):
+        f = f.lhs - f.rhs
+
+    f = f.simplify()
+
+    if symbol not in f.free_symbols:
+        return S.Zero
+
+    if isinstance(f, TrigonometricFunction):
+        try:
+            period = f.period(symbol)
+        except NotImplementedError:
+            pass
+
+    if isinstance(f, Abs):
+        arg = f.args[0]
+        if isinstance(arg, (sec, csc, cos)):
+            # all but tan and cot might have a
+            # a period that is half as large
+            # so recast as sin
+            arg = sin(arg.args[0])
+        period = periodicity(arg, symbol)
+        if period is not None and isinstance(arg, sin):
+            # the argument of Abs was a trigonometric other than
+            # cot or tan; test to see if the half-period
+            # is valid. Abs(arg) has behaviour equivalent to
+            # orig_f, so use that for test:
+            orig_f = Abs(arg)
+            try:
+                return _check(orig_f, period/2)
+            except NotImplementedError as err:
+                if check:
+                    raise NotImplementedError(err)
+            # else let new orig_f and period be
+            # checked below
+
+    if isinstance(f, exp) or (f.is_Pow and f.base == S.Exp1):
+        f = Pow(S.Exp1, expand_mul(f.exp))
+        if im(f) != 0:
+            period_real = periodicity(re(f), symbol)
+            period_imag = periodicity(im(f), symbol)
+            if period_real is not None and period_imag is not None:
+                period = lcim([period_real, period_imag])
+
+    if f.is_Pow and f.base != S.Exp1:
+        base, expo = f.args
+        base_has_sym = base.has(symbol)
+        expo_has_sym = expo.has(symbol)
+
+        if base_has_sym and not expo_has_sym:
+            period = periodicity(base, symbol)
+
+        elif expo_has_sym and not base_has_sym:
+            period = periodicity(expo, symbol)
+
+        else:
+            period = _periodicity(f.args, symbol)
+
+    elif f.is_Mul:
+        coeff, g = f.as_independent(symbol, as_Add=False)
+        if isinstance(g, TrigonometricFunction) or not equal_valued(coeff, 1):
+            period = periodicity(g, symbol)
+        else:
+            period = _periodicity(g.args, symbol)
+
+    elif f.is_Add:
+        k, g = f.as_independent(symbol)
+        if k is not S.Zero:
+            return periodicity(g, symbol)
+
+        period = _periodicity(g.args, symbol)
+
+    elif isinstance(f, Mod):
+        a, n = f.args
+
+        if a == symbol:
+            period = n
+        elif isinstance(a, TrigonometricFunction):
+            period = periodicity(a, symbol)
+        #check if 'f' is linear in 'symbol'
+        elif (a.is_polynomial(symbol) and degree(a, symbol) == 1 and
+            symbol not in n.free_symbols):
+                period = Abs(n / a.diff(symbol))
+
+    elif isinstance(f, Piecewise):
+        pass  # not handling Piecewise yet as the return type is not favorable
+
+    elif period is None:
+        from sympy.solvers.decompogen import compogen, decompogen
+        g_s = decompogen(f, symbol)
+        num_of_gs = len(g_s)
+        if num_of_gs > 1:
+            for index, g in enumerate(reversed(g_s)):
+                start_index = num_of_gs - 1 - index
+                g = compogen(g_s[start_index:], symbol)
+                if g not in (orig_f, f): # Fix for issue 12620
+                    period = periodicity(g, symbol)
+                    if period is not None:
+                        break
+
+    if period is not None:
+        if check:
+            return _check(orig_f, period)
+        return period
+
+    return None
+
+
+def _periodicity(args, symbol):
+    """
+    Helper for `periodicity` to find the period of a list of simpler
+    functions.
+    It uses the `lcim` method to find the least common period of
+    all the functions.
+
+    Parameters
+    ==========
+
+    args : Tuple of :py:class:`~.Symbol`
+        All the symbols present in a function.
+
+    symbol : :py:class:`~.Symbol`
+        The symbol over which the function is to be evaluated.
+
+    Returns
+    =======
+
+    period
+        The least common period of the function for all the symbols
+        of the function.
+        ``None`` if for at least one of the symbols the function is aperiodic.
+
+    """
+    periods = []
+    for f in args:
+        period = periodicity(f, symbol)
+        if period is None:
+            return None
+
+        if period is not S.Zero:
+            periods.append(period)
+
+    if len(periods) > 1:
+        return lcim(periods)
+
+    if periods:
+        return periods[0]
+
+
+def lcim(numbers):
+    """Returns the least common integral multiple of a list of numbers.
+
+    The numbers can be rational or irrational or a mixture of both.
+    `None` is returned for incommensurable numbers.
+
+    Parameters
+    ==========
+
+    numbers : list
+        Numbers (rational and/or irrational) for which lcim is to be found.
+
+    Returns
+    =======
+
+    number
+        lcim if it exists, otherwise ``None`` for incommensurable numbers.
+
+    Examples
+    ========
+
+    >>> from sympy.calculus.util import lcim
+    >>> from sympy import S, pi
+    >>> lcim([S(1)/2, S(3)/4, S(5)/6])
+    15/2
+    >>> lcim([2*pi, 3*pi, pi, pi/2])
+    6*pi
+    >>> lcim([S(1), 2*pi])
+    """
+    result = None
+    if all(num.is_irrational for num in numbers):
+        factorized_nums = [num.factor() for num in numbers]
+        factors_num = [num.as_coeff_Mul() for num in factorized_nums]
+        term = factors_num[0][1]
+        if all(factor == term for coeff, factor in factors_num):
+            common_term = term
+            coeffs = [coeff for coeff, factor in factors_num]
+            result = lcm_list(coeffs) * common_term
+
+    elif all(num.is_rational for num in numbers):
+        result = lcm_list(numbers)
+
+    else:
+        pass
+
+    return result
+
+def is_convex(f, *syms, domain=S.Reals):
+    r"""Determines the  convexity of the function passed in the argument.
+
+    Parameters
+    ==========
+
+    f : :py:class:`~.Expr`
+        The concerned function.
+    syms : Tuple of :py:class:`~.Symbol`
+        The variables with respect to which the convexity is to be determined.
+    domain : :py:class:`~.Interval`, optional
+        The domain over which the convexity of the function has to be checked.
+        If unspecified, S.Reals will be the default domain.
+
+    Returns
+    =======
+
+    bool
+        The method returns ``True`` if the function is convex otherwise it
+        returns ``False``.
+
+    Raises
+    ======
+
+    NotImplementedError
+        The check for the convexity of multivariate functions is not implemented yet.
+
+    Notes
+    =====
+
+    To determine concavity of a function pass `-f` as the concerned function.
+    To determine logarithmic convexity of a function pass `\log(f)` as
+    concerned function.
+    To determine logarithmic concavity of a function pass `-\log(f)` as
+    concerned function.
+
+    Currently, convexity check of multivariate functions is not handled.
+
+    Examples
+    ========
+
+    >>> from sympy import is_convex, symbols, exp, oo, Interval
+    >>> x = symbols('x')
+    >>> is_convex(exp(x), x)
+    True
+    >>> is_convex(x**3, x, domain = Interval(-1, oo))
+    False
+    >>> is_convex(1/x**2, x, domain=Interval.open(0, oo))
+    True
+
+    References
+    ==========
+
+    .. [1] https://en.wikipedia.org/wiki/Convex_function
+    .. [2] http://www.ifp.illinois.edu/~angelia/L3_convfunc.pdf
+    .. [3] https://en.wikipedia.org/wiki/Logarithmically_convex_function
+    .. [4] https://en.wikipedia.org/wiki/Logarithmically_concave_function
+    .. [5] https://en.wikipedia.org/wiki/Concave_function
+
+    """
+    if len(syms) > 1 :
+        return hessian(f, syms).is_positive_semidefinite
+    from sympy.solvers.inequalities import solve_univariate_inequality
+    f = _sympify(f)
+    var = syms[0]
+    if any(s in domain for s in singularities(f, var)):
+        return False
+    condition = f.diff(var, 2) < 0
+    if solve_univariate_inequality(condition, var, False, domain):
+        return False
+    return True
+
+
+def stationary_points(f, symbol, domain=S.Reals):
+    """
+    Returns the stationary points of a function (where derivative of the
+    function is 0) in the given domain.
+
+    Parameters
+    ==========
+
+    f : :py:class:`~.Expr`
+        The concerned function.
+    symbol : :py:class:`~.Symbol`
+        The variable for which the stationary points are to be determined.
+    domain : :py:class:`~.Interval`
+        The domain over which the stationary points have to be checked.
+        If unspecified, ``S.Reals`` will be the default domain.
+
+    Returns
+    =======
+
+    Set
+        A set of stationary points for the function. If there are no
+        stationary point, an :py:class:`~.EmptySet` is returned.
+
+    Examples
+    ========
+
+    >>> from sympy import Interval, Symbol, S, sin, pi, pprint, stationary_points
+    >>> x = Symbol('x')
+
+    >>> stationary_points(1/x, x, S.Reals)
+    EmptySet
+
+    >>> pprint(stationary_points(sin(x), x), use_unicode=False)
+              pi                              3*pi
+    {2*n*pi + -- | n in Integers} U {2*n*pi + ---- | n in Integers}
+              2                                2
+
+    >>> stationary_points(sin(x),x, Interval(0, 4*pi))
+    {pi/2, 3*pi/2, 5*pi/2, 7*pi/2}
+
+    """
+    from sympy.solvers.solveset import solveset
+
+    if domain is S.EmptySet:
+        return S.EmptySet
+
+    domain = continuous_domain(f, symbol, domain)
+    set = solveset(diff(f, symbol), symbol, domain)
+
+    return set
+
+
+def maximum(f, symbol, domain=S.Reals):
+    """
+    Returns the maximum value of a function in the given domain.
+
+    Parameters
+    ==========
+
+    f : :py:class:`~.Expr`
+        The concerned function.
+    symbol : :py:class:`~.Symbol`
+        The variable for maximum value needs to be determined.
+    domain : :py:class:`~.Interval`
+        The domain over which the maximum have to be checked.
+        If unspecified, then the global maximum is returned.
+
+    Returns
+    =======
+
+    number
+        Maximum value of the function in given domain.
+
+    Examples
+    ========
+
+    >>> from sympy import Interval, Symbol, S, sin, cos, pi, maximum
+    >>> x = Symbol('x')
+
+    >>> f = -x**2 + 2*x + 5
+    >>> maximum(f, x, S.Reals)
+    6
+
+    >>> maximum(sin(x), x, Interval(-pi, pi/4))
+    sqrt(2)/2
+
+    >>> maximum(sin(x)*cos(x), x)
+    1/2
+
+    """
+    if isinstance(symbol, Symbol):
+        if domain is S.EmptySet:
+            raise ValueError("Maximum value not defined for empty domain.")
+
+        return function_range(f, symbol, domain).sup
+    else:
+        raise ValueError("%s is not a valid symbol." % symbol)
+
+
+def minimum(f, symbol, domain=S.Reals):
+    """
+    Returns the minimum value of a function in the given domain.
+
+    Parameters
+    ==========
+
+    f : :py:class:`~.Expr`
+        The concerned function.
+    symbol : :py:class:`~.Symbol`
+        The variable for minimum value needs to be determined.
+    domain : :py:class:`~.Interval`
+        The domain over which the minimum have to be checked.
+        If unspecified, then the global minimum is returned.
+
+    Returns
+    =======
+
+    number
+        Minimum value of the function in the given domain.
+
+    Examples
+    ========
+
+    >>> from sympy import Interval, Symbol, S, sin, cos, minimum
+    >>> x = Symbol('x')
+
+    >>> f = x**2 + 2*x + 5
+    >>> minimum(f, x, S.Reals)
+    4
+
+    >>> minimum(sin(x), x, Interval(2, 3))
+    sin(3)
+
+    >>> minimum(sin(x)*cos(x), x)
+    -1/2
+
+    """
+    if isinstance(symbol, Symbol):
+        if domain is S.EmptySet:
+            raise ValueError("Minimum value not defined for empty domain.")
+
+        return function_range(f, symbol, domain).inf
+    else:
+        raise ValueError("%s is not a valid symbol." % symbol)

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

@@ -0,0 +1,8 @@
+from .products import product, Product
+from .summations import summation, Sum
+
+__all__ = [
+    'product', 'Product',
+
+    'summation', 'Sum',
+]

lib/python3.12/site-packages/sympy/concrete/delta.py

@@ -0,0 +1,330 @@
+"""
+This module implements sums and products containing the Kronecker Delta function.
+
+References
+==========
+
+.. [1] https://mathworld.wolfram.com/KroneckerDelta.html
+
+"""
+from .products import product
+from .summations import Sum, summation
+from sympy.core import Add, Mul, S, Dummy
+from sympy.core.cache import cacheit
+from sympy.core.sorting import default_sort_key
+from sympy.functions import KroneckerDelta, Piecewise, piecewise_fold
+from sympy.polys.polytools import factor
+from sympy.sets.sets import Interval
+from sympy.solvers.solvers import solve
+
+
+@cacheit
+def _expand_delta(expr, index):
+    """
+    Expand the first Add containing a simple KroneckerDelta.
+    """
+    if not expr.is_Mul:
+        return expr
+    delta = None
+    func = Add
+    terms = [S.One]
+    for h in expr.args:
+        if delta is None and h.is_Add and _has_simple_delta(h, index):
+            delta = True
+            func = h.func
+            terms = [terms[0]*t for t in h.args]
+        else:
+            terms = [t*h for t in terms]
+    return func(*terms)
+
+
+@cacheit
+def _extract_delta(expr, index):
+    """
+    Extract a simple KroneckerDelta from the expression.
+
+    Explanation
+    ===========
+
+    Returns the tuple ``(delta, newexpr)`` where:
+
+      - ``delta`` is a simple KroneckerDelta expression if one was found,
+        or ``None`` if no simple KroneckerDelta expression was found.
+
+      - ``newexpr`` is a Mul containing the remaining terms; ``expr`` is
+        returned unchanged if no simple KroneckerDelta expression was found.
+
+    Examples
+    ========
+
+    >>> from sympy import KroneckerDelta
+    >>> from sympy.concrete.delta import _extract_delta
+    >>> from sympy.abc import x, y, i, j, k
+    >>> _extract_delta(4*x*y*KroneckerDelta(i, j), i)
+    (KroneckerDelta(i, j), 4*x*y)
+    >>> _extract_delta(4*x*y*KroneckerDelta(i, j), k)
+    (None, 4*x*y*KroneckerDelta(i, j))
+
+    See Also
+    ========
+
+    sympy.functions.special.tensor_functions.KroneckerDelta
+    deltaproduct
+    deltasummation
+    """
+    if not _has_simple_delta(expr, index):
+        return (None, expr)
+    if isinstance(expr, KroneckerDelta):
+        return (expr, S.One)
+    if not expr.is_Mul:
+        raise ValueError("Incorrect expr")
+    delta = None
+    terms = []
+
+    for arg in expr.args:
+        if delta is None and _is_simple_delta(arg, index):
+            delta = arg
+        else:
+            terms.append(arg)
+    return (delta, expr.func(*terms))
+
+
+@cacheit
+def _has_simple_delta(expr, index):
+    """
+    Returns True if ``expr`` is an expression that contains a KroneckerDelta
+    that is simple in the index ``index``, meaning that this KroneckerDelta
+    is nonzero for a single value of the index ``index``.
+    """
+    if expr.has(KroneckerDelta):
+        if _is_simple_delta(expr, index):
+            return True
+        if expr.is_Add or expr.is_Mul:
+            for arg in expr.args:
+                if _has_simple_delta(arg, index):
+                    return True
+    return False
+
+
+@cacheit
+def _is_simple_delta(delta, index):
+    """
+    Returns True if ``delta`` is a KroneckerDelta and is nonzero for a single
+    value of the index ``index``.
+    """
+    if isinstance(delta, KroneckerDelta) and delta.has(index):
+        p = (delta.args[0] - delta.args[1]).as_poly(index)
+        if p:
+            return p.degree() == 1
+    return False
+
+
+@cacheit
+def _remove_multiple_delta(expr):
+    """
+    Evaluate products of KroneckerDelta's.
+    """
+    if expr.is_Add:
+        return expr.func(*list(map(_remove_multiple_delta, expr.args)))
+    if not expr.is_Mul:
+        return expr
+    eqs = []
+    newargs = []
+    for arg in expr.args:
+        if isinstance(arg, KroneckerDelta):
+            eqs.append(arg.args[0] - arg.args[1])
+        else:
+            newargs.append(arg)
+    if not eqs:
+        return expr
+    solns = solve(eqs, dict=True)
+    if len(solns) == 0:
+        return S.Zero
+    elif len(solns) == 1:
+        for key in solns[0].keys():
+            newargs.append(KroneckerDelta(key, solns[0][key]))
+        expr2 = expr.func(*newargs)
+        if expr != expr2:
+            return _remove_multiple_delta(expr2)
+    return expr
+
+
+@cacheit
+def _simplify_delta(expr):
+    """
+    Rewrite a KroneckerDelta's indices in its simplest form.
+    """
+    if isinstance(expr, KroneckerDelta):
+        try:
+            slns = solve(expr.args[0] - expr.args[1], dict=True)
+            if slns and len(slns) == 1:
+                return Mul(*[KroneckerDelta(*(key, value))
+                            for key, value in slns[0].items()])
+        except NotImplementedError:
+            pass
+    return expr
+
+
+@cacheit
+def deltaproduct(f, limit):
+    """
+    Handle products containing a KroneckerDelta.
+
+    See Also
+    ========
+
+    deltasummation
+    sympy.functions.special.tensor_functions.KroneckerDelta
+    sympy.concrete.products.product
+    """
+    if ((limit[2] - limit[1]) < 0) == True:
+        return S.One
+
+    if not f.has(KroneckerDelta):
+        return product(f, limit)
+
+    if f.is_Add:
+        # Identify the term in the Add that has a simple KroneckerDelta
+        delta = None
+        terms = []
+        for arg in sorted(f.args, key=default_sort_key):
+            if delta is None and _has_simple_delta(arg, limit[0]):
+                delta = arg
+            else:
+                terms.append(arg)
+        newexpr = f.func(*terms)
+        k = Dummy("kprime", integer=True)
+        if isinstance(limit[1], int) and isinstance(limit[2], int):
+            result = deltaproduct(newexpr, limit) + sum(deltaproduct(newexpr, (limit[0], limit[1], ik - 1)) *
+                delta.subs(limit[0], ik) *
+                deltaproduct(newexpr, (limit[0], ik + 1, limit[2])) for ik in range(int(limit[1]), int(limit[2] + 1))
+            )
+        else:
+            result = deltaproduct(newexpr, limit) + deltasummation(
+                deltaproduct(newexpr, (limit[0], limit[1], k - 1)) *
+                delta.subs(limit[0], k) *
+                deltaproduct(newexpr, (limit[0], k + 1, limit[2])),
+                (k, limit[1], limit[2]),
+                no_piecewise=_has_simple_delta(newexpr, limit[0])
+            )
+        return _remove_multiple_delta(result)
+
+    delta, _ = _extract_delta(f, limit[0])
+
+    if not delta:
+        g = _expand_delta(f, limit[0])
+        if f != g:
+            try:
+                return factor(deltaproduct(g, limit))
+            except AssertionError:
+                return deltaproduct(g, limit)
+        return product(f, limit)
+
+    return _remove_multiple_delta(f.subs(limit[0], limit[1])*KroneckerDelta(limit[2], limit[1])) + \
+        S.One*_simplify_delta(KroneckerDelta(limit[2], limit[1] - 1))
+
+
+@cacheit
+def deltasummation(f, limit, no_piecewise=False):
+    """
+    Handle summations containing a KroneckerDelta.
+
+    Explanation
+    ===========
+
+    The idea for summation is the following:
+
+    - If we are dealing with a KroneckerDelta expression, i.e. KroneckerDelta(g(x), j),
+      we try to simplify it.
+
+      If we could simplify it, then we sum the resulting expression.
+      We already know we can sum a simplified expression, because only
+      simple KroneckerDelta expressions are involved.
+
+      If we could not simplify it, there are two cases:
+
+      1) The expression is a simple expression: we return the summation,
+         taking care if we are dealing with a Derivative or with a proper
+         KroneckerDelta.
+
+      2) The expression is not simple (i.e. KroneckerDelta(cos(x))): we can do
+         nothing at all.
+
+    - If the expr is a multiplication expr having a KroneckerDelta term:
+
+      First we expand it.
+
+      If the expansion did work, then we try to sum the expansion.
+
+      If not, we try to extract a simple KroneckerDelta term, then we have two
+      cases:
+
+      1) We have a simple KroneckerDelta term, so we return the summation.
+
+      2) We did not have a simple term, but we do have an expression with
+         simplified KroneckerDelta terms, so we sum this expression.
+
+    Examples
+    ========
+
+    >>> from sympy import oo, symbols
+    >>> from sympy.abc import k
+    >>> i, j = symbols('i, j', integer=True, finite=True)
+    >>> from sympy.concrete.delta import deltasummation
+    >>> from sympy import KroneckerDelta
+    >>> deltasummation(KroneckerDelta(i, k), (k, -oo, oo))
+    1
+    >>> deltasummation(KroneckerDelta(i, k), (k, 0, oo))
+    Piecewise((1, i >= 0), (0, True))
+    >>> deltasummation(KroneckerDelta(i, k), (k, 1, 3))
+    Piecewise((1, (i >= 1) & (i <= 3)), (0, True))
+    >>> deltasummation(k*KroneckerDelta(i, j)*KroneckerDelta(j, k), (k, -oo, oo))
+    j*KroneckerDelta(i, j)
+    >>> deltasummation(j*KroneckerDelta(i, j), (j, -oo, oo))
+    i
+    >>> deltasummation(i*KroneckerDelta(i, j), (i, -oo, oo))
+    j
+
+    See Also
+    ========
+
+    deltaproduct
+    sympy.functions.special.tensor_functions.KroneckerDelta
+    sympy.concrete.sums.summation
+    """
+    if ((limit[2] - limit[1]) < 0) == True:
+        return S.Zero
+
+    if not f.has(KroneckerDelta):
+        return summation(f, limit)
+
+    x = limit[0]
+
+    g = _expand_delta(f, x)
+    if g.is_Add:
+        return piecewise_fold(
+            g.func(*[deltasummation(h, limit, no_piecewise) for h in g.args]))
+
+    # try to extract a simple KroneckerDelta term
+    delta, expr = _extract_delta(g, x)
+
+    if (delta is not None) and (delta.delta_range is not None):
+        dinf, dsup = delta.delta_range
+        if (limit[1] - dinf <= 0) == True and (limit[2] - dsup >= 0) == True:
+            no_piecewise = True
+
+    if not delta:
+        return summation(f, limit)
+
+    solns = solve(delta.args[0] - delta.args[1], x)
+    if len(solns) == 0:
+        return S.Zero
+    elif len(solns) != 1:
+        return Sum(f, limit)
+    value = solns[0]
+    if no_piecewise:
+        return expr.subs(x, value)
+    return Piecewise(
+        (expr.subs(x, value), Interval(*limit[1:3]).as_relational(value)),
+        (S.Zero, True)
+    )

lib/python3.12/site-packages/sympy/concrete/expr_with_intlimits.py

@@ -0,0 +1,354 @@
+from sympy.concrete.expr_with_limits import ExprWithLimits
+from sympy.core.singleton import S
+from sympy.core.relational import Eq
+
+class ReorderError(NotImplementedError):
+    """
+    Exception raised when trying to reorder dependent limits.
+    """
+    def __init__(self, expr, msg):
+        super().__init__(
+            "%s could not be reordered: %s." % (expr, msg))
+
+class ExprWithIntLimits(ExprWithLimits):
+    """
+    Superclass for Product and Sum.
+
+    See Also
+    ========
+
+    sympy.concrete.expr_with_limits.ExprWithLimits
+    sympy.concrete.products.Product
+    sympy.concrete.summations.Sum
+    """
+    __slots__ = ()
+
+    def change_index(self, var, trafo, newvar=None):
+        r"""
+        Change index of a Sum or Product.
+
+        Perform a linear transformation `x \mapsto a x + b` on the index variable
+        `x`. For `a` the only values allowed are `\pm 1`. A new variable to be used
+        after the change of index can also be specified.
+
+        Explanation
+        ===========
+
+        ``change_index(expr, var, trafo, newvar=None)`` where ``var`` specifies the
+        index variable `x` to transform. The transformation ``trafo`` must be linear
+        and given in terms of ``var``. If the optional argument ``newvar`` is
+        provided then ``var`` gets replaced by ``newvar`` in the final expression.
+
+        Examples
+        ========
+
+        >>> from sympy import Sum, Product, simplify
+        >>> from sympy.abc import x, y, a, b, c, d, u, v, i, j, k, l
+
+        >>> S = Sum(x, (x, a, b))
+        >>> S.doit()
+        -a**2/2 + a/2 + b**2/2 + b/2
+
+        >>> Sn = S.change_index(x, x + 1, y)
+        >>> Sn
+        Sum(y - 1, (y, a + 1, b + 1))
+        >>> Sn.doit()
+        -a**2/2 + a/2 + b**2/2 + b/2
+
+        >>> Sn = S.change_index(x, -x, y)
+        >>> Sn
+        Sum(-y, (y, -b, -a))
+        >>> Sn.doit()
+        -a**2/2 + a/2 + b**2/2 + b/2
+
+        >>> Sn = S.change_index(x, x+u)
+        >>> Sn
+        Sum(-u + x, (x, a + u, b + u))
+        >>> Sn.doit()
+        -a**2/2 - a*u + a/2 + b**2/2 + b*u + b/2 - u*(-a + b + 1) + u
+        >>> simplify(Sn.doit())
+        -a**2/2 + a/2 + b**2/2 + b/2
+
+        >>> Sn = S.change_index(x, -x - u, y)
+        >>> Sn
+        Sum(-u - y, (y, -b - u, -a - u))
+        >>> Sn.doit()
+        -a**2/2 - a*u + a/2 + b**2/2 + b*u + b/2 - u*(-a + b + 1) + u
+        >>> simplify(Sn.doit())
+        -a**2/2 + a/2 + b**2/2 + b/2
+
+        >>> P = Product(i*j**2, (i, a, b), (j, c, d))
+        >>> P
+        Product(i*j**2, (i, a, b), (j, c, d))
+        >>> P2 = P.change_index(i, i+3, k)
+        >>> P2
+        Product(j**2*(k - 3), (k, a + 3, b + 3), (j, c, d))
+        >>> P3 = P2.change_index(j, -j, l)
+        >>> P3
+        Product(l**2*(k - 3), (k, a + 3, b + 3), (l, -d, -c))
+
+        When dealing with symbols only, we can make a
+        general linear transformation:
+
+        >>> Sn = S.change_index(x, u*x+v, y)
+        >>> Sn
+        Sum((-v + y)/u, (y, b*u + v, a*u + v))
+        >>> Sn.doit()
+        -v*(a*u - b*u + 1)/u + (a**2*u**2/2 + a*u*v + a*u/2 - b**2*u**2/2 - b*u*v + b*u/2 + v)/u
+        >>> simplify(Sn.doit())
+        a**2*u/2 + a/2 - b**2*u/2 + b/2
+
+        However, the last result can be inconsistent with usual
+        summation where the index increment is always 1. This is
+        obvious as we get back the original value only for ``u``
+        equal +1 or -1.
+
+        See Also
+        ========
+
+        sympy.concrete.expr_with_intlimits.ExprWithIntLimits.index,
+        reorder_limit,
+        sympy.concrete.expr_with_intlimits.ExprWithIntLimits.reorder,
+        sympy.concrete.summations.Sum.reverse_order,
+        sympy.concrete.products.Product.reverse_order
+        """
+        if newvar is None:
+            newvar = var
+
+        limits = []
+        for limit in self.limits:
+            if limit[0] == var:
+                p = trafo.as_poly(var)
+                if p.degree() != 1:
+                    raise ValueError("Index transformation is not linear")
+                alpha = p.coeff_monomial(var)
+                beta = p.coeff_monomial(S.One)
+                if alpha.is_number:
+                    if alpha == S.One:
+                        limits.append((newvar, alpha*limit[1] + beta, alpha*limit[2] + beta))
+                    elif alpha == S.NegativeOne:
+                        limits.append((newvar, alpha*limit[2] + beta, alpha*limit[1] + beta))
+                    else:
+                        raise ValueError("Linear transformation results in non-linear summation stepsize")
+                else:
+                    # Note that the case of alpha being symbolic can give issues if alpha < 0.
+                    limits.append((newvar, alpha*limit[2] + beta, alpha*limit[1] + beta))
+            else:
+                limits.append(limit)
+
+        function = self.function.subs(var, (var - beta)/alpha)
+        function = function.subs(var, newvar)
+
+        return self.func(function, *limits)
+
+
+    def index(expr, x):
+        """
+        Return the index of a dummy variable in the list of limits.
+
+        Explanation
+        ===========
+
+        ``index(expr, x)``  returns the index of the dummy variable ``x`` in the
+        limits of ``expr``. Note that we start counting with 0 at the inner-most
+        limits tuple.
+
+        Examples
+        ========
+
+        >>> from sympy.abc import x, y, a, b, c, d
+        >>> from sympy import Sum, Product
+        >>> Sum(x*y, (x, a, b), (y, c, d)).index(x)
+        0
+        >>> Sum(x*y, (x, a, b), (y, c, d)).index(y)
+        1
+        >>> Product(x*y, (x, a, b), (y, c, d)).index(x)
+        0
+        >>> Product(x*y, (x, a, b), (y, c, d)).index(y)
+        1
+
+        See Also
+        ========
+
+        reorder_limit, reorder, sympy.concrete.summations.Sum.reverse_order,
+        sympy.concrete.products.Product.reverse_order
+        """
+        variables = [limit[0] for limit in expr.limits]
+
+        if variables.count(x) != 1:
+            raise ValueError(expr, "Number of instances of variable not equal to one")
+        else:
+            return variables.index(x)
+
+    def reorder(expr, *arg):
+        """
+        Reorder limits in a expression containing a Sum or a Product.
+
+        Explanation
+        ===========
+
+        ``expr.reorder(*arg)`` reorders the limits in the expression ``expr``
+        according to the list of tuples given by ``arg``. These tuples can
+        contain numerical indices or index variable names or involve both.
+
+        Examples
+        ========
+
+        >>> from sympy import Sum, Product
+        >>> from sympy.abc import x, y, z, a, b, c, d, e, f
+
+        >>> Sum(x*y, (x, a, b), (y, c, d)).reorder((x, y))
+        Sum(x*y, (y, c, d), (x, a, b))
+
+        >>> Sum(x*y*z, (x, a, b), (y, c, d), (z, e, f)).reorder((x, y), (x, z), (y, z))
+        Sum(x*y*z, (z, e, f), (y, c, d), (x, a, b))
+
+        >>> P = Product(x*y*z, (x, a, b), (y, c, d), (z, e, f))
+        >>> P.reorder((x, y), (x, z), (y, z))
+        Product(x*y*z, (z, e, f), (y, c, d), (x, a, b))
+
+        We can also select the index variables by counting them, starting
+        with the inner-most one:
+
+        >>> Sum(x**2, (x, a, b), (x, c, d)).reorder((0, 1))
+        Sum(x**2, (x, c, d), (x, a, b))
+
+        And of course we can mix both schemes:
+
+        >>> Sum(x*y, (x, a, b), (y, c, d)).reorder((y, x))
+        Sum(x*y, (y, c, d), (x, a, b))
+        >>> Sum(x*y, (x, a, b), (y, c, d)).reorder((y, 0))
+        Sum(x*y, (y, c, d), (x, a, b))
+
+        See Also
+        ========
+
+        reorder_limit, index, sympy.concrete.summations.Sum.reverse_order,
+        sympy.concrete.products.Product.reverse_order
+        """
+        new_expr = expr
+
+        for r in arg:
+            if len(r) != 2:
+                raise ValueError(r, "Invalid number of arguments")
+
+            index1 = r[0]
+            index2 = r[1]
+
+            if not isinstance(r[0], int):
+                index1 = expr.index(r[0])
+            if not isinstance(r[1], int):
+                index2 = expr.index(r[1])
+
+            new_expr = new_expr.reorder_limit(index1, index2)
+
+        return new_expr
+
+
+    def reorder_limit(expr, x, y):
+        """
+        Interchange two limit tuples of a Sum or Product expression.
+
+        Explanation
+        ===========
+
+        ``expr.reorder_limit(x, y)`` interchanges two limit tuples. The
+        arguments ``x`` and ``y`` are integers corresponding to the index
+        variables of the two limits which are to be interchanged. The
+        expression ``expr`` has to be either a Sum or a Product.
+
+        Examples
+        ========
+
+        >>> from sympy.abc import x, y, z, a, b, c, d, e, f
+        >>> from sympy import Sum, Product
+
+        >>> Sum(x*y*z, (x, a, b), (y, c, d), (z, e, f)).reorder_limit(0, 2)
+        Sum(x*y*z, (z, e, f), (y, c, d), (x, a, b))
+        >>> Sum(x**2, (x, a, b), (x, c, d)).reorder_limit(1, 0)
+        Sum(x**2, (x, c, d), (x, a, b))
+
+        >>> Product(x*y*z, (x, a, b), (y, c, d), (z, e, f)).reorder_limit(0, 2)
+        Product(x*y*z, (z, e, f), (y, c, d), (x, a, b))
+
+        See Also
+        ========
+
+        index, reorder, sympy.concrete.summations.Sum.reverse_order,
+        sympy.concrete.products.Product.reverse_order
+        """
+        var = {limit[0] for limit in expr.limits}
+        limit_x = expr.limits[x]
+        limit_y = expr.limits[y]
+
+        if (len(set(limit_x[1].free_symbols).intersection(var)) == 0 and
+            len(set(limit_x[2].free_symbols).intersection(var)) == 0 and
+            len(set(limit_y[1].free_symbols).intersection(var)) == 0 and
+            len(set(limit_y[2].free_symbols).intersection(var)) == 0):
+
+            limits = []
+            for i, limit in enumerate(expr.limits):
+                if i == x:
+                    limits.append(limit_y)
+                elif i == y:
+                    limits.append(limit_x)
+                else:
+                    limits.append(limit)
+
+            return type(expr)(expr.function, *limits)
+        else:
+            raise ReorderError(expr, "could not interchange the two limits specified")
+
+    @property
+    def has_empty_sequence(self):
+        """
+        Returns True if the Sum or Product is computed for an empty sequence.
+
+        Examples
+        ========
+
+        >>> from sympy import Sum, Product, Symbol
+        >>> m = Symbol('m')
+        >>> Sum(m, (m, 1, 0)).has_empty_sequence
+        True
+
+        >>> Sum(m, (m, 1, 1)).has_empty_sequence
+        False
+
+        >>> M = Symbol('M', integer=True, positive=True)
+        >>> Product(m, (m, 1, M)).has_empty_sequence
+        False
+
+        >>> Product(m, (m, 2, M)).has_empty_sequence
+
+        >>> Product(m, (m, M + 1, M)).has_empty_sequence
+        True
+
+        >>> N = Symbol('N', integer=True, positive=True)
+        >>> Sum(m, (m, N, M)).has_empty_sequence
+
+        >>> N = Symbol('N', integer=True, negative=True)
+        >>> Sum(m, (m, N, M)).has_empty_sequence
+        False
+
+        See Also
+        ========
+
+        has_reversed_limits
+        has_finite_limits
+
+        """
+        ret_None = False
+        for lim in self.limits:
+            dif = lim[1] - lim[2]
+            eq = Eq(dif, 1)
+            if eq == True:
+                return True
+            elif eq == False:
+                continue
+            else:
+                ret_None = True
+
+        if ret_None:
+            return None
+        return False

lib/python3.12/site-packages/sympy/concrete/expr_with_limits.py

@@ -0,0 +1,603 @@
+from sympy.core.add import Add
+from sympy.core.containers import Tuple
+from sympy.core.expr import Expr
+from sympy.core.function import AppliedUndef, UndefinedFunction
+from sympy.core.mul import Mul
+from sympy.core.relational import Equality, Relational
+from sympy.core.singleton import S
+from sympy.core.symbol import Symbol, Dummy
+from sympy.core.sympify import sympify
+from sympy.functions.elementary.piecewise import (piecewise_fold,
+    Piecewise)
+from sympy.logic.boolalg import BooleanFunction
+from sympy.matrices.matrixbase import MatrixBase
+from sympy.sets.sets import Interval, Set
+from sympy.sets.fancysets import Range
+from sympy.tensor.indexed import Idx
+from sympy.utilities import flatten
+from sympy.utilities.iterables import sift, is_sequence
+from sympy.utilities.exceptions import sympy_deprecation_warning
+
+
+def _common_new(cls, function, *symbols, discrete, **assumptions):
+    """Return either a special return value or the tuple,
+    (function, limits, orientation). This code is common to
+    both ExprWithLimits and AddWithLimits."""
+    function = sympify(function)
+
+    if isinstance(function, Equality):
+        # This transforms e.g. Integral(Eq(x, y)) to Eq(Integral(x), Integral(y))
+        # but that is only valid for definite integrals.
+        limits, orientation = _process_limits(*symbols, discrete=discrete)
+        if not (limits and all(len(limit) == 3 for limit in limits)):
+            sympy_deprecation_warning(
+                """
+                Creating a indefinite integral with an Eq() argument is
+                deprecated.
+
+                This is because indefinite integrals do not preserve equality
+                due to the arbitrary constants. If you want an equality of
+                indefinite integrals, use Eq(Integral(a, x), Integral(b, x))
+                explicitly.
+                """,
+                deprecated_since_version="1.6",
+                active_deprecations_target="deprecated-indefinite-integral-eq",
+                stacklevel=5,
+            )
+
+        lhs = function.lhs
+        rhs = function.rhs
+        return Equality(cls(lhs, *symbols, **assumptions), \
+                        cls(rhs, *symbols, **assumptions))
+
+    if function is S.NaN:
+        return S.NaN
+
+    if symbols:
+        limits, orientation = _process_limits(*symbols, discrete=discrete)
+        for i, li in enumerate(limits):
+            if len(li) == 4:
+                function = function.subs(li[0], li[-1])
+                limits[i] = Tuple(*li[:-1])
+    else:
+        # symbol not provided -- we can still try to compute a general form
+        free = function.free_symbols
+        if len(free) != 1:
+            raise ValueError(
+                "specify dummy variables for %s" % function)
+        limits, orientation = [Tuple(s) for s in free], 1
+
+    # denest any nested calls
+    while cls == type(function):
+        limits = list(function.limits) + limits
+        function = function.function
+
+    # Any embedded piecewise functions need to be brought out to the
+    # top level. We only fold Piecewise that contain the integration
+    # variable.
+    reps = {}
+    symbols_of_integration = {i[0] for i in limits}
+    for p in function.atoms(Piecewise):
+        if not p.has(*symbols_of_integration):
+            reps[p] = Dummy()
+    # mask off those that don't
+    function = function.xreplace(reps)
+    # do the fold
+    function = piecewise_fold(function)
+    # remove the masking
+    function = function.xreplace({v: k for k, v in reps.items()})
+
+    return function, limits, orientation
+
+
+def _process_limits(*symbols, discrete=None):
+    """Process the list of symbols and convert them to canonical limits,
+    storing them as Tuple(symbol, lower, upper). The orientation of
+    the function is also returned when the upper limit is missing
+    so (x, 1, None) becomes (x, None, 1) and the orientation is changed.
+    In the case that a limit is specified as (symbol, Range), a list of
+    length 4 may be returned if a change of variables is needed; the
+    expression that should replace the symbol in the expression is
+    the fourth element in the list.
+    """
+    limits = []
+    orientation = 1
+    if discrete is None:
+        err_msg = 'discrete must be True or False'
+    elif discrete:
+        err_msg = 'use Range, not Interval or Relational'
+    else:
+        err_msg = 'use Interval or Relational, not Range'
+    for V in symbols:
+        if isinstance(V, (Relational, BooleanFunction)):
+            if discrete:
+                raise TypeError(err_msg)
+            variable = V.atoms(Symbol).pop()
+            V = (variable, V.as_set())
+        elif isinstance(V, Symbol) or getattr(V, '_diff_wrt', False):
+            if isinstance(V, Idx):
+                if V.lower is None or V.upper is None:
+                    limits.append(Tuple(V))
+                else:
+                    limits.append(Tuple(V, V.lower, V.upper))
+            else:
+                limits.append(Tuple(V))
+            continue
+        if is_sequence(V) and not isinstance(V, Set):
+            if len(V) == 2 and isinstance(V[1], Set):
+                V = list(V)
+                if isinstance(V[1], Interval):  # includes Reals
+                    if discrete:
+                        raise TypeError(err_msg)
+                    V[1:] = V[1].inf, V[1].sup
+                elif isinstance(V[1], Range):
+                    if not discrete:
+                        raise TypeError(err_msg)
+                    lo = V[1].inf
+                    hi = V[1].sup
+                    dx = abs(V[1].step)  # direction doesn't matter
+                    if dx == 1:
+                        V[1:] = [lo, hi]
+                    else:
+                        if lo is not S.NegativeInfinity:
+                            V = [V[0]] + [0, (hi - lo)//dx, dx*V[0] + lo]
+                        else:
+                            V = [V[0]] + [0, S.Infinity, -dx*V[0] + hi]
+                else:
+                    # more complicated sets would require splitting, e.g.
+                    # Union(Interval(1, 3), interval(6,10))
+                    raise NotImplementedError(
+                        'expecting Range' if discrete else
+                        'Relational or single Interval' )
+            V = sympify(flatten(V))  # list of sympified elements/None
+            if isinstance(V[0], (Symbol, Idx)) or getattr(V[0], '_diff_wrt', False):
+                newsymbol = V[0]
+                if len(V) == 3:
+                    # general case
+                    if V[2] is None and V[1] is not None:
+                        orientation *= -1
+                    V = [newsymbol] + [i for i in V[1:] if i is not None]
+
+                lenV = len(V)
+                if not isinstance(newsymbol, Idx) or lenV == 3:
+                    if lenV == 4:
+                        limits.append(Tuple(*V))
+                        continue
+                    if lenV == 3:
+                        if isinstance(newsymbol, Idx):
+                            # Idx represents an integer which may have
+                            # specified values it can take on; if it is
+                            # given such a value, an error is raised here
+                            # if the summation would try to give it a larger
+                            # or smaller value than permitted. None and Symbolic
+                            # values will not raise an error.
+                            lo, hi = newsymbol.lower, newsymbol.upper
+                            try:
+                                if lo is not None and not bool(V[1] >= lo):
+                                    raise ValueError("Summation will set Idx value too low.")
+                            except TypeError:
+                                pass
+                            try:
+                                if hi is not None and not bool(V[2] <= hi):
+                                    raise ValueError("Summation will set Idx value too high.")
+                            except TypeError:
+                                pass
+                        limits.append(Tuple(*V))
+                        continue
+                    if lenV == 1 or (lenV == 2 and V[1] is None):
+                        limits.append(Tuple(newsymbol))
+                        continue
+                    elif lenV == 2:
+                        limits.append(Tuple(newsymbol, V[1]))
+                        continue
+
+        raise ValueError('Invalid limits given: %s' % str(symbols))
+
+    return limits, orientation
+
+
+class ExprWithLimits(Expr):
+    __slots__ = ('is_commutative',)
+
+    def __new__(cls, function, *symbols, **assumptions):
+        from sympy.concrete.products import Product
+        pre = _common_new(cls, function, *symbols,
+            discrete=issubclass(cls, Product), **assumptions)
+        if isinstance(pre, tuple):
+            function, limits, _ = pre
+        else:
+            return pre
+
+        # limits must have upper and lower bounds; the indefinite form
+        # is not supported. This restriction does not apply to AddWithLimits
+        if any(len(l) != 3 or None in l for l in limits):
+            raise ValueError('ExprWithLimits requires values for lower and upper bounds.')
+
+        obj = Expr.__new__(cls, **assumptions)
+        arglist = [function]
+        arglist.extend(limits)
+        obj._args = tuple(arglist)
+        obj.is_commutative = function.is_commutative  # limits already checked
+
+        return obj
+
+    @property
+    def function(self):
+        """Return the function applied across limits.
+
+        Examples
+        ========
+
+        >>> from sympy import Integral
+        >>> from sympy.abc import x
+        >>> Integral(x**2, (x,)).function
+        x**2
+
+        See Also
+        ========
+
+        limits, variables, free_symbols
+        """
+        return self._args[0]
+
+    @property
+    def kind(self):
+        return self.function.kind
+
+    @property
+    def limits(self):
+        """Return the limits of expression.
+
+        Examples
+        ========
+
+        >>> from sympy import Integral
+        >>> from sympy.abc import x, i
+        >>> Integral(x**i, (i, 1, 3)).limits
+        ((i, 1, 3),)
+
+        See Also
+        ========
+
+        function, variables, free_symbols
+        """
+        return self._args[1:]
+
+    @property
+    def variables(self):
+        """Return a list of the limit variables.
+
+        >>> from sympy import Sum
+        >>> from sympy.abc import x, i
+        >>> Sum(x**i, (i, 1, 3)).variables
+        [i]
+
+        See Also
+        ========
+
+        function, limits, free_symbols
+        as_dummy : Rename dummy variables
+        sympy.integrals.integrals.Integral.transform : Perform mapping on the dummy variable
+        """
+        return [l[0] for l in self.limits]
+
+    @property
+    def bound_symbols(self):
+        """Return only variables that are dummy variables.
+
+        Examples
+        ========
+
+        >>> from sympy import Integral
+        >>> from sympy.abc import x, i, j, k
+        >>> Integral(x**i, (i, 1, 3), (j, 2), k).bound_symbols
+        [i, j]
+
+        See Also
+        ========
+
+        function, limits, free_symbols
+        as_dummy : Rename dummy variables
+        sympy.integrals.integrals.Integral.transform : Perform mapping on the dummy variable
+        """
+        return [l[0] for l in self.limits if len(l) != 1]
+
+    @property
+    def free_symbols(self):
+        """
+        This method returns the symbols in the object, excluding those
+        that take on a specific value (i.e. the dummy symbols).
+
+        Examples
+        ========
+
+        >>> from sympy import Sum
+        >>> from sympy.abc import x, y
+        >>> Sum(x, (x, y, 1)).free_symbols
+        {y}
+        """
+        # don't test for any special values -- nominal free symbols
+        # should be returned, e.g. don't return set() if the
+        # function is zero -- treat it like an unevaluated expression.
+        function, limits = self.function, self.limits
+        # mask off non-symbol integration variables that have
+        # more than themself as a free symbol
+        reps = {i[0]: i[0] if i[0].free_symbols == {i[0]} else Dummy()
+            for i in self.limits}
+        function = function.xreplace(reps)
+        isyms = function.free_symbols
+        for xab in limits:
+            v = reps[xab[0]]
+            if len(xab) == 1:
+                isyms.add(v)
+                continue
+            # take out the target symbol
+            if v in isyms:
+                isyms.remove(v)
+            # add in the new symbols
+            for i in xab[1:]:
+                isyms.update(i.free_symbols)
+        reps = {v: k for k, v in reps.items()}
+        return {reps.get(_, _) for _ in isyms}
+
+    @property
+    def is_number(self):
+        """Return True if the Sum has no free symbols, else False."""
+        return not self.free_symbols
+
+    def _eval_interval(self, x, a, b):
+        limits = [(i if i[0] != x else (x, a, b)) for i in self.limits]
+        integrand = self.function
+        return self.func(integrand, *limits)
+
+    def _eval_subs(self, old, new):
+        """
+        Perform substitutions over non-dummy variables
+        of an expression with limits.  Also, can be used
+        to specify point-evaluation of an abstract antiderivative.
+
+        Examples
+        ========
+
+        >>> from sympy import Sum, oo
+        >>> from sympy.abc import s, n
+        >>> Sum(1/n**s, (n, 1, oo)).subs(s, 2)
+        Sum(n**(-2), (n, 1, oo))
+
+        >>> from sympy import Integral
+        >>> from sympy.abc import x, a
+        >>> Integral(a*x**2, x).subs(x, 4)
+        Integral(a*x**2, (x, 4))
+
+        See Also
+        ========
+
+        variables : Lists the integration variables
+        transform : Perform mapping on the dummy variable for integrals
+        change_index : Perform mapping on the sum and product dummy variables
+
+        """
+        func, limits = self.function, list(self.limits)
+
+        # If one of the expressions we are replacing is used as a func index
+        # one of two things happens.
+        #   - the old variable first appears as a free variable
+        #     so we perform all free substitutions before it becomes
+        #     a func index.
+        #   - the old variable first appears as a func index, in
+        #     which case we ignore.  See change_index.
+
+        # Reorder limits to match standard mathematical practice for scoping
+        limits.reverse()
+
+        if not isinstance(old, Symbol) or \
+                old.free_symbols.intersection(self.free_symbols):
+            sub_into_func = True
+            for i, xab in enumerate(limits):
+                if 1 == len(xab) and old == xab[0]:
+                    if new._diff_wrt:
+                        xab = (new,)
+                    else:
+                        xab = (old, old)
+                limits[i] = Tuple(xab[0], *[l._subs(old, new) for l in xab[1:]])
+                if len(xab[0].free_symbols.intersection(old.free_symbols)) != 0:
+                    sub_into_func = False
+                    break
+            if isinstance(old, (AppliedUndef, UndefinedFunction)):
+                sy2 = set(self.variables).intersection(set(new.atoms(Symbol)))
+                sy1 = set(self.variables).intersection(set(old.args))
+                if not sy2.issubset(sy1):
+                    raise ValueError(
+                        "substitution cannot create dummy dependencies")
+                sub_into_func = True
+            if sub_into_func:
+                func = func.subs(old, new)
+        else:
+            # old is a Symbol and a dummy variable of some limit
+            for i, xab in enumerate(limits):
+                if len(xab) == 3:
+                    limits[i] = Tuple(xab[0], *[l._subs(old, new) for l in xab[1:]])
+                    if old == xab[0]:
+                        break
+        # simplify redundant limits (x, x)  to (x, )
+        for i, xab in enumerate(limits):
+            if len(xab) == 2 and (xab[0] - xab[1]).is_zero:
+                limits[i] = Tuple(xab[0], )
+
+        # Reorder limits back to representation-form
+        limits.reverse()
+
+        return self.func(func, *limits)
+
+    @property
+    def has_finite_limits(self):
+        """
+        Returns True if the limits are known to be finite, either by the
+        explicit bounds, assumptions on the bounds, or assumptions on the
+        variables.  False if known to be infinite, based on the bounds.
+        None if not enough information is available to determine.
+
+        Examples
+        ========
+
+        >>> from sympy import Sum, Integral, Product, oo, Symbol
+        >>> x = Symbol('x')
+        >>> Sum(x, (x, 1, 8)).has_finite_limits
+        True
+
+        >>> Integral(x, (x, 1, oo)).has_finite_limits
+        False
+
+        >>> M = Symbol('M')
+        >>> Sum(x, (x, 1, M)).has_finite_limits
+
+        >>> N = Symbol('N', integer=True)
+        >>> Product(x, (x, 1, N)).has_finite_limits
+        True
+
+        See Also
+        ========
+
+        has_reversed_limits
+
+        """
+
+        ret_None = False
+        for lim in self.limits:
+            if len(lim) == 3:
+                if any(l.is_infinite for l in lim[1:]):
+                    # Any of the bounds are +/-oo
+                    return False
+                elif any(l.is_infinite is None for l in lim[1:]):
+                    # Maybe there are assumptions on the variable?
+                    if lim[0].is_infinite is None:
+                        ret_None = True
+            else:
+                if lim[0].is_infinite is None:
+                    ret_None = True
+
+        if ret_None:
+            return None
+        return True
+
+    @property
+    def has_reversed_limits(self):
+        """
+        Returns True if the limits are known to be in reversed order, either
+        by the explicit bounds, assumptions on the bounds, or assumptions on the
+        variables.  False if known to be in normal order, based on the bounds.
+        None if not enough information is available to determine.
+
+        Examples
+        ========
+
+        >>> from sympy import Sum, Integral, Product, oo, Symbol
+        >>> x = Symbol('x')
+        >>> Sum(x, (x, 8, 1)).has_reversed_limits
+        True
+
+        >>> Sum(x, (x, 1, oo)).has_reversed_limits
+        False
+
+        >>> M = Symbol('M')
+        >>> Integral(x, (x, 1, M)).has_reversed_limits
+
+        >>> N = Symbol('N', integer=True, positive=True)
+        >>> Sum(x, (x, 1, N)).has_reversed_limits
+        False
+
+        >>> Product(x, (x, 2, N)).has_reversed_limits
+
+        >>> Product(x, (x, 2, N)).subs(N, N + 2).has_reversed_limits
+        False
+
+        See Also
+        ========
+
+        sympy.concrete.expr_with_intlimits.ExprWithIntLimits.has_empty_sequence
+
+        """
+        ret_None = False
+        for lim in self.limits:
+            if len(lim) == 3:
+                var, a, b = lim
+                dif = b - a
+                if dif.is_extended_negative:
+                    return True
+                elif dif.is_extended_nonnegative:
+                    continue
+                else:
+                    ret_None = True
+            else:
+                return None
+        if ret_None:
+            return None
+        return False
+
+
+class AddWithLimits(ExprWithLimits):
+    r"""Represents unevaluated oriented additions.
+        Parent class for Integral and Sum.
+    """
+
+    __slots__ = ()
+
+    def __new__(cls, function, *symbols, **assumptions):
+        from sympy.concrete.summations import Sum
+        pre = _common_new(cls, function, *symbols,
+            discrete=issubclass(cls, Sum), **assumptions)
+        if isinstance(pre, tuple):
+            function, limits, orientation = pre
+        else:
+            return pre
+
+        obj = Expr.__new__(cls, **assumptions)
+        arglist = [orientation*function]  # orientation not used in ExprWithLimits
+        arglist.extend(limits)
+        obj._args = tuple(arglist)
+        obj.is_commutative = function.is_commutative  # limits already checked
+
+        return obj
+
+    def _eval_adjoint(self):
+        if all(x.is_real for x in flatten(self.limits)):
+            return self.func(self.function.adjoint(), *self.limits)
+        return None
+
+    def _eval_conjugate(self):
+        if all(x.is_real for x in flatten(self.limits)):
+            return self.func(self.function.conjugate(), *self.limits)
+        return None
+
+    def _eval_transpose(self):
+        if all(x.is_real for x in flatten(self.limits)):
+            return self.func(self.function.transpose(), *self.limits)
+        return None
+
+    def _eval_factor(self, **hints):
+        if 1 == len(self.limits):
+            summand = self.function.factor(**hints)
+            if summand.is_Mul:
+                out = sift(summand.args, lambda w: w.is_commutative \
+                    and not set(self.variables) & w.free_symbols)
+                return Mul(*out[True])*self.func(Mul(*out[False]), \
+                    *self.limits)
+        else:
+            summand = self.func(self.function, *self.limits[0:-1]).factor()
+            if not summand.has(self.variables[-1]):
+                return self.func(1, [self.limits[-1]]).doit()*summand
+            elif isinstance(summand, Mul):
+                return self.func(summand, self.limits[-1]).factor()
+        return self
+
+    def _eval_expand_basic(self, **hints):
+        summand = self.function.expand(**hints)
+        force = hints.get('force', False)
+        if (summand.is_Add and (force or summand.is_commutative and
+                 self.has_finite_limits is not False)):
+            return Add(*[self.func(i, *self.limits) for i in summand.args])
+        elif isinstance(summand, MatrixBase):
+            return summand.applyfunc(lambda x: self.func(x, *self.limits))
+        elif summand != self.function:
+            return self.func(summand, *self.limits)
+        return self

lib/python3.12/site-packages/sympy/concrete/gosper.py

@@ -0,0 +1,227 @@
+"""Gosper's algorithm for hypergeometric summation. """
+
+from sympy.core import S, Dummy, symbols
+from sympy.polys import Poly, parallel_poly_from_expr, factor
+from sympy.utilities.iterables import is_sequence
+
+
+def gosper_normal(f, g, n, polys=True):
+    r"""
+    Compute the Gosper's normal form of ``f`` and ``g``.
+
+    Explanation
+    ===========
+
+    Given relatively prime univariate polynomials ``f`` and ``g``,
+    rewrite their quotient to a normal form defined as follows:
+
+    .. math::
+        \frac{f(n)}{g(n)} = Z \cdot \frac{A(n) C(n+1)}{B(n) C(n)}
+
+    where ``Z`` is an arbitrary constant and ``A``, ``B``, ``C`` are
+    monic polynomials in ``n`` with the following properties:
+
+    1. `\gcd(A(n), B(n+h)) = 1 \forall h \in \mathbb{N}`
+    2. `\gcd(B(n), C(n+1)) = 1`
+    3. `\gcd(A(n), C(n)) = 1`
+
+    This normal form, or rational factorization in other words, is a
+    crucial step in Gosper's algorithm and in solving of difference
+    equations. It can be also used to decide if two hypergeometric
+    terms are similar or not.
+
+    This procedure will return a tuple containing elements of this
+    factorization in the form ``(Z*A, B, C)``.
+
+    Examples
+    ========
+
+    >>> from sympy.concrete.gosper import gosper_normal
+    >>> from sympy.abc import n
+
+    >>> gosper_normal(4*n+5, 2*(4*n+1)*(2*n+3), n, polys=False)
+    (1/4, n + 3/2, n + 1/4)
+
+    """
+    (p, q), opt = parallel_poly_from_expr(
+        (f, g), n, field=True, extension=True)
+
+    a, A = p.LC(), p.monic()
+    b, B = q.LC(), q.monic()
+
+    C, Z = A.one, a/b
+    h = Dummy('h')
+
+    D = Poly(n + h, n, h, domain=opt.domain)
+
+    R = A.resultant(B.compose(D))
+    roots = set(R.ground_roots().keys())
+
+    for r in set(roots):
+        if not r.is_Integer or r < 0:
+            roots.remove(r)
+
+    for i in sorted(roots):
+        d = A.gcd(B.shift(+i))
+
+        A = A.quo(d)
+        B = B.quo(d.shift(-i))
+
+        for j in range(1, i + 1):
+            C *= d.shift(-j)
+
+    A = A.mul_ground(Z)
+
+    if not polys:
+        A = A.as_expr()
+        B = B.as_expr()
+        C = C.as_expr()
+
+    return A, B, C
+
+
+def gosper_term(f, n):
+    r"""
+    Compute Gosper's hypergeometric term for ``f``.
+
+    Explanation
+    ===========
+
+    Suppose ``f`` is a hypergeometric term such that:
+
+    .. math::
+        s_n = \sum_{k=0}^{n-1} f_k
+
+    and `f_k` does not depend on `n`. Returns a hypergeometric
+    term `g_n` such that `g_{n+1} - g_n = f_n`.
+
+    Examples
+    ========
+
+    >>> from sympy.concrete.gosper import gosper_term
+    >>> from sympy import factorial
+    >>> from sympy.abc import n
+
+    >>> gosper_term((4*n + 1)*factorial(n)/factorial(2*n + 1), n)
+    (-n - 1/2)/(n + 1/4)
+
+    """
+    from sympy.simplify import hypersimp
+    r = hypersimp(f, n)
+
+    if r is None:
+        return None    # 'f' is *not* a hypergeometric term
+
+    p, q = r.as_numer_denom()
+
+    A, B, C = gosper_normal(p, q, n)
+    B = B.shift(-1)
+
+    N = S(A.degree())
+    M = S(B.degree())
+    K = S(C.degree())
+
+    if (N != M) or (A.LC() != B.LC()):
+        D = {K - max(N, M)}
+    elif not N:
+        D = {K - N + 1, S.Zero}
+    else:
+        D = {K - N + 1, (B.nth(N - 1) - A.nth(N - 1))/A.LC()}
+
+    for d in set(D):
+        if not d.is_Integer or d < 0:
+            D.remove(d)
+
+    if not D:
+        return None    # 'f(n)' is *not* Gosper-summable
+
+    d = max(D)
+
+    coeffs = symbols('c:%s' % (d + 1), cls=Dummy)
+    domain = A.get_domain().inject(*coeffs)
+
+    x = Poly(coeffs, n, domain=domain)
+    H = A*x.shift(1) - B*x - C
+
+    from sympy.solvers.solvers import solve
+    solution = solve(H.coeffs(), coeffs)
+
+    if solution is None:
+        return None    # 'f(n)' is *not* Gosper-summable
+
+    x = x.as_expr().subs(solution)
+
+    for coeff in coeffs:
+        if coeff not in solution:
+            x = x.subs(coeff, 0)
+
+    if x.is_zero:
+        return None    # 'f(n)' is *not* Gosper-summable
+    else:
+        return B.as_expr()*x/C.as_expr()
+
+
+def gosper_sum(f, k):
+    r"""
+    Gosper's hypergeometric summation algorithm.
+
+    Explanation
+    ===========
+
+    Given a hypergeometric term ``f`` such that:
+
+    .. math ::
+        s_n = \sum_{k=0}^{n-1} f_k
+
+    and `f(n)` does not depend on `n`, returns `g_{n} - g(0)` where
+    `g_{n+1} - g_n = f_n`, or ``None`` if `s_n` cannot be expressed
+    in closed form as a sum of hypergeometric terms.
+
+    Examples
+    ========
+
+    >>> from sympy.concrete.gosper import gosper_sum
+    >>> from sympy import factorial
+    >>> from sympy.abc import n, k
+
+    >>> f = (4*k + 1)*factorial(k)/factorial(2*k + 1)
+    >>> gosper_sum(f, (k, 0, n))
+    (-factorial(n) + 2*factorial(2*n + 1))/factorial(2*n + 1)
+    >>> _.subs(n, 2) == sum(f.subs(k, i) for i in [0, 1, 2])
+    True
+    >>> gosper_sum(f, (k, 3, n))
+    (-60*factorial(n) + factorial(2*n + 1))/(60*factorial(2*n + 1))
+    >>> _.subs(n, 5) == sum(f.subs(k, i) for i in [3, 4, 5])
+    True
+
+    References
+    ==========
+
+    .. [1] Marko Petkovsek, Herbert S. Wilf, Doron Zeilberger, A = B,
+           AK Peters, Ltd., Wellesley, MA, USA, 1997, pp. 73--100
+
+    """
+    indefinite = False
+
+    if is_sequence(k):
+        k, a, b = k
+    else:
+        indefinite = True
+
+    g = gosper_term(f, k)
+
+    if g is None:
+        return None
+
+    if indefinite:
+        result = f*g
+    else:
+        result = (f*(g + 1)).subs(k, b) - (f*g).subs(k, a)
+
+        if result is S.NaN:
+            try:
+                result = (f*(g + 1)).limit(k, b) - (f*g).limit(k, a)
+            except NotImplementedError:
+                result = None
+
+    return factor(result)

lib/python3.12/site-packages/sympy/concrete/guess.py

@@ -0,0 +1,473 @@
+"""Various algorithms for helping identifying numbers and sequences."""
+
+
+from sympy.concrete.products import (Product, product)
+from sympy.core import Function, S
+from sympy.core.add import Add
+from sympy.core.numbers import Integer, Rational
+from sympy.core.symbol import Symbol, symbols
+from sympy.core.sympify import sympify
+from sympy.functions.elementary.exponential import exp
+from sympy.functions.elementary.integers import floor
+from sympy.integrals.integrals import integrate
+from sympy.polys.polyfuncs import rational_interpolate as rinterp
+from sympy.polys.polytools import lcm
+from sympy.simplify.radsimp import denom
+from sympy.utilities import public
+
+
+@public
+def find_simple_recurrence_vector(l):
+    """
+    This function is used internally by other functions from the
+    sympy.concrete.guess module. While most users may want to rather use the
+    function find_simple_recurrence when looking for recurrence relations
+    among rational numbers, the current function may still be useful when
+    some post-processing has to be done.
+
+    Explanation
+    ===========
+
+    The function returns a vector of length n when a recurrence relation of
+    order n is detected in the sequence of rational numbers v.
+
+    If the returned vector has a length 1, then the returned value is always
+    the list [0], which means that no relation has been found.
+
+    While the functions is intended to be used with rational numbers, it should
+    work for other kinds of real numbers except for some cases involving
+    quadratic numbers; for that reason it should be used with some caution when
+    the argument is not a list of rational numbers.
+
+    Examples
+    ========
+
+    >>> from sympy.concrete.guess import find_simple_recurrence_vector
+    >>> from sympy import fibonacci
+    >>> find_simple_recurrence_vector([fibonacci(k) for k in range(12)])
+    [1, -1, -1]
+
+    See Also
+    ========
+
+    See the function sympy.concrete.guess.find_simple_recurrence which is more
+    user-friendly.
+
+    """
+    q1 = [0]
+    q2 = [1]
+    b, z = 0, len(l) >> 1
+    while len(q2) <= z:
+        while l[b]==0:
+            b += 1
+            if b == len(l):
+                c = 1
+                for x in q2:
+                    c = lcm(c, denom(x))
+                if q2[0]*c < 0: c = -c
+                for k in range(len(q2)):
+                    q2[k] = int(q2[k]*c)
+                return q2
+        a = S.One/l[b]
+        m = [a]
+        for k in range(b+1, len(l)):
+            m.append(-sum(l[j+1]*m[b-j-1] for j in range(b, k))*a)
+        l, m = m, [0] * max(len(q2), b+len(q1))
+        for k, q in enumerate(q2):
+            m[k] = a*q
+        for k, q in enumerate(q1):
+            m[k+b] += q
+        while m[-1]==0: m.pop() # because trailing zeros can occur
+        q1, q2, b = q2, m, 1
+    return [0]
+
+@public
+def find_simple_recurrence(v, A=Function('a'), N=Symbol('n')):
+    """
+    Detects and returns a recurrence relation from a sequence of several integer
+    (or rational) terms. The name of the function in the returned expression is
+    'a' by default; the main variable is 'n' by default. The smallest index in
+    the returned expression is always n (and never n-1, n-2, etc.).
+
+    Examples
+    ========
+
+    >>> from sympy.concrete.guess import find_simple_recurrence
+    >>> from sympy import fibonacci
+    >>> find_simple_recurrence([fibonacci(k) for k in range(12)])
+    -a(n) - a(n + 1) + a(n + 2)
+
+    >>> from sympy import Function, Symbol
+    >>> a = [1, 1, 1]
+    >>> for k in range(15): a.append(5*a[-1]-3*a[-2]+8*a[-3])
+    >>> find_simple_recurrence(a, A=Function('f'), N=Symbol('i'))
+    -8*f(i) + 3*f(i + 1) - 5*f(i + 2) + f(i + 3)
+
+    """
+    p = find_simple_recurrence_vector(v)
+    n = len(p)
+    if n <= 1: return S.Zero
+
+    return Add(*[A(N+n-1-k)*p[k] for k in range(n)])
+
+
+@public
+def rationalize(x, maxcoeff=10000):
+    """
+    Helps identifying a rational number from a float (or mpmath.mpf) value by
+    using a continued fraction. The algorithm stops as soon as a large partial
+    quotient is detected (greater than 10000 by default).
+
+    Examples
+    ========
+
+    >>> from sympy.concrete.guess import rationalize
+    >>> from mpmath import cos, pi
+    >>> rationalize(cos(pi/3))
+    1/2
+
+    >>> from mpmath import mpf
+    >>> rationalize(mpf("0.333333333333333"))
+    1/3
+
+    While the function is rather intended to help 'identifying' rational
+    values, it may be used in some cases for approximating real numbers.
+    (Though other functions may be more relevant in that case.)
+
+    >>> rationalize(pi, maxcoeff = 250)
+    355/113
+
+    See Also
+    ========
+
+    Several other methods can approximate a real number as a rational, like:
+
+      * fractions.Fraction.from_decimal
+      * fractions.Fraction.from_float
+      * mpmath.identify
+      * mpmath.pslq by using the following syntax: mpmath.pslq([x, 1])
+      * mpmath.findpoly by using the following syntax: mpmath.findpoly(x, 1)
+      * sympy.simplify.nsimplify (which is a more general function)
+
+    The main difference between the current function and all these variants is
+    that control focuses on magnitude of partial quotients here rather than on
+    global precision of the approximation. If the real is "known to be" a
+    rational number, the current function should be able to detect it correctly
+    with the default settings even when denominator is great (unless its
+    expansion contains unusually big partial quotients) which may occur
+    when studying sequences of increasing numbers. If the user cares more
+    on getting simple fractions, other methods may be more convenient.
+
+    """
+    p0, p1 = 0, 1
+    q0, q1 = 1, 0
+    a = floor(x)
+    while a < maxcoeff or q1==0:
+        p = a*p1 + p0
+        q = a*q1 + q0
+        p0, p1 = p1, p
+        q0, q1 = q1, q
+        if x==a: break
+        x = 1/(x-a)
+        a = floor(x)
+    return sympify(p) / q
+
+
+@public
+def guess_generating_function_rational(v, X=Symbol('x')):
+    """
+    Tries to "guess" a rational generating function for a sequence of rational
+    numbers v.
+
+    Examples
+    ========
+
+    >>> from sympy.concrete.guess import guess_generating_function_rational
+    >>> from sympy import fibonacci
+    >>> l = [fibonacci(k) for k in range(5,15)]
+    >>> guess_generating_function_rational(l)
+    (3*x + 5)/(-x**2 - x + 1)
+
+    See Also
+    ========
+
+    sympy.series.approximants
+    mpmath.pade
+
+    """
+    #   a) compute the denominator as q
+    q = find_simple_recurrence_vector(v)
+    n = len(q)
+    if n <= 1: return None
+    #   b) compute the numerator as p
+    p = [sum(v[i-k]*q[k] for k in range(min(i+1, n)))
+            for i in range(len(v)>>1)]
+    return (sum(p[k]*X**k for k in range(len(p)))
+            / sum(q[k]*X**k for k in range(n)))
+
+
+@public
+def guess_generating_function(v, X=Symbol('x'), types=['all'], maxsqrtn=2):
+    """
+    Tries to "guess" a generating function for a sequence of rational numbers v.
+    Only a few patterns are implemented yet.
+
+    Explanation
+    ===========
+
+    The function returns a dictionary where keys are the name of a given type of
+    generating function. Six types are currently implemented:
+
+         type  |  formal definition
+        -------+----------------------------------------------------------------
+        ogf    | f(x) = Sum(            a_k * x^k       ,  k: 0..infinity )
+        egf    | f(x) = Sum(            a_k * x^k / k!  ,  k: 0..infinity )
+        lgf    | f(x) = Sum( (-1)^(k+1) a_k * x^k / k   ,  k: 1..infinity )
+               |        (with initial index being hold as 1 rather than 0)
+        hlgf   | f(x) = Sum(            a_k * x^k / k   ,  k: 1..infinity )
+               |        (with initial index being hold as 1 rather than 0)
+        lgdogf | f(x) = derivate( log(Sum( a_k * x^k, k: 0..infinity )), x)
+        lgdegf | f(x) = derivate( log(Sum( a_k * x^k / k!, k: 0..infinity )), x)
+
+    In order to spare time, the user can select only some types of generating
+    functions (default being ['all']). While forgetting to use a list in the
+    case of a single type may seem to work most of the time as in: types='ogf'
+    this (convenient) syntax may lead to unexpected extra results in some cases.
+
+    Discarding a type when calling the function does not mean that the type will
+    not be present in the returned dictionary; it only means that no extra
+    computation will be performed for that type, but the function may still add
+    it in the result when it can be easily converted from another type.
+
+    Two generating functions (lgdogf and lgdegf) are not even computed if the
+    initial term of the sequence is 0; it may be useful in that case to try
+    again after having removed the leading zeros.
+
+    Examples
+    ========
+
+    >>> from sympy.concrete.guess import guess_generating_function as ggf
+    >>> ggf([k+1 for k in range(12)], types=['ogf', 'lgf', 'hlgf'])
+    {'hlgf': 1/(1 - x), 'lgf': 1/(x + 1), 'ogf': 1/(x**2 - 2*x + 1)}
+
+    >>> from sympy import sympify
+    >>> l = sympify("[3/2, 11/2, 0, -121/2, -363/2, 121]")
+    >>> ggf(l)
+    {'ogf': (x + 3/2)/(11*x**2 - 3*x + 1)}
+
+    >>> from sympy import fibonacci
+    >>> ggf([fibonacci(k) for k in range(5, 15)], types=['ogf'])
+    {'ogf': (3*x + 5)/(-x**2 - x + 1)}
+
+    >>> from sympy import factorial
+    >>> ggf([factorial(k) for k in range(12)], types=['ogf', 'egf', 'lgf'])
+    {'egf': 1/(1 - x)}
+
+    >>> ggf([k+1 for k in range(12)], types=['egf'])
+    {'egf': (x + 1)*exp(x), 'lgdegf': (x + 2)/(x + 1)}
+
+    N-th root of a rational function can also be detected (below is an example
+    coming from the sequence A108626 from https://oeis.org).
+    The greatest n-th root to be tested is specified as maxsqrtn (default 2).
+
+    >>> ggf([1, 2, 5, 14, 41, 124, 383, 1200, 3799, 12122, 38919])['ogf']
+    sqrt(1/(x**4 + 2*x**2 - 4*x + 1))
+
+    References
+    ==========
+
+    .. [1] "Concrete Mathematics", R.L. Graham, D.E. Knuth, O. Patashnik
+    .. [2] https://oeis.org/wiki/Generating_functions
+
+    """
+    # List of all types of all g.f. known by the algorithm
+    if 'all' in types:
+        types = ('ogf', 'egf', 'lgf', 'hlgf', 'lgdogf', 'lgdegf')
+
+    result = {}
+
+    # Ordinary Generating Function (ogf)
+    if 'ogf' in types:
+        # Perform some convolutions of the sequence with itself
+        t = [1] + [0]*(len(v) - 1)
+        for d in range(max(1, maxsqrtn)):
+            t = [sum(t[n-i]*v[i] for i in range(n+1)) for n in range(len(v))]
+            g = guess_generating_function_rational(t, X=X)
+            if g:
+                result['ogf'] = g**Rational(1, d+1)
+                break
+
+    # Exponential Generating Function (egf)
+    if 'egf' in types:
+        # Transform sequence (division by factorial)
+        w, f = [], S.One
+        for i, k in enumerate(v):
+            f *= i if i else 1
+            w.append(k/f)
+        # Perform some convolutions of the sequence with itself
+        t = [1] + [0]*(len(w) - 1)
+        for d in range(max(1, maxsqrtn)):
+            t = [sum(t[n-i]*w[i] for i in range(n+1)) for n in range(len(w))]
+            g = guess_generating_function_rational(t, X=X)
+            if g:
+                result['egf'] = g**Rational(1, d+1)
+                break
+
+    # Logarithmic Generating Function (lgf)
+    if 'lgf' in types:
+        # Transform sequence (multiplication by (-1)^(n+1) / n)
+        w, f = [], S.NegativeOne
+        for i, k in enumerate(v):
+            f = -f
+            w.append(f*k/Integer(i+1))
+        # Perform some convolutions of the sequence with itself
+        t = [1] + [0]*(len(w) - 1)
+        for d in range(max(1, maxsqrtn)):
+            t = [sum(t[n-i]*w[i] for i in range(n+1)) for n in range(len(w))]
+            g = guess_generating_function_rational(t, X=X)
+            if g:
+                result['lgf'] = g**Rational(1, d+1)
+                break
+
+    # Hyperbolic logarithmic Generating Function (hlgf)
+    if 'hlgf' in types:
+        # Transform sequence (division by n+1)
+        w = []
+        for i, k in enumerate(v):
+            w.append(k/Integer(i+1))
+        # Perform some convolutions of the sequence with itself
+        t = [1] + [0]*(len(w) - 1)
+        for d in range(max(1, maxsqrtn)):
+            t = [sum(t[n-i]*w[i] for i in range(n+1)) for n in range(len(w))]
+            g = guess_generating_function_rational(t, X=X)
+            if g:
+                result['hlgf'] = g**Rational(1, d+1)
+                break
+
+    # Logarithmic derivative of ordinary generating Function (lgdogf)
+    if v[0] != 0 and ('lgdogf' in types
+                       or ('ogf' in types and 'ogf' not in result)):
+        # Transform sequence by computing f'(x)/f(x)
+        # because log(f(x)) = integrate( f'(x)/f(x) )
+        a, w = sympify(v[0]), []
+        for n in range(len(v)-1):
+            w.append(
+               (v[n+1]*(n+1) - sum(w[-i-1]*v[i+1] for i in range(n)))/a)
+        # Perform some convolutions of the sequence with itself
+        t = [1] + [0]*(len(w) - 1)
+        for d in range(max(1, maxsqrtn)):
+            t = [sum(t[n-i]*w[i] for i in range(n+1)) for n in range(len(w))]
+            g = guess_generating_function_rational(t, X=X)
+            if g:
+                result['lgdogf'] = g**Rational(1, d+1)
+                if 'ogf' not in result:
+                    result['ogf'] = exp(integrate(result['lgdogf'], X))
+                break
+
+    # Logarithmic derivative of exponential generating Function (lgdegf)
+    if v[0] != 0 and ('lgdegf' in types
+                       or ('egf' in types and 'egf' not in result)):
+        # Transform sequence / step 1 (division by factorial)
+        z, f = [], S.One
+        for i, k in enumerate(v):
+            f *= i if i else 1
+            z.append(k/f)
+        # Transform sequence / step 2 by computing f'(x)/f(x)
+        # because log(f(x)) = integrate( f'(x)/f(x) )
+        a, w = z[0], []
+        for n in range(len(z)-1):
+            w.append(
+               (z[n+1]*(n+1) - sum(w[-i-1]*z[i+1] for i in range(n)))/a)
+        # Perform some convolutions of the sequence with itself
+        t = [1] + [0]*(len(w) - 1)
+        for d in range(max(1, maxsqrtn)):
+            t = [sum(t[n-i]*w[i] for i in range(n+1)) for n in range(len(w))]
+            g = guess_generating_function_rational(t, X=X)
+            if g:
+                result['lgdegf'] = g**Rational(1, d+1)
+                if 'egf' not in result:
+                    result['egf'] = exp(integrate(result['lgdegf'], X))
+                break
+
+    return result
+
+
+@public
+def guess(l, all=False, evaluate=True, niter=2, variables=None):
+    """
+    This function is adapted from the Rate.m package for Mathematica
+    written by Christian Krattenthaler.
+    It tries to guess a formula from a given sequence of rational numbers.
+
+    Explanation
+    ===========
+
+    In order to speed up the process, the 'all' variable is set to False by
+    default, stopping the computation as some results are returned during an
+    iteration; the variable can be set to True if more iterations are needed
+    (other formulas may be found; however they may be equivalent to the first
+    ones).
+
+    Another option is the 'evaluate' variable (default is True); setting it
+    to False will leave the involved products unevaluated.
+
+    By default, the number of iterations is set to 2 but a greater value (up
+    to len(l)-1) can be specified with the optional 'niter' variable.
+    More and more convoluted results are found when the order of the
+    iteration gets higher:
+
+      * first iteration returns polynomial or rational functions;
+      * second iteration returns products of rising factorials and their
+        inverses;
+      * third iteration returns products of products of rising factorials
+        and their inverses;
+      * etc.
+
+    The returned formulas contain symbols i0, i1, i2, ... where the main
+    variables is i0 (and auxiliary variables are i1, i2, ...). A list of
+    other symbols can be provided in the 'variables' option; the length of
+    the least should be the value of 'niter' (more is acceptable but only
+    the first symbols will be used); in this case, the main variable will be
+    the first symbol in the list.
+
+    Examples
+    ========
+
+    >>> from sympy.concrete.guess import guess
+    >>> guess([1,2,6,24,120], evaluate=False)
+    [Product(i1 + 1, (i1, 1, i0 - 1))]
+
+    >>> from sympy import symbols
+    >>> r = guess([1,2,7,42,429,7436,218348,10850216], niter=4)
+    >>> i0 = symbols("i0")
+    >>> [r[0].subs(i0,n).doit() for n in range(1,10)]
+    [1, 2, 7, 42, 429, 7436, 218348, 10850216, 911835460]
+    """
+    if any(a==0 for a in l[:-1]):
+        return []
+    N = len(l)
+    niter = min(N-1, niter)
+    myprod = product if evaluate else Product
+    g = []
+    res = []
+    if variables is None:
+        symb = symbols('i:'+str(niter))
+    else:
+        symb = variables
+    for k, s in enumerate(symb):
+        g.append(l)
+        n, r = len(l), []
+        for i in range(n-2-1, -1, -1):
+            ri = rinterp(enumerate(g[k][:-1], start=1), i, X=s)
+            if ((denom(ri).subs({s:n}) != 0)
+                    and (ri.subs({s:n}) - g[k][-1] == 0)
+                    and ri not in r):
+              r.append(ri)
+        if r:
+            for i in range(k-1, -1, -1):
+                r = [g[i][0]
+                      * myprod(v, (symb[i+1], 1, symb[i]-1)) for v in r]
+            if not all: return r
+            res += r
+        l = [Rational(l[i+1], l[i]) for i in range(N-k-1)]
+    return res

lib/python3.12/site-packages/sympy/concrete/products.py

@@ -0,0 +1,610 @@
+from typing import Tuple as tTuple
+
+from .expr_with_intlimits import ExprWithIntLimits
+from .summations import Sum, summation, _dummy_with_inherited_properties_concrete
+from sympy.core.expr import Expr
+from sympy.core.exprtools import factor_terms
+from sympy.core.function import Derivative
+from sympy.core.mul import Mul
+from sympy.core.singleton import S
+from sympy.core.symbol import Dummy, Symbol
+from sympy.functions.combinatorial.factorials import RisingFactorial
+from sympy.functions.elementary.exponential import exp, log
+from sympy.functions.special.tensor_functions import KroneckerDelta
+from sympy.polys import quo, roots
+
+
+class Product(ExprWithIntLimits):
+    r"""
+    Represents unevaluated products.
+
+    Explanation
+    ===========
+
+    ``Product`` represents a finite or infinite product, with the first
+    argument being the general form of terms in the series, and the second
+    argument being ``(dummy_variable, start, end)``, with ``dummy_variable``
+    taking all integer values from ``start`` through ``end``. In accordance
+    with long-standing mathematical convention, the end term is included in
+    the product.
+
+    Finite products
+    ===============
+
+    For finite products (and products with symbolic limits assumed to be finite)
+    we follow the analogue of the summation convention described by Karr [1],
+    especially definition 3 of section 1.4. The product:
+
+    .. math::
+
+        \prod_{m \leq i < n} f(i)
+
+    has *the obvious meaning* for `m < n`, namely:
+
+    .. math::
+
+        \prod_{m \leq i < n} f(i) = f(m) f(m+1) \cdot \ldots \cdot f(n-2) f(n-1)
+
+    with the upper limit value `f(n)` excluded. The product over an empty set is
+    one if and only if `m = n`:
+
+    .. math::
+
+        \prod_{m \leq i < n} f(i) = 1  \quad \mathrm{for} \quad  m = n
+
+    Finally, for all other products over empty sets we assume the following
+    definition:
+
+    .. math::
+
+        \prod_{m \leq i < n} f(i) = \frac{1}{\prod_{n \leq i < m} f(i)}  \quad \mathrm{for} \quad  m > n
+
+    It is important to note that above we define all products with the upper
+    limit being exclusive. This is in contrast to the usual mathematical notation,
+    but does not affect the product convention. Indeed we have:
+
+    .. math::
+
+        \prod_{m \leq i < n} f(i) = \prod_{i = m}^{n - 1} f(i)
+
+    where the difference in notation is intentional to emphasize the meaning,
+    with limits typeset on the top being inclusive.
+
+    Examples
+    ========
+
+    >>> from sympy.abc import a, b, i, k, m, n, x
+    >>> from sympy import Product, oo
+    >>> Product(k, (k, 1, m))
+    Product(k, (k, 1, m))
+    >>> Product(k, (k, 1, m)).doit()
+    factorial(m)
+    >>> Product(k**2,(k, 1, m))
+    Product(k**2, (k, 1, m))
+    >>> Product(k**2,(k, 1, m)).doit()
+    factorial(m)**2
+
+    Wallis' product for pi:
+
+    >>> W = Product(2*i/(2*i-1) * 2*i/(2*i+1), (i, 1, oo))
+    >>> W
+    Product(4*i**2/((2*i - 1)*(2*i + 1)), (i, 1, oo))
+
+    Direct computation currently fails:
+
+    >>> W.doit()
+    Product(4*i**2/((2*i - 1)*(2*i + 1)), (i, 1, oo))
+
+    But we can approach the infinite product by a limit of finite products:
+
+    >>> from sympy import limit
+    >>> W2 = Product(2*i/(2*i-1)*2*i/(2*i+1), (i, 1, n))
+    >>> W2
+    Product(4*i**2/((2*i - 1)*(2*i + 1)), (i, 1, n))
+    >>> W2e = W2.doit()
+    >>> W2e
+    4**n*factorial(n)**2/(2**(2*n)*RisingFactorial(1/2, n)*RisingFactorial(3/2, n))
+    >>> limit(W2e, n, oo)
+    pi/2
+
+    By the same formula we can compute sin(pi/2):
+
+    >>> from sympy import combsimp, pi, gamma, simplify
+    >>> P = pi * x * Product(1 - x**2/k**2, (k, 1, n))
+    >>> P = P.subs(x, pi/2)
+    >>> P
+    pi**2*Product(1 - pi**2/(4*k**2), (k, 1, n))/2
+    >>> Pe = P.doit()
+    >>> Pe
+    pi**2*RisingFactorial(1 - pi/2, n)*RisingFactorial(1 + pi/2, n)/(2*factorial(n)**2)
+    >>> limit(Pe, n, oo).gammasimp()
+    sin(pi**2/2)
+    >>> Pe.rewrite(gamma)
+    (-1)**n*pi**2*gamma(pi/2)*gamma(n + 1 + pi/2)/(2*gamma(1 + pi/2)*gamma(-n + pi/2)*gamma(n + 1)**2)
+
+    Products with the lower limit being larger than the upper one:
+
+    >>> Product(1/i, (i, 6, 1)).doit()
+    120
+    >>> Product(i, (i, 2, 5)).doit()
+    120
+
+    The empty product:
+
+    >>> Product(i, (i, n, n-1)).doit()
+    1
+
+    An example showing that the symbolic result of a product is still
+    valid for seemingly nonsensical values of the limits. Then the Karr
+    convention allows us to give a perfectly valid interpretation to
+    those products by interchanging the limits according to the above rules:
+
+    >>> P = Product(2, (i, 10, n)).doit()
+    >>> P
+    2**(n - 9)
+    >>> P.subs(n, 5)
+    1/16
+    >>> Product(2, (i, 10, 5)).doit()
+    1/16
+    >>> 1/Product(2, (i, 6, 9)).doit()
+    1/16
+
+    An explicit example of the Karr summation convention applied to products:
+
+    >>> P1 = Product(x, (i, a, b)).doit()
+    >>> P1
+    x**(-a + b + 1)
+    >>> P2 = Product(x, (i, b+1, a-1)).doit()
+    >>> P2
+    x**(a - b - 1)
+    >>> simplify(P1 * P2)
+    1
+
+    And another one:
+
+    >>> P1 = Product(i, (i, b, a)).doit()
+    >>> P1
+    RisingFactorial(b, a - b + 1)
+    >>> P2 = Product(i, (i, a+1, b-1)).doit()
+    >>> P2
+    RisingFactorial(a + 1, -a + b - 1)
+    >>> P1 * P2
+    RisingFactorial(b, a - b + 1)*RisingFactorial(a + 1, -a + b - 1)
+    >>> combsimp(P1 * P2)
+    1
+
+    See Also
+    ========
+
+    Sum, summation
+    product
+
+    References
+    ==========
+
+    .. [1] Michael Karr, "Summation in Finite Terms", Journal of the ACM,
+           Volume 28 Issue 2, April 1981, Pages 305-350
+           https://dl.acm.org/doi/10.1145/322248.322255
+    .. [2] https://en.wikipedia.org/wiki/Multiplication#Capital_Pi_notation
+    .. [3] https://en.wikipedia.org/wiki/Empty_product
+    """
+
+    __slots__ = ()
+
+    limits: tTuple[tTuple[Symbol, Expr, Expr]]
+
+    def __new__(cls, function, *symbols, **assumptions):
+        obj = ExprWithIntLimits.__new__(cls, function, *symbols, **assumptions)
+        return obj
+
+    def _eval_rewrite_as_Sum(self, *args, **kwargs):
+        return exp(Sum(log(self.function), *self.limits))
+
+    @property
+    def term(self):
+        return self._args[0]
+    function = term
+
+    def _eval_is_zero(self):
+        if self.has_empty_sequence:
+            return False
+
+        z = self.term.is_zero
+        if z is True:
+            return True
+        if self.has_finite_limits:
+            # A Product is zero only if its term is zero assuming finite limits.
+            return z
+
+    def _eval_is_extended_real(self):
+        if self.has_empty_sequence:
+            return True
+
+        return self.function.is_extended_real
+
+    def _eval_is_positive(self):
+        if self.has_empty_sequence:
+            return True
+        if self.function.is_positive and self.has_finite_limits:
+            return True
+
+    def _eval_is_nonnegative(self):
+        if self.has_empty_sequence:
+            return True
+        if self.function.is_nonnegative and self.has_finite_limits:
+            return True
+
+    def _eval_is_extended_nonnegative(self):
+        if self.has_empty_sequence:
+            return True
+        if self.function.is_extended_nonnegative:
+            return True
+
+    def _eval_is_extended_nonpositive(self):
+        if self.has_empty_sequence:
+            return True
+
+    def _eval_is_finite(self):
+        if self.has_finite_limits and self.function.is_finite:
+            return True
+
+    def doit(self, **hints):
+        # first make sure any definite limits have product
+        # variables with matching assumptions
+        reps = {}
+        for xab in self.limits:
+            d = _dummy_with_inherited_properties_concrete(xab)
+            if d:
+                reps[xab[0]] = d
+        if reps:
+            undo = {v: k for k, v in reps.items()}
+            did = self.xreplace(reps).doit(**hints)
+            if isinstance(did, tuple):  # when separate=True
+                did = tuple([i.xreplace(undo) for i in did])
+            else:
+                did = did.xreplace(undo)
+            return did
+
+        from sympy.simplify.powsimp import powsimp
+        f = self.function
+        for index, limit in enumerate(self.limits):
+            i, a, b = limit
+            dif = b - a
+            if dif.is_integer and dif.is_negative:
+                a, b = b + 1, a - 1
+                f = 1 / f
+
+            g = self._eval_product(f, (i, a, b))
+            if g in (None, S.NaN):
+                return self.func(powsimp(f), *self.limits[index:])
+            else:
+                f = g
+
+        if hints.get('deep', True):
+            return f.doit(**hints)
+        else:
+            return powsimp(f)
+
+    def _eval_adjoint(self):
+        if self.is_commutative:
+            return self.func(self.function.adjoint(), *self.limits)
+        return None
+
+    def _eval_conjugate(self):
+        return self.func(self.function.conjugate(), *self.limits)
+
+    def _eval_product(self, term, limits):
+
+        (k, a, n) = limits
+
+        if k not in term.free_symbols:
+            if (term - 1).is_zero:
+                return S.One
+            return term**(n - a + 1)
+
+        if a == n:
+            return term.subs(k, a)
+
+        from .delta import deltaproduct, _has_simple_delta
+        if term.has(KroneckerDelta) and _has_simple_delta(term, limits[0]):
+            return deltaproduct(term, limits)
+
+        dif = n - a
+        definite = dif.is_Integer
+        if definite and (dif < 100):
+            return self._eval_product_direct(term, limits)
+
+        elif term.is_polynomial(k):
+            poly = term.as_poly(k)
+
+            A = B = Q = S.One
+
+            all_roots = roots(poly)
+
+            M = 0
+            for r, m in all_roots.items():
+                M += m
+                A *= RisingFactorial(a - r, n - a + 1)**m
+                Q *= (n - r)**m
+
+            if M < poly.degree():
+                arg = quo(poly, Q.as_poly(k))
+                B = self.func(arg, (k, a, n)).doit()
+
+            return poly.LC()**(n - a + 1) * A * B
+
+        elif term.is_Add:
+            factored = factor_terms(term, fraction=True)
+            if factored.is_Mul:
+                return self._eval_product(factored, (k, a, n))
+
+        elif term.is_Mul:
+            # Factor in part without the summation variable and part with
+            without_k, with_k = term.as_coeff_mul(k)
+
+            if len(with_k) >= 2:
+                # More than one term including k, so still a multiplication
+                exclude, include = [], []
+                for t in with_k:
+                    p = self._eval_product(t, (k, a, n))
+
+                    if p is not None:
+                        exclude.append(p)
+                    else:
+                        include.append(t)
+
+                if not exclude:
+                    return None
+                else:
+                    arg = term._new_rawargs(*include)
+                    A = Mul(*exclude)
+                    B = self.func(arg, (k, a, n)).doit()
+                    return without_k**(n - a + 1)*A * B
+            else:
+                # Just a single term
+                p = self._eval_product(with_k[0], (k, a, n))
+                if p is None:
+                    p = self.func(with_k[0], (k, a, n)).doit()
+                return without_k**(n - a + 1)*p
+
+
+        elif term.is_Pow:
+            if not term.base.has(k):
+                s = summation(term.exp, (k, a, n))
+
+                return term.base**s
+            elif not term.exp.has(k):
+                p = self._eval_product(term.base, (k, a, n))
+
+                if p is not None:
+                    return p**term.exp
+
+        elif isinstance(term, Product):
+            evaluated = term.doit()
+            f = self._eval_product(evaluated, limits)
+            if f is None:
+                return self.func(evaluated, limits)
+            else:
+                return f
+
+        if definite:
+            return self._eval_product_direct(term, limits)
+
+    def _eval_simplify(self, **kwargs):
+        from sympy.simplify.simplify import product_simplify
+        rv = product_simplify(self, **kwargs)
+        return rv.doit() if kwargs['doit'] else rv
+
+    def _eval_transpose(self):
+        if self.is_commutative:
+            return self.func(self.function.transpose(), *self.limits)
+        return None
+
+    def _eval_product_direct(self, term, limits):
+        (k, a, n) = limits
+        return Mul(*[term.subs(k, a + i) for i in range(n - a + 1)])
+
+    def _eval_derivative(self, x):
+        if isinstance(x, Symbol) and x not in self.free_symbols:
+            return S.Zero
+        f, limits = self.function, list(self.limits)
+        limit = limits.pop(-1)
+        if limits:
+            f = self.func(f, *limits)
+        i, a, b = limit
+        if x in a.free_symbols or x in b.free_symbols:
+            return None
+        h = Dummy()
+        rv = Sum( Product(f, (i, a, h - 1)) * Product(f, (i, h + 1, b)) * Derivative(f, x, evaluate=True).subs(i, h), (h, a, b))
+        return rv
+
+    def is_convergent(self):
+        r"""
+        See docs of :obj:`.Sum.is_convergent()` for explanation of convergence
+        in SymPy.
+
+        Explanation
+        ===========
+
+        The infinite product:
+
+        .. math::
+
+            \prod_{1 \leq i < \infty} f(i)
+
+        is defined by the sequence of partial products:
+
+        .. math::
+
+            \prod_{i=1}^{n} f(i) = f(1) f(2) \cdots f(n)
+
+        as n increases without bound. The product converges to a non-zero
+        value if and only if the sum:
+
+        .. math::
+
+            \sum_{1 \leq i < \infty} \log{f(n)}
+
+        converges.
+
+        Examples
+        ========
+
+        >>> from sympy import Product, Symbol, cos, pi, exp, oo
+        >>> n = Symbol('n', integer=True)
+        >>> Product(n/(n + 1), (n, 1, oo)).is_convergent()
+        False
+        >>> Product(1/n**2, (n, 1, oo)).is_convergent()
+        False
+        >>> Product(cos(pi/n), (n, 1, oo)).is_convergent()
+        True
+        >>> Product(exp(-n**2), (n, 1, oo)).is_convergent()
+        False
+
+        References
+        ==========
+
+        .. [1] https://en.wikipedia.org/wiki/Infinite_product
+        """
+        sequence_term = self.function
+        log_sum = log(sequence_term)
+        lim = self.limits
+        try:
+            is_conv = Sum(log_sum, *lim).is_convergent()
+        except NotImplementedError:
+            if Sum(sequence_term - 1, *lim).is_absolutely_convergent() is S.true:
+                return S.true
+            raise NotImplementedError("The algorithm to find the product convergence of %s "
+                                        "is not yet implemented" % (sequence_term))
+        return is_conv
+
+    def reverse_order(expr, *indices):
+        """
+        Reverse the order of a limit in a Product.
+
+        Explanation
+        ===========
+
+        ``reverse_order(expr, *indices)`` reverses some limits in the expression
+        ``expr`` which can be either a ``Sum`` or a ``Product``. The selectors in
+        the argument ``indices`` specify some indices whose limits get reversed.
+        These selectors are either variable names or numerical indices counted
+        starting from the inner-most limit tuple.
+
+        Examples
+        ========
+
+        >>> from sympy import gamma, Product, simplify, Sum
+        >>> from sympy.abc import x, y, a, b, c, d
+        >>> P = Product(x, (x, a, b))
+        >>> Pr = P.reverse_order(x)
+        >>> Pr
+        Product(1/x, (x, b + 1, a - 1))
+        >>> Pr = Pr.doit()
+        >>> Pr
+        1/RisingFactorial(b + 1, a - b - 1)
+        >>> simplify(Pr.rewrite(gamma))
+        Piecewise((gamma(b + 1)/gamma(a), b > -1), ((-1)**(-a + b + 1)*gamma(1 - a)/gamma(-b), True))
+        >>> P = P.doit()
+        >>> P
+        RisingFactorial(a, -a + b + 1)
+        >>> simplify(P.rewrite(gamma))
+        Piecewise((gamma(b + 1)/gamma(a), a > 0), ((-1)**(-a + b + 1)*gamma(1 - a)/gamma(-b), True))
+
+        While one should prefer variable names when specifying which limits
+        to reverse, the index counting notation comes in handy in case there
+        are several symbols with the same name.
+
+        >>> S = Sum(x*y, (x, a, b), (y, c, d))
+        >>> S
+        Sum(x*y, (x, a, b), (y, c, d))
+        >>> S0 = S.reverse_order(0)
+        >>> S0
+        Sum(-x*y, (x, b + 1, a - 1), (y, c, d))
+        >>> S1 = S0.reverse_order(1)
+        >>> S1
+        Sum(x*y, (x, b + 1, a - 1), (y, d + 1, c - 1))
+
+        Of course we can mix both notations:
+
+        >>> Sum(x*y, (x, a, b), (y, 2, 5)).reverse_order(x, 1)
+        Sum(x*y, (x, b + 1, a - 1), (y, 6, 1))
+        >>> Sum(x*y, (x, a, b), (y, 2, 5)).reverse_order(y, x)
+        Sum(x*y, (x, b + 1, a - 1), (y, 6, 1))
+
+        See Also
+        ========
+
+        sympy.concrete.expr_with_intlimits.ExprWithIntLimits.index,
+        reorder_limit,
+        sympy.concrete.expr_with_intlimits.ExprWithIntLimits.reorder
+
+        References
+        ==========
+
+        .. [1] Michael Karr, "Summation in Finite Terms", Journal of the ACM,
+               Volume 28 Issue 2, April 1981, Pages 305-350
+               https://dl.acm.org/doi/10.1145/322248.322255
+
+        """
+        l_indices = list(indices)
+
+        for i, indx in enumerate(l_indices):
+            if not isinstance(indx, int):
+                l_indices[i] = expr.index(indx)
+
+        e = 1
+        limits = []
+        for i, limit in enumerate(expr.limits):
+            l = limit
+            if i in l_indices:
+                e = -e
+                l = (limit[0], limit[2] + 1, limit[1] - 1)
+            limits.append(l)
+
+        return Product(expr.function ** e, *limits)
+
+
+def product(*args, **kwargs):
+    r"""
+    Compute the product.
+
+    Explanation
+    ===========
+
+    The notation for symbols is similar to the notation used in Sum or
+    Integral. product(f, (i, a, b)) computes the product of f with
+    respect to i from a to b, i.e.,
+
+    ::
+
+                                     b
+                                   _____
+        product(f(n), (i, a, b)) = |   | f(n)
+                                   |   |
+                                   i = a
+
+    If it cannot compute the product, it returns an unevaluated Product object.
+    Repeated products can be computed by introducing additional symbols tuples::
+
+    Examples
+    ========
+
+    >>> from sympy import product, symbols
+    >>> i, n, m, k = symbols('i n m k', integer=True)
+
+    >>> product(i, (i, 1, k))
+    factorial(k)
+    >>> product(m, (i, 1, k))
+    m**k
+    >>> product(i, (i, 1, k), (k, 1, n))
+    Product(factorial(k), (k, 1, n))
+
+    """
+
+    prod = Product(*args, **kwargs)
+
+    if isinstance(prod, Product):
+        return prod.doit(deep=False)
+    else:
+        return prod

lib/python3.12/site-packages/sympy/concrete/summations.py

@@ -0,0 +1,1646 @@
+from typing import Tuple as tTuple
+
+from sympy.calculus.singularities import is_decreasing
+from sympy.calculus.accumulationbounds import AccumulationBounds
+from .expr_with_intlimits import ExprWithIntLimits
+from .expr_with_limits import AddWithLimits
+from .gosper import gosper_sum
+from sympy.core.expr import Expr
+from sympy.core.add import Add
+from sympy.core.containers import Tuple
+from sympy.core.function import Derivative, expand
+from sympy.core.mul import Mul
+from sympy.core.numbers import Float, _illegal
+from sympy.core.relational import Eq
+from sympy.core.singleton import S
+from sympy.core.sorting import ordered
+from sympy.core.symbol import Dummy, Wild, Symbol, symbols
+from sympy.functions.combinatorial.factorials import factorial
+from sympy.functions.combinatorial.numbers import bernoulli, harmonic
+from sympy.functions.elementary.exponential import exp, log
+from sympy.functions.elementary.piecewise import Piecewise
+from sympy.functions.elementary.trigonometric import cot, csc
+from sympy.functions.special.hyper import hyper
+from sympy.functions.special.tensor_functions import KroneckerDelta
+from sympy.functions.special.zeta_functions import zeta
+from sympy.integrals.integrals import Integral
+from sympy.logic.boolalg import And
+from sympy.polys.partfrac import apart
+from sympy.polys.polyerrors import PolynomialError, PolificationFailed
+from sympy.polys.polytools import parallel_poly_from_expr, Poly, factor
+from sympy.polys.rationaltools import together
+from sympy.series.limitseq import limit_seq
+from sympy.series.order import O
+from sympy.series.residues import residue
+from sympy.sets.sets import FiniteSet, Interval
+from sympy.utilities.iterables import sift
+import itertools
+
+
+class Sum(AddWithLimits, ExprWithIntLimits):
+    r"""
+    Represents unevaluated summation.
+
+    Explanation
+    ===========
+
+    ``Sum`` represents a finite or infinite series, with the first argument
+    being the general form of terms in the series, and the second argument
+    being ``(dummy_variable, start, end)``, with ``dummy_variable`` taking
+    all integer values from ``start`` through ``end``. In accordance with
+    long-standing mathematical convention, the end term is included in the
+    summation.
+
+    Finite sums
+    ===========
+
+    For finite sums (and sums with symbolic limits assumed to be finite) we
+    follow the summation convention described by Karr [1], especially
+    definition 3 of section 1.4. The sum:
+
+    .. math::
+
+        \sum_{m \leq i < n} f(i)
+
+    has *the obvious meaning* for `m < n`, namely:
+
+    .. math::
+
+        \sum_{m \leq i < n} f(i) = f(m) + f(m+1) + \ldots + f(n-2) + f(n-1)
+
+    with the upper limit value `f(n)` excluded. The sum over an empty set is
+    zero if and only if `m = n`:
+
+    .. math::
+
+        \sum_{m \leq i < n} f(i) = 0  \quad \mathrm{for} \quad  m = n
+
+    Finally, for all other sums over empty sets we assume the following
+    definition:
+
+    .. math::
+
+        \sum_{m \leq i < n} f(i) = - \sum_{n \leq i < m} f(i)  \quad \mathrm{for} \quad  m > n
+
+    It is important to note that Karr defines all sums with the upper
+    limit being exclusive. This is in contrast to the usual mathematical notation,
+    but does not affect the summation convention. Indeed we have:
+
+    .. math::
+
+        \sum_{m \leq i < n} f(i) = \sum_{i = m}^{n - 1} f(i)
+
+    where the difference in notation is intentional to emphasize the meaning,
+    with limits typeset on the top being inclusive.
+
+    Examples
+    ========
+
+    >>> from sympy.abc import i, k, m, n, x
+    >>> from sympy import Sum, factorial, oo, IndexedBase, Function
+    >>> Sum(k, (k, 1, m))
+    Sum(k, (k, 1, m))
+    >>> Sum(k, (k, 1, m)).doit()
+    m**2/2 + m/2
+    >>> Sum(k**2, (k, 1, m))
+    Sum(k**2, (k, 1, m))
+    >>> Sum(k**2, (k, 1, m)).doit()
+    m**3/3 + m**2/2 + m/6
+    >>> Sum(x**k, (k, 0, oo))
+    Sum(x**k, (k, 0, oo))
+    >>> Sum(x**k, (k, 0, oo)).doit()
+    Piecewise((1/(1 - x), Abs(x) < 1), (Sum(x**k, (k, 0, oo)), True))
+    >>> Sum(x**k/factorial(k), (k, 0, oo)).doit()
+    exp(x)
+
+    Here are examples to do summation with symbolic indices.  You
+    can use either Function of IndexedBase classes:
+
+    >>> f = Function('f')
+    >>> Sum(f(n), (n, 0, 3)).doit()
+    f(0) + f(1) + f(2) + f(3)
+    >>> Sum(f(n), (n, 0, oo)).doit()
+    Sum(f(n), (n, 0, oo))
+    >>> f = IndexedBase('f')
+    >>> Sum(f[n]**2, (n, 0, 3)).doit()
+    f[0]**2 + f[1]**2 + f[2]**2 + f[3]**2
+
+    An example showing that the symbolic result of a summation is still
+    valid for seemingly nonsensical values of the limits. Then the Karr
+    convention allows us to give a perfectly valid interpretation to
+    those sums by interchanging the limits according to the above rules:
+
+    >>> S = Sum(i, (i, 1, n)).doit()
+    >>> S
+    n**2/2 + n/2
+    >>> S.subs(n, -4)
+    6
+    >>> Sum(i, (i, 1, -4)).doit()
+    6
+    >>> Sum(-i, (i, -3, 0)).doit()
+    6
+
+    An explicit example of the Karr summation convention:
+
+    >>> S1 = Sum(i**2, (i, m, m+n-1)).doit()
+    >>> S1
+    m**2*n + m*n**2 - m*n + n**3/3 - n**2/2 + n/6
+    >>> S2 = Sum(i**2, (i, m+n, m-1)).doit()
+    >>> S2
+    -m**2*n - m*n**2 + m*n - n**3/3 + n**2/2 - n/6
+    >>> S1 + S2
+    0
+    >>> S3 = Sum(i, (i, m, m-1)).doit()
+    >>> S3
+    0
+
+    See Also
+    ========
+
+    summation
+    Product, sympy.concrete.products.product
+
+    References
+    ==========
+
+    .. [1] Michael Karr, "Summation in Finite Terms", Journal of the ACM,
+           Volume 28 Issue 2, April 1981, Pages 305-350
+           https://dl.acm.org/doi/10.1145/322248.322255
+    .. [2] https://en.wikipedia.org/wiki/Summation#Capital-sigma_notation
+    .. [3] https://en.wikipedia.org/wiki/Empty_sum
+    """
+
+    __slots__ = ()
+
+    limits: tTuple[tTuple[Symbol, Expr, Expr]]
+
+    def __new__(cls, function, *symbols, **assumptions):
+        obj = AddWithLimits.__new__(cls, function, *symbols, **assumptions)
+        if not hasattr(obj, 'limits'):
+            return obj
+        if any(len(l) != 3 or None in l for l in obj.limits):
+            raise ValueError('Sum requires values for lower and upper bounds.')
+
+        return obj
+
+    def _eval_is_zero(self):
+        # a Sum is only zero if its function is zero or if all terms
+        # cancel out. This only answers whether the summand is zero; if
+        # not then None is returned since we don't analyze whether all
+        # terms cancel out.
+        if self.function.is_zero or self.has_empty_sequence:
+            return True
+
+    def _eval_is_extended_real(self):
+        if self.has_empty_sequence:
+            return True
+        return self.function.is_extended_real
+
+    def _eval_is_positive(self):
+        if self.has_finite_limits and self.has_reversed_limits is False:
+            return self.function.is_positive
+
+    def _eval_is_negative(self):
+        if self.has_finite_limits and self.has_reversed_limits is False:
+            return self.function.is_negative
+
+    def _eval_is_finite(self):
+        if self.has_finite_limits and self.function.is_finite:
+            return True
+
+    def doit(self, **hints):
+        if hints.get('deep', True):
+            f = self.function.doit(**hints)
+        else:
+            f = self.function
+
+        # first make sure any definite limits have summation
+        # variables with matching assumptions
+        reps = {}
+        for xab in self.limits:
+            d = _dummy_with_inherited_properties_concrete(xab)
+            if d:
+                reps[xab[0]] = d
+        if reps:
+            undo = {v: k for k, v in reps.items()}
+            did = self.xreplace(reps).doit(**hints)
+            if isinstance(did, tuple):  # when separate=True
+                did = tuple([i.xreplace(undo) for i in did])
+            elif did is not None:
+                did = did.xreplace(undo)
+            else:
+                did = self
+            return did
+
+
+        if self.function.is_Matrix:
+            expanded = self.expand()
+            if self != expanded:
+                return expanded.doit()
+            return _eval_matrix_sum(self)
+
+        for n, limit in enumerate(self.limits):
+            i, a, b = limit
+            dif = b - a
+            if dif == -1:
+                # Any summation over an empty set is zero
+                return S.Zero
+            if dif.is_integer and dif.is_negative:
+                a, b = b + 1, a - 1
+                f = -f
+
+            newf = eval_sum(f, (i, a, b))
+            if newf is None:
+                if f == self.function:
+                    zeta_function = self.eval_zeta_function(f, (i, a, b))
+                    if zeta_function is not None:
+                        return zeta_function
+                    return self
+                else:
+                    return self.func(f, *self.limits[n:])
+            f = newf
+
+        if hints.get('deep', True):
+            # eval_sum could return partially unevaluated
+            # result with Piecewise.  In this case we won't
+            # doit() recursively.
+            if not isinstance(f, Piecewise):
+                return f.doit(**hints)
+
+        return f
+
+    def eval_zeta_function(self, f, limits):
+        """
+        Check whether the function matches with the zeta function.
+
+        If it matches, then return a `Piecewise` expression because
+        zeta function does not converge unless `s > 1` and `q > 0`
+        """
+        i, a, b = limits
+        w, y, z = Wild('w', exclude=[i]), Wild('y', exclude=[i]), Wild('z', exclude=[i])
+        result = f.match((w * i + y) ** (-z))
+        if result is not None and b is S.Infinity:
+            coeff = 1 / result[w] ** result[z]
+            s = result[z]
+            q = result[y] / result[w] + a
+            return Piecewise((coeff * zeta(s, q), And(q > 0, s > 1)), (self, True))
+
+    def _eval_derivative(self, x):
+        """
+        Differentiate wrt x as long as x is not in the free symbols of any of
+        the upper or lower limits.
+
+        Explanation
+        ===========
+
+        Sum(a*b*x, (x, 1, a)) can be differentiated wrt x or b but not `a`
+        since the value of the sum is discontinuous in `a`. In a case
+        involving a limit variable, the unevaluated derivative is returned.
+        """
+
+        # diff already confirmed that x is in the free symbols of self, but we
+        # don't want to differentiate wrt any free symbol in the upper or lower
+        # limits
+        # XXX remove this test for free_symbols when the default _eval_derivative is in
+        if isinstance(x, Symbol) and x not in self.free_symbols:
+            return S.Zero
+
+        # get limits and the function
+        f, limits = self.function, list(self.limits)
+
+        limit = limits.pop(-1)
+
+        if limits:  # f is the argument to a Sum
+            f = self.func(f, *limits)
+
+        _, a, b = limit
+        if x in a.free_symbols or x in b.free_symbols:
+            return None
+        df = Derivative(f, x, evaluate=True)
+        rv = self.func(df, limit)
+        return rv
+
+    def _eval_difference_delta(self, n, step):
+        k, _, upper = self.args[-1]
+        new_upper = upper.subs(n, n + step)
+
+        if len(self.args) == 2:
+            f = self.args[0]
+        else:
+            f = self.func(*self.args[:-1])
+
+        return Sum(f, (k, upper + 1, new_upper)).doit()
+
+    def _eval_simplify(self, **kwargs):
+
+        function = self.function
+
+        if kwargs.get('deep', True):
+            function = function.simplify(**kwargs)
+
+        # split the function into adds
+        terms = Add.make_args(expand(function))
+        s_t = [] # Sum Terms
+        o_t = [] # Other Terms
+
+        for term in terms:
+            if term.has(Sum):
+                # if there is an embedded sum here
+                # it is of the form x * (Sum(whatever))
+                # hence we make a Mul out of it, and simplify all interior sum terms
+                subterms = Mul.make_args(expand(term))
+                out_terms = []
+                for subterm in subterms:
+                    # go through each term
+                    if isinstance(subterm, Sum):
+                        # if it's a sum, simplify it
+                        out_terms.append(subterm._eval_simplify(**kwargs))
+                    else:
+                        # otherwise, add it as is
+                        out_terms.append(subterm)
+
+                # turn it back into a Mul
+                s_t.append(Mul(*out_terms))
+            else:
+                o_t.append(term)
+
+        # next try to combine any interior sums for further simplification
+        from sympy.simplify.simplify import factor_sum, sum_combine
+        result = Add(sum_combine(s_t), *o_t)
+
+        return factor_sum(result, limits=self.limits)
+
+    def is_convergent(self):
+        r"""
+        Checks for the convergence of a Sum.
+
+        Explanation
+        ===========
+
+        We divide the study of convergence of infinite sums and products in
+        two parts.
+
+        First Part:
+        One part is the question whether all the terms are well defined, i.e.,
+        they are finite in a sum and also non-zero in a product. Zero
+        is the analogy of (minus) infinity in products as
+        :math:`e^{-\infty} = 0`.
+
+        Second Part:
+        The second part is the question of convergence after infinities,
+        and zeros in products, have been omitted assuming that their number
+        is finite. This means that we only consider the tail of the sum or
+        product, starting from some point after which all terms are well
+        defined.
+
+        For example, in a sum of the form:
+
+        .. math::
+
+            \sum_{1 \leq i < \infty} \frac{1}{n^2 + an + b}
+
+        where a and b are numbers. The routine will return true, even if there
+        are infinities in the term sequence (at most two). An analogous
+        product would be:
+
+        .. math::
+
+            \prod_{1 \leq i < \infty} e^{\frac{1}{n^2 + an + b}}
+
+        This is how convergence is interpreted. It is concerned with what
+        happens at the limit. Finding the bad terms is another independent
+        matter.
+
+        Note: It is responsibility of user to see that the sum or product
+        is well defined.
+
+        There are various tests employed to check the convergence like
+        divergence test, root test, integral test, alternating series test,
+        comparison tests, Dirichlet tests. It returns true if Sum is convergent
+        and false if divergent and NotImplementedError if it cannot be checked.
+
+        References
+        ==========
+
+        .. [1] https://en.wikipedia.org/wiki/Convergence_tests
+
+        Examples
+        ========
+
+        >>> from sympy import factorial, S, Sum, Symbol, oo
+        >>> n = Symbol('n', integer=True)
+        >>> Sum(n/(n - 1), (n, 4, 7)).is_convergent()
+        True
+        >>> Sum(n/(2*n + 1), (n, 1, oo)).is_convergent()
+        False
+        >>> Sum(factorial(n)/5**n, (n, 1, oo)).is_convergent()
+        False
+        >>> Sum(1/n**(S(6)/5), (n, 1, oo)).is_convergent()
+        True
+
+        See Also
+        ========
+
+        Sum.is_absolutely_convergent
+        sympy.concrete.products.Product.is_convergent
+        """
+        p, q, r = symbols('p q r', cls=Wild)
+
+        sym = self.limits[0][0]
+        lower_limit = self.limits[0][1]
+        upper_limit = self.limits[0][2]
+        sequence_term = self.function.simplify()
+
+        if len(sequence_term.free_symbols) > 1:
+            raise NotImplementedError("convergence checking for more than one symbol "
+                                      "containing series is not handled")
+
+        if lower_limit.is_finite and upper_limit.is_finite:
+            return S.true
+
+        # transform sym -> -sym and swap the upper_limit = S.Infinity
+        # and lower_limit = - upper_limit
+        if lower_limit is S.NegativeInfinity:
+            if upper_limit is S.Infinity:
+                return Sum(sequence_term, (sym, 0, S.Infinity)).is_convergent() and \
+                        Sum(sequence_term, (sym, S.NegativeInfinity, 0)).is_convergent()
+            from sympy.simplify.simplify import simplify
+            sequence_term = simplify(sequence_term.xreplace({sym: -sym}))
+            lower_limit = -upper_limit
+            upper_limit = S.Infinity
+
+        sym_ = Dummy(sym.name, integer=True, positive=True)
+        sequence_term = sequence_term.xreplace({sym: sym_})
+        sym = sym_
+
+        interval = Interval(lower_limit, upper_limit)
+
+        # Piecewise function handle
+        if sequence_term.is_Piecewise:
+            for func, cond in sequence_term.args:
+                # see if it represents something going to oo
+                if cond == True or cond.as_set().sup is S.Infinity:
+                    s = Sum(func, (sym, lower_limit, upper_limit))
+                    return s.is_convergent()
+            return S.true
+
+        ###  -------- Divergence test ----------- ###
+        try:
+           lim_val = limit_seq(sequence_term, sym)
+           if lim_val is not None and lim_val.is_zero is False:
+               return S.false
+        except NotImplementedError:
+            pass
+
+        try:
+            lim_val_abs = limit_seq(abs(sequence_term), sym)
+            if lim_val_abs is not None and lim_val_abs.is_zero is False:
+                return S.false
+        except NotImplementedError:
+            pass
+
+        order = O(sequence_term, (sym, S.Infinity))
+
+        ### --------- p-series test (1/n**p) ---------- ###
+        p_series_test = order.expr.match(sym**p)
+        if p_series_test is not None:
+            if p_series_test[p] < -1:
+                return S.true
+            if p_series_test[p] >= -1:
+                return S.false
+
+        ### ------------- comparison test ------------- ###
+        # 1/(n**p*log(n)**q*log(log(n))**r) comparison
+        n_log_test = (order.expr.match(1/(sym**p*log(1/sym)**q*log(-log(1/sym))**r)) or
+                      order.expr.match(1/(sym**p*(-log(1/sym))**q*log(-log(1/sym))**r)))
+        if n_log_test is not None:
+            if (n_log_test[p] > 1 or
+                (n_log_test[p] == 1 and n_log_test[q] > 1) or
+                (n_log_test[p] == n_log_test[q] == 1 and n_log_test[r] > 1)):
+                    return S.true
+            return S.false
+
+        ### ------------- Limit comparison test -----------###
+        # (1/n) comparison
+        try:
+            lim_comp = limit_seq(sym*sequence_term, sym)
+            if lim_comp is not None and lim_comp.is_number and lim_comp > 0:
+                return S.false
+        except NotImplementedError:
+            pass
+
+        ### ----------- ratio test ---------------- ###
+        next_sequence_term = sequence_term.xreplace({sym: sym + 1})
+        from sympy.simplify.combsimp import combsimp
+        from sympy.simplify.powsimp import powsimp
+        ratio = combsimp(powsimp(next_sequence_term/sequence_term))
+        try:
+            lim_ratio = limit_seq(ratio, sym)
+            if lim_ratio is not None and lim_ratio.is_number:
+                if abs(lim_ratio) > 1:
+                    return S.false
+                if abs(lim_ratio) < 1:
+                    return S.true
+        except NotImplementedError:
+            lim_ratio = None
+
+        ### ---------- Raabe's test -------------- ###
+        if lim_ratio == 1:  # ratio test inconclusive
+            test_val = sym*(sequence_term/
+                         sequence_term.subs(sym, sym + 1) - 1)
+            test_val = test_val.gammasimp()
+            try:
+                lim_val = limit_seq(test_val, sym)
+                if lim_val is not None and lim_val.is_number:
+                    if lim_val > 1:
+                        return S.true
+                    if lim_val < 1:
+                        return S.false
+            except NotImplementedError:
+                pass
+
+        ### ----------- root test ---------------- ###
+        # lim = Limit(abs(sequence_term)**(1/sym), sym, S.Infinity)
+        try:
+            lim_evaluated = limit_seq(abs(sequence_term)**(1/sym), sym)
+            if lim_evaluated is not None and lim_evaluated.is_number:
+                if lim_evaluated < 1:
+                    return S.true
+                if lim_evaluated > 1:
+                    return S.false
+        except NotImplementedError:
+            pass
+
+        ### ------------- alternating series test ----------- ###
+        dict_val = sequence_term.match(S.NegativeOne**(sym + p)*q)
+        if not dict_val[p].has(sym) and is_decreasing(dict_val[q], interval):
+            return S.true
+
+        ### ------------- integral test -------------- ###
+        check_interval = None
+        from sympy.solvers.solveset import solveset
+        maxima = solveset(sequence_term.diff(sym), sym, interval)
+        if not maxima:
+            check_interval = interval
+        elif isinstance(maxima, FiniteSet) and maxima.sup.is_number:
+            check_interval = Interval(maxima.sup, interval.sup)
+        if (check_interval is not None and
+            (is_decreasing(sequence_term, check_interval) or
+            is_decreasing(-sequence_term, check_interval))):
+                integral_val = Integral(
+                    sequence_term, (sym, lower_limit, upper_limit))
+                try:
+                    integral_val_evaluated = integral_val.doit()
+                    if integral_val_evaluated.is_number:
+                        return S(integral_val_evaluated.is_finite)
+                except NotImplementedError:
+                    pass
+
+        ### ----- Dirichlet and bounded times convergent tests ----- ###
+        # TODO
+        #
+        # Dirichlet_test
+        # https://en.wikipedia.org/wiki/Dirichlet%27s_test
+        #
+        # Bounded times convergent test
+        # It is based on comparison theorems for series.
+        # In particular, if the general term of a series can
+        # be written as a product of two terms a_n and b_n
+        # and if a_n is bounded and if Sum(b_n) is absolutely
+        # convergent, then the original series Sum(a_n * b_n)
+        # is absolutely convergent and so convergent.
+        #
+        # The following code can grows like 2**n where n is the
+        # number of args in order.expr
+        # Possibly combined with the potentially slow checks
+        # inside the loop, could make this test extremely slow
+        # for larger summation expressions.
+
+        if order.expr.is_Mul:
+            args = order.expr.args
+            argset = set(args)
+
+            ### -------------- Dirichlet tests -------------- ###
+            m = Dummy('m', integer=True)
+            def _dirichlet_test(g_n):
+                try:
+                    ing_val = limit_seq(Sum(g_n, (sym, interval.inf, m)).doit(), m)
+                    if ing_val is not None and ing_val.is_finite:
+                        return S.true
+                except NotImplementedError:
+                    pass
+
+            ### -------- bounded times convergent test ---------###
+            def _bounded_convergent_test(g1_n, g2_n):
+                try:
+                    lim_val = limit_seq(g1_n, sym)
+                    if lim_val is not None and (lim_val.is_finite or (
+                        isinstance(lim_val, AccumulationBounds)
+                        and (lim_val.max - lim_val.min).is_finite)):
+                            if Sum(g2_n, (sym, lower_limit, upper_limit)).is_absolutely_convergent():
+                                return S.true
+                except NotImplementedError:
+                    pass
+
+            for n in range(1, len(argset)):
+                for a_tuple in itertools.combinations(args, n):
+                    b_set = argset - set(a_tuple)
+                    a_n = Mul(*a_tuple)
+                    b_n = Mul(*b_set)
+
+                    if is_decreasing(a_n, interval):
+                        dirich = _dirichlet_test(b_n)
+                        if dirich is not None:
+                            return dirich
+
+                    bc_test = _bounded_convergent_test(a_n, b_n)
+                    if bc_test is not None:
+                        return bc_test
+
+        _sym = self.limits[0][0]
+        sequence_term = sequence_term.xreplace({sym: _sym})
+        raise NotImplementedError("The algorithm to find the Sum convergence of %s "
+                                  "is not yet implemented" % (sequence_term))
+
+    def is_absolutely_convergent(self):
+        """
+        Checks for the absolute convergence of an infinite series.
+
+        Same as checking convergence of absolute value of sequence_term of
+        an infinite series.
+
+        References
+        ==========
+
+        .. [1] https://en.wikipedia.org/wiki/Absolute_convergence
+
+        Examples
+        ========
+
+        >>> from sympy import Sum, Symbol, oo
+        >>> n = Symbol('n', integer=True)
+        >>> Sum((-1)**n, (n, 1, oo)).is_absolutely_convergent()
+        False
+        >>> Sum((-1)**n/n**2, (n, 1, oo)).is_absolutely_convergent()
+        True
+
+        See Also
+        ========
+
+        Sum.is_convergent
+        """
+        return Sum(abs(self.function), self.limits).is_convergent()
+
+    def euler_maclaurin(self, m=0, n=0, eps=0, eval_integral=True):
+        """
+        Return an Euler-Maclaurin approximation of self, where m is the
+        number of leading terms to sum directly and n is the number of
+        terms in the tail.
+
+        With m = n = 0, this is simply the corresponding integral
+        plus a first-order endpoint correction.
+
+        Returns (s, e) where s is the Euler-Maclaurin approximation
+        and e is the estimated error (taken to be the magnitude of
+        the first omitted term in the tail):
+
+            >>> from sympy.abc import k, a, b
+            >>> from sympy import Sum
+            >>> Sum(1/k, (k, 2, 5)).doit().evalf()
+            1.28333333333333
+            >>> s, e = Sum(1/k, (k, 2, 5)).euler_maclaurin()
+            >>> s
+            -log(2) + 7/20 + log(5)
+            >>> from sympy import sstr
+            >>> print(sstr((s.evalf(), e.evalf()), full_prec=True))
+            (1.26629073187415, 0.0175000000000000)
+
+        The endpoints may be symbolic:
+
+            >>> s, e = Sum(1/k, (k, a, b)).euler_maclaurin()
+            >>> s
+            -log(a) + log(b) + 1/(2*b) + 1/(2*a)
+            >>> e
+            Abs(1/(12*b**2) - 1/(12*a**2))
+
+        If the function is a polynomial of degree at most 2n+1, the
+        Euler-Maclaurin formula becomes exact (and e = 0 is returned):
+
+            >>> Sum(k, (k, 2, b)).euler_maclaurin()
+            (b**2/2 + b/2 - 1, 0)
+            >>> Sum(k, (k, 2, b)).doit()
+            b**2/2 + b/2 - 1
+
+        With a nonzero eps specified, the summation is ended
+        as soon as the remainder term is less than the epsilon.
+        """
+        m = int(m)
+        n = int(n)
+        f = self.function
+        if len(self.limits) != 1:
+            raise ValueError("More than 1 limit")
+        i, a, b = self.limits[0]
+        if (a > b) == True:
+            if a - b == 1:
+                return S.Zero, S.Zero
+            a, b = b + 1, a - 1
+            f = -f
+        s = S.Zero
+        if m:
+            if b.is_Integer and a.is_Integer:
+                m = min(m, b - a + 1)
+            if not eps or f.is_polynomial(i):
+                s = Add(*[f.subs(i, a + k) for k in range(m)])
+            else:
+                term = f.subs(i, a)
+                if term:
+                    test = abs(term.evalf(3)) < eps
+                    if test == True:
+                        return s, abs(term)
+                    elif not (test == False):
+                        # a symbolic Relational class, can't go further
+                        return term, S.Zero
+                s = term
+                for k in range(1, m):
+                    term = f.subs(i, a + k)
+                    if abs(term.evalf(3)) < eps and term != 0:
+                        return s, abs(term)
+                    s += term
+            if b - a + 1 == m:
+                return s, S.Zero
+            a += m
+        x = Dummy('x')
+        I = Integral(f.subs(i, x), (x, a, b))
+        if eval_integral:
+            I = I.doit()
+        s += I
+
+        def fpoint(expr):
+            if b is S.Infinity:
+                return expr.subs(i, a), 0
+            return expr.subs(i, a), expr.subs(i, b)
+        fa, fb = fpoint(f)
+        iterm = (fa + fb)/2
+        g = f.diff(i)
+        for k in range(1, n + 2):
+            ga, gb = fpoint(g)
+            term = bernoulli(2*k)/factorial(2*k)*(gb - ga)
+            if k > n:
+                break
+            if eps and term:
+                term_evalf = term.evalf(3)
+                if term_evalf is S.NaN:
+                    return S.NaN, S.NaN
+                if abs(term_evalf) < eps:
+                    break
+            s += term
+            g = g.diff(i, 2, simplify=False)
+        return s + iterm, abs(term)
+
+
+    def reverse_order(self, *indices):
+        """
+        Reverse the order of a limit in a Sum.
+
+        Explanation
+        ===========
+
+        ``reverse_order(self, *indices)`` reverses some limits in the expression
+        ``self`` which can be either a ``Sum`` or a ``Product``. The selectors in
+        the argument ``indices`` specify some indices whose limits get reversed.
+        These selectors are either variable names or numerical indices counted
+        starting from the inner-most limit tuple.
+
+        Examples
+        ========
+
+        >>> from sympy import Sum
+        >>> from sympy.abc import x, y, a, b, c, d
+
+        >>> Sum(x, (x, 0, 3)).reverse_order(x)
+        Sum(-x, (x, 4, -1))
+        >>> Sum(x*y, (x, 1, 5), (y, 0, 6)).reverse_order(x, y)
+        Sum(x*y, (x, 6, 0), (y, 7, -1))
+        >>> Sum(x, (x, a, b)).reverse_order(x)
+        Sum(-x, (x, b + 1, a - 1))
+        >>> Sum(x, (x, a, b)).reverse_order(0)
+        Sum(-x, (x, b + 1, a - 1))
+
+        While one should prefer variable names when specifying which limits
+        to reverse, the index counting notation comes in handy in case there
+        are several symbols with the same name.
+
+        >>> S = Sum(x**2, (x, a, b), (x, c, d))
+        >>> S
+        Sum(x**2, (x, a, b), (x, c, d))
+        >>> S0 = S.reverse_order(0)
+        >>> S0
+        Sum(-x**2, (x, b + 1, a - 1), (x, c, d))
+        >>> S1 = S0.reverse_order(1)
+        >>> S1
+        Sum(x**2, (x, b + 1, a - 1), (x, d + 1, c - 1))
+
+        Of course we can mix both notations:
+
+        >>> Sum(x*y, (x, a, b), (y, 2, 5)).reverse_order(x, 1)
+        Sum(x*y, (x, b + 1, a - 1), (y, 6, 1))
+        >>> Sum(x*y, (x, a, b), (y, 2, 5)).reverse_order(y, x)
+        Sum(x*y, (x, b + 1, a - 1), (y, 6, 1))
+
+        See Also
+        ========
+
+        sympy.concrete.expr_with_intlimits.ExprWithIntLimits.index, reorder_limit,
+        sympy.concrete.expr_with_intlimits.ExprWithIntLimits.reorder
+
+        References
+        ==========
+
+        .. [1] Michael Karr, "Summation in Finite Terms", Journal of the ACM,
+               Volume 28 Issue 2, April 1981, Pages 305-350
+               https://dl.acm.org/doi/10.1145/322248.322255
+        """
+        l_indices = list(indices)
+
+        for i, indx in enumerate(l_indices):
+            if not isinstance(indx, int):
+                l_indices[i] = self.index(indx)
+
+        e = 1
+        limits = []
+        for i, limit in enumerate(self.limits):
+            l = limit
+            if i in l_indices:
+                e = -e
+                l = (limit[0], limit[2] + 1, limit[1] - 1)
+            limits.append(l)
+
+        return Sum(e * self.function, *limits)
+
+    def _eval_rewrite_as_Product(self, *args, **kwargs):
+        from sympy.concrete.products import Product
+        if self.function.is_extended_real:
+            return log(Product(exp(self.function), *self.limits))
+
+
+def summation(f, *symbols, **kwargs):
+    r"""
+    Compute the summation of f with respect to symbols.
+
+    Explanation
+    ===========
+
+    The notation for symbols is similar to the notation used in Integral.
+    summation(f, (i, a, b)) computes the sum of f with respect to i from a to b,
+    i.e.,
+
+    ::
+
+                                    b
+                                  ____
+                                  \   `
+        summation(f, (i, a, b)) =  )    f
+                                  /___,
+                                  i = a
+
+    If it cannot compute the sum, it returns an unevaluated Sum object.
+    Repeated sums can be computed by introducing additional symbols tuples::
+
+    Examples
+    ========
+
+    >>> from sympy import summation, oo, symbols, log
+    >>> i, n, m = symbols('i n m', integer=True)
+
+    >>> summation(2*i - 1, (i, 1, n))
+    n**2
+    >>> summation(1/2**i, (i, 0, oo))
+    2
+    >>> summation(1/log(n)**n, (n, 2, oo))
+    Sum(log(n)**(-n), (n, 2, oo))
+    >>> summation(i, (i, 0, n), (n, 0, m))
+    m**3/6 + m**2/2 + m/3
+
+    >>> from sympy.abc import x
+    >>> from sympy import factorial
+    >>> summation(x**n/factorial(n), (n, 0, oo))
+    exp(x)
+
+    See Also
+    ========
+
+    Sum
+    Product, sympy.concrete.products.product
+
+    """
+    return Sum(f, *symbols, **kwargs).doit(deep=False)
+
+
+def telescopic_direct(L, R, n, limits):
+    """
+    Returns the direct summation of the terms of a telescopic sum
+
+    Explanation
+    ===========
+
+    L is the term with lower index
+    R is the term with higher index
+    n difference between the indexes of L and R
+
+    Examples
+    ========
+
+    >>> from sympy.concrete.summations import telescopic_direct
+    >>> from sympy.abc import k, a, b
+    >>> telescopic_direct(1/k, -1/(k+2), 2, (k, a, b))
+    -1/(b + 2) - 1/(b + 1) + 1/(a + 1) + 1/a
+
+    """
+    (i, a, b) = limits
+    return Add(*[L.subs(i, a + m) + R.subs(i, b - m) for m in range(n)])
+
+
+def telescopic(L, R, limits):
+    '''
+    Tries to perform the summation using the telescopic property.
+
+    Return None if not possible.
+    '''
+    (i, a, b) = limits
+    if L.is_Add or R.is_Add:
+        return None
+
+    # We want to solve(L.subs(i, i + m) + R, m)
+    # First we try a simple match since this does things that
+    # solve doesn't do, e.g. solve(cos(k+m)-cos(k), m) gives
+    # a more complicated solution than m == 0.
+
+    k = Wild("k")
+    sol = (-R).match(L.subs(i, i + k))
+    s = None
+    if sol and k in sol:
+        s = sol[k]
+        if not (s.is_Integer and L.subs(i, i + s) + R == 0):
+            # invalid match or match didn't work
+            s = None
+
+    # But there are things that match doesn't do that solve
+    # can do, e.g. determine that 1/(x + m) = 1/(1 - x) when m = 1
+
+    if s is None:
+        m = Dummy('m')
+        try:
+            from sympy.solvers.solvers import solve
+            sol = solve(L.subs(i, i + m) + R, m) or []
+        except NotImplementedError:
+            return None
+        sol = [si for si in sol if si.is_Integer and
+               (L.subs(i, i + si) + R).expand().is_zero]
+        if len(sol) != 1:
+            return None
+        s = sol[0]
+
+    if s < 0:
+        return telescopic_direct(R, L, abs(s), (i, a, b))
+    elif s > 0:
+        return telescopic_direct(L, R, s, (i, a, b))
+
+
+def eval_sum(f, limits):
+    (i, a, b) = limits
+    if f.is_zero:
+        return S.Zero
+    if i not in f.free_symbols:
+        return f*(b - a + 1)
+    if a == b:
+        return f.subs(i, a)
+    if isinstance(f, Piecewise):
+        if not any(i in arg.args[1].free_symbols for arg in f.args):
+            # Piecewise conditions do not depend on the dummy summation variable,
+            # therefore we can fold:     Sum(Piecewise((e, c), ...), limits)
+            #                        --> Piecewise((Sum(e, limits), c), ...)
+            newargs = []
+            for arg in f.args:
+                newexpr = eval_sum(arg.expr, limits)
+                if newexpr is None:
+                    return None
+                newargs.append((newexpr, arg.cond))
+            return f.func(*newargs)
+
+    if f.has(KroneckerDelta):
+        from .delta import deltasummation, _has_simple_delta
+        f = f.replace(
+            lambda x: isinstance(x, Sum),
+            lambda x: x.factor()
+        )
+        if _has_simple_delta(f, limits[0]):
+            return deltasummation(f, limits)
+
+    dif = b - a
+    definite = dif.is_Integer
+    # Doing it directly may be faster if there are very few terms.
+    if definite and (dif < 100):
+        return eval_sum_direct(f, (i, a, b))
+    if isinstance(f, Piecewise):
+        return None
+    # Try to do it symbolically. Even when the number of terms is
+    # known, this can save time when b-a is big.
+    value = eval_sum_symbolic(f.expand(), (i, a, b))
+    if value is not None:
+        return value
+    # Do it directly
+    if definite:
+        return eval_sum_direct(f, (i, a, b))
+
+
+def eval_sum_direct(expr, limits):
+    """
+    Evaluate expression directly, but perform some simple checks first
+    to possibly result in a smaller expression and faster execution.
+    """
+    (i, a, b) = limits
+
+    dif = b - a
+    # Linearity
+    if expr.is_Mul:
+        # Try factor out everything not including i
+        without_i, with_i = expr.as_independent(i)
+        if without_i != 1:
+            s = eval_sum_direct(with_i, (i, a, b))
+            if s:
+                r = without_i*s
+                if r is not S.NaN:
+                    return r
+        else:
+            # Try term by term
+            L, R = expr.as_two_terms()
+
+            if not L.has(i):
+                sR = eval_sum_direct(R, (i, a, b))
+                if sR:
+                    return L*sR
+
+            if not R.has(i):
+                sL = eval_sum_direct(L, (i, a, b))
+                if sL:
+                    return sL*R
+
+    # do this whether its an Add or Mul
+    # e.g. apart(1/(25*i**2 + 45*i + 14)) and
+    # apart(1/((5*i + 2)*(5*i + 7))) ->
+    # -1/(5*(5*i + 7)) + 1/(5*(5*i + 2))
+    try:
+        expr = apart(expr, i)  # see if it becomes an Add
+    except PolynomialError:
+        pass
+
+    if expr.is_Add:
+        # Try factor out everything not including i
+        without_i, with_i = expr.as_independent(i)
+        if without_i != 0:
+            s = eval_sum_direct(with_i, (i, a, b))
+            if s:
+                r = without_i*(dif + 1) + s
+                if r is not S.NaN:
+                    return r
+        else:
+            # Try term by term
+            L, R = expr.as_two_terms()
+            lsum = eval_sum_direct(L, (i, a, b))
+            rsum = eval_sum_direct(R, (i, a, b))
+
+            if None not in (lsum, rsum):
+                r = lsum + rsum
+                if r is not S.NaN:
+                    return r
+
+    return Add(*[expr.subs(i, a + j) for j in range(dif + 1)])
+
+
+def eval_sum_symbolic(f, limits):
+    f_orig = f
+    (i, a, b) = limits
+    if not f.has(i):
+        return f*(b - a + 1)
+
+    # Linearity
+    if f.is_Mul:
+        # Try factor out everything not including i
+        without_i, with_i = f.as_independent(i)
+        if without_i != 1:
+            s = eval_sum_symbolic(with_i, (i, a, b))
+            if s:
+                r = without_i*s
+                if r is not S.NaN:
+                    return r
+        else:
+            # Try term by term
+            L, R = f.as_two_terms()
+
+            if not L.has(i):
+                sR = eval_sum_symbolic(R, (i, a, b))
+                if sR:
+                    return L*sR
+
+            if not R.has(i):
+                sL = eval_sum_symbolic(L, (i, a, b))
+                if sL:
+                    return sL*R
+
+    # do this whether its an Add or Mul
+    # e.g. apart(1/(25*i**2 + 45*i + 14)) and
+    # apart(1/((5*i + 2)*(5*i + 7))) ->
+    # -1/(5*(5*i + 7)) + 1/(5*(5*i + 2))
+    try:
+        f = apart(f, i)
+    except PolynomialError:
+        pass
+
+    if f.is_Add:
+        L, R = f.as_two_terms()
+        lrsum = telescopic(L, R, (i, a, b))
+
+        if lrsum:
+            return lrsum
+
+        # Try factor out everything not including i
+        without_i, with_i = f.as_independent(i)
+        if without_i != 0:
+            s = eval_sum_symbolic(with_i, (i, a, b))
+            if s:
+                r = without_i*(b - a + 1) + s
+                if r is not S.NaN:
+                    return r
+        else:
+            # Try term by term
+            lsum = eval_sum_symbolic(L, (i, a, b))
+            rsum = eval_sum_symbolic(R, (i, a, b))
+
+            if None not in (lsum, rsum):
+                r = lsum + rsum
+                if r is not S.NaN:
+                    return r
+
+
+    # Polynomial terms with Faulhaber's formula
+    n = Wild('n')
+    result = f.match(i**n)
+
+    if result is not None:
+        n = result[n]
+
+        if n.is_Integer:
+            if n >= 0:
+                if (b is S.Infinity and a is not S.NegativeInfinity) or \
+                   (a is S.NegativeInfinity and b is not S.Infinity):
+                    return S.Infinity
+                return ((bernoulli(n + 1, b + 1) - bernoulli(n + 1, a))/(n + 1)).expand()
+            elif a.is_Integer and a >= 1:
+                if n == -1:
+                    return harmonic(b) - harmonic(a - 1)
+                else:
+                    return harmonic(b, abs(n)) - harmonic(a - 1, abs(n))
+
+    if not (a.has(S.Infinity, S.NegativeInfinity) or
+            b.has(S.Infinity, S.NegativeInfinity)):
+        # Geometric terms
+        c1 = Wild('c1', exclude=[i])
+        c2 = Wild('c2', exclude=[i])
+        c3 = Wild('c3', exclude=[i])
+        wexp = Wild('wexp')
+
+        # Here we first attempt powsimp on f for easier matching with the
+        # exponential pattern, and attempt expansion on the exponent for easier
+        # matching with the linear pattern.
+        e = f.powsimp().match(c1 ** wexp)
+        if e is not None:
+            e_exp = e.pop(wexp).expand().match(c2*i + c3)
+            if e_exp is not None:
+                e.update(e_exp)
+
+                p = (c1**c3).subs(e)
+                q = (c1**c2).subs(e)
+                r = p*(q**a - q**(b + 1))/(1 - q)
+                l = p*(b - a + 1)
+                return Piecewise((l, Eq(q, S.One)), (r, True))
+
+        r = gosper_sum(f, (i, a, b))
+
+        if isinstance(r, (Mul,Add)):
+            from sympy.simplify.radsimp import denom
+            from sympy.solvers.solvers import solve
+            non_limit = r.free_symbols - Tuple(*limits[1:]).free_symbols
+            den = denom(together(r))
+            den_sym = non_limit & den.free_symbols
+            args = []
+            for v in ordered(den_sym):
+                try:
+                    s = solve(den, v)
+                    m = Eq(v, s[0]) if s else S.false
+                    if m != False:
+                        args.append((Sum(f_orig.subs(*m.args), limits).doit(), m))
+                    break
+                except NotImplementedError:
+                    continue
+
+            args.append((r, True))
+            return Piecewise(*args)
+
+        if r not in (None, S.NaN):
+            return r
+
+    h = eval_sum_hyper(f_orig, (i, a, b))
+    if h is not None:
+        return h
+
+    r = eval_sum_residue(f_orig, (i, a, b))
+    if r is not None:
+        return r
+
+    factored = f_orig.factor()
+    if factored != f_orig:
+        return eval_sum_symbolic(factored, (i, a, b))
+
+
+def _eval_sum_hyper(f, i, a):
+    """ Returns (res, cond). Sums from a to oo. """
+    if a != 0:
+        return _eval_sum_hyper(f.subs(i, i + a), i, 0)
+
+    if f.subs(i, 0) == 0:
+        from sympy.simplify.simplify import simplify
+        if simplify(f.subs(i, Dummy('i', integer=True, positive=True))) == 0:
+            return S.Zero, True
+        return _eval_sum_hyper(f.subs(i, i + 1), i, 0)
+
+    from sympy.simplify.simplify import hypersimp
+    hs = hypersimp(f, i)
+    if hs is None:
+        return None
+
+    if isinstance(hs, Float):
+        from sympy.simplify.simplify import nsimplify
+        hs = nsimplify(hs)
+
+    from sympy.simplify.combsimp import combsimp
+    from sympy.simplify.hyperexpand import hyperexpand
+    from sympy.simplify.radsimp import fraction
+    numer, denom = fraction(factor(hs))
+    top, topl = numer.as_coeff_mul(i)
+    bot, botl = denom.as_coeff_mul(i)
+    ab = [top, bot]
+    factors = [topl, botl]
+    params = [[], []]
+    for k in range(2):
+        for fac in factors[k]:
+            mul = 1
+            if fac.is_Pow:
+                mul = fac.exp
+                fac = fac.base
+                if not mul.is_Integer:
+                    return None
+            p = Poly(fac, i)
+            if p.degree() != 1:
+                return None
+            m, n = p.all_coeffs()
+            ab[k] *= m**mul
+            params[k] += [n/m]*mul
+
+    # Add "1" to numerator parameters, to account for implicit n! in
+    # hypergeometric series.
+    ap = params[0] + [1]
+    bq = params[1]
+    x = ab[0]/ab[1]
+    h = hyper(ap, bq, x)
+    f = combsimp(f)
+    return f.subs(i, 0)*hyperexpand(h), h.convergence_statement
+
+
+def eval_sum_hyper(f, i_a_b):
+    i, a, b = i_a_b
+
+    if f.is_hypergeometric(i) is False:
+        return
+
+    if (b - a).is_Integer:
+        # We are never going to do better than doing the sum in the obvious way
+        return None
+
+    old_sum = Sum(f, (i, a, b))
+
+    if b != S.Infinity:
+        if a is S.NegativeInfinity:
+            res = _eval_sum_hyper(f.subs(i, -i), i, -b)
+            if res is not None:
+                return Piecewise(res, (old_sum, True))
+        else:
+            n_illegal = lambda x: sum(x.count(_) for _ in _illegal)
+            had = n_illegal(f)
+            # check that no extra illegals are introduced
+            res1 = _eval_sum_hyper(f, i, a)
+            if res1 is None or n_illegal(res1) > had:
+                return
+            res2 = _eval_sum_hyper(f, i, b + 1)
+            if res2 is None or n_illegal(res2) > had:
+                return
+            (res1, cond1), (res2, cond2) = res1, res2
+            cond = And(cond1, cond2)
+            if cond == False:
+                return None
+            return Piecewise((res1 - res2, cond), (old_sum, True))
+
+    if a is S.NegativeInfinity:
+        res1 = _eval_sum_hyper(f.subs(i, -i), i, 1)
+        res2 = _eval_sum_hyper(f, i, 0)
+        if res1 is None or res2 is None:
+            return None
+        res1, cond1 = res1
+        res2, cond2 = res2
+        cond = And(cond1, cond2)
+        if cond == False or cond.as_set() == S.EmptySet:
+            return None
+        return Piecewise((res1 + res2, cond), (old_sum, True))
+
+    # Now b == oo, a != -oo
+    res = _eval_sum_hyper(f, i, a)
+    if res is not None:
+        r, c = res
+        if c == False:
+            if r.is_number:
+                f = f.subs(i, Dummy('i', integer=True, positive=True) + a)
+                if f.is_positive or f.is_zero:
+                    return S.Infinity
+                elif f.is_negative:
+                    return S.NegativeInfinity
+            return None
+        return Piecewise(res, (old_sum, True))
+
+
+def eval_sum_residue(f, i_a_b):
+    r"""Compute the infinite summation with residues
+
+    Notes
+    =====
+
+    If $f(n), g(n)$ are polynomials with $\deg(g(n)) - \deg(f(n)) \ge 2$,
+    some infinite summations can be computed by the following residue
+    evaluations.
+
+    .. math::
+        \sum_{n=-\infty, g(n) \ne 0}^{\infty} \frac{f(n)}{g(n)} =
+        -\pi \sum_{\alpha|g(\alpha)=0}
+        \text{Res}(\cot(\pi x) \frac{f(x)}{g(x)}, \alpha)
+
+    .. math::
+        \sum_{n=-\infty, g(n) \ne 0}^{\infty} (-1)^n \frac{f(n)}{g(n)} =
+        -\pi \sum_{\alpha|g(\alpha)=0}
+        \text{Res}(\csc(\pi x) \frac{f(x)}{g(x)}, \alpha)
+
+    Examples
+    ========
+
+    >>> from sympy import Sum, oo, Symbol
+    >>> x = Symbol('x')
+
+    Doubly infinite series of rational functions.
+
+    >>> Sum(1 / (x**2 + 1), (x, -oo, oo)).doit()
+    pi/tanh(pi)
+
+    Doubly infinite alternating series of rational functions.
+
+    >>> Sum((-1)**x / (x**2 + 1), (x, -oo, oo)).doit()
+    pi/sinh(pi)
+
+    Infinite series of even rational functions.
+
+    >>> Sum(1 / (x**2 + 1), (x, 0, oo)).doit()
+    1/2 + pi/(2*tanh(pi))
+
+    Infinite series of alternating even rational functions.
+
+    >>> Sum((-1)**x / (x**2 + 1), (x, 0, oo)).doit()
+    pi/(2*sinh(pi)) + 1/2
+
+    This also have heuristics to transform arbitrarily shifted summand or
+    arbitrarily shifted summation range to the canonical problem the
+    formula can handle.
+
+    >>> Sum(1 / (x**2 + 2*x + 2), (x, -1, oo)).doit()
+    1/2 + pi/(2*tanh(pi))
+    >>> Sum(1 / (x**2 + 4*x + 5), (x, -2, oo)).doit()
+    1/2 + pi/(2*tanh(pi))
+    >>> Sum(1 / (x**2 + 1), (x, 1, oo)).doit()
+    -1/2 + pi/(2*tanh(pi))
+    >>> Sum(1 / (x**2 + 1), (x, 2, oo)).doit()
+    -1 + pi/(2*tanh(pi))
+
+    References
+    ==========
+
+    .. [#] http://www.supermath.info/InfiniteSeriesandtheResidueTheorem.pdf
+
+    .. [#] Asmar N.H., Grafakos L. (2018) Residue Theory.
+           In: Complex Analysis with Applications.
+           Undergraduate Texts in Mathematics. Springer, Cham.
+           https://doi.org/10.1007/978-3-319-94063-2_5
+    """
+    i, a, b = i_a_b
+
+    def is_even_function(numer, denom):
+        """Test if the rational function is an even function"""
+        numer_even = all(i % 2 == 0 for (i,) in numer.monoms())
+        denom_even = all(i % 2 == 0 for (i,) in denom.monoms())
+        numer_odd = all(i % 2 == 1 for (i,) in numer.monoms())
+        denom_odd = all(i % 2 == 1 for (i,) in denom.monoms())
+        return (numer_even and denom_even) or (numer_odd and denom_odd)
+
+    def match_rational(f, i):
+        numer, denom = f.as_numer_denom()
+        try:
+            (numer, denom), opt = parallel_poly_from_expr((numer, denom), i)
+        except (PolificationFailed, PolynomialError):
+            return None
+        return numer, denom
+
+    def get_poles(denom):
+        roots = denom.sqf_part().all_roots()
+        roots = sift(roots, lambda x: x.is_integer)
+        if None in roots:
+            return None
+        int_roots, nonint_roots = roots[True], roots[False]
+        return int_roots, nonint_roots
+
+    def get_shift(denom):
+        n = denom.degree(i)
+        a = denom.coeff_monomial(i**n)
+        b = denom.coeff_monomial(i**(n-1))
+        shift = - b / a / n
+        return shift
+
+    #Need a dummy symbol with no assumptions set for get_residue_factor
+    z = Dummy('z')
+
+    def get_residue_factor(numer, denom, alternating):
+        residue_factor = (numer.as_expr() / denom.as_expr()).subs(i, z)
+        if not alternating:
+            residue_factor *= cot(S.Pi * z)
+        else:
+            residue_factor *= csc(S.Pi * z)
+        return residue_factor
+
+    # We don't know how to deal with symbolic constants in summand
+    if f.free_symbols - {i}:
+        return None
+
+    if not (a.is_Integer or a in (S.Infinity, S.NegativeInfinity)):
+        return None
+    if not (b.is_Integer or b in (S.Infinity, S.NegativeInfinity)):
+        return None
+
+    # Quick exit heuristic for the sums which doesn't have infinite range
+    if a != S.NegativeInfinity and b != S.Infinity:
+        return None
+
+    match = match_rational(f, i)
+    if match:
+        alternating = False
+        numer, denom = match
+    else:
+        match = match_rational(f / S.NegativeOne**i, i)
+        if match:
+            alternating = True
+            numer, denom = match
+        else:
+            return None
+
+    if denom.degree(i) - numer.degree(i) < 2:
+        return None
+
+    if (a, b) == (S.NegativeInfinity, S.Infinity):
+        poles = get_poles(denom)
+        if poles is None:
+            return None
+        int_roots, nonint_roots = poles
+
+        if int_roots:
+            return None
+
+        residue_factor = get_residue_factor(numer, denom, alternating)
+        residues = [residue(residue_factor, z, root) for root in nonint_roots]
+        return -S.Pi * sum(residues)
+
+    if not (a.is_finite and b is S.Infinity):
+        return None
+
+    if not is_even_function(numer, denom):
+        # Try shifting summation and check if the summand can be made
+        # and even function from the origin.
+        # Sum(f(n), (n, a, b)) => Sum(f(n + s), (n, a - s, b - s))
+        shift = get_shift(denom)
+
+        if not shift.is_Integer:
+            return None
+        if shift == 0:
+            return None
+
+        numer = numer.shift(shift)
+        denom = denom.shift(shift)
+
+        if not is_even_function(numer, denom):
+            return None
+
+        if alternating:
+            f = S.NegativeOne**i * (S.NegativeOne**shift * numer.as_expr() / denom.as_expr())
+        else:
+            f = numer.as_expr() / denom.as_expr()
+        return eval_sum_residue(f, (i, a-shift, b-shift))
+
+    poles = get_poles(denom)
+    if poles is None:
+        return None
+    int_roots, nonint_roots = poles
+
+    if int_roots:
+        int_roots = [int(root) for root in int_roots]
+        int_roots_max = max(int_roots)
+        int_roots_min = min(int_roots)
+        # Integer valued poles must be next to each other
+        # and also symmetric from origin (Because the function is even)
+        if not len(int_roots) == int_roots_max - int_roots_min + 1:
+            return None
+
+        # Check whether the summation indices contain poles
+        if a <= max(int_roots):
+            return None
+
+    residue_factor = get_residue_factor(numer, denom, alternating)
+    residues = [residue(residue_factor, z, root) for root in int_roots + nonint_roots]
+    full_sum = -S.Pi * sum(residues)
+
+    if not int_roots:
+        # Compute Sum(f, (i, 0, oo)) by adding a extraneous evaluation
+        # at the origin.
+        half_sum = (full_sum + f.xreplace({i: 0})) / 2
+
+        # Add and subtract extraneous evaluations
+        extraneous_neg = [f.xreplace({i: i0}) for i0 in range(int(a), 0)]
+        extraneous_pos = [f.xreplace({i: i0}) for i0 in range(0, int(a))]
+        result = half_sum + sum(extraneous_neg) - sum(extraneous_pos)
+
+        return result
+
+    # Compute Sum(f, (i, min(poles) + 1, oo))
+    half_sum = full_sum / 2
+
+    # Subtract extraneous evaluations
+    extraneous = [f.xreplace({i: i0}) for i0 in range(max(int_roots) + 1, int(a))]
+    result = half_sum - sum(extraneous)
+
+    return result
+
+
+def _eval_matrix_sum(expression):
+    f = expression.function
+    for limit in expression.limits:
+        i, a, b = limit
+        dif = b - a
+        if dif.is_Integer:
+            if (dif < 0) == True:
+                a, b = b + 1, a - 1
+                f = -f
+
+            newf = eval_sum_direct(f, (i, a, b))
+            if newf is not None:
+                return newf.doit()
+
+
+def _dummy_with_inherited_properties_concrete(limits):
+    """
+    Return a Dummy symbol that inherits as many assumptions as possible
+    from the provided symbol and limits.
+
+    If the symbol already has all True assumption shared by the limits
+    then return None.
+    """
+    x, a, b = limits
+    l = [a, b]
+
+    assumptions_to_consider = ['extended_nonnegative', 'nonnegative',
+                               'extended_nonpositive', 'nonpositive',
+                               'extended_positive', 'positive',
+                               'extended_negative', 'negative',
+                               'integer', 'rational', 'finite',
+                               'zero', 'real', 'extended_real']
+
+    assumptions_to_keep = {}
+    assumptions_to_add = {}
+    for assum in assumptions_to_consider:
+        assum_true = x._assumptions.get(assum, None)
+        if assum_true:
+            assumptions_to_keep[assum] = True
+        elif all(getattr(i, 'is_' + assum) for i in l):
+            assumptions_to_add[assum] = True
+    if assumptions_to_add:
+        assumptions_to_keep.update(assumptions_to_add)
+        return Dummy('d', **assumptions_to_keep)